# Release Notes
Source: https://docs.flowx.ai/release-notes/overview

What shipped in every FlowX.AI release - new features, bug fixes, deployment guidelines, and migration steps for the 5.9.x and 5.1.x LTS lines and monthly feature releases.

Release notes · FlowX.AI

What shipped.
Every release, every line.

What shipped in every FlowX.AI release: new features, bug fixes, deployment guidelines, and migration steps. Pick your line below, or jump straight to the latest LTS patch and feature release.

[Latest LTS: 5.9.6](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[Feature release: 6.0.0](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

> [!NOTE]
>
> **Long Term Support (LTS) Versions:** LTS versions receive extended support with security updates and critical bug fixes. **5.9.x** is the current FlowX.AI LTS line, recommended for production environments requiring stability and long-term support. Support for the **5.1.x** line ended with 5.1.14, its final maintenance release. To keep receiving fixes, move to 5.9.x: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview). Release notes for older lines, including 5.1.x and 4.7.x, remain published for reference.
>
> **Feature Releases:** Versions released between LTS lines (such as 5.10.0) introduce new capabilities and are deployed to FlowX.AI SaaS environments as they ship. Self-hosted deployments receive these features consolidated into the next LTS release.

01 · Latest

## Latest releases

[LTS
v5.9.6
Maintenance release for the 5.9.x LTS line. Released on October 20th, 2026.](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)

[FEATURE
v6.0.0
Feature release, live on FlowX.AI SaaS. Released on October 30th, 2026.](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[LTS
v5.1.14
Final maintenance release for the 5.1.x LTS line. Released on October 30th, 2026.](./v5.x/v5.1.x-lts/v5.1.14-october-2026)

> [!TIP]
>
> **New cookbook:** [reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation), from email intake to exception review. More end-to-end builds are in the [cookbooks](/5.9/cookbooks/overview).

***

02 · All releases

## All releases

Planning a 5.9.x upgrade? The [5.9.x LTS changelog](./v5.x/5.9-lts-changelog) lists every change in each 5.9.x maintenance release on one page, with an RSS feed.

Moving from 5.9.x to 6.0.0? The [5.9.x to 6.0.0 changelog](./v6.x/5.9-to-6.0-changelog) lists every change from the 5.10 to 5.13 feature releases and 6.0.0 on one page, with an RSS feed.

versionlinereleased

[v6.0.0FRfeature releaseOctober 30th, 2026→](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[v5.1.14LTSmaintenance · 5.1.x LTS lineOctober 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.14-october-2026)
[v5.9.6LTSmaintenance · 5.9.x LTS lineOctober 20th, 2026→](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[v5.13.0FRfeature releaseSeptember 28th, 2026→](./v5.x/v5.13.0-september-2026/v5.13.0-september-2026)
[v5.9.5LTSmaintenance · 5.9.x LTS lineSeptember 23rd, 2026→](./v5.x/v5.9.5-september-2026/v5.9.5-september-2026)
[v5.1.13LTSmaintenance · 5.1.x LTS lineSeptember 18th, 2026→](./v5.x/v5.1.x-lts/v5.1.13-september-2026)
[v5.12.0FRfeature releaseSeptember 3rd, 2026→](./v5.x/v5.12.0-september-2026/v5.12.0-september-2026)
[v5.9.4LTSmaintenance · 5.9.x LTS lineAugust 27th, 2026→](./v5.x/v5.9.4-august-2026/v5.9.4-august-2026)
[v5.1.12LTSmaintenance · 5.1.x LTS lineAugust 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.12-august-2026)
[v5.11.0FRfeature releaseAugust 11th, 2026→](./v5.x/v5.11.0-august-2026/v5.11.0-august-2026)
[v5.9.3LTSmaintenance · 5.9.x LTS lineJuly 30th, 2026→](./v5.x/v5.9.3-july-2026/v5.9.3-july-2026)
[v5.1.11LTSmaintenance · 5.1.x LTS lineJuly 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.11-july-2026)
[v5.9.2LTSmaintenance · 5.9.x LTS lineJuly 10th, 2026→](./v5.x/v5.9.2-july-2026/v5.9.2-july-2026)
[v5.10.0FRfeature releaseJuly 7th, 2026→](./v5.x/v5.10.0-july-2026/v5.10.0-july-2026)
[v5.1.10LTSmaintenance · 5.1.x LTS lineJune 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.10-june-2026)
[v5.9.1LTSmaintenance · 5.9.x LTS lineJune 15th, 2026→](./v5.x/v5.9.1-june-2026/v5.9.1-june-2026)
[v5.9.0LTSfirst release of the 5.9.x LTS lineJune 2nd, 2026→](./v5.x/v5.9.0-june-2026/v5.9.0-june-2026)
[v5.1.9LTSLTS maintenance releaseMay 29th, 2026→](./v5.x/v5.1.x-lts/v5.1.9-may-2026)
[v5.8.0FRfeature releaseMay 10th, 2026→](./v5.x/v5.8.0-may-2026/v5.8.0-may-2026)
[v5.1.8LTSLTS maintenance releaseApril 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.8-april-2026)
[v5.7.0FRfeature releaseApril 28th, 2026→](./v5.x/v5.7.0-april-2026/v5.7.0-april-2026)
[v5.6.0FRfeature releaseMarch 25th, 2026→](./v5.x/v5.6.0-march-2026/v5.6.0-march-2026)
[v5.1.7LTSLTS maintenance releaseMarch 26th, 2026→](./v5.x/v5.1.x-lts/v5.1.7-march-2026)
[v5.1.6LTSLTS maintenance releaseMarch 16th, 2026→](./v5.x/v5.1.x-lts/v5.1.6-march-2026)
[v5.5.0FRfeature releaseFebruary 27th, 2026→](./v5.x/v5.5.0-february-2026/v5.5.0-february-2026)
[v5.1.5LTSLTS maintenance releaseFebruary 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.5-february-2026)
[v5.1.4LTSLTS maintenance releaseFebruary 9th, 2026→](./v5.x/v5.1.x-lts/v5.1.4-february-2026)
[v5.4.0FRfeature releaseJanuary 30th, 2026→](./v5.x/v5.4.0-january-2026/v5.4.0-january-2026)
[v5.1.3LTSLTS maintenance releaseJanuary 15th, 2026→](./v5.x/v5.1.x-lts/v5.1.3-january-2026)
[v5.3.0FRfeature releaseDecember 24th, 2025→](./v5.x/v5.3.0-december-2025/v5.3.0-december-2025)
[v5.1.2LTSLTS maintenance releaseDecember 3rd, 2025→](./v5.x/v5.1.x-lts/v5.1.2-december-2025)
[v5.2.0FRfeature releaseNovember 10th, 2025→](./v5.x/v5.2.0-november-2025/v5.2.0-november-2025)
[v5.1.1LTSLTS maintenance releaseNovember 10th, 2025→](./v5.x/v5.1.x-lts/v5.1.1-november-2025)
[v4.7.11LTSLTS maintenance releaseDecember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025)
[v4.7.10LTSLTS maintenance releaseNovember 17th, 2025→](./v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025)
[v4.7.9LTSLTS maintenance releaseOctober 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025)
[v5.1.0LTSLTS maintenance releaseOctober 2nd, 2025→](./v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025)
[v4.7.8LTSLTS maintenance releaseSeptember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025)
[v4.7.7LTSLTS maintenance releaseAugust 20th, 2025→](./v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025)
[v5.0.0FRfeature releaseJuly 31st, 2025→](./v5.x/v5.0.0-july-2025/v5.0.0-july-2025)
[v4.7.6LTSLTS maintenance releaseJuly 18th, 2025→](./v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025)
[v4.7.5LTSLTS maintenance releaseJune 19th, 2025→](./v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025)
[v4.7.4LTSLTS maintenance releaseMay 15th, 2025→](./v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025)
[v4.7.3LTSLTS maintenance releaseApril 14th, 2025→](./v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025)
[v4.7.2LTSLTS maintenance releaseMarch 26th, 2025→](./v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025)
[v4.7.1LTSLTS maintenance releaseMarch 7th, 2025→](./v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025)
[v4.7.0LTSLTS maintenance releaseFebruary 24th, 2025→](./v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025)
[v4.6.1FRfeature releaseFebruary 7th, 2025→](./v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025)
[v4.6.0FRfeature releaseJanuary 23rd, 2025→](./v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025)
[v4.1.5LTSLTS maintenance releaseSeptember 23rd, 2024→](./v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024)
[v4.1.4LTSLTS maintenance releaseSeptember 6th, 2024→](./v4.x/v4.1.x/v4.1.4-september-2024/v4.1.4-september-2024)
[v4.1.3LTSLTS maintenance releaseAugust 12th, 2024→](./v4.x/v4.1.x/v4.1.3-august-2024/v4.1.3-august-2024)
[v4.1.2LTSLTS maintenance releaseJune 8th, 2024→](./v4.x/v4.1.x/v4.1.2-june-2024/v4.1.2-june-2024)
[v4.1.1LTSLTS maintenance releaseJune 17th, 2024→](./v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024)
[v4.1.0LTSLTS maintenance releaseMay 30th, 2024→](./v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024)
[v4.0.0FRfeature releaseApril 18th, 2024→](./v4.x/v4.0.0-april-2024/v4.0.0-april-2024)

> [!NOTE]
>
> Releases from the **4.5.x (tech preview)** and **4.2.x** lines are not listed above. You can find them in the sidebar under **Release Notes** → **v4.x**.

***

> [accordion] Version 3.x.x
>
> > [card] [v3.4.8 - June 2024](/release-notes/v3.x.x/v3.4.8-june-2024/v3.4.8-june-2024)
> >
> > Explore the latest enhancements and fixes introduced in June 2024.
>
> > [card] [v3.4.7 - January 2024](/release-notes/v3.x.x/v3.4.7-january-2024/v3.4.7-january-2024)
> >
> > Explore the latest enhancements and fixes introduced in January 2024.
>
> > [card] [v3.4.6 - December 2023](/release-notes/v3.x.x/v3.4.6-december-2023/v3.4.6-december-2023)
> >
> > Explore the latest enhancements and fixes introduced in December 2023.
>
> > [card] [v3.4.5 - November 2023](/release-notes/v3.x.x/v3.4.5-november-2023/v3.4.5-november-2023)
> >
> > Explore the latest enhancements and fixes introduced in November 2023.
>
> > [card] [v3.4.4 - November 2023](/release-notes/v3.x.x/v3.4.4-november-2023/v3.4.4-november-2023)
> >
> > Discover the significant changes and improvements made in November 2023.
>
> > [card] [v3.4.3 - October 2023](/release-notes/v3.x.x/v3.4.3-october-2023/v3.4.3-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.2 - October 2023](/release-notes/v3.x.x/v3.4.2-october-2023/v3.4.2-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.1 - September 2023](/release-notes/v3.x.x/v3.4.1-september-2023/v3.4.1-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.4.0 - September 2023](/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.3.0 - July 2023](/release-notes/v3.x.x/v3.3.0-july-2023/v3.3.0-july-2023)
> >
> > Discover the significant changes and improvements made in July 2023.
>
> > [card] [v3.2.0 - April 2023](/release-notes/v3.x.x/v3.2.0-april-2023/v3.2.0-april-2023)
> >
> > Discover the significant changes and improvements made in April 2023.
>
> > [card] [v3.1.0 - March 2023](/release-notes/v3.x.x/v3.1.0-march-2023/v3.1.0-march-2023)
> >
> > Discover the significant changes and improvements made in March 2023.
>
> > [card] [v3.0.0 - February 2023](/release-notes/v3.x.x/v3.0.0-february-2023/v3.0.0-february-2023)
> >
> > Discover the significant changes and improvements made in February 2023.


# FlowX.AI 5.9.x LTS changelog
Source: https://docs.flowx.ai/release-notes/v5.x/5.9-lts-changelog

Every change in each FlowX.AI 5.9.x LTS maintenance release, grouped by type and component, with an RSS feed for upgrade planning.

This page lists every change in each 5.9.x LTS maintenance release, newest first. Use the RSS button at the top of the page to subscribe and get each new patch as it ships. Mobile renderers and the React Native SDK are covered in their own release notes. Moving to 6.0.0? See the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog).

**5.9.6**

October 2026

**Upgrade actions:** migrate to the `flowx-ai` Helm chart if you installed the `ai-platform` chart, create the `ai.flowx.build.deployment-failed.v1` Kafka topic and allow it in your ACLs, re-publish any build whose deployment failed shortly before the upgrade, review workflow node retry settings, grant the connection-test permissions to custom roles, and allow extra Integration Designer startup time on a large `workflow_instances` collection. Details are in the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).

#### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

#### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect.
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#mongodb-setting-names).
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6) for its version.

#### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.6 release notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026) · [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6)

**5.9.5**

September 2026

**Upgrade actions:** let the `ai-services` consumer group reach zero lag and allow the new AI consumer groups in Kafka ACLs, add private database hosts to the NoSQL DB runner allowlist, set every service-account client secret on `authorization-system`, rename `cache_error_total` in dashboards and alerts, re-expose `loggers` if you change log levels at runtime, and review the deployment guidelines if you had already turned on data partitioning, because the conversion to native partitions is one way. Details are in the [5.9.5 upgrade notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#upgrade-notes).

#### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#native-postgresql-partitioning).

#### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.

#### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.5 release notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026) · [5.9.5 deployment guidelines](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5)

**5.9.4**

August 2026

**Upgrade actions:** move the registry out of `image.repository` if you embedded it there (no action if you set `global.imageRegistry`), grant the Liquibase lock permissions to each service's database user on Oracle, create the `flowx-events-gateway-sa` client yourself if you manage Keycloak clients outside the Helm charts, and move host apps that embed the Angular SDK to Angular 21. Details are in the [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4#configuration-changes).

#### Changed

* **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.
* **Angular SDK:** the Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps that embed the Angular SDK must be on Angular 21. The npm and node requirements are unchanged.
* **Cross-version import:** importing a project build or version exported from an older platform line completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten.
* **Database migrations:** the lock that guards Liquibase schema migrations at service startup is a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration releases its lock when the database closes the session. Service accounts no longer need the `pods/status` permission. Oracle deployments need new database grants.
* **Events Gateway:** authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`. Helm chart deployments where `authorization-system` runs its migrations with Keycloak admin access need no action.
* **Helm charts:** the container image reference is split into `image.registry` and `image.repository`. The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. The default image location is unchanged.
* **Integration Designer:** service startup no longer scans the full token-instance collection, and the run-list summary queries are indexed.
* **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.
* **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.

#### Fixed

* **Actions:** deleting an action whose business rule calls a function works instead of returning a server error.
* **Build export:** retrying a build export re-attempts a dependency library whose own export timed out, so the parent build can finish.
* **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output from trailing empty cells and rows.
* **Entry points:** the entry-point picker in version settings lists only processes and UI flows from the current project.
* **Gateways:** an expression that fails to evaluate on an exclusive gateway surfaces as an incident on the process instance instead of only in the service logs.
* **Generated documents:** a document whose storage write fails returns an error instead of being recorded as successful. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.
* **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is listed once instead of once per consuming project version.
* **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives during a background synchronization, and merging versions no longer fails with a navigation-areas error.
* **Renderers:** the document preview shows its subtitle, and the file-upload error message follows the configured theme.
* **Reusable UI templates:** static input mappings configured on a reusable template are applied at runtime.
* **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.
* **Task management:** the row-selection checkbox column no longer carries an invisible sort control that re-sorted the view and cleared the selection, and changing the page size no longer opens the wrong process from the list.
* **Themes and CMS resources:** exporting a theme no longer includes duplicate copies of system icons, and importing no longer leaves system substitution tags missing.
* **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.4 release notes](/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026) · [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4)

**5.9.3**

July 2026

**Upgrade actions:** none. The new Events Gateway and Integration Designer settings ship with working defaults. Details are in the [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3#configuration-changes).

#### Changed

* **Events Gateway:** new settings tune the dedicated Redis connection pool for blocking reads, and the default blocking-read duration is lowered from 5 seconds to 1 second. If you set the blocking-read duration explicitly, review it against the new default.
* **Integration Designer:** a new setting sets the number of partitions for auto-created workflow Kafka topics. Existing topics are not modified.
* **Media Library:** PDF assets in the list can be opened in a new tab.
* **Process start:** web renderers keep the loading indicator visible until the first user task renders.

#### Fixed

* **Build import:** a transient database write conflict during a multi-dependency import no longer drops a dependency's build, which caused runtime errors on substitution tags and enumerations. Large imports may take slightly longer.
* **Date Picker:** the calendar anchors to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.
* **Designer:** opening Runtime after expanding a component's Permissions section no longer freezes the Designer, and a pending AI UI-generation draft no longer locks the process diagram read-only.
* **Projects:** creating a project with the same name as a deleted project returns a validation error instead of an internal server error.
* **Real-time event delivery:** the Events Gateway no longer leaks Redis connections. Blocking reads run on a dedicated connection pool with Redis Cluster support, so the gateway no longer needs periodic restarts under sustained load.
* **Task management:** deleting a swimlane allocation rule removes only that rule, clicking Save twice no longer creates duplicate rules, and task views no longer reset when the same view is open from different workspaces.
* **Workflows:** a workflow no longer freezes silently after a step exhausts its retries.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.3 release notes](/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026) · [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3)

**5.9.2**

July 2026

**Upgrade actions:** update any Keycloak group mapper or external IdP claim that emits the end-user group `User` to `Users Group`, remove records of the organization-ID migration or other Liquibase changesets you marked as executed by hand on an earlier 5.9.x (contact FlowX support for the list first), upgrade the AI Platform chart and the core services together, and update dashboards, alerts, and log queries that match the `ai-platform-` service name prefix. Details are in the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#upgrade-overview).

#### New

* **AI agents and data models:** AI Designer and AI Developer use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it.
* **AI workflow nodes:** JSON schema fields support `${}` placeholders.
* **Chat file uploads:** end users can attach multiple files in a chat-driven app. Uploads are indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content.
* **Document Parser:** a new LiteParse engine parses PDFs and images locally without GPU or AI calls, and OCR supports English, Romanian, Hungarian, and Bulgarian.
* **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.
* **Knowledge bases:** a Custom Agent node can select multiple knowledge bases, each exposed to the agent as its own retrieval tool, and retrieval can span multiple knowledge bases in a workflow.
* **SQL data sources:** queries on SQL data sources can be tested from the builds list.
* **Use in reporting:** the reporting toggle is available on UI flows and workflows.

#### Changed

* **AI node structured output:** responses from AI nodes with a response schema are validated against it, with automatic repair retries, and node logs include the failure reason and rejected output.
* **AI Platform services:** services are deployed under their plain names, without the `ai-platform-` prefix on pod, service, and image names, and the bundled Qdrant subchart is renamed the same way. Core services resolve AI components by the new names.
* **Audit log:** records sharing, user invitations, designer-user, end-user, and group management, actions on process instances and UI flows, adding a dependency, and terminating process, workflow, or UI flow instances.
* **Copy to project:** copying a process or UI flow to another project also copies its roles.
* **Data archiving:** archiving detaches a partition only when every process or workflow instance in it has finished. New settings for terminating stuck instances and backfilling legacy rows are off by default.
* **Default end-user group:** the group that the 5.1.x upgrade migration creates is renamed from `User` to `Users Group`. Groups your admins created are not renamed.
* **Designer:** the Event Handlers section appears higher in the component configuration panel, and the keys to save for collection items and bundled custom-component inputs are computed automatically.
* **Kafka reconnects:** platform services use a gentler broker-reconnect backoff by default, and repeated Kafka connection errors log at a quieter level.

#### Fixed

* **Active policy:** the user list on the override active-policy form is no longer empty.
* **Application manager:** the runtime-application organization-ID migration converts existing data correctly.
* **Audit logs:** filtering audit entries by user works when the username differs from the email address.
* **Build export with media files:** exporting a build with media file content produces an archive that contains the binaries.
* **Chat:** the floating chat position is calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.
* **CMS enumerations:** cascading-enum value lookups resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.
* **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.
* **Data sync with private CA certificates:** data-sync migrations that call HTTPS endpoints, such as Keycloak, no longer fail certificate validation in environments that use an internal certificate authority.
* **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.
* **Project version merge:** a merge no longer fails with a 500 error.
* **Redis Cluster:** UI template cache keys map to the same cluster slot, which prevents cross-slot errors.
* **Reusable UI templates:** actions are no longer missing at runtime when a template is nested in multiple levels of containers.
* **Self-hosted installation and upgrade:** Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding work on self-hosted environments.
* **Workflow data:** archiving batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine is fixed.
* Stability fixes across the Designer, the renderers, and the backend services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.2 release notes](/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026) · [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2)

**5.9.1**

June 2026

**Upgrade actions:** none for deployments where the Helm chart provisions Kafka topics. If you provision Kafka topics or ACLs manually, create the topics added in 5.9.1. Details are in the [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics).

#### New

* **AI permissions:** AI runtime usage and AI build-time tooling (AI Designer, agent building, code generation) are governed by two separate permissions. When AI is turned off, AI icons and entry points are hidden instead of shown disabled, and build-time helpers such as code generation and "Add comment" follow the dev-agent permission.
* **File Preview:** scroll-trigger event handlers, including a "document end" trigger, let a flow detect when a user scrolls through a document or reaches its end, for example to enable an **Accept** button only after the user reaches the end of an agreement.
* **File upload:** the upload button supports a configurable icon, set in the Designer.
* **Microsoft Outlook:** connections support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
* **Script engine:** business rules, reusable functions, and node rules can each run on the native engine (the 5.9 default) or the legacy GraalVM engine. Rules created before the switch to native keep running on GraalVM until you migrate them, and new rules default to native.

#### Changed

* **AI Designer:** generates UI from a flat template format instead of 3-level nesting, supports more component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates incrementally instead of regenerating them, and can generate reusable UI templates.
* **Kafka topics:** new topics carry runtime config-param change events, runtime instance terminations, resource cache evictions, and evaluation improvement suggestions. The Helm chart provisions them.
* **Merge conflicts:** merge-conflict handling for custom components and UI Flows identifies resources more clearly.
* **Organization settings:** navigation and design improvements.
* **Platform Status:** reports AI Platform components and their databases alongside the core services.
* **Runtime config params:** changes reach the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
* **Workflows:** storage of running steps is optimized, workflows and processes launched from a UI Flow inherit the build of the parent UI Flow, and AI node failures show the error details and model reasoning in the workflow run logs.

#### Fixed

* **Actions:** GET actions no longer fire with undefined parameters.
* **AI chat:** agent responses no longer reappear in chat after stop and refresh, and the builder-agent chat no longer duplicates messages.
* **Copy to project:** copying a process or workflow to another project succeeds, and copied workflows appear in the target project.
* **End-user login:** a null value is no longer cached when looking up the "All end-users" group, which could block logins until data sync completed.
* **File Preview:** previews render correctly, events fire inside collections, a fixed height applies at runtime, and preview resources no longer fail with CORS errors.
* **File Storage:** FTP test connection and file operations resolve configuration-parameter placeholders, and FTP file preview works when the root path has no leading slash.
* **Forms to validate:** scrolling covers the full component hierarchy, placeholders update, and chat and tab-bar components are selected correctly.
* **Hide and disable conditions:** conditions on UI templates, processes, and UI Flows apply at runtime for Designer users without workspace access.
* **Invitations:** an invited Designer user added as an Organization owner is assigned to a workspace.
* **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
* **Modals:** dropdowns no longer flicker, and long key names no longer break the layout.
* **Process instances:** loading an instance with a very large execution graph no longer crashes the browser.
* **Task management:** headers follow the theme in React and Angular, and the filter window no longer disappears after applying criteria.
* **Theme admin:** "copy to" no longer loses theme content.
* **Timer events:** activating a start timer event after a new build regenerated the process resource ID no longer fails with a 500 (duplicate key) error.
* **UI Flow:** images display in preview after refresh, and returning from an expired UI Flow no longer loses the theme UUID.
* **Usage Overview:** opening a usage overview no longer fails with a 500 error.
* **Web renderer:** the button shadow and modal content padding are restored, and components render when a media-file storage path is null.
* **Workflows:** END PARALLEL output no longer includes data from before the parallel branches started, and NoSQL node run logs no longer crash when a node fails before building its options.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.1 release notes](/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026) · [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1)


# Deployment guidelines v5.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10

Component versions and deployment notes for FlowX.AI 5.10 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.10 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.10.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.10.0 |
| - | - |
| **admin** | 11.18.0 |
| **advancing-controller** | 11.12.0 |
| **application-manager** | 11.18.0 |
| **audit-core** | 11.11.0 |
| **authorization-system** | 11.14.0 |
| **cms-core** | 11.14.0 |
| **data-search** | 11.11.0 |
| **data-sync** | 11.9.0 |
| **designer** | 11.36.1 |
| **document-plugin** | 11.19.0 |
| **email-gateway** | 11.15.0 |
| **events-gateway** | 11.14.0 |
| **file-gateway** | 11.14.0 |
| **integration-designer** | 11.24.2 |
| **license** | 11.13.0 |
| **nosql-db-runner** | 11.14.0 |
| **notification-plugin** | 11.14.0 |
| **organization-manager** | 11.14.0 |
| **process-engine** | 11.19.3 |
| **runtime-manager** | 11.18.0 |
| **scheduler-core** | 11.11.0 |
| **task-management-plugin** | 11.15.0 |
| **webhook-gateway** | 11.13.0 |

### AI base components

| Component | 5.10.0 |
| - | - |
| **embedder** | 11.2.0 |
| **knowledgebase-indexer-v2** | 11.2.0 |
| **knowledgebase-rag** | 11.2.0 |
| **doc-parser** | 11.2.0 |

### AI dev-time components

| Component | 5.10.0 |
| - | - |
| **ai-gateway** | 11.15.1 |
| **ai-analyst** | 11.2.0 |
| **ai-assistant** | 11.2.0 |
| **ai-designer** | 11.2.0 |
| **ai-developer** | 11.2.0 |
| **kb-enrichment** | 11.2.0 |
| **planner** | 11.2.0 |

### AI runtime components

| Component | 5.10.0 |
| - | - |
| **agent-builder** | 11.2.0 |
| **data-privacy** | 11.2.0 |
| **doc-converter** | 11.2.0 |
| **dynamic-classifier** | 11.2.0 |
| **evals-judge** | 11.2.0 |
| **speech-to-text** | 11.2.0 |
| **web-crawler** | 11.2.0 |

### AI extensions

| Component | 5.10.0 |
| - | - |
| **modpod** | 11.2.0 |
| **observatory-api** | 11.0.2 |
| **observatory-platform** | 11.0.2 |
| **observatory-web** | 11.0.2 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments receive them, re-verified, with the next LTS release.

### New Kafka topics

| Topic | Producer → Consumer | Purpose |
| - | - | - |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin → process-engine | Resource cache eviction |
| `ai.flowx.config.params.events.v1` | application-manager → process-engine | Config-param change notifications |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine → integration-designer | Runtime-instance termination |
| `ai.flowx.evals.suggestions.job.request.v1` / `.response.v1` | integration-designer | Evals suggestions job requests and responses |

### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them when your environment moves to 5.10.

This release also adds a new AI Platform component, **dynamic-classifier** (listed under AI runtime components above), which backs document classification.

In `admin`, the single `FLOWX_FEATUREAVAILABILITY_AISERVICENAME` setting is replaced by two, reflecting the split between AI dev-time and AI runtime services: `FLOWX_FEATUREAVAILABILITY_AIDEVTIMESERVICENAME` (default `ai-gateway-mngt`) and `FLOWX_FEATUREAVAILABILITY_AIRUNTIMESERVICENAME` (default `agent-builder-mngt`).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.10.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026

What's new in FlowX.AI 5.10: PostgreSQL and SOAP data sources, AI Developer script-node code generation, file uploads in chat-driven apps, and AI and document-intelligence improvements.

[FlowX.AI 5.10 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.10.0.html)

> [!NOTE]
>
> **FlowX.AI 5.10 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments receive them with the next LTS release.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release adds PostgreSQL and SOAP data sources, multi-file upload in chat-driven apps, and a set of AI and document-intelligence capabilities, alongside broader audit coverage, roles that travel with copied resources, and workflow data-partitioning improvements.

***

**What's new?**

> [tab] Core & Platform
>
> 🗂️ [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions\
> 📑 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources\
> ⚡ [**Platform performance and fixes**](#platform-performance-and-fixes) - Task-manager user fetch, project versioning, export/merge

> [tab] Designer & Renderer
>
> 💬 [**Chat file upload**](#chat-file-upload) - Attach multiple files in conversational apps\
> ⬇️ [**File download component**](#file-download-component) - Download files from a rendered app (web and Android)\
> 🔀 [**Conditional event-handler triggers**](#conditional-event-handler-triggers) - Fire event handlers based on a condition\
> 🎨 [**Image color property**](#image-color-property) - Color control on the IMAGE component\
> 💾 [**Save local variable**](#save-local-variable-action) - Capture a collection row into local data on click\
> 🪟 [**Global header and footer**](#global-header-and-footer) - Consistent header and footer across a UI Flow\
> 🧩 [**Reusable UI templates**](#reusable-ui-templates) - Action mapping, undo/redo, and dependency-version fixes

> [tab] Integrations & Data
>
> 🐘 [**PostgreSQL data source**](#postgresql-data-source) - Connect workflows directly to PostgreSQL and run SQL queries\
> 🧼 [**SOAP integration**](#soap-integration) - Import a WSDL and call SOAP operations from workflows\
> 🧮 [**FlowX Database aggregation**](#flowx-database-aggregation) - MongoDB aggregation pipelines\
> 🗄️ [**Documents tab in database testing**](#documents-tab-in-database-testing) - Inspect data while testing DB operations

> [tab] AI & Documents
>
> 📊 [**Tabular data extraction node**](#tabular-data-extraction-node) - Read spreadsheets and CSV into workflow data\
> 🔁 [**Knowledge Base error handling**](#knowledge-base-error-handling-and-retry) - Retry failed KB ingestion\
> ✨ [**AI Developer: script-node code**](#ai-developer-generate-script-node-code) - Generate node code from a prompt\
> 🧪 [**AI evaluation experiments**](#ai-evaluation-experiments) - Multiple datasets and improvement suggestions\
> 🛡️ [**AI node output reliability**](#ai-node-output-reliability) - Schema validation with auto-repair and clearer run errors\
> 📝 [**Template Filling node**](#template-filling-node) - Generate documents from templates in workflows\
> 🗂️ [**File manipulation nodes**](#file-manipulation-nodes) - Combine and split files in workflows\
> 📄 [**DOCX document generation**](#docx-document-generation) - Generate documents as DOCX in addition to PDF\
> 🏷️ [**Document Tag**](#document-tag-renamed-from-document-type) - "Document Type" renamed\
> 🔑 [**Mistral model provider**](#mistral-model-provider) - Bring your own Mistral API key

### **Expanded audit logging**

> [card] Broader audit coverage for access and lifecycle actions
>
> Audit logging now records a wider set of actions: **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> All Deployments

### **Copy with roles**

> [card] Roles travel with copied resources
>
> Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> All Deployments

### **Platform performance and fixes**

> [card] Platform performance and fixes
>
> > [tab] Performance
> >
> > The task manager fetches users through the authorization-system instead of calling Keycloak directly, cutting per-request identity lookups.&#x20;
> >
> > MongoDB partition archiving scales for large datasets, with partition-ID backfill for legacy data and archiving fixes on PostgreSQL and Oracle.&#x20;
>
> > [tab] Bug fixes
> >
> > > [accordion] Core platform fixes
> > >
> > > * **Project selector:** projects without a work-in-progress branch are correctly shown as unavailable.&#x20;
> > > * **Start Solution:** no longer fails with "no entry point set" until the page is refreshed.&#x20;
> > > * **Export and merge:** fixed errors when exporting a project build with imported libraries and when merging project versions, including a 500 during merge.&#x20;
> > > * **Merge-conflict checks:** no longer fail on processes that contain conflicts.&#x20;
> > > * **Allocation roles:** candidate-user search works for users without runtime permissions on the asset.&#x20;
> > > * **Version switching:** the selected resource opens when changing app versions, and reusable-function code refreshes on version switch.&#x20;
> > > * **Process engine:** resolved an incident-save deadlock.&#x20;
> > > * **FlowX Database:** inserting a document with a reserved `_id` key is now rejected with a clear error instead of breaking later reads.&#x20;
>
> All Deployments

### **PostgreSQL data source**

> [card] Connect to PostgreSQL databases from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds **PostgreSQL** as a data source type, alongside Oracle. Connect a workflow directly to a PostgreSQL database and run SQL queries against it as a workflow node, without a custom REST wrapper. See the [PostgreSQL Database](/5.9/docs/platform-deep-dive/integrations/postgresql-database) documentation.
>
> > [tab] Key Features
> >
> > > [card] Direct connection
> > >
> > > Configure host, port, database, schema, and credentials, with an optional SSL connection and a **Test connection** check before saving.
> >
> > > [card] SQL query operations
> > >
> > > Define SQL query operations on the data source and call them from workflow nodes.
> >
> > > [card] Connection pool tuning
> > >
> > > Advanced settings cover pool size, connection and query timeouts, keep-alive, and a validation query.
> >
> > > [card] Familiar experience
> > >
> > > Shares the same configuration and operations experience as the existing Oracle data source.
>
> SaaS

### **SOAP integration**

> [card] Call SOAP web services from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds a **SOAP System** data source. Import the service's **WSDL** — from a URL or an uploaded file — and FlowX discovers the operations with their input, output, and fault schemas, composes the SOAP envelope at runtime, and lets you call each operation from workflows through a **SOAP Operation** node. See the [SOAP System](/5.9/docs/platform-deep-dive/integrations/soap-system) documentation.
>
> > [tab] Key Features
> >
> > > [card] WSDL import
> > >
> > > Preview and select the operations to import; re-import refreshes schemas while preserving your edits
> >
> > > [card] Typed variables
> > >
> > > Envelope variables extracted from the input XSD, referenced as workflow parameters
> >
> > > [card] SOAP 1.1 and 1.2
> > >
> > > Version derived from the WSDL, with standard headers set automatically
> >
> > > [card] Testing built in
> > >
> > > Test operations with value overrides, a curl preview, and full request/response envelopes in run logs
>
> SaaS

### **Reusable UI templates**

> [card] Reusable UI template fixes
>
> Reusable UI templates get more reliable action mapping, undo/redo, and dependency-version handling.
>
> All Deployments

### **Chat file upload**

> [card] Attach multiple files in conversational apps
>
> End users can attach multiple files at once in chat-driven apps, and conversational workflows can receive those files as input. Uploaded files are extracted and indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content. Configurable in the Designer and themable, with runtime support on the web renderer.
>
> Session knowledge bases are isolated per conversation and per tenant, and are excluded from app export.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **File download component**

> [card] Download files from a rendered app
>
> A new File Download component lets end users download files directly from a rendered app. Configured in the Designer, with runtime support on web and Android.
>
> For more information, see the [File download](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download) documentation.
> SaaS

### **Conditional event-handler triggers**

> [card] Fire event handlers based on a condition
>
> Event handlers can now fire conditionally, configured in the Designer and honored by the web and Android renderers.
>
> For more information, see the [event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers) documentation.
> SaaS

### **Image color property**

> [card] Color control on the IMAGE component
>
> The IMAGE component now honors a color property, configured in the Designer and rendered on web and Android.
>
> See the [Image component](/5.9/docs/building-blocks/ui-designer/ui-component-types/image) documentation.
> SaaS

### **Save local variable action**

> [card] Capture a collection row into local data
>
> Event handlers gain a **Save Local Variable** action type: on a component inside a collection, it saves the clicked row's item into local data under a configurable key, entirely client-side with no backend roundtrip — useful for capturing the selected row before a follow-up action fires. Not available inside Reusable UI Templates.
>
> See the [Save Local Variable](/5.9/docs/building-blocks/ui-designer/event-handlers#save-local-variable) documentation.
> SaaS

### **Global header and footer**

> [card] Consistent header and footer across a UI Flow
>
> UI Flows can now define a **global header and footer** that display consistently across every page of the flow. Each holds content components — containers, forms, buttons, links, custom components — with fixed or static positioning (header fixed by default), so you can build persistent navigation or action bars in one place instead of per page.
>
> See the [Global Header and Footer](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer) documentation.
> SaaS

### **Tabular data extraction node**

> [card] Extract spreadsheet and CSV data into workflows
>
> A new workflow node reads a spreadsheet or CSV file and returns its contents as structured JSON in the node's response key, so the data can drive conditions and data operations downstream. Each row is returned as an object keyed by the file's header row, and for Excel files you can select which sheet to read.
>
> For more information, see the [Tabular Data Extraction node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node) documentation.
> SaaS

### **Knowledge Base error handling and retry**

> [card] Recover from failed Knowledge Base ingestion
>
> When Knowledge Base ingestion fails, the Knowledge Base page now shows a clear failure status and reason, and a **Retry** button re-runs the last operation after cleaning up partial content so the store is not left inconsistent. The **Update Knowledge Base** workflow node gains a **FAIL** exit handle with per-operation rollback.
>
> Learn more about [Knowledge Bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview).
> SaaS

### **AI Developer: generate script-node code**

> [card] Generate script-node code with AI Developer
>
> In the workflow designer, a script node can call **AI Developer** to generate or refactor its code from a natural-language prompt. Output streams into the test area for a **Keep** or **Discard** review, with edits shown as a diff. Supports JavaScript and Python, and respects existing AI Developer permissions.
>
> Learn more about [AI Developer](/5.9/ai-platform/pre-built-agents/ai-developer).
> SaaS

### **FlowX Database aggregation**

> [card] Aggregation pipelines in FlowX Database
>
> The FlowX Database data source adds MongoDB **aggregation pipeline** support, so configurators can group, join, reshape, and compute across documents beyond what a single query allows.
>
> Learn more about the [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) data source.
> SaaS

### **AI evaluation experiments**

> [card] Richer AI evaluation experiments
>
> > [tab] Multiple datasets
> >
> > An evaluation experiment can run against **multiple datasets** at once (datasets sharing the same AI node), with overall metrics aggregated across them and a dataset column added to the report.
>
> > [tab] Improvement suggestions
> >
> > Experiment reports now show **AI-generated suggestions** for improving the node's prompt, grouped per LLM-as-judge evaluator, beneath the score cards.
>
> Learn more about [AI evaluations](/5.9/ai-platform/evaluations).
> SaaS

### **AI node output reliability**

> [card] Schema validation with auto-repair and clearer run errors
>
> > [tab] Validation and repair
> >
> > When an AI node has a **Response Schema**, the response is validated against it and automatically retried with a repair prompt on mismatch. Nodes that still fail return a **categorized error** instead of passing malformed output downstream, and the node's **Logs** show the failure reason, rejected output, the model's reasoning summary, and the retry count.
>
> > [tab] Schema placeholders
> >
> > Response schemas now support `${variable}` placeholders resolved at runtime against workflow data, with substituted values coerced to the schema-declared types — consistent with how other AI-node fields resolve placeholders.
>
> See [AI node types](/5.9/ai-platform/agent-builder/node-types#structured-output-validation-and-run-diagnostics) for details.
> SaaS

### **Template Filling node**

> [card] Generate documents from templates in workflows
>
> Integration workflows gain a **Template Filling** node, under **Tools** in the node palette, that generates a document from a document template populated with workflow data. Select a template and language, fill the template's variables from workflow data, and choose **PDF** or **DOCX** output. The generated file's ID and download path are returned on the node's response key.
>
> See the [Template Filling node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) documentation.
> SaaS

### **File manipulation nodes**

> [card] Combine and split files in workflows
>
> Integration workflows add two document nodes, under **Tools** in the node palette: **Combine Files** merges multiple PDFs into one in a given order, and **Split File** breaks a PDF into multiple files by page ranges or one file per page. Both bring document handling that was previously process-only into workflows.
>
> See the [Combine Files](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) documentation.
> SaaS

### **DOCX document generation**

> [card] Generate documents as DOCX
>
> Template-based document generation can now produce **DOCX** files in addition to PDF. Set `outputFormat` (`PDF` or `DOCX`; defaults to `PDF`) on the generation request, or pick the format from the new **Output format** dropdown when testing a template in the Designer. Generated DOCX files preserve the template's styles, data, and images. Barcodes apply to PDF output only.
>
> Learn more in the [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output) documentation.
> SaaS

### **Document Tag (renamed from Document Type)**

> [card] Document Type is now Document Tag
>
> The **Document Type** field is renamed **Document Tag** across the surfaces where a document is tagged for storage (Upload File action, Document-Plugin REST responses, AI Document Generation, and the Web Page Extractor). This is a label change; behavior is unchanged.
> SaaS

### **Documents tab in database testing**

> [card] Inspect data while testing database operations
>
> The Database Query testing modals gain a **Documents** tab, so you can inspect the database right after running an operation. Multi-record operations report an affected-record count.
> SaaS

### **Mistral model provider**

> [card] Bring your own Mistral API key
>
> **Mistral** joins the model provider catalog as a bring-your-own-key provider. Add it with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability: chat, image understanding, embeddings, and document OCR. The seeded catalog covers the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed model lines.
>
> Learn more about [AI providers](/5.9/ai-platform/ai-providers).
> SaaS

***

## Deployment guidelines

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.10 deployment guidelines](./deployment-guidelines-v5.10).&#x20;


# Deployment guidelines v5.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11

Component versions and deployment notes for FlowX.AI 5.11 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.11 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.11.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.11.0 |
| - | - |
| **admin** | 11.53.0 |
| **advancing-controller** | 11.31.0 |
| **application-manager** | 11.46.0 |
| **audit-core** | 11.30.0 |
| **authorization-system** | 11.38.0 |
| **cms-core** | 11.43.0 |
| **data-search** | 11.30.0 |
| **data-sync** | 11.27.0 |
| **designer** | 11.89.1 |
| **document-plugin** | 11.47.0 |
| **email-gateway** | 11.39.0 |
| **events-gateway** | 11.34.0 |
| **file-gateway** | 11.38.0 |
| **integration-designer** | 11.62.1 |
| **license** | 11.34.0 |
| **nosql-db-runner** | 11.35.0 |
| **notification-plugin** | 11.41.0 |
| **organization-manager** | 11.38.0 |
| **process-engine** | 11.53.1 |
| **runtime-manager** | 11.46.0 |
| **scheduler-core** | 11.30.0 |
| **task-management-plugin** | 11.42.0 |
| **webhook-gateway** | 11.37.0 |

### AI base components

| Component | 5.11.0 |
| - | - |
| **embedder** | 11.3.1 |
| **knowledgebase-indexer-v2** | 11.3.1 |
| **knowledgebase-rag** | 11.3.1 |
| **doc-parser** | 11.3.1 |

### AI dev-time components

| Component | 5.11.0 |
| - | - |
| **ai-gateway** | 11.39.0 |
| **ai-analyst** | 11.3.1 |
| **ai-assistant** | 11.3.1 |
| **ai-designer** | 11.3.1 |
| **ai-developer** | 11.3.1 |
| **kb-enrichment** | 11.3.1 |
| **planner** | 11.3.1 |

### AI runtime components

| Component | 5.11.0 |
| - | - |
| **agent-builder** | 11.3.1 |
| **ai-architect** | 11.3.1 |
| **data-privacy** | 11.3.1 |
| **doc-converter** | 11.3.1 |
| **dynamic-classifier** | 11.3.1 |
| **evals-judge** | 11.3.1 |
| **speech-to-text** | 11.3.1 |
| **web-crawler** | 11.3.1 |

### AI extensions

| Component | 5.11.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.89.1` for FlowX.AI 5.11.0). The native iOS and Android renderers version independently.

| Component | 5.11.0 |
| - | - |
| **@flowx/angular-sdk** | 11.89.1 |
| **@flowx/angular-theme** | 11.89.1 |
| **@flowx/angular-ui-toolkit** | 11.89.1 |
| **@flowx/react-sdk** | 11.89.1 |
| **@flowx/react-theme** | 11.89.1 |
| **@flowx/react-ui-toolkit** | 11.89.1 |
| **@flowx/react-native-sdk** | 11.89.1 |
| **@flowx/react-native-theme** | 11.89.1 |
| **@flowx/react-native-ui-toolkit** | 11.89.1 |
| **@flowx/core-sdk** | 11.89.1 |
| **@flowx/core-theme** | 11.89.1 |
| **react-saas** | 11.89.1 |
| **iOS renderer** | 11.1.0 |
| **Android renderer** | 11.7.1 |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.11 capabilities. On SaaS they are created and managed automatically.

**Structured template data model** (document and notification templates move to the structured data model):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.sync.out.v1` | document-plugin, notification-plugin → application-manager |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | document-plugin, notification-plugin → application-manager |

**Runtime content import/export** (Knowledge Base and database content):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → ai-platform |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | ai-platform → integration-designer |

**Document classification and ML extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | ai-platform → integration-designer |

### AI Platform packaging

FlowX.AI 5.11 consolidates the AI Platform services into a single **`ai-platform` umbrella chart** (version `11.3.1`). Services that were previously deployed as standalone releases, including `doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, and `evals-judge`, now ship as subcharts of that chart and continue to run under their plain service names. On SaaS this change is applied automatically. The [component versions](#component-versions) section lists each service at its effective `11.3.1` version.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.11.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026

What's new in FlowX.AI 5.11: workflow tools and agentic RAG on Custom Agents, per-Knowledge-Base embedding models, document classification, extended response caching, subworkflow data mapping, structured template data models, and chat and UI Flow renderer improvements.

[FlowX.AI 5.11 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.11.0.html)

> [!NOTE]
>
> **FlowX.AI 5.11 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.11** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release turns Custom Agents into orchestrators that call FlowX workflows as tools and search knowledge bases agentically, adds per-Knowledge-Base embedding models with local embedders for personal-information content, and introduces document classification. It also extends response caching and subworkflow data mapping in the Integration Designer, moves document and notification templates onto the structured data model, and adds chat notifications, session ownership, and richer runtime audit to the renderers.

### What changed since 5.10.0

| 5.10.0 | 5.11.0 |
| - | - |
| Custom Agents call MCP servers, built-in tools, web search, and Knowledge Bases | + **FlowX workflows as callable tools** on a Custom Agent, with per-tool usage hints and tool-calling caps |
| Knowledge Base retrieval is a plain vector search on the org default embedding model | + **Agentic knowledge base search** and **per-KB embedding models**, including keyless local embedders for personal-information content |
| REST caching covers GET; SQL operations are cacheable | + **POST** REST responses, **file-storage** reads, and **Mongo** reads are cacheable too |
| Subworkflow input/output is raw JSON | + **Input and output mappers** on the Subworkflow node, with per-mapping test and import/export |
| Document and notification templates use a free-form key/value Data model tab | + Templates use the **structured data model** with typed attributes, validators, and Input Parameters |

***

**What's new?**

> [tab] AI & Agents
>
> 🧰 [**Workflow tools on Custom Agents**](#workflow-tools-on-custom-agents) - Attach FlowX workflows as callable agent tools, with usage hints and tool-calling caps\
> 🔎 [**Agentic knowledge base search and Show Reasoning**](#agentic-knowledge-base-search-and-show-reasoning) - Query decomposition, relevance grading, and a reasoning summary in the run log\
> 🧠 [**Per-knowledge-base embedding models**](#per-knowledge-base-embedding-models) - Pick an embedding model per KB and keep personal-information content on a local embedder\
> 🗂️ [**Knowledge Base content lifecycle**](#knowledge-base-content-lifecycle) - Delete entries by metadata filter, structured failure handling, per-chunk timestamps\
> 🏷️ [**Document classification**](#document-classification) - Train or import a classifier and route document pages in a workflow\
> 💬 [**Conversational chat reply requirement**](#conversational-chat-reply-requirement) - A conversational run that never replies to chat now fails with a clear error\
> ✍️ [**Custom Agent instruction limit**](#custom-agent-instruction-limit) - The Instructions field is capped at 10,000 characters

> [tab] Integrations & Data
>
> 🔁 [**Reusable functions in Integration Designer**](#reusable-functions-in-integration-designer) - Call reusable functions from Script and Condition (Fork) nodes\
> ⚡ [**Extended response caching**](#extended-response-caching) - Cache POST REST, file-storage reads, and Mongo reads alongside GET and SQL\
> 🔗 [**Subworkflow data mapping**](#subworkflow-data-mapping) - Map data in and out of a subworkflow with input and output mappers\
> 📎 [**Email attachment filtering by extension**](#email-attachment-filtering-by-extension) - Filter attachments by individual file extension instead of broad categories

> [tab] Platform
>
> 🧱 [**Structured data model for templates**](#structured-data-model-for-templates) - Document and notification templates use typed attributes and Input Parameters\
> ✅ [**Data model attribute validators**](#data-model-attribute-validators) - Required, min/max, length, pattern, email, items, and currency rules on attributes\
> 🧾 [**UI Flow runtime audit**](#ui-flow-runtime-audit) - Audit workflow-instance runs, chat messages, conversation reads, and process renders\
> 📤 [**Cross-version export adaptation**](#cross-version-export-adaptation) - Exports adapt UI templates for older LTS targets by removing unsupported handlers\
> 🔐 [**Platform and runtime improvements**](#platform-and-runtime-improvements) - Runtime access-control hardening

> [tab] Renderers & UI Flows
>
> 🔔 [**Chat notifications and conversation search**](#chat-notifications-and-conversation-search) - Unread-message badge on the chat button and search across conversation history\
> 🚫 [**Disable chat input on a condition**](#disable-chat-input-on-a-condition) - A business condition can make the chat input read-only\
> 🧭 [**Navigate To form validation**](#navigate-to-form-validation) - Require form validation before a Navigate To action, on web, iOS, and Android\
> ⌛ [**Expired UI Flow sessions**](#expired-ui-flow-sessions) - Expired sessions show a session-expired screen with a start-fresh option\
> 👤 [**UI Flow session owner**](#ui-flow-session-owner) - Restrict a running session to a single user\
> 🏁 [**Process Renderer process-end handling**](#process-renderer-process-end-handling) - Run a configurable action when an embedded process ends\
> 🎛️ [**Renderer improvements**](#renderer-improvements) - Batched enumeration fetch and process-start loader alignment

### **Workflow tools on Custom Agents**

> [card] Attach FlowX workflows as callable tools on a Custom Agent
>
> > [tab] Overview
> >
> > **Before 5.11:** a Custom Agent's tools were MCP servers, built-in tools, web search, and Knowledge Base retrieval. **Now:** you can also attach FlowX workflows as callable tools.
> >
> > In the Custom Agent node's **Tools** section, add a workflow as a tool and fill the per-tool **When should the agent use this workflow?** hint that tells the agent when to call it. The agent calls the workflow like any other tool, passing arguments that match the workflow's Start-node input parameters. A workflow with no input parameters cannot be attached. Each tool call starts a fresh workflow run whose output returns to the agent, and the child run is linked in the console log.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Workflows as tools
> > >
> > > Attach up to ten workflows as tools on one Custom Agent, each with a usage hint the agent reads when deciding to call it.
> >
> > > [card] Typed arguments
> > >
> > > The agent passes arguments that match the workflow's Start-node input parameters; workflows without input parameters are not eligible.
> >
> > > [card] Tool-calling limits
> > >
> > > An agent is limited in how many tool calls it can make per run, and workflow-tool call chains are depth-limited so recursion cannot run away.
> >
> > > [card] Linked runs
> > >
> > > Each workflow tool call is a fresh run whose output returns to the agent and is linked in the console log.
>
> SaaS

### **Agentic knowledge base search and Show Reasoning**

> [card] Agentic knowledge base search and reasoning summaries
>
> > [tab] Overview
> >
> > The Custom Agent node gains **agentic knowledge base search** and a **Show Reasoning** toggle.
> >
> > With agentic search on, the agent breaks a question into sub-queries, retrieves and grades results for relevance, and retries with reworded queries if the first pass finds nothing. It is better on complex questions and uses more model calls; a single pass with three sub-queries is the default. Agentic search never returns worse results than plain retrieval. **Show Reasoning** captures the model's reasoning summary in the run and console log; the structured response and the chat reply shown to the user are unchanged.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Agentic search
> > >
> > > Turn on **Enable agentic knowledge base search**, then set **Max attempts** and **Subqueries per attempt** under Settings.
> >
> > > [card] Relevance grading
> > >
> > > Retrieved candidates are graded against the original question, with corrective retries until a relevant result is found or the attempt budget is spent.
> >
> > > [card] Show Reasoning
> > >
> > > Surface the model's reasoning in the run log without changing the answer returned to the user.
> >
> > > [card] Fail-open
> > >
> > > Agentic mode returns the same chunk metadata as plain retrieval, so citations and telemetry are unchanged.
>
> SaaS

### **Per-knowledge-base embedding models**

> [card] Per-KB embedding models and local embedders for personal information
>
> > [tab] Overview
> >
> > Knowledge Bases can now use a **per-KB embedding model**, and a KB that holds personal information can keep its content on a local embedder.
> >
> > Turn on **Containing Personal Information** on a Knowledge Base to enable a local embedding model, then pick one from the **Embedding model** list. Local embedders (for example a text-embedding-inference or Ollama endpoint, or any OpenAI-compatible endpoint) are configured as a single **CUSTOM** provider in the organization AI settings, with a free-form base URL and no API key. The embedding model is set before the first store and cannot be changed afterward. Non-personal-information Knowledge Bases use the organization's default embedding model.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See the Knowledge Base documentation.
>
> > [tab] Key Features
> >
> > > [card] Per-KB model
> > >
> > > Each Knowledge Base carries its own embedding-model reference; a new Settings tab shows the current model.
> >
> > > [card] Local embedders
> > >
> > > Keep personal-information content on-box using a keyless local embedder fronted by a CUSTOM AI provider.
> >
> > > [card] Model travels with export
> > >
> > > Project version export preserves the KB's embedding-model reference, so a re-import keeps the same model.
> >
> > > [card] Set once per KB
> > >
> > > A Knowledge Base's embedding model is chosen before its first store and cannot be changed afterward.
>
> SaaS

### **Knowledge Base content lifecycle**

> [card] Delete entries by filter, structured failure handling, and per-chunk timestamps
>
> > [tab] Overview
> >
> > The **Update Knowledge Base** node gains a **Delete entries** operation and structured failure handling, and retrieval results now carry per-chunk metadata.
> >
> > **Delete entries** soft-deletes chunks whose entry-level metadata matches a filter, in one store or across the Knowledge Base; an empty or match-all filter is rejected so a misconfigured node cannot wipe a store. When an update operation fails, the node's **FAIL** branch returns a structured output with the operation, store, failure reason, and how many chunks were rolled back, and any partial changes are reversed. Retrieval results now include a per-chunk identifier and an ingestion timestamp.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > >
> > > See the Managing Knowledge Base content documentation.
>
> > [tab] Key Features
> >
> > > [card] Filtered deletion
> > >
> > > Delete entries by metadata filter from a workflow, with an empty or match-all filter rejected as a safety guard.
> >
> > > [card] Failure output with rollback
> > >
> > > The FAIL branch reports the operation, store, reason, and rolled-back chunk count; partial changes are reversed.
> >
> > > [card] Per-chunk timestamps
> > >
> > > RAG results carry a chunk identifier and an ingestion timestamp (empty for chunks indexed before this shipped).
> >
> > > [card] Clear retry signal
> > >
> > > Retryable failures such as extraction or chunking errors are distinguished from non-retryable ones such as size or timeout.
>
> SaaS

### **Document classification**

> [card] Classify document pages with a trainable ML model
>
> > [tab] Overview
> >
> > FlowX.AI adds **Document Classifiers**: deterministic ML models that sort document pages into categories. Define classes, upload training data, and train or import a model, then route each page in a workflow with the new **Document Classification** node.
> >
> > The node runs the active model over a document, returns a predicted label and probability per page with a configurable confidence threshold, and flags low-confidence pages. A page-level failure does not fail the node.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer documentation.
>
> > [tab] Key Features
> >
> > > [card] Train or import
> > >
> > > Build classes and training data in the Designer, then train a model or import a pre-trained one.
> >
> > > [card] Per-page classification
> > >
> > > The Document Classification node returns a label and probability for each page, with a confidence threshold and low-confidence flags.
> >
> > > [card] Deterministic routing
> > >
> > > Combine the node with a condition to route pages by their predicted category.
> >
> > > [card] Resilient runs
> > >
> > > A page that cannot be classified is reported per page without failing the whole node.
>
> SaaS

### **Conversational chat reply requirement**

> [card] Conversational runs must reply to chat
>
> A conversational (chat-driven) workflow must send at least one chat reply, either from a Custom Agent node with **Send as Chat Reply** on or from a Navigate in UI Flow node that completes the turn. A run that reaches the end without replying now fails with a clear error instead of ending silently.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **Custom Agent instruction limit**

> [card] Instructions field capped at 10,000 characters
>
> The Custom Agent **Instructions** field is now limited to 10,000 characters.
> SaaS

### **Reusable functions in Integration Designer**

> [card] Call reusable functions from Script and Condition (Fork) nodes
>
> Reusable functions can now be called from **Script** nodes and **Condition (Fork)** nodes in the Integration Designer, not just from Business Rule actions in processes. Functions are referenced in the node's JavaScript or Python and resolved at runtime from the app version's function copies, including functions that call other functions and cross-app references. A Fork node resolves the references used across all of its branch conditions.
>
> For more information, see the [reusable functions](/5.9/docs/building-blocks/reusable-resources/reusable-functions) documentation.
> SaaS

### **Extended response caching**

> [card] Cache POST REST, file-storage reads, and Mongo reads
>
> > [tab] Overview
> >
> > Response caching in the Integration Designer now covers more operation types. **POST** REST endpoints are cacheable alongside GET, with the request body forming part of the cache key so different bodies cache separately. Read **file-storage** operations (LIST and DOWNLOAD) and read **Mongo** operations (FIND, FIND\_ONE, AGGREGATE) are cacheable alongside SQL. Mutating operations are never cached.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] POST caching
> > >
> > > Cache POST responses, keyed on the request body so distinct requests stay separate.
> >
> > > [card] File-storage reads
> > >
> > > LIST and DOWNLOAD operations are cacheable; UPLOAD, DELETE, and MOVE are not.
> >
> > > [card] Mongo reads
> > >
> > > FIND, FIND\_ONE, and AGGREGATE are cacheable alongside SQL; mutating Mongo operations are not.
> >
> > > [card] Shared policy
> > >
> > > All cacheable surfaces reuse the same time-based expiry and per-operation clear-cache action.
>
> SaaS

### **Subworkflow data mapping**

> [card] Map data in and out of a subworkflow with input and output mappers
>
> > [tab] Overview
> >
> > The **Subworkflow** node adds data mapping as an alternative to raw JSON. Turn on **Enable data mapping** to define an **Input mapping** per subworkflow start node and an **Output mapping** per end node, mapping individual data slices instead of hand-editing JSON. Output mapping does not apply to asynchronous subworkflows. Each mapping opens a mapper with a test action, and mappings travel with import, export, and clone.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] Input and output mappers
> > >
> > > Map data into the subworkflow per start node and out of it per end node, without editing raw JSON.
> >
> > > [card] Per-mapping test
> > >
> > > Test a mapping with source and target slices and apply values from a past instance.
> >
> > > [card] Travels with the project
> > >
> > > Mappings are preserved on import, export, and clone.
> >
> > > [card] Async-aware
> > >
> > > Output mapping is hidden for asynchronous subworkflows, which do not return data to the caller.
>
> SaaS

### **Email attachment filtering by extension**

> [card] Filter email attachments by individual file extension
>
> Email Trigger and Microsoft Outlook data sources now filter attachments by **individual file extension** instead of the five broad file-type categories. Choose the exact extensions to accept and to forward into a process. Existing category selections are migrated to their individual extensions automatically on upgrade, so current triggers keep working.
>
> For more information, see the [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger) documentation.
> SaaS

### **Structured data model for templates**

> [card] Document and notification templates use the structured data model
>
> > [tab] Overview
> >
> > **Before 5.11:** document and notification templates declared parameters in a free-form key/value Data model tab. **Now:** templates use the same structured data model as the rest of the platform.
> >
> > On the **Data Model** tab you define typed attributes with validations, sensitive-data and reporting flags, and references to project or library data types. On the **Input Parameters** tab you select which attributes the template expects. Values sent in the request are substituted for those attributes at generation time.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > >
> > > See the notification templates documentation.
>
> > [tab] Key Features
> >
> > > [card] Typed attributes
> > >
> > > Define string, number, boolean, enum, date, currency, object, and array attributes with validations.
> >
> > > [card] Input Parameters
> > >
> > > Pick the attributes the template expects on a dedicated Input Parameters tab.
> >
> > > [card] Reference shared types
> > >
> > > Reference project and library data types like other resources.
> >
> > > [card] OTP unchanged
> > >
> > > The OTP flow contract is unchanged; the reserved `otpValue` and request `data` object work as before.
>
> SaaS

### **Data model attribute validators**

> [card] Validators on data model attributes
>
> Data model attributes now support validators. Available rules depend on the attribute type and include **Required**, **Min/Max Value**, **Min/Max Length**, **Pattern**, **Email Format**, and **Min/Max Items**, plus currency-specific amount and code rules. Validators are stored on the attribute and apply wherever that data model is used, including project, process, template, and reusable UI template data models.
>
> For more information, see the [project data model](/5.9/docs/building-blocks/project-data-model) documentation.
> SaaS

### **UI Flow runtime audit**

> [card] Audit UI Flow runtime activity
>
> UI Flow runtime sessions are now audited in more detail. The audit log records **workflow-instance** runs, chat **message sends**, conversation **list** and **history** reads, and whether the Process Renderer performed a **render** or a start. Entries name the app and the workflow instance.
>
> For more information, see the [audit](/5.9/docs/platform-deep-dive/core-extensions/audit) documentation.
> SaaS

### **Cross-version export adaptation**

> [card] Exports adapt UI templates for older LTS targets
>
> When you export a project to an older platform version, UI-template features the target version cannot understand are removed during down-adaptation, so the export imports cleanly. This currently covers Process Renderer process-end event handlers and the Navigate To **forms to validate** setting.
>
> For more information, see [Cross-version export and import](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
> All Deployments

### **Platform and runtime improvements**

> [card] Runtime access-control hardening
>
> Runtime API requests are now authorized against the roles defined in the running build across start-process, start-workflow, task views, conversation history, and the public runtime API. Requests without a matching build role are denied, and enforcement is on by default.
> All Deployments

> [card] Theme import no longer duplicates system icons
>
> Exporting a theme no longer includes duplicate copies of built-in system icons, and importing a theme no longer creates new ones. Duplicate icon copies that accumulated in earlier versions are cleaned up automatically on upgrade — no action is required.
> All Deployments

### **Chat notifications and conversation search**

> [card] Unread-message badge and conversation search in chat
>
> > [tab] Overview
> >
> > The chat floating action button gains an **unread-message notification badge**, with a themeable **Notification Dot** you can position in the chat style panel. The chat panel also adds **search across conversation history**, which filters conversations by a text query, highlights matches, and shows an empty state when nothing matches.
> >
> > For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
>
> > [tab] Key Features
> >
> > > [card] Unread badge
> > >
> > > The chat button shows a badge with the unread agent-message count; it is hidden while the chat is open in full screen.
> >
> > > [card] Notification Dot
> > >
> > > Position and size the notification dot from the chat style panel, with theme support.
> >
> > > [card] Conversation search
> > >
> > > Search conversation history from the chat panel, with highlighted matches and an empty state.
>
> SaaS

### **Disable chat input on a condition**

> [card] Make the chat input read-only with a business condition
>
> The chat **Input** component can be disabled by a business-condition expression. When the condition evaluates true, the input becomes read-only with an explanatory tooltip, and any pending attachments and voice input are cleared.
>
> For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
> SaaS

### **Navigate To form validation**

> [card] Require form validation before a Navigate To action
>
> A **Navigate To** action can now require selected forms to pass validation before navigating, matching how Start Process and Start Workflow actions gate on validation. This is available on web, iOS, and Android.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Expired UI Flow sessions**

> [card] A session-expired screen with a start-fresh option
>
> Expired UI Flow sessions now show a **session-expired** screen with a start-fresh option instead of leaving the previous data visible in read-only form. Expired and unauthorized access is written to the audit log.
> SaaS

### **UI Flow session owner**

> [card] Restrict a running session to a single user
>
> A UI Flow can restrict a running session to a single owner. When **Allow multiple editors** is off, other users who try to open the session are shown an access-denied screen, and unauthorized access is audited. Newly created flows default to single-owner; imported and existing flows keep the previous shared behavior. A session-owner value type is available for permission-based hide and disable rules.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Process Renderer process-end handling**

> [card] Run a configurable action when an embedded process ends
>
> The Process Renderer can now run a configurable action when its embedded process ends, using a new process-end trigger on event handlers. Configure what happens at that point instead of leaving the renderer idle when the process completes.
>
> For more information, see [Process end handling](/5.9/docs/building-blocks/ui-flows#process-end-handling).
> SaaS

### **Renderer improvements**

> [card] Renderer performance and behavior
>
> * **Batched enumeration fetch:** renderers batch enumeration lookups into a single bulk request, cutting the number of calls when rendering enum-backed fields. Applies to web and mobile renderers.
> * **Process-start loader alignment:** the web renderer keeps the process-start loader visible until the first user task, matching the mobile SDKs.
>   SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

FlowX.AI 5.11 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.11 deployment guidelines](./deployment-guidelines-v5.11).


# Deployment guidelines v5.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12

Component versions and deployment notes for FlowX.AI 5.12 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.12 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.12.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.12.0 |
| - | - |
| **admin** | 11.69.2 |
| **advancing-controller** | 11.46.0 |
| **application-manager** | 11.68.3 |
| **audit-core** | 11.44.1 |
| **authorization-system** | 11.53.2 |
| **cms-core** | 11.61.1 |
| **data-search** | 11.44.1 |
| **data-sync** | 11.43.1 |
| **designer** | 11.126.1 |
| **document-plugin** | 11.68.1 |
| **email-gateway** | 11.58.1 |
| **events-gateway** | 11.49.2 |
| **file-gateway** | 11.55.1 |
| **integration-designer** | 11.90.2 |
| **license** | 11.48.1 |
| **nosql-db-runner** | 11.49.1 |
| **notification-plugin** | 11.61.2 |
| **organization-manager** | 11.53.1 |
| **process-engine** | 11.76.1 |
| **runtime-manager** | 11.68.3 |
| **scheduler-core** | 11.45.1 |
| **task-management-plugin** | 11.59.2 |
| **webhook-gateway** | 11.54.1 |

### AI base components

| Component | 5.12.0 |
| - | - |
| **embedder** | 11.5.0 |
| **knowledgebase-indexer-v2** | 11.5.0 |
| **knowledgebase-rag** | 11.5.0 |
| **doc-parser** | 11.5.0 |

### AI dev-time components

| Component | 5.12.0 |
| - | - |
| **ai-gateway** | 11.53.1 |
| **ai-analyst** | 11.5.0 |
| **ai-assistant** | 11.5.0 |
| **ai-designer** | 11.5.0 |
| **ai-developer** | 11.5.0 |
| **kb-enrichment** | 11.5.0 |
| **planner** | 11.5.0 |

### AI runtime components

| Component | 5.12.0 |
| - | - |
| **agent-builder** | 11.5.0 |
| **ai-architect** | 11.5.0 |
| **data-privacy** | 11.5.0 |
| **doc-converter** | 11.5.0 |
| **dynamic-classifier** | 11.5.0 |
| **evals-judge** | 11.5.0 |
| **speech-to-text** | 11.5.0 |
| **web-crawler** | 11.5.0 |

### AI extensions

| Component | 5.12.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.126.1` for FlowX.AI 5.12.0). The native iOS and Android renderers version independently.

| Component | 5.12.0 |
| - | - |
| **@flowx/angular-sdk** | 11.126.1 |
| **@flowx/angular-theme** | 11.126.1 |
| **@flowx/angular-ui-toolkit** | 11.126.1 |
| **@flowx/react-sdk** | 11.126.1 |
| **@flowx/react-theme** | 11.126.1 |
| **@flowx/react-ui-toolkit** | 11.126.1 |
| **@flowx/react-native-sdk** | 11.126.1 |
| **@flowx/react-native-theme** | 11.126.1 |
| **@flowx/react-native-ui-toolkit** | 11.126.1 |
| **@flowx/core-sdk** | 11.126.1 |
| **@flowx/core-theme** | 11.126.1 |
| **react-saas** | 11.126.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.12 capabilities. On SaaS they are created and managed automatically.

**Event-triggered workflows** (email and webhook triggers can start an integration workflow):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Deep Research node** (the node hands research jobs to the AI Platform over Kafka):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | dead-letter queue for failed research jobs |

**Bulk process-instance migration:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |

**Notifications:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.eventsgateway.user.notifications.v1` | application-manager, process-engine → events-gateway |

**Document classification:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → dead-letter sink (not consumed) |

### New service dependency: webhook-gateway and MongoDB

The webhook gateway now reads the runtime registry that backs event-triggered workflows, so it depends on the runtime MongoDB database in addition to its existing relational database. On SaaS this connection is provisioned and managed by FlowX.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map. | none (required) | integration-designer |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today. | `k1` | integration-designer |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index. | `PT24H` | integration-designer |

### Native PostgreSQL partitioning for the engine

On PostgreSQL, the engine converts its runtime tables to native `RANGE(partition_id)` partitioning the first time it starts on the new version, and archiving then detaches a partition instead of copying rows out of it. Deployments that never enabled partitioning are skipped entirely, and Oracle deployments are unaffected.

Unlike most 5.12 changes, this one also reaches self-hosted 5.9.x in the 5.9.5 patch rather than waiting for the next LTS release family.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Whether archiving detaches partitions with `DETACH CONCURRENTLY` on natively partitioned tables. Setting it to `false` returns archiving to the previous batched insert-and-delete, but does not undo the conversion: the tables stay natively partitioned. | `true` | process-engine |

For the conversion cost, table locking and the one-way caveat, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.12.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026

What's new in FlowX.AI 5.12: parallel multi-instance subworkflow fan-out, event-triggered integration workflows, bulk process-instance migration, personal-data mask and restore nodes, and a Db2 data source.

[FlowX.AI 5.12 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.12.0.html)

> [!NOTE]
>
> **FlowX.AI 5.12 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.12** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release lets an integration workflow fan out over a collection without a subprocess, starts workflows directly from email and webhook events, and migrates process instances to a new build in bulk. It also adds personal-data mask and restore nodes to the Integration Designer and a Db2 relational data source.

### What changed since 5.11.0

| 5.11.0 | 5.12.0 |
| - | - |
| A workflow ran once per call; fanning out over a collection needed a BPMN Call Activity and a subprocess | + **Multi-instance subworkflow node** fans a workflow over a collection directly in the Integration Designer |
| An email or webhook trigger could start a process | + **Event-triggered workflows** start an integration workflow from the same triggers |
| Process instances migrated to a new build one at a time | + **Bulk migration** moves a filtered set of instances in one operation |
| Personal-data handling was configured on the agent | + **Mask and restore nodes** place it as explicit workflow steps, with details in the run log |

***

**What's new?**

> [tab] Integrations & Data
>
> 🔀 [**Multi-instance subworkflow node**](#multi-instance-subworkflow-node) - Fan a workflow out over a collection\
> ⚡ [**Event-triggered workflows**](#event-triggered-workflows) - Start a workflow from an email or webhook\
> 🗄️ [**Db2 relational data source**](#db2-relational-data-source) - Connect to Db2 for i or Db2 LUW\
> 🔻 [**Subworkflow failure exit**](#subworkflow-failure-exit) - Send a failed mapping down its own branch\
> 🔓 [**Skip TLS verification on a REST data source**](#skip-tls-verification-on-a-rest-data-source) - Reach a trusted internal host with an untrusted certificate\
> 🔔 [**Send Notification node**](#send-notification-node) - Send a templated notification straight from a workflow

> [tab] AI Platform
>
> 🛡️ [**Personal-data mask and restore nodes**](#personal-data-mask-and-restore-nodes) - Explicit workflow steps with run-log detail\
> 🧩 [**Reusable functions as agent tools**](#reusable-functions-as-agent-tools) - Give an agent a deterministic function to call\
> 👍 [**Chat response feedback**](#chat-response-feedback) - Let users rate an agent's answer, and theme how it looks\
> 📏 [**Custom evaluators**](#custom-evaluators) - Score an agent against a rubric you write yourself\
> 🔍 [**Deep Research node**](#deep-research-node) - Research a question across the open web and file a cited report\
> 🛠️ [**Built-in agent tools by category**](#built-in-agent-tools-by-category) - Twenty ready-made tools an agent can use, picked by category\
> 🪄 [**AI Designer builds UI Flows**](#ai-designer-builds-ui-flows) - Generate and edit multi-page UI Flows from a description

> [tab] Platform
>
> 📦 [**Bulk process-instance migration**](#bulk-process-instance-migration) - Move a filtered set of instances to a new build\
> 🔎 [**Runtime list filters and a Workflow Instances page**](#runtime-list-filters-and-a-workflow-instances-page) - Find the failed run without scanning the list\
> 🎨 [**Process canvas editing**](#process-canvas-editing) - Connect, reshape and resize more directly on the BPMN canvas\
> ⚠️ [**Check a version for issues**](#check-a-version-for-issues) - Validate every workflow in the version from one panel\
> 🧱 [**Reusable UI Templates in UI Flows**](#reusable-ui-templates-in-ui-flows) - Reuse a template on UI Flow pages, not just User Tasks\
> 🌿 [**Branch management**](#branch-management) - Merge to any branch, archive or delete the ones you are done with

### **Multi-instance subworkflow node**

> [card] Multi-instance subworkflow node
>
> > [tab] Overview
> >
> > **Before 5.12.0:** running an integration workflow once per item in a collection meant leaving the Integration Designer, wrapping the workflow in a BPMN process and fanning out with a multi-instance Call Activity. **Now:** the Subworkflow node fans out over an array on its own, in parallel.
> >
> > Turn on **Parallel Multi-Instance** under **Execution** on a Subworkflow node, pick the **Input Array** to iterate, and pick the **Output Array** that collects each run's result. The node starts one subworkflow instance per element of the input array and gathers the results into the output array on the parent workflow.
>
> > [tab] Key Features
> >
> > > [card] Input Array
> > >
> > > The array of objects to iterate. One subworkflow instance starts per element. Required.
> >
> > > [card] Output Array
> > >
> > > The array each instance result is collected into. Required.
> >
> > > [card] Correlation attribute
> > >
> > > Optional. Decides which output array element each result updates. Results matching no element, or all results when no attribute is set, are appended.
> >
> > > [card] Runs in parallel
> > >
> > > Instances run in parallel, and fan-out stays inside the Integration Designer instead of requiring a BPMN Call Activity.
>
> For the full configuration reference, see [Parallel multi-instance](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) on the Subworkflow node.
> SaaS

### **Event-triggered workflows**

> [card] Event-triggered workflows
>
> > [tab] Overview
> >
> > **Before 5.12.0:** an incoming email or webhook could start a process. **Now:** the same triggers can start an integration workflow directly.
> >
> > A workflow declares the trigger it listens for, and the platform keeps a subscription registry so a change to that trigger takes effect without rebuilding the whole app. Incoming email and webhook events are routed to the workflow that subscribes to them.
>
> > [tab] Key Features
> >
> > > [card] Email and webhook triggers
> > >
> > > Both trigger types can start a workflow, not only a process.
> >
> > > [card] Subscription registry
> > >
> > > Trigger changes update the affected data source without a full build recompute.
>
> > [tab] Architecture
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Trigger subscription changes | admin, integration-designer, application-manager | Design-time changes update the runtime subscription registry |
> > | Event delivery | email-gateway, webhook-gateway, integration-designer | Events are routed to the subscribing workflow |
> > | Webhook state | webhook-gateway | The webhook gateway now also reads the runtime registry, adding a MongoDB dependency it did not previously have |
> >
> > On SaaS these changes are applied automatically. See [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12) for the topic and dependency detail.
>
> For the full configuration reference, see [External triggers](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers) on the Start node.
> SaaS

### **Bulk process-instance migration**

> [card] Bulk process-instance migration
>
> > [tab] Overview
> >
> > **Before 5.12.0:** moving running process instances onto a new build was a one-at-a-time operation. **Now:** a filtered set of instances migrates in a single run.
> >
> > Select the target build, filter the instances to move, check the migration for problems before committing to it, and then run it. Progress and per-instance outcomes are available while it runs, and terminated instances are handled explicitly rather than failing the batch.
> >
> > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > See migrating process instances.
>
> > [tab] Key Features
> >
> > > [card] Filter then migrate
> > >
> > > Move specific instance UUIDs, the instances matching a process, node and status filter, or every eligible instance.
> >
> > > [card] Pre-flight check
> > >
> > > Validate a migration before running it.
> >
> > > [card] Per-instance outcomes
> > >
> > > Inspect details and results for the instances in a batch.
> >
> > > [card] Audit trail
> > >
> > > Migrations are recorded against the instances they touch.
>
> For the full configuration reference, see the [Migrate process instances](/5.9/docs/projects/runtime/active-process/migrate-process-instances) documentation.
> SaaS

### **Runtime list filters and a Workflow Instances page**

> [card] Runtime list filters and a Workflow Instances page
>
> Finding a failed run no longer means scanning an unfiltered list. The **Process Instances** and **UI Flow Sessions** lists gain a multi-select **Status** filter and a start-date filter on their columns, so "every failed instance since last night" is two clicks.
>
> Workflow runs get more: a new **Workflow Instances** page under **Runtime** lists every run in the project, filterable by **Status**, by date, and by **Origin**: whether a run was started by a process, a UI Flow, a webhook, or an email trigger. Until now, a workflow's runs were only visible from inside that workflow in the Integration Designer.
>
> For details, see the [Workflow Instances](/5.9/docs/projects/runtime/workflow-instances) documentation.
> SaaS

***

### **Personal-data mask and restore nodes**

> [card] Personal-data mask and restore nodes
>
> > [tab] Overview
> >
> > **Before 5.12.0:** personal-information handling was configured on the agent rather than placed in the flow. **Now:** masking and restoring personal data are workflow nodes you position explicitly, and you choose which key from the node input they apply to.
> >
> > Put a mask node before the step that must not see the raw values and a restore node after it. The workflow run log shows what each node did, so a run can be inspected without exposing the underlying data.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See the Personal Information Guard documentation.
>
> > [tab] Key Features
> >
> > > [card] Mask and restore as nodes
> > >
> > > Personal-data handling becomes an explicit step in the workflow.
> >
> > > [card] Selectable input key
> > >
> > > Choose which key from the node input the node applies to.
> >
> > > [card] Run-log detail
> > >
> > > A restore reports whether it completed, partially completed or failed, and how many of the issued placeholders it put back.
>
> For the full configuration reference, see [Masking and restoring across several nodes](/5.9/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
> SaaS

### **Db2 relational data source**

> [card] Db2 relational data source
>
> IBM Db2 joins the relational database data sources available in the Integration Designer. Because Db2 products use different drivers, ports and catalogs, the connection starts with a **Db2 Product** choice and the rest of the form follows from it. **Db2 for i (IBM i)** is the default and **Db2 LUW** is also supported. **Db2 for z/OS** appears in the list but is not implemented in this release, and selecting it fails with an explicit error rather than falling back to another driver.
>
> The port is prefilled from the product and whether SSL is on. Db2 for i adds a naming convention, an optional library and library list, and a switch for returning character data that the host reports as binary. On Db2 for i, connections also open **read-only by default**, so turn that off if your queries need to write, and the transaction isolation level defaults to none, because a table without a journal cannot take part in a transaction. Isolation is validated when the data source is saved rather than when a query first runs.
>
> For the full configuration reference, see the [Db2 Database](/5.9/docs/platform-deep-dive/integrations/db2-database) documentation.
> SaaS

***

### **Subworkflow failure exit**

> [card] Subworkflow failure exit
>
> A Subworkflow node now has a second exit. Connect the red one and a failure takes its own branch instead of stopping the parent workflow. It is opt-in per node, so a node without that branch fails and blocks exactly as before and nothing changes for existing workflows.
>
> Only a mapping failure routes, which is the kind a workflow can be built to handle: the input mapper failing, the input not satisfying what the subworkflow expects, or the output mapper failing on merge-back. An unset subworkflow, a missing response key, no mapping at all, and the node and depth limits all still stop the run. The branch reads a fixed `subWorkflowError` key that says which mapping failed and, when a child did start, which run it was.
>
> For the full configuration reference, see [Routing a subworkflow failure](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
> SaaS

***

### **Skip TLS verification on a REST data source**

> [card] Skip TLS verification on a REST data source
>
> A REST data source can now be told to stop checking the certificate of the host it calls, for the cases where an internal endpoint presents a self-signed or mismatched certificate and the alternative is an infrastructure workaround. It is off by default and set per data source, so turning it on for one connector leaves every other call verified.
>
> The Designer warns while it is on, because the call can no longer tell the intended host from anything intercepting it. One consequence is worth knowing before you use it: a truststore configured under Certificates is ignored while verification is skipped, since skipping replaces it rather than adding to it.
>
> For the full configuration reference, see [TLS verification](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#tls-verification) on a REST data source.
> SaaS

***

### **Send Notification node**

> [card] Send Notification node
>
> Workflows can now send notifications themselves. A **Send Notification** node, under **Tools** in the workflow node palette, takes one of your project's notification templates, fills its variables from workflow data, and sends it, without routing through a process just to reach the Notifications plugin.
>
> Address it with **To**, **Cc** and **Bcc**, as fixed addresses or `${}` keys. Email options are all overridable per node: subject, sender name and email, attachments by file path or `${}` key, and custom headers. The node reports the outcome under its response key, including recipient counts and the error when sending fails, so the workflow can branch on it.
>
> For the full configuration reference, see the [Send Notification node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node) documentation.
> SaaS

***

### **Reusable functions as agent tools**

> [card] Reusable functions as agent tools
>
> An AI node's tools can now include a **Function**, alongside built-in web search, an MCP server, and a workflow. Point an agent at a reusable function when the work is deterministic and you would rather it call your code than reason its way there.
>
> A function has to be typed to qualify: it needs both an input and an output slice, and functions without them do not appear in the picker. Give it a description as well, since that is what tells the agent when to reach for it.
>
> For the full configuration reference, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **Chat response feedback**

> [card] Chat response feedback
>
> Users can rate an agent's answer in the chat component, and follow the rating with a reason. The ratings are recorded in audit, so the quality of a deployed agent becomes something you can look at rather than guess at.
>
> The feedback controls and the reason chips are themable, with their own selected and hover states, so they can be styled to match the rest of the interface. The SDKs expose the same feedback state to custom front ends.
>
> For the full configuration reference, see [Rating an answer](/5.9/ai-platform/chat-component#rating-an-answer) on the chat component.
> SaaS

***

### **Custom evaluators**

> [card] Custom evaluators
>
> The evaluator catalogue is no longer fixed. When none of the built-in rubrics measures what you care about, you can write your own evaluator, give it the scoring instructions the judge LLM should follow, and it appears in the catalogue under a **Custom** group alongside the built-in ones.
>
> Choose **Numeric** scoring for a score between 0 and 1 with a pass threshold, or **Binary** for a straight pass or fail. You can start from an existing evaluator to adapt a built-in rubric rather than writing a prompt from scratch. Custom evaluators belong to the workflow you create them in, and unlike the built-in ones they can be edited and deleted.
>
> For the full configuration reference, see the [Evaluations](/5.9/ai-platform/evaluations#custom) documentation.
> SaaS

***

### **Deep Research node**

> [card] Deep Research node
>
> A new AI node researches a question across the open web and files a cited report into a Knowledge Base. It plans the work, sends sub-researchers out to search and read pages, grades what they bring back, and keeps going until its budget is spent or it has enough to report.
>
> Unlike a Custom Agent, you do not write the method: the research prompt is built into the node, so you describe the subject and bind workflow data into it. Depth is a **Quick**, **Standard** or **Deep** preset, or **Custom** if you want to set the number of passes and tool calls yourself. You can restrict which domains the research may read, with an allow list, a deny list, or both.
>
> The result always lands in a Knowledge Base as text, so retrieval nodes and other agents can reach it later. Rendering it as a document is optional.
>
> For the full configuration reference, see the [Deep Research node](/5.9/docs/platform-deep-dive/integrations/deep-research-node) documentation.
> SaaS

***

### **Built-in agent tools by category**

> [card] Built-in agent tools by category
>
> A Custom Agent's built-in tools are now a catalog you pick from by category: **Math tools**, **List tools**, **Date tools**, **Text tools**, and **Web search**. Each category row shows exactly which tools it turns on, and the agent runs deterministic code for that work instead of estimating it in the model.
>
> The catalog holds twenty tools, fifteen of them new: a full date family (business days, date arithmetic, formatting, parsing, timezone conversion), text helpers (regex match and extract, fuzzy match), unit conversion, and list aggregation, joining the original calculator, compare, sort, and filter. Web search is part of the same catalog rather than a separate toggle.
>
> Selection stays opt-in and per node. Agents saved with the old toggles keep working without an edit.
>
> For details, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **AI Designer builds UI Flows**

> [card] AI Designer builds UI Flows
>
> The AI Designer now works at the level of a whole UI Flow. Describe the journey and it generates a multi-page flow: structure first, pages filled in parallel, navigation wired between them. Ask for a change and it edits the affected pages instead of regenerating everything.
>
> Proposals appear on the UI Flow canvas as a draft for you to review, the editor stays locked while one is pending, and any data-model changes the flow needs are presented for approval on every turn, the same way single-screen generation already works.
>
> For details, see the [AI Designer](/5.9/ai-platform/pre-built-agents/ai-designer#ui-flow-generation-and-editing) documentation.
> SaaS

***

### **Check a version for issues**

> [card] Check a version for issues
>
> The Designer can now validate the resources in a project version and collect what it finds in one **Issues** panel at the bottom of the screen. Findings are marked where they occur, on resource lists, page titles and workflow canvas nodes, and selecting a marker opens the panel on that finding.
>
> Checks run when you ask for one, and the panel says when it last ran so a stale result is obvious. You can scope the list to the whole version, the resource you are in, or the node you have selected, filter it by severity or text, and group it by resource or severity. Opening **Commit Changes to Version** runs a check on its own and shows each changed resource's state beside it, as a review step rather than a gate. Integration workflows are the resource type validated in this first iteration.
>
> For the full configuration reference, see the [Checking a version for issues](/5.9/docs/projects/managing-applications/checking-for-issues) documentation.
> SaaS

***

### **Branch management**

> [card] Branch management
>
> Project branches gained a management layer. The merge modal now offers every branch you can merge into, not just the current branch's parents, so a fix made anywhere can land anywhere it is needed.
>
> Branches you are done with no longer linger: **Archive Branch** retires one (with a required reason, shown later in its info panel), **Unarchive Branch** brings it back, and **Delete Branch** removes one permanently, guarded so it refuses while child branches, an uncommitted draft, or a running merge depend on it, and asks you to type the branch name when unmerged work would be lost. Deleting has its own permission.
>
> Branch and version info panels round it out: a version merged from another branch says where it came from, including whether that branch has since been archived.
>
> For details, see [Managing branches](/5.9/docs/projects/managing-applications/versioning#managing-branches).
> SaaS

***

### **Process canvas editing**

> [card] Process canvas editing
>
> The BPMN canvas gains a set of direct editing improvements. A **New Node** panel and
> drop-anywhere connecting make it quicker to add a node and wire it up, connecting to a nearby
> node no longer means aiming precisely at a handle, and sequence flows can be reshaped by
> dragging their control points. Swimlanes now resize from any of their four edges. The
> process-instance viewer picks up the same canvas.
>
> The canvas is deliberately unchanged to look at, so existing diagrams, habits and screenshots
> still hold.
>
> For the full configuration reference, see [Faster ways to build](/5.9/docs/building-blocks/process/process#faster-ways-to-build) on the Process Designer canvas.
> SaaS

***

### **Reusable UI Templates in UI Flows**

> [card] Reusable UI Templates in UI Flows
>
> A Reusable UI Template can now be built for **UI Flow** pages as well as for the User Tasks in a process. Each template declares where it is used when you create it, and the UI Flow editor can drop templates onto a page the same way the Process editor always could.
>
> The host type also decides which actions a template's event handlers offer, so a template built for UI Flows gets navigation and workflow actions while one built for processes gets node actions. Because of that the choice is fixed once the template exists, and templates you created before this release count as Process templates, so nothing you already built changes.
>
> For the full configuration reference, see [Where a template can be used](/5.9/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used) in the Reusable UI Templates documentation.
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12).


# Deployment guidelines v5.13.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13

Component versions and deployment-level changes for FlowX.AI 5.13.0.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.13 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency. Self-hosted deployments receive these capabilities with the next LTS release family.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.13.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.13.0 |
| - | - |
| **admin** | 11.97.0 |
| **advancing-controller** | 11.67.0 |
| **application-manager** | 11.101.0 |
| **audit-core** | 11.69.0 |
| **authorization-system** | 11.78.0 |
| **cms-core** | 11.88.0 |
| **data-search** | 11.67.0 |
| **data-sync** | 11.68.0 |
| **designer** | 11.168.1 |
| **designer-user** | 11.8.0 |
| **document-plugin** | 11.95.0 |
| **email-gateway** | 11.83.0 |
| **events-gateway** | 11.72.0 |
| **file-gateway** | 11.79.0 |
| **integration-designer** | 11.119.1 |
| **license** | 11.72.0 |
| **nosql-db-runner** | 11.73.0 |
| **notification-plugin** | 11.88.0 |
| **organization-manager** | 11.77.0 |
| **process-engine** | 11.104.0 |
| **runtime-manager** | 11.101.0 |
| **scheduler-core** | 11.69.0 |
| **task-management-plugin** | 11.84.0 |
| **webhook-gateway** | 11.78.0 |

**designer-user** is new in 5.13. It backs the Designer notification center.

### AI base components

| Component | 5.13.0 |
| - | - |
| **embedder** | 11.6.0 |
| **knowledgebase-indexer-v2** | 11.6.0 |
| **knowledgebase-rag** | 11.6.0 |
| **doc-parser** | 11.6.0 |

### AI dev-time components

| Component | 5.13.0 |
| - | - |
| **ai-gateway** | 11.85.0 |
| **ai-analyst** | 11.6.0 |
| **ai-architect** | 11.6.0 |
| **ai-assistant** | 11.6.0 |
| **ai-designer** | 11.6.0 |
| **ai-developer** | 11.6.0 |
| **harness** | 11.6.0 |
| **ai-render-host** | 11.168.1 |
| **kb-enrichment** | 11.6.0 |
| **planner** | 11.6.0 |

**harness** and **ai-render-host** are new in 5.13. Together they run the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness): harness is the agent service, and ai-render-host renders UI flows headlessly for the agent. ai-render-host ships at the designer version.

### AI runtime components

| Component | 5.13.0 |
| - | - |
| **agent-builder** | 11.6.0 |
| **cee-pii** | 11.6.0 |
| **data-privacy** | 11.6.0 |
| **doc-converter** | 11.6.0 |
| **dynamic-classifier** | 11.6.0 |
| **evals-judge** | 11.6.0 |
| **speech-to-text** | 11.6.0 |
| **web-crawler** | 11.6.0 |

### AI extensions

| Component | 5.13.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.10.2 |
| **observatory-platform** | 11.10.2 |
| **observatory-web** | 11.10.2 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.168.1` for FlowX.AI 5.13.0). The native iOS and Android renderers version independently.

| Component | 5.13.0 |
| - | - |
| **@flowx/angular-sdk** | 11.168.1 |
| **@flowx/angular-theme** | 11.168.1 |
| **@flowx/angular-ui-toolkit** | 11.168.1 |
| **@flowx/react-sdk** | 11.168.1 |
| **@flowx/react-theme** | 11.168.1 |
| **@flowx/react-ui-toolkit** | 11.168.1 |
| **@flowx/react-native-sdk** | 11.168.1 |
| **@flowx/react-native-theme** | 11.168.1 |
| **@flowx/react-native-ui-toolkit** | 11.168.1 |
| **@flowx/core-sdk** | 11.168.1 |
| **@flowx/core-theme** | 11.168.1 |
| **react-saas** | 11.168.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

***

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.13 capabilities. On SaaS they are created and managed automatically.

**Notification center:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |

Notifications now pass through designer-user, which stores them and forwards them to events-gateway on the existing `ai.flowx.eventsgateway.user.notifications.v1` topic for delivery to the Designer.

**Move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

### New services

The Developer Agentic Harness adds the **harness** and **ai-render-host** services to the AI dev-time group, with a dedicated PostgreSQL database for harness sessions. The notification center adds the **designer-user** core service, which uses MongoDB, Redis, and Kafka. On SaaS these services and their databases are provisioned and managed by FlowX.

### New service dependency: process-engine and object storage

Oversized workflow responses and UI flow updates are now offloaded to object storage instead of travelling inline on Kafka. The process engine reads these offloaded payloads, so it now depends on object storage in addition to its existing databases. On SaaS this connection is provisioned and managed by FlowX.

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` | process-engine, audit-core |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Self-hosted deployments receive this change with the next LTS release family. A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.13.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026

What's new in FlowX.AI 5.13: a user notification center in Designer, UI component copy and paste across contexts, commit descriptions on app versions, and move token on process instances.

[FlowX.AI 5.13 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.13.0.html)

> [!NOTE]
>
> **FlowX.AI 5.13 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.13** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. The headline: the FlowX Developer Agentic Harness, an AI agent in the Designer that builds and changes apps from a description, with you confirming the plan and every operation before it runs. The release also adds a notification center to the Designer, lets builders copy and paste UI components across apps with a review of what could not be placed, records a description on every app version commit, forwards runtime events to Mixpanel and GA4, and moves stuck tokens on running process instances.

### What changed since 5.12.0

| 5.12.0 | 5.13.0 |
| - | - |
| Apps were assembled by hand in the Designer | + **Developer Agentic Harness**: describe the change, confirm the plan, review the result on its own branch |
| Long-running operations surfaced as passing toasts | + **Notification center** keeps a searchable 30-day history with read state |
| UI components copied within one context | + **Copy and paste across contexts**, with a paste review and unique naming |
| App version commits had a name only | + **Commit descriptions** and a commit details view record why a version exists |
| A stuck process instance needed support intervention | + **Move token** relocates the token, guarded by a dedicated corrective-actions role |

***

**What's new?**

> [tab] Builders
>
> 🔔 [**User notification center**](#user-notification-center) - Bell, searchable history, read state in Designer\
> 📋 [**UI component copy and paste**](#ui-component-copy-and-paste) - Cross-context paste with review and unique naming\
> 📝 [**Commit descriptions and details**](#commit-descriptions-and-details) - Optional description on version commits plus a details view\
> 📦 [**Version export alignment**](#version-export-alignment) - Version exports bundle dependencies like build exports

> [tab] Platform
>
> 🚑 [**Move token and corrective actions**](#move-token-and-corrective-actions) - Relocate a token, gated by a dedicated role

> [tab] AI Platform
>
> 🪄 [**Developer Agentic Harness**](#developer-agentic-harness) - Describe a change, the agent plans and builds it on a branch\
> 🧠 [**ML corpus import and export**](#ml-corpus-import-and-export) - Move a document classifier corpus between environments\
> ⚖️ [**Fair scheduling for embedding jobs**](#fair-scheduling-for-embedding-jobs) - Knowledge Base ingestion no longer starves small jobs\
> 🧩 [**Data Parse node**](#data-parse-node) - Tabular Data Extraction generalized, now parses XML and JSON\
> 🔐 [**File Encryption node**](#file-encryption-node) - Encrypt and decrypt files inside a workflow

> [tab] Rendering & SDKs
>
> 💬 [**React Native chat component**](#react-native-chat-component) - Floating chat sheet with voice input on mobile\
> ▶️ [**Conditional start workflow trigger**](#conditional-start-workflow-trigger) - Start a workflow from the UI only when a condition holds

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > **Before 5.13.0:** every process, screen, and data type was assembled by hand in the Designer. **Now:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys your app first, so changes use your real resources and names, then drafts a plan for you to confirm.
> >
> > You hold every gate: the agent runs only after you confirm the plan and review each operation, the change lands on a dedicated branch that never touches your main line, and merging plus serving a new version stay human decisions. See the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness) page for the full flow.
> >
> > <video>
> >   <track label="English" />
> > </video>
>
> > [tab] Key Features
> >
> > > [card] Works on your real app
> > >
> > > Surveys existing resources first, so changes use your actual processes, data types, and names.
> >
> > > [card] Plan, confirm, then run
> > >
> > > You confirm the plan and review every operation; the change runs on a dedicated branch that only you can merge or serve.
> >
> > > [card] Broad resource coverage
> > >
> > > Creates and edits processes, UI flows, workflows, and project data types.
> >
> > > [card] Guarded operations
> > >
> > > Destructive changes are gated, and runtime data such as process instances is never touched.
>
> SaaS

### **User notification center**

> [card] User notification center
>
> > [tab] Overview
> >
> > **Before 5.13.0:** long-running operations such as app imports or instance migrations announced themselves once and were gone. **Now:** a bell in the Designer opens a notification center with a 30-day history.
> >
> > Notifications carry read state, search, and filters by unread status and workspace type. First producers: app version export and process instance migration results.
>
> > [tab] Key Features
> >
> > > [card] 30-day history
> > >
> > > Notifications persist for 30 days instead of disappearing with the toast.
> >
> > > [card] Read state and search
> > >
> > > Mark notifications read, search them, and filter by unread status or workspace type.
> >
> > > [card] Export and migration results
> > >
> > > Get notified when an app version export finishes, fails, or times out, and when a process instance migration completes.
> >
> > > [card] Live updates
> > >
> > > The center updates over a live stream, including read state changes from other sessions.
>
> SaaS

### **UI component copy and paste**

> [card] UI component copy and paste
>
> > [tab] Overview
> >
> > **Before 5.13.0:** copying UI components was limited to the context you were in. **Now:** builders copy components and paste them into another UI Flow, app, or context.
> >
> > Pasting responds with a review of what could not be placed instead of failing silently, and pasted components receive unique names automatically. The clipboard holds one consistent version of the copied structure.
>
> > [tab] Key Features
> >
> > > [card] Cross-context paste
> > >
> > > Paste a copied component into a different UI Flow or app through a dedicated modal.
> >
> > > [card] Paste review
> > >
> > > The paste result names anything it could not place, so nothing drops without a trace.
>
> SaaS

### **Commit descriptions and details**

> [card] Commit descriptions and details
>
> Committing or merging an app version now takes an optional description of up to 2000 characters, and a commit details view shows what a version contains and why it exists. Version history stops being a list of names.
> SaaS

### **Version export alignment**

> [card] Version export alignment
>
> Project version exports now bundle dependencies the same way build exports do, so a version export is self-contained. The export dialog pre-selects the target platform version, and the exported filename carries the target version and whether media is included.
> SaaS

### **Move token and corrective actions**

> [card] Move token and corrective actions
>
> > [tab] Overview
> >
> > **Before 5.13.0:** a process instance stuck on the wrong node needed support intervention. **Now:** an operator with the corrective-actions role moves the token to the right node from Runtime.
> >
> > Corrective actions, covering bulk instance migration and move token, are gated by a dedicated workspace-level role, so admins grant this power without handing out full admin rights.
> >
> > The **Workspace corrective actions editor** role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically. See [Move tokens](/5.9/docs/projects/runtime/active-process/move-token) and the [Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
>
> > [tab] Key Features
> >
> > > [card] Move token
> > >
> > > Relocate the token of a running instance to another node in the process definition.
> >
> > > [card] Dedicated role
> > >
> > > A workspace-level corrective-actions role scopes who can migrate instances and move tokens.
>
> SaaS

### **ML corpus import and export**

> [card] ML corpus import and export
>
> A document classifier corpus now moves between environments: export the corpus with the model, import it into a runtime classifier, and inspect it in a read-only view in the Data tab. Training data stops being trapped in the environment where labeling happened.
> SaaS

### **Fair scheduling for embedding jobs**

> [card] Fair scheduling for embedding jobs
>
> Knowledge Base embedding jobs are scheduled fairly by default, so a large ingestion no longer starves small jobs queued behind it. Uploads to one Knowledge Base stop delaying every other one on the environment.
> SaaS

### **Data Parse node**

> [card] Data Parse node
>
> The Tabular Data Extraction node is generalized into a **Data Parse** node: it still reads CSV and Excel files into workflow data, and now also parses **XML** and **JSON**. A file fetched by a File Storage Operation can be read into the workflow regardless of its structured format.
> SaaS

### **File Encryption node**

> [card] File Encryption node
>
> A new **File Encryption** workflow node encrypts or decrypts a file with a password directly in the workflow, so protecting a generated document or opening a protected upload no longer needs a custom integration. The file path and password take expressions, letting the password come from workflow data.
> SaaS

### **React Native chat component**

> [card] React Native chat component
>
> The React Native renderer gains the chat experience mobile apps were missing: a floating chat sheet with voice input, suggested prompts, and conversation history. Renderer updates in the same release cover form validation on navigation actions, action context on execute-URL, and bulk enum fetching on eager load.
> SaaS

### **Conditional start workflow trigger**

> [card] Conditional start workflow trigger
>
> A start workflow trigger in the UI now takes a condition, so the workflow starts only when the expression holds. Available in the web SDK and on iOS.
> SaaS

### **Smaller improvements**

> [card] Smaller improvements
>
> **Process details modal:** the process name moves from Settings into a Details modal.
>
> **Document and image sources:** Document and Image UI components share one source configuration. In process user tasks, the new **Document Plugin Path** source takes a Documents plugin `downloadPath` directly, so you no longer need a business rule to build the file URL. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13) for File Preview and the [Download component](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download#file-sources-in-flowx-ai-5-13).
>
> **Sign-up link to solution:** a sign-up link lands new users directly in the right solution.
>
> **Bulk invite:** inviting many users at once gets a reworked flow.
>
> **Task list search on translated labels:** the task list searches, filters, and sorts on the labels it displays, in the viewer's language, for status, enumeration, and substitution-tag columns. See [Search and sort on translated labels](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).&#x20;
>
> **Reserved substitution-tag prefix:** custom substitution tags can no longer start with `sys_`; the prefix is reserved for system tags.&#x20;
> **Intersects operator for array fields:** FlowX Database queries can match documents whose array field shares at least one value with a given list. See [Intersects on array fields](/5.9/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).&#x20;
>
> **Request after PII anonymization in the run log:** AI nodes with the input scan enabled log the request exactly as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/5.9/ai-platform/personal-information-guard#request-after-pii-anonymization).&#x20;
>
> **Elasticsearch replica auto-expansion:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Changed default: Elasticsearch replica auto-expansion](./deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).&#x20;
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.13.0](./deployment-guidelines-v5.13).


# FlowX.AI 5.9.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including expanded audit logging, copy-with-roles, and the app-manager organization-ID migration fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.1 → 5.9.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.2** is a maintenance release for the 5.9.x LTS. It pairs a broad bug-fix pass with a few targeted improvements:
>
> * **Expanded audit logging:** coverage for sharing, invitations, user and group management, and process-instance and UI-flow actions
> * **Copy with roles:** copying a resource now also copies its associated roles
> * **Self-hosted upgrade fixes:** smoother installation and upgrade from 5.1.x on self-hosted environments
> * **Key fixes:** active-policy override user list, project-version merge, reusable UI templates in nested containers, and audit-log user filtering&#x20;
> * Wide set of Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.9.2 brings bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions.\
> 👥 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, and backend bug fixes plus security patches.
>
> ***
>
> ### **Expanded audit logging**
>
> > [card] Broader audit coverage for access and lifecycle actions
> >
> > Audit logging now records a wider set of actions, including **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> > All Deployments
>
> ***
>
> ### **Copy with roles**
>
> > [card] Roles travel with copied resources
> >
> > Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Reusable UI templates:** fixed actions missing at runtime when a template is nested in multiple levels of containers.&#x20;
> > > > * **Use in reporting:** the reporting toggle is now available on UI flows and workflows, matching the existing process setting.
> > > > * **UI action keys:** keys to save for collection items and bundled custom-component inputs are now computed automatically, and mapped object keys for collections and custom components are available in runtime data.&#x20;
> > > > * **SQL data sources:** queries on SQL data sources can now be tested from the builds list, mirroring the existing NoSQL runtime test flow.&#x20;
> > > > * **Event handlers:** the Event Handlers section now appears higher in the component configuration panel.&#x20;
> > > > * **Audit logs:** filtering audit entries by user now works when the username differs from the email address.&#x20;
> > > > * **AI agents and data models:** AI Designer and AI Developer now use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it. &#x20;
> > >
> > > > [accordion] Renderer fixes
> > > >
> > > > * **Chat:** the floating chat position is now calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.&#x20;
> > > >
> > > > This release also includes stability fixes across the web, React, React Native, Android, and iOS renderers.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * **Active policy:** fixed the user list appearing empty on the override active-policy form.&#x20;
> > > > * **Project version merge:** fixed a 500 error that could occur during project-version merge.&#x20;
> > > > * **CMS enumerations:** cascading-enum value lookups now resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.&#x20;
> > > > * **Build export with media files:** exporting a build with media file content included now produces an archive that actually contains the binaries.&#x20;
> > > > * **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.&#x20;
> > > > * **Redis Cluster:** UI-template cache keys are now hash-tagged so related keys map to the same cluster slot, preventing cross-slot errors on Redis Cluster deployments.&#x20;
> > > > * **Workflow data:** Mongo partition archiving now batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine was fixed. See [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) for the partitioning and archiving settings.&#x20;
> > > > * **Data sync with private CA certificates:** the data-sync job now runs the same certificate-initialization step as the other platform services, so data-sync migrations that call HTTPS endpoints (such as Keycloak) no longer fail certificate validation in environments using an internal certificate authority.&#x20;
> > > > * **Self-hosted installation and upgrade:** fixed Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding on self-hosted environments. As part of this, the migration-created default end-user group is renamed from `User` to `Users Group`; check the upgrade warning under Additional information if you map IDP groups into FlowX.&#x20;
> > > > * **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.&#x20;
> > > > * **AI workflow nodes:** JSON schema fields now support `${}` placeholders.&#x20;
> > > > * **Multi-KB retrieval:** retrieval can span multiple knowledge bases in a workflow.&#x20;
> > > > * **AI structured output:** responses from AI nodes with a response schema are now validated against it, with automatic repair retries, and node logs include richer run diagnostics such as the failure reason and rejected output.&#x20;
> > > > * **Document Parser:** a new LiteParse engine parses PDFs and images fully locally without GPU or AI calls, and OCR language support expands to English, Romanian, Hungarian, and Bulgarian.&#x20;
> > > > * **Knowledge bases:** a Custom Agent node can now select multiple knowledge bases, each exposed to the agent as its own retrieval tool, replacing the parallel-nodes workaround.&#x20;
> > > > * **Chat file uploads:** end users can attach multiple files in a chat-driven app; uploads are indexed into a knowledge base scoped to the chat session so AI nodes answer grounded in that content.&#x20;
> > > > * **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.&#x20;
> > > >
> > > > This release also includes a broad set of additional fixes and stability improvements across Designer and backend services.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.2 is fully compatible with 5.9.1; standard deployment procedures apply. One migration renames a default end-user group, which needs attention only if group membership is mapped from Keycloak or an external IDP (see the warning below).
>
> > [!WARNING]
> >
> > **Default end-user group renamed from `User` to `Users Group`.** The group that the 5.1.x upgrade migration creates for users who held the `FLOWX_ROLE` realm role is renamed from `User` to `Users Group` when you upgrade to 5.9.2 or any later release. Runtime group matching is by exact name: if a Keycloak **Group Membership** mapper or an external IDP claim emits the old name `User` into `attributes.runtimeGroups`, those values no longer match any FlowX group and affected users **lose solution access on their next sign-in, with no error logged**. Update the mapper or source group name to `Users Group` as part of the upgrade. Groups your admins created themselves, including any you named `User`, are not renamed. See the [runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) setup for where this value is configured.
>
> > [!WARNING]
> >
> > **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration so it converts existing data correctly. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and actually converts your data. If you did not apply that workaround, no action is needed.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.1 → 5.9.2 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.2 are tracked in the [5.9.2 deployment guidelines](./deployment-guidelines-v5.9.2).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3

Component versions, configuration, and deployment notes for FlowX.AI 5.9.3 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.3 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.2 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.2 → 5.9.3**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.0 or 5.9.1 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.165.0 | 10.162.1 | 10.135.0 | 10.106.0 | 9.76.3 |
| **admin** | 10.144.0 | 10.141.1 | 10.116.0 | 10.93.0 | 9.76.3 |
| **designer** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **cms-core** | 10.105.0 | 10.102.3 | 10.86.0 | 10.67.0 | 9.47.3 |
| **scheduler-core** | 10.87.0 | 10.85.1 | 10.70.0 | 10.53.0 | 9.36.3 |
| **events-gateway** | 10.93.0 | 10.90.1 | 10.72.0 | 10.55.0 | 9.37.3 |
| **notification-plugin** | 10.103.0 | 10.100.2 | 10.83.0 | 10.64.0 | 9.40.3 |
| **document-plugin** | 10.116.0 | 10.113.2 | 10.94.0 | 10.75.0 | 9.45.3 |
| **task-management-plugin** | 10.105.0 | 10.102.1 | 10.84.0 | 10.66.0 | 9.44.4 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.85.0 | 10.83.1 | 10.69.0 | 10.52.0 | 9.33.3 |
| **audit-core** | 10.95.0 | 10.93.1 | 10.79.0 | 10.63.0 | 9.41.3 |
| **advancing-controller** | 10.91.0 | 10.89.1 | 10.73.0 | 10.55.0 | 9.36.3 |
| **integration-designer** | 10.192.0 | 10.189.2 | 10.162.0 | 10.128.0 | 9.60.3 |
| **application-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **runtime-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **data-sync** | 10.100.0 | 10.98.0 | 10.81.0 | 10.58.0 | 9.34.2 |
| **authorization-system** | 10.115.0 | 10.112.1 | 10.96.1 | 10.77.0 | 9.44.4 |
| **nosql-db-runner** | 10.94.0 | 10.92.1 | 10.75.0 | 10.56.0 | 9.32.3 |
| **email-gateway** | 10.93.0 | 10.91.1 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.90.0 | 10.88.1 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.62.0 | 10.60.1 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.25.0 | 10.23.1 | 10.8.0 | - | - |
| **license** | 10.80.0 | 10.78.1 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-native-sdk** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/core-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **react-saas** | 10.265.6 | 10.260.7 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.11 | 10.5.6 | 10.4.1 | 10.3.0 | 9.0.27 |
| **Android renderer** | 10.6.6 | 10.5.6 | 10.5.0 | 10.3.0 | 9.0.37 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](../v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.1 | 10.9.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.1 | 10.9.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.1 | 10.9.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.1 | 10.9.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.1 | 10.9.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.1 | 10.9.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.27.0 | 10.25.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.1 | 10.9.0 | - | - | - |
| **ai-assistant** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.1 | 10.9.0 | - | - | - |
| **flowx-docs** | 5.9.3 | 5.9.2 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.3 introduces no new Kafka topics over 5.9.2. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.3 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Events Gateway — Redis connection pool for blocking mode

The Events Gateway's blocking read path is rebuilt on a dedicated Redis connection pool, fixing a connection leak that could previously require periodic Events Gateway restarts under sustained load. The new settings ship with working defaults — no action is required on upgrade.

| Environment variable | Default | Change in 5.9.3 |
| - | - | - |
| `EVENTS_REDIS_POOL_ENABLED` | `true` | New — dedicated connection pool for blocking reads |
| `EVENTS_REDIS_POOL_MAXTOTAL` | `50` | New — maximum pooled connections |
| `EVENTS_REDIS_POOL_MAXIDLE` | `50` | New — maximum idle pooled connections |
| `EVENTS_REDIS_POOL_MINIDLE` | `5` | New — minimum idle pooled connections |
| `EVENTS_REDIS_POOL_MAXWAITMILLIS` | `5000` | New — wait time for a pooled connection before failing |
| `EVENTS_REDIS_SSE_BUFFERSIZE` | `256` | New — per-subscriber SSE backpressure buffer |
| `EVENTS_REDIS_BLOCKDURATIONSECONDS` | `1` | Default lowered from `5` — shortens the blocking-read reissue interval |

If you previously set `EVENTS_REDIS_BLOCKDURATIONSECONDS` explicitly, review whether the new default suits your setup. See the [Events Gateway setup guide](/5.9/setup-guides/events-gateway-setup#events) for the full configuration reference.

#### Integration Designer — workflow topic partitions

`FLOWX_WORKFLOW_TOPICPARTITIONS` (default `1`) sets the number of partitions for auto-created workflow Kafka topics (used with `FLOWX_WORKFLOW_CREATETOPICS`). Existing topics are not modified; the setting applies to newly created topics only.&#x20;

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including the Events Gateway Redis connection-leak fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.2 → 5.9.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.3** is a maintenance release for the 5.9.x LTS:
>
> * **Real-time event delivery:** fixes a Redis connection leak in the Events Gateway that could previously require periodic restarts under sustained load
> * **Key fixes:** build import race during multi-dependency imports, task-management allocation rules, project re-creation error handling
> * **New configuration:** Events Gateway connection-pool tuning and workflow Kafka topic partitions
> * Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.2

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform improvements**](#platform-improvements) - Events Gateway stability, Designer and backend bug fixes, security patches.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Real-time event delivery:** fixed a Redis connection leak in the Events Gateway. Blocking reads now run on a dedicated connection pool with Redis Cluster support, eliminating the gradual connection buildup that could previously require periodic Events Gateway restarts. New tuning options are available — see the [deployment guidelines](./deployment-guidelines-v5.9.3#configuration-changes).
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it, and duplicate rules are no longer created when Save is clicked twice. Task views also no longer reset when the same view is open from different workspaces.&#x20;
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **Designer stability:** fixed a freeze when opening Runtime after expanding a component's Permissions section, and a pending AI UI-generation draft no longer locks the process diagram read-only.&#x20;
> > > > * **Date Picker:** the calendar now anchors correctly to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.&#x20;
> > > > * **Workflows:** fixed a silent workflow freeze that could occur after a step exhausted its retries.&#x20;
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior. UI Flows on iOS also gain support for the `additionalData` object.
> > > >   &#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Media Library:** PDF assets in the list can now be opened in a new tab directly from the Media Library.
> > > > * **Process start loading:** web renderers now keep the loading indicator visible until the first user task renders, matching the mobile SDK behavior.&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.3 is fully compatible with 5.9.2. No configuration changes are required on upgrade; new tuning options ship with working defaults.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.2 → 5.9.3 with no breaking changes
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps are required for this maintenance release. Upgrading directly from 5.9.0 or 5.9.1? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.3](./deployment-guidelines-v5.9.3).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4

Component versions, configuration, and deployment notes for FlowX.AI 5.9.4 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.4 is a maintenance release for the 5.9.x LTS line. The platform upgrade from 5.9.3 is non-breaking, but this release changes how the Helm charts express the container image location, so review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.3 → 5.9.4**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Helm values change.** The charts now express the image location as `image.registry` plus `image.repository` instead of one combined path. Deployments that set `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move it out before upgrading — see [Helm charts: image registry split](#helm-charts-image-registry-split).

> [!NOTE]
>
> **Upgrading from 5.9.0, 5.9.1, or 5.9.2 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.171.3 | 10.165.0 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.149.3 | 10.144.0 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.110.4 | 10.105.0 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.91.2 | 10.87.0 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.97.2 | 10.93.0 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.107.4 | 10.103.0 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.121.3 | 10.116.0 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.109.3 | 10.105.0 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.89.2 | 10.85.0 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.99.2 | 10.95.0 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.95.2 | 10.91.0 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.197.5 | 10.192.0 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.104.3 | 10.100.0 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.119.3 | 10.115.0 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.98.2 | 10.94.0 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.98.2 | 10.93.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.95.2 | 10.90.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.66.2 | 10.62.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.30.2 | 10.25.0 | 10.8.0 | - | - |
| **license** | 10.84.2 | 10.80.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.275.0 | 10.265.6 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.0 | 10.5.11 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.8.0 | 10.6.6 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.2 | 10.9.1 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.10.2 | 10.9.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.10.2 | 10.9.1 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.10.2 | 10.9.1 | 10.1.1 | - | - |
| **speech-to-text** | 10.10.2 | 10.9.1 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.10.2 | 10.9.1 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.32.2 | 10.27.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.10.2 | 10.9.1 | - | - | - |
| **ai-assistant** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.10.2 | 10.9.1 | - | - | - |
| **flowx-docs** | 5.9.4 | 5.9.3 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.4 introduces no new Kafka topics over 5.9.3. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Apply the Helm values change described in [Configuration changes](#configuration-changes), if it affects your setup.
2. Update container images to the 5.9.4 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Helm charts: image registry split

Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.

```yaml theme={"dark"}
# Before
image:
  repository: <registry>/<image-name>

# After
image:
  registry: <registry>
  repository: <image-name>
```

The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.

**Upgrade notes**

* **If you set `global.imageRegistry` to point the charts at your own registry** (the standard, documented approach): no action is required. Your override continues to work, and it now applies cleanly to the default bare repository names.
* **If you embedded the registry inside `image.repository`** (for example `image.repository: harbor.mycorp.internal/flowx/<image-name>`): move the registry portion out. Set it through `global.imageRegistry`, or the chart's `image.registry`, and let `image.repository` fall back to its default bare image name. Leaving the registry in `image.repository` alongside the now-populated `image.registry` prepends the registry twice.

  This applies to deployments configured from the FlowX setup guides before 5.9.4, which showed the combined form. If your values files were built from those examples, check them before upgrading.

#### Events Gateway service account

Events Gateway now authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`, in the service-accounts realm. It needs this identity to resolve and authorize a subscription before admitting the stream.

Two new configuration values are involved, and both take the **same secret**:

| Service | Environment Variable | Purpose |
| - | - | - |
| authorization-system | `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXEVENTSGATEWAYSA` | Secret the migration assigns to the client it creates |
| events-gateway | `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Secret Events Gateway authenticates with |

**Upgrade notes**

* **If you deploy with the FlowX Helm charts and authorization-system runs its migrations with Keycloak admin access**: no action is required. The chart already maps both values to the `KEYCLOAK_EVENTS_GATEWAY_CLIENT_SECRET` key of the `keycloak-flowx-realm-clients` secret, and the authorization-system migration creates the client and grants it the `SA_FLOWX` role.
* **If you manage Keycloak clients outside the chart** (external IdP, or authorization-system cannot provision clients): create `flowx-events-gateway-sa` in the service-accounts realm as a confidential client with service accounts enabled and only the client-credentials grant, then supply its secret to both values above.

> [!WARNING]
>
> If `flowx-events-gateway-sa` already exists, the migration leaves its secret untouched by design. A pre-existing client whose secret does not match the one given to Events Gateway will not be corrected on upgrade, and Events Gateway will fail to authorize subscriptions. Make the two match manually in that case.

#### Liquibase migration lock moves to database session locks

The lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so a stale `databasechangeloglock` row no longer needs clearing by hand. On any other database, Liquibase falls back to its standard row-based lock.

The previous mechanism verified the lock-holder pod through the Kubernetes API. That dependency is gone:

* Service accounts no longer need the `get pods/status` permission, and the FlowX Helm charts no longer create the corresponding Role and RoleBinding. If you maintain that RBAC outside the charts, you can remove the grant.
* The lock keeps working on Kubernetes 1.33 and newer, where the previous mechanism silently deactivated itself.

**Oracle deployments** must grant each FlowX service's database user the following before upgrading. A service whose grants are missing stops at startup with an error naming the missing grant:

```sql theme={"dark"}
GRANT EXECUTE ON SYS.DBMS_LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$SESSION TO <app_user>;
```

PostgreSQL deployments need no action: advisory locks require no additional grant.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, the Angular 21 renderer upgrade, and a Helm chart image-registry change.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. The platform upgrade from **5.9.3 → 5.9.4** requires no data migration, but it does change how the Helm charts express the container image location. Review the [deployment guidelines](./deployment-guidelines-v5.9.4#configuration-changes) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.4** is a maintenance release for the 5.9.x LTS:
>
> * **Helm charts:** the container image reference splits into `image.registry` and `image.repository`, making `global.imageRegistry` a single chart-wide override
> * **Angular 21:** the Angular renderer and the web SDKs move to Angular 21
> * **Key fixes:** branch merges no longer getting stuck, build export retry after a dependency timeout, deleting actions that call functions, gateway expression failures surfaced as incidents, library resource overview
> * **Cross-version import:** an imported theme is completed from the destination's system theme, so nothing is missing after importing an older export
> * Designer, renderer, and backend stability fixes plus security patches
> * No data migration; the only upgrade action is the Helm values change, and only for one override pattern

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, plus a Helm chart change that affects some self-hosted deployments.
>
> 📦 [**Helm chart image registry**](#helm-chart-image-registry) - `image.repository` splits into `image.registry` + `image.repository`\
> 🅰️ [**Angular 21**](#angular-21) - The Angular renderer and web SDKs move to Angular 21\
> 🔧 [**Platform improvements**](#platform-improvements) - Bug fixes and security patches
>
> ***
>
> ### **Helm chart image registry**
>
> > [card] image.repository splits into image.registry + image.repository
> >
> > Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.
> >
> > ```yaml theme={"dark"}
> > # Before
> > image:
> >   repository: <registry>/<image-name>
> >
> > # After
> > image:
> >   registry: <registry>
> >   repository: <image-name>
> > ```
> >
> > The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.
> >
> > > [!WARNING]
> > >
> > > **Check your values files before upgrading.** If you set `global.imageRegistry`, no action is needed. If you embedded the registry inside `image.repository`, move it out first, or the registry is prepended twice. This includes values files built from the FlowX setup guides before 5.9.4, which showed the combined form. Full before-and-after in the [deployment guidelines](./deployment-guidelines-v5.9.4#helm-charts-image-registry-split).
> >
> > All Deployments
>
> ***
>
> ### **Angular 21**
>
> > [card] Angular renderer and web SDKs on Angular 21
> >
> > The Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps embedding the Angular SDK should be on Angular 21 before taking 5.9.4.
> >
> > Angular does not support skipping a major in a single update, so step through the official update guide one major at a time. The **npm** and **node** requirements are unchanged from 5.9.3.
> >
> > See the [Angular SDK requirements](/5.9/sdks/angular-renderer#angular-project-requirements) for the current version floor, and the [Angular migration guide](/5.9/migrating-from-5.1-lts/angular#framework-upgrade-angular-19-→-21) for the upgrade path.
> >
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build export:** retrying a build export now re-attempts a dependency library whose own export ended in a timeout, instead of failing again immediately. Previously the retry skipped the timed-out dependency, so the parent build could never finish; the workaround was to export that dependency directly first.&#x20;
> > > > * **Actions:** deleting an action whose business rule calls a function now works instead of returning a server error. This affected any action at any nesting level, in both projects and libraries; the workaround was to delete the rule from the action first.&#x20;
> > > > * **Gateways:** an expression that fails to evaluate on an exclusive gateway now surfaces as an incident on the process instance. Previously the failure appeared only in the service logs, with no feedback in the platform.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection. Changing the page size no longer opens the wrong process from the list. &#x20;
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives while a background synchronization is still running, and merging versions no longer fails with a navigation-areas error.&#x20;
> > > > * **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds. The page index was previously lost on back-navigation.&#x20;
> > > > * **Reusable UI templates:** static input mappings configured on a reusable template are now applied at runtime.&#x20;
> > > > * **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.&#x20;
> > > > * **Entry points:** the entry-point picker in version settings now lists only processes and UI flows from the current project. Resources from dependency libraries were previously offered and could be selected.&#x20;
> > > > * **Themes and CMS resources:** exporting a theme no longer includes duplicate non-system copies of system icons, so repeated imports stop multiplying them, and importing no longer leaves system substitution tags missing.&#x20;
> > > > * **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output built from trailing empty cells and rows.&#x20;
> > > > * **Generated documents:** a document whose storage write fails now returns an error instead of being recorded as successful with a download path that cannot be opened. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.&#x20;
> > > > * **Renderers:** the document preview shows its subtitle again, and the file-upload error message picks up the configured theme.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Cross-version import:** importing a project build or version exported from an older platform line now completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten, so customizations survive.&#x20;
> > > > * **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.&#x20;
> > > > * **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.&#x20;
> > > > * **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.&#x20;
> > > > * **Integration Designer performance:** service startup no longer scans the full token-instance collection to warm up, and the run-list summary queries are indexed and gated.&#x20;
> > > > * **Database migrations:** the lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so there is no stale `databasechangeloglock` row to clear by hand. The previous mechanism recovered a stuck lock through the Kubernetes API, which required the `pods/status` permission on every service account and silently deactivated on Kubernetes 1.33 and newer. Oracle deployments need new database grants before upgrading: see the [deployment guidelines](./deployment-guidelines-v5.9.4#liquibase-migration-lock-moves-to-database-session-locks).&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade compatibility:** FlowX.AI 5.9.4 is compatible with 5.9.3. No data migration is required. One deployment-level change applies: the Helm charts split the image reference into `image.registry` and `image.repository`. Oracle deployments also need new database grants for the Liquibase migration session lock.
>
> > [!WARNING]
> >
> > **Helm values migration.** Deployments that redirect images through `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move the registry portion out before upgrading. See [Configuration changes](./deployment-guidelines-v5.9.4#configuration-changes).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Direct upgrade from 5.9.3 → 5.9.4. No data migration; review the Helm values change first.
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. The Angular SDK moves to Angular 21.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.4](./deployment-guidelines-v5.9.4).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5

Component versions, configuration, and deployment notes for FlowX.AI 5.9.5 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.5 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.4 is non-breaking and requires no data migration. The headline addition, native PostgreSQL partitioning, is opt-in: deployments that never enabled data partitioning are not affected. Review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.4 → 5.9.5**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.3 or earlier directly?** Review the [5.9.4 deployment guidelines](../v5.9.4-august-2026/deployment-guidelines-v5.9.4) first: the Helm image registry split applies when you skip 5.9.4. Upgrading from 5.9.0, 5.9.1, or 5.9.2, also review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) for the organization-ID migration fix and manually marked Liquibase changesets.

## Component versions

### Core components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.10 | 10.171.3 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.7 | 10.149.3 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.7 | 10.110.4 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.6 | 10.91.2 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.100.7 | 10.97.2 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.110.7 | 10.107.4 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.7 | 10.121.3 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.6 | 10.109.3 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.6 | 10.89.2 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.6 | 10.99.2 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.7 | 10.95.2 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.200.9 | 10.197.5 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.7 | 10.104.3 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.7 | 10.119.3 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.6 | 10.98.2 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.101.6 | 10.98.2 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.6 | 10.95.2 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.6 | 10.66.2 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.7 | 10.30.2 | 10.8.0 | - | - |
| **license** | 10.87.6 | 10.84.2 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB**: see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.282.5 | 10.275.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.2 | 10.6.0 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.9.3 | 10.8.0 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.0 | 10.10.2 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.0 | 10.10.2 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.0 | 10.10.2 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.0 | 10.10.2 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.0 | 10.10.2 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.0 | 10.10.2 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.6 | 10.32.2 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.0 | 10.10.2 | - | - | - |
| **ai-assistant** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.0 | 10.10.2 | - | - | - |
| **flowx-docs** | 5.9.5 | 5.9.4 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.5 introduces no new Kafka topics over 5.9.4. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Review [Configuration changes](#configuration-changes): everything new in this release is opt-in or ships with a safe default, so no values change is required for a standard upgrade.
2. Update container images to the 5.9.5 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Native PostgreSQL partitioning (opt-in)

Process-instance archiving on PostgreSQL can now use native declarative partitions instead of the legacy copy-based mechanism. Data partitioning itself remains **off by default** (`FLOWX_DATA_PARTITIONING_ENABLED` is `false`), so deployments that never enabled it are not affected.

New process-engine variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Use native PostgreSQL partitions for archiving when partitioning is enabled. PostgreSQL only; other databases keep the existing mechanism. | `true` |
| `FLOWX_DATA_PARTITIONING_PREMAKECRONEXPRESSION` | Schedule for the job that creates upcoming partitions in advance. | `0 0 23 * * ?` |
| `FLOWX_DATA_PARTITIONING_PREMAKEPARTITIONSAHEAD` | How many future partitions the job keeps created ahead of the current one. | `2` |

> [!WARNING]
>
> Enabling native partitioning converts the process-instance tables to partitioned tables, and the conversion is one way: there is no supported path back to unpartitioned tables. Review the [partitioning and archiving setup guide](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning) before turning it on.

#### Document plugin: processing size limits

The document plugin now enforces size limits on archive, encryption, and extraction operations. Input over the limit is rejected instead of processed. The defaults are generous; override them only if your documents legitimately exceed them.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOCUMENT_ARCHIVE_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for archive operations. | `209715200` (200 MB) |
| `DOCUMENT_ENCRYPTION_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for encryption. | `104857600` (100 MB) |
| `DOCUMENT_EXTRACT_MAX_UNCOMPRESSED_SIZE` | Maximum total uncompressed size, in bytes, an archive may expand to during extraction. | `209715200` (200 MB) |

#### Integration Designer: workflow output size guard

Workflow output published to Kafka is now size-checked before sending. A root workflow output that exceeds the limit fails the workflow run with the failure type `outputTooLargeForKafka` instead of being silently dropped by the broker's message-size limit. The check applies to root workflow outputs on automatic and default-path completion; subworkflow outputs are not checked.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_KAFKA_PAYLOAD_SIZE_LIMIT` | Maximum serialized size, in bytes, of a root workflow output published to Kafka. | `786432` |

> [!TIP]
>
> Keep this limit below your broker's `max.message.bytes`. The default, 768 KB, sits safely under the common 1 MB broker default.

#### Advancing datasource metrics

The process engine and Integration Designer now register their advancing datasource under a named connection pool (`advancing`), so its metrics are distinguishable from the main datasource pool in Prometheus. No configuration action is required.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026

Maintenance release for the 5.9.x LTS line. Native PostgreSQL partitioning for process data, bug fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. It also brings native PostgreSQL partitioning to process data. Review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.5** is a maintenance release for the 5.9.x LTS:
>
> * **Native PostgreSQL partitioning:** process data tables are partitioned by the database itself, so removing old data becomes a partition drop instead of a bulk delete
> * **Key fixes:** audit entries no longer missing or attributed to the wrong application, merge conflicts raised for changes inside embedded subprocesses, self-hosted Keycloak issuer derived from configuration
> * **Integrations:** an SFTP private key can be stored as a multi-line PEM
> * Backend, Designer, and renderer stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.5 is compatible with 5.9.4, and the upgrade requires no data migration. Native PostgreSQL partitioning is opt-in: if you had already enabled data partitioning, review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade, because the conversion to native partitions runs automatically for you and is one way.

**Before you upgrade, check these:**

* **AI job queues:** each AI service now consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group, and the new groups read only jobs published after they start. Wait until the `ai-services` group has no lag on the job topics before you upgrade, so no queued job is skipped. If your cluster restricts consumer groups with ACLs, allow the new groups first.
* **Relational data sources:** Oracle data sources connect only to hosts that resolve to a public address. Add private database hosts to the allowlist, as described in [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Service-account secrets:** confirm every service-account client secret is set on `authorization-system`, or the service stops at startup. The secrets are listed in the [Authorization setup guide](/5.9/setup-guides/authorization-setup-guide).
* **Dashboards and alerts:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total`.
* **Runtime log levels:** the `loggers` actuator endpoint is no longer exposed by default. Add it back as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Data partitioning:** if you had already turned on data partitioning, the conversion to native partitions runs automatically on upgrade and is one way. See the [deployment guidelines](./deployment-guidelines-v5.9.5).

**Upgrade path:** direct upgrade from 5.9.4. Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. Component versions are listed in the [5.9.5 deployment guidelines](./deployment-guidelines-v5.9.5).

***

## Native PostgreSQL partitioning

The process engine stores process data in tables that PostgreSQL itself partitions by time. Retention then
works by dropping whole partitions rather than deleting rows one at a time, which keeps the cost of
removing old data flat as the tables grow.

This is the same partitioning model described for the 5.12 line, delivered into the 5.9.x LTS.

For how partitioning interacts with archiving and retention, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving).

***

## Full changelog

### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.&#x20;
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](#native-postgresql-partitioning).&#x20;

### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.&#x20;
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.&#x20;
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.&#x20;
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.&#x20;
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.&#x20;
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.&#x20;
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.&#x20;
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](./deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).&#x20;
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](./deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).&#x20;
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).&#x20;
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).&#x20;
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.&#x20;
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.&#x20;

### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.&#x20;
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.&#x20;
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.&#x20;
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.&#x20;
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.&#x20;
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.&#x20;
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.&#x20;
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.&#x20;
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.&#x20;
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.&#x20;
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# Deployment guidelines v5.9.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6

Component versions, configuration, and deployment notes for FlowX.AI 5.9.6 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.6 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.5 adds one Kafka topic, a database table, and a MongoDB index. The table and the index are created automatically when the services start. Review [Kafka topics](#kafka-topics), [Configuration changes](#configuration-changes), and the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes) before you deploy.

> [card] Upgrade Path
>
> **5.9.5 → 5.9.6**: Direct upgrade. No manual data migration is required.
>
> **5.9.6 → 6.0.0**: See [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.4 or earlier directly?** Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first, then the earlier pages they point to.

## Component versions

### Core components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.17 | 10.174.10 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.14 | 10.152.7 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.13 | 10.113.7 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.11 | 10.94.6 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.101.1 | 10.100.7 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.111.1 | 10.110.7 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.13 | 10.124.7 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.12 | 10.112.6 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.8 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.11 | 10.92.6 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.11 | 10.102.6 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.12 | 10.98.7 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.201.2 | 10.200.9 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.13 | 10.107.7 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.13 | 10.122.7 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.13 | 10.101.6 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.102.1 | 10.101.6 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.12 | 10.98.6 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.12 | 10.69.6 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.14 | 10.33.7 | 10.8.0 | - | - |
| **license** | 10.87.12 | 10.87.6 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** 1.52.0, deployed and upgraded by the **SpiceDB operator** 1.25.1.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **solution-portal** (renamed from react-saas) | 10.285.4 | 10.282.5 | 10.230.2 | - | - |
| **iOS renderer** | 10.9.2 | 10.6.2 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.10.2 | 10.9.3 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.2 | 10.11.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.2 | 10.11.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.2 | 10.11.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.2 | 10.11.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.2 | 10.11.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.2 | 10.11.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.13 | 10.35.6 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.2 | 10.11.0 | - | - | - |
| **ai-assistant** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.2 | 10.11.0 | - | - | - |
| **flowx-docs** | 5.9.6 | 5.9.5 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.6 adds one Kafka topic. If your cluster does not create topics automatically, create it before you deploy, and allow both services in your ACLs.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.build.deployment-failed.v1` | runtime-manager | application-manager | Reports a build deployment that failed, so application-manager can queue it for a retry. |

The topic is included in the FlowX Kafka topics chart from version 10.2.0. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Create the `ai.flowx.build.deployment-failed.v1` Kafka topic if your cluster does not create topics automatically. See [Kafka topics](#kafka-topics).
2. Review [Configuration changes](#configuration-changes). No values change is required for a standard upgrade.
3. The `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes).
4. Update container images to the 5.9.6 versions listed in the tables above.
5. Deploy services using your standard deployment process.
6. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Build redeployment retries

When a build deployment fails, application-manager queues it for a retry. The queue is now stored in the application-manager database, in the new `failed_deployment` table, instead of in Redis. The table is created automatically on startup. runtime-manager reports each failure on the `ai.flowx.build.deployment-failed.v1` topic, and application-manager consumes it.

New application-manager variables (the defaults fit a standard deployment):

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_BUILD_DEPLOYMENTFAILED` | Topic that carries failed build deployments. | `ai.flowx.build.deployment-failed.v1` |
| `KAFKA_CONSUMER_GROUPID_BUILD_DEPLOYMENTFAILED` | Consumer group that reads the topic. | `build-deployment-failed-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_DEPLOYMENTFAILED` | Number of consumer threads for the topic. | `1` |

> [!WARNING]
>
> Retries that are still queued in Redis when you upgrade are not moved to the new table. Re-publish any build whose deployment failed shortly before the upgrade. The old entries stay in the Redis hash `build:failed-deployments:v3`, under the persistence key prefix configured for application-manager. Nothing reads them after the upgrade, so you can delete the hash.

#### MongoDB setting names

Services that use MongoDB now read their connection settings from new names. The previous `SPRING_DATA_MONGODB_*` variables still feed the new settings, so existing deployments need no change. Use the new names in new configuration.

| Previous variable | New variable |
| - | - |
| `SPRING_DATA_MONGODB_URI` | `SPRING_MONGODB_URI` |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | `SPRING_MONGODB_REPRESENTATION_UUID` |
| `SPRING_DATA_MONGODB_STORAGE` | `FLOWX_DATASOURCE_MONGO_STORAGE` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | `FLOWX_DATASOURCE_APPRUNTIME_ENABLED` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | `FLOWX_DATASOURCE_APPRUNTIME_URI` |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | `FLOWX_DATASOURCE_APPRUNTIME_REPRESENTATION_UUID` |

`SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION` no longer has any effect: indexes on the runtime database are never created automatically.

#### Document parser models

The document parser image now contains its layout, table, and OCR models, so the parser downloads nothing at startup or on the first parse. It runs without internet access and on a read-only filesystem. `USE_DOCLING` no longer has any effect on the document parser and can be removed from its configuration.

#### Integration Designer: document download timeout

A REST node JSON body can include `"@@base64File(<path>)"` to send a Document Plugin file as base64. Downloading the file from the Document Plugin is cancelled after this timeout. See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

New integration-designer variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` | Longest time a Document Plugin file download for a REST node JSON body may take before it is cancelled. | `PT5M` |

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026

Maintenance release for the 5.9.x LTS line. Durable build redeployment retries, project version merge fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Review the [deployment guidelines](./deployment-guidelines-v5.9.6) before you upgrade: this release adds one Kafka topic.

> [card] Release Highlight
>
> **FlowX.AI 5.9.6** is a maintenance release for the 5.9.x LTS:
>
> * **Durable build redeployments:** a build deployment that failed and waits for a retry is stored in the database, so a Redis flush or restart no longer drops it
> * **Key fixes:** project version merges no longer lose navigation areas, Resources Changed no longer flags unchanged resources, and Number attributes keep the selected subtype
> * Backend, Designer, and AI stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.6 is compatible with 5.9.5. The upgrade adds a database table and a MongoDB index, both created automatically when the services start.

**Before you upgrade, check these:**

* **AI Platform Helm chart:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime.&#x20;
* **Kafka topics:** create the `ai.flowx.build.deployment-failed.v1` topic if your cluster does not create topics automatically, and allow it in your ACLs. `runtime-manager` produces it and `application-manager` consumes it. See [Kafka topics](./deployment-guidelines-v5.9.6#kafka-topics).
* **Pending build redeployments:** retries that are still queued in Redis when you upgrade are not carried over. Re-publish any build whose deployment failed shortly before the upgrade. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Workflow node retries:** retry waits now grow exponentially and the max interval caps each wait instead of the whole retry window. Review the retry settings of nodes that rely on the previous timing.
* **Connection tests:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources. Grant these to custom roles that run connection tests.
* **Integration Designer startup:** the first start after the upgrade builds a new index on the `workflow_instances` MongoDB collection. On a large collection, allow extra time before the readiness check passes.
* **React Native SDK hosts:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` and keeps showing the current process, like the Android and iOS SDKs. Update your app to dispose the current process handle and continue the new process. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).

**Upgrade path:** direct upgrade from 5.9.5. Upgrading from 5.9.4 or earlier? Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/React Native/iOS/Android) and Designer 5.9.x. Component versions are listed in the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6).

***

## Full changelog

### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json) and [Integration Designer: document download timeout](./deployment-guidelines-v5.9.6#integration-designer-document-download-timeout).&#x20;

### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.&#x20;
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).&#x20;
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.&#x20;
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect. See [Document parser models](./deployment-guidelines-v5.9.6#document-parser-models).&#x20;
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.&#x20;
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.&#x20;
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](./deployment-guidelines-v5.9.6#mongodb-setting-names).&#x20;
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.&#x20;
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.&#x20;
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6) for its version.&#x20;

### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.&#x20;
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.&#x20;
* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.&#x20;
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.&#x20;
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.&#x20;
* **React Native SDK:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` instead of replacing the shown process itself, like the Android and iOS SDKs. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).&#x20;
* **React Native SDK:** a custom component keeps receiving data after the app returns from the background, for example from the Android document picker, so a document upload waiting for its link completes.&#x20;
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.9.x to 6.0.0 changelog
Source: https://docs.flowx.ai/release-notes/v6.x/5.9-to-6.0-changelog

Every change a self-hosted FlowX.AI 5.9.x installation picks up when it moves to 6.0.0, grouped by release and type, with an RSS feed.

This page lists what changes for a self-hosted FlowX.AI 5.9.x installation that moves to 6.0.0, newest first. Releases 5.10 to 5.13 shipped to SaaS first, and self-hosted installations get their features with 6.0.0. Changes already delivered in a 5.9.x patch are in the [5.9.x LTS changelog](/release-notes/v5.x/5.9-lts-changelog) and are not repeated here. Mobile renderers and the React Native SDK are covered in their own release notes.

On FlowX.AI SaaS, apps moved from 5.13.0 to 6.0.0, so only the 6.0.0 entry applies to them, including its upgrade actions.

**6.0.0**

October 2026

**Upgrade actions:** check these in your existing apps.

* **AI node prompts:** the chat message is no longer appended. Reference `${userMessage}` in **Context**. [Details](/6.x/ai-platform/chat-driven-workflows#context)
* **AI node retries:** on by default, up to 10 times, 30 seconds apart. [Details](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service)
* **Substitution tags:** `@@key` is rewritten to `${tag:key}`, and a missing `sys_*` tag now renders empty. [Details](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#what-changes-in-existing-apps-when-you-upgrade)
* **FlowX Database and Unmanaged MongoDB writes:** `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter are rejected. To match every document, pass `{"_id": {"$exists": true}}`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb)
* **Masked names:** data-privacy placeholders now carry the gender, such as `<NAME_F_1>`. Update prompts or scripts that match `<NAME_1>`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy)
* **Email triggers over IMAPS:** the mail server's certificate is now verified, so a self-signed or mismatched certificate stops the trigger from connecting. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway)
* **Evaluations:** datasets become test cases with no checks, so an experiment skips them until you add an assert or evaluator. [Details](/6.x/ai-platform/evaluations#datasets-from-earlier-versions)
* **Exports from 5.1.x:** they no longer import, and 5.1.x is no longer an export target. Import a 5.1.x export into a 5.9.x environment and export it again from there. [Details](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x)
* **Scripts on GraalVM:** they now stop at the same per-language time limit as the native engine, 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0 they had no limit. [Details](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits)

Self-hosted installations also follow the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) and the [migration guide](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview) for the Helm chart and renderer SDKs.

#### New

* **Developer Agentic Harness:** a plan can split the work into stories, delivered one at a time, each with how to test it. Comment mode lets you select a component in the running app and ask for a change, and conversations follow you across the Designer. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Integration Designer:** add schedules to a workflow's Start node to run it once on a date or repeatedly on an ISO or cron cycle. A schedule fires only after you activate it in **Runtime** → **Runtime Settings** → **Schedules**. See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
* **Integration Designer:** the Generate Tabular File node turns an array of rows into a CSV or XLSX file. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
* **FlowX Database:** an index can enforce unique values on one attribute or a compound key, and existing duplicates are reported when you run **Apply Indexes**. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
* **Knowledge Base:** **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
* **Resources:** **Documentation** in a resource's menu holds a short description and longer Markdown documentation. Media Library assets get a description, used as the image's alt text. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
* **Substitution tags:** write `${tag:key}` anywhere in a component's text, next to static text and process data. The upgrade rewrites whole-value `@@key` references to `${tag:key}`, and `@@key` keeps working as a whole value. See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).

#### Changed

* **Designer header:** the header holds the project name, the **Config** / **Runtime** switch, the **Build with AI** and **Comment** toggles, and **Run project**. Branching, the current version, and **Commit Changes** move to a version block in the footer. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
* **AI nodes:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when its AI service or provider can't be reached. Turn on **Allow Retry** to set your own count, interval, and backoff. See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
* **Chat-driven workflows:** the chat message is no longer appended to an AI node's prompt. Reference `${userMessage}` in the node's **Context**. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
* **Evaluations:** each workflow has its own test cases, grouped by tags, with **equals** and **equals as JSON** asserts and LLM evaluators. The upgrade converts datasets to test cases with no checks, so add an assert or evaluator to each one before you run it. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
* **Certificates:** the **Certificates** panel on REST and File Storage data sources has two parts: **Trust** (System CAs, Custom CA, or None (insecure)) and **Identity** for mutual TLS. Existing settings are converted automatically. See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates).
* **Knowledge Base:** turning **Containing Personal Information** on or off re-embeds the existing content with the new model. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested).
* **Issues Console:** a check also covers the version itself: entry points, theme, library builds, and unused dependencies. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
* **Notification center:** covers version imports and build exports and imports, alongside version exports and process instance migrations. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
* **Configuration parameters:** after you save a sensitive value, the Designer shows `********` in its place. The real value is still used at runtime. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
* **Script engine:** scripts on GraalVM stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
* **Canvas:** **Auto-arrange** on the workflow canvas and **Arrange** on the process canvas show a layout preview before anything moves. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).
* **Timer events:** timer nodes use the schedule editor. Dates and times are picked in local time and saved in UTC. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).
* **Versioning:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).
* **Datepicker:** **Allow manual input** lets users type a date in the pattern of the project's default locale. Web only.
* **Data mapping:** typing a new attribute path, such as `client.address.street`, creates the data types it names when you save the mapping.

#### Removed

* **AI agents:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors are removed. Open the agent rail with ⌘K (Ctrl+K) or the sparkle toggle in the header. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Evaluations:** the Code evaluators are removed. Use **equals** in place of Exact match and **equals as JSON** in place of JSON match. Levenshtein has no replacement. See [Evaluations](/6.x/ai-platform/evaluations).
* **Export and import:** exports from 5.1.x no longer import, and 5.1.x is no longer an export target. See [Exports from 5.1.x](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x).

#### Deprecated

* **GraalVM script engine:** deprecated. FlowX.AI 6.1.x is the last release family that supports it. Scripts on GraalVM keep working in 6.0.0; move them to the native engine. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).

[6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) · [6.0.0 deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)

**5.13.0**

September 2026

#### New

* **Developer Agentic Harness:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys the app, drafts a plan for you to confirm, and runs the change on its own branch; merging and serving a new version stay with you. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Notification center:** a bell in the Designer opens a 30-day notification history with read state, search, and filters. See [Notification center](/6.x/docs/flowx-designer/notification-center).
* **UI Designer:** copy UI components and paste them into another UI Flow, app, or context. The paste names anything it could not place, and pasted components get unique names.
* **Versioning:** committing or merging a version takes an optional description of up to 2000 characters, and a commit details view shows what a version contains. See [Commit descriptions and details](/6.x/docs/projects/managing-applications/versioning#commit-descriptions-and-details).
* **Runtime:** an operator with the corrective-actions role moves the token of a running process instance to another node. See [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
* **Document classifiers:** a classifier's corpus can be exported and imported between environments, and viewed read-only in the **Data** tab. See [What travels between environments](/6.x/docs/platform-deep-dive/integrations/document-classifiers#what-travels-between-environments).
* **Integration Designer:** the File Encryption node encrypts or decrypts a file with a password inside a workflow. The file path and password take expressions.
* **UI Designer:** a start workflow trigger takes a condition, so the workflow starts only when the condition holds.&#x20;
* **FlowX Database:** the Intersects operator matches documents whose array field shares at least one value with a given list. See [Intersects on array fields](/6.x/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).
* **Personal Information Guard:** AI nodes with the input scan on log the request as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/6.x/ai-platform/personal-information-guard#request-after-pii-anonymization).

#### Changed

* **Access management:** the Workspace corrective actions editor role replaces the Workspace operations editor role. Users and groups with the old role move to the new one automatically. See [Workspace corrective actions editor permission matrix](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
* **Export and import:** version exports bundle dependencies the same way build exports do, and the export dialog preselects the target platform version. See [Version exports that bundle dependencies](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#version-exports-that-bundle-dependencies).
* **Integration Designer:** the Tabular Data Extraction node becomes the Data Parse node and also parses XML and JSON. See [Data Parse: XML and JSON support](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support).
* **Knowledge Base:** embedding jobs are scheduled fairly by default, so a large ingestion no longer delays small jobs queued behind it.
* **File sources:** Document and Image components share one source configuration. In process user tasks, the **Document Plugin Path** source takes a Documents plugin `downloadPath` directly. See [Selecting the file to download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download#selecting-the-file-to-download).
* **Task management:** the task list searches, filters, and sorts on the translated labels it displays. See [Search and sort on translated labels](/6.x/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).
* **Substitution tags:** custom tags can no longer start with `sys_`, which is reserved for system tags. See [Substitution tags](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags).
* **Elasticsearch:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Elasticsearch replica auto-expansion](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).
* **Processes:** the process name moves from **Settings** into a **Details** modal.
* **User management:** inviting many users at once has a reworked flow, and a sign-up link takes new users directly to the right solution.

[5.13.0 release notes](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) · [5.13.0 deployment guidelines](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13)

**5.12.0**

September 2026

**Upgrade actions:** the webhook gateway now reads the runtime registry, which adds a MongoDB dependency it did not have before. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets).

#### New

* **Integration Designer:** turn on **Parallel Multi-Instance** on a Subworkflow node to start one subworkflow per element of an input array and collect the results in an output array. See [Parallel multi-instance](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance).
* **Integration Designer:** email and webhook triggers can start an integration workflow, not only a process. See [External triggers](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).
* **Integration Designer:** a Subworkflow node can route a mapping failure to its own branch instead of stopping the parent workflow. It is opt-in per node. See [Routing a subworkflow failure](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
* **Integration Designer:** the Send Notification node fills a project notification template from workflow data and sends it. See [Send Notification node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node).
* **Db2 data source:** IBM Db2 joins the relational data sources, with Db2 for i as the default and Db2 LUW also supported. Db2 for z/OS is listed but not implemented, and selecting it fails with an error. See [Db2 database](/6.x/docs/platform-deep-dive/integrations/db2-database).
* **Runtime:** bulk migration moves a filtered set of process instances to a new build in one run, with a check before it runs. See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances).
* **Runtime:** a Workflow Instances page lists every workflow run in the project, filterable by status, date, and origin. The Process Instances and UI Flow Sessions lists gain status and start-date filters. See [Workflow instances](/6.x/docs/projects/runtime/workflow-instances).
* **Personal Information Guard:** mask and restore nodes place personal-data handling as explicit workflow steps. See [Masking and restoring across several nodes](/6.x/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
* **Deep Research node:** researches a question across the open web and files a cited report into a Knowledge Base. Depth is Quick, Standard, Deep, or Custom, and domains can be restricted with an allow or deny list. See [Deep Research node](/6.x/docs/platform-deep-dive/integrations/deep-research-node).
* **Custom Agent:** a reusable function with input and output slices can be an agent tool. Built-in tools are a catalog of twenty tools in five categories: Math, List, Date, Text, and Web search. See [Tools tab](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#tools-tab).
* **Chat component:** users rate an agent's answer and add a reason, and the ratings are recorded in audit. See [Rating an answer](/6.x/ai-platform/chat-component#rating-an-answer).
* **Evaluations:** custom evaluators score with Numeric or Binary rules and belong to the workflow you create them in. See [Custom evaluators](/6.x/ai-platform/evaluations#custom).
* **Issues panel:** the Designer validates the resources in a project version and collects the findings in one **Issues** panel. See [Checking for issues](/6.x/docs/projects/managing-applications/checking-for-issues).
* **Versioning:** merge into any branch you can merge into, and archive, unarchive, or delete branches. See [Managing branches](/6.x/docs/projects/managing-applications/versioning#managing-branches).
* **Process canvas:** a **New Node** panel, drop-anywhere connecting, draggable control points on sequence flows, and swimlanes that resize from all four edges. See [Faster ways to build](/6.x/docs/building-blocks/process/process#faster-ways-to-build).
* **Reusable UI templates:** a template can be built for UI Flow pages as well as process user tasks. Templates created earlier count as Process templates. See [Where a template can be used](/6.x/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used).

[5.12.0 release notes](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026) · [5.12.0 deployment guidelines](/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12)

**5.11.0**

August 2026

#### New

* **Custom Agent:** attach FlowX workflows as tools, each with a hint that tells the agent when to call it. See [How workflow tools run](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run).
* **Custom Agent:** agentic knowledge base search breaks a question into sub-queries and retries with reworded queries when the first pass finds nothing. **Show Reasoning** records the model's reasoning summary in the logs. See [Agentic knowledge base search](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#agentic-knowledge-base-search).
* **Knowledge Base:** a Knowledge Base with **Containing Personal Information** on can use a local embedding model, set up as a CUSTOM provider in the organization AI settings. See [Containing personal information](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).
* **Knowledge Base:** the Update Knowledge Base node can delete entries that match a metadata filter, and its FAIL branch reports what failed and how many chunks were rolled back. See [Delete entries](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#delete-entries).
* **Document classifiers:** define classes, upload training data, and train or import a model, then route each document page with the Document Classification node. See [Document classifiers](/6.x/docs/platform-deep-dive/integrations/document-classifiers).
* **Reusable functions:** Script and Condition (Fork) nodes in the Integration Designer can call reusable functions. See [Reusable functions](/6.x/docs/building-blocks/reusable-resources/reusable-functions).
* **Integration Designer:** the Subworkflow node can map input per start node and output per end node instead of raw JSON. See [Subworkflow node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#subworkflow-node).
* **Data model:** attributes support validators such as Required, Min/Max Value, Min/Max Length, Pattern, and Email Format, wherever the data model is used. See [Attribute validations](/6.x/docs/building-blocks/project-data-model#attribute-validations).
* **Templates:** document and notification templates use the structured data model, with typed attributes and an **Input Parameters** tab. See [Managing notification templates](/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates).
* **Chat component:** the chat button shows an unread-message badge, the panel searches conversation history, and the input can be disabled by a condition. See [Chat](/6.x/docs/building-blocks/ui-designer/ui-component-types/chat).
* **UI Flows:** a **Navigate To** action can require selected forms to pass validation before it navigates. See [Navigate To action](/6.x/docs/building-blocks/ui-flows#navigate-to-action).
* **UI Flows:** with **Allow multiple editors** off, a running session is restricted to its owner. New flows default to single-owner; existing and imported flows keep the shared behavior. See [Session owner](/6.x/docs/building-blocks/ui-flows#session-owner).
* **Process Renderer:** a process-end trigger runs a configured action when the embedded process ends. See [Process end handling](/6.x/docs/building-blocks/ui-flows#process-end-handling).

#### Changed

* **Chat-driven workflows:** a conversational workflow must send at least one chat reply, or the run fails with an error. See [Chat-driven workflows](/6.x/ai-platform/chat-driven-workflows).
* **Custom Agent:** the **Instructions** field is limited to 10,000 characters. See [Custom Agent node](/6.x/docs/platform-deep-dive/integrations/custom-agent-node).
* **Response caching:** POST REST endpoints, file-storage LIST and DOWNLOAD, and Mongo FIND, FIND\_ONE, and AGGREGATE operations are cacheable. Mutating operations are never cached. See [REST endpoint caching](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching).
* **Email triggers:** Email Trigger and Microsoft Outlook data sources filter attachments by file extension. Existing category selections are migrated automatically. See [Attachment handling](/6.x/docs/platform-deep-dive/integrations/email-trigger#attachment-handling).
* **Audit:** UI Flow runtime sessions are audited in more detail, including workflow runs, chat messages, and conversation reads. See [Audit](/6.x/docs/platform-deep-dive/core-extensions/audit).
* **Export and import:** exporting to an older platform version removes UI-template features the target cannot read. See [Cross-version export and import](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
* **UI Flows:** an expired session shows a session-expired screen with a start-fresh option.
* **Renderers:** enumeration lookups are batched into a single request.

[5.11.0 release notes](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026) · [5.11.0 deployment guidelines](/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11)

**5.10.0**

July 2026

#### New

* **PostgreSQL data source:** connect a workflow to a PostgreSQL database and run SQL query operations from workflow nodes. See [PostgreSQL database](/6.x/docs/platform-deep-dive/integrations/postgresql-database).
* **SOAP data source:** import a WSDL from a URL or file, and call each operation from workflows with a SOAP Operation node. See [SOAP System](/6.x/docs/platform-deep-dive/integrations/soap-system).
* **FlowX Database:** MongoDB aggregation pipelines group, join, and reshape documents beyond a single query. See [Aggregation pipelines](/6.x/docs/platform-deep-dive/integrations/flowx-database#aggregation-pipelines).
* **Integration Designer:** the Tabular Data Extraction node reads a spreadsheet or CSV file into structured JSON, one object per row. See [Tabular Data Extraction node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node).
* **Integration Designer:** the Template Filling node generates a PDF or DOCX document from a document template filled with workflow data. See [Template Filling node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node).
* **Integration Designer:** the Combine Files node merges PDFs in a given order, and the Split File node splits a PDF by page ranges or per page. See [Combine Files node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node).
* **Documents plugin:** template-based generation can produce DOCX as well as PDF, set with `outputFormat`. See [Generating DOCX output](/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output).
* **Knowledge Base:** a failed ingestion shows its status and reason, and **Retry** re-runs the last operation after cleaning up partial content. The Update Knowledge Base node gains a FAIL exit with per-operation rollback. See [Error handling and retry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#error-handling-and-retry).
* **File Download component:** end users download files directly from a rendered app. See [File download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download).
* **Global header and footer:** a UI Flow can define a header and footer shown on every page. See [Global header and footer](/6.x/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer).
* **Event handlers:** event handlers can fire on a condition. The **Save Local Variable** action saves the clicked collection row into local data under a key. See [Conditional triggers](/6.x/docs/building-blocks/ui-designer/event-handlers#conditional-triggers) and [Save Local Variable](/6.x/docs/building-blocks/ui-designer/event-handlers#save-local-variable).
* **Image component:** the Image component honors a color property. See [Image](/6.x/docs/building-blocks/ui-designer/ui-component-types/image).
* **Data source testing:** the database query testing modals have a **Documents** tab, and multi-record operations report an affected-record count. See [Testing data sources](/6.x/docs/platform-deep-dive/integrations/testing-data-sources).
* **Mistral provider:** add Mistral with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability. See [AI providers](/6.x/ai-platform/ai-providers).

#### Changed

* **Documents:** the **Document Type** field is renamed **Document Tag**. Behavior is unchanged.

[5.10.0 release notes](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026) · [5.10.0 deployment guidelines](/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10)


# Deployment guidelines v6.0.0
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0

Component versions, Kafka topics, environment variables, and Helm chart changes for FlowX.AI 6.0.0, with the steps a self-hosted upgrade needs.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 6.0 is a feature release. On SaaS, FlowX applies every change on this page. Self-hosted deployments usually follow LTS releases and receive these changes with the next LTS release family. If you upgrade a self-hosted installation to 6.0.0, apply the changes below in the order given in [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

### Before you upgrade a self-hosted installation

* Set every AI service group flag explicitly. See [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart).
* Deploy designer-user, the new `core` service. harness and ui-driver (`devtime`) and dynamic-classifier (`runtime`) deploy only if you turn their group on. See [New services](#new-services).
* Create the new database users and secrets for the services you deploy. Every installation needs the four new keys in `keycloak-flowx-realm-clients`. See [New databases and secrets](#new-databases-and-secrets).
* Give process-engine read access to the integration-designer bucket. See [New databases and secrets](#new-databases-and-secrets).
* If you turn on dynamic-classifier, set its bucket name and provide its 20Gi volume. See [Update your values](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart#update-your-values).
* If you route with Kubernetes Ingress, move callers off the admin Ingress routes that the chart no longer creates. See [New databases and secrets](#new-databases-and-secrets).
* Create the new Kafka topics. If your cluster uses ACLs, also give the new clients of three existing topics access. See [New Kafka topics](#new-kafka-topics).
* Let audit-core reach Redis. It now uses Redis only to choose which replica runs its nightly cleanup job, not as a cache, and the chart connects it to the same Redis server as the other services. If you restrict which services can reach Redis, add audit-core. See [Configuring Redis](/6.x/setup-guides/audit-setup-guide#configuring-redis).
* Set the personal-data encryption master key on integration-designer. See [Personal-data encryption master key](#new-required-secret-personal-data-encryption-master-key).
* Choose how Elasticsearch replicates new indices. See [Elasticsearch replica auto-expansion](#changed-default-elasticsearch-replica-auto-expansion).
* Add the MongoDB hosts on your private network that data sources use to `FLOWX_SSRFALLOWEDHOSTS`. See [nosql-db-runner host restrictions](#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).
* Trust the certificates of the IMAP servers your email triggers read from. See [IMAPS certificate verification](#changed-default-imaps-certificate-verification-in-email-gateway).

Upgrading from 5.9.5 or earlier? Two changes from 5.9.6 also apply. See [Upgrading from an older patch release](#upgrading-from-an-older-patch-release).

## Component versions

The versions below are the component versions that make up FlowX.AI 6.0.0, next to FlowX.AI 5.9.6, the latest 5.9.x release a self-hosted installation upgrades from. A dash marks a component that is new since 5.9.6. On SaaS, FlowX manages these versions.

### Core components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **admin** | 11.132.0 | 10.152.14 |
| **advancing-controller** | 11.86.0 | 10.98.12 |
| **application-manager** | 11.143.0 | 10.159.3 |
| **audit-core** | 11.92.0 | 10.102.11 |
| **authorization-system** | 11.102.0 | 10.122.13 |
| **cms-core** | 11.114.0 | 10.113.13 |
| **data-search** | 11.87.0 | 10.92.11 |
| **data-sync** | 11.94.0 | 10.107.13 |
| **designer** | 11.252.0 | 10.285.4 |
| **designer-user** | 11.31.0 | - |
| **document-plugin** | 11.122.0 | 10.124.13 |
| **email-gateway** | 11.110.0 | 10.102.1 |
| **events-gateway** | 11.93.0 | 10.101.1 |
| **file-gateway** | 11.105.0 | 10.33.14 |
| **integration-designer** | 11.158.0 | 10.201.2 |
| **license** | 11.94.0 | 10.87.12 |
| **nosql-db-runner** | 11.98.0 | 10.101.13 |
| **notification-plugin** | 11.113.0 | 10.111.1 |
| **organization-manager** | 11.101.0 | 10.98.12 |
| **process-engine** | 11.137.1 | 10.174.17 |
| **runtime-manager** | 11.143.0 | 10.159.3 |
| **scheduler-core** | 11.89.0 | 10.94.11 |
| **task-management-plugin** | 11.109.0 | 10.112.12 |
| **webhook-gateway** | 11.102.0 | 10.69.12 |

### AI base components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-gateway** | 11.118.1 | 10.35.13 |
| **embedder** | 11.7.0 | 10.11.2 |
| **knowledgebase-indexer-v2** | 11.7.0 | 10.11.2 |
| **knowledgebase-rag** | 11.7.0 | 10.11.2 |
| **doc-parser** | 11.7.0 | 10.11.2 |

### AI dev-time components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-analyst** | 11.7.0 | 10.11.2 |
| **ai-architect** | 11.7.0 | 10.11.2 |
| **ai-assistant** | 11.7.0 | 10.11.2 |
| **ai-designer** | 11.7.0 | 10.11.2 |
| **ai-developer** | 11.7.0 | 10.11.2 |
| **harness** | 11.7.0 | - |
| **kb-enrichment** | 11.7.0 | 10.11.2 |
| **planner** | 11.7.0 | 10.11.2 |
| **ui-driver** | 11.252.0 | - |

### AI runtime components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **agent-builder** | 11.7.0 | 10.11.2 |
| **cee-pii** | 11.7.0 | - |
| **data-privacy** | 11.7.0 | 10.11.2 |
| **doc-converter** | 11.7.0 | 10.11.2 |
| **dynamic-classifier** | 11.7.0 | - |
| **evals-judge** | 11.7.0 | 10.11.2 |
| **speech-to-text** | 11.7.0 | 10.11.2 |
| **web-crawler** | 11.7.0 | 10.11.2 |

### AI extensions

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **modpod** | 11.0.1 | 10.0.7 |
| **observatory-api** | 11.29.4 | 10.7.2 |
| **observatory-platform** | 11.29.4 | 10.7.2 |
| **observatory-web** | 11.29.4 | 10.7.2 |

In FlowX.AI 6.0, the Observatory components run on environments operated by FlowX. They aren't included in client deployments in this release.

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart and deployed with the AI base group (see [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart)). Its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/6.x/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.252.0` for FlowX.AI 6.0.0). The native iOS and Android renderers version independently.

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **@flowx/angular-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/angular-theme** | 11.252.0 | 10.285.4 |
| **@flowx/angular-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/core-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/core-theme** | 11.252.0 | 10.285.4 |
| **solution-portal** | 11.252.0 | 10.285.4 |
| **iOS renderer** | 11.6.0 | 10.9.2 |
| **Android renderer** | 11.18.0 | 10.10.2 |

The **solution-portal** container app tracks the designer version.

***

## Configuration changes

This section compares environment variables, Kafka topics, and the `flowx-ai` Helm chart with FlowX.AI 5.9.6. It includes the changes that reached SaaS in 5.10 to 5.13, so a self-hosted upgrade from 5.9.6 needs only this page.

### New Kafka topics

Compared with 5.9.6, create these 42 topics. Create all of them, whatever your group flags: topics for services you don't deploy stay unused. On SaaS they are created and managed automatically.

**AI nodes as durable jobs:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.agent-node.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.progress.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.cancel.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Deep research node:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Validation findings:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.application-version.validation-findings.request-admin.v1` | application-manager → admin |
| `ai.flowx.application-version.validation-findings.request-cms.v1` | application-manager → cms-core |
| `ai.flowx.application-version.validation-findings.request-document-plugin.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.validation-findings.request-integration.v1` | application-manager → integration-designer |
| `ai.flowx.application-version.validation-findings.request-notification-plugin.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.validation-findings.request-application-manager.v1` | application-manager → application-manager |
| `ai.flowx.application-version.validation-findings.response.v1` | admin, cms-core, document-plugin, integration-designer, notification-plugin → application-manager |
| `ai.flowx.application-version.validation-findings.job-completed.v1` | application-manager → harness |

**Structured template data model:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |

**Runtime content import and export:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → embedder |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | embedder → integration-designer |

**Document classification and extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → none (dead-letter topic) |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | doc-parser → integration-designer |

**Event-triggered workflows:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Workflow schedules:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.workflow-schedules.updates.in.v1` | integration-designer → runtime-manager |
| `ai.flowx.core.notify.timer-event-schedule.state.v1` | scheduler-core → runtime-manager |

**Bulk instance migration and move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

**Designer notifications and preferences:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |
| `ai.flowx.eventsgateway.user.notifications.v1` | designer-user → events-gateway |
| `ai.flowx.designer-user.user-preferences.v1` | designer-user → designer-user |

> [!NOTE]
>
> If your Kafka cluster uses ACLs, also give the new clients of these existing topics access:
>
> * `ai.flowx.application-version.sync.out.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.correction-after-app-operation.response.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1`: document-plugin

### New services

Compared with 5.9.6, the `flowx-ai` Helm chart adds four services. On SaaS they are provisioned and managed by FlowX.

| Service | Group | What it does | Dependencies |
| - | - | - | - |
| designer-user | `core` | Stores Designer user preferences, such as the last-used workspace, and delivers Designer notifications | MongoDB, Redis, Kafka |
| harness | `devtime` | Runs the Developer Agentic Harness | PostgreSQL, Redis, Kafka |
| ui-driver | `devtime` | Renders UI flows in the background for the Developer Agentic Harness | None |
| dynamic-classifier | `runtime` | Classifies documents with trained models | PostgreSQL, a persistent volume, Kafka |

The databases, secrets, and volume are in [New databases and secrets](#new-databases-and-secrets).

The harness reuses the platform's existing Redis, so nothing new is provisioned. It uses Redis to stream a running turn to every open Designer session and to cancel a turn from any harness pod. Without Redis, turns still run, but live progress and cancellation across pods don't work.

The harness also consumes the existing `ai.flowx.llm.config.changed.v1` topic, so a change to an organization's AI model settings reaches it right away. Without Kafka, it picks up the change when its cache expires.

### AI service groups in the Helm chart

The `flowx-ai` Helm chart groups the services into four groups. Each group has its own flag, `groups.<group>.enabled`:

| Group | Services |
| - | - |
| `core` | Core platform services |
| `base` | The AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and the bundled Qdrant |
| `devtime` | ai-analyst, ai-architect, ai-assistant, ai-designer, ai-developer, harness, kb-enrichment, planner, ui-driver |
| `runtime` | agent-builder, data-privacy, doc-converter, dynamic-classifier, evals-judge, speech-to-text, web-crawler. cee-pii is in this group but needs `services.cee-pii.enabled: true` as well |

The groups are the same as in 5.9.6. The 6.0.0 chart adds designer-user to `core`, harness and ui-driver to `devtime`, and cee-pii and dynamic-classifier to `runtime`. The `base` group is unchanged.

Set all four flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

> [!WARNING]
>
> **Set every group flag explicitly for self-hosted upgrades.** Don't rely on the chart's group defaults. The `devtime` and `runtime` services call the AI base services, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

### New databases and secrets

Compared with the `flowx-ai` Helm chart in 5.9.6, these services need new databases. Create a database only if its service's group is on. designer-user is in `core`, so every installation needs its database:

| Service | Group | Database user | Secret |
| - | - | - | - |
| agent-builder | `runtime` | PostgreSQL `agent_builder` | `flowx-postgres-agent-builder` |
| dynamic-classifier | `runtime` | PostgreSQL `dynamic_classifier` | `flowx-postgres-dynamic-classifier` |
| harness | `devtime` | PostgreSQL `harness` | `flowx-postgres-harness` |
| designer-user | `core` | MongoDB `designer-user` | `mongodb-designer-user-designer-user` |

Each database has the same name as its user. Each secret holds the user's password under the key `password`.

The webhook-gateway also connects to the existing `app-runtime` MongoDB database with the `app-runtime` user.

The `keycloak-flowx-realm-clients` secret needs four new keys, one for each new service account:

| Secret key | Keycloak client |
| - | - |
| `KEYCLOAK_DESIGNER_USER_CLIENT_SECRET` | `flowx-designer-user-sa` |
| `KEYCLOAK_AI_HARNESS_CLIENT_SECRET` | `flowx-ai-harness-sa` |
| `KEYCLOAK_NOTIFICATION_PLUGIN_CLIENT_SECRET` | `flowx-notification-plugin-sa` |
| `KEYCLOAK_DOCUMENT_PLUGIN_CLIENT_SECRET` | `flowx-document-plugin-sa` |

Other chart changes:

* **process-engine** needs read-only access (`s3:GetObject`) to the integration-designer bucket, to download the Kafka payloads that integration-designer stores there. The chart reads the access key ID from `global.flowx.s3.credentials.processEngine.accessKey` (default `flowx-process-engine-accesskey`) and the secret access key from the `flowx-process-engine-s3` secret, key `SecretAccessKey`.
* **dynamic-classifier** stores its data on a 20Gi `ReadWriteOnce` persistent volume claim, `dynamic-classifier-data`, and uses the `Recreate` deployment strategy, so an upgrade stops the old pod before the new one starts.
* **dynamic-classifier** reads an OpenAI API key for its LLM judge from the `dynamic-classifier-openai` secret, key `OPENAI_API_KEY`. The secret is optional: without it, the pod still starts and classification keeps working.
* The chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier. ai-gateway keeps its own.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map | none (required) |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today | `k1` |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index | `PT24H` |

### New object storage bucket: runtime content

Runtime content export and import stores its files in a new shared bucket, `runtime-content-bucket`. Application Manager creates the bucket on first use, Integration Designer writes export files and reads imports there, and the embedder reads and writes Knowledge Base vectors at the paths each request names. Grant all three services access to the bucket.

Browsers upload import files and download export files directly, through presigned URLs that Application Manager signs. By default it signs them with the internal storage endpoint, which only pods can reach, so set `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` to a storage endpoint that browsers can reach.

New variables on application-manager and integration-designer. Set the bucket on both, and the presign settings on application-manager only:

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_RUNTIMECONTENTBUCKET` | Bucket for runtime content export and import files | `runtime-content-bucket` |
| `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` | Storage endpoint used to sign the presigned upload and download URLs. Leave empty to sign with the internal storage endpoint | empty |
| `APPLICATION_FILESTORAGE_S3_PRESIGNREGION` | Region used to sign the presigned URLs | `us-east-1` |

For the full list of buckets, see [Data architecture](/6.x/docs/platform-overview/data-architecture#s3-compatible-object-storage-buckets).

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

New process-engine and audit-core variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

### Changed behavior: nosql-db-runner host restrictions cover MongoDB

The host restriction that relational data sources already had now applies to external MongoDB connections too. The nosql-db-runner checks every address a MongoDB host resolves to, including replica-set members and SRV targets, and rejects the connection if any of them is private. For FlowX Database and Unmanaged MongoDB data sources alike, it also rejects `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter. To match every document, pass `{"_id": {"$exists": true}}`.

nosql-db-runner variables (both already existed for relational data sources):

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SSRFALLOWEDHOSTS` | Hosts or CIDR blocks, separated by commas, that may connect even though they resolve to a private address. Addresses on the local machine or in a link-local range stay blocked | empty |
| `FLOWX_SSRFPROTECTIONENABLED` | Turns the host restriction on or off | `true` |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS`.

### Changed behavior: name placeholders in data-privacy

When data-privacy masks a person's name, the placeholder now carries the gender, for example `<NAME_F_1>` or `<NAME_M_1>`. When the name doesn't show the gender, the placeholder stays `<NAME_1>`. Prompts or scripts that match the old placeholder form need updating.

### Changed behavior: Workspace operations editor role replaced

The upgrade replaces the Workspace operations editor role with the [Workspace corrective actions editor](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix) role. Users and groups that had the old role get the new one automatically and keep access to process instance migration and move token. No action is needed.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

New audit-core variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/6.x/setup-guides/audit-setup-guide#configuring-elasticsearch).

### Changed default: IMAPS certificate verification in email-gateway

The email-gateway now verifies the certificate of every IMAPS server it connects to. A server must present a certificate signed by a trusted authority and matching its host name.

New email-gateway variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS` | Mail hosts that skip certificate verification, separated by spaces or commas. Use `*` to skip it for every host | empty |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Email triggers that read from an IMAP server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`.

### Changed default: AI node retry

AI nodes without retry settings of their own now retry when a dependency is temporarily unavailable, such as an LLM provider outage, a rate limit, or a lost connection. Permanent errors aren't retried, and deep research nodes never retry by default. A node's own retry settings replace the default.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_ENABLED` | Turns the default retry for AI nodes on or off | `true` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_MAXATTEMPTS` | Maximum retry attempts | `10` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_BACKOFFPERIOD` | Wait between attempts, as an ISO-8601 duration | `PT30S` |

### Upgrading from an older patch release

Upgrading from 5.9.5 or earlier? Apply the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries) as well. Two 5.9.6 changes affect the upgrade:

* **Build redeployment retries:** the queue of build deployments waiting for a retry moved from Redis to the application-manager PostgreSQL database, with a new topic, `ai.flowx.build.deployment-failed.v1`. Deployments waiting for a retry in Redis when you upgrade aren't moved to the new queue. Re-publish those builds after the upgrade.
* **advancing-controller management port:** `MANAGEMENT_SECURITY_ENABLED` is no longer read. Actuator endpoints on the management port, including Prometheus, answer without authentication.

> [!WARNING]
>
> Keep the advancing-controller management port, `8081`, off any public ingress.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](/release-notes/overview).


# Android SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/android

Migrate the FlowX Android renderer SDK from 5.9.x to 6.0.0.

## Android SDK migration guide

FlowX.AI 6.0 moves the Android SDK to `compileSdk` 37, Android Gradle plugin 9 and Kotlin 2.4, and aligns the SDK's names with the iOS and web SDKs. Update your build setup first, then the renamed SDK APIs.

### System requirements

* **minSdk = 26** (unchanged)
* **compileSdk = 37**

The SDK library was built using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 9.5.0**
* **[Gradle](https://gradle.org/releases/) 9.8.2**
* **[Kotlin](https://kotlinlang.org/) 2.4.21**

Your container app must build with at least:

* **Android Gradle Plugin 9.1.0**
* **Gradle 9.3.1** (the minimum depends on your Android Gradle Plugin version)
* **Kotlin 2.4**
* **JDK 17**

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Android Core KTX](https://developer.android.com/kotlin/ktx#core) | 1.16.0 | **1.19.1** |
| [Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) | 1.10.1 | **1.13.0** |
| [Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) | 2025.09.01 | **2026.09.00** |
| [Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) | 2.9.1 | **2.10.2** |
| [Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) | 2.9.1 | **2.11.0** |
| [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | 1.10.2 | **1.11.0** |
| [Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) | 1.1.7 | **1.3.0** |
| [Android Security](https://developer.android.com/jetpack/androidx/releases/security) | 1.1.0-beta01 | **1.1.0** |
| [OkHttp BOM](https://square.github.io/okhttp/) | 4.12.0 | **5.5.1** |
| [Retrofit](https://square.github.io/retrofit/) | 2.12.0 | **3.0.0** |
| [Coil BOM](https://coil-kt.github.io/coil/) | 3.4.0 | **3.6.3** |
| [Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) | 4.31.1 | **4.36.2** |
| [Mozilla Rhino](https://github.com/mozilla/rhino) | 1.8.0 | **1.9.2** |
| [Accompanist Permissions](https://google.github.io/accompanist/permissions/) | 0.37.3 | 0.37.3 |
| [Moshi](https://github.com/square/moshi) | 1.15.2 | 1.15.2 |
| [Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) | 2.1.5 | 2.1.5 |

> [!WARNING]
>
> The SDK now depends on **OkHttp 5** and **Retrofit 3**. Gradle resolves your app to these versions even if you declare OkHttp 4 or Retrofit 2, so update any code in your app that uses APIs removed in these major versions. Align your app's versions of these libraries with the SDK's versions to avoid compatibility issues.

### Migration steps

To build and run your container app with the 6.0 SDK, follow these steps in order:

**1. Update the SDK version**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
implementation("ai.flowx.android:sdk:<5.9.x version>") // [!code --]
implementation("ai.flowx.android:sdk:<6.0 version>") // [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Increase the `compileSdk` version to `37`**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileSdk = 35 // [!code --]
    compileSdk = 37 // [!code ++]
}
```

> [!NOTE]
>
> The SDK and its AndroidX, OkHttp and Coil dependencies require `compileSdk` 37. Raising `targetSdk` is not required.

**3. Update the `Android Gradle plugin` version to at least `9.1.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "8.10.0" apply false // [!code --]
    id("com.android.application") version "9.5.0" apply false // [!code ++]
}
```

> [!TIP]
>
> Android Gradle plugin 9 is a major release with breaking build changes. Consult the [Android Gradle plugin 9.0 release notes](https://developer.android.com/build/releases/agp-9-0-0-release-notes).

**4. Update the `Gradle` version**

```properties [rootProject]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.2-bin.zip # [!code ++]
```

> [!NOTE]
>
> Android Gradle plugin 9.1 requires at least Gradle 9.3.1, and 9.5 requires at least Gradle 9.6.0. Check the minimum for your version in the [Android Gradle plugin release notes](https://developer.android.com/build/releases/gradle-plugin).

**5. Remove the `Kotlin Android` plugin**

Android Gradle plugin 9 compiles Kotlin by itself (built-in Kotlin), so the `org.jetbrains.kotlin.android` plugin must be removed:

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code --]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") // [!code --]
}
```

> [!TIP]
>
> Consult the [Migrate to built-in Kotlin](https://developer.android.com/build/migrate-to-built-in-kotlin) guide.

**6. Update the `Kotlin` version to at least `2.4`**

With built-in Kotlin, your app compiles with the version of the Kotlin Gradle plugins you declare, such as the Compose Compiler plugin. The Kotlin version that Android Gradle plugin uses by default is too old to read the SDK's classes. Use the same version for every Kotlin Gradle plugin your project declares, such as Parcelize or Serialization.

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code --]
    id("org.jetbrains.kotlin.plugin.compose") version "2.4.21" apply false // [!code ++]
}
```

> [!WARNING]
>
> With an older Kotlin version, the build fails with an error like: `The binary version of its metadata is 2.4.0, expected version is 2.2.0`.

**7. Make sure core library desugaring is enabled**

The SDK requires core library desugaring. If your app does not enable it yet, add:

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**8. Rename the `imageBaseUrl` and `customHeaders` properties of the `Config` interface**

`imageBaseUrl` is now `assetsBaseUrl`, and `customHeaders` is now `additionalHttpHeaders`:

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
Flowx.getInstance().init(
    context = applicationContext,
    config = object : Config {
        ...
        override val imageBaseUrl = "URL to FlowX CMS Media Library" // [!code --]
        override val assetsBaseUrl = "URL to FlowX CMS Media Library" // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code --]
        override val additionalHttpHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code ++]
        ...
    },
    ...
)
```

> [!NOTE]
>
> The default value of the `locale` property changed from `Locale.getDefault()` to `Locale.forLanguageTag("en-US")`. If your app relies on the device locale for date, number and currency formatting, set it explicitly:
>
> ```kotlin theme={"dark"}
> override val locale: Locale = Locale.getDefault()
> ```

**9. Stop passing `null` to the `setAccessToken` method**

The `setAccessToken` method no longer accepts `null`:

```kotlin theme={"dark"}
fun setAccessToken(accessToken: String?) // [!code --]
fun setAccessToken(accessToken: String) // [!code ++]
```

Remove the calls that clear the token (for example, on logout or after a failed login):

```kotlin theme={"dark"}
Flowx.getInstance().setAccessToken(null) // [!code --]
```

A token can't be cleared once set. When another user logs in, set that user's token. If no token is ever set, the SDK runs in anonymous mode. For details, see the [Authentication](/6.x/sdks/android-renderer#authentication) section of the Android SDK reference.
\[!WARNING] Passing an empty string (`""`) no longer clears the token. The SDK sends it as is and the backend rejects the requests.

**10. Rename the `closeModalFunc` parameter to `onDismissRequested`**

The parameter of the `startProcess` and `continueProcess` methods was renamed. Its lambda now runs in the `ProjectScope` context:

```kotlin theme={"dark"}
Flowx.getInstance().startProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)

Flowx.getInstance().continueProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)
```

> [!TIP]
>
> Replace the deprecated `CloseModalProcessScope` type with `ProjectScope`, as described in the [Replace deprecated APIs](#replace-deprecated-apis) section.

**11. Rename the `imageBaseUrl` parameter of the `changeEnvironment` method (if used)**

```kotlin theme={"dark"}
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code --]
fun changeEnvironment(baseUrl: String, assetsBaseUrl: String, enginePath: String) // [!code ++]
```

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. The parameters are unchanged:

| Deprecated (5.9) | Replacement (6.0) | Available on |
| - | - | - |
| `CloseModalProcessScope` | `ProjectScope` | The `onDismissRequested` lambda of `startProcess` and `continueProcess` |
| `replaceSubstitutionTag` | `getSubstitutionTagContent` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getMediaResourceUrl` | `getMediaItemUrl` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getEnumeration` | `getEnumerationItems` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `executeAction` | `runAction` | `CustomComponentScope` |
| `executeUploadAction` | `runUploadAction` | `CustomComponentScope` |
| `configureUpdateState` | `setUpdateStateEnabled` | `Flowx` |

> [!TIP]
>
> Android Studio offers a **Replace with** quick fix on every deprecated call.

These changes are reflected in an actual implementation as shown below:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope // [!code --]
import ai.flowx.android.sdk.api.ProjectScope // [!code ++]

// close process confirmation alert
@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code --]
private fun ProjectScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code ++]
    ...
    Text(replaceSubstitutionTag("@@close_message")) // [!code --]
    Text(getSubstitutionTagContent("@@close_message")) // [!code ++]
}

// custom component
flowxScope.executeAction(action = it, params = JSONObject()) // [!code --]
flowxScope.runAction(action = it, params = JSONObject()) // [!code ++]

// custom loader
flowxScope.replaceSubstitutionTag(text) // [!code --]
flowxScope.getSubstitutionTagContent(text) // [!code ++]
flowxScope.getMediaResourceUrl(key) // [!code --]
flowxScope.getMediaItemUrl(key) // [!code ++]
```

## Related resources

> [card] [Android SDK reference](/6.x/sdks/android-renderer)
>
> Android renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Angular SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/angular

Migrate the FlowX Angular renderer SDK from 5.9.x to 6.0.0.

## Angular SDK migration guide

6.0 moves the Angular renderer to Angular 22 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new input and function names. The framework upgrade, the custom component input, and the removed `logSink` and `logCategories` inputs need code changes.

### Framework upgrade: Angular 21 → 22

Upgrade your host app **before** you bump the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide) from `21.0` to `22.0`.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Angular CLI and `@angular/*` | \~21 | **\~22** |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |
| TypeScript | ≥ 5.9, \< 6.1 | **≥ 6.0, \< 6.1** |

The FlowX Angular packages declare `@angular/*` ≥ 22.0.0 as peer dependencies, so `npm install` fails on an Angular 21 app.

### FlowX SDK changes

#### Renamed inputs and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` input | `baseUrl` |
| `processApiPath` input | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` input | `assetsBaseUrl` |
| `authToken` input | `accessToken` |
| `withConfig({ customLoader })` | `customLoaderProvider` (same shape) |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers.

```diff theme={"dark"}
 <flx-process-renderer
-  [apiUrl]="baseUrl"
-  [processApiPath]="'onboarding'"
-  [staticAssetsPath]="mediaLibraryUrl"
-  [authToken]="token"
+  [baseUrl]="baseUrl"
+  [enginePath]="'onboarding'"
+  [assetsBaseUrl]="mediaLibraryUrl"
+  [accessToken]="token"
   ...
 />
```

#### Custom components: `data$` → `input` signal

Custom components receive their data through an `input` signal input instead of the `data$` Observable. The process data moves under `input().data`, and actions run through `runAction` and the new `runUploadAction`. Both return an Observable.

| 5.9 | 6.0 |
| - | - |
| `data$` input (Observable) | `input` signal input |
| Data fields read from the top level (`data.<field>`) | `input().data.<field>` |
| `data.actionsFn.<name>(params)` | `input().runAction(name, params?)` |
| None | `input().runUploadAction(name, file, params?)` |

```typescript theme={"dark"}
import { Component, computed, input } from '@angular/core';
import { FlxCustomComponentData } from '@flowx/angular-sdk';

@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
})
export class CustomComponentComponent {
  input = input<FlxCustomComponentData>()
  client = computed(() => this.input()?.data.client)

  submit(file: Blob) {
    this.input()?.runAction('action_one', { amount: 3 }).subscribe();
    this.input()?.runUploadAction('upload_document', file, { side: 'front' }).subscribe();
  }
}
```

#### `logSink` and `logCategories` inputs removed

The `[logSink]` and `[logCategories]` inputs on `<flx-process-renderer>` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- [logSink]="formattedLogger"
- [logCategories]="['rest', 'sse']"
```

```typescript theme={"dark"}
import { formattedLogger, logSink } from '@flowx/core-sdk';

const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] });
```

`@flowx/angular-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Inputs removed or deprecated without replacement

| Input | Status in 6.0 |
| - | - |
| `legacyHttpVersion` | Deprecated, no replacement. Still honored. |
| `debugLogs` | Removed. It never had any effect. Use `logSink()` from `@flowx/core-sdk`. |

#### Behavior changes

* `baseUrl` is required on the process, UI Flow, chat and task management renderers, and `assetsBaseUrl` on the process, UI Flow and chat renderers. Without them, the renderer throws ``[FlowX] `baseUrl` is required.`` (or `` `assetsBaseUrl` ``) at start. The template compiler doesn't report a missing value.
* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [Angular SDK reference](/6.x/sdks/angular-renderer)
>
> Angular renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Helm chart
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart

Upgrade a FlowX.AI installation on the flowx-ai Helm chart from 5.9.x to 6.0.0.

> [!NOTE]
>
> FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

This page covers the Helm side of an upgrade from FlowX.AI 5.9.x to 6.0.0 for an installation that already runs on the `flowx-ai` Helm chart. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list every change in detail. This page puts the ones that need action in the order you do them.

> [!NOTE]
>
> If you still run the per-service charts or the `ai-platform` umbrella chart, move to the `flowx-ai` chart on 5.9.x first, as described in [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart). That migration recreates every workload. Doing it separately keeps the 6.0.0 upgrade a single `helm upgrade` of one release.

## Before you begin

* Read the [FlowX.AI 6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) and [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0).
* Get pull access to the `flowx-ai` chart at the chart version for 6.0.0. The chart version is the platform release.
* Take a backup of PostgreSQL, MongoDB, the object store, and the Qdrant collections right before the upgrade.
* If you run a container app with a FlowX renderer SDK, plan its upgrade with the [renderer SDK guides](./migration-overview#renderer-sdk-migration).

The commands on this page read the namespace from `NS`:

```bash theme={"dark"}
export NS={your-flowx-namespace}
```

## Update your values

**1. Set every group flag explicitly**

Don't rely on the chart's group defaults. Set all four group flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

`base` is the AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and Qdrant. The `devtime` and `runtime` services call it, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

For example, to install the core, base, and runtime services:

```yaml theme={"dark"}
groups:
  core:
    enabled: true
  base:
    enabled: true
  devtime:
    enabled: false
  runtime:
    enabled: true
```

See [AI service groups in the Helm chart](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#ai-service-groups-in-the-helm-chart) for the services in each group, and [How do the switches combine?](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#how-do-the-switches-combine) for how group and service flags combine.

**2. Provision databases and secrets for the services you turn on**

In 6.0.0, these services need their own database users and secrets: agent-builder, dynamic-classifier, and harness in PostgreSQL, and designer-user in MongoDB. Create them before the upgrade for every service your group flags turn on. designer-user is in the `core` group, so it always needs its database.

The `keycloak-flowx-realm-clients` secret needs four new client secret keys, whatever your group flags. authorization-system reads all four at startup and, when it has Keycloak admin access (the default), creates the matching service-account clients with those secrets. If a key is missing, its database migration fails and authorization-system doesn't start. Without Keycloak admin access, create the four clients in Keycloak yourself.

See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the user, secret, key, and client names.

**3. Grant process-engine read access to the integration-designer bucket**

process-engine now reads Kafka payloads that integration-designer stores in its bucket. Give the process-engine credentials `s3:GetObject` on that bucket. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the secret names.

**4. Set a bucket name for dynamic-classifier**

If you turn on dynamic-classifier, set its bucket under `services.dynamic-classifier.component.s3.applicationFileStorage.bucketName`. The chart sets no bucket names, as described in [Migrate S3 buckets](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#migrate-s3-buckets). dynamic-classifier also stores data on a 20Gi `ReadWriteOnce` volume, so your cluster needs a storage class that can provide one.

Unlike the Qdrant volumes, this claim is part of the Helm release. `helm uninstall`, or deleting the Argo CD Application with cascading deletion, deletes it, and with a `Delete` reclaim policy its data too.

**5. Move callers off the removed admin Ingress routes**

If you route with Kubernetes Ingress, the chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier, and the upgrade deletes the existing ones. ai-gateway keeps its own. Platform services and frontends don't use these routes. If anything outside the cluster calls one of these paths on the admin host, such as `/speech-to-text`, move it to the service's in-cluster address before you upgrade.

Installations that use the Gateway API aren't affected.

**6. Allow private MongoDB hosts**

nosql-db-runner now applies its host restriction to external MongoDB connections. Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS` on nosql-db-runner. See [nosql-db-runner host restrictions](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).

**7. Trust your IMAP servers' certificates**

email-gateway now verifies the certificate of every IMAPS server it connects to. Email triggers that read from a server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`. See [IMAPS certificate verification](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway).

**8. Keep the management port private**

Upgrading from 5.9.5 or earlier? Since 5.9.6, advancing-controller no longer reads `MANAGEMENT_SECURITY_ENABLED`, and the actuator endpoints on its management port, `8081`, including Prometheus, answer without authentication. Check that no public Ingress or Gateway route exposes that port. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).

**9. Set the personal-data encryption key**

In 6.0.0, integration-designer needs `FLOWX_PII_ENCRYPTION_MASTER_KEY` for the Mask Personal Data and Restore Personal Data nodes. The variable has no default and the chart doesn't set it, so without it those nodes fail when a workflow runs them. Store a strong random value in a secret under the key `FLOWX_PII_ENCRYPTION_MASTER_KEY`, and load the secret into integration-designer:

```yaml theme={"dark"}
services:
  integration-designer:
    extraEnvVarsSecret: {your-pii-secret-name}
```

Keep the value identical on every pod and stable over time: changing it invalidates every in-flight placeholder map. See [Personal-data encryption master key](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-required-secret-personal-data-encryption-master-key).

**10. Choose how Elasticsearch replicates new indices**

In 6.0.0, process-engine and audit-core create new indices with the Elasticsearch `auto_expand_replicas` setting `0-1`, which overrides `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS`. On a cluster with two or more data nodes, the replica roughly doubles the disk space these indices use. To keep a fixed replica count instead, turn auto-expansion off on both services:

```yaml theme={"dark"}
services:
  process-engine:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
  audit-core:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
```

See [Elasticsearch replica auto-expansion](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-elasticsearch-replica-auto-expansion).

**11. Create the new Kafka topics**

New capabilities since 5.9.x depend on new Kafka topics. Create them before you upgrade. The 6.0.0 [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics) list every topic added since 5.9.6. Upgrading from 5.9.5 or earlier? Also create `ai.flowx.build.deployment-failed.v1`, added in 5.9.6. If your cluster uses ACLs, also give the new clients of three existing topics access, as listed in the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics).

If the chart creates your topics, add the new names to the list under `global.flowx.kafka.topics.topics`. The chart creates topics only when `global.flowx.kafka.topics.enabled` is `true`, as Strimzi `KafkaTopic` resources with 3 partitions and 3 replicas unless you set other values under `global.flowx.kafka.topics.defaults`:

```yaml theme={"dark"}
global:
  flowx:
    kafka:
      topics:
        enabled: true
        topics:
          - ai.flowx.build.deployment-failed.v1
```

## Render and compare

Render the 6.0.0 chart with your updated values before you upgrade, and compare it with what runs today:

```bash theme={"dark"}
helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml
```

Check that the rendered Deployments are the services you expect. A missing AI base service, or an AI runtime service you didn't plan for, means a group flag isn't set. The render fails if your values still contain top-level `devtime` or `runtime` keys, or service keys outside `services`. See [Render and compare](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#render-and-compare) for commands that compare environment variables per Deployment.

Using a mirrored or air-gapped registry? List the images the render references, mirror them, and point the chart at your registry with `global.imageRegistry`, as described in [Container images and registry](/6.x/setup-guides/setup-guides-overview#container-images-and-registry):

```bash theme={"dark"}
grep -E '^\s+image:' rendered.yaml | sort -u
```

## Upgrade

Run `helm upgrade` on your `flowx-ai` release with the 6.0.0 chart version and your updated values:

```bash theme={"dark"}
helm upgrade {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml
```

dynamic-classifier uses the `Recreate` deployment strategy, so its old pod stops before the new one starts.

## After the upgrade

* **Upgrading from 5.9.5 or earlier: re-publish builds that were waiting for a retry.** The retry queue for failed build deployments moves from Redis to PostgreSQL, and deployments waiting in Redis are not moved. 5.9.6 already uses the PostgreSQL queue. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).
* **Check component versions.** In FlowX.AI Designer, go to **Platform Status** and compare the versions with the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#component-versions).
* **Check files from before the upgrade.** Open a process attachment, a media library asset, and a knowledge base document, and confirm they load. A bucket-not-found error in the logs points at a bucket name that didn't carry over.
* **Update name placeholders.** data-privacy now masks names with gendered placeholders, such as `<NAME_F_1>`. Update prompts or scripts that match the old form. See [Name placeholders in data-privacy](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy).
* **Expect a new workspace role name.** Users and groups with the Workspace operations editor role now have the Workspace corrective actions editor role, and keep access to process instance migration and move token. See [Workspace operations editor role replaced](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-workspace-operations-editor-role-replaced).

## Related resources

> [card] [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)
>
> Component versions and every deployment-level change in 6.0.0

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single chart


# iOS SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/ios

Migrate the FlowX iOS renderer SDK from 5.9.x to 6.0.0.

## iOS SDK migration guide

FlowX.AI 6.0 aligns the names of five iOS SDK APIs with the Android and web SDKs. The build requirements and library dependencies are unchanged, and the 5.9 names still compile, so your app builds with the 6.0 SDK after you update the pod version. Replace the deprecated names afterwards.

### System requirements

| Requirement | 5.9.x | 6.0 |
| - | - | - |
| Minimum iOS | iOS 15 | iOS 15 |
| Swift | 5.9 | 5.9 |

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Alamofire](https://github.com/Alamofire/Alamofire) | `~> 5.9.0` | `~> 5.9.0` |
| [SDWebImageSwiftUI](https://github.com/SDWebImage/SDWebImageSwiftUI) | 3.0.3 | 3.0.3 |
| [SDWebImageSVGCoder](https://github.com/SDWebImage/SDWebImageSVGCoder) | `~> 1.7.0` | `~> 1.7.0` |

### Migration steps

**1. Update the SDK version**

```ruby Podfile theme={"dark"}
pod 'FlowXRenderer', '<5.9.x version>' # [!code --]
pod 'FlowXRenderer', '<6.0 version>' # [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Replace the deprecated APIs**

Replace the 5.9 names with the 6.0 names listed in the [Replace deprecated APIs](#replace-deprecated-apis) section. The parameters, types and behavior are unchanged.

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. `imageBaseURL` is a property of `FXConfig`; the others are methods of `FlowX.sharedInstance`:

| Deprecated (5.9) | Replacement (6.0) |
| - | - |
| `imageBaseURL` | `assetsBaseURL` |
| `updateAuthorization(token:)` | `setAccessToken(token:)` |
| `getTag(withKey:)` | `getSubstitutionTagContent(key:)` |
| `getEnumeration(name:parentName:)` | `getEnumerationItems(name:parentName:)`, async and completion versions |
| `continueExistingProcess(uuid:name:…)` | `continueProcess(uuid:name:…)`, all three versions |

> [!TIP]
>
> Xcode shows a deprecation warning on every deprecated call, with a **Fix-it** that replaces it with the new name.

These changes are reflected in an actual implementation as shown below:

```swift theme={"dark"}
// configuration
FXConfig.sharedInstance.configure { config in
    config.imageBaseURL = myImageBaseURL // [!code --]
    config.assetsBaseURL = myAssetsBaseURL // [!code ++]
}

// authorization token changes
FlowX.sharedInstance.updateAuthorization(token: accessToken) // [!code --]
FlowX.sharedInstance.setAccessToken(token: accessToken) // [!code ++]

// substitution tags
FlowX.sharedInstance.getTag(withKey: "@@close_message") // [!code --]
FlowX.sharedInstance.getSubstitutionTagContent(key: "@@close_message") // [!code ++]

// enumerations
let items = await FlowX.sharedInstance.getEnumeration(name: "cities", parentName: "countries") // [!code --]
let items = await FlowX.sharedInstance.getEnumerationItems(name: "cities", parentName: "countries") // [!code ++]

// resuming a process
FlowX.sharedInstance.continueExistingProcess(uuid: uuid, // [!code --]
FlowX.sharedInstance.continueProcess(uuid: uuid, // [!code ++]
                                     name: processName,
                                     navigationController: processNavigationController,
                                     isModal: true)
```

## Related resources

> [card] [iOS SDK reference](/6.x/sdks/ios-renderer)
>
> iOS renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Overview
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview

Migration guide for upgrading container apps and the flowx-ai Helm chart from FlowX.AI 5.9.x to 6.0.0

FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

> [!WARNING]
>
> A FlowX.AI 6.0.0 renderer SDK can need a newer framework version in your container app. Check the guide for your SDK, and upgrade the host app before you bump the FlowX SDK.

## Who is affected

Teams that run a container app with a FlowX renderer SDK (Angular, React, iOS, Android, or React Native) and move it to FlowX.AI 6.0.0. See [Renderer SDK migration](#renderer-sdk-migration).

Teams that run FlowX.AI on the `flowx-ai` Helm chart and upgrade it from 5.9.x to 6.0.0. See [Helm chart upgrade](#helm-chart-upgrade).

Teams with business rules, reusable functions, or workflow scripts that still run on the GraalVM script engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

## What's changing

An upgrade to 6.0.0 touches up to three areas, depending on what you run:

* **Helm chart:** set every AI service group flag explicitly, and create databases and secrets for the new services that need them. See [Helm chart upgrade](#helm-chart-upgrade).
* **GraalVM script engine:** deprecated. Scripts on GraalVM keep running after this upgrade, now with the same time limit as the native engine, and 6.1.x is the last release family that supports the engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).
* **Renderer SDKs:** container apps upgrade the FlowX renderer SDK, and the host framework where the SDK needs it. See [Renderer SDK migration](#renderer-sdk-migration).

## Migration process

Follow these steps in order, and skip the ones for areas you don't run.

**1. Check your starting point**

Upgrade to 6.0.0 from FlowX.AI 5.9.x on the `flowx-ai` Helm chart. If you still run the per-service charts or the `ai-platform` umbrella chart, first [migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart) on 5.9.x, as a separate change.

**2. Read the release notes and deployment guidelines**

The [release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) list what changes in 6.0.0. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list the component versions, environment variables, and other configuration changes. The [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog) lists every feature change since 5.9.x, including the 5.10 to 5.13 feature releases.

**3. Prepare the infrastructure**

Create what the 6.0.0 services need before the upgrade window: new PostgreSQL and MongoDB database users and their secrets, four new keys in the `keycloak-flowx-realm-clients` secret, read access for process-engine to the integration-designer bucket, and storage for a 20Gi `ReadWriteOnce` volume if you turn on dynamic-classifier. Create the new Kafka topics, or list them for the chart to create. Also set the personal-data encryption key for integration-designer, choose how Elasticsearch replicates new indices, and allow the private MongoDB hosts and IMAP servers that existing connections use. [Before you upgrade a self-hosted installation](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#before-you-upgrade-a-self-hosted-installation) is the full checklist, and [Update your values](./helm-chart#update-your-values) walks through each item.

**4. Check GraalVM scripts and plan the move off GraalVM**

Scripts on GraalVM keep running, but from 6.0.0 they stop at the same time limit as the native engine. Before the upgrade, check the scripts that can run longer than the limit, or raise it. Then plan their move to the native engine, as described in [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

**5. Back up**

Take the backups listed in [Before you begin](./helm-chart#before-you-begin) right before the upgrade.

**6. Upgrade the Helm release**

Update your values and upgrade the release, as described in [Helm chart](./helm-chart).

**7. Upgrade your container apps**

For each container app, upgrade the host framework first if the SDK needs it, then the FlowX renderer SDK. See [Renderer SDK migration](#renderer-sdk-migration). Container apps on a 5.9.x renderer SDK keep running against a 6.0.0 backend, but screens can render incorrectly wherever 6.0.0 changed behavior. Release the upgraded apps in the same window as the Helm upgrade. For iOS and Android apps, end users who don't install the app update stay on the 5.9.x SDK, so plan how you move them to the new version.

## Helm chart upgrade

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single `flowx-ai` chart

> [card] [Helm chart](./helm-chart)
>
> Upgrade an installation on the `flowx-ai` Helm chart from 5.9.x to 6.0.0

## Move scripts off the GraalVM engine

The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine for JavaScript and Python. Scripts that run on GraalVM keep running after the upgrade to 6.0.0, but they now stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0, a GraalVM script had no time limit. Before you upgrade, check the GraalVM scripts that can run longer than these limits, or raise the limits, as described in [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits). Then plan the move to the native engine.

**1. Find the scripts that run on GraalVM**

Business rules and reusable functions created before the move to the native engine run on GraalVM unless you switched them. The engine selector in each rule's script editor shows the engine it runs on. Workflow scripts run on GraalVM only if `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`.

**2. Test each script on the native engine**

The two engines don't always write the same output. Follow the step-by-step list in [Port a script from GraalVM to native](/6.x/docs/building-blocks/supported-scripts#port-a-script-from-graalvm-to-native), check the [common pitfalls](/6.x/docs/building-blocks/supported-scripts#common-pitfalls), and search scripts for Python imports the native engine blocks, such as `os` and `subprocess`, JavaScript `require(...)`, `process`, or `global`, and calls into Java classes such as `Java.type(...)`. The native engine supports none of these.

**3. Switch to the native engine**

Switch business rules [per rule](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule). Move a reusable function and the rules that call it together: a function written for GraalVM fails when a rule on the native engine calls it. For workflow scripts, remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer`. The default is `native`.

## Renderer SDK migration

> [card] [Angular SDK](./angular)
>
> Migrate the Angular renderer SDK to 6.0.0

> [card] [React SDK](./react)
>
> Migrate the React renderer SDK to 6.0.0

> [card] [iOS SDK](./ios)
>
> Migrate the iOS renderer SDK to 6.0.0

> [card] [Android SDK](./android)
>
> Migrate the Android renderer SDK to 6.0.0

> [card] [React Native SDK](./react-native)
>
> Migrate the React Native renderer SDK to 6.0.0


# React SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react

Migrate the FlowX React renderer SDK from 5.9.x to 6.0.0.

## React SDK migration guide

6.0 moves the React renderer to Node 26 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new prop and function names. The `logSink` and `logCategories` renderer props are removed and need a code change.

### Framework requirements

React stays on 19. Upgrade Node in your build and CI environments.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| React | 19 | 19 |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |

### FlowX SDK changes

#### Renamed props and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` prop | `baseUrl` |
| `processApiPath` prop | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` prop | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customLoader` prop | `customLoaderProvider` (same shape) |
| UI Flow `appInfo.selectedProcessResourceId` | `resourceId` |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `useEnumeration(name, parentName?)` | `useEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers. `customLoaderProvider` applies to the process and UI Flow renderers.

```diff theme={"dark"}
 <FlxProcessRenderer
-  apiUrl={baseUrl}
-  processApiPath="onboarding"
-  staticAssetsPath={mediaLibraryUrl}
-  authToken={token}
+  baseUrl={baseUrl}
+  enginePath="onboarding"
+  assetsBaseUrl={mediaLibraryUrl}
+  accessToken={token}
   ...
 />
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, file, params?)` to upload a file through an upload action. `params` are sent as extra form fields beside the file.

```typescript theme={"dark"}
input.runAction('action_one', { amount: 3 })
input.runUploadAction('upload_document', file, { side: 'front' })
```

`FlxCustomComponentData` is now generic (`FlxCustomComponentData<TFile = Blob>`) and requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### `logSink` and `logCategories` props removed

The `logSink` and `logCategories` props on `FlxProcessRenderer` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- <FlxProcessRenderer logSink={formattedLogger} logCategories={['rest', 'sse']} ... />
+ import { formattedLogger, logSink } from '@flowx/core-sdk'
+
+ const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] })
```

`@flowx/react-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Props removed or deprecated without replacement

| Prop | Status in 6.0 |
| - | - |
| `legacyHttpVersion` on the process renderer | Deprecated, no replacement. Still honored. |
| `legacyHttpVersion` on the UI Flow renderer | Removed. It never had any effect. |
| `customHeaders` | Removed. It never had any effect. |
| `updateStateEnabled` | Removed. It never had any effect. |
| `isAnonymousMode` | Removed. It never had any effect. |
| `fw` | Removed. It never had any effect. |

Delete the removed props from your process and UI Flow renderer props.

#### Behavior changes

* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [React SDK reference](/6.x/sdks/react-renderer)
>
> React renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# React Native SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react-native

Migrate the FlowX React Native renderer SDK from 5.9.x to 6.0.0.

## React Native SDK migration guide

6.0 moves the validated React Native target to Expo SDK 57 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new configuration and prop names. The Android Material 3 date picker opt-in is removed.

### Prerequisites and version range

The peer dependency floors are unchanged: `react-native` ≥ 0.83.0 and `react` ≥ 19.2.0. The validated target moves up one Expo SDK.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Validated target | Expo SDK 56, React Native 0.85.3 | **Expo SDK 57, React Native 0.86.3** |
| React | 19.2.3 (Expo SDK 56 pin) | 19.2.3 (Expo SDK 57 pin) |
| `react-native-blob-util` | ^0.24.9 | **^0.25.1** |
| `@react-native-community/datetimepicker` | Required peer | **No longer used** |

For an Expo project, align the project to Expo SDK 57, then reinstall the FlowX packages with `npx expo install`:

```bash theme={"dark"}
npx expo install expo@^57.0.0 --fix
```

For the full install command and the Expo SDK 57 reference versions, see the [React Native SDK reference](/6.x/sdks/react-native-renderer).

### FlowX SDK changes

#### Renamed configuration options and props

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `FlxConfig.baseURL`, `apiUrl` prop | `baseUrl` |
| `processApiPath` | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customHeaders` | `additionalHttpHeaders` |
| `customLoader` | `customLoaderProvider` (same shape) |
| `customStepperHeader` | `customStepperHeaderProvider` (same component) |
| `configure({ locale, language })` | `FlowX.changeLocaleSettings(locale?, language?)` |
| `configure({ updateStateEnabled })` | `FlowX.setUpdateStateEnabled(enabled)` |
| `setAccessToken(token: string)` | `setAccessToken(token?: string \| null)`: `null`, `undefined` or `''` switches to anonymous access |
| `processUuid` prop | `processInstanceUuid` |
| `onClose(name?)` | `onDismissRequested(name?)` (same argument) |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl`, `enginePath` and `assetsBaseUrl` apply to `FlowX.configure` and to the process, UI Flow and chat renderers. `onDismissRequested` applies to `startProcess`, `continueProcess`, `startUiFlow` and the process and UI Flow renderers.

In 5.9 the content helpers came only from `@flowx/core-sdk/rn`. `@flowx/react-native-sdk` now exports them too, under their new names only (`getEnumerationItems`, `getMediaItemUrl`, `getSubstitutionTagContent`).

```diff theme={"dark"}
 FlowX.configure({
-  baseURL: 'https://api.example.com',
-  processApiPath: 'onboarding',
-  staticAssetsPath: 'https://media.example.com',
-  customHeaders: { 'x-tenant': 'acme' },
-  language: 'en',
-  locale: 'en-US',
+  baseUrl: 'https://api.example.com',
+  enginePath: 'onboarding',
+  assetsBaseUrl: 'https://media.example.com',
+  additionalHttpHeaders: { 'x-tenant': 'acme' },
   organizationId,
 })
+FlowX.changeLocaleSettings('en-US', 'en')
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, { uri, name, type }, params?)` to upload a file through an upload action.

`FlxCustomComponentData` requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### Android Material 3 date picker removed

The opt-in Material 3 date picker for `FlxDatePicker` on Android is removed, along with the `@react-native-community/datetimepicker` peer dependency.

* Remove `material3` from any `configureFlxUiToolkit` call.
* The `@react-native-community/datetimepicker` package is no longer needed by FlowX. Uninstall it if nothing else in your app uses it.
* Keep the `@flowx/react-native-ui-toolkit` Expo config plugin registered. It no longer changes `AppTheme` or sets `extra.flxUiToolkit.material3`. It now adds `fontScale` to the main activity's `android:configChanges` and declares the microphone permissions used by chat voice input. Run `npx expo prebuild` again after the upgrade.

#### Behavior changes

* A session with no usable access token now starts as anonymous instead of failing. In 5.9, a token that was `null`, `undefined` (never set) or an empty string (`''`) made the start throw `Call FlowX.setAccessToken(...) before starting a process.` In 6.0 all three values start an anonymous session, and a backend that requires a token answers `401`. If your token fetch can return `null`, `undefined` or `''`, check the value before you start a process; otherwise the failure only shows up later as a `401`.
* Error and warning messages name `baseUrl` and `assetsBaseUrl` instead of `baseURL` and `staticAssetsPath`. Update any host code that matches on their text.

## Related resources

> [card] [React Native SDK reference](/6.x/sdks/react-native-renderer)
>
> React Native renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# FlowX.AI 6.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026

What's new in FlowX.AI 6.0: the Developer Agentic Harness builds story by story, plus bulk process-instance migration, scheduled workflows, and certificates.

[FlowX.AI 6.0.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/hero-6.0.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 6.0 is a feature release, live on FlowX.AI SaaS. Self-hosted installations usually wait for the next LTS release family, and can also upgrade to 6.0.0 now: see [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

> [!WARNING]
>
> **Check your existing apps:** 6.0.0 changes how AI node prompts and retries, substitution tags, FlowX Database writes, masked names, IMAPS email triggers, evaluations, 5.1.x exports, and GraalVM scripts behave. See the [upgrade actions](/release-notes/v6.x/5.9-to-6.0-changelog) for what to check in each. Coming from 5.9.x? On the same page, also check the **Changed** entries for 5.10 to 5.13.

> [accordion] What changed since 5.13.0
>
> | 5.13.0 | 6.0.0 |
> | - | - |
> | The harness built the whole approved plan in one run | **Story-by-story delivery**: build one slice of the app, test it, then continue |
> | Changes to the app were described in words | **Comment mode**: select a component in the running app and say what should change |
> | The Command Center and the AI buttons in each editor opened standalone AI agents | **One agent rail**: **⌘K** or the header toggle opens the harness, which uses those agents internally |
> | A workflow started only when a process or caller started it | **Scheduled workflows**: date or cycle schedules on the Start node |
> | TLS was configured with keystores, truststores, and a skip switch | **Trust and Identity**: choose what the host is checked against, and whether to present a client certificate |
> | The Issues Console checked resources only | **Version checks**: entry points, theme, and library dependencies |
> | Only version exports sent notifications | **Import and export notifications**: version imports, build exports, and build imports notify you too |
> | A substitution tag had to be a property's whole value | **Tags inside any text**: `${tag:key}` next to static text and process data |
> | An AI node failed as soon as its AI service or provider couldn't be reached | **AI node retries**: on by default, up to 10 times, 30 seconds apart |
> | The chat message was appended to the end of an AI node's prompt | **Chat message in prompts**: reference `${userMessage}` in **Context** where the agent should answer it |
> | Evaluations grouped test cases into datasets and checked outputs with Code evaluators | **Test cases and asserts**: tagged test cases per workflow, checked with asserts and LLM evaluators |
> | The embedding model was locked once a Knowledge Base held content | **Re-embedding**: change **Containing Personal Information** later and the content is re-embedded |
> | Exporting rows to a file needed a Script node | **Generate Tabular File node**: a CSV or XLSX file from an array of rows |
> | A FlowX Database index couldn't reject duplicate values | **Unique indexes**: **Enforce unique values** on one attribute or a compound key |
> | A sensitive configuration value was shown in the Designer after saving | **Sensitive values stay hidden**: the Designer shows `********` in its place |
> | GraalVM was a supported script engine | **GraalVM deprecated**: 6.1.x is the last release family that supports it |

### **Coming from 5.9.x**

Releases 5.10 to 5.13 shipped to SaaS first. An installation that moves from 5.9.x to 6.0.0 gets their features too, including the [corrective actions](#corrective-actions-on-running-instances) below. The highlights:

> [card] New data sources
>
> [PostgreSQL](/6.x/docs/platform-deep-dive/integrations/postgresql-database) and [Db2](/6.x/docs/platform-deep-dive/integrations/db2-database) databases, and [SOAP services](/6.x/docs/platform-deep-dive/integrations/soap-system) imported from a WSDL.

> [card] Document nodes in workflows
>
> [Fill a template](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) into a PDF or DOCX, [combine](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) or [split](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) PDFs, and [parse](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support) spreadsheets, CSV, XML, and JSON.

> [card] Multi-instance and triggered workflows
>
> Run [one subworkflow per array element](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) in parallel, and start a workflow from an [email or webhook trigger](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).

> [card] Workflow Instances page
>
> [Every workflow run in the project](/6.x/docs/projects/runtime/workflow-instances), filterable by status, date, and origin.

> [card] Branches and the Issues panel
>
> [Merge into any branch](/6.x/docs/projects/managing-applications/versioning#managing-branches), archive or delete branches, and [see validation findings](/6.x/docs/projects/managing-applications/checking-for-issues) in one panel.

> [card] Workflows as agent tools
>
> A Custom Agent node [calls FlowX workflows as tools](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run), each with a hint for when to use it.

Full list: the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog), and the [5.10](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026), [5.11](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026), [5.12](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026), and [5.13](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) release notes.

***

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > The Developer Agentic Harness is the Designer's AI agent: it surveys your app, plans the change, and builds it on its own branch.
> >
> > **Before 6.0:** the harness ran an approved plan as a single run, and a conversation stayed tied to the app and branch where you started it. **Now:** a plan can split the work into stories, each a slice of the app you can try on its own, delivered one story at a time. You can point at a component in the running app to ask for a change. Your conversations follow you across the Designer.
> >
> > Each story says how to test it and what the agent needs from you, so you check one working slice before the next one starts. Comment mode turns the running UI flow or process into the brief: select a component, say what should change, and the comment lands in the conversation with the component attached. A conversation writes to the project and branch set by the first change you confirm, wherever you navigate after that, and the agent asks before it reads beyond that target.
> >
> > > [!NOTE]
> > >
> > > **Removed:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors, such as **Generate** on the data model and the sparkle buttons in business rules, reusable functions, and Script nodes. Open the agent rail instead: press **⌘K** (**Ctrl+K** on Windows and Linux) or select the sparkle toggle in the header. The harness still uses those agents internally for focused generation work. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness#what-the-agent-can-see-and-change).
> >
> > <video>
> >   <track label="English" />
> > </video>
> >
> > See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
>
> > [tab] Key Features
> >
> > > [card] [Story-by-story delivery](/6.x/ai-platform/developer-agentic-harness#how-does-a-plan-with-stories-run)
> > >
> > > Implement the next story, test it with the steps the story gives, then continue with one story or all that remain.
> >
> > > [card] [Comment on the running app](/6.x/ai-platform/developer-agentic-harness#how-do-i-comment-on-the-running-app)
> > >
> > > Select **Comment** in the header, pick a component in the running UI flow or process, and say what should change.
> >
> > > [card] [Conversations that follow you](/6.x/ai-platform/developer-agentic-harness#sessions)
> > >
> > > Every conversation you have in the organization, searchable. Each keeps writing to the project and branch of its first confirmed change, wherever you navigate.
> >
> > > [card] [Asks before reading more](/6.x/ai-platform/developer-agentic-harness#what-happens-when-the-agent-asks-to-read-another-project)
> > >
> > > Read-only access to another project needs **Allow for this conversation**, and you can revoke it from the rail.
> >
> > > [card] [Attach your material](/6.x/ai-platform/developer-agentic-harness#attach-files-to-a-conversation)
> > >
> > > Give the agent PDF and DOCX briefs, screenshots, or BPMN diagrams to plan and build from.
> >
> > > [card] [Delete with a plan export](/6.x/ai-platform/developer-agentic-harness#delete-a-conversation)
> > >
> > > Deleting a conversation keeps its commits on the branch and offers **Export plan** for what wasn't run.
> >
> > > [card] [Entry points, handovers, and repairs](/6.x/ai-platform/developer-agentic-harness#entry-points-handovers-timeouts-and-repairs)
> > >
> > > The agent suggests an entry point and asks again before serving, adds handover buttons, times out workflow waits, and proposes a repair when a step fails, a limited number of times per step.
>
> SaaS

### **Corrective actions on running instances**

> [card] Corrective actions on running instances
>
> > [tab] Overview
> >
> > Corrective actions shipped in the 5.12 and 5.13 feature releases. They fix running process instances in place, without restarting them, from **Runtime** → **Runtime Control** → **Corrective Actions**.
> >
> > **Bulk process-instance migration** moves a filtered set of running instances from one build to another in one run, so a fix made in a newer build reaches instances already in flight. **Move token** takes the active token off the node the instances are stuck on and places it on another node of the same process, and the instances stay on their build.
> >
> > The **Workspace corrective actions editor** role grants both. It replaces the Workspace operations editor role, and the upgrade moves users and groups that had the old role to the new one.
> >
> > See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances) and [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
>
> > [tab] Key Features
> >
> > > [card] [Build to build, in bulk](/6.x/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > Pick the source build, the target build, and the instances to move, then review the eligible count and map any node missing from the target build before you start.
> >
> > > [card] [Move token](/6.x/docs/projects/runtime/active-process/move-token)
> > >
> > > Resume stuck instances from another node of the same process, on one or many instances at once.
> >
> > > [card] [Dedicated role](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix)
> > >
> > > Grant corrective actions without handing out workspace admin rights.
> >
> > > [card] [Notified when done](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification)
> > >
> > > The notification center reports when a bulk migration finishes.
>
> SaaS

### **New Designer header**

> [card] New Designer header
>
> **Before 6.0:** the branch selector, the version state, and **Commit Changes** sat in the project's top bar. **Now:** the header holds the project name, the **Config** / **Runtime** switch (**Config** to edit a version, **Runtime** for builds and their settings), the **Build with AI** and **Comment** toggles, and **Run project**, which starts the version's entry point. Branching, the current version, and **Commit Changes** move to a version block at the start of the footer on Config pages.
>
> ![Designer project on a Config page: the header shows the project name, the Config and Runtime switch, the Build with AI toggle, and Run project; the footer starts with the version block showing the main branch, the version name, and Start New Version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/designer-header-6-0.png)
>
> The Designer also opens the workspace you used last, and **Organization settings** is in the avatar menu. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
>
> SaaS

### **AI node retries**

> [card] AI node retries
>
> **Before 6.0:** an AI node failed as soon as its AI service or LLM provider couldn't be reached. **Now:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when the service is unreachable, the provider is unavailable or rate-limits the request, or the connection fails. Timeouts aren't retried by default, because the node may already have called its tools.
>
> Toggle **Allow Retry** on in the node's **Settings** to set your own count, interval, and exponential backoff. After the last retry, the workflow continues down the node's failure exit if one is connected. With **Allow Retry** on, the workflow run logs show each attempt on its own line.  See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
>
> SaaS

### **Knowledge Base re-embedding and entry lifecycle**

> [card] Knowledge Base re-embedding and entry lifecycle
>
> **Before 6.0:** the embedding model was locked once a Knowledge Base held content. **Now:** turning **Containing Personal Information** on or off later re-embeds the existing content with the new model. Search keeps using the current embedding while it runs, and content changes are locked until it finishes. If some documents fail, the Knowledge Base stays on its previous model and the header says how many weren't re-embedded.
>
> Entries also have their own lifecycle: **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested) and [disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
>
> SaaS

### **Chat message in AI node prompts**

> [card] Chat message in AI node prompts
>
> > [!WARNING]
> >
> > **Behavior change.** The chat message is no longer appended to the end of an AI node's prompt automatically. In chat-driven workflows, reference `${userMessage}` in the node's **Context** wherever the agent should answer the user's message.
>
> The message still reaches the model inside the input data when **Use only referenced values as input** is off. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
>
> SaaS

### **Evaluations: test cases replace datasets**

> [card] Evaluations: test cases replace datasets
>
> **Before 6.0:** test cases lived in datasets, and the Code evaluators checked outputs for an exact, JSON, or Levenshtein match. **Now:** each workflow has its own test cases, grouped by tags. Each case carries its checks: asserts for **equals** and **equals as JSON**, and LLM evaluators with a pass threshold. An experiment runs the test cases you select. See [Evaluations](/6.x/ai-platform/evaluations).
>
> > [!WARNING]
> >
> > **Behavior change.** The upgrade converts each dataset's test cases and keeps the dataset name as a tag, but adds no checks. An experiment skips a case with no enabled check, so add an assert or evaluator to each converted case before you run it. The Code evaluators are removed: use the **equals** assert in place of **Exact match**, and **equals as JSON** in place of **JSON match**. **Levenshtein** has no replacement. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
>
> SaaS

### **Scheduled workflows**

> [card] Scheduled workflows
>
> > [tab] Overview
> >
> > **Before 6.0:** an integration workflow started only when a process, a UI flow, or another caller started it. **Now:** add schedules to the workflow's **Start** node and it starts by itself at each fire time.
> >
> > Schedules fire once on a date or repeatedly on an ISO or cron cycle, and the dialog previews the next fire times in your local time zone. Saving a schedule or publishing a build never turns it on: activate it in **Runtime** → **Runtime Settings** → **Schedules**.
> >
> > See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
>
> > [tab] Key Features
> >
> > > [card] Date or cycle
> > >
> > > Fire once at a date and time, or repeatedly with an ISO or cron expression built from guided fields.
> >
> > > [card] Up to 50 per workflow
> > >
> > > Each schedule has a name that is unique on its workflow. Schedules are available on Output Focused workflows, which process structured input and output.
> >
> > > [card] Explicit activation
> > >
> > > A schedule fires only after you activate it on the **Schedules** page, for a workflow in the project's active build.
> >
> > > [card] Next fire times
> > >
> > > Check the previewed fire times before you save.
>
> SaaS

### **Certificates: trust and identity**

> [card] Certificates: trust and identity
>
> > [tab] Overview
> >
> > **Before 6.0:** a REST data source combined keystore, truststore, and a skip-verification switch in one TLS setup. **Now:** the **Certificates** panel has two independent parts. **Trust** decides what the host's certificate is checked against: **System CAs** (the default), a **Custom CA**, or **None (insecure)**. **Identity** is the client certificate FlowX presents for mutual TLS, turned on with **Present a certificate**.
> >
> > The same panel is available on File Storage data sources. Existing certificate settings are converted to the new model automatically.
> >
> > See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates) for when to use each option.
>
> > [tab] Key Features
> >
> > > [card] Trust per data source
> > >
> > > Changing trust on one data source leaves every other call verified as before.
> >
> > > [card] Mutual TLS when asked
> > >
> > > Present a client certificate only to hosts that require one.
> >
> > > [card] [File Storage too](/6.x/docs/platform-deep-dive/integrations/file-storage#certificates)
> > >
> > > S3-compatible storage uses the same Trust and Identity settings.
> >
> > > [card] Insecure, by name
> > >
> > > **None (insecure)** is labeled as such and accepted only on REST and File Storage data sources.
>
> SaaS

### **Generate Tabular File node**

> [card] Generate Tabular File node
>
> A new node under **Tools** in the workflow palette turns a workflow variable that holds an array of rows into a CSV or XLSX file, stored as a document linked to the workflow run. A workflow can now produce an export without a Script node. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
>
> SaaS

### **FlowX Database unique indexes**

> [card] FlowX Database unique indexes
>
> Toggle **Enforce unique values** when you add an index to reject documents that repeat a value already stored, on one attribute or on a compound key, with an option to exempt documents that leave the key empty. Existing duplicates are reported when you run **Apply Indexes**, before the index is created. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
>
> SaaS

### **Issues Console version checks**

> [card] Issues Console version checks
>
> **Before 6.0:** an Issues Console check, which validates the resources in a project version, covered processes, UI flows, and integration workflows. **Now:** it also checks the version itself: missing, broken, or mismatched entry points, a theme that isn't in the workspace, library builds that are missing directly or transitively, and dependencies the version doesn't use. Selecting a finding opens the version settings or the **Dependencies** page, where you fix it. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
>
> SaaS

### **Import and export notifications**

> [card] Import and export notifications
>
> The notification center now covers version imports and build exports and imports, alongside version exports and process instance migrations. Each operation notifies you when it starts and replaces that entry with its result: ready to download, imported, needs review with a conflict or excluded-resource count, failed, or timed out. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
>
> SaaS

### **Resource documentation**

> [card] Resource documentation
>
> Open **Documentation** from a resource's menu to give it a short description and longer Markdown documentation, written and previewed in the same window. Media Library assets in a project library get a description too, used as the image's alt text in the asset preview. Knowledge base stores, navigation areas, and user tasks in the process navigation panel have **Documentation** in their menus too. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
>
> SaaS

### **Sensitive values stay hidden**

> [card] Sensitive values stay hidden
>
> After you save a `value` configuration parameter with **Sensitive** on, the Designer shows `********` in place of the value in the parameters list, overrides, build details and lists, and the merge view. The real value is still used at runtime, and editing other fields keeps it. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
>
> SaaS

### **Substitution tags inside any text**

> [card] Substitution tags inside any text
>
> > [tab] Overview
> >
> > **Before 6.0:** a substitution tag resolved only when it was the whole value of a property, so `@@greeting ${firstName}` rendered as empty text. **Now:** write `${tag:key}` anywhere in a component's text, next to static text and process data, and the renderer fills in every tag: `${tag:greeting}, ${firstName}!` renders as "Hello, John!".
> >
> > The upgrade rewrites whole-value `@@key` references to `${tag:key}` in processes, UI flows, and reusable templates, so existing screens render as before. `@@key` keeps working as a whole value.
> >
> > See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).
>
> > [tab] Key Features
> >
> > > [card] Tags, text, and data together
> > >
> > > Use several tags and process data placeholders in one label, placeholder, message, validator message, or option label.
> >
> > > [card] Existing references converted
> > >
> > > Whole-value `@@key` references become `${tag:key}`. Option values and the default of choice components stay `@@key`.
> >
> > > [card] Task Manager columns
> > >
> > > A column value of exactly `${tag:key}` shows, filters, and sorts like `@@key`.
> >
> > > [card] Import from and export for 5.9
> > >
> > > Importing from 5.9 converts `@@key` forward. Exporting for 5.9 converts whole-value tags back to `@@key`.
>
> SaaS

### **GraalVM script engine deprecated**

> [card] GraalVM script engine deprecated
>
> The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports it, for every JavaScript and Python script: business rules, reusable functions, workflow Script nodes, and the rest. Scripts that run on GraalVM keep working in 6.0.0. Move them to the native engine, the default since 5.9.0, before support ends. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).
>
> **Time limits on GraalVM too:** scripts that run on GraalVM now stop at the same per-language time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default, set on the process engine and Integration Designer with `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` and `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`. Before 6.0.0, a GraalVM script had no time limit. A script that runs past its limit is stopped and fails with an error saying it did not finish within its time limit. Before you upgrade, check GraalVM scripts that can run longer than these limits, or raise the limits. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
>
> All Deployments

### **Smaller improvements**

> [card] Smaller improvements
>
> **Auto-arrange on both canvases:** select **Auto-arrange** on the workflow canvas, or **Arrange** on the process canvas, to see a tidied layout in the **Layout preview** bar before anything moves. Compare it with the current layout, then **Apply** or **Cancel**. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).&#x20;
>
> **Timers in local time:** timer nodes now use the same editor as workflow schedules. Dates and times you pick are in your local time and saved in UTC, one control switches between **Guided**, **Expression**, and **Process variable** entry, and cycle timers preview their next fires. Timers saved with the earlier date pickers can look shifted by your UTC offset in the panel, but they still fire at their stored time. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).&#x20;
>
> **Longer branch names:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).&#x20;
>
> **Organization branding:** a **Branding** page under **Organization settings** > **Customization** sets one brand for the organization: name, logos, legal and social links, container app colors and header, and the sender, signature, and text of the invite, verify email, and reset password emails, with a preview of each. Login page and email branding are available on FlowX SaaS only. See [Organization branding](/6.x/docs/saas/organization-branding).&#x20;
>
> **Typed dates in the Datepicker:** turn on **Allow manual input** to let users type a date in the pattern of the project's default locale instead of picking it. Web only, and not available while **Legacy component** is on.&#x20;
>
> **Data mapping creates data types:** type a new attribute path such as `client.address.street`, and saving the mapping creates the data types it names. Until then, the mapper marks them as not yet added to the data model. Required rows show an asterisk, and mapping an object onto a primitive field shows an error.&#x20;
>
> **Removed fields stay removed:** when a node's output sets a field to `null`, the field is removed from the workflow data and later steps no longer restore it with a `null` value. If a condition checks for `null`, make it handle a missing field too.&#x20;
>
> **Keys with dots stay whole:** a data key that contains a dot, such as `cash|31.12.2025`, now stays one key when a workflow saves its data. Before, the key was split into nested objects and later nodes could not read it.&#x20;
>
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, and Kafka topics, see [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0). To upgrade the Helm chart or a renderer SDK, follow [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).


# Deployment guidelines v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/deployment-guidelines-v4.6.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.

## Component versions

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.1.1** | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.6** | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.2** | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | 4.1.3 | 4.1.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.4** | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.25** | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.4** | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.11** | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

> [!NOTE]
>
> Note: The same container image and Helm chart are used for **Application Manager** and **Runtime Manager**.

## AI Agents

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.16** | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.15** | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.6** | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.27** | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.6.5** | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.1 | Keycloak | 22.x |
| 4.6.1 | Kafka | 3.2.x |
| 4.6.1 | PostgreSQL | 16.2.x |
| 4.6.1 | MongoDB | 7.0.x |
| 4.6.1 | Redis | 7.2.x |
| 4.6.1 | Elasticsearch | 7.17.x |
| 4.6.1 | Oracle Database | 21C/ 21-XE |
| 4.6.1 | Angular (Web SDK) | 19.x |
| 4.6.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.


# FlowX.AI 4.6.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025

FlowX.AI 4.6.1 is here with important fixes and improvements to keep things running smoothly. No new features this time—just focused updates to improve stability, fix bugs, and enhance overall performance. Simple, clean, and efficient.

## **What's new?** 🆕

### Rendering

**Form Elements** improvements:

* **Default Value Handling**: Defaults are applied only when no existing value is found, and set upon first display (with specific exceptions).
* **Data Consistency**: Form elements now save data in standardized formats based on type for improved reliability.
* **Smart Defaults**: Clear fallback behaviors for elements like switches, sliders, and checkboxes when no value is present.
* **Synchronized Inputs**: Linked form elements (e.g., input + slider) stay in sync with automatic value adjustments within set limits.
* **Dynamic Dependencies**: Form elements can dynamically adjust based on related components’ values for greater flexibility.

### Merge conflicts

* Improvement: merged version is now selected after a successful merge in versioning modal.

## Bug fixes 🐞

### Merge conflicts

* Fixed an issue that caused conflicts involving notification and document templates to fail.
* Fixed an issue where merges failed when a deleted configuration parameter was updated on a branch.
* Fixed an issue that resulted in duplicate substitution tag keys appearing in the merged version.
* Fixed an issue where merges failed due to the same dependency being added to both the source and target branches.
* Fixed issues related to workflow conflicts.

### Rendering

* Fixed an issue where documents from the media library were not loading correctly when added as a file preview in a user task.

### Integration Designer

* Fixed issue causing a 400 error when adding an enum mapper to the body tab due to incorrect data validation.
* Fixed issue where the last attribute in the objects table was not visible at higher zoom levels due to UI rendering constraints.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.1](./deployment-guidelines-v4.6.1)

Migrating from v4.6.0:

> [card] [Migrating from previous versions](./migrating-from-v4.1.x-to-v4.6.1)


# Deployment guidelines v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/deployment-guidelines-v4.7.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.0 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.
>
> In version 4.7, the import-export functionality for application-version is no longer backward compatible.
>
> * Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
>
> * Similarly, zip files from earlier versions cannot be imported into 4.7.
>
> Note: Zip files for builds and specific resources remain unaffected.

## Component versions

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.3.1** | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.5.1** | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.11** | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.2** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.5** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.0** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.1** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.2** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.4** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.4** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.3** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.2** | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.1.0** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.5** | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.12** | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.21** | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.7.2** | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.13** | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.31** | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.0** | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.0 | Keycloak | 22.x, 26.x |
| 4.7.0 | Kafka | 3.2.x |
| 4.7.0 | PostgreSQL | 16.2.x |
| 4.7.0 | Oracle Database | 21c, 23ai |
| 4.7.0 | MongoDB | 7.0.x |
| 4.7.0 | Redis | 7.2.x |
| 4.7.0 | Elasticsearch | 7.17.x |
| 4.7.0 | Angular (Web SDK) | 19.x |
| 4.7.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/migrating-from-v4.1.x-to-v4.7.0

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025

FlowX.AI 4.7.0 is here to keep your projects vibing, your merges drama-free, and your configs under control—because struggling with your platform is *so* last season. 😎🔥

## What's new? 🆕

✅ Copy resources across projects\
✅ Duplicate resources (in the same project/library)\
✅ Resources usage tracking\
✅ Smarter merge conflict detection & resolution\
✅ Libraries can now define configuration parameters\
✅ Dynamic Kafka topics using configuration parameters

## Projects

### Copy resources across projects

Moving resources between projects is now **fast and seamless**. The new **Copy to Another Project** feature ensures all dependencies stay intact, eliminating the hassle of manual adjustments.

<video />

> [tab] How it works
>
> 1️⃣ **Select a destination** – Choose the target project or library.\
> 2️⃣ **Pick a branch (if applicable)** – For WIP versions, select the target branch.\
> 3️⃣ **Review dependencies** – The system displays referenced resources and validates dependencies.\
> 4️⃣ **Resolve identifier conflicts** – If an identifier already exists in the destination, you'll be prompted to either:
>
> * **Keep both** (create a duplicate)
> * **Replace** (overwrite the existing resource)
> * **Use destination** (retain the existing resource without copying)

> [tab] Why it’s better
>
> * **No broken references** – Everything stays connected.
> * **Auto-add missing dependencies** – No manual setup required.
> * **Works with WIP & committed versions (only from committed to WIP)** – Flexibility for your workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.48.33.png)

> [card] [Copy resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Duplicate resources

> [tab] What you can duplicate
>
> The **Duplicate Resource** feature lets users create a copy of an existing resource within the same project or library version, streamlining workflows and ensuring quick reusability.
>
> <video />
>
> You can duplicate the following resources:
>
> * **Processes**
> * **Enumerations**
> * **Media files (including Global media library files)**
> * **Notification templates**
> * **Document templates**
> * **Views**

> [tab] How it works
>
> * **Duplicate options** are available from each resource’s three-dot menu (table row & secondary navigation).
> * When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).
> * **Cancel** to discard changes or **Duplicate** to create an exact copy in the same project/library version.
> * **Success confirmation:** The system navigates to the newly created resource and displays a success message.
> * **Error handling:** If a resource with the same name/key exists, users will be prompted to rename it before proceeding.

> [tab] Why it’s useful
>
> 💡 **Use cases:**
>
> * Quickly iterate on existing resources.
> * Reduce redundant manual setup.
> * Maintain consistency within projects.
> * Easily clone complex configurations for testing and modifications.

> [card] [Duplicate resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Track where your resources are used

Monitoring your resources has never been simpler and more efficient. Stay on top of where and how they’re being used.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

> [card] [Process Usage](../../4.7.x/docs/projects/resources#process-usage)
>
> Track where a process is referenced, with a clear **Usage Overview modal** that dynamically updates when references change.

> [card] [Enumeration Usage](../../4.7.x/docs/projects/resources#enumeration-usage)
>
> See where enumerations are used across **UI, Data Models, Systems, and Workflows** before making changes.

> [card] [Media Library Usage](../../4.7.x/docs/projects/resources#media-library-usage)
>
> Identify **which UI elements reference media assets** so you don’t accidentally break designs.

📌 **Before deleting a resource, a confirmation modal lists all affected references. No more surprises!**

***

### Configuration parameters overrides

🔹 **Libraries can now define configuration parameters** to help test processes or workflows that use those parameters.

🔹 However, **libraries do not support overrides**.

* **Overrides for library config parameters must be done within a project** where the library is added as a dependency.
* **Overrides cannot be added in libraries directly.**

<video />

💡 **What this means:**

* Libraries provide **default values** for configuration parameters.
* Projects using those libraries **can override these values** as needed.
* This ensures **clear separation between library defaults and project-specific configurations** while maintaining flexibility.

> [!TIP]
>
> ✨ **Overrides take precedence** over library values—so you stay in control.

***

### Merge conflict enhancements

Merge conflicts are never fun, but at least now they’re **easier to handle**.

> [card] Better Conflict Detection
>
> 🚨 Prevents merging if identical resource identifiers exist in both branches (e.g., same name, key, or code).

> [card] Resizable Merge Conflict Tree
>
> 🖥️ Resize the merge conflict tree for better visibility and navigation.

> [card] New Conflict Type
>
> 📢 A new conflict detection system for parent changes/deletions in both branches.

***

## SDK changes

### Expose Enumerations API in Angular SDK

Developers can now dynamically retrieve enumerations via the Angular SDK, making it easier to use enums in custom components like dropdowns.

> [!TIP]
>
> How it Works?
>
> A new method in the Angular SDK allows direct access to enumerations, reducing manual imports and improving flexibility.

**Usage**

The `getEnumeration()` function returns key-value pairs that can be used in components that need enumeration data:

```typescript theme={"dark"}
getEnumeration(enumName: string): { value: string; label: string }[]
```

* `enumName` (string) – The name of the enumeration to retrieve (e.g., 'UserRoles', 'cities')
* Returns: An array of objects containing value-label pairs representing the requested enumeration

> [accordion] Example usage
>
> The enumeration service works seamlessly with Angular's resource API for reactive state management:
>
> ```typescript theme={"dark"}
> import { Component, effect, model, resource } from '@angular/core';
> import { getEnumeration } from '@flowx/angular-sdk';
>
> @Component({
>   selector: 'app-dynamic-enum-select',
>   template: `
>     <select>
>       @for (option of options.value(); track option.value) {
>         <option [value]="option.value">{{ option.label }}</option>
>       }
>     </select>
>
>     <button (click)="enumName.set('cities')">Load Cities</button>
>     <button (click)="enumName.set('countries')">Load Countries</button>
>   `
> })
> export class DynamicEnumSelectComponent {
>   // Create a signal to track the currently selected enum
>   enumName = model<string>('UserRoles');
>
>   // Use resource API to reactively load enumerations when enumName changes
>   options = resource({
>     request: this.enumName,
>     loader: ({ request: enumName }) => getEnumeration(enumName),
>   });
>
>   constructor() {
>     effect(() => {
>       if (this.options.isLoading()) {
>         console.log(`Loading enumeration: ${this.enumName()}`);
>       } else {
>         console.log(`Loaded enumeration: ${this.enumName()}`, this.options.value());
>       }
>     });
>   }
> }
> ```

***

## **Bug fixes** 🐞

✔️ Improved **merge conflict detection and resolution**\
✔️ Fixed **UI rendering issues**

***

## Changes

### Dynamic Kafka topics

FlowX 4.7.0 introduces **Dynamic Kafka Topics**, enabling more flexible and configurable messaging across processes.

🔹 **What’s new?**

* Use **Configuration Parameters** to dynamically assign Kafka topics in **Kafka Send** and **Kafka Receive** actions.
* Concatenate predefined parameters with process variables for **on-the-fly topic selection**.
* Reduce hardcoded values and **simplify environment-specific configurations**.

💡 **Why it matters:**

* Makes **Kafka integrations more scalable** across different deployments.
* Supports **multi-topic messaging** for different use cases without manual updates.
* Ensures better **reusability and maintainability** in process configurations.

📌 Check the [Kafka Send Action](../../4.7.x/docs/building-blocks/actions/kafka-send-action#dynamic-kafka-topics) section for setup details.

***

### Export/import compatibility

In version 4.7, the import-export functionality for application-version is no longer backward compatible.

* Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
* Similarly, zip files from earlier versions cannot be imported into 4.7.

> [!NOTE]
>
> Zip files for builds and specific resources remain unaffected.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.0](./deployment-guidelines-v4.7.0)\
📌 [Migration Guide (from v4.6.0)](./migrating-from-v4.1.x-to-v4.7.0)


# Deployment guidelines v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/deployment-guidelines-v4.7.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.1.

## Component versions

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.5.1** | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.7.6** | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.3.3** | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.4** | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.7** | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.3** | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.4** | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.6** | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.6** | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.6** | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.5** | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.9** | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.2** | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.7** | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.13** | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.27** | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.2** | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.17** | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.35** | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.4** | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.1 | Keycloak | 22.x, 26.x |
| 4.7.1 | Kafka | 3.2.x |
| 4.7.1 | PostgreSQL | 16.2.x |
| 4.7.1 | Oracle Database | 21c, 23ai |
| 4.7.1 | MongoDB | 7.0.x |
| 4.7.1 | Redis | 7.2.x |
| 4.7.1 | Elasticsearch | 7.17.x |
| 4.7.1 | Angular (Web SDK) | 19.x |
| 4.7.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/migrating-from-v4.1.x-to-v4.7.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025

FlowX.AI 4.7.1 brings enhanced resource navigation, better error detection, and workflow improvements to make your development journey even smoother! 🚀

## What's new? 🆕

✅ Enhanced resource usage tracking with direct navigation\
✅ Upgraded JavaScript support to ECMAScript 15 (2024) in Business Rules\
✅ Added Python 3 support with 3x performance improvement\
✅ Major performance enhancements for both design time and runtime\
✅ Security enhancements for runtime endpoints

## Projects

### Enhanced resource usage navigation

We've significantly improved how you navigate between resources and their references with direct navigation capabilities. Now you can easily jump from the usage tracking panel to the exact location where a resource is referenced.

<video />

> [tab] How it works
>
> 1️⃣ **Access resource usage** – View where a resource is being used through the usage panel.\
> 2️⃣ **One-click navigation** – Use the new redirect button to jump directly to the referenced location.\
> 3️⃣ **Missing resource detection** – Easily identify and fix missing resource references with clear indicators.

> [tab] Why it's better
>
> * **Faster troubleshooting** – Directly navigate to problem areas without manual searching.
> * **Improved productivity** – Less time spent hunting down references means more time building.
> * **Better error prevention** – Quickly spot and fix missing resources before they cause issues.

***

## Enhanced scripting capabilities

### ECMAScript 15 (2024) support for Business Rules

FlowX.AI 4.7.1 brings the latest JavaScript features to your business rules with an upgrade to ECMAScript 15 (2024).

> [tab] What's included
>
> * Access to the latest JavaScript language features
> * Modern syntax for cleaner, more maintainable rules
> * Enhanced tooling and IDE support

> [tab] Benefits
>
> * Write more concise and expressive business rules
> * Leverage modern JavaScript patterns and best practices
> * Improved developer experience with better IDE integration

> [!NOTE]
>
> **Important Configuration Note:** Nashorn engine remains the default runtime. To enable GraalJS support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Nashorn will be used.

### Python 3 support for Business Rules

We've upgraded our Python scripting capabilities to Python 3, delivering significant performance improvements while maintaining compatibility.

> [card] 3x Faster Execution
>
> Python scripts now run at least 3 times faster than with Python 2.7.

> [card] Modern Python Features
>
> Take advantage of Python 3's improved syntax, libraries, and security features.

> [!NOTE]
>
> **Important Configuration Note:** Python 2.7 remains the default runtime. To enable Python 3 support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Python 2.7 will be used.

More details about the scripting capabilities can be found in the [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts) section.

***

## Performance improvements 🚀

We've made significant performance enhancements throughout the platform to make your development and runtime experience smoother and faster.

### Design time improvements

For large processes, you'll notice dramatic improvements:

| Operation | Improvement |
| - | - |
| Cloning a process | **5x faster** |
| Opening a process | **70x faster** |

### Runtime enhancements

Platform average response time has been **reduced by 20%** in our comprehensive benchmark\*.

> [!NOTE]
>
> \*The benchmark simulates a typical business process with a combination of user and service tasks. It includes rules that automate decision-making, as well as events for time-sensitive actions and communication. The process also covers various system functions, ensuring the platform can efficiently manage complex workflows with both individual and parallel tasks.

***

## Security enhancements 🔒

We've significantly improved platform security by implementing proper endpoint access controls and separation between internal and public-facing APIs.

> [card] Enhanced API Security
>
> Runtime execution proxy vulnerability addressed with comprehensive endpoint updates.

> [card] Access Control Improvements
>
> Better separation between design-time and runtime endpoints with proper access controls.

### Endpoint security updates

We've implemented a comprehensive security update for runtime endpoints to prevent potential proxy vulnerabilities:

* Redesigned API structure to separate internal (`runtime-internal`) from external-facing (`runtime`) endpoints
* Migrated design-time operations to use `runtime-internal` endpoints for enhanced security
* Moved specific management operations to dedicated `build-mgmt` endpoints
* Updated all API clients to use the new secure endpoints

> [!NOTE]
>
> **Important:** Make sure to update to the corresponding  version of the [**`flowx-admin`**](./deployment-guidelines-v4.7.1#component-versions) to benefit from these security enhancements.

### Enhanced resource caching in Angular SDK

The Angular SDK now includes an improved caching mechanism for CMS resources, optimizing loading times and performance. The cache parameter on the `flx-process-renderer` component allows developers to control caching behavior in different environments.

> [card] [Read about caching in Angular SDK](../../4.7.x/sdks/angular-renderer#caching)
>
> Find details on controlling CMS resource caching during development and production.

## **Bug fixes** 🐞

* Fixed various minor issues to improve overall stability
* Resolved some UI inconsistencies
* Addresses performance optimizations
* Fixed general usability issues

***

## **Additional information**

📌 [Deployment Guidelines v4.7.1](./deployment-guidelines-v4.7.1)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.1)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.10
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/deployment-guidelines-v4.7.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.3** | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.8** | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.6** | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.5** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.4** | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.6** | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.4** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.3** | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.6** | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.2** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.32** | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.24** | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.10 | Keycloak | 22, 26+ |
| 4.7.10 | Kafka | 3.2 - 3.9 |
| 4.7.10 | PostgreSQL | 16 - 17 |
| 4.7.10 | OracleDB | 19c, 21c, 23ai |
| 4.7.10 | MongoDB | 7 - 8 |
| 4.7.10 | Redis | 7.2 - 8.0 |
| 4.7.10 | Elasticsearch | 7 - 8 |
| 4.7.10 | Angular (Web SDK) | 19.x |
| 4.7.10 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.10 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Updated Spring Boot to the latest release for enhanced security and performance\
✅ Updated Java libraries to fix vulnerabilities across all images\
✅ Selectors support for substitution tags across all platforms (Web, iOS, Android)\
✅ System substitution tags on all task management texts\
✅ CMS - Added system substitution tags with migration script support

### Security and Platform Updates

This release includes critical security updates to ensure your FlowX.AI platform remains secure and up-to-date:

* **Spring Boot Update**: Updated to the latest release on the 4.7.x LTS branch
* **Java Libraries Update**: Updated Java libraries to fix vulnerabilities across all LTS 4.7.x images

### Selectors Support for Substitution Tags

You can now use selectors with substitution tags when the source type is process data across all platforms (Web, iOS, and Android). This enhancement provides more flexibility in displaying dynamic content from your process data in selector components.

**Available on:**

* Angular Web Renderer
* React Web Renderer
* iOS Renderer

### System Substitution Tags for Task Management

Task management now includes comprehensive system substitution tags support:

* **Backend CMS**: Added system substitution tags with a migration script to help you transition existing content
* **Web Renderers**: System substitution tags are now available on all task management texts across Angular and React renderers
* This allows for more dynamic and flexible task management configurations

## Bug fixes

> [accordion] \[Designer] Error when copying/pasting nodes with misconfiguration
>
> Fixed an issue where attempting to copy and paste nodes with misconfigurations, or importing an app version/build with misconfigured nodes, would result in an error. The system now handles misconfigured nodes gracefully during these operations.
>
> **Issue**: Error when trying to copy and paste nodes with misconfiguration or import an app version/build with nodes with misconfigurations

> [accordion] \[React] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the React renderer.
>
> **Issue**: \[React] Card not expandable after finishing subprocess started from it

> [accordion] \[Angular] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the Angular renderer.
>
> **Issue**: \[Angular] Card not expandable after finishing subprocess started from it

> [accordion] \[React] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the React renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[React] Card shouldn't collapse when next nav area is modal

> [accordion] \[Angular] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the Angular renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[Angular] Card shouldn't collapse when next nav area is modal

> [accordion] \[Backend] Task Manager - System substitution tags not displayed in column names
>
> Fixed an issue where system substitution tags were not being displayed in the `columns.displayName` property of the Task Manager backend.
>
> **Issue**: \[BE] Task manager | System substitutionTags are not displayed in columns.displayName

> [accordion] \[Web Renderers] Task Manager - Substitution tags value override
>
> Resolved an issue where system substitution tags values were incorrectly overriding custom substitution tags when the value was not null in both React and Angular renderers.
>
> **Issue**: \[React]\[Angular] Task manager | System subTags values override de custom subTags when value is not null

> [accordion] \[Task Manager] Missing localization for Russian and Uzbek in table view
>
> Fixed localization support in Task Manager table view for Russian and Uzbek languages, ensuring proper display of translated content.
>
> **Issue**: \[Task manager localisation] Table view - Missing localisation support for Russian and Uzbek

> [accordion] \[Task Manager] View search field placeholder not localized
>
> Resolved an issue where the view search field placeholder in Task Manager was not being localized for any language. The placeholder now properly supports all configured languages.
>
> **Issue**: \[Task manager localisation] View search field placeholder not localised for any language


# Deployment guidelines v4.7.11
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/deployment-guidelines-v4.7.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.6** | 8.24.3 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.12** | 7.18.8 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.9** | 5.11.6 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.8** | 6.8.5 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.7** | 6.10.4 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.9** | 7.9.6 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.7** | 6.8.4 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.6** | 2.16.3 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.9** | 2.10.6 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.103.6** | 5.101.2 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.32 | 4.0.32 | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.27** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.25** | 1.8.24 | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.11 | Keycloak | 22, 26+ |
| 4.7.11 | Kafka | 3.2 - 3.9 |
| 4.7.11 | PostgreSQL | 16 - 17 |
| 4.7.11 | OracleDB | 19c, 21c, 23ai |
| 4.7.11 | MongoDB | 7 - 8 |
| 4.7.11 | Redis | 7.2 - 8.0 |
| 4.7.11 | Elasticsearch | 7 - 8 |
| 4.7.11 | Angular (Web SDK) | 19.x |
| 4.7.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.11 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025

Security and maintenance updates for the 4.7.x LTS release

## What's new?

This is a **security and maintenance release** for the FlowX.AI 4.7.x LTS branch, focused on keeping your platform secure and up-to-date with the latest security patches.

✅ **Security Updates** - Updated core libraries and dependencies to address known vulnerabilities\
✅ **Platform Stability** - Improved overall platform security and stability

***

## Migration notes

> [!WARNING]
>
> As this is a **patch release** on the 4.7.x LTS branch, it is designed to be a **drop-in replacement** with no breaking changes.

***

## Component versions

All FlowX.AI components have been updated to version **4.7.11** with the security patches applied. Refer to the deployment guidelines for the complete list of component versions.


# Deployment guidelines v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/deployment-guidelines-v4.7.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.2 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.2.

## Component versions

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.9.0** | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.5** | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.8** | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.10** | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.16** | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.12** | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.13** | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.14** | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.13** | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.14** | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.2.0** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.12** | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.16** | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.9** | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.35** | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.9** | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.24** | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.1** | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.9** | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.2 | Keycloak | 22.x, 26.x |
| 4.7.2 | Kafka | 3.2.x |
| 4.7.2 | PostgreSQL | 16.2.x |
| 4.7.2 | Oracle Database | 21c, 23ai |
| 4.7.2 | MongoDB | 7.0.x |
| 4.7.2 | Redis | 7.2.x |
| 4.7.2 | Elasticsearch | 7.17.x |
| 4.7.2 | Angular (Web SDK) | 19.x |
| 4.7.2 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## Additional configuration

Added new environment variable on Process Engine:

### Message routing configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

> [!NOTE]
>
> When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.


# Migrating from previous versions to v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/migrating-from-v4.1.x-to-v4.7.2

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 and v4.7.1 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.2 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025

FlowX.AI 4.7.2 delivers improved merge conflict handling with retry capabilities, deprecates DMN business rules, and fixes issues with subprocess handling, media file imports, and OCR functionality to enhance your development workflow! 🚀

## **What's new? 🆕**

✅ Improved merge conflict handling with retry functionality\
✅ Enhanced error messages during failed merges\
✅ Streamlined workflow for resolving merge conflicts

## Merge conflicts

### Improved error messages when merge fails

We've enhanced the merge conflict resolution experience with more informative error messages and a new retry functionality:

* When a merge fails, users can now see a "Retry merge" button on the Merge failed modal
* Clicking this button allows users to attempt the merge again without losing previous work

The system now handles two distinct scenarios:

**1. When conflicts exist:**

* The system opens the Merge conflicts panel with the previous state of the merge before the failed attempt
* This preserves all your conflict resolution work so you can fix the specific issues that caused the failure

![Merge failed with conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20conflicts.png)

**2. When no conflicts exist:**

* The system automatically retries the merge operation
* This streamlines the workflow when the merge failure was due to temporary issues rather than actual conflicts

![Merge failed without conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20no%20conflicts.png)

## Process engine

### Deprecated DMN rules

In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.

**What's changing:**

* DMN is no longer available as a language option when configuring business rule actions

**What's next:**
For guidance on using alternative business rule languages, please refer to our [supported scripting languages](../../../../4.7.x/docs/building-blocks/supported-scripts) documentation.

## **Bug fixes** 🐞

* Resolved export/import issues with media library files, particularly for applications migrated from earlier versions
* Fixed an issue where parallel multi-instance Call Activity would incorrectly trigger a subprocess when using an empty array list as a variable
* Fixed a display issue where not all subprocesses were visible in the subprocess list on smaller screens
* Fixed a bug where message events couldn't be caught when placed directly after an uninterrupting timer event
* Resolved "Unsupported Media Type" errors when importing application versions with media file binaries
* Fixed an issue where color palette changes in Theme settings couldn't be saved at 100% browser resolution on smaller screens
* Fixed a issue where OCR plugin failed due to missing correlation headers

***

## **Additional information**

📌 [Deployment Guidelines v4.7.2](./deployment-guidelines-v4.7.2)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.2)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/deployment-guidelines-v4.7.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.3 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.3.

## Component versions

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.13.0** | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.13** | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.12** | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.11** | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.17** | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.13** | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.16** | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.15** | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.14** | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.15** | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.14** | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.6.0** | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.11** | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.14** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.15** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.37** | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.12** | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.26** | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.3** | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.11** | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.3 | Keycloak | 22.x, 26.x |
| 4.7.3 | Kafka | 3.2.x |
| 4.7.3 | PostgreSQL | 16.2.x |
| 4.7.3 | Oracle Database | 21c, 23ai |
| 4.7.3 | MongoDB | 7.0.x |
| 4.7.3 | Redis | 7.2.x |
| 4.7.3 | Elasticsearch | 7.17.x |
| 4.7.3 | Angular (Web SDK) | 19.x |
| 4.7.3 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/migrating-from-v4.1.x-to-v4.7.3

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.3 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025

FlowX.AI 4.7.3 enhances workflow conflict resolution, adds configurable enumeration ordering, and fixes data streams, UI templates, and application export/import issues to improve your development experience! 🚀

## **What's new? 🆕**

✅ Enhanced workflow conflict resolution with improved visibility\
✅ Added ability to configure order attributes on enumerations\
✅ Upgraded conflict management interface for better user experience

## Merge conflicts - workflow improvements

### Enhanced workflow conflict resolution

We've significantly improved how [**workflow**](../../4.7.x/docs/platform-deep-dive/integrations/integration-designer#workflows) conflicts are handled in this release:

* Upgraded to a new version (v2) of the workflow conflict resolution interface
* Now only showing workflow entities that have actual conflicts, making it easier to identify and address issues
* Streamlined the conflict resolution process for a more efficient workflow

![Workflow conflict resolution](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/workflow_conflicts.png)

> [!NOTE]
>
> **Important note about sequence conflicts:**
>
> When resolving conflicts related to sequences, if you select one of the conflicting sequences, nodes that are no longer connected may remain "orphaned" on the canvas in the merged version. This design decision was made to prevent accidental node deletion. If these orphaned nodes are no longer needed, they can be manually removed in subsequent versions.

## Configurable enumeration ordering

You can now configure the **Order** attribute on enumerations, giving you greater control over how enumeration values are displayed in dropdown lists:

* Set specific order values for each enumeration entry
* Control the presentation sequence in UI components
* Improve user experience by arranging options in logical or prioritized order

![Enum order](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/enum_order.png)

> [!NOTE]
>
> **Limitation:** When changing the order value for an enumeration entry, the system does not automatically update the order values of other entries. You'll need to manually adjust the order values of other entries in the interface.

## **Bug fixes** 🐞

* Fixed an issue where workflow nodes could have two output sequences
* Resolved a problem with enumerations displaying in the wrong order in dropdown lists
* Fixed an authentication issue where users would receive 401 unauthorized errors when executing actions after token refresh
* Fixed a UI behavior issue where slider actions configured with "onChange" were incorrectly triggered when entering a screen instead of only when modified
* Fixed an issue with identical advancing IDs occurring in multi-pod deployments due to missing hostname command in GraalVM docker images
* Resolved an issue preventing media library migration from default application
* Fixed the "Go to reference" functionality from data model attributes that was not correctly redirecting to referenced elements
* Fixed an error during application export/import where "There already exists a tagged build for this project version" was preventing successful imports
* Restored support for multiple topics in Data Stream Topics feature, which was previously only listening to the first topic in the list
* Fixed a 500 error that occurred when attempting to create child actions on certain nodes
* Fixed a critical issue where UI templates would disappear when creating a new version of an application after performing undo operations on pasted templates
* Fixed a bug where updates to the subprocess in a Start subprocess action weren't being saved properly
* Fixed an issue with the "Send email" button remaining disabled in the Test notification template feature after correcting validation errors
* Fixed an error that occurred when trying to export document templates containing null values in templateMap
* Fixed a display issue where Tokens, Workflows, and Subprocesses information wasn't showing in process instances after migration from 4.7.1 to 4.7.2
* Fixed a UI issue where business rule code wasn't displayed when testing business rules in committed versions

***

## **Additional information**

📌 [Deployment Guidelines v4.7.3](./deployment-guidelines-v4.7.3)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.3)


# Deployment guidelines v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/deployment-guidelines-v4.7.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.4 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.4.

## Component versions

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.15.2** | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.9.2** | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.16** | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.13** | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.19** | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.15** | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.18** | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.17** | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.16** | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.17** | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.16** | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.7.2** | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.3.2** | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.19** | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.23** | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.39** | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.17** | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.28** | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.5** | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.13** | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.4 | Keycloak | 22.x, 26.x |
| 4.7.4 | Kafka | 3.2.x |
| 4.7.4 | PostgreSQL | 16.2.x |
| 4.7.4 | Oracle Database | 21c, 23ai |
| 4.7.4 | MongoDB | 7.0.x |
| 4.7.4 | Redis | 7.2.x |
| 4.7.4 | Elasticsearch | 7.17.x |
| 4.7.4 | Angular (Web SDK) | 19.x |
| 4.7.4 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## **Additional information**

* Added new environment variable `OPTIMISTIC_LOCKING_RETRIES` to control the number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

Elasticsearch indexing configuration:

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)


# Migrating from previous versions to v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/migrating-from-v4.1.x-to-v4.7.4

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.4 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025

FlowX.AI 4.7.4 enhances system stability with Spring Boot updates and resolves critical issues across build exports, reporting, SDK functionality, and cross-platform consistency to deliver a more reliable development experience! 🚀

## **What's new? 🆕**

✅ Platform enhancements\
✅ Added retry mechanism for ES indexing to handle key‑identifier errors\
✅ Fixed critical build export timeout issues\
✅ Improved reporting data representation\
✅ Enhanced cross-platform consistency

### Platform Enhancements ⚙️

* Enhanced system stability
* Latest security patches
* Improved performance

### Elasticsearch indexing - configurable retry mechanism

* `OPTIMISTIC_LOCKING_RETRIES`: Number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)

### Data-sync run status monitoring

* Added the ability to view the run status of data-sync jobs directly in the platform interface
* Monitor the execution status of all data-sync jobs from the Jobs dashboard
* Quickly identify failed jobs for faster troubleshooting

![Data-sync run status monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-20%20at%2010.55.19.png)

## **Bug fixes** 🐞

* **Build export timeouts**: Resolved intermittent timeout failures on projects with dependency libraries; exports now consistently complete or retry correctly.
* **Build creation on merge without conflicts**: Fixed an issue where merging one branch into another without conflicts—and switching the active policy—did not trigger a new build, forcing users to manually create a version; now, merges automatically update build resources and create the new version so merged changes appear at runtime.
* **Project version import stashing conflict**: Resolved an error where importing a branched project version across environments would inadvertently stash other versions—restoring successful import, fixing the GET history API response, and ensuring the Project versions history modal renders correctly.
* **CosmosDB workflows**: Fixed an issue preventing the workflow instances list from loading in the Integration Designer when using CosmosDB.
* **Reporting arrays**: Corrected array formatting in the `reporting_data` table (process-engine schema).
* **CMS permissions**: Restored backward compatibility for FlowX SDK v4.7+ by removing the unintended `media_library_read` requirement for processes containing images (behavior now matches v4.1).
* **onChange action behavior**: Standardized onChange/onBlur across web, Android, and iOS so users cannot continue typing after token advancement unless explicitly allowed.
* **React SDK ternary expressions**: Fixed an “Invalid Expression” error in SDK v5.86.1—ternary expressions in computed values (e.g. `return ${var1} ? "Onboarded" : (${var2} ? "Non-eligible" : "Ready for Onboarding");`) now parse correctly as they did in v5.62.1.
* **Elasticsearch indexing**: Fixed an issue where the engine was not retrying to index process instances when it encountered concurrent-update errors on key identifiers.
* **iOS SSE token refresh**: Fixed an issue in iOS SDK where Server-Sent Events connections would occasionally use expired JWT tokens instead of refreshed ones, causing 401 errors and process hangs in production environments.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.4](./deployment-guidelines-v4.7.4)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.4)


# Deployment guidelines v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/deployment-guidelines-v4.7.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.5 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.5.

## Component versions

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.17.0** | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.12.2** | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.5.1** | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.1.1** | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.1.1** | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.2.1** | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.4.1** | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.3.1** | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.1.1** | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.9.0** | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.4.1** | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.21** | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.24** | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.18** | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.5 | Keycloak | 22, 26+ |
| 4.7.5 | Kafka | 3.2 - 3.9 |
| 4.7.5 | PostgreSQL | 16 - 17 |
| 4.7.5 | Oracle Database | 21c, 23ai |
| 4.7.5 | MongoDB | 7 - 8 |
| 4.7.5 | Redis | 7.2 - 8.0 |
| 4.7.5 | Elasticsearch | 7 - 8 |
| 4.7.5 | Angular (Web SDK) | 19.x |
| 4.7.5 | React (Web SDK) | 18.x |

> [!NOTE]
>
> **New in 4.7.5: Support for more 3rd Party Dependencies**
>
> FlowX.AI 4.7.5 introduces support for more versions of third-party dependencies:
>
> * All versions are officially supported throughout the entire LTS lifetime
> * Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major release
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/migrating-from-v4.1.x-to-v4.7.5

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.5 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.5 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025

FlowX.AI 4.7.5 enhances system stability with introducing support for more 3rd party dependency and introduces High Availability improvements with Redis Sentinel mode support to deliver a more reliable and scalable development experience! 🚀

## **What's new? 🆕**

✅ **Platform enhancements**\
✅ **Analytics enhancements**

### Platform enhancements ⚙️

**Extended Third-Party Dependency Support** - Introducing support for more versions of third-party dependencies:

* All versions are officially supported throughout the entire LTS lifetime
* Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major releases for critical infrastructure components, ensuring all supported versions are officially maintained throughout the entire LTS lifetime. This enables organizations to perform gradual dependency upgrades during the LTS period, preparing infrastructure to meet the minimum requirements for the next FlowX.AI major release while maintaining full platform support and stability.

### Analytics enhancements ⚙️

* Improved analytics events with enriched metadata for action events across all platforms (Web, iOS, Android). Action events now include screen context, component type identification, and component labels, providing deeper insights into user interactions and enabling more granular analytics tracking for better user experience optimization.

More details:

> [card] [Angular Renderer](../../../../4.7.x/sdks/angular-renderer#analytics)

> [card] [React Renderer](../../../../4.7.x/sdks/react-renderer#analytics)

> [card] [iOS Renderer](../../../../4.7.x/sdks/ios-renderer#collecting-analytics-events)

> [card] [Android Renderer](../../../../4.7.x/sdks/android-renderer#collecting-analytics-events)

### Runtime Manager deployment changes

> [!NOTE]
>
> **Prior to 4.7.5:** Runtime Manager was deployed using `application-manager` chart/image with manual `SPRING_APPLICATION_NAME`: "runtime-manager" configuration.
> Starting with 4.7.5: Runtime Manager has its own dedicated chart and image with proper defaults.

> [!TIP]
>
> Migration Required

* Switch to new chart: Use runtime-manager chart instead of application-manager
* Verify image: Ensure image name is runtime-manager (default in new chart)
* Remove override: `SPRING_APPLICATION_NAME`: "runtime-manager" can be removed (optional)

> [!WARNING]
>
> You may need to delete the existing runtime-manager deployment before upgrading due to Kubernetes label changes that cause `kubectl apply` to fail.

## **Bug fixes** 🐞

* **Fixed Task Manager loading issue with data type changes** - Resolved critical issue where Task Manager would fail to load and throw `NullPointerException`   when process variables were changed from date to string data types, even after updating the data model and clearing cache
* **Fixed All Tasks view missing on build import** - Resolved issue where importing builds from one environment to another would fail to create the All Tasks view, when accessing the Task Manager area
* **Fixed unassign operation causing runtime errors** - Resolved 500 Internal Server Error when accessing process data after performing unassign operations via Kafka messages, where null ownerDetails would cause `NullPointerException` during JSON serialization
* **Fixed CMS-Core export failures with AWS S3 buckets** - Resolved issue where CMS-Core would add double slashes in S3 object paths when creating exports, causing 404 NoSuchKey errors with AWS S3 (while working correctly with MinIO). Fixed path construction to ensure compatibility with both AWS S3 and MinIO storage backends
* **Fixed active policy version resolution** - Resolved issue where importing application versions to environments with existing WIP versions would incorrectly activate the stashed WIP version instead of the imported committed version, causing graph display failures and incorrect active policy settings

***

## **Additional information**

📌 [Deployment Guidelines v4.7.5](./deployment-guidelines-v4.7.5)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.5)


# Deployment guidelines v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/deployment-guidelines-v4.7.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.6 will permanently prevent you from importing process definitions and resources created in versions 4.7.5 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

> [!WARNING]
>
> **Audit data retention change**
>
> Starting with FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. In 4.7.5 and earlier, the service created this policy only once, on the first installation.
>
> The policy it writes has a single hot phase that rolls the audit data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. The default is `30` days; in 4.7.5 and earlier, the rollover period was a fixed 1 day.
>
> Any phase you added to this policy directly in Elasticsearch, such as a delete phase, is removed the next time the Audit service starts. Without a delete phase, old audit indices are never deleted and audit storage keeps growing.
>
> To keep the previous daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1` on the Audit service.

## Component versions

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.21.1** | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.15.2** | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.8.2** | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.4.0** | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.4.0** | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.5.0** | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.7.0** | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.6.0** | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.5.0** | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.13.0** | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.7.1** | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.29** | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.19** | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.6 | Keycloak | 22, 26+ |
| 4.7.6 | Kafka | 3.2 - 3.9 |
| 4.7.6 | PostgreSQL | 16 - 17 |
| 4.7.6 | OracleDB | 21c, 23ai |
| 4.7.6 | MongoDB | 7 - 8 |
| 4.7.6 | Redis | 7.2 - 8.0 |
| 4.7.6 | Elasticsearch | 7 - 8 |
| 4.7.6 | Angular (Web SDK) | 19.x |
| 4.7.6 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8

## Configuration Parameters

Starting with FlowX.AI 4.7.6, Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment.

> [card] [Integration Designer setup](/4.7.x/setup-guides/integration-designer-setup#configuration-parameters)

> [card] [Process Engine setup](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters)

> [card] [Application Manager setup](/4.7.x/setup-guides/application-manager)


# Migrating from previous versions to v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/migrating-from-v4.1.x-to-v4.7.6

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.6 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.6](../v4.7.6-july-2025/deployment-guidelines-v4.7.6)

> [card] [Deployment guidelines v4.7.5](../v4.7.5-july-2025/deployment-guidelines-v4.7.5)

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1/)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.6 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025

This release includes significant improvements to logging configuration and resolves some issues across the Designer, Process Engine, and Integration Designer components.

> [!WARNING]
>
> Upgrading to 4.7.6 changes how the Audit service manages its Elasticsearch lifecycle policy: the policy is rewritten on every startup and the default rollover period changes from 1 day to 30 days. See the [Deployment guidelines](./deployment-guidelines-v4.7.6) before upgrading.

## **What's new? 🆕**

> [card] Improved default logging configuration
>
> Changed logging verbosity to reduce clutter & log sizes, increasing visibility for more relevant log messages.

> [card] Improved the ability to use deployment specific variables as Configuration Parameters (at process runtime)
>
> Now Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment. Check the [**Deployment Guidelines**](./deployment-guidelines-v4.7.6#configuration-parameters) for more details.

> [card] Improved runtime performance
>
> Improved runtime performance by better distributing the execution of nodes across all components.

> [card] Improved the speed of listing process instances
>
> Improved the speed of listing process instances by 4-6x on environments with a lot of process executions.

> [card] Added the ability to change logging levels at runtime
>
> This feature allows you to dynamically adjust logging levels without requiring a service restart, providing more flexibility in managing log output.

> [card] Reduced config deployment complexity
>
> The previously used `CONFIG_PROFILE` environment variable is no longer required as the default configs have been aligned with the recommended profiles.

## **Bug fixes** 🐞

> [accordion] \[Designer] Task view display issue
>
> Fixed task view list row content display issue where table rows were overlapping and text was not vertically centered in the latest Chrome browser version (138). The task view now properly displays centered content without text cutoff.

> [accordion] \[Integration Designer] JSON parsing error
>
> Fixed JSON parsing error when sending JSON result to REST body. Resolved issue where JSON objects generated in script tasks were causing "Unexpected character" errors when used in REST endpoint body parameters with \$ syntax.

> [accordion] \[Branch Merge] Media file export errors
>
> Fixed media file export errors during branch merges. Resolved issue where merging multiple branches created from the same main version would fail with "400 Bad Request" errors for media files after the first successful merge, even when no merge conflicts were present.

> [accordion] \[Process Designer] Rollback issue
>
> Fixed rollback issue during version submission errors. Resolved problem where processes were incorrectly marked as deleted in the database when submit version operations failed with 500 errors, preventing proper rollback and causing subsequent 404 "Process not found" errors.

> [accordion] \[Process Designer] Missing resources during copy operation
>
> Fixed missing resources during copy to another project/library operation. Resolved issue where forms with validation in UserTask nodes were not being copied when copying processes between projects or libraries.

> [accordion] \[Process Designer] Branch with missing resources and 404 errors
>
> Fixed issue where specific branches derived from main version would experience resource corruption, including missing process definitions (404 errors), missing Integration Designer resources, and commit failures.

> [accordion] \[Process Designer] Parallel multi-instance visual bug
>
> Fixed parallel multi-instance designer visual bug and database errors. Resolved issue where call activity nodes with parallel multi-instance enabled created duplicate "inputKey" and "outputKey" entries, causing visual bugs (missing collection key fields) and database update errors during node modifications.

> [accordion] \[Process Engine] Kafka message distribution
>
> Fixed Kafka message distribution across partitions. Resolved issue where Kafka messages were distributed as batches across partitions, causing increased usage of a limited number of partitions, instead of following the round-robin distribution per message strategy.

***

## **Additional information**

> [card] [Deployment Guidelines v4.7.6](./deployment-guidelines-v4.7.6)
>
> Step-by-step deployment instructions and configuration details for this release.

> [card] [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.6)
>
> Complete guide for migrating from version 4.1.x to 4.7.6 with breaking changes and migration steps.


# Deployment guidelines v4.7.7
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/deployment-guidelines-v4.7.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.7 will permanently prevent you from importing process definitions and resources created in versions 4.7.6 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.22.3** | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.16.3** | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.97.1** | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.9.2** | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.6.2** | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.8.2** | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.7.2** | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.6.2** | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.14.2** | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.8.1** | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.40** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.21** | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.29** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.14** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.7 | Keycloak | 22, 26+ |
| 4.7.7 | Kafka | 3.2 - 3.9 |
| 4.7.7 | PostgreSQL | 16 - 17 |
| 4.7.7 | OracleDB | 19c, 21c, 23ai |
| 4.7.7 | MongoDB | 7 - 8 |
| 4.7.7 | Redis | 7.2 - 8.0 |
| 4.7.7 | Elasticsearch | 7 - 8 |
| 4.7.7 | Angular (Web SDK) | 19.x |
| 4.7.7 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.7 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Improved robustness on auto-scaling process-engine and on Kafka node failures\
✅ Improvements on how configuration parameters can now be retrieved from Kubernetes secrets and ConfigMaps\
✅ Vulnerability fixes

## Configuration parameters

Improved configuration parameters retrieval from Kubernetes secrets and ConfigMaps. More details here:

> [card] [FlowX Engine](../../4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#dynamic-configuration-parameters-retrieval)

> [card] [Integration Designer](../../4.7.x/setup-guides/integration-designer-setup#dynamic-configuration-parameters-retrieval)

## Bug fixes

> [accordion] \[Designer] JSON size limit on input data
>
> Fixed JSON payload size limit issue causing "403 payload too large" errors when starting processes. More details [**here**](../../4.7.x/docs/flowx-designer/managing-a-project-flow/starting-a-process#starting-a-process-via-user-interface).

> [accordion] Improved robustness on Kafka node failures
>
> If one Kafka node fails, platform health check fails. This is now fixed.

> [accordion] \[UI Designer] Theming on accordion card
>
> Fixed theming issue where Card component styling was not properly applied when switched to accordion mode.

> [accordion] \[Angular SDK] Loader does not stop on subprocess end
>
> Fixed loader persistence issue where loaders initiated by "show loader" actions in subprocess UserTasks would continue displaying after subprocess completion.

> [accordion] \[Process Designer] Merge error with duplicate embed node keys
>
> Fixed merge conflict error occurring when copying and pasting embed nodes in processes.

> [accordion] \[Process Engine] Process execution stalls on REST-triggered flows when engine replica fails
>
> Fixed process execution recovery issue where REST API-triggered service tasks would hang indefinitely if the handling engine replica failed mid-execution.

> [accordion] \[Process Designer] Merge fails with duplicate key error after creating child branch to jump over broken WIP
>
> Fixed merge conflict error occurring when creating child branches from working commits to bypass broken WIP versions.


# Deployment guidelines v4.7.8
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/deployment-guidelines-v4.7.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.8 will permanently prevent you from importing process definitions and resources created in versions 4.7.7 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.23.2** | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.17.3** | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.10.3** | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.7.2** | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.9.2** | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.8.2** | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.7.2** | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.15.3** | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.9.2** | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.22** | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.8 | Keycloak | 22, 26+ |
| 4.7.8 | Kafka | 3.2 - 3.9 |
| 4.7.8 | PostgreSQL | 16 - 17 |
| 4.7.8 | OracleDB | 19c, 21c, 23ai |
| 4.7.8 | MongoDB | 7 - 8 |
| 4.7.8 | Redis | 7.2 - 8.0 |
| 4.7.8 | Elasticsearch | 7 - 8 |
| 4.7.8 | Angular (Web SDK) | 19.x |
| 4.7.8 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.8 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes\
✅ Support for [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title

### Support for Substitution Tags in Table column title

Now you can use [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title.

## Bug fixes

> [accordion] \[UI Designer] Card expansion state not calculated correctly
>
> Resolved an issue where, in certain situations, the expanded state of cards was not calculated correctly. This prevented users from expanding cards as expected.

> [accordion] \[UI Designer] Document preview component texts not translated
>
> Fixed localization issue where document preview component texts remained in English regardless of the selected language setting.

> [accordion] \[Designer] Groups tab fails to load with Keycloak 26.3
>
> Fixed compatibility issue with Keycloak 26.3 where the Groups tab would remain in loading state indefinitely due to new "description" field in group representations.

> [accordion] \[CMS] Import fails for PDF files with null thumbnail path
>
> Fixed import failure when PDF media files were exported with null `thumbnailStoragePath` values, preventing successful deployment of build or app versions to fresh environments.

> [accordion] \[Runtime Manager] Improved error logging for proxy failures
>
> Enhanced error logging detail when Runtime Manager proxy requests fail, providing better root cause information for debugging infrastructure issues like DNS problems or service unavailability.

> [accordion] \[Integration Designer] Slow performance on first workflow execution after pod restart
>
> Fixed performance issue where workflow IF node processing time increased from 3-5 seconds to 15-20 seconds on the first execution after Integration Designer pod restart.

> [accordion] \[Process Engine] Active step was incorrectly computed when the token is reset
>
> Fixed issue where the active step was incorrectly computed when the token is reset.


# Deployment guidelines v4.7.9
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/deployment-guidelines-v4.7.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.1** | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.4** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.1** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.1** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.1** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.2** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.30** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.26** | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.23** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.9 | Keycloak | 22, 26+ |
| 4.7.9 | Kafka | 3.2 - 3.9 |
| 4.7.9 | PostgreSQL | 16 - 17 |
| 4.7.9 | OracleDB | 19c, 21c, 23ai |
| 4.7.9 | MongoDB | 7 - 8 |
| 4.7.9 | Redis | 7.2 - 8.0 |
| 4.7.9 | Elasticsearch | 7 - 8 |
| 4.7.9 | Angular (Web SDK) | 19.x |
| 4.7.9 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.9 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes and security improvements\
✅ Support for dynamic keys in [**Link component**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/typography#link) URL property across all platforms\
✅ Added property on View for enabling or disabling row selection in tasks table

### Support for dynamic keys in Link component URL property

You can now use dynamic keys in the Link component's URL property across all platforms (Web, iOS, and Android). This enhancement allows you to dynamically construct URLs using process data, enabling more flexible navigation patterns in your applications.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)

### Task Manager rowSelection property on view

A new "Enable row selection" property has been added to Task Manager views, enabling you to control row selection behavior in task tables.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enable_row_select.png)

## Bug fixes

> [accordion] \[Designer] Merge fails if one branch contains past merges
>
> Fixed an issue where merging branches that contain multiple past merge commits would fail with an error. The merge conflict resolution now properly handles complex merge histories when adding values to enumerations or making other configuration changes.

> [accordion] \[CMS] Enumerations retrieve content endpoint should return content from dependencies
>
> Resolved an issue where the CMS enumerations Kafka endpoint only returned content from the local project and not from library dependencies. The endpoint now correctly retrieves enumeration content from both the current project and all dependency libraries.

> [accordion] \[Task Manager] Table doesn't use the current language
>
> Fixed localization issue in Task Manager where table content wasn't respecting the current language setting. Task Manager tables now properly use the selected language for all displayed content.

> [accordion] \[UI Designer]\[Angular]\[React] Modal fixed height is not applied
>
> Resolved an issue where setting a modal's height to "fixed" would not apply correctly in Angular and React renderers. Fixed height configuration now works as expected for modal components.

> [accordion] \[UI Designer]\[Angular] Fixed container should use overflow-y auto instead of scroll
>
> Fixed styling issue where fixed-height containers incorrectly used `overflow-y: scroll` instead of `overflow-y: auto`. Containers now only show scrollbars when content exceeds the container height.


# Deployment guidelines v5.0.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/deployment-guidelines-v5.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.29.2** | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.25.2** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.21.2** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.14.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.17.2** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.14.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.12.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.15.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.11.0** | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.26.2** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.11.0** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.14.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.11.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | |

### Embedded components

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **SpiceDB** | **1.42.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **DGraph** | **25.0.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

### Renderers

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.3** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.0.12** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.0.0 | Keycloak | 26+ |
| 5.0.0 | Kafka | 3.8 - 3.9 |
| 5.0.0 | PostgreSQL | 16 - 17 |
| 5.0.0 | Oracle Database | 21c, 23ai |
| 5.0.0 | MongoDB | 7 - 8 |
| 5.0.0 | Redis | 7.4 - 8.0 |
| 5.0.0 | Elasticsearch | 8 - 9 |
| 5.0.0 | Angular (Web SDK) | 19.x |
| 5.0.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/configuration-and-migration

This section contains the steps in the order we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](../../../../5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The Authorization System will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

> [!NOTE]
>
> The admin user imported here is the same service account referenced in the migration prerequisites. If you followed the prerequisites page and set up the admin Keycloak user beforehand, the Authorization System will pick it up automatically during this step — no additional action is needed.

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from Application Manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.0.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | 🆕 Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Kafka Configuration

> [!NOTE]
>
> Consumer group naming standardized to kebab-case across all FlowX.AI services with new messaging features for enhanced functionality.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group naming changes

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
> | | |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Application Manager specific features

#### New environment variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | 🆕 Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | 🆕 Maximum HTTP request header size |

#### New Kafka features

> [card] Resource Update Propagation
>
> Consumer Group: `app-resource-update-propagation-group`\
> Threads: 3\
> Topic: `ai.flowx.{env}.application-version.resource.update.propagation.v1`

> [card] Build Runtime Data
>
> Consumer Group: `build-runtime-data-group`\
> Threads: 2\
> Topic: `ai.flowx.{env}.build.runtime-data.v1`

> [card] Business Rule Sync
>
> Topic: `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> Purpose: Business rule synchronization

> [card] Process Sync (Restructured)
>
> Topic: `ai.flowx.{env}.application-version.sync.process.in.v1`\
> Purpose: Enhanced process synchronization

> [card] Reusable Templates sync
>
> Topic: `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> Purpose: Reusable template synchronization

#### Kafka environment variables (optional overrides)

```bash New Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_RESOURCEUPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Business Rule Sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1

# Process Sync (restructured)
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1


# Reusable Templates sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1
```

```bash Consumer Groups theme={"dark"}
# New Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
```

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides.

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | 🆕 Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | 🆕 Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | 🆕 S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | 🆕 S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | 🆕 S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | 🆕 S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | 🆕 S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | 🆕 S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | 🆕 Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | 🆕 Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | 🆕 Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | 🆕 Redis host |
| `SPRING_REDIS_PORT` | `6379` | 🆕 Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | 🆕 Redis password |
| `SPRING_REDIS_TTL` | `5000000` | 🆕 Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | 🆕 Redis host |

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/install-services

Step-by-step installation guide for new FlowX.AI 5.0 services

FlowX.AI 5.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](/5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](/5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.6 (or newer) to 5.0.0. If you’re on an earlier version, upgrade to the latest LTS version first.

## Success factors

> [!WARNING]
>
> The following steps are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB** must be installed before any FlowX.AI services. **DGraph** is only required if you are using FlowX AI agents — if not, you can skip DGraph installation, but SpiceDB is still mandatory.
>
> > [!NOTE]
> >
> > Only DGraph can be skipped (and only if you are not using FlowX AI agents). SpiceDB is mandatory for all deployments.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices migration** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](/5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites

This section contains the steps in the order we recommend for migrating data from FlowX v4.7.x to v5.0.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.6 | FlowX.AI 5.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.0#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip installing DGraph. SpiceDB is still mandatory.

> [card] [SpiceDB setup guide](../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.0.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

Before upgrading to FlowX.AI 5.0, you must run two operations on all existing Elasticsearch indices:

1. **Update index mappings** to include the `workspaceId` field (schema change)
2. **Migrate existing documents** to assign them to the default workspace (data migration)

These operations are required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable; if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

> [!WARNING]
>
> If Elasticsearch migration is not completed correctly, some process instances may not appear in search results, data-search features might return incomplete results, and workspace-scoped queries will fail for unmigrated data. Existing resources will also not be visible or accessible within the new workspace structure.

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.0.0.

***

## Authorization System Prerequisites

Before deploying the `authorization-system` service, you must configure the organization admin user. This is a critical prerequisite for ensuring that the authentication and user management features function correctly post-upgrade.

### Steps to Configure the Organization Admin User

Follow these guides to correctly set up the organization admin user:

> [card] [Bootstrap Organization Admin](../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Organization Admin Roles & Workspace Access](../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

> [!TIP]
>
> Configuration of the organization admin user must be completed **before** deploying the authorization-system service (see the [Install Services](./install-services) section for service deployment steps).

### Pre-migration preparation

Required configuration for the authorization-system service:

* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE`= `true` (mandatory for migrations)
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME`= `<admin-username>` (recommended method, default: `admin@flowx.ai`)

The system will search for this username in Keycloak and automatically copy the user's subject ID to the authorization-system database.

**Fallback method:** If the username method fails or you prefer to specify the subject ID directly:

* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID`= `<subject-id-of-admin-user>`

> [!TIP]
>
> To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.

![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users"
    ]
  }
}
```


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.06.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.0") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.0 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.0 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.0 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.0 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.0 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# FlowX.AI 5.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025

Latest features, improvements, and bug fixes in our newest release

> [!WARNING]
>
> This release includes the following features in Tech Preview. We encourage you to try them out and share your feedback to help us improve them. Please note that Tech Preview features may change before final release.

> [tab] What's New
>
> **What's new? 🆕**
>
> 🆕 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture)\
> 🆕 [**Project Data Model (PDM)**](#project-data-model-pdm)\
> 🆕 [**FlowX.AI Database**](#flowx-ai-database)\
> 🆕 [**Multi Select UI Component**](#multi-select-ui-component)\
> 🆕 [**Library-to-Library Dependencies**](#library-to-library-dependencies)\
> 🆕 [**Data Mappers**](#data-mappers)\
> 🆕 [**Reusable Resources**](#reusable-resources)\
> 🆕 [**Files in Integration Designer**](#files-in-integration-designer)\
> 🆕 [**Rendering improvements**](#rendering-improvements)
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Major Infrastructure Changes**: Workspaces introduces SpiceDB integration and new database schemas for multi-tenant architecture.
> > >
> > > **Key Changes:**
> > >
> > > * **SpiceDB Integration**: New permission management system requiring deployment
> > >
> > > * **Database Migration**: Schema updates for workspace support
> > >
> > > * **User Storage**: Only information about FlowX.AI Designer users is stored in FlowX.AI. The stored user data is limited to: unique identifier, username, first name, last name, and email address.
> > >
> > > * **Default Workspace**: All the projects and libraries are migrated to default workspace
> > >
> > > > [!TIP]
> > > >
> > > > **Backward Compatibility**: All existing functionality preserved in default workspace
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Login Flow**: After authentication, select your workspace before accessing FlowX.AI Designer. Once inside a workspace, everything works as before.
> > >
> > > **What's New:**
> > >
> > > * **Workspace Selection**: Choose workspace after login
> > > * **Resource Isolation**: Projects, libraries, themes are workspace-specific
> > > * **Enhanced Permissions**: Fine-grained access control with user groups and ACLs
> > > * **Workspace Management**: Create and manage workspaces (admin users)
> > >
> > > **What Stays the Same:**
> > >
> > > * Process design and configuration
> > > * UI Designer capabilities
> > > * Integration patterns
> > > * All existing FlowX.AI Designer features
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Transformation**: Workspaces enables enterprise multi-tenant architecture with independent business unit governance while sharing platform capabilities.
> > >
> > > **Business Impact:**
> > >
> > > * **Faster time-to-market** for new business verticals
> > > * **Enhanced compliance** with workspace-specific controls
> > > * **Improved governance** with fine-grained access management
> > >
> > > **Enterprise Benefits:**
> > >
> > > * Business unit autonomy with shared platform
> > > * Regulatory compliance through data isolation
> > > * Centralized upgrades and maintenance
> > > * Cross-business unit resource sharing when appropriate
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Infrastructure Impact**: PDM has minimal infrastructure impact - it's a design-time feature that improves development efficiency without affecting runtime resources.
> > >
> > > > [!TIP]
> > > >
> > > > **No deployment changes required** - PDM is part of the design platform, not runtime
> > >
> > > > [!TIP]
> > > >
> > > > **Backward compatible** - Existing processes continue to work unchanged
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer**: Define data types once at project level, use everywhere. No more recreating Customer or Order objects in every process.
> > >
> > > **How to Use PDM:**
> > >
> > > 1. Navigate to Project → Config → Data Model
> > > 2. Define your business entities (Customer, Product, etc.)
> > > 3. Set governance rules (sensitive data, reporting)
> > > 4. Use these types in any process within the project
> > >
> > > **Best Practices:**
> > >
> > > * Start with core business entities
> > > * Use clear, consistent naming
> > > * Mark sensitive fields appropriately
> > > * Leverage library data types when available
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: PDM transforms how your organization manages business data definitions. Define business entities once and ensure consistency across all processes and teams.
> > >
> > > **Business Benefits:**
> > >
> > > * **Enhanced compliance** through centralized governance and data sensitivity controls
> > > * **Reduced errors** from consistent data definitions
> > >
> > > **ROI Indicators:**
> > >
> > > * Development Efficiency: Measure reduction in process creation time
> > > * Error Reduction: Track fewer data-related production issues
> > > * Maintenance Cost: Monitor time spent on data structure updates
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Infrastructure Planning Required**: FlowX.AI Database creates additional MongoDB collections and requires infrastructure planning for storage, monitoring, and backup procedures.
> > >
> > > > [!TIP]
> > > >
> > > > New microservice: NoSQL DB Runner. Check the [setup guide](/5.1/setup-guides/nosql-db-runner) for more details.
> > >
> > > **Key Considerations:**
> > >
> > > * **Storage Planning**: Monitor usage as processes adopt internal database (plan for 20-30% increase)
> > > * **Performance Monitoring**: Set up alerts for FlowX.AI Database query performance
> > > * **Backup Strategy**: Include FlowX.AI Database collections in backup procedures
> > > * **Connection Pooling**: Additional connection pools for database operations
> > > * **Memory**: Additional 256MB-512MB per FlowX.AI instance for database operations
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Integration Option**: FlowX.AI Database appears as a new Data Source type in Integration Designer, right alongside RESTful System.
> > >
> > > **When to Use FlowX.AI Database:**
> > >
> > > * Customer data lookup across processes
> > > * Shared configuration and reference data
> > > * Process-to-process communication
> > > * Caching frequently accessed data
> > > * Temporary operational data storage
> > >
> > > **How to Implement:**
> > >
> > > 1. Add Data Source node to your process
> > >
> > > 2. Select "FlowX.AI Database" as type
> > >
> > > 3. Configure collection and operations
> > >
> > > 4. Use familiar MongoDB syntax (find, insert, update)
> > >
> > > > [!WARNING]
> > > >
> > > > **When NOT to Use**: Don't replace your core business systems. FlowX.AI Database is perfect for operational data, caching, and inter-process communication - but your CRM, ERP, and other systems of record should remain your primary data sources.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: FlowX.AI Database enables new operational patterns that were previously complex or impossible. It's not about replacing your core systems, but about enabling new ways to orchestrate business processes.
> > >
> > > **New Business Capabilities:**
> > >
> > > * **Cross-process workflows**: Loan application → Credit check → Approval across different process instances
> > > * **Real-time dashboards**: Operational data for business monitoring without system integration
> > > * **Agile experimentation**: Test new business rules without impacting core systems
> > > * **Process orchestration**: Complex business flows spanning multiple departments
> > >
> > > **ROI Considerations:**
> > >
> > > * **Time to Market**: Faster implementation of new business processes
> > > * **Agility**: Rapid prototyping and testing of business ideas
> > >
> > > **Use FlowX.AI Database when:**
> > >
> > > * Data is operational and process-specific (not master data)
> > > * You need rapid implementation without IT system changes
> > > * Process instances need to communicate with each other
> > > * You're prototyping new business capabilities
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **No Infrastructure Impact**: Multi Select is a pure UI component with no backend requirements. It works with existing form handling and data storage mechanisms.
> > >
> > > > [!TIP]
> > > >
> > > > **Zero deployment overhead** - Component is part of the UI framework upgrade
> > >
> > > > [!TIP]
> > > >
> > > > **Existing data handling** - Uses standard array storage, no schema changes needed
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Easy Integration**: Multi Select works just like other form elements in UI Designer. Drag, drop, configure - no new learning curve required.
> > >
> > > **Common Use Cases:**
> > >
> > > 1. **Skills Selection**: Job applications, team member profiles, contractor skills
> > > 2. **Product Features**: Insurance coverage options, software licensing features
> > > 3. **Categories & Tags**: Document classification, customer segmentation
> > >
> > > **Key Configuration:**
> > >
> > > * **Max selections**: Control input limits
> > > * **Display format**: Chips, lists, custom
> > > * **Search**: Filter large option sets
> > > * **Clear all**: Easy reset functionality
> > > * **Validation**: Min/max rules
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **User Experience Impact**: Multi Select eliminates user frustration in scenarios where single selection doesn't match real-world needs. This improves data quality and user satisfaction.
> > >
> > > **Before vs After:**
> > >
> > > * ❌ **Before**: "I can only select one skill, but I have multiple certifications"
> > > * ✅ **After**: "Perfect! I can select all my relevant skills at once"
> > >
> > > **Business Process Examples:**
> > >
> > > * **Employee Onboarding**: Select multiple skills, certifications, department access
> > >
> > > * **Product Configuration**: Select multiple features, add-ons, support packages
> > >
> > > * **Customer Preferences**: Select multiple communication channels, product interests
> > >
> > > > [!TIP]
> > > >
> > > > **Analytics Benefit**: Multi-select data provides richer analytics. Instead of knowing a customer chose "Primary Interest: Technology," you know they selected "AI, Cloud Computing, Cybersecurity, Mobile Development" - much more actionable for business intelligence.
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backwards Compatibility**: FlowX.AI 5.0 maintains full backwards compatibility with existing project-to-library dependencies from FlowX.AI 4.x. All existing dependencies will continue to work without modification.
> > >
> > > **Upgrade Process:**
> > >
> > > 1. **Existing dependencies** will be automatically migrated
> > >
> > > 2. **New library dependency features** become available immediately
> > >
> > > 3. **No breaking changes** to existing functionality
> > >
> > > 4. **Enhanced validation** may catch previously undetected issues
> > >
> > > > [!WARNING]
> > > >
> > > > **Post-Migration Required**: After the lib2lib migration is executed, you must clear the cache. This is necessary because a new field is added to the build mongo document.
> > >
> > > **Cache Clearing Steps:**
> > >
> > > 1. Complete the lib2lib migration process
> > > 2. Clear the application cache to ensure the new build document fields are properly recognized
> > > 3. Verify that library-to-library dependencies are functioning correctly
> > >
> > > **Key Changes:**
> > >
> > > * **Build Export Changes**: Build exports now automatically include entire dependency trees (larger packages but self-contained)
> > > * **Dependency Validation**: Build process now checks for dependency conflicts (enhanced validation may catch previously undetected issues)
> > > * **Deployment Consistency**: Single-version constraint prevents runtime conflicts (more predictable deployments)
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Enhanced Organization**: You can now create more sophisticated library structures where specialized libraries build upon common foundations. This reduces duplication and improves consistency.
> > >
> > > **How It Works:**
> > >
> > > 1. Navigate to Library → Config → Dependencies
> > > 2. Add other libraries as dependencies
> > > 3. FlowX.AI validates for conflicts automatically
> > > 4. Resources from all dependency levels become available
> > >
> > > **Best Practices:**
> > >
> > > * Plan your library hierarchy before implementation
> > >
> > > * Keep dependencies focused and purposeful
> > >
> > > * Avoid circular dependencies
> > >
> > > * Use semantic versioning consistently
> > >
> > > * Document dependency relationships clearly
> > >
> > > > [!NOTE]
> > > >
> > > > **Example**: Create a "US Banking Library" that depends on "Global Banking Library" and "US Compliance Library". This way, US-specific processes get both global banking functionality and local compliance requirements automatically.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Enterprise Architecture**: Library-to-Library Dependencies enable sophisticated organizational structures where different teams can own specific business domains while building on shared foundations.
> > >
> > > **Enterprise Use Cases:**
> > >
> > > **Multi-Country Operations:**
> > > Global Insurance Company: US-specific library depends on Global Compliance library
> > >
> > > ```
> > > US Insurance Library → Global Compliance Library → Base Insurance Library
> > > ```
> > >
> > > **Product Line Specialization:**
> > > Bank: Mortgage processes use specialized libraries that extend common banking operations
> > >
> > > ```
> > > Mortgage Library → Lending Library → Core Banking Library
> > > ```
> > >
> > > **Business Impact:**
> > >
> > > * **Team Autonomy**: Teams work independently while leveraging shared assets
> > >
> > > * **Faster Innovation**: New products build on proven foundation components
> > >
> > > * **Risk Reduction**: Tested, validated components reduce implementation risk
> > >
> > > > [!WARNING]
> > > >
> > > > **Change Management**: This capability requires coordination between teams. Establish clear ownership models, communication protocols, and upgrade procedures before implementing complex dependency hierarchies.
>
> ***
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **Zero Infrastructure Impact**: Data Mappers is a design-time feature that enhances the FlowX.AI Designer interface without requiring additional infrastructure or deployment changes.
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backward Compatibility**: All existing data transfer mechanisms (like `append to parent process` or `output.[outputKey]`) continue to work unchanged. Teams can adopt Data Mappers at their own pace.
> > >
> > > **Key Points:**
> > >
> > > * **No new microservices** - Enhancement to existing designer interface
> > > * **No runtime changes** - Data mapping occurs at design time
> > > * **Existing configurations preserved** - Zero impact on current implementations
> > > * **Optional adoption** - Teams choose when and where to use new functionality
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer for Integration**: No more complex syntax for data transfers. Visual drag-and-drop interface makes component integration intuitive and error-free.
> > >
> > > **How to Use Data Mappers:**
> > >
> > > 1. **Define Parameters**: Set input/output parameters on Start/End nodes
> > > 2. **Choose Implementation**: Select "Data Mapper" or "Current" method
> > > 3. **Visual Mapping**: Drag source parameters to destination parameters
> > > 4. **Save Configuration**: Store mappings for reuse and maintenance
> > >
> > > **When to Use:**
> > >
> > > * **Call Activities**: Passing data between parent and child processes
> > >
> > > * **Integration Workflows**: Connecting with external systems
> > >
> > > * **Complex Data Flows**: When visual mapping improves clarity
> > >
> > > * **Team Collaboration**: When multiple people work on integration logic
> > >
> > > > [!WARNING]
> > > >
> > > > **Parameter Changes**: When you modify input/output parameters, existing mappings must be manually updated. Changes don't automatically propagate to avoid unintended data flow modifications.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: Data Mappers transforms technical integration tasks into visual, business-friendly workflows. Non-technical stakeholders can now understand and validate data flows between business processes.
> > >
> > > **Business Impact:**
> > >
> > > * **Reduced Errors**: Visual mapping prevents data integration mistakes that cause process failures
> > > * **Faster Development**: Intuitive interface accelerates process configuration and testing
> > > * **Better Documentation**: Visual data flows serve as living documentation of business logic
> > > * **Team Collaboration**: Business and technical teams can discuss data flows using the same visual interface
> > >
> > > **ROI Indicators:**
> > >
> > > * **Development Speed**: Measure reduction in integration configuration time
> > > * **Error Rate**: Track fewer data-related production issues
> > > * **Team Efficiency**: Monitor cross-functional collaboration improvements
> > > * **Process Quality**: Assess improvement in first-time-right deployments
> > >
> > > **Use Cases by Industry:**
> > >
> > > * **Banking**: Loan application data flowing from customer intake → credit check → approval process
> > > * **Insurance**: Claim data mapping from initial report → investigation → settlement
> > > * **Manufacturing**: Order data flowing from sales → production planning → fulfillment
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Minimal Infrastructure Impact**: Reusable Resources is primarily a design-time enhancement that leverages existing FlowX infrastructure with minimal additional overhead.
> > >
> > > **Infrastructure Considerations:**
> > >
> > > * **Execution Context**: Functions execute within existing process engine contexts - no additional runtime infrastructure required
> > >
> > > > [!TIP]
> > > >
> > > > **No New Microservices**: Features are integrated into existing FlowX.AI platform components
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Development Game Changer**: Access the new "Reusable Resources" section in FlowX.AI Designer - located alongside "Reusable Functions" - to eliminate 60-80% of repetitive development work.
> > >
> > > **Key Capabilities:**
> > >
> > > * **Data Model Support**: Full integration with Project Data Model (PDM)
> > > * **Action Scenarios**: Template-defined actions assigned during instantiation OR form-centric actions handled by User Task
> > > * **Omnichannel**: Templates work across web, mobile, and other channels
> > >
> > > **Best Practices:**
> > >
> > > * **Start with common patterns**: Identify frequently repeated business logic and UI components
> > > * **Test thoroughly**: Use interactive testing for functions and preview mode for templates
> > > * **Document usage**: Include clear descriptions and example use cases
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Revolutionary Business Impact**: Reusable Resources fundamentally changes how organizations approach process development, transforming from "build every time" to "build once, leverage everywhere."
> > >
> > > **Strategic Business Value:**
> > >
> > > * **Quality Assurance**: Dramatic reduction in defects through reusable, tested components
> > > * **Maintenance Efficiency**: Update business rules once to instantly affect all processes
> > > * **Team Productivity**: Developers focus on new business capabilities instead of repetitive development
> > > * **Consistency**: Ensure uniform business rules and user experience across all touchpoints
> > >
> > > **Industry Use Cases:**
> > >
> > > * **Functions**: KYC validation, credit scoring, fraud detection, regulatory compliance checks
> > >
> > > * **UI Templates**: Customer onboarding forms, document upload sections, account summary dashboards, loan application interfaces
> > >
> > > * **Functions**: Premium calculations, risk evaluation, claims processing, policy validation
> > >
> > > * **UI Templates**: Quote request forms, claims submission interfaces, policy comparison tables, agent dashboards
> > >
> > > * **Functions**: Patient eligibility checks, treatment authorization, billing calculations, compliance validation
> > >
> > > * **UI Templates**: Patient registration forms, appointment scheduling interfaces, medical history cards, provider dashboards
>
> ### **Files in Integration Designer**
>
> > [card] File Handling in Integration Designer
> >
> > FlowX.AI 5.0 introduces native file handling capabilities in Integration Designer, enabling seamless file uploads and downloads with external systems directly within your integration workflows.
> >
> > > [card] Download Files
> > >
> > > Call external APIs and receive files in the response. Integration Designer saves files to Document Plugin or S3 and returns paths for further processing.
> >
> > > [card] Upload Files
> > >
> > > Send files stored in Document Plugin or S3 to external APIs via multipart/form-data or single binary requests.
> >
> > > [card] Multiple Formats
> > >
> > > Support for JSON responses with Base64 encoded files and single binary responses with automatic file identification.
> >
> > > [card] Flexible Storage
> > >
> > > Configure file destinations to Document Plugin (process-linked) or S3 Protocol (custom buckets) based on your needs.
> >
> > [Learn more about File Handling in Integration Designer](../../../5.1/docs/platform-deep-dive/integrations/integration-designer#file-handling)
> >
> > New Feature
>
> ### **Rendering Improvements**
>
> > [card] UI/UX Enhancements
> >
> > > [tab] Grid & Layout Improvements
> > >
> > > > [card] Enhanced Grid Component
> > > >
> > > > Improved performance, responsiveness, and customization options for data display and form organization
> > >
> > > > [card] Navigation Areas Redesign
> > > >
> > > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> > >
> > > > [card] Multi Actions Support
> > > >
> > > > Batch operations support for UI components, enabling simultaneous actions on multiple elements
> > >
> > > > [card] Permission-Based UI Editing
> > > >
> > > > Granular control over UI element editing based on user permissions with partial editing capabilities
> >
> > > [tab] Enhanced Form Controls
> > >
> > > > [card] Input Type Code
> > > >
> > > > Specialized input component for code entry
> > >
> > > > [card] Formatting Options
> > > >
> > > > Advanced formatting capabilities for Input and Slider components
> > >
> > > > [card] Switch Variants
> > > >
> > > > Enhanced switch component supporting both toggle and checkbox variants
> > >
> > > > [card] Disabled Options on Selectors
> > > >
> > > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > > [tab] Advanced Features
> > >
> > > > [card] Custom Loader
> > > >
> > > > Configurable loading indicators for improved user experience during data operations
> > >
> > > > [card] Custom Validators
> > > >
> > > > Advanced validation logic using dynamic computed expressions
> > >
> > > > [card] File Upload Button Type
> > > >
> > > > New specialized button variant designed for file upload operations
> > >
> > > > [card] Copy Styles
> > > >
> > > > Efficiently replicate styling across multiple UI components
> >
> > > [tab] Analytics & Process
> > >
> > > > [card] Analytics Enhancements
> > > >
> > > > Custom payload support for detailed user interaction tracking and business intelligence
> > >
> > > > [card] Process End Handling
> > > >
> > > > Improved user experience when processes complete or terminate
> > >
> > > > [card] Forms in Collections
> > > >
> > > > Enhanced support for form elements within collection components
> > >
> > > > [card] Template Management
> > > >
> > > > Streamlined template organization by consolidating functionality in Reusable Resources

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.0](./deployment-guidelines-v5.0)
> >
> > Instructions for deploying FlowX.AI 5.0.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.0/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.0.0


# Deployment guidelines v5.1.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.1 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.0 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.0 → 5.1.1**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.64.3** | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **9.66.5** | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **9.36.3** | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **9.29.1** | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **9.35.1** | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **9.34.2** | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **9.23.1** | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **9.30.1** | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **9.25.1** | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **9.50.0** | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **9.22.1** | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **9.34.2** | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **9.22.1** | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Renderers

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **9.0.5** | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **9.0.3** | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.0 | 0.2.4 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.5** | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.1 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.0 processes and configurations

### What's included in 5.1.1

This maintenance release includes:

* **WCAG 2.1 Level AA compliance** across all web components (28 improvements)
* **3 customer-reported issue fixes** for production environments
* **62 proactive quality improvements** identified through internal testing
* **Platform enhancements** for SSE handling, CMS tags, and infrastructure

For detailed information on all changes, see the [FlowX.AI 5.1.1 Release Notes](./v5.1.1-november-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.1 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.1 | PostgreSQL | 16 - 17 |
| 5.1.1 | Oracle Database | 21c, 23ai |
| 5.1.1 | MongoDB | 7 - 8 |
| 5.1.1 | Redis | 7.4 - 8.0 |
| 5.1.1 | Elasticsearch | 8 |
| 5.1.1 | Angular (Web SDK) | 19.x |
| 5.1.1 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.10 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.9 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.9 → 5.1.10**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **process-engine** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **admin** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **designer** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **cms-core** | 9.46.3 | 9.46.2 | 9.45.4 | 9.44.2 |
| **scheduler-core** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **events-gateway** | 9.36.4 | 9.36.2 | 9.35.4 | 9.34.1 |
| **notification-plugin** | 9.39.3 | 9.39.2 | 9.38.4 | 9.37.1 |
| **document-plugin** | 9.44.3 | 9.44.2 | 9.43.4 | 9.42.2 |
| **task-management-plugin** | 9.43.3 | 9.43.2 | 9.42.4 | 9.41.1 |
| **data-search** | 9.32.3 | 9.32.2 | 9.31.4 | 9.30.1 |
| **audit-core** | 9.40.3 | 9.40.2 | 9.39.4 | 9.38.1 |
| **advancing-controller** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **integration-designer** | 9.59.4 | 9.59.3 | 9.58.5 | 9.57.1 |
| **application-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **runtime-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **data-sync** | 9.33.4 | 9.33.2 | 9.32.3 | 9.31.1 |
| **authorization-system** | 9.43.5 | 9.43.2 | 9.42.4 | 9.41.1 |
| **nosql-db-runner** | 9.31.3 | 9.31.2 | 9.30.4 | 9.29.1 |

### Renderers

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **iOS renderer** | 9.0.25 | 9.0.20 | 9.0.19 | 9.0.12 |
| **Android renderer** | 9.0.31 | 9.0.24 | 9.0.19 | 9.0.13 |

### Plugins

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.7 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.10 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** starting with 5.1.10 the default Redis read mode is `polling` (`EVENTS_REDIS_MODE`). This is applied automatically on upgrade; no action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.9 processes and configurations

### What's included in 5.1.10

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.10 Release Notes](./v5.1.10-june-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.10 | Keycloak | 26+ |
| 5.1.10 | Kafka | 3.8 - 3.9 |
| 5.1.10 | PostgreSQL | 16 - 17 |
| 5.1.10 | Oracle Database | 21c, 23ai |
| 5.1.10 | MongoDB | 7 - 8 |
| 5.1.10 | Redis | 7.4 - 8.0 |
| 5.1.10 | Elasticsearch | 8 - 9 |
| 5.1.10 | Angular (Web SDK) | 19.2 |
| 5.1.10 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.11 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.10 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.10 → 5.1.11**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **process-engine** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **admin** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **designer** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **cms-core** | 9.47.3 | 9.46.3 | 9.46.2 | 9.45.4 |
| **scheduler-core** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **events-gateway** | 9.37.3 | 9.36.4 | 9.36.2 | 9.35.4 |
| **notification-plugin** | 9.40.3 | 9.39.3 | 9.39.2 | 9.38.4 |
| **document-plugin** | 9.45.3 | 9.44.3 | 9.44.2 | 9.43.4 |
| **task-management-plugin** | 9.44.4 | 9.43.3 | 9.43.2 | 9.42.4 |
| **data-search** | 9.33.3 | 9.32.3 | 9.32.2 | 9.31.4 |
| **audit-core** | 9.41.3 | 9.40.3 | 9.40.2 | 9.39.4 |
| **advancing-controller** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **integration-designer** | 9.60.3 | 9.59.4 | 9.59.3 | 9.58.5 |
| **application-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **runtime-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **data-sync** | 9.34.2 | 9.33.4 | 9.33.2 | 9.32.3 |
| **authorization-system** | 9.44.4 | 9.43.5 | 9.43.2 | 9.42.4 |
| **nosql-db-runner** | 9.32.3 | 9.31.3 | 9.31.2 | 9.30.4 |

### Renderers

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **iOS renderer** | 9.0.27 | 9.0.25 | 9.0.20 | 9.0.19 |
| **Android renderer** | 9.0.37 | 9.0.31 | 9.0.24 | 9.0.19 |

### Plugins

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.7 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.11 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.10 processes and configurations

### What's included in 5.1.11

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.11 Release Notes](./v5.1.11-july-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.11 | Keycloak | 26+ |
| 5.1.11 | Kafka | 3.8, 3.9 |
| 5.1.11 | PostgreSQL | 16, 17 |
| 5.1.11 | Oracle Database | 21c, 23ai |
| 5.1.11 | MongoDB | 7, 8 |
| 5.1.11 | Redis | 7, 8 |
| 5.1.11 | Elasticsearch | 8 |
| 5.1.11 | Angular (Web SDK) | 19.2 |
| 5.1.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.12

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.12 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.11 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.11 → 5.1.12**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **process-engine** | 9.76.7 | 9.76.3 | 9.75.7 | 9.75.3 |
| **admin** | 9.76.6 | 9.76.3 | 9.75.7 | 9.75.3 |
| **designer** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **cms-core** | 9.47.5 | 9.47.3 | 9.46.3 | 9.46.2 |
| **scheduler-core** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **events-gateway** | 9.37.4 | 9.37.3 | 9.36.4 | 9.36.2 |
| **notification-plugin** | 9.40.4 | 9.40.3 | 9.39.3 | 9.39.2 |
| **document-plugin** | 9.45.4 | 9.45.3 | 9.44.3 | 9.44.2 |
| **task-management-plugin** | 9.44.6 | 9.44.4 | 9.43.3 | 9.43.2 |
| **data-search** | 9.33.4 | 9.33.3 | 9.32.3 | 9.32.2 |
| **audit-core** | 9.41.4 | 9.41.3 | 9.40.3 | 9.40.2 |
| **advancing-controller** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **integration-designer** | 9.60.5 | 9.60.3 | 9.59.4 | 9.59.3 |
| **application-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **runtime-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **data-sync** | 9.34.3 | 9.34.2 | 9.33.4 | 9.33.2 |
| **authorization-system** | 9.44.5 | 9.44.4 | 9.43.5 | 9.43.2 |
| **nosql-db-runner** | 9.32.4 | 9.32.3 | 9.31.3 | 9.31.2 |

### Renderers

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **iOS renderer** | 9.0.29 | 9.0.27 | 9.0.25 | 9.0.20 |
| **Android renderer** | 9.0.39 | 9.0.37 | 9.0.31 | 9.0.24 |

### Plugins

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.7 | 0.2.6 |

### AI Platform

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.12 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.11 processes and configurations

### What's included in 5.1.12

This maintenance release includes:

* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.12 Release Notes](./v5.1.12-august-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.12 | Keycloak | 26+ |
| 5.1.12 | Kafka | 3.8, 3.9 |
| 5.1.12 | PostgreSQL | 16, 17 |
| 5.1.12 | Oracle Database | 21c, 23ai |
| 5.1.12 | MongoDB | 7, 8 |
| 5.1.12 | Redis | 7, 8 |
| 5.1.12 | Elasticsearch | 8 |
| 5.1.12 | Angular (Web SDK) | 19.2 |
| 5.1.12 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.13
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.13

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.13 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.12 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.12 → 5.1.13**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **process-engine** | 9.76.10 | 9.76.7 | 9.76.3 | 9.75.7 |
| **admin** | 9.76.8 | 9.76.6 | 9.76.3 | 9.75.7 |
| **designer** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **cms-core** | 9.47.6 | 9.47.5 | 9.47.3 | 9.46.3 |
| **scheduler-core** | 9.36.5 | 9.36.4 | 9.36.3 | 9.35.3 |
| **events-gateway** | 9.37.5 | 9.37.4 | 9.37.3 | 9.36.4 |
| **notification-plugin** | 9.40.5 | 9.40.4 | 9.40.3 | 9.39.3 |
| **document-plugin** | 9.45.5 | 9.45.4 | 9.45.3 | 9.44.3 |
| **task-management-plugin** | 9.44.7 | 9.44.6 | 9.44.4 | 9.43.3 |
| **data-search** | 9.33.5 | 9.33.4 | 9.33.3 | 9.32.3 |
| **audit-core** | 9.41.5 | 9.41.4 | 9.41.3 | 9.40.3 |
| **advancing-controller** | 9.36.6 | 9.36.4 | 9.36.3 | 9.35.3 |
| **integration-designer** | 9.60.7 | 9.60.5 | 9.60.3 | 9.59.4 |
| **application-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **runtime-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **data-sync** | 9.34.4 | 9.34.3 | 9.34.2 | 9.33.4 |
| **authorization-system** | 9.44.6 | 9.44.5 | 9.44.4 | 9.43.5 |
| **nosql-db-runner** | 9.32.5 | 9.32.4 | 9.32.3 | 9.31.3 |

### Renderers

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **iOS renderer** | 9.0.32 | 9.0.29 | 9.0.27 | 9.0.25 |
| **Android renderer** | 9.0.44 | 9.0.39 | 9.0.37 | 9.0.31 |

### Plugins

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.7 |

### AI Platform

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.13 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.12 processes and configurations

### What's included in 5.1.13

This maintenance release includes:

* **Reliability fixes** for process advancing under load
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.13 Release Notes](./v5.1.13-september-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.13 | Keycloak | 26+ |
| 5.1.13 | Kafka | 3.8, 3.9 |
| 5.1.13 | PostgreSQL | 16, 17 |
| 5.1.13 | Oracle Database | 21c, 23ai |
| 5.1.13 | MongoDB | 7, 8 |
| 5.1.13 | Redis | 7, 8 |
| 5.1.13 | Elasticsearch | 8 |
| 5.1.13 | Angular (Web SDK) | 19.2 |
| 5.1.13 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.2 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.1 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.1 → 5.1.2**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **process-engine** | **9.67.0** | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **9.68.1** | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **9.39.0** | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **9.28.1** | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **9.29.0** | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **9.32.0** | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **9.37.1** | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **9.25.1** | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **9.33.0** | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **9.28.0** | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **9.52.1** | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **9.26.0** | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **9.24.1** | 9.22.1 | 9.21.0 | 9.11.0 |

### Renderers

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **9.0.7** | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **9.0.5** | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.0 |

### AI Platform

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.6** | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.2 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.1 processes and configurations

### What's included in 5.1.2

This maintenance release includes:

* **Bug fixes** addressing customer-reported issues
* **Stability improvements** for platform reliability
* **Quality enhancements** identified through internal testing

For detailed information on all changes, see the [FlowX.AI 5.1.2 Release Notes](./v5.1.2-december-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.2 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.2 | PostgreSQL | 16 - 17 |
| 5.1.2 | Oracle Database | 21c, 23ai |
| 5.1.2 | MongoDB | 7 - 8 |
| 5.1.2 | Redis | 7.4 - 8.0 |
| 5.1.2 | Elasticsearch | 8 |
| 5.1.2 | Angular (Web SDK) | 19.x |
| 5.1.2 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.3 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.2 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.2 → 5.1.3**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **process-engine** | **9.70.1** | 9.67.0 | 9.64.3 | 9.63.0 |
| **admin** | **9.70.2** | 9.68.1 | 9.66.5 | 9.65.0 |
| **designer** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **cms-core** | **9.41.1** | 9.39.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **9.30.1** | 9.28.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **9.31.2** | 9.29.0 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **9.34.1** | 9.32.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **9.39.1** | 9.37.1 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **9.38.2** | 9.36.1 | 9.34.2 | 9.33.0 |
| **data-search** | **9.27.1** | 9.25.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **9.35.1** | 9.33.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **9.30.2** | 9.28.0 | 9.25.1 | 9.24.0 |
| **integration-designer** | **9.54.1** | 9.52.1 | 9.50.0 | 9.49.1 |
| **application-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **data-sync** | **9.28.1** | 9.26.0 | 9.22.1 | 9.21.0 |
| **authorization-system** | **9.38.1** | 9.36.1 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **9.26.1** | 9.24.1 | 9.22.1 | 9.21.0 |

### Renderers

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **9.0.8** | 9.0.7 | 9.0.5 | 9.0.4 |
| **Android renderer** | **9.0.6** | 9.0.5 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.7** | 9.2.6 | 9.2.5 | 9.2.4 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.3 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes required\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.2 processes and configurations

### Optional configuration

A new optional environment variable is available for process-engine:

| Variable | Description | Default |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from platform components | Falls back to `KAFKA_TOPIC_PATTERN` |

> [!NOTE]
>
> This allows connectors to use custom topic patterns without affecting other components like document-plugin, data-search, and cms-core that use `ai.flowx.engine.receive.*`.

### What's included in 5.1.3

This maintenance release includes:

* **Security fixes**
* **Bug fixes** addressing customer-reported issues

For detailed information on all changes, see the [FlowX.AI 5.1.3 Release Notes](./v5.1.3-january-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.3 | Keycloak | 26+ |
| 5.1.3 | Kafka | 3.8 - 3.9 |
| 5.1.3 | PostgreSQL | 16 - 17 |
| 5.1.3 | Oracle Database | 21c, 23ai |
| 5.1.3 | MongoDB | 7 - 8 |
| 5.1.3 | Redis | 7.4 - 8.0 |
| 5.1.3 | Elasticsearch | 8 |
| 5.1.3 | Angular (Web SDK) | 19.2 |
| 5.1.3 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.4 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.3 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.3 → 5.1.4**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **process-engine** | **9.72.2** | 9.70.1 | 9.67.0 | 9.64.3 |
| **admin** | **9.72.0** | 9.70.2 | 9.68.1 | 9.66.5 |
| **designer** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **cms-core** | **9.43.1** | 9.41.1 | 9.39.0 | 9.36.3 |
| **scheduler-core** | **9.32.0** | 9.30.1 | 9.28.1 | 9.26.1 |
| **events-gateway** | **9.33.0** | 9.31.2 | 9.29.0 | 9.26.1 |
| **notification-plugin** | **9.36.0** | 9.34.1 | 9.32.0 | 9.29.1 |
| **document-plugin** | **9.41.1** | 9.39.1 | 9.37.1 | 9.35.1 |
| **task-management-plugin** | **9.40.0** | 9.38.2 | 9.36.1 | 9.34.2 |
| **data-search** | **9.29.0** | 9.27.1 | 9.25.1 | 9.23.1 |
| **audit-core** | **9.37.0** | 9.35.1 | 9.33.0 | 9.30.1 |
| **advancing-controller** | **9.32.0** | 9.30.2 | 9.28.0 | 9.25.1 |
| **integration-designer** | **9.56.0** | 9.54.1 | 9.52.1 | 9.50.0 |
| **application-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **runtime-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **data-sync** | **9.30.1** | 9.28.1 | 9.26.0 | 9.22.1 |
| **authorization-system** | **9.40.1** | 9.38.1 | 9.36.1 | 9.34.2 |
| **nosql-db-runner** | **9.28.0** | 9.26.1 | 9.24.1 | 9.22.1 |

### Renderers

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **iOS renderer** | **9.0.9** | 9.0.8 | 9.0.7 | 9.0.5 |
| **Android renderer** | **9.0.7** | 9.0.6 | 9.0.5 | 9.0.3 |

### Plugins

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.8** | 9.2.7 | 9.2.6 | 9.2.5 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.4 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.3 processes and configurations

#### New environment variables (optional)

The following optional environment variables have been added for the **process-engine** to configure config params caching:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120` | process-engine |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache | `500` | process-engine |

> [!NOTE]
>
> These variables are optional. If not configured, the default values will be used. Adjust these values based on how frequently your configuration changes and your memory constraints.
>
> For more details, see [Engine Setup - Config params cache](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).

### What's included in 5.1.4

This maintenance release includes:

* **Security patches** addressing identified vulnerabilities
* **Bug fixes** addressing customer-reported issues
* **Platform improvements** including cache improvements, Kafka environment variable alignment, SSE metrics enhancements, and infrastructure updates

For detailed information on all changes, see the [FlowX.AI 5.1.4 Release Notes](./v5.1.4-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.4 | Keycloak | 26+ |
| 5.1.4 | Kafka | 3.8 - 3.9 |
| 5.1.4 | PostgreSQL | 16 - 17 |
| 5.1.4 | Oracle Database | 21c, 23ai |
| 5.1.4 | MongoDB | 7 - 8 |
| 5.1.4 | Redis | 7.4 - 8.0 |
| 5.1.4 | Elasticsearch | 8 |
| 5.1.4 | Angular (Web SDK) | 19.2 |
| 5.1.4 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.5 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.4 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.4 → 5.1.5**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **process-engine** | **9.72.5** | 9.72.2 | 9.70.1 | 9.67.0 |
| **admin** | **9.72.2** | 9.72.0 | 9.70.2 | 9.68.1 |
| **designer** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **cms-core** | **9.43.3** | 9.43.1 | 9.41.1 | 9.39.0 |
| **scheduler-core** | **9.32.2** | 9.32.0 | 9.30.1 | 9.28.1 |
| **events-gateway** | **9.33.2** | 9.33.0 | 9.31.2 | 9.29.0 |
| **notification-plugin** | **9.36.2** | 9.36.0 | 9.34.1 | 9.32.0 |
| **document-plugin** | **9.41.3** | 9.41.1 | 9.39.1 | 9.37.1 |
| **task-management-plugin** | **9.40.2** | 9.40.0 | 9.38.2 | 9.36.1 |
| **data-search** | **9.29.2** | 9.29.0 | 9.27.1 | 9.25.1 |
| **audit-core** | **9.37.2** | 9.37.0 | 9.35.1 | 9.33.0 |
| **advancing-controller** | **9.32.1** | 9.32.0 | 9.30.2 | 9.28.0 |
| **integration-designer** | **9.56.2** | 9.56.0 | 9.54.1 | 9.52.1 |
| **application-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **runtime-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **data-sync** | **9.30.2** | 9.30.1 | 9.28.1 | 9.26.0 |
| **authorization-system** | **9.40.2** | 9.40.1 | 9.38.1 | 9.36.1 |
| **nosql-db-runner** | **9.28.2** | 9.28.0 | 9.26.1 | 9.24.1 |

### Renderers

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **iOS renderer** | **9.0.10** | 9.0.9 | 9.0.8 | 9.0.7 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.6 | 9.0.5 |

### Plugins

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.9** | 9.2.8 | 9.2.7 | 9.2.6 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.5 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No new environment variables
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.4 processes and configurations

### What's included in 5.1.5

This maintenance release includes:

* **Bug fixes** for process loop rendering issues in the Angular renderer
* **Bug fixes** for subprocess output data not being returned from embedded processes

For detailed information on all changes, see the [FlowX.AI 5.1.5 Release Notes](./v5.1.5-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.5 | Keycloak | 26+ |
| 5.1.5 | Kafka | 3.8 - 3.9 |
| 5.1.5 | PostgreSQL | 16 - 17 |
| 5.1.5 | Oracle Database | 21c, 23ai |
| 5.1.5 | MongoDB | 7 - 8 |
| 5.1.5 | Redis | 7.4 - 8.0 |
| 5.1.5 | Elasticsearch | 8 |
| 5.1.5 | Angular (Web SDK) | 19.2 |
| 5.1.5 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.6 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.5 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.5 → 5.1.6**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **process-engine** | **9.72.7** | 9.72.5 | 9.72.2 | 9.70.1 |
| **admin** | **9.72.4** | 9.72.2 | 9.72.0 | 9.70.2 |
| **designer** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **cms-core** | **9.43.5** | 9.43.3 | 9.43.1 | 9.41.1 |
| **scheduler-core** | **9.32.4** | 9.32.2 | 9.32.0 | 9.30.1 |
| **events-gateway** | **9.33.4** | 9.33.2 | 9.33.0 | 9.31.2 |
| **notification-plugin** | **9.36.4** | 9.36.2 | 9.36.0 | 9.34.1 |
| **document-plugin** | **9.41.5** | 9.41.3 | 9.41.1 | 9.39.1 |
| **task-management-plugin** | **9.40.4** | 9.40.2 | 9.40.0 | 9.38.2 |
| **data-search** | **9.29.4** | 9.29.2 | 9.29.0 | 9.27.1 |
| **audit-core** | **9.37.4** | 9.37.2 | 9.37.0 | 9.35.1 |
| **advancing-controller** | **9.32.3** | 9.32.1 | 9.32.0 | 9.30.2 |
| **integration-designer** | **9.56.3** | 9.56.2 | 9.56.0 | 9.54.1 |
| **application-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **runtime-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **data-sync** | **9.30.4** | 9.30.2 | 9.30.1 | 9.28.1 |
| **authorization-system** | **9.40.3** | 9.40.2 | 9.40.1 | 9.38.1 |
| **nosql-db-runner** | **9.28.4** | 9.28.2 | 9.28.0 | 9.26.1 |

### Renderers

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **iOS renderer** | **9.0.11** | 9.0.10 | 9.0.9 | 9.0.8 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.7 | 9.0.6 |

### Plugins

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.8 | 9.2.7 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.6 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> This release introduces optional environment variables for the process engine retry mechanism. These are not required — defaults work for most deployments.

#### Process engine — retry configuration (optional)

The following optional environment variables configure the exponential backoff with Equal Jitter strategy used for optimistic locking retries:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` | process-engine |

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.5 processes and configurations

### What's included in 5.1.6

This maintenance release includes:

* **Bug fixes** for React renderer: modals, sliders, datepicker, selectors, disabled state, and accessibility
* **Bug fixes** for Angular + React renderer: card accordion height, focus outlines, button icon layout
* **Bug fix** for process engine advancing getting stuck on pod crash
* **Bug fix** for connection leak in application-manager export/import
* **Improvement** for configurable retry mechanism with exponential backoff
* **Security patches** across all platform components

For detailed information on all changes, see the [FlowX.AI 5.1.6 Release Notes](./v5.1.6-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.6 | Keycloak | 26+ |
| 5.1.6 | Kafka | 3.8 - 3.9 |
| 5.1.6 | PostgreSQL | 16 - 17 |
| 5.1.6 | Oracle Database | 21c, 23ai |
| 5.1.6 | MongoDB | 7 - 8 |
| 5.1.6 | Redis | 7.4 - 8.0 |
| 5.1.6 | Elasticsearch | 8 |
| 5.1.6 | Angular (Web SDK) | 19.2 |
| 5.1.6 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.7
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.7 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.6 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.6 → 5.1.7**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **process-engine** | **9.73.1** | 9.72.7 | 9.72.5 | 9.72.2 |
| **admin** | **9.73.1** | 9.72.4 | 9.72.2 | 9.72.0 |
| **designer** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **cms-core** | **9.44.2** | 9.43.5 | 9.43.3 | 9.43.1 |
| **scheduler-core** | **9.33.1** | 9.32.4 | 9.32.2 | 9.32.0 |
| **events-gateway** | **9.34.1** | 9.33.4 | 9.33.2 | 9.33.0 |
| **notification-plugin** | **9.37.1** | 9.36.4 | 9.36.2 | 9.36.0 |
| **document-plugin** | **9.42.2** | 9.41.5 | 9.41.3 | 9.41.1 |
| **task-management-plugin** | **9.41.1** | 9.40.4 | 9.40.2 | 9.40.0 |
| **data-search** | **9.30.1** | 9.29.4 | 9.29.2 | 9.29.0 |
| **audit-core** | **9.38.1** | 9.37.4 | 9.37.2 | 9.37.0 |
| **advancing-controller** | **9.33.1** | 9.32.3 | 9.32.1 | 9.32.0 |
| **integration-designer** | **9.57.1** | 9.56.3 | 9.56.2 | 9.56.0 |
| **application-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **runtime-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **data-sync** | **9.31.1** | 9.30.4 | 9.30.2 | 9.30.1 |
| **authorization-system** | **9.41.1** | 9.40.3 | 9.40.2 | 9.40.1 |
| **nosql-db-runner** | **9.29.1** | 9.28.4 | 9.28.2 | 9.28.0 |

### Renderers

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **iOS renderer** | **9.0.12** | 9.0.11 | 9.0.10 | 9.0.9 |
| **Android renderer** | **9.0.13** | 9.0.7 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI Platform

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.8 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.7 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.6 processes and configurations

### What's included in 5.1.7

This maintenance release includes:

* **Bug fix** for build reimport failures with manifest issues
* **Security patches** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.7 Release Notes](./v5.1.7-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.7 | Keycloak | 26+ |
| 5.1.7 | Kafka | 3.8 - 3.9 |
| 5.1.7 | PostgreSQL | 16 - 17 |
| 5.1.7 | Oracle Database | 21c, 23ai |
| 5.1.7 | MongoDB | 7 - 8 |
| 5.1.7 | Redis | 7.4 - 8.0 |
| 5.1.7 | Elasticsearch | 8 |
| 5.1.7 | Angular (Web SDK) | 19.2 |
| 5.1.7 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.8
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.8 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.7 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.7 → 5.1.8**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **process-engine** | **9.74.4** | 9.73.1 | 9.72.7 | 9.72.5 |
| **admin** | **9.74.4** | 9.73.1 | 9.72.4 | 9.72.2 |
| **designer** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **cms-core** | **9.45.4** | 9.44.2 | 9.43.5 | 9.43.3 |
| **scheduler-core** | **9.34.4** | 9.33.1 | 9.32.4 | 9.32.2 |
| **events-gateway** | **9.35.4** | 9.34.1 | 9.33.4 | 9.33.2 |
| **notification-plugin** | **9.38.4** | 9.37.1 | 9.36.4 | 9.36.2 |
| **document-plugin** | **9.43.4** | 9.42.2 | 9.41.5 | 9.41.3 |
| **task-management-plugin** | **9.42.4** | 9.41.1 | 9.40.4 | 9.40.2 |
| **data-search** | **9.31.4** | 9.30.1 | 9.29.4 | 9.29.2 |
| **audit-core** | **9.39.4** | 9.38.1 | 9.37.4 | 9.37.2 |
| **advancing-controller** | **9.34.4** | 9.33.1 | 9.32.3 | 9.32.1 |
| **integration-designer** | **9.58.5** | 9.57.1 | 9.56.3 | 9.56.2 |
| **application-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **runtime-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **data-sync** | **9.32.3** | 9.31.1 | 9.30.4 | 9.30.2 |
| **authorization-system** | **9.42.4** | 9.41.1 | 9.40.3 | 9.40.2 |
| **nosql-db-runner** | **9.30.4** | 9.29.1 | 9.28.4 | 9.28.2 |

### Renderers

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **iOS renderer** | **9.0.19** | 9.0.12 | 9.0.11 | 9.0.10 |
| **Android renderer** | **9.0.19** | 9.0.13 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.8 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.7 processes and configurations

### What's included in 5.1.8

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.8 Release Notes](./v5.1.8-april-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.8 | Keycloak | 26+ |
| 5.1.8 | Kafka | 3.8 - 3.9 |
| 5.1.8 | PostgreSQL | 16 - 17 |
| 5.1.8 | Oracle Database | 21c, 23ai |
| 5.1.8 | MongoDB | 7 - 8 |
| 5.1.8 | Redis | 7.4 - 8.0 |
| 5.1.8 | Elasticsearch | 8 |
| 5.1.8 | Angular (Web SDK) | 19.2 |
| 5.1.8 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.9
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.9 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.8 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.8 → 5.1.9**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **process-engine** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.7 |
| **admin** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.4 |
| **designer** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **cms-core** | **9.46.2** | 9.45.4 | 9.44.2 | 9.43.5 |
| **scheduler-core** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.4 |
| **events-gateway** | **9.36.2** | 9.35.4 | 9.34.1 | 9.33.4 |
| **notification-plugin** | **9.39.2** | 9.38.4 | 9.37.1 | 9.36.4 |
| **document-plugin** | **9.44.2** | 9.43.4 | 9.42.2 | 9.41.5 |
| **task-management-plugin** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.4 |
| **data-search** | **9.32.2** | 9.31.4 | 9.30.1 | 9.29.4 |
| **audit-core** | **9.40.2** | 9.39.4 | 9.38.1 | 9.37.4 |
| **advancing-controller** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.3 |
| **integration-designer** | **9.59.3** | 9.58.5 | 9.57.1 | 9.56.3 |
| **application-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **runtime-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **data-sync** | **9.33.2** | 9.32.3 | 9.31.1 | 9.30.4 |
| **authorization-system** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.3 |
| **nosql-db-runner** | **9.31.2** | 9.30.4 | 9.29.1 | 9.28.4 |

### Renderers

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **iOS renderer** | **9.0.20** | 9.0.19 | 9.0.12 | 9.0.11 |
| **Android renderer** | **9.0.24** | 9.0.19 | 9.0.13 | 9.0.7 |

### Plugins

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.9 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.8 processes and configurations

### What's included in 5.1.9

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.9 Release Notes](./v5.1.9-may-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.9 | Keycloak | 26+ |
| 5.1.9 | Kafka | 3.8 - 3.9 |
| 5.1.9 | PostgreSQL | 16 - 17 |
| 5.1.9 | Oracle Database | 21c, 23ai |
| 5.1.9 | MongoDB | 7 - 8 |
| 5.1.9 | Redis | 7.4 - 8.0 |
| 5.1.9 | Elasticsearch | 8 - 9 |
| 5.1.9 | Angular (Web SDK) | 19.2 |
| 5.1.9 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/deployment-guidelines-v5.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.63.0** | 9.29.2 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.65.0** | 9.25.2 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.35.0** | 9.21.2 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.28.0** | 9.14.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.34.0** | 9.17.2 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.33.0** | 9.14.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.22.0** | 9.12.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.29.1** | 9.15.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.24.0** | 9.11.0 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.49.1** | 9.26.2 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.21.0** | 9.11.0 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.33.0** | 9.14.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.21.0** | 9.11.0 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.4** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.2** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | **0.2.4** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.4** | 9.2.3 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.3.1** | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.0 | Keycloak | 26+ |
| 5.1.0 | Kafka | 3.8 - 3.9 |
| 5.1.0 | PostgreSQL | 16 - 17 |
| 5.1.0 | Oracle Database | 21c, 23ai |
| 5.1.0 | MongoDB | 7 - 8 |
| 5.1.0 | Redis | 7.4 - 8.0 |
| 5.1.0 | Elasticsearch | 8 - 9 |
| 5.1.0 | Angular (Web SDK) | 19.x |
| 5.1.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/configuration-and-migration

This section contains the steps in order that we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](/5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.1.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.1.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.1.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The auth-system will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from app-manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Document plugin

> [!NOTE]
>
> New configuration option for test documents bucket customization.

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILE_STORAGE_TEST_FILES_BUCKET` | `-test-documents` | Overrides the default test documents bucket suffix. Use this to configure a custom bucket name for test files. |

> [!NOTE]
>
> This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed.

## Kafka configuration

> [!NOTE]
>
> Complete Kafka migration including consumer group standardization to kebab-case, comprehensive topic restructuring with new versioned naming patterns, and enhanced messaging features across all FlowX.AI services.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group migrations

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Kafka topic migrations

> [!NOTE]
>
> All Kafka topics migrate to versioned naming pattern `ai.flowx.{env}.{service}.{operation}.v1` for improved organization and future compatibility.

> [tab] Application Manager
>
> **Application resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
>
> **Sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS_IN` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE_IN` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE_IN` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN` | `ai.flowx.application-version.sync.out.v1` |
>
> **Resource update propagation:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | `ai.flowx.application-version.resource.update.propagation.v1` |
>
> **Build resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

> [tab] Admin
>
> **Consumer groups:**
>
> | Environment Variable | New Consumer Group | Threads |
> | - | - | - |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_SYNC` | `process-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC` | `business-rule-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC` | `reusable-template-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION` | `processCorrectionAfterAppOperationGroup` | `6` |
>
> **Application sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE` | `ai.flowx.application-version.sync.out.v1` |
> | `KAFKA_TOPIC_APPLICATION_PROCESS_SYNC` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
>
> **Application correction after app operation topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
>
> **Build topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

### New Kafka features

> [card] Resource Update Propagation
>
> **Consumer Group:** `app-resource-update-propagation-group`\
> **Threads:** 3\
> **Topic:** `ai.flowx.{env}.application-version.resource.update.propagation.v1`\
> **Purpose:** Real-time resource change propagation

> [card] Build Runtime Data
>
> **Consumer Group:** `build-runtime-data-group`\
> **Threads:** 2\
> **Topic:** `ai.flowx.{env}.build.runtime-data.v1`\
> **Purpose:** Build process data management

> [card] Business Rule Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> **Purpose:** Enhanced business rule synchronization\
> **Consumer Group:** `business-rule-sync-group`

> [card] Process Sync Enhanced
>
> **Topic:** `ai.flowx.{env}.application-version.sync.process.in.v1`\
> **Purpose:** Improved process synchronization\
> **Consumer Group:** `process-sync-group`

> [card] Reusable Template Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> **Purpose:** Template synchronization\
> **Consumer Group:** `reusable-template-sync-group`

> [card] Correction After App Operation
>
> **Multiple Topics:** Process, business rule, and template correction\
> **Purpose:** Post-deployment resource correction\
> **Consumer Group:** `processCorrectionAfterAppOperationGroup`

### Configure environment variables

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides. Only override when custom naming is required.

```bash Application Manager Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Sync Topics
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
```

```bash Admin Topics theme={"dark"}
# Application Sync
KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE=ai.flowx.dev.application-version.sync.out.v1
KAFKA_TOPIC_APPLICATION_PROCESS_SYNC=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT=ai.flowx.dev.application-version.correction-after-app-operation.response.v1
```

```bash Consumer Groups and Threads theme={"dark"}
# Application Manager Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Admin Consumer Groups  
KAFKA_CONSUMER_GROUPID_PROCESS_SYNC=process-sync-group
KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC=business-rule-sync-group
KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC=reusable-template-sync-group
KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION=processCorrectionAfterAppOperationGroup

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
KAFKA_CONSUMER_THREADS_PROCESS_SYNC=6
KAFKA_CONSUMER_THREADS_BUSINESS_RULE_SYNC=6
KAFKA_CONSUMER_THREADS_REUSABLE_TEMPLATE_SYNC=6
KAFKA_CONSUMER_THREADS_PROCESS_CORRECTIONAFTERAPPOPERATION=6
```

### Additional Application Manager variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | Maximum HTTP request header size |

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | Redis host |
| `SPRING_REDIS_PORT` | `6379` | Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | Redis password |
| `SPRING_REDIS_TTL` | `5000000` | Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | Redis host |

## FlowX Engine

> [!NOTE]
>
> The ADVANCING controller has been redesigned with separate picking and processing operations for improved performance and resource management.

### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.

### Elasticsearch indexing configuration

> [!NOTE]
>
> Elasticsearch indexing environment variables have been updated with new naming conventions for better consistency with FlowX naming standards.

#### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEXING_TYPE` | `FLOWX_INDEXING_TYPE` | `kafka` | `kafka` |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` | `process_instance` |
| `FLOWX_INDEXING_PROCESSINSTANCE_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `FLOWX_INDEXING_PROCESSINSTANCE_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

> [!NOTE]
>
> For complete Elasticsearch indexing setup including Kafka Connect configuration and time-based partitioning, see the [Configuring Elasticsearch indexing](/5.1/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing) guide.

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.

### Development environment exception

> [!NOTE]
>
> For development environments only, `CONFIG_PROFILE` migrates to the standard Spring configuration profile variable.

| Remove This Variable | Replace With | Environment |
| - | - | - |
| `CONFIG_PROFILE` | `SPRING_CONFIG_PROFILE` | devenv only |

## SpiceDB integration

> [!NOTE]
>
> FlowX.AI 5.1 introduces SpiceDB integration for enhanced authorization capabilities across all core services.

### Services affected

The following services require new SpiceDB configuration variables:

* Admin
* Application Manager
* Audit Core
* CMS Core
* Document Plugin
* Integration Designer
* Notification Plugin
* Process Engine
* Runtime Manager
* Task Management Plugin

### New variables to add

For every CAS configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_SPICEDB_TOKEN` | *(secret)* | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Data sync updates

### Data Sync additional variables

For every Data-Sync configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_URL` | - | Authentication system URL. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME` | - | Authentication system username. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` | - | Authentication system password. |
| `FLOWX_SPICEDB_TOKEN` | - | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Kafka topic naming

### Global configuration change

| Variable | Old Default | New Default | Description |
| - | - | - | - |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | (varies) | `""` | Moved to default empty environment |

> [!NOTE]
>
> This change standardizes topic naming across environments by defaulting to an empty environment identifier.

## CORS and ingress updates

> [!WARNING]
>
> All services with Kubernetes ingress configurations now require the `Fx-Workspace-Id` header for workspace identification in multi-tenant environments.

### Standard ingress pattern

FlowX.AI v5.1 introduces a standardized ingress configuration pattern for all services. The key change is adding the `Fx-Workspace-Id` header to the CORS configuration.

**Required annotation update:**

```yaml theme={"dark"}
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
```

### Services requiring updates

All FlowX.AI services that expose ingress endpoints require this update:

| Service | Fx-Workspace-Id Required | Reference |
| - | - | - |
| Admin | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Application Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Audit Core | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Authorization System | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Events Gateway | ❌ No (SSE) | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) |
| Integration Designer | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Process Engine | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Runtime Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Task Management | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |

> [card] [Complete Ingress Configuration Guide](../../../../../5.1/setup-guides/ingress-configuration)
>
> View the complete ingress configuration pattern including:
>
> * Standard template for all services
> * Service-specific paths and rewrite rules
> * Annotation explanations
> * Troubleshooting guide
> * Environment-specific customization

> [!NOTE]
>
> **Exception:** Events Gateway does not require the `Fx-Workspace-Id` header because it handles Server-Sent Events (SSE) with different security requirements. See the [Events Gateway exception](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) section for details.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/install-services

Step-by-step installation guide for new FlowX.AI 5.1.0 services

FlowX.AI 5.1.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](../../../../../5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](../../../../../5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.

> [!WARNING]
>
> **Continuing to 5.9.x?** If 5.1.x is only an intermediate stop on your path to 5.9.x, land on the **latest available 5.1.x patch**, not 5.1.0. Data migrations and their fixes accumulate across the patches of the family, and the latest patch is the level guaranteed to carry all of them. Before starting the next migration, confirm the environment is fully functional: every service up and healthy in **FlowX.AI Designer → Platform Status**, and the data-sync job completed successfully. See the [5.1 → 5.9 migration prerequisites](/5.9/migrating-from-5.1-lts/prerequisites).

## Success factors

> [!WARNING]
>
> Take care when following the steps below are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB and DGraph** must be installed before any FlowX.AI services
>
> > [!NOTE]
> >
> > DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices (data migration)** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration (Elasticsearch indices)

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation

> [card] [Troubleshooting](./troubleshooting)
>
> Common issues and solutions for post-upgrade problems


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/prerequisites

This section contains the steps in order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.8 | FlowX.AI 5.1.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.1#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.1.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip this step.

> [card] [SpiceDB setup guide](../../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.1.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

> [!WARNING]
>
> Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.1.0 to ensure workspace functionality works correctly.

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Prerequisites for migration

Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:

```json theme={"dark"}
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
```

This mapping update is required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable, if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

### Post-migration impact

**Without proper Elasticsearch migration, you will experience:**

* Some process instances may not appear in search results
* Data-search functionality may not return complete results
* Workspace-scoped queries will fail for unmigrated data
* **Existing resources will not be visible or accessible within the new workspace structure**

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.1.0.

***

## Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).

Details on how to configure the organization admin user:

> [card] [Authorization system](../../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Workspaces access rights](../../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

***

#### Pre-migration preparation

You must configure the authorization-system service before migration. There are two supported approaches:

> [tab] Recommended: Use admin email (simpler)
>
> Set the following authorization-system environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=<username-of-admin-user>`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.

> [tab] Alternative: Use admin subject ID
>
> Set the following environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
>
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=<subject-id-of-admin-user>`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).
>
> > [!TIP]
> >
> > To get the subject ID of the admin user, extract it from the JWT token of the admin user.
>
> ![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.1.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users",
      "manage-realm"
    ]
  }
}
```

***

## Process instances migration

All active process instances will be migrated under default workspace.

> [!WARNING]
>
> For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.1.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.2") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.2 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.2 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.2 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.2 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.2 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# Post-upgrade troubleshooting
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/troubleshooting

Common issues and solutions that may occur after upgrading from FlowX v4.7.x to v5.1.0.

This section covers common issues that may occur after completing the upgrade to FlowX.AI 5.1.0 and their solutions.

## Designer login issues

### DataIntegrityViolationException error

If you cannot login to FlowX Designer after the 5.x upgrade and encounter the following error in the authorization-system logs:

```
org.springframework.dao.DataIntegrityViolationException: could not execute statement [ERROR: duplicate key value violates unique constraint "cas_user_username_key"
  Detail: Key (username)=(admin@flowx.ai) already exists.] [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; SQL [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; constraint [cas_user_username_key]
```

**Root Cause**: This error occurs because the `sub` (subject ID) is missing from JWT tokens. Starting with Keycloak version 25, the `sub` claim is not added by default to lightweight access tokens.

**Solution**: Ensure the `basic` Client Scope is created in your Keycloak Realm and added to all FlowX clients.

> [!WARNING]
>
> Since Keycloak version 25, the `sub` claim is not added by default to JWT lightweight tokens. This is a breaking change that affects FlowX.AI authentication.

### How to verify if subject ID is missing

**1. Login attempt**

Try to login to FlowX Designer and note if the login fails.

**2. Capture the token**

1. Open your browser's Developer Tools
2. Navigate to the **Network** tab
3. Attempt to login again
4. Look for a call to: `https://<your-keycloak-address>/auth/realms/flowx/protocol/openid-connect/token`
5. Copy the access token from the response

**3. Decode the token**

1. Go to [https://jwt.io/](https://jwt.io/)
2. Paste the token in the **Encoded** section
3. Check the **Payload** section for the presence of the `sub` claim

> [!TIP]
>
> If the `sub` claim is present, the token should contain a field like: `"sub": "12345678-1234-1234-1234-123456789abc"`

**4. Verify Client Scope configuration**

If the `sub` claim is missing, you need to configure the Client Scope in Keycloak:

1. Login to your Keycloak Admin Console
2. Navigate to your FlowX realm
3. Go to **Client Scopes**
4. Ensure the `basic` client scope exists and includes the `sub` claim
5. Add this client scope to all FlowX clients (FlowX Designer, Admin, etc.)

### Additional resources

> [card] [Keycloak Release Notes](https://www.keycloak.org/docs/latest/release_notes/#lightweight-access-token-to-be-even-more-lightweight)
>
> Official Keycloak documentation about lightweight access token changes

***

## Other common issues

> [!NOTE]
>
> Additional troubleshooting sections will be added as common post-upgrade issues are identified. If you encounter issues not covered here, please consult the FlowX support team.


# FlowX.AI 5.1.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025

Introducing Workspaces, Project Data Model, Library-to-Library Dependencies, Data Mappers, Reusable Resources, and more for a more efficient and flexible development experience.

**What's new? 🆕**

> [tab] Reusability
>
> Build once, use everywhere. These features transform how you develop and maintain applications by eliminating duplication and enabling sophisticated modular architectures.
>
> 🔄 [**Project Data Model (PDM)**](#project-data-model-pdm) - Define reusable data types at the project level to ensure consistency across processes\
> 🔄 [**Library-to-Library Dependencies**](#library-to-library-dependencies) - Create complex dependency trees with multiple levels of library-to-library relationships\
> 🔄 [**Data Mappers**](#data-mappers) - Visual drag-and-drop data mapping with reusable parameter definitions\
> 🔄 [**Reusable Resources**](#reusable-resources) - Create and manage UI Templates and Business Functions across multiple processes\
> 🔄 [**Files in Integration Designer**](#files-in-integration-designer) - Enhanced file management and reusability in integration workflows\
> 🔄 [**Resources Overrides**](#resources-overrides) - Localization and customization of core applications across multiple regions with centralized management\
> 🔄 [**Active Policy Overrides**](#active-policy-overrides) - User-specific and role-specific deployment policies for independent testing and controlled rollouts
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.1.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.1.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> ***
>
> ### **Files in Integration Designer**
>
> > [card] Files in Integration Designer
> >
> > > [tab] Files Overview
> > >
> > > ![Integration Designer file workflows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh.png)
> > >
> > > FlowX.AI 5.1.0 introduces comprehensive file handling capabilities in Integration Designer, resolving previous limitations where sending or receiving documents, photos, or any files via Integration Designer was not supported. This powerful enhancement enables seamless file exchange with external systems through automated workflows.
> >
> > > [tab] Core File Scenarios
> > >
> > > > [card] File Downloads
> > > >
> > > > Process calls external API (GET/POST) and receives files in response. Integration Designer saves files to specified location and returns paths to workflow
> > >
> > > > [card] File Uploads
> > > >
> > > > Process sends files stored in Document Plugin or S3 Bucket to external API via POST request. Workflow transmits file path for seamless transfer
> > >
> > > > [card] Document Plugin Integration
> > > >
> > > > Seamless integration with FlowX.AI Document Plugin for process-specific file management and organization
> > >
> > > > [card] S3 Storage Support
> > > >
> > > > Custom S3 bucket storage for files not tied to specific process instances or when Document Plugin is unavailable
> >
> > > [tab] Enhanced Capabilities
> > >
> > > **1. Automated File Exchange**
> > >
> > > Enable seamless file transfer with external systems without manual handling or complex custom integrations
> > >
> > > **2. Flexible Storage Options**
> > >
> > > Choose between Document Plugin for process-specific files or S3 Protocol for independent file operations
> > >
> > > **3. Workflow Integration**
> > >
> > > Files are automatically integrated into workflow processes with proper path management and metadata handling
> > >
> > > **4. External Service Communication**
> > >
> > > Communicate effectively with document services, AI processing systems, report generators, and CMS platforms
> >
> > > [tab] Real-World Use Cases
> > >
> > > > [accordion] Contract Generation Workflows
> > > >
> > > > **Scenario**: Generate personalized contracts using external document services
> > > >
> > > > * **Process Flow**: Send customer data → External contract service → Receive generated PDF contract
> > > > * **Integration**: Customer information flows to document generation API, completed contracts return to process
> > > > * **Storage**: Generated contracts stored in Document Plugin for process tracking and audit trails
> > > > * **Business Value**: Automated contract creation with legal template compliance and version control
> > >
> > > > [accordion] Document Processing & OCR
> > > >
> > > > **Scenario**: Process uploaded documents through external AI/OCR services
> > > >
> > > > * **Process Flow**: Upload document → AI processing service → Receive extracted data and processed files
> > > > * **Integration**: Documents sent to AI services for text extraction, classification, or compliance validation
> > > > * **Storage**: Processed documents and extracted data stored for business logic processing
> > > > * **Business Value**: Automated document processing with intelligent data extraction capabilities
> > >
> > > > [accordion] Report Generation & Analytics
> > > >
> > > > **Scenario**: Generate business reports using external reporting services
> > > >
> > > > * **Process Flow**: Send business data → Reporting service → Receive formatted reports (PDF, Excel)
> > > > * **Integration**: Business metrics and KPIs sent to specialized reporting engines
> > > > * **Storage**: Generated reports available for download and distribution workflows
> > > > * **Business Value**: Professional report generation with advanced formatting and visualization capabilities
> > >
> > > > [accordion] CMS & Content Management
> > > >
> > > > **Scenario**: Integrate with content management systems for file organization
> > > >
> > > > * **Process Flow**: Upload files → CMS integration → Organize and categorize content
> > > > * **Integration**: Files uploaded to external CMS platforms with metadata and categorization
> > > > * **Storage**: S3 Protocol ideal for CMS integrations with unassociated documents
> > > > * **Business Value**: Centralized content management with automated workflow integration
> >
> > [Learn more about Integration Designer](../../../../5.1/docs/platform-deep-dive/integrations/integration-designer)
> >
> > Major Enhancement
>
> ***
>
> ### **Resources Overrides**
>
> > [card] Resources Overrides
> >
> > > [tab] Resources Overrides Overview
> > >
> > > ![Resources Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
> > >
> > > Resources Overrides enable localization and customization of core business applications across multiple regions while maintaining centralized updates from headquarters. This powerful feature allows organizations to adapt specific business logic, compliance requirements, or local regulations without losing connection to the master application.
> >
> > > [tab] Key Features
> > >
> > > > [card] Localization Control
> > > >
> > > > Customize processes, workflows, and enumerations for different countries or regions while maintaining core functionality
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all resource overrides through the Dependencies page with comprehensive override tracking and configuration
> > >
> > > > [card] Selective Overriding
> > > >
> > > > Override only specific resources that need localization while inheriting all other updates from the main library
> > >
> > > > [card] Export/Import Support
> > > >
> > > > Automatically include override configurations in project exports and imports for seamless environment management
> >
> > > [tab] Business Benefits
> > >
> > > **1. Accelerate Global Expansion**
> > >
> > > Deploy core applications to new regions quickly by overriding only country-specific elements instead of rebuilding from scratch
> > >
> > > **2. Maintain Compliance**
> > >
> > > Adapt business logic and data handling to meet local regulatory requirements while preserving global standards
> > >
> > > **3. Preserve Investment**
> > >
> > > Continue receiving updates and improvements from headquarters without losing local customizations
> > >
> > > **4. Reduce Maintenance Overhead**
> > >
> > > Manage regional variations centrally instead of maintaining completely separate application instances
> >
> > > [tab] Supported Resource Types
> > >
> > > > [card] Process Overrides
> > > >
> > > > Customize business process logic while maintaining input/output compatibility and core workflow structure
> > >
> > > > [card] Workflow Overrides
> > > >
> > > > Replace entire workflow implementations to adapt business rules for local requirements
> > >
> > > > [card] Enumeration Overrides
> > > >
> > > > Localize value lists, dropdown options, and classification systems for regional variations
> > >
> > > > [card] Runtime Resolution
> > > >
> > > > Overrides are resolved dynamically at runtime, ensuring the correct regional version is always used
> >
> > > [tab] Real-World Applications
> > >
> > > > [accordion] Multi-National Banking
> > > >
> > > > **Scenario**: Global bank with country-specific loan approval processes
> > > >
> > > > * **Global Library**: Common loan application workflow with standard validation steps
> > > > * **Country Overrides**: Local credit scoring algorithms, regulatory compliance checks, documentation requirements
> > > > * **Business Value**: Single platform maintenance with automated compliance for each country's banking regulations
> > >
> > > > [accordion] Insurance Operations
> > > >
> > > > **Scenario**: Insurance company operating across different regulatory environments
> > > >
> > > > * **Global Library**: Standard claims processing workflow and policy management
> > > > * **Regional Overrides**: Country-specific coverage types, claim validation rules, regulatory reporting
> > > > * **Business Value**: Consistent global operations with local market adaptation and compliance
> > >
> > > > [accordion] Manufacturing & Supply Chain
> > > >
> > > > **Scenario**: Manufacturing company with different operational requirements per region
> > > >
> > > > * **Global Library**: Core production planning and inventory management processes
> > > > * **Local Overrides**: Regional supplier networks, compliance standards, environmental regulations
> > > > * **Business Value**: Standardized operations with flexibility for local business practices and regulations
> >
> > [Learn more about Resources Overrides](../../../../5.1/docs/projects/resources#resources-overrides)
> >
> > Major Enhancement
>
> ***
>
> ### **Active Policy Overrides**
>
> > [card] Active Policy Overrides
> >
> > > [tab] Active Policy Overrides Overview
> > >
> > > ![Active Policy Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap2.png)
> > >
> > > Active Policy Overrides enable user-specific and role-specific deployment policies that allow independent testing of different builds or branches without affecting the global policy. This powerful feature provides granular control over which project versions different users access in runtime environments.
> >
> > > [tab] Key Features
> > >
> > > > [card] User-Specific Policies
> > > >
> > > > Create individual policy overrides for specific users to test different builds independently
> > >
> > > > [card] Role-Based Overrides
> > > >
> > > > Apply policy overrides to entire roles for team-based testing and deployment strategies
> > >
> > > > [card] Priority-Based Resolution
> > > >
> > > > Handle conflicts when multiple overrides apply using configurable priority systems
> > >
> > > > [card] Real-Time Switching
> > > >
> > > > Switch between different project versions instantly without deployment downtime
> >
> > > [tab] Business Benefits
> > >
> > > **1. Independent Testing**
> > >
> > > Enable QA teams and developers to test different builds simultaneously without interfering with production users
> > >
> > > **2. Controlled Rollouts**
> > >
> > > Gradually deploy new features to specific user groups before full production release
> > >
> > > **3. Emergency Rollback**
> > >
> > > Quickly revert specific users to stable versions during incidents without affecting the entire system
> > >
> > > **4. Branch-Specific Development**
> > >
> > > Allow different teams to work with different development branches in shared environments
> >
> > > [tab] Override Management
> > >
> > > > [card] Policy Types
> > > >
> > > > Support for both "Latest on Branch" and specific "Build" policies with flexible branch and version selection
> > >
> > > > [card] Search & Filter
> > > >
> > > > Real-time search functionality to quickly locate specific user or role overrides
> > >
> > > > [card] Activation Control
> > > >
> > > > Enable or disable overrides without deletion for temporary testing scenarios
> > >
> > > > [card] Conflict Resolution
> > > >
> > > > Clear hierarchy: User overrides > Role overrides > Global policy with priority-based resolution
> >
> > > [tab] Real-World Scenarios
> > >
> > > > [accordion] Development Team Testing
> > > >
> > > > **Scenario**: Frontend team needs to test with latest UI changes while backend team tests API updates
> > > >
> > > > * **Override Setup**: Create role-based overrides for "Frontend Developers" and "Backend Developers"
> > > > * **Policy Configuration**: Frontend role uses latest on `ui-redesign` branch, Backend role uses `api-v2` branch
> > > > * **Business Value**: Parallel development with isolated testing environments and no cross-team interference
> > >
> > > > [accordion] Gradual Feature Rollout
> > > >
> > > > **Scenario**: New premium features need testing with select customers before full release
> > > >
> > > > * **Override Setup**: Create user-specific overrides for beta customers and internal stakeholders
> > > > * **Policy Configuration**: Beta users get latest build with premium features, others remain on stable version
> > > > * **Business Value**: Risk mitigation through controlled exposure and real-world testing feedback
> > >
> > > > [accordion] Emergency Response
> > > >
> > > > **Scenario**: Critical bug discovered in production affecting specific user workflows
> > > >
> > > > * **Override Setup**: Create high-priority role override for affected user groups
> > > > * **Policy Configuration**: Temporarily revert affected users to last stable build while others continue normally
> > > > * **Business Value**: Immediate incident response with minimal user impact and service continuity
> >
> > [Learn more about Active Policy Overrides](../../../../5.1/docs/projects/runtime/active-policy)
> >
> > Major Enhancement

> [tab] Persistence
>
> Advanced data management and storage capabilities that enable new architectural patterns and improved data governance.
>
> 🔄 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture) - Logical separation of business contexts with shared infrastructure\
> 🔄 [**FlowX.AI Database**](#flowx-ai-database) - New persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.1.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature

> [tab] Rendering Improvements & UI/UX Enhancements
>
> Enhanced user experience through improved components, better performance, and streamlined interface design.
>
> 🎨 [**Rendering Improvements & UI/UX Enhancements**](#rendering-improvements-&-ui/ux-enhancements) - Enhanced grid components, navigation redesign, advanced form controls, and analytics capabilities\
> 📋 [**Forms in Collections**](#forms-in-collections) - Enhanced support for form elements within collection components, enabling complex data entry scenarios\
> 🔄 [**Multi Select UI Component**](#multi-select-ui-component) - Allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
>
> ### **Rendering Improvements & UI/UX Enhancements**
>
> > [card] Rendering Improvements & UI/UX Enhancements
> >
> > FlowX.AI 5.1.0 delivers comprehensive UI/UX improvements that enhance the user experience across all platform components, from streamlined navigation to advanced form controls and better workflow handling.
> >
> > ## Interface & Navigation Improvements
> >
> > > [card] Enhanced Grid Component
> > >
> > > Improved performance, responsiveness, and customization options for data display and form organization
> >
> > > [card] Navigation Areas Redesign
> > >
> > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> >
> > > [card] Multi Actions Support
> > >
> > > Batch operations support for UI components, enabling simultaneous actions on multiple elements, multi select, multi copy/paste, multi drag and drop, multi delete
> >
> > > [card] [Permission-Based UI Editing](../../../../5.1/docs/building-blocks/ui-designer/ui-designer#permission-based-expressions)
> > >
> > > Granular control over UI element editing based on user permissions with partial editing capabilities, allow multiple executors on swimlane level
> >
> > ## Enhanced Form Controls & Components
> >
> > > [card] [Input Type Code](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-types)
> > >
> > > Specialized input component for code entry
> >
> > > [card] Formatting Options
> > >
> > > Advanced formatting capabilities for Input and Slider components
> >
> > > [card] [Switch Variants](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field#switch-type)
> > >
> > > Enhanced switch component supporting both toggle and checkbox variants
> >
> > > [card] [Disabled Options on Selectors](/5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select#disabled-options)
> > >
> > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > ## User Experience Enhancements
> >
> > > [card] Custom Loader
> > >
> > > Configurable loading indicators for improved user experience during data operations
> >
> > > [card] [Custom Expression Validators](../../../../5.1/docs/building-blocks/ui-designer/validators#custom-validators)
> > >
> > > Advanced validation logic using dynamic computed expressions that can reference other process data values. Write JavaScript expressions that return boolean values for cross-field validation scenarios
> >
> > > [card] File Upload Button Type
> > >
> > > Introduces a specialized button variant for file upload operations, supporting **fill**, **ghost**, and **text** types for flexible UI styling.
> >
> > > [card] Copy Styles
> > >
> > > Efficiently replicate styling across multiple UI components
> >
> > ## Workflow & Analytics Improvements
> >
> > > [card] Analytics Enhancements
> > >
> > > Custom payload support for detailed user interaction tracking and business intelligence
> >
> > > [card] Process End Handling
> > >
> > > Improved user experience when processes complete or terminate
> >
> > > [card] Template Management
> > >
> > > Streamlined template organization by consolidating functionality in Reusable Resources
>
> ***
>
> ### **Forms in Collections**
>
> > [card] Forms in Collections
> >
> > A powerful new feature that enables dynamic, repeatable forms within collection prototypes, eliminating the need for custom development when building forms with repeatable sections like co-debtors, comments, or any list of similar items.
> >
> > <video />
> >
> > ## Key Capabilities
> >
> > > [card] No Custom Development
> > >
> > > Drag Form components directly into Collection Prototypes - they automatically repeat for each item in your data array
> >
> > > [card] Flexible Validation
> > >
> > > Choose between individual item validation or bulk validation across all collection items
> >
> > > [card] Two Saving Scenarios
> > >
> > > Individual save (one item at a time) or bulk save (entire collection) with different validation behaviors
> >
> > ## Common Use Cases Solved
> >
> > **1. Dynamic Forms**
> >
> > Build forms that show different elements based on conditions without custom development
> >
> > **2. Repeatable Sections**
> >
> > Create forms with sections like adding multiple co-debtors, comments, or family members
> >
> > **3. Complex Data Entry**
> >
> > Handle arrays of objects with proper validation and data management
> >
> > **4. Real-time vs Batch Processing**
> >
> > Choose individual saves for real-time editing or bulk saves for form completion workflows
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component

> [tab] AI Platform
>
> New AI capabilities in Integration Designer for processing text, documents, images, and data using AI-powered nodes.
>
> 🤖 [**AI Nodes in Integration Designer**](#ai-nodes-in-integration-designer) - Process text, documents, images, and data using AI-powered workflow nodes
>
> ### **AI Nodes in Integration Designer**
>
> > [card] AI Nodes in Integration Designer
> >
> > > [tab] AI Nodes Overview
> > >
> > > ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
> > >
> > > FlowX.AI 5.1.0 introduces AI-powered nodes in Integration Designer, enabling intelligent processing of text, documents, images, and data within your workflows. These nodes bring AI capabilities directly into your integration flows without requiring external AI services.
> >
> > > [tab] AI Text Operations
> > >
> > > > [card] Text Transformation
> > > >
> > > > Modify text tone, complexity or formatting for better clarity or style
> > >
> > > > [card] Text Understanding
> > > >
> > > > Analyze text to determine sentiment, topics, intent, language and named entities
> > >
> > > > [card] Text Generation
> > > >
> > > > Generate new text such as summaries, completions, translations or paraphrases
> > >
> > > > [card] Text Extraction
> > > >
> > > > Extract structured information, keywords or metadata from text
> >
> > > [tab] AI Document Operations
> > >
> > > > [card] Document Generation
> > > >
> > > > Automatically build reports or complete templates based on given inputs
> > >
> > > > [card] Document Extraction
> > > >
> > > > Identify and extract structured data, entities or metadata from documents
> > >
> > > > [card] Document Understanding
> > > >
> > > > Analyze documents to extract meaning, topics, sentiment, or important information
> > >
> > > > [card] Extract Text from Document
> > > >
> > > > Extract text content from documents (OCR, PDF text extraction)
> >
> > > [tab] AI Image & Data Operations
> > >
> > > **Image Operations:**
> > >
> > > > [card] Image Description
> > > >
> > > > Generate captions or extract detailed information from visual content
> > >
> > > > [card] Image Analysis
> > > >
> > > > Recognize objects, emotions and scenes in images for contextual understanding
> > >
> > > **Data Operations:**
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Add annotations, context or relationships to enhance raw data value
> > >
> > > > [card] Data Generation
> > > >
> > > > Produce synthetic or structured data using templates and logic-based rules
> > >
> > > > [card] Data Transformation
> > > >
> > > > Clean, normalize, aggregate, or restructure datasets into usable formats
> >
> > > [tab] Use Cases
> > >
> > > > [accordion] Intelligent Document Processing
> > > >
> > > > * Extract data from invoices, contracts, and forms
> > > > * Classify documents automatically
> > > > * Validate extracted information against business rules
> > >
> > > > [accordion] Customer Communication Analysis
> > > >
> > > > * Analyze customer feedback sentiment
> > > > * Extract key topics from support tickets
> > > > * Generate personalized responses
> > >
> > > > [accordion] Content Generation
> > > >
> > > > * Create summaries of long documents
> > > > * Translate content to multiple languages
> > > > * Generate reports from structured data
> > >
> > > > [accordion] Data Processing
> > > >
> > > > * Enrich customer data with AI-derived insights
> > > > * Transform unstructured data to structured formats
> > > > * Generate test data for development
> >
> > [Learn more about AI Node Types](../../../../5.1/docs/platform-deep-dive/integrations/ai-nodes)
> >
> > New Feature

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.1](./deployment-guidelines-v5.1)
> >
> > Instructions for deploying FlowX.AI 5.1.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.1/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.1.0


# FlowX.AI 5.1.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.1-november-2025

WCAG 2.1 Level AA compliance achieved, AI Platform enhancements, bug fixes, and quality improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **accessibility compliance**, **AI Platform enhancements**, **customer issue resolution**, and **proactive quality improvements**.
> Upgrades from **5.1.0 → 5.1.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Quality Achievement**: FlowX.AI 5.1.1 demonstrates our commitment to proactive quality improvement:
>
> * **[WCAG 2.1 Level AA compliance](https://www.w3.org/TR/WCAG21/)** achieved across all web components
> * **Proactive quality improvements** identified through internal QA before reaching customers
> * **Customer issues** resolved with full business context
> * **Zero breaking changes** - fully compatible upgrade from 5.1.0
>
> This release represents months of accessibility audits, automated testing, and quality assurance work to deliver exceptional software quality.

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.1 delivers comprehensive improvements across accessibility, stability, and platform reliability.
>
> ♿  [**WCAG 2.1 Compliance Achieved**](#wcag-2-1-compliance) - Full accessibility support across all web components\
> 🌍 [**Task Management Localization**](#task-management-localization) — Comprehensive multi-language support with 51 substitution tags\
> 🤖 [**AI Platform Enhancements**](#ai-platform-enhancements) — Multi-agent system improvements and AI workflow stability\
> 🎯 [**Customer Fixes**](#customer-fixes) — Critical issues resolved based on customer feedback\
> ✨ [**Proactive Improvements**](#proactive-quality-improvements) — Issues identified through internal QA before reaching customers\
> 🔧 [**Platform Enhancements**](#platform-enhancements) — SSE handling, audit logs, and infrastructure improvements
>
> ### **WCAG 2.1 compliance**
>
> > [card] WCAG 2.1 compliance
> >
> > > [tab] Overview
> > >
> > > **FlowX.AI is now WCAG 2.1 Level AA compliant**
> > >
> > > This release delivers full accessibility support through **28 comprehensive improvements** across Angular and React SDKs, making FlowX applications usable by everyone, including users with disabilities.
> > >
> > > ### Business value
> > >
> > > > [card] Government Compliance
> > > >
> > > > Meet accessibility requirements for government and public sector applications
> > >
> > > > [card] Healthcare Standards
> > > >
> > > > Comply with healthcare industry accessibility regulations and standards
> > >
> > > > [card] Financial Services
> > > >
> > > > Satisfy financial sector requirements for inclusive digital experiences
> > >
> > > > [card] Universal UX
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those with disabilities
> > >
> > > ### What changed
> > >
> > > * All components now fully keyboard-accessible
> > > * Complete screen reader support with ARIA labels
> > > * Proper focus management across all interactions
> > > * Accessible error announcements and validation
> > > * Semantic HTML structure throughout
> >
> > > [tab] Key features
> > >
> > > > [card] Auto-bindable ARIA Tags
> > > >
> > > > Automatically bind accessibility labels, descriptions, and ARIA attributes to all UI components from Designer configuration
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Full keyboard navigation support with proper focus management, tab order, and keyboard shortcuts in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > ARIA labels, descriptions, and live regions implemented across all form elements and interactive components
> > >
> > > > [card] UI Designer Integration
> > > >
> > > > Dedicated accessibility configuration section in UI Designer for managing labels and descriptions
> >
> > > [tab] Supported components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio/Segmented buttons, Slider, and File upload with labels, descriptions, and error announcements
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card with keyboard navigation, focus management, and state announcements
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with semantic HTML structure and proper labeling
> > >
> > > **4. Platform Support**
> > >
> > > Complete implementation for Angular and React SDKs (iOS and Android in future releases)
> >
> > > [tab] Implementation details
> > >
> > > **28 Improvements Delivered:**
> > >
> > > > [accordion] Angular SDK
> > > >
> > > > * Custom keyboard navigation implementation
> > > > * Focus management for Select/Multiselect components
> > > > * Modal focus trap and restoration
> > > > * Shift+Tab handling across form elements
> > > > * Listbox keyboard operations
> > > > * Table navigation improvements
> > > > * Switch and checkbox accessibility
> > > > * File preview focus indicators
> > > > * Button Space key activation
> > > > * Link focus outlines
> > > > * Disabled element keyboard behavior
> > >
> > > > [accordion] React SDK
> > > >
> > > > * BaseUI Combobox implementation for Select/Multiselect
> > > > * Keyboard navigation with clear buttons
> > > > * Focus restoration after interactions
> > > > * Outline theming for focus indicators
> > > > * Modal auto-focus on open
> > > > * Card accordion keyboard handling
> > > > * Table row navigation
> > > > * Option highlighting in dropdowns
> > >
> > > > [accordion] UI Designer
> > > >
> > > > * Accessibility configuration panel
> > > > * Auto-bindable tags for all components
> > > > * Label and description fields
> > > > * Alt text management for images
> > > > * ARIA attribute configuration
> > > > * Accessibility section styling
> > > > * Component-specific accessibility settings
> > >
> > > > [accordion] Technical tasks completed
> > > >
> > > > * Implemented BaseUI Combobox for Select/Multiselect
> > > > * Custom keyboard navigation for Angular
> > > > * React SDK keyboard navigation with clear button
> > > > * Auto-bindable accessibility tags for all components
> > > > * Accessibility configuration panel in UI Designer
> > > > * Removed conflicting title attribute tooltips
> > > > * Aligned Stepper accessibility between frameworks
> > > > * Bind labels and descriptions to form fields
> >
> > [Learn more about Accessibility Configuration](/5.1/docs/platform-deep-dive/accessibility)
> >
> > Major Achievement
>
> ***
>
> ### **Customer fixes**
>
> > [card] Customer fixes
> >
> > We prioritized and resolved **customer-reported issues** in this release, addressing critical functionality issues and workflow inefficiencies reported via Zendesk.
> >
> > > [accordion] Action parameters lost on copy/paste
> > >
> > > **Problem:**\
> > > When copying nodes with Kafka send actions, topic and message configurations were not preserved, forcing users to manually reconfigure all action parameters after paste operations.
> > >
> > > **Customer Impact:**
> > >
> > > * Development velocity significantly reduced
> > > * Risk of configuration errors during manual re-entry
> > > * Frustration with repetitive configuration work
> > >
> > > **Resolution:**\
> > > actionParamsMap now properly persists through copy/paste operations
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create send message node with Kafka action
> > > 2. Configure topic and message parameters
> > > 3. Copy and paste the node
> > > 4. All configurations now preserved correctly
> > >
> > > **Customer Benefit:**\
> > > Faster workflow development with reduced configuration errors and improved developer experience.
> >
> > > [accordion] Orphaned warnings block process deployments
> > >
> > > **Problem:**\
> > > When deleting parent actions that had child actions with warnings, the warnings remained in the system as orphans. These orphaned warnings prevented process export/import operations and blocked build deployments.
> > >
> > > **Customer Impact:**
> > >
> > > * Build pipelines blocked by stale warnings
> > > * Deployment delays requiring manual database cleanup
> > > * Process export/import operations failed
> > > * Development and testing workflows disrupted
> > >
> > > **Resolution:**\
> > > Warnings now cascade-delete automatically when parent actions are removed
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create action with subactions containing warnings
> > > 2. Delete the parent action
> > > 3. All child warnings now properly cleaned up
> > >
> > > **Customer Benefit:**\
> > > Clean deployments without manual intervention, faster development cycles, no more blocked pipelines.
> >
> > > [accordion] Default application cannot be removed
> > >
> > > **Problem:**\
> > > Auto-generated `default_application` in new environments existed only in app\_manager schema and could not be deleted through standard operations, returning validation errors.
> > >
> > > **Customer Impact:**
> > >
> > > * Environment cleanup difficulties
> > > * Testing complications with unwanted default projects
> > > * Confusion about application lifecycle management
> > >
> > > **Resolution:**\
> > > Added proper runtime validation for application deletion operations
> > >
> > > **Error (Fixed):**
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": 400,
> > >   "message": "error.validation.runtime.application.not_found",
> > >   "title": "Runtime project not found."
> > > }
> > > ```
> > >
> > > **Customer Benefit:**\
> > > Clean environment management with predictable application lifecycle operations.
>
> ***
>
> ### **Proactive quality improvements**
>
> > [card] Proactive quality improvements
> >
> > > [tab] Overview
> > >
> > > **Issues identified and resolved proactively**:
> > >
> > > ### Quality process
> > >
> > > > [card] Accessibility Audits
> > > >
> > > > WCAG 2.1 compliance testing identified keyboard navigation and focus management improvements
> > >
> > > > [card] Automated Testing
> > > >
> > > > Continuous integration pipelines caught component behavior issues and rendering problems
> > >
> > > > [card] Internal QA
> > > >
> > > > Manual testing uncovered edge cases in form interactions and modal behaviors
> > >
> > > > [card] Code Reviews
> > > >
> > > > Peer reviews identified potential stability issues in backend processing and dependency management
> > >
> > > ### Distribution by category
> > >
> > > * **Keyboard Navigation**: Fixes across Angular and React
> > > * **Focus Management**: Fixes for modals, forms, and interactive elements
> > > * **Component Behavior**: Fixes for proper state handling and rendering
> > > * **Backend Stability**: Fixes for processing and dependency management
> >
> > > [tab] Angular SDK
> > >
> > > > [accordion] Keyboard navigation improvements
> > > >
> > > > * Fixed listbox remaining open when pressing Shift+Tab
> > > > * Fixed Shift+Tab not working on Select with search
> > > > * Fixed Multiselect tab navigation moving to first element instead of next
> > > > * Fixed Select input focus not working properly
> > > > * Fixed Select list not scrolling during keyboard navigation
> > > > * Fixed up/down arrow scrolling screen alongside option list
> > > > * Fixed focus lost after loading new user task
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed Link in message focus missing outline
> > > > * Fixed modal close button not focused automatically
> > > > * Fixed file preview focus not highlighted and lost
> > > > * Fixed button inside modal not working with Space key
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Multiselect options list not opening
> > > > * Fixed MultiSelect and link focusable when disabled
> > > > * Fixed modal dismiss buttons not working with Space key
> > > > * Fixed modal without close button not easily focusable
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Space pressed on card with accordion scrolling page
> > > > * Fixed Switch with label position start focus issues
> >
> > > [tab] React SDK
> > >
> > > > [accordion] Keyboard Navigation Improvements
> > > >
> > > > * Fixed outline from theme not applied to modal close button and links
> > > > * Fixed Select selected option not highlighted in options list
> > > > * Fixed Select search not filtering after selection
> > > > * Fixed Input/textarea/select focus lost after using clear button
> > > > * Fixed Tab focus moving inside collapsed card
> > > > * Fixed table Tab navigation skipping rows
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed file preview retry focus not highlighted and lost
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Select and link focusable when disabled
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Datepicker clear icon focus not highlighted
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed doc preview modal not closable with Enter or Space
> > > > * Fixed button inside table focus not highlighted
> > > > * Fixed Slider decimal numbers not rendered correctly
> > > > * Fixed Substepper not rendered correctly
> > > > * Fixed doc preview display mode showing inline
> > > > * Fixed cards expandable before token reaches them
> >
> > > [tab] Designer & Backend
> > >
> > > > [accordion] UI Designer Improvements
> > > >
> > > > * Fixed missing accessibility section on Link component
> > > > * Fixed missing accessibility section on Image button
> > > > * Fixed missing space in accessibility label and info icon
> > > > * Fixed Alt text field disabled styling not applied
> > > > * Fixed console errors when changing pages from header
> > > > * Fixed Select/multiselect highlighted in preview and settings tabs
> > > > * Fixed outline theming in enumerations and inputs
> > > > * Fixed Workflows info points content not rendered correctly
> > > > * Fixed Workflows tabs content not showing properly
> > > > * Fixed padding missing on RUT UI Assets panel
> > >
> > > > [accordion] Backend Stability Improvements
> > > >
> > > > * Fixed wrong navigationTree response on overridden process
> > > > * Fixed incorrect navigationTree for resource override details
> > > > * Fixed error when trying to update dependency lib versions
> > > > * Fixed error returned when updating dependency with override
> > > > * Fixed no response on out topic for start process by name from Kafka
> > > > * Fixed checkbox "Allow back to this action" status not loaded
> > > > * Fixed empty screen when logging in without workspace access
> > > > * Fixed Elasticsearch scheduled task errors with failed documents
> > > > * Fixed services not logging when Liquibase crashing due to lock
> >
> > Proactive Quality
>
> ***
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 adds comprehensive localization support for Task Management, enabling multi-language task management interfaces through 51 system substitution tags. Table grid localization is automatic.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > >
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> > >
> > > > [!NOTE]
> > > >
> > > > This feature enables complete Task Management localization for global deployments, meeting requirements for government, healthcare, and financial services applications requiring multi-language support.
> >
> > > [tab] Key features
> > >
> > > > [card] FlowX Substitution Tags (51 Keys)
> > > >
> > > > Complete set of substitution tags for task actions, statuses, history events, and UI elements
> > >
> > > > [card] Table Grid Localization
> > > >
> > > > Table grid localizes automatically based on container app language; FlowX tags configured manually in CMS
> > >
> > > > [card] Web Renderer Integration
> > > >
> > > > Angular and React renderers use system substitution tags on all task management texts
> >
> > > [tab] What's localized
> > >
> > > **FlowX Substitution Tags (51 Keys):**
> > >
> > > * Table columns (title, stage, assignee, status, priority, last updated)
> > > * Process states (created, started, finished, failed, expired, etc.)
> > > * Task actions (assign, unassign, hold, unhold, execute, start)
> > > * Bulk operations (assign to, unassign all, hold all, etc.)
> > > * History events (task created, assigned, status changed, etc.)
> > > * User selection dialogs and UI states
> > >
> > > **Table Grid Localization**:
> > >
> > > * Filters (set, text, number, date with all operators)
> > > * Menus (column, context, aggregation, sorting)
> > > * Pagination (navigation, page size, row counts)
> > > * Data types (boolean, dates, numbers with formatting)
> > > * ARIA labels for accessibility
> >
> > > [tab] Implementation details
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization based on this setting
> > >
> > > **2. Configure CMS Tags**
> > >
> > > Add translations for all 51 sys\_tm\_\* tags in CMS for each supported language - this is the only manual configuration needed
> > >
> > > **3. Use in Renderers**
> > >
> > > Web renderers automatically apply system substitution tags to all task management UI elements
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> ***
>
> ### **AI Platform enhancements**
>
> > [card] AI Platform enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 delivers significant improvements to the AI Platform, enhancing multi-agent collaboration, conversation management, and AI workflow stability. These enhancements ensure more reliable AI-assisted development workflows and better user experience.
> > >
> > > > [card] Multi-Agent System
> > > >
> > > > Enhanced agent communication and thread management for improved collaborative AI workflows
> > >
> > > > [card] Conversation Stability
> > > >
> > > > Improved conversation handling with better error propagation and session management
> > >
> > > > [card] AI Developer Tools
> > > >
> > > > Enhanced AI Developer capabilities with proper data model integration and expression generation
> > >
> > > > [card] Document Intelligence
> > > >
> > > > Multi-page document generation support and improved content handling
> >
> > > [tab] Key improvements
> > >
> > > **Multi-Agent Conversation Management:**
> > >
> > > * Enhanced conversation thread handling with proper parent action status updates
> > > * Improved backend support for adding new messages on agent threads
> > > * Better session management with new session button in Command Center
> > > * Context switching prevention during execution plan generation
> > >
> > > **AI Developer Enhancements:**
> > >
> > > * Fixed data model integration for expressions and business rules generation
> > > * Improved action target saving and destination setting
> > > * Enhanced execution plan editing from user prompts
> > > * Better handling of empty execution plans
> > >
> > > **Error Handling & Stability:**
> > >
> > > * Graceful error propagation from internal AI agent operations
> > > * Improved CORS headers for document object downloads
> > > * Enhanced telemetry support for debugging and monitoring
> > > * Better handling of plan enhancement patches
> > >
> > > **Document & Content Features:**
> > >
> > > * Multi-page document generation support in AI nodes
> > > * Source selector component for image and document inputs
> > > * Improved messaging system for AI agents in command center
> > > * Enhanced UI feedback for AI-generated resources
> >
> > > [tab] Technical improvements
> > >
> > > **Backend Enhancements:**
> > >
> > > * Continuous patching support for action contexts during execution
> > > * Improved navigation tree responses for overridden processes
> > > * Enhanced dependency management for library overrides
> > > * Better error handling and logging across AI services
> > >
> > > **Frontend Improvements:**
> > >
> > > * Fixed target selector closing behavior in implementation threads
> > > * Improved preview mode handling after developer changes
> > > * Enhanced command center messaging and error display
> > > * Better UI state management for AI workflow interactions
> > >
> > > **Integration Updates:**
> > >
> > > * CORS headers properly configured for GraphQL object downloads
> > > * Process task destinations automatically set to current process
> > > * Improved integration between AI agents and execution plans
> > > * Enhanced audit logging for resource overrides
> >
> > AI Platform
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform enhancements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] SSE Disconnect Handling
> > > >
> > > > Improved Server-Sent Events disconnect handling to reduce error log flooding when clients disconnect
> > >
> > > > [card] Resource Overrides Audit
> > > >
> > > > Implemented audit logs for library resource overrides to track configuration changes
> > >
> > > > [card] Security Updates
> > > >
> > > > Fixed high vulnerabilities in Designer 5.1.x and main branch
> >
> > > [tab] Renderer Enhancements
> > >
> > > > [card] System Substitution Tags
> > > >
> > > > Web renderers now use system substitution tags on all task management texts
> > >
> > > > [card] Outline Theming
> > > >
> > > > Enhanced outline and select/multiselect option highlight theming for visual consistency
> >
> > > [tab] Technical Improvements
> > >
> > > **Code Quality:**
> > >
> > > * Eliminated deprecated code for Kafka start process
> > > * Improved error handling for Elasticsearch document updates
> > > * Enhanced dependency management for library overrides
> > > * Better logging and error reporting across services
> > >
> > > **Performance:**
> > >
> > > * Optimized SSE connection handling
> > > * Improved query performance for navigation tree
> > > * Better resource management in long-running processes
> >
> > Platform Updates

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.1 is fully compatible with 5.1.0. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.0 → 5.1.1 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Android and iOS accessibility properties implementation
> > * Additional Select component refinements
> > * UI Designer padding optimizations
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and critical bug fixes
> * Accessibility enhancements for mobile platforms
> * Performance optimizations
>
> Major new features are planned for future releases in the 5.x series. See the [5.2.0 release notes](../v5.2.0-november-2025/v5.2.0-november-2025) for upcoming capabilities.


# FlowX.AI 5.1.10 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.10-june-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.9 → 5.1.10** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.10 includes bug fixes and security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Active policy and iOS renderer fixes
> * Real-time event delivery stability improvement (Events Gateway)
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.9

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Reusable UI templates:** fixed several issues affecting reusable UI templates: actions remaining mapped after changing dependency versions, undo/redo leaving an action without a name or unable to save, data-slice and mapping requests returning 400 after a data-model key was renamed, duplicate entries returned for available templates, the "open in new tab" flag not being saved on UI action mappings, actions going missing when the same template is nested at multiple container levels, and conditional styling and validators being applied incorrectly when the same template is used more than once in a single user task.
> > > >
> > > > * **Active policy:** fixed an issue where the user list could appear empty on the override active-policy form.
> > > >
> > > > * **Project version merge:** fixed a 500 error that could occur when merging app versions.&#x20;
> > > >
> > > > * **Organization settings:** fixed the runtime users list failing to load.&#x20;
> > > >
> > > > - **Real-time event delivery:** improved Redis connection stability under sustained load. The Events Gateway now uses polling as the default mode for reading real-time events from Redis, preventing the gradual connection buildup that could previously require periodic Events Gateway restarts. The change applies automatically on upgrade; no configuration is required.
> > > > - **Renderer:** accordion card height and custom styles now follow the component's opened state, and gap spacing is applied correctly to collections.
> > > > - **Process instances:** fixed duplicate API calls and rendering errors when navigating between process instances.
> > > > - **iOS renderer:** broad VoiceOver and accessibility improvements across components (form fields, file preview, sliders, date picker, validation messages), and fixed form view-model lookup for forms nested in collections.
> > > > - **Android renderer:** component sizing now includes padding on text, link, markdown, and image components; fixed a TopAppBar crash in some configurations, tooltip icon overrides, slider step rounding, document preview caching, and resilience to process death.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.10 is fully compatible with 5.1.9. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.9 → 5.1.10 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.10](./deployment-guidelines-v5.1.10).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.11 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.11-july-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.10 → 5.1.11** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.11 includes bug fixes and security patches:
>
> * Audit log and task management fixes
> * Project creation error-handling fix
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.10

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Audit log:** filtering by user now returns results when a user's username differs from their email address.
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it.
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.11 is fully compatible with 5.1.10. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.10 → 5.1.11 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.11](./deployment-guidelines-v5.1.11).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.12 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.12-august-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.11 → 5.1.12** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.12 includes bug fixes for library resources and task management:
>
> * Library process resource overview fixes
> * Task management sort control fix
> * No breaking changes; fully compatible upgrade from 5.1.11

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes for library resource overview and task management
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.12 is fully compatible with 5.1.11. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.11 → 5.1.12 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.12](./deployment-guidelines-v5.1.12).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.13 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.13-september-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **security patches**. Upgrades from **5.1.12 → 5.1.13** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.13 includes reliability fixes for process advancing, a process designer fix, and security patches:
>
> * Process advancing fixes that prevent lost or stalled process advances under load
> * Action deletion fix for business rules that call reusable functions
> * Security patches and dependency upgrades across platform components
> * No breaking changes; fully compatible upgrade from 5.1.12

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and security patches across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Process advancing reliability fixes, a process designer fix, and security patches
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Process advancing:** the partition cleanup job no longer deletes advance events that are accepted while cleanup is running. Event insertion and cleanup now coordinate through database row locks, on both PostgreSQL and Oracle, so a process advance can no longer be lost to a concurrent cleanup.&#x20;
> > > > * **Process advancing:** advancing workers no longer pause for cooldown while work is still queued, and event completion is retried after a database deadlock instead of leaving an already-processed event marked as in progress.&#x20;
> > > > * **Process designer:** deleting an action no longer fails with a server error when one of its business rules calls a reusable function.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components. The Java runtime base images move to Eclipse Temurin 21.0.12 with a refreshed OS package layer.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.13 is fully compatible with 5.1.12. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.12 → 5.1.13 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.13](./deployment-guidelines-v5.1.13).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.2-december-2025

Bug fixes, stability improvements, and quality enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes**, **stability improvements**, and **quality enhancements**.
> Upgrades from **5.1.1 → 5.1.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.2 provides continued quality, stability, and reliability for the platform:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * New features and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.2 delivers maintenance improvements focused on stability, reliability, and feature enhancements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — issues resolved including customer-reported and proactive fixes\
> ✨ [**New Features**](#new-features) — enhancements including new features and platform improvements\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure and stability enhancements
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Authorization service configuration
> > > >
> > > > **Problem:**\
> > > > Wrong service account client secret config parameter was used in Authorization service, causing authentication failures.
> > > >
> > > > **Resolution:**\
> > > > Fixed configu gration parameter mapping for service account client secret in Authorization service
> > >
> > > > [accordion] Token state changes on back navigation
> > > >
> > > > **Problem:**\
> > > > When performing back in steps actions, tokens incorrectly changed from Aborted to Active state when lazy actions finished.
> > > >
> > > > **Resolution:**\
> > > > Fixed token state management during back navigation to preserve correct state
> > >
> > > > [accordion] Action parameters not copied on node copy
> > > >
> > > > **Problem:**\
> > > > When copying nodes with child actions, action parameters (like Kafka topic and message configurations) were not preserved.
> > > >
> > > > **Resolution:**\
> > > > Fixed actionParamsMap persistence through copy/paste operations
> > >
> > > > [accordion] Permissions updated incorrectly during action execution
> > > >
> > > > **Problem:**\
> > > > hideRules and disableRules values were incorrectly updated in database when executing actions, causing permission issues.
> > > >
> > > > **Resolution:**\
> > > > Fixed permission rule handling during action execution
> > >
> > > > [accordion] Subprocess data mapping issues
> > > >
> > > > **Problem:**\
> > > > Starting subprocess with legacy mapping caused data to be incorrectly appended instead of replaced.
> > > >
> > > > **Resolution:**\
> > > > Fixed data mapping behavior for subprocess start actions
> > >
> > > > [accordion] Forms in collections - action not found
> > > >
> > > > **Problem:**\
> > > > When saving data from outside collection with forms to submit, actions were not found correctly.
> > > >
> > > > **Resolution:**\
> > > > Fixed action resolution for forms inside collections
> >
> > > [tab] AI Platform fixes
> > >
> > > > [accordion] AI Designer improvements
> > > >
> > > > * Fixed no feedback when uploading large documents in command center
> > > > * Fixed targets for business rules never being set by planner
> > > > * Fixed file upload limit lower than 3MB
> > > > * Fixed missing messages on Keep/Discard buttons for UI and BR
> > > > * Fixed Save & Close button not working in Data Model modal
> > > > * Fixed DM keys not created after keeping UI
> > > > * Fixed table key appearing as mapped when Data Model is empty
> > > > * Fixed pip window being clipped
> > > > * Fixed Submit prompt button color not indicating active state
> > > > * Fixed source not indicating uploaded document for some Plan actions
> > > > * Fixed UI outcome duplication until connected-graph keep method finishes
> > > > * Fixed missing scrollbar in Context Documents modal with multiple subprocesses
> > > > * Fixed command center not reopenable after closing in developer preview mode
> > > > * Fixed planner sample data import crashes
> > > > * Fixed business logic targets not correctly stored in execution plan
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Web renderer improvements
> > > >
> > > > * Fixed hide subprocess navigation closing parent navigation with multiple hierarchies
> > > > * Fixed card collapsing when next nav area is modal (Angular & React)
> > > > * Fixed card not expandable after finishing subprocess started from it (Angular & React)
> > > > * Fixed loader missing or not fully shown in React
> > > > * Fixed message icon and text rendered on different rows when width fill in React
> > > > * Fixed collection prototype shown when collection source array doesn't exist in React
> > > > * Fixed broken image rendered when missing url or base64 image in React
> > > > * Fixed switch component knob and container alignment in React
> > > > * Fixed multi select search not filtering available options in React SDK
> > > > * Fixed custom component keys duplicated in action body (React & Angular)
> > >
> > > > [accordion] Task Manager fixes
> > > >
> > > > * Fixed Task Manager theming not applied in Angular
> > > > * Fixed Task Manager header theming not applied in React
> > > > * Fixed assignee dropdown list and placeholder not displayed in React
> > >
> > > > [accordion] Reusable templates fixes
> > > >
> > > > * Fixed custom body being null at runtime for Reusable templates actions
> >
> > > [tab] Platform & Data fixes
> > >
> > > > [accordion] Data model and mappers
> > > >
> > > > * Fixed input/output parameters not deleted after updating parameters
> > > > * Fixed Go to reference button redirecting incorrectly
> > > > * Fixed parameters items deleted when updating Project Data Model object
> > >
> > > > [accordion] Process Designer
> > > >
> > > > * Fixed retry token button available for inactive tokens
> > > > * Fixed missing save action button when opening action config from UI designer
> > >
> > > > [accordion] Platform stability
> > > >
> > > > * Fixed advancing errors in partition event table
>
> ***
>
> ### **New features**
>
> > [card] New features
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation
> > > >
> > > > Generate Data Model for tables and table columns from AI Designer
> >
> > > [tab] Renderers
> > >
> > > > [card] Android Accessibility
> > > >
> > > > Accessibility properties from UI Designer now supported in Android renderer
> > >
> > > > [card] Substitution Tags in Selectors
> > > >
> > > > Selectors (checkbox, radio, select, multiselect) now support substitution tags when source type is process data across Angular, React, and iOS renderers
> > >
> > > > [card] Template Caching
> > > >
> > > > Improved caching for reusable templates at runtime
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Dgraph Upgrade
> > > >
> > > > Bring dgraph to flowx-release
> >
> > > [tab] Performance & Optimization
> > >
> > > > [card] Designer Static Assets
> > > >
> > > > Make designer nginx use compression & caching for static assets

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.2 is fully compatible with 5.1.1. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.1 → 5.1.2 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.2](./deployment-guidelines-v5.1.2).
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Task Manager theming issues in Angular and React
> > * Task Manager assignee dropdown display issues in React
> > * Custom component key duplication in action body
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.3-january-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.2 → 5.1.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.3 delivers security patches and significant performance improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.2

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.3 delivers comprehensive security, performance, and stability improvements across the platform.
>
> ♿ [**iOS Accessibility**](#improvements-and-enhancements) — VoiceOver accessibility support for iOS renderer\
> ✨ [**Improvements and enhancements**](#improvements-and-enhancements) — AI Platform improvements and enhancements for Data Model generation\
> ⚡ [**Performance Improvements**](#performance-improvements) — Performance improvements and optimizations across platform components and services\
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Improvements and enhancements**
>
> > [card] Improvements and enhancements
> >
> > > [tab] Renderers
> > >
> > > > [card] iOS Accessibility
> > > >
> > > > VoiceOver accessibility support for the iOS renderer. Accessibility properties configured in the UI Designer (labels, hints, traits, decorative flags) are now applied to iOS components including form elements, text, images, and links.
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation for Tables
> > > >
> > > > Generate Data Model mappings for table components from AI Designer. AI automatically creates array of objects DM keys for tables with type validation and visual feedback.
> > >
> > > > [card] Data Model Generation for Table Columns
> > > >
> > > > Extended DM generation for text and link elements within table columns, with automatic attribute mapping and support for partial matching.
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.3 delivers significant performance improvements to the process engine
> > >
> > > > [card] Optimized Writes
> > > >
> > > > Smart change detection skips unnecessary database writes when param\_values unchanged
> > >
> > > > [card] Reduced DB Calls
> > > >
> > > > N+1 query fixes and batch loading significantly reduce database round trips
> > >
> > > > [card] Request Caching
> > > >
> > > > Request-scoped caching for frequently accessed runtime configuration
> >
> > > [tab] Key optimizations
> > >
> > > > [accordion] ProcessInstance param\_values Optimization
> > > >
> > > > Optimized handling of large `param_values` to reduce network overhead and prevent optimistic locking conflicts:
> > > >
> > > > * **Change Detection**: Skip database writes when param\_values unchanged
> > > > * **Lightweight Queries**: Exclude param\_values from SELECT when not needed
> > >
> > > > [accordion] Runtime Improvements - Reduced DB Calls
> > > >
> > > > **Optimizations Implemented:**
> > > >
> > > > * Improved batch loading and caching to reduce redundant queries
> > > > * Streamlined process initiation
> > > > * Enhanced batching for database writes
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Task Manager View Not Updating
> > > >
> > > > **Problem:**\
> > > > When using a view with dataset config where assignee is set to blank, after assigning a task (or self-assigning), the view appeared unchanged. Similarly, when assignee is set to not blank and you unassign a task, the view did not update.
> > > >
> > > > **Resolution:**\
> > > > Fixed view refresh behavior after assign/unassign operations to properly reflect the updated task state and provide visual feedback to users.
> > >
> > > > [accordion] Forms in Collections - Backend Keys Calculation
> > > >
> > > > **Problem:**\
> > > > When saving data from outside a collection with forms to submit, the backend calculated keys for UUID entries in formsToSubmit. These keys were only partial (relative to the collection array) and could overwrite existing process values.
> > > >
> > > > **Resolution:**\
> > > > Added a flag on PATCH /actions requests to notify the backend to exclude backend keys calculation for forms in collections UUIDs from formsToSubmit.
> > >
> > > > [accordion] Variables Reset on Config Update
> > > >
> > > > **Problem:**\
> > > > Updating parameters in the config page caused existing parameters to be replaced with new ones, generating new flowxUuids. This caused variables in database nodes to no longer match, losing all references.
> > > >
> > > > **Resolution:**\
> > > > Fixed to always send id and flowxUuid for existing params when saving the operation, preserving variable references.
> > >
> > > > [accordion] Build Export Timeout
> > > >
> > > > **Problem:**\
> > > > When exporting builds with multiple resources, some resources remained in EXPORTING status, others got EXPORT\_TIMEOUT without the build export receiving the status, and others had EXPORTED status. This was caused by Kafka messages being processed before the MongoDB transaction was committed.
> > > >
> > > > **Resolution:**\
> > > > Fixed the export function to ensure proper sequencing of database transactions and Kafka messages during build export operations.
> >
> > > [tab] Designer fixes
> > >
> > > > [accordion] Table Row Deletable with Backspace in RUT
> > > >
> > > > **Problem:**\
> > > > In Reusable UI Templates, selecting a table row and pressing backspace would delete the row, even though table rows should not be deletable.
> > > >
> > > > **Resolution:**\
> > > > Fixed keyboard handling to prevent accidental table row deletion via backspace key.
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Android Upload Action Payload Missing
> > > >
> > > > **Problem:**\
> > > > Upload action payload data (except uploadFileTempFileId) was missing on execution in the Android renderer.
> > > >
> > > > **Resolution:**\
> > > > Fixed payload handling to include all required data in upload action execution.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Connector Topic Pattern
> > > >
> > > > Added dedicated KAFKA\_TOPIC\_CONNECTOR\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [tab] AI Platform
> > >
> > > > [card] Streaming Client Library
> > > >
> > > > Implemented client library for invoking the run AI node with streaming support for conversational API

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.3 is fully compatible with 5.1.2. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.2 → 5.1.3 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### New configuration options
>
> > [!NOTE]
> >
> > **Optional**: New environment variable available for process-engine
>
> | Variable | Description | Default |
> | - | - | - |
> | `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from other platform components | Falls back to `KAFKA_TOPIC_PATTERN` if not set |
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.3](./deployment-guidelines-v5.1.3).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.3 → 5.1.4** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.4 delivers security patches and stability improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.3

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.4 delivers comprehensive security, performance, and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components and stability improvements\
> ⚡ [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Form validators do not work inside collection prototypes
> > > >
> > > > **Summary:**
> > > >
> > > > Validators applied to forms within collection prototypes are not triggered as expected.
> > >
> > > > [accordion] Project editor could modify access permissions
> > > >
> > > > **Summary:**
> > > >
> > > > Project editors were incorrectly able to modify project access permissions and delete projects. This has been fixed: `project_editor` can no longer modify access management or delete projects/libraries. Only `project_owner` and `workspace_admin` can change project ownership, add/remove users and groups from projects/libraries, and delete projects/libraries.
> > >
> > > > [accordion] Subprocess UI still shown after subprocess is finished
> > > >
> > > > **Summary:**
> > > >
> > > > In processes with multiple subprocesses that have UI, the first subprocess UI remained visible after completion until the next user task details were received. The UI now correctly clears when a subprocess finishes.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Kafka environment variables alignment
> > > >
> > > > Kafka environment variables are now consistent across all services with backwards compatibility support for existing configurations.
> > >
> > > > [card] Config params cache improvements
> > > >
> > > > New environment variables for tuning config params cache: `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` and `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`. See [Engine Setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
> > >
> > > > [card] Project editor permissions update
> > > >
> > > > `project_editor` can no longer delete projects or modify access permissions. `projects_admin` permission now grants full project management capabilities. See [Roles Permissions Matrix](/5.1/setup-guides/access-management/roles-permissions-matrix).
> > >
> > > > [card] Advancing partition counter fix
> > > >
> > > > Fixed an issue where the advancing partition counter could go negative, causing event processing failures. Improves reliability in integration-designer and process-engine.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.4 is fully compatible with 5.1.3. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.3 → 5.1.4 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.4](./deployment-guidelines-v5.1.4).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.5-february-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.4 → 5.1.5** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.5 delivers bug fixes and stability improvements:
>
> * Fixes for process loop rendering issues in the Angular renderer
> * Fix for subprocess output data not being returned from embedded processes
> * No breaking changes — fully compatible upgrade from 5.1.4

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.5 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer and process engine fixes for process loop scenarios
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes
> > >
> > > Issues resolved in the Angular renderer:
> > >
> > > > [accordion] Validation shown without user interaction on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task for the second time, form validation errors were displayed immediately without any user interaction. Validation now correctly waits for user input before showing errors.
> > >
> > > > [accordion] Action executed continuously on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task that had a UI action configured on a form element, the action was executed continuously in a loop. Actions are now correctly triggered only on user interaction.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Subprocess not returning output from embedded process
> > > >
> > > > **Summary:**
> > > >
> > > > When a subprocess (call activity) was started from an embedded process, the output data was not passed back to the parent process instance after completion. Data mapping from subprocess to parent now works correctly in embedded process scenarios.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.5 is fully compatible with 5.1.4. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.4 → 5.1.5 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.5](./deployment-guidelines-v5.1.5).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026

Bug fixes, stability improvements, and platform enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.5 → 5.1.6** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.6 delivers bug fixes and stability improvements:
>
> * Multiple React and Angular renderer fixes for modals, sliders, buttons, and accessibility
> * Data mappers autocomplete fix for values not loading
> * Process engine fix for advancing getting stuck on pod crash with multiple partition events
> * Kafka health check fix for reporting UP despite consumer DNS failure
> * New health indicator for runtime MongoDB connection
> * Connection leak fix in application-manager export/import operations
> * Improved retry mechanism with configurable exponential backoff
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.5

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.6 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer, process engine, and application manager fixes
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Retry mechanism enhancements and security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes (React)
> > >
> > > Issues resolved in the React renderer:
> > >
> > > > [accordion] Clear icon present and clickable on disabled input/textarea
> > > >
> > > > **Summary:**
> > > >
> > > > When an input or textarea component was disabled, the clear icon was still visible and clickable. The clear icon is now hidden and non-interactive on disabled components.
> > >
> > > > [accordion] Options list not shown when selectors are inside modal
> > > >
> > > > **Summary:**
> > > >
> > > > When select or multiselect components were placed inside a modal, the options list was not displayed when opened. Selector dropdowns now render correctly within modal contexts.
> > >
> > > > [accordion] Datepicker calendar shown behind modal
> > > >
> > > > **Summary:**
> > > >
> > > > When a datepicker was placed inside a modal, the calendar popup appeared behind the modal overlay. The datepicker calendar now renders above the modal with correct z-index stacking.
> > >
> > > > [accordion] Slider min/max value not set when loading a screen
> > > >
> > > > **Summary:**
> > > >
> > > > When a slider shared a process data key with an input, or when slider min/max values depended on computed values from another slider, the min/max values were not set on load. Slider initialization now correctly applies min/max values and computed dependencies.
> > >
> > > > [accordion] Slider default value not set with multiple sliders on same page
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple sliders were present on the same page, some sliders did not receive their default values, especially when no explicit null value was set in the data store. Default value initialization now works correctly for all sliders on a page.
> > >
> > > > [accordion] Task management assignee clear icon clickable when disabled
> > > >
> > > > **Summary:**
> > > >
> > > > In the task management view, the assignee field's clear icon was visible and clickable even when the field was disabled (non-editable). The clear icon is now hidden when the assignee field cannot be edited.
> > >
> > > > [accordion] Input, select, datepicker, textarea, and table filters have incorrect inner outline
> > > >
> > > > **Summary:**
> > > >
> > > > Multiple form components displayed an incorrect inner outline styling. The outline now only appears during keyboard navigation, following proper accessibility patterns.
> > >
> > > > [accordion] Data mappers autocomplete values not loading
> > > >
> > > > **Summary:**
> > > >
> > > > Data mapper autocomplete suggestions were not loading values in certain configurations. Autocomplete now correctly fetches and displays available values.
> >
> > > [tab] Renderer fixes (Angular + React)
> > >
> > > Issues resolved in both Angular and React renderers:
> > >
> > > > [accordion] Card height does not update when accordion is collapsed
> > > >
> > > > **Summary:**
> > > >
> > > > When a card component with fixed height contained an accordion, the card height did not update when the accordion was collapsed. Card height now correctly recalculates when accordion state changes.
> > >
> > > > [accordion] Focus outline appears when interacting with card/file preview accordion
> > > >
> > > > **Summary:**
> > > >
> > > > When interacting with a card or file preview component that included an accordion, an unwanted focus outline appeared. The focus outline is now only displayed during keyboard navigation.
> > >
> > > > [accordion] Button icon not correctly rendered
> > > >
> > > > **Summary:**
> > > >
> > > > When a button was configured with a right-aligned icon, fill width, and right-aligned typography, the icon was not aligned with the text, the gap was missing, and text and icon were center-aligned instead of right-aligned. Button icon layout now respects all configured alignment and spacing settings.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Advancing gets stuck when multiple events are available for one partition and pod crashes
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple events were available for the same partition and a pod crashed, only the first event was picked up and the rest remained stuck. Event processing now correctly handles all pending events after a pod recovery.
> > >
> > > > [accordion] Kafka health check reported UP despite consumer DNS failure
> > > >
> > > > **Summary:**
> > > >
> > > > The Kafka health check indicator could report UP even when consumers had DNS resolution failures, masking connectivity issues. Health indicators now correctly reflect the actual state of Kafka consumer connections.
> > >
> > > > [accordion] Health indicator for runtime MongoDB connection
> > > >
> > > > **Summary:**
> > > >
> > > > A new health indicator has been added to monitor the runtime MongoDB connection. This improves observability and allows operators to detect MongoDB connectivity issues through the standard health endpoint.
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Theme not imported during build import
> > > >
> > > > **Summary:**
> > > >
> > > > When importing a build that included theme resources, the theme was not correctly imported. Build import now includes theme resources as expected.
> > >
> > > > [accordion] Connection leak in export/import services
> > > >
> > > > **Summary:**
> > > >
> > > > During import/export operations, database connections were held for the entire duration of long-running operations (MinIO file transfers, REST calls, Kafka messaging), which could exhaust the connection pool. Transaction boundaries have been refined so that database connections are only held during actual database operations.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Process engine
> > >
> > > > [accordion] Configurable retry mechanism with exponential backoff
> > > >
> > > > **Summary:**
> > > >
> > > > The retry mechanism for optimistic locking in the process engine now uses an Equal Jitter strategy and supports runtime configuration via environment variables. Previously, the jitter was nullified by the max delay cap, causing retrying threads to collide at the same millisecond.
> > > >
> > > > New environment variables for the `process-engine`:
> > > >
> > > > | Environment Variable | Description | Default Value |
> > > > | - | - | - |
> > > > | `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` |
> > > > | `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` |
> > > > | `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` |
> > > >
> > > > > [!TIP]
> > > > >
> > > > > Default settings give a total retry window of \~1.2 seconds, which covers most transient optimistic lock conflicts. Increase `FLOWX_RETRY_MAX_RETRIES` or `FLOWX_RETRY_MAX_DELAY_MS` if you see retry exhaustion under high contention.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Removed deprecated access rights endpoint
> > > >
> > > > **Summary:**
> > > >
> > > > A deprecated endpoint and its associated test for access rights have been removed from the codebase as they are no longer needed.
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across all platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.6 is fully compatible with 5.1.5. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.5 → 5.1.6 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.6](./deployment-guidelines-v5.1.6).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.7 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.7-march-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.6 → 5.1.7** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.7 delivers bug fixes and stability improvements:
>
> * Fix for build import issues with manifest (reimport failures)
> * Security patches
> * No breaking changes, fully compatible upgrade from 5.1.6

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.7 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Build import fix
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Build reimport failures with manifest issues
> > > >
> > > > **Summary:**
> > > >
> > > > When reimporting a build, the import could fail due to manifest validation issues, either stopping mid-import or reporting that the build was already being imported. Build reimport now correctly handles manifest validation and prevents duplicate import conflicts.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.7 is fully compatible with 5.1.6. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.6 → 5.1.7 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.7](./deployment-guidelines-v5.1.7).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.8 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.8-april-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.7 → 5.1.8** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.8 delivers security patches and dependency upgrades:
>
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.7

***

**What's new? 🆕**

> [tab] Highlights
>
> Security patches and dependency upgrades across platform components.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.8 is fully compatible with 5.1.7. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.7 → 5.1.8 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.8](./deployment-guidelines-v5.1.8).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.9 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.9-may-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.8 → 5.1.9** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.9 delivers notable bug fixes alongside security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Android renderer fixes
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.8

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Advancing workers** — Improved connection management so advancing workers no longer accumulate database connections across cooldown and rampup cycles, preventing connection growth on long-running runtime deployments.
> > > > * **Reusable UI templates** — Fixed an issue where input and output mappings on reusable UI templates could be silently lost when a referenced library version was updated.
> > > > * **Designer** — Fixed server errors when bulk-editing UI templates and when patching UI actions inside reusable UI templates.
> > > > * **Android renderer** — Fixed sticky container behavior across nested hierarchy levels, and deferred the custom loader display until CMS resources are available.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.9 is fully compatible with 5.1.8. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.8 → 5.1.9 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.9](./deployment-guidelines-v5.1.9).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.2.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/deployment-guidelines-v5.2

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.12.0** | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **10.12.0** | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **10.7.0** | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **10.7.0** | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **10.6.0** | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **10.4.1** | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **10.6.0** | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **10.4.1** | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **10.8.0** | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **10.3.1** | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **10.4.1** | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **10.0.0** | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **10.0.0** | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.0.1** | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | **10.2.0** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.2.0 | Keycloak | 26+ |
| 5.2.0 | Kafka | 3.8 - 3.9 |
| 5.2.0 | PostgreSQL | 16 - 17 |
| 5.2.0 | Oracle Database | 21c, 23ai |
| 5.2.0 | MongoDB | 7 - 8 |
| 5.2.0 | Redis | 7.4 - 8.0 |
| 5.2.0 | Elasticsearch | 8 - 9 |
| 5.2.0 | Angular (Web SDK) | 19.2 |
| 5.2.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.2.0

### Key infrastructure updates

> [card] SpiceDB Upgrade
>
> Upgraded to SpiceDB v1.38.0+ and spice-db-operator for improved permission management and stability

> [card] Security Enhancements
>
> Updated Java libraries and base images to Oracle 10-slim, resolving HIGH and CRITICAL vulnerabilities

> [card] Accessibility Support
>
> Enhanced renderer components with comprehensive WCAG 2.1 compliance features

> [card] Python IDE Features
>
> Added autocomplete and IntelliSense support in business rules editors

> [card] Parallel Workflow Branches
>
> Support for concurrent execution paths in Integration Designer workflows

> [card] Workflow Partitioning & Archiving
>
> Time-based partitioning and automatic archiving for Integration Designer workflow instances

## Upgrading from v5.1.0

### Key changes

* **Accessibility Features**: No breaking changes, but new accessibility properties available in UI Designer
* **Database Security**: FlowX Database now supports sensitive data masking (requires Project Data Model configuration)
* **IDE Enhancements**: Python autocomplete is automatically available in business rules editors
* **Infrastructure**: SpiceDB upgrade requires cache clearing after migration

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.

### Compatibility

* **Backward Compatible**: v5.2.0 maintains backward compatibility with v5.1.0 configurations
* **Renderer Updates**: Web SDKs include accessibility enhancements without breaking changes
* **Mobile Renderers**: iOS and Android renderers include accessibility improvements

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/update-environment-variables-5.2

Update environment variables for all existing FlowX.AI services

## Integration Designer

### Workflow partitioning and archiving

> [!NOTE]
>
> Integration Designer now supports workflow instance partitioning and automatic archiving for efficient data management in high-volume deployments.

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Enable or disable workflow instance partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Time interval for creating partitions (`DAY`, `WEEK`, `MONTH`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Enable or disable automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Cron expression for archiving schedule (default: daily at 1:00 AM) |

> [!NOTE]
>
> **Workflow partitioning configuration:**
>
> * **Partitioning**: When enabled, workflow instances are stored in time-based partitions according to the specified interval
> * **Retention**: Determines how many intervals to keep active. Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> * **Archiving schedule**: The cron expression controls when the archiving process runs
> * **Best practice**: Enable partitioning first without archiving, verify it works correctly, then enable archiving

> [!WARNING]
>
> Enable partitioning and archiving only after careful planning and testing. Ensure your database has sufficient storage for partition management operations. It's recommended to start with archiving disabled and enable it only after verifying that partitioning works correctly for your use case.

### Advancing controller improvements

> [!NOTE]
>
> Integration Designer now uses the new ADVANCING controller with separate picking and processing operations for improved performance and resource management.

#### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

#### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.


# FlowX.AI 5.2.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025

Accessibility improvements, new side panel navigation, FlowX Database sensitive data handling, REST API response caching, and Python IDE enhancements for business rules development.

**What's new?**

> [tab] Accessibility & UX
>
> Making FlowX applications more inclusive and user-friendly with comprehensive accessibility improvements and enhanced navigation.
>
> ♿ [**Accessibility Enhancements**](#accessibility-enhancements) - Comprehensive [WCAG](https://www.w3.org/TR/WCAG21/) (Web Content Accessibility Guidelines) compliance features across all UI components\
> 🎨 [**New Workflow Side Panel**](#new-workflow-side-panel) - Enhanced navigation experience with improved drag-and-drop functionality
>
> ### **Accessibility enhancements**
>
> > [card] Accessibility enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds accessibility features across all UI components, enabling you to build [WCAG 2.1 Level AA compliant](https://www.w3.org/TR/WCAG21/) applications. These features support users with assistive technologies such as screen readers and keyboard-only navigation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs1.png)
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs2.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Accessibility Configuration Panel
> > > >
> > > > Configure labels, descriptions, and ARIA attributes in a dedicated accessibility section within UI Designer
> > >
> > > > [card] Auto-bindable Tags
> > > >
> > > > Bind accessibility tags automatically to buttons, inputs, selects, modals, and other UI components
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Navigate using keyboard shortcuts with proper focus management and tab order in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > Use screen readers with ARIA labels, descriptions, and live regions on all components
> >
> > > [tab] Supported Components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio buttons, Slider, and File upload components with labels and descriptions
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card components with keyboard navigation and focus management
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with alt text support and semantic HTML structure
> > >
> > > **4. Cross-Platform Support**
> > >
> > > Web (Angular/React), iOS, and Android platforms
> >
> > > [tab] Benefits
> > >
> > > > [card] WCAG Compliance
> > > >
> > > > Build applications that meet WCAG 2.1 Level AA standards for web accessibility
> > >
> > > > [card] Inclusive Design
> > > >
> > > > Make your applications usable for people with diverse abilities and assistive technology users
> > >
> > > > [card] Improved User Experience
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those using assistive technologies
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Meet accessibility requirements for government, healthcare, financial services, and other regulated industries
> >
> > Major Enhancement
>
> ***
>
> ### **New workflow side panel**
>
> > [card] New workflow side panel
> >
> > > [tab] Overview
> > >
> > > The new Workflow Side Panel provides an enhanced navigation experience in Integration Designer workflows. It includes improved organization, better drag-and-drop functionality, and intuitive access to design components and resources.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_side_panel.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Drag & Drop
> > > >
> > > > Add and organize workflow nodes with drag-and-drop functionality
> > >
> > > > [card] Improved Organization
> > > >
> > > > Group nodes logically with expandable/collapsible sections
> > >
> > > > [card] Search & Filter
> > > >
> > > > Find nodes instantly with quick search functionality
> >
> > UI/UX Enhancement
>
> ***

> [tab] Data & Security
>
> Enhanced data management and security features for FlowX Database and business rules.
>
> 🔒 [**FlowX Database Sensitive Data**](#flowx-database-sensitive-data) - GDPR-compliant sensitive data handling for FlowX Database\
> 🚀 [**Performance Improvements**](#performance-improvements) - Caching optimizations for better system performance
>
> ### **FlowX database sensitive data**
>
> > [card] FlowX database sensitive data
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds sensitive data handling for FlowX Database to ensure GDPR compliance. Attributes marked as sensitive in your Project Data Model are automatically protected across all FlowX Database operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic Data Masking
> > > >
> > > > Hide sensitive attributes automatically in logs, console outputs, and testing interfaces
> > >
> > > > [card] Project Data Model Integration
> > > >
> > > > Mark attributes as sensitive in Project Data Model to apply protection across all FlowX Database operations
> > >
> > > > [card] Developer-Friendly
> > > >
> > > > Access full data at runtime while maintaining security in design-time interfaces
> > >
> > > > [card] Audit Trail Protection
> > > >
> > > > Mask sensitive data in workflow output logs and operational documents
> >
> > > [tab] Protected Areas
> > >
> > > **1. Documents Page**
> > >
> > > Sensitive attributes are masked when viewing FlowX Database documents in the designer
> > >
> > > **2. Test Operations Pages**
> > >
> > > Database operation testing interfaces automatically hide sensitive data
> > >
> > > **3. Workflow Console**
> > >
> > > Console logs and output panels mask sensitive information from FlowX Database responses
> > >
> > > **4. Full Runtime Access**
> > >
> > > Applications have full access to sensitive data at runtime - protection is design-time only
> >
> > > [tab] Benefits
> > >
> > > > [card] GDPR Compliance
> > > >
> > > > Meet data protection requirements by preventing sensitive data exposure in design tools
> > >
> > > > [card] Security by Design
> > > >
> > > > Sensitive data protection is automatic once attributes are marked in Project Data Model
> > >
> > > > [card] Developer Productivity
> > > >
> > > > Test and develop without worrying about accidentally exposing sensitive information
> > >
> > > > [card] Audit-Ready
> > > >
> > > > Demonstrate proper data handling practices with masked logs and interfaces
> >
> > Security Enhancement
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Caching Enhancements
> > >
> > > FlowX.AI 5.2.0 adds intelligent caching mechanisms that improve system performance by reducing redundant processing when identical values are sent at process start.
> >
> > > [tab] Key Features
> > >
> > > > [card] Smart Caching
> > > >
> > > > Cache and reuse results automatically when identical input values are detected
> > >
> > > > [card] Reduced Latency
> > > >
> > > > Start processes faster when repeating operations with the same parameters
> > >
> > > > [card] Resource Optimization
> > > >
> > > > Reduce server load and improve resource utilization
> > >
> > > > [card] Automatic Management
> > > >
> > > > Manage cache automatically with no configuration required
> >
> > > [tab] Benefits
> > >
> > > **1. Response Times**
> > >
> > > Initialize processes faster in cached scenarios
> > >
> > > **2. Scalability**
> > >
> > > Handle more concurrent users with the same infrastructure
> > >
> > > **3. Cost Efficiency**
> > >
> > > Use fewer compute resources for high-volume scenarios
> >
> > Performance

> [tab] Developer Experience
>
> Enhanced tools and features for business rules development, testing, and workflow design.
>
> 🔀 [**Parallel Branches in Workflows**](#parallel-branches-in-workflows) - Design and execute parallel execution paths in Integration Designer workflows\
> 💾 [**REST API Response Caching**](#integration-designer-rest-api-response-caching) - Cache GET endpoint responses in Integration Designer with flexible TTL policies\
> 📊 [**Workflow Partitioning & Archiving**](#workflow-partitioning-&-archiving) - Manage Integration Designer workflow data efficiently with time-based partitions and automatic archiving\
> 🐍 [**Python IDE Enhancements**](#python-ide-enhancements) - Autocomplete and IntelliSense for Python business rules\
> 🧪 [**Business Rules Testing**](#functions-testing) - Save test parameters in reusable functions modal
>
> ### **Parallel branches in workflows**
>
> > [card] Parallel branches in workflows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds the ability to design and execute parallel branches in Integration Designer workflows. This enables concurrent execution of independent workflow paths and improves performance for complex integrations.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Start Parallel Node
> > > >
> > > > Split workflow execution into multiple concurrent branches with start parallel nodes
> > >
> > > > [card] End Parallel Node
> > > >
> > > > Merge parallel branches with end parallel nodes that wait for all branches to complete
> > >
> > > > [card] Path Visualization
> > > >
> > > > View which nodes belong to which parallel branch with visual path indexing in the workflow diagram
> > >
> > > > [card] Runtime Monitoring
> > > >
> > > > Track parallel path execution with timing information for each branch and merge point
> >
> > > [tab] How It Works
> > >
> > > **1. Design Parallel Paths**
> > >
> > > Add a Start Parallel node and create multiple sequences from it. Each sequence represents an independent execution path
> > >
> > > **2. Configure Branch Logic**
> > >
> > > Add workflow nodes to each parallel branch, such as API calls, transformations, or database operations
> > >
> > > **3. Merge Paths**
> > >
> > > Close parallel branches with an End Parallel node. This node waits for all branches to complete before continuing
> > >
> > > **4. Runtime Execution**
> > >
> > > All branches execute concurrently at runtime. The End Parallel node completes when the slowest branch finishes
> >
> > > [tab] Use Cases
> > >
> > > > [card] Multiple API Calls
> > > >
> > > > Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Fetch data from multiple sources in parallel for comprehensive data aggregation
> > >
> > > > [card] Notification Broadcasting
> > > >
> > > > Send notifications through multiple channels (email, SMS, push) simultaneously
> > >
> > > > [card] Document Processing
> > > >
> > > > Process different document types or sections in parallel for faster throughput
> >
> > > [tab] Runtime Behavior
> > >
> > > > [accordion] Path Timing
> > > >
> > > > * **Path Time**: Sum of all node execution times within that branch
> > > > * **End Parallel Time**: Node processing time + maximum time across all parallel paths
> > > > * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
> > >
> > > > [accordion] Console Logging
> > > >
> > > > * **Start Parallel Node**: Displays Input tab showing data split across branches
> > > > * **End Parallel Node**: Displays Output tab showing merged results from all branches
> > > > * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
> > >
> > > > [accordion] Error Handling
> > > >
> > > > * If any branch fails, the workflow handles it according to standard error handling rules
> > > > * End Parallel node waits for all non-failed branches before continuing
> > > > * Runtime validation ensures parallel branches are configured correctly
> >
> > > [tab] Limitations
> > >
> > > > [!WARNING]
> > > >
> > > > **First Iteration Constraints**: This is the initial implementation of parallel branches with the following considerations:
> > >
> > > * **Array Processing**: Arrays are not merged across parallel branches. When multiple branches modify the same array path, the last branch to complete determines the final array value. You cannot process individual objects from the same array in different parallel branches (for example, first element in branch 1, second element in branch 2). To preserve data from all branches, save to different keys and merge manually using a script before the end node
> > >
> > > * **Branch Closure**: All start parallel branches must be closed with end parallel nodes. Nodes following a start parallel node must merge into the same end parallel node, except for nodes that terminate with end workflow nodes
> > >
> > > > [!NOTE]
> > > >
> > > > Based on user feedback and raised exceptions during runtime execution, additional configuration constraints and validations are planned for future releases.
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Reduce workflow execution time by running independent operations concurrently instead of sequentially
> > >
> > > **2. Resource Utilization**
> > >
> > > Maximize throughput by executing multiple operations simultaneously
> > >
> > > **3. Design Clarity**
> > >
> > > Model concurrent operations explicitly in your workflow diagrams
> > >
> > > **4. Monitoring**
> > >
> > > Track execution time for each parallel path to identify bottlenecks
> >
> > Integration Designer
>
> ***
>
> ### **Integration Designer REST API response caching**
>
> > [card] Integration Designer REST API response caching
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces intelligent response caching for REST API GET endpoints in Integration Designer. Cache responses based on flexible Time-To-Live (TTL) policies to reduce redundant API calls, avoid rate limits, and lower operational costs while maintaining data freshness.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Endpoint_Get.png)
> > >
> > > > [!NOTE]
> > > >
> > > > When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Flexible TTL Policies
> > > >
> > > > Configure caching with "Expires after" (duration-based) or "Expires at" (time-based) policies
> > >
> > > > [card] Cache Management
> > > >
> > > > Clear cached responses from endpoint definitions or testing modals as needed
> > >
> > > > [card] Cache Status Visibility
> > > >
> > > > View cache status, keys, and TTL information in testing modals and workflow console logs
> > >
> > > > [card] Automatic Fallback
> > > >
> > > > System automatically calls the external API if cache retrieval fails, ensuring reliability
> >
> > > [tab] TTL Configuration
> > >
> > > > [accordion] Expires After (Duration-Based)
> > > >
> > > > Cache responses for a specific duration after the request is made.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **ISO Duration**: Use ISO 8601 duration format (e.g., `PT1H` for 1 hour, `P1D` for 1 day, `P1W` for 1 week)
> > > > * **Dynamic Duration**: Reference configuration parameters (e.g., `${myConfigParam}`)
> > > > * **Default**: `R/P1D` (1 day)
> > > >
> > > > **Example**: Cache for 10 minutes after each request
> > > >
> > > > ```
> > > > PT10M
> > > > ```
> > >
> > > > [accordion] Expires At (Time-Based)
> > > >
> > > > Cache responses until a specific time of day with recurring patterns.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **Expire Time**: Set specific time (e.g., `23:00` for midnight, `08:00` for 8 AM)
> > > > * **Recurrency**: Set how often the pattern repeats (integer > 0, default: 1)
> > > > * **Time Unit**: Choose Day, Week, or Month (default: Day)
> > > >
> > > > **Example**: Cache until midnight every day
> > > >
> > > > ```
> > > > Expire Time: 00:00
> > > > Recurrency: 1
> > > > Time Unit: Day
> > > > ```
> > > >
> > > > **Example**: Cache until 6 PM every Friday
> > > >
> > > > ```
> > > > Expire Time: 18:00
> > > > Recurrency: 1
> > > > Time Unit: Week
> > > > ```
> >
> > > [tab] Cache Visibility
> > >
> > > **1. Testing Modal**
> > >
> > > View cache status directly in the endpoint testing modal with:
> > >
> > > * **Cache Hit/Miss Status**: Whether results came from cache
> > > * **Cache Key**: The unique identifier for the cached response
> > > * **TTL Information**: When the cache expires (e.g., "Expires after PT10M" or "Expires at 23:00 on 2025-11-04")
> > >
> > > **2. Workflow Console**
> > >
> > > Monitor cache usage in workflow execution logs with the same detailed information
> > >
> > > **3. Clear Cache Action**
> > >
> > > Clear cached responses from the endpoint page or testing modal when cache is configured
> >
> > > [tab] How It Works
> > >
> > > **1. Configure Caching**
> > >
> > > In Integration Designer, open a REST System and navigate to a GET endpoint. Enable caching and select your TTL policy (Expires After or Expires At)
> > >
> > > **2. First Request**
> > >
> > > When the endpoint is called for the first time, the response is fetched from the external API and stored in cache with the configured TTL
> > >
> > > **3. Subsequent Requests**
> > >
> > > If the cache is still valid (within TTL), subsequent requests return the cached response immediately without calling the external API
> > >
> > > **4. Cache Expiration**
> > >
> > > Once TTL expires, the next request fetches fresh data from the external API and updates the cache
> > >
> > > **5. Cache Management**
> > >
> > > Use the "Clear Cache" action to manually invalidate cached responses when needed (e.g., after data updates)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Reference Data
> > > >
> > > > Cache country lists, product catalogs, or other reference data that rarely changes
> > >
> > > > [card] Rate Limit Avoidance
> > > >
> > > > Reduce API calls to third-party services with strict rate limits
> > >
> > > > [card] Cost Optimization
> > > >
> > > > Lower operational costs by reducing billable API calls to external services
> > >
> > > > [card] Performance
> > > >
> > > > Improve workflow execution speed by eliminating network latency for cached responses
> >
> > > [tab] Error Handling
> > >
> > > > [!WARNING]
> > > >
> > > > **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. This ensures your workflows always receive correct data.
> > >
> > > **Failure Scenarios**:
> > >
> > > * Cache service unavailable → Direct API call
> > > * Cache corruption or invalid data → Direct API call
> > > * Cache storage failure → Direct API call (with warning logged)
> > >
> > > Your workflows continue to function normally even if caching fails.
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced API Costs
> > > >
> > > > Minimize charges from external APIs by serving cached responses when data hasn't changed
> > >
> > > > [card] Improved Performance
> > > >
> > > > Return responses instantly from cache instead of waiting for external API calls
> > >
> > > > [card] Rate Limit Compliance
> > > >
> > > > Stay within API rate limits by reducing the number of requests to external services
> > >
> > > > [card] Better Scalability
> > > >
> > > > Handle higher workflow volumes without increasing external API calls
> >
> > Integration Designer
>
> > [card] [REST Endpoint Caching](../../../5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching)
> >
> > Learn how to configure caching policies, manage cache, and optimize your REST API integrations
>
> ***
>
> ### **Workflow partitioning & archiving**
>
> > [card] Workflow partitioning & archiving
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces workflow instance partitioning and archiving for Integration Designer. This feature enables efficient management of workflow data by organizing instances into time-based partitions and automatically archiving old data to maintain optimal database performance in large-scale deployments.
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow partitioning is particularly beneficial for high-volume Integration Designer workflows where instances accumulate over time, helping to maintain query performance and manage storage efficiently.
> >
> > > [tab] Key Features
> > >
> > > > [card] Time-Based Partitioning
> > > >
> > > > Organize workflow instances into partitions based on configurable time intervals (Day, Week, or Month)
> > >
> > > > [card] Automatic Archiving
> > > >
> > > > Automatically archive partitions older than the specified retention period to optimize active database size
> > >
> > > > [card] Flexible Retention Policies
> > > >
> > > > Configure how many time intervals to retain before archiving with granular control
> > >
> > > > [card] Scheduled Archiving
> > > >
> > > > Use cron expressions to schedule archiving operations at optimal times
> >
> > > [tab] Configuration
> > >
> > > Configure workflow partitioning using environment variables in Integration Designer:
> > >
> > > > [accordion] Partitioning Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ENABLED`**: Enable or disable workflow instance partitioning
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_INTERVAL`**: Time interval for creating partitions
> > > >   * Default: `MONTH`
> > > >   * Options: `DAY`, `WEEK`, `MONTH`
> > >
> > > > [accordion] Archiving Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`**: Enable or disable automatic archiving
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`**: Number of intervals to retain before archiving
> > > >   * Default: `3`
> > > >   * Options: Any positive integer
> > > >   * Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`**: Schedule for archiving operations
> > > >   * Default: `0 0 1 * * ?` (runs daily at 1:00 AM)
> > > >   * Options: Any valid cron expression
> >
> > > [tab] How It Works
> > >
> > > **1. Enable Partitioning**
> > >
> > > Set `FLOWX_DATA_PARTITIONING_ENABLED=true` to start organizing workflow instances into time-based partitions
> > >
> > > **2. Configure Partition Interval**
> > >
> > > Choose a partition interval (DAY, WEEK, or MONTH) based on your workflow volume and retention needs
> > >
> > > **3. Set Retention Policy**
> > >
> > > Define how many intervals to retain. For example, with MONTH interval and 3 retention intervals, data older than 3 months will be archived
> > >
> > > **4. Enable and Schedule Archiving**
> > >
> > > Turn on archiving and configure the cron expression to run archiving operations during low-traffic periods
> > >
> > > **5. Monitor Performance**
> > >
> > > Track database performance improvements as old partitions are archived and active data size is optimized
> >
> > > [tab] Use Cases
> > >
> > > > [card] High-Volume Workflows
> > > >
> > > > Maintain performance for Integration Designer workflows processing thousands of instances daily
> > >
> > > > [card] Compliance Requirements
> > > >
> > > > Archive historical workflow data while maintaining access to recent instances for operational needs
> > >
> > > > [card] Database Optimization
> > > >
> > > > Keep active database size manageable by automatically moving old data to archive partitions
> > >
> > > > [card] Long-Running Deployments
> > > >
> > > > Prevent database bloat in production environments running for extended periods
> >
> > > [tab] Best Practices
> > >
> > > > [!WARNING]
> > > >
> > > > **Planning and Testing Required**: Enable partitioning and archiving only after careful planning and testing. Once enabled:
> > > >
> > > > * Ensure sufficient database storage for partition management operations
> > > > * Start with archiving disabled to verify partitioning works correctly
> > > > * Test thoroughly in non-production environments before enabling in production
> > > > * Monitor database performance during initial archiving operations
> > > > * Choose partition intervals based on your workflow volume and retention requirements
> > >
> > > **Recommended Approach**:
> > >
> > > 1. Enable partitioning first without archiving
> > > 2. Monitor partition creation and database performance
> > > 3. After verifying stable operation, enable archiving
> > > 4. Schedule archiving during low-traffic periods (e.g., overnight)
> > > 5. Start with longer retention periods and adjust based on requirements
> >
> > > [tab] Benefits
> > >
> > > > [card] Improved Performance
> > > >
> > > > Maintain fast query performance as workflow instance count grows over time
> > >
> > > > [card] Efficient Storage
> > > >
> > > > Optimize database storage by archiving historical data while keeping recent data accessible
> > >
> > > > [card] Automatic Management
> > > >
> > > > Set retention policies once and let the system handle archiving automatically
> > >
> > > > [card] Scalability
> > > >
> > > > Support long-running production deployments with predictable database growth
> >
> > Integration Designer
>
> > [card] [Integration Designer Setup](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration)
> >
> > Learn how to configure workflow partitioning and archiving for Integration Designer
>
> ***
>
> ### **Python IDE enhancements**
>
> > [card] Python IDE enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds professional IDE features to Python business rules development, including autocomplete, IntelliSense, and enhanced code editing capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Autocomplete
> > > >
> > > > Get intelligent code suggestions as you type, including Python standard library and FlowX APIs
> > >
> > > > [card] IntelliSense
> > > >
> > > > Use context-aware code completion with parameter hints and documentation
> > >
> > > > [card] Syntax Highlighting
> > > >
> > > > Read code more easily with enhanced Python syntax highlighting
> > >
> > > > [card] Error Detection
> > > >
> > > > Detect syntax errors in real-time with helpful error messages
> >
> > > [tab] Benefits
> > >
> > > **1. Development Speed**
> > >
> > > Write business rules faster with intelligent code suggestions
> > >
> > > **2. Error Reduction**
> > >
> > > Catch syntax errors before deployment with real-time validation
> > >
> > > **3. API Discovery**
> > >
> > > Discover available APIs and methods through IntelliSense
> > >
> > > **4. Professional Experience**
> > >
> > > Use IDE-quality editing features directly in FlowX Designer
> >
> > Developer Tools
>
> ***
>
> ### **Functions testing**
>
> > [card] Functions testing
> >
> > > [tab] Overview
> > >
> > > Test Reusable Functions more efficiently by saving test parameters directly from the testing modal. This enables faster iteration and better test coverage.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Save Test Parameters
> > > >
> > > > Save test inputs directly from the testing modal and reuse them in future test runs
> > >
> > > > [card] Test History
> > > >
> > > > Access previously saved test parameters for regression testing
> > >
> > > > [card] Faster Iteration
> > > >
> > > > Re-test functions quickly with saved parameter sets
> > >
> > > > [card] Test Coverage
> > > >
> > > > Build a library of test cases for comprehensive function validation
> >
> > > [tab] Benefits
> > >
> > > **1. Quality**
> > >
> > > Test functions more thoroughly to improve quality
> > >
> > > **2. Time Savings**
> > >
> > > Avoid re-entering test data for each test iteration
> > >
> > > **3. Documentation**
> > >
> > > Use saved test cases as examples of how to use the function
> >
> > Testing Enhancement

> [tab] Additional Improvements
>
> Platform improvements, security updates, and bug fixes.
>
> 🌍 [**Task Management Localization**](#task-management-localization) - Comprehensive localization support with automatic table grid localization and 51 substitution tags\
> 🔧 [**Platform Enhancements**](#platform-enhancements) - Infrastructure upgrades and security improvements\
> 🐛 [**Bug Fixes**](#bug-fixes) - Resolved issues and stability improvements
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds comprehensive localization support for Task Management, enabling you to customize all user-facing text elements including table columns, filters, and actions. This allows you to deliver Task Management experiences in multiple languages:
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> >
> > > [tab] Key Features
> > >
> > > > [card] Table Grid Localization (Automatic)
> > > >
> > > > Data table components (filters, menus, pagination, data types) are automatically localized based on container app language
> > >
> > > > [card] Substitution Tags (Manual)
> > > >
> > > > Configure 51 system substitution tags in CMS to localize table columns, task actions, and UI elements
> > >
> > > > [card] Multi-language Support
> > > >
> > > > Support for 34 languages including Arabic, Chinese, Japanese, Korean, and European languages
> > >
> > > > [card] Task Action Localization
> > > >
> > > > Localize all task actions, statuses, and workflow-related text elements
> >
> > > [tab] Localization components
> > >
> > > > [accordion] Table Grid Locale Keys
> > > >
> > > > FlowX Task Management uses a comprehensive table grid localization system. These keys are **automatically applied** by FlowX.AI based on your container app language and cover all table functionality:
> > > >
> > > > * **Filters**: Set filters, text filters, number filters, date filters with all operators (equals, contains, starts with, etc.)
> > > >
> > > > * **Menus**: Column menus, context menus, aggregation functions, sorting options
> > > >
> > > > * **Pagination**: Page navigation, page size selectors, row counts
> > > >
> > > > * **Data Types**: Boolean values, dates, numbers with proper formatting
> > > >
> > > > * **Advanced Features**: Pivot mode, charting, column grouping, and row operations
> > > >
> > > > * **ARIA Labels**: Accessibility labels for screen readers and assistive technologies
> > > >
> > > > > [!NOTE]
> > > > >
> > > > > **Automatic Localization**: Table grid locale keys are automatically translated by FlowX.AI based on your container app language. No manual configuration or setup required.
> > >
> > > > [accordion] FlowX substitution tags (51 keys)
> > > >
> > > > Use these substitution tags in CMS to localize custom Task Management interface elements. All tags include English default values:
> > > >
> > > > **Search & Navigation**
> > > >
> > > > * `sys_tm_search` - "Search"
> > > >
> > > > **Table Columns**
> > > >
> > > > * `sys_tm_title` - "Title"
> > > > * `sys_tm_stage` - "Stage"
> > > > * `sys_tm_assignee` - "Assignee"
> > > > * `sys_tm_status` - "Status"
> > > > * `sys_tm_priority` - "Priority"
> > > > * `sys_tm_last_updated` - "Last updated"
> > > >
> > > > **Process States (Status Values)**
> > > >
> > > > * `sys_tm_created` - "Created"
> > > > * `sys_tm_started` - "Started"
> > > > * `sys_tm_finished` - "Finished"
> > > > * `sys_tm_finished_with_error` - "Finished with error"
> > > > * `sys_tm_failed` - "Failed"
> > > > * `sys_tm_expired` - "Expired"
> > > > * `sys_tm_aborted` - "Aborted"
> > > > * `sys_tm_terminated` - "Terminated"
> > > > * `sys_tm_dismissed` - "Dismissed"
> > > > * `sys_tm_on_hold` - "On hold"
> > > >
> > > > **Bulk Actions**
> > > >
> > > > * `sys_tm_assign_to` - "Assign to…"
> > > > * `sys_tm_unassign_all` - "Unassign All"
> > > > * `sys_tm_assign_all_to_me` - "Assign All to me"
> > > > * `sys_tm_hold_all` - "Hold All"
> > > > * `sys_tm_unhold_all` - "Unhold All"
> > > >
> > > > **Task Actions**
> > > >
> > > > * `sys_tm_view_application` - "View Application"
> > > > * `sys_tm_unassign` - "Unassign"
> > > > * `sys_tm_assign_to_myself` - "Assign to myself"
> > > > * `sys_tm_unhold` - "Unhold"
> > > > * `sys_tm_hold` - "Hold"
> > > > * `sys_tm_assign` - "Assign"
> > > > * `sys_tm_execute` - "Execute"
> > > > * `sys_tm_start` - "Start"
> > > >
> > > > **Task Details Sections**
> > > >
> > > > * `sys_tm_assignee_deactivated` - "(Deactivated)"
> > > > * `sys_tm_comments` - "Comments"
> > > > * `sys_tm_write_a_comment` - "Write a comment…"
> > > > * `sys_tm_history` - "History"
> > > >
> > > > **History Events**
> > > >
> > > > * `sys_tm_task_created` - "Task created"
> > > > * `sys_tm_user_created_this_task` - "`${user}` created this task"
> > > > * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
> > > > * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
> > > > * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
> > > > * `sys_tm_task_moved_to` - "Task moved to"
> > > > * `sys_tm_task_status_changed_to` - "Task status changed to"
> > > > * `sys_tm_task_assigned_to` - "Task assigned to"
> > > > * `sys_tm_task_owner_removed` - "Task owner removed"
> > > >
> > > > **User Selection & Search**
> > > >
> > > > * `sys_tm_select_person` - "Select person..."
> > > > * `sys_tm_search_person` - "Search users"
> > > > * `sys_tm_search_term_validation` - "Type at least 4 characters..."
> > > >
> > > > **UI States**
> > > >
> > > > * `sys_tm_loading` - "Loading..."
> > > > * `sys_tm_nothing_found` - "Nothing Found"
> > > >
> > > > **Data Display**
> > > >
> > > > * `sys_tm_in` - "In" (custom filter operator)
> > > >
> > > > * `sys_tm_yes` - "Yes" (boolean value)
> > > >
> > > > * `sys_tm_no` - "No" (boolean value)
> > > >
> > > > > [!WARNING]
> > > > >
> > > > > **\*\*Manual Configuration Required**: These 51 FlowX substitution tags must be configured manually in CMS for each language. They control custom Task Management UI elements outside of the data table.
> >
> > > [tab] Implementation
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization (300+ keys for filters, menus, pagination, data types) based on this setting
> > >
> > > **2. Configure FlowX Substitution Tags in CMS**
> > >
> > > Add translations for all 51 FlowX substitution tags (sys\_tm\_\*) in CMS for each supported language. These control custom Task Management UI elements (task actions, bulk operations, history events, comments)
> > >
> > > **3. Configure Custom Column Names (Optional)**
> > >
> > > If you need custom columns beyond the defaults, use substitution tags for column display names in your Task Management configuration
> > >
> > > **4. Test Localization**
> > >
> > > Verify complete localization:
> > >
> > > * **Table grid elements** (automatic): filters, sorting, pagination, menus should display in container app language
> > >
> > > * **FlowX custom elements** (CMS): task actions, bulk operations, history events, comments should use your CMS translations
> > >
> > > > [!NOTE]
> > > >
> > > > **Simple Setup**: Configure only the 51 FlowX substitution tags in CMS. Table grid localization (300+ keys) is handled automatically by the platform.
> >
> > > [tab] Benefits
> > >
> > > > [card] Global Reach
> > > >
> > > > Deploy Task Management to users worldwide with native language support
> > >
> > > > [card] Consistent Experience
> > > >
> > > > Provide a fully localized experience across all Task Management components
> > >
> > > > [card] Easy Maintenance
> > > >
> > > > Manage translations centrally through CMS substitution tags
> > >
> > > > [card] Professional Quality
> > > >
> > > > Leverage professional translations for data grid components with automatic localization
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> > [card] [Task Management Overview](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
> >
> > Learn about Task Management features and configuration
>
> > [card] [Process Settings](../../../5.1/docs/building-blocks/process/process-definition#integrate-with-task-manager)
> >
> > Configure Task Management integration in process settings
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform Enhancements
> >
> > FlowX.AI 5.2.0 includes platform improvements focused on security, stability, and infrastructure.
> >
> > ## Security & Infrastructure Updates
> >
> > > [card] Vulnerability Fixes
> > >
> > > Update Java libraries and base images to address security vulnerabilities
> >
> > > [card] SpiceDB Upgrade
> > >
> > > Upgrade SpiceDB with new operator version
> >
> > > [card] Dependency Updates
> > >
> > > Update platform dependencies to latest secure versions
> >
> > ## Additional improvements
> >
> > > [card] Permission-based UI
> > >
> > > Add permission-based UI functionality in Reusable UI Templates
> >
> > > [card] Database Query Improvements
> > >
> > > Improve FlowX Database query handling and error messages
> >
> > > [card] System Substitution Tags
> > >
> > > Use system substitution tags in task management texts in CMS
> >
> > > [card] SSE Disconnect Handling
> > >
> > > Handle Server-Sent Events disconnections better to reduce log noise
> >
> > > [card] [Integration Designer Environment Variables](./update-environment-variables-5.2)
> > >
> > > Update environment variables for improved advancing controller with separate picking and processing operations, see details [here](./update-environment-variables-5.2)
> >
> > Platform Updates
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes & stability improvements
> >
> > FlowX.AI 5.2.0 includes bug fixes and stability improvements to improve the overall user experience.
> >
> > ## Notable fixes
> >
> > > [accordion] Fixes
> > >
> > > * **Process Instances Page**: Fix error when opening Runtime process instances page
> > > * **Resource Import**: Fix import requests that use incorrect content type
> > > * **Elasticsearch Updates**: Fix engine errors when updating documents in older indexes
> > > * **Navigation Tree**: Fix navigation tree response for overridden processes
> > > * **Dependency Management**: Fix errors when updating library dependency versions
> >
> > > [accordion] UI/UX fixes
> > >
> > > * **Accessibility**: Fix missing accessibility sections on various components
> > > * **Theme Configuration**: Fix element selection issues in segmented button panel
> > > * **Modal Behavior**: Improve modal focus management and keyboard navigation
> > > * **Select Components**: Fix highlighting and navigation issues in select/multiselect
> > > * **Task Manager**: Fix browser freeze when opening table configuration
> >
> > > [accordion] Renderer fixes
> > >
> > > * **Angular SDK**: Fix keyboard navigation issues with select components and shift+tab behavior
> > > * **React SDK**: Fix option highlighting and keyboard navigation in various components
> > > * **Workflow Display**: Fix rendering issues in Integration Designer workflows
> > > * **Collection Components**: Fix card expansion issues with accordions in navigation areas
> >
> > > [accordion] Backend fixes
> > >
> > > * **Events Gateway**: Improve SSE disconnect handling to reduce error log flooding
> > > * **Database Operations**: Improve error handling and validation for FlowX Database queries
> > > * **Process Navigation**: Fix back button redirects from process definitions
> > > * **Warning Management**: Clean up warnings properly when deleting parent actions

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.2.0](./deployment-guidelines-v5.2).
>
> ### Environment variables updates
>
> > [!NOTE]
> >
> > For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
>
> ### Coming soon
>
> Additional features currently in development for future releases:
>
> * Extended accessibility support for iOS and Android platforms
> * Additional Python IDE capabilities
> * Enhanced FlowX Database query preview and optimization tools


# Deployment guidelines v5.3.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/deployment-guidelines-v5.3

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.29.0** | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 |
| **admin** | **10.26.1** | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 |
| **designer** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **cms-core** | **10.16.0** | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 |
| **scheduler-core** | **10.11.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **events-gateway** | **10.12.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **notification-plugin** | **10.17.0** | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **document-plugin** | **10.16.0** | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 |
| **task-management-plugin** | **10.18.0** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 |
| **data-search** | **10.10.1** | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 |
| **audit-core** | **10.15.1** | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **advancing-controller** | **10.11.0** | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 |
| **integration-designer** | **10.24.0** | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 |
| **application-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **runtime-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **data-sync** | **10.14.1** | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 |
| **authorization-system** | **10.18.1** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - |
| **nosql-db-runner** | **10.10.1** | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **iOS renderer** | **10.1.0** | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 |
| **Android renderer** | **10.1.0** | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 |

### Plugins

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.1** | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 |
| **di-platform** | **10.2.5** | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 |
| **ai-platform-ai-developer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-connected-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agents** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-conversations** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-models** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-tenants** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-planner** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-analyst** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-designer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agent-builder** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-binaries** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.3.0 | Keycloak | 26+ |
| 5.3.0 | Kafka | 3.8 - 3.9 |
| 5.3.0 | PostgreSQL | 16 - 17 |
| 5.3.0 | Oracle Database | 21c, 23ai |
| 5.3.0 | MongoDB | 7 - 8 |
| 5.3.0 | Redis | 7.4 - 8.0 |
| 5.3.0 | Elasticsearch | 8 |
| 5.3.0 | Angular (Web SDK) | 19.2 |
| 5.3.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.3.0

### Key features and updates

> [card] UI Flows
>
> Build multi-platform applications with reusable UI components across web, iOS, and Android

> [card] UI Events
>
> Real-time user interaction handling with event-driven UI components

> [card] Workflow Data Models
>
> Workflow-level data models with input/output parameters and process-to-workflow data mapping

> [card] Mobile Accessibility
>
> WCAG 2.1 accessibility compliance extended to iOS and Android platforms

> [card] Custom Component Enhancements
>
> Standardized custom component integration across all platforms

> [card] SaaS Capabilities
>
> Multi-tenant SaaS capabilities with organization management

## Upgrading from v5.2.0

### Breaking changes

> [!WARNING]
>
> **FlowX Engine Configuration Changes**: The partitioning and archiving configuration structure has been reorganized. If you have enabled data partitioning, you **must** update your configuration files before or immediately after upgrading.

> [card] [Complete migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
>
> See the detailed migration guide with step-by-step instructions, configuration examples, and troubleshooting

### Key changes

* **UI Flows**: New feature for building multi-platform reusable UI components
* **Workflow Data Models**: Enhanced integration between processes and workflows with structured data models
* **Mobile Accessibility**: iOS and Android renderers now support WCAG 2.1 accessibility standards
* **Configuration Structure**: Breaking change in FlowX Engine partitioning/archiving configuration (see preceding section)

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.

### Compatibility

* **Breaking Changes**: FlowX Engine partitioning/archiving configuration structure has changed (action required if using partitioning)
* **Feature Additions**: UI Flows, UI Events, and Workflow Data Models are new features with no breaking changes
* **Renderer Updates**: Web and mobile SDKs include new features with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/migration-overview

Migration guide for upgrading from FlowX.AI v5.2.0 to v5.3.0

> [!NOTE]
>
> FlowX.AI v5.3.0 is an incremental update from v5.2.0 with one breaking change related to FlowX Engine configuration structure.

## What's changing

FlowX.AI v5.3.0 introduces a breaking change to the FlowX Engine partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings have been reorganized under `partitioning.archiving`.

## Who is affected

> [!WARNING]
>
> This breaking change **only affects** deployments that have:
>
> * Enabled data partitioning in FlowX Engine (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings (`SCHEDULER_DATAPARTITIONING_ENABLED=true`)
>
> If you have not enabled these features, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

## Migration process

**1. Review configuration changes**

Understand the new configuration structure and identify which settings need to be updated in your deployment

**2. Update configuration files**

Update your FlowX Engine configuration files (YAML or environment variables) following the migration steps

**3. Deploy and verify**

Deploy the updated configuration and verify that partitioning and archiving continue to work correctly

## Key changes summary

### Configuration structure

**What's removed:**

* `scheduler.dataPartitioning` section with `enabled` and `cronExpression` settings

**What's added:**

* `partitioning.archiving` subsection containing all archiving-related settings

**What's moved:**

* `retention-intervals` moved from `partitioning` to `partitioning.archiving`
* `detached-partition-compression` moved to `partitioning.archiving`
* `moved-data-batch-size` moved to `partitioning.archiving`
* `cronExpression` moved from `scheduler.dataPartitioning` to `partitioning.archiving`

### Environment variables

5 environment variables have been renamed to reflect the new structure:

| Old Variable | New Variable |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` |

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility**: The old configuration structure is not supported in v5.3.0 and causes FlowX Engine startup errors.
>
> You must update your configuration before or immediately after upgrading to v5.3.0.

## Rollback support

If you need to rollback from v5.3.0 to v5.2.x:

1. Revert your configuration files to the previous structure
2. Restore environment variables to their previous names
3. Downgrade the FlowX Engine container/pod to the previous version

> [!NOTE]
>
> Database schema changes are forward-compatible. Ensure you have database backups before any upgrade.

> [!NOTE]
>
> This is a configuration-only change. No code changes, data migration, or schema updates are required.

## Next steps

## Additional resources

> [card] [Partitioning & Archiving Setup](/5.1/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving)
>
> Complete guide to FlowX Engine partitioning and archiving

> [card] [Deployment Guidelines v5.3.0](../deployment-guidelines-v5.3)
>
> Component versions and deployment instructions

> [card] [Release Notes v5.3.0](../v5.3.0-december-2025)
>
> Full release notes for v5.3.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/update-environment-variables-5.3

Update environment variables for all existing FlowX.AI services

## FlowX Engine

### Partitioning and archiving configuration restructure

> [!NOTE]
>
> FlowX.AI v5.3.0 reorganizes the partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings are now under `partitioning.archiving`.

#### Variables to remove

If you are using environment variables to override FlowX Engine configuration, remove these variables:

| Remove This Variable | Reason |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |

#### Variables to replace

| Old Variable Name | New Variable Name | Default Value | Description |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of partition intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression level for archived partitions (Oracle only): `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for moving data during archiving (PostgreSQL only) |

#### New variables structure

The archiving configuration is now nested under `partitioning.archiving`:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Turn on or off data partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Partition interval: `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Turn on or off automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Schedule expression for archiving operations (default: daily at 1:00 AM) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression for archived partitions (Oracle only) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for data movement (PostgreSQL only) |

> [!NOTE]
>
> **Configuration structure changes:**
>
> * **Removed**: `scheduler.dataPartitioning` section
> * **Added**: `partitioning.archiving` subsection with all archiving-related settings
> * **Unchanged**: Core partitioning settings (`enabled`, `interval`) remain at `partitioning` level
> * **Moved**: Archiving-specific settings (`retention-intervals`, `cronExpression`, `detached-partition-compression`, `moved-data-batch-size`) are now under `partitioning.archiving`

> [!WARNING]
>
> **Action required if using partitioning:**
>
> If you have enabled data partitioning in FlowX Engine, you **must** update your configuration:
>
> 1. **YAML configuration**: Update your `application.yml` to follow the new structure (see [Deployment Guidelines](../deployment-guidelines-v5.3#breaking-changes))
> 2. **Environment variables**: Update variable names as shown in the tables above
> 3. **Deployment order**: Update configuration before or immediately after upgrading to v5.3.0

#### Configuration examples

> [tab] Environment Variables (Before)
>
> ```bash theme={"dark"}
> # Old structure (v5.2 and earlier)
> SCHEDULER_DATAPARTITIONING_ENABLED=true
> SCHEDULER_DATAPARTITIONING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS=3
> FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [tab] Environment Variables (After)
>
> ```bash theme={"dark"}
> # New structure (v5.3.0)
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true
> FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS=3
> FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [!NOTE]
>
> **Impact assessment:**
>
> This change only affects deployments that have:
>
> * Enabled data partitioning (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings
>
> If partitioning is disabled, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

### New optional variables

| Variable | Default Value | Description |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Falls back to `KAFKA_TOPIC_PATTERN` if not set | Dedicated topic pattern for FlowX connectors, separate from other platform components like document-plugin, data-search, and cms-core |

> [!NOTE]
>
> The `KAFKA_TOPIC_CONNECTOR_PATTERN` variable allows you to configure a custom Kafka topic pattern specifically for FlowX connectors without affecting other platform components.

> [card] [Complete migration guide](migration-overview)
>
> See the Deployment Guidelines for complete configuration examples, step-by-step migration instructions, and troubleshooting guidance.


# FlowX.AI 5.3.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025

UI Flows for multi-platform app building, UI Events for real-time interactions, enhanced custom component integration, and mobile accessibility improvements.

**What's new?**

> [tab] App builder & reusability
>
> Build multi-platform applications faster with UI Flows, enhance real-time interactions with UI Events, and integrate custom components across all platforms.
>
> 📱 [**UI Flows**](#ui-flows) - Build multi-platform applications with reusable UI components across web, iOS, and Android\
> ⚡  [**UI Events**](#ui-events) - Real-time user interaction handling with event-driven UI components\
> 🧩 [**Custom Component Enhancements**](#custom-component-enhancements) - Enhanced integration for custom components with standardized data mapping\
> 📤 [**File Upload Improvements**](#file-upload-improvements) - Enhanced file upload experience with better loading states and user feedback\
> ♿ [**Mobile Accessibility**](#mobile-accessibility) - WCAG 2.1 accessibility compliance for iOS and Android platforms\
> 🏢 [**Cross Workspace Projects**](#cross-workspace-projects) - Share projects across multiple workspaces for flexible environment testing\
> 🎯 [**Collection & Table Actions**](#collection-and-table-actions) - Execute actions from collections and tables in UI Flows
>
> ### **UI flows**
>
> > [card] UI flows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Flows, a powerful new capability that enables you to build reusable, multi-platform user interfaces that work across web (Angular/React), iOS, and Android applications. UI Flows separate UI definitions from process logic, enabling better reusability and faster application development without the overhead of full BPMN processes.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flows revolutionize how you build applications by allowing you to create a UI once and deploy it across all platforms, dramatically reducing development time and ensuring consistent user experiences.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Unnecessary process complexity
> > > >
> > > > Some use cases do not need a mapping of the business case in BPMN and the complexity and overhead that a FlowX process entails
> > >
> > > > [card] Subprocess overhead
> > > >
> > > > Unnecessary subprocess layers inside processes added complexity for simple UI scenarios
> > >
> > > > [card] Tight UI-process coupling
> > > >
> > > > UI definitions were tightly coupled to process logic, reducing reusability and increasing maintenance
> > >
> > > > [card] Platform-specific development
> > > >
> > > > Building the same UI for multiple platforms required separate implementations for each platform
> >
> > > [tab] Key Features
> > >
> > > > [card] UI Flows as project resources
> > > >
> > > > UI Flows are managed as independent project resources, separate from process definitions
> > >
> > > > [card] Navigation areas management
> > > >
> > > > Manage Navigation Areas inside UI Flows Designer for structured navigation and layout
> > >
> > > > [card] Start process UI action
> > > >
> > > > Launch FlowX processes directly from UI Flows, bridging UI and process execution
> > >
> > > > [card] Navigate to UI action
> > > >
> > > > Setup navigation to Nav areas or Container elements through scroll for seamless UX
> > >
> > > > [card] Task Manager component
> > > >
> > > > Embed Task Manager as a UI Component in UI Flows for task management capabilities
> > >
> > > > [card] Multi-platform support
> > > >
> > > > Create UI once and deploy to web (Angular/React), iOS, and Android with platform-specific configurations
> > >
> > > > [card] Import/export
> > > >
> > > > Export UI Flows as portable packages and import them across environments and applications
> > >
> > > > [card] Platform selection
> > > >
> > > > Configure platform-specific behaviors and overrides for web, iOS, and Android in the UI Flows designer
> > >
> > > > [card] Home page support
> > > >
> > > > Create UI Flows with dedicated home pages and home navigation icons for better UX
> >
> > > [tab] How It Works
> > >
> > > **1. Create UI flow**
> > >
> > > Create a UI Flow as a project resource in FlowX Designer, separate from process definitions
> > >
> > > **2. Design navigation**
> > >
> > > Manage Navigation Areas inside UI Flows Designer, defining pages and navigation structure
> > >
> > > **3. Add components**
> > >
> > > Add UI components including Task Manager, forms, custom components, and other UI elements
> > >
> > > **4. Configure actions**
> > >
> > > Setup UI Actions like Start Process (to launch processes) and Navigate To (for Nav areas or container scrolling)
> > >
> > > **5. Configure platforms**
> > >
> > > Set platform-specific configurations using the platform selection subheader (Web, iOS, Android)
> > >
> > > **6. Set home page**
> > >
> > > Designate a page as the home page with automatic home icon navigation support
> > >
> > > **7. Export & reuse**
> > >
> > > Export your UI Flow and import it into other applications or environments for maximum reusability
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced complexity
> > > >
> > > > Build UIs without the overhead of BPMN processes for use cases that don't require business process mapping
> > >
> > > > [card] Faster development
> > > >
> > > > Build UI once instead of creating separate interfaces for each platform
> > >
> > > > [card] Flexible architecture
> > > >
> > > > Eliminate unnecessary subprocess layers - use UI Flows for simple scenarios and processes for complex business logic
> > >
> > > > [card] Consistent UX
> > > >
> > > > Ensure identical user experiences across web, iOS, and Android applications
> > >
> > > > [card] Reusability
> > > >
> > > > Share UI Flows across multiple applications and projects
> > >
> > > > [card] Process integration
> > > >
> > > > Launch processes from UI Flows when needed, maintaining clean separation of concerns
> > >
> > > > [card] Maintainability
> > > >
> > > > Update UI in one place and propagate changes across all platforms
> > >
> > > > [card] Enhanced navigation
> > > >
> > > > Rich navigation capabilities with Nav areas, container scrolling, and Task Manager integration
> >
> > > [tab] Use Cases
> > >
> > > **When to Use UI Flows vs Processes:**
> > >
> > > **Use UI Flows for:**
> > >
> > > * **Information Display**: Dashboards, reports, and static content that doesn't require process orchestration
> > > * **Task Management**: Task lists and task management interfaces with embedded Task Manager component
> > > * **Navigation Shells**: Application navigation structures and home pages
> > > * **Form Collections**: Data entry forms that start processes but don't need their own process context
> > > * **Multi-Platform Apps**: Applications that need consistent UI across web and mobile platforms
> > >
> > > **Use Processes for:**
> > >
> > > * **Business Logic**: Complex workflows with business rules, approvals, and integrations
> > > * **State Management**: Applications requiring process state tracking and persistence
> > > * **Orchestration**: Multi-step operations with decision points and parallel execution
> > >
> > > **Combine Both:**
> > >
> > > Create UI Flows as the main application shell and use Start Process UI Actions to launch business processes when needed, keeping your architecture clean and maintainable.
> >
> > > [card] [UI Flows Documentation](/5.9/docs/building-blocks/ui-flows)
> > >
> > > Complete guide to creating and configuring UI Flows, including navigation management, UI actions, and platform considerations.
> >
> > Major Feature
>
> ***
>
> ### **UI events**
>
> > [card] UI events
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Events, enabling real-time interaction handling directly within Reusable UI Templates. UI Events allow you to capture user interactions like button clicks, form changes, or custom events and respond immediately without process execution, providing responsive and dynamic user experiences.
> >
> > > [tab] Key Features
> > >
> > > > [card] Event configuration
> > > >
> > > > Configure UI Events in UI Designer with custom event types and handling logic
> > >
> > > > [card] Cross-platform support
> > > >
> > > > UI Events work consistently across Angular, React, iOS, and Android renderers
> > >
> > > > [card] Runtime mapping
> > > >
> > > > UI Event results are mapped automatically in Reusable UI Template instances at runtime
> > >
> > > > [card] Design-time testing
> > > >
> > > > Test UI Events directly in UI Designer before deploying to runtime
> >
> > > [tab] Use Cases
> > >
> > > > [card] Form validation
> > > >
> > > > Validate form inputs in real-time as users type, providing immediate feedback
> > >
> > > > [card] Dynamic UI updates
> > > >
> > > > Show/hide fields, update options, or change UI state based on user interactions
> > >
> > > > [card] Client-side logic
> > > >
> > > > Execute lightweight client-side logic without triggering backend processes
> > >
> > > > [card] Responsive interactions
> > > >
> > > > Create highly responsive UI behaviors like autocomplete, live search, or conditional displays
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Handle UI interactions instantly without waiting for backend process execution
> > >
> > > **2. User experience**
> > >
> > > Provide immediate visual feedback and responsive interactions
> > >
> > > **3. Reduced complexity**
> > >
> > > Simplify process logic by handling UI-specific interactions at the component level
> >
> > UX Enhancement
>
> ***
>
> ### **Custom component enhancements**
>
> > [card] Custom component enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 standardizes custom component integration across all platforms (Angular, React, iOS, Android) with unified data mapping for input keys, data binding, save operations, and action handling. This provides a consistent developer experience when building custom components.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified data mapping
> > > >
> > > > Standard data, saveData, and action body mapping across all platforms
> > >
> > > > [card] Input key mapping
> > > >
> > > > Consistent input key handling for passing configuration and data to custom components
> > >
> > > > [card] Platform parity
> > > >
> > > > Identical custom component APIs across Angular, React, iOS, and Android
> > >
> > > > [card] Action integration
> > > >
> > > > Integration with FlowX actions for triggering backend operations
> >
> > > [tab] Benefits
> > >
> > > **1. Developer productivity**
> > >
> > > Build custom components once with knowledge that applies across all platforms
> > >
> > > **2. Code reusability**
> > >
> > > Share component logic and patterns across web and mobile implementations
> > >
> > > **3. Consistency**
> > >
> > > Ensure consistent behavior and data handling across all platforms
> >
> > Developer Experience
>
> ***
>
> ### **File upload improvements**
>
> > [card] File upload improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the file upload experience across all platforms with improved loading states, better user feedback, and more flexible configuration options. These improvements provide clearer status communication during file upload operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Enhanced loading behavior
> > > >
> > > > Configure loading behavior with optional overlay loader and custom loading messages
> > >
> > > > [card] Toast notifications
> > > >
> > > > Success and error messages displayed as toasts with customizable messages
> > >
> > > > [card] Dynamic messages
> > > >
> > > > Display dynamic key values in toast and loading messages for context-aware feedback
> > >
> > > > [card] Generic loader design
> > > >
> > > > Updated loader designs across Angular, React, iOS, and Android for consistent theming
> >
> > > [tab] Configuration
> > >
> > > **Loading Behavior Options:**
> > >
> > > * **NONE**: No loading overlay displayed during upload
> > > * **OVERLAY**: Full-screen overlay with spinner and optional loading message
> > >
> > > **Toast Notifications:**
> > >
> > > * **Success Toast**: Toggle to show success message when upload completes (auto-dismiss after 3-5 seconds)
> > > * **Error Toast**: Toggle to show error message when upload fails (auto-dismiss after 3-5 seconds)
> > > * **Custom Messages**: Configure success and error messages with dynamic substitutions
> > >
> > > **Theming Support:**
> > >
> > > * Apply custom themes to loaders and toast messages
> > > * Configure colors, sizes, and styling to match your brand
> > > * Consistent visual language across platforms
> >
> > UX Enhancement
>
> ***
>
> ### **Mobile accessibility**
>
> > [card] Mobile accessibility
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 extends WCAG 2.1 accessibility compliance to iOS and Android platforms, allowing you to configure accessibility properties directly from UI Designer and ensuring your mobile applications are accessible to all users.
> >
> > > [tab] Key Features
> > >
> > > > [card] iOS accessibility
> > > >
> > > > Configure labels, hints, traits, and accessibility properties for iOS components
> > >
> > > > [card] Android accessibility
> > > >
> > > > Set content descriptions and accessibility properties for Android components
> > >
> > > > [card] Designer integration
> > > >
> > > > Configure all accessibility properties from UI Designer without code changes
> > >
> > > > [card] Platform-specific options
> > > >
> > > > Set platform-specific accessibility configurations for optimal native experience
> >
> > > [tab] Benefits
> > >
> > > > [card] Inclusive mobile apps
> > > >
> > > > Make your mobile applications accessible to users with disabilities
> > >
> > > > [card] Regulatory compliance
> > > >
> > > > Meet mobile accessibility requirements for government, healthcare, and financial sectors
> > >
> > > > [card] Better UX
> > > >
> > > > Accessibility improvements benefit all users, not just those using assistive technologies
> > >
> > > > [card] Unified configuration
> > > >
> > > > Configure accessibility for all platforms from a single Designer interface
> >
> > Accessibility
>
> ***
>
> ### **Cross workspace projects**
>
> > [card] Cross workspace projects
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 removes the restriction that prevented importing the same project into multiple workspaces within the same environment. This enables organizations to use workspaces to represent different upper environments (UAT, Staging) for testing and development.
> > >
> > > > [!NOTE]
> > > >
> > > > A single project (identified by its UUID) can now exist independently across workspaces, each with its own lifecycle: separate active policies, configurations, and access controls.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Environment testing restrictions
> > > >
> > > > Organizations could not use workspaces on the same FlowX deployment to represent different upper environments for testing (e.g. UAT, Staging)
> > >
> > > > [card] Operational costs
> > > >
> > > > This feature is intended to allow organizations to use workspace functionality to emulate different environments and reduce operational costs.
> >
> > > [tab] Solution
> > >
> > > **What Changed:**
> > >
> > > **1. Restriction removed**
> > >
> > > The system now allows importing the same project (identified by UUID) into multiple workspaces within the same environment
> > >
> > > **2. Independent lifecycles**
> > >
> > > Each project instance in different workspaces maintains its own independent lifecycle with separate active policies, configurations, and access controls
> > >
> > > **3. Workspace isolation**
> > >
> > > Changes in one workspace do not affect the same project in other workspaces, ensuring proper isolation
> >
> > > [tab] How It Works
> > >
> > > **Import Behavior:**
> > >
> > > | Aspect | Behavior |
> > > | - | - |
> > > | **Import** | Import a project build (and optionally a version) into a different workspace on the same environment |
> > > | **Active Policy** | The imported build is automatically set as the active policy, regardless of what was active in the original workspace |
> > > | **User Access** | Workspace users must be granted appropriate project rights (e.g., project viewer) to interact with the imported project |
> > > | **Process Instances** | Workspace-specific; imported projects start with no instances until processes run in the new workspace |
> > > | **Database** | Projects across workspaces on the same environment share the same database |
> > > | **No Impact on Original** | Import does not affect the original project's settings, policies, information, or process instances |
> > >
> > > > [!WARNING]
> > > >
> > > > Only the build itself is transferred during cross-workspace import. Configuration and access controls are defined separately in each workspace.
> >
> > > [tab] Benefits
> > >
> > > > [card] Flexible testing environments
> > > >
> > > > Use workspaces to represent UAT, Staging, and other test environments on the same deployment
> > >
> > > > [card] Reduced costs
> > > >
> > > > Eliminate the need for additional deployments and DevOps resources for environment management
> > >
> > > > [card] Better organization
> > > >
> > > > Organize projects and environments more efficiently with workspace-based separation
> > >
> > > > [card] Independent control
> > > >
> > > > Maintain separate policies and configurations for each workspace while using the same project
> > >
> > > > [card] Simplified operations
> > > >
> > > > Streamline deployment and environment management workflows
> > >
> > > > [card] Faster environment setup
> > > >
> > > > Quickly create new test environments by importing existing projects into new workspaces
> >
> > > [tab] Use Cases
> > >
> > > **Example Scenarios:**
> > >
> > > 1. **Multi-Environment Testing**: Import the same project into UAT and Staging workspaces, each with different test data and configurations
> > >
> > > 2. **Development Lifecycle**: Maintain development, integration, and pre-production environments as separate workspaces with the same project
> > >
> > > 3. **Parallel Testing**: Run multiple test scenarios simultaneously by creating separate workspaces for each testing team
> > >
> > > 4. **Isolated Training Environments**: Create dedicated workspaces for training and demos while keeping production separate
> >
> > > [card] [Workspaces Documentation](/5.1/docs/projects/workspaces#cross-workspace-project-import)
> > >
> > > Complete guide to cross-workspace project import, including import behavior and best practices.
> >
> > Reusability Enhancement
>
> ***
>
> ### **Collection and table actions**
>
> > [card] Collection and table actions
> >
> > FlowX.AI 5.3 enables executing actions directly from collection and table rows within UI Flows across Angular and React platforms, providing contextual user interactions within data-driven UI Flow components.
> >
> > > [card] Row-level actions
> > >
> > > Configure and trigger actions with row context for edit, delete, or start process operations in UI Flows
> >
> > > [card] Cross-platform support
> > >
> > > Works in both Angular and React web renderers for UI Flows
> >
> > UI Flows
>
> ***

> [tab] Integration & data
>
> Enhanced workflow integration, data model management, and backend performance improvements.
>
> 🔄 [**Data mappers for workflow integration**](#data-mappers-for-workflow-integration) - Data mappers for workflow integration\
> 🗄️ [**Workflow data model**](#workflow-data-model) - New CRUD endpoints and runtime data model access\
> 🤖 [**MCP Integration**](#mcp-integration) - Connect AI agents with external tools and services through Model Context Protocol servers\
> 🤖 [**Custom Agent Nodes**](#custom-agent-nodes) - Custom Agent nodes for AI agents to use external tools and services
> 📚 [**Knowledge Base**](#knowledge-base) - Create and manage Knowledge Bases for AI agents with document ingestion and semantic search\
> 🔧 [**Update process variables**](#update-process-variables) - Operations teams can modify process variables on active instances to resolve production issues\
> 🔍 [**Token view improvements**](#token-view-improvements) - Enhanced token hierarchy visibility with horizontal scrolling, frozen columns, and context-aware columns\
> 🛡️ [**Access management enhancements**](#access-management-enhancements) - New operations editor role and granular workspace permissions\
> ⚡ [**Performance & stability**](#performance-and-stability) - Backend optimizations, caching improvements, and infrastructure updates\
> 🔀 [**Exclusive Gateways**](#exclusive-gateways) - Expression testing and validation improvements
>
> ### **Data mappers for workflow integration**
>
> > [card] Data mappers for workflow integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces data mappers that enable integration between processes and Integration Designer workflows. Similar to Process Definitions, you can now define structured data models at the workflow level with input and output parameters, ensuring consistent data lineage across your integration architecture.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
> > >
> > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process-workflow.png)
> > >
> > > Map data bidirectionally between processes and workflows using data mappers
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow Data Models provide the same structured data management capabilities as Process Data Models, enabling declarative data mapping between workflows and processes with full type safety and validation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow data model
> > > >
> > > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > > [card] Input parameter management
> > > >
> > > > Input parameters automatically pre-fill Start Nodes with structured data from the workflow data model
> > >
> > > > [card] Data parameters
> > > >
> > > > Use data parameters to define input and output data subsets for workflow operations
> > >
> > > > [card] Process ↔ workflow mapping
> > > >
> > > > Create data mappers on nodes to receive outputs from workflows and map data bidirectionally
> > >
> > > > [card] Generic CRUD endpoints
> > > >
> > > > Manage data models, entities, attributes, and data parameters programmatically via REST APIs
> > >
> > > > [card] Unique node validation
> > > >
> > > > Automatic node name uniqueness validation within workflow definitions to ensure clear data lineage
> >
> > > [tab] How It Works
> > >
> > > **1. Define workflow data model**
> > >
> > > Create a data model for your workflow with entities and attributes, similar to Process Data Models. Define which parameters are inputs and outputs
> > >
> > > **2. Configure input parameters**
> > >
> > > Input parameters automatically pre-fill the Start Node when you open the workflow diagram or test at runtime. No manual JSON editing required
> > >
> > > **3. Map process to workflow**
> > >
> > > When invoking a workflow from a process, create data mappers to map process data to workflow input parameters
> > >
> > > **4. Map workflow to process**
> > >
> > > Configure output mappings on nodes to receive workflow results and map them back to process data
> >
> > > [tab] Data Model Management
> > >
> > > **New API Capabilities:**
> > >
> > > * **Data Model CRUD**: Create, read, update, and delete workflow data models
> > > * **Entity Management**: Add, modify, and remove entities within data models
> > > * **Attribute Management**: Define and manage attributes with types and validation rules
> > > * **Data Parameters Operations**: Create input and output data parameters for workflows
> > > * **Usage Tracking**: Query references and usages for attributes and entities
> > > * **Import/Export**: Export and import complete data models across environments
> > >
> > > **Technical Implementation:**
> > >
> > > * Centralized data model library for common classes and interfaces
> > > * Generic endpoints for data model and data parameters manipulation
> > > * Integration Designer communicates with Admin service for data model operations
> > > * Automatic input body computation based on data model input parameters
> > > * Runtime workflow start data endpoint for testing and execution
> >
> > > [tab] Limitations & Compatibility
> > >
> > > **Current Limitations:**
> > >
> > > * **Start Subworkflow Node**: Works as-is without data model integration in this release
> > > * **Endpoint Schemas**: Imported Swagger schemas are not yet integrated with workflow data models (planned for future release)
> > > * **Database Schemas**: Database operation schemas are not mapped to workflow variables yet (planned for future release)
> > >
> > > **Backwards Compatibility:**
> > >
> > > * Existing workflows continue to work without changes
> > > * End nodes from existing workflows can be renamed manually to align with output parameters
> > > * No breaking changes to current workflow execution
> > >
> > > **Node Naming:**
> > >
> > > * Node names must be unique within a workflow definition
> > > * System automatically validates uniqueness when renaming nodes
> > > * If duplicate names exist, an index is incremented (e.g., "Transform", "Transform\_2")
> >
> > > [tab] Benefits
> > >
> > > > [card] Consistent data lineage
> > > >
> > > > Ensure data consistency across processes and workflows with structured data models
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Input parameters automatically pre-fill Start Nodes - no manual JSON editing
> > >
> > > > [card] Type safety
> > > >
> > > > Define data types and validation rules at the workflow level for runtime safety
> > >
> > > > [card] Reusability
> > > >
> > > > Create reusable workflows with clear input/output contracts that can be invoked from multiple processes
> > >
> > > > [card] Better testing
> > > >
> > > > Test workflows with structured input data based on the data model
> > >
> > > > [card] Clear interfaces
> > > >
> > > > Workflow data models document the expected inputs and outputs for each workflow
> >
> > > [card] [Workflow Data Models Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> > >
> > > Complete guide to creating workflow data models, input/output parameters, process integration, and API reference.
> >
> > Integration Designer
>
> ***
>
> ### **Workflow data model**
>
> > [card] Workflow data model
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 adds comprehensive workflow data model management capabilities with new CRUD endpoints and runtime access to data model paths. This enables dynamic data model operations and better runtime introspection.
> >
> > > [tab] Key Features
> > >
> > > > [card] CRUD endpoints
> > > >
> > > > Create, read, update, and delete workflow data models programmatically via REST APIs
> > >
> > > > [card] Data model paths
> > > >
> > > > Runtime endpoint for retrieving workflow data model paths and structure information
> > >
> > > > [card] RUT instance mappings
> > > >
> > > > Enhanced /status and /details endpoints with mappings per workflow instance
> > >
> > > > [card] Runtime caching
> > > >
> > > > Improved caching for reusable templates to reduce latency and improve performance
> >
> > > [tab] Use Cases
> > >
> > > > [card] Dynamic forms
> > > >
> > > > Build dynamic forms based on data model structure at runtime
> > >
> > > > [card] Data migration
> > > >
> > > > Automate data model synchronization across environments
> > >
> > > > [card] Documentation
> > > >
> > > > Generate data model documentation automatically from API responses
> > >
> > > > [card] Validation
> > > >
> > > > Implement runtime validation based on data model definitions
> >
> > API Enhancement
>
> ***
>
> ### **MCP integration**
>
> > [card] MCP integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Model Context Protocol (MCP) integration, enabling AI agents to connect with external MCP servers and use their tools within Custom Agent nodes. MCP provides a standardized protocol for AI agents to access external tools, databases, APIs, and services.
> > >
> > > > [!NOTE]
> > > >
> > > > MCP integration extends AI agent capabilities by providing access to external tools through a standardized protocol. Configure MCP servers as data sources in Integration Designer and use their tools in workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] MCP data sources
> > > >
> > > > Add MCP servers as data sources in Integration Designer with base URL and authentication configuration
> > >
> > > > [card] Tool management
> > > >
> > > > View, enable, and turn off specific tools exposed by MCP servers directly from Integration Designer
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Select MCP servers in Custom Agent nodes to make their tools available to AI agents during workflow execution
> > >
> > > > [card] Authentication support
> > > >
> > > > Support for no authentication and OAuth 2.0 service account authentication methods
> > >
> > > > [card] Tool discovery
> > > >
> > > > Automatic tool discovery from MCP servers with schema information for inputs and outputs
> > >
> > > > [card] Execution monitoring
> > > >
> > > > Track tool usage and execution details in console logs for debugging and monitoring
> >
> > > [tab] How It Works
> > >
> > > **1. Add MCP server**
> > >
> > > Configure an MCP server as a data source in Integration Designer with base URL and authentication details
> > >
> > > **2. Authenticate connection**
> > >
> > > Set up authentication using no authentication (for development) or OAuth 2.0 service account (for production)
> > >
> > > **3. Discover tools**
> > >
> > > View available tools exposed by the MCP server with their input/output schemas
> > >
> > > **4. Enable tools**
> > >
> > > Enable or turn off specific tools based on your workflow requirements
> > >
> > > **5. Configure custom agent**
> > >
> > > Add a Custom Agent node to your workflow and select which MCP servers the agent can access
> > >
> > > **6. Execute workflow**
> > >
> > > AI agents can now use MCP tools during workflow execution to interact with external systems
> > >
> > > **7. Monitor execution**
> > >
> > > View tool usage and execution details in console logs for debugging and performance tracking
> >
> > > [tab] Authentication
> > >
> > > **Supported Authentication Methods:**
> > >
> > > **None**
> > >
> > > * No authentication required
> > > * Use for public MCP servers or development environments
> > > * Quick setup for testing and prototyping
> > >
> > > **Service Account (OAuth 2.0)**
> > >
> > > * OAuth 2.0 service account authentication
> > > * Required configuration:
> > >   * **Client ID**: OAuth client identifier
> > >   * **Client Secret**: OAuth client secret
> > >   * **Identity Provider URL**: Authorization server endpoint
> > > * Use for production environments
> > > * Secure access to MCP servers
> >
> > > [tab] Use Cases
> > >
> > > > [card] External API integration
> > > >
> > > > Connect AI agents to external APIs and services for data retrieval and action execution
> > >
> > > > [card] Database operations
> > > >
> > > > Query databases and perform data operations through MCP tools within AI workflows
> > >
> > > > [card] Custom business logic
> > > >
> > > > Expose custom business logic as MCP tools for AI agents to execute
> > >
> > > > [card] Multi-system orchestration
> > > >
> > > > Use multiple MCP servers in a single Custom Agent node to orchestrate operations across systems
> >
> > > [tab] Benefits
> > >
> > > > [card] Standardized integration
> > > >
> > > > Use a standardized protocol for AI agent tool integration across different systems
> > >
> > > > [card] Extended capabilities
> > > >
> > > > Extend AI agent capabilities with external tools without custom code
> > >
> > > > [card] Flexible tool management
> > > >
> > > > Enable or turn off specific tools per MCP server based on workflow needs
> > >
> > > > [card] Secure connections
> > > >
> > > > Support for OAuth 2.0 authentication ensures secure access to external services
> > >
> > > > [card] Tool reusability
> > > >
> > > > Configure MCP servers once and use their tools across multiple workflows and Custom Agent nodes
> > >
> > > > [card] Monitoring & debugging
> > > >
> > > > Console logs provide visibility into tool execution for troubleshooting and optimization
> >
> > > [card] [MCP Integration Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> > >
> > > Complete guide to MCP integration including data source configuration, tool management, and Custom Agent node usage.
> >
> > AI Integration
>
> ***
>
> ### **Custom Agent nodes**
>
> > [card] Custom Agent nodes
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Custom Agent nodes, enabling you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
> >
> > > [card] [Custom Agent Node Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > Complete guide to Custom Agent nodes, including configuration, usage, and best practices.
> >
> > AI Integration
>
> ***
>
> ### **Knowledge base**
>
> > [card] Knowledge base
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Knowledge Base integration, enabling you to create and manage centralized repositories of information that AI agents can query when preparing responses. Upload static documents or ingest dynamic data from workflows into Knowledge Bases that use vector embeddings and semantic search for intelligent information retrieval.
> > >
> > > > [!NOTE]
> > > >
> > > > Knowledge Bases enable AI agents to provide contextual, accurate responses based on your organization's documentation, policies, and dynamic data.
> >
> > > [tab] Key Features
> > >
> > > > [card] Document upload
> > > >
> > > > Upload PDF documents directly into Knowledge Bases for AI agent access
> > >
> > > > [card] Workflow ingestion
> > > >
> > > > Ingest data dynamically from workflows using Knowledge Base operations (Append, Replace, Delete)
> > >
> > > > [card] Semantic search
> > > >
> > > > AI agents find relevant information using natural language queries with vector embeddings
> > >
> > > > [card] Content sources
> > > >
> > > > Organize content across multiple sources within a Knowledge Base for better management
> > >
> > > > [card] Relevance scoring
> > > >
> > > > Configure minimum relevance thresholds (0-100%) to control response quality
> > >
> > > > [card] Testing capabilities
> > > >
> > > > Test queries and operations in isolation before adding them to production workflows
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Enable Knowledge Base queries in Custom Agent nodes with configurable parameters
> > >
> > > > [card] Content versioning
> > > >
> > > > Append, replace, or delete content sources with full traceability and state management
> >
> > > [tab] How It Works
> > >
> > > **1. Create Knowledge Base**
> > >
> > > Add a new Knowledge Base data source in Integration Designer
> > >
> > > **2. Ingest content**
> > >
> > > Upload PDF documents or ingest data from workflows into content sources
> > >
> > > **3. Automatic chunking**
> > >
> > > Content is automatically split into chunks and indexed in the vector database
> > >
> > > **4. Configure Custom Agent**
> > >
> > > Enable Knowledge Base in Custom Agent nodes and configure query parameters
> > >
> > > **5. Query execution**
> > >
> > > AI agents query the Knowledge Base using semantic search and receive relevant chunks
> > >
> > > **6. Response generation**
> > >
> > > Agents use retrieved chunks as context to generate accurate, informed responses
> >
> > > [tab] Workflow Operations
> > >
> > > **Knowledge Base operations available in workflows:**
> > >
> > > | Operation | Description |
> > > | - | - |
> > > | **Append** | Add new content to an existing content source without removing existing data |
> > > | **Replace** | Delete all existing content and replace with new content |
> > > | **Delete** | Remove all content from a content source |
> > >
> > > **Configuration Options:**
> > >
> > > * **Knowledge Base**: Select from local project libraries or dependencies
> > > * **Content Source**: Use existing sources, create new ones, or use workflow variables
> > > * **Content**: Static text, workflow variables, or configuration parameters
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product documentation assistant
> > > >
> > > > Create Knowledge Bases with product documentation for AI agents to answer customer questions
> > >
> > > > [card] Policy compliance
> > > >
> > > > Upload company policies so AI agents can reference them when processing requests
> > >
> > > > [card] Dynamic knowledge updates
> > > >
> > > > Ingest data from external systems through workflows to keep AI knowledge current
> > >
> > > > [card] Multi-source synthesis
> > > >
> > > > Organize information across sources and let AI agents synthesize comprehensive answers
> >
> > > [tab] Benefits
> > >
> > > > [card] Contextual AI responses
> > > >
> > > > AI agents provide accurate responses based on your organization's actual documentation
> > >
> > > > [card] Dynamic updates
> > > >
> > > > Keep AI knowledge current by ingesting data from workflows automatically
> > >
> > > > [card] Quality control
> > > >
> > > > Relevance scoring ensures only high-quality, relevant information is used
> > >
> > > > [card] Centralized management
> > > >
> > > > Manage all AI knowledge sources from a single location in Integration Designer
> > >
> > > > [card] No code integration
> > > >
> > > > Configure Knowledge Base queries directly in Custom Agent nodes without code
> > >
> > > > [card] Testable
> > > >
> > > > Test queries and see relevance scores before deploying to production
> >
> > > [tab] Limitations
> > >
> > > **Current Limitations:**
> > >
> > > > [!WARNING]
> > > >
> > > > * Only PDF documents are supported for manual upload (images, PPT, DOC, XLS support coming in future releases)
> > > > * Custom metadata cannot be defined (only system metadata is available)
> > > > * AI agents can only use one Knowledge Base per Custom Agent node
> > > > * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
> >
> > > [card] [Knowledge Base Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > Complete guide to creating Knowledge Bases, ingesting content, and using them in Custom Agent workflows.
> >
> > AI Integration
>
> ***
>
> ### **Update process variables**
>
> > [card] Update process variables
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces the ability for operations teams to modify process variables on active (Started or On Hold) process instances, providing critical tools to resolve production issues without process restarts. Edit, add, or delete attributes and objects directly using an editor with JSON validation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Formatting%20_%20Custom%20Date%20Format.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Tokens%20table.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > > [!NOTE]
> > > >
> > > > Updated values automatically sync to Task Manager and Elasticsearch, ensuring consistency across all systems. Previous values are saved in a snapshot table, and all modifications are tracked in the audit log for complete traceability.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Limited correction tools
> > > >
> > > > Operations teams had minimal tools to correct production issues at the process-instance level
> > >
> > > > [card] Blocked instances
> > > >
> > > > No way to unblock stuck process instances without backend intervention or process restarts
> > >
> > > > [card] Data correction challenges
> > > >
> > > > Incorrect process data required complex workarounds or manual database modifications
> > >
> > > > [card] Operational delays
> > > >
> > > > Production issues required developer intervention, increasing resolution time
> >
> > > [tab] Key Features
> > >
> > > > [card] Editor
> > > >
> > > > Edit process variables in a JSON editor with syntax validation and formatting
> > >
> > > > [card] Multiple entry points
> > > >
> > > > Access from Process Instances page contextual menu or Process Instance page secondary navigation
> > >
> > > > [card] Dual view modes
> > > >
> > > > Switch between Tree View (existing) and JSON View for variable visualization and editing
> > >
> > > > [card] Full CRUD operations
> > > >
> > > > Edit existing attribute values, add new attributes/objects, or delete existing attributes/objects
> > >
> > > > [card] JSON validation
> > > >
> > > > Automatic JSON format validation before saving to ensure data integrity
> > >
> > > > [card] Snapshot history
> > > >
> > > > Previous process variables are saved in a new snapshot table before changes are applied
> > >
> > > > [card] Auto-sync to Task Manager
> > > >
> > > > Updated variables automatically sync to Task Manager using existing mechanism
> > >
> > > > [card] Elasticsearch integration
> > > >
> > > > Process variables configured for data search are automatically updated in Elasticsearch
> > >
> > > > [card] Permission-based access
> > > >
> > > > Role-based access control with process\_variables\_edit permission ensures only authorized users can modify variables
> > >
> > > > [card] Export functionality
> > > >
> > > > Export button available near the view dropdown for downloading process variables
> > >
> > > **Iteration 2 - Enhanced Review:**
> > >
> > > > [card] Compare feature
> > > >
> > > > Ability to review updated process variables through a compare feature, showing before/after values for better visibility and validation
> >
> > > [tab] How It Works
> > >
> > > **Accessing the Feature:**
> > >
> > > You can access the edit functionality from two entry points:
> > >
> > > 1. **Process Instances Page**: Use contextual menu on a process instance row → navigates to Process Instance page and opens Variables tab in edit mode
> > > 2. **Process Instance Page**: Use contextual menu in secondary navigation → opens Variables tab in edit mode
> > >
> > > **Editing Process Variables:**
> > >
> > > **1. Select active instance**
> > >
> > > Choose an active process instance (Started or On Hold status) that requires variable modification
> > >
> > > **2. Switch to JSON view**
> > >
> > > In the Variables tab, switch from Tree View to JSON View using the view dropdown
> > >
> > > **3. Click edit**
> > >
> > > Click the Edit button (visible only if you have process\_variables\_edit permission)
> > >
> > > **4. Modify in editor**
> > >
> > > Edit process variables in the JSON editor - you can edit existing values, add new attributes/objects, or delete existing ones
> > >
> > > **5. Validate JSON**
> > >
> > > Ensure your JSON format is valid before saving - the editor will highlight syntax errors
> > >
> > > **6. Save changes**
> > >
> > > Click Save to apply changes - a snapshot of previous values is automatically created
> > >
> > > **7. Auto-sync**
> > >
> > > System automatically syncs updated variables to Task Manager and Elasticsearch (for variables configured for data search)
> > >
> > > **8. Review audit log**
> > >
> > > Check the Audit Log tab to confirm the modification was recorded with all details
> >
> > > [tab] Permissions & Security
> > >
> > > **Permission Requirements:**
> > >
> > > * **New Permission**: `process_variables_edit` available at workspace level
> > > * **Default Roles**: Added to `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, and `workspace_operations_editor` roles
> > > * **New Role**: `workspace_operations_editor` - A dedicated workspace role for operations management including process variable editing and operations (migration & move token)
> > >
> > > **Access Control:**
> > >
> > > * Edit option in UI is only visible to users with `process_variables_edit` permission
> > > * Save functionality is restricted to users with the required permission
> > > * Unauthorized users can view process variables but cannot modify them
> > >
> > > **Audit Logging:**
> > >
> > > Every process variable modification creates an audit log entry with:
> > >
> > > * Workspace ID
> > > * Feature: Process variables
> > > * Section: Process Instance
> > > * Application UUID and name
> > > * Subject: Process variables
> > > * Event: Edit
> > > * Subject Identifier: Process instance UUID
> > > * Body: JSON with new version of process parameters
> > >
> > > Audit logs are displayed in the Audit Log tab within the process instance for easy tracking.
> >
> > > [tab] Data Synchronization
> > >
> > > **What Gets Updated:**
> > >
> > > > [card] Task Manager
> > > >
> > > > Variables are automatically updated in Task Manager using existing mechanisms - ensures task keywords and data remain consistent
> > >
> > > > [card] Elasticsearch
> > > >
> > > > Variables configured for data search are automatically updated in Elasticsearch - maintains search accuracy
> > >
> > > > [card] Process instance params
> > > >
> > > > Primary process instance parameters are updated immediately in the database
> > >
> > > > [card] Snapshot table
> > > >
> > > > Previous values are saved in a new snapshot table before changes are applied
> > >
> > > **What Does NOT Get Updated:**
> > >
> > > > [card] Process snapshots
> > > >
> > > > Process instance snapshots (used for back navigation/reset) are not updated - maintains historical integrity
> > >
> > > > [card] Debug table
> > > >
> > > > Process instance debug records remain unchanged - preserves execution history
> > >
> > > > [card] Existing audit logs
> > > >
> > > > Previously recorded audit logs (manual actions, integrations) are not modified - maintains compliance trail
> > >
> > > > [card] Subprocess variables
> > > >
> > > > Child subprocess variables are not automatically updated - parent changes don't cascade to children
> >
> > > [tab] Important Considerations
> > >
> > > **Limitations & Best Practices:**
> > >
> > > > [!WARNING]
> > > >
> > > > **Subprocess Impact**: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.
> > >
> > > > [!WARNING]
> > > >
> > > > **Back Navigation**: 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.
> > >
> > > > [!WARNING]
> > > >
> > > > **Integration Messages**: 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.
> > >
> > > **Best Practices:**
> > >
> > > * **Verify JSON Format**: Always ensure valid JSON before saving to prevent data corruption
> > > * **Document Changes**: Use audit logs to track all modifications and maintain operational documentation
> > > * **Test in Lower Environments**: When possible, test variable modifications in staging before production
> > > * **Understand Dependencies**: Review process flow and subprocess relationships before modifying variables
> > > * **Consider Timing**: Best used for stuck processes or data corrections, not for regular operational changes
> > > * **Check Search Data**: If variables are used in data search, verify Elasticsearch sync completed successfully
> >
> > > [tab] Benefits
> > >
> > > > [card] Faster issue resolution
> > > >
> > > > Operations teams can resolve production issues immediately without developer intervention
> > >
> > > > [card] Reduced downtime
> > > >
> > > > Unblock stuck instances quickly, minimizing impact on end users and business processes
> > >
> > > > [card] Operational independence
> > > >
> > > > Empower ops teams with self-service tools for process-instance management
> > >
> > > > [card] Data consistency
> > > >
> > > > Automatic sync ensures Task Manager and Elasticsearch reflect updated values
> > >
> > > > [card] Full traceability
> > > >
> > > > Snapshots and audit logs provide complete history of all modifications for compliance
> > >
> > > > [card] Reduced risk
> > > >
> > > > Permission-based access and comprehensive audit trail reduce risk of unauthorized changes
> > >
> > > > [card] Flexible editing
> > > >
> > > > The JSON editor provides powerful JSON editing capabilities with validation
> > >
> > > > [card] Historical preservation
> > > >
> > > > Original values preserved in snapshot table for rollback scenarios
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Correct User Input Errors**
> > >
> > > * Customer submitted incorrect data in a loan application (wrong income, invalid address)
> > > * Operations team edits the variables to correct the information
> > > * Process continues without requiring customer to restart the application
> > >
> > > **2. Unblock Stuck Process Instances**
> > >
> > > * Process is waiting for external data that will never arrive (integration timeout, external system down)
> > > * Ops team updates the variable to provide expected data or skip the condition
> > > * Instance is unblocked and continues execution
> > >
> > > **3. Fix Integration Data Issues**
> > >
> > > * External system returned incorrect or incomplete data
> > > * Operations team corrects process variables to match expected values
> > > * Process continues with accurate data without re-calling the integration
> > >
> > > **4. Emergency Data Updates**
> > >
> > > * Critical business information changed after process started (regulatory update, pricing change)
> > > * Ops team modifies variables to reflect current information
> > > * Process continues with updated data without restart
> > >
> > > **5. Add Missing Attributes**
> > >
> > > * Process needs additional data that wasn't collected at start
> > > * Operations team adds new attributes or objects to process variables
> > > * Process can now access the required information
> > >
> > > **6. Remove Invalid Data**
> > >
> > > * Process contains incorrect or test data that shouldn't be there
> > > * Ops team deletes the problematic attributes or objects
> > > * Process continues with clean, valid data only
> > >
> > > **7. Update Task Manager Keywords**
> > >
> > > * Task search keywords need updating based on corrected data
> > > * Variables are modified and automatically synced to Task Manager
> > > * Tasks become searchable with correct keywords
> > >
> > > **8. Fix Elasticsearch Search Data**
> > >
> > > * Process data indexed for search contains errors
> > >
> > > * Operations team corrects variables configured for data search
> > >
> > > * Elasticsearch automatically updates, ensuring accurate search results
> > >
> > > > [!NOTE]
> > > >
> > > > This capability, combined with the upcoming Move Token feature, provides comprehensive process-instance management tools for operations teams.
> >
> > > [card] [Update Process Variables Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > >
> > > Complete guide including step-by-step instructions, permissions, data synchronization, best practices, and troubleshooting.
> >
> > Operations Enhancement
>
> ***
>
> ### **Token view improvements**
>
> > [card] Token view improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the **Tokens tab** in the **Process Instance View** with improved visibility and comprehension of token hierarchy and context. The enhanced token view introduces horizontal scrolling, frozen columns, hierarchical nesting, and new context-related columns to provide better insights into process execution.
> > >
> > > > [!NOTE]
> > > >
> > > > These improvements make it easier to understand complex process flows with parallel gateways, embedded subprocesses, and boundary events by clearly displaying token relationships and execution context.
> >
> > > [tab] Key Features
> > >
> > > > [card] Horizontal scrolling
> > > >
> > > > The table supports horizontal scrolling to accommodate all columns, ensuring all token information remains accessible
> > >
> > > > [card] Frozen columns
> > > >
> > > > Token UUID and Actions columns remain fixed during horizontal scroll for constant visibility of key identifiers and actions
> > >
> > > > [card] Hierarchical nesting
> > > >
> > > > Tokens display in a tree structure with nested child tokens under parent tokens, showing clear parent-child relationships
> > >
> > > > [card] Auto-expanded rows
> > > >
> > > > All token rows are expanded by default, providing immediate visibility into the complete token hierarchy
> > >
> > > > [card] Dynamic indentation
> > > >
> > > > Indentation dynamically adjusts based on nesting depth, visually representing token relationships
> > >
> > > > [card] Context column
> > > >
> > > > New Context column displays subprocess names for tokens running within embedded subprocesses, or main process name for main process tokens
> > >
> > > > [card] Initiator node column
> > > >
> > > > New Initiator Node column shows the node name that generated the token (e.g., Parallel Gateway, Non-interrupting boundary event)
> > >
> > > > [card] First executed node column
> > > >
> > > > New First Executed Node column displays the first node executed after token generation
> > >
> > > > [card] UUID copy functionality
> > > >
> > > > Token UUID displays first 6 characters with a copy icon; clicking copies the full UUID to clipboard with success notification
> > >
> > > > [card] Color-coded status tags
> > > >
> > > > Token Status column uses color-coded tags for quick visual identification of token lifecycle states
> > >
> > > > [card] Tooltip support
> > > >
> > > > Long node names are truncated with tooltips showing full text on hover for better readability
> > >
> > > > [card] Timezone-aware timestamps
> > > >
> > > > Last Updated column displays full datetime in browser timezone for accurate local time representation
> >
> > > [tab] Table Columns
> > >
> > > The enhanced token view includes the following columns:
> > >
> > > | Column | Description | Special Behavior |
> > > | - | - | - |
> > > | **Token UUID** | Unique identifier of the token | Only first 6 characters displayed. Copy icon appears beside UUID. Clicking copies full UUID to clipboard with success toast: "Full Token UUID copied to clipboard." **Frozen column** (stays visible during horizontal scroll) |
> > > | **Context** | Displays contextual data for token | Shows main process name for tokens in main process. Shows embedded subprocess name for tokens in embedded subprocesses (any nesting level) |
> > > | **Initiator Node** | Shows the node name that generated the token | Applies to child tokens only. For parent tokens, displays "-". Examples: Parallel Gateway name, Non-interrupting boundary event name |
> > > | **First Executed Node** | Displays the first node executed after token generation | For parallel gateway tokens: first executed node on that parallel branch. For boundary event tokens: first executed node on branch started from boundary node. If first node is embedded subprocess, displays embedded subprocess name |
> > > | **Current Node** | Displays the last node executed within the token branch | For parallel gateway tokens: last node on branch. For boundary event tokens: last node executed on branch triggered by boundary. For tokens in embedded subprocess: displays current node from subprocess |
> > > | **Current Node Status** | Shows the current execution status | Examples: WAITING\_TIMER\_EVENT, ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL. Sortable column |
> > > | **Token Status** | Indicates lifecycle state | Values: ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, TERMINATED. **Color-coded tags** for visual identification |
> > > | **Last Updated** | Timestamp of latest token state change | Displays full datetime in browser timezone |
> > > | **Actions** | Available actions for the token | Includes Retry token and View (eye icon) actions. **Frozen column** (stays visible during horizontal scroll). Retry button only visible for ACTIVE tokens |
> >
> > > [tab] Nesting Behavior
> > >
> > > **Token Hierarchy Display:**
> > >
> > > **1. Parent-child relationships**
> > >
> > > Tokens created by parallel gateways or embedded subprocesses are displayed as nested child tokens under their parent tokens
> > >
> > > **2. Default expansion**
> > >
> > > All token rows are expanded by default, showing the complete token hierarchy immediately
> > >
> > > **3. Dynamic indentation**
> > >
> > > Indentation adjusts automatically based on nesting depth, with columns expanding accordingly to maintain alignment
> > >
> > > **4. Visual hierarchy**
> > >
> > > The tree structure makes it easy to identify which tokens belong to which parallel branch or subprocess
> > >
> > > **Initiator Node Logic:**
> > >
> > > * **Parent tokens**: Display "-" in Initiator Node column
> > > * **Child tokens from parallel gateway**: Display the parallel gateway node name
> > > * **Child tokens from boundary event**: Display the boundary event node name
> > > * **Child tokens from back in steps**: Display appropriate initiator information
> >
> > > [tab] Benefits
> > >
> > > > [card] Better visibility
> > > >
> > > > Horizontal scrolling and frozen columns ensure all token information remains accessible regardless of table width
> > >
> > > > [card] Clear hierarchy
> > > >
> > > > Hierarchical nesting with dynamic indentation makes parent-child token relationships immediately clear
> > >
> > > > [card] Context awareness
> > > >
> > > > Context column provides immediate visibility into which subprocess a token is executing within
> > >
> > > > [card] Execution tracking
> > > >
> > > > Initiator Node and First Executed Node columns help track token origin and execution path
> > >
> > > > [card] Quick actions
> > > >
> > > > Frozen Actions column ensures retry and view actions are always accessible without scrolling
> > >
> > > > [card] Easy UUID access
> > > >
> > > > Quick copy functionality for full UUIDs without needing to view token details
> > >
> > > > [card] Visual status identification
> > > >
> > > > Color-coded status tags enable quick identification of token states at a glance
> > >
> > > > [card] Improved readability
> > > >
> > > > Tooltips for truncated names and timezone-aware timestamps improve overall readability
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Parallel Gateway Debugging**
> > >
> > > * View all parallel branches simultaneously with clear parent-child relationships
> > > * Identify which branch each token belongs to through hierarchical nesting
> > > * Track execution progress across multiple parallel paths
> > >
> > > **2. Embedded Subprocess Analysis**
> > >
> > > * Context column immediately shows which subprocess tokens are executing within
> > > * Understand nested subprocess relationships through indentation
> > > * Track token flow across multiple subprocess levels
> > >
> > > **3. Boundary Event Monitoring**
> > >
> > > * Initiator Node column shows which boundary event triggered each token
> > > * First Executed Node shows the execution path started by boundary events
> > > * Monitor non-interrupting boundary event token execution
> > >
> > > **4. Process Instance Troubleshooting**
> > >
> > > * Frozen UUID column ensures token identification is always visible
> > > * Copy UUID functionality enables quick token reference in support tickets
> > > * Color-coded status tags help identify problematic tokens quickly
> > >
> > > **5. Multi-Level Process Analysis**
> > >
> > > * Hierarchical view supports complex processes with multiple nesting levels
> > > * Dynamic indentation adapts to any nesting depth
> > > * All tokens visible by default without manual expansion
> >
> > > [card] [Token Documentation](/5.1/docs/building-blocks/token)
> > >
> > > Complete guide to tokens, including token status values, current node status, and detailed token status view.
> >
> > UX Enhancement
>
> ***
>
> ### **Access management enhancements**
>
> > [card] Access management enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces new workspace-level permissions and a dedicated operations editor role, providing more granular control over process instance management and operations.
> > >
> > > > [!NOTE]
> > > >
> > > > These enhancements enable organizations to delegate operational tasks to dedicated teams without granting full runtime or admin access.
> >
> > > [tab] New Role
> > >
> > > **workspace\_operations\_editor**
> > >
> > > A new predefined workspace role designed for operations teams who need to manage process instances without requiring full runtime or admin capabilities.
> > >
> > > > [card] Operations management
> > > >
> > > > Full CRUD access for process instance operations including migration and move token functionality
> > >
> > > > [card] Process variables
> > > >
> > > > Edit permission for process variables on active instances across the workspace
> > >
> > > > [card] Process instances
> > > >
> > > > Read and edit access to all process instances in the workspace
> > >
> > > > [card] Workspace user inheritance
> > > >
> > > > Inherits all base permissions from workspace\_user role including project creation
> > >
> > > **Role Constraints:**
> > >
> > > * Cannot be edited or deleted (predefined role)
> > > * Extends workspace\_user with operations-specific permissions
> > > * Does not include broader runtime capabilities (builds, policies, scheduled processes)
> > >
> > > **Use Cases:**
> > >
> > > * Support engineers managing process migrations
> > > * Operations teams handling token movements
> > > * Technical support staff editing process variables
> >
> > > [tab] New Permissions
> > >
> > > **Workspace-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **Operations** (Read/Edit/Create/Delete) | Manage process instance operations including migration and move token | `org_admin`, `workspace_admin`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Operations** (Read/Create only) | Create operations and view all operations | `workspace_user` |
> > > | **Process Variables** (Edit) | Edit process variables on active instances | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Process Instances** (Edit) | Edit process instance data | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > >
> > > **Project-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **UI Flows** (Read/Edit/Create/Delete) | Full access to create and manage UI Flows | `project_owner`, `project_editor` |
> > > | **UI Flows** (Read only) | View UI Flows definitions | `project_viewer` |
> >
> > > [tab] Benefits
> > >
> > > > [card] Principle of least privilege
> > > >
> > > > Grant only the permissions needed for specific operational tasks
> > >
> > > > [card] Dedicated operations teams
> > > >
> > > > Enable operations teams to work independently without full admin access
> > >
> > > > [card] Clear separation of concerns
> > > >
> > > > Distinguish between runtime management (builds, policies) and operations management (migrations, variables)
> > >
> > > > [card] Flexible role combinations
> > > >
> > > > Combine with other workspace roles for customized access patterns
> >
> > > [card] [Access Management Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix)
> > >
> > > Complete permissions matrix and role specifications for all FlowX roles.
> >
> > Access Management
>
> ***
>
> ### **Performance and stability**
>
> > [card] Performance and stability
> >
> > FlowX.AI 5.3 includes platform improvements focused on performance, reliability, and operational excellence.
> >
> > ## Backend optimizations
> >
> > > [card] Optimistic lock improvements
> > >
> > > Replace retry pattern with capped exponential backoff and infinite retries for better concurrency handling
> >
> > > [card] Events gateway optimization
> > >
> > > Update Redis read mode to XREAD BLOCK for more efficient event streaming
> >
> > > [card] Database performance
> > >
> > > Remove unnecessary index on token\_instance.current\_node\_id to improve update performance
> >
> > > [card] Template caching
> > >
> > > Enhanced caching for reusable templates at runtime reduces latency and improves throughput
> >
> > ## Infrastructure updates
> >
> > > [card] Connector Topic Pattern
> > >
> > > Added dedicated KAFKA\_CONNECTORS\_TOPIC\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [card] SpiceDB backup
> > >
> > > Documented backup and restore procedures for SpiceDB for disaster recovery
> >
> > > [card] Observability
> > >
> > > Publish Prometheus and OpenTelemetry Helm charts and container images to Harbor
> >
> > > [card] Security updates
> > >
> > > Fix HIGH vulnerabilities in Designer 5.1.x and main branch
> >
> > > [card] Renderer improvements
> > >
> > > Enhanced Angular renderer with action form submit functionality and substitution tag support
> >
> > Platform Updates
>
> ***
>
> ### **Exclusive gateways**
>
> > [card] Exclusive gateways
> >
> > FlowX.AI 5.3 enhances Exclusive Gateway configuration with expression testing capabilities and improved validation.
> >
> > > [card] Expression testing
> > >
> > > Test gateway expressions directly from the configuration panel with real-time validation
> >
> > > [card] Committed version testing
> > >
> > > Test business rules and gateway expressions in committed versions
> >
> > > [card] Code editor integration
> > >
> > > Enhanced code editor with syntax highlighting for complex expressions
> >
> > > [card] Payload synchronization
> > >
> > > Test payloads automatically update when rules are saved
> >
> > Process Logic
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes and stability improvements across Designer, renderers, backend services, and data management.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI Designer and Integration Designer stability improvements\
> 🖥️ [**Renderer Fixes**](#renderer-fixes) - Cross-platform renderer bug fixes for web, iOS, and Android\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements\
> 🗄️ [**Data & Integration Fixes**](#data-and-integration-fixes) - Data mapper and workflow integration fixes
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.3 resolves numerous Designer issues to improve stability and user experience.
> >
> > ## UI designer improvements
> >
> > > [accordion] Configuration & styling
> > >
> > > * **Fixed styles not applied after undo/redo** in Reusable UI Template config panel
> > > * **Fixed UI blocking** when slider min value exceeds max value
> > > * **Fixed warning icon display** in config panel
> > > * **Fixed expression test modal styles** when opened in resized screen
> > > * **Fixed UI action section refresh** when selecting different UI template
> > > * **Fixed UI action section rendering** after clicking 'Add new ui action'
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed loading spinner toggle** not available for Overlay loading behavior
> > > * **Fixed incomplete loading behavior dropdown**
> > > * **Fixed default messages** not displayed after undo
> > > * **Fixed forms in collections handling** for patch actions requests
> >
> > > [accordion] UI Flows designer
> > >
> > > * **Fixed task management error state** when view is selected
> > > * **Fixed tab content preview** showing content from 2 tabs when adding new tab
> >
> > > [accordion] Output parameters
> > >
> > > * **Fixed currency key management** - can now add/remove currency key in output params
> >
> > > [accordion] Exclusive Gateways
> > >
> > > * **Fixed gateway decisions** can now be modified after initial save
> > > * **Fixed test payload** updates when rules are saved
> > > * **Fixed expression propagation** to test modal
> >
> > ## Frontend runtime fixes
> >
> > > [accordion] Process management
> > >
> > > * **Fixed context column** showing empty value for tokens in embedded subprocesses
> > > * **Fixed process params update** from running process instance modal
> > > * **Fixed long node names** overlapping adjacent columns in Tokens table
> > > * **Fixed workspace redirect** on page refresh
> >
> > > [accordion] Audit & logging
> > >
> > > * **Fixed audit log subject value** not displayed for process params updates
> > > * **Fixed toast error messages** to use text from backend request
> > > * **Added documentation link** to Modify Variables modal info text
> >
> > Designer Stability
>
> ***
>
> ### **Renderer fixes**
>
> > [card] Renderer fixes
> >
> > FlowX.AI 5.3 includes comprehensive renderer fixes across all platforms.
> >
> > ## Web renderers (Angular & React)
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed theming** not applied to general loader
> > > * **Fixed theming** not applied to toast messages
> > > * **Fixed dynamic key values** not displayed in toast/loading messages
> > > * **Fixed success toast** displayed when flag is false
> >
> > > [accordion] Card & navigation
> > >
> > > * **Fixed card not expandable** after finishing subprocess started from it (Angular & React)
> > > * **Fixed card collapse** when next nav area is modal (Angular & React)
> > > * **Fixed subprocess navigation** closing parent process navigation with multiple hierarchies
> >
> > > [accordion] UI events
> > >
> > > * **Fixed UI event triggering** without user interaction (Angular)
> >
> > > [accordion] Call activity
> > >
> > > * **Fixed call activity UT rendering** when started from embedded process
> >
> > > [accordion] Collections & forms
> > >
> > > * **Fixed button with forms to submit** no longer disabled until template edited (Angular & React)
> > > * **Fixed multi-select search** filtering (React)
> > > * **Fixed JSON generation** with special characters in CollectionsV2
> >
> > ## Mobile renderers
> >
> > > [accordion] Android
> > >
> > > * **Fixed SSE Event & UI Event** - UI event value displayed instead of SSE value
> >
> > Renderer Stability
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process management
> >
> > > [accordion] Process & build issues
> > >
> > > * **Fixed processes not displayed** in container app list for imported builds
> > > * **Fixed token state** changing from Aborted to Active during back navigation
> > > * **Fixed audit logs** for override operations after merge
> >
> > > [accordion] Performance
> > >
> > > * **Fixed /details endpoint** returning cache error for processes with many components
> >
> > > [accordion] Process engine
> > >
> > > * **Fixed token stuck** in receive node when message received after advancing
> > > * **Fixed action params** copied correctly for child actions when copying node
> > > * **Fixed metadata preservation** when importing process
> >
> > ## Security & configuration
> >
> > > [accordion] Authentication
> > >
> > > * **Fixed service account client secret** configuration parameter in Authorization service
> >
> > ## Data management
> >
> > > [accordion] Runtime issues
> > >
> > > * **Fixed FlowxProps.events** mapping at runtime for array of objects
> >
> > ## Infrastructure
> >
> > > [accordion] Database & events
> > >
> > > * **Fixed advancing errors** in partition event table
> > > * **Fixed Liquibase logging** when crashing due to lock
> >
> > Backend Stability
>
> ***
>
> ### **Data and integration fixes**
>
> > [card] Data and integration fixes
> >
> > Fixes for data mappers and workflow integration features.
> >
> > ## Data mapper issues
> >
> > > [accordion] Mapping operations
> > >
> > > * **Fixed 400 error** when saving mappings
> > > * **Fixed error** when saving mapping with empty parameters
> > > * **Fixed unsaved mapping modal** displayed when saving action
> > > * **Fixed array mapping** - arrays in mapper functions now work correctly
> > > * **Fixed slice deletion** when updating PDM objects
> >
> > > [accordion] Data streams & workflows
> > >
> > > * **Fixed data stream availability** for older exports during import
> > > * **Fixed workflow data stream** data appending issue
> > > * **Fixed legacy mapping** toggle now triggers correctly for call activity
> >
> > > [accordion] UI updates
> > >
> > > * **Fixed start node** not updated in UI after parameters update until refresh
> > > * **Fixed manifest resource** not found after switching versions
> >
> > > [!NOTE]
> > >
> > > Data mapper fixes ensure reliable workflow integration and process-to-workflow data synchronization.
> >
> > Integration Stability
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.3.0](./deployment-guidelines-v5.3).
>
> ### Environment variable updates
>
> > [!NOTE]
> >
> > For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.
>
> ### Breaking changes
>
> > [!WARNING]
> >
> > **FlowX Engine Configuration**: v5.3.0 includes a breaking change to the partitioning and archiving configuration structure. If you have enabled data partitioning, you must update your configuration files.
>
> > [card] [Migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
> >
> > Complete migration guide with step-by-step instructions, configuration examples, and troubleshooting
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.2.0 requires configuration changes for FlowX Engine partitioning/archiving
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.3


# Deployment guidelines v5.4.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/deployment-guidelines-v5.4

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.38.0** | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **10.38.0** | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **10.22.0** | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **10.15.0** | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **10.17.0** | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **10.22.0** | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **10.23.0** | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **10.25.0** | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **10.14.0** | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **10.21.0** | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **10.16.0** | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **10.38.0** | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **10.20.1** | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **10.28.0** | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **10.17.0** | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **email-gateway** | **10.9.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 |

### AI Platform

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.4.0 | Keycloak | 26+ |
| 5.4.0 | Kafka | 3.8 - 3.9 |
| 5.4.0 | PostgreSQL | 16 - 17 |
| 5.4.0 | Oracle Database | 21c, 23ai |
| 5.4.0 | MongoDB | 7 - 8 |
| 5.4.0 | Redis | 7.4 - 8.0 |
| 5.4.0 | Elasticsearch | 8 |
| 5.4.0 | Angular (Web SDK) | 20 |
| 5.4.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.4.0

### Key features and updates

> [card] Email Trigger
>
> Start processes automatically from incoming emails with configurable validation rules

> [card] MCP Server Improvements
>
> Enhanced audit logging, resource management, and tool refresh capabilities

> [card] Email Gateway
>
> New microservice for handling email communication workflows

## Upgrading from v5.3.0

### Breaking changes

> [!NOTE]
>
> FlowX.AI 5.4.0 does not introduce breaking changes for standard deployments. Upgrades from v5.3.0 should be straightforward.

### New environment variables

The following new environment variables have been introduced:

| Variable | Service | Description |
| - | - | - |
| `KAFKA_CONNECTORS_TOPIC_PATTERN` | process-engine | Dedicated Kafka topic pattern for connectors (optional, falls back to `KAFKA_TOPIC_PATTERN` if not set) |
| `KAFKA_BOOTSTRAP_SERVERS` | All services | Standardized Kafka bootstrap servers property (preferred over `SPRING_KAFKA_BOOTSTRAPSERVERS`, backwards compatible) |
| `KAFKA_SECURITY_PROTOCOL` | All services | Standardized Kafka security protocol property (preferred over `SPRING_KAFKA_SECURITY_PROTOCOL`, backwards compatible) |

### Key changes

* **Email Trigger**: New capability to start processes from email events
* **Connector Topics**: New dedicated topic pattern variable for connectors
* **Kafka Configuration**: Standardized Kafka property names (`KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_SECURITY_PROTOCOL`) aligned across all services with backwards compatibility
* **Email Gateway**: New microservice for email communication workflows

### New microservice: Email Gateway

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces a new optional microservice: **Email Gateway**. This service handles email communication workflows within the platform.

The Email Gateway requires the following infrastructure:

| Component | Requirement |
| - | - |
| PostgreSQL | Dedicated database named `email_gateway` |
| MongoDB | Connection to existing `app-runtime` database |
| Kafka | Access to the FlowX Kafka cluster |
| Redis | Shared Redis instance |
| Keycloak | Service account for authentication |

> [!NOTE]
>
> The Email Gateway operates as an internal service and does not require ingress configuration.

> [card] [Email Gateway Setup Guide](/5.9/setup-guides/email-gateway-setup)
>
> Complete setup instructions including Helm values, environment variables, and troubleshooting.

### Compatibility

* **No Breaking Changes**: Standard deployments can upgrade without configuration changes
* **Feature Additions**: SaaS features require additional infrastructure configuration for production use
* **Renderer Updates**: Web and mobile SDKs include bug fixes with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.4.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026

SaaS multi-tenant platform capabilities, database tenant isolation, email-triggered processes, MCP server enhancements, and backend performance improvements.

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces foundational support for a multi-tenant platform, enabling organization management and improved tenant isolation in the SaaS deployment model.

> [!NOTE]
>
> **Deployment models** - Starting with v5.4.0, FlowX.AI is available in two deployment models:
>
> * **Self-Managed** (On-Premises / Customer Cloud)
> * **FlowX SaaS** (FlowX-hosted)
>
> **Feature availability badges:**
>
> * SaaS Features exclusive to FlowX SaaS deployments
> * Self-Managed Features specific to self-managed deployments
> * All Deployments Features available in both deployment models

**What's new?**

> [tab] SaaS & multi-tenancy
>
> > [!NOTE]
> >
> > The features described in this section apply to **FlowX SaaS deployments**.\
> > Self-managed deployments are not affected unless explicitly stated.
>
> FlowX.AI 5.4.0 introduces initial SaaS capabilities enabling multi-tenant deployments with organization management and tenant isolation.
>
> 🏢 [**SaaS Multi-Tenancy**](#saas-multi-tenancy) - Multi-tenant platform with organization isolation and provisioning
>
> ### **SaaS multi-tenancy**
>
> > [card] SaaS multi-tenancy
> >
> > Multi-tenant SaaS capabilities enable multiple organizations to operate independently on shared infrastructure. Each organization receives dedicated resources while maintaining complete isolation from other tenants.
> >
> > > [card] Multi-tenant architecture
> > >
> > > Multiple organizations operate on shared infrastructure with complete isolation
> >
> > > [card] Tenant isolation
> > >
> > > Complete data and authentication isolation between organizations
> >
> > > [card] Organization provisioning
> > >
> > > Automatic provisioning of dedicated resources for each organization
> >
> > > [card] Resource management
> > >
> > > Each organization receives dedicated resources and project spaces
> >
> > > [card] [Documentation](/5.9/docs/saas/saas-overview)
> > >
> > > See the complete FlowX SaaS documentation for guides and best practices.
> >
> > Major FeatureSaaS
>
> ***

> [tab] AI & Integration
>
> Enhanced MCP server management.
>
> 📧 [**Email Trigger**](#email-trigger) - Start processes from external email events with configurable validation rules\
> 💬 [**Chat Component**](#chat-component) - Standalone chat tab for AI-powered conversational interfaces\
> 🔧 [**MCP Server Improvements**](#mcp-server-improvements) - Enhanced audit logging, resource management, and tool updates
>
> ### **Email trigger**
>
> > [card] Email trigger
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces Email Trigger as a new Data Source type in Integration Designer, enabling processes to be started automatically when emails are received. Connect to IMAP mail servers, monitor specific mailboxes, and create process instances with the email data.
> > >
> > > > [!NOTE]
> > > >
> > > > Email Triggers bridge external communication channels with FlowX.AI process automation, enabling organizations to automatically route and process incoming emails through defined business workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation for configuration guides and examples.
> >
> > > [tab] Key Features
> > >
> > > > [card] IMAP Connection
> > > >
> > > > Connect to any IMAP-compatible email server with SSL/TLS support
> > >
> > > > [card] Message Start Event
> > > >
> > > > New trigger type option in Message Start Event nodes to use Email Triggers
> > >
> > > > [card] Attachment handling
> > > >
> > > > Automatic upload of email attachments to Document Plugin with file validation
> > >
> > > > [card] Validation rules
> > > >
> > > > Configure allowed file types, maximum file size, and attachment count limits
> > >
> > > > [card] Manage triggers
> > > >
> > > > Central Runtime page to activate, deactivate, and monitor email triggers
> > >
> > > > [card] Failed triggers
> > > >
> > > > Dedicated page to view and troubleshoot failed email processing attempts
> >
> > > [tab] Configuration
> > >
> > > **Data Source Settings:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | IMAP (currently supported) |
> > > | Server Host | IMAP server hostname |
> > > | Port | Connection port (993 for SSL/TLS) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > > | SSL/TLS | Enable secure connection |
> > >
> > > **Filtering Criteria:**
> > >
> > > * **Email Address**: Monitored email address (read-only, based on authentication)
> > > * **Mailbox Folder**: Folder to monitor (default: Inbox)
> > >
> > > **Validation Options:**
> > >
> > > * **Allowed File Types**: PDF, DOCUMENT, IMAGE, EXCEL, ZIP
> > >
> > > * **Maximum File Size**: Up to 25 MB per attachment
> > >
> > > * **Maximum File Count**: Limit attachments per email
> > >
> > > > [!TIP]
> > > >
> > > > All fields accept configuration parameters using `${configParam}` syntax for environment-specific values.
> >
> > > [tab] Email Data Schema
> > >
> > > When an email triggers a process, the following data structure is available:
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "emailMessage": {
> > >     "subject": "Support Request #12345",
> > >     "dateTime": "2026-01-15T10:30:00Z",
> > >     "sender": "customer@example.com",
> > >     "body": "Email body content...",
> > >     "fileAttachments": [{
> > >       "filePath": "email-attachments/proc-123/file.pdf",
> > >       "downloadPath": "/api/internal/files/uuid/download"
> > >     }],
> > >     "headerParams": {
> > >       "Message-ID": "<abc123@example.com>"
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Use Cases
> > >
> > > > [card] Customer support automation
> > > >
> > > > Automatically create support tickets from incoming customer emails
> > >
> > > > [card] Document processing
> > > >
> > > > Process attached documents through automated workflows
> > >
> > > > [card] Request handling
> > > >
> > > > Route requests to appropriate departments based on email content
> > >
> > > > [card] Notification processing
> > > >
> > > > Process automated notifications from external systems
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat component**
>
> > [card] Chat component
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a standalone Chat tab in web container applications, enabling AI-powered conversational interfaces within your applications. The Chat component provides a dedicated space for users to interact with AI agents through a familiar messaging interface.
> > >
> > > > [!NOTE]
> > > >
> > > > The Chat component integrates with FlowX.AI's AI platform to enable intelligent conversational experiences powered by your configured AI agents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the complete Chat Component documentation for configuration guides and best practices.
> >
> > > [tab] Key Features
> > >
> > > > [card] Standalone chat tab
> > > >
> > > > Dedicated chat interface available as a standalone tab in web container apps
> > >
> > > > [card] Message history
> > > >
> > > > Persistent chat history with automatic scrolling to the latest messages
> > >
> > > > [card] AI agent integration
> > > >
> > > > Connect to workflows powered by AI agents
> > >
> > > > [card] Session management
> > > >
> > > > Automatic session handling with persistence across page refreshes
> > >
> > > > [card] Customizable UI
> > > >
> > > > Themeable components with comprehensive style configuration through Theme Admin
> >
> > > [tab] Configuration
> > >
> > > **Component setup:**
> > >
> > > * Add Chat component from UI Designer to your UI Flow
> > > * Select a workflow to handle chat interactions
> > > * Configure header, messages, and input properties
> > > * Apply custom styling through Theme Admin
> > >
> > > **Display modes:**
> > >
> > > * Full screen (v5.4.0)
> > > * Additional modes planned for v5.5
> >
> > > [tab] Improvements
> > >
> > > **Session handling:**
> > >
> > > * Chat session ID is now generated when the first message is sent (not when opening the chat)
> > > * Improved session tracking
> > >
> > > **Message display:**
> > >
> > > * Latest messages are automatically scrolled into view after loading chat history
> > > * User input formatting (JSON, multiline text) is now preserved in displayed messages
> > >
> > > **Platform support:**
> > >
> > > * Available in both Angular and React web renderers
> > > * Mobile support planned for v5.5
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **MCP server improvements**
>
> > [card] MCP server improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 enhances MCP (Model Context Protocol) server integration with improved audit logging, exception handling, and resource management capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audit logging
> > > >
> > > > Complete audit trail for MCP server operations including creation, updates, and tool execution
> > >
> > > > [card] Tool refresh
> > > >
> > > > Update MCP servers to fetch new tools without recreating the data source
> > >
> > > > [card] Resource tracking
> > > >
> > > > Track MCP server usage across workflows with proper resource management
> > >
> > > > [card] Copy support
> > > >
> > > > Properly preserve MCP server selections when copying or duplicating workflows
> > >
> > > > [card] SSE streaming
> > > >
> > > > Fixed SSE event streaming to deliver events individually as they complete
> > >
> > > > [card] Exception handling
> > > >
> > > > Improved error handling and reporting for MCP server operations
> >
> > > [tab] Bug Fixes
> > >
> > > * **Tool updates**: Updating MCP servers now correctly fetches new tools
> > > * **Workflow copy**: MCP server selections are preserved when copying workflows
> > > * **Resource usages**: Fixed resource usage tracking when copying workflows to other projects
> > > * **SSE events**: Events are now streamed individually instead of all at once
> > > * **Audit entries**: Fixed missing event and subject in audit log entries
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] Rendering
>
> UI component enhancements and navigation improvements for web applications.
>
> 🎴 [**Card Default Collapse State**](#card-default-collapse-state) - Configure cards to load in collapsed state by default\
> 🧭 [**UI Flow Breadcrumbs**](#ui-flow-breadcrumbs) - Navigation breadcrumbs ui component for UI Flows with theme configuration\
> 📊 [**UI Flow Sessions**](#ui-flow-sessions) - Monitor and manage UI Flow sessions with audit logs and process tracking\
> 📋 [**Tables in Collections**](#tables-in-collections) - Add support for Table UI components within Collection UI elements
>
> ### **Card default collapse state**
>
> > [card] Card default collapse state
> >
> > FlowX.AI 5.4.0 introduces a new **Default collapse state** property for Card components with accordion functionality, allowing you to configure cards that are collapsed when first loaded.
> >
> > > [tab] Overview
> > >
> > > When using Card components with the accordion feature enabled, you can now specify whether the card should be expanded or collapsed by default when the screen loads. This provides better control over the initial presentation of content and helps manage screen real estate.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> > > >
> > > > See the complete Card component documentation for configuration details.
> >
> > > [tab] Configuration
> > >
> > > **Default collapse state options:**
> > >
> > > | State | Description |
> > > | - | - |
> > > | **Expanded** | The card content is visible when the screen loads (default behavior) |
> > > | **Collapsed** | The card content is hidden when the screen loads; users click to expand |
> > >
> > > > [!NOTE]
> > > >
> > > > This property is only available when the **Has accordion** setting is enabled on the Card component.
> >
> > > [tab] Use Cases
> > >
> > > > [card] Progressive disclosure
> > > >
> > > > Start with collapsed sections to reduce initial visual complexity
> > >
> > > > [card] Optional content
> > > >
> > > > Hide less important information by default while keeping it accessible
> > >
> > > > [card] Long forms
> > > >
> > > > Break up lengthy forms into collapsible sections for better navigation
> > >
> > > > [card] FAQ sections
> > > >
> > > > Display questions collapsed with answers revealed on click
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Breadcrumbs**
>
> > [card] UI Flow Breadcrumbs
> >
> > > [tab] Overview
> > >
> > > Navigation breadcrumbs UI component for UI Flows provide users with clear context of their current location within the application hierarchy. Breadcrumbs display the navigation path and enable quick navigation to parent screens.
> > >
> > > > [!NOTE]
> > > >
> > > > Breadcrumbs enhance user experience by providing visual navigation context and allowing users to understand their position in the application structure.
> >
> > > [tab] Key Features
> > >
> > > > [card] Navigation breadcrumbs UI component
> > > >
> > > > Display breadcrumbs UI component for UI Flows showing the current navigation path
> > >
> > > > [card] Admin theme configuration
> > > >
> > > > Configure breadcrumb appearance and styling through Admin theme settings
> >
> > > [tab] Configuration
> > >
> > > **Theme Configuration:**
> > >
> > > * Configure breadcrumb styling through Admin theme settings
> > > * Customize colors, fonts, and spacing to match your application design
> > > * Apply consistent styling across all UI Flows
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Sessions**
>
> > [card] UI Flow Sessions
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces UI Flow Sessions monitoring in the Runtime view, providing comprehensive visibility into active user sessions with UI Flows. Monitor session activity, view audit logs, track associated processes, and debug UI Flow interactions in real-time.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flow Sessions enable administrators and developers to track user interactions, troubleshoot issues, and monitor the health of UI Flow-based applications.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> > > >
> > > > See the complete UI Flow Sessions documentation for detailed usage and troubleshooting guides.
> >
> > > [tab] Key Features
> > >
> > > > [card] Session monitoring
> > > >
> > > > View all active and historical UI Flow sessions with status, start date, and session IDs
> > >
> > > > [card] Audit log
> > > >
> > > > Comprehensive audit trail showing all events and actions within each session
> > >
> > > > [card] Process tracking
> > > >
> > > > Monitor process instances started from UI Flows with execution status and timing
> > >
> > > > [card] Workflow debugging
> > > >
> > > > View workflow execution details, node timing, and data transformations for troubleshooting
> > >
> > > > [card] Filtering and search
> > > >
> > > > Filter sessions by UI Flow definition and search by session ID for quick access
> > >
> > > > [card] Real-time status
> > > >
> > > > Track session status updates in real-time (STARTED, ACTIVE, FINISHED, FAILED)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Session monitoring
> > > >
> > > > Monitor active sessions to understand user engagement and identify sessions needing attention
> > >
> > > > [card] Audit and compliance
> > > >
> > > > Track all user interactions and actions for audit purposes and compliance requirements
> > >
> > > > [card] Debugging
> > > >
> > > > Investigate issues by reviewing audit logs, process instances, and workflow executions
> > >
> > > > [card] Performance analysis
> > > >
> > > > Analyze session duration, process start times, and workflow execution performance
> >
> > Runtime ManagementAll Deployments
>
> ***
>
> ### **Tables in Collections**
>
> > [card] Tables in Collections
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces support for Table UI components within Collection UI elements, enabling you to display structured tabular data as items within dynamic collections. This enhancement provides greater flexibility for presenting complex data structures in a consistent, organized format.
> > >
> > > > [!NOTE]
> > > >
> > > > You can now embed Table components inside Collection prototypes, allowing each collection item to display data in a structured table format with columns, rows, and table-specific features.
> > >
> > > > [card] [Table Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/table)
> > > >
> > > > See the complete Table component documentation for configuration details and usage examples.
> > >
> > > > [card] [Collection Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/collection/collection)
> > > >
> > > > Learn about Collection components and how to configure collection prototypes.
> >
> > > [tab] Key Features
> > >
> > > > [card] Table in collection items
> > > >
> > > > Embed Table components within Collection prototypes to display structured data for each collection item
> > >
> > > > [card] Structured data display
> > > >
> > > > Present complex data structures with columns, rows, and table-specific formatting within collections
> > >
> > > > [card] Table features
> > > >
> > > > Leverage full Table component capabilities including sorting, filtering, pagination, and row actions
> > >
> > > > [card] Dynamic content
> > > >
> > > > Combine Collection's dynamic data handling with Table's structured presentation for flexible layouts
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product catalogs
> > > >
> > > > Display product information in table format within a collection of products
> > >
> > > > [card] Data dashboards
> > > >
> > > > Create dashboard views with multiple tables showing different data sets in collection items
> > >
> > > > [card] Report listings
> > > >
> > > > Show report summaries in table format within a collection of reports
> > >
> > > > [card] Comparison views
> > > >
> > > > Compare multiple entities side-by-side using tables within collection items
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Platform & infrastructure
>
> Backend optimizations, connector improvements, and platform stability enhancements.
>
> 🔌 [**Connector Topic Pattern**](#connector-topic-pattern) - Dedicated Kafka topic pattern for connectors\
> ⚙️ [**Kafka Configuration Alignment**](#kafka-configuration-alignment) - Unified Kafka property names across all services with backwards compatibility\
> ⚡ [**Advancing Performance**](#advancing-performance) - Fixed advancing partition issues and improved concurrency handling
>
> ### **Connector topic pattern**
>
> > [card] Connector topic pattern
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a dedicated Kafka topic pattern variable (`KAFKA_CONNECTORS_TOPIC_PATTERN`) for connectors, allowing custom topic patterns without affecting other platform components like document-plugin, data-search, and cms-core.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Shared topic pattern
> > > >
> > > > Connectors used the same `KAFKA_TOPIC_PATTERN` as other components, limiting customization
> > >
> > > > [card] Security concerns
> > > >
> > > > Connectors could write to all topics with the pattern `ai.flowx.engine.receive.*`
> >
> > > [tab] Solution
> > >
> > > **New Configuration:**
> > >
> > > ```yaml theme={"dark"}
> > > # Old configuration (shared with all components)
> > > KAFKA_TOPIC_PATTERN: ai.flowx.engine.receive.*
> > >
> > > # New configuration (dedicated for connectors)
> > > KAFKA_CONNECTORS_TOPIC_PATTERN: ro.uniflow.*
> > > ```
> > >
> > > **Benefits:**
> > >
> > > * Connectors can use custom topic patterns
> > > * Other components continue using the standard pattern
> > > * Improved security through topic isolation
> >
> > InfrastructureSelf-Managed
>
> ***
>
> ### **Kafka configuration alignment**
>
> > [card] Kafka configuration alignment
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 aligns Kafka configuration properties across all services (core-services and AI platform services) by introducing standardized property names while maintaining full backwards compatibility with existing configurations.
> >
> > > [tab] New Properties
> > >
> > > **Standardized Kafka Properties:**
> > >
> > > The following new environment variables are now available across all services:
> > >
> > > | Environment Variable | Description | Fallback Property |
> > > | - | - | - |
> > > | `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers | `SPRING_KAFKA_BOOTSTRAP_SERVERS` |
> > > | `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka communication | `SPRING_KAFKA_SECURITY_PROTOCOL` |
> > >
> > > > [!NOTE]
> > > >
> > > > The new properties take precedence over the legacy `SPRING_KAFKA_*` properties. If the new properties are not set, the system automatically falls back to the legacy properties, ensuring backwards compatibility.
> >
> > > [tab] Benefits
> > >
> > > > [card] Property alignment
> > > >
> > > > Consistent property names across core-services and AI platform services
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing configurations using `SPRING_KAFKA_*` properties continue to work without changes
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Unified configuration approach across all FlowX.AI services
> > >
> > > > [card] Migration flexibility
> > > >
> > > > Migrate to new properties at your own pace without breaking existing deployments
> > >
> > > > [!NOTE]
> > > >
> > > > This change was implemented in core-services and automatically applies to all services that use the shared Kafka configuration. No action is required for existing deployments, but you can optionally migrate to the new property names for consistency.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Advancing performance**
>
> > [card] Advancing performance
> >
> > FlowX.AI 5.4.0 includes significant fixes and improvements to the advancing mechanism, resolving issues with stalled events and improving concurrency handling.
> >
> > > [accordion] Stalled events fix
> > >
> > > Fixed issue where NEW entries in `advancing_partition` and `advancing_partition_event` tables would become stalled and never processed. This occurred when multiple events were generated for the same partition during parallel processing.
> >
> > > [accordion] Numeric overflow fix
> > >
> > > Fixed numeric overflow error when `advancing_partition_event_seq` sequence exceeded `Integer.MAX_VALUE`. Now correctly uses `getLong()` instead of `getInt()` for sequence values.
> >
> > > [accordion] Concurrency improvements
> > >
> > > * Fixed issue with multiple events to the same partition causing negative `count_queued_events`
> > > * Replaced trigger-based solution with SQL transactions for atomic updates
> > > * Improved handling of embedded subprocess completion under concurrent load
> >
> > > [accordion] Automated test stability
> > >
> > > Resolved data inconsistencies and business exceptions that were causing automated tests to fail consistently.
> >
> > PerformanceAll Deployments
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes across SaaS features, Designer, and backend services.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI and navigation fixes for Designer\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.4.0 resolves Designer issues to improve stability and user experience.
> >
> > ## Navigation & routing
> >
> > > [accordion] Navigation fixes
> > >
> > > * **Fixed sidebar display** - sidebar menu now shows when accessing pages via URL
> > > * **Fixed subprocess navigation** - resolved 403 when navigating to subprocesses
> > > * **Fixed back navigation** - resolved 403 when going back from UI Flows page
> > > * **Fixed audit log access** - resolved errors when viewing process instance audit logs
> > > * **Fixed version history** - "Open version in new tab" now works correctly
> >
> > > [accordion] UI improvements
> > >
> > > * **Fixed default locale display** - locale now correctly shown in Version settings
> > > * **Fixed substitution calls** - resolved errors when starting processes or accessing UI Flows
> >
> > Designer StabilityAll Deployments
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process engine
> >
> > > [accordion] Advancing & concurrency
> > >
> > > * **Fixed stalled advancing events** - NEW entries no longer get stuck in advancing tables
> > > * **Fixed numeric overflow** - resolved overflow when sequence exceeds Integer.MAX\_VALUE
> > > * **Fixed concurrent updates** - resolved stale data errors for embedded subprocess completion
> > > * **Fixed negative counter** - resolved issue with `count_queued_events` going negative
> >
> > ## AI platform
> >
> > > [accordion] AI integration fixes
> > >
> > > * **Fixed multi-agent streaming** - streaming now works correctly for multi-agent chat
> > > * **Fixed SSE event delivery** - events are delivered individually as they complete
> >
> > ## Integration Designer
> >
> > > [accordion] Workflow & data model
> > >
> > > * **Fixed file upload multipart** - only file name is sent in multipart body, not full path
> > > * **Fixed data model duplicates** - resolved duplicate entries in mongo properties\_paths
> >
> > Backend StabilityAll Deployments
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.4.0](./deployment-guidelines-v5.4).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.3.0 - no breaking changes for standard deployments
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.4
>
> ### SaaS features
>
> > [!NOTE]
> >
> > The SaaS multi-tenant features introduced in this release require additional infrastructure configuration for production deployments. Contact your FlowX.AI representative for guidance on enabling SaaS capabilities.


# Deployment guidelines v5.5.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/deployment-guidelines-v5.5

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.60.0** | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 |
| **admin** | **10.53.0** | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 |
| **designer** | **10.91.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **cms-core** | **10.35.0** | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **10.25.0** | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **10.27.0** | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **10.35.0** | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **10.35.0** | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **10.35.0** | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 |
| **data-search** | **10.25.0** | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **10.31.0** | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **10.27.0** | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 |
| **integration-designer** | **10.63.0** | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 |
| **application-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **data-sync** | **10.31.1** | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 |
| **authorization-system** | **10.42.1** | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **10.27.0** | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 |
| **email-gateway** | **10.24.0** | 10.9.0 | - | - | - | - |
| **organization-manager** | **10.19.2** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 |
| **Android renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 |
| **di-platform** | **10.2.6** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **knowledgebase** | **TBD** | - | - | - | - | - |
| **knowledgebase-rag** | **10.2.0** | - | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.2.0** | - | - | - | - | - |
| **mcp** | **10.2.0** | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.5.0 | Keycloak | 26+ |
| 5.5.0 | Kafka | 3.8 - 3.9 |
| 5.5.0 | PostgreSQL | 16 - 17 |
| 5.5.0 | Oracle Database | 21c, 23ai |
| 5.5.0 | MongoDB | 7 - 8 |
| 5.5.0 | Redis | 7.4 - 8.0 |
| 5.5.0 | Elasticsearch | 8 - 9 |
| 5.5.0 | Angular (Web SDK) | 20 |
| 5.5.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.5.0

### Key features and updates

> [card] Chat Component Enhancements
>
> New subcomponents (reasoning, error, suggestions), display modes, and mobile support

> [card] UI Flows Improvements
>
> Process renderer component, start workflow action, and on load events

> [card] Microsoft Outlook Integration
>
> Native MS Graph data source for reading and sending Outlook emails

> [card] Send Notification Action
>
> Send emails and reply to received emails directly from processes via SMTP

> [card] Knowledge Base v2
>
> Updated Knowledge Base with audit, resource management, and improved UI

> [card] User Management Updates
>
> Password policy, DISABLED status, resend invitations, workspace environment types

## Upgrading from v5.4.0

### Breaking changes

> [!WARNING]
>
> FlowX.AI 5.5.0 introduces a **breaking change** to the default authentication mechanism across most platform services. If you rely on the default `SECURITY_TYPE` value or opaque-token introspection, action is required before upgrading.

#### Authentication mechanism change

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. This reflects a shift from opaque-token introspection to JWT-based authentication as the default security mechanism.

**Removed environment variables:**

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

**Changed default values:**

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

**Migration steps:**

**1. Update SECURITY\_TYPE if explicitly set**

If you explicitly set `SECURITY_TYPE=oauth2` in your deployment configuration, update it to `jwt-public-key` or remove it to use the new default.

**2. Remove deprecated opaque-token variables**

Remove all `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_*` variables from your Helm values, environment configs, or deployment manifests.

**3. Update service account client IDs**

Service account client IDs now follow the `flowx-{service-name}-sa` pattern (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Update your Keycloak service account configurations accordingly.

**4. Configure the service account realm**

Add the `security.oauth2.sa-realm` property to your configuration if your service account realm differs from the default.

**5. Remove legacy OAuth2 client variables**

Remove `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENT_ID`, `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`, and `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_*` variables from your configuration.

***

### Key changes

* **Authentication**: Default `SECURITY_TYPE` changed from `oauth2` to `jwt-public-key` (breaking change — see above)
* **Organization Manager**: New microservice for organization and tenant management
* **Chat Component**: Enhanced with new subcomponents (reasoning, error, suggestions), display modes, and mobile support
* **UI Flows**: New process renderer component, start workflow action, and on load UI event
* **Microsoft Outlook**: New MS Graph data source for Outlook email integration
* **Send Notification**: New action type for sending/replying to emails via SMTP
* **Knowledge Base v2**: Updated UI, audit trail, and resource management
* **Container Apps**: Enhanced authentication flow and landing page
* **File Upload**: Improved progress indicators, drag and drop, and large file support
* **File Encrypt/Decrypt**: New document plugin actions for file encryption and decryption
* **User Management**: Password policy updates, DISABLED status, resend invitations, workspace environment type
* **Process Variables Compare**: Monaco diff editor for comparing variable values
* **New Kafka topics**: Multiple new topics added across document-plugin, integration-designer, admin, application-manager, email-gateway, authorization-system, and notification-plugin

***

### New microservice: Organization Manager

> [!NOTE]
>
> **Available starting with FlowX.AI 5.5.0**
>
> The Organization Manager is a new microservice responsible for organization and tenant management, including user registration, organization lifecycle, and platform component health monitoring.

**Infrastructure requirements:**

| Dependency | Details |
| - | - |
| PostgreSQL | Dedicated database for organization data |
| Redis | Caching and session management |
| Kafka | Event publishing (organization events topic) |
| Keycloak/IAM | Authentication and realm management |
| SpiceDB | Authorization via CAS lib |

> [card] [Organization Manager Setup](/5.1/setup-guides/organization-manager-setup)
>
> Complete setup and configuration guide for the Organization Manager microservice

***

### New Kafka topics

FlowX.AI 5.5.0 introduces new Kafka topics across multiple services.

#### Document-plugin Kafka topics

New topics for file encryption, decryption, bulk document persistence, and UI Flow session document persistence operations.

**Input topics (document-plugin consumes from these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Triggers file decryption operations |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Triggers file encryption operations |
| `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Triggers bulk document persistence operations |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway |

**Output topics (document-plugin publishes to these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Results from file decryption operations |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Results from file encryption operations |
| `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Results from bulk document persistence |
| `ai.flowx.eventsgateway.receive.document.v1` | Document upload progress notifications sent to events-gateway for SSE delivery |

#### Integration-designer Kafka topics

New topics for integration-designer in 5.5.0. Integration-designer now participates in the application sync mechanism for system and workflow resources.

> [!NOTE]
>
> The `sync.out.v1` and `correction-after-app-operation.response.v1` topics already exist since 5.1.x (used by admin). In 5.5.0, integration-designer becomes an additional producer on these shared response topics.

**New topics:**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync requests | Inbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System resource correction requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow resource correction requests | Inbound |
| `ai.flowx.build.runtime-data.v1` | Build runtime data | Outbound |
| `ai.flowx.license.usage.v1` | License usage tracking | Outbound |

**Existing topics (new producer in 5.5.0):**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.out.v1` | Sync operation responses | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | Correction operation responses | Outbound |

#### Admin Kafka topics

New topics for UI flow synchronization and correction operations in 5.5.0.

> [!NOTE]
>
> The `sync.process.in.v1`, `sync.business-rule.in.v1`, `sync.reusable-template.in.v1`, `sync.out.v1`, and `correction-after-app-operation` topics for process, business-rule, and reusable-template already exist since 5.1.x. Only the UI flow topics below are new in 5.5.0.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Inbound |

#### Application-manager Kafka topics

New outbound topics for resource synchronization and correction of system, workflow, and UI flow resources in 5.5.0.

> [!NOTE]
>
> Application-manager already produces sync and correction topics for process, business-rule, and reusable-template since 5.1.x. The topics below extend the same mechanism to system, workflow, and UI flow resources.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync | Outbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync | Outbound |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow resource sync | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Outbound |

#### Email-gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.save.audit.v1` | Audit event logging | Outbound |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Trigger process start from email events | Outbound |

#### Authorization-system Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.organization.events.v1` | Organization lifecycle events | Outbound |

#### Notification-plugin Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.resources-usages.refresh.v1` | Resource usages refresh events | Inbound |
| `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` | Sub-resource validation responses | Outbound |
| `ai.flowx.application-version.resources-usages.operations.bulk.v1` | Bulk resource usage operations | Outbound |

> [!NOTE]
>
> These topics are automatically created if your Kafka cluster has auto-topic creation enabled. For production environments, it is recommended to create them manually with appropriate partition counts and replication factors.

***

### New environment variables

#### Platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

#### Document-plugin variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) | document-plugin |

> [!NOTE]
>
> This setting affects all file uploads handled by the document-plugin. Configure alongside the existing Spring multipart settings (`SPRING_SERVLET_MULTIPART_MAXFILESIZE`, `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`) for consistent upload limits. See [Documents Plugin Setup](/5.1/setup-guides/documents-plugin-setup#multipart-upload-configuration).

#### Authorization-system variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client. Required for new deployments. | ` ` (empty) | authorization-system |

> [!WARNING]
>
> **New deployments only**: If this variable is not set, the `flowx-platform-authenticate` Keycloak client will have no redirect URIs and OAuth2 login will fail. Set this to your Designer and app URLs (e.g., `https://designer.yourcompany.com/*,https://app.yourcompany.com/*`).
>
> Existing deployments upgrading to 5.5.0 are not affected — the Liquibase migration that uses this variable has already run.

> [card] [Authorization System Setup](/5.1/setup-guides/authorization-setup-guide#keycloak-redirect-uris)
>
> See the full redirect URI configuration details

#### Email-gateway variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` | email-gateway |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` | email-gateway |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL` | TTL for cached MS Graph client instances | `1d` | email-gateway |

> [!NOTE]
>
> For complete email-gateway configuration including database, Redis, and Kafka settings, see the [Email Gateway Setup](/5.9/setup-guides/email-gateway-setup) guide.

***

### Compatibility

* **Authentication**: Default `SECURITY_TYPE` changed to `jwt-public-key` — deployments using opaque-token introspection require migration (see [breaking changes](#authentication-mechanism-change))
* **Renderer Updates**: Web and mobile SDKs include new Chat component features and UI Flows enhancements
* **Database**: No schema changes required for this upgrade
* **Mobile Support**: Chat component now available on iOS and Android renderers
* **New Service**: Organization Manager requires PostgreSQL, Redis, Kafka, and Keycloak infrastructure

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/migration-overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!WARNING]
>
> FlowX.AI v5.5.0 introduces a **critical breaking change** to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

## What's changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (`oauth2`) to JWT-based authentication (`jwt-public-key`). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — **Organization Manager** — has been introduced for organization and tenant management.

## Who is affected

> [!WARNING]
>
> **All deployments** are affected by the authentication mechanism change. The default `SECURITY_TYPE` value has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services.
>
> If you explicitly set `SECURITY_TYPE=oauth2` or rely on opaque-token introspection, you **must** update your configuration before upgrading.

## Migration process

**1. Back up your configuration**

Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.

**2. Update Keycloak service accounts**

Update your Keycloak service account client IDs to follow the new `flowx-{service-name}-sa` naming pattern. See [Update Keycloak service accounts](#update-keycloak-service-accounts) for the full mapping.

**3. Update environment variables**

Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.

**4. Deploy Organization Manager**

If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.

**5. Deploy and verify**

Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

***

## Authentication mechanism change

### Overview

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. Opaque-token introspection has been **removed entirely**.

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

### Changed default values

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

***

## Update Keycloak service accounts

Service account client IDs now follow the `flowx-{service-name}-sa` pattern. Update your Keycloak configuration to match:

| Service | New Client ID |
| - | - |
| Admin | `flowx-admin-sa` |
| Process Engine | `flowx-process-engine-sa` |
| Integration Designer | `flowx-integration-designer-sa` |
| Authorization System | `flowx-authorization-system-sa` |
| Runtime Manager | `flowx-runtime-manager-sa` |
| Scheduler Core | `flowx-scheduler-core-sa` |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager | `flowx-organization-manager-sa` |
| License | `flowx-license-sa` |
| Email Gateway | `flowx-email-gateway-sa` |

> [!WARNING]
>
> Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

***

## New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the **Organization Manager** microservice for organization and tenant management, user registration, and platform component health monitoring.

**Infrastructure requirements:**

* PostgreSQL
* Redis
* Kafka
* Keycloak/IAM
* SpiceDB

For full setup instructions, see the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility** for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

## Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your `SECURITY_TYPE` and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

> [!NOTE]
>
> Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

***

## Additional resources

> [card] [Update Environment Variables](./update-environment-variables-5.5)
>
> Per-service environment variable changes for v5.5.0

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions and deployment instructions

> [card] [IAM Configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution)
>
> Keycloak setup and service account configuration

> [card] [Release Notes v5.5.0](../v5.5.0-february-2026)
>
> Full release notes for v5.5.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/update-environment-variables-5.5

Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!NOTE]
>
> This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"dark"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

> [tab] Before (v5.4)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "oauth2"
>
> # Service account client ID (example for admin service)
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"
>
> # Token URI using main realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
> ```

> [tab] After (v5.5)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "jwt-public-key"
>
> # Service account client ID follows flowx-{service-name}-sa pattern
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"
>
> # Token URI now uses separate sa-realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
> ```

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

***

## Document plugin

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

> [!NOTE]
>
> **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` |

***

## Additional resources

> [card] [Migration Overview](./migration-overview)
>
> Full migration guide with Keycloak and service account changes

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions, Kafka topics, and infrastructure requirements


# FlowX.AI 5.5.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/v5.5.0-february-2026

Enhanced Chat component, UI Flows improvements, Microsoft Outlook integration, container app authentication, and platform management updates.

> [!NOTE]
>
> FlowX.AI 5.5.0 introduces significant enhancements to the Chat component, UI Flows capabilities, email integrations, and platform management features including Knowledge Base v2, user management improvements, and new document processing capabilities.

![Data Source types in FlowX 5.5.0](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_type_selector_all.png)

**What's new?**

> [tab] AI Platform
>
> AI-powered features and document processing enhancements.
>
> 📄 [**Extract Data from File**](#extract-data-from-file) - Configurable document and image extraction with LLM, OCR, and text parsing strategies\
> 📚 [**Knowledge Base v2**](#knowledge-base-v2) - Updated Knowledge Base with audit, resource management, and improved UI
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 renames "Extract Text from Document" to **Extract Data from File** and adds configurable extraction strategies, image input support, and signature detection. Choose between LLM, OCR, or text parsing strategies based on your document types, accuracy requirements, and cost constraints.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Extraction strategies
> > > >
> > > > Choose between LLM Model, OCR Engine, or Text Parsing for optimal accuracy/cost balance
> > >
> > > > [card] Image support
> > > >
> > > > Process images (JPG, PNG, TIFF) in addition to documents — automatic PDF conversion
> > >
> > > > [card] Image extraction options
> > > >
> > > > Extract data from embedded images or generate image descriptions
> > >
> > > > [card] Signature detection
> > > >
> > > > Detect and locate signatures within documents (LLM and OCR modes)
> >
> > > [tab] Configuration
> > >
> > > **Extraction strategies:**
> > >
> > > | Strategy | Best for | Speed | Cost | Accuracy |
> > > | - | - | - | - | - |
> > > | LLM Model | Complex layouts, handwritten text | Slow | High | High |
> > > | OCR Engine | Scanned documents | Medium | Medium | Medium |
> > > | Text Parsing | Clean digital PDFs | Fast | Free | Low–Medium |
> > >
> > > **Image extraction options (LLM and OCR only):**
> > >
> > > | Option | Description |
> > > | - | - |
> > > | Image Description | Generates text descriptions of images |
> > > | Image Content | Extracts text and data from images |
> > >
> > > > [!TIP]
> > > >
> > > > A new [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) covers backend service configuration, deployment sizing, and cost optimization.
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Knowledge Base v2**
>
> > [card] [Knowledge Base v2](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 updates the Knowledge Base with a refreshed UI, audit capabilities, and improved resource management. Knowledge Base entries now support versioning and provide better traceability for AI-powered features.
> >
> > > [tab] Key Features
> > >
> > > > [card] Updated UI
> > > >
> > > > Refreshed Knowledge Base interface with improved navigation and search
> > >
> > > > [card] Audit trail
> > > >
> > > > Track changes to Knowledge Base entries with full audit history
> > >
> > > > [card] Resource management
> > > >
> > > > Improved management of Knowledge Base resources and documents
> > >
> > > > [card] Version tracking
> > > >
> > > > Version-aware Knowledge Base entries tied to app versions
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] UI Flows
>
> Enhanced UI Flows with new components, actions, and chat improvements.
>
> 💬 [**Chat Component Enhancements**](#chat-component-enhancements) - New subcomponents, display modes, and mobile support\
> 🧭 [**UI Flows Breadcrumbs**](#ui-flows-breadcrumbs) - Navigation breadcrumbs for UI Flows\
> 📄 [**Process Renderer Component**](#process-renderer-component) - Embed process renderers within UI Flows\
> 🚀 [**Start Workflow Action**](#start-workflow-action) - Start workflows directly from UI Flows\
> ⚡ [**On Load UI Event**](#on-load-ui-event) - Execute actions when UI Flows load
>
> ### **Chat component enhancements**
>
> > [card] [Chat component enhancements](/5.9/ai-platform/chat-component)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 significantly enhances the Chat component with new subcomponents for reasoning, error handling, and suggestions. The component now supports multiple display modes and is available on mobile platforms.
> >
> > > [tab] New Subcomponents
> > >
> > > > [card] Reasoning display
> > > >
> > > > Show AI reasoning and thought process to users for transparency
> > >
> > > > [card] Error handling
> > > >
> > > > Graceful error display with retry options and helpful messages
> > >
> > > > [card] Suggestions
> > > >
> > > > Display suggested responses or actions to guide user interactions
> >
> > > [tab] Display Modes
> > >
> > > **Available display modes:**
> > >
> > > | Mode | Description |
> > > | - | - |
> > > | **Full screen** | Chat occupies the entire screen (available since v5.4.0) |
> > > | **Sidebar** | Chat appears as a collapsible sidebar |
> > > | **Floating** | Chat appears as a floating widget |
> > > | **Embedded** | Chat embedded within a container component |
> >
> > > [tab] Mobile Support
> > >
> > > The Chat component is now fully supported on mobile platforms:
> > >
> > > > [card] iOS
> > > >
> > > > Native iOS renderer support with optimized touch interactions
> > >
> > > > [card] Android
> > > >
> > > > Native Android renderer support with material design integration
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **UI Flows breadcrumbs**
>
> > [card] [UI Flows breadcrumbs](/5.9/docs/building-blocks/ui-flows#breadcrumbs)
> >
> > FlowX.AI 5.5.0 enhances the breadcrumbs navigation component for UI Flows, providing users with clear context of their current location and enabling quick navigation to parent screens.
> >
> > > [card] Navigation path
> > >
> > > Display the full navigation path within UI Flows
> >
> > > [card] Click navigation
> > >
> > > Navigate to any parent screen by clicking breadcrumb items
> >
> > > [card] Theme configuration
> > >
> > > Customize breadcrumb appearance through Admin theme settings
> >
> > > [card] Responsive design
> > >
> > > Breadcrumbs adapt to different screen sizes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process renderer component**
>
> > [card] [Process renderer component](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > > [tab] Overview
> > >
> > > Embed process renderers directly within UI Flows using the new Process Renderer component. This enables hybrid applications that combine UI Flow navigation with traditional process-based screens.
> >
> > > [tab] Key Features
> > >
> > > > [card] Process embedding
> > > >
> > > > Embed any process renderer within a UI Flow screen
> > >
> > > > [card] Data passing
> > > >
> > > > Pass data between UI Flows and embedded processes
> > >
> > > > [card] Event handling
> > > >
> > > > Handle process events within the UI Flow context
> > >
> > > > [card] Consistent styling
> > > >
> > > > Maintain consistent styling and navigation across UI Flows and processes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Start workflow action**
>
> > [card] [Start workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action)
> >
> > > [tab] Overview
> > >
> > > Start integration workflows directly from UI Flows using the new Start Workflow action. This enables UI Flows to trigger backend workflows without requiring a full process instance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow selection
> > > >
> > > > Select from available integration workflows
> > >
> > > > [card] Input mapping
> > > >
> > > > Map UI Flow data to workflow input parameters
> > >
> > > > [card] Response handling
> > > >
> > > > Handle workflow responses and update UI state
> > >
> > > > [card] Error handling
> > > >
> > > > Configure error handling for failed workflow executions
> >
> > UI EnhancementAll Deployments
>
> ### **On load UI event**
>
> > [card] [On load UI event](/5.9/docs/building-blocks/ui-designer/event-handlers#triggers)
> >
> > > [tab] Overview
> > >
> > > Execute actions automatically when UI Flow screens load using the new On Load UI Event. This enables initialization logic, data fetching, and setup operations when users navigate to a screen.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic execution
> > > >
> > > > Actions execute automatically when the screen loads
> > >
> > > > [card] Data initialization
> > > >
> > > > Fetch and initialize data when entering a screen
> > >
> > > > [card] Conditional logic
> > > >
> > > > Execute different actions based on conditions
> > >
> > > > [card] Loading states
> > > >
> > > > Manage loading states during initialization
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Integrations
>
> Email integrations, document processing, and Integration Designer updates.
>
> 📬 [**Microsoft Outlook Data Source**](#microsoft-outlook-data-source) - Native MS Graph integration for reading and sending Outlook emails\
> 📧 [**Send Notification Action**](#send-notification-action) - Send emails and reply to received emails directly from processes\
> 🔌 [**Integration Designer Improvements**](#integration-designer-improvements) - Query parameter encoding, config param autocomplete\
> 🔑 [**Security Details in Workflows**](#security-details-in-workflows) - Access user security details in workflow scripts\
> 🔐 [**File Encrypt and Decrypt**](#file-encrypt-and-decrypt) - Encrypt and decrypt files in the Documents Plugin
>
> ### **Microsoft Outlook data source**
>
> > [card] Microsoft Outlook data source
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces a new **Microsoft Outlook** data source type that connects to Outlook mailboxes via the Microsoft Graph API. Unlike Email Trigger (IMAP) and Email Sender (SMTP), this provides a unified data source for both reading and sending emails through native Outlook integration with Azure AD authentication.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> > > >
> > > > See the complete Microsoft Outlook data source documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified read & send
> > > >
> > > > Single data source supports Read Emails, Send Emails, or Read & Send Emails scopes
> > >
> > > > [card] Azure AD authentication
> > > >
> > > > Service account authentication with Tenant ID, Client ID, and Client Secret
> > >
> > > > [card] Email monitoring
> > > >
> > > > Monitor Outlook mailboxes and trigger processes automatically when emails arrive
> > >
> > > > [card] Send & reply
> > > >
> > > > Send new emails or reply to received emails with conversation thread support
> > >
> > > > [card] Attachment validations
> > > >
> > > > Configure allowed file types, max file size, and max file count for incoming emails
> > >
> > > > [card] Test connection
> > > >
> > > > Validate Azure AD credentials and MS Graph permissions before saving
> >
> > > [tab] Configuration
> > >
> > > **Azure AD Authentication:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Tenant ID | Azure AD tenant ID |
> > > | Client ID | Azure AD application (client) ID |
> > > | Client Secret | Azure AD client secret |
> > >
> > > **Scope Options:**
> > >
> > > | Scope | MS Graph Permissions Required |
> > > | - | - |
> > > | Read Emails | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
> > > | Send Emails | `Mail.Send` or `Mail.ReadWrite` |
> > > | Read & Send Emails | One read + one send permission |
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Send Notification action**
>
> > [card] Send Notification action
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces the Send Notification action — a new action type that sends emails directly from process nodes through SMTP, without routing through Kafka. Combined with the new Email Sender data source type, it enables processes to send new emails or reply to emails that triggered the process via Email Trigger.
> > >
> > > > [!NOTE]
> > > >
> > > > Existing notification templates configured for Kafka-based sending continue to work without modification.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> > > >
> > > > See the complete Send Notification action documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Email Sender data source
> > > >
> > > > New SMTP data source type in Integration Designer with SSL/TLS smart port defaults
> > >
> > > > [card] Reply to emails
> > > >
> > > > Reply to emails that triggered the process, maintaining conversation threads
> > >
> > > > [card] Send new emails
> > > >
> > > > Send new outbound emails to specified recipients with CC/BCC support
> > >
> > > > [card] Notification template updates
> > > >
> > > > New Email Server and Email Sender fields for direct SMTP delivery
> > >
> > > > [card] Attachments
> > > >
> > > > Attach files using static paths or process variable keys
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing Kafka-based notification templates continue to work unchanged
> >
> > > [tab] Configuration
> > >
> > > **Email Sender Data Source (new):**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | SMTP (only option) |
> > > | Server Host | SMTP server hostname |
> > > | SSL/TLS | Enable secure connection (default: on) |
> > > | Port | `587` (SSL/TLS on) or `465` (SSL/TLS off) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > >
> > > **Send Notification Action:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Notification Template | Select a template with Predefined Email Connection |
> > > | Reply to received emails | Toggle on to reply to the email that triggered the process |
> > > | Reply to Email Header | Process variable with original email headers (reply mode) |
> > > | Receivers | Recipient email addresses or process variables |
> > > | CC/BCC Receivers | Optional CC and BCC recipients |
> > > | Language | Process variable key for template language |
> > > | Attachments | File path or process variable key |
> > > | Template Data | JSON key-value pairs for dynamic template content |
> > >
> > > > [!TIP]
> > > >
> > > > Available on Send Message Task, Task, and User Task nodes.
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Integration Designer improvements**
>
> > [card] Integration Designer improvements
> >
> > FlowX.AI 5.5.0 adds URL encoding options for REST endpoint query parameters, improved error handling for invalid REST responses, and configuration parameter autocomplete in data source forms.
> >
> > > [card] Query parameter encoding
> > >
> > > Configure whether query parameter values are URL-encoded automatically or sent as-is (for pre-encoded values)
> >
> > > [card] REST Content-Type handling
> > >
> > > Improved error handling when REST endpoints return responses with unexpected Content-Type headers
> >
> > > [card] Config param autocomplete
> > >
> > > Type `$` in data source configuration fields to autocomplete configuration parameters or create new ones inline
> >
> > > [!NOTE]
> > >
> > > See [Integration Designer - Query parameters](/5.1/docs/platform-deep-dive/integrations/integration-designer#query-parameters) for details.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Security details in workflows**
>
> > [card] Security details in workflows
> >
> > Workflow scripts can now access `additionalData.securityDetails` to retrieve the current user's identity. This works when a workflow is started from a **Chat component**, a **UI Flow**, or a **manual run**. Sub-workflows inherit security details from their parent.
> >
> > Unlike processes, where security details are grouped by swimlane and role, workflows use a simplified flat structure:
> >
> > ```json theme={"dark"}
> > {
> >   "securityDetails": {
> >     "username": "user@email.com",
> >     "identifier": "keycloak-subject-id",
> >     "details": {
> >       "firstName": "John",
> >       "lastName": "Snow",
> >       "email": "user@email.com"
> >     }
> >   }
> > }
> > ```
> >
> > > [!NOTE]
> > >
> > > See [Extracting additional data in business rules](/5.1/docs/building-blocks/actions/business-rule-action/extracting-additional-data) for full details and code examples for both processes and workflows.
> >
> > New FeatureAll Deployments
>
> ***
>
> ### **File encrypt and decrypt**
>
> > [card] [File encrypt and decrypt](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files)
> >
> > FlowX.AI 5.5.0 adds new file encryption and decryption actions to the Documents Plugin, enabling processes to encrypt files before storage and decrypt them for authorized access.
> >
> > > [card] File encryption
> > >
> > > Encrypt files using configurable encryption algorithms before storage
> >
> > > [card] File decryption
> > >
> > > Decrypt files for authorized access within process flows
> >
> > InfrastructureAll Deployments
>
> ***

> [tab] Platform & Management
>
> User management, workspace configuration, rendering, and platform improvements.
>
> 🔐 [**Container App Authentication**](#container-app-authentication) - Authentication flow and landing page improvements\
> 🔑 [**Password Policy Updates**](#password-policy-updates) - Updated password complexity requirements\
> 🚫 [**User status DISABLED**](#user-status-disabled) - New DISABLED status for user accounts\
> 📧 [**Resend User Invitation**](#resend-user-invitation) - Resend invitations for pending users\
> 🏷️ [**Workspace Environment Type**](#workspace-environment-type) - Sandbox, Staging, and Production labels for workspaces\
> 🏢 [**Organization ID Propagation**](#organization-id-propagation) - Enhanced multi-tenant isolation\
> ⚡ [**Rendering Runtime UX**](#rendering-runtime-ux) - Runtime UX improvements for rendering\
> 🔍 [**Process Variables Compare**](#process-variables-compare) - Monaco diff editor for process variable values\
> 📧 [**Failed Email Trigger Details Page**](#failed-email-trigger-details-page) - Dedicated details page for failed email triggers\
> 📐 [**Data Model Sidepanel**](#data-model-sidepanel) - Redesigned attribute settings, inline add, and path copy
>
> ### **Container app authentication**
>
> > [card] [Container app authentication](/5.9/docs/saas/container-app-authentication)
> >
> > > [tab] Overview
> > >
> > > Enhanced authentication flow and landing page for generic container applications. Configure authentication providers, customize login pages, and manage user sessions with improved security and user experience.
> >
> > > [tab] Key Features
> > >
> > > > [card] Authentication providers
> > > >
> > > > Support for multiple authentication providers
> > >
> > > > [card] Custom landing page
> > > >
> > > > Customize the landing page for unauthenticated users
> > >
> > > > [card] Session management
> > > >
> > > > Improved session handling and token refresh
> > >
> > > > [card] SSO integration
> > > >
> > > > Seamless single sign-on integration
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Password policy updates**
>
> > [card] [Password policy updates](/5.1/setup-guides/access-management/configuring-an-iam-solution#password-policy)
> >
> > FlowX.AI 5.5.0 updates the password policy with stricter complexity requirements for improved security.
> >
> > **New requirements:**
> >
> > | Rule | Value |
> > | - | - |
> > | Minimum length | 8 characters |
> > | Maximum length | 64 characters |
> > | Complexity | Must include uppercase, lowercase, number, and special character |
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **User status DISABLED**
>
> > [card] [User status DISABLED](/5.9/docs/saas/inviting-users#user-statuses)
> >
> > FlowX.AI 5.5.0 introduces a new **DISABLED** user status. Administrators can now enable or disable user accounts through the **Enable** and **Disable** actions in the user management menu, providing better control over user access without deleting accounts.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Resend user invitation**
>
> > [card] [Resend user invitation](/5.9/docs/saas/inviting-users#resending-invitations)
> >
> > FlowX.AI 5.5.0 adds the ability to resend invitations for users with a **Pending** status, ensuring users who missed or lost their initial invitation can still complete onboarding.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Workspace environment type**
>
> > [card] [Workspace environment type](/5.1/docs/projects/workspaces#workspace-environment-type)
> >
> > FlowX.AI 5.5.0 adds an **Environment Type** dropdown to workspace configuration, allowing administrators to label workspaces as **Sandbox**, **Staging**, or **Production**. This provides clearer context when working across multiple environments.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Organization ID propagation**
>
> > [card] Organization ID Propagation
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 enhances multi-tenant isolation by propagating organization ID across more runtime contexts. This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
> >
> > > [tab] Key Changes
> > >
> > > > [card] Scheduler execution
> > > >
> > > > Organization ID added to scheduled job context
> > >
> > > > [card] Event listeners
> > > >
> > > > Organization ID propagated to event handlers
> > >
> > > > [card] Process instances
> > > >
> > > > Organization ID captured from initiator
> > >
> > > > [card] Audit trail
> > > >
> > > > Enhanced audit logging with organization context
> >
> > InfrastructureSaaS
>
> ***
>
> ### **Rendering runtime UX**
>
> > [card] Rendering runtime UX
> >
> > FlowX.AI 5.5.0 includes various rendering runtime UX improvements for better performance and user experience.
> >
> > > [card] Loading states
> > >
> > > Improved loading state indicators and skeleton screens
> >
> > > [card] Transition animations
> > >
> > > Smoother transitions between screens and states
> >
> > > [card] Error boundaries
> > >
> > > Better error handling with graceful degradation
> >
> > > [card] Performance
> > >
> > > Optimized rendering performance for complex UIs
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process variables compare**
>
> > [card] [Process variables compare](/5.9/docs/projects/runtime/active-process/update-process-variables#compare-view)
> >
> > FlowX.AI 5.5.0 introduces a Monaco diff editor for comparing process variable values, making it easier to identify changes between versions or states.
> >
> > > [card] Diff editor
> > >
> > > Side-by-side comparison of process variable values using Monaco diff editor
> >
> > > [card] Version comparison
> > >
> > > Compare variable values across different process versions
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Failed email trigger details page**
>
> > [card] [Failed email trigger details page](/5.9/docs/platform-deep-dive/integrations/email-trigger#failed-trigger-details-page)
> >
> > FlowX.AI 5.5.0 adds a dedicated details page for failed email triggers, providing better visibility into email processing failures and enabling faster troubleshooting.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Data Model sidepanel**
>
> > [card] Data Model sidepanel
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 redesigns the Data Model editing experience with a new attribute settings side panel, inline add-attribute buttons, and attribute path display. These improvements make it faster to create, configure, and reference data model attributes without switching between menus.
> > >
> > > > [card] [Process Data Model](/5.1/docs/building-blocks/process/data-model#data-model-interface)
> > > >
> > > > See the updated Process Data Model documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Attribute settings side panel
> > > >
> > > > Select any attribute to open a settings panel with type, validations, sensitive data, and reporting options
> > >
> > > > [card] Inline add attribute
> > > >
> > > > Add attributes directly on each data type — button shows on hover after the first attribute
> > >
> > > > [card] Attribute path copy
> > > >
> > > > View and copy the full key path for any attribute for use in business rules and UI bindings
> > >
> > > > [card] Selection highlights
> > > >
> > > > Selecting a data type or connector highlights its location on the canvas
> > >
> > > > [card] Default minimized panel
> > > >
> > > > The Data Types panel starts minimized by default for a cleaner canvas view
> > >
> > > > [card] Confirmation toasts
> > > >
> > > > Success notifications when adding new data types
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### Additional improvements
>
> * **Workflow logs milliseconds** — Workflow execution logs now display timestamps with millisecond precision
> * **Single select in table edit** — SDK enhancement for single-select dropdowns within editable table cells. See [Table component](/5.1/docs/building-blocks/ui-designer/ui-component-types/table#editable-rows)
> * **UI Flows action name optional** — Action names in UI Flows are now optional, reducing configuration overhead
> * **Data mappers editable JSON testing** — Improved JSON testing experience in data mappers with editable input fields
> * **Solutions page load optimization** — Solutions page now loads only projects, improving performance for container apps
> * **Security patches** — General security improvements across platform services

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.5.0](./deployment-guidelines-v5.5).
>
> ### Compatibility
>
> > [!WARNING]
> >
> > **Breaking change:** The default `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 services. Opaque-token introspection has been removed. See the [Deployment Guidelines](./deployment-guidelines-v5.5#breaking-changes) for migration steps.
>
> > [card] Upgrade path
> >
> > Upgrade from v5.4.0 — requires authentication mechanism migration (`SECURITY_TYPE` change)
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.5


# Deployment guidelines v5.6.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/deployment-guidelines-v5.6

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.77.0** | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 |
| **admin** | **10.66.0** | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 |
| **designer** | **10.127.3** | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **cms-core** | **10.43.0** | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 |
| **scheduler-core** | **10.31.0** | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 |
| **events-gateway** | **10.33.1** | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 |
| **notification-plugin** | **10.42.1** | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 |
| **document-plugin** | **10.46.0** | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 |
| **task-management-plugin** | **10.41.1** | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 |
| **data-search** | **10.30.1** | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 |
| **audit-core** | **10.40.0** | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 |
| **advancing-controller** | **10.33.1** | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 |
| **integration-designer** | **10.84.0** | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 |
| **application-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **runtime-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **data-sync** | **10.38.0** | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 |
| **authorization-system** | **10.51.0** | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 |
| **nosql-db-runner** | **10.34.0** | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 |
| **email-gateway** | **10.32.1** | 10.24.0 | 10.9.0 | - | - | - |
| **organization-manager** | **10.26.1** | 10.19.2 | - | - | - | - |
| **webhook-gateway** | **10.1.1** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **iOS renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 |
| **Android renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 |

### Plugins

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.2.3** | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 |
| **di-platform** | **10.3.0** | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 |
| **ai-platform-ai-developer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-connected-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-knowledge-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agents** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-conversations** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-models** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-tenants** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-planner** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-analyst** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-designer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agent-builder** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-binaries** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **knowledgebase** | **10.6.0** | TBD | - | - | - | - |
| **knowledgebase-rag** | **10.6.0** | 10.2.0 | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.0** | 10.2.0 | - | - | - | - |
| **mcp** | **10.6.0** | 10.2.0 | - | - | - | - |
| **doc-converter** | **10.2.2** | - | - | - | - | - |
| **doc-parser** | **10.5.1** | - | - | - | - | - |

> [!NOTE]
>
> **New in 5.6.0:** `webhook-gateway` is a new microservice for processing incoming webhooks. It handles webhook event ingestion and routing to process instances.

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.6.0 | Keycloak | 26+ |
| 5.6.0 | Kafka | 3.8 - 3.9 |
| 5.6.0 | PostgreSQL | 16 - 17 |
| 5.6.0 | Oracle Database | 21c, 23ai |
| 5.6.0 | MongoDB | 7 - 8 |
| 5.6.0 | Redis | 7.4 - 8.0 |
| 5.6.0 | Angular (Web SDK) | 20 |
| 5.6.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.6.0

### Key features and updates

> [card] Chat Driven Workflows
>
> Multi-turn AI conversations with session memory and intent classification

> [card] Incoming Webhooks
>
> Trigger processes from external HTTP POST requests via the new webhook-gateway service

> [card] Web Page Extractor
>
> Collect readable content from web page URLs with crawling and link following

> [card] Proxy Server Connections
>
> Route integration traffic through HTTP/HTTPS proxy servers

> [card] UI Flow Route Management
>
> Query parameters, route maps, and breadcrumb navigation for UI Flows

> [card] MCP Authentication
>
> BEARER and BASIC auth for MCP server connections

## Upgrading from v5.5.0

### Breaking changes

#### WorkspaceCreatedEvent ownership change

> [!WARNING]
>
> The `WorkspaceCreatedEvent` Kafka topic ownership has moved from `authorization-system` to `organization-manager`.

**What changed:**

* `organization-manager` now produces `WorkspaceCreatedEvent` messages
* `authorization-system` no longer produces these events
* Update your Kafka topic ACLs if you manage topic-level permissions

***

#### gRPC thread pool configuration

> [!WARNING]
>
> The default gRPC client thread pool sizes in AI Platform have been updated. Review your deployment configuration if you have custom thread pool settings.

***

### New environment variables

#### Integration Designer

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_WEBHOOKS_BASE_URL` | Base URL for webhook-gateway service communication | `http://webhook-gateway:80` | integration-designer |
| `FLOWX_WEB_CRAWLER_BASE_URL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80` | integration-designer |

#### NoSQL DB Runner

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100` | nosql-db-runner |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL` | Time-to-live for cached external MongoDB connections | `1d` | nosql-db-runner |

#### Process Engine

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts for failed operations | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Base delay between retries (ms) | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum delay between retries (ms) | `200` | process-engine |

#### Authorization System

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD` | Initial password for default realm admin user | *(none)* | authorization-system |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY` | Force password change on first login | `true` | authorization-system |

#### Application Manager

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_RESOURCE_ID_FIELD` | Resource ID field for proxy connection merge | `resourceId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_ID_FIELDS` | Flatten map ID fields for proxy connection merge | `resourceId, name` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection flatten map | `authorization.configuration` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_COMPARE_REMOVED_JSON_PATHS` | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_CONFLICT_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection conflict detection | `resourceId, resourceDefinitionId` | application-manager |

#### Data Search

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | data-search |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | data-search |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | data-search |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | data-search |

#### Email Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | email-gateway |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | email-gateway |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | email-gateway |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | email-gateway |

> [!NOTE]
>
> The SpiceDB and CAS client variables for `data-search` and `email-gateway` are required for authorization integration. These services now use the same SpiceDB-based authorization as other platform services.

#### Webhook Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for webhook registrations database | `jdbc:postgresql://postgresql:5432/webhook_gateway` | webhook-gateway |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` | webhook-gateway |
| `SPRING_DATASOURCE_PASSWORD` | Database password | *(required)* | webhook-gateway |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | OAuth2/OIDC server base URL | — | webhook-gateway |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | — | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account client ID | `flowx-webhook-gateway-sa` | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account client secret | *(required)* | webhook-gateway |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Kafka topic for process start events | `ai.flowx.core.trigger.start-for-event.process.v1` | webhook-gateway |

> [!NOTE]
>
> `webhook-gateway` is a **new microservice** in 5.6.0. It requires its own PostgreSQL database (`webhook_gateway`), Kafka access, Keycloak service account (`flowx-webhook-gateway-sa`), and SpiceDB connectivity.

***

### New Kafka topics

#### Document Plugin

New topic for UI Flow session document persistence.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway | Inbound |
| `ai.flowx.eventsgateway.receive.document.v1` | Document events sent to events-gateway for SSE delivery | Outbound |

#### Webhook Gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Triggers process starts from incoming webhook events | Outbound |

> [!NOTE]
>
> The Webhook Gateway is a **producer-only** service — it receives HTTP webhook requests and publishes process start events to Kafka. It does not consume from any Kafka topics.

#### UI flow session variable updates

New topic for propagating document upload results and workflow completion results to the process-engine, which updates UI flow session variables.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | UI flow session variable updates after document upload or workflow completion | Inbound (process-engine) / Outbound (document-plugin, integration-designer) |

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | process-engine |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Consumer group ID for UI flow updates | `ui-flow-update` | process-engine |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of consumer threads for UI flow updates | `6` | process-engine |

***

### Compatibility

* **SpiceDB**: Now required for `data-search` and `email-gateway` in addition to existing services
* **Renderer Updates**: Web and mobile SDKs include route management, start parameters, enum label display, and chat enhancements
* **Database**: The `start_params` column on `ui_flow_session` table has been renamed to `variables` (auto-migrated via Liquibase). The column now stores all session variables, including start parameters and updates from document uploads and workflow completions

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026

Conversational AI with memory and intent routing, incoming webhooks, proxy connections, unmanaged MongoDB, UI Flow session variables, chat history, and 28 bug fixes.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html)

FlowX.AI 5.6.0 brings **conversational AI** to your apps. Build multi-turn chat experiences where agents remember context, classify user intent, and navigate users to the right screen — all within a single workflow. On the integration side, **incoming webhooks** let external systems start processes via HTTP, **proxy connections** route traffic through intermediary servers, and **unmanaged MongoDB** connects FlowX to your existing database infrastructure. The UI layer gains **session variables**, **route management**, **chat history**, and **suggested prompts** for richer end-user experiences.

> [card] [For AI builders](#conversational-workflows)
>
> Chat Driven workflows, session memory, intent routing, and context retrieval

> [card] [For integrators](#incoming-webhooks)
>
> Incoming webhooks, proxy connections, unmanaged MongoDB, and base64 certificates

> [card] [For UI developers](#ui-flow-session-variables)
>
> Session variables, route management, chat history, suggested prompts, and new UI events

### What changed since 5.5.0

| 5.5.0 | 5.6.0 |
| - | - |
| Output Focused workflows only | + **Chat Driven** workflows with multi-turn memory |
| No event-driven process starts from external systems | **Incoming webhooks** with API key auth |
| FlowX-managed MongoDB only | + **Unmanaged MongoDB** — bring your own database |
| No conversation persistence | **Chat History** — browse and resume past sessions |
| Static chat empty state | **Suggested Prompts** — guide users with one-click starters |
| Certificate file paths only | **Base64 certificates** — paste content directly, no file mounts |
| No cross-page data in UI Flows | **Session variables** — persist data across pages and workflows |

***

**What's new?**

> [tab] AI Platform
>
> Build complete conversational AI pipelines — from understanding what the user wants, to retrieving the right context, to navigating them to the right screen.
>
> 💬 [**Conversational Workflows**](#conversational-workflows) - New Chat Driven workflow type for multi-turn conversations\
> 🧠 [**Memory Capabilities**](#memory-capabilities) - Automatic session memory with summarization across turns\
> 🎯 [**Intent Classification node**](#intent-classification-node) - Classify user messages and route to the right branch in one step\
> 🧭 [**Navigate in UI Flow**](#navigate-in-ui-flow) - Let the AI open forms and screens with contextual data\
> 🔍 [**Context Retrieval node**](#context-retrieval-node) - RAG search against Knowledge Bases without calling an LLM\
> 📄 [**Extract Data from File**](#extract-data-from-file) - Three extraction methods, image support, and signature detection\
> 🌐 [**Web Page Extractor**](#web-page-extractor) - Crawl web pages and extract readable content for AI processing
>
> See also: [Chat History](#chat-history), [Suggested Prompts](#chat-suggested-prompts), and [Markdown in chat](#markdown-in-chat-messages) in the **UI & Designer** tab.
>
> ### **Conversational Workflows**
>
> > [card] Conversational Workflows
> >
> > > [tab] Overview
> > >
> > > Chat Driven workflows are a specialized workflow type for multi-turn chat interactions. Unlike Output Focused workflows that process structured input/output, Chat Driven workflows manage ongoing dialogue — handling message exchange, session memory, and response routing through a dedicated Start node layout (Chat Session ID + User Message) and Custom Agent nodes with direct chat reply capability.
> > >
> > > ![Conversational workflow with Custom Agent configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_config.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> > > >
> > > > See the complete Conversational Workflows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multi-turn conversations
> > > >
> > > > Support for back-and-forth conversations with persistent context
> > >
> > > > [card] Intent routing
> > > >
> > > > Automatically classify user messages and route to appropriate workflow branches
> > >
> > > > [card] Session memory
> > > >
> > > > Built-in session memory with automatic summarization across conversation turns
> > >
> > > > [card] Chat UI components
> > > >
> > > > Dedicated chat component with error handling and shared state management
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Memory Capabilities**
>
> > [card] Memory Capabilities
> >
> > > [tab] Overview
> > >
> > > Conversational workflows include built-in session memory that automatically persists and retrieves conversation history. On each message, the system retrieves the last 3 turns of raw messages plus a summary of earlier exchanges, injecting them into the AI node's system prompt for context-aware responses.
> > >
> > > ![Memory tab showing conversation summary and history](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> > > >
> > > > See the complete Memory Capabilities documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic retrieval
> > > >
> > > > Last 3 turns + summary of earlier exchanges retrieved on each message via sessionId
> > >
> > > > [card] Smart summarization
> > > >
> > > > Older conversation history is automatically summarized to fit within context limits
> > >
> > > > [card] Per-node control
> > > >
> > > > Turn on memory per Custom Agent node with the **Use memory** toggle
> > >
> > > > [card] Memory tab in console
> > > >
> > > > View retrieved memory (raw turns + summary) in the workflow console log
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Intent Classification node**
>
> > [card] Intent Classification Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that combines AI-powered message classification with workflow branching in a single step. Define up to 10 intents with natural language descriptions, and the node classifies user messages and routes to the matching branch automatically — replacing the previous TEXT\_UNDERSTANDING + Condition two-node pattern.
> > >
> > > ![Intent Classification node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intent_classification_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> > > >
> > > > See the complete Intent Classification documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] AI + routing in one node
> > > >
> > > > Combines LLM classification and conditional branching — no separate Condition node needed
> > >
> > > > [card] Natural language conditions
> > > >
> > > > Define intents as plain-text descriptions instead of code expressions
> > >
> > > > [card] Conversation memory
> > > >
> > > > Optionally use past conversation context for more accurate classification
> > >
> > > > [card] Built-in fallback
> > > >
> > > > Automatic "If No Intent Matches" branch handles unrecognized inputs
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Navigate in UI Flow**
>
> > [card] Navigate in UI Flow
> >
> > > [tab] Overview
> > >
> > > A new workflow node exclusive to **Chat Driven** (conversational) workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — for example, the AI says *"Let me open your account details"* and the user sees a pre-filled form with data from the conversation.
> > >
> > > ![Navigate in UI Flow node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node)
> > > >
> > > > See the Navigate in UI Flow section in Conversational Workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Conversational context
> > > >
> > > > Navigate users to UI screens directly from a Chat Driven workflow conversation
> > >
> > > > [card] Dynamic parameters
> > > >
> > > > Pass workflow data to the destination screen using `${expression}` syntax
> > >
> > > > [card] Destination picker
> > > >
> > > > Select from the UI Flow's navigation tree with auto-populated query parameters
> > >
> > > > [card] Chat Driven only
> > > >
> > > > Available exclusively in the Actions category of conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval node**
>
> > [card] Context Retrieval Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that performs RAG (Retrieval-Augmented Generation) searches against Knowledge Bases without calling an LLM. Returns raw chunks with relevance scores and metadata, giving you full control over downstream processing. Supports hybrid, semantic, and keyword search with configurable re-ranking and metadata filters.
> > >
> > > Use Context Retrieval when you need to inspect, filter, or transform chunks before passing them to an LLM — for example, checking relevance scores before generating a response. For all-in-one RAG, use a Custom Agent node with a Knowledge Base attached instead.
> > >
> > > ![Context Retrieval node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the complete Context Retrieval documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] No LLM required
> > > >
> > > > Retrieves chunks directly — no AI generation step, lower latency and cost
> > >
> > > > [card] Multiple search types
> > > >
> > > > Hybrid, semantic, or keyword search with configurable relevance thresholds
> > >
> > > > [card] Metadata filters
> > > >
> > > > Filter chunks by user-defined metadata for scoped retrieval
> > >
> > > > [card] Re-ranking
> > > >
> > > > Optional re-ranking for improved result ordering
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > The workflow node formerly known as "Extract Text from Document" has been renamed to **Extract Data from File** and gained three new configurable settings: **Extraction Method** (LLM Model, OCR Engine, or Text Parsing), **Image Extraction** (Image Description or Image Contents), and **Detect Signatures**. The node now also accepts image files (JPG, PNG, TIFF) in addition to documents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Three extraction methods
> > > >
> > > > Choose between LLM Model (AI vision), OCR Engine (scanned docs), or Text Parsing (digital PDFs) per use case
> > >
> > > > [card] Image support
> > > >
> > > > Process JPG, PNG, and TIFF files alongside PDF, DOCX, XLSX, and PPTX
> > >
> > > > [card] Signature detection
> > > >
> > > > Identify signature areas within documents when using LLM or OCR extraction
> > >
> > > > [card] Moved to Tools category
> > > >
> > > > The node is now in the **Tools** category in the workflow node palette
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor**
>
> > [card] Web Page Extractor
> >
> > > [tab] Overview
> > >
> > > A new workflow node in the **Tools** category that collects readable content from web page URLs. Crawl documentation sites to build a Knowledge Base, scrape product pages for competitive analysis, or extract terms and conditions for compliance review. Supports static URL lists or dynamic URL generation, configurable crawling depth with link following, PDF extraction from linked documents, and adjustable scrape speed presets.
> > >
> > > ![Web Page Extractor node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> > > >
> > > > See the complete Web Page Extractor documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Static or dynamic URLs
> > > >
> > > > Provide a fixed list of up to 20 URLs or generate them dynamically from workflow data
> > >
> > > > [card] Link following
> > > >
> > > > Follow links on pages up to a configurable depth (0–10 levels)
> > >
> > > > [card] PDF processing
> > > >
> > > > Extract content from PDF files linked on crawled pages
> > >
> > > > [card] Speed presets
> > > >
> > > > Choose Slow, Moderate, Fast, or Custom with manual rate limit and concurrency
> >
> > All Deployments

> [tab] Integrations
>
> Connect FlowX to more systems — trigger processes from external events, route traffic through proxies, and query your own MongoDB databases.
>
> 🔗 [**Incoming Webhooks**](#incoming-webhooks) - Trigger processes from external HTTP POST requests\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Route integration traffic through proxy servers\
> 🗄️ [**Unmanaged MongoDB Datasource**](#unmanaged-mongodb-datasource) - Connect to externally managed MongoDB instances\
> 📧 [**Email Trigger Enhancements**](#email-trigger-enhancements) - Resource management, reply-to, and mock email testing\
> 🔐 [**MCP Authentication**](#mcp-authentication) - BEARER and BASIC auth support for MCP server connections\
> 📜 [**Base64 Certificate Support**](#base64-certificate-support) - Provide certificates as base64-encoded strings instead of file paths\
> 📊 [**CSV/Excel to JSON Conversion**](#csv/excel-to-json-conversion) - Download CSV and Excel files as structured JSON on the fly
>
> ### **Incoming Webhooks**
>
> > [card] Incoming Webhooks
> >
> > > [tab] Overview
> > >
> > > A new data source type and microservice (`webhook-gateway`) that allows external systems to trigger FlowX processes via HTTP POST requests. Create a Webhook data source in Integration Designer, connect it to a Message Start Event in your process, and FlowX generates a unique URL with API key authentication. When external systems POST to this URL, a process instance starts automatically with the webhook payload and headers.
> > >
> > > ![Active webhook trigger in Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)
> > >
> > > > [!NOTE]
> > > >
> > > > Requires deploying the new `webhook-gateway` microservice. See [Deployment Guidelines](./deployment-guidelines-v5.6) for configuration.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> > > >
> > > > See the complete Incoming Webhooks documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] API key authentication
> > > >
> > > > Each webhook gets a unique, cryptographically secure API key for authentication
> > >
> > > > [card] JSON payload forwarding
> > > >
> > > > Webhook body and headers are forwarded to the process instance as variables
> > >
> > > > [card] Manage Triggers integration
> > > >
> > > > Activate, deactivate, and monitor webhooks from the Manage Triggers UI
> > >
> > > > [card] API key regeneration
> > > >
> > > > Regenerate API keys without recreating the webhook configuration
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Proxy Server Connections**
>
> > [card] Proxy Server Connections
> >
> > > [tab] Overview
> > >
> > > Create reusable proxy connections in Integration Designer and attach them to RESTful System data sources. Route outbound API traffic through HTTP or HTTPS proxy servers for environments that require intermediary routing for security or compliance.
> > >
> > > ![Proxy Connection configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> > > >
> > > > See the complete Proxy Connections documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] HTTP and HTTPS proxies
> > > >
> > > > Configure HTTP or HTTPS proxy servers with optional basic authentication
> > >
> > > > [card] Reusable connections
> > > >
> > > > Create a proxy once and attach it to multiple RESTful System data sources
> > >
> > > > [card] Test connectivity
> > > >
> > > > Validate proxy configuration before saving with the built-in test function
> > >
> > > > [card] Config parameter support
> > > >
> > > > Use `${param}` syntax in host and port fields for environment-specific values
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Unmanaged MongoDB Datasource**
>
> > [card] Unmanaged MongoDB Datasource
> >
> > > [tab] Overview
> > >
> > > Connect to externally managed MongoDB instances as a data source in FlowX. Unlike the built-in FlowX Database (which provisions and manages MongoDB collections automatically), Unmanaged MongoDB connects to databases and collections you control — with the same CRUD operations, connection discovery, and configurable connection pooling. Requires MongoDB 6.0 or later.
> > >
> > > ![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> > > >
> > > > See the complete Unmanaged MongoDB documentation.
> >
> > All Deployments
>
> ***
>
> ### **Email Trigger Enhancements**
>
> > [card] Email Trigger Enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.6.0 enhances the Email Trigger with resource management capabilities, reply-to-email support, process instance tracking for email-triggered processes, and mock email testing for development.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Resource management
> > > >
> > > > Manage email trigger resources with proper lifecycle controls
> > >
> > > > [card] Reply-to-email
> > > >
> > > > Support for reply-to patterns in email-triggered workflows
> > >
> > > > [card] Process instances
> > > >
> > > > View and track process instances created from email triggers
> > >
> > > > [card] Mock email testing
> > > >
> > > > Test email-triggered processes with mock email content during development
> >
> > All Deployments
>
> ***
>
> ### **MCP Authentication**
>
> > [card] MCP Authentication
> >
> > > [tab] Overview
> > >
> > > MCP server connections now support **BEARER** and **BASIC** authentication methods. Configure auth credentials when adding an MCP data source to connect to secured MCP servers.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source)
> > > >
> > > > See the Adding MCP Data Source documentation.
> >
> > All Deployments
>
> ***
>
> ### **Base64 Certificate Support**
>
> > [card] Base64 Certificate Support
> >
> > > [tab] Overview
> > >
> > > RESTful system data sources now support providing keystore and truststore content as **base64-encoded strings** instead of file paths. A new "Certificate type" selector lets you choose between Base64 (default for new configurations) and Path (existing behavior). Additionally, keystore and truststore passwords now support `${configParam}` placeholder syntax for dynamic per-environment resolution.
> > >
> > > ![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#certificates)
> > > >
> > > > See the Integration Designer certificates documentation.
> >
> > All Deployments
>
> ***
>
> ### **CSV/Excel to JSON Conversion**
>
> > [card] CSV/Excel to JSON Conversion
> >
> > > [tab] Overview
> > >
> > > Download CSV, XLS, or XLSX files as structured JSON directly from the file download endpoints. The conversion happens on the fly using the `Accept: application/json` header — no new files are created in storage. Supports two output formats: an array of objects (one per row) or a columnar structure.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats#csv/excel-to-json-conversion)
> > > >
> > > > See the Document Conversion documentation.
> >
> > All Deployments

> [tab] UI & Designer
>
> Richer end-user experiences with session state, chat history, and navigation — plus Designer productivity improvements.
>
> 🗺️ [**UI Flow Route Management**](#ui-flow-route-management) - Configure routes, query parameters, and navigation in UI Flows\
> ▶️ [**UI Flow Start Parameters**](#ui-flow-start-parameters) - Pass parameters when starting UI Flows\
> 💾 [**UI Flow Session Variables**](#ui-flow-session-variables) - Persist data across pages from workflows and file uploads\
> 📋 [**Chat History**](#chat-history) - Browse and resume past chat conversations\
> 💡 [**Chat Suggested Prompts**](#chat-suggested-prompts) - Pre-configured prompt suggestions in chat empty state\
> 🖱️ [**onClick UI events**](#onclick-ui-events) - Client-side data updates on Button and Collection Prototype clicks\
> ✨ [**Monaco Editor Autocomplete**](#monaco-editor-autocomplete) - Autocomplete from config params in code editors\
> 📊 [**KB query results in workflow console**](#kb-query-results-in-workflow-console) - View retrieved chunks and relevance scores during workflow runs\
> 📎 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Upload multiple files simultaneously\
> ❌ [**DISMISS UI action**](#dismiss-ui-action) - Dismiss modals automatically after Start Workflow completes\
> 🎨 [**Process Variables UX**](#process-variables-ux-improvements) - UI/UX improvements for updating process variables\
> 🏷️ [**Enum label display**](#enum-label-display) - Show enum labels instead of codes in text components\
> 📬 [**Notification template usages**](#notification-template-usages) - See where notification templates are used\
> 📐 [**Side Panel in Data Model**](#side-panel-in-data-model) - Improved data model navigation with side panel\
> 👁️ [**On Display UI event**](#on-display-ui-event) - Re-trigger actions every time a screen becomes visible\
> 🪟 [**On Load event on Modal**](#on-load-event-on-modal) - Modal components now support On Load events\
> 🏗️ [**KB user-defined metadata**](#kb-user-defined-metadata) - Define custom metadata keys on Knowledge Base content sources\
> ⚙️ [**Config params in workflow conditions**](#config-params-in-workflow-conditions) - Use config params and user details in workflow Fork node expressions\
> 🎨 [**Branding settings grouping**](#branding-settings-grouping) - Reorganized branding settings page\
> ✍️ [**Markdown in chat messages**](#markdown-in-chat-messages) - Render formatted text, links, and lists in chat responses\
> 🔗 [**External Action dynamic URL**](#external-action-dynamic-url) - Use expressions in External Action URLs for dynamic navigation\
> 📬 [**Notification history**](#notification-history) - View sent notification details and search by process instance
>
> ### **UI Flow Route Management**
>
> > [card] UI Flow Route Management
> >
> > > [tab] Overview
> > >
> > > Define query parameters on root views (Pages, Modals), pass data between screens via URL query strings, and get automatic breadcrumb generation from the navigation graph. Navigate To actions support destination parameter mapping with `${expression}` syntax for dynamic values.
> > >
> > > ![Route parameters modal with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#route-management)
> > > >
> > > > See the Route Management section in UI Flows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Route parameters
> > > >
> > > > Define named query parameters on root views with default values and required flags
> > >
> > > > [card] Parameter passing
> > > >
> > > > Map data from process store to destination query parameters using JSON expressions
> > >
> > > > [card] Auto breadcrumbs
> > > >
> > > > Breadcrumbs auto-generate from the navigation graph with proper parameter handling
> > >
> > > > [card] Modal URL state
> > > >
> > > > Modals add `modalId` to URL — survives page reload and supports deep linking
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Start Parameters**
>
> > [card] UI Flow Start Parameters
> >
> > > [tab] Overview
> > >
> > > Pass initial data when launching a UI Flow. Define start parameters as a JSON object in the Designer's Run dialog, extract them from URL query strings in SaaS container apps, or send them in the API request body. Parameters are persisted on the session and available throughout the UI Flow lifecycle.
> > >
> > > ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#start-parameters)
> > > >
> > > > See the Start Parameters section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Session Variables**
>
> > [card] UI Flow Session Variables
> >
> > > [tab] Overview
> > >
> > > UI Flow sessions can now persist variables across all pages sharing the same session ID. Data from start parameters, workflow outputs, and file upload responses is automatically collected and merged into session variables. Reference them in component configurations using `${}` syntax. A new **Variables** tab in the Designer session console shows current values for debugging.
> > >
> > > ![Variables tab in UI Flow session console](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#session-variables)
> > > >
> > > > See the Session Variables section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **Chat History**
>
> > [card] Chat History
> >
> > > [tab] Overview
> > >
> > > Users can now browse and resume past chat conversations. Chat History displays a list of previous sessions grouped by time (Today, Yesterday, Previous 7 Days, Previous 30 Days, Older), with the ability to open any conversation and continue where they left off. Conversations are per-user with access control enforced.
> > >
> > > ![Chat History panel with conversation list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#chat-history)
> > > >
> > > > See the Chat History section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Chat Suggested Prompts**
>
> > [card] Chat Suggested Prompts
> >
> > > [tab] Overview
> > >
> > > The Chat component now supports pre-configured **Suggested Prompts** — pill buttons displayed below the welcome message in the chat empty state. Configure a title and up to 5 prompt options in the Designer. When a user clicks a suggestion, it is submitted as their message, starting the conversation immediately.
> > >
> > > ![Suggested Prompts in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#suggested-prompts)
> > > >
> > > > See the Suggested Prompts section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Monaco Editor Autocomplete**
>
> > [card] Monaco Editor Autocomplete
> >
> > > [tab] Overview
> > >
> > > Code editors in the Designer now provide autocomplete suggestions from your project's configuration parameters. This speeds up writing business rules and expressions that reference config params.
> > >
> > > > [card] [Documentation](/5.1/docs/projects/runtime/configuration-parameters-overrides)
> > > >
> > > > See the Configuration Parameters documentation.
> >
> > All Deployments
>
> ***
>
> ### **Process Variables UX improvements**
>
> > [card] Process Variables UX
> >
> > > [tab] Overview
> > >
> > > UI/UX improvements to the Update Process Variables experience, making it easier to view and edit runtime process data.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > > >
> > > > See the Update Process Variables documentation.
> >
> > All Deployments
>
> ***
>
> ### **onClick UI events**
>
> > [card] onClick UI events
> >
> > > [tab] Overview
> > >
> > > Buttons and Collection Prototypes now support **onClick** UI events — client-side JavaScript expressions that execute immediately when clicked, *before* any configured UI actions fire. Use them for instant local data updates without server roundtrips.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-events)
> > > >
> > > > See the UI Events documentation.
> >
> > All Deployments
>
> ***
>
> ### **KB query results in workflow console**
>
> > [card] KB Query Results
> >
> > > [tab] Overview
> > >
> > > The workflow run console now includes a **Knowledge Base** tab that displays retrieved chunks, relevance scores, content sources, and metadata when Custom Agent nodes query a knowledge base. This makes it easier to debug and tune RAG-powered workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows)
> > > >
> > > > See Using Knowledge Base in Workflows.
> >
> > All Deployments
>
> ***
>
> ### **Multi-file bulk upload**
>
> > [card] Multi-file Bulk Upload
> >
> > > [tab] Overview
> > >
> > > Upload multiple files simultaneously at runtime using the new [Multiple File Upload](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload) component. Supports drag-and-drop, batch selection, per-file validation, and progress tracking. Available in both process screens and UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **DISMISS UI action**
>
> > [card] DISMISS Action
> >
> > > [tab] Overview
> > >
> > > The Start Workflow UI action now includes a **Dismiss modal** checkbox. When enabled, the modal closes automatically after the workflow completes — removing the need for a separate close action.
> >
> > All Deployments
>
> ***
>
> ### **Enum label display**
>
> > [card] Enum Label Display
> >
> > > [tab] Overview
> > >
> > > Text components can now display the human-readable **label** of an enumeration value instead of the raw code. When a data key references an enumeration, the renderer resolves the selected code to its label at display time. Enumeration values are also prefetched from the data model before action resolution for improved performance.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations#displaying-enum-labels-in-text-components)
> > > >
> > > > See the Enumerations documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification template usages**
>
> > [card] Notification Template Usages
> >
> > > [tab] Overview
> > >
> > > Notification templates now show a **usages** modal that lists all processes and workflows referencing the template. This helps you understand the impact of changes before editing or deleting a template.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > > >
> > > > See the Managing Notification Templates documentation.
> >
> > All Deployments
>
> ***
>
> ### **Side Panel in Data Model**
>
> > [card] Side Panel in Data Model
> >
> > > [tab] Overview
> > >
> > > The Data Model editor now includes a side panel for easier navigation and editing of data model attributes, improving the workflow when working with large data models.
> >
> > All Deployments
>
> ***
>
> ### **On Display UI event**
>
> > [card] On Display UI event
> >
> > > [tab] Overview
> > >
> > > A new `onDisplay` event type that triggers every time a screen becomes visible — on initial load, when navigating back, or when a modal is dismissed. Unlike On Load (which fires once), On Display re-triggers on every view, making it ideal for refreshing data.
> > >
> > > Supported on Page, Zone, and Tab Bar components in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **On Load event on Modal**
>
> > [card] On Load event on Modal
> >
> > > [tab] Overview
> > >
> > > Modal components in UI Flows now support the On Load event and Start Workflow action. This enables data fetching when a modal opens, allowing you to load context-specific data for modal content.
> >
> > All Deployments
>
> ***
>
> ### **KB user-defined metadata**
>
> > [card] KB user-defined metadata
> >
> > > [tab] Overview
> > >
> > > Define custom metadata keys on Knowledge Bases and assign values to content sources. User-defined metadata enables filtering and scoping when searching chunks — for example, by department, document version, or region. Metadata values are propagated to the vector database and can be used as filters in the Context Retrieval workflow node.
> >
> > All Deployments
>
> ***
>
> ### **Config params in workflow conditions**
>
> > [card] Config params in workflow conditions
> >
> > > [tab] Overview
> > >
> > > Workflow Fork (condition) nodes can now access configuration parameters via `additionalData.applicationConfiguration` and authenticated user details via `additionalData.securityDetails` in their expressions. This enables environment-aware routing and user-based branching in integration workflows.
> >
> > All Deployments
>
> ***
>
> ### **Branding settings grouping**
>
> > [card] Branding settings grouping
> >
> > > [tab] Overview
> > >
> > > The branding settings page has been reorganized with improved grouping and layout, making it easier to find and configure branding options.
> >
> > All Deployments
>
> ***
>
> ### **Markdown in chat messages**
>
> > [card] Markdown in Chat Messages
> >
> > > [tab] Overview
> > >
> > > Chat message components in web renderers now support Markdown rendering. AI-generated responses can include formatted text, headings, links, code blocks, and lists — displayed with proper styling in the chat interface.
> >
> > All Deployments
>
> ***
>
> ### **External Action dynamic URL**
>
> > [card] External Action Dynamic URL
> >
> > > [tab] Overview
> > >
> > > External Action URLs now support `${expression}` syntax for dynamic values. Build destination URLs using process data, config params, or computed values — enabling context-aware external navigation from UI Flows.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-actions#external-ui-actions)
> > > >
> > > > See the UI Actions documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification history**
>
> > [card] Notification History
> >
> > > [tab] Overview
> > >
> > > New REST API endpoints on the notification plugin let you retrieve sent notification history. Query a paginated summary list filtered by app and optionally by process instance, or fetch full notification details by ID — including recipients, subject, body, and the source process/action that triggered it.
> > >
> > > * `GET /api/notification/summary` — paginated summary list with filtering and sorting
> > > * `GET /api/notification/{id}` — full notification details including body and recipients
> >
> > > [tab] Key Features
> > >
> > > > [card] Summary and detail views
> > > >
> > > > Paginated summary list for browsing, with full detail drill-down by notification ID
> > >
> > > > [card] Source tracking
> > > >
> > > > Each notification records which process, node, and action triggered it for full traceability
> >
> > All Deployments

> [tab] SaaS
>
> User management and branding improvements for SaaS deployments.
>
> 👤 [**Runtime User Invitations**](#runtime-user-invitations) - Invite runtime users directly to test projects\
> 🏢 [**Workspace Type Display**](#workspace-type-display) - See workspace type within Designer\
> 🎨 [**Container App Branding**](#container-app-branding) - Customize branding for SaaS container apps\
> 👥 [**Designer User Invitations**](#designer-user-invitations) - Updated invite modal for designer users
>
> ### **Runtime User Invitations**
>
> > [card] Runtime User Invitations
> >
> > > [tab] Overview
> > >
> > > Invite runtime users directly to test projects from within the Designer. Simplifies the process of granting test access without requiring full workspace-level permissions.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS
>
> ***
>
> ### **Workspace Type Display**
>
> > [card] Workspace Type Display
> >
> > > [tab] Overview
> > >
> > > The Designer now displays the workspace type (development, staging, production) directly within the workspace view, making it easier to identify your current environment.
> >
> > SaaS
>
> ***
>
> ### **Container App Branding**
>
> > [card] Container App Branding
> >
> > > [tab] Overview
> > >
> > > Customize your SaaS container app branding at the organization level — upload a custom logo, set primary and secondary colors, toggle the header, and configure the solutions page background.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/container-app-branding)
> > > >
> > > > See the Container App Branding documentation.
> >
> > SaaS
>
> ***
>
> ### **Designer User Invitations**
>
> > [card] Designer User Invitations
> >
> > > [tab] Overview
> > >
> > > The invite modal for designer users has been redesigned with clearer role selection, group assignment, and a streamlined layout for inviting multiple users.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS

> [tab] Bug Fixes
>
> ## Bug fixes
>
> ### Core Platform
>
> * **Authorization-system Oracle DB startup** — Fixed an issue where the authorization-system service failed to start when using Oracle as the configured database.
> * **Process definition merge timing** — Fixed a race condition where the process definition was updated before the merge was finalized.
> * **Theme import with builds** — Fixed an issue where themes were not included when importing builds.
> * **Library import permissions** — Fixed an issue where importing a library into a workspace redirected to a 403 error page.
> * **App version reimport** — Fixed an error that occurred when reimporting an app version (project or library).
> * **Email resend after URL expiry** — Fixed an issue where the resend email endpoint returned 200 OK but no email was sent after the URL expired.
> * **Platform status discovery** — Fixed an authorization error when trying to force discover platform status.
> * **Runtime roles in permissions** — Fixed inconsistent runtime roles display in the permissions dropdown.
>
> ### AI Platform & Workflows
>
> * **gRPC thread pool sizing** — Fixed under-provisioned gRPC client thread pools that caused socket timeouts and dropped requests in production.
> * **API error trace IDs** — API errors now include a reference to the active traceID for easier debugging.
> * **Cross-project resource copy** — Fixed an issue where copying a workflow resource to another project did not include LDM objects.
> * **Multi-instance mappings** — Fixed a 400 error when saving multi-instance mappings in data mappers.
> * **Email trigger mock testing** — Fixed errors when starting a process from a build with mock email content.
> * **Multiple start nodes with email trigger** — Fixed an issue where only one start option was displayed when a process contained multiple start nodes with email triggers.
>
> ### Renderers & UI
>
> * **Angular input field crash** — Fixed an issue where pressing Enter in an input field caused the Angular UI to crash.
> * **Floating Chat interaction blocking** — Fixed an issue where the floating chat component blocked all interaction with page content while open.
> * **S3 internal bucket error** — Fixed an error when the integration-designer downloads files from document-plugin via downloadPath.
> * **File upload second attempt** — Fixed an issue where upload requests were not made when uploading a second file.
> * **UI Flow analytics** — Fixed issues where analytics events were not visible and not saved for Navigate-to action types.
> * **Task management column selection** — Fixed an issue where the Last Updated column remained selected in task management.
> * **Task Manager theming and UX** — Multiple fixes for Task Manager theming, dropdown display, comment field styling, and user assignment behavior.
> * **Toggle/checkbox label alignment** — Fixed an issue where the switch toggle/checkbox or label shifted position when in an error state.&#x20;
> * **Query parameters lost after refresh** — Fixed an issue where URL query parameters were lost after page refresh in UI Flows.&#x20;
> * **SSE connection management** — Fixed multiple issues where SSE connections were opened twice or not closed properly after messages were received.&#x20;
> * **Modal layering** — Fixed incorrect layering when a loader modal was displayed on top of another modal.&#x20;
> * **Card theming overrides** — Fixed an issue where card theming overrides were not applied when the card was collapsed.&#x20;
> * **On Display workflow triggering** — Fixed an issue where past On Display workflows were not re-triggered on page refresh.&#x20;
>
> ### Knowledge Base
>
> * **KB metadata handling** — Fixed multiple issues with Knowledge Base user-defined metadata: empty properties on content source creation, metadata not available for content sources added through apps, and incorrect cleanup when deleting metadata keys.&#x20;

> [tab] Info
>
> ## Additional information
>
> ### At a glance
>
> This release includes **30+ new features and enhancements** across AI Platform, Integrations, UI & Designer, and SaaS — plus **28 bug fixes** spanning Core Platform, AI/Workflows, Renderers, and Knowledge Base.
>
> ***
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6).
>
> For new environment variables and Kafka topics, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6#new-environment-variables).
>
> ### Changes to be aware of
>
> > [!NOTE]
> >
> > FlowX.AI 5.6.0 is a SaaS-managed release — deployment-level changes (infrastructure, Kafka topics, service configuration) are handled automatically by FlowX. The items below are listed for transparency and for future reference when on-prem support ships in 5.7+.
>
> #### API change (action required if you use this endpoint)
>
> > [!WARNING]
> >
> > **Process definition start metadata endpoint renamed** — `GET /api/process-definition/{uuid}/get-input-json` has been renamed to `GET /api/process-definition/{uuid}/get-start-metadata`. Update any API clients or custom integrations that call this endpoint directly.
> >
> > The response now includes an additional `hasEmailTriggerStart` boolean field.
>
> #### Infrastructure changes (managed by FlowX on SaaS)
>
> * **gRPC thread pool configuration** — Default gRPC client thread pool sizes have been updated for better production throughput.
> * **WorkspaceCreatedEvent ownership** — Kafka topic ownership moved from `authorization-system` to `organization-manager`.
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.5.0 — if you call `get-input-json` directly, update to `get-start-metadata`. All other changes are managed automatically on SaaS.
>
> > [card] [Component versions](./deployment-guidelines-v5.6#component-versions)
> >
> > See the Deployment Guidelines for the full component version matrix


# Deployment guidelines v5.7.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7

Component versions, environment variables, and configuration changes for FlowX.AI 5.7.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.96.0** | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 |
| **admin** | **10.83.0** | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 |
| **designer** | **10.164.0** | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **cms-core** | **10.58.0** | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 |
| **scheduler-core** | **10.45.0** | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 |
| **events-gateway** | **10.47.0** | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 |
| **notification-plugin** | **10.56.0** | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 |
| **document-plugin** | **10.64.0** | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 |
| **task-management-plugin** | **10.57.0** | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 |
| **data-search** | **10.44.0** | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 |
| **audit-core** | **10.54.0** | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 |
| **advancing-controller** | **10.45.0** | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 |
| **integration-designer** | **10.113.0** | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 |
| **application-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **runtime-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **data-sync** | **10.50.0** | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 |
| **authorization-system** | **10.68.0** | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 |
| **nosql-db-runner** | **10.48.0** | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 |
| **email-gateway** | **10.47.0** | 10.32.1 | 10.24.0 | 10.9.0 | - | - |
| **organization-manager** | **10.44.0** | 10.26.1 | 10.19.2 | - | - | - |
| **webhook-gateway** | **10.15.0** | 10.1.1 | - | - | - | - |
| **license** | **10.36.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |

### Plugins

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 |
| **ai-platform-ai-assistant** | **10.6.2** | - | - | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 |
| **ai-platform-ai-developer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-connected-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-knowledge-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agents** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-conversations** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-tenants** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-planner** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-analyst** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-designer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agent-builder** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-binaries** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **embedder** | **10.6.2** | - | - | - | - | - |
| **knowledgebase-rag** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **mcp** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **doc-converter** | **10.2.3** | 10.2.2 | - | - | - | - |
| **doc-parser** | **10.6.2** | 10.5.1 | - | - | - | - |
| **web-crawler** | **10.3.2** | - | - | - | - | - |
| **data-privacy** | **10.0.8** | - | - | - | - | - |
| **speech-to-text** | **10.3.3** | - | - | - | - | - |
| **modpod** | **10.0.7** | - | - | - | - | - |

> [!NOTE]
>
> **Note:** The `ai-platform-models` service has been removed in 5.7.0. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers) within the Organization Manager.

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.7.0 | Keycloak | 26+ |
| 5.7.0 | Kafka | 3.8 - 3.9 |
| 5.7.0 | PostgreSQL | 16 - 17 |
| 5.7.0 | Oracle Database | 21c, 23ai |
| 5.7.0 | MongoDB | 7 - 8 |
| 5.7.0 | Redis | 7.4 - 8.0 |
| 5.7.0 | Elasticsearch | 8 |
| 5.7.0 | Angular (Web SDK) | 20 |
| 5.7.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> The following versions of third-party dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

***

## Self-hosted deployment changes

> [!WARNING]
>
> **First on-premises release since 5.4.0.** This section covers critical configuration changes for self-hosted (on-premises) deployments.

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **Fresh install** | Supported | Guided setup flow on first launch. See [Organization Manager setup](/5.1/setup-guides/organization-manager-setup). |
| **5.1.x LTS** | Supported | Requires Organization ID on all 19 services. Liquibase migrates active process instances and realm data. Inactive instances require separate handling by FlowX. See details below. |
| **5.2 - 5.4** | FlowX-assisted only | These versions may have partial realm or organization changes. Contact your FlowX representative for a custom migration plan. Do **not** follow the 5.1.x upgrade path. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

### Organization ID (mandatory for upgrades)

The Organization ID is how FlowX identifies your installation. How it is obtained depends on your deployment path:

* **Fresh install:** The Organization ID is created automatically during the guided setup flow (Designer first-launch screen). No manual configuration needed.
* **Upgrade from 5.1.x:** FlowX registers your organization in the SaaS licensing infrastructure and provides an Organization ID (UUID). Set `ORGANIZATION_ID` on **all 19 services** before deploying 5.7.0 images — Liquibase migrations use it to replace the default organization.

```yaml theme={"dark"}
# Example — set on every service
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

**Affected services (all 19):** process-engine, admin, audit-core, authorization-system, advancing-controller, events-gateway, cms-core, scheduler-core, data-search, document-plugin, nosql-db-runner, notification-plugin, task-management-plugin, integration-designer, organization-manager, email-gateway, application-manager, runtime-manager, license.

> [!WARNING]
>
> Do **not** deploy 5.7.0 images without setting `ORGANIZATION_ID` on upgrade scenarios. Services will fail to start if Liquibase migrations cannot find the organization ID.

> [!NOTE]
>
> **Active vs inactive instances.** Liquibase migrations automatically update the Organization ID on **active process instances** only. Inactive or archived instances require separate migration handled by the FlowX team during guided deployment. Contact your FlowX representative for details.

### License service (new)

Self-hosted deployments must configure the License service to connect to FlowX SaaS for license validation and usage reporting. See the [License service setup guide](/5.9/setup-guides/license-engine-setup) for complete configuration.

### IAM / Keycloak changes

FlowX.AI now uses a **two-realm architecture** in Keycloak and **JWT public key validation** (replacing opaque-token introspection). These changes were introduced in 5.5.0 (SaaS) and are now relevant for self-hosted deployments.

* **Token validation**: `security.type` switches from `oauth2` to `jwt-public-key` on all services
* **Service accounts realm**: A dedicated realm (`00000002-0002-4002-8002-000000000002`) holds all service account clients, separate from the user realm
* **Organization manager**: Now a required dependency for all services (provides realm resolution)
* **`flowx-platform-authorize` client**: No longer needed — remove from Keycloak
* **Master realm credentials**: The authorization-system service needs Keycloak admin access for realm migrations. If you cannot provide admin credentials, see [Manual Keycloak configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).
* **SMTP**: Must be configured in Keycloak for password reset and user invitations

For complete IAM setup instructions, see the [Configuring an IAM solution](/5.1/setup-guides/access-management/configuring-an-iam-solution) guide.

***

## Environment info deprecation

The **Configure Environment Info** feature (`PATCH /api/platform/environment`) is deprecated and removed. Environment name is now set during organization registration. The following are no longer used:

* `FLOWX_CLIENT_NAME` environment variable
* `FLOWX_ENVIRONMENT_NAME` environment variable
* `environmentDetails` section in the `/api/init` response

***

## Kafka integration changes

### Fx-Organization-Id header (mandatory)

All FlowX Kafka consumers now validate the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected with a non-retryable `MissingKafkaHeaderException`.

> [!WARNING]
>
> **Action required for custom Kafka integrations.** If you have custom Kafka producers that publish directly to FlowX topics (starting processes, sending task events, responding to engine requests), you must add the `Fx-Organization-Id` header to every message. Set it to the Organization UUID (`ORGANIZATION_ID` value).
>
> ```java theme={"dark"}
> producerRecord.headers().add("Fx-Organization-Id",
>     organizationId.getBytes(StandardCharsets.UTF_8));
> ```
>
> See the [Creating a Kafka producer](/5.1/docs/platform-deep-dive/integrations/creating-a-kafka-producer#important-headers) guide for details.

### New Kafka topics

| Topic | Environment Variable | Producer | Consumer | Description |
| - | - | - | - | - |
| `ai.flowx.llm.config.changed.v1` | `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | organization-manager | integration-designer, AI Python services | Broadcast when LLM provider or model configuration changes at the organization level |

***

## Environment variables

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `ORGANIZATION_ID` | Organization UUID provided by FlowX. Required on all services for upgrades. Fresh installs get this automatically via the setup flow. | - | all services |
| `FLOWX_LICENSE_KEY` | License key for FlowX SaaS connection | - | license |
| `FLOWX_LICENSE_AUTHSERVERURL` | FlowX SaaS auth URL | - | license |
| `FLOWX_LICENSE_SERVERURL` | FlowX SaaS license API URL | - | license |
| `FLOWX_ORG_MANAGER_URL` | Organization Manager service URL for LLM provider configuration. Required on all Python AI services. | - | planner, ai-developer, ai-analyst, ai-designer, agent-builder, knowledgebase-rag, embedder, knowledgebase |
| `SECURITY_MASTERREALM_CLIENTID` | Master realm admin client ID for Keycloak management | `admin-cli` | authorization-system |
| `SECURITY_MASTERREALM_NAME` | Keycloak master realm name | `master` | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username for realm migrations | - | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password for realm migrations | - | authorization-system |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` | all services |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL for security lib | `http://organization-manager:80` | all services |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `60` | organization-manager |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `30` | organization-manager |
| `FLOWX_SPEECH_TO_TEXT_BASE_URL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` | integration-designer |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Topic for LLM config change notifications | `ai.flowx.llm.config.changed.v1` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys at rest. **Change from default in production.** | `default-dev-key-change-in-prod` | organization-manager |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required on on-prem deployments. | - | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required on on-prem deployments when the FlowX generic container app is deployed. | - | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If empty, derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` | organization-manager |
| `DEFAULT_ORGANIZATION_NAME` | Fallback organization code used by the Designer web app during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present. Required on on-prem — set to the organization code registered with FlowX. | - | designer |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for Oracle Database schema discovery responses cached for the SQL editor. | `24h` | integration-designer |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools used by Oracle Database data sources. | `100` | nosql-db-runner |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached JDBC connection pools. | `1d` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per Oracle Database data source. | `5` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout for Oracle Database data sources. | `10` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses for Oracle Database operations. | `1000` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout for Oracle Database operations. | `30` | nosql-db-runner |

### Removed environment variables

> [!WARNING]
>
> **For upgrades:** Remove these variables only **after** the Liquibase migrations have completed successfully. If you remove them before starting services for the first time on 5.7.0, the migrations may fail. The recommended sequence is: (1) add new variables, (2) deploy 5.7.0 images, (3) let migrations run, (4) verify services are healthy, (5) remove old variables in a follow-up deployment.

| Environment Variable | Reason | Component |
| - | - | - |
| `FLOWX_CLIENT_NAME` | Replaced by org code from registration | process-engine |
| `FLOWX_ENVIRONMENT_NAME` | Replaced by env name from registration | process-engine |
| `AI_SERVICE_MODELS_ENDPOINT` | The Models microservice (port 9104) has been removed. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers). Remove this service from your deployment. | ai-platform (all Python services) |
| `SECURITY_OAUTH2_REALM` | Replaced by per-organization realm resolution. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | Opaque-token introspection client no longer needed. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | Opaque-token introspection client secret no longer needed. | all services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_*` | Entire opaque-token introspection config removed. | all services |


# FlowX.AI 5.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/v5.7.0-april-2026

Single-org on-premises deployment, custom React components, AI providers self-service, chat-based UI Flows, voice input, end-user access management, and advanced query builder.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

FlowX.AI 5.7.0 makes on-premises deployment a first-class experience. **Single-org deployment** is now the default mode — configure your organization once, connect to FlowX licensing, and you're running. For builders, **Custom Components** let you write React code directly in the Designer, **AI Providers** configuration gives organizations self-service control over their LLM setup, and **Chat-based UI Flows** simplify conversational experiences. For organization admins, **End-user access management** separates runtime users, roles, and groups from Designer users.

> [card] [For platform teams](#single-org-deployment)
>
> Single-org deployment, license service, organization setup flow

> [card] [For builders](#custom-components)
>
> Custom React components, AI provider config, chat-based UI Flows, voice input

> [card] [For admins](#end-user-access-management)
>
> End-user access management, runtime roles, and groups

### What changed since 5.6.0

| 5.6.0 | 5.7.0 |
| - | - |
| SaaS-focused deployment | + **Single-org on-premises** as the default mode |
| Built-in UI components only | + **Custom React Components** with code editor and dependencies |
| AI models configured by FlowX | + **AI Providers self-service**: OpenAI (FlowX Managed or BYOK), custom URL, Defaults & Fallbacks per workspace type |
| Chat workflow set per component | + **Chat-based UI Flows**: set one workflow for the entire UI Flow |
| Text-only chat input | + **Voice input** for chat conversations |
| No audio processing in workflows | + **Speech to Text** node for transcription and text-to-speech |
| Runtime users mixed with Designer users | + **End-user access management**: separate org-level lists for end-users, roles, and groups, with CSV bulk invite |
| Basic query filters | + **Advanced Query Builder** for database operations |
| MongoDB-only database data sources | + **Oracle Database** as a new data source type with schema-aware SQL editor |
| Fixed search strategy for KB retrieval | + **Context Retrieval**: configurable search type (Hybrid/Semantic/Keyword) and re-ranking |
| Equality-only metadata filters, AND logic | + **Knowledge Base filter builder** with typed operators and AND/OR grouping; **Content Sources** tab renamed to **Stores** |
| Basic merge modal | + **Merge conflicts UX**: redesigned modal, diff viewer theme, keyboard support |

***

**What's new?**

> [tab] Platform
>
> FlowX 5.7.0 introduces single-org deployment as the default mode for on-premises installations, with self-service licensing, organization management, and runtime access controls.
>
> 🏢 [**Single-org deployment**](#single-org-deployment) - On-premises deployment with automatic organization setup\
> 🔑 [**License service**](#license-service) - Connect to FlowX SaaS for license validation and usage reporting\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level end-users, roles, and groups, separate from Designer users
>
> ### **Single-org deployment**
>
> > [card] Single-org deployment
> >
> > > [tab] Overview
> > >
> > > Self-hosted deployments now run as single-organization systems by default. FlowX registers your organization in the SaaS licensing infrastructure, provides an Organization ID, and your deployment connects to FlowX for license validation and usage reporting. The Designer guides you through a setup flow on first launch: enter a token, name your environment, and create your admin user.
> > >
> > > > [card] [Documentation](/5.1/setup-guides/organization-manager-setup#organization-id-configuration)
> > > >
> > > > See the Organization Manager setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Guided setup flow
> > > >
> > > > Designer walks you through organization registration on first launch
> > >
> > > > [card] Organization ID
> > > >
> > > > Mandatory on all services for Liquibase migrations on upgrades
> > >
> > > > [card] License connectivity
> > > >
> > > > On-premises license service connects to FlowX SaaS for validation and usage
> > >
> > > > [card] Multi-org features hidden
> > > >
> > > > Registration, org selection, and org switching are not available on-prem
> > >
> > > > [card] Explicit web app URLs
> > > >
> > > > Designer and Runtime URLs are configured via dedicated on-prem env vars on organization-manager, replacing hard-coded org-code lookup
> >
> > Major FeatureSelf-Hosted
>
> ***
>
> ### **License service**
>
> > [card] License service
> >
> > > [tab] Overview
> > >
> > > The License service is the bridge between your self-hosted deployment and FlowX SaaS. It validates your platform license, reports usage data, and ensures your subscription is active. Configure it with the license key and server URLs provided by FlowX during organization registration.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> > > >
> > > > See the License service setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] License validation
> > > >
> > > > Continuous license sync with FlowX SaaS
> > >
> > > > [card] Usage reporting
> > > >
> > > > AI node execution consumption reported to FlowX
> > >
> > > > [card] Organization events
> > > >
> > > > Listens to organization lifecycle events via Kafka
> > >
> > > > [card] Setup guide
> > > >
> > > > Complete setup guide with PostgreSQL, Kafka, Redis, and SpiceDB configuration
> >
> > Self-Hosted
>
> ***
>
> ### **End-user access management**
>
> > [card] End-user access management
> >
> > > [tab] Overview
> > >
> > > Organization admins can now manage the people who use published solutions separately from Designer users. A new **Access Management** section at the organization level holds three lists — **End-Users**, **End-Users Roles**, and **End-Users Groups** — each with its own permissions. Invite end users individually or import many at once from a CSV template, define roles that describe runtime access, and organize users into groups with custom attributes for filtering.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> > > >
> > > > See the End-user access management setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Separate end-user list
> > > >
> > > > End-Users are kept distinct from Designer users, with their own read/write permissions
> > >
> > > > [card] End-user roles
> > > >
> > > > Define named roles that describe runtime access at the organization level
> > >
> > > > [card] End-user groups
> > > >
> > > > Group users by department, region, or any attribute, and assign roles to the whole group
> > >
> > > > [card] Bulk invite
> > > >
> > > > Invite many users at once from a CSV template with names and attributes
> >
> > All Deployments
>
> ***

> [tab] AI & Chat
>
> Self-service AI provider configuration, chat-based UI Flows, AI Triggers, and voice input for conversational experiences.
>
> 🤖 [**AI Providers**](#ai-providers) - Organization-level LLM provider and model configuration\
> 💬 [**Chat-based UI Flows**](#chat-based-ui-flows) - Set a conversational workflow for the entire UI Flow\
> 🎤 [**Voice input**](#voice-input) - Speech-to-text input in chat conversations\
> ⏹️ [**Stop agent response**](#stop-agent-response) - Cancel an in-progress agent reply from the chat input\
> 🗣️ [**Speech to Text node**](#speech-to-text-node) - Transcription and text-to-speech workflow node\
> ⚡ [**AI Triggers**](#ai-triggers) - Named message templates for launching conversational workflows with context\
> 🧩 [**UI Flow Context**](#ui-flow-context) - Pass UI state from a Page to a conversational workflow\
> 🎯 [**Recommended prompts**](#recommended-prompts) - AI-generated follow-up suggestions in chat conversations\
> 🔎 [**Context Retrieval enhancements**](#context-retrieval-enhancements) - Configurable search type and re-ranking\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - Stores rename, typed metadata filters, AND/OR grouping\
> 🌐 [**Web Page Extractor enhancements**](#web-page-extractor-enhancements) - URL filtering, crawl depth, and file downloads
>
> ### **AI Providers**
>
> > [card] AI Providers
> >
> > > [tab] Overview
> > >
> > > Organizations can now configure their own AI providers and assign models at the organization level. Configure **OpenAI** (Bring Your Own Key or FlowX Managed) or **Azure OpenAI** for deployment-based access to GPT models, enable specific models, and assign default and fallback models per AI capability and workspace type (Sandbox, Staging, Production). **Defaults & Fallbacks** now includes an **Audio Capabilities** row used by the Speech to Text node, with `whisper-1` available in the OpenAI model catalog.
> > >
> > > ![Model Providers page with OpenAI and Azure OpenAI configured at the organization level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_view_org.png)
> > >
> > > ![Provider Details modal showing OpenAI and Azure OpenAI as provider options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_model_Provider.png)
> > >
> > > ![Defaults and Fallbacks page with capability rows including Audio Capabilities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/defaults_and_fallbacks.png)
> > >
> > > ![Model selection and configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ai_models_selection.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/ai-providers)
> > > >
> > > > See the AI providers and model configuration documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Organization-level providers
> > > >
> > > > Add and manage AI providers with API keys and connection settings
> > >
> > > > [card] Azure OpenAI
> > > >
> > > > Connect to Azure-hosted OpenAI deployments with a base URL and API version
> > >
> > > > [card] Custom model entry
> > > >
> > > > Add models manually for providers that use deployment names (Azure) or non-public catalogs
> > >
> > > > [card] Audio Capabilities
> > > >
> > > > New row in Defaults & Fallbacks for transcription and speech synthesis, used by the Speech to Text node
> > >
> > > > [card] Defaults & Fallbacks
> > > >
> > > > Assign default and fallback models per AI capability and workspace type
> > >
> > > > [card] Fallback strategy
> > > >
> > > > Set fallback models on different providers for resilience
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat-based UI Flows**
>
> > [card] Chat-based UI Flows
> >
> > > [tab] Overview
> > >
> > > UI Flows now support two experience types: **Flow-Based** (traditional) and **Chat-Based** (conversational). Chat-Based UI Flows connect to a conversational workflow at the UI Flow level, so all Chat components in the flow use the same workflow by default. A new Settings page with a Chat Options tab lets you configure or change the workflow after creation.
> > >
> > > ![Chat-based UI Flow configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_based_ui_flow.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> > > >
> > > > See the UI Flows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Experience types
> > > >
> > > > Choose Flow-Based or Chat-Based when creating a UI Flow
> > >
> > > > [card] UI Flow Settings
> > > >
> > > > New Settings page with Chat Options tab for workflow configuration
> > >
> > > > [card] Workflow filtering
> > > >
> > > > Chat components only show conversational workflows in the selector
> > >
> > > > [card] Navigate in UI Flow
> > > >
> > > > AI can open specific screens with parameters from a conversation
> >
> > All Deployments
>
> ***
>
> ### **Chat improvements**
>
> > [card] Chat improvements
> >
> > Configure which parts of the chat header are visible on a per-component basis. The Chat component (when display type is **Fill**) gains a **Show Header** toggle in its Properties panel, and the Chat Header component gets a new **Available Actions** accordion with toggles for **New Conversation** and **History**. Conversation history now loads in pages, with a **Load more** action, and conversations are sorted by creation date with the most recent first.
> >
> > All Deployments
>
> ***
>
> ### **Voice input**
>
> > [card] Voice input
> >
> > > [tab] Overview
> > >
> > > Chat components now support voice input, allowing users to record audio messages directly in the chat. Users can record, preview with an audio player, and send voice messages within conversations.
> > >
> > > > [!NOTE]
> > > >
> > > > Voice input captures and sends audio recordings. When paired with the [Speech to Text](/5.9/ai-platform/agent-builder/speech-to-text) workflow node, voice messages are automatically transcribed and processed as text in conversational workflows.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audio recording
> > > >
> > > > Record voice messages directly in the chat input
> > >
> > > > [card] Audio preview
> > > >
> > > > Preview recordings with a built-in audio player before sending
> >
> > All Deployments
>
> ***
>
> ### **Stop agent response**
>
> > [card] Stop agent response
> >
> > > [tab] Overview
> > >
> > > The chat input now shows a **Stop** button in place of Send while an agent reply is streaming. Pressing Stop cancels the conversational workflow instance: any in-flight AI call is aborted, partial output is discarded, and the user prompt is persisted with a `cancelled` flag so the chat history reflects what happened.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Cross-platform
> > > >
> > > > Available on Web (Standard, Floating, Full Screen), iOS, and Android
> > >
> > > > [card] Themeable
> > > >
> > > > New `stopResponseIcon` slot in `chatInputArea` themes; preloaded by cms-core
> > >
> > > > [card] Localized
> > > >
> > > > New system substitution tags for Stop and Send labels with a11y variants
> >
> > All Deployments
>
> ***
>
> ### **Speech to Text node**
>
> > [card] Speech to Text
> >
> > > [tab] Overview
> > >
> > > A new workflow node that converts between audio and text. **Transcribe** converts audio files (MP3, WAV, M4A, AAC, OGG) into text with language detection and confidence scores. **Text to Speech** generates audio files from text with configurable voice, speed, and format. In conversational workflows, the node processes voice messages from the chat UI automatically.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> > > >
> > > > See the Speech to Text node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Transcription
> > > >
> > > > Convert audio to text with language detection and confidence scores
> > >
> > > > [card] Text to Speech
> > > >
> > > > Generate audio from text with configurable voice, model, speed, and format
> > >
> > > > [card] Chat voice integration
> > > >
> > > > Automatically transcribes voice messages in conversational workflows
> > >
> > > > [card] Multiple file sources
> > > >
> > > > Read from Document Plugin, S3, or chat input
> >
> > > [!NOTE]
> > >
> > > The transcription model is resolved from the organization's **Audio** capability default, configured in **AI Settings** under [Defaults & Fallbacks](/5.9/ai-platform/ai-providers).
> >
> > All Deployments
>
> ***
>
> ### **AI Triggers**
>
> > [card] AI Triggers
> >
> > > [tab] Overview
> > >
> > > Define named message templates with parameters on conversational workflows, so different UI Flow pages can launch the same workflow with different starting contexts. Triggers are configured in a dedicated side nav tab and selected on the Start node or sent from the Chat component at runtime.
> > >
> > > ![Reply Triggers list in a conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_reply_trigger.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Parameterized messages
> > > >
> > > > Message templates with `${paramName}` placeholders resolved at runtime
> > >
> > > > [card] Multi-page reuse
> > > >
> > > > Different pages launch the same workflow with different context
> > >
> > > > [card] Start node integration
> > > >
> > > > Toggle between Text and AI Trigger modes on the Start node
> > >
> > > > [card] Memory aware
> > > >
> > > > Trigger messages saved to conversation memory but hidden from chat history
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Context**
>
> > [card] UI Flow Context
> >
> > > [tab] Overview
> > >
> > > Conversational workflows can now receive a JSON context alongside the user message. A new **Conversation Context** property on UI Flow Pages lets you define the Parameters payload (with `${expression}` resolution), and the Start node exposes it as a collapsible **UI Flow Context** editor — also available in the Run Workflow test modal for manual runs.
> > >
> > > ![Start node UI Flow Context and UI Flow Conversation Context property](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#setting-context-from-a-ui-flow)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] UI-driven context
> > > >
> > > > Pages attach a JSON payload to conversational runs without hard-coding it in the workflow
> > >
> > > > [card] Expression resolution
> > > >
> > > > Parameters support `${expression}` syntax to bind live UI Flow data at runtime
> > >
> > > > [card] Start node field
> > > >
> > > > Collapsible UI Flow Context editor on the Start node for both runtime and manual testing
> > >
> > > > [card] JSON validation
> > > >
> > > > Invalid JSON is rejected before the run starts, surfacing a clear error
> >
> > All Deployments
>
> ***
>
> ### **Recommended prompts**
>
> > [card] Recommended prompts
> >
> > > [tab] Overview
> > >
> > > Custom Agent nodes can now generate follow-up prompt suggestions alongside their chat replies. When enabled via the new **Prompt Suggestions** satellite panel on a Custom Agent node, the agent includes recommended next questions or actions in its response. These appear as clickable suggestions in the chat UI, guiding users toward relevant follow-up interactions.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions)
> > > >
> > > > See the Custom Agent node documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Satellite panel
> > > >
> > > > Configure prompt suggestions directly on Custom Agent nodes in the workflow editor
> > >
> > > > [card] AI-generated suggestions
> > > >
> > > > Agent generates contextual follow-up prompts based on the conversation
> > >
> > > > [card] Clickable in chat
> > > >
> > > > Suggestions render as tappable chips in the chat UI
> > >
> > > > [card] Conversational workflows
> > > >
> > > > Works with send-as-reply mode in conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval enhancements**
>
> > [card] Context Retrieval enhancements
> >
> > > [tab] Overview
> > >
> > > **Custom Agent** and **Context Retrieval** nodes now support configurable **search type** and **re-ranking** for Knowledge Base retrieval. Choose between Hybrid (default), Semantic, or Keyword search strategies depending on your use case. Turn on re-ranking to apply a secondary relevance model that reorders retrieved chunks for higher-quality results.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the Context Retrieval node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Search type
> > > >
> > > > Choose Hybrid, Semantic, or Keywords search for Knowledge Base retrieval on Custom Agent and Context Retrieval nodes
> > >
> > > > [card] Re-ranking
> > > >
> > > > Apply a re-ranking model to reorder results by relevance to the query — available on both Custom Agent and Context Retrieval nodes
> >
> > All Deployments
>
> ***
>
> ### **Knowledge Base enhancements**
>
> > [card] Knowledge Base enhancements
> >
> > > [tab] Overview
> > >
> > > The Knowledge Base data source gets a refreshed workspace and a more powerful metadata filter builder. The **Content Sources** tab is now called **Stores**, and the Chunks tab gains a structured query builder for metadata filters with typed operators, AND/OR logic, and grouping — replacing the previous equality-only filters.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > > >
> > > > See the Knowledge Base content management guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Stores tab
> > > >
> > > > The Content Sources tab is renamed to Stores. Same concept, clearer label.
> > >
> > > > [card] Typed filter operators
> > > >
> > > > Operators per metadata type: equals, not equals, contains, in, not in, before, after, exists, size equals, and more
> > >
> > > > [card] AND/OR grouping
> > > >
> > > > Combine conditions with AND or OR and nest them in groups for non-trivial logic
> > >
> > > > [card] Query builder on Chunks tab
> > > >
> > > > Test retrieval with Search Type (Hybrid/Semantic/Keywords), Use Re-rank, and the new filter builder
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor enhancements**
>
> > [card] Web Page Extractor enhancements
> >
> > > [tab] Overview
> > >
> > > The Web Page Extractor node now supports **URL filtering** to include or exclude specific URL patterns during crawling, **configurable crawl depth** for more control over how deep the crawler follows links, and **file downloads** to retrieve attached files from crawled pages.
> >
> > > [tab] Key Features
> > >
> > > > [card] URL filtering
> > > >
> > > > Include or exclude URLs matching specific patterns during crawling
> > >
> > > > [card] Crawl depth
> > > >
> > > > Configure how many levels deep the crawler follows links
> > >
> > > > [card] File downloads
> > > >
> > > > Download attached files from crawled web pages
> > >
> > > > [card] Bulk document type
> > > >
> > > > When file downloads are enabled, the document type auto-sets to **Bulk** so a single crawl can return multiple documents
> >
> > All Deployments
>
> ***

> [tab] UI & Components
>
> Custom React components, advanced query builder, and merge conflict improvements.
>
> 🧩 [**Custom Components**](#custom-components) - Write React code in Designer and use in UI Flows\
> 🔍 [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder for database operations\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor\
> 🔀 [**Merge conflicts UX**](#merge-conflicts-ux) - Improved merge modal and conflict resolution experience
>
> ### **Custom Components**
>
> > [card] Custom Components
> >
> > > [tab] Overview
> > >
> > > Create custom React components directly in FlowX Designer. Write JSX, CSS, and use pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Components receive process data through input keys and can trigger process actions. Define once in Reusable Resources, use across multiple User Tasks.
> > >
> > > ![Custom Components code editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> > > >
> > > > See the Custom Components documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Code editor
> > > >
> > > > Write React JSX and CSS with a built-in code editor and file tree
> > >
> > > > [card] Pre-defined packages
> > > >
> > > > React, Emotion, Lodash, Axios, and date-fns available out of the box
> > >
> > > > [card] Process integration
> > > >
> > > > Receive process data via input keys and trigger process actions
> > >
> > > > [card] Import/Export
> > > >
> > > > Export as ZIP and import into other projects
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Advanced Query Builder**
>
> > [card] Advanced Query Builder
> >
> > > [tab] Overview
> > >
> > > A visual query builder for database operations and metadata filters, replacing manual JSON query writing with a structured interface. Build complex queries with conditions, grouping, and sorting without writing raw queries. The operator set has expanded with NULL checks (`exists`, `is null`), set membership (`not in`), string matching (`contains`, `starts with`, `ends with`), boolean tests (`is true`, `is false`), and date comparators (`before`, `after`). The `between` operator has been removed from the UI.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> > > >
> > > > See the FlowX Database documentation for the full query builder reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] Visual conditions
> > > >
> > > > Build query conditions with a structured UI instead of raw JSON
> > >
> > > > [card] Grouping and sorting
> > > >
> > > > Combine conditions with AND/OR grouping and configure result sorting
> > >
> > > > [card] Schema awareness
> > > >
> > > > Fields auto-populated from your collection schema with type-aware operators
> > >
> > > > [card] Visual/Script toggle
> > > >
> > > > Switch between visual builder and raw code editor at any time
> >
> > All Deployments
>
> ***
>
> ### **Oracle Database integration**
>
> > [card] Oracle Database integration
> >
> > > [tab] Overview
> > >
> > > Connect FlowX workflows to externally managed Oracle databases. Configure a connection (Oracle 19c, 21c, or 23ai), save parameterized SQL queries against the schema, and call them from the existing Database Operation node alongside other data sources.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> > > >
> > > > See the Oracle Database integration guide for the full reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] SERVICE\_NAME or SID
> > > >
> > > > Connect via Service Name or SID, with an optional SSL toggle
> > >
> > > > [card] Schema-aware SQL editor
> > > >
> > > > Monaco editor with syntax highlighting, autocomplete, and a side panel for tables, columns, primary keys, and foreign keys
> > >
> > > > [card] Test queries inline
> > > >
> > > > Run SQL with sample parameters: table view for SELECT, affected-row count for INSERT, UPDATE, and DELETE
> > >
> > > > [card] Workflow integration
> > > >
> > > > Pick the Oracle data source and query from the Database Operation node, with no new node type required
> >
> > All Deployments
>
> ***
>
> ### **Datasource Experience**
>
> > [card] Datasource Experience
> >
> > The **Add Data Source** dialog now groups data source types into four categories (**AI Capabilities**, **APIs**, **Databases**, and **Connectors**) with a search box for finding a specific type. REST endpoint authoring also suggests common HTTP headers and values to speed up integration setup.
> >
> > ![New Add Data Source dialog with categorized data source types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_new_data_source.png)
> >
> > All Deployments
>
> ***
>
> ### **MongoDB-aware code editor**
>
> > [card] MongoDB-aware code editor
> >
> > Operation editors on MongoDB data sources now use a Monaco language provider tuned for MongoDB. The editor highlights MongoDB operators (Comparison, Logical, Element, Evaluation, Array, Update, Aggregation, Conditional) and `${param}` interpolations, including inside string literals. Three autocomplete flows speed up authoring: typing `$` lists MongoDB operators, opening a quote in a field-name position lists the schema field paths from the linked Project Data Type, and typing inside `${...}` lists the operation's parameter keys.
> >
> > All Deployments
>
> ***
>
> ### **Project Data Model authoring**
>
> > [card] Project Data Model authoring
> >
> > Three improvements make Project Data Model authoring easier and less error-prone.
> >
> > > [card] Go to source
> > >
> > > A new **Go to source** button on data-model usages and Data Model nodes jumps directly to the source definition without manual navigation.
> >
> > > [card] Type-aware example values
> > >
> > > The example-value input on each attribute now matches its declared type: number inputs for NUMBER, a date picker for DATE, a true/false dropdown for BOOLEAN, single-select for enums, multi-select chips for enum arrays, and so on. CURRENCY values use the currency code rather than the symbol.
> >
> > > [card] Type-aware test data
> > >
> > > The same type-aware inputs apply when running or testing a workflow node and when filling input parameters for a reusable function, replacing the previous generic text inputs.
> >
> > All Deployments
>
> ***
>
> ### **Stop Run for workflows**
>
> > [card] Stop Run for workflows
> >
> > You can now cancel a running workflow instance directly from the workflow editor. While a workflow is running, the **Run Workflow** button switches to **Stop Run** — clicking it cancels the instance and marks all in-progress and scheduled nodes as cancelled. Cancelled instances show a new **Cancelled** status alongside Started, Finished, and Failed.
> >
> > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#running-and-stopping-workflows)
> > >
> > > See Running and stopping workflows in the Integration Designer reference.
> >
> > All Deployments
>
> ***
>
> ### **Merge conflicts UX**
>
> > [card] Merge conflicts UX
> >
> > The merge branches experience has been improved with a redesigned merge modal, better form validation with detailed error messages, and keyboard support (submit with Enter). The conflict resolution diff viewer now uses a new CodeMirror theme that matches the Monaco editor styling for a consistent visual experience.
> >
> > All Deployments
>
> ***

> [tab] Bug fixes
>
> ## Bug fixes
>
> ### AI Platform
>
> | Issue | Description |
> | - | - |
> | Custom Agent WebSocket stability | Fixed WebSocket 1006 abnormal closure for Custom Agent nodes with large payloads by upgrading AI SDK to handle Spring Framework 7's 64KB frame aggregation limit |
> | Azure OpenAI structured output | Fixed silent hang on Azure OpenAI for Custom Agents, Intent Classification, and Recommended Prompts when the response JSON schema lacked title and description fields |
> | Custom Agent node stuck | Fixed Custom Agent node getting stuck in running state |
> | MCP tool updates not working | Fixed an issue where updating tools on an existing MCP Server did not persist changes |
> | KB append performance | Fixed slow execution of the Append Knowledge Base node |
> | KB chunking on append | Fixed an issue where appended content via JSON in the Update Knowledge Base node was not chunked |
> | REST node with base64 certificate | Fixed error when running a workflow with a REST node using a REST system with a base64 certificate |
> | Workflow dependencies copy | Fixed dependencies not being copied for already-copied workflows |
>
> ### Core Platform
>
> | Issue | Description |
> | - | - |
> | Import pipeline issues | Fixed API issues in the import pipeline |
> | Enum CSV import losing changes | Fixed an issue where importing enumerations via CSV on committed resources did not update the resource modified date, causing changes to appear lost |
> | Data model duplicate key on import | Fixed a MongoDB duplicate key error when importing data model slices with duplicate entries |
> | Config params page not loading | Fixed GET config params endpoint not being called when accessing the Configuration Parameters page |
> | Enum default values dropdown | Fixed only first-level enum objects being displayed in the default values dropdown |
> | Data model loading state | Fixed user getting stuck in loading state after an error on data model keep operation |
>
> ### UI & Renderers
>
> | Issue | Description |
> | - | - |
> | Select component clear icon | Fixed misaligned clear icon on Select components in both Angular and React renderers |

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > **Self-hosted deployments:** FlowX 5.7.0 introduces the Organization ID as a mandatory configuration on all services. See the [deployment guidelines](./deployment-guidelines-v5.7) for complete upgrade instructions.
>
> ### Compatibility
>
> > [card] [Upgrade path](./deployment-guidelines-v5.7#supported-upgrade-paths)
> >
> > See the deployment guidelines for supported upgrade paths from 5.1.x LTS, 5.2–5.4, and 5.5–5.6.
>
> > [card] [Component versions](./deployment-guidelines-v5.7#component-versions)
> >
> > See the deployment guidelines for the full component version matrix and third-party dependency support.


# Deployment guidelines v5.8.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/deployment-guidelines-v5.8

Component versions, environment variables, and configuration changes for FlowX.AI 5.8.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.106.0** | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 |
| **admin** | **10.93.0** | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 |
| **designer** | **10.181.0** | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 |
| **cms-core** | **10.67.0** | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 |
| **scheduler-core** | **10.53.0** | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 |
| **events-gateway** | **10.55.0** | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 |
| **notification-plugin** | **10.64.0** | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 |
| **document-plugin** | **10.75.0** | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 |
| **task-management-plugin** | **10.66.0** | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 |
| **data-search** | **10.52.0** | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 |
| **audit-core** | **10.63.0** | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 |
| **advancing-controller** | **10.55.0** | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 |
| **integration-designer** | **10.128.0** | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 |
| **application-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **runtime-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **data-sync** | **10.58.0** | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 |
| **authorization-system** | **10.77.0** | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 |
| **nosql-db-runner** | **10.56.0** | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 |
| **email-gateway** | **10.56.0** | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 | - |
| **organization-manager** | **10.53.0** | 10.44.0 | 10.26.1 | 10.19.2 | - | - |
| **webhook-gateway** | **10.25.0** | 10.15.0 | 10.1.1 | - | - | - |
| **license** | **10.46.0** | 10.36.0 | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |

### Plugins

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 |
| **ai-platform-ai-assistant** | **10.7.0** | 10.6.2 | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **ai-platform-ai-developer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-connected-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-knowledge-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agents** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-conversations** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-tenants** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-analyst** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-designer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agent-builder** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-binaries** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **embedder** | **10.7.0** | 10.6.2 | - | - | - |
| **knowledgebase-rag** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **knowledgebase-indexer-v2** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **mcp** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **doc-parser** | **10.7.0** | 10.6.2 | 10.5.1 | - | - |
| **web-crawler** | **10.3.5** | 10.3.2 | - | - | - |
| **data-privacy** | **10.1.0** | 10.0.8 | - | - | - |
| **speech-to-text** | 10.3.3 | 10.3.3 | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | - | - | - |

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.8.0 | Keycloak | 26+ |
| 5.8.0 | Kafka | 3.8 - 3.9 |
| 5.8.0 | PostgreSQL | 16 - 17 |
| 5.8.0 | Oracle Database | 21c, 23ai |
| 5.8.0 | MongoDB | 7 - 8 |
| 5.8.0 | Redis | 7.4 - 8.0 |
| 5.8.0 | Elasticsearch | 8 |
| 5.8.0 | Angular (Web SDK) | 20 |
| 5.8.0 | React (Web SDK) | 18.x |

***

## Self-hosted deployment changes

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **5.7.0** | Supported | Standard upgrade. |
| **5.1.x LTS** | Supported | Direct upgrade from 5.1.x to 5.8.0 is supported. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

***

## Kafka integration changes

### New Kafka topics

| Topic | Producer | Producer env var | Consumer | Consumer env var |
| - | - | - | - | - |
| `ai.flowx.license.events.v1` | organization-manager | `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | license | `KAFKA_TOPIC_LICENSE_IN_EVENTS` |
| `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | admin | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` | knowledgebase-indexer-v2 | n/a (Python constant) | embedder | n/a (Python constant) |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` | embedder | n/a (Python constant) | knowledgebase-indexer-v2 | n/a (Python constant) |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | (no env var; resolved from `kafka.topic.naming.*`) | document-plugin | `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` |

**License lifecycle events** are delivered from FlowX SaaS to the on-prem license service.

**Custom-component correction requests** complement the existing process / business-rule / reusable-template / ui-flow correction topics that the admin orchestrator already consumed.

**UI Flow multi-file upload** sends a single bulk command to document-plugin in place of the per-file pattern. The plugin persists each file in the session, emits one SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) at the end of the batch via events-gateway, and forwards per-file results to the existing `ai.flowx.core.trigger.ui-flow.update.v1` topic.

**KB embedding-request / embedding-response** replace the previous gRPC `EmbedderService` path (`BulkGenerateEmbeddings` / `GenerateEmbeddings`); the indexer now publishes one embedding job per chunk and the embedder writes points to Qdrant directly, emitting `KbStoreEntryStateChanged` once all chunks for an entry are persisted.

> [!NOTE]
>
> The two `core-services` topic names (`license.events`, `application-version.correction-after-app-operation.custom-component.request`) resolve from the standard `${kafka.topic.naming.prefix}` / `${kafka.topic.naming.suffix}` machinery: default prefix `ai.flowx.` (empty environment segment), default suffix `.v1`. Operators that want an environment-prefixed topic name (e.g., `ai.flowx.dev.license.events.v1`) set `kafka.topic.naming.environment` globally rather than overriding individual topics. The two AI Platform topics are hard-coded constants in the indexer and embedder and do not participate in the prefix machinery.

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX. Initialized with the `notset` sentinel; replace it with the value FlowX provides before the license service starts. Type changed from UUID to String in 5.8.0. | `notset` | license |
| `KAFKA_CONSUMER_GROUPID_LICENSE_EVENTS` | Kafka consumer group used by the license service to receive license events. | `license-events` | license |
| `KAFKA_CONSUMER_THREADS_LICENSE_EVENTS` | Listener container concurrency for the license-events consumer. | `1` | license |
| `KAFKA_TOPIC_LICENSE_IN_EVENTS` | License events topic consumed by the license service. | `ai.flowx.license.events.v1` | license |
| `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | Same topic, producer-side binding on organization-manager. | `ai.flowx.license.events.v1` | organization-manager |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | Custom-component correction-request topic, producer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` | Same topic, consumer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | admin |
| `MANAGEMENT_HEALTH_REDIS_TIMEOUT` | Spring Boot Actuator timeout for the Redis health indicator (in ms). | `5000` | all services using Redis |
| `SPRING_CACHE_REDIS_PERSISTENCEKEYPREFIX` | Prefix applied to Redis keys for the advancing-controller cache. | `flowx:core:cache:advancing-controller:` | advancing-controller |
| `REDIS_COMMAND_TIMEOUT` | Redis command timeout in ms. Fail-fast during master failover. Bound via `${REDIS_COMMAND_TIMEOUT:5000}` placeholder on `spring.data.redis.timeout`. | `5000` | all services using Redis |
| `REDIS_CONNECT_TIMEOUT` | Redis connection establishment timeout in ms. Bound via `${REDIS_CONNECT_TIMEOUT:5000}`. | `5000` | all services using Redis |
| `REDIS_POOL_MAX_ACTIVE` | Maximum number of active Redis connections in the pool. | `10` | all services using Redis |
| `REDIS_POOL_MAX_IDLE` | Maximum number of idle Redis connections retained in the pool. | `5` | all services using Redis |
| `REDIS_POOL_MIN_IDLE` | Minimum number of idle Redis connections kept warm in the pool. | `1` | all services using Redis |
| `REDIS_POOL_MAX_WAIT` | Maximum time to wait for an available connection from the pool, in ms. | `2000` | all services using Redis |
| `FLOWX_METRICS_STUCKCHECKINTERVALMS` | Interval at which the stuck-events metric scheduler runs (ms). Bound from the inline `@Value("${flowx.metrics.stuck-check-interval-ms:60000}")` default; not in `application.yml`. | `60000` | advancing-controller |
| `FLOWX_METRICS_STUCKTHRESHOLDMINUTES` | Age threshold (in minutes) above which an advancing event is considered stuck. Bound from `@Value("${flowx.metrics.stuck-threshold-minutes:5}")`. | `5` | advancing-controller |
| `FLOWX_DATAPRIVACY_BASEURL` | Base URL for the new Data Privacy service. Required when any AI workflow node enables the Personal Information Guard. | `http://data-privacy:80` | integration-designer |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60` | integration-designer |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. Producer-side is the matching `kafka.topic.session.upload.bulk.out` on process-engine, which resolves from the standard naming machinery. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | document-plugin |

### Removed environment variables

| Environment Variable | Replaced by | Component |
| - | - | - |
| `FLOWX_SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Removed with the move to single-pod scheduler execution (plat-1549, `commons-scheduler-lib`). No replacement; only one scheduler pod runs now. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_ENABLED` | Same. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_PROVIDER` | Same. | application-manager, license |
| `SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Same. | integration-designer, process-engine |

***


# FlowX.AI 5.8.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/v5.8.0-may-2026

Runtime authorization overhaul, UI Flow permissions, Custom Components in Processes, new theme components, Angular bulk file upload, and webhook provider adapters.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

Sharing a FlowX solution used to mean handing out admin keys. **5.8.0 changes that.** The AI Developer now ships the React component you wished you'd had time to build, PII never reaches your LLM by accident, and you can finally invite a reviewer without giving them the platform.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html)

### What changed since 5.7.0

| 5.7.0 | 5.8.0 |
| - | - |
| End-user access management with org-level roles and groups | + **Runtime authorization** with project-version-scoped roles, groups, and attribute-based assignment |
| UI Flows accessible to any runtime user | + **UI Flow permissions**: assign roles per UI Flow, evaluated at runtime |
| Custom Components in UI Flows only (Phase 1, React) | + **Custom Components in Processes** with shared data model, input/output mappings, and AI Developer generation |
| Built-in UI components | + **Tooltip, Markdown, Progress Bar, Separator** as new theme components |
| React-only multi-file upload | + **Angular SDK bulk file upload** |
| Generic webhook gateway | + **Webhook provider adapters** (Slack, with HMAC signing-secret validation) |
| Oracle Database (basic SQL editor) | + **Richer SQL autocomplete** in the Monaco editor: operators, schema-aware tables/columns, and `:paramName` interpolations |
| No personal-information guardrails on AI workflow nodes | + **PII Guard** with input/output scans, sensitivity presets, and an entity catalog |

***

**What's new?**

> [tab] Platform
>
> 🔐 [**Runtime authorization**](#runtime-authorization) - Project-scoped roles, end-user groups in FlowX, and Solutions → Share flow\
> 📋 [**UI Flow permissions**](#ui-flow-permissions) - Role-based UI Flow visibility with runtime enforcement

> [tab] Builders
>
> 🧩 [**Custom Components in Processes**](#custom-components-in-processes) - Bundled CCs in Process User Tasks with shared data model\
> 🎨 [**New UI components**](#new-ui-components) - Tooltip, Markdown, Progress Bar, Separator\
> 📥 [**Angular bulk file upload**](#angular-bulk-file-upload) - Multi-file upload component for the Angular SDK\
> 📦 [**UI Flow multi-file upload backend**](#ui-flow-multi-file-upload-backend) - Single bulk endpoint and one completion SSE event for batch uploads\
> 🪝 [**Webhook provider adapters**](#webhook-provider-adapters) - Slack inbound webhook support with HMAC signing\
> 🗄️ [**Richer SQL autocomplete**](#richer-sql-autocomplete) - Monaco editor enhancements for the Oracle data source SQL editor\
> 🧱 [**Data source UX redesign**](#data-source-ux-redesign) - Tile-based creation, type filters, unified settings, save with incomplete config\
> ➕ [**Context menu adds UI components in Processes**](#context-menu-adds-ui-components-in-processes) - Right-click Add UI component in Process User Tasks and Reusable UI Templates\
> 👆 [**Pointer cursor on actionable elements**](#pointer-cursor-on-actionable-elements) - Web renderers show pointer on action-bound components

> [tab] AI Platform
>
> 🛡️ [**PII Guard**](#pii-guard) - Personal information identification on AI inputs\
> 🤖 [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent now drafts Custom Component code\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - System metadata keys, Kafka indexer→embedder, Qdrant export/delete, error handling\
> 🌐 [**Web Crawler multi-URL filters**](#web-crawler-multi-url-filters) - Multiple URL filters per crawler config

### **Runtime authorization**

> [card] Runtime authorization overhaul
>
> > [tab] Overview
> >
> > **Before 5.8.0:** a role on a user matched every project that role appeared in. **Now:** roles live at the project version, sharing is explicit, and Designer users still bypass runtime so they can demo without standing up test accounts.
> >
> > Runtime access is reorganized around the project. Roles live at the **project version**, each org has a managed catalog of **end-user groups**, and access flows through a **Solutions → Share** modal. FlowX retains authentication and external-IDP federation in Keycloak; runtime roles, end-user groups, and project-scoped sharing live in FlowX itself, evaluated by a custom runtime authorization service tuned for the volume of runtime permission checks. SpiceDB remains the design-time permission engine for Designer access.
> >
> > > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> > >
> > > See Setup guides → Access management → Runtime authorization.
>
> > [tab] Key Features
> >
> > > [card] Project-scoped roles
> > >
> > > Each project version declares the runtime roles required to operate it. Roles are org-level entities, defined once and reusable across projects and libraries.
> >
> > > [card] Default `user` role on creation
> > >
> > > New projects spawn with a default `user` role so a fresh project is reachable on day one without extra wiring.
> >
> > > [card] Sharing from Solutions
> > >
> > > The Solutions page gains a **Share** modal. Pick a user or end-user group, assign a role, and the user can launch the solution at runtime.
> >
> > > [card] End-user groups in FlowX
> > >
> > > Groups previously managed in Keycloak now live in FlowX. Recommended pattern: an "All End Users" group per single-role solution; one group per role for multi-role solutions.
> >
> > > [card] Process swimlane roles
> > >
> > > BPMN swimlanes assign view, execute, and self-assign permissions per role.
> >
> > > [card] Designer-user bypass
> > >
> > > Designer users can run any project they have designer access to without holding a runtime role; they auto-receive view, execute, and self-assign on every swimlane.
> >
> > > [card] Active Policy gate
> > >
> > > The Share modal lists only roles defined in the build set as **Active Policy** for the project. Roles defined in a non-active build do not appear until promoted.
>
> > [tab] Architecture
> >
> > The 5.8.0 release introduces a clear split between authentication and runtime authorization:
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Authentication, sessions, MFA | Keycloak | Unchanged |
> > | External IDP federation | Keycloak | Configured per organization |
> > | User attributes (business filters) | Keycloak | Source of truth for token claims |
> > | Runtime roles | FlowX (custom CAS) | Defined per project version, evaluated at runtime |
> > | End-user groups | FlowX (custom CAS) | Replaces Keycloak group management |
> > | Project-scoped sharing | FlowX (custom CAS) | Solutions → Share modal |
> > | Design-time permissions | FlowX SpiceDB | Designer UI access; unchanged from prior releases |
> >
> > A `designer-user` Keycloak attribute is auto-managed on each user (`true` for designer users, `false` for end-users), with a mapper on the `flowx-platform-authenticate` client so the engine can check it cheaply on the access token.
>
> > [tab] Migration
> >
> > > [!WARNING]
> > >
> > > **Sharing settings do not export between environments or workspaces.** Configure sharing per environment as a deliberate step when promoting a project to a higher environment.
> >
> > Sharing data does not travel with the project export, so promoting a build from one environment to another (for example, dev to staging) requires a sharing pass in the target environment. Treat it as an explicit step in your deployment checklist.
> >
> > Existing FlowX organizations migrate as follows:
> >
> > * Roles previously assigned directly to users continue to work for backward compatibility while you rebuild assignments under the project-scoped model.
> > * End-user groups configured in Keycloak are migrated into FlowX and become the authoritative source going forward.
> > * Existing UI Flows receive the project-level **User** role automatically as their default allowed role on upgrade. See the [UI Flow permissions](#ui-flow-permissions) section for next steps.
>
> All Deployments

### **UI Flow permissions**

> [card] UI Flow permissions
>
> > [tab] Overview
> >
> > **Before 5.8.0:** every UI Flow was reachable by anyone with runtime access. **Now:** each UI Flow carries its own allow-list and components inside it can be hidden or disabled per role.
> >
> > Each UI Flow now carries a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API. Inside a UI Flow session, individual components can be hidden or disabled by permission-based rules evaluated at runtime against the user's permission set.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> > >
> > > See UI Flows → UI Flow permissions.
>
> > [tab] Key Features
> >
> > > [card] Permissions page
> > >
> > > A new **Settings → Permissions** page in the UI Flow editor lets you assign one or more runtime roles to each UI Flow.
> >
> > > [card] Default role on creation
> > >
> > > New UI Flows receive the project-level **User** role by default so they are reachable on day one; tighten the list before deploying.
> >
> > > [card] Per-component hide/disable
> > >
> > > Components can be hidden or made readonly based on the user's runtime permissions, using the same hide/disable rule machinery as JavaScript expressions.
> >
> > > [card] Permission toast
> > >
> > > Users without the required role see a permission toast in the Designer-hosted runtime preview; the deployed app returns 403 from the start endpoint.
> >
> > > [card] Input-parameter validation
> > >
> > > Input parameters are validated against the UI Flow's input schema before the session is created.
> >
> > > [card] Travels with import/export
> > >
> > > Allowed roles are saved on the UI Flow resource and travel with project export/import.
>
> > [tab] Migration
> >
> > UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.
>
> All Deployments

### **Custom Components in Processes**

> [card] Custom Components in Processes
>
> > [tab] Overview
> >
> > **Before 5.8.0:** Custom Components only ran in UI Flows. **Now:** drag one onto a Process User Task and the React SDK applies the input/output mappings at runtime.
> >
> > Bundled Custom Components, previously only usable in UI Flows, now render in **Process User Tasks**. Each Custom Component carries its own **data model** with explicit input and output slices, and you map process data into and out of the component at each use site. Renderer support ships in the React SDK.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components#using-custom-components-in-process-user-tasks)
> > >
> > > See Custom Components → Using Custom Components in Process User Tasks.
>
> > [tab] Key Features
> >
> > > [card] Process User Task host
> > >
> > > Drag a Custom Component onto a Process User Task layout the same way you do in UI Flows.
> >
> > > [card] Custom Component data model
> > >
> > > Each Custom Component declares its own data model. The Designer keeps input and output slices isolated so the component contract is clear at every use site.
> >
> > > [card] INPUT mappings
> > >
> > > Map process data attributes onto the Custom Component's input slice at runtime, so the component receives only the data it declared.
> >
> > > [card] OUTPUT mappings
> > >
> > > When the component triggers an action, the React SDK applies the configured OUTPUT mappings before piping `saveData` back to process variables.
> >
> > > [card] Test with sample inputs
> > >
> > > The Custom Component editor lets you fill input params with sample data for in-Designer preview, mirroring the UI Flow test flow.
> >
> > > [card] Import and export
> > >
> > > Custom Components export and import alongside the data model and mappings so a component travels intact between projects.
>
> > [tab] Limitations
> >
> > Phase 1 limitations from 5.7.0 still apply: React SDK only (no Angular renderer), pre-defined dependency set (React, Emotion, Lodash, Axios, date-fns), browser-side bundling, and client-side rendering only. See the [Custom Components limitations](/5.9/docs/building-blocks/reusable-resources/custom-components#limitations-phase-1) section.
>
> All Deployments

### **New UI components**

> [card] New UI components
>
> Four new theme components ship with renderer parity across React, Angular, and Android SDKs.
>
> > [card] [Tooltip](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Contextual hint anchored to any UI element. Configurable text (static, local variable, or computed expression), position handling, and an optional icon.
>
> > [card] [Markdown](/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown)
> >
> > Render Markdown content from a static string or computed expression, with localization formatting for numbers, dates, and currency. Six heading levels and link styling are theme-driven.
>
> > [card] [Progress Bar](/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar)
> >
> > Visual progress indicator. Set a value between `0` and `1` from a static value, local variable, or computed expression.
>
> > [card] [Separator](/5.9/docs/building-blocks/ui-designer/ui-component-types/separator)
> >
> > Visual divider with theme-driven color. Adjustable height for layout spacing.
>
> All four are exposed in the **Theme Admin** sidebar so theme overrides cascade through templates.
>
> All Deployments

### **Angular bulk file upload**

> [card] Angular bulk file upload
>
> > [tab] Overview
> >
> > The **Multiple File Upload** component (`BULK_FILE_UPLOAD`), previously available only in the React SDK, now ships in the Angular SDK with the same drag-and-drop area and theming. Existing UI Flows that use the component render across React and Angular containers without configuration changes.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> > >
> > > See the Multiple File Upload component reference.
>
> > [tab] Key Features
> >
> > > [card] Renderer parity
> > >
> > > Same component, same configuration, same theming across React and Angular containers.
> >
> > > [card] Drag-and-drop area
> > >
> > > Drop zone with click-to-browse fallback in both renderers.
> >
> > > [card] Theme-driven
> > >
> > > The component picks up theme overrides for typography, colors, and spacing the same way as built-in components.
> >
> > > [card] No flow changes needed
> > >
> > > UI Flows authored before 5.8.0 render in the Angular SDK without edits.
>
> All Deployments

### **UI Flow multi-file upload backend**

> [card] UI Flow multi-file upload backend
>
> > [tab] Overview
> >
> > Multi-file uploads from UI Flows now use a dedicated bulk endpoint and a single completion event in place of the per-file pattern. The upload action accepts a list of temp-file IDs in one request and the SDK receives a single SSE frame when the batch is persisted.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload#ui-flow-upload-flow)
> > >
> > > See Multiple file upload → UI Flow upload flow.
>
> > [tab] Key Features
> >
> > > [card] Single bulk endpoint
> > >
> > > `POST /ui-flow/{uiFlowSessionId}/upload-multiple` accepts a list of temp-file IDs and returns a server-generated `uploadBatchId`.
> >
> > > [card] Single completion event
> > >
> > > One SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) delivers per-file results once the batch is persisted.
> >
> > > [card] New Kafka topic
> > >
> > > `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` carries the bulk command from process-engine to document-plugin.
> >
> > > [card] Session variable mapping
> > >
> > > Per-file results are stored as a list under the upload action's `responseKey` in the UI Flow session.
>
> All Deployments

### **Webhook provider adapters**

> [card] Webhook provider adapters
>
> > [tab] Overview
> >
> > Inbound webhook registrations now select a **provider**: `GENERIC` or `SLACK`. The Slack adapter performs HMAC-SHA256 signature validation against the Slack signing secret on every request, including the `X-Slack-Request-Timestamp` skew check (5 minutes). Provider-segmented URLs (`/webhooks/incoming/slack/...`) keep generic and provider-specific registrations isolated. Future providers plug in behind the same `InboundProviderAdapter` interface without changing the URL contract.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#provider-adapters)
> > >
> > > See Incoming webhooks → Provider adapters.
>
> > [tab] Key Features
> >
> > > [card] Slack signature validation
> > >
> > > HMAC-SHA256 on `X-Slack-Signature`, with timestamp skew enforced
> >
> > > [card] Slack URL-verification handshake
> > >
> > > The gateway answers Slack's `url_verification` challenge automatically
> >
> > > [card] Provider-segmented URLs
> > >
> > > `/webhooks/incoming/{provider}/...` keeps providers isolated; mismatch returns 400
> >
> > > [card] Independent secret rotation
> > >
> > > Rotate the provider signing secret without touching the FlowX API key
> >
> > > [card] Settings tab
> > >
> > > Provider + signing secret moved to a dedicated Settings tab on the webhook system
> >
> > > [card] Pluggable
> > >
> > > New providers add an adapter and an enum value; no URL or registration schema changes
>
> All Deployments

### **Richer SQL autocomplete**

> [card] Richer SQL autocomplete
>
> > [tab] Overview
> >
> > The Monaco editor on the Oracle Database data source now ships with a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `:paramName` interpolations resolved from the parameters panel.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database#sql-editor)
> > >
> > > See the Oracle Database SQL editor documentation.
>
> > [tab] Key Features
> >
> > > [card] Keywords and operators
> > >
> > > Full SQL language definition powers keyword highlighting and completion.
> >
> > > [card] Schema-aware suggestions
> > >
> > > Tables and columns parsed from the saved schema context appear in completion lists.
> >
> > > [card] Parameter interpolation
> > >
> > > `:paramName` placeholders resolve against the parameters panel for inline preview.
> >
> > > [card] Editor consistency
> > >
> > > Matches the editor experience used by other code surfaces in the Designer.
>
> All Deployments

### **Data source UX redesign**

> [card] Data source UX redesign
>
> > [tab] Overview
> >
> > The Data Sources resource page is rebuilt around a tile-based creation flow and a unified details view. Each data source type has its own icon and a dedicated tile in the **New Data Source** modal, with a search box that filters tiles as you type. The list view shows the type next to each entry and adds a type filter so you can scope the list by connector. Settings panels for every data source type are normalized to the same card-based layout.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer reference for data source configuration.
>
> > [tab] Key Features
> >
> > > [card] Tile-based creation modal
> > >
> > > The **New Data Source** modal lists every connector type as a searchable tile, replacing the previous type dropdown.
> >
> > > [card] Type icons in the list
> > >
> > > Each entry in the data sources list shows the connector's icon and type, so a long list is easier to scan.
> >
> > > [card] Filter by type
> > >
> > > Filter the list to a specific connector type (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.) without scrolling.
> >
> > > [card] Unified settings layout
> > >
> > > Every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
> >
> > > [card] Save with incomplete config
> > >
> > > Create and save a data source even when some fields (credentials, endpoints) are not yet available. You can reference the data source in workflows and processes immediately and finish the configuration later — the data source will only operate at runtime once required fields are filled in.
>
> All Deployments

### **PII Guard**

> [card] Personal Information Guard
>
> > [tab] Overview
> >
> > **Before 5.8.0:** data-sensitive customers couldn't enable AI workflow nodes at all. **Now:** every AI node carries a per-node guardrail with sensitivity presets, scan directions, and a fail-closed contract.
> >
> > AI workflow nodes gain a per-node guardrail that detects and replaces personal information before it reaches the LLM and, optionally, scans LLM output before it flows downstream. The guard runs against the new **Data Privacy** service, configured per node with sensitivity presets, scan directions, and an entity catalog organized into Universal, Regional EN, and Regional RO scopes. Iteration 1 covers Custom Agent, Intent Classification, Extract Data from File, and all AI Text, Document, Image, and Data Operations, including Document Generation.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See Personal Information Guard.
>
> > [tab] Key Features
> >
> > > [card] Per-node toggle
> > >
> > > Enable on any AI node. Choose a sensitivity preset (Strict / Balanced / Relaxed) or set a custom threshold.
> >
> > > [card] Input and output scans
> > >
> > > Redacts inputs and `systemPrompt` before the LLM call; optionally scans LLM output before it leaves the node.
> >
> > > [card] File redaction
> > >
> > > Document and image nodes get a redacted source artifact uploaded back to the same storage; the file binding is swapped automatically.
> >
> > > [card] Entity catalog
> > >
> > > 24 entity types (email, phone, IBAN, etc.) grouped under Universal, Regional EN, and Regional RO. Modal supports search and section-level Select All.
> >
> > > [card] System-prompt appender
> > >
> > > Custom Agent nodes get a non-editable system-prompt segment teaching the LLM how to handle `<PII type=.../>` placeholders.
> >
> > > [card] Fail-closed
> > >
> > > Any error from the Data Privacy service stops node execution and surfaces on the run log; no partially-redacted prompts reach the LLM.
> >
> > > [card] Run-log visibility
> > >
> > > Each scan reports status, per-entity detection counts, and (for file scans) original and redacted storage paths.
> >
> > > [card] New Data Privacy service
> > >
> > > Backed by Presidio. Configured via `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` on integration-designer.
>
> All Deployments

### **Knowledge Base enhancements**

> [card] Knowledge Base
>
> > [tab] Overview
> >
> > Knowledge Bases gain richer metadata and a more resilient indexing path. Stores and chunks expose system metadata fields you can filter on in the Test KB modal and the Custom Agent node, the indexer and embedder communicate over Kafka instead of synchronous calls, and the Update Knowledge Base node can ingest files by path from inside a workflow.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See Knowledge Base → Overview.
>
> > [tab] Key Features
> >
> > > [card] System metadata on stores
> > >
> > > Filter entries by `Source` (Manual or Workflow), `Uploaded`, `Doc name`, `Doc type`, `Doc pages`, and `Store origin`
> >
> > > [card] System metadata on chunks
> > >
> > > Filter chunks by `Chunk counter`, `Chunk type`, `Chunk section`, `Chunk page start`, and `Chunk entry`
> >
> > > [card] Kafka between indexer and embedder
> > >
> > > Replaces the previous synchronous gRPC path; per-chunk embedding requests flow through `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1`
> >
> > > [card] Delete chunks from Qdrant
> > >
> > > Indexer forwards a delete job to the embedder, which removes matching points from Qdrant when an entry is deleted
> >
> > > [card] File path mode in Update KB node
> > >
> > > The Update Knowledge Base node accepts `contentType: FILE_PATH` so workflows can ingest content uploaded earlier in the run
> >
> > > [card] Doc pages in agent stream
> > >
> > > Custom Agent streaming responses include `doc_pages` and chunk metadata (counter, type, section, page start) for richer trace and debug
>
> All Deployments

### **Web Crawler multi-URL filters**

> [card] Web Crawler multi-URL filters
>
> > [tab] Overview
> >
> > The Web Crawler node now accepts up to 20 URL filter patterns per crawler configuration. Open the **URL Filters** modal on the Web Crawler node, add one row per pattern, and the crawler restricts its breadth-first traversal to URLs that match any of the configured filters.
> >
> > > [card] [Documentation](/5.9/setup-guides/web-crawler-setup)
> > >
> > > See the Web Crawler setup guide.
>
> > [tab] Key Features
> >
> > > [card] Up to 20 patterns per crawler
> > >
> > > Add one row per pattern in the URL Filters modal; deep crawls match any pattern.
> >
> > > [card] Replaces single-string filter
> > >
> > > The previous single-string filter is superseded by the new multi-pattern array. Existing crawlers are migrated automatically.
> >
> > > [card] Breadth-first scoping
> > >
> > > Filters apply to the crawler's breadth-first traversal so deep crawls stay within the intended scope.
> >
> > > [card] Per-pattern tuning
> > >
> > > Combine narrow and broad patterns in one configuration to handle multi-section sites without spawning multiple crawlers.
>
> All Deployments

### **AI Developer generates Custom Components**

> [card] AI Developer generates Custom Components
>
> > [tab] Overview
> >
> > **Before 5.8.0:** the AI Developer wrote business rules and JS expressions. **Now:** it ships entire React Custom Components — JSX, CSS, `package.json`, and sample input data — in one prompt.
> >
> > The AI Developer pre-built agent gains a **Generate Custom Component** action and an **Edit Custom Component** action. From the Designer's AI command center, describe the component you want, and the agent returns a complete React bundle (JSX, CSS, `package.json`, and sample input data) that you can preview, accept, or iterate on. The same conversation can edit existing components.
> >
> > > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> > >
> > > See AI Developer → Pre-built agents.
>
> > [tab] Key Features
> >
> > > [card] Generate from natural language
> > >
> > > Describe a component in plain language; receive JSX, CSS, `package.json`, and sample input data in one response.
> >
> > > [card] Sample input field
> > >
> > > A dedicated input field lets you provide preview data so the generated component renders meaningfully on first run.
> >
> > > [card] Edit existing components
> > >
> > > Iterate on a generated or hand-authored component through the same conversation. The agent keeps the component context.
> >
> > > [card] Inline preview
> > >
> > > The Designer's Preview area renders the generated bundle next to the conversation so you can validate before saving.
> >
> > > [card] Dependency summary
> > >
> > > A new dependency summary panel surfaces the npm packages the agent included in `package.json`.
> >
> > > [card] Keep / Discard
> > >
> > > Accept the generated bundle into the workspace or discard it without leaving the conversation.
>
> > [tab] Limitations
> >
> > The first iteration generates the component code, styles, and input parameters. Wiring component actions to host-side handlers (Process or UI Flow actions) is not yet inferred — connect actions manually after accepting the generated bundle.
>
> All Deployments

### **iframe logout postMessage contract**

> [card] iframe logout postMessage
>
> The runtime SaaS app now notifies an iframe parent when a user logs out. When the parent passes a `parentOrigin` query parameter on the `/{orgCode}/logout` URL, the runtime posts `{ type: 'logout-success' }` to `window.parent` immediately before the sign-out redirect. Host applications that embed the FlowX runtime in an iframe can listen for this message and react (clear local state, navigate, surface a UI cue) without polling the iframe URL.
>
> All Deployments

### **Context menu adds UI components in Processes**

> [card] Right-click Add UI component in Processes and Reusable UI Templates
>
> The right-click contextual menu for adding a UI component, previously available only in UI Flows, now works in **Process User Tasks** and **Reusable UI Templates** as well. Right-click a node in the components hierarchy panel to insert any allowed child component without dragging from the palette. Copy and paste styles are also exposed from the same menu.
>
> All Deployments

### **Pointer cursor on actionable elements**

> [card] Pointer cursor on actionable elements
>
> Web renderers now switch the cursor to a pointer when hovering over any UI component bound to an action, matching standard web affordances. No configuration change is required — the new behavior applies automatically to elements that already declare an action role.
>
> All Deployments

### **"Process Data" → "Local Variables" rename**

> [card] Process Data renamed to Local Variables
>
> In the UI Designer, the **Process Data** label is now displayed as **Local Variables** when you are editing a UI Flow or a Reusable UI Template. Process editing is unchanged and continues to use **Process Data**. The data source key and binding behavior are identical; only the user-visible label changed, so existing flows continue to work without any update.
>
> All Deployments

### **License billing guards**

> [card] License billing guards
>
> The license service no longer creates billing plans for periods past an organization's subscription end date. This prevents stale plan rows from accumulating after a subscription expires and aligns the on-prem billing trail with the SaaS-side license lifecycle.
>
> Self-Hosted

### **Speech-to-text and Web Crawler in AI consumption**

> [card] Speech-to-text and Web Crawler in AI consumption
>
> AI consumption tracking now includes Speech-to-text and Web Crawler workflow nodes alongside the existing AI Text, Document, Image, and Data Operations. Organizations on AI consumption-based plans see usage and billing reflected for these nodes from 5.8.0 onward.
>
> All Deployments

***

## Shipped by

This release is the work of the FlowX engineering team — backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.8.0](./deployment-guidelines-v5.8).


# Deployment guidelines v5.9.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9

Component versions, environment variables, and configuration changes for FlowX.AI 5.9.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

> [!NOTE]
>
> **Upgrading from 5.1.x LTS?** This page describes the steady-state 5.9.0 deployment. For the architecture delta, deprecation list, and upgrade steps, see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Deployment packaging.** 5.9.x is the last LTS release distributed as a multi-chart deployment, where each FlowX service is installed from its own Helm chart.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

The following tables list component versions per FlowX.AI release. Verify your installed versions against the 5.9.0 column in **FlowX.AI Designer → Platform Status**.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **process-engine** | 10.135.0 | 10.106.0 | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 |
| **admin** | 10.116.0 | 10.93.0 | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 |
| **designer** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 |
| **cms-core** | 10.86.0 | 10.67.0 | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 |
| **scheduler-core** | 10.70.0 | 10.53.0 | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 |
| **events-gateway** | 10.72.0 | 10.55.0 | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 |
| **notification-plugin** | 10.83.0 | 10.64.0 | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 |
| **document-plugin** | 10.94.0 | 10.75.0 | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 |
| **task-management-plugin** | 10.84.0 | 10.66.0 | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |
| **data-search** | 10.69.0 | 10.52.0 | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 |
| **audit-core** | 10.79.0 | 10.63.0 | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 |
| **advancing-controller** | 10.73.0 | 10.55.0 | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 |
| **integration-designer** | 10.162.0 | 10.128.0 | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 |
| **application-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **runtime-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **data-sync** | 10.81.0 | 10.58.0 | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 |
| **authorization-system** | 10.96.1 | 10.77.0 | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 |
| **nosql-db-runner** | 10.75.0 | 10.56.0 | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 |
| **email-gateway** | 10.74.0 | 10.56.0 | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 |
| **organization-manager** | 10.71.0 | 10.53.0 | 10.44.0 | 10.26.1 | 10.19.2 | - |
| **webhook-gateway** | 10.44.0 | 10.25.0 | 10.15.0 | 10.1.1 | - | - |
| **file-gateway** | 10.8.0 | - | - | - | - | - |
| **license** | 10.63.0 | 10.46.0 | 10.36.0 | - | - | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB**
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-native-sdk** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-theme** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-ui-toolkit** | 10.230.2 | - | - | - | - | - |
| **@flowx/core-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/core-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **react-saas** | 10.230.2 | - | - | - | - | - |
| **iOS renderer** | 10.4.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |
| **Android renderer** | 10.5.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |

The **react-saas** container app tracks the designer version.

### Plugins

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-knowledgebase-rag** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-embedder** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **doc-parser** | 10.9.0 | 10.7.0 | 10.6.2 | 10.5.1 | - | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-agent-builder** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **data-privacy** | 10.1.0 | 10.1.0 | 10.0.8 | - | - | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **evals-judge** | 10.1.1 | - | - | - | - | - |
| **speech-to-text** | 10.3.4 | 10.3.3 | 10.3.3 | - | - | - |
| **web-crawler** | 10.3.5 | 10.3.5 | 10.3.2 | - | - | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-gateway** | 10.7.0 | - | - | - | - | - |
| **ai-platform-ai-analyst** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-assistant** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **ai-platform-ai-designer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-developer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **di-platform** | 10.3.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **flowx-docs** | 5.9.0 | - | - | - | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - | - | - |
| **ai-observatory** | 10.3.2 | - | - | - | - | - |

***

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

***

## Kafka topics

### Document-plugin archive and extract listeners

5.9.0 exposes four Kafka topics for the document-plugin **archive** and **extract** operations. Both follow the encrypt/decrypt trigger and reply pattern: document-plugin consumes the `trigger.*.file` topic and process-engine consumes the matching `engine.receive.*.file.results` reply.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.archive.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.extract.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` | document-plugin | process-engine |

The four topic names are exposed as env vars on the document-plugin side (`KAFKA_TOPIC_FILE_ARCHIVE_IN`, `KAFKA_TOPIC_FILE_ARCHIVE_OUT`, `KAFKA_TOPIC_FILE_EXTRACT_IN`, `KAFKA_TOPIC_FILE_EXTRACT_OUT`). See [Documents plugin setup → File archive / File extract](/5.9/setup-guides/documents-plugin-setup#file-archive). Two new thread-pool entries are added: `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN` and `..._FILEEXTRACTIN`, both defaulting to `5`.

### Document-plugin encrypt and decrypt listeners

The **encrypt** and **decrypt** operations follow the same trigger-and-reply pattern: process-engine produces the `trigger.*.file` topic and document-plugin replies on the matching `engine.receive.*.file.results` topic.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | document-plugin | process-engine |

The topic names are exposed as env vars on the document-plugin side: `KAFKA_TOPIC_FILE_ENCRYPT_IN`, `KAFKA_TOPIC_FILE_ENCRYPT_OUT`, `KAFKA_TOPIC_FILE_DECRYPT_IN`, `KAFKA_TOPIC_FILE_DECRYPT_OUT`.

### Document-plugin session-upload listeners

Multi-file upload for UI flows routes uploaded files to the document-plugin for persistence. process-engine produces the trigger topic and document-plugin consumes it — `session` for a single upload session and `session.bulk` for batched multi-file uploads.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | process-engine | document-plugin |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | document-plugin |

The topic names are exposed on process-engine as `KAFKA_TOPIC_SESSION_UPLOAD_OUT` and `KAFKA_TOPIC_SESSION_UPLOAD_BULK_OUT`, and on document-plugin as `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN` and `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN`.

### AI Platform job topics

`integration-designer` dispatches asynchronous jobs to the standalone AI services over Kafka, using a request/response pair per service. Provision these topics when you deploy the corresponding AI service (see [AI components](#ai-components) above).

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.ai-platform.doc-parser.job.request.v1` | integration-designer | doc-parser |
| `ai.flowx.ai-platform.doc-parser.job.response.v1` | doc-parser | integration-designer |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | integration-designer | evals-judge |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | evals-judge | integration-designer |
| `ai.flowx.ai-platform.speech-to-text.job.request.v1` | integration-designer | speech-to-text |
| `ai.flowx.ai-platform.speech-to-text.job.response.v1` | speech-to-text | integration-designer |

On `integration-designer` the topic names are set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_REQUEST_OUT` and `..._RESPONSE_IN` (for example `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`). Each service also has a dead-letter topic — `ai.flowx.ai-platform.<service>.job.dlq.v1`, set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_DLQ_IN` — that integration-designer consumes for failed jobs.

### UI Flow runtime triggers

process-engine consumes two trigger topics that back the UI Flow runtime cache and expiration features. `update` invalidates a cached UI Flow when its definition changes; `expire` removes expired UI Flow runtime data.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer | process-engine |
| `ai.flowx.core.trigger.expire.ui-flow.v1` | scheduler-core | process-engine |

On process-engine these are set via `KAFKA_TOPIC_UIFLOW_UPDATE_IN` and `KAFKA_TOPIC_UIFLOW_EXPIRE_IN`; the producers expose `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`. The expire trigger uses the platform scheduler: when a UI Flow session is created, process-engine registers a delayed message with scheduler-core, which publishes it back to this topic at the expiry time. It is consumed by a dedicated consumer group (`KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE`, default `ui-flow-expire`).

### File and webhook process triggers

Two trigger topics let the file-gateway and webhook-gateway start or resume processes in process-engine. The **start-for-event** topic starts a process when a watched file arrives (file-gateway) or an incoming webhook fires (webhook-gateway); the **message event** topic resumes a running process that is waiting on an intermediate message catch event.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | file-gateway, webhook-gateway | process-engine |
| `ai.flowx.core.message.event.process.v1` | webhook-gateway | process-engine |

On the producers, the start-for-event topic is set via `KAFKA_TOPIC_TRIGGER_STARTFOREVENT_PROCESS_OUT` (file-gateway) and `KAFKA_TOPIC_PROCESS_START_OUT` (webhook-gateway); process-engine consumes it via `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`. The message event topic uses `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` on both webhook-gateway and process-engine. Like every service, file-gateway and webhook-gateway also publish to the shared audit topic `ai.flowx.core.trigger.save.audit.v1` via `KAFKA_TOPIC_AUDIT_OUT` (consumed by audit-core).

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Data-sync: Keycloak admin credentials

The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak on first run, using the Keycloak admin API. Configure the following on the data-sync job:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak` (the only supported provider). | `keycloak` | data-sync |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` | data-sync |
| `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` | data-sync |
| `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` | data-sync |
| `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Typically `admin-cli` for standard Keycloak deployments. Must be set explicitly. There is no default. | `-` | data-sync |

For full data-sync configuration, see [Data-sync job setup](/5.9/setup-guides/data-sync#openid-provider-configuration).

### Anonymous service account: shared client secret

5.9.x introduces a single shared service-account client, `flowx-anonymous-sa`, used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows. One client secret is reused across all consumers — it must be provided in two places.

**On `authorization-system`** — passed to Liquibase so the client is provisioned with the correct secret when FlowX manages Keycloak:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXANONYMOUSSA` | Client secret used by Liquibase to create the `flowx-anonymous-sa` client in the service-accounts realm at first boot. Required when `SECURITY_KEYCLOAKADMINENABLED=true`. | `-` | `authorization-system` |

**On every consuming service** — the Spring Security OAuth2 client registration for the `anonymousidentity` alias resolves the same secret at runtime:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Client secret for the `anonymousidentity` registration. **Must be the same value across every service** — it is a single shared service account. | `-` | `admin`, `application-manager`, `authorization-system`, `document-plugin`, `email-gateway`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `mock-server`, `nosql-db-runner`, `organization-manager`, `process-engine`, `scheduler-core`, `task-management-plugin`, `webhook-gateway` |

> [!WARNING]
>
> This is a secret. Store it in your secrets management solution (e.g., Kubernetes Secret, Vault) and reference it from there. Never commit it to version control.

For the Keycloak-side context (`flowx-anonymous-sa` client, `SA_FLOWX_ANONYMOUS` realm role, manual-configuration recipe for deployments without Keycloak admin access), see [Manual Keycloak configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).

### Knowledgebase-rag: Qdrant search tuning

Two env vars control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Defaults are tunable per environment.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. | `100` | knowledgebase-rag |
| `QDRANT_FUSION_LIMIT` | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker input. | `80` | knowledgebase-rag |

Raise both when recall is insufficient on very large or long-tailed Knowledge Bases. Lower them when Qdrant pods report memory pressure or filter-heavy queries time out.

### CORS handling: `APPLICATION_CORS_ALLOWORIGIN`

CORS is enforced at the application layer. Each backend service exposed via admin or public URLs reads its allowed-origin list from a single environment variable. Allowed methods, allowed headers, exposed headers, and credential handling are baked into each service's `application.yaml` with safe defaults. The 5.9.x default allow-headers set is `Accept, Content-Type, Authorization, Fx-Workspace-Id, Fx-Client-Host, Referer, User-Agent, Flowx-Platform, X-Fx-Anonymous-Session-Id, Fx-BuildId, Fx-AppId`, and `X-Fx-Anonymous-Session-Id` is exposed to the browser for anonymous runtime sessions. Only `APPLICATION_CORS_ALLOWORIGIN` is deployment-specific.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains (`https://*.yourcompany.com`). Must include every Designer, runtime renderer, and integration domain that calls FlowX APIs. | `-` | `admin`, `ai-gateway`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway` |
| `APPLICATION_CORS_EXPOSEDHEADERS` | Response headers exposed to browser JavaScript. The default carries the anonymous-session header; override only if you need to expose additional custom headers. | `X-Fx-Anonymous-Session-Id` | all services (shared security library) |

For migration guidance and the full list of removed NGINX CORS annotations, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

### Process-engine and integration-designer: native script engine

The default script engine for JavaScript and Python execution is a **native subprocess pool**. Scripts run in isolated Node.js and Python worker processes.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider | `native` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size | `16` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary | `/usr/bin/node` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS script execution timeout (ms) | `5000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a JS worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max JS input payload size (bytes) | `1048576` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size | `8` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary | `/usr/bin/python3` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python script execution timeout (ms) | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a Python worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max Python input payload size (bytes) | `1048576` | process-engine, integration-designer |

To use GraalVM instead of the native engine, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services.


# FlowX.AI 5.9.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026

First LTS in the 5.9.x family. Brings conversational AI, UI Flows and Custom Components, AI Platform, runtime authorization, new React Native and iOS UI Flow SDKs, and a wide set of integration and process-ops improvements.

[FlowX.AI 5.9.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-5.9.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted deployments
> * All Deployments Features available in both self-hosted and SaaS

### What 5.9.0 includes

* **Closes the runtime authorization rewrite**. Per-environment sharing, project-version-scoped roles, data-sync Keycloak provisioning.
* **Brings the full set of changes accumulated since the 5.1.x LTS line**. Conversational AI, UI Flows, Custom Components, AI Platform, runtime authorization.
* **Ships a new React Native SDK** and rounds out iOS UI Flow support.

> [!NOTE]
>
> **5.9.0 is the first LTS in the 5.9.x family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Self-hosted customers upgrading from 5.1.x LTS go directly to 5.9.0. See the [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview) guide for the consolidated upgrade path.

***

**What's in this LTS release?**

> [tab] Runtime authorization and sharing
>
> 🔐 [**Runtime authorization completion**](#runtime-authorization-completion) - Per-environment sharing checklist, project-level end-user roles, data-sync provisioning of Keycloak groups and roles.\
> 🌐 [**Anonymous runtime access**](#anonymous-runtime-access) - Built-in Anonymous role + Share modal "Everyone with the link" for unauthenticated end users; session-bound, SDK auth-skip mode.\
> 🛡️ [**Runtime authorization overhaul**](#runtime-authorization-overhaul) - Project-version-scoped roles, end-user groups moved from Keycloak into FlowX, Solutions → Share modal flow, Active Policy gate, designer-user bypass.\
> 🔒 [**UI Flow permissions**](#ui-flow-permissions) - Per-UI-Flow role allow-list with runtime 403 enforcement; assignments travel with import/export.\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.\
> 🎯 [**Active policy: group overrides**](#active-policy-group-overrides) - Override a project's active build per runtime group; legacy role overrides are excluded from runtime resolution and only kept for deletion.\
> 🧩 [**Roles carried across project-version merges**](#roles-carried-across-project-version-merges) - Application-version roles cloned onto the merged version automatically, no manual re-binding after merge.\
> 🏷️ [**Operations-editor role**](#operations-editor-role) - **Workspace operations editor** role and `wks_process_instance_variables_edit` permission for ops teams.\
> 🗂️ [**Cross-workspace projects**](#cross-workspace-projects) - Import the same project into multiple workspaces in the same environment.\
> 🔁 [**Cross-LTS import/export**](#cross-lts-import/export) - Move project versions and builds between the 5.1.x and 5.9.x LTS lines, in both directions.\
> 🚪 [**Log-in page redesign**](#log-in-page-redesign) - IdP provider button replaces the fallback link; refreshed labels across the log-in flow.

> [tab] Conversational AI
>
> 💬 [**Chat component**](#chat-component) - Standalone chat tab; Inline / Floating / FullScreen modes; iOS and Android support; Chat History; Suggested Prompts; Markdown.\
> 🌀 [**Conversational Workflows**](#conversational-workflows) - Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node.\
> 🎙️ [**Voice input + Speech-to-Text**](#voice-input-+-speech-to-text) - Audio recording in chat; Speech-to-Text node for transcription.\
> 🧠 [**Memory capabilities**](#memory-capabilities) - Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full; Use conversation memory toggle on the AI / Custom Agent node.\
> 🧭 [**Intent Classification node**](#intent-classification-node) - LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.\
> 💭 [**Chat-based UI Flows**](#chat-based-ui-flows) - Flow-Based vs Chat-Based experience type set at the UI Flow level.\
> ⚡ [**AI Triggers**](#ai-triggers) - Named parameterized message templates to launch conversational workflows with context.\
> 🏷️ [**Chat title generation and conversation search**](#chat-title-generation-and-conversation-search) - Auto-generated session titles + cross-conversation search on the chat history.\
> 🛑 [**Stop agent response**](#stop-agent-response) - Stop button while streaming; cancels the underlying workflow.

> [tab] AI Agents and Knowledge
>
> 📊 [**Evaluations (Evals)**](#evaluations) - LLM-as-judge, RAG-quality, and code evaluators score AI node outputs; datasets, experiments, per-org judge model via new `EVAL` capability.\
> 🤖 [**Custom Agent nodes**](#custom-agent-nodes) - AI agents that use MCP tools to act autonomously in workflows.\
> 🔎 [**Web Search tool for Custom Agents**](#web-search-tool-for-custom-agents) - Built-in web search so Custom Agents can look up up-to-date public-web information during a run.\
> 🔌 [**MCP integration**](#mcp-integration) - MCP servers as data sources; tools in Custom Agent nodes; OAuth 2.0, BEARER, BASIC auth.\
> 📖 [**Knowledge Bases**](#knowledge-bases) - PDF upload, workflow ingestion, semantic search, Custom Agent integration; Stores rename + typed filter builder; system metadata; Kafka indexer/embedder.\
> 🧰 [**AI Providers self-service**](#ai-providers-self-service) - Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability.\
> 🛡️ [**PII Guard: per-entity detections on documents and images**](#pii-guard-per-entity-detections-on-documents-and-images) - Document and image scans return the same per-entity detection list as text scans, with bounding regions.\
> 📝 [**Operational prompt split**](#operational-prompt-split) - System prompt split into operational guardrails and user-instruction layers, versioned independently.\
> 📄 [**Extract Data from File**](#extract-data-from-file) - LLM / OCR / Text Parsing strategies; image input; signature detection.\
> 🌐 [**Web Page Extractor / Web Crawler**](#web-page-extractor-/-web-crawler) - Static or dynamic URLs, link-following depth, PDF extraction, URL filtering, file downloads, multi-URL filters.\
> 📚 [**Manage Knowledge Base content from Runtime**](#manage-knowledge-base-content-from-runtime) - End users can add and update KB content at runtime without going back to the Designer.\
> ✨ [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent drafts React Custom Components from a brief.

> [tab] UI Flows and Custom Components
>
> 🪟 [**UI Flows**](#ui-flows) - Reusable multi-platform UI as project resources; Sessions monitoring; Process Renderer; Route Management; Start Parameters; Session Variables; onClick / On Display / On Load events.\
> ⏳ [**UI Flow session expiry**](#ui-flow-session-expiry) - Expire a UI Flow after a duration or on a schedule; expired sessions become read-only.\
> 🖼️ [**Configurable modal component**](#configurable-modal-component) - Title, subtitle, dismiss behavior, alignment and sizing on modals; theme-level shadow and dismiss icon.\
> 💻 [**Custom Components**](#custom-components) - React JSX / CSS in the Designer; Custom Components in Processes with INPUT/OUTPUT mappings.\
> 🎬 [**Event Handlers**](#event-handlers) - Typed Event Handlers section in the UI component config panel; UI events and AI triggers unified under one model.\
> ♿ [**Accessibility (WCAG 2.1 AA)**](#accessibility-wcag-2-1-aa) - Cross-platform accessibility model surfaced in the UI Designer.\
> 🧱 [**New theme components**](#new-theme-components) - Tooltip, Markdown, Progress Bar, Separator across React / Angular / Android.\
> 📤 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Multiple File Upload on process screens and UI Flows; Angular and React SDK support.\
> 🎨 [**Theming and Designer polish**](#theming-and-designer-polish) - Scoped variants and padding for form labels/errors/helpers, mandatory-label style.

> [tab] Integration and Data Platform
>
> 📨 [**Email Trigger**](#email-trigger) - IMAP-triggered processes; attachments to the `document-plugin`; validation rules.\
> 📧 [**Microsoft Outlook data source**](#microsoft-outlook-data-source) - Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes.\
> 🪝 [**Incoming Webhooks**](#incoming-webhooks) - New `webhook-gateway` microservice; trigger processes via HTTP POST; Slack provider adapter.\
> 🗄️ [**Oracle Database integration**](#oracle-database-integration) - Oracle 21c / 23ai data source; schema-aware Monaco editor.\
> 🍃 [**Unmanaged MongoDB data source**](#unmanaged-mongodb-data-source) - Connect to externally managed MongoDB 6.0+ instances.\
> 📁 [**File Storage data source**](#file-storage-data-source) - Move files in and out of external FTP / SFTP / S3 / Azure Blob storage from workflows.\
> 📨 [**Meta webhook provider**](#meta-webhook-provider) - WhatsApp / Messenger / Instagram / Threads webhook support with verify-token handshake and X-Hub-Signature-256 verification.\
> 📂 [**Documents in process instances**](#documents-in-process-instances) - Dedicated Documents section on each process instance.\
> 📤 [**Send Notification action + Email Sender**](#send-notification-action-+-email-sender) - SMTP data source; new action sends or replies email directly without Kafka.\
> 🎛️ [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder replacing manual JSON, with new operators.\
> 🧬 [**Parallel branches in workflows**](#parallel-branches-in-workflows) - Start / End Parallel nodes for concurrent execution.\
> ⚡ [**REST endpoint caching + workflow partitioning**](#rest-endpoint-caching-+-workflow-partitioning) - TTL-based REST GET caching; time-based workflow partitions with retention.\
> 🔗 [**Data mappers + workflow data models**](#data-mappers-+-workflow-data-models) - Workflow data models with input/output; process ↔ workflow mapping; CRUD endpoints.\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Reusable HTTP/HTTPS proxies attached to REST data sources.\
> ✉️ [**Two-stage attachment filtering for Email triggers**](#two-stage-attachment-filtering-for-email-triggers) - Choose which emails trigger the process and which attachments are forwarded into it.\
> ⏸️ [**Resume a process from an incoming webhook**](#resume-a-process-from-an-incoming-webhook) - Webhooks now drive Message Catch Intermediate Events with a Process Correlation Key.\
> 🌐 [**REST endpoints: content-type-aware responses**](#rest-endpoints-content-type-aware-responses) - Accept-driven JSON / text / XML parsing with XXE-safe XML; responses over 5 MiB are returned raw.\
> 📝 [**Raw endpoint payload type**](#raw-endpoint-payload-type) - Send request body as-is with the user's Content-Type preserved; XML / SOAP / form-urlencoded / plain text without MULTIPART wrapping.

> [tab] Process operations
>
> ✏️ [**Update Process Variables**](#update-process-variables) - JSON editor for variables on active instances; snapshot history; Compare diff.\
> 🛑 [**Stop workflow instances in runtime**](#stop-workflow-instances-in-runtime) - Authorized end users can stop running workflow instances from runtime.\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor.\
> 🔔 [**Notification history + template usages**](#notification-history-+-template-usages) - `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all references.\
> 📋 [**Token view improvements**](#token-view-improvements) - Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, color-coded status.\
> 🔧 **Fixed: names with square brackets** - Processes and UI flows whose names contain square brackets now start correctly again.

> [tab] Platform, deployment and infrastructure
>
> 🏢 [**Single-org self-hosted deployment**](#single-org-self-hosted-deployment) - Self-hosted default mode; guided setup wizard.\
> 🔑 [**License service**](#license-service) - Centralized license validation and usage reporting for self-hosted deployments.\
> 🔐 [**Authentication: opaque-token → JWT**](#authentication-opaque-token-→-jwt) - Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key`; dedicated service-accounts realm.\
> 🆕 [**New services to deploy**](#new-services-to-deploy) - `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. None existed in a 5.1.x deployment.\
> 🐍 [**Native script engine for JavaScript and Python**](#native-script-engine-for-javascript-and-python) - Default JS/Python execution moves from GraalVM to a Node.js + CPython subprocess pool; GraalVM available as opt-in.\
> 🌐 [**Ingress routing and CORS handling**](#ingress-routing-and-cors-handling) - NGINX ingress controller deprecated as the FlowX-shipped default; CORS moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on every backend service.\
> 📡 [**Kafka configuration alignment**](#kafka-configuration-alignment) - Standardized `KAFKA_*` env vars; mandatory `Fx-Organization-Id` header.\
> 📊 [**OpenTelemetry + SpiceDB DR**](#opentelemetry-+-spicedb-dr) - OpenTelemetry / Prometheus Helm charts published; SpiceDB backup and disaster-recovery procedures.\
> 🛡️ [**Durable message-processing**](#durable-message-processing) - Parked integration responses are persisted durably so in-flight responses survive runtime restarts, reducing stuck process tokens.\
> 🌍 [**Task management localization**](#task-management-localization) - 51 substitution tags + automatic table grid localization across 30 languages.

> [tab] Mobile & Renderers
>
> 📱 [**React Native SDK**](#react-native-sdk) - New SDK for React Native apps with process renderer, forms, navigation, and CMS integration. Demo app included.\
> 🍎 [**iOS UI Flows support**](#ios-ui-flows-support) - Full UI Flows renderer on iOS; sessions, document plugin subtypes, dismiss action, start parameters, new native components.\
> 📲 [**Mobile chat support**](#conversational-ai) - Chat component available on iOS and Android.\
> ⚛️ [**React 19 upgrade**](#react-19-upgrade) - React SDK upgraded to React 19; host apps must upgrade in lockstep.

> [tab] Info
>
> ℹ️ [**Deployment guidelines**](./deployment-guidelines-v5.9) - Component versions, environment variables, Kafka topics\
> 🗺️ [**Migrating from 5.1 LTS**](/5.9/migrating-from-5.1-lts/overview) - Consolidated upgrade path from 5.1.x LTS to 5.9.x LTS

> [card]
>
> ### **Runtime authorization completion**
>
> 5.9.0 completes the project-version-scoped runtime authorization model:
>
> * **Sharing checklist for environment promotion.** Sharing assignments do not export with builds. Each environment must be reconfigured when a project is promoted. The deployment checklist for this is now part of the setup guide.
> * **Project-level end-user roles.** Roles can be assigned at the project level from creation, so a fresh project is reachable without a separate share pass.
> * **Data-sync provisioning.** The data-sync job calls the Keycloak admin API on first run to provision FlowX-managed end-user groups and runtime roles. Five new `FLOWX_OPENID_*` env vars expose the admin credentials.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > See Setup guides → Access management → Runtime authorization for the day-to-day model.
>
> > [accordion] Key Features
> >
> > * **Per-environment sharing checklist.** When you promote a project from dev to uat to prod, the Share modal assignments do not travel with the build. The setup guide now documents the explicit per-environment reconfiguration step.
> > * **Project-level end-user roles.** Assign end-user roles at the project level so a freshly created project is reachable on day one. No separate Share-modal pass required for the default access pattern.
> > * **Data-sync Keycloak provisioning.** The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak the first time it runs against a 5.9.0 environment. Configure admin credentials with the new `FLOWX_OPENID_*` env vars on the data-sync job.
> > * **Deployment checklist included.** The runtime authorization setup guide now ships a deployment prerequisites section so the data-sync OpenID config and per-environment sharing reset are part of the standard promotion runbook.
>
> > [accordion] Configuration
> >
> > Required on the data-sync job from 5.9.0 onward:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak`. | `keycloak` |
> > | `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` |
> > | `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` |
> > | `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` |
> > | `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Set to `admin-cli` for standard Keycloak deployments. | `-` |
> >
> > See [Data-sync job setup → OpenID provider configuration](/5.9/setup-guides/data-sync#openid-provider-configuration) for the full setup.

> [card]
>
> ### **Anonymous runtime access**
>
> 5.9.0 introduces unauthenticated runtime access: an app can be made publicly reachable, and processes or UI flows inside it can be opened to anonymous end users via a new built-in role.
>
> * **Two independent gates.** The app must be set to **Everyone with the link** in the Share modal AND the process or UI flow must have the **Anonymous** role assigned. If either gate is closed, the runtime returns `403 Forbidden` (`Anonymous access not enabled for this application` / `Anonymous access not enabled for this build`).
> * **System-level Anonymous role.** Auto-seeded on every new app version, cannot be deleted or edited; allowed operations are `VIEW`, `EXECUTE`, and an auto-populated `SELF_ASSIGN`.
> * **Session-bound traffic.** Anonymous requests carry an `X-Fx-Anonymous-Session-Id` header. The backend issues a new session ID on first contact; instances are bound to that session and cannot be read by another.
> * **SDK auth-skip.** The renderer decides authenticated vs anonymous from the `authToken` parameter at initialization. Token-in-storage on the same browser silently bypasses anonymous mode — container apps must scrub the `Authorization` header on public routes.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access)
> >
> > See Platform deep-dive → User roles management → Anonymous runtime access for the full feature reference.
>
> > [accordion] Key Features
> >
> > * **Share modal public-access option.** A new **General access** section in the Share modal switches between **Everyone with the link** and **Only invited users and groups**. Default remains invited-only.
> > * **Anonymous role on processes, UI flows, and reusable UI templates.** Selectable in the Permissions tab once the role is on the version; additive to other roles.
> > * **Component hide / disable rules.** UI Designer supports an Anonymous condition in role-based hide/disable rules at the component level.
> > * **Public-build asset rule.** When a build has the Anonymous role and the app is shared publicly, all assets inside (enumerations, substitution tags, media files, themes, fonts) become reachable anonymously — except UI flows and processes that don't carry the Anonymous role.

> [card]
>
> ### **Runtime authorization overhaul**
>
> Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > Open the **Runtime authorization overhaul** documentation.

> [card]
>
> ### **UI Flow permissions**
>
> Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> >
> > Open the **UI Flow permissions** documentation.

> [card]
>
> ### **End-user access management**
>
> Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> >
> > Open the **End-user access management** documentation.

> [card]
>
> ### **Operations-editor role**
>
> New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix)
> >
> > Open the **Operations-editor role** documentation.

> [card]
>
> ### **Cross-workspace projects**
>
> Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/workspaces#cross-workspace-project-import)
> >
> > Open the **Cross-workspace projects** documentation.

> [card]
>
> ### **Cross-LTS import/export**
>
> Move project versions and builds between the **5.1.x** and **5.9.x** LTS lines, in both directions. A newer platform version imports exports produced by an older one, and exports produced on a newer version can target an older one — useful for shipping a hotfix to an environment that hasn't been upgraded yet. Compatibility is patch-agnostic: any 5.9.x patch works with any 5.1.x patch.
>
> When exporting to an older version, resources whose type doesn't exist there are excluded automatically and listed in a `manifest_excluded.json` file in the archive, so the import still succeeds. The lowest version in the export/import path defines the usable functionality.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import)
> >
> > Open the **Cross-version export and import** documentation.

> [card]
>
> ### **Active policy: group overrides**
>
> Active policy overrides can now target **runtime groups** instead of runtime roles. The override resolves the active build for every member of the group at runtime, with a priority field deciding which group wins when a user belongs to several.
>
> Role-based overrides are deprecated in the same change. The **Role** override type is gone from the Add / Edit modal, and any role overrides carried over from a 5.1.x upgrade are kept in the table for visibility only — they are flagged **DEPRECATED**, excluded from runtime resolution, and can only be deleted.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-policy)
> >
> > See Projects → Runtime → Active policy for the full configuration model.
>
> > [accordion] Key Features
> >
> > * **Group override type.** Add / Edit Policy Override now exposes **Username** and **Group**. The group picker lists runtime groups that have a runtime role configured for the current project.
> > * **Priority is mandatory and unique per project for group overrides.** Lower numbers win when several groups match the same user. Username overrides ignore priority and always take precedence.
> > * **Resolution order.** Username override → Group override (lowest priority wins) → Global policy.
> > * **Role overrides deprecated.** Removed from the Add / Edit modal. Existing role rows are rendered muted with a **DEPRECATED** marker and a red banner; only the delete action remains. Deprecated role overrides are excluded from runtime resolution.
> > * **Test panel.** The effective-policy test panel simulates resolution for a given user.
> > * **Audit log.** Group override create / update / delete / enable / disable events are recorded.
>
> > [accordion] Upgrade impact
> >
> > Upgrading from 5.1.x carries existing role overrides into the new table as deprecated entries. They no longer affect runtime behavior. Recreate the intended access using group overrides and delete the role rows. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.

> [card]
>
> ### **Roles carried across project-version merges**
>
> Application-level role definitions are now carried into the merged project version automatically. Before 5.9.0, merging two project versions could leave the role table in a partial state. Bindings defined on one side were not consistently propagated to the merged version. 5.9.0 clones the roles from the destination latest version onto the merged version atomically as part of the merge transaction, so merges with role changes complete without follow-up manual cleanup.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Roles propagated as part of the merge.** When a project version is merged, application-version roles from the destination latest version are cloned onto the merged version in the same transaction.
> > * **No manual role re-binding after merge.** Operators no longer need to re-apply role bindings on the merged version. The merge completes in a single commit; the merged version is immediately usable.

> [card]
>
> ### **Log-in page redesign**
>
> The Designer log-in page is refreshed to align with the platform's design system. When an organization has an external IdP configured, the previous fine-print fallback link is replaced with a primary button labeled with the IdP configuration's **Display name**. Field labels and call-to-action copy across the log-in flow are aligned with the rest of the UI.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **IdP provider button.** When the organization has an IdP configured, the log-in screen surfaces a primary button labeled with the IdP's **Display name**, instead of a fine-print link below the form.
> > * **Refreshed copy.** Updated labels across the flow: **Log In** replaces *Sign In*, **Reset Password** replaces *Forgot password?*, and the page title becomes **Log In**.

> [card]
>
> ### **Chat component**
>
> Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component)
> >
> > Open the **Chat component** documentation.

> [card]
>
> ### **Conversational Workflows**
>
> Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> >
> > Open the **Conversational Workflows** documentation.

> [card]
>
> ### **Voice input + Speech-to-Text**
>
> Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> >
> > Open the **Voice input + Speech-to-Text** documentation.

> [card]
>
> ### **Memory capabilities**
>
> Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> >
> > Open the **Memory capabilities** documentation.

> [card]
>
> ### **Intent Classification node**
>
> Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> >
> > Open the **Intent Classification node** documentation.

> [card]
>
> ### **Chat-based UI Flows**
>
> UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> >
> > Open the **Chat-based UI Flows** documentation.

> [card]
>
> ### **AI Triggers**
>
> Named parameterized message templates to launch conversational workflows with context.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> >
> > Open the **AI Triggers** documentation.

> [card]
>
> ### **Stop agent response**
>
> Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> >
> > Open the **Stop agent response** documentation.

> [card]
>
> ### **Chat title generation and conversation search**
>
> Chat sessions now get a meaningful title generated automatically from the user's first message. No more "untitled chat" entries in the history. End users can also search across all their conversations with a single query that scans both message bodies and session titles.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Auto-generated session title.** The first user message seeds a provisional title (first 7 words). A one-shot LLM call then refines it into a concise descriptive title; the chat list updates live via an SSE event.
> > * **Conversation search.** `/api/conversations` accepts a `q` query parameter (2–200 characters). Matches against both session titles and message bodies. Each result carries a `snippet` field showing the matched excerpt.
> > * **Title update event.** When the LLM title is generated, the gateway emits a `chatSessionRenamed` event on the chat session channel; the chat list shows the refined title on the next load.
> > * **Single-shot generation.** Title generation runs exactly once per session, on first persist. The provisional 7-word title remains in place if the LLM call fails. No error surfaces to the end user.

> [card]
>
> ### **Evaluations**
>
> 5.9.0 introduces Evaluations: score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Attach datasets to AI nodes, launch experiments, and read per-evaluator aggregate scores plus per-test-case details.
>
> * **10 built-in evaluators across three categories.** LLM-as-judge (Correctness, Conciseness, Hallucination, Answer relevance), RAG (Groundedness, Helpfulness, Retrieval relevance), and Code (Exact match, Levenshtein, JSON match). Numeric evaluators ship with default thresholds; binary evaluators return pass/fail.
> * **Datasets attached to AI nodes.** Test cases sourced manually or captured from real node executions. The dataset persists a schema snapshot so older runs remain reproducible if the workflow changes underneath.
> * **Async judge pipeline.** A new Python `evals-judge` event-driven worker consumes `ai.flowx.ai-platform.evals-judge.job.request.v1`, scores each (test case × evaluator) pair via the configured judge LLM, and publishes back on the response topic. Unscored jobs land on a DLQ for manual review.
> * **Per-org judge model.** A new `EVAL` capability is registered in the org-manager LLM catalogue. Platform default is `gpt-5.4-mini`, backfilled per org on upgrade so evals work out-of-the-box.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/evaluations)
> >
> > See AI Platform → Evaluations for the user workflow, evaluator catalogue, REST API surface, and operator setup.
>
> > [accordion] Key Features
> >
> > * **Designer workflow.** Add a dataset on an AI node, add test cases (manually or captured from a node execution), pick evaluators, launch an experiment, read aggregate + per-test-case reports.
> > * **LLM-as-judge scoring.** A judge LLM reads the model output (and optional expected output) and scores it on a single rubric, returning a numeric score plus its reasoning.
> > * **RAG-quality scoring.** Judges the retrieval side of a RAG workflow — is the retrieved context grounded, helpful, and relevant?
> > * **Deterministic code evaluators.** No LLM call. Exact match, normalized Levenshtein, and JSON-shape match against the dataset's output contract.

> [card]
>
> ### **PII Guard: per-entity detections on documents and images**
>
> PII Guard scans on document and image AI nodes now surface the same per-entity detection list already shown for text scans. The run console reports each match with its entity type, confidence, original value, and replacement, making it easy to verify what was redacted on file-based AI inputs.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Same shape as text scans.** Document and image scans now return a `detections` list with `entityKey`, `confidence`, `originalValue`, `replacement`, and `direction`, matching the existing text-scan output.
> > * **Bounding regions for document and image hits.** Each detection on a `DOCUMENT` or `IMAGE` source includes `regions` (`x`, `y`, `width`, `height`) so the run console can highlight where the entity was matched.
> > * **Source-type tagging.** Detections carry a `sourceType` of `TEXT`, `DOCUMENT`, or `IMAGE`, mirroring the wrapper's `sourceType` field so audit consumers can attribute matches to the right payload.
> > * **Backward-compatible upgrade.** On older data-privacy versions that don't yet return the analyzer pass for object endpoints, `detections` stays empty and the redacted artifacts continue to be produced and downloadable.

> [card]
>
> ### **Custom Agent nodes**
>
> AI agents that use MCP tools to act autonomously inside workflows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> >
> > Open the **Custom Agent nodes** documentation.

> [card]
>
> ### **Web Search tool for Custom Agents**
>
> Custom Agent nodes can call a built-in web search tool to look up up-to-date information from the public web during a run. Turn it on with a single toggle — the agent decides when to search based on its instructions and the user's request.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Single toggle.** Enable **Tools → Built-in tools → Use Web Search Tool** on a Custom Agent node. Off by default; no extra configuration.
> > * **Agent-driven.** The agent calls web search on its own when the task needs current information, and folds the results into its response.

> [card]
>
> ### **MCP integration**
>
> MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> >
> > Open the **MCP integration** documentation.

> [card]
>
> ### **Knowledge Bases**
>
> Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > Open the **Knowledge Bases** documentation.

> [card]
>
> ### **AI Providers self-service**
>
> Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/ai-providers)
> >
> > Open the **AI Providers self-service** documentation.

> [card]
>
> ### **Extract Data from File**
>
> LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> >
> > Open the **Extract Data from File** documentation.

> [card]
>
> ### **Web Page Extractor / Web Crawler**
>
> Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> >
> > Open the **Web Page Extractor / Web Crawler** documentation.

> [card]
>
> ### **Context Retrieval**
>
> RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> >
> > Open the **Context Retrieval** documentation.

> [card]
>
> ### **AI Developer generates Custom Components**
>
> Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> >
> > Open the **AI Developer generates Custom Components** documentation.

> [card]
>
> ### **Operational prompt split**
>
> The single Operation Prompt field on AI nodes is split into two inputs so the static portion of the prompt can be cached by the LLM provider while dynamic values are passed separately. **Instructions** holds the agent's role, tasks, and expected I/O, sent as the System message and cached between executions, so `${}` dynamic values are not allowed. The **Context** field, inside the **Background** section, takes the dynamic per-execution prompt text and supports `${}` references, sent as the User message and not cached.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Instructions: cached System message.** Mandatory. Holds the agent's role, tasks, and expected input/output. Sent as the System message and cached by the LLM between executions. `${}` references are rejected to keep the cache key stable.
> > * **Background section: dynamic User message.** Wraps the Knowledge Base selector, the **Context** textarea (free text with `${}` support), the **Use only referenced values as input** toggle, and, in Chat Driven workflows, the **Use conversation memory** toggle. Sent as the User message on every execution; not cached.
> > * **Lower LLM cost and latency.** The static portion of the prompt is sent once per cache window instead of on every execution, so each call pays only for the dynamic Background section. The longer the Instructions, the bigger the per-call saving.
> > * **Applies to every AI node subtype.** The split UI is now shared by all AI node subtypes that previously used the single Operation Prompt field.

> [card]
>
> ### **Manage Knowledge Base content from Runtime**
>
> A new **Test KB** option on the build is available in runtime, giving operators visibility into Knowledge Base content that was previously opaque after deployment. Authorized users can inspect chunks, add or replace sources, edit metadata, and query the KB without going back to the Designer. Useful for debugging retrieval issues and keeping KBs current as business knowledge evolves.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Six runtime operations.** Create store, Append content, Replace content, Delete store, Edit metadata, and Query. All from the Test KB option inside the running app.
> > * **Files and payloads.** Both file uploads and inline payloads can be added to the KB through this feature.
> > * **Permission-gated.** KB management at runtime is controlled by runtime authorization, so only users with the right role see the Test KB controls.
> > * **Visibility into chunking.** Inspect how documents were chunked and what metadata was captured, useful when debugging retrieval quality on client-uploaded content.

> [card]
>
> ### **UI Flows**
>
> 5.9.0 closes the UI Flows feature: reusable, multi-platform UI (web, iOS, Android) as first-class project resources with their own lifecycle and runtime sessions. UI Flows now reach feature parity with processes for end-user-facing apps that don't need a BPMN process underneath.
>
> * **Multi-platform.** Author once in the Designer; UI Flows render on web (React), iOS, and Android via the platform-specific renderers. Layouts and component bindings travel together as a single resource.
> * **Sessions and runtime monitoring.** Each UI Flow run is a `UiFlowSession` with its own state, navigation history, and SSE event stream. Operators can monitor and inspect sessions from the runtime.
> * **Process integration.** UI Flows can start processes (Start Process action), navigate to other UI Flows (Navigate UI action), and embed a Process Renderer to show a running process inside a UI Flow. Workflows can also be invoked from a UI Flow with a Start Workflow action.
> * **Per-UI-Flow permissions.** A dedicated Permissions tab on each UI Flow controls which roles can run it. Runtime enforces with `403`; assignments travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows)
> >
> > See Building blocks → UI Flows for the full feature reference, including Navigation Areas, session variables, route management, and the component reference.
>
> > [accordion] Key Features
> >
> > * **Navigation Areas.** Group UI components into named areas for layout, scroll, and per-area transitions.
> > * **Start Parameters and Session Variables.** Pass typed inputs into a UI Flow at start; persist state across nodes via Session Variables.
> > * **Route management.** Each UI Flow exposes a stable runtime route; nested navigation preserves browser history and back/forward behaviour.
> > * **Task Manager component.** Drop the Task Manager surface inside a UI Flow to drive process tasks from the same UI shell.
> > * **onClick and On Display events, plus a new On Load event.** Component-level events trigger workflows or UI actions, with the new On Load event firing when the UI Flow first opens.
> > * **Breadcrumbs.** Built-in breadcrumbs reflect the Navigation Area hierarchy and follow the active theme.
> > * **Process Renderer + Start Workflow action.** Embed a running process inside a UI Flow; trigger an integration workflow from a button or event without leaving the flow.

> [card]
>
> ### **UI Flow session expiry**
>
> A UI Flow session can be set to expire automatically after a fixed duration or on a schedule. Once expired, the session becomes read-only — the user keeps the data already loaded but cannot take further action.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Flexible expiry.** Set the **Expiry time** in **Settings → General** as an ISO-8601 duration (for example `PT3M22S`) or a cron expression (for example `0 0 9-17 * * MON-FRI`). Empty means no expiry.
> > * **Read-only on expiry.** Expired sessions block all actions; loaded data stays visible and nothing is wiped.
> > * **Server-enforced.** The platform marks sessions `EXPIRED` server-side, so it applies the same way in the deployed app and the Designer preview.

> [card]
>
> ### **Configurable modal component**
>
> Modals on process screens and UI Flows gain configurable content and layout. Set a title and subtitle, control dismiss behavior, and align and size the modal from the Designer.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Content.** Set the modal **Title** and **Subtitle** from the Settings panel.
> > * **Dismiss behavior.** Toggle **Dismissible**, allow **Backdrop click**, and optionally show a **Confirmation alert** with custom title, message, and button labels.
> > * **Layout.** Align content **Left**, **Center**, or **Right**, and set **Width**/**Height** to **Fixed** or **Auto**.
> > * **Theme-level styling.** The modal **shadow** and **dismiss icon** are defined once in the theme's Modal section.

> [card]
>
> ### **Custom Components**
>
> Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> >
> > Open the **Custom Components** documentation.

> [card]
>
> ### **Process Renderer in UI Flows**
>
> Embed process renderers inside UI Flows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > Open the **Process Renderer in UI Flows** documentation.

> [card]
>
> ### **UI Flow sessions monitoring**
>
> Runtime view with session list, audit log, process tracking, workflow debugging.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> >
> > Open the **UI Flow sessions monitoring** documentation.

> [card]
>
> ### **Accessibility (WCAG 2.1 AA)**
>
> Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> All Deployments

> [card]
>
> ### **New theme components**
>
> Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Open the **New theme components** documentation.

> [card]
>
> ### **Multi-file bulk upload**
>
> Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> >
> > Open the **Multi-file bulk upload** documentation.

> [card]
>
> ### **Card default collapse + Tables in Collections**
>
> Cards configurable to load collapsed; Table UI components inside Collection prototypes.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> >
> > Open the **Card default collapse + Tables in Collections** documentation.

> [card]
>
> ### **Event Handlers**
>
> The UI component configuration panel introduces a dedicated **Event Handlers** section. The legacy `flowx_props` bag is replaced by a typed, per-handler form covering action type, optional analytics, custom body, destination, and collection save-key fields. Container components (Page, Zone, Modal, Tab Bar in UI Flows; Tab on process screens) and inline components resolve their actions through the same model.
>
> Existing UI events and AI triggers are migrated automatically. A Liquibase migration runs on the first 5.9.0 boot and moves the data into the new `ui_action` model. No project re-export or re-import is required.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Typed Event Handlers.** Each handler is a named, typed entity instead of a free-form prop, making configuration easier to validate and audit.
> > * **Action type selector.** Pick the action type from a dropdown that knows which fields are required for that type.
> > * **Analytics, body, destination, save-key.** Per-handler sub-forms cover analytics events, custom request bodies, destination resolution, and collection save-key fields.
> > * **Unified for inline and container components.** Page, Zone, Modal, and Tab Bar containers in UI Flows use the same Event Handlers model as inline components; on process screens, Tab containers use it.

> [card]
>
> ### **Theming and Designer polish**
>
> > [accordion] Theming
> >
> > Form field labels, error messages, and helper text gain padding controls and scoped style variants in the theme model. Theme Admin exposes the new padding properties on segmented buttons, sliders, and input selections; the React and Angular SDKs apply the values in the renderers; the Designer preview reflects them in place. Form fields also pick up a consistent **mandatory label** style applied automatically when a field is required.
> >
> > * **Scoped variants for labels, errors, helpers.** Theme configs can override label, error, and helper styles per component without affecting other parts of the form.
> > * **Padding for segmented buttons, sliders, input selections.** Theme Admin adds label, error, and helper padding controls for these components; values flow through to all renderers.
> > * **Mandatory label style.** A consistent style for mandatory-field labels, applied automatically when a form field is required.
> > * **Designer preview parity.** Theme overrides and paddings are visible in the Designer preview without round-tripping through a runtime app.
> >
> > All Deployments
>
> > [accordion] Designer polish
> >
> > The command center floating action button is now hidden on the running-instance screens of Processes, UI Flows, and UI Templates, where it overlapped with the instance view; it reappears when the instance data panel is open. The command center remains reachable through the standard keyboard shortcut and from screens where it does not interfere.
> >
> > All Deployments

> [card]
>
> ### **Email Trigger**
>
> New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> >
> > Open the **Email Trigger** documentation.

> [card]
>
> ### **Microsoft Outlook data source**
>
> Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> >
> > Open the **Microsoft Outlook data source** documentation.

> [card]
>
> ### **Incoming Webhooks**
>
> New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> >
> > Open the **Incoming Webhooks** documentation.

> [card]
>
> ### **Oracle Database integration**
>
> Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL. Beyond tables and `SELECT`, queries can also target views, functions, and stored procedures, with output parameters returned to the workflow.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> >
> > Open the **Oracle Database integration** documentation.

> [card]
>
> ### **Unmanaged MongoDB data source**
>
> Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> >
> > Open the **Unmanaged MongoDB data source** documentation.

> [card]
>
> ### **File Storage data source**
>
> A new data source connecting workflows to external file storage — FTP, SFTP, S3 / S3-compatible, or Azure Blob Storage. Define named List, Download, Upload, Delete, and Move operations scoped to a root path, browse and test them in Designer, and call them from a Data Source node. Operations run in the new `file-gateway` service, exchanging files with the `document-plugin`.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/file-storage)
> >
> > Open the **File Storage data source** documentation.

> [card]
>
> ### **Send Notification action + Email Sender**
>
> SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> >
> > Open the **Send Notification action + Email Sender** documentation.

> [card]
>
> ### **Advanced Query Builder**
>
> Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> >
> > Open the **Advanced Query Builder** documentation.

> [card]
>
> ### **Parallel branches in workflows**
>
> Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> All Deployments

> [card]
>
> ### **REST endpoint caching + workflow partitioning**
>
> TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> All Deployments

> [card]
>
> ### **Data mappers + workflow data models**
>
> Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> >
> > Open the **Data mappers + workflow data models** documentation.

> [card]
>
> ### **Proxy Server Connections**
>
> Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> >
> > Open the **Proxy Server Connections** documentation.

> [card]
>
> ### **Faster authoring loop**
>
> 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.
>
> All Deployments

> [card]
>
> ### **Meta webhook provider**
>
> Incoming Webhooks add **Meta** as a built-in provider alongside Generic and Slack, covering WhatsApp, Messenger, Instagram, and Threads. The webhook-gateway handles the Meta-specific subscription handshake and signature verification natively. No custom adapter code required to wire a Meta-platform integration into a FlowX process.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Subscription handshake.** The gateway answers Meta's GET URL-verification request by validating `hub.mode=subscribe` and the provided `hub.verify_token` against the configured verify token, then echoes `hub.challenge` back. Constant-time token comparison.
> > * **X-Hub-Signature-256 verification.** Every POST is authenticated with the `X-Hub-Signature-256` HMAC-SHA256 signature using the configured app secret. Requests with missing or invalid signatures are rejected before reaching the process engine.
> > * **Two secrets per webhook.** When you create a Meta webhook in Integration Designer, two masked inputs appear in the configuration panel: **Verify token** (used during the handshake) and **App secret** (used for signature verification). Both are required.
> > * **Multi-product support.** A single Meta webhook can receive events from WhatsApp, Messenger, Instagram, and Threads. The provider is configured at the webhook level; the channel is part of the payload.
>
> > [accordion] Configuration
> >
> > Select **Meta** in the provider dropdown when creating the webhook data source. Both secret fields are required:
> >
> > | Field | Description |
> > | - | - |
> > | **Verify token** | The token Meta sends back during the GET URL-verification handshake. Choose any string; configure the same value on the Meta App developer console. |
> > | **App secret** | The App secret from the Meta App configuration; used to verify the `X-Hub-Signature-256` HMAC on every POST. |
> >
> > Both values are stored as a JSON-packed pair on the existing webhook secret field. No schema migration is required.
> >
> > See [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#meta-provider) for the full setup walk-through.

> [card]
>
> ### **Documents in process instances**
>
> Each process instance now exposes a dedicated **Documents** tab. A single source of truth for every document handled during the process, regardless of how it entered the instance. Operations teams can review tracking metadata, preview, and download attached files from one place rather than walking through the process timeline.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **All document sources in one place.** End-user uploads via the file-upload component, attachments from email triggers, files generated from HTML templates, OCR output, and files produced by AI workflow nodes, all listed under one tab.
> > * **Tracking metadata and preview.** Each row shows source, timestamp, and uploader, with inline preview for supported file types.
> > * **Direct download.** Download any attached document directly from the Documents tab.
> > * **Faster operations review.** No more clicking through the process timeline to reconstruct which file came in at which step.

> [card]
>
> ### **Two-stage attachment filtering for Email triggers**
>
> Email triggers (IMAP and Microsoft Outlook) now expose a two-stage filter on each trigger: choose which incoming emails create a process instance, then choose which attachments are forwarded into the process. The previous single on/off validations toggle is replaced with explicit, per-trigger control over inbound mail.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start Process for.** Trigger the process for all emails, only emails with attachments, or only emails carrying selected file types (PDF, DOCUMENT, IMAGE, EXCEL, ZIP).
> > * **Save email attachments on process.** Forward all attachments, none (metadata-only), or only specific file types into the process instance.
> > * **Trigger-level rejection.** Emails that fail the trigger condition or exceed **Maximum File Count** are rejected with explicit Failed Triggers causes. **No attachments**, **No matching file types**, **File count exceeded**.
> > * **Backward-compatible upgrade.** Existing triggers are migrated to **All incoming emails** + **All attachments** with no manual intervention. Reopen each trigger to reapply file-type filtering if you previously relied on the validations toggle.

> [card]
>
> ### **Resume a process from an incoming webhook**
>
> Incoming Webhooks can now drive a **Message Catch Intermediate Event**, not just a Message Start Event. When a process is paused on an intermediate catch event, an external system can POST to the webhook to resume that specific instance. Useful for callbacks from third-party services, asynchronous job completions, or operator actions delivered over HTTP.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start or resume from one webhook model.** The same webhook data source can start new processes (on a Message Start Event) or resume waiting ones (on a Message Catch Intermediate Event). The trigger type is set automatically based on where the webhook is attached.
> > * **Process Correlation Key.** Each intermediate catch event declares a Process Correlation Key (a business variable like `applicationId`). The webhook-gateway matches this value against the incoming payload to route the resume to the right process instance. The Webhook Correlation Key now accepts array indices in square brackets (`entry[0].changes[0].value.messages[0].text.body`), so the canonical Meta WhatsApp resume path works without flattening upstream.
> > * **Validation at design time.** Process Correlation Key and Process Key are required on intermediate webhook catch events and are validated when the message event is created or updated.
> > * **Backward-compatible upgrade.** Existing webhooks are migrated to `triggerType=START_PROCESS` with no manual intervention. New webhooks attached to an intermediate catch event are flagged `RESUME_PROCESS` automatically.

> [card]
>
> ### **REST endpoints: content-type-aware responses**
>
> REST endpoint responses in Integration Designer are now parsed by content type rather than assumed to be JSON. The endpoint's `Accept` header drives parsing: JSON, plain text, and XML responses are each handled with the right parser, and the original XML string is preserved alongside the parsed map so downstream nodes can read either form. Existing JSON-returning endpoints continue to work without configuration changes.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Accept-driven response parsing.** The endpoint's `Accept` header decides how the response is parsed. JSON variants (`application/json`, `application/hal+json`, `application/problem+json`, any `+json` suffix) are parsed as JSON; `text/*` is returned as a string; XML variants (`application/xml`, `text/xml`, `application/soap+xml`, any `+xml` suffix) are parsed into a JSON-shaped map. When `Accept` is missing, the endpoint falls back to `Content-Type`, then to **AUTO** best-effort.
> >
> > * **XML responses parsed into JSON-shaped objects.** XML response bodies are auto-converted to maps so existing path expressions (`response.body.someField`) work without code changes. The original XML string is preserved on `sourceBody` for callers that need it raw.
> >
> > * **Loud failures on declared mismatches.** When an endpoint declares JSON or XML and the upstream returns a different category, or returns a body that fails to parse, the node fails with a precise error message (for example, `Expected response content type "application/json" but received "text/plain"`). The original body is preserved on `rawBody`.
> >
> > * **Tolerant under AUTO and wildcards.** Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) and inferred categories (no `Accept` declared) fall back to the raw string instead of failing. Flaky or mislabelled upstreams don't break the node.
> >
> > * **XXE-safe XML parser.** XML parsing has DTD processing and external-entity resolution disabled by construction. External-entity attack payloads are neutralized; billion-laughs / entity-expansion attacks cannot fire.
> >
> > * **File downloads bypass Content-Type checks.** File-download endpoints (BINARY or BASE64) deliver the platform's own JSON payload regardless of upstream `Content-Type`, so legacy PDF, octet-stream, and image downloads work unchanged.
> >
> > * **Large XML returned raw.** XML response bodies larger than 5 MiB are returned as the raw string instead of a parsed map, so very large payloads don't block the node.
> >
> > > [!WARNING]
> > >
> > > **Mixed-content XML responses expose a new `value` key.** An XML element with both attributes and inner text (`<leaf attr="v">text</leaf>`) is now parsed to `{attr: "v", value: "text"}`. The inner text used to be silently dropped. Downstream nodes that iterate response keys or assert the exact key set on mixed-content elements may see an additional `value` entry. Path expressions that addressed attributes or child elements directly are unaffected.

> [card]
>
> ### **Raw endpoint payload type**
>
> REST endpoint configuration adds a **Raw** content type alongside JSON, Multipart, and Binary. Raw bodies are sent to the upstream system as-is. Useful for XML, SOAP envelopes, form-urlencoded payloads, or any plain-text body where you need to set the `Content-Type` header yourself.
>
> Before 5.9.0, the only way to send a non-JSON textual body was to use Multipart, which wrapped the payload in `multipart/form-data` and overrode the `Content-Type` header. Raw removes that wrapping.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Body sent as-is.** The body field is sent verbatim. The dispatcher does not transform, wrap, or pretty-print it.
> > * **Caller controls Content-Type.** Set the `Content-Type` header on the endpoint to whatever the upstream expects (`text/xml`, `application/soap+xml`, `application/x-www-form-urlencoded`, `text/plain`). The dispatcher does not override it.
> > * **Monaco plain-text mode.** The endpoint editor switches Monaco to plain text when Raw is selected. XML and SOAP indentation are preserved on paste and edit instead of being reformatted as JSON.
> > * **Shares the JSON body slot.** Raw and JSON payloads use the same storage field on the endpoint definition, so no schema migration is required. Existing endpoints continue to work without changes.

> [card]
>
> ### **Update Process Variables**
>
> JSON editor for variables on active instances with snapshot history; Compare diff.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> >
> > Open the **Update Process Variables** documentation.

> [card]
>
> ### **Stop Run for workflows**
>
> Cancel a running workflow instance from the editor.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-workflows#running-and-stopping-workflows)
> >
> > Open the **Stop Run for workflows** documentation.

> [card]
>
> ### **Notification history + template usages**
>
> `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> >
> > Open the **Notification history + template usages** documentation.

> [card]
>
> ### **Token view improvements**
>
> Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/token)
> >
> > Open the **Token view improvements** documentation.

> [card]
>
> ### **Stop workflow instances in runtime**
>
> Authorized end users can now stop running workflow instances directly from runtime. Previously, stopping a workflow required Designer access or a direct API call. The new control surfaces the action inside the runtime application alongside other workflow-instance management options.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **One-click stop.** Stop a running workflow instance from the runtime instance list.
> > * **Permission-gated.** The stop control is governed by runtime authorization.
> > * **Audited.** Stop actions are recorded on the workflow-instance audit log with the actor and timestamp.

> [card]
>
> ### **Native script engine for JavaScript and Python**
>
> The default script engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a **native subprocess pool**. Scripts run in long-running Node.js and Python worker processes managed by `process-engine` and `integration-designer`. Existing scripts that read from `input` and write to `output` keep working, including `output.put(...)`, `output.get(...)`, and bracket assignment.
>
> The change is opt-out: set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services to keep the previous engine.
>
> Self-HostedAll Deployments
>
> > [accordion] Key Features
> >
> > * **Node.js workers for JavaScript.** JavaScript runs in isolated Node.js worker processes. Each script executes in a fresh V8 context with an explicit globals allowlist and a V8-level execution timeout.
> > * **CPython workers for Python.** Python 3 runs in isolated worker processes with a curated sandbox. Common standard-library modules (`random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64`) are available without `import`. Process, OS, and network modules are blocked.
> > * **Worker pools with recycling.** Worker pools default to 16 Node.js workers and 8 Python workers, sized per service. Workers are recycled after a configurable number of executions to prevent state leakage.
> > * **HashMap method compatibility.** The familiar `output.put(key, value)`, `output.get(key)`, and `output.containsKey(key)` methods continue to work on both JavaScript and Python. The same scripts that ran under GraalVM polyglot context keep working without rewrites.
> > * **GraalVM still available as opt-in.** Set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine, useful if a script depends on GraalVM-specific polyglot features.
> > * **Hardened execution sandbox.** Per-execution fresh scope, environment variables cleared at worker startup, dangerous Python module references scrubbed before user code runs, no `require` / `process` / `global` access in JavaScript.
>
> > [accordion] Configuration
> >
> > The native engine is the default on `process-engine` and `integration-designer`. Tune worker pools and timeouts as needed:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider. `native` or `graalvm`. | `native` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size. | `16` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS execution timeout per script (ms). | `5000` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size. | `8` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python execution timeout per script (ms). | `10000` |
> >
> > See [Process engine setup → Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration) and [Integration Designer setup → Script engine configuration](/5.9/setup-guides/integration-designer-setup#script-engine-configuration) for the full set including payload size and worker recycling.
>
> > [accordion] Migration impact
> >
> > For most existing scripts the change is transparent. The `input`, `output`, `additionalData`, and `instanceMetadata` bindings behave the same, and HashMap-style access on `output` is preserved.
> >
> > Scripts that need attention:
> >
> > * **Python scripts that `import` modules outside the curated allowlist.** Narrow the script to use only the pre-loaded modules, or stay on GraalVM via the opt-out env var.
> > * **JavaScript scripts that reach for `require(...)`, `process`, or `global`.** Those references were never part of the supported surface area but may have worked under GraalVM. Rewrite to use only the bindings provided, or stay on GraalVM via the opt-out env var.
> > * **Scripts that depended on GraalVM-specific polyglot APIs** (calling Java classes from JavaScript / Python). Stay on GraalVM via the opt-out env var.
> >
> > See [Script runtime change for JavaScript and Python business rules](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit checklist.

> [card]
>
> ### **Single-org self-hosted deployment**
>
> Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/organization-deployment)
> >
> > Open the **Single-org self-hosted deployment** documentation.

> [card]
>
> ### **License service**
>
> Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> >
> > Open the **License service** documentation.

> [card]
>
> ### **Authentication: opaque-token → JWT**
>
> Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/authentication-iam)
> >
> > Open the **Authentication: opaque-token → JWT** documentation.

> [card]
>
> ### **New services to deploy**
>
> `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/prerequisites#new-services-to-deploy)
> >
> > Open the **New services to deploy** documentation.

> [card]
>
> ### **Ingress routing and CORS handling**
>
> The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/ingress-routing)
> >
> > Open the **Ingress routing and CORS handling** documentation.

> [card]
>
> ### **Kafka configuration alignment**
>
> Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/kafka)
> >
> > Open the **Kafka configuration alignment** documentation.

> [card]
>
> ### **OpenTelemetry + SpiceDB DR**
>
> OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> All Deployments

> [card]
>
> ### **Durable message-processing**
>
> The process engine now persists parked integration and external-message responses durably, so a response that arrives before its process is ready to consume it survives a runtime restart instead of being lost. This removes a class of stuck process-token failures and improves message-processing robustness at runtime.
>
> All Deployments

> [card]
>
> ### **Task management localization**
>
> 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Open the **Task management localization** documentation.

> [card]
>
> ### **React Native SDK**
>
> FlowX 5.9.0 ships a brand-new **React Native SDK**, bringing the same process renderer model that has powered the React, Angular, iOS, and Android SDKs to React Native apps. Teams building cross-platform mobile or embedded React Native experiences can now host FlowX processes natively, with forms, navigation, and CMS integration handled by the SDK.
>
> A companion demo app is included as a reference integration, covering authentication, the showcase page, and the wiring needed to start a process from inside a container app.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Process renderer.** Render FlowX processes inside any React Native screen with the same component model as the other SDKs.
> > * **Forms and basic components.** Page, Button, Text, Container, Card, and form components ship out of the box.
> > * **CMS integration.** Static content and theming load from the FlowX CMS, including dynamic display values.
> > * **Navigation.** Basic process navigation between screens follows the same patterns as the iOS and Android SDKs.
> > * **Demo app included.** A demo app with authentication and a showcase page is shipped alongside the SDK as a reference integration.

> [card]
>
> ### **iOS UI Flows support**
>
> The iOS renderer reaches feature parity with the React and Angular renderers on UI Flows. iOS apps can now start UI Flows from container apps, manage UI Flow sessions, dismiss modals, handle UI actions, and render document-plugin subtypes (images and document previews).
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start UI Flow from container app.** Container apps can launch a UI Flow with start parameters and handle the response.
> > * **UI Flow session management.** The renderer manages a UI Flow session lifecycle on iOS the same way it does on web.
> > * **onLoad UI Event for Page.** Pages emit an `onLoad` UI Event that iOS handlers can listen to, matching the cross-platform event model.
> > * **Dismiss action and dismiss-on-completion.** A `dismiss` action type cleanly closes modals; `dismiss on completion` on `START_WORKFLOW` actions auto-closes the launching modal when the workflow finishes.
> > * **UI Flow start params.** Pass typed start parameters into a UI Flow at launch.
> > * **Upload File support.** UI Flows on iOS support file upload, including image and document-preview document-plugin subtypes.
> > * **Updated start-process endpoint.** The iOS renderer uses the latest start-process endpoint and `data` property on Start UI Flow, aligned with the web SDKs.
> > * **New native components.** Tooltip, Separator, Progress View, and Markdown components are now rendered natively on iOS, bringing the iOS component set closer to parity with the React and Angular renderers.
> > * **Accessibility properties from UI Designer.** Accessibility properties configured in the UI Designer flow through to the iOS renderer, so screen reader labels and traits are honored on native screens.

> [card]
>
> ### **React 19 upgrade**
>
> The React SDK upgrades to **React 19**, picking up the runtime improvements and APIs that ship with that release. Surrounding `@flowx/*` packages are upgraded in lockstep so the renderer continues to work as a single coherent bundle.
>
> Host apps embedding the React renderer should plan a React 19 upgrade on their side and run the standard React migration checks before adopting 5.9.0.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **React 19 runtime.** Adopts the React 19 reconciler and the APIs that ship with that release.
> > * **Packages upgraded in lockstep.** All `@flowx/*` web SDK packages move to the same baseline so the renderer ships as one coherent bundle.
>
> > [accordion] Host app impact
> >
> > Host apps that embed the React renderer must be on React 19 themselves. Run the React 19 codemods and verify any third-party React libraries you depend on are compatible before upgrading FlowX.

> [card]
>
> ### **Runtime authorization and sharing**
>
> This is the biggest governance change in the 5.1 → 5.9 upgrade. End-user identities, runtime roles, and sharing assignments move out of Keycloak into FlowX-managed records, with project-version-scoped roles and a dedicated Share modal flow on Solutions.
>
> > [card] [Runtime authorization completion](#runtime-authorization-completion)
> >
> > Closes the rewrite: per-environment sharing checklist, project-level end-user roles, data-sync Keycloak provisioning. See the 5.9.0 card above.
>
> > [card] [Anonymous runtime access](#anonymous-runtime-access)
> >
> > Built-in `Anonymous` role + Share modal "Everyone with the link" option for unauthenticated end users. Session-bound (`X-Fx-Anonymous-Session-Id`), fire-and-forget; per-component hide/disable rules; SDK auth-skip mode.
>
> > [card] [Runtime authorization overhaul](#runtime-authorization-overhaul)
> >
> > Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> > [card] [UI Flow permissions](#ui-flow-permissions)
> >
> > Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> > [card] [End-user access management](#end-user-access-management)
> >
> > Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> > [card] [Operations-editor role](#operations-editor-role)
> >
> > New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> > [card] [Cross-workspace projects](#cross-workspace-projects)
> >
> > Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.

> [card]
>
> ### **Conversational AI**
>
> 5.9 takes FlowX from no chat to production conversational AI: the Chat component, conversational workflows with memory and intent classification, voice and speech-to-text, chat-based UI Flows, and runtime controls.
>
> > [card] [Chat component](#chat-component)
> >
> > Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> > [card] [Conversational Workflows](#conversational-workflows)
> >
> > Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> > [card] [Voice input + Speech-to-Text](#voice-input-+-speech-to-text)
> >
> > Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> > [card] [Memory capabilities](#memory-capabilities)
> >
> > Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> > [card] [Intent Classification node](#intent-classification-node)
> >
> > Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> > [card] [Chat-based UI Flows](#chat-based-ui-flows)
> >
> > UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> > [card] [AI Triggers](#ai-triggers)
> >
> > Named parameterized message templates to launch conversational workflows with context.
>
> > [card] [Stop agent response](#stop-agent-response)
> >
> > Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.

> [card]
>
> ### **AI Agents and Knowledge**
>
> The agent-builder story: Custom Agents, MCP integration, Knowledge Bases for RAG, document and web extraction, AI Providers self-service, and PII Guard.
>
> > [card] [Evaluations (Evals)](#evaluations)
> >
> > Score AI node outputs against test cases with 10 built-in evaluators (LLM-as-judge: correctness, conciseness, hallucination, answer-relevance; RAG: groundedness, helpfulness, retrieval-relevance; code: exact-match, Levenshtein, JSON-match). Datasets attached to AI nodes, async judge pipeline via the new `evals-judge` service + 3 Kafka topics, per-org judge model via the new `EVAL` capability (default `gpt-5.4-mini`).
>
> > [card] [Custom Agent nodes](#custom-agent-nodes)
> >
> > AI agents that use MCP tools to act autonomously inside workflows.
>
> > [card] [MCP integration](#mcp-integration)
> >
> > MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> > [card] [Knowledge Bases](#knowledge-bases)
> >
> > Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> > [card] [AI Providers self-service](#ai-providers-self-service)
> >
> > Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> > [card] [PII Guard](#pii-guard-per-entity-detections-on-documents-and-images)
> >
> > Per-AI-node guardrail with Strict / Balanced / Relaxed presets, input/output scans, file redaction. 5.9.0 adds per-entity detections on documents and images. See the 5.9.0 card above.
>
> > [card] [Extract Data from File](#extract-data-from-file)
> >
> > LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> > [card] [Web Page Extractor / Web Crawler](#web-page-extractor-/-web-crawler)
> >
> > Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> > [card] [Context Retrieval](#context-retrieval)
> >
> > RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> > [card] [AI Developer generates Custom Components](#ai-developer-generates-custom-components)
> >
> > Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.

> [card]
>
> ### **UI Flows and Custom Components**
>
> Build user-facing apps without a process. UI Flows reach feature parity with processes; Custom Components let teams ship React code inside the Designer.
>
> > [card] [UI Flows](#ui-flows)
> >
> > Reusable multi-platform UI (web / iOS / Android) as project resources. Navigation Areas, Start Process / Navigate UI actions, Task Manager component. Breadcrumbs + Sessions monitoring. Process Renderer + Start Workflow action + On Load event. Route management + Start Parameters + Session Variables + onClick / On Display events. UI Flow permissions.
>
> > [card] [Custom Components](#custom-components)
> >
> > Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> > [card] [Process Renderer in UI Flows](#process-renderer-in-ui-flows)
> >
> > Embed process renderers inside UI Flows.
>
> > [card] [UI Flow sessions monitoring](#ui-flow-sessions-monitoring)
> >
> > Runtime view with session list, audit log, process tracking, workflow debugging.
>
> > [card] [Accessibility (WCAG 2.1 AA)](#accessibility-wcag-2-1-aa)
> >
> > Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> > [card] [New theme components](#new-theme-components)
> >
> > Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> > [card] [Multi-file bulk upload](#multi-file-bulk-upload)
> >
> > Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> > [card] [Card default collapse + Tables in Collections](#card-default-collapse-+-tables-in-collections)
> >
> > Cards configurable to load collapsed; Table UI components inside Collection prototypes.

> [card]
>
> ### **Integration and Data Platform**
>
> For builders connecting FlowX to enterprise systems, 5.9 adds new data sources, new triggers, parallel workflow execution, REST resilience, and visual query authoring.
>
> > [card] [Email Trigger](#email-trigger)
> >
> > New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> > [card] [Microsoft Outlook data source](#microsoft-outlook-data-source)
> >
> > Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> > [card] [Incoming Webhooks](#incoming-webhooks)
> >
> > New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> > [card] [Oracle Database integration](#oracle-database-integration)
> >
> > Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL.
>
> > [card] [Unmanaged MongoDB data source](#unmanaged-mongodb-data-source)
> >
> > Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> > [card] [Send Notification action + Email Sender](#send-notification-action-+-email-sender)
> >
> > SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> > [card] [Advanced Query Builder](#advanced-query-builder)
> >
> > Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> > [card] [Parallel branches in workflows](#parallel-branches-in-workflows)
> >
> > Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> > [card] [REST endpoint caching + workflow partitioning](#rest-endpoint-caching-+-workflow-partitioning)
> >
> > TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> > [card] [Data mappers + workflow data models](#data-mappers-+-workflow-data-models)
> >
> > Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> > [card] [Proxy Server Connections](#proxy-server-connections)
> >
> > Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> > [card] [Faster authoring loop](#faster-authoring-loop)
> >
> > 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.

> [card]
>
> ### **Process operations**
>
> Day-2 operations for runtime teams: edit live process state, inspect tokens with more context, audit notifications, and operate on workflow instances.
>
> > [card] [Update Process Variables](#update-process-variables)
> >
> > JSON editor for variables on active instances with snapshot history; Compare diff.
>
> > [card] [Stop Run for workflows](#stop-run-for-workflows)
> >
> > Cancel a running workflow instance from the editor.
>
> > [card] [Notification history + template usages](#notification-history-+-template-usages)
> >
> > `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> > [card] [Token view improvements](#token-view-improvements)
> >
> > Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> 5.9.0 adds **Stop workflow instances in runtime** and **Documents in process instances**. See the 5.9.0 cards above.

> [card]
>
> ### **Platform, deployment and infrastructure**
>
> Read this first if you operate a self-hosted deployment. 5.9 adds new microservices, a new deployment mode, and the auth architecture transition.
>
> > [card] [Single-org self-hosted deployment](#single-org-self-hosted-deployment)
> >
> > Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> > [card] [License service](#license-service)
> >
> > Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> > [card] [Authentication: opaque-token → JWT](#authentication-opaque-token-→-jwt)
> >
> > Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> > [card] [New services to deploy](#new-services-to-deploy)
> >
> > `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> > [card] [Native script engine for JavaScript and Python](#native-script-engine-for-javascript-and-python)
> >
> > JavaScript and Python business rules and workflow scripts run on a Node.js + CPython subprocess pool by default. HashMap-style access on `output` is preserved; GraalVM remains available via `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`. See the 5.9.0 card above and the migration audit checklist.
>
> > [card] [Ingress routing and CORS handling](#ingress-routing-and-cors-handling)
> >
> > The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> > [card] [Kafka configuration alignment](#kafka-configuration-alignment)
> >
> > Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> > [card] [OpenTelemetry + SpiceDB DR](#opentelemetry-+-spicedb-dr)
> >
> > OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> > [card] [Task management localization](#task-management-localization)
> >
> > 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.

***

## Deployment notes

> [card] [Deployment guidelines v5.9.0](./deployment-guidelines-v5.9)
>
> Component versions, environment variables, Kafka topics, and self-hosted upgrade guidance.

> [card] [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview)
>
> Consolidated 5.1 LTS → 5.9 LTS migration guide. Direct upgrade to 5.9.0.


# Deployment guidelines v5.9.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1

Component versions, configuration, and deployment notes for FlowX.AI 5.9.1 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.1 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.0 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.0 → 5.9.1**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

## Component versions

### Core components

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **process-engine** | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.3 |
| **admin** | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.3 |
| **designer** | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.4 |
| **cms-core** | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.2 |
| **scheduler-core** | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.2 |
| **events-gateway** | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.2 |
| **notification-plugin** | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.2 |
| **document-plugin** | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.2 |
| **task-management-plugin** | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.2 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |
| **data-search** | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.2 |
| **audit-core** | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.2 |
| **advancing-controller** | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.2 |
| **integration-designer** | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.3 |
| **application-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **runtime-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **data-sync** | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.2 |
| **authorization-system** | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.2 |
| **nosql-db-runner** | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.2 |
| **email-gateway** | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-native-sdk** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/core-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **react-saas** | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.20 |
| **Android renderer** | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.24 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-knowledgebase-rag** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-embedder** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-agent-builder** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-gateway** | 10.17.0 | 10.7.0 | - | - |
| **ai-platform-ai-analyst** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-assistant** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-ai-designer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-developer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-planner** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-kb-enrichment** | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.1 adds two Kafka topics. Both are **auto-provisioned by the Helm chart** — no manual creation is required for standard deployments. The names and env vars are listed here for environments that provision topics or ACLs manually.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | application-manager | process-engine | Runtime config-param change events; invalidates the build cache |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine | integration-designer | Notifies that a runtime instance has been terminated |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin | process-engine | Resource cache eviction triggered when a process version changes |
| `ai.flowx.evals.suggestions.job.request.v1` | integration-designer | AI Platform | Evaluation improvement-suggestion job requests |
| `ai.flowx.evals.suggestions.job.response.v1` | AI Platform | integration-designer | Evaluation improvement-suggestion job responses |

Topic env vars and consumer groups:

| Topic | Producer var (OUT) | Consumer var (IN) | Consumer group |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | `config-params` |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_OUT` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_IN` | `integration-designer-runtime-instance-terminated-group` |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT_IN` | `resource-cache-evict` |
| `ai.flowx.evals.suggestions.job.request.v1` | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT` | — (consumed by AI Platform) | — |
| `ai.flowx.evals.suggestions.job.response.v1` | — (produced by AI Platform) | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN` | `integration-designer-evals-suggestions-response-group` |

For the config-param cache-invalidation behavior, see [Engine setup → Topics related to runtime config params](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-runtime-config-params). For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.1 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including split AI permissions, the legacy script flag, and File Storage and document-preview fixes.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.0 → 5.9.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.1** is a maintenance release for the 5.9.x LTS with bug fixes, security patches, and a few targeted improvements:
>
> * **Import/export:** stability and cross-version compatibility fixes
> * **Split AI permissions:** separate governance for AI runtime usage and AI build-time tooling
> * **Legacy script flag:** per-rule Native / GraalVM script runtime selection
> * **File Storage and document-preview improvements**
> * Wide set of Designer, Renderer, and platform bug fixes
> * No breaking changes; fully compatible upgrade from 5.9.0

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Split AI permissions**](#split-ai-permissions) - Independent governance for AI usage and AI build tooling.\
> 📝 [**Legacy script flag**](#legacy-script-flag) - Per-rule Native / GraalVM script runtime selection.\
> 🗂️ [**File Storage improvements**](#file-storage-improvements) - FTP connection and preview fixes.\
> 📄 [**File Preview scroll events**](#file-preview-scroll-events) - Scroll-trigger event handlers for the File Preview component.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, Workflows, and backend bug fixes plus security patches.
>
> ***
>
> ### **Split AI permissions**
>
> > [card] Separate governance for AI usage and AI build tooling
> >
> > > [tab] Overview
> > >
> > > AI permissions are now split into two independent controls, so administrators can govern **AI runtime usage** separately from **AI build-time tooling** (AI Designer, agent building, code generation).
> >
> > > [tab] Behavior
> > >
> > > * When AI is turned off, AI-related icons and entry points are hidden rather than shown in a disabled state.
> > > * AI nodes in workflows behave consistently with the gateway's availability.
> > > * Build-time AI helpers (code generation, "Add comment") follow the dev-agent permission rather than the runtime AI permission.
> >
> > All Deployments
>
> ***
>
> ### **Legacy script flag**
>
> > [card] Per-rule Native / GraalVM script runtime
> >
> > Business rules, reusable functions, and node rules can now choose their script engine individually: the current **native** engine (the 5.9 default) or the legacy **GraalVM** engine. Rules created before the switch to native keep running on GraalVM until you migrate them, while new rules default to native, so teams can move scripts across at their own pace. The per-rule selector only appears for rules that support GraalVM; new rules run on native.
> > All Deployments
>
> ***
>
> ### **File Storage improvements**
>
> > [card] FTP connection and preview fixes
> >
> > * FTP **test connection** now resolves configuration-parameter placeholders before connecting.
> > * **File operations** also resolve configuration-parameter placeholders at runtime.
> > * FTP **file preview** works when the root path has no leading slash.
> >   All Deployments
>
> ***
>
> ### **File Preview scroll events**
>
> > [card] Scroll-trigger event handlers for File Preview
> >
> > The **File Preview** component now supports **scroll-trigger event handlers** (including a "document end" trigger), configurable in the Designer and handled by the web, iOS, and Android renderers. They let a flow detect when a user scrolls through a document or reaches its end.
> >
> > This is built for consent and disclosure use cases such as banking flows that must prove, per local regulation, that the user actually read an agreement. You can keep an action such as a **Submit** or **Accept** button hidden or disabled until the document-end event handler fires; that handler can be a simple local script that sets a flag to enable the button.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Forms to validate:** fixed scrolling through the full component hierarchy, placeholder updates, and incorrect selection of chat and tab-bar components.
> > > > * **Process instances:** fixed a browser crash when loading instances with very large execution graphs.
> > > > * **Theme admin:** fixed theme content being lost when using "copy to".
> > > > * **UI Flow:** fixed images not displaying in preview after refresh, and a missing theme UUID when returning from an expired UI Flow.
> > > > * **Actions:** stopped GET actions firing with undefined parameters.
> > > > * **Modals:** fixed dropdown flicker and layout issues with long key names.
> > >
> > > > [accordion] Renderer fixes (Web / React / React Native)
> > > >
> > > > * **Web:** fixed missing button shadow, modal content padding, and rendering when a media-file storage path is null.
> > > > * **File Preview:** fixed preview not rendering correctly, events not firing inside collections, fixed height not applied at runtime, and CORS errors when accessing preview resources.
> > > > * **React Native:** fixed date-picker shifting to a previous day and input/textarea retaining focus after moving to another component.
> > > > * **Task management:** fixed header theming (React/Angular) and the filter window disappearing after applying criteria.
> > > > * **File upload:** the upload button now supports a configurable icon, set in the Designer and rendered on web, iOS, and Android.
> >
> > > [tab] Workflows & AI
> > >
> > > > [accordion] Workflow fixes
> > > >
> > > > * Fixed END PARALLEL output including data from before the parallel branches started.
> > > > * Optimized storage of running steps for workflows.
> > > > * Fixed a crash in NoSQL node run logs when a node failed before building its options.
> > > > * Workflows and processes launched from a UI Flow now inherit the build from the parent UI Flow.
> > > > * AI node failures now surface the error details and model reasoning in the workflow run logs, making failed AI steps easier to diagnose.
> > >
> > > > [accordion] AI improvements & fixes
> > > >
> > > > * **AI Designer** generates more reliable UI from a flat template format (replacing the previous 3-level nesting), supports additional component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates by applying changes incrementally instead of regenerating from scratch, and can now generate **reusable UI templates**.
> > > > * Fixed agent responses reappearing in chat after stop and refresh.
> > > > * Fixed duplicated messages in the builder-agent chat.
> > > > * **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
> > > > * **Platform Status** now reports AI Platform components and their databases alongside the core services.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * Fixed a null value being wrongly cached when looking up the "All end-users" group, which could block logins until data-sync completed.
> > > > * Fixed copying a process or workflow to another project: the copy now succeeds, and copied workflows appear in the target project.
> > > > * Fixed an invited Designer user added as an Organization owner not being assigned to a workspace.
> > > > * Improved merge-conflict handling for custom components and UI Flows, with clearer resource identification.
> > > > * Hide/disable conditions on UI templates, processes, and UI Flows are now applied at runtime for Designer users without workspace access.
> > > > * Fixed a 500 (duplicate key) error when activating a start timer event after a new build regenerated the process resource ID.
> > > > * Fixed a 500 error when opening a Usage Overview.
> > > > * Organization settings navigation and design improvements.
> > > > * **Runtime config params:** changes to runtime configuration parameters now propagate to the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
> > > > * **Microsoft Outlook connections** now support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.1 is fully compatible with 5.9.0. No breaking changes; standard deployment procedures apply.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.0 → 5.9.1 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.1 are tracked in the [5.9.1 deployment guidelines](./deployment-guidelines-v5.9.1).&#x20;
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2

Component versions, configuration, and deployment notes for FlowX.AI 5.9.2 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.2 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.1 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.1 → 5.9.2**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and converts your data. If you did not apply that workaround, no action is needed.

> [!WARNING]
>
> **Manually marked Liquibase changesets.** If any Liquibase changesets were manually marked as executed (MARK\_RAN) to work around failures during earlier 5.9.x upgrade attempts, those records must be removed after upgrading to 5.9.2 so the corrected changesets can run. Contact FlowX support for the exact list of affected changesets before removing anything. If you did not mark any changesets manually, no action is needed.

## Component versions

### Core components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.162.1 | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.7 |
| **admin** | 10.141.1 | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.7 |
| **designer** | 10.260.7 | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.10 |
| **cms-core** | 10.102.3 | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.3 |
| **scheduler-core** | 10.85.1 | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.3 |
| **events-gateway** | 10.90.1 | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.4 |
| **notification-plugin** | 10.100.2 | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.3 |
| **document-plugin** | 10.113.2 | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.3 |
| **task-management-plugin** | 10.102.1 | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.3 |
| **reporting-plugin**\* | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.7 |
| **data-search** | 10.83.1 | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.3 |
| **audit-core** | 10.93.1 | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.3 |
| **advancing-controller** | 10.89.1 | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.3 |
| **integration-designer** | 10.189.2 | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.4 |
| **application-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **runtime-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **data-sync** | 10.98.0 | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.4 |
| **authorization-system** | 10.112.1 | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.5 |
| **nosql-db-runner** | 10.92.1 | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.3 |
| **email-gateway** | 10.91.1 | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.88.1 | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.60.1 | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.23.1 | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.78.1 | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-native-sdk** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/core-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **react-saas** | 10.260.7 | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.6 | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.25 |
| **Android renderer** | 10.5.6 | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.31 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.0 | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.0 | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.0 | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.0 | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.0 | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.0 | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.25.0 | 10.17.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.0 | - | - | - | - |
| **ai-assistant** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.0 | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.2 | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.2 introduces no new Kafka topics over 5.9.1. For the topics added in 5.9.1, see the [5.9.1 deployment guidelines](../v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics); for the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.2 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

* **Kafka reconnect backoff:** platform services now default to a gentler broker-reconnect backoff — `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MS` `1000` / `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MAX_MS` `10000` (and the consumer equivalents) — and repetitive Kafka NetworkClient connection errors log at a quieter level, tunable via `LOGGING_LEVEL_KAFKA_NETWORK_CLIENT` (default `ERROR`). No action needed unless you previously tuned these.&#x20;
* **Resource-server security type:** the default for `idp.resourceServer.securityType` on the AI services changes to `jwt`. If you previously set the security type to `jwt` explicitly as a workaround, that override is no longer needed and can be removed.&#x20;

#### Data partitioning and archiving

5.9.2 adds configuration for the archiving lifecycle on the process-engine and Integration Designer. All new settings default to off, so no action is required on upgrade.&#x20;

* **Stuck-instance termination:** an optional sweep (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`, default `false`) terminates instances that would otherwise block archiving. Enable it, plus its cron and batch-size, if archiving stalls on unfinished data.
* **Legacy backfill:** one-shot backfills of `partition_id` (`FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED`) and `organization_id` (`FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED`), both default `false`, populate legacy rows when you first turn partitioning on. The organization-ID backfill is optional on self-hosted and can remain `false`.

> [!WARNING]
>
> **Partitions that still contain unfinished instances are not archived.** Starting with 5.9.2, the archiving job detaches a partition only when every process instance in it has reached a finished state (`FINISHED`, `FINISHED_WITH_ERROR`, `FAILED`, `EXPIRED`, `ABORTED`, `DISMISSED`, or `TERMINATED`). A single instance still in `CREATED`, `STARTED`, or `ON_HOLD` blocks the entire partition; it is retried on the next archiving run. The same rule applies to workflow instances on the Integration Designer, where a `STARTED` workflow instance blocks its partition. If partitions accumulate unarchived, terminate the blocking instances — set process expiry, or turn on the stuck-instance termination sweep above.

For the full property tables and defaults, see [Partitioning & archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) (process-engine) and [Integration Designer setup → Workflow partitioning](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration).

#### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them as part of this upgrade. The bundled Qdrant subchart is renamed the same way, so any explicit references to its service host must be updated too.

> [!WARNING]
>
> Core platform services resolve AI Platform components by these new names. Upgrade the AI Platform chart and the core platform services to 5.9.2 together — running a 5.9.1 AI Platform chart against 5.9.2 core services (or the reverse) breaks AI features.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# Deployment guidelines v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/deployment-guidelines-v4.6.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.0 FlowX.AI release, you cannot import old process definitions or resources into the new platform from older versions .

## Component versions

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.0.2** | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.3** | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.1.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.0** | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.0.3** | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.0.3** | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | **4.1.3** | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | **7.0.3** | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.0** | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.0** | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.1.12** | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.0** | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.1** | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.0.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.3** | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.9** | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.10** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.9** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.3** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.24** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.5.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.0 | Keycloak | 22.x |
| 4.6.0 | Kafka | 3.2.x |
| 4.6.0 | PostgreSQL | 16.2.x |
| 4.6.0 | MongoDB | 7.0.x |
| 4.6.0 | Redis | 7.2.x |
| 4.6.0 | Elasticsearch | 7.17.x |
| 4.6.0 | Oracle Database | 21C/ 21-XE |
| 4.6.0 | Angular (Web SDK) | 19.x |
| 4.6.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

## New microservices - setup guides

> [card] [Application-manager](/4.7.x/setup-guides/application-manager)

> [card] [Runtime-manager](/4.7.x/setup-guides/runtime-manager)

> [card] [Integration Designer](/4.7.x/setup-guides/integration-designer-setup)

> [card] [Data-sync job](/4.7.x/setup-guides/data-sync)

## New access rights and roles

> [card] [Integration Designer access rights](/4.7.x/setup-guides/access-management/configuring-access-rights-for-integration-designer)

> [card] [Application Manager access rights](/4.7.x/setup-guides/access-management/app-manager-access-rights)

## Updated access rights and roles

> [card] [Task Manager access rights](/4.7.x/setup-guides/plugins-access-rights/configuring-access-rights-for-task-management)
>
> Added new roles for **manage-views**.

## New service accounts

> [card] [Runtime manager service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#runtime-manager-service-account)

> [card] [Integration Designer service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#integration-designer-service-account)


# Deployment changes for v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x

This document outlines the configuration and infrastructure changes introduced from v4.1.x to v4.6.0 for deploying the FlowX.AI platform.

## CMS Setup

### MongoDB configuration

In version 4.6.0, the CMS setup includes a more comprehensive MongoDB configuration, especially for runtime data handling:

* **Runtime MongoDB Instance**: A dedicated MongoDB instance for managing runtime data.
  * **New Environment Variables**:
    * `RUNTIME_DB_USERNAME`: Username for runtime MongoDB access.
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: Connection URI for the runtime MongoDB instance.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`). Default is `mongodb`.
  * **Transaction Settings for Mongock Library**:
    * `MONGOCK_TRANSACTIONENABLED`: Controls MongoDB transaction support with Mongock, defaulting to `false` due to compatibility concerns with MongoDB 5.

### Private storage configuration

Private CMS to securely store uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints. This CMS will support AI services and workflows while maintaining strict access controls.

> [!NOTE]
>
> Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from project builds as they aren't needed at runtime.

* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL`: This environment variable specifies the URL of the S3 server used for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME`: This environment variable specifies the name of the S3 bucket dedicated to private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET`: This environment variable indicates whether the private S3 bucket should be created if it does not already exist. It can be set to true or false.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY`: This environment variable holds the access key used to authenticate to the S3 server for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY`: This environment variable holds the secret key used to authenticate to the S3 server for private file storage.

> [card] [CMS setup guide](/4.7.x/setup-guides/cms-setup)

***

## Admin setup

### MongoDB configuration

Version 4.6.0 introduces a new MongoDB setup in the Admin service for managing data model information:

* **New MongoDB Data Model Configuration**:
  * **Environment Variables**:
    * `SPRING_DATA_MONGODB_URI`: URI for connecting to the MongoDB data model instance.
    * `DB_USERNAME`: Set to `data-model` for data model access.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`).

***

## Engine setup

### MongoDB configuration

The Engine configuration now includes additional setup for a runtime MongoDB instance to manage runtime builds:

* **Runtime MongoDB for Engine**:
  * **New Environment Variables**:
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: URI for connecting to the runtime MongoDB.
    * `DB_USERNAME`: Set to `app-runtime` for runtime data access.


# Configuration and migration guide
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/process-configuration

This guide outlines changes in process and UI configuration from v4.1.x to 4.6.0 version.

## Projects

The **Projects** feature in FlowX AI v4.6.0 is a new structure that organizes all dependencies and resources required for a project into a single deployable view. This enhancement simplifies configuration, deployment, and maintenance by layering projects on top of processes, offering a centralized workspace that encapsulates everything needed for project execution.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)

Several key configuration changes impact how resources and dependencies are managed, deployed, and maintained. This guide provides a breakdown of the configuration changes, automatic migration processes, and manual steps required to ensure a smooth transition.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)

***

### Consolidated resource management

* **Change**: All resources that were previously managed individually within processes are now grouped within Projects. This includes content management elements, integrations, themes, task configurations, and permissions.
* **Impact**: Resources like **enumerations**, **substitution tags**, and **generic parameters** are now managed within Projects, allowing centralized configuration and version control.
* **Migration**: All process-related resources will be migrated automatically into a **default project**, ensuring continuity of functionality in the new framework. After migration, you should verify that all critical resources are correctly configured within this default project.

> [card] [What are resources?](/4.7.x/docs/projects/resources)

### Enhanced version control and dependency management

* **Impact**: Projects support **dependency management** through **Libraries** and enforce version-controlled resources. Setting up a project now requires careful dependency management and versioning to prevent unintended updates.
* **Benefit**: Allows for modular, reusable resources and stable deployments across projects, reducing resource duplication and enhancing project compatibility.

### Migration checklist

To ensure a smooth transition, complete the following steps:

1. **Verify Process Migration**: Confirm that all existing process definitions have been correctly migrated into the default project.
2. **Set Configuration Parameter Overrides**: Post-deployment, adjust environment-specific Configuration Parameters in the default project.
3. **Update Task Views**: Replace the global "All Tasks" feature with project-specific Views in each project.
4. **Transfer Processes and Dependencies Manually**: If moving a process from the default project to another project, manually transfer associated resources and re-check dependencies.

***

## Generic parameters migration

* **Overview**: In version 4.6.0, global generic parameters (from versions prior to 4.6.0) have been migrated to project-level as Configuration Parameters, consolidating parameter management within specific projects for improved organization and control.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/Screenshot%202024-11-06%20at%2019.04.49.png)

* **Migration**: All generic parameters will be automatically migrated to Configuration Parameters section under a default project.
* **Business Rules Unaffected**: There is no impact on existing business rules; they will continue to function as before without requiring updates.
* **Process Export Considerations**: If you export a process from one project to another, ensure that you also transfer the associated configuration parameters. This step is crucial to maintain process functionality and consistency across projects.
* **Important Note**: Only values of generic parameters associated with the specific environment, or where `env = null` (displayed as "all" in the interface in versions prior to 4.6.0), will be migrated. You must ensure that you have correctly set the values for generic parameters, paying attention to environment values (which are case-sensitive), and export these generic parameters before migration to avoid any potential data loss.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.39.29.png)

* **Post-Deployment Step**: After the first deployment to an upper environment, you will need to create configuration parameter overrides with the specific values required for that environment. This ensures that all environment-specific configurations are accurately maintained and applied across different deployment stages.

> [!TIP]
>
> To set configuration parameter overrides, navigate to **Your App -> Runtime -> Configuration Parameters Overrides**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.42.06.png)

***

## Source systems migration

* **Change**: Source systems have not been migrated automatically and need to be manually recreated.
* **New Location**: In v4.6.0, source systems have been moved under Integration Designer.
* Manual Migration Required:
  1. Navigate to Integration Designer.
  2. Recreate each source system manually with the same code as in the original configuration.
  3. Ensure the "Enable enumeration value mapping" checkbox is enabled.
* **Impact**: Failure to manually migrate source systems may result in broken integrations and missing data mappings.

**v4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2009.53.30.png)

**\< v.4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2010.09.12.png)

## Task management

* "All Tasks" as a View: The global "All Tasks" feature is no longer standalone and will now function as a View in a project.

**v4.6.0:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

**v4.1.x:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/all_tasks.png)

***

## General

Before starting the migration, complete the following steps:

1. **Merge All Feature Branches**: Ensure all feature branches for processes are merged into the latest version on the main branch.
2. **Remove Unnecessary Resources**: Delete any test processes or resources that are no longer needed.
3. **Export Generic Parameters**: Export generic parameters as a backup to ensure they migrate accurately to project-specific Configuration Parameters.

### Migration steps

During migration, resources will be transferred into a single **default project** with one committed version.

* **Process Definitions**: Only the last committed process version on the main branch will migrate. If no committed version exists, the latest WIP version will be used.
* **Enumerations, Substitution Tags, and Task Manager**: These resources will be migrated to the default project.
* **Generic Parameters**: Migrated as **Configuration Parameters** within the default project, covering only values where `env = null` or that match the platform’s environment setting.
* **Languages**: Language settings (available languages and default) will be moved to project settings. Languages remain globally available.

### Resources excluded from migration

Some resources will remain globally available or are deprecated:

* **Themes**
* **Fonts**
* **Global Media Library** (for media used in themes)
* **Out of Office (Task Manager)**
* **Integration Management** (will not be available in v4.6.0)

***

## Datepicker Migration

In version 4.6.0, significant updates have been introduced to the **Datepicker** component to ensure compatibility with ISO 8601 date formats and enhanced handling of date attributes within the **Data Model**. This migration affects both newly created and existing processes.

### Key changes

1. **Introduction of Date Types**:
   * **Standard Date**: Stores and displays date values in ISO 8601 format, respecting the project's locale and timezone settings.
   * **Legacy Date**: Retains previous formatting to ensure compatibility with existing business rules and processes.

2. **Properties Updates**:
   * The **Datepicker** now supports dependent properties such as `minDate`, `maxDate`, and `defaultValue`. These properties:
     * Follow the formatting rules of the selected date type (Standard or Legacy).
     * Ensure that dynamic date values pulled from the **Data Model** are displayed correctly.

3. **Backward Compatibility**:
   * **Existing Processes**: All migrated processes with legacy Datepicker components will default to `Legacy Date` type. This preserves the original formatting and ensures no disruption in business rules or workflows.
   * **New Processes**: Newly created processes will default to `Standard Date` type, saving values in ISO 8601 format.

***

### Migration process

1. **Legacy Datepickers**:

   * Automatically flagged during migration.
   * Continue to work with existing business rules.
   * Require manual review for future updates to transition to the **Standard Date** format.

2. **Business Rules Updates**:
   * Legacy Datepickers may require manual adjustments if associated business rules reference hardcoded date formats.
   * Ensure that any dynamic dates used in business rules are compatible with the ISO 8601 standard.

3. **Standard Datepickers**:
   * All new Datepicker components save date values directly in ISO 8601 format.
   * Fully compatible with updated **Data Model** attributes, allowing seamless integration with external systems, adaptors, and reporting plugins.

### Considerations

* **Default Values**:
  * For **Standard Datepickers**, the `defaultValue` must be in ISO 8601 format.
  * Dynamic defaults can also be set using **Data Model** attributes or process data.
* **Data Model Integration**:
  * All external and internal date attributes, including those used by adaptors or business rules, must be explicitly defined in the **Data Model**.
* **UI Designer Overrides**:
  * Overrides can be applied to display dates differently for specific UI elements, ensuring flexibility for localized formatting.

### Recommendations for transition

* **Existing Processes**:
  * Leave Datepicker components in `Legacy` mode unless business rules and workflows are updated to support ISO 8601.
* **New Processes**:
  * Use `Standard Date` to ensure future compatibility and alignment with ISO 8601 formatting.
* **Documentation**:
  * Review and update all timer expressions, adaptors, and external data feeds to use ISO 8601 format for consistency.

***

## Updates to expression evaluation

**What Changed:**

* A fix was implemented in the web expression evaluator regarding how string values are handled during process value replacement.
* Previously, when evaluating dynamic and computed expressions, string variables required manual insertion of double quotes (`""`) because the system did not automatically add them.
* With the recent fix, the system now **automatically adds the necessary quotes** for string replacements.

**Impact:**

* **Existing Expressions:** If your current dynamic or computed expressions include manually added quotes around string values, these might now result in redundant quotes or incorrect string formatting.
* **Behavioral Shift:** The automatic quote addition alters how string values are processed, which might affect outputs if the expressions were structured with the expectation of manual quotes.

**Action Required:**

1. **Review Your Expressions:** Check any dynamic and computed expressions in your processes that currently include manual double quotes around string values.
2. **Modify as Needed:** Remove unnecessary double quotes where the system now handles them automatically to prevent duplicate quoting or formatting issues.

***

## Export/import enumerations (CSV)

In the transition from version 4.1.x to 4.6.0, the following columns have been removed from the enum CSV export format:

* description.application
* description.draft
* contentValue.childContentDescription.application
* contentValue.childContentDescription.draft
* contentValue.childContentDescription.type

Existing CSV export/import processes should be updated to remove references to these columns to ensure compatibility with the 4.6.0 release.

***

## Post-migration recommendations

For complex projects with multiple use cases, **do not use the default project for ongoing development or production builds**. Instead:

1. **Create Branches within the Default Project**: Organize and streamline resources by creating branches. This enables a lightweight build focused on production.
2. **Split the Default Project into Smaller Projects**: Use the import/export feature to separate the default project into individual projects by use case.
   * **Note**: When importing processes into a new project, resource references may need to be manually reconfigured.

***


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/renderers

This guide assists in migrating from FlowX v4.1.x to v4.6.0.

## Android SDK migration guide

### Initialization config changes

A new configuration parameter named `locale` was added to improve formatting the dates, numbers and currencies.

When the SDK initialization happens through the `FlowxSdkApi.getInstance().init(...)` method, the argument must be included inside the `config: SdkConfig` parameter value:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().init(
    ...
    config = SdkConfig(
        baseUrl = "URL to FlowX backend",
        imageBaseUrl = "URL to FlowX CMS Media Library",
        enginePath = "some_path",
        language = "en",
        locale = Locale.getDefault(), // e.g. Locale("en", "US"), Locale("fr", "CA")
        validators = mapOf("exact_25_in_length" to { it.length == 25 }),
        enableLog = false,
    ),
    ...
)
```

### Changes when starting a Flowx process

Two new parameters were added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The id of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun startProcess(
    projectId: String,
    processName: String,
    params: JSONObject = JSONObject(),
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes when resuming a Flowx process

One new parameter was added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the continued process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes regarding the implementation of Custom Components

The support for classical **[Android View](https://developer.android.com/reference/android/view/View)** system has been dropped.\

A Custom Component can now be implemented only by using the **[Compose](https://developer.android.com/compose)** UI system.

This means that the `CustomViewComponent` is now ignored in the internals of the SDK and has been marked as `@Deprecated` and will be completely removed in the next release.

> [!NOTE]
>
> There is no immediate need to update any of the existing components.

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```kotlin theme={"dark"}
fun changeLocaleSettings(locale: Locale, language: String)
```

### Library dependencies updates

* **[Kotlin](https://kotlinlang.org/)**: 1.9.22 **↗** **1.9.24**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping)**: 2024.02.00 **↗** **2024.06.00**
* **[Compose Compiler](https://developer.android.com/jetpack/androidx/releases/compose-compiler)**: 1.5.9 **↗** **1.5.14**
* **[Gson](https://github.com/google/gson)**: 2.10.1 **↗** **2.11.0**

***

## iOS SDK migration guide

### Initialization config changes

A new configuration parameter, named `locale` was added to improve formatting the dates, numbers and currencies.

The locale needs to be set on the `FXConfig.sharedInstance.configure` method

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    config.locale = "en-US"
    ...
}
```

### Changes when starting a process

Two new parameters were added on the 3 available start process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The uuid string of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func startProcess(projectId: String, 
                  name: String, 
                  params: [String : Any]?, 
                  isModal: Bool = false, 
                  showLoader: Bool = false, 
                  completion: ((UIViewController?) -> Void)?, 
                  onProcessEnded: (() -> Void)? = nil)
```

### Changes when resuming a Flowx process

One new parameter was added on the 3 available continue process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func continueExistingProcess(uuid: String, 
                             name: String, 
                             isModal: Bool = false, 
                             completion: ((UIViewController?) -> Void)? = nil, 
                             onProcessEnded: (() -> Void)? = nil)
```

### Updated FXDataSource protocol

A new method has been added to the `FXDataSource` protocol. Update conformance to protocol by adding the implementation of the new func.

```swift theme={"dark"}
func newProcessStarted(processInstanceUuid: String) {
    
}
```

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```swift theme={"dark"}
func changeLocaleSettings(locale: String?, language: String?)
```

***

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated and will use the latest versions Angular (version 19), thus all container apps that want to use the new SDKs should first update the Angular version of the container apps.

In the following we cover the migration guide for a container app from Angular v17 to v19 and the new SDKs.

**1. Remove old packages and their explicit dependencies (required dependency packages for new sdks are bundled in the libraries so we don't need)**

* remove `material-moment-adapter` unless it is used in custom components (usually together with material datepicker) and also the `moment` package (unless used elsewhere in the project )

```bash theme={"dark"}
npm uninstall @angular/material-moment-adapter
npm uninstall moment
```

* remove old FlowX SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/ui-sdk @flowx/ui-theme @flowx/ui-toolkit 
```

* in `angular.json` remove references to old stylesheets:

```bash theme={"dark"}
"./node_modules/@flowx/ui-sdk/src/assets/scss/style.scss"
"./node_modules/paperflow-web-components/src/assets/scss"
"./node_modules/@flowx/ui-sdk/src/assets/scss"
```

* remove old FlowX SDKs explicit dependencies. Please check before removing that packages are not used in the container app or custom components.

```bash theme={"dark"}
npm uninstall date-fns event-source-polyfill inputmask ng2-pdfjs-viewer vanillajs-datepicker @ngneat/input-mask deepmerge-ts marked-mangle
```

* remove deprecated `Angular Flex` library (the new sdks don't use it anymore and the package has been deprecated by the Angular team) unless it is not used in container app or custom components

```bash theme={"dark"}
npm uninstall @angular/flex-layout
```

**2. Update container app to Angular 18**

* Make sure to have the Angular CLI installed at version 18 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@18
```

* Run the Angular update for version 18

```bash theme={"dark"}
ng update @angular/core@18 @angular/cli@18
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@18
```

or, if the container app uses Angular Material, run:

```bash theme={"dark"}
ng update @angular/material@18
```

* Optionally, if your project uses other angular packages (ex. `NgRx`) please run migrations to v18 for each of them before proceeding. You can find details on the libraries documentation pages.

* Angular has changed the default build path in the `dist` folder, it now uses a `browser` folder for the build output. To place the output of the build command directly in the `dist/[APP_NAME]` folder, add the following change in `angular.json`:

```json theme={"dark"}
{
  ...
  "architect": {
    ...
    "build": {
      ...
      "options": {
        ...
        "outputPath": {
          "base": "dist/flowx-demo-app",
          "browser": "" <-- add this line
        },
      }
    }
  }
}

```

**3. Update container app to Angular 19**

* Make sure to have the Angular CLI installed at version 19 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Run the Angular update for version 19

```bash theme={"dark"}
ng update @angular/core@19 @angular/cli@19
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@19
```

or, if the container app uses Angular material, run:

```bash theme={"dark"}
ng update @angular/material@19
```

* Optionally, if your project uses other Angular packages (ex. `NgRx`) please run migrations to v19 for each of them before proceeding. You can find details on the libraries documentation pages.

* Also, it is recommended that you update the `target` and `module` settings in the `tsconfig.json` file to the new version, although be advised that this might require additional changes in the codebase due to new compilation errors that might arise.

```json theme={"dark"}
{
  ...
  "compilerOptions": {
      ...
      "target": "ES2022",
      "module": "ES2022"
  }
}
```

**4. Install the new FlowX SDK packages**

**Adding overrides for libraries that have a dependency on Angular version \< 19**

For some libraries, the required angular version might not be up to date or compatible with the new Angular version. In this case, you can add an override in the `package.json` file to force the library to use the new Angular version.

* For example, the `ng2-pdfjs-viewer` library has a dependency on Angular version 18 and will not work with the installed Angular version 19. To force the library to use the new Angular version, add the following override in the `package.json` file:

```json theme={"dark"}
{
  ...
  "overrides": {
    "ng2-pdfjs-viewer": {
      "@angular/common": "^19.0.0",
      "@angular/core": "^19.0.0",
      "ng-packagr": "^19.0.0"
    }
  }
}
```

**Install new packages**:

> [!WARNING]
>
> **ACTION REQUIRED**: Update to the latest version 4.6 to ensure optimal performance and compatibility.

```bash theme={"dark"}
npm install @flowx/core-sdk@5.63.0 @flowx/core-theme@5.63.0 @flowx/angular-sdk@5.63.0 @flowx/angular-theme@5.63.0 @flowx/angular-ui-toolkit@5.62.1 
```

* Install a type dependency for the SSE library:

```bash theme={"dark"}
npm install --save-dev @types/event-source-polyfill
```

* run through all the migration steps in the [New SDK Api changes](#new-sdk-api-changes) section below.

> [!NOTE]
>
> Each migration requires a 'clean' repository state. Make sure to commit all changes before starting the next migration step.

> [!TIP]
>
> After each Angular update it is recommended you restart your editor or TS Server, to use the new TS version since some import errors might appear.

### New SDK API changes

#### Renderer SDK component usage

In the Angular SDK, the `<flx-process-renderer>` component has two new parameters have been introduced: `projectInfo` and `locale`. These additions help support localization and project-specific configurations.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectInfo` | Object containing an `projectId` key, which identifies the project of the process to be started | `{projectId: string}` | Mandatory |
| `locale` | Provides region-specific settings for localization. | `string` | Mandatory |

Add the definitions for these properties in the class file of the component that uses the process renderer component:

```typescript theme={"dark"}
projectInfo = { projectId: 'your-project-id' },
locale = 'en-US',
```

Use these parameters in the template as inputs for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  ...
  [projectInfo]="projectInfo"
  [locale]="locale"
/>
```

#### API changes

Process Renderer:

| Category | Old Approach | New Approach |
| - | - | - |
| **Process Renderer** | `FlxProcessModule.forRoot({...})` | `FlxProcessModule.withConfig({...})` |

#### Import path updates

| Category | Old Approach | New Approach |
| - | - | - |
| **Import Paths** | `@flowx/ui-sdk` | `@flowx/angular-sdk` (or, in some cases `@flowx/core-sdk`) |
| | `@flowx/ui-theme` | `@flowx/angular-theme` |
| | `@flowx/ui-toolkit` | `@flowx/angular-ui-toolkit` |
| **Process Module** | `import {FlxProcessModule} from '@flowx/ui-sdk';` | `import {FlxProcessModule} from @flowx/angular-sdk` |
| **Localization Module** | `import {FlxLocalizationModule} from '@flowx/ui-sdk';`  Include in module imports | `import {FlxLocalizePipe} from '@flowx/angular-sdk';` Remove from module imports |
| **Task Management** | `import {FlxTaskManagementModule} from '@flowx/ui-sdk';` | `import {FlxTasksManagementComponent} from '@flowx/angular-sdk';` |
| **Client Store Interface** | `import {ClientStoreInterface} from '@flowx/ui-sdk';` | `import {ClientStoreInterface} from '@flowx/core-sdk';` |

> [!NOTE]
>
> You can also remove the `FlxLocalizationModule` from any `imports` arrays in modules, and import the `FlxLocalizePipe` instead

### Icon module update

The `withExtraIconSet` method has been replaced with `provideExtraIconSet`, which should now be used in the providers array.

```typescript theme={"dark"}
@NgModule({
  imports: [
    IconModule,  // Import the IconModule
  ],
  providers: [
    // Use provideExtraIconSet to add your custom icon set
    provideExtraIconSet({
      customIcon1: 'path/to/custom-icon1.svg',
      customIcon2: 'path/to/custom-icon2.svg',
      // Add more icons as needed
    })
  ]
})
export class AppModule {}
```

### Custom Interceptors

The new FlowX SDKs do not depend on Angular's `HttpClient` to make API calls, so existing interceptors must be adapted to a new format, for Request Interceptors (eg. custom headers) and Response Interceptors (eg. error handling)

For an overview of implementation details, please refer to the respective sections of the renderer documentation for the new API changes.

> [card] [Custom Interceptors](/4.7.x/sdks/angular-renderer#custom-interceptors)


# FlowX.AI 4.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025

Welcome, FlowX fam! The 4.6.0 update is here, and it’s packed with features designed to save you time, boost efficiency, and maybe even make you chuckle. Let’s dive into the details, feature by glorious feature. 🎉

## **What's new?** 🆕

### Projects: Order out of chaos

The new Project concept introduces a streamlined approach to managing and deploying complex projects within FlowX. By grouping all related resources—such as processes, enumerations, integrations, and assets—into a single, organized workspace, projects provide a cohesive view for efficient development and deployment.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

💼 **Key Benefits**:

* **Unified Workspace**: Group related processes, integrations, assets, and configurations into one tidy space.
* **Version Control**: Manage multiple builds and versions effortlessly. Rollbacks? No sweat.
* **Resource Sharing**: Reuse processes and configurations across projects like a boss.

> [!TIP]
>
> **Why you’ll love it**: It’s like going from a messy desk to an organized digital office.

🎥 **Quick Demo**: (Who needs text when you have visuals?)

<video />

> [card] [Projects](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

#### 🛠 Config vs Build Mode

**Config Mode**: Tinker, tweak, and perfect.

* Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's the workspace where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

**Build Mode**: Lock it, load it, deploy it.

* Build mode is the stage where the configurations you've set up are packaged into a deployable form. This is the runtime-ready version of your project, containing everything needed for it to function in a production environment. A build includes a snapshot of the project’s state at a given point, ensuring stability and predictability when deployed.

<video />

> [card] [Configuration](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

> [card] [Runtime](/4.7.x/docs/projects/runtime/builds)
>
> For more details, check out this section

***

### Integration Designer: Connect like a pro

It’s like a dating app for your systems: drag, drop, connect, and let the workflows flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)

API integration just got easier! Integration Designer simplifies connecting FlowX with external systems using REST APIs.

✨ **The magic of it**:

* **Drag-and-Drop Interface**: Map data, define workflows, and configure endpoints like a breeze.
* **Flexible Authorization**: Use Service Tokens, Bearer tokens, or go authentication-free.
* **Error Management**: Built-in tools ensure your integrations don’t ghost you.

> [!TIP]
>
> **Fun Fact**: Integration Designer doesn’t just test APIs (we love you, [Postman](https://www.postman.com/)❤️). It automates workflows, saving you tons of time.

> [card] [Integration Designer](/4.7.x/docs/platform-deep-dive/integrations/integration-designer)
>
> For more details, check out this section

***

### Merge Conflicts 2.0: Merge without the drama

Merging branches? We've overhauled the process to make it faster, smarter, and far less painful.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)

🧩 **What’s New**:

* **Advanced Conflict Detection**: Pinpoint issues by resource type (Processes, Enumerations, Media, etc.).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)

* **Resource-Level Resolution**: Resolve conflicts directly in the UI with:
  * JSON comparisons (color-coded for clarity!).
  * Navigation tools to jump between differences.
  * Progress tracking for reviewed items.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

> [!TIP]
>
> **Pro Tip**: Use the “Merge Anyway” option if you need to override unresolved conflicts (but use it wisely!).

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)

> [card] [Merge conflicts](/4.7.x/docs/projects/managing-applications/versioning#managing-conflicts)

***

### AI Agents: Smart, adaptable, always ready to help

FlowX AI Agents bring automation to your fingertips, powered by a flexible, LLM-agnostic core.

🤖 **Why It’s Cool**:

* Works with both open-source and private language models.
* Secure, on-premise deployments available.
* Automates business processes and interactions.

🎥 Check out a quick demo:

<video />

Stay tuned for more.

***

### Localization and Internationalization

FlowX is now more global-friendly with enhanced localization features.

> [card] Flexible Date, Time, Number, and Unit Formatting
>
> Enhanced formatting options for dates, times, numbers, and currencies with support for various international standards including short, medium, long, full, and custom formats.

> [card] Currency Customization
>
> Support for currency formatting with options to display values using ISO codes or symbols, adapting to user-selected locales and regional preferences.

> [card] Locale-Based Configurations
>
> Comprehensive settings for pluralization, capitalization, alignment, and sorting that adapt to regional requirements, helping cater to a diverse global user base.

> [card] Enhanced UI Component Formatting
>
> New options in the UI Designer to override general settings for text, messages, links, and form elements based on locale and region.

> [card] Document Localization
>
> Static and dynamically generated legal documents can now be customized based on regional and locale settings, improving compliance and communication with local audiences.

> [card] [Localization and internationalization](/4.7.x/docs/building-blocks/ui-designer/localization-and-i18n)
>
> For more details, check out this section

***

### Data Model 2.0: Data handling, but make it fashion

In this release, we've introduced Data Model 2.0, a major upgrade designed to simplify and enhance data handling. Key improvements include the introduction of reusable objects, a visual representation of complex data structures, and dynamic data binding, all aimed at creating a more reliable and intuitive experience. The new model ensures references are automatically updated when changes are made, streamlining data management across the platform.

**Highlights**:

* **New Root Element**: Provides a structural basis without impacting business logic, ensuring a clear and organized data structure.
* **Enhanced Data Binding**: Expanded to more areas, with dynamic updates based on changes in the data model.
* **Localization**: Added handling mechanism for locale-specific formatting, ensuring accurate data representation.

<video />

> [card] [Data model](/4.7.x/docs/building-blocks/process/data-model)
>
> For more details, check out this section

***

### Task management 2.0

We've enhanced Task Management capabilities, making it easier to create, track, and manage tasks efficiently. The updated Task Management features include customizable views and advanced filtering and sorting options for task data. Additionally, users can now implement both low-code and full-code solutions for a tailored Task Management experience, ensuring maximum flexibility for different business needs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

> [card] [Task Management](/4.7.x/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> For more details, check out this section

***

### UI Designer

#### Grid layout

We are excited to introduce the Grid Layout feature in this release, enhancing the flexibility and usability of the UI Designer for creating structured and responsive layouts. With the new Grid Layout, users can organize form elements, tables, and other components using a multi-column and row system, allowing for more complex, bidirectional designs compared to the previous flex-based layout.

<video />

> [accordion] This might happen after using it for the first time:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid-layout-first-time.jpg)

#### Table

The Table component is a simple and flexible way to display data in web applications. It lets you customize columns, add pagination, sort and filter data, and apply your own styling. You can resize columns, scroll through data, and even add actions like editing or deleting rows directly in the table. It’s easy to set up, with default columns and rows generated automatically based on your data.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)

> [card] [Table](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/table)
>
> For more details, check out this section

#### FlowX.AI UI Designer new navigator

We are thrilled to introduce the new and improved **UI Designer Navigator**, a major update designed to streamline your UI design process.

> [card] Enhanced UI Layer Panel Design and Functionality
>
> The UI layer panel has been redesigned for a more intuitive experience, making it easier to manage and navigate through your design elements.

> [card] Improved Drag and Drop Experience
>
> Dragging and dropping components in the preview is now smoother and more precise, allowing for faster and easier creation of UIs.

> [card] Flexible Root Component Management
>
> You can now change the root component from a form group to a container or vice versa, offering greater flexibility when copying nodes or resolving configuration problems.

> [card] Clearer Component Hierarchy
>
> It is now simpler to identify where you are placing a component within the hierarchy, thanks to the enhanced drag/reorder functionality in the right panel.

<video />

#### Conditional formatting for UI elements

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)

> [!NOTE]
>
> Conditional styling is available for **text**, **link**, and **container** UI elements based on specific conditions.

#### Hide expressions enhancements

Expanded hide expressions functionality to include:

* Cards
* Collection prototypes and children
* Table cell children (e.g., texts, images, buttons, links)

#### UI actions

* Added a new UI action **Start new project instance**
* Removed the **Start Process Inherit** UI action type.

#### UI action form updates

* Introduced **Functional** and **UX sections** for all action types, with a checkbox for **Add Analytics Name** in the UX section.
* Simplified custom and exclude key management.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2015.20.01.png)

***

### Start new project instance action

We’ve introduced the Start New Project Instance node action, enabling users to initiate a completely new process from within an ongoing one. This functionality is perfect for scenarios where isolated use cases are managed across different projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)

> [card] [Start new project instance action](/4.7.x/docs/building-blocks/actions/start-new-project-instance)

***

### Custom components validation

You are able to validate and retrieve data from a generated screen, including data from a custom form section. Additionally, you’ll have the ability to trigger and manage data directly within that section. This will be a major benefit for clients who have chosen to create custom components for the entire screen (for example, a form that isn’t supported natively by the platform).

> [card] [Validating elements](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/root-components/card#validating-elements)

***

### Autocomputed data to send

In previous platform versions, when creating your UI screens and working with data, you had to ensure that all the data stored in your process keys was saved in the process instance. This required adding an extra parameter called "Data to send" to the "Save Data" node action.

**Older versions** vs **v4.6.0**:

![older versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.x-aut.png)

![v.4.6](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.2-aut.png)

Now, with the autocompute feature, this step is no longer necessary, as the data is automatically saved and sent on your process instance.

> [!TIP]
>
> You no longer need to add "Save Data" node actions, but make sure to include "Forms to Validate" on the UI Actions. This helps ensure that data is submitted correctly and automatically activates any added validators where they exist.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/forms_to_validate.png)

However, you still have the option to customize which keys are included or excluded as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/include_exclude_keys.png)

***

### **Scripting UX Improvements**: *Write code like a wizard*

* **Autocomplete**: Get tailored suggestions based on your data model.
* **New Editors**: JSON and hide/disable expressions editors now include examples, syntax help, and better visual feedback.

<video />

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide%3Adisable%20editor.png)

***

### React & Angular SDKs

Dev friends, we heard you. FlowX now integrates smoothly into your React and Angular apps. It’s like peanut butter and jelly, but make it code.

#### React SDK

With the 4.6.0 release, we're excited to announce the launch of the FlowX React SDK! This new SDK empowers developers to seamlessly integrate FlowX.AI capabilities into React applications, making it easier than ever to build highly interactive, responsive, and dynamic user experiences.

To get started, simply install the FlowX React SDK via npm and check our documentation for examples and best practices!

> [card] [React SDK](/4.7.x/sdks/react-renderer)

#### New Angular SDK

We're excited to announce new releases for FlowX packages to support web applications:

* `@flowx/core-sdk`
* `@flowx/angular-sdk`
* `@flowx/angular-theme`
* `@flowx/angular-ui-toolkit`
* `@flowx/core-theme`

> [!WARNING]
>
> We recommend upgrading to the **latest** versions of all @flowx packages to take full advantage of these new features and improvements. Check the deployment guidelines for version details.

> [card] [Angular SDK migration guide](migrating-from-v4.1.x-to-v4.6.0/renderers#angular-sdk-migration-guide)

***

### Analytics integration for Container Apps

Container apps now support tracking "Screen Displayed" and "Action Executed" events, configurable in the UI Designer to improve insights into user interactions.

**UI Designer updates**

* **Analytics Screen Name:** Configurable under Root UI components (Cards and Containers) to enable tracking in analytics platforms like Google Analytics.

> [!TIP]
>
> "Screen Displayed" events support user task-based reporting, such as when a user task screen is shown.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.01.58.png)

> [!NOTE]
>
> The configured values are stored in `flowxProps.analytics`, making them accessible for integration with analytics tools.

* **Action Analytics:** Tracks user actions (e.g., button clicks) with tags set directly in the UI Action Form.

> [!NOTE]
>
> Added analytics configuration in the **UX Section** for all UI action types.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.20.53.png)

> [!NOTE]
>
> Values are saved in `params.analytics` via the PATCH `/actions` request.

**Renderers updates**

Renderers now expose a public API for triggering analytics events:

* **Screen Events:** Triggered on user task display, using `flowxProps.analytics`.
* **Action Events:** Triggered on action execution, using `params.analytics`.

Dynamic values such as process store keys and replace tags are supported for more contextual tracking.

***

### Plugin updates

**Notifications** and **Documents** plugins have been integrated as **project resources**.

***

### Scheduled Processes: Timer management reimagined

We've completely redesigned how you manage timer-triggered processes. Before 4.6.0, timer activation was managed through a quick actions menu in process definition headers; now it's handled via dedicated UI section in the Runtime tab under Scheduled Processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

🕒 Key Improvements:

* **Centralized Timer Management:** All process timers are now visible and manageable in one dedicated location
* **Persistent Settings:** Timer configurations persist across build exports/imports
* **Environment Control:** Activate or deactivate timers without redeploying your application

For more details, check out this section

> [card] [Scheduled Processes](/4.7.x/docs/projects/runtime/scheduled-processes)

## Bug fixes 🐞

### Rendering

* **Default Value Initialization for UI Elements**: Resolved an issue where certain UI elements were initialized with incorrect default values.

* **Improved Security for Hidden Fields**: Fixed a vulnerability where hidden fields could be accessed through browser developer tools.

* **Form Validation Reset on UI Dismissal**: Addressed an issue where form validation errors persisted after the UI was closed.

* **Keybinding Issues on Windows**: Fixed a bug where pressing specific keys triggered unintended operations in the designer.

* **Input Field Validation for Number Type**: Corrected the validation logic for number input fields to ensure consistent behavior.

* **Improved Datepicker Popup Positioning**: Resolved an issue where the datepicker popup overlapped the associated input field.

* **Manual Date Entry in Datepicker**: Fixed an issue where manually entering a date after selecting one from the datepicker caused errors.

* **Enhanced Update Mechanism for Custom Components**: Improved the reliability of updates for custom components to reflect changes consistently.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **New substitution tags with the same name on different branches aren’t flagged**: Merging branches that include new substitution tags with identical names on different branches does not trigger a conflict. Instead, both tags are retained, resulting in duplicate substitution tags with the same name but different values. This issue bypasses expected conflict detection and can lead to inconsistencies in substitution tag usage.
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] Notification and document templates
>
> * Branches with notification and document templates fail to merge into the main branch

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Changes 🔧

* **Web Renderer Caching:** Improved resource caching with browser mechanisms keyed to build IDs.
* **Process Designer:** Enhanced drag-and-drop functionality for node placement.

***

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.0](./deployment-guidelines-v4.6.0)

Migrating from v4.1.x:

> [card] [Migrating from v4.1.x to v4.6.0](./migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x)

> [card] [Changes in process configuration](./migrating-from-v4.1.x-to-v4.6.0/process-configuration)

> [card] [Renderer SDKs](./migrating-from-v4.1.x-to-v4.6.0/renderers)


# Migrating from previous versions to v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/migrating-from-v4.1.x-to-v4.6.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.0 version, make sure to first review the migration guide for v4.6.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

If you're moving from v4.1.x to v4.6.1, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# Tutorial: Build a credit card application
Source: https://docs.flowx.ai/5.9/docs/getting-started/building-your-first-proc

Learn FlowX.AI by building and running a credit card request process with a form, a credit check, branching logic, and a confirmation screen.

Tested · October 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** All three card-type paths ran end to end, from the form to the confirmation screen, with each instance finishing in the expected branch.

In this tutorial, you'll build a credit card application process from scratch and run it end to end. By the end, you'll know how to:

* Design a BPMN process with user tasks, service tasks, and gateways
* Build a form and wire its button to the process
* Set and read process data with business rules
* Branch on a value with an Exclusive Gateway
* Start a process instance and inspect it

> [!NOTE]
>
> **Time required:** about 15 minutes
>
> **Prerequisites:**
>
> * Access to FlowX Designer
> * A workspace and project set up ([create one here](/5.9/docs/projects/workspaces))

> [!TIP]
>
> Everything in the guided steps runs inside FlowX, with no external system required. The credit score is simulated by a business rule. The [Extend the process](#extend-the-process) section at the end shows where real integrations plug in.

***

## What you'll build

A customer requests a new credit card through a bank app. The process:

1. Collects personal information
2. Computes a credit score
3. Assigns a card type based on the score
4. Shows the result and asks the customer to confirm

```mermaid theme={"dark"}
flowchart LR
  S((Start)) --> A[Fill Personal Data]
  A --> B[Check Credit Score]
  B --> G{Card type?}
  G -->|700 or more| P[Premium]
  G -->|500 to 699| T[Standard]
  G -->|below 500| Q[Basic]
  P --> M{" "}
  T --> M
  Q --> M
  M --> R[Review and Confirm]
  R --> E((End))
```

This is how the finished process looks on the Designer canvas:

![The finished credit-card-request process on the canvas: Start, Fill Personal Data, Check Credit Score, a Card type? gateway branching to Basic, Standard, and Premium, a Merge gateway, Review and Confirm, and End](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-finished-process.png)

***

## Step 1: Create the process

**1. Open your project**

In **FlowX Designer**, open your workspace, then your project, then its **Processes** section.

**2. Create a new process**

Add a new process, name it `credit-card-request`, and click **Create process**. The Designer opens the empty canvas.

**3. Add a Start Event**

Drag a **Start Event** from the node palette on the left onto the canvas. This is where the process begins when a customer opens the credit card application.

> [card] [Creating process definitions](/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-new-process-definition)

> [card] [Learn more about processes](/5.9/docs/building-blocks/process/process)

***

## Step 2: Collect user data (User Task)

The first step is collecting the customer's personal information.

**1. Add a User Task**

Drag a **User Task** node after the Start Event, connect the two, and name it `Fill Personal Data`.

**2. Assign it to a navigation area**

Every user task must belong to a navigation area. Without one, the Designer marks the node with a warning and its screen does not render at runtime.

In the left panel, open the **Navigation** tab. Click **Add New Area** (the **+** button), choose **Page**, and name it `Application`. Then drag `Fill Personal Data` from **User Tasks (not allocated)** into the page. The second user task gets its own page in Step 5.

![Navigation tab in the left panel with two pages, Application holding Fill Personal Data and Confirmation holding Review and Confirm, and an empty User Tasks (not allocated) list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-navigation-areas.png)

**3. Design the form**

Select the user task and open the **UI Designer**. Add a **Form** component, then add these fields inside it:

* Full name: an **Input** of type **Text**
* Email: an **Input** of type **Email**, which validates the address format for you
* Date of birth: a **Datepicker**
* Annual income: an **Input** of type **Number**

![UI Designer showing the Fill Personal Data form with Full name, Email, Date of birth, and Annual income fields and a Continue button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-form-ui-designer.png)

**4. Configure the data model**

Set the **Process data key** of each field. This is where the value lands in the process data:

* `application.fullName`
* `application.email`
* `application.dateOfBirth`
* `application.annualIncome`

![The process data model with the application object and its fullName, email, dateOfBirth, annualIncome, creditScore, and cardType attributes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-data-model.png)

**5. Add a Continue button and wire it**

The form cannot advance the process on its own: it needs a button bound to an action. A user task already comes with a **Save Data** action named `saveData`, set to **Manual** so it waits for the user, so you do not have to create one.

In the **UI Designer**, drag a **Button** onto the screen and label it `Continue`. In its **Event Handlers** section, click **+**, choose the **On Click** trigger, set **Action Type** to **Node Action**, and select `saveData`.

Check **Add forms to submit** and select your form. This validates the visible fields and sends their values with the action.

![Continue button selected in the UI Designer, with an On Click event handler set to Node Action saveData and the personal data form added to submit](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-continue-button-event-handler.png)

> [!NOTE]
>
> Buttons never advance a process on their own. Each button corresponds to a **manual node action** on the same node, reached through an **On Click** event handler. If you are coming from 5.1.x, the Event Handlers section is what replaced the separate **UI actions** tab. See the [migration mapping](/5.9/docs/building-blocks/ui-designer/event-handlers#migrating-from-ui-events-and-ui-actions) for the old-to-new action names.

> [card] [Learn more about User Tasks](/5.9/docs/building-blocks/node/user-task-node)

> [card] [Event Handlers](/5.9/docs/building-blocks/ui-designer/event-handlers)

> [card] [Navigation areas](/5.9/docs/building-blocks/process/navigation-areas)

> [card] [Input fields and validators](/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field)

***

## Step 3: Check credit score (Service Task)

Compute a credit score automatically after the form is submitted. For this tutorial, a business rule derives the score from the annual income, so you can run the process without an external scoring service.

**1. Add a Service Task**

Drag a **Service Task** after `Fill Personal Data`, connect the two, and name it `Check Credit Score`.

**2. Add a Business Rule action**

On the node's **Actions** tab, add a **Business Rule** action with **JavaScript** as the language, and paste:

```javascript theme={"dark"}
var income = Number(input.application.annualIncome);
var score = 450;
if (income >= 80000) {
  score = 750;
} else if (income >= 40000) {
  score = 600;
}
output.put("application", { "creditScore": score });
```

`input` holds the process data the form saved. `output.put` merges the new key into it, so the other `application` keys are kept.

![The Business Rule action on the Check Credit Score node with the JavaScript rule expanded and a Test Rule button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-check-credit-score-rule.png)

> [accordion] Using a real credit scoring service instead
>
> In production, this step calls an external service. In FlowX, integrations run as **Workflows**: lightweight flows that call external systems through Data Sources, triggered from your BPMN process with a **Start Integration Workflow** action. Replace the Service Task above with the following.
>
> **1. Create the credit-scoring workflow**
>
> Define your scoring service as a **RESTful System** data source, then build a workflow that calls it. New to workflows? The [integration workflow tutorial](./building-your-first-workflow) walks through this exact Data Source + Workflow setup.
>
> **2. Add a Send Message Task with a Start Integration Workflow action**
>
> Drag a **Send Message Task** after the user task. Add a **Start Integration Workflow** action, select your credit-scoring workflow, and in **Input Mapping** select the customer data (for example `application.annualIncome`) as the source path for each workflow input.
>
> **3. Add a Receive Message Task**
>
> This waits for the workflow to complete. In **Integration Output**, add a **Data Stream**, set **Source** to **Workflow**, and select your credit-scoring workflow. With **Legacy Mapping** off (the default), use the wrench button next to the workflow's End node under **Output Mapping** to map the score to `application.creditScore`. Alternatively, turn **Legacy Mapping** on and set **Key Name** to `application.creditScore`.
>
> ![Receive Message Task Integration Output with a Workflow data stream, Legacy Mapping off, and the End node listed under Output Mapping with its wrench button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-receive-output-mapping.png)
>
> The wrench opens the data mapping for that End node. Map the workflow's `creditScore` output to `application.creditScore`:
>
> ![Data mapping modal mapping the workflow's creditScore output to application.creditScore in the process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-receive-output-mapping-modal.png)
>
> Leaving the output mapping empty stops the process with a missing data stream mapping error.
>
> > [card] [Learn more about the Start Integration Workflow action](/5.9/docs/building-blocks/actions/start-integration-workflow)

> [card] [Learn more about business rules](/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action)

***

## Step 4: Branch based on credit score (Exclusive Gateway)

Different credit scores qualify for different card types.

**1. Add an Exclusive Gateway**

Drag an **Exclusive Gateway** after `Check Credit Score` and connect it. This creates a decision point based on the credit score.

**2. Add Service Tasks for each branch**

Add three Service Tasks (Premium, Standard, Basic) and draw an arrow from the gateway to each one. The gateway's **Advance to** list only shows nodes it is already connected to.

On each Service Task, add a **Business Rule** action with **JavaScript** as the language, and set the card type:

```javascript theme={"dark"}
output.put("application", { "cardType": "PREMIUM" });
```

Use `STANDARD` and `BASIC` on the other two. The output is merged into the process data, so the other `application` keys (name, income, credit score) are kept.

![Premium Service Task Actions tab with a Business Rule action in JavaScript that sets application.cardType to PREMIUM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-service-task-business-rule.png)

**3. Configure branch conditions**

Open the gateway's **Gateway Decisions** tab. Conditions read the process data through `input`, so start each one with `input.`:

* **Branch 1:** `input.application.creditScore >= 700` → Premium card
* **Branch 2:** `input.application.creditScore >= 500` → Standard card
* **Branch 3:** **Else** → Basic card

> [!NOTE]
>
> Conditions are evaluated top to bottom and the first true one wins, so keep the `>= 700` rule above the `>= 500` rule. A score of `750` satisfies both, and the order is what sends it to Premium. Click **Test** to try a sample `input` against your conditions before you save.

![Gateway Decisions tab for the card type gateway, routing credit scores of 700 or more to Premium, 500 or more to Standard, and everything else to Basic](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-gateway-decisions.png)

**4. Add a closing Exclusive Gateway**

Merge the branches back together after the card type is set: drag a second **Exclusive Gateway** and connect all three Service Tasks to it. A gateway with a single outgoing path needs no conditions.

> [card] [Learn more about Gateways](/5.9/docs/building-blocks/node/exclusive-gateway-node)

***

## Step 5: Show results and confirm (User Task)

Let the customer review their card type and confirm.

**1. Add a User Task**

Drag a **User Task** after the closing gateway, connect it, and name it `Review and Confirm`. In the **Navigation** tab, add a second **Page** named `Confirmation` and drag the task into it. User tasks on the same page render together, so a sequential screen needs its own page.

**2. Design the confirmation screen**

Display the assigned card type. Add a **Container** or **Card** to the screen, then place a **Text** component inside it with, for example, `You have a ${application.cardType} card.` The value is filled in from the process data when the screen shows.

![UI Designer showing the Review and Confirm screen with a Your card heading, the card type text, and a Confirm button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-confirmation-ui-designer.png)

**3. Add the Confirm button**

Add a **Button** labeled `Confirm` in the **UI Designer** and give it an **On Click** event handler with **Action Type** set to **Node Action**, pointing at this node's `saveData` action, exactly as you did in Step 2.

***

## Step 6: End the process

Drag an **End Event** after `Review and Confirm` and connect it. When the customer clicks **Confirm**, the token reaches the End Event and the instance completes.

***

## Test your process

**1. Check for warnings**

The Designer saves your changes automatically. Before you start, make sure no node shows a warning, in particular a user task that is not included in a navigation area.

**2. Start a process instance**

Click **Start Process** in the top-right corner. A dialog opens where you can pass start data as **JSON data**; leave it as `{}` and click **Start Process**. The form opens. Fill it in with an annual income of `90000` and click **Continue**. The score is computed, the gateway routes to Premium, and the confirmation screen shows `You have a PREMIUM card.` Click **Confirm**.

![Start Process dialog with an empty JSON data field and the Start Process button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-start-process-dialog.png)

![Running form with full name, email, date of birth, and an annual income of 90000 filled in, and the Continue button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-run-form-filled.png)

![Confirmation screen reading You have a PREMIUM card, with the Confirm button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-run-confirmation.png)

**3. Inspect the instance**

Open **Process Instances** to see the instance, the path its token took, and the data at each step. You should find `application.creditScore` set to `750` and `application.cardType` set to `PREMIUM`.

![Process instance view showing the finished token path through Premium and the application variables with creditScore 750 and cardType PREMIUM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cc-process-instance.png)

> [!TIP]
>
> You built and ran a complete process: a form that writes process data, a business rule that computes from it, a gateway that branches on it, and a screen that reads it back.

> [!TIP]
>
> Start two more instances with incomes of `50000` and `20000` to see the Standard and Basic branches.

> [card] [Starting a process](/5.9/docs/flowx-designer/managing-a-project-flow/starting-a-process)
>
> Other ways to start a process: from a UI, a Kafka event, an incoming email, or a webhook.

***

## Troubleshooting

> [accordion] Continue fails with Previous mandatory actions were not completed
>
> The user task has more than one manual action, usually a second `saveData` added by mistake. Open the node's **Actions** tab and remove the extra action, so the **Continue** button points at the only manual action left.

> [accordion] The form and the confirmation screen show up together
>
> Both user tasks are in the same navigation area. User tasks on one page render at the same time. Move `Review and Confirm` to its own **Page** in the **Navigation** tab, as in Step 5.

> [accordion] A score of 750 ends up as a Standard card
>
> The gateway conditions are evaluated in order, and the first true condition wins. Open the **Gateway Decisions** tab and make sure the `>= 700` condition is above the `>= 500` one, then click **Save**.

***

## What you learned

| Concept | How you used it |
| - | - |
| **User Tasks** | Collecting data, showing the result, wiring buttons to node actions |
| **Navigation areas** | Giving user tasks a page to render in |
| **Service Tasks** | Computing the credit score and setting the card type with business rules |
| **Exclusive Gateway** | Branching on the credit score and merging the branches back |
| **Process data** | Written by a form and a business rule, read by gateway conditions and a Text component |

***

## Extend the process

The full version of this scenario adds integrations. Each one needs a system outside FlowX, which is why they are not part of the guided steps:

* **Real credit scoring**: replace the business rule with an integration workflow that calls your scoring service, as shown in Step 3.
* **Confirmation email**: after the customer confirms, add a **Send Message Task** that calls the [notifications plugin](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview) with the customer's name and card type.
* **Register the card in the core banking system**: run it in parallel with the email by wrapping both in a [Parallel Gateway](/5.9/docs/building-blocks/node/parallel-gateway), each branch calling its own integration workflow.
* **Pick a branch for card pickup**: call a locations API from a workflow, then let the customer choose a branch in another user task.

***

## Next steps

> [card] [Continue: build your first workflow](./building-your-first-workflow)
>
> Connect an external API as a Data Source, build an integration workflow around it, and call it from a process. It is the piece that turns the simulated credit check into a real one.

> [card] [Build a complete app: reconcile supplier invoices](/5.9/cookbooks/invoice-reconciliation)
>
> A tested end-to-end build: receive invoices by email, extract them with AI, match each one against its purchase order, and send only the exceptions to a reviewer.

> [card] [UI components](/5.9/docs/building-blocks/ui-designer/ui-designer)
>
> Learn all available form and display components

> [card] [Business rules](/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action)
>
> Add complex logic with JavaScript or Python business rules

> [card] [Error handling](/5.9/docs/building-blocks/node/error-events)
>
> Handle failures gracefully

> [card] [FlowX Academy](https://academy.flowx.ai)
>
> Take structured courses with certifications


# Tutorial: Build your first UI Flow
Source: https://docs.flowx.ai/5.9/docs/getting-started/building-your-first-ui-flow

Build a two-page loan estimator UI Flow in FlowX Designer, with a form that starts a workflow, displays its result, and navigates between pages.

Tested · October 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** The workflow ran on its own, then the UI Flow validated the form, started the workflow, showed the result on both pages, and kept it in the session data.

In this tutorial you build your first **UI Flow**: a small two-page app where a user enters a loan amount and a term, clicks **Calculate**, and sees the monthly payment and a repayment breakdown. A workflow does the math. By the end, you'll know how to:

* Create a UI Flow with two pages and choose which one opens first
* Build a form with required fields and bind it to the UI Flow data model
* Start a workflow from a button and pass it the form values
* Show the workflow's output on a page and navigate between pages
* Run the UI Flow and inspect its session data

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.0**
>
> Everything in this tutorial works on FlowX.AI 5.9.0 and later releases. The screenshots come from a later release, so some panels can look slightly different on 5.9.x.

> [!NOTE]
>
> **Time required:** about 25 minutes
>
> **Prerequisites:**
>
> * Access to FlowX Designer
> * A workspace and project set up ([create one here](/5.9/docs/projects/workspaces))

> [!TIP]
>
> A **UI Flow** is a standalone user interface with its own pages, navigation, and data model, separate from any process. A **workflow** is integration logic built in the Integration Designer. In this tutorial the UI Flow collects input and shows results, and the workflow computes them. See the [Glossary](./glossary) if any term here is new.

***

## What you'll build

A loan estimator for Acme Bank. The **estimateForm** page holds a form with two fields. Its **Calculate** button validates the form and starts the `calculateLoanEstimate` workflow with the two values. The workflow returns a `loanEstimate` object, and the page shows the monthly payment from it. A second page, **estimateBreakdown**, shows the total repayment and the total interest from the same object.

```mermaid theme={"dark"}
flowchart LR
  subgraph U [UI Flow: LoanEstimator]
    P1[estimateForm page<br/>Loan amount, Term, Calculate] -- View breakdown --> P2[estimateBreakdown page<br/>Total repayment, Total interest]
    P2 -- Back --> P1
  end
  subgraph W [Workflow: calculateLoanEstimate]
    WS((Start)) --> SC[Calculate payment]
    SC --> WE((End))
  end
  P1 -. amount, termMonths .-> WS
  WE -. loanEstimate .-> P1
```

This is the finished first page at runtime, after a calculation:

![The Loan estimate page at runtime with Loan amount 25,000 and Term (months) 60 filled in, a Calculate button, the text Monthly payment: 489.15, and a View breakdown button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-runtime-result.png)

***

## Step 1: Build the workflow

The UI Flow needs something to call, so start with the workflow. It takes an amount and a term, applies a fixed annual interest rate of 6.5%, and returns three amounts ready to display. If you haven't built a workflow before, [Build your first workflow](./building-your-first-workflow) covers each of these screens in detail.

**1. Create the workflow**

Go to **Projects** → your project → **Integrations** → **Workflows** and click **Add Workflow**. Set the **Name** to `calculateLoanEstimate`. The workflow editor opens with a **Start** node already on the canvas.

**2. Declare the input and output**

Open the workflow's **Data Model** page from the left rail and add these attributes:

* `amount`: **Number**, **Floating Point**
* `termMonths`: **Number**, **Integer**
* `loanEstimate`: an object with three **String** attributes, `monthlyPayment`, `totalRepayment`, and `totalInterest`

Add `amount` and `termMonths` under **Input Parameters**. On the **Output Parameters** tab, select `loanEstimate`; its three fields are selected with it.

> [!NOTE]
>
> The three results are **String**, not **Number**, so they keep exactly two decimals. An output parameter of type **Number** (**Floating Point**) is stored with single precision, so `489.15` would reach the page as `489.1499938964844`.

**3. Set the Start node sample input**

Back in the editor, set the **Start** node's JSON to:

```json theme={"dark"}
{
  "amount": 25000,
  "termMonths": 60
}
```

At runtime the UI Flow supplies these values. The sample is what **Run Workflow** uses inside the editor.

**4. Add the Script node**

Drag a **Script** node after **Start**, connect the two, and name it `Calculate payment`. Keep the **JS** language tab and paste:

```javascript theme={"dark"}
// Fixed annual interest rate of 6.5%
const monthlyRate = 0.065 / 12;
const amount = Number(input.amount);
const months = Number(input.termMonths);

const payment = amount * monthlyRate / (1 - Math.pow(1 + monthlyRate, -months));

// toFixed(2) returns text with exactly two decimals, ready to display
output.loanEstimate = {
  monthlyPayment: payment.toFixed(2),
  totalRepayment: (payment * months).toFixed(2),
  totalInterest: (payment * months - amount).toFixed(2)
};
```

The script reads the workflow input from `input` and publishes its result by assigning `output.loanEstimate`. `Number()` makes the math work whether the values arrive as numbers or as numeric strings.

![The Calculate payment Script node with the JS tab selected, showing the interest-rate script that assigns output.loanEstimate using toFixed(2)](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-wf-script-node.png)

**5. Add the End node**

Drag an **End Flow** node after the script and connect it. Its **Output Schema** shows `loanEstimate` and its three fields, taken from the output parameters you selected. This is what the UI Flow receives.

![The End node with its Output Schema listing loanEstimate and its three string fields: monthlyPayment, totalRepayment, and totalInterest](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-wf-end-node.png)

**6. Run the workflow**

Click **Run Workflow** and open the **Output** tab of the **Run Logs** panel:

```json theme={"dark"}
{
  "loanEstimate": {
    "monthlyPayment": "489.15",
    "totalRepayment": "29349.22",
    "totalInterest": "4349.22"
  }
}
```

> [!TIP]
>
> The run finishes with no errors and the Output tab shows the three values above. The workflow is ready for the UI Flow.

***

## Step 2: Create the UI Flow and its pages

**1. Create the UI Flow**

Go to **Projects** → your project → **UI Flows** and click **+**. In the **Create UI Flow** dialog, fill in:

* **Name**: `LoanEstimator`
* **Platform**: **Web**
* **Experience Type**: **Flow-Based**

Click **Create**. The UI Flow editor opens.

> [!NOTE]
>
> Platform and experience type can't be changed after creation. **Chat-Driven** UI Flows are built around an AI conversational workflow and are out of scope for this tutorial.

**2. Define the data model**

In the left rail, open **Data Model**. On the **Data Model** tab, click **Create Attribute** and add:

* `loanAmount`: **Number**, **Floating Point**
* `termMonths`: **Number**, **Integer**

These are the keys the form fields bind to. Define them before you add the fields, because the field's **Data key** setting searches the data model.

**3. Add the two pages**

In the left rail, open **Designer**, then the **Navigation** tab of the left panel. Click **+** (**Add Root Component**) and pick **Page**. Do it twice, so the tree holds two pages.

Select the first page and, in the **Settings** tab on the right, set **Component Identifier** to `estimateForm`. Select the second page and set it to `estimateBreakdown`. The identifier is the name you pick later as a navigation destination.

**4. Set the home page**

Right-click `estimateForm` in the tree and choose **Set as Home**. The home page is the one the UI Flow opens on when it starts.

![The LoanEstimator UI Flow editor with the Navigation tab listing estimateForm, marked with a home icon, and estimateBreakdown, and the Settings panel showing Component Identifier estimateForm](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-ed-pages.png)

> [!TIP]
>
> The **Navigation** tab lists `estimateForm` and `estimateBreakdown`, with `estimateForm` marked as home.

> [card] [Learn more about UI Flows](/5.9/docs/building-blocks/ui-flows#creating-a-ui-flow)

***

## Step 3: Build the form page

Components are added from the **UI Assets** tab of the left panel (**UI Components**), by dragging them onto a node in the tree. You can also right-click a node and choose **Add UI components**. A page holds layout components such as cards, and a card holds the form, the buttons, and the text.

**1. Add a card**

From **Layout**, drag a **Card** onto `estimateForm`. In **Settings**, set its **Title** to `Loan estimate`.

**2. Add the form and its fields**

From **Form Components**, drag a **Form** into the card. Set its **Component Identifier** to `loanForm`, and leave **Validate on** at `submit`.

Drag two **Input** components into the form and configure them in **Settings**:

| Setting | First input | Second input |
| - | - | - |
| **Data key** | `loanAmount` | `termMonths` |
| **Label** | `Loan amount` | `Term (months)` |
| **Placeholder** | `25000` | `60` |
| Validator | `required`, **Error Message** `Enter the loan amount` | `required`, **Error Message** `Enter the term in months` |

In the **Data key** field, type at least three characters and pick the key from the data model. To add the validator, click **Add a validator** in the **Validators** section, set **Validator type** to `required`, and fill in the **Error Message**.

![The estimateForm component tree with estimateCard, loanForm, the two inputs, calculateButton, monthlyPaymentText, and viewBreakdownButton; the Loan amount input is selected and its Settings show Data key loanAmount, Label Loan amount, Placeholder 25000, and a Required validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-ed-form-input.png)

**3. Add the Calculate button**

From **Basic**, drag a **Button** into the card, below the form and outside it. Set its **Label** to `Calculate`. You wire it to the workflow in Step 4.

> [!NOTE]
>
> Keep buttons as siblings of the form, not inside it. The button's action decides which forms to validate.

**4. Add the result text**

From **Basic**, drag a **Text** component into the card, below the button. Set its **Text** to:

```text theme={"dark"}
Monthly payment: ${loanEstimate.monthlyPayment}
```

`${...}` reads a value from the UI Flow session data. `loanEstimate` doesn't exist until the workflow returns it, and you don't have to declare it in the data model: workflow output is added to the session data when it arrives.

**5. Add the View breakdown button**

Drag a second **Button** into the card, below the text, and set its **Label** to `View breakdown`.

> [card] [Learn more about input fields](/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field)

> [card] [Learn more about validators](/5.9/docs/building-blocks/ui-designer/validators)

***

## Step 4: Start the workflow from the Calculate button

Actions on UI Flow components are configured as **event handlers**: a trigger, such as a click, and an action that runs when it fires.

**1. Add a click handler**

Select the **Calculate** button. On the **Settings** tab, find the **Event Handlers** section, click **+**, and choose **On Click**.

**2. Pick the workflow**

Set **Action Type** to **Start Workflow**, and in **Workflow** pick `calculateLoanEstimate`.

**3. Validate the form**

In the **Functional** section, tick **Add forms to validate** and pick `loanForm`. The handler then runs only when both required fields hold a value.

**4. Pass the form values as start params**

Tick **Add start params** and enter:

```json theme={"dark"}
{"amount": ${loanAmount}, "termMonths": ${termMonths}}
```

The keys on the left are the workflow's input parameters; the `${...}` expressions read the form values from the session data. Don't put quotes around `${...}`: each value is inserted already JSON-encoded.

> [!WARNING]
>
> In a UI Flow, validating a form doesn't send its values anywhere. Start params are how the workflow receives them. If you leave start params empty, the workflow starts with no input.

**5. Save the handler**

Click **Save**. Optionally, tick **Show loader** in the **UX** section first, to show a loading indicator while the workflow runs.

![The On Click event handler of the Calculate button: Action Type Start Workflow, Workflow calculateLoanEstimate, Add forms to validate ticked with loanForm, and Add start params ticked with the amount and termMonths JSON](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-ed-start-workflow.png)

When the workflow finishes, its output (`loanEstimate`) is added to the UI Flow session data, and the **Monthly payment** text updates.

> [card] [Learn more about the Start Workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action)

> [card] [Learn more about event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers)

***

## Step 5: Build the breakdown page and connect the pages

**1. Build the breakdown page**

Drag a **Card** onto `estimateBreakdown` and set its **Title** to `Repayment breakdown`. Inside it, add two **Text** components:

```text theme={"dark"}
Total repayment: ${loanEstimate.totalRepayment}
```

```text theme={"dark"}
Total interest: ${loanEstimate.totalInterest}
```

Then add a **Button** below them with the **Label** `Back`.

Both pages read the same session data, so the breakdown page shows the result the first page received without calling the workflow again.

**2. Navigate to the breakdown**

Select the **View breakdown** button on `estimateForm`. Under **Event Handlers**, click **+**, choose **On Click**, set **Action Type** to **Navigate To**, and in **Destination** pick `estimateBreakdown`. Click **Save**.

![The On Click event handler of the View breakdown button with Action Type Navigate To and Destination estimateBreakdown](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-ed-navigate-to.png)

**3. Navigate back**

Select the **Back** button on `estimateBreakdown` and add the same kind of handler, with **Destination** set to `estimateForm`. Click **Save**.

> [card] [Learn more about the Navigate To action](/5.9/docs/building-blocks/ui-flows#configuring-the-navigate-to-action)

***

## Step 6: Run it and inspect the session

**1. Run the UI Flow**

Click **Run** in the top-right corner of the UI Flow editor. The **Run Ui Flow** dialog opens. **Input Parameters** holds the variables the UI Flow expects at start; this one expects none, so leave `{}`. Keep the default **Theme** and click **Run**.

![Run Ui Flow dialog for LoanEstimator with an empty Input Parameters JSON editor, the Theme dropdown set to the default theme, and a Run button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-run-dialog.png)

The UI Flow opens on `estimateForm`, the home page.

**2. Check the validation**

Click **Calculate** with both fields empty. The workflow doesn't start, and each field shows its required message.

![The Loan estimate page with both fields empty after clicking Calculate: the fields have red borders, the messages Enter the loan amount and Enter the term in months appear under them, and the Monthly payment text is still empty](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-runtime-validation.png)

**3. Calculate an estimate**

Enter `25000` and `60` and click **Calculate**. The page shows **Monthly payment: 489.15**.

**4. Open the breakdown**

Click **View breakdown**. The second page shows the totals from the same result:

![The Repayment breakdown page at runtime showing Total repayment: 29349.22, Total interest: 4349.22, and a Back button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-runtime-breakdown.png)

Click **Back**. The first page still shows the monthly payment.

**5. Inspect the session data**

In the toolbar on the left of the running UI Flow, click the eye icon (**View UI Flow instance**). A panel opens with the UI Flow name, the session ID, its status, and the tabs **Variables**, **Audit Log**, **Processes**, and **Workflows**. The **Variables** tab shows `loanEstimate` with the three values the workflow returned.

![The UI Flow instance panel for LoanEstimator with status STARTED and the Variables tab open in Tree View, showing loanEstimate as an object with monthlyPayment 489.15, totalRepayment 29349.22, and totalInterest 4349.22](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ufl-instance-panel.png)

Use **Export JSON** to copy the whole session data, for example when comparing two runs.

> [!TIP]
>
> The form refuses empty input, **Calculate** shows 489.15, the breakdown page shows 29349.22 and 4349.22, and the **Variables** tab holds `loanEstimate`. That loop, page to workflow and back into the session data, is the pattern behind most UI Flow screens.

***

## Troubleshooting

> [accordion] The monthly payment stays empty after Calculate
>
> The workflow ran without the values it needs, or its output didn't reach the UI Flow. Check, in order:
>
> * The start params keys are exactly `amount` and `termMonths`, the workflow's input parameter names.
> * The `${...}` expressions name the form's data keys, `loanAmount` and `termMonths`, and have no quotes around them.
> * The workflow's **End Flow** node lists `loanEstimate` in its **Output Schema**.
> * The **Text** reads `${loanEstimate.monthlyPayment}`, with the same spelling as the script's output.
>
> Open the **Workflows** tab of the **View UI Flow instance** panel to see whether the workflow ran.

> [accordion] The monthly payment shows extra decimals, like 489.1499938964844
>
> The `loanEstimate` fields are typed **Number** (**Floating Point**) in the workflow's **Data Model**. Change all three to **String** and return them with `toFixed(2)`, as in the `Calculate payment` script.

> [accordion] The Variables tab doesn't show loanAmount or termMonths
>
> That's expected. In a UI Flow, **Add forms to validate** only validates the form; the values reach the workflow through the start params. The **Variables** tab shows what was stored in the session, such as the workflow output.

> [accordion] The UI Flow opens on the breakdown page
>
> `estimateBreakdown` is the home page. Right-click `estimateForm` in the **Navigation** tab and choose **Set as Home**, then run the UI Flow again.

> [accordion] The Data key field finds nothing
>
> The key isn't in the UI Flow's data model yet. Open **Data Model**, add `loanAmount` and `termMonths` with **Create Attribute**, and pick the key again. The search starts after three characters.

> [accordion] The workflow isn't listed in the Workflow dropdown
>
> The dropdown lists the workflows of the project you're working in. Create `calculateLoanEstimate` in the same project as the UI Flow.

***

## What you learned

| Concept | How you used it |
| - | - |
| **UI Flow** | A standalone app with its own pages, data model, and session |
| **Home page** | **Set as Home** decides which page opens when the UI Flow starts |
| **Form and validators** | Two inputs bound with **Data key**, each with a `required` validator |
| **Start Workflow handler** | **Add forms to validate** to gate the click, **Add start params** to pass the values |
| **Session data** | Workflow output added under `loanEstimate` and read by `${...}` in text on both pages |
| **Navigate To handler** | Moving between pages by **Destination** |
| **UI Flow instance panel** | Checking the session data in the **Variables** tab |

***

## Where to go next

> [card] [UI Flows](/5.9/docs/building-blocks/ui-flows)
>
> The full reference: experience types, navigation, Start Process and Start Workflow actions, and embedded processes.

> [card] [Event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers)
>
> Every trigger and action type you can attach to a UI component.

> [card] [Validators](/5.9/docs/building-blocks/ui-designer/validators)
>
> Built-in and custom validators for form fields.

> [card] [Build your first workflow](./building-your-first-workflow)
>
> Call a real REST API from a workflow and start it from a process.


# Tutorial: Build your first workflow
Source: https://docs.flowx.ai/5.9/docs/getting-started/building-your-first-workflow

Connect FlowX to an external REST API, build an integration workflow around it, and call that workflow from a BPMN process.

Tested · October 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** The workflow ran on its own, then the process called it and finished with the exchange rate in its instance data.

In this tutorial you build your first **integration workflow**: a small flow that calls a public exchange-rates API, picks one rate out of the response with a script, and hands the result back to a Business Process Model and Notation (BPMN) process. By the end, you'll know how to:

* Define a data source with a tested REST endpoint
* Build a workflow from REST API Call, Script, and End nodes and run it
* Start a workflow from a process and map data in and out of it
* Find the result in the finished process instance

> [!NOTE]
>
> **Time required:** about 20 minutes
>
> **Prerequisites:**
>
> * Access to FlowX Designer
> * A workspace and project set up ([create one here](/5.9/docs/projects/workspaces))
> * Outbound internet access from your FlowX environment, so the workflow can reach the public API

> [!TIP]
>
> Remember the distinction: a **process** is a BPMN flow with user and service tasks; a **workflow** is integration logic built in the Integration Designer. Processes delegate data fetching and transformations to workflows. See the [Glossary](./glossary) if any term here is new.

***

## What you'll build

A currency lookup. A process holds the currency a customer picked, starts a workflow with it, and waits. The workflow calls the [Frankfurter](https://frankfurter.dev) exchange-rates API (free, no API key), extracts the USD rate, and returns it. The process stores the result under `exchangeResult`.

```mermaid theme={"dark"}
flowchart LR
  subgraph P [Process: currencyLookup]
    S((Start)) --> A[Get exchange rate]
    A --> B[Receive exchange rate]
    B --> E((End))
  end
  subgraph W [Workflow: Get exchange rate]
    WS((Start)) --> R[Get rates]
    R --> X[Pick USD rate]
    X --> WE((End))
  end
  A -. baseCurrency .-> WS
  WE -. rate, currency .-> B
```

The API is a stand-in. Swap in any REST API you have access to and the steps stay the same.

This is how the finished workflow looks in the Integration Designer:

![The finished Get exchange rate workflow on the canvas: a Start node, a Get rates REST API Call node, a Pick USD rate Script node, and an End node with rate and currency in its Output Schema](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-workflow-canvas.png)

Watch the workflow being built and run, from the REST API Call node to the USD rate in the output:

<video>
  <track label="English" />
</video>

***

## Step 1: Create the data source

A data source is a reusable connection to an external system: its base URL, authorization, and the endpoints you call on it. Every workflow in the project can use it.

**1. Create a RESTful system**

In FlowX Designer, go to **Workspaces** → your workspace → **Projects** → your project → **Integrations** → **Data Sources**. Click **+**, and in the **Add Data Source** modal pick **Restful System**. Fill in:

* **Name**: `Exchange Rates`
* **Description**: `Frankfurter exchange-rates API`

Click **Create Data Source**. The system page opens.

**2. Set the base URL**

In the **Base URL** card on the system page, enter `https://api.frankfurter.dev/v1`.

> [!TIP]
>
> Base URLs usually differ per environment. You can write them as `https://api.${environment}.example.com/v1` and resolve the variable through [configuration parameters overrides](/5.9/docs/projects/runtime/configuration-parameters-overrides).

**3. Check the authorization**

Open the **Settings** tab. Under **Authorization**, the **Auth Type** options are `NO_AUTH`, `BEARER`, `BASIC`, `SERVICE_ACCOUNT`, `PRIVATE_KEY`, and `ACCESS_KEY`. Frankfurter needs no credentials, so leave `NO_AUTH`. For a real API, pick what it requires. Token values are best defined here at system level and overridden per environment.

**4. Add an endpoint**

Open the **Endpoints** tab and click **+**. In the **Add Endpoint** dialog, pick the `GET` method and set the **Name** to `getLatestRates`, then confirm. On the endpoint page:

* **Path**: `/latest`
* On the **Query** tab, add one parameter: **Name** `base`, **Value** `EUR`, then click the green check to add the row. The value is the default the endpoint test uses; the workflow overrides it at runtime.

![Endpoint page for GET getLatestRates with the read-only Base URL, the Path set to /latest, and the Query tab showing one parameter named base with the value EUR](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-endpoint-query.png)

Back on the system page, the **Endpoints** tab now lists `getLatestRates`.

![Exchange Rates system page with the Base URL card set to the Frankfurter API and the Endpoints tab listing the GET getLatestRates endpoint](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-data-source-system.png)

**5. Test the endpoint**

Click **Test** on the endpoint page. The **Test GET getLatestRates** modal shows the resolved URL and the query parameter. Click **Test** in the modal and read the response:

```json theme={"dark"}
{
  "base": "EUR",
  "date": "2026-10-02",
  "rates": {
    "GBP": 0.85033,
    "JPY": 176.99,
    "USD": 1.1225
  }
}
```

The real response lists about 30 currencies; the rate values change daily. Click **Use as Response Example** to store the shape on the endpoint's **Response Example** tab.

![Test GET getLatestRates modal with the Exchange Rates system, the endpoint URL, the base query parameter, and a response pane showing status 200 and a JSON body with base, date, and rates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-endpoint-test.png)

> [!TIP]
>
> The test returns status 200 and a JSON body whose `rates` object contains `USD`. If it does, the data source is ready for the workflow.

> [card] [Learn more about data sources](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#creating-a-new-data-source-definition)

> [card] [Learn more about REST endpoints](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#defining-rest-integration-endpoints)

***

## Step 2: Build the workflow

**1. Create the workflow**

Go to **Projects** → your project → **Integrations** → **Workflows** and click **+**. In the **Add Workflow** dialog, set the **Name** to `Get exchange rate`, add a description, under **Set Workflow Type** keep **Output Focused**, and click **Save**. The workflow editor opens with a **Start** node already on the canvas.

**2. Place the End node**

Drag an **End Flow** node from the palette onto the canvas and leave it unconnected for now; you connect it after the script. It keeps its default name, `End Flow 001`; that is the name Step 3 shows for it.

The End node comes first because output parameters belong to it: until it exists, the **Output Parameters** tab of the Data Model page says **No End node present in the workflow**.

**3. Declare the data model, inputs, and outputs**

Open the workflow's **Data Model** page from the left rail and add three attributes: `baseCurrency` (String), `rate` (Number), and `currency` (String). Select `rate` and, in **Attribute Settings**, set **Subtype** to **Floating Point**. Then:

* On the **Input Parameters** tab, add `baseCurrency`.
* On the **Output Parameters** tab, with `End Flow 001` selected in the node dropdown, click **Define parameters**, tick `rate` and `currency`, and click **Done**.

> [!WARNING]
>
> A **Number** attribute's **Subtype** defaults to **Integer**. Left that way, the workflow returns the rate `1.1225` as `1`.

This is what makes the process able to talk to the workflow in Step 3: the input mapper offers only declared input parameters, and the End node exposes only declared output parameters.

> [!NOTE]
>
> Finish the Data Model page before you configure the nodes. Going back to it later and returning to the editor can drop the **Start payload** and show the REST API Call node's endpoint as unselected; reopening the workflow from the **Workflows** list brings the endpoint back.

**4. Set the Start node sample input**

Back in the editor, the **Start** node's **Start payload** field carries the input every run begins with, as JSON. It is pre-filled from the input parameters as `{"baseCurrency": ""}`. Set it to:

```json theme={"dark"}
{
  "baseCurrency": "EUR"
}
```

At runtime the process supplies this value. The sample is what **Run Workflow** uses inside the editor.

**5. Add the REST API Call node**

Drag a **REST API Call** node from the palette, connect **Start** to it, and name it `Get rates` (double-click the node title to rename it). Configure it:

* **Endpoint**: pick `GET getLatestRates` under the Exchange Rates system (the dropdown groups endpoints by system).
* **Query Parameters** → `base`: enter `${baseCurrency}` in the field that reads **Add value or variable**. This replaces the test default with the workflow input.
* **Response Key**: `rates`

![Get rates node card with the GET getLatestRates endpoint selected and the base query parameter set to the baseCurrency workflow variable](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-rest-node.png)

The Response Key is where the next node finds the call result: the node writes the whole HTTP response under `input.rates`, and the JSON body sits at `input.rates.data`.

**6. Pick the rate with a Script node**

Drag a **Script** node after `Get rates`, connect the two, and name it `Pick USD rate`. Keep the **JS** language tab and paste:

```javascript theme={"dark"}
// input.rates = REST API Call result
const body = input.rates.data;
output.rate = body.rates.USD;
output.currency = "USD";
```

Scripts read the previous nodes' data from `input` and publish their result by assigning keys on `output`. There is no return statement.

![Pick USD rate Script node card with the JS tab selected and the four-line script that reads input.rates.data and sets output.rate and output.currency](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-script-node.png)

**7. Connect the End node**

Connect `Pick USD rate` to `End Flow 001`. The End node's card shows an **Output Schema** with `rate` and `currency`. Whatever the previous nodes wrote under those keys is the workflow's output, and it is what the calling process receives.

![End node card showing the Output Schema with rate of type number and currency of type string](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-end-node.png)

**8. Run the workflow**

Click **Run Workflow** in the top-right corner. On a draft project version the run starts immediately with the Start node's JSON, and the **Run Logs** panel opens at the bottom: a **Nodes** list with the time each node took, and **Logs**, **Input**, and **Output** tabs. Open **Output**:

```json theme={"dark"}
{
  "rate": 1.1225,
  "currency": "USD"
}
```

Each node card also gains **Input** and **Output** tabs with that run's data, which is the quickest way to see what the REST call returned.

![Run Logs panel after a successful run, listing the Workflow, Start, Get rates, Pick USD rate, and End nodes with their timings, and the Output tab showing rate 1.1225 and currency USD](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-workflow-run.png)

> [!NOTE]
>
> On a committed project version, **Run Workflow** opens a **Test Workflow** dialog first, where you edit the **Test Input** before running.

> [!TIP]
>
> The run finishes with no errors and the Output tab shows a numeric `rate` and `"USD"`. The rate differs from the one above, because the API publishes new rates every working day.

> [card] [Learn more about workflows](/5.9/docs/platform-deep-dive/integrations/integration-workflows#creating-a-workflow)

> [card] [Learn more about workflow data models](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)

***

## Step 3: Call the workflow from a process

The process needs two things: a place to keep the input and the result, and a pair of nodes that start the workflow and wait for its answer.

**1. Create the process and its data model**

Go to **Processes**, click **+**, and create a process named `currencyLookup`. Open its **Data Model** page from the left rail and set up two attributes:

* `selectedCurrency` (String): the input the process passes to the workflow
* `exchangeResult`: where the workflow's output lands. It is an object with `rate` and `currency`, and objects are built from a data type:
  1. In the **Data Types** panel, click **+** and name the new type `ExchangeResult` in **Data Type Settings**.
  2. Add two attributes to `ExchangeResult`: `rate` (Number, with **Subtype** set to **Floating Point**, as in the workflow) and `currency` (String).
  3. Add the `exchangeResult` attribute and, in its type menu, click **Custom data type**, then pick `ExchangeResult` under **Existing** → **Process**.

**2. Add the nodes**

On the canvas, build: **Start** → **Send Message Task** named `Get exchange rate` → **Receive Message Task** named `Receive exchange rate` → **End Process**. Connect them in that order. To rename a node, select it and, in **Node settings** → **Node Config**, change **Node name** and click **Save**. The start and end nodes keep their default names, `Start_001` and `End_001`.

![The currencyLookup process on the canvas: Start, a Get exchange rate Send Message Task, a Receive exchange rate Receive Message Task, and End in one swimlane](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-process-diagram.png)

The **Start Integration Workflow** action also works on **Task** and **User Task** nodes. The send-and-receive pair is the plain form: the send node fires the workflow, the receive node parks the token until the output arrives.

**3. Add the Start Integration Workflow action**

Select `Get exchange rate`, open **Node settings** → **Actions**, and click **+**. Give the action a name, check that **Action Type** is **Start Integration Workflow** (the default on a Send Message Task), and leave **Trigger**, **Execution**, and **Navigation** at their defaults, so the action runs on its own when the token arrives.

In the workflow field (**Search workflow by name**), pick `Get exchange rate`. Under **Data mapping**, leave **Legacy mapping** off. The **Input Mapping** section lists the **Workflow nodes** that take input: click the wrench on the **Start** row.

![Action Edit form with Action Type set to Start Integration Workflow, the Get exchange rate workflow selected, Legacy mapping off, and the Input Mapping section listing the Start workflow node with its wrench button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-action-config.png)

**4. Map the process data to the workflow input**

The **Data Mapping Integration Start Node Start** modal opens. The left pane lists the process attributes sent to the workflow; the right pane lists the workflow's input parameters.

1. If the left pane says **No process Parameters**, click **Define parameters**, tick `selectedCurrency`, and click **Done**.
2. In the right pane, click the field next to `baseCurrency`, type `${selectedCurrency}`, and pick the suggestion that appears.
3. Click **Confirm**, then **Save** on the action form.

![Data mapping modal for the workflow Start node: selectedCurrency listed under Variables sent by the main process on the left, and baseCurrency mapped to the selectedCurrency variable under Variables expected by the workflow on the right](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-input-mapping.png)

**5. Receive the workflow output**

Select `Receive exchange rate` and open **Node settings** → **Node Config**. Under **Integration Output**, click **Add Stream** and configure the **Data Stream**:

* **Source**: **Workflow** (the default)
* **Select workflow**: `Get exchange rate`
* **Legacy Mapping**: leave off

The **Output Mapping** section lists the workflow nodes that produce output. Click the wrench on the **End Flow 001** row.

![Receive exchange rate node configuration with a Data Stream whose Source is Workflow and workflow is Get exchange rate, Legacy Mapping off, and the Output Mapping section listing the End workflow node with its wrench button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-receive-output-config.png)

**6. Map the workflow output to the process**

The **Data Mapping Integration End Node End Flow 001** modal opens, mirrored: the workflow's output parameters on the left, the process attributes on the right.

1. Add the targets to the right pane: it says **No process Parameters**, so click **Define parameters**, tick `rate` and `currency` under `exchangeResult`, and click **Done**.

2) Next to `exchangeResult.rate` type `${rate}` and pick the suggestion; next to `exchangeResult.currency` type `${currency}` and pick the suggestion.
3) Click **Confirm**, then **Save** on the node.

![Data mapping modal for the workflow End node: rate and currency listed under Variables returned by the workflow on the left, and the exchangeResult object on the right with its rate and currency attributes mapped to the rate and currency variables](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-output-mapping.png)

> [!NOTE]
>
> **Legacy Mapping** is the alternative: turn it on and set a single **Key Name**, and the whole workflow output lands under that key without per-attribute mapping. The mapper is the default because it keeps the process data model explicit.

> [card] [Learn more about the Start Integration Workflow action](/5.9/docs/building-blocks/actions/start-integration-workflow)

***

## Step 4: Run it end to end

**1. Start the process**

Click **Start Process** in the top-right corner. In the dialog, set **JSON data** to:

```json theme={"dark"}
{
  "selectedCurrency": "EUR"
}
```

and click **Start Process**. The JSON editor closes braces for you, so if you type or paste the block, check that it ends with a single `}`.

There is no screen to fill in: the token runs through the four nodes on its own. The editor switches to a preview that keeps loading; you can leave it and go on to **Runtime**.

**2. Inspect the instance**

Switch to **Runtime** and open **Process Instances**. The newest `currencyLookup` instance is **FINISHED** with `End_001` as its current node. Open it: the diagram highlights the path Start → Get exchange rate → Receive exchange rate → End, the **Variables** tab shows the data, and the **Tokens** tab shows the single token with `End_001` as its current node.

![A finished currencyLookup process instance with its diagram, a FINISHED status badge, and the Variables tab showing selectedCurrency EUR and an exchangeResult object with rate 1.1225 and currency USD](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/fw-process-instance.png)

> [!TIP]
>
> `exchangeResult.rate` holds a number and `exchangeResult.currency` holds `USD`. That round trip, process to workflow to external API and back into the process data, is the pattern behind most FlowX integrations.

***

## Troubleshooting

> [accordion] The input mapper's left pane says No process Parameters
>
> The action does not know yet which process attributes to offer. Click **Define parameters** in the left pane, tick `selectedCurrency`, and click **Done**. The attribute then appears and can be mapped.

> [accordion] The input mapper's right pane is empty
>
> The workflow has no input parameters declared, so there is nothing to map to. Open the workflow's **Data Model** page and add `baseCurrency` under **Input Parameters**, then reopen the mapper.

> [accordion] Typing the attribute name only offers Add new attribute
>
> The mapper matches the expression form, not the bare name. Type the full `${selectedCurrency}` (with the dollar sign and braces) and pick the suggestion that appears below the field.

> [accordion] The rate comes back as a whole number, such as 1
>
> A **Number** attribute's **Subtype** defaults to **Integer**, which drops the decimals. Open the workflow's **Data Model** page, select `rate`, and set **Subtype** to **Floating Point** in **Attribute Settings**. Do the same for `rate` in the process's `ExchangeResult` data type, then run again.

> [accordion] The Output Parameters tab says No End node present in the workflow
>
> Output parameters belong to an End node. Add the **End Flow** node to the canvas first, then open **Output Parameters**, pick the End node in the dropdown, and click **Define parameters**.

> [accordion] The script fails reading rates
>
> The Script node reads `input.rates.data`, so the REST API Call node's **Response Key** must be exactly `rates`. If you used another key, change either the key or the first line of the script to match. Open the `Get rates` node's **Output** tab after a run to see the exact shape it produced.

***

## What you learned

| Concept | How you used it |
| - | - |
| **Data source** | A RESTful system with a base URL, an auth type, and a tested `GET` endpoint |
| **Workflow data model** | Input and output parameters that make the Start and End nodes typed |
| **REST API Call node** | Calling the endpoint with a workflow variable and naming the result with a Response Key |
| **Script node** | Shaping the response into the two values the process needs |
| **Start Integration Workflow action** | Starting the workflow from a Send Message Task with mapper-mode input mapping |
| **Integration Output** | Receiving the output on a Receive Message Task and mapping it into `exchangeResult` |

***

## Where to go next

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> The full reference: endpoint parameters, authorization, caching, file handling, and every workflow node.

> [card] [Workflow data models](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
>
> Typed inputs and outputs for workflows, with automatic Start-node pre-fill.

> [card] [Start integration workflow action](/5.9/docs/building-blocks/actions/start-integration-workflow)
>
> Everything about calling workflows from processes, including when to use subprocesses instead.

> [card] [Cookbook: call an external API](/5.9/cookbooks/call-external-api)
>
> Your next build: send data to a workflow, call a real API, and map the reply back into the process.

> [card] [Cookbooks](/5.9/cookbooks/overview)
>
> Tutorials, guides, and patterns to build on what you just learned.


# FlowX.AI documentation
Source: https://docs.flowx.ai/5.9/docs/introduction

Build enterprise applications and deploy AI agents for banking, insurance, and logistics

FlowX.AI Docs · 5.9 LTS

Build enterprise apps. Deploy AI agents.

FlowX.AI is an enterprise platform for building business apps in regulated industries. Connect your existing systems, design processes visually, and launch modern solutions without replacing your core infrastructure.

[Build your first process](/5.9/docs/getting-started/building-your-first-proc)
[Build your first workflow](/5.9/docs/getting-started/building-your-first-workflow)
[Browse the cookbooks](/5.9/cookbooks/overview)

01 · Paths

## Choose your path

[01
I want to build apps
Start here. Create your first process with a UI in the visual designer.](/5.9/docs/getting-started/building-your-first-proc)

[02
I need to deploy FlowX
Install and configure FlowX in your infrastructure.](/5.9/setup-guides/setup-guides-overview)

[03
I want to integrate APIs
Use the SDKs (Angular, React, iOS, Android) or REST APIs.](/5.9/sdks/sdks-overview)

[04
I want to deploy AI agents
Build and deploy AI agents for your business processes.](/5.9/ai-platform/ai-in-flowx)

05
I'm evaluating FlowX
See how the platform is built, where it runs, and what it connects to, before anyone writes a process.

[architecture](/5.9/docs/platform-overview/flowx-architecture)
[deploy.options](/5.9/docs/saas/saas-overview)
[integrations](/5.9/docs/platform-deep-dive/integrations/integrations-overview)
[agent.catalog](/5.9/ai-platform/agent-catalog)

flowx-designer · sdksclientapi gateway

core-engineprocessapp-lifecyclebuild · deploycontent-datacms · searchauth-securityspicedbbusiness-servicesdocs · tasksai-platformagents

layerskafka

***

02 · Learning path

## Learning path

New to FlowX? Follow this sequence:

<ul>
  <li>[build your first process](/5.9/docs/getting-started/building-your-first-proc) · model a BPMN flow with a UI and run it, in about 15 min*step 01*</li>
  <li>[build your first workflow](/5.9/docs/getting-started/building-your-first-workflow) · connect an external API and call it from your process*step 02*</li>
  <li>[mortgage advisor chatbot](/5.9/ai-platform/tutorials/mortgage-advisor) · ready for AI? build a conversational agent*step 03*</li>
  <li>[cookbooks](/5.9/cookbooks/overview) · build a complete app, like [invoice reconciliation](/5.9/cookbooks/invoice-reconciliation) or [customer onboarding with KYC](/5.9/ai-platform/tutorials/customer-onboarding), with the [glossary](/5.9/docs/getting-started/glossary) at hand*step 04*</li>
</ul>

***

03 · In production

## What you can build

Real examples of what teams build with FlowX.AI:

use casecoversstatus

customer-onboardingID verification · KYC · account creationin production+

**The problem:** Onboarding takes weeks, requires multiple systems, and drops customers due to friction.**What you build:** A unified digital journey: ID verification, document upload, KYC checks, and account creation, all in one flow that connects to your core banking system.**Result:** Onboarding in minutes instead of days. Full audit trail for compliance.**Build one:** [customer onboarding with KYC](/5.9/ai-platform/tutorials/customer-onboarding), from identity verification to manual review routing.

loan-originationcapture · scoring · decisioning · e-signin production+

**The problem:** Loan applications require manual data entry across systems, slow credit decisions, and paper-based approvals.**What you build:** End-to-end digital lending: application capture, credit scoring integration, automated decisioning, e-signature, and disbursement, with human review where needed.**Result:** Faster time-to-yes, reduced operational costs, consistent decisions.**Build one:** [a document processing pipeline](/5.9/ai-platform/tutorials/document-processing), where an AI agent verifies applicant documents against the declared data.

claims-processingFNOL · assessment · routing · settlementin production+

**The problem:** Claims intake is manual, assessment is slow, and customers wait weeks for resolution.**What you build:** First notice of loss capture, document collection, AI-assisted damage assessment, automated routing to adjusters, and settlement workflows.**Result:** Claims resolved in days, not weeks. Better customer experience.

back-office-automationapprovals · tasks · escalations · reportingin production+

**The problem:** Internal processes rely on emails, spreadsheets, and tribal knowledge.**What you build:** Structured workflows for approvals, task assignment, escalations, and reporting, with visibility into bottlenecks.**Result:** Consistent processes, clear accountability, reduced errors.**Build one:** [reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation), from email intake to exception review.

***

04 · Process

## How it works

<ol>
  <li>
    01
    Design your process
    Map your workflow using BPMN 2.0 in the visual designer. Drag and drop nodes, define business rules, set up integrations. No coding required for standard flows.
    [designer.overview](/5.9/docs/flowx-designer/overview)
  </li>

  <li>
    02
    Build your UI
    Configure components: forms, tables, file uploads, signatures. The UI automatically adapts to web and mobile.
    [ui.components](/5.9/docs/building-blocks/ui-designer/ui-designer)
  </li>

  <li>
    03
    Connect your systems
    Integrate with your existing infrastructure using REST APIs, Kafka, or custom connectors. FlowX orchestrates the data flow between systems.
    [integrations](/5.9/docs/platform-deep-dive/integrations/integrations-overview)
  </li>

  <li>
    04
    Deploy and run
    Deploy to FlowX SaaS or your own infrastructure. Monitor processes, handle exceptions, iterate based on real usage.
    [deploy.options](/5.9/docs/saas/saas-overview)
  </li>
</ol>

***

05 · Concepts

## Key concepts

New to FlowX? Here's what you need to know:

processA business workflow defined in BPMN 2.0. Contains nodes, actions, and UI.nodeA step in your process: user tasks, service tasks, gateways, events.actionWhat happens at a node: save data, call API, send notification, run business rule.tokenTracks where a process instance is. Multiple tokens = parallel execution.data modelThe structure of data in your process. Defined as keys with types.integrationConnection to external systems via REST, Kafka, or custom protocols.

For every other term, see the [full glossary](/5.9/docs/getting-started/glossary).

***

06 · Get help

## Get help

Start building.
Free courses on FlowX Academy, support when you need it, and the latest platform changes in the release notes.

[FlowX Academy](https://academy.flowx.ai)
[Contact support](https://flowxai.zendesk.com/)
[Release notes](/release-notes/overview)
[Use with AI](/5.9/docs/getting-started/using-flowx-docs-with-ai)


# Node actions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/actions

Actions define the activities that a node handles. Actions have various types and specify communication details for plugins or integrations.

Node actions are the units of work you attach to a process node: they run business rules, send Kafka messages, push data to the user interface, start subprocesses or integration workflows, upload files, and send notifications. You configure them in the **Actions** tab of a node in the FlowX.AI Designer.

> [card] Why is it important?

Node actions allow you to incorporate **business rules** (Business rules are actions that can be configured on task/user task nodes in a business process. Business rules can be written in various script languages such as MVEL, JavaScript, Python, or Groovy.) into a **process** (A process is a representation of a business use case, such as requesting a new credit card. These steps can involve a combination of automated actions and human interactions.), and send data to front-end apps.

The FlowX.AI platform supports the following **types of node actions**:

> [card] [Business rule](./business-rule-action/business-rule-action)

> [card] Save Data

> [card] [Kafka send](../node/message-send-received-task-node)

> [card] [Send data to user interface](./send-data-to-user-interface)

> [card] [Upload file](./upload-file-action)

> [card] [Start subprocess](./start-subprocess-action)

> [card] [Append params to parent process](./append-params-to-parent-process)

> [card] [Start integration workflow](./start-integration-workflow)

> [card] [Start new project instance](./start-new-project-instance)

> [card] [Send notification](./send-notification-action)

> [!NOTE]
>
> You can only define and add actions on the following types of **nodes**: [**send message task**](../node/message-send-received-task-node#send-message-task), [**task**](../node/task-node) and [**user task**](../node/user-task-node).

Actions fall into two categories:

* Business rules
* User interactions

### Business rules

Actions use action rules such as MVEL expressions or scripts in JavaScript, Python, or Groovy to attach business rules to a node.

> [card] [Business rule action](./business-rule-action)

> [card] [Supported scripts](../supported-scripts)
>
> For more information about supported scripting languages, see Supported scripts.

> [!NOTE]
>
> Each button on the user interface corresponds to a manual user action.

### Action edit

When configuring an action, the Action Edit panel provides three main configuration sections:

#### Trigger

This section defines how and when you can execute the action:

* **Manual**: Requires manual triggering through the REST API, typically by a user interaction in the interface (for example, clicking a button). When turned off, the action runs automatically.
* **Repeatable**: When enabled, you can trigger the action multiple times. When turned off, you can execute the action only once.

> [!NOTE]
>
> Manual actions can be either mandatory or optional. Automatic actions are always considered mandatory.

#### Execution

This section controls the action's execution behavior:

* **Optional**: When enabled, the action is optional and the flow can advance without executing it. When turned off (default), the action is mandatory.
* **Autorun Children?**: When enabled, all child actions marked as mandatory and automatic run immediately after the parent action completes. Default is off.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/node_action.png)

> [!NOTE]
>
> If all mandatory actions on a node are not executed, the flow (token) doesn't advance.

#### Navigation

This section controls user navigation behavior:

* **Allow back to this action**: Returns the token to this action from a downstream node only if you trigger the action manually.
  When enabled, you have the following "Back in steps" configuration options available:
  * **When returning to this action, reset process data**: Restores the process state and data to how it was before the initial execution of this action. Default is off.
  * **Copy the following objects from current state**: Specifies process keys that retain their data as persisted before you navigate back to this action.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/allow_back_in_action.png)

### Action parameters

Action parameters store extra values as key/value pairs, such as topics for outgoing messages or message formats for the front-end.

## Configuring actions

Beyond the basic trigger, execution, and navigation settings described in the preceding section, actions have additional characteristics:

### Action order

When multiple actions exist on a single node, the system executes them in the order you define them.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/%20node_action1.png)

### Parent/child hierarchy

Actions can be organized in a parent/child hierarchy, allowing you to create dependent action chains. Child actions can be configured to:

* Run automatically after the parent completes (using **Autorun Children?**): When enabled, all child actions marked as mandatory and automatic run immediately after the parent action completes. Default is off.
* Execute as callbacks when responses are received from external systems

For more information on adding and managing actions, see the following section:

> [card] [Adding an action to a node](../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node)

## Linking actions together

You can link actions together in two ways so that certain actions run immediately after others:

> [!NOTE]
>
> Certain actions can run immediately after another action by setting the `parentName` field on the action for callbacks. Callback actions are performed when the Engine receives a specific message, indicated by the `callbacksForAction` header in the message. To run actions immediately after the parent action, set the `autoRunChildren` flag to `true` for the parent action.

### Child actions

A parent action has a flag `autoRunChildren`, set to `false` by default. When you set this flag to `true`, the child actions (the ones defined as mandatory and automatic) run immediately after the parent action completes execution.

![Action Edit settings with Autorun Children switched on](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/17-autorun_children.png)

### Callback actions

You can mark child actions as callbacks to run after receiving a reply from an external system. Set these actions when defining the interaction with the external system (the [Kafka send action](../node/message-send-received-task-node#configuring-a-send-message-task)).

For example, you can use a callback function to handle a user's interaction with a web page, such as uploading a file. When the user performs the action, the callback function executes, allowing the web app to respond appropriately.

![Upload File action headers with callbacksForAction set to the parent action name](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/03b-upload_config_b_headers.png)

#### Example

Add callback actions in the **Advanced configuration** tab, in the **header** parameter `callbacksForAction`.

```js theme={"dark"}
{"processInstanceId": ${processInstanceId}, "destinationId": "upload_file", "callbacksForAction": "upload_file"}
```

* `callbacksForAction`: The value of this key is a string that specifies a callback action associated with the `upload_file` destination ID. This is part of an event-driven system (Kafka send action) where the system calls this callback after the `upload_file` action completes.
* `destinationId`: The name of the node that receives the reply. `callbacksForAction` holds the name of the parent action: when the reply arrives, the engine runs that action's child actions.


# Append params to parent process
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/append-params-to-parent-process

It is a type of action that allows you to send data from a subprocess to a parent process.

**Why is it important?**  If you are using subprocesses that produce data that needs to be sent back to the main **process**, you can do that by using an **Append Params to Parent Process** action.

> [!NOTE]
>
> This action writes data into the **parent process data model** permanently. To push real-time updates to the parent UI without modifying the data model, use [Send data to user interface](./send-data-to-user-interface) with Target Process set to Parent. For a comparison of all data passing mechanisms, see [Subprocess management - How data flows](../process/subprocess#how-data-flows-between-subprocess-and-parent).

## When to use this action

In a synchronous subprocess (Start Async = OFF on the Start Subprocess action), prefer **Data Mapping** on the Start Subprocess action — it propagates results back to the parent automatically when the subprocess ends, without an extra action.

Append Params to Parent Process is the right choice when:

* **The subprocess runs asynchronously** (Start Async = ON on the Start Subprocess action). The parent doesn't wait for the subprocess to finish, so Data Mapping doesn't apply — the subprocess must push results to the parent itself.
* **The subprocess is long-running** (LLM agents, slow integrations, batch jobs) and you want fire-and-forget execution while the user continues in the UI.

![Main process with two async subprocesses started in parallel before a converging gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/append_param_1.png)

### Combined with Send data to user interface

To both persist the result AND notify the user's UI in a single step, attach two actions to the final node of the async subprocess:

1. **Append Params to Parent Process** — writes the result into the parent's data model.
2. **Send data to user interface** with Target Process set to Parent — pushes a UI update over SSE.

This is the standard pattern for async agent results: data is persisted so downstream nodes can read it, and the user sees the update appear without refreshing.

![Two actions configured on the final node of an async subprocess — Append Params to Parent Process and Send data to user interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/append_param_2.png)

## Configuring an Append params to parent process

After you create a process designed to be used as a [subprocess](../process/subprocess), you can configure the action. To do this, you need to add an **Append Params to Parent Process** on a [**Task node**](../node/task-node) in the subprocess.

The following properties must be configured:

* [Action Edit](#action-edit)
* [Parameters](#parameters)
* [Data to send (for Manual actions)](#data-to-send)

### Action edit

* **Name** — internal identifier for the action. We recommend defining a naming standard so actions are easy to find.
* **Action Type** — set to **Append Params to Parent Process**.

The remaining options are grouped into three columns:

**Trigger**

* **Manual** — when ON, the action runs only after a user triggers it (for example, from a button in a UI Task). When OFF, the action runs automatically as soon as the token reaches the node. For Append Params, leave this OFF in most cases.
* **Repeatable** — when ON, the action can be triggered multiple times.

**Execution**

* **Optional** — automatic actions cannot be optional. Manual actions can be optional or required.
* **Autorun Children?** — when ON, child actions (mandatory and automatic) run immediately after this action finishes.

**Navigation**

* **Allow back to this action** — when ON, the user can return to this action via the back-in-process functionality. The toggle is enabled only when **Manual** is ON. For details, see [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process).

### Parameters

All three fields below are mandatory.

* **Copy from current state** - data that you want to be copied back to the parent process
* **Destination in the parent state** - on what key to copy the param values
* **Show Target Process** - ID of the parent process where the params are written. Set this to `${parentProcessInstanceId}` if the variable was defined when you [started the subprocess](./start-subprocess-action). If this value is missing or cannot be parsed as a process instance ID, the action raises a `MISSCONFIG_SUBPROCESS` incident on the parent process — it does not fail silently.

> [!TIP]
>
> To recap: if you have a **Copy from current state** with a simple **JSON** -`{"age": 17}`, that needs to be available in the parent process, on the `application.client.age` key, you will need to set this field (**Destination in the parent state**) with `application.client`, which will be the key to append to in the parent process.

> [!WARNING]
>
> **The payload always lands at the destination key — don't repeat the key in both fields.** If **Copy from current state** is `{"clickCount": ${clickCount}}` and **Destination in the parent state** is `clickCount`, the parent receives a nested object at `clickCount.clickCount`, not the value at `clickCount`. To write a single value to a top-level parent key, use a raw value reference instead: set **Copy from current state** to `${clickCount}` and **Destination in the parent state** to `clickCount`. Raw references work for numbers, booleans, objects, and arrays; wrap string values in quotes (`"${myKey}"`).
>
> **The action replaces the value at the destination key.** If the destination key already contains a nested object — for example `application.client = {"name": "Alice", "age": 30}` — sending `{"age": 35}` to destination `application.client` overwrites the entire object and `name` is lost. To preserve siblings, write to a destination key that doesn't conflict with existing parent state (for example, `application.subprocessResult.client` instead of `application.client`), or use [Send data to user interface](./send-data-to-user-interface) with Target Process set to Parent for non-destructive updates.

### Data to send

* **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User Task configuration](../node/user-task-node) section)

> [!WARNING]
>
> **Data to send** is configurable only when the **Manual** toggle is ON.

## Example

We have a subprocess that allows us to enter the age of the client on the **data.client.age** key, and we want to copy the value back to the parent process. The key to which we want to receive this value in the parent process is **application.client.age**.

This is the configuration to apply the above scenario:

**Parameters**

* **Copy from current state** - `{"age": ${data.client.age}}` — the JSON payload to send to the parent
* **Destination in the parent state** - `application.client` — the key on the parent where the payload is written. Combined with the payload above, the value lands at `application.client.age`.
* **Show Target Process** - `${parentProcessInstanceId}` — required, identifies the parent process


# Business rules types
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action

A business rule is an action type in FlowX.AI that allows you to configure a script on a BPMN node. It's a way to specify business logic or decision-making processes in a business process.

The script can read and write the data available on the process at the moment the script is executed. For this reason, it is very important to understand what data is available on the process when the script is executed.

Business rules can be attached to a node by using actions with [**action rules**](../actions#business-rules) on them. These can be specified using MVEL expressions, or scripts written in JavaScript, Python, or Groovy.

![Business rule action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/business_rule_action.png)

For more information about supported scripting languages, see the next section:

> [card] [Supported scripts](../../supported-scripts)

You can also test your rules by using the **Test Rule** function.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/test_rule_function.png)

## Configuration

To use a Business Rules Action, follow these steps:

1. **Select a BPMN Task Node**: Choose the BPMN task node to which you want to attach the Business Rules Action. This could be a Service Task, User Task, or another task type that supports actions.
2. **Define the Action**: In the task node properties, configure the "Business Rules Action" field and select the desired language (MVEL, Java, JavaScript or Python).
3. **Write the Business Rule**: In the selected language, write the business rule or decision logic. This rule should take input data, process it, and possibly generate an output or result.
4. **Input and Output Variables**: Ensure that the task node can access the necessary input variables from the BPMN process context and store any output or result variables as needed.
5. **Execution**: When the BPMN process reaches the task node, the attached Business Rules Action is executed, and the defined business rule is evaluated.
6. **Result**: The result of the business rule execution may affect the flow of the BPMN process, update process variables, or trigger other actions based on the logic defined in the rule.

The script's `output` is merged into the existing process data, not written over it: keys the script doesn't write keep their values, and writing `{}` to an existing object changes nothing. To clear a key, set it to `null`. For the full merge rules, see [How output is merged into process data](../../supported-scripts#how-output-is-merged-into-process-data).

### Script engine per rule

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1.**

Each business rule can run on either the current **native** script engine (the 5.9 default) or the legacy **GraalVM** engine, selected per rule. This lets you migrate scripts to native one at a time instead of all at once.

* **Rules created before the move to native** keep running on **GraalVM**, and the engine selector is available so you can switch them to native after testing.
* **New rules** run on **native** by default; the selector only appears for rules that support GraalVM.
* On platforms configured for native-only execution, the selector is hidden and all rules run on native.

Switching a JavaScript rule to the other engine can change the data it writes, because the engines handle `undefined` differently. Test the rule again on the new engine. See [Same JavaScript rule, different output on native and GraalVM](../../supported-scripts#common-pitfalls). For every difference between the engines in one list, follow [Port a script from GraalVM to native](../../supported-scripts#port-a-script-from-graalvm-to-native).

The platform-wide default engine is set separately — see [Supported scripts](../../supported-scripts).

### Script size and execution limits

JavaScript and Python rules that run on the native script engine are bounded by the worker pool limits of the process engine:

| Limit | JavaScript default | Python default | Environment variable |
| - | - | - | - |
| Max input payload size | `1048576` bytes (1 MB) | `1048576` bytes (1 MB) | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` / `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` |
| Execution timeout per script | `5000` ms | `10000` ms | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` / `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` |

The input payload includes the process data passed to the script. A large data model can exceed the payload limit even when the script is short. When this happens, the rule fails with an error stating that the request payload exceeds `maxPayloadSizeBytes`. To fix it, reduce the data passed to the script or ask your platform administrator to raise the limit for the affected language. See [Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration).

Let's take look at the following example. We have some data about the gender of a user and we need to create a business rule that computes the formal title based on the gender:

1. This is how the process instance data looks like before it reaches the business rule:

   ```json theme={"dark"}
   {
       "application" : {
           "client" : 
           {
               "firstName" : "David",
               "surName" : "James",
               "gender" : "M",
               
           }
       }
   }
   ```
2. When the token reaches this node the following script (defined for the business rule) is executed. The language used here for scripting is MVEL.

```java theme={"dark"}
if (input.application.client.gender == 'F') {
    output.put("application", {
        "client": {
            "salutation": "Ms"
        }
    });
} else if (input.application.client.gender == 'M') {
    output.put("application", {
        "client": {
            "salutation": "Mr"
        }
    });
} else {
    output.put("application", {
        "client": {
            "salutation": "Mx"
        }
    });
}
```

3. After the script is executed, the process instance data will look like this:

```json theme={"dark"}
{
    "application": {
        "client": {
            "firstName": "David",
            "surName": "James",
            "gender": "M",
            "salutation": "Mr"
        }
    }
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/mvel_example.gif)

## Flattened vs unflattened keys

> [!WARNING]
>
> With version [**2.5.0**](https://old-docs.flowx.ai/release-notes/v2.5.0-april-2022/) we introduced unflattened keys inside business rules. Flattened keys are now obsolete. You are notified when you need to delete and recreate a business rule so it contains an unflattened key.

![Obsolete business rule](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/obsolete_business_rule.png)

## Business rules examples

> [!TIP]
>
> Examples available for [**v2.5.0**](https://old-docs.flowx.ai/release-notes/v2.5.0-april-2022/) version and higher

We will use the MVEL example used above to rewrite it in other scripting languages formats:

> [tab] MVEL
>
> ```Java theme={"dark"}
> if (input.application.client.gender == 'F') {
>         output.put("application", {
>             "client": {
>                 "salutation": "Ms"
>             }
>          });
>     } else if (input.application.client.gender == 'M') {
>         output.put("application", {
>             "client": {
>                 "salutation": "Mr"
>             }
>          });
>     } else {
>         output.put("application", {
>             "client": {
>                 "salutation": "Mx"
>             }
>         });
>     }
> ```

> [tab] Python
>
> ```python theme={"dark"}
>     if input.get("application").get("client").get("gender") == "F":
>         output.put("application", {
>             "client" : {
>                 "salutation" : "Ms"
>             }
>         })
>     elif input.get("application").get("client").get("gender") == "M":
>         output.put("application", {
>             "client" : {
>                 "salutation" : "Mr"
>             }
>         })
>     else:
>         output.put("application", {
>                 "client" : {
>                     "salutation" : "Mx"
>                 }
>             })
> ```

> [tab] JS
>
> ```js theme={"dark"}
> if (input.application.client.gender === 'F') {
>     output.application = {
>         client: {
>             salutation: 'Ms'
>         }
>     };
> } else if (input.application.client.gender === 'M') {
>     output.application = {
>         client: {
>             salutation: 'Mr'
>         }
>     };
> } else {
>     output.application = {
>         client: {
>             salutation: 'Mx'
>         }
>     };
> }
> ```

> [tab] Groovy
>
> ```groovy theme={"dark"}
> if (input.application.client.gender === 'F') {
> def gender = input.application.client.gender
> switch (gender) {
>     case 'F':
>         output.application = [client: [salutation: 'Ms']]
>         break
>     case 'M':
>         output.application = [client: [salutation: 'Mr']]
>         break
>     default:
>         output.application = [client: [salutation: 'Mx']]
> }
> ```


# Extracting additional data in business rules
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/business-rule-action/extracting-additional-data

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.

Business rules can read more than the process data model: at execution time the platform injects additional runtime data, such as the current user's security details and configuration parameters, that your scripts can extract and use. This page shows how to retrieve security details, extract specific user attributes, and fetch configuration parameters from a business rule.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> **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.

> [tab] In processes
>
> ### Retrieve security details
>
> Use the following business rule to fetch and store security details:
>
> ```JavaScript theme={"dark"}
> // Retrieve security details from additionalData
> securityDetails = additionalData.get("securityDetails");
>
> // Store the extracted security details
> output.put("securityDetails", securityDetails);
> ```
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2813%29.png)
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-25%20at%2013.32.37.png)
>
> Example output:
>
> ```json theme={"dark"}
> {
>     "securityDetails": {
>         "Default": {
>             "owner": {
>                 "username": "user@email.com",
>                 "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600",
>                 "details": {
>                     "firstName": "John",
>                     "lastName": "Snow",
>                     "email": "user@email.com",
>                     "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):
>
> > [tab] JavaScript
> >
> > ```javascript theme={"dark"}
> > // 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);
> > ```
>
> > [tab] Python
> >
> > ```python theme={"dark"}
> > # 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`)
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2814%29.png)
>
> ### Dynamic extraction by swimlane
>
> If your application uses multiple swimlanes, retrieve the owner details dynamically:
>
> ```JavaScript theme={"dark"}
> // 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:
>
> ```json theme={"dark"}
> {
>   "email": "user@email.com",
>   "username": "user@email.com",
>   "firstName": "John",
>   "lastName": "Snow"
> }
> ```

> [tab] 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.
>
> ```javascript theme={"dark"}
> // Retrieve all additional data
> const additionalParams = additionalData;
>
> // Access security details directly
> output.put("securityDetails", additionalParams.securityDetails);
> ```
>
> Example output:
>
> ```json theme={"dark"}
> {
>   "securityDetails": {
>     "username": "user@email.com",
>     "identifier": "f08b1452-7c4c-415c-ad6d-8bb2d2d14600",
>     "details": {
>       "firstName": "John",
>       "lastName": "Snow",
>       "email": "user@email.com",
>       "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) |
>
> > [!NOTE]
> >
> > 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:
>
> > [tab] JavaScript
> >
> > ```javascript theme={"dark"}
> > // 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);
> > ```
>
> > [tab] Python
> >
> > ```python theme={"dark"}
> > # 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 |
>
> > [!WARNING]
> >
> > 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.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2816%29.png)

### Retrieve configuration parameters

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

```JavaScript theme={"dark"}
// 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.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.54.47.png)

#### Configuration parameters

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

> [!TIP]
>
> 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`).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.56.41.png)

**2. Retrieve Commission Percentage from Configuration**

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

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-27%20at%2013.59.57.png)

Business rule used:

```JavaScript theme={"dark"}
// 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:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-27%2014.21.53.gif)

> [!TIP]
>
> 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.


# Kafka send action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/kafka-send-action

The FlowX.AI Designer offers various options to configure the Kafka Send Action through the Actions tab at the node level.

The Kafka send action publishes a message from a process node to a Kafka topic, which is how a process communicates asynchronously with plugins and external systems. You configure it in the **Actions** tab at the node level in the FlowX.AI Designer, in two parts:

* [Action Edit](#action-edit)
* [Parameters](#parameters)

![Kafka Send Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/kafka_send_action_confg.gif)

### Action Edit

* **Name** - Used internally to distinguish between different [actions](../actions/actions) within the process. Establish a clear naming convention for easy identification.
* **Order** - Sets the running order for multiple actions on the same node.
* **Timer Expression** - Enables a delay, using [ISO 8601 duration format](../node/timer-events/timer-expressions#iso-8601) (e.g., `PT30S` for a 30-second delay).
* **Action Type** - Designate as **Kafka Send Action** for sending messages to external systems.
* **Trigger Type** - **Automatic** by default: the action runs when the process reaches the node. Set it to **Manual** to run the action only when it is triggered, for example by a button.

> [!NOTE]
>
> Kafka Send actions are **Automatic** by default. To send the message on a user interaction instead, turn on **Manual** and bind the action to a button through a UI action. For how manual actions work, see [Trigger](../actions/actions#trigger).

* **Required Type** (Mandatory/Optional) - **Automatic** actions are typically set as **mandatory**. Manual actions can be either mandatory or optional.
* **Repeatable** - Allows triggering the action multiple times if required.
* **Autorun Children** - When activated, child actions (mandatory and automatic) execute immediately after the parent action concludes.

### Parameters

You can add parameters via the **Custom** option or import predefined parameters from an integration.

> [!NOTE]
>
> For detailed information on **Integrations management**, refer to [**this link**](../../platform-deep-dive/integrations/integration-designer).

* **Topics** - Specifies the Kafka topics listened to by the external system for requests.
* **Message** - Contains the message payload to be dispatched.
* **Advanced Configuration (Headers)** - Represents a JSON value sent within the Kafka message headers.

![Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/message_send_parameters.png)

## Dynamic Kafka topics

You can use dynamic topic names for Kafka Send and Kafka Receive actions in FlowX.AI processes by leveraging Configuration Parameters. This enables flexibility when working with Kafka topics across different environments or use cases.

Steps to Create Dynamic Kafka Topics:

**1. Define Configuration Parameters for Kafka Topics**

Navigate to **Projects → Your Project → Configuration Parameters** in FlowX.AI Designer.

Add or update configuration keys for Kafka topics.

Example:

* Key: `kafka_send_2`
* Value: `ai.flowx.plugin.document.trigger`
* Key: `kafka_receive`
* Value: `ai.flowx.engine.receive.plugin.document`

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2017.47.57.png)

This allows referencing these parameters dynamically in your Kafka actions.

**2. Use Configuration Parameters in Kafka Send Action**

Open the process where you want to configure the Kafka Send Action.

Go to Node Config > Actions.

Select Kafka Send Action as the action type.

Under Parameters, locate the Topics field.

Use a dynamic reference to concatenate a parameter with another value:

`${kafka_send_2}.${topic2}`

Here:

* `${kafka_send_2}` dynamically pulls the value from Configuration Parameters.
* `${topic2}` can be another dynamic input set within the process.

**3. Configure the Kafka Message Payload**

Define the JSON structure for the message payload.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2018.03.36.png)

Ensure that all required fields align with the expected schema of the consuming system.

**4. Validate and Test the Configuration**

Start the process and check whether messages are correctly sent to the Kafka topic.

If needed, modify the configuration parameters to change the topic dynamically.

## Kafka send action scenarios

The Kafka Send action serves as a versatile tool that facilitates communication across various systems and plugins, enabling efficient data transfer, reliable document management, notifications, and process initiation.

This action finds application in numerous scenarios while configuring processes:

* **Communicating with External Services**
* **Interacting with Connectors** - For example, integrating a connector in the FlowX.AI Designer [here](../../platform-deep-dive/integrations/building-a-connector#integrating-a-connector-in-flowx-ai-designer).
* **Engaging with Plugins:**
  * **Document Plugin:**
    * Generating, uploading, converting, and splitting documents - Explore examples [here](../../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview).
    * Updating/deleting documents - Find an example [here](../../platform-deep-dive/core-extensions/content-management/documents-plugin/deleting-a-file)
    * Optical Character Recognition (OCR) integration - View an example [here](../../platform-deep-dive/plugins/custom-plugins/ocr-plugin#scenario-for-flowx-ai-generated-documents).
  * **Notification Plugin:**
    * Sending notifications - Example available [here](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification) and emails with attachments [here](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments).
    * One-Time Password (OTP) generation and validation - Refer to these examples for [generating](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/generate-otp) and [validating](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/validate-otp) an OTP.
    * Forwarding notifications to external systems - Explore this [example](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/forwarding-notifications-to-an-external-system).
  * **OCR Plugin**
  * **Customer Management Plugin**
  * **Task Management Plugin:**
    * Bulk operations update - Find an example [here](../../platform-deep-dive/core-extensions/task-management/task-management-overview#bulk-updates).
* **Requesting Process Data for Forwarding or Processing** - For example, Data Search [here](../../platform-deep-dive/core-extensions/search-data-service).
* **Initiating Processes** - Starting a process via Kafka. Find examples [here](../../flowx-designer/managing-a-project-flow/starting-a-process).

The Kafka Send action stands as a versatile facilitator, enabling smooth operations in communication, document management, notifications, and process initiation across diverse systems and plugins.


# Send data to user interface
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/send-data-to-user-interface

Push real-time updates from the process to the client over a single long-lived HTTP connection using Server-Sent Events (SSE).

The Send data to user interface action pushes data from the process to the front-end app in real time, over Server-Sent Events (SSE). Use it when a screen must react to something that happened in the process, such as displaying a computed result or refreshing state, without the user reloading anything.

> [!NOTE]
>
> This action pushes data to the **UI only** via SSE. It does not modify the parent process data model. To persist data from a subprocess into the parent process, use [Append Params to Parent Process](./append-params-to-parent-process). For a comparison of all data passing mechanisms, see [Subprocess management - How data flows](../process/subprocess#how-data-flows-between-subprocess-and-parent).

## Configuring a Send data to user interface action

Multiple options are available for this type of action and can be configured via the **FlowX.AI Designer**. To configure a Send data to user interface, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-a-new-node), which has the following configuration options:

* [Action Edit](#action-edit)
* [Parameters](#parameters)
* [Data to send (for Manual actions)](#data-to-send)

### Action Edit

* **Name** — internal identifier for the action. We recommend defining a naming standard so actions are easy to find.
* **Action Type** — set to **Send data to user interface**.

The remaining options are grouped into three columns:

**Trigger**

* **Manual** — when ON, the action runs only after a user triggers it (for example, from a button in a UI Task). When OFF, the action runs automatically as soon as the token reaches the node.
* **Repeatable** — when ON, the action can be triggered multiple times.

**Execution**

* **Optional** — automatic actions cannot be optional. Manual actions can be optional or required.
* **Autorun Children?** — when ON, child actions (mandatory and automatic) run immediately after this action finishes.

**Navigation**

* **Allow back to this action** — when ON, the user can return to this action via the back-in-process functionality. The toggle is enabled only when **Manual** is ON. For details, see [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process).

![Send data to user interface action edit panel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/send_data_UI_1.png)

### Parameters

The following fields are required for a minimum configuration of this type of action:

* **Message Type** — one of four options. Each maps to a distinct SSE `messageType` on the wire:
  * **Default** (sent as `data`) — push a JSON payload to the UI. Most common case.
  * **Action** (sent as `runAction`) — tell the UI to perform an action. The Message must define a `type` field set to one of the supported [action types](../ui-designer/event-handlers#action-types) (`DISMISS`, `ACTION`, `START_PROCESS_INHERIT`, `UPLOAD`, `EXTERNAL`).
  * **General** (sent as `generalData`) — push the process's general data (configured under **Process Settings → General**) to the UI.
  * **Process Metadata** (sent as `processMetadata`) — push process instance metadata to the UI.

> [!WARNING]
>
> To start a new process from a Send data to user interface action, set **Message Type** to **Action** and define a **Message** with the following format:

```json theme={"dark"}
{
  "processName": "demoProcess",
  "type": "START_PROCESS_INHERIT",
  "clientDataKeys":["webAppKeys"],
  "params": {
     "startCondition": "${startCondition}",
     "paramsToCopy": []
     }
}
```

> [!NOTE]
>
> * `paramsToCopy` — choose which keys from the parent process parameters are copied to the subprocess
> * `withoutParams` — choose which keys from the parent process parameters are excluded when copying

* **Message** — the JSON payload to send. You can use constant values and substitutions from process instance data.
* **Replace Values** — toggle next to the Message field, ON by default. When ON, `${...}` placeholders in the message are replaced with the corresponding values from process instance data before the message is sent. When OFF, the message is sent as literal text, with `${...}` placeholders left unresolved. The same toggle appears on other action parameters (for example, on Start Subprocess) and behaves the same way: it controls placeholder substitution for that parameter, before the action executes.
* **Target Process** — the running process instance the message is sent to. Options: **Active process** (`${processInstanceUuid}`) or **Parent process** (`${parentProcessInstanceUuid}`).

> [!NOTE]
>
> When this action runs inside a subprocess (started via [Start Subprocess](./start-subprocess-action), a [Call activity node](../node/call-subprocess-tasks/call-activity-node), or an embedded subprocess), set **Target Process** to **Parent process** to push the message to the user's UI session bound to the parent process.

### Data to send

* **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User task configuration](../node/user-task-node) section)

> [!WARNING]
>
> **Data to send** is configurable only when the **Manual** toggle is ON.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/websocket_data_to_send.gif)

### Send update data example

To send the latest value from the [process instance](../../projects/runtime/active-process/process-instance) data found at `application.client.firstName` key, to the frontend app, you can do the following:

1. Add a **Send data to user interface**.
2. Set the **Message Type** to **Default** (this is default value for `data`).
3. Add a **Message** with the data you want to send:
   * `{ "name": "${application.client.firstName}" }`
4. Choose the **Target Process**.

![Send data to user interface — Message and Target Process configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/send_data_UI_2.png)


# Send notification action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/send-notification-action

Send emails directly from process nodes using the Send Notification action. Supports both new outbound emails and replies to received emails.

## Overview

The Send Notification action enables process nodes to send emails directly through a predefined email connection. It supports two modes:

* **New email mode** - Send a new email to specified recipients
* **Reply mode** - Reply to an email that triggered the process (using data from an [Email Trigger](../../platform-deep-dive/integrations/email-trigger) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) data source)

This differs from the existing [Kafka send](../node/message-send-received-task-node) notification approach in how you configure it, not in how the email is delivered: instead of hand-crafting the request payload in a Kafka send action, you fill in typed fields and the action builds the request for you. Both approaches hand the request to the Notifications Plugin, which sends the email through the email connection set on the notification template, an [Email Sender](../../platform-deep-dive/integrations/email-sender) (SMTP) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) (MS Graph) data source.

> [!NOTE]
>
> Notification templates configured before this feature for Kafka-based sending continue to work without modification.

> [!TIP]
>
> **Recommended for new processes.** The Send Notification action provides typed, validated configuration fields and is the simpler choice for outbound emails. The [Kafka-based sending guide](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments) remains fully supported for existing processes and advanced cases where you need to craft the notification payload yourself.

***

## Prerequisites

Before using the Send Notification action, ensure you have:

1. An [Email Sender](../../platform-deep-dive/integrations/email-sender) (SMTP) or [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) (MS Graph) data source configured in Integration Designer (or a Default Server configured at the environment level)
2. A [notification template](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates) with **Email Server** set to **Predefined Email Connection**

***

## Adding the action

The Send Notification action is available on the following node types:

* [Send Message Task](../node/message-send-received-task-node#send-message-task)
* [Task](../node/task-node)
* [User Task](../node/user-task-node)

To add the action:

1. Select a node in your process definition
2. Open the **Actions** tab
3. Click **Add action**
4. Set **Action type** to **Send Notification**

![Send Notification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/et1.png)

***

## Configuration

### Notification template

**Notification Template** `select` *required*

Select the notification template to use for the email content.

> [!NOTE]
>
> Only notification templates with **Email Server** set to **Predefined Email Connection** appear in this list.

### Data mapping

The **Data Mapping** section contains the email delivery settings, starting with the reply toggle.

**Reply to received emails** `boolean`

Toggle this setting to reply to the email that started the process.

**Default:** OFF

> [!NOTE]
>
> When enabled, the reply is sent only to the original sender unless you configure CC or BCC Receivers. The subject is automatically set to `RE: <original email subject>`.

***

## Reply mode (reply toggle ON)

When **Reply to received emails** is enabled, the action replies to the email that triggered the current process instance. The email is sent to the original sender, and the subject is automatically prefixed with `RE:`.

**Reply to Email Header** `object` *required*

The process variable key that contains the `headerParams` object from the original email received through an [Email Trigger](../../platform-deep-dive/integrations/email-trigger).

**Example:** `${replyField}`

> [!NOTE]
>
> The `headerParams` object includes the `Message-ID` and other headers from the original email, which are required to maintain the email conversation thread.

**Language** `string` *required*

The process variable key that resolves to a language code for the notification template.

**Examples:** `en`, `ro`, `fr`

> [!TIP]
>
> Use a process variable key that resolves to a language code — for example, `"en"` or `"ro"`.

**Attachments** `json`

Optional file attachments. Enter a JSON object (single attachment) or array of JSON objects (multiple), or a process variable that resolves to the same shape.

Each attachment requires:

* `path` — file storage key (for example, `flowx-document-plugin-.../file.pdf`), not a local OS path
* `filename` — name shown to the recipient

**Example:**

```json theme={"dark"}
[{"path": "flowx-document-plugin-.../report.pdf", "filename": "Report.pdf"}]
```

![Attachments field example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/attachments.png)

> [!WARNING]
>
> On SMTP, omitting `filename` results in an unnamed attachment. Always set it.

**Receivers** `string | array` *required*

The recipients for the reply. If left empty, the reply is automatically sent to the original sender (`emailMessage.sender`). Use a process variable or explicit list to override.

**Example:** `${emailMessage.sender}`

> [!TIP]
>
> For multiple addresses, enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

**CC Receivers** `string | array`

CC recipients for the reply email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

> [!WARNING]
>
> Original CC recipients are **not** preserved automatically. If this field is empty, the reply is sent without any CC. To reply-all, pass `${emailMessage.cc}` explicitly (or build your own list).

**BCC Receivers** `string | array`

BCC recipients for the reply email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

> [!NOTE]
>
> BCC recipients from the original email are not visible on incoming messages and cannot be inherited. Set this field explicitly if you need BCCs on the reply.

**Template Data** `object`

Map data sent from the process through the template. Use the JSON editor to define key-value pairs matching the data model in your notification template.

***

## New email mode (reply toggle OFF)

When **Reply to received emails** is turned off, the action sends a new email to the specified recipients.

**Language** `string` *required*

The process variable key that resolves to a language code for the notification template.

**Examples:** `en`, `ro`, `fr`

> [!TIP]
>
> Use a process variable key that resolves to a language code — for example, `"en"` or `"ro"`.

**Attachments** `json`

Optional file attachments. Enter a JSON object (single attachment) or array of JSON objects (multiple), or a process variable that resolves to the same shape.

Each attachment requires:

* `path` — file storage key (for example, `flowx-document-plugin-.../file.pdf`), not a local OS path
* `filename` — name shown to the recipient

**Example:**

```json theme={"dark"}
[{"path": "flowx-document-plugin-.../report.pdf", "filename": "Report.pdf"}]
```

![Attachments field example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/attachments.png)

> [!WARNING]
>
> On SMTP, omitting `filename` results in an unnamed attachment. Always set it.

**Receivers** `string | array` *required*

The recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

**CC Receivers** `string | array`

CC recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

**BCC Receivers** `string | array`

BCC recipients for the email. Enter a JSON array literal (`["a@example.com","b@example.com"]`) or a process variable key that resolves to a list.

**Template Data** `object`

Map data sent from the process through the template. Use the JSON editor to define key-value pairs matching the data model in your notification template.

![Send Notification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/et2.png)

***

## Example: Reply to a customer email

This example shows a complete flow where an incoming email triggers a process, and the process replies to the sender.

**1. Set up the Email Trigger**

Configure an [Email Trigger](../../platform-deep-dive/integrations/email-trigger) data source to monitor incoming emails (for example, `support@company.com`).

**2. Set up the Email Sender**

Configure an [Email Sender](../../platform-deep-dive/integrations/email-sender) data source with SMTP credentials for outbound emails.

**3. Create a notification template**

Create a notification template for the reply email:

1. Set **Email Server** to **Predefined Email Connection**
2. Set **Email Sender** to your Email Sender data source
3. Design the reply content using the template editor

**4. Design the process**

Create a process with:

* A **Message Start Event** configured with the Email Trigger
* Processing nodes for your business logic (for example, classify the email, look up customer data)
* A node with the **Send Notification** action configured in reply mode

**5. Configure the Send Notification action**

On the appropriate node:

1. Set **Action type** to **Send Notification**
2. Select your notification template
3. Toggle **Reply to received emails** to **ON**
4. Set **Reply to Email Header** to the process variable containing the original email's header params (for example, `${replyField}`)
5. Set **Receivers** to `${emailMessage.sender}`
6. Set **Language** to the appropriate language code (for example, `en`)

When an email arrives, the process starts automatically, runs your business logic, and sends a reply to the original sender — maintaining the email conversation thread.

***

## Related resources

> [card] [Email Sender](../../platform-deep-dive/integrations/email-sender)
>
> Configure SMTP connections for sending emails

> [card] [Email Trigger](../../platform-deep-dive/integrations/email-trigger)
>
> Configure IMAP connections to trigger processes from incoming emails

> [card] [Notification Templates](../../platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
>
> Create and manage email notification templates

> [card] [Node Actions](./actions)
>
> Learn about all available action types


# Start integration workflow action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-integration-workflow

The Start Integration Workflow action initiates a configured workflow to enable data processing, transformation, or other tasks across connected systems.

> [!NOTE]
>
> The Start Integration Workflow action is available on **Send Message Task**, **Task**, and **User Task** nodes within BPMN processes.

## Overview

The Start Integration Workflow action allows a BPMN process to trigger an integration workflow, send input data, and receive the workflow output into process data through a Receive Message Task. This enables processes to delegate data fetching, transformations, and external system integrations to lightweight workflows without creating subprocesses.

> [!TIP]
>
> For triggering workflows from **UI Flows** (without a BPMN process), see the [Start Workflow action](../ui-flows#configuring-the-start-workflow-action).

***

## How it works

When a Start Integration Workflow action is triggered:

**1. Input data is sent**

The input data mapped in the action configuration is sent as start variables to the workflow.

**2. Workflow executes**

The integration workflow runs with the provided inputs, executing its configured nodes (REST calls, data transformations, AI operations, etc.).

**3. Output is captured**

Workflow output data is captured in the process instance upon completion, at the location configured on the Receive Message Task's Data Stream.

**4. Process continues**

The BPMN process continues to the next node after the workflow completes.

> [!WARNING]
>
> The process waits for the workflow to complete before continuing. To receive output data, you must add a **Receive Message Task** node after the Send Message Task that triggers the workflow.

### How do the process and the workflow communicate?

Over Kafka. You don't add a Kafka action or pick a topic: each workflow gets its own pair of topics, named after the workflow's ID.

| Direction | Default topic | Who listens |
| - | - | - |
| Process → workflow: the start message, with the mapped input | `ai.flowx.integration.receive.<workflow-id>.in` | Integration Designer, on `ai.flowx.integration.receive.*` |
| Workflow → process: the workflow output | `ai.flowx.engine.receive.<workflow-id>.out` | Process Engine, on `ai.flowx.engine.receive.*` |

The Receive Message Task picks up the output from the second topic. To change the topic patterns or let Integration Designer create these topics automatically, see the [Integration Designer setup guide](/5.9/setup-guides/integration-designer-setup#engine-and-integration-communication-topics).

***

## Configuration

### Selecting a workflow

The workflow search field (**Search workflow by name**) displays:

* All workflows within the current app version
* Any workflows referenced in the app (e.g., via the Library)

### Input mapping

Map process variables to workflow input parameters. By default the action uses data mappers: open **Input Mapping** and map each workflow input to a process data attribute selected as a source path, for example `customer.id` to `customerId`.

With **Legacy mapping** turned on, the input is a JSON template. Placeholders name process data paths from the root of the process data, with no prefix:

```json theme={"dark"}
{
  "customerId": "${customer.id}",
  "requestType": "credit_check"
}
```

### Receiving output

To capture workflow output in your process:

1. Add a **Receive Message Task** node after the node with the Start Integration Workflow action
2. In its **Data Stream** configuration, set the source to **Workflow** and select the workflow
3. Choose where the output lands: map each End node's output with **Output Mapping** (the default), or turn on **Legacy Mapping** and set a single **Key Name**
4. Subsequent nodes can access the output data at the mapped keys

***

## When to use

| Scenario | Recommended Action |
| - | - |
| Call external APIs and return data | Start Integration Workflow |
| Run data transformations | Start Integration Workflow |
| Execute AI operations (extraction, generation) | Start Integration Workflow |
| Multi-step user journeys | Use subprocesses instead |
| Processes requiring state management | Use subprocesses instead |

***

## Related resources

> [card] [Build your first workflow](/5.9/docs/getting-started/building-your-first-workflow)
>
> Tutorial: call a REST API from a workflow and start it from a process

> [card] [Passing data between nodes](../process/passing-data-between-nodes)
>
> How node outputs land in process variables and how downstream nodes read them

> [card] [Integration Designer](../../platform-deep-dive/integrations/integration-designer)
>
> Build and configure integration workflows

> [card] [UI Flows - Start Workflow](../ui-flows#configuring-the-start-workflow-action)
>
> Trigger workflows from UI Flows without BPMN processes

> [card] [Message Events](../node/message-events/message-events)
>
> Learn about Send and Receive Message Task nodes

> [card] [Actions Overview](./actions)
>
> Explore all available action types


# Start new project instance
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-new-project-instance

Initiate a new main process from within an ongoing process to handle isolated use cases across different apps or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)

### Key considerations

* The "Start New Project Instance" action **cannot be configured as a subaction**. It must always be a standalone action.
* This action is exclusively triggered **manually**; automated execution is not supported.

> [!NOTE]
>
> You can launch a new project instance, which will always use the active version of the target application's build at the time of execution.

***

## Common use cases

This action is particularly useful when multiple use cases are managed separately and require isolation between applications. For example:

1. **Customer Profile Management:**
   * Onboarding a power of attorney.
   * Submitting a mortgage request.
   * Enrolling in a credit card program.
     Each of these processes may be managed by different teams and applications, emphasizing the need for separation and flexibility.

2. **Cross-Application Workflow Initiation:**
   A process in one application might require triggering a process in another application with specific parameters. For instance:
   * Initiating an "Onboarding" process (version 2) for a customer directly from the main application.

## Configuring the action

The **Start New Project Instance** action is configured via the **FlowX.AI Designer**. To set it up, navigate to the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-a-new-node).

### Configuration options

#### Action settings

* **Name:** Used internally to distinguish actions on nodes. It’s recommended to define a naming standard for easier identification.
* **Order:** If multiple actions exist on the same node, specify the order in which they run.
* **Timer Expression:** Adds a delay to the action if needed. Use the [**ISO 8601 duration format**](https://www.w3.org/TR/NOTE-datetime) (e.g., `PT30S` for a 30-second delay).
* **Action Type:** Must be set to **Start New Project Instance**.
* **Trigger Type:** Always set to **Manual**.
* **Required Type:**
  * **Mandatory:** Required for automatic actions.
  * **Optional or Mandatory:** Can be used for manual actions.
* **Repeatable:** Check this box if the action can be triggered multiple times.
* **Autorun Children:** Automatically runs child actions (mandatory and automatic) immediately after the parent action completes.
* **Allow Back on This Action:** Enables users to move back in the process flow and redo previous actions. For details, see [Moving a Token Backwards in a Process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process).

> [!NOTE]
>
> The "Start New Project Instance" action is incompatible with subprocess configurations because projects, unlike libraries, are self-contained collections of resources designed to satisfy specific use cases. Libraries provide reusable, lightweight resources and routines, such as error handling or enumerations, and do not manage complex business logic.

#### Parameters

The following parameters must be configured for the action:

* **Project:** Specifies the target project to be initiated.
* **Process:** Selects the process from the list of processes available in all builds.
* **Start with Parameters:** Defines the parameters passed to the new process. These parameters can include:
  * **Customer Name:** Useful for initiating flows tailored to a specific customer.
  * **Copied Data:** Information from the current process that is required to start the target application’s process.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-22%20at%2013.36.55.png)

***

## Key benefits

* **Isolated Process Management:** Supports launching new, isolated processes in separate applications, ensuring flexibility and independence across teams and environments.
* **Active Version Execution:** Ensures that the project instance uses the active build version at the time of initiation, providing consistency in functionality.
* **Parameter Passing:** Enables data transfer between the initiating and target processes, improving operational efficiency.


# Start subprocess action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/start-subprocess-action

A Start subprocess action is an action that allows you to start a subprocess from another (parent) process.

> [!NOTE]
>
> The "Start subprocess" is available only on [User Task](../node/user-task-node) nodes.
> For any other scenarios, you should use the [Call Activity node](../node/call-subprocess-tasks/call-activity-node) instead.

Using **subprocesses** is a good way to split the complexity of your business flow into multiple, simple and reusable processes.

> [!TIP]
>
> Before configuring a Start subprocess action, read [Process design principles](../process/design-principles) for the rules on when to start a subprocess from a User Task action (must be optional, modal-only navigation) and how it differs from a Call Activity.

## Configuring a Start subprocess action

To use a process as a [subprocess](../process/subprocess) you must first create it. Once the subprocess is created, you can start it from another (parent) process. To do this, you will need to add a **Start Subprocess** action to a [**User task**](../node/task-node) node in the parent process or by using a [Call activity node](../node/call-subprocess-tasks/call-activity-node).

Here are the steps to start a subprocess from a parent process:

1. First, create a [process](../process/process-definition) designed to be used as a [subprocess](../process/subprocess).
2. In the parent process, create a **user task** node where you want to start the subprocess created at step 1.
3. Add a **Start subprocess** action to the task node.
4. Configure the **Start Subprocess** action and from the dropdown list choose the subprocess created at step 1.

By following these steps, you can start a subprocess from a parent process and control its execution based on your specific use case.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/process_subprocess1.png)

The following properties must be configured for a **Start subprocess** action:

* [Action Edit](#action-edit)
* [Trigger](#trigger)
* [Execution](#execution)
* [Navigation](#navigation)
* [Select Subprocess](#select-subprocess)
* [Subprocess Options](#subprocess-options)
* [Data Mapping](#data-mapping)
* [Advanced Configuration](#advanced-configuration)
* [Data to send (for Manual actions)](#data-to-send)

### Action edit

* **Name** - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions
* **Action type** - should be set to **Start Subprocess**

### Trigger

* **Manual** - toggle to choose if this action should be triggered manually (triggered by the user) or automatically (when the process flow reaches this step). In most use cases, this will be set to automatic
* **Repeatable** - toggle to enable if the action can be triggered multiple times

### Execution

* **Optional** - automatic actions are mandatory by default. Manual actions can be set as optional by enabling this toggle
* **Autorun Children?** - when this is enabled, the child actions (the ones defined as mandatory and automatic) will run immediately after the execution of the parent action is finalized

### Navigation

* **Allow back to this action** - enables back-in-process functionality that allows you to go back in a business process and redo a series of previous actions in the process. For more details, check [**Moving a token backwards in a process**](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) section

### Select Subprocess

* **Subprocess name** - dropdown to select the process that you want to start as a subprocess. The dropdown displays the available subprocesses in the format `[Workspace]ProcessName`

### Subprocess Options

* **Parallel Multi-Instance** - enables the subprocess to run multiple instances in parallel
* **Start Async** - when enabled, the subprocess will start asynchronously

### Data Mapping

* **Switch to legacy mapping** - toggle to enable legacy data mapping configuration

When legacy mapping is enabled, you can configure:

* **Copy from current state** - if a value is set here, it will overwrite the default behavior (of copying the whole data from the subprocess) with copying just the data that is specified (based on keys). Click the **+** button to add keys and specify the **Output Key** for each
* **Exclude from current state** - specify which fields you want to exclude when copying the data from the parent process to the subprocess (by default all data fields are copied). Click the **+** button to add keys to exclude

> [!NOTE]
>
> Map which data will be sent and received from the subprocess you are starting.

![Start Subprocess Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/start-subprocess-action-config.png)

### Advanced configuration

* **Show Target Process** - toggle to enable the subprocess to communicate with the parent process (the process where this action is configured)

### Data to send

* **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [**User task configuration**](../node/user-task-node) section)

> [!WARNING]
>
> **Data to send** option is configurable only when the action **trigger type** is **Manual**.

## Example

Let's create a main **process**, in this process we will add a user task node that will represent a menu page. In this newly added node we will add multiple subprocess actions that will represent menu items. When you select a menu item, a subprocess will run representing that particular menu item.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_menu1.png)

To start a subprocess, we can, for example, create the following minimum configuration in a user task node (now we configure the process where we want to start a subprocess):

* **Action** - `menu_item_1` - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions
* **Trigger type** - Manual; Optional
* **Repeatable** - yes
* **Subprocess** - `docs_menu_item_1` - the name of the process that you want to start as a subprocess
* **Exclude from current state** - `test.price` - copy all the data from the parent, except the price data
* **Copy from current state** - leave this field empty to copy all the data (except the keys that are specified in the **Exclude from current state** field), if not, add the keys from which you wish to copy the data

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_example2.png)

**Advanced configuration**

* **Target process (parentProcessInstanceId)** - `${processInstanceId}` - current process ID

#### Result

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/subprocess_example.gif)


# Upload file action
Source: https://docs.flowx.ai/5.9/docs/building-blocks/actions/upload-file-action

An Upload File action is an action type that allows you to upload a file to a service available on Kafka.

**Why is it useful?** The action will receive a file (or multiple files) from the frontend and send it to Kafka, and will also attach some metadata.

The Upload File action supports two modes:

> [card] Single file
>
> Used with the [File Upload Button](../ui-designer/ui-component-types/buttons#file-upload-button). The SDK sends a single temp file ID (`{actionName}TempFileId`).

> [card] Multiple files
>
> Used with the [Multiple File Upload](../ui-designer/ui-component-types/multiple-file-upload) component. The SDK sends a list of temp file IDs (`{actionName}TempFileIds`).

The process engine automatically detects which mode to use based on the parameter key present in the process instance data.

## Configuring an Upload file action

Multiple options are available for this type of action and can be configured via the **FlowX.AI Designer**. To configure an Upload File action, use the **Actions** tab at the [task node level](../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node), which has the following configuration options:

* [Action Edit](#action-edit)
* [Back in steps (for Manual actions)](#back-in-steps)
* [Parameters](#parameters)
* [Data to send (for Manual actions)](#data-to-send)
* [UI Configuration](#ui-configuration)

### Action edit

* **Name** - used internally to make a distinction between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions
* **Order** - if multiple actions are defined on the same node, the running order should be set using this option
* **Timer expression** - it can be used if a delay is required on that action. The format used for this is [ISO 8601 duration format ](https://www.w3.org/TR/NOTE-datetime)(for example, a delay of 30 seconds will be set up as `PT30S`)
* **Action type** - should be set to **Upload File**
* **Trigger type** (options are Automatic/Manual) - choose if this action should be triggered automatically (when the process flow reaches this step) or manually (triggered by the user); in most use cases, this will be set to automatic
* **Required type** (options are Mandatory/Optional) - automatic actions can only be defined as mandatory. Manual actions can be defined as mandatory or optional.
* **Repeatable** - should be checked if the action can be triggered multiple times
* **Autorun Children** - when this is switched on, the child actions (the ones defined as mandatory and automatic) will run immediately after the execution of the parent action is finalized

![Upload File action Action Edit settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/01-upload_file_action_edit.png)

### Back in steps

* **Allow BACK on this action** - back in process is a functionality that allows you to go back in a business process and redo a series of previous actions in the process. For more details, check [Moving a token backwards in a process](../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) section.

### Parameters

* **Topics** - the Kafka topic where the file will be posted
* **Document Type** - other metadata that can be set (useful for the [document plugin](../../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview))
* **Folder** - allows you to configure a value by which the file will be identified in the future
* **Advanced configuration (Show headers)** - this represents a JSON value that will be sent on the headers of the Kafka message

### Data to send

* **Keys** - are used when data is sent from the frontend via an action to validate the data (you can find more information in the [User Task configuration](../node/user-task-node) section)

> [!WARNING]
>
> **Data to send** option is configurable only when the action **trigger type** is **Manual**.

## UI configuration

When configuring the event handler that corresponds to the Upload File node action, you must set the **Action Type** to **Upload**. This ensures proper integration between the frontend interface and the backend upload functionality.

![File Upload event handler with Action Type set to Upload](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/10-ui_action_upload.png)

***

## Single vs. multi-file processing

When the Upload File action executes, the process engine checks for two mutually exclusive parameter keys:

| Key pattern | Type | Behavior |
| - | - | - |
| `{actionName}TempFileId` | `String` (single UUID) | **Single-file path** — sends a `DocumentPayload` to Kafka (existing behavior) |
| `{actionName}TempFileIds` | `List<String>` (UUID list) | **Multi-file path** — sends a `BulkDocumentPayload` to Kafka |

If neither key is present, the action returns an error and no Kafka message is published.

### Multi-file Kafka topics

When the multi-file path is triggered, the following dedicated Kafka topics are used:

| Direction | Default topic | Description |
| - | - | - |
| Process engine → document plugin | `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Bulk persist request |
| Document plugin → process engine | `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Per-file persist results |

For multiple files, set the action's **Topics** parameter to the bulk persist topic. To read the results, add a Custom Topic data stream on the bulk results topic to the node.

### Multi-file request payload

```json theme={"dark"}
{
  "documents": [
    {
      "tempFileId": "550e8400-e29b-41d4-a716-446655440000",
      "customId": "119246",
      "documentType": "CONTRACT",
      "shouldOverride": false
    },
    {
      "tempFileId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "customId": "119246",
      "documentType": "CONTRACT",
      "shouldOverride": false
    }
  ]
}
```

> [!NOTE]
>
> `shouldOverride` is always `false` for multi-file uploads. All files share the same `customId` and use `documentType` from the action configuration (typically `BULK`). This means files accumulate — re-uploading adds new documents rather than replacing existing ones.

### Partial success handling

The document plugin processes each file individually. If one file fails, the remaining files continue processing — successfully persisted files are not rolled back. The response includes a per-file status so your process logic can handle partial failures.

### Multi-file reply

The bulk results message lists one entry per file under `documents`, each with its own `downloadPath`, `originalFileName`, and `error`:

```json theme={"dark"}
{
  "documents": [
    {
      "customId": "119246",
      "fileId": "8f14e45f-ceea-467a-9b3c-2c1f0e2a7d10",
      "documentType": "BULK",
      "documentLabel": null,
      "minioPath": "flowx-process-id-119246/{organizationId}/{workspaceId}/119246/15035_BULK.pdf",
      "filePath": "flowx-process-id-119246/{organizationId}/{workspaceId}/119246/15035_BULK.pdf",
      "downloadPath": "internal/files/8f14e45f-ceea-467a-9b3c-2c1f0e2a7d10/download",
      "originalFileName": "acme-brochure.pdf",
      "noOfPages": null,
      "error": null
    }
  ],
  "error": null
}
```

`downloadPath` is relative and `filePath` is a storage path, not a URL. To show each uploaded file, see [Preview files in a collection](../ui-designer/ui-component-types/file-preview#preview-files-in-a-collection).

### Action order

The process engine rejects an action while a mandatory action placed above it on the same node hasn't run. Place the Upload File action above any mandatory manual action, such as the `saveData` action a user task creates, by dragging it in the node's **Actions** list.

***

## Example: single file upload

An example of **Upload File Action** is to send a file to the [document plugin](../../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview). In this case, the configuration will look like this:

**Parameters configuration**

* **Topics (topicName)** - will be set to the Documents plugin persist topic, by default `ai.flowx.plugin.document.trigger.persist.document.v1`
* **Document Type** - metadata used by the document plugin, here we will set it to`BULK`
* **Folder** - the value by which we want to identify this file in the future (here we use the **client.id** value available on the process instance data: `${application.client.id}`

**Advanced configuration**

* **Headers** - headers will send extra metadata to this topic -`{"processInstanceId": ${processInstanceId}, "destinationId": "currentNodeName"}`)

![Upload File action parameters with the persist topic, Document Type, and Folder set to the client ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/02-upload_file_action_params.png)
![Upload File action headers with processInstanceId and destinationId](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/02b-upload_file_action_headers.png)

The Documents plugin reply carries a relative `downloadPath`, not a complete URL. To show the uploaded file in a File Preview, see [Preview an uploaded file](../ui-designer/ui-component-types/file-preview#preview-an-uploaded-file).

***

## Academy courses

> [card] [Upload and Preview Files course](https://academy.flowx.ai/explore/upload-and-preview-files)
>
> Hands-on course covering data stream topics, upload actions, and file preview UI elements


# Call activity node
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/call-subprocess-tasks/call-activity-node

The Call Activity node is a custom node type in the main process that provides advanced options for starting subprocesses.

The call activity node runs another process as a subprocess inside the current one: in sync mode the parent waits for the subprocess to finish before advancing, while in async mode it continues without waiting. Use it to reuse a process across multiple parents or to split a large flow into manageable pieces.

![Call Activity node on the process canvas](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/call-activity-node.png)

> [!NOTE]
>
> **Call activity or embedded subprocess?** On the process canvas, both nodes are rounded rectangles with a box-and-plus icon. A call activity node has a thicker border and a bolder icon. A start embedded subprocess node has the same thin border as other task nodes. In the node palette, they are named **Call Activity** and **Start Embedded Subprocess**. To decide which one a phase needs, see [Call Activity or embedded subprocess](../../process/call-activity-vs-embedded-subprocess).

> [card] [Subprocess](../../process/subprocess)

> [!TIP]
>
> For when to use a Call Activity vs. starting a subprocess from a User Task action, mobile back-navigation behavior, and async mode constraints, see [Process design principles](../../process/design-principles).

> [!NOTE]
>
> **Swimlane constraint**: a subprocess whose UI renders inside the parent process (through a **Parent Process** navigation area) must have **exactly one swimlane**. With multiple swimlanes, the runtime can't render the subprocess in the parent and reports `Could not render subprocess due to multiple swimlanes or missing Parent Process Area` - see the [error glossary](../../../resources/error-glossary#could-not-render-subprocess-due-to-multiple-swimlanes-or-missing-parent-process-area).

The Call Activity node contains a default action for starting a subprocess, which can be started in two modes:

* **Async mode**: The parent **process** will continue without waiting for the subprocess to finish.

> [!NOTE]
>
> Select if this task should be invoked asynchronously. Make tasks asynchronous if they cannot be executed instantaneously, for example, a task performed by an outside service.

* **Sync mode**: The parent process must wait for the subprocess to finish before advancing.

The start mode can be chosen when configuring the call activity.

If the parent process needs to wait for the subprocess to finish and retrieve results, the parent process key that will hold the results must be defined using the *output key* node configuration value.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sync_async.png)

## Calling a subprocess from a library

A Call Activity can start a process that belongs to a library, as long as the library is a dependency of your project. You configure it the same way as a subprocess from your own project:

1. Add the library to your project. See [Adding library dependencies](../../../projects/managing-applications/dependencies#adding-library-dependencies).
2. In the Call Activity's start subprocess action, open the process dropdown. Processes from your own project are listed under **Local**, and processes from each library are listed under the library's name. Select the library process.

Only libraries already added as dependencies appear in the dropdown. You don't choose a library version in the Call Activity: the subprocess runs from the library version that your project's dependency points to. To use a newer version of the library process, [update the dependency](../../../projects/managing-applications/dependencies#updating-dependencies).

## Retrying the parent token

Retrying the parent process token while it sits on a Call Activity node re-executes the node's start subprocess action, starting a **new subprocess instance**. The original subprocess instance isn't resumed or terminated: it remains in its current state alongside the new one. With [parallel multi-instance](#parallel-multi-instance) enabled, retrying the parent token starts a new full set of subprocess instances.

> [!WARNING]
>
> Account for the extra instance when retrying: any work or data in the original subprocess instance is not carried over to the new one.

## Starting multiple subprocesses

### Parallel multi-instance

The Call Activity node can also be used for starting a set of subprocesses that will be started and run at the same time.

This is useful when there is an array of values in the parent process parameters, and a subprocess needs to be started for each element in that array.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/call_activity_parallel_multi_instance.png)

#### Configuration options

When configuring parallel multi-instance on a Call Activity node, you have access to the following configuration options:

* **Input Array**: Declare the array used for subprocess input. Map the array of objects or the keys inside the array of objects to the destination object or its keys from the subprocess.
* **Output Array**: Declare the array used for subprocess output. Map from the subprocess object back to an array of objects in the parent process.
* **Correlation attribute**: The attribute that will be used to correlate subprocess results with parent process data.

#### Data mapping

In the **Data Mapping** section, when **Parallel Multi-instance** is enabled, you can configure:

##### New data mapping

1. **Declare arrays**: Define the arrays used for subprocess input and subprocess output
2. **Input mapping**: In the mapping modal, map the array of objects or the keys inside the array of objects to the destination object or its keys from the subprocess
3. **Output mapping**: Map from the subprocess object back to an array of objects in the parent process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pmi_mapping.png)

##### Legacy mapping

Legacy mapping works using current mechanics in both configuration and runtime, with no changes to existing features.

> [!WARNING]
>
> When you change the arrays in the node configuration and save, any existing mappings for input and output will be automatically deleted.

> [!TIP]
>
> To filter, reshape, or compute over an array inside a mapping (instead of passing it through wholesale), switch the parameter to **function mode** with the **f(x)** icon and use JavaScript on the resolved value. See [Transforming arrays](../../process/data-mappers#transforming-arrays) on the Data mappers page for patterns and the `|| []` fallback.

#### Correlation attribute behavior

When results from parallel subprocesses are returned, the **correlation attribute** determines how the subprocess payload is handled:

* **Update existing element**: When the correlation attribute value from the subprocess payload matches one or more elements in the parent process array, those elements are updated with the subprocess payload
* **Insert new element**: When the correlation attribute value from the subprocess payload doesn't match any records in the parent process array, the payload is inserted as a new element in the array

This allows for flexible data handling where subprocesses can either update existing records or add new ones based on the correlation logic.

#### Output population and incomplete instances

The output array in the parent process populates **incrementally**: each subprocess reports back as it completes, and the parent appends its result right away - results don't wait for the rest of the set. Results arrive in **completion order**, not input-array order; when a **correlation attribute** is configured, each result updates the element matching its correlation key instead of appending.

Until the parent token advances, the accumulated values live in the parent's process data but aren't visible to subsequent nodes or the UI - you can confirm they arrived by inspecting the instance's process data in monitoring.

In **Sync mode**, the parent token advances only when **every** instance in the set completes. A subprocess counts as completed when it **reaches an end node** or is **dismissed**. An instance that ends any other way (ABORTED, TERMINATED, EXPIRED, FAILED) never reports back to the parent, so the parent token keeps waiting - **there is no timeout on the wait** - even though the results of the completed instances are already present in the parent's process data. A partial run isn't recoverable: to get results for all items, run the operation again.

Two configurations end the wait automatically:

* **Expiry time on the parent process definition**: the parent (and, by default, its active subprocesses) moves to EXPIRED at the scheduled moment. The run isn't recovered, but it stops hanging. See [What happens when a process expires](../../process/process-definition#what-happens-when-a-process-expires).
* **An interrupting boundary event (timer, message, or error) on the Call Activity node**: the parent advances on the boundary branch, and the still-active subprocess instances are aborted. Already-finished instances keep their FINISHED status.

An instance reaches **ABORTED** in exactly two cases: an interrupting boundary event on the parent's Call Activity node (as above), or a token reset in the parent from a manual action with back-navigation, which aborts the subprocesses started by the actions being re-executed.

> [!TIP]
>
> For parallel multi-instance sets whose subprocesses depend on external systems (Kafka replies, integrations), configure an **interrupting boundary timer** on the Call Activity node so a single failed instance can't hold the parent indefinitely.

> [!WARNING]
>
> The Retry action isn't available on an aborted subprocess instance, because Retry applies only to ACTIVE tokens. Retrying the parent token starts a new full set of subprocess instances — see [Retrying the parent token](#retrying-the-parent-token).

#### Dismissing unfinished subprocesses

When subprocesses are started in **Sync mode**:

* If the token is advanced due to another action being performed in the process
* Then the subprocesses that haven't finished are automatically dismissed

This ensures that the parent process can continue without waiting indefinitely for subprocesses that may not complete.

### Business rule example

Below is an example of an MVEL business rule used to generate a list of shipping codes:

```java theme={"dark"}
import java.util.*;

def mapValues(shippingCode) {
    return {
        "shippingCode": shippingCode
    }
}

shippingCodeList = [];

shippingCodeList.add(mapValues("12456"));
shippingCodeList.add(mapValues("146e3"));
shippingCodeList.add(mapValues("24356"));
shippingCodeList.add(mapValues("54356"));
output.put("shippingCodeList", shippingCodeList);
```

In this example, the shippingCodeList array contains multiple shipping code maps. Each of these maps could represent parameters for individual subprocesses. The ability to generate and handle such arrays allows the system to dynamically start and manage multiple subprocesses based on the elements in the array, enabling parallel processing of tasks or operations.

To achieve this, select the *parallel multi-instance* option. The *input array* name from the parent process also needs to be specified.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/input_array.png)

> [!NOTE]
>
> When designing such a subprocess that will be started in a loop, remember that the input value for the subprocess (one of the values from the array in the parent process) will be stored in the subprocess parameter values under the key named *item*. This key should be used inside the subprocess. If this subprocess produces any results, they should be stored under a key named *result* to be sent back to the parent process.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/map_new_list.png)

#### Subprocess business rule example

Here's an MVEL business rule for a subprocess that processes shipping codes:

```java theme={"dark"}
import java.util.*;

map = new HashMap();

if (input.item.shippingCode.startsWith("1")) {
    map.package = "Fragile";
} else {
    map.package = "Non-fragile";
}

map.shippingCode = input.item.shippingCode;

output.put("result", map);
```

## Result (one of the subprocess instances)

The result shows the output of a process that has handled multiple shipping codes. The structure is:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/map_new_result.png)

```json theme={"dark"}
{
    "package": "Non-fragile",
    "shippingCode": "54356"
}
```

This contains the result of processing the specific shipping code, indicating additional attributes related to the shipping code (for example, package type) determined during the subprocess execution.


# Start embedded subprocess
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/call-subprocess-tasks/start-embedded-subprocess

The Start Embedded Subprocess node initiates subprocesses within a parent process, allowing for encapsulated functionality and enhanced process management.

## Overview

The Start Embedded Subprocess node enables the initiation of subprocesses within a parent process, offering a range of features and options for enhanced functionality.

![Start Embedded Subprocess node on the process canvas](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/start-embedded-subprocess-node.png)

> [!NOTE]
>
> **Call activity or embedded subprocess?** On the process canvas, both nodes are rounded rectangles with a box-and-plus icon. A call activity node has a thicker border and a bolder icon. A start embedded subprocess node has the same thin border as other task nodes. In the node palette, they are named **Call Activity** and **Start Embedded Subprocess**. To decide which one a phase needs, see [Call Activity or embedded subprocess](../../process/call-activity-vs-embedded-subprocess).

## Usage Considerations

### Data Management

Embedded subprocesses offer advantages such as:

* Segregated sections from a subprocess can be utilized without rendering them over the parent process.
* Data is stored within the parent process instance, eliminating the need for data transfer.
* Embedded subprocesses are visible in the navigation view.

### Runtime Considerations

**Important** runtime considerations for embedded subprocesses include:

* The **child process** must have only **one swimlane**.
* Runtime swimlane permissions are inherited from the parent.
* Certain boundary events are supported on Start Embedded Subprocess node, except for Timer events (currently not implemented).

> [!WARNING]
>
> Embedded subprocesses cannot support multiple swimlanes in the actual implementation.

## Example

Let's explore this scenario: Imagine you're creating a process that involves a series of steps, each akin to a sequential movement of a stepper. Now, among these steps, rather than configuring one step from scratch, you can integrate a pre-existing process, treating it as a self-contained unit within the overarching process.

### Step 1: Design the Embedded Subprocess

**1. Access FlowX.AI Designer**

Log in to the FlowX.AI Designer where you create and manage process flows.

**2. Create a New Process**

Start by creating a new process or selecting an existing process where you want to embed the subprocess.

**3. Navigation Areas**

Design your navigation areas to match your needs.

![Navigation view of a parent process: a stepper with three steps, the Start Embedded Subprocess node assigned to the Offer review step](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-parent-navigation.png)

> [!TIP]
>
> Make sure you allocated all your user tasks into the navigation area accordingly.

**4. Design Subprocess**

Within the selected process, design the subprocess by adding necessary tasks, events and so on. Ensure that the subprocess is contained within **a single swimlane**.

![A process to embed, with a single swimlane named Default](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-child-process.png)

> [!WARNING]
>
> To initiate a process with an embedded subprocess, designate the root Navigation Area of the subprocess as an inheritance placeholder **Parent Process Area** label in the **Navigation Areas**.
> Ensure that the navigation hierarchy within the Parent Process Area can be displayed beneath the parent navigation area within the main process interface.
>
> ![Navigation view of the process to embed: its user task sits under a Parent Process area](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-parent-process-area.png)
>
> > [!TIP]
> >
> > Make sure you allocated all your user tasks into the navigation area accordingly.

### Step 2: Configure Start Embedded Subprocess Node

**1. Add Start Embedded Subprocess Node**

Within the parent process, add a **Start Embedded Subprocess Node** from the node palette to initiate the embedded subprocess.

![Process Nodes palette with the Start Embedded Subprocess and Call Activity nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-node-palette.png)

**2. Specify Subprocess**

Select the node and open **Node details**. In the **Node Config** tab, under **General Config**, enter a **Node name**, optionally choose a **Process Stage**, and select the process to embed from the dropdown below them. Processes from the current project are listed under **Local**. The icon next to the dropdown opens the selected process in a new tab. Click **Save**.

![Node Config tab of a Start Embedded Subprocess node with Node name, Process Stage and the selected process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-node-config.png)

### Step 3: Customize Subprocess Behavior

> [!NOTE]
>
> [**Alternative flows**](../../process/navigation-areas#alternative-flows) configured in the **main process** will also be applied to **embedded subprocesses** if they share the same name.

**1. Customize Data Handling**

Within the subprocess, handle data as needed. Remember that data is stored within the parent process instance when using embedded subprocesses.

**2. Implement Boundary Events**

Implement boundary events within the subprocess if specific actions need to be triggered based on certain conditions.

![Running parent process: the embedded subprocess's screen renders as step 2 of the parent's stepper](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-runtime-step.png)

### Step 4: Test Integration

**1. Test Functionality**

Test the integration of the embedded subprocess within the parent process. Ensure that the subprocess initiates correctly and interacts with the parent process as expected.

**2. Verify Data Flow**

Verify that data flows correctly between the parent process and the embedded subprocess. Check if any results produced by the subprocess are correctly captured by the parent process.

![Parent process with a Start Embedded Subprocess node between two Call Activity nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-parent-process.png)

For further details on other ways of configuring and utilizing subprocesses, refer to the following resources:

> [card] [Subprocess Configuration](../../process/subprocess)

> [card] [Start Subprocess action](../../actions/start-subprocess-action)

> [card] [Process design principles](../../process/design-principles)
>
> Subprocess lifecycle, Call Activity vs. User Task action, async constraints.


# Error events
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/error-events

Error Events expand the capabilities of process modeling and error handling within BPMN processing. These Error Event nodes enhance the BPMN standard and offer improved control over error management.

Error events catch failures on a node so the process can take a recovery path instead of stopping. In FlowX.AI they attach to the boundary of an activity, a task, subprocess, or call activity, they always interrupt the activity they are attached to, and they fire when their configured condition is met.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_events.png)

## Intermediate event - error event (interrupting)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/error_event.png#center)

## Compatibility matrix for Error Events

**Error Events** are used to handle error scenarios within BPMN processes. The following table outlines their compatibility with different node types:

| **Node Type** | **Error Boundary Event** |
| - | - |
| **User Task** | Yes |
| **Service Task** | Yes |
| **Send Message Task** | Yes |
| **Receive Message Task** | Yes |
| **Subprocess** | Yes |
| **Call Activity** | Yes |

## Key characteristics

1. **Boundary of an Activity node or Subprocess:**
   * Error Events can only be used on the boundary of an activity, including subprocesses nodes. They cannot be placed in the normal flow of the process.

2. **Always Interrupt the Activity:**
   * It's important to note that Error Events always interrupt the activity to which they are attached. There is no non-interrupting version of Error Events.

3. **Handling Thrown Errors:**
   * A thrown error, represented by an Error Event, can be caught by an Error Catch Event. This is achieved specifically using an Error Boundary Event, which is placed on the boundary of the corresponding activity.

4. **Using error events on Subprocesses nodes**:
   * An error catch event can be linked to a subprocess, with the error source residing within the subprocess itself, denoted by the presence of an error end event, signifying an abnormal termination of the subprocess.

## Configuring an Error Intermediate boundary event

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_scenario.png)

* **Name**: Assign a name to the event for easy identification.
* **Condition**: Specify the condition that triggers the error event. Various script languages can be used for defining conditions, including:
  * MVEL
  * JavaScript
  * Python

> [!NOTE]
>
> To draw a sequence from an error event node and link it to other nodes, follow these steps: right-click on the node, and then select the option to "Add Sequence."

> [!NOTE]
>
> When crafting a condition, use a predefined key as illustrated below:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/scenario_input.gif)
>
> For instance, in the example provided, we've taken a process key defined on a switch UI element and constructed a user-defined condition like this: `input.application.switch == true`.

* **Priority**: Determine the priority level of this error event in relation to other error events added on the same node.

When multiple error events are configured for a node, and multiple conditions simultaneously evaluate to true, only one condition can interrupt the ongoing activity and advance the token to the next node. The determination of which condition takes precedence is based on the "priority" field.

If the "priority" field is set to "null," the system will randomly select one of the active conditions to trigger the interruption.

> [!NOTE]
>
> * `input.application.switch`: This represents a key to bind a value to the Switch UI element within the "application" part of the "input". It is used in this example to capture input or configuration from a user.
>
> * `==`: This is an equality operator, and it checks if the value on the left is equal to the value on the right.
>
> * `true` is a boolean value, which typically represents a state of "true" or "on."
>
> So, when you put it all together, the statement is checking if the value of the "input.application.switch" is equal to the string "true." If the value of "input.application.switch" is indeed "true" (as a string), the condition is considered true. If the value is anything other than "true," the condition is false and the error is triggered.

### Use case: handling errors during User Task execution

**Description:** This use case pertains to a page dedicated to collecting client contact data. Specifically, it deals with scenarios where users are given the opportunity to verify their email addresses and phone numbers.

> [!TIP]
>
> In this scenario we will create a process to throw an error if an email address is not valid.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/error_execution.png)

#### Example configuration

1. **Error Boundary Event:** We will set an error boundary event associated with a user task.

2. **Error Node:** The node will be responsible to redirect the user to other flows after the user's email address is validated based on the conditions defined.

```java theme={"dark"}
input.application.client.contactData.email.emailAddress  !=  "john.doe@email.com"
```

> [!NOTE]
>
> The expression checks if the email address configured in `application.client.contactData.email.emailAddress` key is not equal to "[john.doe@email.com](mailto:john.doe@email.com)." If they are not the same, it evaluates to true, indicating a mismatch.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_val_v1.png)

3. **Flow Control:** Depending on the outcome of the validation process, users will be directed to different flows, which may involve displaying error modals as appropriate.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/error_email.gif)

***

## Academy courses

> [card] [Debug 101 course](https://academy.flowx.ai/explore/debug-your-process-0)
>
> Learn exception handling, process/token status, error types, and debugging patterns


# Exclusive gateway
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/exclusive-gateway-node

In the world of process flows, decisions play a crucial role, and that's where the Exclusive Gateway comes into play. This tool enables you to create conditional pathways based on data provided.

## Understanding Exclusive (XOR) Gateway

An exclusive gateway (also called XOR gateway) represents a decision point in your process where exactly one outgoing path is selected based on conditions. This is one of the most common routing mechanisms used in business process modeling.

**Core principles of Exclusive Gateways**

When designing decision logic with exclusive gateways, consider these guiding principles:

> [accordion] Exclusive Choices - Only One Path
>
> An exclusive gateway evaluates multiple conditions, but only **one outgoing sequence flow** will be taken - the first condition that evaluates to *true*.

> [accordion] Condition Evaluation - Logic Drives Flow
>
> Each outgoing path from an XOR gateway depends on a condition that evaluates to *true* or *false*.

> [accordion] Condition Compatibility - Avoid Overlap
>
> Overlapping conditions - where multiple paths could match - can lead to **unpredictable routing**. Gateways will select the first matching path, which might not be the correct one.

> [accordion] Which Path Should Be Taken?
>
> This is the essential question behind every XOR gateway: **"Given the input, which path should the process follow?"**

> [accordion] Testing and Validation - Prove It Works
>
> Before deploying a process with an XOR gateway, test it using **realistic data sets** and **edge cases**. Ensure each possible path behaves as expected - and none are silently skipped or broken.

> [accordion] Decision Points - Clear Divergence
>
> Every XOR gateway introduces a **decision point**. Each outgoing sequence flow represents a **distinct outcome** - make sure those outcomes are meaningful and necessary.

> [accordion] Default Path - Don't Leave the Process Hanging
>
> Include a **default path** in the gateway to catch any scenario where none of the defined conditions match. This is especially important when the decision logic depends on external or dynamic data.

> [accordion] Clear Logic - Keep It Understandable
>
> Your conditions should be **simple, explicit, and named clearly**. Avoid nesting complex expressions directly in the gateway when possible - move logic to a service task if needed.

> [accordion] Maintainability - Keep Logic Aligned with Reality
>
> Business rules change. Processes evolve. If your gateway logic doesn't keep up, the process will drift out of sync with how the business actually works.

## Configuring an Exclusive Gateway node

![Exclusive gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_exclusive.png#center)

To configure this node effectively, it's essential to set up both the **input** and **output** sequences within the gateway process.

![Exclusive Gateways single](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_single.png)

Exclusive Gateways single

![Exclusive Gateways multiple](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_multiple.png)

Exclusive Gateways multiple

### General configuration

* **Node name**: Give your node a meaningful name.
* **Can go back**: Enabling this option allows users to revisit this step after completing it.

> [!NOTE]
>
> When a step has "Can Go Back" set to false, all preceding steps become inaccessible.

* [**Stage** ](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node.

![Exclusive gateway configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/excl_gtway.png)

Exclusive Node Config

### Gateway decisions

* **Language**: When configuring conditions, you can use JavaScript, Python, MVEL, or Groovy expressions that evaluate to either **true** or **false**.
* **Conditions**: In the **Gateway Decisions** tab, you can see that the conditions (**if, else if, else**) are already built-in and you can **select** the destination node when the condition is **true**.

> [!WARNING]
>
> The order of expressions matters; the first **true** evaluation stops execution, and the token moves to the selected node.

![Exclusive Gateways Decisions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_gateway_decisions.png)

Exclusive Gateway Decisions

After the exclusive portion of the process, where one path is chosen over another, you'll need to either end each path (as in the example below) or reunite them into a single process (as in the example above) using a new exclusive gateway without any specific configuration.

![Exclusive Gateways Multiple Flows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_gateways_multiple_flows.png)

Exclusive Gateways Multiple Flows

## JavaScript examples

### Getting input from a Switch UI element

Let's consider the following example: we want to create a process that displays 2 screens and one modal. The gateway will direct the token down a path based on whether a switch element (in our case, VAT) is toggled to true or false.

![Exclusive Gateway JavaScript Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_config_example.png)

Exclusive Gateway JavaScript Example

If, during the second screen, the VAT switch is toggled on, the token will follow the second path, displaying a modal.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/vat_on.gif)

After interacting with the modal, the token will return to the main path, and the process will continue its primary flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_flow.png)

**Example configuration**:

* **Language**: JavaScript
* **Expression**:

```javascript theme={"dark"}
input.application.company.vat == true // you can use the same method to access a value for other supported scripts in our platform: MVEL, Python and Groovy
```

> [!NOTE]
>
> Essentially, you are accessing a specific value or property within a structured data object. The format is usually `input.{{key from where you want to access a value}}`. In simpler terms, it's a way to verify if a particular property within your input data structure (`input.application.company.vat` key attached to Switch UI element) is set to the value true. If it is, the condition is met and returns true; otherwise, it returns false.

> [!NOTE]
>
> The `application.company.vat` key corresponds to the switch UI element.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/VAT_key.png)

### Getting input from multiple UI elements

Consider another scenario in which the process relies on user-provided information, such as age and membership status, to determine eligibility for a discount. This decision-making process utilizes multiple conditions, and depending on the input, it may either conclude or continue with other flows.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/xor_example_discount.gif)

**Configuration example**:

![Exclusive Gateway JavaScript Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/exc_config_example.png)

Exclusive Gateway JavaScript Example

> [!NOTE]
>
> In our case, the expressions fields will be populated with the `input.application.client.age` and `input.application.client.membership` keys, which correspond to the user input collected on the initial screen.

Here's how we've configured the rules for our discount eligibility process:

1. Users under 18 with standard membership are not eligible (redirected to not\_eligible\_modal):
   ```
   input.application.client.age < 18 && input.application.client.membership == "standard"
   ```

2. Users 18 or older with standard membership are not eligible due to membership level (redirected to not\_eligible\_membership):
   ```
   input.application.client.age >= 18 && input.application.client.membership == "standard"
   ```

3. Users 18 or older with gold membership qualify for a discount (redirected to discount\_applied):
   ```
   input.application.client.age >= 18 && input.application.client.membership == "gold"
   ```

4. Users 18 or older with platinum membership also qualify for a discount (redirected to discount\_applied):
   ```
   input.application.client.age >= 18 && input.application.client.membership == "platinum"
   ```

5. Any other combinations are sent to needsValidation for further review.

Each rule uses the logical AND operator (&&) to ensure both conditions must be true for the rule to apply. The rules are evaluated in sequence, and the process follows the path of the first matching rule.

The process is visualized as follows:

<video />


# Message catch boundary events
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-catch-boundary-event

Trigger interrupting or non-interrupting boundary events on user tasks when an incoming message is received during a process flow.

**Why is it important?** It empowers processes to actively listen for and capture designated messages during the execution of associated user tasks.

When an event is received, it progresses through the sequence from the intermediate **node**. Multiple intermediate boundary events can exist on the same user task, but only one can be activated at a time.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_boundary_multiple.png)

Message Catch Boundary Events can be categorized by their behavior, resulting in two main classifications:

* [**Interrupting**](#message-catch-interrupting-event)
* [**Non-interrupting**](#message-catch-non-interrupting-event)

## Message catch interrupting event

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_interrupting_event.png#center)

In the case of an Interrupting Message Catch Boundary Event triggered by a received message, it immediately interrupts the ongoing task. The associated task concludes, and the **process flow** advances based on the received message.

* **Use Cases:**
  * Suitable for scenarios where the receipt of a specific message requires an immediate interruption of the current activity.
  * Often used when the received message signifies a critical event that demands prompt attention.

* **Example:**
  * A user task is interrupted as soon as a high-priority message is received, and the process flow moves forward to handle the critical event.

## Message catch non-interrupting event

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/%20message_catch_non_interrupting.png#center)

Contrastingly, a Non-Interrupting Message Catch Boundary Event continues to listen for messages during the execution of the associated task without immediate interruption. The task persists in its execution even upon receiving messages. Multiple non-interrupting events can be activated concurrently while the task is still active, allowing the task to continue until its natural completion.

* **Use Cases:**
  * Appropriate for scenarios where multiple messages need to be captured during the execution of a user task without disrupting its flow.
  * Useful when the received messages are important but do not require an immediate interruption of the ongoing activity.

* **Example:**
  * A user task continues its execution while simultaneously capturing and processing non-critical messages.

## Compatibility matrix for Message Events

**Message Events** can be used in various contexts within BPMN processes. The following table outlines their compatibility with the following nodes:

| **Node Type** | **Message Catch Event - Interrupting** | **Message Catch Event - Non-Interrupting** |
| - | - | - |
| **User Task** | Yes | Yes |
| **Service Task** | Yes | Yes |
| **Send Message Task** | No | No |
| **Receive Message Task** | Yes | Yes |
| **Start Embedded Subprocess** | Yes | Yes |
| **Call Activity** | Yes | Yes |

## Configuring a message catch interrupting/non-interrupting event

#### General config

* **Correlate with Throwing Events** - the dropdown lists all throw events from accessible process definitions

> [!NOTE]
>
> Establishes correlation between the catch event and the corresponding throw event. Selection of the relevant throw event triggers the catch event upon message propagation.

* **Correlation Key** - process key used to correlate received messages with specific process instances

> [!NOTE]
>
> The correlation key associates incoming messages with specific process instances. Upon receiving a message with a matching correlation key, the catch event is triggered.

* **Receive Data (Process Key)** - the catch event can receive and store data associated with the message in a process variable with the specified process key

> [!NOTE]
>
> This received data becomes available within the process instance, facilitating further processing or decision-making.

## Illustrating boundary events (interrupting and non-interrupting)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/boundary_multiple.png)

**Business Scenario:**

A customer initiates the account opening process. Identity verification occurs, and after successful verification, a message is thrown to signal that the account is ready for activation.

Simultaneously, the account activation process begins. If there are issues during activation, they are handled through the interruption process. The overall process ensures a smooth account opening experience while handling potential interruptions during activation, and also addresses exceptions through the third lane.


# Message Start Event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-catch-start-event

Start a process instance when a specific message, incoming email, or incoming webhook is received by the Message Start Event node.

**Why this matters:** The Message Start Event allows a process to be triggered and initiated based on the reception of a specific message, an incoming email, or an external webhook request.

## Configuring a message start event

A Message Start Event is a special event in a process that initiates the start of a process instance upon receiving a specific trigger. It acts as the entry point for the process, waiting for the designated trigger to occur. Once triggered, the process instance is created and begins its execution, following the defined process flow from that point onwards.

> [!WARNING]
>
> To use this type of node with the task management plugin, you must have a service account defined in your identity solution. For more information, see how to [create service accounts using Keycloak](../../../../setup-guides/access-management/configuring-an-iam-solution#process-engine-service-account).

![Message Start Event BPMN symbol: a thin-bordered circle with an envelope inside](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_catch_message_event.png#center)

### General config

**Node name** `string`

The name of the node.

**Process Stage** `dropdown`

Assign a stage to the node, if needed.

***

### Process trigger

The **Trigger Type** determines how the process instance is started. Three options are available: **Internal Throw Message**, **Email Trigger**, and **Incoming Webhook**. Microsoft Outlook mailboxes are selected under **Email Trigger**.

> [tab] Internal Throw Message
>
> Use this trigger type when you want to start a process instance from another process using a [Message Throw Event](./message-intermediate/message-throw-intermediate-event). This is the classic approach for inter-process communication.
>
> ![Internal Throw Message configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm3.png)
>
> **Trigger Type** `enum` *required*
>
> Select **Internal Throw Message** to enable message-based triggering from other processes.
>
> **Correlate with throwing message events** `dropdown`
>
> The message event name that this start event listens for. This must match the event name configured in the corresponding Message Throw Event from the sending process.
>
> **Process Key** `string`
>
> The process key / variable name where incoming message data will be mapped in the started process. The data sent from the throwing process will be available under this key.
>
> > [!NOTE]
> >
> > **Note:** The correlation key field is not available for Message Start Events. Correlation keys are only used for intermediate catch events where a running process instance needs to be identified.
> >
> > The correlation value set on the [Message Throw Event](./message-intermediate/message-throw-intermediate-event) still matters for start events:
> >
> > * A message with an empty correlation value is discarded and starts nothing.
> > * If an instance that was started by the same message name and correlation value is still active, no new instance starts for that process and the platform records an error instead.

> [tab] Email Trigger
>
> Use this trigger type when you want to automatically start a process instance when an email is received. This requires an Email Trigger data source to be configured in Integration Designer.
>
> ![Email Trigger configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm1.png)
>
> **Trigger Type** `enum` *required*
>
> Select **Email Trigger** to enable email-based process triggering.
>
> **Select Email Trigger** `dropdown` *required*
>
> Choose the data source that will initiate this process. The dropdown lists the Email Trigger (IMAP) data sources and the Microsoft Outlook data sources with **Read** or **Read & Send** scope configured in your project.
>
> > [!NOTE]
> >
> > Before using Email Trigger, you must configure an Email Trigger data source in Integration Designer. See [Email Trigger](../../../platform-deep-dive/integrations/email-trigger) for complete setup instructions.
>
> > [!TIP]
> >
> > When an email arrives and triggers the process, the email data (sender, subject, body, attachments, etc.) is automatically mapped to the process instance data. See the [Email Trigger documentation](../../../platform-deep-dive/integrations/email-trigger#email-data-schema) for the complete data structure.

> [tab] Microsoft Outlook
>
> Use a Microsoft Outlook data source when you want to automatically start a process instance when an email is received in a Microsoft Outlook mailbox via the MS Graph API. This requires a Microsoft Outlook data source with **Read** or **Read & Send** scope configured in Integration Designer.
>
> Microsoft Outlook is not a separate trigger type.
>
> **Trigger Type** `enum` *required*
>
> Select **Email Trigger**.
>
> **Select Email Trigger** `dropdown` *required*
>
> Choose the Microsoft Outlook data source that will initiate this process. The dropdown lists Microsoft Outlook data sources with **Read** or **Read & Send** scope next to the IMAP Email Trigger data sources.
>
> > [!NOTE]
> >
> > Before using Microsoft Outlook, you must configure a Microsoft Outlook data source in Integration Designer. See [Microsoft Outlook](../../../platform-deep-dive/integrations/microsoft-outlook-data-source) for complete setup instructions.
>
> > [!TIP]
> >
> > When an email arrives and triggers the process, the email data (sender, subject, body, attachments, headers) is automatically mapped to the process instance data. The `x-ms-graph-message-id` header is included for reply threading. See the [Microsoft Outlook documentation](../../../platform-deep-dive/integrations/microsoft-outlook-data-source#email-data-schema) for the complete data structure.

> [tab] Incoming Webhook
>
> Use this trigger type when you want to start a process instance from an external HTTP POST request. This requires an Incoming Webhook data source to be configured in Integration Designer.
>
> ![Incoming Webhook trigger configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_configured.png)
>
> **Trigger Type** `enum` *required*
>
> Select **Incoming Webhook** to enable webhook-based process triggering.
>
> **Select Webhook** `dropdown` *required*
>
> Choose the Incoming Webhook data source that will initiate this process. The dropdown displays all Incoming Webhook resources configured in your project.
>
> > [!NOTE]
> >
> > Before using Incoming Webhook, you must create an Incoming Webhook data source in Integration Designer. See [Incoming Webhooks](../../../platform-deep-dive/integrations/incoming-webhooks) for complete setup instructions.
>
> > [!TIP]
> >
> > When a webhook request triggers the process, the payload data (body, headers, timestamp) is automatically mapped to the process instance data. See the [Incoming Webhooks documentation](../../../platform-deep-dive/integrations/incoming-webhooks#webhook-payload) for the complete data structure.
>
> > [!NOTE]
> >
> > A Message Start Event always creates a **new** process instance for each request. To push data into a process instance that is **already running** — for example, sending updated credit data into a loan application that is waiting on an external system — use a [Message Catch Intermediate Event](./message-intermediate/message-catch-intermediate-event) with a webhook whose **Webhook Behavior** is set to **Resume a Waiting Process**. See [Incoming Webhooks → On a Message Catch Intermediate Event](../../../platform-deep-dive/integrations/incoming-webhooks#on-a-message-catch-intermediate-event).

> [!WARNING]
>
> When switching between trigger types in the Designer UI, the configuration fields are automatically cleared to prevent invalid configurations. Ensure you reconfigure all required fields after changing the trigger type.

***

## Example: Interprocess communication with internal throw message

This section demonstrates how to use the **Internal Throw Message** trigger type to start a process from another process.

### Throwing process (sender)

The throwing process contains a [Message Throw Event](./message-intermediate/message-throw-intermediate-event) that sends a message to start the target process.

![Throwing process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm4.png)

#### Configuring the throw intermediate event

**Correlate with catch events** `dropdown` *required*

The message event name. This must match the **Correlate with throwing message events** value configured in the target Message Start Event.

**Send data** `string`

Define a JSON structure with the data to be sent along with the message. For example:

```json theme={"dark"}
{"test": "docs"}
```

\*\* Process Stage\*\* `dropdown`

Assign a stage to the node if needed.

![Throw event configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm7.png)

### Catching process (receiver)

The catching process uses a Message Start Event configured with the **Internal Throw Message** trigger type.

![Catching process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm6.png)

#### Configuring the Message Start Event (Start Catch Message) node

> [!NOTE]
>
> Remember, it's mandatory to have a service account defined in your identity solution to have the necessary rights to start a process using the message catch start event. For more information, see how to [create service accounts using Keycloak](../../../../setup-guides/access-management/configuring-an-iam-solution#process-engine-service-account).

![Message Start Event (Start Catch Message) node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm5.png)

### Result

After running the throw process, the process containing the Message Start Event (Start Catch Message) node is triggered automatically. The data sent from the throwing process is available in the new process instance:

![Message Start Event (Start Catch Message) node result](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/scm8.png)

***

## Related resources

> [card] [Message Throw Event](/5.9/docs/building-blocks/node/message-events/message-intermediate/message-throw-intermediate-event)
>
> Send the message that starts the receiver process

> [card] [Message Catch Intermediate Event](/5.9/docs/building-blocks/node/message-events/message-intermediate/message-catch-intermediate-event)
>
> Wait for a message in a process that is already running

> [card] [Starting a process](/5.9/docs/flowx-designer/managing-a-project-flow/starting-a-process)
>
> All the ways a process instance can start

> [card] [Manage Triggers](/5.9/docs/projects/runtime/manage-triggers)
>
> Activate Email Trigger and Incoming Webhook triggers at runtime


# Message Events
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-events

Message events serve as a means to incorporate messaging capabilities into business process modeling. These events are specifically designed to capture the interaction between different process participants by referencing messages.

Message events let processes communicate with each other: a process throws a message and another process, or another part of the same process, catches it, either advancing a waiting flow or starting a new instance.

![Process canvas with six numbered message event examples: Start Message Catch Event, Intermediate Message Throw Event, Intermediate Message Catch Event, interrupting and non-interrupting catch boundary events on user tasks, and a user task with multiple boundary message events](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_events_new.png)

By leveraging message events, processes can pause their execution until the expected messages are received, enabling effective coordination and communication between various system components.

## Intermediate events

| Trigger | Description | Marker |
| - | - | :-: |
| Message | A Message Intermediate Event serves to send or receive messages. A filled marker denotes a "throw" event, while an unfilled marker indicates a "catch" event. This either advances the process or alters the flow for exception handling. Identifying the Participant is done by connecting the Event to a Participant through a Message Flow. | Throw ![Message throw event symbol with a filled envelope](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/throw_message_event.png#center) Catch ![Message catch event symbol with an outlined envelope](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_intermediate_event.png#center) |

## Boundary events

Boundary Events involve handling by first consuming the event occurrence. Message Catch Boundary Events, triggered by incoming messages, can be configured as either interrupting or non-interrupting.

| Trigger | Description | Marker |
| - | - | :-: |
| Message | **Non-interrupting Message Catch Event**: The event can be triggered at any time while the associated task is being performed. | Non-interrupting ![Non-interrupting message catch boundary event attached to a task, drawn with a dashed border](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/%20message_catch_non_interrupting.png#center) |

| Trigger | Description | Marker |
| - | - | :-: |
| Message | **Interrupting Message Catch Event**: The event can be triggered at any time while the associated task is being performed, interrupting the task. | Interrupting ![Interrupting message catch boundary event attached to a task, drawn with a solid border](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_interrupting_event.png#center) |

## Intermediate vs boundary

**Intermediate Events**

* Intermediate events temporarily halt the process instance, awaiting a message.

**Boundary Interrupting Events**

* These events can only be triggered while the token is active within the parent node.

![Process instance with a token waiting on User\_Task\_008, whose interrupting message boundary event is highlighted, and the Tokens tab listing that token as ACTIVE with status EXECUTED\_PARTIAL](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/token_interrupting.png)

* Upon activation, the parent node concludes, and the token progresses based on the boundary flow.

![The same process instance after the boundary event fires: the token for User\_Task\_008 is INACTIVE and the flow continues along the boundary path](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/token_intterrupting_exec.png)

**Boundary Non-Interrupting Events**

* Similar to interrupting events, non-interrupting events can only be triggered while the token is active in the parent node.
* Upon triggering, the parent node remains active, and a new token is generated to execute the boundary flow concurrently.

FlowX.AI works with the following message events nodes:

* [**Message catch start event**](./message-catch-start-event)
* [**Message intermediate events**](./message-intermediate/)
* [**Message catch boundary event**](./message-catch-boundary-event)

## Message events correlation

> [!NOTE]
>
> Catch events are not limited to messages thrown inside FlowX. A Message Start Event or a Message Catch Intermediate Event can also be driven by an external HTTP POST, letting an outside system start a process or resume one that is waiting. See [Incoming Webhooks](../../../platform-deep-dive/integrations/incoming-webhooks) for setup.

Messages are not sent directly to process instances. Instead, message correlation is achieved through two properties that must match between the throw and catch events:

* **Message name** — configured via the "Correlate with catch/throwing events" dropdown, must be identical on both sides
* **Correlation value** — the runtime value extracted from the correlation key expression

> [!NOTE]
>
> A correlation key is an expression that resolves to a value at runtime. The engine extracts this value from the process instance and uses it to match throw and catch events. It is not the key name that matters, but the **value** it resolves to.
>
> For example, if two sibling subprocesses both use `parentProcessInstanceId` as their correlation key, the engine extracts the parent's ID from each — since both share the same parent, the values match and the message is delivered.

### Available correlation keys

The correlation key expression is evaluated against two sources, checked in order:

1. **Instance metadata** — system properties automatically set by the engine:

| Key | Description | Available on |
| - | - | - |
| `processInstanceId` | Numeric ID of the current process instance | All instances |
| `processInstanceUuid` | UUID of the current process instance | All instances |
| `parentProcessInstanceId` | Numeric ID of the parent process | Subprocesses only |
| `parentProcessInstanceUuid` | UUID of the parent process | Subprocesses only |

2. **Process variables** (`paramValues`) — any custom variable stored in the process data model (e.g., `orderId`, `applicationId`, `customer.ssn`)

> [!TIP]
>
> For communication between sibling subprocesses (subprocess → subprocess), use `parentProcessInstanceId` since both siblings share the same parent. Alternatively, pass a custom business key from the parent process to both subprocesses.

### Timing requirement

> [!WARNING]
>
> The catch event must be in a **waiting state** (its token must have arrived on the node) **before** the throw event fires. If the throw executes before the catch is ready, the message will not be delivered and correlation will fail.
>
> When using async subprocesses, ensure the subprocess containing the catch event has enough time to reach the catch node before the throw event is triggered in another subprocess.

The communication works as follows: you receive a message on a Kafka topic - `${kafka.topic.naming.prefix}.core.message.event.process${kafka.topic.naming.suffix}`. The engine listens here and writes the response.

## Message events configuration

* `attachedTo`: a property that applies to boundary events
* `messageName`: a unique name at the database level, must be the same for throw and catch events (configured via the "Correlate with" dropdown in the Designer)
* `correlationKey`: an expression that resolves to a value used to match the throw event with the correct catch event instance
* `data`: allows defining the JSON message body mapping as output and input

### Data example

```json theme={"dark"}
{
	"document":{
			"documentId": "${document.id}",
			"documentUrl": "${document.url}"
	}
}
```


# Intermediate message events in business processes
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-intermediate/example-intermediate-message-events

Orchestrate information exchange and synchronize stages within a process using Intermediate Message Events.

* [Throw and catch on sequence - credit card request process example](#throw-and-catch-on-sequence---credit-card-request-process-example)
* [Throw and catch - interprocess communication](#interprocess-communication-with-throw-and-catch-events)

## Throw and catch on sequence - Credit card request process example

### Business scenario

In the following example, we'll explore a credit card request process that encompasses the initiation of a customer's request, verification based on income rules, approval or rejection pathways, and communication between the client and back office.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_catch_intermediate_process.png)

#### Activities

##### Default swimlane (client)

* **Start Event:** Marks the commencement of the process.
* **User Task 1:** Customer Requests New Credit Card - Involves the customer submitting a request for a new credit card.
* **Exclusive Gateway:** The process diverges based on the verification result (dependent on income rules).
  * **Path A (Positive Verification):**
    * **User Task 2:** Approve Credit Card Application - The bank approves the credit card application.
    * **End Event:** Denotes the conclusion of the process for approved applications.
  * **Path B (Negative Verification):**
    * **Parallel Gateway Open:** Creates two parallel zones.
    * **First Parallel Zone:**
      * **User Task 3:** Reject Credit Card Application - The bank rejects the credit card application.
      * **Message Throw Intermediate Event:** Signals the rejection, throwing a message to notify the back office department.
      * **End Event:** Signifies the end of the process for rejected applications.
    * **Second Parallel Zone:**
      * **User Task 3:** Reject Credit Card Application - The bank rejects the credit card application.
      * **Message Catch Intermediate Event:** The back office department is notified about the rejection.
      * **Send Message Task**: A notification is sent via email to the user about the rejection.
      * **End Event:** Signifies the end of the process for rejected applications.

##### Backoffice swimlane

* **Message Catch Intermediate Event:** The back office department awaits a message to proceed with credit card issuance.
* **Send Message Task:** Send Rejection Letter - Involves sending a rejection letter to the customer.

### Sequence flow

```mermaid theme={"dark"}
graph TD

  subgraph Default Swimlane
    StartEvent[Start Process]
    UserTask1[User Task 1: Customer Requests New Credit Card]
    Gateway1{Exclusive Gateway}
    UserTask2[User Task 2: Approve Credit Card Application]
    endA[End Event: End approved scenario]
    ParallelGateway{Parallel Gateway}
    UserTask3A[User Task 3: Reject Credit Card Application]
    MessageThrow[Message Throw Intermediate Event: Throwing a message to notify the back office department.]
    Gateway2{Close Parallel}
    endC[End Event: Signifies the end of the process for rejected applications.]
  end

  subgraph Backoffice Swimlane
    MessageCatch
    SendEmailTask
  end

  StartEvent -->|Start Process| UserTask1
  UserTask1 -->|Income Verification| Gateway1
  Gateway1 -->|Positive Verification| UserTask2
  UserTask2 -->|Approved| endA
  Gateway1 -->|Negative Verification| ParallelGateway
  ParallelGateway -->|First Parallel Zone| UserTask3A
  UserTask3A -->|Credit Card Rejected| MessageThrow
  MessageThrow --> Gateway2 -->|Second Parallel Zone| MessageCatch
  MessageCatch --> SendEmailTask
  SendEmailTask --> Gateway2
  Gateway2 -->|End| endC

```

### Message flows

A message flow connects the Message Throw Intermediate Event to the Message Catch Intermediate Event, symbolizing the communication of credit card approval from the credit card approval task to the back office department.

In summary, when a customer initiates a new credit card request, the bank verifies the information. If declined, a message is thrown to notify the back office department. The Message Catch Intermediate Event in the back office awaits this message to proceed with issuing and sending the rejection letter to the customer.

### Configuring the BPMN process

To implement the illustrated BPMN process for the credit card request, follow these configuration steps:

**Step 1**

**FlowX.AI Designer**: Open FlowX.AI Designer.

**Step 2**

**Draw BPMN Diagram**: Import the provided BPMN diagram into FlowX.AI Designer or recreate it by drawing the necessary elements.

**Step 3**

**Customize Swimlanes**: Set up the "Default" and "Backoffice" swimlanes to represent different departments or stakeholders involved in the process. This helps visually organize and assign tasks to specific areas.

**Step 4**

**Define User Tasks**: Specify the details for each user task. Configure User Task 1, User Task 2, and User Task 3 with appropriate screens.

* **User Task 1** - *customer\_request\_new\_credit\_card*

> [!TIP]
>
> We will use the value from `application.income` key added on the slider UI element to create an MVEL business rule in the next step.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task1_interm.gif)

* **User Task 2** - *approve\_credit\_card\_request*

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task2_interm.gif)

In this screen, we configured a modal to display the approval confirmation. The modal acts as a single brief interruption before the process advances, not as a step in the main flow. See [Process design principles](../../../process/design-principles#modal-design) for when a modal is appropriate.

* **User Task 3** - *reject\_credit\_card\_request*

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task3_interm.gif)

**Step 5**

**Configure Gateways**: Adjust the conditions for the Exclusive Gateway based on your business rules. Define the conditions for positive and negative verifications, guiding the process down the appropriate paths.

> [!TIP]
>
> In our example, we used an MVEL rule to determine eligibility based on the income of the user. We used the `application.income` key configured in the first user task to create the rule.

![MVEL Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/mvel_example_gateway.png)

Also, add Parallel gateways to open/close parallel paths.

![Parallel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/parallel_open_close.gif)

**Step 6**

**Set Message Events**: Configure the Message Throw and Message Catch Intermediate Events in the "Default" and "Backoffice" swimlanes, respectively. Ensure that the Message Catch Intermediate Event in the "Backoffice" swimlane is set up to wait for the specific message thrown by the Message Throw event. This facilitates communication between different stages of the process.

**Step 7**

**Define End Events**: Customize the End Events for approved and rejected applications in the "Default" swimlane. Also, set an end event in the "Backoffice" swimlane to indicate the completion of the back-office tasks.

**Step 8**

**Configure Send Message Task**: Set up the Send Message Task in the "Backoffice" swimlane to send a rejection letter as a notification to the user.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/sending_a_notification.png)

Define the content of the rejection letter, the method of notification, and any additional details required for a smooth user experience. More details on how to configure a notification can be found in the following section:

> [card]
>
> [**Sending a notification**](../../../../platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification)

**Step 9**

**Validate and Test**: Validate the BPMN diagram for correctness and completeness. Test the process flow by simulating different scenarios, such as positive and negative verifications.

### Configuring intermediate message events

Configuring message events is a crucial step in orchestrating effective communication and synchronization within a business process. Whether you are initiating a message throw or awaiting a specific message with a catch, the configuration process ensures information exchange between different components of the process.

In this section, we explore the essential steps and parameters involved in setting up message events to optimize your BPMN processes.

### Message throw intermediate event

A Message Throw Intermediate Event is an event in a process where a message is sent to trigger communication or action with another part of the process (can be correlated with a catch event). It represents the act of throwing a message to initiate a specific task or notification. The event creates a connection between the sending and receiving components, allowing information or instructions to be transmitted. Once the message is thrown, the process continues its flow while expecting a response or further actions from the receiving component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_intrmdt.png)

#### General Configuration

* **Can go back?** - Setting this to true allows users to return to this step after completing it. When encountering a step with `canGoBack` false, all steps found behind it will become unavailable.

* **Correlate with catch message events** — The dropdown contains all catch messages from the process definitions accessible to the user. In our example: `throwcatchsequenceloan`

> [!NOTE]
>
> It is imperative to define the message for the catch event first. This ensures its availability in the dropdown menu when configuring the throw intermediate event.

* **Correlation Key** — A business or process variable that identifies the target instance. In our example, we used `processInstanceId`, automatically available in instance metadata at runtime.

* **Send data** — Define a JSON structure with the data to transmit alongside the message. In this example, we used dynamic data from user input bound to a slider UI element.

```json theme={"dark"}
{"value": "${application.income}"}
```

* **Stage** - Assign a stage to the node.

In the end, this is what we have:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_throw_config.png)

### Message catch intermediate event

A Message Catch Intermediate Event is a type of event in a process that waits for a specific message before continuing with the process flow. It enables the process to synchronize and control the flow based on the arrival of specific messages, ensuring proper coordination between process instances.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt.png)

#### General Configuration

* **Can go back?** - Setting this to true allows users to return to this step after completing it. When encountering a step with `canGoBack` false, all steps found behind it will become unavailable.
* **Correlate with throwing message events** — Must match the message name configured on the corresponding throw event. In our example: `throwcatchsequenceloan`
* **Correlation Key** — Must resolve to the same value as the throw event's correlation key at runtime.
* **Process Key** — The process key where the data received from the throw event will be stored.
* **Stage** - Assign a stage to the node.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt_cfg.png)

### Testing the final result

After configuring the BPMN process and setting up all the nodes, it is crucial to thoroughly test the process to ensure its accuracy and effectiveness.

> [!NOTE]
>
> We will test the path where the user gets rejected.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/testing_the_proc_interm.gif)

In the end, the user will receive this notification via email:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/notification_received.png)

## Interprocess communication with throw and catch events

Facilitate communication between different processes by using message intermediate events.

### Business scenario

Consider a Bank Loan Approval process where the parent process initiates a loan application. During the execution, it throws a message to a subprocess responsible for additional verification.

#### Activities

**Parent Process:**

* **Start Event:** A customer initiates a loan application.
* **Start Subprocess:** Initiates a subprocess for additional verification.
* **User Task:** Basic verification steps are performed in the parent process.
* **Throw Message:** After the basic verification, a message is thrown to indicate that the loan application is ready for detailed verification.
* **End Event:** The parent process concludes.

**Subprocess:**

* **Start Event:** The subprocess is triggered by the message thrown from the parent process.
* **Catch Message:** The subprocess catches the message, indicating that the loan application is ready for detailed verification.
* *(Perform Detailed Verification and Analysis)*
* **End Event:** The subprocess concludes.

### Sequence flow

```mermaid theme={"dark"}
graph TD
  subgraph Parent Process
    a[Start]
    b[Start Subprocess]
    c[Throw message to another process]
    d[User Task]
    e[End]
  end

  subgraph Subprocess
    f[Start]
    g[Catch event in subprocess]
    h[End]
  end

  a --> b --> c --> d --> e
  f --> g --> h
  c --> g
```

### Message flows

* The parent subprocess triggers the subprocess run node, initiating the child process.
* Within the child process, a message catch event waits for and processes the message thrown by the parent subprocess.

### Configuring the parent process (throw event)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_and_catch_subpr.png)

**Step 1**

\*\*Open **FlowX.AI Designer** and create a new process.

**Step 2**

**Add a User Task for user input**.

* Within the designer interface, add a "User Task" element to collect user input. Configure the user task to capture the necessary information that will be sent along with the message.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/user_task_loan_subrp.gif)

**Step 3**

**Integrate a [**Call activity**](../../../node/call-subprocess-tasks/call-activity-node) node**.

* Add a "Subprocess Run Node" and configure it:

  * **Start Async** - Enable this option. When subprocesses are initiated in async mode, the parent process continues without waiting for completion. The parent process then manages the reception of process data from the child via catch message events.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/subprocess_run_node_cfg.png)

* Add and configure the "Start Subprocess" action:

  * **Parameters**:
    * **Subprocess name** - Specify the name of the process containing the catch message event.
    * **Branch** - Choose the desired branch from the dropdown menu.
    * **Version** - Indicate the type of version to be utilized within the subprocess.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_subprocess_configuration.png)

For a more comprehensive guide on configuring the "Start Subprocess" action, refer to the following section:

[Start Subprocess action](../../../../building-blocks/actions/start-subprocess-action)

**Step 4**

**Insert a Throw Event for Message Initiation**.

* Add a "Throw Event" to the canvas, indicating the initiation of a message.
* Configure the throw message intermediate event node:

  * **Correlate with catch message events** — The dropdown contains all catch messages from the process definitions accessible to the user. In our example: `throwcatchDocs`

  * **Correlation Key** — A business or process variable that identifies the target instance. In our example, we used `processInstanceId`, which is automatically available in instance metadata at runtime.

  * **Send data** — Define a JSON structure with the data to transmit alongside the message. In this example, we used dynamic data from user input bound to slider UI elements.

```json theme={"dark"}
{
  "client_details": {
    "clientIncome": ${application.income},
    "loanAmount": ${application.loan.amount},
    "loanTerm": ${application.loan.term}
  }
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/throw_in_anthr_proc.png)

### Configuring the subprocess (catch event)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/catch_from_anthr_proc.png)

**1. Insert an Intermediate Message Catch event**

Configure the node:

* **Correlate with throwing message events** — Use the same message name added for the associated throw message event.
* **Correlation Key** — Set to `parentProcessInstanceId`. Since this is a subprocess, the engine extracts the parent's process instance ID, which matches the `processInstanceId` value extracted by the throw event in the parent process.
* **Process Key** — The process key where the data received from the throw event will be stored.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/catch_interm_from_anthr_prc.png)

**2. Integrate a Service Task**

* Integrate and Fine-Tune a Service Task for Additional Verification.

* Incorporate a service task to execute the additional verification process. Tailor the configuration to align with your preferred method of conducting supplementary checks.

***

## Subprocess-to-subprocess communication

Facilitate communication between sibling subprocesses (two subprocesses started from the same parent process) using message intermediate events.

### Business scenario

Consider a process where a parent process starts two subprocesses: one for document verification and another for fraud checks. Once the fraud check subprocess completes its analysis, it sends a message to the document verification subprocess with the results.

```mermaid theme={"dark"}
graph TD
  subgraph Parent Process
    a[Start]
    b["Call Activity 1 (async) → Fraud Check"]
    c["Call Activity 2 → Document Verification"]
    d[End]
  end

  subgraph "Subprocess A: Fraud Check"
    e[Start]
    f[Perform Fraud Analysis]
    g["Throw Message (fraud results)"]
    h[End]
  end

  subgraph "Subprocess B: Document Verification"
    i[Start]
    j["Catch Message (wait for fraud results)"]
    k[Continue Verification with Fraud Data]
    l[End]
  end

  a --> b --> c --> d
  e --> f --> g --> h
  i --> j --> k --> l
  g -.->|message| j
```

### Correlation key for sibling subprocesses

Since both subprocesses are started from the same parent, they share the same `parentProcessInstanceId`. Use this as the correlation key on both throw and catch events:

* **Throw event** (in Fraud Check subprocess): **Correlation Key** = `parentProcessInstanceId`
* **Catch event** (in Document Verification subprocess): **Correlation Key** = `parentProcessInstanceId`

At runtime, both resolve to the same value (the parent's process instance ID), so the engine can match them.

> [!TIP]
>
> Alternatively, you can pass a custom business key (e.g., `applicationId`) from the parent to both subprocesses and use that as the correlation key.

### Timing: catch must be waiting before throw fires

> [!WARNING]
>
> The catch event must reach its waiting state **before** the throw event executes. If the throw fires first, there is no registered listener to receive the message and correlation will fail.
>
> **Common pitfall with async subprocesses:** If Call Activity 1 is set to **Start Async**, it launches Subprocess A without waiting for it to complete, and the parent immediately starts Call Activity 2 (Subprocess B). If Subprocess A reaches its throw event before Subprocess B reaches its catch event, the message is lost.
>
> **Solutions:**
>
> * Ensure the subprocess with the **catch** event starts **first** (or has enough lead time to reach the catch node)
> * Add a timer or additional tasks before the throw event to give the catch event time to register
> * Reverse the logic: place the catch in the subprocess that starts first (async), and the throw in the one that starts second

***

### Throw with multiple catch events

> [card] [Throw with multiple catch events example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Throw%20with%20multiple%20catch%20events.pdf)
>
> Download the example


# Message catch intermediate event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-intermediate/message-catch-intermediate-event

A Message Catch Intermediate Event is a type of event in a process that waits for a specific message before continuing with the process flow.

The message catch intermediate event pauses a process until a specific message arrives, then resumes the flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/message_catch_intermediate_event.png#center)

**Why this matters:** It enables the process to synchronize and control the flow based on the arrival of specific messages, ensuring proper coordination between process instances.

Similar to the message catch boundary event, the message catch intermediate event is important because it facilitates the communication and coordination between process instances through messages. By incorporating this event, the process can effectively synchronize and control the flow based on the arrival of specific messages.

> [!NOTE]
>
> Message Catch Intermediate Event can be used as a standalone node, this means that it will block a process until it receives an event.

## Configuring a message catch intermediate event

Imagine a process where multiple tasks are executed in sequence, but the execution of a particular task depends on the arrival of a certain message. By incorporating a message catch intermediate event after the preceding task, the process will pause until the expected message is received. This ensures that the subsequent task is not executed prematurely and allows for the synchronization of events within the process.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt.png)

### Trigger type

A message catch intermediate event can be driven by one of two trigger types:

| Trigger type | Use it when… |
| - | - |
| **Internal Throw Message** | Another node inside FlowX — typically a [Message Throw Intermediate Event](./message-throw-intermediate-event) elsewhere in the process — sends the resume signal. |
| **Incoming Webhook** | An external system resumes the process over HTTP. See [Incoming Webhooks → On a Message Catch Intermediate Event](../../../../platform-deep-dive/integrations/incoming-webhooks#on-a-message-catch-intermediate-event) for setup. |

The rest of this page covers the **Internal Throw Message** configuration. For the **Incoming Webhook** flow (Data Source, Webhook Correlation Key, Process Correlation Key, Process Key), follow the Incoming Webhooks page.

#### General config

**Correlate with throwing message events** `dropdown` *required*

Select the throw message event that this catch event should listen for. The dropdown contains all throw messages from the process definitions accessible to the user.

> [!NOTE]
>
> The message name must match exactly between the throw and catch events for correlation to work.

**Correlation Key** `string` *required*

A business or process variable that uniquely identifies the process instance to which the message is sent.

The engine extracts the value of this key when the token arrives on the catch node. At runtime, the extracted value must match the value extracted by the corresponding throw event.

Common correlation key examples:

* `processInstanceId` — to correlate within the same process
* `parentProcessInstanceId` — to receive messages from a parent process or to communicate between sibling subprocesses that share the same parent
* Custom business keys like `orderId`, `applicationId`, etc.

**Process Key** `string`

The process key where the data received from the throw event will be stored. This allows the catch event to capture and use the payload sent along with the message.

> [!WARNING]
>
> The catch event must be in a **waiting state** before the corresponding throw event fires. If the throw executes before the catch node is reached, the message will not be delivered. This is especially important when working with async subprocesses — ensure the subprocess containing the catch event has time to reach the catch node before the throw fires.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_catch_intrmdt_cfg.png)


# Message intermediate events overview
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-intermediate/message-intermediate

Overview of BPMN message intermediate events for throwing and catching messages within process flows.

An intermediate event is an occurrence situated between a start and an end event in a process or system. It is represented by a circle with a double line. This event can either catch or throw information, and the directional flow is indicated by connecting objects, determining whether the event is catching or throwing information.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/intermediate_message_events.png)

### Message throw intermediate event

This event throws a message and continues with the process flow.
It enables the sending of a message to a unique destination.

> [card] [Message Throw Intermediate Event](./message-throw-intermediate-event)

### Message catch intermediate event

This event waits for a message to be caught before continuing with the process flow.

> [card] [Message Catch Intermediate Event](./message-catch-intermediate-event)


# Message throw intermediate event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-events/message-intermediate/message-throw-intermediate-event

A Message Throw Intermediate Event is an event in a process where a message is sent to trigger communication or action with another part of the process. It represents the act of throwing a message to initiate a specific task or notification.

The message throw intermediate event sends a message from a running process, to a catch event in another process or to start a new process instance, and then continues the flow without waiting for a reply.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/throw_message_event.png#center)

**Why this matters:** The Message Throw Intermediate Event enables communication between different parts of a process or between separate processes entirely. It allows you to send data and trigger actions in other process instances, making it essential for coordinating complex workflows.

## Configuring a message throw intermediate event

A Message Throw Intermediate Event sends a message that can be correlated with a catch event—either a [Message Catch Intermediate Event](./message-catch-intermediate-event) in a running process or a [Message Start Event](../message-catch-start-event) to initiate a new process instance. The event creates a connection between the sending and receiving components, allowing information or instructions to be transmitted. Once the message is thrown, the process continues its flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mti2.png)

### General config

**Correlate with catch message events** `dropdown` *required*

Select the catch message event that this throw event should communicate with. The dropdown contains all catch messages from the process definitions accessible to the user.

> [!NOTE]
>
> Define the message for the catch event first. This ensures its availability in the dropdown menu when configuring the throw intermediate event.

**Correlation Key** `string` *required*

A business or process variable that uniquely identifies the instance to which the message is sent. The engine extracts the value of this key at runtime and uses it to find a matching catch event listener.

Common correlation key examples:

* `processInstanceId` — to correlate within the same process
* `parentProcessInstanceId` — to communicate between a parent and subprocess, or between sibling subprocesses that share the same parent
* Custom business keys like `orderId`, `applicationId`, etc.

**Send data** `object`

Define a JSON structure with the data to be sent along with the message. You can use dynamic values from the process data using the `${}` syntax.

Example:

```json theme={"dark"}
{
  "customerName": "${customer.name}",
  "applicationStatus": "${application.status}",
  "amount": ${application.amount}
}
```

\*\* Process Stage\*\* `dropdown`

Assign a stage to the node if needed. Stages help organize and track process progress.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mti1.png)

***

> [!WARNING]
>
> The corresponding catch event must be in a **waiting state** before this throw event fires. If the throw executes before the catch node is reached, the message will not be delivered and correlation will fail. This is especially important when working with async subprocesses.

## Use cases

### Correlating with a running process instance

Use the Message Throw Intermediate Event to send data to a [Message Catch Intermediate Event](./message-catch-intermediate-event) that is waiting in another part of the same process or in a different running process instance.

> [!NOTE]
>
> Both the throw and catch events must have matching:
>
> * **Message name** (selected in **Correlate with catch message events** / **Correlate with throwing message events**)
> * **Correlation key value** at runtime

### Starting a new process instance

Use the Message Throw Intermediate Event to trigger a [Message Start Event](../message-catch-start-event) and start a new process instance. In this case, no correlation key is needed on the catch side since a new process instance is always created.

> [!TIP]
>
> For detailed examples of interprocess communication using throw and catch events, see [Intermediate Message Events Examples](./example-intermediate-message-events).

***

## Related documentation

> [card] [Message Catch Intermediate Event](./message-catch-intermediate-event)
>
> Learn how to configure catch events that receive messages from throw events.

> [card] [Message Start Event](../message-catch-start-event)
>
> Trigger new process instances using messages from throw events.

> [card] [Intermediate Message Events Examples](./example-intermediate-message-events)
>
> Complete examples showing throw and catch event configurations.


# Send message/receive message tasks
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/message-send-received-task-node

Send message task and Receive message task nodes are used to handle the interaction between a running process and external systems. This is done using Kafka send actions or start integration workflow actions.

Send message and receive message tasks are how a process talks to external systems over Kafka: the send message task publishes a request to a topic, and the receive message task waits for the reply. They typically work as a pair around an integration or plugin call.

## Send message task

This node is used to configure messages that should be sent to external systems.

![Send Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/send-task_node.svg#center)

### Configuring a send message task

Node configuration is done by accessing the **Node Config** tab. You have the following configuration options for a send message task:

#### General Config

Inside the **General Config** tab, you have the following properties:

* **Node Name**: The name of the node
* [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node

To configure a send message task, you first need to add a new node and then configure an **action** (**Kafka Send Action** or **Start Integration Workflow** type):

1. Open **Process Designer** (The process designer is a component of FlowX.AI Designer that allows users to create and design business processes using process definitions.) and start configuring a process.
2. Add a **send message task** node.
3. Select the **send message task** node and open the **Node Configuration**.
4. Add an **action** (Actions in the FlowX.AI platform are used to define the activity that a node has to handle. They can have various types and are used to specify the communication details for plugins or integrations.), the type of the action set to **Kafka Send Action** or **Start Integration Workflow**.
5. A few action parameters will need to be filled in depending on the selected action type.

![Actions tab of a send message task showing a Kafka Send Action with Trigger, Execution, Parameters, and Advanced configuration sections](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kafka_send_action.png)

Multiple options are available for this type of action and can be configured via the FlowX.AI Designer. To configure and [add an action to a node](../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node), use the **Actions** tab at the node level, which has the following configuration sections:

* [Action Edit](#action-edit)
* [Trigger](#trigger)
* [Execution](#execution)
* Navigation
* [Parameters](#parameters)
* [Advanced configuration](#advanced-configuration)

#### Action Edit

* **Name**: The name of the action
* **Action Type**: The type of the action, should be set to **Kafka Send Action** for actions used to send messages to external systems, or **Start Integration Workflow** to trigger [**workflows**](../../platform-deep-dive/integrations/integration-workflows)

> [!NOTE]
>
> Additional fields like **Order** and **Timer Expression** may also be available in certain configurations to control action execution order and timing.

#### Trigger

* **Manual**: When enabled, the action must be triggered manually by the user. When off (automatic), the action triggers automatically when the process flow reaches this step
* **Repeatable**: When enabled, the action can be triggered multiple times

#### Execution

* **Optional**: When enabled, the action is optional and the process can continue without it being executed. When off (mandatory), the action must be completed before advancing to the next node
* **Autorun Children**: When enabled, child actions (defined as mandatory and automatic) run immediately after the parent action completes

#### Parameters

Parameters define the message details for the Kafka send action:

* **Topics**: The Kafka topic name where the message should be sent
* **Message**: The message payload to send (can include process variables using `${variableName}` syntax)

> [!NOTE]
>
> Parameters can be added either using the **Custom** option (where you configure everything on the spot) or by using **From Integration** to import parameters already defined in an integration.
>
> For more information, see the [Integrations Management documentation](../../platform-deep-dive/integrations/integration-designer).

#### Advanced configuration

* **Show Headers**: When enabled, allows you to configure custom headers for the Kafka message (for example, `processInstanceId`)

![Kafka Send Action with a topic and JSON message, and Show Headers turned on with a pre-filled processInstanceId header](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/kafka-send-action-show-headers.png)

For more information about Kafka, check the following sections:

> [card] [Intro to Kafka](/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts)

> [card] [Kafka documentation](https://kafka.apache.org/documentation/)

### Example of a send message task usage

Send a message to a CRM integration to request a search in the local database:

#### Action Edit

* **Name** - pick a name that makes it easy to figure out what this action does, for example, `sendRequestToSearchClient`
* **Action Type** - Kafka Send Action

#### Trigger

* **Manual** - off (automatic trigger)
* **Repeatable** - off (it only needs to run once)

#### Execution

* **Optional** - off (mandatory - the action must be completed before advancing to the next node)
* **Autorun Children** - enabled (if there are child actions, they run automatically)

#### Parameters

* **Topics** - `ai.flowx.in.crm.search.v1` - the Kafka topic on which the CRM listens for requests
* **Message**:

```json theme={"dark"}
// Example of a message payload
{ "clientType": "${application.client.clientType}", "personalNumber": "${personalNumber.client.personalNumber}" }
```

#### Advanced configuration

* **Show Headers**: When enabled, allows you to configure custom headers for the Kafka message (for example, `processInstanceId`, correlation IDs, or other metadata)

## Receive Message Task

This type of node is used when we need to wait for a reply from an external system.

![Receive Message Task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/receive-task%20_node.svg#center)

The reply from the external system will be saved in the process instance values, on a specified key.

For example, let's think about a CRM microservice that waits to receive requests to look for a user in a database. It will send back the response when a topic is configured to listen for the response.

![Receive message task Node Config with Integration Output, Source set to Custom Topic, showing the Topic Name and Key Name fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/receive_kafka_custom.png)

### Configuring a Receive Message Task

Node configuration happens in the **Integration Output** section of the **Node Config** tab.

### Integration Output

The reply arrives on a **data stream**. Click **Add Stream** to add one, then pick its **Source**:

* **Custom Topic**: Type the **Topic Name** the engine listens on and the **Key Name** where the payload lands in the process data.
* **Workflow**: Pick the integration workflow in the **Select workflow** dropdown. With the **Legacy Mapping** toggle **OFF** (the default - see [Legacy mapping vs data mappers](#legacy-mapping-vs-data-mappers)), the **Output Mapping** list shows the workflow's End nodes - configure an output mapping for each one that tells the engine which process attribute receives the workflow's result:

  1. Open the End node's mapping (the wrench icon next to it).
  2. Map the process attribute to the workflow output using `${...}` interpolation syntax.
  3. Click **Test** to preview the mapped result, then **Confirm** to store the mapping.
  4. Save the node - the mapping is persisted only when the node itself is saved.

> [!WARNING]
>
> **Test only previews - Confirm stores.** Closing the mapping modal without clicking **Confirm**, or skipping the node save, leaves the node with no mapping, and every reply then fails at runtime with `workflow output cannot be appended to the process instance due to missing mapping in the data stream`. A failed reply is not retried, so the instance stays blocked on the node - fix the mapping and test with a new process instance. See the [error glossary](../../resources/error-glossary#workflow-output-cannot-be-appended-to-the-process-instance-due-to-missing-mapping-in-the-data-stream).
>
> The **Update** button next to **Clear** and **Test** (**Select from data model** in newer versions) only adds process attributes to the mapping list. It doesn't store the mapping.

> [!TIP]
>
> To see the full send, workflow, receive round trip built end to end, follow the [Call an external API from a process](/5.9/cookbooks/call-external-api) cookbook.

#### Legacy mapping vs data mappers

A **Workflow** data stream works in one of two modes, switched per stream with the **Legacy Mapping** toggle:

* **Data mappers** (toggle **OFF**, the default): configure a per-End-node output mapping as described above. The mapping modal is populated from the workflow's declared output parameters, and a broken mapping fails loudly at runtime with the errors listed in the [error glossary](../../resources/error-glossary#integration-workflow-output). See [Data mappers](../process/data-mappers) for the general mapping mechanism.
* **Legacy mapping** (toggle **ON**): type a single **Key Name** instead of configuring a mapping. The entire workflow output payload is stored under that key in the process data, exactly as the End node returns it. If the End node returns `{"value": 1322}` and the key is `result`, downstream nodes read `result.value`. Nothing validates the key against the workflow - it is simply where the payload lands, so a downstream node reading a different key finds no data and no error points at the mismatch.

Both modes work at runtime - they are alternatives, not a migration requirement. Legacy mapping is what older configurations and training material use. Data mappers pair with a declared workflow data model, which is what provides the visual mapping and the runtime output contract.

The same choice exists on the send side: the **Start Integration Workflow** action either uses data mapping driven by the workflow's declared input parameters, or a hand-typed JSON body whose keys must match what the workflow's Start node expects.

> [!NOTE]
>
> A Receive Message Task has no timeout of its own: the token waits on the node indefinitely until the message arrives. To bound the wait, attach an interrupting [timer boundary event](./timer-events/timer-boundary-event) to the node and route the timeout path from there.


# Process nodes (BPMN)
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/node

A Business Process Model and Notation (BPMN) node is a visual representation of a point in your process. Nodes are added at specific process points to denote the entrance or transition of a record within the process.

Process nodes are the building blocks of a FlowX.AI process: events that start and end the flow, tasks that execute work, and gateways that split or join it. This page lists the BPMN node types available in the FlowX.AI Designer and links to the configuration guide for each.

> [!TIP]
>
> For a comprehensive understanding of BPMN (Business Process Model and Notation), start with the following section:
> [**Intro to BPMN**](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn)

The FlowX.AI platform supports various node types, each requiring distinct configurations to fulfill its role in your business flow. Understanding these node types is essential for building effective process workflows.

## Types of BPMN nodes

The following sections explore each type of BPMN node available in FlowX.AI:

### Start and End nodes

* **Start Node**: Defines the beginning of a process flow and how a process instance is initiated.
* **Message Start Event**: Starts a process instance when a specific message is received.
* **Timer Start Event**: Initiates a process instance based on a specified time or schedule.
* **End Node**: Marks where the process finishes.

> [!NOTE]
>
> A process definition may have multiple start nodes (only if they are in different swimlanes, only one start node per swimlane) and end nodes based on the flow outcomes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_end_nodes.png)

### Activity nodes

* **User Task**: Represents user interactions and displays UI components.

* **Service Task**: Executes tasks using various services to accomplish specific functions.

* **Start Embedded Subprocess**: Initiates subprocesses within a parent process, providing encapsulated functionality and enhanced process management.

* **Call Activity**: Provides advanced options for starting **subprocesses** with enhanced control.

* **Send Message Task**: Sends messages to external systems, integrations, and plugins.

* **Receive Message Task**: Receives messages from external systems, integrations, and plugins.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/activities.png)

### Intermediate events

* **Message Throw Event**: Throws a message and continues with the process flow.
* **Message Catch Event - Interrupting**: Waits for a message before continuing with the process flow.
* **Message Catch Event - Non-Interrupting**: Waits for a message before continuing with the process flow.
* **Timer Event - Interrupting**: Triggers based on a specific time duration, date, or cycle. Can also be used as a boundary event.
* **Timer Event - Non-Interrupting**: Triggers based on a specific time duration, date, or cycle. Can also be used as a boundary event.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intermediate_events.png)

#### Boundary events

Boundary events attach to the boundary of specific nodes (e.g., User Task, Service Task, Subprocess, or Call Activity) and are triggered when predefined conditions occur. These events can interrupt the ongoing activity or allow it to continue while starting a parallel flow. They include:

* **Message Catch Event - Interrupting**: Waits for and responds to a specific incoming message during a task.
* **Message Catch Event - Non-Interrupting**: Waits for and responds to a specific incoming message during a task.
* **Timer Event - Interrupting**: Activates based on elapsed time, a specific date, or a recurring cycle, useful for timeouts or deadlines.
* **Timer Event - Non-Interrupting**: Activates based on elapsed time, a specific date, or a recurring cycle, useful for timeouts or deadlines.
* **Error Event - Interrupting**: This event catches errors during a task or subprocess and redirects the process flow to handle them appropriately.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-03%20at%2012.17.17.png)

### Compatibility matrix

Boundary events can attach to the following node types:

> [accordion] Compatible node types
>
> * **User Task**: All boundary event types supported
> * **Service Task**: Supports Message Catch Event - Interrupting, Timer Event - Interrupting, and Error Event - Interrupting boundary events.
> * **Send Message/Receive Message Tasks**: Supports Message Catch Event - Interrupting, Timer Event - Interrupting, and Error Event - Interrupting boundary events.
> * **Start Embedded Subprocess**: Supports Message Catch Event - Interrupting, Timer Event - Interrupting, and Error Event - Interrupting boundary events.
> * **Call Activity**: Supports Message Catch Event - Interrupting/Non-Interrupting, Timer Event - Interrupting/Non-Interrupting, and Error Event - Interrupting boundary events.

Boundary events are a critical element for creating resilient and adaptive processes, enabling efficient error handling, timeout management, and real-time interactions.

## Next steps

Now that you understand the different types of BPMN nodes available in FlowX.AI, you can start building your own processes. Each node type offers specific configuration options and capabilities that you'll explore as you design your workflows.

> [!TIP]
>
> Start with simple processes using Start nodes, User Tasks, and End nodes before incorporating more complex elements like boundary events and subprocesses.

For hands-on guidance on creating and configuring nodes in your processes, see:

[Managing a process flow](../../flowx-designer/managing-a-project-flow/adding-a-new-node)

For comprehensive insights into BPMN and its various node types, explore our course at FlowX Academy:

> [card] [BPMN 101](https://academy.flowx.ai/explore/bpmn-101)
>
> * What's BPMN (Business Process Model Notation) and how does it work?
> * How is BPMN used in FlowX?


# Parallel gateway
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/parallel-gateway

Run independent tasks concurrently in a process by opening and closing a parallel section with Parallel Gateway nodes.

The parallel gateway splits a process into two or more branches that run at the same time, and a closing parallel gateway joins them back, waiting for all branches to complete before the flow continues.

## Configuring parallel paths

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_parallel.png#center)

This node requires no special configuration and can initiate two or more parallel paths. It's important to note that the closing Parallel node, which is required to conclude the parallel section, will wait for all branches to complete before advancing to the next node.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/parallel_gateways.png)

### Configuration example

Let's consider a scenario involving a Paid Time Off (PTO) request. We have two distinct flows: one for the HR department and another for the manager. Initially, two tokens are generated—one for each parallel path. A third token is created when both parallel paths converge at the closing parallel gateway.

In the HR flow, in our example, the request is automatically approved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/hr_flow.gif)

Now, we await the second flow, which requires user input.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/manager_flow.gif)

After the tokens from the parallel paths have completed their execution, a third token initiates from the closing parallel gateway.


# Start/end nodes
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/start-end-node

Let's go through all the options for configuring start and end nodes for a process definition.

Every FlowX.AI process runs between a start node, which creates the process instance, optionally guarded by a start condition, and an end node, which marks where a flow path finishes.

## Start node

The start node represents the beginning of a process and it is mandatory to add one when creating a process.

![Start node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/start_node.png#center)

A process can have one or more start nodes. If you defined multiple start nodes, each should have a start condition value configured. When starting a new process instance the desired start condition should be used.

![Start node Start\_001 selected on the process canvas, with its Node Config panel showing Node name, the Can go back? toggle, and Stage](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_node.png)

### Configuring a start node

Node configuration is done by accessing the **Node Config** tab. You have the following configuration options for a **start node**:

* [General Config](#general-config)

#### General Config

* **Node name**: The name of the node
* [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node

## End node

![End Event](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/end-event.png#center)

An end node is used to mark where the process finishes. When the process reaches this node, the process is considered completed and its status will be set to `Finished`.

### Configuring an end node

Multiple end nodes can be used to show different end states. The configuration is similar to the start node.

![End node End\_001 selected on the process canvas, with its Node Config panel showing Node name, the Can go back? toggle, and Stage](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/end_node.png)


# Service Task node
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/task-node

A service task node refers to a task that utilizes various services, such as Web services, automated applications, or other similar services, to accomplish a particular task.

The service task node executes automated work with no user interaction: when the process token reaches it, the node's configured actions, business rules, subprocess starts, or data transfers, run and the flow moves on.

![Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/task_node.png)

This type of node finds application in multiple scenarios, including:

* Executing a [**business rule**](../actions/business-rule-action/) on the process instance data
* Initiating a [**subprocess**](../actions/start-subprocess-action)
* Transferring data from a subprocess to the parent process
* Transmitting data to frontend applications

## Configuring task nodes

One or more actions can be configured on a task node. The actions are executed in the configured order.

Node configuration is done by accessing the **Node Config** tab. You have the following configuration options for a task node:

#### General Config

* **Node name**: The name of the node.
* **Can go back**: Allows users to return to a previous step after completing current step.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/task_node_config.png)

#### Integration Output

Add a data stream (**Add Stream**) and pick its **Source**:

* **Workflow**: Select a workflow in the **Select workflow** dropdown, then configure its output mapping - see [Integration Output](./message-send-received-task-node#integration-output) on the Receive Message Task page for the mapping steps.

![Node Config panel with Integration Output, Source set to Workflow, a selected workflow, and the output mapping for the End and End failure nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/dst_wkflw_workflow.png)

* **Custom Topic**: The **Topic Name** where the [process engine](../../platform-deep-dive/core-components/flowx-engine) listens for the response (this should be added to the platform and match the topic naming rule for the engine to listen to it) - available for UPDATES topics (Kafka receive events)

* **Key Name**: Will hold the result received from the external system, if the key already exists in the process values, it will be overwritten

#### Task Management

* **Update task management**: Force the Task Management Plugin to update the information after this node. Update the Base URL, title, stage, priority, or business filters using business rules.

#### Data Search

* **Update data search**: Send updates to the Data Search service after this node, allowing you retrieve data from various process instances.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/update_tm_ds.png)

## Configuring task nodes actions

Multiple options are available when configuring an action on a task node. To configure and add an action to a node, use the **Actions** tab at the node level, which has the following configuration options:

* [Action Edit](#action-edit)
* [Parameters](#parameters)

#### Action Edit

> [!NOTE]
>
> Depending on the type of the [**action**](../actions/actions), different properties are available, let's take a [**business rule**](../actions/business-rule-action/business-rule-action) as an example.

1. **Name**: Used internally to differentiate between different actions on nodes in the process. We recommend defining an action naming standard to be able to quickly find the process actions.

2. **Action type**: Defines the appropriate action type

3. **Trigger**:
   * **Manual**: manually (triggered by the user)
   * **If switched off**: triggered automatically (when the process flow reaches this step)

4. **Execution**:
   * **Optional**: the action is optional
   * **If switched off**: the action is mandatory

5. **Navigation**:
   * **Allow back to this action**: When turned on, the action can be executed again when the token returned from a downstream node (can be switched on only if the trigger type is **Manual**).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/action_edit.png)

#### Parameters

> [!NOTE]
>
> Depending on the type of the [**action**](../actions/actions), different properties are available. We refer to a **Business rule** as an example

1. **Business Rules** - business rules can be attached to a node by using actions with action rules on them, these can be specified using MVEL expressions, or scripts written in Javascript, Python, or Groovy.

> [card] [Supported scripting languages](../supported-scripts)

### Business Rule action

A [business rule](../actions/business-rule-action/business-rule-action) is a Task action that allows a script to run. For now, the following script languages are supported:

* **MVEL**
* **JavaScript**
* **Python**
* **Groovy**

For more details about node actions, check the following section:

> [card] [Node actions](../actions/actions)


# Timer boundary event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/timer-events/timer-boundary-event

Attach a BPMN event to a task or subprocess that activates when a duration, deadline, or specific date condition is met.

This event is used to integrate time-related triggers into workflows, allowing processes to respond automatically to time-sensitive requirements. It is particularly useful for enforcing deadlines, scheduling periodic actions, or sending notifications, ensuring that time-critical steps are incorporated into the overall process design. This capability is especially valuable for scenarios where time-sensitive actions or notifications need to be integrated within process flows.

### Compatibility matrix for Timer Events

**Timer Events** can be applied to various contexts within BPMN processes. The table below outlines their compatibility with different node types:

| **Node Type** | **Timer Event - Interrupting** | **Timer Event - Non-Interrupting** |
| - | - | - |
| **User Task** | Yes | Yes |
| **Service Task** | Yes | Yes |
| **Send Message Task** | Yes | Yes |
| **Receive Message Task** | Yes | Yes |
| **Start Embedded Subprocess** | No | No |
| **Call Activity** | Yes | Yes |

## Timer boundary event - interrupting

A Timer Boundary Event is an event attached to a specific activity (task or subprocess) that is triggered when a specified time duration or date is reached. It can interrupt the ongoing activity and initiate a transition.

![Interrupting timer boundary event icon: a solid double circle with a clock on the edge of an activity](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_boundary_event_interrupting.svg#center)

### Configuration

For Timer Boundary Events - Interrupting, the following values can be configured:

| Field | Validations | Accepted Values |
| - | - | - |
| Name | Mandatory | Name of the boundary event |
| Timer Type | Mandatory | Date or Duration |
| Definition | Mandatory | ISO 8601 date or duration |
| | | Process parameter (check the dynamic value box and pick the data key) |

![Interrupting timer boundary event configuration panel with the Duration timer type, the dynamic value checkbox checked, and the Parameter name picker suggesting the invoice.reviewDeadline key](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/04-boundary-interrupting-dynamic-parameter.png)

### General rules

* When the token enters the parent activity, a scheduler is set, and it waits for the timer event to be triggered.
* When the timer is triggered, the ongoing activity is terminated, and the process continues with the defined transition.

## Timer boundary event - non-interrupting

A Timer Boundary Event is an event attached to a specific activity (task or subprocess) that is triggered when a specified time duration or date is reached. It can trigger independently of the ongoing activity and initiate a parallel path.

![Non-interrupting timer boundary event icon: a dashed double circle with a clock on the edge of an activity](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_boundary_event_non_interrupting.svg#center)

### Configuration

For Timer Boundary Events - Non-Interrupting, the following values can be configured:

| Field | Validations | Accepted Values |
| - | - | - |
| Name | Mandatory | Name of the boundary event |
| Timer Type | Mandatory | Date, Duration, or Cycle |
| Definition | Mandatory | ISO 8601 date, duration, or repeating interval |
| | | Spring cron expression (Cycle timer type, **Cron** format) |
| | | Process parameter (check the dynamic value box and pick the data key) |

### General rules

* When a token arrives at a node with a Timer Boundary Event - Non-Interrupting associated:
  * A trigger is scheduled, but the current token execution remains unaffected.
* When the token enters the parent activity, a scheduler is set, and it waits for the timer event to be triggered.
* If the timer is a cycle, it is rescheduled for the specified number of repetitions.
* The scheduler is canceled if the token leaves the activity before it is triggered.


# Timer events
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/timer-events/timer-events

Trigger BPMN actions or events at predefined intervals, durations, or cycles to add time-based behavior to processes.

Timer events add time-based behavior to a process: they can start a process on a schedule, pause it until a duration or date is reached, or interrupt a task that runs too long. There are three timer event node types:

* **Timer Start Event**: This node initiates a process instance at a scheduled time. It allows you to set a specific date or a repeating cycle for the process to start, so a process can be triggered once or repeatedly.
* **Timer Intermediate Event**: This node introduces time-based triggers within a process. It's used to pause the process execution until a specified time duration or date is reached. Once triggered, the process continues its execution.
* **Timer Boundary Event (interrupting/non-interrupting)**: Attached to a task or subprocess, this node monitors the passage of time while the task is being executed. When the predefined time condition is met, the boundary event triggers an associated action, interrupting or non-interrupting the ongoing task or subprocess.

![Process canvas with a Timer Start Event, a Timer Intermediate Event, and timer boundary events attached to user tasks, service tasks, and a call activity](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-03%20at%2014.37.56.png)

## Timers

Timers introduce the ability to trigger events at specific time intervals. They can be configured in three different ways: as a date, a duration, or a cycle. These configurations can use static values or dynamic values read from the process data.

* **Date**: Events triggered on a specific date and time.
  * Format: ISO 8601 (e.g., `2019-10-01T12:00:00Z` or `2019-10-02T08:09:40+02:00`). Seconds and a time zone (`Z` or an offset) are required.

* **Time Duration**: Events triggered after a specified duration.
  * Format: ISO 8601 duration expression (`P(n)Y(n)M(n)DT(n)H(n)M(n)S`)
    * P: Duration designator
    * Y: Years
    * M: Months
    * D: Days
    * T: Time designator
    * H: Hours
    * M: Minutes
    * S: Seconds

Examples:

* `PT15S` - 15 seconds
* `PT1H30M` - 1 hour and 30 minutes
* `P14D` - 14 days
* `P3Y6M4DT12H30M5S` - 3 years, 6 months, 4 days, 12 hours, 30 minutes, and 5 seconds

![Timer Intermediate Event configuration panel with the Date timer type and the definition editor showing a date picker, a time picker, and the preview 2026-10-15T09:30:00Z](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/01-intermediate-timer-date-editor.png)

![Timer Intermediate Event configuration panel with the Duration timer type and the definition editor converting 1 day 12 hours to the preview P1DT12H](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/02-intermediate-timer-duration-editor.png)

* **Time Cycle** (available for Timer Start Events and non-interrupting Timer Boundary Events): Events triggered at repeating intervals.
  * Option 1: ISO 8601 repeating intervals format (`R`)
    * Examples:
      * `R5/2023-08-29T15:30:00Z/PT2H`: Every 2 hours, up to five times, starting with 29 August, 15:30 UTC time
      * `R/P1D`: Every day, infinitely

![Non-interrupting timer boundary event configuration panel with the Cycle timer type, the ISO format selected, and the definition editor showing Repeat Every 4 hours, 3 repeats, the Infinite and Start Time options, and the preview R3/PT4H](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/03-boundary-noninterrupting-cycle-iso-editor.png)

* Option 2: Using cron expressions
  * Example: `0 0 9-17 * * MON-FRI`: Every hour on the hour from 9 a.m. to 5 p.m. UTC, Monday to Friday

> [!WARNING]
>
> Important: Only Spring cron expressions are permissible for configuration. Refer to the [**official documentation**](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/support/CronExpression.html) for detailed information on configuring Spring Cron expressions.

Scheduled timer events are clearly indicated within the process definition list of an application at Runtime, as illustrated in the following example:

![Runtime Scheduled processes list showing process definitions with active timer start events](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

> [card] [Scheduled processes](../../../projects/runtime/scheduled-processes/)

More information about timer expressions you can find in the below section:

[Timer expressions](./timer-expressions)

***

## Configure a timer

Select a timer node on the canvas (or a timer boundary event on its parent activity) to open its configuration panel. The panel has the following fields:

| Field | Description |
| - | - |
| **Timer Type** | **Date**, **Duration**, or **Cycle**. The options offered depend on the node type, see the [table below](#configuration). |
| **Definition** | The timer value. Use ISO 8601 for dates, durations, and cycles, or a cron expression for cycles. The field is mandatory. |
| **ISO** / **Cron** | The format of the definition. **Cron** is offered only when the timer type is **Cycle**. Switching the type or the format clears the current definition. |
| **Dynamic value** (the **x** checkbox next to the format) | Reads the definition from the process data instead of a static value. When checked, the **Definition** input is replaced by a **Parameter name** picker that lists the keys of the process data model. The key must start with a letter and may use dots for nested values (for example `customer.deadline`). Not available on Timer Start Events. |

> [!TIP]
>
> Click the pencil icon in the **Definition** field to open the definition editor instead of typing the ISO value. The editor shows a **Preview** of the resulting value and adapts to the timer type:
>
> * **Date**: a date picker and a time picker. The result is written in UTC (`...T09:30:00Z`). To use another time zone offset, type the ISO value directly.
> * **Duration**: a plain-language input (for example `2 hours` or `5 mins 20 minutes`) that is converted to an ISO 8601 duration.
> * **Cycle** (ISO): **Repeat Every**, **# of repeats** or **Infinite**, and an optional **Start Time**.
> * **Cycle** (Cron): the start and end date and time of the schedule, see [Timer Start Event](./timer-start-event#cron-expressions).

An invalid definition is rejected with the message **Invalid format.** before the node can be saved.

### How does the timer editor work on SaaS?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, the pencil-icon definition editor and the **x** dynamic value checkbox are replaced by entry modes, picked with buttons next to the field label:

* **Guided** (labelled **Static** for **Duration** timers) builds the value from fields: a **Fire at** date and time picker for **Date** timers, a plain-language length such as `1h30m` for **Duration** timers, and **Repeat Every**, **# of repeats** or **Infinite**, and **Start Time** for ISO **Cycle** timers.
* **Expression** takes the ISO 8601 or cron value as typed. It is offered for **Duration** and **Cycle** timers.
* **Process variable** reads the value from a process data key, picked in **Parameter name**. It is offered on Timer Intermediate Events and Timer Boundary Events.

Dates and times you pick are in your local time, and the Designer converts them to UTC when it saves. Cron expressions are still read in UTC. The **Format** choice (**ISO** or **Cron**) appears only for **Cycle** timers, and cycle timers show a preview of the next three fire times in your browser's time zone.

> [!NOTE]
>
> Timers saved with the date and time pickers in the earlier editor stored your local time marked as UTC. The SaaS editor shows a stored value converted to your local time, so such a timer can look shifted by your UTC offset. The stored value, and the time the timer fires, don't change until you edit the timer.

***

## Configuration

For each node type, the following timer types can be configured:

| Node Type | Date | Duration | Cycle |
| - | - | - | - |
| Timer Start Event | Yes | No | Yes |
| Timer Intermediate Event | Yes | Yes | No |
| Timer Boundary Event (interrupting) | Yes | Yes | No |
| Timer Boundary Event (non-interrupting) | Yes | Yes | Yes |

> [!WARNING]
>
> A swimlane can hold only one start node of any kind (Start Event, Message Start Event, or Timer Start Event). Adding a second start node to the same swimlane is rejected.

For comprehensive details on each timer event node in this section, please refer to the corresponding documentation:

> [card] [Timer Start Event](./timer-start-event)

> [card] [Timer Intermediate Event](./timer-intermediate-event)

> [card] [Timer Boundary Events](./timer-boundary-event)

> [card] [Timer expressions](./timer-expressions)


# Timer expressions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/timer-events/timer-expressions

Configure timer expressions using Cron syntax for scheduling or ISO 8601 format for durations and timeouts.

When working with FlowX.AI components, there are multiple scenarios in which timer expressions are needed.

There are two timer expressions formats supported:

* [**Cron expressions**](#cron-expressions) - used for **Cycle** timers (Timer Start Events and non-interrupting Timer Boundary Events) and to define the expiry time on processes
* [**ISO 8601**](#iso-8601) - used to define dates, durations, and repeating intervals for timer events

## Cron expressions

A cron expression is a string made up of **six mandatory subexpressions (fields) that each specifies an aspect of the schedule** (for example, `* * * * * *`). These fields, separated by white space, can contain any of the allowed values with various combinations of the allowed characters for that field.

> [!NOTE]
>
> A field may be an asterisk (`*`), which always stands for “first-last”. For the day-of-the-month or day-of-the-week fields, a question mark (`?`) may be used instead of an asterisk.

> [!WARNING]
>
> Important: Only Spring cron expressions are permissible for configuration. Refer to the [**official documentation**](https://docs.spring.io/spring-framework/reference/integration/scheduling.html#scheduling-cron-expression) for detailed information on configuring Spring Cron expressions.

Subexpressions:

1. Seconds
2. Minutes
3. Hours
4. Day-of-Month
5. Month
6. Day-of-Week

An example of a complete cron-expression is the string `0 0 12 ? * FRI` - which means **every Friday at 12:00:00 PM**.

More details:

[Scheduling cron expressions](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#scheduling-cron-expression)

### Cron Expressions are used in the following example:

* [**Process definition**](../../../building-blocks/process/process-definition) - **Expiry time** - a user can set up a `expiryTime` function on a process, for example, a delay of 30s will be set up like:

![Process definition settings with the expiry time field set to a cron expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/timer_process_settings.png)

## ISO 8601

ISO 8601 is an international standard covering the worldwide exchange and communication of date and time-related data. It can be used to standardize the following: dates, time of delay, time intervals, recurring time intervals, etc.

More details:

[ISO 8601 date format](https://www.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_date_format.htm)

[ISO 8601 duration format](https://www.digi.com/resources/documentation/digidocs//90001488-13/reference/r_iso_8601_duration_format.htm)

### ISO 8601 format is used in the following examples:

* **Timer events** - a **Definition** with the **Duration** timer type, for example `PT30M` on an interrupting [timer boundary event](./timer-boundary-event) that limits how long a receive task waits for a message

ISO 8601 dates and times:

| Format accepted | Value ranges |
| - | - |
| Year (Y) | YYYY, four-digit, abbreviated to two-digit |
| Month (M) | MM, 01 to 12 |
| Week (W) | WW, 01 to 53 |
| Day (D) | D, day of the week, 1 to 7 |
| Hour (h) | hh, 00 to 23, 24:00:00 as the end time |
| Minute (m) | mm, 00 to 59 |
| Second (s) | ss, 00 to 59 |
| Decimal fraction (f) | Fractions of seconds, any degree of accuracy |

![Timer configuration with an ISO 8601 duration used as a response timeout](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/timer_response_timeout.png)

* [**Actions**](../../actions/actions) - **Timer expression** - it can be used if a delay is required on that action

![Action edit dialog with the timer expression field used to delay the action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/timer_action_edit.png)


# Timer Intermediate Event (interrupting)
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/timer-events/timer-intermediate-event

A Timer Intermediate Event (interrupting) is an event that is triggered based on a specified time duration or date. It is placed within the flow of a process and serves as a point of interruption and continuation.

![Timer Intermediate Event node icon: a double circle with a clock](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_intermediate_event.png#center)

## Configuring a timer intermediate event (interrupting)

| Field | Validations | Accepted Values |
| - | - | - |
| Timer Type | Mandatory | Date or Duration |
| Definition | Mandatory | ISO 8601 date or duration |
| | | Process parameter (check the dynamic value box and pick the data key) |

![Process canvas of an invoice approval flow with a Timer Intermediate Event named Wait for payment run placed between the Escalate to manager user task and the Approved end event, and two timer boundary events attached to the Review invoice task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/05-timer-events-canvas-overview.png)

### Timer type:

#### Date

* event triggered on a specific date-time
* ISO 8601 format (example: `2019-10-01T12:00:00Z` - UTC time, `2019-10-02T08:09:40+02:00`- UTC plus two hours zone offset)

![Timer Intermediate Event configuration panel with the Date timer type and the definition editor showing a date picker, a time picker, and the preview 2026-10-15T09:30:00Z](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/01-intermediate-timer-date-editor.png)

#### Duration

Event triggered after x duration after the token reached the timer node (or parent node) (example: `PT6S`).

* Definition:
  * ISO 8601 duration
  * Process parameter

> [!NOTE]
>
> Cron expressions are available only for the **Cycle** timer type, which this node does not support.

## General Rules

* A Timer Intermediate Event is triggered based on its duration or date definition.
* When the token enters a Timer Intermediate Event, a scheduler is set, and it waits for the timer event to be triggered.
* After the timer is triggered, the process instance continues.


# Timer start event
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/timer-events/timer-start-event

A Timer Start Event initiates a process instance based on a specified time or schedule.

![Timer Start Event node icon: a circle with a clock](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/timer_start_interrupting.png#center)

> [!NOTE]
>
> A swimlane can hold only one start node of any kind (Start Event, Message Start Event, or Timer Start Event). A process with several swimlanes can therefore have several Timer Start Events, one per swimlane, and each appears as its own row in **Scheduled Processes**.

## Configuration

The Timer Start Event supports two timer types:

| Timer Type | Description |
| - | - |
| Date | Specifies an exact date and time for triggering the event (ISO 8601 format) |
| Cycle | Specifies a repeating interval using ISO 8601 repeating intervals or cron expressions |

> [!NOTE]
>
> The Start Timer Event supports either ISO 8601 formats or Spring cron expressions for defining timer values. The **Definition** must be a static value: the dynamic value option (reading the definition from a process parameter) is not available on this node, because no process instance exists yet when the timer fires.

> [!TIP]
>
> Starting a process via registered timers requires sending a process start message to Kafka, necessitating a service account and authentication. For detailed guidance, refer to:
>
> [**Service Accounts**](../../../../setup-guides/access-management/configuring-an-iam-solution#scheduler-service-account)

## Timer type details

> [!NOTE]
>
> On SaaS with FlowX.AI 6.0, the Date picker, ISO cycle fields, and cron active window take your local time and are saved in UTC, and the pencil-icon editor is replaced by entry modes. See [How does the timer editor work on SaaS?](./timer-events#how-does-the-timer-editor-work-on-saas)

### Date

Specifies an exact date and time for triggering the event. You can use ISO 8601 date format for accurate date-time representation.

When configuring a Date timer with the definition editor (pencil icon), you can set:

* **Date**: Select a specific date (format: yyyy-mm-dd) using the date picker
* **Time**: Set the specific time when the timer should trigger

The editor writes the value in UTC (for example `2025-03-12T13:30:00Z`). To schedule in another time zone, type the ISO value with an offset directly in the **Definition** field (for example `2025-03-12T15:30:00+02:00`).

![Timer Start Event configuration with the Date timer type, a UTC ISO definition, and the date and time pickers of the definition editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_date.png)

### Cycle

Specifies a repeating interval for triggering the event. Select **ISO** or **Cron** next to the **Definition** label to choose the format. For the Cycle timer definition, you can use either:

#### ISO 8601 repeating intervals

For standardized time intervals (e.g., "R5/PT10M" for repeating 5 times with 10 minutes between each)

![Timer Start Event configuration with the Cycle timer type, an R5/PT10M definition, and the Repeat Every, number of repeats, Infinite, and Start Time controls of the definition editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_cycle_iso_repeating.png)

> [!TIP]
>
> When configuring a Cycle timer (ISO 8601 repeating intervals) you can set:
>
> * **Repeat Every**: The interval between triggers (e.g., "2 hours")
> * **# of repeats**: How many times the timer should trigger (e.g., "3")
> * **Infinite**: Option to make the timer repeat indefinitely
> * **Start Time**: When the timer should begin (format: yyyy-mm-dd)

#### Cron expressions

For more complex scheduling patterns (e.g., "0 0 12 \* \* MON-FRI" for 12pm every weekday). Type the Spring cron expression in the **Definition** field.

The definition editor (pencil icon) lets you bound the schedule with a **Start Date** and **Start Time** and an **End Date** and **End Time**. The timer fires only inside this window. These bounds exist only on Timer Start Events.

![Timer Start Event configuration with the Cycle timer type, the Cron format selected, and a weekday noon cron expression as the definition](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_cycle_cron.png)

#### Cron editor with required schedule window

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The definition editor for cron cycles contains a **Cron expression** field with the six-field Spring format (second, minute, hour, day, month, weekday), for example `0 */5 * * * ?` for every five minutes. The start and end date and time are required for Timer Start Events. Once both are set, the panel shows the resulting window under the definition, for example `Active window: 2026-10-01 09:00 – 2026-12-31 18:00 UTC`.

![Cron definition editor of a Timer Start Event with the Cron expression field set to 0 0 2 \* \* MON-FRI and the Start Date, Start Time, End Date, and End Time fields filled in](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/06-timer-start-cron-editor-513.png)

![Timer Start Event configuration panel with the Cycle timer type, the Cron format selected, a weekday cron definition, and the Active window summary line under the definition](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/07-timer-start-cron-active-window-513.png)

The expression is validated before saving: exactly six fields, with support for lists, ranges, steps, `?`, `L`, `W`, `#`, month and weekday names, and the `@hourly`, `@daily`, `@midnight`, `@weekly`, `@monthly`, `@yearly`, and `@annually` macros. A seventh field is rejected with **Invalid cron expression.**

## Activate/deactivate start timer events

All timers can be activated/deactivated in the Runtime section under "Scheduled Processes":

![Runtime Scheduled processes list with the activate and suspend controls for each timer start event](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/active_timer_events.png)

> [!WARNING]
>
> If a project contains multiple versions with Start Timer Event nodes, a scheduler will be generated only for the ones included in the version set in the active policy.
>
> ![Active policy dialog selecting the build whose timer start events are scheduled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-03-11%20at%2014.35.21.png)

## Usage examples

### Date timer example: Employee Onboarding Reminder

In this scenario, the Timer Start Event triggers an employee onboarding process at a specific date and time.

![Process canvas of the employee onboarding scenario: Timer Start Event, Employee Onboarding Notification task, and Complete Onboarding end](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_event_scenario.png)

* Start Event (Timer Start Event) - New Hire Start Date
  * Timer Definition: 2023-09-01T09:00:00Z (ISO 8601 format) → This means the process will initiate automatically at the specified date and time.
  * This event serves as the trigger for the entire process.
  * Transition → Employee Onboarding Notification

![Timer Start Event configuration for the onboarding scenario with a Date definition of 2023-09-01T09:00:00Z](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_timer_date_scenario.png)

* Employee Onboarding Notification
  * Notify new employee about onboarding requirements by sending an email notification with a template called "Important Onboarding Information"
  * Actions: The HR team or automated system sends out necessary email information/documents, and instructions to the new employee.
  * After the notification is sent, the process transitions to the Complete Onboarding node.

![Send notification action configured with the Important Onboarding Information template](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/onboarding_notification.png)

* Complete Onboarding
  * Employee onboarding completed
  * At this point, the employee's onboarding process is considered complete.
  * Actions: The employee may have completed required tasks, paperwork, or orientation sessions.

### General rules

* Schedulers are generated only for builds that are part of the active policy.
* If you change the active policy, processes with Timer Start Event nodes might appear or disappear from the scheduled processes list if they aren't part of the active build.
* You can view scheduled processes in the Runtime section under "Scheduled Processes".
* When a build in the active policy is updated with new Timer Start Event settings:
  * The scheduler is updated based on the new settings.
  * The scheduler state (active or suspended) remains the same as before.

***

## Related resources

> [card] [Timer expressions](/5.9/docs/building-blocks/node/timer-events/timer-expressions)
>
> ISO 8601 and cron syntax for timer definitions

> [card] [Scheduled processes](/5.9/docs/projects/runtime/scheduled-processes)
>
> Activate, suspend, and review Timer Start Events at runtime

> [card] [Timer intermediate event](/5.9/docs/building-blocks/node/timer-events/timer-intermediate-event)
>
> Pause a running process for a duration or until a date

> [card] [Starting a process](/5.9/docs/flowx-designer/managing-a-project-flow/starting-a-process)
>
> All the ways a process instance can start


# User task node
Source: https://docs.flowx.ai/5.9/docs/building-blocks/node/user-task-node

This node represents an interaction with the user. It is used to display a piece of UI (defined in the UI Designer or a custom Angular component. You can also define actions available for the users to interact with the process.

## Configuring a user task node

![User Task Node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/user_task_node.png#center)

User task nodes allow you to define and configure UI templates and possible [actions](../actions/actions) for a certain template config node (ex: [button components](../ui-designer/ui-component-types/buttons)).

#### General Config

* **Node name**: The name of the node
* **Can go back**: When enabled, allows users to return to this step after completing it. When encountering a step with `canGoBack` false, all steps found behind it will become unavailable.
* [**Stage**](../../platform-deep-dive/core-extensions/task-management/using-stages): Assign a stage to the node

> [!NOTE]
>
> When encountering a step with `canGoBack` switched to false, all steps found behind it will become unavailable.

#### Integration Output

Add a data stream (**Add Stream**), set its **Source** to **Custom Topic**, and configure:

* **Topic Name**: The topic name where the process engine listens for the response (this should be added to the platform and match the topic naming rule for the engine to listen to it) - available for UPDATES topics (Kafka receive events)

> [!TIP]
>
> A naming pattern must be defined on the [process engine configuration](../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka) to use the defined topics. All events that start with a configured pattern are consumed by the Engine. For example, `KAFKA_TOPIC_PATTERN` is the topic name pattern where the Engine listens for incoming Kafka events.

* **Key Name**: Will hold the result received from the external system, if the key already exists in the process values, it will be overwritten

#### Task Management

* **Update task management** - force [Task Management](../../platform-deep-dive/core-extensions/task-management/task-management-overview) plugin to update information about this process after this node

#### Data Search

* **Update data search**: Send updates to the Data Search service after this node, allowing you retrieve data from various process instances.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/update_ds_tn.png)

## Configuring the UI

The **FlowX.AI Designer** includes an intuitive [UI Designer](../ui-designer/ui-designer) (drag-and-drop editor) for creating diverse UI templates. You can use various elements from basic [buttons](../ui-designer/ui-component-types/buttons), indicators, and [forms](../ui-designer/ui-component-types/form-elements/), but also predefined [collections](../ui-designer/ui-component-types/collection/collection) or [prototypes](../ui-designer/ui-component-types/collection/collection-prototype).

### Accessing the UI Designer

To access the **UI Designer**, follow the next steps:

1. Open **FlowX.AI Designer**.
2. Select a workspace.
3. Select a project.
4. Select a **process**.
5. Select a **user task** **node** then click the **brush** icon to open the **UI Designer**.

### Predefined components

UI can be defined using the available components provided by FlowX.AI, using the UI Designer available at node level.

Predefined components can be split in 3 categories:

> [accordion] Root components
>
> These elements are used to group different types of components, each having a different purpose:
>
> * [**Card**](../ui-designer/ui-component-types/root-components/card) - used to group and configure the layout for multiple **form elements.**
> * [**Container**](../ui-designer/ui-component-types/root-components/container) - used to group and configure the layout for multiple **components** of any type.
> * [**Custom**](../ui-designer/ui-component-types/root-components/custom) - these are Angular components developed in the container application and passed to the SDK at runtime, identified here by the component name
>
> More details in the following section:
>
> > [card] [Root components](../ui-designer/ui-component-types/root-components/root-components)

> [accordion] UI components
>
> The root component can hold a hierarchical component structure.
>
> Available children for **Card** and **Container** are:
>
> * **Container** - used to group and align its children
> * **Form** - used to group and align form field elements (**inputs**, **radios**, **checkboxes**, etc)
> * **Image** - allows you to configure an image in the document
> * **Text** - a simple text can be configured via this component, basic configuration is available
> * **Hint** - multiple types of hints can be configured via this component
> * **Link** - used to configure a hyperlink that opens in a new tab
> * **Button** - Multiple options are available for configuration, the most important part being the possibility to add actions
> * **File Upload** - A specific type of button that allows you to select a file
>
> More details in the following section:
>
> > [card] [Component types](../ui-designer/ui-designer#ui-components)

> [accordion] Form elements
>
> This type of elements are used to allow the user to input data, and can be added only in a **Form** Component. They have have multiple properties that can be managed.
>
> 1. [**Input**](../ui-designer/ui-component-types/form-elements/input-form-field) - FlowX.AI form element that allows you to generate an input form filed
> 2. [**Select**](../ui-designer/ui-component-types/form-elements/select-form-field) - to add a dropdown
> 3. [**Checkbox**](../ui-designer/ui-component-types/form-elements/checkbox-form-field) - the user can select zero or more input from a set of options
> 4. [**Radio**](../ui-designer/ui-component-types/form-elements/radio-form-field) - the user is required to select one and only one input from a set of options
> 5. [**Datepicker**](../ui-designer/ui-component-types/form-elements/datepicker-form-field) - to select a date from a calendar picker
> 6. [**Switch**](../ui-designer/ui-component-types/form-elements/switch-form-field) - allows the user to toggle an option on or off
>
> More details in the following section:
>
> > [card] [Form elements](../ui-designer/ui-component-types/form-elements)

### Custom components

These are components developed in the web application and referenced here by component identifier. This will dictate where the component is displayed in the component hierarchy and what actions are available for the component.

To add a custom component in the template config tree, we need to know its unique identifier and the data it should receive from the process model.

More details in the following section:

> [card] [Custom](../ui-designer/ui-component-types/root-components/custom)


# Call Activity or embedded subprocess - which to use
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/call-activity-vs-embedded-subprocess

Decide between a Call Activity and a Start Embedded Subprocess node based on data ownership, lifecycle and navigation, with patterns and anti-patterns.

Use a **Call Activity** when a phase owns data that the parent process should not keep, such as integration responses, intermediate calculations or preparation data. Use a **Start Embedded Subprocess** node when the phase is a set of screens that works mostly on the parent's data and must appear as a step in the parent's navigation.

Both nodes split a large process into smaller ones. They differ in where the subprocess runs and where its data lives.

***

## How do the two nodes differ?

| | Call Activity | Start Embedded Subprocess |
| - | - | - |
| **Process instance** | Starts a separate process instance with its own tokens and data | Runs inside the parent process instance. No new instance is created |
| **Data** | Isolated. Input is copied from the parent, output is returned explicitly | Shared. The subprocess reads and writes the parent's data directly |
| **Navigation** | Renders its screens in its own navigation areas, not in the parent's stepper or tabs | Renders under a **Parent Process** navigation area, so its screens appear as steps in the parent's navigation |
| **Execution modes** | Synchronous or asynchronous, plus parallel multi-instance | Always part of the parent token's path |
| **Swimlanes** | Any number | Exactly one |
| **BPMN 2.0 equivalent** | Call Activity: a reusable process invoked by reference | Embedded subprocess: a process fragment that shares the parent's context |

> [!NOTE]
>
> A process built for embedding can only be embedded. The runtime rejects a process whose root navigation area is a **Parent Process** area when it's started by a Call Activity or a Start Subprocess action (`Could not render subprocess due to root Parent Process Area.`), and when it's started on its own (`The process couldn’t start because root navigation area can only be rendered for embedded subprocesses.`).

***

## Rule of thumb

**If the phase brings its own temporary data, use a Call Activity. If the phase mostly reuses data the parent already has, use an embedded subprocess.**

| Question | Call Activity | Embedded subprocess |
| - | - | - |
| Where does the data come from? | The phase fetches or computes data the parent doesn't need afterwards | Most of the data comes from the parent and goes back to it |
| What happens to temporary data? | It stays in the child instance. The parent only receives what you return | Nothing to clean up, but everything the phase writes stays on the parent instance |
| What does the phase contain? | Integrations, calculations, document generation, preparation or save steps, transient overlays | Screens, user tasks, step-by-step journeys |
| Does it need a step in the parent's stepper or tabs? | No | Yes |
| Where do errors and incidents land? | On the child instance, separate from the parent's tokens | On the parent instance, because the subprocess shares the parent's tokens |

***

## Recommended pattern: prepare, screen, save

Wrap each user-facing phase between two Call Activities:

```
[Prepare - Call Activity] → [Screen - Start Embedded Subprocess] → [Save - Call Activity]
```

![Parent process in navigation view: Prepare offer Call Activity, Review Start Embedded Subprocess node in the Offer review step, Save offer Call Activity](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/embedded-subprocess-parent-navigation.png)

Navigation view of a parent process built with this pattern. The embedded subprocess node (Review) sits in the Offer review step of the stepper. The Prepare offer and Save offer Call Activities aren't assigned to any step.

* **Prepare** fetches, enriches and computes the data the screen needs. Raw integration responses stay in the child instance, and only the values the screen uses go back to the parent.
* **Screen** renders the user tasks as steps in the parent's navigation and works on the parent's data.
* **Save** persists or processes what the user entered, again without leaving intermediate data on the parent.

With this pattern, the parent process becomes a sequencer: it orders the phases and holds the business data, while integration logic lives in the prepare and save processes.

> [!TIP]
>
> If a phase varies between projects that share a library, such as a country-specific preparation step, put that phase in its own library process. A project can then replace just that process with a [resource override](../../projects/resources#resources-overrides) without touching the parent. An override must keep the original process's data model and structure.

***

## When should I use a Call Activity?

* **Integration-heavy phases with no user tasks:** calculations, document generation, decision calls, status updates.
* **Preparation phases** that fetch or compute data before a screen is shown.
* **Save phases** that persist or process the results of a screen.
* **Parallel work over a list:** a [parallel multi-instance](../node/call-subprocess-tasks/call-activity-node#parallel-multi-instance) Call Activity starts one subprocess per array item, for example to generate several documents at once.
* **Shared utilities** called from many processes, such as status updates or error handling. Each caller gets its own instance, so a change to the utility doesn't change the parent's data model.
* **Transient overlays:** an error modal, a confirmation dialog before an irreversible action, or a status message while a long operation runs. The overlay resolves and the user returns to the same place in the journey.

> [!WARNING]
>
> Start the overlay **from inside** the Call Activity. Don't trigger a Call Activity from a modal user task in the parent: invoking a Call Activity from inside a modal dismisses that modal, and it isn't restored afterwards. See [Don't chain a modal user task to a Call Activity](./design-principles#don’t-chain-a-modal-user-task-to-a-call-activity).

A Call Activity can also render Pages and Steppers. Those screens join the mobile back stack while the subprocess runs and are cleared when it finishes, so use them for journeys the user shouldn't return to once completed. See [Process design principles](./design-principles#call-activity-subprocesses-with-pages-or-steppers-appear-in-mobile-back-nav).

***

## When should I use an embedded subprocess?

* **Screens and user tasks** that must appear as a named step in the parent's stepper, tabs or navigation areas.
* **Reusable UI fragments** that several parent processes show as part of their own journey.
* **Error screens that are a step of the journey.** If the error screen should appear in the stepper, embed it. If it's a transient interruption, use a Call Activity.
* **Phases where copying data in and out is wasted work.** An embedded subprocess shares the parent's data, so it needs no **Copy from Current State**, **Exclude from Current State** or **Append Params to Parent Process** configuration.

> [!WARNING]
>
> **Requirements for an embedded subprocess**
>
> * The subprocess must have exactly **one swimlane**, and its swimlane permissions are inherited from the parent.
> * Its root navigation area must be a **Parent Process** area.
> * Both rules apply to every subprocess it embeds in turn.
>
> Otherwise the runtime reports `Could not render subprocess due to multiple swimlanes or missing Parent Process Area.` See the [error glossary](../../resources/error-glossary#could-not-render-subprocess-due-to-multiple-swimlanes-or-missing-parent-process-area) and the [runtime considerations](../node/call-subprocess-tasks/start-embedded-subprocess#runtime-considerations) for the node.

***

## Anti-patterns

### One Call Activity per quick integration

Each Call Activity starts a process instance. Wrapping every single backend call in its own Call Activity adds instance overhead and makes the process graph hard to read. Group integrations that always run together into one Call Activity.

### A subprocess that only starts more subprocesses

Starting a subprocess just to pass parameters and immediately launch several Call Activities from inside it pays the instance cost twice. To run the same work for several inputs, use a parallel multi-instance Call Activity directly from the parent.

### Embedded subprocesses as integration gateways

An embedded subprocess that wraps integrations and is embedded from many processes couples all of them to the same data keys: any change to the integration lands in every caller's data model. Move shared integrations into Call Activities, so each caller receives only the output it maps.

### Circular embedding

Avoid chains where a process embeds a process that, directly or through other subprocesses, embeds the first one again. Use Call Activities for shared utilities, so each call has its own lifecycle and the dependency doesn't loop back into the parent's instance.

***

## Decision table

| Scenario | Use |
| - | - |
| Backend call, no UI | Call Activity |
| Several integrations that always run together | One Call Activity for all of them |
| The same work for each item in a list | Parallel multi-instance Call Activity |
| Data preparation before a screen | Call Activity |
| Saving or processing a screen's results | Call Activity |
| Calculations without user tasks | Call Activity |
| Transient error modal, confirmation dialog or status overlay | Call Activity, with the modal inside it |
| A screen that is a named step in the stepper or tabs | Embedded subprocess |
| A reusable screen or modal that is a named step of the journey | Embedded subprocess |
| A phase that differs per project or country | Its own library process, invoked by a Call Activity and replaced with a resource override |

***

## Related resources

> [card] [Call Activity node](../node/call-subprocess-tasks/call-activity-node)
>
> Sync and async modes, library subprocesses, parallel multi-instance

> [card] [Start Embedded Subprocess node](../node/call-subprocess-tasks/start-embedded-subprocess)
>
> Parent Process area, swimlane rules, configuration steps

> [card] [Subprocess management](./subprocess)
>
> Start modes, parameter inheritance, returning data to the parent

> [card] [Process design principles](./design-principles)
>
> Modal, subprocess and navigation rules for process design


# Data mappers
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/data-mappers

Visually map data transfers between components while maintaining full backward compatibility.

## Overview

Use Data Mappers to define how data flows between components. Add JavaScript transformations for complex scenarios.

### Key concepts

> [card] Source Components
>
> Send data to another component to trigger execution
>
> * Parent processes
> * Integration flows
> * Business rules

> [card] Destination Components
>
> Receive input from a source component to execute
>
> * Subprocesses
> * Workflows
> * Business rules

### Parameters & variables

Configure parameters and variables on the **Data Model** tab at process level.

> [tab] Input Parameters
>
> **Input Parameters**: Define the structure your component expects to receive for successful execution.
>
> **Input Variables**: Send actual data from source to destination component for execution.
>
> ![Input Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp1.png)

> [tab] Output Parameters
>
> **Output Parameters**: Define the structure your component returns to the source component after execution.
>
> **Output Variables**: Return actual data from destination to source component after execution.
>
> ![Output Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp2.png)

#### Parameter types by origin

> [accordion] Predefined Parameters
>
> Established before the mapping action (e.g., input of a subprocess or workflow). These typically belong to **destination components** with fixed requirements.

> [accordion] Flexible Parameters
>
> Defined during the mapping process. Associated with **source components** that specify where destination component data comes from.

## Quick reference

Looking for a specific syntax rule or behavior? Everything is in this table; the sections after it walk through each scenario in detail.

| You want to | Do this |
| - | - |
| Map a single value | Use interpolation syntax: `${variableName}`. This format differs from process key formats. |
| Map all attributes at once | **Auto-populate**: select the data model type from the dropdown. **Quick Mapping**: available when source and destination share the same data type. |
| Transform, filter, or compute a value | Click the **f(x)** function icon next to the parameter and write JavaScript. Every computed value must use a `return` statement. |
| Reference data inside JavaScript | `${...}` resolves a **path** to its value; it does not evaluate JavaScript inside the braces. Place the placeholder first, then chain methods on the result. |
| Map part of an array | Not possible from the UI: arrays map **wholesale**. Use function mode to filter or reshape. See [Transforming arrays](#transforming-arrays). |
| Chain array methods safely | Wrap the placeholder with an empty-array fallback so an unpopulated path doesn't make `.filter()` or `.map()` throw. Copy-ready snippets: [Transforming arrays](#transforming-arrays). |
| Map output from an async subprocess | Not possible: the parent doesn't wait, so async supports **input mapping only**. |
| Preview what will be sent | Click **test** to render the JSON payload using the example values from your data model. |
| Change the data model | Deleted and renamed attributes propagate to mappings automatically; **new attributes must be added and mapped manually**. |
| Change a multi-instance input/output array | Saving the array change **deletes the existing mappings**; reconfigure them afterward. |

***

## Prerequisites

> [!WARNING]
>
> Plan your Data Model carefully before implementing Data Mappers. Proper setup ensures success.

### Data Model hierarchy

Understand the data model hierarchy to implement Data Mappers effectively:

> [card] Project Data Model
>
> **Organization Level**: Define reusable data structures (e.g., "customer", "client type") that you can share across all processes and workflows within your project.

> [card] Library Data Model
>
> **Enterprise Level**: Create organization-wide standardized data types that you can reuse across multiple projects by including the library as a dependency.

> [card] Process Data Model
>
> **Process Level**: Define process-specific data structures while reusing components from project and library levels.

### Setup requirements

**1. Define Project Data Model First**

**Critical**: Define your project data model before creating processes. This enables:

* Reusability across processes and workflows
* Consistent data structures
* Improved error prevention
* Enhanced mapping experience

**2. Include Example Values**

Add meaningful example values to your data model attributes. This helps you:

* Visualize attribute meaning and expected values
* Test without separate mock data
* Improve your configuration experience

**3. Plan for Reusability**

Design data structures that can be shared across multiple components:

* Customer information structures
* Common business entities
* Standardized response formats

## Configuration

### Setting up process parameters

**1. Configure Input Parameters**

* Open the process you want to configure
* Navigate to the **Data Model**
* Select the **Input parameters** tab and click "Define parameters"

![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp3.png)

> [!NOTE]
>
> Define parameters for each start node separately when you have multiple start nodes. Select nodes from the dropdown.
>
> ![Start node selection dropdown on the Input parameters tab for processes with multiple start nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp4.png)

* Define the schema based on the process's Data Model
* Mark fields as optional if your component can function without those parameters. The optional flag indicates your component can operate without these parameters throughout its entire operation, not just during mapping.
* **Note**: This centralizes input definition at the subprocess level, replacing the previous "data to send" configuration on the parent process

![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp5.png)

**2. Configure Output Parameters**

* Navigate to the **Data Model**
* Select the **Output parameters** tab
* Define the schema based on the process's Data Model

![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/output_variables.png)

**3. Handle Multiple Start/End Nodes**

* View all start or end nodes when your subprocess has multiple nodes
* Use this for scenarios with exclusive gateways
* Configure parameters independently for each node

> [!NOTE]
>
> **Process Start Prompts**: When you start a process with defined input parameters, the system generates input prompts based on required parameters to help with testing and validation.

## Mapping scenarios

### Call activity mapping

#### Synchronous call activity

```yaml Prerequisites theme={"dark"}
- Parent process with defined Data Model
- Child process with input/output parameters on Data Model  
- Project-level data model for reusable structures
```

```yaml Configuration Steps theme={"dark"}
1. Define call-activity type node
2. Select subprocess to be called
3. Choose Data Mapper implementation (default)
4. Configure input/output mapping
5. Test mapping with example values
6. Save configuration
```

**1. Set Up Call Activity**

* In a process, define a **call-activity** type node
* Select the subprocess to be called
* **Data Mapping is now the default option**
* Toggle to "Switch to legacy mapping" if needed for backward compatibility

> [!NOTE]
>
> **Data mapping vs legacy mapping**
>
> The **Switch to legacy mapping** toggle picks between two mapping modes:
>
> * **Data mapping** (toggle **OFF**, the default): map each attribute visually in the mapping modal, driven by the declared data model, with a **Test** preview before storing. This is the mechanism this page documents.
> * **Legacy mapping** (toggle **ON**): the key-based mechanism used by configurations built before data mappers existed. Data is passed by key as-is, without the data-model-driven modal or the Test preview.
>
> Both modes work at runtime: legacy mapping is an alternative, not a deprecation. For the detailed comparison on message tasks, see [Legacy mapping vs data mappers](../node/message-send-received-task-node#legacy-mapping-vs-data-mappers).
>
> ![Data Mapping section of a call activity with the Switch to legacy mapping toggle turned off](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/legacy.png)

> [!NOTE]
>
> Existing actions that were configured before this update automatically retain legacy mapping—there is no need for you to modify them unless you want to switch to the new Data Mapping.

![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp7.png)

**2. Map Input Parameters**

* View the subprocess's input parameters
* Click the "key icon" next to the parameter

![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp8.png)

* **Source Component**: Current process (parent)
* **Destination Component**: Subprocess input parameters
* **Mapping Options**:
  * **Individual Mapping**: Map each attribute individually using interpolation syntax: `${variableName}`
  * **Auto-populate Mapping**: Select the data model types from dropdown for automatic mapping of all attributes
  * **Quick Mapping**: If source and destination have the same data type, use dropdown for automatic mapping of all attributes

> [!TIP]
>
> **Auto-populate Feature**: Instead of manually typing variable paths, select your data model types from the dropdown and the system will automatically populate all the mappings for you.

![Mapping modal with auto-populate dropdown selecting a data model type to fill all attribute mappings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp9.png)

![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/params_parent_process_dn.png)

* **Display Options**: You can view variables as schema or JSON format for better visualization
* **Variable Format**: When mapping manually, use interpolation syntax `${variableName}` - this format differs from process keys
* **Testing**: Click the "test" button to visualize the JSON payload using example values from your data model

![Test preview rendering the JSON payload built from the data model's example values](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dm13.png)

**3. Map Output Parameters**

* Select the **Output** tab
* View subprocess's output parameters
* Select attributes in parent process data model for storing output
* Map subprocess output parameters (source) to parent process parameters (destination)

![Define parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_output.png)

**JavaScript Transformation**:

To access JavaScript transformations, click the **function icon** next to the variable you want to transform.

* **Use JavaScript functions** for data transformation and combination
* **Syntax Requirements**: All computed values must use `return` statements
* **Example**: `return ${userVerification.status} + " on " + ${userVerification.verificationDate}`

![JavaScript transformation editor opened from the function icon, combining variables with a return statement](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/interpolation.png)

**Data Reference Syntax**:

* **Dynamic values**: Use `${variableName}` syntax to reference dynamic values (same as used for variable mapping)
* **Example**: `return ${approverName} + " approved on " + ${date}`

**Testing and Persistence**:

* **Testing**: Use test button to see transformed output with example values
* **Value Persistence**: Previous values are saved until you click "confirmation" and "save"
* **Error Handling**: JavaScript errors trigger when functions encounter issues (e.g., reading property from undefined object)

**Type Handling**:

* System sends configured data even with type mismatches (e.g., string to number)
* Always validate your transformations before saving

**4. Save Configuration**

Save the mapping configuration for both input and output

#### Asynchronous call activity

> [!NOTE]
>
> For async nodes, output cannot be mapped as the parent process doesn't wait for completion.

**1. Set Up Async Call Activity**

* Define **call-activity** node or **Start Subprocess** action on User Task
* Select subprocess to be called
* Check the **Run async** toggle

**2. Map Input Only**

* Choose Data Mapper implementation
* Map input parameters from parent process (source) to subprocess (destination)
* Save input mapping configuration

### Parallel multi-instance mapping

Use parallel multi-instance mapping when you need to start multiple subprocess instances simultaneously—one for each element in an array from the parent process.

> [!NOTE]
>
> **When to use**: This pattern is ideal for batch processing scenarios like processing multiple shipping orders, validating multiple documents, or handling multiple customer requests in parallel.

#### Configuration options

When **Parallel Multi-instance** is enabled on a Call Activity node or Start Subprocess action, configure these options:

| Option | Description |
| - | - |
| **Input Array** | The array from the parent process. Each element spawns a subprocess instance. |
| **Output Array** | The array in the parent process where subprocess results are collected. |
| **Correlation Attribute** | The attribute used to match subprocess results back to the correct parent array element. |

![Parallel multi-instance configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/call_activity_parallel_multi_instance.png)

#### Data mapping configuration

**1. Enable Parallel Multi-Instance**

* Open the **Call Activity** node or **Start Subprocess** action
* Enable the **Parallel Multi-instance** toggle

**2. Declare Arrays**

* **Input Array**: Specify the parent process array containing the data to process (e.g., `ordersList`)
* **Output Array**: Specify where to store the subprocess results (e.g., `processedOrdersList`)

**3. Configure Input Mapping**

* Click to open the mapping modal
* Map array element attributes to subprocess input parameters
* **Example**: Map `${item.orderId}` from parent array to `orderId` in subprocess

![Parallel multi-instance mapping](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pmi_mapping.png)

**4. Configure Output Mapping**

* Map subprocess output parameters back to the parent output array
* Each subprocess instance's result is added to the output array

**5. Set Correlation Attribute**

* Define which attribute correlates subprocess results with parent data
* This determines whether results **update existing** or **insert new** array elements

#### Correlation attribute behavior

When subprocess results return, the correlation attribute determines how data is handled:

> [card] Update Existing
>
> When the correlation attribute value **matches** an element in the parent array, that element is updated with the subprocess result.

> [card] Insert New
>
> When the correlation attribute value **doesn't match** any element in the parent array, the result is inserted as a new element.

#### Example: Processing shipping codes

**Scenario**: Process multiple shipping codes in parallel, determining package type for each.

**1. Prepare Parent Process Data**

Create an array of shipping codes using a business rule:

```java theme={"dark"}
import java.util.*;

def mapValues(shippingCode) {
    return {
        "shippingCode": shippingCode
    }
}

shippingCodeList = [];
shippingCodeList.add(mapValues("12456"));
shippingCodeList.add(mapValues("146e3"));
shippingCodeList.add(mapValues("24356"));
shippingCodeList.add(mapValues("54356"));
output.put("shippingCodeList", shippingCodeList);
```

**2. Configure Call Activity**

* Enable **Parallel Multi-instance**
* Set **Input Array**: `shippingCodeList`
* Set **Output Array**: `packageType`
* Set **Correlation Attribute**: `shippingCode`

**3. Map Input Parameters**

* Map `${item.shippingCode}` → subprocess `shippingCode` input parameter

**4. Subprocess Processing**

In the subprocess, process each shipping code:

```java theme={"dark"}
import java.util.*;

map = new HashMap();

if (input.item.shippingCode.startsWith("1")) {
    map.package = "Fragile";
} else {
    map.package = "Non-fragile";
}

map.shippingCode = input.item.shippingCode;
output.put("result", map);
```

**5. Result**

Each subprocess returns its result, which is collected in the parent's output array:

```json theme={"dark"}
{
    "package": "Non-fragile",
    "shippingCode": "54356"
}
```

> [!WARNING]
>
> **Array changes reset mappings**: When you modify the input or output array configuration and save, any existing mappings are automatically deleted. Reconfigure your mappings after changing array definitions.

> [!NOTE]
>
> **Sync mode behavior**: When parallel subprocesses run in sync mode and the parent process token advances (due to another action), unfinished subprocesses are automatically dismissed.

### Workflow integration mapping

Data mappers also connect a process to an [integration workflow](../../platform-deep-dive/integrations/integration-designer): the **Start Integration Workflow** action maps process data to the workflow's declared input parameters, and the Receive Message Task's data stream maps each workflow End node's output back to process attributes. Both sides also offer a **Legacy Mapping** mode that works with a hand-typed body or key instead.

For the mode comparison and the output-mapping configuration steps, see [Legacy mapping vs data mappers](../node/message-send-received-task-node#legacy-mapping-vs-data-mappers) on the Receive Message Task page.

The **Start Integration Workflow** action maps process data into the workflow's input parameters:

![Start Integration Workflow action on a Send Message Task, showing the input mapping panel for the selected workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-05-send-action.png)

The Receive Message Task's data stream maps each workflow End node's output back to process attributes:

![Receive Message Task Integration Output panel with Source set to Workflow, a selected workflow, and the output mapping for the End and End failure nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/dst_wkflw_workflow.png)

## Transforming arrays

When a parameter is an array, the data mapping panel maps it **wholesale**, you cannot map individual elements or sub-attributes from the UI. To filter, reshape, or compute over an array, switch to **function mode** by clicking the **f(x)** icon next to the parameter and use JavaScript on the resolved value.

> [!WARNING]
>
> The `${...}` interpolation syntax resolves a **path** to its value, it does not evaluate JavaScript inside the braces. Method calls like `${application.documents.filter(...)}` will fail. Place the placeholder first, then chain methods on the result.

**Default mapping** (pass the array through, no transformation):

```js theme={"dark"}
return ${application.documents};
```

**Filter an array**, keep only documents with `id` equal to 1:

```js theme={"dark"}
return (${application.documents} || []).filter(doc => doc?.id === 1);
```

**Map to a new shape**, extract a single field from each element:

```js theme={"dark"}
return (${application.documents} || []).map(doc => ({ documentId: doc.id }));
```

**Combine filter and map**:

```js theme={"dark"}
return (${application.documents} || [])
  .filter(doc => doc?.status === "APPROVED")
  .map(doc => doc.id);
```

> [!TIP]
>
> Always default to `|| []` when chaining array methods on a placeholder. If the source path resolves to `undefined` (parameter not yet populated), `.filter()` and `.map()` would throw, the empty-array fallback keeps the mapping safe.

## Testing and validation

### Testing methodology

**1. Use Example Values**

* Use example values from your data model for testing
* No need for separate mock data
* Values automatically populate in test scenarios
* **Auto-populate benefit**: Example values help visualize attribute meaning and expected data

**2. Test Payload Generation**

* Click "test" button to visualize JSON payload
* See exactly what data will be sent to destination component
* Verify transformations work as expected
* **Display formats**: View results as schema or JSON for better understanding

**3. Variable Mapping Validation**

* Verify interpolation syntax `${variableName}` is correctly formatted
* Test both manual mappings and auto-populated ones
* Ensure data type compatibility between source and destination

> [!NOTE]
>
> The interpolation format `${variableName}` used in Data Mappers differs from process key formats. Pay attention to this when manually entering variable paths.

**4. Apply Previous Session Information**

* Use information from previous sessions in testing
* Validate real-world scenarios
* Ensure data flows correctly end-to-end

**5. Testing subprocess data**

* When testing data coming from subprocesses, you need to check for the UUID instance of the subprocess and copy paste it in the instance field of the test data, as shown in the demo below:

<video />

### JavaScript transformation testing

> [accordion] Syntax Requirements
>
> * All computed values must include `return` statements
> * Use clear parameter notation (e.g., `userVerification.status`)
> * Functions must handle potential undefined values

> [accordion] Error Handling
>
> * System sends data even with type mismatches
> * JavaScript errors trigger for undefined object property access
> * Test transformations thoroughly before deployment

> [accordion] Value Persistence
>
> * Previous values are saved during configuration
> * Only lost upon clicking "confirmation" and "save"
> * Allows iterative testing and refinement

## Managing parameter changes

Different types of parameter changes require different handling - some propagate automatically while others need manual updates.

### Automatic propagation

These changes propagate automatically to input/output parameters and mappings:

> [card] Deleted Attributes
>
> **Automatic removal**: When you delete an attribute from the data model, it disappears from input/output parameters and mappings

> [card] Renamed Attributes
>
> **Automatic update**: When you rename an attribute in the data model, the change reflects in input/output parameters and mappings

### Manual intervention required

> [card] New Attributes
>
> **Manual addition**: When you add new attributes to the data model, you must manually:
>
> 1. Add them to input/output parameters
> 2. Configure them in the data mapper

### Data Model propagation timing

Propagation speed varies by data model type:

> [!NOTE]
>
> When you don't alter data type structure (e.g., adding attributes or changing types), updates propagate as follows:
>
> * **Project data model**: Immediately
> * **Library data model**: After the dependency build is updated

### Best practices for parameter changes

> [!WARNING]
>
> Always test your mappings after any data model changes to ensure they function correctly.

## Use cases

Configure data mappers for these scenarios:

> [accordion] Start Subprocess Action
>
> Mappings can be configured whether the subprocess is triggered from:
>
> * **Call Activity node**: Direct subprocess invocation within process flow
> * **User Task node**: Subprocess triggered by user interaction
>
> Both scenarios support full input and output parameter mapping capabilities.

> [accordion] Subprocess Execution Modes
>
> Data mappers handle different subprocess execution patterns:
>
> * **Synchronous execution**: Parent process waits for completion, enabling both input and output mapping
> * **Asynchronous execution**: Parent process continues without waiting, supporting input mapping only
> * **Single instance**: One subprocess instance per trigger
> * **Parallel multi-instance**: Multiple subprocess instances started simultaneously from an array. See [Parallel multi-instance mapping](#parallel-multi-instance-mapping) for detailed configuration.

> [accordion] Reusable UI Template Integration
>
> When integrating a pre-defined reusable UI template into a User Task node:
>
> * Map data from parent process to template input parameters
> * Configure template output to flow back to parent process
> * Enable consistent UI behavior across multiple processes

## Real-world examples

### Example 1: Monthly income collection

**Scenario**: A subprocess collects monthly income information from users and passes it back to the parent process.

**1. Subprocess Design**

* **UI Behavior**: Modal appears asking user to select currency and enter income amount
* **Data Collection**: User enters monthly income value
* **Requirement**: Pass collected data back to parent process

**2. Data Model Configuration**

**In the subprocess**:

* Add `monthlyIncome` variable to the data model
* Navigate to **Output Parameters** tab
* Define `monthlyIncome` as an output parameter

**In the parent process**:

* Initially no input parameters needed (not sending data to subprocess)
* Focus on receiving output data

**3. Call Activity Mapping**

* Open the **call activity** node in parent process
* Navigate to **Input and Output Parameters** section
* **Output mapping**: Connect subprocess output to parent process variable

**Variable format**: Use `${monthlyIncome}` (interpolation syntax)

> [!TIP]
>
> **Auto-mapping shortcut**: Select data model types from dropdown to automatically populate mappings instead of manual entry.

**4. Variable Renaming Example**

* **Subprocess variable**: `monthlyIncome`
* **Parent process variable**: `incomePerMonth` (renamed for clarity)
* **Mapping**: `${monthlyIncome}` → `incomePerMonth`
* **Result**: Two distinct data models successfully connected

### Example 2: Time-off approval with JavaScript transformation

**Scenario**: A colleague submits a time-off request, requiring approval with enhanced data transformation.

**1. Request Flow Design**

* **Input data**: Start/end dates, requester information
* **UI Behavior**: Modal shows request details with approve/deny options
* **Output requirement**: Return approval status + approver name

**2. Input Parameter Mapping**

* **Parent process sends**:
  * Approver name
  * Request details (start date, end date)
* **Subprocess receives**: Input parameters for display

**Configuration**: Parent process output parameters → Subprocess input parameters

**3. JavaScript Transformation for Output**

**Goal**: Combine approval decision with approver identity

* Click the **function icon** next to the output variable
* **Script example**:

```javascript theme={"dark"}
return ${approverName} + " approved on " + new Date().toISOString()
```

**Dynamic value syntax**:

* Use `${variableName}` to reference dynamic values: `${approverName}`

> [!WARNING]
>
> Always include `return` statements in JavaScript transformations.

**4. Testing Transformation**

* Click **test** button to preview transformed output
* Verify JavaScript logic with example data
* **Result**: Enriched data flows back to parent process

> [!NOTE]
>
> **Key Takeaway**: Data Mappers enable not just data transfer, but also data enrichment and transformation through JavaScript, making them versatile tools for complex business workflows.

## Best practices

> [card] Define Data Models Early
>
> Establish project and library data models before creating processes for maximum reusability

> [card] Use Example Values
>
> Include meaningful example values in data models to improve testing and configuration experience

> [card] Plan for Reusability
>
> Design data structures that can be shared across multiple components and processes

> [card] Test Thoroughly
>
> Validate mappings and transformations with various data scenarios before deployment

> [card] Document Dependencies
>
> Note any dependencies between mapped parameters and transformation logic

> [card] Use Quick Mapping
>
> Use quick mapping for components with identical data types to speed up configuration

## FAQs

> [accordion] Do parameter changes propagate automatically?
>
> **It depends on the change type**:
>
> * **Deleted attributes**: Automatically removed from mappings
>
> * **Renamed attributes**: Automatically updated in mappings
>
> * **New attributes**: You must manually add and configure them
>
> > [!WARNING]
> >
> > Always test your mappings after making parameter changes to ensure they still function correctly.

> [accordion] How do data mappers impact subprocess configuration?
>
> When you start a subprocess using Data Mappers:
>
> * **No need to configure "Append Data to Parent Process" action** in the subprocess anymore
> * For **synchronous subprocesses**: Output automatically flows back to parent process
> * For **asynchronous subprocesses**: You can configure input mapping, and the subprocess can append data back to the parent process asynchronously

> [accordion] How do you set up process parameters with multiple end nodes?
>
> You can define input and output parameters for each end node separately:
>
> * Navigate to **Data Model** → **Input/Output Parameters**
>
> * Select the specific node from the dropdown
>
> * Configure parameters independently for each end node
>
> > [!NOTE]
> >
> > Use this for processes with exclusive gateways where different entry points need different data structures.

> [accordion] What happens with currency variables in input mapping?
>
> **Known limitation**: When you send a currency variable with amount and code as input, the system doesn't transmit the code because inputs don't collect the code from currency fields.
>
> **Solutions**:
>
> * Set the code as optional in the output parameters, OR
>
> * Gather the code separately using a segmented button or other input method
>
> > [!WARNING]
> >
> > Handle this properly to avoid mapping errors.

## Current limitations

Current limitations to be aware of:

> [accordion] Start Subprocess for collection item
>
> * **Array to Object Mapping**: Cannot map array → object for scenarios when you edit or add an item in a collection *(estimated fix: 5.X Feature)*

> [accordion] Currency variable input mapping
>
> * **Currency Code Transmission**: When mapping currency variables as input, only the amount is sent - the currency code is not transmitted
> * **Workaround Required**: Either make code optional in output parameters or collect currency code through separate input methods

## Related documentation

> [card] [Call Activity Node](../../building-blocks/node/call-subprocess-tasks/call-activity-node)
>
> Learn about call activity nodes and subprocess execution

> [card] [Integration Designer](../../platform-deep-dive/integrations/integration-designer)
>
> Discover workflow automation and external system integration

> [card] [Data Model](../../building-blocks/process/data-model)
>
> Understand process data structure and management


# Process data model
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/data-model

Manage key-value attributes inside process definitions, supporting strings, numbers, booleans, objects, arrays, and enums.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/data_model_new.png)

## Overview

The Data Model serves as the foundation for managing structured information throughout your process definitions. It provides a centralized approach to define, organize, and maintain the data attributes that drive your business processes and user interfaces.

### Attribute types

The Data Model supports the following attribute types:

* STRING
* NUMBER
* CURRENCY
* BOOLEAN
* OBJECT
* ARRAY
  * ARRAY OF STRINGS
  * ARRAY OF NUMBERS
  * ARRAY OF BOOLEANS
  * ARRAY OF OBJECTS
  * ARRAY OF ENUMS
* ENUM
* DATE

#### Currency attribute

Currencies are managed using an object structure that ensures accurate representation and localization.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.36.00.png)

* **Currency Object Structure**:
  * Includes `amount` (numerical value) and `code` (ISO 4217 currency code, e.g., USD, EUR).
  * Example:
    ```json theme={"dark"}
    {
      "amount": 12000.78,
      "code": "USD"
    }
    ```
* **Regional Formatting**:
  * Currency values adapt to regional conventions for grouping, decimals, and symbol placement. For instance:
    * **en-US (United States)**: `$12,000.78` (symbol before the value, comma for grouping, dot for decimals).
    * **ro-RO (Romania)**: `12.000,78 RON` (dot for grouping, comma for decimals, code appended).
* **Fallback Behavior**: If the `code` is null, the system defaults to the locale's predefined currency settings.
* **UI Integration**:
  * Currency input fields dynamically format values based on locale settings and save the `amount` and `code` into the data store.
  * Sliders and other components follow the same behavior, formatting values and labels according to the locale.

> [card] [Localization and internationalization](../ui-designer/localization-and-i18n)
>
> Check this section for more details about l10n & i18n

#### Date attribute

Dates are represented in ISO 8601 format and dynamically formatted based on locale and application settings.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.44.33.png)

* **Locale-Specific Date Formats**: FlowX.AI dynamically applies regional date formatting rules based on the locale. For instance:
  * **en-US (United States)**: `MM/DD/YYYY` → `09/28/2024`
  * **fr-FR (France)**: `DD/MM/YYYY` → `28/09/2024`
* **Customizable Formats**: You can choose from predefined formats (e.g., short, medium, long, full) or define custom formats at both application and UI Designer levels.
* **Timezone Handling**:
  * **Standard Date**: Adjusts to the current timezone.
  * **Date Agnostic**: Ignores time zones, using GMT for consistent representation.
* **ISO 8601 Compliance**: Ensures compatibility with international standards.

> [card] [Localization and internationalization](../ui-designer/localization-and-i18n)
>
> Check this section for more details about l10n & i18n

#### Number attribute

The **Number** attribute type supports two subtypes: **integers** and **floating point numbers**, providing flexibility to represent whole numbers or decimal values as required.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.41.25.png)

* **Subtypes**
  * **Integer**: Represents whole numbers without any fractional or decimal part.
    * Example: `1, 42, 1000`
  * **Floating Point**: Represents numbers with a decimal point, enabling precise storage and representation of fractional values.
    * Example: `3.14, 0.01, -123.456`
* **Locale-Specific Formatting**:
  * Numbers adapt to regional conventions for decimal separators and digit grouping. For example:
    * **en-US (United States)**: `1,234.56` (comma for grouping, dot for decimals)
    * **de-DE (Germany)**: `1.234,56` (dot for grouping, comma for decimals)
    * **fr-FR (France)**: `1 234,56` (space for grouping, comma for decimals)
* **Precision Settings**:
  * **Minimum Decimals**: Ensures a minimum number of decimal places are displayed, adding trailing zeros if necessary.
  * **Maximum Decimals**: Limits the number of decimal places stored, rounding values to the defined precision.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2010.42.16.png)

> [!TIP]
>
> These settings can be overriden at the application level or in the **UI Designer** for specific components.

* **Validation**:
  * Enforce range constraints (e.g., minimum and maximum values).
  * Input fields automatically apply formatting masks to prevent invalid data entry.

> [card] [Localization and internationalization](../ui-designer/localization-and-i18n)
>
> Check this section for more details about l10n & i18n

## Data model interface

When you open the Data Model, the left-side **Data Types** panel is minimized by default. Expand it to browse, search, and filter your data types. Selecting a data type or connector on the canvas highlights its location and scrolls to the parent data type.

![Data Model interface with settings side panel](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/side_panel_overview.png)

***

## Creating and managing a data model

### Adding attributes to a data type

Each data type displays an **Add attribute** button for creating the first attribute. After the first attribute exists, the button appears only when you hover over the data type.

> [!TIP]
>
> **Key Naming Conventions**:
>
> * Keys in the data model are case-sensitive. This means 'customerName' and 'CustomerName' would be treated as two distinct attributes.
> * It's recommended to follow a consistent naming convention (such as camelCase) throughout your data model to avoid confusion.
> * Special characters and spaces in keys should be avoided.

When you add a new data type, a confirmation toast notifies you that it was successfully created.

### Attribute settings side panel

Selecting an attribute opens a **settings side panel** on the right with all configuration options for that attribute:

* **Type** — attribute type (string, number, boolean, object, array, enum, date, currency)
* **Validations** — required fields, range validation, pattern matching, custom validation
* **Sensitive data** — flag to hide values from process details and browser console
* **Reporting** — designate attributes for use in the reporting plugin
* **Example values** — provide sample values used in data mapping operations

> [!TIP]
>
> Example values remain as text input. Type-specific validators will be added in a future iteration.

### Attribute path

Each attribute displays a **path button** next to its name. Click it to view the full key path (for example, `customer.address.street`) and copy it to your clipboard. This is useful when referencing keys in business rules, UI component bindings, or integration mappings.

![Attribute path with copy button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/side_panel_overview.png)

### Validation rules

You can define validation rules for your data model attributes to ensure data integrity throughout your processes:

* **Required Fields**: Mark attributes that must have values before a process can proceed
* **Range Validation**: Set minimum and maximum values for numeric attributes
* **Pattern Matching**: Define regular expression patterns for string validation
* **Custom Validation**: Implement custom validation logic using business rules

> [!TIP]
>
> Validation rules can be defined at the data model level and enforced throughout UI components, business rules, and integration points, ensuring consistent data quality.

***

## Data model reference

The "View References" feature allows you to see where specific attributes are used within the data model. This includes:

* **Process Keys**: Lists all process keys linked to an attribute.
* **UI Elements**: Displays references such as the element label, node name, and UI Element key.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-18%2010.18.08.gif)

***

## Sensitive data

Protect sensitive information by flagging specific keys in the data model. This ensures data is hidden from process details and browser console outputs. You can configure this directly from the [attribute settings side panel](#attribute-settings-side-panel).

<video />

***

## Reporting

The **Use in Reporting** tag allows you to designate keys for use in the reporting plugin, enabling efficient tracking and analysis. You can configure this directly from the [attribute settings side panel](#attribute-settings-side-panel).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/dm_reporting.png)

> [card] [Reporting](../../platform-deep-dive/plugins/custom-plugins/reporting/reporting-overview)
>
> Learn more about how to use Data Model attributes in the Reporting plugin.

## Integration with other platform features

The Data Model serves as the backbone for numerous platform features, enabling consistent data flow between different components of your FlowX.AI application.

### Integration with UI Designer

The Data Model directly integrates with the UI Designer, allowing you to:

* Bind UI components to data model attributes
* Create dynamic UI layouts based on data model values
* Implement validation and formatting rules consistently across interfaces

### Integration with workflows

When designing workflows in the Integration Designer, you can use the Data Model to:

* Pass data from processes to workflows using the Start Integration Workflow action
* Map data between your process and external systems
* Transform and validate data during integration flows

> [card] [Workflow integration](../../platform-deep-dive/integrations/integration-workflows)
>
> Learn more about integrating Data Model with workflows

### Decision model integration

Data model attributes can be used as inputs for business rules, enabling:

* Complex business rule implementation using structured data
* Consistent data handling across decision points

## Best practices

### Structuring your data model

* **Use hierarchical structures**: Organize related data in nested objects to improve maintainability
* **Consistent naming**: Adopt a consistent naming convention for all attributes
* **Documentation**: Add clear descriptions for complex attributes to improve team understanding
* **Modularization**: Group related attributes into logical objects rather than using flat structures

### Version control and migration

When evolving your data model across versions:

* **Backwards compatibility**: Ensure changes don't break existing processes
* **Migration strategy**: Plan for how existing process instances will handle schema changes
* **Documentation**: Maintain clear documentation of data model changes between versions

## Troubleshooting

### Common issues

* **Missing data**: Ensure all required attributes are defined in your data model before referencing them
* **Type mismatches**: Verify that attributes are assigned the correct data type
* **Validation errors**: Check validation rules when data appears to be rejected

### Debugging tips

* Use the data model reference feature to track attribute usage
* Examine process instance data to verify attribute values
* Review UI component bindings to ensure proper data mapping

## Summary

The Data Model enables structured data management across your FlowX.AI applications. By following best practices for design, validation, and integration, you can build reliable process applications with consistent data handling throughout all stages of your business processes.


# Process design principles
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/design-principles

Foundational principles for designing FlowX processes. Covers modal usage, subprocess lifecycle, navigation, and platform behaviors.

## How to read this page

Every rule on this page is labeled with a **tier badge** (what kind of rule it is) and a **platform badge** (where it applies).

### Tiers

Must Breaks if ignored. Unsupported or code-enforced.

Recommendation Bad idea but works. No code guard, but you will regret it.

Platform behavior Factual platform difference. Not a ban. Something to design around.

Context-dependent Depends on platform or scenario. Read carefully.

### Platforms

Web Applies to web only.

Mobile Applies to mobile (iOS, Android) only.

Both Applies to both platforms.

***

## Guiding principles

These are the foundational principles that everything else on this page derives from. Keep them in mind as you design.

1. **Web is a single-page application.** It renders whatever is pushed to the DOM.
2. **Mobile maintains a navigation history.** Users can navigate back.
3. **The main process and its subprocesses share the same navigation.**
4. **Subprocesses started from User Task actions must be only optional and secondary flows**, meaning modals.
5. **Be very intentional about when user tasks stay in the main process vs. move to Call Activities.** Keep them in the main process when you want the user to be able to go back. Keep them in Call Activities when you don't want the user to be able to go back once the subprocess has finished.
6. **Modals must be displayed on top of existing content.** The main process must not start with a modal.
7. **Asynchronously started subprocesses cannot have user tasks.** Multiple sibling subprocesses cannot share the same navigation history at the same time. The current subprocess must finish before a new one begins.
8. **Subprocesses without UI must not contain subprocesses with UI.**
9. **On mobile, you can have navigation inside the same modal.** Use this when the screens refer to the same user task split across multiple screens. Avoid nesting modals.
10. **On web, only one modal can be displayed at a time.** Nesting modals replaces the previous modal, and you cannot return to it.

***

## Modal design

### Modals must overlay existing content

MustBoth

**Why.** A modal is rendered on top of existing content. If the process starts with a modal, there is nothing underneath. The modal becomes the only visible surface, which breaks its interruption semantics. It is also not in the back stack (see [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile)), so dismissing it from a first-screen position has no defined return target. The user experience cannot begin with a modal.

**Do this instead.** Make the first screen a **Page**. Open the modal over that Page when an interruption is actually needed (confirmation, acknowledgment, short focused task).

***

### Chaining modals: depends on platform and on whether subprocesses are involved

Context-dependentBoth

The "don't chain modals" rule is not absolute. It depends on where you are and what's in the chain.

**Why.**

* **Web:** opening a second modal replaces the first modal in the DOM. You cannot return to the first modal. If that loss of back-navigation is acceptable for your scenario, it's a valid design. If not, don't chain.
* **Mobile:** two "modals" can be the same modal with internal navigation between them. This is allowed when the screens represent steps of the same user task. Do **not** nest separate modals on top of each other.

**Do this instead.**

* **Same-task multi-step on mobile:** use internal modal navigation, not a second modal.

***

### Do not use modals as loaders

RecommendationBoth

**Why.** A modal is an interruption that requires the user to act. A loading state isn't. The user can't interact with "wait." Using a modal as a loader blocks the user unnecessarily and misuses the modal's interruption semantics.

**Do this instead.** Use the **Show loader** option on event handlers for action-scoped loaders, or replace the default loader UI with the renderer SDK's custom loader API.

**Custom loader APIs in the SDKs.** Each renderer SDK exposes a custom loader API so the container app can replace the default loader per scenario (start process, save data, resume, etc.). Use those instead of a modal:

* [React renderer: Custom loader](../../../sdks/react-renderer#custom-loader)
* [Angular renderer: Custom loader](../../../sdks/angular-renderer#custom-loader)
* [Android renderer: Custom loaders](../../../sdks/android-renderer#custom-loaders)
* [iOS renderer: Custom loader](../../../sdks/ios-renderer#fxdatasource)

***

### No modal over modal

Context-dependentBoth

**Why.**

* **Web:** only one modal can be displayed at a time. Nesting modals replaces the previous modal, and you cannot return to it (Guiding principle 10).
* **Mobile:** the OS automatically pops the current modal when the flow advances to the next screen (see [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile)). This is why two modals cannot be stacked on mobile at all. The recommended way to have navigation between modal-rendered screens is a single Modal navigation area with multiple User Tasks inside; mobile renders each User Task as a linked screen within the same modal.

**If you do nest modals, the choice must be intentional and the consequences understood.** On web, the previous modal is gone for good. On mobile, the OS auto-pops the first as soon as the second is pushed. Don't reach for nested modals as a shortcut.

**Do this instead.** On mobile, use internal modal navigation for same-task multi-step flows (one Modal nav area, two UTs). On web, use Pages or Stepper steps when you need to return to a previous screen.

***

### No two modals simultaneously

MustBoth

**Why.** Only one modal can be displayed at a time (Guiding principle 10). The renderer does not reliably handle concurrent modals.

**Do this instead.** Resolve the current modal before opening another.

***

### Modals are not navigation containers

MustBoth

**Why.** A modal must overlay existing content (Guiding principle 6). It is not a container for pages, steppers, tabs, or other navigation structures. Nesting navigation areas inside a modal breaks the Designer's render and dismiss logic.

**Do this instead.** Keep the modal as a leaf in the navigation tree. Put pages, steppers, and tab bars at the root of their respective zones, not inside a modal. See [Navigation best practices: What "child navigation areas" means](./navigation-best-practices#what-child-navigation-areas-means) for correct vs incorrect nav trees.

***

### Max modal depth is 1

MustBoth

**Why.** Direct consequence of Guiding principles 9 and 10, and of how the OS back stack treats modals on mobile (see [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile)). On web, a second modal replaces the first. On mobile, the OS auto-pops the first modal the moment the second would be pushed, so two modals never coexist. The only scenario that produces a nominal depth greater than 1 is nested Call Activities, where each activity contains its own modal; this is a hierarchy artifact, not modal stacking, and is not a reason to plan around depth greater than 1.

**Enforcement.** This rule is enforced by design, not by a runtime guard. The Designer will accept configurations with deeper modal nesting, and the template config will load, but the rendering behavior in those cases is unsupported. Don't rely on the platform to catch a depth violation.

**Do this instead.** Design to a single modal depth. If you need a multi-step flow on mobile inside a modal, use internal modal navigation. If you need multiple distinct screens, use a Stepper or Pages.

***

### No cyclic modal paths

RecommendationBoth

**Why.** There is no code-level cycle detection for modal paths. A process loop that returns to a modal already in the current navigation path can confuse the user's navigation history and mental model.

**Do this instead.** Resolve the modal before looping. If the modal is part of the main sequential flow, replace it with a Step.

***

### Modals are dismissed only by user interaction

MustBoth

**Why.** Modal lifecycle should be user-driven. A modal is an interruption; ending the interruption is the user's signal that they are ready to continue. Backend-driven auto-dismiss (timers, SSE events that the user didn't initiate, flow progression the user isn't aware of) breaks that contract.

**User-initiated chains are fine.** A dismiss that follows a user action is compliant, even when the close is delayed. Example: in UI Flows, a user clicks a button configured with Start Workflow and **Dismiss on completion**. The modal closes once the workflow finishes, but the dismiss is still a direct consequence of the user's click. That is not auto-dismiss.

**What to avoid.** Timer-based dismiss. Backend events that arrive independent of user action. Automatic close on flow progression without user acknowledgment.

**Do this instead.** Close modals via user triggers: confirm button, cancel button, close icon, backdrop click, or a user-initiated action whose completion dismisses the modal.

***

### Don't chain a modal user task to a Call Activity

MustBoth

**Why.** Invoking a Call Activity from inside a modal user task dismisses the modal. There is no restoration path: the modal is not brought back when the Call Activity finishes, and the user loses the interruption context.

**Do this instead.** Resolve the modal first, then advance to the Call Activity from the Page or Step underneath. Don't put the Call Activity trigger inside the modal itself.

***

## Subprocess design

### A child subprocess does not dismiss its parent

MustBoth

**Why.** The engine guarantees parent isolation. When a Call Activity or Embedded subprocess finishes, it signals the parent to continue, but does not terminate the parent. Dismissal does not cascade upward.

**Do this instead.** Treat a child's completion as a signal that resolves only the child. To propagate results up to the parent, use **Append Params to Parent Process** (to write into the parent's data model) or **Send data to user interface** with target **Parent process** (to push data into the parent's UI in real time).

***

### Call Activity subprocesses with Pages or Steppers appear in mobile back-nav

Platform behaviorMobile

**Why.** Mobile maintains a navigation history. When a Call Activity subprocess renders a **Page** or **Stepper**, those screens land in the shared back stack and the user can tap back into them while the subprocess is running. Modals, by contrast, are auto-popped on forward navigation and never appear in back-nav.

**What happens when the subprocess finishes.** The user is returned to the last screen of the parent process. The subprocess's screens are cleared from the back stack, so the user cannot return to them. See [Navigation back-stack behavior on mobile](./subprocess#navigation-back-stack-behavior-on-mobile) for the full mental model.

**Design for it.** Back-navigation targets should land on meaningful states, not orphaned or mid-step screens. Ask: "if the user taps back from the next screen, what makes sense to show them?"

**Context rule for modals after a Call Activity.** If a modal appears immediately after a Call Activity finishes, its context belongs to that Call Activity, not to the parent process. The user has not seen the parent's last screen for many screens; a modal referencing that parent context will feel disconnected. Either keep the modal inside the Call Activity, or make sure its content references what the user just completed.

***

### Avoid nesting a UI subprocess under a headless one

RecommendationBoth

**Why.** Subprocesses without UI should not contain subprocesses with UI (Guiding principle 8). When the immediate parent has no screens, the UI subprocess has no natural parent context, and the hierarchy becomes harder to read, maintain, and debug.

**Do this instead.** If a subprocess needs UI, its immediate parent should also have UI. Restructure so the UI subprocess is a sibling of the headless one, or promote the parent to have UI.

***

### UI subprocesses must start synchronously

MustBoth

**Why.** Asynchronously started subprocesses cannot have user tasks (Guiding principle 7). An async UI subprocess races with the parent's token advance, and the UI gets dismissed before the user can complete it.

**Do this instead.** Use sync mode for any subprocess that contains user tasks. Reserve async mode for headless subprocesses (service tasks, integrations, notifications).

***

### Starting a subprocess from a User Task action

MustBoth

**Why.** Subprocesses started from User Task actions must be only optional and secondary flows, meaning modals (Guiding principle 4). Mandatory UT actions that launch subprocesses block the flow if the subprocess cannot start.

**Do this instead.** Use modal-only navigation for the entry point, and keep the starting action **optional**. If the journey is mandatory, move it into a Call Activity on the main process, not behind a UT action.

***

## Related resources

> [card] [Navigation best practices](./navigation-best-practices)
>
> Practical guide for choosing between Pages, Modals, Steppers, Tab Bars, and Zones.

> [card] [Subprocess management](./subprocess)
>
> Configuring, starting, and executing subprocesses, including mobile navigation behavior.

> [card] [Navigation areas](./navigation-areas)
>
> Reference for all navigation area types and platform-specific capabilities.


# Navigation areas
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/navigation-areas

Navigation areas play a pivotal role in user interface design. They enhance the user experience by providing a structured, organized, and efficient way for users to interact with and explore various features and solutions.

> [card] [Stepper](#stepper)
>
> Sequential workflow navigation with progress tracking. Maximum 2 levels supported.

> [card] [Tab Bar](#tab-bar)
>
> Multi-section navigation. Must be root component on mobile platforms.

> [card] [Page](#page)
>
> Full-screen content display with wizard or single-page form options.

> [card] [Modal](#modal)
>
> Temporary overlay for focused tasks. Use sparingly on mobile.

> [card] [Zone](#zone)
>
> Layout container with headers/footers. Web-only feature.

> [card] [Parent Process Area](#parent-process-area)
>
> Subprocess hierarchy management and design organization.

> [!NOTE]
>
> This page covers navigation areas in **BPMN processes**, where user tasks are assigned to areas. [UI Flows](../ui-flows) use the same navigation area types (Page, Tab Bar, Zone, Modal) but configure them directly in the UI Flows Designer as UI assets, without user tasks.

> [!NOTE]
>
> In the navigation panel, the navigation hierarchy should be displayed beneath platform tabs, which include options for both web and mobile platforms. The default tab selected upon opening should be the web platform.

## User task requirements

> [!WARNING]
>
> **Critical Configuration Requirements**: All user tasks in your process must be included within navigation areas structure. It is a **misconfiguration** to have user tasks that are not associated with the navigation areas hierarchy.
>
> **Key Requirements:**
>
> * Every user task must be assigned to a navigation area
> * User tasks cannot be left empty - they must contain UI elements
> * All user tasks must be organized within the proper navigation hierarchy
>
> Failing to follow these requirements will result in runtime errors and poor user experience.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/nav_ares.gif)

## Platform-specific capabilities

### Web platform capabilities

* **Zone**: Used for organizing parts of screen with headers and footers
* **Zone/Page**: Supports wizard navigation and single-page form layouts
* **Tab Bar**: Optional placement and full navigation hierarchy support
* **Stepper**: Maximum 2 levels supported
* **Modal**: Full functionality with flexible usage patterns
* **Parent Process Area**: Complete subprocess design support

### Mobile platform capabilities

* **Tab Bar**: Must be positioned as first root navigation to define the entire application navigation structure
* **Stepper**: Maximum 2 levels supported
* **Modal**: Limited usage recommended (see recommendations below)
* **Parent Process Area**: Basic subprocess design support
* **Zone**: Not supported
* **Page**: Basic functionality only
* **1 User Task = 1 screen**: Mobile renders each User Task as its own screen. A multi-UT flow means multiple screens, one per task

### Platform support matrix

| Navigation Area | Web | Mobile | Platform-specific notes |
| - | - | - | - |
| **Zone** | ✅ | ❌ | Web only - used for organizing parts of screen |
| **Tab Bar** | ✅ | ✅ | Mobile: must be first root navigation for entire app structure |
| **Page** | ✅ | ✅ | Web: wizard navigation/single-page form support |
| **Stepper** | ✅ | ✅ | Maximum 2 levels across all platforms |
| **Modal** | ✅ | ✅ | Mobile: specific usage recommendations apply |
| **Parent Process Area** | ✅ | ✅ | Subprocess design and hierarchy management |

## Getting started

This section covers the essential tasks for working with navigation areas: creating, configuring, and managing them in FlowX.AI Designer.

### Creating navigation areas

To create a new navigation area, follow these steps:

**1. Access FlowX.AI Designer**

Open **FlowX.AI Designer** and either open an existing process definition or create a new one.

**2. Open Navigation View**

Toggle the navigation areas menu by clicking on **Navigation view**.

**3. Create New Area**

Select **Create New Area** to begin configuring your navigation structure.

> [!NOTE]
>
> Navigation configurations made on one platform (for example, Web) are not automatically duplicated to the other platform by default. You must copy or recreate them.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/creating_nav_areas.gif)

### Managing navigation areas

Once you've created a navigation area, you can manage it through the breadcrumbs menu, which provides these options:

> [accordion] Area settings
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/area_settings.gif)
>
> Use **Area Settings** to configure the following properties:
>
> * **Name** - a name for the navigation area element that is visible in the **Navigation menu**
>
> > [!NOTE]
> >
> > This does not represent the label for your navigation area (for example, for a step element) that would be visible in the process at runtime. To set the label for your element, use the UI Designer to edit it.
> > To do that, trigger the **Navigation View** menu, then navigate to your element and click on the breadcrumbs. Afterward, click "UI Designer."
>
> * **Alternative Flows** - There might be cases when you want to include or exclude process nodes based on some information that is available as a start condition.

> [accordion] UI Designer
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_designer_navigation_areas.gif)
>
> Use UI Designer to configure the following:
>
> * **Settings**:
>   * **Generic**: Properties available cross-platform (Web, Android and iOS), available for all platforms
>   * **Platform-specific configuration and styling**: For components across Web, iOS, and Android.

> [accordion] Copy/Paste
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/copy_paste_areas.gif)
>
> The "Copy Navigation Areas" feature allows you to replicate navigation hierarchies and elements between different platforms.
>
> > [!WARNING]
> >
> > The Copy/Paste Navigation Areas feature facilitates the duplication of navigation configurations within the same process definition and environment. It does not support copying across different process definitions or environments.

> [accordion] Delete an area
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/delete_area.gif)
>
> To delete a navigation area:
>
> 1. Access the **Navigation view** menu within the FlowX.AI Designer.
>
> 2. Choose the intended navigation area, then click on the breadcrumbs menu located on the right.
>
> 3. Select **Delete Area**.
>
> > [!WARNING]
> >
> > **Important**: Deleting the navigation area will also remove any associated child areas. Additionally, any user tasks contained within will be unassigned and relocated to the User Tasks section within the **Navigation view**.
> >
> > **Action Required**: After deleting a navigation area, you must reassign any unassigned user tasks to proper navigation areas. Leaving user tasks unassigned is a misconfiguration that will cause runtime issues.

## Navigation area types

Choose the right navigation area type based on your user interface needs and platform requirements.

### Quick reference

| Type | Use Case | Web Support | Mobile Support | Key Features |
| - | - | - | - | - |
| **Stepper** | Sequential workflows | ✅ | ✅ | Progress tracking, 2-level max |
| **Tab Bar** | Section switching | ✅ | ✅ (root only) | Parallel content access |
| **Page** | Full-screen content | ✅ | ✅ | Wizard/single-page modes |
| **Modal** | Focused tasks | ✅ | ✅ | Temporary overlays |
| **Zone** | Layout structure | ✅ | ❌ | Headers/footers (web only) |
| **Parent Process** | Subprocess design | ✅ | ✅ | Hierarchy management |

### Available navigation types

You can create the following types of navigation areas:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/UI_areas_types.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/navigation_types.gif)

### Stepper

Sequential workflow navigation that breaks down complex processes into logical, numbered steps.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/stepper.png)

**Key Features:**

* Progress tracking with visual indicators
* Return to previously visited steps
* Maximum 2 levels of nesting supported

> [!WARNING]
>
> **Stepper  Recommendation**: FlowX supports a maximum of **2 levels** of stepper navigation across all platforms. Design your processes with this limit in mind to avoid navigation complexity. If you need more levels, consider breaking complex flows into separate processes.
>
> > [!TIP]
> >
> > If you need more levels, consider breaking complex flows into separate processes.
> >
> > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/stepper_in_steps.gif)

You can also define a stepper in step structure with the possibility to track progress and also returning to a previously visited step (as you can see in the navigation areas in the example above).

#### Stepper in step example

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/stepper_in_steps.gif)

#### Steps

Steps are individual elements within a stepper, simplifying complex processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/steps_ui_t.png)

### Tab Bar

Multi-section navigation component that allows users to switch between different areas of content.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/tabs_view.gif)

**Key Features:**

* Parallel zone support within user tasks
* Quick switching between sections
* Support for nested tab structures

> [card] Parallel Zones
>
> The navigation Tab Bar offers specialized support for **parallel zones** within the same **user task**. This feature allows users to navigate effortlessly between different sections or functionalities.

> [card] Multiple Tabs
>
> Access multiple tabs within the tab bar for quick switching between various views or tasks.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/tab_bar_nav_area.png)

When setting up a tab bar zone in your BPMN diagram, ensure that you always initiate a parallel zone using **Parallel Gateway** nodes. This involves using one Parallel Gateway node to open the zone and another to close it, as demonstrated in the example above. This approach ensures clarity and consistency in your diagram structure, facilitating better understanding.

> [!WARNING]
>
> **Mobile Requirements**: On mobile devices, tab bars must be positioned as the **root component** in navigation and remain consistently visible, prioritizing ease of navigation.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/root_navigation_tab.png)

> [!NOTE]
>
> **Parallel scenarios must be independent.** Each parallel branch under a Tab Bar (and each Tab's content) should be a self-contained scenario, behaving as if it were its own process with no parallel siblings. Data can propagate between branches via normal FlowX mechanisms. Navigation cross-jumps between branches are not supported by design: the SDKs instantiate each branch with its own navigation scope, but there is no runtime firewall preventing cross-branch state leakage. Treat parallel branches as independent scenarios. See [Process design principles](./design-principles) for the full set of rules.

> [!NOTE]
>
> **What a Tab can contain on mobile.** Tabs can hold User Tasks and Modals. They cannot hold Pages, nested Tab Bars, or Zones. Keeping the hierarchy flat is intentional: the mobile renderer relies on the Tab Bar being the consistent root.

#### Tabs

Tabs are clickable navigation elements within the Tab Bar that allow users to switch between different sections or functionalities within an application.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/tabs_parallel.png)

Each tab could contain a user task or multiple user tasks that can be rendered in parallel.

> [!NOTE]
>
> You can also use [**Start embedded subprocess**](../node/call-subprocess-tasks/start-embedded-subprocess) nodes to render defined subprocesses as a tab. Check the [**Start embedded subprocess**](../node/call-subprocess-tasks/start-embedded-subprocess) for more details.

#### Tab bars inside tabs

In addition to regular tab bars, you have the option to implement nested tab bars, allowing for the display of another set of tabs when accessing a specific tab.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/nested_tab_bars.png)

To achieve this configuration, you'll need to create an additional parallel zone inside the previously created one for the main tab bar. This section should encompass the child tabs of the primary tab bar in your diagram. Once these child tabs are defined, close the parallel zone accordingly.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sub_tabs.png)

### Page

Full-screen content display that can contain multiple user tasks in parallel or sequential presentation.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/page_smth.gif)

A page could contain multiple user tasks displayed either in parallel (single page application) or one by one (wizard style).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_overview.png)

#### Navigation type (only for Web)

You have the possibility to add step-by-step or wizard-style navigation within a page (applicable when a page contains more than one User Task). This means you can navigate through the app in a guided manner, accessing each step within the designated area and page.

![Page navigation type options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_navigation_type.png)

* **Single page form** (default): The Web Renderer displays all User Tasks within the same page (in parallel).

![Single page form layout](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_single_page.png)

> [!TIP]
>
> For optimal navigation, we suggest utilizing cards to guide users through the content.
>
> > [!NOTE]
> >
> > To maintain a clean UI while displaying user tasks on a single page, use cards as the root UI elements and apply accordions to them. This allows you to collapse each card after it is validated by an action.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/cards_single_page_coll.gif)

> [!NOTE]
>
> Child areas will be rendered on the same page.

* **Wizard**: For the Wizard option, the Web Renderer will display one user task at a time, allowing navigation using custom Next and Back buttons.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/page_wizard.gif)

> [!TIP]
>
> Child areas will be presented sequentially. It's crucial to configure actions properly to ensure smooth user navigation.

### Modal

Temporary overlay that interrupts the main flow to present focused tasks or information.

![Modal Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal.gif)

Modals offer temporary control over user interaction within a process, typically appearing as pop-ups or overlays. They guide users through specific tasks before returning to the main functionality of the application or website.

To enable user interaction with a modal, you can configure it to be dismissable in two ways:

* Dismiss on backdrop click
* Display dismiss confirmation alert

Here's how to configure these options:

1. Navigate to your configured modal and access the UI Designer.

![Modal UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal_ui_designer.gif)

2. Select the modal and configure its content and behavior from the **Settings** and **Styles** panels:

   * **Settings → Title** and **Subtitle** — the heading text shown in the modal header.
   * **Settings → Dismiss Behavior:**
     * **Dismissible** — let users close the modal. On by default.
     * **Backdrop click** — allow closing by clicking outside the modal.
     * **Confirmation alert** — show a confirmation before closing; configure its **Title**, **Message**, **Confirm button label**, and **Cancel button label**.
   * **Styles → Layout → Alignment** — align the modal content **Left**, **Center**, or **Right**.
   * **Styles → Sizing** — set **Width** and **Height** to **Fixed** or **Auto**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal_configuration.png)

> [!NOTE]
>
> The modal's **shadow** and its **close (dismiss) icon** are defined at the theme level, in the **Modal** section of the theme editor — not per modal instance.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/modal_example.gif)

> [!NOTE]
>
> **Modal title or header.** The Modal navigation area itself has no built-in `title` property. The only title field available on a Modal is the **dismiss confirmation alert title** (shown when a user tries to close a dismissable modal). To display a title or header inside the modal content on any platform, including mobile, place a Text or Heading UI component as the first element of the modal's user task content.

### Zone

Web-only container for organizing layout with headers, footers, and structured content areas.

A Zone serves as a container designed to govern UI navigation by grouping specific elements together. Its optimal application is in scenarios involving processes featuring both a header and footer.

> [!NOTE]
>
> **Looking for Milestone nodes?** Zones replace the start and end Milestone nodes, which were removed in FlowX.AI 4.0. When a process definition created before 4.0 is migrated, its Milestone nodes become Zones.

#### Navigation type (only for Web)

You have the possibility to add step-by-step or wizard-style navigation within a specific zone (applicable when a zone contains more than one User Task). This means you can navigate through the app in a guided manner, accessing each step within the designated area and page.

* **Single page form** (default): The Web Renderer will display all User Tasks within the same zone.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/single_page_form.png)

> [!TIP]
>
> For optimal navigation, we suggest utilizing cards to guide users through the content.

> [!NOTE]
>
> Child areas will be rendered on the same page.

* **Wizard**: For the Wizard option, the Web Renderer will display one user task at a time, allowing navigation using custom Next and Back buttons.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/wizard.gif)

> [!TIP]
>
> Child areas will be presented sequentially. It's crucial to configure actions properly to ensure smooth user navigation.

> [!WARNING]
>
> Zones with headers and footers are exclusively accessible in web configurations. They are not supported as navigation areas for mobile development.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header_footer.png)

#### How to Create a Header/Footer Zone

To establish a header/footer zone, follow these steps:

1. Begin by opening a new parallel zone and ensure to close it where you want the header/footer zone to end.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header%3Afooter_parallel.gif)

2. Introduce two new user tasks nodes within your process, designated to function as the header, respectively as footer.
3. Connect the first parallel gateway node to both of them.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/connect_header_footer.png)

4. Now connect the header and footer user tasks to the closing Parallel Gateway.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/connect_with_closing.gif)

3. In the navigation areas menu, incorporate a new zone labeled "Header Zone" and a new zone "Footer Zone".
4. Position the header at the top of your navigation structure or at the top within your primary navigation element and the footer at the bottom.
5. Assign the user tasks to the "Header Zone" and to the "Footer Zone".

> [!NOTE]
>
> When working with containers directly within navigation zones, you have the flexibility to set the sticky/static property directly on your specific navigation zone using the UI Designer, without having to add specific user tasks. However, determining the best practice depends on the specific use case you're aiming to implement.
> For instance, if you're looking to incorporate footers containing actions or buttons such as "Cancel application" or "Continue," it's advisable to include user tasks, allowing you to configure node actions effectively.
>
> > [!TIP]
> >
> > On the other hand, if your goal is to integrate static headers and footers featuring branding assets and external URLs, it's simpler to directly add them to the navigation areas. In this scenario, you can effortlessly incorporate images or text with external URLs on your containers styling.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header_footer_blaa.png)

6. Proceed to customize the user tasks UI according to your preferences.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/header_footer_custom.gif)

#### Styling options

To customize the appearance of headers and footers, you need to utilize containers as the root UI elements for **user tasks** or navigation areas.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_ui.png)

You have two styling options available for these containers:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_configuration.gif)

* **Static**: This style remains fixed and does not scroll along with the page content.
* **Sticky**: When the sticky property is enabled, the container maintains its position even during scrolling.
  * **Layout**: You have the option to specify minimum distances between the container and its parent element while scrolling. At runtime, sticky containers will keep their position on scroll relative to top/ bottom/ right/ left margin of the parent element

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Screenshot%202023-12-13%20at%2017.18.39.png)

> [!NOTE]
>
> In mobile configurations, the right and left properties for sticky layout are ignored by the mobile renderer.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_demo.gif)

### Parent Process Area

Specialized container for managing subprocess design within parent process hierarchies.

**Use Cases:**

* Subprocess organization
* Hierarchy validation
* Design restriction enforcement

## Warnings

If you do not assign a user task to a navigation area, the platform will display a warning indicating that there are user tasks not included in the navigation structure (applies to all platforms).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wrn.png)

### Why does a user task say it is not ordered accordingly in the Navigation Hierarchy?

The full warning reads:

> The content won't display correctly because preceding nodes in the BPMN diagram are not ordered accordingly in the Navigation Hierarchy.

FlowX compares the order of user tasks in the BPMN diagram with the order of their navigation areas. When one user task follows another in the process flow, its navigation area must also come after the earlier task's navigation area in the Navigation Hierarchy. If it comes before, the later user task gets this warning, because at runtime the screens would appear in a different order than the process reaches them. Embedded subprocesses are checked the same way as user tasks.

The check runs separately for the web and mobile hierarchies, so the warning can apply to one platform or to both. It skips:

* User tasks that are not assigned to a navigation area (these get the unassigned warning instead)
* User tasks whose areas sit side by side inside the same **Tab Bar**, since tabs are meant to be used in parallel

To clear the warning:

**1. Open Navigation View**

Open the process definition and click **Navigation view**. Switch to the platform (web or mobile) the warning applies to.

**2. Find the flagged user task**

Locate the navigation area that contains the user task named in the warning, and the area that contains the user task right before it in the BPMN diagram.

**3. Reorder the areas**

Drag the flagged area so it sits after the earlier task's area, or move the user task into an area that comes later in the hierarchy. If the navigation order is the one you want, change the sequence in the BPMN diagram instead.

FlowX re-runs the check whenever the process diagram or the Navigation Hierarchy changes, and removes the warning once the two orders match.

## Best practices and recommendations

> [card] [Navigation best practices guide](./navigation-best-practices)
>
> Detailed guidance on choosing between pages and modals, valid nesting combinations, common scenarios (phone verification, confirmations, multi-step forms), and anti-patterns to avoid.

### User task configuration requirements

> [!WARNING]
>
> **Mandatory User Task Organization**: Every user task in your process definition must be properly organized within navigation areas:
>
> * **Complete coverage**: All user tasks must be assigned to navigation areas - unassigned user tasks indicate a misconfiguration
> * **Non-empty user tasks**: User tasks must contain UI elements and cannot be left empty
> * **Proper hierarchy**: Organize user tasks within the appropriate navigation area hierarchy based on your process flow
>
> These requirements are essential for proper process execution and user experience.

### Mobile platform recommendations

* **Modal usage**: FlowX strongly recommends the use of modals only when you need to temporarily interrupt the normal (root) flow of the app, to present a focused task or message to the user, requiring the user to interact with it before returning to the main flow.
* **Important**: If finishing a task in a modal leads to navigating to another screen, and not just dismissing the modal, then the modal should be a root navigation area.
* **Tab bar implementation**: On mobile, tab bars must be positioned as first root navigation to define the entire application navigation structure and remain consistently visible.

### Cross-platform guidelines

* **Stepper complexity**: Maximum 2 levels supported across all platforms. Break complex flows into separate processes if more levels are needed.
* **Design approach**: Start with mobile constraints first, then enhance for web. Keep navigation structures simple and flat with clear visual indicators.
* **Web-specific features**: Use zones with headers and footers for comprehensive layouts. Use wizard navigation for complex processes and take advantage of larger screen real estate.

## Advanced features

### Demo and learning resources

For more information, you can also check the following demo on our Academy website:

> [card] [FlowX.AI Navigation view](https://academy.flowx.ai/explore/flowxai-navigation-view)

### Alternative flows

There might be cases when you want to include or exclude process nodes based on some information that is available at start.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/alternative_flows.png)

> [!TIP]
>
> For example, in case of a bank onboarding process, you might want a few extra BPMN nodes in the process in case the person trying to onboard is a minor.

For these cases, we have added the possibility of defining **alternative flows**.

For each navigation area or node, you can choose to make it available only in specific alternative flows. In the example below, we will create two alternative flows in which we will include two different steppers and one modal without being part of an alternative flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/adding_alternative_flows.gif)

When starting a process, you must mention for the which flow the process will be initiated using the "navigationFlow" parameter and the name of the alternative flow:

```json theme={"dark"}
{"navigationFlow": "First Flow"}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/alternative_flows_ex.gif)

> [!NOTE]
>
> If a node is not assigned to an alternative flow, this means the node will be included in all possible flows.
>
> > [!TIP]
> >
> > A node could also be a part of multiple flow names.

> [!TIP]
>
> When configuring alternative flows in the main process, remember that they will also be applied in any embedded subprocesses with identical names.


# Navigation best practices
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/navigation-best-practices

Guidelines for choosing the right navigation patterns, understanding valid combinations, and avoiding common misconfigurations in FlowX process design.

## Choosing the right navigation pattern

Picking the correct navigation area type is one of the most impactful decisions in process design. A wrong choice leads to broken flows, inconsistent behavior across platforms, and poor user experience.

Use this guide to decide **when** to use each navigation type and **how** to combine them correctly.

***

## Before you start

The foundational principles and per-rule classification (tier, platform, why, alternative) live on a dedicated page. Read them first, then come back here for practical decisions on how to combine patterns.

> [card] [Process design principles](./design-principles)
>
> Guiding principles, modal rules, and subprocess rules with platform tags and examples.

***

## Page vs modal: the core decision

The most common mistake is using a modal when a page is needed, or chaining modals together. Whether modal chaining is acceptable depends on the platform — see [Chaining modals](./design-principles#chaining-modals-depends-on-platform-and-on-whether-subprocesses-are-involved) for the full rule. Here is how to decide between page and modal:

> [tab] Use a Page when...
>
> * The user needs to **complete a full step** in a flow (data entry, review, confirmation)
> * The content is **part of the main journey** and not an interruption
> * The user might need to **navigate back** to this screen
> * The flow involves **multiple sequential tasks** (use Wizard navigation type)
> * The content is **complex or long** (forms, tables, document reviews)
>
> **Examples:** Personal data form, account setup steps, document upload, application review

> [tab] Use a Modal when...
>
> FlowX strongly recommends the use of modals only when you need to temporarily interrupt the normal (root) flow of the app, to present a focused task or message to the user, requiring the user to interact with it before returning to the main flow.
>
> * The user needs to handle a **brief, focused interruption** before returning to the main flow
> * The task is **self-contained** and resolves with a single action (confirm, dismiss, acknowledge)
> * You need to show a **confirmation dialog** ("Are you sure?")
> * You need to display **supplementary information** without losing context (terms & conditions, help text)
>
> **Examples:** Confirmation dialogs, terms acceptance, single-field verification-code input, informational pop-ups

### Quick decision flowchart

Ask yourself these questions in order:

**1. Is it a temporary interruption?**

If the user will **do one thing and return** to where they were, consider a **Modal**.

If the user is **progressing to a new step** in the flow, use a **Page** (or Step in a Stepper).

**2. Does it lead to another screen?**

If finishing a task in a modal leads to navigating to another screen, and not just dismissing the modal, then the modal should be a root navigation area.

> [!WARNING]
>
> This is the most common mistake. If your modal opens another modal or navigates to a page after completion, it should not be nested inside another navigation area.

**3. Is the content complex?**

If the screen has **multiple form fields, validation logic, or scrollable content**, use a **Page**.

Modals work best for **simple, focused interactions** (1-3 fields maximum).

**4. Does the user need to go back?**

Modals have **no back navigation**. If users might need to return to this screen from a later step, it must be a **Page** within a Stepper or Wizard.

***

## Modal rules

For the full set of modal rules (tier, platform, why, and alternatives), see [Process design principles → Modal design](./design-principles#modal-design).

A modal should not contain child navigation areas. It can contain user tasks and trigger workflows (including via On Load events), but it is not a container for pages, steppers, or other navigation structures.

### What "child navigation areas" means

In the Designer's **Navigation view**, you build a tree of navigation areas. **Child navigation areas** are areas nested inside a parent. Here is what a correct vs incorrect navigation tree looks like:

> [tab] Correct
>
> ![Correct navigation structure — modal as leaf under a step](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigation_best_practices_correct.png)
>
> The modal sits under a Step as a **leaf** — it contains user tasks but no child navigation areas.
>
> ```
> 📂 Zone 1
> └── 📋 Stepper 1
>     ├── ─○ Step - "Personal Data"
>     ├── ─○ Step - "Documents"
>     └── ─○ Step - "Review"
>         └── 🪟 Modal - "Confirm Submit"    ← leaf, no child areas
> ```
>
> The modal is triggered as a brief interruption (e.g., "Are you sure?") and dismissed to return to the step.

> [tab] Incorrect
>
> Here the modal is used as a **navigation container** with areas nested inside it. The Designer allows this, but it causes rendering and dismiss behavior issues.
>
> ```
> 🪟 Modal - "Verification flow"
> └── 📂 Zone                                ❌ zone nested inside modal
>     └── 📋 Stepper
>         ├── ─○ Step - "Enter code"         ❌ flow steps inside modal
>         └── ─○ Step - "Verify code"
> ```
>
> Another common mistake: using multiple separate Modal navigation areas as sequential flow steps:
>
> ```
> 📄 Page - "Enter Phone"
> 🪟 Modal - "Sending..."                    ❌ modal used as loader
> 🪟 Modal - "Enter code"                    ❌ second separate modal in sequence
> 📄 Page - "Confirmation"
> ```
>
> For multi-step interactions that must stay inside a modal on mobile, use **one** Modal navigation area with multiple User Tasks inside, not two separate Modal areas. See [Chaining modals](./design-principles#chaining-modals-depends-on-platform-and-on-whether-subprocesses-are-involved).

> [!WARNING]
>
> **Rule of thumb:** A modal can contain user tasks, but never other navigation areas. Don't nest pages, steppers, tabs, or other modals inside it.

### How modals fit in the navigation flow

A modal should overlay the current screen as a **temporary interruption** and return to the same context when dismissed:

```
Main flow:  [Page A] → [Page B] → [Page C]
                          ↓ ↑
                        [Modal]     ← brief interruption, returns to Page B or advances to Page C
```

Do **not** chain separate modals as sequential steps in the navigation:

```
❌  [Page] → [Modal A] → [Modal B] → [Page]     ← two separate Modal navigation areas
❌  [Page] → [Modal] → [Page] → [Modal]         ← modals are not steps in a flow
```

What actually happens depends on the platform:

* **Web:** opening a second modal replaces the first in the DOM. You cannot return to the first modal. If that loss of back-navigation is acceptable, it is a valid (though discouraged) design.
* **Mobile:** the OS auto-pops the current modal on forward navigation, so two separate modals cannot coexist. **For multi-step interactions inside a modal**, put multiple User Tasks inside a **single Modal navigation area** — mobile renders each User Task as a linked screen within the same modal with a built-in back button. This is the recommended pattern, not a workaround.

See [Chaining modals](./design-principles#chaining-modals-depends-on-platform-and-on-whether-subprocesses-are-involved) and [Max modal depth is 1](./design-principles#max-modal-depth-is-1) for the canonical rules.

> [!NOTE]
>
> In **UI Flows**, modals are navigation areas that you navigate to using the **Navigate To** action. The modal adds a `modalId` to the URL, which supports deep linking and survives page refresh. Use the **Dismiss modal** option or browser back to close.

***

## Valid navigation combinations

### Navigation area nesting reference

The table below shows what the Designer allows you to add as child areas, and what you should actually use.

| Parent area | Designer allows | Recommended use |
| - | - | - |
| **Root** (blue +) | Stepper, Tab Bar, Page, Modal, Zone, Parent Process | Web: start with Zone for header/footer layouts, or Page/Stepper for simpler flows. Mobile: Tab Bar must be root for multi-section apps; otherwise Page or Stepper |
| **Zone** | Zone, Stepper, Tab Bar, User Tasks, Embedded Subprocess | Stepper for multi-step flows, Tab Bar for section-based layouts |
| **Stepper** | Step | Add one Step per stage in the flow |
| **Step** | Stepper, Modal, Zone, Tab Bar, User Tasks, Embedded Subprocess | One User Task per Step on mobile (1 UT = 1 screen) |
| **Tab Bar** | Tab | One Tab per section |
| **Tab** | Zone, Modal, Tab Bar, User Tasks, Embedded Subprocess | Zone or Tab Bar for complex tab content (web); on mobile, prefer User Tasks or Modal |
| **Page** | Modal, Zone, Tab Bar, User Tasks, Embedded Subprocess | Modal for brief interruptions only |
| **Modal** | Zone, Tab Bar, User Tasks, Embedded Subprocess | **Don't nest navigation areas under modals** — treat as leaf |

The Designer offers Zone and Tab Bar as child areas only on the Web platform. On Android and iOS, the other allowed children stay the same, and further platform differences appear at runtime in the mobile renderers.

> [!WARNING]
>
> **Mobile-specific behavior to design around:**
>
> * **Tab Bar must be the root navigation area on mobile.** If it appears anywhere else, the renderer will not behave correctly.
> * **Zone is not rendered on mobile.** On web it gives header/footer layouts; on mobile it is treated as a Page. Plan for this.
> * **One User Task per Page, Step, Tab, or Modal on mobile.** Mobile renders 1 UT as 1 screen, so multiple UTs under the same area is a misconfiguration.
> * **Nested navigation areas inside a Modal** are unsupported on mobile (iOS does not render them; Android renders them but the user experience is unpredictable). Treat the modal as a leaf.

### Patterns that work

> [card] Zone with Stepper (web only)
>
> Zone (header/footer) containing a Stepper with Steps. Each Step holds user tasks with form content.
>
> **Use for:** multi-step flows with persistent header/footer on web. Not available on mobile, where Zone is not rendered (treated as a Page).

> [card] Stepper with confirmation Modal
>
> Stepper with Steps for each stage. One Step contains a Modal for a brief confirmation before submission.
>
> **Use for:** forms that need an "Are you sure?" prompt before submit.

> [card] Page with Wizard navigation (web only)
>
> Single Page area with Wizard navigation type. Displays user tasks one at a time with Next/Back buttons.
>
> **Use for:** sequential data entry without visible step indicators on web. Not available on mobile (Wizard navigation does not exist).

> [card] Tab Bar with Tabs
>
> Tab Bar at root level with Tabs for each section. Each Tab can contain its own content and actions.
>
> **Use for:** Multi-section apps where users switch between areas.

### Patterns that break

> [card] Modal chain (two separate modals)
>
> Two separate Modal navigation areas chained sequentially. On web the second replaces the first in the DOM; on mobile the OS auto-pops the first.
>
> **Fix on web:** use Stepper steps or Wizard pages. **Fix on mobile:** put multiple User Tasks inside a single Modal navigation area (internal modal navigation).

> [card] Modal as flow step
>
> Page → Modal → Page where the modal is a step in the journey, not an interruption.
>
> **Fix:** Replace the modal with a Page or Step.

> [card] Modal as loader
>
> Opening a modal to show a loading spinner while a backend operation completes.
>
> **Fix:** Use the loading state properties on UI components (loader overlays, skeleton screens).

> [card] Deep nesting
>
> Zone → Stepper → Stepper → Stepper (more than 2 levels of stepper nesting).
>
> **Fix:** Break the flow into separate processes or subprocesses.

> [card] Cyclic modal path
>
> A process cycle that loops back into a modal already in the current navigation path.
>
> **Fix:** Resolve the modal before re-entering the loop, or replace the modal with a Page or Step.

> [card] Close-modal → open-modal
>
> One event that both dismisses the current modal and opens another.
>
> **Fix:** Split into two user-triggered actions, or replace with a Page/Step transition.

> [card] Modal → Call Activity
>
> A modal user task that triggers a Call Activity. The modal is dismissed and not restored when the Call Activity completes.
>
> **Fix:** Resolve the modal first, then transition to the Call Activity from a Page or Step.

> [card] Auto-dismissed modal
>
> A modal that closes on a timer, backend event, or automatic flow progression rather than user interaction.
>
> **Fix:** Require an explicit user action (confirm, cancel, dismiss button, backdrop click) to close the modal.

***

## Common scenarios

### Phone verification with a sent code

> [tab] Recommended
>
> Use a **Stepper** or **Page with Wizard** navigation:
>
> 1. **Step 1 (Page):** user enters phone number
> 2. **Step 2 (Page):** user enters the verification code with a resend option
> 3. **Step 3 (Page):** confirmation, next step in the flow
>
> Each step is a proper page with back navigation support and clear progress indication.

> [tab] Avoid
>
> ❌ Page (enter phone) → Modal (show "sending code" loader) → Modal (enter code) → Page (confirmation)
>
> This chains modals as flow steps and uses a modal as a loader. It will not work correctly.

### Confirmation before submission

> [tab] Recommended
>
> Use a **Modal** for the confirmation dialog:
>
> 1. User completes the form on a **Page**
> 2. User clicks **Submit**
> 3. A **Modal** appears: "Are you sure you want to submit?"
> 4. User confirms → modal dismisses → process continues
>
> The modal is a brief interruption with a single action.

> [tab] Avoid
>
> ❌ Navigating to a separate confirmation **Page** for a simple yes/no question wastes a navigation step.
>
> ❌ Using a modal that then opens *another* modal for success/error feedback.

### Terms and conditions

> [tab] Recommended
>
> Use a **dismissable Modal**:
>
> 1. User reaches a step that requires accepting terms
> 2. User clicks "View Terms" → a **Modal** opens with the full text
> 3. User reads and dismisses the modal
> 4. User checks the acceptance checkbox on the **Page** and continues
>
> Configure the modal as dismissable (backdrop click or close button).

> [tab] Avoid
>
> ❌ Making the terms page a full navigation step in the Stepper, forcing the user through it sequentially.
>
> ❌ Embedding long scrollable legal text directly in the form page.

### Multi-section dashboard

> [tab] Recommended
>
> Use a **Tab Bar** with **Pages** for each section:
>
> * Tab 1: Account overview (Page)
> * Tab 2: Transaction history (Page)
> * Tab 3: Settings (Page with Wizard if multi-step)
>
> On mobile, the Tab Bar must be the root navigation area.

> [tab] Avoid
>
> ❌ Using modals to show different sections.
>
> ❌ Nesting Tab Bars more than 2 levels deep.

***

## Navigation selection guide

| Scenario | Navigation type | Why |
| - | - | - |
| Multi-step form with progress | **Stepper** | Users see where they are and can go back |
| Sequential tasks without step indicators | **Page (Wizard)** | Guided flow with Next/Back, no visible steps |
| All fields on one screen | **Page (Single page form)** | Parallel display, use cards to group sections |
| Brief confirmation or acknowledgment | **Modal** | Quick interruption, single action, dismiss and return |
| Supplementary info (help, terms) | **Modal (dismissable)** | Read-only content that doesn't affect the main flow |
| Multi-section app | **Tab Bar** | Parallel access to different areas |
| Persistent header/footer (web) | **Zone** | Layout container for branding and global actions |

***

## Related resources

> [card] [Navigation areas](./navigation-areas)
>
> Configuration reference for all navigation area types.

> [card] [UI Designer best practices](../ui-designer/best-practices)
>
> General best practices for building interfaces.


# Passing data between nodes
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/passing-data-between-nodes

How outputs from subprocesses, workflows, AI agents, and business rules land in process variables, and how downstream nodes read them.

## Overview

Inside a BPMN process, every node, including subprocess, integration workflow, AI agent, business rule, and user task, reads from and writes to a shared store of **process variables** (also called *process instance data* in code).

This page explains the mental model: where each node type's output lands, and how the next node, or a user task screen, reads it. For the configuration syntax of any specific mapping, follow the links to the dedicated pages.

> [!NOTE]
>
> If you are calling FlowX from an external app (React frontend, another backend service) and want to fetch a process result over HTTP, that is a different question. See [Consuming FlowX from external apps](../../platform-deep-dive/integrations/consuming-flowx-from-external-apps).

***

## The mental model

A process variable is a key on the process instance data store. Every node configures:

* **Input mapping**: which existing process variables to send into the node, or how to compute them.
* **Output mapping or key name**: where the node's output is written back into the process variables.

After the node finishes, downstream nodes and any user task screens that follow can read the result by referencing that key.

```
       ┌──────────────────────────────────────────────────────────┐
       │              Process variables (shared store)             │
       └──────────────────────────────────────────────────────────┘
              ▲                ▲                ▲              ▲
              │ output         │ output         │ output       │ read
              │                │                │              │
        ┌─────┴─────┐    ┌─────┴─────┐    ┌─────┴─────┐  ┌─────┴─────┐
        │ Subprocess│    │ Workflow  │    │ AI agent  │  │ User task │
        └───────────┘    └───────────┘    └───────────┘  └───────────┘
```

***

## Choose the right pattern

| If you need to… | Use this node | Where its output lands | Reference |
| - | - | - | - |
| Run a stateful, multi-step BPMN flow with its own user tasks | Subprocess (call activity) | Mapped into parent variables via Data Mapper | [Data mappers](./data-mappers) |
| Call an integration workflow (REST, DB, AI ops) and capture the result | Send Message Task with **Start Integration Workflow** action | Mapped into process variables by the **Receive Message Task** that waits for the workflow | [Start Integration Workflow](../actions/start-integration-workflow) |
| Call an AI agent (extraction, decision, generation) | Service Task with the agent integration | Mapped back to process variables in the action's output mapping | [BPMN integration with agents](../../../ai-platform/using-agents/bpmn-integration) |
| Compute or transform values inline | Business Rule action | Writes to keys passed to `output.put(key, value)` | [Business rule action](../actions/business-rule-action/business-rule-action) |

***

## The Receive Message Task pattern (workflows)

This is the part most people miss the first time.

When a process triggers an integration workflow with **Start Integration Workflow**, the process must wait for the workflow to finish before reading its output. To wait, place a **Receive Message Task** after the Send Message Task that triggers the workflow.

**1. Add a Send Message Task**

Configure it with the **Start Integration Workflow** action: select the workflow and map its input. The action has no output setting; the output is configured on the next node.

**2. Add a Receive Message Task immediately after**

The process pauses on this node until the workflow completes. In its **Data Stream** configuration, set the source to **Workflow** and select the workflow. Then choose where the output lands: map each End node's output with **Output Mapping** (the default), or turn on **Legacy Mapping** and set a single **Key Name**.

**3. Read the result downstream**

Any node after the Receive Message Task, including gateway, business rule, and user task, can read the mapped output from process variables.

For the full configuration walkthrough, see [Start Integration Workflow → Receiving output](../actions/start-integration-workflow#receiving-output) and [Send/Receive Message Task nodes](../node/message-send-received-task-node).

> [!NOTE]
>
> **For AI agents:** the integration is typically wired on a Service Task, and the agent's response is mapped back to process variables in the action's output mapping. No separate Receive Message Task is required. See [BPMN integration with agents](../../../ai-platform/using-agents/bpmn-integration).

***

## Reading process variables downstream

Once a value is in process variables, the way you reference it depends on where you are reading from:

* **In another node's input mapping** (Send Message Task action, agent input, etc.): use the placeholder syntax documented on that node's page. Example for workflow input mapping: select `customer.id` as the source path in **Input Mapping**, or write `${customer.id}` with **Legacy mapping** turned on (see [Start Integration Workflow → Input mapping](../actions/start-integration-workflow#input-mapping)).
* **In a subprocess's Data Mapper**: use `${variableName}` against the subprocess's defined Input Parameters. The Data Mapper is the canonical interface for parent ↔ subprocess data flow (see [Data mappers](./data-mappers)).
* **In a business rule script**: read from `input` (the keys you mapped in) and write to `output` via `output.put("keyName", value)`. See [Business rule action](../actions/business-rule-action/business-rule-action).
* **In a gateway condition**: reference the same process variables to choose a path.
* **In a user task screen**: bind UI components to process data. The value flows automatically once the variable exists in process instance data.

> [!WARNING]
>
> Placeholders in an action's JSON message, such as a Start Integration Workflow message, name process data paths from the root of the process data, with no prefix: `${customer.id}`. A `${processInstanceData.customer.id}` placeholder resolves to nothing at runtime. Subprocess Data Mappers use `${variableName}`. Always follow the syntax shown on the destination page.

***

## End-to-end example

A loan-onboarding process that uses an integration workflow to fetch a credit score, then an AI agent to extract data from an uploaded document, then a user task to confirm the final summary.

**1. User uploads document on a user task**

The file id lands on process variables, for example at `loan.documentId`.

**2. Send Message Task triggers a credit-check integration workflow**

Input mapping reads `loan.customerId`.

**3. Receive Message Task waits for the workflow**

Its data stream maps the workflow output to `creditCheck`. When the workflow completes, the response lands there in process variables.

**4. Service Task calls the document-extraction agent**

Input mapping sends `loan.documentId`. Output mapping writes the extracted fields to `loan.extracted`.

**5. Final user task displays the summary**

UI components on the screen are bound to `creditCheck` and `loan.extracted`. They render automatically because both keys now exist in process variables.

***

## Common pitfalls

> [accordion] Reading a workflow result before the Receive Message Task
>
> The workflow output only reaches process variables after the Receive Message Task unblocks. A node placed between Send and Receive will see an empty value.

> [accordion] Output key collision
>
> Two integrations whose output maps to the same key will overwrite each other. Use distinct, descriptive paths (`creditCheck`, `addressVerification`) instead of generic ones (`result`, `data`).

> [accordion] Wrong placeholder prefix
>
> `${processInstanceData.customer.id}` resolves to nothing at runtime: placeholders in an action's JSON message read process data from its root, so write `${customer.id}`. Subprocess Data Mappers use `${variableName}`. Follow the syntax shown on each node's page.

> [accordion] Expecting a synchronous result back to an external HTTP caller
>
> Starting a process via REST returns metadata (process instance UUID, state), not the process's business output. To surface results to an external app, use the SDK, a Service Task callback, or a Kafka event. See [Consuming FlowX from external apps](../../platform-deep-dive/integrations/consuming-flowx-from-external-apps).

***

## Related resources

> [card] [Data mappers](./data-mappers)
>
> Parent ↔ subprocess parameter mapping

> [card] [Start Integration Workflow](../actions/start-integration-workflow)
>
> Workflow input/output and the Receive Message Task pattern

> [card] [BPMN integration with agents](../../../ai-platform/using-agents/bpmn-integration)
>
> Calling AI agents from a process

> [card] [Business rule action](../actions/business-rule-action/business-rule-action)
>
> Inline scripts that read from `input` and write to `output`

> [card] [Send/Receive Message Task](../node/message-send-received-task-node)
>
> Node-level configuration of the wait pattern

> [card] [Consuming FlowX from external apps](../../platform-deep-dive/integrations/consuming-flowx-from-external-apps)
>
> External HTTP/SDK integration patterns


# Permission-based expressions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/permission-based-expressions

Control UI element visibility and interaction based on user roles, usernames, and process data for granular access control.

Control what users see and edit within the same process instance based on their roles, usernames, or process data. One process definition automatically adapts to different users, providing role-specific interfaces and access control.

## Overview

Permission-based expressions enable you to:

* **Customize UI per role**: Different roles see different UI elements within the same process
* **Enable read-only access**: Users view and navigate process instances without making changes
* **Support concurrent work**: Multiple users with different permissions work on the same instance
* **Adapt dynamically**: UI changes in real-time based on user permissions and process data

> [!NOTE]
>
> **Use case examples**: A loan application where applicants see only input fields, reviewers see approval buttons, and managers see all data but in read-only mode. One process definition serves all roles.

## Prerequisites

Before configuring permission-based expressions:

> [!TIP]
>
> * Process definition created with swimlanes configured
> * User roles defined in the platform
> * **Allow multiple executors** enabled at the swimlane level (in process Settings → Permissions tab)
> * Understanding of your access control requirements

## Permission capabilities

### Partial editing

Tailor UI element access for specific users, roles, or usernames within the same swimlane:

* **Role-based control**: Different roles see different UI elements
* **Username-specific access**: Individual users get customized interfaces
* **Data-driven permissions**: Process data determines what users can access

### Read-only access

Enable users to view and navigate process instances without modification:

* Users can navigate through user tasks and view data
* All input fields and buttons are non-interactive
* Hide and disable conditions continue to apply
* Navigation between tasks remains available

> [!WARNING]
>
> **Configuration required**: Enable "Allow Read-Only Process Configuration" in process General settings, then assign **View** permission to appropriate roles at the swimlane level.

### Multiple executors

Multiple users with different roles work concurrently on the same process instance within a swimlane:

* Different permission levels (Execute, Self-assign, View) assigned to different roles
* Each user sees their role-specific interface
* Changes are synchronized across all active users
* Essential for collaborative workflows with varied responsibilities

## How permissions work

Permission-based expressions combine three key elements to control UI behavior:

### 1. Swimlane role configuration

Configure base permissions at the swimlane level:

* Assign roles (Execute, Self-assign, View) to user groups
* Enable **Allow multiple executors** to activate permission-based expressions
* Set minimum access level for each role

Each permission type grants a distinct level of access within the swimlane:

| Permission | What it allows |
| - | - |
| **Execute** | Perform actions in the swimlane: submit forms, click buttons, complete tasks |
| **Self-assign** | Become the swimlane owner by acting in an unowned swimlane |
| **View** | See the process instance and navigate its tasks without making changes |

For the full swimlane permissions setup, see [Configure swimlane permissions](./process-definition#configure-swimlane-permissions).

### 2. UI element conditions

Apply conditions to individual UI components to control visibility and interaction:

**Hide condition**

* Completely removes the UI element from the interface
* Available for all component types
* Element doesn't occupy any space in the layout

**Disable condition**

* Shows the element but prevents user interaction
* Available for forms, form elements, and buttons
* Element appears grayed out or visually disabled

### 3. Condition precedence

> [!NOTE]
>
> When both hide and disable conditions exist on the same element, **disable takes precedence**. The element will be shown in a disabled state rather than hidden.

## Configuring permission-based expressions

Follow these steps to set up permission-based UI control for your process:

**1. Enable multiple executors**

Navigate to **Process Settings → Permissions** tab and enable **Allow multiple executors** for your swimlane.

![Allow Multiple Executors Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/allow_multiple_executors.png)

Enable multiple executors at the swimlane level

> [!NOTE]
>
> Configure role permissions (Execute, Self-assign, View) for each role that will access this swimlane.

**2. Open UI Designer**

Navigate to the **UI Designer** tab and select the component you want to configure with permission-based visibility or interaction controls.

**3. Access permissions configuration**

In the component properties panel, expand the **Permissions** section.

![Permission Configuration Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pemission_%20based_ui.png)

Permission configuration interface

**4. Add condition**

Click the **+** button next to your desired condition type:

* **Hide Condition**: Available for all component types
* **Disable Condition**: Available for forms, form elements, and buttons

**5. Configure condition parameters**

Define the permission logic using these parameters:

**Type**: Who the condition applies to

* **USERNAME**: Target specific usernames
* **ROLE**: Target users with specific roles

**Operator**: How to evaluate the condition

* **IN**: Condition applies when user matches the value
* **NOT\_IN**: Condition applies when user does NOT match the value

**Value Type**: Where permission data comes from

* **SWIMLANE\_OWNER**: Current swimlane owner (automatic, no value needed)
* **PROCESS\_DATA**: Reference data stored in the process instance
* **CONFIGURATION\_SWIMLANE\_ROLE**: Use roles configured at swimlane level

**Value**: The actual permission data (depends on Value Type)

* **PROCESS\_DATA**: Process data keypath (e.g., `${app.client.userList}`)
* **CONFIGURATION\_SWIMLANE\_ROLE**: Array of role names (e.g., `["ROLE_1", "ROLE_2"]`)
* **SWIMLANE\_OWNER**: Not applicable (determined automatically)

> [!TIP]
>
> Use `CONFIGURATION_SWIMLANE_ROLE` for static role-based permissions. Use `PROCESS_DATA` for dynamic, context-dependent permissions determined during process execution.

**6. Save configuration**

Click **Save** to apply your permission-based expression. Test the behavior by accessing the process with different user roles.

## Common expression patterns

Use these examples as templates for typical permission scenarios:

### Role-based access control

Hide or disable elements for specific roles configured at the swimlane level:

```javascript theme={"dark"}
{
  "type": "ROLE",
  "operator": "IN",
  "valueType": "CONFIGURATION_SWIMLANE_ROLE",
  "value": ["ROLE_MANAGER", "ROLE_SUPERVISOR"]
}
```

**Use case**: Show approval buttons only to managers and supervisors.

### Dynamic username lists

Control access based on usernames stored in process data:

```javascript theme={"dark"}
{
  "type": "USERNAME",
  "operator": "IN", 
  "valueType": "PROCESS_DATA",
  "value": ["${app.client.authorizedUsers}"]
}
```

**Use case**: Display sensitive data only to users listed in an authorized users array populated during process execution.

> [!TIP]
>
> When using `PROCESS_DATA`, ensure data is mapped to the keypath **before** users reach the user task. Arrays must contain username or role strings.

### Target a specific user

There is no value type for hardcoding a username directly in the expression. To restrict an element for one exact user, store that username in process data and reference it with `PROCESS_DATA`:

```javascript Store the username in a business rule theme={"dark"}
// Business rule before the user task
output.put("app", {"restrictedUser": "john.doe@company.com"});
```

```javascript Disable condition on the UI element theme={"dark"}
{
  "type": "USERNAME",
  "operator": "IN",
  "valueType": "PROCESS_DATA",
  "value": ["${app.restrictedUser}"]
}
```

**Use case**: Gray out an action button for one named user chosen at runtime. Switch the operator to `NOT_IN` to invert the rule — the element is disabled for everyone **except** that user.

### Swimlane owner restrictions

Limit access to the current swimlane owner only:

```javascript theme={"dark"}
{
  "type": "USERNAME",
  "operator": "IN",
  "valueType": "SWIMLANE_OWNER"
}
```

**Use case**: Allow only the task owner to edit specific fields, while other team members can view but not modify.

#### How the swimlane owner is determined

The platform assigns swimlane ownership automatically as the process runs:

* **Process start**: the user who starts the process instance becomes the owner of every swimlane their roles give them access to.
* **First action in a swimlane**: if a swimlane has no owner yet, the first user who executes an action in it becomes its owner. This requires the **Self-assign** permission on that swimlane.
* **No automatic transfer**: ownership stays with that user. With **Allow multiple executors** enabled, other permitted users can act in the swimlane without taking over ownership. When it is turned off, only the current owner can execute actions in the swimlane.
* **Reassignment**: assigning or unassigning the task from Task Manager updates the swimlane owner. Unassigning also removes the inherited owner from active subprocesses.

### Exclusion patterns

Hide elements from specific users or roles using `NOT_IN`:

```javascript theme={"dark"}
{
  "type": "ROLE",
  "operator": "NOT_IN",
  "valueType": "CONFIGURATION_SWIMLANE_ROLE",
  "value": ["ROLE_EXTERNAL_USER", "ROLE_VIEWER"]
}
```

**Use case**: Hide internal notes or administrative actions from external users and read-only viewers.

## Advanced: Cross-swimlane references

### Limitation

`SWIMLANE_OWNER` references only the owner of the **current swimlane**. You cannot directly reference owners from other swimlanes in the same process.

### Workaround: Store owners in process data

To reference users from other swimlanes, explicitly store their information in process data during swimlane transitions:

```javascript Store swimlane owners during process execution theme={"dark"}
// Map during swimlane transitions or process start
{
  "swimlaneOwners": {
    "frontOffice": "john.doe@company.com",
    "backOffice": "jane.smith@company.com", 
    "supervisor": "manager@company.com"
  }
}
```

```javascript Reference stored swimlane owner theme={"dark"}
// Use in permission expression on any swimlane
{
  "type": "USERNAME",
  "operator": "IN",
  "valueType": "PROCESS_DATA", 
  "value": ["${app.swimlaneOwners.frontOffice}"]
}
```

> [!WARNING]
>
> Cross-swimlane owner references require explicit data mapping. Design your process to capture user information during swimlane transitions or use business rules to populate owner data.

**Implementation approach**:

1. Add a Business Rule node at the start of each swimlane
2. Capture the current user's username
3. Store it in your process data structure (e.g., `swimlaneOwners.{swimlaneName}`)
4. Reference this stored data in permission expressions on other swimlanes

## Best practices

Follow these guidelines for effective permission-based expressions:

> [!TIP]
>
> **Design principles**:
>
> * **Start simple**: Begin with role-based permissions before adding complex data-driven logic
> * **Test thoroughly**: Validate permission behavior with all user roles before deployment
> * **Document your logic**: Add comments in your process explaining complex permission patterns
> * **Minimize conditions**: Too many conditions can make UI behavior unpredictable and hard to maintain
> * **Use consistent naming**: Follow a standard naming convention for roles and process data keys
> * **Plan for edge cases**: Consider what happens when process data is missing or null
> * **Performance consideration**: Complex permission expressions on many components can impact rendering performance

> [!WARNING]
>
> **Common pitfalls to avoid**:
>
> * Don't create circular dependencies between hide and disable conditions
> * Don't forget to test with users who have no assigned roles
> * Don't rely on process data that might not be populated yet
> * Don't use permission expressions as a substitute for proper swimlane role configuration

## Related resources

> [card] [Access roles configuration](/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes)
>
> Set up user roles and permissions at the platform level

> [card] [Swimlanes](/5.9/docs/platform-deep-dive/user-roles-management/swimlanes)
>
> Learn about swimlane configuration and role assignment

> [card] [UI Designer](/5.9/docs/building-blocks/ui-designer/ui-designer)
>
> Design user interfaces with permission-aware components

> [card] [Process definition](./process-definition)
>
> Complete guide to process definition configuration


# Process Designer
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/process

The Process Designer workspace is tailored for creating and editing business processes, featuring a menu with all the essential elements needed to design a process.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_dsgnr.png)

The Process Designer provides a visual, BPMN 2.0-compliant environment where you can create, edit, and manage business process workflows. Whether you're building simple linear flows or complex branching processes with multiple decision points, the designer gives you the tools to model your business logic effectively.

> [!TIP]
>
> **Build one:** [Build your first process](/5.9/docs/getting-started/building-your-first-proc) walks through a credit card application with a form, a business rule, a gateway, and a confirmation screen.

## Process Designer interface

When you open a process definition, you'll see the following essential elements:

> [accordion] 1. Process definition name
>
> The name of your process definition appears at the top, providing a clear identifier for the workflow. Click on the name to access process-level settings including permissions, expiry time, platform configuration, and task management options.

> [accordion] 2. Process Nodes
>
> The left panel contains the node palette with all available BPMN elements you can drag and drop onto the canvas. Nodes are organized by category: events, tasks, gateways, and subprocesses.
>
> > [!TIP]
> >
> > Hover over any node in the palette to see a tooltip with its name and primary use case.

> [accordion] 3. Navigation Areas
>
> The Navigation section allows you to configure how users navigate through your process on web and mobile platforms. You can create steppers, modals, and other navigation structures that organize user tasks.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/nav_areas.png)
>
> > [card] [Navigation Areas](./navigation-areas)

> [accordion] 4. Autosave
>
> Changes to your process are automatically saved as you work, eliminating the need to manually save. The autosave indicator shows when your last change was saved, ensuring your work is never lost.
>
> > [!NOTE]
> >
> > Autosave works on draft versions. To make changes permanent and available to other environments, you need to commit your project version.

> [accordion] 5. Canvas
>
> The main canvas area is where you design your process flow by adding nodes, connecting them with sequences, and organizing them into swimlanes. The canvas supports zoom, pan, and offers visual feedback for validation warnings.

> [accordion] 6. Warnings
>
> The warning indicator displays misconfigurations that could prevent your process from executing correctly. Warnings are platform-specific and help ensure your navigation structure and UI configuration align with your selected platforms (Web, Mobile, or Omnichannel).
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wrn.png)
>
> > [!WARNING]
> >
> > Address all warnings before publishing your process to production to avoid runtime errors.

> [accordion] 7. Node details
>
> When you select a node, the right panel displays its configuration options. Here you can set node properties, add actions, configure UI elements for user tasks, and define business rules.

We have designed FlowX.AI components to closely resemble their BPMN counterparts for ease of use.

> [card] [BPMN nodes](../node/node)
>
> Comprehensive guide to all available node types

> [card] [BPMN 101](https://academy.flowx.ai/explore/bpmn-101)
>
> Learn BPMN fundamentals through FlowX Academy

## Working with the canvas

The Process Designer canvas provides several features to help you efficiently create and manage process flows:

### Canvas navigation

* **Zoom**: Use the mouse wheel or zoom controls to zoom in and out of your process
* **Pan**: Click and drag on empty canvas space to move around large processes

### Adding and connecting nodes

**1. Add a node**

Drag a node from the left palette onto the canvas, or click a node type to add it to the center of your current view.

**2. Connect nodes**

Click on a node to select it, then click the arrow icon that appears. Click on the target node to create a sequence flow connection.

> [!TIP]
>
> You can also create connections by dragging from the arrow icon on the source node to the target node.

**3. Configure the node**

Select the node and use the right panel to configure its properties, actions, and behavior.

#### Faster ways to build

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The palette-and-arrow steps above still work. Alongside them, the canvas offers quicker ways to do the same things:

| Instead of | You can |
| - | - |
| Dragging from the palette | Open the **New Node** panel and place a node from there |
| Aiming at a node's arrow icon | Drop a connection anywhere on the target node |
| Lining a connection up by hand | Drag a node near another to connect the two |
| Living with the default routing | Drag a sequence flow's control points to reshape it |
| Resizing a swimlane from one edge | Resize it from any of its four edges |

The process-instance viewer uses this same canvas, so a running instance looks and behaves like the diagram you designed.

> [!NOTE]
>
> The canvas is deliberately unchanged to look at. Existing diagrams, saved layouts and screenshots all still hold.

***

### Organizing your process

**Swimlanes**: Organize nodes by roles or departments using swimlanes. This helps visualize which parts of the process are handled by which teams and enables role-based access control.

**Layout best practices**:

* Arrange your process flow from left to right for better readability
* Use vertical spacing to separate parallel branches
* Group related nodes close together
* Keep crossing sequence flows to a minimum
* Use subprocesses to encapsulate complex logic

> [card] [Swimlanes](./process-definition#organize-processes-with-swimlanes)

## Validating your process

Before publishing a process, ensure it meets all requirements:

### Validation rules

The Process Designer automatically validates your process and displays warnings for:

* **Missing required nodes**: Processes must have at least one START and one END node
* **Disconnected nodes**: All nodes must be reachable through sequence flows
* **Missing configurations**: User tasks without assigned navigation areas or UI elements
* **Platform mismatches**: UI configurations that don't align with selected platforms (Web/Mobile/Omnichannel)
* **Permission issues**: Swimlanes without proper role assignments
* **Invalid expressions**: Business rules or conditions with syntax errors

> [!NOTE]
>
> Click on any warning to navigate directly to the problematic node or configuration.

### Testing your process

Before deploying to production:

1. **Start a test instance**: Use the test function to start a process instance in your development environment
2. **Monitor execution**: Watch how tokens move through your process and verify all paths work correctly
3. **Check data flow**: Ensure data is properly captured and passed between nodes
4. **Test all branches**: Verify that gateways route correctly based on different conditions
5. **Validate integrations**: Confirm external system connections work as expected

> [card] [Starting a process](../../flowx-designer/managing-a-project-flow/starting-a-process)

### Common validation errors

> [accordion] Process definition not found
>
> **Cause**: The process hasn't been set as published or doesn't exist in the target environment.
>
> **Solution**: Ensure your process is part of a committed project version and deployed to the environment.

> [accordion] Start node not properly configured
>
> **Cause**: Missing or misconfigured START node.
>
> **Solution**: Add a START node and ensure it has proper permissions configured if multiple start nodes exist.

> [accordion] Multiple start nodes without conditions
>
> **Cause**: Multiple START nodes defined without start conditions to differentiate them.
>
> **Solution**: Add start conditions to each START node or remove extra START nodes.

> [accordion] User task not assigned to navigation area
>
> **Cause**: A user task node hasn't been assigned to any navigation area.
>
> **Solution**: Open the Navigation view and assign the user task to an appropriate navigation area.

## Collaboration and versioning

### Working with multiple users

Multiple team members can work on processes simultaneously:

* **Concurrent editing**: Multiple users can view and edit processes within the same draft version
* **Real-time updates**: Changes made by other users appear automatically when you refresh
* **Conflict prevention**: The system prevents conflicting changes through optimistic locking
* **Change tracking**: The audit log records who made what changes and when

> [!WARNING]
>
> When working with multiple users on the same process, communicate about major structural changes to avoid conflicts.

### Version management

Processes are versioned as part of projects:

* **Draft versions**: Work-in-progress changes that can be edited
* **Committed versions**: Finalized snapshots that are immutable
* **Version comparison**: Compare different versions to see what changed
* **Audit trail**: Track all changes with timestamps and user information

> [card] [Versioning](../../projects/managing-applications/versioning)
>
> Learn about project versioning

> [card] [Audit log](./process-definition#audit-log)
>
> View change history

## Best practices

> [!TIP]
>
> **Follow these guidelines for maintainable, performant processes**:
>
> **Design principles**:
>
> * Start simple with START and END nodes, then add complexity incrementally
> * Use clear, descriptive names for nodes and actions that explain their purpose
> * Document complex business logic in node descriptions
> * Create subprocesses for reusable logic or to simplify complex flows
> * Limit process complexity - if a process has more than 20-30 nodes, consider breaking it into subprocesses
>
> **Performance optimization**:
>
> * Minimize the number of nodes in frequently executed paths
> * Use parallel gateways judiciously - each branch creates additional tokens
> * Avoid deeply nested subprocesses when possible
> * Consider using timer events instead of polling for external events
>
> **Naming conventions**:
>
> * Use a consistent format like `[Department]_[Function]_[Action]` for process names
> * Name nodes to describe what they do, not what they are (e.g., "Validate Customer Data" instead of "Task Node 1")
> * Use uppercase for process-level constants and lowercase with underscores for data keys
>
> **Testing strategy**:
>
> * Test all decision branches with different input data
> * Verify error handling paths work correctly
> * Test with realistic data volumes for collection iterations
> * Validate all integration points before deployment

## Troubleshooting

> [accordion] Process won't save
>
> **Symptoms**: Changes aren't being saved or the autosave indicator shows an error.
>
> **Solutions**:
>
> * Check your network connection
> * Verify you have edit permissions for the project
> * Ensure the project is in draft status (committed versions can't be edited)
> * Try refreshing the page and re-applying your changes
> * Check if another user has locked the resource

> [accordion] Nodes can't be connected
>
> **Symptoms**: Unable to create sequence flows between nodes.
>
> **Solutions**:
>
> * Verify you're connecting compatible node types (e.g., END nodes can't have outgoing sequences)
> * Check if a sequence already exists between the nodes
> * Ensure nodes are in the same process (not trying to connect across subprocess boundaries)
> * Try zooming in - connection points might be difficult to target at small zoom levels

> [accordion] Process instances fail to start
>
> **Symptoms**: Runtime errors when trying to start process instances.
>
> **Solutions**:
>
> * Review and resolve all validation warnings
>
> * Verify the process is published and included in an active build
>
> * Check that users have appropriate permissions (execute role)
>
> * Ensure all required integrations are configured and accessible
>
> * Review the exceptions log for detailed error messages
>
> > [card] [Failed process start](../../projects/runtime/active-process/failed-process-start)

> [accordion] UI elements not displaying
>
> **Symptoms**: Configured UI components don't appear when running the process.
>
> **Solutions**:
>
> * Verify user tasks are assigned to navigation areas
> * Check that UI elements are configured for the correct platform (Web/Mobile)
> * Ensure actions are set to "Manual" if they should be triggered by user interaction
> * Validate that the process platform setting matches your deployment (Web Only, Mobile Only, or Omnichannel)
> * Check hide/disable expressions aren't preventing element display

> [card] [Process Instance Monitoring](../../projects/runtime/active-process/process-instance)
>
> Learn how to monitor and debug running process instances

In the following sections, we will provide more details on how to use the Process Designer and its components.

## Process definition

The process is the core building block of the platform. Think of it as a representation of your business use case, for example making a request for a new credit card, placing an online food order, registering your new car or creating an online fundraiser supporting your cause.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_designer.png)

A process is a series of steps that need to be followed to get to the desired outcome: getting a new credit card, gathering online donations from friends or having your lunch brought to you. These steps involve a series of actions, whether automated or handled by a human, that allows you to complete your chosen business objective.

> [card] [Process definition](./process-definition)

## Process instance

Once the desired processes are defined in the platform, they are ready to be used. Each time a process needs to be used, for example, each time a customer wants to request a new credit card, a new instance of the specified process definition is started in the platform. Think of the process definition as a blueprint for a house, and of the process instance as each house of that type that is being built.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/view_instance.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_instance.png)

From this point on, the platform takes care of following the process flow, handling the necessary actions, storing and interpreting the resulting data.

> [card] [Process Instance](../../projects/runtime/active-process/process-instance)

> [card] [Exceptions](../../projects/runtime/active-process/failed-process-start)

> [card] [Debug 101 course](https://academy.flowx.ai/explore/debug-your-process-0)
>
> Learn debugging patterns, process/token status, error types, and exception handling

> [card] [From Zero to Build course](https://academy.flowx.ai/explore/5from-zero-build-onboarding-project)
>
> End-to-end project build course covering all major platform features


# Process definition
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/process-definition

The core of the platform is the process definition, which is the blueprint of the business process made up of nodes that are linked by sequences.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_definitions.png)

## What is a process definition?

A process definition is the blueprint for your business processes. It defines the complete workflow logic—including nodes, sequences, decision points, user interactions, and integrations—that makes up your business process.

> [!NOTE]
>
> A process definition is like an architectural blueprint. The definition specifies how to build the structure, while process instances are the actual buildings constructed from that blueprint.

### Key characteristics of process definitions

> [card] Executable Blueprint
>
> Once defined and published, process definitions can be instantiated, executed, and monitored in real-time

> [card] Version Controlled
>
> Processes are versioned as part of projects, enabling safe evolution and rollback capabilities

> [card] Multi-Platform Support
>
> Configure processes for Web Only, Mobile Only, or Omnichannel deployment

> [card] Role-Based Access
>
> Control who can view, execute, and modify processes using swimlanes and permissions

### Understand definitions and instances

Process definitions and process instances serve different purposes:

| Aspect | Process Definition | Process Instance |
| - | - | - |
| **Nature** | Blueprint/template | Actual execution |
| **When created** | Design time | Runtime |
| **Quantity** | One per process type | Many per definition |
| **Changeability** | Can be versioned and updated | Immutable once started |
| **Contains** | Node configurations, rules, UI | Current state, runtime data, token position |

> [card] [Process instance](../../projects/runtime/active-process/process-instance)
>
> Learn about running process instances

> [card] [Failed process start](../../projects/runtime/active-process/failed-process-start)
>
> Troubleshoot process execution errors

## Manage the process lifecycle

The process lifecycle consists of seven stages, from initial design through deployment and optimization:

**1. Design**

Create your process definition using the Process Designer, adding nodes, configuring actions, and building the UI.

**2. Configure**

Set process-level settings including permissions, platforms, expiry time, and integrations with Task Manager or reporting.

**3. Validate**

Address any configuration warnings and test the process with sample data to ensure it works as expected.

**4. Commit**

Save your changes as part of a committed project version, making them available for deployment.

> [!NOTE]
>
> Committed versions are immutable. To make further changes, create a new draft version.

**5. Build and Deploy**

Include the process in a project build and deploy it to your target environments (development, staging, production).

**6. Execute**

Process instances are created from the definition when users or systems trigger the process.

**7. Monitor and Optimize**

Track process performance, identify bottlenecks, and iterate with new versions to improve efficiency.

> [card] [Creating a process definition](../../flowx-designer/managing-a-project-flow/creating-a-new-process-definition)
>
> Step-by-step guide to creating your first process

## Work with core components

Process definitions consist of six integrated workspaces and tools that work together to create business applications:

![Process definition menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_def_opts.png)

Process definition navigation menu

### 1. Process Designer

The visual BPMN 2.0 workspace where you create and edit process logic using a drag-and-drop interface.

![Process Designer Canvas](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_dsgn.png)

Process Designer canvas showing swimlanes, nodes, and process flow

**Key features**:

* **Node palette**: Access all BPMN node types (User Tasks, Service Tasks, Gateways, Events, etc.)
* **Swimlanes**: Organize process steps by role or department for access control
* **Canvas controls**: Zoom, pan, and navigate large process diagrams
* **Sequence flows**: Connect nodes to define the execution path
* **Visual feedback**: Real-time validation warnings and configuration status

> [card] [Process Designer](./process)
>
> Complete guide to the Process Designer workspace

### 2. UI Designer

The visual workspace where you design user interfaces for process interactions without code.

![UI Designer Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_designer_proc_def.png)

UI Designer showing component library and interface preview

**Key features**:

* **Component library**: Pre-built UI components (Forms, Inputs, Buttons, Tables, Cards, etc.)
* **Drag-and-drop design**: Build interfaces by dragging components onto the canvas
* **Live preview**: See how your UI will appear to users in real-time
* **Platform-specific design**: Configure separate UIs for Web, iOS, and Android
* **Data binding**: Connect UI elements directly to process data
* **Theme support**: Apply consistent styling across your application

> [card] [UI Designer](../ui-designer/ui-designer)
>
> Learn about UI component configuration

### 3. Data Model

Define the structure and schema for all data that flows through your process.

![Data Model Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prc_dm.png)

Data Model showing types, structures, and relationships

**Key features**:

* **Type definitions**: Create reusable data structures with typed fields
* **Visual relationships**: See how data objects connect and reference each other
* **Input parameters**: Define what data the process expects to receive
* **Output parameters**: Specify what data the process returns
* **Example values**: Include sample data for testing and development
* **Validation rules**: Ensure data integrity with type checking

> [card] [Data Model](./data-model)
>
> Comprehensive data modeling guide

### 4. Settings

Configure process-level settings including naming, permissions, integrations, and platform options.

![Settings Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/settings_interface.png)

Settings interface showing process configuration tabs

**Configuration tabs**:

* **Process Name**: Set the unique identifier with naming constraints. On SaaS (5.13), this tab is removed; see [Set your process name](#set-your-process-name)
* **General**: Platform selection, reporting, expiry time
* **Permissions**: Configure swimlane roles and access control
* **Task management**: Integration with Task Manager plugin
* **Data Search**: Define searchable and filterable process data keys

**Access settings**: Click the settings icon in the left sidebar or use the top navigation menu.

### 5. Start a process for testing

Click the **Start Process** button in the top-right corner to test your process directly from the designer.

**Capabilities**:

* Automatically generates input forms based on your defined input parameters
* Validates required data before the process starts
* Creates a test process instance in your current environment
* Helps you test and debug during development

> [!TIP]
>
> When you have input parameters defined, the Start Process function will automatically generate input fields for required data, making it easy to test your process with sample values.

> [card] [Starting a process](../../flowx-designer/managing-a-project-flow/starting-a-process)
>
> Learn more about starting and testing processes

### 6. Access additional operations

Click the contextual menu (three-dot icon ⋮ in the top-right corner) to access essential process operations:

![Contextual menu options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/proc_contextual.png)

Process definition contextual menu

> [!NOTE]
>
> **Two contextual menus for process management:**
>
> This menu is available when you're **inside** a process definition, actively editing it. There's also a separate contextual menu available from the **Processes list view** (before opening a process) that provides operations like Export, Duplicate, Copy to another project, and See used resources.

> [card] [Managing processes from the list view](../../flowx-designer/managing-a-project-flow/creating-a-new-process-definition#managing-process-definitions)
>
> Learn about the Processes list contextual menu for export, duplicate, and copy operations

> [accordion] Clear Cache
>
> Clear cached process definition data to force a refresh from the database.
>
> **When to use**:
>
> * After making significant changes that aren't reflecting in the UI
>
> * When experiencing unexpected behavior or outdated data display
>
> * To troubleshoot synchronization issues
>
> > [!NOTE]
> >
> > This only clears the cache for the current process definition in your browser session.

> [accordion] Audit Log
>
> View comprehensive change history for the process definition.
>
> **Information tracked**:
>
> * Timestamp of each change
> * User who made the change
> * Application version
> * Subject and event type
> * Subject identifier
> * Status of the change
>
> **Features**:
>
> * Filterable entries for easy tracking
>
> * Complete audit trail for compliance
>
> * Version comparison capabilities
>
> > [card] [Audit documentation](../../platform-deep-dive/core-extensions/audit)

> [accordion] View History
>
> Access the version history of the process definition to see all changes over time.
>
> ![View History](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/history2.png)
>
> Select a version
>
> ![View History](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/history1.png)
>
> View changes
>
> **Capabilities**:
>
> * Compare different versions side-by-side
>
> * See what changed between versions
>
> * Track evolution of the process definition
>
> * Identify when specific changes were introduced
>
> > [!NOTE]
> >
> > This shows the version history within the project versioning system, allowing you to see how the process evolved across committed versions.

> [accordion] Delete
>
> Remove the process definition from the project.
>
> ![Delete process definition](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/delete_process.png)
>
> Delete process definition
>
> > [!WARNING]
> >
> > **Use with caution**: Deleting a process definition is a significant action that should only be performed when:
> >
> > * The process is no longer needed
> > * You've verified that no other processes reference this one as a subprocess
> > * You have appropriate backup or version control
>
> **Impact**:
>
> * The process definition is removed from the current wip version (you cannot delete a process definition that is part of a committed version)
> * References from other processes may break
> * Historical data of process instances is not affected
> * Can be recovered from previous committed versions if needed

## Define your data model

The data model defines the structure of all data in your process. It acts as the schema for process variables, letting you organize and manage data throughout the process lifecycle.

> [!NOTE]
>
> Access the data model directly from the process definition interface to add new key-value pairs without switching menus.

### Why define a data model?

Defining your data model provides several benefits:

* **Type safety**: Prevent errors during process execution by defining data types
* **Auto-completion**: Get intelligent suggestions in UI Designer based on defined keys
* **Validation**: Ensure data consistency across nodes and actions
* **Documentation**: Use the data model as living documentation of your process data structure
* **Reusability**: Reference data structures across multiple nodes and actions
* **Testing**: Include example values to test without creating mock data

> [!TIP]
>
> **Best practice**: Define your data model structure at the project level before building processes. This enables reusability across processes and improves consistency.

For comprehensive information on working with the Data Model, including advanced features like input/output parameters and data mappers:

> [card] [Data model](./data-model)

### Configure input and output parameters

Define the data contract for your process by specifying what data it receives (inputs) and what data it returns (outputs). These parameters are essential for subprocesses, workflows, and process testing.

#### Access parameter configuration

To configure parameters, navigate to the **Data Model** tab.

**Input parameters**

Input parameters define the data structure your process expects when it starts or when called as a subprocess:

* Enable process start validation
* Generate automatic input prompts for testing
* Support Call Activity nodes and subprocess integration

**Output parameters**

Output parameters define the data structure your process returns after execution:

* Return data to parent processes
* Enable synchronous subprocess communication
* Replace manual "Append Data to Parent Process" actions

![Input parameters configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dmp5.png)

Configuring input parameters

#### How to configure parameters

To configure input or output parameters:

1. Navigate to **Data Model** → **Input/Output Parameters**.
2. Click **Define parameters**.
3. Configure the schema:
   * Add the parameter name and data type.
   * Mark parameters as required or optional.
   * Add descriptions and example values.
4. If you have multiple start or end nodes, select the specific node from the dropdown.

> [!WARNING]
>
> **Required parameters**: Missing required parameters will cause process start failures. Only mark parameters as optional if your process can truly function without them.

> [!TIP]
>
> **Best practice**: Define parameter schemas based on your project-level data model for consistency and reusability.

#### Key features

* **Automatic validation** of required parameters
* **Type checking** ensures data integrity
* **Change propagation**: Deleted/renamed attributes automatically update in mappings
* **Multiple nodes support**: Different parameters for different start/end points

> [card] [Data mappers](./data-mappers)
>
> Complete guide to mapping data between components

> [card] [Call Activity node](../node/call-subprocess-tasks/call-activity-node)
>
> Using parameters with subprocess calls

## Organize processes with swimlanes

Swimlanes provide a visual and functional way to organize process nodes by participants or roles. You can structure your process by dividing it into horizontal lanes, with each lane representing different actors, departments, or responsibility areas.

> [!NOTE]
>
> Swimlanes serve two purposes: they provide visual organization in the process designer and enforce role-based access control at runtime.

### Benefits of using swimlanes

Use swimlanes to:

* **Improve visual clarity**: Show which team or role is responsible for each process step
* **Control access**: Restrict who can execute, view, or self-assign tasks in each lane
* **Ensure compliance**: Enforce separation of duties by distributing tasks across different roles
* **Optimize processes**: Identify bottlenecks by seeing which roles handle the most tasks

### Add swimlanes

To add swimlanes to your process definition:

**1. Open the process**

1. Access the **FlowX.AI Designer**
2. Open an existing process definition or create a new one

**2. Access swimlane menu**

Identify the default swimlane and select it to display the contextual menu.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/add_swimlane.png)

> [!TIP]
>
> With the contextual menu, you can easily perform various actions: add or remove swimlanes, reorder them, or configure their settings.

**3. Add swimlane**

1. Choose the desired location for the new swimlane (above or below existing lanes)
2. Click the **add swimlane icon** to create the new swimlane
3. Give the swimlane a descriptive name (e.g., "Front Office", "Approver", "Back Office")

**4. Configure permissions**

After creating a swimlane, configure which roles can access it in the **Permissions** section of process settings.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/swimlane_permissions.png)

For more details about access management, check the following sections:

> [card] [User roles management - Swimlanes](../../platform-deep-dive/user-roles-management/swimlanes)

> [card] [Configuring access roles for processes](../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes)

## Configure process settings

The Settings panel provides configuration options organized across five tabs. To access settings, click the settings icon in the left sidebar.

### Set your process name

Configure the unique identifier for your process definition in the **Process Name** tab.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, the **Process Name** tab is removed from Settings, which now opens on **General**. To rename a process, open the process three-dot menu (⋮) and select **Details**.&#x20;

* **Process definition name**: The unique name for your process

> [!NOTE]
>
> Name can only contain letters, numbers and the following special characters: `[ ] ( ) . _ -`

**Best practices for naming**:

* Use descriptive names that clearly identify the process purpose.
* Follow a consistent naming convention across your organization.
* Use underscores or hyphens instead of spaces.
* Keep names concise but meaningful (for example, `Customer_Onboarding` or `Loan_Application`).

### Configure general settings

Use the **General** tab to configure platform settings, reporting options, process data, and expiry time.

![General settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/general_settings.png)

General settings tab

#### Select your deployment platform

Choose the deployment target for your process. This setting affects configuration options in Navigation Areas, UI Designer, and Misconfigurations.

**Available platforms**:

* **Web Only**: Use this option when your navigation areas are defined exclusively for web. The process is optimized for web usage and doesn't provide the same functionality on mobile devices.
* **Mobile Only**: Use this option when your navigation areas are defined only for mobile. The process uses mobile-specific features and provides an optimal mobile experience.
* **Omnichannel**: Use this option when your process has navigation areas defined for both web and mobile platforms. This ensures users have a consistent experience regardless of their platform.

> [!NOTE]
>
> Navigation Areas, UI Designer and misconfigurations will be affected by this setting.

> [!NOTE]
>
> By default, new processes are set to **Web Only**. This ensures that they are initially optimized for web-based usage, providing a starting point for most users and scenarios.

#### Enable read-only access

Allow users to view and navigate through your process definition without modifying data or triggering actions.

![Read-only configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/read_nonly_enable.png)

Read-only process configuration toggle

When you enable this setting, you unlock additional customization capabilities in Process Designer and UI Designer, letting you configure read-only access at the process level.

**When to use read-only access**:

* **Supervision and oversight**: Let supervisors review process instances without making changes.
* **Audit and compliance**: Let auditors view process data and history without risk of modification.
* **Information sharing**: Let stakeholders view process status without granting edit permissions.
* **Training and demo**: Show process flows and data to trainees without allowing changes.

**How to configure read-only access**:

1. Enable "Allow Read-Only Process Configuration" in the General settings tab.
2. Configure read-only permissions at the swimlane level in the Permissions tab.
3. Use permission-based expressions in UI Designer to control element visibility and interaction.
4. Enable or disable the toggle at the node level to configure read-only access for specific nodes.

> [!NOTE]
>
> Read-only access allows users to navigate through process screens and see the full context without the ability to modify data or execute actions. This is useful for oversight, auditing, and information sharing scenarios.

> [!WARNING]
>
> **Important**: Read-only configuration must be set at the process level first, then configured per swimlane in the Permissions tab. Hide and disable conditions configured in UI Designer still apply to read-only users.

> [card] [Permission-based expressions](./permission-based-expressions)
>
> Learn how to configure granular read-only access control

#### Enable reporting

Toggle **Use process in reporting** to include the process in reporting via the Reporting plugin.

#### Configure general data

Use general data to display notifications, warnings, or informational content immediately when a process starts.

**When to use general data**

General data is useful for:

* **Supervision messages**: Display important notices about account supervision or approval requirements.
* **Document generation status**: Show immediate feedback about document processing.
* **Process-level notifications**: Present critical information that needs to be visible from the start.
* **Banner messages**: Display persistent notifications at the top of the process interface.

> [!WARNING]
>
> General data is not intended for Server-Sent Events (SSE) updates. It provides data immediately available in the process start response, ensuring notifications appear before any real-time updates occur.

**Example configuration**

```json theme={"dark"}
{
  "notifications": [
    {
      "identifier": "Supervision",
      "show": "true", 
      "componentIdentifier": "MESSAGE",
      "displayOptions": {
        "flowxProps": {
          "text": "Account opening requires supervision. The client's account and products will be active after receiving necessary approvals.",
          "messageType": "warning"
        }
      }
    }
  ]
}
```

> [!TIP]
>
> When you configure general data notifications, ensure the message field contains the actual text to display. Set the `messageType` property to `success`, `warning`, `error`, or `info` to apply the correct styling.

#### Set expiry time

You can configure an expiry time expression on a process definition to specify when the process expires.

| **Example** | **Expression** | **Explanation** |
| - | - | - |
| Daily Expiry at Midnight | `0 0 0 * * ?` | Sets the process to expire at 00:00 (midnight) every day. The `?` is used in the day-of-week field to ignore its value. |
| Hourly Expiry on Weekdays | `0 0 9-17 * * MON-FRI` | Sets the process to expire at the start of each hour between 9 AM and 5 PM on weekdays (Monday to Friday). |
| Expiry After a Duration | `PT3M22S` | Sets the process to expire after a duration of 3 minutes and 22 seconds from the start, using **ISO 8601 format**. |

> [!TIP]
>
> FlowX.AI supports Spring cron expressions. They  **must always include six fields**: `seconds`, `minutes`, `hours`, `day of month`, `month`, and `day of week`.\
> This differs from traditional UNIX cron, which uses only five fields. Be sure to include the `seconds` field in Spring cron expressions to avoid errors.

> [!NOTE]
>
> The cron expression format should include seconds (0), minutes (0), hours (0), and then wildcards for the day, month, and day of the week fields. The `?` sign in the day-of-week field is used when the day-of-month field is already specified (or ignored in this case).

> [!NOTE]
>
> You can use both ISO 8601 duration format (`PT3M22S`) and cron expressions (`0 0 0 * * ?`, `0 0 9-17 * * MON-FRI`) to define `expiryTime` expressions for process definitions.

For more information about **Cron Expressions** and **ISO 8601** formatting, check the following section:

[Timer Expressions](../node/timer-events/timer-expressions)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/proc_general_settings.png)

#### What happens when a process expires

The expiry expression is evaluated once, when a process instance starts:

* An **ISO 8601 duration** (`PT3M22S`) is measured from the moment the instance starts.
* A **cron expression** (`0 0 0 * * ?`) resolves to the next matching time after the instance starts.

Changing the expiry expression on a process definition affects only instances started after the change.

When the expiry moment arrives and the instance is still active:

* The process instance status changes to **EXPIRED**, a final state recorded with a finish date.
* All ACTIVE tokens change to the **EXPIRED** token status, which is terminal: the process can't advance any further, and the Retry action is no longer available (it applies only to ACTIVE tokens).
* Active subprocesses started by the instance expire together with the parent by default. This cascade is configurable — see [Managing subprocesses expiration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#managing-subprocesses-expiration).
* Scheduled timer events for the instance are cancelled and its event listeners are removed.
* Connected screens receive the state change, and Task Manager is notified of the new process and token states.

> [!NOTE]
>
> **If the process finishes before the expiry time, nothing happens at the expiry moment.** The scheduled expiry is cancelled when the instance reaches a final state, and an instance that already ended is never moved to EXPIRED. Expiry only affects instances that are still active when the moment arrives.

> [!NOTE]
>
> There is no action to expire an instance on demand: expiry fires only at the scheduled time. To end an active instance earlier, use a termination [process operation via Kafka](../../platform-deep-dive/core-extensions/task-management/task-management-overview#available-operation-types) — the instance ends with the TERMINATED status, not EXPIRED.

> [!TIP]
>
> The **Expiry time** field on a **UI Flow** is a separate mechanism: it expires the UI Flow session, not a process instance. See [Session expiry](../ui-flows#session-expiry).

### Set permissions

Use the **Permissions** tab to configure role-based access control for each swimlane in your process.

![Permissions settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/swm_prmsn.png)

Permissions settings tab

After you define roles in your identity provider solution (for example, Keycloak), they become available for configuring swimlane access in the process definition settings.

#### Configure swimlane permissions

**1. Select swimlane**

Choose the swimlane you want to configure from the dropdown menu.

**2. Add roles**

1. Click **Add Role** to assign permissions
2. Select the role from the dropdown
3. Choose permission types: **Execute**, **Self Assign**, **View**

**3. Configure multiple executors**

Toggle **Allow Multiple Swimlane-Executors** to enable multiple users with different roles to work concurrently on the same process instance within the same swimlane.

> [!NOTE]
>
> When enabled, permissions can be configured at UI Element level in User Tasks from the selected swimlane, allowing granular control over who can see and interact with specific UI components.

#### Default permissions

When you create a new swimlane, it comes with two default permissions:

* **Execute**: Allows users to perform actions in the swimlane
* **Self-assign**: Enables users to assign tasks to themselves

Additional permissions can be added manually based on your requirements.

> [card] [Configuring access rights for processes](../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes)

> [card] [Permission-based expressions](./permission-based-expressions)

### Integrate with Task Manager

Use the **Task Management** tab to configure integration with the Task Manager plugin for task tracking and management.

![Task management settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/tsk_mngmnt_settings.png)

Task management settings tab

#### Available configuration options

**Use process in task management**

Toggle this option to enable integration with the Task Manager system.

When you enable this option, the process becomes available for managing tasks within Task Management. This allows data, tasks, and status updates to flow between the process and Task Manager.

**Container App URL**

The Container App URL is the endpoint that directs users to the specific application instance where your process runs.

The URL serves as a reference point for accessing and managing tasks directly from Task Manager. Set it to the route of your container app that renders a process, for example:

```
{container app url}/process
```

When a user opens a task, Task Manager appends the process details as query parameters (`?appId=…&processUuid=…&themeId=…`), so the route must load the process from these parameters.

You can:

* Define the URL dynamically using configuration parameters (for example, `${genericParameter}`).
* Set the URL at the process data level using business rules.

**Example URL**:

```
https://demo-angular.devmain.flowxai.dev/
```

**Keys to send to Task Manager**

Specify the data fields (keys) from your process that are sent to Task Manager for indexing and display. Configure these keys on a separate interface.

> [!TIP]
>
> **Important considerations**:
>
> * Keys must exist in the process data model
> * Keys need re-indexing if their type or structure is updated
> * Only enable Task Manager integration if you need task-level tracking
> * This adds overhead, so use selectively for business-critical processes

> [card] [Task Management](../../platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> Learn more about Task Manager configuration

> [card] [Task Management Localization](../../platform-deep-dive/core-extensions/task-management/task-management-localization)
>
> Localize Task Management in 34+ languages

### Configure data search

Use the **Data Search** tab to configure which process data keys are indexed for searching and filtering process instances.

![Data Search settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/process-settings-data-search-tab.png)

Data Search settings tab

#### Index search keys

The **Search Key Indexing** section lets you define which process data fields are searchable. These indexed keys enable efficient searching and filtering of process instances in the Active Process view.

**How to configure search keys**:

1. Click the **+** button to add a new search key.
2. Type at least 3 characters of the key path (for example, `application.client`), then select the key from the data model suggestions (for example, `application.client.firstName`).
3. Save your changes to apply the indexing configuration.

**Key path format requirements**:

* Use dot notation to access nested fields: `parent.child.fieldName`.
* Keys must match your data model structure exactly.
* Matching is case-sensitive.

**Example key paths**:

* `application.client.firstName`
* `application.client.lastName`
* `application.status`
* `application.dateOfBirth`

> [!TIP]
>
> **Process Data Keys**: These are paths or fields in the process definition that store relevant data. For example, `application.client.firstName` corresponds to a field capturing the first name within the client object.

> [!WARNING]
>
> **Re-indexing required**: After updating the data model structure, re-index the keys in the Search indexing tab to ensure accurate searching and filtering. Indexing can take several minutes for environments with many process instances.

> [!NOTE]
>
> **Performance consideration**: Only index keys you actually need for searching. Excessive indexing can impact performance. Focus on fields commonly used for filtering and searching process instances.

## Apply best practices

Follow these guidelines to create well-structured, maintainable process definitions.

### Follow configuration standards

Apply these best practices when configuring your process definitions:

**Platform selection**:

* Choose **Web Only** for desktop-focused applications with complex interactions.
* Choose **Mobile Only** for mobile-first experiences optimized for touch.
* Choose **Omnichannel** only when you need both platforms. Maintain separate processes when platform requirements diverge significantly.

**Naming and organization**:

* Use descriptive, consistent names that clearly identify the process purpose.
* Follow a naming convention like `[Department]_[Function]_[Action]` (for example, `HR_Onboarding_NewEmployee`).
* Avoid special characters beyond the allowed set: `[ ] ( ) . _ -`.
* Keep process names under 50 characters for better readability in lists.

**Data model design**:

* Define your data model structure before building process flows.
* Use meaningful key names that describe the data they contain.
* Organize related data under common parent keys (for example, `customer.firstName` and `customer.lastName`).
* Include example values in the data model to help with development and testing.
* Avoid deeply nested structures—limit nesting to 3-4 levels for better performance.

### Configure swimlanes effectively

**Swimlane best practices**:

* Create swimlanes that mirror your organizational structure or process ownership.
* Assign clear, descriptive names to swimlanes (for example, "Front Office", "Back Office", or "Supervisor").
* Configure appropriate permissions for each swimlane (execute, view, self-assign).
* Enable **Allow multiple executors** when multiple users with different roles need concurrent access.
* Limit the number of swimlanes—too many can make processes difficult to visualize. Aim for 3-5 maximum.

> [card] [Permission-based expressions](./permission-based-expressions)
>
> Learn advanced permission configuration for granular access control

### Optimize performance

**Settings that affect performance**:

* **Expiry time**: Set appropriate expiry times to prevent stale process instances from accumulating.
* **Task management integration**: Only enable when needed—it adds overhead for task tracking.
* **Reporting integration**: Enable selectively for business-critical processes that require analytics.
* **Search indexing**: Index only the keys you need for searching—excessive indexing affects performance.
* **General data**: Keep general data lightweight—it loads on every process start.

**Data model optimization**:

* Don't store large binary data in the process data model.
* Use references to external systems for large files or documents.
* Clean up temporary data that's no longer needed as the process progresses.

### Follow security best practices

> [!WARNING]
>
> Apply these security best practices:
>
> * **Never include sensitive data** in process names or descriptions.
> * **Use role-based permissions properly**: Don't grant execute permissions to roles that shouldn't start processes.
> * **Configure swimlane permissions carefully** to ensure data privacy.
> * **Enable Task Manager integration only** for processes where users need task-level visibility.
> * **Use environment-specific configuration parameters** for sensitive values like API endpoints.
> * **Set appropriate expiry times** to ensure processes don't remain active indefinitely.
> * **Review permission-based expressions** to ensure UI elements hide sensitive data from unauthorized users.

### Configuration checklist

Before deploying a process definition, verify:

**1. Basic Configuration**

* [ ] Process name is descriptive and follows naming conventions
* [ ] Platform selection (Web/Mobile/Omnichannel) matches your deployment target
* [ ] Data model is defined with clear, meaningful key names

**2. Permissions**

* [ ] Swimlanes are configured with appropriate roles
* [ ] Execute permissions are assigned to correct user roles
* [ ] Self-assign permissions are configured where needed
* [ ] Permission-based expressions are tested with different user roles

**3. Integrations**

* [ ] Task Manager integration enabled only if required
* [ ] Application URL configured correctly for Task Manager
* [ ] Keys to send to Task Manager are defined
* [ ] Reporting integration enabled only if needed
* [ ] Search indexing configured for relevant keys

**4. Advanced Settings**

* [ ] Expiry time expression set appropriately (if needed)
* [ ] General data configured for initial notifications (if needed)
* [ ] Audit log reviewed for recent changes

## Manage process versions

Process definitions are versioned as part of projects, providing comprehensive change management.

### Understanding versioning

> [!NOTE]
>
> Process definitions in FlowX.AI are versioned at the **project level**, not individually. This ensures all related resources stay synchronized.

**Version types**:

* **Draft versions**: Work-in-progress changes that you can edit freely.
* **Committed versions**: Finalized snapshots that become immutable.
* **Branches**: Parallel development paths for different features or environments.
* **Version comparison**: Tools to compare settings and configurations across versions.

### Make changes to process definitions

**1. Edit in draft**

Process definitions can only be edited when part of a draft project version. If you need to modify a committed process:

1. Create a new draft version of your project
2. Make your changes to the process definition
3. Test thoroughly
4. Commit the project version

**2. Commit changes**

When you commit a project version:

* The process definition becomes immutable
* It's available for inclusion in builds
* All settings are frozen at that point in time

**3. Deploy to environments**

Create a build from the committed version and deploy it to your target environments. The deployed process definition becomes active and can create process instances.

> [card] [Versioning](../../projects/managing-applications/versioning)
>
> Detailed guide to project versioning

> [card] [Builds and deployment](../../projects/runtime/builds)
>
> Learn about building and deploying processes

### Understand the impact on running instances

> [!WARNING]
>
> Changes to a process definition don't affect running process instances. Running instances continue using the version of the process definition that was active when they started.

**What this means**:

* You can safely deploy new process definition versions without affecting active users.
* Long-running processes complete using their original definition.
* New process instances use the latest deployed version.
* To apply changes to running instances, you need to migrate them (typically not recommended).

## Troubleshoot common issues

This section covers common issues when configuring process definitions and how to resolve them.

> [accordion] Process won't commit
>
> **Symptoms**: You can't commit project version or get errors when trying to save changes.
>
> **Common causes and solutions**:
>
> * **Validation errors**: Review process designer warnings and fix all configuration issues.
>
> * **Missing required nodes**: Ensure your process has at least one start node and one end node.
>
> * **Invalid expressions**: Check all business rules, cron expressions, and permission expressions for syntax errors.
>
> * **Permission issues**: Verify you have commit permissions for the project.
>
> * **Uncommitted dependencies**: Ensure all referenced subprocesses and workflows are also committed.
>
> > [!TIP]
> >
> > Check the validation warnings panel in the Process Designer before you try to commit.

> [accordion] Process instances won't start
>
> **Symptoms**: Users get errors when trying to start a new process instance.
>
> **Common causes and solutions**:
>
> * **Process not published**: Verify the process is part of an active build deployed to the environment.
>
> * **Missing permissions**: Check that user roles have execute permission on the process start node.
>
> * **Invalid start node configuration**: Review the start node settings and start conditions.
>
> * **Multiple start nodes without conditions**: If you have multiple start nodes, ensure each has a unique start condition.
>
> * **Environment mismatch**: Confirm the process is deployed to the correct environment.
>
> > [card] [Failed process start errors](../../projects/runtime/active-process/failed-process-start)

> [accordion] Task Manager integration not working
>
> **Symptoms**: The process doesn't appear in Task Manager or tasks aren't created.
>
> **Common causes and solutions**:
>
> * **Integration not enabled**: Enable "Use process in task management" in the **Task management** settings tab.
> * **Application URL misconfigured**: Verify the application URL format is correct and uses valid parameters.
> * **Keys not configured**: Define which keys should be sent to Task Manager.
> * **Indexing issues**: Keys may need re-indexing after data model changes.
> * **Task Manager service unavailable**: Check platform status to ensure the Task Manager service is running.

> [accordion] Search/filtering not working correctly
>
> **Symptoms**: You can't find process instances using search, or filters return incorrect results.
>
> **Common causes and solutions**:
>
> * **Keys not indexed**: Add the required keys to the Data Search configuration.
>
> * **Data model changes not re-indexed**: After changing the data model structure, re-index search keys.
>
> * **Incorrect key paths**: Verify the key paths match your actual data model structure and check for typos.
>
> * **Case sensitivity**: Search is case-sensitive—ensure queries match the actual data casing.
>
> * **Indexing delay**: Recent process instances may not be immediately searchable—allow time for indexing.
>
> > [!NOTE]
> >
> > Re-indexing can take several minutes for environments with many process instances.

> [accordion] Expiry time not working as expected
>
> **Symptoms**: Processes expire too early, too late, or not at all.
>
> **Common causes and solutions**:
>
> * **Cron expression errors**: Verify your cron expression includes all six required fields (seconds, minutes, hours, day, month, day of week).
>
> * **Time zone issues**: Cron expressions use server time zone—account for time zone differences.
>
> * **ISO 8601 format errors**: Check the duration format is correct (for example, `PT3M22S` for 3 minutes 22 seconds).
>
> * **Expiry not enabled**: Confirm the expiry time expression is configured in settings.
>
> * **Process already expired**: Processes past expiry time may not be startable.
>
> > [card] [Timer expressions](../node/timer-events/timer-expressions)

> [accordion] Platform-specific configuration issues
>
> **Symptoms**: Navigation areas or UI elements don't appear on expected platforms.
>
> **Common causes and solutions**:
>
> * **Incorrect platform setting**: Verify "Available Platforms" matches your navigation area configuration.
> * **Web Only with mobile navigation**: If set to Web Only, mobile navigation areas aren't available.
> * **Platform mismatch with deployment**: Ensure the deployed build targets the correct platform (web renderer or mobile renderer).
> * **Navigation areas not configured**: Check that navigation areas exist for the selected platform.
> * **UI Designer platform mismatch**: Verify UI elements are configured for the same platform as the process.

> [accordion] Permission configuration errors
>
> **Symptoms**: Users can't access the process, see unexpected UI elements, or can't perform actions.
>
> **Common causes and solutions**:
>
> * **Missing role assignments**: Verify users have required roles in your identity provider (for example, Keycloak).
>
> * **Swimlane permissions not configured**: Check that appropriate permissions (execute, view, self-assign) are set.
>
> * **Permission expressions incorrect**: Review permission-based expressions for syntax errors.
>
> * **Multiple executors not enabled**: If you need multiple users in the same swimlane, enable "Allow multiple executors".
>
> * **Cross-swimlane reference issues**: When referencing users from other swimlanes, store them in process data.
>
> > [card] [Permission-based expressions](./permission-based-expressions)

### Get help with other issues

If you continue experiencing issues:

1. Check the **audit log** to see recent changes that might have caused problems.
2. Review **process validation warnings** in the Process Designer.
3. Test with a **simple process** to isolate whether the issue is process-specific or environmental.
4. Check **Platform Status** to ensure all FlowX services are healthy.
5. Review **logs** in your FlowX.AI deployment for detailed error messages.

> [card] [Platform status monitoring](../../flowx-designer/overview#platform-status)
>
> Check the health of FlowX services

## Related resources

> [card] [Process Designer](./process)
>
> Learn about the canvas and design interface

> [card] [BPMN Nodes](../node/node)
>
> Complete guide to all node types

> [card] [Data Model](./data-model)
>
> Managing process data structures

> [card] [Subprocess](./subprocess)
>
> Creating reusable process components

> [card] [Navigation Areas](./navigation-areas)
>
> Configuring user navigation

> [card] [User Roles Management](../../platform-deep-dive/user-roles-management/swimlanes)
>
> Advanced swimlane configuration


# Subprocess management
Source: https://docs.flowx.ai/5.9/docs/building-blocks/process/subprocess

Learn how to configure, start, and execute subprocesses efficiently within your process flow.

Subprocesses are smaller process flows triggered by actions in the main process. They can inherit some process parameter values from the parent process and communicate with front-end apps using the same connection details as their parent process.

## Overview

Subprocesses can be started in two modes:

* **Asynchronous**: Execute alongside the parent process without delaying it.
* **Synchronous**: The parent process waits until subprocesses are finished before advancing.

## Knowledge for mobile

Screens rendered on mobile (Pages, Steps) are kept inside a navigation history which the user can go back to.

Subprocesses started from Call activity nodes share the navigation history (stack) with the main processes. When a subprocess is finished, it's UI is cleared from the navigation history. Design your BPMN processes in accordance with your business and ux needs.

Subprocesses started from User task nodes, should only be used for secondary flows that are displayed to the user, which should be rendered in modals. These flows should be optional event handlers. If the journey is mandatory, then consider moving it into call activities.

### Navigation back-stack behavior on mobile

This is the mental model for how the mobile back stack works across Pages, Modals, and Call Activity subprocesses.

**Pages and Steps.** Every Page or Step the user reaches is pushed onto the native back stack. The OS back button, gesture back, and any in-app back button pop the last entry. Users can back-navigate all the way to the first screen of the flow.

**Modals.** Modals are never kept in the back stack. When the flow advances past a modal onto the next screen, the modal is popped before the new entry is pushed. This is why you cannot back-navigate into a modal: by the time anything has been pushed after it, the modal is already gone.

**Modal internal navigation.** The recommended way to have back-navigation *between* modal-rendered screens is a single **Modal** navigation area with multiple User Tasks inside. Mobile renders each User Task as one screen (1 UT = 1 screen), with a built-in back button between them. Separate modal navigation areas cannot be stacked or linked this way.

**Call Activity subprocesses.** A Call Activity subprocess shares the same back stack as the parent process. While the subprocess runs, its Pages and Steps are pushed onto the shared stack alongside the parent's. The user can back-navigate through them normally.

**Call Activity finish.** When the subprocess finishes, the user is returned to the last screen of the parent process (where the Call Activity was started from). The subprocess's screens are cleared from the back stack, so the user cannot return to them after completion.

**Modals and Call Activity interact as expected.** A modal inside a Call Activity is not special: the OS auto-pops it on forward navigation, and the subprocess-finish clearing operates on whatever Pages or Steps remain. The user never lands on a modal via back, regardless of whether it was inside the parent process or the subprocess.

***

## Subprocess design rules

> [!WARNING]
>
> **Hard rules for subprocesses:**
>
> * **Avoid nesting a UI subprocess under a headless one.** A subprocess with no UI should not contain a subprocess with UI. The hierarchy is harder to read and maintain. See [Process design principles](./design-principles#avoid-nesting-a-ui-subprocess-under-a-headless-one) for the full rationale.
> * **A child subprocess must not dismiss its parent.** A subprocess of a subprocess should not end the lifecycle of the parent subprocess. Completion of a grandchild should only resolve the grandchild.
> * **UI subprocesses must start synchronously.** A subprocess with UI should never start in async mode. Async UI subprocesses race with the parent's token advance and get dismissed before the user can complete them.
> * **Starting a subprocess from a user task action.** Use modal-only navigation for the entry point and keep the starting action **optional**. Mandatory UT actions that launch subprocesses block the flow if the subprocess cannot start.
> * **Call Activity subprocesses with Pages or Steppers appear in mobile back-nav.** Their screens land in the native back stack. Design flows so that back-navigation actions land on **meaningful states**, not orphaned or mid-step screens.
> * **A subprocess rendered inside the parent must have exactly one swimlane.** A subprocess whose UI renders in the parent process (through a **Parent Process** navigation area) requires a single swimlane. With multiple swimlanes, the runtime can't render it and reports `Could not render subprocess due to multiple swimlanes or missing Parent Process Area` - see the [error glossary](../../resources/error-glossary#could-not-render-subprocess-due-to-multiple-swimlanes-or-missing-parent-process-area).

***

## Configuring & starting subprocesses

Design subprocesses within the FlowX.AI Designer, mirroring the main process structure.

**1. Start Subprocess Action**

* Within user tasks or task nodes.

**2. Call Activity node**

* Custom node type in the main process.

**3. Start Embedded Subprocess node**

* Using the corresponding node.

> [!TIP]
>
> For when to use a Call Activity and when to use a Start Embedded Subprocess node, see [Call Activity or embedded subprocess](./call-activity-vs-embedded-subprocess).

### Parameter inheritance

> [!NOTE]
>
> Available for **Start Subprocess** action and **Call Activity** node.

By default, subprocesses inherit all parent process parameter values. Configure inheritance by:

* **Copy from Current State**: Select keys to copy.
* **Exclude from Current State**: Specify keys to ignore.

Sub-processes can also have an [**Append Params to Parent Process**](../actions/append-params-to-parent-process) action  configured inside their process definitions which will append their results to the parent process parameter values.

> [card] [Append Params to Parent Process](../actions/append-params-to-parent-process)

## Executing subprocesses

Define subprocess execution mode:

* **Asynchronous/Synchronous**: Set the `startedAsync` parameter accordingly.

In synchronous mode, subprocesses notify completion to the parent process. The parent process then resumes its flow and handles subprocess data.

## How data flows between subprocess and parent

When a subprocess needs to send data back to the parent process, FlowX provides several mechanisms. Choosing the right one depends on whether you need data in the parent UI, the parent data model, or both.

### Data return mechanisms

| Mechanism | What it does | Parent data model | Parent UI | When to use |
| - | - | :-: | :-: | - |
| [**Append Params to Parent Process**](../actions/append-params-to-parent-process) | Copies specified keys from subprocess into the parent process data model | Yes | No (until next UI refresh) | Business logic in the parent needs subprocess results (conditions, validations, downstream actions) |
| [**Send data to user interface**](../actions/send-data-to-user-interface) (target: Parent) | Pushes data to the parent process UI via SSE | No | Yes (real-time) | Real-time UI updates while the subprocess runs (progress indicators, live previews) |
| **Call Activity output key** (sync mode) | Automatically returns subprocess data under a configured key when the subprocess completes | Yes | No | Sync subprocesses where the parent waits for results |
| **Embedded subprocess** | Shares the parent data model directly, no data transfer needed | Shared | Shared | Simple subprocess logic that operates on the same data |

### Common patterns

**"I need data in both the parent data model and the parent UI"**
Use both actions: configure **Append Params to Parent Process** to persist the data, and **Send data to user interface** (target: Parent) to push the update to the UI immediately.

**"My subprocess has a throw event before the end node — do output parameters still get sent?"**
Output parameters configured on the Call Activity node are sent when the subprocess token reaches the **End** node. If the subprocess ends via a throw event before reaching End, the output parameters are not automatically returned. Use **Append Params to Parent Process** before the throw event to ensure data reaches the parent.

### Message format example

When using **Send data to user interface** to push data to the parent UI, the message body follows this format:

```json theme={"dark"}
{
  "application": {
    "clientName": "${application.client.firstName}",
    "status": "verified"
  }
}
```

This data is sent via SSE and rendered in the parent process UI, but is **not** stored in the parent process data model.

***

## Additional resources

> [card] [Call activity node](../node/call-subprocess-tasks/call-activity-node)

> [card] [Start a subprocess action](../actions/start-subprocess-action)

> [card] [Start embedded subprocess](../node/call-subprocess-tasks/start-embedded-subprocess)

> [card] [Synchronous Subprocesses course](https://academy.flowx.ai/explore/synchronous-subprocesses-0)
>
> Academy course covering embedded/call activities, UI updates, and data passing patterns


# UI Designer best practices
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/best-practices

Best practices for creating effective user interfaces using FlowX.AI UI Designer, based on established design principles and platform capabilities.

## UI Designer best practices in FlowX.AI

When designing user interfaces with FlowX.AI UI Designer, following established best practices ensures consistent, usable, and effective user experiences.

## Design principles

Based on FlowX.AI documentation for creating user interfaces:

> [card] Consistent Styling
>
> **Use consistent styling across all screens** for a cohesive user experience.
>
> Use platform-specific overrides strategically while maintaining visual consistency.

> [card] Logical Grouping
>
> **Group related inputs within logical sections or cards**.
>
> Use Cards and Containers to organize content and create visual hierarchy.

> [card] Proper Validation
>
> **Implement proper validation** to prevent errors and guide users.
>
> Use available validators: required, custom, and conditional validation.

> [card] Clear Feedback
>
> **Provide clear feedback** on actions with success and error messages.
>
> Use event handlers to handle user interactions appropriately.

## Component usage guidelines

### Form elements best practices

> [accordion] Input Fields
>
> **Configuration**:
>
> * Use clear, descriptive labels
> * Implement appropriate validation (required, custom)
> * Configure hide/disable expressions for dynamic behavior
> * Add helper text for complex requirements
>
> **Available Properties**:
>
> * Label and placeholder text
> * Validation rules (required, custom)
> * Hide and disable expressions
> * Platform-specific overrides

> [accordion] Selection Components
>
> **Select Component**:
>
> * Use for dropdown menus and single selections
> * Configure options with proper labels and values
> * Implement CHANGE event handlers for dependent fields
> * Use disabled options feature for conditional availability
>
> **Radio Buttons**:
>
> * Best for 2-4 exclusive options
> * Use when all options need to be visible
>
> **Checkboxes**:
>
> * Use for multiple selections or single yes/no choices
> * Configure CHANGE events for dynamic interactions

> [accordion] Action Components
>
> **Buttons**:
>
> * Use descriptive labels that indicate the action
> * Configure appropriate event handlers (Process Actions, Data Operations)
> * Consider platform-specific button styles
>
> **File Upload**:
>
> * Clearly indicate accepted file types
> * Provide appropriate feedback during upload process
> * Consider platform limitations for mobile devices

### Layout best practices

> [tab] Linear Layout
>
> **When to Use**: Simple, sequential content flow
>
> **Configuration**:
>
> * **Direction**: Choose Horizontal for row layout, Vertical for column layout
> * **Justify**: Control main axis alignment (Start, Center, End, Space Between, etc.)
> * **Align**: Control cross axis alignment (Start, Center, End, Stretch)
> * **Gap**: Set appropriate spacing between elements
> * **Wrap**: Enable for responsive behavior when needed
>
> **Best For**:
>
> * Form layouts
> * Content that flows in one direction
> * Mobile-first designs

> [tab] Grid Layout
>
> **When to Use**: Complex, multi-dimensional layouts
>
> **Benefits**:
>
> * Better control over 2D layouts
> * Responsive design capabilities
> * Suitable for dashboard-style interfaces
>
> **Considerations**:
>
> * More complex to configure than linear layouts
> * Test across platforms for consistent behavior

## Platform-specific best practices

### Web Platform

**1. Navigation Design**

**Navigation Types**:

* Use **Single Page Form** for displaying all User Tasks on the same page
* Use **Wizard** navigation for step-by-step processes
* Configure actions properly for smooth navigation flow

**2. Zone Configuration**

**Web-Specific Features**:

* Utilize zones with headers and footers (web-only feature)
* Implement proper navigation hierarchy
* Use cards to guide users through content on single-page forms

**3. Layout Optimization**

**Screen Real Estate**:

* Take advantage of larger screen sizes
* Use appropriate justify and align settings for content distribution
* Consider horizontal layouts for better space utilization

### Mobile Platforms (iOS & Android)

> [accordion] Screen Configuration
>
> **Mobile-Specific Properties**:
>
> * Configure **Screen Title** for navigation bar display (Card component when used as root)
> * Set **Scrollable** property appropriately (iOS-specific)
> * Use platform overrides for shorter titles and mobile-optimized content
>
> **Limitations**:
>
> * Zones with headers and footers are not supported
> * Navigation features are more limited compared to web

> [accordion] Content Adaptation
>
> **Content Strategy**:
>
> * Use shorter titles and labels for mobile displays
> * Consider touch interaction patterns
> * Ensure content fits within mobile screen constraints
> * Test with realistic content lengths

## Dynamic behavior best practices

### Hide and Disable Expressions

> [tab] Hide Expressions
>
> **Purpose**: Control element visibility based on conditions
>
> **Implementation**:
>
> * Use JavaScript expressions that evaluate to true/false
> * Reference process data store keys for dynamic evaluations
> * Configure in Settings → Platform → Overrides → Expressions → Hide
>
> **Common Use Cases**:
>
> * Show/hide fields based on user selections
> * Display different content for different user roles
> * Adapt interface based on process state

> [tab] Disable Expressions
>
> **Purpose**: Make elements non-interactive while keeping them visible
>
> **Best Practice**: Ensure disabled fields have the same expression configured under hide expressions for consistency.
>
> **Usage**: Disable form fields based on validation state or user permissions

### Conditional Styling

**Available For**: Text, Link, and Container elements

**1. Configuration**

1. Select a **Text**, **Link**, or **Container** element
2. Navigate to the **Styles** tab
3. Locate the **Conditional Styling** section
4. Click the **➕** icon to add expressions and effects
5. Use the **JS Editor** to configure expressions

**2. Structure**

**Condition**: String expression evaluated similarly to hide/disable expressions
**Overrides**: Key-value map defining property-value pairs to apply

**3. Best Practices**

* Use real-time data evaluation for responsive UI updates
* Handle conflict resolution (latest condition takes precedence)
* Combine with data-driven expressions for adaptable designs

## Validation best practices

### Available Validators

> [accordion] Required Validator
>
> **Usage**: Ensure essential fields are completed before form submission
>
> **Application**: Apply to critical form elements like name, email, or selection fields

> [accordion] Custom Validator
>
> **Usage**: Implement complex business logic validation
>
> **Benefits**: Flexible validation rules specific to your business requirements
>
> **Configuration**: Use JavaScript expressions for validation logic

> [accordion] Conditional Validation
>
> **Usage**: Apply validation based on other field values or process state
>
> **Examples**: Validate fields only when certain conditions are met

## Event handlers best practices

### Event Configuration

**Common Events**:

* **CHANGE**: Triggered when form element values change
* Use for updating dependent fields, triggering calculations, showing/hiding related content

**Action Types**:

* **Process Actions**: Advance workflow based on user interactions
* **Data Operations**: Update form fields and process data
* **UI Updates**: Show/hide elements dynamically
* **External Calls**: Integrate with external systems

> [!TIP]
>
> Configure event handlers to provide immediate feedback and create responsive user experiences.

## Testing and quality assurance

### Platform Testing

**1. Multi-Platform Preview**

Use the UI Designer's platform switching to preview designs across Web, iOS, and Android platforms.

**2. Responsive Testing**

Test layouts with different content lengths and screen orientations.

**3. Expression Validation**

Test hide/disable expressions and conditional styling with various data scenarios.

**4. Navigation Flow**

Verify wizard navigation and single-page form behaviors work as expected.

### Content Considerations

> [card] [Accessibility](../../platform-deep-dive/accessibility)
>
> **Design Considerations**:
>
> * Use proper labels for form elements
> * Ensure sufficient color contrast
> * Test with assistive technologies
> * Provide alternative text for images
>
> For details on WCAG 2.1 compliance, keyboard navigation, and screen reader support, see the [Accessibility guide](../../platform-deep-dive/accessibility).

> [card] Responsive Design
>
> **Test Strategy**:
>
> * Verify layouts work on different screen sizes
> * Test navigation on both mobile and web
> * Ensure content remains readable across platforms
> * Check platform-specific overrides function correctly

## Common patterns and solutions

### Navigation areas management

**Copy Navigation Areas**: Use the copy/paste feature to replicate navigation hierarchies between platforms (within the same process definition and environment).

**Area Deletion**: When deleting navigation areas, remember that child areas are also removed, and user tasks are relocated to the User Tasks section.

### Theme and styling management

**Theme Overrides**:

* Customize component appearance to differ from theme settings
* Import/export theme overrides between platforms for consistency
* Use contextual menu options for efficient style management

**Style Copying**: Use copy/paste functionality for styles between compatible components and across platforms.

> [!NOTE]
>
> These best practices are based on actual FlowX.AI capabilities and documentation. Always refer to the latest documentation for the most current features and recommendations.


# Platform-specific considerations
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/platform-considerations

Platform-specific configuration, limitations, and best practices for Web, iOS, and Android platforms in FlowX.AI UI Designer.

## Platform-specific configuration

FlowX.AI UI Designer provides platform-specific configuration and styling for components across **Web**, **iOS**, and **Android** platforms. Understanding platform differences and capabilities is essential for creating optimal user experiences.

## Platform overview

### Supported platforms

> [card] Web
>
> **Full Feature Support**
>
> * Complete navigation area functionality
> * Zones with headers and footers
> * Wizard and single-page navigation
> * All UI component types supported

> [card] iOS
>
> **Mobile-Optimized**
>
> * Basic navigation areas
> * Screen title configuration for navigation bar
> * Scrollable property for root card components
> * Platform-specific property overrides

> [card] Android
>
> **Mobile-Optimized**
>
> * Basic navigation areas
> * Screen title configuration for navigation bar
> * Platform-specific property overrides
> * Material design considerations

## Web platform features

### Navigation capabilities

**Full Navigation Support**: Web platform provides the most comprehensive navigation features.

> [accordion] Zone Navigation
>
> **Web-Exclusive Features**:
>
> * Zones with headers and footers
>
> * Complete navigation hierarchy
>
> * Advanced navigation patterns
>
> > [!WARNING]
> >
> > Zones with headers and footers are exclusively accessible in web configurations. They are not supported as navigation areas for mobile development.

> [accordion] Navigation Types
>
> **Single Page Form (Default)**:
>
> * Web Renderer displays all User Tasks within the same page (in parallel)
> * Use cards to guide users through content
> * Child areas rendered on the same page
>
> **Wizard Navigation**:
>
> * Displays one user task at a time
> * Custom Next and Back buttons
> * Child areas presented sequentially
> * Requires proper action configuration

### Component support

**Full Component Library**: Web platform supports all UI component types without restrictions.

## Mobile platform features

### iOS platform specifics

> [tab] Screen Configuration
>
> **iOS-Specific Properties**:
>
> **Screen Title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root)
>
> **Scrollable Property**: Define the desired behavior of the screen, specifying whether it should be scrollable or not (default: true)
>
> ```json theme={"dark"}
> {
>   "screenTitle": "User Profile",
>   "scrollable": true
> }
> ```

> [tab] Navigation Limitations
>
> **Mobile Navigation Restrictions**:
>
> * Basic navigation areas only
> * No zones with headers and footers
> * Limited navigation types compared to web
> * Navigation hierarchy displayed beneath platform tabs

> [tab] Component Adaptations
>
> **iOS Considerations**:
>
> * Screen size variations (iPhone, iPad)
> * Touch interaction patterns
> * Platform-specific styling requirements
> * System integration features

### Android platform specifics

> [accordion] Screen Configuration
>
> **Android-Specific Features**:
>
> **Screen Title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root)
>
> **Material Design Considerations**: Android components adapt to Material Design principles where applicable

> [accordion] Device Variations
>
> **Android Ecosystem**:
>
> * Multiple screen sizes and densities
> * Different Android versions
> * Manufacturer-specific customizations
> * Hardware capability variations

## Platform override system

### Configuration hierarchy

**1. Generic Settings**

**Base Configuration**: Properties available cross-platform (Web, Android and iOS), serving as the default for all platforms.

**2. Platform Overrides**

**Specific Customizations**: Override generic settings for individual platforms to optimize user experience.

**3. Preview and Testing**

**Visual Validation**: Preview changes across platforms, keeping in mind that iOS and Android previews are estimates.

### Implementing overrides

To configure platform-specific overrides:

**1. Access Platform Settings**

From the UI Designer navigation panel, select the **Settings** tab, then select the **desired platform** (Web, iOS, or Android).

**2. Add Override**

Click the "+" button (next to "Overrides") and select the type of override:

* **Properties**: Override component properties (e.g., Title, Subtitle, Helper text)
* **Expressions**: Override hide/show conditions

**3. Configure Value**

Enter the platform-specific value that differs from the generic setting.

**4. Import/Export**

Use the import/push functionality to share overrides between platforms when appropriate.

### Available override types

> [tab] Property Overrides
>
> **Common Property Overrides**:
>
> * **Title**: Shorter titles for mobile displays
> * **Subtitle**: Platform-appropriate subtitles
> * **Helper Text**: Context-specific help information
> * **Labels**: Adapted for platform conventions
>
> **Example Use Case**: Web title "Complete Application Process" → Mobile title "Complete App"

> [tab] Expression Overrides
>
> **Hide Expressions**: Platform-specific visibility conditions
>
> **Use Cases**:
>
> * Show different content on mobile vs desktop
> * Hide complex features on mobile platforms
> * Adapt to platform-specific user flows

## Platform limitations and constraints

### Component availability

| Component Type | Web | iOS | Android | Notes |
| - | - | - | - | - |
| Container | ✅ | ✅ | ✅ | Full support across platforms |
| Card | ✅ | ✅ | ✅ | Mobile has additional screen title property |
| Custom | ✅ | ❌ | ❌ | Web-only component |
| Form Elements | ✅ | ✅ | ✅ | Full support with platform adaptations |
| Navigation Areas | ✅ | ⚠️ | ⚠️ | Limited on mobile (no headers/footers) |

> [!NOTE]
>
> ⚠️ = Limited functionality or platform-specific constraints\
> ❌ = Not supported on platform

### Styling and layout limitations

These design-time options are applied by the **web renderer only**. Native iOS and Android renderers do not honor them:

* **Custom CSS**: custom CSS is a web-only styling mechanism; native renderers ignore it.
* **Justify layout options**: the **Justify** setting (Start, Center, End, Space Between, Space Around, Space Evenly) is honored on web only.

### Navigation limitations

> [accordion] Mobile Navigation Constraints
>
> **Limitations**:
>
> * No zones with headers and footers on mobile
> * Limited navigation types (no wizard mode on mobile)
> * Simplified navigation hierarchy
> * Basic navigation areas only
>
> **Workarounds**:
>
> * Use card-based layouts for mobile organization
> * Implement navigation through event handlers
> * Use platform-specific screen titles

> [accordion] Cross-Platform Consistency
>
> **Challenges**:
>
> * Different navigation capabilities across platforms
> * Varying screen sizes and interaction methods
> * Platform-specific design conventions
>
> **Solutions**:
>
> * Use generic settings as baseline
> * Apply strategic platform overrides
> * Test across all target platforms
> * Design for the most constrained platform first

## Platform-specific best practices

### Web platform optimization

> [card] Navigation Design
>
> **Use Web Capabilities**:
>
> * Use full zone navigation with headers/footers
> * Implement wizard navigation for complex flows
> * Take advantage of larger screen real estate
> * Use single-page forms with card organization

> [card] Layout Strategy
>
> **Web-Specific Layouts**:
>
> * Utilize horizontal space effectively
> * Implement complex grid layouts
> * Support both single-page and wizard navigation
> * Consider desktop interaction patterns

### Mobile platform optimization

**1. Screen Space Management**

**Mobile Constraints**:

* Smaller screen sizes require condensed content
* Use shorter titles and labels
* Prioritize essential information
* Consider thumb-friendly interaction zones

**2. Platform Integration**

**Mobile-Specific Features**:

* Configure screen titles for navigation bars
* Set appropriate scrollable behavior (iOS)
* Consider platform design conventions
* Test on actual devices when possible

**3. Content Adaptation**

**Mobile Content Strategy**:

* Use platform overrides for mobile-optimized text
* Simplify complex interactions
* Ensure touch targets are appropriately sized
* Test with realistic content lengths

## Testing across platforms

### Preview limitations

> [!NOTE]
>
> **Important**: The preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view. Actual device testing is recommended for production applications.

### Testing Strategy

> [accordion] Platform Switching
>
> **UI Designer Testing**:
>
> * Use platform tabs to switch between Web, iOS, and Android views
> * Compare layouts and content across platforms
> * Validate platform overrides are applied correctly
> * Check navigation behavior differences

> [accordion] Content Validation
>
> **Cross-Platform Content**:
>
> * Verify text fits within mobile constraints
> * Test with longest expected translations
> * Ensure critical information is visible on all platforms
> * Validate platform-specific features function correctly

> [accordion] Functionality Testing
>
> **Feature Validation**:
>
> * Test navigation flows on each platform
> * Verify platform-specific components work as expected
> * Validate hide/show expressions across platforms
> * Test conditional styling behavior

## Migration and maintenance

### Platform updates

> [!TIP]
>
> **Override Management**: Settings overrides can always be imported/pushed from one platform to another, making it easier to maintain consistency while allowing for platform-specific optimizations.

### Maintenance best practices

**1. Regular Testing**

Test your interfaces across all target platforms regularly, especially after making changes to generic settings or platform overrides.

**2. Documentation**

Document platform-specific decisions and overrides to help team members understand the rationale behind platform differences.

**3. Consistency Monitoring**

Regularly review platform overrides to ensure they still serve their intended purpose and maintain overall design consistency.

> [!TIP]
>
> Understanding platform-specific considerations helps you create interfaces that work well across all target platforms while taking advantage of each platform's unique capabilities and respecting their constraints.


# Screen configuration guide
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/screen-configuration-guide

Learn how to configure screens effectively using FlowX.AI UI Designer with platform-specific settings and navigation areas.

FlowX.AI UI Designer allows you to create rich, interactive user interfaces for your process flows. The UI Designer is available for **User Task** nodes and **Navigation Areas** elements, providing contextual interface design capabilities.

## Platform-specific configuration

FlowX.AI provides platform-specific configuration and styling for components across **Web**, **iOS**, and **Android** platforms.

### Generic vs platform-specific settings

> [tab] Generic Settings
>
> **Cross-Platform Properties**: Configure properties available cross-platform (Web, Android and iOS), available for all platforms.
>
> These settings serve as the base configuration that applies to all platforms unless specifically overridden.

> [tab] Platform-Specific Overrides
>
> **Platform-Specific Configuration**: Override generic settings for specific platforms.
>
> For example, on Android, you might want to change the Card title to a shorter one to better fit mobile screens.

### Configuring platform overrides

To override a general property for a specific platform:

**1. Access UI Designer**

Open the UI Designer and select a UI Element, such as a **Card**.

**2. Access Platform-Specific Settings**

From the UI Designer navigation panel, select the **Settings** tab, then select the **desired platform** (Web, iOS, or Android).

**3. Perform Override**

Click the "+" button (next to "Overrides") and select **Properties** -> select the property you want to override (e.g., **Title**), then input your desired value.

**4. Preview Changes**

Preview your changes in the UI Designer by navigating from one platform to another or by comparing them.

> [!TIP]
>
> Settings overrides can always be imported/pushed from one platform to another for consistency across platforms.

> [!NOTE]
>
> Keep in mind that the preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view.

## Navigation areas configuration

Navigation areas play a pivotal role in user interface design. They enhance the user experience by providing a structured, organized, and efficient way for users to interact with and explore various features and solutions.

### Navigation types (web only)

> [accordion] Single Page Form (Default)
>
> **Behavior**: The Web Renderer will display all User Tasks within the same page (in parallel).
>
> **Best Practices**:
>
> * Use **Cards** to guide users through the content
> * Apply **Accordions** to cards to collapse each card after validation
> * Maintain a clean UI while displaying multiple user tasks
>
> **Child Areas**: Rendered on the same page

> [accordion] Wizard Navigation
>
> **Behavior**: The Web Renderer will display one user task at a time, allowing navigation using custom Next and Back buttons.
>
> **Usage**: Ideal for step-by-step or wizard-style navigation within a page when a page contains more than one User Task.
>
> **Child Areas**: Presented sequentially
>
> > [!WARNING]
> >
> > It's crucial to configure actions properly to ensure smooth user navigation in wizard mode.

> [!NOTE]
>
> Navigation types are only available for **Web** platform configurations.

### Platform hierarchy

In the navigation panel, the navigation hierarchy is displayed beneath platform tabs:

* **Web Platform**: Full navigation features including zones with headers and footers
* **Mobile Platforms** (iOS & Android): Limited navigation features

> [!WARNING]
>
> Zones with headers and footers are exclusively accessible in web configurations. They are not supported as navigation areas for mobile development.

## Layout configuration

Layout settings are available for all components that can group other types of elements (for example, **Containers** or **Cards**).

### Linear layout properties

> [accordion] Display Mode
>
> **Linear**: Selected by default for arranging child elements in a linear fashion.

> [accordion] Direction
>
> * **Horizontal**: Aligns child elements horizontally in a row
> * **Vertical**: Aligns child elements vertically in a column

> [accordion] Justify
>
> Controls the alignment of child elements along the main axis (the direction set by Horizontal or Vertical):
>
> * **Start**: Aligns elements at the start of the container
> * **Center**: Centers elements along the main axis
> * **End**: Aligns elements at the end of the container
> * **Space Between**: Distributes elements evenly with space between them
> * **Space Around**: Distributes elements with space around them
> * **Space Evenly**: Distributes elements with equal space around them

> [accordion] Align
>
> Controls the alignment of child elements along the cross axis (perpendicular to the main axis):
>
> * **Start**: Aligns elements at the start of the cross axis
> * **Center**: Centers elements along the cross axis
> * **End**: Aligns elements at the end of the cross axis
> * **Stretch**: Stretches elements to fill the container along the cross axis

> [accordion] Wrap
>
> * **Yes**: Allows elements to wrap onto multiple lines when they exceed the container's width
> * **No**: Forces all elements to remain on a single line, potentially causing overflow

> [accordion] Gap
>
> Sets the spacing between child elements, measured in pixels.

## Hide and disable expressions

Configure dynamic visibility and interaction using JavaScript expressions:

### Available expression types

> [tab] Hide Condition
>
> **Purpose**: A JavaScript expression that hides the UI element when it evaluates to a truthy value.
>
> **Usage**: Control element visibility based on process data or user interactions.
>
> **Example**: Hide a field based on user role or form state.

> [tab] Disabled Condition
>
> **Purpose**: A JavaScript expression that disables the UI element when it returns a truthy value.
>
> **Usage**: Make elements non-interactive while keeping them visible.
>
> > [!NOTE]
> >
> > It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

### Expression configuration

Configure expressions for dynamic behavior:

1. Select the UI component in the **UI Designer**
2. Navigate to **Settings** → **your desired platform** → **Overrides (+)** → **Expressions**
3. Configure **Hide** or **Disabled** conditions
4. Add your JavaScript expression

## Best practices for screen configuration

Follow these design principles to create efficient, user-friendly interfaces that perform well across all platforms.

### Core design principles

> [accordion] Single Purpose User Tasks
>
> **Keep user tasks focused**:
>
> * Design each user task with **one clear purpose** to avoid cognitive overload
>
> * Limit the number of UI components per screen to prevent overcrowding
>
> * Break complex processes into multiple, focused user tasks
>
> * Use progressive disclosure to reveal information when needed
>
> > [!WARNING]
> >
> > Overcrowded screens with too many UI components can lead to poor user experience and potential performance issues during process execution.

> [accordion] Efficient Layout Structure
>
> **Optimize container usage**:
>
> * **Avoid unnecessary nesting** of containers whenever possible
>
> * **Don't nest containers** solely for sizing or layout purposes
>
> * **Prefer grid layout** over nested containers for complex arrangements
>
> * Use **linear layout** and **alignments** for simpler positioning needs
>
> > [!TIP]
> >
> > Grid layout is your primary tool for creating complex layouts efficiently. It reduces nesting while providing flexible positioning capabilities.

> [accordion] Conditional Styling Strategy
>
> **Use hide expressions wisely**:
>
> * **Minimize the use** of hide expressions to maintain performance
>
> * Consider using **conditional styling** instead of hiding elements when possible
>
> * Group related conditional elements to reduce expression complexity
>
> * Document complex conditional logic for maintainability
>
> > [!WARNING]
> >
> > Overusing hide expressions can negatively impact performance and make interfaces harder to maintain.

### Implementation recommendations

> [accordion] Navigation Design
>
> **For optimal navigation**:
>
> * Use **Cards** to guide users through content on single-page forms
> * Apply **Accordions** to collapse validated sections
> * Configure actions properly for wizard-style navigation
> * Consider platform limitations (mobile vs web features)

> [accordion] Platform Considerations
>
> **Multi-Platform Design**:
>
> * Start with generic settings as your base configuration
> * Use platform-specific overrides strategically (e.g., shorter titles on mobile)
> * Test previews across all target platforms
> * Remember that iOS/Android previews are estimates

> [accordion] Layout Best Practices
>
> **Effective Layout Strategy**:
>
> * **Prioritize grid layout** for complex arrangements
> * Use **linear layout** for simple sequential content
> * Apply proper **alignment settings** instead of wrapper containers
> * Choose appropriate layout direction for your content flow
> * Use gap settings to create proper spacing hierarchy
> * Consider responsive wrapping for dynamic content
> * Test layouts with realistic content lengths

> [accordion] Performance Optimization
>
> **Maintain optimal performance**:
>
> * Limit UI component density per screen
>
> * Reduce container nesting depth
>
> * Minimize complex hide expressions
>
> * Use efficient layout methods (grid over nested containers)
>
> * Test with realistic data volumes
>
> > [!TIP]
> >
> > Well-designed screens with proper layout structure and minimal nesting perform better and provide smoother user interactions.

## Configuration examples

### Mobile configuration example

For mobile platforms (iOS & Android), you can configure specific properties:

**Card Component Example**:

* **Screen Title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root)
* **Scrollable Property** (iOS): Define whether the screen should be scrollable (default: true)

### Platform override example

Override a card title for different platforms:

> [tab] Generic Setting
>
> **Title**: "Complete Application Process"

> [tab] Mobile Override
>
> **Title**: "Complete App" (shorter for mobile displays)

This approach ensures your interfaces are optimized for each platform while maintaining consistency in functionality.


# Collection
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/collection/collection

The Collection component functions as a versatile container element, allowing you to iterate through a list of elements and display them according to their specific configurations.

## Configurable properties

* `collectionSource`: This property specifies the process key where a list can be found. It should be a valid array of objects.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_source_key1.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/%20collection_source_key.png)

## Example usage

Here's an example of configuring a Collection component to display a list of products:

![Collection configuration for displaying employees](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_example.png)

Source collection data example using an [**MVEL business rule**](../../../actions/business-rule-action/business-rule-action):

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_mvel.png)

```java theme={"dark"}
output.put("processData", //this is the key
{
  "products": [ // this is the source that will populate the data on collection
    {
      "name": "Product One Plus",
      "description": "The plus option",
      "type": "normal"
    },
    {
      "name": "Product Two Premium",
      "description": "This is premium product",
      "type": "recommended"
    },
    {
      "name": "Product Basic",
      "description": "The most basic option",
      "type": "normal"
    },
    {
      "name": "Gold Product",
      "description": "The gold option",
      "type": "normal"
    }
  ]
}
);
```

The above configuration will render the Collection as shown below:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/render_collection.gif)

> [!NOTE]
>
> Components within a collection use **relative paths** to the collection source. This means that wherever the collection is found inside the process data, the components inside the collection need their keys configured relative to that collection.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_relative_key.png)
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_key_rule.png)

> [!WARNING]
>
> To send and display dynamic data received on the keys you define to the frontend, make sure to include the following data structure in your root UI element using Message parameters. For instance, if you want to include data for the `processData` key mentioned earlier, your configuration should resemble this:
>
> ```json theme={"dark"}
> {
>   "processData": ${processData}
> }
> ```

> [!TIP]
>
> **When do you need Collection Prototypes?**
>
> * **Single layout for all items**: If all items in your collection should display the same way, add one Collection Prototype and leave PIK/PIV empty
> * **Multiple layouts based on item properties**: If items should display differently based on their data (like the `type` field in the example above), add multiple Collection Prototypes with PIK/PIV configured
>
> For detailed configuration guidance, see the Collection Prototype documentation:

> [card] [Collection prototype](/5.9/docs/building-blocks/ui-designer/ui-component-types/collection/collection-prototype)

***

## Forms in collections

> [!NOTE]
>
> Forms in Collections is a feature that enables you to create dynamic, repeatable forms within collection prototypes. This eliminates the need for custom development when building forms with repeatable sections like adding multiple co-debtors or comment entries.

### Overview

Forms in Collections addresses common pain points in form design:

* **Dynamic Forms**: No longer need custom development to support dynamic forms that show different form elements based on certain conditions
* **Repeatable Sections**: Create forms with repeatable sections like adding co-debtors, comments, or any list of similar items
* **Flexible Validation**: Support both individual item validation and bulk validation scenarios

The feature allows you to drag Form components directly into Collection Prototypes, where they automatically repeat for each item in your data array.

![Forms in Collections](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic1.png)

> [!NOTE]
>
> Collection source rules remain the same as regular collections. Each key in collection prototypes uses a prefix computed from the collection source and the index of the object being displayed. At runtime, keys are constructed with the full object path (e.g., `application.clients[0].name`).

### How it works

When you add forms to a collection prototype:

1. **Data Structure**: Your process data contains an array of objects (e.g., `application.clients`)
2. **UI Configuration**: Collection component points to your array, and Form components are placed inside Collection Prototypes
3. **Key Generation**: Form field keys are automatically prefixed with the collection path and item index
4. **Runtime Behavior**: Each collection item gets its own form instance with properly scoped keys

### Implementation guide

**1. Prepare your data structure**

Set up your process data with an array to hold the repeatable items:

```javascript theme={"dark"}
// Define an object named 'application' to store client information
var application = {
    client: {
        // Store the client's name
        name: "Aang the Last Airbender",
        // Store the loan amount details
        loanAmount: {
            amount: 238989, // The loan amount
            code: "USD" // The currency code for the loan amount
        },
        // List of codebtors associated with the loan
        codebtors: [
            {
                // First codebtor's name and occupation
                id: 1,
                name: "Sokka",
                occupation: "Boomerang Master"
            },
            {
                // Second codebtor's name and occupation
                id: 2,
                name: "Prince Zuko",
                occupation: "Firebending Master"
            }
        ]
    }
};

// Output the client information from the application object
output.put("application", { "client": application.client });
```

**2. Create the Collection component**

1. In the UI Designer, add a Collection component
2. Set the **Collection Source** to point to your array (e.g., `application.client.codebtors`)
3. The collection will iterate through each item in the array

![Collection configuration for forms](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic2.png)

**3. Add Collection Prototype with Forms**

1. Add a **Collection Prototype** as a child of your Collection component
2. Configure prototype identifier. This is the key that will be used to identify the prototype.
3. **Drag Form components directly into the Collection Prototype**
4. Configure form fields with relative keys (e.g., `name`, `email`)

![Collection configuration for forms](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic3.png)

> [!NOTE]
>
> This is the key innovation: you can now place Form components directly inside Collection Prototypes, and they will automatically repeat for each collection item.

**4. Configure form fields**

Configure each form field using relative paths to the collection item data:

* Use keys like `name`, `email`, `type` (not full paths)
* The system automatically constructs the full path at runtime
* Example: `name` becomes `application.client.codebtors[0].name` for the first item

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic4.png)

### Saving scenarios

Forms in Collections supports two distinct saving approaches, each suited for different use cases:

> [tab] Individual Item Save (Scenario 1)
>
> **When to use**: Save one collection item at a time, with validation only for that specific item.
>
> **Configuration**:
>
> * Place your Save button **inside the Collection Prototype**
> * Configure a **Collection Item Save Key** on the event handler
> * The edited object will be saved to this key
> * Add a business rule to update the original array and send it back to the frontend
>
> ![Collection configuration for forms](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic5.png)
>
> **Behavior**:
>
> * Validates only the forms for the specific collection index where the action is triggered
>
> * Saves individual items as they are edited
>
> * Requires business rule to sync changes back to the main array
>
> > [!WARNING]
> >
> > You must configure a business rule to update the original array after individual saves to maintain data consistency.
>
> #### Business rule Examples
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fic6.png)
>
> > [accordion] Business rule  - Add new codebtor in the array
> >
> > ```javascript theme={"dark"}
> > // This business rule is adapted to the runtime requirements of the FlowX.AI engine.
> >
> > // ARGS
> > var application = null;
> > var client = null;
> >
> > if (input["application"] != null) {
> >     application = input["application"];
> > }
> > if (application != null && application["client"] != null) {
> >     client = application["client"];
> > }
> >
> > // Business Rule Code
> > if (client != null) {
> >     if (!Array.isArray(client["codebtors"])) {
> >         client["codebtors"] = [];
> >     }
> >     var newCodebtor = {"name": ""};
> >     newCodebtor["id"] = client["codebtors"].length + 1;
> >     client["codebtors"].push(newCodebtor);
> > }
> >
> > // OUTPUT
> > if (client != null) {
> >     output["application"] = { "client": client };
> > } else {
> >     output["error"] = {
> >         "type": "MISSING_FIELD",
> >         "message": "Client is missing"
> >     };
> > }
> >
> > ```
>
> > [accordion] Send data to the frontend
> >
> > ```javascript theme={"dark"}
> > { "application": ${application}}
> > ```

> [tab] Bulk Save (Scenario 2)
>
> **When to use**: Save all collection items at once with validation for all forms.
>
> **Configuration**:
>
> * Place your Save button **outside the Collection** (not in the prototype)
> * Configure a **Custom Key** on the event handler to save the entire array
> * All forms in the collection will be validated simultaneously
>
> **Behavior**:
>
> * Validates all forms across all collection prototype items
> * Saves the entire modified array in one operation
> * No additional business rules needed for array synchronization
>
> ```javascript theme={"dark"}
> // Bulk save configuration  
> {
>   "customKey": "updatedClients",
>   "formsToSubmit": ["clientForm"]
> }
> ```
>
> > [!TIP]
> >
> > Bulk save is simpler to implement as it doesn't require additional business rules to maintain array consistency.

Demo:

<video />

### Key formation and validation

Understanding how keys work in Forms in Collections is crucial for proper configuration:

#### Runtime key construction

Keys are automatically constructed using the full object path:

```javascript Original Key theme={"dark"}
// In your form field configuration
"name"
```

```javascript Runtime Key   theme={"dark"}
// What the system generates at runtime
"application.clients[0].name"  // For first item
"application.clients[1].name"  // For second item
```

#### Validation behavior

> [accordion] Individual Save Validation
>
> When using **Scenario 1** (action inside prototype):
>
> * Only validates forms for the specific collection index
> * Example: If action is triggered on item 2, only `clients[1]` forms are validated
> * Other items in the collection are ignored during validation

> [accordion] Bulk Save Validation
>
> When using **Scenario 2** (action outside collection):
>
> * Validates all forms across all collection items
> * All items must pass validation for the save to succeed
> * Comprehensive validation ensures data integrity across the entire collection

### Configuration examples

#### Individual save example

```javascript Event handler configuration theme={"dark"}
{
  "event": "CLICK",
  "actionType": "SAVE_DATA", 
  "nodeActionName": "saveClient",
  "collectionItemSaveKey": "currentClient",
  "formsToSubmit": ["clientDetailsForm"],
  "excludeKeys": ["temporaryData"]
}
```

#### Bulk save example

```javascript Event handler configuration theme={"dark"}
{
  "event": "CLICK",
  "actionType": "SAVE_DATA",
  "nodeActionName": "saveAllClients", 
  "customKeys": ["allClients"],
  "formsToSubmit": ["clientDetailsForm"]
}
```

### Troubleshooting

> [accordion] Forms not validating correctly
>
> **Symptoms**: Validation errors not showing or validation not working as expected
>
> **Solutions**:
>
> * Ensure `formsToSubmit` includes the correct form identifiers
> * Check that form fields have proper relative keys configured
> * Verify the event handler is placed in the correct location (inside or outside prototype)
> * For individual saves, confirm the Collection Item Save Key is configured

> [accordion] Data not saving properly
>
> **Symptoms**: Form data not persisting or appearing in wrong location
>
> **Solutions**:
>
> * For individual saves: Ensure business rule updates the original array
> * For bulk saves: Verify Custom Key configuration captures the full array
> * Check key formation by examining the process data structure
> * Confirm the Collection Source points to the correct array

> [accordion] Can't hide form elements based on external variables
>
> **Limitation**: Form elements within collections cannot be hidden based on variables outside the collection
>
> **Workaround**: Use keys from within the collection item object for conditional display. The mechanics of collections require using data from within the current collection item scope.

### Frequently asked questions

> [accordion] Can I hide form elements based on variables outside the collection?
>
> No, the mechanics of collections require using keys from within the collection item object. You cannot use variables outside the collection scope to control form element visibility within the collection.

> [accordion] What happens to null values in form fields?
>
> You can configure **Exclude Keys** in the event handler to handle null values. This prevents null or empty values from being included in the saved data.

> [accordion] How are keys formed at runtime?
>
> Keys are constructed with the full object path including array indices. For example, a field with key `name` becomes `application.clients[0].name` for the first collection item.

> [accordion] Do I need business rules for both saving scenarios?
>
> * **Individual Save (Scenario 1)**: Yes, you need a business rule to update the original array
> * **Bulk Save (Scenario 2)**: No, the entire array is saved directly without additional business rules

### Best practices

> [card] Choose the Right Scenario
>
> Use Individual Save for real-time editing where users work on one item at a time. Use Bulk Save for form-completion workflows where all data is submitted together.

> [card] Key Management
>
> Use descriptive, relative keys in your form fields. Let the system handle path construction automatically for better maintainability.

> [card] Validation Strategy
>
> Plan your validation approach early. Individual saves validate per item, bulk saves validate everything - choose based on your user experience goals.

> [card] Data Structure
>
> Design your array structure to include all necessary fields from the start. Adding fields later may require updates to existing prototypes.

This feature significantly simplifies building dynamic forms with repeatable sections, eliminating the need for custom development while providing flexible validation and saving options.

***

## Common patterns

### Display a list of plain values (string or number array)

A Collection binds each child component to a **key** on the current item, so the source must be an **array of objects**. You can't bind a raw array of primitives like `["Red", "Green", "Blue"]` directly, because there is no key to point a component at.

To display a plain array, wrap each value in an object first, then bind a component to that key.

**1. Transform the array into objects**

Add a business rule that maps each primitive into an object with a single key (for example, `value`):

```javascript theme={"dark"}
var colors = input.colors || ["Red", "Green", "Blue"];

var items = colors.map(function (c) {
    return { "value": c };
});

output.put("displayed", { "colors": items });
```

This produces `[{ "value": "Red" }, { "value": "Green" }, { "value": "Blue" }]`.

**2. Point the Collection at the transformed array**

Set the Collection **Source** to the transformed key (for example, `displayed.colors`).

**3. Bind a component to the wrapper key**

Inside the Collection Prototype, add a **Text** (or other) component and set its key to the **relative** key `value`. At runtime it resolves to `displayed.colors[0].value`, `displayed.colors[1].value`, and so on.

> [!TIP]
>
> You can name the wrapper key anything (`value`, `label`, `name`), just make sure the component's relative key matches it.

***

### Delete an item from a collection

Collections do not have a built-in delete mechanism. To remove an item, use a business rule triggered from within the collection prototype.

**1. Add a delete button inside the Collection Prototype**

Place a button inside your Collection Prototype. Add an event handler with:

* **Event:** `CLICK`
* **Action Type:** `ACTION`
* **Node Action Name:** your delete business rule
* **Collection Item Save Key:** a temporary key (e.g., `itemToDelete`) — this saves the clicked item's data so the business rule knows which item to remove

**2. Create the delete business rule**

Add a **manual, optional, repeatable** business rule on the User Task node.

**Delete by matching an attribute** (when items have no unique ID):

```javascript theme={"dark"}
var clients = input.application.clients || [];
var itemToDelete = input.itemToDelete;

if (itemToDelete != null) {
    for (var i = 0; i < clients.length; i++) {
        if (clients[i].name === itemToDelete.name 
            && clients[i].email === itemToDelete.email) {
            clients.splice(i, 1);
            break;
        }
    }
}

output.application = { "clients": clients };
```

**Delete by ID** (when items have a unique identifier):

```javascript theme={"dark"}
var clients = input.application.clients || [];
var itemToDelete = input.itemToDelete;

var updated = clients.filter(function(item) {
    return item.id !== itemToDelete.id;
});

output.application = { "clients": updated };
```

**3. Send the updated array back to the UI**

Add a **Send Data to User Interface** action to push the modified array back:

```json theme={"dark"}
{
  "application": ${application}
}
```

> [!WARNING]
>
> Always send the updated array back to the frontend after deletion. Without this step, the UI will still display the deleted item until the next page refresh.

***

### Add an item to a collection dynamically

To let users add new entries to a collection (e.g., an "Add" button), create a business rule that appends a new object to the source array.

```javascript theme={"dark"}
var clients = input.application.clients || [];

var newClient = {
    "id": clients.length + 1,
    "name": "",
    "email": ""
};

clients.push(newClient);

output.application = { "clients": clients };
```

Place the "Add" button **outside** the collection, and attach an event handler (type `ACTION`) pointing to this business rule. Then send the data back to the UI with a **Send Data to User Interface** action.

***

### Filter a collection using form controls

Collections do not have built-in filtering. To filter displayed items based on form selections, use the same pattern as [Table cross-component filtering](../table#filter-table-data-using-form-controls):

1. Keep the **original data** in one key (e.g., `application.clients`)
2. Store the **displayed data** in a separate key (e.g., `displayed.clients`)
3. Point the Collection's **Source** to the displayed key
4. On each filter dropdown's `CHANGE` event, trigger a business rule that filters the original data and writes the result to the displayed key

```javascript theme={"dark"}
var allClients = input.application.clients || [];
var selectedStatus = input.filter.status;

var filtered = allClients.filter(function(item) {
    if (selectedStatus && item.status !== selectedStatus) return false;
    return true;
});

output.displayed = { "clients": filtered };
```

> [!TIP]
>
> For simple client-side transformations (no server roundtrip needed), you can also use [Event Handlers](../../event-handlers) with an `onChange` expression instead of a business rule.

***

### Preview uploaded files

To show one File Preview per file uploaded with a Multiple File Upload component, bind a collection to the Documents plugin bulk reply. See [Preview files in a collection](../file-preview#preview-files-in-a-collection).

***

## Academy courses

> [card] [Collections and Prototypes course](https://academy.flowx.ai/explore/collections-and-prototypes)
>
> Hands-on course covering collection configuration, service tasks, and business rules with collections

> [card] [Handle Dynamic Data course](https://academy.flowx.ai/explore/handle-dynamic-data-flowxai)
>
> Learn to configure dynamic dropdowns and data-driven UI from process data


# Card
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card

A card in FlowX.AI is a graphical component designed for the purpose of grouping and aligning various elements. It offers added functionality by incorporating an accordion feature, allowing users to expand and collapse content as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/card_ex.gif)

The following properties that can be configured:

## Properties and settings

### Settings (applicable across all platforms)

These settings added in the **Generic** tab are available and they apply to all platforms including Web, iOS, and Android.

#### When used as root

When the Card is utilized as the root component, it offers the following settings:

* **Custom UI Payload**: A valid JSON describing the custom data transmitted to the frontend when the process reaches a specific user task.
* **Title**: The title displayed on the card.
* **Subtitle**: Additional descriptive text accompanying the card.
* **Has accordion**: Introduces a Bootstrap accordion, facilitating the organization of content within collapsible items. It ensures that only one collapsed item is displayed at a time.
* **Default collapse state**: When accordion is enabled, this property determines whether the card is initially collapsed or expanded when first loaded. Options:
  * **Expanded** (default): The card content is visible when the screen loads.
  * **Collapsed**: The card content is hidden when the screen loads, and users must click to expand it.

> [!NOTE]
>
> The accordion feature is not available for mobile configuration.

#### Mobile configuration (iOS & Android)

For mobile configuration (iOS and Android), you can also configure the following property (not available on Web configuration):

* **Screen title**: Set the screen title used in the navigation bar on mobile devices (available only when the card element is set as the root).

![Android Screen Title](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/screen_title_android%20%282%29.png)

Android Card Screen Title

### Card settings overrides

You may want to override the card title or subtitle set as **Generic** to be displayed differently on mobile devices. For example, on the web, titles might be shorter.

> [tab] Web
>
> Available properties overrides for web (overriding properties set in **Generic** settings tab):
>
> * Title
> * Subtitle
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/overrides_web.png)

> [tab] Android
>
> Available properties overrides for Android (overriding properties set in **Generic** settings tab):
>
> * Title
> * Subtitle
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/overrides_android.png)

> [tab] iOS
>
> Available properties overrides for iOS (overriding properties set in **Generic** settings tab):
>
> * Title
> * Subtitle

#### When not used as root

When the card is not the root, you can configure: **Title**, **Subtitle**, **Card Style**, **Has Accordion**, and **Default collapse state**.

Use cards in your designs to organize and present content, enhancing the overall user experience.

## Styling

> [tab] Web
>
> > [tab] Layout
> >
> > When designing for the web, consider the layout options available for the card. These options include:
> >
> > * **Direction**: Choose between **Horizontal** or **Vertical** alignment to define the flow of components. For example, select Horizontal for a left-to-right layout.
> > * **Justify (H)**: Specify how content is aligned along the main axis. For instance, select end to align items to the end of the card.
> > * **Align (V)**: Align components vertically within their card using options such as top, center, or bottom alignment.
> > * **Wrap**: Enable wrapping to automatically move items to the next line when they reach the end of the card. Useful for creating multi-line layouts.
> > * **Gap**: Define the space between components to control the distance between each item. Adjusting the gap enhances visual clarity and organization.
>
> > [tab] Sizing
> >
> > Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
> >
> > * **fill**: Fills the available space.
> > * **fixed**: Maintains a fixed width.
> > * **auto**: Adjusts the width automatically based on content.
> >
> > Fit H (height) offers two options:
> >
> > * **fixed**: Sets an exact height in pixels. Content that doesn't fit scrolls inside the card.
> > * **auto**: Adjusts the height automatically based on content.
> >
> > Fit H has no **fill** option, so a card can't stretch to the full height of the page. To make it taller, set Fit H to **fixed** and enter the height you need.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.
>
> However, for mobile applications, there's an additional layout style property specific to cards when used as the root component:
>
> * **Scrollable**:  This property allows you to define the desired behavior of the screen, specifying whether it should be scrollable or not. By default, this property is set to true, enabling scrolling functionality.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.
>
> However, for mobile applications, there's an additional layout style property specific to cards when used as the root component:
>
> * **Scrollable**:  This property allows you to define the desired behavior of the screen, specifying whether it should be scrollable or not. By default, this property is set to true, enabling scrolling functionality.

### Theme overrides

Customize the appearance by overriding style options coming from your default theme. Available overrides:

* Border width
* Border radius
* Border color
* Background color
* Shadow
* Title
* Title Color
* Subtitle
* Subtitle Color

> [card] [Layout Demos](https://tburleson-layouts-demos.firebaseapp.com/#/docs)

## Validating elements

To ensure the validation of all form elements and custom components within a card upon executing a Save Data action such as **Submit** or **Continue**, follow these steps:

1. When adding an event handler to a button inside a card, locate the dropdown menu labeled **Add forms to submit**.
2. From the dropdown menu, select the specific forms, individual form elements, or custom components you wish to validate.
3. If you select custom components, ensure they are properly configured to handle validation and data saving responsibilities.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2013.26.20.png)

***

### Custom component validation

Event handlers enable validation and data management for custom components alongside form elements. This provides flexibility if you want to design custom components for entire screens, such as custom forms not natively supported by the platform.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2013.37.15.png)

#### Key features

* **Validation API**: The renderer provides a public API for validating custom components before triggering an action.
* **Custom Component Responsibilities**:
  * Validate custom forms and return a boolean (`true` for valid, `false` for invalid).
  * Display validation errors in the UI for invalid data.
  * Populate a `saveData` property with the structured data to be submitted.
* **Configurator Responsibilities**:
  * Select custom components in the **Add forms to submit** dropdown when configuring an event handler.
  * Set the custom key to store the data submitted by the custom component.

By including custom components in the validation process, you can now validate and retrieve data from custom form sections, ensuring comprehensive and reliable form submission.


# Container
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/container

A container in FlowX.AI is a versatile building block that empowers you to group components and arrange them as needed, providing flexibility in UI design. It can also serve as the root component for your design.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_ex.gif)

The following properties can be configured in the container:

## Properties and settings

### Settings (applicable across all platforms)

These settings added in the **Generic** tab are available and they apply to all platforms including Web, iOS, and Android.

#### When used as root

When employed as the root component, the container offers the following settings:

* **Custom UI Payload**: A valid JSON describing the data sent to the frontend when the process reaches a specific user task.
* **Expressions (Hide condition)**: JavaScript expressions utilized to dynamically hide components based on conditions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_root_new.png)

#### When not used as root

When the container is not used as the root, you can configure only the **Hide Condition** property.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/container_not_root.png)

By leveraging containers, you gain the ability to structure your UI elements efficiently, enhancing the overall design and usability of your application.

### Container settings overrides

You may want to override settings configured in the **Generic** tab to be displayed differently on mobile devices.

* **Hide expressions**: Use Overrides in the Settings tab to hide a container on a specific platform.

> [!NOTE]
>
> For instance, you can set a container to appear on all platforms, or create an override to hide it on mobile but show it on web.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/override_hide.gif)

To achieve this:

1. Select a Container element in the UI Designer, then navigate to Settings -> your desired platform -> Overrides (+) -> Expressions -> Hide.
2. Add your JavaScript Hide condition.

## Styling

> [tab] Web
>
> > [tab] Layout
> >
> > When designing for the web, consider the layout options available for the container. These options include:
> >
> > * **Position**
> >   * **Static**: This style remains fixed and does not scroll along with the page content.
> >   * **Sticky**: When the sticky property is enabled, the container maintains its position even during scrolling.
> >     * **Sticky layout**: You have the option to specify minimum distances between the container and its parent element while scrolling. At runtime, sticky containers will keep their position on scroll relative to top/ bottom/ right/ left margin of the parent element.
> >
> > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Screenshot%202023-12-13%20at%2017.18.39.png)
> >
> > * **Direction**: Choose between **Horizontal** or **Vertical** alignment to define the flow of components. For example, select Horizontal for a left-to-right layout.
> > * **Justify (H)**: Specify how content is aligned along the main axis. For instance, select end to align items to the end of the container.
> > * **Align (V)**: Align components vertically within their container using options such as top, center, or bottom alignment.
> > * **Wrap**: Enable wrapping to automatically move items to the next line when they reach the end of the container. Useful for creating multi-line layouts.
> > * **Gap**: Define the space between components to control the distance between each item. Adjusting the gap enhances visual clarity and organization.
>
> > [tab] Sizing
> >
> > Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
> >
> > * **fill**: Fills the available space.
> > * **fixed**: Maintains a fixed width.
> > * **auto**: Adjusts the width automatically based on content.
> >
> > Fit H (height) offers two options:
> >
> > * **fixed**: Sets an exact height in pixels. Content that doesn't fit scrolls inside the container.
> > * **auto**: Adjusts the height automatically based on content.
> >
> > Fit H has no **fill** option, so a container can't stretch to the full height of the page. To make it taller, set Fit H to **fixed** and enter the height you need.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.
>
> However, there are exceptions, particularly with **Sticky layout**:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_mobile.png)
>
> In mobile configurations, the right and left properties for **Sticky layout** are ignored by the iOS renderer.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.
>
> However, there are exceptions, particularly with **Sticky layout**:
>
> ![Sticky layout on Android](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/sticky_mobile.png)
>
> In mobile configurations, the right and left properties for **Sticky layout** are ignored by the Android renderer.

### Theme overrides

Customize the appearance by overriding style options coming from your default theme. Available overrides:

* Border width
* Border radius
* Border color
* Background color
* Shadow

More layout demos available below:

> [card] [Layout Demos](https://tburleson-layouts-demos.firebaseapp.com/#/docs)

For more information about styling and layout configuration, check the following section:

> [card] [UI Designer](../../ui-designer#styles-tab)


# Custom component
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/custom

Custom components are developed in the web application and referenced here by component identifier. This will dictate where the component is displayed in the component hierarchy and what actions are available for the component.

> [!WARNING]
>
> Starting with **3.4.7** platform version, for User Tasks containing UI Elements, when the page is rendered, the Backend (BE) should, by default, send to the Frontend (FE) all available data as process variables with matching keys.
>
> If the User Task also includes a **custom component**, the BE should send, in addition to default keys, objects mentioned in the "Message" option of the root element.

To add a custom component in the template config tree, we need to know its unique identifier and the data it should receive from the process model.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom.png)

The properties that can be configured are as follows:

* **Identifier** - This enables the custom component to be displayed within the component hierarchy and determines the actions available for the component.
* **Input keys** - These are used to specify the pathway to the process data that components will utilize to receive their information.
* [**Event Handlers**](../../event-handlers) - actions defined here will be made available to the custom component

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom_settings.png#center)

## Prerequisites (before creation)

* **Angular Knowledge**: You should have a good understanding of Angular, as custom components are created and imported using Angular.

* **Angular CLI**: Ensure that you have Angular CLI installed.

* **Development Environment**: Set up a development environment for Angular development, including Node.js and npm (Node Package Manager).

* **Component Identifier**: You need a unique identifier for your custom component. This identifier is used for referencing the component within the application.

## Creating a custom component (Web)

To create a Custom Component in Angular, follow these steps:

1. Create a new Angular component using the Angular CLI or manually.
2. Implement the necessary HTML structure, TypeScript logic, and SCSS styling to define the appearance and behavior of your custom component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_comp.png)

## Importing the component

After creating the Custom Component, you need to import it into your application.

In your `app.module.ts` file (located at src → app → app.module.ts), add the following import statement:

```ts theme={"dark"}
`import { YourComponent } from '@app/components/yourComponent.component'`
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/import_cus.gif)

## Declaration in AppModule

In the same `app.module.ts` file, declare your Custom Component within the `declarations` array in the `@NgModule` decorator:

```ts theme={"dark"}
@NgModule({
  declarations: [
    // ...other components
    YourComponent
  ],
  // ...other module configurations
})

```

## Declaration in FlxProcessModule

To make your Custom Component available for use in processes created in FlowX.AI Designer, you need to declare it in `FlxProcessModule`.

In your process.module.ts file (located at src > app > modules > process > process.module.ts), add the following import statement:

```ts theme={"dark"}
import { YourComponent } from '@app/components/yourComponent.component';
```

Then, declare your Custom Component in the `FlxProcessModule.forRoot` function:

```ts theme={"dark"}
FlxProcessModule.forRoot({
  components: {
    // ...other components
    yourComponent: YourComponent
  },
  // ...other module configurations
})
```

## Using the custom component

Once your Custom Component is declared, you can use it for configuration within your application.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_component.gif)

## Data input and actions

The Custom Component accepts input data from processes and can also include actions extracted from a process. These inputs and actions allow you to configure and interact with the component dynamically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_input_data.png)

## Extracting data from processes

There are multiple ways to extract data from processes to use within your Custom Component. You can utilize the data provided by the process or map actions from the BPMN process to Angular actions within your component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_loader_input.png)

> [!WARNING]
>
> Make sure that the Angular actions that you declare match the names of the process actions.

## Styling with CSS

To apply CSS classes to UI elements within your Custom Component, you first need to identify the UI element identifiers within your component's HTML structure. Once identified, you can apply defined CSS classes to style these elements as desired.

Example:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/Screenshot%202023-10-10%20at%2012.29.51.png)

## Custom component example

Below you can see an example of a basic custom loader component built with Angular:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/2023-10-10%2012.01.58.gif)

## Additional considerations

* **Naming Conventions**: Be consistent with naming conventions for components, identifiers, and actions. Ensure that Angular actions match the names of process actions as mentioned in the documentation.

* **Component Hierarchy**: Understand how the component fits into the overall component hierarchy of your application. This will help determine where the component is displayed and what actions are available for it.

* **Documentation and Testing**: Document your custom component thoroughly for future reference. Additionally, testing is crucial to ensure that the component behaves as expected in various scenarios.

* **Security**: If your custom component interacts with sensitive data or performs critical actions, consider security measures to protect the application from potential vulnerabilities.

* **Integration with FlowX.AI Designer**: Ensure that your custom component integrates with FlowX.AI Designer, as it is part of the application's process modeling capabilities.

## Creating a custom component (iOS)

Enhance your skills with our academy course! Learn how to develop and integrate a custom iOS component with FlowX.AI:

> [card] [iOS Custom Component](https://academy.flowx.ai/module/ios-custom-component)


# Global Header and Footer
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer

Add a global header and footer to a UI Flow so the same top and bottom areas display consistently across every page.

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

The **Global Header** and **Global Footer** are UI Flow components that display consistently around every page of the flow — a single header at the top and a single footer at the bottom, instead of repeating the same elements on each page.

They are added from a dedicated **global components** section, available only for **UI Flow** resources (not process user tasks), and only on the **Web** device view. Each UI Flow can have at most **one** header and **one** footer.

## Positioning

Both components support two positions:

* **Fixed** — the area stays pinned as the page content scrolls. This is the **default for the header**.
* **Static** — the area scrolls with the page content. This is the **default for the footer**.

Header and footer always span the full width of the flow; there is no width setting.

## Child components

A header or footer can hold the same components as a container — for example **Container**, **Form**, **Button**, **Link**, **Text**, **Image**, **Custom** components, **File Upload**, and **File Download** — so you can build navigation bars, action bars, or persistent menus.

The following components **cannot** be placed inside a header or footer:

* **Collection**
* **Table**
* **Task Management**
* **Chat**

This restriction is enforced on paste as well — pasting a container that contains any of these is rejected.

> [!NOTE]
>
> Navigation areas (pages, zones, tabs, steppers, modals) are not available as children — a header or footer holds content components, not layout structure.

## Actions

Components inside a header or footer support the usual event handlers, with one exception: the **Dismiss** action is not available, because a global area is not tied to a single page or modal to dismiss. Forms placed inside a header or footer submit normally.

## Styling

The style panel for a header or footer exposes:

* **Layout** — position (Static or Fixed) and the flex or grid arrangement of children.
* **Sizing** — height (with optional overflow scrolling).
* **Spacing** — padding and margin.

> [!NOTE]
>
> A fixed header and footer are accounted for in page height automatically, so scrollable content and the chat area leave room for them.

## Related resources

> [card] [Container](./container)
>
> The container component that headers and footers build on

> [card] [Root components](./root-components)
>
> How components are structured in the UI Designer


# Root Components in UI Design
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/root-components

Root components serve as the foundation for structuring user interfaces, providing the framework for arranging and configuring different types of components.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/root_components_new.gif)

Root components are the top-level building blocks of a FlowX.AI user interface: Containers, Cards, Custom components, and global elements such as headers and footers. Root components play a crucial role in defining the layout and hierarchy of elements within an application. Here's an overview of key root components and their functionalities:

### Container

The Container component is a versatile element used to group and configure the layout for multiple components of any type. It provides a flexible structure for organizing content within a UI.

Learn more about [Container components](./container).

### Card

The Card component functions similarly to a Container component but also offers the capability to function as an accordion, providing additional flexibility in UI design.

Discover more about [Card components](./card).

### Custom

Custom components are Web components developed within the container application and dynamically passed to the SDK at runtime. These components are identified by their unique names and enable developers to extend the functionality of the UI.

Explore [Custom components](./custom) for advanced customization options.

### Global Header and Footer

In UI Flows, a **Global Header** and **Global Footer** display consistently across every page of the flow. See [Global Header and Footer](./global-header-footer) (SaaS · 5.10).

A card or a container can hold a hierarchical component structure as this example:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/root_comp_str.png)

Available children for **Card** and **Container** are:

1. [**Form**](../form-elements/) - Used to group and align form field elements (inputs, radios, checkboxes, etc.).

> [!NOTE]
>
> For more information about the form elements, please refer to the [**Form elements**](../form-elements/) section.

2. [**Image**](../image) - Allows you to configure an image in the document.
3. **Text** - A simple text can be configured via this component; basic configuration is available.
4. **Link** - Used to configure a hyperlink that opens in a new tab.
5. [**Button**](../buttons) - Multiple options are available for configuration, with the most important part being the possibility to add actions.
6. [**File Upload**](../buttons) - A specific type of button that allows you to select a file.
7. [**Custom**](./custom) - Custom components.
8. [**Indicators**](../indicators) - Message UI elements to display different types of messages.

### Analytics Screen Name

Root components (Cards and Containers) can emit an analytics event when they are displayed, so you can track screen views in an analytics tool such as Google Analytics.

To configure it, select the root component and open the **Advanced** section of the config panel:

* **Analytics Screen Name** - turn on the toggle and set the screen name. When the component appears, the renderer emits an event carrying this name, which your analytics tool can pick up.
* **Analytics custom payload** - optional. When the toggle is on, add an expression to include extra data in the emitted event.

> [!NOTE]
>
> UI Flows expose the same capability as an **Add analytics** step (Analytics name + Custom payload) when you build a flow. See [UI Flows](../../../ui-flows).

Learn more:

> [card] [Card](./card)

> [card] [Container](./container)

> [card] [Custom](./custom)


# UI Designer
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-designer

The FlowX.AI UI Designer is a comprehensive, multi-platform interface creation tool that enables visual design of user experiences across web, iOS, and Android platforms without extensive coding.

## Purpose

The **FlowX.AI UI Designer** is an intuitive interface creation tool for building user interfaces within FlowX.AI processes. It provides a visual editor where you can add, arrange, and configure UI components to create rich web interfaces for your business processes.

### Key capabilities

> [card] Multi-Platform Support
>
> Create interfaces with platform-specific configuration and styling across Web, iOS, and Android

> [card] Visual Interface Design
>
> Use a drag-and-drop environment to design diverse UI templates with various elements and components

> [card] Real-Time Preview
>
> Preview your designs across different platforms and themes with live feedback

> [card] Component Library
>
> Access ready-to-use UI components including form elements, containers, and specialized components

> [!NOTE]
>
> The UI Designer integrates with BPMN process flows, making it available for [**User Task**](../node/user-task-node) nodes and **Navigation Areas** to create contextual user interfaces.

## UI Designer interface

The UI Designer provides a comprehensive interface for creating and configuring user interfaces within your FlowX.AI processes.

### Platform selection

The UI Designer supports multi-platform design with dedicated configuration tabs:

> [tab] Web Platform
>
> **Full Feature Support**: Complete UI Designer functionality with all component types and navigation features
>
> * All UI component types supported
> * Full navigation area capabilities
> * Zones with headers and footers
> * Single page and wizard navigation types

> [tab] iOS Platform
>
> **Mobile-Optimized Interface**: Platform-specific properties and limitations
>
> * Basic navigation areas (no zones with headers/footers)
> * Screen title configuration for navigation bar
> * Scrollable property for card components
> * Platform-specific property overrides

> [tab] Android Platform
>
> **Mobile-Optimized Interface**: Android-specific adaptations
>
> * Basic navigation areas (no zones with headers/footers)
> * Screen title configuration for navigation bar
> * Platform-specific property overrides
> * Material design considerations

### Configuration panels

The UI Designer interface consists of configuration sections for comprehensive component setup:

> [accordion] Settings Tab
>
> **Generic Configuration**: Properties available cross-platform (Web, Android and iOS)
>
> **Platform-Specific Settings**: Override generic properties for specific platforms
>
> * Property overrides (Title, Subtitle, Helper text)
> * Expression overrides (Hide conditions)
> * Import/export functionality between platforms

> [accordion] Styles Tab
>
> **Theme Integration**: Components inherit styling from the active theme by default
>
> **Theme Overrides**: Customize component appearance beyond theme settings
>
> * Platform-specific styling
> * Conditional styling (for Text, Link, Container elements)
> * Import/export styles between platforms

> [accordion] Preview
>
> **Multi-Platform Preview**: Switch between platforms to preview designs
>
> * Real-time platform switching
>
> * Theme selection for preview
>
> * Visual estimation for mobile platforms
>
> > [!NOTE]
> >
> > iOS and Android previews are estimates to help visualize mobile views.

### UI components available

The FlowX.AI platform offers a variety of ready-to-use UI components. The groupings below follow the navigation order:

> [accordion] Root components
>
> **Layout foundation elements**, the framework for arranging everything else:
>
> * **[Root components overview](./ui-component-types/root-components/root-components)**: How root components structure a screen
> * **[Container](./ui-component-types/root-components/container)**: Flexible grouping and layout control
> * **[Card](./ui-component-types/root-components/card)**: Content cards with built-in styling
> * **[Custom](./ui-component-types/root-components/custom)**: Advanced custom component integration
> * **[Global header and footer](./ui-component-types/root-components/global-header-footer)**: Top and bottom areas shared across every page of a UI Flow

> [accordion] Form elements
>
> **Data collection components**, for capturing user input:
>
> * **[Input](./ui-component-types/form-elements/input-form-field)**: Text input fields
> * **[Textarea](./ui-component-types/form-elements/text-area)**: Multi-line text input
> * **[Select](./ui-component-types/form-elements/select-form-field)**: Dropdown menus
> * **[Multi select](./ui-component-types/form-elements/multi-select)**: Choose several options from one list
> * **[Checkbox](./ui-component-types/form-elements/checkbox-form-field)**: Multiple selection options
> * **[Radio](./ui-component-types/form-elements/radio-form-field)**: Single selection from options
> * **[Switch](./ui-component-types/form-elements/switch-form-field)**: Toggle controls
> * **[Datepicker](./ui-component-types/form-elements/datepicker-form-field)**: Date and time selection
> * **[Slider](./ui-component-types/form-elements/slider)**: Range and numeric input
> * **[Segmented button](./ui-component-types/form-elements/segmented-button)**: Multi-option selection

> [accordion] Action, file and display elements
>
> **Interactive and display components**:
>
> * **[Buttons](./ui-component-types/buttons)**: Action triggers and navigation, including the [File Upload Button](./ui-component-types/buttons#file-upload-button) for uploading one file at a time
> * **[Multiple file upload](./ui-component-types/multiple-file-upload)**: Drag-and-drop area for uploading several files in one action
> * **[File preview](./ui-component-types/file-preview)**: Preview file contents without fully opening the file
> * **[File download](./ui-component-types/file-download)**: Let end users download a file from a rendered app
> * **[Table](./ui-component-types/table)**: Structured data presentation
> * **[Image](./ui-component-types/image)**: Media display
> * **[Typography](./ui-component-types/typography)**: Text and links
> * **[Indicators](./ui-component-types/indicators)**: Status and message display

> [accordion] Chat and content elements
>
> **Conversational and formatted content**:
>
> * **[Chat](./ui-component-types/chat)**: Interactive AI agent conversations, with sub-components for the header, history, messages, input, suggested prompts and file attachments
> * **[Markdown](./ui-component-types/markdown)**: Renders Markdown-formatted content on a screen
> * **[Separator](./ui-component-types/separator)**: Visual divider for grouping content
> * **[Progress bar](./ui-component-types/progress-bar)**: Visualizes progress or completion state
> * **[Tooltip](./ui-component-types/tooltip)**: Shows extra context on hover or focus

> [accordion] Collections
>
> **Dynamic content components**, for repeated content and dynamic data:
>
> * **[Collection](./ui-component-types/collection/collection)**: Dynamic lists of data
> * **[Collection prototype](./ui-component-types/collection/collection-prototype)**: Templates for collection items

### Component configuration

After adding a UI component, the right-side menu displays configuration options:

* **Settings Tab**: Configure component properties and behavior
* **Styles Tab**: Customize appearance and apply theme overrides
* **Platform Overrides**: Adapt components for specific platforms

### Navigation areas integration

Navigation areas can be configured through the UI Designer, providing:

* Hierarchical navigation structure
* Platform-specific navigation capabilities
* Copy/paste functionality for consistency across platforms

## Using the UI designer

To access the UI Designer and start building interfaces:

**1. Open FlowX.AI Designer**

Navigate to **FlowX.AI Designer** and select **Definitions** from the **Processes** tab.

**2. Select Process**

Choose a **process** from the process definitions list.

**3. Edit Process**

Click the **Edit process** button to enter editing mode.

**4. Access UI Designer**

Select a **User Task node** or a **Navigation Area** then click the **brush icon** to open the **UI Designer**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_ui_designer.gif)

> [!NOTE]
>
> The UI Designer is available for [**User Task**](../node/user-task-node) nodes and **Navigation Areas** elements, providing contextual interface design capabilities.

> [!TIP]
>
> **Productivity Features**:
>
> * **Undo/Redo**: Available within the UI Designer for actions such as dragging, dropping, or deleting elements
> * **Keyboard Shortcuts**: Use keyboard commands for quick access to undo/redo functionality
> * **Drag and Drop**: Support for dragging and dropping elements in the preview section
> * **Settings Panel**: Right-side menu displays configuration options after adding components

## Comprehensive design guides

Master the UI Designer with our detailed guides covering every aspect of interface creation:

> [card] [Screen Configuration Guide](./screen-configuration-guide)
>
> **How to Approach Screen Configuration**
>
> Learn the systematic methodology for creating effective user interfaces:
>
> * User journey definition and analysis
> * Navigation pattern selection
> * Information architecture planning
> * Layout strategy implementation
> * Platform-specific adaptations
> * Validation and testing approaches

> [card] [Best Practices](./best-practices)
>
> **UI Designer Best Practices**
>
> Essential guidelines for creating accessible, performant interfaces:
>
> * User-centered design principles
> * Information architecture standards
> * Component usage excellence
> * [Accessibility compliance (WCAG 2.1)](../../platform-deep-dive/accessibility)
> * Testing and quality assurance
> * Maintenance strategies

> [card] [Platform Considerations](./platform-considerations)
>
> **Platform-Specific Guidelines**
>
> Comprehensive platform optimization and limitation reference:
>
> * Web, iOS, and Android design patterns
> * Performance optimization strategies
> * Platform-specific constraints and workarounds
> * Security and privacy considerations
> * Cross-platform testing protocols

> [card] [Latest Features](#latest-features)
>
> **Advanced UI Designer Capabilities**
>
> Discover the features in FlowX.AI UI Designer:
>
> * Conditional styling for dynamic interfaces
> * Platform-specific configuration and overrides
> * Advanced form components with validation
> * Navigation areas integration
> * Flexible layout configuration and reusable templates

## Latest features

FlowX.AI UI Designer includes several advanced features for creating rich, interactive user interfaces:

> [accordion] Conditional Styling
>
> **Dynamic Styling Based on Data**
>
> * Apply styles conditionally based on process data
> * Available for Text, Link, and Container elements
> * Real-time evaluation with priority handling
> * Platform-specific styling overrides
>
> **Configuration**:
>
> * Navigate to Styles tab → Conditional Styling section
>
> * Add expressions and effects using JS Editor
>
> * Define conditions and style overrides
>
> > [!TIP]
> >
> > Use conditional styling to highlight data patterns, outliers, or trends directly within the interface, reducing the need for multiple prototypes.

> [accordion] Platform-Specific Configuration
>
> **Multi-Platform Design Support**
>
> * Universal configuration and styling across Web, iOS, and Android
> * Platform-specific property overrides
> * Generic settings with targeted customizations
> * Import/export overrides between platforms
>
> **Key Features**:
>
> * Settings tab with platform selection
> * Override system for properties and expressions
> * Preview across different platforms
> * Consistent yet platform-optimized experiences

> [accordion] Advanced Form Components
>
> **Rich Form Element Support**
>
> * Input fields with validation (required, custom)
> * Select components with CHANGE event handling
> * Checkboxes and radio buttons with dynamic behavior
> * File upload components with platform considerations
> * Date pickers and sliders for enhanced input
>
> **Validation Features**:
>
> * Required field validation
> * Custom validation rules
> * Conditional validation based on other fields
> * Real-time validation feedback

> [accordion] Navigation Areas Integration
>
> **Enhanced Navigation Design**
>
> * Navigation areas accessible within UI Designer
> * Platform-specific navigation capabilities
> * Web: Full zones with headers/footers, wizard navigation
> * Mobile: Basic navigation areas with screen titles
> * Copy/paste navigation areas for consistency

> [accordion] Layout Configuration
>
> **Flexible Layout System**
>
> * Linear layout with direction, justify, align controls
> * Grid layout support for complex designs
> * Gap settings for proper spacing
> * Wrap functionality for responsive behavior
> * Available for containers and grouping components

> [accordion] Reusable UI Templates
>
> **Component Reusability**
>
> * Create modular UI components for reuse across processes
> * Template hierarchy with data model support
> * Input/output parameter mapping
> * Visual components and layout focus
> * Cannot include complex business logic

## UI components

FlowX offers a wide range of [UI components](./ui-designer#ui-components) that can be customized using the UI Designer. For example, when configuring a [card](./ui-component-types/root-components/card) element (which is a root component), the following properties can be customized:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_ui_designer.gif)

### Settings tab

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/uI_designer_panel1.png)

#### Generic tab

This is where you configure the logic and assign process keys, event handlers, and other component settings that are common across all platforms (Web, iOS, Android).

#### Platform-specific settings

For example, on Android, you might want to change the Card title to a shorter one.

To override a general property like a title, follow these steps:

**1. Go to UI Designer**

Access the UI Designer and select a UI Element, such as a **Card**.

**2. Access platform-specific settings**

From the UI Designer navigation panel, select the **Settings** tab, then select the **desired platform**

**3. Perform the override**

Click the "+" button (next to "Overrides") and select **Properties -> Title**, then input your desired value.

> [!TIP]
>
> Settings overrides can always be imported/pushed from one platform to another:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

**4. Preview your changes**

Preview your changes in the UI Designer by navigating from one platform to another or by comparing them.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/props_ui_designer_override.gif)

> [!NOTE]
>
> Keep in mind that the preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view.

#### Hide and disabled conditions

Components can be hidden or turned read-only at runtime based on a JavaScript condition. Both live in the **Expressions** section of a component's **Settings** panel:

| Field | Effect when the condition is true |
| - | - |
| **Hide condition** | The component is not rendered |
| **Disabled condition** | The component is rendered but cannot be edited |

**Step 1**

Select a UI component in the **UI Designer**, then open **Settings** -> **Expressions**.

**Step 2**

Add your JavaScript condition in **Hide condition** or **Disabled condition**.

Availability depends on the component. Most form fields support both, along with Form, Button, the file upload and download components, and the chat input. A hide condition is available on a wider set, including containers, cards, tables, text and images.

**Setting a condition for one platform only**

To hide or disable an element on a specific platform rather than everywhere, add the same expression as a platform override: **Settings** -> your desired platform -> **Overrides (+)** -> **Expressions**. A component whose expression is overridden on some platforms shows an info marker naming them.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/hide_condition.gif)

## Permission-based expressions

Control UI element visibility and interaction based on user roles and process data.

> [card] [Permission-based expressions](../process/permission-based-expressions)
>
> Complete guide to configuring role-based UI permissions, cross-swimlane references, and collaborative workflows

### Quick configuration

**1. Enable multiple executors**

In process settings, enable **Allow multiple executors** for your swimlane.

**2. Select component**

In **UI Designer**, select the component to configure.

**3. Add condition**

Expand **Permissions** section and click **+** to add hide or disable conditions.

**4. Configure parameters**

Set **Type** (USERNAME/ROLE), **Operator** (IN/NOT\_IN), **Value Type**, and **Value**.

> [!TIP]
>
> Use `CONFIGURATION_SWIMLANE_ROLE` for swimlane roles and `PROCESS_DATA` for dynamic values. `SWIMLANE_OWNER` requires no value.

### Styles tab

The Styles tab functions independently for three platforms: Web, iOS, and Android. Here, you can customize styles for each UI component on each platform.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_designer_panel2.png)

If you want to customize the appearance of a component to differ from the theme settings, you must apply a **Theme Override**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styless.gif)

> [!NOTE]
>
> Theme overrides can be imported from one platform to another.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styles.png)

> [card] [Theme Management](../../flowx-designer/design-assets/themes)

#### Copy/paste styles

Contextual menu functionality enables efficient style management:

* **Copy Style**: Copy styling properties between compatible components
* **Paste Style**: Apply copied styles to selected components
* **Copy to/from Platform**: Share styles across Web, iOS, and Android platforms
* **Multiple selection**: Apply styles to multiple components simultaneously

Compatible component groups for style copying:

* **Input-like**: Input, Select, Datepicker, Textarea, Multiselect
* **Selection**: Radio, Checkbox
* **Container**: Container, Form, Card, Collection, Collection Prototype
* **Action**: Button, File Upload

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/copy_styles.png)

#### Copy/paste platform actions

### Preview

When you are editing a process in **UI Designer** you have the possibility of having the preview of multiple themes:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/preview_theme_ui_designer.gif)

> [!NOTE]
>
> Overrides are completely independent of the theme, regardless of which theme you choose in the preview mode.

### Layout

There are two main types of layouts for organizing child elements: **Linear** and **Grid**.

* **Linear Layout**: Arranges child elements in a single line, either horizontally or vertically. Ideal for simple, sequential content flow.
* **Grid Layout**: Organizes elements into a structured grid with multiple columns and rows, useful for more complex, multi-dimensional designs.
* **Platform-Specific Layouts**: You can customize layout settings per platform (e.g., Grid on web, Linear on mobile) to ensure optimal responsiveness.

> [!NOTE]
>
> Both layouts offer options to customize direction, alignment, spacing, and wrap behavior for flexibility in design.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/set_linear.png)

> [card] [Layout](layout-configuration)

### Sizing

By setting desired values for these props, you can ensure that all UI elements on the interface are the desired size and perfectly fit with each other.

When adjusting the Fit W and Fit H settings, you can control the size and shape of the elements as they appear on your screen:

* Fit W: fill, fixed or auto
* Fit H: fixed or auto. The Chat component in **Fill** display type offers fixed or fill instead.

![UI element sizing options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_sizing.gif)

### Spacing

Margin and padding are CSS properties used to create space between elements in a web page:

* **margin** - the space outside an element
* **padding** - the space inside an element

![UI element spacing options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_spacing.gif)

> [card] [Margin](https://www.w3schools.com/css/css_margin.asp)

> [card] [Padding](https://www.w3schools.com/css/css_padding.asp)

### Advanced

* **Advanced** - for advanced customization, you can add CSS classes to pre-defined components, this option is available under the **Advanced** section
* **Data Test ID** - add custom test identifiers for automated testing and element interaction

By utilizing these styling options in FlowX.AI, you can create unique and visually appealing interfaces that meet your design requirements.

#### Data Test ID

The Advanced section includes a **Data Test ID** field, allowing you to assign custom identifiers to UI components. This feature enhances automated testing by providing meaningful, easily identifiable selectors for UI elements.

Key benefits:

* Replace auto-generated test IDs with custom, readable identifiers
* Simplify element targeting in test scripts

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-03-12%20at%2015.08.03.png)

## Tree view

The Tree View panel displays the component hierarchy, allowing you to navigate through the different levels of the interface.

Clicking on a specific component in the tree will highlight the selection in the editor, helping you locate and modify it.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_tree1.gif)

### Navigator in the left panel

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![Process UI Designer left panel on the Navigation tab, with a navigation root expanded to its user task and a Not Allocated group listing unassigned user tasks, above the selected user task's components section](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ui-designer-navigation-tab.png)

In the process UI Designer, the component tree is replaced by a two-part navigator on the **Navigation** tab of the left panel, the same layout [UI Flows](../ui-flows#adding-global-components) use. The UI Designer opens on this tab. The navigation area selector that sat next to the platform selector in the UI Designer header is removed: you pick the navigation area in the navigator instead.

#### Navigation section

The top section, **Navigation**, lists the navigation roots of the process for the selected platform. User tasks that are not assigned to any navigation area appear under a **Not Allocated** heading.

* Select a navigation root to open it. The open root expands to show its nested navigation areas, user tasks, and embedded subprocesses.
* On an embedded subprocess row, select **Open Subprocess** to open that subprocess.
* Use the view toggle (**Switch to dropdown view** / **Switch to list view**) to collapse the list into a searchable **Select a root** dropdown.
* When the process allows read-only mode, a filter button offers **Filter Nodes by** → **Visible in Read-Only Mode** or **View All**. With **Visible in Read-Only Mode** selected, entries that are not visible in read-only mode are dimmed and marked with a crossed-out eye icon.

#### Components section

The bottom section, **`<name>` Components**, is named after the current selection, such as a navigation area or user task, and shows its UI component tree. Use **Add UI Component** to add components and **Collapse All** to fold the tree. A user task holds a single root component, so the add button is turned off once the root exists.

When there is nothing to show, the section explains why:

| Message | When it appears |
| - | - |
| **No components yet** | The user task has no root component. Select **Add UI Component** to add a Container, Card, or Custom component. |
| **Multiple User Tasks** | The selected navigation area holds more than one user task. Select one of them to see its UI components. |
| **No User Tasks yet** | The selected navigation area has no user tasks. Select **Open Process Designer** to add and assign them. |
| Embedded subprocess notice | The selection is an embedded subprocess, whose UI components are managed in that subprocess. Select **Open Process** to go there. |

When a user task, UI Flow, or reusable UI template has no components yet, the canvas shows the same **UI Designer** empty state in all three, with a shortcut to add the first component or generate the layout with AI, depending on your permissions.

In the [reusable UI template](../reusable-resources/reusable-ui) designer, the navigator shows only the components section, labeled **UI Components**, where you add the template's single root component.

## Copy and paste UI components

Right-click a component and select **Copy** (**⌘C** on macOS, **Ctrl+C** elsewhere) to copy it, together with its child components. Then select the parent component you want to paste into, right-click it, and select **Paste** (**⌘V** / **Ctrl+V**). **Paste** is available only when a single parent is selected.

### Paste review and cross-context paste

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![Review paste modal with a struck-through component and its tooltip explaining why it cannot be pasted, the 2 components will be pasted summary, and the Paste 2 components button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ui-designer-review-paste.png)

You can paste copied UI components into a different context: from a user task into a UI Flow, from a UI Flow into a reusable UI template, and so on. Copy and paste share one clipboard format across user tasks, UI Flows, and reusable UI templates.

When everything in the clipboard fits the target, the paste happens straight away. When something does not fit, nothing is pasted yet and a **Review paste** modal opens instead:

* The modal shows the copied component hierarchy. Components that cannot be placed are struck through. Hover over one to see why, and whether its child components are dropped with it or reviewed on their own.
* Top-level components carry a checkbox, so you can leave out more components before pasting.
* The summary reads **N components will be pasted**. Select **Paste N components** to go ahead or **Cancel** to stop.
* When nothing in the selection can be pasted, the modal is titled **Paste blocked** and offers only **Close**.

Common reasons a component is dropped:

| Reason | Example |
| - | - |
| The component only exists in another context | A UI Flow-only component pasted into a user task |
| Navigation areas | Navigation areas are created in the navigation designer, not pasted |
| Another project's resource | A custom component, process renderer, or task management component that points to a resource in another project |
| Not available on the target device | A component missing from the palette of the target platform |
| Parent rules | A form inside another form, content that cannot sit inside a [header or footer](./ui-component-types/root-components/global-header-footer), or a component the parent does not accept |
| Chat in a flow-based UI | A chat pasted into a flow-based UI |
| Single root | The target holds a single root component |

Pasted components are also fitted to where they land:

* **Unique identifiers:** a pasted component keeps its **Component Identifier** when no other component on the target screen uses it. Otherwise it gets a new generated identifier for its type, such as `Button02`, that no other component on the screen holds.
* **Data model:** pasted components point to the data model of the target screen.
* **Unsupported properties:** properties the target cannot use are removed or adjusted in the pasted copy.

> [!NOTE]
>
> If the copied content was made with an earlier clipboard format, for example before a platform update, the paste is refused with **The copied content is no longer valid. Copy it again and retry.** A component also cannot be pasted into one of its own child components.

## UI component types

Different UI component types can be configured using UI Designer. The UI components are available and can be configured only using **user task nodes** or **navigation areas**.

> [!NOTE]
>
> Depending on the component type different properties are available for configuration.

Understanding these component types will help you to better utilize the UI Designer tool and create rich web interfaces.

> [accordion] Layout (root components)
>
> * [Container](./ui-component-types/root-components/container)
> * [Card](./ui-component-types/root-components/card)
> * [Custom](./ui-component-types/root-components/custom)

> [accordion] Collection
>
> * [Collection](./ui-component-types/collection/collection)
> * [Collection Prototype](./ui-component-types/collection/collection-prototype)

> [accordion] Basic
>
> * [Button](./ui-component-types/buttons)
> * [File Upload](./ui-component-types/buttons#file-upload-button)
> * [Image](./ui-component-types/image)

> [accordion] Typography
>
> * Text
> * Link

> [accordion] Forms
>
> Form elements are a crucial aspect of creating user interfaces as they serve as the means of collecting information from the users. These elements come in various types, including simple forms, [inputs](./ui-component-types/form-elements/input-form-field), [text areas](./ui-component-types/form-elements/text-area), drop-down menus ([select](./ui-component-types/form-elements/select-form-field)), [checkboxes](./ui-component-types/form-elements/checkbox-form-field), [radio buttons](./ui-component-types/form-elements/radio-form-field), toggle switches ([switch](./ui-component-types/form-elements/switch-form-field)), [segmented buttons](./ui-component-types/form-elements/segmented-button), [sliders](./ui-component-types/form-elements/slider) and [date pickers](./ui-component-types/form-elements/datepicker-form-field). Each of these form elements serves a unique purpose and offers different options for capturing user input.
>
> * Form
> * [Input](./ui-component-types/form-elements/input-form-field)
> * [Textarea](./ui-component-types/form-elements/text-area)
> * [Select](./ui-component-types/form-elements/select-form-field)
> * [Checkbox](./ui-component-types/form-elements/checkbox-form-field)
> * [Radio](./ui-component-types/form-elements/radio-form-field)
> * [Switch](./ui-component-types/form-elements/switch-form-field)
> * [Segmented button](./ui-component-types/form-elements/segmented-button)
> * [Slider](./ui-component-types/form-elements/slider)
> * [Datepicker](./ui-component-types/form-elements/datepicker-form-field)

> [accordion] Indicators
>
> * [Message](./ui-component-types/indicators)

Navigation areas

> [accordion] Navigation
>
> * Page
> * Stepper
> * Step
> * Modal
> * Container


# Fonts
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/design-assets/font-files

Fonts management allows you to upload and manage multiple font files, which can be later utilized when configuring UI templates using the UI Designer.

## Default fonts

FlowX ships with the **Open Sans** font family preinstalled, available in the UI Designer without any upload step. The following weight + style combinations are included:

| Weight | Normal | Italic |
| - | - | - |
| 300 (Light) | OpenSans-Light.ttf | OpenSans-LightItalic.ttf |
| 400 (Regular) | OpenSans-Regular.ttf | OpenSans-Italic.ttf |
| 600 (SemiBold) | OpenSans-SemiBold.ttf | OpenSans-SemiBoldItalic.ttf |
| 700 (Bold) | OpenSans-Bold.ttf | OpenSans-BoldItalic.ttf |
| 800 (ExtraBold) | OpenSans-ExtraBold.ttf | OpenSans-ExtraBoldItalic.ttf |

Any other typography needs to be uploaded as a custom font (see below).

***

## Managing fonts

The "Font Management" screen displays a table with uploaded fonts. The following details are available:

* **FontFamily**: The names of the uploaded font families.
* **File Name**: The name of the font file.
* **Weight**: The weight of the font, represented by a numeric value.
* **Style**: The style of the font, such as "italic" or "normal".
* **Actions**: This tab contains options for managing the uploaded fonts, such as deleting or downloading them.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/fonts4.5.0.png)

## Uploading fonts

### Uploading theme font files

To upload new theme font files, follow these steps:

1. Open **FlowX.AI Designer**.
2. Navigate to **Design Assets** and select **Fonts**.
3. Click **Upload font** (the **+** button) and choose a valid font file.

> [!NOTE]
>
> The accepted font format is TTF (TrueType Font file). **Only static TTF fonts are supported**. Variable fonts (dynamic fonts with adjustable width/weight in a single file) are not supported.

> [!WARNING]
>
> Each font weight and style combination requires a separate TTF file. For example, if you need "Open Sans" in regular (400), bold (700), and italic styles, you must upload separate TTF files for each variant.

4. Optionally, follow this naming convention for better compatibility: `[font family]-[font weight][font style]` (for example, `OpenSans-700Italic.ttf`).
5. Click **Upload**. You can upload multiple TTF font files.
6. For each uploaded font file, the system will automatically extract information such as font family, weight, and style from the file metadata.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/fonts-metadata.png)

## Exporting fonts

You can use the export feature to export a JSON file containing all the font files.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/export_fonts.png)

The exported JSON will look like this:

```json theme={"dark"}

{
  "fonts": [
    {
      "fontFamily": "Open Sans",
      "filename": "OpenSans-ExtraBoldItalic.ttf",
      "weight": 800,
      "style": "italic",
      "size": 135688,
      "storagePath": "https://d22tnnndi9lo60.cloudfront.net/devmain/flowx/fonts-folder/1690383294848_OpenSans-ExtraBoldItalic.ttf",
      "contentType": "font/ttf",
      "application": "flowx",
      "flowxUuid": "ce0f75e2-72e4-40e3-afe5-3705d42cf0b2"
    },
    {
      "fontFamily": "Open Sans",
      "filename": "OpenSans-BoldItalic.ttf",
      "weight": 700,
      "style": "italic",
      "size": 135108,
      "storagePath": "https://d22tnnndi9lo60.cloudfront.net/devmain/flowx/fonts-folder/1690383295987_OpenSans-BoldItalic.ttf",
      "contentType": "font/ttf",
      "application": "flowx",
      "flowxUuid": "d3e5e2a0-958a-4183-8625-967432c63005"
    }
    //...

     ],
      "exportVersion": 1
}

```

## Importing fonts

You can use the import feature to import a **JSON file** containing font files from another environment. This is useful for transferring your font library between different environments (for example, from development to production).

> [!NOTE]
>
> **Important distinction**:
>
> * **Import** = Upload a JSON file exported from another environment (bulk transfer of fonts)
> * **Upload font** (+) = Add individual TTF font files one by one

If a font file already exists in the target environment, you will be notified.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/import_fonts.png)

## Using fonts in UI Designer

For example, for an input UI element you can customize the typography by changing the following properties:

* Label:
  * Font family
  * Style and weight
  * Font line size (px)
  * Font line height (px)

* Text:
  * Font family
  * Style and weight
  * Font line size (px)
  * Font line height (px)

* Helper & errors:
  * Font family
  * Style and weight
  * Font line size (px)
  * Font line height (px)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/usinf_fonts.gif)


# Global Media Library
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/design-assets/global-media-library

System assets serve as a centralized hub for managing and organizing various types of media files outside an application, used on themes, including images, GIFs, and more.

![Global Media Library](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/global_media_library.png)

# 🌐 Global Media Library

This section is accessible from the left-side navigation under:

> **FlowX.AI Designer → Design Assets → Global Media Library**

***

## 📁 Media Library overview

The main **Media Library** interface displays all uploaded media assets in a table format with the following columns:

* **Preview**: Thumbnail preview of the asset.
* **Key**: A unique identifier for the asset.
* **Format**: File type (e.g., SVG, PNG).
* **Size**: File size.
* **Used as icon**: Indicates if the asset is used as a global icon (✓ if true).

![Use As Icon](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/use_as_icon.png)

* **Edited by**: User who last modified the asset.
* **Edited at**: Timestamp of the last modification.

Each asset row also includes:

* ✏️ **Edit icon**: To update the asset.
* ⋮ **More actions menu**: For additional options.

***

## ➕ Adding a New Asset

To add a new media asset:

1. Click the **blue plus (+)** button in the top-right corner.
2. In the **Add new item** dialog:
   * Click **Upload item** to select a file from your device.
   * Enter a **Key** for the asset.
3. Click **Add** to upload the item to the library.

> [!TIP]
>
> **Important:** The key must be unique and **cannot** be changed later. Choose it carefully.

***

## 📥 Import and Export

Click the **⋮ menu** next to the + button to access:

* **Import media assets**: Bulk upload multiple media files.
* **Export all**: Download all media assets as a ZIP archive. You can choose whether to **include media file content (binaries)** in the export — include them when moving assets to an environment that cannot reach this environment's storage; leave them out for a lighter, metadata-only archive.

> [!NOTE]
>
> The global Media Library is a separate, organization-level library with its own content. It is not a way to re-export the assets of a specific project — for project assets, use the [project Media Library](../../platform-deep-dive/core-extensions/content-management/media-library) or a project version/build export.

***

## 🔍 Search Functionality

Use the **Search item by key** bar at the top to find media assets quickly. Results are filtered as you type.

***

## 📌 Icon Usage

If an asset is marked with a ✓ under the **Used as icon** column, it is actively used as a global icon across the FlowX.AI platform.


# Themes
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/design-assets/themes

Theme management enables you to change the appearance and styling of your app. Personalize the look and feel to match your branding, preferences, or specific requirements.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/themes4.5.0.png)

## Key features of theme management

1. **Theme Management:**
   * Creation, editing, and management of themes.
   * Selection of predefined themes or customization of themes from scratch.

2. **Customization Options:**
   * Modification of color schemes, typography, spacing, and visual effects.
   * Upload of custom assets like fonts and icons.

3. **Overrides and Variations:**
   * Ability to override default UI components styles properties on specific elements or sections.
   * Creation of different themes to accommodate different users/clients preferences.

4. **Platform Consistency:**
   * Consistency of theme styles across different platforms and devices.

5. **Preview:**
   * Real-time visualization of theme changes.

6. **Export/Import Functionality:**
   * Export of themes for backup, sharing, or reuse across multiple environments (UAT, DEV, etc.).
   * Import of exported from other environments.

## Creating a new theme

> [!NOTE]
>
> You have two options for creating the theme. You can import a theme that was exported from another environment (for example, your UAT/DEV) or to manually create it.

To successfully create a new theme in FlowX.AI Designer, follow these steps:

**1. Initiating theme creation**

Locate the "Create New" button positioned above the right of the **Themes** list table.

**2. Inputting theme details**

Click the "Create New" button and enter  details for your theme:

* **Theme Name** - pick a name for your theme
* **Font Family** - select your desired font family, by default, the system provides "Open Sans"

> [!TIP]
>
> If you wish to add a new font, click on the link provided under the **Font Family** field, which redirects you to the **Fonts management** Selection.

* **Choose your primary color** - the default color is `#006BD8`.

> [!TIP]
>
> Verify that the color format is in **HEX**. If not, an error message will indicate "Please insert a HEX color."

<video />

## Configuring a new theme

After creating a theme, you must configure it. To configure your theme effectively, follow these steps:

**1. Access theme settings**

* Navigate to the settings or customization section of your app (in the UI Designer).
* Look for options related to styling and think of an overall design

**2. Customize theme settings**

> [!NOTE]
>
> The Themes styles mechanism is based on hierarchy. In this hierarchy we have the following elements: Design Tokens, Global Settings and Components.

Modify color schemes (using the design tokens), typography, spacing, and other visual elements to match your desired look and feel.
Use the provided tools or controls to adjust theme settings. This might include sliders, color pickers, or dropdown menus.

> [accordion] Design Tokens
>
> > [!NOTE]
> >
> > **The Design Tokens** represent values based on which the theme is built.
>
> * **Color Palette, Shadows, Typography Tokens**: Configure these tokens based on your company's brand guidelines. They ensure reusability and consistency.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/design_tokens_theme.gif)

> [accordion] Global Settings
>
> > [!NOTE]
> >
> > The **Global Settings** are properties that inherit values from the **Design Tokens** and sit on the top of the hierarchy. These properties are then inherited by the **Components**.
>
> * **Platform-specific Settings**: Configure settings for each platform (web, iOS, Android) based on the global settings you've defined.
> * **Styles and Utilities**: General settings applying to all components (styles) and labels, errors, and helper text settings (utilities).
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/global_settings_theme.gif)

> [accordion] Component-level configuration
>
> > [!NOTE]
> >
> > When setting up your theme, remember that different platforms like web, iOS, and Android have their own settings. You need to configure each platform separately. Only color settings are the same across all platforms.
>
> > [!TIP]
> >
> > For example, you can configure a web theme, and then use the push and import options. You can push from the web the same configuration to iOS or Android.
>
> **Component-level Configuration**: Customize the style of each component type.
>
> > [!NOTE]
> >
> > Keep in mind, there are differences between platforms, for example, for button configuration there are different properties available. What you configure on a platform will not be inherited by the others.
>
> > [!NOTE]
> >
> > The theme includes a configurable **Modal** component. You can style the modal container (padding, gap, border width, border radius, shadow, background and border colors) and its header (padding, gap, alignment, icon color, title and subtitle text styles and colors, and the dismiss icon).
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/platform-components.gif)

**3. Reviewing the changes (multi-platform)**

* Before finalizing the theme configuration, it's crucial to review how the changes will appear across different platforms. This step ensures consistency and allows for platform-specific adjustments if needed.
* You can do that by either using the preview feature from **Themes** or by using the preview mode in the **UI Designer** by switching to your preffered platform.

> [!WARNING]
>
> Keep in mind that the preview generated in the UI Designer for iOS and Android platforms is an estimate meant to help you visualize how it might look on a mobile view.

Here is a quick walkthrough video on how to create and configure a theme:

<video />

## Managing themes - process level (theme overrides)

With the Overrides feature you have now the possibility to override default theme settings on specific elements or sections.

Use Theme Overrides in UI Designer to adjust styles or props for specific UI elements based on the desired platform (Web, iOS and Android).

> [!NOTE]
>
> All components can now be styled with token overrides, for color, typography and shadow settings defined in the theme.

> [!NOTE]
>
> **Theme overrides** in **UI Designer** are applied to the component itself, rather than to specific themes. This means that when switching the view to another theme, the overrides persist and apply to the new theme as well.

### Styles tab

The Styles tab functions independently for three platforms: Web, iOS, and Android. Here, you can customize styles for each UI component on each platform.

If you want to customize the appearance of a component to differ from the theme settings, you must apply a **Theme Override**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styless.gif)

> [!NOTE]
>
> Theme overrides can be imported from one platform to another.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/theme_overrides_styles.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_designer_panel2.png)

> [!NOTE]
>
> Preview mode: In the UI Designer, overrides are entirely independent of the theme. Regardless of the theme selected in preview mode, you will see the applied override reflected at the UI Designer level.

### Preview

When you are editing a process in **UI Designer** you have the possibility of having the preview of multiple themes:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/preview_theme_ui_designer.gif)

> [!NOTE]
>
> Overrides are completely independent of the theme, regardless of which theme you choose in the preview mode.

## Using a Theme in the container application

To integrate the theme into your container application, follow these steps:

* Copy the unique identifier (UUID) associated with the theme.
* Set the copied UUID within your container application.
* By doing so, ensure that the renderers within your application can recognize and apply the specified theme.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/copy_uuid.gif)

## Exporting/importing a theme

The Export/Import functionality in the theme management system allows users to export themes for various purposes such as backup, sharing, or reuse across multiple environments.

Additionally, it enables importing themes previously exported from other environments, facilitating integration and continuity across design workflows.

> [!WARNING]
>
> Import is restricted to internal FlowX.AI mechanisms only; themes from external sources like Figma or Zeplin are not supported.

### Exporting a theme

**Step 1**

Navigate to **Design Assets** → **Themes**.

**Step 2**

Find the theme you want to export.

**Step 3**

Open the theme's contextual menu and select **Export**.

**Step 4**

The exported theme is saved in a standard format (JSON) and can be downloaded to a local directory or storage location.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/exporting_a_theme.gif)

### Importing a theme

**Step 1**

Navigate to **Design Assets** → **Themes**.

**Step 2**

From the contextual menu at the top of the page, select **Import from ZIP**.

**Step 3**

Import it as a new theme or if the theme already exists in other environment, you can override it.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_a_theme.gif)

### Setting a default theme

You can establish a default theme by accessing the contextual menu on the right side of a theme and selecting "Set as Default."

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/default_th.png)

When a default theme is not set (or you haven't created a theme yet), the platform automatically assigns the FlowX.AI Theme, which is the platform's default theme. This ensures that there's always a default theme in place to provide a consistent appearance across processes and interactions within the app.

> [!NOTE]
>
> In case you select a specific default theme but later you delete it, the platform will revert to the FlowX.AI theme as the default. This safeguard ensures that there's always a default theme available, even if you remove your custom selection.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/2024-04-04%2019.00.33.gif)

Upon opening any process within the UI Designer, the default theme displays as the initial preview. This gives you a clear starting point and ensures consistency in the appearance of the process until you apply further customization.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/default2.png)

When creating a new process, you will notice the Default Theme (*FlowXTheme*) as the default preview.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/default1.png)

> [!NOTE]
>
> Furthermore, when you start a process definition, the theme switch defaults to the default theme in the run process popup from the process definitions list. This ensures that the default theme is consistently applied during the execution of processes, maintaining visual coherence in user interactions.


# Adding a new node
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/adding-a-new-node

Learn how to add and configure different node types to build process flows in FlowX.AI Designer.

Once you've created a process definition, the next step is to build your process flow by adding and connecting nodes. Nodes represent different steps, events, and decision points in your business process.

![Adding a new node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_add_new_node.gif)

## What is a BPMN node?

> [card] BPMN node
>
> A BPMN (Business Process Model and Notation) node is a visual representation of a point in your process. Nodes are added at specific process points to denote the entrance or transition of a record within the process. Each node type has a specific purpose and configuration requirements.

## Available node types

FlowX.AI supports a rich variety of BPMN node types that you can use to model your business processes:

### Flow control nodes

> [card] [Start event](../../building-blocks/node/start-end-node)
>
> Marks the beginning of a process flow

> [card] [End Event](../../building-blocks/node/start-end-node)
>
> Marks the conclusion of a process flow

### Activity nodes

> [card] [Task Node](../../building-blocks/node/task-node)
>
> Executes automated tasks and business rules

> [card] [User Task](../../building-blocks/node/user-task-node)
>
> Creates user interfaces and handles user interactions

> [card] [Send Message Task](../../building-blocks/node/message-send-received-task-node)
>
> Sends data to external systems or services

> [card] [Receive Message Task](../../building-blocks/node/message-send-received-task-node)
>
> Receives data from external systems or services

### Gateway nodes

> [card] [Exclusive gateway](../../building-blocks/node/exclusive-gateway-node)
>
> Creates decision points with mutually exclusive paths

> [card] [Parallel Gateway](../../building-blocks/node/parallel-gateway)
>
> Splits process flow into multiple concurrent paths

### Event nodes

> [card] [Message event](../../building-blocks/node/message-events/)
>
> Captures interactions between different process participants

> [card] [Timer Event](../../building-blocks/node/timer-events/timer-events)
>
> Triggers actions based on time conditions or delays

> [card] [Error Event](../../building-blocks/node/error-events)
>
> Manages error handling in processes

### Subprocess nodes

> [card] [Call activity](../../building-blocks/node/call-subprocess-tasks/call-activity-node)
>
> Calls and runs a subprocess within the main process

> [card] [Start Embedded Subprocess](../../building-blocks/node/call-subprocess-tasks/start-embedded-subprocess)
>
> Initiates subprocesses embedded within a parent process

### Boundary event nodes

> [card] [Message catch boundary event](../../building-blocks/node/message-events/message-catch-boundary-event)
>
> Waits for a specific message during task execution

> [card] [Timer Boundary Event](../../building-blocks/node/message-events/message-catch-boundary-event)
>
> Triggers based on time conditions during task execution

> [card] [Error Boundary Event](../../building-blocks/node/error-events#configuring-an-error-intermediate-boundary-event)
>
> Catches errors during task or subprocess execution

> [!NOTE]
>
> Boundary events can only be attached to certain node types:
>
> * User Task
> * Service Task
> * Send Message/Receive Message Tasks
> * Subprocess (Embedded and Call Activity)

For more information on BPMN node types and BPMN standards, see the following resources:

> [card] [BPMN Node Documentation](../../building-blocks/node/node)
>
> BPMN node types in FlowX.AI

> [card] [Intro to BPMN](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn)
>
> Learn fundamental BPMN concepts and standards

For a comprehensive understanding of BPMN standards and concepts, see [BPMN 2.0 Basic Concepts](../../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn).

> [card] [BPMN 101](https://academy.flowx.ai/explore/bpmn-101)
>
> Learn more about BPMN and how it's used in FlowX through our Academy course

## Adding a node to your process

**1. Access Your Process Definition**

1. Open **FlowX.AI Designer** and navigate to your project
2. Go to the **Processes** section within your project
3. Click on the process definition you want to edit

**2. Add a Node to the Canvas**

1. Locate the node palette on the left side of the screen
2. **Drag and drop** your desired node type onto the canvas
3. Position the node where you want it in your process flow

> [!TIP]
>
> Organize your process flow from left to right for better readability. Place related nodes closer together to show their relationship.

**3. Connect Nodes with Sequence Flows**

To create a connection between nodes (called a sequence flow):

1. Click on the source node to select it
2. Click the **arrow** icon that appears
3. Click on the target node you want to connect to
4. A sequence flow arrow will be created between the two nodes

![Connect nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_sequence.png)

> [!WARNING]
>
> Every node (except End nodes) must have at least one outgoing sequence flow, and every node (except Start nodes) must have at least one incoming sequence flow for the process to be valid.

**4. Configure Node Properties**

After adding a node, you need to configure its properties:

1. Click on the node to select it to open the properties panel
2. Click edit icon to open the properties panel
3. Configure basic properties like name and description
4. Set node-specific properties depending on the node type
5. Configure actions for the node

![Node edit menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_edit_menu.png)

![Node properties](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_config.png)

> [!NOTE]
>
> Different node types have different configuration options. For example, Gateway nodes have condition-related settings.
>
> ![Gateway configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gateway_config.png)

**5. Add Actions to Nodes**

For nodes that support actions (task nodes, user task nodes, and message nodes):

1. Select the node
2. In the properties panel, navigate to the **Actions** section
3. Click **+ Add Action**
4. Select the action type and configure its parameters

![Add action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/node_action.png)

> [!NOTE]
>
> Actions allow you to incorporate business rules, save data, send messages, and interact with users. Learn more about [Node Actions](../../building-blocks/actions/actions).

## Common node configuration options

While each node type has specific properties, many share these common configuration options:

> [accordion] Basic Properties
>
> * **Name**: A descriptive name for the node (visible in the Process Designer).
> * **Can go back**: Option available in various nodes that controls whether users can return to previous steps in a process. When enabled (set to true), it allows users to revisit and redo that step after completing it.
> * **Stage**: The stage of the process the node belongs to.

> [accordion] Action Properties
>
> For nodes that support actions:
>
> * **Action Type**: Type of action to execute
> * **Action Parameters**: Configuration for the specific action
> * **Execution Order**: Sequence for multiple actions on a node

## Node type-specific configuration

> [card] User Task Configuration
>
> * UI Component selection
> * Form configuration
> * Data validation rules
> * Task assignment settings

> [card] Gateway Configuration
>
> * Condition expressions
> * Default sequence flow
> * Branch naming
> * Gateway direction (diverging/converging)

> [card] Message Task Configuration
>
> * Message format
> * Target system
> * Correlation keys
> * Timeout handling

> [card] Service Task Configuration
>
> * Service implementation
> * Input/output mapping
> * Error handling
> * Execution parameters

## Best practices

> [!TIP]
>
> **When adding nodes to your process:**
>
> * **Use descriptive names** for nodes to make the process easier to understand
> * **Organize the layout** from left to right for better readability
> * **Limit the number of sequence flows** from a single node to maintain clarity
> * **Group related functionality** into subprocesses to reduce complexity
> * **Document assumptions and decisions** in node descriptions
> * **Validate your process** regularly during development to catch errors early

## Next steps

After adding nodes to your process, you can:

> [card] [Add Actions to Nodes](../managing-a-project-flow/adding-an-action-to-a-node)
>
> Configure business rules and actions for your nodes


# Adding an action to a node
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/adding-an-action-to-a-node

Learn how to enhance your process flows by adding actions to nodes for business rules, data management, and integration with external systems.

Actions are elements that bring your process nodes to life by adding business logic, data management capabilities, and integration with external systems. They define the specific activities that nodes perform within your process flow.

![Adding a node action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_add_node_action.gif)

## What is a node action?

> [card] Node Action
>
> A node action defines the specific activity that a node performs within a process flow. Actions allow you to incorporate business rules, manage data, communicate with external systems, and control what gets displayed in the user interface. They are the building blocks that drive your process logic and user interactions.

> [card] [Actions Documentation](../../building-blocks/actions)
>
> Comprehensive documentation on all action types and their configurations

> [card] [Business Rules](../../building-blocks/actions/business-rule-action/business-rule-action)
>
> Learn how to implement business logic with rule actions

## Action types

FlowX.AI supports several types of actions that can be added to nodes, broadly categorized into business rules and user interactions:

### Business rules and data management

> [card] Business Rule
>
> Add custom logic and decision-making using scripts

> [card] Save Data
>
> Persist process data to storage

> [card] Upload File
>
> Handle file uploads within the process flow

### Integration and messaging

> [card] Start Integration Workflow
>
> Trigger an integration workflow that connects to external systems

> [card] Kafka Send
>
> Send messages directly to Kafka topics for event-driven scenarios

> [card] [Send Notification](../../building-blocks/actions/send-notification-action)
>
> Send an email directly through an email connection, as a new message or a reply to a received email

> [!TIP]
>
> For connecting to external systems, prefer **Start Integration Workflow**: you configure the connection visually in a workflow and get data mapping without managing topics. Use **Kafka Send** when you need direct control over Kafka topics and message formats, for example when integrating with a custom connector.

### Process control

> [card] Start Subprocess
>
> Initiate a subprocess from within the current process

> [card] Append Params to Parent Process
>
> Pass data back to a parent process from a subprocess

> [card] Start New Project Instance
>
> Launch a new project instance from within a process

### User interface

> [card] Send Data to User Interface
>
> Send data to be displayed in front-end applications

> [!NOTE]
>
> Actions can only be added to certain node types:
>
> * Task nodes (Service Tasks)
> * User Task nodes
> * Send Message/Receive Message Task nodes

## Adding an action to a node

**1. Access Your Process Definition**

1. Open **FlowX.AI Designer** and navigate to your project
2. Go to the **Processes** section within your project
3. Select your process definition from the list
4. Click the **Edit Process** button to open the Process Designer

**2. Select or Add a Node**

1. Either select an existing node that supports actions, or add a new one
2. Remember that only Task nodes, User Task nodes, and Message Task nodes support actions

> [!NOTE]
>
> If you need to add a new node first, refer to the [Adding a New Node](./adding-a-new-node) documentation.

**3. Add an Action**

1. With the node selected, locate the **Actions** section in the properties panel
2. Click the **+ Add Action** button
3. From the dropdown menu, select the action type you want to add

![Adding a node action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_add_node_action.gif)

**4. Configure Action Parameters**

Each action type requires specific configuration parameters:

1. Fill in the required fields for your selected action type
2. Configure optional parameters as needed
3. Save your changes

![Action parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/actions_paramss.png)

> [!WARNING]
>
> Pay careful attention to parameter syntax and formatting. Incorrect configurations may cause the action to fail during process execution.

**5. Set Action Execution Order (Multiple Actions)**

If you have multiple actions on a single node:

1. Use the drag handles to arrange the actions in the desired execution order
2. Actions will execute from top to bottom in the list
3. Consider dependencies between actions when setting the order

> [!TIP]
>
> For complex nodes with multiple actions, consider adding comments in scripts or descriptions to document the purpose and dependencies of each action.

**6. Save Your Process**

Click the **Save** button to save your process definition with the new action.

## Common action configurations

Different action types require different configurations, but many share these common elements:

> [accordion] Business Rule Action
>
> * **Name**: Descriptive identifier for the rule
> * **Script Type**: JavaScript or other supported languages
> * **Script Content**: The business logic to execute
> * **Input Parameters**: Data inputs to the script
> * **Output Parameters**: Data returned from the script

> [accordion] Save Data Action
>
> * **Process Variables**: The data to be saved
> * **Target Storage**: Where the data should be persisted
> * **Data Mapping**: How process data maps to storage fields

> [accordion] Kafka Send Action
>
> * **Topic**: The Kafka topic to send messages to
> * **Key**: Identifier for the message
> * **Value**: The data payload to send
> * **Headers**: Additional message metadata

> [accordion] Send Data to User Interface
>
> * **UI Component**: The target component to update
> * **Data**: The information to display
> * **Formatting**: Display options for the data

## Best practices

> [!TIP]
>
> **When adding actions to nodes:**
>
> * **Use meaningful action names** to clearly indicate their purpose
> * **Keep business rules focused** on a single responsibility
> * **Document complex logic** with comments in your scripts
> * **Consider error handling** in your action configurations
> * **Test actions individually** before relying on them in production flows
> * **Monitor performance** of actions that might be resource-intensive
> * **Use consistent data structure** across related actions for better maintainability

## Next steps

After adding actions to your nodes, you can:

> [card] [Handling decisions in the flow](../../flowx-designer/managing-a-project-flow/handling-decisions-in-the-flow)
>
> Learn how to implement conditional branching in your processes using exclusive gateways

> [card] [Configure UI Components](../../flowx-designer/managing-a-project-flow/creating-a-user-interface)
>
> Design the user interface elements that will interact with your actions


# Adding parallel flow branches
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/adding-more-flow-branches

Learn how to create concurrent process flows using parallel gateways to execute multiple activities simultaneously.

In many business processes, certain activities can or should be performed simultaneously rather than sequentially. FlowX.AI's parallel gateway nodes allow you to split your process flow into multiple concurrent branches, enabling parallel execution of different activities.

![Parallel Gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/process_flowx_parallel.png#center)

Parallel Gateway Visualization

## What is a parallel gateway?

> [card] Parallel Gateway
>
> A parallel gateway (also known as an AND gateway) creates multiple concurrent paths in your process flow. Unlike exclusive gateways which follow only one path, parallel gateways activate all outgoing paths simultaneously. This allows multiple activities to be performed in parallel, improving process efficiency.

> [card] [Parallel Gateway Documentation](../../building-blocks/node/parallel-gateway)
>
> Complete reference for parallel gateway configuration

> [card] [Process Flow Tokens](../../building-blocks/token)
>
> Learn more about how tokens drive process flow execution

## How parallel gateways work

![Parallel Branches Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/parallel_zn.png)

Process Flow with Parallel Branches

Parallel gateways function as fork and join points in your process:

1. **Fork (Diverging Gateway)**: Splits the process flow into multiple concurrent paths
2. **Parallel Execution**: All branches execute simultaneously and independently
3. **Join (Converging Gateway)**: Merges the parallel branches back into a single flow
4. **Synchronization**: The process waits until all parallel branches complete before proceeding

> [!NOTE]
>
> A process must have both a diverging parallel gateway (fork) and a converging parallel gateway (join) that brings all branches back together. All branches must be completed before the process can continue past the converging gateway.

## Token behavior in parallel gateways

Tokens are fundamental to understanding how parallel flows work in FlowX.AI:

![Token Flow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/token_parallel.png)

Token Flow in Parallel Gateways

**1. Token Creation**

When a process reaches a parallel gateway, the gateway creates child tokens for each outgoing branch. Each branch receives its own token.

**2. Independent Execution**

Each child token advances through its respective branch independently, proceeding from one node to the next based on the sequence and actions defined in the process.

**3. Token Synchronization**

A converging parallel gateway waits for all child tokens to arrive. The parent token remains at this gateway until all child tokens have completed their respective paths.

**4. Process Continuation**

Once all child tokens have arrived at the converging gateway, they are merged back into the parent token, and the process continues with a single token.

> [!WARNING]
>
> If any parallel branch gets stuck or never completes, the entire process will wait indefinitely at the converging gateway. Always ensure all branches can complete successfully.

## Creating a flow with parallel branches

**1. Create or Open a Process Definition**

1. Open **FlowX.AI Designer** and navigate to your project
2. Go to the **Processes** section and select your process or create a new one
3. Click the **Edit Process** button to open the Process Designer

**2. Add Basic Flow Elements**

1. Add a **Start Node** to your process canvas (if creating a new process)
2. Add initial nodes for any process steps that should occur before the parallel branches

> [!NOTE]
>
> Plan your parallel branches carefully. Activities in parallel branches should be independent of each other and not rely on results from other branches.

**3. Add the Diverging Parallel Gateway**

1. From the node palette, drag a **Parallel Gateway** node onto your canvas
2. Connect your previous node to this gateway
3. Give your gateway a descriptive name (e.g., "Start Parallel Processing")

**4. Create Parallel Branches**

1. Add the nodes for each parallel branch that will execute simultaneously
2. Connect the diverging parallel gateway to the first node of each branch
3. Build out each branch with the necessary nodes and actions

> [!TIP]
>
> You can have any number of parallel branches, but keep in mind that every branch must eventually connect to the converging gateway.

**5. Add the Converging Parallel Gateway**

1. Add another **Parallel Gateway** node to the canvas
2. Connect the last node of each parallel branch to this converging gateway
3. Give this gateway a descriptive name (e.g., "Merge Parallel Branches")

> [!WARNING]
>
> Ensure that all parallel branches connect to the converging gateway. Missing connections will result in stuck processes.

**6. Complete the Process Flow**

1. Add any additional nodes that should execute after the parallel branches
2. Connect the converging gateway to the next node in your process
3. Ensure your process eventually reaches an **End Node**
4. Save your process definition

## Use cases for parallel gateways

Parallel gateways are ideal for the following scenarios:

> [card] Document Collection
>
> Requesting multiple documents simultaneously from different systems or departments

> [card] Multi-Party Approval
>
> Collecting approvals from multiple stakeholders at the same time

> [card] Data Processing
>
> Performing multiple data operations or calculations in parallel

> [card] Background Checks
>
> Running different validation or verification processes concurrently

## Best practices

> [!TIP]
>
> **When implementing parallel branches:**
>
> * **Use meaningful names** for parallel gateways to document their purpose
> * **Keep branches independent** of each other to avoid deadlocks or race conditions
> * **Balance work** across branches to optimize overall process execution time
> * **Consider timeouts** for branches that might get stuck or take too long
> * **Test all branches** thoroughly to ensure they can complete successfully
> * **Use data scoping** carefully to prevent data conflicts between branches
> * **Consider error handling** in each branch to prevent process deadlocks

## Common patterns

> [card] Simple Parallel Split-Join
>
> Basic pattern with a diverging and converging gateway

> [card] Multi-Layer Parallel Processing
>
> Nested parallel structures with gateways inside parallel branches

> [card] Parallel Tasks with Timeouts
>
> Parallel branches with timer events to handle potential delays

> [card] Collect and Merge
>
> Parallel branches that gather different pieces of information for later consolidation

## Next steps

After implementing parallel branches in your process, you can:

> [card] [Creating a user interface](../../flowx-designer/managing-a-project-flow/creating-a-user-interface)
>
> Design the user interface elements that will interact with your actions


# Creating and managing process definitions
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-new-process-definition

Learn how to create new process definitions and manage them using operations like export, duplicate, copy between projects, and view dependencies.

<video />

## What is a process definition?

A process definition is the core building block of the FlowX.AI platform, serving as the blueprint for a business process. It's composed of nodes linked by sequences that define the path and logic of your application's workflow.

> [!NOTE]
>
> A complete process definition must include at least one [START](../../building-blocks/node/start-end-node#start-node) and one [END](../../building-blocks/node/start-end-node#end-node) node to mark where the process begins and concludes.

> [card] Executable Blueprint
>
> Process definitions can be instantiated, executed, and monitored within the platform

> [card] Business Logic Container
>
> Houses all actions, decisions, user interfaces, and integrations for your business process

> [card] Event-Driven Flow
>
> Nodes and sequences create a path for process tokens to follow based on conditions and events

> [card] Multi-Platform Support
>
> Process definitions can generate interfaces for web, mobile, and other platforms

## Creating a process definition

**1. Access the Process Definitions Section**

1. Open **FlowX.AI Designer** and navigate to your project
2. Go to the **Processes** section within your project

> [!NOTE]
>
> You must have already created a project before creating process definitions. Process definitions belong to projects and inherit project settings.

**2. Create a New Process Definition**

1. Click the **+ New Process** button in the top-right corner
2. Enter a unique name for your process definition that clearly describes its purpose
3. Optionally, add a description to provide context about what this process does
4. Click **Create** to create the new process definition

> [!TIP]
>
> Use a descriptive naming convention for your processes, such as "\[Department]-\[Function]-\[Action]" (e.g., "HR-Onboarding-Application").

![Process Definition Editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/create_new_process.png)

**3. Configure the Process Definition**

After creating the process definition, you'll be automatically directed to the FlowX.AI Process Designer editor where you can start building your process flow.

![Process Designer Empty Canvas](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/process_designer_empty.png)

**4. Add Start and End Nodes**

Every process definition must have at least one START node and one END node:

1. From the node palette on the left, drag a **START** node onto the canvas
2. Configure the START node properties in the panel that appears
3. Drag an **END** node onto the canvas
4. Connect the nodes by clicking on the START node, selecting the arrow command, and then clicking on the END node

> [!WARNING]
>
> Without properly configured START and END nodes, your process won't be executable. The START node initializes the process, while the END node ensures proper process completion.

**5. Build Your Process Flow**

Expand your process by adding additional nodes between the START and END nodes:

1. Drag the appropriate node types from the palette onto the canvas
2. Configure each node's properties and actions
3. Connect nodes in the sequence they should execute
4. Add conditions and gateways to create branching logic

> [card] Task Nodes
>
> For business rules and automated actions

> [card] User Task Nodes
>
> For user interactions and UI components

> [card] Gateways
>
> For decision points and parallel flows

**6. Save Your Process Definition**

Regularly save your work by clicking the **Save** button in the editor toolbar.

> [!NOTE]
>
> Process definitions are saved within your project but need to be included in a project version and build to be deployed to environments.

## Key node types

When building your process definition, you'll use various node types to model your business logic:

> [accordion] Start and End Nodes
>
> **Start Node**: Marks the beginning of a process flow, defining how a process instance is initiated.
>
> **End Node**: Marks the conclusion of a process flow, ensuring proper cleanup and completion.
>
> > [!NOTE]
> >
> > A process can have multiple START nodes (with different conditions) and multiple END nodes depending on the possible outcomes.

> [accordion] Task Nodes
>
> **Task Node**: Used for executing automated actions without user interaction.
>
> **User Task Node**: Configures the UI components and collects data from users.
>
> **Send/Receive Message Tasks**: Used for communication with external systems and services.

> [accordion] Gateway Nodes
>
> **Exclusive Gateway**: Creates decision points where the flow follows only one path based on conditions.
>
> **Parallel Gateway**: Splits the process into multiple parallel branches that execute simultaneously.

> [accordion] Special Nodes
>
> **Subprocess Run Node**: Enables you to run a subprocess within the main process.
>
> **Timer Events**: Schedule actions to occur at specific times or after delays.
>
> **Message Events**: Handle message-based communication between processes.

## Adding actions to nodes

Nodes can have actions associated with them to perform specific operations:

> [card] Business Rules
>
> Execute logic, validate data, and make decisions

> [card] Data Operations
>
> Save, retrieve, and manipulate process data

> [card] Integration
>
> Connect with external systems and services

> [card] UI Interactions
>
> Send data to and receive data from users

> [!NOTE]
>
> Actions can only be added to certain node types: task nodes, user task nodes, and send/receive message tasks.

## Managing process definitions

After creating process definitions, you can manage them using the contextual menu available in the Processes list. Access this menu by clicking the three-dot icon (⋮) next to any process entry.

![Process management menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_dsg_cm.png)

Process contextual menu with management options

> [!NOTE]
>
> **Two contextual menus available:**
>
> This menu is accessible from the **Processes list view** (before opening a process). There's also a separate contextual menu available when you're **inside** a process definition that provides operations like Clear Cache, Audit Log, View History, and Delete.

> [card] [Operations inside process definitions](../../building-blocks/process/process-definition#6-access-additional-operations)
>
> Learn about the contextual menu available while editing a process definition

### Configure process settings

Open the process settings interface to configure process-level options including permissions, platform selection, task management integration, and data search indexing.

**To configure a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Settings** from the menu
3. The settings panel opens, where you can modify:
   * Process name and general settings (on SaaS 5.13, open the process and use the ⋮ menu → **Details** in the process editor instead)
   * Platform selection (Web, Mobile, Omnichannel)
   * Permissions and swimlane access control
   * Task management integration
   * Data search and indexing

> [card] [Process settings](../../building-blocks/process/process-definition#configure-process-settings)
>
> Complete guide to all process configuration options

### Export a process

Export a process definition to transfer it between environments, create backups, or share it with other teams.

**To export a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Export**
3. The system generates a downloadable package containing:
   * Process definition JSON
   * Process metadata and manifest files
   * Version information
4. Save the export file to your local system

**Export structure**:

When you export a process, FlowX.AI creates a structured folder:

* Root export folder with unique identifier
* Process subfolder with `manifest.json` and `metadata.json`
* Version subfolder with the process definition JSON file

> [!TIP]
>
> Use a clear naming convention for exported files such as `[ProcessName]_[Version]_[Date].zip` to help identify exports later.

> [!WARNING]
>
> Exported process definitions may contain environment-specific configurations. Review and adjust these settings when importing to a different environment.

> [card] [Export and import guide](./export-import-a-process-definition)
>
> Learn about importing exported processes

### Duplicate a process

Create a copy of an existing process definition within the same project. This is useful when you want to create a variant of a process or use an existing process as a template.

**To duplicate a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Duplicate**
3. Enter a name for the duplicated process
4. Click **Confirm** to create the copy

**What gets duplicated**:

* Complete process flow with all nodes and sequences
* All node configurations and actions
* UI Designer configurations
* Data model structure
* Process settings (permissions, platform selection, etc.)

**What doesn't get duplicated**:

* Process instances and runtime data
* Audit history
* Version history

> [!TIP]
>
> Use duplication to create process variants for different departments or to test significant changes without affecting the original process.

> [!NOTE]
>
> The duplicated process is created in the current work-in-progress (WIP) version of your project. Remember to commit your changes when ready.

### Copy to another project or library

Transfer a process definition to a different project or library within your FlowX.AI environment. This enables sharing reusable processes across multiple projects.

**To copy a process to another project**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Copy to another project/library**
3. Choose the destination project or library from the list
4. Optionally adjust the process name for the destination
5. Click **Confirm** to complete the copy operation

**Use cases**:

* **Create reusable components**: Move common processes to a shared library
* **Share across teams**: Copy processes to other team projects
* **Promote to production projects**: Transfer tested processes to production-ready projects
* **Create process templates**: Build a library of standard process templates

> [!WARNING]
>
> Ensure all dependencies (subprocesses, data types, integrations) exist in the destination project, or copy them separately. Missing dependencies will cause errors.

> [!NOTE]
>
> Copying a process creates an independent copy. Changes to the original won't affect the copied version and vice versa.

### See used resources

View all resources and dependencies that the process definition uses. This helps you understand the process's connections to other components and identify potential impacts when making changes.

**To view used resources**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **See used resources**
3. Review the list of dependencies, which may include:
   * Subprocesses and workflows
   * UI templates and components
   * Data model types
   * Integration connectors
   * Business rules and scripts
   * Document templates
   * Notification templates

**Benefits**:

* **Impact analysis**: Understand what will be affected by changes
* **Dependency tracking**: Ensure all required resources are available before deployment
* **Documentation**: Map relationships between processes and resources
* **Troubleshooting**: Identify missing or misconfigured dependencies

> [!TIP]
>
> Review used resources before exporting or copying a process to ensure you include all necessary dependencies in the target environment.

### View audit log

Access the comprehensive change history for the process definition, showing who made changes, when, and what was modified.

**To view the audit log**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Audit log**
3. Review the audit entries, which include:
   * Timestamp of each change
   * User who made the change
   * Application version
   * Event type and subject
   * Change status

**Audit log features**:

* **Filterable entries**: Search and filter by date, user, or event type
* **Complete audit trail**: Maintain compliance with regulatory requirements
* **Change tracking**: Identify when specific modifications were introduced
* **Troubleshooting**: Trace issues back to specific changes

> [card] [Audit documentation](../../platform-deep-dive/core-extensions/audit)
>
> Learn more about audit logging capabilities

### View history

Access the version history of the process definition to see how it evolved across different committed versions.

**To view version history**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **View history**
3. Review the list of versions
4. Select two versions to compare changes side-by-side

**History capabilities**:

* **Version comparison**: See exactly what changed between any two versions
* **Change tracking**: Identify when specific features were added or modified
* **Rollback reference**: Understand previous configurations if you need to revert changes
* **Documentation**: Track the evolution of your process over time

> [!NOTE]
>
> Version history shows committed versions only. Changes in the current work-in-progress version appear after you commit the project version.

> [card] [Project versioning](../../projects/managing-applications/versioning)
>
> Complete guide to version management

### Delete a process

Remove a process definition from your project when it's no longer needed.

**To delete a process**:

1. Click the three-dot menu (⋮) next to the process name
2. Select **Delete**
3. Confirm the deletion in the dialog that appears

> [!WARNING]
>
> **Use with extreme caution**: Deleting a process definition is a significant action with the following consequences:
>
> * The process definition is removed from the current work-in-progress (WIP) version
> * You cannot delete a process that's part of a committed version
> * Other processes that reference this one as a subprocess may break
> * The deletion can be recovered only from previous committed versions

**Before deleting a process**:

1. ✓ **Check for dependencies**: Use "See used resources" to identify processes that reference this one
2. ✓ **Review running instances**: Verify no critical process instances are currently active
3. ✓ **Backup if needed**: Export the process definition before deletion if you might need it later
4. ✓ **Update documentation**: Remove references to the deleted process from your documentation

**Impact of deletion**:

| Aspect | Impact |
| - | - |
| **Current WIP version** | Process is removed immediately |
| **Committed versions** | Previous versions remain unchanged |
| **Running instances** | Existing instances continue with their original definition |
| **Dependent processes** | May show errors or validation warnings |
| **Historical data** | Process instance data in reporting is not affected |

> [!NOTE]
>
> Deleted processes can be recovered by accessing previous committed versions through version history, but any uncommitted changes will be lost.

## Best practices

> [!TIP]
>
> **Process Definition Design Tips**:
>
> * Start with a simple skeleton process with START and END nodes before adding complexity
> * Create a logical flow from left to right in your diagram for better readability
> * Group related activities into subprocesses to keep the main process clean
> * Use clear naming conventions for nodes and actions
> * Document your process design decisions within node descriptions
> * Test your process with simulated data before publishing

## Next steps

After creating your process definition, you can:

> [card] [Add Nodes to Your Process](./adding-a-new-node)
>
> Learn how to add and configure different node types

> [card] [Create User Interfaces](./creating-a-user-interface)
>
> Build interactive UIs for your process

> [card] [Process Definition Deep Dive](../../building-blocks/process/process-definition)
>
> Comprehensive guide to process configuration and settings

> [card] [Export and Import](./export-import-a-process-definition)
>
> Transfer processes between environments

## Frequently asked questions

> [accordion] Can a process have multiple START nodes?
>
> Yes, a process definition can have multiple START nodes, each with different starting conditions as long as they are on different swimlanes. This allows the same process to be initiated in different ways depending on the context.
>
> > [!NOTE]
> >
> > Process definition cannot contain multiple start nodes on the same swimlane.

> [accordion] How do I modify an existing process definition?
>
> To modify an existing process, navigate to the Processes section in your project, find the process you want to edit, and click on it. Then click the "Edit Process" button to open it in the Process Designer.

> [accordion] Can I reuse parts of a process definition?
>
> Yes, you can create reusable components as subprocesses, which can then be called from multiple main processes. This promotes reusability and maintainability. You can also duplicate existing processes or copy them to other projects using the contextual menu operations described in the Managing process definitions section above.

> [accordion] Can I export or import process definitions?
>
> Yes, FlowX.AI allows you to export and import process definitions. Use the **Export** option from the process contextual menu to create a downloadable package. The export includes the process definition JSON, metadata, and version information in a structured format. See the [Export a process](#export-a-process) section above for detailed instructions.

> [accordion] How do I see what resources my process uses?
>
> Use the **See used resources** option from the process contextual menu to view all dependencies including subprocesses, UI templates, data model types, integrations, and more. This helps with impact analysis before making changes and ensures all dependencies are available when exporting or deploying the process.


# Creating a new project
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-project

Learn how to create and configure a new project in FlowX.AI Designer

The first step in building applications with FlowX.AI is creating a project. Projects serve as organized containers containing all the resources needed for your business solutions, including process definitions, UI components, and integrations.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

## What is a project?

A project in FlowX.AI is a structured container that groups all the resources required to implement a business solution. It's not just a collection of processes - it's a comprehensive unit that manages the entire lifecycle of your app.

> [card] Centralized Management
>
> Manage all resources, processes, and dependencies in one place, reducing context-switching

> [card] Version Control
>
> Track changes with versioning for processes, resources, and configurations

> [card] Multi-Environment Deployment
>
> Deploy consistent builds across development, QA, and production environments

> [card] Resource Organization
>
> Ensure clarity with structured resources and reduce configuration errors

## Project lifecycle

In FlowX.AI, a project follows a well-defined lifecycle from creation to deployment:

**1. Create Project**

Define basic project properties and settings

**2. Configure Resources**

Add and configure all necessary components

**3. Create Version**

Capture project state at significant milestones

**4. Build Package**

Create immutable deployment package from a version

**5. Deploy**

Release to development, QA, or production environments

This documentation covers the first two steps of creating and configuring a new project.

## Creating a project

**1. Access the Projects Section**

Log in to FlowX.AI Designer and navigate to the **Projects** section from the main navigation.

> [!NOTE]
>
> You'll need appropriate permissions to create new projects. If you don't see the Projects section, contact your FlowX administrator.

**2. Initiate Project Creation**

Click the **+ New Project** button to open the project creation dialog.

![Creating a new project](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/create_new_project.gif)

**3. Define Project Properties**

Configure the basic properties for your project:

* **Project Name**: Enter a descriptive name that clearly identifies your business solution
* **Platform Type**: Select the platform you want to use for your project:
  * Omnichannel
  * Web only
  * Mobile only

**4. Configure Version Settings**

Set up additional parameters that define how your project will function:

* **Default Theme**: Choose a theme to apply a consistent look and feel
* **Number Formatting**:
  * **Min/Max Decimals**: Configure how numbers are displayed
  * **Date Format**: Choose short or long date formats
  * **Currency Format**: Set display as ISO code (USD) or symbol (\$)
* **Languages**:
  * Set a default language (e.g., English)
  * Add additional languages for localization support

> [!NOTE]
>
> Project language settings serve two important purposes:
>
> * They fill the default state for preview in the UI Designer
> * They enable you to create translatable values in enumerations and substitution tags

![Configure initial settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/configure_initial.gif)

## Configuring project resources

After creating your project, you'll need to configure various resources before you can build and deploy your app. These resources form the foundation of your solution.

**1. Configure Project Resources**

Your project includes these key resource sections:

> [card] Processes
>
> Define business processes and subprocesses that orchestrate your application workflows

> [card] Project Data Model
>
> Define the data structure shared by the processes in your project

> [card] Reusable Resources
>
> Build UI templates, custom components, and functions you can reuse across processes

> [card] UI Flows
>
> Design screen flows and interfaces with the visual UI builder

> [card] CMS
>
> Configure enumerations, substitution tags, media, notification templates, and document templates

> [card] Task Manager
>
> Set up views, stages, and allocation rules for workload management

> [card] Integrations
>
> Connect to external systems through data sources, workflows, and proxy connections

> [card] Dependencies
>
> Add libraries containing reusable resources shared across projects

> [card] Configuration Parameters
>
> Define environment-specific parameters for deployment flexibility

> [card] Version Settings
>
> Manage platform type, themes, formatting, and languages for the project version

> [!NOTE]
>
> **Resource Inventory**: Your project can include the following components:
>
> **Process Resources**:
>
> * Process definitions with BPMN diagrams
> * Action configurations and task settings
> * Subprocess definitions and connections
>
> **UI Resources**:
>
> * Screen layouts and component configurations
> * Form definitions and validation rules
> * Navigation flows and interaction patterns
>
> **Content Resources**:
>
> * Enumerations for dropdown menus and selections
> * Substitution tags for dynamic content
> * Media assets (images, videos, documents)
>
> **Integration Resources**:
>
> * API endpoint configurations
> * Data mappings and transformations
> * Workflow definitions for system interactions
>
> **Supporting Resources**:
>
> * Themes and styling assets
> * Configuration parameters for environments
> * Library dependencies for shared functionality

> [!TIP]
>
> **Configuration Best Practices**:
>
> * Begin with process definitions before configuring supporting resources
> * Use clear, consistent naming conventions across all resources
> * Configure reusable components in libraries when they'll be used in multiple projects
> * Test individual components before integrating them into the complete workflow
> * Set up environment variables for settings that differ between environments
> * Create versions after completing significant resource configurations

**2. Create Process Definitions**

Process definitions are the core of your application, defining the user journey and business logic:

* Navigate to the **Processes** section
* Click **+ New Process** to create a new process
* Use the BPMN editor to design your process flow
* Configure actions, forms, and integration points

> [card] [Learn more about Process Definitions](../managing-a-project-flow/creating-a-new-process-definition)

**3. Design User Interfaces**

Create the screens and components users will interact with:

* Open the UI Designer from a User Task node in your process, or design screen flows in the **UI Flows** section
* Create screens for each user-facing step in your processes
* Configure forms, buttons, and other interactive elements
* Design responsive layouts for different device types

**4. Configure Integrations**

Set up connections to external systems and services in the **Integrations** section:

* Define data sources for the systems you connect to (REST APIs, databases, email, and more)
* Configure authentication and security settings
* Create workflows that orchestrate calls to external systems
* Test connections to ensure proper data exchange

**5. Set Configuration Parameters**

Define environment-specific variables:

* Add parameters that will differ between environments
* Set default values for development
* Mask sensitive information like passwords and API keys
* Organize parameters by functional area

![Configuration Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/config_params.png)

## Project lifecycle management

After configuring your project resources, you'll need to prepare it for deployment through versioning and building:

**1. Create Project Version**

When your project configuration reaches a milestone:

* Create a version to capture the current state
* You can create multiple versions and commit them before creating a build
* Versions can be modified until they are committed
* Committed versions are locked and cannot be changed

**2. Create Build**

To deploy your project to an environment:

* Create a build from any committed version
* Builds are immutable and serve as deployable packages
* Each build contains exactly one version of a project
* Once a build is created, its contents (processes, enumerations, substitution tags, integrations) cannot be edited - you'll need to create a new project version for changes

  <video />

**3. Deploy Build**

Deploy your build to the target environment:

* Development for testing
* QA for validation
* Production for end-users

> [!NOTE]
>
> Configuration parameters set for specific environments will be applied during deployment.

## Best practices

> [!WARNING]
>
> Projects contain all your process definitions and resources. Use clear naming conventions and proper documentation to maintain organization as your project grows.

* **Project Naming**: Use clear, descriptive names that reflect business purpose
* **Project Scope**: Keep projects focused on specific business domains
* **Documentation**: Add comprehensive descriptions to your project and components
* **Version Control**: Make effective use of the built-in versioning capabilities
* **Configuration Management**: Use environment variables for deployment-specific settings
* **Dependency Management**: Carefully manage library dependencies to avoid conflicts
* **Testing**: Validate changes in development before promoting to production

## Next steps

After creating your project, you can proceed to:

> [card] [Create Process Definition](../managing-a-project-flow/creating-a-new-process-definition)
>
> Define your first business process within the project

## Frequently asked questions

> [accordion] How do I create a new version of a project?
>
> To create a new version, navigate to the project dashboard, select "Create New Version," and make any changes. Once finalized, commit the version to lock it.

> [accordion] What happens when I create a build?
>
> Creating a build captures a snapshot of the project version, consolidating resources into a single deployable package. Builds are immutable and cannot be edited once created.

> [accordion] Can I manage multiple localizations within a project?
>
> Yes, projects support multiple locales. You can define regional settings, such as date formats and currencies, to cater to different environments.
>
> > [card] [Learn more about Localization](../../building-blocks/ui-designer/localization-and-i18n)

> [accordion] What is the difference between a Project Version and a Build?
>
> A Project Version is a snapshot of resources and configurations that can be modified, tracked, and rolled back. A Build is a deployable package created from a committed version, and it is immutable once deployed.

> [accordion] How do I add a library as a dependency?
>
> Go to your project settings, navigate to dependencies, and select the desired library. Choose the build you want to use, and its resources will be accessible within your project.

> [accordion] Can I make changes to a deployed build?
>
> No, a build is immutable. To make changes, modify the project version, create a new version, and deploy a new build.

> [accordion] How do I ensure that a library update doesn't break my project?
>
> Use a controlled environment like Dev or UAT to test new builds of the library before updating the dependency in your main project. This allows you to validate changes and ensure they don't negatively impact your project.

> [accordion] What happens to resource versions when I update a dependency?
>
> When a dependency is updated to a newer build, any resources that were modified in the library will reflect the latest version. Projects have control over when to update, so older versions remain stable until the dependency is manually updated.


# Creating a user interface
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-user-interface

Learn how to design and configure user interfaces for your process flows using FlowX.AI Designer.

FlowX.AI allows you to create interactive user interfaces for your process flows without extensive coding. Using the UI Designer, you can configure screens with various components and navigation patterns to create intuitive user experiences.

![User Interface Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui.png)

Process Flow with User Tasks

## Understanding UI design in FlowX.AI

> [card] UI Design Concepts
>
> In FlowX.AI, user interfaces are primarily associated with **User Task** nodes in your process flow. Each User Task can represent a screen or part of a screen in your app. The UI Designer provides a visual editor where you can add, arrange, and configure UI components to create your desired interface.

> [card] [UI Designer Documentation](../../building-blocks/ui-designer/ui-designer)
>
> Comprehensive guide to the UI Designer and available components

> [card] [Navigation Areas](../../building-blocks/process/navigation-areas)
>
> Learn more about different navigation patterns and structures

## Creating a process with user interfaces

**1. Create a Process Definition**

1. Open **FlowX.AI Designer** and navigate to your project
2. Go to the **Processes** section and click **+ New Process**
3. Give your process a descriptive name and click **Create**

> [!TIP]
>
> Plan your user interface flow before starting. Consider how many screens you need and how users will navigate between them.

**2. Add Process Flow Nodes**

1. Add a **Start Node** to your process canvas
2. Add **User Task** nodes for each screen in your app
3. Connect the nodes in the sequence users will navigate through them
4. Add an **End Node** to complete your process

![User Interface Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui.png)

Process Flow with User Tasks

> [!NOTE]
>
> Each User Task node represents a screen or a significant UI interaction in your app. Design your process flow to match your intended user journey.

**3. Create a Navigation Area**

1. With your process open in edit mode, click the **Navigation** tab
2. Click the **+ Add** button to create a new navigation area
3. Select **Page** as the navigation type (or another type based on your needs)
4. Name your navigation area (e.g., "Main Application Page")
5. Assign the relevant User Task nodes to this navigation area

![Create Navigation Area](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui1.gif)

Creating a Navigation Area

> [!NOTE]
>
> **Available Navigation Area Types:**
>
> * **Stepper**: Breaks progress into logical, numbered steps for intuitive navigation
> * **Tab Bar**: Allows users to switch between different sections or views
> * **Page**: Displays full-page content for an immersive experience
> * **Modal**: Overlays that require user interaction before returning to the main interface
> * **Zone**: Groups specific navigation areas or tasks, like headers and footers
> * **Parent Process Area**: Supports subprocess design under a parent hierarchy

## Configuring the UI

All visual properties of UI elements and navigation areas are configured using the FlowX.AI UI Designer, which provides a visual editor for building your interfaces.

![UI Designer Location](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/where_ui1.png)
![UI Designer Access](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/where_ui2.png)

UI Designer Location

### Selecting navigation type

To begin, you need to define the type of navigation for your app:

**1. Configure Navigation Type**

1. In the UI Designer, go to the navigation configuration section
2. Select one of the following navigation types:
   * **Single page form**: For simple, one-page applications
   * **Wizard**: For multi-step processes with clear progression

![Navigation Type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui3.png)

Navigation Type Selection

> [!NOTE]
>
> This example uses the **Wizard** type, which is ideal for multi-step processes like applications or onboarding flows.

## Designing the first screen

Let's configure the first User Task node to create an engaging and functional screen:

**1. Open the UI Designer**

1. In your process diagram, select the first **User Task** node
2. Click the **UI Designer** button in the properties panel
3. This will open the visual UI Designer for this specific node

**2. Add a Card Component**

1. From the component palette, drag a **Card** component onto the canvas
2. The Card component will serve as a container for your form elements
3. Configure the card's appearance using the properties panel (size, padding, etc.)

**3. Add a Form Component**

1. Drag a **Form** component into the Card
2. Forms help organize inputs and handle data binding
3. Configure the form's properties as needed

**4. Add Input Fields**

1. Drag an **Input** component into the Form
2. Configure the input's properties:
   * Set a label (e.g., "Full Name")
   * Choose the input type (text, number, email, etc.)
   * Configure validation rules if needed
   * Set the data binding to store user input

![First Card UI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_card1.png)

First Card Design

**5. Add a Button with Action**

1. Drag a **Button** component into the Form
2. Configure the button text (e.g., "Continue" or "Next")
3. Set up the button's action to trigger process advancement

> [!NOTE]
>
> Before the button will work, you need to configure an action on the User Task node itself. This action will be triggered when the button is clicked.

![Save Data Action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui_save_data.png)

Save Data Action Configuration

### Testing the first screen

**1. Preview Your Screen**

1. Save your UI design
2. Start the process to test the UI
3. The Card with the Form and Input field should be displayed as configured

![Test First Screen](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/test_card_ui.gif)

Testing the First Screen

## Designing the second screen

Follow a similar process to design your second screen:

**1. Configure the Second User Task**

1. Select the second **User Task** node in your process
2. Open the **UI Designer**
3. Add a **Card** component
4. Add other UI components as needed (text, inputs, buttons, etc.)

![Second Card UI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/create_ui4.png)

Second Card Design

**2. Add Navigation Actions**

1. Add a button to submit the form or continue to the next step
2. Configure actions on the User Task node as needed
3. Consider adding a "Back" button if appropriate for your flow

## Testing the complete flow

Once you've configured all your screens, test the complete process flow:

![Test Complete Flow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/final_rez.gif)

Testing the complete flow

## Available UI components

FlowX.AI provides a rich set of UI components to create engaging interfaces:

> [card] Layout Components
>
> Cards, containers and grids for organizing content

> [card] Form Elements
>
> Inputs, checkboxes, radio buttons, selects, switches, sliders, segmented buttons and date pickers

> [card] Interactive Elements
>
> Buttons, links, tabs, and accordions for user interaction

> [card] Content Components
>
> Text, images, icons, and media elements for displaying information

> [card] Data Display
>
> Tables for showing structured data

> [card] Navigation
>
> Steppers, and pagination controls

> [card] Other
>
> Other components for building complex interfaces

## Best practices

> [!TIP]
>
> **When designing user interfaces:**
>
> * **Use consistent styling** across all screens for a cohesive user experience
> * **Group related inputs** within logical sections or cards
> * **Implement proper validation** to prevent errors and guide users
> * **Provide clear feedback** on actions with success and error messages
> * **Design with [accessibility](../../platform-deep-dive/accessibility)** in mind using proper labels and ARIA attributes
> * **Test your UI** on different screen sizes to ensure responsive design
> * **Keep navigation intuitive** with clear paths forward and back
> * **Use data binding** to maintain state across screens

## Next steps

After creating your user interface, you can:

> [card] [Moving a token backwards in the flow](../managing-a-project-flow/moving-a-token-backwards-in-a-process)
>
> Learn how to move a token backwards in the flow


# Exporting and importing projects
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition

Learn how to transfer projects between environments using the export and import functionality in FlowX.AI Designer.

Moving projects between environments is a common requirement in enterprise software development. FlowX.AI provides export and import functionality to help you promote your projects from development to testing and production environments.

> [!NOTE]
>
> In recent versions of FlowX.AI, the export/import functionality has moved from the process definition level to the project level, allowing for more comprehensive and consistent transfers between environments.

> [!NOTE]
>
> Export and import are driven from the **Designer UI**. There is no public REST API to import a process definition or project programmatically — drive the workflow through the Designer.

## Project vs. process export/import

> [card] Project-Level Operations
>
> Modern versions of FlowX.AI use **project-level** export and import operations rather than process-level ones. This approach ensures that the resources and configurations belonging to the project are transferred together, maintaining the integrity of your application.

### How library dependencies are handled

Whether the libraries a project depends on travel with the export depends on what you export:

* **Project version export**: records library dependencies only as **references** to specific library builds. The libraries themselves are not included, so the target environment must already contain those library builds — otherwise the import succeeds but the dependencies land as broken references.
* **Build export**: also **packages the builds of the libraries** the project depends on, including transitive dependencies. Importing the build imports those library builds as well; library builds that already exist in the target environment are skipped.

#### Version exports that bundle dependencies

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A project version export that targets the platform version your environment runs now packages the same content a build export does:

* **Library dependencies**: the builds of the libraries the project depends on are exported and packed into the version archive. On import, library builds that already exist in the target environment are reused, and the others are imported with the version.
* **Theme**: the project's default theme is included, unless it is the system theme. On import, the theme is created in the target environment only if it does not exist there yet. A theme that already exists there is left unchanged, because other project versions can use it.

A version export is therefore self-contained, and you no longer need to import the library builds into the target environment first.

If a library build cannot be exported, the version export fails and names the dependency that failed. If a bundled library build cannot be imported, the version import fails and is rolled back. Library builds that did import are kept, so a retry reuses them.

> [!NOTE]
>
> An export that targets an older LTS line, such as **5.9.x** or **5.1.x**, keeps the older format: library dependencies are recorded only as references and the theme is not included, because those platform versions cannot read the bundled content. Pre-stage the library builds in the target environment before you import such an export.

> [!NOTE]
>
> This documentation covers the updated project export/import approach. If you're using an older version of FlowX.AI that still handles exports at the process definition level, some details may differ.

## Exporting a project

You can export projects from the version details panel. This allows you to export specific committed versions with granular control over what's included in the export.

**1. Navigate to Version Details**

1. Open **FlowX.AI Designer** and go to the **Projects** section
2. Select the project you want to export
3. Navigate to the version details panel for the specific committed version you want to export

**2. Initiate Export**

1. In the version details panel, locate the **Export Version** button
2. Click **Export Version** to open the export dialog

![Export Version button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/export_version.png)

Export Version button in the Version Details panel

**3. Choose the target version and options**

In the **Export Version** dialog, set two things:

* **Target platform version** - the platform version running in the environment you'll import into. It defaults to **Current Version** (the version you're exporting from). To import into an environment on a different LTS line (for example, a 5.1.x environment), select that version here. The exported ZIP can only be imported into environments running the selected version. See [Cross-version export and import](#cross-version-export-and-import).
* **Include media file content** - toggle **ON** to bundle media assets (for example, images and documents) into the export package. Toggle **OFF** to export only the project structure and configuration, which produces a smaller file and a faster import.

> [!WARNING]
>
> Including media file content may significantly increase the export file size and the time required to import the version in another environment. Only include it if the target environment needs those assets.

![Target platform version selector](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/legal/export_version_modal.png)

Export Version dialog with the Target platform version selector

![Include media file content](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/include_media_file_content_Modal.png)

Include media file content option

**4. Complete the Export**

1. Click **Export** to generate the export package
2. The system generates a downloadable file containing your project version
3. Save this file to your local system

> [!TIP]
>
> Use a clear naming convention for your export files to help identify their contents later, such as `[project-name]_[version]_[environment]_[date].zip`.

> [!NOTE]
>
> For more information about versioning and managing project versions, see the [Versioning documentation](../../projects/managing-applications/versioning#exporting-versions).

> [!WARNING]
>
> **Knowledge Base stores are exported as definitions only.** A version export carries the Knowledge Base data-source configuration (system, endpoints, metadata keys), but not the store contents — uploaded documents and their indexed embeddings stay on the source workspace. After importing on another workspace or environment, the stores appear empty: re-upload and re-index the content there. The media file content option above covers media assets, not Knowledge Base content.

### Target version and export file name

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![Export Version dialog with the Target platform version dropdown open, listing 5.13 marked Current Version and the 5.9.x and 5.1.x LTS lines](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/export-version-target-platform.png)

In the **Export Version** and **Export Build** dialogs, **Target platform version** lists the platform version your environment runs by its version number, for example `5.13`, marked **Current Version** and pre-selected. The older LTS lines you can export for are listed as `5.9.x` and `5.1.x`. Keep the pre-selected version when the target environment runs the same platform version, or pick an LTS line for an older environment, as described in [Cross-version export and import](#cross-version-export-and-import).

The downloaded ZIP is named after the package it contains:

* **Version export**: `{project-name}_{version-id}_flowx{target-version}_{media}.zip`
* **Build export**: `{project-name}_{build-tag}_flowx{target-version}_{media}.zip`

`{version-id}` is the last 12 characters of the version ID, `{target-version}` is the target platform version you selected, and `{media}` is `media` or `no-media` depending on the **Include media file content** toggle. Characters in the project name other than letters, numbers, `.` and `-` are replaced with `-`. Exporting the same version or build with the same options always produces the same file name, so you can tell from the name alone which export files contain the same package.

### Exporting builds

You can also export builds directly from the **Builds** section. This is useful when you want to transfer a specific build (rather than a version) between environments.

**1. Navigate to Builds Section**

1. Open **FlowX.AI Designer** and go to the **Projects** section
2. Select your project and navigate to **Runtime** and then to the **Builds** section

**2. Select Build to Export**

1. Locate the build you want to export in the builds list
2. Click the **Export** icon (box with upward arrow) for the desired build

**3. Complete Export**

The build export follows the same process as version export, including the target platform version and media file content options. The exported build can be imported into other environments or workspaces.

> [!NOTE]
>
> Builds are immutable snapshots of committed project versions. When exporting a build, you're exporting a deployable package that can be directly used in runtime environments. For more information about builds, see the [Builds documentation](../../projects/runtime/builds).

## Importing a project

**1. Open the Projects section**

Open **FlowX.AI Designer** in the target environment and go to the **Projects** section.

**2. Open the Import menu**

Click the three-dots (kebab) menu at the top right of the Projects list and choose one of:

* **Import Version** — restores a project version (and its full version history) into the target environment. Use this when promoting work between environments.
* **Import Build** — imports a build (an immutable snapshot of a committed version) into the **Builds** section. Use this when promoting a deployable package.

The menu only shows the items you have permission for.

> [!TIP]
>
> You can also start an **Import Version** from inside an open project: open the **All Branches** view in the Version Details panel and click the upload icon in the panel header. This is functionally equivalent to **Import Version** from the Projects list.

**3. Select the .zip file**

The Designer opens your operating system's file chooser. Select the `.zip` you exported earlier and confirm.

**4. Wait for the import to complete**

The import runs asynchronously. A toast notification confirms success or reports an error. There is no in-app preview, no confirmation dialog, and no manual conflict-resolution step between picking the file and the import completing — see [Import scenarios](#import-scenarios) below for what happens when the target environment already has the project.

> [!WARNING]
>
> If the target environment has versions on the same lineage as the import file, those versions are silently stashed during the import. There is no preview or confirmation step before this happens. See [Existing project with additional versions](#existing-project-with-additional-versions) for the consequences and the recommended workflow.

## Import scenarios

When importing a project, you may encounter different scenarios depending on whether the project already exists in the target environment and what versions are present.

### New project import

> [card] New project
>
> If the project does not exist in the target environment, it will be created with all its resources, and you'll see all versions from the export file.

### Existing project with no additional versions

> [card] Update Existing Project
>
> If the project exists but doesn't have versions beyond those in the import file, the system will update the existing project with any changes from the import file.

### Existing project with additional versions

Importing restores the version history and parent–child relationships exactly as they exist in the import file. **There is no merge functionality on import.**

> [card] Versions become stashed, not merged
>
> If the target environment has versions on the same lineage that are not in the import file, those versions become **stashed**: they remain in the database but are no longer accessible in the Designer. There is no UI to retrieve stashed versions — recovery requires direct database intervention by FlowX support and is not always feasible.

> [!WARNING]
>
> **Importing on top of diverged work is destructive.** If two environments committed different versions on the same branch, importing one over the other stashes the target version. The previous content cannot be restored from the Designer. Always export the target project before importing on top of it, and contact FlowX support if recovery is needed.

> [!TIP]
>
> **Recommended workflow:** Use a separate branch per environment. On import, new branches are added alongside existing ones instead of overwriting versions on a shared lineage.

### Cross-workspace import

You can import the same project into multiple workspaces on the same environment. This removes the previous limitation that restricted a project (identified by its UUID) to exist in only one workspace per environment.

> [card] Cross-Workspace Import
>
> Import a project build (and optionally a version) into a different workspace on the same environment. The imported project maintains its own independent lifecycle with separate active policies and access controls.

**Key behaviors for cross-workspace import:**

| Aspect | Behavior |
| - | - |
| **Lifecycle** | The imported project has its own independent lifecycle in the new workspace |
| **Active Policy** | The imported build is automatically set as the active policy, regardless of what was active in the original workspace |
| **Access Controls** | Separate access controls and policies are defined for each workspace |
| **No Impact on Original** | The import does not affect the original project's settings, policies, or process instances |
| **User Access** | Workspace users must be granted appropriate project rights (for example, project viewer) to interact with the imported project |
| **Process Instances** | Process instances are workspace-specific; the imported project starts with no instances until processes run in the new workspace |
| **Database** | Projects across workspaces on the same environment share the same database |

> [!TIP]
>
> **Use case**: Use this feature to represent different operational environments (UAT, Staging, Pre-production) as separate workspaces on a single FlowX deployment, reducing infrastructure and DevOps costs.

> [card] [Workspaces documentation](../../projects/workspaces#cross-workspace-project-import)
>
> Learn more about cross-workspace project management

***

## Cross-version export and import

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.0**
>
> Environments are not always on the same platform version. During a phased upgrade, lower environments (dev, test) are usually upgraded first, while upper environments (staging, production) stay on the previous version until the upgrade is validated and scheduled. Cross-version compatibility lets you export a project version or build from a higher platform version in a format that an environment running a **lower** platform version can import — so you can still ship fixes to an environment that hasn't been upgraded yet.

When a problem is found in an upper environment during an upgrade window, the source-of-truth project version often already lives on an upgraded environment. Cross-version export and import lets you deliver the fix to the older environment without rolling back the upgrade on lower environments or rushing the upgrade of the upper ones.

An older-line export always imports into a newer line: a 5.1.x export imports into any 5.9.x environment with no extra steps. Going the other way is the case that needs handling — a newer-line export reaches an older line only when it is produced **targeting** that older version, which is what this section covers.

When a 5.1.x export is imported into 5.9.x, every `FLOWX_ROLE` reference in its processes, including swimlane roles and UI hide and disable rules, is renamed to `User`, the default runtime role in 5.9.x. `User` is a role, not the **Users Group** end-user group. After the import, check which end-user groups hold the `User` role in [runtime authorization](/5.9/setup-guides/access-management/runtime-authorization#two-ways-to-grant-access) so the right end users can start the imported processes.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.4**
>
> When you import a project build or version exported from an older line, the imported theme is completed from the destination environment's system theme. Theme components and tokens introduced after the export was taken are filled in, so newer components are not left unthemed. Values already set in the exported file are never overwritten, at any depth, so your customizations survive.
>
> Icons are not carried in the export file. Theme components reference them by key, and those assets are seeded per environment, so the destination environment supplies them.

Cross-version compatibility is supported **between LTS lines** — currently the **5.1.x** and **5.9.x** lines — and is patch-agnostic in each supported direction: any 5.1.x export imports into any other 5.1.x environment and into any 5.9.x environment, and a 5.9.x export **that targets 5.1** imports into any 5.1.x patch. The target version is chosen at export time; a 5.9.x export left on its native 5.9.x version cannot be imported into 5.1.x.

### When to use it

Use cross-version export and import when **all** of the following are true:

* Lower environments (for example, dev and test) have already been upgraded to a newer platform version.
* One or more upper environments (for example, staging or production) are still on an older platform version.
* A fix or change must be delivered to an upper environment before it is upgraded.

### How incompatible content is handled

A cross-version export works only when the exported content stays within what the **target (lower) platform version** can understand. When you export targeting an older version, resources whose type doesn't exist on that version are handled automatically:

* **Incompatible resources are excluded** from the export and from the manifest, rather than failing the export.
* **Resources that reference an excluded resource are still exported.** Their usages are kept as-is and point to the now-missing resource; references are not removed and dependents are not cascade-excluded.
* **The excluded resources are listed** in a separate `manifest_excluded.json` file in the archive. Kept resources stay in `manifest.json`. The excluded-list file is informational only and is ignored on import.
* **The export still imports successfully** into the older environment.

> [!WARNING]
>
> Keep the fix on the upgraded environment limited to functionality that also exists on the older target version. Resource types, properties, or behaviors introduced after the target version cannot be carried over — they are excluded from the export and must wait until the target environment itself is upgraded.
>
> As a rule of thumb, the **lowest** platform version in the export/import path defines the set of functionality usable for that fix. As long as the fix uses only features available on the target version, the round trip is lossless.

### Example: hotfix to production on an older version

Consider a phased upgrade where the lower environments are already on 5.9 but production is still on 5.1:

| Environment | Platform version |
| - | - |
| dev | 5.9 |
| uat | 5.9 |
| production | 5.1 |

A defect is reported in production (still on 5.1) and must be fixed before production is upgraded. The source-of-truth project version now lives on the upgraded dev/uat environments.

**1. Apply the fix on the upgraded environment**

Make the change in the project version on dev/uat (5.9), keeping it strictly within functionality that also exists on 5.1 — no resources, nodes, actions, or fields introduced after 5.1.

**2. Validate the fix**

Test the change on the upgraded environment as usual.

**3. Export targeting the lower version**

Export the project version or build targeting 5.1 so the artifact is produced in a format the 5.1 runtime can import. Anything incompatible with 5.1 is excluded and listed in `manifest_excluded.json`, so you can review or rework it before proceeding.

**4. Import into production**

Import the compatible artifact into the 5.1 production environment. The fix is applied without upgrading production or rolling back the upgrade on dev/uat.

Provided the fix uses only functionality available in 5.1, no information is lost in the round trip. Anything that depends on post-5.1 functionality cannot be carried over and must wait until production is upgraded.

### Limitations

* A cross-version export is only as capable as the **target** version. Newer functionality cannot be downgraded into an older runtime.
* This mechanism delivers fixes to a not-yet-upgraded environment during an upgrade window. It is not a substitute for upgrading the upper environments.
* Always validate the imported build on the target environment, since the fix was authored and tested on a different platform version.

***

## Best practices for export/import

> [!TIP]
>
> **When transferring projects between environments:**
>
> * **Plan your promotion path** - Establish a clear workflow for moving from development to testing to production
> * **Use consistent naming** - Name your projects, versions, and export files consistently across environments
> * **Pre-stage library dependencies for version imports** - On FlowX.AI 5.9.x, and for any export that targets 5.9.x or 5.1.x, a project **version** export records its library dependencies only as references to specific library builds; unlike a build export, it does not bundle the libraries themselves (see [Version exports that bundle dependencies](#version-exports-that-bundle-dependencies) for the SaaS behavior). Make sure those library builds already exist in the target environment before importing a version, or the import succeeds but the dependencies land as broken references.
> * **Test after import** - Always validate your project in the new environment after import
> * **Version control** - Consider using external version control systems in addition to FlowX.AI's built-in versioning
> * **Incremental imports** - For large projects, consider importing incrementally rather than all at once
> * **Export the target project before importing** - Importing on top of diverged work stashes the target version, and stashed versions cannot be recovered from the Designer. Exporting the target first gives you a recovery point.

## Common issues and solutions

> [accordion] Version Compatibility
>
> **Issue**: An export from a newer environment contains resources that the older target environment does not support.
>
> **Solution**: Export **targeting** the older platform version by selecting the target version when you export. A cross-version export automatically excludes resources that the target version can't interpret and records them in a separate excluded-resources file inside the archive. The export imports successfully; review the excluded list and adjust any resources that referenced them. A 5.9.x export left on its native version cannot be imported into 5.1.x. See [Cross-version export and import](#cross-version-export-and-import).

> [accordion] Missing Dependencies
>
> **Issue**: Imported project references libraries or resources not present in the target environment.
>
> **Solution**: Import the required library builds into the target environment before importing the project version (on 5.9.x, or when the export targets 5.9.x or 5.1.x, a version archive references library builds but does not contain them; a build archive does include them), or update the project to use libraries already available in the target. Dependencies that can't be resolved on import are flagged as broken references, and resources that use them become broken links.

> [accordion] Conflict Resolution
>
> **Issue**: Conflicts between imported versions and existing versions.
>
> **Solution**: Carefully review the differences and decide whether to overwrite or preserve existing versions. Consider merging changes manually for complex conflicts.

> [accordion] Environment-Specific Configurations
>
> **Issue**: Hard-coded environment-specific values in processes or configurations.
>
> **Solution**: Use environment variables and configuration parameters instead of hard-coded values to ease transitions between environments.

## Next steps

After importing your project, you should:

> [card] Verify Project Resources
>
> Ensure all process definitions, UI components, and other resources imported correctly

> [card] Configure Environment Settings
>
> Adjust any environment-specific settings for the new environment

> [card] Test Process Flows
>
> Validate that all process flows work as expected in the new environment

> [card] Create a Build
>
> Create a build from your imported project for deployment


# Handling decisions in the flow
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/handling-decisions-in-the-flow

Learn how to implement conditional branching in your processes using exclusive gateways to create dynamic, decision-driven workflows.

Business processes often require making decisions based on data and conditions. FlowX.AI's exclusive gateway nodes allow you to create branching paths in your process flow, directing the execution based on specific conditions and business rules.

![Exclusive Gateway](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/node/gateway_exclusive.png#center)

Exclusive Gateway Visualization

## What is an exclusive gateway?

> [card] Exclusive Gateway
>
> An exclusive gateway (also known as an XOR gateway) creates conditional branches in your process flow. It directs the process token to exactly one of the outgoing paths based on evaluated conditions. Think of it as an "if-then-else" decision point in your process.

> [card] [Exclusive Gateway Documentation](../../building-blocks/node/exclusive-gateway-node)
>
> Complete reference for exclusive gateway configuration

> [card] [Business Rules](../../building-blocks/actions/business-rule-action/business-rule-action)
>
> Learn more about implementing decision logic

## How exclusive gateways work

![Exclusive Gateway Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/xclsv_mapf.png)

Process Flow with Exclusive Gateway

Exclusive gateways function as decision points in your process:

1. When the process flow reaches an exclusive gateway, it evaluates conditions associated with each outgoing path
2. The first condition that evaluates to `true` determines which path is taken
3. Only one path is followed, even if multiple conditions could evaluate to `true`
4. A default path can be specified to be taken if no conditions are met

> [!NOTE]
>
> Best practice is to always provide a default path to ensure your process doesn't get stuck if none of the specified conditions are met.

## Creating a flow with exclusive branches

**1. Create or Open a Process Definition**

1. Open **FlowX.AI Designer** and navigate to your project
2. Go to the **Processes** section and select your process or create a new one
3. Click the **Edit Process** button to open the Process Designer

**2. Add Basic Flow Elements**

1. Add a **Start Node** to your process canvas (if creating a new process)
2. Add a node before your decision point (typically a task or user task node)
3. Ensure the necessary data for your decision is available in the process at this point

> [!TIP]
>
> The decision conditions will evaluate data that's already in your process context, so make sure any required data is collected or calculated before reaching the gateway.

**3. Add the Decision Gateway**

1. From the node palette, drag an **Exclusive Gateway** node onto your canvas
2. Connect your previous node to this gateway
3. Give your gateway a descriptive name that indicates its decision purpose (e.g., "Evaluate Credit Score")

> [!WARNING]
>
> You must connect all outgoing paths from the exclusive gateway before configuring the decision conditions.

**4. Create Outgoing Paths**

1. Add the task nodes that will be the targets for each decision branch
2. Connect the exclusive gateway to each of these nodes using sequence flows
3. Name each sequence flow to indicate the condition (e.g., "Premium Card Path", "Standard Card Path")

![Gateway Condition Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/mapf_gateway_condition.png)

Example of Gateway Condition Configuration

**5. Configure Decision Conditions**

1. Select one of the sequence flows (arrows) from the gateway
2. In the properties panel, navigate to the **Condition** section
3. Select a **scripting language** from the dropdown (e.g., MVEL, JavaScript)
4. Enter your condition expression, for example:

```javascript theme={"dark"}
input.get("application.client.creditScore") >= 700
```

5. Repeat for each outgoing path with the appropriate condition:

```javascript theme={"dark"}
input.get("application.client.creditScore") < 700
```

> [!NOTE]
>
> Conditions are evaluated in the order they appear in the Designer. The first condition that evaluates to `true` determines the path taken, so order matters!

**6. Add Converging Gateway (Optional)**

If your branches need to converge back to a single flow:

1. Add another **Exclusive Gateway** after your branch tasks
2. Connect each branch endpoint to this converging gateway
3. Continue the process flow from this gateway

> [!NOTE]
>
> A converging exclusive gateway doesn't require conditions since it's merely joining paths rather than splitting them.

**7. Complete the Process Flow**

1. Add any additional nodes needed after the decision branches
2. Ensure your process eventually reaches an **End Node**
3. Save your process definition

## Condition expression examples

Here are some example condition expressions for different decision scenarios:

> [accordion] Numeric Comparisons
>
> ```javascript theme={"dark"}
> // Check if age is over 18
> input.get("customer.age") >= 18
>
> // Check if balance is sufficient
> input.get("account.balance") > input.get("transaction.amount")
>
> // Check if score is within a range
> input.get("application.score") >= 600 && input.get("application.score") < 750
> ```

> [accordion] String Comparisons
>
> ```javascript theme={"dark"}
> // Check customer type
> input.get("customer.type") == "premium"
>
> // Check if country is in EU
> ["DE", "FR", "IT", "ES"].contains(input.get("customer.country"))
>
> // Check if name starts with specific letters
> input.get("customer.lastName").startsWith("A")
> ```

> [accordion] Boolean logic
>
> ```javascript theme={"dark"}
> // Check multiple conditions with AND
> input.get("customer.verified") == true && input.get("customer.active") == true
>
> // Check multiple conditions with OR
> input.get("application.status") == "pending" || input.get("application.status") == "review"
>
> // Complex condition with nested logic
> (input.get("customer.age") >= 21 || (input.get("customer.age") >= 18 && input.get("customer.parentalConsent") == true)) && input.get("customer.verified") == true
> ```

> [accordion] Date Comparisons
>
> ```javascript theme={"dark"}
> // Check if membership is expired
> new java.text.SimpleDateFormat("yyyy-MM-dd").parse(input.get("membership.expiryDate")).before(new java.util.Date())
>
> // Check if account is older than 1 year
> dateDiffInDays(new java.text.SimpleDateFormat("yyyy-MM-dd").parse(input.get("account.openDate")), new java.util.Date()) > 365
> ```

## Best practices

> [!TIP]
>
> **When implementing decision logic:**
>
> * **Use clear, descriptive names** for gateways and sequence flows to document the decision logic
> * **Keep conditions simple and focused** on a single aspect of the decision
> * **Ensure conditions are mutually exclusive** when possible to avoid ambiguity
> * **Always provide a default path** to handle unexpected scenarios
> * **Test each decision branch** with various input data to verify correct routing
> * **Document complex decision logic** in the process documentation or node descriptions
> * **Consider using business rule actions** before the gateway for complex evaluations

## Common patterns

> [card] If-Then-Else
>
> The simplest decision pattern with two outcomes - a condition is either met or not met

> [card] Multi-Choice
>
> Multiple conditions evaluated in sequence, with one path chosen based on the first match

> [card] Approval Flow
>
> Branching based on approval status, typically with approve/reject/review paths

> [card] Eligibility Check
>
> Evaluation of multiple criteria to determine if a process can proceed

## Next steps

After implementing decision logic in your process, you can:

> [card] [Implement Parallel Processing](../managing-a-project-flow/adding-more-flow-branches)
>
> Learn how to create parallel process branches with parallel gateways


# Moving a token backwards in a process
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process

Learn how to implement "Back" functionality in your processes to allow users to return to previous steps while preserving data.

While most process flows progress in a forward direction, FlowX.AI provides capabilities for moving backwards in a process flow. This feature allows users to revisit previous steps without losing their progress or data, enhancing the flexibility and user-friendliness of your apps.

![Back Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/allow_back_action.png)

Back Action Configuration

## What is token resetting?

> [card] Token Concept
>
> In FlowX.AI, a **token** represents the current position within a process instance. It moves from one node to another as the process executes, carrying process data and state information. Normally, tokens advance forward through the process flow, but sometimes you need to allow users to go back to previous steps.

> [card] [Process Tokens](../../building-blocks/token)
>
> Learn more about tokens and how they drive process flow

> [card] [Process Instances](../../projects/runtime/active-process/process-instance)
>
> Understand how processes execute in FlowX.AI

## Why use backwards navigation?

> [card] User Experience
>
> Allows users to correct mistakes or review previous inputs without starting over

> [card] Process Flexibility
>
> Creates more natural and less rigid process flows that adapt to user needs

> [card] Data Preservation
>
> Maintains important data while allowing selective changes to specific fields

> [card] Reduced Abandonment
>
> Decreases process abandonment rates by allowing users to navigate freely

## How token resetting works

When a user navigates backwards in a process:

1. The current token is marked as **aborted**
2. A **new token** is created at the target node (the previous step)
3. Data is selectively copied from the original token to the new one
4. Any subprocesses started between the original and new positions are aborted
5. The process continues from the reset position with the new token

> [!NOTE]
>
> The token can only be reset to specific actions on specific nodes that have been configured to allow backwards navigation.

## Configuring backwards navigation

Back navigation is configured at two levels: the **node** (can users return to this step at all?) and one of its **actions** (what do users re-execute when they return, and what happens to the data?).

**1. Identify target steps**

Determine which user tasks users should be able to return to. Typically, these are:

* Form submission steps
* Points where users might need to correct previous inputs
* The beginning of logical sections in your process

**2. Turn on Can go back? on the nodes**

1. Select the user task node
2. In the node configuration, toggle **Can go back?** **ON**

As the token advances through the process, each node with **Can go back?** turned on is recorded as a valid return point for that process instance. A node with it turned off cannot be returned to.

**3. Turn on Allow back to this action**

1. On the target node, add or edit a **Manual** action (typically the action that saves and submits that screen's data)
2. In the action configuration, under **Navigation**, toggle **Allow back to this action** **ON**

![Back Action Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/allow_back_action.png)

Back Action Configuration

> [!NOTE]
>
> **Allow back to this action** is available only for actions with the **Manual** trigger. When a mandatory action with this option runs, the engine saves a snapshot of the process data, so the data can be restored if the user later returns to this step.

> [!WARNING]
>
> Only configure "back" functionality on actions that make logical sense as return points in your process. Too many back points can make process state management complex.

**4. Configure data handling**

Turning on **Allow back to this action** reveals the **Back in steps** section. The **When returning to this action, reset process data** toggle decides what happens to process data when the user comes back:

* Toggle **OFF** (default): the process keeps its current data. Use **Remove the following objects from current state** to list process keys that should be deleted when the user navigates back.
* Toggle **ON**: the process data is restored to the snapshot taken when this action first ran. Use **Copy the following objects from current state** to list process keys that should keep their current values instead of being restored.

> [!TIP]
>
> Generally, keep contextual or reference data and reset only the data related to the step being revisited.

**5. Let users navigate back from the process navigation**

Users trigger back navigation from the rendered navigation itself. There is no separate Back button to configure:

* In a **Stepper** navigation area, completed steps become clickable. Clicking an earlier step returns the user to it.
* In a **Single Page Form** layout with accordion cards, users can reopen a previous card.

After returning, the user adjusts the data and resubmits that step's own action. The engine detects that a back-enabled action from an earlier node was executed, resets the token, and the UI re-renders from that step.

Users can return to any earlier back-enabled step, not only the immediately previous one: jumping directly from step 4 to step 2 works as long as step 2 is a valid return point.

> [!WARNING]
>
> A **Button** on the current screen cannot trigger back navigation: the button's **Node Action** event handler only lists actions belonging to the button's own node, and there is no dedicated Back action type. Back navigation is available only through the navigation components described above.

> [!NOTE]
>
> On mobile, user tasks rendered inside a single Modal navigation area get a built-in back control between them. See [Navigation best practices](../../building-blocks/process/navigation-best-practices).

![Token Reset Animation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/pf_moving_token_bw.gif)

Back Navigation in Action

## Use cases for backwards navigation

> [accordion] Multi-Step Forms
>
> In applications with multi-step forms or wizards, backwards navigation allows users to review and edit their inputs across different steps before final submission.

> [accordion] Decision Correction
>
> When users make selections that lead down specific process paths, back functionality lets them change their mind and explore alternative options.

> [accordion] Error Correction
>
> If validation occurs after a form submission and errors are found, users can navigate back to fix issues while preserving other valid inputs.

> [accordion] Process Review
>
> In complex workflows like loan applications or onboarding processes, users often need to review previous sections before completing the process.

## Best practices

> [!TIP]
>
> **When implementing backwards navigation:**
>
> * **Be selective** about which nodes allow back functionality
> * **Consider data dependencies** between steps to avoid inconsistent states
> * **Provide clear UI indicators** for steps users can navigate back to
> * **Test thoroughly** to ensure data is properly preserved or reset
> * **Consider subprocess implications** as they will be aborted during reset
> * **Document back navigation points** for easier maintenance
> * **Use clear step labels** so users recognize which steps they can return to

## Technical considerations

> [!WARNING]
>
> **Keep in mind these technical aspects when implementing back functionality:**
>
> 1. **Performance Impact**: Token resetting involves creating new tokens and copying data, which may impact performance in complex processes
> 2. **Subprocess Handling**: Any subprocesses active between the current and target positions will be aborted
> 3. **Data Consistency**: Ensure your data model can handle partial updates without creating inconsistencies
> 4. **Action Sequencing**: When the user returns to a step whose back-enabled action is optional, the engine re-runs that node's mandatory actions. Actions that produce a different output on a second run (for example, calls to external systems) can behave unexpectedly, so review what re-executes on return


# Initiating/starting processes
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/managing-a-project-flow/starting-a-process

Learn the different methods for starting process instances in FlowX.AI, including user interaction, automated triggers, and system integration options.

Once you've designed your process definitions, you'll need to know how to start process instances. FlowX.AI provides multiple ways to initiate processes, from manual user-triggered starts to fully automated system-initiated flows.

> [card] [User Interface](#starting-a-process-via-user-interface)
>
> The most common way to start processes through user interaction

> [card] [Kafka Messages](#starting-a-process-via-kafka)
>
> Start processes through Kafka events from other systems

> [card] [Timer Events](#timer-start-event)
>
> Schedule processes to start automatically at specific times

> [card] [Message Events](#message-catch-start-event)
>
> Trigger processes through message events from other processes

> [card] [Email Triggers](#email-and-webhook-triggers)
>
> Start processes automatically when an email arrives in a monitored inbox

> [card] [Incoming Webhooks](#email-and-webhook-triggers)
>
> Start processes from external systems through HTTP POST requests

## Starting a process via user interface

> [!WARNING]
>
> Manual Start using start parameters (JSON data) are limited to 1MB

When starting a process manually via the **FlowX Designer UI**, you’ll be prompted to enter a JSON payload (in the "JSON Object" editor). This is subject to the same infrastructure limits as any other process start.

* Payloads must be **under 1MB** total
* If exceeded, the request will fail with:

  ```http theme={"dark"}
  413 Content Too Large
  ```

![Start Process Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_params.png)

Start Process JSON input in Designer

### Affected layers

| Layer | Limit | Notes |
| - | - | - |
| NGINX/Ingress | 1MB (default if not configured) | `client_max_body_size` |
| Kafka → Runtime bridge | \~1MB total (default if not configured) | Applies when starting via Kafka too |

### Tips

For larger inputs, consider (as last resort, not recommended) increasing the limits for the affected layers.

## Starting a process via Kafka

One of the most effective ways to initiate processes is through Kafka messaging, which allows systems to communicate and trigger processes without direct user interaction.

**1. Access Your Project**

1. Open **FlowX.AI Designer** and navigate to your project
2. Select an existing process definition or create a new one that will send the Kafka message

**2. Add a Send Message Task**

1. Add a **Send Message Task** node to your process flow
2. Attach a **Kafka Send Action** to this node

> [!TIP]
>
> This task will send the message that initiates another process. You can place it at any appropriate point in your process flow.

**3. Configure the Kafka Topic**

1. In the Kafka Send Action configuration, specify the topic linked to the `KAFKA_TOPIC_PROCESS_STARTBYNAME_IN` environment variable
2. This variable is shared between the **application-manager** and **runtime-manager** deployments

![Process Start Topic Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_process_by_name_topic.png)

Process Start Topic Configuration

> [!NOTE]
>
> To verify the topic in FlowX Designer, navigate to: **Platform status → FlowX Components → application-manager-mngt -> kafkaTopicHealthCheckIndicator → details → configuration → topic → process → start-by-name**
>
> ![Topic Verification](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/topic_kafka.png)
>
> Topic Verification

**4. Add Message Content**

Add any required data in the message body that should be passed to the new process:

```json theme={"dark"}
{"test": "something"}
```

> [!NOTE]
>
> This data will be available to the process being started, providing it with initial context or parameters.

**5. Respect Payload Size Limits**

> [!WARNING]
>
> **Payload Size Must Be Under 1MB**: All Kafka-triggered process starts go through the runtime HTTP API, which enforces strict 1MB payload limits.

#### What does this mean?

* The `variables` field in the Kafka message **must not exceed 1MB**
* This includes base64 or pretty-printed formats

#### Why?

These limits are enforced across:

| Layer | Limit | Description |
| - | - | - |
| NGINX/Ingress | 1MB | `client_max_body_size` |
| Runtime Manager (Undertow) | 1MB | `max-http-post-size` |
| Kafka Process Start | \~1MB total | Translates into a REST call internally |

#### Recommendations:

* If absolutely required, increase `max-http-post-size` via:

```yaml theme={"dark"}
server:
  undertow:
    max-http-post-size: 2MB
```

**6. Configure Required Headers**

1. Expand the **Advanced Configuration** section
2. In the headers section, add these required headers:
   * `Fx-Organization-Id`: Organization UUID for the target deployment
   * `Fx-Workspace-Id`: The UUID of the workspace where the process should run
   * `Fx-AppId`: The ID of the project (application) where the process resides
   * `Fx-ProcessName`: The name of the process you want to start
   * `jwt`: Your JWT token for authentication

![Headers Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_process_by_name_headers.png)

Headers Configuration

The headers should look something like this:

```json theme={"dark"}
{
  "Fx-Organization-Id": "26ef7b5f-b463-4375-88c8-aaaaaaaaaaaa",
  "Fx-Workspace-Id": "00000000-0000-0000-0000-000000000001",
  "Fx-AppId": "afcc6452-f50e-4d95-ae3b-6b35caed68bd",
  "Fx-ProcessName": "test_kafka",
  "jwt": "your_jwt"
}
```

> [!TIP]
>
> **Don't know where to find these values?** Check the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for step-by-step instructions on locating Application IDs, Process Names, JWT tokens, and more.

> [!WARNING]
>
> Messages missing `Fx-Organization-Id` are rejected immediately with a non-retryable `MissingKafkaHeaderException`. Without an active policy and proper authentication, the process may not start even if the Kafka message is otherwise correctly configured.

**7. Test and Monitor**

1. Run your process to send the Kafka message
2. To monitor the results, you can use tools like AKHQ to check the response on the `KAFKA_TOPIC_PROCESS_STARTBYNAME_OUT` topic

![Kafka Response Monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-11%20at%2017.33.58.png)

Kafka Response Monitoring

## Timer start event

Timer Start Events allow you to schedule processes to start automatically at defined times or intervals, enabling automated workflows without manual intervention.

**1. Configure a Process with Timer Start**

1. Open **FlowX.AI Designer** and navigate to your project
2. Select an existing process definition or create a new one
3. Add a **Start Timer Event** to your process instead of a regular Start node

![Timer Start Event Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_timer_process.png)

Timer Start Event Configuration

**2. Configure Timer Settings**

Configure the timer according to your requirements:

1. **Date**: Set a specific date and time for the process to start
2. **Cycle**: Configure a recurring schedule, either as an ISO 8601 repeating interval or as a Spring cron expression (select **ISO** or **Cron** next to the **Definition** label)

A Timer Start Event offers only these two timer types. **Duration** is available on intermediate and boundary timer events, not on start events.

> [!WARNING]
>
> Starting processes through registered timers requires sending a process start message to Kafka, which needs a service account and authentication. See [Service Accounts](../../../setup-guides/access-management/configuring-an-iam-solution#scheduler-service-account) for details.

For more detailed information about Timer Start Events, refer to the [Start Timer Event](../../building-blocks/node/timer-events/timer-start-event) documentation.

## Message catch start event

Message Catch Start Events allow one process to initiate another through message-based communication, creating dependencies and workflows between processes.

**1. Configure the Sender Process**

1. Open **FlowX.AI Designer** and create or edit the process that will send the message
2. Add a **Message Throw Intermediate Event** node at the point where you want to trigger the other process
3. Configure data that will be used for correlation (e.g., a key value like 'key1')

![Correlation Data Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/correlation_data.png)

Correlation Data Configuration

4. Configure the message correlation in the node properties:

![Message Correlation Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/message_correlation.png)

Message Correlation Configuration

**2. Configure the Receiver Process**

1. Create or edit the process that should be started by the message
2. Add a **Start Message Catch Event** node as the starting point
3. Configure the node with:
   * The same message name used in the throw event (e.g., 'start\_correlation')
   * A **Process Key** where the message data is stored in the started process

> [!NOTE]
>
> A Message Start Event has no **Correlation Key** field. The correlation value set on the throw event must not be empty, and the receiver process doesn't start again while an instance started with the same message name and correlation value is still active.

**3. Test the Configuration**

Run the sender process and watch as it automatically triggers the receiver process when the Message Throw Event is reached.

![Message Start Event in Action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/start_with_message_event.gif)

Message Start Event in Action

> [!NOTE]
>
> Message correlation is essential for message-based communication between processes. It's achieved through the message name (which must be identical in both throw and catch events) and the correlation key (or value).

## Email and webhook triggers

A Message Start Event can also start a process directly from external events, without any Kafka configuration or sender process. Set the node's **Trigger Type** to one of these options and select a data source configured in Integration Designer:

* **Email Trigger**: starts a process instance when an email arrives in a monitored inbox (IMAP). The email data (sender, subject, body, attachments) is automatically mapped to the process instance data. Microsoft Outlook mailboxes use the same **Email Trigger** option: select a Microsoft Outlook data source with **Read** or **Read & Send** scope in the **Select Email Trigger** dropdown. The email arrives via the MS Graph API.
* **Incoming Webhook**: starts a process instance from an external HTTP POST request. The request payload (body, headers, timestamp) is automatically mapped to the process instance data.

**1. Create the Data Source**

In your project, go to **Integrations** → **Data Sources** and create the trigger resource: an [Email Trigger](../../platform-deep-dive/integrations/email-trigger), a [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) data source, or an [Incoming Webhook](../../platform-deep-dive/integrations/incoming-webhooks).

**2. Configure the Message Start Event**

1. Add a **Message Start Event** node as the starting point of your process
2. Set the **Trigger Type** to **Email Trigger** (for IMAP or Microsoft Outlook data sources) or **Incoming Webhook**
3. Select the data source created in the previous step

**3. Use the Incoming Data**

The trigger payload is mapped to the process instance data automatically, so you can reference the email fields or webhook body in your process logic.

For the full configuration reference of each trigger type, see the [Message Start Event](../../building-blocks/node/message-events/message-catch-start-event) documentation.

## Best practices

> [!TIP]
>
> **When implementing process initiation:**
>
> * **Choose the appropriate method** based on your use case (user-triggered, scheduled, event-based, etc.)
> * **Consider authentication requirements** for system-initiated processes
> * **Use correlation keys thoughtfully** to ensure reliable message delivery
> * **Test your initiation methods** thoroughly in a development environment
> * **Monitor process starts** to identify any failures or performance issues
> * **Document your initiation methods** for easier maintenance and troubleshooting

## Next steps

After setting up your process initiation methods, you can:

> [card] [Configure Process Data Models](../../building-blocks/process/data-model)
>
> Define the data structure for your process instances

> [card] [Set Up User Interfaces](./creating-a-user-interface)
>
> Create user interfaces for human-interactive processes

> [card] [Implement Business Rules](../../building-blocks/actions/business-rule-action/business-rule-action)
>
> Add decision logic to your processes

> [card] [Configure Integrations](../../platform-deep-dive/integrations/integration-designer)
>
> Connect your processes to external systems


# Notification center
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/notification-center

Track and act on long-running Designer operations, such as exports, imports, and process instance migrations, from a notification history in the app header.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

Some Designer operations keep running after you start them: a version or build export is assembled in the background, an imported version or build is unpacked into the workspace, and a process instance migration settles batch by batch. The notification center tells you when each of those operations starts and how it ended, lets you act on the result from the notification itself, and keeps a history so a result you missed is still there when you come back.

Notifications reach you in two ways:

* **Pop-up notifications** appear in the corner of the Designer as soon as an operation finishes, on any page.
* **The notification center** is a panel behind the bell in the app header. It lists every notification from the last 30 days, with read state, search, and filters.

![Notification center panel open from the bell in the app header, with the search field, the filter button, Mark all as read, one unread Export finished successfully notification under Today, and the Notifications are kept for 30 days footer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/notification-center-panel.png)

***

## What sends a notification

A notification is sent to the user who started the operation. Exports and imports send one when they start and another when they finish. A process instance migration sends one when it finishes.

| Operation | Notification title | Status | Action |
| - | - | - | - |
| [Version export](../projects/managing-applications/versioning#exporting-versions) | **Preparing version export...** | In progress | |
| | **Version export ready to download** | Success | **Download** |
| | **Version export ready - N resources excluded** | Warning (resources that the target FlowX version doesn't support were left out) | **Review** |
| | **Version export failed** | Failed | **Retry** |
| | **Export timed out** | Failed | **Retry** |
| [Build export](../projects/runtime/builds#exporting-builds) (SaaS · 6.0) | **Preparing build export...** | In progress | |
| | **Build export ready to download** | Success | **Download** |
| | **Build export ready - N resources excluded** | Warning | **Review** |
| | **Build export failed** | Failed | **Retry** |
| | **Export timed out** | Failed | **Retry** |
| [Version import](./managing-a-project-flow/export-import-a-process-definition#importing-a-project) (SaaS · 6.0) | **Importing version...** | In progress | |
| | **Version imported** | Success | **View** |
| | **Version import needs review - N conflicts** | Warning (the version was imported, with conflicts to review) | **View** |
| | **Version import failed** | Failed | **Retry** |
| | **Import timed out** | Failed | **Retry** |
| [Build import](../projects/runtime/builds) (SaaS · 6.0) | **Importing build...** | In progress | |
| | **Build imported** | Success | **View** |
| | **Build import failed** | Failed | **Retry** |
| | **Import timed out** | Failed | **Retry** |
| [Process instance migration](../projects/runtime/active-process/migrate-process-instances) | **Instance migrated** | Success (every instance migrated) | |
| | **Instance migrated - N failed** | Warning (some instances failed) | |
| | **Instance migration failed** | Failed (the migration could not run, and no instance was changed) | |

> [!NOTE]
>
> Only exports, imports, and process instance migrations send notifications. Other operations, such as moving tokens on running instances, finish without one.

### In-progress notifications

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When an export or import starts, you get an in-progress notification with a blue clock icon. When the operation finishes, the result replaces the in-progress notification, both on screen and in the notification center, so each operation is listed once. If an export finishes quickly, you only see the result.

### What a notification shows

Each notification, in the pop-up and in the panel, shows:

* A status icon: a green check for success, an orange warning for a partial result, a red icon for a failure, and a blue clock for an operation still in progress.
* The title of the notification.
* A tag with the environment type of the workspace the operation ran in (**SANDBOX**, **STAGING**, or **PRODUCTION**), followed by the workspace name and the app name.
* A summary line:
  * For exports: the branch, the version ID, the target FlowX version, and whether media was included (**media included** or **media excluded**).
  * For imports: the branch and the version ID.
  * For migrations: the source and target build tags and an instance count.
* A short message when the operation has one to add, for example the reason an export failed.
* An action button for exports and imports, described in [Acting on a notification](#acting-on-a-notification).
* In the panel only, the age of the notification: `now`, then minutes (`5m`), hours (`3h`), days (`2d`), or weeks (`1w`).

***

## Using the notification center

### Open the panel

The bell sits in the header of an open app, to the right of the **Config** and **Runtime** switch. A red dot on the bell means you have unread notifications.

**1. Open an app**

Open any app in the Designer. The bell is part of the app header, so it is not shown on workspace-level pages.

**2. Click the bell**

The panel opens with your notifications, newest first, grouped into **TODAY**, **THIS WEEK**, and **OLDER**. Unread notifications have a blue background.

**3. Close the panel**

Click anywhere outside the panel to close it.

The panel lists all your notifications in the organization, not only the ones for the app you have open. Use the workspace tag, workspace name, and app name on each row to see where the operation ran.

> [!NOTE]
>
> While the panel is open, new notifications appear directly in the list instead of as pop-ups. Opening the panel also clears any pop-ups on screen.

### Mark notifications as read

* **One notification:** hover over an unread row and click the check mark (**Mark as read**) next to its age.
* **From a pop-up:** click anywhere on the pop-up notification, including its close button.
* **All notifications:** click **Mark all as read** in the panel header.

> [!WARNING]
>
> **Mark all as read** marks every unread notification you have, across all workspaces, even if a search or filter currently hides some of them.

Read state belongs to your user, not to the browser tab. When you mark a notification as read, it also shows as read in your other open Designer tabs and sessions.

### Search notifications

Type in the **Search notifications...** field. The search starts after 2 characters and matches the notification title, message, workspace type, workspace name, app name, and the migration build and count details.

### Filter notifications

Click the filter button next to the search field and pick one option:

| Filter | Shows |
| - | - |
| **All Notifications** | Every notification from the last 30 days (the default) |
| **Unread** | Only unread notifications. The number next to it is your unread count. |
| **SANDBOX**, **STAGING**, **PRODUCTION** (under **Workspace Type**) | Only notifications from workspaces with that [environment type](../projects/workspaces#workspace-environment-type) |

The filter button turns blue while a filter other than **All Notifications** is active. Search and filter combine: the search applies to the filtered list.

### Pop-up notifications

Pop-up notifications appear at the edge of the screen when an operation finishes, on any Designer page:

* Each pop-up closes on its own after 5 seconds, or after 7 seconds when it offers an action. Click the close button to dismiss it sooner.
* Up to 3 pop-ups show at once. Further notifications wait and appear as space frees up.
* Hovering over the pop-ups, or moving focus into them, pauses the countdown. The countdown also pauses while the Designer tab is in the background.

![Pop-up notification for Export finished successfully with a green check icon, the SANDBOX tag, the workspace and app name, and the message Go ahead and download.](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/notification-popup-export-finished.png)

***

## Acting on a notification

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Export and import notifications carry an action button, in the pop-up and in the panel. The button works from any Designer page: you don't need to open the app the operation ran in.

> [tab] Version and build export
>
> | Button | Shown on | What it does |
> | - | - | - |
> | **Download** | Ready to download | Downloads the export archive (`.zip`). |
> | **Review** | Ready - N resources excluded | Opens the **Download export** review, described below. |
> | **Retry** | Failed or timed out | Runs the export again right away, with the same target FlowX version and media option. The new run sends its own notifications. |
>
> **Review an export that left resources out.** Some resources don't exist on the FlowX version you exported for, so the export leaves them out of the archive. **Review** opens the **Download export** window, which lists the **Excluded resources** with a count. Then choose:
>
> * **Download anyway** to download the archive without those resources.
> * **Change Target Version** to open the export window again and pick another target FlowX version.
>
> You can also download an export from the export window you started it from. For the export flows, see [Exporting versions](../projects/managing-applications/versioning#exporting-versions) and [Exporting builds](../projects/runtime/builds#exporting-builds).

> [tab] Version and build import
>
> | Button | Shown on | What it does |
> | - | - | - |
> | **View** | Version imported, or needs review | Opens the imported version. |
> | **View** | Build imported | Opens the **Builds** list of the imported app. |
> | **Retry** | Failed or timed out | Asks you to select the `.zip` file again, then imports it into the workspace the failed import ran in. The new run sends its own notifications. |
>
> **Retry** asks for the file again because the browser can't reuse a file you selected earlier.
>
> For the import flow, see [Importing a project](./managing-a-project-flow/export-import-a-process-definition#importing-a-project).

> [tab] Process instance migration
>
> When you start a migration, the Designer shows a **Corrective Action in Progress...** dialog.
>
> * If you keep the dialog open, the Designer opens the migration's details as soon as the migration finishes, and closes the dialog. No pop-up is shown, but the notification is still added to the notification center.
> * If you click **Close - keep working**, the outcome arrives as a pop-up notification and in the notification center.
>
> To review the result, including which instances failed, see [Migrate process instances](../projects/runtime/active-process/migrate-process-instances).
>
> ![Corrective Action in Progress dialog for a migration from build 1.0.0 to build 1.1.0, with the Close - keep working button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/notification-corrective-action-in-progress.png)

***

## Scope and retention

**Personal.** A notification goes only to the user who started the operation. Other users in the same workspace do not see it.

**Organization-wide.** The notification center shows your notifications for the organization you are signed in to, from every workspace and app in it. The bell shows the same list from any app.

**30-day history.** The panel lists notifications from the last 30 days. Older notifications no longer appear. The panel footer shows this as **Notifications are kept for 30 days**.

**Not missed while signed out.** Notifications are stored when they are sent. If an operation finishes while you are signed out, its notification appears in the panel the next time you open the Designer.

***

## Troubleshooting

> [accordion] I moved tokens on running instances and got no notification
>
> This is expected. Only exports, imports, and process instance migrations send notifications. A token move finishes without one. Check its result on the **Corrective Actions** page.

> [accordion] My migration finished but no pop-up appeared
>
> Two cases skip the pop-up:
>
> * The **Corrective Action in Progress...** dialog was still open. The Designer opened the migration's details instead.
> * The notification center panel was open. New notifications go straight into the list while the panel is open.
>
> In both cases the notification is in the notification center.

> [accordion] A notification I expected is not in the panel
>
> Check the following:
>
> * **Filter and search:** switch the filter back to **All Notifications** and clear the search field.
> * **Age:** notifications older than 30 days are no longer listed.
> * **Recipient:** notifications go only to the user who started the operation. If a colleague started the export or migration, the notification is in their notification center.
> * **Connection:** the live connection does not replay notifications sent while it was interrupted. Reload the Designer to load the full history again.

> [accordion] Notifications from other workspaces were marked as read
>
> **Mark all as read** applies to all your unread notifications in the organization, regardless of the active filter or search. To mark only some notifications, use the check mark on each row.

***

## Related resources

> [card] [Versioning](../projects/managing-applications/versioning#exporting-versions)
>
> Export a version and download the export file

> [card] [Migrate process instances](../projects/runtime/active-process/migrate-process-instances)
>
> Move running instances to another build and review the result

> [card] [Workspaces](../projects/workspaces#workspace-environment-type)
>
> Workspace environment types used by the notification filter

> [card] [FlowX.AI Designer](./overview)
>
> Overview of the Designer and its main areas


# FlowX.AI Designer
Source: https://docs.flowx.ai/5.9/docs/flowx-designer/overview

The FlowX.AI Designer is a collaborative, no-code, web-based application development environment, designed to facilitate the creation of web and mobile applications without the need for coding expertise.

<video />

## Overview

The **FlowX.AI Designer** is a collaborative platform that empowers you to create sophisticated web and mobile applications without coding expertise. Let's explore the key capabilities available in the Designer:

> [tab] Workspace Management
>
> ![Workspace Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
>
> Workspaces provide isolated environments for organizing projects and controlling access:
>
> * Create dedicated spaces for different teams or departments
> * Manage user access and permissions at workspace level
> * Organize projects by business unit or use case
> * Maintain separation between development contexts
> * Control visibility and collaboration boundaries

> [tab] Project Management
>
> ![Project Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)
>
> Projects serve as a structured container that group all resources, dependencies, and configurations needed for specific use cases. They provide:
>
> * Centralized resource management
> * Version control capabilities
> * Build deployment across environments
> * Collaborative editing workflows
> * Modular organization of processes and assets

> [tab] Process Design
>
> ![Process Design](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/prs_def.png)
>
> The process designer allows you to:
>
> * Create and edit processes using BPMN 2.0 standards
> * Configure nodes with business rules and actions
> * Set up user tasks and system integrations
> * Establish decision logic and execution paths
> * Test and debug process flows

> [tab] Content & UI
>
> ![UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/ui_ui_designer.gif)
>
> Create intuitive user interfaces and manage content with:
>
> * Drag-and-drop UI component assembly
> * Advanced navigator with layer management
> * Theme customization capabilities
> * Media library organization
> * Font and styling controls

> [tab] Plugins & Integration
>
> ![Integrations](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/plugins_integrations.png)
>
> Extend functionality with plugins and integrations:
>
> * Task management capabilities
> * Document generation and templates
> * Notification system configuration
> * Integration mapping and monitoring
> * API connection management

## Key features & capabilities

> [card] Workspace Management
>
> Organize projects into isolated workspaces with dedicated access control, enabling team separation and structured collaboration across departments.

> [card] Project & Library Management
>
> Create and manage comprehensive workspaces with centralized resources, version control, and modular components that enable efficient collaboration.

> [card] Process Design & Monitoring
>
> Design, debug, and monitor processes using BPMN 2.0 standards with tracking and performance analytics.

> [card] Content Management
>
> Manage enumerations, substitution tags, media, fonts, and themes with comprehensive organization tools.

> [card] UI Design
>
> Create intuitive interfaces with an advanced navigator, component library, and flexible styling options.

> [card] Plugin Ecosystem
>
> Extend functionality with task management, notification, and document generation plugins for comprehensive solutions.

> [card] Integration Tools
>
> Configure and monitor integrations between the FlowX Engine, plugins, and external systems with visual mapping tools.

> [card] Platform Monitoring
>
> Track the health and installed version of every platform component.

> [card] AI Assistance
>
> Accelerate development with AI-powered suggestions, optimization recommendations, and contextual help.

> [!NOTE]
>
> Depending on your access rights, some features and tabs might not be visible. For more information, check [Access Management](../../setup-guides/access-management/access-management-overview) section.

## Where to find things

The Designer has a menu for each level. Entries in parentheses are the items inside a group.

| Menu | Entries |
| - | - |
| Organization admin | Solutions, Usage Stats, **AI Settings** (Model Providers, Defaults & Fallbacks), Workspaces, **Design Assets** (Fonts, Branding), **Access Management** (Designer Users, Designer Roles, End-Users, End-Users Groups), **Task Manager** (Out of Office), Platform Status, Audit Logs |
| Workspace | Projects, Libraries, **Design Assets** (Themes, Fonts, Global Media Library), **Access Management** (Users, Groups), Platform Status, Audit Logs, Organization Settings |
| Project, **Config** view | Processes, Project Data Model, **Reusable Resources** (UI Templates, Custom Components, Functions, UI Flows), **CMS** (Enumerations, Substitution Tags, Media Library, Notification Templates, Document Templates), **Task Manager** (Views, Stages, Allocation Rules), **Integrations** (Data Sources, Workflows, Proxy Connections, Document Intelligence), Dependencies, Configuration Parameters, Version Settings |
| Project, **Runtime** view | Builds, **Runtime Settings** (Active Policy, Scheduled Processes, Manage Triggers), **Processes** (Process Instances, Failed Process Start, Failed Triggers), UI Flows Sessions, Task Manager, Configure Params Overrides |

## Detailed component overview

> [accordion] Workspaces
>
> ![Workspace Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
>
> Workspaces are the top-level organizational unit in FlowX.AI Designer, providing isolated environments where teams can collaborate on projects with controlled access and visibility.
>
> ### Key Capabilities
>
> **1. Workspace Creation & Management**
>
> Create dedicated workspaces for different teams, departments, or business units. Each workspace acts as an independent container with its own projects and resources.
>
> **2. Access Control**
>
> Configure workspace-level permissions to control who can view, edit, or manage projects within each workspace. Administrators can assign users and groups specific roles.
>
> **3. Project Organization**
>
> Group related projects together within a workspace for better organization and discoverability. Projects inherit workspace-level settings and permissions.
>
> **4. Team Collaboration**
>
> Enable focused collaboration by bringing together stakeholders who need to work on related projects, while maintaining separation from other teams.
>
> ### Benefits
>
> * **Isolation**: Keep different teams' work separate and secure
>
> * **Flexibility**: Organize workspaces by department, product line, or any business structure
>
> * **Security**: Control access at the workspace level for enhanced governance
>
> * **Clarity**: Reduce clutter by showing users only relevant workspaces and projects
>
> > [card] [Workspace Access Rights](../../setup-guides/access-management/workspaces-access-rights)
> >
> > Learn more about configuring workspace access rights

> [accordion] Projects & Libraries
>
> > [tab] Projects
> >
> > A project groups resources that represent a project's entire lifecycle. It's not just a collection of processes; it's an organized workspace containing all dependencies required for that project. It enables:
> >
> > * Centralized resource management
> > * Version control with history tracking
> > * Build deployment across environments
> > * Collaborative workflows with simultaneous editing
> > * Modular organization of processes and assets
> >
> > ![Project Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)
> >
> > > [card] [Learn More About Projects](../projects/managing-applications/application)
>
> > [tab] Libraries
> >
> > A library is a specialized project type designed to store and share reusable resources across multiple projects:
> >
> > * Share processes, enumerations, and media assets
> > * Enable centralized resource management
> > * Provide version-controlled dependency management
> > * Support modular development approaches
> > * Include comprehensive dependency tracking
> > * Offer comprehensive import/export functionality

> [accordion] Process Management
>
> > [tab] Process Definitions
> >
> > A **process definition** is uniquely identified by its name and version number. The process designer provides:
> >
> > * [Process definition](../building-blocks/process/process-definition) management
> > * Versioning history with comparison capabilities
> > * Debugging tools for process execution
> > * Version comparison for change identification
> > * BPMN 2.0 standard compliance
> >
> > ![Process Definitions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_process_definitions.gif)
> >
> > > [card] [Process Definition](../building-blocks/process/process-definition)
> >
> > > [card] [Managing a Process Flow](../flowx-designer/managing-a-project-flow/)
>
> > [tab] Process Instances
> >
> > **Process instances** are listed in a project's **Runtime** view, under **Processes** → **Process Instances**. Monitor and manage running process instances with:
> >
> > * Filtering by process definition names
> > * Search by unique process ID
> > * View current process status and data
> > * [Token](../building-blocks/token) instance and content inspection
> > * [Subprocess](../building-blocks/process/subprocess) management
> > * Real-time monitoring with performance metrics
> > * Advanced filtering for process management
> >
> > ![Active Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_active_process.png)
> >
> > > [card] [Process Instance Management](../projects/runtime/active-process/process-instance)

> [accordion] Content Management
>
> #### Data & Localization
>
> **1. Enumerations**
>
> Manage static value definitions that can be used in UI components or templates with bulk import/export capabilities.
>
> **2. Substitution Tags**
>
> Generate dynamic content across the platform with context-aware tag suggestions for localization.
>
> **3. Source Systems**
>
> Connect to multiple data sources for [enumeration values](../platform-deep-dive/core-extensions/content-management/enumerations) with third-party system integration.
>
> #### Media & Styling
>
> **1. Media Library**
>
> Centrally manage various media files with metadata tagging and optimization capabilities.
>
> **2. Font Management**
>
> Upload and manage font files including variable fonts with subset creation for performance.
>
> **3. Themes**
>
> Personalize application appearance with atomic design principles and multi-device previewing.
>
> Languages are not part of CMS: you set them per project version, in **Version Settings** → **Languages**.
>
> ![Content Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_cms.gif)
>
> > [!NOTE]
> >
> > You need to deploy the CMS service in your infrastructure before you can start defining and using custom content types.
>
> > [card] [Headless CMS](../platform-deep-dive/core-extensions/content-management/content-management)
>
> > [card] [CMS Setup Guide](../../setup-guides/cms-setup)

> [accordion] Plugins
>
> > [card] [Task Management](../platform-deep-dive/core-extensions/task-management/task-management-overview)
> >
> > ![Task Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_task_manager.png)
> >
> > Track and assign activities with prioritization, history tracking, and performance analytics. The Task Manager provides a business-oriented view of processes with assignment-level interactions.
>
> > [card] [Notification Templates](../platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview)
> >
> > ![Notification Templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_notification_templates.png)
> >
> > Create, edit, and activate/deactivate notification templates for multiple channels (SMS, email, push notifications) with scheduling, monitoring, and personalization capabilities.
>
> > [card] [Document Templates](../platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview)
> >
> > ![Document Templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_documents.png)
> >
> > Generate documents based on custom templates with process data, convert between formats, split documents, add barcodes/signatures, and manage version control with conditional template variables.

> [accordion] System Settings
>
> > [tab] Configuration Parameters
> >
> > ![Generic Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_generic_params.png)
> >
> > Manage environment-specific settings with:
> >
> > * Key-value parameter definition
> >
> > * Environment-specific value configuration
> >
> > * Parameter grouping and categorization
> >
> > * Environment comparison tools
> >
> > * Import/export capabilities
> >
> > > [!WARNING]
> > >
> > > The maximum length of a parameter input value is 255 characters.
>
> > [tab] Access Management
> >
> > ![Access Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_access_mng.png)
> >
> > Administrate users, roles and groups through:
> >
> > * Integration with Keycloak/[RH-SSO](https://access.redhat.com/products/red-hat-single-sign-on)
> >
> > * Role-based access control
> >
> > * Granular permission management
> >
> > * User onboarding templates
> >
> > * Group organization
> >
> > > [card] [Access Management](../../setup-guides/access-management/access-management-overview)
>
> > [tab] Integrations
> >
> > ![Integration Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-designer/designer_integrations.png)
> >
> > The **Integrations** group in a project's navigation holds:
> >
> > * [Data Sources](../platform-deep-dive/integrations/data-sources-and-endpoints)
> > * [Workflows](../platform-deep-dive/integrations/integration-designer)
> > * [Proxy Connections](../platform-deep-dive/integrations/proxy-connections)
> > * **Document Intelligence**

> [accordion] Platform Status
>
> ![Platform Status](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/platform_status.png)
>
> The Platform Status page is also where you check **which version of FlowX your environment is running**. It lists each component's installed version next to its suggested version, so you can confirm the deployed version at a glance. Open it from the organization admin menu or from a workspace menu.
>
> The page has two tables, **Services** and **Jobs**, with the columns **Component name**, **Status**, **Component Type**, **Installed version**, and **Suggested version**. You can also:
>
> * Search by component name
> * Open a component's details from its row
> * Run **Force Rescan** or **Export** from the page menu

> [accordion] UI Designer
>
> ![UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/ui_designer.png)
>
> The UI Designer provides a comprehensive environment for creating intuitive user interfaces with:
>
> * Enhanced UI layer panel for intuitive design element management
>
> * Improved drag and drop functionality for precise component placement
>
> * Flexible root component management for form groups and containers
>
> * Clear component hierarchy visualization with navigation controls
>
> * Rich component library with customization options
>
> * Integration with themes and styling capabilities
>
> > [card] [UI Designer Documentation](../building-blocks/ui-designer/ui-designer)
> >
> > Learn more about UI Designer capabilities and components

## Next steps

> [card] [Managing a Process Flow](../flowx-designer/managing-a-project-flow/)
>
> Learn how to create and manage a process from scratch


# Glossary
Source: https://docs.flowx.ai/5.9/docs/getting-started/glossary

The FlowX.AI vocabulary in one place - what each core term means and where to learn more about it.

FlowX.AI has its own vocabulary, and a few terms mean something more specific here than in everyday usage. This page defines the core terms and links each one to its full documentation.

> [!TIP]
>
> The most common mix-up: a **process** is a BPMN flow with user and service tasks; a **workflow** is an integration flow built in the Integration Designer, often with AI nodes. They are different building blocks with different designers.

***

## Platform and projects

**FlowX.AI Designer:** The web app where you build everything: processes, workflows, UIs, data sources, and AI agents. See the [FlowX.AI Designer overview](/5.9/docs/flowx-designer/overview).

**Project:** The container that groups all resources and dependencies needed to implement a use case: processes, workflows, UI, enumerations, media, and integrations. See [Projects](/5.9/docs/projects/managing-applications/application).

**Library:** A specialized project that serves as a reusable container for resources shared across multiple projects. See [Libraries](/5.9/docs/projects/managing-applications/libraries).

**Workspace:** A logically isolated business context within one FlowX instance. An organization can run multiple workspaces, each with its own projects and access rights. See [Workspaces](/5.9/docs/projects/workspaces).

**Dependency:** A link from a project to a library version, making that library's resources available in the project. See [Dependencies](/5.9/docs/projects/managing-applications/dependencies).

**Version:** A tracked snapshot of a project's configuration. Projects evolve through submitted versions, which are then packaged into builds. See [Versioning](/5.9/docs/projects/managing-applications/versioning).

**Build:** A deployable package of a project that encapsulates all its resources into a single unit. Builds are what run in an environment. See [Builds](/5.9/docs/projects/runtime/builds).

**Active policy:** The strategy that selects which build of a project is active in a runtime environment. See [Active policy](/5.9/docs/projects/runtime/active-policy).

**Configuration parameters overrides:** Environment-specific values for parameters within a project, so the same build can behave differently per environment. See [Configuration parameters overrides](/5.9/docs/projects/runtime/configuration-parameters-overrides).

**Config-time vs runtime:** Config-time is where you design (Designer, projects, versions); runtime is where builds execute and end users interact with running instances.

***

## Processes (BPMN)

**Process definition:** The blueprint of a business process: a graph of nodes linked by sequences, modeled in BPMN. See [Process definition](/5.9/docs/building-blocks/process/process-definition).

**Process instance:** One specific execution of a process definition, carrying its own data and state. Instances can be executed, monitored, and optimized. See [Process instance](/5.9/docs/projects/runtime/active-process/process-instance).

**Node:** A visual representation of a point in your process: where a record enters, transitions, or exits. Node types include user tasks, service tasks, and message events. See [Process nodes](/5.9/docs/building-blocks/node/node).

**Token:** The current position in the process flow. A token moves through the node graph as the instance advances; parallel paths mean multiple tokens. See [Token](/5.9/docs/building-blocks/token).

**Node action:** An activity a node handles, such as saving data, calling a business rule, or communicating with plugins and integrations. See [Node actions](/5.9/docs/building-blocks/actions/actions).

**Business rule:** An action type that configures a script on a BPMN node to express business logic or decision-making within a process. See [Business rule action](/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action).

**Subprocess:** A process started from within another process, used to reuse and compose flows. See [Subprocess](/5.9/docs/building-blocks/process/subprocess).

***

## Workflows and integrations

**Workflow:** An integration flow built in the Integration Designer, used for data processing, transformation, and AI operations across connected systems. Not a BPMN process: workflows are started from processes or triggers, and their nodes are grouped into Flow Control, Data Operations, Tools, and AI categories (AI Text, AI Document, AI Image, and AI Data Operations, plus AI Agents). See [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer).

**Integration Designer:** The drag-and-drop workspace for connecting FlowX to external systems via REST APIs, and for building workflows. See [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer).

**Data source:** A configured connection a workflow or process can use. Types include RESTful System, FlowX Database, MCP Server, Email Trigger, Email Sender, Knowledge Base, Microsoft Outlook, and Incoming Webhook.

**FlowX Database:** A built-in data source for storing and accessing structured data across processes and apps, without standing up an external database. See [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database).

**Knowledge Base:** A managed store of documents and dynamic data that gives AI agents contextual information for retrieval-augmented generation. See [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview).

**Incoming Webhook:** A data source that starts or advances flows when an external system sends an HTTP POST, secured with API keys. See [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks).

**Email Trigger:** A data source that monitors an IMAP mailbox and starts process instances when emails arrive. See [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger).

***

## User interfaces

**UI Designer:** The visual, multi-platform tool for designing interfaces that render on web, iOS, and Android without extensive coding. See [UI Designer](/5.9/docs/building-blocks/ui-designer/ui-designer).

**UI Flow:** A reusable, multi-platform user interface that runs without the overhead of a BPMN process. See [UI Flows](/5.9/docs/building-blocks/ui-flows).

**UI Flow session:** One user's active interaction with a UI Flow, with its own status, audit trail, and associated processes. See [UI Flow Sessions](/5.9/docs/projects/runtime/ui-flow-sessions).

**Custom component:** A React component you build and register to extend the built-in UI component palette, with access to process data and actions. See [Custom components](/5.9/docs/building-blocks/reusable-resources/custom-components).

***

## AI Platform

**Config-time agents:** AI agents built into the FlowX Designer that help you build faster: AI Analyst, AI Designer, AI Developer, and AI Assistant. See [Config-time agents](/5.9/ai-platform/pre-built-agents/overview).

**Business agents:** AI agents that power experiences for end users in your apps, created with the Agent Builder. See [AI in FlowX](/5.9/ai-platform/ai-in-flowx).

**Agent Builder:** The no-code/low-code tool for creating custom AI agents. See [Agent Builder](/5.9/ai-platform/agent-builder/overview).

**Chat-driven workflow:** A workflow behind a multi-turn chat experience, with session memory, intent routing, and context-aware responses. See [Chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).

***

## Deployment and releases

**SaaS:** FlowX operated as a managed cloud service. New feature releases reach SaaS first.

**Self-hosted:** FlowX deployed and operated in your own infrastructure. Self-hosted deployments follow LTS releases.

**LTS release:** A long-term-support platform version (such as 5.9.x) that receives maintenance patches and is the basis for self-hosted deployments.

**Feature release:** A monthly release between LTS versions that ships new capabilities to SaaS; those capabilities reach self-hosted with the next LTS.

***

## Related resources

> [card] [Build your first process](/5.9/docs/getting-started/building-your-first-proc)
>
> Put the vocabulary to work in a hands-on tutorial.

> [card] [Cookbooks](/5.9/cookbooks/overview)
>
> Tutorials, guides, and reusable patterns for building on FlowX.AI.


# Using FlowX docs with AI assistants
Source: https://docs.flowx.ai/5.9/docs/getting-started/using-flowx-docs-with-ai

Connect this documentation to Claude, ChatGPT, Cursor, or any MCP client so your assistant answers from the current docs instead of guessing.

This documentation is built to be read by AI assistants as well as people. You can connect it to your assistant so that answers come from the current FlowX.AI documentation rather than from whatever the model happened to memorize during training.

> [!NOTE]
>
> This page is about connecting **the documentation site** to an AI assistant. It is not about the MCP Server data source you configure inside a project. For that, see [MCP integration overview](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview).

***

## Why connect the docs

Language models are trained at a point in time and FlowX.AI ships monthly. An assistant answering from memory will confidently describe features that changed, node types that were renamed, and configuration keys that never existed.

Connecting the docs changes where the answer comes from. The assistant searches the live documentation, reads the actual page, and cites it back to you.

> [!TIP]
>
> This matters most for version-sensitive questions. Availability, environment variables, and node configuration differ between releases, and those are exactly the details a model is most likely to get wrong from memory.

***

## Connect from any page

Every page on this site has a contextual menu at the top with the connection options built in.

**1. Open the menu on any documentation page**

Use the control at the top of the page, beside the page title.

**2. Pick your assistant or editor**

Options include Claude, ChatGPT, Perplexity, Cursor, and VS Code. Each one hands the current page, or the connection details, straight to that tool.

**3. Ask your question**

The assistant now has the documentation available and will search it rather than answering from memory.

The same menu also offers **Copy page** and **View as Markdown** if you would rather paste content in manually.

***

## Connect manually over MCP

For any client that supports the Model Context Protocol, connect to this endpoint over HTTP:

```
https://docs.flowx.ai/mcp
```

In Claude Code, add it with:

```bash theme={"dark"}
claude mcp add --transport http flowx-docs https://docs.flowx.ai/mcp
```

Other clients store MCP server definitions in their own configuration file, and most accept a remote HTTP server as a name and URL pair. Use the contextual menu on any page to get the exact configuration for Cursor and VS Code, since it generates the correct file and format for you.

### What the assistant can do once connected

The docs server exposes three tools.

| Tool | What it does |
| - | - |
| `search_flow_x_ai` | Searches the documentation and returns matching content with direct links to the source page |
| `query_docs_filesystem_flow_x_ai` | Reads and searches the documentation as a read-only file tree, for exact keyword matching or reading a full page |
| `submit_feedback` | Reports a documentation problem to the docs team, tied to the page path it concerns |

When you search, set `version` to `v5.9.x` for the current LTS or `v6.x` for 6.0. Other spellings, such as `6.x` or `6.0.x`, return no results.

> [!NOTE]
>
> `query_docs_filesystem_flow_x_ai` runs against a sandboxed, in-memory copy of the documentation. It is not a shell, and nothing runs on your machine, the docs server, or any FlowX environment.

> [!TIP]
>
> `submit_feedback` is worth knowing about. If your assistant gives you an answer that turns out to be wrong because a page is outdated or incomplete, you can ask it to report that, and the correction reaches the docs team with the page path attached.

***

## Install the FlowX skill

The docs also publish a skill: a short capability summary that tells an agent what it can build with FlowX.AI, which terms to use, and which constraints apply. Search answers one question at a time. The skill gives the agent working context before you ask.

If you connected over MCP, you already have it. The docs server exposes the skill as an MCP resource, so your client can load it without a separate install.

For an agent that does not use MCP, install it with the skills CLI:

```bash theme={"dark"}
npx skills add https://docs.flowx.ai
```

The CLI requires a recent Node.js release (22.20 or later). The raw file is published at `https://docs.flowx.ai/skill.md`.

> [!NOTE]
>
> The skill describes the current LTS release family. On an older release, rely on search results from your version's documentation tree rather than the skill's capability summary.

### Set it up with a prompt

Copy this prompt into your agent, or open it in Cursor, and let the agent do the setup.

Connect the FlowX.AI documentation to your agent.

Connect the FlowX.AI documentation to this agent so you answer FlowX.AI questions from the current docs instead of from memory.

1. Add the remote MCP server `https://docs.flowx.ai/mcp` over HTTP, using the configuration format this client expects.
2. If this client does not load MCP resources, install the FlowX.AI skill with `npx skills add https://docs.flowx.ai`.
3. Ask me which FlowX.AI release I am running, and search that version's documentation tree in every answer.
4. Confirm the setup by searching the docs for "build your first process" and returning the page link.

***

## Bulk formats

If you are building a tool, seeding a knowledge base, or feeding a long-context model, three formats are published.

> [card] Page as Markdown
>
> Append `.md` to any documentation URL to get that single page as clean Markdown.

> [card] llms.txt
>
> An index of the documentation with a one-line description per page. Good for routing and discovery.

> [card] llms-full.txt
>
> The complete documentation as a single Markdown file. Large, and intended for ingestion rather than browsing.

> [card] Sitemap
>
> `https://docs.flowx.ai/sitemap.xml` lists every indexed page URL.

Example, fetching one page as Markdown:

```bash theme={"dark"}
curl https://docs.flowx.ai/5.9/docs/getting-started/glossary.md
```

***

## Working across versions

FlowX.AI documentation is published as one tree per release family, and the version is part of every URL. When you ask a version-specific question, name the release in your prompt so the assistant searches and cites the right tree.

> [!WARNING]
>
> Ask for the version you are running, and check the version in the links your assistant returns. A question asked without a version can be answered from any tree, including release families that have reached end of life.

Feature Release content documented in the current LTS tree carries a **SaaS** availability badge. Those features are live on managed deployments immediately, and reach self-hosted deployments with the next LTS release family. If your assistant reports a feature as available, confirm against that badge before planning a self-hosted rollout.

***

## Related resources

> [card] [MCP integration overview](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
>
> Configure an MCP Server as a data source inside a FlowX project

> [card] [Glossary](/5.9/docs/getting-started/glossary)
>
> Core FlowX.AI terms, so your prompts use the right vocabulary

> [card] [Build your first process](/5.9/docs/getting-started/building-your-first-proc)
>
> Start here if you are new to the platform

> [card] [Knowledge Base and RAG](/5.9/ai-platform/patterns/knowledge-base-rag)
>
> Build retrieval into your own FlowX agents


# FlowX.AI data architecture: which service uses which store
Source: https://docs.flowx.ai/5.9/docs/platform-overview/data-architecture

See which data stores FlowX.AI uses, what each one holds, and which services read and write each PostgreSQL database, MongoDB database, and bucket.

## Overview

FlowX.AI uses multiple specialized data stores, each chosen for specific workload characteristics: PostgreSQL for process definitions and instance state, MongoDB for runtime configuration and the FlowX Database, Redis for caching and sessions, Kafka for event streaming, S3-compatible object storage for files and documents, Elasticsearch for audit logs and search indexes, and Qdrant for vector embeddings and semantic retrieval. They fall into two categories:

* **Embedded data components**: shipped with the platform, managed by FlowX.AI
* **Platform data services**: third-party dependencies deployed by your team

```mermaid theme={"dark"}
flowchart LR
    FX["FlowX.AI Platform"]

    FX -->|"process definitions, instance state,\nplatform config, metadata"| PG[("PostgreSQL")]
    FX -->|"runtime config, workflow state,\nFlowX Database"| MONGO[("MongoDB")]
    FX -->|"cache, sessions,\ndistributed locks"| REDIS[("Redis")]
    FX -->|"event streaming,\nasync messaging"| KAFKA[("Kafka")]
    FX -->|"files, documents,\nbinary assets"| S3[("S3-compatible\nobject storage")]
    FX -->|"audit logs,\nsearch indexes"| ES[("Elasticsearch")]
    FX -->|"vector embeddings,\nsemantic retrieval"| QD[("Qdrant")]

    style PG fill:#336791,color:#fff
    style MONGO fill:#4DB33D,color:#000
    style REDIS fill:#DC382D,color:#fff
    style KAFKA fill:#231F20,color:#fff
    style S3 fill:#FF9900,color:#000
    style ES fill:#FED10A,color:#000
    style QD fill:#DC244C,color:#fff
```

***

## Embedded data components

> [!NOTE]
>
> Embedded data components are delivered as part of the FlowX.AI platform (Docker images + Helm charts). They run on Kubernetes only, and their versioning is managed by FlowX.AI. These components are included in the standard deployment and cannot be replaced by alternative implementations.

> [card] [Qdrant](https://qdrant.tech/documentation/)
>
> **Type:** Vector database
>
> Qdrant is used by the AI Platform RAG path (`knowledgebase-rag`, `embedder`, `knowledgebase-indexer-v2`) and by AI agents for semantic retrieval. It stores vector embeddings and serves similarity search over indexed knowledge.
>
> It holds separate collections for **runtime knowledge bases** (queried by business agents at run time), **design-time knowledge bases** (used by the config-time agents in FlowX Designer), and the **AI assistant** corpus. Qdrant runs embedded as a single node by default; cluster mode is recommended for production.

***

## Platform data services

> [!NOTE]
>
> The following data services are required by the FlowX.AI platform but are third-party dependencies. You choose the deployment model (managed service or self-hosted, inside or outside the Kubernetes cluster) according to your enterprise standards. FlowX.AI connects to these services via configuration.
>
> For supported versions and compatibility details, see the [Third-party components](../platform-deep-dive/third-party-components#compatibility-matrix) compatibility matrix.

### Relational storage with PostgreSQL or Oracle

PostgreSQL is the primary relational database and system-of-record for most core services. Oracle Database is also supported as an alternative. They store:

* Process definitions and metadata
* Runtime instance state
* Platform configuration
* Administrative data

Most FlowX.AI microservices use PostgreSQL or Oracle as their authoritative storage layer.

### Document storage with MongoDB

MongoDB provides document-oriented storage for unstructured and semi-structured content. It stores:

* Runtime configuration
* Runtime workflow state
* Flexible data structures used by apps and integrations

MongoDB is also the storage layer for [FlowX Database](../platform-deep-dive/integrations/flowx-database), a cross-instance, long-term storage feature that lets apps persist and query data beyond a single process instance.

### Caching with Redis

Redis is an in-memory cache used for performance optimization across the platform. It stores:

* Cached process definitions
* Transient session data
* Distributed locks across microservices

> [!NOTE]
>
> Redis is used strictly for short-lived, performance-related data and is **not** a system-of-record. Long-term persistence is handled by PostgreSQL and MongoDB.

> [!NOTE]
>
> Message-start deduplication and pending external (received) messages are persisted in PostgreSQL, which is their source of truth. Message-start deduplication relies on a PostgreSQL unique constraint. Redis is read only as a fallback for pending messages written before the upgrade, so in-flight message processing survives a Redis restart or data loss.

### Event streaming with Kafka

Kafka is the event streaming backbone that enables asynchronous, event-driven communication between microservices. It handles:

* Internal event propagation between platform services
* External integration messaging
* Decoupled processing workflows

> [!NOTE]
>
> Kafka is used for transient message propagation. Authoritative business data is persisted in PostgreSQL and MongoDB, not in Kafka.

### S3-compatible object storage

S3-compatible object storage provides persistent file storage. It stores:

* File attachments
* Document outputs (generated PDFs, converted files)
* Large binary assets
* Kafka messages above the payload size limit (see [S3-compatible object storage buckets](#s3-compatible-object-storage-buckets))

FlowX.AI accesses object storage via an S3-compatible interface.

> [!TIP]
>
> For providers without native S3 support (such as Azure Blob Storage), an S3 proxy is required to expose an S3-compatible interface. If you use a native S3 service (like AWS S3), no proxy is needed.

> [!WARNING]
>
> On Azure Blob Storage, multipart uploads (files over 5 MB) through an S3 proxy can require Azure roles that include blob index tag permissions, which `Storage Blob Data Contributor` does not cover. See [Azure Blob Storage through an S3 proxy](/5.9/setup-guides/documents-plugin-setup#azure-blob-storage-through-an-s3-proxy) for the required roles.

### Search and indexing with Elasticsearch

Elasticsearch is used primarily for audit logging and full-text search across workflow and runtime data. It stores:

* Searchable representations of audit events
* Platform activity logs
* Indexed workflow data for fast retrieval

Elasticsearch is optimized for fast search and traceability rather than primary data storage.

***

## AI Platform data stores

The AI Platform does not introduce a separate data stack. Its services reuse the same store families as the rest of the platform (PostgreSQL, MongoDB, Kafka, and object storage) and add **Qdrant** as the one AI-specific store for vector embeddings.

| Data store | How the AI Platform uses it |
| - | - |
| **Qdrant** | Vector embeddings and similarity search for knowledge-base RAG and AI agents. Separate collections for runtime knowledge bases, design-time knowledge bases, and the AI assistant. |
| **PostgreSQL** | Service state for AI components: embedding-job tracking and document-enrichment artifacts. Standalone services (document parser, speech-to-text) keep durable job state here. |
| **Kafka** | Asynchronous AI job topics (document parsing, speech-to-text, web crawling, evaluations, data privacy) and the internal knowledge-base pipeline that chains indexing, embedding, and enrichment. |
| **Object storage (S3)** | Knowledge-base enrichment payloads, email attachment scan results, files that AI nodes read and write, and Kafka messages above the payload size limit. Document services (document parser, document converter, speech-to-text, data privacy) also read the files a request points to, usually stored in Document Plugin buckets. See [AI Platform buckets](#ai-platform-buckets). |
| **MongoDB** | AI Gateway conversation and message history (`ai-gateway` database). Knowledge-base **metadata** (store and entry definitions), owned by Integration Designer. The vectors themselves live in Qdrant, so a knowledge base spans MongoDB (metadata) and Qdrant (embeddings). |

> [!NOTE]
>
> All vector storage and similarity search across the AI Platform use **Qdrant**. PostgreSQL holds only service/job state for the AI components, not embeddings.

For exact databases, environment variables, Kafka topics, and provisioning details, see the [AI Platform setup](../../setup-guides/ai-platform-setup) guide.

***

## Quick reference

| Data Store | Role | What it stores | Persistence |
| - | - | - | - |
| **PostgreSQL / Oracle** | System of record | Process definitions, config, metadata, instance state | Permanent |
| **MongoDB** | Document store | Runtime state, flexible data, FlowX Database | Permanent |
| **Redis** | Cache | Process definitions cache, sessions, locks | Transient |
| **Kafka** | Event streaming | Inter-service messages, integration events | Transient |
| **Object Storage** | File store | Attachments, documents, binary assets | Permanent |
| **Elasticsearch** | Search engine | Audit logs, indexed workflow data | Permanent |
| **Qdrant** | Vector database (AI) | Embeddings for RAG and semantic retrieval | Permanent |

***

## Service-level database mapping

The tables and diagrams below show which FlowX.AI services connect to which databases and what operations they perform. This is useful for infrastructure sizing, backup planning, and troubleshooting.

### PostgreSQL databases

Each core service owns its own PostgreSQL database and manages its schema through Liquibase migrations at startup.

```mermaid theme={"dark"}
flowchart LR
    subgraph Services
        ADM["Admin"]
        ADV["Advancing Controller"]
        APPM["Application Manager"]
        AUTH["Authorization System"]
        DOC["Document Plugin"]
        EMAIL["Email Gateway"]
        INTD["Integration Designer"]
        LIC["License"]
        ORG["Organization Manager"]
        ENG["Process Engine"]
        TASK["Task Management"]
        DSYNC["Data Sync"]
        WHG["Webhook Gateway"]
    end

    subgraph PostgreSQL
        ADVDB[("advancing")]
        APPMDB[("app_manager")]
        AUTHDB[("authorization_system")]
        DOCDB[("document_plugin")]
        EMAILDB[("email_gateway")]
        LICDB[("license")]
        ORGDB[("org_manager")]
        ENGDB[("process_engine")]
        WHGDB[("webhook_gateway")]
    end

    ADM -->|"reads, writes"| ENGDB
    ADV -->|"creates, reads, writes"| ADVDB
    APPM -->|"creates, reads, writes"| APPMDB
    AUTH -->|"creates, reads, writes"| AUTHDB
    DOC -->|"creates, reads, writes"| DOCDB
    EMAIL -->|"creates, reads, writes"| EMAILDB
    INTD -->|"reads, writes"| ADVDB
    LIC -->|"creates, reads, writes"| LICDB
    ORG -->|"creates, reads, writes"| ORGDB
    ENG -->|"creates, reads, writes"| ENGDB
    ENG -->|"reads, writes"| ADVDB
    TASK -->|"reads, writes"| ENGDB
    WHG -->|"creates, reads, writes"| WHGDB
    DSYNC -.->|"manages migrations"| APPMDB
    DSYNC -.->|"manages migrations"| AUTHDB
    DSYNC -.->|"manages migrations"| ENGDB
```

| Service | Database | Operations |
| - | - | - |
| Admin | `process_engine` | Reads, writes |
| Advancing Controller | `advancing` | Creates, reads, writes |
| Application Manager | `app_manager` | Creates, reads, writes |
| Authorization System | `authorization_system` | Creates, reads, writes |
| Document Plugin | `document_plugin` | Creates, reads, writes |
| Email Gateway | `email_gateway` | Creates, reads, writes |
| Integration Designer | `advancing` | Reads, writes |
| License | `license` | Creates, reads, writes |
| Organization Manager | `org_manager` | Creates, reads, writes |
| Process Engine | `process_engine` | Creates, reads, writes |
| Process Engine | `advancing` | Reads, writes |
| Task Management | `process_engine` | Reads, writes |
| Webhook Gateway | `webhook_gateway` | Creates, reads, writes |

> [!NOTE]
>
> Admin and Task Management share the `process_engine` database with Process Engine. Process Engine and Integration Designer share the `advancing` database with Advancing Controller. Data Sync acts as a centralized migration coordinator for `app_manager`, `authorization_system`, and `process_engine`.

### MongoDB databases

Each service manages its own MongoDB database. The `app-runtime` database is a shared read-only dependency for multiple services.

```mermaid theme={"dark"}
flowchart LR
    subgraph Services
        ADM["Admin"]
        APPM["Application Manager"]
        RTM["Runtime Manager"]
        CMS["CMS Core"]
        DOC["Document Plugin"]
        INTD["Integration Designer"]
        NOTIF["Notification Plugin"]
        SCHED["Scheduler"]
        TASK["Task Management"]
        ENG["Process Engine"]
        EMAIL["Email Gateway"]
        FILEG["File Gateway"]
        AIGW["AI Gateway"]
        NOSQL["NoSQL DB Runner"]
    end

    subgraph MongoDB
        DM[("data-model")]
        AR[("app-runtime")]
        CMSDB[("cms-core")]
        DOCDB[("document-plugin")]
        NOTIFDB[("notification-plugin")]
        SCHEDDB[("scheduler-core")]
        TASKDB[("task-management-plugin")]
        INTDDB[("integration-designer")]
        NOSQLDB[("nosql-db-runner")]
        FILEGDB[("file-gateway")]
        AIGWDB[("ai-gateway")]
    end

    ADM -->|"creates, reads, writes"| DM
    APPM -->|"creates, reads, writes"| AR
    RTM -->|"reads, writes"| AR
    CMS -->|"creates, reads, writes"| CMSDB
    CMS -->|"reads"| AR
    DOC -->|"creates, reads, writes"| DOCDB
    DOC -->|"reads"| AR
    INTD -->|"creates, reads, writes"| INTDDB
    INTD -->|"reads"| AR
    NOTIF -->|"creates, reads, writes"| NOTIFDB
    NOTIF -->|"reads"| AR
    SCHED -->|"creates, reads, writes"| SCHEDDB
    TASK -->|"creates, reads, writes"| TASKDB
    TASK -->|"reads"| AR
    ENG -->|"reads"| AR
    EMAIL -->|"reads"| AR
    NOSQL -->|"creates, reads, writes"| NOSQLDB
    FILEG -->|"creates, reads, writes"| FILEGDB
    AIGW -->|"creates, reads, writes"| AIGWDB
```

| Service | Database | Operations |
| - | - | - |
| Admin | `data-model` | Creates, reads, writes |
| Application Manager | `app-runtime` | Creates, reads, writes |
| Runtime Manager | `app-runtime` | Reads, writes |
| CMS Core | `cms-core` | Creates, reads, writes |
| CMS Core | `app-runtime` | Reads |
| Document Plugin | `document-plugin` | Creates, reads, writes |
| Document Plugin | `app-runtime` | Reads |
| Integration Designer | `integration-designer` | Creates, reads, writes |
| Integration Designer | `app-runtime` | Reads |
| Notification Plugin | `notification-plugin` | Creates, reads, writes |
| Notification Plugin | `app-runtime` | Reads |
| Scheduler | `scheduler-core` | Creates, reads, writes |
| Task Management | `task-management-plugin` | Creates, reads, writes |
| Task Management | `app-runtime` | Reads |
| Process Engine | `app-runtime` | Reads |
| Email Gateway | `app-runtime` | Reads |
| NoSQL DB Runner | `nosql-db-runner` | Creates, reads, writes |
| File Gateway | `file-gateway` | Creates, reads, writes |
| AI Gateway | `ai-gateway` | Creates, reads, writes |

> [!WARNING]
>
> The `app-runtime` database is created by Application Manager, written by Runtime Manager when it deploys builds, and read by 7 other services. It contains runtime configuration, build data, and deployed app state. Availability of this database is critical for runtime operations.

### Elasticsearch indexes

| Service | Index | Operations |
| - | - | - |
| Audit Core | Audit index | Creates, reads, writes |
| Process Engine | Process instance index | Creates, reads, writes |
| Data Search | Process instance index | Reads |

### Redis

Core services use Redis as a cache via Spring Cache Manager. Events Gateway, Integration Designer, and Process Engine also use Redis for more than caching, as the following table shows.

Services using Redis for caching: Admin, Application Manager, Authorization System, CMS Core, Document Plugin, Email Gateway, Integration Designer, License, Notification Plugin, Organization Manager, Process Engine, Runtime Manager, Task Management.

| Service | Usage |
| - | - |
| Events Gateway | Cache, Redis Streams to route messages to the instance that holds the SSE connection |
| Integration Designer | Cache, pub/sub for workflow cancellation |
| Process Engine | Cache, pub/sub for runtime configuration parameter changes |

### S3-compatible object storage buckets

> [!NOTE]
>
> Bucket names shown are defaults from the configuration and are configurable via environment variables (for example, `MINIO_BUCKET_PREFIX`). Your deployment may use different names. In some deployments, multiple services may share the same bucket. Ensure cross-bucket read access is configured where needed.
>
> The Document Plugin bucket prefix (`MINIO_BUCKET_PREFIX`) is a **prefix**, not a single bucket name. The service derives per-type buckets from it as `<prefix>-<type>`. With the default partition strategy (`NONE`), it stores process documents in one bucket per process instance, `<prefix>-process-id-<processInstanceId>`, files that are not tied to a process instance in `<prefix>-svc-file`, and test files in `<prefix>-test-documents`. The table shows the default prefix. Date partitioning and runtime buckets change this layout, see [Documents plugin setup](/5.9/setup-guides/documents-plugin-setup#runtime-buckets-configuration).

| Service | Default Bucket | Env Variable | Purpose |
| - | - | - | - |
| Application Manager | `applications-bucket` | — | App builds and exported/imported resources |
| CMS Core | `media-library-bucket` | — | Public media assets |
| CMS Core | `cms-private-storage-bucket` | — | Private theme and font files |
| Document Plugin | `flowx-dev-bucket` | `MINIO_BUCKET_PREFIX` | Document templates and generated files |
| Document Plugin | `temp-bucket` | `MINIO_TEMP_BUCKET` | Temporary processing files |
| Integration Designer | `workflows-bucket` | — | Workflow file uploads and Kafka messages above the payload size limit |
| Notification Plugin | `qdevlocal-preview-paperflow` | `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | Configured, but not used to store files. The plugin reads email attachments from Document Plugin buckets by their full path. |

> [!NOTE]
>
> Kafka messages larger than the payload size limit (`FLOWX_KAFKA_PAYLOADSIZELIMIT`, 512000 bytes by default) are not sent inline. The producer stores the message as a zip file under `payload-offload/` in its bucket and sends the path instead. The consumer reads the file from the bucket named in that path, so it needs read access to the producer's bucket. Integration Designer and the AI services use `workflows-bucket` for these files.

#### AI Platform buckets

The `flowx-ai` Helm chart does not set AI bucket names. The defaults below are the names the previous charts set. To set them in the `flowx-ai` chart, see [Migrate S3 buckets](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart#migrate-s3-buckets).

| Service | Default Bucket | Env Variable | Purpose |
| - | - | - | - |
| Agent Builder | `workflows-bucket` | `APPLICATION_FILE_STORAGE_S3_BUCKET_NAME` | Files that AI nodes read and write |
| Document Parser | `email-ingest` | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` | Email attachment scan results. Large Kafka messages go to `workflows-bucket`. |
| Document Converter | — | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` | PDF previews and conversion logs for email attachments |
| Speech-to-Text | — | — | Reads audio from the bucket the request names. Large Kafka messages go to `workflows-bucket`. |
| Data Privacy | `data-privacy-bucket` | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` | Source files for redaction jobs |
| Knowledge Base Indexer, Knowledge Base Enrichment | `kb-enrichment-bucket` (shared) | `APPLICATION_FILE_STORAGE_S3_BUCKET_NAME` | Enrichment payloads the indexer hands to the enrichment service, under `kb-enrichment/`. The indexer creates the bucket if it is missing. |

Document Parser, Document Converter, Speech-to-Text, and Data Privacy also read the file a request points to, usually stored in a Document Plugin bucket, with their own credentials. Grant each of them read access to those buckets. When called through their APIs, Document Converter and Data Privacy write the converted or redacted file next to the source file, so they also need write access there.

### Qdrant collections

The AI Platform stores vector embeddings in separate Qdrant collections. The `embedder` service writes vectors; retrieval and design-time services read them.

| Collection | Written by | Read by | Content |
| - | - | - | - |
| Runtime knowledge bases | Embedder | Knowledgebase RAG, Planner | Embeddings for knowledge bases queried by business agents at run time |
| Design-time knowledge bases | Embedder | KB Enrichment, Planner, Knowledgebase RAG | Layout-aware embeddings for documents used by the config-time agents in FlowX Designer |
| AI assistant | Snapshot on startup | AI Assistant | Pre-indexed documentation corpus for the AI assistant |

> [!NOTE]
>
> Collection names are versioned and encode the embedding models in use, so exact names vary by deployment and release. Treat the collection roles above as the stable reference.

***

## Related resources

> [card] [Third-party components](../platform-deep-dive/third-party-components)
>
> Supported versions and compatibility matrix

> [card] [FlowX Database](../platform-deep-dive/integrations/flowx-database)
>
> Cross-instance, long-term data storage using MongoDB

> [card] [FlowX.AI architecture](./flowx-architecture)
>
> Overall platform architecture and microservices overview

> [card] [Redis configuration](../../setup-guides/redis-configuration)
>
> Redis deployment modes and configuration

> [card] [AI Platform setup](../../setup-guides/ai-platform-setup)
>
> AI Platform data stores, environment variables, and Kafka topics


# FlowX.AI architecture: services, layers, and data flow
Source: https://docs.flowx.ai/5.9/docs/platform-overview/flowx-architecture

Explore the FlowX.AI microservices architecture: core engine, app lifecycle, authorization, business services, AI Platform, SDKs, and infrastructure.

## Overview

FlowX.AI is an event-driven platform built on specialized microservices that communicate primarily through Apache Kafka. The architecture is organized into distinct layers, each responsible for a specific concern, from process execution and app lifecycle management to authorization, content delivery, and AI-powered automation.

All backend services are containerized and deployed on Kubernetes. Client applications connect through an API Gateway that handles OAuth2 token validation and request routing.

> [!NOTE]
>
> For detailed database-to-service mapping and storage types, see the [Data architecture](./data-architecture) page.

***

## Architecture overview

![FlowX.AI 5.9 platform architecture with services, layers, and data stores](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.svg)

Almost all inter-service communication flows through Kafka, while the Events Gateway pushes real-time updates to clients via Server-Sent Events (SSE).

> [!TIP]
>
> Most Kafka topics follow the naming convention `ai.flowx.{service}.{action}.v1` (for example, `ai.flowx.core.trigger.advance.process.v1`). Some, mainly AI Platform job topics such as `ai.flowx.web-crawler.job.request`, have no version suffix.

### Explore interactively

Click a component to inspect its connections, use the guided views to walk the request and event paths, or [open the diagram full screen](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.html).

[⛶ Open full screen](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.html)

[Interactive FlowX.AI 5.9 platform architecture diagram](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/flowx-architecture-5.9.html)

***

## Service quick reference

Looking up a specific database or dependency? Everything is in this table; the sections after it explain each layer and service in detail. All services listen on port 8080, with the management (actuator) port on 8081. SpiceDB serves gRPC on port 50051.

| Service | Layer | Primary DB | Key Dependencies |
| - | - | - | - |
| **Process Engine** | Core Engine | PostgreSQL, MongoDB | Kafka, Redis, Elasticsearch, SpiceDB |
| **Advancing Controller** | Core Engine | PostgreSQL | Process Engine |
| **Events Gateway** | Core Engine | — | Redis, Kafka |
| **Scheduler Core** | Core Engine | MongoDB | Kafka |
| **Application Manager** | App Lifecycle | PostgreSQL, MongoDB | S3, SpiceDB |
| **Runtime Manager** | App Lifecycle | PostgreSQL, MongoDB | Redis, Application Manager |
| **Admin** | App Lifecycle | PostgreSQL, MongoDB | SpiceDB |
| **Data Sync** | App Lifecycle | — | PostgreSQL (3 DBs), MongoDB (8 DBs) |
| **CMS Core** | Content & Data | MongoDB | S3, SpiceDB |
| **Data Search** | Content & Data | Elasticsearch | Kafka |
| **NoSQL DB Runner** | Content & Data | MongoDB | — |
| **Integration Designer** | Content & Data | MongoDB, PostgreSQL | S3, SpiceDB |
| **Authorization System** | Auth & Security | PostgreSQL | SpiceDB |
| **SpiceDB** | Auth & Security | (embedded) | PostgreSQL |
| **Organization Manager** | Auth & Security | PostgreSQL | SpiceDB |
| **Document Plugin** | Plugins | PostgreSQL, MongoDB | S3 |
| **Notification Plugin** | Plugins | MongoDB | S3 |
| **Task Management** | Plugins | PostgreSQL, MongoDB | SpiceDB |
| **OCR Plugin** | Plugins | — | — |
| **Audit Core** | Supporting | Elasticsearch | Kafka |
| **Email Gateway** | Supporting | PostgreSQL, MongoDB | Kafka |
| **File Gateway** | Supporting | MongoDB | Kafka, Document |
| **Webhook Gateway** | Supporting | PostgreSQL | Kafka |
| **AI Gateway** | Supporting | MongoDB | SpiceDB, AI Platform |
| **License** | Supporting | PostgreSQL | — |
| **Document Parser** | AI Platform | — | Kafka, AI providers |
| **AI Platform (16 services)** | AI Platform | Qdrant | Kafka, AI providers |
| **FlowX Designer** | Client | — | API Gateway |
| **Web / Mobile SDKs** | Client | — | API Gateway, Events Gateway |

> [!NOTE]
>
> **SpiceDB is a startup dependency for more services than it serves.** The Authorization System, Admin, AI Gateway, Application Manager, Audit Core, CMS Core, Document Plugin, Email Gateway, File Gateway, Integration Designer, Notification Plugin, Task Management, and Process Engine include `spicedb` in their readiness health group, so those pods do not become ready while SpiceDB is unreachable. This includes the Process Engine, which serves runtime traffic but also checks design-time permissions on the process instance and incident endpoints that FlowX Designer calls.

> [!TIP]
>
> For detailed database names, S3 bucket names, and per-service operations (read/write), see the [Data architecture](./data-architecture) page.

***

## FlowX Designer

The **FlowX Designer** is a collaborative, no-code/full-code web app for building and managing processes, UIs, integrations, and other app components.

* **BPMN editor**: visual process designer built on Fabric.js canvas
* **UI designer**: drag-and-drop interface builder for web and mobile
* **Data model builder**: schema design and management
* **Integration designer UI**: visual workflow builder for external system connections
* **Script builder**: Monaco-based code editor for business rules (JavaScript, Python, MVEL, Groovy)
* **AI features**: embedded config-time agents, conversation system, command center
* **CMS, theme editor, access management**: content, branding, and permissions configuration

The Designer communicates with backend services through REST APIs, GraphQL, and SSE connections, all routed through the API Gateway.

> [!TIP]
>
> The Designer runs in the browser and is not deployed as part of the backend infrastructure. It connects to backend services through the API Gateway.

> [card] [FlowX Designer](../flowx-designer/overview)

***

## Core Engine layer

The Core Engine layer handles workflow execution, process orchestration, and real-time event delivery.

### Process Engine

The **Process Engine** is the central orchestration service that executes BPMN 2.0 process definitions and manages process instance lifecycles.

* Executes business processes and coordinates real-time interactions between users, systems, and data
* Manages process instances from creation through completion
* Supports multiple scripting languages: JavaScript and Python 3 (run by the native script engine by default), MVEL, and Groovy. The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine ([supported scripts](../building-blocks/supported-scripts)).
* Dynamically generates and delivers UI components based on process state

**Data stores:** PostgreSQL or Oracle (`process_engine`, `advancing`), MongoDB (`app-runtime` read), Redis (cache), Elasticsearch (indexing)

> [card] [Process Engine](../platform-deep-dive/core-components/flowx-engine)

### Advancing Controller

The **Advancing Controller** ensures efficient process instance progression, particularly in scaled deployments.

* Distributes workload evenly across Process Engine instances
* Redistributes work during scale-up and scale-down
* Prevents process instances from getting stuck if a worker pod fails
* Performs cleanup tasks and monitors worker pod status

**Data stores:** PostgreSQL (`advancing`)

> [card] [Advancing Controller](../platform-deep-dive/core-components/advancing-controller)

### Events Gateway

The **Events Gateway** centralizes real-time communication between backend services and frontend clients through Server-Sent Events (SSE).

* Routes and distributes messages from Kafka topics to appropriate frontend clients
* Enables real-time UI updates without page refreshes or polling
* Uses Redis Streams to ensure messages reach the correct instance holding the SSE connection

> [card] [Events Gateway](../platform-deep-dive/core-components/events-gateway)

### Scheduler Core

The **Scheduler Core** handles time-based operations within processes.

* Sets process expiration dates and reminders
* Triggers time-based events and activities
* Manages recurring tasks and delayed actions

**Data stores:** MongoDB (`scheduler-core`)

> [card] [Scheduler Core](../platform-deep-dive/core-extensions/scheduler)

***

## Application Lifecycle layer

The Application Lifecycle layer manages the full journey from design through build to deployment.

### Application Manager

The **Application Manager** handles project lifecycle management.

* Creates, updates, and deletes projects and their resources
* Manages versions, manifests, and configurations
* Serves as a proxy for frontend resource requests
* Handles project builds and deployments

**Data stores:** PostgreSQL (`app_manager`), MongoDB (`app-runtime`), S3 (`applications-bucket`)

> [card] [Projects](../projects/managing-applications/application)

### Runtime Manager

The **Runtime Manager** works alongside the Application Manager to deploy and manage apps in runtime environments.

* Deploys app builds to runtime environments
* Manages runtime configurations and environment-specific settings
* Monitors and manages active app instances

**Data stores:** PostgreSQL (`app_manager` shared), MongoDB (`app-runtime`), Redis (cache)

### Admin

The **Admin** service manages process definitions and platform-wide settings.

* Stores and edits process definitions and data models
* Manages user roles and permissions
* Configures system-wide settings

**Data stores:** PostgreSQL (`process_engine` shared), MongoDB (`data-model`)

### Data Sync

The **Data Sync** job coordinates database migrations and data synchronization across multiple services.

* Manages Liquibase migrations for `app_manager`, `authorization_system`, and `process_engine` databases
* Synchronizes resource definitions across MongoDB instances (CMS, Scheduler, Task Management, Document Plugin, Notification Plugin, Integration Designer)

***

## Content & Data layer

The Content & Data layer handles taxonomies, search, data persistence, and external system integrations.

### CMS Core

The **CMS Core** (Content Management System) manages all taxonomies and structured content within the platform.

* Manages enumerations, dropdown options, and categories
* Stores and serves localization content and translations
* Organizes media assets and reference data

**Data stores:** MongoDB (`cms-core`), S3 (`media-library-bucket`, `cms-private-storage-bucket`)

> [card] [Content Management](../platform-deep-dive/core-extensions/content-management/content-management)

### Data Search

The **Data Search** service enables search capabilities across process instances using Elasticsearch.

* Indexes process data automatically on status changes or at configured trigger points
* Supports filtering by process status, date ranges, and indexed keys
* Enables cross-app data discovery

**Data stores:** Elasticsearch (process instance index)

> [card] [Data Search](../platform-deep-dive/core-extensions/search-data-service)

### NoSQL DB Runner

The **NoSQL DB Runner** powers the FlowX Database feature, which stores structured data independently of process instances.

* Executes MongoDB operations (find, insert, update, delete)
* Supports both native MongoDB and Azure Cosmos DB (MongoDB API)
* Enables data sharing between different process instances

**Data stores:** MongoDB (`nosql-db-runner`)

> [card] [FlowX Database](../platform-deep-dive/integrations/flowx-database)

### Integration Designer

The **Integration Designer** provides a visual interface for creating and managing integrations with external systems.

* Defines REST API endpoints and authentication methods
* Creates and configures integration workflows with parallel branches
* Maps data between FlowX.AI processes and external systems
* Supports AI nodes for text, document, image, and data processing

**Data stores:** MongoDB (`integration-designer`), PostgreSQL or Oracle (`advancing`), S3 (`workflows-bucket`)

> [card] [Integration Designer](../platform-deep-dive/integrations/integration-designer)

***

## Authorization & Security layer

The Authorization & Security layer provides multi-tenant access control, workspace isolation, and identity management.

### Authorization System

The **Authorization System** is the centralized authorization service for the platform.

* Manages workspaces, users, groups, roles, and permissions
* Enforces access control lists (ACLs) for fine-grained resource permissions
* Provides RBAC (role-based access control) at organization, workspace, and project levels
* Covers both designer users and runtime end users, through two separate decision engines

**Data stores:** PostgreSQL (`authorization_system`), SpiceDB (design-time ACL operations)

> [!NOTE]
>
> **Two decision engines, one service.** Designer users and runtime end users are both managed by the Authorization System, and both are stored in the `authorization_system` PostgreSQL database. What differs is how a permission decision is made: designer-time permissions are relationship tuples evaluated in SpiceDB, while runtime permissions are resolved from relational tables in the same PostgreSQL database. The two do not interact at runtime.

### SpiceDB

**SpiceDB** is a relationship-based access control (ReBAC) engine inspired by Google's Zanzibar paper.

* Stores and evaluates design-time authorization policies
* Provides consistent, fine-grained permission decisions for Designer access checks
* Supports reverse lookups (finding all resources a user can access)

> [!NOTE]
>
> **Scope: design-time permissions only.** SpiceDB backs build-time access checks in the FlowX Designer (who can edit which workspace, project, or resource). Runtime permissions, meaning which end users can interact with which solution at execution time, use a separate custom implementation inside the Authorization System that does not call SpiceDB. See [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization).

> [!NOTE]
>
> SpiceDB ships with the platform rather than being sourced by the customer, but it runs as its own workload and is installed through the SpiceDB operator. See the [SpiceDB setup guide](/5.9/setup-guides/spicedb) for the installation steps.

### Organization Manager

The **Organization Manager** handles organization and tenant lifecycle management.

* Manages organization creation and provisioning
* Handles user registration and onboarding
* Monitors platform component health
* Publishes organization lifecycle events to Kafka

**Data stores:** PostgreSQL (`org_manager`)

### Multi-tenancy and workspaces

FlowX.AI uses **workspaces** to provide logical data isolation across the platform. Each workspace operates independently with its own resources (projects, libraries, themes) and access controls. The Authorization System, SpiceDB, and Organization Manager work together to enforce tenant boundaries while allowing users to belong to multiple workspaces.

> [card] [Workspaces](../projects/workspaces)

### Identity providers

FlowX.AI delegates authentication to external identity providers. Every request passes through the API Gateway, which validates OAuth2 tokens before allowing access.

> [card] [Keycloak](../../setup-guides/access-management/configuring-an-iam-solution)

> [card] [Azure AD (Entra)](../../setup-guides/access-management/configuring-an-iam-solution-entra)

***

## Business services

Business services extend the core engine with domain-specific capabilities. Document, Notification, and Task Management are deployed as core backend services alongside the engine; OCR and Reporting are formal plugins that ship through the Plugins versioning track.

### Document

Handles document generation and management.

* Generates documents from HTML templates
* Supports file upload, conversion, splitting, combining, and encryption/decryption
* Manages document storage and retrieval

**Data stores:** PostgreSQL (`document_plugin`), MongoDB (`document-plugin`, `app-runtime` read), S3 (`flowx-dev-bucket` prefix, `temp-bucket`)

### Notification

Manages notifications across multiple channels.

* Sends email, SMS, and push notifications
* Handles OTP (one-time password) generation and validation
* Supports notification templates with dynamic content substitution

**Data stores:** MongoDB (`notification-plugin`, `app-runtime` read), S3 (`qdevlocal-preview-paperflow` prefix)

### Task Management

Handles human task assignment and lifecycle.

* Manages task creation, assignment, and completion
* Supports allocation rules and out-of-office delegation
* Provides multi-language localization with substitution tags

**Data stores:** PostgreSQL (`process_engine` shared), MongoDB (`task-management-plugin`, `app-runtime` read)

> [card] [Task Management](../platform-deep-dive/core-extensions/task-management/task-management-overview)

### OCR (plugin)

The **OCR Plugin** provides optical character recognition for document processing and data extraction.

### Reporting (plugin)

The **Reporting Plugin** powers analytics and dashboards, integrating with Apache Superset for visualization.

> [card] [Plugins](../platform-deep-dive/plugins/custom-plugins)

***

## Supporting services

Supporting services provide cross-cutting capabilities like auditing, email communication, and licensing.

### Audit Core

The **Audit Core** service provides a centralized audit trail for all platform activities.

* Logs user actions and system events with timestamps, subjects, and status
* Stores audit data in Elasticsearch for efficient querying
* Ingests events from Kafka topic `ai.flowx.core.trigger.save.audit.v1`

**Data stores:** Elasticsearch (audit index)

> [card] [Audit](../platform-deep-dive/core-extensions/audit)

### Email Gateway

The **Email Gateway** handles email communication workflows.

* Receives emails via IMAP or Microsoft Graph
* Monitors configured mailboxes and publishes incoming email events to Kafka for process triggering
* Supports leader election for high availability across distributed instances

**Data stores:** PostgreSQL (`email_gateway`), MongoDB (`app-runtime` read)

### File Gateway

The **File Gateway** handles file-transfer integrations with external storage systems.

* Connects to FTP, SFTP, S3, and Azure Blob storage to ingest files into workflows and deliver generated artifacts back
* Polls watched locations for new files, uploads them to the Document service, and publishes Kafka events to start processes (file triggers)
* Supports distributed leasing for high availability across instances, mirroring the Email Gateway

**Data stores:** MongoDB (`file-gateway`)

### Webhook Gateway

The **Webhook Gateway** receives inbound webhook calls from external systems and uses them to trigger FlowX processes.

* Exposes a public, API-key-authenticated `/webhooks/**` endpoint that external systems call over HTTP
* On a valid request, publishes Kafka events that the Process Engine consumes to start a new process instance or resume a waiting message-catch event
* Producer-only to Kafka: it does not consume any topics
* Requires ingress to be enabled, since it receives HTTP requests from outside the cluster

**Data stores:** PostgreSQL (`webhook_gateway`)

### AI Gateway

The **AI Gateway** powers the AI chat experience in the FlowX Designer.

* Streams AI assistant responses to the Designer in real time via Server-Sent Events (SSE)
* Routes chat requests to the config-time agents and manages conversation context
* Enforces workspace-level access control on AI interactions

**Data stores:** MongoDB, SpiceDB (ACL operations)

### License

The **License** service (formerly known as the License Engine) manages platform and app licensing, subscription plans, feature quotas, and usage tracking for FlowX organizations across SaaS and self-hosted deployments.

For setup and configuration, see [License service setup](/5.9/setup-guides/license-engine-setup).

**Data stores:** PostgreSQL (`license`)

***

## AI Platform

The **AI Platform** extends FlowX.AI with intelligent agents that operate at two levels:

* **Config-time agents**: embedded in the FlowX Designer to help developers and analysts build apps faster (AI Analyst, AI Designer, AI Developer, AI Assistant)
* **Business agents**: power end-user experiences at runtime, built with the Agent Builder or installed from the Agentic Apps Marketplace

As of 5.9.2, the AI Platform comprises 17 services: `ai-developer`, `planner`, `ai-analyst`, `ai-architect`, `ai-designer`, `agent-builder`, `ai-assistant`, `embedder`, `kb-enrichment`, `knowledgebase-rag`, `knowledgebase-indexer-v2`, `doc-parser`, `doc-converter`, `web-crawler`, `data-privacy`, `speech-to-text`, and `evals-judge`. [Observatory](/5.9/observatory/overview), for AI observability and governance, is not part of these services: it deploys as its own stack, and agents report to it through the Observatory SDK.  Vector storage and retrieval are handled by **Qdrant** (embedded). On 5.9.0 and 5.9.1, most of these services carry an `ai-platform-` name prefix (for example, `ai-platform-planner`), which 5.9.2 drops; `ai-architect` is available only starting with 5.9.2 and does not exist in earlier 5.9.x deployments. In 5.9.0 this tier shipped `di-platform`, which was decommissioned into `kb-enrichment` in 5.9.1.

### Document and utility AI services

Six of the AI Platform services handle document processing, ingestion, transcription, and evaluation workloads. On 5.9.0 and 5.9.1 they installed via separate paths and versioned independently; starting with 5.9.2 they deploy as part of the AI Platform chart and version with it:

* **doc-parser**: document parsing engine (PDF, DOCX, XLSX, PPTX, images; supports Tesseract and EasyOCR, plus RapidOCR up to 5.9.5; semantic chunking for RAG; signature detection; table extraction)
* **doc-converter**: document format conversion
* **web-crawler**: web content ingestion for the Web Page Extractor node
* **data-privacy**: PII detection and redaction (PII Guard)
* **speech-to-text**: audio transcription for voice and call workflows
* **evals-judge**: LLM-as-judge evaluation service for scoring agent and model outputs

**modpod**, a supporting runtime service, remains standalone: it installs via its own path and versions on its own cadence.

> [card] [AI Platform](../../ai-platform/ai-in-flowx)

***

## Client SDKs

The FlowX.AI SDKs provide process renderers that display dynamic UIs and orchestrate user interactions on each platform. The SDK architecture uses a framework-agnostic core (`@flowx/core-sdk`) with platform-specific wrappers.

> [card] [Angular SDK](../../sdks/angular-renderer)
>
> `@flowx/angular-sdk` for Angular applications

> [card] [React SDK](../../sdks/react-renderer)
>
> `@flowx/react-sdk` for React applications

> [card] [React Native SDK](../../sdks/react-native-renderer)
>
> Renderer for React Native applications

> [card] [iOS SDK](../../sdks/ios-renderer)
>
> Native iOS renderer

> [card] [Android SDK](../../sdks/android-renderer)
>
> Native Android renderer

> [!NOTE]
>
> The SDKs include companion packages for theming (`@flowx/core-theme`, plus `@flowx/angular-theme`, `@flowx/react-theme`, or `@flowx/react-native-theme`) and UI components (`@flowx/angular-ui-toolkit`, `@flowx/react-ui-toolkit`, or `@flowx/react-native-ui-toolkit`).

***

## Service communication

The following diagram shows the typical request flow through the platform:

```mermaid theme={"dark"}
sequenceDiagram
    participant Client as Client app (SDK)
    participant GW as API Gateway
    participant Engine as Process Engine
    participant Kafka as Kafka
    participant Plugin as Plugin / Integration
    participant Events as Events Gateway

    Client->>GW: Start process (REST + OAuth2 token)
    GW->>Engine: Forward authenticated request
    Engine->>Kafka: Publish process event
    Kafka->>Plugin: Route to plugin or integration
    Plugin->>Kafka: Return result event
    Kafka->>Engine: Deliver result
    Engine->>Kafka: Publish UI update event
    Kafka->>Events: Route SSE event
    Events->>Client: Push real-time update (SSE)
```

1. **Client applications** initiate processes through the API Gateway using REST calls with an OAuth2 token
2. The **Process Engine** executes the process definition and publishes events to Kafka
3. **Plugins and integrations** consume events, perform their work, and publish results back to Kafka
4. The **Events Gateway** picks up UI update events and pushes them to connected clients via SSE

Because these steps run asynchronously, long-running processes don't block the user: the UI stays responsive while external systems process requests in the background.

***

## Infrastructure

FlowX.AI requires the following infrastructure components:

* **PostgreSQL / Oracle**: system of record for process definitions, instance state, and platform configuration
* **MongoDB**: document storage for runtime configuration, workflow state, and flexible data structures
* **Redis**: in-memory cache for process definitions and distributed locks
* **Apache Kafka**: event streaming backbone for most inter-service communication
* **Elasticsearch**: search indexes for process data and audit logs
* **S3-compatible storage**: files, documents, and binary assets
* **Qdrant**: vector database for the AI Platform RAG path (embedded)

All services are containerized and designed for Kubernetes deployment. Stateless components support horizontal scaling, and Kafka provides resilient message handling across scaled instances.

> [card] [Data architecture](./data-architecture)
>
> Database-to-service mapping and storage details

> [card] [Third-party components](../platform-deep-dive/third-party-components)
>
> Supported versions and compatibility matrix

***

## Quick demo

<video title="Introduction to FlowX.AI: architecture overview" aria-label="Introduction to FlowX.AI: architecture overview video" />

***

## Related resources

> [card] [Data architecture](./data-architecture)
>
> Database-to-service mapping and storage types

> [card] [Third-party components](../platform-deep-dive/third-party-components)
>
> Supported versions and compatibility matrix

> [card] [AI Platform](../../ai-platform/ai-in-flowx)
>
> AI agents for config-time and runtime

> [card] [SDKs overview](../../sdks/sdks-overview)
>
> Web and mobile SDK documentation


# Intro to BPMN
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn

A process represents your business use case, such as requesting a credit card, placing a food order, or registering a vehicle.

FlowX.AI processes are designed and modeled using **BPMN 2.0**, the industry-standard graphical notation for business processes. This page introduces the BPMN elements you work with in the FlowX.AI Designer, events, activities, gateways, and pools and lanes, and what each one does in a process flow.

## What is Business Process Model and Notation (BPMN)?

Business Process Model and Notation (BPMN) is a graphical representation for specifying business processes in a business process model.

It is **the most widely used standard for business process diagrams**. It is intended to be used directly by the stakeholders who design, manage and realize business processes, but at the same time be precise enough to allow BPMN diagrams to be translated into software process components.

This is why we chose it for modeling the process flows.

## BPMN 2.0 elements

A BPMN business process flow is represented as a set of process elements connected by sequences. Here are the most common types of elements:

> [card] [Events](#events)

> [card] [Activities](#activities)

> [card] [Gateways](#gateways)

> [card] [Pools and lanes](#pools-and-lanes)

### Events

Events describe something that happens during the course of a process. There are three main events types: start events, intermediate events, and end events. These three types are also defined as either catching events (they react to a trigger) or throwing events (they are triggered by the process).

![basic event types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/events.png)

### Activities

An activity represents a unit of work to be performed by the business process. An activity can be atomic (a task) or can represent a group of more activities (a subprocess).

![various types of activities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/activities.png)

### Gateways

Gateways are used to control how a process flows. They act as a decision point that picks which sequence flow should the [**process instance**](../../../projects/runtime/active-process/process-instance) take. This is based on the result of the evaluation of condition(s) specified (in case of exclusive gateways) or they can be used to split a process into more branches (in case of parallel gateways).

![exclusive and parallel gateways](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/gateways.png)

### Pools and lanes

Pools and lanes group the process steps by process participants. To show that certain user roles are responsible for performing specific process steps you can divide the process using lanes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/swimlanes_pool.png)

## BPMN basic concepts

Let's get into a bit more details on the main types of BPMN process elements.

### Events

Events are signals that something happens within a process, including its start and end and any interactions with the process environment.

Types of Events:

* Start Events
* End Events
* Intermediate Events

### Start and End events

**Start & End events**

| Start Event Icon | End Event Icon |
| :-: | :-: |
| ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/event_start.png) | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/event_end.png) |
| Event that triggers the process | Event that defines the state that terminates the process |

### Intermediate events

An intermediate event occurs between a start and an end event. It is represented by a circle with a double line, indicating its ability to both catch and throw information.

#### Message events

Message events serve as a means to incorporate messaging capabilities into business process modeling. These events are specifically designed to capture the interaction between different process participants by referencing messages.

### Activities

#### Task

An atomic activity within a process flow, created when the activity cannot be broken down further. A task belongs to one lane.

| User task | Service task |
| :-: | :-: |
| ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/user_task.png#center) | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn/bpmn-basic-concepts/service_task.png#center) |
| A task that requires human action | A task that uses a web service, automated application, or other kinds of service in completing the task |

#### User Task

A task performed by the user without aid from a business process execution engine or application, requiring a certain action in the application.

#### Service Task

Executed by a business process engine. The task defines a script that the FlowX Engine can interpret and execute, completing when the script finishes. It can also run a [**business rule**](../../../building-blocks/actions/business-rule-action/business-rule-action) on the process data.

### BPMN Subprocesses

In BPMN, a subprocess is a compound activity that represents a collection of other tasks and subprocesses. Generally, we create BPMN diagrams to communicate processes with others. To facilitate effective communications, we really do not want to make a business process diagram too complex. By using subprocesses, you can split a complex process into multiple levels, which allows you to focus on a particular area in a single process diagram.

### Gateways

Gateways allow to control as well as merge and split the **process flow**.

#### Exclusive gateways

In business processes, you typically need to make choices — **business decisions**. The most common type of decision is choosing **either/or**. Exclusive Gateways limit the possible outcome of a decision to a single path, and circumstances choose which one to follow.

#### Parallel gateways

In many cases, you want to split up the flow within your business process. For example the sales and risk departments may examine a new mortgage application at the same time. This reduces the total cycle time for a case. To express parallel flow in BPMN, you use a **parallel gateway**.

| Exclusive gateway (XOR) | Parallel gateway (AND) |
| :-: | :-: |
| ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/gateway_exclusive.png#center) | ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-overview/frameworks-and-standards/business-process-industry-standards/gateway_parallel.png#center) |
| <ul><li>defines a decision point</li></ul> | <ul><li>no decision making </li><li>all outgoing branches are activated</li></ul> |

**Closing gateway**

* Closes gateways by connecting branches with no logic involved
* The symbol used is determined by the initial gateway type.
* Parallel gateways:
  * These gateways wait for all input tokens and merge them into a single token.
  * Are aware of all preceding token flows, know the paths selected, and expect tokens from these paths.

## In depth docs

> [card] [BPMN Quick guide](https://www.bpmnquickguide.com/view-bpmn-quick-guide/)

> [card] [BPMN Best practices](https://bpmtips.com/interview-with-sandeep-johal-process-modeling-best-practices/)

For comprehensive insights into BPMN and its various node types, explore our course at FlowX Academy:

> [card] [BPMN 101](https://academy.flowx.ai/explore/bpmn-101)
>
> * What's BPMN (Business Process Model Notation) and how does it work?
> * How is BPMN used in FlowX?


# Intro to Elasticsearch
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch

Integrate Elasticsearch into event-driven architectures and workflows to efficiently index and search event data.

This integration allows event-driven systems to use Elasticsearch’s search and analytics capabilities for real-time processing and retrieval of event data.

## What is Elasticsearch?

Elasticsearch is a highly scalable open-source search and analytics engine built on top of the [Apache Lucene](https://lucene.apache.org/) library. It is designed to handle a wide range of data types and is particularly well-suited for real-time search and data analysis use cases. Elasticsearch provides a distributed, document-oriented architecture, making it capable of handling large volumes of structured, semi-structured, and unstructured data.

## How it works?

At its core, Elasticsearch operates as a distributed search engine, allowing you to store, search, and retrieve large amounts of data in near real-time. It uses a schema-less JSON-based document model, where data is organized into indices, which can be thought of as databases. Within an index, documents are stored, indexed, and made searchable based on their fields. Elasticsearch also provides advanced querying capabilities, allowing you to perform complex searches, filter data, and aggregate results.

## Why it is useful?

One of the key features of Elasticsearch is its distributed nature. It supports automatic data sharding, replication, and node clustering, which enables it to handle massive amounts of data across multiple servers or nodes. This distributed architecture provides high availability and fault tolerance, ensuring that data remains accessible even in the event of hardware failures or network issues.

Elasticsearch integrates with various programming languages and frameworks through its comprehensive RESTful API. It also provides official clients for popular languages like Java, Python, and JavaScript, enabling you to interact with the search engine in your preferred development environment.

## Indexing & sharding

### Indexing

Indexing refers to the process of adding, updating, or deleting documents in Elasticsearch. It involves taking data, typically in JSON format, and transforming it into indexed documents within an index. Each document represents a data record and contains fields with corresponding values. Elasticsearch uses an inverted index data structure to efficiently map terms or keywords to the documents containing those terms. This enables fast full-text search capabilities and retrieval of relevant documents.

### Sharding

Sharding, on the other hand, is the practice of dividing index data into multiple smaller subsets called shards. Each shard is an independent, self-contained index that holds a portion of the data. By distributing data across multiple shards, Elasticsearch achieves horizontal scalability and improved performance. Sharding allows Elasticsearch to handle large amounts of data by parallelizing search and indexing operations across multiple nodes or servers.

Shards can be configured as primary or replica shards. Primary shards contain the original data, while replica shards are exact copies of the primary shards, providing redundancy and high availability. By having multiple replicas, Elasticsearch ensures data durability and fault tolerance. Replicas also enable parallel search operations, increasing search throughput.

Sharding offers several advantages. It allows data to be distributed across multiple nodes, enabling parallel processing and faster search operations. It also provides fault tolerance, as data is replicated across multiple shards. Additionally, sharding allows Elasticsearch to scale horizontally by adding more nodes and distributing the data across them.

The number of shards and their allocation can be determined during index creation or modified later. Consider factors such as the size of the dataset, hardware resources, and search performance requirements when deciding on the number of shards.

For more details, check Elasticsearch documentation:

> [card] [Elasticsearch documentation](https://www.elastic.co/guide/index.html)

## Using Elasticsearch for advanced indexing with FlowX.AI

The integration between FlowX.AI and Elasticsearch involves the indexing of specific keys or data from the [**UI Designer**](../../../building-blocks/ui-designer/) to [process definitions](../../../building-blocks/process/process-definition). The indexing process is initiated by the [FlowX Engine](../../../platform-deep-dive/core-components/flowx-engine) which sends the data to Elasticsearch, where data is then indexed in the "process\_instance" index.

There are two methods available for indexing data: Kafka and HTTP.

* **Kafka**: Data is sent to be indexed through a Kafka topic using the new strategy. Deploy the [**Kafka Connect with Elasticsearch Sink Connector**](../../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#step-2-deploy-kafka-connect) in the infrastructure to utilize this method.
* **HTTP**: Data is indexed by establishing a direct connection from the FlowX Engine to Elasticsearch. Use HTTP calls to connect directly from the FlowX Engine to Elasticsearch.

To ensure effective indexing of process instances' details, a crucial step involves defining a mapping that specifies how Elasticsearch should index the received messages. This mapping is essential as the process instances' details often have specific formats. The process-engine takes care of this by automatically creating an index template during startup if it doesn't already exist. The index template acts as a blueprint, providing Elasticsearch with the necessary instructions on how to index and organize the incoming data accurately. By establishing and maintaining an appropriate index template, the integration between FLOWX.AI and Elasticsearch can index and retrieve process instance information in a structured manner.

### Kafka transport strategy

[Kafka](../event-driven-architecture-frameworks/intro-to-kafka-concepts) transport strategy implies process-engine sending messages to a Kafka topic whenever there is data from a process instance to be indexed. Kafka Connect is then configured to read these messages from the topic and forward them to Elasticsearch for indexing.

This approach offers benefits such as fire-and-forget communication, where the process-engine no longer needs to spend time handling indexing requests. By decoupling the process-engine from the indexing process and leveraging Kafka as a messaging system, the overall system becomes more efficient and scalable. The process-engine can focus on its core responsibilities, while Kafka Connect takes care of transferring the messages to Elasticsearch for indexing.

To optimize indexing response time, Elasticsearch utilizes multiple indices created dynamically by the Kafka Connect connector. The creation of indices is based on the timestamp of the messages received in the Kafka topic. The frequency of index creation, such as per minute, hour, week, or month, is determined by the timestamp format configuration of the Kafka connector.

It's important to note that the timestamp used for indexing is the process instance's start date. This means that subsequent updates received for the same object will be directed to the original index for that process instance. To ensure proper identification and indexing, it is crucial that the timestamp of the message in the Kafka topic corresponds to the process instance's start date, while the key of the message aligns with the process instance's UUID. These two elements serve as unique identifiers for determining the index in which a process instance object was originally indexed.

For more details on how to configure process instance indexing through Kafka transport, check the following section:

> [card] [Configuring Elasticsearch indexing](../../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing)

> [card] [Configuration guidelines](../../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/process-instance-indexing-config-guidelines)


# Intro to Kafka concepts
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts

Apache Kafka is an open-source distributed event streaming platform that can handle a high volume of data and enables you to pass messages from one end-point to another.

Kafka is a unified platform for handling all the real-time data feeds. Kafka supports low latency message delivery and gives a guarantee for fault tolerance in the presence of machine failures. It can handle many diverse consumers. Kafka is very fast, and performs 2 million writes/sec. Kafka persists all data to the disk, which essentially means that all the writes go to the page cache of the OS (RAM). This makes it very efficient to transfer data from a page cache to a network socket.

### Benefits of using Kafka

* **Reliability** − Kafka is distributed, partitioned, replicated, and fault-tolerant
* **Scalability** − Kafka messaging system scales without downtime
* **Durability** − Kafka uses Distributed commit log which means messages persist on disk as fast as possible
* **Performance** − Kafka has high throughput for both publishing and subscribing messages. It maintains a stable performance even though many TB of messages are stored.

## Key Kafka concepts

### Events

Kafka encourages you to see the world as sequences of events, which it models as key-value pairs. The key and the value have some kind of structure, usually represented in your language’s type system, but fundamentally they can be anything. Events are immutable, as it is (sometimes tragically) impossible to change the past.

### Topics

Because the world is filled with so many events, Kafka gives us a means to organize them and keep them in order: topics. A topic is an ordered log of events. When an external system writes an event to Kafka, it is appended to the end of a topic.

In FLOWX.AI, Kafka handles all communication between the [FlowX Engine](../../../platform-deep-dive/core-components/flowx-engine) and external plugins and integrations. It is also used for notifying running process instances when certain events occur.  More information about KAFKA configuration on the section below:

> [card] [FlowX Engine setup guide](../../../../setup-guides/flowx-engine-setup-guide/engine-setup)

### Producer

A producer is an external application that writes messages to a Kafka cluster, communicating with the cluster using Kafka’s network protocol.

### Consumer

The consumer is an external application that reads messages from Kafka topics and does some work with them, like filtering, aggregating, or enriching them with other information sources.

> [card] [How to create a Kafka producer](../../../platform-deep-dive/integrations/creating-a-kafka-producer)

> [card] [How to create a Kafka consumer](../../../platform-deep-dive/integrations/creating-a-kafka-consumer)

## In-depth docs

> [card] [Kafka documentation](https://kafka.apache.org/intro)

> [card] [How Kafka works](https://www.confluent.io/blog/apache-kafka-intro-how-kafka-works/)


# Intro to Kubernetes
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kubernetes

Kubernetes is an open-source container orchestration platform that automates many of the manual processes involved in containerized application deployment, management, and scaling.

The purpose of Kubernetes is to orchestrate containerized applications to run on a cluster of hosts. **Containerization** enables you to deploy multiple applications using the same operating system on a single virtual machine or server.

Kubernetes, as an open platform, enables you to build applications using your preferred programming language, operating system, libraries, or messaging bus. To schedule and deploy releases, existing continuous integration and continuous delivery (CI/CD) tools can be integrated with Kubernetes.

## Benefits of using Kubernetes

* A proper way of managing containers
* High availability
* Scalability
* Disaster recovery

## Key Kubernetes concepts

### Node & PODs

A Kubernetes node is a machine that runs containerized workloads as part of a Kubernetes cluster. A node can be a physical machine or a virtual machine, and can be hosted self-hosted or in the cloud.

A pod is composed of one or more containers that are colocated on the same host and share a network stack as well as other resources such as volumes. Pods are the foundation upon which Kubernetes applications are built.

Kubernetes uses pods to run an instance of your application. A pod represents a single instance of your application.

Pods are typically ephemeral, disposable resources. Individually scheduled pods miss some of the high availability and redundancy Kubernetes features. Instead, pods are deployed and managed by Kubernetes *Controllers*, such as the Deployment Controller.

### Service & Ingress

**Service** is an abstraction that defines a logical set of pods and a policy for accessing them. In Kubernetes, a Service is a REST object, similar to a pod. A Service definition, like all REST objects, can be POSTed to the API server to create a new instance. A Service object's name must be a valid [RFC 1035](https://www.ietf.org/rfc/rfc1035.txt) label name.

**Ingress** is a Kubernetes object that allows access to the Kubernetes services from outside of the Kubernetes cluster. You configure access by writing a set of rules that specify which inbound connections are allowed to reach which services. This allows combining all routing rules into a single resource.

**Ingress controllers** are pods, just like any other application, so they’re part of the cluster and can see and communicate with other pods.  An Ingress can be configured to provide Services with externally accessible URLs, load balance traffic, terminate SSL / TLS, and provide name-based virtual hosting. An Ingress controller is in charge of fulfilling the Ingress, typically with a load balancer, but it may also configure your edge router or additional frontends to assist with the traffic.

FlowX.AI offers a predefined NGINX setup as Ingress Controller. The [NGINX Ingress Controller](https://www.nginx.com/products/nginx-ingress-controller/) works with the [NGINX](https://www.nginx.com/resources/glossary/nginx/) web server (as a proxy). For more information, check the below sections:

> [card] [Intro to NGINX](./intro-to-nginx)

> [card] [FlowX Designer setup guide](../../../../setup-guides/designer-setup-guide)

### ConfigMap & Secret

**ConfigMap** is an API object that makes it possible to store configuration for use by other objects. A ConfigMap, unlike most Kubernetes objects with a spec, has `data` and `binaryData` fields. As values, these fields accept key-value pairs. The `data` field and `binaryData` are both optional. The data field is intended to hold UTF-8 strings, whereas the `binaryData` field is intended to hold binary data as base64-encoded strings.

> [!NOTE]
>
> The name of a ConfigMap must be a valid [DNS subdomain name](https://www.ietf.org/rfc/rfc1035.txt).

**Secret** represents an amount of sensitive data, such as a password, token, or key. Alternatively, such information could be included in a pod specification or a container image. Secrets are similar to ConfigMaps but they are designed to keep confidential data.

### **Volumes**

A Kubernetes volume is a directory in the orchestration and scheduling platform that contains data accessible to containers in a specific pod. Volumes serve as a plug-in mechanism for connecting ephemeral containers to persistent data stores located elsewhere.

### **Deployment**

A deployment is a collection of identical pods that are managed by the Kubernetes Deployment Controller. A deployment specifies the number of pod replicas that will be created. If pods or nodes encounter problems, the Kubernetes Scheduler ensures that additional pods are scheduled on healthy nodes.

Typically, deployments are created and managed using `kubectl create` or `kubectl apply`. Make a deployment by defining a manifest file in YAML format.

## Kubernetes architecture

Kubernetes architecture consists of the following main parts:

* Control Plane (master)
  * kube-apiserver
  * etcd
  * kube-scheduler
  * kube-controller-manager
  * cloud-controller-manager
* Node components
  * kubelet
  * kube-proxy
  * Container runtime

## Install tools

### kubectl

`kubectl` makes it possible to run commands against Kubernetes clusters using the `kubectl` command-line tool. `kubectl` can be used to deploy applications, inspect and manage cluster resources, and inspect logs. See the `kubectl` [reference documentation ](https://kubernetes.io/docs/reference/kubectl/)for more information.

### kind

`kind` command makes it possible to run Kubernetes on a local machine. As a prerequisite, Docker needs to be installed and configured. What `kind` is doing is to run local Kubernetes clusters using Docker container “nodes”.

## In depth docs

> [card] [Kubernetes documentation](https://kubernetes.io/docs/home/)


# Intro to NGINX
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-nginx

NGINX is a free, open-source, high-performance web server with a rich feature set, simple configuration, and low resource consumption that can also function as a reverse proxy, load balancer, mail proxy, HTTP cache, and many other things.

### How NGINX is working?

NGINX allows you to hide a server application's complexity from a front-end application. It uses an event-driven, asynchronous approach to create a new process for each web request, with requests handled in a single thread.

### Using NGINX with FlowX Designer

[**The NGINX Ingress Controller for Kubernetes**](https://kubernetes.github.io/ingress-nginx/) - `ingress-nginx` is an ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.

Ingress allows you to route requests to services based on the host or path of the request, centralizing a number of services into a single entry point.

The [ingress resource](https://www.nginx.com/products/nginx-ingress-controller/nginx-ingress-resources/) simplifies the configuration of **SSL/TLS** **termination**, **HTTP load-balancing**, and **layer routing**.

For more information, check the following section:

> [card] [Using NGINX as a K8s ingress controller](https://www.nginx.com/resources/videos/using-nginx-as-a-kubernetes-ingress-controller)

#### Integrating with FlowX Designer

FlowX Designer is using NGINX ingress controller for the following actions:

1. For routing calls to plugins
2. For routing calls to the [FlowX Engine](../../../platform-deep-dive/core-components/flowx-engine):

* Viewing current instances of processes running in the FlowX Engine
* Testing process definitions from the FlowX Designer - route the API calls and SSE communications to the FLOWX engine backend
* Accessing REST API of the backend microservice

3. For configuring the Single Page Application (SPA) - FlowX Designer SPA will use the backend service to manage the platform via REST calls

In the following section, you can find a suggested NGINX setup, the one used by FlowX.AI:

> [card] [Designer setup guide](../../../../setup-guides/designer-setup-guide)

### Installing NGINX Open Source

For more information on how to install NGINX Open Source, check the following guide:

> [card] [NGINX Admin Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source?_ga=2.31029759.1179818521.1651763502-1509066026.1651763502)


# Intro to Redis
Source: https://docs.flowx.ai/5.9/docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis

Open-source, in-memory key-value data store used as a cache for fast access to frequently used data with sub-millisecond response times.

It is also used as a Pub/Sub messaging solution, allowing messages to be passed to channels and for all subscribers to that channel to receive that message. This feature enables information to flow quickly through the platform without using up space in the database as messages are not stored.

Redis offers a primary-replica architecture in a single node primary or a clustered topology. This allows you to build highly available solutions providing consistent performance and reliability. You can scale the cluster size up or down, allowing the cluster to adjust to any demands.

## In depth docs

> [card] [Redis.io](https://redis.io/)

> [card] [Redis overview](https://www.tutorialspoint.com/redis/redis_overview.htm)


# Security
Source: https://docs.flowx.ai/5.9/docs/platform-overview/security

How FlowX secures the platform end to end, covering identity and access management, role-based access control, runtime authorization, audit, and AI data protection.

## Overview

FlowX security spans five layers, each documented in its own guide:

1. **Identity**: authentication is delegated to your identity provider through a standards-based IAM integration.
2. **Access control**: role-based access control (RBAC) governs what each user can do in the Designer, per organization, workspace, and project.
3. **Runtime authorization**: separate, project-scoped controls decide who can access a published solution at runtime.
4. **Auditability**: a dedicated Audit service records platform events in a centralized location.
5. **AI data protection**: personal data is detected and redacted before it reaches a model, and AI usage maps to regulatory controls.

This page routes to the detailed documentation for each layer.

> [!NOTE]
>
> For corporate compliance, including the ISO/IEC 27001 certification and SOC 2 attestations, see the [FlowX.AI Trust & Compliance page](https://www.flowx.ai/trust).

***

## Identity and access management

FlowX delegates authentication to an external identity provider. Step-by-step configuration guides cover Keycloak and Microsoft Entra ID.

> [card] [IAM solution](/5.9/setup-guides/access-management/access-management-overview)
>
> The identity and access management framework FlowX uses to control access to digital identities

> [card] [Configuring an IAM solution (Keycloak)](/5.9/setup-guides/access-management/configuring-an-iam-solution)
>
> Step-by-step Keycloak setup for managing users, roles, and apps

> [card] [Configuring an IAM solution (Entra ID)](/5.9/setup-guides/access-management/configuring-an-iam-solution-entra)
>
> Step-by-step Microsoft Entra ID setup for managing users, roles, and apps

***

## Roles and permissions

Access in the Designer is governed by RBAC at organization, workspace, and project level.

> [card] [Roles and permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> Detailed permission matrices for all FlowX roles across organization, workspace, and project levels

> [card] [Workspaces access rights](/5.9/setup-guides/access-management/workspaces-access-rights)
>
> Workspace-level access rights and role-based access control

> [card] [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization)
>
> Project-scoped roles, end-user groups, and solution sharing for controlling runtime access to published solutions

> [card] [End-user access management](/5.9/setup-guides/access-management/end-user-access-management)
>
> Managing access for the end users of your published solutions

***

## Audit

The Audit service provides a centralized record of platform events.

> [card] [Audit](/5.9/docs/platform-deep-dive/core-extensions/audit)
>
> The Audit service and the details captured for each audit event

> [card] [Audit setup](/5.9/setup-guides/audit-setup-guide)
>
> Deploying and configuring the Audit service

***

## AI and data protection

> [card] [Personal Information Guard](/5.9/ai-platform/personal-information-guard)
>
> Detect and redact personal data (PII) before it reaches a model, and restore it afterwards

> [card] [EU AI Act](/5.9/observatory/compliance/eu-ai-act)
>
> 18 EU AI Act requirements mapped to Observatory controls, with scope by risk tier

> [card] [Data architecture](/5.9/docs/platform-overview/data-architecture)
>
> Which data stores FlowX uses, what each stores, and how they fit together


# Projects
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/application

Projects group all resources and dependencies needed to implement an use case.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

## Overview

A project groups resources that represent a project's entire lifecycle. It's not just a collection of processes; it's an organized container holding all dependencies required for that project, from themes and templates to integrations and other resources. Projects enable you to:

* Create Versions of a project to manage changes over time.
* Deploy Builds for consistent environments.
* Organize Resources to ensure clarity and reduce errors.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)

## Core features

> [card] Centralized Resource Management
>
> Projects provide a single view of all resources referenced in a process, enabling you to manage everything from one central location. This approach reduces context-switching and keeps configuration focused.

> [card] Localization and Multi-Language Support
>
> Projects support the definition of multiple locales, allowing you to handle regional content and settings. Enumerations, substitution tags, and media can be localized to meet specific environment requirements.

> [card] Version Control and Builds
>
> Projects support a versioning mechanism that tracks changes to processes, resources, and configurations. The Project Version captures a snapshot of all included resources, while the Build consolidates everything into a deployable package. Each build contains only one version of a project, ensuring a consistent deployment.

> [card] Dependency Management
>
> Projects can use Libraries, which act similarly to projects but are designed for resource sharing across projects. A library can contain reusable components like processes or templates that can be included in other projects. Dependencies between projects and libraries are managed carefully to ensure compatibility.

## Config

Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

<video />

## Project components

### Processes

* **Processes**: Process definitions that drive the project's core functionality and share a project's resources.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/process_definition.png)

> [card] [Processes](../../building-blocks/process/process-definition)

* **Subprocesses**: Processes that can be invoked within the main process. These can either be part of the same project or imported from a library set as a dependency for the project.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_subprocess.gif)

> [card] [Subprocesses](../../building-blocks/process/subprocess)

### Content Management System (CMS)

* **Enumerations**: Predefined sets of options or categories used across the project. These are useful for dropdown menus, filters, and other selection fields.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/enums_app.png)

> [card] [Enumerations](../../platform-deep-dive/core-extensions/content-management/enumerations)

* **Substitution tags**: Here you have system predefined substitution tags and dynamic placeholders that allow for personalized content, such as user-specific data in notifications or documents.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/subst_tags.png)

> [card] [Substitution tags](../../platform-deep-dive/core-extensions/content-management/substitution-tags)

* **Media Library**: A collection of images, videos, documents, and other media assets accessible within the project.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/media_library_app.png)

### Task Management

* **Views**: Views are configurable interfaces that present task-related data based on specific business process definitions. They allow users to create tailored visualizations of task information, utilizing filters, sorting options, and custom parameters to focus on relevant data.
* **Stages**: The phases that a task goes through within a workflow (e.g., Pending, In Progress, Completed).
* **Allocation Rules**: Criteria for assigning tasks within workflows based on predefined rules (e.g., user roles, availability).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/app_task_manager.gif)

### Integrations

* **Systems (API Endpoints)**: Configurations for connecting to external systems via REST APIs. These endpoints facilitate data exchange and integration with third-party platforms.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/systems_overview.png)

* **Workflows**: Workflows are configurable sequences of tasks and decision nodes that automate data processing, system interactions, and integrations, enabling efficient communication and functionality across different projects and services.

<video />

### Dependencies

Dependencies refer to the relationship between a project and the external resources it relies on, typically housed in a **Library**. These dependencies allow projects to access and utilize common assets, like processes, enumerations, or media files, from another project without duplicating content. By managing dependencies effectively, organizations can ensure that their projects remain consistent, efficient, and modular, streamlining both development and maintenance.

* **Libraries**: A library is a special type of project that stores reusable resources. Projects can declare a library as a dependency to gain access to the resources stored within it.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/libraries_dependencies.gif)

* **Build-Specific Dependencies**: When a project adds a library as a dependency, it does so by referencing a specific build of that library

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/build_library.png)

> [!NOTE]
>
> This build-specific dependency ensures that changes in the library do not automatically propagate to the dependent projects, providing stability and control over which version is in use.

* **Versioning**: Dependencies are versioned, meaning a project can rely on a particular version of a library's build. This versioning capability allows projects to remain insulated from future changes until they are ready to update to a newer version.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/library_build.gif)

> [card] [Libraries](libraries)
>
> Read more about libraries by accessing this section

***

### Configuration Parameters

Configuration Parameters are essential components that allow projects to be dynamic, flexible, and environment-specific. They provide a way to manage variables and values that are likely to change based on different deployment environments (e.g., Development, QA, Production), without requiring hardcoded changes within the project. This feature is particularly useful for managing sensitive information and environment-specific settings.

* **Set environment-specific values**: Tailor your project's behavior depending on the target environment.
* **Store sensitive data securely**: Store API keys, passwords, or tokens securely using environment variables.
* **Centralize settings**: Manage common values in one place, making it easier to update settings across multiple processes or integrations.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/config_params.png)

***

### Project level settings

#### Name

The name of the project, which serves as the main identifier for your project within FlowX AI. This name is used to categorize and manage all associated resources.

#### Type

You choose the type when you create the project. You have two options:

* **Project**: A standard project that will contain processes, resources, integrations, and other elements.
* **Library**: A reusable set of resources that can be referenced by multiple projects.

#### Platform type

You can specify the platforms for the project:

* **Omnichannel**: The project will support web, mobile, and other platforms.
* **Web only**: The project will be restricted to web-based access.
* **Mobile only**: The project will only be accessible via mobile platforms.

Individual processes can override the platform. Changing the project platform applies only to processes you create afterward.

#### Project entry point

The entry point declares **what the generic container app launches** when it loads your project version. Either a **Process** or a **UI Flow** can be set as the entry point, and the entry point applies in both configuration testing and runtime.

> [!NOTE]
>
> **Required to run your project from the generic container app.** Without an entry point, the container app loads the project shell but has nothing to render — users see an empty screen. Set the entry point before sharing the container app URL with end users or test runners.

**Setting the entry point.** Open **Version Settings → General** and pick the resource under **Project Entry Point**:

* For **Web** platforms, set the **Web** entry point.
* For **Mobile** platforms, set the **Mobile** entry point.
* For **Omnichannel** projects, set both — each platform launches its own entry point.

Only project-type entries can have entry points; **library** projects do not. The dropdown lists the Processes and UI Flows defined in the current project version whose platform matches the entry point, plus Omnichannel ones, grouped under the project name.

> [!WARNING]
>
> Entry points must be defined in the project itself. Processes or UI Flows coming from library dependencies cannot be used directly as entry points.
>
> To reuse logic from a library, create a project-level Process/UI Flow that calls the library resource, or move the entry point into the project.

> [!TIP]
>
> The container app reads the entry point from the build it runs. Which build that is depends on the project's [active policy](../runtime/active-policy), including any user or group override that applies to you:
>
> * **Latest on Branch**: each work-in-progress version has its own build, and saving the entry point updates that build. The change applies as soon as you save it, without a commit.
> * **Build**: the pinned build keeps the entry point it was committed with. Commit the version, then point the active policy at the new build.

#### Testing a build

From the builds list, the **Play** (▶) menu launches a build so you can validate it before sharing the container app URL. **Test build** opens a dialog where you pick a Process from the build, then set its start data and a theme. Clicking a build row opens the same dialog.

#### Testing from the entry point

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Test Build** runs the configured entry point (the Web entry point if set, otherwise Mobile). If no entry point is set, a prompt asks you to set a Process or UI Flow as the entry point first.

You can also launch a specific resource without changing the entry point:

* **Test Process** — pick any Process in the build and start it with a JSON data form (or an email form for Email-Trigger processes) and a theme.
* **Test UI Flow** — pick any UI Flow in the build and start it with a JSON data form and a theme.

**Test Process** and **Test UI Flow** appear only if you have read access to that resource type. Clicking a build row runs **Test Build**.

#### Default theme

Use **Project Theme** to apply a consistent look and feel across the project. Themes manage colors, fonts, and UI elements for a unified visual experience. In the screenshot, "FlowXTheme" is selected as the default.

![Version Settings General tab with the platform, project entry point and project theme settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/version_settings_general_59.png)

> [card] [Theming](/5.9/docs/flowx-designer/design-assets/themes)

#### End-User Roles

Define the end-user roles this project version exposes at runtime. Click **Add Role** to attach an existing role from the organization catalog, or select **Create New Role** to define a new one. New projects start with a default **User** role. You can also remove a role from the version when you no longer want to expose it (available starting with 5.9.4).&#x20;

Assign these roles on process swimlanes and UI Flow permissions to control what each role can access. They become grantable to users and groups in the **Share** modal once the build is set as the project's Active Policy.

For the full runtime authorization model, see the [End-user access management](/5.9/setup-guides/access-management/end-user-access-management#end-users-roles) guide.

#### Number formatting

* **Minimum Decimals** and **Maximum Decimals**: Configure how numbers are displayed in the project by setting the minimum and maximum decimal points. This helps ensure data consistency when dealing with financial or scientific information.
* **Date Format**: Choose the format for displaying dates (**Short**, **Medium**, **Long**, **Full**, or **Custom**) to ensure the information is localized or standardized based on your project's requirements.
* **Currency Format**: Set whether currency is displayed using the ISO code (e.g., USD) or using a symbol (\$). This affects how financial information is presented across the project.

![Version Settings Formatting tab with the decimals, date format and currency format settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/version_settings_formatting_59.png)

#### Languages

This section allows you to manage languages supported by the project.

* **Default Language**: You can set one language as the default, which will be the primary language for users unless they specify otherwise. In the screenshot, English (EN) is set as the default language.
* **Add Multiple Languages**: This enables multi-language support. Substitution tags and enumerations can be localized to provide a better experience for users in different regions.

![Version Settings Languages tab with English (EN) set as the default language](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/version_settings_languages_59.png)

Fore more information about localization and internationalization, check the following section:

> [card] [l10n & i18n](../../building-blocks/ui-designer/localization-and-i18n)

## Creating and managing projects

A project's lifecycle includes the following stages:

**1. Creating a Project**

* Start by defining the name and platform (Omnichannel, Web only, or Mobile only).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/create_first_app.gif)

* Set up initial configurations like themes, languages, and formats.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/configure_initial.gif)

* Inherit system-wide design assets like themes or fonts.

**2. Configuring Resources**

* Add processes, define templates, set up enumerations, and manage integrations.
* Configure environment-specific parameters like API URLs or passwords using environment variables.
* Reuse resources from libraries by setting up dependencies, allowing access to shared content.

**3. Publishing a Project**

* Submit your configured resources to a version.
* Once finalized, a version can be committed for stability.
* Create a build from a version when ready to deploy to a different environment.

**4. Deploying a Build**

* A build packages the project version for a consistent deployment.
* Each build is immutable and cannot be modified once created, ensuring runtime stability.

<video />

## FAQs

> [accordion] How do I create a new version of a project?
>
> To create a new version, navigate to the project dashboard, select **Start New Version**, and make any changes. Once finalized, commit the version to lock it.

> [accordion] What happens when I create a build?
>
> Creating a build captures a snapshot of the project version, consolidating resources into a single deployable package. Builds are immutable and cannot be edited once created.

> [accordion] Can I manage multiple localizations within a project
>
> Yes, projects support multiple locales. You can define regional settings, such as date formats and currencies, to cater to different environments.

> [accordion] How do I handle resource changes in a shared environment?
>
> When modifying shared resources, FlowX AI enforces versioning. You can track which processes or resources are affected by a change and revert if necessary.

> [accordion] What is the difference between a Project Version and a Build?
>
> A Project Version is a snapshot of resources and configurations that can be modified, tracked, and rolled back. A Build is a deployable package created from a committed version, and it is immutable once deployed.

> [accordion] How do I add a library as a dependency?
>
> Open **Dependencies** in the project's left navigation and select the desired library. Choose the build you want to use, and its resources will be accessible within your project.

> [accordion] Can I make changes to a deployed build?
>
> No, a build is immutable. To make changes, modify the project version, create a new version, and deploy a new build.

> [accordion] How are resource versions managed within a project?
>
> Each resource has a Resource Definition ID (consistent across versions) and a Resource Version ID (specific to each version). These ensure that the correct version of a resource is used at runtime.

> [accordion] What is the purpose of dependencies in FlowX AI?
>
> **A:** Dependencies allow projects to share and reuse resources like processes, enumerations, and templates that are stored in libraries. By setting a library as a dependency, a project can access the resources it needs without duplication, fostering modular development.

> [accordion] How do versioning and dependencies work together?
>
> **A:** Dependencies are version-controlled, meaning you can choose specific library builds to ensure stability. Each build version of a library captures the state of its resources, allowing projects to lock onto a particular version until they are ready to upgrade.

> [accordion] Can I remove a dependency from a project?
>
> **A:** Yes, you can remove a dependency from the project. Open **Dependencies** in the project's left navigation and select the dependency you want to remove. However, make sure that no critical resources in the project rely on that dependency.

> [accordion] What are the risks of circular dependencies?
>
> **A:** Circular dependencies occur when two libraries depend on each other. This can lead to conflicts and unexpected behavior. It's best to keep dependencies modular and avoid tightly coupling libraries to prevent such issues.

> [accordion] How do I ensure that a library update doesn't break my project?
>
> **A:** Use a controlled environment like Dev or UAT to test new builds of the library before updating the dependency in your main project. This allows you to validate changes and ensure they don't negatively impact your project.

> [accordion] What happens to resource versions when I update a dependency?
>
> **A:** When a dependency is updated to a newer build, any resources that were modified in the library will reflect the latest version. Projects have control over when to update, so older versions remain stable until the dependency is manually updated.


# Checking a version for issues
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/checking-for-issues

Validate the resources in a project version from the Issues Console, see where each problem is, and review what is outstanding before you commit.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

The Designer can check the resources in your project version and list what it finds in one place. Findings are listed in the **Issues Console**, and marked where they occur so you can go straight to them.

Open the console from the **Issues** button in the bottom bar of the project, which shows how many findings the version has. That count covers every finding in the version, whatever filters you apply in the console.

The console is a floating window. Drag it by its title bar, resize it from any edge or corner, and close it with the close button. It belongs to the project rather than to a single page, so it stays open, at the same size and position, as you move between the project's pages.

> [!NOTE]
>
> **What is validated.** Processes, UI Flows and integration workflows are checked. Other resource types are listed as not validated rather than reported as clean, so an empty result never means more than it should.

![The Issues Console floating over the Processes list, set to All in version and grouped by Severity. Three errors report missing Web and Mobile entry points and a swimlane that references a role outside the project version; six warnings report workflow nodes that are not reachable from the START node. The filter row shows the Show, Search and Group controls and error, warning and info count chips, and the bottom bar shows 9 Issues, checked just now.](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/issues-console.png)

> [!NOTE]
>
> In the workflow editor, the console also has a **Run Logs** tab for the workflow's test runs.

***

## Running a check

A version that has been checked before opens with the results of its last check, whoever ran it. A version that has never been checked shows **Nothing checked yet. Run a check to validate every resource in this version.** and a **Check for issues** button.

To check again, select the refresh button next to the **Issues** count in the bottom bar, or in the console's title bar. Both places show how long ago the last check ran, for example `5 min ago`, so you can tell a current result from a stale one.

> [!TIP]
>
> Run a check again after a round of edits. The list describes the version as it was at the last check, not as it is now.

***

## Reading the list

Every finding is reported at one of three severities, **error**, **warning**, or **info**, and names the element and the resource it came from. Select that name to go straight to the element.

Hover over a finding to show its lightbulb button. Select it to expand a **Suggested Fix** with the remediation and a **Go to** button that opens the element.

The filter row above the list narrows what you see:

| Control | What it does |
| - | - |
| **Show** | Choose **In context** to see only the findings for the page you are on (a resource list, a single resource, or the version settings), or **All in version** for everything. **In context** is the default on pages that have one. A choice you make lasts until you move to another page. |
| Severity chips | One chip each for errors, warnings, and info, showing the count. Turn any of them off. All three are on by default. |
| **Search** | Filter by text in the message, the resource name, or the element name. |
| **Group** | **Severity**, **Resource**, or **None**. Grouping by severity is the default, and each group can be collapsed. |

Your severity and grouping choices are remembered in your browser, across versions. Search is not.

***

## Which version settings does a check cover?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Besides resources, a check covers the version's own settings and its library dependencies. Selecting one of these findings opens the page where you fix it: entry point and theme findings open the version settings, and dependency findings open the **Dependencies** page.

| Rule | Severity | Reported when |
| - | - | - |
| **Missing entry point** | Error | The version has no entry point for a channel (Web or Mobile), so it can't be launched there. |
| **Broken entry point** | Error | A channel's entry point references a process or UI Flow that no longer exists. |
| **Entry point platform mismatch** | Warning | A channel's entry point is a resource built only for the other platform. |
| **Broken theme reference** | Error | The version references a theme that isn't in this workspace. Renderers fall back to a FlowX built-in theme. |
| **Missing library build** | Error | The version depends on a library build that isn't in this workspace. Nothing from that library can run until the build is imported. |
| **Missing transitive library build** | Error | A library the version depends on needs a build of another library that isn't in this workspace. |
| **Unused dependency** | Info | The version depends on a library but uses none of its resources. The dependency still brings its own dependencies into the version. |

***

## Markers

Findings are also marked where they live: on workflow list rows, on the page title, and on nodes in the workflow canvas. Markers show errors and warnings only, never info, and the page title marks errors only. Selecting a marker opens the Issues Console; on a canvas node, it also focuses that node.

To turn markers off, open the settings popover in the filter row and clear **Show on canvas and lists**. The console keeps working; only the markers elsewhere are hidden.

![Workflow canvas with an error marker on the computeQuote node header and on the page title, and a warning marker on applyDiscount, a node not connected to the flow. The bottom bar shows Run Logs, the 11 Issues count and the time of the last check.](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/issues-console-canvas-markers.png)

***

## Before you commit

Opening **Commit Changes** runs a check on its own, and each changed resource in the modal shows what the check found: its errors and warnings, a check mark when it has no issues, or a minus sign when its type is not validated yet. A resource you are deleting is shown as not validated, since it is not part of the version being described. Above the commit button, a summary reads **Issues found** or **No issues found** for the changed resources.

> [!WARNING]
>
> **Findings do not block the commit.** When changed resources have errors, the button reads **Commit with 2 errors** (with the actual count), but you can still commit. Treat the list as a review step you perform, not a gate the Designer applies for you.

![Commit Changes modal listing three changed resources: a UI Flow and a workflow with check marks, and the calculateShippingQuote workflow with one error and one warning. An Issues found summary sits above the buttons, and the commit button reads Commit with 1 error.](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/issues-console-commit-modal.png)

***

## Related resources

> [card] [Versioning](./versioning)
>
> Project versions, committing changes, branches and builds

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Building the workflows this check validates


# Dependencies
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/dependencies

Manage dependencies between projects and libraries to enable resource sharing, modular development, and version control across your FlowX applications

Dependencies in FlowX enable projects and libraries to share and reuse resources, fostering modular development and reducing duplication. By establishing dependency relationships, you can access common assets like processes, enumerations, and media files from external libraries while maintaining version control and stability.

## Overview

![Dependencies overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/dependencies_ov.png)

Dependencies allow you to:

* **Share resources** across projects and libraries without duplication
* **Maintain version control** by referencing specific builds
* **Create modular architectures** with reusable components
* **Ensure stability** through controlled dependency management
* **Build hierarchical structures** with library-to-library dependencies

## Types of dependencies

> [tab] Project Dependencies
>
> **Project Dependencies** allow projects to reference and use resources from libraries.
>
> ### Key Features
>
> * **Library Access**: Projects can add libraries as dependencies to access their resources
> * **Build-Specific**: Dependencies reference specific builds of libraries for stability
> * **Version Control**: Projects control when to upgrade to newer library versions
> * **Resource Availability**: All resources from dependent libraries become available in the project
>
> ### Use Cases
>
> * Shared UI components and templates
> * Common business processes and subprocesses
> * Standardized enumerations and configuration
> * Reusable integration workflows
>
> ![Project dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/projects_dependencies.png)

> [tab] Library Dependencies
>
> **Library Dependencies** enable libraries to depend on other libraries, creating hierarchical dependency structures.
>
> ### Key Features
>
> * **Library-to-Library**: Libraries can now reference other libraries as dependencies
> * **Dependency Tree**: Create complex hierarchical structures with multiple levels
> * **Resource Inheritance**: Projects gain access to resources from the entire dependency hierarchy
> * **Modular Design**: Break down complex functionality into smaller, focused libraries
>
> ### Use Cases
>
> * Country-specific processes that use common base libraries
> * Shared utility libraries used by multiple specialized libraries
> * Hierarchical organization of business domains
> * Team-based development with library ownership
>
> ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)

## Dependency tree management

### Understanding dependency trees

A **dependency tree** represents the hierarchical structure of dependencies for a project or library. In FlowX 5.1, dependency trees can include multiple levels of library dependencies.

![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)

#### Example dependency tree

```
Mortgage Project
├── Enums Library (1.6.0)
├── Integrations Library (2.5.0)
│   ├── Commons Library (1.1.0)  
│   └── Enums Library (1.6.0) # Transitive dependency
└── Subprocesses Library (1.3.0)
    └── Enums Library (1.6.0)  # Transitive dependency
```

### Dependency tree constraints

> [!WARNING]
>
> **Important Constraint**: FlowX implements a **single-version constraint** for dependency trees. The same library cannot exist multiple times in a dependency tree with different builds.

#### Allowed scenarios

> [accordion] Same library, same version (Allowed)
>
> ```
> Mortgage Project
> ├── Subprocesses Library (1.3.0)
> │   └── Enums Library (1.6.0)
> └── Integrations Library (2.4.0)
>     └── Enums Library (1.6.0)  # ✅ Same version - ALLOWED
> ```
>
> This scenario is permitted because both references use the same build (1.5.0) of the Enums Library.

#### Blocked scenarios

> [accordion] Same library, different versions (Blocked)
>
> ```
> Mortgage Project
> ├── Enums Library (1.6.0)           # Direct dependency
> └── Subprocesses Library (1.3.0)
>     └── Enums Library (1.5.0)       # ❌ Different version - BLOCKED
> ```
>
> This scenario is **blocked** because it would create a version conflict in the dependency tree.

> [accordion] Circular dependencies (Blocked)
>
> ```
> Library A (1.0.0)
> └── Library B (1.0.0)
>     └── Library A (1.1.0)  # ❌ Circular reference - BLOCKED
> ```
>
> Circular dependencies are **strictly prohibited** to prevent infinite loops and maintain dependency tree integrity.

### Conflict resolution

When dependency conflicts occur, you have several resolution options:

**1. Update Direct Dependencies**

Update the direct library dependency to a version that uses the required transitive dependency version.

```
# Before (Conflict)
Project → Library A (1.0) → Commons (1.1)
       → Library B (2.0) → Commons (1.2)  # Conflict

# After (Resolved)
Project → Library A (1.1) → Commons (1.2)  # Updated A to use Commons 1.2
       → Library B (2.0) → Commons (1.2)  # Now compatible
```

**2. Create New Library Builds**

Create new builds of libraries that include the required dependency versions.

**3. Restructure Dependencies**

Reorganize your dependency structure to avoid conflicts, potentially by creating intermediate libraries.

## Managing dependencies

### Adding project dependencies

**1. Navigate to Dependencies**

In your project workspace, go to the **Config** tab and select **Dependencies**.

**2. Add Library Dependency**

Click **Add Dependency** and select the library you want to add.

![Add project dependency](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/select_dependency.png)

**3. Select Build Version**

Choose the specific build version of the library you want to use.

> [!WARNING]
>
> Only committed builds are available.

**4. Validate Dependency Tree**

FlowX will automatically validate that the new dependency doesn't create conflicts in your dependency tree.

**5. Confirm Addition**

Review the dependency tree preview and confirm the addition. The library's resources will become available in your project.

### Adding library dependencies

**1. Open Library Configuration**

Navigate to your library and go to the **Config** tab, then select **Dependencies**.

**2. Add Library Dependency**

Click **Add Dependency** and select another library as a dependency.

![Add library dependency](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/add_lib_dependency.png)

**3. Conflict Detection**

FlowX will check for potential conflicts, including:

* Version conflicts with existing dependencies
* Circular dependency detection
* Transitive dependency validation

**4. Review Dependency Tree**

Preview the complete dependency tree to understand all transitive dependencies.

### Updating dependencies

> [accordion] Single Dependency Update
>
> When updating a single dependency:
>
> 1. Navigate to the **Dependencies** section
> 2. Select the dependency to update
> 3. Choose the new build version
> 4. FlowX validates the dependency tree for conflicts
> 5. If conflicts exist, resolve them before proceeding
>
> ![Update dependency](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/single_dep_update.png)

> [accordion] Bulk Dependency Updates
>
> For complex dependency trees, you may need to update multiple dependencies simultaneously:
>
> 1. Plan your update strategy to avoid intermediate conflicts
> 2. Update dependencies in the correct order (typically from leaf to root)
> 3. Use the dependency tree view to validate changes
> 4. Test in a development environment before applying to production
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/bulk_dep_update.png)

## Resource resolution

### Resource types and references

Different resource types use different referencing mechanisms:

| Resource Type | Reference Method | Example |
| - | - | - |
| **Process** | Resource Definition ID | `proc_customer_onboarding_123` |
| **Media Library Item** | Resource Definition ID | `media_logo_456` |
| **System/Workflow** | Resource Definition ID | `sys_crm_integration_789` |
| **Enumeration** | Name | `CUSTOMER_TYPES` |
| **Substitution Tag** | Name | `WELCOME_MESSAGE` |
| **Notification Template** | Name | `EMAIL_CONFIRMATION` |
| **Document Template** | Name | `CONTRACT_TEMPLATE` |
| **Configuration Parameter** | Name | `MAX_RETRY_COUNT` |

### Resource precedence rules

When multiple resources with the same name exist in the dependency tree:

**1. Highest Level Wins**

Resources from the **highest level** (closest to the project) take precedence.

```
Project (Level 0)
├── Library A (Level 1) - contains ENUM_X
└── Library B (Level 1)
    └── Library C (Level 2) - contains ENUM_X

# ENUM_X from Library A (Level 1) is used
```

**2. Same Level Resolution**

If resources exist at the same level, the resource from the **newest build** (by build creation date) takes precedence.

**3. Predictable Resolution**

The resolution is deterministic and consistent across environments.

> [!WARNING]
>
> **Best Practice**: Avoid duplicate resource names across libraries in your dependency tree to maintain control and predictability over resource usage at runtime.

## Build and deploy considerations

### Build export/import

When exporting or importing builds:

* **All dependent libraries** are included in the export package
* **Transitive dependencies** are automatically resolved and included
* **Version consistency** is maintained across environments
* **Dependency tree structure** is preserved during import

### Runtime behavior

At runtime:

* **Resource resolution** follows the established precedence rules
* **Dependency tree** is flattened for efficient resource lookup
* **Version consistency** ensures predictable behavior
* **Build immutability** guarantees that deployed builds remain stable

## Best practices

### Dependency design

> [!TIP]
>
> **Keep dependencies modular**: Design libraries with clear, focused responsibilities to avoid monolithic structures.

> [!TIP]
>
> **Plan your hierarchy**: Design your dependency tree structure before implementation to avoid conflicts later.

> [!TIP]
>
> **Use semantic versioning**: Follow consistent versioning practices to make dependency management predictable.

> [!TIP]
>
> **Avoid circular dependencies**: Design your library architecture to prevent circular references.

> [!TIP]
>
> **Document dependencies**: Maintain clear documentation of library purposes and dependency relationships.

### Version management

> [!TIP]
>
> **Lock to specific builds**: Always reference specific builds rather than "latest" versions for stability.

> [!TIP]
>
> **Test dependency updates**: Use development environments to test dependency updates before production.

> [!TIP]
>
> **Plan upgrade paths**: Consider the impact on dependent projects when updating library versions.

> [!TIP]
>
> **Maintain backward compatibility**: When possible, maintain backward compatibility to ease library updates.

### Team collaboration

> [!TIP]
>
> **Establish ownership**: Clearly define which teams own which libraries to coordinate updates.

> [!TIP]
>
> **Communication protocols**: Establish processes for communicating library changes to dependent teams.

> [!TIP]
>
> **Shared standards**: Agree on naming conventions and design patterns across library-owning teams.

## Troubleshooting

### Common dependency issues

> [accordion] Version Conflict Errors
>
> **Problem**: Cannot add dependency due to version conflicts.
>
> **Solutions**:
>
> * Update existing dependencies to compatible versions
> * Create new library builds with compatible dependency versions
> * Restructure your dependency hierarchy to avoid conflicts
> * Review your dependency tree for optimization opportunities

> [accordion] Circular Dependency Detection
>
> **Problem**: System prevents adding a dependency due to circular reference.
>
> **Solutions**:
>
> * Analyze your dependency structure to identify the circular path
> * Extract common functionality into a separate base library
> * Restructure libraries to create a proper hierarchy
> * Consider if the circular dependency indicates a design issue

> [accordion] Missing Resources
>
> **Problem**: Expected resources are not available after adding dependencies.
>
> **Solutions**:
>
> * Verify the dependency was added with the correct build version
> * Check if resources exist in the expected library build
> * Review resource name conflicts that might affect precedence
> * Ensure the library build contains the expected resources

> [accordion] Build Export Issues
>
> **Problem**: Build export fails due to dependency problems.
>
> **Solutions**:
>
> * Validate all dependencies are using committed builds (not WIP)
> * Ensure all transitive dependencies are available
> * Check for missing or deleted library builds
> * Review access permissions for all dependent libraries

## FAQ

> [accordion] Can libraries depend on multiple other libraries
>
> Yes, libraries can have multiple dependencies, just like projects. Each dependency is managed independently and contributes to the overall dependency tree.

> [accordion] What happens if I delete a library that others depend on?
>
> FlowX prevents deletion of libraries that are referenced as dependencies. You must remove all dependency references before a library can be deleted.

> [accordion] Can I test with WIP versions of dependencies?
>
> No, dependencies must reference committed builds, not WIP (Work in Progress) versions. This ensures stability and prevents issues with changing dependencies.

> [accordion] How deep can dependency trees go?
>
> There's no enforced limit on dependency tree depth, but for maintainability and performance, it's recommended to keep trees reasonably shallow (typically 3-4 levels maximum).

> [accordion] What's the difference between direct and transitive dependencies?
>
> * **Direct dependencies**: Libraries explicitly added as dependencies to your project or library
> * **Transitive dependencies**: Libraries that are dependencies of your direct dependencies (automatically included)

> [accordion] How do I resolve dependency conflicts between teams?
>
> 1. Establish clear communication channels between teams
> 2. Plan library updates and coordinate with dependent teams
> 3. Use development environments to test impact of changes
> 4. Consider creating shared governance processes for critical libraries

> [accordion] Can I override a transitive dependency with a direct dependency?
>
> No, FlowX enforces the single-version constraint. If you need a different version of a transitive dependency, you must update the direct dependency that includes it.


# Libraries
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/libraries

Libraries are specialized projects that serve as reusable containers for resources that can be shared across multiple projects.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)

Unlike regular projects, which are intended for creating and managing specific workflows, libraries are designed to house common elements—like processes, enumerations, and media assets—that other projects may rely upon.

This makes libraries a cornerstone for establishing consistency and efficiency across various projects.

#### Key features

* **Resource Sharing**:

  * Libraries facilitate the reuse of resources like processes, enumerations, and media assets across different projects. This allows for a more modular design, where commonly used elements are stored centrally.
  * Resources in a library can be included in other projects by setting the library as a dependency.

* **Dependencies**:

  * A project can add a library as a dependency, meaning it will have access to the resources stored in that library.
  * Dependencies are managed through builds; each project can choose a specific version (build) of a library to depend on. This ensures that updates in the library do not automatically impact all projects unless intended.

* **Versioning**:

  * Just like projects, libraries can be versioned. Each version of a library captures the state of its resources at a specific point in time.
  * This versioning allows projects to lock dependencies to specific library versions, providing stability and predictability during runtime.

#### Managing libraries

1. **Creating a Library**:

   * Libraries can be created similarly to projects. The creation process involves setting a name, defining the resources it will contain, and managing its configuration settings.
   * Once created, resources can be added to the library incrementally, allowing for iterative development.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/docs_library.png)

2. **Managing Library Resources**:

   * Users can create, edit, delete, or version resources within the library. Resources include processes, enumerations, media files, and other elements that can be referenced by projects.
   * A library can have multiple versions, each capturing the resource state. This allows backward compatibility with older project builds relying on specific library versions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/library_build.png)

3. **Adding Library Dependencies to Projects**:

   * In the project workspace, libraries can be set as dependencies under the **Dependencies** section.
   * Users can select which build version of the library to reference. This allows projects to control how library changes affect them by choosing to update the dependency to newer library builds as needed.

> [!NOTE]
>
> Libraries can be added as a dependency only to Work-In-Progress (WIP) project versions.

<video />

#### Library build process

* **Builds in Libraries** are tagged versions, allowing a snapshot of the current library resources to be used by projects. Each build in a library captures the state of all its resources.
* Projects referencing a library can specify the exact build to use, ensuring that changes to the library do not inadvertently impact dependent projects.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/library_build.gif)

#### Use cases

1. **Centralized Resource Management**:

   * Organizations that need to maintain a standard set of processes or other resources can use libraries to store these centrally. Each project can then use the same library resources, ensuring consistency.

2. **Version-Controlled Dependency Management**:

   * By utilizing builds and versioning within libraries, projects can safely depend on specific versions, reducing the risk of unexpected behavior due to resource updates.

3. **Streamlining Updates Across Projects**:

   * When an update is required across multiple projects that rely on the same resources, it can be done by updating the library and releasing a new build. Each project can then choose to update to the new build when ready.

## Best practices

* Use libraries for resources that need to be standardized across multiple projects.
* Carefully manage dependencies and choose specific builds to avoid unexpected runtime behavior.
* Use versioning to maintain a clear history of resource changes, allowing rollbacks if necessary.

Libraries thus play a crucial role in modularizing the development process, enabling reusable and maintainable components across different projects. This leads to improved project organization, reduced redundancy, and simplified resource management.

## FAQs

> [accordion] How do I add a library as a dependency to an project?
>
> **A:** In the project workspace, navigate to the **Dependencies** section. Select the library you want to add, choose the specific build version, and confirm. Once added, the resources from that library will be available for use within the project.

> [accordion] What happens if a resource in a library is updated?
>
> **A:** When a resource in a library is updated, dependent projects will not be affected unless the library build they reference is updated to a newer version. This allows projects to maintain stability by controlling when updates are adopted.

> [accordion] Can I use multiple libraries as dependencies for a single project?
>
> **A:** Yes, a project can depend on multiple libraries. Each library can be referenced by selecting the desired build version. However, ensure that dependencies are managed carefully to avoid conflicts or redundancy.

> [accordion] What should I do if a newer library build is available?
>
> **A:** Before switching to a newer library build, test it in a development or staging environment to ensure compatibility. If everything functions as expected, update the project’s dependency to the new build in the **Dependencies** section.


# Versioning
Source: https://docs.flowx.ai/5.9/docs/projects/managing-applications/versioning

Easily track and manage your project's evolution with comprehensive versioning features.

Versioning enables you to manage changes, track progress, and collaborate effectively by capturing snapshots of your project's state at any point in time. The versioning system ensures that resources are grouped and tracked as part of the project, providing a comprehensive and structured approach to development.

## Project version

A **Project Version** is an editable snapshot of your project at a specific moment. It contains all resources (e.g., processes, integrations, templates) and configurations grouped under the project.

* **Project**: The main project entity that contains all your resources (processes, integrations, templates, etc.)
* **Project Branch**: Branches within a project (similar to Git branches) that allow parallel development
* **Project Version**: Individual versions within branches that track the state of your project

Each version can have one of the following statuses:

* **WIP (Work In Progress)**: Draft versions that are actively being edited
* **COMMITTED**: Finalized versions that have been submitted with a commit message
* **MERGE\_IN\_PROGRESS**: Versions currently being merged between branches

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-22%20at%2019.09.53.png)

The tab above provides a summary of all accessible project versions and branches available in the current environment.

> [!NOTE]
>
> Resources within a project (e.g., processes, integrations, templates) are versioned as part of the project, not individually.

> [!NOTE]
>
> Certain resources are considered **global** and are not included in project-specific versioning. These resources are shared across projects and environments to maintain consistency and simplify their management. Examples of such global resources include:
>
> * **Themes**: Predefined design themes used across multiple projects.
> * **Fonts**: A library of fonts accessible globally.
> * **Global Media Files**: Shared media assets.
> * **Out of Office Settings**: Configurations for user availability and auto-responses that are managed at the platform level.

***

## Version details

![Version Details panel for a draft version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/version_details_draft.png)

* **State**: Displays the current state of the version (e.g., `draft`, `committed`).
* **Branch**: Indicates the currently selected branch (e.g., `main`).
* **Last Saved By**: Shows the username of the person who last saved changes (e.g., "JS").
* **Last Saved At**: Displays the timestamp of the most recent save (e.g., "23 Jan 2025 at 10:11 AM").
* **ID**: A unique identifier for the version, with a copy button for convenience.
* **Resources Changed**: Displays a summary of modified, added, or deleted resources compared with the previous version (visible only for draft versions with changes).

### Resources changed

The **Resources Changed** section provides a clear overview of all modifications made in the current draft version compared to the last committed version. This helps you track exactly what has been modified before committing your changes.

![Resources Changed](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/version_details_resources_changed.png)

The list groups changes by resource type, including:

* **CMS \ Enumerations**: Modified enumeration values (for example, country lists, dropdown options)
* **Processes**: Changed process definitions
* **Project Data Model**: Updates to the data model structure
* **CMS \ Substitution Tags**: Modified substitution tags
* **CMS \ Media Library**: Added, modified, or deleted media assets
* **Task Manager \ Views**: Changes to task manager view configurations
* **Dependencies**: Updated project dependencies
* **Resource Overrides**: Modified resource override configurations

Each resource is color-coded to indicate the type of change:

| Color | Meaning |
| - | - |
| **Yellow** | Modified resource |
| **Green** | Added resource |
| **Red** | Deleted resource |

> [!TIP]
>
> Use the Resources Changed list to review all pending modifications before committing. This ensures you have a complete understanding of what will be included in the commit.

### Compare versions

The **Compare Versions** feature allows you to select two versions and view the differences between them. This is useful for understanding what changes were made between any two points in your project's history.

To compare versions:

1. Select a version in the branch graph
2. Click on the **Compare with current version** button at the bottom of the graph to quickly compare any committed version with the current draft version.

![Compare Versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/compare_v.png)

The comparison view displays:

* **Comparing current version**: Shows the first selected version with its branch, state, and last edited timestamp
* **with**: Shows the second selected version being compared against
* **Resources changed**: Lists all resources that differ between the two versions

#### Viewing detailed resource changes

To inspect the specific changes made to a resource, hover over any item in the **Resources changed** list and click the **eye icon** that appears. This opens a detailed comparison modal.

![View Resource Changes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-11-27%20at%2017.49.50.png)

The **Changes** modal provides a side-by-side JSON comparison:

* **Left panel**: Shows the version you are comparing with (the previous/committed version)
* **Right panel**: Shows the current draft version
* **Highlighted lines**: Added or modified content is highlighted in green, making it easy to identify what changed

![Resource Changes Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-11-27%20at%2017.50.19.png)

> [!NOTE]
>
> This feature helps you track changes across multiple commits, review what was modified before a specific release, or understand the evolution of your project over time.

### Resource history

The **Resource History** feature lets you view the version history for a specific resource, showing which project versions included changes to that resource.

To access it, right-click any resource (process, enumeration, substitution tag, media asset, integration, etc.) and select **View History**. This opens the Resource History modal.

The modal displays a table with the following columns:

| Column | Description |
| - | - |
| **Version** | The project version that included a change to this resource |
| **Last edited by** | The user who last modified the resource in that version |
| **Last edited at** | The timestamp of the last modification |

For each version in the list, you can:

* **See changes** — Opens a comparison view showing what changed in this resource between the selected version and the previous one
* **Open version in new tab** — Navigates to the full project version in a new browser tab

> [!NOTE]
>
> Resource history tracks changes at the project version level. Individual resources do not have their own independent version history — they are always versioned as part of the project.

### Branch and commit graph

The graph visually organizes the project’s versioning structure, showing relationships between branches and commits.

* **Graph View**:
  * Provides a visual representation of branches and commits.
  * **Main Branch** (blue): The main development branch.
  * **Secondary Branches** (yellow): Feature or development branches such as `branch3`, `branch4`, and `secondary_branch`.
  * **Markers**:
    * **Dotted Circles**: Represent draft versions.
    * **Solid Circles**: Represent committed versions.

### Commit history

* Displays a chronological list of commit messages for the selected branch.
* **Details**:
  * Commit messages (e.g., `v1`, `commit_secondary_branch`) are aligned with their respective branches.
  * Each commit shows:
    * The user responsible (e.g., "JS").
    * The state of the commit (e.g., `draft`, `commited`).

### Top bar: global controls

* **Project Name**: Displays the current project name (`Docs_customer_onboarding`).
* **Branch Selector**: Dropdown to navigate between branches.
* **State Indicator**: Highlights the state of the current branch (e.g., `draft` for `main`).
* **Commit Changes to Version**: Button for committing draft changes globally.
* **Config/Runtime Tabs**:
  * **Config**: For managing version configuration.
  * **Runtime**: For runtime options or monitoring.

***

## Core versioning operations

The table below summarizes key versioning operations and their functions:

| Operation | Description |
| - | - |
| **Create Project** | Creates a project and its initial draft version. |
| **Create Resource** | Adds a new resource in draft status to the current project version. |
| **Edit Resource** | Creates a deep copy of a resource for editing if the original is COMMITTED. |
| **Commit Project** | Updates the statuses of the project, its manifest, and resources to COMMITTED. |
| **Discard draft** | Deletes draft resources and the draft project version. |
| **Start New draft** | Creates a new draft version by copying the last COMMITTED project version. |
| **Create Branch** | Creates a new branch and a corresponding draft project version from the selected commit. |

### Detailed steps for operations

**1. Create Project**

* A new project is created in draft (WIP) state.
* An initial draft project version is automatically generated.

**2. Create Resource**

* Adds a resource in draft status to the current project version.
* Updates the project manifest to include:
  * **UUID** of the new resource.
  * `last_change_time`: Set to the current timestamp.
  * `last_committed_time`: Null (since the resource is WIP).

**3. Edit Resource**

* **Scenario A**: Editing a draft Resource
  * No new resource version is created.
  * Updates the project manifest:
    * `last_change_time`: Current timestamp.

* **Scenario B**: Editing a `COMMITTED` Resource
  * A deep copy of the `COMMITTED` resource is created as draft.
  * Updates the project manifest:
    * Links to the new draft resource.
    * `last_change_time`: Current timestamp.

**4. Commit Project**

* Commits the current draft project version:
  1. **draft Resources**:
     * Status: Updated to `COMMITTED`.
     * `last_change_time` and `last_committed_time`: Set to the current timestamp.
  2. **Project Version**:
     * Status: Updated to `COMMITTED`.

**5. Discard Draft**

* Deletes draft resources and the draft project version.
* Available only when there are changes after the last commit.

**6. Start New Draft**

* Creates a new draft project version by copying:
  * The last `COMMITTED` project version.
  * Its manifest, linking to `COMMITTED` resources.

**7. Create Branch**

* Creates a new branch and draft project version:
  * Copies the selected `COMMITTED` project version.
  * Updates the manifest to reference existing `COMMITTED` resources.

***

## Lifecycle of a project version

1. **Create Project**: Automatically starts with a draft (work-in-progress) project version.
2. **Modify Resources**: Draft (WIP) resources can be edited directly, while `COMMITTED` resources are cloned into draft (WIP) before editing.
3. **Commit Changes**: Promotes the project version and its resources to `COMMITTED` status.
4. **Start New WIP**: Allows iterative development by creating a new draft version.
5. **Create Branch**: Enables parallel development with isolated draft versions.

***

## Starting a new draft version

You can initiate a new draft (work-in-progress) version while keeping the committed version intact. A draft version is automatically created under the following circumstances:

* **New Project**: When you create a new project, a corresponding draft version is initiated. This ensures that ongoing changes are tracked separately from the committed version.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2013.35.54.gif)

* **New Branch Creation**: The creation of a new branch in the system also triggers the creation of a draft version (from a committed version only). This simplifies the process of branching and development, allowing for parallel progress without impacting the main committed version.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-28%20at%2013.39.50.png)

* **Manual Draft Version Creation**: You have the flexibility to initiate a new draft version manually. This is particularly useful when building upon the latest version available on a branch.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2013.47.04.gif)

***

## Advanced features

### Committing changes

You can commit changes exclusively on work-in-progress (WIP) versions. Changes can be committed using the designated action within the version menu. Upon triggering the commit action, a modal window appears, prompting you to provide a commit message.

> [!NOTE]
>
> A string of maximum 50 characters, mandatory for commit. Only letters, numbers, and characters \[] () . \_ - / are allowed. On SaaS (5.13), punctuation such as commas is also accepted; see [Commit descriptions and details](#commit-descriptions-and-details).&#x20;

The placeholder indicating work-in-progress is replaced with a "committed" state within the graph view.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The commit modal also checks the version for problems and shows what it found next to each changed resource. The findings do not block the commit. See [Checking a version for issues](./checking-for-issues).

#### Updating commit messages

You have the flexibility to modify commit messages after changes are committed. This can be accomplished using the action available in the version menu.

#### Commit descriptions and details

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![Commit Changes modal with a commit message and a longer description filled in, character counters under both fields, and the list of changed resources](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/versioning-commit-changes-description.png)

![Commit details in the branching overlay Details panel, showing the commit date, editor, version ID, commit message, and description](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/versioning-commit-details.png)

A commit can carry a longer description next to its short commit message. The commit message stays the short label you see in the branch graph and commit history, and the description records what changed and why.

When you commit, the **Commit Changes** modal has two fields:

* **Commit Message**: required, between 2 and 50 characters. Punctuation such as commas is accepted.
* **Description**: optional, up to 2000 characters. A counter under the field shows how many characters you have used.

Click **Commit** to create the version. Spaces at the start and end of both fields are trimmed, and a description left empty is not saved.

The **Merge Branch** modal has the same optional **Description** field under **Merge Message**, with the same 2000-character limit, so a merge can explain what it brings in.

To read the message and description of a committed version:

**1. Select a committed version**

In the branching overlay, select a committed version. Its commit message appears as a button in the **Details** panel.

**2. Open the commit details**

Click the commit message button. The **Commit details** view opens and shows the version state, **Edited by**, **Version ID**, the full **Commit message**, and the **Description**. When a version has no description, a dash is shown instead.

**3. Go back to the version details**

Click the back arrow in the **Commit details** header to return to the **Details** panel and its list of changed resources.

To change the message or description of a committed version, open its **Commit details** view and click the pencil icon (**Rename Commit Message**) in the header. The **Edit Commit Message** modal opens with the same **Commit Message** and **Description** fields. Click **Save** to apply the change. The icon is shown only if you can edit the project.

### Creating a new branch

Using versioning you can work on a stable copy of the project, isolated from ongoing updates by other users. You can create a new branch starting from a specific commit point.
The initiation of new branches is achieved using the dedicated action located in the left menu of the chosen commit point (used as the starting point for the branch).

> [!WARNING]
>
> A branch name is mandatory. It can be up to 16 characters long and can use letters, digits, and the characters `[ ] ( ) . - _ /`. On SaaS, the limit is 40 characters (SaaS · 6.0).

### Merging changes

You can incorporate updates made on a secondary branch into the main branch or another secondary branch. To ensure successful merging of changes, adhere to the following criteria:

* You can merge the latest version from a secondary branch into either its direct or indirect parent branch.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2015.42.30.gif)

* Upon triggering the merge action, a modal window appears, giving the possibility to make the following selection:
  * **Branch**: Displays the branches to which the current branch is a child (direct or indirect).
  * **Message**: A string of maximum 50 characters (limited to letters), numbers and the following characters: \[] () . \_ - /.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/merge_changes.png)

The graph representation is updated to display the new version on the selected parent branch and the merged version is automatically selected, facilitating further development and tracking.

### Managing branches

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Branch management grew a set of operations of its own, available from the branching overlay and the branch info panel:

* **Merge to any branch**: the merge modal's **Branch** list now offers every branch the current branch can merge into, not only its direct or indirect parents.
* **Archive Branch**: retire a branch you are done with. A **Reason** is required ("Why is this being archived?"), and the branch's info panel then shows who archived it and why. Versions already merged into other branches are kept there. An archived branch can be restored with **Unarchive Branch**.
* **Delete Branch**: permanently remove a branch from the branching overlay. Deleting is blocked while the branch has child branches, an uncommitted draft, or a merge in progress, and if unmerged commits would be lost you must type the branch name to confirm. It requires its own permission, so not everyone who can edit a project can delete its branches.
* **Branch info panels**: selecting a branch or a version in the branching overlay opens an info panel with its **Branch Summary**, and versions merged from another branch show where they came from, including whether that source branch has since been archived.

### Managing conflicts

The Conflict Resolution and Version Comparison feature provides a mechanism to identify and address conflicts between two process versions that, if merged, could potentially disrupt the integrity of a project.

The system displays both the version to be merged and the current version on a single screen, providing a clear visual representation of the differences. Conflicts and variations between the two versions are highlighted, enabling users to readily identify areas requiring attention.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2015.54.48.gif)

> [!TIP]
>
> Unless specified otherwise, changes from the source branch will be prioritized.

> [!NOTE]
>
> Not all changes are considered conflicts, changes in node positions are not treated as conflicts. Primary causes lie in identifying differences within business rules, expressions, and other scripts. For how the merge decides which layout to keep, see [Node layout after merging](#node-layout-after-merging).

#### Merging without conflicts

Easily merge secondary branches into the main branch or other branches when no conflicts are detected. The updated merge modal includes:

* A clean interface for branch selection.
* A mandatory, validated commit message field (max 50 characters).
* Real-time feedback for successful merges and updates to the branching graph.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The merge modal also takes an optional **Description** of up to 2000 characters next to the merge message. See [Commit descriptions and details](#commit-descriptions-and-details).

#### Advanced conflict detection

The new **Conflicts Detected Modal** provides a detailed overview of conflicting changes, with features such as:

* Clear grouping by resource type (e.g., Processes, Enumerations, Media Library).
* Scrollable lists and clickable entries to resolve conflicts efficiently.
* A comprehensive comparison of source and target branch differences for context.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)

#### Resource-level conflict resolution

Resolve conflicts directly at the resource level with an intuitive interface:

* **JSON Comparisons:** Visualize differences with color-coded highlights (source: yellow, target: blue).
* **Navigation Support:** Quickly jump between differences for efficient resolution.
* **Progress Tracking:** Mark resources as “Reviewed” or “Seen” to monitor resolution progress.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)

#### Substitution tag conflicts

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Substitution tag conflicts are resolved per tag and per language. Each tag appears under its key, and its values per language appear under **Translations**:

* **Deleted on one branch, changed on the other:** select the tag to open its **Translations** and choose a side. The tag is kept or deleted to match the side the Translations end on.
* **Renamed differently on each branch:** the merged version keeps both names as two separate tags.

#### Flexible merge overrides

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)

#### Merging empty User Task nodes

Adding components to the same **User Task** node on two parallel branches, when that node was empty at the point the branches diverged, is a special case the merge can't resolve as a conflict. Each branch creates its own root container with a distinct ID, so there is no shared resource to compare and the system doesn't flag a conflict.

Starting with FlowX.AI 5.9.2, when this happens the merge keeps the **source branch** container together with all of its content and removes any other root containers. To review or recover removed content, open the previous version from the [Resource history](#resource-history).

> [!WARNING]
>
> As a best practice, avoid this pattern: add at least one component to a **User Task** node before branching, so both branches modify the same container instead of creating separate root containers. In releases before 5.9.2, merging two branches that each added a root container to the same empty User Task node can leave the merged screen unable to render, and starting the process returns an error.

#### Node layout after merging

Node positions and swimlane sizes are not part of conflict detection. A merge never flags layout differences, and it reports success even when the resulting diagram needs manual cleanup.

Which layout the merge keeps depends on whether the process also changed on the target branch after the branch was created:

* **Process unchanged on the target branch**: the merge applies the source branch layout as is.
* **Process changed on both branches**: the merge keeps the node positions and swimlane size of the target branch. Nodes that were repositioned on the source branch return to their target-branch positions (a node moved to a different swimlane keeps its source-branch position), while nodes added on the source branch keep their source-branch coordinates. New nodes can therefore end up on top of existing nodes or outside the swimlane, shown in a red error state.

Any committed change to the process on the target branch counts as a change here, including a layout-only rearrangement. If a node has a genuine conflict and you resolve it by keeping the source version, that node also takes its source-branch position, so a merged diagram can mix positions from both branches.

Only the placement is affected: sequences, node configuration, and the other merged changes are applied correctly, and the process still commits and runs.

> [!TIP]
>
> After merging a branch where the same process changed on both sides, review the diagram and rearrange any overlapping nodes. If new nodes ended up outside the swimlane, resize the swimlane in a single drag that makes it large enough to contain every node at once; a resize that still leaves nodes outside its bounds is rejected.

### Read-only state

The Read-Only State feature allows you to access and view committed versions of your projects while safeguarding the configuration from unintended modifications. By recognizing the visual indicators of the read-only state, you can confidently work within a controlled environment, ensuring the integrity of project's process definitions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-28%20at%2011.54.39.png)

***

## Builds

A **build** is a deployable snapshot of a committed project version, packaged and prepared for deployment to a runtime environment. Builds enable you to create immutable, versioned packages that can be deployed consistently across different environments.

> [!NOTE]
>
> You can create multiple versions of a project before creating a build. You can create a build for any committed project version. Once created, a build cannot be edited—you'll need to create a new project version and generate a new build to incorporate changes.

### Creating a build

To create a build from a committed project version:

**1. Navigate to Version Details**

Access the version details panel for the committed version you want to build. You can only create builds from committed versions, not from draft (WIP) versions.

**2. Open Create Build Dialog**

Click the **Create Build...** button in the version details panel. This opens the build creation modal.

![Create Build](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build.png)

Create Build

**3. Configure Build Settings**

In the **Create build** modal, configure the following settings:

* **Name**: The build name (defaults to the project name). This helps identify the build in the builds list.
* **Build Tag Version**: Set the semantic version for this build:
  * **Major**: Major version number (e.g., `1`)
  * **Minor**: Minor version number (e.g., `0`)
  * **Patch**: Patch version number (e.g., `0`)

The build tag follows semantic versioning format (e.g., `1.0.0`) and helps track different builds of the same project version.

**4. Save the Build**

Click **Save** to create the build. The build is now available in the Builds section and can be deployed to runtime environments.

![Create Build Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build_modal.png)

### Managing builds

The **Builds** section provides a centralized interface for viewing and managing all builds for your project.

![Builds Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/builds_interface.png)

#### Builds list

The builds list displays all builds created for the project, showing:

* **Build name and version**: Displays the build name and tag version (e.g., `Update_process_variables 1.0.0`)
* **Build actions**: Each build entry provides quick access to:
  * **Play/Run**:
    * Test build
    * Test endpoint
    * Test workflow
    * Test operation
  * **Export**:
    * Export the build
  * **More options**: Additional actions via the context menu
    * View contents
    * Workflow test instances
    * Audit log
    * Apply indexes

#### Searching builds

Use the **Search by build tag** field to quickly find specific builds by their version tag or name.

### Exporting versions

You can export project versions for backup, migration, or sharing across environments. The export process includes an option to include binary files.

**1. Select Version to Export**

Navigate to the version details panel and select the version you want to export.

**2. Initiate Export**

Click the **Export Version** button in the version details panel.

**3. Choose Binary Files Option**

When exporting, a modal appears asking whether to include binary files:

* **Include**: Includes binary files (e.g., images, documents) in the export. This may increase the export size and import time.
* **Don't include**: Exports only the project structure and configurations without binary files.

> [!WARNING]
>
> Including binary files may significantly increase the export file size and the time required to import the version in another environment.

**4. Complete Export**

Click **Continue** to proceed with the export. The exported file can be imported into other environments or workspaces.

![Export Version Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/export_version.png)

> [!NOTE]
>
> For detailed information about importing exported versions and builds, see the [Export/Import documentation](../../flowx-designer/managing-a-project-flow/export-import-a-process-definition).

### Build immutability

Once a build is created, it becomes immutable—you cannot modify its contents. This ensures:

* **Consistency**: The same build behaves identically across all environments
* **Traceability**: You can always identify exactly which project version is running
* **Stability**: Prevents accidental changes that could affect production systems

To incorporate changes into a build:

1. Make your changes in the project (creating a new draft version)
2. Commit the changes to create a new project version
3. Create a new build from the updated committed version

<video />

***

## Audit view

The "Open Audit View" provides you with a detailed audit log of actions related to work-in-progress (WIP) versions of a process. The primary goal is to ensure transparency and accountability for actions taken before the commit or save process.

You can quickly access and review the history of WIP versions, facilitating efficient decision-making and collaboration.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/versioning_audit_log.gif)


# Reference types in resources usage
Source: https://docs.flowx.ai/5.9/docs/projects/reference-types

Understanding how Reference Type values are determined in the Resource Usage Overview and why certain values appear based on the underlying resource model.

## Overview

The **Resource Usage Overview** in FlowX.AI tracks where and how resources (such as enumerations, media files, processes, and workflows) are referenced throughout your projects. A key column in this overview is the **Reference Type**, which indicates the type of element that directly contains the reference to a resource.

![Resource Usage Overview showing Reference Type column](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

### Why reference type matters

Understanding Reference Type helps you:

* **Identify the exact location** of resource references within your project
* **Understand dependency chains** before modifying or deleting resources
* **Navigate directly** to the element containing the reference
* **Plan impact analysis** when updating shared resources

### How FlowX.AI identifies references

FlowX.AI identifies resource references through **sub-resources**—the actual elements that contain references, rather than their parent containers. This distinction is crucial for understanding why certain Reference Type values appear.

For example, when an enumeration is used in a User Task node, the reference is technically stored inside the **UI Template** attached to that User Task—not in the User Task node itself. Therefore, the Reference Type displays **UI Template**, not "User Task".

***

## Reference type values

Reference type values are derived from two sources in the FlowX data model:

1. **Element Types** — The type of element within a service that contains the reference
2. **Element Path Types** — The specific path or context within that element

### Element types

Element types identify the owner service, source resource, and the element containing the reference:

| Element Type | Owner Service | Source Resource | Description |
| :- | :- | :- | :- |
| `uiTemplate` | admin | process | UI Templates attached to nodes or defined as Reusable UI components |
| `action` | admin | process | Node actions (business rules, Kafka sends, subprocess starts, etc.) |
| `dataModel` | admin | process | Data model attributes and entity definitions |
| `view` | task-management-plugin | view | Task management views |
| `hook` | task-management-plugin | hook | Task management hooks |
| `allocation-setting` | task-management-plugin | allocation-setting | Task allocation rules |
| `endpoint` | integration-designer | system | System endpoints |
| `workflowNode` | integration-designer | workflow | Workflow nodes within integration workflows |

### Element path types

Element path types provide more granular context about where within an element the reference exists.

#### Process node path types

| Element Type | Element Description | Path Type (Reference Type) |
| :- | :- | :- |
| `action` | Start subprocess action | `StartSubProcessHandler` |
| `uiTemplate/action` | User Task node | `USER_TASK` |
| `action/node` | Service Task node | `TASK` |
| `action` | Call subprocess node | `SUBPROCESS_RUN` |
| `node` | Embed process node | `SUBPROCESS_EMBED` |

#### Task management path types

| Element Type | Element Description | Path Type (Reference Type) |
| :- | :- | :- |
| (none) | Allocation rule | `allocation-setting` |
| (none) | View | `view` |
| (none) | Hook | `hook` |

#### Integration Designer path types

| Element Type | Element Description | Path Type (Reference Type) |
| :- | :- | :- |
| (none) | System | `system` |
| (none) | Endpoint | `endpoint` |
| `workflowNode` | Workflow node | `workflowNode` |

#### Data model path types

When a resource (like an enumeration) is referenced in a data model attribute, the Reference Type shows the attribute's data type:

| Element Type | Element Description | Path Type (Reference Type) |
| :- | :- | :- |
| `dataModel` | Data model entity | `entity` |
| `dataModel` | String attribute | `STRING` |
| `dataModel` | Integer attribute | `INTEGER` |
| `dataModel` | Float attribute | `FLOAT` |
| `dataModel` | DateTime attribute | `DATE_TIME` |
| `dataModel` | ZonedDateTime attribute | `ZONE_DATE_TIME` |
| `dataModel` | Boolean attribute | `BOOLEAN` |
| `dataModel` | Object attribute | `OBJECT` |
| `dataModel` | Enum attribute | `ENUM` |
| `dataModel` | Currency attribute | `CURRENCY` |

#### UI Template element path types

When a resource is referenced inside a UI Template, the Reference Type shows the specific UI element type:

| Element Type | Element Description | Path Type (Reference Type) |
| :- | :- | :- |
| `uiTemplate` | Page component | `PAGE` |
| `uiTemplate` | Container component | `CONTAINER` |
| `uiTemplate` | Card component | `CARD` |
| `uiTemplate` | Form component | `FORM` |
| `uiTemplate` | Modal component | `MODAL` |
| `uiTemplate` | Stepper component | `STEPPER` |
| `uiTemplate` | Step component | `STEP` |
| `uiTemplate` | Tab component | `TAB` |
| `uiTemplate` | Zone component | `ZONE` |
| `uiTemplate` | Collection component | `COLLECTION` |
| `uiTemplate` | Table component | `TABLE` |
| `uiTemplate` | Input field | `INPUT` |
| `uiTemplate` | Text area | `TEXTAREA` |
| `uiTemplate` | Select dropdown | `SELECT` |
| `uiTemplate` | Checkbox | `CHECKBOX` |
| `uiTemplate` | Radio button | `RADIO` |
| `uiTemplate` | Switch toggle | `SWITCH` |
| `uiTemplate` | Slider | `SLIDER` |
| `uiTemplate` | Datepicker | `DATEPICKER` |
| `uiTemplate` | Button | `BUTTON` |
| `uiTemplate` | Link | `LINK` |
| `uiTemplate` | Text element | `TEXT` |
| `uiTemplate` | Image element | `IMAGE` |
| `uiTemplate` | Message element | `MESSAGE` |

***

## Why UI element types appear as Reference Types

One of the most common questions about the Resource Usage Overview is:

> "Why does the Reference Type show 'SELECT' or 'IMAGE' instead of 'User Task' when using resources in a User Task?"

### The technical explanation

In FlowX.AI's architecture, **UI Templates contain UI elements** that hold references to resources like enumerations, media files, and substitution tags. The Reference Type shows the **specific UI element type** that contains the reference, not the parent node:

```mermaid theme={"dark"}
flowchart TB
    subgraph UserTask["User Task Node"]
        subgraph UITemplate["UI Template"]
            Select["Select Component<br/>(type: SELECT)"]
        end
    end
    
    Enum[("Countries" Enumeration)]
    
    Select -. "Data Source" .-> Enum
    
    Select -.-> RefType["Reference Type = SELECT"]
    
    style RefType fill:#ffd700,stroke:#333,stroke-width:2px
    style Select fill:#e1f5fe,stroke:#0288d1
    style Enum fill:#f3e5f5,stroke:#7b1fa2
```

### The rule

> [!WARNING]
>
> **Reference Type always reflects the specific element holding the reference, not the process node containing it.**

This means:

| Scenario | What contains the reference | Reference type shown |
| :- | :- | :- |
| Enumeration in Select dropdown | Select component in UI Template | `SELECT` |
| Enumeration in Radio buttons | Radio component in UI Template | `RADIO` |
| Enumeration in Data Model | Data model attribute | `ENUM` |
| Media file in Image component | Image element in UI Template | `IMAGE` |
| Substitution tag in Text | Text element in UI Template | `TEXT` |
| Process called from action | Action on the node | `StartSubProcessHandler` or `SUBPROCESS_RUN` |
| Workflow in integration node | Workflow node | `workflowNode` |

### Why this design?

This design reflects the actual data model and provides:

1. **Precision** — Shows the exact UI element type or data model attribute type that contains the reference
2. **Consistency** — The same UI element type (like `SELECT`) produces the same Reference Type regardless of whether it's in a User Task or Reusable UI
3. **Actionable information** — You know immediately what type of component needs to be modified if you want to change the reference

***

## Reference type by resource category

Different resource types generate different Reference Type values based on how they're used in the platform.

### Process references

Processes can be referenced from multiple contexts:

| Reference Context | Element | Reference Type |
| :- | :- | :- |
| Start subprocess action | Action | `StartSubProcessHandler` |
| Call activity node | Action | `SUBPROCESS_RUN` |
| Embedded subprocess | Node | `SUBPROCESS_EMBED` |
| Task management view | View | `view` |
| Task management hook (parent process) | Hook | `hook` |
| Task management hook (triggered process) | Hook | `hook` |
| Allocation rule | Allocation Setting | `allocation-setting` |

> [!NOTE]
>
> Hooks reference two processes: the **parent process** (which triggers the hook) and the **triggered process** (which runs when the hook fires). Both create separate resource usage entries with Reference Type `hook`.

### Enumeration references

Enumerations are primarily referenced in UI components, data models, and integration systems:

| Reference Context | Element | Reference Type |
| :- | :- | :- |
| Select dropdown | UI Template | `SELECT` |
| Radio button group | UI Template | `RADIO` |
| Checkbox group | UI Template | `CHECKBOX` |
| Data model attribute (ENUM type) | Data Model | `ENUM` |
| System endpoint (enumeration mapping) | Endpoint | `endpoint` |

> [!TIP]
>
> Enumerations used as data sources in UI components will show the specific UI element type (like `SELECT` or `RADIO`) as the Reference Type, not just "UI Template."

### Media file references

Media files (images, icons, documents) are referenced in UI Templates:

| Reference Context | Element | Reference Type |
| :- | :- | :- |
| Image component | UI Template | `IMAGE` |
| Button with icon | UI Template | `BUTTON` |
| Card component | UI Template | `CARD` |
| Container background | UI Template | `CONTAINER` |
| Any UI element with image property | UI Template | Corresponding element type |

### Substitution tag references

Substitution tags are used for dynamic text content and are only referenced in UI Templates:

| Reference Context | Element | Reference Type |
| :- | :- | :- |
| Text element | UI Template | `TEXT` |
| Button label | UI Template | `BUTTON` |
| Input placeholder | UI Template | `INPUT` |
| Any text-containing element | UI Template | Corresponding element type |

> [!NOTE]
>
> Substitution tags are referenced using the format `@@path.to.SubstitutionTag` within UI Template text properties. The Reference Type will show the specific UI element type where the tag is used.

### Workflow references

Integration workflows can be referenced from:

| Reference Context | Element | Reference Type |
| :- | :- | :- |
| Start Integration Workflow action | Action | Action type |
| Receive Message Task (Workflow data stream) | Node | Node type |
| Subworkflow node in another workflow | Workflow Node | `workflowNode` |

### System and endpoint references

Integration systems and their endpoints appear in workflow configurations:

| Reference Context | Element | Reference Type |
| :- | :- | :- |
| Workflow node using endpoint | Workflow Node | `workflowNode` |
| Enumeration mapping configuration | Endpoint | `endpoint` |

### Resources not tracked as usages

Some resource types are **not used by other resources** and therefore don't appear as Reference Types when viewing other resources:

| Resource Type | Notes |
| :- | :- |
| View | Views use processes, but views themselves are not referenced by other resources |
| Hook | Hooks reference processes, but hooks themselves are not referenced by other resources |
| Allocation Rule | Allocation rules reference processes, but are not referenced by other resources |
| Configuration Parameters | Not tracked as resources; used as string values in business rules |
| Document Templates | Referenced by name in Kafka send actions, not by resource ID |
| Notification Templates | Referenced by name in Kafka send actions, not by resource ID |

***

## Examples

### Example 1: enumeration used inside a User Task

**Scenario**: You have a "Country" enumeration used in a Select dropdown within a User Task node's UI.

**Resource**: `Countries` enumeration\
**Location**: User Task node → UI Template → Select component → Data Source

**Result in Usage Overview**:

| Resource | Reference Type | Reference Path |
| :- | :- | :- |
| Countries | `SELECT` | Process: Onboarding → Node: SelectCountry → UI Template |

> [!TIP]
>
> Even though you navigate through the User Task to find this enumeration, the **Reference Type is `SELECT`** because that's the specific UI element type that contains the data source reference.

### Example 2: enumeration used inside a Reusable UI

**Scenario**: You have a "Document Types" enumeration used in a Select component within a Reusable UI component.

**Resource**: `DocumentTypes` enumeration\
**Location**: Reusable UI → UI Template → Select component → Data Source

**Result in Usage Overview**:

| Resource | Reference Type | Reference Path |
| :- | :- | :- |
| DocumentTypes | `SELECT` | Reusable UI: DocumentSelector → UI Template |

> [!NOTE]
>
> Notice that both User Task UI and Reusable UI show **`SELECT`** as the Reference Type. This is because the referencing element is a Select component in both cases, regardless of whether it's in a User Task or Reusable UI.

### Example 3: workflow referenced in a workflow node

**Scenario**: An integration workflow "SendNotification" calls another workflow "EmailService" from one of its nodes.

**Resource**: `EmailService` workflow\
**Location**: Workflow: SendNotification → Workflow Node: CallEmail

**Result in Usage Overview**:

| Resource | Reference Type | Reference Path |
| :- | :- | :- |
| EmailService | workflowNode | Workflow: SendNotification → Node: CallEmail |

### Example 4: data model attribute using ENUM type

**Scenario**: A data model has an attribute "accountType" with type ENUM referencing the "AccountTypes" enumeration.

**Resource**: `AccountTypes` enumeration\
**Location**: Process: AccountOpening → Data Model → accountType attribute

**Result in Usage Overview**:

| Resource | Reference Type | Reference Path |
| :- | :- | :- |
| AccountTypes | ENUM | Process: AccountOpening → Data Model: accountType |

### Example 5: media file used in UI Template inside a node

**Scenario**: A company logo image is used in a Card component header within a User Task.

**Resource**: `company_logo.png` media file\
**Location**: User Task node → UI Template → Card → Image component

**Result in Usage Overview**:

| Resource | Reference Type | Reference Path |
| :- | :- | :- |
| company\_logo.png | `IMAGE` | Process: Welcome → Node: ShowBranding → UI Template |

> [!WARNING]
>
> The Reference Type is **`IMAGE`** (the UI element type), not "User Task" or the specific node type. The media file reference lives inside an Image component within the UI Template, regardless of which node contains that template.

***

## How resource usage tracking works

Understanding the technical architecture behind resource usage tracking helps explain why Reference Types appear the way they do.

### Resource usage data model

When a resource reference is detected, FlowX.AI stores the following information:

| Field | Description |
| :- | :- |
| Source Application Version | The app version containing the reference |
| Source Resource Definition ID | The resource definition where the reference exists |
| Source Resource Type | Type of the containing resource (such as process) |
| Source Element ID | The specific sub-element ID (such as UI Template ID) |
| Source Element Type | The type of sub-element (such as `uiTemplate` or `action`) |
| Source Location | The specific field path (such as `flowxProps.dataSource`) |
| Target Resource Definition ID | The referenced resource's definition ID |
| Target Application ID | The app containing the referenced resource |
| Target Resource Type | Type of the referenced resource (such as enumeration) |

### Operations that affect resource usages

Resource usage entries are created, updated, or deleted when you perform these operations:

**For UI Templates:**

* Update UI template properties
* Delete UI template
* Copy/paste UI templates or nodes
* Undo/redo operations
* Import/export processes

**For Actions:**

* Create, update, or delete actions
* Update node configurations
* Copy/paste nodes
* Import/export processes

**For Data Model:**

* Add or modify attributes with ENUM type
* Delete data model attributes

**For Task Management:**

* Create, update, or delete views
* Create, update, or delete hooks
* Create or delete allocation rules

**For Integration Designer:**

* Configure workflow nodes
* Set up endpoint enumeration mappings

***

## Understanding the resource hierarchy

To fully understand Reference Types, it helps to understand FlowX.AI's resource hierarchy:

### Resources vs sub-resources

| Category | Examples | Can be a Reference Type? |
| :- | :- | :- |
| **Top-level resources** | Processes, Workflows, Enumerations, Media Files, Systems | These are what get referenced, not reference types themselves |
| **Sub-resources (reference containers)** | UI Templates, Actions, Data Model attributes, Workflow Nodes | Yes, these appear as reference types |
| **Parent containers** | User Task nodes, Service Task nodes, Gateway nodes | No, the parent node type is not the reference type |

### Why parent node types never appear as reference types

Parent nodes (like User Task, Service Task, or Call Activity) are containers that **hold** sub-resources. The actual reference always lives inside a sub-resource:

* **User Task** → contains UI Template (reference is in UI Template)
* **Service Task** → contains Actions (reference is in Action)
* **Call Activity** → contains Action configuration (reference is in Action)

The parent node type provides **context** for navigation but is not the Reference Type itself.

***

## Frequently asked questions

> [accordion] Why doesn't Reference Type show 'User Task'?
>
> Reference Type reflects the **actual element containing the reference**, not the parent node. When you use an enumeration in a User Task's interface, the reference is stored in the **UI Template** attached to that User Task. Therefore, the Reference Type shows the specific UI element type (like `SELECT` or `RADIO`).
>
> The User Task is simply the container node—it doesn't directly hold the enumeration reference; the UI Template inside it does.

> [accordion] Why does everything look like a UI element type?
>
> Many resources (enumerations, media files, substitution tags) are primarily used within user interfaces. Since all UI components are defined inside UI Templates—whether those templates are attached to User Tasks, Reusable UI components, or other UI-enabled nodes—the Reference Type shows the specific UI element type (like `SELECT`, `IMAGE`, `TEXT`, etc.).
>
> This is accurate and provides precise information about exactly which UI component contains the reference.

> [accordion] Can navigation areas create resource usages?
>
> Navigation areas define the structure and routing of your application's UI. If a navigation area has an associated UI Template that references resources like enumerations or media files, those references will be tracked with the corresponding UI element type as the Reference Type.

> [accordion] Do configuration parameters appear as Reference Types?
>
> No. Configuration parameters are not tracked as resources. They are used as string values within business rules and do not appear in the Resource Usage Overview. The usage of configuration parameters is not set explicitly—they are configured in business rules as strings.

> [accordion] Do substitution tag values appear as Reference Types?
>
> Substitution tags are referenced in UI Templates using the format `@@path.to.SubstitutionTag`. When you view the usage of a substitution tag, the Reference Type will show the specific UI element type (like `TEXT` or `BUTTON`) where the tag is embedded.
>
> Note that substitution tags exist as a single resource per application version, and only their individual values are tracked for usage.

> [accordion] How do I find all usages of a resource in User Tasks specifically?
>
> While the Reference Type shows the specific UI element type, the **Reference Path** column provides the full context including the parent node. You can use this path to identify which User Tasks contain UI elements that reference your resource.
>
> Look for paths like: `Process: [Name] → Node: [UserTaskName] → UI Template`

> [accordion] What's the difference between 'action' and specific handler types like 'StartSubProcessHandler'?
>
> The Reference Type can show either the general element type (`action`) or a more specific path type depending on the context:
>
> * **`StartSubProcessHandler`** — Start subprocess action type
> * **`SUBPROCESS_RUN`** — Call activity (call subprocess) node
> * **`SUBPROCESS_EMBED`** — Embedded subprocess node
> * **`TASK`** — Service task node
> * **`USER_TASK`** — User task node
>
> The specific types provide more granular information about what kind of node or action holds the reference.

> [accordion] Why don't Document and Notification Templates appear in resource usages?
>
> Document templates and notification templates are referenced **by name** in Kafka send action configurations, not by resource ID. The actual template resource ID is resolved at runtime by the document and notification services based on the template name and build ID. Because they're referenced by name (a string value) rather than by resource definition ID, they are not tracked in the Resource Usage Overview.

> [accordion] What happens to resource usages when I create a new application version?
>
> When you create a new application version (WIP), the resource usages are cloned from the source version. This ensures that the new version has an accurate picture of all resource references. When you discard a WIP version, its resource usages are also discarded.

> [accordion] What happens to resource usages during import/export?
>
> Resource usages are included when exporting applications and are restored during import. The resource definition IDs remain the same when exporting and importing an application, ensuring that the usage tracking remains accurate.

> [accordion] Can I see usages for resources from library dependencies?
>
> Yes. When your project uses resources from library dependencies (like enumerations or media files from a shared library), those usages are tracked. The resource usage entry stores both the source location (where the reference exists in your project) and the target resource information (including the library's application ID).

***

## Summary

The Reference Type in the Resource Usage Overview accurately reflects FlowX.AI's internal resource model:

**1. References live in sub-resources**

Actual resource references are stored in sub-resources like UI Templates, Actions, and Data Model attributes—not in parent node types.

**2. Reference Type shows the container**

The Reference Type displays the type of element that directly contains the reference, providing accurate technical information.

**3. Parent context is in the path**

While the Reference Type shows "UI Template", the full Reference Path includes parent information like the node name and process for complete context.

**4. Consistency across contexts**

The same resource used in different contexts (User Task UI vs. Reusable UI) shows the same Reference Type because the referencing element is the same—a UI Template.

Understanding this model helps you:

* Correctly interpret the Resource Usage Overview
* Plan changes with accurate impact analysis
* Navigate efficiently to the actual location of resource references


# Resources
Source: https://docs.flowx.ai/5.9/docs/projects/resources

Overview of Global and project resources, including their usage, dependencies, promotion, and configuration within the platform.

## Overview

Resources are categorized into **Global Resources** and **Project Resources**. Each type has unique characteristics that define its usage, dependencies, and promotion between environments. Understanding these distinctions ensures efficient project development, management, and deployment.

***

## Global resources

Global Resources are designed for **reuse across multiple projects** or business contexts.

> [!NOTE]
>
> These resources are often organized within **libraries**, enabling consistency and efficiency by providing a central repository of shared components.

### Key characteristics

* **Reusable**: Common design elements, themes, fonts, and other assets can be used in multiple projects.
* **Independent**: Global Resources exist outside individual projects, making them adaptable across different business cases.
* **No Dependencies**: These resources are not project-specific, making them versatile for broad use cases. Projects can reference libraries without requiring modifications to the core resources.

### Examples

#### Design assets

* **Themes**: Standardized themes for consistent styling.
* **Global Media Library**: Shared images, icons, and other assets.
* **Fonts**: Reusable font families to maintain branding.

#### Plugins

* **Languages**: Language packs or configurations that support multilingual capabilities across projects.
* **Templates**: Notification and document templates managed at a global level.
* **Out-of-Office Settings**: Platform-wide absence management settings.

#### General settings

* **Users**: User accounts and profiles that can be accessed across multiple projects.
* **Roles**: Defined roles that determine user permissions and access levels.
* **Groups**: User groupings that facilitate collective management and permissions.
* **Audit Log**: Logs that track changes and activities within the platform for security and compliance purposes.

#### Libraries

Organized resource containers including **enumerations**, **substitution tags**, and **CMS components** for multi-project use.

### Promotion workflow

* **Library Promotion**: Global Resources within libraries are promoted separately from projects. They are typically **imported into the Designer UI** in target environments as part of their own libraries.
* **Configuration Management**: When libraries are promoted, existing configurations, such as **generic parameters**, are replaced by project-level configurations in the target environment.

***

## Project resources

Project Resources are specific to a **business use case**. Unlike Global Resources, they belong to a single project, allowing for custom configurations and dependencies on libraries.

### Key characteristics

* **Project-Specific**: Tailored to a single project’s needs.
* **Library Dependencies**: Can reference and extend Global Resources.
* **Configurable**: Parameters can be updated in upper environments through environment variables or overrides.

### Examples

1. **Processes**: BPMN workflows customized for the project’s business logic.
2. **CMS Components**: Project-specific enumerations, substitution tags, and media items.
3. **Task Management**:
   * **Views**: Configurable interfaces to display task-related data based on process definitions.
   * **Stages**: Stages that allow task progression through different statuses.
   * **Allocation rules**: Define how tasks are assigned to users or teams.
4. **Integration Designer**:
   * **Systems**: A system is a collection of resources—endpoints, authentication, and variables—used to define and run integration workflows.
   * **Workflows**: A workflow defines a series of tasks and processes to automate system integrations. Within the Integration Designer, workflows can be configured using different components to ensure efficient data exchange and process orchestration.
5. **Configuration Parameters**: Project-specific rendering settings like `applicationUuid`, `locale`, `language`, and `process parameters`.
6. **Project Builds**: Builds represent finalized versions of the project, including all associated metadata and linked library versions.
7. **Version Settings**: Configure various aspects of a project like platform type, default theme, formatting, etc.

### Promotion workflow

* **Build-Based Promotion**: Only **builds** (not commits) are promoted.
* **Design Asset Handling**: Referenced assets are created if missing but are not updated during import.
* **Configuration Parameters Overrides**: Environment variables replace default values in upper environments.

***

## Resources usage tracking

Track where resources are used to prevent unintended changes and ensure stability.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

The **Resource Usage Tracking** feature provides real-time visibility into where and how resources are being used, preventing unintended changes and ensuring system stability.

**Key features**

* **View Dependencies** before making updates or deletions.
* **Understand Resource Interactions** across projects.
* **Prevent Issues** when modifying critical elements.

Each resource type includes a **Usage Overview modal**, which updates dynamically as references change.

### Process usage

1. **Access Usage Overview**
   * Click the **Usage Overview icon** in the **Process List**.
2. **Usage Modal Details**
   * Displays references by resource type (e.g., Process, UI Template, Workflow).
   * Provides detailed context, including node configurations.

#### Deleting a process with references

* A **confirmation modal** warns users before deletion.
* The modal lists all affected references.

### Enumeration usage

1. **Access Usage Overview**
   * Click the **Usage Overview icon** in the **Enumeration List**.
2. **Usage Modal Details**
   * Shows where the enumeration is referenced (e.g., UI Designer, Data Model, Workflow)

### Media library usage

1. **Access Usage Overview**
   * Click the **Usage Overview icon** in the **Media Library List**.
2. **Usage Modal Details**
   * Displays where media files are used (e.g., UI Template, Process).

***

### Managing dependencies & tracking changes

* **Dynamic Updates**: Reference lists update automatically as resources change.
* **Dependency Checks**: Users see affected resources before deletion.
* **Bidirectional Tracking**: The **Usage Overview modal** also shows resources referenced **inside** a process.

***

## How do I document a resource?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Supported resources have a **Documentation** item in their menu, in the resource list and on the resource's own page. It opens the **Documentation** window for that resource, with two fields:

* **Description**: a short summary of what the resource is for, up to 1,000 characters.
* **Documentation**: longer notes in Markdown, up to 65,535 characters. Switch between **Write** and **Preview** to check the formatting.

Click **Save** to keep the changes. If you can only view the resource, the window is read-only and has a **Close** button instead.

You can document these resources:

* UI flows
* Reusable UI templates
* Custom components
* Document templates
* Notification templates
* Task Manager views
* UI components on a page: select the component, then in the configuration panel open **More** (⋮) and select **Documentation**
* Knowledge base stores: in the knowledge base's stores list, open the store's menu
* Navigation areas: open the area's menu on the process canvas or in the process navigation panel. An area shows the documentation of its root UI template. Parent process and embedded subprocess areas don't have the item.
* User tasks: open the task's menu in the process navigation panel. It shows the documentation of the user task node.

In the UI Designer, the **Documentation** item isn't shown for components inside an embedded subprocess, or for components that belong to a reusable UI template used on the page. Document those in the template itself.

Edit a resource's description in its **Documentation** window. The create and details windows of workflows, data sources, UI flows, reusable UI templates, custom components, and Task Manager views don't have a **Description** field. For Media Library assets, see [Media Library](/5.9/docs/platform-deep-dive/core-extensions/content-management/media-library#asset-descriptions).

***

## Copying resources

Use the **Copy to Another Project** feature to transfer resources while maintaining dependencies.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**
>
> Copying a process or UI Flow to another project also copies the resource's associated roles, so you don't have to recreate access configuration by hand after a copy.

<video />

**1. Select a resource from the list**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.23.08.png)

**2. Choose a Destination Project or Library**

Choose the target project or library.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.28.04.png)

**3. Pick a branch (if applicable)**

Select the target branch.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.29.50.png)

**4. Review Dependencies before copying**

The system displays referenced resources and validates dependencies.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.47.22.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.48.53.png)

**5. Include Substitution Tags (optional)**

If necessary, copy all substitution tags from a project to the target project. Existing substitution tags in the target project with the same key will not be overwritten.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.52.45.png)

**6. Resolve Identifier Conflicts**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2011.54.07.png)

If an identifier already exists in the destination, you'll be prompted to either:

* **Keep Both**: Create a duplicate.
* **Replace**: Overwrite existing resource.
* **Use Destination**: Keep existing resource without copying.

> [!TIP]
>
> **Handling conflicts:** The system automatically detects duplicate identifiers and provides a clear choice to avoid unintended overwrites.

### Supported resource types

The copy feature is available for the following resources:

* **Process definitions** (including referenced resources)
* **Systems**
* **Workflows**
* **Enumerations** (including child enumerations)
* **Media Library items**
* **Notification** and **Document** templates

## Duplicating resources

The **Duplicate Resource** feature allows users to quickly copy resources within the same project or library.

<video />

### Supported resource types

* **Processes**
* **Enumerations**
* **Media files (including Global media library files)**
* **Notification templates**
* **Document templates**
* **Views**

### Steps

**1. Open the Three-Dot Menu next to the resources**

Duplicate options are available from each resource’s three-dot menu (table row & secondary navigation).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2014.13.45.png)

**2. Select Duplicate**

When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-26%20at%2014.18.31.png)

***

## Resources overrides

Resource overrides enable **localization and customization** of core business applications across multiple regions while maintaining centralized updates from headquarters.

> [!NOTE]
>
> Resource overrides are **only available at the project level**. Libraries cannot contain resource overrides.

### Why use resource overrides?

Resource overrides are essential for organizations that need to:

* **Build and maintain a business application HQ** that expands to multiple countries
* **Customize the core application** for each country's specific requirements
* **Keep receiving updates from HQ** without losing local customizations

> [!TIP]
>
> Think of resource overrides as a way to maintain a "master copy" at headquarters while allowing each region to adapt specific business logic, compliance requirements, or local regulations.

***

## Managing resource overrides

Resource overrides are configured through the **Dependencies** page in your project's main navigation. This interface provides comprehensive management capabilities for all your library resource customizations.

### Accessing resource overrides

**1. Navigate to Dependencies**

From your project's main menu, click on **Dependencies** to access the configuration interface.

**2. Select Resource Overrides tab**

The Dependencies page contains two tabs:

* **Dependencies**: Manages project library dependencies
* **Resource Overrides**: Configures and manages all resource overrides

### Resource overrides interface

The Resource Overrides tab displays all configured overrides in a comprehensive table with the following columns:

* **Resource Type**: The type of resource being overridden (Process, Workflow, Enumeration)
* **Original Resource**: The name of the library resource being overridden
* **Original Library**: The library containing the original resource
* **Override Resource**: The name of the resource used as the override
* **Override Source**: The source of the override resource (library name or "Local" for project resources)
* **Actions**: Edit and delete options for each override

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)

### Adding a new override

**1. Create new override**

Click the **+** button to add a new editable row at the top of the table.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro2.png)

**2. Select resource type**

Choose from the available resource types:

* **Process**
* **Workflow**
* **Enumeration**

> [!WARNING]
>
> Changing the resource type will clear any selections in the Original Resource and Override Resource fields.

**3. Choose original resource**

Select the library resource you want to override:

* Search through all available resources of the selected type
* Resources are grouped by their source library
* Already overridden resources appear disabled with a tooltip: *"An override already exists for \[resource name]"*

The **Original Library** field automatically populates with the selected resource's library.

**4. Select override resource**

Choose the resource to use as the override:

* Available resources include both local project resources and library resources
* Resources are grouped by source (project or library)
* Must match the selected resource type

The **Override Source** field automatically shows "Local" for project resources or the library name for library resources.

**5. Save or cancel**

* **Save**: Validates required fields and persists the override
* **Cancel (X)**: Discards the new override without saving

> [!TIP]
>
> Success message: "Resource override has been successfully added."

### Updating an existing override

**1. Enter edit mode**

Click the **Edit** icon on any override row to make it editable.

**2. Modify fields**

Update any of the override configuration fields following the same validation rules as adding a new override.

**3. Save changes**

* **Save**: Applies your changes to the override
* **Cancel (X)**: Reverts to the original configuration

> [!TIP]
>
> Success message: "Resource override has been successfully updated."

### Deleting an override

> [!WARNING]
>
> Deleting an override will revert the project to using the original library resource at runtime.

**1. Initiate deletion**

Click the **Delete** icon on the override you want to remove.

**2. Confirm deletion**

A confirmation modal appears asking you to confirm the deletion.

**3. Complete deletion**

Click **Confirm Delete** to permanently remove the override.

> [!TIP]
>
> Success message: "Resource override has been successfully deleted."

### Export and import with overrides

Resource overrides are automatically included when exporting and importing project versions or builds.

#### Export behavior

When exporting a project version or build:

* A JSON file containing all resource overrides is included in the export ZIP
* Override definitions include complete resource mapping information
* Both original and override resource metadata are preserved

#### Import behavior

When importing a project with resource overrides:

* All override configurations are restored from the JSON file
* Dependencies on referenced libraries are validated
* Override mappings are reestablished in the target environment

> [!TIP]
>
> Always verify that required library dependencies are available in the target environment before importing projects with resource overrides.

### Enumeration override behavior

Enumerations have special handling due to their usage patterns across the platform:

#### Current enumeration resolution

* Enumerations are resolved **by name** at runtime
* If multiple enumerations exist with the same name in the dependency tree:
  * The closest one to the project root is chosen
  * If multiple exist at the same level, the one from the build with the most recent creation date is selected

#### Enumeration usage contexts

* **UI Components**: Radio buttons, dropdowns, and multi-select components reference enumerations by name
* **Kafka Actions**: Enumeration names are embedded in message request bodies
* **Data Sources**: Enumeration mapping in endpoint configurations for value transformation
* **CMS Translation**: Both Kafka and REST requests use enumeration names for translation services

> [!WARNING]
>
> **Current limitation**: Enumeration value transformation between system codes works only when the enumeration and the system configuration are in the same library or project. A resource override cannot point that transformation at an enumeration from another library.

### Error handling and validation

The interface provides comprehensive error handling:

#### Validation errors

* **Required field missing**: *"This field is required"*
* **Duplicate override**: *"An override already exists for \[resource name]"*

#### System errors

* **Save error**: *"An error occurred while saving resource override. Please try again later."*
* **Update error**: *"An error occurred while updating resource override. Please try again later."*
* **Delete error**: *"An error occurred while deleting resource override. Please try again later."*

### Empty state

When no resource overrides are configured, the interface displays an empty state with guidance on how to create your first override.

***

## Technical concepts

Understanding the technical implementation of resource overrides helps ensure successful customization while maintaining system integrity.

### How resource overrides work

Resource overrides replace library resources at runtime while preserving the original library structure and dependencies.

#### Process overrides

When overriding processes from libraries:

* **Input/output mapping**: Ensure processes properly map input and output data
* **Node compatibility**: The override process must maintain compatibility with the original process structure
* **Data model validation**: Overrides are validated against the data model and number of nodes

> [!NOTE]
>
> You cannot completely replace a process with an entirely different process. The override must maintain the core structure and interface of the original process from the library.

#### Complex process scenarios

For processes with **multiple start nodes and end nodes**:

* Validation occurs on both data model structure and node count
* Each start/end node must have a corresponding match in the override
* Business logic can be customized while maintaining the process interface

#### Enumeration and workflow overrides

Unlike processes, **enumerations and workflows** offer more flexibility:

* Can override any enumeration with any other enumeration
* Workflow overrides allow complete replacement of business logic
* Useful for country-specific value lists and decision trees

### Override workflow

**1. Identify library dependency**

Ensure your project has a dependency on the library containing the resource to override.

**2. Select resource for override**

Navigate to the library resource you want to customize for your project.

**3. Create override**

Use the override functionality to create a project-specific version while maintaining the library reference.

**4. Customize business logic**

Modify the override to meet local requirements while preserving input/output compatibility.

**5. Test integration**

Validate that the override works correctly with call activities and other dependent resources.

### Current limitations

> [!WARNING]
>
> Be aware of these limitations in the current implementation:

* **Runtime error detection**: Some overrides with errors may only be discovered at runtime rather than design time
* **Merge conflict visibility**: When comparing JSON configurations, you'll see UUIDs instead of human-readable resource names
* **Dynamic list updates**: If library resources change significantly, they may not appear in the available override list
* **Dependency validation**: If a start node is deleted in a newer library version and doesn't match your override dependency, the system will fail at runtime

### Best practices

* **Design with overrides in mind**: When creating library processes, consider which elements might need localization
* **Maintain interface compatibility**: Ensure overrides preserve the original process's input/output contract
* **Test thoroughly**: Validate overrides in a staging environment before production deployment
* **Version management**: Keep track of library versions and test override compatibility with updates
* **Documentation**: Document the specific business reasons for each override to help with maintenance

> [!TIP]
>
> Start with a well-designed reference application in your library, then create minimal, targeted overrides rather than extensive modifications. This approach makes it easier to receive and integrate updates from headquarters.

***

## Use cases and examples

Resource overrides are particularly valuable in enterprise scenarios where centralized governance meets local customization needs.

### Multi-country application deployment

Consider a financial services company with headquarters developing a core onboarding application that needs to be deployed across different countries, each with unique requirements:

#### Architecture overview

**1. Master copy in library**

The **reference application** (master copy) is maintained in a **library** at headquarters, containing:

* Core business logic
* Standard processes (e.g., client onboarding, overdraft management)
* Common UI components and workflows
* Base data models and enumerations

**2. Country-specific projects**

Each country has its own **project** with:

* Dependencies on the master library
* Country-specific overrides for local requirements
* Custom business rules and compliance logic

**3. Process execution with call activities**

Country projects start processes using **call activities** that:

* Reference the master processes from the library
* Apply local overrides where needed
* Handle country-specific data transformations

#### Localization examples

Different countries often require customized logic for:

* **Exchange rates calculation**: Each country may use different formulas or data sources
* **Privacy policy collection**: Some countries have stricter data protection requirements
* **Compliance workflows**: Regulatory requirements vary by jurisdiction
* **Authentication methods**: Local preferences for OTP, biometric verification, etc.

### Common override scenarios

* **Regulatory compliance**: Adapting processes to meet local legal requirements
* **Language localization**: Customizing enumerations and UI elements for different markets
* **Business logic variations**: Implementing region-specific calculation methods or validation rules
* **Integration differences**: Connecting to different local systems or service providers
* **User experience adaptations**: Modifying workflows to match local business practices


# Active policy
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-policy

The active policy decides which build of a project runs at runtime, either the latest version on a branch including uncommitted changes or a build you created.

This feature plays a key role in ensuring that the correct [**project**](../managing-applications/application) configuration is executed, managing how processes interact with specific builds, and controlling how changes propagate through environments. The active policy determines which project version is currently "live", either the latest version on a branch or the version a specific build was created from, and dictates how updates and new builds are adopted.

![Active Policy](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/ap1_59.png)

> [!NOTE]
>
> Active Policy supports both global policies that apply to all users and specific policy overrides for individual users or groups, allowing independent testing of different builds or branches.

> [!WARNING]
>
> **Role-based overrides are deprecated in 5.9.0.** New overrides target users or groups; the **Role** override type has been removed from the Add / Edit modal. Any role overrides carried over from a 5.1.x upgrade remain visible in the table but are marked **DEPRECATED**, are excluded from runtime resolution, and can only be deleted. Recreate the intended access using a [group override](#policy-overrides) instead. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.

## Key concepts

### Active build

* The active build is the currently selected version of a project that is deployed in the runtime environment. It is the version that all process executions will reference when initiated.
* While a global policy applies to all users by default, individual policy overrides can specify different active builds for specific users or groups.

### Policy types

* **Latest on Branch**: Runs the latest version on a specific branch, including a work-in-progress version that isn't committed yet. You don't need to create a build. This is useful for environments like development or testing, where ongoing changes need to be reflected in real-time.
* **Build**: Points to a specific build you created from a committed version (see [Builds](./builds)). This policy ensures that only the selected build is used, preventing unexpected updates. It is typically used for UAT and Production environments.

### Policy hierarchy

* **Global Policy**: The default policy that applies to all users unless overridden.
* **Policy Overrides**: User-specific or group-specific policies that take precedence over the global policy for targeted users.
* Policy overrides enable independent testing of different builds or branches without affecting other users.

### Version control and flexibility

* Active Policy provides flexibility by allowing different users to work with different build versions simultaneously.
* By managing both global policies and overrides, you control which changes go live for which users and when, allowing for testing and controlled rollouts.

## Global policy

The Global Policy section defines the default active policy that applies to all users unless specifically overridden by individual policy overrides.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap4.png)

**1. Navigate to Active Policy**

In the left navigation, expand **Runtime Settings** and select **Active Policy**.

**2. Configure Global Policy**

In the **Global Policy** section, choose your policy type:

* **Latest on Branch**: Always use the latest version on the selected branch
* **Build**: Use a specific build from the available builds for the project

Select the branch or the build, depending on the policy type you chose.

**3. Update Policy**

Click **Update** to apply the global policy changes.

> [!TIP]
>
> The policy takes effect immediately for all users without specific overrides.

## Policy overrides

Policy Overrides allow you to define specific active policies for individual users or groups, enabling independent testing of different builds or branches without affecting the global policy.

> [!NOTE]
>
> Define policies for specific users or groups to simulate conditions and test branch behavior independently from the global policy.

### Managing policy overrides

The Policy Overrides section provides comprehensive tools for creating, managing, and monitoring user-specific and group-specific active policies.

#### Override table structure

The policy overrides are displayed in a table with the following columns:

* Override Type: Specifies whether the override applies to a **Username** or **Group**.
* Applies To: Indicates the specific Runtime User (by username) or Runtime Group (by group name) that this policy override applies to.
* Policy: Specifies the policy type to use for the override.
* Branch/Build Version: Specifies the branch or build version to use for the override.
* Priority: Required for **Group** overrides; ignored for **Username** overrides. Lower numbers take precedence when multiple group overrides apply to the same user.
* Status: Shows whether the override is **Active** or **Deactivated**.

> [!NOTE]
>
> Legacy **Role** overrides created before 5.9.0 still appear in this table with a red **Deprecated** status. They can only be deleted (no edit) and are excluded from runtime resolution. Recreate them as group overrides. The **Role overrides are no longer supported** banner above the table shows how many remain, and its **Remove All** button deletes them in one step.

#### Search and filter

Use the search functionality to quickly locate specific overrides:

* **Search by Username**: Enter a username to filter overrides for specific users
* **Search by Group**: Enter a group name to filter overrides for specific groups
* The search filters the table in real-time as you type

**1. Add New Override**

Click the **Add** button (+ icon) to create a new policy override.

**2. Configure Override Type**

Select whether the override applies to a **Username** or **Group**:

* **Username**: Choose a specific user from the dropdown
* **Group**: Select a runtime group from the available options. The picker lists only groups that have a runtime role configured for the current project.

**3. Set Policy Configuration**

Choose the policy type:

* **Latest on Branch**: Select the branch to use
* **Build**: Choose a specific build version

**4. Set Priority (Group overrides only)**

Group overrides require a priority to resolve conflicts when a user belongs to several groups that each have an override.

> [!WARNING]
>
> Priority is mandatory for group overrides and must be unique across all group overrides on the same project. Saving a group override without a priority or with a duplicate value is blocked with a validation error.

> [!TIP]
>
> Lower numbers = higher priority. Use priority 0 for the most critical overrides.

Username overrides do not use priority; they always take precedence over any group override.

**5. Enable Override**

Check **Enable this override** to activate it immediately, or leave unchecked to create it in an inactive state.

**6. Create Override**

Click **Create Override** to save the new policy override.

> [!TIP]
>
> The override appears in the table and takes effect immediately if enabled.

#### Override management actions

Each override in the table provides several management options:

**Edit Override**

* Click the edit icon to modify override settings
* Update policy type, target build/branch, or priority
* Changes take effect immediately upon saving

**Contextual Menu Actions**

* **Audit Logs**: View the change history of the override
* **Delete**: Permanently remove the override

To turn an override off without deleting it, edit it and clear **Enable this override**.

> [!WARNING]
>
> Deleting an override immediately reverts affected users to the global policy. Ensure this change is intentional.

## Key features

### Environment-specific control

* Each environment can have its own global policy and set of policy overrides
* Control what version of the project runs for different user groups at each stage of development

### User-specific testing

* Policy overrides enable individual users or groups to test different builds independently
* Developers can work and test their ongoing work simultaneously without conflicts
* QA teams can test specific builds while production users remain on stable versions

### Priority-based resolution

* When multiple group overrides apply to the same user, priority determines which takes precedence
* Fine-grained control over policy application in complex scenarios
* Clear hierarchy: Username overrides > Group overrides (lowest priority number wins) > Global policy

### Rollback capability

* Easily revert to previous builds by updating the global policy or specific overrides
* Quick rollback minimizes disruption and maintains system stability
* Independent rollback for specific users without affecting others

### Branch-specific management

* Support for branch-based policies in both global settings and overrides
* Parallel development with different active branches for different user groups
* Flexible testing scenarios across multiple development streams

## Benefits

* **Controlled Rollouts**: Gradual deployment to specific users or groups before wider release
* **Independent Testing**: Users can test different builds simultaneously without conflicts
* **Enhanced Stability**: Risk mitigation through targeted deployment and easy rollback
* **Flexible Development**: Support for parallel development streams and testing scenarios
* **User-Centric Control**: Granular policy management at the user and group level
* **Priority Management**: Clear resolution when multiple policies could apply

## Permissions and access control

Active Policy management requires appropriate permissions to ensure secure and controlled access to policy configuration.

> [!WARNING]
>
> Access to Active Policy settings should be strictly controlled as changes can affect production environments and user experience.

### Required permissions

Active Policy uses two workspace permissions:

* **`wks_active_policy_read`**: View the global policy, the policy overrides, and the effective policy
* **`wks_active_policy_edit`**: Change the global policy, and create, edit, enable, disable, and delete policy overrides

See the [permission reference](/5.9/setup-guides/access-management/permission-reference-guide) for the roles that include them.

### Permission enforcement

* Unauthorized actions are blocked with clear denial messages
* All policy changes are audited with user identification and timestamps
* Role-based access ensures users can only perform actions within their authorization level

> [!NOTE]
>
> Contact your system administrator if you need additional permissions to manage active policies.

## Technical details

### Policy resolution hierarchy

When a user accesses the runtime environment, the system resolves their active policy using this hierarchy:

1. **Username overrides** (highest priority)
2. **Group overrides** (if no username override exists; lowest priority number wins when several groups match)
3. **Global policy** (default fallback)

Legacy role overrides are skipped at this stage regardless of their saved priority.

### Priority-based override resolution

* When multiple group overrides could apply to a user, the override with the lowest priority number takes precedence
* Username overrides always take precedence over group overrides regardless of priority
* Priority numbers must be unique for group overrides on the same project and are mandatory
* Priority is particularly important when users belong to multiple groups, ensuring deterministic policy resolution
* Priority numbers help resolve conflicts when group membership overlaps

> [!NOTE]
>
> In scenarios where a user belongs to multiple groups (e.g., `developers` and `qa-testers`), the system uses the group override with the lowest priority number to determine their active policy.

### Project context and resource references

* The active policy system determines how resource references are handled during process execution
* At runtime, the system identifies the active build based on the resolved policy for each user
* Ensures correct resource definitions are used based on user-specific or global policies

### Metadata and versioning

* Each policy (global and overrides) includes comprehensive metadata:
  * Policy type and the branch ID or build ID it points to
  * User/group assignments and priority settings
  * Creation and modification timestamps

### Audit and monitoring

* All policy changes are logged with detailed audit information:
  * User performing the action
  * Timestamp of the change
  * Before and after values
  * Action type (create, update, or delete; enabling or disabling an override is logged as an update)
* Audit logs are accessible to authorized users for compliance and troubleshooting

### Storage and management

* Active policies and overrides are stored separately from build data
* Policy changes don't affect build integrity
* Efficient policy resolution at runtime with minimal performance impact
* Scalable architecture supports complex override scenarios

## Example use cases

### Scenario 1: Feature testing with user overrides

A development team collaborates on a project where all features are merged into the `main` branch.

To support this workflow, set a policy override for each developer, pointing to the feature branch they are currently working on. When a developer merges their branch, update their override to either deactivate it or assign it to their next active feature branch. This approach ensures developers can test their work in isolation without impacting the main environment or other users.

**1. Set Global Policy**

Set the global policy to use the latest build on the `main` branch. This ensures all users without overrides receive the most up-to-date production version by default.

**2. Set User-Specific Policy Override**

Set a policy override for each developer, assigning it to the feature branch they are currently working on:

* **Override Type**: Username
* **Applies To**: Individual developer (e.g., `alice@company.com`)
* **Policy**: Latest on Branch
* **Branch**: Developer's active feature branch (e.g., `feature/alice-new-payment-flow`)

When a developer merges their branch, update their override to either:

* **Disable** the override (clear **Enable this override**) if no new feature branch is active, or
* **Reassign** the override to the next feature branch they are working on

This approach ensures each developer can test their changes independently, and their override always reflects their current work.

**3. Test Independently**

Developers can now test the new feature while production users continue using the stable build.

> [!TIP]
>
> No impact on production users during feature development and testing.

### Scenario 2: Gradual rollout with priority management

Rolling out a new version to different user groups:

**1. QA Testing Override**

Create high-priority override for the QA team:

* **Override Type**: Group
* **Applies To**: `qa-testers`
* **Policy**: Build `v2.2.0-rc1`
* **Priority**: 0 (highest)

**2. Beta User Override**

Create an override for beta users:

* **Override Type**: Group
* **Applies To**: `beta-users`
* **Policy**: Build `v2.2.0-rc1`
* **Priority**: 1

**3. Production Rollout**

After successful testing, update the global policy to `v2.2.0` and remove overrides.

> [!TIP]
>
> Controlled rollout minimizes risk and ensures thorough testing.

> [!NOTE]
>
> Runtime groups are managed in **Runtime Access Settings** and are shared across projects. See [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization) for how groups are created and how they receive runtime roles on each project.

### Scenario 3: Emergency rollback

Quickly roll back from a problematic build by downgrading the global active policy:

**1. Identify Issue**

A critical issue is discovered in the current production build `v2.3.0`.

**2. Downgrade Global Policy**

Update the global active policy to point to the previous stable build (e.g., `v2.2.5`).

> [!TIP]
>
> All users will immediately use the stable build, ensuring a consistent and safe rollback.

**3. Restore Latest Version**

After resolving the issue, update the global policy to the new stable build (e.g., `v2.3.1` or a fixed `v2.3.0`).

> [!TIP]
>
> For emergency rollbacks, prefer downgrading the global active policy instead of using overrides. This approach is simpler, avoids confusion, and ensures all users are aligned on the same stable version.

## Conclusion

The Active Policy feature in FlowX.AI provides comprehensive control over project version management through both global policies and granular policy overrides. This dual-layer approach enables:

* **Flexible Testing**: Independent testing of different builds and branches by different user groups
* **Controlled Deployment**: Gradual rollouts with priority-based conflict resolution
* **Enhanced Stability**: Quick rollback capabilities and isolated testing environments
* **User-Centric Management**: Granular control at both user and group levels

By combining global policies with targeted overrides, Active Policy ensures that the right users access the right project versions at the right time, making it an essential tool for modern development and deployment workflows.

> [!TIP]
>
> Start with simple global policies and gradually introduce overrides as your testing and deployment needs become more complex.


# Failed process start (exceptions)
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/failed-process-start

View and debug exceptions that occur when process instances fail to start, including detailed error information and stack traces.

Exceptions are types of errors meant to help you debug a failure in the execution of a process.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/exceptions1.png)

Exceptions can be accessed from multiple places:

* **Failed process start** tab from **Active process** menu in FlowX.AI Designer.
* **Process Status** view, accessible from **Process instances** list in FlowX.AI Designer.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/exceptions2.png)

> [!NOTE]
>
> If you open a process instance and it does not contain exceptions, the **Exceptions** tab will not be displayed.

### Exceptions data

When you click **view** button, a detailed exception will be displayed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/exceptions_data.png)

* **Process Definition**: The process where the exception was thrown.
* **Source**: The source of the exception (see the possible type of [sources](#possible-sources) below).
* **Message**: A hint type of message to help you understand what's wrong with your process.
* **Type**: Exception type.
* **Cause Type**: Cause type (or the name of the node if it is the case).
* **Process Instance UUID**: Process instance unique identifier (UUID).
* **Token UUID**: The token unique identifier.
* **Timestamp**: The default format is - `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.
* **Details**: Stack trace (a **stack trace** is a list of the method calls that the process was in the middle of when an **Exception** was thrown).

#### Possible sources

> [card] [Actions](../../../building-blocks/actions/actions)

> [card] [Node](../../../building-blocks/node/node)

> [card] [Subprocess](../../../building-blocks/process/subprocess)

> [card] [Process Definition](../../../building-blocks/process/process-definition)

### Exceptions type

Based on the exception type, there are multiple causes that could make a process fail. Here are some examples:

| Type | Cause |
| :- | - |
| Business Rule Evaluation | When executing action rules fails for any reason. |
| Condition Evaluation | When executing action conditions. |
| Engine | When the connection with the database failswhen the connection with [Redis](../../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis) fails |
| Definition | Misconfigurations: process def name, subprocess parent process id value, start node condition missing. |
| Node | When an outgoing node can’t be found (missing sequence etc). |
| Gateway Evaluation | When the token can’t pass a gateway for any reason, possible causes:<ul><li>Missing sequence/node</li><li>Failed node rule</li></ul> |
| Subprocess | Exceptions will be saved for them just like for any other process, parent process ID will also be saved (we can use this to link them when displaying exceptions). |


# Migrate process instances
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/migrate-process-instances

Move running process instances from one build to another to apply a corrected process definition without restarting them, individually or in bulk.

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

Process instance migration moves running instances from the build they started on to a
different build of the same process, so a fix or change made in a newer build applies to
instances that are already in flight. It is an operational corrective action, alongside
[updating process variables](./update-process-variables) - you use it to fix forward
without asking end users to restart.

You can migrate:

* **A single instance** - from its contextual menu on the Process instances page.
* **Instances in bulk** - a chosen set of instances on a source build, from the Corrective Actions page.

## Eligibility

Only instances that are still running can be migrated:

| Condition | Rule |
| - | - |
| **Instance status** | Only instances in **STARTED** or **ON HOLD** status are eligible. Finished, terminated, expired, and failed instances are not migrated. |
| **Build selection** | The **active** build cannot be the **source**, since its instances are the ones the active policy is serving. It can be the **target**. The only build excluded from the target list is the one already picked as the source. |

\| **UI Flow sessions** | UI Flow sessions are **not** migrated (see Limitations). |

## Prerequisites

Migrating process instances is a workspace-level **Operations** action. The acting user needs
the **Operations** permission in the workspace. The built-in `operations_editor`
(`workspace_operations_editor`) role grants it, and `workspace_admin` includes it by default.

For the full permission breakdown, see the
[Roles and permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) and
[Workspaces access rights](/5.9/setup-guides/access-management/workspaces-access-rights).

### Corrective actions role

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Migration is governed by the **Process instance corrective actions** permission, granted by the
**Workspace corrective actions editor** role. This role replaces the Workspace operations editor
role, and users and groups that had the old role are moved to the new one automatically.
`workspace_admin` includes the permission, and organization admins have it through their workspace
admin access. See the
[Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).

## Migrate a single instance

**1. Open the process instance menu**

Go to **Runtime → Processes → Process Instances**, then open the contextual menu
(three dots) on the instance you want to migrate and select **Migrate**.

**2. Choose the target build**

Select the **target build** to migrate the instance to. Builds are listed newest first
(descending by build creation date).

**3. Map unmatched nodes**

On the Migration page, review how the instance's active node maps into the target build.
If the active node does not exist in the target build, the token is repositioned per the
[node mapping rules](#node-mapping-when-a-node-is-missing).

**4. Start the migration**

Confirm to run the migration. When it completes, the instance runs on the target build and
its previously active tokens are marked **Migrated** (see [After migration](#after-migration)).

## Migrate instances in bulk

Bulk migration moves every eligible instance on a source build to a target build in one action.

**1. Open Bulk Migration**

Go to **Runtime → Runtime Control → Corrective Actions**, open the menu (three dots, top
right) and select **Bulk Migration**.

**2. Configure the migration**

In the **Migrate Instances** modal, choose the **Source Build** and the **Target Build**.
Both lists are ordered newest first (descending by build creation date). Then, under
**Which instances do you want to move?**, pick a selection mode and fill in its fields; see
[Choosing which instances to move](#choosing-which-instances-to-move). Click **Continue**.

![The Migrate Instances modal with Source Build and Target Build selectors and the three selection modes, with All active instances selected](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/bulk-migration-all-active.png)

**3. Review the Migration page**

The Migration page shows the number of **running instances** eligible for migration
(instances in STARTED or ON HOLD status), the source and target builds (read-only), and the
node mapping section.

**4. Map unmatched nodes**

Resolve any active nodes that do not exist in the target build, per the
[node mapping rules](#node-mapping-when-a-node-is-missing).

**5. Start the migration**

Click **Start** to run the bulk migration.

> [!WARNING]
>
> Keep a single bulk run at or below roughly **10,000 instances**. Runs of that size perform
> acceptably. Substantially larger runs degrade and are not recommended.

### Choosing which instances to move

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Bulk migration no longer means "everything on the build". The modal offers three selection modes, and you pick one:

| Mode | Use it when |
| - | - |
| **Specific instance UUIDs** | You already know which instances are affected, so you paste their UUIDs. |
| **Instances matching filters** | You know the shape of the problem but not the UUIDs. |
| **All active instances** | You want every eligible instance moved. Instances that cannot be moved are skipped rather than failing the run. |

**Specific instance UUIDs** shows a **Process Instance UUID** field taking comma-separated UUIDs, up to **100** in one run. More than that is rejected rather than truncated.

![The Migrate Instances modal with Specific instance UUIDs selected and its Process Instance UUID field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/bulk-migration-specific-uuids.png)

**Instances matching filters** selects by where an instance currently sits, not by its overall state. The three fields cascade: pick a process first, and each later field offers only values relevant to the earlier ones.

| Filter | Required | What it matches |
| - | - | - |
| **Process Name** | Yes | Instances of that process definition. |
| **Current Node Name** | No | Instances whose active token sits on that node. |
| **Instance status** | No | The token's status on that node. Pick a node first, since a status on its own has nothing to apply to. |

![The Migrate Instances modal with Instances matching filters selected, showing the Process Name, Current Node Name, and Instance status fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/bulk-migration-matching-filters.png)

Before you start the run, the modal reports how many instances the selection matches, and calls out any UUIDs you pasted that can never match so you can correct them rather than wonder why the count is short.

> [!TIP]
>
> Reach for **Instances matching filters** when a fix targets a known failure point, such as every instance stuck on one Service Task. It is the difference between moving the instances that need the fix and moving the whole build.

## Node mapping (when a node is missing)

When an active token sits on a node that does not exist in the target build, the token is
repositioned to the previously visited node. Specific node types have additional effects:

| Active node not in target build | Result |
| - | - |
| **General rule** | The active migrated token remains on the previously visited node. |
| **Start Parallel Gateway** | Not supported. The parallel gateway must still exist in the target build, so this is not a case you should migrate into. See [Limitations](#limitations). |
| **Embedded subprocess** | Token moves to the previously visited node. All previously visited nodes in the embedded context are removed from token history. |
| **Call Activity** | Token moves to the previously visited node. All started subprocess instances from that node are cancelled. |
| **Node with a boundary event** | Token moves to the previously visited node. |

## After migration

On the Process instance page of a migrated instance:

* Tokens that were active on the source build are shown with the **Migrated** status.
* Tokens created after migration are shown with their current status.
* Nodes on the canvas are color-coded based on the newly created and active tokens.

## Audit trail

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Every bulk migration is recorded in the [audit log](../../../platform-deep-dive/core-extensions/audit), attributed to the user who started it:

* One entry for the run itself, with the **Bulk Migrate Process Instances** subject and the **Migrate** event. The entry records success, or an error with the number of instances that failed to migrate.
* One **Migrate** entry per migrated instance, with the **Process Instance** subject and the instance identifier. A root instance and its subprocesses are audited individually, all with the same outcome: the tree migrates, and rolls back on failure, as a single unit.

To view these entries filtered to corrective actions, go to **Runtime → Runtime Control → Corrective Actions**, open the menu (three dots, top right) and select **Audit Logs**.

## Limitations

> [!WARNING]
>
> * **UI Flow sessions are not migrated.** Any UI Flow session tied to the instance does not carry
>   over to the target build.
> * **No undo of a successful migration.** Rollback is automatic only if a migration **fails**;
>   there is no snapshot restore for a migration that succeeded. To correct a bad migration, fix
>   the target build and migrate the instance again (fix-forward).
> * **The parallel gateway itself must still exist in the target build.** You can change nodes
>   *inside* the parallel branches and migrate normally. You cannot migrate onto a build where the
>   parallel gateway nodes themselves (the split and the join) no longer exist.

## Related resources

> [card] [Process instance](./process-instance)
>
> Monitor instance status, tokens, and canvas color coding.

> [card] [Update process variables](./update-process-variables)
>
> The other in-flight corrective action for running instances.

> [card] [Roles and permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> The Operations permission that governs migration.


# Move tokens
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/move-token

Reposition the active tokens of running process instances to a different node of the same process, in bulk, without restarting the instances.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

Move token is a corrective action that takes the active token of a running process instance off the node it is stuck on and places it on another node of the same process. Use it when instances are blocked on a node and you want them to resume somewhere else, for example to skip a step that cannot complete or to send them back to repeat one.

It runs in bulk from the Corrective Actions page, on one or many instances at once, and the instances keep running on the build they started on.

| You want to | Use |
| - | - |
| Resume instances from a different node of the same process | **Move token** (this page) |
| Apply a corrected process definition from another build | [Migrate process instances](./migrate-process-instances) |
| Fix the data an instance is carrying | [Update process variables](./update-process-variables) |

***

## Eligibility

| Condition | Rule |
| - | - |
| **Instance status** | Only running root instances are eligible: **STARTED** or **ON HOLD** status. Finished, terminated, expired, and failed instances can't be selected. |
| **Build** | The instance must have started on a committed build. Unlike migration, there is no restriction on the active build: instances running on it can have their tokens moved. |
| **Token status** | Only tokens that are **active** or **on hold** are moved. |
| **Destination** | Any node of the same process definition, before or after the current node. Inside a parallel section, see [Parallel gateways](#parallel-gateways). |

***

## Prerequisites

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

You need the **Workspace corrective actions editor** role in the workspace, plus permission to view and edit process instances in the project. Workspace admins have corrective actions access by default, and organization admins get it through their workspace admin access.

The Corrective Actions page is visible to anyone with read access to corrective actions. The **Move Tokens** and **Bulk Migration** menu items appear disabled unless you can also create them.

For the full permission breakdown, see the [Roles and permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix).

***

## Move tokens

**1. Open Move Tokens**

Go to **Runtime → Runtime Control → Corrective Actions**, open the menu (three dots, top right) and select **Move Tokens**.

![The Corrective Actions page with the page menu open, showing Move Tokens, Bulk Migration, and Audit Logs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/move-token-menu.png)

**2. Choose the instances**

In the **Move tokens** modal, under **Which instances do you want to move tokens on?**, pick a selection mode and fill in its fields; see [Choosing the instances](#choosing-the-instances). Click **Continue**.

![The Move tokens modal with Specific instance UUIDs selected and two process instance UUIDs entered](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/move-token-select-instances.png)

**3. Set the token destinations**

The **Move Token Configuration** page lists each process that has running instances in your selection. For each one, click **Move Token** to add a row, then choose:

* **Blocked on Node**: the node the tokens currently sit on. Only nodes where the selected instances have tokens are offered.
* **Resume at Node**: the node the tokens should move to.

Add one row per blocked node. A node used as **Blocked on Node** in one row can't be picked again in another. Every row must be complete before you can continue. Click **Continue**.

![The Move Token Configuration page for the customerOnboarding process, with one row moving tokens blocked on personalInfo to employmentInfo](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/move-token-configuration.png)

**4. Review and start**

The **Move Token Summary** lists the processes and the number of tokens that will move in each. Click **Start Move Token** to run it, or **Back to Setup** to change the configuration.

![The Move Token Summary modal showing one process, customerOnboarding, with 2 tokens to move, and the Start Move Token button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/move-token-summary.png)

> [!WARNING]
>
> A move token run can't be undone or cancelled once it starts.

**5. Track the result**

The run continues in the background, so you can close the progress window and keep working. Track it on the Corrective Actions page; see [Track the run](#track-the-run).

### Choosing the instances

The modal offers two selection modes:

| Mode | Use it when |
| - | - |
| **Specific instance UUIDs** | You already know which instances are affected, so you paste their UUIDs. |
| **Instances matching filters** | You know the shape of the problem but not the UUIDs. |

**Specific instance UUIDs** takes comma-separated UUIDs in the **Process Instance UUID** field, up to **100** in one run. The instances can be running on different builds. If any UUID is invalid or not eligible, the modal flags it so you can correct the list.

**Instances matching filters** selects instances on one build per run:

| Filter | Required | What it matches |
| - | - | - |
| **Instances running on build** | Yes | Instances running on that build. The active build is labelled **(Active build)**. |
| **Process Name** | No | Instances of that process. Leave it empty to include all processes. |
| **Current Node Name** | No | Instances whose active token sits on that node. |
| **Instance status** | No | The token's status on that node. |

***

## What happens to a moved token

When a token moves, the instance is paused for the duration of the move, then:

* The original token is closed with the **Moved** status and stays in the instance history.
* A new token is created on the destination node, carrying the earlier history. The destination node runs from the start, so its actions execute again.
* Only the tokens you picked are affected. Other tokens of the same instance keep running.
* Process data is not changed. If the destination node expects data that earlier steps never produced, [update the process variables](./update-process-variables) as well.
* Moving a token **backward** removes the history from the destination node onward, so the instance replays those steps.
* Tokens that descend from the moved token are aborted, and subprocesses started by actions on the node being left are cancelled.
* Timers on the node being left are stopped. Timers on the destination node are created again, with a fresh start time.
* Moving a token onto the end node of an embedded subprocess returns the token to the parent process.

### Parallel gateways

Inside a parallel section, a token can move only to a node on its own branch. Moving it to a node on another branch is rejected. A token outside a parallel section can move past a complete parallel section, split and join included.

***

## Track the run

Each run appears on the Corrective Actions page with the **Move Token** type and its status: **Draft**, **Initialized**, **Pending**, **In Progress**, **Completed**, or **Failed**.

![The Corrective Actions list with one Move Token run in Completed status](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/move-token-list.png)

Click a run to open **Move Token Status**. It shows the corrective action ID and the per-instance outcome, with **Success** and **Failed** filters and an **Error** column for instances that failed.

![The Move Token Status page showing a Completed run with 2 root instances, both successful](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/move-token-status.png)

Instances are processed independently. If the move fails for one instance, that instance is restored to its state before the move, and the others are unaffected. The run reaches **Completed** even when some instances failed, so check the **Failed** filter.

***

## Audit trail

Every move token run is recorded in the [audit log](../../../platform-deep-dive/core-extensions/audit), attributed to the user who started it:

* One entry for the run itself, identified by the corrective action ID. The entry records success, or an error with the number of instances whose tokens failed to move.
* One entry per instance, with the **Process Instance** subject and the instance identifier.

To view these entries filtered to corrective actions, go to **Runtime → Runtime Control → Corrective Actions**, open the menu (three dots, top right) and select **Audit Logs**.

***

## Limitations

> [!WARNING]
>
> * **No undo or cancel.** A run can't be stopped once started, and a successful move can't be rolled back. To correct a move, run another one.
> * **No completion notification.** The progress window mentions a notification, but move token runs don't send one. Check the status on the Corrective Actions page.
> * **Tokens tab after a move.** On the Process instance page of an instance whose tokens were moved, the **Tokens** tab doesn't display. Use the canvas and the **Move Token Status** page to confirm where the tokens are.
> * **UUID limit.** **Specific instance UUIDs** accepts up to 100 instances per run.

***

## Related resources

> [card] [Migrate process instances](./migrate-process-instances)
>
> Move running instances to another build of the same process.

> [card] [Update process variables](./update-process-variables)
>
> Correct the data a running instance is carrying.

> [card] [Process instance](./process-instance)
>
> Monitor instance status, tokens, and canvas color coding.

> [card] [Roles and permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> Workspace roles and the permissions they grant.


# Process instance
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/process-instance

A process instance is a specific execution of a business process that is defined on the FlowX.AI platform. Once a process definition is added to the platform, it can be executed, monitored, and optimized by creating an instance of the definition.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_instance.png)

## Overview

Once the desired processes are defined in the platform, they are ready to be used. Each time a process needs to be used, for example each time a customer wants to request a new credit card, a new instance of the specified process definition is started in the platform. Think of the process definition as a blueprint for a house, and of the process instance as each house of that type being built.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_instance_overview.png)

The **FlowX.AI Engine** is responsible for executing the steps in the process definition and handling all the business logic. The token represents the current position in the process and moves from one node to the next based on the sequences and rules defined in the exclusive gateways. In the case of parallel gateways, child tokens are created and eventually merged back into the parent token.

Kafka events are used for communication between FlowX.AI components such as the engine and integrations/plugins. Each event type is associated with a Kafka topic to track and orchestrate the messages sent on Kafka. The engine updates the UI by sending messages through sockets.

> [card] [More about Kafka](../../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts)

## Checking the Process Status

To check the status of a process or troubleshoot a failed process, follow these steps:

1. Open **FlowX.AI Designer**.
2. Go to **Projects → Your Project → Runtime → Processes → Process Instances**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_status.png)

### Filtering the list

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Status** column carries a multi-select filter, and **Start date** a date filter, so you can pull up, say, every **FAILED** instance from the last day instead of scanning the unfiltered list. Filters combine with the search fields above the table.

### Understanding the Process Status data

Understanding the various elements within process status data is crucial. Here's what each component entails:

* The **Status** field indicates the state of the process instance, offering distinct values:

| Status | Indicates the state of the process instance. Offers distinct values: |
| - | - |
| **CREATED** | Visible if there's an error during process creation. Displays as `STARTED` if there were no errors during creation. |
| **STARTED** | Indicates the current running status of the process. |
| **DISMISSED** | Available for processes with subprocesses, seen when a user halts a subprocess. |
| **EXPIRED** | This status appears when the defined "expiryTime" expression in the process definition elapses since the process was initiated (`STARTED`). |
| **FINISHED** | Signifies successful completion of the process execution. |
| **TERMINATED** | A termination request was sent to the instance through a Kafka process operation message. See [Task operations via Kafka](../../../platform-deep-dive/core-extensions/task-management/task-management-overview#available-operation-types). |
| **ON HOLD** | Marks a state where the process is no longer editable. |
| **FAILED** | Occurs if a CronJob triggers at a specific hour, and the instance isn't finished by then. |

## Process instance details

Click on a process instance to view the details.

* **Active process instance**: The UUID of the process instance, with a copy action available.
* **Variables**: Displayed as a tree view or a JSON view. You can modify the variables using the JSON editor (available for STARTED or ON HOLD process instances). Check [Update Process Variables](./update-process-variables) for more information.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/variables.png)

* **Tokens**: A token represents the state within the process instance and describe the current position in the process flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token.png)

> [!NOTE]
>
> For more information, see the [token documentation](../../../building-blocks/token).

* **Subprocesses**: Displayed only if the current process instance generated a [subprocess](../../../building-blocks/process/subprocess) instance.
* **Exceptions**: Errors that let you know where the process is blocked, with a direct link to the node where the process is breaking for easy editing.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/process_exceptions.png)

> [!NOTE]
>
> For more information on exceptions, check the following section:
>
> [Exceptions](../active-process/failed-process-start)

* **Audit Log**: The audit log displays events registered for process instances, tokens, tasks, and exceptions in reverse chronological order by timestamp.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/audit_log.png)

> [card] [Audit](../../../platform-deep-dive/core-extensions/audit)

* **Workflows**: If process instance has a Start Workflow node, the workflow will be displayed here.

* **Trigger**: Displayed for process instances started by an event-based trigger (such as an email trigger). Shows the following details:

| Column | Description |
| - | - |
| **Trigger Type** | The type of trigger that started the instance (for example, Email Trigger, Microsoft Outlook) |
| **Trigger Name** | The name of the trigger data source |
| **Process Name** | The process definition that was started |
| **Timestamp** | Date and time the trigger event occurred |

* **Notifications**: Displays email notifications sent from this process instance. The table includes the following columns:

| Column | Description |
| - | - |
| **Notification Type** | The type of notification sent |
| **Status** | Delivery status with color-coded indicators: green for `DELIVERED`, red for `FAILED` or `ERROR` |
| **Data Source Name** | The email connection (data source) used to send the notification |
| **Template Name** | The notification template used |
| **Process Name** | The process definition associated with the notification |
| **Sent At** | Date and time the notification was sent |

* **Documents**: Single source of truth for every document handled during the process instance, regardless of how it entered the process. Each row exposes tracking metadata and an inline preview, and any document can be downloaded directly from the tab. Sources covered:

  * End-user uploads via the file-upload component
  * Attachments forwarded from an [email trigger](../../../platform-deep-dive/integrations/email-trigger)
  * Files generated from HTML templates
  * Files produced by OCR processing
  * Files produced by AI workflow nodes (for example, [Document Generation](../../../../ai-platform/agent-builder/node-types#ai-document-operations))

### Color coding

In the **Process Status** view, some nodes are highlighted with different colors to easily identify any failures:

* **Green**: Nodes highlighted with green mark the nodes passed by the [token](../../../building-blocks/token).
* **Red**: The node highlighted with red marks the node where the token is stuck (process failure).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/color_coding.png)

## Starting a new process instance

To start a new process instance, a request must be made to the [FlowX.AI Engine](../../../platform-deep-dive/core-components/flowx-engine). This is handled by the web/mobile application. The current user must have the appropriate role/permission to start a new process instance.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/process/process_instance_diagram.png)

To be able to start a new process instance, the current user needs to have the appropriate role/permissions:

> [card] [Configuring access roles for processes](../../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes)

When starting a new process instance, we can also set it to [inherit some values from a previous process instance](../../../platform-deep-dive/core-components/flowx-engine#orchestration).

## Troubleshooting possible errors

If everything is configured correctly, the new process instance should be visible in the UI and added to the database. However, if you encounter issues, here are some common error messages and their possible solutions:
Possible errors include:

| Error Message | Description |
| - | - |
| *"Process definition not found."* | The process definition with the requested name was not set as published. |
| *"Start node for process definition not found."* | The start node was not properly configured. |
| *"Multiple start nodes found, but start condition not specified."* | Multiple start nodes were defined, but the start condition to choose the start node was not set. |
| *"Some mandatory params are missing."* | Some parameters set as mandatory were not included in the start request. |
| `HTTP code 403 - Forbidden` | The current user does not have the process access role for starting that process. |
| `HTTP code 401 - Unauthorized` | The current user is not logged in. |


# Update process variables
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/active-process/update-process-variables

Modify process variables on active process instances to resolve production issues without restarts or backend 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.

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

![Process Variables View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/modify_variables.png)

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

![Process Variables View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/json_editor1.png)

Edit process variables using the JSON editor with JSON validation

### Access points

Access the editor from two locations:

> [tab] From Process Instances page
>
> 1. Navigate to **Runtime** → **Processes** → **Process Instances**
> 2. Click the contextual menu (three dots) on any process instance row
> 3. Select **Modify Variables**
> 4. The system navigates to the Process Instance page and opens the Variables tab in edit mode

> [tab] From View process instance page
>
> 1. Open a specific process instance
> 2. Select **Modify Variables** from the contextual menu in secondary navigation
> 3. The Variables tab opens in edit mode

![Process Variables View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/modify_variables.png)

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](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/tree_view.png)

Tree view of process variables

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

![JSON View](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/json_view.png)

JSON view of process variables

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

### Compare view

The compare view uses a Monaco diff editor to show side-by-side differences between the original and modified process variable values. This helps you review changes before saving.

| Feature | Description |
| - | - |
| **Side-by-side diff** | Original values on the left, modified values on the right |
| **Change highlighting** | Added, removed, and modified lines are color-coded |
| **Toggle views** | Switch between Edit and Compare modes while editing |

To use the compare view:

1. Open the variables editor in **Edit mode**
2. Make your changes in the JSON editor
3. Toggle to **Compare** view to see a diff of your modifications against the original values
4. Switch back to **Edit** view to continue making changes, or click **Save** to apply

> [!TIP]
>
> Use the compare view before saving to verify that only the intended variables were modified, especially when editing large JSON structures.

### 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

**1. Check permissions**

Ensure you have the `process_variables_edit` permission at the workspace level.

> [!NOTE]
>
> The Edit option is only visible to users with this permission.

**2. Navigate to process instance**

Access from either:

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

**3. Open Variables tab**

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

***

## Editing process variables

**1. Select active instance**

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

> [!WARNING]
>
> Only process instances in Started or On Hold status can have their variables modified.

**2. Switch to JSON View**

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

**3. Enable edit mode**

Click the **Modify Variables** button to make the JSON editor editable.

> [!NOTE]
>
> This button is only visible if you have the necessary permissions.

![JSON editor in edit mode](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/edit_mode.png)

The editor with Edit enabled, showing Save and Cancel buttons

**4. Modify variables**

Edit process variables in the JSON editor:

**Example - Editing existing values:**

```json theme={"dark"}
{
  "application": {
    "customer": {
      "id": "12345",
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "status": "approved"
  }
}
```

**Example - Adding new attributes:**

```json theme={"dark"}
{
  "application": {
    "customer": {
      "id": "12345",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phoneNumber": "+1234567890"
    },
    "status": "approved",
    "creditScore": 750
  }
}
```

**Example - Deleting attributes:**

Remove unwanted attributes by deleting their lines from the JSON.

**5. Validate JSON**

Ensure your JSON format is valid before saving.

> [!WARNING]
>
> You cannot save if the JSON format is invalid. The JSON editor will highlight syntax errors automatically.

![JSON validation errors](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/edit_errors.png)

The editor showing syntax errors highlighted with error indicators

**Common validation errors:**

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

**6. 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

**7. Review audit log**

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

***

## Permissions and security

> [!NOTE]
>
> **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](/5.9/setup-guides/access-management/workspaces-access-rights) and the [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide).

***

## Data synchronization

### Updated automatically

When you modify process variables, the following are updated:

> [card] Process instance parameters
>
> Variables are updated immediately in the database

> [card] Task Manager
>
> Variables sync using existing mechanisms; task keywords and data remain consistent

> [card] Elasticsearch
>
> Variables configured for data search are updated automatically

> [card] Snapshot table
>
> Previous values are saved in a snapshot table before changes are applied

### Not updated

The following are preserved to maintain data integrity:

> [card] Process snapshots
>
> Snapshots used for back navigation (Reset process data) remain unchanged

> [card] Debug records
>
> Process instance debug records preserve execution history as it occurred

> [card] Existing audit logs
>
> Previously recorded audit logs (manual actions, integrations) are not modified

> [card] Subprocess variables
>
> Child subprocess variables are not updated; parent changes don't cascade to children

### Synchronization details

#### Task manager sync

**How it works**

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

**What gets synced**

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

**Timing**

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

#### Elasticsearch sync

**How it works**

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

**What gets synced**

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

**Timing**

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

***

## Audit logging

Every process variable modification creates a detailed audit log entry. Audit logs are displayed in the **Audit Log** tab within the process instance (open the instance from **Runtime** → **Processes** → **Process Instances**).

**1. Open process instance**

Navigate to the process instance that was modified.

**2. Go to Audit Log tab**

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

**3. Find modification entry**

Look for entries with Event = "Update and Subject = "Process variables".

![Audit log edit entry](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pv_audit.png)

Audit Log tab showing the process variables edit event with Event = Update and Subject = Process variables

**4. Review details**

Click on the audit log entry to see:

* Complete Body JSON
* URL

![Audit log edit entry](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pv_audit_body.png)

***

## Important considerations

### Subprocess impact

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

**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

**Impact**

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

**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

### Back navigation

> [!WARNING]
>
> **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.

**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

**Impact**

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

**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

> [!WARNING]
>
> **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.

**Why this happens**

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

**Impact**

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

**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

> [card] Correct user input errors
>
> Fix incorrect data submitted in forms

> [card] Unblock stuck instances
>
> Resolve missing data preventing continuation

> [card] Fix integration data issues
>
> Correct incorrect responses from external systems

> [card] Add missing attributes
>
> Add required data not collected initially

> [card] Remove invalid data
>
> Clean up test or incorrect data

> [card] Update search keywords
>
> Correct Task Manager search data

> [card] Fix Elasticsearch data
>
> Ensure accurate search results

### When not to use

> [card] Regular operational updates
>
> Design proper process flows instead

> [card] Subprocess coordination
>
> Parent-child sync not supported

> [card] Complex back navigation flows
>
> Snapshots won't reflect changes

> [card] While waiting for integrations
>
> Responses based on original values

> [card] Routine data corrections
>
> Indicates process design issues

> [card] Automated scripts
>
> Use process design and actions instead

### Validation before saving

> [card] Verify JSON syntax
>
> Ensure valid JSON format to prevent data corruption and save failures

> [card] Review impact
>
> Understand which variables you're changing and their impact on process flow

> [card] Check dependencies
>
> Review process flow, subprocesses, and integrations before modifying critical variables

> [card] Document changes
>
> Audit logs record changes automatically, but document why changes were made

***

## Common use cases

### 1. Correct user input errors

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

**Solution:**

1. Navigate to the process instance
2. Access Variables tab in edit mode
3. Locate the incorrect values in JSON
4. Correct the data:
   ```json theme={"dark"}
   {
     "application": {
       "income": 75000,  // Changed from 50000
       "address": "123 Main St, New York, NY 10001"  // Corrected
     }
   }
   ```
5. Save changes
6. 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:**

1. Identify the variable causing the blockage
2. Open process variables in edit mode
3. Update the variable to provide expected data or bypass condition:
   ```json theme={"dark"}
   {
     "integration": {
       "responseReceived": true,  // Manually set to true
       "creditCheckStatus": "completed"  // Provide expected value
     }
   }
   ```
4. Save changes
5. 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:**

1. Review the integration response variables
2. Edit variables to correct the data:
   ```json theme={"dark"}
   {
     "creditCheck": {
       "score": 720,  // Corrected from incorrect 520
       "status": "approved",  // Fixed status
       "provider": "ExternalCreditBureau"
     }
   }
   ```
3. Save changes
4. 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:**

1. Access process variables
2. Add new required attributes:
   ```json theme={"dark"}
   {
     "application": {
       "existingField": "value",
       "newlyRequiredField": "new value",  // Added
       "additionalData": {  // Added entire object
         "field1": "value1",
         "field2": "value2"
       }
     }
   }
   ```
3. Save changes
4. 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:**

1. Open process variables
2. Remove problematic data:
   ```json theme={"dark"}
   {
     "application": {
       "validData": "correct value"
       // Removed "testData": {...}
       // Removed "invalidObject": {...}
     }
   }
   ```
3. Save changes
4. 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:**

1. Modify variables that are configured as Task Manager keywords:
   ```json theme={"dark"}
   {
     "customer": {
       "name": "Jane Smith",  // Corrected
       "accountNumber": "ACC-98765",  // Updated
       "status": "active"
     }
   }
   ```
2. Save changes
3. System automatically syncs to Task Manager
4. 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:**

1. Identify variables configured for Elasticsearch data search
2. Correct the values:
   ```json theme={"dark"}
   {
     "searchableData": {
       "category": "loans",  // Corrected from "loans_test"
       "priority": "high",  // Fixed
       "customerSegment": "premium"  // Updated
     }
   }
   ```
3. Save changes
4. Elasticsearch automatically updates
5. 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:**

1. Access affected process instances
2. Update variables to reflect new business rules:
   ```json theme={"dark"}
   {
     "pricing": {
       "interestRate": 3.5,  // Updated per regulation
       "fees": {
         "processing": 50,  // Adjusted
         "regulatory": 25   // New fee added
       }
     }
   }
   ```
3. Save changes for all affected instances
4. Processes continue with compliant data

***

## Troubleshooting

> [accordion] 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:**
>
> 1. Verify user has `process_variables_edit` permission:
>    * Check workspace permissions
>    * Confirm user role includes this permission
>    * Contact workspace administrator if needed
> 2. 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
> 3. Ensure you're in Variables tab:
>    * Switch to Variables tab if in another tab
>    * Refresh the page if needed

> [accordion] 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:**
>
> ```json theme={"dark"}
> {
>   "field1": "value1"  // ❌ Missing comma here
>   "field2": "value2"
> }
> ```
>
> **Correct:**
>
> ```json theme={"dark"}
> {
>   "field1": "value1",  // ✅ Comma added
>   "field2": "value2"
> }
> ```
>
> **Trailing comma:**
>
> ```json theme={"dark"}
> {
>   "field1": "value1",
>   "field2": "value2",  // ❌ Trailing comma
> }
> ```
>
> **Unclosed brackets:**
>
> ```json theme={"dark"}
> {
>   "object": {
>     "field": "value"
>   // ❌ Missing closing }
> }
> ```
>
> **Solutions:**
>
> 1. Use JSON editor error highlights to locate issues
> 2. Copy JSON to external validator (jsonlint.com)
> 3. Check for common issues: commas, brackets, quotes
> 4. Validate structure matches JSON specification
> 5. Remove trailing commas
> 6. Ensure all brackets and braces are closed

> [accordion] 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:**
>
> 1. Wait and refresh:
>    * Wait 10-30 seconds for sync
>    * Refresh Task Manager view
>    * Clear browser cache if needed
> 2. Verify configuration:
>    * Check if variables are configured as task keywords
>    * Review Task Manager configuration
>    * Confirm variable mapping is correct
> 3. Check system health:
>    * Verify Task Manager service is running
>    * Review sync logs for errors
>    * Check Kafka messages if available
> 4. Verify save completed:
>    * Check audit log for successful save
>    * Confirm no error messages appeared
>    * Review process instance variables show new values

> [accordion] 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:**
>
> 1. Wait for index refresh:
>    * Elasticsearch typically refreshes within seconds
>    * Wait up to 1 minute for propagation
>    * Try search again after waiting
> 2. Verify configuration:
>    * Check if variables are configured for Elasticsearch indexing
>    * Review process definition for data search settings
>    * Confirm variable paths match index mapping
> 3. Check Elasticsearch health:
>    * Verify Elasticsearch service is running
>    * Check index status
>    * Review indexing logs for errors
> 4. Manual verification:
>    * Query Elasticsearch directly if possible
>    * Check index document for process instance
>    * Verify field values match expected data

> [accordion] 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:**
>
> 1. **Document this behavior:**
>    * Inform operations team about snapshot behavior
>    * Add notes to operational procedures
>    * Train users on implications
> 2. **Prevent back navigation:**
>    * Disable back navigation for nodes after modification
>    * Configure "Allow back to this action" appropriately
>    * Consider process design implications
> 3. **Alternative approaches:**
>    * Modify variables only when back navigation unlikely
>    * Re-apply modifications after back navigation if needed
>    * Design processes to minimize back navigation needs
> 4. **User warnings:**
>    * Display warnings before allowing back navigation
>    * Inform users modifications may be lost
>    * Provide clear guidance on expected behavior

> [accordion] 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:**
>
> 1. **Understand before modifying:**
>    * Check if process has active subprocesses
>    * Review parent-child data dependencies
>    * Assess impact of data divergence
> 2. **Manual coordination:**
>    * Modify subprocess variables separately if needed
>    * Document intentional data divergence
>    * Test subprocess behavior with original values
> 3. **Process design considerations:**
>    * Design processes to minimize parent-child data coupling
>    * Pass critical data as subprocess parameters
>    * Use events for dynamic data synchronization

> [accordion] 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:**
>
> 1. **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
> 2. **Re-execute if needed:**
>    * Consider re-executing the integration node
>    * Manually trigger integration with new values if possible
>    * Design retry mechanisms in process flow
> 3. **Accept response:**
>    * Use integration response as-is
>    * Modify only non-integration-related variables
>    * Document why integration response doesn't match

***

## Related resources

> [card] [Process Instance Overview](./process-instance)
>
> Learn about process instances and execution

> [card] [Process Status](./process-instance#checking-the-process-status)
>
> Monitor process execution and troubleshoot issues

> [card] [Audit Logs](../../../platform-deep-dive/core-extensions/audit)
>
> Understand audit logging and compliance tracking

> [card] [Task Management](../../../platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> Learn about Task Manager integration


# Builds
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/builds

The Build feature allows for the creation of deployable packages of a project, encapsulating all its resources into a single unit.

A build is a snapshot of a specific project version, packaged and prepared for deployment to a runtime environment. The concept of builds plays a crucial role in ensuring that the correct version of a project, with all its configurations and dependencies, runs consistently across different environments (for example, Dev, UAT, Production).

> [!NOTE]
>
> You can create multiple versions of a project before creating a build. You can create a build for any committed project version. Once created, a build cannot be edited—you'll need to create a new project version and generate a new build to incorporate changes.

> [!NOTE]
>
> The builds on this page are the ones you create with **Create Build** from a committed version. The **Latest on Branch** [active policy](./active-policy) doesn't need one: it runs the latest version on the branch, including changes you haven't committed yet.

#### Key concepts

1. **Project Version vs. Build**
   * **Project Version** is the editable snapshot of a project's state at a specific point in time. It contains all the resources (like processes, integrations, templates, etc.) and configurations grouped within the project.
   * A **Build** is the deployable package of a project version. It is the compiled and immutable state that contains all the project resources transformed into executable components for the runtime environment.

2. **Single Version Rule**
   * A build can only represent a single version of a project. If you have multiple versions of a project, each one can have a unique build. This ensures that you can clearly manage which version of the project is running in a specific environment without conflicts.

3. **Consistency and Deployment**
   * Builds ensure that when you deploy a project to a different environment (like moving from Dev to UAT), the exact configuration, processes, templates, integrations, and all associated resources remain consistent.
   * Builds are immutable—once created, a build cannot be altered. Any updates require creating a new version of the project and generating a new build.

### Creating a build

To create a build from a committed project version:

**1. Navigate to Version Details**

Access the version details panel for the committed version you want to build. You can only create builds from committed versions, not from draft (WIP) versions.

**2. Open Create Build Dialog**

Click the **Create Build...** button in the version details panel. This opens the build creation modal.

![Create Build](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build.png)

Create Build

**3. Configure Build Settings**

In the **Create build** modal, configure the following settings:

* **Name**: The project name, shown read-only. It identifies the build in the builds list.
* **Build Tag Version**: Set the semantic version for this build:
  * **Major**: Major version number (for example, `1`)
  * **Minor**: Minor version number (for example, `0`)
  * **Patch**: Patch version number (for example, `0`)

The build tag follows semantic versioning format (for example, `1.0.0`). Major, Minor, and Patch are required whole numbers, and `0.0.0` isn't accepted. The tag must be unique within the project.

Each committed version can have only one build. Once a version has a build, **Create Build...** is disabled for it; to build again, commit a new version.

**4. Save the Build**

Click **Save** to create the build. The build is now available in the Builds section and can be deployed to runtime environments.

![Create Build Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build_modal.png)

### Build immutability

Once a build is created, it becomes immutable—you cannot modify its contents. This ensures:

* **Consistency**: The same build behaves identically across all environments
* **Traceability**: You can always identify exactly which project version is running
* **Stability**: Prevents accidental changes that could affect production systems

To incorporate changes into a build:

1. Make your changes in the project (creating a new draft version)
2. Commit the changes to create a new project version
3. Create a new build from the updated committed version

### Key features

1. **Checksum and Integrity**
   * Each build includes a checksum or identifier to verify its integrity. This ensures that the deployed build matches the expected configuration and no changes have been made post-build.

2. **Runtime Dependency**
   * The runtime environment relies on builds to determine the active project configuration. This means the runtime does not directly interact with the editable project versions but uses builds to maintain stability and reliability.

3. **Version Control**
   * Builds are version-controlled, and each build corresponds to a specific project version. This means you can trace exactly which project configuration is active in a particular environment at any time.

#### Benefits

* **Consistency Across Environments**: Builds ensure that the same version of an project runs in different environments, avoiding discrepancies between development and production.
* **Reduced Errors**: Immutable builds reduce the risk of runtime errors caused by unexpected changes.
* **Simplified Rollbacks**: If an issue is detected with a current build, previous builds can be deployed quickly, providing an efficient rollback strategy.
* **Simplified Deployment**: Builds allow for a straightforward deployment process, reducing the complexity of transferring configurations and resources between environments.

### Managing builds

The **Builds** section provides a centralized interface for viewing and managing all builds for your project. Access this section by navigating to your project, switching to **Runtime** mode, and selecting **Builds** from the navigation menu.

![Builds Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/builds_interface_59.png)

#### Builds list

The builds list displays all builds created for the project, showing:

* **Build name and version**: Displays the build name and tag version (for example, `Update_process_variables 1.0.0`)
* **Build actions**: Each build entry provides quick access to:
  * **Play/Run**: Test the build with options to:
    * **Test build** - run a process from the build
    * **Test endpoint** - call a REST data source endpoint
    * **Test workflow** - run an integration workflow
    * **Test operation** - run a FlowX Database or unmanaged MongoDB operation; see [Testing data sources from Runtime](/5.9/docs/platform-deep-dive/integrations/testing-data-sources)
    * **Test query** - run an Oracle or PostgreSQL query; see [Testing data sources from Runtime](/5.9/docs/platform-deep-dive/integrations/testing-data-sources)
    * **Test knowledge base** - test knowledge base operations; see [Testing a knowledge base](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/testing-knowledge-base)
  ![Build test actions menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/test_build_options.png)
  * **Export**: Export the build for transfer to other environments or workspaces
  * **More options**: Additional actions via the context menu:
  ![Build Actions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/builds_ctx_59.png)
  * View contents
  * Workflow test instances
  * Audit Logs
  * Apply Indexes (shown as **Applied Indexes** once the build has indexes applied)

#### Test SOAP operation

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Play/Run** menu also has **Test SOAP operation**, which runs a SOAP system operation. See [SOAP system](/5.9/docs/platform-deep-dive/integrations/soap-system#testing-an-operation).

#### Apply indexes

Indexes defined on [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) collections during config time are not automatically applied to the actual MongoDB database. To apply them, use the **Apply Indexes** action from the build's context menu (**More options → Apply Indexes**).

Indexes are applied from the build's snapshot, not from your current configuration. If you add or change indexes, create a new build to capture them and run **Apply Indexes** on that build. If the indexes are unchanged, you don't need to re-apply them for every new build — once applied, they stay on the database until you change them or use **Drop Indexes**.

> [!NOTE]
>
> * Only **one build** per project or library can have indexes applied at a time.
> * Applying indexes on a new build **replaces** any previously applied indexes that differ from those in the new build.
> * To remove all applied indexes from a build, open **More options → Applied Indexes** and click **Drop Indexes** in the modal. Dropping indexes may impact existing query performance.

#### Workflow test instances

When you run an integration workflow from a build using the **Test workflow** action, each run is recorded as a test instance. To review the history of these runs, use the **Workflow test instances** action from the build's context menu (**More options → Workflow test instances**).

The action opens a list of workflow test runs for that build, with the following details:

| Column | Description |
| - | - |
| **Name** | The workflow that was run |
| **Status** | The run outcome |
| **Date started** | When the run began |
| **Date finished** | When the run completed |

Select an instance to drill into that run's details. If no workflows have been run from the build yet, the list is empty.

#### Searching builds

Use the **Search by build tag** field to quickly find specific builds by their build tag. This is particularly useful when managing multiple builds for the same project.

### Exporting builds

You can export builds directly from the **Builds** section. This is useful when you want to transfer a specific build (rather than a version) between environments or workspaces.

**1. Navigate to Builds Section**

1. Open **FlowX.AI Designer** and go to the **Projects** section
2. Select your project and navigate to **Runtime** and then to the **Builds** section

**2. Select Build to Export**

1. Locate the build you want to export in the builds list
2. Click the **Export** icon (box with upward arrow) for the desired build

**3. Complete Export**

In the **Export Build** modal:

1. Choose the **Target platform version** — the platform version running in the target environment. The exported ZIP can only be imported into environments running the selected version; see [Cross-version export and import](../../flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import) for how content is adapted when targeting an older version.
2. Toggle **Include media file content** to bundle media files in the export package. Including media file content may increase export and import time.
3. Click **Export**. The export runs in the background.
4. When the export finishes, the build's export button changes to a download button (tooltip **Download build**). Click it to save the ZIP.

The exported build can be imported into other environments or workspaces.

![Export Build modal with target platform version and media content options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/export_build.png)

> [!NOTE]
>
> For detailed information about importing exported builds, see the [Export/Import documentation](../../flowx-designer/managing-a-project-flow/export-import-a-process-definition).

### Technical details

1. **Manifest and Metadata**
   * Each build contains a manifest that lists all the resources included, their version IDs, and their resource definitions.
   * Metadata helps identify which project version the build is derived from, providing traceability.

2. **Separation of Design and Runtime**
   * Builds serve as a bridge between the design (config) view and the runtime view. The config view is where changes are made and managed, while the runtime view uses builds to execute stable, tested versions of projects.

3. **Storage**
   * Builds are stored in a dedicated storage system to ensure they are separate from the editable project versions. This storage supports easy retrieval and deployment of builds.

#### Example use case

Imagine you have a project for customer onboarding with multiple processes, templates, and integrations. After completing development and final testing, you:

* Submit changes to create **Version 1.0** of the project.
* Create a build for **Version 1.0**.
* Deploy this build to the UAT environment for final stakeholder review.
* If any adjustments are needed, you go back to the project, make changes, and submit them as **Version 1.1**.
* Create a new build for **Version 1.1**, ensuring that the changes are encapsulated separately from the previous version.

Once everything is approved, you can publish **Version 1.1 Build** to the Production environment, ensuring all environments are aligned without manual reconfiguration.

#### Conclusion

The Build feature is essential for managing projects across multiple environments. It provides a clear and organized pathway from development to deployment, ensuring consistency, integrity, and stability throughout the project's lifecycle.


# Configuration parameters overrides
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/configuration-parameters-overrides

The Configuration parameters overrides feature allows you to set environment-specific values for certain parameters within a project.

This features enables flexibility and customization, making it possible to tailor a project’s behavior and integration settings to each workspace (for example, Sandbox, Staging, and Production). By defining overrides, you can manage variables like API endpoints, authentication tokens, workspace-specific URLs, and other settings without altering the core project configuration.

#### Key concepts

1. **Configuration Parameters**
   * Configuration parameters are placeholders used throughout a project to store key settings and values. These parameters can include anything from URLs, API keys, and credentials to integration-specific details.
   * Parameters can be defined at the project level and referenced throughout processes, business rules, integrations, and templates.

> [!NOTE]
>
> If an override is needed for a configuration parameter defined in a library, it must be applied within the project where the library is used as a dependency. This ensures a clear distinction between library defaults and project-specific configurations while maintaining flexibility.
>
> Overrides applied in a project take precedence over the values defined in the library.

2. **Workspace Overrides**
   * Overrides are specific values assigned to configuration parameters within a particular workspace. This ensures that a project behaves appropriately in each workspace without requiring changes to the project itself.
   * Each workspace (for example, Sandbox, Staging, and Production) can have a unique set of overrides that replace the default parameter values at runtime.

3. **Variable Precedence**

* Process variables override configuration parameters in `${...}` placeholders:
  * When the engine resolves a `${...}` placeholder (for example in a message payload or template), it checks process variables first. If a process variable and a configuration parameter share the same name, the process variable takes precedence.
  * If the process variable is null or undefined, the configuration parameter’s value is used as a fallback.
* In JavaScript and Python business rules there is no naming conflict: configuration parameters are not merged into process data, but exposed separately under `additionalData.applicationConfiguration`. See [Extracting additional data in business rules](../../building-blocks/actions/business-rule-action/extracting-additional-data).
* Best Practice: Avoid naming process variables the same as configuration parameters to prevent unexpected overrides or conflicts.

4. **Centralized Management**
   * Configuration parameters and their overrides are managed centrally within the project’s settings. This allows for quick adjustments and a clear overview of how each environment is configured.

#### Workflow for managing Configuration parameter overrides

1. **Defining Configuration Parameters**
   * In the project's Config view, open **Configuration Parameters**.
   * Define parameters that will be used across the project, such as:
     * **CRM URL**: Base URL for CRM integration.
     * **API Key**: Secure key for external service authentication.
     * **Environment URL**: Different base URLs per workspace (for example, Sandbox, Staging, and Production).

2. **Setting Up Workspace-Specific Overrides**
   * In the project's Runtime view, open **Configure Params Overrides**.
   * Assign override values to the defined parameters for the current workspace. For example, in the Staging workspace:
     * `CRM_URL` → `https://staging.crm.example.com`
   * Save the overrides. These values take precedence over the parameter's default value at runtime in that workspace.

3. **Applying Overrides at Runtime**
   * When a project is deployed to a specific environment, the system automatically applies the relevant overrides.
   * Overrides ensure that the configuration aligns with environment-specific requirements, like endpoint adjustments or security settings, without altering the core setup.

#### Key features

1. **Flexibility Across Environments**
   * Easily adjust configuration parameters without changing the core application, ensuring that the project adapts to the target environment.

2. **Centralized Parameter Management**
   * Configuration parameters and their environment-specific overrides are managed centrally within the project settings, providing a single source of truth.

3. **Dynamic Integration Adaptation**
   * Environment-specific overrides allow integrations to connect to different endpoints or use different credentials based on the environment, supporting a smoother development-to-production workflow.

4. **Improved Security**
   * Sensitive data, such as API keys or credentials, can be stored as environment-specific overrides, ensuring that development and testing environments do not share the same sensitive values as production.

5. **Avoid Variable Naming Conflicts**
   * Best Practice: Use distinct names for process variables and configuration parameters to avoid unintentional overrides. If process variables are undefined or null, they will default to the corresponding configuration parameter’s value.

6) **Editor Autocomplete**
   * Monaco code editors in the Designer (Script nodes, Business Rules, workflow expressions) provide autocomplete suggestions from your project’s configuration parameters, reducing errors and speeding up development.

#### Benefits

* **Simplified Deployment**: Overrides eliminate the need for manual configuration changes during deployment, streamlining the process and reducing the risk of errors.
* **Environment Consistency**: Each environment can have its own tailored settings, ensuring consistent behavior and performance across all stages.
* **Secure Configuration**: Overrides keep sensitive parameters isolated to the appropriate environments, enhancing security and minimizing the risk of exposure.
* **Ease of Maintenance**: Centralized management of parameters and overrides simplifies adjustments when changes are needed, minimizing maintenance overhead.

#### Managing Configuration parameters overrides

1. **Creating a Parameter**
   * In the project's Config view, open **Configuration Parameters**.
   * Define a new parameter by specifying its name, type, and default value.
   * This parameter will be used as a placeholder throughout the project, referenced in processes, templates, and integrations.

2. **Assigning Overrides**
   * In the project's Runtime view, open **Configure Params Overrides**.
   * Select a configuration parameter and assign an override value for the current workspace.
   * Confirm the changes to apply the overrides for that workspace.

3. **Viewing and Editing Overrides**
   * From the project’s settings, you can review all environment-specific overrides in one place.
   * Edit existing overrides or add new ones as needed to adapt to changes in environment requirements.

#### Technical details

1. **Parameter Resolution at Runtime**
   * During runtime, the system retrieves the active configuration parameters for the project. If overrides are set for the environment, they replace the default values.
   * This resolution ensures that the correct parameters are used, based on the environment in which the application is running.

2. **Integration with Business Rules and Processes**
   * Configuration parameters can be directly referenced in business rules and processes. Overrides ensure that these references point to the correct environment-specific values during execution.

> [!NOTE]
>
> For more information on how to use configuration parameters in business rules, see [Extracting values from configuration parameters](../../building-blocks/actions/business-rule-action/extracting-additional-data#extracting-values-from-configuration-parameters)

3. **Storage and Management**
   * Configuration parameters and their overrides are stored centrally, and the values are retrieved dynamically during runtime. This centralized approach ensures that updates to parameters are automatically reflected in the application without needing a new build.

#### Example use case

Imagine you have an application that integrates with a third-party CRM system. You:

* Define a `CRM_URL` parameter with a default value.
* Add overrides in the Staging and Production workspaces with their respective URLs.
* In the Staging workspace, the system automatically uses the staging CRM URL for all integration points without changing the project’s core configuration.
* In the Production workspace, the system uses the production override, ensuring that the application connects to the right CRM instance.


# Manage Triggers
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/manage-triggers

Monitor and control event-based triggers that automatically start process instances. Manage Triggers provides a centralized interface to view, activate, and deactivate triggers configured in your project builds.

## Overview

The **Manage Triggers** feature provides a centralized interface for monitoring and controlling event-based triggers that automatically start process instances. Triggers connect external events (such as email arrivals, message events, or other data sources) to your process definitions, enabling event-driven automation.

> [card] Trigger Types
>
> Supported trigger types:
>
> * **Email Trigger** (IMAP): Start processes when emails arrive via [Email Trigger](../../platform-deep-dive/integrations/email-trigger) data sources
> * **Microsoft Outlook** (MS Graph): Start processes when emails arrive via [Microsoft Outlook](../../platform-deep-dive/integrations/microsoft-outlook-data-source) data sources. These rows show the trigger type **Email Trigger**.
> * **Webhook**: Start or resume processes when an external system calls an [Incoming Webhook](../../platform-deep-dive/integrations/incoming-webhooks)

![Manage Triggers Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/emt.png)

## Accessing manage triggers

Navigate to **Runtime** → **Runtime Settings** → **Manage Triggers** in your project to access the triggers management interface.

> [!NOTE]
>
> You must have appropriate runtime permissions to view and manage triggers. See [Workspace runtime editor](/5.9/setup-guides/access-management/workspaces-access-rights#workspace-runtime-editor) for details.

## Trigger list

The **Manage Triggers** interface displays all triggers configured in your active build. Each trigger appears as a row in the table with the following information:

| Column | Description |
| - | - |
| **State** | Current status: `Active` (monitoring enabled) or `Deactivated` (monitoring paused) |
| **Trigger Type** | The type of trigger: `Email Trigger` (IMAP and Microsoft Outlook data sources) or `Webhook` |
| **Event Name** | The name of the trigger data source or event configuration |
| **Location** | `Local` when the trigger is defined in this project, or the name of the library project the trigger comes from |
| **Used in** | How many resources subscribe to the trigger, as a count such as `2 resources`, with a breakdown by processes and workflows on hover. A trigger nothing uses shows `0 resources`, and its hover reads `Not used by any resource`. |

The **Used in** column is new in FlowX.AI 5.12.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![The Manage Triggers list showing webhook triggers with their state, type, event name, location, and the Used in column reporting how many resources subscribe to each](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/manage-triggers-used-in.png)

### Empty state

When no triggers are configured for your project, the interface displays an empty state message: **"There are no triggers on this project yet."**

Triggers appear in this list once:

1. ✅ A trigger data source is created (for example, Email Trigger in Integration Designer)
2. ✅ The trigger is linked to a Message Start Event node in a process definition (Email Trigger or Incoming Webhook), to a Message Catch Intermediate Event that waits for an Incoming Webhook, or, on SaaS (5.12), to the Start node of an [integration workflow](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers)&#x20;
3. ✅ The process is included in a build that is part of the **Active Policy**

## Activating and deactivating triggers

You can control trigger monitoring directly from the **Manage Triggers** interface:

**1. View triggers**

Navigate to **Runtime** → **Runtime Settings** → **Manage Triggers** to see all available triggers for your active build.

**2. Change the trigger state**

Open the row menu (**⋮**) on the trigger and select **Activate** or **Deactivate**, then confirm. The **State** column updates to:

* **Active**: The system monitors for events and creates process instances automatically
* **Deactivated**: Monitoring is paused; no new process instances are created from this trigger

For webhook triggers, the same menu also has **Get URL**, which shows the webhook endpoint to give to the calling system.

![Manage Triggers Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/emt1.png)

> [!WARNING]
>
> When you change the **Active Policy** (switch to a different build), triggers retain their previous activation state. If a trigger is removed from the new active build, it will be automatically deactivated.

## Trigger activation requirements

For a trigger to appear in **Manage Triggers**, it must meet all of the following requirements:

1. **Trigger data source exists**: The trigger must be configured as a data source (for example, Email Trigger in Integration Designer)
2. **Linked to process**: The trigger must be connected to a Message Start Event node in a process definition (Email Trigger or Incoming Webhook), to a Message Catch Intermediate Event that waits for an Incoming Webhook, or, on SaaS (5.12), to the Start node of an [integration workflow](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers)
3. **In active build**: The process containing the trigger must be part of a build that is set as the **Active Policy**

> [!NOTE]
>
> Triggers are read-only in the Runtime view. To modify trigger configurations (for example, change email server settings, update filters), you must edit the data source in Integration Designer and create a new build.

## Use cases

> [card] Email-based automation
>
> Automatically start customer support processes when emails arrive in monitored mailboxes. Email Triggers enable event-driven workflows for support ticket creation, document processing, and request handling.

> [card] Event-driven processes
>
> Connect external systems to FlowX processes through event triggers. When external events occur (emails, messages, API calls), processes start automatically without manual intervention.

> [card] Production control
>
> Pause or resume trigger monitoring in production environments without redeploying builds. This is especially useful for maintenance windows or when troubleshooting issues.

> [card] Multi-environment management
>
> Manage trigger states independently across different environments (dev, staging, production) while using the same build configuration.

## Monitoring trigger activity

### Failed triggers

When triggers fail to process events (for example, email validation errors, connection issues), they appear in the **Failed Triggers** section.

Navigate to **Runtime** → **Processes** → **Failed Triggers** to view:

* Timestamp of the failure
* Trigger type and name
* Cause type (for example, "File type not permitted," "File size exceeded")
* Context information (for example, sender email, file details)

> [card] [Handling failed triggers](/5.9/docs/platform-deep-dive/integrations/email-trigger#handling-failed-triggers)
>
> See the Email Trigger documentation for the failure causes, the details view, and how to resolve failed email triggers.

## Best practices

> [card] Test before activation
>
> Always test triggers in development environments before activating them in production. Verify that process instances start correctly and handle edge cases.

> [card] Monitor failed triggers
>
> Regularly check the Failed Triggers section to identify and resolve issues. Common causes include file size limits, connection problems, and validation errors.

> [card] Use descriptive names
>
> Give triggers descriptive names in Integration Designer to make them easily identifiable in the Manage Triggers list.

> [card] Document trigger behavior
>
> Document which processes are triggered by each trigger and under what conditions. This helps with troubleshooting and maintenance.

## Related resources

> [card] [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger)
>
> Learn how to configure Email Triggers in Integration Designer and connect them to Message Start Events.

> [card] [Message Start Events](/5.9/docs/building-blocks/node/message-events/message-catch-start-event)
>
> Understand how Message Start Events work and how to configure them in process definitions.

> [card] [Active Policy](/5.9/docs/projects/runtime/active-policy)
>
> Learn how to set the Active Policy to control which build's triggers are available for management.

> [card] [Failed Process Start](/5.9/docs/projects/runtime/active-process/failed-process-start)
>
> View and debug exceptions raised when a process instance fails to start.

> [card] [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
>
> Configure Incoming Webhook data sources that start or resume processes, and find the webhook URL to share with callers.


# Scheduled processes
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/scheduled-processes

Automate process instance creation on specific dates, times, or intervals using Start Timer Event nodes and predefined schedules.

## Overview

The **Scheduled Processes** feature automatically triggers process instances using Timer Start Events. In the **Runtime** tab, you can view scheduled processes and activate/deactivate timers without a redeployment. This feature is especially useful in upper environments, where you might need to pause or resume cron jobs without modifying the project build.

> [card] [Timer Start Event](../../building-blocks/node/timer-events/timer-start-event)
>
> Check this section for more details about Timer Start Events and how to configure them.

![Scheduled processes list in Runtime Settings with State, Process Name, Swimlane Name, Timer Name, Timer Type, and Location columns, including one row per swimlane for a multi-swimlane process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

### Where are workflow schedules managed?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, this page is called **Schedules** (**Runtime** → **Runtime Settings** → **Schedules**). It lists process timers and [workflow schedules](../../platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule) together, and the **Origin** filter (**Process** or **Workflow**) separates them. You activate and deactivate workflow schedules here the same way as process timers. Self-hosted deployments keep the **Scheduled Processes** page until the next LTS release.

## Key components

### 1. List of scheduled processes

The **Scheduled Processes** tab displays all timers that trigger process instances. Each row in the list shows:

* **Process Name:** The process linked to the timer.
* **Swimlane Name:** In multi-swimlane processes, each swimlane may have its own timer.
* **Timer Name:** The name of the timer node.
* **Timer Type:**
  * **Date-based:** Triggers at a specific date and time.
  * **Cycle-based:** Repeats at defined intervals (for example, every 10 seconds).
* **Location:** The execution environment (e.g., **Local**).

From this interface, you can view timer details or activate/deactivate timers as needed.

### 2. Timer Events schedule

To view a timer’s configuration, click the **View** icon next to the scheduled timer in the list.

![Timer Events Schedule dialog for a Cycle timer showing Repeat Every 10 secs and 60 repeats](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/timer_events_schedule.png)

### 3. Activating and deactivating timers

Manage timer activation directly from the UI:

![Animation of activating a timer from the play icon in the Scheduled processes list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/activate_scheduled_processes.gif)

* **Activate:** Click the activate button in the Scheduled Processes tab.
* **Deactivate:** Click the same button to suspend the timer.

> [!WARNING]
>
> You cannot edit timer configurations in the **Runtime** tab. To modify settings, update the process definition and redeploy.

***

## Use cases

**1. Employee Onboarding reminder**

A Timer Start Event can be scheduled to **automatically trigger** an onboarding process at a predefined time.

**Example**: Process starts on **January 28, 2025, at 12:14 PM**, sending onboarding notifications.

**2. Recurring Data processing jobs**

A Cycle timer can execute a job **every 10 seconds for 60 repetitions**, ensuring periodic execution.

**3. Scheduled Report generation**

A cycle timer with a cron expression can generate a report at **1 AM every day**.

***

## Additional notes

* **Runtime Timer Control:**\
  Manage timers in the **Runtime** tab without changing the application build. The Timer Start Event node itself has no activation setting.

* **Timers in Multi-Swimlane Processes:**\
  Each swimlane can have its own timer. The **Scheduled Processes** tab displays each timer separately for clear management.

* **Exporting and Importing Builds:**\
  Timer activation settings are not editable during build export/import. All timer management occurs in the **Runtime** tab.

***

## Related resources

> [card] [Timer Start Event](/5.9/docs/building-blocks/node/timer-events/timer-start-event)
>
> Configure the Date or Cycle timer that schedules a process

> [card] [Timer expressions](/5.9/docs/building-blocks/node/timer-events/timer-expressions)
>
> ISO 8601 and cron syntax for timer definitions

> [card] [Active policy](/5.9/docs/projects/runtime/active-policy)
>
> Choose the build whose timers are scheduled


# UI Flow Sessions
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/ui-flow-sessions

Monitor and manage active UI Flow sessions, track session activity, and view audit logs. UI Flow Sessions provides visibility into user interactions with UI Flows, including session status, audit trails, and associated processes.

## Overview

**UI Flow Sessions** provides a comprehensive interface for monitoring and managing active user sessions with UI Flows. This feature enables you to track session activity, view audit logs, monitor associated processes, and debug UI Flow interactions in real-time.

> [card] UI Flows
>
> UI Flows are reusable, multi-platform user interfaces that work across web, iOS, and Android. They provide an alternative to BPMN processes when full process orchestration is not required.

![UI Flow Sessions Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/uifs.png)

## Accessing UI flow sessions

In your project's Runtime view, open **UI Flows Sessions** to access the sessions management interface.

> [!NOTE]
>
> You must have appropriate runtime permissions to view UI Flow Sessions. See [Workspace runtime editor](/5.9/setup-guides/access-management/workspaces-access-rights#workspace-runtime-editor) for details.

## Sessions list

The **UI Flow Sessions** interface displays all active and historical sessions for UI Flows in your project. Each session appears as a row in the table with the following information:

| Column | Description |
| - | - |
| **ID** | Unique session identifier (UUID format) |
| **UI Flow** | The name of the UI Flow definition associated with this session |
| **Status** | Current session status (for example, `STARTED`, `FINISHED`, `ACTIVE`) |
| **Start Date** | Date and time when the session was initiated (localized format) |

### Filtering and searching

Use the filter and search controls preceding the sessions table to find specific sessions:

* **Filter by definition**: Select a specific UI Flow definition from the dropdown to show only sessions for that UI Flow
* **Search by session id**: Enter a session ID (full or partial) to quickly locate a specific session

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Status** column additionally carries a multi-select filter, and **Start Date** a date filter, so you can scope the list to, say, failed sessions inside an incident window.

## Session details

Click on any session in the list to view detailed information about that session. The session details view provides comprehensive insights into session activity.

### Session information header

The session details header displays:

* **UI Flow**: The name of the UI Flow definition
* **UI Flow session ID**: The unique session identifier with a copy button for easy sharing
* **Status badge**: Visual indicator of the current session status (for example, `STARTED`, `FINISHED`)

### Detail tabs

The session details view includes four tabs for different aspects of the session:

> [tab] Variables
>
> Inspect runtime variables associated with the UI Flow session.
>
> The **Variables** tab displays the current state of all variables in the session. You can switch between two view modes using the dropdown:
>
> * **Tree View** — Expandable JSON tree viewer for navigating nested data structures
> * **JSON View** — Read-only Monaco code editor with JSON syntax highlighting
>
> Click **Export JSON** to download the session variables as a `.json` file.
>
> > [!NOTE]
> >
> > The Variables tab is the first tab in the session details panel, giving you immediate access to the session's data state when debugging.

> [tab] Audit Log
>
> View a chronological log of all events and actions that occurred during the session.
>
> **Audit Log columns:**
>
> | Column | Description |
> | - | - |
> | **Timestamp** | Date and time when the event occurred (localized format) |
> | **User** | User email or identifier who performed the action |
> | **Subject** | Type of subject (e.g., "UI Flow Session") |
> | **Event** | Event type (e.g., "Start", "Navigate", "Action") |
> | **Subject Identifier** | Unique identifier for the subject (session ID, process instance ID, etc.) |
> | **Status** | Event status (e.g., `success`, `failed`, `pending`) |
> | **View** | Eye icon to view additional details about the event |
>
> ![UI Flow Session Audit Log](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/uifs_audit_log.png)
>
> **Common audit log events:**
>
> * **Start**: Session initialization
> * **Navigate**: Navigation between Navigation Areas
> * **Action**: Actions executed (e.g., Start Process, Navigate To)
> * **Process Start**: Process instances launched from the UI Flow
> * **Process Complete**: Process instances completed

> [tab] Processes
>
> View all process instances that were started from this UI Flow session.
>
> This tab shows:
>
> * Process instance IDs
>
> * Process definition names
>
> * Process status
>
> * Start and completion times
>
> * Links to process instance details
>
> > [!NOTE]
> >
> > Processes started from UI Flows using the **Start Process action** appear in this tab. This enables you to trace which business processes were triggered by user interactions in the UI Flow.

> [tab] Workflows
>
> View workflow execution details for workflows associated with this UI Flow session.
>
> This tab provides:
>
> * Workflow run IDs
>
> * Workflow execution status
>
> * Node-by-node execution timing
>
> * Input/output data
>
> * Execution logs
>
> > [card] Workflow Debugging
> >
> > Use the Workflows tab to debug workflow execution, view node execution times, and inspect data transformations. This is especially useful for troubleshooting AI agent workflows or data source operations.

## Session statuses

UI Flow sessions can have different statuses indicating their current state:

| Status | Description |
| - | - |
| **STARTED** | Session has been initiated and is active |
| **ACTIVE** | Session is currently active with ongoing user interactions |
| **FINISHED** | Session has been completed or closed |
| **FAILED** | Session encountered an error and was terminated |

> [!NOTE]
>
> Session statuses are updated in real-time as users interact with UI Flows. The status badge in the session details view reflects the current state.

## Use cases

> [card] Session monitoring
>
> Monitor active UI Flow sessions to understand user engagement and identify sessions that may need attention or support.

> [card] Audit and compliance
>
> Track all user interactions and actions within UI Flow sessions for audit purposes and compliance requirements.

> [card] Debugging and troubleshooting
>
> Investigate issues by reviewing audit logs, process instances, and workflow executions associated with a specific session.

> [card] Performance analysis
>
> Analyze session duration, process start times, and workflow execution performance to identify optimization opportunities.

> [card] User support
>
> Use session details to help users by understanding what actions they performed and identifying where they may have encountered issues.

> [card] Process tracking
>
> Trace which business processes were triggered from UI Flow interactions and monitor their execution status.

## Best practices

> [card] Regular monitoring
>
> Regularly review active sessions to identify long-running sessions or sessions that may indicate user issues.

> [card] Use filters effectively
>
> Use the filter by definition to focus on specific UI Flows when troubleshooting or analyzing usage patterns.

> [card] Review audit logs
>
> Check audit logs for failed events or unexpected behavior patterns that may indicate configuration issues.

> [card] Track process launches
>
> Monitor the Processes tab to understand which business processes are most commonly triggered from UI Flows.

## Troubleshooting

> [accordion] Session not appearing in list
>
> **Possible causes:**
>
> * Session hasn't been started yet
> * Filter is excluding the session
> * User doesn't have permission to view sessions
>
> **Solutions:**
>
> * Verify the UI Flow is being accessed by users
> * Clear filters and search again
> * Check user permissions for Runtime access
> * Verify the build containing the UI Flow is active

> [accordion] Audit log shows failed events
>
> **Possible causes:**
>
> * Event handler configuration error
> * Process start failure
> * Workflow execution error
> * Permission issues
>
> **Solutions:**
>
> * Review the event details using the view icon
> * Check process definition is published and accessible
> * Verify workflow configuration in Integration Designer
> * Confirm user has necessary permissions
> * Review browser console for client-side errors

> [accordion] Process instances not showing
>
> **Possible causes:**
>
> * Process wasn't started from the UI Flow
> * Process start action failed
> * Process instance was deleted
>
> **Solutions:**
>
> * Verify the Start Process action is configured correctly
> * Check audit log for process start events
> * Confirm process definition is in the active build
> * Review Failed Process Start section for errors

## Related resources

> [card] [UI Flows](/5.9/docs/building-blocks/ui-flows)
>
> Learn about UI Flows, their capabilities, and how to create and configure them.

> [card] [Start Process action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-process-action)
>
> Understand how to configure Start Process actions to launch processes from UI Flows.

> [card] [Process Instance](/5.9/docs/projects/runtime/active-process/process-instance)
>
> Learn how to monitor and manage process instances that are started from UI Flows.

> [card] [Chat Component](/5.9/ai-platform/chat-component)
>
> Understand how chat sessions are tracked within UI Flow Sessions for AI-powered workflows.


# Workflow instances
Source: https://docs.flowx.ai/5.9/docs/projects/runtime/workflow-instances

A Runtime page listing every workflow run in the project, filterable by origin, status, and start date.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

> [!NOTE]
>
> **On self-hosted FlowX.AI 5.9**, this page isn't available yet. Find past workflow runs in two places:
>
> * **Runs started from the Designer:** open the workflow in Integration Designer and open the **Run Logs** panel at the bottom. Its **History** list shows past runs. Select one to see each node with its logs, input and output, which is how you find the node that failed and its error.
> * **Runs started by a process:** open the process instance and use its **Workflows** tab.

## Overview

The **Workflow Instances** page lists every workflow run in the project, in one place. Until now a workflow's runs were visible only from inside that workflow in the Integration Designer, so finding a failed run meant already knowing which workflow it belonged to.

Open it from **Projects → Your Project → Runtime → Workflow Instances**. Viewing it requires the same read permission as the Process Instances page.

![The Workflow Instances page listing runs with their UUID, name, origin, status, and start and finish dates, with column filters on Origin, Status, and Date started](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/workflow-instances-page.png)

## The list

| Column | Description |
| - | - |
| **UUID** | The run's unique identifier. |
| **Name** | The workflow definition the run belongs to. |
| **Origin** | What started the run: **Process**, **UI Flow**, **Webhook**, **Email**, or, on SaaS (6.0), **Schedule**. Runs started by hand from the Designer aren't listed here: open them from the workflow's **Run Logs** panel. A workflow invoked as an agent's [workflow tool](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run) shows `WORKFLOW_TOOL`. |
| **Status** | **Started**, **Finished**, **Failed**, or **Cancelled**. |
| **Date started** / **Date finished** | When the run began and ended. |

## Finding the runs you care about

Three controls narrow the list:

* **Filter by workflow definition**, above the table.
* **Origin** and **Status** column filters, each a multi-select, so one view can show, say, every **Failed** run started by a **Webhook** or **Email** trigger.
* A date filter on **Date started**, for scoping to an incident window.

> [!TIP]
>
> The **Origin** filter is the fastest way to audit [event-triggered workflows](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers): runs started by a webhook or an email trigger carry that origin, while runs started from a process or a UI Flow carry theirs.

## Related resources

> [card] [Process instances](./active-process/process-instance)
>
> The sibling page for process runs, with the same status and date filters

> [card] [UI Flow sessions](./ui-flow-sessions)
>
> Sessions for UI Flows, also filterable by status and start date


# Workspaces
Source: https://docs.flowx.ai/5.9/docs/projects/workspaces

Workspaces enable organizations to manage multiple business contexts within one FlowX instance while maintaining logical data isolation.

![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)

> [!NOTE]
>
> **Scope**: This page covers Designer-side access to workspaces and projects. For runtime authorization — how end users access published solutions on 5.9.x — see [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization).

### Key benefits

> [card] Faster Onboarding
>
> Onboard new business verticals in days instead of weeks with shared platform capabilities

> [card] Data Isolation
>
> Provide secure separation between different business contexts while allowing controlled resource sharing

> [card] Enhanced Access Control
>
> Implement granular permissions with role-based access control (RBAC) and access control lists (ACLs)

## Key concepts

### Workspace

A workspace is a logical grouping of entities and assets defined in FlowX that are only available to a subset of users who are given explicit access. Each workspace operates independently, ensuring data and configuration separation between different business contexts.

### Multi-workspace user access

Users can be granted access to multiple workspaces and can switch between them as needed. When a user has access to multiple workspaces, they can select which workspace to enter after authentication.

### Data isolation

Workspaces provide logical data isolation, meaning that resources (projects, libraries, themes, etc.) are scoped to specific workspaces and cannot be accessed from other workspaces without explicit sharing configurations.

### Additional terminology

* **Group**: A collection of users who share common characteristics, responsibilities, or access needs within a system. Groups are used to simplify access control by managing permissions collectively rather than assigning them individually to each user.
* **Permissions**: Define what actions can be performed on resources. They are fine-grained access controls that specify privileges for a resource type, such as: read process, edit process, delete process.
* **Roles**: Collections of permissions grouped together based on job functions or responsibilities. They simplify permission management by assigning a set of permissions to users instead of managing them individually.

> [!NOTE]
>
> **Role assignment rule**: Roles are never assigned directly to users or groups. A user or group is assigned a role ONLY when given access to a workspace OR a project/library. **Exception**: `org_admin` role is the only one assigned to users directly at the organization level.

> [!NOTE]
>
> When a user has multiple roles assigned in the context of a workspace or project, their access level is the union of all permissions from all roles associated with the user.

## Workspace use cases

> [accordion] Multiple Business Lines
>
> **Isolation Level**: High
>
> Different use cases, projects, permissions, and users between business verticals (e.g., retail vs. corporate vs. investment banking).
>
> **Shared Resources**:
>
> * Shared users across business lines
> * Shared library builds
> * Shared themes (configurable)
>
> **Example**: A multinational bank with separate workspaces for Retail Banking, Corporate Banking, and Investment Banking, each with its own processes but sharing common user authentication and compliance libraries.

> [accordion] Regional Separation
>
> **Isolation Level**: Medium
>
> Same business line across different regions, subject to local regulations.
>
> **Shared Resources**:
>
> * Libraries and common processes
> * Some shared users with multi-region access
>
> **Example**: An insurance company with workspaces for US, EU, and APAC operations, sharing global insurance processes but maintaining region-specific compliance and regulatory processes.

> [accordion] Distinct Organizations
>
> **Isolation Level**: Highest
>
> Complete separation for different customers or organizations.
>
> **Shared Resources**: None
>
> **Example**: A consulting firm providing FlowX services to multiple clients, with completely isolated workspaces for each client organization.

## How workspaces work

### Authentication and access flow

**1. User Authentication**

User logs in using OAuth 2.0 through the configured identity provider (Keycloak or client's existing provider). Authenticated users are saved with subject ID in FlowX database.

**2. Permission Retrieval**

System fetches the user's workspace permissions and available workspaces

**3. Workspace Selection**

If user has access to multiple workspaces, they select which workspace to enter

**4. Context Loading**

FlowX Designer loads with workspace-specific content, projects, and permissions

### Workspace selection experience

The workspace selection experience varies based on user access:

> [tab] Single Workspace Access
>
> **Direct Navigation**: Users with access to only one workspace are automatically redirected to the projects page within their workspace.
>
> **UI Behavior**: The workspace dropdown selector is disabled since no selection is needed.
>
> **Session Flow**: Simplified experience with no additional selection steps required.

> [tab] Multiple Workspace Access
>
> **Homepage Display**: Users see a "Your Workspaces" homepage after authentication.
>
> **Workspace Layout**:
>
> * Workspaces displayed in alphabetical order
> * 3 workspace tiles per row
> * Name truncation with "..." for long names
> * Hover tooltips show full workspace names
>
> **Navigation to Organization Admin view**: when a logged in user is an organization admin, Organization Settings button appears on Select Workspace page in top right corner.

> [tab] No Workspace Access
>
> **Empty State Display**: Users without access to any workspace see an informational message instead of the workspace list.
>
> **Message Content**: "You're not assigned to a workspace yet" or similar notification
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/no_workspace.png)
>
> **Next Steps**: User must wait for an organization admin to grant workspace access before they can proceed
>
> > [!NOTE]
> >
> > This scenario commonly occurs for new users from LDAP/Active Directory after their first login, before an admin assigns workspace access.

#### Session management

> [!NOTE]
>
> **Session Persistence**: Workspace selection is saved for the user session. On subsequent visits within the same session, users are automatically redirected to their previously selected workspace.

#### Error handling and access denied scenarios

> [accordion] No Access to Selected Workspace
>
> **Trigger**: User attempts to access a workspace they don't have permissions for, or workspace ID is incorrect
>
> **System Response**: User is redirected to `workspace/403` error page
>
> **Common Causes**:
>
> * Workspace access was revoked
> * User navigated to an invalid workspace ID
> * Workspace was deleted or renamed
>
> **Resolution**: Contact workspace admin or organization admin to restore access

> [accordion] No Access to Resource
>
> **Trigger**: User attempts to access a specific resource (project, library, etc.) they don't have permissions for
>
> **System Response**: User is redirected to `403` error page
>
> **Common Causes**:
>
> * Insufficient project-level permissions
> * Resource is restricted to specific roles or groups
> * Project access was revoked
>
> **Resolution**: Request access from the project owner or workspace admin

### Resource management

> [tab] Project Isolation
>
> **Workspace Scoping**: Each project is tagged with its workspace ID and only accessible within that workspace
>
> **Independent Lifecycle**: Projects in different workspaces can have the same names and follow independent versioning
>
> **Cross-Workspace Import**: The same project can now be imported into multiple workspaces on the same environment. Each imported project maintains its own independent lifecycle with separate active policies and access controls.
>
> **Import Behavior**: Projects created from version or build import are created with access only for the currently logged in user with 'Project Owner' role. Workspace admins are also able to view projects. Access can be extended to required users subsequently.
>
> **Runtime Permissions**: Permissions for Runtime section are received by users with workspace role. Users inherit runtime permissions from workspace role for ALL projects/libraries they have access to.

> [tab] Library Sharing
>
> **Build Sharing**: Library builds can be reused across workspaces on the same environment
>
> **Controlled Access**: Libraries from other workspaces can be added as dependencies if permissions allow
>
> **Version Management**: Single version constraint applies across workspace boundaries for shared libraries
>
> **Workspace Access**: All builds created in workspace for any library have 'public' access within workspace. When adding library dependencies, all libraries with builds are available as dependencies.
>
> **Cross-Workspace Sharing**: Library builds can be shared across workspaces using export/import mechanism
>
> > [!WARNING]
> >
> > **Important**: Library builds from Workspace A can be imported into Workspace B on same environment. Libraries containing only builds are not viewable to workspace users outside the Dependencies page.
>
> **Library Creation**: Libraries are created only with version import (not created when importing a build of a library).

> [tab] Theme Management
>
> **Workspace Themes**: Each workspace can have its own themes and branding
>
> **Shared Themes**: Themes can be shared between workspaces when configured appropriately
>
> **Brand Consistency**: Maintain consistent branding across business units or customize per workspace
>
> **Default Theme**: Default theme can be set in each workspace. When creating a project or library, the project/library version inherits the workspace default theme as the configured theme in Version settings.
>
> **Export/Import**: Themes can be shared across workspaces using export/import.

> [tab] Media Files & Fonts
>
> **Media Files**: Each workspace can create and manage workspace specific media files, not accessible to be used by other workspaces. However, when exporting themes, media files will also be exported and can be imported easily in other workspace together with the theme.
>
> **Fonts**: Fonts can be uploaded from **Organization Settings** or from a workspace, under **Design Assets → Fonts**. Every uploaded font is shared by all workspaces in the organization.

### Additional workspace features

#### Command Center (AI Agents)

> [!NOTE]
>
> AI Agents permission is a project-level permission. **Consequence**: Command center is available only on projects or libraries pages.

#### Audit Logs

The **Audit Logs** entry in the main menu shows the workspace audit log, which includes entries for every project and library in the workspace. It is visible to users whose workspace role includes the `wks_audit_log_read` permission. Every built-in workspace role includes it. See the [permission reference guide](/5.9/setup-guides/access-management/permission-reference-guide).

## Access control

### Role-based access control (RBAC)

> [!NOTE]
>
> For detailed role permissions and setup instructions, see [Workspaces Access Rights](../../setup-guides/access-management/workspaces-access-rights).

> [card] Predefined Roles
>
> * **Project editor** - Can modify project content, processes, and configurations. Includes all Project Viewer permissions.
> * **Project viewer** - Read-only access to project content and processes. Cannot make modifications.
> * **Workspace user** - View only access to workspace entities. Can create projects, but only sees projects they have explicit access to.
> * **Owner** - Automatically assigned to project creators. Full control over project settings, access management, and can delete the project.
> * **Theme editor** - Extends workspace user role to include permissions to manage themes and associated resources (global media files).
> * **Workspace admin** - Manages all workspace level resources including users, roles, themes. Can configure access and content, but cannot manage organization-wide settings.
> * **Runtime editor** - Enables users to test runtime functionality and manage runtime policies without full configurator permissions. Commonly used by QA teams and testers who need to manage "change active policy" operations and test processes during runtime without broader editing capabilities.
> * **Operations editor** - Extends workspace user role to view and edit process instances, edit process instance variables, and manage operations (migration and move token) on all projects and libraries in the workspace.

> [card] Workspace-Specific
>
> Roles are specific to each workspace - a user can have different roles in different workspaces

> [!NOTE]
>
> Only pre-defined roles are available for workspace and project/library access.

#### Detailed role permissions

To add a user to a workspace, and to assign a role to the user, you need to go to **Organization settings** page and select your desired workspace, then add the user to the workspace and assign the role to the user.

* **Workspace admin**: Manages all workspace level resources including users, roles, themes. Can configure access and content, but cannot manage organization-wide settings.

> [!WARNING]
>
> Workspace admins will be able to view and edit ALL projects and libraries in workspace, regardless of project/library access settings.

* **Workspace user**: View only access to workspace entities. Can create projects, but only sees projects they have explicit access to.

* **Theme editor**: Extends workspace user role to include permissions to manage themes and associated resources (global media files).

* **Runtime editor**: Enables users to test runtime functionality and manage runtime policies without full configurator permissions. Commonly used by QA teams and testers who need to manage "change active policy" operations and test processes during runtime without broader editing capabilities.

* **Operations editor**: Extends workspace user role to view and edit process instances, edit process instance variables, and manage operations (migration and move token) on all projects and libraries in the workspace. See the [permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wks1.png)

### User groups

> [!NOTE]
>
> User groups simplify permission management by allowing you to assign permissions to groups rather than individual users.

* **Default Groups**: Each workspace includes an "Everyone in workspace" default group
* **Custom Groups**: Create groups based on teams, departments, or project requirements
* **Inherited Permissions**: Users automatically inherit permissions from their group memberships

### Access control lists (ACLs)

> [accordion] Resource-Specific Permissions
>
> Grant fine-grained control over individual resources within a workspace, allowing exceptions to general role permissions.
>
> **Example**: A user with `project_viewer` role can be granted edit access to a specific project without becoming a full `configurator`.

> [accordion] Exception-Based Access
>
> Provide specific users or groups access to individual resources without requiring full platform permissions.
>
> **Use Case**: External consultants can be given access to specific projects they're working on without broader workspace access.

> [accordion] Owner Management
>
> Resource creators can manage access to their specific resources without requiring full admin intervention.
>
> **Benefit**: Project owners can add team members to their projects without needing admin approval for each addition.

### Project-level access control

Projects and libraries support fine-grained access control through dedicated project roles that work alongside workspace-level permissions.

> [card] Project Owner
>
> Automatically assigned to project creators. Full control over project settings, access management, and can delete the project.

> [card] Project Editor
>
> Can modify project content, processes, and configurations. Includes all Project Viewer permissions.

> [card] Project Viewer
>
> Read-only access to project content and processes. Cannot make modifications.

#### Creating a project

**1. Create Project**

Create a new project by clicking the **+** icon in the top-right corner of the Projects page.

**2. Owner Assignment**

The currently logged-in user is automatically assigned as Project Owner with full access rights.

**3. Extend Access**

Project owners can subsequently add users or groups with Project Editor or Project Viewer roles as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wks2.png)

#### Access management inheritance

* **Project Editor role** automatically includes Project Viewer permissions
* **Multiple roles**: Users can have both workspace-level and project-level roles simultaneously
* **Permission union**: When users have multiple roles, their access is the combination of all permissions from all assigned roles

## Organization administration

### Organization admin role

> [!NOTE]
>
> The `org_admin` role is the only role assigned directly to users at the organization level, not workspace level.

Organization admins will be able to see all workspaces and have the same permissions as Workspace Admins inside each workspace. Multiple users can have this role assigned. Role can be assigned/revoked by other org admins.

To promote an existing Designer user to organization admin:

1. Go to **Organization Settings** → **Users**.
2. Find the user in the list and open their context menu (the three-dot menu).
3. Select **Set as ORG Admin**.

> [!NOTE]
>
> Only an existing organization admin can promote another user. Use **Set as ORG Admin** directly — changing the role through the user's **Edit** form is a different flow and is not how the organization admin role is assigned.

### User management

> [!WARNING]
>
> Users from an external identity provider appear in FlowX only after their first login to FlowX Designer. An organization admin can add someone ahead of that by inviting them or creating them directly — see [User creation scenarios](#user-creation-scenarios).

The **Organization Users** page lists only **Designer users** — users who have logged into FlowX Designer at least once, or who were manually created by an organization admin. It does not list **end users**, who access published solutions at runtime. Designer users and end users are managed separately:

* **Designer users** — managed in **Organization Settings → Users**. Control access to the FlowX Designer, workspaces, projects, and libraries.
* **End users** — managed in **Organization Settings** → **Access Management** (**End-Users** and **End-Users Groups**). Control access to published solutions at runtime (e.g., who can start or view a process). End-user roles are defined per project in **Version Settings** → **End-User Roles**.

> [!NOTE]
>
> End-user groups are managed inside FlowX (not in Keycloak), and a role grants access only on the solutions where it's been explicitly shared from the Solutions page. See [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization).

The **User Details** page shows the Designer user's Workspace access summary (which workspaces they belong to and what roles they hold).

#### User creation scenarios

> [tab] LDAP/Active Directory Users
>
> **Sync Behavior**: Users from customer's LDAP/Active Directory are not automatically created in FlowX.
>
> **Onboarding Steps**:
>
> 1. User logs into FlowX Designer for the first time
>
> 2. They are redirected to a "You're not assigned to a workspace yet" message page
>
> 3. User account is now created in FlowX and appears in the Users list in Organization Settings
>
> 4. Organization admin assigns workspace access with appropriate role (Workspace User, Workspace Admin, Theme Editor, Runtime Editor, or Operations Editor)
>
> 5. On next login, user will have access to assigned workspaces
>
> > [!NOTE]
> >
> > Users synced from LDAP will only appear in FlowX after their first login attempt.

> [tab] Direct FlowX Creation
>
> **Prerequisites**: Only available when using Keycloak as the authentication provider.
>
> **Creation Process**:
>
> 1. Organization admin clicks the + icon in Users section
>
> 2. Enter user details (name, email, password, runtime roles)
>
> 3. User is immediately created in both Keycloak and FlowX Designer
>
> 4. Organization admin can immediately assign workspace access
>
> 5. User can log in directly without the initial "no workspace" flow
>
> > [!NOTE]
> >
> > This method is primarily for internal use and may not be available in all deployments. If direct user creation is needed, users should be created directly in Keycloak.

> [tab] Invitation
>
> **Use when**: onboarding someone who has not signed in yet, and you don't want to set a password on their behalf.
>
> **Invitation process**:
>
> 1. Go to **Access Management** → **Designer Users**
> 2. Select **Invite user**
> 3. Enter the **User Email** and pick an **Organization Role**
> 4. Optionally toggle **Set User First and Last Name** and fill in both fields
> 5. The invited person sets their own password when they first sign in
>
> To onboard several people at once, use **Import from CSV** instead of inviting them individually.
>
> > [!NOTE]
> >
> > Inviting creates the user, not their workspace access. Assign workspaces and roles separately afterwards — until you do, the person can sign in but has nothing to work in.

##### Assigning roles while inviting

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The invitation form also assigns access, so a person can be invited and given somewhere to build in a single step. **Invite Designer User** contains:

| Field | Purpose |
| - | - |
| **Email** | The invited person's address. Required. |
| **Set User First and Last Name** | Optional toggle that reveals **First Name** and **Last Name**. |
| **Organization-Level Roles** | **Workspace Member** (access to one or more workspaces only), **Organization Admin** (full administrative access to the organization and workspaces), or **Organization Owner** (manage users and solutions, and monitor usage). Required. |
| **Workspace-Level Roles** | Select a workspace and a role in it. Use **Add Workspace** to grant access to more than one. Required. |
| **Runtime Attributes** | Optional attributes applied to the user at runtime. |

![Invite Designer User](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/invite_user.png)

> [!TIP]
>
> This is the shortest path when onboarding a whole client or partner team, because you can grant workspace access before anyone has signed in.

### Additional organization settings

#### Runtime roles and groups

Runtime roles and end-user groups are managed in FlowX (not in Keycloak). End users and end-user groups live under **Organization Settings** → **Access Management** (**End-Users** and **End-Users Groups**); runtime roles are defined per project in **Version Settings** → **End-User Roles**. Together they control the permissions end users hold on published solutions.

> [!NOTE]
>
> Role assignment to a user or group is set per-solution from the Share modal on the Solutions page. See [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization).

> [!NOTE]
>
> Roles and groups are defined at organization level, so all workspaces share the same list.

> [!WARNING]
>
> Runtime Roles and Runtime Groups require Keycloak as the IAM backend. External identity providers (Azure AD, Okta, etc.) federate into Keycloak — they don't replace it. See [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution) for setup.

#### Set environment info

Configuring client and environment information is available only in Organization settings section under Platform status page.

## Workspace management

### Creating and managing workspaces

**1. Admin Access Required**

Only users with organization administrator permissions can create new workspaces

**2. Workspace Configuration**

Set workspace name, description, and basic settings during creation

**3. User Assignment**

Add initial users and assign appropriate roles to get started

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wks3.png)

> [!WARNING]
>
> Deleting a workspace is not currently available.

### Workspace environment type

Workspaces are labeled with an **Environment Type** that indicates their purpose within your deployment. The label is visible in every workspace listing, so users can immediately tell whether they are working in development, testing, or live data — particularly important when the same project (by UUID) is imported into more than one workspace via [cross-workspace project import](#cross-workspace-project-import).

### Available types

| Type | When to use |
| - | - |
| **Sandbox** | Development, experimentation, and testing. The default for any workspace on a non-production FlowX environment. |
| **Staging** | Pre-production validation and QA — the workspace that mirrors production data shape but is not customer-facing. |
| **Production** | Live, end-user-facing deployment. Reserve this label for workspaces that drive real customer traffic. |

### Setting the type

The Environment Type is set at workspace creation and can be changed later by a Workspace or Organization Admin:

* **At creation:** the **Create Workspace** dialog includes an **Environment Type** dropdown. Pick the type that matches the workspace's intended use.
* **After creation:** go to **Organization Settings** → select your workspace → adjust the **Environment Type** dropdown.

> [!NOTE]
>
> The selected type is displayed as a **Type** column in the Designer workspace list, so administrators and users can identify the environment without opening workspace settings.

### Multi-workspace identification

Because the same FlowX environment can host multiple workspaces, and the same project (same UUID) can be imported into more than one workspace, the Environment Type label is the primary cue for *where* a user is working. Without it, a designer opening a project cannot tell at a glance whether they are about to edit a Sandbox copy or the Production copy of the same project.

Recommended patterns:

* On a **non-production FlowX environment**, label every workspace **Sandbox** — the environment itself is not customer-facing, regardless of how the workspaces are organized internally.
* On a **production FlowX environment** that hosts multiple workspaces (for example, UAT, Staging, and Production for the same project), use **Staging** for the validation workspace and **Production** for the live workspace. The Environment Type lets users distinguish them inside the same Designer.
* Avoid mixing labels arbitrarily across an environment — the value of the cue depends on the label matching the workspace's role.

> [!TIP]
>
> Pair Environment Type with a clear **workspace naming convention** (for example, `retail-prod`, `retail-staging`, `retail-sandbox`). The combination of name and type makes the destination of every action — sharing, importing, deploying — unambiguous.

### User management within workspaces

> [tab] Adding Users
>
> * **Direct Assignment**: Add users directly to workspace with specific roles
> * **Group Membership**: Add users to groups that inherit workspace permissions
> * **Multi-Workspace Access**: Users can be members of multiple workspaces

> [tab] Role Assignment
>
> * **Multiple Roles**: Users can have multiple roles within a workspace
> * **Role Inheritance**: Roles can inherit permissions from other roles
> * **Workspace Scoping**: User roles are specific to each workspace

> [tab] Access Matrix
>
> * **Visual Interface**: See all users, groups, and their permissions at a glance
> * **Quick Adjustments**: Easily modify permissions and access levels
> * **Audit Capabilities**: Track who has access to what resources

## Migration and compatibility

### Initial setup requirements

> [!WARNING]
>
> **Critical Setup Step**: Before starting any FlowX environment, the initial organization admin must be configured.

> [!NOTE]
>
> Complete setup instructions are available in the [Workspaces Setup Guide](../../setup-guides/authorization-setup-guide).

1. To create the first user in FlowX Designer with organization admin role, an environment variable `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME` needs to be configured with the username of the user from Identity Store (Keycloak/ other Identity Store from where the users are used to login in FlowX.AI).
2. If request to Keycloak fails, the fallback is to use `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID` to create the organization admin user. Value that must be set is the ***subject identifier***. (***sub*** in *JWT token OR* user’s id in Keycloak).

> [!NOTE]
>
> This step is important for creating any environment, no matter if there's a pre-existing env or a newly created one.

> [!WARNING]
>
> **IMPORTANT**: Instruct the DevOps team to set this user id **BEFORE** system startup. Otherwise the authorization-service startup will fail. Ensure the correct value is set. The correct value is the subject id of the user, value that will be populated by the authorization service in the access token used for FlowX login.

> [accordion] For existing FlowX customers
>
> Workspaces already exist in FlowX 5.1.x, so upgrading to 5.9.x does not create or restructure workspaces: your existing workspaces, projects, libraries, themes, and Designer users carry over unchanged.
>
> What does change in the upgrade is the runtime access model (end-user roles and groups move fully into FlowX, with per-solution role assignment). See the [5.1 to 5.9 migration guide](/5.9/migrating-from-5.1-lts/overview) for the complete upgrade impact.

> [accordion] For new FlowX 5.x installations
>
> **Initial Setup Process:**
>
> 1. Configure the first workspace administrator user
> 2. Create the initial workspace
> 3. Set up users and role assignments
> 4. Begin creating projects and processes

## Best practices

### Workspace design

> [card] Clear Boundaries
>
> Define workspaces based on clear business, regulatory, or organizational boundaries

> [card] Naming Conventions
>
> Use consistent naming conventions for workspaces, roles, and resources

> [card] Documentation
>
> Document workspace purposes, user access patterns, and governance policies

> [card] Scalability Planning
>
> Plan workspace structure to accommodate future growth and organizational changes

### Permission management

* **Principle of Least Privilege**: Grant minimum necessary permissions
* **Group-Based Management**: Use groups for permission management rather than individual assignments
* **Regular Audits**: Periodically review and audit workspace permissions
* **Clear Ownership**: Establish clear ownership models for workspace resources

### Resource sharing

* **Controlled Sharing**: Implement clear policies for resource sharing between workspaces
* **Dependency Management**: Track and manage dependencies between shared resources
* **Version Control**: Maintain version control for shared libraries and themes

## Common use cases

> [accordion] Banking - Multi-Division Operations
>
> **Scenario**: Large bank with retail, corporate, and investment banking divisions
>
> **Workspace Structure**:
>
> * Retail Banking Workspace
> * Corporate Banking Workspace
> * Investment Banking Workspace
> * Shared Compliance Workspace (for common libraries)
>
> **Benefits**: Division autonomy while sharing compliance processes and user management

> [accordion] Insurance - Geographic Separation
>
> **Scenario**: Insurance company operating in multiple countries
>
> **Workspace Structure**:
>
> * US Operations Workspace
> * EU Operations Workspace
> * APAC Operations Workspace
>
> **Benefits**: Region-specific regulatory compliance while sharing global insurance processes

## Cross-workspace project import

You can import the same project into multiple workspaces on the same environment. This feature enables organizations to use workspaces to represent different operational environments (such as UAT, staging, pre-production) on a single FlowX deployment, reducing operational costs.

### How it works

> [card] Import to Multiple Workspaces
>
> Import a project build (and optionally a version) into different workspaces on the same environment

> [card] Independent Lifecycle
>
> Each imported project maintains its own lifecycle with separate active policies and access controls

> [card] No Impact on Original
>
> Importing to another workspace does not affect the original project's settings, policies, or process instances

> [card] Separate Process Instances
>
> Process instances are workspace-specific; imported projects have no instances initially until processes run in the new workspace

### Import behavior

| Aspect | Behavior |
| - | - |
| **Active Policy** | The imported build is automatically set as the active policy in the new workspace |
| **User Access** | Workspace users must be granted appropriate rights on the imported project (e.g., project viewer) to interact with it |
| **Database** | Projects across workspaces on the same environment share the same database |
| **Configuration** | All project configuration lives within each specific workspace independently |

> [!TIP]
>
> **Use case**: Organizations like banks and insurance companies can use this feature to represent different upper environments (UAT, Staging, Production) as separate workspaces on the same FlowX deployment, significantly reducing infrastructure and DevOps costs.

***

## Limitations and considerations

### Current limitations

* **Resource Isolation**: Direct access to resources from other workspaces is not possible
* **Single Environment Sharing**: Library sharing only works within the same FlowX environment
* **Permission Inheritance**: Workspace permissions don't automatically inherit across workspace boundaries

### Additional limitations

> [!WARNING]
>
> * Workspace import/export is out of scope; each FlowX environment has its own default workspace and workspaces are managed independently on each instance.
> * Library builds from other workspaces are only visible on the Dependencies page after import, not as full library entries in the workspace.

### Planning considerations

* **Change Management**: Organizational alignment needed for governance models
* **User Training**: Users need to understand workspace selection and navigation
* **Governance Policies**: Clear policies needed for resource sharing and access management
* **Migration Planning**: Existing customers should plan workspace structure before creating additional workspaces

***

## Related documentation

* [Workspaces Setup Guide](../../setup-guides/authorization-setup-guide)
* [Workspaces Access Rights](../../setup-guides/access-management/workspaces-access-rights)


# Combine UI Flows, processes, and workflows
Source: https://docs.flowx.ai/5.9/docs/building-blocks/combining-ui-flows-processes-and-workflows

Connect a UI Flow, a process, and a workflow in one FlowX app. See which action starts each one, where its output lands, and what happens when a process ends.

## How do UI Flows, processes, and workflows fit together?

A UI Flow is the app shell the user navigates. It starts a **process** with the **Start Process** action or the **Process Renderer** component, and it calls a **workflow** directly with the **Start Workflow** action. A process calls a workflow with the **Start Integration Workflow** action and reads the result with a **Receive Message Task**.

Data travels forward through these hops, and comes back only from workflows. A workflow's output returns to whatever started it. A process's data never returns to the UI Flow that started it.

```mermaid theme={"dark"}
flowchart LR
    UF["UI Flow<br/>(screens and navigation)"]
    P["Process<br/>(stateful BPMN journey)"]
    W["Workflow<br/>(integrations and data)"]
    UF -- "Start Process action<br/>or Process Renderer" --> P
    UF -- "Start Workflow action<br/>(output merges into UI Flow data)" --> W
    P -- "Start Integration Workflow action<br/>(output returns via Receive Message Task)" --> W
```

The diagram shows three resources. A UI Flow points to a process (Start Process action or Process Renderer) and to a workflow (Start Workflow action). A process points to a workflow (Start Integration Workflow action). No arrow returns from the process to the UI Flow.

To decide which resource a piece of your app should be, see [Workflow, process, or UI Flow: which one do I use?](/5.9/docs/platform-deep-dive/integrations/integration-workflows#workflow-process-or-ui-flow-which-one-do-i-use) and [When to use UI Flows](/5.9/docs/building-blocks/ui-flows#when-to-use-ui-flows).

***

## What can start what?

| From | To | How | Where the result lands |
| - | - | - | - |
| UI Flow | Workflow | [Start Workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action) | Merged into the UI Flow's session data, so components bound to those keys update |
| UI Flow | Process | [Start Process action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-process-action) | The process replaces the UI Flow view. Process data stays in the process |
| UI Flow | Process | [Process Renderer component](/5.9/docs/building-blocks/ui-flows#process-renderer-component) (web only) | The process runs inside a UI Flow page or modal. Process data stays in the process |
| Process | Workflow | [Start Integration Workflow action](/5.9/docs/building-blocks/actions/start-integration-workflow) | Process data, at the keys mapped on the [Receive Message Task](/5.9/docs/building-blocks/node/message-send-received-task-node#receive-message-task) |
| Chat-driven workflow | UI Flow | [Navigate in UI Flow node](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node) | The destination page opens with the parameters the node passes |

The process only receives what you pass when you start it. The Start Process action (**Add start params**) and the Process Renderer (**Start Params**) each take a JSON object with `${key}` expressions, resolved from the UI Flow's data when the process starts. A process can't read any other UI Flow data.

> [!NOTE]
>
> **Add forms to validate** on a Start Process action only checks that the selected forms are valid before the process starts. It doesn't send their values. To pass a field value to the process, reference its key in the start parameters.

***

## What happens when a process started from a UI Flow ends?

On web, the UI Flow does not take back control when the process ends. With the Start Process action, the last process screen stays on display with its values cleared, and no process data is passed back to the UI Flow. The user returns to the UI Flow page with the browser back button, and the page shows the UI Flow data as they left it.

Design for this when a UI Flow starts a process:

* End the journey on a user task that confirms the outcome, and keep the user on it, rather than relying on the process end to move the user on.
* Save anything the UI Flow needs to show later (an application status, a reference number) somewhere the UI Flow can load it, for example with a workflow on the page's On Load event.
* When the process runs in a Process Renderer, browser back and breadcrumb navigation follow the rules in [Process Renderer navigation behavior](/5.9/docs/building-blocks/ui-flows#navigation-behavior).

Newer releases add configurable actions that run when a Process Renderer's process ends. See [Process end handling](/5.9/docs/building-blocks/ui-flows#process-end-handling) for availability.

***

## Example: a loan portal that starts a process, which calls a workflow

Acme Bank builds a loan portal in three pieces:

* **LoanPortal** (UI Flow): a home page with a form for **Loan amount** and **Term (months)**, and an **Apply** button.
* **loanApplication** (process): Start → Init Data → Calculate estimate → Receive estimate → Review estimate → End.
* **calculateLoanEstimate** (workflow): takes an amount and a term and returns the monthly payment and total repayment. It's the workflow built in [Build your first UI Flow](/5.9/docs/getting-started/building-your-first-ui-flow).

**1. The UI Flow starts the process**

The **Apply** button has a **Start Process** action that selects `loanApplication`, adds the form under **Add forms to validate**, and passes the two form values under **Add start params**:

```json theme={"dark"}
{
  "application": {
    "amount": ${loanAmount},
    "termMonths": ${termMonths}
  }
}
```

![Start Process event handler on the Apply button: Process set to loanApplication, Add forms to validate set to applyForm, and Add start params passing loanAmount and termMonths](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/comp-start-process-handler.png)

Clicking **Apply** with empty fields shows the form's required-field messages and starts nothing. With valid values, the process replaces the UI Flow view.

**2. The process calls the workflow**

The **Calculate estimate** node has a **Start Integration Workflow** action that starts `calculateLoanEstimate` with the amount and term from `application`. The **Receive estimate** node is a Receive Message Task that maps the workflow output into the process data.

**3. The process shows the result**

The **Review estimate** user task displays the mapped values. For 25,000 over 60 months, it shows a monthly payment of 489.15 and a total repayment of 29349.22.

![The loanApplication process running in place of the LoanPortal UI Flow, showing a monthly payment of 489.15, a total repayment of 29349.22, and a Submit application button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/comp-process-in-ui-flow.png)

**4. The process ends**

**Submit application** completes the user task and the process reaches its End node. The review screen stays on display with its values cleared. Browser back returns the user to the LoanPortal home page, with the form values still filled in.

If the portal only needed to show the estimate, without a review step or any state to keep, the **Apply** button could call `calculateLoanEstimate` with a **Start Workflow** action instead, and the result would land directly in the UI Flow's data. That's the pattern [Build your first UI Flow](/5.9/docs/getting-started/building-your-first-ui-flow) uses.

***

## Related resources

> [card] [UI Flows](/5.9/docs/building-blocks/ui-flows)
>
> Start Process, Start Workflow, and Process Renderer configuration

> [card] [Start integration workflow action](/5.9/docs/building-blocks/actions/start-integration-workflow)
>
> Call a workflow from a process and receive its output

> [card] [Build your first UI Flow](/5.9/docs/getting-started/building-your-first-ui-flow)
>
> A UI Flow that calls a workflow directly

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Build the workflows that UI Flows and processes call


# Project data model
Source: https://docs.flowx.ai/5.9/docs/building-blocks/project-data-model

Define reusable data types at the project level to ensure consistency across processes

## What is a project data model?

![Project Data Model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)

The Project Data Model (PDM) lets you define reusable data types at the project level. These data types propagate to the process data models, ensuring data consistency across your FlowX.AI applications, including in Reusable Functions, Persistence Layer schemas, and other components.

With PDM, you create a centralized data structure that serves as the foundation for all processes within your project. This ensures that core data types like Customer, Product, or Document maintain consistent definitions throughout your application.

![Project Data Model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_process.png)

## Key concepts

> [tab] Data Model Types
>
> FlowX.AI supports several data model layers, each serving different purposes:
>
> | Data Model Layer | Description |
> | - | - |
> | Process Data Model | Can use data types defined in the Project Data Model or Library Data Model. |
> | Project Data Model (PDM) | Defines data types that can be reused across processes and other resources within the project |
> | Library Data Model | Defined within a library. Allows data types to be reused across multiple projects, promoting standardization. |
>
> ![Data Model Types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_process.png)

> [tab] Data Types & Attributes
>
> A **data type** defines the structure of a particular set of data. For example, a `Customer` data type might contain attributes like `name`, `email`, and `address`.
>
> An **attribute** is an individual property of a data type that specifies its data structure.
>
> Data types and attributes can be categorized based on their usage:
>
> * **Used/Unused**: A data type or attribute is considered "used" when it's incorporated into the structure of another data type.
> * **Referenced/Unreferenced**: Refers to data types or attributes from the Project Data Model being used within a Process Data Model or a UI Template.
>
> ![PDM usage](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_usage.gif)

## Benefits of project data model

> [card] Consistency
>
> Ensures data structure consistency across multiple processes and resources

> [card] Reusability
>
> Define once, use many times across processes, business rules, and other components

> [card] Efficiency
>
> Reduces development time by eliminating duplicate definitions

> [card] Maintainability
>
> Centralized management of data structures

> [card] Standardization
>
> Promotes the use of common data structures across projects

## How to use the project data model

### Access the project data model

**1. Open FlowX.AI Designer**

Open FlowX.AI Designer.

**2. Navigate to your project**

Select the project where you want to configure the Project Data Model.

**3. Select Data Model**

Select "Project Data Model" from the project menu.

![Project Data Model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/where_to_find_pdm.png)

### Define a project data model

**1. Add a new data type**

In the Project Data Model view, click **+** to add a new data type. A confirmation toast notifies you when the data type is created.

![Add data type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_new_data_type.png)

**2. Name the data type**

Provide a name for the data type.

**3. Add attributes**

Each data type displays an **Add attribute** button for creating the first attribute. After the first attribute exists, the button appears only on hover over the data type.

When you select an attribute, a **settings side panel** opens on the right where you can configure:

* Attribute name and type (string, number, boolean, object, array, enum)
* Validations, sensitive data, and reporting settings
* Example values for data mapping

![Add attributes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_attributes.png)

### Manage data types

#### Add a data type

1. Click **+** in the Data Types panel.
2. Enter the name and properties of the data type.
3. Use the inline **Add attribute** button on the data type to add attributes.
4. Save changes.

### Edit a data type

**1. Select the data type**

Select the data type in the Project Data Model.

**2. Select an attribute**

Click an attribute to open the **settings side panel** on the right with all configuration options.

**3. Edit the attribute**

Edit the attribute settings as needed. Changes are saved automatically.

## Attribute validations

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

You can attach validation rules to a data model attribute so that the values held by that attribute follow the constraints you define. Validators are set per attribute from the attribute **settings side panel**, and they travel with the data model wherever it is used, including process data models, reusable functions, and reusable UI templates.

> [!NOTE]
>
> These validators are defined on the **data model attribute** itself. They are different from the [UI Designer validators](./ui-designer/validators), which are configured on individual form components inside a UI template.

### Add a validator

**1. Select an attribute**

In the Project Data Model, select an attribute to open the **settings side panel** on the right.

**2. Open the Validations section**

In the side panel, expand the **Validations** section and click **Add validator**.

**3. Choose a validator type**

Select a validator type. Only the validator types that apply to the attribute's type are listed (see [Available validators by attribute type](#available-validators-by-attribute-type)).

**4. Enter a value**

Enter the value the validator checks against. Required field and Email Format take no value; every other validator type takes one. For a date attribute, the Min Date and Max Date values are picked from a date picker.

**5. Save the validator**

Save the validator. It appears in the Validations list for the attribute. Changes to the data model are saved automatically.

> [!NOTE]
>
> You can add at most one validator of each type to an attribute. A type that is already applied no longer appears in the validator list.

### Available validators by attribute type

The validator types offered depend on the attribute's type. Required field is available for every type.

| Attribute type | Available validators |
| - | - |
| String | Required field, Min Length, Max Length, Pattern, Email Format |
| Number | Required field, Min Value, Max Value |
| Boolean | Required field |
| Date | Required field, Min Date, Max Date |
| Enum | Required field |
| Array | Required field, Min Items, Max Items |
| Object | Required field |
| Currency | Required field, Min Amount Value, Max Amount Value, Min Code Length, Max Code Length, Code Pattern (regex) |

> [!NOTE]
>
> For a currency attribute, the Min Amount Value and Max Amount Value validators apply to the amount, while Min Code Length, Max Code Length, and Code Pattern (regex) apply to the currency code.

### What each validator checks

> [accordion] Required field
>
> Requires the attribute to hold a value. Takes no value of its own.

> [accordion] Min Length / Max Length
>
> Sets the minimum or maximum number of characters for a string value. For a currency attribute these apply to the currency code and are labeled **Min Code Length** and **Max Code Length**. The configured limit is shown as a number of characters, for example `3 characters`.

> [accordion] Min Value / Max Value
>
> Sets the lower or upper bound for a numeric value. For a date attribute these are labeled **Min Date** and **Max Date** and the bound is entered as a date. For a currency attribute these are labeled **Min Amount Value** and **Max Amount Value** and the bound is displayed together with the attribute's currency code, for example `100 EUR`.

> [accordion] Pattern
>
> Checks a string value against a regular expression. For a currency attribute this is labeled **Code Pattern (regex)** and validates the currency code.

> [accordion] Email Format
>
> Checks that a string value is a valid email address. Takes no value of its own.

> [accordion] Min Items / Max Items
>
> Sets the minimum or maximum number of items for an array attribute.

> [!WARNING]
>
> When you change an attribute's type, every validator except **Required field** is removed automatically, because the other validators may no longer apply to the new type. Re-add the validators you need after changing the type.

***

### Attribute path

Each attribute displays a **path button** next to its name. Click it to view the full key path and copy it to your clipboard. This is useful when referencing keys in business rules, UI component bindings, or integration mappings.

> [!NOTE]
>
> Changes to data types propagate to all processes referencing them. If a process is using this data type, it will automatically get the updated structure.
>
> > [!WARNING]
> >
> > However, changes do NOT propagate to UI Designer paths, which will need to be adjusted manually.
>
> <video />

### Remove a data type

**1. Select the data type**

Select the data type to remove.

> [!NOTE]
>
> You can either delete an entire object or just a single attribute.

![Delete data type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/remove_dm_obj.png)

**2. Click remove**

Click the remove button.

**3. Confirm deletion**

You can delete the data type even if it's in use. The system will show you a warning message indicating which processes reference the data type.

> [!WARNING]
>
> If the data type is in use by processes, you will receive a warning message showing which processes reference it. You can still proceed with the deletion, but this may affect the referenced processes.
>
> ![Delete data type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_delete.png)

### Working with referenced data types

When a data type from the Project Data Model is used in a Process Data Model:

1. The Process Data Model will display the referenced data type.
2. The referenced data type cannot be modified at the process level.
3. Changes to the data type in the Project Data Model will propagate to all referencing processes.

## Common scenarios

> [tab] Edit a Key
>
> **1. Access PDM**
>
> Navigate to the Project Data Model.
>
> **2. Make changes**
>
> Make changes to an existing key or attribute.
>
> **3. Propagation**
>
> The changes automatically propagate to all processes using that key.
>
> **4. Updates**
>
> Referenced components in processes will be updated to reflect the changes, but UI Designer paths require manual adjustment.

> [tab] Remove a Key
>
> **1. Access PDM**
>
> Navigate to the Project Data Model.
>
> **2. Remove key**
>
> Attempt to remove a key or object.
>
> **3. System check**
>
> System checks if the key is in use by any process.
>
> **4. Result**
>
> A warning modal shows references but allows deletion.

> [tab] Change Type
>
> **1. Access PDM**
>
> Navigate to the Project Data Model.
>
> **2. Change type**
>
> Change the type of an attribute (e.g., from string to boolean).
>
> **3. Confirmation**
>
> System will prompt for confirmation as this might break processes.
>
> **4. Result**
>
> **Incompatible change**: References will be broken and removed from UI templates.
>
> **Compatible change**: No changes to references are required.

### Use the Project Data Model in processes

1. Navigate to a process within your project.
2. Open the Process Data Model.
3. Project data types are available for selection.
4. Select the desired project data type to use in your process.
5. The data type is added to your Process Data Model, maintaining reference to the Project Data Model.

### Work with libraries

![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/library_pdm.png)

#### Integrate Library Data Models

1. Navigate to your project dependencies.
2. Add a library as a dependency. The library must have a build created.

![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/lib_pdm_dependency.png)

3. Library data types become available in your Project Data Model.

> [!WARNING]
>
> Library data types are not visible by default! You must select the library source in the filter to display them.

> [!TIP]
>
> To filter by library types you can use the "Filter by source" feature.
>
> ![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_lib_filter.png)

4. You can now use the library data types in your data model.

![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/lib_pdm_flow.gif)

#### Handle duplicate types from libraries

When multiple libraries contain data types with the same name:

1. Both types will be visible in the Project Data Model with visual indicators.
2. Namespacing functionality will prevent technical issues.

![Library PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/lib_multiple.png)

## Configure reporting and sensitive data settings

You can configure reporting and sensitive data settings directly from the attribute settings side panel:

1. Go to the Project Data Model.
2. Select an attribute to open the **settings side panel**.
3. Toggle **Sensitive data** or **Use in Reporting** as needed.

![Reporting Sensitive](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_reporting_sensitive.png)

> [!NOTE]
>
> These settings apply to all instances of the attribute across processes.

> [!TIP]
>
> You can also access these settings from the three-dots menu in the upper right corner of the side panel → **Show details**.

## Project Data Model after version commitment

After committing a project version:

1. The Project Data Model becomes read-only.
2. You can still view the diagram and monitor usage.
3. This read-only configuration is available for any configuration on committed versions and applies also to resource data models.

![PDM after version commitment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_read_only.png)

3. To make changes to the data model, you will require a new project version.

![PDM after version commitment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_new_version.png)

## Search and filter

The Project Data Model interface provides tools to help you find and work with your data types:

1. Navigate to the Project Data Model.
2. By default, only project-level types are displayed.
3. Use filters to view library types as well.
4. Use the search function to find specific types by name.

## Update library dependencies

When updating library dependencies:

1. Navigate to the dependencies section.
2. Select the new library version.
3. The system will inform you of any breaking changes to data types.
4. You can decide whether to proceed with the update.
5. If you proceed, changes will propagate to processes according to compatibility rules.

## Real-world example: Insurance claims processing

> [!NOTE]
>
> This example demonstrates how an insurance company uses project data model for their claims processing system.

> [accordion] Core data types in PDM
>
> The insurance company created these data types in their Project Data Model:
>
> ![Insurance PDM](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example2.png)
>
> 1. **Customer**
>    * `customerId`: string
>    * `firstName`: string
>    * `lastName`: string
>    * `dateOfBirth`: date
>    * `contactInformation`: ContactInfo (reference)
>    * `policyNumbers`: array of string
>    * `customerSince`: date
>    * `riskProfile`: RiskProfile (reference)
>    * *Settings*: Sensitive data = True, Used in reporting = True
> 2. **ContactInfo**
>    * `email`: string
>    * `phone`: string
>    * `address`: Address (reference)
>    * *Settings*: Sensitive data = True, Used in reporting = False
> 3. **Claim**
>    * `claimId`: string
>    * `policyNumber`: string (reference to Policy)
>    * `claimType`: enum \["Auto", "Property", "Medical", "Liability"]
>    * `incidentDate`: date
>    * `reportedDate`: date
>    * `status`: enum \["New", "Under Review", "Pending Documents", "Approved", "Denied", "Closed"]
>    * `estimatedAmount`: number
>    * `approvedAmount`: number
>    * `documents`: array of Document (reference)
>    * *Settings*: Sensitive data = False, Used in reporting = True
> 4. **Document**
>    * `documentId`: string
>    * `documentType`: string
>    * `fileName`: string
>    * `fileUrl`: string
>    * `uploadDate`: date
>    * *Settings*: Sensitive data = False, Used in reporting = False

> [accordion] Process-specific data models
>
> The company created multiple processes using the PDM:
>
> > [tab] Auto Claim Processing
> >
> > **Root**: ClaimProcess
> >
> > ![Auto Claim Processing](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> >
> > **Data Structure**:
> >
> > * **ClaimProcess** (Process-specific type)
> >   * `claim`: Claim (reference from PDM)
> >   * `assignedAdjuster`: string
> >   * `vehicleInfo`: AutoClaimDetails (reference)
> >   * `processingStage`: enum \["Initial Review", "Damage Assessment", "Liability Determination", "Settlement Negotiation", "Payment Processing"]
> > * **AutoClaimDetails** (Process-specific type)
> >   * `vehicleMake`: string
> >   * `vehicleModel`: string
> >   * `vehicleYear`: number
> >   * `vin`: string
> >   * `accidentLocation`: Address (reference from PDM)
> >   * `damageDescription`: string
>
> > [tab] Policy Renewal Process
> >
> > **Root**: RenewalProcess
> >
> > ![Policy Renewal Process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example3.png)
> >
> > **Data Structure**:
> >
> > * **RenewalProcess** (Process-specific type)
> >   * `customer`: Customer (reference from PDM)
> >   * `renewalDate`: date
> >   * `premiumChange`: number
> >   * `renewalStatus`: enum \["Pending Review", "Offer Generated", "Offer Sent", "Accepted", "Declined", "Expired"]

> [accordion] Example use cases
>
> > [tab] Add an attribute
> >
> > <video />
> >
> > 1. A configurator adds a new attribute `loyaltyTier` to the Customer data type in the PDM.
> > 2. This attribute is an enum \["Bronze", "Silver", "Gold", "Platinum"].
> > 3. The new attribute automatically propagates to all processes using the Customer data type.
> > 4. The Policy Renewal Process now has access to the customer's loyalty tier without any process-level changes.
>
> > [tab] Remove a field
> >
> > ![Remove field warning](https://mintlify.s3.us-west-1.amazonaws.com/flowxai/images/pdm-remove-warning.png)
> >
> > Warning when trying to remove a field in use
> >
> > 1. A configurator tries to remove the `contactInformation` attribute from the Customer data type.
> > 2. The system displays a warning that the attribute is in use by multiple processes.
> > 3. The configurator is prevented from making the change until the references are resolved.
>
> > [tab] Library integration
> >
> > ![Library integration](https://mintlify.s3.us-west-1.amazonaws.com/flowxai/images/pdm-library-integration.png)
> >
> > Using a library-defined Vehicle data type
> >
> > 1. The company uses a "Common Insurance Standards" library with standardized data types.
> > 2. After setting the library as a dependency, they can use the library's "Vehicle" data type in their PDM.
> > 3. When the library updates, the configurator can choose to adopt the changes.

> [accordion] Benefits demonstrated
>
> > [card]
> >
> > This example shows how the Project Data Model:
> >
> > * **Ensures data consistency**: Core entities like Customer and Policy maintain consistent structures across all processes and resources.
> > * **Promotes reusability**: Common data types are defined once and reused in in multiple processes, business rules, and other resources.
> > * **Simplifies changes**: Updates to data types are propagated automatically to all processes.
> > * **Enforces governance**: Sensitive data is marked at the project level for consistent handling.
> > * **Allows flexibility**: Process-specific data can extend the PDM while maintaining core data integrity.

## Export and import

You can export and import project data types to transfer them between projects or environments.

### Exporting

To export project data types:

1. Open the context menu on the Project Data Model page
2. Select **Export**
3. The data types are downloaded as a ZIP file

### Importing

To import project data types:

1. Open the context menu on the Project Data Model page
2. Select **Import**
3. Select the ZIP file exported from another project or environment
4. If data types with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting data type (or use **Apply to all**):
   * **Keep both** - imports the data type as a new copy alongside the existing one
   * **Replace** - overwrites the existing data type with the imported version
   * **Skip this one** - keeps the existing data type unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

***

## Best practices

> [!TIP]
>
> **Plan before implementation**: Design your Project Data Model before creating processes to ensure consistency.

> [!TIP]
>
> **Always provide example values**: Example values will be used in data mapping and other operations.

> [!TIP]
>
> **Use descriptive names**: Choose clear, descriptive names for data types and attributes.

> [!TIP]
>
> **Document your model**: Add descriptions to data types and attributes for better understanding and for AI agents.

> [!TIP]
>
> **Consider reusability**: Design data types with reusability in mind across processes and resources.

> [!TIP]
>
> **Review impact of changes**: Before modifying data types, check their usage across processes.

> [!TIP]
>
> **Use libraries for cross-project standards**: For data types needed across multiple projects, define them in libraries.

> [!TIP]
>
> **Maintain regularly**: Periodically review and clean up unused data types.

## Limitations

**Current limitations of the Project Data Model**

> [!WARNING]
>
> Custom Data Types from the Project or Library Data Model level cannot be modified at the resource level.

> [!WARNING]
>
> Removing or changing Data Types in use may break resources using it.

> [!WARNING]
>
> Project Data Model becomes read-only after version commitment. This is available for any configuration on commited versions; it applies also for resources data models.

> [!WARNING]
>
> Library builds with breaking changes to Data Types require usage review.

> [!NOTE]
>
> Data Types defined at the Project or Library level can be referenced in the data models of Processes, Reusable Functions, and Reusable UI Templates.

## Troubleshooting

> [accordion] Cannot modify a referenced data type in process
>
> **1. Problem**
>
> You're trying to edit a data type from the PDM within a process, but the fields are read-only.
>
> **2. Solution**
>
> Make changes at the project level instead:
>
> 1. Navigate to the Project Data Model
> 2. Locate and edit the data type
> 3. Save changes
> 4. The changes will propagate to all processes

> [accordion] Cannot delete a data type that is in use
>
> **1. Problem**
>
> You're trying to delete a data type, but receive an error that it's in use.
>
> **2. Solution**
>
> Either:
>
> * Remove all references to the data type first
> * Create a new version of your project to make the change

> [accordion] References broken after type change
>
> **1. Problem**
>
> After changing a data type (e.g., from string to number), references are broken in processes.
>
> **2. Solution**
>
> Review affected processes and update references manually:
>
> 1. Check the warning message that lists affected processes
> 2. Open each process
> 3. Update UI templates or other components that referenced the changed attribute

> [accordion] Library update warning about breaking changes
>
> **1. Problem**
>
> When updating a library dependency, you receive warnings about breaking changes to data types.
>
> **2. Solution**
>
> Carefully review the changes and their impact before proceeding:
>
> 1. Check which data types are affected
> 2. Review how these types are used in your processes
> 3. Decide whether to proceed with the update or maintain the current version

***

## Academy courses

> [card] [Data Model 101 course](https://academy.flowx.ai/explore/data-model-101-0)
>
> Learn attribute types, JSON format, and data modeling fundamentals

> [card] [Handle Dynamic Data course](https://academy.flowx.ai/explore/handle-dynamic-data-flowxai)
>
> Configure dynamic dropdowns and data-driven UI from process data


# Custom Components
Source: https://docs.flowx.ai/5.9/docs/building-blocks/reusable-resources/custom-components

Create custom React components that integrate with FlowX process data and actions, extending the built-in component palette with your own UI elements.

## What are Custom Components?

Custom Components are developer-defined React components that you create in FlowX Designer and reference in UI Flows. Unlike [Reusable UI Templates](./reusable-ui) which use the visual component builder, Custom Components let you write actual React code to build complex, interactive UI elements.

> [card] Code-based
>
> Write React TypeScript/JavaScript directly in the Designer code editor

> [card] Data-connected
>
> Receive process data through input keys and trigger process actions

> [card] Reusable
>
> Define once in Reusable Resources, use across multiple User Tasks

> [card] Import/Export
>
> Export as ZIP and import into other projects

***

## When to use Custom Components

| Use case | Recommended approach |
| - | - |
| Standard forms, layouts, navigation | Built-in components or [Reusable UI Templates](./reusable-ui) |
| Complex interactive widgets (charts, maps, custom inputs) | **Custom Components** |
| Third-party library integration | **Custom Components** |
| Custom business logic in the UI | **Custom Components** + [Reusable Functions](./reusable-functions) |
| Reusable visual patterns without code | [Reusable UI Templates](./reusable-ui) |

***

## Creating a Custom Component

Custom Components are managed under **Reusable Resources** in your project.

**1. Navigate to Custom Components**

In the Designer, open your project and go to **Reusable Resources** → **Custom Components**.

**2. Create a new component**

Click the **+** button to create a new Custom Component. Fill in the creation modal:

![Create Custom Component modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)

| Field | Description |
| - | - |
| **Name** | Display name for the component |
| **Unique Identifier** | A unique string identifier used to reference the component in UI Flows |
| **Platform** | **Web** or **Mobile** |
| **Description** | Optional description of the component's purpose |

**3. Write your component code**

The component editor has three panels:

* **Source Files** (left) — a file tree with your component's JSX, CSS, and `package.json`
* **Code editor** (right) — edit the selected file
* **Dependencies** (bottom-left) — lists available packages

Each component is scaffolded with:

* `identifier.jsx` — your React component code
* `identifier.css` — component styles
* `package.json` — dependency declarations

**Available dependencies:**

| Package | Version | Purpose |
| - | - | - |
| `react` | 18.3.1 | Core React library |
| `react-dom` | 18.3.1 | DOM rendering |
| `@emotion/css` | 11.13.5 | CSS-in-JS styling |
| `lodash` | 4.17.21 | Utility functions |
| `axios` | 1.13.2 | HTTP requests |
| `date-fns` | 2.30.0 | Date manipulation |

**4. Configure input keys**

Define **Input Keys** to specify which process data paths the component receives. These map process data model attributes to the component's `data` prop.

For example, if your process data model has `application.metrics.revenue`, add it as an input key. The component receives it as `data['application.metrics.revenue']`.

**5. Test and save**

Use the **Test** button to preview your component with sample data. Click **Save** to persist your changes.

You can also test end-to-end by starting a UI Flow that includes the component.

***

## Using Custom Components in UI Flows

Once defined, Custom Components can be added to User Tasks in your UI Flows.

**1. Add to a User Task**

In the UI Designer, drag a **Custom Component** element from the component palette into your User Task layout.

**2. Select the component**

In the properties panel, select your Custom Component by its **Identifier** (e.g., `MyCustomChart`).

**3. Map input keys**

Configure which process data paths are passed to the component. Use data model paths like `${application.user.profile}` to bind process data.

![Custom Component parameters configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/custom_comps_params.png)

**4. Connect event handlers**

If your component triggers actions (e.g., button clicks), connect them to process actions defined on the User Task node.

***

## Using Custom Components in Process User Tasks

The Process User Task host follows the same drag-and-drop authoring flow as UI Flows, with one extra concept: every Custom Component declares its own data model, kept distinct from process data so the component contract stays explicit at each use site.

**1. Drop the Custom Component onto a User Task**

In the Designer, open a Process and select a User Task node. From the component palette, drag the **Custom Component** element into the User Task layout, and pick your component by its identifier.

**2. Configure INPUT mappings**

On the Custom Component's properties panel, define how process data flows into the component. Map process attributes onto the slots declared on the component's input data model. The React SDK applies these mappings at runtime and the component receives only the data it declared.

**3. Configure OUTPUT mappings**

For components that trigger actions, define how the component's `saveData` is remapped back to process variables. The React SDK applies the OUTPUT mappings before the action's `saveData` is piped into the process state.

INPUT and OUTPUT mappings appear only when the component's **Type** is **Bundled** on the Web platform. With **Type** set to **Self-Managed**, and on Android and iOS, the properties panel shows **Identifier**, **Input Keys**, and **Event handlers** instead.

**4. Connect process actions**

Wire component-triggered actions to the actions defined on the User Task node, the same way you do for built-in components.

> [!TIP]
>
> The Custom Component editor lets you fill input parameters with sample data and preview the component without leaving the Designer. The same flow works for components that target both UI Flows and Process User Tasks.

> [!NOTE]
>
> Custom Components in Process User Tasks are rendered by the React SDK only, starting with 5.8.0. The Phase 1 React-only limitation in the section below still applies: there is no Angular SDK support for Custom Components yet.

***

## Example: Onboarding checklist

A progress tracker that displays a list of onboarding steps with completion status, driven by process data.

![Onboarding checklist custom component rendered output](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_output_custom_component.png)

> [tab] identifier.jsx
>
> ```jsx theme={"dark"}
> import React from "react";
>
> export default function OnboardingChecklist({ input }) {
>   const steps = input?.data || [];
>   const completed = steps.filter((s) => s.completed).length;
>   const total = steps.length;
>   const pct = total > 0 ? Math.round((completed / total) * 100) : 0;
>
>   return (
>     <div className="obc-root">
>       <div className="obc-header">
>         <span className="obc-title">Onboarding progress</span>
>         <span className="obc-pct">{pct}%</span>
>       </div>
>       <div className="obc-bar-track">
>         <div className="obc-bar-fill" style={{ width: `${pct}%` }} />
>       </div>
>       <ul className="obc-list">
>         {steps.map((step, i) => (
>           <li key={i} className={`obc-step ${step.completed ? "obc-done" : ""}`}>
>             <span className="obc-icon">{step.completed ? "✓" : "○"}</span>
>             <span>{step.label}</span>
>           </li>
>         ))}
>       </ul>
>     </div>
>   );
> }
> ```

> [tab] identifier.css
>
> ```css theme={"dark"}
> .obc-root {
>   font-family: sans-serif;
>   padding: 20px;
>   border: 1px solid #e2e8f0;
>   border-radius: 12px;
> }
>
> .obc-header {
>   display: flex;
>   justify-content: space-between;
>   margin-bottom: 8px;
> }
>
> .obc-title {
>   font-weight: 600;
>   font-size: 14px;
>   color: #1e293b;
> }
>
> .obc-pct {
>   font-weight: 600;
>   font-size: 14px;
>   color: #10b981;
> }
>
> .obc-bar-track {
>   height: 6px;
>   background: #f1f5f9;
>   border-radius: 3px;
>   margin-bottom: 16px;
> }
>
> .obc-bar-fill {
>   height: 100%;
>   background: #10b981;
>   border-radius: 3px;
>   transition: width 0.3s ease;
> }
>
> .obc-list {
>   list-style: none;
>   margin: 0;
>   padding: 0;
> }
>
> .obc-step {
>   display: flex;
>   align-items: center;
>   gap: 10px;
>   padding: 8px 0;
>   font-size: 14px;
>   color: #94a3b8;
> }
>
> .obc-step.obc-done {
>   color: #1e293b;
> }
>
> .obc-icon {
>   width: 20px;
>   text-align: center;
>   font-size: 14px;
> }
>
> .obc-step.obc-done .obc-icon {
>   color: #10b981;
>   font-weight: 700;
> }
> ```

> [tab] Sample data
>
> The component's `input.data` expects an array of step objects:
>
> ```json theme={"dark"}
> [
>   { "label": "Verify email address", "completed": true },
>   { "label": "Complete personal details", "completed": true },
>   { "label": "Upload ID document", "completed": false },
>   { "label": "Sign agreement", "completed": false },
>   { "label": "First deposit", "completed": false }
> ]
> ```

### Key patterns in this example

| Pattern | How it's used |
| - | - |
| **Guard against undefined** | `input?.data \|\| []` prevents errors before process data loads |
| **Scoped CSS** | All classes prefixed with `obc-` to avoid style conflicts |
| **No CSS import** | The CSS file is loaded automatically by the runtime |
| **Derived state** | Progress percentage calculated from the data, not stored separately |
| **Minimal dependencies** | Only React — no additional packages needed |

> [!TIP]
>
> **Generating components with AI:** You can use the following prompt template to generate Custom Components with an AI assistant:
>
> *"Create a simple react component as a widget that \[description]. Rules: one jsx file + one css file, scoped CSS (no global styles), don't import the CSS file, contain dimensions, keep it simple. The component receives an `input` prop with a `data` property (initial value is undefined, guard against it). The data value should \[describe the shape]. Output a JSON dependencies list (ignoring react, @emotion/css, lodash, axios, date-fns)."*

***

## Component API reference

Custom Components receive the following props:

| Prop | Type | Description |
| - | - | - |
| `data` | `Record<string, any>` | Process data mapped through the configured input keys |
| `actions` | `ProcessAction[]` | List of available process actions |
| `actionsFn` | `Record<string, () => Observable>` | Bound action functions keyed by action name |

> [!NOTE]
>
> Custom Components run in the React SDK runtime. They have access to standard React APIs and a set of pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Custom npm packages cannot be added in Phase 1.

***

## Import and export

Custom Components support the standard FlowX import/export workflow:

* **Export**: Select components and export as a ZIP file
* **Import**: Import ZIP files into other projects
* **Conflict resolution**: When importing, choose to **Keep both**, **Replace**, or **Skip** for each component

***

## Permissions

Custom Components are controlled by the `CUSTOM_COMPONENT` resource type in the authorization system.

| Permission | Description |
| - | - |
| `CUSTOM_COMPONENT` read | View custom components in a project |
| `CUSTOM_COMPONENT` write | Create and edit custom components |
| `CUSTOM_COMPONENT` delete | Delete custom components |
| Import/Export | Requires standard resource import/export permissions |

By default, the **Project Owner** role has full Custom Component permissions.

***

## Limitations (Phase 1)

> [!WARNING]
>
> Phase 1 limitations — these will be addressed in future releases:
>
> * **React only** — Custom Components are not supported in Angular SDK
> * **Pre-defined dependencies** — A curated set of packages is available (React, Emotion, Lodash, Axios, date-fns). Custom npm packages cannot be added in Phase 1.
> * **Browser-side bundling** — Components are bundled in the browser, which limits complexity
> * **No server-side rendering** — Components render client-side only

***

## Related resources

> [card] [Reusable UI Templates](./reusable-ui)
>
> Visual, no-code reusable UI patterns

> [card] [Reusable Functions](./reusable-functions)
>
> Reusable business logic functions

> [card] [UI Flows](../ui-flows)
>
> Building user interfaces with FlowX

> [card] [Event Handlers](../ui-designer/event-handlers)
>
> Configuring event handlers on components


# Reusable Functions
Source: https://docs.flowx.ai/5.9/docs/building-blocks/reusable-resources/reusable-functions

Create and manage business logic components that can be reused across multiple processes in your FlowX.AI applications.

![Reusable Functions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr4.png)

## What are Reusable Functions?

Reusable Functions are self-contained business logic components that process data according to your specified rules. Instead of writing the same logic multiple times across different processes, you can:

* Define the logic once in a reusable function
* Use the function in multiple processes through data mapping
* Automatically propagate updates to all instances when you modify the function

> [!NOTE]
>
> Functions execute in isolated environments and cannot be edited within individual process contexts. All changes must be made to the original function definition.

### Script engine per function

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1.** Each reusable function can run on either the current **native** script engine (the 5.9 default) or the legacy **GraalVM** engine, selected per function. Functions created before the move to native keep running on GraalVM until you switch them over; new functions run on native by default. See [Script engine per rule](../actions/business-rule-action/business-rule-action#script-engine-per-rule).

> [!WARNING]
>
> **A function runs on the engine of the business rule that calls it.** The per-function selection applies when you test the function on its own. When a process runs, the function executes on the engine selected for the calling rule, so the function's code must be valid on that engine.
>
> Mixing engines is not supported: a function written for GraalVM that is called from a rule running on native fails at runtime. Keep a function and every rule that calls it on the same engine, or write the function so that it runs on both.

## Key benefits

> [card] Reduce duplication
>
> Write business logic once and reuse it across multiple processes

> [card] Improve maintainability
>
> Update logic in one place and automatically apply changes everywhere

> [card] Ensure consistency
>
> Standardize business rules across your entire application

> [card] Increase efficiency
>
> Spend less time rewriting similar logic for different processes

## Before you begin

Make sure you have:

* Access to the FlowX.AI Designer
* Appropriate permissions to create and manage reusable resources
* A clear understanding of the business logic you want to implement

## Create a reusable function

**1. Access the Functions section**

1. In FlowX.AI Designer, go to your project
2. Navigate to **Reusable Resources** > **Functions**
3. Click the **+** icon to create a new function

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr3.png)

**2. Configure basic settings**

1. Enter a descriptive name for your function
2. Add an optional description explaining the function's purpose
3. Click **Save** to create the function and open the editor

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr5.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr6.png)

**3. Define the data model**

1. Go to the **Model** tab
2. Add attributes that your function will work with:
   * Click **Add Attribute** to create new fields
   * Set attribute types by selecting existing objects from your project
   * Define nested structures as needed

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr1.png)

> [!NOTE]
>
> Functions support both primitive data types (string, number, boolean) and complex object data types for input and output parameters. See [Understanding Data Types](#understanding-data-types) for more information.

> [!TIP]
>
> Define **both input and output fields** in your data model. Later, you'll select which fields are inputs (Input Parameters tab) and which are outputs (Output Parameters tab).

> [tab] getBasicFacts - Primitive
>
> **Primitive types only** — all fields are flat (string/number), no nesting. Use this pattern when your function takes a single input value and returns several scalar results.
>
> ```json theme={"dark"}
> {
>   "question": "string",
>   "universeAge": "number",
>   "galaxyCount": "number",
>   "speedOfLight": "number",
>   "explanation": "string"
> }
> ```
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr7.png)

> [tab] getUniverseOverview - Object
>
> **Object types with one level of nesting** — inputs and outputs are objects, each containing a small set of related fields. Use this pattern when your function takes structured query parameters and returns a structured result object.
>
> * **Inputs**: `query` (topic + detail level) and `user_preferences` (formatting options)
> * **Outputs**: `universe` (facts + composition) and `explanation` (summary + key facts)
>
> ```json theme={"dark"}
> {
>   "query": {
>     "topic": "string",
>     "detail_level": "string"
>   },
>   "user_preferences": {
>     "scientific_notation": "boolean",
>     "units": "string"
>   },
>   "universe": {
>     "basicFacts": {
>       "age": "number",
>       "galaxyCount": "number",
>       "starCount": "number"
>     },
>     "composition": {
>       "darkMatter": "number",
>       "darkEnergy": "number",
>       "ordinaryMatter": "number"
>     }
>   },
>   "explanation": {
>     "summary": "string",
>     "keyFacts": "array",
>     "confidence": "number"
>   }
> }
> ```
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr8.png)

> [tab] myFirstFunction - Complex
>
> **Deeply nested objects with multiple input groups** — inputs are split across three distinct objects (`request`, `user_context`, `constraints`), with `user_context` containing a nested `preferences` sub-object. Outputs include three separate result objects (`universe`, `timeline`, `explanation`). Use this pattern when you need to model richer context or pass multiple independent parameter groups to a single function.
>
> Compared to `getUniverseOverview`, this example shows: more input objects, deeper nesting (e.g. `user_context.preferences`), and more output fields covering a broader data structure.
>
> Comprehensive data model for explaining the universe:
>
> ```json theme={"dark"}
> {
>   "request": {
>     "topic": "string",
>     "scope": "string",
>     "scientific_level": "string"
>   },
>   "user_context": {
>     "background": "string",
>     "preferences": {
>       "include_equations": "boolean",
>       "visual_aids": "boolean"
>     }
>   },
>   "constraints": {
>     "max_length": "number",
>     "language": "string"
>   },
>   "universe": {
>     "fundamentalConstants": {
>       "speedOfLight": "number",
>       "gravitationalConstant": "number",
>       "hubbleConstant": "number"
>     },
>     "composition": {
>       "darkMatter": "number",
>       "darkEnergy": "number",
>       "ordinaryMatter": "number"
>     },
>     "structures": {
>       "galaxies": "number",
>       "stars": "number",
>       "planets": "number"
>     }
>   },
>   "timeline": {
>     "bigBang": "number",
>     "firstStars": "number",
>     "earthFormation": "number"
>   },
>   "explanation": {
>     "summary": "string",
>     "keyInsights": "array",
>     "confidence": "number"
>   }
> }
> ```

**4. Configure input parameters**

1. Switch to the **Input Parameters** tab
2. Select the fields from your data model that your function needs as input
3. Expand objects to choose specific properties

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rbr2.png)

> [tab] getBasicFacts - Input
>
> Select input fields from the data model for basic universe queries:
>
> ```json Input parameter selection from data model theme={"dark"}
> [
>   "question"
> ]
> ```
>
> From the data model fields:
>
> * ✅ **question** (string) - SELECT as input
> * ❌ **universeAge** (number) - Do NOT select (output only)
> * ❌ **galaxyCount** (number) - Do NOT select (output only)
> * ❌ **speedOfLight** (number) - Do NOT select (output only)
> * ❌ **explanation** (string) - Do NOT select (output only)
>
> Example input mapping from process:
>
> ```json theme={"dark"}
> {
>   "question": "processData.userQuery"
> }
> ```
>
> > [!NOTE]
> >
> > Select only the fields your function needs as input from the data model. The output fields will be selected in the Output Parameters tab.

> [tab] getUniverseOverview - Input
>
> Select input fields from the data model for detailed queries:
>
> ```json Input parameter selection from data model theme={"dark"}
> [
>   "query",
>   "user_preferences"
> ]
> ```
>
> From the data model fields:
>
> * ✅ **query** (object) - SELECT as input
> * ✅ **user\_preferences** (object) - SELECT as input
> * ❌ **universe** (object) - Do NOT select (output only)
> * ❌ **explanation** (object) - Do NOT select (output only)
>
> Example input mapping from process:
>
> ```json theme={"dark"}
> {
>   "query": "processData.universeQuery",
>   "user_preferences": "processData.userSettings"
> }
> ```
>
> > [!NOTE]
> >
> > Select the input objects from your data model. The function will use these to customize its output behavior.

> [tab] myFirstFunction - Input
>
> Select input fields from the data model for complex universe explanations:
>
> ```json Input parameter selection from data model theme={"dark"}
> [
>   "request",
>   "user_context", 
>   "constraints"
> ]
> ```
>
> From the data model fields:
>
> * ✅ **request** (object) - SELECT as input
> * ✅ **user\_context** (object) - SELECT as input
> * ✅ **constraints** (object) - SELECT as input
> * ❌ **universe** (object) - Do NOT select (output only)
> * ❌ **timeline** (object) - Do NOT select (output only)
> * ❌ **explanation** (object) - Do NOT select (output only)
>
> Example input mapping from process:
>
> ```json theme={"dark"}
> {
>   "request": "processData.universeRequest",
>   "user_context": "processData.userProfile",
>   "constraints": "processData.outputConstraints"
> }
> ```
>
> > [!NOTE]
> >
> > Select the input objects that control how the function behaves. The output objects will be configured in the Output Parameters tab.

> [!TIP]
>
> Define clear input contracts to make your functions truly reusable across different contexts. Match input complexity to function complexity.

**5. Set output parameters**

1. Go to the **Output Parameters** tab
2. Select the fields from your data model that the function returns
3. Choose individual fields or entire objects as needed

> [tab] getBasicFacts - Output
>
> Select output fields from the data model for basic universe facts:
>
> ```json Output parameter selection from data model theme={"dark"}
> [
>   "universeAge",
>   "galaxyCount", 
>   "speedOfLight",
>   "explanation"
> ]
> ```
>
> From the data model fields:
>
> * ❌ **question** (string) - Do NOT select (input only)
>
> * ✅ **universeAge** (number) - SELECT as output
>
> * ✅ **galaxyCount** (number) - SELECT as output
>
> * ✅ **speedOfLight** (number) - SELECT as output
>
> * ✅ **explanation** (string) - SELECT as output
>
> > [!NOTE]
> >
> > Select the fields that your function calculates and returns. These were the fields showing incorrectly in your Input Parameters tab.

> [tab] getUniverseOverview - Output
>
> Select output fields from the data model for detailed universe data:
>
> ```json Output parameter selection from data model theme={"dark"}
> [
>   "universe",
>   "universe.basicFacts",
>   "universe.composition",
>   "explanation",
>   "explanation.summary",
>   "explanation.keyFacts",
>   "explanation.confidence"
> ]
> ```
>
> From the data model fields:
>
> * ❌ **query** (object) - Do NOT select (input only)
>
> * ❌ **user\_preferences** (object) - Do NOT select (input only)
>
> * ✅ **universe** (object) - SELECT as output
>
> * ✅ **explanation** (object) - SELECT as output
>
> > [!NOTE]
> >
> > Select the objects that your function generates. You can choose entire objects or specific nested properties based on what your process needs.

> [tab] myFirstFunction - Output
>
> Select output fields from the data model for complete universe explanation:
>
> ```json Output parameter selection from data model theme={"dark"}
> [
>   "universe",
>   "universe.fundamentalConstants",
>   "universe.composition", 
>   "universe.structures",
>   "timeline",
>   "explanation",
>   "explanation.keyInsights"
> ]
> ```
>
> From the data model fields:
>
> * ❌ **request** (object) - Do NOT select (input only)
>
> * ❌ **user\_context** (object) - Do NOT select (input only)
>
> * ❌ **constraints** (object) - Do NOT select (input only)
>
> * ✅ **universe** (object) - SELECT as output
>
> * ✅ **timeline** (object) - SELECT as output
>
> * ✅ **explanation** (object) - SELECT as output
>
> > [!NOTE]
> >
> > Select the objects that contain the universe explanation results. You can choose entire objects or drill down to specific properties you need.

> [!TIP]
>
> You can select entire objects (like `universe`) or specific properties (like `universe.basicFacts.age`) depending on what your process needs.

**6. Implement the business logic**

1. Navigate to the **Script** tab
2. Choose your programming language (JavaScript or Python)
3. Write your business logic using the appropriate data format

> [tab] getBasicFacts - Primitive
>
> Simple function with basic universe facts:
>
> ```javascript getBasicFacts theme={"dark"}
> // Function format: functions.projectName.functionName(input)
> function functions.cosmos.getBasicFacts(question) {
>     // Access input parameter: input.question
>     const userQuestion = input.question || "What is the universe?";
>
>     // Basic universe facts
>     output.universeAge = 13.8; // billion years
>     output.galaxyCount = 2000; // billion galaxies
>     output.speedOfLight = 299792458; // m/s
>     output.explanation = "The universe is 13.8 billion years old and contains about 2 trillion galaxies.";
> }
> ```
>
> ```python getBasicFacts (Python) theme={"dark"}
> # Function format: functions.projectName.functionName(input)
> # function functions.cosmos.getBasicFacts(question)
> # Access input parameter: input.question
> user_question = input.question or "What is the universe?"
>
> # Basic universe facts
> output.universeAge = 13.8  # billion years
> output.galaxyCount = 2000  # billion galaxies
> output.speedOfLight = 299792458  # m/s
> output.explanation = "The universe is 13.8 billion years old and contains about 2 trillion galaxies."
> ```

> [tab] getUniverseOverview - Object
>
> Function with structured universe data:
>
> ```javascript getUniverseOverview theme={"dark"}
> // Function format: functions.projectName.functionName(input)
> function functions.cosmos.getUniverseOverview(query) {
>     // Access input parameters: input.query.topic, input.query.detail_level, input.user_preferences
>     const detailLevel = input.query?.detail_level || "basic";
>     const userPrefs = input.user_preferences || {};
>
>     // Structured universe data
>     output.universe = {
>         basicFacts: {
>             age: 13.8, // billion years
>             galaxyCount: 2000, // billion
>             starCount: 200000000 // billion billion (2×10^23)
>         },
>         composition: {
>             darkMatter: 26.8, // percentage
>             darkEnergy: 68.3, // percentage
>             ordinaryMatter: 4.9 // percentage
>         }
>     };
>
>     output.explanation = {
>         summary: "The universe is mostly dark matter and dark energy, with ordinary matter making up less than 5%.",
>         keyFacts: [
>             "Universe is 13.8 billion years old",
>             "Contains 2 trillion galaxies",
>             "Dark energy causes expansion"
>         ],
>         confidence: 0.9
>     };
> }
> ```
>
> ```python getUniverseOverview (Python) theme={"dark"}
> # Access input parameters: input.query.detail_level, input.user_preferences
> # Note: avoid .get() with a default value — check key existence instead
> detail_level = 'basic'
> if input.query and 'detail_level' in input.query:
>     detail_level = input.query['detail_level']
> user_prefs = input.user_preferences or {}
>
> # Structured universe data
> output.universe = {
>     'basicFacts': {
>         'age': 13.8,  # billion years
>         'galaxyCount': 2000,  # billion
>         'starCount': 200000000  # billion billion
>     },
>     'composition': {
>         'darkMatter': 26.8,
>         'darkEnergy': 68.3,
>         'ordinaryMatter': 4.9
>     }
> }
>
> output.explanation = {
>     'summary': 'The universe is mostly dark matter and dark energy.',
>     'keyFacts': ['Universe is 13.8 billion years old', 'Contains 2 trillion galaxies'],
>     'confidence': 0.9
> }
> ```

> [tab] myFirstFunction - Complex
>
> Comprehensive function with detailed universe data:
>
> ```javascript myFirstFunction theme={"dark"}
> // Function format: functions.projectName.functionName(input)
> function functions.cosmos.myFirstFunction(request) {
>     // Access comprehensive input parameters
>     const topic = input.request?.topic || "general";
>     const scope = input.request?.scope || "basic";
>     const scientificLevel = input.request?.scientific_level || "beginner";
>     const userBackground = input.user_context?.background || "general";
>     const maxLength = input.constraints?.max_length || 10000;
>
>     // Comprehensive universe explanation
>     output.universe = {
>         fundamentalConstants: {
>             speedOfLight: 299792458, // m/s
>             gravitationalConstant: 6.674e-11,
>             hubbleConstant: 70 // km/s/Mpc
>         },
>         composition: {
>             darkMatter: 26.8,
>             darkEnergy: 68.3,
>             ordinaryMatter: 4.9
>         },
>         structures: {
>             galaxies: 2e12, // 2 trillion
>             stars: 1e24, // 1 septillion
>             planets: 1e24 // estimated
>         }
>     };
>
>     output.timeline = {
>         bigBang: 13.8e9, // years ago
>         firstStars: 13.6e9, // years ago
>         earthFormation: 4.6e9 // years ago
>     };
>
>     output.explanation = {
>         summary: "The universe began 13.8 billion years ago and is dominated by dark matter and dark energy.",
>         keyInsights: [
>             "Universe is expanding and accelerating",
>             "Most matter is invisible (dark matter)",
>             "Contains billions of galaxies with trillions of stars"
>         ],
>         confidence: 0.85
>     };
> }
> ```
>
> ```python myFirstFunction (Python) theme={"dark"}
> # Access comprehensive input parameters
> # Note: avoid .get() with a default value — check key existence instead
> topic = 'general'
> if input.request and 'topic' in input.request:
>     topic = input.request['topic']
> scope = 'basic'
> if input.request and 'scope' in input.request:
>     scope = input.request['scope']
> scientific_level = 'beginner'
> if input.request and 'scientific_level' in input.request:
>     scientific_level = input.request['scientific_level']
> user_background = 'general'
> if input.user_context and 'background' in input.user_context:
>     user_background = input.user_context['background']
> max_length = 10000
> if input.constraints and 'max_length' in input.constraints:
>     max_length = input.constraints['max_length']
>
> # Comprehensive universe explanation
> output.universe = {
>     'fundamentalConstants': {
>         'speedOfLight': 299792458,
>         'gravitationalConstant': 6.674e-11,
>         'hubbleConstant': 70
>     },
>     'composition': {
>         'darkMatter': 26.8,
>         'darkEnergy': 68.3,
>         'ordinaryMatter': 4.9
>     },
>     'structures': {
>         'galaxies': 2e12,
>         'stars': 1e24,
>         'planets': 1e24
>     }
> }
>
> output.timeline = {
>     'bigBang': 13.8e9,
>     'firstStars': 13.6e9,
>     'earthFormation': 4.6e9
> }
>
> output.explanation = {
>     'summary': 'The universe began 13.8 billion years ago.',
>     'keyInsights': ['Universe is expanding', 'Most matter is dark matter'],
>     'confidence': 0.85
> }
> ```

> [!NOTE]
>
> Always use `input.attribute` format to access function parameters and `output.attribute` to set return values.

**7. Test your function**

1. Go to the **Test** tab
2. Add sample data for your input parameters
3. Click **Test** to execute the function
4. Review the output to ensure your logic works correctly
5. Save your function when testing is successful

## Use functions in processes

After creating a reusable function, you can use it in your business processes through Business Rule actions, or reference it within other reusable functions.

### Where you can reference functions

Reusable functions can be referenced in two contexts:

* **Business Rule actions** within process nodes
* **Other reusable functions** to create composite logic

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

From FlowX.AI 5.11, reusable functions can also be referenced in a third context: **Script nodes** and **Condition (Fork) nodes** in Integration Designer workflows. Write the function call directly in the node's code using the standard `functions.projectName.functionName(...)` syntax, the same way a Business Rule action does. For details, see [Calling reusable functions](../../platform-deep-dive/integrations/workflow-nodes-control-flow#calling-reusable-functions) in the Integration Designer documentation.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

From FlowX.AI 5.12, you can also attach a reusable function to a Custom Agent node as a tool the agent calls at runtime. The function needs typed input and output parameters to be eligible. For details, see [Custom Agent node](../../platform-deep-dive/integrations/custom-agent-node).&#x20;

### Function referencing syntax

When referencing a reusable function, use this format:

```javascript theme={"dark"}
functions.projectName.functionName(input.params)
```

Where:

* `functions` - Convention to reference any reusable function
* `projectName` - Name of the project/library where the function is defined
* `functionName` - Name of the reusable function
* `input.params` - Input parameters using local process variables

```javascript Primitive parameter example theme={"dark"}
functions.academy.calculateMaxLoanAmount(input.monthlySalary)
```

```javascript Object parameter example theme={"dark"}
functions.loanLibrary.calculateLoan(input.client)
```

```javascript Multiple parameters example theme={"dark"}
functions.library1.calculateAgeFromSSN(input.client.ssn)
```

### Add a function to a process

1. Open your process definition in FlowX.AI Designer
2. Select the node where you want to add business logic
3. Create a new **Business Rule** action
4. Reference your reusable function using the syntax above
5. Configure data mapping between your process and the function

### Configure data mapping

Data mapping connects your process data to the function's input and output parameters.

> [tab] Input mapping
>
> Map process variables to function input parameters:
>
> > [tab] getBasicFacts Mapping
> >
> > Simple input mapping for basic universe queries:
> >
> > ```json getBasicFacts input mapping theme={"dark"}
> > {
> >   "question": "processData.userQuestion"
> > }
> > ```
> >
> > Process context example:
> >
> > ```json theme={"dark"}
> > {
> >   "processData": {
> >     "userQuestion": "What is the universe?"
> >   }
> > }
> > ```
>
> > [tab] getUniverseOverview Mapping
> >
> > Structured input mapping for detailed queries:
> >
> > ```json getUniverseOverview input mapping theme={"dark"}
> > {
> >   "query": "processData.universeRequest",
> >   "query.topic": "processData.selectedTopic", 
> >   "query.detail_level": "processData.requestedDetail",
> >   "user_preferences": "processData.userProfile.preferences"
> > }
> > ```
> >
> > Process context example:
> >
> > ```json theme={"dark"}
> > {
> >   "processData": {
> >     "universeRequest": {
> >       "topic": "dark_matter",
> >       "detail_level": "intermediate"
> >     },
> >     "selectedTopic": "composition",
> >     "requestedDetail": "moderate",
> >     "userProfile": {
> >       "preferences": {
> >         "scientific_notation": true,
> >         "units": "metric"
> >       }
> >     }
> >   }
> > }
> > ```
>
> > [tab] myFirstFunction Mapping
> >
> > Comprehensive input mapping for complex universe explanations:
> >
> > ```json myFirstFunction input mapping theme={"dark"}
> > {
> >   "request": "processData.universeInquiry",
> >   "request.topic": "processData.specificSubject",
> >   "request.scope": "processData.explanationScope",
> >   "request.scientific_level": "processData.userExpertiseLevel",
> >   "user_context": "processData.userContext",
> >   "constraints": "processData.outputLimitations"
> > }
> > ```
> >
> > Process context example:
> >
> > ```json theme={"dark"}
> > {
> >   "processData": {
> >     "universeInquiry": {
> >       "topic": "cosmic_evolution",
> >       "scope": "comprehensive",
> >       "scientific_level": "advanced"
> >     },
> >     "specificSubject": "big_bang_theory",
> >     "explanationScope": "timeline_focused",
> >     "userExpertiseLevel": "graduate_level",
> >     "userContext": {
> >       "background": "physics_student",
> >       "preferences": {
> >         "include_equations": true,
> >         "visual_aids": false
> >       }
> >     },
> >     "outputLimitations": {
> >       "max_length": 5000,
> >       "language": "english"
> >     }
> >   }
> > }
> > ```
>
> > [!WARNING]
> >
> > Ensure data types match between your process variables and function parameters to avoid runtime errors. Use dot notation for nested object properties.

> [tab] Output mapping
>
> Specify where to store function outputs in your process data:
>
> > [tab] getBasicFacts Mapping
> >
> > Map primitive outputs to process variables:
> >
> > ```json getBasicFacts output mapping theme={"dark"}
> > {
> >   "processData.universeAge": "output.universeAge",
> >   "processData.totalGalaxies": "output.galaxyCount",
> >   "processData.lightSpeed": "output.speedOfLight",
> >   "processData.summary": "output.explanation"
> > }
> > ```
>
> > [tab] getUniverseOverview Mapping
> >
> > Map structured outputs to process data:
> >
> > ```json getUniverseOverview output mapping theme={"dark"}
> > {
> >   "processData.cosmicData": "output.universe",
> >   "processData.universeAge": "output.universe.basicFacts.age",
> >   "processData.composition": "output.universe.composition",
> >   "processData.explanation": "output.explanation",
> >   "processData.confidence": "output.explanation.confidence"
> > }
> > ```
>
> > [tab] myFirstFunction Mapping
> >
> > Map comprehensive outputs to process variables:
> >
> > ```json myFirstFunction output mapping theme={"dark"}
> > {
> >   "processData.universeData": "output.universe",
> >   "processData.constants": "output.universe.fundamentalConstants",
> >   "processData.timeline": "output.timeline",
> >   "processData.explanation": "output.explanation",
> >   "processData.insights": "output.explanation.keyInsights"
> > }
> > ```
>
> > [!NOTE]
> >
> > You can map entire objects or specific properties. Use dot notation to access nested properties from complex function outputs.

### Use functions within functions

You can create composite business logic by calling one reusable function from within another reusable function. This enables you to build complex functionality from smaller, focused components.

**1. Reference the function**

Use the standard function referencing syntax within your script:

```javascript theme={"dark"}
// Call another function and use its output
const maxLoan = functions.academy.calculateMaxLoanAmount(input.monthlySalary);

// Use the result in further calculations
const loanDetails = functions.loanLibrary.calculateLoan({
    principal: maxLoan,
    rate: input.interestRate,
    term: input.loanTerm
});

// Set the final output
output.integratedLoanData = loanDetails;
```

**2. Handle data flow**

Ensure proper data flow between functions:

* **Input format**: Always use `input.attribute` to access function parameters
* **Function calls**: Use `functions.projectName.functionName(parameters)` format
* **Output assignment**: Set results to `output.attribute`

**3. Test composite functions**

Test thoroughly to ensure all nested function calls work correctly:

1. Test each individual function first
2. Test the composite function with realistic data
3. Verify the data flows correctly between function calls
4. Check error handling when nested functions fail

```javascript integratedLoanCalculator example theme={"dark"}
// Function that calculates loan based on salary using other functions
function functions.loanProject.integratedLoanCalculator(clientData) {
    // Calculate how much loan a person can get based on their salary
    const maxAmount = functions.academy.calculateMaxLoanAmount(input.clientData.monthlySalary);
    
    // Use that amount with calculateLoan function to compute detailed loan information
    const loanDetails = functions.loanLibrary.calculateLoan({
        principal: maxAmount,
        monthlyRate: input.clientData.monthlyRate,
        numberOfPayments: input.clientData.numberOfPayments,
        client: input.clientData
    });
    
    // The final computed result is passed into the output
    output.integratedLoanData = loanDetails;
}
```

```python integratedLoanCalculator (Python) theme={"dark"}
# Calculate how much loan a person can get based on their salary
max_amount = functions.academy.calculateMaxLoanAmount(input.clientData.monthlySalary)

# Use that amount with calculateLoan function to compute detailed loan information
loan_details = functions.loanLibrary.calculateLoan({
    'principal': max_amount,
    'monthlyRate': input.clientData.monthlyRate,
    'numberOfPayments': input.clientData.numberOfPayments,
    'client': input.clientData
})

# The final computed result is passed into the output
output.integratedLoanData = loan_details
```

> [!WARNING]
>
> When using functions within functions, ensure all referenced functions exist in your project and have compatible input/output formats.

## Manage functions

### View function usage

To see where a function is used:

1. Select the function in **Reusable Resources** > **Functions**
2. Click the **Usages** tab
3. Review all processes and nodes that reference the function

> [!NOTE]
>
> The system displays a resource usage modal when you make changes that might affect existing implementations.

### Update functions

When you modify a reusable function:

* Changes automatically propagate to all instances
* Existing process instances may need to restart to pick up updates
* The system preserves instance-specific configurations like data mapping

### Change programming languages

You can change a function's programming language after creation:

1. Open the function editor
2. Go to the **Script** tab
3. Select a different language from the dropdown
4. Rewrite your logic in the new language
5. Test thoroughly before saving

> [!NOTE]
>
> The system shows a usage modal to help you understand the impact of language changes on existing implementations.

## Understanding data types

Reusable functions support two categories of data types for input and output parameters:

### Primitive data types

Primitive types represent single, simple values. They are the basic building blocks of data.

Available primitive types:

* **string** - Text values (for example, "John Doe," "active")
* **number** - Numeric values (for example, 42, 3.14, 13.8)
* **boolean** - True/false values (for example, true, false)

When to use primitives:

* Simple calculations requiring single values
* Basic status flags or indicators
* Individual measurements or counts
* Simple user inputs

Example - Primitive function:

```json theme={"dark"}
{
  "salary": 5000,           // number
  "approved": true,         // boolean
  "status": "active"        // string
}
```

### Complex object data types

Complex types are structured collections of related data, containing multiple fields that can include both primitives and nested objects.

Available complex types:

* **object** - Structured data with named properties
* **array** - Ordered collections of values
* **nested objects** - Objects containing other objects

When to use complex types:

* Grouping related information together
* Representing real-world entities (customers, orders, products)
* Handling structured business data
* Managing hierarchical relationships

Example - Complex object function:

```json theme={"dark"}
{
  "customer": {                    // object
    "personalInfo": {              // nested object
      "name": "John Doe",          // string
      "age": 35                    // number
    },
    "accounts": [                  // array
      {
        "type": "checking",
        "balance": 5000.00
      }
    ]
  },
  "preferences": {                 // object
    "notifications": true,         // boolean
    "language": "en"              // string
  }
}
```

### Key differences

| Aspect | Primitive Types | Complex Object Types |
| - | - | - |
| Structure | Single value | Multiple related values |
| Nesting | Not applicable | Can contain nested structures |
| Access pattern | Direct value access | Dot notation for properties (for example, customer.personalInfo.name) |
| Use case | Simple, standalone data | Related data that should be grouped |
| Mapping complexity | Simple one-to-one mapping | Can map entire objects or individual properties |

### Choosing the right data type

> [tab] Use primitives when
>
> * Working with single, independent values
> * Performing basic calculations
> * Storing simple flags or settings
> * Handling individual measurements
>
> **Example:** Calculating tax on a single amount, validating a single field

> [tab] Use complex objects when
>
> * Data represents a business entity
> * Multiple related values should stay together
> * You need hierarchical data structures
> * Function processes grouped information
>
> **Example:** Processing a loan application, validating customer information

> [!NOTE]
>
> **Best practice:** Start with primitives for simple functions. Upgrade to complex objects when you find yourself passing multiple related parameters or need better data organization.

## Export and import

You can export and import reusable functions to transfer them between projects or environments.

### Exporting

To export a reusable function:

1. Navigate to **Reusable Resources** > **Functions**
2. Open the context menu for the function you want to export
3. Select **Export**
4. The function is downloaded as a ZIP file

### Importing

To import reusable functions:

1. Navigate to **Reusable Resources** > **Functions**
2. Open the context menu and select **Import from ZIP**
3. Select the ZIP file exported from another project or environment
4. If functions with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting function (or use **Apply to all**):
   * **Keep both** - imports the function as a new copy alongside the existing one
   * **Replace** - overwrites the existing function with the imported version
   * **Skip this one** - keeps the existing function unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

***

## Best practices

### Design principles

> [accordion] Single responsibility
>
> Each function should serve one specific, well-defined purpose. Avoid creating functions that handle multiple unrelated tasks.

> [accordion] Clear interfaces
>
> Define precise input and output parameters. Well-defined interfaces make functions easier to understand and use correctly.

> [accordion] Self-contained logic
>
> Functions shouldn't depend on external state or global variables. All necessary data should come through input parameters.

> [accordion] Predictable behavior
>
> The same inputs should always produce the same outputs. Avoid non-deterministic behavior in your business logic.

### Development workflow

1. **Define data model first**: Always establish your data structure before writing code
2. **Specify parameters early**: Define inputs and outputs before implementing logic
3. **Use descriptive names**: Choose clear, business-oriented function names
4. **Test thoroughly**: Validate functions with realistic data before deployment
5. **Handle errors gracefully**: Implement thorough error handling in your business logic

### Organization strategies

* **Group related functions**: Organize functions by business domain or use case
* **Follow naming conventions**: Establish consistent patterns for function names
* **Document extensively**: Include clear descriptions and usage examples
* **Version carefully**: Use project versioning to manage function changes safely

## Troubleshooting

### Common issues

> [accordion] Function not executing
>
> **Possible causes:**
>
> * Incorrect input parameter mapping
> * Data type mismatches between process and function
> * Missing required input parameters
> * Runtime errors in function logic
>
> **Solutions:**
>
> * Verify all input mappings are correct
> * Check data types match between source and target
> * Ensure all required parameters have values
> * Review function logs for error details

> [accordion] Unexpected output
>
> **Possible causes:**
>
> * Incorrect output parameter mapping
> * Logic errors in function implementation
> * Invalid test data during development
>
> **Solutions:**
>
> * Validate output parameter configuration
> * Test function with realistic data
> * Review business logic implementation
> * Check data transformations within the function

> [accordion] Performance issues
>
> **Possible causes:**
>
> * Complex data processing logic
> * Inefficient algorithms
> * Large data structures
>
> **Solutions:**
>
> * Optimize function algorithms
> * Simplify data models where possible
> * Consider breaking complex functions into smaller components
> * Monitor execution times in process context

### Debugging strategies

1. **Use the test environment**: Always test functions thoroughly before deploying to production
2. **Start simple**: Build and test functions incrementally rather than implementing everything at once
3. **Use realistic data**: Test with data that matches your production scenarios
4. **Verify outputs**: Carefully check that function outputs match your expectations
5. **Add logging**: Include console output in your function logic to trace execution

## Function execution context

### Function format and syntax

All reusable functions follow a consistent format and syntax:

```javascript Function declaration format theme={"dark"}
function functions.projectName.functionName(parameterName) {
    // Function implementation
}
```

```javascript Function reference format theme={"dark"}
functions.projectName.functionName(input.params)
```

**Key format rules:**

* **Function declaration**: `functions.projectName.functionName(parameters)`
* **Input access**: Always use `input.attribute` to access function parameters
* **Output assignment**: Use `output.attribute` to set return values
* **Function calls**: Reference other functions using `functions.projectName.functionName(params)`

### Data access patterns

When functions execute within processes, they have access to:

* **Input parameters**: Mapped from process data according to your configuration
* **Output object**: Used to return processed data back to the process
* **Standard libraries**: Built-in functions available in JavaScript or Python
* **Error handling**: Mechanisms to report execution problems back to the process

> [tab] Input format
>
> Access function input using the `input.attribute` format:
>
> ```javascript theme={"dark"}
> // Access input parameters
> const salary = input.monthlySalary;
> const client = input.client;
> ```

> [tab] Output format
>
> Set function output using the `output` object:
>
> ```javascript theme={"dark"}
> // Primitive output
> output = monthlySalary * 48;
>
> // Object output
> output.computedLoan = {
>     principal: input.principal,
>     monthlyPayment: monthlyPayment
> };
> ```

> [!WARNING]
>
> Always verify that your input format (`input.attribute`) matches the parameter names defined in your function to avoid runtime errors.

### Size limits

A function's script can be at most **3,000 characters**, and its description at most 3,000 characters. The script editor doesn't stop you from typing past the limit, but saving a longer script fails with a validation error.

If a function's logic doesn't fit, split it into smaller functions and call them from one another. See [Use functions within functions](#use-functions-within-functions).

## Frequently asked questions

> [accordion] Can you change a reusable function's programming language after creation?
>
> Yes, you can change a function's programming language after creation. Navigate to the **Script** tab, select a different language from the dropdown, rewrite your logic in the new language, and test thoroughly before saving. The system will show a usage modal to help you understand the impact on existing implementations.

> [accordion] Where can you reference reusable functions?
>
> Reusable functions can be referenced in these contexts:
>
> * **Business Rule actions** within process nodes
> * **Other reusable functions** to create composite logic
> * **Script and Condition (Fork) nodes** in Integration Designer workflows (SaaS · 5.11)
> * **Custom Agent function tools** (SaaS · 5.12)

> [accordion] How do you reference a function?
>
> Use the format: `functions.projectName.functionName(input.params)`
>
> Example: `functions.library1.calculateAgeFromSSN(input.client.ssn)`
>
> Where:
>
> * `functions` - Convention to reference a function
> * `library1` - Name of the project/library where the function is defined
> * `calculateAgeFromSSN` - Name of the reusable function
> * `input.client.ssn` - Input parameters using local process variables

> [accordion] Can you use functions within functions?
>
> Yes, you can use functions within functions to create composite business logic. Simply reference other functions using the standard syntax: `functions.projectName.functionName(parameters)` within your function script.

> [accordion] What data types can you use as parameters?
>
> You can use both primitive and object data types as parameters for input and output:
>
> **Primitive types**: string, number, boolean
> **Object types**: Complex structures with nested properties, arrays, and custom business objects
>
> Functions automatically handle the data format based on your model definition.


# Reusable UI Templates
Source: https://docs.flowx.ai/5.9/docs/building-blocks/reusable-resources/reusable-ui

Create and manage modular UI components that can be reused across the User Tasks in your processes or the pages in your UI Flows.

## What are Reusable UI Templates?

Reusable UI Templates are self-contained UI component hierarchies that you design once and instantiate multiple times throughout your application. They solve common UI development challenges:

* **Repetitive styling**: No more redoing component styles and properties for similar UI patterns
* **Manual updates**: Reduce the need to manually change components across multiple locations
* **Template management**: Centralized configuration and management of UI templates

![Reusable UI Templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/reusable_ui.png)

> [!NOTE]
>
> Reusable UI Templates focus on visual components and layout. They cannot include reusable business rules or complex business logic.

## Key benefits

> [card] Consistency
>
> Ensure uniform UI patterns across your entire application

> [card] Efficiency
>
> Design once and use many times - no more recreating similar patterns

> [card] Maintainability
>
> Update templates in one place to affect all instances automatically

> [card] Omnichannel support
>
> Templates work across different platforms and channels

## Template types

FlowX.AI supports two main types of reusable UI templates:

> [tab] Dynamic Templates (with inputs)
>
> **Characteristics:**
>
> * Include input parameters that receive data from the process
> * Support output parameters that send data back to the process
> * Contextualized based on runtime data
> * Ideal for forms and data-driven interfaces
>
> **Use cases:** User registration forms, data collection cards, feedback forms

> [tab] Static Templates (without inputs)
>
> **Characteristics:**
>
> * Self-contained UI components
> * No data exchange with the process
> * Focus on consistent styling and layout
> * Purely visual/structural elements
>
> **Use cases:** Headers, footers, information panels, navigation elements

## Where a template can be used

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Every template declares the kind of resource it can be reused in. You choose this when you create the template, under **Where is it used**:

| Host type | The template can be placed in |
| - | - |
| **Process** | User Tasks in your processes |
| **UI Flow** | Pages in your UI Flows |

> [!WARNING]
>
> **The host type is fixed once the template exists.** You can only set it while creating the template. When you reopen a template to edit it, the field stays visible but locked, so a template built for processes cannot later be reused in UI Flows, or the other way round. Create a second template instead.

Templates you created before this option existed count as **Process** templates, so nothing you have already built changes.

> [!NOTE]
>
> **New templates default to UI Flow.** If you are building a template for a User Task, select **Process** before you save.

### The host type decides which actions you can configure

A template's event handlers only offer the actions that make sense for its host, so the two types are not interchangeable even where the components look identical:

| Host type | Actions available by default |
| - | - |
| **UI Flow** | **Start Process**, **Start Workflow**, **External**, **Navigate To**, **Dismiss** |
| **Process** | **Node Action**, **Dismiss**, **Start Project**, **External** |

Individual components narrow this further. File upload components offer **Upload**, and a file download component offers only **Download**, whichever host it sits in.

> [!TIP]
>
> When you extract a template from something you have already built, the host type is set for you from where you extracted it. Extract from a UI Flow and you get a UI Flow template; extract from a User Task and you get a Process template.

## Template structure

A reusable template consists of:

* **Root component**: A single container (Card, Container, or Custom Component)
* **UI hierarchy**: Child components arranged in a hierarchical structure
* **Event handlers**: Interactive elements that can trigger process actions
* **Data model**: Input and output parameters for template configuration
* **Configuration**: Name, description, and resource metadata

> [!NOTE]
>
> A template has one root component, but that root can hold **multiple forms** alongside any other components. Add each form as a child of the root container — there is no limit on the number of forms in a single template.

![Reusable UI Template Structure](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/reusable_ui1.png)

## Before you begin

Make sure you have:

* Access to FlowX.AI Designer
* Appropriate permissions to create and manage reusable resources
* A clear understanding of the UI pattern you want to standardize

## Create a reusable template

**1. Access template management**

1. In FlowX.AI Designer, go to your project
2. Navigate to **Reusable Resources** > **Templates**
3. Click **+ New Reusable Template**

**2. Configure basic settings**

1. Enter a descriptive name for your template (required)

   > [!WARNING]
   >
   > Template names cannot contain spaces. Use UpperCamelCase or underscores instead.

   * ✅ Good: `PersonalDetailsCard`, `User_Registration_Form`
   * ❌ Avoid: `Personal Details Card`, `user-form`

![Personal Details Card](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/personalDetailsCard.png)

2. Add an optional description explaining the template's purpose
3. Choose your root component type:
   * **Card**: Best for content needing visual separation and styling
   * **Container**: Ideal for layout and grouping without visual styling
4. Configure the data model with input and output parameters

**3. Define the data model**

The **template data model** defines the internal data structure that the template uses to exchange data with the process — which fields the template receives as input and which it sends back as output. It is separate from the process data model and scoped only to this template.

> [!NOTE]
>
> If you're unfamiliar with how data models work in FlowX, see the [Process data model](../process/data-model) documentation.

Set up the internal data structure that your template will use:

1. **Set the root element** (e.g., `applicationUI`)
2. **Define field attributes** with appropriate data types:

**Example: Personal Details Template**

```
applicationUI:
├── firstName_UI – string
├── lastName_UI – string  
├── emailAddress_UI – string
├── phoneNumber_UI – string
├── dob_UI – date
├── gender_UI – string
├── consent_UI – boolean
└── ssn – string
```

> [!TIP]
>
> Use descriptive field names with consistent naming patterns (e.g., `fieldName_UI`) to clearly identify template-specific data.

**4. Configure input and output parameters**

Define the data contract between your template and the process:

**Input Parameters:**

* Data that flows INTO the template from the process
* Example: `ssn` (pre-filled from existing process data)

**Output Parameters:**

* Data that flows OUT of the template back to the process
* Example: `firstName_UI`, `lastName_UI`, `emailAddress_UI`, `phoneNumber_UI`, `dob_UI`, `gender_UI`, `consent_UI`

> [!NOTE]
>
> Parameters control data flow only. They don't determine field visibility or editability - you can still edit input parameter fields unless explicitly made read-only.

Once parameters are defined, click **Done** to establish the template's data contract.

**5. Design the UI hierarchy**

Use the template UI designer to build your component structure:

```
Root Component (Card/Container)
├── UI Components (Text, Input, Button, etc.)
├── Layout Components (Containers, Flex containers)
└── Interactive Components (Forms, Actions)
```

> [!NOTE]
>
> The template UI designer focuses on screen parts without navigation concepts or process-related navigation.

**6. Configure event handlers (optional)**

Define interactive elements within your template:

> [tab] Template-defined actions
>
> * Define event handlers within the reusable template
> * Assign node actions when instantiated in User Tasks
> * Use for standard actions like "Save", "Submit", or "Cancel"

> [tab] Form-centric actions
>
> * Template holds forms with specific information
> * User Task contains actions to validate and send data
> * Use for complex forms combining template and User Task data

**7. Test your template**

1. Use **Preview Mode** to see how your template renders
2. Verify component hierarchy and basic functionality
3. Test with different themes and configurations
4. Save your template when testing is successful

> [!NOTE]
>
> Preview Mode provides visual-only testing. Templates are not functional until embedded in a live process with proper parameter mapping.

### Template navigator

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![Reusable UI template designer on the Navigation tab, showing the UI Components section with a single root card and the tooltip A single root component is supported. on the add button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/reusable-ui-template-navigator.png)

When you edit a template, the left panel opens on the **Navigation** tab and shows the template's component tree under a single **UI Components** section. Templates have no navigation areas, so the navigation section used for user tasks is not shown. Select **Add UI Component** to add the template's root component. A template holds a single root component, so once it has one the add button is turned off with the tooltip **A single root component is supported.**

For the full navigator, see [Navigator in the left panel](../ui-designer/ui-designer#navigator-in-the-left-panel). Copying components into or out of a template is covered in [Copy and paste UI components](../ui-designer/ui-designer#copy-and-paste-ui-components).

## Use templates in User Tasks

To integrate reusable templates into your processes, follow this complete workflow:

### Prerequisites: Set up data models

**1. Configure Project Data Model**

1. In your project, define the main entity (e.g., `Application`)
2. Add child objects that match your template structure (e.g., `Client`)
3. Include all fields from your template's data model:
   * `firstName`, `lastName`, `emailAddress`
   * `phoneNumber`, `dob`, `gender`, `consent`, `ssn`

**2. Configure Process Data Model**

1. Reference the project entity in your process
2. Select `application` as the root entity
3. Include `Client` as a child object
4. The data model will automatically populate with the correct entities

### Add and configure templates

**1. Add template to User Task**

1. Open the UI Designer for your User Task
2. In the component panel, locate **Reusable Templates**
3. Drag and drop your desired template into the UI hierarchy
4. The template will appear with red warning icons indicating unmapped parameters

**2. Map input parameters**

1. Select the template instance in the UI hierarchy
2. Navigate to the template settings panel
3. Click **Define Parameters** for Input Parameters
4. Map each input to process data using dynamic keys:

   **Example mapping:**

   ```
   Static value: "123-45-6789"
   Dynamic key: ${application.client.ssn}
   ```

   > [!TIP]
   >
   > Use dynamic keys like `${application.client.fieldName}` to pull data from your process context automatically.

**3. Map output parameters**

1. Click **Define Parameters** for Output Parameters

2. Select all fields that should return data to the process

3. Map each output to the corresponding process data structure:

   **Example mappings:**

   ```
   applicationUI.firstName_UI → ${application.client.firstName}
   applicationUI.lastName_UI → ${application.client.lastName}
   applicationUI.emailAddress_UI → ${application.client.emailAddress}
   ```

4. Test the parameter mappings to ensure data flows correctly

**4. Connect template actions to process**

1. **Define process action**: In Process Designer, create a node action (e.g., `saveData`)
2. **Link to template**: Return to UI Designer, select the action button within the template
3. **Configure the handler**: In the **Event Handlers** section, add a handler with **Node Action** as the action type and select your node action
4. FlowX.AI automatically fills in the action identifier and establishes the connection

### Runtime behavior

At runtime, the process engine expands reusable templates by:

* Replacing the `REUSABLE_TEMPLATE` placeholder with the actual component hierarchy
* Maintaining proper parent-child relationships
* Ensuring unique identifiers for each instance
* Preserving configured event handlers and data bindings

## Manage templates

### View template usage

To see where a template is used:

1. Go to **Reusable Resources** > **Templates**
2. Select your template
3. Click the **Usages** tab
4. Review all processes and User Tasks using the template

### Update templates

When you modify a reusable template:

* Changes automatically propagate to all instances
* Existing process instances may need to restart for updates
* Instance-specific configurations are preserved
* The system validates changes to prevent breaking existing implementations

> [!WARNING]
>
> Template updates affect all instances immediately. Test changes thoroughly before saving to avoid disrupting active processes.

### Template dependencies

Reusable templates can reference these project resources:

> [accordion] Enumerations
>
> Use for dropdown menus and selection components within your templates

> [accordion] Media items
>
> Include images, documents, and other media assets in your templates

> [accordion] Substitution tags
>
> Add dynamic content that updates based on process context

> [accordion] Themes
>
> Apply consistent styling across all template instances

## Event handlers in templates

### Current capabilities

Event handlers in reusable templates support basic interactive functionality. The system handles:

* **Action context management**: Unique identification for template instances
* **Form submission**: Automatic identification of form elements within template context
* **Data mapping**: Proper mapping of data keys to process variables
* **Validation preservation**: Template validation rules are maintained across instances

### Planned scenarios

> [tab] Template-defined actions
>
> **How it works:**
>
> 1. Define an event handler within the reusable template
> 2. Assign the node action when instantiated in a User Task
> 3. Use for standard actions needing different backend connections
>
> **Best for:** "Save", "Submit", or "Cancel" actions that need process-specific handling

> [tab] Form-centric actions
>
> **How it works:**
>
> 1. Template holds a form with additional information
> 2. User Task contains the action to validate and send data
> 3. Combines data from both template and other User Task forms
>
> **Best for:** Complex forms where template data combines with User Task data

> [!NOTE]
>
> Reusable UI Templates are designed as self-contained components and do not support nesting within other reusable templates

## Troubleshooting

> [accordion] Template not displaying
>
> **Possible causes:**
>
> * Invalid template hierarchy
> * Missing dependencies (enumerations, media, themes)
> * Insufficient permissions
> * Invalid component configurations
>
> **Solutions:**
>
> * Verify template structure in the designer
> * Check all referenced resources exist
> * Confirm user permissions for template access
> * Validate component property settings

> [accordion] Event handlers not working
>
> **Possible causes:**
>
> * Incorrect action context configuration
> * Invalid form submission setup
> * Data model compatibility issues
> * Missing action permissions
>
> **Solutions:**
>
> * Verify action context is properly set
> * Check form submission configuration
> * Ensure data models match between template and process
> * Review user permissions for action execution

> [accordion] Data binding issues
>
> **Possible causes:**
>
> * Invalid key mappings in template instances
> * Mismatched process data model structure
> * Data type incompatibilities
> * Incorrect substitution tag usage
>
> **Solutions:**
>
> * Validate key mappings match expected data structure
> * Check process data model compatibility
> * Ensure data types align between components and data sources
> * Review substitution tag configurations

## Reusable UI Templates vs. Reusable Functions

Understanding the difference between these two reusable components is crucial:

> [tab] Reusable UI Templates
>
> **Purpose:** UI Designer components for creating reusable interface elements
>
> **Scope:**
>
> * Visual components and layout
> * Styling and basic UI interactions
> * Form structure and input patterns
>
> **Usage context:** User Tasks and interface design
>
> **Cannot:** Include reusable business rules or complex business logic

> [tab] Reusable Functions
>
> **Purpose:** Business logic components for data processing
>
> **Scope:**
>
> * Data processing and validation
> * Calculations and transformations
> * Integration patterns and API calls
>
> **Usage context:** Service Tasks and process automation
>
> **Cannot:** Be used within reusable UI templates

## Advanced features

### Planned enhancements

> [card] Template nesting
>
> Future support for using templates within other templates for enhanced modularity

> [card] Enhanced data model
>
> Input and output parameters with function-like behavior and type safety

> [card] Advanced testing
>
> Mock data testing and interactive validation capabilities

> [card] Cross-project sharing
>
> Export/import templates and library dependency management

### Export and import

You can export and import reusable UI templates to transfer them between projects or environments.

#### Exporting

1. Navigate to **Reusable Resources** > **UI Templates**
2. Open the context menu for the template you want to export
3. Select **Export**
4. The template is downloaded as a ZIP file

#### Importing

1. Navigate to **Reusable Resources** > **UI Templates**
2. Open the context menu and select **Import**
3. Select the ZIP file exported from another project or environment
4. If templates with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting template (or use **Apply to all**):
   * **Keep both** - imports the template as a new copy alongside the existing one
   * **Replace** - overwrites the existing template with the imported version
   * **Skip this one** - keeps the existing template unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.


# Supported scripts
Source: https://docs.flowx.ai/5.9/docs/building-blocks/supported-scripts

Scripts are used to execute actions and configure properties inside nodes. The following script languages are supported.

## Business rules scripting

> [card] [Python 3](#python-3)

> [card] [MVEL](#mvel)

> [card] [Groovy](#groovy)

> [card] [JavaScript](#javascript)

| Scripting Language | Language Version | Default Engine (5.9.0+) | Opt-in Engine |
| - | - | - | - |
| JavaScript | ECMAScript 2024 | Node.js V8 (subprocess pool) | GraalJS on GraalVM |
| Python 3 | 3.12 | CPython (subprocess pool) | GraalPy on GraalVM (Python 3.13 starting with 5.9.5) |
| MVEL | 2 | `org.mvel » mvel2` 2.5.2.Final | — |
| Groovy | 5.0.8 | `org.apache.groovy » groovy-jsr223` 5.0.8 | — |

> [!NOTE]
>
> **Starting with 5.9.0, JavaScript and Python execute on a native subprocess pool by default.** Existing scripts that read from `input`, write to `output`, and use language built-ins keep working. `output.put(...)`, `output.get(...)`, and bracket assignment are preserved. To keep a script on the previous GraalVM engine: business rules select the engine **per rule** — see [Script engine per rule](./actions/business-rule-action/business-rule-action#script-engine-per-rule) (rules created before the move to native keep GraalVM automatically); for workflow scripts, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `integration-designer`. See [Script runtime change](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit.

> [!WARNING]
>
> **The GraalVM script engine is deprecated.** FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine, for every JavaScript and Python script: business rules, reusable functions, workflow Script nodes, and the rest. Move scripts that still run on GraalVM to the native engine: switch rules [per rule](./actions/business-rule-action/business-rule-action#script-engine-per-rule) after testing them, and remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer` if you set it.

> [!NOTE]
>
> In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.

> [!WARNING]
>
> Python 2.7 is no longer supported. Migrate Python scripts to Python 3 to take advantage of improved performance and modern language features.

## Integration designer scripting

| Scripting Language | Language Version | Default Engine (5.9.0+) | Opt-in Engine |
| - | - | - | - |
| JavaScript | ECMAScript 2024 | Node.js V8 (subprocess pool) | GraalJS on GraalVM |
| Python | 3.12 | CPython (subprocess pool) | GraalPy on GraalVM (Python 3.13 starting with 5.9.5) |

## Port a script from GraalVM to native

Use this checklist to move a JavaScript or Python script from the deprecated GraalVM engine to the native engine. Each step names one difference between the engines and links to the details. The steps apply to business rules, reusable functions, and workflow Script nodes.

**1. Find the scripts that still run on GraalVM**

Business rules and reusable functions created before the move to the native engine run on GraalVM unless you switched them. The engine selector in the rule's script editor shows which engine it runs on. Workflow Script nodes run on GraalVM only if `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`. Move a reusable function together with the rules that call it. See [Script engine per rule](./actions/business-rule-action/business-rule-action#script-engine-per-rule).

**2. Write to output keys, never reassign output**

`output = {...}` is lost on GraalVM and kept on native, so a script that relied on either behavior changes after the port. Write `output.key = value` or `output["key"] = value`, which works the same on both engines. See [Output is empty](#common-pitfalls).

**3. Stop relying on undefined in JavaScript**

GraalVM writes an `undefined` key as `null`, which clears the value in process data. Native drops the key, so the old value stays. Write `null` when you mean to clear a value, and guard with `!== undefined` when you only want to copy data that exists. See [Same JavaScript rule, different output on native and GraalVM](#common-pitfalls).

**4. Keep or simplify the map calls**

`input.get("key")`, `output.put("key", value)`, `containsKey`, `keySet`, and `size` work on both engines, and plain property access works on native. You can simplify Java-style code, but you don't have to. See [Java HashMap interop in JavaScript](#common-pitfalls).

**5. Remove Java and Node.js access**

The native engine exposes only the standard language built-ins plus `input`, `output`, and the other script variables. `Java.type(...)`, Java classes, `require(...)`, `process`, and `global` fail on native. See [Can I use the Node.js crypto module in JavaScript?](#common-pitfalls).

**6. Check Python imports and built-ins**

The native engine blocks modules that reach the system, network, or files, such as `os`, `sys`, `subprocess`, `socket`, and `pickle`, and removes built-ins such as `print`, `open`, `eval`, and `exec`. Standard modules such as `re`, `datetime`, `uuid`, `hashlib`, and `base64` work. See [Python import errors](#common-pitfalls) and [Python built-ins such as print aren't available](#common-pitfalls).

**7. Expect console.log to be silent**

On native, `console.log` writes nothing and `print` doesn't exist. Write debug values to `output` while you test, then remove them. See [console.log prints nothing](#common-pitfalls).

**8. Make output JSON-serializable**

Native sends `output` back as JSON. Python `datetime`, `Decimal`, and `set` values fail with "Failed to serialize output", and JavaScript `Map` and `Set` values become `{}`. Convert them to strings, numbers, lists, or plain objects before writing them. See [Failed to serialize output](#common-pitfalls).

**9. Stay inside the limits**

The native engine stops a script after 5,000 ms for JavaScript and 10,000 ms for Python by default. GraalVM has no time limit, so a script that ran long on GraalVM can fail after the port. Native also rejects input over 1 MB, including the process data passed to the script, and runs scripts on a worker pool of 16 JavaScript and 8 Python workers per service by default. Under load, a script can fail with "No available workers within timeout". See [Script size and execution limits](./actions/business-rule-action/business-rule-action#script-size-and-execution-limits) and the script engine settings in the [process engine](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration) and [integration designer](/5.9/setup-guides/integration-designer-setup#script-engine-configuration) setup guides.

**10. Switch the engine and test with real data**

Switch each business rule per rule and run it with real data. A script that runs without errors on both engines can still write different output. For workflow scripts, remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer`, which moves every Script node at once, and test the workflows afterwards.

***

## Input and output

Scripts in FlowX receive data through bound variables. The available variables depend on the context.

### Available variables

| Variable | Type | Process business rules | Workflow scripts | Description |
| - | - | - | - | - |
| `input` | `Map` (read-only copy) | ✅ | ✅ | Process instance data or workflow start node data |
| `output` | `Map` (mutable) | ✅ | ✅ | Write results here — data is persisted after script execution |
| `additionalData` | `Map` | ✅ | ✅ | Contains `securityDetails` and `applicationConfiguration` |
| `instanceMetadata` | `Map` | ✅ | ❌ | Process instance identifiers — see [instanceMetadata keys](#instancemetadata-keys) (not available in workflows) |

### instanceMetadata keys

`instanceMetadata` contains only instance identifiers:

| Key | Type | Description |
| - | - | - |
| `processInstanceId` | `Number` | Internal database ID of the process instance |
| `processInstanceUuid` | `String` (UUID) | Unique identifier of the process instance |
| `parentProcessInstanceId` | `Number` | Internal ID of the parent instance (subprocesses only) |
| `parentProcessInstanceUuid` | `String` (UUID) | UUID of the parent instance (subprocesses only) |

> [!NOTE]
>
> The process definition name is **not** available in `instanceMetadata` or any other script variable. If a business rule needs the process name as data, set it explicitly — for example as a process parameter on the start node or in the start request — since the name is static per process definition.

### Writing to output

Assign values to the `output` variable to persist data. Both assignment and `.put()` syntax work.

> [tab] JavaScript
>
> ```javascript theme={"dark"}
> // Dot notation
> output.clientName = input.firstName + " " + input.lastName;
>
> // Bracket notation
> output["totalAmount"] = input.price * input.quantity;
>
> // Java method (also works)
> output.put("status", "approved");
>
> // Nested objects
> output.address = {
>   street: input.streetName,
>   city: input.cityName
> };
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # Bracket notation
> output["clientName"] = input["firstName"] + " " + input["lastName"]
>
> # Java method (also works)
> output.put("totalAmount", input["price"] * input["quantity"])
>
> # Nested objects
> output["address"] = {
>   "street": input["streetName"],
>   "city": input["cityName"]
> }
> ```

### How output is merged into process data

In process business rules, `output` starts empty every time the script runs. When the script finishes, FlowX merges `output` into the existing process data instead of replacing it. Keys you don't write to keep their current values.

The merge works key by key:

| What you write | Existing value | Result |
| - | - | - |
| An object, for example `output.client = { city: "Cluj" }` | An object | Merged recursively: `client.city` is updated, all other keys under `client` are kept |
| An object | Missing, or not an object | The object is stored as the new value |
| A string, number, or boolean | Anything | The new value replaces the existing one |
| An array, for example `output.items = [...]` | Anything | The whole array is replaced. Arrays are never merged item by item |
| `null` (`None` in Python) | Anything | The value is set to `null`. The key stays in the process data |
| An empty object, `{}` | An object | No change: the existing object and its keys are kept |

To update one item in an array, read the array from `input`, change it, and write the full array back to `output`.

> [!WARNING]
>
> Writing `{}` doesn't clear an object that already exists in the process data. To clear it, set the key to `null`. To clear a single nested key, set only that key to `null`, for example `output.client = { city: null }`.
>
> `delete output.key` only removes a key you wrote earlier in the same script. It can't remove data the process instance already holds.

### Reading from input

`input` is a deep copy of the process or workflow data. Changes to `input` are not persisted. Always write to `output`.

> [tab] JavaScript
>
> ```javascript theme={"dark"}
> // Dot notation
> var name = input.application.client.name;
>
> // Bracket notation
> var code = input["application"]["countryCode"];
>
> // Safe access for optional fields
> var detail = input.query?.detail_level || "basic";
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # Bracket notation
> name = input["application"]["client"]["name"]
>
> # Check before accessing optional fields
> if "countryCode" in input["application"]:
>     code = input["application"]["countryCode"]
> ```

#### Check whether a field is missing or null

A field can be missing from `input`, or present with a `null` value. Check for both, so the script works whichever way the data arrives.

> [tab] JavaScript
>
> ```javascript theme={"dark"}
> // == null matches both a null value and a missing field (undefined)
> if (input.customer == null) {
>     output.status = "NO_CUSTOMER";
> }
>
> // === null misses a field that isn't there at all
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # .get() returns None when the key is missing
> if input.get("customer") is None:
>     output["status"] = "NO_CUSTOMER"
>
> # Nested field: fall back to an empty dict when the parent is missing or None
> task_id = (input.get("match") or {}).get("task_id")
> ```

Avoid falsy checks such as `||`, `!value`, or `if not value` when `0`, `""`, or `false` are valid values: they treat those values as missing.

### Accessing configuration parameters

Retrieve project-level configuration parameters through `additionalData`:

```javascript theme={"dark"}
var commission = additionalData.applicationConfiguration.get("commissionPercentage");
output.commissionValue = input.amount * commission;
```

For security details and more examples, see [Extracting additional data in business rules](./actions/business-rule-action/extracting-additional-data).

### Common pitfalls

> [accordion] Output is empty (\{})
>
> If your script runs without errors but output is `{}`:
>
> * **Check your variable names**. `output` must be spelled exactly, it's case-sensitive
> * **Check assignment syntax**. In Python on the GraalVM engine, use `output["key"] = value` (bracket notation), not `output.key = value`. The default native engine accepts both forms
> * **Don't reassign output**. On the GraalVM engine, `output = {"key": "value"}` replaces the reference and is lost, because the engine reads back its own `output` object. The default native engine keeps the reassigned object, but `output["key"] = "value"` works on both engines, so use bracket assignment
> * **Don't use `return`**. Scripts don't need a return statement. Write directly to `output`.

> [accordion] Same JavaScript rule, different output on native and GraalVM
>
> The native and GraalVM engines don't always produce the same output for the same JavaScript script. Test each rule on the engine it runs on, and test it again after you switch its engine.
>
> The engines differ when a script assigns `undefined` to a key of `output`, at any nesting level:
>
> * **Native** leaves the key out of the output, so the process data keeps its current value.
> * **GraalVM** writes the key as `null`, so the current value is cleared.
>
> For how each value is applied, see [How output is merged into process data](#how-output-is-merged-into-process-data).
>
> Example, with this process data before the rule runs:
>
> ```json theme={"dark"}
> {
>   "topics": { "asd": "topic" },
>   "nested": { "a": "old", "b": 0 },
>   "arr": ["old"],
>   "other": { "keep": 1 }
> }
> ```
>
> | Script | Result on GraalVM | Result on native |
> | - | - | - |
> | `var dm = JSON.parse("{}"); output.topics = dm.topics;` | `"topics": null` (cleared) | `"topics": {"asd": "topic"}` (kept) |
> | `output.nested = {a: undefined, b: 1};` | `"nested": {"a": null, "b": 1}` | `"nested": {"a": "old", "b": 1}` |
> | `output.arr = [undefined, 2];` | `"arr": [null, 2]` | `"arr": [null, 2]` |
> | `output.other = null;` | `"other": null` | `"other": null` |
>
> Only the first two scripts differ. An `undefined` array item becomes `null` on both engines, and an explicit `null` clears the value on both.
>
> To get the same result on both engines, make the intent explicit instead of relying on `undefined`:
>
> ```javascript theme={"dark"}
> var source = input.application || {};
>
> // Clear the value when the source is missing
> output.topics = source.topics ?? null;
>
> // Or keep the current value when the source is missing
> if (source.topics !== undefined) {
>   output.topics = source.topics;
> }
> ```
>
> Workflow Script nodes behave the same way. A workflow script runs on GraalVM only when `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`. In that case a key set to `undefined` is written as `null`, which clears the value that earlier nodes put in the workflow data. On the default native engine, the value is kept.
>
> Python scripts aren't affected: `None` is written as `null` on both engines.

> [accordion] Python import errors
>
> On the GraalVM engine (GraalPy), Python scripts run in a sandboxed environment. Standard library modules such as `uuid`, `re`, `hashlib`, `hmac`, `secrets`, and `base64` can be imported. The modules that aren't available are listed under [Python Library Support](#python-library-support).
>
> On the default native engine (CPython), standard library modules such as `uuid`, `re`, `hashlib`, `hmac`, `secrets`, and `base64` can be imported. Modules that reach the system, network, or files, or that inspect or generate code, are blocked together with their submodules, and fail with `Import of '<module>' is not allowed in FlowX scripts`. The blocked modules are `os`, `sys`, `subprocess`, `multiprocessing`, `signal`, `ctypes`, `shutil`, `pathlib`, `glob`, `tempfile`, `io`, `socket`, `ssl`, `select`, `selectors`, `asyncio`, `http`, `urllib`, `ftplib`, `smtplib`, `xmlrpc`, `requests`, `httplib2`, `aiohttp`, `httpx`, `webbrowser`, `antigravity`, `turtle`, `tkinter`, `inspect`, `dis`, `code`, `codeop`, `compileall`, `importlib`, `pkgutil`, `modulefinder`, `types`, `pickle`, `shelve`, and `marshal`.
>
> ```python theme={"dark"}
> # ✅ Works on both engines
> import uuid
> output["id"] = str(uuid.uuid4())
>
> # ❌ Fails on the native engine: Import of 'os' is not allowed in FlowX scripts
> import os
> ```

> [accordion] Python built-ins such as print aren't available
>
> On the default native engine, these Python built-ins are removed: `print`, `input`, `open`, `exec`, `eval`, `compile`, `getattr`, `setattr`, `delattr`, `globals`, `locals`, `vars`, `dir`, `memoryview`, `bytearray`, `exit`, `quit`, and `breakpoint`. A script that calls one fails with `NameError`, for example `NameError: name 'print' is not defined`.
>
> To inspect a value while you build a script, write it to `output` instead of printing it, and remove the key once the script works, because `output` is saved to the process data:
>
> ```python theme={"dark"}
> # ❌ Fails on the native engine: NameError: name 'print' is not defined
> print(input["amount"])
>
> # ✅ Works on both engines
> output["debugAmount"] = input["amount"]
> ```

> [accordion] Python syntax limitations
>
> Some Python patterns behave differently in the GraalPy sandbox:
>
> ```python theme={"dark"}
> # ❌ enumerate() not available
> for i, item in enumerate(items):
>
> # ✅ Use manual index
> i = 0
> while i < len(items):
>     item = items[i]
>     i = i + 1
>
> # ❌ .get() with default argument may cause arity errors
> value = input.get("key", "default")
>
> # ✅ Check key existence first
> if "key" in input:
>     value = input["key"]
> else:
>     value = "default"
>
> # ❌ dict.items() iteration not supported
> for k, v in data.items():
>
> # ✅ Iterate over keys
> keys = list(data.keys())
> i = 0
> while i < len(keys):
>     k = keys[i]
>     v = data[k]
>     i = i + 1
> ```

> [accordion] Java HashMap interop in JavaScript
>
> When accessing data returned by Java services (such as AI node output), values may be Java HashMaps rather than native JavaScript objects. Standard JS methods like `Object.keys()` and spread syntax may not work as expected.
>
> ```javascript theme={"dark"}
> // ❌ May not work with Java HashMaps
> var keys = Object.keys(javaMap);
> var copy = {...javaMap};
>
> // ✅ Use Java interop
> var value = javaMap.get("key");
> javaMap.put("key", "value");
> ```
>
> The default native engine accepts the same calls on `input` and `output`: `get`, `put`, `set`, `containsKey`, `keySet`, and `size`. A rule written for the GraalVM engine keeps working after you switch it to native, and plain JavaScript property access works there too.

> [accordion] Can I use the Node.js crypto module in JavaScript?
>
> No. JavaScript scripts don't run as Node.js modules, so `require` doesn't exist and Node.js modules such as `crypto`, `fs`, or `http` can't be loaded. Calling `require('crypto')` fails with `ReferenceError: require is not defined`. There is no `crypto` global either.
>
> On the default native engine, a script sees only the standard JavaScript built-ins (`JSON`, `Math`, `Date`, `RegExp`, and similar) plus the script variables such as `input` and `output`. Node.js globals such as `process` and `Buffer` aren't available.
>
> To hash data or generate IDs, use a Python script, where `hashlib`, `hmac`, `secrets`, and `uuid` can be imported on both engines:
>
> ```python theme={"dark"}
> import hashlib
> import uuid
>
> output["checksum"] = hashlib.sha256(input["payload"].encode()).hexdigest()
> output["id"] = str(uuid.uuid4())
> ```

> [accordion] console.log prints nothing
>
> On the default native engine, `console.log`, `console.info`, `console.warn`, and `console.error` exist, so calling them doesn't fail, but they discard what you pass them and nothing reaches the service logs. To inspect a value while you build a script, write it to `output`, for example `output.debugAmount = input.amount;`, and remove the key once the script works.

> [accordion] Script stopped at its time limit
>
> On the default native engine, a script that runs too long is stopped. The default limits are 5,000 ms for JavaScript and 10,000 ms for Python. The rule fails with an error saying the script worker timed out, and a workflow Script node fails the same way.
>
> The limits apply to business rules in the process engine and to Script nodes in Integration Workflows, and each service sets them separately with `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` and `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`. Rules on the GraalVM engine have no time limit, so a rule that loops forever on GraalVM keeps running. Before raising a limit, check the script for a loop that never ends or a large data model that is copied on every run. The native engine also rejects input over 1 MB. See [Script size and execution limits](./actions/business-rule-action/business-rule-action#script-size-and-execution-limits).

> [accordion] Failed to serialize output
>
> On the default native engine, `output` is sent back to the service as JSON, so every value in it must be JSON-serializable. A script that writes a value JSON can't represent fails with `Failed to serialize output`. In Python this happens with `datetime`, `Decimal`, and `set` values. In JavaScript, `Map` and `Set` values serialize as `{}` and function values are dropped, without an error.
>
> Convert such values before writing them to `output`: format dates as ISO strings with `isoformat()` or `toISOString()`, turn a `Decimal` into a `str` or `float`, and turn sets and maps into lists or plain objects. The GraalVM engine has no such step, so a script that works there can fail this way after switching to native.

### Scripts in Integration Workflows

Script nodes in [Integration Workflows](../platform-deep-dive/integrations/integration-designer) use the same `input` and `output` variables as process business rules, but the data flow is different:

* **In a process business rule**, `output` writes directly to the process instance data store.
* **In a workflow Script node**, FlowX merges `output` into the workflow data, which is the `input` for the **next node** in the workflow. The data stays within the workflow until the workflow completes at an **End** node.

Only the End node output is mapped back to the calling process (via a Receive Message Task with a **Workflow** data stream).

> [!NOTE]
>
> FlowX merges a workflow Script node's `output` into the workflow data. Keys the script doesn't write keep their values, so later nodes still read data from earlier nodes, and an empty `output` (`{}`) changes nothing, as in process business rules. Write only the keys you add or change.

For details on mapping workflow output back to your process, see [Workflow data models](../platform-deep-dive/integrations/workflow-data-models).

***

## JavaScript

JavaScript scripts run on one of two engines:

| Engine | Runtime | When it's used |
| - | - | - |
| Native (default) | Node.js V8, in a subprocess pool | Default starting with 5.9.0 for new business rules and for workflow scripts |
| GraalVM (opt-in) | GraalJS | Business rules set to GraalVM, including rules created before the move to native, and workflow scripts when `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer` |

Business rules select the engine per rule. See [Script engine per rule](./actions/business-rule-action/business-rule-action#script-engine-per-rule).

### Native engine (default)

Scripts run in an isolated V8 context. A script sees the standard JavaScript built-ins (`JSON`, `Math`, `Date`, `RegExp`, and similar) plus the script variables such as `input` and `output`. `require`, Node.js modules such as `crypto` or `fs`, and Node.js globals such as `process` and `Buffer` aren't available. `console.log` and the other `console` methods write nothing.

### GraalVM engine (opt-in)

> [!NOTE]
>
> **New in v4.7.1**: JavaScript support has been upgraded from Nashorn (ECMAScript 5.1) to GraalJS (ECMAScript 15/2024), providing significantly improved performance and modern language features.

On the GraalVM engine, JavaScript is powered by GraalJS, which supports ECMAScript 15 (2024) standards. This provides modern JavaScript capabilities for your business rules and integrations.

#### What is GraalJS?

GraalJS is an ECMAScript compliant JavaScript implementation built on GraalVM. It supports the latest ECMAScript features and offers high performance through the GraalVM's JIT compiler.

#### Properties

* Supports ECMAScript 15 (2024) features including modern syntax and APIs
* Provides consistent scripting across business rules and integration designer
* Runs in a secure sandboxed environment

#### Limitations

On the GraalVM engine, JavaScript scripts run in a sandboxed environment. Here is a list of JavaScript features not available in the sandbox:

* import.meta (ES2020)
* top-level await (ES2022)
* set operations (ES2024)
* Array.fromAsync (ES2024)

### Useful links

> [card] [GraalJS Documentation](https://www.graalvm.org/javascript/)

> [card] [ECMAScript 2024 Language Specification](https://tc39.es/ecma262/)

***

## Python 3

Python is a high-level, interpreted programming language known for its simplicity and readability. FlowX.AI runs Python scripts on one of two engines, selected the same way as for [JavaScript](#javascript): per business rule, and for workflow scripts through `APPLICATION_SCRIPTENGINE_PROVIDER` on `integration-designer`.

| Engine | Runtime | Python version |
| - | - | - |
| Native (default) | CPython, in a subprocess pool | 3.12 |
| GraalVM (opt-in) | GraalPy | 3.12 in 5.9.0 to 5.9.4, 3.13 starting with 5.9.5 |

### Native engine (default)

Standard library modules such as `uuid`, `re`, `hashlib`, `hmac`, `secrets`, and `base64` can be imported. Modules that reach the system, network, or files, such as `os`, `subprocess`, `socket`, `urllib`, and `io`, are blocked and fail with `Import of '<module>' is not allowed in FlowX scripts`. Built-ins such as `print`, `open`, `eval`, `exec`, and `getattr` are removed. See [Common pitfalls](#common-pitfalls) for the full lists.

Both `output["key"] = value` and `output.key = value` write to `output`.

### GraalVM engine (opt-in)

#### What is GraalPy?

GraalPy is an implementation of Python that runs on the GraalVM. It offers high compatibility with standard Python (CPython) while providing the ability to run within the Java ecosystem. GraalPy supports Python 3 and provides access to a large subset of the standard Python library.

#### Properties

* Supports Python 3.12 (Python 3.13 starting with 5.9.5) with access to most common Python libraries
* Runs up to 3x faster than Python 2.7 via Jython
* Runs in a sandboxed environment for better security

#### Python Library Support

On the GraalVM engine, Python 3 support in FlowX comes with a subset of the [standard Python library](https://docs.python.org/3.12/library/index.html). Python runs in a sandboxed environment and the following modules are not available:

"stringprep", "sqlite3", "plistlib", "getpass", "curses", "curses.textpad", "curses.ascii", "curses.panel", "xml.parsers.expat", "xmlrpc.client", "xmlrpc.server", "turtle", "tkinter", "test.support", "symtable", "pyclbr", "msvcrt", "winreg", "winsound", "grp", "termios", "tty", "pty", "syslog", "audioop", "msilib", "nis", "ossaudiodev", "smtpd", "spwd", "crypt"

> [!WARNING]
>
> Available modules might provide limited access to system resources due to the execution in a sandbox environment.

### Useful links

> [card] [Python 3.12 Documentation](https://docs.python.org/3.12/)

> [card] [GraalPy Documentation](https://www.graalvm.org/python/)

## MVEL

MVEL is an expression language for Java-based applications. It provides a plethora of features and is suited for everything from the smallest property binding and extraction, to full-blown scripts.

* FlowX.AI uses [**mvel2 - 2.5.2.Final version**](https://mvnrepository.com/artifact/org.mvel/mvel2/2.5.2.Final)

### Useful links

> [card] [MVEL Documentation](http://mvel.documentnode.com/)

> [card] [Maven repository: Mvel 2.5.2 Final](https://github.com/mvel/mvel/tags)

***

## Groovy

Groovy is a multi-faceted language for the Java platform. The language can be used to combine Java modules, extend existing Java applications and write new applications

We use and recommend **Groovy 5.0.8** version, using **groovy-jsr223** engine.

> [!NOTE]
>
> **Groovy** has multiple ways of integrating with Java, some of which provide richer options than available with **JSR-223** (e.g. greater configurability and more security control). **JSR-223** is recommended when you need to keep the choice of language used flexible and you don't require integration mechanisms not supported by **JSR-223**.

> [!NOTE]
>
> **JSR-223** (spec) is **a standard scripting API for Java Virtual Machine (JVM) languages** . The JVM languages provide varying levels of support for the JSR-223 API and interoperability with the Java runtime.

### Useful links

> [card] [Groovy Language Documentation](https://docs.groovy-lang.org/docs/groovy-5.0.8/html/documentation/)

> [card] [\[Java\] Class GroovyScriptEngineImpl](https://docs.groovy-lang.org/docs/groovy-5.0.8/html/gapi/org/codehaus/groovy/jsr223/GroovyScriptEngineImpl.html)

> [card] [groovy-jsr223](https://mvnrepository.com/artifact/org.apache.groovy/groovy-jsr223)

***

## Academy courses

> [card] [Exclusive Gateways course](https://academy.flowx.ai/explore/configure-exclusive-gateways)
>
> Learn to configure conditions in JavaScript and DMN for gateway routing

> [card] [Debug 101 course](https://academy.flowx.ai/explore/debug-your-process-0)
>
> Troubleshoot script execution errors, exceptions, and debugging patterns


# Token
Source: https://docs.flowx.ai/5.9/docs/building-blocks/token

Token represents the current position in the process flow. When you start a process, you have a graph of nodes that connect based on the defined sequence and configuration.

The token is a [BPMN](../platform-overview/frameworks-and-standards/business-process-industry-standards/intro-to-bpmn) concept that represents a state within a process instance. It keeps track of the current position in the process flow and is used to store data related to the current process instance state.

A token is created each time a new process instance starts. As actions on the process instance execute, the token advances from one node to the next. Because a node can have several [actions](./actions/actions) that need execution, the token also tracks the actions executed in each node.

> [!TIP]
>
> For [parallel gateways](./node/parallel-gateway), child tokens are created for each flow branch. The parent token moves to the gateway sync node and advances only after all child tokens reach that node.

The following diagram shows how a token advances through a process flow:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/flowx-token-flow-diagram.svg)

A token advances through a process flow

The token moves to the next node only after all mandatory actions from the current node are executed. The token also waits on a node if the node is configured to receive an event from an external system through Kafka.

> [!TIP]
>
> Sometimes the token stops at a node until user input is received. If user input is required to advance the process, the token advances only after all data is received. Use a mandatory manual action linked to the user action to ensure the process flow advances only after the user input is received.

## Viewing tokens

Retrieve the current process instance status using the FlowX Designer. The Designer displays information about tokens related to that process instance and the current nodes they are in.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token_view.png)

### Token view table

The token view displays tokens in a **tree table** format, providing a hierarchical view of parent and child tokens. This format is especially useful when working with parallel gateways or embedded subprocesses.

> [!NOTE]
>
> If parallel gateways are configured in a process, multiple tokens are created, one for each parallel path.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/parallel_tokens.png)

#### Token view features

> [card] Tree structure
>
> Tokens are displayed hierarchically, showing parent-child relationships. All rows are expanded by default.

> [card] Horizontal scrolling
>
> The table supports horizontal scrolling to accommodate all columns

> [card] Frozen columns
>
> The UUID and Token Status columns remain fixed when scrolling horizontally for constant visibility

> [card] Tooltips
>
> Long names are truncated with tooltips showing the full text on hover

The token view table includes the following columns:

| Column | Description |
| - | - |
| **UUID** | Unique identifier for the token. Only the first 6 characters are displayed with a copy icon. Clicking the icon copies the full UUID to clipboard. **Frozen column** (stays visible during horizontal scroll) |
| **Token Status** | Current state of the token in the process (ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, or TERMINATED). Displayed as color-coded tags. **Frozen column** (stays visible during horizontal scroll) |
| **Context** | Shows the main process name for tokens in the main process, or the embedded subprocess name for tokens running within embedded subprocesses (any nesting level) |
| **Initiator Node** | The node or event that initiated the token (for example, Parallel Gateway, Non-interrupting boundary event). Applies to child tokens only; displays "-" for parent tokens |
| **First Executed Node** | The node where the token first executed. For parallel gateway tokens, shows the first executed node on that parallel branch. For boundary event tokens, shows the first executed node on the branch started from the boundary node |
| **Current Node** | The node where the token is currently positioned. For tokens in embedded subprocesses, displays the current node from the subprocess |
| **Current Node Status** | The token's status within the current node (ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL, WAITING\_MESSAGE\_EVENT, WAITING\_TIMER\_EVENT, WAITING\_MESSAGE, MESSAGE\_RECEIVED, or MESSAGE\_RESPONSE\_TIMED\_OUT). Sortable column |
| **Last updated** | The date and time when the token was last updated. Displays full datetime in browser timezone |
| **Actions** | Available actions including Retry (only visible for ACTIVE tokens) and View details (eye icon) |

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token_status_cn.png)

## Understanding token status

### Token status values

The token status indicates the lifecycle state of a token in the process:

> [accordion] ACTIVE
>
> Token state is active when tokens are created. A parent token reactivates when all child tokens reach the parallel gateway closing node.

> [accordion] INACTIVE
>
> Child tokens become inactive when they arrive at a parallel gateway closing node. The current token becomes inactive when it reaches a final node.

> [accordion] ABORTED
>
> The current token becomes aborted when it moves backward to redo a series of previous actions in the process. The token resets, and a new token activates.
>
> A subprocess token is also aborted when an **interrupting boundary event** (error, timer, or message) fires on the parent's Call Activity node: still-active subprocess instances are aborted, while already-finished instances keep their FINISHED status. These two paths - backward movement in the parent and an interrupting boundary event on the parent's node - are the ways a token reaches ABORTED.

> [accordion] ON HOLD
>
> When a parallel split gateway node is reached, the parent token is set to On hold until all child tokens reach the parallel gateway closing node. The parent token does not have a "Retry" action icon until all child tokens finish.

> [accordion] DISMISSED
>
> The process or subprocess reaches a certain node and is canceled or exited.

> [accordion] EXPIRED
>
> A defined "expiryTime" in the process definition passes, and the token changes to this status.

> [accordion] TERMINATED
>
> The process is terminated by a termination request.

### Current node status values

The current node status indicates the execution status of the token within its current node:

> [accordion] ARRIVED
>
> The token reaches a new node

> [accordion] EXECUTING
>
> The token execution starts

> [accordion] EXECUTED\_COMPLETE
>
> Node actions execute, and all mandatory actions from the node complete

> [accordion] EXECUTED\_PARTIAL
>
> Node actions execute, but mandatory uncompleted actions remain

> [accordion] WAITING\_MESSAGE\_EVENT
>
> The token reaches an intermediate message catch event node

> [accordion] WAITING\_TIMER\_EVENT
>
> The token reaches an intermediate timer event node

> [accordion] WAITING\_MESSAGE
>
> The token waits for a message from another system

> [accordion] MESSAGE\_RECEIVED
>
> The message is received

> [accordion] MESSAGE\_RESPONSE\_TIMED\_OUT
>
> The message is not received within the set timeframe

### Initiator types

Tokens can be initiated by different sources. The initiator information is displayed in the **Initiator Node** column of the token view:

> [card] START\_EVENT
>
> Token initiated by a process start event. Parent tokens display "-" in the Initiator Node column.

> [card] BOUNDARY\_EVENT
>
> Token initiated by a boundary event (for example, timer or message boundary event). The boundary event node name is displayed in the Initiator Node column.

> [card] PARALLEL\_GATEWAY
>
> Child token created by a parallel split gateway. The parallel gateway node name is displayed in the Initiator Node column.

> [card] SUBPROCESS
>
> Token created for an embedded subprocess execution.

> [!NOTE]
>
> For tokens initiated by a **BOUNDARY\_EVENT** within an embedded subprocess, the token context is preserved and the initiator node name is correctly mapped in the token view.

### Viewing token details

To view more details about a token:

**1. Open Process status**

Click the **Process status** view button in the FlowX Designer.

**2. Select a token**

Select a token from the token list.

**3. View details**

Click the **view button** (eye icon) to open the detailed token status view.

Access the detailed token status view by navigating to Process instance → Tokens → View (eye icon). The detailed token status modal displays comprehensive information about the token's current state, execution history, and configuration in a structured key-value format.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/token_status.png)

Detailed token status view showing token information, node details, and execution states

The detailed token status view presents token information in an expandable JSON-like structure. Key identifiers and status values are highlighted for quick identification. The modal includes the following fields organized by category:

> [accordion] Token identification
>
> * **id**: The unique identifier of the token
> * **version**: The version number of the token schema
> * **parentTokenId**: The identifier of the parent token (present for child tokens created by parallel gateways or subprocesses)
> * **processInstanceId**: The identifier of the process instance this token belongs to

> [accordion] Token state
>
> * **state**: The current lifecycle state of the token (see [Token status values](#token-status-values) for details)
> * **statusCurrentNode**: The execution status of the token within its current node (see [Current node status values](#current-node-status-values) for details)
> * **dateUpdated**: The ISO 8601 timestamp indicating when the token was last updated

> [accordion] Node information
>
> * **startNodeId**: The identifier of the node where the token execution began
> * **currentNodeId**: The identifier of the node where the token is currently positioned
> * **currentNodeName**: The human-readable name of the current node
> * **currentNode**: Detailed information about the current node object
> * **embedNodeId**: The identifier of the embedded node, if the token is executing within an embedded subprocess
> * **mainSwimlaneId**: The identifier of the main swimlane associated with the token

> [accordion] Process context
>
> * **currentProcessVersionId**: The identifier of the process version currently being executed
> * **currentContext**: The current execution context (typically "main" for the main process, or the subprocess name for embedded subprocesses). This corresponds to the **Context** column in the token view table.

> [accordion] Initiator information
>
> * **initiatorType**: The type of initiator that created this token (see [Initiator types](#initiator-types) for details)
> * **initiatorId**: The identifier of the initiator node or event
> * **initiatorNode**: The name of the node that initiated the token. This corresponds to the **Initiator Node** column in the token view table.

> [accordion] Synchronization
>
> * **syncNodeTokensCount**: The total number of synchronized node tokens (used for parallel gateway synchronization)
> * **syncNodeTokensFinished**: The count of synchronized node tokens that have finished execution

> [accordion] Execution history
>
> * **nodesActionStates**: An expandable array containing detailed information about the action states for each node the token has visited. Each entry includes:
>   * **nodeId**: The identifier of the node
>   * **context**: The execution context (main or subprocess name)
>   * **embedNodeId**: The embedded node identifier, if applicable
>   * **name**: The name of the node
> * **backSeq**: An expandable object containing backward sequence information for tokens that have moved backward in the process flow:
>   * **nodesSeq**: An array of node sequences that were executed in reverse order
>   * **uuid**: The unique identifier for the backward sequence
>   * **context**: The context where the backward sequence occurred
>   * **initiatorNode**: The name of the node that initiated the backward sequence
>   * **firstExecutedNode**: The first node executed in the backward sequence
>   * **currentNode**: The current node in the backward sequence

> [accordion] Additional data
>
> * **paramValues**: Parameter values and process variables associated with the token

> [!NOTE]
>
> The **nodesActionStates** and **backSeq** sections are expandable in the detailed token status view. Expand these sections to view comprehensive information about node execution history and backward sequence tracking.


# Conditional styling
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/conditional-styling

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

Conditional styling enables dynamic, data-driven design adjustments based on specific conditions. It helps reduce the need for multiple prototypes by applying styles conditionally, depending on the data and platform-specific configurations.

> [!NOTE]
>
> **Conflict Resolution:** When multiple conditions overlap, the latest condition (evaluated from top-to-bottom) takes priority.

***

## Configuring conditional styling

1. Open the **UI Designer**.
2. Select an element that supports conditional styling (see [Availability](#availability)).
3. Navigate to the **Styles** tab.
4. Locate the **Conditional Styling** section.
5. Click the **➕** icon to add new expressions and effects.
6. Use the **JS Editor** to configure and test your expressions for accurate behavior.

***

## Conditional styling properties

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)

### Availability

Conditional styling is available on these components:

| Component |
| - |
| Text |
| Link |
| Container |
| Card |
| Form |
| Collection |
| Collection prototype |

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Image** also supports conditional styling.

### Properties you can override

The properties available depend on the component. Across the supported set these are:

| Property | Key used in `overrides` |
| - | - |
| **Background Color** | `backgroundColor` |
| **Border Color** | `borderColor` |
| **Border Width** | `borderWidth` |
| **Text Color** | `labelColor` |
| **Text Style** | `labelStyle` |
| **Link Color** | `linkColor` |

> [!WARNING]
>
> Use the keys in the right-hand column. A key that is not in this list is stored but never applied, so the style silently has no effect.

***

## Structure of conditional styling

1. **Condition:**
   * A string expression, evaluated like the [hide and disabled conditions](./ui-designer#hide-and-disabled-conditions).
   * Supports referencing process data store keys for dynamic evaluations.

2. **Overrides:**
   * A key-value map defining specific property-value pairs.
   * Overrides are applied based on the evaluated condition.

### Example:

```json theme={"dark"}
{
  "platformDisplayOptions": {
    "platform": "web",
    "style": {
      "conditionals": [
        {
          "condition": "$user.age > 30",
          "overrides": {
            "backgroundColor": "#FFD700",
            "labelStyle": "bold"
          }
        },
        {
          "condition": "$user.subscription == 'premium'",
          "overrides": {
            "borderColor": "#4CAF50",
            "labelColor": "#FFFFFF"
          }
        }
      ]
    }
  }
}
```

## Renderer behavior

* **Real-Time Evaluation**: Conditions are continuously evaluated based on live data updates.
* **Priority Handling**: If multiple conditions are met, the last condition in the sequence takes precedence.
* **Dynamic Application**: Styles are applied instantly upon condition satisfaction, enhancing UI responsiveness.

## Contextual menu options

* Conditional Styling Section: Copy To/From Platforms to reuse conditions across different environments.
* Expression + Effect Section: Copy To/From Platforms and Delete options for efficient management.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/contextual_menu.png)

## Key notes

* **Dynamic Styling**: Facilitates platform-specific style overrides driven by real-time data conditions.
* **Scalability**: Designed to support iterative and scalable UI implementations.
* **Enhanced Usability**: Simplifies user interaction with intuitive UI/UX components, making style management more accessible and efficient.

> [!TIP]
>
> Combine conditional styling with data-driven expressions to create responsive, adaptable UI designs.


# Dynamic & computed values
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/dynamic-and-computed-values

Build dynamic, interactive UIs with dynamic and computed values that deliver personalized and responsive experiences to users.

## Dynamic values

Dynamic values give you the flexibility to fill various UI properties at runtime, based on process parameters or substitution tags. By doing so, your application can adapt to specific scenarios or user inputs.

Use this feature to fine-tune how your application appears and behaves without needing to rebuild or redeploy. The table below outlines which UI elements support dynamic values and the corresponding properties that can accept parameters or substitution tags.

| **Element** | **Properties** | **Accepts** |
| - | - | - |
| [**Form Elements**](./ui-component-types/form-elements)  *Input, Textarea, Select, Checkbox, Radio, Switch, Datepicker, Slider, Segmented Button* | - **Default Value** - **Label** - **Placeholder** - **Helper Text** - **Validators** - **Prefix**, **Suffix** | **Yes:** Process parameters or Substitution tags |
| [**File Preview**](./ui-component-types/file-preview) | - **Title** - **Subtitle** | **Yes:** Process parameters or Substitution tags |
| [**Card**](./ui-component-types/root-components/card) | - **Title** - **Subtitle** | **Yes:** Process parameters or Substitution tags |
| **Form** | - **Title** | **Yes:** Process parameters or Substitution tags |
| **Message** | - **Message** | **Yes:** Process parameters or Substitution tags |
| [**Button**](./ui-component-types/buttons), [**Upload**](./ui-component-types/buttons) | - **Label** | **Yes:** Process parameters or Substitution tags |
| **Select**, **Checkbox**, **Radio**, **Segmented Button** (*Static source type only*) | - **Label** - **Value** | **Substitution tags only** |
| **Text** | - **Text** | **Yes:** Process parameters or Substitution tags |
| **Link** | - **Link Text** | **Yes:** Process parameters or Substitution tags |
| **Modal** &#xNAN;*(`modalDismissAlert` properties)* | - **Title** - **Message** - **ConfirmLabel** - **CancelLabel** | **Yes:** Process parameters or Substitution tags |
| **Step** | - **Label** | **Yes:** Process parameters or Substitution tags |
| **Tab** | - **Title** | **Yes:** Process parameters or Substitution tags |

> [!NOTE]
>
> Default Value is not available for the **Switch** element.

### How it works

* **Process Parameters**: At runtime, values can be injected from backend logic or state, such as the outcome of an API call or an action, which then populate the relevant UI element properties.
* **Substitution Tags**: Whenever a UI property references a substitution tag key (e.g., `test`), the application replaces it with the appropriate content at runtime. This is particularly useful for rapid localization, real-time data injection, and user-specific content.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-16%20at%2014.10.36.png)

### Example using Substitution tags

> [!TIP]
>
> Use keys beginning with "@@" to return their value. If a valid key isn't found, you'll get an empty string. If the key format is incorrect, the original string is returned.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release-notes/dynamic_val.gif)

### Example using process parameters

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/dynamic_values_params.gif)

#### Business rule example

In the preceding example, an MVEL business rule demonstrates the population of specific keys with dynamic values from the task. This JSON object, assigned to the "app" key, captures the values for various UI properties:

```json theme={"dark"}
///assigning a JSON object containing dynamic values for the specified keys to the "app" key 

output.put("app",{"label":"This is a label",
                    "title":"This is a title",
                    "placeholder":"This is a placeholder",
                    "helpertext":"This is a helper text",
                    "errorM":"This is a error message",
                    "prefix":"prx",
                    "suffix":"sfx",
                    "subtitile":"This is a subtitle",
                    "message":"This is a message",
                    "defaultV":"defaultValue",
                    "value":"Value101",
                    "value":"Value101",
                    "confirmLabel":"This is a confirm label",
                    "cancelLabel":"This is a cancel label",
                    "defaultValue":"dfs",
                    "defaultDate":"02.02.2025",
                    "defaultSlider": 90});

```

## Computed values

Computed values present a method to dynamically generate values using JavaScript expressions. Beyond adhering to predefined values, computed values enable the manipulation, calculation, and transformation of data grounded in particular rules or conditions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/computed1.png)

Computed values can be created via JavaScript expressions that operate on process parameters or other variables within the application.

> [!TIP]
>
> To introduce a computed value, toggle the "Computed value" option (represented by the **f(x)** icon). This will transform the chosen field into a JavaScript editor.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/computed_default_value.png)

By enabling computed values, the application provides flexibility and the ability to create dynamic and responsive user interfaces.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release-notes/computed.gif)

### Slider example (parsing keys as integers)

The instance above showcases computed values' usage in a Slider element. JavaScript expressions are used to dynamically compute minimum and maximum values based on a value sourced from a linked input UI element (connected via the process key `${application.client.amount}`).

#### Minimum Value

```js theme={"dark"}
if ( !isNaN(parseInt(${application.client.amount})) ) {
    return 0.15 * parseInt(${application.client.amount})
}  else {
    return 10000
}
```

* `!isNaN(parseInt(${application.client.amount}))`: This part ascertains whether the value in the input field `(${application.client.amount})` can be effectively converted to an integer using `parseInt`. Moreover, it validates that the outcome isn't `NaN` (i.e., not a valid number), ensuring input validity.
* If the input is a valid number, the minimum value for the slider is calculated as 15% of the entered value `(0.15 * parseInt(${application.client.amount}))`.
* If the input is not a valid number `(NaN)`, the minimum value for the slider is set to 10000.

#### Maximum Value

```js theme={"dark"}
if ( !isNaN(parseInt(${application.client.amount})) ) {
    return 0.35 * parseInt(${application.client.amount})
}  else {
    return 20000
}
```

* Similar to the previous expression, it checks if the value entered on the input field is a valid number using `!isNaN(parseInt(${application.client.amount}))`.
* If the input is a valid number, the maximum value for the slider is calculated as 35% of the entered value `(0.35 * parseInt(${application.client.amount}))`.
* If the input is not a valid number `(NaN)`, the maximum value for the slider is set to 20000.

#### Summary

In summary, the above expressions provide a dynamic range for the slider based on the value entered on the input field. If a valid numeric value is entered, the slider's range will be dynamically adjusted between 15% and 35% of that value. If the input is not a valid number, a default range of 10000 to 20000 is set for the slider. This can be useful for scenarios where you want the slider's range to be proportional to a user-provided value.

### Text example (using computed strings)

The following scenario outlines the functionality and implementation of dynamically displayed property types via a text UI element. This is done based on the chosen loan type through a select UI element in a user interface.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dynamic_string.gif)

#### Scenario

The UI in focus showcases two primary UI elements:

* Select Element - "Loan type": This element allows users to choose from different loan types, including "Conventional," "FHA," "VA," and "USDA."

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loan_type.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/select_values.png)

* Text Element - "Property type": This element displays property types based on the selected loan type.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/property_type.png)

The following code snippet illustrates how the dynamic property types are generated based on the selected loan type (JavaScript is used):

```javascript theme={"dark"}
if ("${application.loanType}" == "conventional") {
    return "Single-Family Home, Townhouse CondoMulti-Family, Dwelling";
} else if ("${application.loanType}" == "fha") {
    return "Single-Family Home, Townhouse, Condo, Manufactured Home";
} else if ("${application.loanType}" == "va") {
    return "Single-Family Home, Townhouse, Condo, Multi-Family Dwelling";
} else if ("${application.loanType}" == "usda") {
    return "Single-Family Home, Rural Property, Farm Property";
} else {
    return "Please select a loan type first";
}
```

#### Summary

* **Loan Type Selection**: Users interact with the "Loan Type Select Element" to choose a loan type, such as "Conventional," "FHA," "VA," or "USDA."
* **Property Types Display**: Once a loan type is selected, the associated property types are dynamically generated and displayed in the "Text Element."
* **Fallback Message**: If no loan type is selected or an invalid loan type is chosen, a fallback message "Please select a loan type first" is displayed.

### Integration across the UI elements

The UI Designer allows the inclusion of JavaScript expressions for generating computed values. This functionality extends to the following UI elements and their associated properties:

| Element | Properties |
| - | - |
| Slider | min Value, max Value, default Value |
| Input | Default Value |
| Any UI Element that accepts validators | min, max, minLength, maxLength |
| Text | Text |
| Link | Link Text |

* **Slider**: The min value, max value, and default value for sliders can be set using JavaScript expressions applied to process parameters. This allows for dynamic configuration based on numeric values.
* **Any UI Element that accepts validators min, max, minLength, maxLength**: The "params" field for these elements can also accept JavaScript expressions applied to process parameters. This enables flexibility in setting validator parameters dynamically.
* **Default Value**: For input elements like text inputs or number inputs, the default value can be a variable from the process or a computed value determined by JavaScript expressions.
* **Text**: The content of a text element can be set using JavaScript expressions, allowing for dynamic text generation or displaying process-related information.
* **Link**: The link text can also accept JavaScript expressions, enabling dynamic generation of the link text based on process parameters or other conditions.

> [!TIP]
>
> When working with computed values, it's important to note that they are designed to be displayed as integers and strings.

> [!NOTE]
>
> For input elements (e.g., text input), you may require a default value from a process variable, while a number input may need a computed value.

## Understanding the return statement

### Why the return statement is essential

When working with computed values in the UI Designer, **the `return` statement is mandatory** for your JavaScript expressions to function correctly. This is a fundamental requirement that ensures your computed values are properly evaluated and applied to UI elements.

**Technical Reason**: Computed values are executed as JavaScript functions in the UI Designer's evaluation engine. Like any JavaScript function, they must explicitly return a value to provide output to the calling context.

### The role of return in computed values

Computed values use JavaScript expressions that must explicitly return a value using the `return` statement. Without it, your expression will not produce any output, and the UI element will not receive the expected value.

> [!WARNING]
>
> **Critical**: If you forget the `return` statement, your computed value will evaluate to `undefined`, which can cause:
>
> * UI elements to display blank or default values
> * Validation rules to fail unexpectedly
> * Slider ranges to become invalid
> * Text elements to appear empty

#### ✅ Correct Implementation

```javascript theme={"dark"}
// Slider minimum value calculation
if (!isNaN(parseInt(${application.client.amount}))) {
    return 0.15 * parseInt(${application.client.amount});
} else {
    return 10000;
}
```

#### ❌ Incorrect Implementation

```javascript theme={"dark"}
// This will NOT work - missing return statements
if (!isNaN(parseInt(${application.client.amount}))) {
    0.15 * parseInt(${application.client.amount}); // No return!
} else {
    10000; // No return!
}
```

### Best practices for testing

#### Always include return statements

Every code path in your computed value expression should have a `return` statement.

#### Handle edge cases

```javascript theme={"dark"}
// Good practice: Handle both valid and invalid inputs
if (!isNaN(parseInt(${application.client.amount}))) {
    return 0.15 * parseInt(${application.client.amount});
} else {
    return 10000; // Fallback value
}
```

#### Test different scenarios

When testing your computed values, ensure you test:

* **Valid input values** - Normal expected data
* **Invalid or empty input values** - `null`, `undefined`, empty strings
* **Edge cases** - Zero, negative numbers, very large numbers
* **Different data types** - Strings that look like numbers, boolean values
* **Network delays** - Process parameters that might not be loaded yet

> [!NOTE]
>
> **Pro Tip**: Use your browser's developer console to test computed value logic before implementing it in the UI Designer. You can copy your expression and test it with sample data.

#### Use meaningful default values

```javascript theme={"dark"}
// Provide sensible defaults for fallback scenarios
if ("${application.loanType}" == "conventional") {
    return "Single-Family Home, Townhouse, Condo, Multi-Family Dwelling";
} else {
    return "Please select a loan type first"; // Clear user guidance
}
```

## Troubleshooting common issues

### Issue: Computed value not updating

**Symptoms**: UI element shows old values or doesn't change when process parameters change
**Solution**:

* Ensure every code path has a `return` statement
* Check that process parameter syntax uses `${}` correctly
* Verify the process parameter actually exists and has data

### Issue: Getting `undefined` values

**Symptoms**: UI elements appear blank or show "undefined"
**Solution**:

* Check that your JavaScript expression syntax is correct and includes `return`
* Add fallback `return` statements for all possible conditions
* Use defensive programming: `return ${application.value} || "default value"`

### Issue: Values not calculating correctly

**Symptoms**: Math operations produce unexpected results
**Solution**:

* Verify that process parameters are properly referenced with `${}` syntax
* Use `parseInt()` or `parseFloat()` for numeric operations
* Add type checking: `if (typeof ${application.value} === 'number')`

### Issue: Expression works in console but not in UI Designer

**Symptoms**: Logic works when tested separately but fails in computed values
**Solution**:

* Remember that process parameters use `${}` syntax, not regular JavaScript variables
* Ensure all code paths return values, not just the main logic
* Check for syntax errors specific to the UI Designer's JavaScript engine

## Summary

The `return` statement is not optional in computed values—it's a requirement. When testing your computed value rules:

1. **Always** include `return` statements in your JavaScript expressions
2. **Test** all possible code paths and scenarios
3. **Provide** meaningful fallback values for edge cases
4. **Verify** that your expressions work correctly across different input conditions
5. **Debug** using browser console before implementing in UI Designer

> [!WARNING]
>
> **Final Reminder**: Without the `return` statement, your computed values will not function as expected, and your UI elements will not receive the calculated values they need to display correctly. This is the #1 cause of computed value failures.

### Quick Reference: Common Return Patterns

```javascript theme={"dark"}
// Simple conditional return
return ${application.value} > 100 ? "High" : "Low";

// Multiple conditions with fallback
if (${application.status} === "active") {
    return "Status: Active";
} else if (${application.status} === "pending") {
    return "Status: Pending";
} else {
    return "Status: Unknown";
}

// Numeric calculations with validation
if (!isNaN(parseFloat(${application.amount}))) {
    return parseFloat(${application.amount}) * 1.1;
} else {
    return 0;
}

// String operations
return (${application.firstName} || "") + " " + (${application.lastName} || "");
```

***

## Hide and disable expressions

Hide and disable conditions are JavaScript expressions evaluated on the client side. They control whether a UI element is visible or interactive.

* **Hide condition**: hides the element when the expression evaluates to `true`
* **Disabled condition**: disables the element (greyed out, not interactive) when the expression evaluates to `true`

> [!NOTE]
>
> Hide/disable expressions use the same `${}` interpolation syntax as computed values, but they do **not** use the `return` statement. The expression is evaluated directly as a boolean.

### Syntax reference

| Pattern | Expression | Result |
| - | - | - |
| Hide if field is empty | `${application.income} === null \|\| ${application.income} === ""` | Hidden when income is null or empty string |
| Hide if field has a value | `${application.income} !== null && ${application.income} !== ""` | Hidden when income has a value |
| Disable based on value | `${application.name} === 'TEST'` | Disabled when name equals "TEST" |
| Show only for specific option | `${application.loanType} !== 'mortgage'` | Hidden unless loan type is "mortgage" |
| Hide based on boolean | `${application.isVIP} === false` | Hidden when isVIP is false |
| Hide based on number | `${application.amount} < 1000` | Hidden when amount is less than 1000 |
| Multiple conditions (AND) | `${application.age} >= 18 && ${application.consent} === true` | Hidden when both are true |
| Multiple conditions (OR) | `${application.status} === 'rejected' \|\| ${application.status} === 'cancelled'` | Hidden when either matches |

### Common pitfalls

> [accordion] Null vs empty string
>
> Process data keys can be `null` (never set) or `""` (set to empty string). Always check for both:
>
> ```javascript theme={"dark"}
> // Wrong — misses empty strings
> ${application.income} === null
>
> // Wrong — misses null values
> ${application.income} === ""
>
> // Correct — catches both
> ${application.income} === null || ${application.income} === ""
> ```

> [accordion] String comparison requires quotes
>
> When comparing to a string value, always wrap it in quotes:
>
> ```javascript theme={"dark"}
> // Wrong — compares to a variable named mortgage
> ${application.loanType} === mortgage
>
> // Correct — compares to the string "mortgage"
> ${application.loanType} === 'mortgage'
> ```

> [accordion] Boolean values — use strict equality
>
> Boolean fields may come as `true`/`false` or as strings `"true"`/`"false"` depending on the data source:
>
> ```javascript theme={"dark"}
> // Safe approach — handles both boolean and string
> ${application.isActive} === true || ${application.isActive} === 'true'
> ```

> [accordion] Nested objects — check parent exists first
>
> If a parent object might be null, accessing a child property will throw an error:
>
> ```javascript theme={"dark"}
> // Risky — fails if client is null
> ${application.client.status} === 'active'
>
> // Safer — check parent first
> ${application.client} !== null && ${application.client.status} === 'active'
> ```

> [accordion] Number comparisons — watch for string types
>
> Values from form inputs may arrive as strings. Use explicit parsing if needed:
>
> ```javascript theme={"dark"}
> // May fail if amount is a string "1000"
> ${application.amount} > 500
>
> // Safer for numeric comparisons
> parseInt(${application.amount}) > 500
> ```

### Where expressions are used

| Context | Syntax | Uses `return`? | Evaluated |
| - | - | - | - |
| **Hide condition** | `${key} === value` | No | Client-side, boolean |
| **Disable condition** | `${key} === value` | No | Client-side, boolean |
| **Computed values** | `return ${key} + ...` | Yes | Client-side, any type |
| **Conditional styling** | `$key.field > value` | No | Client-side, boolean |
| **Gateway conditions** | MVEL/JS on process data | Depends on language | Server-side, boolean |

> [!TIP]
>
> For more complex logic that depends on multiple data sources or requires server-side processing, consider using [Event Handlers](./event-handlers) (client-side JavaScript) or [business rules](../actions/business-rule-action/business-rule-action) (server-side) instead of hide/disable expressions.


# Event Handlers
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/event-handlers

Configure how UI components respond to user interaction and lifecycle events — run node actions, start workflows, navigate, run local scripts, and more — from a single Event Handlers panel.

## Overview

An **event handler** connects a UI component to something that happens when the user interacts with it or when a screen loads. Each handler has a **trigger** (the event, such as a click) and one or more **actions** (what runs in response, such as a node action or a workflow).

Event handlers are configured per component, in the **Event Handlers** section of the component's configuration panel. A single trigger can run an ordered chain of actions.

> [card] One unified panel
>
> UI events, UI actions, and AI triggers are all configured as event handlers in one place

> [card] Triggers to actions
>
> React to On Click, On Change, On Load, and On Display with a chain of typed actions

> [card] Run local scripts
>
> Update local data on the client with a JavaScript expression — no backend roundtrip

> [card] Ordered chains
>
> Sequence multiple actions per trigger, with ordering and compatibility rules enforced

***

## Triggers

A handler reacts to one of six trigger events. The triggers available on a component depend on the component type and the context (Process vs UI Flow).

| Trigger | Fires when | Typical components |
| - | - | - |
| **On Click** | The user clicks the component | Button, File Upload, Bulk File Upload, Image, Text, Collection Prototype |
| **On Change** | The component's value changes | Form fields (input, text area, select, multi-select, date picker, slider, radio, checkbox, segmented button, switch), Table |
| **On Load** | A screen is rendered for the first time in a session | UI Flow: Page, Zone, Tab Bar, Modal · Process: Tab |
| **On Display** | A screen becomes visible (initial render, navigating back, or a modal closing) | UI Flow: Page, Zone, Tab Bar · Process: Tab |
| **On Scroll** | The user scrolls within a previewed document | File Preview |
| **On Document End** | The user reaches the end of a previewed document | File Preview |

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1.** The **On Scroll** and **On Document End** triggers on the File Preview component are handled by the web and Android renderers. A common use is consent and disclosure: keep a **Submit** or **Accept** action hidden or disabled until an On Document End handler confirms the user reached the end of the document (the handler can be a simple local script that sets a flag).

> [!NOTE]
>
> **On Load vs On Display** — On Load fires once per component per session and does not re-fire on back/forward or breadcrumb navigation. In UI Flows, an explicit **Navigate To** action resets this: the destination screen's On Load re-fires so it can re-initialize data. On Display fires every time the component becomes visible. In UI Flows, **Modal** supports On Load only.

### Conditional triggers

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

An event handler can run **only when a condition is met**. Set a **trigger condition** on the handler — an expression evaluated against the current data — and the handler's actions run only when it resolves to true. This lets one component drive different behavior depending on runtime state, without duplicating handlers. Configured in the Designer and honored by the web and Android renderers.

***

## Action types

The **Action Type** of a handler determines what runs. The available types depend on the context, the component, and the trigger.

| Action type | What it does |
| - | - |
| **Node Action** | Runs a manual node action configured on the same user task node (Process context). |
| **Start Process** | Starts a process instance. |
| **Start Workflow** | Triggers an integration workflow. Fire-and-forget; does not pause the current flow. |
| **Start Project** | Starts a new instance in another project/application. |
| **Navigate To** | Navigates to another screen within a UI Flow. |
| **External** | Opens an external URL, optionally in a new tab. Supports `${variable}` values from data. |
| **Upload** | Initiates a file upload. Available on file-upload components. |
| **Dismiss** | Dismisses a subprocess or closes a modal. |
| **Run Local Script** | Evaluates a client-side JavaScript expression and merges the result into local data — no backend roundtrip. (See [Run Local Script](#run-local-script).) |
| **Save Local Variable** | Saves the current collection row's item into local data under a key — no backend roundtrip. (See [Save Local Variable](#save-local-variable), SaaS · 5.10.) |
| **Conversation Reply Trigger** | In Chat-Driven UI Flows, sends a reply trigger to the conversational agent with parameter mapping. |

**Which action types appear** depends on context, component, and trigger:

* **On Load / On Display** triggers: UI Flow → **Start Workflow** only; Process → **Node Action** only.
* **UI Flow** (other triggers): Start Process, Start Workflow, External, Navigate To, Dismiss. File-upload components add **Upload**.
* **Process** (other triggers): Node Action, Dismiss, Start Project, External. File-upload components → **Upload** only.
* **Run Local Script** is available on interactive and form-field components.
* **Conversation Reply Trigger** is available in UI Flow context when a chat surface is in scope.

***

## Configuring an event handler

Event handlers are configured in the **Event Handlers** section of the selected component's configuration panel.

**1. Select the component**

In the UI Designer, select the component (button, form field, page, modal, and so on) that should respond to an event.

**2. Add a handler for a trigger**

In the **Event Handlers** section, click **+** and choose the trigger event (On Click, On Change, On Load, or On Display). Handlers are grouped under their trigger.

**3. Choose the action type and configure it**

Pick an **Action Type** and fill in its fields (see [Action types](#action-types)). For example, a **Node Action** needs a **Node Action Name**; **External** needs a **URL**; **Start Workflow** needs a **Workflow**.

**4. Order the chain (optional)**

When a trigger has more than one action, drag handlers to set their execution order. The editor flags ordering or compatibility violations.

**5. Save**

Save the handler. Each handler is stored as an ordered action on the component's template configuration.

### Common handler options

Depending on the action type, a handler can include:

* **Show loader** — display a loader until a server-side event updates the data or screen.
* **Open in new tab** — for External actions, open the URL in a new tab.
* **Dismiss on completion** — dismiss the modal as part of a user-triggered action.
* **Hide Subprocess Navigation** — disable navigation to subprocesses (requires Open in new tab).
* **Add form to submit** — link the action to forms whose fields are validated before it runs (see [Form validation](#form-validation)).
* **Add custom keys / Exclude keys / Add custom body** — shape the data sent with the action. These three options appear only on **Action** (Start/Submit), **Upload**, and **Start Project** handlers:
  * **Add custom keys** — data-model paths (dot-separated, e.g. `application.client.firstName`) saved along with the fields of the forms the action submits. With no form to submit, only these paths are saved.
  * **Exclude keys** — a deny-list applied after the custom keys and form fields: drops the listed paths from what is saved.
  * **Add custom body** — a JSON object sent with the action; supports `${...}` placeholders resolved from process data at runtime. A custom body on its own is **not** included in the node output — to keep its data, also list those keys under **Add custom keys**.

***

## Action chains

A single trigger can run several actions in sequence. The Designer enforces three kinds of rules:

* **Per-type limits** — one action of each type per trigger, except **Run Local Script**, which allows up to **five**.
* **Compatibility** — some action types cannot coexist on the same trigger. For example, in a UI Flow, **Start Process** cannot be combined with Navigate To, Dismiss, External, or Conversation Reply Trigger. The rules differ between UI Flow and Process contexts; custom components are exempt.
* **Ordering** — handlers run as a sequential chain in the order shown. Some types cannot follow others; the editor blocks invalid orderings. If an action in the chain fails, the local data-store changes made earlier in the chain are **rolled back**.

***

## Run Local Script

The **Run Local Script** action evaluates a JavaScript expression on the client and merges the returned object into the local data store. There is no backend roundtrip, so the UI updates instantly. This is the same client-side mechanism that was previously called a "UI event."

> [!WARNING]
>
> **Data availability** — a Run Local Script expression can only access data already sent from the backend to the frontend for display on the current screen. Referencing a property that isn't on the page will cause the expression to fail.

### Writing the expression

Use the same `${}` syntax as [computed values](./dynamic-and-computed-values#computed-values). Instead of returning a single value, return an object that updates the local data store:

```javascript theme={"dark"}
// Access data using ${} syntax
const calculatedValue = ${client.debt} / ${client.income};

// Return an object to update local data
return {
  "client": {
    "debtPercentage": calculatedValue
  }
}
```

| Aspect | Business Rule | Run Local Script |
| - | - | - |
| **Logic language** | Python, JavaScript, MVEL | JavaScript only |
| **Output syntax** | `output.put(key, value)` | `return { }` |
| **Execution** | Server-side | Client-side (SDK) |
| **Latency** | Network roundtrip | Instant |

Values updated by Run Local Script remain **local to the UI** until a submit action sends them to the process engine. On an On Click handler, the script evaluates before any other action on the same trigger — useful for setting a selected item's ID right before an action fires.

> [tab] Calculate percentage
>
> ```javascript theme={"dark"}
> const prc = ${client.debt} / ${client.income};
> return { "client": { "debtPrc": prc } }
> ```

> [tab] Conditional value
>
> ```javascript theme={"dark"}
> const amount = ${app.loanAmount};
> const status = amount > 100000 ? "high" : "standard";
> return { "app": { "riskCategory": status } }
> ```

> [tab] Array totals
>
> ```javascript theme={"dark"}
> const items = ${order.items} || [];
> const total = items.reduce((sum, item) => sum + item.price, 0);
> return { "order": { "totalAmount": total, "itemCount": items.length } }
> ```

> [!TIP]
>
> Keep Run Local Script expressions lightweight — they run synchronously on the UI thread. For heavy logic, use a server-side business rule. In Reusable UI Templates, any keys referenced in the expression must be mapped through the template's input parameters.

***

## Form validation

When a handler has one or more forms linked via **Add form to submit**, the platform validates all visible, enabled fields in those forms before the action runs. If any field fails, the action is blocked and errors are shown.

> [!WARNING]
>
> **Hidden and disabled fields skip validation.** When a field is hidden by a hide condition, its validators are removed and any errors are cleared (they re-apply when it becomes visible). Disabled fields are also treated as valid. This prevents invisible fields from blocking progress — if you rely on validation for data integrity, give hidden fields valid defaults or validate them on the backend.

> [!TIP]
>
> If no forms are selected in **Add form to submit**, no client-side validation runs and the action executes immediately. Use this for "Save as Draft"-style actions that should allow incomplete data.

***

## Action specifics

### External

External actions open a URL, optionally in a new tab. URLs support `${variableName}` placeholders resolved from process data at runtime (a missing variable resolves to `null`):

* `https://example.com/users/${userId}`
* `${externalSystemUrl}/api/resource`

### Start Workflow

Select the **Workflow** to trigger and provide **Start params**. When triggered from a button inside a modal, **Dismiss modal** dismisses the modal as part of the action.

> [!WARNING]
>
> Start Workflow is fire-and-forget — it does not pause the current process or wait for the workflow to finish.

### Dismiss

Dismiss calls the backend to dismiss the current process instance and sets the process and its active subprocesses to the terminal **DISMISSED** state. It requires only a name and optional analytics parameters — no form submission or custom keys.

#### Permissions required for Dismiss

Dismiss is authorized against the swimlane that owns the node the active token sits on. Three conditions are checked, in this order:

1. **Swimlane ownership** — the user must be the current owner of that swimlane on this process instance. If someone else holds it, or no owner has been recorded yet, the call is rejected.
2. **Business filters** — any business filters configured on the swimlane must match the user.
3. **Execute operation** — the user's runtime roles must grant **Execute** on that swimlane. View or Self-assign alone is not enough.

All three failures return the same message, `You don't have the rights to perform this action`, so check ownership first when troubleshooting — it is the condition that most often fails.

> [!WARNING]
>
> For a subprocess, the swimlane is **inherited from the parent process instance**. A Dismiss inside a Call Activity modal is authorized against the parent's swimlane and its owner, not against the subprocess's own swimlane. Granting Execute on the subprocess alone does not make the Dismiss succeed.

For the swimlane permission model, see [Swimlanes](/5.9/docs/platform-deep-dive/user-roles-management/swimlanes) and [Configuring access roles for processes](/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes).

> [!NOTE]
>
> A modal's own **Dismissible** property (close-on-backdrop-click and optional confirmation alert) is separate from the Dismiss action. For modal lifecycle guidance, see [Process design principles](../process/design-principles#modals-are-dismissed-only-by-user-interaction).

### Save Local Variable

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Save Local Variable** action saves the current collection row's item into the local data store under the key you set in **Row Item Save Key** — entirely client-side, with no backend roundtrip. Use it on a component inside a collection to capture the clicked row's data so other handlers or components on the same screen can reference it (for example, storing the selected row before a follow-up action fires).

> [!NOTE]
>
> Save Local Variable is not available inside Reusable UI Templates.

***

## Migrating from UI events and UI actions

In 5.1.x, three separate surfaces existed: **UI events** (client-side expressions), **UI actions** (backend interactions), and **AI triggers** (conversation replies). In 5.9.0 they are unified into Event Handlers:

| 5.1.x | 5.9.0 |
| - | - |
| UI event expression (`onChange` / `onClick` / `onLoad` / `onDisplay`) | **Run Local Script** action on the matching trigger |
| UI action (Node Action, Start Process, External, Navigate To, Dismiss, …) | The corresponding **action type** on a handler |
| AI trigger (conversation reply) | **Conversation Reply Trigger** action |

The trigger names map one-to-one (`onClick` → On Click, `onChange` → On Change, `onLoad` → On Load, `onDisplay` → On Display). Behavior is unchanged — Run Local Script still evaluates a client-side expression and merges the result into local data. The storage model changed: handlers are now backend-persisted, ordered action objects on the component's template configuration rather than inline `flowxProps.events` entries.

***

## Related resources

> [card] [Build your first UI Flow](/5.9/docs/getting-started/building-your-first-ui-flow)
>
> Tutorial: Start Workflow and Navigate To handlers in a two-page UI Flow

> [card] [Dynamic & computed values](./dynamic-and-computed-values)
>
> Expressions for hide conditions and computed values

> [card] [Validators](./validators)
>
> Configure validation rules for form fields

> [card] [Buttons](./ui-component-types/buttons)
>
> Configure button components that trigger event handlers

> [card] [Adding an action to a node](../../flowx-designer/managing-a-project-flow/adding-an-action-to-a-node)
>
> Configure the node actions that Node Action handlers call


# Layout configuration
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/layout-configuration

Layout settings are available for all components that can group other types of elements (for example, Containers or Cards).

The layout configuration settings enable users to customize key properties, including layout direction, alignment, gap, sizing, and spacing, to create visually appealing and functional designs.

<video />

These settings can be applied practically in various ways, depending on the context and purpose of the design:

* **Layout Direction and Alignment**: Use these settings to control how content is displayed, ensuring a logical and visually appealing arrangement. For example, a left-to-right layout direction suits languages that read from left to right, while center alignment is ideal for headings or titles.
* **Gap, Sizing, and Spacing**: Manage the distance between elements to create a sense of hierarchy and balance. Adjusting spacing between paragraphs or sections can improve readability, while resizing elements can prioritize certain components within the design.
* **Accessibility Considerations**: Customizing layout direction, alignment, spacing, and sizing can enhance the accessibility and inclusivity of your design. For example, adjusting these settings can make content more readable for users with disabilities or those using assistive technologies. For more information, see the [Accessibility guide](../../platform-deep-dive/accessibility).

## Linear layout

The Linear layout arranges child elements in a single line, either horizontally or vertically.

<video />

### Linear layout configuration properties

**1. Display Mode**

**Linear**: Selected by default for arranging child elements in a linear fashion.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/set_linear.png)

**2. Direction**

* **Horizontal**: Aligns child elements horizontally in a row.
* **Vertical**: Aligns child elements vertically in a column.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_direction.gif)

**3. Justify**

Controls the alignment of child elements along the main axis (the direction set by Horizontal or Vertical).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_justify.gif)

Options include:

* **Start**: Aligns elements at the start of the container.
* **Center**: Centers elements along the main axis.
* **End**: Aligns elements at the end of the container.
* **Space Between**: Distributes elements evenly with space between them.
* **Space Around**: Distributes elements with space around them.
* **Space Evenly**: Distributes elements with equal space around them.

> [!NOTE]
>
> The **Justify** options are honored by the web renderer only. Native iOS and Android renderers do not apply them — see [Platform limitations](./platform-considerations#styling-and-layout-limitations).

**4. Align**

Controls the alignment of child elements along the cross axis (perpendicular to the main axis).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_align.gif)

Options include:

* **Start**: Aligns elements at the start of the cross axis.
* **Center**: Centers elements along the cross axis.
* **End**: Aligns elements at the end of the cross axis.
* **Stretch**: Stretches elements to fill the container along the cross axis.

**5. Wrap**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_wrap.gif)

* **Enabled** (Yes): This option allows elements to wrap onto multiple lines when they exceed the container's width along the main axis, ensuring a flexible and responsive layout.
* **Disabled** (No): This option forces all elements to remain on a single line, even if they overflow beyond the container's width, potentially causing elements to be clipped or hidden.

**6. Gap**

Sets the spacing between child elements, measured in pixels.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/linear_gap.gif)

To better understand how these layout configurations work and see real-time feedback on different combinations, please refer to the following link:

> [card] [Layout configuration](https://tburleson-layouts-demos.firebaseapp.com/#/docs)

## Grid layout

In addition to linear (flex-based) layouts, you can configure components using a grid layout. This option is particularly useful for designs requiring a more structured and multi-dimensional arrangement of elements.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout.png)

### Switching layout types

For components that contain child elements (such as Containers, Cards, and Forms), you can switch between a linear layout and a Grid layout using a layout picker. The default layout is linear, but you can select Grid to arrange your content in a more structured way.

<video />

### Platform-specific layouts

You can configure different layout settings for different platforms. For example, you can opt for a grid layout on the web but switch to a linear layout on mobile for a more simplified user experience. This flexibility ensures that the design is responsive and optimized for each platform, improving usability across different devices.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/layout_platform_specific.gif)

#### Configuring the grid

Once the Grid layout is selected, you can define the number of columns. Initially, the columns will be distributed equally, meaning all columns will have the same width. Additional customization options include:

* **Number of Columns**: Set the number of columns for the grid. By default, grid will use two columns.
* **Alignment**: Control how child elements are aligned within the grid. Alignment can be adjusted both horizontally and vertically, ensuring that content is positioned exactly where needed.
* **Gap Configuration**: Customize the gap between columns and rows. The default gap is inherited from the parent component's theme settings, ensuring consistency across your design.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_specs.png)

#### Grid child settings

When configuring a grid, individual child components can be further customized:

* **Column Span**: Set how many columns a child component should span across.

> [!WARNING]
>
> Col Span should not exceed the number of parent grid columns.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout_child_settings.gif)

* **Row Span (Web Only)**: Set how many rows a child component should span.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout_child_settings1.gif)

#### Order property

The Order property controls the arrangement of elements within grid layouts. By default, elements follow the order in which they appear in the parent component's array. However, this order can be customized using the following options:

* **Auto**: The default setting that retains the order of elements as defined in the array (default value is `0`).
* **First**: Moves the element to the first position by setting its order to `-999`.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/order_first.gif)

* **Last**: Moves the element to the last position by setting its order to `999`.
* **Manual**: Allows for custom ordering by setting a specific numerical value.

> [!TIP]
>
> Example: In a Grid with 10 elements, setting one element's order to `5` while the others are set to `auto` (which equals `0`) will place that element last, because `5` is greater than `0`.

#### Alignment in grid layouts

Proper alignment within grid layouts is essential, particularly when working with fixed-width columns or rows. By default, child elements will inherit alignment settings from their parent component, ensuring a consistent look and feel.

However, you have the flexibility to override these default settings for individual child elements, allowing precise control over horizontal and vertical alignment. This customization is key to achieving the desired visual structure, especially when certain elements need specific positioning within the grid.

### Component details

* **Components with gridLayout Property**: The following components support the `gridLayout` property:
  * [**CONTAINER**](./ui-component-types/root-components/container)
  * [**CARD**](./ui-component-types/root-components/card)
  * **FORM**
  * [**COLLECTION**](./ui-component-types/collection)
  * [**COLLECTION PROTOTYPE**](./ui-component-types/collection/collection-prototype)
* **Components with gridChild Property**: All components can have the `gridChild` property, depending on their parent component's layout.
* **Collection gridLayout**: Within collections, the `gridLayout` property specifies only the number of columns, rowGap, and columnGap.
* **Collection Prototype**: The collection prototype does not include the `gridChild` property.
* **Grid and Flex Layout Application**: The grid and flex layouts apply exclusively to the layout of child components. Elements such as Card titles, subtitles, and Form titles are excluded from these layout types.

### Default style properties

* **Grid Layout Defaults**:
  * **Columns**: 2
  * **ColumnGap**: Inherited from component theming gap
  * **RowGap**: Inherited from component theming gap
  * **Position**: Start Start (aligning items to the start both horizontally and vertically)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_layout_defaults.png)

* **Grid Child Defaults**:
  * **Position**: Start Start (aligned to the start of both axes)
  * **ColumnSpan:** 1 (spans a single column)
  * **RowSpan (Web)**: 1 (spans a single row)
  * **Order**: 0 (Auto, maintaining the default order of elements)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid_child_defaults.png)

***

### Example using grid layout

**Use case**: **Customer Information Form**

This scenario involves a banking application that requires detailed input from a company representative, either during onboarding or for a loan application. Given the need to gather extensive information, a form with a 2-column grid layout is used to ensure clean and consistent alignment of fields.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/example_gridd.png)

> [!TIP]
>
> For forms requiring additional inputs, consider adjusting the **Columns** property to match the number of fields needed. Expanding the form layout will help organize the inputs efficiently and improve user experience.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/more_columns.gif)

> [accordion] Role and Name
>
> * Collect the company representative’s role and name.
> * A 2-column grid layout can display the *Role* in one column and *Name* in the other, ensuring fields are aligned and easy to access.

> [accordion] Shareholder Status
>
> * A toggle or checkbox asks if the representative is the main shareholder and/or the ultimate beneficial owner.
> * A 2-column grid places these toggles side by side for a cleaner interface.

> [accordion] Personal Details
>
> * Fields like *First Name*, *Personal Identification Number*, *Date of Birth*, and *Country of Residence* are collected.
> * The 2-column grid aligns these fields horizontally, with appropriate spacing for readability.

> [accordion] Contact Details
>
> * Collects *Phone Number*, *Email*, and *Preferred Method of Contact*.
> * The grid places *Phone Number* and *Email* side by side, while the *Preferred Method of Contact* dropdown spans the row.

> [accordion] Residence Address
>
> * Collect *State*, *Country*, and *City*.
> * A 3-column grid displays these fields in a single row, simplifying navigation for the user.

> [accordion] Employment Seniority
>
> * Capture employment history such as *Total Service Duration* and *Verified By*.
> * A 2-column grid aligns these fields for easy comparison, avoiding misalignment or unnecessary gaps.

> [accordion] Union Membership
>
> * A simple yes/no radio button for union membership.
> * A grid layout ensures the options are neatly aligned for a clean, straightforward selection.

***

### Best Practices

To ensure an optimal user experience and consistent visual design, consider these best practices when using grid layouts:

* **Minimize Fixed Widths**: Avoid using fixed widths for child components in a grid. Relying on flexible sizing allows the grid to adapt smoothly across different screen sizes and devices. Only use fixed widths when absolutely necessary (e.g., for icons or buttons with defined sizes).

* **Consider Total Width**: If you know the width of the screen is `X`, ensure that the total width of your fixed-width elements doesn't exceed `X`. This prevents layout issues like content overflow or misalignment across different devices.

* **Use Column Span Thoughtfully**: When setting the `columnSpan` for a grid child, ensure that the total spans across all elements do not exceed the number of columns. This ensures a consistent and predictable layout.

* **Avoid Overcrowding**: When adding numerous child components to a grid, be mindful of spacing (gaps) between elements. Proper use of `rowGap` and `columnGap` helps maintain clarity and reduces visual clutter.

* **Use Default Inheritance**: Utilize the default alignment inheritance from the parent grid to ensure consistency. Only override alignment on child components when specific visual differences are needed.

* **Use `Auto` Order When Possible**: Stick with the `auto` order setting for most child components, unless a specific element needs to appear first or last. This will help maintain logical reading and visual flow without complex manual ordering.

* **Always Be Mindful of Mobile Screen Width**: When designing for mobile, always consider the narrower screen width. Ensure that grid layouts adapt gracefully, perhaps switching from a grid to a linear layout, or adjusting spacing and sizing to fit within the mobile screen's constraints without causing overflow or misalignment.

* **Test Across Platforms**: Given potential differences in behavior between web, iOS, and Android platforms, test your grid layout across these platforms to ensure consistent performance and avoid unexpected behavior like overflow or misalignment.

* **Avoid Fixed Widths on Columns**: Instead of setting fixed widths on the entire column, apply fixed widths to the individual elements inside the grid cells. This ensures more flexible layouts that adapt to different screen sizes, especially on mobile devices, without causing issues like overflow or misalignment.

### FAQs

> [accordion] I have a Grid with 10 elements, and I set one element's order to `5`. Why is it not displayed as the fifth element?
>
> **A:** The order property works relative to other elements. If other elements are set to `auto` (which equals `0`), then the element with order `5` will be placed after all the `0` elements, making it appear last.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/FAQ1.gif)

> [accordion] What should I be cautious about when working with a Grid layout?
>
> **A:** Be careful with using fixed widths in Grid layouts. Fixed widths can lead to unexpected behavior, especially on different devices. It's better to use flexible sizing options whenever possible to maintain a responsive and predictable design.


# Localization and internationalization
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/localization-and-i18n

FlowX.AI localization and internationalization adapt applications to different languages, regions, and formats, enhancing the user experience with dynamic date, number and currency formatting.

<video />

## Internationalization

Internationalization (i18n) in FlowX.AI enables apps to be adapted for multiple languages and regions without altering the core code. It sets the foundation for localization by handling language structure, layout adjustments, and supporting various formats.

> [!TIP]
>
> To set the default language at the application level, navigate to **Projects -> Application -> Settings**.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application_language.png)

> [!NOTE]
>
> These settings control the languages **your app** is built and rendered in. In UI Designer, the language and locale selectors in the component header switch which language you are previewing and editing content for, so you can check each translation against the layout.

## Localization

Locale settings impact all date, number, and currency formats based on the combination of region and language. The language dictates translations, while the region specifies formatting order and conventions.

### Locale sources

Locale settings are derived from two main sources:

* **Container Application**: Provides global locale settings across the application.

> [!NOTE]
>
> If not specified during deployment, the default locale is `en-US` and the default language is `en`. The locale governs date, number, and currency formatting; the language governs which translations are served.

> [!TIP]
>
> When you pass `language` and `locale` as URL query parameters (e.g., `?language=ro&locale=ro-RO`), the SDK automatically preserves them across navigation and page refreshes. You don't need to store them in session storage.

* **Application Level**: Enables context-specific overrides within the application for formatting Numbers, Dates, and Currencies.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/app_lvl_format.png)

## Core i18n & l10n features

### Date formats

The default date format in FlowX.AI is automatically determined by the default locale set at the application or system level. Each locale follows its region-specific date convention.

For example:

* en-US locale (United States): `MM/DD/YYYY` → 09/28/2024

> [!TIP]
>
> You can set date formats at the application level (as you can see in the example above), choosing from five predefined options: short, medium, long, full, or custom (e.g., dd/mm/yy).
>
> Additionally, date formats can be overridden at the UI Designer level for specific UI elements that support date customization.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/override_custom.png)

UI Elements supporting date formats:

* Text
* Link
* Message
* Datepicker

FlowX.AI will apply the following formatting options, adapting to the region's standard conventions:

| Format Type | Format Pattern | Example | Description |
| - | - | - | - |
| **Short** | `MM/dd/yy` | `08/28/24` | Month before day, two-digit year. |
| **Medium** | `MMM dd, yyyy` | `Sep 28, 2024` | Abbreviated month, day, four-digit year. |
| **Long** | `MMMM dd, yyyy` | `September 28, 2024` | Full month name, day, and four-digit year. |
| **Full** | `EEEE, MMMM dd, yyyy` | `Thursday, September 28, 2024` | Full day of the week, month, day, year. |
| **Custom** | `dd/MM/yyyy` | `28/08/2024` | User-defined format; day before month. |

> [!NOTE]
>
> The date formats shown in the example are based on the **en-US (United States English) locale**, which typically uses the month-day-year order.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/date_formats.png)

> [!TIP]
>
> If the predefined date formats do not met your needs you can declare and use a custom date format (both at application level or override in UI Designer).

The following example will demonstrate how to set and display various date formats using text UI elements. We will override the default format (originating from the application level) directly in the UI Designer to showcase all available formats:

<video />

> [!NOTE]
>
> FlowX.AI formats dates using [**ISO 8601**](https://www.iso.org/iso-8601-date-and-time-format.html) for consistent and clear international representation.

### Number formatting

FlowX.AI adjusts number formats to align with regional standards, including the use of appropriate decimal separators and digit grouping symbols. This ensures that numbers are displayed in a familiar format for users based on their locale.

#### Locale-specific formatting

Formatting the numbers to adapt decimal separators (`comma` vs. `dot`) and digit grouping (`1,000` vs. `1.000`) to match regional conventions.

> [!TIP]
>
> The correct formatting for a number depends on the locale. Here's a quick look at how the same number might be formatted differently in various regions:
>
> * **en-US (United States)**: 1,234.56 (comma for digit grouping, dot for decimals)
> * **de-DE (Germany)**: 1.234,56 (dot for digit grouping, comma for decimals)
> * **fr-FR (France)**: 1 234,56 (space for digit grouping, comma for decimals)
> * **es-ES (Spain)**: 1.234,56 (dot for digit grouping, comma for decimals)

#### Decimal precision

You can set minimum and maximum decimal places for numbers in application settings to store data and display it with the required precision in the data store.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/app_number_formatting.png)

> [!NOTE]
>
> Formatting settings defined in the FlowX.AI props in the UI Designer take precedence over the application-level formatting settings.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/min_max_decimals.png)

> [!TIP]
>
> For UI elements that support `number` or `currency` types, FlowX.AI checks the data model for precision settings and applies them during data storage, ensuring consistency to configured precision levels.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/darta_model_precision.png)
>
> This means that when using a `float` data model attribute, the precision settings directly control how the number is saved in the data store, specifying the maximum number of decimal places that can be stored.
>
> > [!NOTE]
> >
> > Additionally, an for input UI elements a mask is applied to prevent users from entering more decimal places than the precision set, ensuring data integrity and compliance with defined formatting rules.
>
> For more details, refer to [Data model integration](#data-model-integration).

* **Minimum Decimals**: Sets the least number of decimal places that a number will display. If a number has fewer than the specified decimals, trailing zeros will be added to meet the requirement.
* **Maximum Decimals**: Limits the number of decimal places a number can have. If the number exceeds this limit, it will be rounded to the specified number of decimals.

**Example**:

If you set both Minimum and Maximum Decimals to 3, a number like 2 would display as 2.000, and 3.14159 would be 3.141.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/min_max_decimals_ex.gif)

> [!NOTE]
>
> At runtime, the system applies number formatting rules based on the locale and the settings defined in the application's configuration or UI Designer overrides.
>
> If the number is linked to a data model key the formatting adheres to the metadata defined there, ensuring consistent rendering of numerical data.

### Currency formatting

FlowX.AI provides currency formatting features that dynamically adapt to regional settings, ensuring accurate representation of financial data.

#### Currency object structure

Currencies are managed as a system object with `amount` and `code` keys, creating a wrapper that facilitates consistent handling. This design ensures that every currency display corresponds accurately to the regional and formatting standards defined by the locale. If the `code` is not provided, the system uses the locale to determine the appropriate currency symbol or code.

#### Display behavior

When displaying currency values, the system expects keys like `loanAmount` to have both `amount` and `code` properties. For example, with the locale set to `en-US`, the output will automatically follow the US formatting conventions, displaying amounts like "\$12,000.78" when the currency is USD.

* If the value found at the key path is not an object containing `amount` or `code`, the system will display the value as-is if it is primitive. If it's an object, it will show an empty string.
* If the key path is not defined, similar behavior applies: primitive values are displayed as-is, and objects result in an empty string.

#### Locale-sensitive formatting

Currency formatting depends primarily on the region defined by the locale, not the language.

> [!NOTE]
>
> When the currency `code` is `null`, the system defaults to the currency settings embedded within the locale, ensuring region-specific accuracy.

#### Dynamic formatting in UI

FlowX dynamically applies number formatting within UI components, such as inputs and sliders. These components adjust in real-time based on the current locale, ensuring that users always see numbers in their preferred format. UI components that support currency values dynamically format them in real time. For example:

* Input fields with `CURRENCY` types save values in `{key path}.amount` and will delete the entry from the data store if the input is empty.
* Sliders will save integer values (with no decimals) to `{key path}.amount` and format the displayed values, including min/max labels, according to the locale and currency.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/slider_min_max.gif)

**Formatting Text with locale and data from UI elements**

This example demonstrates how to format a dynamic text by substituting placeholders with values from a data store, taking into account locale-specific formatting. In this case, the goal is to insert the value  coming from a key called loanAmount (added on an Input UI element) into a text and format it according to the en-US locale.

**Data store**:

A JSON object containing key-value pairs. The `loanAmount` key holds a currency object with two properties:

* amount: The actual loan value (a float or number).
* code: The currency code in ISO format (e.g., "USD" for US Dollars).

```json{ theme={"dark"}
  "loanAmount": {
    "amount": 12000.78,
    "code": "USD"
  }
}
```

**Locale**

The locale determines the number and currency formatting rules, such as the use of commas, periods, and currency symbols.

Locale: en-US (English - United States)

**Processing**

* Step 1: The platform extracts the loanAmount.amount value (12000.78) and the loanAmount.code from the data store.
* Step 2: Format the amount according to the specified locale (en-US). In this locale:
  * Use a comma , to separate thousands.
  * Use a period . to denote decimal places.
* Step 3: Replace the `${loanAmount}` placeholder in the text with the formatted value \$12,000.78.

**Output**

The resulting text with the formatted loan amount and the appropriate currency symbol for the en-US locale.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/loanAmount.gif)

Here is the data extracted from the data store (it is available on the process instance)

> [!TIP]
>
> For instance, with a Romanian locale (`ro-RO`), currency is displayed like "12.000,78 RON" when the `code` is null or unavailable.

## Data model integration

FlowX.AI integrates number formatting directly with the data model. When keys are set to number or currency types, the system automatically checks and applies precision settings during data storage. This approach ensures consistency across different data sources and UI components.

Integration Details:

* Numbers are broken down into integer and decimal parts, stored according to specified precision.
* Currency keys are managed as wrapper objects containing amount and code, formatted according to the locale settings.

## UI Designer integration

Formatting is dependent on the locale, which includes both language and region settings. The application container provides the locale for display formatting.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/locale_language_ui_designer.png)

Formatting settings (which is by default `auto`) can be switched to `manual` and overridden for text, message, and link components within the UI Designer's properties tab.

<video />

The UI Designer enables application-level formatting settings for localized display of dynamic values.

## Supported components

* **Text/Message/Link**: Override general localization settings to match localized content presentation.
* **Input Fields**: Inputs correctly format currency and number types based on regional settings.
* **Sliders**: Currency formatting for sliders, with suffixes disabled when currency types are detected.
* **Datepickers**: Date formatting


# Buttons
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/buttons

Interactive button components for triggering actions and file uploads with comprehensive styling and configuration options.

Buttons are essential interactive elements that enable users to trigger actions, navigate between sections, and upload files. FlowX.AI provides two specialized button types, each optimized for specific use cases with extensive customization options.

![Button types overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/basic_buttons.png#center)

## Button types overview

Choose the right button type for your specific use case:

> [card] [Basic Button](#basic-button)
>
> Trigger actions like process advancement, sending notifications, or opening new content

> [card] [File Upload Button](#file-upload-button)
>
> Enable file selection with built-in validation for file types and sizes

## Basic button

Basic buttons serve as the primary interaction mechanism for users to perform actions within your application. They can trigger process flows, send notifications, navigate to different sections, or execute business logic.

### Configuration overview

> [card] Properties
>
> Labels and basic settings

> [card] Event Handlers
>
> Event handling and action types

> [card] Styling
>
> Visual appearance and icons

### Basic button properties

> [accordion] Label Configuration
>
> **Purpose**: Define the text displayed on the button
>
> **Features**:
>
> * Supports Markdown syntax for rich formatting
> * Dynamic text from process data
> * Localization support for multi-language applications
> * Responsive text scaling
>
> **Best Practices**:
>
> * Use action-oriented language ("Submit", "Continue", "Send")
>
> * Keep labels concise but descriptive
>
> * Consider button context and user expectations
>
> * Use consistent terminology across the application
>
> > [!TIP]
> >
> > Action buttons should clearly indicate what will happen when clicked. Use verbs like "Save Changes" instead of generic terms like "OK".

### Event handlers configuration

Define the behavior when users interact with your button:

> [tab] Event Types
>
> | Event | Description | Use Cases |
> | - | - | - |
> | **CLICK** | Triggered when button is clicked/tapped | All button interactions |
>
> > [!NOTE]
> >
> > While CLICK is the primary event, the action type determines what happens when the event occurs.

> [tab] Action Types
>
> **Available Actions**:
>
> * **Process Actions**: Advance workflow, complete tasks
> * **Navigation**: Move between pages or sections
> * **Data Operations**: Save, submit, or validate data
> * **External Integrations**: Call APIs, send notifications
> * **UI Updates**: Show/hide elements, update content
>
> ![Event handler configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/button1.png)

> [tab] Advanced Configuration
>
> **Conditional Actions**: Execute different actions based on conditions
>
> * User roles and permissions
> * Form validation states
> * Process instance data
> * External system responses
>
> **Error Handling**: Define fallback behaviors
>
> * Network connectivity issues
>
> * Permission errors
>
> * Validation failures
>
> * System unavailability
>
> > [!TIP]
> >
> > For detailed event handler configuration, see the [Event Handlers guide](../event-handlers).

### Button styling & visual design

#### Button types

Set the button's visual style with the **Type** property, found on the **Styles** tab under **Properties**. Choose from three styles to match your design system:

> [tab] Fill
>
> **Appearance**: Solid background
>
> **Purpose**: Main call-to-action buttons
>
> **Characteristics**:
>
> * High contrast, prominent appearance
> * Usually one per screen/section
> * Draws immediate attention
>
> **Use Cases**: Submit forms, confirm actions, proceed to next step

> [tab] Ghost
>
> **Appearance**: Outlined style — transparent background with a border
>
> **Purpose**: Supporting actions that don't compete with primary content
>
> **Characteristics**:
>
> * Less prominent than Fill
> * Minimal visual weight
> * Integrates with content
>
> **Use Cases**: Cancel operations, alternative paths, optional actions

> [tab] Text
>
> **Appearance**: Text-only — no background or border
>
> **Purpose**: Minimal visual impact for tertiary actions
>
> **Characteristics**:
>
> * Looks like clickable text
> * Lowest visual hierarchy
>
> **Use Cases**: Links, minor actions, text-based navigation

> [!TIP]
>
> For comprehensive CSS styling options, check our [Styling Guide](../ui-designer#styles-tab).

#### Icon integration

Enhance your buttons with meaningful icons:

> [accordion] Icon Configuration
>
> **Icon Key**: Select from the Media Library
>
> * Consistent icon set across the application
> * SVG format for scalability
> * Optimized for different screen sizes
>
> **Icon Color**: Customize appearance
>
> * Use color picker for precise control
>
> * Maintain accessibility contrast ratios
>
> * Consider colorblind accessibility
>
> > [!TIP]
> >
> > When setting colors, the entire icon fill changes. Avoid color modifications on multicolor icons to prevent visual distortion.

> [accordion] Icon Positioning
>
> **Available Positions**:
>
> | Position | Description | Visual Result | Best For |
> | - | - | - | - |
> | **Left** | Icon before text | 🔍 Search | Most common layout |
> | **Right** | Icon after text | Submit ➤ | Directional actions |
> | **Center** | Icon only | 🔍 | Icon-only buttons |
>
> > [!TIP]
> >
> > When using center position, the button displays only the icon. Ensure the icon clearly communicates the action to maintain usability.
>
> ![Icon-only button example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/button_icon.png)

## File upload button

File upload buttons provide a specialized interface for file selection with built-in validation and user feedback. They're essential for document submission, image uploads, and data import workflows.

### Configuration overview

File upload buttons share many properties with basic buttons but include specialized file handling features:

> [card] File Properties
>
> File type restrictions and validation

> [card] Validation
>
> Size limits and error handling

> [card] User Experience
>
> Feedback and progress indication

### File upload properties

> [accordion] Label Configuration
>
> **Purpose**: Clearly indicate the upload purpose
>
> **Examples**:
>
> * "Upload Document"
> * "Select Profile Picture"
> * "Import Data File"
> * "Attach Receipt"
>
> **Best Practices**:
>
> * Specify what type of file is expected
> * Include file requirements in the label if space allows
> * Use progressive disclosure for complex requirements

> [accordion] File Type Restrictions
>
> **Purpose**: Control which file types users can select
>
> **Configuration Options**:
>
> | Specification | Example | Purpose |
> | - | - | - |
> | **MIME Categories** | `audio/*`, `image/*`, `video/*` | Broad category filtering |
> | **Specific MIME Types** | `application/pdf`, `text/csv` | Exact format control |
> | **File Extensions** | `.doc`, `.docx`, `.jpg`, `.png` | User-friendly restrictions |
>
> **Common Combinations**:
>
> ```
> Images: image/*, .jpg, .jpeg, .png, .gif, .webp
> Documents: .pdf, .doc, .docx, .txt, .rtf
> Spreadsheets: .xls, .xlsx, .csv
> Archives: .zip, .rar, .7z
> ```
>
> > [!WARNING]
> >
> > Be specific about accepted file types to prevent user confusion and reduce invalid uploads.

> [accordion] File Size Management
>
> **Max File Size**: Set appropriate limits based on:
>
> * Server capacity and processing power
> * Network bandwidth considerations
> * Storage limitations
> * User experience expectations
>
> **Size Guidelines**:
>
> * **Images**: 5-10 MB for high quality
> * **Documents**: 25-50 MB for complex files
> * **Data Files**: Based on processing requirements
> * **Media Files**: 100+ MB for videos
>
> **Error Messages**: Provide clear feedback
>
> * "File size must be under 10 MB"
> * "Please compress your image and try again"
> * "Large files may take longer to process"

> [accordion] Validation & Error Handling
>
> **Invalid File Type Error**: Custom messages for unsupported formats
>
> * Explain what formats are accepted
> * Provide guidance on file conversion
> * Link to help resources if needed
>
> **Max File Size Error**: Clear size limit communication
>
> * Display the exact limit
> * Suggest file compression tools
> * Offer alternative upload methods for large files
>
> **Example Configuration**:
>
> ```
> Invalid Type: "Please upload PDF, DOC, or DOCX files only"
> Size Error: "File must be smaller than 25 MB. Current size: 35 MB"
> ```

### Runtime feedback

File upload buttons now provide feedback hints for success, progress, and error states. Previously, users lacked sufficient feedback when uploading a file unless they had a File Preview component or image link, making it difficult to know if the file was uploaded successfully or to see the progress.

> [card] Loading Overlay
>
> Optional overlay loader during file upload for both web and mobile

> [card] Toast Messages
>
> Success and error messages displayed as toasts at runtime, informing users about upload status

> [card] Dynamic Messages
>
> Display dynamic values in toast and loading messages for context-aware feedback

#### Configuration properties

The following properties are available in the File Upload button configuration panel:

| Property | Description |
| - | - |
| **Loading behavior** | Controls how the loading indicator appears (`NONE` or `OVERLAY`) |
| **Loading message** | Custom message displayed during upload (supports dynamic values) |
| **Toast notification on success** | Toggle to show success toast when upload completes |
| **Success message** | Custom success message (supports dynamic values) |
| **Toast notification on error** | Toggle to show error toast when upload fails |
| **Error message** | Custom error message (supports dynamic values) |

#### Configuring upload feedback

> [accordion] Loading Behavior
>
> Configure how loading indicators appear during file uploads:
>
> | Option | Description |
> | - | - |
> | **NONE** | No loading overlay displayed |
> | **OVERLAY** | Full-screen overlay with spinner and optional loading message |
>
> **Loading Message Configuration**:
>
> * Configure custom messages using substitution tags or dynamic values
> * Works consistently across web and mobile platforms
>
> **Example messages**:
>
> * "Uploading your document..."
> * "Processing \$..."
> * "Please wait while we upload your file"

> [accordion] Success Messages
>
> **Success Toast**: Displayed when the file upload completes successfully
>
> * **Enable**: Toggle "Toast notification on success" to show the toast
> * **Custom message**: Set a personalized success message with dynamic values
> * **Auto-dismiss**: Toast automatically disappears after 3-5 seconds
>
> **Example messages**:
>
> * "File uploaded successfully!"
> * "\$ has been uploaded"
> * "Your document is ready for processing"

> [accordion] Error Messages
>
> **Error Toast**: Displayed when the file upload fails
>
> * **Enable**: Toggle "Toast notification on error" to show the toast
> * **Custom message**: Set a personalized error message with dynamic values
> * **Auto-dismiss**: Toast automatically disappears after 3-5 seconds
>
> **Example messages**:
>
> * "Upload failed. Please try again."
> * "Unable to upload \$. Check your connection."
> * "File upload error. Please select a different file."

> [!TIP]
>
> Use substitution tags and dynamic values in your loader and toast messages to provide contextual feedback that includes file names or other relevant data.

#### Theming

The loader and toast components inherit styling from your theme configuration:

> [tab] Loader Styling
>
> | Element | Theme Property |
> | - | - |
> | Background color | `general.appBackground` |
> | Loading text color | `general.generalTextColor` |
> | Loading text style | `general.textFont` |
> | Spinner tint color | `general.accentColor` |
> | Dimmed background | `rgba(0, 0, 0, 0.25)` |

> [tab] Toast Styling
>
> | Toast Type | Theme Property |
> | - | - |
> | Success toast | `Message.fill.success` |
> | Error toast | `Message.fill.error` |

#### Custom loader API (SDK)

For advanced customization, developers can provide custom loader components through the SDK. The `customLoader` object supports file upload loaders alongside existing process loaders:

```typescript theme={"dark"}
type CustomLoaders = {
  startProcess?: Component,    // Loader for process start
  reloadProcess?: Component,   // Loader for process reload
  defaultUpload?: Component,   // Default loader for file uploads
  defaultAction?: Component,   // Default loader for actions
  actions?: Record<string, Component>  // Named action loaders
}
```

**Loader resolution order:**

1. If a named action loader exists (`customLoader.actions?.[actionName]`), use it
2. Otherwise, if `defaultAction` or `defaultUpload` is defined, use that
3. Fall back to the internal SDK loader

> [!NOTE]
>
> Custom loaders allow you to maintain consistent branding and UX patterns across your application while leveraging the FlowX upload infrastructure.

### File upload example

Example configuration for an image upload button:

![File Upload component settings with accepted type image/\*, a 5 MB max size, and custom error messages](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/11-file_upload_img.png)

**Configuration Details**:

* **Accepted Types**: `image/*` (all image formats)
* **Max Size**: 5 MB
* **Error Handling**: Custom messages for type and size violations
* **UI Feedback**: Progress indication and preview capabilities

### File upload actions

> [!NOTE]
>
> The File Upload Button only supports the **Upload** action type. For multi-file uploads, see the [Multiple File Upload](./multiple-file-upload) component.

> [accordion] Event Configuration
>
> **Event Type**: CLICK (same as basic buttons)
>
> **Action Types for File Upload**:
>
> * **File Processing**: Validate, resize, or convert files
> * **Progress Tracking**: Show upload progress and status
> * **Data Integration**: Process file content into application data
> * **Workflow Advancement**: Continue process after successful upload
>
> ![File Upload event handler with Action Type set to Upload](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/10-ui_action_upload.png)

> [accordion] Multi-file uploads
>
> The File Upload Button handles **single-file uploads** only. For batch uploads with drag-and-drop, file validation, and progress tracking, use the dedicated [Multiple File Upload](./multiple-file-upload) component.

### File upload styling

File upload buttons have specialized styling options:

> [tab] Button Types
>
> | Type | Appearance | Best Used For |
> | - | - | - |
> | **Fill** | Solid background | Primary upload actions |
> | **Ghost** | Outlined style | Secondary upload options |
> | **Text** | Text-only appearance | Subtle upload links |

> [tab] Icon & Layout
>
> **Icon Integration**: Same as basic buttons
>
> * **Icon Key**: Select from Media Library
> * **Icon Position**: Left, Right, or Center
> * **Icon Color**: Customizable appearance
>
> **Recommended Icons**:
>
> * Upload arrow (↑)
> * Cloud upload (☁↑)
> * Folder or document icons
> * Plus (+) for add file actions

> [tab] Responsive Sizing
>
> | Option | Behavior | Use Case |
> | - | - | - |
> | **Fill** | Expands to container width | Full-width upload areas |
> | **Fixed** | Maintains specific width | Consistent button sizing |
> | **Auto** | Adjusts to content | Compact layouts |

## Best practices

> [card] [Accessibility](../../../platform-deep-dive/accessibility)
>
> * Use descriptive labels that explain the button's purpose
> * Ensure sufficient color contrast for all button states
> * For icon-only buttons, set an accessibility label in the UI Designer
>
> See the [Accessibility guide](../../../platform-deep-dive/accessibility) for keyboard navigation, ARIA mapping, and screen reader details.

> [card] User Experience
>
> * Place primary actions prominently and consistently
> * Use loading states for actions that take time
> * Provide clear feedback for successful/failed actions
> * Group related buttons logically
> * Avoid too many competing call-to-action buttons
> * Consider touch targets for mobile users (minimum 44px)

> [card] Visual Design
>
> * Maintain consistent button styling across the application
> * Use button hierarchy to guide user attention
> * Choose icons that are universally understood
> * Test button visibility in different lighting conditions
> * Consider color-blind users when relying on color alone
> * Ensure buttons look clickable and interactive

> [card] Performance
>
> * Optimize file upload handling for large files
> * Implement proper error handling and retry mechanisms
> * Provide progress feedback for long-running actions
> * Cache frequently used icons and styling
> * Test button responsiveness under load
> * Consider offline scenarios for critical actions

## Common use cases

### Basic button scenarios

| Use Case | Button Type | Icon Suggestion | Action Type |
| - | - | - | - |
| **Form Submission** | Fill | ✓ (checkmark) | Process advancement |
| **Cancel Operation** | Ghost | ✕ (close) | Navigation back |
| **Delete Item** | Ghost | 🗑 (trash) | Data operation |
| **View Details** | Text | 👁 (eye) | Navigation |
| **Save Draft** | Ghost | 💾 (save) | Data operation |

### File upload scenarios

| Use Case | File Types | Size Limit | Validation Notes |
| - | - | - | - |
| **Profile Photo** | `image/*` | 5 MB | Square aspect ratio preferred |
| **Document Upload** | `.pdf,.doc,.docx` | 25 MB | OCR processing available |
| **Data Import** | `.csv,.xlsx` | 50 MB | Column validation required |
| **Media Gallery** | `image/*,video/*` | 100 MB | Thumbnail generation |
| **Backup Files** | `.zip,.rar` | 500 MB | Virus scanning enabled |

## Platform considerations

> [tab] Web Applications
>
> **Enhanced Features**:
>
> * Drag and drop file upload support
> * Keyboard shortcuts for common actions
> * Hover states and advanced animations
> * Context menus for additional options
> * Multi-file selection capabilities

> [tab] Mobile Applications
>
> **Mobile Optimizations**:
>
> * Touch-friendly button sizes (minimum 44px)
> * Native file picker integration
> * Camera access for image uploads
> * Simplified button layouts for smaller screens
> * Gesture-based interactions

> [tab] Cross-Platform
>
> **Consistency Features**:
>
> * Shared styling configurations
> * Platform-appropriate animations
> * Adaptive button sizing
> * Consistent behavior patterns
> * Universal icon meanings


# Chat
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/chat

Enable interactive AI agent conversations with end-users through a conversational interface in FlowX applications.

The Chat component provides a conversational interface for AI-powered interactions. It enables real-time messaging between users and AI agents within your FlowX applications.

<video />

## Overview

> [card] Real-time messaging
>
> Send and receive messages instantly with streaming support

> [card] AI agent integration
>
> Connect to workflows powered by AI agents

> [card] Session management
>
> Automatic session handling and persistence across page refreshes

> [card] Customizable UI
>
> Themeable components with independent styling for agent and user messages

## Adding to a UI Flow

**1. Navigate to UI Flows**

Open your project and go to **UI Flows** from the left navigation menu.

**2. Select or create a UI Flow**

Select an existing UI flow or create a new one.

![UI Flows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat1.png)

**3. Open UI Assets panel**

In the left sidebar, expand the **UI Assets** panel. Find Chat alongside Table, Collection, and other components.

![UI Assets](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat2.png)

**4. Add and configure**

Drag **Chat** onto the canvas, then configure properties in the right panel.

***

## Configuration

### Required settings

| Property | Description |
| - | - |
| **Workflow** | The agent workflow that handles chat interactions (required) |
| **Welcome Message** | Initial greeting shown when chat opens |
| **Thinking Message** | Text displayed while agent processes (default: "Thinking...") |

### Component hierarchy

The Chat component has configurable sub-components:

```
📁 Chat
  ├── 📄 Header (title, subtitle, new chat button)
  ├── 📁 Messages
  │     ├── 💬 Agent Message (avatar, text styling)
  │     ├── 💬 User Message (bubble styling)
  │     ├── 📎 Attached Files (files sent with a user message)
  │     │     └── 📄 File Item (one row per sent file)
  │     └── 💡 Suggested Prompts (pre-configured prompt suggestions)
  └── ⌨️ Input (placeholder, send button)
        └── 📎 File Attachments (accepted types, limits, error messages)
              └── 📄 File Item (one row per pending file)
```

![Chat Component Anatomy](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat_anatomy.png)

### Settings by sub-component

> [accordion] Chat (root)
>
> | Property | Description |
> | - | - |
> | **Workflow** | Select the workflow handling chat interactions |
> | **Welcome Message** | Initial greeting (supports variables: `${customerName}`) |
> | **Thinking Message** | Text shown during processing |
>
> ![Chat Component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat_props.png)

> [accordion] Header
>
> | Property | Description |
> | - | - |
> | **Button Label** | "New chat" button text |
> | **Title** | Main header text |
> | **Subtitle** | Secondary text below title |
> | **Show Chat Icon** | Toggle avatar icon visibility |
> | **Show Separator** | Toggle separator line |
>
> ![Header](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/chat_header.png)

> [accordion] Chat History
>
> | Property | Description |
> | - | - |
> | **Title** | Heading displayed on the chat history panel |
>
> SaaS · 5.11
>
> > [!NOTE]
> >
> > **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.
>
> **Searching past conversations**
>
> End users can search the conversation list from the history panel. Searching starts once the query reaches a minimum length, so a single character does not trigger a lookup, and results replace the list while the query is active.
>
> > [!NOTE]
> >
> > Conversation previews in the list can show raw Markdown characters such as `#` and `*` when an agent reply contains them. Rendering Markdown in the preview line is not yet supported.

> [accordion] Agent Message
>
> | Property | Description |
> | - | - |
> | **Show Avatar** | Toggle agent avatar visibility |
>
> ![Agent Message](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/agent_message.png)

> [accordion] Input
>
> | Property | Description | Default |
> | - | - | - |
> | **Placeholder** | Hint text (e.g., "Ask me anything...") | — |
> | **Enable Voice Input** | Show the microphone button so users can send voice messages. | `Off` |
> | **Enable File Attachments** | Show the attach button so users can send files together with a message. | `Off` |
>
> ![Input](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/input_message.png)
>
> For runtime behavior (recording limits, playback rules) see [Voice input](/5.9/ai-platform/chat-component#voice-input) in the Chat component reference. Turning on **Enable File Attachments** activates the **File Attachments** sub-component below.
>
> SaaS · 5.11
>
> > [!NOTE]
> >
> > **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.
>
> **Turning off the input on a business condition**
>
> Select the chat **Input**, then open **Settings** → **Expressions** → **Disabled condition** and write a JavaScript condition. When it evaluates true, users can still read the conversation but cannot send a new message. The **Expressions** section also holds the **Hide condition** field, which works the same way but removes the input entirely. See [Hide and disabled conditions](../../ui-designer/ui-designer#hide-and-disabled-conditions) for how both fields behave across components.
>
> Use it to close a conversation once a journey reaches a terminal state, for example after a case is submitted or a decision is returned, while keeping the transcript readable.
>
> > [!WARNING]
> >
> > Available on Web and Android. The iOS renderer does not evaluate the **Disabled condition** yet, so on iOS the input stays enabled.

> [accordion] Suggested Prompts
>
> Displays pre-configured prompt suggestions before the user types. Child of **Messages** (alongside Agent Message and User Message).
>
> | Property | Type | Default | Description |
> | - | - | - | - |
> | **Title** | string | `"Suggested Prompts"` | Heading text displayed above the suggestions |
> | **Prompts** | string\[] | — | List of prompt strings shown as clickable suggestions |
>
> Clicking a suggestion sends it as the user's message. Long prompts are truncated and revealed via tooltip.

> [accordion] File Attachments
>
> SaaS · 5.10
>
> > [!NOTE]
> >
> > **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.
>
> Lets end users send files together with a text message. Turn on **Enable File Attachments** on the **Input** sub-component to activate it, then configure the accepted files and the error copy here.
>
> Hierarchy is **Chat** → **Input** → **File Attachments** → **File Item**. Files the user has already sent appear under **Messages** → **Attached Files** → **File Item**.
>
> | Property | Description | Default |
> | - | - | - |
> | **Accepted file types** | File types the picker accepts, for example `png, jpg, pdf` | All types |
> | **Invalid file message** | Shown on a file whose type is not accepted | — |
> | **Max number of files** | Maximum files per message. The Designer rejects any value above 10 | `10` |
> | **Max files error message** | Shown when the file count is exceeded | — |
> | **Max files size (in bytes)** | Maximum total upload size, for example `5000000` | `5000000` |
> | **Files size error message** | Shown when the size limit is exceeded | — |
>
> > [!WARNING]
> >
> > All six fields are required once file attachments are turned on. The defaults above are the runtime fallbacks the renderer applies when a field is left empty, not values the Designer fills in for you.
>
> **File Item** has no properties of its own. It is the per-file row, and it carries its own default and error styling.
>
> For upload behavior, error handling, and how uploaded files reach the agent, see [File attachments](/5.9/ai-platform/chat-component#file-attachments) in the Chat component reference.

***

## Styling

Configure visual styling through **Theme Admin** (Design Assets → Themes → Components → Chat).

### Themeable elements

| Element | Key properties |
| - | - |
| **Chat container** | Padding, border, background, shadow |
| **Header** | Title/subtitle text styles, separator |
| **Messages area** | Padding, gap between messages |
| **Agent Message** | Avatar icon, text style, background |
| **User Message** | Bubble border, radius, background, text |
| **Suggested Prompts** | Title text style, prompt chip appearance, hover state |
| **Input area** | Border, background, send icon, attach icon |
| **File Attachments / File Item** | Padding, border, radius, background, file name and file info text, delete and download icons, plus an error state on File Item |

> [!TIP]
>
> All styling can be configured in Theme Admin for consistent branding. Changes preview in real-time.

***

## Display modes

> [!NOTE]
>
> The Chat component supports four display modes, including mobile chat and per-mode theme configuration.

When adding a Chat component, you select a display mode that controls how the chat renders and where it can be placed.

| Display mode | Description | Placement |
| - | - | - |
| **Inline** | Renders in place within the page layout (default) | Child of any container or card |
| **Overlay** | Positioned overlay panel with minimize and expand controls | Child of Page or Root Zone |
| **FullScreen** | Takes over the full viewport | Child of Page or Root Zone |
| **Floating** | Floating panel triggered by a FAB (Floating Action Button) | Child of Page or Root Zone |

> [!NOTE]
>
> You can change the display mode after creation if needed.

> [!WARNING]
>
> **Placement constraints:** Inline is only available when the parent is a **Container** or **Card**. Overlay, FullScreen, and Floating are only available when the parent is a **Page** or **Root Zone**. Unavailable options are disabled in the selection dialog.

### Sizing defaults

| Display mode | Default width | Default height | Notes |
| - | - | - | - |
| **Inline** | Fill (parent) | Fill (parent) | Supports Fill or Fixed sizing |
| **Overlay** | Configurable | Configurable | Positioned over content |
| **FullScreen** | Full viewport | Full viewport | No sizing controls |
| **Floating** | `420px` (fixed) | `640px` (fixed) | FAB at `right: 24px`, `bottom: 24px` |

> [!TIP]
>
> For Inline, you can switch between **Fill** and **Fixed** sizing for both width and height. For Floating, width and height are fixed values you can customize in the style panel.

### Floating action button (FAB)

Floating and FullScreen modes include a **Floating Action Button** that triggers the chat. The FAB is configurable in the style panel:

| Property | Default | Description |
| - | - | - |
| **Width** | `56px` | FAB button width |
| **Height** | `56px` | FAB button height |
| **Position** | Right: `24px`, Bottom: `24px` | Fixed position on screen |

#### Notification dot

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When an agent replies while the chat is collapsed, a notification dot appears on the floating action button so users see there is something to read. It clears when the user opens the chat.

Style it in the **Notification Dot** section of the chat style panel. The values apply to both Floating and FullScreen modes.

| Property | Default | Description |
| - | - | - |
| **Height** | `22px` | Dot diameter |
| **Offset X** | `0` | Horizontal offset from its anchor on the button |
| **Offset Y** | `0` | Vertical offset from its anchor on the button |

> [!NOTE]
>
> The dot does not survive a page refresh. If a user reloads the page before opening the chat, the dot clears even though the agent reply is still unread.

### Theming per display mode

Theme values are configured independently per display mode and per platform (Web, Android, iOS) through **Design Assets → Themes → Components → Chat**. Supported properties include padding and margin for each mode.

For complete runtime details, see the [Chat component reference](/5.9/ai-platform/chat-component#display-modes).

***

## Advanced documentation

For comprehensive documentation including runtime behavior, session management, custom persistence workflows, SDK integration, and troubleshooting:

> [card] [Chat component - Full reference](/5.9/ai-platform/chat-component)
>
> Complete technical documentation in AI Platform section

## Related resources

> [card] [Chat interface concepts](/5.9/ai-platform/using-agents/chat-interface)
>
> High-level chat integration patterns

> [card] [AI Triggers](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
>
> Launch chat-driven workflows with structured trigger messages

> [card] [Knowledge bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Ground AI responses in your data

> [card] [AI in FlowX](/5.9/ai-platform/ai-in-flowx)
>
> AI capabilities overview


# Collection Prototype
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/collection/collection-prototype

Create dynamic, data-driven interfaces with different layouts based on item properties using collection prototypes.

> [!NOTE]
>
> Collection prototypes allow you to display items within a collection using different layouts based on their properties, creating more dynamic and context-aware user interfaces.

## What are collection prototypes?

Collection prototypes are specialized components that define different display formats for items within a single collection. They act as templates that are applied conditionally based on item properties, allowing you to:

* Display collection items with different layouts based on their data properties
* Create visually distinct displays for featured or highlighted items
* Apply specialized formatting for different item types or states
* Integrate custom components for enhanced functionality
* Add interactive features like item selection

> [!NOTE]
>
> Collection prototypes always work as child components within a parent [Collection component](../collection). While a Collection iterates through a data array, Collection Prototypes determine how each individual item should be displayed.

## How collection prototypes work

### Core concepts

Collection prototypes use a simple mechanism to determine which layout to apply to each item. The behavior depends on whether you have one or multiple prototypes:

> [card] Prototype Identifier Key (PIK)
>
> The data property used to determine which prototype to apply (e.g., `type`, `status`, `priority`)

> [card] Prototype Identifier Value (PIV)
>
> The specific value that triggers this prototype layout (e.g., `featured`, `active`, `high`)

### When to configure PIK and PIV

> [tab] Single prototype
>
> **Configuration**: PIK and PIV are **optional** and should **not** be configured
>
> > [!NOTE]
> >
> > If you have only one collection prototype, the system will automatically use that prototype for all items in the array, regardless of their properties. In this case, leave both PIK and PIV empty.

> [tab] Multiple prototypes
>
> **Configuration**: PIK and PIV are **required** and **both must be completed**
>
> > [!WARNING]
> >
> > When using multiple collection prototypes, both PIK and PIV must be properly configured for each prototype. The configuration is only valid if both fields are completed.
>
> When the collection renders, each item is evaluated against all available prototypes in order. The first prototype whose identifier key and value match the item's data is used to render that item. If no prototype matches, the item falls back to the first prototype in the collection.

### Visual examples

> [tab] Single prototype scenario
>
> **Use case**: Displaying a list of menu items where all items have the same layout
>
> ```javascript theme={"dark"}
> // Data structure - all items use the same prototype
> [
>   {
>     "name": "Margherita Pizza",
>     "price": 12.99,
>     "description": "Classic tomato and mozzarella"
>   },
>   {
>     "name": "Caesar Salad", 
>     "price": 8.99,
>     "description": "Fresh romaine with parmesan and croutons"
>   }
> ]
> ```
>
> **Configuration**:
>
> * PIK: *(leave empty)*
>
> * PIV: *(leave empty)*
>
> > [!NOTE]
> >
> > Since all items use the same layout, no prototype identification is needed.

> [tab] Multiple prototypes scenario
>
> **Use case**: Restaurant menu with different layouts for main courses vs desserts
>
> ```javascript theme={"dark"}
> // Data structure with type field for prototype identification
> [
>   {
>     "name": "pizza",
>     "type": "main course",
>     "price": 15.99,
>     "ingredients": ["tomato", "mozzarella", "basil"]
>   },
>   {
>     "name": "cremsnit",
>     "type": "dessert", 
>     "price": 6.99,
>     "sweetness": "medium"
>   }
> ]
> ```
>
> **Configuration for main course prototype**:
>
> * PIK: `type`
> * PIV: `main course`
>
> **Configuration for dessert prototype**:
>
> * PIK: `type`
>
> * PIV: `dessert`
>
> > [!TIP]
> >
> > Each item's `type` property determines which prototype layout to use.

![Animated demonstration of collection prototypes rendering different layouts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/render_collection.gif)

Collection with multiple prototypes in action

> [accordion] Normal product display
>
> ![Example of a normal product prototype layout](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype1.png)

> [accordion] Recommended product display
>
> ![Example of a recommended product prototype layout](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype2.png)

## Implementation guide

### 1. Prepare your data

Before implementing collection prototypes, you need to prepare the data structure that will determine which prototype applies to each item.

#### Using a service task node

The most common approach is to use a Service Task node with business rules:

**1. Add a Service Task Node**

In the FlowX.AI Designer, add a **Service Task** node before your User Task node and connect them with a sequence flow.

![Adding a Service Task node to your process](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/task_node_array.png)

Adding a Service Task node

**2. Configure the Business Rule**

Select your Service Task node, go to the **Business Rules** tab, and add a new business rule or edit an existing one.

![Configuring a business rule in a Service Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/prepare_array_of_products.png)

Configuring a business rule

**3. Write the Data Preparation Code**

Use JavaScript to create your data structure and assign it to the process context:

```javascript theme={"dark"}
// Create the data structure for products
const products = [
{
  "name": "Product One Plus",
  "description": "The plus option",
  "type": "normal",  // This property will determine which prototype to use
  "price": 99.99
},
{
  "name": "Product Two Premium",
  "description": "This is premium product",
  "type": "recommended",  // This will use a different prototype
  "price": 149.99
},
{
  "name": "Product Basic",
  "description": "The most basic option",
  "type": "normal",
  "price": 49.99
}
];

// Add the products array to the process data
output.put("products", products);
```

**4. Test Your Data**

Save your configuration, and test your business rule by using the **Test Rule** feature in the business rules editor to make sure the data is correctly added to the process context.

![Verifying business rule output](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/test_your_data.png)

Verifying business rule output

### 2. Create the UI components

Once your data is prepared, you can implement the collection and its prototypes in the UI Designer:

**1. Create a User Task Node**

In the FlowX.AI Designer, create or select an existing **User Task** node in your process and click the **brush icon** to open the UI Designer.

![Opening the UI Designer from a User Task node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_user_task_node_for_collection.gif)

Opening the UI Designer for a User Task node

**2. Add a Collection Component**

Add a **root component** (like a Card or Container) to your node, then add a **Collection** component inside it. Configure the Collection's **source** to point to your data array (e.g., `products`).

![Adding a Collection component in the UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_prototype_source.png)

Adding a Collection component

> [!NOTE]
>
> The `collectionSource` property specifies the process key where your list can be found. It should be a valid array of objects. For example, if your data is at `processData.products`, you would set the source to `products`.

**3. Add Collection Prototypes**

> [tab] Single prototype (simple case)
>
> For a single prototype that applies to all items:
>
> 1. Click on your Collection component to select it
>
> 2. Add a **Collection Prototype** as a child component
>
> 3. **Leave PIK and PIV empty** - no configuration needed
>
> 4. The prototype will automatically apply to all items in the collection
>
> > [!NOTE]
> >
> > This is the most common scenario when all items in your collection should have the same layout.

> [tab] Multiple prototypes (advanced case)
>
> For different display types based on item properties:
>
> 1. Click on your Collection component to select it
> 2. Add a **Collection Prototype** as a child component
> 3. Configure the prototype's settings:
>    * **Prototype Identifier Key**: The field to check (e.g., `type`)
>    * **Prototype Identifier Value**: The value to match (e.g., `normal`)
>
> ![Configuring a Collection Prototype in the UI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_prototype_source1.png)
>
> Configuring a Collection Prototype
>
> 4. Repeat for each different prototype you need, using different identifier values
>
> > [!WARNING]
> >
> > Both PIK and PIV must be configured for each prototype when using multiple prototypes.

**4. Design Each Prototype's Layout**

For each prototype, add the UI components that will display your data:

1. Select a Collection Prototype
2. Add components like **Text**, **Image**, **Button**, etc.
3. Configure each component to use relative paths to the collection item data saved in the Data Model:
   * Use text UI element with the key `${name}`
   * Use text UI element with the key `${description}`

![Adding components to a Collection Prototype](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_prototype_elements.gif)

Adding components to a prototype

> [!NOTE]
>
> Components within a collection use **relative paths** to the collection source. This means that wherever the collection is found inside the process data, the components inside the collection need their keys configured relative to that collection.
>
> ![Relative path configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/collection_relative_key.png)

### 3. Add interactivity

To make your collection items interactive, such as allowing users to select an item:

**1. Create a Node Action**

Add an [Action](../../../actions/actions) to your [User task node](../../../node/user-task-node):

1. Go back to the process designer
2. Select your User Task node
3. Go to the **Actions** tab
4. Add a new action with:
   * Type: **Manual**
   * Name: (e.g., `selectItem`)

![Configuration screen for node action setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/add_interactivity.png)

Adding a Node Action

**Configuration options:**

* Set as **Manual** since users trigger it
* Mark as **Mandatory** if selection is required to proceed
* Enable **Repeatable** for changeable selections

**2. Configure an event handler**

Add an event handler to your collection prototype:

1. Return to the UI Designer
2. Select the component in your prototype that should trigger the action
3. In the Settings panel, add an event handler
4. Add a  **Collection Item Save Key**.
5. Add a **Custom Key** and make sure it matches the **Collection Item Save Key**.

![Configuration screen for event handler setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/collection_item_save_key.png)

Adding an event handler

**3. Test the Interaction**

Save your changes and test your process to verify that:

* Different items display with the correct prototype layouts
* Interactive elements work as expected
* Selected data is properly saved to your process data

> [accordion] Before selection
>
> ![Process data state before item selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype_result.png)

> [accordion] After selection
>
> ![Process data state after item selection showing selected product data](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/c.prototype_result_final.png)

## Best practices

### Working with custom components

> [!TIP]
>
> When integrating custom components into collection prototypes, follow these best practices:

1. **Use relative paths for data access**
   * Configure input keys relative to collection items
   * Example: Use `name` instead of `app.clients.name`

2. **Maintain consistent data structures**
   * Ensure required data exists in collection items
   * Follow consistent data patterns across all items

### Data access patterns

> [tab] Outside collections
>
> Components use full paths from data root:
>
> ```jsx theme={"dark"}
> // Input keys:
> // app.name
> // app.signatureImageURL
>
> data: {
>     app: {
>         name: "John Doe",
>         signatureImageURL: "http://example.com/signature1.png"
>     }
> }
> ```

> [tab] Inside collections
>
> Components use relative paths:
>
> ```jsx theme={"dark"}
> // Input keys:
> // name
> // signatureImageURL
>
> data: {
>     name: "John Doe",
>     signatureImageURL: "http://example.com/signature1.png"
> }
> ```

### Performance optimization

* Limit the number of items in your collection when possible
* Simplify complex prototype layouts
* Consider pagination for large data sets
* Optimize images and other media within prototypes
* Avoid deeply nested components within prototypes

> [!TIP]
>
> **Pro tips:**
>
> * Test your collection prototypes with various data scenarios
> * Verify data flow through the entire selection process
> * Monitor the process data for correct updates
> * Ensure your UI provides clear visual feedback when an item is selected

## Troubleshooting

When working with collection prototypes, you might encounter some common issues:

### Common issues and solutions

> [accordion] Prototype not displaying correctly
>
> **Symptoms:**
>
> * Collection items appear with incorrect layouts
> * All items use the same prototype regardless of identifier values
> * Some items don't render at all
>
> **Solutions:**
>
> **For single prototype scenarios:**
>
> * Ensure PIK and PIV fields are **left empty** - they should not be configured
> * If you accidentally configured PIK/PIV for a single prototype, clear both fields
>
> **For multiple prototype scenarios:**
>
> * Verify that your **Prototype Identifier Key** exactly matches the property name in your data
>
> * Ensure the **Prototype Identifier Value** matches the expected values in your data
>
> * **Both PIK and PIV must be configured** - partial configuration will not work
>
> * Check for case sensitivity issues in both keys and values
>
> * Validate your data structure using the process debugger
>
> * Confirm that the parent Collection component has the correct source path
>
> > [!WARNING]
> >
> > Configuration is only valid when both PIK and PIV are properly completed for multiple prototypes, or both are left empty for single prototypes.

> [accordion] Event handlers not working
>
> **Symptoms:**
>
> * Clicking on items doesn't trigger the expected action
> * Selected data isn't saved to the process
> * No visual feedback when items are selected
>
> **Solutions:**
>
> * Confirm that the **Collection Item Save Key** matches exactly with the **Data to send** field in your node action
> * Verify that your node action is properly configured as **Manual** and **Repeatable** if needed
> * Check that the event handler is attached to the correct element within the prototype
> * Ensure the node action has the correct permissions and is properly linked
> * Verify that your root UI element includes the necessary Message parameters to pass data

> [accordion] Data binding issues
>
> **Symptoms:**
>
> * Components inside prototypes show empty or incorrect data
> * Dynamic content doesn't update properly
> * Error messages in the console related to undefined properties
>
> **Solutions:**
>
> * Remember that components inside collections must use relative paths (e.g., `name` instead of `app.clients.name`)
> * Verify your data structure matches what the components expect
> * Use the process debugger to inspect the actual data being passed to the collection
> * Check for null or undefined values that might cause rendering issues
> * Ensure your data is properly structured as an array of objects

### Known limitations

> [!WARNING]
>
> * **Nested collections** (collections inside collection prototypes) may cause performance issues and should be used sparingly
> * **Deep data structures** might require careful handling of relative paths for proper data binding

### Debugging tips

1. **Use process data inspection:**
   * Monitor the process data before and after interactions with collection prototypes
   * Verify that selected items are correctly saved to the expected process data keys

2. **Test with simplified data:**
   * Start with a minimal data set to confirm basic functionality
   * Gradually add complexity to identify where issues might occur

3. **Isolate components:**
   * Test individual UI components outside the collection context
   * Add components to prototypes one by one to identify problematic elements

## Frequently asked questions

> [accordion] Can I use different layouts for mobile and desktop?
>
> Yes, you can create platform-specific overrides for your collection prototypes. Configure different layouts, spacing, and styling for Web, iOS, and Android platforms through the platform tabs in the UI Designer.

> [accordion] How do I handle missing identifier values?
>
> Items that don't match any prototype still render: the renderer falls back to the first prototype in the collection. To control the fallback layout explicitly, add a prototype with no identifier key or value as the **last** prototype. A key-less prototype matches every item, so items skipped by the specific prototypes above it will use it. Don't place a key-less prototype first, since prototypes are evaluated in order and it would match all items before the specific ones are considered.

> [accordion] When should I configure PIK and PIV vs leaving them empty?
>
> **Leave PIK and PIV empty** when:
>
> * You have only one collection prototype
> * All items in your collection should use the same layout
>
> **Configure both PIK and PIV** when:
>
> * You have multiple collection prototypes
>
> * Different items should display with different layouts based on their properties
>
> * Both fields must be completed for the configuration to work
>
> > [!NOTE]
> >
> > This logic has been unchanged since 2021 and is a fundamental aspect of how collection prototypes work.

> [accordion] Can I use expressions in prototype identifier values?
>
> No, prototype identifier values must be static strings that exactly match the values in your data. However, you can transform your data before it reaches the collection to achieve dynamic prototype selection.

> [accordion] Is there a limit to how many prototypes I can define?
>
> There's no hard limit on the number of prototypes, but for performance and maintainability reasons, it's recommended to keep the number reasonable (typically under 5-7 different prototypes).

> [accordion] What's the difference between Collection and Collection Prototype?
>
> A **Collection** is a container that iterates through an array of data items, while a **Collection Prototype** defines how each individual item should be displayed based on its properties. You need at least one Collection Prototype inside a Collection, but you can have multiple prototypes to handle different item types or states.

## Code examples

### Different prototype layouts based on item status

This example shows how to display items differently based on their status (active, pending, completed):

```java Process Data Setup theme={"dark"}
// Setting up process data with items of different statuses
output.put("processData", {
  "tasks": [
    {
      "id": "task-001",
      "title": "Review application",
      "description": "Initial review of customer application",
      "status": "active",
      "priority": "high"
    },
    {
      "id": "task-002",
      "title": "Verify documents",
      "description": "Check submitted documentation for completeness",
      "status": "pending",
      "priority": "medium"
    },
    {
      "id": "task-003",
      "title": "Send confirmation",
      "description": "Email confirmation to customer",
      "status": "completed",
      "priority": "low"
    }
  ]
});
```

```javascript Collection Configuration theme={"dark"}
// Collection component configuration
{
  "type": "COLLECTION",
  "settings": {
    "source": "tasks",
    "direction": "vertical"
  },
  "children": [
    // Active task prototype
    {
      "type": "COLLECTION_PROTOTYPE",
      "settings": {
        "prototypeIdentifierKey": "status",
        "prototypeIdentifierValue": "active"
      },
      "children": [
        // Active task UI elements with highlighted styling
      ]
    },
    // Pending task prototype
    {
      "type": "COLLECTION_PROTOTYPE",
      "settings": {
        "prototypeIdentifierKey": "status",
        "prototypeIdentifierValue": "pending"
      },
      "children": [
        // Pending task UI elements with standard styling
      ]
    },
    // Completed task prototype
    {
      "type": "COLLECTION_PROTOTYPE",
      "settings": {
        "prototypeIdentifierKey": "status",
        "prototypeIdentifierValue": "completed"
      },
      "children": [
        // Completed task UI elements with muted styling
      ]
    }
  ]
}
```

### Multiple identifier keys for complex conditions

You can use multiple collection prototypes with different identifier keys to handle complex display logic:

```java Process Data with Multiple Attributes theme={"dark"}
// Setting up process data with items having multiple attributes
output.put("processData", {
  "notifications": [
    {
      "id": "notif-001",
      "message": "Your application has been approved",
      "type": "success",
      "priority": "high",
      "read": false
    },
    {
      "id": "notif-002",
      "message": "Please review updated terms",
      "type": "info",
      "priority": "low",
      "read": true
    },
    {
      "id": "notif-003",
      "message": "Action required: Missing information",
      "type": "warning",
      "priority": "high",
      "read": false
    }
  ]
});
```

```javascript Multiple Prototype Configuration theme={"dark"}
// Collection with multiple prototype conditions
{
  "type": "COLLECTION",
  "settings": {
    "source": "notifications",
    "direction": "vertical"
  },
  "children": [
    // High priority unread success notification
    {
      "type": "COLLECTION_PROTOTYPE",
      "settings": {
        "prototypeIdentifierKey": "type",
        "prototypeIdentifierValue": "success",
        "additionalConditions": [
          {
            "key": "priority",
            "value": "high"
          },
          {
            "key": "read",
            "value": false
          }
        ]
      },
      "children": [
        // UI elements for high priority unread success notifications
      ]
    },
    // Other prototypes for different combinations...
  ]
}
```

### Nested data structures

Working with nested data in collection prototypes:

```java Nested Data Structure theme={"dark"}
// Setting up process data with nested objects
output.put("processData", {
  "orders": [
    {
      "id": "order-001",
      "customer": {
        "name": "John Smith",
        "tier": "premium"
      },
      "items": [
        { "name": "Product A", "quantity": 2 },
        { "name": "Product B", "quantity": 1 }
      ],
      "status": "processing"
    },
    {
      "id": "order-002",
      "customer": {
        "name": "Jane Doe",
        "tier": "standard"
      },
      "items": [
        { "name": "Product C", "quantity": 3 }
      ],
      "status": "shipped"
    }
  ]
});
```

```javascript Accessing Nested Data theme={"dark"}
// Collection prototype accessing nested data
{
  "type": "COLLECTION",
  "settings": {
    "source": "orders",
    "direction": "vertical"
  },
  "children": [
    // Premium customer prototype
    {
      "type": "COLLECTION_PROTOTYPE",
      "settings": {
        "prototypeIdentifierKey": "customer.tier",
        "prototypeIdentifierValue": "premium"
      },
      "children": [
        // UI elements for premium customers
        {
          "type": "TEXT",
          "settings": {
            "text": "Premium Customer",
            "style": "heading"
          }
        },
        {
          "type": "TEXT",
          "settings": {
            "text": "${customer.name}",
            "style": "subheading"
          }
        },
        // Collection for order items
        {
          "type": "COLLECTION",
          "settings": {
            "source": "items",
            "direction": "horizontal"
          },
          "children": [
            // Item prototype
            {
              "type": "COLLECTION_PROTOTYPE",
              "settings": {},
              "children": [
                {
                  "type": "TEXT",
                  "settings": {
                    "text": "${name} (${quantity})",
                    "style": "body"
                  }
                }
              ]
            }
          ]
        }
      ]
    },
    // Standard customer prototype
    {
      "type": "COLLECTION_PROTOTYPE",
      "settings": {
        "prototypeIdentifierKey": "customer.tier",
        "prototypeIdentifierValue": "standard"
      },
      "children": [
        // UI elements for standard customers
      ]
    }
  ]
}
```

## Related components

> [card] [Collection Component](../collection)
>
> The parent component that iterates through data arrays and contains Collection Prototypes

> [card] [Event Handlers](../../event-handlers)
>
> Add interactivity to Collection Prototypes — run actions on click, or use Run Local Script to update local data when an item is clicked


# File download
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download

Let end users download a file from a rendered app using the Download component.

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Download** component renders as a button that downloads a file when the end user clicks it — for example, a generated contract, an uploaded document, or a static form. You configure which file it serves through the component's **Download** action.

![Download component in the UI Designer: palette entry, canvas, and settings with the Download action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/download_ui_comp.png)

## Configuring a Download component

The component sits in the **Basic** category of the component palette. Drop it inside a container or card — it is available in both process user tasks and UI Flows, on web and mobile layouts, including collection prototypes and headers/footers. It cannot be placed directly inside forms or table cells.

### Properties

* **Label**: The button text. **Default:** `Download`
* **Save-as File Name**: Optional file name used when saving the downloaded file (e.g., `MyFile.pdf`); supports `${}` expressions. When left empty, files stored in the Documents plugin keep their original file name.
* **Toast notification on success**: Toggle **ON** to show a confirmation toast after the download completes, with a configurable **Success Message** (default: `File downloaded`).
* **Toast notification on error**: Toggle **ON** to show a toast when the download fails, with a configurable **Error Message** (default: `There was an error downloading the file`).
* **Loading behavior**: **None** or **Overlay**. With **Overlay**, a loading indicator with a configurable **Loading message** (default: `Downloading...`) is shown while the file is being fetched.

> [!NOTE]
>
> The notification and loading options apply to the web renderer. On Android they are not available — the component downloads the file without toasts or a loading overlay.

### Selecting the file to download

The Download component offers a single **Download** action on click, added in the component's **Event Handlers** section. The **File source** select determines where the file comes from:

* **Media Library**: Serve a PDF document from the project's Media Library — pick one with **Select from Media Library** or add a new one with **Upload to Media Library**.
* **Process Data** (in a process) / **Local Variables** (in a UI Flow): Point to the data key where the document reference is found. In a process, the value at that key is used as-is, so it must be a complete, absolute URL. The `downloadPath` in an upload or document-generation reply is relative, so build the URL in a business rule first, as shown in [Preview an uploaded file](./file-preview#preview-an-uploaded-file). In a UI Flow, an additional **Location** select declares whether the key holds a **URL** or a **Document plugin** reference. With **Document plugin**, point to the object that contains `downloadPath`, for example an upload reply, and the renderer builds the URL. Inside a collection prototype, the key resolves against the row the component is rendered in, so every row of a list serves its own file.
* **Static**: A fixed URL of the document.

> [!NOTE]
>
> Files stored in the Documents plugin (and FlowX download URLs) are fetched and saved directly with the resolved file name. A plain external URL opens in a new browser tab instead of downloading, and the success/error notifications do not apply to it.

> [!WARNING]
>
> **Serve stored files through this component rather than through a link of your own.** A file held by the Documents plugin is served over the app's authenticated session, and the Download component fetches it that way. A plain browser navigation to the same address sends no credentials, so reusing a stored file's download path in a **Static** URL, or in a link or button wired by hand, returns an authorization error instead of the file.

### File sources in FlowX.AI 5.13

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Starting with FlowX.AI 5.13, the **Download** action uses the same source options as [File Preview](./file-preview#file-sources-in-flowx-ai-5-13). **Process Data**, **Local Variables**, **Static**, and the **Location** select are replaced by these sources:

* **Media Library**: a PDF from the project's Media Library.
* **Document Plugin Path** (process user tasks): a Documents plugin `downloadPath`, such as the one in an upload reply. The renderer adds the Documents plugin base URL, so you don't need a business rule to build the URL.
* **Document Plugin** (UI Flows): the object that contains `downloadPath`, for example an upload reply. When **Save-as File Name** is empty, the file keeps its original file name.
* **URL**: a complete, absolute URL.

For **Document Plugin Path** and **URL**, **Value Type** sets where the value comes from: **Static** for a fixed value, or **Variable** to read it from a data key. **Document Plugin** always reads a data key.

With **Document Plugin Path**, the file is saved as `document` unless you set **Save-as File Name**.

![Download event handler on a File Download component, with Source set to Document Plugin Path and Data key set to downloadPath](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5-13-download-document-plugin-path.png)

### Styling

The Download component renders as a button and reuses button styling: a **Type** (default `ghost`), an optional **Icon** with configurable position, and valid CSS properties per platform. For more information, see the [styling documentation](../../ui-designer/ui-designer#styles-tab).

## Platform support

Configured in the FlowX Designer, with runtime support on the **web** and **Android** renderers.

## Related resources

> [card] [File preview](./file-preview)
>
> Preview file contents inside a UI without opening the file

> [card] [Multiple file upload](./multiple-file-upload)
>
> Let users upload one or more files from a rendered app


# File preview
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview

Preview file contents inside a UI flow without fully opening the file, using the File Preview component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview.gif)

The File Preview component displays a document's contents directly on a UI Flow page, so users can read it without downloading or opening it separately. The file can come from the Media Library, from process data, or from a static URL, and it renders inline (optionally in an accordion) or in a modal. This page covers the component's web and mobile properties and its styling options.

## Configuring a File preview element

A File Preview element can be configured for both mobile and web applications.

### File preview properties (web)

![File Preview settings with Title, Display mode, Has accordion, Default view, and Source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/12-file_preview_info.png)

Captured in the FlowX.AI 5.13 Designer, where Source Type is labeled Source and lists the 5.13 sources. See File sources in FlowX.AI 5.13 below.

The settings for the File Preview element include the following properties:

* **Title**: Specifies the title of the element. If the file is downloaded or shared, the file name should serve as the title used in the preview component.
* **Subtitle**: Allows for the inclusion of a subtitle for the element.
* **Display mode**: Depending on the selected display method, the following properties are available:
  * **Inline** → **Has accordion**:
    * `false`: Displays the preview inline without an expand/collapse option.
    * `true` (Default View: Collapsed): Displays the preview inline with an expand/collapse option, initially collapsed.
    * `true` (Default View: Expanded): Displays the preview inline with an expand/collapse option, initially expanded.

  * **Modal** → view icon is enabled
* **Has accordion**:  Introduces a Bootstrap accordion, facilitating the organization of content within collapsible items. It ensures that only one collapsed item is displayed at a time.
* **Source Type**:
  * **Media Library**: Refers to PDF documents uploaded in the Media Library.

> [!NOTE]
>
> PDF documents uploaded to the Media Library must adhere to a maximum file size limit of 10 MB.

* **Process Data**: Identifies the key location within the process where the document is sourced, establishing the linkage between the document and process data. The value at that key is used as-is, so it must be a complete, absolute URL. The renderer attaches the user's access token only when the URL ends in `download`. To preview a file uploaded through the Documents plugin, see [Preview an uploaded file](#preview-an-uploaded-file).
* **Static**: Denotes the document's URL, serving as a fixed reference point.

> [!WARNING]
>
> It's worth noting that the inline modal view can raise accessibility issues if the file preview's height exceeds the screen height.

### File preview properties (mobile)

> [!TIP]
>
> Both iOS and Android devices support the share button.

#### iOS

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview_ios.gif)

#### Android

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview_android.gif)

### File preview styling

The File Preview styling property enables you to customize the appearance of the element by adding valid CSS properties. For more information, see the [styling documentation](../../ui-designer/ui-designer#styles-tab).

When drag and drop a File Preview element in UI Designer, it comes with the following default styling properties:

#### Sizing

* **Fit W** - auto
* **Fit H** - fixed / Height - 400 px

![File Preview Styles tab with the default sizing](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/13-doc_preview_styling.png)

## File Preview example

Below is an example of a File Preview UI element with the following properties:

* **Display mode** - Inline
* **Has accordion** - True
* **Default view** - Expanded
* **Source Type** - Static

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/doc_preview_example.gif)

***

## Preview an uploaded file

When a user uploads a file with a File Upload component, the Documents plugin stores it and replies on its persist reply topic. The reply doesn't contain a URL that File Preview can load directly:

* `downloadPath` is relative, for example `internal/files/{fileId}/download`.
* `filePath` is the object path in file storage (MinIO or S3), not a URL.

Build the absolute URL in a business rule, then bind File Preview to the result.

**1. Receive the upload reply**

Configure the upload as described in [Creating and uploading a new document](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document). On the node that receives the reply, add an **Integration Output** data stream (**Source**: **Custom Topic**) with the persist reply topic and a key, for example `uploadedDocument`.

**2. Build the absolute URL**

Add a business rule that prefixes `downloadPath` with the Documents plugin base URL and stores the result under a new key:

```javascript theme={"dark"}
adminPath = "https://{your-flowx-api-host}/document/";
downloadPath = input.?uploadedDocument.?downloadPath;

if (downloadPath != null) {
    output.put("preview", {
        "filePath": adminPath + downloadPath
    });
}
```

The example uses MVEL. `{your-flowx-api-host}` is the host that serves the FlowX APIs to your renderer. The Documents plugin is exposed on it under `/document`, as listed in the [ingress service route reference](/5.9/setup-guides/ingress-configuration#service-route-reference).

**3. Bind File Preview to the URL**

On the user task that shows the file, set the File Preview **Source Type** to **Process Data** and the key to `preview.filePath`.

***

## File sources in FlowX.AI 5.13

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Starting with FlowX.AI 5.13, the File Preview sources align with the other file components. In a process user task, **Source** offers three options:

* **Media Library**: a PDF from the project's Media Library.
* **Document Plugin Path**: a Documents plugin `downloadPath`, such as the one in an upload reply. The renderer adds the Documents plugin base URL, so you don't need a business rule to build the URL.
* **URL**: a complete, absolute URL.

For **Document Plugin Path** and **URL**, **Value Type** sets where the value comes from: **Static** for a fixed value, or **Variable** to read it from a process data key.

To preview an uploaded file, set **Source** to **Document Plugin Path**, **Value Type** to **Variable**, and **Data key** to the `downloadPath` in the upload reply, for example `uploadedDocument.downloadPath`.

![File Preview settings with Source set to Document Plugin Path, Value Type set to Variable, and Data key set to uploadedDocument.downloadPath](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/file_preview_document_plugin_path_source.png)

***

## Preview files in a collection

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When users upload several files at once with a [Multiple File Upload](./multiple-file-upload) component, the Documents plugin returns every file in one bulk reply. To show one File Preview per uploaded file, place File Preview inside a [Collection](./collection/collection) bound to that reply. The user stays on the same user task: the files appear after the upload, with no submit.

**1. Add the Upload File action**

On the user task, add an [Upload File action](../../actions/upload-file-action), for example `uploadDocs`, with these parameters:

* **Topics**: the Documents plugin bulk persist topic, by default `ai.flowx.plugin.document.trigger.persist.document.bulk.v1`.
* **Document Tag**: `BULK`.
* **Folder**: the value that groups the files, for example `${processInstanceId}`.
* **Headers**: `{"processInstanceId": ${processInstanceId}, "destinationId": "uploadDocuments", "callbacksForAction": "uploadDocs"}`. `destinationId` is the name of the user task node, and `callbacksForAction` is the name of the Upload File action.

In the node's **Actions** list, drag the Upload File action above any mandatory manual action, such as the `saveData` action the user task creates. The process engine rejects the upload while a mandatory action placed above it hasn't run.

**2. Connect the Multiple File Upload component**

On the Multiple File Upload component, add an event handler with **Event type** `CLICK` and **Action type** **Upload**, and select the Upload File action.

**3. Receive the bulk reply**

On the same node, add an **Integration Output** data stream with **Source** set to **Custom Topic**, the bulk reply topic `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1`, and a key, for example `docs`. The reply stores the files as a list under `docs.documents`, one entry per file, each with its own `downloadPath`.

**4. Send the reply to the user task**

Add a child action under the Upload File action, of type **Send data to user interface**, with the message `{"docs": ${docs}}`. It runs when the bulk reply arrives and refreshes the user task with the uploaded files.

**5. Bind the collection and File Preview**

Add a Collection with source `docs.documents`, and a collection prototype with identifier key `documentType` and value `BULK`. Inside the prototype, add a File Preview with **Source** set to **Document Plugin Path**, **Value Type** set to **Variable**, and **Data key** set to `downloadPath`.

> [!TIP]
>
> Inside a collection prototype, keys resolve against the current item, so the data key is `downloadPath`. The key suggestions list full paths such as `docs.documents.downloadPath`: type the relative key instead of picking a suggestion.

![Upload documents user task at runtime with a Multiple File Upload drop zone and a File Preview of the uploaded invoice](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/19-file_preview_collection_runtime.png)

***

## Event handlers

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1.**

The File Preview component supports two scroll-based [event handler](../event-handlers) triggers, handled by the web and Android renderers:

* **On Scroll**: fires as the user scrolls within the previewed document.
* **On Document End**: fires when the user reaches the end of the document.

![File Preview scroll and document end event handlers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/file_preview_document_end_scroll_ev_handlers.png)

A common use is consent and disclosure: keep a **Submit** or **Accept** action hidden or disabled until an On Document End handler confirms the user reached the end of the document. The handler can be a simple local script that sets a flag enabling the action.


# Checkbox
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/checkbox-form-field

A checkbox form field is an interactive element in a web form that provides users with multiple selectable options. It allows you to choose one or more options from a pre-determined set by checking the corresponding checkboxes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_new.png)

This type of form field can be used to gather information such as interests, preferences, or approvals, and it provides a simple and intuitive way for users to interact with a form.

## Configuring the Checkbox element

### Checkbox generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#hide/disable-expressions)
* [**Event handlers**](#event-handlers)
* [**Checkbox styling**](#checkbox-styling)

#### Process data key

Process data key establishes the binding between the checkbox element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node).

#### Properties

* **Label**: The visible label for the checkbox.
* **Helpertext**: Additional information about the checkbox element, which can be optionally hidden within an infopoint.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_props.png)

#### Datasource configuration

* **Default value**: The default value of the checkbox.
* **Source Type**: The source can be Static, Enumeration, or Process Data.
* **Add option** : Define label and value pairs here.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_datasource.png)

#### Validators

The following validators can be added to a checkbox: `required` and `custom`. For more information, see the [validators documentation](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_validators.png)

#### Hide/disable expressions

The checkbox behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the checkbox element when it evaluates to the specified result.
* **Disabled condition**: A JavaScript expression that disables the checkbox when it returns a truthy value.

These expressions can be used with any form element. See the following example for details:

> [card] [Input hide/disabled example](./input-form-field#hide/disable-expressions)

> [!NOTE]
>
> It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

#### Event handlers

Event handlers can be added to the checkbox element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

> [!NOTE]
>
> For more information, see the [Event Handlers documentation](../../event-handlers).

### Checkbox settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the checkbox label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

> [!TIP]
>
> Overrides can always be imported/pushed from one platform to another:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

### Checkbox styling

> [tab] Web
>
> > [tab] Properties
> >
> > * **Type**: Set the type of the checkbox. Possible values:
> >
> >   * bordered
> >   * clear
>
> > [tab] Sizing
> >
> > Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
> >
> > * **fill**: Fills the available space.
> > * **fixed**: Maintains a fixed width.
> > * **auto**: Adjusts the width automatically based on content.
>
> > [tab] Layout
> >
> > * **Direction**: Determines the orientation of the layout, which can be either horizontal or vertical.
> > * **Gap**: Specifies the size of the space between rows and columns.
> > * **Columns**: Indicates the number of columns in the layout.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.

#### Checkbox style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)

Style options:

> [accordion] Common Properties
>
> * Border radius **\[TEXT]**
> * Border width  **\[TEXT]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_common.png)

> [accordion] Label
>
> * Default state
>   * Text color **\[COLOR]**
> * Disabled state
>   * Text color  **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)

> [accordion] Helper
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
> * Helper Tooltip
>   * Text style **\[FONT]**
>   * Text color **\[COLOR]**
>   * Background color **\[COLOR]**
>   * Icon Color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)

> [accordion] Error
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)

> [accordion] Unselected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)

> [accordion] Selected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)

> [accordion] Disabled Unselected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)

> [accordion] Disabled Selected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)

> [accordion] Hover Unselected State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_unselected_state.png)

> [accordion] Hover Selected State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_selected_state.png)

> [!NOTE]
>
> You can import or push the overrides from one platform to another without having to configure them multiple times.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)


# Datepicker
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/datepicker-form-field

The datepicker (Calendar Picker) is a lightweight component that allows end users to enter or select a date value.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker_form_field.png)

The datepicker (Calendar Picker) is a lightweight component that allows end users to enter or select a date value.

> [!NOTE]
>
> The default datepicker value is `DD.MM.YYYY`.

## Configuring the datepicker element

### Datepicker generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#hide/disable-expressions)
* [**Event handlers**](#event-handlers)
* [**Datepicker styling**](#datepicker-styling)

#### Process data key

Process data key establishes the binding between the datepicker element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node).

#### Properties

* **Label**: The visible label for the datepicker element.
* **Placeholder**: Text that appears within the datepicker element when it is empty.
* **Min Date**: Set the minimum valid date selectable in the datepicker.
* **Max Date**: Set the maximum valid date selectable in the datepicker.
* **Min Date, Max Date error**: When a date is introduced by typing, define the error message to be displayed.
* **Helpertext**: Additional information about the datepicker element, which can be optionally hidden within an infopoint.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker1.png)

#### Datasource configuration

**Default Value**: The default values of the datepicker element, this will autofill the datepicker when you will run the process.

#### Validators

The following validators can be added to a datepicker: `required`, `custom`, `isSameOrBeforeToday` or `isSameOrAfterToday`. For more information, see the [validators documentation](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker2.png)

#### Hide/disable expressions

The datepicker behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the datepicker element when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the datepicker element when it returns a truthy value.

> [!NOTE]
>
> It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

#### Event handlers

Event handlers can be added to the datepicker element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the action type.

> [!TIP]
>
> For more information, see the [Event Handlers documentation](../../event-handlers).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/datepicker3.png)

### Datepicker settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the datepicker label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

> [!TIP]
>
> Overrides can always be imported/pushed from one platform to another:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

### Datepicker styling

> [tab] Web
>
> #### Sizing
>
> Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
>
> * **fill**: Fills the available space.
> * **fixed**: Maintains a fixed width.
> * **auto**: Adjusts the width automatically based on content.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.
>
> However, for mobile applications, there’s an additional sizing style property:
>
> * **Height** (pt - points): Determines the vertical size of the datepicker element on the screen.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.
>
> However, for mobile applications, there’s an additional sizing style property:
>
> * **Height** (dp - density-independent pixels): Determines the vertical size of the datepicker element on the screen.

#### Datepicker style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_all.png)

Style options:

> [accordion] Common Properties
>
> * Border radius **\[TEXT]**
> * Border width  **\[TEXT]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_com_props.png)

> [accordion] Label
>
> * Default state
>   * Text color **\[COLOR]**
> * Disabled state
>   * Text color  **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_label.png)

> [accordion] Helper
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
> * Helper Tooltip
>   * Text style **\[FONT]**
>   * Text color **\[COLOR]**
>   * Background color **\[COLOR]**
>   * Icon Color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_helper.png)

> [accordion] Error
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_error.png)

> [accordion] Empty State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_empty_state.png)

> [accordion] Active State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_active_state.png)

> [accordion] Filled State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_filled_state.png)

> [accordion] Disabled State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_disabled_state.png)

> [accordion] Error State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ovselect_error_state.png)

> [accordion] Hover State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_hover-state.png)

> [!NOTE]
>
> You can import or push the overrides from one platform to another without having to configure them multiple times.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)


# Input field
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field

Enable users to input and validate various types of data with flexible configuration options and platform-specific customization.

An input field is a versatile form element that enables users to enter data with built-in validation, conditional visibility, and cross-platform compatibility. Input fields can be customized for different data types and use cases, from simple text entry to specialized formats like email addresses and code snippets.

![Input field demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_element.png)

## Configuration overview

Configure your input field using these main sections:

> [card] Basic Settings
>
> Process data binding, labels, and input types

> [card] Data & Validation
>
> Default values, validators, and data formatting

> [card] Behavior
>
> Hide/disable conditions and event handlers

> [card] Styling
>
> Visual appearance and platform-specific overrides

## Basic configuration

### Process data key

The process data key establishes the binding between the input element and process data, enabling its later use in:

* [Decision nodes](../../../node/exclusive-gateway-node)
* [Business rule actions](../../../actions/business-rule-action/business-rule-action)
* [Integration tasks](../../../node/message-send-received-task-node)

### Core properties

> [accordion] Label
>
> **Purpose**: The visible text displayed above or alongside the input field
>
> **Features**:
>
> * Supports full Markdown syntax for rich formatting
>
> * Can include links, emphasis, and other Markdown elements
>
> * Responsive across all platforms
>
> > [!TIP]
> >
> > Use Markdown to enhance your labels with **bold**, *italic*, or [linked text](https://www.markdownguide.org/cheat-sheet/).
>
> ![Label with Markdown formatting](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/label_attributed.png)

> [accordion] Input Types
>
> Choose the appropriate input type for your data:
>
> | Type | Description | Validation Features | Best Used For |
> | - | - | - | - |
> | **Text** | General text input | Length, pattern matching | Names, titles, descriptions |
> | **Number** | Numeric values only | Min/max values, decimals | Quantities, prices, scores |
> | **Email** | Email address format | Built-in email validation | Contact information |
> | **Password** | Masked text input | Strength requirements | Authentication, security |
> | **Code** | Digits-only input | Only digits allowed | OTP codes, PIN numbers, postal codes, verification codes |
>
> > [!NOTE]
> >
> > The **Code** input type accepts only digit characters during input and stores the value as a **string** (not as a number). This is ideal for numeric codes that should be treated as text, such as OTP codes, PIN numbers, postal codes, or verification codes where leading zeros or string formatting is important.
>
> > [!TIP]
> >
> > Use **Code** instead of **Number** when you need numeric-only input but want to preserve the value as a string in your data model. This is particularly useful for cases where:
> >
> > * Leading zeros must be preserved (e.g., "001234")
> > * The value is an identifier rather than a mathematical number
> > * You need string operations on numeric values
>
> **Code Type Technical Details**:
>
> * **Input behavior**: Only allows digits (0-9) to be typed
> * **Data storage**: Saves the value as a string data type
> * **Data model support**: String data model types only
> * **Value formatting**: No automatic formatting is applied to the displayed value
> * **Common use cases**: OTP validation, PIN entry, postal codes, verification codes
>
> ```json theme={"dark"}
> {
>   "inputType": "code",
>   "label": "Enter verification code",
>   "placeholder": "000000"
> }
> ```

> [accordion] Placeholder Text
>
> **Purpose**: Provide hints or examples of expected input
>
> **Best Practices**:
>
> * Keep it concise and helpful
> * Show format examples (e.g., "[john@example.com](mailto:john@example.com)")
> * Avoid using placeholder as primary label
> * Consider accessibility for screen readers

> [accordion] Prefix & Suffix
>
> **Prefix**: Text or symbols appearing before the input
>
> * Currency symbols (\$, €, £)
> * Protocol indicators (https\://, @)
> * Unit prefixes
>
> **Suffix**: Text or symbols appearing after the input
>
> * Units of measurement (kg, cm, %)
> * Domain extensions (.com, .org)
> * Contextual indicators
>
> **Examples**:
>
> ```
> $ [input field] USD    // Prefix: $, Suffix: USD
> @ [input field]        // Prefix: @
> [input field] %        // Suffix: %
> ```

> [accordion] Additional Features
>
> **Has Clear**: Adds an ✕ button to quickly clear the input content
>
> * Improves user experience on mobile devices
> * Useful for search fields and optional inputs
>
> **Helper Text**: Additional context or instructions
>
> * Can be displayed as regular text below the field
> * Can be hidden within an expandable info point
> * Supports Markdown formatting
>
> **Update on Blur**: Controls when data is saved
>
> * Triggers validation when user leaves the field
> * Optimizes performance by reducing frequent updates

## Data configuration

### Datasource configuration

Configure the data source and default values for your input field:

**Default Value**: Set the initial value when the field is first displayed

* Static values for consistent defaults
* Dynamic values from process data
* Calculated values from expressions

![Default value](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_datasource1_new.png)

> [!WARNING]
>
> Consider the user experience impact of default values - they should help users rather than create confusion.

### Validation rules

Ensure data quality with comprehensive validation options:

> [tab] Basic Validators
>
> | Validator | Purpose | Configuration |
> | - | - | - |
> | **Required** | Ensures field is not empty | Error message customization |
> | **Min Length** | Minimum character count | Specify minimum number |
> | **Max Length** | Maximum character count | Specify maximum number |
> | **Email** | Valid email format | Works with email input type |
> | **Pattern** | Custom regex validation | Define regex pattern |

> [tab] Numeric Validators
>
> | Validator | Purpose | Use Case |
> | - | - | - |
> | **Min Value** | Minimum numeric value | Age limits, prices |
> | **Max Value** | Maximum numeric value | Quantity limits, scores |
> | **Decimal Places** | Control decimal precision | Currency, measurements |

> [tab] Date Validators
>
> | Validator | Purpose | Application |
> | - | - | - |
> | **Past Date** | Date must be in the past | Birth dates, historical events |
> | **Future Date** | Date must be in the future | Appointments, deadlines |
> | **Date Range** | Within specific date range | Event scheduling, availability |

> [tab] Custom Validators
>
> **Purpose**: Complex business logic validation
>
> **Implementation**: Write custom JavaScript validation functions
>
> **Examples**:
>
> * Cross-field validation
> * External API validation
> * Business rule enforcement
>
> **Documentation**: [Learn more about custom validators](../../validators)

![Validation example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Input_validat.gif)

## Behavior configuration

### Hide/disable expressions

Define the input field's behavior using JavaScript expressions to control its visibility or disablement:

* **Hide condition**: A JavaScript expression that hides the input field when it evaluates to the specified result.
* **Disabled condition**: A JavaScript expression that disables the input field when it returns a truthy value.

#### Hide expression example

We can use a rule to hide an input field if another field has a null value (it is not filled). For example, the "Mortgage" input field, which remains hidden until users fill in the "Income" field:

![Hide expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_hide.png)

**Rule used:**

```javascript theme={"dark"}
${application.input.income} === null || ${application.input.income} === ""
```

![Hide expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input.income.png)

Result:

![Hide expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_hide_result.gif)

#### Disable example

You can use a disabled condition to disable an input element based on values from other fields. When you type 'TEST' in the first input (Name) the second input (Test) will be disabled:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_disabled_condition.png)

**Rule used:**

```javascript theme={"dark"}
${application.input.name} === 'TEST'
```

![Disabled expression](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/disabled_input.gif)

> [!NOTE]
>
> It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

### Event handlers

Configure interactive behaviors for your input field:

| Event | Description | Common Use Cases |
| - | - | - |
| **CHANGE** | Triggered when input changes | Update related fields, trigger calculations, show/hide elements |
| **FOCUS** | When field receives focus | Load dynamic data, show helper content |
| **BLUR** | When field loses focus | Validate input, save data, format display |

![Event handlers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_ui_actions_new.gif)

**Action Types Available**:

* Navigate to different pages
* Execute business rules
* Call external services
* Update other form elements
* Trigger process actions

> [!TIP]
>
> For detailed event handler configuration, see the [Event Handlers guide](../../event-handlers).

## Platform customization

### Settings overrides

Customize your input field differently across platforms:

> [tab] Web Applications
>
> **Override Options**:
>
> * Label text for desktop terminology
> * Placeholder text optimized for keyboard input
> * Helper text with extended descriptions
> * Prefix/suffix for web-specific formatting
>
> **Web-Specific Features**:
>
> * Keyboard shortcuts integration
> * Advanced formatting options
> * Enhanced validation messages

> [tab] Mobile Apps
>
> **Override Options**:
>
> * Shorter labels for mobile screens
> * Touch-optimized placeholder text
> * Simplified helper text
> * Mobile-appropriate prefix/suffix
>
> **Mobile-Specific Features**:
>
> * Input type optimization for mobile keyboards
> * Touch-friendly clear buttons
> * Platform-specific validation styling

![Platform override import/export](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

> [!NOTE]
>
> Override settings can be imported and pushed between platforms, saving configuration time and ensuring consistency.

## Visual styling

### Layout options

> [tab] Web Styling
>
> > [accordion] Icon Integration
> >
> > **Left Icon**: Visual cue at the start of the input
> >
> > * Search icons for search fields
> > * User icons for name fields
> > * Lock icons for password fields
> >
> > **Right Icon**: Action or status indicator
> >
> > * Clear buttons (×)
> > * Validation status (✓ or ⚠)
> > * Dropdown arrows
> >
> > **Icon Configuration**:
> >
> > * Select from Media Library
> > * Custom icon keys
> > * Platform-specific icons
>
> > [accordion] Responsive Sizing
> >
> > | Option | Behavior | Best For |
> > | - | - | - |
> > | **Fill** | Expands to use available space | Full-width forms |
> > | **Fixed** | Maintains specified width | Consistent layouts |
> > | **Auto** | Adjusts based on content | Dynamic forms |

> [tab] iOS Styling
>
> **Platform Adaptations**:
>
> * iOS-specific input styling
> * Native keyboard integration
> * Apple Design Guidelines compliance
> * iOS-specific validation styling

> [tab] Android Styling
>
> **Platform Adaptations**:
>
> * Material Design principles
> * Android keyboard optimization
> * Platform-specific animations
> * Android validation patterns

### Theme customization

Override default styling for complete visual control:

> [accordion] Input Field Styling
>
> **Border & Background**:
>
> * Border colors for different states
> * Background color customization
> * Border radius and thickness
>
> **Text Styling**:
>
> * Font family and size
> * Text color for different states
> * Placeholder text styling
>
> **States**:
>
> * Default, focused, disabled, error states
> * Hover effects for web
> * Touch feedback for mobile

> [accordion] Label & Helper Styling
>
> **Label Customization**:
>
> * Typography controls
> * Color options
> * Positioning and alignment
>
> **Helper Text**:
>
> * Font styling
> * Color coordination
> * Tooltip appearance

> [accordion] Validation Styling
>
> **Error States**:
>
> * Error message styling
> * Input border color changes
> * Icon integration
>
> **Success States**:
>
> * Success indicators
> * Positive feedback styling
> * Completion animations

## Best practices

> [card] [Accessibility](../../../../platform-deep-dive/accessibility)
>
> * Provide clear, descriptive labels
> * Use appropriate input types for better mobile experience
> * Include helper text for complex fields
> * Set an accessibility label when the input has no visible label
>
> See the [Accessibility guide](../../../../platform-deep-dive/accessibility) for ARIA auto-binding, keyboard navigation, and screen reader details.

> [card] User Experience
>
> * Choose appropriate input types for the data
> * Provide helpful placeholder text and examples
> * Use validation that guides rather than frustrates
> * Consider progressive disclosure for complex forms
> * Implement auto-save functionality where appropriate
> * Group related inputs logically

> [card] Data Management
>
> * Use meaningful process data keys
> * Plan for data validation early in development
> * Consider data format consistency across platforms
> * Implement proper error handling
> * Document validation rules for maintenance
> * Test with real-world data scenarios

## Common use cases

| Scenario | Input Type | Validation | Additional Features |
| - | - | - | - |
| **Contact Form** | Text, Email | Required, Email format | Clear buttons, helper text |
| **Login Form** | Text, Password | Required, Min length | Security indicators |
| **Search Field** | Text | Min length | Auto-complete, clear button |
| **OTP codes** | Code | Pattern matching | |
| **Numeric Input** | Number | Min/max values | Prefix/suffix for units |
| **Address Entry** | Text | Format validation | Auto-complete integration |


# Multi select
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select

The Multi Select form field is an element that allows users to choose multiple options from a list of choices. Each option consists of a label, which is displayed in the dropdown menu, and a corresponding value, which is stored upon selection.

![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)

> [!NOTE]
>
> For example, consider a scenario where you have options "Sports" with the value "S", "Music" with the value "M", and "Reading" with the value "R". When a user selects both "Sports" and "Music" in the process instance, the values \["S", "M"] will be stored as an array for the "Multi Select" key.

## Configuring the Multi Select element

### Multi Select generic settings

These allow you to customize the generic settings for the Multi Select element:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#hide/disable-expressions)
* [**Event handlers**](#event-handlers)
* [**Multi Select styling**](#multi-select-styling)

#### Process data key

Process data key establishes the binding between the multi select element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node).

> [!NOTE]
>
> The Multi Select component stores selected values as an array, similar to how a Checkbox works. This differs from the single Select component, which stores only a single value.

#### Properties

* **Label**: The visible label for the multi select element.
* **Placeholder**: Text that appears within the multi select element when it is empty.
* **Empty message**: Text displayed for custom type when no results are found.
* **Helpertext**: Additional information about the multi select element, which can be optionally hidden within an infopoint.
* **Show selections**: Controls how selected items are displayed. Available display modes:
  * **Comma separated**: Selected values are displayed as a comma-separated text string within the input field (e.g., "Option 1, Option 2, Option 3")
  * **Chips inside**: Selected values appear as chips/badges inside the input field, allowing individual removal with close buttons
  * **Chips outside**: Selected values are displayed as chips/badges below the input field, keeping the input area clean
* **Max. Options Selectable**: Sets the maximum number of options that can be selected simultaneously.

#### Show selections display modes

The "Show selections" property determines how users see their selected options. Each mode offers different benefits depending on your use case:

> [tab] Comma separated
>
> Selected values are displayed as a comma-separated text string within the input field. This mode is space-efficient and works well when you have predictable option lengths.
>
> **Best for:** Simple lists, short option names, read-only display scenarios
>
> ![Multi Select with comma separated display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms1.png)

> [tab] Chips inside
>
> Selected values appear as individual chips/badges inside the input field with close buttons `×` for easy removal. This mode provides clear visual separation and allows users to remove specific selections easily.
>
> **Best for:** Interactive forms, when individual item removal is important, moderate number of selections
>
> ![Multi Select with chips inside display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms2.png)
>
> **Features:**
>
> * Individual close buttons for each selection
> * Clear visual distinction between options
> * Hover effects for better interaction

> [tab] Chips outside
>
> Selected values are displayed as chips/badges below the input field, keeping the input area clean and uncluttered. This mode is ideal when you expect many selections or longer option names.
>
> **Best for:** Forms with many selections, long option names, when input field clarity is important
>
> ![Multi Select with chips outside display](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ms3.png)
>
> **Benefits:**
>
> * Input field remains clean and readable
> * Better accommodation for many selections
> * Improved mobile experience with long lists

> [!TIP]
>
> **Choosing the right display mode:**
>
> * Use **comma separated** for simple, read-only scenarios or when space is limited
> * Use **chips inside** for interactive forms where users frequently add/remove items
> * Use **chips outside** for complex forms with many selections or when input field clarity is crucial

#### Datasource configuration

* **Default value**: Autofill the multi select field with these values. You need to specify an array of values from the value/label pairs defined in the Datasource tab.

![Multi Select default value configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)

* **Source Type**: The source can be Static, Enumeration, or Process Data.
* **Add option**: Define label and static value pairs here.

#### Process Data

When the data source type is set to Process Data, the multi select element will be populated with options from a specific process data key. This approach provides dynamic data loading capabilities, allowing options to be generated, modified, or filtered at runtime through business rules.

#### Configuration steps

* Set Source Type: Select "Process Data" from the Source Type dropdown
* Specify Process Data Key: Enter the key path where your options array is stored (e.g., app.options)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/br_multi.png)

Example of JavaScript business rule that populates the multi select element with the values from the process data key:

```javascript theme={"dark"}
options = [
    {
        "label": "option 1",
        "value": "option1",
        "enabled": true
    },
    {
        "label": "option 2",
        "value": "option2",
    },
    {
        "label": "option 3",
        "value": "option3",
        "enabled": false
    },
    {
        "label": "option 4",
        "value": "option4",
        "enabled": false
    },
    {
        "label": "option 5",
        "value": "option5"
    }
];

output.put("app", {"options": options});
```

Now the multi select element will be populated with the values from the `app.options` key:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process_data_multiselect.png)

#### Validators

You can add multiple validators to a multi select field. For more details, refer to [**Validators**](../../validators).

Common validators for Multi Select include:

* **Required**: Ensures at least one option is selected
* **Custom**: You can add a custom validator to the multi select element.
* **Custom Expression**: You can add a custom expression to the multi select element.

#### Hide/disable expressions

The multi select field's behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the Multi Select field when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the Multi Select field when it returns a truthy value.

> [!NOTE]
>
> It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

#### Event handlers

Event handlers can be added to the multi select element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

> [!NOTE]
>
> For more information, see the [Event Handlers documentation](../../event-handlers).

### Disabled options

You can control the availability of specific options in Multi Select elements by marking them as disabled. This feature is particularly useful for implementing business logic that restricts certain choices based on user permissions, subscription levels, or contextual conditions.

#### Example

> [!NOTE]
>
> The `enabled` property is used to control the availability of the option.

```javascript theme={"dark"}
options = [
    {
        "label": "option 1",
        "value": "option1",
        "enabled": true
    },
    {
        "label": "option 2",
        "value": "option2",
        "enabled": false
    },
    {
        "label": "option 3",
        "value": "option3",
        "enabled": true
    },
    {
        "label": "option 4",
        "value": "option4",
        "enabled": false
    },
    {
        "label": "option 5",
        "value": "option5"
    },

    
];

output.put("app", {"options": options});
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/disabled_options.png)

### Multi Select settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

### Web overrides

* Properties:
  * **Label**: Override the multi select label.
  * **Helper**: Override helper text/info point.
  * **Placeholder**: Override the placeholder.
  * **Show selections**: Override the show selections.
* Expressions:
  * **Hide**: Override the hide expression.

### iOS overrides

Same as Web overrides.

### Android overrides

Same as Web overrides.

> [!TIP]
>
> Overrides can always be imported/pushed from one platform to another:
>
> ![Importing and pushing overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

### Multi Select styling

> [tab] Web
>
> > [tab] Max Rows
> >
> > * **Max Rows**: Adjust the maximum number of rows of the multi select element.
>
> > [tab] Spacing
> >
> > * **Margin**: Adjust the margin of the multi select element.
> > * **Padding**: Adjust the padding of the multi select element.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.
>
> However, for mobile applications, there's an additional sizing style property specific to multi select elements:
>
> * **Fit Width**: Adjust the fit width of the multi select element:
>   * **fill**: Fills the available space.
>   * **fixed**: Maintains a fixed width.
>   * **auto**: Adjusts the width automatically based on content.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.
>
> However, for mobile applications, there's an additional sizing style property specific to multi select elements:
>
> * **Fit Width**: Adjust the fit width of the multi select element:
>   * **fill**: Fills the available space.
>   * **fixed**: Maintains a fixed width.
>   * **auto**: Adjusts the width automatically based on content.

#### Multi Select style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

Style options:

> [accordion] Common Properties
>
> * Border radius **\[TEXT]**
> * Border width **\[TEXT]**
> * Text style **\[FONT]**
>
> ![Multi Select common properties overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_com_props.png)

> [accordion] Label
>
> * Default state
>   * Text color **\[COLOR]**
> * Disabled state
>   * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![Multi Select label overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_label.png)

> [accordion] Helper
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
> * Helper Tooltip
>   * Text style **\[FONT]**
>   * Text color **\[COLOR]**
>   * Background color **\[COLOR]**
>   * Icon Color **\[COLOR]**
>
> ![Multi Select helper overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_helper.png)

> [accordion] Error
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![Multi Select error overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_error.png)

> [accordion] Empty State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![Multi Select empty state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_empty_state.png)

> [accordion] Active State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![Multi Select active state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_active_state.png)

> [accordion] Filled State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
> * Selected chip background **\[COLOR]**
> * Selected chip text color **\[COLOR]**
> * Selected chip border color **\[COLOR]**
>
> ![Multi Select filled state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_filled_state.png)

> [accordion] Disabled State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![Multi Select disabled state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_disabled_state.png)

> [accordion] Error State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![Multi Select error state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_error_state.png)

> [accordion] Hover State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![Multi Select hover state overrides](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/multi_select_ov_hover_state.png)

> [!NOTE]
>
> You can import or push the overrides from one platform to another without having to configure them multiple times.
>
> ![Importing and pushing overrides for Multi Select](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)

# Example - Income sources selection form

Let's create an example using **enumeration data** to create an income sources selection form where users can select multiple income sources from a predefined list, as part of a loan application process.

To create this kind of process, we need the following elements:

* a [**user task node**](../../../node/user-task-node) (here we have the client forms and here we add the MULTI SELECT elements)

![Multi Select user task configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_process.png)

### Creating the enumeration

First, we need to create an enumeration for income sources:

1. Create it on your project or in a library.
2. Click on the breadcrumbs (top-right corner) then click **New enumeration** (the Enumeration Designer will now open).
3. Create an enumeration named \`\` with the following values:
   * **S** - Salary
   * **F** - Freelance
   * **R** - Rents
   * **I** - Investments

![Income sources enumeration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_enum_income.png)

![Income sources enumeration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enum_multi_select.png)

### Configuring the UI

Follow the next steps to configure the UI needed:

1. Select the **user task node** and click the **brush icon** to open [**UI Designer**](../../ui-designer).
2. Add a [**Card**](../root-components/card) UI element as a [**root component**](../root-components/) (this will group the other elements inside it) with the following properties:

* Generic:
  * **Title** - *Loan Application Form*

3. Inside the **card**, add a [**form element**](./).
4. Inside the **form** add the standard form fields (First Name, Last Name, Date of Birth, Email, Income) and then add a **multi select element** for income sources selection.
5. For the multi select element (Income Sources) set the following properties:
   * **Process data key** - `application.incomeSources`

> [!NOTE]
>
> The attribute `application.incomeSources` is the key on which we added income sources selection. It is an array of strings with the source of enumeration.
>
> ![Multi Select income sources configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/incomeSource_attr.png)

* **Label** - Income Sources
* **Placeholder** - Select your income sources...
* **Empty message** - No income sources found
* **Show selections** - Comma Separated
* **Max. Options Selectable** - 4 (reasonable limit for income sources)
* **Source type** - Enumeration
* **Enumeration** - Select `incomeSources` from the dropdown

![Multi Select income sources configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/incomeSource_dropdown.png)

8. Test and run the process by clicking **Start process**.

<video />

## Data handling and validation

### Common validation scenarios

> [accordion] Required income sources validation
>
> Ensure at least one income source is selected for loan applications:
>
> ```javascript theme={"dark"}
> // Validator expression
> ${application.incomeSources != null && application.incomeSources.length > 0}
> ```
>
> **Error message**: "Please select at least one income source to continue with your application."

> [accordion] Minimum income diversity validation
>
> Require at least 2 different income sources for better loan approval chances:
>
> ```javascript theme={"dark"}
> // Validator expression  
> ${application.incomeSources != null && application.incomeSources.length >= 2}
> ```
>
> **Error message**: "Please select at least 2 income sources to demonstrate income stability."

> [accordion] Maximum income sources validation
>
> Limit to maximum 4 income sources to keep the application manageable:
>
> ```javascript theme={"dark"}
> // Validator expression
> ${application.incomeSources == null || application.incomeSources.length <= 4}
> ```
>
> **Error message**: "Please select no more than 4 primary income sources."

> [accordion] Primary income validation
>
> Ensure that salary or business income is selected as a primary source (for certain loan types):
>
> ```javascript theme={"dark"}
> // Validator expression
> ${application.incomeSources != null && (application.incomeSources.contains("salary") || application.incomeSources.contains("business"))}
> ```
>
> **Error message**: "At least one primary income source (Salary or Business Income) is required for this loan type."

## Best practices

> [!TIP]
>
> **Limit options**: Don't overwhelm users with too many options. Consider grouping or categorizing if you have many choices.

> [!TIP]
>
> **Set maximum selections**: Use the "Max. Options Selectable" property to prevent users from selecting too many options.

> [!TIP]
>
> **Provide clear labels**: Make option labels descriptive and easy to understand.

> [!TIP]
>
> **Consider mobile experience**: Test how selected items display on mobile devices, especially when many options are selected.

> [!TIP]
>
> **Validate selections**: Always validate that the user's selections meet your business requirements using appropriate validators.

> [!TIP]
>
> **Handle empty states**: Provide clear messaging when no options are available or when search yields no results.

## Differences from Single Select

| Feature | Single Select | Multi Select |
| - | - | - |
| **Selection** | One option only | Multiple options |
| **Data Storage** | Single value | Array of values |
| **Display** | Selected value | Chips, comma-separated, or custom format |
| **Validation** | Simple required validation | Min/max selections, required array validation |
| **Use Cases** | Country selection, status selection | Skills, categories, tags, interests |
| **Clear Action** | Clears single selection | Clears all selections |

> [!NOTE]
>
> When migrating from Single Select to Multi Select, remember to update your data model to handle arrays and adjust any business rules or integrations that process the selected values.


# Radio
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/radio-form-field

Radio buttons are normally presented in radio groups (a collection of radio buttons describing a set of related options). Only one radio button in a group can be selected at the same time.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/radio_form_field.png)

## Configuring the radio field element

### Radio generic settings

These allow you to customize the generic settings for the Radio element:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#hide/disable-expressions)
* [**Event handlers**](#event-handlers)
* [**Radio styling**](#radio-styling)

#### Process data key

Process data key establishes the binding between the radio element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_process_key.png)

#### Properties

* **Label**: The visible label for the radio element.
* **Helpertext**: Additional information about the radio element, which can be optionally hidden within an infopoint.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_label_info.png)

#### Datasource configuration

* **Default value**: Autoselect an option from the radio element based on this value. You need to specify the value from the value/label pairs defined in the Datasource tab.
* **Source Type**: The source can be Static, Enumeration, or Process Data.
* **Add option**: Define label and value pairs here.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_datasource.png)

#### Validators

The following validators can be added to a radio: `required` and `custom`. For more information, see the [validators documentation](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/radio_validators.png)

#### Hide/disable expressions

The radio's element behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression that hides the Radio element when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the Radio element when it returns a truthy value.

> [!NOTE]
>
> It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/radio_validators.png)

#### Event handlers

Event handlers can be added to the radio element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

> [!TIP]
>
> For more information, see the [Event Handlers documentation](../../event-handlers).

### Radio settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the radio label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

> [!TIP]
>
> Overrides can always be imported/pushed from one platform to another:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

### Radio styling

> [tab] Web
>
> > [tab] Properties
> >
> > * **Type**: Set the type of the radio. Possible values:
> >
> >   * bordered
> >   * clear
>
> > [tab] Sizing
> >
> > Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
> >
> > * **fill**: Fills the available space.
> > * **fixed**: Maintains a fixed width.
> > * **auto**: Adjusts the width automatically based on content.
>
> > [tab] Layout
> >
> > * **Direction**: Determines the orientation of the layout, which can be either horizontal or vertical.
> > * **Gap**: Specifies the size of the space between rows and columns.
> > * **Columns**: Indicates the number of columns in the layout.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.
>
> However, for mobile applications, there's a difference on Gap value:
>
> * **Gap**: pt - points instead of pixels

> [tab] Android
>
> Similar styling considerations apply to Android as for web.
>
> However, for mobile applications, there's a difference on Gap value:
>
> * **Gap**: dp - density-independent pixels

#### Radio style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)

Style options:

> [accordion] Common Properties
>
> * Border radius **\[TEXT]**
> * Border width  **\[TEXT]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_common.png)

> [accordion] Label
>
> * Default state
>   * Text color **\[COLOR]**
> * Disabled state
>   * Text color  **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)

> [accordion] Helper
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
> * Helper Tooltip
>   * Text style **\[FONT]**
>   * Text color **\[COLOR]**
>   * Background color **\[COLOR]**
>   * Icon Color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)

> [accordion] Error
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)

> [accordion] Unselected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)

> [accordion] Selected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)

> [accordion] Disabled Unselected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)

> [accordion] Disabled Selected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)

> [accordion] Hover Unselected State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_unselected_state.png)

> [accordion] Hover Selected State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_selected_state.png)

> [!NOTE]
>
> You can import or push the overrides from one platform to another without having to configure them multiple times.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)


# Segmented button
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/segmented-button

It allows you to pick only one option from a group of options, and you can choose to have between 2 and 5 options in the group. The segmented button helps improve usability in your app.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/segmented_button1.gif)

## Configuring the segmented button

### Segmented button generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* **Expressions**
* [**Event handlers**](#event-handlers)
* [**Segmented button styling**](#segmented-button-style-overrides-options)

#### Process data key

Process data key establishes the binding between the segmented buton and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node).

#### Properties

* **Label**: The visible label for the segmented button.
* **Helpertext**: Additional information about the segmented button, which can be optionally hidden within an infopoint.

#### Datasource configuration

* **Default Value**: The default value of the segmented button (it can be selected from one of the static source values)
* **Source Type**: It is by default Static.
* **Add option**: Define label and value pairs here.

#### Validators

The following validators can be added to a segmented button: `required` and `custom`. For more information, see the [validators documentation](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/segmented_button_props.png)

#### Event handlers

Event handlers can be added to the segmented button element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the action type.

> [!TIP]
>
> For more information, see the [Event Handlers documentation](../../event-handlers).

### Segmented button settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the segmented button label.
  * **Helper**: Override helper text/info point.
* Expressions:
  * **Hide**: Override the hide expression.

> [!TIP]
>
> Overrides can always be imported/pushed from one platform to another:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

> [tab] Web
>
> #### Sizing
>
> Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
>
> * **fill**: Fills the available space.
> * **fixed**: Maintains a fixed width.
> * **auto**: Adjusts the width automatically based on content.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.

#### Segmented button style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)

Style options:

> [accordion] Common Properties
>
> * Border radius **\[TEXT]**
> * Border width  **\[TEXT]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_common.png)

> [accordion] Label
>
> * Default state
>   * Text color **\[COLOR]**
> * Disabled state
>   * Text color  **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)

> [accordion] Helper
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
> * Helper Tooltip
>   * Text style **\[FONT]**
>   * Text color **\[COLOR]**
>   * Background color **\[COLOR]**
>   * Icon Color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)

> [accordion] Error
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)

> [accordion] Unselected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)

> [accordion] Selected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)

> [accordion] Disabled Unselected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)

> [accordion] Disabled Selected State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)

> [accordion] Hover Unselected State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_unselected_state.png)

> [accordion] Hover Selected State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Icon color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_hover_selected_state.png)

> [!NOTE]
>
> You can import or push the overrides from one platform to another without having to configure them multiple times.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)


# Single Select
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/select-form-field

Enable users to choose from a dropdown list of predefined options with advanced features including search, validation, and selective option disabling.

The Single Select form field allows users to choose from a dropdown list of predefined options. Each option consists of a label (displayed to users) and a corresponding value (stored in the process data). This component supports static data, enumerations, and dynamic process data sources with advanced features like search filtering and conditional option enabling.

![Single Select demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/select_form_field.png)

> [!NOTE]
>
> **Example**: Consider a dropdown with "Sports" (value: "S") and "Music" (value: "M"). When a user selects "Sports", the value "S" is stored in the process instance under the Select element's data key.

## Configuration overview

Configure your single select component using these main sections:

> [card] Basic Settings
>
> Process data binding, labels, and properties

> [card] Data Source
>
> Static options, enumerations, or dynamic data

> [card] Behavior
>
> Hide/disable conditions and event handlers

> [card] Styling
>
> Visual appearance and platform overrides

## Basic configuration

### Process data key

The process data key establishes the binding between the select element and process data, enabling its later use in:

* [Decision nodes](../../../node/exclusive-gateway-node)
* [Business rule actions](../../../actions/business-rule-action/business-rule-action)
* [Integration tasks](../../../node/message-send-received-task-node)

### Core Properties

> [accordion] Label & Display
>
> **Label**: The visible text displayed above the select element
>
> * Supports Markdown syntax for rich formatting
> * Can include links, emphasis, and other formatting
> * Responsive across all platforms
>
> **Placeholder**: Text shown when no option is selected
>
> * Provides guidance on what to select
> * Should be clear and actionable
> * Example: "Choose your preferred option..."
>
> **Empty Message**: Custom text for no results scenarios
>
> * Displayed when search yields no matches
> * Helpful for dynamic data sources
> * Example: "No matching options found"

> [accordion] Search & Interaction
>
> **Search for Options**: Enable filtering functionality
>
> * Improves usability for long option lists
> * Real-time filtering as users type
> * Case-insensitive search capabilities
> * Particularly useful for large datasets
>
> **Has Clear**: Add option to clear selection
>
> * Provides users with reset functionality
> * Useful for optional fields
> * Improves user control and flexibility
>
> **Helper Text**: Additional context or instructions
>
> * Can be displayed as regular text
> * Can be hidden within an expandable info point
> * Supports Markdown formatting

## Data source configuration

### Default value setup

Configure the initial selected option:

**Default Value**: Specify which option should be pre-selected

* Must match a value from your data source
* Improves user experience by reducing required interactions
* Consider user context and common selections

![Default value configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/default_value_select.gif)

### Source types

Choose the appropriate data source for your select options:

> [tab] Static Options
>
> **Purpose**: Fixed list of options defined at design time
>
> **Configuration**:
>
> * **Add Option**: Define label/value pairs manually
> * **Label**: User-friendly display text
> * **Value**: Internal identifier stored in process data
> * **Enabled**: Control option availability (see below)
>
> **Best For**:
>
> * Fixed categories (Yes/No, Active/Inactive)
> * Configuration options
> * Simple selection lists

> [tab] Enumeration
>
> **Purpose**: Predefined lists managed centrally
>
> **Benefits**:
>
> * Consistent across multiple forms
> * Centralized maintenance
> * Automatic updates when enumeration changes
> * Version control for option lists
>
> **Best For**:
>
> * Shared vocabularies (countries, currencies)
> * Business domains (departments, categories)
> * Standardized classifications

> [tab] Process Data
>
> **Purpose**: Dynamic options from process variables
>
> **Features**:
>
> * Runtime data population
> * Context-dependent options
> * Integration with external systems
> * **Enhanced Option Control** (NEW)
>
> **Best For**:
>
> * User-specific options
>
> * Data from external APIs
>
> * Conditional option sets
>
> * Dynamic business logic
>
> > [!NOTE]
> >
> > Process Data sources now support the **enabled** property for individual option control. See the Enhanced Option Control section below.

### Enhanced option control

> [!WARNING]
>
> Individual option enabling/disabling is available for **Process Data** source types only.

When using Process Data, you can control which options are selectable using the `enabled` property:

**How It Works**:

* **`enabled: true`** or **missing**: Option is selectable (default)
* **`enabled: false`**: Option appears but is disabled

**Example**:

```json theme={"dark"}
{
  "options": [
    {
      "value": "available", 
      "label": "Available Option",
      "enabled": true
    },
    {
      "value": "disabled",
      "label": "Disabled Option", 
      "enabled": false
    }
  ]
}
```

**Common Use Cases**: Conditional availability based on permissions, progressive disclosure, status indication (e.g., "Out of Stock"), or guided selection flows.

> [!NOTE]
>
> Disabled options support theming for both **disabled unselected** and **disabled selected** states. An option can be both selected and disabled simultaneously.

## Validation

Apply validators to ensure data quality and completeness:

**Available Validators**:

* **Required**: Ensures a selection is made
* **Custom**: Complex business logic validation
* **Conditional**: Validation based on other field values

For comprehensive validation options, refer to our [Validators Guide](../../validators).

## Behavior configuration

### Hide/disable expressions

Control the select element's visibility and interaction using JavaScript expressions:

### Event handlers

Configure interactive behaviors for your select element:

| Event | Description | Common Use Cases |
| - | - | - |
| **CHANGE** | Triggered when selection changes | Update dependent fields, trigger calculations, show/hide related content |

**Action Types Available**:

* **Process Actions**: Advance workflow based on selection
* **Data Operations**: Update related form fields
* **UI Updates**: Show/hide dependent elements
* **External Calls**: Fetch related data from APIs

> [!TIP]
>
> For detailed event handler configuration, see the [Event Handlers guide](../../event-handlers).

## Platform customization

### Settings overrides

Customize your select element differently across platforms:

> [tab] Web Applications
>
> **Override Options**:
>
> * **Label**: Desktop-optimized terminology
> * **Helper**: Extended descriptions with more context
> * **Placeholder**: Detailed guidance text
>
> **Web-Specific Features**:
>
> * Enhanced search with keyboard shortcuts
> * Hover states and advanced animations
> * Larger option lists with scrolling

> [tab] Mobile Apps
>
> **Override Options**:
>
> * **Label**: Concise mobile-friendly text
> * **Helper**: Brief, essential information
> * **Placeholder**: Short, clear guidance
>
> **Mobile Optimizations**:
>
> * Touch-friendly option sizing
> * Native picker integration
> * Simplified layouts for smaller screens

![Platform override import/export](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

> [!NOTE]
>
> Override settings can be imported and pushed between platforms, saving configuration time and ensuring consistency.

## Visual styling

### Layout options

> [tab] Web Styling
>
> > [accordion] Icon Integration
> >
> > **Left Icon**: Visual cue for the select purpose
> >
> > * Category icons (📂, 🏢, 👤)
> > * Functional indicators (🔍, ⚙️, 📊)
> > * Status symbols (✓, ⚠️, 🔒)
> >
> > **Icon Configuration**:
> >
> > * **Icon Key**: Select from Media Library
> > * Platform-specific optimization
> > * Consistent with design system
> >
> > ![Icon configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/input_icons.png)
>
> > [accordion] Responsive Sizing
> >
> > | Option | Behavior | Best For |
> > | - | - | - |
> > | **Fill** | Expands to use available space | Full-width forms |
> > | **Fixed** | Maintains specified width | Consistent layouts |
> > | **Auto** | Adjusts based on content | Dynamic layouts |

> [tab] iOS Styling
>
> **Platform Adaptations**:
>
> * Native iOS picker integration
> * Height specification in points (pt)
> * iOS design guideline compliance
> * Optimized for touch interaction
>
> **Additional Properties**:
>
> * **Height (pt)**: Vertical size control for mobile optimization

> [tab] Android Styling
>
> **Platform Adaptations**:
>
> * Material Design principles
> * Height specification in density-independent pixels (dp)
> * Android-specific animations
> * Platform-consistent appearance
>
> **Additional Properties**:
>
> * **Height (dp)**: Vertical size control optimized for Android displays

### Theme customization

Override default styling for complete visual control:

![Theme override interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_all.png)

> [accordion] Common Properties
>
> **Layout & Structure**:
>
> * Border radius for rounded corners
> * Border width for outline definition
> * Text style for typography consistency
>
> ![Common properties styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_com_props.png)

> [accordion] Label Styling
>
> **Default State**:
>
> * Text color customization
> * Font family and size options
>
> **Disabled State**:
>
> * Dimmed appearance
> * Consistent with disabled styling
>
> ![Label styling options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_label.png)

> [accordion] Helper Text Styling
>
> **Standard Helper**:
>
> * Text color and font options
>
> **Tooltip Helper**:
>
> * Background color customization
> * Icon color options
> * Typography controls
>
> ![Helper text styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_helper.png)

> [accordion] Interactive States
>
> > [tab] Empty State
> >
> > **When no option is selected**:
> >
> > * Border and background colors
> > * Icon color customization
> > * Placeholder text styling
> >
> > ![Empty state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_empty_state.png)
>
> > [tab] Active State
> >
> > **When dropdown is open**:
> >
> > * Active border highlighting
> > * Background color changes
> > * Text and icon color adjustments
> >
> > ![Active state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_active_state.png)
>
> > [tab] Filled State
> >
> > **When option is selected**:
> >
> > * Selected option appearance
> > * Confirmation visual cues
> > * Clear selection indicator
> >
> > ![Filled state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_select_filled_state.png)
>
> > [tab] Error & Disabled States
> >
> > **Error State**: Validation failure appearance
> > **Disabled State**: Non-interactive appearance
> > **Hover State** (Web only): Mouse-over effects
> >
> > ![Error state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ovselect_error_state.png)

> [!NOTE]
>
> **Time-Saving Tip**: Export your styling configuration from one platform and import it to others to maintain consistency without manual reconfiguration.
>
> ![Style import/export workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)

## Advanced example: Dynamic dropdowns

Create sophisticated dropdown interactions with dependent selections using process data and business rules.

### Scenario overview

Build a customer contract selection system where available contracts depend on the selected customer:

![Dynamic dropdowns demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/d_dropdowns.gif)

### Process structure

**Required Elements**:

1. **Task Node**: Populates dropdown data using business rules
2. **User Task Node**: Contains the select elements and form interface

### Implementation steps

> [accordion] Step 1: Process Setup
>
> 1. Open **FlowX.AI Designer** → **Processes** → **Definitions**
> 2. Click **New Process** to open Process Designer
> 3. Add the required nodes:
>    * Task node (for data preparation)
>    * User task node (for user interface)
>
> ![Process structure](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/d_dropdowns1.gif)

> [accordion] Step 2: Data Preparation
>
> **Task Node Configuration**:
>
> * **Action Type**: Business Rule
> * **Execution**: Automatic, Mandatory
> * **Language**: MVEL (or your preferred scripting language)
>
> **Sample MVEL Script**:
>
> ```java theme={"dark"}
> output.put("application",
> {
>     "client": {
>         "identity": [
>         {
>             "value": "001",
>             "label": "Eddard Stark"
>         },
>         {
>             "value": "002", 
>             "label": "Sansa Stark"
>         },
>         {
>             "value": "003",
>             "label": "Catelyn Stark"
>         }
>     ]},
>     "contracts": {
>         "001": [
>             {
>                 "value": "c001",
>                 "label": "Eddard Contract 1"
>             },
>             {
>                 "value": "c007", 
>                 "label": "Eddard Contract 2"
>             }
>         ],
>         "003": [
>             {
>                 "value": "c002",
>                 "label": "Catelyn Contract 1"
>             },
>             {
>                 "value": "c003",
>                 "label": "Catelyn Contract 2"
>             },
>             {
>                 "value": "c004",
>                 "label": "Catelyn Contract 3"
>             }
>         ],
>         "002": [
>             {
>                 "value": "c005",
>                 "label": "Sansa Contract 1"
>             }
>         ]
>     }
> });
> ```
>
> ![Business rule configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/d_business_rukle.png)

> [accordion] Step 3: User Interface Setup
>
> **User Task Node Configuration**:
>
> * **Action Type**: Save Data
> * **Execution**: Manual, Mandatory
> * **Data to Send**: `application`
>
> **UI Structure**:
>
> 1. **Card Element** (root component):
>    * **Custom UI Payload**: `{"application": ${application}}`
>    * **Title**: "Customer Contract"
>
> 2. **Form Element** (container for selects)
>
> 3. **First Select** (Customer Name):
>    * **Process Data Key**: `application.client.selectedClient`
>    * **Label**: Customer Name
>    * **Source Type**: Process Data
>    * **Name**: `application.client.identity`
>
> 4. **Second Select** (Contract ID):
>    * **Process Data Key**: `application.client.selectedContract`
>    * **Label**: Contract ID
>    * **Source Type**: Process Data
>    * **Name**: `application.contracts`
>    * **Parent**: SELECT (first dropdown)
>
> ![Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/select_customer.png)

> [accordion] Step 4: Testing & Validation
>
> **Test Process**:
>
> 1. Click **Start Process** in the designer
> 2. Select a customer from the first dropdown
> 3. Verify that the second dropdown populates with relevant contracts
> 4. Submit the form to validate data storage
>
> **Expected Behavior**:
>
> * Customer selection triggers contract list update
> * Only contracts associated with selected customer appear
> * Form submission stores both selected values
>
> ![Dynamic example in action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/dynamic_ex.gif)

### Enhanced dynamic example with disabled options

Extend the previous example to include conditional option disabling:

```json theme={"dark"}
{
  "application": {
    "client": {
      "identity": [
        {
          "value": "001",
          "label": "Eddard Stark",
          "enabled": true
        },
        {
          "value": "002",
          "label": "Sansa Stark", 
          "enabled": false  // Disabled due to account status
        },
        {
          "value": "003",
          "label": "Catelyn Stark",
          "enabled": true
        }
      ]
    },
    "contracts": {
      "001": [
        {
          "value": "c001",
          "label": "Eddard Contract 1",
          "enabled": true
        },
        {
          "value": "c007",
          "label": "Eddard Contract 2 (Expired)",
          "enabled": false  // Disabled due to expiration
        }
      ]
    }
  }
}
```

## Best practices

> [card] [Accessibility](../../../../platform-deep-dive/accessibility)
>
> * Provide clear, descriptive labels and helper text
> * Ensure sufficient color contrast for all states
> * Set an accessibility label when the select has no visible label
>
> See the [Accessibility guide](../../../../platform-deep-dive/accessibility) for keyboard navigation, ARIA auto-binding, and screen reader details.

> [card] User Experience
>
> * Keep option lists manageable (under 10 items when possible)
> * Use search functionality for longer lists
> * Provide clear visual feedback for disabled options
> * Consider default selections for common use cases
> * Group related options logically
> * Show loading states for dynamic data

> [card] Data Management
>
> * Use meaningful keys for integration purposes
> * Plan for data validation and error handling
> * Consider performance impact of large option sets
> * Document business rules for option availability
> * Test with realistic data volumes
> * Implement proper error handling for external data sources

> [card] Performance
>
> * Cache frequently used option lists
> * Implement lazy loading for large datasets
> * Optimize search algorithms for responsiveness
> * Consider pagination for very large lists
> * Monitor performance with real-world data
> * Test on various devices and network conditions

## Common use cases

| Scenario | Configuration | Features Used |
| - | - | - |
| **Country Selection** | Enumeration source | Search, large option list |
| **Department Selection** | Static options with roles | Conditional enabling based on user role |
| **Product Categories** | Process data with availability | Dynamic options, disabled out-of-stock items |
| **Status Selection** | Static with validation | Required validation, status-dependent actions |
| **Dynamic Filtering** | Dependent dropdowns | Parent-child relationships, real-time updates |


# Slider
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/slider

The slider lets end users select a numeric value from a defined range by dragging a handle, with configurable min and max values, step size, and an optional value label.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/slider.gif)

The slider component lets end users pick a numeric value from a defined range by dragging a handle. You set the range with min and max values, control granularity with a step size, and can display the selected value with an optional suffix such as a unit of measurement. Like other form elements, the slider binds to a process data key so the selected value can drive business rules, decisions, and integrations.

## Configuring the slider element

### Slider generic settings

The available configuration options for this form element are:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#hide/disable-expressions)
* [**Event handlers**](#event-handlers)
* [**Slider styling**](#slider-styling)

#### Process data key

Process data key establishes the binding between the slider element and process data, enabling its later use in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node).

#### Properties

* **Label**: The visible label for the slider element.
* **Show value label**: A toggle option that determines whether the current selected value of the slider is displayed as a label alongside the slider handle.
* **Helpertext**: Additional information about the slider element, which can be optionally hidden within an infopoint.
* **Min Value** : The minimum value or starting point of the slider's range, it defines the lowest selectable value on the slider.
* **Max Value**: The maximum value or end point of the slider's range, it sets the highest selectable value on the slider.
* **Suffix**: An optional text or symbol that can be added after the displayed value on the slider handle or value label, it is commonly used to provide context or units of measurement.
* **Step size**: The increment or granularity by which the slider value changes when moved, it defines the specific intervals or steps at which the slider can be adjusted, allowing users to make more precise or discrete value selections.

#### Datasource configuration

**Default Value**: The default value of the slider (static value - integer) the initial value set on the slider when it is first displayed or loaded, it represents a static value (integer), that serves as the starting point or pre-selected value for the slider, users can choose to keep the default value or adjust it as desired.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/slider_general.png)

#### Validators

The following validators can be added to a slider: `required` and `custom`. For more information, see the [validators documentation](../../validators).

#### Hide/disable expressions

* **Hide condition**: A JavaScript expression that hides the slider element when it returns a truthy value.
* **Disabled condition**: A JavaScript expression that disables the slider element when it returns a truthy value.

> [!NOTE]
>
> It’s important to make sure that disabled fields have the same expression configured under the path expressions → hide.

#### Event handlers

Event handlers can be added to the slider element to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the action type. For more information, see the [Event Handlers documentation](../../event-handlers).

### Multiple sliders

You can also use multiple sliders UI elements that are interdependent, as you can see in the following example:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/multiple_sliders.gif)

> [!NOTE]
>
> You can improve the configuration of the slider using computed values as in the example above. These values provide a more flexible approach for handling complex use cases. You can find an example by referring to the following documentation:
>
> [**Dynamic & computed values**](../../dynamic-and-computed-values#computed-values)

### Slider settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the slider label.
  * **Helpertext**: Override helper text/info point.
  * **Show value**: Override the show value option.
  * **Suffix**: Override the suffix.
* Expressions:
  * **Hide**: Override the hide expression.

> [!TIP]
>
> Overrides can always be imported/pushed from one platform to another:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

### Slider styling

> [tab] Web
>
> #### Sizing
>
> Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
>
> * **fill**: Fills the available space.
> * **fixed**: Maintains a fixed width.
> * **auto**: Adjusts the width automatically based on content.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.

#### Slider style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)

Style options:

> [accordion] Common Properties
>
> * Limits font **\[FONT]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/select_ov_com_props.png)

> [accordion] Label
>
> * Default state
>   * Text color **\[COLOR]**
> * Disabled state
>   * Text color  **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)

> [accordion] Helper
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
> * Helper Tooltip
>   * Text style **\[FONT]**
>   * Text color **\[COLOR]**
>   * Background color **\[COLOR]**
>   * Icon Color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)

> [accordion] Error
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)

> [accordion] Default state
>
> * Empty **\[COLOR]**
>
> * Filled **\[COLOR]**
>
> * Knob color **\[COLOR]**
>
> * Limits **\[COLOR]**
>
> * Value **\[COLOR]**
>
> > [!NOTE]
> >
> > On iOS, overrides for the **Knob** are not available.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)

> [accordion] Disabled State
>
> * Empty **\[COLOR]**
>
> * Filled **\[COLOR]**
>
> * Knob color **\[COLOR]**
>
> * Limits **\[COLOR]**
>
> * Value **\[COLOR]**
>
> > [!NOTE]
> >
> > On iOS, overrides for the **Filled** and **Empty** states, as well as the **Knob**, are not available.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)

> [!NOTE]
>
> You can import or push the overrides from one platform to another without having to configure them multiple times.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)


# Switch
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field

Enable users to toggle between two states with an intuitive switch interface that stores boolean values in your process instances.

A switch component provides users with a simple toggle interface to select between two states (on/off, true/false). When users interact with the switch, the corresponding boolean value is automatically stored in the process instance for use in decisions, business rules, and integrations.

![Switch component demonstration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/switch_form_field.gif)

## Configuration overview

Configure your switch component using these main sections:

> [card] Basic Settings
>
> Process data binding, labels, and switch type

> [card] Data & Validation
>
> Default values, datasources, and validators

> [card] Behavior
>
> Hide/disable conditions and event handlers

> [card] Styling
>
> Visual appearance and platform-specific overrides

## Basic configuration

### Process data key

The process data key creates a binding between your switch component and the process data, enabling you to reference the switch value in:

* [Decision nodes](../../../node/exclusive-gateway-node)
* [Business rule actions](../../../actions/business-rule-action/business-rule-action)
* [Integration tasks](../../../node/message-send-received-task-node)

### Core properties

> [accordion] Label
>
> **Purpose**: The visible text displayed alongside the switch
>
> **Features**:
>
> * Supports full Markdown syntax for rich formatting
>
> * Can include links, emphasis, and other Markdown elements
>
> * Responsive across all platforms
>
> > [!TIP]
> >
> > Use Markdown to enhance your labels with **bold**, *italic*, or [linked text](https://www.markdownguide.org/cheat-sheet/).
>
> ![Label with Markdown formatting](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/label_attributed.png)

> [accordion] Switch Type
>
> Choose the visual representation of your switch:
>
> | Type | Description | Best Used For |
> | - | - | - |
> | **Toggle** | Traditional sliding switch | On/off states, preferences |
> | **Checkbox** | Square checkbox interface | Agreements, confirmations |

> [accordion] Helper Text
>
> **Purpose**: Provide additional context or instructions
>
> **Options**:
>
> * Display as regular text below the switch
> * Hide within an expandable info point tooltip
> * Support for Markdown formatting

## Data configuration

### Default value

Set the initial state of your switch component:

* **Default**: Switch starts in the "on" position (true)
* **Alternative**: Configure to start in the "off" position (false)

> [!WARNING]
>
> Choose your default value carefully as it affects user experience and data collection patterns.

### Validation rules

Apply these validators to ensure data quality:

> [tab] Required True
>
> **Use case**: Force users to accept terms, confirm agreements
>
> **Behavior**: Switch must be in the "on" position to pass validation
>
> **Error message**: Customize the message shown when validation fails

> [tab] Custom Validator
>
> **Use case**: Complex business logic validation
>
> **Implementation**: Write custom JavaScript validation functions
>
> **Documentation**: [Learn more about custom validators](../../validators)

![Switch validation configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/switch_details.png)

## Behavior configuration

### Hide/disable expressions

Define the switch element's behavior using JavaScript expressions to control its visibility or disablement:

* Hide condition: A JavaScript expression that hides the Switch element when it returns a truthy value.
* Disabled condition: A JavaScript expression that disables the Switch element when it returns a truthy value.

#### Hide expression example

We can use a rule to hide a switch element if another field has a null value (it is not filled). For example, the "Terms Agreement" switch, which remains hidden until users fill in the "Email" field:
Rule used:

```javascript theme={"dark"}
${application.input.email} === null || ${application.input.email} === ""
```

#### Disable expressions

You can use a disabled condition to disable a switch element based on values from other fields or based on permissions.

> [!NOTE]
>
> It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

### Event handlers

Configure interactive behaviors for your switch:

| Event | Description | Common Use Cases |
| - | - | - |
| **CHANGE** | Triggered when switch state changes | Update related fields, trigger calculations, send notifications |

**Action Types Available**:

* Navigate to different pages
* Execute business rules
* Call external services
* Update other form elements

> [!TIP]
>
> For detailed event handler configuration, see the [Event Handlers guide](../../event-handlers).

## Platform customization

### Settings overrides

Customize your switch differently across platforms:

> [tab] Web Applications
>
> * Override labels for web-specific terminology
> * Adjust helper text for desktop users
> * Modify hide/show expressions for web workflows

> [tab] Mobile Apps
>
> * Shorter labels for mobile screens
> * Touch-friendly sizing adjustments
> * Platform-specific validation messages

![Platform override import/export](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

> [!NOTE]
>
> Override settings can be imported and pushed between platforms, saving configuration time.

## Visual styling

### Layout options

> [tab] Web Styling
>
> > [accordion] Label Position
> >
> > **Start**: Label appears before the switch (left side)
> > **End**: Label appears after the switch (right side)
>
> > [accordion] Responsive Sizing
> >
> > | Option | Behavior | Best For |
> > | - | - | - |
> > | **Fill** | Expands to use available space | Full-width layouts |
> > | **Fixed** | Maintains specified width | Consistent column layouts |
> > | **Auto** | Adjusts based on content | Dynamic layouts |

> [tab] iOS Styling
>
> Similar styling options as web with iOS-specific design guidelines applied automatically.

> [tab] Android Styling
>
> Follows Material Design principles with Android-specific styling conventions.

### Theme customization

Override default styling for complete visual control:

![Theme override interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov.png)

> [accordion] Label Styling
>
> **Default State**:
>
> * Text color customization
> * Font family and size options
>
> **Disabled State**:
>
> * Dimmed text color options
> * Consistent typography
>
> ![Label styling options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_label.png)

> [accordion] Helper Text Styling
>
> **Standard Helper**:
>
> * Text color and font options
>
> **Tooltip Helper**:
>
> * Background color customization
> * Icon color options
> * Typography controls
>
> ![Helper text styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_helper.png)

> [accordion] Error State Styling
>
> * Error message text color
> * Font styling for error states
> * Consistent error indication
>
> ![Error styling options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_error.png)

> [accordion] Switch States
>
> > [tab] Unselected (Off)
> >
> > * Border color customization
> > * Background color options
> > * Switch knob color
> >
> > ![Unselected state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_unselected.png)
>
> > [tab] Selected (On)
> >
> > * Active border color
> > * Active background color
> > * Active knob color
> >
> > ![Selected state styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_selected.png)
>
> > [tab] Disabled States
> >
> > **Disabled Unselected**:
> >
> > ![Disabled unselected styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_unselected_state.png)
> >
> > **Disabled Selected**:
> >
> > ![Disabled selected styling](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/checkbox_ov_disabled_selected_state.png)

> [!NOTE]
>
> **Time-Saving Tip**: Export your styling configuration from one platform and import it to others to maintain consistency without manual reconfiguration.
>
> ![Style import/export workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)

## Best practices

> [card] [Accessibility](../../../../platform-deep-dive/accessibility)
>
> * Provide clear, descriptive labels
> * Use helper text for complex switches
> * Set an accessibility label when the switch has no visible label
>
> See the [Accessibility guide](../../../../platform-deep-dive/accessibility) for keyboard navigation and screen reader details.

> [card] User Experience
>
> * Choose appropriate default values
> * Provide immediate visual feedback
> * Use consistent switch types throughout your application
> * Consider the context when placing switches

> [card] Data Management
>
> * Use meaningful process data keys
> * Plan for boolean value usage in business rules
> * Consider validation requirements early
> * Document switch behavior for other developers

## Common use cases

| Scenario | Configuration | Notes |
| - | - | - |
| **Terms & Conditions** | Required validator, default off | Forces user interaction |
| **Feature Toggles** | No validation, default varies | User preference setting |
| **Permissions** | Conditional display/disable | Role-based access control |
| **Status Indicators** | Read-only mode | Display-only information |


# Text area
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/form-elements/text-area

Capture multi-line input from users for longer responses such as descriptions, comments, or feedback.

![Text area](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/text_area41.png)

It is an important tool for creating intuitive and effective conversational interfaces that can collect and process large amounts of user input.

## Configuring the text area element

### Text area generic settings

These settings added in the Generic tab are available and they apply to all platforms including Web, iOS, and Android:

* [**Process data key**](#process-data-key)
* [**Properties**](#properties)
* [**Datasource**](#datasource-configuration)
* [**Validators**](#validators)
* [**Expressions**](#hide/disable-expressions)
* [**Event handlers**](#event-handlers)
* [**Text area styling**](#text-area-styling)

#### Process data key

Process data key creates the binding between form element and process data, so it can be later used in [decisions](../../../node/exclusive-gateway-node), [business rules](../../../actions/business-rule-action/business-rule-action) or [integrations](../../../node/message-send-received-task-node)

#### Properties

* **Label**: The visible label for the text area element.
* **Placeholder**: Text that appears within the text area when it is empty.
* **Has Clear**: Option to include a content clear mechanism.
* **Helpertext**: Additional information about the text area field (can be hidden inside an infopoint).
* **Update on Blur**: Update behavior triggered when the text area loses focus.

#### Datasource configuration

The default value for the element can be configured here, this will autofill the text field when you will run the process.

#### Validators

You can add multiple validators to a text area field. For more details, refer to [**Validators**](../../validators).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/text_area_props.png)

#### Hide/disable expressions

The text area's behavior can be defined using JavaScript expressions for hiding or disabling the element. The following properties can be configured for expressions:

* **Hide condition**: A JavaScript expression used to hide the text area when it is evaluated to your desired result.
* **Disabled condition**: A JavaScript expression used to disable the text area when it returns a truthy value

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide_text_area.png)

> [!NOTE]
>
> In the example above, we used a rule to hide a text area element if the value of the switch element above is false.

#### Hide expression example

We will use the key defined on the switch element to create a JavaScript hide condition to hide the text area element:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide_text_area1.png)

* Rule used:

```javascript theme={"dark"}
${application.client.hasHouse} === false
```

* Result:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/text_area_result.gif)

#### Disable example

For example, you can use a disabled condition to disable a text area element based on what values you have on other elements.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/disable_text_area1.png)
![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/disable_text_area2.png)

When you choose a specific value on the radio element (Contact via SMS), the text area is disabled based on the disabled condition.

* Rule used:

```javascript theme={"dark"}
${application.client.contact} == "prfS"
```

> [!NOTE]
>
> It's important to make sure that disabled fields have the same expression configured under the path expressions → hide.

#### Event handlers

Event handlers can be added to the text area field to define its behavior and interactions.

* **Event**: Possible value - `CHANGE`.
* **Action Type**: Select the type of the action to be performed.

> [!TIP]
>
> For more information, see the [Event Handlers documentation](../../event-handlers).

### Text area settings overrides

There are instances where you may need to tailor settings configured in the **Generic** settings tab. This proves especially beneficial when you wish to adjust these settings to appear differently across various platforms such as Web, Android, or iOS.

Available override settings:

* Properties:
  * **Label**: Override the text area label.
  * **Helper**: Override helper text/info point.
  * **Placeholder**: Override the placeholder.
* Expressions:
  * **Hide**: Override the hide expression.

> [!TIP]
>
> Overrides can always be imported/pushed from one platform to another:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/importing_pushing_overrides.gif)

### Text area styling

> [tab] Web
>
> > [tab] Sizing
> >
> > #### Fit W (fit width)
> >
> > Adjusting the size of components is crucial for a responsive design. Fit W (width) offers three options:
> >
> > * **fill**: Fills the available space.
> > * **fixed**: Maintains a fixed width.
> > * **auto**: Adjusts the width automatically based on content.
> >
> > #### H Type (height type)
> >
> > * **fixed**: Maintains a fixed height (pixels)
> > * **auto**: Adjusts the height automatically based on the content.
> >
> > #### Rows
> >
> > * **Min Rows**: Sets the minimum number of rows.
> > * **Max Rows**: Sets the maximum number of rows.

> [tab] iOS
>
> Similar styling considerations apply to iOS as for web.
>
> * **fixed height**: Measured in dp - density-independent pixels.

> [tab] Android
>
> Similar styling considerations apply to Android as for web.
>
> * **fixed height**: Measured in pt - points.

#### Text area style overrides options

Theme overrides refer to the ability to modify or customize the appearance and behavior of UI components by overriding default theme settings. This can be applied at various levels, such as specific elements or entire sections, and can be platform-specific (Web, iOS, Android).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_all.png)

Style options:

> [accordion] Common Properties
>
> * Border radius **\[TEXT]**
> * Border width **\[TEXT]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_common_props.png)

> [accordion] Label
>
> * Default state
>   * Text color **\[COLOR]**
> * Disabled state
>   * Text color  **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_label.png)

> [accordion] Helper
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
> * Helper Tooltip
>   * Text style **\[FONT]**
>   * Text color **\[COLOR]**
>   * Background color **\[COLOR]**
>   * Icon Color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_helper.png)

> [accordion] Error
>
> * Text color **\[COLOR]**
> * Text style **\[FONT]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_error.png)

> [accordion] Empty State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_empty_state.png)

> [accordion] Active State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_active_state.png)

> [accordion] Filled State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_filled_state.png)

> [accordion] Disabled State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_disabled_state.png)

> [accordion] Error State
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_error_state.png)

> [accordion] Hover State (only for Web configuration)
>
> * Border color **\[COLOR]**
> * Background color **\[COLOR]**
> * Text color **\[COLOR]**
> * Right icon color **\[COLOR]**
> * Left icon color **\[COLOR]**
> * Prefix/Suffix color **\[COLOR]**
> * Placeholder color **\[COLOR]**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/input_ov_hover_state.png)

> [!NOTE]
>
> You can import or push the overrides from one platform to another without having to configure them multiple times.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/ov_push_import.gif)


# Image
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/image

Image UI elements are graphical components of a user interface that display a static or dynamic visual representation of an object, concept, or content.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_general.png)

These elements can be added to your interface using the UI Designer tool, and they are often used to convey information, enhance the aesthetic appeal of an interface, provide visual cues and feedback, support branding and marketing efforts, or present complex data or concepts in a more intuitive and accessible way.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_generic.png)

## Configuring an image

Configuring an image in the UI Designer involves specifying various settings and properties. Here are the key aspects of configuring an image:

### Image settings

The image settings consist of the following properties:

* **Source location** - the location from where the image is loaded:

  * [**Media Library**](#media-library)
  * [**Process Data**](#process-data)
  * [**External**](#external)

Depending on which **Source location** is selected, different configurations are available:

### Media library

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_media_library1.png)

* **Image key** - the key of the image from the media library
* **Select from media library** - search for an item by key and select it from the media library

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/search_item_by_key.png)

* **Upload to media library** - add a new item (upload an image on the spot)
  * **upload item** - supported formats: PNG, JPG, GIF, SVG, WebP; ❗️(maximum size - 50 MB by default)
  * **key** - the key must be unique and cannot be changed afterwards

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/upload_to_media_lib.png)

### Process data

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/process_data.gif)

* Identify the **Source Type**. It can be either a **URL** or a **Base 64 string**.
* Locate the data using the **Process Data Key**. With **URL**, the value at that key is used as-is, so it must be a complete, absolute URL. The renderer attaches the user's access token only when the URL ends in `download`. To show a file uploaded through the Documents plugin, build the URL from the upload reply's `downloadPath` in a business rule, as shown in [Preview an uploaded file](./file-preview#preview-an-uploaded-file).
* In a UI Flow, where this location is labeled **Local Variables**, **Source Type** also offers **Document plugin**. Point the key to an object that contains `downloadPath`, such as an upload reply, and the renderer builds the URL.
* If using a URL, provide a **Placeholder URL** for public access. This is the URL where the image placeholder is available.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, **Source** in a process user task offers **Media Library**, **Document Plugin Path**, **URL**, and **Base64**. With **Document Plugin Path**, point the key at a Documents plugin `downloadPath` and the renderer builds the URL, so no business rule is needed. For how the shared file sources work, see [File sources in FlowX.AI 5.13](./file-preview#file-sources-in-flowx-ai-5-13).&#x20;

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/process_data_img.png)

### External

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_external.png)

* **Source Type**: it can be either a **URL** or a **Base 64 string**
* **Image source**: the valid URL of the image.
* **Placeholder URL**: the public URL where the image placeholder is available

## Event handlers

The event handlers property allows you to add an event handler, which must be configured on the same node. For more information, see the [Event Handlers documentation](../event-handlers).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_ui_actions.png#center)

## Image styling

The image styling property allows you to add or to specify valid CSS properties for the image. For more information, see the [styling documentation](../../ui-designer/ui-designer#styles-tab).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/image_styling.png)

## Color

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The image component has a **Color** property that applies a color to the image, useful for tinting single-color icons and SVGs so they match a theme without editing the source asset. Set it in the component's configuration; the color is applied by the web and Android renderers.


# Indicators
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/indicators

The indicators (Message UI elements) allow you to display different types of messages.

Messages can be categorized into the following types:

* **Info**: Used to convey general information to users.
* **Warning**: Indicates potential issues or important notices.
* **Error**: Highlights errors or critical issues.
* **Success**: Communicates successful operations or completion.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicators_gen.png)

## Properties

When configuring a message, you have the following properties:

* **Message**: The content of the message body, this property supports markdown attributes such as: bold, italic, bold italic, strikethrough and URLs, allowing you to format the content of the message.
* **Type**: one of the four indicator types: info, warning, error, success
* **Expressions**: you can define expressions to control when the message should be hidden. This can be useful for dynamically showing or hiding messages based on specific conditions.
* **Platform overrides**: the **Message** text and the **Hide** expression can be overridden per platform. Select the message element, then go to **Settings** → your desired platform → **Overrides (+)** and pick **Message** or **Expressions** → **Hide**. Use this to show a shorter message on mobile or hide the banner on one platform only.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicators_prop.png)

Info example with markdown:

```markdown theme={"dark"}
If you are encountering any difficulties, please [contact our support team](mailto:support@flowx.ai).
```

When executed, will look like this:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicators1.png)

## Types and Usage

Here's how you can use the Message UI element in your UI design:

### Info

If you are encountering any difficulties, please [contact our support team](mailto:support@flowx.ai).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/info_indicator.png)

### Error

An error occurred while processing your request. Please try again later.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_error.png)

### Success

Your payment was successfully processed. Thank you for using our services!

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_success.png)

## Indicators styling

To create an indicator with specific styling, sizing, typography, and color settings, you can use the following configuration:

### Style

The Style section allows you to customize the appearance of your indicator UI element. You can apply the following style to achieve the desired visual effect:

* **Text**: Displays only the icon and the text.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_text.png)

* **Border**: Displays the icon, the text and the border.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_border.png)

* **Fill**: It will fill the UI element's area.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/indicator_fill.png)

> [!TIP]
>
> For more information, see the [styling documentation](../../ui-designer/ui-designer#styles-tab).


# Markdown
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown

A UI component that renders Markdown-formatted content on a screen.

> [!NOTE]
>
> This is the standalone Markdown UI component. For Markdown rendering inside chat messages, see the [Chat](./chat) component.

## Overview

Use a Markdown component when you need to display rich text that may include structure (headings, lists, tables) or content authored in Markdown by an AI model, a CMS entry, or a process data field. Common use cases:

* Surfacing an AI-generated explanation alongside a form
* Embedding Terms & Conditions or Help text written in Markdown
* Rendering a step-by-step instruction list pulled from CMS
* Showing a tabular summary returned by a workflow

The Markdown component is read-only. Bind its content to a process data key or a static value, and it renders on the fly.

## Properties

| Property | Type | Description |
| - | - | - |
| **Content** | String / expression | Markdown source. Bind to a process data key or set a static literal. |
| **Visibility** | Expression | JavaScript expression that hides the component when truthy. |
| **Theme overrides** | Object | Override fonts, colours, link colour, heading styles, and table styling for this instance. |

## Supported Markdown

Standard CommonMark syntax: headings (`#` to `######`), bold/italic, links, ordered and unordered lists, fenced code blocks, inline code, blockquotes, and tables (GFM-style). Raw HTML is not rendered.

## Theme configuration

The Markdown component exposes two theme entries: **Markdown** (for the body) and **Markdown table** (for tables embedded inside Markdown content).

### Markdown — body defaults

| Token | Default | Description |
| - | - | - |
| `font` | `typography@Paragraph/P1#regular` | Base body typography. |
| `color` | `color@shades#900` | Body text colour. |
| `linkColor` | `color@primary#500` | Inline link colour. |
| `heading1Font` | `typography@Heading/H5#medium` | H1 typography. |
| `heading2Font` | `typography@Heading/H6#medium` | H2 typography. |
| `heading3Font` | `typography@Paragraph/P3#medium` | H3 typography. |
| `heading4Font` | `typography@Paragraph/P2#medium` | H4 typography. |
| `heading5Font` | `typography@Paragraph/P2#medium` | H5 typography. |
| `heading6Font` | `typography@Paragraph/P2#medium` | H6 typography. |

### Markdown table — defaults

| Token | Default | Description |
| - | - | - |
| `borderColor` | `color@neutrals#200` | Outer table border colour. |
| `dividerColor` | `color@neutrals#200` | Row and column divider colour. |
| `backgroundColor` | `color@shades#0` | Cell background. |
| `font` | `typography@Paragraph/P1#regular` | Cell typography. |
| `color` | `color@shades#900` | Cell text colour. |
| `headerFont` | `typography@Paragraph/P1#medium` | Header row typography. |
| `headerColor` | `color@shades#900` | Header row text colour. |
| `headerBackgroundColor` | `color@neutrals#100` | Header row background. |

To override globally, edit **Theme → Components → Markdown** (and **Markdown table**) in the Designer.

## Related resources

> [card] [UI Designer overview](../ui-designer)
>
> Compose screens in the UI Designer.

> [card] [Typography](./typography)
>
> Configure typography styles for text components.


# Multiple file upload
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload

A drag-and-drop upload component that lets users select and upload multiple files in a single action.

The Multiple File Upload component provides a drag-and-drop area where users can select multiple files and upload them in a single request. It is purpose-built for workflows that require batch document submission — such as onboarding packets, supporting evidence, or multi-page scans.

![Multiple File Upload component with two selected files and the Upload Files and Remove Files buttons](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/18b-multiple-file-upload-selected.png)

***

## Overview

Unlike the [File Upload Button](./buttons#file-upload-button), which handles one file at a time via a button click, the Multiple File Upload component offers:

> [card] Batch uploads
>
> Upload multiple files in a single request with individual validation per file

> [card] Drag and drop
>
> Drag-and-drop zone with click-to-browse fallback

> [card] File management
>
> Preview selected files with name, size, and a remove option before uploading

**Platform availability:** React SDK (web) — since 5.5.0. Angular SDK (web) — since 5.8.0. Available in both process-based screens and UI Flows.

### UI Flow upload flow

When the component is bound to a UI Flow upload action:

1. The SDK uploads the selected files to the temp-file store via `POST /document/internal/wks/{workspaceId}/temp-files/upload-multiple` (multipart, document-plugin).
2. The SDK calls `POST /api/runtime/wks/{workspaceId}/appId/{appId}/ui-flow/{uiFlowSessionId}/upload-multiple` (process-engine) with the list of returned temp-file IDs. The 200 response returns a server-generated `uploadBatchId`.
3. process-engine sends a single bulk command to document-plugin; document-plugin persists each file in the session.
4. The SDK receives one SSE frame (`eventType=UI_FLOW_FILE_UPLOAD_MULTIPLE`, `namespace=uploadBatchId`) carrying the per-file results.
5. The per-file results are written to the action's `responseKey` as a list under the UI Flow session variables.

**UI Flow response shape:**

```json theme={"dark"}
{
  "documents": [
    { "uploadResponseId": "...", "fileName": "...", "fileSize": 123, "errorMessage": null }
  ]
}
```

The UI Flow per-file shape (`UiFlowUploadResponse`) is a subset of the process-based upload response — it omits `customId`, `fileId`, `documentType`, `documentLabel`, and `status`, which are not meaningful for session-scoped uploads.

***

## Component properties

The following properties are available in the Multiple File Upload configuration panel:

### Display

| Property | Key | Description | Default |
| - | - | - | - |
| **Title** | `title` | Heading displayed in the drop zone | `"Drag & drop your files here"` |
| **Subtitle** | `subtitle` | Supporting text below the title | `"or click to browse your files"` |
| **Browse label** | `browseLabel` | Text on the browse button | `"Browse Files"` |
| **Upload label** | `uploadLabel` | Text on the upload action button | `"Upload Files"` |
| **Reset label** | `resetLabel` | Text on the remove/reset button | `"Remove Files"` |

### Validation

| Property | Key | Description | Default | Required |
| - | - | - | - | - |
| **Accepted file types** | `accept` | Comma-separated MIME types, extensions, or wildcards (e.g., `png`, `application/pdf`, `image/*`) | — | Yes |
| **Invalid file type message** | `invalidFileType` | Error shown when a file does not match accepted types | — | Yes |
| **Max files** | `maxFiles` | Maximum number of files allowed per upload | — | Yes |
| **Max files exceeded message** | `filesExceeded` | Error shown when the file count exceeds the limit | — | Yes |
| **Max files size** | `maxFilesSize` | Maximum total size of all files in bytes | — | Yes |
| **Files size exceeded message** | `filesSizeExceeded` | Error shown when total size exceeds the limit | — | Yes |

> [!WARNING]
>
> All validation properties are required. You must configure accepted file types, max file count, and max file size along with their corresponding error messages.

### Feedback

| Property | Key | Description | Default |
| - | - | - | - |
| **Show success** | `showSuccess` | Display a toast notification on successful upload | `false` |
| **Success message** | `successMessage` | Custom success toast text | `"Files successfully uploaded"` |
| **Show error** | `showError` | Display a toast notification on upload failure | `false` |
| **Error message** | `errorMessage` | Custom error toast text | `"There was an error with the upload"` |
| **Loading type** | `loading` | Loading indicator style (`Overlay` or `None`) | `None` |
| **Loading message** | `loadingMessage` | Text displayed during the upload | `"Files are being uploaded..."` |

### Visibility

| Property | Key | Description |
| - | - | - |
| **Hide condition** | `hide` | Expression that hides the component when it evaluates to `true` |
| **Disabled condition** | `disabled` | Expression that disables the component when it evaluates to `true` |

***

## Event handler configuration

The Multiple File Upload component only supports the **Upload** action type.

When configuring the event handler for this component, set:

* **Event type**: `CLICK`
* **Action type**: `Upload`

This links the component to an [Upload File action](../../actions/upload-file-action) configured on the node. The SDK automatically populates `{actionName}TempFileIds` (a list of UUIDs) in the process instance params before triggering the action.

> [!NOTE]
>
> Starting with 5.5.0, the existing [File Upload Button](./buttons#file-upload-button) is also adjusted so that **Upload** is its only selectable action type (matching this component). It continues to work with the single-file path (`{actionName}TempFileId`). Both components can coexist in the same process.

***

## How it works

**1. User selects files**

The user drags files into the drop zone or clicks **Browse Files** to select them. Each file is validated against the configured accepted types, max files count, and max file size.

**2. Files uploaded to temporary storage**

When the user clicks **Upload Files**, the SDK sends all selected files in a single `multipart/form-data` request to the document plugin's bulk temp upload endpoint. The response returns a list of temporary file IDs.

**3. Process action triggered**

The SDK populates `{actionName}TempFileIds` with the list of temp file IDs and triggers the Upload File action. The process engine detects the list key and routes the request through the bulk Kafka path.

**4. Documents persisted**

The document plugin receives the bulk persist request on `ai.flowx.plugin.document.trigger.persist.document.bulk.v1`, processes each file individually, and returns a response with per-file results (including partial success handling) on `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1`. Each file in the reply has its own `downloadPath`.

For the backend configuration details, see the [Upload File action](../../actions/upload-file-action) documentation and the [document upload scenario](../../../platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document). To show each uploaded file on the same user task, see [Preview files in a collection](./file-preview#preview-files-in-a-collection).

***

## Important behavior

> [accordion] Document type and storage
>
> All files uploaded through this component share the same `customId` and use `documentType=BULK` with `shouldOverride=false`. This means:
>
> * Multiple files accumulate under the same `customId` — they are stored as separate documents, not as a single archive
> * **Re-uploading does not replace previous files** — it adds new ones alongside the existing documents
> * If you need to replace previously uploaded files, you must delete them separately before re-uploading

> [accordion] Action order on the node
>
> The process engine rejects the Upload File action while a mandatory action placed above it on the same node hasn't run. In the node's **Actions** list, place the Upload File action above mandatory manual actions such as the `saveData` action the user task creates.

> [accordion] Validation scope
>
> Validation runs **client-side before upload**:
>
> * **File type** — validated per file against the `accept` property
> * **File count** — validated against `maxFiles` (total selected files)
> * **Total size** — validated against `maxFilesSize` (sum of all file sizes)
>
> There is no per-file size limit in this component. Only the total size across all files is checked.

> [accordion] Upload feedback
>
> The component provides an overall loading state (overlay or none) during the upload. Individual per-file progress indicators are not available — the upload is treated as a single batch operation.
>
> After the upload completes, the component clears its state (file list), hides the loader, and shows a success or error toast (if configured).

> [accordion] File selection UX
>
> Users can add files incrementally:
>
> * Drag and drop files into the zone multiple times
> * Click **Browse Files** multiple times to add more
> * Each selected file appears as a card showing file name and size
> * Individual files can be removed with the delete button before uploading
> * The **Remove Files** button clears all selected files at once

***

## Theming

The Multiple File Upload component supports full theming through Theme Admin. The component is registered under `contentWeb → components → bulkFileUpload`.

> [tab] Drop zone
>
> | Token | Description |
> | - | - |
> | **Title font** | Font style for the drop zone heading |
> | **Title color** | Color for the drop zone heading |
> | **Subtitle font** | Font style for the subtitle text |
> | **Subtitle color** | Color for the subtitle text |
> | **Border width** | Drop zone border width (inherits from general) |
> | **Border radius** | Drop zone corner radius (inherits from general) |
> | **Border color** | Drop zone border color |
> | **Background color** | Drop zone background |
> | **Shadow** | Drop zone shadow |

> [tab] File items
>
> | Token | Description |
> | - | - |
> | **File name font** | Font style for the file name |
> | **File name color** | Color for the file name |
> | **File size font** | Font style for the file size text |
> | **File size color** | Color for the file size text |
> | **File border width** | Border width for individual file rows |
> | **File border radius** | Corner radius for individual file rows |
> | **File border color** | Border color for individual file rows |

> [tab] Caption
>
> | Token | Description |
> | - | - |
> | **Caption font** | Font style for helper/caption text |
> | **Caption color** | Color for helper/caption text |

### Icons

The component uses three system icons that are included automatically via CMS migration:

| Icon key | Description |
| - | - |
| `sys_BFUTitle` | Icon displayed in the drop zone header |
| `sys_BFUDocument` | Icon displayed next to each file in the list |
| `sys_BFUDelete` | Icon for the delete/remove button on each file |

### Substitution tags

The component also registers system substitution tags for localization and accessibility:

| Tag code | English | Romanian |
| - | - | - |
| `sys_bfu_max_files_size` | Maximum files size: | Dimensiune maximă a fișierelor: |
| `sys_a11y_bfu_drop_files` | Drop files | Plasează fișierele |
| `sys_a11y_bfu_delete_file` | Delete file | Șterge fișier |

These tags are automatically available after CMS migration and can be customized per language in the CMS.

***

## Related resources

> [card] [Upload file action](../../actions/upload-file-action)
>
> Configure the backend action for single and multi-file uploads

> [card] [Uploading a new document](../../../platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document)
>
> End-to-end document upload scenario with the document plugin

> [card] [File Upload Button](./buttons#file-upload-button)
>
> Single-file upload button component

> [card] [File preview](./file-preview)
>
> Display uploaded documents inline


# Progress bar
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar

A UI component for visualizing progress or completion state on a screen.

## Overview

Use a Progress Bar when the user needs a quick visual answer to *"how far along?"* — for example, a multi-step onboarding flow, a long-running document upload, an order-fulfilment status, or a goal-tracking dashboard.

The Progress Bar is read-only. Bind its value to a process field or computed expression and it updates as the data changes.

## Properties

| Property | Type | Description |
| - | - | - |
| **Progress** | Number (0–1) / expression | The current progress, as a value between `0` and `1` (for example, `0.25` fills the bar to 25%). Bind to a process data key or use a computed expression. |
| **Visibility** | Expression | JavaScript expression that hides the bar when truthy. |
| **Theme overrides** | Object | Override `color`, `backgroundColor`, `height`, `borderRadius` for this instance only. |

## Process data binding

To drive the bar from process data, set **Progress** to a process data key that holds a value between `0` and `1`:

```javascript theme={"dark"}
${application.upload.fractionComplete}
```

For derived values, use a computed expression — for example, mapping a step index to a fraction in a 4-step flow:

```javascript theme={"dark"}
${application.flow.currentStep} / 4
```

See [Dynamic and computed values](../dynamic-and-computed-values) for the full expression syntax.

## Theme configuration

Defaults from the platform theme:

| Token | Default | Description |
| - | - | - |
| `color` | `color@primary#500` | Fill colour of the completed portion. |
| `backgroundColor` | `color@primary#100` | Track colour for the unfilled portion. |
| `height` | `8px` | Bar thickness. |
| `borderRadius` | `4px` | Corner radius applied to both fill and track. |
| `borderColor` | `color@shades#0` | Outline colour. Hidden by default via `borderWidth: 0`. |
| `borderWidth` | `0px` | Set to `1` or higher to display the outline. |

To override globally, edit **Theme → Components → Progress Bar** in the Designer.

## Related resources

> [card] [UI Designer overview](../ui-designer)
>
> Compose screens in the UI Designer.

> [card] [Dynamic and computed values](../dynamic-and-computed-values)
>
> Bind component properties to process data.


# Separator
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/separator

A visual divider component used to group and separate UI content in screens.

## Overview

Use a Separator when you need a clear visual boundary between two regions of a screen — for example, between a form section and an action bar, between repeated rows in a list, or between groups of related fields. Unlike empty containers or padding, a Separator carries explicit meaning to the reader: "this is one section, this is another."

The Separator is allowed inside any container component (Card, Container, Collection) as well as inside chat layouts and process screens.

## Properties

| Property | Type | Description |
| - | - | - |
| **Visibility** | Expression | JavaScript expression that hides the Separator when truthy. |
| **Theme overrides** | Object | Override `color`, `borderWidth`, or other theme tokens for this instance only. See the Conditional styling guide for examples. |

The Separator has no process-data binding — it is purely presentational.

## Theme configuration

Defaults from the platform theme:

| Token | Default | Description |
| - | - | - |
| `color` | `color@neutrals#200` | Line color. Override at the theme level for global changes, or per instance via theme overrides. |

To override the default for an entire workspace, edit the **Theme → Components → Separator** section in the Designer.

## Related resources

> [card] [UI Designer overview](../ui-designer)
>
> Compose screens in the UI Designer.

> [card] [Conditional styling](../conditional-styling)
>
> Apply dynamic styles and theme overrides.


# Table
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/table

The Table component is a versatile UI element allowing structured data display with customizable columns, pagination, filtering, and styling options.

## Overview

The **Table** component is available **only for Web**, built to deliver a consistent design through FlowX.AI’s theming framework. It closely mirrors the [**Collection**](./collection/collection) component functionality, offering dynamic data handling and flexible row/column configurations.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_overview.png)

> [!NOTE]
>
> **Web-only UI Component:** The Table component is designed specifically for web applications and includes theming options for consistent design across the platform.

## Table elements

1. **Table Header (`th`)**\
   Displays column labels, typically one `th` element per column.

2. **Rows (`tr`)**\
   Each row represents a single data entry from the source array. Rows automatically repeat based on your data size.

3. **Cells**\
   Cells hold data points within each row. You can place multiple UI elements (text, image, link, buttons) inside a cell.

4. **Actions Column**\
   If you enable row deletion or editing, an actions column is automatically created to handle row-level features (delete icon, edit icon, etc.).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_actions_column.gif)

> [!NOTE]
>
> By default, when you create a new Table, three columns and a matching set of cell placeholders are generated automatically.

## Configuring the table

When building a Table, you’ll primarily interact with:

* **Generic Settings** (source key, columns, table body, expressions, styling)
* **Cell-Specific Settings** (sorting, filtering, editing, validators)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_settings.png)

> [!TIP]
>
> Below is an example of a JavaScript business rule that populates the Table with mock data. The `users` array is assigned to `application.users`, which serves as the Table’s source.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/dynamic_table.png)
>
> > [accordion] Business rule exmaple
> >
> > ```js theme={"dark"}
> >  users = [
> >     {
> >         "firstName": "John",
> >         "lastName": "Doe",
> >         "loanAmount": {
> >             "amount": 1000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-01-01T00:00:00Z",
> >         "email": "john.doe@example.com"
> >     },
> >     {
> >         "firstName": "John",
> >         "lastName": "Does",
> >         "loanAmount": {
> >             "amount": 2000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-02-01T00:00:00Z",
> >         "email": "john.does@example.com"
> >     },
> >     {
> >         "firstName": "Jane",
> >         "lastName": "Doe",
> >         "loanAmount": {
> >             "amount": 3000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-03-01T00:00:00Z",
> >         "email": "jane.doe@example.com"
> >     },
> >     {
> >         "firstName": "Jane",
> >         "lastName": "Does",
> >         "loanAmount": {
> >             "amount": 4000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-04-01T00:00:00Z",
> >         "email": "jane.does@example.com"
> >     },
> >     {
> >         "firstName": "Jim",
> >         "lastName": "Doe",
> >         "loanAmount": {
> >             "amount": 5000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-05-01T00:00:00Z",
> >         "email": "jim.doe@example.com"
> >     },
> >     {
> >         "firstName": "Jim",
> >         "lastName": "Does",
> >         "loanAmount": {
> >             "amount": 6000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-06-01T00:00:00Z",
> >         "email": "jim.does@example.com"
> >     },
> >     {
> >         "firstName": "Jake",
> >         "lastName": "Doe",
> >         "loanAmount": {
> >             "amount": 7000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-07-01T00:00:00Z",
> >         "email": "jake.doe@example.com"
> >     },
> >     {
> >         "firstName": "Jake",
> >         "lastName": "Does",
> >         "loanAmount": {
> >             "amount": 8000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-08-01T00:00:00Z",
> >         "email": "jake.does@example.com"
> >     },
> >     {
> >         "firstName": "Jill",
> >         "lastName": "Doe",
> >         "loanAmount": {
> >             "amount": 9000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-09-01T00:00:00Z",
> >         "email": "jill.doe@example.com"
> >     },
> >     {
> >         "firstName": "Jill",
> >         "lastName": "Does",
> >         "loanAmount": {
> >             "amount": 10000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-10-01T00:00:00Z",
> >         "email": "jill.does@example.com"
> >     },
> >     {
> >         "firstName": "Joe",
> >         "lastName": "Doe",
> >         "loanAmount": {
> >             "amount": 11000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-11-01T00:00:00Z",
> >         "email": "joe.doe@example.com"
> >     },
> >     {
> >         "firstName": "Joe",
> >         "lastName": "Does",
> >         "loanAmount": {
> >             "amount": 12000.00,
> >             "code": "USD"
> >         },
> >         "birthDate": "1985-12-01T00:00:00Z",
> >         "email": "joe.does@example.com"
> >     }
> > ];
> >
> > application = {
> >     "users": users
> > };
> >
> > output.put("application", application);
> > ```

### Table generic settings

The following generic settings are found in the Generic tab:

* [**Source key**](#source-key)
* [**Columns**](#columns)
* [**Table body**](#table-body)
* [**Expressions**](#hide-condition)
* [**Table Styling**](#table-styling)

#### Source key

* Specify an array of objects (e.g., `application.users`), enabling dynamic row creation based on your data structure.
* Similar to the Collection component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_source_key.png)
![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/Screenshot%202024-10-15%20at%2019.22.32.png)

#### Columns

* Customize the Table’s columns: add, delete, rename, or reorder.
* Each column automatically includes a corresponding th (header cell) and td (body cell).
* A table must keep at least two columns; deleting below that is blocked.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_columns.png)

#### Table body

* **Default Sorting**: Sortable option must be enabled for the selected column for default sorting to work.
  * **Column**: Select the desired column.
  * **Direction**: Set the sort direction (**Ascending** or **Descending**).
* **Pagination**: Toggle **ON** to split rows into pages.
  * **Page Size**: The maximum number of entries displayed per page. Enabling pagination sets it to `20` by default; the minimum accepted value is `1`, and clearing the field or entering an invalid value turns pagination back off. End users cannot change the page size at runtime.
* **Scrolling**: Toggle Pagination **OFF** to render all rows as one continuous, scrollable list.
* **Deletable Rows**: Enable row deletion.

> [!NOTE]
>
> Pagination is client-side: the full source array is loaded and split into pages in the browser. The paginator is a runtime-only control, so it does not appear on the UI Designer canvas preview.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_body.png)

#### Hide condition

* Optionally hide the entire Table based on a JavaScript expression including the data key from another component.
* Useful for conditional flows (e.g., only show the Table if certain conditions are met).

**Demonstration**:

<video />

***

## Feature highlights

### Default sorting

* **Enable default sorting** in table body settings.
* **Select the desired column** and **sort direction** (ascending by default).

> [!TIP]
>
> Sortable option must be enabled for the selected column at **cell level** for default sorting to work.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/cell_sorting.png)

<video />

### Pagination & scrolling

Define how many rows appear on each page using **Pagination** feature.

<video />

* **Scrolling**: Disable pagination to allow continuous scrolling.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/disable_pagination.png)

### Remembered view state

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.4**

While a UI Flow session is active, each table remembers its filter values, sort order, and current page across data refreshes and re-renders, so interacting with the page no longer resets the table view.

* The remembered page is restored once rows are available again; if the data shrank, it clamps to the last available page.
* The view state lives in the browser session only. The page index is never written to process data.
* Navigating to the screen again or ending the UI Flow session resets the remembered state.
* This applies to UI Flow sessions only: tables on screens rendered by a BPMN process (user tasks) do not remember view state.

### Empty state

When the source array is empty, the table shows the `@@sys_table_empty` substitution tag, which defaults to "No data to show". Override the tag in your CMS substitution tags to customize the text.

### Editable rows

Enable row editing in **cell-level → column settings**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-23%20at%2017.04.39.png)

* Editing can be triggered by double-click or the dedicated Edit button icon.

> [!TIP]
>
> Make sure each editable cell references a valid data model key to facilitate edit.

* Edits are validated and saved row-by-row.

The editor type for each cell is automatically determined by the data model type of the column's key:

| Data Model Type | Editor |
| - | - |
| String (default) | Text input |
| Integer, Float, Currency | Number input |
| Boolean | Toggle switch |
| Date/Time | Date picker |
| Enum | Single-select dropdown |

> [!TIP]
>
> For enum columns, the dropdown options are automatically loaded from the enumeration referenced in the data model. No additional configuration is needed — set the column's **Editable** toggle to ON and ensure the key references an ENUM data model type.

### Deletable rows

Toggle **Deletable** in Table settings to enable row deletion.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.15.17.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-23%20at%2017.17.32.png)

> [!TIP]
>
> A delete icon will appear in the Actions column, removing the corresponding row from the data source.

### Filters

Mark columns as filterable to enable filtering icons.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-24%20at%2016.37.06.png)

* Filter type automatically matches the column data type (string, number, date, boolean, or currency).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-24%20at%2016.48.18.png)

> [!TIP]
>
> Filtering option is ideal for large data sets where quick column-based searches are necessary.

## Table styling

### Sizing

* **Fit Width**: By default, the Table stretches to occupy available width.
* **Fit Height**: Grows automatically based on content height.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/table_sizing.png)

> [!TIP]
>
> **Horizontal scrolling** kicks in automatically when the combined column widths exceed the table's container. Set columns to **Fixed** widths large enough that their sum overflows, and the table renders a horizontal scrollbar at the bottom. This is useful on mobile or narrow layouts where many columns can't fit at once.

### Cell styling

**Layout Options:**

* **Direction**: Horizontal (default).
* **Justify**: Space-around (evenly spaces elements within each cell).
* **Align**: Start (left-aligned).
* **Wrap**: Enables text wrapping.
* **Gap**: 8px spacing between cell elements.

**Column Style Options:**

* **Width Fit Options**:
  * **Fill**: Fills available container space.
  * **Fixed**: Keeps a fixed column width.
  * **Auto**: Adjusts column width to fit content.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/cell_styling.png)

* **User Resizable Columns**: Adjust column width by dragging the column edges in the header, enhancing customization.

![User Resizable Columns](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/2024-10-15%2019.37.13.gif)

This Table component enhances flexibility and offers a cohesive design, integrated with FlowX.AI’s theming framework for a consistent, web-optimized user experience.

## Table event handler

Append a saveData action to the table and configure the action’s custom keys with the same key used as source for the table, in order for the backend to take into consideration the updated array.

See [**User Task configuration**](#user-task-configuration) section for more details.

## Actions in table cells

When configuring actions within a Table component, each action is bound to a unique table item key, ensuring that interactions within each cell are tracked and recorded precisely.
The key allows the action to target specific rows and store results or updates effectively.

* **Table Item Save Key**:
  * This key is essential for identifying the exact cell or row where an action should be executed and saved.
  * It ensures that data within each cell remains distinct and correctly mapped to each table entry.
* **Custom Key for Data Saving**:
  * Important: To properly send the data from a selected cell/row to the backend, you must configure both a **Custom Key** (in your `SaveData` action) and a **Table Item Save Key** (in your column/cell configuration) using the same value.
  * Having only a `Table Item Save Key` is not sufficient to propagate the updated information. The matching **Custom Key** in the **SaveData** action tells the system which row/cell data to capture and transmit.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/table_item_save_key.png)

* **Supported Action Types** - Available actions include:
  * **Action**: Initiates predefined actions within the cell.
  * **Start Process Inherit**: Enables workflows inherited from process configurations to be triggered.
  * **Upload**: Allows file or data uploads directly within a table cell.
  * **External**: Used to create an action that will open a link in a new tab.

## User Task configuration

When configuring a screen in User Task containing table, you must configure the following node actions:

**1. Configure SaveData Action**

* The `SaveData` action must be:
  * **Manual**: Requires user initiation.
  * **Optional**: Not mandatory for task completion.
  * **Repeatable**: Can be executed multiple times.
* **Execution Order Constraint**:
  * The `SaveData` action can only be executed **before** mandatory actions.
  * The UI is built by configurators to ensure the correct execution order of actions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2014.58.14.png)

* Add an event handler to the table by assigning the previously created node action.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2015.01.16.png)

> [!NOTE]
>
> Add a custom key that is exactly the source key of the table so the platform knows where to save the edits applied in the table.

**2. Add Another Manual and Mandatory Action**

* An additional **manual** and **mandatory** action should be included.
* This ensures that the **token remains within the user task** where the table is rendered.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2014.58.26.png)

**3. Add Another Action (Optional)**

* You can add another node action if you want to assign an event handler to a table cell element (e.g, a text).
* Assign the event handler to that particular element.
* Make sure it is manual, optional and repeatable (can only be executed before mandatory actions).

## Common patterns

### Populate a table from an integration workflow

When your table data comes from an external API (via an integration workflow), the pattern is:

**1. Run the integration workflow**

Use a **Service Task** with a **Start Integration Workflow** action. The workflow calls your API and returns the response to a process key (e.g., `application.users`).

**2. Send data to the UI**

Add a **Send Data to User Interface** action on the same node (or a subsequent one) to push the data to the frontend:

```json theme={"dark"}
{
  "application": ${application}
}
```

**3. Configure the table source**

Set the Table's **Source Key** to the same key (e.g., `application.users`). Rows are generated automatically from the array.

> [!TIP]
>
> The table source must be an array of objects. If your API returns a nested structure, use a business rule to extract the array before binding it to the table.

***

### Filter table data using form controls

The Table component has [built-in column filters](#filters) for per-column filtering. For **cross-component filtering** (e.g., dropdown selections that filter the entire table), use a business rule triggered by an event handler:

**1. Add form controls (dropdowns, inputs) to your screen**

Configure each dropdown with a process data key (e.g., `filter.status`, `filter.category`).

**2. Create a business rule for filtering**

Add a **manual, optional, repeatable** business rule action on the User Task node:

```javascript theme={"dark"}
var originalData = input.application.users;
var selectedStatus = input.filter.status;

var filtered = originalData.filter(function(item) {
    if (selectedStatus && item.status !== selectedStatus) return false;
    return true;
});

output.displayed = { "users": filtered };
```

**3. Add an event handler on each dropdown**

On each form control, add an event handler with:

* **Event:** `CHANGE`
* **Action Type:** `ACTION`
* **Node Action Name:** your filter business rule

This triggers the filter every time a dropdown value changes.

**4. Point the table to the filtered data**

Set the Table's **Source Key** to the filtered key (e.g., `displayed.users`) instead of the original data.

> [!NOTE]
>
> Keep the original data in a separate key (e.g., `application.users`) so you can reset filters by copying it back to the displayed key.

***

### Reset table to original data

To add a "Reset filters" button, create another business rule that copies the original data back:

```javascript theme={"dark"}
output.displayed = { "users": input.application.users };
output.filter = { "status": null, "category": null };
```

Attach this as an event handler (type `ACTION`) on a reset button.

***

## FAQs

> [accordion] What is the `table item key` used for in Table actions?
>
> The `table item key` is essential for identifying specific rows and cells within a table. When actions are triggered in table cells, this key ensures that the action applies to the correct item, allowing data to be saved accurately in the intended cell or row. Without this key, actions may not track or save data correctly.

> [accordion] How does the Table component differ from Collection?
>
> While the Table component shares structural similarities with Collection, it is tailored specifically for tabular data. Unlike Collection, it supports column customization, row pagination, built-in filtering/sorting, and in-place row editing, streamlining the handling of tabular data.

> [accordion] Can I use conditional styling in Table cells?
>
> Yes. You can use [conditional styling](../conditional-styling) to dynamically update cell or row styles based on conditions, such as highlighting critical items or overdue entries.

> [accordion] Does the Table component support nested tables?
>
> No, nested tables (tables within other tables) are currently unsupported and are not planned for future updates. This limitation keeps the Table component optimized for its intended use without overcomplicating its structure.

> [accordion] What actions can I use within Table cells?
>
> Table cells support various actions:
>
> * **Action**: Executes a predefined action within the cell.
> * **Start Process Inherit**: Triggers workflows based on inherited process configurations.
> * **Upload**: Allows direct file or data uploads within a cell.
>   Each of these actions requires a `table item key` to ensure data accuracy.

> [accordion] How is pagination configured in the Table component?
>
> Pagination can be customized to control the number of entries displayed per page. Alternatively, you can enable scrollable view mode by disabling pagination, which provides a continuous, scrollable data view.

> [accordion] Can I edit data directly within the Table cells?
>
> Yes. Enable the **Editable** toggle on individual columns in cell-level settings. Editing is triggered by double-click or the Edit button. The editor type (text, number, date, toggle, or single-select dropdown) is automatically determined by the column's data model type. Edits are validated and saved row-by-row.

> [accordion] Are there specific data sources required for populating a Table?
>
> Yes, the Table component requires a source in the form of an array of objects. The source allows the Table to dynamically populate cells based on the data structure, ensuring rows and columns align with your data set.

> [accordion] What if I need to add custom actions within the Table?
>
> Custom actions can be configured using the UI Designer. Each action added to a cell will use the `table item key` to perform tasks such as saving edits, initiating workflows, or uploading files directly from the table.

> [accordion] Can I hide specific columns or rows based on conditions?
>
> Yes, the Table component supports JavaScript expressions to control visibility dynamically. By setting up expressions, you can create conditions that hide certain columns or rows when specific criteria are met.


# Tooltip
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip

A UI component that displays additional context on hover or focus, with configurable icon and content.

## Overview

A Tooltip is a thin contextual hint anchored to an icon. Use it to explain a non-obvious field label, surface a regulatory disclaimer next to a control, or expand on an acronym without taking screen space.

The icon is configurable from the theme, the trigger is hover or focus, and the overlay positions itself automatically to stay on screen.

The Tooltip is allowed inside any container component (Card, Container, Collection) as well as inside chat layouts and process screens.

## Properties

| Property | Type | Description |
| - | - | - |
| **Tooltip Text** | String / expression | Tooltip text. Bind to a process data key for dynamic content, or set a static literal. |
| **Visibility** | Expression | JavaScript expression that hides the Tooltip when truthy. |
| **Theme overrides** | Object | Override icon, colours, font, padding, border, max-width, max-rows, or shadow for this instance only. |

## Process data binding

To drive Tooltip content from process data, bind **Tooltip Text** to a process data key:

```javascript theme={"dark"}
${application.help.fieldExplanation}
```

For static content, set **Tooltip Text** to a string literal — for example, `"Your IBAN is shown as it appears on your bank statement."`.

See [Dynamic and computed values](../dynamic-and-computed-values) for the full expression syntax.

## Theme configuration

Defaults from the platform theme:

| Token | Default | Description |
| - | - | - |
| `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` | `8px` each | Inner padding around the tooltip content. |
| `font` | `typography@Caption#regular` | Body typography. |
| `color` | `color@neutrals#500` | Text colour. |
| `backgroundColor` | `color@shades#100` | Tooltip background. |
| `borderColor` | `color@neutrals#200` | Outline colour. |
| `borderWidth` | `1px` | Outline thickness. |
| `borderRadius` | `8px` | Corner radius. |
| `maxWidth` | `360px` | Maximum overlay width before text wraps. |
| `maxRows` | `5` | Maximum text rows before truncation. |
| `iconColor` | `color@neutrals#500` | Trigger icon colour. |
| `shadow` | `shadow@s` | Drop shadow on the overlay. |
| `tooltipIcon` (icon) | `sys_TooltipInfo_16` | Trigger icon. Replace via the theme to use a different glyph. |

To override globally, edit **Theme → Components → Tooltip** in the Designer.

## Related resources

> [card] [UI Designer overview](../ui-designer)
>
> Compose screens in the UI Designer.

> [card] [Conditional styling](../conditional-styling)
>
> Apply dynamic styles to UI components.


# Typography
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/ui-component-types/typography

Typography is an important aspect of design that greatly influences how users perceive and interact with your content. In this section, we'll explore how to effectively utilize two essential UI elements, "Text" and "Link."

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/typography_gen.png)

## Text

The "Text" UI element serves as a tool dedicated solely to presenting text within your user interface. Whether it's paragraphs or descriptions, the "Text" UI element. Through manipulation of embedded CSS properties, you're afforded to edit the visual appearance and formatting of text, aligning it with your design preferences.

### Markdown compatibility

The Text UI element gives you with the flexibility of Markdown formatting. You can enhance your text using various markdown tags, including:

* **Bold**

```markdown theme={"dark"}
**Bold**
```

* *italic*

```markdown theme={"dark"}
*italic*
```

* ***bold italic***

```markdown theme={"dark"}
***bold italic***
```

* strikethrough

```markdown theme={"dark"}
~~strikethrough~~
```

* URL

```markdown theme={"dark"}
[URL](https://url.net)
```

* Inline code

```markdown theme={"dark"}
Press `Enter` to continue
```

* Line break — on web, use a raw `<br>` tag (Markdown blank lines and trailing spaces do **not** produce breaks). Behavior differs on mobile; see the note below.

```html theme={"dark"}
First line.<br>Second line.
```

Let's take the following markdown text example:

```markdown theme={"dark"}
Be among the *first* to receive updates about our **exciting new products** and releases. Subscribe [here](flowx.ai/newsletter) to stay in the loop! Do not ~~miss~~ it!
```

When running the process it will be displayed like this:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/text_markdown.png)

> [!WARNING]
>
> The Text element renders inline-only Markdown. The following Markdown features are **not supported** and will appear as plain text:
>
> * Bullet lists (`- item`) and ordered lists (`1. item`)
> * Headings (`#`, `##`, `###`)
> * Paragraph breaks (a blank line between paragraphs)
> * Code blocks (triple backticks)
> * Blockquotes (`>`)
> * Tables

> [!TIP]
>
> **Need bullet points?** Stack multiple Text elements vertically inside a Container, or use a list-capable component instead of Text.

> [!NOTE]
>
> Line breaks in the Text component are **not officially supported yet**, and the behavior is still being aligned across the Designer and the SDKs. As a current, unofficial workaround:
>
> * **Web:** insert a raw `<br>` tag between lines (shown above).
> * **Mobile:** enter an actual line break in the text editor by pressing **Enter** — do not use a `<br>` tag or a literal `\n`. A literal `\n` is escaped and displayed as text.

### Text styling

The Styling section provides you with granular control over how your text is displayed, ensuring it aligns with your design vision.

#### Spacing:

Adjust the spacing around your text, setting the margin as follows: 16px 0 0 0 0 0 0 16px.

#### Sizing:

Choose "Fit W" to ensure the text fits the width of its container.

#### Typography

Define the font properties:

* **Font family**: Choose the desired font family.
* **Font weight**: Define the thickness of the font.
* **Font size**: Specify the font size in pixels (px).
* **Height**: Set the line height in pixels (px).
* **Color**: Determine the text color.

#### Align

Determine the text alignment.

## Link

Links are essential for navigation and interaction. The "Link" UI element creates clickable text that directs users to other pages or external resources.

### Configuring the Link element

The Link component provides a simple way to create hyperlinks in your application interface.

#### Properties

* **Label**: The visible text for the link that users will click on.
* **URL**: The destination URL for the link. This property supports:
  * Static URLs (e.g., `https://example.com`)
  * Dynamic keys for dynamic URL construction (e.g., `${application.externalUrl}`)
  * Combination of static text and dynamic values (e.g., `https://example.com/${application.userId}/profile`)

> [!NOTE]
>
> The Link component supports dynamic keys in the URL property across all platforms (Web, iOS, and Android). This allows you to dynamically construct URLs using process data stored in the datastore.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)

#### Using dynamic keys in URL

You can reference process data in your link URLs by using the `${key}` syntax:

**Example:**

If you have process data like:

```json theme={"dark"}
{
  "application": {
    "documentId": "12345",
    "userId": "user-abc"
  }
}
```

You can create a link with:

* URL: `https://docs.example.com/view/${application.documentId}`
* Label: View Document

When rendered, this will create a link to `https://docs.example.com/view/12345`.

#### Link behavior

* Links open in a new browser tab by default
* The link text can be styled using the standard typography styling options
* Links maintain accessibility standards with proper hover and focus states

### Link styling

The Link element supports styling customization similar to the Text element:

#### Typography

* **Font family**: Choose the desired font family
* **Font weight**: Define the thickness of the font
* **Font size**: Specify the font size in pixels (px)
* **Color**: Determine the link color (default and hover states)

#### Spacing

Adjust the spacing around your link element using margin properties.


# Validators
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-designer/validators

Apply pre-defined validation rules to form inputs such as text, number, email, and date fields across web, mobile, and desktop apps.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/validators.png)

FlowX.AI provides default validators such as:

## Predefined validators

> [accordion] min validator
>
> This validator checks whether a numeric value is smaller than the specified value. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a required validator.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_min.png)
>
> > [card] [min validator](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/min)
> >
> > Refer to MDN documentation for more details about the min attribute.

> [accordion] max validator
>
> This validator checks whether a numeric value is larger than the specified value. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#predefined-validators) validator.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_max.png)
>
> > [card] [max validator](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/max)
> >
> > Refer to MDN documentation for more details about the max attribute.

> [accordion] minLength
>
> This validator checks whether the input value has a minimum number of characters. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a required validator.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_minlength.png)
>
> > [card] [minLength](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/minlength)
> >
> > Refer to MDN documentation for more details about the minlength attribute.

> [accordion] maxLength
>
> This validator checks whether the input value has a maximum number of characters. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#predefined-validators) validator.
>
> ![maxlength validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_maxlength.png)
>
> > [card] [maxLength](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength)
> >
> > Refer to MDN documentation for more details about the maxlength attribute.

> [accordion] required
>
> This validator checks whether a value exists in the input field.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validatorss.png)
>
> It is recommended to use this validator with other validators like [minlength](#predefined-validators) to check if there is no value at all.
>
> ![required validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validators.png)
>
> > [card] [required](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required)
> >
> > Refer to MDN documentation for more details about the required attribute.

> [accordion] email
>
> This validator checks whether the input value is a valid email. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#predefined-validators) validator.
>
> ![email validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_email.png#center)
>
> > [card] [email](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email)
> >
> > Refer to MDN documentation for more details about email input validation.

> [accordion] pattern validator
>
> This validator checks whether the input value matches the specified pattern (for example, a [regex expression](https://www.regexbuddy.com/regex.html)).
>
> > [!WARNING]
> >
> > **Important:** Pattern validators can only be applied to input fields of type **"text"** or **"string"**. They cannot be used with input fields of type **"number"**. If you need to validate numeric input with specific patterns (such as preventing leading zeros), you must either:
> >
> > * Use a text input field instead of a number input field, or
> > * Create a custom validator that handles the numeric validation logic
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_pattern.png#center)
>
> > [card] [pattern validator](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern)
> >
> > Refer to MDN documentation for more details about the pattern attribute.

> [accordion] custom expression validator
>
> This validator allows you to validate a form element based on computed expressions that can reference other values from the process data store, not just the current form element being validated.
>
> ![custom expression validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_expression.png)
>
> Example used:
>
> ```javascript Simple comparison theme={"dark"}
> return ${user.endDate} > ${user.startDate}
> ```
>
> The validator uses a code editor where you can write computed expressions that must eventually return `true` (valid) or `false` (invalid). The expression can contain process data store values and will be evaluated dynamically.
>
> > [!NOTE]
> >
> > The `customExpression` validator runs only when the field value is not empty or missing, similar to other predefined validators.
>
> **Key features:**
>
> * **Dynamic validation**: Based on other process values, not just the current field
> * **Computed expressions**: Write JavaScript expressions that return boolean values
> * **Real-time updates**: Re-evaluates when referenced process data changes
> * **Universal compatibility**: Available for all form elements
>
> **Expression examples:**
>
> ```javascript Simple comparison theme={"dark"}
> return ${app.endDate} > ${app.startDate}
> ```
>
> ```javascript Complex validation theme={"dark"}
> return ${app.userAge} >= 18 && ${app.hasParentConsent} === true
> ```
>
> ```javascript Numeric validation theme={"dark"}
> return ${app.totalAmount} <= ${app.availableBalance}
> ```
>
> > [!WARNING]
> >
> > **Important considerations:**
> >
> > * The expression **must** return a boolean value (`true` for valid, `false` for invalid)
> > * Use proper syntax when referencing process data store values with `${}`
> > * Ensure referenced process data keys exist to avoid runtime errors
> > * The validator is asynchronous and will be re-evaluated when dependent data changes

Other predefined validators are also available:

> [accordion] isSameOrBeforeToday
>
> This validator can be used to validate [datepicker](./ui-component-types/form-elements/datepicker-form-field) inputs. It checks whether the selected date is today or in the past. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#predefined-validators) validator.
>
> ![isSameOrBeforeToday](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_issameday.png)

> [accordion] isSameOrAfterToday
>
> This validator can be used to validate datepicker inputs. It checks whether the selected date is today or in the future. If there are no characters at all, this validator will not trigger. It is advisable to use this validator with a [required](#predefined-validators) validator.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_issamedayafter.png)

## Validator compatibility with input field types

Different validators work with different input field types. Here's a compatibility matrix:

| Validator | Text Fields | Number Fields | Email Fields | Date Fields |
| - | - | - | - | - |
| required | ✅ | ✅ | ✅ | ✅ |
| min | ❌ | ✅ | ❌ | ❌ |
| max | ❌ | ✅ | ❌ | ❌ |
| minLength | ✅ | ❌ | ✅ | ❌ |
| maxLength | ✅ | ❌ | ✅ | ❌ |
| email | ❌ | ❌ | ✅ | ❌ |
| pattern | ✅ | ❌ | ✅ | ❌ |
| customExpression | ✅ | ✅ | ✅ | ✅ |
| isSameOrBeforeToday | ❌ | ❌ | ❌ | ✅ |
| isSameOrAfterToday | ❌ | ❌ | ❌ | ✅ |

> [!NOTE]
>
> To ensure the validation of all form elements within a card upon executing a Save Data action such as "Submit" or "Continue," follow these steps:
>
> * When adding an event handler to a button inside a card, locate the dropdown menu labeled **Add form to validate**.
> * From the dropdown menu, select the specific form or individual form elements that you wish to validate.
> * By choosing the appropriate form or elements from this dropdown, you can ensure comprehensive validation of your form.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/input_validators.png)

***

## Common expression patterns

The `customExpression` validator supports JavaScript expressions that return `true` (valid) or `false` (invalid). Below are patterns for common validation scenarios.

### Date comparison

Validate that one date comes after another:

```javascript theme={"dark"}
return new Date(${application.endDate}) > new Date(${application.startDate})
```

### Required-if (conditional required)

Make a field required only when another field has a specific value:

```javascript theme={"dark"}
if (${application.hasSpouse} === true) {
  return ${application.spouseName} !== null && ${application.spouseName} !== ""
}
return true
```

### Regex patterns

Validate a string against a pattern using `match()`:

```javascript UK National Insurance Number (NINO) theme={"dark"}
return /^[A-CEGHJ-PR-TW-Z]{1}[A-CEGHJ-NPR-TW-Z]{1}[0-9]{6}[A-D]{1}$/.test(${application.nino})
```

```javascript Phone number (10 digits) theme={"dark"}
return /^\d{10}$/.test(${application.phoneNumber})
```

```javascript Postal code (UK format) theme={"dark"}
return /^[A-Z]{1,2}\d[A-Z\d]?\s?\d[A-Z]{2}$/.test(${application.postalCode})
```

> [!TIP]
>
> For simple pattern matching on text fields, the [pattern validator](#predefined-validators) may be more appropriate. Use `customExpression` when you need to combine patterns with other logic.

### Null and empty checks

Handle optional fields that should be validated only when populated:

```javascript theme={"dark"}
if (${application.alternateEmail} === null || ${application.alternateEmail} === "") {
  return true
}
return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(${application.alternateEmail})
```

### Cross-field validation

Compare multiple field values:

```javascript theme={"dark"}
return ${application.confirmPassword} === ${application.password}
```

> [!NOTE]
>
> **Hidden fields skip validation.** When a form element is hidden via a hide condition, all its validators (including `customExpression`) are disabled. Hidden fields do not block form submission. If you need to validate data regardless of field visibility, use a [business rule action](../actions/business-rule-action/business-rule-action) on the backend.
>
> For full details on how visibility affects validation, see [Event Handlers — Form validation](./event-handlers#form-validation).

***

## Custom validators

Additionally, custom validators can be created within the web application and referenced by name. These custom validators can have various configurations such as execution type, name, parameters, and error message.

1. **Execution type** - synchronous/asynchronous validator
2. **Name** - name provided by the developer to uniquely identify the validator
3. **Params** - if the validator needs inputs to decide if the field is valid or not, you can pass them using this list
4. **Error Message** - the message that will be displayed if the field is not valid

> [!WARNING]
>
> The error that the validator returns **MUST** match the validator name.

![custom validator](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/validator_custom.png#center)

### Custom validator example

Below you can find an example of a custom validator (`currentOrLastYear`) that restricts date selection to the current or the previous year:

#### currentOrLastYear

```typescript theme={"dark"}
currentOrLastYear: function currentOrLastYear(AC: AbstractControl): { [key: string]: any } {
    if (!AC) {
      return null;
    }

    const yearDate = moment(AC.value, YEAR_FORMAT, true);
    const currentDateYear = moment(new Date()).startOf('year');
    const lastYear = moment(new Date()).subtract(1, 'year').startOf('year');

    if (!yearDate.isSame(currentDateYear) && !yearDate.isSame(lastYear)) {
      return { currentOrLastYear: true };
    }

    return null;
```

#### smallerOrEqualsToNumber

Below is another custom validator example that validates form input asynchronously. The validator is called `smallerOrEqualsToNumber` and takes an array of `params` as an input.

> [!NOTE]
>
> For this custom validator the execution type should be marked as `async` using the UI Designer.

```typescript theme={"dark"}
export function smallerOrEqualsToNumber (params$: Observable<any>[]): AsyncValidatorFn {
  return (AC): Promise<ValidationErrors | null> | Observable<ValidationErrors | null> => {
    return new Observable((observer) => {
      combineLatest(params$).subscribe(([maximumLoanAmount]) => {
        const validationError =
          maximumLoanAmount === undefined || !AC.value || Number(AC.value) <= maximumLoanAmount ? null : {smallerOrEqualsToNumber: true};

        observer.next(validationError);
        observer.complete();
      });
    });
  };
}
```

If the input value is undefined or the input value is smaller or equal to the maximum loan amount value, the function returns `null`, indicating that the input is valid. If the input value is greater than the maximum loan amount value, the function returns a validation error object with a key `smallerOrEqualsToNumber` and a value of true, indicating that the input is invalid.

### Troubleshooting async validators

> [accordion] Could not resolve async validator \[name]. Missing process instance UUID.
>
> **Cause:** Async validators resolve their parameters from live process instance data, so they can only run when the component is rendered inside a running process instance. If the screen has no process instance behind it (for example, a preview or a UI rendered outside a running process), the renderer throws this error for every async validator on the form.
>
> **Solution:**
>
> * If the validator does not need live process data, set its **Execution type** to synchronous. This option is not available for a **Custom expression** validator: the Designer always runs it as async, so it needs a running process instance behind the screen.
>
> * If it does, make sure the component is rendered from a user task inside a running process instance.
>
> > [!NOTE]
> >
> > A datepicker whose **min date** or **max date** is a computed value registers as an async validator too, so it is subject to the same requirement even if you never marked anything as async.

> [!NOTE]
>
> For more details about custom validators please check the [SDK documentation](../../../sdks/).

> [!TIP]
>
> Using validators in your application can help ensure that the data entered by users is valid, accurate, and consistent, improving the overall quality of your application.

It can also help prevent errors and bugs that may arise due to invalid data, saving time and effort in debugging and fixing issues.

***

## Academy courses

> [card] [Hide and Disable course](https://academy.flowx.ai/explore/hide-and-disable-ui-elements)
>
> Academy course on building dynamic UI logic with hide and disable conditions, including validation behavior


# UI Flows
Source: https://docs.flowx.ai/5.9/docs/building-blocks/ui-flows

Build reusable, multi-platform user interfaces that work across web, iOS, and Android without the overhead of BPMN processes.

## Overview

UI Flows are a project resource for use cases where full BPMN mapping is unnecessary. Full BPMN mapping for simple UI experiences introduces overhead and complexity. UI Flows also eliminate subprocesses that add layers to the main process for UI purposes only.

> [!TIP]
>
> **Build one:** [Build your first UI Flow](/5.9/docs/getting-started/building-your-first-ui-flow) walks through a two-page loan estimator with a validated form, a Start Workflow action, and page navigation.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows1.png)

UI Flows support web (Angular/React), iOS, and Android. They separate UI definitions from process logic, providing an alternative to BPMN processes when business orchestration is not required.

> [card] Multi-Platform Support
>
> Target web (Angular/React) or mobile at creation; a single mobile UI Flow serves both iOS and Android with platform-specific configurations

> [card] Process Integration
>
> Launch FlowX processes from UI Flows when needed using the Start Process action

> [card] Navigation Management
>
> Manage Navigation Areas, pages, and scrolling within UI Flows Designer

> [card] Task Manager Integration
>
> Embed Task Manager as a UI component to display task lists

> [card] AI Chat Integration
>
> Add Chat components for conversational AI experiences powered by AI agents

### Key characteristics

| Characteristic | Description |
| - | - |
| **Project Resource** | Managed as independent project resources, separate from process definitions |
| **UI Designer** | Configure using UI Designer (navigation areas appear as UI assets instead of BPMN nodes) |
| **Navigation Areas** | Add navigation areas as UI assets to define the user journey |
| **Components** | Supports components, substitution tags, media items, and enumerations |
| **Theme Support** | Themes apply to UI Flows |
| **Data Model** | UI Flows have their own data model for localization and formatting |
| **FLX UI Flow Component** | The `flx-ui-flow` component renders UI Flows and can be embedded in any container app |
| **Custom Components** | Custom components can be added to UI Flows |
| **Experience Type** | UI Flows can be **Flow-Based** (default) or **Chat-Driven** (connected to a chat-driven workflow) |

> [!WARNING]
>
> **Platform selection is permanent**: When creating a UI Flow, you select a platform (web or mobile). This cannot be changed later. Changing the project-level platform setting does not update existing UI Flow resources.

***

## Experience types

UI Flows support two experience types, selected when creating the UI Flow:

> [card] Flow-Based
>
> **Default.** Traditional UI flows with navigation areas, forms, and standard components. Use for structured user journeys.

> [card] Chat-Driven
>
> Optimized for conversational experiences. Connected to a [chat-driven workflow](/5.9/ai-platform/chat-driven-workflows) that powers all Chat components in the UI Flow.

### Chat-Driven UI Flows

When you select **Chat-Driven** as the experience type:

* You must select an **AI Conversational Workflow** to connect to the UI Flow
* All Chat components in the UI Flow use this workflow by default
* The workflow can be changed later in the UI Flow **Settings** page (gear icon in the sidenav)

### UI Flow Settings

Every UI Flow has a **Settings** page, accessible from the gear icon in the UI Flow editor sidenav. The Settings page includes:

| Tab | Description |
| - | - |
| **General** | **Use UI flow in reporting** and the **Expiry time** of UI Flow sessions. Click **Save settings** to apply changes. |
| **Permissions** | **Add Roles**: the roles you select can see and run the UI Flow. Finer control is set per component. |
| **Chat Options** | Select or change the chat-driven workflow for Chat-Driven UI Flows |

> [!NOTE]
>
> The **Chat Options** tab is only enabled for Chat-Driven UI Flows. On Flow-Based UI Flows the tab is disabled.

### Expiry time

UI Flow general settings include an **Expiry time** field that sets how long a UI Flow session stays valid. The field accepts either an **ISO 8601 duration** (for example `PT3M22S` for 3 minutes 22 seconds) or a **cron expression** (for example `0 0 9-17 * * MON-FRI`) for time-based expiry.

***

## When to use UI Flows

### Use UI Flows for

Use UI Flows when you need a user interface without BPMN process orchestration:

> [card] Information Display
>
> Dashboards, reports, and static content that doesn't require process orchestration

> [card] Task Management
>
> Task lists and task management interfaces with embedded Task Manager component

> [card] Navigation Shells
>
> App navigation structures, home pages, and menu systems

> [card] Form Collections
>
> Data entry forms that start processes but don't need their own process context

### Use processes for

Use processes when you need:

> [card] Business Logic
>
> Complex workflows with business rules, approvals, and integrations

> [card] State Management
>
> Applications requiring process state tracking and persistence

> [card] Orchestration
>
> Multi-step operations with decision points and parallel execution

### Combine both approaches

> [!TIP]
>
> Use UI Flows as the main app shell and **Start Process actions** to launch business processes when needed.

**Example:**

* UI Flow provides the home screen, navigation, and dashboard
* User clicks "Apply for Loan" → the Start Process action launches the loan process
* After process completion, user returns to the UI Flow dashboard

For how data moves between a UI Flow, the processes it starts, and the workflows they call, see [Combine UI Flows, processes, and workflows](/5.9/docs/building-blocks/combining-ui-flows-processes-and-workflows).

***

## How navigation works

A UI Flow behaves like a single-page app: one UI Flow session hosts a set of routable views, and moving between them updates the browser URL without leaving the session.

* **Root navigation areas are the routes.** Each root-level navigation area — a **Page**, root **Zone**, or root **Tab Bar** — is a routable view with its own URL. **Modals** are routed too, addressed through a `modalId` query parameter on top of the current view. This page also refers to routable views as *screens* or *root views* — they are the same thing.
* **One session, one data store.** All views in a UI Flow share the same session and its [session variables](#session-variables). Navigating between views never resets the session — data fetched on one view is available on every other view.
* **Navigate To actions define the navigation graph.** The [route map](#route-map-and-breadcrumbs) — shortest paths, breadcrumbs, and back navigation — is computed automatically from the Navigate To actions you configure.
* **URLs are real.** Views support query parameters, [deep linking](#deep-linking), browser back/forward, and refresh recovery through the [navigation stack](#navigation-stack).

Inside a single view, a Page or Zone additionally has a **layout mode**: **Single page** renders all child areas on one screen, while **Wizard** shows them one at a time with Next/Back navigation. Layout mode controls rendering *within* a view; it is separate from routing *between* views.

***

## Key features

> [!NOTE]
>
> **What you can build with UI Flows:**
>
> * Create and render UI Flows for Web, iOS, and Android platforms
> * Navigate between Navigation Areas with the Navigate To action
> * Fetch and display data with the Start Workflow action
> * Start FlowX processes via the Start Process action, or embed one with the Process Renderer component
> * Embed the Task Manager and Chat components
> * Configure the UI Flow data model for localization

### Navigation Areas management

In UI Flows Designer:

* Create pages and navigation flows
* Configure navigation areas (Page, Tabbar, Zone, Modal)
* Set up header and footer zones (web only)
* Define home pages with navigation icons

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows4.png)

### Start Process action

Launch FlowX processes from UI Flows:

* Start processes on button clicks or events
* Pass data from UI Flow to process
* Return to UI Flow after process completion

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_process_ui.png)

### Navigate To action

Configure navigation within UI Flows:

* Navigate to specific Navigation Areas
* Scroll to Container elements
* Create multi-step wizards

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows2.png)

### Task Manager component

Embed Task Manager in UI Flows:

* Display task lists
* Filter and search tasks
* Launch tasks in context

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows3.png)

### Home page support

* Designate any page as the home page
* Automatic home icon in navigation
* Return to home from any screen

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows5.png)

### Global components

Add persistent components that appear across all screens in a UI Flow:

* **Breadcrumbs** (web only) — show navigation path and enable click-to-navigate
* **Chat** (web + mobile) — embed AI-powered conversational interface

### Process Renderer component

Embed a full FlowX process inside a UI Flow screen (web only):

* Start any process from the current app
* Pass data from the UI Flow data store to the process
* Maintain consistent navigation with URL-based process tracking

### Export and import

You can export and import UI Flows to transfer them between projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows6.png)

#### Exporting

1. Open the context menu on the UI Flows list page
2. Select **Export** for the UI Flow you want to export
3. The UI Flow is downloaded as a ZIP file

#### Importing

1. Open the context menu on the UI Flows list page and select **Import**
2. Select the ZIP file exported from another project or environment
3. If UI Flows with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
4. Choose a strategy for each conflicting UI Flow (or use **Apply to all**):
   * **Keep both** - imports the UI Flow as a new copy alongside the existing one
   * **Replace** - overwrites the existing UI Flow with the imported version
   * **Skip this one** - keeps the existing UI Flow unchanged
5. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

***

## Creating a UI Flow

**1. Create UI Flow resource**

In FlowX Designer, navigate to your project and create a new UI Flow as a project resource.

* Navigate to **UI Flows** tab
* Click **+ Add** button
* Enter a name and description
* Select platform (Web or Mobile)
* Select experience type: **Flow-Based** (default) or **Chat-Driven**
* If Chat-Driven, select the **AI Conversational Workflow** to connect

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows7.png)

**2. Design navigation structure**

Open UI Flows Designer and manage Navigation Areas:

* Add Navigation Areas (pages)
* Configure navigation type (Single Page or Wizard)
* Setup zones (header, content, footer) for web
* Define navigation flow between areas

**3. Add UI components**

Build your interface using the component library:

* Drag and drop UI components
* Configure component properties
* Add Task Manager component if needed
* Setup data bindings

**4. Configure event handlers**

Setup interactivity and navigation:

* **Start Process**: Launch processes when needed
* **Navigate To**: Move between Nav areas or scroll to containers
* **External**: Open a link in a new tab

**5. Set home page (optional)**

Designate a page as the home page:

* Select the Navigation Area
* Mark as "Home Page"
* Configure home icon appearance

**6. Test and validate**

Test your UI Flow:

* Preview across platforms
* Test navigation flow
* Verify Start Process actions work
* Check Task Manager integration

***

## Configuring the Start Process action

The Start Process action allows you to launch FlowX processes from UI Flows. Although UI Flows do not require a process and user tasks, they support actions for process initiation.

![Start Process action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_ui_process_action.png)

### How it works

When a process is started from a UI Flow:

1. The `FlxProcessRenderer` component is **dynamically added**, replacing the UI Flow content
2. The process renderer inherits configuration from the UI Flow and shares common stores:
   * API URL and static assets path
   * Workspace and project IDs
   * Language and locale settings
   * Build information
   * Theme and fonts
   * Substitution tags and media items

> [!NOTE]
>
> When configuring the `FlxUIFlow` component in your container app, ensure the `processApiPath` parameter is set to enable process starting capabilities.

### Configuration steps

**1. Add button or trigger**

Add a UI component that will trigger the process (typically a Button).

**2. Add an event handler**

Configure the handler:

* In the **Event Handlers** section, add a handler
* Select **Start Process** as the action type
* Choose the process definition to start from the dropdown

**3. Configure forms and data**

The Start Process action allows you to configure:

* **Process selection**: Select the process to start
* **Add forms to validate**: Choose which forms must pass validation before the process starts. To send field values to the process, reference them in the custom body
* **Custom body**: Define which data to send as start parameters

```json theme={"dark"}
{
  "customerId": "${uiData.customer.id}",
  "applicationAmount": "${uiData.amount}"
}
```

**4. Configure behavior**

Set what happens after process starts:

* Navigate to process UI
* Stay in UI Flow
* Show confirmation message

**5. Optional: Add analytics**

Configure analytics tracking:

* **Analytics name**: Set a name for tracking
* **Custom payload**: Add additional data for analytics

***

## Configuring the Start Workflow action

![Start Workflow action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/start_ui_wf_action.png)

The Start Workflow action allows you to execute integration workflows directly from UI Flows. Unlike Start Process, which creates a full process instance with state management, Start Workflow executes lighter-weight integration workflows that return results immediately.

![UI Flow Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ui_flow_designer.png)

### When to use Start Workflow vs Start Process

| Use Case | Action Type | Description |
| - | - | - |
| **Data fetching** | Start Workflow | Retrieve data from APIs or databases |
| **Simple operations** | Start Workflow | Execute stateless operations (calculations, validations) |
| **Integrations** | Start Workflow | Call external services and return results |
| **Business processes** | Start Process | Multi-step processes requiring state management |
| **User journeys** | Start Process | Processes with multiple user interactions |

### How it works

When a workflow is started from a UI Flow:

1. The workflow is executed via the Runtime Manager API
2. Input parameters are mapped from UI Flow data
3. The API returns a `workflowInstanceUuid` for tracking
4. UI Flow subscribes to SSE events for workflow completion
5. Results are mapped back to UI Flow data for display

### API endpoint

```
POST /rtm/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start-workflow
```

| Parameter | Type | Description |
| - | - | - |
| `workspaceId` | Path | Workspace identifier |
| `appId` | Path | Application identifier |
| `resourceDefinitionId` | Path | Resource definition ID for the workflow |
| Request body | JSON | Workflow input parameters |

**Response:**

```json theme={"dark"}
{
  "workflowInstanceUuid": "uuid-string",
  "status": "started|pending|failed"
}
```

### SSE events

The UI Flow subscribes to Server-Sent Events (SSE) to receive workflow completion notifications.

**Event type:** `UI_FLOW_WORKFLOW_RESPONSE`

```json theme={"dark"}
{
  "eventType": "UI_FLOW_WORKFLOW_RESPONSE",
  "workflowInstanceUuid": "uuid-string",
  "status": "completed|failed|timeout",
  "data": {},
  "timestamp": "ISO-8601"
}
```

### Configuration steps

**1. Add a UI component**

Add a component that will trigger the workflow — typically a **Button**, or use an **On Load** event on a Page to fetch data automatically when the screen opens.

**2. Add an event handler**

Configure the handler:

* In the **Event Handlers** section, add a handler
* Select **Start Workflow** as the action type
* Choose the integration workflow to execute from the **Workflow** dropdown

**3. Configure start parameters (optional)**

If the workflow needs input data, check **Add start params** and provide a JSON body. Use `${}` expressions to pass current session data:

```json theme={"dark"}
{
  "customerId": "${customerId}",
  "requestType": "balance_inquiry"
}
```

**4. Configure UX options**

| Option | Description |
| - | - |
| **Show loader** | Display a loading indicator while the workflow executes |
| **Dismiss on completion** | Automatically close the modal when the workflow finishes (modals only) |

> [!NOTE]
>
> **Dismiss on completion** is a user-initiated dismiss: the user clicks the button with Start Workflow, the workflow runs, and the modal closes when the workflow finishes. The close is downstream of the user's action, so this pattern is compliant with the [modal lifecycle rule](./process/design-principles#modals-are-dismissed-only-by-user-interaction).

### How workflow output reaches your components

Unlike processes, there is no `responseKey` configuration for Start Workflow actions. When a workflow completes, its output is **automatically merged** into the UI Flow's session variables. Any component on any page in the same session can reference the returned data immediately.

**1. Workflow returns output**

The workflow's **End** node determines what data is returned. The output parameters configured on the workflow definition control the shape of the response.

> [!WARNING]
>
> The workflow must return a **named object**, not a raw array. For example, return `{"submissions": [...]}` instead of `[...]`. The auto-merge expects an object with keys — returning a bare array will cause an error.

**2. Output auto-merges into session variables**

When the workflow completes, its output is delivered via a real-time SSE event and deep-merged into the session's data store. Existing session variables are preserved — new keys are added and matching keys are updated.

> [!NOTE]
>
> Arrays in the output **replace** existing arrays with the same key (they are not appended). If you need to combine results from multiple workflow calls, handle the merge in the workflow itself.

**3. Components reactively update**

Any component bound to the returned keys updates automatically. For example, if the workflow returns `{"foundSubmissions": [...]}`, a table with its source bound to `${foundSubmissions}` displays the data as soon as the workflow completes.

> [!TIP]
>
> Use the **Variables** tab in the UI Flow session console to inspect what data is currently available. This is the fastest way to verify whether the workflow output arrived and what keys it contains.

### Example: Fetch and display a list

1. Create a workflow called `getSubmissions` that queries a database and returns output as a named object:
   ```json theme={"dark"}
   {
     "foundSubmissions": [
       { "_id": "69c66a...", "submissionDetails": { "lineOfBusiness": "Property", ... } },
       { "_id": "69cb7c...", "submissionDetails": { "lineOfBusiness": "Casualty", ... } }
     ]
   }
   ```
2. On your Page, add a **Table** component and bind its data source to `${foundSubmissions}`.
3. Add a **Start Workflow** action (triggered **On Load** or via a Button click) pointing to `getSubmissions`.
4. When the page loads (or the button is clicked), the workflow runs and the table populates automatically.

> [!NOTE]
>
> Start Workflow supports organization-aware execution with organization ID propagation from the workflow instance for proper multi-tenant isolation.

### Page parameters vs session variables

These are two separate concepts:

| Concept | Purpose | How data gets there |
| - | - | - |
| **Page parameters** | Define URL query parameters for deep linking and navigation between pages | Configured via the **Parameters** gear icon on a Page or Modal |
| **Session variables** | Store workflow output, file upload responses, and start params — shared across all pages in the session | Populated **automatically** when workflows complete or files are uploaded |

Page parameters appear in the browser URL (e.g., `?userId=123`) and are passed via **Navigate To** actions. Session variables live in the session's data store and are the primary mechanism for getting workflow output into UI components.

> [!NOTE]
>
> In processes, a `responseKey` wraps the action output under a specific key in the process data model. UI Flows do not use `responseKey` — the workflow output object is merged directly into session variables. Make sure your workflow End node returns data with descriptive top-level keys (e.g., `foundSubmissions`, `accountDetails`) to avoid collisions with other session data.

***

## Configuring the Navigate To action

The Navigate To action handles navigation within UI Flows and scrolling to specific elements.

### Navigation behavior: Route vs Scroll

The Navigate To action either **routes** (changes the URL/view) or **scrolls** (anchor navigation) depending on the destination and the area's [layout mode](#how-navigation-works) (single page vs wizard):

| Scenario | Behavior | Example |
| - | - | - |
| Destination inside same Navigation Area (single page) | **Scroll** | Button in Card X scrolls to Card Y within the same Page |
| Destination inside same Navigation Area (wizard navigation) | **Route** | Button navigates to next step in a wizard Page |
| Destination outside Navigation Area, different root | **Route** | Button in Page 1 navigates to Page 2 |
| Destination outside Navigation Area, same root (wizard) | **Route** | Button in Zone 1 routes to Zone 2 within a wizard Page |
| Destination outside Navigation Area, same root (single page) | **Scroll** | Button in Zone 1 scrolls to Zone 2 within a single-page layout |
| Destination is a Modal | **Route** | Button opens Modal as a routed view |

> [accordion] Detailed navigation examples
>
> **Example layout:**
>
> ```
> Page 1 - Single page form
> ├── Zone - Header
> │   └── Card 1 (Button 2)
> ├── Zone - Content
> │   ├── Card 2 (Button 1)
> │   ├── Modal
> │   │   └── Card 8
> │   ├── Card 9 (Button 3)
> │   └── Card 10 (Button 4)
> └── Zone - Footer
>     └── Card 3
>
> Page 2 - Wizard navigation
> ├── Card 4
> ├── Card 5
> └── Card 6
> ```
>
> **Action outcomes:**
>
> | Action | Destination | Result |
> | - | - | - |
> | Button 1 | Modal/Card 8 | **Route** to modal |
> | Button 2 | Card 10 | **Scroll** to Card 10 |
> | Button 3 | Card 4 (Page 2) | **Route** to Page 2, Card 4 |

> [!NOTE]
>
> Under the hood, every Navigate To updates the URL and pushes a browser history entry, then scrolls the destination element into view. **Route** vs **Scroll** in the table describes the visible outcome: whether the rendered view changes, or the current view scrolls to an anchor.

### Configuring the action

**1. Add navigation trigger**

Add a Button or menu item that triggers navigation.

**2. Select the destination**

* Add an event handler → **Navigate To**
* Pick the destination from the **Destination** dropdown

Available destinations include all Navigation Areas in the hierarchy plus their first-level children (Card, Container, Custom). Selecting a child element scrolls to it when it is on the currently visible view, or navigates to its view and then scrolls to it.

**3. Optional: Pass parameters**

If the destination root view defines [route parameters](#configuring-route-parameters), use the **Destination Parameters Mapping** field to pass values.

> [!NOTE]
>
> Scrolling is automatic — there is no separate scroll configuration on the action. The renderer smooth-scrolls the destination element into view after navigating.

***

## Embedding Task Manager

Add Task Manager as a UI component in UI Flows to display task lists without requiring a process.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ui_flows_tm.png)

**1. Add Task Manager component**

In UI Flows Designer, add the Task Manager component to a Container or Card.

**2. Select a view**

Configure which view to display in the Task Manager:

* Select the view you want from your available views list
* Each view can have different columns, filters, and sorting options

***

## Embedding Chat component

The Chat component enables interactive conversations with AI agents directly within UI Flows. It provides a conversational interface for AI-powered workflows, supporting real-time message exchange, session persistence, and memory capabilities.

> [card] AI Agent Conversations
>
> Connect to chat-driven workflows powered by AI agents

> [card] Session Persistence
>
> Automatic session handling across page refreshes

**1. Add Chat component**

In UI Flows Designer, select **Chat** from the UI Assets panel and drag it onto the canvas.

**2. Configure the agent workflow**

In the Settings tab, specify the **Agent ID / Workflow Name** for the chat-driven workflow.

> [!WARNING]
>
> Only **chat-driven workflows** can be integrated with the Chat component. Task-oriented workflows cannot be used.

**3. Customize appearance**

Use the Styles tab to configure header, messages, and input styling. Theme Admin provides comprehensive theming options.

> [card] [Chat Component Documentation](/5.9/ai-platform/chat-component)
>
> View the complete Chat component documentation for detailed configuration, memory capabilities, SDK integration, and best practices.

***

## Process Renderer component

The Process Renderer component allows you to embed a full FlowX process directly inside a UI Flow screen. This enables hybrid apps that combine UI Flow navigation with traditional process-based screens. Available on **web only**.

### Configuration

**1. Add the component**

In the UI Flows Designer, drag **Process Renderer** from the **Complex Components** category in the UI Assets panel onto a **Page** or **Modal**.

> [!WARNING]
>
> A container can have either a Process Renderer or other children, but not both. If the target container already has child components, the Process Renderer cannot be added.

**2. Select a process**

In the **Settings** panel under **Properties**, use the **Process** dropdown to select the process to embed. The dropdown lists all processes in the current app.

**3. Configure start parameters (optional)**

Use the **Start Params** field to pass data from the UI Flow to the process. Enter a JSON object, optionally using `${keyName}` expressions to reference values from the UI Flow data store.

```json theme={"dark"}
{ "name": ${app.name}, "loanAmount": ${app.loanAmount} }
```

### Properties

| Property | Type | Required | Description |
| - | - | - | - |
| **Process** | Dropdown | Yes | The process to embed (selected by resource definition ID) |
| **Start Params** | JSON / expression | No | Data passed to the process on start. Supports `${keyName}` expressions resolved from the UI Flow data store |

### Style

| Property | Options | Default |
| - | - | - |
| **Width** | Fill, Fixed | `Fill` |
| **Height** | Auto, Fixed | `Auto` |
| **Margins** | Top, Right, Bottom, Left | — |

### Placement rules

* Can only be placed as a direct child of a **Page** or **Modal**
* A container with a Process Renderer cannot have other child components (mutual exclusivity)
* **Web only** — not available on iOS or Android

### Navigation behavior

When a process is started inside the Process Renderer, a `processUuid` parameter is added to the URL and mapped to the current view.

| Navigation method | Behavior |
| - | - |
| **Browser back / Breadcrumb click** | Restores the previously started process instance from the view map |
| **Navigate To action** | Restarts the process and resets the view entry |
| **Modal context** | Skips URL parameter matching (process runs independently) |

### Process end handling

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When the process embedded in a Process Renderer reaches its end, the renderer fires a process-end event. You can configure an action to run at that point instead of leaving the ended process on screen.

The configurable process-end actions are:&#x20;

* Navigate to a screen in the current UI Flow.
* Open an external link.
* Dismiss the modal, when the Process Renderer is hosted in a modal.

> [!WARNING]
>
> Process-end actions use a trigger that does not exist on the current LTS. When a UI Flow is exported and imported into an earlier release, any configured process-end actions are removed during the down-adapt so the earlier renderer can load the flow.

***

## Global components

Global components persist across all screens in a UI Flow. They are rendered outside the normal navigation tree and remain visible as users navigate between screens.

### Adding global components

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

In the UI Flows Designer, the left panel has two tabs. The **UI Assets** tab holds the component palette, and the **Navigator** tab shows the structure of the flow, split into two resizable sections:

* **Navigation** (top) — the screens and global components of the flow, with a home icon marking the starting screen
* **`<Screen>` Components** (bottom) — the component tree of whichever screen or global component is selected above

To add a global component, select **+** in the **Navigation** section header. The menu offers **Header**, **Breadcrumbs**, **Chat** and **Footer** alongside the screen types (**Page**, **Zone**, **Tab Bar**). Only one instance of each global type is allowed per UI Flow.

![The Navigator tab with the Add Component menu open in the Navigation section, listing Header, Breadcrumbs, Chat, Page, Zone, Tab Bar and Footer, above the Page01 Components tree](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ui_flow_navigator_add_component.png)

The **Navigation** section header carries two more controls:

| Control | What it does |
| - | - |
| **Sitemap view** | Shows where the Pages in this UI Flow navigate to, so you can read the flow's routing rather than just its list of screens. |
| **View toggle** | Switches the section between **list view** and **dropdown view**. Dropdown view collapses the screens into a single selector, which reads **Select a root or global component**. |

When a new screen (Page, root Zone, or root Tab Bar) is added to the UI Flow, all existing global components are automatically **assigned** to it. To control which screens a global component appears on, right-click it in the **Navigation** section and use **Apply To** to check or uncheck specific screens. Unassigned components appear grayed out in the navigator for that screen and are not rendered at runtime.

> [!NOTE]
>
> **Apply To only appears on global components.** Right-clicking an ordinary component offers copy, paste, style and delete actions instead, with no **Apply To** entry.

***

### Breadcrumbs

Breadcrumbs display the user's current navigation path within a UI Flow and provide click-to-navigate functionality. They are automatically generated from the navigation hierarchy.

| Feature | Description |
| - | - |
| **Auto-generated** | Built from the navigation stack as users move between screens |
| **Click to navigate** | Click any breadcrumb item to navigate directly to that screen |
| **Dynamic updates** | Update automatically as users navigate deeper into the UI Flow |
| **Back navigation** | Support browser back button and breadcrumb click navigation |
| **Deep link support** | Breadcrumbs are correctly generated when accessing a screen via deep link |

#### Configuration properties

| Property | Description | Default |
| - | - | - |
| **Collapse Mode** | Controls how breadcrumbs collapse when the path is long. `NONE` shows all items; `MIDDLE` collapses intermediate items into an ellipsis | `NONE` |
| **Max Visible Items** | Maximum number of breadcrumb items to display when collapse mode is `MIDDLE` (minimum 2) | `4` |
| **Show Home Icon** | Display a home icon as the first breadcrumb item | `true` |

#### Setting breadcrumb titles

Breadcrumb labels are populated from the **Title** property on root navigation areas. To configure:

1. Select a **Page**, root **Zone**, or root **Tab Bar** in the navigator
2. Open **Settings** → **Properties**
3. Set the **Title** field

Titles support dynamic values:

* **Substitution tags** — use `@@tag_name` syntax
* **Data store values** — use `${keyName}` syntax to reference values from the UI Flow data store

#### Navigation behavior

Breadcrumbs maintain a route hierarchy that avoids circular paths. For example, if a user navigates A → B → A, the breadcrumb trail resets to just A rather than showing a loop.

#### Theming

Breadcrumbs support theming through the Theme Admin with two theme elements:

* **Breadcrumbs** (container) — padding, gap
* **Breadcrumb Item** — border radius, padding, gap, with state modifiers for default, active, hover, and active hover (text style, text color, background color, border color, icon color)

Two system icons are used:

* `sys_BreadcrumbsHome` — the home icon
* `sys_BreadcrumbsSeparator` — the separator between items

![Breadcrumbs theming](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/breadcrumbs_theming.png)

#### Accessibility

| Element | HTML Tag | Attributes |
| - | - | - |
| Breadcrumb container | `nav` | `aria-label` (localized via `@@sys_a11y_breadcrumb` substitution tag) |
| Breadcrumb list | `ol` | — |
| Breadcrumb item | `li` | `aria-current="page"` on the active (last) item |
| Separator | `img` | `aria-hidden` |

***

### Chat as a global component

The Chat component can be added as a global component with three display modes:

* **Fill** — renders inline within a container
* **Floating** — renders as a floating action button (FAB)
* **Fullscreen** — renders as a fullscreen overlay

Floating and Fullscreen modes can be combined so the FAB expands to fullscreen on click.

To change the display mode, right-click the Chat component in the Global Components section and select **Edit Display Types**. Use **Apply To** to assign or unassign the Chat component from specific screens.

> [card] [Chat Component Documentation](/5.9/ai-platform/chat-component)
>
> View the complete Chat component documentation for detailed configuration and best practices.

## Route management

Route management gives you control over URL structure, query parameters, and navigation paths within UI Flows. Define parameters on root views, pass data between screens via query strings, and let breadcrumbs auto-generate from the navigation graph.

> [!NOTE]
>
> URL-based route management (query parameters, `modalId`, deep linking, the session-storage navigation stack) applies to the **web** renderer. Mobile renderers manage navigation natively with their own navigation stack.

### Route types

| Route Type | Description |
| - | - |
| **UI Flow Route** | The base route defined by the UI Flow where the FLX UI Flow component is added |
| **Process Instance Route** | When a process is started, an additional route segment is added based on the process instance UID |
| **Deep Link Route** | Direct URL access to specific screens using route parameters and query strings |

### Configuring route parameters

Root views (Pages, Modals) can define query parameters that control what data is available when that view loads.

**1. Select a root view**

In the UI Flows Designer, select a **Page** or **Modal** in the navigation tree.

**2. Open the parameters config**

In the config panel, click the **Parameters** gear icon to open the parameters modal.

**3. Add parameters**

Define parameters with the following properties:

| Property | Description |
| - | - |
| **Name** | The query parameter key (must be unique within the view) |
| **Default Value** | Value used if the parameter is not provided at navigation time |
| **Required** | Whether the parameter must be passed when navigating to this view |

The modal shows a URL path preview so you can see how the parameters will appear in the browser URL.

![Edit Parameters modal showing route parameters with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)

### Passing parameters with Navigate To

When configuring a **Navigate To** action that targets a root view with parameters, a **Destination Parameters** field appears. Enter a JSON mapping that resolves parameter values from the UI Flow data store:

```json theme={"dark"}
{
  "userId": "${user.id}",
  "status": "${userData.status}"
}
```

When the destination view changes, the Designer auto-populates required parameters as a template so you know which values to provide.

### Route map and breadcrumbs

The route map is a navigation graph computed automatically from all **Navigate To** actions in the UI Flow. It determines:

* **Shortest paths** from the root view to any other view
* **Breadcrumb labels** generated from view titles
* **Back navigation** — clicking a breadcrumb navigates to that view with the correct query parameters preserved

When navigating, the system:

1. Evaluates the parameter mapping JSON against the UI Flow data store
2. Adds destination parameters to the URL
3. Removes parameters that belong only to the source view
4. Preserves parameters shared between source and destination

### Modal navigation

Modals integrate with route management through a `modalId` query parameter:

* Opening a modal adds `modalId={flowxUuid}` to the URL
* Closing a modal removes the `modalId` parameter
* On page reload, the `modalId` in the URL automatically re-opens the correct modal
* Modals on the same root open locally without triggering root navigation

### Navigation stack

UI Flows maintain a navigation stack that tracks the user's path through screens. The stack is persisted in the browser's **session storage**, enabling:

* **Browser back button support** — Users can navigate back through their history
* **Refresh recovery** — The stack survives page refreshes; it is cleared when the browser tab is closed
* **Programmatic navigation** — Use the `NAVIGATE_TO` action type to navigate to specific screens
* **Circular path prevention** — Navigating A → B → A resets the breadcrumb trail to just A

> [!NOTE]
>
> The stack is stored under a single session-storage key per browser tab. If two container apps hosting different UI Flows run on the same origin in the same tab, they overwrite each other's navigation history.

### Deep linking

Deep linking allows direct URL access to specific UI Flow screens. URLs are updated as users navigate, enabling:

* Sharing links to specific screens
* Bookmarking specific states
* Browser history navigation with meaningful URLs

### On Load event integration

When a Navigate To action targets a screen, the destination screen's [On Load event](./ui-designer/event-handlers#triggers) re-fires automatically. This ensures data initialization workflows run each time a user navigates to that screen, even if the screen was previously loaded in the session. Back/forward and breadcrumb navigation do **not** re-fire On Load — only an explicit Navigate To resets it.

The same behavior applies to [intent-based navigation](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node) triggered by AI chat agents — the destination screen's On Load event re-fires to initialize data for the new navigation context.

***

## Start parameters

Start parameters allow you to pass initial data when launching a UI Flow. Configure them in the Designer and provide values at runtime via the API request body or query strings in SaaS container apps.

### How start parameters work

Start parameters are an arbitrary JSON object passed when starting a UI Flow session. They are:

* Persisted on the `ui_flow_session` record in the database
* Returned in both start and status API responses
* Available to renderers throughout the session lifecycle

### Passing start parameters

> [tab] Designer (testing)
>
> When running a UI Flow from the Designer, a **Start params JSON** code editor appears in the Run dialog. Enter valid JSON to pass as start parameters:
>
> ```json theme={"dark"}
> {
>   "clientId": "123",
>   "tier": "premium"
> }
> ```
>
> The Run button is disabled until the JSON is valid. Default value is `{}`.
>
> ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)

> [tab] SaaS container app
>
> In a SaaS container app, start parameters are extracted from URL query strings. Reserved parameters (`projectId`, `workspaceId`, `processUuid`, `uiFlowSessionUuid`, `chatSessionId`, `language`, `locale`) are used for configuration; all other query parameters are passed as start parameters.
>
> The `language` and `locale` query parameters are preserved across SDK navigation and page refreshes, so you don't need to manage them manually via session storage.
>
> For example, this URL:
>
> ```
> https://app.example.com/?projectId=xyz&clientId=123&tier=premium
> ```
>
> passes `{"clientId": "123", "tier": "premium"}` as start parameters.
>
> Configuration parameters are automatically scrubbed from the browser URL after initialization.

> [tab] API
>
> Pass start parameters in the request body when calling the start UI Flow endpoint:
>
> ```
> POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flows/{uiFlowName}
> ```
>
> ```json theme={"dark"}
> {
>   "clientId": "123",
>   "tier": "premium"
> }
> ```
>
> The `startParams` field is optional and defaults to an empty object.

***

## Session variables

Session variables persist data across all pages that share the same UI Flow session ID. They allow you to pass data between workflows, file uploads, and UI components within a single session without relying on process state.

### Variable sources

Variables are automatically collected from the following sources and merged into the session:

| Source | Description | Merge behavior |
| - | - | - |
| **Start parameters** | JSON provided when starting the UI Flow session | Initial values, set once |
| **Workflow output** | Output from Start Workflow actions — must be a named object (e.g., `{"items": [...]}`, not a bare array) | Deep-merged with existing variables |
| **File upload response** | Document Plugin response from Upload actions | Stored under the **Response Key** configured on the Upload action |

> [!NOTE]
>
> Process output (from Process Renderer components) is handled separately and is not part of session variables.

### Using variables in components

Reference session variables in component configurations using `${}` syntax:

```text theme={"dark"}
${clientId}
${uploadedDocument.fileId}
${workflowResult.status}
```

### Variables tab

The UI Flow session console in the Designer includes a **Variables** tab that displays all current session variables. This is useful for debugging and verifying that data flows correctly between workflows, file uploads, and UI components.

![Variables tab in the UI Flow session console showing session variables](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)

The session console tabs are:

| Tab | Description |
| - | - |
| **Variables** | Current session variable values (read-only) |
| **Processes** | Process instances launched from the session |
| **Workflows** | Workflow instances launched from the session |
| **Audit Log** | Session activity log |

> [!NOTE]
>
> Session variables are **read-only** in the console — you cannot edit them directly. Variables are updated automatically when workflows complete or files are uploaded.

***

## Platform considerations

> [tab] Web
>
> **Full Feature Support:**
>
> * All UI component types available
> * Navigation Areas with zones (header, content, footer)
> * Full wizard and single-page navigation
> * Task Manager component integration
>
> **Excluded Navigation Areas:**
>
> * Stepper & Step
>
> **Available Root Navigation Areas:**
>
> * Page
> * Tabbar
> * Zone
>
> **Component Hierarchy:**
>
> ```
> Page (multiple allowed)
> ├── Card
> ├── Container
> ├── Custom
> ├── Modal
> ├── Zone
> └── Tabbar
>
> Tabbar
> └── Tab (multiple allowed)
>     ├── Card
>     ├── Container
>     ├── Custom
>     ├── Modal
>     ├── Zone
>     └── Tabbar
>
> Modal (multiple allowed)
> ├── Card
> ├── Container
> └── Custom
> ```

> [tab] Mobile
>
> **Mobile-Optimized (iOS & Android):**
>
> * Preview selection via dropdown (iOS/Android)
> * Basic Navigation Areas (Page, Tab Bar), no header/footer zones
> * Platform-specific property overrides (copy to/from iOS/Android)
>
> **Excluded Navigation Areas:**
>
> * Zone
> * Stepper & Step
>
> **Excluded Components:**
>
> * Task management
> * Table
>
> **Available Root Navigation Areas:**
>
> * Page
> * Tabbar (only as first root - not enforced in UI Designer)
>
> **Component Hierarchy:**
>
> ```
> Page (multiple allowed)
> ├── Card
> ├── Container
> ├── Custom
> └── Modal
>
> Tabbar
> └── Tab (multiple allowed)
>     ├── Card
>     ├── Container
>     ├── Custom
>     └── Modal
>
> Modal (multiple allowed)
> ├── Card
> ├── Container
> └── Custom
> ```

> [!TIP]
>
> Use the platform selection subheader in UI Designer to switch between platforms and configure platform-specific behaviors.

***

## Rendering in a container app

A UI Flow runs inside your own application through the FlowX renderer SDKs. Each platform has a dedicated entry point:

> [card] [Angular](/5.9/sdks/angular-renderer#ui-flow-renderer)
>
> Embed the `flx-ui-flow` component

> [card] [React](/5.9/sdks/react-renderer#ui-flow-renderer)
>
> Embed the `FlxUiFlowRenderer` component

> [card] [iOS](/5.9/sdks/ios-renderer#how-to-start-a-ui-flow)
>
> Call `startUIFlow`

> [card] [Android](/5.9/sdks/android-renderer#start-an-ui-flow)
>
> Call `startUiFlow`

You need the UI Flow name, the project ID, and, when the UI Flow starts or embeds processes, the process API path. Each SDK section lists the exact inputs for its platform.

> [!WARNING]
>
> Async validators do not work on processless UI Flow screens. Validators that resolve their parameters from process data — a **Custom expression** validator, or any validator whose value is computed instead of static, including computed datepicker min/max dates — require a running process instance behind the screen, and on a plain UI Flow page they throw `Could not resolve async validator [name]. Missing process instance UUID.` Keep such validators on screens rendered by a process (for example, through the Process Renderer component), or use static validator values. See [Troubleshooting async validators](./ui-designer/validators#troubleshooting-async-validators).

***

## Best practices

### Architecture

> [card] Use UI Flows for UI Logic
>
> Keep navigation, layout, and presentation in UI Flows

> [card] Use Processes for Business Logic
>
> Delegate complex business operations to processes via Start Process action

> [card] Minimize Data in UI Flows
>
> Session variables last only for the session lifetime — pass data that must be durably persisted to processes

> [card] Reuse Across Projects
>
> Design UI Flows for reuse across multiple apps

### Design

**DO:**

✅ Create clear navigation hierarchies\
✅ Use descriptive names for Navigation Areas\
✅ Test on all target platforms before deployment\
✅ [Configure accessibility properties](../platform-deep-dive/accessibility) for mobile
✅ Use Task Manager component for task-centric applications

**DON'T:**

❌ Duplicate business logic in UI Flows and Processes\
❌ Create overly complex navigation structures\
❌ Ignore platform-specific limitations\
❌ Skip [accessibility configuration](../platform-deep-dive/accessibility) for mobile apps
❌ Use UI Flows when you need process state management

***

## Migration from subprocess-based navigation

If you currently use subprocesses for UI-only scenarios, consider migrating to UI Flows:

**1. Identify UI-only subprocesses**

Review your subprocesses and identify those that:

* Only display UI without business logic
* Act as navigation shells
* Could be replaced with simpler UI

**2. Create equivalent UI Flow**

Build a UI Flow that replicates the UI functionality:

* Create Navigation Areas matching subprocess pages
* Add UI components
* Setup navigation using Navigate To actions

**3. Migrate process launches**

Replace subprocess starts with Start Process actions:

* Keep actual business processes as processes
* Launch them from UI Flows when needed

**4. Test thoroughly**

Verify functionality across platforms:

* Navigation works correctly
* Process launches function properly
* Data flows as expected

**5. Deprecate old subprocesses**

Once validated, remove the unnecessary subprocess layers.

***

## UI Flow permissions

UI Flow permissions sit on top of the [runtime authorization model](../../setup-guides/access-management/roles-permissions-matrix). Each UI Flow has a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API.

### Default role on creation

When a UI Flow is created, a default runtime role is assigned automatically so the UI Flow is reachable from day one. The default is the project-level **User** role; change it from the UI Flow Permissions page.

### Configuring permissions

Open **Settings → Permissions** in the UI Flow editor. The Permissions page lets you:

* Select one or more runtime roles allowed to start the UI Flow
* Remove the default role and replace it with a project-version-scoped role
* View the resulting permission set for each role

Role changes are saved as part of the UI Flow resource and travel with project export/import.

### Runtime enforcement

When a user starts a UI Flow:

1. The runtime checks the user's roles against the UI Flow's allowed roles list.
2. If the user has none of the allowed roles, the request is rejected and a permission toast is shown in the Designer-hosted runtime preview. In the deployed app, the UI Flow is not listed and the start endpoint returns 403.
3. Input parameters are validated against the UI Flow's input schema before the session is created.

Within a UI Flow session, individual components can be hidden or disabled via permission-based hide/disable rules. These evaluate at runtime against the user's permission set, the same way they evaluate JavaScript expressions today.

### Migration from earlier versions

UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.

***

## Session owner

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

By default, a newly created UI Flow restricts each running session to a single user, its **session owner**. While a session is owned, other users cannot open or act on that same session.

### Allowing multiple editors

The behavior is controlled by a setting on the UI Flow that allows multiple editors.&#x20;

| Setting | Behavior | Default |
| - | - | - |
| **Multiple editors off** | The session has a single owner. Other users are blocked from the same session. | Newly created UI Flows |
| **Multiple editors on** | Any permitted user can join the session (previous behavior). | UI Flows imported or created before this release |

UI Flows imported from an earlier release, or created before this release, keep the previous multi-user behavior, so upgrading does not change how existing flows run. Review the setting per UI Flow if you want to enforce single-owner sessions.

### Enforcing session ownership

When multiple editors are not allowed and a second user tries to access a session that already has an owner:

* The renderer shows an access-denied screen instead of the UI Flow.&#x20;
* The runtime status request for that session returns `403`.
* The blocked attempt is written to the [audit log](../platform-deep-dive/core-extensions/audit) as unauthorized session access.

### Session owner in permission rules

Session ownership is also available as a value in [permission-based hide and disable rules](#runtime-enforcement): a component can be shown or enabled only for the session owner.&#x20;

***

## Session expiry

A UI Flow session can be set to expire automatically after a set time or on a schedule. When a session expires, it becomes read-only: the user can still see the data already loaded, but no further actions can be taken.

### Setting the expiry time

Open **Settings → General** in the UI Flow editor and set the **Expiry time** field. It accepts either:

* An **ISO-8601 duration** — for example `PT3M22S` (3 minutes, 22 seconds) or `PT1H` (1 hour), measured from when the session starts.
* A **cron expression** — for example `0 0 9-17 * * MON-FRI`, to expire sessions on a schedule.

Leave the field empty for no expiry (the default). The value is validated for format only; an invalid entry blocks **Save settings**.

### Expired sessions

When a session reaches its expiry, the runtime marks it **EXPIRED**:

* All actions are blocked — the user cannot submit, navigate, or trigger any process action from the expired session.
* Data already loaded stays visible in read-only form; nothing is wiped.
* In the Designer session preview, the session status is shown as **EXPIRED**.

Expiry is enforced by the platform server-side, so it applies the same way in the deployed app and the Designer preview.

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Starting with 5.11, an expired session is no longer kept accessible in read-only form. Instead, the runtime presents a session-expired screen with an option to start a fresh session.  Attempts to keep using or re-open an expired session are recorded in the [audit log](../platform-deep-dive/core-extensions/audit) as expired-session access.

***

## Caching

UI Flow definitions are cached at runtime to speed up rendering — the flow definition, its name, allowed roles, templates, and custom-component data. The cache is populated lazily on first use and is invalidated automatically when a UI Flow's resources are overridden at runtime.

### Clearing the cache manually

If you need to force a refresh, use the **Clear cache** action in the UI Flow editor:

**1. Open the UI Flow**

Open the UI Flow whose cache you want to clear.

**2. Clear cache**

Open the **⋮** (more) menu in the page header and select **Clear cache**. This clears the cached definition for that UI Flow.

> [!NOTE]
>
> **Clear cache** requires delete permission on the UI Flow. It clears the cache for the selected UI Flow only.

***

## Limitations and compatibility

### Current limitations

> [!WARNING]
>
> UI Flows have the following limitations:

* **Data Persistence**: Session variables persist only for the lifetime of the session — data that must outlive the session must be passed to processes for storage
* **Complex Conditionals**: For complex business rules, use processes instead
* **Reusable UI**: Reusable UI components are not yet supported in UI Flows on self-hosted 5.9.x. On SaaS (5.12), Reusable UI templates can be placed on UI Flow pages; see [Where a template can be used](./reusable-resources/reusable-ui#where-a-template-can-be-used)&#x20;
* **Undo-Redo**: Limited undo-redo support in UI Flows Designer
* **Multi-Instance (Concurrent)**: While a UI Flow can launch multiple process instances (for example, separate buttons for mortgage or credit card applications), it cannot yet have multiple instances running concurrently from the same page

### Future enhancements

Planned for future releases:

* **Reusable UI integration**: Integrate reusable UI components in UI Flows with input/output parameters and data mappers. On SaaS (5.12), templates can already be placed on UI Flow pages
* **Enhanced resource management**: Undo-redo, resource usages, merge conflicts, and audit logging
* **Advanced actions**: Start project with entrypoint, start process/project with mappings
* **Additional UI components**: Modal as UI element
* **AI integration**: Additional AI-powered features for UI Flows

***

## Troubleshooting

> [accordion] Start Process action not working
>
> **Possible causes:**
>
> * Process definition not published
> * Missing required process parameters
> * Insufficient permissions
>
> **Solutions:**
>
> * Ensure process definition is published in target environment
> * Verify all required parameters are mapped in the action
> * Check user has permission to start the process
> * Review browser console for error messages

> [accordion] Navigate To action not working
>
> **Possible causes:**
>
> * Target destination no longer exists (deleted or moved in the navigation tree)
> * Destination not available on the current platform
> * Navigation configuration error
>
> **Solutions:**
>
> * Verify the destination still exists in the navigation tree and reselect it in the handler
> * Review navigation configuration in UI Designer
> * Test navigation flow step by step

> [accordion] Task Manager component not showing tasks
>
> **Possible causes:**
>
> * Task Manager not properly configured
> * User doesn't have tasks
> * Filter configuration too restrictive
>
> **Solutions:**
>
> * Verify Task Manager component configuration
> * Check user has assigned tasks in Task Manager
> * Review and adjust filter settings
> * Ensure Task Manager service is running

> [accordion] Platform-specific configuration not applying
>
> **Possible causes:**
>
> * Wrong platform selected in preview
> * Configuration not saved
> * Cache issues
>
> **Solutions:**
>
> * Switch platform tabs and verify configuration
> * Save UI Flow and refresh browser
> * Clear browser cache and reload
> * Test on actual device if possible

***

## Related resources

> [card] [UI Designer Overview](./ui-designer/ui-designer)
>
> Learn about UI Designer capabilities and interface

> [card] [Navigation Areas](./process/navigation-areas)
>
> Understand navigation area types as used in BPMN processes

> [card] [Event Handlers](./ui-designer/event-handlers)
>
> Configure event handlers including Start Process and Navigate To

> [card] [Task Management](../platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> Learn about Task Manager and task management capabilities

> [card] [Chat Component](/5.9/ai-platform/chat-component)
>
> Add conversational AI experiences to your UI Flows

> [card] [AI Platform](/5.9/ai-platform/ai-in-flowx)
>
> Explore AI capabilities in FlowX


# FlowX.AI Advancing Controller
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-components/advancing-controller

The Advancing Controller is a support service for the FlowX.AI Engine that enhances the efficiency of advancing operations. It facilitates equal distribution and redistribution of the workload during scale-up and scale-down scenarios.

The Advancing Controller microservice monitors process advancement in both PostgreSQL and Oracle Database configurations, ensuring efficient workload distribution across worker instances.

## Usage

The Advancing Controller service is responsible for managing and optimizing the advancement process in the PostgreSQL or Oracle databases. It ensures efficient workload distribution, performs cleanup tasks, and monitors the status of worker pods.

If a worker pod fails, the service reassigns its work to other pods to prevent [**process instances**](../../projects/runtime/active-process/process-instance) from getting stuck.

> [!TIP]
>
> It is essential to have the Advancing Controller service running alongside the FlowX Engine for uninterrupted instance advancement.

> [!TIP]
>
> Ensure that both the FlowX Engine and the Advancing Controller microservices are up and running concurrently for optimal performance.

## Configuration

For detailed instructions on how to set up the Advancing Controller microservice, refer to the following guide:

> [card] [Advancing controller setup guide](../../../setup-guides/advancing-controller-setup-guide)


# FlowX.AI Events Gateway
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-components/events-gateway

The FlowX Events Gateway is a service that centralizes the communication with Server-Sent Events (SSE) messages from Backend to Frontend.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/events_gateway_archi.png)

The FlowX Events Gateway serves as a central component for handling and distributing events within the system:

> [card] [Event processing](#event-processing)

> [card] [Message distribution](#message-distribution)

> [card] [Event publication](#event-publication)

> [card] [Integration with Redis](#integration-with-redis)

### Event processing

The Events Gateway system is responsible for receiving and processing events from various sources, such as the [**FlowX Engine**](./flowx-engine) and [**Task Management**](../core-extensions/task-management/task-management-overview). It acts as an intermediary between these systems and the rest of the system components.

> [!TIP]
>
> It is a reusable component and is also used in administration scenarios to provide feedback without a refresh—for example, surfacing misconfigurations so an error can be displayed in real-time during configuration.

### Message distribution

The Events Gateway system reads messages from the Kafka topic (`messaging_events_topic`) and distributes them to relevant components within the system. It ensures that the messages are appropriately routed to the intended recipients for further processing.

### Event publication

The Events Gateway system plays a crucial role in publishing events to the frontend renderer (FE renderer). It communicates with the frontend renderer using `HTTP` via `WebFlux`. By publishing events, it enables real-time updates and notifications on the user interface, keeping the user informed about the progress and changes in the system.

It is designed to efficiently send updates to the frontend in the following scenarios:

* When reaching a specific [**User Task (UT)**](../../building-blocks/node/user-task-node), a notification is sent to ensure the corresponding screen is rendered promptly.
* When specific actions require data to be sent to the user interface from a node.

### Integration with Redis

> [!NOTE]
>
> [**Redis**](../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis) plays an important role within the platform. It handles every message and is mandatory for the platform to function correctly, especially with the frontend. The platform relies on Redis to ensure that the messages are distributed efficiently and that the correct instance with the SSE connection pointer for the recipient is always reached.

The events-gateway system also interacts with Redis to publish events on a stream. This allows other components in the system to consume the events from the Redis stream and take appropriate actions based on the received events.

In these situations, the FlowX Engine places a message on Kafka for the Events Gateway. The Events Gateway then retrieves the message and stores it in Redis.

In summary, the events-gateway system acts as a hub for event processing, message distribution, and event publication within the system. It ensures efficient communication and coordination between various system components, facilitating real-time updates and maintaining system consistency.

For more details about how to configure events-gateway microservice, check the following section:

> [card] [Events gateway configuration](../../../setup-guides/events-gateway-setup)


# FlowX.AI Engine
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-components/flowx-engine

Core service that runs process definitions, generates UI, and communicates with the frontend, custom integrations, and plugins.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Engine%20Diagram%20%281%29.png)

> [!NOTE]
>
> The Web renderer supports both Angular and React. The diagram above uses Angular as an example, but the same architecture applies to React-based deployments.

## Orchestration

Creating and interacting with process instances is pretty straightforward, as most of the interaction happens automatically and is handled by the engine.

The only points that need user interaction are starting the process and executing user tasks on it (for example when a user fills in a form on the screen and saves the results).

> [card] [FlowX Engine setup guide](../../../setup-guides/flowx-engine-setup-guide/)


# FlowX.AI Audit
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/audit

The Audit service provides a centralized location for all audit events. The following details are available for each event.

* **Timestamp** - the date and time the event occurred, the timestamp is displayed in a reversed chronologically order
* **User** - the entity who initiated the event, could be a username or a system
* **Subject** - the area or component of the system affected by the event

> [accordion] Possible values
>
> <ul>
>   <li>Process Instance</li>
>   <li>Process variables</li>
>   <li>Token</li>
>   <li>Task</li>
>   <li>Exception</li>
>   <li>Process definition</li>
>   <li>Node</li>
>   <li>Action</li>
>   <li>UI Component</li>
>   <li>General Settings</li>
>   <li>Swimlane</li>
>   <li>Swimlane Permissions</li>
>   <li>Connector</li>
>   <li>Enumeration</li>
>   <li>Enumeration Value</li>
>   <li>Substitution Tag</li>
>   <li>Content Model</li>
>   <li>Language</li>
>   <li>Source System</li>
>   <li>Image</li>
>   <li>Font file</li>
>   <li>Custom Component</li>
>   <li>Reusable UI Template</li>
>   <li>Reusable Business Rule</li>
>   <li>UI Flow</li>
>   <li>End-user group</li>
>   <li>End user</li>
>   <li>Runtime access</li>
>   <li>Designer user</li>
>   <li>Workflow Instance (SaaS · 5.11)</li>
>   <li>Bulk Migrate Process Instances (SaaS · 5.12)</li>
> </ul>

* **Event** - the specific action that occurred

> [accordion] Possible values
>
> <ul>
>   <li>Create</li>
>   <li>Update</li>
>   <li>Update bulk</li>
>   <li>Update state</li>
>   <li>Edit</li>
>   <li>Export</li>
>   <li>Import</li>
>   <li>Delete</li>
>   <li>Clone</li>
>   <li>Start</li>
>   <li>Start with inherit</li>
>   <li>Advance</li>
>   <li>View</li>
>   <li>Expire</li>
>   <li>Message Send</li>
>   <li>Message Receive</li>
>   <li>Notification receive</li>
>   <li>Run scheduled action</li>
>   <li>Execute action</li>
>   <li>Finish</li>
>   <li>Dismiss</li>
>   <li>Retry</li>
>   <li>Abort</li>
>   <li>Assign</li>
>   <li>Unassign</li>
>   <li>Hold</li>
>   <li>Unhold</li>
>   <li>Invite</li>
>   <li>Bulk invite</li>
>   <li>Resend invite</li>
>   <li>Share</li>
>   <li>Update password</li>
>   <li>Add user to end-user group</li>
>   <li>Remove user from end-user group</li>
>   <li>Assigned to end-user group</li>
>   <li>Removed from end-user group</li>
>   <li>Render (SaaS · 5.11)</li>
>   <li>Request conversation history (SaaS · 5.11)</li>
>   <li>Request list of conversations (SaaS · 5.11)</li>
>   <li>Migrate (SaaS · 5.12)</li>
> </ul>

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**
>
> Audit coverage extends to user and access management operations: the End-user group, End user, Runtime access, and Designer user subjects, together with the invite, share, password update, and end-user group membership events. Group membership changes are recorded from both perspectives — as an event on the group (user added or removed) and on the user (assigned or removed).
>
> Starting with FlowX.AI 5.9.3, workspace and project membership changes are also recorded from the user's perspective.
>
> Calls made from a UI Flow to workflow and process resources are audited as well (SaaS · 5.11). This adds the **Workflow Instance** subject, together with the **Render**, **Request conversation history**, and **Request list of conversations** events. These entries also carry the app and workflow instance names.
>
> [Bulk migration of process instances](../../projects/runtime/active-process/migrate-process-instances#audit-trail) between builds is audited as well (SaaS · 5.12). This adds the **Bulk Migrate Process Instances** subject and the **Migrate** event: one entry per migration run, plus one **Migrate** entry on the **Process Instance** subject for every migrated instance, all attributed to the user who started the migration.

* **Subject identifier** - the name related to the subject, there are different types of identifiers based on the selected subject

* **Project/Library name** - the project or library the event belongs to

* **Project/Library version** - the project or library version the event belongs to

* **Workspace ID** - the workspace the event belongs to, shown only in the organization-level audit log

* **Section** - the section the event belongs to, shown only in the workspace-level audit log

* **Status** - the outcome of the event (e.g. success or failure)

![Audit log overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/audit_log_new.png)

## Filtering

You can filter audit records by event date and by selecting specific options for User, Subject, and Subject Identifier.

* Filter by event date

![Audit filter by event date](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/audit_filter_by_event.png)

* **User** - single selection, type at least 4 characters
* **Subject** - single selection
* **Subject identifier** - exact match

> [!NOTE]
>
> The audit trail captures everything by design: every change is recorded and persisted whether it was performed by a person, a system actor, or a service account, and no setting excludes events at capture time — completeness is what makes it an audit trail. Filtering happens only when reading the log. The **User** filter is a positive selection — you pick one author to view, so narrowing to human users means selecting them, not excluding system actors.

## Audit log details

To view additional details for a specific event, click the eye icon on the right of the event in the list. Additional information available in the audit log details window includes
Here you have the following information:

* **Event** - the specific action that occured
* **URL** - the URL associated with the event
* **Body** - any additional data or information related to the event

![Audit log details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/audit_log_details.png)

> [card] [Audit setup](../../../setup-guides/audit-setup-guide)
>
> More details on how to deploy Audit microservice

For the full picture of platform security, including identity, access control, and AI data protection, see the [Security overview](/5.9/docs/platform-overview/security).


# Configuration parameters
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/configuration-parameters

Manage variables and values that change across deployment environments (Development, QA, Production) without hardcoded updates.

In earlier FlowX.AI versions, configuration parameters were called **generic parameters**.

> [!NOTE]
>
> Configuration Parameters are defined per **project version** or **library version**, ensuring consistency across builds while allowing for environment-specific overrides. These parameters can be used across various components, such as business rules, UI elements, integration designer, and gateways.
>
> Libraries can define configuration parameters to facilitate testing of processes or workflows that depend on them. However, unlike project-level configuration parameters, libraries do not support direct overrides.
>
> * Libraries provide default values for configuration parameters.
> * Projects using these libraries can override the provided values as required.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2018.45.32.png)

***

## Default and override values

* **Default Value**: Defined during parameter creation and included in the application build. It serves as the fallback value when no environment-specific override is set.
* **Override Value**: A value defined post-deployment for a specific environment. Overrides take precedence during runtime.
* **Precedence Behavior** (process variables override):
  * If a process variable and a configuration parameter share the same name, the process variable's value takes precedence during runtime.
  * If the process variable is null or undefined, the configuration parameter's value is used as a fallback.
  * Process variables override configuration parameters unless the process variable is `null` or undefined, in which case the configuration parameter is used.
* **Subprocess Behavior**:
  * When a value is passed to a subprocess, the subprocess uses the resolved value (process variable or configuration parameter) from the parent process.
  * If a new value is defined within the subprocess, it is appended back to the parent process.

> [!TIP]
>
> To avoid conflicts, use distinct names for process variables and generic parameters whenever possible.

> [!NOTE]
>
> **Exception in Business Rules**:\
> In business rules, values are taken directly from the map of configuration parameters without applying the above fallback logic.

For details on configuring runtime overrides, see:

> [card] [Configuration Parameters Overrides](../../projects/runtime/configuration-parameters-overrides)

***

## Types of configuration parameters

Configuration parameters are defined as **key-value pairs** and support the following types:

### Value

A static value directly used by the project. Suitable for settings that do not change across environments.

* **Use Cases**:
  * Feature flags to toggle functionality (e.g., enabling/disabling insurance sales in a customer dashboard).
  * Email addresses for notification recipients.
  * Homebank redirect URLs for specific processes.

* **Example**:
  * **Key**: `officeEmail`
  * **Type**: `value`
  * **Value**: `officeEmail@office.com`

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-19%20at%2010.02.09.png)

***

### Environment variable

References an external value managed by DevOps. The stored value is the **environment variable name** that is resolved at runtime by looking it up in a configured **provider** (pod environment variables by default, or Kubernetes ConfigMaps). By default, the name must start with `FLOWX_CONFIGPARAM_`, for example `FLOWX_CONFIGPARAM_BASE_URL`; a variable named anything else, such as a plain `BASE_URL`, can't be read at runtime.

* **Use Cases**:
  * Environment-specific API base URLs.
  * Dynamic configuration of services or integrations.

* **Example**:
  * **Key**: `baseUrl`
  * **Type**: `environment variable`
  * **Value**: `FLOWX_CONFIGPARAM_BASE_URL` (environment variable name resolved at runtime to an externally defined value)

> [!WARNING]
>
> By default, only variables that match the regex pattern `FLOWX_CONFIGPARAM_.*` can be read at runtime. Variables that don't follow this naming convention will not be accessible, even if they are properly defined. See [Runtime access patterns](#runtime-access-patterns) for more details.

Configuration details:

| Key | Type | Value | Description |
| - | - | - | - |
| baseUrl | `environment variable` | `FLOWX_CONFIGPARAM_BASE_URL` | A reference to the base URL configured externally by DevOps. |

**Example values for different environments**

| Environment | External Variable Name | Actual Value |
| - | - | - |
| Development | `FLOWX_CONFIGPARAM_BASE_URL` | `https://dev.example.com/api` |
| QA | `FLOWX_CONFIGPARAM_BASE_URL` | `https://qa.example.com/api` |
| Production | `FLOWX_CONFIGPARAM_BASE_URL` | `https://api.example.com` |

***

### Secret environment variable

References sensitive data (passwords, API keys, credentials) managed by DevOps. The value you enter is the **name of the environment variable** (e.g., `FLOWX_CONFIGPARAM_DB_PASSWORD`) that holds the actual secret. At runtime, FlowX resolves this name by looking it up in a dedicated secrets provider — separate from the one used for regular environment variables — so that sensitive values can be stored and accessed securely (e.g., via Kubernetes Secrets).

* **Use Cases**:
  * Passwords or tokens for integrations.
  * Secure configuration of external services in the integration designer.

* **Example**:
  * **Key**: `dbPassword`
  * **Type**: `secret environment variable`
  * **Value**: `FLOWX_CONFIGPARAM_DB_PASSWORD`

> [!WARNING]
>
> Like environment variables, secret environment variables must also follow the regex pattern `FLOWX_CONFIGPARAM_.*` to be accessible at runtime. See [Runtime access patterns](#runtime-access-patterns) for more details.

### How environment variable and secret environment variable differ

Both types work the same way — they store an environment variable name that is resolved at runtime by a **provider**. The key difference is that each type uses a **separate provider**, which can be configured independently:

| Type | Provider setting | Default provider | Kubernetes provider |
| - | - | - | - |
| Environment variable | `FLOWX_CONFIGPARAMS_VARS_PROVIDER` | `env` (pod env vars) | `k8s-configmaps` |
| Secret environment variable | `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | `env` (pod env vars) | `k8s-secrets` |

> [!NOTE]
>
> With the **default `env` provider**, both types resolve from pod environment variables — the only difference is that each type has its own allowlist regex (`FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX` vs `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX`), so operators can control which variables are accessible for each type.
>
> With **Kubernetes providers**, the distinction becomes more significant: environment variables read from **ConfigMaps** (plain text), while secret environment variables read from **Kubernetes Secrets** (Base64-encoded).

For full provider configuration details, see the [FlowX Engine setup guide](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters) or the [Integration Designer setup guide](/5.9/setup-guides/integration-designer-setup#configuration-parameters).

***

## Use cases for configuration parameters

Configuration parameters simplify the management of environment-specific or dynamic settings across multiple project components:

1. **Business Rules**:
   * Define dynamic logic based on parameters such as feature toggles or environment-specific conditions.
   * Access configuration parameters directly from the `additionalData.applicationConfiguration` map.

> [!NOTE]
>
> For more information on how to use configuration parameters in business rules, see [Extracting values from configuration parameters](../../building-blocks/actions/business-rule-action/extracting-additional-data#extracting-values-from-configuration-parameters).

2. **UI Elements**:
   * Configure content dynamically based on the environment (e.g., URLs for redirects, conditional features).
   * **Note**: Ensure variables referenced in UI components (e.g., for dynamic content or URLs) are uniquely named to avoid unexpected overrides by process variables.
3. **Integration Designer**:
   * Reference configuration parameters in system URLs, tokens, credentials, and other endpoint settings.
   * For a data source whose base URL differs per environment (dev, UAT, production), put a parameter such as `${baseUrl}` in the base URL. Then either override it per environment in [Configuration parameters overrides](../../projects/runtime/configuration-parameters-overrides), or make it an `environment variable` parameter whose value is a `FLOWX_CONFIGPARAM_` name, such as `FLOWX_CONFIGPARAM_BASE_URL`, that DevOps sets per environment.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-19%20at%2010.40.02.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-19%20at%2010.41.41.png)

4. **Gateways**:
   * Dynamically manage routing and decision-making logic using environment-specific parameters.

5. **Workflow condition nodes**:
   * Use configuration parameters and user details in workflow Fork/Condition node expressions.
   * Access configuration parameters via `additionalData.applicationConfiguration` and user details via `additionalData.securityDetails`.

***

## Autocomplete support

Configuration parameters are surfaced through autocomplete in two places:

### Integration Designer fields

Fields that accept configuration parameters (base URLs, tokens, client IDs, and other system settings) provide a **searchable dropdown** when you type `$`:

* Type `$` to trigger autocomplete and see available configuration parameters
* Filter the list by typing the parameter key after `$`
* Select a parameter to insert it as `${paramKey}`
* If no matching parameter exists, select **Create new** to define a new configuration parameter inline without leaving the current screen

### Business rule code editors

The Monaco code editor in business rule actions provides **IntelliSense autocomplete** for configuration parameters. When typing `additionalData.applicationConfiguration.`, the editor shows all defined configuration parameters with their descriptions and values.

> [!NOTE]
>
> Sensitive parameters display masked values (`********`) in the autocomplete suggestions.

***

## Adding a configuration parameter

To add a new configuration parameter:

1. Navigate to **Your Project** → **Configuration Parameters**.
2. Click **New Parameter** and provide the following:
   * **Key**: Name of the parameter.
   * **Type**: Select `value`, `environment variable`, or `secret environment variable`.
   * **Value**:
     * For `value`: Enter the static value.
     * For `environment variable` or `secret environment variable`: Enter a name following the agreed naming convention (must start with `FLOWX_CONFIGPARAM_` by default).
   * **Sensitive**: Toggle **ON** to mark this parameter as containing sensitive data. When enabled, the parameter's resolved value is masked (`********`) in engine debug logs. This flag is independent of the parameter type — any type can be marked as sensitive. For a `value` parameter, FlowX Designer also shows `********` instead of the value after you save it (SaaS · 6.0). See [What happens after you save a sensitive value?](#what-happens-after-you-save-a-sensitive-value).
3. Click **Save** to include the parameter in the application build.

> [!TIP]
>
> Remember that environment variables and secret environment variables must follow the naming pattern `FLOWX_CONFIGPARAM_*` to be accessible at runtime. See [Runtime access patterns](#runtime-access-patterns) for more details.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-18%20at%2019.07.20.png)

### What happens after you save a sensitive value?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

After you save a `value` parameter with **Sensitive** toggled **ON**, FlowX Designer never shows the stored value again. You see `********` in its place in:

* the project's **Configuration Parameters** list
* [configuration parameter overrides](../../projects/runtime/configuration-parameters-overrides)
* build details and build lists
* the merge view when you merge project versions

The real value is still used at runtime. Only `value` parameters are hidden: an `environment variable` or `secret environment variable` parameter holds the name of a variable, not the secret itself, so its value stays visible.

When you edit a hidden parameter:

* **Change other fields without retyping the value**: FlowX.AI keeps the stored value.
* **Toggle Sensitive OFF**: FlowX.AI keeps the stored value and shows it in clear from then on.
* **Change the type**: enter the real value. `********` isn't accepted.
* **Create a new override**: enter the real value. A value copied as `********`, for example from a build, isn't accepted.
* **Merge versions that hold different values for the parameter**: enter the real value in the merge view.

When `********` can't stand for a stored value, the save fails with: `The hidden placeholder can only keep the stored value of a sensitive VALUE config param; send the real value.`

Audit log entries for creating or updating configuration parameters and overrides don't record the request body, so parameter values don't reach the audit log.

***

## Runtime access patterns

FlowX.AI implements security controls to limit which environment variables and secrets can be accessed at runtime. This prevents unauthorized access to system variables and ensures only intended configuration parameters are readable by the application.

### Default regex pattern

By default, the FlowX Engine uses the regex pattern `FLOWX_CONFIGPARAM_.*` to filter which configuration parameters can be accessed at runtime. This means:

* **Environment variables** and **secret environment variables** must start with `FLOWX_CONFIGPARAM_` to be readable
* Variables that don't match this pattern will be ignored, even if properly defined in the environment
* This security measure prevents accidental access to system variables like `SPRING_*`, `JAVA_*`, or other sensitive environment variables

### Naming convention requirements

When defining environment variables or secret environment variables, follow this naming convention:

✅ **Correct naming:**

* `FLOWX_CONFIGPARAM_API_URL`
* `FLOWX_CONFIGPARAM_DB_PASSWORD`
* `FLOWX_CONFIGPARAM_EXTERNAL_SERVICE_TOKEN`

❌ **Incorrect naming (will not be accessible):**

* `API_URL`
* `DB_PASSWORD`
* `SERVICE_TOKEN`

![Configuration Parameters Regex Pattern](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/config_params_regex.png)

### Customizing the regex pattern

The default regex pattern can be overridden by configuring the following environment variables on the FlowX Engine:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX` | Regex pattern for environment variables | `FLOWX_CONFIGPARAM_.*` |
| `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX` | Regex pattern for secret variables | `FLOWX_CONFIGPARAM_.*` |

> [!WARNING]
>
> Changing the default regex pattern should be done carefully and only by experienced DevOps teams. Using overly permissive patterns (like `.*`) can expose sensitive system variables to the application.

### Best practices for naming

1. **Always use the prefix**: Start all environment and secret variables with `FLOWX_CONFIGPARAM_`
2. **Use descriptive names**: Make variable names clear and specific to their purpose
3. **Follow consistent naming**: Use uppercase with underscores for environment variables
4. **Test accessibility**: Verify that your variables are accessible in your target environment before deployment

***

## Export and import

You can export and import configuration parameters to transfer them between projects or environments.

### Exporting

1. Navigate to **Your Project** > **Configuration Parameters**
2. Open the context menu and select **Export**
3. The parameters are downloaded as a ZIP file

### Importing

1. Navigate to **Your Project** > **Configuration Parameters**
2. Open the context menu and select **Import ZIP**
3. Select the ZIP file exported from another project or environment
4. If parameters with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting parameter (or use **Apply to all**):
   * **Keep both** - imports the parameter as a new copy alongside the existing one
   * **Replace** - overwrites the existing parameter with the imported version
   * **Skip this one** - keeps the existing parameter unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

***

## Technical notes and best practices

### Security

* **Sensitive values**: Mark parameters containing passwords, tokens, or credentials as **Sensitive** to ensure their values are masked in engine debug logs and, for `value` parameters, hidden in FlowX Designer after you save them (SaaS · 6.0).
* **Secret environment variables**: Use the `secret environment variable` type for values that should be sourced from Kubernetes Secrets in production deployments.
* Avoid logging or exposing sensitive configuration parameter values in custom business rules or UI elements.

### Environment-specific updates

* Environment variable and secret environment variable updates are managed by DevOps.
* Updates may require service restarts unless a caching or real-time mechanism (e.g., change streams) is implemented.

### Reserved keys

* Certain keys are reserved for system use (e.g., `processInstanceId`). Avoid using reserved keys for custom configurations.

### Variable naming

* **Avoid Shared Names**:
  * Do not use the same name for configuration parameters and process variables to prevent unintentional overrides.
* **Fallback Logic Awareness**:
  * Understand that `null` or `undefined` process variables will default to the corresponding configuration parameter's value during runtime.
* **Subprocess Behavior**:
  * Variables in subprocesses are appended back to parent processes with their current state. Plan naming conventions and data flows accordingly.

> [!WARNING]
>
> When designing processes, ensure that variables in subprocesses and parent processes do not conflict with configuration parameters names. Test these interactions in scenarios where variables are dynamically assigned or left undefined.

***


# FlowX.AI CMS
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/content-management

The FlowX.AI Headless Content Management System (CMS) is a core component of the FlowX.AI platform, designed to enhance the platform's capabilities with specialized functionalities for managing taxonomies and diverse content types.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/cms5.1.png)

## Key features

The FlowX.AI CMS offers the following features:

> [card] [Enumerations](enumerations)
>
> Manage and configure enumerations for various content types

> [card] [Substitution tags](substitution-tags)
>
> Utilize tags to dynamically insert content values. Essential for Task Management localization with 51 system tags

> [card] [Media library](media-library)
>
> Organize and manage media assets

> [card] [Notification templates](notifications-plugin)
>
> Manage notification templates

> [card] [Document templates](documents-plugin)
>
> Manage document templates

## Enumeration sources

The FlowX.AI platform supports three types of enumeration sources:

* **Project-level enumerations**: Enumerations defined directly at the project level within the FlowX.AI Designer
* **Library enumerations**: Enumerations defined in a shared library that must be set as a dependency for the project
* **Data source enumerations**: Enumerations that come from external data sources when using the Enumeration Mapper feature

## Deployment and integration

The CMS can be rapidly deployed on your chosen infrastructure, preloaded with necessary taxonomies or content via a REST interface, and integrated with the FlowX Engine using Kafka events.

For deployment and configuration, refer to the:

> [card] [CMS setup guide](../../../../setup-guides/cms-setup)

## Using the CMS service

Once the CMS is deployed in your infrastructure, you can define and manage custom content types, such as lists with different values based on external systems, blog posts, and more.

### Kafka integration

You can use Kafka to translate and extract content values based on your defined languages and source systems. This is useful for:

* Extracting values from specific enumerations for UI components
* Sending data to other integrations that require different label formats
* Generating documents with localized content
* Handling different label conventions from various external systems

> [!NOTE]
>
> Various external systems and integrations might use different labels for the same information. In processes, it is easier to use the corresponding code and translate this into the needed label when necessary: for example when sending data to other integrations, when generating documents, etc.

#### Kafka topics configuration

Manage content retrieval messages between the CMS and the FlowX Engine using the following Kafka topics:

| Environment Variable | Default FlowX.AI value (customizable) | Purpose |
| - | - | - |
| KAFKA\_TOPIC\_REQUEST\_CONTENT\_IN | ai.flowx.plugin.cms.trigger.retrieve.content.v1 | Topic where CMS listens for incoming content retrieval requests |
| KAFKA\_TOPIC\_REQUEST\_CONTENT\_OUT | ai.flowx.engine.receive.plugin.cms.retrieve.content.results.v1 | Topic where CMS sends content retrieval results back to FlowX Engine |

> [!TIP]
>
> You can find the defined topics in two ways:
>
> 1. In the FlowX.AI Designer: Go to **Platform Status** → **cms-core-mngt** → **kafkaTopicsHealthCheckIndicator** → **Details** → **Configuration** → **Topic** → **Request** → **Content** (use the `in` topic).
>
> ![Kafka Topics in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/kafka-translate-cms-topics.png)
>
> 2. Alternatively, check the CMS microservice deployment for the `KAFKA_TOPIC_REQUEST_CONTENT_IN` environment variable.

#### Required Kafka headers

The following headers must be included in translation requests:

| Header | Required | Description |
| - | - | - |
| `BUILD_APP_VERSION_ID` | Yes\* | Application version build ID |
| `BUILD_ID` | Yes\* | Alternative to BUILD\_APP\_VERSION\_ID |
| `WORKSPACE_ID` | No | Workspace identifier for multi-tenant environments |

> [!WARNING]
>
> Either `BUILD_APP_VERSION_ID` or `BUILD_ID` must be provided in the Kafka message headers.

#### Translation request structure

Add a [**Send Message Task** (kafka send event)](../../../building-blocks/node/message-send-received-task-node) and configure it to send content requests to the FlowX.AI Engine.

##### Request parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `sourceSystem` | String | No\* | Target source system for code translation |
| `fromSourceSystem` | String | No\* | Source system to translate codes from (cannot be used with `sourceSystem`) |
| `language` | String | No\* | Language code for label translation (e.g., "en", "fr", "ro") |
| `replyTopic` | String | No | Custom Kafka topic for response (overrides default) |
| `entries` | Array | Yes | List of content entries to translate |

> [!WARNING]
>
> **Validation rules:**
>
> * At least one of `sourceSystem`, `language`, or `fromSourceSystem` must be provided
> * `sourceSystem` and `fromSourceSystem` **cannot both be provided** (bidirectional conflict)

##### Entry structure

Each entry in the `entries` array contains:

| Parameter | Type | Required | Description |
| - | - | - | - |
| `codes` | Array | Yes | Array of codes to translate |
| `contentDescription` | Object | Yes | Content metadata for lookup |
| `contentDescription.name` | String | Yes | Enumeration/content name |
| `contentDescription.application` | String | No | Application name (defaults to `defaultApplication`) |
| `children` | Object | No | Nested child content translations (hierarchical) |

#### Example: Basic translation request

<video />

**Request Body:**

```json theme={"dark"}
{
  "sourceSystem": "FlowX",
  "language": "fr",
  "entries": [
    {
      "codes": [
        "RO",
        "DE"
      ],
      "contentDescription": {
        "name": "tari"
      }
    }
  ]
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/kafka-translate-cms.png)

#### Example: Hierarchical content request

For enumerations with nested/hierarchical structures (parent-child relationships), you can request content at multiple levels by specifying the `children` property. This is useful when you need to retrieve values from dependent dropdowns or cascading selections.

**Use cases:**

* Country → County → City selections
* Product Category → Subcategory → Product
* Department → Team → Employee
* Any cascading dropdown scenario

**Request Body for Hierarchical Content:**

```json theme={"dark"}
{
  "language": "ro",
  "sourceSystem": "FlowX",
  "entries": [
    {
      "codes": [
        "RO"
      ],
      "contentDescription": {
        "name": "tari"
      },
      "children": {
        "RO": [
          {
            "code": "AB",
            "children": [
              {
                "code": "AB-Abrud"
              },
              {
                "code": "AB-Aiud"
              }
            ]
          },
          {
            "code": "BV",
            "children": [
              {
                "code": "BV-Brasov"
              }
            ]
          }
        ]
      }
    }
  ]
}
```

**Key points for hierarchical requests:**

* The `children` property is an object where **keys represent parent codes** and values are arrays of child items
* Each child item must have a `code` property and can optionally have a nested `children` array for deeper hierarchies
* This allows you to request specific branches of hierarchical data rather than entire enumerations
* Content metadata (name, application) is inferred from parent-child relationships configured in CMS
* Unlimited nesting depth is supported for complex hierarchical structures

> [!TIP]
>
> **Best practice:** Request only the levels needed for the current UI state rather than the entire hierarchy upfront. Use progressive loading (parent → selected child → grandchild) for better performance.

#### Translation types

The CMS translation service supports multiple types of translations:

> [tab] Language Translation
>
> **Purpose:** Translate codes to human-readable labels in specific languages
>
> **Request:**
>
> ```json theme={"dark"}
> {
>   "language": "en",
>   "entries": [
>     {
>       "codes": ["RO"],
>       "contentDescription": {"name": "country"}
>     }
>   ]
> }
> ```
>
> **Response:**
>
> ```json theme={"dark"}
> {
>   "entries": [
>     {
>       "contentName": "country",
>       "code": "RO",
>       "label": "Romania",
>       "translatedCode": null
>     }
>   ]
> }
> ```

> [tab] Source System Translation
>
> **Purpose:** Translate codes to target source system format
>
> **Request:**
>
> ```json theme={"dark"}
> {
>   "sourceSystem": "SAP",
>   "entries": [
>     {
>       "codes": ["RO"],
>       "contentDescription": {"name": "country"}
>     }
>   ]
> }
> ```
>
> **Response:**
>
> ```json theme={"dark"}
> {
>   "entries": [
>     {
>       "contentName": "country",
>       "code": "RO",
>       "label": null,
>       "translatedCode": "RO-SAP"
>     }
>   ]
> }
> ```

> [tab] Combined Translation
>
> **Purpose:** Get both language labels and source system codes
>
> **Request:**
>
> ```json theme={"dark"}
> {
>   "language": "en",
>   "sourceSystem": "SAP",
>   "entries": [
>     {
>       "codes": ["RO"],
>       "contentDescription": {"name": "country"}
>     }
>   ]
> }
> ```
>
> **Response:**
>
> ```json theme={"dark"}
> {
>   "entries": [
>     {
>       "contentName": "country",
>       "code": "RO",
>       "label": "Romania",
>       "translatedCode": "RO-SAP"
>     }
>   ]
> }
> ```

> [tab] Reverse Translation
>
> **Purpose:** Translate from external source system code to internal code
>
> **Request:**
>
> ```json theme={"dark"}
> {
>   "fromSourceSystem": "SAP",
>   "language": "en",
>   "entries": [
>     {
>       "codes": ["RO-SAP"],
>       "contentDescription": {"name": "country"}
>     }
>   ]
> }
> ```
>
> **Response:**
>
> ```json theme={"dark"}
> {
>   "entries": [
>     {
>       "contentName": "country",
>       "code": "RO",
>       "label": "Romania",
>       "translatedCode": null
>     }
>   ]
> }
> ```

#### Translation response structure

Add a **Receive Message Task** to handle the response from the CMS service. Configure it to listen to the topic where the Engine sends the response (e.g., `ai.flowx.updates.contents.values.v1`).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/kafka-translate-cms-response.png)

**Response Message Structure:**

```json theme={"dark"}
{
  "entries": [
    {
      "contentName": "country",
      "code": "ROMANIA",
      "label": "Romania",
      "translatedCode": "ROMANIA-FlowX"
    },
    {
      "contentName": "country",
      "code": "BAHAMAS",
      "label": "Bahamas",
      "translatedCode": "BAHAMAS-FlowX"
    }
  ],
  "error": null
}
```

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `entries` | Array | List of translated content entries |
| `entries[].contentName` | String | Name of the content/enumeration |
| `entries[].code` | String | Original code value |
| `entries[].label` | String | Translated label based on language parameter |
| `entries[].translatedCode` | String | Code translated for source system (format: `{code}-{sourceSystem}`) |
| `entries[].children` | Object | Nested translated child content (for hierarchical requests) |
| `error` | String | Error message (null if successful) |

**Response for hierarchical content:**

```json theme={"dark"}
{
  "entries": [
    {
      "contentName": "countries",
      "code": "RO",
      "label": "România",
      "translatedCode": "RO-FlowX",
      "children": {
        "AB": [
          {
            "contentName": "counties",
            "code": "AB",
            "label": "Alba",
            "translatedCode": "AB-FlowX",
            "children": [
              {
                "contentName": "cities",
                "code": "AB-Abrud",
                "label": "Abrud",
                "translatedCode": "AB-Abrud-FlowX"
              }
            ]
          }
        ]
      }
    }
  ],
  "error": null
}
```

#### Dynamic language switching example

<video />

The video demonstrates how to change the system language and modify your process to display translations dynamically on different screens.

#### Advanced features

##### Custom reply topics

You can override the default response topic by specifying a `replyTopic` parameter in your request:

```json theme={"dark"}
{
  "language": "en",
  "replyTopic": "ai.flowx.custom.translate.response.v1",
  "entries": [
    {
      "codes": ["RO"],
      "contentDescription": {"name": "country"}
    }
  ]
}
```

This is useful for:

* Process-specific handling
* Asynchronous workflows
* Custom routing logic

> [!WARNING]
>
> Ensure the Engine is configured to listen on custom reply topics before using this feature.

##### Build context and versioning

The CMS translation service uses build context headers to ensure correct content version resolution:

* `BUILD_APP_VERSION_ID` or `BUILD_ID` ensures translation uses the correct content version
* Critical for environments with multiple application versions running simultaneously
* Resolves content from build manifest resource overrides
* Ensures consistent translations across deployments

##### Resource overrides

The translation service supports content overrides via build manifest, enabling:

* Version-specific translations
* Multi-tenant workspace configurations
* Environment-specific content variations
* A/B testing with different content versions

#### Performance considerations

> [accordion] Batch Multiple Codes
>
> Request multiple codes in a single Kafka message to reduce overhead:
>
> ```json theme={"dark"}
> {
>   "language": "en",
>   "entries": [
>     {
>       "codes": ["RO", "DE", "FR", "IT", "ES"],
>       "contentDescription": {"name": "country"}
>     }
>   ]
> }
> ```

> [accordion] Use Hierarchical Children
>
> Request parent and child content together to minimize round trips:
>
> ```json theme={"dark"}
> {
>   "language": "en",
>   "entries": [
>     {
>       "codes": ["RO"],
>       "contentDescription": {"name": "country"},
>       "children": {
>         "RO": [{"code": "AB"}, {"code": "BV"}]
>       }
>     }
>   ]
> }
> ```

> [accordion] Cache Translated Values
>
> Store translated values in process data when they will be reused multiple times within the same process instance.

> [accordion] Progressive Loading
>
> For deep hierarchies, load levels progressively based on user selections rather than requesting entire hierarchies upfront.

#### Error handling

Common translation errors:

| Error | Description | Resolution |
| - | - | - |
| Content not found | The specified content/enumeration does not exist | Verify content name and ensure it's published in CMS |
| Invalid source system | The source system is not configured | Check source system configuration in CMS |
| Missing required fields | Required parameters are missing from request | Ensure `codes` and `contentDescription.name` are provided |
| Build context missing | Required headers not present | Include `BUILD_APP_VERSION_ID` or `BUILD_ID` in headers |
| Validation conflict | Both `sourceSystem` and `fromSourceSystem` provided | Use only one direction of translation per request |

**Error response structure:**

```json theme={"dark"}
{
  "entries": [],
  "error": "Content 'invalid_content_name' not found"
}
```

> [!NOTE]
>
> When translation fails, the `error` field contains a descriptive message and the `entries` array may be empty or contain partial results.

## Additional resources

> [card] [Enumerations](enumerations)
>
> Learn how to configure enumerations in CMS

> [card] [CMS Setup Guide](../../../../setup-guides/cms-setup)
>
> Complete deployment and configuration guide


# Combining files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/combining-files

You can combine multiple files into a single document using the Documents plugin.

This guide provides step-by-step instructions on how to combine multiple files into a single PDF document, such as when a user needs to merge several related documents into one file.

## Prerequisites

1. **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.

2. **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

   * **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section)

3. Before initiating the combining process, ensure you have the unique IDs of all files you want to combine in the storage solution. This ensures that the combination is performed on already uploaded files.

> [!TIP]
>
> Ensure that all files to be combined are PDF documents. The combine operation merges multiple PDF files into a single PDF.

You have two options to obtain file IDs:

* Extract the file ID from a [**Response Message**](./uploading-a-new-document#response-message-example-1) of an upload file request. For more details, refer to the [**upload process documentation**](./uploading-a-new-document).

* Extract the file ID from a [**Response Message**](./generating-from-html-templates#step-3-receive-the-generated-document) of a generate from template request. For more details, refer to the [**document generation reply documentation**](./generating-from-html-templates).

> [!NOTE]
>
> In the following example, we will combine two documents using their `fileId` values obtained from previous upload operations.
>
> **File 1:**
>
> ```json theme={"dark"}
> {
>   "customId": "119501",
>   "fileId": "0b453429-6807-4439-9a14-46222d70620c",
>   "documentType": "APPLICATION_FORM",
>   "documentLabel": null,
>   "minioPath": "flowx-dev-process-id-119501/119501/470_APPLICATION_FORM.pdf",
>   "downloadPath": "internal/files/0b453429-6807-4439-9a14-46222d70620c/download",
>   "noOfPages": 12,
>   "error": null
> }
> ```
>
> **File 2:**
>
> ```json theme={"dark"}
> {
>   "customId": "119501",
>   "fileId": "0da982f6-e167-4e4b-9c71-459e3fca429b",
>   "documentType": "APPENDIX",
>   "documentLabel": null,
>   "minioPath": "flowx-dev-process-id-119501/119501/471_APPENDIX.pdf",
>   "downloadPath": "internal/files/0da982f6-e167-4e4b-9c71-459e3fca429b/download",
>   "noOfPages": 3,
>   "error": null
> }
> ```

## Configuring the combining process

To create a process that combines multiple files into a single document, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-send-message-task) node and a [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-receive-message-task) node:

* Use the **Send Message Task** node to send the combine request.
* Use the **Receive Message Task** node to receive the combine reply.

2. Configure the **first node (Send Message Task)** by adding a **Kafka Send Action**.

3. Specify the [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup#file-combination) where you want to send the combine request.

> [!TIP]
>
> To identify your defined topics in your current environment, follow the next steps:
>
> 1. From the FLOWX.AI main screen, navigate to the Platform Status menu at the bottom of the left sidebar.
> 2. In the FLOWX Components list, scroll to the document-plugin-mngt line and press the eye icon on the right side.
> 3. In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → file → combine**. Here you will find the in and out topics for combining files.

4. Fill in the body of the message request.

#### Message request example

```json theme={"dark"}
{
  "combineFiles": [
    {
      "documentType": "CONTRACT",
      "customId": "119501",
      "files": [
        {
          "fileId": "0b453429-6807-4439-9a14-46222d70620c",
          "startPage": 0,
          "endPage": 11,
          "order": 0
        },
        {
          "fileId": "0da982f6-e167-4e4b-9c71-459e3fca429b",
          "startPage": 0,
          "endPage": 2,
          "order": 1
        }
      ],
      "shouldOverride": true
    }
  ]
}
```

* **combineFiles**: An array of combine operations. Each operation creates one combined document.
  * **documentType**: The document type to assign to the combined file.
  * **customId**: The unique identifier for the combined document (it could be for example the ID of a client or process instance).
  * **files**: An array of files to include in the combined document:
    * **fileId**: The unique identifier of the file to include.
    * **startPage**: Starting page number (0-indexed). Use `0` for the first page.
    * **endPage**: Ending page number (0-indexed). Use `0` to include only the first page, or specify a higher number to include a range.
    * **order**: The order in which files should be combined. Files are merged in ascending order based on this value.
  * **shouldOverride**: A boolean value indicating whether to override an existing document if one with the same name already exists.

> [!WARNING]
>
> **Page numbering is 0-indexed.** Setting both `startPage: 0` and `endPage: 0` will include only the first page of that file. To include all pages from a 12-page document, use `startPage: 0` and `endPage: 11`.

> [!NOTE]
>
> You can combine specific page ranges from different documents. For example, you could take pages 1-3 from document A and pages 5-10 from document B.

5. Configure the **second node (Receive Message Task)** by adding a data stream (**Integration Output** → **Add Stream**, **Source**: **Custom Topic**):

> [!NOTE]
>
> The response will be sent to the `..out` Kafka topic configured for file combination.

## Receiving the reply

The following values are expected in the reply body:

* **customId**: The unique identifier for your document (matching the name of the folder in the storage solution where the document is uploaded).
* **fileId**: The ID of the newly created combined file.
* **documentType**: The document type.
* **documentLabel**: The document label (if available).
* **minioPath**: The storage path for the combined document.
* **downloadPath**: The download path for the combined document.
* **noOfPages**: The total number of pages in the combined document.
* **error**: Any error message in case of an error during the combining process.

#### Message response example

```json theme={"dark"}
{
  "customId": "119501",
  "fileId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "documentType": "CONTRACT",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119501/119501/472_CONTRACT.pdf",
  "downloadPath": "internal/files/c3d4e5f6-a7b8-9012-cdef-345678901234/download",
  "noOfPages": 15,
  "error": null
}
```

The combined file is now available in the storage solution and can be downloaded. The total page count reflects the sum of included pages from all source documents based on your specified page ranges.

> [!NOTE]
>
> Note that the actual values in the response will depend on the specific combine request and the documents being combined.


# Converting files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats

Convert documents between formats using the Documents Plugin. Supports PDF to JPEG conversion and on-the-fly CSV/Excel (including macro-enabled .xlsm) to JSON conversion on download.

The Documents Plugin supports two types of file conversion:

* **PDF to JPEG** — converts an uploaded PDF into JPEG images via Kafka messaging
* **CSV/Excel to JSON** — converts CSV, XLS, XLSX, or XLSM files to structured JSON on-the-fly when downloading, using content negotiation (no new files are stored)

***

## CSV/Excel to JSON conversion

You can download CSV or Excel files as structured JSON directly from the file download endpoints. The conversion happens on-the-fly — no new files are created in storage.

To request JSON output, set the `Accept` header to `application/json` when calling either of these endpoints:

* `GET /internal/files/{fileId}/download`
* `GET /internal/storage/download`

### Supported file types

| Content type | Extensions |
| - | - |
| `text/csv` | `.csv` |
| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | `.xlsx` |
| `application/vnd.ms-excel` | `.xls` |
| `application/vnd.ms-excel.sheet.macroEnabled.12` | `.xlsm` |

> [!NOTE]
>
> `.xlsm` (macro-enabled Excel) is supported, but macros themselves are not executed — only the tabular data is read.

### Query parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `format` | `string` | `objects` | Output shape: `objects` (array of key-value maps using the header row as keys) or `arrays` (array of arrays including headers as the first row) |
| `sheet` | `string` | First sheet | For Excel files, the name of the sheet to convert. If omitted, the first sheet is used |

### Example

```bash theme={"dark"}
curl -H "Accept: application/json" \
  "https://{your-document-url}/internal/files/{fileId}/download?format=objects"
```

Given a CSV file:

```csv theme={"dark"}
name,age,city
Alice,30,New York
Bob,25,London
```

**`format=objects`** returns:

```json theme={"dark"}
[
  {"name": "Alice", "age": "30", "city": "New York"},
  {"name": "Bob", "age": "25", "city": "London"}
]
```

**`format=arrays`** returns:

```json theme={"dark"}
[
  ["name", "age", "city"],
  ["Alice", "30", "New York"],
  ["Bob", "25", "London"]
]
```

### Behavior

* If the file is already JSON, the raw content is passed through unchanged.
* If the file is not a supported tabular format (for example, PDF), the endpoint returns **406 Not Acceptable**.
* If no `Accept: application/json` header is sent, the file downloads as raw bytes — preserving existing behavior.

***

## PDF to JPEG conversion

> [!NOTE]
>
> The PDF to JPEG conversion uses Kafka messaging and creates a new file in storage, unlike the on-the-fly CSV/Excel to JSON conversion described above.

This section provides step-by-step instructions on how to convert an uploaded file from PDF to JPEG.

## Prerequisites

1. **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.

2. **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

* **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section)

3. Before initiating the conversion process, it is essential to identify the file in the storage solution using its unique ID. This ensures that the conversion is performed on an already uploaded file.

You have two options to obtain the file ID:

* Extract the file ID from a [**Response Message**](./uploading-a-new-document) of an upload file request. For more details, refer to the [**upload process documentation**](./uploading-a-new-document).

* Extract the file ID from a [**Response Message**](./generating-from-html-templates) of a generate from template request. For more details, refer to the [**document generation reply documentation**](./generating-from-html-templates)

> [!NOTE]
>
> In the following example, we will use the `fileId` generated for [**Uploading a New Document**](./uploading-a-new-document) scenario.
>
> ```json theme={"dark"}
> {
>   "customId": "119246",
>   "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
>   "documentType": "BULK",
>   "documentLabel": null,
>   "minioPath": "flowx-dev-process-id-119246/119246/458_BULK.pdf",
>   "downloadPath": "internal/files/96975e03-7fba-4a03-99b0-3b30c449dfe7/download",
>   "noOfPages": null,
>   "error": null
> }
> ```

## Configuring the process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_pdf_to_jpeg.png)

To create a process that converts a document from PDF to JPEG format, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) node and a [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node):

* Use the **Send Message Task** node to send the conversion request.
* Use the **Receive Message Task** node to receive the reply.

2. Configure the first node (**Send Message Task**) by adding a **Kafka send action**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_action_name.png)

3. Specify the [**Kafka topic**](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka) where you send the conversion request.

> [!TIP]
>
> To identify your defined topics in your current environment, follow the next steps:
>
> 1. From the FLOWX.AI main screen, navigate to the **Platform Status** menu at the bottom of the left sidebar.
> 2. In the FLOWX Components list, scroll to the **document-plugin-mngt** line and press the eye icon on the right side.
> 3. In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → file → convert**. Here will find the in and out topics for converting files.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kakfa_topics_convert.png)

4. Fill in the body of the message request.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_action.png)

#### Message request example

> [!NOTE]
>
> This is an example of a message that follows the custom integration data model.

```json theme={"dark"}
{
  "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
  "to": "image/jpeg"
}
```

* `fileId`: The file ID that will be converted
* `to`: The file extension to convert to (in this case, "JPEG")

5. Configure the second node (**Receive Message Task**) by adding a data stream (**Integration Output** → **Add Stream**, **Source**: **Custom Topic**):

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_stream.png)

> [!NOTE]
>
> The response will be sent to this `..out` Kafka topic.

## Receiving the reply

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/convert_response.png)

The following values are expected in the reply body:

* **customId**: The unique identifier for your document (it could be for example the ID of a client)
* **fileId**: The file ID
* **documentType**: The document type
* **documentLabel**: The document label (if available)
* **minioPath**: The path where the converted file is saved. It represents the location of the file in the storage system, whether it's a MinIO path or an S3 path, depending on the specific storage solution
* **downloadPath**: The download path for the converted file
* **noOfPages**: If applicable
* **error**: Any error message in case of an error during the conversion process

#### Message response example

```json theme={"dark"}
{
  "customId": "119246",
  "fileId": "8ec75c0e-eaa6-4d80-b7e5-15a68bba7459",
  "documentType": "BULK",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119246/119246/461_BULK.jpg",
  "downloadPath": "internal/files/461/download",
  "noOfPages": null,
  "error": null
}
```

The converted file is now available in the storage solution and it can be downloaded:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/jpg_final.png)

> [!NOTE]
>
> Note that the actual values in the response will depend on the specific conversion request and the document being converted.


# Deleting files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/deleting-a-file

The Documents plugin provides functionality for deleting files.

## How files get deleted

Files in the Documents Plugin can be deleted in two ways:

> [card] Explicit deletion
>
> Using the Kafka delete action described below to manually delete a specific file by its `fileId` and `customId`.

> [card] Implicit deletion (replacement)
>
> When uploading a new file with the **same `customId` AND `documentType`** combination as an existing file, the previous file is automatically marked as deleted.

> [!NOTE]
>
> **Understanding implicit deletion**
>
> The implicit deletion behavior ensures that each `customId` + `documentType` combination points to only one active file. When you upload a new file with an existing combination:
>
> * The previous file is marked as deleted in the database
> * The previous file's download URLs stop working
> * The new file becomes the active document for that combination
>
> This is by design and useful for scenarios where you want to replace documents (e.g., updating a profile photo or replacing a draft contract). However, if you need to store multiple files of the same type, ensure each has a **unique `customId`**.

## Prerequisites

Before deleting files, ensure:

1. **Access Permissions**: Ensure that the user account used has the necessary access rights for updates or deletions.

2. **Kafka Configuration**:

* **Verify Kafka Setup**: Ensure proper configuration and accessibility of the Kafka messaging system.
* **Kafka Topics**: Understand the Kafka topics used for these operations.

3. **File IDs and Document Types**: Prepare information for updating or deleting files:

* `fileId`: ID of the file to delete.
* `customId`: Custom ID associated with the file.

> [!NOTE]
>
> In the example below, we use a `fileId` generated for a document using [**Uploading a New Document**](./uploading-a-new-document) scenario.
>
> ```json theme={"dark"}
> {
>   "docs": [
>     {
>       "customId": "119407",
>       "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2",
>       "documentType": "BULK",
>       "documentLabel": null,
>       "minioPath": "flowx-dev-process-id-119408/119407/466_BULK.pdf",
>       "downloadPath": "internal/files/c4e6f0b0-b70a-4141-993b-d304f38ec8e2/download",
>       "noOfPages": 2,
>       "error": null
>     }
>   ],
>   "error": null
> }
> ```

## Configuring the deletion process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_file_proc.png)

To delete files, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) node and [**Message Event Receive (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-receive-message-task) node:

* Use the **Send Message Task** node to send the delete request.
* Use the **Receive Message Task** node to receive the delete reply.

2. Configure the **first node (Send Message Task)** by adding a **Kafka Send Action**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_file_action.png)

3. Specify the [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup) for sending the delete request.

> [!TIP]
>
> To identify defined topics in your environment:
>
> * Navigate to **Platform Status > FLOWX Components > document-plugin-mngt** and click the eye icon on the right side.
> * In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → file → delete**. Here will find the in and out topics for deleting files.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_topics.png)

4. Fill in the request message body.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_request_message.png)

#### Message request example

Example of a message following the custom integration data model:

```json theme={"dark"}
{
  "customId": "119408",
  "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2"
}
```

* **fileId**: The ID of the file.
* **customId**: The custom ID.

5. Configure the **second node (Receive Message Task)** by adding a data stream (**Integration Output** → **Add Stream**, **Source**: **Custom Topic**):

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_stream.png)

> [!NOTE]
>
> The response will be sent to `..out` Kafka topic.

### Receiving the reply

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/delete_response.png)

The reply body should contain the following values:

* **customId**: The unique identifier for your document (it could be for example the ID of a client)
* **fileId**: The ID of the file
* **documentType**: The document type
* **error**: Any error message in case of an error during the deleting process

#### Message response example

```json theme={"dark"}
{
  "customId": "119408",
  "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2",
  "documentType": null,
  "error": null
}
```


# Document Templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview

You can add Document Templates to your custom FlowX.AI deployment to enhance the core platform capabilities with functionality specific to document handling.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_templates_ex.png)

The Document Templates feature offers the following features:

* **Document storage and editing**: Easily store and make changes to documents.
* **Document generation**: Generate documents using predefined templates and custom process-related data.
* **WYSIWYG editor**: Create various templates using a user-friendly ["What You See Is What You Get" (WYSIWYG) editor](../../../plugins/wysiwyg).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_template_edit.png)

* **Template export and import**: Transfer templates between projects or environments using ZIP files.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_templates_import.png)

To import document templates:

1. Open the context menu on the Document Templates list page and select **Import from ZIP**
2. Select the ZIP file exported from another environment
3. If templates with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
4. Choose a strategy for each conflicting template (or use **Apply to all**):
   * **Keep both** - imports the template as a new copy alongside the existing one
   * **Replace** - overwrites the existing template with the imported version
   * **Skip this one** - keeps the existing template unchanged
5. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

* **Document conversion**: Convert documents from PDF to JPEG format.
* **Document splitting**: Split bulk documents into smaller separate documents.
* **Document editing**: Add generated barcodes, signatures, and assets to documents.
* **OCR integration**: When a document requires OCR (Optical Character Recognition) processing, the Documents Plugin initiates the interaction by passing the document data or reference to the [**OCR plugin**](../../../plugins/custom-plugins/ocr-plugin).

You can deploy the Documents Plugin on your chosen infrastructure, preloaded with industry-specific document templates using an intuitive WYSIWYG editor, and connected to the FLOWX Engine through Kafka events.

* [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#send-message-task)
* [**Receive Message Task(Kafka)**](../../../../building-blocks/node/message-send-received-task-node#receive-message-task)

> [!NOTE]
>
> Performance considerations:
>
> To ensure optimal performance while using Document Templates, consider the following recommendations:
>
> * For large or complex documents, it is recommended to allocate sufficient system resources, such as CPU and memory, to handle the conversion/editing process efficiently.
> * Avoid processing extremely large files or a large number of files simultaneously, as it may impact performance and responsiveness.
> * Monitor system resources during the generating/editing/converting etc. process and scale resources as needed to maintain smooth operations.
> * Following these performance considerations will help optimize the document processing and improve overall system performance.

## Using Document Templates

Once you have deployed the Document Templates microservice in your infrastructure, you can start creating various document templates. After selecting a document template, proceed to create a process definition by including [**Send Message/Receive Message**](../../../../building-blocks/node/message-send-received-task-node) (Kafka nodes) and custom document-related actions in your process flow.

Before adding these actions to your **process definition**, follow these steps:

1. Ensure that all custom information is properly configured in the plugin, such as the document templates to be used.
2. For each Kafka send/receive node you will need a corresponding Kafka topic.

> [!TIP]
>
> The `..in` topic names configured for the plugin should match [**the `..out` topic  names used when configuring the engine**](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka). Make sure to use an outgoing topic name that matches the pattern configured in the Engine. The value can be found and overwritten in the `KAFKA_TOPIC_PATTERN` variable.
>
> For more information, see the [Process Engine Kafka topic configuration](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka).
>
> To make a request to the Document Templates microservice, the process definition needs to include an action of type **Kafka send** defined on a [**Send Message Task**](../../../../building-blocks/node/message-send-received-task-node#send-message-task) node. The action parameter should have the key `topicName` and the corresponding topic name as its value.
>
> To receive a reply from the Document Templates microservice, the process definition needs to include a [**Receive Message Task**](../../../../building-blocks/node/message-send-received-task-node#receive-message-task) node with a node value having the key `topicName` and the topic name as its value.

Once the setup is complete, you can begin adding custom actions to your processes.

Let's explore a few examples that cover both the configuration and integration with the engine for all the use cases supported by the plugin:

> [card] [Generating documents based on templates](generating-from-html-templates)

> [card] [Uploading a new document](uploading-a-new-document)

> [card] [Converting documents to different formats](converting-documents-to-different-formats)

> [card] [Splitting a document](splitting-a-document)

> [card] [Combining files](combining-files)

> [card] [Deleting a file](deleting-a-file)

> [card] [Getting URLs to documents](getting-urls-to-documents)

> [card] [Listing stored documents](listing-stored-files)


# Encrypting and decrypting files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files

Learn how to encrypt and decrypt files using the Documents plugin via Kafka messaging.

## Overview

The Documents plugin provides file encryption and decryption capabilities through Kafka messaging. This feature allows you to:

* **Encrypt files** - Password-protect one or multiple files stored in the Documents plugin
* **Decrypt files** - Unlock password-protected files and extract contents from encrypted ZIP archives

Both operations are triggered via Kafka messages. Internal HTTP endpoints are also available for testing purposes.

### Supported file types

| Format | Extensions |
| - | - |
| PDF | `.pdf` |
| Microsoft Word | `.doc`, `.docx` |
| Microsoft Excel | `.xls`, `.xlsx` |
| ZIP | `.zip` |

> [!NOTE]
>
> When encrypting multiple files, they are automatically bundled into a password-protected ZIP archive. During decryption, ZIP archives are extracted and only files matching supported types are returned.

## Prerequisites

Before using the encryption/decryption features, ensure:

> [!TIP]
>
> The Documents plugin is deployed and configured in your environment

> [!TIP]
>
> Files are already uploaded to the Documents plugin (you'll need file IDs)

> [!TIP]
>
> Kafka topics are properly configured

## Kafka topics

The encryption and decryption operations use dedicated Kafka topics for communication between the FlowX Engine and the Documents plugin.

### Topic configuration

| Environment Variable | Default Topic Name | Direction | Description |
| - | - | - | - |
| `KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_IN` | `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Inbound | Topic for encryption requests |
| `KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_IN` | `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Inbound | Topic for decryption requests |
| `KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_OUT` | `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Outbound | Topic for encryption results |
| `KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_OUT` | `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Outbound | Topic for decryption results |

> [!TIP]
>
> To find the configured topic names in your environment:
>
> 1. Navigate to **FlowX Designer → Platform Status**
> 2. Locate **document-plugin-mngt** in the components list
> 3. Click the eye icon and expand **KafkaTopicsHealthCheckIndicator → details → configuration → topic → document**

***

## Encrypting files

Use file encryption to password-protect documents stored in the Documents plugin.

### How encryption works

1. The plugin validates that all specified file(s) exist
2. Validates that files are of supported types
3. Downloads the file(s) from storage
4. Creates a password-protected copy:
   * **Single file**: Creates an encrypted copy with a new file ID
   * **Multiple files**: Creates a ZIP archive containing all files, then password-protects the ZIP
5. Returns the file ID of the encrypted document

### Request message structure

Configure a **Send Message Task** node with a Kafka Send action to trigger file encryption.

**Topic**: Use the encryption inbound topic (e.g., `ai.flowx.plugin.document.trigger.encrypt.file.v1`)

**Request body**:

```json theme={"dark"}
{
  "fileIds": ["file-id-1", "file-id-2"],
  "password": "your-secure-password"
}
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileIds` | Array of strings | Yes | List of file IDs to encrypt (files must exist in Documents plugin) |
| `password` | String | No | Password for encryption. If null, creates an unprotected archive for multiple files |

### Response message structure

Configure a **Receive Message Task** node to receive the encryption result.

**Topic**: Use the encryption outbound topic (e.g., `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1`)

**Response body**:

```json theme={"dark"}
{
  "status": "success",
  "message": null,
  "fileId": "encrypted-file-id-123"
}
```

| Parameter | Type | Description |
| - | - | - |
| `status` | String | Operation result: `success`, `partial_success`, `error`, or `no-op` |
| `message` | String | Additional information (populated in case of errors or partial success) |
| `fileId` | String | The file ID of the newly created encrypted file |

### Example: Encrypt a single file

**1. Add a Send Message Task node**

Configure a Kafka Send action with the encryption topic and the following message body:

```json theme={"dark"}
{
  "fileIds": ["${uploadedDocument.fileId}"],
  "password": "${encryptionPassword}"
}
```

**2. Add a Receive Message Task node**

Configure the node to listen on the encryption results topic to capture the encrypted file ID.

**3. Store the encrypted file ID**

Use the response `fileId` for subsequent operations (e.g., sending via email, downloading).

***

## Decrypting files

Use file decryption to unlock password-protected documents and extract contents from encrypted archives.

### How decryption works

1. The plugin validates that the specified file exists
2. Validates that the file is of a supported type
3. Downloads the file from storage
4. Attempts to open the file:
   * First tries without a password
   * If that fails, uses the provided password
5. If the file is a ZIP archive, extracts its contents
6. Filters extracted files by supported types
7. Uploads the resulting file(s) to storage
8. Returns the file ID(s) of the decrypted/extracted files

### Request message structure

Configure a **Send Message Task** node with a Kafka Send action to trigger file decryption.

**Topic**: Use the decryption inbound topic (e.g., `ai.flowx.plugin.document.trigger.decrypt.file.v1`)

**Request body**:

```json theme={"dark"}
{
  "fileId": "encrypted-file-id-123",
  "password": "your-secure-password"
}
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | String | Yes | The file ID of the encrypted file to decrypt |
| `password` | String | No | Password for decryption. If the file is not password-protected, this can be null |

### Response message structure

Configure a **Receive Message Task** node to receive the decryption result.

**Topic**: Use the decryption outbound topic (e.g., `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1`)

**Response body**:

```json theme={"dark"}
{
  "status": "success",
  "message": null,
  "fileIds": ["decrypted-file-id-1", "decrypted-file-id-2"]
}
```

| Parameter | Type | Description |
| - | - | - |
| `status` | String | Operation result: `success`, `partial_success`, `error`, or `no-op` |
| `message` | String | Additional information (populated in case of errors or partial success) |
| `fileIds` | Array of strings | List of file IDs for the decrypted/extracted files |

> [!NOTE]
>
> When decrypting a ZIP archive, the response contains multiple file IDs—one for each extracted file that matches supported file types.

### Example: Decrypt a password-protected file

**1. Add a Send Message Task node**

Configure a Kafka Send action with the decryption topic and the following message body:

```json theme={"dark"}
{
  "fileId": "${encryptedDocument.fileId}",
  "password": "${userProvidedPassword}"
}
```

**2. Add a Receive Message Task node**

Configure the node to listen on the decryption results topic.

**3. Process the decrypted files**

The response `fileIds` array contains all successfully decrypted files. Use these IDs for further document processing.

***

## Error handling

Both encryption and decryption operations return descriptive error messages when issues occur.

### Common error scenarios

| Scenario | Status | Description |
| - | - | - |
| All files processed | `success` | All files were encrypted/decrypted successfully |
| Some files failed | `partial_success` | Some files were processed but others failed (e.g., unsupported type in a batch) |
| File not found | `error` | The specified file ID does not exist in the Documents plugin |
| Unsupported file type | `error` | The file format is not supported for encryption/decryption |
| Invalid password | `error` | The provided password is incorrect (decryption only) |
| No files to process | `no-op` | Empty file list provided or all files filtered out |

### Example error response

```json theme={"dark"}
{
  "status": "error",
  "message": "File with ID 'invalid-id-123' not found",
  "fileId": null
}
```

> [!WARNING]
>
> Always implement error handling in your process flow to gracefully manage encryption/decryption failures. Check the `status` field before proceeding with subsequent operations.

***

## Security considerations

> [card] Password handling
>
> In the current version, passwords are transmitted in clear text. Ensure your Kafka communication is secured with TLS encryption.

> [card] File storage
>
> Encrypted files are stored as new documents with unique file IDs. Original files remain unchanged.

***

## Related documentation

> [card] [Documents plugin overview](./documents-plugin-overview)
>
> Learn about all Documents plugin capabilities

> [card] [Documents plugin setup](../../../../../setup-guides/documents-plugin-setup)
>
> Configure the Documents plugin in your environment

> [card] [Uploading files](./uploading-a-new-document)
>
> Upload files to the Documents plugin before encryption

> [card] [Kafka Send action](../../../../building-blocks/actions/kafka-send-action)
>
> Configure Kafka Send actions in your process


# Generating documents
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates

Generate new documents from custom templates that can be pre-filled with data from the current process instance.

> [!NOTE]
>
> Configure document templates using the [**WYSIWYG editor**](../../../plugins/wysiwyg). Access and manage your templates through the **Document Templates** section in your Project in [**FlowX Designer**](../../../../flowx-designer/overview).

![Document template interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/docs_plugin_template.png)

## Generating documents from HTML templates

The Documents plugin generates documents from predefined templates. This guide focuses on generating documents using HTML templates.

![Document templates](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_tmplts.png)

## Before you begin

1. **Verify access permissions**: Ensure you have the necessary [permissions to manage document templates](../../../../../setup-guides/access-management/workspaces-access-rights).
2. **Check Kafka configuration**: Confirm that Kafka is properly configured and accessible:
   * The document plugin relies on Kafka for communication between nodes
   * Familiarize yourself with the required Kafka topics (detailed later in this guide)

## Creating an HTML template

1. Access the [**WYSIWYG editor**](../../../plugins/wysiwyg) through **FlowX Designer → Plugins → Document templates**
2. Create or import your HTML template

![HTML template creation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/doc_template.png)

For detailed template management instructions:

> [card] [Managing HTML templates](./managing-html-templates)

> [!TIP]
>
> For comprehensive guidance, take the FlowX.AI Academy course: [**Creating a Document Template in Designer**](https://academy.flowx.ai/module/create-document-templates-flowxai-designer).

## Implementing document generation in a process

Let's build a document generation flow that creates personalized documents based on user input:

![Document generation process example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_upload_prev_ex.png)

### Step 1: Create a user input form

1. Add a **User Task** node to your process
2. Configure UI elements to collect the information needed for your document:
   * Input fields (text, numbers, dates, etc.)
   * Make sure to set appropriate keys for each field that match your template variables

<video />

### Step 2: Configure the document generation request

1. Add a **Send Message Task (Kafka)** node
2. Configure the Kafka send action with the appropriate topic:
   * For HTML template generation, use `ai.flowx.plugin.document.trigger.generate.html.v1` (or your configured equivalent, set via `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN`)

![Kafka send action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gen_template_action.png)

> [!TIP]
>
> To find your environment's configured topics:
>
> 1. Navigate to **FlowX Designer → Platform Status**
> 2. Find the **document-plugin-mngt** component and click the eye icon
> 3. Expand `KafkaTopicsHealthCheckIndicator → details → configuration → topic → document → generate`
> 4. Look under HTML and PDF sections for your in/out topics
>
> ![Kafka topics for document generation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_topics_html_generate.png)

3. Create the request payload with the following structure:

```json theme={"dark"}
{ 
  "documentList": [
    {
      "customId": "ClientsFolder",
      "templateName": "AccountCreation",
      "language": "en",
      "data": {
        "firstInput": "${application.client.firstName}",
        "secondInput": "${application.client.lastName}",
        "thirdInput": "${application.client.accountType}"
      },
      "includeBarcode": false
    }
  ]
}
```

![Kafka send action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/gen_templ_payload.png)

Key parameters:

* **customId**: Folder name where the file will be saved
* **templateName**: Name of the template defined in Document templates
* **language**: Must match the language configured on the template
* **data**: Key-value pairs mapping template variables to process data
* **includeBarcode**: Set to true if you need a barcode on the document

> [!NOTE]
>
> When using templates in a process, the system uses default values from the default project language. For example, if English is your default project language, the template will use values from the English version.
>
> To check your default language: **FlowX Designer → Version Settings → Languages**

### Generating DOCX output

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

By default, generated documents are PDF files. To generate a DOCX file instead, add `outputFormat` to a document entry in the request payload:

```json theme={"dark"}
{
  "documentList": [
    {
      "customId": "ClientsFolder",
      "templateName": "AccountCreation",
      "language": "en",
      "outputFormat": "DOCX",
      "data": {
        "firstInput": "${application.client.firstName}"
      }
    }
  ]
}
```

* **outputFormat**: `PDF` or `DOCX`. When omitted, the document is generated as PDF.
* The generated DOCX preserves the template's styles, data, and images, and is stored and returned the same way as a PDF.
* **includeBarcode** applies to PDF output only; it is ignored when generating DOCX.

When testing a template in **FlowX Designer → Plugins → Document templates**, use the **Output format** dropdown in the test modal to download the test result as PDF or DOCX.

### Step 3: Receive the generated document

1. Add a **Receive Message Task (Kafka)** node
2. Configure it with:
   * The response topic: `ai.flowx.engine.receive.plugin.document.generate.html.results.v1` (or your configured equivalent, set via `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT`)
   * Key for storing the response: `generatedDocuments`

![Receive message configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/generate_template_receive.png)

The response contains information about the generated documents:

![HTML generation response](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/html_generated_response.png)

Sample response structure:

```json theme={"dark"}
{
  "generatedFiles": {
    "ClientsFolder": {
      "AccountCreation": {
        "customId": "ClientsFolder",
        "fileId": "320f4ec2-a509-4aa9-b049-87224594802e",
        "documentType": "AccountCreation",
        "documentLabel": "GENERATED_PDF",
        "minioPath": "{{your_bucket}}/2024/2024-01-15/process-id-865759/ClientsFolder/6869_AccountCreation.pdf",
        "downloadPath": "internal/files/320f4ec2-a509-4aa9-b049-87224594802e/download",
        "noOfPages": 1,
        "error": null
      }
    }
  },
  "error": null
}
```

Response fields:

* **fileId**: Unique identifier for the generated file
* **documentType**: Template name used for generation
* **minioPath**: Storage location (MinIO or S3)
* **downloadPath**: Download path relative to the Documents plugin base URL, for example `internal/files/{fileId}/download`. It is not a complete URL.
* **noOfPages**: Document page count
* **error**: Error information (null if successful)

### Error responses

When generation fails, `error` is populated as an object with three fields:

| Field | Description |
| - | - |
| `code` | Numeric status code: `400` for request or validation problems, `500` for rendering or storage failures |
| `message` | What went wrong |
| `timestamp` | When the error occurred (ISO-8601) |

The error appears at one of two levels, never both:

* **Request-level** (`error` at the root): the whole request was rejected before any document was processed, for example a malformed payload or an empty `documentList`. `generatedFiles` is not populated.

```json theme={"dark"}
{
  "generatedFiles": null,
  "error": {
    "code": 400,
    "message": "Document list is empty",
    "timestamp": "2026-09-14T08:31:46.512+00:00"
  }
}
```

* **Per-document** (`error` inside a `generatedFiles` entry): that document failed while the rest of the request proceeded. A missing template or failed input validation returns `400`; a rendering or storage failure returns `500`. Other documents in the same response can still succeed, so check the `error` field of each entry. The root `error` stays `null` in this case.

```json theme={"dark"}
{
  "generatedFiles": {
    "ClientsFolder": {
      "AccountCreation": {
        "customId": "ClientsFolder",
        "fileId": null,
        "documentType": "AccountCreation",
        "downloadPath": null,
        "error": {
          "code": 400,
          "message": "Template could not be found.",
          "timestamp": "2026-09-14T08:31:46.512+00:00"
        }
      }
    }
  },
  "error": null
}
```

> [!TIP]
>
> In the process, branch on the received `error` fields before using `downloadPath`: a failed document has `fileId` and `downloadPath` set to `null`, so wiring the happy path only leaves the user with a broken file preview when generation fails.

## Displaying the generated document

To display the generated document to the user:

1. Add a **Task Node** with a business rule that prefixes `downloadPath` with the Documents plugin base URL and stores the complete URL under a new key
2. Add a **User Task** with the File Preview UI Element:
   * Set its **Source Type** to **Process Data** and its key to the key that holds the complete URL

The raw `downloadPath` is relative, so File Preview can't load it on its own. For the business rule and the binding, see [Preview an uploaded file](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#preview-an-uploaded-file).

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, you can skip the business rule: set the File Preview **Source** to **Document Plugin Path** and point it at `downloadPath` directly. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13).&#x20;

On SaaS, you can also generate the document from an integration workflow with the **Template Filling** node. See [Fill a document template from a workflow and download it](/5.9/cookbooks/generate-and-download-a-document), which also shows how to build the download URL.

For detailed instructions on displaying documents, see:

> [card] [Uploading a new document](./uploading-a-new-document)


# Getting URLs
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/getting-urls-to-documents

In certain scenarios, obtaining URLs pointing to uploaded documents for use in integrations is essential. This process involves adding a custom action to your workflow that requests URLs from the Documents plugin.

## Prerequisites

Before retrieving document URLs, ensure:

1. **Access Permissions**: Ensure that the user account has the necessary access rights.

2. **Kafka Configuration**:

* **Verify Kafka Setup**: Ensure proper configuration and accessibility of the Kafka messaging system.
* **Kafka Topics**: Understand the Kafka topics used for these operations.

3. **Document Types**: Prepare information for updating or deleting files:

* `types`: A list of document types.

## Configuring the getting URLs process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls.png)

To obtain document URLs, follow these steps:

**1. Create the process**

Create a process that will contain the following types of nodes:

* [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) - used to send the get URLs request
* [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node) - used to receive the get URLs reply
* [**User Task**](../../../../building-blocks/node/user-task-node) - where you will perform the upload action

**2. Configure the User Task**

Start configuring the **User Task** node:

#### Node Config

* **Integration Output**: Add a data stream (**Source**: **Custom Topic**) with the topic where the response will be sent; in this example `ai.flowx.updates.document.html.persist.v1` and its key: `uploadedDocument`.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls1.png)

#### Actions

We will configure the following node actions:

* Upload File action ("uploadDocument") will have two child actions:
  * Send Data to User Interface ("uploadDocumentSendToInterface")
  * Business Rule ("uploadDocumentBR")
* Save Data action ("save")

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_document_actions.png)

**3. Upload action parameters**

Configure the parameters for the **Upload Action**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_action_get_urls.png)

> [!NOTE]
>
> For more details on uploading a document and configuring the file upload child actions, refer to the following sections:
>
> * [**Upload document**](./uploading-a-new-document)
> * [**Upload action**](../../../../building-blocks/actions/upload-file-action)

**4. Configure the Send Message Task**

Next, configure the **Send Message Tas (Kafka)** node by adding a **Kafka Send Action** and specifying the `..in` [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup#basic-kafka-configuration) to send the request.

> [!TIP]
>
> Identify defined topics in your environment:
>
> * Navigate to **Platform Status > FlowX Components > document-plugin-mngt**  and press the eye icon on the right side.
> * In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → document → get**. Here will find the in and out topics for getting URLs for documents.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/get_urls_kafka.png)

**5. Configure the request action**

Fill in the body of the request message for the Kafka Send action to send the get URLs request:

![Request Message](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls2.png)

* `types`: A list of document types.

#### Message request example

Example of a message following the custom integration data model:

```json theme={"dark"}
{
  "types": [
    "119435",
    "119435"
  ]
}
```

**6. Configure the Receive Message Task**

Configure the [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-receive-message-task) by adding the `..out` Kafka topic on which the response will be sent.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls3.png)

## Receiving the reply

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/doc_plugin_get_urls4.png)

The response body should include the following values:

* **success**: A boolean indicating whether the document exists and the URL was generated successfully.
* **fullName**: The full name of the document file, including the directory path.
* **fileName**: The name of the document file without the extension.
* **fileExtension**: The extension of the document file.
* **url**: The full download URL for the document.

#### Message response example

```json theme={"dark"}
[
  {
    "success": true,
    "fullName": "2024/2024-08-27/process-id-1926248/1234_1926248/7715_1926248.pdf",
    "fileName": "2024/2024-08-27/process-id-1926248/1234_1926248/7715_1926248",
    "fileExtension": "pdf",
    "url": "http://minio:9000/qualitance-dev-paperflow-devmain/2024/2024-08-27/process-id-1926248/1234_1926248/7715_1926248.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=minio%2F20240827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240827T150257Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=575333697714249e9deb295359f5ba9365f618f53303bf5583ca30a9b1c45d84"
  }
]
```


# Listing stored files
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/listing-stored-files

View files stored in S3-compatible buckets (such as MinIO or Amazon S3) using the Documents Plugin REST API.

To determine the partitioning strategy used for storing generated documents, you can access the following key in the configuration:

`application.file-storage.partition-strategy`

```yaml theme={"dark"}
application:
  defaultLocale: en
  supportedLocales: en, ro
  #fileStorageType is the configuration that activates one FileContentService implementation. Valid values: minio / fileSystem
  file-storage:
    type: s3
    disk-directory: MS_SVC_DOCUMENT
    partition-strategy: NONE

```

The `partition-strategy` property can have two possible values:

* **NONE**: Documents are saved in separate buckets for each process instance. Each process instance has its own dedicated bucket.
* **PROCESS\_DATE**: Documents are saved in a single bucket with a subfolder structure based on the process date. For example: `bucket/2022/2022-07-04/process-id-xxxx/customer-id/file.pdf`.

## REST API

The Documents Plugin provides the following REST API endpoints for interacting with the stored files:

### List buckets

> [!TIP]
>
> Check out the [**List buckets API reference**](../../../../api/storage/list-buckets) for more details.

* This endpoint returns a list of available buckets.

### List objects in a bucket

> [!TIP]
>
> Check out the [**List objects in a bucket API reference**](../../../../api/storage/list-objects-in-buckets) for more details.

* This endpoint retrieves a list of objects stored within a specific bucket. Replace `BUCKET_NAME` with the actual name of the desired bucket

### Download file

> [!TIP]
>
> Check out the [**Download file API reference**](../../../../api/storage/download-file) for more details.

* This endpoint allows you to download a file by specifying its path or key.


# Managing templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/managing-html-templates

The Documents plugin provides the flexibility to define and manage HTML templates for document generation, enabling customization through various parameter types.

Additionally, the platform incorporates a [**What You See Is What You Get (WYSIWYG)**](../../../plugins/wysiwyg) editor, allowing users to have a real-time, visual representation of the document or content during the editing process. Furthermore, you have the capability to test and review your template by downloading it as a PDF.

> [!TIP]
>
> A WYSIWYG editor, typically provides two main views:
>
> * **Design View (Visual View)**: In this view, you can see a visual representation of their content as it would appear when rendered in a web browser or other output medium. It resembles the final output closely, allowing you to format text, add images, and apply styles directly within the visual interface. This view aims to provide a real-time preview of the document's appearance.
>
> * **HTML View (Source View)**: In this view, you can see and edit the underlying HTML code that corresponds to the content displayed in the Design View. It shows the raw HTML markup, providing a more detailed and technical representation of the document. You can manually edit the HTML code to make precise adjustments or to implement features not available in the visual interface.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/wysiwyg_example.gif)

Explore the different parameter types and their specifications:

## Configuring HTML templates

In the following example, we will create an example of a template using the HTML View (Source View).

To create a document template, navigate to the **Document Templates** section in the **Designer**, select ”**New document**” from the menu in the top-right corner, name your template, and click **Create**.

Now follow the next steps to design a new template:

1. **Open the WYSIWYG editor**:

Access the WYSIWYG editor within the Document Management Plugin, found in the **FlowX Designer → Plugins → Document templates** section.

* **Language Configuration**: Create a dedicated template for each language specified in your system.

> [!TIP]
>
> To confirm the installed languages on the platform, go to **FLOWX.AI Designer → Content Management → Languages**.

2. **Design the document header**:

Begin by creating a header section for the document, including details such as the company logo and title.

```html theme={"dark"}
<!-- Source: -->
<header>
   <img src="https://d22tnnndi9lo60.cloudfront.net/devmain/flowx/flowxlogo/1669299027205_FLOWX.AI%20main%20logo.png" alt="Company Logo" width="150px" height="auto">
   <h1 th:text="${offerTitle}">Offer Document</h1>
</header>
```

Data specifications (process data):

```json theme={"dark"}
"data": {
    "companyLogo": "INSERT_BASE64_IMAGE",
    "offerTitle": "Client Offer"
}

```

3. **Text Parameters for Client Information**:

Include a section for client-specific information using text parameters.

> [!NOTE]
>
> Text parameters enable the inclusion of dynamic text in templates, allowing for personalized content.

```html theme={"dark"}
<!-- Source: -->
<section>
<h2>Client Information</h2>

<p><strong>Client Name:</strong> <span th:text="${clientName}"></span></p>

<p><strong>Client ID:</strong> <span th:text="${clientId}"></span></p>
</section>

<section>
```

Data specifications:

```json theme={"dark"}
"data": {
    "clientName": "John Doe",
    "clientId": "JD123456"
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/client_infor.png)

4. **Dynamic table for offer details:**

Create a dynamic table to showcase various details of the offer.

```html theme={"dark"}
<!-- Source: -->
<section>
<h2>Offer Details</h2>

<table>
	<thead>
		<tr>
			<th>Item</th>
			<th>Description</th>
			<th>Price</th>
		</tr>
	</thead>
	<tbody>
		<tr th:each="item : ${offerItems}">
			<td th:text="${item.name}"></td>
			<td th:text="${item.description}"></td>
			<td th:text="${item.price}"></td>
		</tr>
	</tbody>
</table>
</section>
```

Data specifications:

```json theme={"dark"}
"data": {
    "offerItems": [
        { "name": "Product A", "description": "Description A", "price": "$100" },
        { "name": "Product B", "description": "Description B", "price": "$150" },
        { "name": "Product C", "description": "Description C", "price": "$200" }
    ]
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/table_offer.png)

5. **Dynamic sections for certain conditions:**

Dynamic sections allow displaying specific content based on certain conditions. For example, you can display a paragraph only when a certain condition is met.

```html theme={"dark"}
<!-- Source: -->
<section>
<h2>Dynamic Sections for Certain Conditions</h2>
<span th:if="${isPreferredClient}"> </span>

<p><span th:if="${isPreferredClient}">This is displayed if it is a preferred client. They are eligible for special discounts!&nbsp;</span></p>
<span th:if="${isPreferredClient}"> </span> <span th:if="${hasSpecialRequest}"> </span>

<p><span th:if="${hasSpecialRequest}">This is displayed if the client has specific requests. Please review them carefully.</span></p>
<span th:if="${hasSpecialRequest}"> </span> <span th:if="${isActiveContract}"> </span>

<p><span th:if="${isActiveContract}">This is displayed if the client has an active contract with us.</span></p>
<span th:if="${isActiveContract}"> </span></section>
```

Data specifications:

```json theme={"dark"}
"data": {
    "clientName": "John Doe",
    "clientId": "JD123456",
    "isPreferredClient": false,
    "hasSpecialRequest": false,
    "isActiveContract": true
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/display_conditions.png)

6. **Lists**:

Lists are useful for displaying values from selected items in a checkbox as a bulleted list.

```html theme={"dark"}
<!-- Source: -->
<section>
<div th:if="${incomeSource != null}">
<h3>Income source:</h3>

<ul>
	<li th:each="item : ${incomeSource}" th:text="${item}"></li>
</ul>
</div>
</section>
```

Data specifications:

```json theme={"dark"}
{
    "data": {
        "incomeSource": [
            "Income 1",
            "Income 2",
            "Income 3",
            "Income 4"
        ]
    }
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/list_html.png)

7. **Include Image for Authorized Signature:**

Embed an image for the authorized signature at the end of the document.

```html theme={"dark"}
<!-- Source: -->
<footer>
<p>Authorized Signature:</p>
<img alt="Authorized Signature" height="auto" th:src="*{'data:image/png;base64,' + signature}" width="200px"></footer>
```

Data Specifications:

```json theme={"dark"}
"data": {
    "signature": "INSERT_BASE64_IMAGE"
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/authorized_sign.png)

8. **Barcodes**:

Set the `includeBarcode` parameter to true if you want to include a barcode. For information on how to use barcodes and OCR plugin, check the following section:

> [card] [OCR plugin](../../../plugins/custom-plugins/ocr-plugin)

9. **Checkboxes for Consent**:

Consent checkboxes in HTML templates are commonly used to obtain explicit agreement or permission from users before proceeding with certain actions or processing personal data.

```html theme={"dark"}
<!--Source:-->
    <section>
        <label for="consent-checkbox">
            <input type="checkbox" id="consent-checkbox" name="consent" value="consent">
            I consent to the terms and conditions.
        </label>
    </section>
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/checkbox_html.gif)

10. **Data Model**:

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

With the structured data model, the documents template **Data Model** tab is the shared structured builder. You define typed attributes (**String**, **Number**, **Boolean**, **Enum**, **Date**, **Currency**, object, or **Array**), add validations, and optionally reference data types from the **Project Data Model** or a **Library**. You then use the **Input Parameters** tab to select which attributes the template expects. At generation time the values you send in the payload are substituted for those attributes, such as first name or company name.

> [!TIP]
>
> For the full data model builder reference, see the [Project data model](/5.9/docs/building-blocks/project-data-model) documentation.

In the documents template we have the **Data Model** tab. Here you define parameters, which are dynamic data fields that will be replaced with the values you define in the payload, like first name, or company name.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/data_model_input.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/dataModelTemplate.png)

## Styling

HTML template styling plays a crucial role in enhancing the visual appeal, readability, and user experience of generated documents.

> [!WARNING]
>
> The PDF generation engine only supports **CSS 2.1**. Modern CSS features such as Flexbox, Grid, CSS variables, and advanced selectors are not supported. Ensure your styles are compatible with CSS 2.1 specifications.

We will apply the following styling to the previously created HTML template using **Source** view of the editor.

```css theme={"dark"}
	<style type="text/css">body {
            font-family: 'Arial', sans-serif;
            margin: 20px;
            color: #343a40;
        }

        header {
            text-align: center;
        }

        header img {
            width: 150px;
            height: auto;
        }

        h1 {
            color: #000; /* Adjust color as needed */
            margin-top: 10px;
        }

        h2 {
            color: #fdb913;
            margin-bottom: 10px;
            font-size: 1.2em; /* Adjust font size as needed */
        }

        p {
            margin-bottom: 10px;
            font-size: 1em; /* Adjust font size as needed */
        }

        table {
            width: 100%;
            border-collapse: collapse;
            margin-bottom: 20px;
        }

        th, td {
            border: 1px solid #ddd;
            padding: 8px;
            text-align: left;
        }

        th {
            background-color: #f2f2f2;
        }

        ul {
            list-style-type: disc;
            margin-left: 20px;
            color: #6c757d;
        }

        footer {
            margin-top: 20px;
        }
	</style>
```

In the end the template will look like this:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/manage_template_final.png)

## Samples

### Without dynamic data

The final result after generating the template without dynamic data:

> [!NOTE]
>
> Download the [PDF sample](../../../assets/HTMLExample.pdf).

### With dynamic data

The final result after generating the template with the following dummy process data:

```json theme={"dark"}
"data": {
    "offerTitle": "Client Offer",
    "clientName": "John Doe",
    "clientId": "JD123456",
    "isPreferredClient": false,
    "hasSpecialRequest": false,
    "isActiveContract": true,

    "offerItems": [
        { "name": "Product A", "description": "Description A", "price": "$100" },
        { "name": "Product B", "description": "Description B", "price": "$150" },
        { "name": "Product C", "description": "Description C", "price": "$200" },
    ],
     "incomeSource": [
            "Income 1",
            "Income 2",
            "Income 3",
            "Income 4"
        ],
}
```

> [!TIP]
>
> Download a [PDF sample](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/726_ManageHTMLTemplate%20.pdf).


# Splitting documents
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/splitting-a-document

You can split a document into multiple parts using the Documents plugin.

This guide provides step-by-step instructions on how to split a document, such as when a user uploads a bulk scanned file that needs to be separated into distinct files.

## Prerequisites

1. **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.

2. **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

* **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section)

3. Before initiating the splitting process, ensure you have the unique ID of the file in the storage solution. The system performs the splitting on an already uploaded file.

> [!TIP]
>
> Ensure that the uploaded document contains more than one file.

You have two options to obtain the file ID:

* Extract the file ID from a [**Response Message**](./uploading-a-new-document#response-message-example-1) of an upload file request. For more details, refer to the [**upload process documentation**](./uploading-a-new-document).

* Extract the file ID from a [**Response Message**](./generating-from-html-templates#step-3-receive-the-generated-document) of a generate from template request. For more details, refer to the [**document generation reply documentation**](./generating-from-html-templates).

> [!NOTE]
>
> In the following example, we will use the `fileId` generated for a document with multiple files using [**Uploading a New Document**](./uploading-a-new-document) scenario.
>
> ```json theme={"dark"}
> {
>   "customId": "119407",
>   "fileId": "446c69fb-32d2-44ba-a0b2-02dbb55e7eea",
>   "documentType": "BULK",
>   "documentLabel": null,
>   "minioPath": "flowx-dev-process-id-119407/119407/465_BULK.pdf",
>   "downloadPath": "internal/files/446c69fb-32d2-44ba-a0b2-02dbb55e7eea/download",
>   "noOfPages": null,
>   "error": null
> }
> ```

## Configuring the splitting process

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_document.png)

To create a process that splits a document into multiple parts, follow these steps:

1. Create a process that includes a [**Send Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-send-message-task) node and a [**Receive Message Task (Kafka)**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-receive-message-task) node:

* Use the **Send Message Task** node to send the splitting request.
* Use the **Receive Message Task** node to receive the splitting reply.

2. Configure the **first node (Send Message Task)** by adding a **Kafka Send Action**.

3. Specify the [**Kafka topic**](../../../../../setup-guides/documents-plugin-setup#document-splitting) where you want to send the splitting request. By default this is `ai.flowx.plugin.document.trigger.split.document.v1`, set by `KAFKA_TOPIC_DOCUMENT_SPLIT_IN`.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/kafka_split_topic.png)

> [!TIP]
>
> To identify your defined topics in your current environment, follow the next steps:
>
> 1. From the FLOWX.AI main screen, navigate to the Platform Status menu at the bottom of the left sidebar.
> 2. In the FLOWX Components list, scroll to the document-plugin-mngt line and press the eye icon on the right side.
> 3. In the details screen, expand the `KafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → document → split**. Here you will find the in and out topics for splitting documents.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/kafka_topics_split.png)

4. Fill in the body of the message request.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_kafka_action.png)

#### Message request example

```json theme={"dark"}
{
  "parts": [
    {
      "documentType": "BULK",
      "customId": "119407",
      "pagesNo": [
        1,
        2
      ],
      "shouldOverride": true
    }
  ],
  "fileId": "446c69fb-32d2-44ba-a0b2-02dbb55e7eea"
}
```

* **fileId**: The file ID of the document that will be split
* **parts**: A list containing information about the expected document parts
  * **documentType**: The document type.
  * **customId**: The unique identifier for your document (it could be for example the ID of a client)
  * **shouldOverride**: A boolean value (true or false) indicating whether to override an existing document if one with the same name already exists
  * **pagesNo**: The pages that you want to separate from the document

5. Configure the **second node (Receive Message Task)** by adding a data stream (**Integration Output** → **Add Stream**, **Source**: **Custom Topic**):

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_response_kafka.png)

> [!NOTE]
>
> The response will be sent to this `..out` Kafka topic. By default this is `ai.flowx.engine.receive.plugin.document.split.document.results.v1`, set by `KAFKA_TOPIC_DOCUMENT_SPLIT_OUT`.

## Receiving the reply

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/split_response.png)

The following values are expected in the reply body:

* **docs**: A list of documents.
  * **customId**: The unique identifier for your document (matching the name of the folder in the storage solution where the document is uploaded).
  * **fileId**: The ID of the file.
  * **documentType**: The document type.
  * **minioPath**: The storage path for the document.
  * **downloadPath**: The download path for the document.
  * **noOfPages**: The number of pages in the document.
* **error**: Any error message in case of an error during the splitting process.

Here's an example of the response JSON:

#### Message response example

```json theme={"dark"}
{
  "docs": [
    {
      "customId": "119407",
      "fileId": "c4e6f0b0-b70a-4141-993b-d304f38ec8e2",
      "documentType": "BULK",
      "documentLabel": null,
      "minioPath": "flowx-dev-process-id-119408/119407/466_BULK.pdf",
      "downloadPath": "internal/files/c4e6f0b0-b70a-4141-993b-d304f38ec8e2/download",
      "noOfPages": 2,
      "error": null
    }
  ],
  "error": null
}
```

The split document is now available in the storage solution and can be downloaded:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/2024-01-30%2013.39.35.gif)


# Creating and uploading a new document
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document

A comprehensive guide to integrating document creation from templates, managing uploads, and configuring workflows for document processing.

> [!NOTE]
>
> User task nodes provide a flexible framework to defining and configuring UI templates and actions for specific template config nodes, such as an upload file button.

![Upload and preview process with the client\_data, create\_document, receive\_reply, create\_document\_path, preview\_generated\_document, and upload\_document nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/14-docs_upload_proc.png)

## Prerequisites

Before you begin, ensure the following prerequisites are met:

* **Access Permissions**: Ensure that you have the necessary permissions to use the Documents Plugin. The user account used for these operations should have the required access rights.
* **Kafka Configuration**: Verify that the Kafka messaging system is properly configured and accessible. The Documents Plugin relies on Kafka for communication between nodes.

  * **Kafka Topics**: Familiarize yourself with the Kafka topics used for these operations (later in this section).

> [!WARNING]
>
> **Important: Document replacement behavior**
>
> When uploading a file with the **same `customId` AND `documentType` combination** as an existing document, the previous document will be automatically **marked as deleted** and replaced by the new file.
>
> This means:
>
> * The previous file's URLs will stop working
> * Only the most recent file with that `customId` + `documentType` combination will be accessible
>
> **Best practices:**
>
> * Always use **unique, dynamic values** for `customId` (e.g., `${processInstanceId}`, client ID, or a generated UUID)
> * Do not copy examples with hardcoded values like `customId: "1234"` without changing them to unique values
> * If you need to store multiple documents of the same type for the same entity, ensure each has a unique identifier
>
> ```json Example: Using dynamic values theme={"dark"}
> {
>   "customId": "${processInstanceId}",  // or use a client-specific ID
>   "documentType": "CONTRACT",
>   "tempFileId": "..."
> }
> ```

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Terminology note:** starting with FlowX.AI 5.10, the Designer UI labels this concept **Document Tag** (renamed from **Document Type**). The rename affects UI labels only — the `documentType` field in Kafka requests and responses is unchanged, and self-hosted 5.9.x deployments still show **Document Type**.

To upload a document using this process, follow the steps outlined below.

## Step-by-step guide: uploading and previewing a document

In the [Generating from HTML templates](./generating-from-html-templates) guide, you learned how to generate documents from HTML templates. This section focuses on creating a process where users can generate a document, review and sign it, and subsequently upload it.

<video />

### Process overview

This process involves several key nodes, each performing specific tasks to ensure smooth document creation, preview, and upload:

* **Start and End Nodes**: These nodes mark the beginning and end of the process, respectively.
* **User Task Node**: Collects user input necessary for document generation.
* **Send and Receive Message Tasks (Kafka)**: Handle communication with Kafka for generating the document and retrieving it after processing.
* **Service Task Node**: Appends the path of the generated document to the process, enabling further actions.
* **User Task Nodes**: Facilitate the preview of the generated document and manage the upload of the signed document.

## Configuring the process

**1. Document generation**

Follow the steps outlined in [**Generating from HTML templates**](./generating-from-html-templates) configure the document generation part of the process.

![Document generation part of the process highlighted, from client\_data to receive\_reply](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/15-doc_plugin_upload_prev_ex.png)

> [!NOTE]
>
> If you only need to upload a new file without generating it from templates, skip the template generation steps.

After configuration, your request and response messages should resemble the examples below.

#### Request message example

This JSON structure represents a Kafka message sent through the `..in` topic to initiate a request in the Process Engine. It includes information for generating an "AccountCreation" document with a custom ID "119237" in English. Data specifies client details extracted dynamically from user input (first name, last name, age, country) and company information (name, registration date).

> [!NOTE]
>
> This an example of a message that follows the custom integration data model.

```json theme={"dark"}
{
  "documentList": [
    {
      "customId": "119246", //this will match the name of the folder in the storage solution
      "templateName": "AccountCreation",
      "language": "en",
      "data": {
        "application": {
          "client": {
            "firstName": "John",
            "lastName": "Doe",
            "age": "33",
            "country": "AU"
          },
          "company": {
            "name": "ACME",
            "registrationDate": "24.01.2024"
          }
        }
      },
      "includeBarcode": false
    }
  ]
}
```

#### Response message example

This JSON structure represents the response received on the `..out` Kafka topic, where the Process Engine expects a reply. It contains details about the generated PDF file corresponding to the custom ID "119237" and the "AccountCreation" template. The response provides file-related information such as file ID, document type, document label, storage path, download path, number of pages, and any potential errors (null if none). The paths provided in the response facilitate access and download of the generated PDF file.

```json theme={"dark"}
{
  "generatedFiles": {
    "119246": {
      "AccountCreation": {
        "customId": "119246",
        "fileId": "f705ae5b-f301-4700-b594-a63b50df6854",
        "documentType": "AccountCreation",
        "documentLabel": "GENERATED_PDF",
        "minioPath": "flowx-dev-process-id-119246/119246/457_AccountCreation.pdf", // path to the document in the storage solution
        "downloadPath": "internal/files/f705ae5b-f301-4700-b594-a63b50df6854/download", //link for download
        "noOfPages": 1,
        "error": null
      }
    }
  },
  "error": null
}
```

**2. Preview document**

Configure the **preview** part of the process.

![Preview part of the process highlighted: create\_document\_path and preview\_generated\_document](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/16-preview_path.png)

#### Service task node

We will configure the service task node to construct the file path for the generated document.

Configure a business rule to construct a file path for the generated document. Ensure the base admin path is specified.

> [!TIP]
>
> File Preview uses the value at its key as-is, so the business rule must build a complete, absolute URL. The renderer attaches the user's access token only to URLs that end in `download`, which is how the `downloadPath` from the reply ends.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, File Preview can read `downloadPath` directly with **Source** set to **Document Plugin Path**, so this business rule is not needed. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13).&#x20;

#### Actions

**Action Edit**

* **Action Type**: Set to **Business Rule**
* **Trigger Type**: Choose **Automatic** because is not a user-triggered action
* **Required Type**: Set as **Mandatory**

![Business Rule action on the create\_document\_path node that builds the document file path](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/08-create_document_path.png)

**Parameters**

* **Language**: We will use **MVEL** for this example
* **Body Message**: Fill in the body message request

```js theme={"dark"}
adminPath = "https://{your-flowx-api-host}/document/";
processInstanceId = input.?generatedDocuments.?generatedFiles.keySet().toArray()[0];
downloadPath = input.?generatedDocuments.?generatedFiles.?get(processInstanceId).Company_Client_Document.downloadPath;

if(downloadPath != null){
    output.put("generatedDocuments", {
        "filePath" : adminPath + downloadPath
    });
}
```

> [accordion] Explanation of MVEL code
>
> * **adminPath**: Base URL of the Documents plugin. Replace `{your-flowx-api-host}` with the host that serves the FlowX APIs to your renderer; the Documents plugin is exposed on it under `/document`, as listed in the [ingress service route reference](/5.9/setup-guides/ingress-configuration#service-route-reference). Keep the trailing slash, because `downloadPath` is relative (for example `internal/files/{fileId}/download`).
>
> ```java theme={"dark"}
> adminPath = "https://{your-flowx-api-host}/document/";
> ```
>
> * **processInstanceId**: Extracts the process instance ID from the input. Assumes an input structure with a generatedDocuments property containing a generatedFiles property. Retrieves the keys, converts them to an array, and selects the first element.
>
> ```java theme={"dark"}
> processInstanceId = input.?generatedDocuments.?generatedFiles.keySet().toArray()[0];
> ```
>
> * **downloadPath**: Retrieves the downloadPath property using the obtained processInstanceId.
>
> ```java theme={"dark"}
> downloadPath = input.?generatedDocuments.?generatedFiles.?get(processInstanceId).Company_Client_Document.downloadPath;`
> ```
>
> * **if condition**: Checks if downloadPath is not null and constructs a new object in the output map.
>
> ```java theme={"dark"}
> if(downloadPath != null){
>     output.put("generatedDocuments", {
>         "filePath" : adminPath + downloadPath
>     });
> }
> ```

### User Task

Now we will configure the user task to preview the generated document.

#### Actions

Configure the **Actions edit** section:

* **Action Type**: Set to **Save Data**.
* **Trigger Type**: Choose **Manual** to allow user-triggered action.
* **Required Type**: Set as **Mandatory**.

![Save Data action on the preview\_generated\_document user task](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/09-document_preview_action.png)

Let's see what we have until now.

The screen where you can fill in the client details:

![Client Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_fill_data.gif)

The screen where you can preview and download the generated document:

![Preview Document](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/preview_document_vis.gif)

**3. Upload document**

Configure the user task where we will upload the signed document genereated from the previous document template.

#### Node Config

* **Swimlane**: Choose a swimlane (if multiple) to restrict access to specific user roles.
* **Stage**: Assign a stage to the node.
* **Integration Output**: Add a data stream (**Source**: **Custom Topic**) with the topic where the response will be sent; in this example the default Documents plugin persist reply topic `ai.flowx.engine.receive.plugin.document.persist.document.results.v1` and its key: `uploadedDocument`.

![upload\_document node config with a Custom Topic data stream on the persist reply topic and the key uploadedDocument](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/07-upload_document_node_config.png)

#### Actions

Configure the following node actions:

* Upload File action with two child actions:
  * Business Rule
  * Send Data to User Interface
* Save Data action

![upload\_document actions: an Upload File action with Business Rule and Send data to user interface child actions, and a Save Data action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/06-upload_document_actions.png)

#### Upload file action

This is a standard predefined FlowX Node Action for uploading files. This is done through Kafka and by using `persist` topics.

> [accordion] Configuring the File Upload action
>
> #### Action edit
>
> * **Action Type**: Set to **Upload File**.
> * **Trigger Type**: Choose **Manual** to allow user-triggered action.
> * **Required Type**: Set it as **Optional**.
> * **Repeatable**: Check this option if the action can be triggered multiple times.
>
> #### Parameters
>
> * **Topics**: Kafka topic where the file will be posted, in this example the default `ai.flowx.plugin.document.trigger.persist.document.v1`.
>
> > [!TIP]
> >
> > To identify your defined topics in your current environment, follow the next steps:
> >
> > * From the FLOWX.AI main screen, navigate to the **Platform Status** menu at the bottom of the left sidebar.
> > * In the **Services** list, scroll to the **document-plugin** line and press the eye icon on the right side.
> > * In the details screen, expand the `kafkaTopicsHealthCheckIndicator` line and then **details → configuration → topic → document → persist**. Here you'll find the in and out topics for persisting (uploading documents).
> >
> > ![document-plugin details in Platform Status, with the Kafka topics health check expanded to the document persist topics](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/kafka-topics-persist-document-plugin.png)
>
> * **Document Type**: Metadata for the document plugin, in this example `BULK`.
> * **Folder**: Configure a value by which the file will be identified, in this example it will be the`${processInstanceId}` (it will be replaced at runtime with a generated process instance id).
> * **Advanced configuration (Show headers)**: This represents a JSON value that will be sent on the headers of the Kafka message, in this example:
>
> ```json theme={"dark"}
> {"processInstanceId": ${processInstanceId}, "destinationId": "upload_document", "callbacksForAction": "uploadDocument"}`
> ```
>
> > [!TIP]
> >
> > `callbacksForAction` - the value of this key is a string that specifies a callback action associated with the "upload\_document" destination ID (node). This is part of an event-driven system (Kafka send action) where this callback will be called once the "upload\_document" action is completed.
>
> #### Data to send
>
> * **Keys**: Used when data is sent from the frontend via an action for data validation.

![Upload File action parameters with the persist topic, Document Type BULK, and Folder](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/03-upload_config_b_params.png)
![Upload File action Folder and headers with processInstanceId, destinationId, and callbacksForAction](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/03b-upload_config_b_headers.png)

> [!NOTE]
>
> When configuring the event handler that corresponds to the Upload File node action, you must set the **Action Type** to **Upload**. This ensures proper integration between the frontend interface and the backend upload functionality.
>
> ![File Upload event handler with Action Type set to Upload](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/10-ui_action_upload.png)

Now, configure the child actions of Upload File Action.

#### Business rule

This is necessary to create the path to display the uploaded document.

> [accordion] Configuring the Business Rule action
>
> **Action Edit**
>
> * **Order**: Set to **1** so it will be processed before the second child action.
> * **Action Type**: Set to **Business Rule**.
> * **Trigger Type**: Choose **Automatic**, it does not need user intervention.
> * **Required Type**: Set as **Mandatory**.
> * **Repeatable**: Check this option if the action can be triggered multiple times.
>
> **Parameters**
>
> * **Language**: In this example we will use **MVEL**.
> * **Body Message**: Fill in the body of the message request by applying a logic similar to the one utilized in configuring the "preview\_document" node. Establish a path that will be later employed to showcase the uploaded document within a preview UI component.
>
> ```js theme={"dark"}
> adminPath = "https://{your-flowx-api-host}/document/";
> downloadPath = input.?uploadedDocument.?downloadPath;
>
> if(downloadPath != null){
>     output.put("uploadedDocument", {
>         "filePath" : adminPath + downloadPath
>     });
> }
> ```
>
> The rule replaces the reply's `filePath`, which is a storage path, with the preview URL. The other keys from the reply stay as they are.

![Business Rule child action settings under the Upload File action](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/04a-upload_business_rule_a.png)
![Business Rule child action script](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/04b-upload_business_rule_b.png)

#### Send Data to User Interface

This is necessary to send the previously created information to the frontend.

> [accordion] Configuring the Send Data to User Interface action
>
> **Action Edit**
>
> * **Order**: Set to **2** so it will be processed after the previously created Business Rule.
> * **Action Type**: Set to **Send data to user interface**.
> * **Trigger Type**: Choose **Automatic**, it does not need user intervention.
> * **Required Type**: Set as **Mandatory**.
> * **Repeatable**: Check this option if the action can be triggered multiple times.
>
> **Parameters**
>
> * **Message Type**: Set to **Default**.
> * **Body Message**: Populate the body of the message request; this object will be utilized to bind it to the File Preview UI element.
>
> ```json theme={"dark"}
> {
>     "uploadedDocument": {
>         "filePath": "${uploadedDocument.filePath}"
>     }
> }
> ```
>
> * **Target Process**: Used to specify to what running process instance should this message be sent - set to **Active Process**.

![Send data to user interface child action settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/05a-send_to_UI_a.png)
![Send data to user interface child action message body](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/05b-send_to_UI_b.png)

#### Save Data

Configure the last node action to save all the data.

**Action edit**

* **Order**: Set to **3**.
* **Action Type**: Set to **Save Data**.
* **Trigger Type**: Choose **Manual** to allow user-triggered action.
* **Required Type**: Set as **Mandatory**.

#### Request message example

To initiate the document processing, a Kafka request with the following JSON payload will be sent through `..in` topic:

> [!NOTE]
>
> This an example of a message that follows the custom integration data model.

```json theme={"dark"}
{
  "tempFileId": "05081172-1f95-4ece-b2dd-1718936710f7", //a unique identifier for the temporary file
  "customId": "119246", //a custom identifier associated with the document
  "documentType": "BULK" //the type of the document 
}
```

#### Response message example

Upon successful processing, you will receive a JSON response on the `..out` topic with details about the processed document:

```json theme={"dark"}
{
  "customId": "119246",
  "fileId": "96975e03-7fba-4a03-99b0-3b30c449dfe7",
  "documentType": "BULK",
  "documentLabel": null,
  "minioPath": "flowx-dev-process-id-119246/119246/458_BULK.pdf",
  "downloadPath": "internal/files/96975e03-7fba-4a03-99b0-3b30c449dfe7/download",
  "noOfPages": null,
  "error": null
}
```

Now the screen is configured for uploading the signed document:

![Upload File](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/upload_document_signed.gif)

***

## Uploading multiple files

For the backend action configuration, see the [Upload File action](../../../../building-blocks/actions/upload-file-action) documentation. To show each uploaded file on the same user task, see [Preview files in a collection](../../../../building-blocks/ui-designer/ui-component-types/file-preview#preview-files-in-a-collection).

***

## Receiving the reply

The response, containing information about the generated and uploaded documents, is sent to the output Kafka topic defined in the Kafka Receive Event Node. The response includes details such as file IDs, document types, and storage paths.

![Process instance variables showing the upload reply, with filePath replaced by the document preview URL](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/upload-reply-variables.png)

The reply body is expected to contain the following values:

* **customId**: A custom identifier associated with the document.
* **fileId**: The ID of the file.
* **documentType**: The document type.
* **minioPath**: The path where the uploaded file is saved. It represents the location of the file in the storage system, whether it's a MinIO path or an S3 path, depending on the specific storage solution.
* **downloadPath**: The download path for the uploaded file. It specifies the location from where the file can be downloaded.
* **noOfPages**: The number of pages in the document (if applicable).
* **filePath**: The object path of the file in storage (MinIO or S3). It isn't a URL: to display the document, build a URL from `downloadPath`, as the business rule in this example does.


# Enumerations
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations

Enumerations allow you to manage a collection of predefined values that can be used within UI components or templates. These values can be tailored for specific source systems or languages.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2012.36.20.png)

## Overview

Enumerations help you standardize and manage lists of values that are displayed in your applications. Each enumeration consists of one or more values with both an internal identifier (the code) and display strings (labels) for different languages. You can also establish hierarchies by creating child collections—for example, defining states within a country.

> [!NOTE]
>
> Enumerations are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific enumeration, right-click it and select **View History**.

## User interface overview

The **Enumerations** tab is divided into the following sections:

### Header

* **New Enumeration** - Click this button to create a new enumeration.
* **Contextual Menu (three dots)** - Provides options for **Import** and **Export**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2012.53.55.png)

### Main table

* **Name** - Displays the name of each enumeration.
* **Edited At** - Indicates the last update timestamp for each enumeration.
* **View Details** - Allows you to update the enumeration name.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2012.42.36.png)

***

## Enumeration entry details

When you open an enumeration entry, define the following properties:

1. **Code** - Not displayed in the end-user interface, but used to assure value uniqueness
2. **Labels** - These are the display strings shown to end users in various languages.
3. **External source systems codes** - Specifies the corresponding codes for each external system that consumes the data. Connectors use these codes for data validation.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-29%20at%2013.14.01.png)

### Adding a new enumeration

To create a new enumeration:

1. **Open your project:**  Launch **FlowX Designer** and open your project.
2. **Access Enumerations:** Select **Enumerations** from the **CMS** tab.
3. **Name the Enumeration:** Enter a suggestive name and click **Add**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/create_new_enum.png)

### Configuring an enumeration

After creating an enumeration, add values to it by configuring:

* **Code:** A unique identifier (not visible to end-users).
* **Labels:** The display string for each language.
* **Source Systems:** The code values assigned for each external system consuming the data.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/enum_add_value.png)

> [!NOTE]
>
> You can find the list of available source systems under **Projects → Integrations → Systems**.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/systems.png)

### Creating a child collection

Enumerations can be organized hierarchically by defining child values for each entry. For example, you might define states as children under a country enumeration. Hierarchical structures enable cascading selections in the user interface; for instance, choosing a country in one dropdown can filter the states available in another.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/child_enum.png)
![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/child_enum_example.png)

### Importing/exporting an enumeration

You can import or export enumerations using the following formats:

* **ZIP**
* **CSV**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/export_import_enums.png)

> [!WARNING]
>
> Every enumeration (root or child) must contain at least one **content value** (i.e., at least one label is provided) before attempting an import or export. Remember, the term *value* here refers to the display content for end-users, not the internal code.

### Resolution across library dependencies

At runtime, enumerations are looked up by name across the project and all its library dependencies. When the same enumeration name is defined in more than one place, the value is resolved by proximity to the project — the same rule as for [substitution tags](./substitution-tags#resolution-across-library-dependencies):

1. **The project's own enumeration always wins** over one with the same name defined in any library.
2. **A direct dependency wins over a transitive one**: the definition closest to the project in the dependency tree is used.
3. **Two libraries at the same depth**: the enumeration from the library with the most recent build is used.

> [!TIP]
>
> To override an enumeration that comes from a library, define one with the same name in the project. Avoid relying on the same name in two sibling libraries — the tiebreaker depends on build recency, so the resolved enumeration can change when either library is rebuilt.

### Is there a bulk endpoint for enumerations?

No. FlowX has no public bulk endpoint for enumerations. A container app loads each enumeration with its own request, for example with the `getEnumeration` method of the Angular, Android, or iOS renderer SDK.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The React and React Native renderer SDKs batch enumeration loading on their own. Before a screen renders, they fetch every root enumeration that the screen references in a single request. Child enumerations are not part of that request: each dependent select loads its own values. There is nothing to configure.

### Enumerations example

Consider an example for **Activity Domain Companies**. You can use hierarchies to organize related domains and activities.

#### **Activity Domain Companies → Agriculture forestry and fishing:**

* **Agriculture, hunting, and related services →**

<details>
  <summary>Cultivation of non-perennial plants:</summary>

  * Cultivation of cereals (excluding rice), leguminous plants and oilseeds
  * Cultivation of rice
  * Growing of vegetables and melons, roots and tubers
  * Cultivation of tobacco
</details>

<details>
  <summary>Cultivation of plants from permanent crops:</summary>

  * Cultivation of grapes
  * Cultivation of grapes
  * Cultivation of seeds and stone fruits
  * Cultivation of oil seeds
</details>

<details>
  <summary>Animal husbandry:</summary>

  * Raising of dairy cattle
  * Raising of other cattle
  * Raising horses and other horses
</details>

* **Forestry and logging →**

<details>
  <summary>Forestry and other forestry activities:</summary>

  * Forestry and other forestry activities
</details>

<details>
  <summary>Logging:</summary>

  * Logging
</details>

<details>
  <summary>Collection of non-wood forest products from spontaneous flora:</summary>

  * Collection of non-wood forest products from spontaneous flor
</details>

* **Fisheries and aquaculture →**

<details>
  <summary>Fishing:</summary>

  * Sea fishing
  * Freshwater fishing
</details>

<details>
  <summary>Aquaculture:</summary>

  * Maritime aquaculture
  * Freshwater aquaculture
</details>

This is the output after adding all the lists/collections from above:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/enumerations_output.gif)

***

## Displaying enum labels in text components

Text components can display the human-readable **label** of an enumeration value instead of the raw code. When a data key bound to a text component references an enumeration field, the renderer automatically resolves the stored code to its corresponding label at display time.

For example, if a Select component stores the code `RO` from a "Countries" enumeration, a text component bound to the same data key displays **Romania** (the label) rather than `RO`.

Enumeration values are **prefetched** from the data model before action resolution, so label lookups happen without additional network requests at render time.

***

## Using enum labels in process logic

Label resolution happens at display time, in the renderer. Business rule scripts cannot look up an enumeration's label from its code: scripts only see the process data passed to them (`input`, `output`, `additionalData`, `instanceMetadata`) and have no access to the content management service.

To use a label in a business rule or condition, retrieve it into process data first through the CMS content retrieval Kafka flow: a Send Message Task requests the translation for one or more codes, and the paired Receive Message Task stores the response, including the `label` for each code, on a process key. Downstream business rules can then read the label from `input` like any other process data. See [Content management — Kafka integration](./content-management#kafka-integration) for the request and response structure.

> [!TIP]
>
> If the logic only needs to distinguish between values, compare the stored **code** directly — codes are stable across languages and source systems, labels are not. Retrieve labels only when the label text itself drives the logic, such as composing a message or a document.


# Media library
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/media-library

Centralized hub for managing PDFs, images, GIFs, and other media files uploaded to processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml4.png)

> [!TIP]
>
> You can also upload an image directly to the Media Library on the spot when configuring a process using the [**UI Designer**](../../../building-blocks/ui-designer/ui-designer). For more information, see the [**Image component documentation**](../../../building-blocks/ui-designer/ui-component-types/image).

> [!NOTE]
>
> Media assets are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific asset, right-click it and select **View History**.

## Uploading a new asset

To upload an asset to the Media Library, follow the next steps:

1. Open your project in **FlowX Designer**.
2. Go to **CMS** and select **Media Library**.
3. Click **Add new item** ("+" button in the top-right corner), the following details will be displayed:
   * **Upload item** - opens a local file browser
   * **Key** - the key must be unique, you cannot change it afterwards

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml7.png)

4. Click **Upload item** button and select a file from your local browser.
5. Click **Add** to upload the asset.

> [!NOTE]
>
> You can upload files in **PNG, JPEG, JPG, GIF, SVG, WebP, or PDF** format. The maximum supported file size is **25 MB** for any file type.

> [!NOTE]
>
> On upload, the platform stores the file under a **timestamp-prefixed storage name** (for example, `157439683_report.pdf` for an uploaded `report.pdf`). The prefix keeps storage names unique across uploads and is expected behavior — reference the asset by its **Key**, not by the stored file name.

## Displaying assets

You can preview all the uploaded assets by accessing the **Media Library**.

You have the following information about assets:

* Preview (thumbnail 48x48)
* Key
* Format ("-" for unknown format)
* Size
* Used as icon
* Edited at
* Edited by

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml5.png)

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.3**
>
> PDF assets in the Media Library list include an open-in-new-tab button, so you can view the full document directly from the list instead of relying on the thumbnail preview.

## Searching assets

You can search an asset by using its key (full or substring).

## Updating assets

You can replace an item on a specific key (this will not break references to process definitions). To do that, click on the asset and select \**Upload item* then click **Update**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml6.png)

### Asset descriptions

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

In a project's Media Library, the asset window has a **Description** field, up to 1,000 characters. FlowX Designer uses it as the image's alternative text in the asset preview. Assets in the workspace Media Library don't have a description.

## Icons

The Icons feature allows you to personalize the icons used in UI elements. By uploading SVG files through the Media Library and marking them, you can choose icons from the available list in the UI Designer.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml2.png)

* **Use as icon** - this will mark the SVG file as an icon and it will be displayed in the UI Designer

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml1.png)

> [!NOTE]
>
> When selecting icons in the UI Designer, only SVG files marked as icons in the Media Library will be displayed.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml3.png)

> [!NOTE]
>
> To ensure optimal visual rendering and alignment within your UI elements, it is recommended to use icons with small sizes such as: 16px, 24px, 32px.
>
> Using icons specifically designed for these sizes helps maintain consistency and ensures a visually pleasing user interface. It is advisable to select icons from icon sets that provide these size options or to resize icons proportionally to fit within these dimensions.
>
> > [!WARNING]
> >
> > Icons are displayed or rendered at their original, inherent size.

## Referencing assets in UI Designer

You have the following options when configuring image components using [UI Designer](../../../building-blocks/ui-designer/ui-designer):

* **Source Location** - here you must select **Media Library** as source location (or directly select "Upload to Media Library" button for on the spot upload)
* **Image Key**  - automatically populated with the key of the asset when selecting an asset from the Media Library

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml8.png)

> [!TIP]
>
> For more details on how to configure an image component, see the [**Image component documentation**](../../../building-blocks/ui-designer/ui-component-types/image).

## Customization

Content-specific icons pertain to the content of UI elements, such as icons for [input fields](../../../building-blocks/ui-designer/ui-component-types/form-elements/input-form-field) or [send message buttons](../../../building-blocks/ui-designer/ui-component-types/buttons). These icons are readily accessible in the [UI Designer](../../../building-blocks/ui-designer/).

![Adding icons to UI elements](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/icon_add_ui.gif)

More details on how to add icons on each element, check the sections below:

> [card] [Input element](../../../building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#visual-styling)

> [card] [Select element](../../../building-blocks/ui-designer/ui-component-types/form-elements/select-form-field)

> [card] [Buttons](../../../building-blocks/ui-designer/ui-component-types/buttons#icon-integration)

## Export and import media assets

You can export and import media assets to transfer them between projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ml9.png)

### Exporting

To export media assets:

1. Open the context menu on the Media Library list page
2. Select **Export**
3. All media assets in your project are downloaded as a ZIP file

> [!WARNING]
>
> The project Media Library export produces a **metadata-only** ZIP — the media files themselves are not bundled. The export stores each asset's storage URL, and on import FlowX fetches the files from the **source** environment's storage. If the destination environment cannot reach that storage (for example, an isolated or on-premise environment), the import fails.
>
> To transfer a project's assets **with** their files, export a project **version** or **build** and choose **Include** in the [binary files option](../../../flowx-designer/managing-a-project-flow/export-import-a-process-definition#exporting-a-project).

### Importing

To import media assets:

1. Open the context menu on the Media Library list page
2. Select **Import**
3. Select the ZIP file exported from another project or environment
4. If assets with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting asset (or use **Apply to all**):
   * **Keep both** - imports the asset as a new copy alongside the existing one
   * **Replace** - overwrites the existing asset with the imported version
   * **Skip this one** - keeps the existing asset unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.


# Forwarding notifications
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/forwarding-notifications-to-an-external-system

If the Notification service is not directly connected to an SMTP / SMS server and you want to use an external system for sending the notifications, you can use the notification plugin just to forward the notifications to your custom implementation.

### Check needed Kafka topics

You will need the name of the Kafka topics defined at the following environment variables:

* `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` - topic used to trigger the request to send a notification
* `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` - the notification will be forwarded on this topic to be handled by an external system
* `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` - topic used for sending replies after sending the notification

> [!TIP]
>
> You can check the defined topics by going to **FlowX Designer > Platform Status > notification-plugin-mngt > kafkaTopicsHealthCheckIndicator > details > configuration > topic > notification**.

### Example: send a notification from a business flow

Let's pick a simple use case. Imagine we need to send a new welcome letter when we onboard a new customer. You must follow the next steps:

1. Configure the [template](./managing-notification-templates) that you want to use for the welcome email, use the [WYSIWYG Editor](../../../plugins/wysiwyg)

> [!TIP]
>
> Make sure that the **Forward on Kafka** checkbox is ticked, so the notification will be forwarded to an external adapter.

2. Configure the data model for the template.

3. To configure a document template, first, you need to define some information stored in the [Body](../../../plugins/wysiwyg#notification-templates):

* **Type** - MAIL (for email notifications)
* ❗️**Forward on Kafka** - if this box is checked, the notification is not being sent directly by the plugin to the destination, but forwarded to another adapter
* **Language** - choose the language for your notification template
* **Subject** - enter a subject

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/notification_email.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/data_model_notif.png)

4. Use the FlowX Designer to create a process definition.
5. Add a [**Send Message Task**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-send-message-task) and a [**Receive Message Task**](../../../../building-blocks/node/message-send-received-task-node#configuring-a-receive-message-task) (one to send the request, one to receive the reply).
6. Check if the needed topic (defined at the following environment variable) is configured correctly: `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN`.
7. Add the proper configuration to the action, the Kafka topic, and the body message.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/notif_params_send.png)

> [!NOTE]
>
> **Forward on Kafka** option will forward the notification to an external adapter, make sure the needed Kafka topic for forwarding is defined/overwritten using the following environment variable: `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT`.

7. Run the process and look for the response (you can view it via the **Audit log**) or by checking the responses on the Kafka topic

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/notif_send_resp.png)

Forwarded notification example at `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` — this is the payload your external adapter consumes, with the template already rendered:

```json theme={"dark"}
{
  "type": "MAIL",
  "subject": "Welcome to FlowX!",
  "body": "<html>...rendered template content...</html>",
  "senderName": "FlowX",
  "senderEmail": "no-reply@flowx.ai",
  "recipients": [
    "john.doe@mail.com"
  ],
  "ccRecipients": null,
  "bccRecipients": null,
  "creationDate": "2026-07-08T10:15:30",
  "guid": "d3b07384-d9a0-4c9b-8f6e-1a2b3c4d5e6f",
  "attachments": []
}
```

Response example at `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT`:

```json theme={"dark"}
{
  "status": "SUCCESS",
  "errorMessage": null,
  "identifier": null,
  "templateName": "welcomeLetter",
  "language": "en"
}
```


# Managing notification templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates

You can create and manage notification templates using FlowX.AI Designer by accessing the dedicated section.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templates.png)

### Configuring a template

To configure a notification template, first, you need to select some information stored in the **Body**:

1. **Type** - could be either MAIL or SMS notifications
2. **Email Server** - select the email delivery method (available for MAIL type):
   * **Predefined Email Connection** (default) - send emails directly through a configured SMTP server using the [Send Notification](../../../../building-blocks/actions/send-notification-action) action
   * **Forward on Kafka** - forward the notification to Kafka for the Notifications Plugin or an [external adapter](./forwarding-notifications-to-an-external-system) to handle (this is mandatory for SMS notification templates)
3. **Email Sender** - displayed only when **Email Server** is set to **Predefined Email Connection**:
   * **Default Server** (default) - uses the default SMTP connection configured at the environment level
   * Or select a specific [Email Sender](../../../integrations/email-sender) data source configured in Integration Designer
4. **Language** - choose the language for your notification template
5. **Subject** - enter a subject

> [!NOTE]
>
> You can edit the content for each language you have defined in the project.

![Notification template](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templ_ex.png)

#### Editing the content

You can edit the content of a notification template by using the [WYSIWYG](../../../plugins/wysiwyg) editor embedded in the body of the notification templates body.

### Configuring the data model

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

With the structured data model, the notification template editor has two tabs. On the **Data Model** tab you build typed data types and attributes with the same builder used across FlowX, then use the **Input Parameters** tab to choose which attributes the template expects at send time.

On the **Data Model** tab you can:

* Add typed attributes. Supported types are **String**, **Number**, **Boolean**, **Enum**, **Date**, **Currency**, **New Data type** (a nested object you define inline), **Existing Data Type** (an object you reference), and **Array**.
* Add validations to an attribute (for example min, max, length, or pattern).
* Mark an attribute as **Sensitive data** or **Use in Reporting**.
* Reference data types from the **Project Data Model** or from a **Library**, instead of redefining them.

On the **Input Parameters** tab, select the Data Model attributes the template needs. These become the values you supply when the template is filled. The tab lists only attributes you have defined on the Data Model.

> [!TIP]
>
> For the full data model builder reference (data types, attribute paths, referenced types, validations, and reporting or sensitive-data settings), see the [Project data model](/5.9/docs/building-blocks/project-data-model) documentation.

Using the **Data model** tab, you can define key pair values (parameters) that will be displayed and reused in the editor. Multiple parameters can be added:

* STRING
* NUMBER
* BOOLEAN
* OBJECT
* OBJECT\_REF
* ARRAY
* ARRAY\_REF
* ENUM

![Data model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_template_dm.png)

After you defined some parameters in the **Data Model** tab, you can type "**#**" in the editor to trigger a dropdown where you can choose which one you want to use/reuse.

The dropdown inserts a Thymeleaf placeholder for the selected key:

```html theme={"dark"}
<span th:text="${customer.firstName}">#customer.firstName</span>
```

The Notifications plugin renders the body with Thymeleaf, so only Thymeleaf expressions are replaced at send time. A plain `${customer.firstName}` typed into the body is sent as literal text. If you write the body in the **Source** tab, use the `th:text` form above, and pass each key in the `data` object of the send request (see [Using dynamic keys](./sending-a-notification#using-dynamic-keys)).

![Data model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templ_dm.gif)

> [card] [WYSIWYG Editor](/5.9/docs/platform-deep-dive/plugins/wysiwyg)

### Testing the template

You can use the test function to ensure that your template configuration is working as it should before publishing it.

<video />

The test modal includes the following fields:

* **Receivers emails** — recipient email addresses for the test
* **Language** — select the template language to test
* **Attachments** — upload files to test attachment handling
* **Template data** — provide values for template variables
* **Advanced** (hidden section) — **Sender Name** and **Sender Email** overrides

> [!WARNING]
>
> If some keys (marked as mandatory) are not used in the template, the test will not go through.

### Other actions

When opening the contextual menu (accessible by clicking on the breadcrumbs button), you have multiple actions to work with the notifications templates:

* **Configure** - edit the template
* **Export template** - export a template as a ZIP file
* **Audit log** - view the audit log
* **Copy to another project/library** - copy a template to another project/library
* **Duplicate** - duplicate a template
* **Delete** - delete a template

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_templ_menu.png)

***

### Export and import

You can export and import notification templates to transfer them between projects or environments (for example, from development to UAT to production).

#### Exporting a template

To export a notification template:

1. Open the contextual menu (breadcrumbs button) for the template you want to export
2. Select **Export template**
3. The template is downloaded as a ZIP file

#### Importing templates

To import notification templates:

1. Navigate to the **Notification Templates** list
2. Open the context menu and select **Import from ZIP**
3. Select the ZIP file exported from another project or environment
4. If templates with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting template (or use **Apply to all**):
   * **Keep both** - imports the template as a new copy alongside the existing one
   * **Replace** - overwrites the existing template with the imported version
   * **Skip this one** - keeps the existing template unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.


# Notification Templates
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview

You can add Notification Templates to your custom FlowX.AI deployment. The plugin will **enhance the core platform capabilities with functionality specific to sending various notifications**.

The Notification Templates feature offers the following features:

* Email notifications
* SMS templates to mobile devices

> [!NOTE]
>
> To use the Notification Templates feature to send notifications, via SMS channel, a third party provider for SMS communication is needed, for example, [Twilio](https://www.twilio.com/).

* Forward custom notifications to external outgoing services
* Generate and validate OTP passwords for user identity verification

You can also use the Notification Templates feature to track what notifications have been sent and to whom.

Let's go through the steps needed to deploy and set up the Notification Templates feature:

## Using Notification Templates

After deploying the Notification Templates feature in your infrastructure, you can start sending notifications by configuring related actions in your **process definitions**.

Before adding the corresponding **actions** in your process definition, you will need to follow a few steps:

* make sure all prerequisites are prepared, for example, the [notification templates](./managing-notification-templates) you want to use
* the database is configured properly
* for each **Kafka** event type, you will need two Kafka topics:
  * one for the request sent from the FlowX Engine to the Notification Templates feature
  * one for the corresponding reply

> [card] [Kafka configuration for Notifications plugin](../../../../../setup-guides/notifications-plugin-setup#kafka-configuration)
>
> **DEVELOPER**

> [!NOTE]
>
> The topic names configured for the plugin should match the ones used when configuring the engine and when adding plugin-related process actions:
>
> * FlowX Engine is listening for messages on topics with names of a certain pattern, make sure to use an outgoing topic name that matches the pattern configured in the Engine
>
> For more information, see the [Kafka configuration guide](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka).
>
> * to make a request to the plugin, the process definition needs to have an action of type `Kafka send` that has an action parameter with key `topicName` and the needed topic name as a value
> * to receive a reply from the plugin, the process definition needs to have a receiving node with a node value with key `topicName` and the topic name as the value

After all the setup is in place, you can start adding custom actions to the processes.

Let's go through a few examples. These examples cover both the configuration part, and the integration with the engine for all the use cases.

> [card] [Managing notification templates](managing-notification-templates)

> [card] [Send a notification](sending-a-notification)

> [card] [Send an email with attachements](sending-an-email-with-attachments)

> [card] [Forward notifications to an external system](forwarding-notifications-to-an-external-system)

> [card] [OTP flow](otp-flow)


# Generate OTP
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/generate-otp

There are some cases when you will need to generate an OTP (One Time Password) from a business flow, for example when validating an email account.

The notifications plugin handles both the actual OTP code generation and sending the code to the user using a defined [notification template](../managing-notification-templates).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/otp_archi.png)

## Define needed Kafka topics

> [!NOTE]
>
> **DEVELOPER**: Kafka topic names can be set/found by using the following environment variables in your Notifications plugin deployment:
>
> * `KAFKA_TOPIC_OTP_GENERATE_IN` — the OTP generate request is sent on this topic. **Default:** `ai.flowx.plugin.notification.trigger.generate.otp.v1`
> * `KAFKA_TOPIC_OTP_GENERATE_OUT` — after the OTP is generated and sent to the user, the response is sent back to the Engine on this topic. **Default:** `ai.flowx.engine.receive.plugin.notification.generate.otp.results.v1`

> [!NOTE]
>
> The Engine is listening for messages on topics with names of a certain pattern, make sure to use an outgoing topic name that matches the pattern configured in the Engine.

## Request to generate an OTP

Send the request on the `KAFKA_TOPIC_OTP_GENERATE_IN` topic. The body holds the following values:

| Field | Description |
| - | - |
| `processInstanceId` | Process instance ID |
| `templateName` | Name of the [notification template](../managing-notification-templates) used to send the code |
| `language` | Template language to use, for example `en` |
| `channel` | Notification channel: `MAIL`, `SMS`, or `PUSH` |
| `clientId` | Business identifier of the client (for example, the SSN) |
| `recipient` | Notification receiver: email address or phone number |
| `data` | Parameters substituted into the notification template (for example, `name`) |

```json theme={"dark"}
{
  "processInstanceId": 1994,
  "templateName": "your_otp_mail_template",
  "language": "en",
  "channel": "MAIL",
  "clientId": "1871201460101",
  "recipient": "john.doe@example.com",
  "data": {
    "name": "John"
  }
}
```

> [!NOTE]
>
> You don't send the OTP code yourself. The plugin generates it and automatically injects it into the template data under the reserved key **`otpValue`** before rendering — see [Notification template](#notification-template) below.

> [!WARNING]
>
> The `contentParams` field is deprecated. Use `data` instead.

## Notification template

The OTP code is delivered using a notification template created in **Content Management** → **Notification Templates**. In the template **Body**, reference the generated code with the `#otpValue` placeholder (this maps to `${otpValue}` in the **Source** view):

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otpTemplate_example_notif_template.png)

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The OTP request and response contract is unchanged: `otpValue` stays reserved and is still added automatically by the plugin. In the upcoming structured data model, you declare the attributes the template expects as typed data model attributes on the **Data Model** tab, then expose them on the **Input Parameters** tab. `otpValue` still holds the generated code; any other attributes (such as `name`) are still taken from the `data` object in the request.

In the template **Data model**, declare the parameters the template expects. `otpValue` holds the generated code; any other parameters (such as `name`) are taken from the `data` object in the request:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otpTemplate_example_notif_data_model-template.png)

> [!TIP]
>
> You never pass `otpValue` in the request — the plugin adds it automatically. The number of digits in the code is controlled by the `FLOWX_OTP_LENGTH` environment variable (**default:** `4`).

## Response from generate OTP

The response is sent back to the Engine on the `KAFKA_TOPIC_OTP_GENERATE_OUT` topic. The reply body holds the following values:

| Field | Description |
| - | - |
| `processInstanceId` | Process instance ID |
| `clientId` | Client identifier |
| `channel` | Notification channel used |
| `otpSent` | Confirmation whether the notification was sent: `true` or `false` |
| `error` | Error description, if any (otherwise `null`) |

```json theme={"dark"}
{
  "processInstanceId": 1994,
  "clientId": "1871201460101",
  "channel": "MAIL",
  "otpSent": true,
  "error": null
}
```

## Example: generate an OTP from a business flow

This example uses a simple process with a **Kafka send** node (to request the OTP) and a **Kafka receive** node (to capture the response):

Identify the business identifier you will use to validate the OTP (for example, a user identification number).

1. Configure the notification template that you want to use (for example, a `MAIL` template).
2. Make sure the Kafka communication through the `KAFKA_TOPIC_OTP_GENERATE_IN` topic (send the OTP request) and the topic used to receive the response (`KAFKA_TOPIC_OTP_GENERATE_OUT`) is defined properly.

> [!TIP]
>
> You can check the defined topics by going to **FlowX Designer** → **Platform Status** → **notification-plugin-mngt** → **kafkaTopicsHealthCheckIndicator** → **details** → **configuration** → **topic** → **otp**.

3. Add a **Kafka send** action to the correct node in the process definition. Set the topic to `KAFKA_TOPIC_OTP_GENERATE_IN` and configure the message body:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otp_generate_kafka_action_config.png)

4. Add a **Kafka receive** node and configure the process key where the response is stored (for example, `otpResult`).

5. When the process runs, the response lands on that key, confirming the OTP was sent:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/otp_response_example_on_kafka.png)

6. The recipient receives the OTP code rendered from the notification template:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/email_received_example.png)


# Handling OTP
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/otp-flow

The notifications plugin can also be used for handling the one time password (OTP) generation and validation flow.

The flow is made of two steps, the OTP generation and the OTP validation.

### OTP Configuration

The desired character size and expiration time of the generated one-time-passwords can also be configured using the following environment variables:

* `FLOWX_OTP_LENGTH` — number of digits in the generated code. **Default:** `4`
* `FLOWX_OTP_EXPIRETIMEINSECONDS` — how long the OTP stays valid, in seconds. **Default:** `6000`

Let's go through the examples for both steps:

> [card] [Generate OTP](generate-otp)

> [card] [Validate OTP](validate-otp)


# Validate OTP
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/otp-flow/validate-otp

Validate one-time passwords (OTP) sent via SMS or email using the Notifications Plugin Kafka integration.

## Define needed Kafka topics

Kafka topic names can be set by using environment variables:

* `KAFKA_TOPIC_OTP_VALIDATE_IN` - the event sent on this topic (with an OTP and an identifier) will check if the OTP is valid
* `KAFKA_TOPIC_OTP_VALIDATE_OUT` - the response for this request will validate an OTP, the reply is sent back to the Engine on this topic

> [!TIP]
>
> You can check the defined topics by going to **FlowX Designer > Platform Status > notification-plugin-mngt > kafkaTopicsHealthCheckIndicator > details > configuration > topic > otp**.

> [!NOTE]
>
> The Engine is listening for messages on topics with names of a certain pattern, make sure to use an outgoing topic name that matches the pattern configured in the Engine.

## Request to validate an OTP

Values expected in the request body:

* **processInstanceId** = process instance ID
* **client id** = the user unique ID in the system
* **channel** = notification channel: SMS/MAIL
* **otp** = OTP code that you received, used to compare with the one that was sent from the system

Example:

```json theme={"dark"}
{ 
    "processInstanceId": 12345, 
    "clientId": "1871201460101", 
    "channel": "MAIL", 
    "otp": "1111" 
}
```

### Reply from validate OTP

The response is sent back to the Engine on the `KAFKA_TOPIC_OTP_VALIDATE_OUT` topic. The reply body holds the following values:

| Field | Description |
| - | - |
| `processInstanceId` | Process instance ID |
| `clientId` | The user unique ID in the system |
| `channel` | Notification channel used |
| `otpValid` | Confirmation whether the provided OTP code matched the one sent from the system: `true` or `false` |

```json theme={"dark"}
{
  "processInstanceId": 12345,
  "clientId": "1871201460101",
  "channel": "MAIL",
  "otpValid": true
}
```

## Example: validate an OTP from a business flow

Similar to the generation of the OTP you can validate the OTP that was generated for an identifier.

1. Check that the needed topics are configured correctly: (`KAFKA_TOPIC_OTP_VALIDATE_IN` and `KAFKA_TOPIC_OTP_VALIDATE_OUT`)
2. Add the actions for sending the request to validate the OTP on the node that contains the 'Generate OTP' actions
3. Add the proper configuration to the action, the Kafka topic and configure the body message.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/validate_otp_temp.png)

4. Add a node to the process definition (for the [Receive Message Task](../../../../../building-blocks/node/message-send-received-task-node#receive-message-task))
5. Configure on what key you want to receive the response on the process instance parameters

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/validate_otp3.png)


# Sending a notification
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification

Learn how to configure and implement notification functionality in your business processes using the FlowX.AI Notifications Plugin.

The FlowX.AI Notifications Plugin enables you to send various types of notifications such as emails and SMS messages. This document explains how to integrate notification functionality into your business processes.

> [!NOTE]
>
> For **new processes** that send email, use the [Send Notification action](../../../../building-blocks/actions/send-notification-action). It builds the same request from typed fields and your data mapping, so you don't write the payload by hand. This page covers the Kafka-based approach, which remains supported for existing flows and for cases where you need to craft the payload yourself.

## Configuring the notification process

To configure a business process that sends notifications, follow these steps:

1. Create or edit a [notification template](./managing-notification-templates) in **FlowX Designer**
2. Design your BPMN process in **Process Designer** with:
   * A [send message task](../../../../building-blocks/node/message-send-received-task-node#send-message-task)
   * A [receive message task](../../../../building-blocks/node/message-send-received-task-node#receive-message-task)
3. Configure required [node actions](../../../../building-blocks/actions/actions)
4. Set up the request body parameters

> [!NOTE]
>
> The notification process uses Send message task/receive message task nodes to manage communication between components.

The diagram below shows how the notification system integrates with your business processes:

![Notification architecture diagram](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/notification_archi_send.png)

> [!TIP]
>
> **DEVELOPER NOTE**: Ensure that Kafka topics are properly configured in your environment by setting these variables:
>
> * `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` (default: `ai.flowx.plugin.notification.trigger.send.notification.v1`) - Topic for notification requests
> * `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` (default: `ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1`) - Topic for notification responses

## Send notification request body parameters

Your notification request must include these parameters:

| Key | Definition | |
| :-: | :-: | :-: |
| templateName | The name of the notification template to use | Mandatory |
| receivers | Notification recipients: email addresses or phone numbers | Mandatory |
| ccReceivers | Notification CC recipients: email addresses | Optional |
| bccReceivers | Notification BCC recipients: email addresses | Optional |
| language | The language code of the template to use (e.g., "en", "fr") | Mandatory |
| subject | Notification subject, overriding the template's own | Optional |
| data | Parameters for filling the template with dynamic content | Optional |
| senderEmail | Email address of the notification sender | Optional |
| senderName | Name of the notification sender | Optional |
| attachments | Files to attach to the notification (only for MAIL notifications) | Optional |

> [!NOTE]
>
> The notification channel (SMS or email) is not part of the request — it comes from the **Type** configured on the notification template itself. The older `contentParams` key is still accepted for template parameters but is deprecated; use `data`.

### Using dynamic keys

Notifications support dynamic keys (placeholders) that allow for personalized content:

* Dynamic keys use the syntax `${...}` to insert data from the process context
* The system fetches corresponding values from the specified data path
* This approach eliminates hardcoding and supports personalized content
* Example: `${application.client.firstName}` retrieves and displays the client's first name

```json Request Example with Dynamic Content theme={"dark"}
{
  "templateName": "ClientRelationshipEmailConfirmation",
  "receivers": [
    "${application.client.email}"
  ],
  "language": "en",
  "data": {
    "firstInputClient": "${application.client.firstName}"
  },
  "attachments": [
    {
      "path": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.minioPath}",
      "filename": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.documentType}.pdf"
    }
  ]
}
```

## Implementation example

Let's implement a welcome email notification for new customer onboarding.

**1. Create a notification template**

First, create and configure your welcome email template. See [Managing notification templates](./managing-notification-templates) for detailed instructions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/welcomeLetter_template.gif)

With notification templates, you can:

* Set up subjects and body content with a WYSIWYG editor
* Add dynamic fields using the data model to include recipient-specific information
* Define multiple language versions of the same template
* Configure notification types and delivery channels

**2. Design the BPMN process**

Inside your project, create a process definition with:

* A [User Task](../../../../building-blocks/node/user-task-node) to capture the recipient's email address and other user inputs if needed
* A [**Send Message Task**](../../../../building-blocks/node/message-send-received-task-node#send-message-task)
* A [**Receive Message Task**](../../../../building-blocks/node/message-send-received-task-node#receive-message-task)

This pattern enables asynchronous notification handling through Kafka messaging.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_notification_bpmn.png)

**3. Configure the send message task**

On the send message task, add a Kafka send action with the following settings:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/kafka_send_action_notif.png)

* **Topics**:
  * Use the value from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` environment variable
  * Example (in our case): `flowx-notifications-devmain`

> [!TIP]
>
> To find defined topics in your environment:
>
> 1. Navigate to **FlowX Designer > Platform Status**
> 2. Select **notification-plugin-mngt**
> 3. Open **kafkaTopicsHealthCheckIndicator > details > configuration > topic > notifications**
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notification_internal_in_topi.png)

* **Message** (expected parameters):
  * templateName (string)
  * language (string)
  * receivers (array) - usually extracted from process context but also can be a static value
* **Can include**: `data` (object) for dynamic content, `attachments` (array) for emails

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_send_parameters.png)

**4. Configure the receive message task**

* On the receive message task, add a data stream where you will receive the confirmation that the notification was sent:
  * **Topic Name**:
    * Use the value from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` environment variable
    * Example (in our case): `ai.flowx.updates.devmain.notification.request.v1`

To add a data stream, follow the steps below:

1. On your **Receive Message Task** node, click on the **Node Config** tab.
2. Then under **Integration Output** click **Add Stream**.
3. Set the **Source** to **Custom Topic** and enter the topic name from the `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` environment variable.
4. Add a **Key Name** where you will see the response added to the process instance.
5. Click **Save**.

> [!NOTE]
>
> To find the corresponding topic name in your environment follow the same steps as in the [previous step](#configure-the-send-message-task)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/receive_notification_node.png)

**5. Run and verify the process**

Execute the process and verify the results by:

* Checking the audit log
* Checking the process instance status
* Monitoring responses on the `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` topic

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notification_sent.png)

When successful, you'll receive a response on the `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` topic similar to this:

```json Response Example theme={"dark"}
{
  "identifier": null,
  "templateName": "welcomeLetter",
  "language": "en",
  "error": null
}
```

## Integration with document generation

You can enhance your notifications by attaching dynamically generated documents. To accomplish this:

Set up document templates using the Document Plugin
Generate documents in your process before sending the notification
Reference the generated documents in the notification request using dynamic keys:

```json theme={"dark"}
"attachments": [  
  {
    "path": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.minioPath}",
    "filename": "${generatedDocuments.generatedFiles.1234.ClientRelationshipDetails.documentType}.pdf"
  }
]
```

This integration creates a complete communication flow where personalized documents are automatically generated and sent to recipients.

## Troubleshooting

> [accordion] Missing Kafka topics
>
> Ensure that all required Kafka topics are properly configured in your environment variables. Check the Platform Status screen for confirmation that topics are available and accessible.

> [accordion] Notification not received
>
> Verify that the receiver information is correct and that your template is properly configured. Check the audit log for any error messages in the notification response.

> [accordion] Template rendering issues
>
> If your notification is sent but doesn't display properly, check that all template variables are correctly defined and that the `data` values in your request match the expected template variables.

> [accordion] Dynamic key not resolving
>
> If a dynamic key isn't displaying the expected value, verify the path is correct and that the data exists in the process context. Dynamic keys are case-sensitive and must match the exact path to the data.

> [accordion] Attachment problems
>
> For issues with attachments, ensure the document was successfully generated and stored before attempting to attach it. Check that the path and filename are correctly specified in the attachment configuration.


# Sending an email
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-an-email-with-attachments

To use the notification plugin for sending emails with attachments, you must define the same topic configuration as for sending regular notifications. A notification template must be created, and the corresponding Kafka topics must be defined.

> [!TIP]
>
> Before proceeding, make sure you understand [how to send basic notifications](./sending-a-notification).

> [!NOTE]
>
> For **new processes**, use the [Send Notification action](../../../../building-blocks/actions/send-notification-action) instead. It provides typed configuration fields and validation, and runs through the same notification backend. This Kafka-based guide is preserved for existing flows and advanced cases where the payload must be hand-crafted.

## Overview

This guide explains how to send emails with document attachments through the notification plugin. You'll learn how to:

* Configure email templates with dynamic content
* Reference generated documents as attachments
* Implement the complete email notification flow in your processes

## Prerequisites

1. A configured notification template (see [Managing notification templates](./managing-notification-templates))
2. Properly defined Kafka topics for the notification plugin
3. Files to attach (such as generated documents or uploaded files)

## Implementing email notifications with attachments

Let's walk through a common scenario: sending a customer a copy of their account details document via email.

![Email notification process flow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_an_email.png)

> [card] [Document Generation](../documents-plugin/generating-from-html-templates)
>
> If you need to generate the document first, see the document generation guide.

### Understanding document references

When you generate a document, as explained in the [Generating documents](../documents-plugin/generating-from-html-templates) guide, you need to reference two key pieces of information:

1. **minioPath**: The storage location of the generated document
2. **documentType**: The type identifier used to create the attachment filename

These values are stored in the process instance with the following structure:

```
generatedDocuments.generatedFiles.{{customId}}.{{templateName}}.minioPath
generatedDocuments.generatedFiles.{{customId}}.{{templateName}}.documentType
```

For example, if your document generation used:

* customId: "ClientsFolder"
* templateName: "AccountCreation"

The paths would be:

```json theme={"dark"}
...
  "attachments": [
    {
      "path": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.minioPath}",
      "filename": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.documentType}.pdf"
    }
  ]
```

> [!TIP]
>
> You can verify these values in the process instance details:
>
> ![Process instance details showing document paths](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/generate_doc_template_first.png)

### Step-by-step implementation

**1. Prepare your email template (notification template)**

Configure the template you'll use for the email:

* Define subject line, body text, and placeholders for dynamic content
* Set proper HTML formatting if needed
* Test the template to ensure it displays correctly

![Email template example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/email_template.png)

See [Managing notification templates](./managing-notification-templates) for detailed instructions.

**2. Verify Kafka topic configuration**

Confirm that the required Kafka topics are properly defined:

1. Navigate to **FlowX Designer → Platform Status**
2. Select **notification-plugin-mngt**
3. Expand **kafkaTopicsHealthCheckIndicator → details → configuration → topic → notification → internal**
4. Verify that the input and output topics for email notifications are listed

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/notif_kafka_topics.png)

**3. Add a Send Message Task (Kafka) and Receive Message Task (Kafka)**

In your process definition:

1. Open the process definition in your project in FlowX Designer
2. Add a [Send Message Task (Kafka)](../../../../building-blocks/node/message-send-received-task-node#send-message-task) after the document generation step
3. Add a [Receive Message Task (Kafka)](../../../../building-blocks/node/message-send-received-task-node#receive-message-task) after the Send Message Task

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_an_email_bpmn.png)

**4. Configure the email request payload (Send Message Task)**

On the Send Message Task, add a Kafka send action, add the corresponding Kafka topic and create the JSON payload containing all information needed for the email:

```json theme={"dark"}
{
  "templateName": "accountDetails",
  "receivers": ["something@email.com"],
  "language": "en",
  "data": {
    "firstInput": "${application.client.firstName}",
    "secondInput": "${application.client.lastName}"
  },
  "attachments": [
    {
      "path": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.minioPath}",
      "filename": "${generatedDocuments.generatedFiles.ClientsFolder.AccountCreation.documentType}.pdf"
    }
  ]
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/send_email_node.png)

Key parameters:

* **templateName**: The name of your configured email template
* **language**: The language code matching your template's language version
* **receivers**: Array of email addresses (can use process data variables)
* **ccReceivers**: Array of email addresses to be added as CC (can use process data variables)
* **bccReceivers**: Array of email addresses to be added as BCC (can use process data variables)
* **data**: Values to replace template placeholders (the older `contentParams` key is still accepted but deprecated)
* **attachments**: Array of files to attach, with filename and minioPath/storage path

**5. Configure the email success handler (Receive Message Task)**

On the Receive Message Task, add a Kafka receive action, add the corresponding Kafka topic and configure the node with the following properties:

* Go to **Node config** tab
* Under **Integration Output**, add a data stream (**Add Stream**) and set its **Source** to **Custom Topic**
* Add the topic name
* Click **Save**

![Kafka receive action configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-15%20at%2017.56.57.png)

**6. Run the process**

Run the process and check the result in the process instance details:

![Process instance details showing email success](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/result_send_email.png)

## Request payload reference

### Required fields

| Field | Description | Example |
| - | - | - |
| templateName | The unique identifier of your email template | "accountDetails" |
| language | Language code (must match a template language) | "en" |
| receivers | List of email addresses to receive the message | \["[customer@example.com](mailto:customer@example.com)"] |

### Optional fields

| Field | Description | Example |
| - | - | - |
| data | Key-value pairs for template variable replacement (the older `contentParams` key is still accepted but deprecated) | `{"firstName": "John"}` |
| attachments | List of files to attach to the email | See below |

### Attachment structure

Each attachment requires:

```json theme={"dark"}
{
  "path": "${path.to.file.in.storage}",
  "filename": "desired_filename.extension"
}
```

* **path**: References the storage location (usually a MinIO path from document generation)
* **filename**: The name recipients will see for the attached file (can include process variables)

## Testing and troubleshooting

After configuring your email notification:

1. Verify that variables resolve correctly in the template and attachment references
2. Check email delivery to test recipients
3. Review notification plugin logs if issues occur

### Common issues

| Problem | Solution |
| - | - |
| Email not received | Verify template name, receiver address, and SMTP configuration |
| Missing attachment | Check that the MinIO path is correct and the file exists |
| Template errors | Ensure all variables in template have corresponding values in `data` |
| Variable resolution | Confirm process variables use the correct path (check in process instance view) |

For further assistance, check the notification plugin logs in your environment.


# Substitution tags
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/content-management/substitution-tags

Substitution tags are used to generate dynamic content across the platform. As **enumerations**, substitution tags can be defined for each language set for the solution.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/substitution_tags.png)

> [!NOTE]
>
> Substitution tags are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific substitution tag, right-click it and select **View History**.

On the main screen inside **Substitution tags**, you have the following elements:

* **Key**
* **Values** - strings that are used in the end-user interface, according to the language set for the generated solution
* **Edit** - button used to edit substitution tags
* **Delete** - button used to delete substitution tags
* **New value** - button used to add a new substitution tag
* **Breadcrumbs menu** - access import, export, and other bulk actions
* **Search by** - search function used to easily look for a particular substitution tag

### Export and import

You can export and import substitution tags to transfer them between projects or environments.

#### Exporting

1. Open the breadcrumbs menu on the Substitution Tags list page
2. Select **Export** and choose the format:
   * **to JSON** - exports as a ZIP file containing JSON data
   * **to CSV** - exports as a CSV file

#### Importing

1. Open the breadcrumbs menu on the Substitution Tags list page
2. Select **Import** and choose the format:
   * **from ZIP** - import from a ZIP file exported from another environment
   * **from CSV** - import from a CSV file for bulk operations
3. Select the file to import
4. If substitution tags with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting tag (or use **Apply to all**):
   * **Keep both** - imports the tag as a new copy alongside the existing one
   * **Replace** - overwrites the existing tag with the imported version
   * **Skip this one** - keeps the existing tag unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

### Adding new substitution tags

To add a new substitution tag, follow the next steps.

1. Open your project in **FlowX Designer** and go to **CMS**.
2. Select **Substitution Tags**.
3. Click **New value**.
4. Fill in the necessary details:
   * Key
   * Languages
5. Click **Add** after you finish.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/add_new_substitution.png)

> [!NOTE]
>
> When working with substitution tags or other elements that imply values from other languages defined in the CMS, when running a **process**, the default values extracted will be the ones marked by the default language.

### Using substitution tags in a container app

All substitution tags are retrieved by the renderer [**SDK**](../../../../sdks/sdks-overview) before the first process starts - fetched for the current language, then cached and reused on subsequent process starts. Reference a tag from UI content with the `@@` prefix (for example, `@@myTagKey`). Starting with FlowX.AI 5.9.4, a reference that doesn't match any tag in the catalog renders as empty text, or as the platform's built-in default text for system (`sys_*`) tags. Earlier 5.9.x releases render the bare key text.

The functions for reading a tag value programmatically (in custom components or the container app) belong to each renderer SDK - see the SDK reference for your platform:

> [card] [React renderer](../../../../sdks/react-renderer#getsubstitutiontag)
>
> `getSubstitutionTag` in the Utility API

> [card] [iOS renderer](../../../../sdks/ios-renderer#getting-a-substitution-tag-value-by-key)
>
> `getTag(withKey:)`

> [card] [Angular renderer](../../../../sdks/angular-renderer)
>
> Localization utilities

> [card] [React Native renderer](../../../../sdks/react-native-renderer)
>
> Localization utilities

### How do I mix substitution tags with text on SaaS?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, write a tag as `${tag:key}`, for example `${tag:sys_ok}`. A tag can sit anywhere in the text, next to static text and process data placeholders, and one text can hold several tags: with the tag `greeting` = `Hello` and `firstName` = `John` in the process data, `${tag:greeting}, ${firstName}!` renders as "Hello, John!". Tags resolve in the display text of UI components (labels, placeholders, helper texts, titles, messages, and accessibility labels), in validator messages, and in option labels.

* **`@@key` still works** when it's the whole value of a property, but use `${tag:key}` for new content. `@@` never worked inside a longer text: `@@greeting ${firstName}` renders as empty text. Rewrite it as `${tag:greeting} ${firstName}`.
* **Missing keys render as empty text**, including system (`sys_*`) tags, with no fallback to built-in English text.
* **Existing references are converted.** On the move to FlowX.AI 6.0, whole-value `@@key` references in processes, UI flows, and reusable templates are rewritten to `${tag:key}`, and the text users see doesn't change. Option values, the default value of choice components, text that isn't one whole tag, and keys containing `{`, `}`, or `:` stay as `@@key`.
* **Option values stay `@@key`.** Don't put `${tag:key}` in an option value.
* **Task Manager** treats a column value that is exactly `${tag:key}` the same as `@@key`.
* **Moving projects between SaaS and 5.9:** importing from 5.9 converts whole-value `@@key` to `${tag:key}`. Exporting for 5.9 converts whole-value `${tag:key}` back to `@@key`, and text that mixes a tag with other content is exported as written, where 5.9 doesn't resolve the tag.

### Resolution across library dependencies

At runtime, substitution tags from the project and all its library dependencies are merged into a single set. When the same tag key is defined in more than one place, the value is resolved by proximity to the project:

1. **The project's own tag always wins** over a tag with the same key defined in any library.
2. **A tag from a direct dependency wins over one from a transitive dependency**: the definition closest to the project in the dependency tree is used.
3. **Two libraries at the same depth**: the tag from the library with the most recent build is used.

> [!TIP]
>
> The project-wins rule is the reliable way to override a tag that comes from a library: define the same key in the project. Avoid relying on the same key in two sibling libraries — the tiebreaker depends on build recency, so the resolved value can change when either library is rebuilt.

## Task Management localization

Substitution tags are essential for localizing Task Management interfaces. FlowX.AI provides **51 system substitution tags** (prefixed with `sys_tm_*`) specifically for Task Management localization:

* Table columns (title, stage, assignee, status, priority)
* Process states (created, started, finished, etc.)
* Task actions (assign, hold, unassign, execute)
* Bulk operations
* History events and comments
* User selection dialogs

How system tags resolve:

* `sys_tm_*` tags live in the **same global substitution-tag catalog** as your own tags - the prefix does not create a separate scope. Task Manager screens reference them by default, but any component that accepts a substitution tag resolves a `@@sys_tm_*` reference the same way.
* Resolution happens in the **renderer**, not on the server: the backend sends the raw `@@sys_tm_*` reference (for example, as a task-view column name) and the SDK substitutes the localized value at render time. Starting with FlowX.AI 5.9.4, a `@@sys_tm_*` reference with no value in the catalog renders the platform's built-in default text, or empty text when there is no default; earlier 5.9.x releases render the bare key text.
* To change the wording or add translations, edit the tag values in the CMS like any other substitution tag - see the localization guide linked below. Some history tags contain runtime placeholders (for example, `${user}` in "user created this task") that the renderer fills in per event.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The `sys_` prefix is now reserved for system substitution tags: creating a custom substitution tag whose key starts with `sys_` is rejected. Editing the **values** of existing system tags, for wording or translations, works the same as before.

> [!NOTE]
>
> `sys_tm_*` is one of several system tag families shipped with the platform - others cover chat surfaces (`sys_chat_*`), accessibility labels (`sys_a11y_*`), error messages (`sys_error_*`), and generic UI labels such as `sys_close` and `sys_cancel`. All follow the same catalog and resolution rules.

> [card] [Task Management Localization](../task-management/task-management-localization)
>
> Complete guide to localizing Task Management with all 51 substitution tags. Table grid localization is automatic.


# FlowX.AI Scheduler
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/scheduler

The Scheduler is part of the core extensions of the FlowX.AI platform. You can add it to your custom FlowX deployment to enhance the core platform capabilities with functionality specific to scheduling messages.

The service offers the possibility to schedule a message that you only need to process after a configured time period.

It can be quickly deployed on the chosen infrastructure and then connected to the **FlowX.AI Engine** through Kafka events.

## Using the scheduler

After deploying the scheduler service in your infrastructure, you can start using it to schedule messages that you need to process at a later time.

One such example would be to use the scheduler service to expire processes that were started but haven't been finished.

> [!WARNING]
>
> First you need to check the configured Kafka topics match the ones configured in the engine deployment.

> [!TIP]
>
> For example the engine topics `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_SET` and `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_STOP` **must** be the same with the ones configured in the scheduler at `KAFKA_TOPIC_SCHEDULE_IN_SET` and `KAFKA_TOPIC_SCHEDULE_IN_STOP` environment variables.

When a process is scheduled to expire, the engine sends the following message to the scheduler service (on the topic `KAFKA_TOPIC_SCHEDULE_IN_SET`):

```json theme={"dark"}
{
  "applicationName": "onboarding",
  "applicationId": "04f82408-ee66-4c68-8162-b693b06bba00",
  "payload": {
    "scheduledEventType": "EXPIRE_PROCESS",
    "processInstanceUuid": "04f82408-ee66-4c68-8162-b693b06bba00"
  },
  "scheduledTime": 1621412209.353327,
  "responseTopicName": "ai.flowx.process.expire.staging"
}
```

The scheduled time should be defined as `java.time.Instant`.

At the scheduled time, the payload will be sent back to the response topic defined in the message, like so:

```json theme={"dark"}
{
  "scheduledEventType": "EXPIRE_PROCESS",
  "processInstanceUuid": "04f82408-ee66-4c68-8162-b693b06bba00"
}
```

If you don't need the scheduled message anymore, you can discard it by sending the following message (on the topic `KAFKA_TOPIC_SCHEDULE_IN_STOP`)

```json theme={"dark"}
{
  "applicationName": "onboarding",
  "applicationId": "04f82408-ee66-4c68-8162-b693b06bba00"
}
```

These fields, `applicationName` and `applicationId` are used to uniquely identify a scheduled message.

> [card] [Scheduler setup](../../../setup-guides/scheduler-setup-guide)
>
> Steps to deploy and set up the service


# FlowX.AI Data Search
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/search-data-service

Search for specific data across process instances using Elasticsearch-powered indexing for fast, precise results.

![Data Search Service Overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/data_search_ov.png)

The Data Search service enables you to find specific data across process instances within your FlowX.AI platform. It uses Elasticsearch to perform fast, indexed searches across process data.

> [card] [Simple Search](#3-configure-search-parameters)
>
> Search by a single field and value

> [card] [Advanced Search](#3-configure-search-parameters)
>
> Search using multiple criteria simultaneously

> [card] [Array Search](#3-configure-search-parameters)
>
> Search within array elements and nested structures

> [card] [Cross-Application](#3-configure-search-parameters)
>
> Search across multiple applications

> [card] [Date Filtering](#3-configure-search-parameters)
>
> Filter results by process creation dates

## Prerequisites

Before using the Data Search service, ensure you have:

> [accordion] Elasticsearch Configuration
>
> * Elasticsearch cluster running and accessible
> * Indexing enabled in FlowX Engine configuration
> * Proper network connectivity between services

> [accordion] Kafka Topics
>
> * `KAFKA_TOPIC_DATA_SEARCH_IN` configured for requests
> * `KAFKA_TOPIC_DATA_SEARCH_OUT` configured for responses
> * Proper topic permissions and access

> [accordion] Process Data
>
> * Process instances with indexed data
> * Searchable fields defined in Process Settings → Data Search
> * **"Update data search" flag enabled** on at least one node to trigger indexing
> * Completed process instances for reliable results

***

## Quick start

**1. Set up your data process**

Create a process that stores searchable data and configure field indexing.

**2. Create a search process**

Build a process with Kafka Send/Receive actions for search functionality.

**3. Configure search parameters**

Define your search criteria using simple, advanced, or array search syntax.

**4. Handle search results**

Process the returned data and display results to users.

### 1. Set up your data process

First, create a process that contains searchable data. Add a Service Task with a business rule:

```json Example Client Data theme={"dark"}
output.put("application", {
  "client": {
    "personalInfo": {
      "firstName": "Sarah",
      "lastName": "Johnson", 
      "email": "sarah.johnson@techcorp.com",
      "phone": "+1-555-0101"
    },
    "address": {
      "country": "USA",
      "city": "San Francisco", 
      "state": "California",
      "zipCode": "94102"
    },
    "business": {
      "company": "TechCorp Inc",
      "industry": "Technology",
      "position": "CTO"
    },
    "account": {
      "type": "Premium",
      "status": "Active",
      "riskLevel": "Low"
    }
  }
});
```

```json Example Client List Data theme={"dark"}
output.put("application", {
  "listClient": [
    {
      "firstName": "Maria",
      "lastName": "Rodriguez",
      "email": "maria.rodriguez@company.com",
      "department": "Engineering"
    },
    {
      "firstName": "John",
      "lastName": "Smith", 
      "email": "john.smith@company.com",
      "department": "Sales"
    },
    {
      "firstName": "Maria",
      "lastName": "Garcia",
      "email": "maria.garcia@company.com", 
      "department": "Marketing"
    }
  ]
});
```

![Process Data Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/payload_process_add.png)

> [!WARNING]
>
> **Critical Step**: After creating your data structure, you must configure field indexing in **Process Settings → Data Search** for the search to work.

#### Configure field Indexing

Navigate to **Process Settings → Data Search** and add the field paths you want to search:

![Index Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/index_keys.png)

**Example indexed fields:**

* `application.client.personalInfo.firstName`
* `application.client.personalInfo.lastName`
* `application.client.personalInfo.email`
* `application.listClient` (array — all fields of every element are indexed automatically)

> [!WARNING]
>
> **Array fields**: index the array path itself (e.g. `application.listClient`) — do **not** use `[]` notation in Process Settings. A key like `application.listClient.[].firstName` cannot be resolved and silently indexes nothing — no error is shown. The `[]` notation is used only in search requests.
>
> Indexing an array indexes all fields of every element. You cannot index a subset of an array's fields directly — if you need only some fields (or want to keep the index small), build a slimmed copy of the array in a business rule (e.g. `application.listClientSearch` containing only the searchable fields) and index that key instead.
>
> Every indexed field of every array element counts toward Elasticsearch's nested-objects-per-document limit (10,000 by default). Indexing very large arrays will fail — index a slim projection or scalar summary keys instead.

#### When data gets indexed to Elasticsearch

> [!WARNING]
>
> **Critical**: Configuring field indexing in Process Settings is only the first step. Your data will **not** be automatically indexed to Elasticsearch just because the process finishes.

Data indexing to Elasticsearch occurs **only** in these specific scenarios:

| Trigger | What Gets Indexed |
| - | - |
| **Stage changes** | All configured indexed fields |
| **Swimlane changes** | All configured indexed fields |
| **"Update data search" flag enabled on a node** | All configured indexed fields |
| **Process status changes** (STARTED → FINISHED, etc.) | Only the process status, **not** the data fields |

> [!NOTE]
>
> When a process instance changes status (e.g., from STARTED to FINISHED), only the status itself is updated in Elasticsearch. The actual data fields you configured for indexing are **not** automatically re-indexed at this point.

#### Enable the "Update data search" flag

To ensure your data is indexed and searchable, you must enable the **Update data search** flag on at least one node in your process:

1. Open a node in your process definition
2. Go to **Node Config**
3. Enable the **Update data search** toggle

**Best practices for flag placement:**

* **For final data only**: Place the flag on the last node before process completion
* **For milestone tracking**: Place the flag at key checkpoints where you need searchable snapshots
* **You don't need to enable it on every node**; only enable it where you need the data to be indexed

> [!TIP]
>
> If you only need to search the final process data, enable "Update data search" on just the last node before the End Event. This minimizes unnecessary Elasticsearch updates while ensuring your completed data is searchable.

### 2. Create your search process

Create a new process with a **Send Message Task**:

![Search Process Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/search_topic_action.png)

**Configuration:**

* **Action Type**: Kafka Send Action
* **Topic**: `KAFKA_TOPIC_DATA_SEARCH_IN`

### 3. Configure search parameters

Choose your search approach based on your needs:

> [tab] Simple Search
>
> Use when searching by a single field:
>
> ```json theme={"dark"}
> {
>   "searchKey": "application.client.personalInfo.lastName",
>   "value": "Johnson",
>   "processDefinitionNames": ["client_process"],
>   "states": ["FINISHED"]
> }
> ```
>
> ![Simple Search Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/simple_search_payload.png)

> [tab] Advanced Search
>
> Use when searching by multiple criteria (AND logic):
>
> ```json theme={"dark"}
> {
>   "searchKeys": [
>     {"key": "application.client.personalInfo.firstName", "value": "Sarah"},
>     {"key": "application.client.personalInfo.lastName", "value": "Johnson"}
>   ],
>   "processDefinitionNames": ["client_process"],
>   "states": ["FINISHED"]
> }
> ```
>
> > [!NOTE]
> >
> > All conditions in `searchKeys` must match for a result to be returned.

> [tab] Array Search
>
> Use when searching within arrays or lists. Use `searchKeys` with `[]` array notation in the field path:
>
> ```json theme={"dark"}
> {
>   "searchKeys": [
>     {"key": "application.listClient.[].firstName", "value": "Maria"}
>   ],
>   "processDefinitionNames": ["client_process"],
>   "states": ["FINISHED"]
> }
> ```
>
> **Combined array search (multiple conditions in array):**
>
> ```json theme={"dark"}
> {
>   "searchKeys": [
>     {"key": "application.listClient.[].firstName", "value": "Maria"},
>     {"key": "application.listClient.[].department", "value": "Engineering"}
>   ],
>   "processDefinitionNames": ["client_process"]
> }
> ```
>
> > [!NOTE]
> >
> > * Use `[]` notation to search within array elements
> > * This searches through all items in the array
> > * Returns processes where any array element matches the criteria

> [tab] Cross-Application
>
> Search across multiple applications:
>
> ```json theme={"dark"}
> {
>   "searchKey": "application.client.account.type",
>   "value": "Premium",
>   "applicationIds": [
>     "app-1-uuid",
>     "app-2-uuid"
>   ]
> }
> ```

> [tab] Date Filtering
>
> Filter by process creation dates:
>
> ```json theme={"dark"}
> {
>   "searchKey": "application.client.business.industry",
>   "value": "Technology",
>   "processStartDateAfter": "2024-01-01T00:00:00Z",
>   "processStartDateBefore": "2024-12-31T23:59:59Z",
>   "states": ["FINISHED"]
> }
> ```

### 4. Handle search results

Add a **Receive Message Task** with:

* **Data Stream**: `KAFKA_TOPIC_DATA_SEARCH_OUT`

![Receive Search Results](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/receive_data_search.png)

**Success response example:**

![Search Results](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/result_simple.png)

```json Success Response theme={"dark"}
{
  "result": [
    {
      "processInstanceUUID": "b743ac99-4029-4b93-9ac3-4a45b4a62673",
      "state": "FINISHED",
      "processStartDate": "2025-05-28T12:18:50.532Z",
      "data": {
        "application": {
          "client": {
            "personalInfo": {
              "firstName": "Sarah",
              "lastName": "Johnson"
            }
          }
        }
      }
    }
  ],
  "tooManyResults": false,
  "success": true
}
```

```json Array Search Response theme={"dark"}
{
  "result": [
    {
      "processInstanceUUID": "c854bd10-5140-5c04-0bd4-5b56c5b73784",
      "state": "FINISHED", 
      "processStartDate": "2025-05-28T14:22:15.847Z",
      "data": {
        "application": {
          "listClient": [
            {
              "firstName": "Maria",
              "lastName": "Rodriguez",
              "email": "maria.rodriguez@company.com",
              "department": "Engineering"
            },
            {
              "firstName": "Maria", 
              "lastName": "Garcia",
              "email": "maria.garcia@company.com",
              "department": "Marketing"
            }
          ]
        }
      }
    }
  ],
  "tooManyResults": false,
  "success": true
}
```

```json No Results Response theme={"dark"}
{
  "result": [],
  "searchKey": "application.client.personalInfo.lastName",
  "searchValue": "Smith",
  "tooManyResults": false,
  "success": true
}
```

## Search parameters reference

### Quick reference table

| Parameter | Type | Mandatory | Description | Example |
| - | - | - | - | - |
| `searchKey` | String | Yes | Single field path to search | `"application.client.personalInfo.lastName"` |
| `value` | String | Yes | Value to search for (with searchKey) | `"Johnson"` |
| `searchKeys` | Array | Yes (if multiple fields) | Multiple field-value pairs (AND logic); use `[]` notation for array search | `[{"key": "list.[].field", "value": "val"}]` |
| `processDefinitionNames` | Array | Yes | Limit to specific processes | `["client_onboarding"]` |
| `applicationIds` | Array | No | Search across applications | `["uuid-1", "uuid-2"]` |
| `states` | Array | No | Filter by process states | `["FINISHED", "STARTED"]` |
| `processStartDateAfter` | String | No | Include processes after date | `"2024-01-01T00:00:00Z"` |
| `processStartDateBefore` | String | No | Include processes before date | `"2024-12-31T23:59:59Z"` |

### Basic search parameters

> [accordion] searchKey (String)
>
> **Purpose**: The field path to search in for single-field searches.
>
> **Usage**: Use dot notation to specify the exact path to the field you want to search or a specific key in the payload.
>
> **Examples**:
>
> * `"application.client.personalInfo.firstName"`
> * `"application.client.address.city"`
> * `"application.client.business.industry"`
>
> **Important**: This field must be indexed in Process Settings → Data Search to work.
>
> > [!WARNING]
> >
> > Cannot be used together with `searchKeys`. Choose one approach.

> [accordion] value (String)
>
> **Purpose**: The exact value to search for when using `searchKey`.
>
> **Usage**: Must match the stored value exactly (case-sensitive).
>
> **Examples**:
>
> * `"Johnson"` - searches for exact lastName match
> * `"Technology"` - searches for exact industry match
> * `"Active"` - searches for exact status match
>
> **Note**: Only used with `searchKey`, not with `searchKeys`.

> [accordion] searchKeys (Array)
>
> **Purpose**: Array of key-value pairs for multi-field searches with AND logic.
>
> **Usage**: All conditions must match for a result to be returned. Can also be used for array searches with `[]` notation.
>
> **Format**:
>
> ```json theme={"dark"}
> [
>   {"key": "field.path.1", "value": "value1"},
>   {"key": "field.path.2", "value": "value2"}
> ]
> ```
>
> **Examples**:
>
> ```json theme={"dark"}
> [
>   {"key": "application.client.personalInfo.firstName", "value": "Sarah"},
>   {"key": "application.client.business.industry", "value": "Technology"}
> ]
> ```
>
> **Array Search Example**:
>
> ```json theme={"dark"}
> [
>   {"key": "application.listClient.[].firstName", "value": "Maria"}
> ]
> ```
>
> **Nested Array Example**:
>
> ```json theme={"dark"}
> [
>   {"key": "application.clients.[].addresses.[].city", "value": "New York"}
> ]
> ```
>
> > [!NOTE]
> >
> > * Returns processes where any array element matches the criteria
> > * Supports deeply nested array structures
>
> > [!WARNING]
> >
> > Cannot be used together with `searchKey`. Choose one approach.

### Filtering parameters

> [accordion] processDefinitionNames (Array)
>
> **Purpose**: Limit search to specific process definitions.
>
> **Default**: Searches all processes if omitted.
>
> **Usage**: Improves performance by narrowing search scope.
>
> **Examples**:
>
> * `["client_onboarding"]` - search only in client processes
> * `["employee_registration", "contractor_onboarding"]` - search in multiple process types
>
> **Best Practice**: Always specify to improve search performance.

> [accordion] applicationIds (Array)
>
> **Purpose**: Search across specific applications.
>
> **Default**: Searches current application if omitted.
>
> **Usage**: Enable cross-application searches.
>
> **Examples**:
>
> * `["8dd20844-2dc5-4445-83a5-bbbcc82bed5f"]` - search in specific app
> * `["app-1-uuid", "app-2-uuid", "app-3-uuid"]` - search across multiple apps
>
> **Use Case**: Useful for consolidated reporting across different business units.

> [accordion] states (Array)
>
> **Purpose**: Filter results by process instance status.
>
> **Default**: Returns all states if omitted.
>
> **Available States**:
>
> * `"CREATED"` - Process instance created but not started
> * `"STARTED"` - Process is currently running
> * `"FINISHED"` - Process completed successfully
> * `"FAILED"` - Process encountered an error and stopped
> * `"TERMINATED"` - Process was manually stopped/cancelled
> * `"ONHOLD"` - Process is paused or waiting for external input
>
> **Examples**:
>
> * `["FINISHED"]` - only completed processes
> * `["STARTED", "ONHOLD"]` - active or paused processes
> * `["FAILED", "TERMINATED"]` - processes that didn't complete normally
>
> **Best Practice**: Use `["FINISHED"]` for most business searches to get complete data.

### Date range parameters

> [accordion] processStartDateAfter (String)
>
> **Purpose**: Include only processes started after the specified date.
>
> **Format**: ISO 8601 timestamp (`YYYY-MM-DDTHH:MM:SSZ`)
>
> **Examples**:
>
> * `"2024-01-01T00:00:00Z"` - processes started after Jan 1, 2024
> * `"2024-06-15T09:30:00Z"` - processes started after June 15, 2024 at 9:30 AM
>
> **Use Cases**:
>
> * Monthly reports: `"2024-03-01T00:00:00Z"`
> * Recent activity: `"2024-05-20T00:00:00Z"`

> [accordion] processStartDateBefore (String)
>
> **Purpose**: Include only processes started before the specified date.
>
> **Format**: ISO 8601 timestamp (`YYYY-MM-DDTHH:MM:SSZ`)
>
> **Examples**:
>
> * `"2024-12-31T23:59:59Z"` - processes started before end of 2024
> * `"2024-06-30T23:59:59Z"` - processes started before end of June 2024
>
> **Use Cases**:
>
> * Historical analysis: `"2024-01-01T00:00:00Z"`
> * Quarterly reports: `"2024-03-31T23:59:59Z"`

### Process states explained

Understanding process states is crucial for effective searching:

| State | Description | When to Use |
| - | - | - |
| **CREATED** | Process instance exists but hasn't started execution | Rarely used for business searches |
| **STARTED** | Process is actively running | Find ongoing processes, current workload |
| **FINISHED** | Process completed successfully | Most common for business data searches |
| **FAILED** | Process encountered an error | Error analysis, troubleshooting |
| **TERMINATED** | Process was manually cancelled | Audit trails, cancelled applications |
| **ONHOLD** | Process is paused/waiting | Active cases needing attention |

> [!NOTE]
>
> **Recommendation**: Use `["FINISHED"]` for most business searches to ensure you're getting complete, reliable data.

### Response structure

The search returns a JSON object with these fields:

* **`result`** (Array): List of matching process instances
  * `processInstanceUUID`: Unique process identifier
  * `state`: Current process state
  * `processStartDate`: When the process started
  * `data`: The actual process data with your searchable fields
* **`tooManyResults`** (Boolean): True if more than 50 results found (limit applied)
* **`success`** (Boolean): Whether the search completed successfully
* **`errorMessage`** (String): Error details if search failed

## Use cases & examples

> [card] HR employee lookup
>
> Search for employees by department, position, or location across HR systems.

> [card] Compliance Auditing
>
> Locate specific transactions or approvals for regulatory compliance.

> [card] Business Intelligence
>
> Analyze process data patterns and generate reports.

> [card] Multi-contact Search
>
> Find processes containing specific individuals within contact lists or arrays.

### Real-world example: Employee directory search

**1. HR needs to find employees**

HR department needs to find all employees named "Maria" across different departments.

**2. Search within employee arrays**

```json theme={"dark"}
{
  "searchKeys": [
    {"key": "application.employees.[].firstName", "value": "Maria"}
  ],
  "processDefinitionNames": ["employee_onboarding"],
  "states": ["FINISHED"]
}
```

**3. Get comprehensive results**

Receive all employee records containing anyone named "Maria" in their employee lists.

**4. Refine search if needed**

Add additional criteria like department or role to narrow results further.

### Real-world example: Customer support search

**1. Customer calls with issue**

Support agent needs to find customer's account quickly.

**2. Search by multiple criteria**

```json theme={"dark"}
{
  "searchKeys": [
    {"key": "customer.email", "value": "customer@email.com"},
    {"key": "customer.status", "value": "Active"}
  ],
  "processDefinitionNames": ["customer_onboarding"],
  "states": ["FINISHED"]
}
```

**3. Get comprehensive results**

Receive full customer profile with account details, order history, and support tickets.

**4. Resolve customer issue**

Use the retrieved data to address the customer's concern effectively.

***

## Best practices

> [accordion] Indexing Strategy
>
> * **Always enable "Update data search"** on at least one node to trigger data indexing
> * **If you don't have stages or swimlanes configured**, the "Update data search" flag is your **only way** to index data - without it, your data fields won't be searchable
> * **Place the flag strategically**: on the last node for final data, or at milestones for intermediate snapshots
> * **Don't enable on every node**: this creates unnecessary Elasticsearch updates
> * **Remember**: Process status changes (like finishing) only update the status in Elasticsearch, not your data fields
> * **For long processes**, consider enabling at key checkpoints to make data searchable earlier

> [accordion] Array Search Optimization
>
> * **Use `[]` path notation** in `searchKeys` for array searches (e.g. `application.listClient.[].firstName`)
> * **Index array fields by their array path** (e.g. `application.listClient`) in Process Settings — `[]` notation is used only in search requests
> * **Consider array size** - large arrays may impact search performance
> * **Combine array searches** with filters to reduce result sets
> * **Test nested array searches** thoroughly before deploying to production

> [accordion] Performance optimization
>
> * **Limit search scope** using `processDefinitionNames` and `states`
> * **Use date ranges** for time-sensitive searches
> * **Index only frequently searched fields** to reduce storage overhead
> * **Monitor search response times** and optimize queries
> * **Avoid wildcard searches** on large datasets

> [accordion] Data Modeling
>
> * **Use consistent field naming** across processes
> * **Normalize data formats** (dates, phone numbers, etc.)
> * **Consider search patterns** when designing data structures
> * **Document indexed fields** for team reference
> * **Plan for data growth** and scaling needs
> * **Design arrays with search in mind** - consider what fields will be searched

> [accordion] Security & Compliance
>
> * **Don't index sensitive data** (SSN, passwords, etc.)
> * **Implement proper access controls** for search endpoints
> * **Log search activities** for audit trails
> * **Sanitize search inputs** to prevent injection attacks
> * **Follow data retention policies** for search results

> [accordion] Error Handling
>
> * **Handle empty results** gracefully in your UI
> * **Implement retry logic** for failed searches
> * **Provide meaningful error messages** to users
> * **Set reasonable timeouts** for search operations
> * **Monitor and alert** on search failures

***

## Troubleshooting

> [accordion] No Search Results
>
> **Possible Causes:**
>
> * **"Update data search" flag not enabled** on any node (most common cause)
> * Fields not indexed in Process Settings → Data Search
> * Incorrect field path (case-sensitive)
> * Process instances not in expected state
> * Elasticsearch indexing delay
> * Array notation missing for array searches
>
> **Solutions:**
>
> * **Enable "Update data search"** on at least one node (typically the last node before completion)
> * Verify field indexing configuration in Process Settings → Data Search
> * Check exact field paths in process data
> * Ensure processes are in FINISHED state
> * Wait 30-60 seconds after process completion
> * Use `[]` notation for array field searches

> [accordion] Data Not Indexed Despite Process Completion
>
> **Possible Causes:**
>
> * "Update data search" flag not enabled on any node
> * Misunderstanding of when indexing occurs (status changes only update the status, not data)
> * Data added after the last node with the flag enabled
>
> **Solutions:**
>
> * Enable "Update data search" on the last node before the End Event
> * Remember: process status changes (STARTED → FINISHED) only index the status, not your data fields
> * Place the "Update data search" flag after all data has been collected
> * For milestone-based indexing, enable the flag at each checkpoint where you need searchable data

> [accordion] Array Search Issues
>
> **Possible Causes:**
>
> * Missing `[]` notation in field path
> * Array fields not properly indexed
> * Sending unsupported parameters (only `searchKey`/`value` and `searchKeys` are accepted)
> * Array is empty or doesn't contain expected data
>
> **Solutions:**
>
> * Ensure field path includes `[]` for arrays (e.g., `list.[].field`)
> * Verify array fields are indexed by their array path (e.g. `application.listClient`), not `[]` notation — index keys containing `[]` silently index nothing
> * Check that arrays contain the expected data structure
> * Test with simple array structures first

> [accordion] Search Timeout Errors
>
> **Possible Causes:**
>
> * Query too broad (searching all data)
> * Elasticsearch cluster performance issues
> * Large dataset without proper filtering
> * Complex nested array searches
>
> **Solutions:**
>
> * Add more specific filters (`processDefinitionNames`, `states`)
> * Use date ranges to limit scope
> * Check Elasticsearch cluster health
> * Optimize indexing strategy
> * Simplify complex array search patterns

> [accordion] Invalid Search Key Errors
>
> **Possible Causes:**
>
> * Typos in field paths
> * Field doesn't exist in process data
> * Incorrect JSON format in request
> * Missing array notation for array fields
>
> **Solutions:**
>
> * Verify field paths exist in process instances
> * Check for case sensitivity
> * Validate JSON syntax
> * Test with simple field paths first
> * Add `[]` notation for array field searches

> [accordion] Connection Issues
>
> **Possible Causes:**
>
> * Kafka topics not properly configured
> * Network connectivity problems
> * Service authentication issues
>
> **Solutions:**
>
> * Verify Kafka topic configuration
> * Check network connectivity
> * Validate service credentials
> * Review FlowX Engine logs

***

## Configuration templates

```json Simple search template theme={"dark"}
{
  "searchKey": "your.field.path",
  "value": "search_value",
  "processDefinitionNames": ["your_process"],
  "states": ["FINISHED"]
}
```

```json Advanced search template theme={"dark"}
{
  "searchKeys": [
    {"key": "field1", "value": "value1"},
    {"key": "field2", "value": "value2"}
  ],
  "processDefinitionNames": ["your_process"],
  "states": ["FINISHED"]
}
```

```json Array search template theme={"dark"}
{
  "searchKeys": [
    {"key": "application.listField.[].property", "value": "search_value"}
  ],
  "processDefinitionNames": ["your_process"],
  "states": ["FINISHED"]
}
```

```json Multiple array conditions template theme={"dark"}
{
  "searchKeys": [
    {"key": "application.employees.[].firstName", "value": "Maria"},
    {"key": "application.employees.[].department", "value": "Engineering"}
  ],
  "processDefinitionNames": ["employee_process"]
}
```

```json Cross-application template theme={"dark"}
{
  "searchKey": "your.field.path",
  "value": "search_value",
  "applicationIds": ["app-uuid-1", "app-uuid-2"],
  "states": ["FINISHED"]
}
```

```json Date range template theme={"dark"}
{
  "searchKey": "your.field.path",
  "value": "search_value",
  "processStartDateAfter": "2024-01-01T00:00:00Z",
  "processStartDateBefore": "2024-12-31T23:59:59Z",
  "processDefinitionNames": ["your_process"]
}
```

***

## Related resources

> [card] [Elasticsearch setup](../../../setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/)
>
> Configure Elasticsearch indexing for FlowX Engine

> [card] [Data search service setup](../../../setup-guides/search-data-service-setup-guide)
>
> Complete deployment and configuration guide

> [card] [Process designer](../../building-blocks/process/process)
>
> Learn how to design processes with searchable data


# Task Management localization
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization

Comprehensive localization support for Task Management, enabling multi-language experiences through FlowX substitution tags.

Task Management in FlowX.AI includes comprehensive localization capabilities, allowing you to deliver fully translated task management interfaces in multiple languages. Configure 51 FlowX substitution tags in CMS for each language you want to support.

## Localization approach

Task Management localization operates through FlowX Substitution Tags:

### FlowX Substitution Tags (51 Keys) - manual configuration

Custom Task Management UI elements that **must be configured manually in CMS** for each language:

* Table column names (title, stage, assignee, status, priority)
* Task actions (assign, unassign, hold, execute)
* Bulk operations (assign all to me, unassign all, hold all)
* History events and status values
* Comments and user selection dialogs

> [!NOTE]
>
> If you need to configure FlowX substitution tags default text values (51 keys) in CMS, you can do so by navigating to **CMS** → **Substitution Tags** and adding the default text values for the substitution tags.

## FlowX substitution tags

FlowX substitution tags control custom Task Management interface elements outside the data table. These **51 tags** must be configured manually in CMS for each language.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)

### Complete tag reference

> [tab] Search & columns
>
> **Search & Navigation**
>
> * `sys_tm_search` - "Search"
>
> **Table Columns**
>
> * `sys_tm_title` - "Title"
> * `sys_tm_stage` - "Stage"
> * `sys_tm_assignee` - "Assignee"
> * `sys_tm_status` - "Status"
> * `sys_tm_priority` - "Priority"
> * `sys_tm_last_updated` - "Last updated"

> [tab] Process states
>
> **Process States (Status Values)**
>
> * `sys_tm_created` - "Created"
> * `sys_tm_started` - "Started"
> * `sys_tm_finished` - "Finished"
> * `sys_tm_finished_with_error` - "Finished with error"
> * `sys_tm_failed` - "Failed"
> * `sys_tm_expired` - "Expired"
> * `sys_tm_aborted` - "Aborted"
> * `sys_tm_terminated` - "Terminated"
> * `sys_tm_dismissed` - "Dismissed"
> * `sys_tm_on_hold` - "On hold"

> [tab] Actions
>
> **Bulk Actions**
>
> * `sys_tm_assign_to` - "Assign to…"
> * `sys_tm_unassign_all` - "Unassign All"
> * `sys_tm_assign_all_to_me` - "Assign All to me"
> * `sys_tm_hold_all` - "Hold All"
> * `sys_tm_unhold_all` - "Unhold All"
>
> **Task Actions**
>
> * `sys_tm_view_application` - "View Application"
> * `sys_tm_unassign` - "Unassign"
> * `sys_tm_assign_to_myself` - "Assign to myself"
> * `sys_tm_unhold` - "Unhold"
> * `sys_tm_hold` - "Hold"
> * `sys_tm_assign` - "Assign"
> * `sys_tm_execute` - "Execute"
> * `sys_tm_start` - "Start"

> [tab] Task details
>
> **Task Details Sections**
>
> * `sys_tm_assignee_deactivated` - "(Deactivated)"
> * `sys_tm_comments` - "Comments"
> * `sys_tm_write_a_comment` - "Write a comment…"
> * `sys_tm_history` - "History"
>
> **History Events**
>
> * `sys_tm_task_created` - "Task created"
> * `sys_tm_user_created_this_task` - "`${user}` created this task"
> * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
> * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
> * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
> * `sys_tm_task_moved_to` - "Task moved to"
> * `sys_tm_task_status_changed_to` - "Task status changed to"
> * `sys_tm_task_assigned_to` - "Task assigned to"
> * `sys_tm_task_owner_removed` - "Task owner removed"

> [tab] User selection & UI
>
> **User Selection & Search**
>
> * `sys_tm_select_person` - "Select person..."
> * `sys_tm_search_person` - "Search users"
> * `sys_tm_search_term_validation` - "Type at least 4 characters..."
>
> **UI States**
>
> * `sys_tm_loading` - "Loading..."
> * `sys_tm_nothing_found` - "Nothing Found"
>
> **Data display**
>
> * `sys_tm_in` - "In" (custom filter operator)
> * `sys_tm_yes` - "Yes" (boolean value)
> * `sys_tm_no` - "No" (boolean value)

> [!WARNING]
>
> **Manual Configuration Required**: All 51 FlowX substitution tags must be configured manually in CMS for each language you want to support. They control custom Task Management UI elements outside of the data table.

## Implementation guide

To localize Task Management, configure the **51 FlowX substitution tags** in CMS for each language you want to support.

**1. Add FlowX substitution tags to CMS**

For each supported language:

1. Navigate to **CMS** → **Substitution Tags**
2. Add values for all 51 `sys_tm_*` tags for the target language
3. These control custom Task Management UI elements:
   * Task actions (assign, hold, unassign)
   * Bulk operations (assign all to me, unassign all, hold all, unhold all)
   * History events (task created, user created this task, started process instance with id, started process instance on build, task ownership changed to, task moved to, task status changed to, task assigned to, task owner removed)
   * Comments section (comments, write a comment...)
   * User selection dialogs (select person, search users, search term validation)
   * UI states (loading, nothing found)
   * Data display (in, yes, no)

**2. Configure custom column names (Optional)**

If you need columns beyond the default ones:

1. Define custom parameters in **Process Settings** → **Task Management**
2. Use substitution tags for column display names
3. These tags will also need CMS translations for each language
4. When you configure the column display name, use the substitution tag for the column name( it is called using "@@" prefix)

**3. Test localization**

Verify that Task Management is properly localized:

* Task action buttons (assign, unassign, hold, execute)
* Bulk operation buttons (assign all to me, unassign all, hold all)
* Task history timeline and status values
* Comments section and user assignment dialogs

## Localization best practices

### 1. Maintain consistency

Ensure translation consistency across:

* CMS substitution tags
* Custom column display names

### 2. Handle dynamic content

For history events and comments that include dynamic values (user names, dates, IDs), use the variable placeholders:

```javascript theme={"dark"}
// In CMS, use placeholders
sys_tm_user_created_this_task: "${user} created this task"
sys_tm_task_assigned_to: "Task assigned to ${user}"

// The system will replace ${user} with actual usernames at runtime
```

## Localization by component

### Task list view

| Component | Configuration Required |
| - | - |
| Column headers (default) | CMS translation |
| Column headers (custom) | CMS translation |
| Search placeholder | CMS translation |
| Status values | CMS translation |

### Task details panel

| Component | Configuration Required |
| - | - |
| Action buttons | CMS translation |
| Section titles | CMS translation |
| History timeline | CMS translation |
| Comment input | CMS translation |
| User selector | CMS translation |

### Bulk operations

| Component | Configuration Required |
| - | - |
| Bulk action buttons | CMS translation |
| Confirmation dialogs | CMS translation |
| Success/error messages | CMS translation |

## Search and sort on translated labels

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The task list searches and sorts on the labels it displays, in the language the task list is shown in, instead of on the values stored on the task. A user who types a word they see in the grid, in their own language, finds the matching tasks.

This applies to columns that display a label:

* **Status**: matched and sorted on the translated `sys_tm_*` status labels. With the Romanian example below, searching `Finalizat` finds finished tasks.
* **Enumeration columns**: matched and sorted on the enumeration labels for the viewer's language.
* **Text columns that hold a substitution tag**: a value stored as a substitution tag is matched and sorted on the tag's translated text. Ordinary text values match as before.

How each operation behaves on these columns:

* **Search box**: partial, case-insensitive match against the label. A value displayed as a label is found through its label, not through the stored code.
* **Text filters**: filters applied in the task list match the labels the same way. Filters saved in a view's **Dataset Config** keep comparing the stored values, so existing views return the same tasks. Filters on enumeration and status columns, which you pick from a list, work as before.
* **Sorting**: tasks are ordered by the displayed label, ignoring letter case. Tasks with no value in the sorted column are listed last, in both ascending and descending order.

In a running app, the labels come from the build the app runs. In FlowX Designer, they come from the app version you are editing.

> [!NOTE]
>
> If the task list has no language set, or its labels can't be read, search and sort use the stored values, as in earlier versions. An enumeration value or status that has no label in the viewer's language is matched on its stored value. A text value stored as a substitution tag that has no translation is displayed empty, is not found by search or text filters, and is sorted with the empty values.

## Troubleshooting

> [accordion] Custom elements not translating
>
> **Problem**: Task actions, history, or comments display in English.
>
> **Solutions**:
>
> 1. Verify all 51 `sys_tm_*` tags are configured in CMS
> 2. Check that translations exist for the current user's language
> 3. Ensure CMS language codes match your application's language selection
> 4. Verify substitution tag syntax is correct (no typos)

> [accordion] Mixed language display
>
> **Problem**: Some elements in one language, others in another.
>
> **Solutions**:
>
> 1. This indicates incomplete CMS configuration - likely missing FlowX substitution tags
> 2. Verify all 51 `sys_tm_*` tags are translated in CMS for the target language
> 3. Use browser dev tools to identify which specific elements are untranslated

> [accordion] Custom column names not translating
>
> **Problem**: Custom columns display original names instead of translations.
>
> **Solutions**:
>
> 1. Ensure custom column display names use substitution tags
> 2. Verify those substitution tags are configured in CMS for all languages
> 3. Check that column configuration points to correct substitution tag keys

## Example: complete Romanian localization

Here's an example of configuring Task Management for Romanian language:

**1. Add Romanian CMS translations**

In CMS, add translations for all 51 tags:

```json theme={"dark"}
{
  "sys_tm_search": "Căutare",
  "sys_tm_title": "Titlu",
  "sys_tm_stage": "Etapă",
  "sys_tm_assignee": "Asignat",
  "sys_tm_status": "Status",
  "sys_tm_priority": "Prioritate",
  "sys_tm_last_updated": "Ultima actualizare",
  "sys_tm_created": "Creat",
  "sys_tm_started": "Început",
  "sys_tm_finished": "Finalizat",
  "sys_tm_assign_to": "Atribuie către…",
  "sys_tm_unassign": "Anulează atribuirea",
  "sys_tm_comments": "Comentarii",
  "sys_tm_history": "Istoric",
  // ... add all 51 tags
}
```

**2. Verify complete localization**

Test all areas to confirm:

* ✅ Task actions show Romanian labels (from CMS)
* ✅ History events display in Romanian (from CMS)
* ✅ Comments section uses Romanian labels (from CMS)

## Additional resources

> [card] [Task Management Overview](./task-management-overview)
>
> Learn about Task Management features and configuration

> [card] [CMS Substitution Tags](../content-management/substitution-tags)
>
> Configure substitution tags in Content Management System


# Task management
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-overview

The Task Manager tracks work items from running processes - build filtered task views, assign and reassign tasks, manage swimlanes and stages, and embed task lists in your apps with the Task Manager UI component. One task is created per process instance.

![Task Manager](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/tsk_mng2.0.png)

Task Management tracks work items generated by running processes. It gives teams visibility into who is responsible for each case, where it stands, and what needs attention. It supports both low-code (built-in views) and full-code (SDK-based) approaches.

***

## How it works

### Tasks and process instances

When a process instance starts, FlowX creates **one task** for that instance. The task acts as a container that tracks everything happening inside the process: which swimlane the work is in, who is assigned, what stage it has reached, and what its status is.

The relationship is **one task per process instance**, not per user or per node.

### Tokens and swimlanes

Inside a task, FlowX tracks individual **tokens** as they move through swimlanes and stages. Each time a token enters or exits a swimlane or stage, Task Management records that transition. This means a single task can reflect activity across multiple swimlanes if the process is designed that way.

### Parallel gateways

When a process reaches a parallel gateway and splits into multiple paths:

* The **parent token** is paused (`ON_HOLD`) while child tokens execute in parallel.
* Each **child token** is tracked independently inside the same task.
* If multiple tokens land in the **same swimlane**, Task Management automatically deduplicates them so the task list shows a single entry per swimlane.
* When all parallel paths complete and the gateway joins, the parent token resumes.

### Enabling task management for a process

Before Task Management can track a process, you must enable it:

1. In **FlowX Designer**, open the process definition and go to **Process Settings** → **Task Management** tab.
2. Toggle **Use process in task management** to **ON**.

> [!WARNING]
>
> This toggle is required. If it is off, no task will be created for instances of this process, and no updates will be sent to Task Management.

Once enabled, you can also configure which nodes send updates to Task Management by enabling the **Update task management** switch on individual nodes. This controls whether task metadata (title, priority, stage, business filters) is refreshed when the token passes through that node.

***

## Key features

* **Views**: Configurable interfaces to display task-related data, scoped to a process definition.
* **Stages**: Monitor the progression of tasks within a process by identifying where a case may have stalled. Useful for tracking business stages like onboarding, verification, and validation.
* **Allocation rules**: Automatically distribute tasks among users based on current workload. The user with the fewest assigned tasks in the target swimlane is selected.
* **Localization** (Available in 5.1.1+): Multi-language support with 34+ languages. Configure substitution tags in CMS while table grid localization happens automatically. See [**Task Management Localization**](./task-management-localization) for details.

### Viewing tasks in FlowX Designer

To see the tasks of a project without opening a container app, open the project, switch to the **Runtime** view, and select **Task Manager**. The page lists the project's runtime tasks, with **Title**, **Stage**, **Assignee**, **Status**, **Priority**, and **Last updated** columns, using the project's default theme and language. It needs read access to the workspace's tasks.

## Task Management Views

Views offer a flexible way to tailor task data display according to business needs. By configuring views, users can create structured, customized interfaces that help specific roles, departments, or use cases access relevant data effectively.

Example of custom view:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2016.29.13.png)

### All tasks

In the All Tasks section, you can view all tasks generated from any process definition marked as "to be used in task manager" within a project. This provides a centralized view of all relevant tasks, as long as you have the appropriate permissions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-11%20at%2018.32.13.png)

It provides an interactive visualization, with built-in filtering functionalities for refined data display.

> [!NOTE]
>
> Dataset Config and Table Config options are not accessible in the All Tasks view.

### Creating a view

In the Views section, you can create a new view by selecting a name and choosing a process definition. The process definition is crucial because it determines which keys you can access when configuring the view.

To set up a view, navigate to the Views section in the Task Management interface:

1. Click **Add View**.
2. Enter a **Name** for the view.
3. **Choose a Process Definition**: This will link the view's configuration to a specific process and its associated keys.

> [!NOTE]
>
> Once a view is created for a process (e.g., Process X), it cannot be reassigned to another process. This ensures consistent data structuring based on the selected process definition.

Upon creating a view, you are automatically redirected to configure its parameters.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-11%2018.34.39.gif)

The Task Management default view contains four primary columns, with two additional default columns that can be added.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-11%20at%2018.37.30.png)

> [!TIP]
>
> You also have the option to add custom parameters to the table, with no limit on the number of columns.

**Columns explained**:

* **Stage**: Indicates where the process halted, providing a clear view of its current state.
* **Assignee**: Displays the username of the user the task is assigned to. By default, this is the `preferred_username` claim from the user's identity provider token, which in Keycloak is the user's **Username** field. The column doesn't show the user's first name, last name, or email.
* **Priority**: A numeric value set via business rules, used for sorting and filtering tasks in views.
* **Last Updated**: Shows the timestamp of the most recent action taken on the task.
* **Title**: Displays the designated name of the task, which can be customized by using Business Rules.
* **Status**: The current process instance status, such as `STARTED` or `FINISHED`. See [Process status updates](#process-status-updates) for all values.
* **Custom parameters**: User-defined keys within the process settings, which become available only after their configuration is complete.

### Custom parameters and display names

### Display names

You can rename default and custom parameters to make them contextually relevant for various business needs. For example:

* Rename an address field to clarify if it refers to "Residence" or "Issuing Location."

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-11%2019.13.07.gif)

* Use Substitution Tags for dynamic display names.

> [!NOTE]
>
> Renaming a parameter's Display Name will only change how it's shown in the interface, without altering the actual data model. The rename option is also available for default parameters (not just custom parameters). Changing the Display Name also allows the use of Substitution Tags.
>
> For multi-language support, configure substitution tags in CMS for each language. See [**Task Management Localization**](./task-management-localization) for complete localization setup.

### Custom Parameters in Task Management

Custom parameters in Task Management provide a way to tailor task displays and ensure that task data aligns with specific business needs and contexts.

**Key setup and configuration**

1. **Adding Custom Parameters**:
   * In **Process Settings** → **Task Management**, you can define the custom keys that will be indexed and made available for tasks.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-11%20at%2019.11.02.png)

* Each custom parameter can be renamed to suit different business contexts, ensuring clarity in cases where parameters may have multiple meanings.

> [!TIP]
>
> Ensure that the custom key exists in the **Data Model** before it can be mapped in Task Management.
>
> > [!WARNING]
> >
> > If the **attribute type** of a custom key is modified after it has been indexed, the key must be re-indexed in the **Task Management** section. This re-indexing step is crucial to ensure that Task Management reflects the updated attribute type correctly.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2010.38.23.png)

> [!TIP]
>
> For data from custom parameters to flow correctly, ensure that **Forms to Validate** is set on the button's **event handler** in your UI for the corresponding process. This configuration is necessary for custom parameters to be validated and included in Task Management.

2. **Labeling Custom Parameters**:
   * When adding a custom parameter, use the rename option to assign it a label relevant to the process context (as demonstrated in the example [above](#display-names)).
   * This allows parameters to remain flexible for different roles or departments, adapting to each use case.

<video />

> [!NOTE]
>
> Remember to enable the **Use process in task management** toggle in **Process Settings** → **Task Management** and the **Update task management** switch on relevant nodes. See [Enabling task management for a process](#enabling-task-management-for-a-process) for details.

### Table config and Dataset config in Task Management

You can use **Table Config** and **Dataset Config** to configure and filter task data effectively. These configurations help create a customized and user-friendly interface for different roles, departments, or organizational needs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2013.41.17.png)

#### Table config

**Table Config** is used to define the structure and content of the Task Management table view. Here, you can configure the columns displayed in the table and set up default sorting options.

1. **Configuring the Table Columns**:
   * **Default Columns**: By default, the table includes the following columns: **Stage**, **Assignee**, **Priority**, and **Last Updated**.
   * You can add additional columns, such as **Title**, **Status**, and **Custom Parameters**. Custom parameters can be chosen from the keys configured in **Process Settings** → **Task Management**.

2. **Setting Default Sorting**:
   * You can select one column for **default sorting** in ascending or descending order. This configuration helps prioritize how data is initially displayed, often based on “Last Updated” or other relevant fields.
   * If no specific sorting rule is configured, the table will automatically apply sorting based on the **Last Updated** column.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2013.54.57.png)

#### Dataset config

**Dataset Config** is used to filter and refine the data displayed in Task Management views. This helps create targeted views based on specific needs, such as differentiating data for front office vs. back office or specific roles like managers and operators.

1. **Adding Filters**:
   * You can apply filters on the keys brought into the **Dataset Config** to customize the data shown. Filters can be applied based on various data types, such as enums, strings, numbers, dates, and booleans.

2. **Filtering Options by Data Type**:
   * **Enums**: Can be filtered using the `In` operator. Only parent enums are available for mapping in Task Management (ensure enums are mapped in the data model beforehand).

> [!NOTE]
>
> Before you can map enums in Task Management, they must be configured in the Data Model. Only parent enums can be mapped.
>
> > [!WARNING]
> >
> > If any changes are made to the Data Model after the keys have been configured and indexed in Task Management, these changes will not be automatically reflected. You must re-add and re-index the keys in the process settings to ensure that the updated information is indexed correctly.

### Searching tasks

The search box in a task view matches your keyword against the **visible columns of that view** only. Columns you haven't added to the view are not searched, and the search does not scan the full task payload.

How the keyword matches depends on each column's data type:

* **Text columns:** partial, case-insensitive match. Searching `inv` returns tasks whose value contains `inv`, `INV`, or `Invoice`.
* **Number columns (INTEGER, FLOAT):** exact match, and only when the keyword is itself a number. A non-numeric keyword skips these columns.
* **Boolean columns:** exact match, only for `true` or `false`.
* **Date columns:** not searched. Use view filters to narrow by date instead.

A task is returned if the keyword matches in **any** eligible column.

> [!NOTE]
>
> If a search returns fewer results than expected, check which columns the view exposes. Only visible, non-date columns are searched, so add the column you want to search on to the view, or use [view filters](#view-filter-operators-reference) for date and exact-value matching.

#### Search and sort in the viewer's language

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On the **Status** column, enumeration columns, and text columns that hold substitution tags, search and sort use the labels shown in the task list, in the viewer's language, instead of the stored values. For details, see [Search and sort on translated labels](./task-management-localization#search-and-sort-on-translated-labels).

### View filter operators reference

The following table provides a comprehensive reference of all available view filter operators and their compatible data types:

| Filter Operator | Compatible Data Types | Description |
| - | - | - |
| **Equals** | STRING, BOOLEAN, DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY | Matches values that are exactly equal to the specified value |
| **Not Equals** | STRING, DATE\_TIME, ZONED\_DATE\_TIME | Matches values that are not equal to the specified value |
| **In** | STRING, ENUM | Matches values that are contained within a specified list |
| **Greater Than** | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY | Matches values that are greater than the specified value |
| **Less Than** | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY | Matches values that are less than the specified value |
| **Greater Than or Equal** | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY | Matches values that are greater than or equal to the specified value |
| **Less Than or Equal** | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY | Matches values that are less than or equal to the specified value |
| **Range** | DATE\_TIME, ZONED\_DATE\_TIME, INTEGER, FLOAT, CURRENCY | Matches values within a specified range (between two values) |
| **Starts With** | STRING | Matches string values that begin with the specified text |
| **Ends With** | STRING | Matches string values that end with the specified text |
| **Contains** | STRING | Matches string values that contain the specified text anywhere within |
| **Not Contains** | STRING | Matches string values that do not contain the specified text |

#### Data type filter compatibility

**String filters:**

* `Equals`, `Not Equals`, `In`, `Starts With`, `Ends With`, `Contains`, `Not Contains`

**Numeric filters (INTEGER, FLOAT, CURRENCY):**

* `Equals`, `Greater Than`, `Less Than`, `Greater Than or Equal`, `Less Than or Equal`, `Range`

**Date filters (DATE\_TIME, ZONED\_DATE\_TIME):**

* `Equals`, `Not Equals`, `Greater Than`, `Less Than`, `Greater Than or Equal`, `Less Than or Equal`, `Range`

**Boolean filters:**

* `Equals`

**Enum filters:**

* `In`

> [!TIP]
>
> When using range filters, you'll need to specify both a minimum and maximum value. For date ranges, ensure the date format matches your system's configured format.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2017.07.35.png)

3. **Role-Specific Configurations**:
   * **Dataset Config** allows creating views tailored to specific audiences, such as different departments or roles within an organization. However, note that filters in Dataset Config do not override user permissions on task visibility.

Example with filter applied a number attribute:

<video />

### Managing data model changes

Views are scoped to a process definition and do not need to be recreated when the data model changes. However, custom parameters used as columns must exist as keys in the process's data model before they can be added to Task Management. If you modify a custom key's attribute type after indexing, you must re-index it in **Process Settings** → **Task Management** for the change to take effect.

### Task details

The **Task Details** tab within **Task Manager** provides key process information, including:

* **Priority**: A numeric value (set via business rules) used for sorting and filtering tasks. Does not affect automatic allocation.
* **Status**: The current process instance status (for example, `STARTED`, `FINISHED`, or `ON_HOLD`).
* **Stage**: The current stage during process execution.
* **Comments**: User comments.
* **History**: Information such as task creation, creator, and status changes.
* **Last Updated**: Displays the most recent timestamp of any changes made to a task.
* **View Application**: Provides direct access to the container application URL where the FlowX.AI process related to a specific task is running.

![Task details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-12%20at%2017.46.01.png)

**Accessing Task details in Task Management**

To access the **Task Details** of a specific task in a Task Management view, follow these steps:

1. **Navigate to the Task Management Interface**:
   * Open the Task Management section within the project and select the desired **View** that contains the list of tasks.

2. **Locate the Task**:
   * In the selected view (e.g., All Tasks, Custom View), find the task you want to inspect. Use filters and sorting options if necessary to locate the task more efficiently.

3. **Open Task Details**:
   * Click on the task or select the **Details** option (often represented by an icon or “Details” link) associated with the task entry.
   * This action will open the **Task Details** panel, which provides an in-depth view of information specific to that task.

<video />

> [!NOTE]
>
> Please note that specific roles must be defined in a process to utilize all the task management features. For configuration details, see [**Configuring Access Roles for Task Manager**](../../../../setup-guides/access-management/workspaces-access-rights).

### Export and import views

You can export and import Task Management views to transfer them between projects or environments.

To import views:

1. Navigate to the **Views** list in Task Manager
2. Open the context menu and select **Import from Zip**
3. Select the ZIP file exported from another project or environment
4. If views with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting view (or use **Apply to all**):
   * **Keep both** - imports the view as a new copy alongside the existing one
   * **Replace** - overwrites the existing view with the imported version
   * **Skip this one** - keeps the existing view unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

## Process status updates

Task Manager displays the process instance status for each task. These statuses match the [process instance statuses](../../../projects/runtime/active-process/process-instance):

| Status | Definition |
| - | - |
| **CREATED** | Visible only if there is an error during process creation. If the process starts without errors, it transitions directly to `STARTED`. |
| **STARTED** | The process instance is running. |
| **FINISHED** | The process reached an end node and completed execution. |
| **FINISHED\_WITH\_ERROR** | The process completed but encountered errors during execution. |
| **FAILED** | A [CronJob](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) expired before the process completed. For example, if a process must finish by a deadline and does not. |
| **EXPIRED** | The `expiryTime` defined in the process definition elapsed. Configure this in **Process Settings** → **General** → **Expiry time**. |
| **ABORTED** | A subprocess was aborted because the [token was moved backward](../../../flowx-designer/managing-a-project-flow/moving-a-token-backwards-in-a-process) in the parent process, or an interrupting boundary event (error, timer, or message) fired on the parent's Call Activity node. |
| **DISMISSED** | A user stopped a running subprocess. |
| **ON\_HOLD** | The process is frozen, blocking further actions. A superuser can place a process on hold for clarification and later unfreeze it. |
| **TERMINATED** | A termination request ended all active tokens in the process and its subprocesses. |

## Swimlanes and Stages updates

Task Manager also tracks swimlane and stage changes:

### Swimlanes updates

| Status | Definition |
| - | - |
| **Swimlane Enter** | Marks token entering a new swimlane. |
| **Swimlane Exit** | Indicates token exiting a swimlane. |

### Stages updates

| Status | Definition |
| - | - |
| **Stage Enter** | Marks token entering a new stage. |
| **Stage Exit** | Indicates token exiting a stage. |

## Using the plugin

The Task Manager plugin offers a range of features tailored to different roles, including:

* [Swimlane permissions for Task Management](#swimlane-permissions-for-task-management)
* [Assigning and unassigning Tasks](#task-assignment-and-reassignment)
* [Hold/unhold tasks](#hold/unhold-tasks)
* [Adding comments](#adding-comments)
* [Viewing the application](#viewing-the-application)
* [Bulk updates (via Kafka)](#bulk-updates)

### Swimlane permissions for Task Management

To perform specific actions within Task Management at process level, you must configure swimlane permissions at the process settings level. Each swimlane (e.g., BackOffice, FrontOffice, Manager) should be assigned appropriate roles and permissions based on the responsibilities and access needs of each user group.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2012.44.21.png)

**Example permissions configuration**

Below are example configurations for swimlane permissions based on roles commonly used in a loan application approval process:

1. **BackOffice Swimlane**:
   * Role: `FLOWX_BACKOFFICE`
   * Permissions:
     * **Unhold**: Allows the user to resume tasks that have been put on hold.
     * **Execute**: Enables the user to perform task actions.
     * **Self Assign**: Permits users to assign tasks to themselves.
     * **View**: Grants viewing rights for tasks.
     * **Hold**: Allows tasks to be temporarily paused.

2. **Manager (Supervisor) Swimlane**:
   * Role: `FLOWX_MANAGER`
   * Permissions:
     * **Unhold**: Allows the user to resume tasks that have been put on hold.
     * **Execute**: Enables the user to perform task actions.
     * **Self Assign**: Permits users to assign tasks to themselves.
     * **View**: Grants viewing rights for tasks.
     * **Hold**: Allows tasks to be temporarily paused.

> [!NOTE]
>
> These permissions can be customized depending on each use case and organizational needs. Ensure that permissions are aligned with the roles' responsibilities within the workflow.

### Task assignment and reassignment

Consider this scenario: you're the HR manager overseeing the onboarding process for new employees. To simplify this operation, you've opted to use the task manager plugin. This process consists of two key phases: the Initiation Stage and the Account Setup Stage, each requiring a designated team member.

The Initiation Stage has successfully concluded, marking the transition to the Account Setup Stage. At this juncture, it's essential to reassign the task, originally assigned to John Doe, to Jane Doe, a valuable member of the backoffice team.

<video />

### Hold/unhold tasks

As a project manager overseeing various ongoing projects, you may need to temporarily pause one due to unforeseen circumstances. To manage this, you use the "On Hold" status.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-13%2013.48.35.gif)

### Adding comments

When handling on-hold projects, document the reasons, inform the team, and plan for resumption. This pause helps address issues and ensures a smoother project flow upon resuming. Never forget to add comments:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-13%20at%2013.53.07.png)

### Viewing the application

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2017.08.21.png)

Container App URL represents an URL or a configuration parameter used to redirect users directly to a specific FlowX process instance.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2015.02.09.png)

#### Process settings level

In the Process Definition settings, navigate to the **Task Management** tab and locate the **Container App URL** field. Here, paste the container application URL where the process is loaded, following this format:

```
{container app url}/process
```

**Example**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2017.10.54.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-30%2017.16.10.gif)

> [!TIP]
>
> You can also use a predefined generic parameter as the URL: `${genericParameter}`.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-30%20at%2017.13.56.png)
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-13%20at%2017.08.12.png)

#### Process data level

If task.baseUrl is specified in the process parameters, it will be sent to the Task Manager to update the tasks accordingly.

```java theme={"dark"}
output.put("task", {"baseUrl": "https://your_base_url"});
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/tsk_manager_base_url.png)

> [!WARNING]
>
> The `baseURL` set in the process data (business rules) will override the `baseURL` set in the process definition settings.

## Task operations via Kafka

You can perform task operations programmatically by sending Kafka messages to the `ai.flowx.core.trigger.operation.v1` topic. This enables integration with external systems and automation of task management workflows.

### Required Kafka headers

| Header | Required | Purpose |
| - | - | - |
| `Fx-Organization-Id` | ✅ Yes | Organization UUID. Messages without it are rejected with `MissingKafkaHeaderException` |
| `Fx-Workspace-Id` | ✅ Yes | UUID of the workspace where the process instance lives |
| `jwt` | ❌ No | JWT token of the user (or service account) performing the operation. Sets the security and audit context when present; messages without it are still processed. Operation attribution comes from the `author` body field |
| `callbackTopic` | ❌ No | Topic to receive the operation result; omit for fire-and-forget |

For details on how to obtain these values, see [Finding Identifiers and Parameters](../../integrations/finding-identifiers-and-parameters).

### Available operation types

| Operation Type | Description |
| - | - |
| **ASSIGN** | Assigns the task to a specified user |
| **UNASSIGN** | Unassigns the task from the user |
| **HOLD** | Places the task on hold, blocking further actions |
| **UNHOLD** | Removes the hold status, allowing the task to proceed |
| **TERMINATE** | Terminates the instance of the process |

#### Field descriptions

| Field | Type | Required | Description |
| - | - | - | - |
| **operationType** | String | ✅ Yes | The type of operation to perform (see available operation types table) |
| **processInstanceUuid** | String (UUID) | ✅ Yes | The UUID of the process instance |
| **swimlaneName** | String | ✅ Yes | Name of the swimlane where the task resides |
| **owner** | Object | ✅ Yes (for ASSIGN) | User details for assignment operations |
| **taskId** | String | ❌ No | Unique identifier of the task (optional) |
| **swimlaneId** | String (UUID) | ❌ No | Unique identifier of the swimlane (optional) |
| **author** | String | ❌ No | The user performing the operation (typically email or username) |

#### Owner object structure

| Field | Type | Required | Description |
| - | - | - | - |
| **username** | String | ✅ Yes | Username or email of the user |
| **firstName** | String | ❌ No | First name of the user being assigned |
| **lastName** | String | ❌ No | Last name of the user being assigned |
| **enabled** | Boolean | ❌ No | Whether the user account is enabled |

### Required parameters by operation

> [tab] ASSIGN
>
> **Minimal parameters required:**
>
> | Parameter | Required |
> | - | - |
> | operationType | ✅ Yes |
> | processInstanceUuid | ✅ Yes |
> | swimlaneName | ✅ Yes |
> | owner.username | ✅ Yes (only username is needed) |
> | taskId | ❌ No |
> | swimlaneId | ❌ No |
> | author | ❌ No |
>
> **Example:**
>
> ```json theme={"dark"}
> {
>   "operationType": "ASSIGN",
>   "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
>   "swimlaneName": "Default",
>   "owner": {
>     "username": "user@flowx.ai"
>   }
> }
> ```

> [tab] UNASSIGN
>
> **Minimal parameters required:**
>
> | Parameter | Required |
> | - | - |
> | operationType | ✅ Yes |
> | processInstanceUuid | ✅ Yes |
> | swimlaneName | ✅ Yes |
> | taskId | ❌ No |
> | swimlaneId | ❌ No |
> | author | ❌ No |
>
> **Example:**
>
> ```json theme={"dark"}
> {
>   "operationType": "UNASSIGN",
>   "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
>   "swimlaneName": "Default"
> }
> ```

> [tab] HOLD / UNHOLD
>
> **Minimal parameters required** - swimlane and owner fields are not needed.
>
> | Parameter | Required |
> | - | - |
> | operationType | ✅ Yes |
> | taskId | ✅ Yes |
> | processInstanceUuid | ✅ Yes |
> | swimlaneName | ❌ No |
> | swimlaneId | ❌ No |
> | owner | ❌ No |
> | author | ✅ Yes |
>
> **Example (HOLD):**
>
> ```json theme={"dark"}
> {
>   "operationType": "HOLD",
>   "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
>   "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
>   "author": "admin@company.com"
> }
> ```
>
> **Example (UNHOLD):**
>
> ```json theme={"dark"}
> {
>   "operationType": "UNHOLD",
>   "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
>   "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
>   "author": "admin@company.com"
> }
> ```

> [tab] TERMINATE
>
> **Minimal parameters required:**
>
> | Parameter | Required |
> | - | - |
> | operationType | ✅ Yes |
> | processInstanceUuid | ✅ Yes |
>
> **Example:**
>
> ```json theme={"dark"}
> {
>   "operationType": "TERMINATE",
>   "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223"
> }
> ```

> [!WARNING]
>
> Ensure that users performing operations have the appropriate swimlane permissions configured in the process settings. Operations will fail if the user lacks the necessary permissions for the specified swimlane.

## Bulk updates

Send bulk update requests via Kafka (using Process Engine) to perform multiple operations at once. Use the Kafka topic:

* Send the operations as an array to the topic configured in the Process Engine's `KAFKA_TOPIC_PROCESS_OPERATIONS_BULKIN` variable (default: `ai.flowx.core.trigger.operations.bulk.v1`). The engine consumes the message and runs each operation in the array. For more information, see the [Task Management plugin topics](../../../../setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-the-task-management-plugin).

Bulk requests use the same Kafka headers as single operations (see [Required Kafka headers](#required-kafka-headers)). Set `callbackTopic` to receive a per-operation result list with `SUCCESS`, `PARTIAL_ERROR`, or `ERROR` status.

Example of a bulk request:

```json theme={"dark"}
{
  "operations": [
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default",
      "owner": null,
      "author": "john.doe@flowx.ai",
      "requestID": "1234567891"
    },
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default",
      "owner": null,
      "author": "john.doe@flowx.ai",
      "requestID": "1234567890"
    }
  ]
}
```

For more information on bulk updates configuration, see FlowX Engine setup:

> [card] [FlowX Engine setup](../../../../setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-the-task-management-plugin)

## Updating Task Manager metadata through business rules

You can dynamically update task metadata during process execution using business rules. The engine intercepts values stored under the reserved `task` key in the process data and forwards them to Task Management.

### Reserved `task.*` keys

The following keys are reserved. When set via `output.put("task", {...})` in a business rule, the engine extracts them and sends them to Task Management:

| Key | Type | Description |
| - | - | - |
| `task.title` | String | Display title shown in task lists and details |
| `task.priority` | Number | Numeric priority for sorting and filtering (does not affect automatic allocation) |
| `task.baseUrl` | String | Container app URL for the "View Application" link. Overrides the URL set in process settings |
| `task.tags` | List | Tags attached to the task |
| `task.metadata` | Object | Arbitrary metadata attached to the task |
| `task.businessFilters` | Object | Business filter values used for allocation and view filtering |
| `task.candidateUsers` | List | Candidate users for task assignment, overriding swimlane-level allocation settings |

> [!WARNING]
>
> The `task` key is **reserved**. Any data stored under `task.*` in process parameters is intercepted by the engine and sent to Task Management. Do not use the `task` key for other business data.

### Updating task title and priority

Here is how to update both the title and priority:

```javascript theme={"dark"}
// Define your task title
taskTitle = "SME Branch Lending";
taskPriority = 1; 

// Update the task title
output.put("task", {
    "title": taskTitle,
    "priority": taskPriority
});
```

### Setting dynamic value based on business logic

You can set priority dynamically based on business conditions:

```javascript theme={"dark"}
// Get client data and loan amount
const clientDataSection = input.clientDataSection;
const loanAmount = input.loanAmount;

// Create a descriptive task title
const taskTitle = `Loan Application # ${clientDataSection.firstName} - ${clientDataSection.lastName}`;

// Set priority based on loan amount
let taskPriority;
if (loanAmount > 50000) {
    taskPriority = 1; // HIGH priority for large loans
} else if (loanAmount > 10000) {
    taskPriority = 2; // MEDIUM priority for medium loans
} else {
    taskPriority = 3; // LOW priority for small loans
}

// Update both title and priority
output.put("task", {
    "title": taskTitle,
    "priority": taskPriority
});
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/task_and_title.png)

You can make task titles more dynamic and informative by incorporating process data:

```javascript theme={"dark"}
// Get relevant data from the process
const clientName = input.get("customer.fullName");
const applicationId = input.get("application.id");
const loanAmount = input.get("loan.amount");

// Create a descriptive task title
const taskTitle = `Loan Application #${applicationId} - ${clientName} - ${loanAmount}`;

// Update the task title
output.put("task", {
    "title": taskTitle
});
```

## Full-Code implementation

For more customized UX, the **full-code** implementation using the **Task Management SDKs (React and Angular)** allows developers to build custom tables, cards, or any other UI elements based on the views and columns configured in Task Management.

## FAQs

> [accordion] What happens to currencies, numbers, and dates already indexed when a locale or format override is applied in the UI Designer?
>
> A: The format changes will only affect how the data is displayed, not how it's indexed.

> [accordion] Can I switch to full-code if I'm not satisfied with the current view and filter options?
>
> A: Yes, you can always switch to full-code and create custom views or tables using the Task Management SDK.

> [accordion] How are subprocess keys handled in Task Management?
>
> A: To use data from a subprocess, you must send it to the parent process first. Subprocess keys are currently displayed in the task manager once indexed through the parent process.


# Using allocation rules
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/using-allocation-rules

Allocation rules automatically assign tasks to users as tokens enter a swimlane, distributing work based on each user's current task count.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2012.54.21.png)

Allocation rules automatically assign tasks to users as a token enters a swimlane that has a specific role configured. For example, you can route front-office tasks to one group and back-office tasks to another.

### How allocation works

When a task reaches a swimlane with allocation rules configured, the system:

1. Identifies **candidate users** — either all users with execute permissions in that swimlane, or a specific list you define.
2. Counts each candidate's **currently assigned tasks** across all processes.
3. Assigns the task to the user with the **fewest assigned tasks** (lowest workload).
4. If two or more users have the same task count, one is selected **randomly**.

> [!NOTE]
>
> Allocation is based purely on task count. Task **priority** does not affect which user receives the task — it is a display and filtering field only.

## Accessing allocation rules

To access the allocation rules, follow the next steps:

1. Open **FlowX Designer**.
2. Go to your **Application** and from the side menu, under **Task Management**, select the **Allocation rules** entry.

## Adding process and allocation rules

To add process and allocation rules, follow the next steps:

1. Click **Add process** button, in the top-right corner.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-11-14%2013.01.30.gif)

2. Select a [**process definition**](../../../building-blocks/process/process-definition) from the drop-down list.

3. Click **Add swimlane allocations button (+)** to add allocations.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.03.34.png)

> [!NOTE]
>
> If there are no users with execute rights in the swimlane you want to add (`hasExecute: false`), the following error message will be displayed:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.06.00.png)

4. **Option 1**: Allocate all users with `execute rights`.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/allocate_execute_rights.png)

5. **Option 2**: Allocate only users you choose from the drop-down list. You can use the search function to filter users by name.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/allocate_execute_rights1.png)

6. Click **Save**.

> [!NOTE]
>
> Users with out-of-office status are skipped by automatic allocation. For more information, see the [out-of-office records documentation](using-out-of-office-records).

## Editing allocation rules

To edit allocation rules, follow the next steps:

1. Click **Edit** button.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.14.12.png)

2. Change the allocation method.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/change_allocation_method.gif)

3. Click **Save**.

### Viewing allocation rules

The allocation rules list displays all the configured swimlanes grouped by process:

1. **Process** - the process definition name where the swimlanes were configured
2. **Swimlane** - the name of the swimlane
3. **Allocation** - applied allocation rules
4. **Edited at** - the last time when an allocation was edited
5. **Edited by** - the user who edited/created the allocation rules

## Exporting/importing process allocation rules

To copy process allocation rules and move them between different environments, you can use the export/import feature.

You can export process allocation rules as JSON files directly from the allocation rules list:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.17.51.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-14%20at%2013.19.39.png)

## Related resources

> [card] [Task Management Overview](./task-management-overview)
>
> Learn about Task Management features and configuration

> [card] [Task Management Localization](./task-management-localization)
>
> Localize Task Management UI in 34+ languages

> [card] [Out of Office Records](./using-out-of-office-records)
>
> Manage user availability for task allocation


# Using out of office records
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/using-out-of-office-records

The Out-of-office feature allows you to register users availability to perform a task. It can be allocated manually or automatically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/out_of_office_records.png)

> [!NOTE]
>
> Users with out-of-office status are excluded from the candidates for automatic task allocation list during the out-of-office period. For more information, see the [allocation rules documentation](./using-allocation-rules).

## Accessing out-of-office records

To add out-of-office records, follow the next steps:

1. Open **FlowX Designer**.
2. Open **Organization Settings**, then under **Task Manager**, select **Out of Office**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/access_out_of_office.png)

## Adding out-of-office records

To add out-of-office records, follow the next steps:

1. Click **Add out-of-office** button, in the top-right corner.
2. Fill in the following mandatory details:
   * Assignee - user single select
   * Start Date (:exclamation:cannot be earlier than tomorrow)
   * End Date (:exclamation:cannot be earlier than tomorrow)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/add_out_of_office.png)

3. Click **Save**.

## Editing out-of-office records

To edit out-of-office records, follow the next steps:

1. Click **Edit** button.
2. Modify the dates (:exclamation:cannot be earlier than tomorrow).
3. Click **Save**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/edit_out_of_office.png)

## Deleting out-of-office records

To delete out-of-office records, follow the next steps:

1. From the **out-of-office list**, select a **record**.
2. Click **Delete** button. A pop-up message will be displayed: *"By deleting this out-of-office record, the user will become eligible to receive tasks in the selected period. Do you want to proceed?"*

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/delete_out_of_office.png)

> [!WARNING]
>
> If you choose to delete an out-of-office record, the user is eligible to receive tasks allocation during the mentioned period. For more information, see the [automatic task allocation documentation](./using-allocation-rules).

3. Click **Yes, proceed** if you want to delete the record, click **Cancel** if you want to abort the deletion.

> [!NOTE]
>
> If the out-of-office period contains days selected in the past, the user cannot delete the record, the following message is displayed: *“You can’t delete this record because it already affected allocations in the past. Try to shorten the period, if it didn’t end.”*

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/cant_delete_ooo.png)

## Viewing out-of-office records

The out-of-office records list contains the following elements:

1. **User** - firstName, lastName, userName
2. **Start Date** - the date when the out-of-office period will be effective
3. **End Date** - the date when the out-of-office period will end
4. **Edited at** - the last time when an out-of-office record was edited
5. **Edited by** - the user who edited/created the out-of-office record

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/view_ooo.png)

> [!NOTE]
>
> The list is sorted in reverse chronological order by "edited at" `dateTime` (newest added on top).

## Related resources

> [card] [Task Management Overview](./task-management-overview)
>
> Learn about Task Management features and configuration

> [card] [Task Management Localization](./task-management-localization)
>
> Localize Task Management UI in 34+ languages

> [card] [Allocation Rules](./using-allocation-rules)
>
> Configure automatic task allocation rules


# Using stages
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/core-extensions/task-management/using-stages

You can define specific stages during the execution of a process. Stages are configured on each node and they will be used to trigger an event when passing from one stage to another.

## Creating a new stage

To create a new stage, follow the next steps:

1. Open **FlowX Designer**.
2. Go to Task Manager and select **Stages**.
3. Click **New Stage.**
4. Fill in the required details.

![Create new stage](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/stages_add_new.png)

## Assigning a node to a stage

To assign a node to a stage, follow the next steps:

1. Open **FlowX Designer** and then select your **process**.
2. Choose the node you want to assign and select the **Node Config** tab.
3. Scroll down until you find the **Stage** field and click the dropdown button.
4. Choose the stage you want to assign.

![Node Assigning](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/stages_node_assigning.png)

## Export and import

You can export and import stages to transfer them between projects or environments.

### Exporting

1. Navigate to **Task Manager** > **Stages**
2. Open the context menu and select **Export**
3. The stages are downloaded as a ZIP file

### Importing

1. Navigate to **Task Manager** > **Stages**
2. Open the context menu and select **Import**
3. Select the ZIP file exported from another project or environment
4. If stages with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting stage (or use **Apply to all**):
   * **Keep both** - imports the stage as a new copy alongside the existing one
   * **Replace** - overwrites the existing stage with the imported version
   * **Skip this one** - keeps the existing stage unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

***

## Related resources

> [card] [Task Management Overview](./task-management-overview)
>
> Learn about Task Management features and configuration

> [card] [Task Management Localization](./task-management-localization)
>
> Localize stage names and Task Management UI in 34+ languages


# Consuming FlowX from external apps
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps

Choose the right integration pattern when calling FlowX from your own code — embed the UI with the SDKs, trigger processes via REST or webhooks, drive events through Kafka, or react to events downstream.

This guide is for developers who want to integrate FlowX with their **own application or backend** — for example, embedding a FlowX-driven UI inside a React app, triggering a FlowX process from a backend job, or reacting to FlowX events in a downstream system.

Pick the pattern that matches what you are trying to do. Each section links to the reference docs for setup details.

> [!WARNING]
>
> **Do not poll renderer-internal runtime endpoints from your own code.**
>
> Endpoints under `/api/runtime/process/.../status` and `/api/runtime/process/.../data` exist for the FlowX renderers (React / React Native / Angular / iOS / Android SDKs) to refresh their own state. They are not part of the public integration surface and their contracts can change between releases without notice. If you need process state in your own app, use one of the patterns below instead.

***

## Choose your pattern

| If you want to… | Use this pattern | Why |
| - | - | - |
| Show FlowX-driven screens inside your existing web or mobile app | [Renderer SDK](#1-embed-the-flowx-ui-with-an-sdk) | Handles state, validation, UI updates for you |
| Start a FlowX process from your backend, a scheduled job, or another service | [Public REST API](#2-trigger-a-process-via-rest) | Stable, documented, public endpoints |
| Start a FlowX process when an external system fires an HTTP callback | [Incoming Webhook](#3-trigger-a-process-from-an-incoming-webhook) | No backend code needed; FlowX exposes the URL |
| Start a FlowX process from an event your other services already publish | [Kafka custom integration](#4-trigger-a-process-from-a-kafka-event) | Fits event-driven architectures |
| React to FlowX activity from a downstream system | [Kafka events outbound](#5-react-to-flowx-events) | Decoupled, stream-based |

***

## 1. Embed the FlowX UI with an SDK

Use a renderer SDK to render FlowX-driven UI flows and process screens inside your app. The SDK manages session state, polling, and form lifecycle — you do not need to call runtime endpoints directly.

> [card] [React Renderer](/5.9/sdks/react-renderer)
>
> Embed FlowX flows in a React application

> [card] [React Native Renderer](/5.9/sdks/react-native-renderer)
>
> Embed FlowX flows in a React Native application

> [card] [Angular Renderer](/5.9/sdks/angular-renderer)
>
> Embed FlowX flows in an Angular application

> [card] [iOS Renderer](/5.9/sdks/ios-renderer)
>
> Embed FlowX flows in a native iOS app

> [card] [Android Renderer](/5.9/sdks/android-renderer)
>
> Embed FlowX flows in a native Android app

**Use this when:** the UI your end users see should be driven by FlowX (forms, screens, navigation, validation).

**Do not use this when:** you only need a backend/server-to-server integration with no UI.

***

## 2. Trigger a process via REST

Start a process programmatically from any HTTP-capable code (backend service, CLI, scheduled job, partner system).

**1. Get the build info**

Call **[Get Build Info](/5.9/docs/api/start-process/get-build-info)** with the workspace ID and app ID to retrieve the active `buildId`. The active policy determines which build is currently live for the runtime.

**2. Start the process**

Call **[Start process by build id and process name](/5.9/docs/api/start-process/rest2)** with the `appId`, `buildId`, and process definition name. The response contains the new process instance UUID.

For UI-action scenarios where the process should inherit a resource definition from a related instance, see [Start with resource definition and inherit values](/5.9/docs/api/start-process/start-process-rdi-inherit).

**3. Locate the IDs you need**

If you do not know your `workspaceId`, `appId`, or process definition name, see the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide.

**Use this when:** another service needs to kick off a FlowX process and the user-facing UI (if any) is handled separately.

**Do not use this when:** you are tempted to keep polling the runtime to track the process — switch to Kafka events or use the SDK instead.

***

## 3. Trigger a process from an incoming webhook

If the external system can call an HTTP endpoint, FlowX exposes a Webhook Gateway URL per resource definition. The system POSTs to the URL, FlowX starts the process. No code on your side beyond configuring the call.

> [card] [Incoming Webhooks](./incoming-webhooks)
>
> Configure webhook-triggered processes, secure them with API keys

**Use this when:** integrating with a third-party SaaS that supports outbound webhooks (Slack, GitHub, payment providers, custom apps).

**Do not use this when:** the calling system is your own backend that already speaks Kafka — pattern 4 is more efficient.

***

## 4. Trigger a process from a Kafka event

Build a custom integration (Connector microservice) that publishes to a Kafka topic the FlowX engine listens on, or wire an existing event stream into the engine through a topic naming convention.

> [card] [Custom integrations and Kafka topics](./integrations-overview)
>
> Custom integrations overview, topic naming, Connector quickstart

**Use this when:** your architecture is already event-driven and you want FlowX to react to events alongside other consumers.

***

## 5. React to FlowX events

Run a downstream service that consumes Kafka events emitted by the FlowX engine — for example, audit forwarding, metrics, or notifications.

See the [custom integrations overview](./integrations-overview) for topic naming and event types.

**Use this when:** you need to mirror or transform FlowX activity into another system without coupling it to a synchronous API call.

***

## Authentication

All public REST endpoints require a Bearer token issued by the configured identity provider (Keycloak by default). See [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution) for setup, and the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide for retrieving the values you need to authenticate from outside the platform.

> [!NOTE]
>
> The reference pages linked above cover the most common public endpoints (build info + process start variants). FlowX exposes additional public endpoints — for example, starting workflows, fetching task views, and retrieving public data-model paths — that are not yet documented end-to-end. If you need one of those, contact the platform team and we will add it to the reference set.

***

## Frequently asked

> [accordion] How do I know when a process I started has finished or what data it produced?
>
> Do not poll runtime query endpoints from your own code. The supported approaches are:
>
> * If you need real-time process state in a UI, use a [Renderer SDK](#1-embed-the-flowx-ui-with-an-sdk) — it handles state for you.
> * If you need to react to completion in another service, consume the relevant Kafka event (see pattern 5).
> * If you need a callback to your own HTTP endpoint, model that as an explicit step in the process (a Service Task that calls your URL when the process reaches that node).

> [accordion] Can I build my entire UI in React without using the FlowX renderer?
>
> You can, but you will not get FlowX's UI state management, validation, navigation, or form generation — those live inside the renderer. If you only need to start processes from a custom UI (not render FlowX-driven screens), pattern 2 is enough. If you need FlowX-driven screens, use the React Renderer.

> [accordion] Where do I find my appId and buildId?
>
> See the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide. The `buildId` returned from [Get Build Info](/5.9/docs/api/start-process/get-build-info) is the one to use when starting a process from a frontend or external app.

***

## Related resources

> [card] [Public REST API reference](/5.9/docs/api/start-process/get-build-info)
>
> Endpoint specs for build info and starting processes

> [card] [SDKs overview](/5.9/sdks/sdks-overview)
>
> React, React Native, Angular, iOS, Android renderer SDKs

> [card] [Incoming Webhooks](./incoming-webhooks)
>
> Trigger processes from external HTTP callbacks

> [card] [Custom integrations](./integrations-overview)
>
> Kafka-based Connectors and topic naming


# Custom Agent node
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/custom-agent-node

Create AI agents with advanced capabilities using MCP tools to execute complex tasks in Integration Designer workflows.

## Overview

The **Custom Agent Node** is a specialized Integration Designer workflow node that enables you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.

![Custom Agent Node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca1.png)

## Key features

* **Tool Access**: Connect to one or more MCP servers to provide tools to the AI agent
* **Reasoning & Acting**: Built-in ReAct (Reasoning and Acting) model for intelligent decision-making
* **Multi-Step Execution**: Agent can use multiple tools in sequence to accomplish complex tasks
* **Structured Responses**: Define expected response schemas for consistent output
* **Execution Tracking**: Monitor tool usage and agent reasoning in console logs

> [!NOTE]
>
> Custom Agent nodes automatically apply the ReAct (Reasoning and Acting) model, which enables the AI agent to think through problems, decide which tools to use, and take actions based on the results.

## When to use custom agent nodes

Custom Agent nodes are ideal for scenarios where you need:

* **Dynamic Decision Making**: The agent determines which tools to use based on the task
* **External System Integration**: Access external APIs, databases, or services through MCP tools
* **Complex Multi-Step Operations**: Execute workflows that require multiple tool interactions
* **Autonomous Problem Solving**: Let the AI agent figure out how to accomplish a goal using available tools

### Example use cases

> [accordion] Customer Support Automation
>
> Create an agent that can:
>
> * Look up customer information from a CRM system
> * Check order status from an order management system
> * Generate personalized responses based on the gathered data
> * Create support tickets if needed

> [accordion] Data Analysis & Reporting
>
> Build an agent that:
>
> * Queries multiple databases for relevant data
> * Performs calculations and aggregations
> * Generates charts and visualizations
> * Produces formatted reports

> [accordion] Process Automation
>
> Design an agent that:
>
> * Monitors external systems for events
> * Validates data across multiple sources
> * Triggers actions in integrated systems
> * Handles exceptions and error cases

> [accordion] Integration Orchestration
>
> Implement an agent that:
>
> * Coordinates operations across multiple systems
> * Transforms data between different formats
> * Handles complex business logic
> * Manages transaction workflows

## Adding a Custom Agent node

To add a Custom Agent node to an Integration Designer workflow:

1. Open **Integration Designer** and navigate to your workflow
2. Click **Select Next Node** dropdown
3. Select **Custom Agent** from the available node types
4. Configure the node settings

![Add Custom Agent](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca2.png)

> [!NOTE]
>
> Custom Agent nodes are available in Integration Designer workflows, alongside other node types like REST API Call, Script, Condition, and Subworkflow nodes.

> [!TIP]
>
> The Custom Agent node is specifically designed for Integration Designer workflows. For BPMN process workflows, use the **Start Integration Workflow** action to invoke workflows that contain Custom Agent nodes.

## Configuring a Custom Agent node

After adding a Custom Agent node to your Integration Designer workflow, configure it through the node configuration panel:

**instructions** `string` *required*

The agent's role, tasks, and expected input/output. Sent to the LLM as the **System message** and **cached** between executions to reduce cost and latency, so `${variable}` placeholders are not allowed in this field — use **Context** for dynamic values.

The field is limited to 10,000 characters (SaaS · 5.11).&#x20;

Describe:

* The agent's role and the task it should accomplish
* Specific requirements or constraints
* Expected output format and edge-case handling

**Example:**

```
You are a customer order assistant. For each request, retrieve the
customer's recent order history and summarize it as a JSON object
with fields: customerId, totalOrders, totalValue, recentOrders.
If the customer is not found, return an error explaining the
customer ID is invalid.
```

**context** `string`

The per-execution prompt text, located inside the **Background** section of the node configuration panel. Supports `${variable}` placeholders for values from process data. Sent to the LLM as the **User message** on every execution and is **not** cached.

**Example:**

```
Customer ID: ${application.customerId}
Look back window: last 6 months
```

The **Background** section also exposes the Knowledge Base selector and the **Use only referenced values as input** toggle. In Chat Driven workflows, it additionally contains the **Use conversation memory** and **Use uploaded files** toggles.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

Selecting multiple Knowledge Bases makes each one available to the agent as its own retrieval tool, so the agent queries all of them. On earlier releases, only the first selected Knowledge Base is used.

**useUploadedFiles** `boolean`

Lets the agent search the files the end user attached during the conversation. In the Designer this is the **Use uploaded files** toggle, in the **Background** section, with the tooltip *When enabled, the agent can reference documents uploaded by the user during the conversation.*

**Default:** on. A Custom Agent created in a Chat Driven workflow starts with the toggle enabled, so uploaded files are searchable unless you turn it off.

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The toggle appears in Chat Driven workflows only. A Custom Agent in a standard workflow has no conversation to draw uploads from, so the toggle is not shown at all.

Attached files are extracted and indexed into a Knowledge Base scoped to the chat session, so this is a retrieval source rather than a way of handing a file to the model. For how uploads reach the session, see [File uploads](/5.9/ai-platform/chat-driven-workflows#file-uploads).

Turning the toggle on reveals a retrieval block of its own, separate from the settings on any Knowledge Base you attached:

| Setting | Description | Default |
| - | - | - |
| **Search Type** | How the uploaded content is searched: **Hybrid**, **Semantic** or **Keywords**. | `Hybrid` |
| **Number of Chunks** | How many chunks to retrieve per search. | `4` |
| **Min Relevance Score** | The relevance score, as a percentage, a chunk must reach to be returned. | `50` |
| **Use Re-rank** | Re-order the retrieved chunks by relevance before they reach the model. | `false` |

> [!NOTE]
>
> This block has no **Metadata Filters** control, unlike the one on an attached Knowledge Base. There is nothing to configure beyond the four settings above.

### Knowledge base retrieval settings

When one or more Knowledge Bases are attached, the **Background** section shows a retrieval block that applies to them:

| Setting | Description | Default |
| - | - | - |
| **Search Type** | How the Knowledge Bases are searched: **Hybrid**, **Semantic** or **Keywords**. | `Hybrid` |
| **Number of Chunks** | How many chunks each retrieval returns. | `4` |
| **Min Relevance Score** | The relevance score, as a percentage, a chunk must reach to be returned. | `50` |
| **Use Re-rank** | Re-order the retrieved chunks by relevance before they reach the model. | `false` |
| **Metadata Filters** | A metadata predicate applied to every retrieval, so the agent only searches the slice of the Knowledge Base you scope it to. | — |

#### Filtering options

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Filtering options** decides who writes that metadata filter:

* **Manual** (the default) applies the **Metadata Filters** you configure.
* **Agentic** lets the agent write its own filter at run time from the Knowledge Base's metadata keys. The **Metadata Filters** control disappears, and the panel notes `Agent builds the filter at runtime`.

> [!WARNING]
>
> **For per-tenant or per-run isolation, use Manual.** A model-authored filter that omits your scoping condition is a filter that does not isolate. Agentic filtering narrows retrieval for relevance; it is not an access-control mechanism.

### Agentic knowledge base search

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When a Custom Agent has one or more Knowledge Bases attached, you can turn on **Enable agentic knowledge base search** in the **Background** section. Agentic search is off by default; when it is off, each Knowledge Base is queried once with a plain single-pass retriever.

When agentic search is on, the agent breaks the question into sub-queries, searches and grades the results for relevance, and retries with reworded queries if the first pass finds nothing useful. It is better on complex questions, but it is slower and uses more model calls.

> [!NOTE]
>
> Agentic search is fail-open: it never returns worse results than the plain retriever would have. It also returns the same chunk metadata (chunk id, source id, and relevance score), so citations and telemetry are unchanged.

When **Enable agentic knowledge base search** is on, an **Additional controls** row appears with a **Settings** button. Open it to configure two controls in the settings dialog:

| Setting | Description | Default |
| - | - | - |
| **Max attempts** | How many retrieval passes the agent may run. The first pass always includes the original question; extra passes reword the query and retry only if earlier passes find nothing relevant. | `1` |
| **Subqueries per attempt** | How many sub-queries the agent generates per pass to search the Knowledge Base in parallel. | `3` |

> [!TIP]
>
> Start with the defaults. Raise **Max attempts** only for questions where a single pass regularly misses relevant content, since each extra pass adds model calls and latency.

![Agentic knowledge base search enabled, with Max attempts and Subqueries per attempt settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca_enable_agentic_search.png)

![Additional controls Settings dialog for agentic knowledge base search](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca_enable_agentic_additional_settings.png)

![The Add tool menu on the Custom Agent node, offering MCP Server, Workflow, Function, Web Search, and Built-in Tools](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ca-add-tool-menu.png)

**mcpServers** `array`

One or more MCP servers whose tools will be available to the AI agent.

**Configuration:**

* Select from locally defined MCP servers
* Include MCP servers from dependency libraries
* Multiple selections allowed

> [!NOTE]
>
> Only enabled tools from the selected MCP servers will be available to the agent. Tools can be managed in the MCP server details page.

**workflowTools** `array`

FlowX workflows attached to the agent as callable tools. When the agent decides a task needs one of these workflows, it calls the workflow like any other tool, passing arguments that match the workflow's input parameters.

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Configuration:**

* Open the **Tools** section of the node configuration panel and add one or more workflows.
* For each attached workflow, fill in the **When should the agent use this workflow?** field. This text tells the agent what the workflow does and when to reach for it, so write it as guidance the model can act on. Maximum 2,000 characters.
* A workflow's input parameters (defined on its Start node) become the tool's arguments. The agent fills them in from its reasoning when it makes the call.

> [!NOTE]
>
> A workflow with no configured input parameters cannot be attached as a tool. Add at least one input parameter to the workflow's Start node to make it eligible. Ineligible workflows still appear in the list, greyed out and with the note `Workflows with no configured input parameters are not eligible to be used.`, so you can see what needs fixing rather than wondering why a workflow is missing.

Two kinds of workflow are left out of the list entirely:

| Not listed | Why |
| - | - |
| The workflow you are editing | An agent cannot attach its own workflow as one of its tools. |
| Chat Driven workflows | Only standard workflows can be attached. A conversational workflow is started by a chat session, not by a tool call. |

> [!NOTE]
>
> A Custom Agent can have at most **10** workflow tools attached.

![Tools section of a Custom Agent node with an attached workflow tool card showing its when-to-use text, next to built-in tool category cards](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca-workflow-tools.png)

**functionTools** `array`

Reusable functions attached to the agent as callable tools. Reach for one when the work is deterministic and you would rather the agent call your code than reason its way to the answer.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Configuration:**

* Open the **Tools** section of the node configuration panel, choose **Function**, and pick a function from the list.
* Fill in the **When should the agent use this function?** field. Maximum 2,000 characters.
* The function's input parameters become the tool's arguments. The agent fills them in from its reasoning when it makes the call.

Functions defined in the project and functions coming from libraries both appear in the list.

> [!NOTE]
>
> A function is eligible only if it is **typed on both sides**: it needs an input slice and an output slice, each with at least one field. Functions that are not typed do not appear in the list at all, and a project with none shows `No eligible functions available`.

**Write a description on the function itself.** As with a workflow tool, the text the agent reads comes from the function's own description, joined with the when-to-use text you enter here. A function with no description is still attachable, but the tool card warns `This function has no description. Use Go to to open the function and add one.` and the agent is left with only the when-to-use text to go on.

> [!NOTE]
>
> The ten-tool limit on this page counts **workflow** tools only. Attaching a function does not consume one of those slots.

![Add tool menu open on the Function option, listing a local reusable function marked as already added, with the attached function tool card and its when-to-use text below](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca-function-tools.png)

**builtinToolCategories** `array`

Gives the agent ready-made helper tools, chosen by category, so exact work such as date math or regex matching runs as code instead of being estimated by the model. In the Designer, select **Add tool** → **Built-in Tools** and toggle the categories you want. Each category row lists the tools it contains, and a card is shown per selected category.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Selection is opt-in and per node: the agent gets every tool in the categories you selected, and nothing is added implicitly. A node with no tools selected keeps the lighter non-agentic execution path.

| Category | Tools |
| - | - |
| **Math tools** | Calculator, Compare, Unit convert |
| **List tools** | Filter, Sort list, List aggregate |
| **Date tools** | Business days, Current date and time, Date difference, Date sequence, Date shift, Duration, Format date, Parse date, Period bounds, Timezone convert |
| **Text tools** | Fuzzy match, Regex extract, Regex match |
| **Web search** | Web search |

The categories and their contents are served by the AI Platform, so the list can grow without a Designer change. A category is grouping only: what the agent runs is the tools themselves.

> [!NOTE]
>
> **Before FlowX.AI 5.12**, built-in tools were two toggles introduced in 5.10: **Use Web Search Tool** and **Use built-in tools**, the latter enabling a fixed set of four (calculator, compare, sort, filter). Web search is now the **Web search** category rather than a separate mechanism. A node last saved with the old toggles needs no edit: **Use built-in tools** maps to the **Math tools** and **List tools** categories, and **Use Web Search Tool** to **Web search**. Once you save a category selection, it becomes the node's source of truth.

**responseSchema** `string` *required*

JSON Schema defining the expected structure of the agent's response.

This ensures the agent returns data in a consistent, predictable format that can be easily processed by subsequent nodes.

**Example Schema:**

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "customerInfo": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "email": { "type": "string" }
      }
    },
    "orderSummary": {
      "type": "object",
      "properties": {
        "totalOrders": { "type": "number" },
        "totalValue": { "type": "number" },
        "recentOrders": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "orderId": { "type": "string" },
              "date": { "type": "string" },
              "total": { "type": "number" }
            }
          }
        }
      }
    }
  },
  "required": ["customerInfo", "orderSummary"]
}
```

**responseKey** `string` *required*

The key in the process data where the agent's response will be stored.

**Example**: `agentResponse`, `customerData`, `analysisResults`

If the key already exists in the process data, it will be overwritten with the agent's response.

### Show Reasoning

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Turn on **Show Reasoning** to have the agent state its reasoning before it answers. The reasoning is captured in the run log and on the node's completion event, and it is then removed from the agent's output.

**Show Reasoning** does not change the structured response stored at the response key, and in Chat Driven workflows it does not change the reply shown to the user. It only surfaces the model's reasoning summary for review in the [Console Logs](#monitoring-agent-execution).

> [!NOTE]
>
> When the resolved model is a reasoning model, its reasoning summary is returned on the completion event regardless of this toggle. **Show Reasoning** additionally asks non-reasoning models to state their reasoning so it can be captured the same way.

![Show Reasoning toggle in the Custom Agent node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/custom_agent_node_show_reasioning_prop.png)

![Agent reasoning summary surfaced in the run log](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca_run_log_reasoning.png)

![Custom Agent AI Config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca3.png)

## How custom agent nodes execute

When a Custom Agent node is executed in an Integration Designer workflow, the following process occurs:

**1. Initialization**

The FlowX Engine sends the Instructions (as the System message), the Context (as the User message), and the available tools to the AI Service.

**2. Reasoning**

The AI agent analyzes the prompt and determines which tools it needs to use and in what order.

**3. Tool Execution**

The agent requests tool execution through the MCP server:

* Agent provides input parameters based on its reasoning
* MCP server executes the tool
* Results are returned to the agent

**4. Iteration**

The agent evaluates the results and decides whether to:

* Use additional tools to gather more information
* Process the data and formulate a response
* Handle any errors or unexpected results

**5. Response Generation**

Once the agent has all necessary information, it generates a structured response according to the defined schema.

**6. Data Storage**

The response is stored in the process data at the specified response key and the workflow continues.

> [!NOTE]
>
> The agent's reasoning process, tool invocations, and results are all logged in the console for debugging and monitoring purposes.

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

If the AI service can't be reached, the platform retries the Custom Agent node automatically. To see the defaults and change them from the node's **Settings** tab, see [What happens when an AI node can't reach its AI service?](/5.9/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).

## Monitoring agent execution

After running a workflow with a Custom Agent node, you can monitor its execution in the **Console Logs**:

### Node logs tab

The **Logs** tab displays:

* **Execution Status**: Success, failure, or in-progress
* **Duration**: Time taken to complete the node execution
* **Tool Usage Summary**: Quick overview of which tools are used during the execution
* **Instructions** and **User Message**: The prompt the node sent to the model
* **Response schema**: The schema the response must follow, when the node has one
* **Standard Output**: Agent's final response

![Agent Node Logs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca5.png)

### Tools tab

> [!NOTE]
>
> The **Tools** tab is only displayed when MCP tools have been used during execution.

For each tool invocation, you can see:

**Tool** `string`

The name of the tool that was invoked.

**Thoughts** `string`

The AI agent's reasoning for using this tool - why it decided this tool was necessary and what it hoped to accomplish.

**Example**: "I need to retrieve the customer's information from the CRM system to get their contact details and account status."

**Input** `object`

The parameters sent by the AI agent to the MCP tool.

**Example**:

```json theme={"dark"}
{
  "customerId": "CUST-12345",
  "includeOrders": true
}
```

**Output** `object`

The response received from the MCP tool for the AI agent to interpret.

**Example**:

```json theme={"dark"}
{
  "customer": {
    "id": "CUST-12345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "tier": "premium"
  },
  "orders": [
    {
      "orderId": "ORD-001",
      "date": "2025-03-15",
      "total": 299.99
    }
  ]
}
```

![Agent Tools Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca4.png)

### Workflow-level logs

If the Custom Agent node is part of a larger workflow, tool usage information is also displayed at the workflow level:

1. Navigate to the workflow instance in Console Logs
2. View the workflow's **Tools** tab for an aggregated view of all tool usage
3. Drill down into specific nodes to see detailed tool execution

### How workflow tools run

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When the agent calls a workflow tool, FlowX starts a fresh top-level run of that workflow and passes the agent's arguments to it. The workflow runs to completion and its output is returned to the agent, which uses it to continue reasoning or to produce its final response.

Each workflow-tool call is recorded in the **Console Logs**. The call appears in the agent node's **Tools** tab, and the workflow run it triggered is linked by its workflow instance identifier so you can open the child run and inspect it.

> [!WARNING]
>
> **Give the workflow output parameters, not just input parameters.** Output parameters are configured in the **Output Parameters** tab of the workflow's Data Model, and only input parameters are checked when you attach the tool. A workflow with no output parameters attaches, runs, and reports the call as successful, but hands the agent an empty result. The agent then reasons on nothing and the cause is not obvious from the agent's own logs, so check the child run's output when a tool call looks successful but the answer ignores it.

![Run Logs panel on the agent node's Tools tab: a workflow-tool call whose name links to the child run, with the output JSON showing the child workflow instance identifiers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca-workflow-tool-console.png)

## Best practices

### Writing effective Instructions

> [!TIP]
>
> **Be Specific**: Clearly define what the agent should accomplish
>
> ```
> Good: "Retrieve customer order history for the last 6 months and calculate total spend"
> Avoid: "Get customer info"
> ```

> [!TIP]
>
> **Set Expectations**: Describe the expected output format
>
> ```
> "Return a summary with: customer name, total orders, and average order value"
> ```

> [!TIP]
>
> **Handle Edge Cases**: Include guidance for error scenarios
>
> ```
> "If the customer is not found, return an error message explaining that 
> the customer ID is invalid"
> ```

> [!WARNING]
>
> Don't put `${variable}` placeholders in Instructions — they're rejected by the form because Instructions is the cached System message. Put per-execution values in **Context** instead.

### Writing effective Context

> [!TIP]
>
> **Pass per-request values via placeholders**: keep the dynamic surface area small and named
>
> ```
> "For customer ${application.customerId}, check pending orders 
> from the ${application.orderSystem} system"
> ```

> [!TIP]
>
> **Use "Use only referenced values as input"** to send just the placeholders you reference, instead of the entire node input — narrows the model's context window and reduces token cost.

### Selecting MCP servers

> [!TIP]
>
> **Relevance**: Only include MCP servers whose tools are relevant to the agent's task

> [!TIP]
>
> **Minimize Scope**: Fewer tools = faster decision-making and more predictable behavior

> [!TIP]
>
> **Tool Availability**: Ensure required tools are enabled in the MCP server configuration

### Defining response schemas

> [!TIP]
>
> **Match Use Case**: Design the schema to match downstream data requirements

> [!TIP]
>
> **Required Fields**: Mark essential fields as required in the schema

> [!TIP]
>
> **Type Safety**: Use appropriate JSON Schema types for validation

> [!TIP]
>
> **Documentation**: Add descriptions to schema properties for clarity

## Prompt suggestions

When a Custom Agent node has **Send as chat reply** enabled, you can configure it to generate recommended follow-up prompts alongside its chat response. These appear as clickable suggestion chips in the chat UI, guiding users toward relevant next steps in the conversation.

### How it works

When prompt suggestions are enabled:

1. The agent generates both a text reply and a list of follow-up suggestions in a single response
2. Suggestions appear as clickable chips below the agent's reply in the chat UI
3. Clicking a suggestion sends its content as the user's next message, continuing the conversation
4. Suggestions are one-time use — they disappear after one is clicked

### Configuring prompt suggestions

Prompt suggestions are configured through a **satellite panel** that appears on the workflow canvas, connected to the Custom Agent node.

**1. Enable Send as chat reply**

In the Custom Agent node configuration, toggle **Send as chat reply** to **ON**. This is required for prompt suggestions to be available.

**2. Enable prompt suggestions**

Toggle **Prompt Suggestions** to **ON** in the Response section. A satellite panel appears on the canvas, connected to the Custom Agent node.

**3. Configure the satellite panel**

The satellite panel contains the following settings:

**instructions** `string` *required*

Instructions that guide the agent on what kind of follow-up prompts to generate.

**Default:** `Generate contextual follow-up replies the user is most likely to take next. Focus on actionable next steps, not clarifying questions.`

Supports `${paramName}` interpolation for dynamic values from the process data.

**maxSuggestions** `number`

Maximum number of suggestions the agent should generate per reply.

**Default:** `3` (range: 1-5)

**maxCharacters** `number`

Maximum character length for each suggestion label displayed in the chat UI.

**Default:** `120` (range: 10-200)

![Prompt Suggestions satellite panel on a Custom Agent node in a chat-driven workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/prompt_suggestions.png)

> [!TIP]
>
> The satellite panel is draggable on the canvas. Its position is saved automatically. When you move the parent Custom Agent node, the satellite moves with it.

### Response structure

When prompt suggestions are enabled, the response schema is auto-generated. The agent's output is stored at the configured response key as a structured object instead of a plain string:

```json theme={"dark"}
{
  "reply": "The Pro plan costs $49/month and includes unlimited agents...",
  "suggestions": [
    {
      "label": "Compare all plans",
      "content": "Show me a detailed comparison of the Starter, Pro, and Enterprise plans."
    },
    {
      "label": "How do I upgrade?",
      "content": "What are the steps to upgrade my current account to the Pro plan?"
    }
  ]
}
```

| Field | Description |
| - | - |
| `reply` | The agent's text response displayed in the chat |
| `suggestions[].label` | Short text displayed on the suggestion chip in the chat UI |
| `suggestions[].content` | Full prompt sent to the agent when the user clicks the suggestion. If omitted, `label` is used |

> [!NOTE]
>
> When prompt suggestions are enabled, the response schema is managed automatically — you cannot edit it manually. Turning off prompt suggestions restores the standard editable response schema.

### Chat behavior

* **Display**: Suggestions render as clickable chips below the agent's reply message
* **Click**: Clicking a chip displays the `label` as the user's message and sends the `content` to the agent as the next input
* **Memory**: The `content` (not the label) is stored in conversation memory for context continuity
* **Conversation restore**: When restoring a previous conversation, suggestion labels are shown for past user selections, but active suggestions on the last message are not re-displayed

***

## Limitations

| Constraint | Value | Details |
| - | - | - |
| **Maximum tool calls per execution** | `20` | The agent can make up to 20 tool calls in a single workflow execution. If the limit is reached, the execution stops and returns the last available result. Configurable via the `AGENT_BUILDER_MAX_TOOL_CALLS` environment variable on the AI platform service. |

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Two additional guardrails apply when an agent uses **workflow tools**:

* **Workflow-tool fan-out limit.** Across a single node run, the agent can make at most **10** workflow-tool calls in total. The budget is shared by every workflow tool attached to the agent, so it is a total rather than a per-tool allowance, and it is separate from the overall tool-call limit above. A call is counted when it is attempted, including one that then fails, so a retrying tool spends the budget. Going over the limit does not fail the node: the call is not dispatched and the agent is told to answer with what it already has, keeping its earlier tool results and reasoning. Configurable via the `WORKFLOW_TOOL_MAX_CALLS` environment variable on the AI platform service. Function tools do not draw on this budget.
* **Recursion depth limit.** A workflow tool can itself contain a Custom Agent that calls further workflow tools. These call chains are limited to a depth of **5**. The depth is fixed when a run starts and checked once, so a run that is too deep fails immediately at its Start node with `WORKFLOW_TOOL_RECURSION_LIMIT: Maximum workflow-tool recursion depth reached`. Only runs started by a workflow-tool call are counted, and the limit is separate from, and much lower than, the subworkflow depth limit. Configurable via the `FLOWX_WORKFLOW_MAXWORKFLOWTOOLDEPTH` environment variable on the Integration Designer service.

***

## Troubleshooting

> [accordion] Agent Not Using Expected Tools
>
> **Problem**: The agent doesn't use the tools you expected.
>
> **Possible Causes**:
>
> * Instructions don't clearly indicate the need for specific tools
> * Tools are disabled in the MCP server configuration
> * Agent found an alternative approach
>
> **Solutions**:
>
> * Review and refine the Instructions to be more specific about when each tool should be used
> * Check MCP server tool status (enabled/disabled)
> * Review agent reasoning in the Tools tab to understand its decision-making

> [accordion] Response Doesn't Match Schema
>
> **Problem**: The agent's response doesn't conform to the defined schema.
>
> **Possible Causes**:
>
> * Schema is too restrictive or doesn't match the prompt
> * Tools return unexpected data structures
> * Agent encountered errors during execution
>
> **Solutions**:
>
> * Verify schema matches what the prompt asks for
> * Test tools independently to verify their outputs
> * Review error logs for execution issues
> * Adjust schema or prompt to align better

> [accordion] Agent Execution Times Out
>
> **Problem**: The Custom Agent node takes too long to execute.
>
> **Possible Causes**:
>
> * Too many MCP servers/tools available
> * Complex multi-step operations
> * External systems responding slowly
>
> **Solutions**:
>
> * Limit MCP servers to only those needed
> * Break complex tasks into multiple simpler agent nodes
> * Optimize external system performance
> * Increase timeout configuration if appropriate

> [accordion] Tool Invocation Fails
>
> **Problem**: A tool invocation fails during agent execution.
>
> **Possible Causes**:
>
> * MCP server connection issues
> * Invalid parameters sent by agent
> * Tool authentication or permission errors
>
> **Solutions**:
>
> * Test MCP server connection in Integration Designer
> * Review tool input schema and agent's input in the Tools tab
> * Verify authentication credentials for the MCP server
> * Check tool-specific error messages in console logs

## Next steps

> [card] [MCP Integration Overview](./mcp-integration/mcp-integration-overview)
>
> Learn about MCP integration capabilities

> [card] [MCP Data Sources](./mcp-integration/adding-mcp-data-source)
>
> Add, configure, and manage MCP servers and tools

> [card] [Integration Designer](./integration-designer)
>
> Learn about Integration Designer workflows

## Related resources

> [card] [Start Integration Workflow](../../building-blocks/actions/start-integration-workflow)
>
> Learn how to call Integration Designer workflows from BPMN processes


# Data sources and endpoints in Integration Designer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints

Define data sources and REST endpoints in Integration Designer: caching, variables, parameter types, enum mappers, and authorization methods.

Data sources and endpoints are the connection layer of [Integration Designer](./integration-designer). Workflows call the endpoints you define here.

## Data Sources

A data source is a collection of resources—endpoints, authentication, and variables—used to define and run integration workflows.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds1.png)

## Creating a new data source definition

With **Data Sources** feature you can create, update, and organize endpoints used in API integrations. These endpoints are integral to building workflows within the Integration Designer, offering flexibility and ease of use for managing connections between systems. Endpoints can be configured, tested, and reused across multiple workflows, streamlining the integration process.

<video />

Go to the **Data Sources** section in FlowX Designer at **Workspaces** -> **Your workspace** -> **Projects** -> **Your project** -> **Integrations** -> **Data Sources**.

> [!NOTE]
>
> The data sources resource page uses a tile-based creation flow and a unified details view.
>
> * **Creation modal**: clicking **New Data Source** opens a modal where each connector type appears as its own tile with an icon. Use the search box to filter tiles by name. Pick a tile, give the data source a name, and click **Create** to open the configuration page.
> * **List view**: each entry shows the connector's icon and type. Use the type filter at the top to scope the list to a specific connector (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.).
> * **Unified settings layout**: every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
> * **Save with incomplete configuration**: you can create and save a data source even when some fields (credentials, endpoints) are not yet available. The data source can be referenced in workflows and processes immediately, but it will only operate at runtime once required fields are filled in.

## Data sources types

There are multiple types of data sources available:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds5.png)

> [card] RESTful System
>
> Connect to external REST APIs. Configure endpoints, authentication, and parameters for HTTP-based integrations. **Detailed in this document below.**

> [card] [SOAP System](./soap-system)
>
> Connect to SOAP web services by importing a WSDL and invoking the discovered operations from workflows (SaaS · 5.10).

> [card] [FlowX Database](./flowx-database)
>
> Store and retrieve structured data within FlowX using MongoDB collections. Share data across processes without external dependencies.

> [card] [Unmanaged MongoDB](./unmanaged-mongodb)
>
> Connect to externally managed MongoDB instances. Use your existing MongoDB infrastructure with the same CRUD operations as FlowX Database.

> [card] [Oracle Database](./oracle-database)
>
> Connect to independently managed Oracle databases and run saved SQL queries from workflows.

> [card] [PostgreSQL Database](./postgresql-database)
>
> Connect to independently managed PostgreSQL databases and run saved SQL queries from workflows (SaaS · 5.10).

> [card] [Db2 Database](./db2-database)
>
> Connect to independently managed IBM Db2 databases and run saved SQL queries from workflows.

> [card] [MCP Integration](./mcp-integration/mcp-integration-overview)
>
> Connect Model Context Protocol servers to enable AI agents to use external tools, databases, and services.

> [card] [FlowX Knowledge Base](./knowledge-base-integration/knowledge-base-overview)
>
> AI-powered contextual knowledge repositories for intelligent document search and retrieval in workflows.

> [card] [Email Trigger](./email-trigger)
>
> Start process instances automatically when emails are received. Connect to IMAP servers and monitor mailboxes for event-driven automation.

> [card] [Email Sender](./email-sender)
>
> Configure SMTP connections to send emails directly from processes, including replies to received emails.

> [card] [Incoming Webhook](./incoming-webhooks)
>
> Trigger processes from external systems via HTTP POST requests with API key authentication.

### RESTful System

Add a **New Data Source**, set the data source's unique code, name, and description:

* **Select Data Source**: RESTful System
* **Name**: The data source's name.
* **Code**: A unique identifier for the external data source.
* **Base URL**: The base URL is the main address of a website or web application, typically consisting of the protocol (`http` or `https`), domain name, and a path.
* **Description**: A description of the data source and its purpose.
* **Enable enumeration value mapping**: If checked, this system will be listed under the mapped enumerations. See [enumerations](../core-extensions/content-management/enumerations) section for more details.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds6.png)

> [!TIP]
>
> To dynamically adjust the base URL based on the upper environment (e.g., dev, QA, stage), you can use environment variables and configuration parameters. For example: `https://api.${environment}.example.com/v1`.
>
> Additionally, keep in mind that the priority for determining the configuration parameter (e.g., base URL) follows this order: first, input from the user/process; second, configuration parameters overrides (set directly on FlowX.AI designer or environment variables); and lastly, configuration parameters.

2. Set up authorization (Service Token, Bearer Token, or No Auth). In our example, we will set the auth type as a bearer and we will set it at system level:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/auth_bearer_token.png)

> [!TIP]
>
> The value of the token might change depending on the environment so it is recommended to define it at system level and apply [Configuration Parameters Overrides](../../projects/runtime/configuration-parameters-overrides) at runtime.

## Defining REST integration endpoints

In this section you can define REST API endpoints that can be reused across different workflows.

1. Under the **Endpoints** section, add the necessary endpoints for system integration.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/add_new_endpoint.png)

2. Configure an endpoint by filling in the following properties:
   * **Method**: GET, POST, PUT, PATCH, DELETE.
   * **Path**: Path for the endpoint.
   * **Parameters**: Path, query, and header parameters.
   * **Content type** (POST endpoints): **JSON**, **Raw**, **Multipart/Form-Data**, or **Binary**.
   * **Response**: JSON or Single binary file.
   * **Response example**: Body or headers.

> [!TIP]
>
> **Sending non-JSON text bodies** (XML, SOAP, plain text, `application/x-www-form-urlencoded`): set the **Content type** to **Raw**. The body is sent as-is, and FlowX preserves the `Content-Type` you set in the endpoint's request **Headers** rather than forcing one. (Earlier releases offered only JSON, Multipart/form-data, or Binary, so these payloads had to be wrapped as multipart.)
>
> For OAuth token endpoints that expect a form-urlencoded payload (e.g. `client_credentials` or `password` grant), prefer configuring the data source's **Authorization** settings instead of building the call by hand — FlowX handles the token request internally and applies the resulting access token to subsequent calls.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds11.png)

## REST endpoint caching

For GET endpoints, you can configure response caching to reduce redundant API calls, avoid rate limits, and lower operational costs. When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.

### Configuring cache Time-To-Live (TTL)

Choose between two TTL policies based on your use case:

> [tab] Expires After (Duration-Based)
>
> Cache responses for a specific duration after each request.
>
> **Configuration Options**:
>
> * **ISO Duration**: Use ISO 8601 duration format
>   * `PT1H` - Cache for 1 hour
>   * `PT30M` - Cache for 30 minutes
>   * `P1D` - Cache for 1 day
>   * `P1W` - Cache for 1 week
> * **Dynamic Duration**: Reference configuration parameters using `${myConfigParam}`
> * **Default**: `R/P1D` (1 day)
>
> **Use Case**: Ideal when you want consistent cache duration regardless of time of day.
>
> **Example**: Cache country list for 24 hours after each request
>
> ```
> P1D
> ```

> [tab] Expires At (Time-Based)
>
> Cache responses until a specific time with recurring patterns.
>
> **Configuration Options**:
>
> * **Expire Time**: Set the time when cache expires (format: `HH:MM`)
>   * `00:00` - Midnight
>   * `18:00` - 6 PM
>   * `08:00` - 8 AM
> * **Recurrency**: How often the pattern repeats (integer > 0, default: 1)
> * **Time Unit**: Choose from Day, Week, or Month (default: Day)
>
> **Use Cases**:
>
> * Data that updates at specific times (e.g., daily reports at midnight)
> * Batch processes that refresh data on schedule
> * Business hours data that changes after 5 PM
>
> **Example 1**: Cache until midnight every day
>
> ```
> Expire Time: 00:00
> Recurrency: 1
> Time Unit: Day
> ```
>
> **Example 2**: Cache until 6 PM every Friday
>
> ```
> Expire Time: 18:00
> Recurrency: 1
> Time Unit: Week
> ```

### Cache visibility and management

**Testing Modal**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Test%20Endpoint.png)

When testing endpoints, you can view:

* **Cache Status**: Whether results came from cache (hit) or external API (miss)
* **Cache Key**: Unique identifier for the cached response
* **TTL Information**: When the cache will expire
  * Duration-based: "Expires after PT10M" (10 minutes)
  * Time-based: "Expires at 23:00 on 2025-11-04"

**Workflow Console**

Monitor cache usage during workflow execution with the same detailed information visible in logs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Test%20Endpoint.png)

**Clear Cache**

Manually invalidate cached responses when needed:

* Available in the endpoint testing modal
* Available from the endpoint definition page
* Only visible when caching is configured

> [!TIP]
>
> Clear cache after updating data in the external system to ensure workflows fetch fresh data on the next request.

### How caching works

**1. First Request**

When a GET endpoint is called for the first time, FlowX.AI:

1. Calls the external API
2. Stores the response in cache with the configured TTL
3. Returns the response to the workflow

**2. Subsequent Requests**

If the cache is still valid (within TTL):

1. FlowX.AI returns the cached response immediately
2. No external API call is made
3. Response time is significantly faster

**3. Cache Expiration**

Once the TTL expires:

1. Next request fetches fresh data from the external API
2. Cache is updated with the new response
3. New TTL period begins

### Error handling

> [!WARNING]
>
> **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. Your workflows always receive correct data.

Automatic fallback scenarios:

* Cache service unavailable → Direct API call
* Cache corruption or invalid data → Direct API call
* Cache storage failure → Direct API call (with warning logged)

### Use cases

> [card] Reference Data
>
> Cache country lists, product catalogs, currency rates, or other reference data that changes infrequently

> [card] Rate Limit Compliance
>
> Stay within third-party API rate limits by reducing the number of requests

> [card] Cost Optimization
>
> Lower operational costs by reducing billable API calls to external services

> [card] Performance
>
> Improve workflow execution speed by eliminating network latency for cached responses

**Example**: An e-commerce platform caches product catalog data for 1 hour. With 1000 workflow executions per hour, caching reduces API calls from 1000 to just 1, saving 999 external calls while ensuring data freshness every hour.

## SQL operation caching

SQL data source operations support response caching with the same TTL policies as REST endpoints. On a SQL operation's details page, open the **Response Caching** section and toggle **Caching Enabled**, then choose a return policy (**Expires After** duration or **Expires At** time-based), exactly as for REST GET endpoints above. A **Clear cache** button invalidates cached responses on demand.

Caching is governed by three platform-wide settings on the `integration-designer` service:

| Environment Variable | Description | Default |
| - | - | - |
| `FLOWX_SQL_CACHE_ENABLED` | Global master switch for SQL operation caching. When `false`, per-operation caching is skipped and queries run live. | `true` |
| `FLOWX_SQL_CACHE_MAX_PAYLOAD_BYTES` | Maximum size of a cacheable result payload | `5242880` |
| `FLOWX_SQL_CACHE_MAX_DURATION` | Upper bound on the cache duration a single operation can request | `PT24H` |

> [!NOTE]
>
> Per-operation caching only takes effect when `FLOWX_SQL_CACHE_ENABLED` is `true`. If an operation has caching enabled while the global switch is off, the query runs live and a warning is logged.

## Extended response caching

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Response caching extends beyond GET REST endpoints and SQL operations to cover **POST** endpoints, Mongo read operations, and file storage read operations. These surfaces reuse the same TTL policies, **Clear cache** control, and automatic fallback behavior described above.

### POST endpoint caching

You can enable response caching on **POST** endpoints as well as GET endpoints. For a POST endpoint, the request body is part of the cache key, so calls to the same URL with different bodies are cached as separate entries and never return one another's response. GET requests carry no body, so their cache keys are unchanged.

### Mongo read caching

Database data source caching also applies to Mongo read operations: `FIND`, `FIND_ONE`, and `AGGREGATE`, alongside the SQL queries already covered above. Mutating operations (for example inserts, updates, and deletes) cannot be cached. Enable caching per operation in the **Response Caching** section of the operation's details page, exactly as for SQL operations. The same payload-size and duration caps apply to both SQL and Mongo caching.&#x20;

### File operation caching

File storage data source operations support response caching with the same TTL policies and controls as REST endpoints and database operations. Caching applies to read operations only:

| Operation | Cacheable | Notes |
| - | - | - |
| `LIST` | Yes | Caches the listing returned for the configured path. |
| `DOWNLOAD` | Yes | Caches only the document reference, never the file bytes (see below). |
| `UPLOAD` | No | Mutating operation. |
| `DELETE` | No | Mutating operation. |
| `MOVE` | No | Mutating operation. |

On a `LIST` or `DOWNLOAD` operation's details page, open the **Response Caching** section, toggle **Caching Enabled**, and choose a return policy (**Expires After** duration or **Expires At** time-based). A **Clear cache** button invalidates cached responses on demand, exactly as for REST endpoints and database operations.

> [!NOTE]
>
> For a `DOWNLOAD`, FlowX caches the document reference rather than the file content. On a cache hit, the workflow receives a fresh document created from the retained copy, so the read from remote storage is skipped while your workflow still gets a valid document to work with.

## Defining variables

The Variables tab allows you to store system-specific variables that can be referenced throughout workflows using the format `${variableName}`.

These declared variables can be utilized not only in workflows but also in other sections, such as the Endpoint or Authorization tabs.

> [!TIP]
>
> For example:
>
> * For our integration example, you can declare configuration parameters and use the variables to store your `tableId` and `baseId` and reference them the **Variables** tab.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds10.png)
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds8.png)
>
> * Use variables in the **Base URL** to switch between different environments, such as UAT or production.

## Endpoint parameter types

When configuring endpoints, several parameter types help define how the endpoint interacts with external systems. These parameters ensure that requests are properly formatted and data is correctly passed.

### Path parameters

Elements embedded directly within the URL path of an API request that acts as a placeholder for specific value.

* Used to specify variable parts of the endpoint URL.
* Defined with `${parameter}` format.
* Mandatory in the request URL.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds15.png)

> [!TIP]
>
> Path parameters must always be included, while query and header parameters are optional but can be set as required based on the endpoint's design.

### Query parameters

Query parameters are added to the end of a URL to provide extra information to a web server when making requests.

* Query parameters are appended to the URL after a `?` symbol and are typically used for filtering or pagination (for example, `?search=value`)
* Useful for filtering or pagination.
* Example URL with query parameters: [https://api.example.com/users?search=johndoe\&page=2](https://api.example.com/users?search=johndoe\&page=2).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds13.png)

> [!WARNING]
>
> These parameters must be defined in the Parameters table, not directly in the endpoint path.

#### URL encoding option

Each query parameter has an **Encode** option that controls whether the value is URL-encoded before being sent:

* **Encode enabled**: The system automatically URL-encodes the parameter value (special characters like spaces, `&`, `=` are converted to their encoded equivalents like `%20`, `%26`, `%3D`)
* **Encode disabled** (default): The value is sent as-is, allowing you to provide pre-encoded values

> [!TIP]
>
> Use the **Encode** option when your parameter values may contain special characters that need encoding. Disable it if you're already providing URL-encoded values or if the external API expects raw values.

> [!NOTE]
>
> To preview how query parameters are sent in the request, you can use the **Preview** feature to see the exact request in cURL format. This shows the complete URL, including query parameters.

### Header parameters

Used to give information about the request and to give instructions to the API of how to handle the request

* Header parameters (HTTP headers) provide extra details about the request or its message body.
* They are not part of the URL. Default values can be set for testing and overridden in the workflow.
* Custom headers sent with the request (for example, `Authorization: Bearer token`).
* Define metadata or authorization details.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds14.png)

### Body parameters

The data sent to the server when an API request is made.

* These are the data fields included in the body of a request, usually in JSON format.
* Body parameters are used in POST, PUT, and PATCH requests to send data to the external system (for example, creating or updating a resource).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ds16.png)

### Response body parameters

The data sent back from the server after an API request is made.

* These parameters are part of the response returned by the external system after a request is processed. They contain the data that the system sends back.
* Typically returned in GET, POST, PUT, and PATCH requests. Response body parameters provide details about the result of the request (for example, confirmation of resource creation, or data retrieval)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/response_body_param.png)

## Enum mapper

The enum mapper for the request body enables you to configure enumerations for specific keys in the request body, aligning them with values from the External System or translations into another language.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/enum_mapper.png)

On enumerations you can map both translation values from different languages or values for different source systems.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-10-27%20at%2012.42.28.png)

Make sure you have the enumerations created with corresponding translations and system values in your application already:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/2024-10-27%2012.41.08.gif)

> [!NOTE]
>
> Select whether to use in the integration the enumeration value corresponding to the External System or the translation into another language.
>
> For translating into language a header parameter called 'Language' is required to specify the language for translation.

### Translate response values

The **Response** tab has its own enum mapper when the response content type is **JSON**. It converts codes in the response body from the external system's values to FlowX enumeration codes, so the process receives the same codes it uses everywhere else.

Response mapping works only when **Enable enumeration value mapping** is turned on for the data source. It always maps source system values, never labels.

### Map child enumerations

Each mapping row has a **JSON Path** and a **Type**:

* **Enumeration**: the path holds a code of the enumeration selected in the **Enumeration** column.
* **Child Enumeration**: the path holds a code from a child collection. Set **Parent Path** to the path of the mapping row whose enumeration owns that child collection.

A child path is translated only when its parent path holds exactly one code. If the parent path holds several codes, for example an array, the parent codes are translated and the child values are sent unchanged.

### What the enum mapper doesn't translate

* Only the request body and the response body are translated. Query parameters, path parameters and headers are sent unchanged.
* Translation into a language applies to the request body only. Response values are never converted to labels.
* If a mapped path holds a code with no matching enumeration value, or a child code that isn't in its parent's child collection, the node that calls the endpoint fails with a translation error.

## Configuring authorization

* Select the required **Authorization Type** from a predefined list.
* Enter the relevant details based on the selected type (for example, Realm and Client ID for Service Accounts).
* These details will be automatically included in the request headers when the integration is executed.

## Authorization methods

The Integration Designer supports several authorization methods, allowing you to configure the security settings for API calls. Depending on the external system's requirements, you can choose one of the following authorization formats:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/auth_type.png)

### Service account

Service Account authentication requires the following key fields:

* **Identity Provider Url**: The URL for the identity provider responsible for authenticating the service account.
* **Client Id**: The unique identifier for the client within the realm.
* **Client secret**: A secure secret used to authenticate the client alongside the Client ID.
* **Scope**: Specifies the access level or permissions for the service account.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/auth_service_account.png)

> [!NOTE]
>
> When using Entra as an authentication solution, the **Scope** parameter is mandatory. Ensure it is defined correctly in the authorization settings.

### Basic authentication

* Requires the following credentials:
  * **Username**: The account's username.
  * **Password**: The account's password.
    * Suitable for systems that rely on simple username/password combinations for access.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/basic_auth.png)

### Bearer

* Requires an **Access Token** to be included in the request headers.
* Commonly used for OAuth 2.0 implementations.
* Header Configuration: Use the format `Authorization: Bearer {access_token}` in headers of requests needing authentication.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/token_bearer.png)

* System-Level Example: You can store the Bearer token at the system level, as shown in the example below, ensuring it's applied automatically to future API calls:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/bearer.png)

> [!TIP]
>
> Store tokens in a configuration parameter so updates propagate across all requests when tokens are refreshed or changed.
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/token_config_param.png)

### Certificates

Use this setup when the external system requires certificate-based security. It includes a Keystore (which holds the client certificate FlowX presents to the external system) and a Truststore (which holds the certificates FlowX trusts when validating that system). You can turn each on independently, based on what the integration requires.

On SaaS, certificates are configured as **Trust** and **Identity** instead, and existing settings are converted for you (SaaS · 6.0). See [Trust and identity certificates](#trust-and-identity-certificates).

**When to use what**

| The external system... | What you need |
| - | - |
| Requires you to present a client certificate (mutual TLS) | Keystore |
| Presents a certificate that is self-signed or issued by a private CA | Truststore |
| Both of the above | Keystore and Truststore |
| Has a publicly trusted certificate and doesn't ask for a client certificate | Neither. Leave **Use Certificate** off |

![Authorization tab showing certificates, truststore, and proxy configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/authorization_rest_all.png)

When the **Use Certificate** option is turned on, select a **Certificate type**:

* **Base64** (default for new configurations) — provide the certificate content directly as a base64-encoded string
* **Path** — provide the file system path to the certificate file

> [!NOTE]
>
> **Path** points to the filesystem of the Integration Designer service, not to your local machine: the file must be mounted into the service container (for example, through a Kubernetes secret and volume mount). On SaaS deployments, use **Base64**.

**Keystore credentials**

| Field | Base64 mode | Path mode |
| - | - | - |
| **Keystore Content (Base64)** | Base64-encoded keystore content | — |
| **Keystore Path** | — | File path, e.g., `/opt/certificates/testkeystore.jks` |
| **Keystore Password** | Password to unlock the keystore | Password to unlock the keystore |
| **Keystore Type** | `JKS` or `PKCS12` | `JKS` or `PKCS12` |

**Truststore credentials**

| Field | Base64 mode | Path mode |
| - | - | - |
| **Truststore Content (Base64)** | Base64-encoded truststore content | — |
| **Truststore Path** | — | File path, e.g., `/opt/certificates/testtruststore.jks` |
| **Truststore Password** | Password to access the truststore | Password to access the truststore |

All fields support `${configParam}` placeholders for dynamic per-environment resolution.

> [!TIP]
>
> Use [Configuration Parameters Overrides](../../projects/runtime/configuration-parameters-overrides) to manage certificate content and passwords across environments (Dev, UAT, Production) without changing the data source configuration. For example, store the base64 keystore content in a config parameter and reference it with `${keystoreContent}`.

![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)

**Preparing the stores**

If you received a client certificate and private key as separate PEM files, package them as a PKCS12 keystore:

```bash theme={"dark"}
openssl pkcs12 -export -in client.crt -inkey client.key -out keystore.p12 -name client
```

To trust a private CA, import its certificate into a truststore:

```bash theme={"dark"}
keytool -importcert -alias external-ca -file ca.crt -keystore truststore.jks -storepass <password>
```

For **Base64** mode, encode the resulting file and paste the output into the content field, or store it in a configuration parameter:

```bash theme={"dark"}
base64 -i keystore.p12
```

### TLS verification

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A REST data source can be told to stop checking the TLS certificate of the host it calls. Open the data source, go to **Settings**, and turn on **Skip verification** under **TLS Verification**.

With it on, the call accepts any certificate the target presents: self-signed, expired, or issued for a different hostname. It is the equivalent of `curl --insecure`, and it applies to the **host's** certificate, not to the client certificate you present.

> [!WARNING]
>
> Skipping verification removes protection against man-in-the-middle attacks, because the call can no longer tell the intended host from anything that intercepts it. Turn it on only for hosts you control on a trusted network, and leave it off everywhere else.

The setting belongs to a single data source and is off by default, so turning it on for one connector leaves every other call verified as before.

> [!NOTE]
>
> **A truststore configured under [Certificates](#certificates) is ignored while this is on.** Skipping verification replaces it rather than adding to it. If you want calls validated against that truststore, turn **Skip verification** off.

Only REST data sources accept it. Setting it on any other type is rejected.

On SaaS, **Skip verification** is replaced by the **None (insecure)** trust option, and a data source that had it on is converted to that option (SaaS · 6.0). See [Trust and identity certificates](#trust-and-identity-certificates).

### Trust and identity certificates

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Certificates** panel in the **Settings** of a REST data source has two independent parts. **Trust** decides what the certificate the host presents is checked against. **Identity** is the client certificate FlowX presents back to the host (mutual TLS), which most hosts don't ask for.

**When to use what**

| The external system... | Trust | Identity |
| - | - | - |
| Has a publicly trusted certificate and doesn't ask for a client certificate | **System CAs** (default) | Off |
| Presents a certificate that is self-signed or issued by a private CA | **Custom CA** | Off |
| Requires you to present a client certificate (mutual TLS) | **System CAs**, or **Custom CA** for a private CA | **Present a certificate** ON |

**Trust**

Under **Verify the host's certificate against**, select one option:

| Option | What happens |
| - | - |
| **System CAs** | The default. Calls are verified against the platform's trusted certificate authorities. Nothing to configure. |
| **Custom CA** | Calls are verified against the certificate authority you provide in the certificate fields below. |
| **None (insecure)** | Verification is turned off. The call accepts any certificate the host presents: self-signed, expired, or issued for a different hostname, like `curl --insecure`. |

> [!WARNING]
>
> **None (insecure)** removes protection against man-in-the-middle attacks, because the call can no longer tell the intended host from anything that intercepts it. Use it only for trusted internal hosts you control, and keep **System CAs** or **Custom CA** everywhere else.

The trust setting belongs to a single data source, so changing it for one connector leaves every other call verified as before. **None (insecure)** is accepted only by REST and File Storage data sources.

**Identity**

Toggle **Present a certificate** ON to send a client certificate when the host asks for one, then fill in the certificate fields below. Leave it OFF when the host doesn't use mutual TLS.

**Certificate fields**

**Custom CA** and **Present a certificate** each take one certificate, with these fields:

| Field | Description | Default |
| - | - | - |
| **Source** | **Inline** to paste the certificate content, or **Path** to point to a file | `Inline` |
| **Format** | `PEM`, `PKCS12`, or `JKS` | `PEM` |
| **Certificate content** | Inline only. The base64-encoded file. A PEM certificate can also be pasted as text, starting with `-----BEGIN` | - |
| **Certificate path** | Path only. The file path, for example `/opt/certificates/client.p12` | - |
| **Private key content** or **Private key path** | Identity with PEM only. The private key, when it is in a separate file from the certificate (for example `client.crt` and `client.key`). Leave it empty when both are in the same file | - |
| **Password** | PKCS12 and JKS only. The password of the keystore or truststore | - |
| **Private key passphrase** | Identity with PEM only. Needed only when the private key is encrypted | - |

A PEM certificate for **Custom CA** is a public certificate, so it takes no password.

> [!NOTE]
>
> **Path** points to the filesystem of the Integration Designer service, not to your local machine: the file must be mounted into the service container (for example, through a Kubernetes secret and volume mount). On SaaS deployments, use **Inline**.

All fields support `${configParam}` placeholders for dynamic per-environment resolution.

> [!TIP]
>
> Use [Configuration Parameters Overrides](../../projects/runtime/configuration-parameters-overrides) to manage certificate content and passwords across environments (Dev, UAT, Production) without changing the data source configuration. For example, store the certificate content in a config parameter and reference it with `${clientCertificate}`.

**Preparing the files**

PEM files work as you receive them: use the CA certificate (for example `ca.crt`) for **Custom CA**, and the client certificate and its key (`client.crt` and `client.key`) for **Present a certificate**. No `keytool` or `openssl` step is needed.

To use PKCS12 instead, package a PEM certificate and its key as a keystore:

```bash theme={"dark"}
openssl pkcs12 -export -in client.crt -inkey client.key -out keystore.p12 -name client
```

For **Inline** with PKCS12 or JKS, encode the file and paste the output into **Certificate content**, or store it in a configuration parameter:

```bash theme={"dark"}
base64 -i keystore.p12
```

**What happens to certificate settings from earlier versions?**

Data sources configured as described in [Certificates](#certificates) and [TLS verification](#tls-verification) are converted automatically, and so are imported exports from earlier versions:

| Earlier setting | Converted to |
| - | - |
| **Use Certificate** OFF | Trust **System CAs**, Identity OFF |
| A keystore configured | Identity **Present a certificate** ON, with the keystore |
| The truststore turned on | Trust **Custom CA**, with the truststore |
| **Skip verification** ON | Trust **None (insecure)** |

**Exporting for 5.9.x or 5.1.x**

When you export for an older LTS line in **Target platform version**, certificate settings are written in the format those versions read. The export stops with an error that names the data source (`System '<name>' cannot be exported to this FlowX version, which does not support ...`) when a data source uses something they can't store:

* a **Custom CA** without a client certificate
* a PEM certificate
* a CA and a client certificate in different formats, or one **Inline** and the other **Path**

Change the certificates of that data source, or export for the current version. For the export options, see [Cross-version export and import](../../flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).


# Deep Research node
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/deep-research-node

Research a question across the open web with a budgeted, multi-pass agent, and file the cited result into a knowledge base.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

The **Deep Research** node investigates a question across the open web and files a cited report into a Knowledge Base. It is a budgeted, multi-pass agent: it plans the work, sends sub-researchers to search and read pages, grades what they bring back, and keeps going until the budget runs out or it has enough to report.

Unlike a [Custom Agent](./custom-agent-node), you do not write the method. The research prompt is built into the node, so you describe the subject and the node decides how to pursue it.

> [!NOTE]
>
> **The result always lands in a Knowledge Base.** Research is filed as text so retrieval nodes and other agents can reach it later. A rendered document is optional, and off by default.

***

## Adding a Deep Research node

Open your workflow in **Integration Designer**, then pick **Deep Research** from the **AI Agents** group in the left node panel, alongside **Custom Agent** and **Intent Classification Agent**.

***

## Configuring the node

**researchQuestion** `string` *required*

What the node should investigate. Bind workflow data with `${...}` placeholders, and add any standing guidance you want the node to follow.

**Example:**

```
Research ${topic}. Prefer primary sources.
```

There is no **Instructions** field on this node. The research method itself is built in, so this field carries the subject and your guidance, and nothing about how to search.

**researchDepth** `string`

How far the node fans out, chosen from four options.

**Default:** `Standard`

**Quick**, **Standard** and **Deep** apply budgets tuned by the platform, shown under the control as a summary such as `24 passes · 6 tool calls per sub-researcher`:

| Depth | Passes | Tool calls per sub-researcher |
| - | - | - |
| **Quick** | 12 | 4 |
| **Standard** | 24 | 6 |
| **Deep** | 48 | 10 |

**Custom** replaces the summary with two fields you set yourself:

| Field | What it controls |
| - | - |
| **Passes** | How many model calls the whole run may make. More passes let the node dig further, and cost more. |
| **Tool calls** | How many searches and page fetches each sub-researcher may make before it has to report back. |

> [!NOTE]
>
> **The number of sub-researchers is always the node's decision.** It is not a setting, on any depth.

**sources** `object`

Which parts of the open web the node may read. Leave both lists empty to allow anything.

Open **Manage lists** to edit them:

| List | Effect |
| - | - |
| **Allow only** | When set, the node may read **only** these domains. |
| **Deny** | Domains the node must never read, even when no allow list is set. |

> [!WARNING]
>
> **An allow list is a hard restriction. Nothing outside it is read.** An over-strict list yields no sources and fails the node.

Each list holds up to **50** entries and takes either mode:

* **Static** — type hostnames such as `reuters.com`. Anything that is not a hostname is rejected, and a duplicate is refused with `Already in the list`.
* **Dynamic** — bind a single `${...}` expression that resolves to the whole list, such as `${allowedDomains}`. Anything past the first 50 entries is ignored at runtime.

**storeResponse** `object` *required*

Where the report is indexed so retrieval nodes and other agents can reach it. All three fields are required.

| Field | Description | Default |
| - | - | - |
| **Knowledge Base** | The Knowledge Base to write into. **Store** stays locked until you pick one. | — |
| **Write mode** | **Append Content** adds to what is there, **Replace** overwrites it. | `Append Content` |
| **Store** | The store inside that Knowledge Base. | — |
| **Metadata values** | Optional metadata attached to what is written. Shows `No metadata values` when empty. | — |

> [!WARNING]
>
> **Check the store name.** An unrecognised name creates a new store rather than failing, so a typo produces a second store that looks empty instead of an error you can see.

**generateReport** `boolean`

Renders the research as a document in addition to filing it as text, and lets you choose the format and where it lands.

**Default:** `false`

The research is always filed as raw text for the Knowledge Base, so turning this off does not lose the result. Turn it on when someone needs a document to read.

**subResearcherModel** `string`

The model the sub-researchers use, set on the **AI Model** tab.

**Default:** `Same as orchestrator`

A cheaper model here is the usual way to make a wide fan-out affordable, since the sub-researchers do most of the calls.

**responseKey** `string` *required*

The key the node's output lands under in workflow state.

**Default:** `responseKey`

> [!NOTE]
>
> This node has no **Request timeout** setting. The shared timeout does not apply to it, so the control is not shown rather than shown and ignored.

***

## Related resources

> [card] [Custom Agent node](./custom-agent-node)
>
> Agents where you write the instructions and attach the tools

> [card] [Knowledge Base overview](./knowledge-base-integration/knowledge-base-overview)
>
> Where the research is filed, and how to retrieve it


# Document classifiers
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/document-classifiers

Train or import deterministic machine-learning models that sort document pages into categories, and route each page in a workflow based on the predicted label.

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A Document Classifier is a trained machine-learning model that sorts document pages into categories you define, such as `INVOICE`, `NATIONAL_ID`, or `BANK_STATEMENT`, so a workflow can route each page to the right handling. Classification is deterministic: the same page always gets the same result, and no large language model runs at inference time.

Document Classifiers live in your project under **Integrations** → **Document Classifiers**, alongside Data Sources, Workflows, and Proxy Connections.

***

## When to use a Document Classifier

FlowX offers two ways to classify documents. Pick based on how well-defined your document types are and how much labeled data you have:

| Approach | Best for |
| - | - |
| **Document Classifier** (this page) | Narrow, well-defined document types at scale. Deterministic results, low latency, low cost per page. Needs labeled example pages to train. |
| **LLM-based classification** with a [Custom Agent](./custom-agent-node) | Standing something up fast without training data, or open-ended document types. Results vary between runs and cost more per page. |

> [!NOTE]
>
> Two other features have similar names but do different things: **Document Intelligence** ingests documents into a knowledge base for AI retrieval, and the **Extract Data from File** workflow node extracts field values from a document. A Document Classifier only answers one question per page: *which category is this?*

***

## Create a Document Classifier

**1. Open Document Classifiers**

In your project, go to **Integrations** → **Document Classifiers** and click **+**.

**2. Name the classifier**

Enter a **Name** and an optional **Description**.

**3. Choose how the model gets trained**

Leave **Use preexisting model bundle** toggled **OFF** to create an empty classifier and train it in FlowX (the usual path). Toggle it **ON** to import a model bundle exported from another FlowX environment. See [Import a pre-trained bundle](#import-a-pre-trained-bundle).

The classifier detail page has three tabs (**Classes**, **Data**, and **Trained Models**) that mirror the three parts of a classifier: a label taxonomy, a labeled page corpus, and trained model versions.

***

## Define classes

Classes are the categories the model sorts pages into. Open the **Classes** tab and click **New class**.

**Class name** `string` *required*

Must be UPPER\_SNAKE\_CASE (letters, digits, underscores, starting with a letter, such as `NATIONAL_ID`) and unique within the classifier.

**Description** `string` *required*

Describe what differentiates this class from the others. The description guides automatic pre-labeling when you upload unlabeled documents.

**Positive examples** `list`

Snippets of text likely to appear verbatim in a document of this class.

**Negative examples** `list`

Snippets that look like this class but are not. They help the model separate near-misses.

Every classifier ships with a locked **UNKNOWN** class as the default catch-all. Pages that don't belong to any of your classes get labeled `UNKNOWN` instead of landing in a wrong category.

> [!TIP]
>
> Define at least two classes besides `UNKNOWN`, and make them mutually exclusive. If two classes overlap heavily, merge them and let a downstream step tell them apart.

***

## Build the corpus

The unit of classification is a **page**, not a file. The **Data** tab is where labeled pages accumulate into the training corpus. There are two ways to add pages:

* **Upload unlabeled batch**: drop ZIP, PDF, or Word files. Source files can be up to 20 MB each. The pages are pre-labeled automatically and queued for your review; each page needs review before it joins the corpus.&#x20;
* **Upload sorted by class**: drop files that are already sorted per class; the pages join the corpus directly, without review.

Added pages join the corpus with an automatic **80% train / 20% test** split, assigned per class when the page enters and never reshuffled, so test results stay comparable between training runs. Pages labeled `UNKNOWN` go entirely to the test pool. The corpus table shows every page with its class, split, and upload batch. You can remove pages, but not relabel them in place.

***

## Train a model

In the **Data** tab, select the training pages to use and click **Train model**. Training requires at least **10 training pages for every class**; the locked `UNKNOWN` class is exempt. A warning appears when the corpus is heavily imbalanced: when one class has far more pages than another, the model tends to over-predict the bigger one.&#x20;

Training runs asynchronously. Each successful run produces an immutable **model version** in the **Trained Models** tab, with its accuracy metrics, per-class results, and a confusion matrix. You can compare any two versions to see what changed between training runs.

The **main** version is the one workflows use. The first trained version becomes main automatically; promote a different version when it performs better.

> [!NOTE]
>
> Training and promotion work on the draft (WIP) version of your project. Committing a project version freezes the classifier's corpus and training for that version. Editing a committed classifier continues on a new draft.

### What travels between environments

When you export or build a project, the classifier's **class taxonomy travels with it** as part of the versioned configuration. The **corpus and trained models do not travel with a project export or build**: the target environment receives the classes and trains against its own data.&#x20;

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The corpus itself can now move between environments: export a classifier's corpus and import it into the classifier in the target environment. An imported corpus appears in a **read-only view** in the classifier's **Data** tab, so you can inspect the pages it was trained on without editing them there. Exporting a corpus requires the ML models permission. To move a trained model, use the pre-trained bundle flow described below.

***

## Import a pre-trained bundle

If you already have a model trained in another FlowX environment, toggle **Use preexisting model bundle** ON when creating the classifier and upload the exported bundle: a ZIP with the model metadata and binary. FlowX validates the bundle on upload and adds it as an uploaded candidate version:

* It must define at least two classes, named in UPPER\_SNAKE\_CASE, without duplicates.
* Its training metrics must be present and consistent with the declared class set.
* FlowX rejects a bundle that fails validation; nothing is created. A bundle that uploads but fails processing leaves the classifier in a **Failed** state with a **Retry** option.

> [!WARNING]
>
> Bundles are produced by FlowX. Export them from an environment where the model was trained: hand-assembled bundles fail validation or produce meaningless predictions, because the model's features are tied to how it was trained.

***

## Classify pages in a workflow

Consume the trained model with the **Document Classification** node from the workflow node palette.  The node is a pure classifier: it labels pages and writes the result. Routing happens in a downstream condition node.

| Field | Description | Default |
| - | - | - |
| **Document Classifier** | The classifier whose main model version runs. A read-only **Classes** hint lists its labels so you can build the downstream condition. | N/A |
| **File Content** | An expression that resolves to an array of extracted page texts, one entry per page, such as `${extractedPages}`. | N/A |
| **Confidence Threshold** | Predictions below this probability get flagged `low_confidence`. | `0.7` |
| **Response Key** | The key the node writes the result JSON under. | `responseKey` |
| **Timeout** | Inference call timeout, in milliseconds. | `10000` |

> [!WARNING]
>
> The node classifies **text, not files**. Extract page text upstream, for example with the **Extract Data from File** node or your document processing flow, and pass the array of page texts to **File Content**.

### Output

The node classifies each page independently and writes one result object:

```json theme={"dark"}
{
  "pages": [
    {
      "page": 1,
      "predictedLabel": "NATIONAL_ID",
      "predictedProbability": 0.92,
      "low_confidence": false,
      "classes": [
        { "label": "NATIONAL_ID", "probability": 0.92 },
        { "label": "PASSPORT", "probability": 0.05 }
      ],
      "error": null
    }
  ],
  "confidenceThreshold": 0.7,
  "error": null
}
```

* `predictedLabel` is the highest-probability class; `classes` lists all class probabilities in descending order.
* `low_confidence` is `true` when `predictedProbability` is below the configured threshold. A low-confidence prediction is still a **successful** result. Use the condition node to route those pages to human review instead of treating them as failures.
* A single page failing to classify populates that page's `error` and the node still succeeds; the other pages classify normally.
* Whole-node failures set the top-level `error` and route to the node's error output. The error codes:

| Code | Meaning |
| - | - |
| `MODEL_NOT_FOUND` | The selected classifier or its main model version doesn't exist. |
| `MODEL_NOT_READY` | The classifier has no trained, ready model version yet. |
| `NO_DOCUMENT_TEXT` | The File Content expression resolved to nothing. |
| `EMPTY_INPUT` | The input resolved to an empty page list. |
| `INVALID_TIMEOUT` | The configured timeout value isn't usable. |
| `INFERENCE_UNAVAILABLE` | The classification service is unreachable. Retryable. |

### Route by label

Add a **Condition** node after the Document Classification node and branch on the result: typically iterating `pages` and switching on `predictedLabel`, with a separate branch for `low_confidence` pages.

***

## Related resources

> [card] [Integration Designer](./integration-designer)
>
> Build workflows that combine classifiers with REST calls, data operations, and AI nodes

> [card] [Custom Agent node](./custom-agent-node)
>
> LLM-based alternative for classification without training data


# Send and receive files with Integration Designer endpoints
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling

Configure Integration Designer endpoints to receive files and XML or SOAP responses, and to send files in POST bodies, with runtime behavior and an example.

You can now handle file uploads and downloads with external systems directly within Integration Designer. This update introduces native support for file transfers in RESTful connectors, reducing the need for custom development and complex workarounds.

> [!WARNING]
>
> **Important: Document replacement behavior**
>
> When saving files to the Document Plugin, if you upload a file with the **same `customId` AND `documentType` combination** as an existing document, the previous document will be automatically **marked as deleted** and replaced by the new file.
>
> This means:
>
> * The previous file's URLs will stop working
> * Only the most recent file with that `customId` + `documentType` combination will be accessible
>
> **Best practices:**
>
> * Always use **unique, dynamic values** for `customId` (for example, `${processInstanceId}`, `${clientId}`, `${uuid}`)
> * Never copy examples with hardcoded values like `customId: "1234"` or `documentType: "BULK"` without changing them
> * If you need to store multiple documents of the same type, ensure each has a unique `customId`
>
> ```json Example: Using dynamic customId theme={"dark"}
> {
>   "customId": "${processInstanceId}_${timestamp}",
>   "documentType": "CONTRACT"
> }
> ```

## Core scenarios

Integration Designer supports two primary file handling scenarios:

**1. Downloading Files**

Can call an external API (`GET` or `POST`) and receives a response containing one or more files. Integration Designer saves these files to a specified location and returns their new paths to the workflow for further processing.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh1.png)

**2. Uploading Files**

Can send a file that is already stored in the **Document Plugin** or a custom **S3 Bucket** to an external API via a `POST` request. The workflow transmits the file path, enabling file transfer without manual handling.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh2.png)

> [!NOTE]
>
> Common use cases include contract generation workflows where data is sent to external document services and the generated files are retrieved back into the process.

***

## Receiving XML and SOAP responses

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.0**
>
> Earlier releases assumed every response body was JSON — any other format failed the node even on a valid `2xx`. From 5.9.0, the engine honours the content type the endpoint declares and parses XML responses automatically.

REST endpoints can consume **JSON**, **XML** (including **SOAP** envelopes), and **plain text** responses. You don't pick the response format in a dropdown — the engine resolves it from the endpoint's request **Headers**:

1. The **`Accept`** header wins (what the integration expects back).
2. If `Accept` is absent, the request **`Content-Type`** is used as a fallback.
3. If neither is set, the engine runs in **automatic** mode and infers the format from the upstream's response `Content-Type`.
4. Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) are treated as automatic — they don't commit to a format.

Media types are categorised as follows:

| Declared / received type | Parsed as | Resulting body |
| - | - | - |
| `application/json`, `application/hal+json`, anything ending in `+json` | JSON | Object you map with `${...}` paths |
| `application/xml`, `text/xml`, anything ending in `+xml` (e.g. `application/soap+xml`) | XML | Object you map the same way as JSON |
| `text/*` (plain text, HTML) | Text | The raw string |
| Anything else / unset | Automatic | JSON if parseable, otherwise the raw string |

When an XML or SOAP response is parsed, you map its fields exactly like a JSON response (for example `${response.body.Envelope.Body.result}`). The original XML is preserved alongside the parsed object, so flows that need the raw markup can still access it.

> [!WARNING]
>
> The engine fails the node with a clear error when the response does not match what the endpoint declared:
>
> * **Content type mismatch** — declared `application/json` but the upstream returned `text/plain`: `Expected response content type "application/json" but received "text/plain".`
> * **Parse failure on a declared type** — declared XML but the body is malformed: `Response declared as XML but could not be parsed as XML.`
>
> In automatic mode (or when XML was only *inferred* from the upstream's `Content-Type`), a parse failure does **not** fail the node — the raw string is returned instead, so a mislabelled upstream doesn't break the flow.

XML parsing is XXE-safe: external entity resolution and DTD processing are disabled, so XXE and entity-expansion payloads cannot read local files or exhaust memory.

XML bodies larger than 5 MiB are returned as raw strings without parsing.

> [!NOTE]
>
> To **send** a SOAP or XML request body, set the endpoint **Content type** to **Raw** and add the matching `Content-Type` header — see [Defining REST integration endpoints](./data-sources-and-endpoints#defining-rest-integration-endpoints).

***

## Receiving files (endpoint response configuration)

To configure an endpoint to handle incoming files from an external system, navigate to its **Response** tab. This functionality is available for both `GET` and `POST` methods.

### Enabling and configuring file downloads

**1. Activate File Processing**

Switch the **Save Files** toggle to the "on" position to activate file processing for the response.

> [!WARNING]
>
> If this toggle is **off**, the system doesn't save files. The response body reaches the workflow as a raw string, whether it holds Base64 data or the binary file itself, and the node succeeds. The node fails only when the endpoint's request headers declare an `Accept` type (or, without one, a `Content-Type`) of JSON, XML, or text and the response is a different type. The error reads `Expected response content type "…" but received "…".`

**2. Configure Content-Type**

Select the expected format of the successful API response from the **Content-Type** dropdown:

* `JSON` (Default): For responses containing Base64 encoded file data
* `Single Binary`: For responses where the body is the file itself

### Handling JSON content-type

This option is used when the API returns a JSON object containing one or more Base64 encoded files.

**File Destination Configuration:**

> [tab] Document Plugin
>
> Saves files to the platform's managed storage, linking them to a specific process instance. The Document Plugin acts as a wrapper over the file system and provides special integration capabilities with document templates.
>
> **processInstance** `string` *required*
>
> The ID of the process instance. This field defaults to `${processInstanceId}` to be mapped dynamically at runtime.
>
> > [!TIP]
> >
> > When using Document Plugin for file operations, you typically send only the document reference (ID) rather than the entire file content. The Integration Designer handles the special integration with document templates automatically.
>
> **Files Mapping Table:**
>
> | Column | Description | Example |
> | - | - | - |
> | **Base 64 File Key** | The JSON path to the Base64 encoded string | `files.user.photo` |
> | **File Name Key** | *Optional.* The JSON path to the filename string | `files.photoName` |
> | **Default File Name** | A fallback name to use if the File Name Key is not found | `imagineProfil` |
> | **Default Folder** | The business-context folder, such as a client ID (`CNP`) | `folder_client` |
> | **Default Doc Type** | The document type for classification in the Document Plugin | `Carte Identitate` |

> [tab] S3 Protocol
>
> Saves files to a custom S3 bucket, ideal for files not tied to a specific process instance or when Document Plugin is not available.
>
> This configuration requires the same **Files** table but omits the `Process Instance` and `Default Document Type` fields since S3 storage operates independently of the FlowX document management system.
>
> > [!TIP]
> >
> > Use S3 Protocol when you want to manipulate files at the workflow level for scenarios like AI processing, report generation, or CMS integrations with unassociated documents.

> [!NOTE]
>
> The `Translate or Convert Enumeration Values` toggle can be used in conjunction with the `Save Files` feature.

### Handling Single Binary content-type

This option is used when the entire API response body is the file itself. The Single Binary content-type is ideal for endpoints that return raw file data directly in the response body.

**1. Configure Content-Type**

In the **Response** tab of your endpoint configuration:

1. Enable the **Save Files** toggle
2. Select **Single Binary** from the **Content-Type** dropdown

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh3.png)

> [!WARNING]
>
> With the **Save Files** toggle off, a binary response isn't saved as a file: the body reaches the workflow as a raw string. Turn **Save Files** on to store the file.

**2. Choose File Destination**

Select your preferred file storage destination:

> [tab] S3 Protocol
>
> For files stored in custom S3 buckets, ideal for files not tied to specific process instances.

> [tab] Document Plugin
>
> For files managed by FlowX's document system, linked to process instances with additional metadata.

**3. Configure File Name Identification**

Choose how the system should identify the filename from the response.

**File Name Identification Methods:**

> [tab] Auto Identify (Recommended)
>
> The system automatically parses the `Content-Disposition` HTTP header to extract the `filename` attribute. This is the standard approach for most file download endpoints.
>
> > [!TIP]
> >
> > **When to use:** When the external API follows standard HTTP conventions and includes file information in the `Content-Disposition` header.
>
> **Example of standard Content-Disposition header:**
>
> ```
> Content-Disposition: attachment; filename="document.pdf"
> ```
>
> The system will automatically extract `document.pdf` as the filename.

> [tab] Manual Configuration
>
> Configure custom header parsing when the external system doesn't follow standard conventions or uses custom headers for file information.
>
> **1. Disable Auto Identify**
>
> Turn off the **Auto Identify File** toggle to enable manual configuration options.
>
> **2. Configure Header Fields**
>
> **File Name Header Key** `string` *required*
>
> The name of the HTTP header that contains the filename information.
>
> **Examples:**
>
> * `X-Dctm-Object-Name`
> * `X-File-Name`
> * `Custom-Filename-Header`
>
> **File Name Header Attribute** `string` *required*
>
> The specific attribute or value within the header to extract as the filename.
>
> **Examples:**
>
> * For simple headers: leave empty or use the full header value
> * For complex headers: specify the attribute name
>
> **3. Apply Custom Regex (Optional)**
>
> Enable the **Apply Custom Regex** toggle when you need to extract the filename using pattern matching.
>
> > [!NOTE]
> >
> > **When to use regex:** When the filename is embedded within a larger header value and needs to be extracted using pattern matching.
> >
> > **Example scenarios:**
> >
> > * Header value: `filename=document.pdf; size=1024`
> > * Regex pattern: `filename=([^;]+)`
> > * Extracted result: `document.pdf`
>
> **Common regex patterns:**
>
> ```regex theme={"dark"}
> # Extract filename from "filename=document.pdf"
> filename=(.+)
>
> # Extract filename with extension from complex header
> ([a-zA-Z0-9_-]+\.[a-zA-Z]{2,4})
>
> # Extract quoted filename: filename="my document.pdf"
> filename="([^"]+)"
> ```
>
> > [!TIP]
> >
> > Use manual configuration when working with legacy systems, custom APIs, or when the external server provides file information through non-standard headers.

**File Destination Configuration:**

> [tab] Document Plugin
>
> For files managed within FlowX's document system with full process integration:
>
> **Default File Name** `string` *required*
>
> Fallback filename if header extraction fails
>
> **Default Folder** `string` *required*
>
> Business context folder (e.g., client ID, case number)
>
> **Default Document Type** `string` *required*
>
> Document classification for the Document Plugin
>
> > [!NOTE]
> >
> > Files stored via Document Plugin are automatically linked to process instances and can be used with document templates and other FlowX document features.

> [tab] S3 Protocol
>
> For files stored in custom S3 buckets with flexible storage options:
>
> **Default File Name** `string` *required*
>
> Fallback filename if header extraction fails
>
> **Default Folder** `string`
>
> Optional folder structure within the S3 bucket
>
> > [!TIP]
> >
> > S3 Protocol storage is ideal for files that need to be processed by external systems, used in AI workflows, or when Document Plugin is not available.

**Configuration Examples:**

```json Auto Identify Example theme={"dark"}
{
  "contentType": "Single Binary",
  "saveFiles": true,
  "autoIdentifyFile": true,
  "fileDestination": "S3 Protocol",
  "defaultFileName": "downloaded_file",
  "defaultFolder": "client_${clientId}"
}
```

```json Manual Configuration Example theme={"dark"}
{
  "contentType": "Single Binary", 
  "saveFiles": true,
  "autoIdentifyFile": false,
  "fileNameHeaderKey": "X-Document-Name",
  "fileNameHeaderAttribute": "filename",
  "applyCustomRegex": true,
  "customRegex": "filename=\"([^\"]+)\"",
  "fileDestination": "Document Plugin",
  "defaultFileName": "fallback_document",
  "defaultFolder": "documents",
  "defaultDocumentType": "Contract",
}
```

***

## Sending files (endpoint POST body configuration)

To configure an endpoint to send a file, navigate to the **Body** tab and select the appropriate **Content Type**.

### Content Type: Multipart/Form-data

Use this to send files and text fields in a single request. This format is flexible and can handle mixed content types within the same POST request.

**1. Configure File Source**

Select where the file originates:

* `Document Plugin`
* `S3 Protocol`

**2. Define Form Parts**

Add rows to the resource table, defining each part of the form:

* **Key Type**: Choose `File` or `Text`
* **Value**:
  * For files: Provide the `filePath` (Minio path for S3 or Document Plugin reference)
  * For text: Provide the string value or variable reference

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh4.png)

> [!NOTE]
>
> Multipart requests can be sent even without files - you can include only text fields by setting all Key Types to `Text`. The difference between content types is primarily in how data is packaged for transmission to the target server.

### Content Type: Single binary

Use this to send the raw file as the entire request body. This method sends only the file content without any additional form data or metadata.

**fileSource** `string` *required*

Select `Document Plugin` or `S3 Protocol`

**filePath** `string` *required*

Specify the path of the file to be sent (Minio path for the file location)

> [!TIP]
>
> When using Single Binary, only the Minio path is required since the entire request body will be the file content itself, without any additional packaging or metadata.

### Content Type: JSON

Use this option for standard JSON payloads. To send a file as the whole request body or as a form part, use `Single Binary` or `Multipart/Form-Data`.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.6**
>
> A JSON body can carry a file from the Document Plugin as a base64 string. In 5.9.5 and earlier, a JSON body cannot carry a file: use `Multipart/Form-Data` or `Single Binary`.

To embed a file, set a string value in the JSON body to `@@base64File(<path>)`, where `<path>` is the file's path in the Document Plugin. When the node runs, the marker is replaced with the file content encoded as base64:

```json theme={"dark"}
{
  "documentName": "contract.pdf",
  "content": "@@base64File(${filePath})"
}
```

* The path can come from a workflow variable, such as `${filePath}` from an earlier node. Variables are resolved before the marker is read.
* Only string values are replaced. A marker used as a JSON key is left as it is.
* The file content is added only to the request that is sent. The saved request body and the generated curl command keep the marker.
* Downloading the file from the Document Plugin is cancelled after 5 minutes by default. On self-hosted deployments, change the limit with `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` (see the [Integration Designer setup guide](../../../setup-guides/integration-designer-setup#service-communication)).

***

## Runtime behavior & testing

### Workflow node configuration

All configured file settings (for example, `File Path`, `Folder`, `Process Instance ID`) are exposed as parameters on the corresponding workflow nodes, allowing them to be set dynamically using process variables at runtime.

### Response payload & logging

> [!TIP]
>
> When a node successfully downloads and saves a file, its output will contain the **`filePath`** to the stored file, **not** the raw Base64 string or binary content.

> [!NOTE]
>
> For security and performance, runtime logs will also only contain the `filePath`, not the raw file content.

### Error handling

If a node is configured to receive a `Single Binary` file but the external system returns a `JSON` error (for example, file not found), the JSON error will be correctly passed through to the workflow for handling.

If **Save Files** is on with the `JSON` content type (Base64 files) and the external system returns a success status (2xx) with a response that isn't JSON or XML, the node fails with `Unsupported content type "text/html". Make sure system is configured correctly.` (the message names the content type actually received). The external system's response causes this error, not the endpoint configuration.

**Error status (non-2xx), starting with FlowX.AI 5.9.6:** the node keeps the response body as text, with its status code, for both `JSON` (Base64 files) and `Single Binary`. Nothing is saved as a file, and the error response isn't stored in the endpoint response cache. The status code then drives the node: with **Allow Retry** on, a `408`, `429`, `500`, `502`, `503`, or `504` is retried, and once retries are done the node completes with the error status, so a failure path on the node can handle it. For example, an HTML `504 Gateway Timeout` page from a gateway or proxy is now retried instead of failing the workflow.

**Error status on 5.9.5 and earlier:** with `JSON` (Base64 files), an HTML error page fails the node, for example `Content type 'text/html' not supported for bodyType=com.fasterxml.jackson.databind.JsonNode`. Changing the request `Accept` header doesn't help, because the upstream gateway decides the response format. To avoid the gateway's error page, set the node's **Timeout** on its **Settings** tab (default `10000` ms) lower than the gateway's timeout. The node then stops waiting before the gateway responds and returns a `408` status, which is retried when **Allow Retry** is on. Switching the response to `Single Binary` doesn't avoid the problem on these versions: Single Binary doesn't check the status code, so an HTML error page is saved as a file.

### Testing guidelines

> [!TIP]
>
> The **Test Modal** is context-aware. It will only display input fields for file parameters (`Process Instance ID`, `Folder`, etc.) if `Save Files` is enabled on the endpoint.

> [!WARNING]
>
> If you test an endpoint that returns a binary file without configuring it as `Single Binary`, the test will fail with the error: "*Endpoint returns a binary file. Please configure the Content-Type to handle binary responses.*"

> [!NOTE]
>
> The **Response Example** tab is now separate from the **Response** configuration tab and includes both `Body` and `Headers` sections for better clarity.

## Example: sending files to an external system after uploading a file to the Document Plugin

> [!NOTE]
>
> In this example, we'll send a file to an external system using the  Integration Designer.

**1. Upload a file to the Document Plugin**

Configure a process where you will upload a file to the Document Plugin.

* Configure a User Task node where you will upload the file to the Document Plugin.
* Configure an Upload File Action node to upload the file to the Document Plugin.
* Configure a Save Data Action node to save the file to the Document Plugin.

**2. Configure the Integration Designer**

Configure the Integration Designer to send the file to an external system:

* Configure a REST API Call node to send the file to an external system.


# Finding identifiers and parameters
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/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.

> [!TIP]
>
> **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

> [card] Workspace ID
>
> Required for multi-tenant environments and data isolation

> [card] Project ID
>
> Identifies your project in API calls

> [card] Build ID
>
> References a specific deployed version of your application

> [card] Process IDs
>
> Various identifiers for processes and their instances

## Organization identifiers

### Organization ID (Fx-Organization-Id)

The organization ID identifies the FlowX deployment tenant. It's mandatory on **every Kafka message** — messages missing this header are rejected with a non-retryable `MissingKafkaHeaderException`. On REST endpoints the header is read when present (to set security context) but not enforced.

**1. Self-hosted (single-org) deployments**

The organization ID is the value set in the `ORGANIZATION_ID` environment variable on all FlowX services. It is the UUID provided by FlowX when your organization is registered. See the [Organization Manager setup guide](../../../setup-guides/organization-manager-setup) for details.

**2. From the Designer URL**

After logging into the FlowX Designer, the organization ID appears in the URL path:

```
https://designer.your-domain.flowx.ai/{organization-id}/...
```

**3. From service configuration**

Check the `ORGANIZATION_ID` environment variable on any FlowX service (process-engine, application-manager, etc.). All services share the same value in single-org deployments.

> [!NOTE]
>
> **Format**: UUID, for example `26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx`

> [!NOTE]
>
> **Where it's used**:
>
> * Kafka header: `Fx-Organization-Id` (mandatory on every message)
> * REST header: `Fx-Organization-Id` (optional; read into security context if present)
> * Service config: `ORGANIZATION_ID` environment variable
> * CloudEvent extension: `flowxorganizationid`

## Workspace identifiers

### Workspace ID (Fx-Workspace-Id)

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://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wid.png)

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

> [!TIP]
>
> The workspace ID is also visible in your browser's address bar when navigating within a workspace.

> [!NOTE]
>
> **Default Workspace**: If you migrated from a pre-5.x version, your default workspace has the UUID: `00000000-0000-0000-0000-000000000001`

> [!NOTE]
>
> **Where it's used**:
>
> * Kafka header: `Fx-Workspace-Id`
> * 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.

> [!NOTE]
>
> **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

> [!NOTE]
>
> **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 referred to as 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 the projects list**

* In the **Projects** list, click the three dots on the project row
* Select "Copy UUID" to copy the project UUID

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prjid.png)

> [!NOTE]
>
> **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.

> [!TIP]
>
> In most cases, `Fx-RootAppId` will be the same as `Fx-AppId` unless you're dealing with complex multi-application workflows.

> [!NOTE]
>
> **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

> [!WARNING]
>
> **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](#obtaining-build-id-via-api) or from browser developer tools when viewing build details.

**3. Identify Active Build**

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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:

```bash theme={"dark"}
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`.

> [!NOTE]
>
> **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`

> [!NOTE]
>
> **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

> [!NOTE]
>
> **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.

> [!WARNING]
>
> **Deprecated Header**: `Fx-BuildId` is deprecated. 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

> [!TIP]
>
> Process names are case-sensitive and must match exactly when used in API calls or Kafka messages.

> [!NOTE]
>
> **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

> [!NOTE]
>
> **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`.

> [!WARNING]
>
> **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
```

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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.

> [tab] 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**:
>
> ```bash theme={"dark"}
> GET /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/workflow/ri/{resourceId}/integration/api/workflows/getById
> ```
>
> **Processes**:
>
> ```bash theme={"dark"}
> GET /appmanager/api/resource/app/{appId}/app-version/{appVersionId}/rt/process/ri/{resourceId}/...
> ```
>
> The response includes the `resourceDefinitionId`:
>
> ```json theme={"dark"}
> {
>   "resourceId": "36ab1a35-fc4e-49ee-872d-b3551e3e33ce",
>   "resourceDefinitionId": "e96fb0fb-a710-44db-b3bd-1a57bc2cb3e8",
>   "applicationId": "fd44d9d9-b072-40fe-b12e-b7714105ba48",
>   "name": "My Resource",
>   ...
> }
> ```

> [tab] Via List Endpoints
>
> You can also find the `resourceDefinitionId` in the response when fetching lists of resources:
>
> **Get all workflows**:
>
> ```bash theme={"dark"}
> 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`.

> [tab] 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
>
> > [!TIP]
> >
> > The GET request is usually the first call made when entering the details of a resource.

> [!NOTE]
>
> **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

> [accordion] 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):**
>
> ```json theme={"dark"}
> {
>   "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):**
>
> ```json theme={"dark"}
> {
>   "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 → Processes → 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

> [!TIP]
>
> **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.

> [!NOTE]
>
> **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 (the same view as for the [Process Instance UUID](#process-instance-uuid-processinstanceuuid)).

**2. Check Instance Metadata**

Scroll to the **Instance Metadata** section, which displays:

* `processInstanceId`: The numeric ID
* `processInstanceUuid`: The UUID

> [!NOTE]
>
> Both `processInstanceId` (numeric) and `processInstanceUuid` (UUID) identify the same process instance. **Prefer the UUID for integrations**: it's unique across all resource types, workspaces, and environments, and stays stable across data migrations or sequence resets. The numeric ID is only unique within a single database's sequence, so it can collide or shift when data moves between environments — use it for internal queries and legacy integrations.

> [!NOTE]
>
> **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 → Processes → 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

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **fxContext structure**:
>
> * Root process: `"main"`
> * Embedded subprocess (nodeId=4): `"main:4"`
> * Sub-subprocess (nodeId=12 inside subprocess 4): `"main:4:12"`

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

> [!NOTE]
>
> **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 ")

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> **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 self-hosted 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.

> [!NOTE]
>
> **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 |
| - | - | - | - | - |
| Organization ID | `Fx-Organization-Id`, `ORGANIZATION_ID` | UUID | Service env var OR Designer URL path | Kafka headers (mandatory) |
| Workspace ID | `Fx-Workspace-Id` | UUID | Organization Settings → Workspaces OR URL | Kafka headers, API calls |
| Global Application ID | `globalId` | UUID | API responses (internal) | Cross-workspace operations |
| Project ID | `appId`, `Fx-AppId` | UUID | Project URL, Project Settings | API paths, Kafka headers |
| Root Application ID | `Fx-RootAppId` | UUID | Same as Project 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 |

> [!NOTE]
>
> **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**: Project ID
* **buildId**: Build ID (obtained via API: `GET /appmanager/api/app/{appId}/builds`)
* **processDefinitionName**: Process name (from Definitions → Processes)
* **JWT token**: From authentication

```bash theme={"dark"}
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]
>
> **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-Organization-Id**: Organization UUID (mandatory on every message)
* **Fx-Workspace-Id**: Workspace UUID
* **Fx-AppId**: Project ID
* **Fx-ProcessName**: Process definition name
* **jwt**: JWT token

```json theme={"dark"}
{
  "headers": {
    "Fx-Organization-Id": "26ef7b5f-b463-4375-88c8-aaaaaaaaaaaa",
    "Fx-Workspace-Id": "00000000-0000-0000-0000-000000000001",
    "Fx-AppId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
    "Fx-ProcessName": "customer_onboarding",
    "jwt": "your-jwt-token"
  },
  "variables": {
    "customerName": "John Doe"
  }
}
```

### Responding to Kafka messages from FlowX

Required Kafka headers to preserve:

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

```java theme={"dark"}
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);
}
```

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

> [!NOTE]
>
> **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

> [accordion] 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.

> [accordion] 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:
>    ```bash theme={"dark"}
>    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

> [accordion] Process won't start via Kafka
>
> **Common issues**:
>
> 1. **Missing `Fx-Organization-Id` header**: Messages without this header are rejected immediately with a non-retryable `MissingKafkaHeaderException`. Verify the header is present and matches the `ORGANIZATION_ID` set on your FlowX services.
> 2. **Missing or incorrect headers**: Verify `Fx-Workspace-Id`, `Fx-AppId`, `Fx-ProcessName`, and `jwt` headers
> 3. **No active policy**: Check that the build is set as Active Policy in Runtime → Active Policy
> 4. **Authentication failure**: Ensure the JWT token is valid and not expired
> 5. **Process name mismatch**: Process names are case-sensitive - copy exact name from process list
> 6. **Payload too large**: Ensure your Kafka message payload is under 1MB

> [accordion] 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

> [accordion] Can't find process instance UUID
>
> **Solution**:
>
> 1. Navigate to **Runtime → Processes → 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

> [card] [Creating a Kafka Producer](./creating-a-kafka-producer)
>
> Learn how to create Kafka producers and understand required headers

> [card] [Workspaces](../../projects/workspaces)
>
> Understand workspace concepts and multi-tenant architecture

> [card] [Starting Processes](../../flowx-designer/managing-a-project-flow/starting-a-process)
>
> Learn different methods for initiating process instances


# FlowX Database
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/flowx-database

Store and access structured data across processes and apps

## What is FlowX Database?

<video />

FlowX Database (FlowX DB) is a persistence layer that allows you to store structured data independently of process instances. This enables you to:

* Share data between different process instances
* Store and retrieve data across multiple processes
* Create a persistent data store within the FlowX ecosystem
* Access structured data without directly interacting with external systems

> [!NOTE]
>
> FlowX Database is powered by the **nosql-db-runner** microservice, which provides MongoDB functionality within the FlowX ecosystem. This service supports both **native MongoDB** and **Azure Cosmos DB (MongoDB API)**, enabling you to choose the database backend that best fits your infrastructure needs while maintaining FlowX's workflow integration capabilities.
>
> For more information about the **nosql-db-runner** service and CosmosDB considerations, see the [NoSQL DB Runner documentation](../../../setup-guides/nosql-db-runner).

## Key concepts

> [tab] Collections
>
> Collections are containers for storing documents in FlowX Database. Each collection:
>
> * Stores documents with similar structure
> * Has a unique identifier
> * Can be accessed from different processes
> * Functions similarly to a database table, but with more flexibility
>
> Collections are created and managed through the Data Sources section in the Integration Designer.

> [tab] Operations
>
> Operations define the actions you can perform on a collection. FlowX Database supports the full range of essential MongoDB operations:
>
> | Operation | Description | MongoDB Docs |
> | - | - | - |
> | `find` | Retrieve multiple documents based on criteria | [MongoDB find()](https://www.mongodb.com/docs/manual/reference/method/db.collection.find/) |
> | `findOne` | Retrieve a single document | [MongoDB findOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.findOne/) |
> | `insertOne` | Add a single document | [MongoDB insertOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertOne/) |
> | `insertMany` | Add multiple documents at once | [MongoDB insertMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertMany/) |
> | `updateOne` | Modify a single document | [MongoDB updateOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateOne/) |
> | `updateMany` | Modify multiple documents at once | [MongoDB updateMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateMany/) |
> | `deleteOne` | Remove a single document | [MongoDB deleteOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteOne/) |
> | `deleteMany` | Remove multiple documents at once | [MongoDB deleteMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteMany/) |
>
> Each operation is configured with specific parameters that determine how it interacts with the data.

## Prerequisites

Before working with FlowX Database, you should have a solid understanding of:

> [card] MongoDB Fundamentals
>
> Basic knowledge of MongoDB operations, document structure, and query syntax

> [card] JSON Structure
>
> Understanding of JSON payloads and data formatting

> [card] CRUD Operations
>
> Familiarity with Create, Read, Update, and Delete operations in database systems

> [card] Query Modifiers
>
> Knowledge of query parameters like filters, sorting, projection, and pagination

> [!NOTE]
>
> If you're new to MongoDB, review the [MongoDB Manual](https://www.mongodb.com/docs/manual/) before working with FlowX Database operations.

## Benefits of FlowX Database

> [card] Data Sharing
>
> Share data between different process instances, enabling more complex workflows and business scenarios

> [card] Independence
>
> Store data structured according to your needs, independent of external systems

> [card] Extended Use Cases
>
> Enable new business cases that require persistent data across multiple processes

> [card] Simplified Integration
>
> Reduce the need for creating custom connectors to external systems for basic data persistence

> [card] Native Integration
>
> Integrate with workflows through the existing workflow designer

> [card] Complete CRUD Operations
>
> Perform all standard Create, Read, Update, and Delete operations on your data

> [card] Bulk Operations
>
> Handle multiple documents efficiently with insertMany, updateMany, and deleteMany operations

> [card] Flexible Querying
>
> Use MongoDB's query syntax to filter, sort, and project your data

## How to use FlowX Database

### Creating a collection

**1. Access Data Sources**

Navigate to the 'Integrations' section in the left sidebar of FlowX Designer, then click on 'Data Sources'.

![Accessing Data Sources in the navigation menu](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db.png)

Accessing Data Sources in the navigation menu

**2. Add a new Data Source**

Click the "+" button to add a new Data Source. In the "Add Data Source" dialog, select "FlowX Database" from the dropdown list.

![Adding a new FlowX Database data source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)

Adding a new FlowX Database data source

**3. Configure the collection**

Provide a name and description for your collection. The name will be used to identify this database collection in your workflows.

> [!WARNING]
>
> **Data Model Required**: You must have a data model defined before creating a FlowX Database collection. The data model becomes the schema for your database collection and defines the structure of documents that will be stored.

![Configuring the collection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb1.png)

Configuring the collection

* **Schema Definition**: Define the schema for your collection (the selected schema enhances auto-completion but does not enforce validation during insert or update)
* **Partitioning Key**: The attribute used to partition data in your collection. By default, this is set to the `id` attribute, but you can specify a different field based on your data model.

**4. Create the collection**

Click "Create" to save the collection in FlowX Database. Your new collection will appear in the Data Sources list with the type "FlowX Database".

> [!NOTE]
>
> Each FlowX Database data source represents a collection in the underlying MongoDB database. When you create a new data source with the FlowX Database type, you're essentially creating a new collection where your documents will be stored.

### Viewing collection data

**1. Navigate to collection**

Go to the collection you want to view in the 'Data Sources' section.

**2. Access Documents tab**

Click the 'Documents' section within the collection.

**3. Browse documents**

You'll see a listing of currently saved documents in the collection.

![Viewing documents in a FlowX Database collection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb2.png)

Viewing documents in a FlowX Database collection

**4. Search and filter**

Use the search functionality to find specific documents in the collection. You can add queries to filter documents, sort them, and use projections to choose what content from each entry you want to see.

![Searching and filtering documents in a FlowX Database collection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb3.png)

Searching and filtering documents in a FlowX Database collection

> [!NOTE]
>
> FlowX Database currently relies on MongoDB’s native sorting behavior for query results.
> All sorting is performed using MongoDB’s default binary comparison rules.

**5. Delete a document**

Hover over a document row and click the trash icon, then confirm with **Delete** (SaaS · 6.0). The document is permanently removed from the collection and can't be restored. You delete one document at a time, and you need edit rights on the data source.

### Managing collection settings

Each FlowX Database collection has a **Settings** tab where you can configure performance optimizations:

**1. Access Settings tab**

Navigate to your collection and click on the 'Settings' tab.

**2. Define indexes**

Create indexes for your collection to improve query performance. Indexes are particularly important for large collections as they significantly reduce query execution time.

> [!TIP]
>
> Create indexes on fields that you frequently use in filter conditions, sort operations, or queries to optimize performance.

![Defining indexes for a FlowX Database collection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb4.png)

Defining indexes for a FlowX Database collection

> [!WARNING]
>
> Defining indexes in the Settings tab saves them as **configuration only** — they are not applied to the actual MongoDB collection immediately. To apply indexes, you must go to the **Runtime** view of your project or library, open the **Builds** section, and select **Apply Indexes** from the build's context menu. Only one build per project or library can have indexes applied at a time. Applying indexes on a new build will automatically replace any previously applied indexes that differ.
>
> For more details, see [Builds](/5.9/docs/projects/runtime/builds#apply-indexes).

> [!NOTE]
>
> For large collections with thousands of documents, proper indexing is crucial for maintaining good query performance. Consider indexing frequently queried fields before your collection grows large.

### How do I make an index unique?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Toggle **Enforce unique values** when you add an index to reject any document that repeats a value already stored on the indexed attributes. On a single attribute, no two documents can hold the same value. On a compound index, the combination of attributes must be unique, not each attribute on its own.

When **Enforce unique values** is on, a second toggle controls empty values:

* **Enforce only when the value is filled in** (single attribute) or **Enforce only when the whole key is filled in** (compound index) **ON**: documents that leave the attribute, or any attribute of the key, empty are exempt. Duplicates among documents that do have values are still rejected.
* The same toggle **OFF**: empty attributes count as values. Only one document in the collection can leave a single indexed attribute empty, and on a compound index two documents conflict when their keys match, blanks included.

Keep these rules in mind:

* Values are matched exactly, so `Ana@x.com` and `ana@x.com` are two different values. Changing this later means dropping and recreating the index.
* `_id` is always unique, so it can't be the only attribute of a unique index, and a single index can't cover two array attributes.
* If a new unique index adds nothing to an existing one, FlowX Designer asks you to confirm with **Create anyway**.
* If the collection sets a partitioning key and is sharded, the unique index must start with that key.

Like any index, a unique index is only created in the database when you run **Apply Indexes** on a build. That is when FlowX.AI checks for existing duplicates: if the environment's collection already holds duplicate values, the **Apply Indexes** window lists sample values and keeps **Apply** unavailable. Remove the duplicates from that environment's collection (for example from the **Documents** tab), then click **Re-check**. See [Apply indexes](/5.9/docs/projects/runtime/builds#apply-indexes).

After the index is applied, an insert or update that would create a duplicate fails.

***

### Creating database operations

> [tab] Create operation
>
> **1. Access operations list**
>
> Navigate to your FlowX Database collection in the Data Sources section.
>
> **2. Create new operation**
>
> Click the "+" button to create a new operation.
>
> ![Creating a new operation for a FlowX Database collection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/new_operation.png)
>
> Creating a new operation for a FlowX Database collection
>
> **3. Select operation type**
>
> Choose the operation type from the dropdown (find, findOne, insertOne, insertMany, etc.).
>
> ![Selecting the operation type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/operation_type_selection.png)
>
> Selecting the operation type
>
> **4. Name the operation**
>
> Give your operation a meaningful name and description that indicates its purpose.
>
> **5. Define the operation parameters**
>
> Configure the parameters for your operation based on its type. For example, for a find operation:
>
> ![Configuring operation parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb5.png)
>
> Configuring operation parameters
>
> * **Filter**: Define the criteria to match documents
>
> * **Projection**: Select which fields to include in the results
>
> * **Sort**: Specify the sorting order
>
> * **Skip**: For find operations, specify the number of documents to skip
>
> * **Limit**: Set the maximum number of documents to return
>
> > [!NOTE]
> >
> > **Parameter Syntax**: When defining operation parameters, remember:
> >
> > * **Parameters defined in the operation** are referenced using `${parameterName}` syntax
> > * **Database field names** must be in quotes (e.g., `"firstName"`, `"customerId"`)
> > * Parameters don't need to match your data model exactly - they're placeholders that get replaced with actual values
> > * Field names in quotes must match exactly what's stored in the database (same as your data model)
>
> **6. Test the operation**
>
> Use the test functionality to verify your operation works correctly.
>
> ![Testing an operation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fldb6.png)
>
> Testing an operation
>
> > [!WARNING]
> >
> > **Testing Delete Operations**: Be extremely careful when testing delete operations (`deleteOne` and `deleteMany`) as they will actually remove documents from your collection. Always use test data or ensure you have backups before testing deletion operations in collections with important data.
>
> **7. Save the operation**
>
> Click "Save" to add the operation to your collection. It will now be available for use in workflows.

> [tab] Update operation
>
> **1. Select operation**
>
> From the list of operations, select the one you want to update.
>
> **2. Make changes**
>
> Update the operation name, description, or parameters as needed.
>
> **3. Test updated operation**
>
> Test the updated operation to ensure it works as expected.
>
> **4. Save changes**
>
> Save your changes to apply them to the operation.

> [tab] Delete operation
>
> **1. Select operation**
>
> From the list of operations, select the one you want to delete.
>
> **2. Delete operation**
>
> Click the delete button and confirm the deletion when prompted.
>
> **3. Verify removal**
>
> Verify that the operation has been removed from the collection.

### Visual query builder

Instead of writing raw MongoDB query syntax, you can use the visual query builder to define filters, updates, projections, and sorting through a guided interface that understands your collection's schema.

Each operation type has a tailored builder experience. You can switch between **Visual** and **Script** mode at any time with the two icon buttons above the editor: the brick wall icon opens the visual builder, and the curly braces icon opens the JSON query (Script mode). The buttons have no text labels. The two modes work independently — saving in one mode sets that as the active query for the operation.

> [!WARNING]
>
> Switching modes does not sync changes between them. A warning message informs you that saving in the current mode will set it as the final query for the operation.

#### Condition rows

The core building block of the query builder is the **condition row**, used in filter sections across all operation types:

| Element | Description |
| - | - |
| **Field dropdown** | Pick a field from the collection schema. Supports nested paths (e.g., `address.city`). Shows a data type badge for each field. |
| **Operator dropdown** | Type-aware operators that change based on the selected field's data type (see table below). |
| **Value input** | Enter a static value or switch to dynamic mode using `${paramName}` syntax. Input type adapts to the field type (text, number, date picker, boolean toggle, enum dropdown). |
| **Remove button** | Delete the condition row. |

Multiple condition rows can be combined with **AND** or **OR** logic using a dropdown selector. AND is the default.

> [!NOTE]
>
> Each condition row is matched on its own. Two conditions on fields inside the same array of objects, such as `items.sku` and `items.qty`, can be met by **different** elements of the array. When both must hold on the same element, write the filter in Script mode with `$elemMatch`. See [Filter on nested fields and arrays of objects](#mongodb-operations-supported).

#### Type-aware operators

The available operators change based on the selected field's data type:

| Field type | Available operators |
| - | - |
| **String** | equals, not equals, contains, starts with, ends with, matches regex, in, not in, exists, is null |
| **Number** | equals, not equals, greater than, greater or equal, less than, less or equal, in, exists, is null |
| **Boolean** | equals, exists |
| **Date/Time** | equals, before, after, exists, is null |
| **Enum** | equals, not equals, in, not in, exists |
| **Object** | exists, not exists |
| **Array** | contains, size equals, size greater than, exists, and on SaaS (5.13) intersects |

> [!TIP]
>
> Fields not in the schema can also be used — select a custom key and a data type selector appears so you can set the appropriate operators.

#### Intersects on array fields

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**intersects** matches documents whose array field shares at least one value with the list you supply. The value is either a literal list of strings or numbers, or a single `${param}` that resolves to a list at runtime. A parameter cannot be placed inside a literal list. Documents where the field is not an array never match.

> [!NOTE]
>
> Conditions that use **intersects**, like aggregation stages, are not included in the version 3 export format. Use the current export format when moving operations that rely on them.

#### Builder sections by operation type

> [tab] Find / Find One
>
> * **Filter**: Condition rows to define which documents to match
> * **Sort**: Add sort fields with ASC/DESC direction
> * **Projection**: Select fields to include or exclude from results
> * **Pagination** (find only): Set **Limit** (max documents) and **Skip** (offset) values

> [tab] Insert / Insert Many
>
> * **Document fields**: Auto-populated from the collection schema with appropriate input types per field
> * `_id` is auto-included with an "auto-generated" indicator
> * Array fields have an **+ Add item** button
> * Each field supports static values or `${paramName}` dynamic references

> [tab] Update / Update Many
>
> * **Filter section**: Same condition row builder as Find — defines which documents to update
> * **Update section**: Define what to change in matching documents:
>
> | Update operator | Description |
> | - | - |
> | `$set` | Replace field value |
> | `$unset` | Remove field |
> | `$inc` | Increment number |
> | `$push` | Add to array |
> | `$pull` | Remove from array |
> | `$addToSet` | Add unique value to array |

> [tab] Delete / Delete Many
>
> * **Filter section**: Same condition row builder as Find — defines which documents to delete
>
> > [!WARNING]
> >
> > A warning banner is always displayed: "This operation will permanently delete matching documents."

#### Testing operations

The existing 3-panel test modal is enhanced with the visual builder:

* **Left panel**: Input parameters — fill in test values for `${paramName}` references
* **Middle panel**: Shows the visual builder view of the query
* **Right panel**: Results displayed in tabular format with schema-derived column headers

For insert operations, a **Quick Find** button appears after a successful test, letting you immediately verify the inserted document.

***

### Aggregation pipelines

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Database operations support MongoDB **aggregation pipelines**, so you can group, join, reshape, and compute across documents beyond what a single query allows. A pipeline is built as an ordered list of **stages** — such as **Filter**, **Sort**, **Projection**, and **Limit** — each configured in the visual builder and applied in sequence to the collection. Use aggregation when you need computed results (counts, sums, grouped summaries) rather than raw documents.

***

## Working with FlowX Database in workflows

![Database node in a workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/database_node_workflow.png)

Database node in a workflow

FlowX Database integrates directly with the workflow designer through the "Data Source" node type:

**1. Add Data Source node**

In your workflow, add a new node and select the 'DATA\_SOURCE' type.

**2. Configure data source**

In the node properties panel:

![Data Source node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/data_source_node_config.png)

Data Source node configuration

1. Choose "FlowX Database" as the system type from the dropdown
2. Select your collection from the available options
3. Choose the operation you want to perform (find, findOne, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany)

**3. Configure operation parameters**

Set the parameters for your selected operation. The available parameters will depend on the operation type:

* **filter** - For find operations, define the criteria to match documents
* **sort** - For find operations, specify the sorting order for results
* **document** - For insert operations, define the document to insert
* **update** - For update operations, define the document to update
* **delete** - For delete operations, define the criteria to match documents
* **skip** - For find operations, specify the number of documents to skip
* **limit** - For find operations, specify the maximum number of documents to return
* **projection** - For find operations, specify the fields to include or exclude in the results

![Configuring operation parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/config_operation_params.png)

Configuring operation parameters

You can use static JSON or reference process variables using the expression syntax.

**4. Set response key**

Specify where the operation result should be stored in the process instance. This makes the data available to subsequent nodes in your workflow.

> [accordion] Example: Using filter parameter in find operation
>
> ```json theme={"dark"}
> {
>   "age": { "$gt": 30 },
>   "status": "active"
> }
> ```
>
> This filter will return all documents where the age is greater than 30 and the status is "active".
>
> > [!NOTE]
> >
> > For more information about MongoDB comparison operators like \$gt, see [Comparison Query Operators](https://www.mongodb.com/docs/manual/reference/operator/query-comparison/).

> [accordion] Example: Using process variables in parameters
>
> ```json theme={"dark"}
> {
>   "customerId": "${processInstance.customerData.id}"
> }
> ```
>
> This filter uses a value from the process instance to find documents matching a specific customer ID.
>
> > [!NOTE]
> >
> > Learn more about MongoDB query syntax in the [Query Documents Tutorial](https://www.mongodb.com/docs/manual/tutorial/query-documents/).

## MongoDB operations supported

FlowX Database uses MongoDB's query capabilities through the **nosql-db-runner** service, providing pure MongoDB functionality. For detailed information about MongoDB query operators, filters, and syntax, refer to the [MongoDB Query and Projection Operators documentation](https://www.mongodb.com/docs/manual/reference/operator/query/).

The following MongoDB operations are supported in FlowX Database. Each tab includes practical examples that you can use as a starting point for your own operations.

> [tab] find
>
> **Parameters:**
>
> For complete documentation on find operations and query syntax, see [MongoDB db.collection.find()](https://www.mongodb.com/docs/manual/reference/method/db.collection.find/).
>
> * **filter** (document, optional): Criteria to match documents. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
>
> * **sort** (document, optional): Document specifying the sorting order. See [Sort Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/)
>
> * **skip** (integer, optional): Number of documents to skip. See [Limit Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.skip/)
>
> * **limit** (integer, optional): Maximum number of documents to return. See [Limit Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.limit/)
>
> * **projection** (document, optional): Fields to include or exclude. See [Project Fields](https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/)
>
> > [accordion] Example: List active customers
> >
> > This example finds all active customers, sorts them by registration date (newest first), limits to 10 results, and returns only specific fields.
> >
> > Operation name: listActiveCustomers
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": "active"
> > > }
> > > ```
> >
> > > [tab] sort
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerSince": -1
> > > }
> > > ```
> >
> > > [tab] projection
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerId": 1,
> > >   "firstName": 1,
> > >   "lastName": 1,
> > >   "email": 1,
> > >   "status": 1,
> > >   "_id": 0
> > > }
> > > ```
> >
> > > [tab] skip
> > >
> > > ```
> > > 0
> > > ```
> >
> > > [tab] limit
> > >
> > > ```
> > > 10
> > > ```
> >
> > This operation will return up to 10 active customers, with the most recently registered customers first.
>
> > [accordion] Example: Find products by category and price
> >
> > This example finds products in a specific category within a price range.
> >
> > Operation name: findAffordableElectronics
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "category": "electronics",
> > >   "price": { "$gte": 10, "$lte": 100 }
> > > }
> > > ```
> >
> > > [tab] sort
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "price": 1
> > > }
> > > ```
> >
> > > [tab] projection
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "productName": 1,
> > >   "price": 1,
> > >   "rating": 1,
> > >   "inStock": 1,
> > >   "_id": 0
> > > }
> > > ```
> >
> > > [tab] limit
> > >
> > > ```
> > > 20
> > > ```
> >
> > This operation will return up to 20 electronics products with prices between $10 and $100, sorted from lowest to highest price.
>
> > [accordion] Example: Filter on nested fields and arrays of objects
> >
> > In Script mode, the filter goes to MongoDB unchanged, so standard MongoDB filter syntax works. Use dot notation for a field inside an object, and `$elemMatch` when several conditions must hold on the same element of an array.
> >
> > Operation name: findClujOrdersWithBulkItem
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "address.city": "Cluj",
> > >   "items": { "$elemMatch": { "sku": "A1", "qty": { "$gt": 2 } } }
> > > }
> > > ```
> >
> > This operation returns orders shipped to Cluj that contain at least one line with SKU `A1` **and** a quantity above 2 on that same line. Without `$elemMatch`, `{"items.sku": "A1", "items.qty": {"$gt": 2}}` would also match an order where one line has SKU `A1` and a different line has a quantity above 2.

> [tab] findOne
>
> **Parameters:**
>
> For complete documentation on findOne operations, see [MongoDB db.collection.findOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.findOne/).
>
> * **filter** (document, optional): Criteria to match the document. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
>
> * **projection** (document, optional): Fields to include or exclude. See [Project Fields](https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/)
>
> * **sort** (document, optional): Document specifying the sorting order. See [Sort Query Results](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/)
>
> > [accordion] Example: Find customer by ID
> >
> > This example retrieves a single customer by their unique customer ID.
> >
> > Operation name: findCustomerById
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerId": "${processInstance.customerId}"
> > > }
> > > ```
> >
> > > [tab] projection
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "firstName": 1,
> > >   "lastName": 1,
> > >   "email": 1,
> > >   "phone": 1,
> > >   "status": 1,
> > >   "customerSince": 1,
> > >   "address": 1,
> > >   "_id": 0
> > > }
> > > ```
> >
> > This operation uses a process variable for the customer ID and returns specific customer fields. Since findOne only returns one document, sort is usually unnecessary unless you need the first document matching certain criteria.
>
> > [accordion] Example: Find latest order
> >
> > This example finds the most recent order for a customer.
> >
> > Operation name: findLatestOrder
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerId": "${processInstance.customerId}"
> > > }
> > > ```
> >
> > > [tab] sort
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "orderDate": -1
> > > }
> > > ```
> >
> > > [tab] projection
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "orderId": 1,
> > >   "orderDate": 1,
> > >   "totalAmount": 1,
> > >   "status": 1,
> > >   "items": 1,
> > >   "_id": 0
> > > }
> > > ```
> >
> > This operation will find the most recent order for a specific customer by sorting by orderDate in descending order and returning only the first match.

> [tab] insertOne
>
> **Parameters:**
>
> For complete documentation on insertOne operations, see [MongoDB db.collection.insertOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertOne/).
>
> * **document** (document, required): The document to insert. See [Insert Documents](https://www.mongodb.com/docs/manual/tutorial/insert-documents/)
>
> > [accordion] Example: Create a new customer
> >
> > This example inserts a new customer record using data from a process instance.
> >
> > Operation name: createCustomer
> >
> > > [tab] document
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerId": "${processInstance.customerData.id}",
> > >   "firstName": "${processInstance.customerData.firstName}",
> > >   "lastName": "${processInstance.customerData.lastName}",
> > >   "email": "${processInstance.customerData.email}",
> > >   "phone": "${processInstance.customerData.phone}",
> > >   "status": "active",
> > >   "customerSince": "${processInstance.customerData.registrationDate}",
> > >   "address": {
> > >     "street": "${processInstance.customerData.address.street}",
> > >     "city": "${processInstance.customerData.address.city}",
> > >     "state": "${processInstance.customerData.address.state}",
> > >     "zipCode": "${processInstance.customerData.address.zipCode}"
> > >   }
> > > }
> > > ```
> >
> > This operation creates a new customer document with nested address data, using values from the process instance.
>
> > [accordion] Example: Log a system event
> >
> > This example logs a system event with static and dynamic data.
> >
> > Operation name: logSystemEvent
> >
> > > [tab] document
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "eventType": "user_action",
> > >   "action": "${processInstance.actionType}",
> > >   "timestamp": "${processInstance.currentDateTime}",
> > >   "userId": "${processInstance.userId}",
> > >   "details": "${processInstance.actionDetails}",
> > >   "source": "workflow",
> > >   "processId": "${processInstance.id}"
> > > }
> > > ```
> >
> > This operation creates an event log entry with information about user actions in the system.

> [tab] insertMany
>
> **Parameters:**
>
> For complete documentation on insertMany operations, see [MongoDB db.collection.insertMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertMany/).
>
> * **documents** (array, required): Array of documents to insert. See [Insert Documents](https://www.mongodb.com/docs/manual/tutorial/insert-documents/)
>
> > [accordion] Example: Import multiple customers
> >
> > This example inserts multiple customer records at once, typically from an imported data source.
> >
> > Operation name: importCustomers
> >
> > > [tab] documents
> > >
> > > ```json theme={"dark"}
> > > [
> > >   {
> > >     "customerId": "CUST001",
> > >     "firstName": "John",
> > >     "lastName": "Doe",
> > >     "email": "john.doe@example.com",
> > >     "status": "active",
> > >     "customerSince": "2025-01-15"
> > >   },
> > >   {
> > >     "customerId": "CUST002",
> > >     "firstName": "Jane",
> > >     "lastName": "Smith",
> > >     "email": "jane.smith@example.com",
> > >     "status": "active",
> > >     "customerSince": "2025-01-20"
> > >   },
> > >   {
> > >     "customerId": "CUST003",
> > >     "firstName": "Robert",
> > >     "lastName": "Johnson",
> > >     "email": "robert.j@example.com",
> > >     "status": "inactive",
> > >     "customerSince": "2024-11-05"
> > >   }
> > > ]
> > > ```
> >
> > This operation inserts multiple customer records at once. In a real scenario, you would typically reference a process variable containing the array: `{processInstance.importedCustomers}`
>
> > [accordion] Example: Create order items
> >
> > This example creates multiple order items for a single order.
> >
> > Operation name: createOrderItems
> >
> > > [tab] documents
> > >
> > > ```json theme={"dark"}
> > > [
> > >   {
> > >     "orderId": "${processInstance.orderId}",
> > >     "productId": "${processInstance.items[0].productId}",
> > >     "quantity": "${processInstance.items[0].quantity}",
> > >     "unitPrice": "${processInstance.items[0].price}",
> > >     "subtotal": "${processInstance.items[0].subtotal}"
> > >   },
> > >   {
> > >     "orderId": "${processInstance.orderId}",
> > >     "productId": "${processInstance.items[1].productId}",
> > >     "quantity": "${processInstance.items[1].quantity}",
> > >     "unitPrice": "${processInstance.items[1].price}",
> > >     "subtotal": "${processInstance.items[1].subtotal}"
> > >   }
> > > ]
> > > ```
> >
> > This operation creates multiple order item records for a single order. In practice, you would use `{processInstance.items}` directly if your process data model matches the database structure.

> [tab] updateOne
>
> **Parameters:**
>
> For complete documentation on updateOne operations, see [MongoDB db.collection.updateOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateOne/).
>
> * **filter** (document, required): Criteria to match the document to update. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
>
> * **update** (document, required): Update operations to apply. See [Update Operators](https://www.mongodb.com/docs/manual/reference/mql/update/)
>
> > [!WARNING]
> >
> > **Important Update Behavior**: When using update operations without the `$set` operator, the entire document will be replaced with the new data. This means any fields not included in your update payload will be removed from the document. Always use the `$set` operator to update specific fields while preserving others.
>
> > [accordion] Example: Update customer status
> >
> > This example updates a customer's status and records when the change occurred.
> >
> > Operation name: updateCustomerStatus
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerId": "${processInstance.customerId}"
> > > }
> > > ```
> >
> > > [tab] update
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "$set": {
> > >     "status": "${processInstance.newStatus}",
> > >     "lastUpdated": "${processInstance.currentDate}",
> > >     "statusReason": "${processInstance.statusChangeReason}"
> > >   }
> > > }
> > > ```
> >
> > This operation updates a customer's status along with the reason and timestamp.
>
> > [accordion] Example: Update order with tracking information
> >
> > This example updates an order with shipping details and increments a counter.
> >
> > Operation name: updateOrderShipping
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "orderId": "${processInstance.orderId}"
> > > }
> > > ```
> >
> > > [tab] update
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "$set": {
> > >     "status": "shipped",
> > >     "shippingDetails": {
> > >       "carrier": "${processInstance.shippingData.carrier}",
> > >       "trackingNumber": "${processInstance.shippingData.trackingNumber}",
> > >       "estimatedDelivery": "${processInstance.shippingData.estimatedDelivery}"
> > >     },
> > >     "lastUpdated": "${processInstance.currentDateTime}"
> > >   },
> > >   "$inc": {
> > >     "statusUpdates": 1
> > >   }
> > > }
> > > ```
> >
> > This operation updates an order with shipping information, sets the status to "shipped", and increments a counter tracking the number of status updates.

> [tab] updateMany
>
> **Parameters:**
>
> For complete documentation on updateMany operations, see [MongoDB db.collection.updateMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateMany/).
>
> * **filter** (document, required): Criteria to match documents to update. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
>
> * **update** (document, required): Update operations to apply. See [Update Operators](https://www.mongodb.com/docs/manual/reference/mql/update/)
>
> > [!WARNING]
> >
> > **Important Update Behavior**: When using update operations without the `$set` operator, the entire document will be replaced with the new data. This means any fields not included in your update payload will be removed from the document.
> >
> > For example, if a document has `id`, `name`, and `email`, and you update only the `name` field without using `$set`, the `email` field will be deleted. Always use the `$set` operator to update specific fields while preserving others.
>
> > [accordion] Example: Deactivate inactive customers
> >
> > This example updates the status of multiple customers based on their last activity date.
> >
> > Operation name: deactivateInactiveCustomers
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "lastActivityDate": { "$lt": "${processInstance.thresholdDate}" },
> > >   "status": "active"
> > > }
> > > ```
> >
> > > [tab] update
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "$set": {
> > >     "status": "inactive",
> > >     "deactivationDate": "${processInstance.currentDate}",
> > >     "deactivationReason": "inactivity"
> > >   }
> > > }
> > > ```
> >
> > This operation identifies all active customers whose last activity date is older than a threshold date and marks them as inactive.
> >
> > > [!NOTE]
> > >
> > > **Key MongoDB Operators**: This example uses `$lt` (less than) for date comparison and `$set` to update specific fields without affecting other customer data. The `$set` operator is essential for partial document updates.
>
> > [accordion] Example: Update multiple customers by ID list
> >
> > This example demonstrates updating multiple specific customers using the `$in` operator.
> >
> > Operation name: updateCustomersByIdList
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerId": { "$in": ["${processInstance.customerIds}"] }
> > > }
> > > ```
> >
> > > [tab] update
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "$set": {
> > >     "lastContactedDate": "${processInstance.currentDate}",
> > >     "contactMethod": "${processInstance.contactMethod}",
> > >     "notes": "${processInstance.contactNotes}"
> > >   }
> > > }
> > > ```
> >
> > This operation updates all customers whose IDs are in the provided list, setting contact information for multiple customers at once.
> >
> > > [!TIP]
> > >
> > > **Standard MongoDB Pattern**: The combination of `$in` for filtering and `$set` for updating is a standard pattern in MongoDB. Use `$in` when you need to match against a list of values, and always use `$set` to avoid replacing the entire document.
>
> > [accordion] Example: Apply discount to products
> >
> > This example applies a discount to all products in a specific category.
> >
> > Operation name: applySeasonalDiscount
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "category": "${processInstance.discountCategory}",
> > >   "onSale": false
> > > }
> > > ```
> >
> > > [tab] update
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "$mul": {
> > >     "price": ${processInstance.discountFactor}
> > >   },
> > >   "$set": {
> > >     "onSale": true,
> > >     "discountPercent": "${processInstance.discountPercent}",
> > >     "saleEndDate": "${processInstance.saleEndDate}"
> > >   }
> > > }
> > > ```
> >
> > This operation applies a discount to all products in a specific category by multiplying the price by a discount factor (e.g., 0.8 for 20% off) and setting sale-related fields.
> >
> > > [!TIP]
> > >
> > > **MongoDB Operators in Action**: This example demonstrates essential MongoDB operators:
> > >
> > > * `$mul` multiplies the price by the discount factor
> > > * `$set` updates specific fields without affecting others
> > > * In the filter, you could use `$in` to target multiple categories: `"category": {"$in": ["electronics", "clothing"]}`

> [tab] deleteOne
>
> **Parameters:**
>
> For complete documentation on deleteOne operations, see [MongoDB db.collection.deleteOne()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteOne/).
>
> * **filter** (document, required): Criteria to match the document to delete. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
>
> > [accordion] Example: Delete a customer record
> >
> > This example removes a single customer record by ID.
> >
> > Operation name: deleteCustomer
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "customerId": "${processInstance.customerIdToDelete}"
> > > }
> > > ```
> >
> > This operation deletes a customer record with the specified ID. Make sure to implement proper validation and confirmation before executing deletion operations.
>
> > [accordion] Example: Remove abandoned cart
> >
> > This example removes an abandoned shopping cart after confirmation.
> >
> > Operation name: removeAbandonedCart
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "cartId": "${processInstance.cartId}",
> > >   "status": "abandoned",
> > >   "lastUpdated": { "$lt": "${processInstance.thresholdDate}" }
> > > }
> > > ```
> >
> > This operation deletes a shopping cart that's been marked as abandoned and hasn't been updated since a specific date.

> [tab] deleteMany
>
> **Parameters:**
>
> For complete documentation on deleteMany operations, see [MongoDB db.collection.deleteMany()](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteMany/).
>
> * **filter** (document, required): Criteria to match documents to delete. See [Query Filter Documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
>
> > [accordion] Example: Purge temporary records
> >
> > This example removes all temporary records older than a specified date.
> >
> > Operation name: purgeTemporaryRecords
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": "temporary",
> > >   "createdDate": { "$lt": "${processInstance.purgeThresholdDate}" }
> > > }
> > > ```
> >
> > This operation removes all documents marked as "temporary" that were created before a specific date. Use with caution as this will delete all matching records.
>
> > [accordion] Example: Clear completed tasks
> >
> > This example removes all completed tasks for a specific user.
> >
> > Operation name: clearCompletedTasks
> >
> > > [tab] filter
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "assignedTo": "${processInstance.userId}",
> > >   "status": "completed",
> > >   "completedDate": { "$lt": "${processInstance.olderThanDate}" }
> > > }
> > > ```
> >
> > This operation removes all tasks that are marked as completed, were assigned to a specific user, and were completed before a certain date.

> [!WARNING]
>
> Always use caution with update and delete operations, especially those that affect multiple documents (updateMany, deleteMany). Always include specific filter criteria to avoid unintended changes to your data.

## Real-world example: Customer management system

This example demonstrates how a customer management system could use FlowX Database to persist and share customer data across different processes.

> [accordion] Setup
>
> **1. Create Customer collection**
>
> Create a new FlowX Database data source named "Customers".
>
> ![Creating the Customers FlowX Database data source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/create_cs_db.png)
>
> **2. Define operations**
>
> Create the following operations:
>
> > [tab] findCustomer
> >
> > **Operation Type**: findOne
> >
> > ![findOne operation configuration for findCustomer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/findCustomer.png)
> >
> > **Parameters**:
> >
> > ```json theme={"dark"}
> > {
> >   "filter": {
> >     "customerId": "${processInstance.customerId}"
> >   },
> >   "projection": {
> >     "firstName": 1,
> >     "lastName": 1,
> >     "email": 1,
> >     "phone": 1,
> >     "status": 1,
> >     "customerSince": 1,
> >     "_id": 0
> >   }
> > }
> > ```
> >
> > This operation retrieves a single customer by their customerId, returning only selected fields.
>
> > [tab] createCustomer
> >
> > **Operation Type**: insertOne
> >
> > ![insertOne operation configuration for createCustomer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/createCustomer.png)
> >
> > **Parameters**:
> >
> > ```json theme={"dark"}
> > {
> >   "document": {
> >     "customerId": "${processInstance.customerData.id}",
> >     "firstName": "${processInstance.customerData.firstName}",
> >     "lastName": "${processInstance.customerData.lastName}",
> >     "email": "${processInstance.customerData.email}",
> >     "phone": "${processInstance.customerData.phone}",
> >     "status": "active",
> >     "customerSince": "${processInstance.customerData.registrationDate}",
> >     "address": {
> >       "street": "${processInstance.customerData.address.street}",
> >       "city": "${processInstance.customerData.address.city}",
> >       "state": "${processInstance.customerData.address.state}",
> >       "zipCode": "${processInstance.customerData.address.zipCode}"
> >     }
> >   }
> > }
> > ```
> >
> > This operation inserts a new customer document using data from the process instance.
>
> > [tab] updateCustomerStatus
> >
> > **Operation Type**: updateOne
> >
> > ![updateOne operation configuration for updateCustomerStatus](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/updateCustomerStatus.png)
> >
> > **Parameters**:
> >
> > ```json theme={"dark"}
> > {
> >   "filter": {
> >     "customerId": "${processInstance.customerId}"
> >   },
> >   "update": {
> >     "$set": {
> >       "status": "${processInstance.newStatus}",
> >       "lastUpdated": "${processInstance.currentDate}"
> >     }
> >   }
> > }
> > ```
> >
> > This operation updates a customer's status and sets the lastUpdated timestamp.
>
> > [tab] listActiveCustomers
> >
> > **Operation Type**: find()
> >
> > ![find operation configuration for listActiveCustomers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/listActiveCustomers.png)
> >
> > **Parameters**:
> >
> > ```json theme={"dark"}
> > {
> >   "filter": {
> >     "status": "active"
> >   },
> >   "sort": {
> >     "customerSince": -1
> >   },
> >   "limit": 50,
> >   "projection": {
> >     "customerId": 1,
> >     "firstName": 1,
> >     "lastName": 1,
> >     "email": 1,
> >     "status": 1,
> >     "_id": 0
> >   }
> > }
> > ```
> >
> > This operation retrieves a list of active customers, sorted by registration date (newest first), limited to 50 results.

> [accordion] Customer support process
>
> In this process:
>
> 1. Support agent enters the customer ID
> 2. A Data Source node retrieves the customer details from the Customers collection
> 3. Customer information is displayed to the agent
> 4. After resolving the issue, the support agent updates the customer status
> 5. Another Data Source node updates the customer record in the database

> [accordion] Benefits demonstrated
>
> > [card]
> >
> > This example shows how FlowX Database:
> >
> > * Enables data persistence across multiple processes
> > * Provides a single source of truth for customer data
> > * Makes data retrieval and updates easier
> > * Eliminates the need for external systems to store basic customer information

## Limitations and considerations

**Current limitations of FlowX Database**

> [!WARNING]
>
> Multiple versions of documents are stored in the collection. Upon retrieval, all data that fits the filter conditions will be retrieved regardless of version.

> [!WARNING]
>
> No automatic migration capabilities are available. Any migration will need to be done manually by the DevOps team.

> [!WARNING]
>
> In the initial release, FlowX Database does not support transactions across multiple collections.

> [!WARNING]
>
> Data validation based on a schema is not yet supported.

## Best practices

> [!TIP]
>
> **Design before implementation**: Plan your collections and operations carefully before implementation.

> [!TIP]
>
> **Keep document structure simple**: Avoid deeply nested structures for better performance and easier querying.

> [!TIP]
>
> **Use meaningful names**: Choose clear names for collections and operations.

> [!TIP]
>
> **Limit document size**: Keep individual documents under 16MB for optimal performance.

> [!TIP]
>
> **Test operations thoroughly**: Use the testing functionality to ensure operations work as expected.

> [!TIP]
>
> **Consider indexing**: For large collections, consider indexing frequently queried fields.

> [!TIP]
>
> **Provide default values**: Ensure all data types have default values (e.g., empty string for null, 0 for integers).

## Troubleshooting

> [accordion] Operation fails with filter error
>
> **1. Problem**
>
> Find operation fails with an error related to the filter syntax.
>
> **2. Solution**
>
> Check your filter syntax to ensure it follows MongoDB query syntax. Common issues:
>
> * Missing quotes around string values
> * Incorrect operator syntax (e.g., using > instead of \$gt)
> * Mismatched brackets or braces

> [accordion] Documents not appearing in results
>
> **1. Problem**
>
> Your query doesn't return expected documents.
>
> **2. Solution**
>
> * Verify your filter conditions are correct
> * Check if documents actually exist in the collection
> * Try a more general query to see if documents are returned
> * Check if field names in your filter match exactly with the document structure

> [accordion] Performance issues with large result sets
>
> **1. Problem**
>
> Queries returning large amounts of data are slow.
>
> **2. Solution**
>
> * Add pagination using skip and limit parameters
> * Add more specific filter conditions
> * Use projection to return only needed fields
> * Consider indexing frequently queried fields

> [accordion] Insert operation fails
>
> **1. Problem**
>
> Insert operation fails with an error.
>
> **2. Solution**
>
> * Check that your document JSON is valid
> * Ensure document size is under 16MB
> * Verify all required fields are present
> * Check for any unique constraint violations

## Related features

> [card] [Cookbook: reconcile invoices](/5.9/cookbooks/invoice-reconciliation)
>
> See FlowX Database in a full build: look up each invoice's purchase order and compare them in a workflow.

> [card] [Data Search](../core-extensions/search-data-service)
>
> Learn about the Data Search service for indexing and searching process data.

> [card] [Integration Management](./integration-designer)
>
> Understand how to manage integrations with external systems.

> [card] [Workflow](../integrations/integration-workflows)
>
> See how workflows can interact with data sources.

> [card] [Process Data Model](../../building-blocks/process/data-model)
>
> Learn about data models used within processes.

## Summary

FlowX Database provides a persistence layer that enables you to store and share data across different processes and projects. By using MongoDB's capabilities through the **nosql-db-runner** service, FlowX Database offers:

1. **Flexible data storage** for any structured data
2. **Data sharing** between process instances
3. **Integration** with workflows
4. **Independence** from external systems for basic data persistence

## MongoDB learning resources

To get the most out of FlowX Database, familiarize yourself with MongoDB concepts and operations:

> [card] [MongoDB Manual](https://www.mongodb.com/docs/manual/)
>
> Complete MongoDB documentation covering all operations and concepts

> [card] [Query Tutorial](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
>
> Learn how to construct effective MongoDB queries

> [card] [Update Operations](https://www.mongodb.com/docs/manual/tutorial/update-documents/)
>
> Master document update operations and operators

> [card] [Data Modeling](https://www.mongodb.com/docs/manual/core/data-modeling-introduction/)
>
> Best practices for structuring your data in MongoDB

## FAQs

> [accordion] When should I use Data Search vs. FlowX Database?
>
> FlowX Database does not replace Data Search. Each serves different purposes in the platform.
>
> > [tab] FlowX Database
> >
> > * Acts as a persistent data store
> > * Optimized for CRUD operations
> > * Stores structured business data
> > * Designed for sharing data across processes
> > * Uses MongoDB as the underlying technology (via nosql-db-runner service)
>
> > [tab] Data Search
> >
> > * Provides indexing and search capabilities
> > * Optimized for quick lookups and aggregations
> > * Used for debugging and analytics
> > * Enables searching across process instances
> > * Uses Elasticsearch as the underlying technology

> [accordion] What types of data should I store in FlowX Database?
>
> FlowX Database is designed for **operational data with temporary character**, including:
>
> * **Dashboard data**: Aggregated information for reporting and visualization. For example, create operations that gather information from multiple processes and pull all the data to calculate sums, averages, or other metrics for executive dashboards
>
> * **Cached data**: Frequently accessed information that changes periodically, such as:
>   * Daily exchange rates for financial calculations
>   * Product catalogs that update weekly
>   * Configuration data that multiple processes need to access
>
> * **Internal operational comments**: Information that needs to be shared between users but shouldn't reach business systems, such as:
>   * Internal comments in a client's profile for bank tellers
>   * Notes and annotations that support decision-making across different process instances
>   * Communication logs between team members working on the same case
>
> * **Shared process data**: Information that needs to be accessed across multiple process instances - this solves the key pain point of data sharing between different process instances
>
> * **Temporary operational data**: Working data that supports business processes but isn't part of your permanent records
>
> > [!WARNING]
> >
> > **Important**: FlowX Database should **not become your primary book of records** or system of record. Use it for operational data that supports your processes, not for critical business data that requires long-term retention and governance.

> [accordion] Can I share FlowX Database collections between different projects?
>
> Yes, you can share collections between projects using the library approach:
>
> 1. **Create collections in one project**: Set up your FlowX Database collections in a primary project
> 2. **Include as libraries**: Add these collections as libraries in other projects that need access
> 3. **Maintain consistency**: This approach ensures all projects use the same data structures and operations
> 4. **Future-proof management**: Having centralized collection definitions makes updates and maintenance easier across all projects
>
> This pattern is particularly useful for shared reference data, common configurations, or cross-project operational data.
>
> > [!NOTE]
> >
> > **Collection Ownership**: Each FlowX Database collection has an owner - either the project where it was created or the library that contains it. By default, only processes and workflows within the same project can access a collection. If you need to access the same collection from multiple projects, create it in a library and then include that library in all projects that need access.

> [accordion] Why doesn't FlowX Database support automatic data migration?
>
> FlowX Database intentionally does not provide automatic migration capabilities for several important reasons:
>
> * **Data integrity**: Many documents need to remain in their original format to maintain historical accuracy and compliance requirements
> * **Process dependencies**: Existing processes may depend on specific data structures, and automatic changes could break functionality
> * **Business context**: Data migration often requires business logic and context that automated systems cannot provide
> * **Risk management**: Manual migration allows for proper testing and validation before changes are applied
>
> When you need to modify data structures, plan for manual migration processes with proper testing and validation procedures handled by your DevOps team.

> [accordion] Can I store different types of documents in the same collection?
>
> **No, this is strongly discouraged.** Each collection should contain documents with the same structure and purpose.
>
> **DON'T DO IT** - Mixing different document types in one collection can lead to:
>
> * **Query complexity**: Filtering becomes more complex when documents have different schemas
> * **Performance issues**: Indexes become less effective with mixed document types
> * **Maintenance problems**: Updates and changes become harder to manage
> * **Data consistency**: Harder to ensure data quality and validation
>
> Instead, create separate collections for each document type, even if they seem related. This follows MongoDB best practices and keeps your data organized and manageable.

> [accordion] How does FlowX Database solve cross-process data sharing?
>
> FlowX Database solves the key pain point of **accessing the same data from multiple process instances**:
>
> * **Cross-instance access**: Multiple process instances can read from and write to the same collections simultaneously
> * **Data persistence**: Data remains available even after individual processes complete
> * **Concurrent access**: The underlying MongoDB technology (via nosql-db-runner) handles concurrent read/write operations safely
> * **Shared state**: Enables complex workflows where processes need to coordinate through shared data
>
> This capability enables use cases like multi-step approval processes, shared customer data across different business processes, and coordinated workflows that span multiple process instances - addressing a major limitation of traditional process-scoped data storage.

> [accordion] What's the relationship between FlowX Database and the nosql-db-runner service?
>
> FlowX Database is powered by the **nosql-db-runner** microservice, which provides:
>
> * **Pure MongoDB functionality**: Direct access to MongoDB operations within the FlowX ecosystem
> * **Native integration**: Connection between FlowX workflows and MongoDB operations
> * **Scalable architecture**: A dedicated service that can be scaled independently based on database operation needs
>
> The nosql-db-runner acts as the bridge between FlowX's workflow engine and MongoDB, enabling you to use MongoDB's full capabilities while maintaining FlowX's process orchestration capabilities.

***

## Academy courses

> [card] [Integration Designer course](https://academy.flowx.ai/explore/integration-designer)
>
> Hands-on course covering systems, data sources, workflows, and database integration patterns

> [card] [Data Mappers course](https://academy.flowx.ai/explore/5data-mappers)
>
> Learn data mapping and transformation between process and integration workflows


# Integration Designer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/integration-designer

Connect FlowX to external systems via REST APIs using a drag-and-drop interface for data models, workflows, and endpoints.

> [card] Did you know?
>
> Unlike [Postman](https://www.postman.com/), which focuses on API testing, the Integration Designer automates workflows between systems. With drag-and-drop ease, it handles REST API connections, real-time processes, and error management, making integrations scalable and maintainable.

## Overview

Integration Designer facilitates the integration of the FlowX platform with external systems, applications, and data sources.

> [!TIP]
>
> **Build one:** [Build your first workflow](/5.9/docs/getting-started/building-your-first-workflow) walks through a REST data source, a workflow that calls it, and a process that starts the workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)

> [!NOTE]
>
> Integration Designer supports multiple data source types including RESTful Systems, FlowX Database, MCP Integration, Knowledge Base, Email Trigger, Email Sender, and Microsoft Outlook.

> [!NOTE]
>
> Integration resources (data sources, workflows, systems) are versioned as part of your project version, not individually. Changes are tracked in the project's [**Resources Changed**](/5.9/docs/projects/managing-applications/versioning#resources-changed) view. To view the change history for a specific integration resource, right-click it and select **View History**.

***

## Key features

**1. Drag-and-Drop Simplicity**

You can build complex API workflows using a drag-and-drop interface, making it accessible for both technical and non-technical audience.

**2. Visual REST API Integration**

Specifically tailored for creating and managing REST API calls through a visual interface, streamlining the integration process without the need for extensive coding.

**3. Real-Time Testing and Validation**

Allows for immediate testing and validation of REST API calls within the design interface.

***

## Integration Designer guides

> [card] [Data sources and endpoints](./data-sources-and-endpoints)
>
> Define data sources and REST endpoints, with caching, variables, parameters, and authorization

> [card] [File handling](./endpoint-file-handling)
>
> Receive files and XML or SOAP responses, and send files from endpoints

> [card] [Workflows](./integration-workflows)
>
> Create, configure, and run integration workflows

> [card] [Control flow nodes](./workflow-nodes-control-flow)
>
> Start, REST API Call, FlowX Database, Condition, Parallel, Script, Subworkflow, and End nodes

> [card] [Data and AI nodes](./workflow-nodes-data-and-ai)
>
> Tabular data, templates, notifications, PDF files, context retrieval, and AI agent nodes

***

## Integration with external systems

This example demonstrates how to integrate FlowX with an external system, in this example, using Airtable, to manage and update user credit status data. It walks through the setup of a data source, defining API endpoints, creating workflows, and linking them to BPMN processes in FlowX Designer.

> [!TIP]
>
> Before going through this example of integration, we recommend:
>
> * Create your own base and table in Airtable. For more information, see the [Airtable base creation guide](https://www.airtable.com/guides/build/create-a-base).
> * Review the [Airtable Web API documentation](https://airtable.com/developers/web/api/introduction) to get familiarized with the Airtable API.

### Integration in FlowX.AI

**1. Define a Data Source**

Navigate to the **Integration Designer** and create a new data source:

* Name: **Airtable Credit Data**
* **Base URL**: `https://api.airtable.com/v0/`

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/airtable1.png)

**2. Define Endpoints**

In the **Endpoints** section, add the necessary API endpoints for system integration:

1. **Get Records Endpoint**:
   * **Method**: GET
   * **Path**: `/${baseId}/${tableId}`
   * **Path Parameters**: Add the values for the baseId and for the tableId so they will be available in the path.
   * **Header Parameters**: Authorization Bearer token

See the [API docs](https://airtable.com/developers/web/api/list-records).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/airtable2.png)

2. **Create Records Endpoint**:
   * **Method**: POST
   * **Path**: `/${baseId}/${tableId}`
   * **Path Parameters**: Add the values for the baseId and for the tableId so they will be available in the path.
   * **Header Parameters**:
     * `Content-Type: application/json`
     * Authorization Bearer token
   * **Body**: JSON format containing the fields for the new record. Example:

```json theme={"dark"}
   {
    "typecast": true,
    "records": [
        {
            "fields": {
                "First Name": "${firstName}",
                "Last Name": "${lastName}",
                "Age": ${age},
                "Gender": "${gender}",
                "Email": "${email}",
                "Phone": "${phone}",
                "Address": "${address}",
                "Occupation": "${occupation}",
                "Monthly Income ($)": ${income},
                "Credit Score": ${creditScore},
                "Credit Status": "${creditStatus}"
            }
        }
    ]
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/airtable3.png)

**3. Design the Workflow**

1. **Open the Workflow Designer** and create a new workflow.
   * Provide a name and description.

2. **Configure Workflow Nodes**:
   * **Start Node**: Initialize the workflow.

> [!TIP]
>
> On the start node add the data that you want to extract from the process. This way when you will add the **Start Workflow Integration** node action it will be populated with this data.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/start_data.gif)
>
> ```json theme={"dark"}
> {
> "firstName": "${firstName}",
> "lastName": "${lastName}",
> "age": ${age},
> "gender": "${gender}",
> "email": "${email}",
> "phone": "${phone}",
> "address": "${address}",
> "occupation": "${occupation}",
> "income": ${income},
> "creditScore": ${creditScore},
> "creditStatus": "${creditStatus}"
> }
> ```
>
> Make sure these keys are also mapped in the data model of your process with their corresponding attributes.

* **REST Node**: Set up API calls:
  * **GET Endpoint** for fetching records from Airtable.
  * **POST Endpoint** for creating new records.
* **Condition Node**: Add logic to handle credit scores (e.g., triggering a warning if the credit score is below 300).

> [!TIP]
>
> Condition example:
>
> ```json theme={"dark"}
> input.responseKey.data.records[0].fields["Credit Score"] < 300
> ```

* **Script Node**: Include custom scripts if needed for processing data (not used in this example).
* **End Node**: Define the end of the workflow with success or failure outcomes.

<video />

**4. Link the Workflow to a Process**

1. **Integrate the workflow** into a BPMN process:
   * Open the process diagram and include a **User Task** and a **Receive Message Task**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/bpmn_airtable.png)

> [!NOTE]
>
> In this example, we'll use a User Task because we need to capture user data and send it to our workflow.

2. **Map Data** in the **UI Designer**:
   * Create the data model
   * Link data attributes from the data model to form fields, ensuring the user input aligns with the expected parameters.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/data_model_id.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/ut_dat_input.gif)

3. **Add a Start Integration Workflow** node action:

* Make sure all the input will be captured.

<video />

**5. Monitor Workflow and Capture Output**

**Receive Workflow Output**:

* Use the **Receive Message Task** to capture workflow outputs like status or returned data.
* Set up a data stream in the node's **Integration Output** section to ensure workflow output is mapped to a predefined key.

> [!NOTE]
>
> **One key per hop.** Data crosses three boundaries on its way back to the process, and each one uses its own name:
>
> 1. Inside the workflow, the REST node stores its result under its **Response Key** - the body is at `${responseKey.data}`.
> 2. The **End node** maps that value into the workflow's declared **output parameter**.
> 3. The **Receive Message Task** maps the returned output into a **process attribute** through its data stream output mapping.
>
> Most "empty value" problems come from using a key from the wrong hop, or from a typo - a wrong key in a `${...}` placeholder resolves silently to nothing rather than raising an error. If the result never reaches the process, check the [error glossary](/5.9/docs/resources/error-glossary#integration-workflow-output) for the two runtime errors that pinpoint which hop is broken.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/id_kafka_receive.png)

**6. Start the integration**

* Start your process to initiate the workflow integration. It should add a new user with the details captured in the user task.

<video />

* Check if it worked by going to your base in Airtable. You can see, our user has been added.

<video />

***

This example demonstrates how to integrate Airtable with FlowX to automate data management. You configured a data source, set up endpoints, designed a workflow, and linked it to a BPMN process.

***

## Export and import

You can export and import both **data sources** and **workflows** as ZIP files to transfer them between projects or environments (for example, from development to UAT to production).

### Exporting

To export a data source or workflow:

1. Navigate to the **Data Sources** or **Workflows** list in Integration Designer
2. Open the context menu for the resource you want to export
3. Select **Export**
4. The resource is downloaded as a ZIP file containing the full configuration

**What's included in the export:**

* **Data Sources** - data source configuration, endpoints, NoSQL operations, MCP tools
* **Workflows** - workflow nodes and their configurations

### Importing

To import a data source or workflow:

1. Navigate to the **Data Sources** or **Workflows** list in Integration Designer
2. Open the context menu and select **Import from ZIP**
3. Select the ZIP file exported from another project or environment
4. If resources with the same identifiers already exist, a **Review Resource Identifiers Conflicts** modal appears
5. Choose a strategy for each conflicting resource (or use **Apply to all**):
   * **Keep both** - imports the resource as a new copy alongside the existing one
   * **Replace** - overwrites the existing resource with the imported version
   * **Skip this one** - keeps the existing resource unchanged
6. Click **Continue** to complete the import

> [!NOTE]
>
> Importing is only available for work-in-progress (WIP) project versions. You cannot import into a committed version.

## FAQs

> [accordion] Can I call GraphQL, SOAP, or gRPC endpoints?
>
> **A:** For external API calls, the Integration Designer uses **REST (HTTP)** as the communication protocol. There is no dedicated GraphQL, SOAP, gRPC, or JDBC data source type — but protocols that run over HTTP can be called through a REST data source.
>
> You can call a **GraphQL** endpoint by using a REST data source configured with the **POST** method, sending the GraphQL query as a JSON body:
>
> ```json theme={"dark"}
> {
>   "query": "mutation { updatePerson(input: { name: \"${input.name}\" }) { id status } }"
> }
> ```
>
> Set the endpoint content type to `application/json` and map the response as you would for any REST call.
>
> For **SOAP**, there is a dedicated **SOAP System** data source with WSDL import and automatic envelope composition — available on SaaS starting with 5.10; see [SOAP System](./soap-system). On earlier releases (and self-hosted deployments until the next LTS), call a SOAP web service through REST instead: configure a **POST** REST endpoint, set the **Content type** to **Raw**, put the SOAP envelope in the request body, and add the `Content-Type` (`text/xml` or `application/soap+xml`) and `SOAPAction` request headers. The XML response is parsed automatically, so you can map its fields like any JSON response — see [Receiving XML and SOAP responses](./endpoint-file-handling#receiving-xml-and-soap-responses). With the REST approach there is no WSDL import or automatic envelope/fault generation; you build the envelope yourself.
>
> **gRPC** and **JDBC** are not supported — they are not HTTP-based and have no data source type.
>
> The Integration Designer also supports specialized data source types beyond REST: FlowX Database, Unmanaged MongoDB, MCP Server, Knowledge Base, Email Trigger, Email Sender, Incoming Webhook, and Microsoft Outlook. See [Data sources](./data-sources-and-endpoints#data-sources) for details.

> [accordion] How is security handled in integrations??
>
> **A:** The Integration Service handles all security aspects, including certificates and secret keys. Authorization methods like Service Token, Bearer Token, and OAuth 2.0 are supported.

> [accordion] How are errors handled?
>
> **A**: Errors are logged within the workflow and can be reviewed in the monitoring dedicated console for troubleshooting and diagnostics

> [accordion] Can I import endpoint specifications in the Integration Designer?
>
> **A**: You can import full data sources (including their endpoints) and workflows via ZIP files using the **Import from ZIP** option in the context menu. See the [Export and import](#export-and-import) section for details.
>
> Importing endpoint specifications from external formats like Swagger/OpenAPI is not yet supported. Endpoints must be defined manually within the data source configuration.

> [accordion] Can I cache responses from all endpoint methods?
>
> **A**: No. On FlowX.AI 5.9.x, caching is available for GET endpoints only. On SaaS, starting with FlowX.AI 5.11, POST endpoints can also be cached, with the request body as part of the cache key (see [Extended response caching](./data-sources-and-endpoints#extended-response-caching)). PUT, PATCH, and DELETE methods cannot be cached, as they are designed to modify data rather than retrieve it.

> [accordion] What happens if the cache service fails?
>
> **A**: FlowX.AI automatically falls back to calling the external API directly. Your workflows always receive correct data even if caching fails. The failure is logged for monitoring purposes.

> [accordion] Can I use different cache policies for the same endpoint in different workflows?
>
> **A**: No, the cache policy is configured at the endpoint level in the Data Source definition. All workflows using that endpoint share the same cache. If you need different caching behavior, create separate endpoint definitions.

> [accordion] How do I know if my workflow is using cached data?
>
> **A**: Cache status is visible in both the endpoint testing modal and the workflow console logs. You'll see whether the response came from cache (hit) or from the external API (miss), along with the cache key and TTL information.

***

## Academy courses

> [card] [Integration Designer course](https://academy.flowx.ai/explore/integration-designer)
>
> Hands-on course covering systems, data sources, workflows, and REST integration patterns

> [card] [Data Mappers course](https://academy.flowx.ai/explore/5data-mappers)
>
> Learn Kafka data mapping and transformation between process and integration workflows


# Create and run workflows in Integration Designer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/integration-workflows

Choose between a workflow, process, or UI Flow, then create a workflow, define its data model, reference workflow data in nodes, and run or stop it.

A workflow defines a series of tasks and processes to automate system integrations. Within the Integration Designer, workflows can be configured using different components to ensure efficient data exchange and process orchestration.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/integration_designer/workflow_ex.png)

## Workflow, process, or UI Flow: which one do I use?

Use a **workflow** to call external systems and transform data, a **process** to run a multi-step business journey that keeps state, and a **UI Flow** to show screens that don't need a process behind them. A workflow is not a BPMN process: it is a separate resource built here, in the Integration Designer. The three are often combined, for example a process or a UI Flow starts a workflow to fetch data and uses the result.

| | Workflow | Process | UI Flow |
| - | - | - | - |
| **What it is** | An integration flow built in the Integration Designer | A BPMN 2.0 process definition | A multi-platform user interface that runs without a BPMN process |
| **Use it for** | REST API and database calls, data transformation, AI operations | Business logic with approvals, business rules, user tasks, and subprocesses | Dashboards, task lists, navigation shells, and forms that start processes |
| **State** | Stateless: takes input, returns output | Keeps process instance data across steps | No process state of its own |
| **User interaction** | None | User tasks with screens built in the UI Designer | Screens and navigation |

A quick test: if a step waits for a person or must remember data between steps, use a process. If it only fetches, sends, or transforms data, use a workflow. If it only shows screens and starts other resources, use a UI Flow.

To start a workflow from a process, use the [Start Integration Workflow action](/5.9/docs/building-blocks/actions/start-integration-workflow). To start one from a UI Flow, see [When to use Start Workflow vs Start Process](/5.9/docs/building-blocks/ui-flows#when-to-use-start-workflow-vs-start-process). For the UI Flow side of the choice, see [When to use UI Flows](/5.9/docs/building-blocks/ui-flows#when-to-use-ui-flows).

For a worked example that connects all three, see [Combine UI Flows, processes, and workflows](/5.9/docs/building-blocks/combining-ui-flows-processes-and-workflows).

## Creating a workflow

1. Navigate to Workflow Designer:
   * In FlowX.AI Designer to **Projects -> Your application -> Integrations -> Workflows**.
   * Create a New Workflow, provide a name and description, and save it.
2. Start to design your workflow by adding nodes to represent the steps of your workflow:

* **Start Node**: Defines where the workflow begins and also defines the input parameter for subsequent nodes.
* **REST API Call nodes**: Add REST API calls for fetching or sending data.
* **FlowX Database nodes**: Read and write data to FlowX Database collections.
* **Custom Agent nodes**: Enable AI agents to use MCP tools for intelligent task automation.
* **Intent Classification Agent nodes**: Classify user messages using AI and route the workflow to the matching intent branch.
* **Context Retrieval nodes**: Perform RAG searches against Knowledge Bases to retrieve relevant chunks without calling an LLM.
* **Start Parallel and End Parallel nodes**: Run several branches of the workflow at the same time and merge their results when all branches finish.
* **Fork nodes (conditions)**: Add conditional logic for decision-making.
* **Data mapping nodes (scripts)**: Write custom scripts in JavaScript or Python.
* **Subworkflow nodes**: Invoke other workflows as reusable components.
* **Navigate in UI Flow nodes**: Navigate users to specific UI Flow screens from chat-driven workflows, passing dynamic parameters.
* **Web Page Extractor nodes**: Crawl web pages, follow links up to a configurable depth, and extract content for use in workflows or Knowledge Bases.
* **End Nodes**: Capture output data as the completed workflow result, ensuring the process concludes with all required information.
* **Update Knowledge Base**: Update the Knowledge Base with the results of the workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/create_workflow.gif)

### How do I auto-arrange the workflow canvas?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Click **Auto-arrange** in the bottom-right corner of the canvas, above the zoom controls, to lay out every node of the workflow from left to right, starting from the Start node. Nothing is saved until you apply the new layout.

**1. Open the layout preview**

Click **Auto-arrange**. The canvas shows the proposed layout, and the **Layout preview** bar says how many nodes move. While the preview is open, the canvas is read-only.

**2. Compare the layouts**

Switch between **Show current** and **Show preview** to compare the existing layout with the proposed one.

**3. Apply or cancel**

Click **Apply** (or press **Enter**) to save the new node positions, or **Cancel** (or press **Escape**) to keep the current layout.

* Auto-arrange always arranges the whole workflow, not a selection.
* There is no undo after you apply a layout, so compare the two layouts first.
* If the workflow changes after the preview is built, **Apply** becomes **Refresh preview**.
* The button is unavailable when the workflow is read-only, for example when you don't have edit rights or while a running instance is shown on the canvas.

The process editor has the same control, labeled **Arrange**, with the same layout preview.

## Workflow nodes overview

> [!NOTE]
>
> Workflow nodes are the building blocks of your integration logic. Each node type serves a specific function, allowing you to design, automate, and orchestrate complex processes visually.

| Node Type | Purpose |
| - | - |
| Start Node | Defines workflow input and initializes data |
| REST API Call Node | Makes REST API calls to external systems |
| FlowX Database Node | Reads/writes data to the FlowX Database |
| Custom Agent Node | Enables AI agents to use MCP tools for intelligent automation |
| Intent Classification Agent Node | Classifies user messages using AI and routes to matching intent branches |
| Context Retrieval Node | Retrieves relevant data from Knowledge Bases or memory using semantic, keyword, or hybrid search |
| AI Nodes | Process text, documents, images, and data using AI-powered capabilities |
| Condition (Fork) | Evaluates conditions and routes the flow along one matching branch |
| Script Node | Transforms or maps data using JavaScript or Python |
| Update Knowledge Base | Update the Knowledge Base with the results of the workflow |
| Subworkflow Node | Invokes another workflow as a modular, reusable subcomponent |
| Navigate in UI Flow | Navigates the user to a specific screen in a UI Flow from a chat-driven workflow |
| Web Page Extractor | Crawls web pages, follows links up to a configurable depth, and extracts content |
| Tabular Data Extraction | Reads a CSV or spreadsheet file and returns its rows as structured JSON (SaaS · 5.10). Named **Data Parse** and also parses XML and JSON (SaaS · 5.13) |
| Generate Tabular File | Turns workflow data into a CSV or XLSX file stored against the current run (SaaS · 6.0) |
| Template Filling | Generates a document from a document template populated with workflow data (SaaS · 5.10) |
| Combine Files | Merges multiple PDF files into a single output file in a given order (SaaS · 5.10) |
| Split File | Splits a PDF into multiple files by page ranges or one file per page (SaaS · 5.10) |
| End Node | Captures and outputs the final result of the workflow |
| Start Parallel / End Parallel | Run several branches at the same time and merge their results when all branches finish |
| [Document Classification](./document-classifiers) | Classifies a document into one of a configured set of categories using AI (SaaS · 5.11) |

Each node's configuration is described in the node reference pages: [control flow and integration nodes](./workflow-nodes-control-flow) and [data, document, and AI nodes](./workflow-nodes-data-and-ai).

***

## Workflow data models

Workflow Data Models bring structured data management to Integration Designer workflows, enabling you to define input and output parameters at the workflow level, similar to Process Data Models.

### Key benefits

> [card] Automatic Input Management
>
> Input parameters automatically pre-fill the Start Node from the data model—no manual JSON editing

> [card] Consistent Data Lineage
>
> Ensure data consistency across processes and workflows with structured data models

> [card] Type Safety
>
> Define data types and validation rules at the workflow level for runtime safety

> [card] Better Integration
>
> Map data bidirectionally between processes and workflows using data mappers

### Quick start

**1. Define Data Model**

Create entities and attributes for your workflow data structure

**2. Configure Input Parameters**

Select which attributes will be workflow input parameters

**3. Automatic Pre-fill**

Start Node is automatically populated with structured data from your data model

**4. Map to Processes**

Use data mappers to pass data between processes and workflows

> [card] [Complete Workflow Data Models Guide](./workflow-data-models)
>
> Learn how to create workflow data models, configure input/output parameters, and integrate with processes

***

## Referencing workflow data in node configurations

Node configuration fields (file paths, messages, request payloads) reference workflow data with `${...}` expressions:

| Expression | Resolves |
| - | - |
| `${filePath}` | A top-level value from the workflow state |
| `${firstFile.filePath}` | A nested value, using dot navigation |
| `${uploadedFiles}` | A whole object or array |

> [!WARNING]
>
> **Array indexing is not supported in `${...}` expressions.** A reference like `${uploadedFiles[0].filePath}` does not resolve, and the node fails with `The placeholder uploadedFiles[0].filePath has no value set!` even when the value is visible in the node's **Input** tab. The error means the syntax cannot resolve, not that the data is missing.

To use one element of an array, extract it with a **Script node** first, then reference the extracted value with dot navigation:

```javascript theme={"dark"}
// Script node placed before the consuming node
output.firstFile = input.uploadedFiles[0];
```

The next node can then reference `${firstFile.filePath}`.

This applies to every array, including the `uploadedFiles` array that [chat file uploads](/5.9/ai-platform/chat-driven-workflows#file-uploads) deliver to a chat-driven workflow.

***

## Workflow settings

Open **Settings** in the workflow's side navigation to see the **Workflow Settings** page:

| Setting | Description |
| - | - |
| **Kafka Topics** | The **In** and **Out** topics the workflow uses when a process starts it. Both are read-only, with a copy button. |
| **Use workflow in reporting** | Makes the workflow's data available to the reporting plugin. See [Reporting](/5.9/docs/platform-deep-dive/plugins/custom-plugins/reporting/reporting-overview). |
| **Workflow Type** | **Output Focused** or **Chat Driven**. Read-only after the workflow is created, and shown only when the AI runtime is available. See [Chat-driven workflows](/5.9/ai-platform/chat-driven-workflows). |

## Test files

A test file stands in for a real file when you test a node that reads a file, such as Extract Data from File or Speech to Text. Test files belong to the workflow, so you upload a sample once and reuse it on every test run.

Open **Test Files** in the workflow's side navigation to manage them. The list shows each file's **Name**, **Type**, **Uploaded by**, and **Uploaded at**. Click **+** to upload a file, click a row to open or download it, and use the row menu to delete it. Uploading is disabled on a committed version.

Supported types:

| Type | Extensions |
| - | - |
| Image | `png`, `jpg`, `jpeg` |
| Document | `pdf`, `docx` |
| Audio | `mp3`, `wav`, `m4a`, `aac`, `ogg` |

A test file can be up to 15 MB. Audio files are limited to 10 MB, or 5 MB in a chat-driven workflow.

To use a test file, turn on **Use Test File** in the node's configuration and pick one under **Select Test File**, or upload a new one with **Add New Test File**.

***

## Running and stopping workflows

You can run a workflow directly from the editor to test and debug it, and stop it while it is running.

* **Run Workflow**: Click **Run Workflow** in the workflow editor toolbar to start a new workflow instance. You can provide start data in JSON format before running.
* **Stop Run**: While a workflow instance is running, the button changes to **Stop Run**. Click it to cancel the instance. All in-progress and scheduled nodes are marked as cancelled.

Workflow instances can have the following statuses:

| Status | Description |
| - | - |
| **Started** | The workflow instance is currently running |
| **Finished** | The workflow instance completed successfully |
| **Failed** | The workflow instance encountered an error |
| **Cancelled** | The workflow instance was manually stopped by the user |


# Choose how to connect FlowX.AI to external systems
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/integrations-overview

Compare Integration Designer data sources, incoming webhooks, and custom Kafka connectors, and pick the right way to connect FlowX.AI to your external systems.

FlowX.AI connects to external systems in three ways. Most integrations use **Integration Designer**, a low-code environment where you configure a data source (a REST API, database, mailbox, file store, or AI tool) and call it from an integration workflow. External systems can also call into FlowX through **incoming webhooks** or the REST API. For legacy systems that need bespoke logic, self-hosted deployments can run **custom Kafka connectors**.

***

## Which integration approach should I use?

| You need to | Use | Deployment |
| - | - | - |
| Call a REST or SOAP API, query a database, send or read email, or move files | [Integration Designer](./integration-designer) data source, called from an integration workflow | All deployments (some data source types are SaaS-only for now, see the cards below) |
| Start or resume a process when an external system sends an HTTP POST | [Incoming Webhook](./incoming-webhooks) | All deployments |
| Embed FlowX screens in your app, trigger processes from your own code, or react to FlowX events | [Consuming FlowX from external apps](./consuming-flowx-from-external-apps) | All deployments |
| Connect a legacy system, an RPA tool, or a custom file exchange that needs logic you write yourself | [Custom Kafka connector](#how-do-custom-kafka-connectors-work) | Self-hosted only |

***

## What can Integration Designer connect to?

In Integration Designer, a data source holds the connection to one external system. Integration workflows call its endpoints or operations, and a process runs a workflow through the [Start integration workflow action](../../building-blocks/actions/start-integration-workflow). For the full walkthrough, see the [Integration Designer](./integration-designer) guide.

### APIs and web services

> [card] [RESTful System](./data-sources-and-endpoints#restful-system)
>
> Connect to external REST APIs and configure endpoints, authentication, and parameters

> [card] [SOAP System](./soap-system)
>
> Import a WSDL and invoke the discovered operations from workflows (SaaS · 5.10)

### Databases

> [card] [FlowX Database](./flowx-database)
>
> Store and share structured data across processes and apps, with no external database to manage

> [card] [Unmanaged MongoDB](./unmanaged-mongodb)
>
> Connect to MongoDB instances your organization already manages

> [card] [Oracle Database](./oracle-database)
>
> Run saved SQL queries against an Oracle database you manage

> [card] [PostgreSQL Database](./postgresql-database)
>
> Run saved SQL queries against a PostgreSQL database you manage (SaaS · 5.10)

> [card] [Db2 Database](./db2-database)
>
> Run saved SQL queries against an IBM Db2 database you manage (SaaS · 5.12)

### Email and inbound events

> [card] [Email Trigger](./email-trigger)
>
> Start process instances when emails arrive in a mailbox monitored over IMAP

> [card] [Email Sender](./email-sender)
>
> Send new emails and replies to received emails from processes over SMTP

> [card] [Microsoft Outlook](./microsoft-outlook-data-source)
>
> Read and send Outlook emails through the Microsoft Graph API (5.9.1 and later)

> [card] [Incoming Webhook](./incoming-webhooks)
>
> Start or resume a process from an external HTTP POST secured with an API key

### Files

> [card] [File Storage](./file-storage)
>
> Move files in and out of external FTP, SFTP, S3, or Azure Blob storage

### AI tools and context

> [card] [MCP Integration](./mcp-integration/mcp-integration-overview)
>
> Connect Model Context Protocol (MCP) servers so AI agents can use external tools

> [card] [Knowledge Base](./knowledge-base-integration/knowledge-base-overview)
>
> Give AI agents contextual information from documents and data feeds

### Other Integration Designer topics

| Topic | Use it to |
| - | - |
| [Workflow data model](./workflow-data-models) | Define a workflow's input and output parameters |
| [Custom Agent node](./custom-agent-node) | Run an AI agent with MCP tools inside a workflow |
| [Proxy connections](./proxy-connections) | Route data source traffic through an HTTP or HTTPS proxy |
| [Testing data sources from Runtime](./testing-data-sources) | Run database operations against a deployed build without starting a workflow |
| [Finding identifiers and parameters](./finding-identifiers-and-parameters) | Locate the IDs and parameters needed for API calls and Kafka messages |

***

## How do custom Kafka connectors work?

> [!NOTE]
>
> Custom connectors are a **self-hosted** capability. On FlowX.AI SaaS, the Kafka cluster is internal to the platform and a connector you run cannot reach it. On SaaS, use an Integration Designer data source or an [Incoming Webhook](./incoming-webhooks) instead.

A connector is a microservice you build and deploy, in any technology that can send and receive Kafka messages. The process engine sends a message to the connector, the connector talks to the external system, and it replies on a Kafka topic the engine listens on. The process waits at a receive message node until the reply arrives.

![The FlowX Engine's Kafka producer sends a message from a process task through Kafka to the connector's Kafka consumer. The connector translates the data, calls the external system over REST, SOAP, or another protocol, and its Kafka producer sends the reply back through Kafka to the engine's Kafka consumer.](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/intgr_final.png)

**1. Build the connector**

Develop a microservice that listens for Kafka events, processes the received data, calls the external system, and sends the result back to Kafka. For a Java starting point, use the [quickstart connector](https://github.com/flowx-ai/quickstart-connector) repository.

**2. Send data from the process**

In the [process definition](../../building-blocks/process/process-definition), add a [message send task](../../building-blocks/node/message-send-received-task-node) with an action that sends the required data to the connector's input topic.

**3. Receive the reply**

Add a receive message task where the process waits for the connector's response. The connector must reply on a topic that matches the topic pattern the engine listens on.

> [!WARNING]
>
> The engine does not consume replies from arbitrary topic names. Before you name the reply topic, read the topic pattern rules and topic provisioning notes in [Building a connector](./building-a-connector#connector-configuration-sample).

For the full guide, including Kafka consumer and producer examples, see [Building a connector](./building-a-connector), [Creating a Kafka consumer](./creating-a-kafka-consumer), and [Creating a Kafka producer](./creating-a-kafka-producer).

***

## How do I test and monitor integrations?

> [card] [Mock integrations](./mock-integrations)
>
> Test a process flow before every integration is finished, using the mock integrations server

> [card] [Observability with OpenTelemetry](./open-telemetry)
>
> Trace, measure, and log integration calls across the platform

***

## Related resources

> [card] [Integration Designer](./integration-designer)
>
> Data sources, endpoints, and integration workflows in full

> [card] [Consuming FlowX from external apps](./consuming-flowx-from-external-apps)
>
> SDKs, REST, webhooks, and Kafka patterns for calling FlowX

> [card] [Start integration workflow action](../../building-blocks/actions/start-integration-workflow)
>
> Run an integration workflow from a process node

> [card] [Building a connector](./building-a-connector)
>
> Build and deploy a custom Kafka connector


# Knowledge Base integration
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview

Learn how to create and manage FlowX Knowledge Bases to provide AI agents with contextual information from static documents and dynamic data feeds.

## Overview

The FlowX Knowledge Base integration enables you to ingest static documents into contextual Knowledge Bases that AI agents can query when preparing responses. This integration provides a centralized repository for information that can be semantically searched and retrieved by AI agents during workflow execution.

> [!NOTE]
>
> Knowledge Bases use vector embeddings and semantic search to find the most relevant information for AI agent queries.

## Key features

* **Centralized content management**: Upload documents into organized Knowledge Bases
* **Multiple stores**: Manage content by splitting it across different stores for better organization
* **Semantic search**: AI agents can find relevant information using natural language queries
* **Multiple search modes**: Choose between hybrid, semantic, or keyword search algorithms
* **Testing capabilities**: Test queries and operations in isolation before adding them to workflows
* **Content versioning**: Append, replace, or delete stores with full traceability
* **Relevance scoring**: Understand which content chunks are most relevant for agent responses
* **Audit trail**: Track all store operations with user and timestamp information
* **Version tracking**: Knowledge Base entries are tied to app versions for consistency

## How it works

```mermaid theme={"dark"}
graph LR
    A[Upload Documents] -->|Ingest| B[Knowledge Base]
    B -->|Chunk & Index| D[Vector Database]
    E[Custom Agent Node] -->|Query| D
    D -->|Return Chunks| E
    E -->|Generate Response| F[AI Service]
```

### High-level workflow

1. **Create Knowledge Base**: Add a new Knowledge Base data source in Integration Designer
2. **Ingest content**: Upload documents into stores
3. **Automatic chunking**: Content is automatically split into chunks and indexed for semantic search
4. **Query in workflows**: AI agents query the Knowledge Base to find relevant information
5. **Monitor usage**: Track which chunks are used and their relevance scores in console logs

## Main capabilities

### Content ingestion

> [card] Manual upload
>
> Upload PDF documents directly from the Knowledge Base admin interface

### Content management

**1. Organize by stores**

Manage content by organizing it into separate stores for better control and traceability

**2. Append or replace**

Update existing stores by appending new information or replacing it entirely

**3. Delete when needed**

Remove stores and all associated chunks when they're no longer needed

### AI agent integration

AI agents can use Knowledge Bases with the ReAct (Reasoning and Acting) model to:

* Find relevant information based on user queries
* Understand which stores provided the information
* See relevance scores for retrieved chunks
* Make informed decisions based on contextual knowledge

## Stores

Stores represent individual collections of information within a Knowledge Base. Each store can be:

* **Manual**: Files uploaded through the Knowledge Base admin interface
* **Workflow**: Content ingestion through workflow operations. The Update Knowledge Base node accepts a file path, so workflows can ingest content uploaded earlier in the run (5.8.0+)

![Knowledge Base Stores](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_stores.png)

### Store lifecycle

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> New: Create
    New --> Processing: Upload/Ingest
    Processing --> Ready: Complete
    Processing --> Failed: Error
    Ready --> Processing: Update
    Ready --> Failed: Partial failure
    Ready --> MarkedForRemoval: Delete
    Failed --> Processing: Retry
    MarkedForRemoval --> [*]
```

Stores progress through the following states:

| State | Description |
| - | - |
| **New** | Store created, awaiting content |
| **Processing** | Content is being uploaded, chunked, and indexed |
| **Ready** | Content is fully processed and available for queries |
| **Failed** | Processing encountered an error, or content is partially degraded |
| **Deleting** | Store is scheduled for deletion |

### Audit trail

All store operations are tracked in the audit trail with full traceability:

| Field | Description |
| - | - |
| **Operation type** | `ADD_CONTENT_SOURCE`, `REPLACE_CONTENT_SOURCE`, `DELETE_CONTENT_SOURCE`, `ADD_CONTENT`, `REMOVE_CONTENT` |
| **Triggered by** | How the operation was initiated: Manual, API, Workflow, or Test |
| **User** | The user who performed the operation (for manual operations) |
| **Status** | Final operation state: Completed or Failed |
| **Timestamp** | When the operation occurred |

> [!TIP]
>
> Use the audit trail to track who made changes to Knowledge Base content and when, which is useful for compliance and troubleshooting.

## Error handling and retry

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When Knowledge Base ingestion fails, the Knowledge Base page shows a clear **failure status and reason**, and a **Retry** button re-runs the last operation after cleaning up any partial content, so the store is not left inconsistent. For the store-side recovery flow, see [Managing content](./managing-content#error-handling).

In workflows, the **Update Knowledge Base** node gains a **FAIL** exit handle with **per-operation rollback**: when an update fails, the node routes to the FAIL branch and rolls back the failed operation instead of leaving partial content behind, so you can handle the error explicitly in the flow.

## Search modes

Knowledge Bases support three search algorithms that determine how queries are matched against stored content:

| Search Mode | Description | Best For |
| - | - | - |
| **Hybrid** | Combines semantic and keyword search for balanced results | General-purpose queries where both meaning and exact terms matter |
| **Semantic** | Uses vector embeddings to match by meaning, not exact words | Natural language questions, conceptual queries |
| **Keywords** | Term-based matching that also finds closely related words, not just exact terms | Precise lookups, technical terms, codes, identifiers |

> [!TIP]
>
> Start with **Hybrid** search mode for most use cases. Switch to Semantic for conversational queries or Keywords for exact term lookups.

***

## Chunks and search

Chunks are small snippets of content that are indexed in the vector database for semantic search. When an AI agent queries a Knowledge Base, the most relevant chunks are returned based on:

* **Content similarity**: Semantic meaning of the query vs. chunk content
* **Relevance score**: Percentage indicating how relevant the chunk is (0-100%)
* **Metadata filters**: Optional filters built from typed operators and AND/OR logic — see [Filtering by metadata](./managing-content#filtering-by-metadata)

> [!TIP]
>
> You can test different query parameters to see which chunks are returned and their relevance scores before using the Knowledge Base in production workflows.

## Use cases

### Product documentation assistant

Create a Knowledge Base with product documentation and allow AI agents to answer customer questions based on the latest documentation.

### Policy compliance

Upload company policies and compliance documents. AI agents can reference these when processing requests to ensure compliance.

### Dynamic knowledge updates

Upload updated documents to Knowledge Bases to keep AI agent knowledge current. Content can be managed manually through the admin interface or programmatically through workflows and APIs.

### Multi-source information synthesis

Organize information across multiple stores and let AI agents synthesize information from different sources to provide comprehensive answers.

## Limitations

> [!WARNING]
>
> **Current limitations:**
>
> * Before 5.9.2, a Custom Agent node uses only one Knowledge Base. Starting with 5.9.2, it can use several, each as its own retrieval tool&#x20;
> * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
> * Store renaming is not available
> * There is no bulk operation to clear all content from a Knowledge Base: content is deleted per store. See [Emptying a knowledge base](./managing-content#emptying-a-knowledge-base)
> * Deleting the Knowledge Base data source does not remove already-ingested content: delete all of its stores first, then delete the data source

***

## Creating a knowledge base

### Prerequisites

Before you begin, ensure you have:

* Access to FlowX Designer with appropriate permissions
* A project where you want to add the Knowledge Base
* Content ready to ingest (PDF documents or JSON data)

### Setup steps

To add a new Knowledge Base data source:

**1. Navigate to Integration Designer**

Go to **FlowX Designer** → **Workspaces** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources**

**2. Create new data source**

Click **Add New Data Source** and select **FlowX Knowledge Base** as the data source type

**3. Configure basic settings**

Fill in the required fields with the following information

![Add Knowledge Base](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/add_kb.png)

### Configuration fields

#### Name

The unique identifier for your Knowledge Base within the project.

**Name** `string` *required*

**Validation rules:**

* **Required**: Field cannot be empty
* **Uniqueness**: Must be unique within the project
* **Special characters**: Only letters, numbers, and the following characters are allowed: `[]`, `()`, `.`, `_`, `-`
* **Length**: Minimum 3 characters, maximum 50 characters

#### Description

An optional description explaining the purpose and contents of the Knowledge Base.

**Description** `string`

Provide additional context about what information this Knowledge Base contains and how it should be used.

#### Containing personal information

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Turn on **Containing Personal Information** when the Knowledge Base will hold personal data and you need its content to stay on-box. When the toggle is on, FlowX indexes the Knowledge Base with a **local embedding model** instead of the cloud default, so the content is never sent to an external embedding provider.

**Containing Personal Information** `toggle`

Enables a local embedding model so that personal information from the Knowledge Base stays on-box. **Default:** OFF.

When on, an **Embedding model** dropdown appears listing the enabled embedding models from your local AI providers. If none are configured, the dropdown shows *"No local embedding models are available. Configure one in the organization AI settings."*

> [!NOTE]
>
> Local embedding models are configured once, at the organization level, as a **CUSTOM** AI provider that points at any OpenAI-compatible on-box endpoint (for example, a self-hosted text-embeddings server). The provider stores a free-form base URL and needs no API key.

> [!WARNING]
>
> The embedding model is set before the first store and can no longer be changed. Choose it before you ingest any content: once the first store is built, the model is locked for the life of the Knowledge Base. To use a different model, create a new Knowledge Base. On SaaS from FlowX.AI 6.0, you can turn **Containing Personal Information** on or off later and the content is re-embedded: see [Can I change personal information after content is ingested?](#can-i-change-personal-information-after-content-is-ingested)

When the toggle is **off**, the Knowledge Base uses the organization default embedding model and no model selector is shown.

#### Can I change personal information after content is ingested?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Yes. When you turn **Containing Personal Information** on or off for a Knowledge Base that already holds content, FlowX.AI re-embeds all of it with the new model:

* **Turning it on**: select a local **Embedding model** in the confirmation window. **Turn on** stays unavailable until you do.
* **Turning it off**: the content is re-embedded with the organization's default embedding model.

**1. Change the toggle**

In the **Settings** tab, change **Containing Personal Information**. The **Turn on personal information?** or **Turn off personal information?** window opens.

**2. Confirm**

Click **Turn on** or **Turn off**. FlowX.AI shows **Re-embedding started**, and the Knowledge Base header shows **Re-embedding content…** until it finishes. How long it takes depends on how much content the Knowledge Base holds.

While re-embedding runs:

* Search and retrieval keep using the current embedding, so workflows that use the Knowledge Base need no change.
* The **Containing Personal Information** toggle is locked.
* Content changes are refused with the message `An embedding migration is running for this knowledge base. Content operations are locked until it finishes.`
* An **Update Knowledge Base** node that targets the Knowledge Base fails without retrying.

If re-embedding fails, the Knowledge Base stays on its previous embedding model and is still fully searchable. The header shows how many documents weren't re-embedded, for example `3 of 120 documents were not re-embedded`. Change the setting again to retry.

On a Knowledge Base with no content yet, the change applies at once and FlowX.AI shows **Embedding settings updated**.

### Example configuration

Here's an example of a well-configured Knowledge Base:

```yaml theme={"dark"}
Name: Product Documentation KB
Description: Contains all product documentation, user guides, and FAQ documents for the customer support AI agent
```

### After creation

Once you've created a Knowledge Base, you'll see three tabs:

> [card] Stores
>
> View and manage all stores ingested into the Knowledge Base

> [card] Chunks
>
> Search and view the individual chunks created from your content

> [card] Metadata
>
> Define custom metadata keys used to filter and scope retrieval

![Knowledge Base Dashboard](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kb_dashboard.png)

#### Settings tab

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Settings** tab holds the **Embedding** section for the Knowledge Base:

* The **Containing Personal Information** toggle and, when it is on, the **Embedding model** selector.
* The active embedding model, shown in the Knowledge Base header tooltip as *"Embedding model: \<model>"*.
* **Dimensions** and **distance metric**, which the platform derives from the model when the first store is built. These are read-only.

***

## Next steps

> [card] [Managing Content](./managing-content)
>
> Upload documents and manage stores

> [card] [Using in Workflows](./using-knowledge-base-in-workflows)
>
> Query Knowledge Bases from workflows

> [card] [Testing Operations](./testing-knowledge-base)
>
> Test queries and operations before production use

## Related resources

> [card] [Integration Designer](../integration-designer)
>
> Integration Designer and data sources

> [card] [Custom Agent Nodes](../custom-agent-node)
>
> Using AI agents in workflows

> [card] [Integrations Overview](../integrations-overview)
>
> Integration ecosystem overview


# Managing stores
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content

Learn how to upload documents, manage stores, and work with chunks in FlowX Knowledge Bases.

## Overview

Stores are the building blocks of a Knowledge Base. Each store represents a collection of related information that has been ingested, processed, and indexed for semantic search.

## Store types

There are two types of stores:

> [card] Manual
>
> Files uploaded directly through the Knowledge Base admin interface

> [card] Workflow
>
> Content added from a workflow through the **Update Knowledge Base** node: a file path or a pasted payload

## Viewing stores

Navigate to your Knowledge Base to see all stores. The **Stores** tab displays:

![Stores List](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_stores.png)

### Store information

Each row shows:

**Type** `string`

* **Manual**: Files uploaded in the Knowledge Base page
* **Workflow**: Content added from a workflow through the **Update Knowledge Base** node
* **Test Operation**: Content created from the **Test Knowledge Base** modal

**Store** `string`

The unique name of the store within the Knowledge Base

**Status** `string`

Current processing state:

* **New**: Store created, awaiting content upload
* **Processing**: Content is being uploaded, chunked, and indexed
* **Ready**: Content is fully processed and available for queries
* **Failed**: An error occurred during processing, or content is partially degraded

Status badges update in real-time — you don't need to refresh the page to see status changes.

**Updated by** `string`

* **Username**: For files uploaded in the Knowledge Base page
* **Workflow name**: For content ingested through workflows

**Updated at** `timestamp`

Timestamp of the last upload or workflow operation execution

## Uploading documents

**1. Navigate to Knowledge Base**

Open your Knowledge Base in FlowX Designer and select the **Stores** tab.

**2. Open the upload dialog**

Click the **+** button in the top-right of the Stores tab. A file picker opens.

**3. Select file**

Choose a PDF file from your computer and click **Open**. The **Upload Store** modal appears.

**4. Set the store name**

The **Name** field is pre-filled with the file name (without extension). Edit it if needed — the name must be unique within the Knowledge Base.

**5. Review metadata (optional)**

The **Metadata** section shows the metadata schema defined for this Knowledge Base. If no metadata is defined, a "No metadata defined" placeholder appears — click **Go to Metadata Setup** to configure a schema on the **Metadata** tab before uploading. See [User-defined metadata](#user-defined-metadata) for details.

**6. Upload**

Click **Upload** to start the ingestion process. The store appears in the list with status **Processing**, and transitions to **Ready** once chunking and indexing complete.

![Upload Store modal with Name field and Metadata section](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/upload-store.png)

### File requirements

> [!WARNING]
>
> **Supported formats:**
>
> * PDF files
>
> **File size:**
>
> * Maximum file size: 20 MB (can be changed using environment variables)
>
> **Future releases will support:**
>
> * Images
> * PowerPoint presentations
> * Excel spreadsheets

#### Word document support

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Word documents (`.docx`) can also be uploaded as stores, and are chunked and indexed the same way as PDFs. This applies to store uploads in the Designer; the **Test Knowledge Base** modal accepts PDF only — see [Testing the Knowledge Base](./testing-knowledge-base).

> [!NOTE]
>
> Each store operation takes **one** document or **one** payload. There is no multi-file selector and no folder-based ingestion, in the upload dialog or on the **Update Knowledge Base** node.
>
> To load a set of documents in one pass, see [Ingesting many documents](#ingesting-many-documents).

### Store naming

When uploading a document, you must provide a unique store name:

> [!TIP]
>
> **Store name rules:**
>
> * Must be unique within the Knowledge Base
> * Default name is the file name without extension
> * Choose descriptive names for easy identification
> * Consider using versioning in names (e.g., "Product Guide v2.1")

### Duplicate stores

If you select a file with the same name as an existing store, you'll see a warning:

```
A Store with this name already exists. We recommend updating the existing store instead.
```

**Available options:**

* **Append Content**: Add the new document's content to the existing store
* **Replace Content**: Replace the existing content with the new document
* **Cancel**: Choose a different name or file

## Adding content from a payload

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Besides uploading a file, you can add content to a store by pasting a **payload** — free text, Markdown, or JSON — directly into a code editor. This is useful for seeding or updating a store quickly without producing a file, for example pasting a documentation snippet, a block of guidelines, or a JSON blob.

The store add flow has a **Source** toggle:

* **Document** (default) — upload a file, as described in [Uploading documents](#uploading-documents).
* **Payload** — paste content into the editor.

Payload works for all three content operations — **create**, **append**, and **replace** — and is available both in the Knowledge Base admin (design time) and in the **Data Sources Content** view of a running app.

**1. Switch Source to Payload**

In the store's add or update flow, set the **Source** toggle to **Payload**.

**2. Paste the content**

Enter text, Markdown, or JSON. JSON is not validated — content is accepted as-is.

**3. Name the store (create only)**

When creating a store, type a unique name. Append and replace derive the entry name automatically.

**4. Submit**

Content is processed and indexed asynchronously — the store shows **Processing** until **Ready**. Replacing a populated store asks for confirmation first, since it deletes existing content.

> [!NOTE]
>
> A payload is stored as plain text — wrapped into a text file and chunked like a document. JSON is kept as an opaque text blob, so it is not stored or queried field by field.

The store's History distinguishes how each operation was performed — for example **Append Content - Payload** vs **Append Content - Document**.

## Managing stores

Once content is uploaded and processed, you can perform the following operations:

![Manage Stores](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/content_ops.png)

### Append content

Add new content to an existing store without removing the existing chunks.

**1. Select store**

Click on the store you want to update

**2. Choose Append Content**

Select the **Append Content** operation

**3. Upload new file**

Select a new PDF file with additional content

**4. Confirm**

The new content will be processed and added to the existing chunks

**Use case:** Adding a new chapter to existing documentation or supplementing information without losing the original content.

### Replace content

Replace all existing content in a store with new content.

**1. Select store**

Click on the store you want to replace

**2. Choose Replace Content**

Select the **Replace Content** operation

**3. Upload new file**

Select a new PDF file that will replace the existing content

**4. Confirm**

All existing chunks will be deleted and new chunks will be created from the new content

> [!WARNING]
>
> **Replace Content** will permanently delete all existing chunks from the store. This operation cannot be undone.

**Use case:** Updating documentation to a new version where the old content is no longer relevant.

### Delete store

Remove a store and all its associated chunks from the Knowledge Base.

**1. Select store**

Click on the store you want to delete

**2. Choose Delete**

Select the **Delete Store** operation

**3. Confirm deletion**

Confirm that you want to permanently delete the store

> [!WARNING]
>
> Deleting a store will:
>
> * Remove all chunks generated from that content
> * Remove the store's embeddings from the vector database (removal is asynchronous and may take a few moments to complete)
> * Permanently delete the content from the Knowledge Base
> * This operation cannot be undone

### Delete entries

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Remove individual chunks and entries from a store by matching their metadata, without deleting the whole store. This is a workflow-driven operation on the **Update Knowledge Base** node, useful when you need to retire a subset of content (for example, entries for a region or a document version) while keeping the rest of the store intact.

**1. Add an Update Knowledge Base node**

In your workflow, add an **Update Knowledge Base** node and select the target Knowledge Base and store.

**2. Choose Delete entries**

Set the operation to **Delete entries**.

**3. Build the metadata filter**

Define a metadata filter that matches the entries you want to remove. The filter uses the same query builder as chunk search (field / operator / value, grouped with **AND** / **OR**). See [Filtering by metadata](#filtering-by-metadata) for the operator list.

**4. Confirm**

Matching entries and their chunks are soft-deleted from the store. Removal from the vector database is asynchronous and may take a few moments to complete.

> [!WARNING]
>
> A **Delete entries** operation requires a non-empty metadata filter. An empty or match-all filter is rejected, so a mis-configured node cannot wipe an entire store or Knowledge Base by accident.

**Use case:** Removing entries for a specific document version, region, or department while keeping the rest of the store's content available for retrieval.

### How do I disable, re-activate, or permanently delete an entry?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Open the menu on an entry in a store to manage it from FlowX Designer:

* **Disable Entry**: takes a ready entry out of retrieval while keeping it in the store. The entry card shows a **Disabled** tag, and the store list shows how many entries are disabled. Entries removed by a **Delete entries** operation show as disabled too.
* **Activate Entry**: puts a disabled entry back into retrieval.
* **Permanent delete**: removes the entry, its indexed content, and its source document. FlowX Designer asks you to confirm with **Delete**, and the action can't be undone. It isn't available while the entry is still being indexed.

Disable and activate apply in one click, without a confirmation, because each reverses the other. The actions you see depend on your access rights on the Knowledge Base.

### Update Knowledge Base node failure handling

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When an **Update Knowledge Base** operation fails during a workflow run, the platform rolls back any partial changes and routes the node to its **FAIL** branch with a structured error payload. Nothing is left half-applied: the store returns to the state it was in before the operation started.

The error payload is available on the FAIL branch (in `paramValues`) and in the workflow run console. It carries the following keys:

| Key | Description |
| - | - |
| `error` | Human-readable message: "The operation \[\<operation>] on store \[\<store>] failed. Any partial changes were reversed." |
| `operation` | The operation that failed: `APPEND`, `REPLACE`, `DELETE`, or `DELETE_ENTRIES` |
| `storeName` | The name of the store the operation targeted |
| `errorReason` | A machine-readable reason (see table below) |
| `chunksRolledBack` | The number of chunks reverted by the rollback |

Use `errorReason` to branch your workflow's error handling:

| `errorReason` | Meaning | Automatically retried |
| - | - | - |
| `size_exceeded` | The content exceeded the allowed size | No |
| `extraction_failed` | Text could not be extracted from the document | Yes |
| `chunking_failed` | The content could not be chunked or embedded | Yes |
| `timeout` | The operation did not complete in time | No |
| `unknown` | The cause could not be determined | Yes |

When an operation is automatically retried, the console shows a retry notification with the original error and a "Retrying \[\<operation>] on store \[\<store>]." message.

> [!NOTE]
>
> Retryable reasons (`extraction_failed`, `chunking_failed`, `unknown`) are retried automatically before the node fails. Non-retryable reasons (`size_exceeded`, `timeout`) route to the FAIL branch immediately.

### Ingesting many documents

Each **Update Knowledge Base** execution ingests a single document or payload, so loading a set of documents means running the node once per file. Collect the files first, then fan out.

**1. Collect the files in one action**

Add a [Multiple File Upload](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload) component to the screen where the documents are submitted. It uploads the whole selection in a single request and writes the per-file results back as a list.

**2. Fan out over the list**

Add a [Call Activity](/5.9/docs/building-blocks/node/call-subprocess-tasks/call-activity-node) node in **parallel multi-instance** mode and set that list as its **input array**. One subprocess instance starts per element.

The input array must be an **array of objects** — the per-file result list qualifies, a plain list of path strings does not, and only arrays of objects appear in the **Input Array** picker. Map the fields you need into the subprocess in the node's **Data Mapping** section: a child that receives no mapping knows only its position in the collection, not which file it is handling.

**3. Ingest one file per instance**

In the subprocess, call the workflow that holds the **Update Knowledge Base** node and pass it the single file path from `item`. Use **Append Content** so every instance adds to the same store.

> [!TIP]
>
> If the documents already sit in object storage, you can skip the upload step: set the node's **File Source** to **S3 Protocol** and drive the same fan-out from your own list. Build it as an array of objects, one per file carrying its path, so the Call Activity can bind it as an input array.

> [!WARNING]
>
> A wide fan-out issues many concurrent append operations against one store. Start with a small set to confirm the mapping before scaling up, and handle per-instance errors on the node's [FAIL branch](#update-knowledge-base-node-failure-handling) — a subprocess that ends any way other than reaching an end node never reports back to its parent.

### Emptying a knowledge base

Stores are the unit of deletion: there is no bulk operation that clears all content from a Knowledge Base at once. To empty a Knowledge Base while keeping it available for re-ingestion, delete each of its stores individually. You can automate this from a workflow with the **Update Knowledge Base** node using the **Delete** operation.

> [!WARNING]
>
> Deleting the Knowledge Base data source itself does not remove content that was already ingested. To remove a Knowledge Base completely, delete all of its stores first, then delete the data source.

### Stores and version export

Store contents stay on the workspace where they were ingested. A project version export carries the Knowledge Base data-source **definition** (system, endpoints, metadata keys), but not the stores' documents or their indexed embeddings. After importing the version on another workspace or environment, the Knowledge Base appears with empty stores — upload the content again there to rebuild the index. See [Export/import a project](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition) for the full export behavior.

## Store states

Stores progress through different states during their lifecycle. Status badges update in real-time — you don't need to refresh the page to see transitions.

### New

The initial state after content is uploaded to the Knowledge Base.

**What's happening:**

* File has been transferred to the FlowX platform
* Content is being validated and queued for processing

**Duration:** Usually a few seconds, depending on file size

### Processing

Content is being chunked, embedded, and indexed in the vector database.

**What's happening:**

* Content is being extracted from the document
* Text is being split into semantically meaningful chunks
* Chunks are being embedded and indexed in the vector database

**Duration:** Can take from seconds to minutes depending on content size

### Ready

Store is fully processed and available for queries.

**What you can do:**

* Query the store in AI agents
* View individual chunks
* Append or replace content
* Delete the store

### Failed

An error occurred during processing, or the store is partially degraded.

**What to do:**

1. Check the error message in the Store History modal
2. Verify the file format and content
3. Retry the operation

![Failed State](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/console_history.png)

## Error handling

When processing fails, the store will show a warning indicator.

### Error states and recovery

> [accordion] Upload failed
>
> **Cause:** File upload was interrupted or the file format is invalid
>
> **Solution:**
>
> * Verify the file format is supported — see [File requirements](#file-requirements)
> * Check your network connection
> * Try uploading again

> [accordion] Chunking failed
>
> **Cause:** Error occurred while processing the content
>
> **Solution:**
>
> * Check the Store History for specific error details
> * Verify the file is not corrupted
> * Contact support if the issue persists

> [accordion] Retry behavior
>
> When retrying a failed operation:
>
> * Any chunks already created will be deleted
> * The content will be processed entirely from the beginning
> * No duplicate chunks will be created

### Warning indicators

When a store has a failed update:

* **Yellow warning icon** appears on the store row
* **Tooltip message**: "Last Store update failed. Check history."
* **Dismiss trigger**: The warning is automatically dismissed after a successful update

## Viewing store history

Store History lists every operation performed on a store. Open it from the store's actions menu with **View History**.

| Operation | Description |
| - | - |
| Create KB Store | Creates the store and inserts content |
| Append Content | Adds new content to existing chunks |
| Replace Content | Deletes existing content and inserts new content |
| Delete KB Store | Removes the store and all chunks |
| Update Content Metadata | Changes an entry's metadata values |

Each history entry includes:

* Timestamp
* User
* Type (Manual/Workflow/Test Operation)
* Operation performed
* Updated By (user or workflow name)
* Operation Status

## Working with chunks

Chunks are the individual pieces of content that AI agents query. To view and test chunks:

**1. Navigate to Chunks tab**

Click the **Chunks** tab in your Knowledge Base

**2. Search chunks**

Enter a query to search for relevant chunks

**3. Filter results**

Apply filters to refine the search results

**4. Review chunks**

Examine the returned chunks, their relevance scores, and metadata

![Chunks](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_chunks.png)

### Chunk information

Each chunk displays:

**Relevance Score** `percentage`

How relevant the chunk is to your query (0-100%)

**Store** `string`

The store that generated this chunk (clickable link)

**Submitted Content** `link`

Link to the original document or JSON payload that created this chunk

**Chunk Content** `text`

The actual text content of the chunk

**Chunk Metadata** `object`

System metadata associated with the chunk:

* `source`: manual\_upload or from\_workflow
* `path`: Document filepath or JSON payload
* `chunk_id`: UUID from the vector database
* `knowledge_base`: Knowledge Base ID

User-defined metadata keys (if configured) are also included.

### User-defined metadata

You can define custom metadata keys on a Knowledge Base and assign values to stores. User-defined metadata enables filtering and scoping when searching chunks — for example, filtering by department, document version, or region.

#### Defining metadata keys

Metadata keys are managed on the **Metadata** tab of the Knowledge Base data source.

![Metadata tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_metadata.png)

To add a key, click **Add Metadata Key** and fill in the following fields:

| Field | Description |
| - | - |
| **Name** | Unique key name. Cannot be changed after creation. |
| **Type** | Data type: `String`, `Number`, `Boolean`, `Enum`, or `Date`. Cannot be changed after creation. |
| **Enum values** | Allowed values (only visible when **Type** is `Enum`). Values defined at creation cannot be removed. |
| **Description** | Optional free-text description of the key's purpose. |

> [!TIP]
>
> Name and type are locked after a key is saved. Only description and enum values (additions only) can be updated later.

#### Assigning metadata values

When uploading or appending a store (manually or through the **Update Knowledge Base** workflow node), a **Metadata** section appears in the upload modal listing all defined keys for the Knowledge Base. Assign a value to each relevant key before uploading. The values are stored alongside the content and propagated to the vector database.

#### Filtering by metadata

When searching chunks (in the **Chunks** tab or through the Context Retrieval workflow node), you can add metadata filters using the query builder. System metadata keys are always available as filter options alongside any user-defined keys.

> [!NOTE]
>
> The metadata filter UI is a full query builder with typed operators, AND/OR logic, and grouping.

##### System metadata keys

System metadata keys are reserved names populated automatically by the platform. They are listed in the filter picker with human-readable labels and can be combined with user-defined keys.

| Key | Type | Scope | Description |
| - | - | - | - |
| `source` | Enum | Entry | How the entry was added: `manual_upload`, `from_workflow`, `test_operation` |
| `uploaded` | Date | Entry | UTC timestamp set when the entry was added to the Knowledge Base |
| `docName` | String | Entry | File name of the uploaded document |
| `docType` | Enum | Entry | Document type derived from the file extension, lower-cased (starter values include `pdf`, `xlsx`, `docx`, `txt`) |
| `docPages` | Number | Entry | Total page count, reported once document parsing completes (a re-index refreshes the value) |
| `storeOrigin` | String | Entry | Name of the store the entry was added to |
| `chunkCounter` | Number | Chunk | Sequential position of the chunk within its source document |
| `chunkType` | Enum | Chunk | Structural element the chunk was extracted from (starter values include `table`, `header`, `section_header`, `picture`, `paragraph`) |
| `chunkSection` | String | Chunk | Document section heading the chunk belongs to |
| `chunkPageStart` | Number | Chunk | Page number where the chunk starts in the source document |
| `chunkEntry` | String | Chunk | Document name of the entry the chunk belongs to (equivalent to `docName`) |

> [!NOTE]
>
> If a user-defined metadata key collides with a reserved system name, it is automatically renamed to `<name>_user` on upgrade. Wire-level identifiers stay plain; the filter picker shows human labels (for example, `Doc type` for `docType`).

Filters are expressed as conditions made of **field / operator / value**. Each condition uses operators appropriate to the metadata key's type:

| Type | Available operators |
| - | - |
| **String** | equals, not equals, contains, starts with, ends with, matches regex, in, not in, exists, is null |
| **Number** | equals, not equals, greater than, greater or equal, less than, less or equal, between, in, exists, is null |
| **Boolean** | is true, is false, exists |
| **Date** | equals, before, after, between, exists, is null |
| **Enum** | equals, not equals, in, not in, exists |

Conditions are organized in **groups**. Within a group, conditions can be combined with `and` or `or`. Groups themselves are also combined with `and` or `or`, which lets you express non-trivial logic such as `(region = "EU" AND tier IN ["gold", "platinum"]) OR priority >= 5`.

Use **New Filter** to add a condition and **New Group** to add a nested group.

### Searching chunks

Use the **Chunks** tab to test how chunks will be retrieved by AI agents:

**Store** `string`

Filter by a specific store. Default: all stores

**Query Prompt** `string`

Enter a natural language question or search query

**Search Type** `select`

Strategy used for retrieving context:

* **Hybrid** (default) — combines semantic and keyword search
* **Semantic** — vector similarity only
* **Keywords** — lexical match only (hides **Min. Relevance Score**)

**Max. Number of Results** `number`

Maximum number of chunks to return. Range: 1-10. Default: 4.

**Min. Relevance Score** `percentage`

Only return chunks with relevance score above this threshold. Range: 0-100%. Hidden when **Search Type** is **Keywords**.

**Use Re-rank** `boolean`

Reorders results to surface the best matches. Improves quality but takes slightly longer.

**Metadata Filters** `object`

Refine results using the query builder (see [Filtering by metadata](#filtering-by-metadata))

> [!TIP]
>
> Use chunk search to understand what information AI agents will receive for different queries. This helps you optimize your Knowledge Base content and structure.

## Best practices

### Content organization

> [!TIP]
>
> **Organize by topic or version:**
>
> * Create separate stores for different topics
> * Use versioning in store names (e.g., "User Guide v1.0", "User Guide v2.0")
> * Group related documents in the same store using Append Content

### Content updates

> [!TIP]
>
> **Choose the right operation:**
>
> * Use **Append Content** when adding supplementary information
> * Use **Replace Content** when updating to a new version
> * Test queries after updates to verify the changes work as expected

### Error prevention

> [!TIP]
>
> **Avoid common errors:**
>
> * Ensure PDF files are not corrupted before uploading
> * Use unique, descriptive names for stores
> * Monitor the status of stores during processing
> * Check Store History when errors occur

## Next steps

> [card] [Using in Workflows](./using-knowledge-base-in-workflows)
>
> Learn how to query Knowledge Bases from workflows

## Related resources

> [card] [Knowledge Base Overview](./knowledge-base-overview)
>
> Understanding Knowledge Base capabilities


# Testing a knowledge base
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/testing-knowledge-base

Test create, append, replace, delete, edit-metadata, and query operations against a knowledge base on a deployed build before running them in production.

> [!NOTE]
>
> The **Test Knowledge Base** modal lets you exercise content-management operations against a knowledge base on a deployed build, without modifying a workflow first. Use it to validate a knowledge base after deploy, to load initial content, or to investigate retrieval issues from a production knowledge base.

## Overview

Knowledge bases are populated and queried through workflows. The Test Knowledge Base modal gives you a direct, build-level UI for the same operations, so you can:

* Seed a newly created knowledge base with content immediately after deploy
* Append or replace store content without triggering a workflow run
* Spot-check what a query returns against the current knowledge base state
* Edit metadata on individual entries when a real-world correction is needed

All write actions performed from this modal are tagged with `source: manual` on the affected entries, so they remain distinguishable from workflow-driven changes.

## Opening the modal

**1. Open a deployed build**

Navigate to a project that has a knowledge base configured, and open the build where you want to test.

**2. Click the play button**

On the build, click the **play** button and select **Test Knowledge Base**.

**3. Choose the knowledge base**

In the modal header, open the knowledge base dropdown and select the knowledge base you want to act on. The dropdown lists both project knowledge bases and any knowledge bases referenced from libraries used by the build.

## Available actions

Six actions are available inside the modal. Each one is run by clicking **Test** after filling in the required fields.

### Create new store

Creates a new store in the selected knowledge base and ingests an initial document.

| Field | Description |
| - | - |
| **Store name** | Required. Must be unique within the knowledge base. |
| **Upload** | Opens the file picker, filtered to PDF. |
| **Metadata** | Same metadata inputs available when uploading from the knowledge base admin view. |

If a store with the same name already exists, the modal shows the toast error "Store name already exists." and highlights the store-name input.

### Append to a store

Adds new content to an existing store, leaving prior chunks in place.

| Field | Description |
| - | - |
| **Store name** | Required. Searchable dropdown of existing stores. |
| **Type** | Either **From document** (PDF upload) or **From payload** (JSON in the code editor). |
| **Metadata** | Metadata values applied to the appended content. |

### Replace store content

Removes the existing content of a store and replaces it with new content.

| Field | Description |
| - | - |
| **Store name** | Required. Searchable dropdown of existing stores. |
| **Type** | Either **From document** or **From payload**. |
| **Metadata** | New metadata values applied to the replacement content. |

> [!WARNING]
>
> Replace is destructive. All existing chunks in the store are removed before the new content is added.

### Delete a store

Removes a store from the knowledge base.

| Field | Description |
| - | - |
| **Store name** | Required. Searchable dropdown of existing stores. |

### Edit metadata values

Updates metadata values on individual entries inside a store.

**1. Select a store**

Pick a store from the searchable dropdown. The entries of that store appear on the right side of the modal.

**2. Select an entry**

Click the entry you want to edit. Each entry card shows both user-defined and system metadata.

**3. Edit metadata values**

Use the metadata area on the left to update values. Metadata is grouped into two categories: **configured** (keys that already have a value) and **empty** (keys that have no value yet). When you populate an empty key and save, it moves to the configured category. The empty category is hidden when no keys remain in it.

**4. Save or discard**

Save commits the changes to the selected entry. Discard clears the selection and any unsaved edits. If you try to switch entries with unsaved changes, the modal prompts you to confirm.

> [!NOTE]
>
> Metadata **values** are editable, metadata **keys** are not. Adding, removing, or renaming a metadata key from the modal is intentionally not allowed because metadata filters elsewhere in the platform depend on the key set.

### Query

Runs a retrieval against the knowledge base and shows which chunks come back.

| Field | Description |
| - | - |
| **Query** | Free-text query string. |
| **Metadata filters** | Advanced query builder over all metadata keys, including system metadata. Store-level filtering is expressed as a metadata filter. |

Use this to validate retrieval quality, debug an AI agent that is pulling unexpected chunks, or confirm that a recent ingestion is searchable.

## Reading the results

When you click **Test**, the modal header shows progress and an action-specific summary on completion.

| Action | Status header on completion |
| - | - |
| Create new store | `Created: [X] chunks` |
| Append to a store | `Appended: [X] chunks` |
| Replace store content | `Deleted: [X] chunks   Added: [Y] chunks` |
| Delete a store | `Deleted: [X] chunks` |
| Query | (no count, retrieved chunks listed below) |

The chunks pane below the header reflects the action:

* **Create / Append** — new chunks are listed with a badge. For Append, new chunks appear at the top of the list, above pre-existing ones.
* **Replace** — only the new chunks are shown, each with a badge.
* **Delete** — the chunks area is empty.
* **Query** — retrieved chunks are listed without a badge.

> [!NOTE]
>
> Only the first **10 chunks** are shown in the preview. A disclaimer is rendered above the chunks list when the result set is truncated.

## Limitations

> [!WARNING]
>
> * The preview shows at most 10 chunks per action.
> * Metadata keys cannot be added, removed, or edited from the modal — only values.
> * File uploads accept PDF only.
> * Edits made from this modal are tagged `source: manual` and remain distinguishable from workflow-driven changes.

## Related resources

> [card] [Knowledge base overview](./knowledge-base-overview)
>
> Concepts, stores, chunks, and search modes.

> [card] [Managing stores](./managing-content)
>
> Design-time UI for store management.

> [card] [Using a knowledge base in workflows](./using-knowledge-base-in-workflows)
>
> Query, append, and replace from inside a workflow.

> [card] [Custom agent nodes](../custom-agent-node)
>
> Wire a knowledge base into an AI agent.


# Using Knowledge Base in workflows
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows

Learn how to query Knowledge Bases using Custom Agent and Context Retrieval nodes in workflows.

## Overview

Knowledge Bases can be integrated into workflows to enable AI agents and Context Retrieval nodes to query them for contextual information when generating responses.

> [!NOTE]
>
> This page covers **querying** Knowledge Bases from workflows. To add, replace, or delete Knowledge Base content from a workflow, use the **Update Knowledge Base** node. See [Managing content](./managing-content) for store operations, including [ingesting many documents](./managing-content#ingesting-many-documents) in one pass.

## Choosing the right approach

There are two ways to query Knowledge Bases in workflows:

| Approach | Node | When to use |
| - | - | - |
| **Integrated RAG** | [Custom Agent](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) | You want the AI to retrieve chunks and generate a response in a single step |
| **Standalone retrieval** | [Context Retrieval](/5.9/ai-platform/agent-builder/context-retrieval) | You want raw chunks returned without LLM processing, so you can filter, transform, or route them before generation |

***

## Using knowledge bases in custom agent nodes

Custom Agent nodes can query Knowledge Bases to retrieve contextual information when generating responses.

### Configuring custom agent with knowledge base

**1. Add Custom Agent node**

Add a Custom Agent node to your workflow

**2. Configure the agent**

Set up the basic agent configuration (operation prompt, etc.)

**3. Enable Knowledge Base**

In the **Knowledge Base** section, enable the Knowledge Base feature

**4. Select Knowledge Base**

Choose a Knowledge Base from the available options

**5. Configure query parameters**

Set the query parameters for retrieving chunks

![Custom Agent with KB](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kb_can.png)

### Knowledge base query configuration

**Knowledge Base** `select` *required*

Select the Knowledge Base that the agent should query

**Max. Number of Results** `number`

Maximum number of chunks to retrieve (1-10). Default: 5

**Min. Relevance Score** `percentage`

Minimum relevance score threshold (0-100%). Only chunks above this score will be included. Default: 70%

**Metadata Filters** `object`

Refine retrieved chunks using the query builder. Click the **Metadata Filters** button to open a modal where you can compose structured filter conditions.

Each condition is a **field / operator / value** triple. Operators vary by metadata key type (equals, not equals, contains, in, not in, before, after, exists, etc.). Conditions can be grouped and combined with **AND** or **OR**.

To restrict results to a specific store, add a condition on the system metadata key `source`.

The button label shows how many filters are currently active (e.g., "3 Filters Applied" or "No Filters Applied").

> [!NOTE]
>
> The Metadata Filters modal supports typed operators, AND/OR logic, and grouping. See [Filtering by metadata](./managing-content#filtering-by-metadata) for the full operator list.

**Use advance metadata filters** `boolean`

Toggle **ON** to enable advanced metadata filter expressions for more complex filtering logic. When turned on, you can write expression-based filters instead of using the structured filter UI.

**Default:** `false`

***

## Using knowledge bases in context retrieval nodes

Context Retrieval nodes retrieve relevant data from Knowledge Bases or conversation memory using semantic, keyword, or hybrid search. Unlike Custom Agent nodes, Context Retrieval nodes are dedicated to chunk retrieval without agent reasoning -- they are available under **Data Operations** in the workflow node palette.

### Configuring context retrieval with knowledge base

**1. Add Context Retrieval node**

Add a **Context Retrieval** node from the **Data Operations** category in the workflow editor

**2. Select a source**

Choose between **Knowledge Base** or **Memory** (Memory is only available in chat-driven workflows)

**3. Select Knowledge Base**

If using Knowledge Base as the source, select a Knowledge Base from the available options

**4. Define the user query**

Enter the search query, typically a process variable expression (e.g., `${userMessage}`)

**5. Configure settings**

Expand **Settings** to configure search type, max chunks, min relevance, metadata filters, and re-ranking

### Context retrieval configuration

**Source** `select` *required*

The data source to retrieve context from.

**Options:**

* **Knowledge Base** — search a connected Knowledge Base
* **Memory** — search conversation memory (chat-driven workflows only)

**Knowledge Base** `select`

Select the Knowledge Base to query. Only visible when **Source** is set to **Knowledge Base**.

**User Query** `string` *required*

The search query used to retrieve relevant chunks. Supports process variable expressions.

**Example:** `${userMessage}`

**Search Type** `select`

The strategy used for retrieving context.

**Options:**

* **Hybrid** (default) — combines semantic and keyword search
* **Semantic** — vector-based similarity search
* **Keywords** — traditional keyword matching

**Max Number of Chunks** `number`

How many relevant chunks to return (1-10).

**Default:** `5`

**Min Relevance Score** `percentage`

The threshold a chunk must meet to be included in results (0-100%). Only visible when search type is **Hybrid** or **Semantic**.

**Default:** `70%`

**Metadata Filters** `object`

Refine results by filtering chunks based on their metadata properties. Click the button to open the query builder modal where you can compose structured filter conditions.

Each condition is a **field / operator / value** triple. Operators vary by metadata key type (equals, not equals, contains, in, not in, before, after, exists, etc.). Conditions can be grouped and combined with **AND** or **OR**.

The button label shows how many filters are currently active.

> [!NOTE]
>
> Typed operators, AND/OR logic, and grouping are supported. See [Filtering by metadata](./managing-content#filtering-by-metadata) for the full operator list.

**Use advance metadata filters** `boolean`

Toggle **ON** to enable advanced metadata filter expressions for more complex filtering logic.

**Default:** `false`

**Use Re-rank** `boolean`

Toggle **ON** to re-rank retrieved chunks before they are returned, improving result quality.

**Default:** `false`

***

### How the agent uses knowledge base

When a Custom Agent node executes with Knowledge Base enabled, the Knowledge Base is a retrieval tool the agent can call. The agent decides whether it needs it. When it does:

1. **Query generation**: The agent analyzes the user's input and generates a search query
2. **Chunk retrieval**: The Knowledge Base is queried using the node's search type
3. **Relevance filtering**: Only chunks meeting the minimum relevance score are returned
4. **Context inclusion**: Retrieved chunks are added to the agent's context
5. **Response generation**: The agent generates a response using the retrieved information

```mermaid theme={"dark"}
sequenceDiagram
    participant User
    participant Agent
    participant KB as Knowledge Base
    participant LLM
    
    User->>Agent: User query
    opt Agent decides it needs the Knowledge Base
    Agent->>KB: Search query
    KB->>Agent: Relevant chunks
    end
    Agent->>LLM: Query + chunks
    LLM->>Agent: Generated response
    Agent->>User: Response with context
```

> [!TIP]
>
> To retrieve on every run, whatever the agent decides, add a [Context Retrieval](/5.9/ai-platform/agent-builder/context-retrieval) node before the agent and pass its chunks in **Context**.&#x20;

### ReAct model with knowledge base

When using the ReAct (Reasoning and Acting) model, the agent can:

* **Reason**: Determine if Knowledge Base information is needed
* **Act**: Query the Knowledge Base as a tool
* **Iterate**: Make multiple queries if needed for comprehensive answers

**Example ReAct flow:**

```
User: "What are the new features in version 2.5?"

Agent Reasoning: I need to search the Knowledge Base for version 2.5 information

Agent Action: Query Knowledge Base with "new features version 2.5"

Knowledge Base: Returns 3 relevant chunks about version 2.5 features

Agent Reasoning: I have enough information to answer the question

Agent Response: "Version 2.5 introduces three major features..."
```

## Viewing Knowledge Base results

When a Custom Agent node queries a Knowledge Base during a workflow run, you can inspect the retrieved chunks directly in the workflow run console.

### Knowledge Base tab

A **Knowledge Base** tab appears in the node console (alongside Logs, Input, Output, and Tools) when a node has KB results. For each Knowledge Base queried, the tab displays:

| Field | Description |
| - | - |
| **Knowledge Base name** | The name of the queried KB (links to the KB data source configuration) |
| **Number of Results** | The `topK` value used for the query |
| **Min. Relevance Score** | The minimum relevance threshold (as a percentage) |
| **Chunks** | Expandable list of retrieved chunks |

Each chunk entry shows:

* **Relevance score** — how closely the chunk matches the query (percentage)
* **Store** — the name of the store the chunk belongs to
* **Chunk content** — the actual text (expandable, collapsed to 6 lines by default)
* **Submitted Content** — button to view the full chunk content in an overlay panel
* **Metadata** — any metadata associated with the chunk (if present)

- **Chunk ID**: the unique identifier of the chunk in the vector database (`chunkId`)
- **Created at**: the ingestion timestamp of the chunk (`createdAt`), which records when the chunk was indexed. Chunks indexed before this field existed show no value.

> [!TIP]
>
> Use the Knowledge Base tab to debug retrieval quality. If the agent returns inaccurate answers, check whether the retrieved chunks contain the expected information and whether relevance scores are appropriate.

KB results also appear inline in the **Logs** tab for AI nodes and are aggregated at the workflow level in the overall workflow console.

***

## Example workflows

### Dynamic documentation updates

Update product documentation whenever a new release is deployed:

```yaml theme={"dark"}
Workflow: Product Release
Nodes:
  1. Receive Release Data
  2. Knowledge Base Operation
     - KB: "Product Documentation KB"
     - Operation: "Replace Content"
     - Store: "Release Notes ${release.version}"
     - Content: "${release.documentation}"
  3. Notify Support Team
```

### Customer support with contextual AI

Use Knowledge Base in a customer support chatbot:

```yaml theme={"dark"}
Workflow: Customer Support Chat
Nodes:
  1. Receive Customer Message
  2. Custom Agent Node
     - Model: GPT-4
     - Knowledge Base: "Support Documentation KB"
     - Min. Relevance: 75%
     - Max Results: 5
  3. Send Response to Customer
```

### Multi-source knowledge ingestion

Aggregate information from multiple systems:

```yaml theme={"dark"}
Workflow: Weekly Knowledge Update
Nodes:
  1. Fetch from CRM System
  2. Append to KB
     - Store: "CRM Updates"
  3. Fetch from Documentation Site
  4. Append to KB
     - Store: "Documentation"
  5. Fetch from Support Tickets
  6. Append to KB
     - Store: "Support Insights"
```

## Error handling

### Common errors and solutions

> [accordion] Store not found
>
> **Error:** `Store "Example" does not exist in Knowledge Base "KB Name"`
>
> **Cause:** Attempting to append or replace content in a non-existent store
>
> **Solution:**
>
> * Verify the store name is correct
> * Use "Append Content" which creates the store if it doesn't exist
> * Check for typos in store names

> [accordion] Invalid JSON content
>
> **Error:** `Failed to parse JSON content`
>
> **Cause:** The content provided is not valid JSON
>
> **Solution:**
>
> * Ensure workflow variables contain valid JSON
> * Validate JSON structure before passing to Knowledge Base operation
> * Check for special characters that may break JSON formatting

> [accordion] Knowledge Base not accessible
>
> **Error:** `Knowledge Base "KB Name" not found or not accessible`
>
> **Cause:** The Knowledge Base doesn't exist or you don't have permissions
>
> **Solution:**
>
> * Verify the Knowledge Base exists in the project or dependencies
> * Check access permissions for the Knowledge Base
> * Ensure the Knowledge Base is published if using from dependencies

> [accordion] Chunking failed
>
> **Error:** `Failed to process content into chunks`
>
> **Cause:** Error occurred while creating chunks from the content
>
> **Solution:**
>
> * Check console logs for detailed error messages
> * Verify the content is in the expected format
> * Retry the operation
> * Contact support if the issue persists

## Best practices

### Agent configuration

> [!TIP]
>
> **Custom Agent with Knowledge Base:**
>
> * Start with a higher minimum relevance score (70-80%) to avoid irrelevant results
> * Adjust max results based on your use case (fewer for focused answers, more for comprehensive coverage)
> * Test different queries to understand chunk retrieval behavior
> * Monitor console logs to optimize configuration

### Relevance score management

> [!TIP]
>
> **Optimizing relevance scores:**
>
> * **Chunk size matters**: If chunks are too large and queries are small, relevance scores will be low because the query doesn't cover all the content. If you find yourself setting minimum relevance score to 0%, this may indicate your chunks are too large.
> * **Let the agent determine relevance**: Consider ordering chunks by relevance (descending) and letting the agent evaluate which chunks are relevant, rather than filtering by minimum relevance score. The agent can see if chunks are relevant and make better decisions.
> * **System prompt guidance**: If you want to manage relevance filtering, add instructions to your system prompt such as: "If you don't find any relevant information in the provided chunks, just say 'I cannot find this information'."
> * **Empty results handling**: The Knowledge Base tool returns an empty list when no results are found. Ensure your agent handles empty results gracefully and informs users when information is not available.

### Performance

> [!TIP]
>
> **Optimize performance:**
>
> * Keep stores focused and organized by topic
> * Add a metadata filter on the `source` system key when you know which store contains relevant information
> * Avoid ingesting extremely large documents without proper structuring
> * Regular cleanup of deprecated stores
> * **Consider removing max results limit**: Instead of limiting the number of chunks, order them by relevance (descending) and let the agent process all relevant chunks. This allows the agent to make better decisions about which information to use.

## Limitations

> [!WARNING]
>
> **Current limitations:**
>
> * Only one Knowledge Base per Context Retrieval node. A Custom Agent node can use several starting with 5.9.2&#x20;
> * Cannot ingest documents directly from Document Plugin
> * Structured metadata filters cover common operators and AND/OR grouping. For filtering logic that cannot be expressed in the query builder (for example, arbitrary JSON expressions), toggle **Use advance metadata filters**.

## Using Context Retrieval nodes

The **Context Retrieval** node performs a standalone RAG search against a Knowledge Base and returns raw chunks without calling an LLM. This gives you full control over how retrieved information is used in your workflow.

### When to use Context Retrieval

* You need to inspect or filter chunks before passing them to an AI node
* You want to combine results from multiple Knowledge Bases
* You need chunk metadata (relevance scores, stores) for routing decisions
* You're building a multi-step RAG pipeline with custom processing between retrieval and generation

For full configuration details, see the [Context Retrieval node documentation](/5.9/ai-platform/agent-builder/context-retrieval).

***

## Next steps

> [card] [Managing Content](./managing-content)
>
> Understand store management in detail

## Related resources

> [card] [Custom Agent Nodes](../custom-agent-node)
>
> Complete guide to Custom Agent nodes

> [card] [Context Retrieval](/5.9/ai-platform/agent-builder/context-retrieval)
>
> Standalone Knowledge Base retrieval without LLM

> [card] [Integration Designer](../integration-designer)
>
> Overview of all workflow node types including Context Retrieval

> [card] [Workflow Data Models](../workflow-data-models)
>
> Understanding workflow variables and data


# MCP Data Sources
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source

Learn how to add, configure, and manage MCP servers as data sources in Integration Designer.

## Overview

This guide covers the complete lifecycle of working with MCP (Model Context Protocol) data sources in Integration Designer—from initial setup through ongoing tool management. Once configured, the MCP server's tools become available for use in Custom Agent nodes within your workflows.

## Prerequisites

Before adding an MCP data source, ensure you have:

* Access to Integration Designer with appropriate permissions
* MCP server URL and connection details
* Authentication credentials (if required)
* Knowledge of which tools you want to enable

> [!NOTE]
>
> Ensure you have the necessary permissions to access Integration Designer and manage data sources.

## Adding an MCP server

### Step 1: Access Integration Designer

1. Open **FlowX Designer** and navigate to **General Settings**.
2. Select **Integration Designer** from the menu.
3. Click **Add Data Source**.

### Step 2: Select MCP server type

1. In the data source type selection, choose **MCP Server**.
2. A configuration form appears with required fields.

![Add MCP Data Source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp.png)

### Step 3: Configure basic information

**1. Enter Name**

Provide a unique name for the MCP server connection.

**2. Add Description**

(Optional) Provide a description of the MCP server's purpose and the tools it provides.

This description is displayed in the MCP server details page and helps team members understand the integration's purpose.

> [!NOTE]
>
> If not provided, the description will be autofillled after test connection is successful.

**3. Configure Server URL**

Enter the base URL of the MCP server.

**Requirements:**

* **Required**: URL cannot be empty
* **Format**: Must be a valid URL (e.g., `https://api.example.com/mcp`)
* **Multiple Connections**: You can create multiple connections to the same MCP server with different configurations

**Example URLs:**

```
https://api.githubcopilot.com/mcp/
https://mcp.figma.com/mcp
https://mcp.intercom.com/sse
```

![MCP Server Basic Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp1.png)

### Step 4: Configure authentication

Select the appropriate authentication method for your MCP server:

> [tab] None
>
> No authentication required. The MCP server accepts requests without credentials.
>
> **Use case**: Development environments, public MCP servers, or servers with network-level security.
>
> **Configuration**: No additional fields required.

> [tab] Basic Auth
>
> Username and password authentication.
>
> **Use case**: MCP servers with simple authentication requirements.
>
> **Required fields:**
>
> **username** `string` *required*
>
> The username for authentication.
>
> **password** `string` *required*
>
> The password for authentication. Stored securely.

> [tab] Bearer Token
>
> Static token-based authentication sent in the Authorization header.
>
> **Use case**: MCP servers that accept pre-generated access tokens or API keys.
>
> **Required fields:**
>
> **token** `string` *required*
>
> The bearer token value. Stored securely.

> [tab] API Key
>
> Key-based authentication sent via a header or query parameter.
>
> **Use case**: Third-party API services that use API key authentication.
>
> **Required fields:**
>
> **apiKey** `string` *required*
>
> The API key value. Stored securely.

> [tab] OAuth2 Client Credentials
>
> OAuth 2.0 service account authentication using the **client credentials flow**.
>
> **Use case**: Production environments requiring secure service-to-service authentication.
>
> **Required fields:**
>
> **clientId** `string` *required*
>
> The OAuth 2.0 client identifier provided by your identity provider.
>
> **clientSecret** `string` *required*
>
> The OAuth 2.0 client secret. This is encrypted and stored securely.
>
> **identityProviderUrl** `string` *required*
>
> The URL of your OAuth 2.0 authorization server (e.g., `https://auth.example.com/oauth/token`).
>
> ![MCP Service Account Authentication](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp3.png)

> [tab] OAuth2 User
>
> OAuth 2.0 authentication that carries user identity context, using a redirect URI for authorization.
>
> **Use case**: Operations that require the end-user's identity for access control or auditing.
>
> **Required fields:**
>
> **clientId** `string` *required*
>
> The OAuth 2.0 client identifier.
>
> **clientSecret** `string` *required*
>
> The OAuth 2.0 client secret.
>
> **identityProviderUrl** `string` *required*
>
> The authorization server endpoint.
>
> **redirectUri** `string` *required*
>
> The redirect URI for the OAuth2 authorization flow.

### Step 5: Test connection

Before saving the MCP data source, test the connection to verify it's configured correctly.

1. Click **Test Connection** button.
2. The system attempts to connect to the MCP server using the provided configuration.
3. Wait for the connection test result:

**Success Response:**

```json theme={"dark"}
{
  "status": 200,
  "message": "Connection successful"
}
```

> [!TIP]
>
> If the connection test succeeds, you can proceed to save the data source. If it fails, review the error message and verify your configuration.

![Successful Connection Test](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp4.png)

### Step 6: Save and view tools

1. After a successful connection test, click **Create**.
2. The MCP server is persisted as a data source.
3. You are automatically redirected to the MCP server details page, where available tools are displayed.

> [!NOTE]
>
> By default, all tools exposed by the MCP server are enabled. You can turn off specific tools from the MCP server details page.

## MCP server details page

After successfully adding an MCP server, the details page displays:

### Header Information

* **Title**: The name you assigned to the MCP server
* **Subtitle**: Description and server URL (trimmed to one row)
  * Click to view full description in a modal

![MCP Server Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp5.png)

### Tools tab

The Tools tab displays all available tools from the MCP server and allows you to manage which tools are available for use in Custom Agent nodes.

![MCP Tools Management](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp6.png)

#### Understanding tool information

Each tool in the MCP server displays the following information:

**name** `string`

The unique identifier for the tool. This name is used when the AI agent invokes the tool.

**description** `string`

A brief description of what the tool does. This helps users understand the tool's purpose and when to use it.

**status** `boolean`

Indicates whether the tool is currently enabled (available to AI agents) or disabled (not available).

* **Enabled**: Tool can be used in Custom Agent nodes
* **Disabled**: Tool is hidden from Custom Agent node configuration

#### Viewing tool details

To view complete details about a tool:

1. Click on any tool row in the Tools tab
2. A modal window opens displaying:

> [accordion] Tool Name
>
> The complete name of the tool as registered in the MCP server.

> [accordion] Description
>
> Full description of the tool's functionality, including:
>
> * What the tool does
> * When to use it
> * Expected behavior

![MCP Tool Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp6.png)

> [accordion] Input Schema
>
> JSON Schema defining the expected input parameters for the tool.
>
> **Example:**
>
> ```json theme={"dark"}
>   {
>     "type": "object",
>     "properties": {
>       "customerId": {
>         "type": "string",
>         "description": "The unique identifier for the customer"
>       },
>       "includeOrders": {
>         "type": "boolean",
>         "description": "Whether to include order history",
>         "default": false
>       }
>     },
>     "required": ["customerId"]
>   }
> ```
>
> > [!NOTE]
> >
> > The input schema is used by AI agents to understand what parameters the tool expects and how to format requests.

> [accordion] Output Schema (Optional)
>
> JSON Schema defining the structure of the tool's response.
>
> **Example:**
>
> ```json theme={"dark"}
>   {
>     "type": "object",
>     "properties": {
>       "customer": {
>         "type": "object",
>         "properties": {
>           "id": { "type": "string" },
>           "name": { "type": "string" },
>           "email": { "type": "string" }
>         }
>       },
>       "orders": {
>         "type": "array",
>         "items": {
>           "type": "object",
>           "properties": {
>             "orderId": { "type": "string" },
>             "total": { "type": "number" }
>           }
>         }
>       }
>     }
>   }
> ```
>
> > [!NOTE]
> >
> > Output schemas are optional. If not provided, the AI agent will work with the actual response structure returned by the tool.

![MCP Tool Details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp7.png)

#### Enabling and disabling tools

You can control which tools are available for use in Custom Agent nodes by enabling or disabling them.

**Enable/Disable Individual Tools:**

**1. Access Tool Menu**

In the Tools tab, locate the tool you want to enable or disable.

**2. Toggle Tool Status**

* Click the three-dot menu (⋯) at the end of the tool row
* Select **Enable** or **Disable** from the menu

**3. Confirm Change**

The tool's status updates immediately. Enabled tools show a green status indicator, while disabled tools show a gray indicator.

![Enable/Disable Tools Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp8.png)

> [!WARNING]
>
> Disabling tools that are currently in use by active workflows may affect those workflows. Always verify that tools are not in use before disabling them.

### Authorization tab

The Authorization tab displays the current authentication configuration:

* **Authentication Type**: None, Basic Auth, Bearer Token, API Key, OAuth2 Client Credentials, or OAuth2 User
* **Configuration Details**: Relevant fields for the selected auth type (sensitive information like secrets and tokens are hidden)

> [!WARNING]
>
> Changes to authentication settings require re-testing the connection and may affect existing workflows using this MCP server.

![Authorization Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mcp9.png)

## Managing tools

### Refreshing tools from MCP server

Tools are automatically synchronized from the MCP server when you:

* Initially connect the MCP server
* Re-test the connection from the Authorization tab
* Manually refresh the tools list

To manually refresh tools:

1. Navigate to the MCP server details page
2. Go to the **Authorization** tab
3. Click **Check for Updates**
4. If successful, return to the **Tools** tab to see any new or updated tools

> [!NOTE]
>
> Tool definitions (name, description, schemas) are read-only and managed by the MCP server. You can only control the enabled/disabled status from Integration Designer.

### API endpoint for tool management

Tools can also be managed programmatically using the API:

**Enable/Disable Tool API:**

```http theme={"dark"}
POST /api/systems/tool/{toolId}/enable?resourceId={resourceId}
```

**Request Body:**

```json theme={"dark"}
{
  "enabled": true
}
```

**Response:**

A successful call returns `200 OK` with an empty response body.

> [!NOTE]
>
> For complete API documentation, see [MCP API Reference](../../../api/mcp-api-reference).

### Monitoring tool usage

To understand which tools are being used in your workflows:

1. Navigate to the **Run Logs** section after running a workflow
2. Check the **Tools** tab (visible when MCP tools are used)
3. Review which tools were invoked and their execution details

![Tool Usage Monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/run_logs.png)

## Managing multiple MCP connections

You can create multiple connections to the same MCP server with different configurations:

**Use Cases:**

* Different authentication credentials for different environments
* Separate tool configurations for different use cases
* Testing vs. production instances

**Example:**

```
- CRM Production (https://api.crm.com) - Service Account Auth
- CRM Development (https://api.crm.com) - No Auth
- CRM Testing (https://api.crm.com) - Different Service Account
```

## Validation rules summary

> [accordion] Name Validation
>
> * **Required**: ✅ Yes
> * **Unique**: ✅ Within project
> * **Allowed Characters**: Letters, numbers, `[]`, `()`, `.`, `_`, `-`
> * **Error Message**: "Name must be unique inside the project." or "Name can only contain letters, numbers and the following special characters \[] () . \_ -"

> [accordion] Description Validation
>
> * **Required**: ❌ No
> * **Max Length**: No explicit limit (trimmed in UI display)

> [accordion] Server URL Validation
>
> * **Required**: ✅ Yes
> * **Unique**: ❌ No (multiple connections allowed)
> * **Format**: Valid URL with protocol (http/https)

> [accordion] Authentication Validation
>
> * **Required Fields**: Depends on authentication type selected
> * **Service Account**: All three fields (Client ID, Client Secret, Identity Provider URL) are required

## Best practices

### Data source setup

> [!TIP]
>
> **Test Before Saving**: Always test the connection before saving an MCP data source to ensure the configuration is correct.

> [!TIP]
>
> **Use Descriptive Names**: Choose clear, descriptive names that indicate the MCP server's purpose and environment (e.g., "CRM-Production", "Analytics-Dev").

> [!TIP]
>
> **Document Purpose**: Add detailed descriptions to help team members understand what the MCP server provides and when to use it.

> [!TIP]
>
> **Secure Authentication**: Use Service Account authentication for production environments to ensure secure access.

### Tool management

> [!TIP]
>
> **Start with All Enabled**: By default, all tools are enabled. Review the available tools and disable only those you don't need.

> [!TIP]
>
> **Regular Audits**: Periodically review enabled tools to ensure they're still needed and being used effectively.

> [!TIP]
>
> **Security Considerations**: Disable tools that provide access to sensitive data or operations if they're not needed for your use case.

### Workflow impact considerations

Before disabling tools, consider the following:

1. **Check Tool Usage**: Verify if the tool is currently used in any active workflows
2. **Impact Assessment**: Understand what workflows might be affected
3. **Communication**: Notify team members before disabling tools that might be in use
4. **Testing**: Test workflows after re-enabling tools to ensure they work as expected

> [!WARNING]
>
> If you disable a tool that's referenced in a Custom Agent node, that node will not be able to use the tool during execution. The AI agent will work with the remaining enabled tools only.

## Common issues and troubleshooting

> [accordion] Connection Test Fails
>
> **Possible Causes:**
>
> * Invalid server URL
> * Incorrect authentication credentials
> * Network connectivity issues
> * MCP server is down or unreachable
>
> **Solutions:**
>
> * Verify the server URL is correct and accessible
> * Check authentication credentials with your MCP server administrator
> * Test network connectivity to the MCP server
> * Confirm the MCP server is running and accepting connections

> [accordion] No Tools Displayed
>
> **Possible Causes:**
>
> * MCP server hasn't exposed any tools
> * Connection issue after initial setup
>
> **Solutions:**
>
> * Verify the MCP server is configured to expose tools
> * Re-test the connection from the Authorization tab
> * Contact your MCP server administrator

> [accordion] Name Validation Error
>
> **Error**: "Name must be unique inside the project."
>
> **Solution**: Choose a different name that hasn't been used in this project.
>
> ***
>
> **Error**: "Name can only contain letters, numbers and the following special characters \[] () . \_ -"
>
> **Solution**: Remove any special characters that aren't in the allowed list.

> [accordion] New Tools Not Appearing
>
> **Problem**: You added new tools to your MCP server, but they don't appear in Integration Designer.
>
> **Solution**:
>
> 1. Go to the Authorization tab
> 2. Click **Test Connection** to refresh the tool list
> 3. Return to the Tools tab to see the new tools

> [accordion] Tool Used in Active Workflow
>
> **Problem**: You want to disable a tool, but it's used in an active workflow.
>
> **Solution**:
>
> 1. Search for workflows using the tool
> 2. Update those workflows to use alternative tools or remove the MCP server reference
> 3. Test the modified workflows
> 4. Disable the tool once it's no longer in use

> [accordion] Re-enabling a Previously Disabled Tool
>
> **Problem**: You disabled a tool and now need to re-enable it.
>
> **Solution**:
>
> 1. Find the tool in the Tools tab (disabled tools are still listed)
> 2. Click the toggle or menu to enable it
> 3. Test workflows that use this tool to ensure they work correctly

> [accordion] Tool Schema Changes
>
> **Problem**: The MCP server updated a tool's input or output schema.
>
> **Solution**:
>
> 1. Test the MCP connection to refresh tool definitions
> 2. Review the updated schema in the tool details modal
> 3. Update any Custom Agent nodes that use this tool to match the new schema
> 4. Test affected workflows

## Next steps

> [card] [Custom Agent Node](../custom-agent-node)
>
> Learn how to use MCP tools in workflows with Custom Agent nodes

## Related resources

> [card] [MCP Integration Overview](./mcp-integration-overview)
>
> Learn about MCP integration capabilities

> [card] [MCP API Reference](../../../api/mcp-api-reference)
>
> View API documentation for programmatic access

> [card] [Integration Designer course](https://academy.flowx.ai/explore/integration-designer)
>
> Hands-on course covering data sources including MCP server integration


# MCP integration
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview

Learn how to integrate Model Context Protocol (MCP) servers with FlowX.AI to enable AI agents to use external tools and services.

## Overview

The Model Context Protocol (MCP) integration connects FlowX.AI with external MCP servers and exposes their tools to AI agents. AI agents can interact with external systems, databases, APIs, and services through this protocol.

> [!NOTE]
>
> MCP is a protocol for AI agents to access external tools and data sources.

## Key features

* Connect MCP servers as data sources in Integration Designer
* Enable or turn off specific tools exposed by MCP servers
* Use MCP tools in workflow processes through Custom Agent nodes
* Secure connections with multiple authentication methods
* Monitor tool usage and execution details in console logs

## How it works

```mermaid theme={"dark"}
graph LR
    A[Integration Designer] -->|Connect| B[MCP Server]
    B -->|Expose Tools| C[Tool Registry]
    C -->|Select Tools| D[Custom Agent Node]
    D -->|Execute| E[AI Service]
    E -->|Use Tools| B
```

### High-level workflow

1. **Add MCP server**: Configure an MCP server connection as a data source in Integration Designer
2. **Authorize access**: Authenticate the connection using supported authentication methods
3. **Manage tools**: View and enable or turn off available tools from the MCP server
4. **Use in workflows**: Add Custom Agent nodes to workflows and select which MCP servers to use
5. **Execute and monitor**: Run workflows and track tool usage in console logs

## Supported protocols and features

> [!NOTE]
>
> The MCP integration is actively being developed. The features listed below represent the current capabilities. Additional protocol support and authentication methods will be added in future releases.

### Transport protocols

The following transport protocols are currently supported:

> [accordion] SSE (Server-Sent Events)
>
> Server-Sent Events protocol for real-time, unidirectional communication from the MCP server to FlowX.AI.
>
> **Use Case**: Ideal for streaming responses and long-running operations where the server needs to push updates to the client.

> [accordion] Streamable HTTP
>
> HTTP-based streaming protocol for receiving data in chunks over a persistent connection.
>
> **Use Case**: Suitable for large data transfers and scenarios where you need progressive response handling.

### Proxy support

MCP connections support inline proxy configuration for environments that require routing through a proxy server. This is configured directly on each MCP data source connection.

| Setting | Description |
| - | - |
| **Protocol** | HTTP, HTTPS, SOCKS4, or SOCKS5 |
| **Host and port** | Proxy server address |
| **Authentication** | Optional basic authentication for the proxy |
| **No-proxy patterns** | Bypass list for addresses that should not use the proxy |
| **SSL verification** | Toggle SSL/TLS certificate verification |
| **Connection timeout** | Configurable timeout for proxy connections |

> [!NOTE]
>
> This is separate from the reusable [Proxy connections](../proxy-connections) resource available for RESTful System data sources. MCP data sources use their own inline proxy configuration.

***

## Authentication methods

MCP integrations support the following authentication methods:

| Method | Description | Use case |
| - | - | - |
| **None** | No authentication | Public MCP servers, development environments |
| **Basic Auth** | Username and password | Simple authentication requirements |
| **Bearer Token** | Static token-based authentication | API key or pre-generated token access |
| **API Key** | Key-based authentication via header or query parameter | Third-party API access |
| **OAuth2 Client Credentials** | Service account authentication | Production service-to-service communication |
| **OAuth2 User** | User-context OAuth2 with redirect URI | Operations requiring user identity context |

> [!NOTE]
>
> The authentication type is selected during MCP server setup and can be discovered automatically during connection testing using the **Supported Auth Discovery** feature.

## Use cases

### External API integration

Connect to external APIs and services through MCP tools. AI agents can fetch data, trigger actions, and integrate with third-party systems.

### Database operations

Query databases, retrieve records, and perform data operations through MCP tools.

### Custom business logic

Expose custom business logic as MCP tools for AI agents to execute.

### Multi-system orchestration

Use multiple MCP servers in a single Custom Agent node to orchestrate operations across different systems.

## Next steps

> [card] [MCP Data Sources](./adding-mcp-data-source)
>
> Add, configure, and manage MCP servers and their tools

> [card] [Custom Agent Node](../custom-agent-node)
>
> Use MCP tools in workflows with Custom Agent nodes

> [card] [MCP API Reference](../../../api/mcp-api-reference)
>
> API documentation for MCP integration

## Related resources

> [card] [Integration Designer](../integration-designer)
>
> Integration Designer and data sources

> [card] [Integrations Overview](../integrations-overview)
>
> Integration ecosystem overview


# Proxy connections
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/proxy-connections

Create and manage reusable proxy connections to route data source traffic through HTTP or HTTPS proxy servers.

## Overview

Proxy connections let you route data source traffic through an intermediary proxy server. Instead of configuring proxy settings on each data source individually, you create reusable proxy connection resources in Integration Designer and attach them to one or more data sources.

This is useful in environments where outbound traffic must pass through a corporate proxy, or when you need to route API calls through a specific gateway for security or compliance reasons.

***

## Key features

> [card] HTTP and HTTPS
>
> Support for both HTTP and HTTPS proxy protocols

> [card] Basic authentication
>
> Optional user and password authentication for proxy servers that require credentials

> [card] Test connectivity
>
> Validate proxy configuration before saving with the built-in test function

> [card] Reusable across data sources
>
> Create a proxy once and attach it to multiple RESTful System data sources

***

## Managing proxy connections

Proxy connections are managed from the **Proxy Connections** section in Integration Designer.

To access the proxy list:

**1. Open your project**

Open **FlowX Designer** and navigate to your project.

**2. Expand Integrations**

In the left sidebar, expand **Integrations**.

**3. Open Proxy Connections**

Click **Proxy Connections**.

![Proxy Connections list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_list.png)

The list displays all configured proxy connections with the following information:

| Column | Description |
| - | - |
| **Name** | The proxy connection name |
| **Description** | Optional description of the proxy's purpose |
| **Type** | HTTP or HTTPS |
| **Edited by** | User who last modified the proxy |
| **Edited at** | Date and time of last modification |

***

## Adding a proxy connection

**1. Open the proxy creation form**

From the **Proxy Connections** list, click the **+** button at the top of the page.

**2. Configure basic information**

![Add Proxy Connection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_add.png)

Fill in the following fields:

| Field | Required | Description |
| - | - | - |
| **Name** | Yes | A unique name for the proxy connection |
| **Description** | No | Purpose or context for this proxy |
| **Proxy Type** | Yes | Select **HTTP** or **HTTPS** |
| **Proxy Host** | Yes | The proxy server hostname or IP address. Supports `${param}` for configuration parameters. |
| **Proxy Port** | Yes | The proxy server port number. Supports `${param}` for configuration parameters. |

**3. Set auth type**

Select an **Auth Type** from the dropdown:

> [tab] NO\_AUTH
>
> No authentication required. The proxy accepts connections without credentials.

> [tab] BASIC
>
> Username and password authentication for the proxy server.
>
> **Required fields:**
>
> **user** `string` *required*
>
> The user for proxy authentication.
>
> **password** `string` *required*
>
> The password for proxy authentication. Stored securely.

**4. Test the proxy connection**

Click **Test Connection** to validate the configuration. The system attempts to connect through the proxy and reports success or failure.

> [!TIP]
>
> If the test succeeds, the proxy is ready to use. If it fails, verify the host, port, and credentials.

**5. Create the proxy**

Click **Create** to save the proxy connection. It is now available for use with data sources.

***

## Using proxies with data sources

Proxy connections can be attached to **RESTful System** data sources. When a proxy is attached, all API calls made through that data source are routed through the proxy server.

### Attaching a proxy to a data source

**1. Open a RESTful System data source**

Navigate to the data source configuration in Integration Designer. This works for both new and existing RESTful System data sources.

**2. Turn on proxy routing**

Toggle **Connect through Proxy** to **ON**. A new dropdown field appears.

**3. Select a proxy connection**

Choose a proxy from the **Select Proxy Connection** dropdown. The list shows all available proxy connections in the current project.

If no proxies exist, the dropdown shows a **Create** option that takes you to the proxy creation form.

**4. Save the data source**

Save the data source configuration. All subsequent API calls through this data source will be routed through the selected proxy.

> [!WARNING]
>
> If you delete a proxy connection that is in use by a data source, the data source does **not** automatically switch back to a direct connection. You must manually update the data source configuration.

***

## Example: route a CRM integration through a corporate proxy

In this scenario, your organization requires all outbound API traffic to pass through a corporate proxy server before reaching external services. You have a RESTful System data source that connects to a CRM API and need to route its traffic through the proxy.

**1. Create the proxy connection**

Go to **Integrations** → **Proxy Connections** and click **+**. Configure:

| Field | Value |
| - | - |
| **Name** | `Corporate Proxy` |
| **Description** | `Routes traffic through the corporate proxy gateway` |
| **Proxy Type** | `HTTPS` |
| **Proxy Host** | `proxy.corp.example.com` |
| **Proxy Port** | `8443` |
| **Auth Type** | `BASIC` |
| **User** | `svc-flowx` |
| **Password** | `••••••••` |

Click **Test Connection** to verify, then click **Create**.

![Corporate Proxy example configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)

> [!TIP]
>
> Use configuration parameters for values that change across environments, for example `${corp.proxy.host}` for the host and `${corp.proxy.port}` for the port. This way the same project works in dev, staging, and production with different proxy servers.

**2. Attach the proxy to a data source**

Go to **Integrations** → **Data Sources** and open your CRM data source (RESTful System type).

Toggle **Connect through Proxy** to **ON** and select **Corporate Proxy** from the dropdown. Save the data source.

**3. Verify in runtime**

Run a workflow that uses the CRM data source. In the runtime console, the cURL preview now reflects the proxy:

```bash theme={"dark"}
curl --proxy https://proxy.corp.example.com:8443 --proxy-user svc-flowx:******** https://crm.example.com/api/v2/contacts
```

***

## Proxy in cURL commands

When a proxy is active on a RESTful System data source, the cURL command preview in the runtime console reflects the proxy configuration.

**Without proxy:**

```bash theme={"dark"}
curl https://api.example.com/data
```

**With proxy (no auth):**

```bash theme={"dark"}
curl --proxy http://proxy-host:8080 https://api.example.com/data
```

**With proxy (basic auth):**

```bash theme={"dark"}
curl --proxy http://proxy-host:8080 --proxy-user user:password https://api.example.com/data
```

**With HTTPS proxy:**

```bash theme={"dark"}
curl --proxy https://proxy-host:8443 https://api.example.com/data
```

***

## Configuration reference

| Property | Type | Required | Description |
| - | - | - | - |
| **Name** | `string` | Yes | Unique name for the proxy connection |
| **Description** | `string` | No | Optional description |
| **Proxy Type** | `HTTP` \| `HTTPS` | Yes | The proxy protocol |
| **Proxy Host** | `string` | Yes | Proxy server hostname or IP. Supports `${param}` syntax. |
| **Proxy Port** | `number` | Yes | Proxy server port. Supports `${param}` syntax. |
| **Auth Type** | `NO_AUTH` \| `BASIC` | Yes | Authentication method |
| **User** | `string` | When Basic | Proxy auth user |
| **Password** | `string` | When Basic | Proxy auth password |

***

## Limitations

The following proxy types and authentication methods are not supported in this release:

| Not supported | Notes |
| - | - |
| SOCKS4 / SOCKS5 | Only HTTP and HTTPS proxy types are available |
| PAC URL | Proxy auto-configuration URLs are not supported |
| Client credentials auth | Only No Auth and Basic Authentication are available |
| mTLS | Mutual TLS authentication for proxy servers is not supported |
| MCP Server data sources | MCP connections use their own [inline proxy configuration](./mcp-integration/mcp-integration-overview#proxy-support) |

***

## Related resources

> [card] [Integration Designer](./integration-designer)
>
> Data sources and workflow integrations

> [card] [MCP Integration](./mcp-integration/mcp-integration-overview)
>
> MCP server connections with separate proxy support


# Unmanaged MongoDB
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb

Connect to externally managed MongoDB instances as a data source in FlowX workflows.

## Overview

Unmanaged MongoDB is a data source type that lets you connect FlowX workflows to **external MongoDB databases that your organization manages independently**. Unlike the built-in [FlowX Database](./flowx-database) — which provisions and manages MongoDB collections automatically — Unmanaged MongoDB connects to existing databases and collections you control.

> [card] Use your infrastructure
>
> Connect to MongoDB instances you already manage, including Atlas, self-hosted, or cloud-managed deployments

> [card] Same operations
>
> Use the same CRUD operations (find, insert, update, delete) as FlowX Database

> [card] Connection discovery
>
> Browse available databases and collections directly from the Designer after connecting

> [card] Connection pooling
>
> Configure pool size, idle timeouts, and maintenance frequency per data source

***

## Managed vs unmanaged MongoDB

| Aspect | FlowX Database (managed) | Unmanaged MongoDB |
| - | - | - |
| **Collection creation** | Automatic — FlowX creates and manages collections | Manual — you provide an existing collection |
| **Schema management** | Defined in FlowX Designer | Optional — you manage schemas externally |
| **Index management** | CRUD via Designer UI | You manage indexes externally |
| **Connection** | Internal, handled by FlowX | You provide a connection URI |
| **Auth** | Internal | Username/password (SCRAM-SHA-256), or credentials embedded in the connection URI |
| **Use case** | Data sharing between FlowX processes | Integrate with existing MongoDB infrastructure |

> [!TIP]
>
> Use **FlowX Database** when you need FlowX to manage the full lifecycle of your data. Use **Unmanaged MongoDB** when you need to read from or write to databases that exist outside FlowX.

> [!NOTE]
>
> Both [FlowX Database](./flowx-database) (managed) and Unmanaged MongoDB are served by the same **nosql-db-runner** service. Managed collections are stored in nosql-db-runner's own MongoDB database, while an Unmanaged MongoDB data source opens a separate, isolated connection to the external instance you specify — it never touches nosql-db-runner's internal database. Point it at infrastructure you own and manage.

***

## Prerequisites

* A MongoDB 6.0+ instance accessible from your FlowX deployment
* An existing database and collection on the target instance
* A MongoDB user with appropriate permissions (read, write, or both)
* Network connectivity between FlowX services and the MongoDB instance
* For TLS/SSL connections: appropriate certificates configured on the MongoDB instance

***

## Creating an Unmanaged MongoDB data source

![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)

**1. Open Data Sources**

Navigate to **Integrations** → **Data Sources** in your project.

**2. Create a new data source**

Click **New Data Source** and select **Unmanaged MongoDB** as the type.

**3. Configure the connection**

Enter the MongoDB connection URI:

```
mongodb+srv://username:password@cluster.example.net
```

Or standard format:

```
mongodb://username:password@host:27017
```

**4. Test the connection**

Click **Test Connection** to verify connectivity and credentials.

**5. Select database and collection**

After a successful connection test, browse available databases and select the target database. Then browse and select the target collection.

**6. Configure authorization (optional)**

In the **Authorization** tab, configure authentication if not embedded in the connection URI.

**7. Save**

Click **Save** to create the data source.

> [!WARNING]
>
> The target collection must already exist on the MongoDB instance. FlowX does not create collections on unmanaged databases.

***

## Connection pool configuration

Each Unmanaged MongoDB data source has its own connection pool. You can tune pool settings in the data source **Settings** tab:

| Setting | Description | Default |
| - | - | - |
| **Min pool size** | Minimum number of connections maintained | `0` |
| **Max pool size** | Maximum number of concurrent connections | `100` |
| **Max idle time** | How long an idle connection stays open | `60000` ms (1 min) |
| **Max lifetime** | Maximum lifetime of a connection | `0` (unlimited) |
| **Wait queue timeout** | How long a request waits for an available connection | `120000` ms (2 min) |
| **Maintenance frequency** | How often the pool checks for idle connections to close | `60000` ms (1 min) |

> [!TIP]
>
> For production workloads, set **Min pool size** to match your baseline concurrent usage to avoid connection warm-up latency.

***

## Operations

Unmanaged MongoDB supports the same operations as [FlowX Database](./flowx-database):

| Operation | Description |
| - | - |
| `find` | Retrieve multiple documents based on criteria |
| `findOne` | Retrieve a single document |
| `insertOne` | Add a single document |
| `insertMany` | Add multiple documents at once |
| `updateOne` | Modify a single document |
| `updateMany` | Modify multiple documents at once |
| `deleteOne` | Remove a single document |
| `deleteMany` | Remove multiple documents at once |

Operations are configured the same way as FlowX Database operations — with filters, projections, sorting, and parameter substitution using `${paramName}` syntax. You can test operations directly in the Designer before using them in workflows.

The **Documents** tab on the data source page lets you browse documents in the collection with pagination, filtering, and sorting.

For details on configuring each operation, see the [FlowX Database operations documentation](./flowx-database#mongodb-operations-supported).

***

## Using in workflows

Unmanaged MongoDB data sources are used in workflows the same way as other data sources:

**1. Create operations**

Define operations on the data source (find, insert, update, delete).

**2. Add a Data Source node**

Add a **Data Source** node to your workflow.

**3. Select the data source**

Select the Unmanaged MongoDB data source and operation.

**4. Map parameters**

Map input/output parameters in the data mapper.

***

## Deployment

No additional microservices are required. Unmanaged MongoDB uses the existing **nosql-db-runner** service to execute operations against your external MongoDB instance.

Ensure the `nosql-db-runner` service has network access to your MongoDB instance. If your MongoDB is behind a firewall, configure the appropriate network rules.

***

## Related resources

> [card] [FlowX Database](./flowx-database)
>
> Managed MongoDB data storage within FlowX

> [card] [Integration Designer](./integration-designer)
>
> Overview of all data source types and workflow building

> [card] [NoSQL DB Runner setup](/5.9/setup-guides/nosql-db-runner)
>
> Deployment configuration for the database runner service


# Workflow data model
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/workflow-data-models

Define structured data models at the workflow level with input and output parameters, enabling consistent data lineage and structured integration between processes and Integration Designer workflows.

> [!TIP]
>
> **Workflow data models** define input and output parameters for **Start Nodes** and **End Nodes**:
>
> * **Input parameters**: Define the data structure that enters the workflow through the Start Node. The input parameters automatically pre-fill the Start Node when you open the workflow diagram or test the workflow at runtime.
> * **Output parameters**: Define the data structure returned by End Nodes when the workflow completes.
>
> When a workflow is integrated into another resource (for example, a process), these parameters define how data is processed between the two components:
>
> * **Input mapping** (Start Integration Workflow Action): Maps data from the process to the workflow's input parameters when starting the workflow.
> * **Output mapping** (Receive Message Task): Maps data returned from the workflow back to the process variables.

## Overview

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)

Define data models at the workflow level with input and output parameters, similar to Process Definitions

Workflow data models bring the same structured data management capabilities available in Process Definitions to Integration Designer workflows. By defining data models at the workflow level, you ensure consistent data lineage across your integration architecture, making workflows more reusable, testable, and maintainable.

> [card] Structured Data Management
>
> Define entities, attributes, and custom data types at the workflow level, similar to Process Data Models

> [card] Input/Output Parameters
>
> Specify which data enters and exits your workflow with automatic parameter management

> [card] Process Integration
>
> Map data bidirectionally between processes and workflows using data mappers

> [card] Type Safety & Validation
>
> Define data types and validation rules to ensure runtime data integrity

***

## Key concepts

### Workflow data model

A Workflow Data Model defines the structure of data used throughout a workflow's execution. It consists of:

* **Entities**: Logical groupings of related data (for example, Customer, Order, Payment)
* **Attributes**: Individual data fields with types and constraints
* **Input Parameters**: Subset of the data model defining workflow input parameters
* **Output Parameters**: Subset of the data model defining workflow output parameters

### Workflow

Workflow parameters are defined in the data model that define which data is passed as input or returned as output:

* **Input Parameters**: Automatically pre-fills the Start Node with structured data when you open the workflow diagram tab or test the workflow at runtime
* **Output Parameters**: Defines the data structure returned by End Nodes. Currently, output parameters work as-is (you can manually configure them), but automatic pre-filling from output parameters is planned for future releases

### Node name uniqueness

> [!WARNING]
>
> Node names within a workflow must be unique to ensure clear data lineage and avoid ambiguity when mapping data.

When you rename nodes, the system validates uniqueness. If a duplicate name exists, an index is automatically appended (for example, `Transform`, `Transform_2`, `Transform_3`).

***

## Creating a workflow data model

**1. Navigate to Workflow Settings**

Open your workflow in Integration Designer and navigate to the **Data Model** tab in workflow settings.

![Workflow Data Model Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_dm.png)

**2. Define Entities**

Create entities to represent the logical data structures in your workflow:

* Click **Create Attribute**
* Enter an entity name (e.g., `Customer`, `Order`)
* Add a description for documentation

**3. Add Attributes**

For details on adding and configuring attributes for your data model—including data types, required fields, validation, and advanced options—see the [**Data Model**](../../building-blocks/process/data-model) documentation.

**4. Configure Input Parameters**

Define which data will be passed as input to your workflow:

* Open the **Input Parameters** tab
* Click **Define parameters**, or **Edit** if the workflow already has input parameters
* Select attributes from your data model to include
* Mark required parameters

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Process%20-%20Input%20Params.png)

> [!NOTE]
>
> Input parameters data automatically pre-fills the Start Node when you open the workflow diagram or test at runtime.

**5. Configure Output Parameters**

Define which data will be returned when your workflow completes:

* Open the **Output Parameters** tab (the workflow needs an End node first, because output parameters belong to it)
* Click **Define parameters**, or **Edit** if the workflow already has output parameters
* Select attributes from your data model to include as outputs
* These parameters define the data structure returned by End Nodes

> [!NOTE]
>
> Output parameters are used when mapping workflow results back to the calling process via the Receive Message Task.

**6. Save and Test**

Save your data model and test the workflow to verify input and output parameter mapping works correctly.

***

## Input parameter management

### Automatic start node pre-filling

When you define input parameters, the Workflow Start Node is automatically populated with the structured data:

![Input Parameters tab of a workflow data model listing four number attributes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/workflow-input-parameters.png)

Input parameters definition

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/prefill_start_node.png)

Automatic pre-filling of the Workflow Start Node

> [!WARNING]
>
> **Important**: If you manually modify the JSON structure in the Start Node, your changes will be lost when you refresh the workflow diagram or reopen the workflow. The Start Node is automatically populated from the input parameters definition, so any manual edits are overwritten.
>
> To change the input structure, update the input parameters definition in the **Input Parameters** tab instead of editing the Start Node JSON directly.

### Empty input parameters behavior

If no input parameters are defined for a workflow, the Start Node contains an empty object (`{}`). The input parameters are optional, but defining it provides better structure and type safety for your workflow inputs.

### Benefits of input parameters

> [card] No Manual Editing
>
> Input parameters automatically pre-fill the Start Node - no JSON editing needed

> [card] Type Safety
>
> Data types are enforced at the workflow level, preventing runtime errors

> [card] Clear Contracts
>
> Input parameters document exactly what data the workflow expects

> [card] Easier Testing
>
> Test workflows with structured input data based on the data model

***

## Integration with processes

### Process to workflow data mapping

Use data mappers to pass data from processes to workflows. The data mapper configuration in the **Start Integration Workflow** action maps process data to workflow input parameters, independent of the workflow's input parameters definition.

> [!NOTE]
>
> The workflow's input parameters are used for:
>
> * Pre-filling the Start Node when designing/testing workflows
> * Documenting the expected input structure
>
> When invoking workflows from processes via **Start Integration Workflow** action, data mappers handle the actual data mapping at runtime.

**1. Add Start Integration Workflow Action**

In your process definition, add a **Start Integration Workflow** action to the node where you want to invoke the workflow. Choose the workflow you want to invoke from the dropdown.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/test_wk_dm.png)

Start Integration Workflow action

**2. Configure Input Mapping**

Access **Input Mapping** tab to configure the input mapping.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_input_mapping.png)

Input Mapping tab

Map process data to workflow input parameters using the data mapper:

```json theme={"dark"}
{
  "customerId": "${application.customer.id}",
  "accountNumber": "${application.account.number}",
  "amount": "${application.transaction.amount}"
}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_input_mapping1.png)

Input Mapping

> [!TIP]
>
> The keys on the left should match your workflow's input parameters for consistency, though the data mapper operates independently.

**3. Add Receive Message Task**

Add a **Receive Message Task** node to capture workflow output when the workflow completes.

Add a **Data Stream** by going to the **Node Config -> Integration Output -> Data Streams** tab and clicking **Add Data Stream**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_output_mapping.png)

Data Streams tab

**4. Configure Output Mapping**

Create a data mapper on the Receive Message Task to map workflow outputs back to process data:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_output_mapping1.png)

Data Stream

> [!TIP]
>
> When you use User Tasks, the input and output mapping are both available in the User Task node configuration at Node Config -> Integration Input/Output -> Data Streams.

### Example: User search workflow

This example demonstrates a workflow that searches for a user in the FlowX database using a username and returns the user's available information.

#### Workflow data model configuration

Configure your workflow data model with the following parameters:

**Input Parameter:**

* `username` (String, required) - The user's name to search for

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex.png)

Input Parameter

**Output Parameter:**

* `user` (Object) - The user object containing all available user information

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex1.png)

Output Parameter

#### Process setup

The process includes:

1. **User Task**: Contains an input field where users enter the username to search

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex2.png)

User Task

2. **Search Button**: Triggers the **Start Integration Workflow** action

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex3.png)

Start Integration Workflow Action

3. **Results Container**: Configured with conditional visibility to display only when results are returned

```text Example theme={"dark"}
**User found:**
Name: ${user.name}
Account ID: ${user.account_id}
Active user: ${user.is_active}
```

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex4.png)

Results Container

#### Mapping configuration

The **Start Integration Workflow** action requires two mapping configurations:

**Input Mapping (Process → Workflow):**

Maps the username from the main process to the workflow's expected input variable:

```json theme={"dark"}
{
  "username": "${user.name}"
}
```

**Output Mapping (Workflow → Process):**

To configure output mapping:

1. Add a **data stream** for the workflow on the Receive Message Task
2. Define the user object as the output variable needed by the main process
3. Link the workflow's returned variables to the process variables

```json theme={"dark"}
{
  "user": "${user}" //entire user object is returned
}
```

> [!NOTE]
>
> The output mapping displays all available end nodes from the workflow. Select the appropriate end node that returns the user data.

### User database

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex6.png)

User database

> [!NOTE]
>
> The user database is a simple database with a single user object.

#### Workflow diagram

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_ex5.png)

Workflow diagram

> [!NOTE]
>
> You can see the start workflow node is pre-filled with the input parameter.

#### Execution results

When the process runs and the search action executes:

**Workflow Input:**

```json theme={"dark"}
{
  "username": "Joshua Helk"
}
```

**Workflow Output:**

```json theme={"dark"}
{
  "user": {
    "_id": "6936ceb5c72d63c5585b93e7",
    "name": "Joshua Helk",
    "account_id": "dsa76d09ashu0231",
    "creation_date": "date",
    "is_active": true
  }
}
```

After workflow completion, all output information is available in the process variables of the main process, and the results container displays the user information.

***

## Best practices

### Data model structure

> [card] Use logical entities
>
> Group related attributes into meaningful entities that represent domain concepts

> [card] Consistent naming
>
> Use camelCase for attributes and PascalCase for entities consistently

> [card] Reuse existing data types
>
> Reuse existing data types for bulk mapping to simplify data model creation and ensure consistency

> [card] Document everything
>
> Add descriptions to entities and attributes for better team understanding

> [card] Keep it simple
>
> Start with minimal data models and expand as needed

### Input and output design

**DO:**

✅ Define only required input parameters in the input parameters\
✅ Use meaningful parameter names that describe the data\
✅ Set appropriate data types for validation\
✅ Mark parameters as required when they're essential

**DON'T:**

❌ Include unnecessary data in input/output parameters\
❌ Use ambiguous or cryptic parameter names\
❌ Make all parameters optional when some are required\
❌ Change data model structure without updating mappings

### Node naming

> [!TIP]
>
> Use descriptive node names that indicate their purpose:
>
> * ✅ `FetchCustomerData`, `ValidateCreditScore`, `TransformResponse`
> * ❌ `Node1`, `Node2`, `Script`

The system enforces unique node names within workflows. If you need similar operations, use descriptive suffixes:

* `FetchCustomerData_Personal`
* `FetchCustomerData_Financial`

***

## Limitations and compatibility

### Current limitations

> [!WARNING]
>
> The following features are **not yet available**:

* **Subworkflow node**: on self-hosted 5.9.x, Subworkflow nodes work as-is without data model integration. On SaaS (5.11), use [Subworkflow data mapping](./workflow-nodes-control-flow#data-mapping) to map data in and out through the subworkflow's data model.
* **Endpoint schema integration**: Endpoint request and response schemas are not integrated with workflow data models yet
* **Database schema mapping**: Database operation schemas are not mapped to workflow variables yet

***

## Related resources

> [card] [Build your first workflow](/5.9/docs/getting-started/building-your-first-workflow)
>
> Tutorial: define workflow inputs and outputs in a working build

> [card] [Integration Designer Overview](./integration-designer)
>
> Learn about Integration Designer workflows and nodes

> [card] [Process Data Model](../../building-blocks/process/data-model)
>
> Understand Process Data Models and how they work

> [card] [Data Mappers](../../building-blocks/process/data-mappers)
>
> Configure data mappings between processes and workflows

> [card] [Start Integration Workflow Action](../../building-blocks/actions/start-integration-workflow)
>
> Invoke workflows from process definitions

***

## Troubleshooting

> [accordion] Start Node input is empty after defining input parameters
>
> **Possible causes:**
>
> * Input parameters not saved correctly
> * Browser cache issues
> * No input parameters defined (results in empty object)
>
> **Solutions:**
>
> * Save the workflow and refresh the browser
> * Re-open the workflow diagram tab
> * Check that the input parameters contains attributes
> * Verify attributes are marked as required if needed
> * If no input parameters are defined, the Start Node will contain an empty object `{}`

> [accordion] Manual changes to Start Node JSON are lost
>
> **Problem:** You manually edited the JSON in the Start Node, but your changes disappeared after refreshing or reopening the workflow.
>
> **Cause:**
> The Start Node is automatically populated from the input parameters definition. Any manual edits are overwritten when the workflow diagram is refreshed or reopened.
>
> **Solution:**
>
> * Update the input parameters definition in the **Input Parameters** tab instead of editing the Start Node JSON directly
> * Changes to the input parameters will automatically reflect in the Start Node
> * If you need a different structure, modify the data model and input parameters accordingly

> [accordion] Node name uniqueness validation error
>
> **Error message:** "Node name must be unique within the workflow"
>
> **Solution:**
>
> * Choose a different, more descriptive node name
> * The system will suggest appending an index (e.g., `_2`)
> * Use descriptive suffixes instead (e.g., `_Personal`, `_Financial`)

> [accordion] Data mapper not working after adding data model
>
> **Possible causes:**
>
> * Input parameters keys don't match process data mapper
> * Data types mismatch
>
> **Solutions:**
>
> * Ensure data mapper keys match input parameters attribute names exactly
> * Verify data types are compatible (string to string, number to number)
> * Check for typos in attribute names
> * Review process data model to workflow data model mapping

> [accordion] Cannot delete entity or attribute
>
> **Error message:** "Entity/Attribute is referenced and cannot be deleted"
>
> **Solution:**
>
> * Check attribute usages using the API: `GET .../attributes/{name}/usages`
> * Remove references from input/output parameters first
> * Update workflow nodes that use the attribute
> * Then retry deletion


# Workflow node reference: control flow and integration nodes
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow

Configure the Start, REST API Call, FlowX Database, Condition, Start and End Parallel, Script, Subworkflow, and End nodes in Integration Designer workflows.

This page describes the control flow and integration nodes you use in [Integration Designer workflows](./integration-workflows). For every node type, see the [workflow nodes overview](./integration-workflows#workflow-nodes-overview).

## Start node

The Start node is the mandatory first node in any workflow. It defines the input data model and passes this data to subsequent nodes.

> [!TIP]
>
> Define all required input fields in the Start node to ensure data mapping from processes or user tasks.

> [!NOTE]
>
> Use [Workflow Data Models](./workflow-data-models) to define structured input and output parameters at the workflow level. Input parameters automatically pre-fill the Start Node from the data model.

### External triggers

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A workflow normally runs when something calls it: a process, a parent workflow, or the run button. Turn on an external trigger and it starts on its own, when a webhook is called or an email arrives.

Open the **Start** node, expand **External Triggers**, switch **Enable trigger** on, then choose **Webhook** or **Email** and pick the data source that receives the event.

![Start node with External Triggers enabled, a webhook data source selected, and the Start payload showing the webhookMessage schema](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/start_node_trigger_example.png)

> [!NOTE]
>
> External triggers are available on Output Focused workflows only. Configuring one on another workflow type is rejected.

> [!NOTE]
>
> To run a workflow on a schedule on SaaS, add a schedule to its Start node. See [How do I run a workflow on a schedule?](#how-do-i-run-a-workflow-on-a-schedule). Self-hosted deployments get workflow schedules with the next LTS release. Until then, create a process with a Timer Start Event and call the workflow from it with a **Start Integration Workflow** action. See [Scheduled processes](../../projects/runtime/scheduled-processes).

**Before you can pick a webhook**, the webhook data source has to be set to **Start a Process/Workflow**. A data source set to **Resume a Waiting Process** is refused, and because Webhook Behavior cannot be changed after the first save, a resume webhook can never be reused here: create a new one. See [Webhook Behavior](./incoming-webhooks#webhook-behavior).

**The event lands in the data model.** Enabling the trigger adds an entity for the incoming event, and turning the trigger off removes it again, so switch it on before mapping anything downstream.

| Trigger | Entity | Contents |
| - | - | - |
| Webhook | `webhookMessage` | `dateTime`, `payload`, `headers` |
| Email | `emailMessage` | See the [email data schema](./email-trigger#email-data-schema) |

`payload` holds the request body as sent, nested structure intact. `headers` holds each header as a **list** of strings, so a single-valued header still arrives as a one-element list.

A script node can then read it directly:

```javascript theme={"dark"}
var msg = input.webhookMessage;
var order = msg.payload;
output.orderSummary = order.client + " wants " + order.suma + " " + order.detalii.moneda;
```

**Activate the trigger** before it accepts anything. Go to **Runtime** → **Manage Triggers** and activate it there. The list also shows how many resources each trigger is bound to.

![Manage Triggers listing webhook triggers with their state and the resources each is used in](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/manage_triggers_5.9.x.png)

> [!WARNING]
>
> One data source can be bound to several workflows, and a single incoming event then starts **all** of them. The Manage Triggers list shows this as a resource count above one. Bind a data source to a second workflow only when you mean to run both.

> [card] [Incoming webhooks](./incoming-webhooks)
>
> Creating a webhook data source, Webhook Behavior, providers, the URL and its API key

> [card] [Email trigger](./email-trigger)
>
> Creating an email trigger data source, filtering, polling, and the email data schema

### How do I run a workflow on a schedule?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Add a schedule to the workflow's **Start** node, then activate it in **Runtime** → **Runtime Settings** → **Schedules**. From then on the workflow starts by itself at each fire time, with no process or caller involved.

Schedules are available on Output Focused workflows. A workflow can have up to 50 schedules, and each one needs a name that is unique on that workflow.

**1. Add a schedule**

Open the **Start** node, expand **Schedules**, and click **Add schedule**. Click the new schedule card to open the **Schedule Workflow** dialog, and give the schedule a **Name**.

**2. Set when it fires**

Choose a **Timer Type**:

* **Date** fires once, at the **Fire at** date and time, entered in your local time.
* **Cycle** fires repeatedly. Pick a **Format**, **ISO** or **Cron**, then build the expression with **Guided** fields or type it under **Expression**.

The dialog previews the next fire times in your local time zone. Check them, then click **Save**.

**3. Activate the schedule**

Go to **Runtime** → **Runtime Settings** → **Schedules**, filter **Origin** by **Workflow**, and click **Activate** on the schedule. The workflow must be part of the project's active build.

> [!WARNING]
>
> Saving a schedule or publishing a build never activates it. A schedule fires only after you activate it on the **Schedules** page.

**Which cycle format should I use?**

| Format | How it fires | Example | Rules |
| - | - | - | - |
| **ISO** | Repeats an ISO 8601 interval a set number of times, or indefinitely | `R5/P1D`: five times, once a day | The interval must be longer than zero, in whole seconds. A **Start Time**, if you set one, must be in the future. |
| **Cron** | Fires on a six-field cron schedule: second, minute, hour, day of month, month, day of week | `0 */5 * * * ?`: every five minutes | Cron is read in UTC. Set an **Active window** with a **Start** and an **End**: the schedule fires only between them. Macros such as `@daily` and `@hourly` also work. |

**What does a scheduled run receive?** A scheduled run doesn't use the Start node's test payload. Its input holds three fields that you can map like any other input:

| Field | Contents |
| - | - |
| `firedAt` | When the run actually started, as an ISO 8601 timestamp |
| `scheduledFor` | When the schedule was due, as an ISO 8601 timestamp |
| `triggerName` | The name of the schedule that started the run |

**Where do scheduled runs show up?** In [Workflow Instances](../../projects/runtime/workflow-instances), with the origin **Schedule**. The run details name the schedule that started it.

**How do I stop a schedule?** To pause it, click **Deactivate** on the **Schedules** page, and click **Activate** to resume it. To remove it for good, delete it from its card on the **Start** node. A deleted schedule stops firing immediately, and the deletion can't be undone.

***

## REST API Call node

Enables communication with external systems via REST API calls. Supports GET, POST, PUT, PATCH, and DELETE methods. Endpoints are selected from a dropdown, grouped by system.

* **Params**: Configure path, query, and header parameters.
* **Input/Output**: Input is auto-populated from the previous node; output displays the API response.

> [!TIP]
>
> You can test REST API Call nodes independently to validate connections and data retrieval.

### When does a REST API Call node take its failure exit?

A REST API Call node has a success exit and a failure exit. It takes the success exit only for a `2xx` response without errors. Everything else takes the failure exit:

* a non-`2xx` response;
* a timeout, stored as status `408` with `data.timeout: true` (set the limit with **Timeout** on the node's **Settings** tab, default `10000` ms);
* a connection error;
* a response body declared as JSON or XML that can't be parsed.

With **Allow Retry** on, a `408`, `429`, `500`, `502`, `503`, or `504` is retried first, and the node takes the failure exit only once the retries are used up.

> [!WARNING]
>
> If the call fails and the failure exit isn't connected, the workflow instance fails with `Workflow is missing outgoing sequence.` It doesn't fall through to the success exit.

On both exits the node writes its result under its response key: `data` (the parsed body), `metadata` (`statusCode` and `headers`), `hasError` and `errorMessage`. `hasError` only flags connection and parsing errors: a `4xx` or `5xx` with a readable body has `hasError: false` even though the node took the failure exit, and on a timeout it isn't set. To branch on the outcome, use the exits or `metadata.statusCode`, not `hasError`.

Errors while building the request, such as a failed input mapping or a missing endpoint, don't use the failure exit. They fail the workflow instance.

***

## FlowX database node

Allows you to read and write data to the FlowX Database within your workflow.

> [card] [FlowX Database Documentation](./flowx-database)
>
> Learn more about FlowX Database operations, collections, and usage

***

## Condition (Fork) node

Evaluates logical conditions (JavaScript or Python) to direct workflow execution along different branches.

* **If/Else**: Routes based on condition evaluation.
* **One branch per run**: The node follows the first branch whose condition passes, or the Else branch. To run branches at the same time, use the [Start Parallel and End Parallel nodes](#start-parallel-and-end-parallel-nodes).

> [!NOTE]
>
> Use fork nodes to implement business rules, error handling, or multi-path logic.

### Available bindings

Condition expressions have access to the following data bindings:

| Binding | Description |
| - | - |
| `input` | Workflow input data from the previous node |
| `additionalData.securityDetails` | Current user's identity (username, identifier, details including roles, groups, and attributes from 5.7.0 onward) |
| `additionalData.applicationConfiguration` | Configuration parameters from the app build |

### Condition examples

> [tab] JavaScript
>
> ```javascript theme={"dark"}
> // Route based on user identity
> additionalData.securityDetails.username === 'admin@company.com'
>
> // Route based on configuration parameter
> additionalData.applicationConfiguration.featureEnabled === true
>
> // Combine input data with config parameters
> input.amount > additionalData.applicationConfiguration.approvalThreshold
>
> // Check user and input together
> input.priority === 'high' && additionalData.securityDetails.details.email.endsWith('@company.com')
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # Route based on user identity
> additionalData["securityDetails"]["username"] == "admin@company.com"
>
> # Route based on configuration parameter
> additionalData["applicationConfiguration"]["featureEnabled"] == True
>
> # Combine input data with config parameters
> input["amount"] > additionalData["applicationConfiguration"]["approvalThreshold"]
>
> # Check user and input together
> input["priority"] == "high" and additionalData["securityDetails"]["details"]["email"].endswith("@company.com")
> ```

> [!TIP]
>
> For details on the `securityDetails` and `applicationConfiguration` structure, see [Extracting additional data in business rules](../../building-blocks/actions/business-rule-action/extracting-additional-data).

### Calling reusable functions in conditions

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Condition expressions can call the [reusable functions](../../building-blocks/reusable-resources/reusable-functions) defined in your project, so branch routing can reuse the same business logic as your processes. Call a function inside a condition using the standard syntax:

> [tab] JavaScript
>
> ```javascript theme={"dark"}
> // Route on the result of a reusable function
> functions.lending.isEligible(input.applicant) === true
> ```

> [tab] Python
>
> ```python theme={"dark"}
> # Route on the result of a reusable function
> functions.lending.isEligible(input["applicant"]) == True
> ```

Each branch condition can call functions, and the node resolves the functions referenced across all of its branches together. Resolution follows the same rules as the Script node: calls resolve from the workflow's build, a function that calls another function resolves its full call chain, and cross-app calls are matched by app name.

> [!WARNING]
>
> As with Script nodes, reusable functions resolve only in a build context. A draft or test run with no build resolves no functions.

***

## Start Parallel and End Parallel nodes

Run several steps of a workflow at the same time with a pair of nodes: **Start Parallel** splits the flow into branches that all run at once, and **End Parallel** waits for every branch, merges what the branches wrote, and continues. In the node palette they sit under **Flow Control** as **Start Parallel Path** and **End Parallel Path**. Dropped on the canvas, they are named **Start Parallel** and **End Parallel**.

These nodes are the only way to run branches concurrently. A [Condition (Fork) node](#condition-fork-node) evaluates its conditions and follows one branch.

<video />

### How do I run steps in parallel?

**1. Add a Start Parallel node**

Drag **Start Parallel Path** from the **Flow Control** group onto the canvas and connect the previous node to it.

**2. Create one sequence per branch**

Draw a sequence from the Start Parallel node to the first node of each branch. Every outgoing sequence is a branch. A branch needs at least one node: the Designer does not let you connect a Start Parallel node straight to an End Parallel or End Flow node.

**3. Build each branch**

Add the nodes each branch needs: REST endpoints, scripts, FlowX Database operations, AI nodes, subworkflows, or another Start Parallel node for nested branches.

**4. Close every branch on the same End Parallel node**

Connect the last node of every branch to one **End Parallel Path** node, then connect that node to whatever comes next. An End Parallel node allows a single outgoing sequence.

At runtime all branches run concurrently. The End Parallel node completes when the slowest branch reaches it, so the branch section takes as long as its longest branch, not the sum of the branches.

### What data does each branch see?

Each branch starts with a **deep copy** of the workflow data as it was when the Start Parallel node ran. Branches work on independent copies: a branch cannot read what another branch writes while they run.

### How are the branches merged?

When a branch reaches the End Parallel node, the keys that branch wrote are merged into the parent data with a recursive deep merge, in the order the branches finish:

* Keys written by only one branch are kept.
* A key written by two branches ends up with the value from the branch that finished last.
* Nested objects are merged key by key, so only the conflicting leaf values are overwritten.
* Arrays and all other non-object values are replaced whole. There is no element-level merge, so two branches cannot each fill a different element of the same array.

Because the merge order depends on which branch finishes last, two branches that write the same key give a non-deterministic result.

> [!TIP]
>
> Have each branch write to its own key, for example `apiResultA`, `apiResultB` and `apiResultC`, and combine them in a Script node after the End Parallel node.

### What happens when a branch fails?

* A node that fails inside a branch follows the same rules as anywhere else in the workflow. If its failure exit is connected, the branch continues on that path and must still reach the End Parallel node. If the failure exit is not connected, the workflow instance fails.
* When the instance fails, the other branches stop at the next node they reach. Nothing they already executed is rolled back.
* If the branches of one Start Parallel node end on different End Parallel nodes, or one End Parallel node receives branches from two different Start Parallel nodes, the run fails with `Missing end parallel gateway` and the cause `Parallel branches merge failed: missing or incompatible end parallel node.`
* A Start Parallel node with no outgoing sequence fails the run with `Workflow is missing outgoing sequences.`

### Runtime view

> [accordion] Console logging
>
> * **Start Parallel node**: the Input tab shows the data handed to the branches.
> * **End Parallel node**: the Output tab shows the merged result of all branches.
> * **Path grouping**: the nodes of each branch are grouped by path, so you can follow one branch at a time.

> [accordion] Path timing
>
> * **Path time**: sum of the execution times of the nodes in that branch.
> * **End Parallel time**: the node's own processing time plus the longest path time.
> * **Example**: if branch A takes 2s and branch B takes 5s, the End Parallel node completes after 5s plus its own processing time.

### Use cases

> [card] Multiple API calls
>
> Call several independent APIs at once instead of one after the other.

> [card] Data enrichment
>
> Fetch data from several sources in parallel and combine it afterwards.

> [card] Notification broadcasting
>
> Send notifications through several channels (email, SMS, push) at the same time.

> [card] Document processing
>
> Process different document types or sections in parallel.

### Limitations

* **Same End Parallel node for all branches**: every branch of a Start Parallel node must end on the same End Parallel node, and that node allows one outgoing sequence.
* **Last-write-wins merge**: write to distinct keys per branch and combine them in a Script node afterwards.
* **No element-level array merge**: you cannot process the first element of an array in one branch and the second in another.
* **No cross-branch reads**: branches run on independent data copies and cannot see each other's writes until the merge.
* **Nesting is allowed**: a branch can contain its own Start Parallel and End Parallel pair.

***

## Script node

Executes custom JavaScript or Python code to transform, map, or enrich data between nodes.

The node's `output` is merged into the workflow data, the same way business rule output is merged into process data: keys the script doesn't write keep their values, and writing `{}` to an existing object changes nothing. To clear a key, set it to `null`. For the full merge rules, see [How output is merged into process data](../../building-blocks/supported-scripts#how-output-is-merged-into-process-data).

### Calling reusable functions

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A Script node can call the [reusable functions](../../building-blocks/reusable-resources/reusable-functions) defined in your project, the same way a process Business Rule action does. Write the call directly in the node's code using the standard syntax:

```javascript theme={"dark"}
functions.projectName.functionName(input.params)
```

The Designer reads the function calls from your script and links the node to those functions automatically, so there is no separate step to register a reference. The linked functions also appear on each function's **Usages** tab, and removing the node clears those usage entries.&#x20;

Function calls resolve from the app version that the workflow runs in, and a function that calls another function resolves its full call chain. Functions defined in a different app are matched by their app name, so cross-app calls work the same way they do in processes.

> [!WARNING]
>
> Reusable functions resolve only in a build context. The Script node's **Test** modal resolves them when you run it against a selected build; a draft or preview run with no build in context resolves no functions, so calls to `functions.*` return no result until a build is selected.

### Testing a script in isolation

A Script node ships with a **Test modal** that lets you exercise the script against sample input without running the full workflow. Open it with the **expand** icon at the top-right corner of the code editor, next to the expand/collapse chevron.

The modal has three side-by-side panels:

| Panel | Purpose |
| - | - |
| **Input** | JSON input passed to the script. Load from a past individual node run or from a past workflow run via the input selector. |
| **Code** | The script body. Inline warnings are surfaced as you type. Includes **Save** and **Test** buttons. |
| **Output** | The JSON returned by the script after running **Test**. Runtime errors are shown here. |

> [!TIP]
>
> The **Test** button runs the current contents of the Code panel, even if you have not clicked **Save** yet. Use this to iterate on a fix without committing changes to the Script node.

> [!NOTE]
>
> Runs triggered from the Test modal are excluded from the Console log History panel, because they may be running unsaved code.

### Run instance IDs in the Logs tab

The Logs tab of a workflow run displays the **node run instance ID** alongside the workflow instance ID for each Script node execution. A copy button is rendered next to every instance ID. Use this to grab a node-run identifier and paste it into the Test modal's input selector to replay the exact past run.

***

## Subworkflow node

The Subworkflow node allows you to modularize complex workflows by invoking other workflows as reusable subcomponents. This approach simplifies process design, promotes reuse, and simplifies maintenance.

**1. Add a Subworkflow Node**

Select **Start Subworkflow** from the **Select Next Node** dropdown. Choose from workflows categorized as **Local** or **Libraries**.

**2. Configure the Subworkflow Node**

* **Workflow Selection**: Pick the workflow to invoke.
* **Open**: Edit the subworkflow in a new tab.
* **Preview**: View the workflow canvas in a popup.
* **Response Key**: Set a key (e.g., `response_key`) for output.
* **Input**: Provide input in JSON format.
* **Output**: Output is read-only JSON after execution.

### Data mapping

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

By default, a Subworkflow node forwards the whole parent context to the subworkflow and nests the result under the response key. **Data mapping** lets you instead pass only selected fields into the subworkflow and land its results directly into named parent variables, using visual input and output mappers rather than raw JSON.

In the node config panel, expand **Data mapping** and turn **Enable data mapping** on.

![Subworkflow node config with Enable data mapping turned on, showing the Start input mapping row and an End Flow output mapping row](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/subworkflow-data-mapping-toggle.png)

> [!NOTE]
>
> When data mapping is off, the node keeps its original behavior: the **Input** and read-only **Output** JSON fields described above. Turning **Enable data mapping** on replaces those with the mappers below.

When data mapping is on, the node exposes two mappers, driven by the subworkflow's own start and end nodes:

| Mapper | Helper text | Defined per | How it is labeled |
| - | - | - | - |
| **Input mapping** | Variables sent by the main workflow | The subworkflow start node | A single row labeled **Start** |
| **Output mapping** | Variables received by the main workflow | Each subworkflow end node | One row per end node, labeled with the end node's name |

![Input mapping and Output mapping sections on the Subworkflow node, with the input mapping helper tooltip open](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/subworkflow-input-output-mapping-rows.png)

> [!NOTE]
>
> Output mapping applies only to synchronous subworkflows. If the subworkflow runs asynchronously, the parent does not wait for a result, so the **Output mapping** block is hidden.

Each row opens a mapper modal. Use it to draw field-to-field mappings between the data models, then check the result before saving.

**1. Open the mapper**

Click the edit icon on the **Start** row (input) or on an end-node row (output).

**2. Map fields between the two data models**

The modal shows the source data model on the left and the target data model in the middle. Each side is color-coded: **Project Data Model** and **Workflow Data Model**. Draw the field-to-field mappings, or define static values and expression scripts where a direct field match does not exist.

**3. Test the mapping**

Click **Test** to run the current mappings and preview the produced payload in the read-only results panel on the right. Any mapping errors are highlighted so you can correct them before saving.

**4. Apply values from a past run (optional)**

To test against real data, pick a previous workflow instance from **Past Instances Variables** and click **Apply** to load that instance's values as the source example. Use the reset control to return to the default example values.

**5. Save**

Click **Save** to store the mapping on the node. In committed or upper environments the modal is read-only and shows **Close** instead.

![Input mapping modal with the parent workflow variables on the left, mapped subworkflow fields in the middle, and the Test preview payload on the right](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/subworkflow-data-mapping-modal.png)

> [!TIP]
>
> Data mapping keeps the subworkflow's contract explicit: the parent passes exactly the fields the subworkflow needs, and only the mapped results flow back. This is easier to maintain than forwarding the entire context and reading everything back through the response key.

**Import, export, and clone**

Subworkflow mappings are stored as part of the workflow definition, so they travel with the node when the workflow is exported, imported, or cloned.

> [!WARNING]
>
> On upgrade, existing Subworkflow nodes keep data mapping turned **off**, so they continue to behave exactly as before. Turn **Enable data mapping** on per node to adopt the mappers.

> [!TIP]
>
> Use subworkflows for reusable logic such as data enrichment, validation, or external system calls.

### Parallel multi-instance

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A Subworkflow node normally runs the child workflow once. Turn on **Parallel Multi-Instance** to run it once for every element of an array instead, in parallel, and collect the results back into a second array.

This keeps fan-out inside the Integration Designer. Previously, running a workflow once per item meant wrapping it in a process and fanning out with a multi-instance Call Activity.

In the node config panel, expand **Execution** and turn **Parallel Multi-Instance** on.

![Execution section on the Subworkflow node with Parallel Multi-Instance turned on and Enable Data Mapping locked on, showing the required Input Array and Output Array selectors](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/subworkflow-execution-parallel-multi-instance.png)

> [!NOTE]
>
> Turning **Parallel Multi-Instance** on also turns **Enable Data Mapping** on and locks it there, because each array element has to be mapped into the child workflow individually. The [data mapping](#data-mapping) mappers stay available and work the same way.

Then set the two arrays:

| Setting | Where | Required | What it does |
| - | - | - | - |
| **Input Array** | Input Mapping | Yes | The array of objects to iterate. One subworkflow instance starts per element. |
| **Output Array** | Output Mapping | Yes | The array each instance's result is collected into. |
| **Correlation attribute** | Output Mapping | No | Decides which output array element each result updates. |

Only array attributes from the workflow data model can be selected, and both arrays must be arrays of objects. If a dropdown offers nothing, the workflow data model has no array attributes to choose from.

![Subworkflow node with the Input Array, Output Array, and Correlation attribute selectors filled with array attributes from the workflow data model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/subworkflow-input-output-array-selectors.png)

**How results land**

The correlation attribute behaves as an upsert key rather than a strict join:

* A result whose correlation value matches an existing element of the output array updates that element.
* A result that matches no element is appended.
* With no correlation attribute set, every result is appended.

Correlation candidates are the primitive fields of the output array's element, so pick the output array first. Until you do, the **Correlation attribute** selector stays empty.

If the merge fails, the still-running instances are cancelled and the output array is emptied. See [Routing a subworkflow failure](#routing-a-subworkflow-failure).

> [!TIP]
>
> Point the input and output arrays at different data model attributes. Reusing one array as both the source and the target makes the upsert behavior hard to reason about.
>
> Each instance runs the same subworkflow against one element, so if you need per-element branching, put it inside the child workflow rather than around the Subworkflow node.

> [!NOTE]
>
> **Parallel multi-instance is not the same as [parallel branches](#start-parallel-and-end-parallel-nodes).** Start Parallel and End Parallel nodes run several *different* branches of one workflow at the same time. Parallel multi-instance runs *one* subworkflow many times, once per element of an array. Use parallel branches for different work in parallel, and multi-instance for the same work over a collection.

### Execution logic and error handling

* Parent workflow waits for subworkflow completion before proceeding.
* If the subworkflow fails, the parent workflow halts at this node. On SaaS (5.12), connecting the node's failure exit routes the failure down its own branch instead. See [Routing a subworkflow failure](#routing-a-subworkflow-failure).
* Subworkflow output is available to downstream nodes via the response key.
* Logs include workflow name, instance ID, and node statuses for both parent and subworkflow.

> [!WARNING]
>
> If a subworkflow is deleted, an error displays: `[name] subworkflow not found.`

> [!TIP]
>
> Subworkflow runs are recorded in workflow instance history for traceability.

### Routing a subworkflow failure

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A Subworkflow node has two exits, drawn as a green connector for success and a red one for failure. Connect the red exit to send a failed run down its own branch instead of stopping the parent workflow.

This is opt-in per node. A node whose red exit is not connected fails and blocks exactly as it did before, and nothing is changed for existing workflows.

Only a **mapping** failure is routed, because that is the kind of failure a workflow can be built to handle: the same workflow succeeds for records that carry the right fields.

| Routed down the failure exit | Still stops the workflow |
| - | - |
| The input mapper fails | No subworkflow is set on the node |
| The input it produced does not satisfy what the subworkflow expects | The response key is missing |
| The output mapper fails when merging the result back | The node has no mapping configured at all |
| | The run hits the maximum node or subworkflow-depth limit |

On the failure branch, the node writes a fixed **`subWorkflowError`** key, separate from its response key:

| Field | Description |
| - | - |
| `hasError` | Always `true`. It exists so a branch reads the same shape here as on other node types. |
| `errorMessage` | For example, `The input of subworkflow node [name] could not be mapped, so no subworkflow was started.` |
| `errorType` | `INPUT_MAPPING` or `OUTPUT_MAPPING`, so a branch can tell a child that never started from one that ran and could not be merged back. |
| `childInstanceUuid` | The run whose result could not be mapped back. Left out entirely when no child was started. |

> [!NOTE]
>
> The failure exit covers the node's own mapping. A subworkflow that fails **inside itself** still cascades to the parent, whether or not the failure exit is connected.
>
> A manual single-node run also reports the error to you rather than following the branch.

> [!WARNING]
>
> On a [parallel multi-instance](#parallel-multi-instance) node, a merge failure cancels the sibling instances that are still running and empties the output array before taking the failure branch, so the branch never reads a half-filled list.

### Console logging, navigation, and read-only mode

* Console shows input/output, workflow name, and instance ID for each subworkflow run.
* Open subworkflow in a new tab for debugging from the console.
* Breadcrumbs enable navigation between parent and subworkflow details.
* In committed/upper environments, subworkflow configuration is read-only and node runs are disabled (preview/open only).

> [!NOTE]
>
> Subworkflow instances are logged in history, and you can navigate between parent and child workflow runs for comprehensive debugging.

### Use case: CRM Data Retrieval with subworkflows

Suppose you need to retrieve CRM details in a subworkflow and use the output for further actions in the parent workflow.

**1. Create the Subworkflow**

Design a workflow that connects to your CRM system, fetches user details, and outputs the data in a structured JSON format.

**2. Add a Subworkflow Node in the Parent Workflow**

In your main workflow, add a Subworkflow Node and select the CRM retrieval workflow. Map any required input parameters.

**3. Use Subworkflow Output in Parent Workflow**

Downstream nodes in the parent workflow can reference the subworkflow's output using the defined `responseKey`.

```json theme={"dark"}
{
  "crmData": "${responseKey}"
}
```

**4. Monitor and Debug**

Use the console to view input/output data, workflow names, and instance IDs. Open subworkflow runs in new tabs for detailed debugging.

> [!NOTE]
>
> This modular approach allows you to build scalable, maintainable integrations by composing workflows from reusable building blocks.

***

## End node

The End node signifies the termination of a workflow's execution. It collects the final output and completes the workflow process.

* Receives input in JSON format from the previous node.
* Output represents the final data model of the workflow.
* Multiple End nodes are allowed for different execution paths.

> [!NOTE]
>
> If the node's output doesn't meet mandatory requirements, it will be flagged as an error to ensure all necessary data is included. Output parameters declared in the workflow's output schema are a runtime contract: when any of them resolves to no value, the run fails with `The mandatory output parameters of the <workflow> workflow are missing at runtime` - see the [error glossary](/5.9/docs/resources/error-glossary#the-mandatory-output-parameters-of-the-workflow-are-missing-at-runtime).

> [!WARNING]
>
> A placeholder that doesn't resolve fails **silently** on an End node: the output field is set to `null`, and the only error you see is the mandatory-output failure above. When mapping an End node output:
>
> * Use the bare key with no prefix: `${responseKey.data}`, not `${output.value}` or `${input.responseKey.data}`.
> * Check the spelling against the Response Key configured on the REST node - the response body lives under `<responseKey>.data`.
> * Leave the placeholder unquoted for numeric or boolean values; quote it (`"${key}"`) only for strings.
>
> To confirm what an End node actually produced, open the node in the workflow run details: it shows the exact input it received and the output JSON it emitted.


# Workflow node reference: data, document, and AI nodes
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai

Configure workflow nodes that parse and generate tabular files, fill templates, send notifications, merge or split PDFs, retrieve context, and run AI agents.

This page describes the data, document, and AI nodes you use in [Integration Designer workflows](./integration-workflows). For every node type, see the [workflow nodes overview](./integration-workflows#workflow-nodes-overview).

## Tabular Data Extraction node

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Reads a CSV or spreadsheet file and returns its rows as structured JSON, so extracted data can drive conditions, script logic, and data operations downstream. Available under **Tools** in the workflow node palette.

**Configuration:**

* **Use Test File** — toggles where the file comes from. **OFF**: provide **File Path**, the download path of a file available at run time (for example, produced by a previous node or a file upload); supports `${}` expressions. **ON**: select an uploaded test file — useful while building and testing the workflow
* **Sheet** (Excel only) — the sheet name to extract from; leave empty to use the first sheet
* **Response Key** — where the node writes its output; the extracted rows are stored under `<responseKey>.data`

**Supported files:** CSV, XLS, and XLSX, up to 15 MB for test-file uploads.

Each row becomes a JSON object keyed by the header row (the file's first row), with every value returned as a **string**. For a file with columns `id`, `name`, and `role` and response key `rows`:

```json theme={"dark"}
{
  "rows": {
    "data": [
      { "id": "1", "name": "Alice", "role": "Engineer" },
      { "id": "2", "name": "Bob", "role": "Designer" }
    ]
  }
}
```

> [!NOTE]
>
> The node outputs data, not a file — its result cannot be passed to the file-manipulation nodes (Combine Files, Split File). To extract structured data from unstructured documents such as PDFs or images, use the **Extract Data from File** AI node instead.

If extraction fails (missing file, unknown sheet name, or an unsupported format), an `error` object is returned on the same key. An empty file returns an empty `data` array.

### Data Parse: XML and JSON support

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The node appears in the **Tools** palette as **Data Parse**, described as "Parse CSV, spreadsheet, XML or JSON files into structured JSON." Workflows that already use the node keep working: the node type and its configuration fields are unchanged.

* **Accepted files**: CSV, XLS, XLSX, and XLSM spreadsheets, plus **XML** and **JSON** files. Test file uploads are still capped at 15 MB. Uploaded XML and JSON test files are listed with the **Structured Data** type.
* **Sheet**: applies to Excel files only (`.xls`, `.xlsx`, `.xlsm`) and is ignored for CSV, XML, and JSON.
* **Output**: always under `<responseKey>.data`. Spreadsheets return rows as described above. XML and JSON files return an object tree.
* **Size and depth limits**: XML and JSON files are parsed up to 5 MB. XML nested deeper than 64 levels is rejected.

A **JSON** file is returned as it is, once the node has checked that it holds a single well-formed JSON document.

An **XML** file is converted with these rules:

* The root element is unwrapped: `data` holds its content, not an object keyed by the root name.
* An element with only text becomes a string. An empty element becomes an empty string.
* Attributes become keys. When an element has both attributes and text, the text is stored under `value`.
* Sibling elements with the same name become an array. A single occurrence stays an object, so plan for both shapes when the count can vary.
* Namespaces are dropped and only local names are kept. All values are strings.
* Document type definitions (DTDs) and external entities are not processed.

For this file and response key `customers`:

```xml theme={"dark"}
<customers>
  <customer id="1">
    <name>Alice</name>
    <role>Engineer</role>
  </customer>
  <customer id="2">
    <name>Bob</name>
    <role>Designer</role>
  </customer>
</customers>
```

the node returns:

```json theme={"dark"}
{
  "customers": {
    "data": {
      "customer": [
        { "id": "1", "name": "Alice", "role": "Engineer" },
        { "id": "2", "name": "Bob", "role": "Designer" }
      ]
    }
  }
}
```

A file downloaded by a **File Storage Operation** node can be parsed too. Its format is recognized from the file name, so keep the extension (for example, `.xml` or `.json`) on the stored file. Malformed XML or JSON, a file over the size limit, or XML nested too deeply makes the node run fail with an error message.

***

## Generate Tabular File node

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Turns workflow data into a CSV or XLSX file and stores it as a document linked to the current workflow run, so a workflow can produce an export without a Script node. Available under **Tools** in the workflow node palette.

**Configuration:**

* **File name**: the name of the generated file, up to 255 characters; supports `${}` expressions (for example, `${reportDate}`). The extension is added from **Format**, so a typed `.csv`, `.xlsx`, or `.xls` extension is replaced. The characters `\ / : * ? " < > |` are replaced with `_`.
* **Document Tag** (optional): the tag stored on the generated document; supports `${}` expressions. When left empty, the file name without its extension is used.
* **Format**: `CSV` (default) or `XLSX`.
* **Row format**: the shape of each row in **Data**.
  * **Arrays** (default): each row is a list of values, such as `["FP-1001", "Closed"]`. The first row is the header row, and each following row is written in the same column order.
  * **Objects**: each row is an object, such as `{"invoice": "FP-1001", "status": "Closed"}`. The keys become the column headers, in the order they first appear. A missing key leaves the cell empty.
* **Data**: a single workflow variable that holds the rows, such as `${data}` or `${dbResult.sheets}`. The variable must resolve to an array; inline JSON is not accepted.
* **Response Key**: where the node writes the generated file's metadata.

For a `${employees}` variable set to:

```json theme={"dark"}
[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob", "role": "Designer" }
]
```

with **Row format** set to **Objects**, **Format** set to `CSV`, **File name** set to `team-export`, and response key `export`, the node writes a CSV file with the columns `id`, `name`, and `role`, and returns:

```json theme={"dark"}
{
  "export": {
    "fileName": "team-export.csv",
    "documentType": "team-export",
    "format": "CSV",
    "rowFormat": "objects",
    "rowCount": 2,
    "fileSize": 40,
    "downloadPath": "internal/files/{fileEntryUuid}/download",
    "filePath": "...",
    "fileEntryUuid": "..."
  }
}
```

`rowCount` counts data rows only, never the header row, and `fileSize` is in bytes. The generated file also appears in the **Document** tab of the run's console log.

**How values are written:**

* CSV files are UTF-8 encoded with a byte order mark, so spreadsheet apps read non-ASCII characters correctly. XLSX files have a single sheet named `Sheet1`, and numbers and booleans keep their type.
* Text that starts with `=`, `+`, `-`, `@`, a tab, or a carriage return is written as text, never as a formula.
* In **Arrays** mode, a row shorter than the header row is padded with empty cells, and extra values become extra columns with an empty header.
* Rows with no values are left out. An empty array still produces a file, with `rowCount` set to `0`.

**Limits:** an XLSX file holds up to 1,048,576 rows, including the header row. A generated file can be up to 50 MB.

The node run fails with an error message in the run log when **Data** is not mapped, is not a single variable reference, or does not resolve to an array; when a row does not match the selected **Row format**; when **File name** or **Document Tag** references a variable that has no value; or when the file exceeds a limit. Reduce the number of rows or split the export across several nodes to stay under the limits.

***

## Template Filling node

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Generates a document from a document template populated with workflow data. Available under **Tools** in the workflow node palette.

**Configuration:**

* **Template** — select a document template defined in your project's **Document templates**; **Open template** jumps to the template definition
* **Language** — enabled once a template is selected, and defaults to the template's first available language
* **Template Variables** — click **Configure Variables** to fill the template's data-model variables with values from the workflow; changing the template resets the language and variables
* **Input Mapping** — on SaaS (5.13), new nodes map workflow data onto the template's input parameters in the data mapper (**Configure mapping** on the **Template Input** card) instead of **Template Variables**. Nodes created earlier show an **Enable data mapping** toggle: on uses the data mapper, off keeps **Template Variables**
* **Folder** — optional folder for the generated file; supports `${}` expressions (e.g., `${client.id}`)
* **Document Tag** — the tag under which the generated document is stored (e.g., `ContractTemplate`)
* **Document format** — **PDF** (default) or **DOCX**

The node writes the generation result to its response key, including the file ID, storage and download paths, document tag, and page count. If generation fails, an `error` object is returned on the same key.

To map a Script node's output into the template, fix a node that shows no mapping options, or build the download URL from `downloadPath`, see [Fill a document template from a workflow and download it](/5.9/cookbooks/generate-and-download-a-document).

> [card] [Managing document templates](../core-extensions/content-management/documents-plugin/managing-html-templates)
>
> Learn how to create and manage the document templates this node fills

***

## Send Notification node

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Sends a notification built from one of your project's notification templates, directly from a workflow. Available under **Tools** in the workflow node palette. Until now this took a round trip through a process: the workflow had no way to reach the Notifications plugin on its own.

**Configuration:**

* **Template** — the notification template to send, from your project's notification templates; **Open notification template** jumps to its definition. **Language** unlocks once a template is picked. **Variables** fills the template's data-model variables from workflow data, the same mapping as the Template Filling node.
* **Recipients** — **To** (required), **Cc** and **Bcc**. Each takes a recipient address, a JSON array of addresses, or a `${}` expression resolving to either.
* **Email options** — all optional: **Subject override** (leave empty to use the template subject), **Sender name** and **Sender email**, **Attachments** (one file path or `${}` key per line), and **Custom headers**, which must be a JSON object or a `${}` expression that resolves to one.

### When does a Send Notification node take its failure exit?

A Send Notification node has a success exit and a failure exit. It takes the success exit only when the Notifications plugin accepts the message with a `2xx` response. Everything else takes the failure exit:

* A configuration problem caught before sending, such as no template or language, an empty **To** after `${}` expressions resolve, an attachment given as a URL instead of a file path, or custom headers that aren't valid JSON
* The Notifications plugin rejecting the message
* An authorization error (`401` or `403`)
* The plugin being unreachable, timing out, or answering with a `5xx`

If the node fails and the failure exit isn't connected, the workflow instance fails with `Workflow is missing outgoing sequences.` It doesn't fall through to the success exit.

On both exits the node writes its result under its response key: `sent`, `hasError`, `errorType`, `errorMessage`, `template` (name and ID), `language`, `recipients` (`to`, `cc`, and `bcc` counts), and `metadata.statusCode`. `errorType` is `VALIDATION` (caught before sending), `DELIVERY` (rejected by the plugin), `AUTH`, or `TRANSPORT`. `metadata` is absent for `VALIDATION` and `TRANSPORT`, because no status code reached the node.

> [card] [Managing notification templates](../core-extensions/content-management/notifications-plugin/managing-notification-templates)
>
> Learn how to create and manage the notification templates this node sends

***

## Combine Files node

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Merges multiple **PDF** files into a single output file, in the order you specify. Available under **Tools** in the workflow node palette.

**Configuration:**

* **Files** — add two or more source files, each by path (or a test file). Set the **order** and choose which pages to include per file: **All pages** or a **custom** page range.
* **Folder** — optional folder for the combined file; supports `${}` expressions.
* **Document Tag** — the tag under which the combined file is stored.

Each input must be a PDF of up to 15 MB, and at least two files are required. The node writes the combined file's ID and paths to its response key.

***

## Split File node

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Splits a single **PDF** into multiple output files — by page ranges or one file per page. Available under **Tools** in the workflow node palette.

**Configuration:**

* **Source file** — the PDF to split, by path (or a test file).
* **Output files** — define each output by its **pages** using a range grammar such as `1-3,5`, or a `${}` expression that resolves to one at runtime. Each output can set its own **Folder** and **Document Tag**.

The source must be a PDF of up to 15 MB. The node writes the resulting files' IDs and paths to its response key.

***

## Context Retrieval node

Retrieves relevant data from Knowledge Bases or conversation memory using semantic and keyword search, without calling an LLM, and passes the chunks to downstream nodes. Available under **Data Operations** in the workflow node palette.

**Configuration:**

* **Source** — choose between Knowledge Base or Memory (Memory is available only in chat-driven workflows)
* **Knowledge Base** — select a Knowledge Base to search (when source is Knowledge Base)
* **User Query** — the search query, supports process variable expressions (e.g., `${userMessage}`)
* **Search Type** — Hybrid (default), Semantic, or Keywords
* **Max Number of Chunks** — how many chunks to return (1-10, default: 5)
* **Min Relevance Score** — minimum relevance threshold (0-100%, default: 70%)
* **Metadata Filters** — filter chunks by metadata properties using the query builder: typed operators per key type and AND/OR grouping
* **Use advance metadata filters** — toggle to enable expression-based filtering for complex logic
* **Use Re-rank** — toggle to re-rank retrieved chunks before returning

The node returns structured chunk data: content, metadata, relevance score, and store.

**Common use cases:**

* Feeding context into a downstream Custom Agent or Text Generation node
* Building multi-step RAG pipelines with custom processing between retrieval and generation
* Retrieving relevant documentation chunks for further analysis

> [card] [Context Retrieval Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
>
> Learn how to configure Context Retrieval nodes, search types, and output format

> [card] [Using Knowledge Base in Workflows](./knowledge-base-integration/using-knowledge-base-in-workflows)
>
> Learn how to configure Context Retrieval and Custom Agent nodes with Knowledge Bases

***

## Custom Agent node

Enables AI agents to perform intelligent, autonomous tasks using Model Context Protocol (MCP) tools within your workflow. Custom Agent nodes apply ReAct (Reasoning and Acting) to decide which tools to use and execute multi-step operations.

**Key capabilities:**

* Access external systems through MCP servers
* Execute complex, multi-step operations autonomously
* Make intelligent decisions based on available tools
* Return structured responses for downstream processing

**Use cases:**

* Customer support automation with CRM integration
* Data analysis across multiple systems
* Dynamic integration orchestration
* Autonomous problem-solving workflows

> [card] [Custom Agent Node Documentation](./custom-agent-node)
>
> Learn how to configure Custom Agent nodes, write effective prompts, and monitor AI agent execution

***

## Intent Classification Agent node

Classifies user messages using an LLM and automatically routes the workflow to the matching intent branch — combining AI classification and conditional branching in a single node. Works like a [Condition (Fork)](./workflow-nodes-control-flow#condition-fork-node) node, but uses natural language intent descriptions instead of code expressions.

**Key capabilities:**

* Define up to 10 intents as plain-text descriptions
* Automatic "If No Intent Matches" fallback branch
* Optional conversation memory for context-aware classification
* Optional rationale output explaining the classification decision

**Common use cases:**

* Chatbot message routing
* Email triage and classification
* Customer support ticket categorization

> [card] [Intent Classification Agent Documentation](/5.9/ai-platform/agent-builder/intent-classification)
>
> Learn how to configure intents, output format, and routing behavior

***

## AI Nodes

AI nodes enable intelligent processing of text, documents, images, and data directly within your Integration Designer workflows.

![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)

### AI Text Operations

| Node | Description |
| - | - |
| **Text Transformation** | Modify text tone, complexity or formatting for better clarity or style |
| **Text Understanding** | Analyze text to determine sentiment, topics, intent, language and named entities |
| **Text Generation** | Generate new text such as summaries, completions, translations or paraphrases |
| **Text Extraction** | Extract structured information, keywords or metadata from text |

### AI Document Operations

| Node | Description |
| - | - |
| **Document Generation** | Automatically build reports or complete templates based on given inputs |
| **Document Extraction** | Identify and extract structured data, entities or metadata from documents |
| **Document Understanding** | Analyze documents to extract meaning, topics, sentiment, or important information |
| **Extract Data from File** | Extract text and data from documents and images using LLM, OCR, or text parsing |

### AI Image Operations

| Node | Description |
| - | - |
| **Image Description** | Generate captions or extract detailed information from visual content |
| **Image Analysis** | Recognize objects, emotions and scenes in images for contextual understanding |

### AI Data Operations

| Node | Description |
| - | - |
| **Data Enrichment** | Add annotations, context or relationships to enhance raw data value |
| **Data Generation** | Produce synthetic or structured data using templates and logic-based rules |
| **Data Transformation** | Clean, normalize, aggregate, or restructure datasets into usable formats |

> [card] [AI Node Types](../../../ai-platform/agent-builder/node-types)
>
> Learn more about AI node types and configuration options

### Personal Information Guard

Personal Information Guard detects and redacts PII on AI workflow nodes before the payload reaches the model, and restores it in the response. It is configured per node (sensitivity preset, input/output scan direction, entity types) and runs in the fail-closed **data-privacy** service.

For the full reference — configuration, scan flow, supported entity types, and run-log fields — see [Personal Information Guard](/5.9/ai-platform/personal-information-guard).


# FlowX custom plugins
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins

Adding new capabilities to the core platform can be done by using plugins. FlowX plugins represent already-built functionality that can be added to a FlowX.AI platform deployment.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/plugins_40.png)

These could be either one of the provided custom **plugins** that we've already built or building your desired plugin.

On our roadmap, we’re also looking to enhance the **plugins library** with 3rd party providers, so stay tuned for more.

## High-level architecture

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/plugins_diagram.png)

The plugins are microservice apps that can be developed using any tech stack. The only requirement is that they need to be able to connect to the core platform using Kafka events.

> [card] [Introduction to Kafka](../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts)

> [card] [Send message task (Kafka)](../../building-blocks/node/message-send-received-task-node#send-message-task)

> [card] [Receive message task (Kafka)](../../building-blocks/node/message-send-received-task-node#receive-message-task)

To interact with plugins, you need to understand a few details about them:

* the events that can trigger them
* the infrastructure components needed
* the needed configurations

## Custom plugins

The currently available plugins are:

* [**OCR**](./custom-plugins/ocr-plugin) - helps you scan your documents and integrate them into a business process
* [**Reporting**](./custom-plugins/reporting/reporting-overview) - a plugin that will help you create and bootstrap custom reports built on generic information about usage and processes metrics

Let's get into a bit more detail about the custom plugins 🎛️

## OCR plugin

**Automatic key information extraction**

Used to easily read barcodes or extract handwritten signatures from PDF documents.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_plugin_archi.svg)

> [card] [More about OCR plugin](./custom-plugins/ocr-plugin)

## Reporting plugin

**Easy-to-read dynamic dashboards**

Use reporting plugin to build and bootstrap custom reports built on generic information about usage and processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/reporting_diag.png)

> [card] [More about Reporting plugin](./custom-plugins/reporting/reporting-overview)


# OCR plugin
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins/ocr-plugin

The OCR (Optical Character Recognition) plugin is a tool that enables you to read barcodes and extract handwritten signatures from .pdf documents.

Before using the OCR service for reading barcodes and extracting signatures, please note the following requirements:

> [!NOTE]
>
> * All \*.pdf documents that are sent to the OCR service for reading barcodes and extracting handwritten signatures should be scanned at a minimum resolution of 200DPI (approximately 1654x2339 px for A4 pages)
> * Barcode is searched on the top 15% of each image (scanned page)
> * Signatures are detected on boxes with a border: 4px black solid
> * Only two signatures per image (scanned page) are detected.

> [!NOTE]
>
> The plugin supports **1D Code 128** barcodes. For more information, see the [Code 128 documentation](https://graphicore.github.io/librebarcode/documentation/code128.html).

## Using the OCR plugin

You can utilize the OCR plugin to process generic document templates by either using a specific flow on FlowX.AI (HTML template) or any other document editor.

> [!TIP]
>
> Using a specific flow on FlowX.AI offers several advantages:
>
> * Centralized management of templates and flows within a single application.
> * Access to template history and version control.

### Use case

1. Prepare and print generic document templates.
2. End-users complete, sign, and scan the documents.
3. Upload the scanned documents to the flow.
4. FlowX.AI validates the template (barcode) and the signatures.

### Scenario for FlowX.AI generated documents

1. Utilize the [**Documents plugin**](../../core-extensions/content-management/documents-plugin/documents-plugin-overview) to create a [**document template**](../../core-extensions/content-management/documents-plugin/generating-from-html-templates).

> [card] [Generating documents based on templates](../../core-extensions/content-management/documents-plugin/generating-from-html-templates)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_doc_template.gif)

2. Create a process and add a [**Kafka Send Action**](../../../building-blocks/node/message-send-received-task-node#configuring-a-send-message-task) to a [**Send Message Task**](../../../building-blocks/node/message-send-received-task-node#send-message-task) node. Here you specify the [**Kafka topic**](../../../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts#topics) (address) where the template will be generated.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_kafka_send.png)

> [!NOTE]
>
> The Kafka topic for generating the template must match the topic defined in the **`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN`** variable. Refer to the [**Kafka configuration guide**](../../../../setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka) for more details. For additional information, please see the [**Documents plugin setup guide**](../../../../setup-guides/documents-plugin-setup).

3. Fill in the **Message**. The request body should include the following values:

* **documentList** - a list of documents to be generated, including properties such as name and values to be replaced in the document templates
* **customId** - client ID
* **templateName** - the name of the template to be used
* **language**
* **includeBarcode** - true/false
* **data** - a map containing the values that should replace the placeholders in the document template, the keys used in the map should match those defined in the HTML template

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_message_body.png)

> [!NOTE]
>
> The `data` parameters must be defined in the document template beforehand. For more information, check the [**document template**](../../core-extensions/content-management/documents-plugin/generating-from-html-templates) section.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_data_model.png)

4. Add a **barcode**.

> [!TIP]
>
> * to include a **default barcode**, add the following parameter to the message body: `includeBarCode: true`.
> * to include a **custom barcode**, set `includeBarCode: false` and provide the desired data in the `data` field

5. Add a [**Receive Message Task**](../../../building-blocks/node/message-send-received-task-node#receive-message-task) node and specify the topic where you want to receive the response.

> [!TIP]
>
> Ensure that the topic matches the one defined in the **`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT`** variable.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_receive_response.png)

6. Add a [**User Task**](../../../building-blocks/node/user-task-node) node and configure an [**Upload file**](../../../building-blocks/actions/upload-file-action) action to send the file (defined by the **`KAFKA_TOPIC_DOCUMENT_PERSIST_IN`** variable) to the storage solution (for example, S3).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/ocr_upload_file.png)

7. Next, the response will be sent back to the Kafka topic defined by **`KAFKA_TOPIC_DOCUMENT_PERSIST_OUT`** environment variable through a callback action/subprocess.
8. Next, send the response to the OCR Kafka topic defined at **`KAFKA_TOPIC_OCR_IN`** variable (representing the path to the S3 file).
9. Display the result of the OCR validation in the Kafka topic defined at **`KAFKA_TOPIC_OCR_OUT`**.

For the OCR request and response message formats, refer to the [OCR plugin setup guide](../../../../setup-guides/plugins-setup-guide/ocr-plugin-setup).

> [!NOTE]
>
> The env vars above (`KAFKA_TOPIC_OCR_IN`, `KAFKA_TOPIC_OCR_OUT`) are configured on the **Document Plugin** side. The standalone **OCR Plugin** uses its own env vars (`KAFKA_INPUT_TOPIC`, `KAFKA_OUTPUT_TOPIC`) — see the [OCR plugin setup guide](../../../../setup-guides/plugins-setup-guide/ocr-plugin-setup#kafka-configuration) for details.

### Setup guide

> [card] [OCR plugin setup](../../../../setup-guides/plugins-setup-guide/ocr-plugin-setup)
>
> Refer to the OCR plugin setup guide for detailed instructions on setting up the OCR plugin.


# Authorization & access roles
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins/reporting/access-and-authorization

Configure authorization and access roles for the Reporting plugin using Keycloak integration with Apache Superset.

## IAM solution

> [!NOTE]
>
> Superset is using by default flask-openid, as implemented in flask-security.

Superset can be integrated Keycloak, an open-source identity and access management solution. This integration enables users to manage authentication and authorization for their Superset dashboards.

> [card] [Configuring an IAM solution](../../../../../setup-guides/access-management/configuring-an-iam-solution)

### Prerequisites

* Keycloak server
  * Keycloak Realm
  * Keycloak Client & broker configured with OIDC protocols
  * client\_secret.json
* admin username & password of postgres instance
* Superset Database created in postgresql
* optionally Cert-manager if you want to have SSL certificates on hostnames.

> [card] [Superset + Keycloak configuration](../../../../../setup-guides/plugins-setup-guide/reporting-setup#superset-single-sign-on)


# Reporting plugin
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/custom-plugins/reporting/reporting-overview

Build custom and technical reports from BPMN process data and process instance data, integrated with the FlowX.AI Engine.

### Quick walkthrough video

Watch this quick walkthrough video to get started:

<video />

### Data exploration and visualization

The plugin uses **Superset** as a free data exploration and visualization tool.

> [!TIP]
>
> You can however use your own BI tool like Tableau, PowerBI etc. as an alternative to Superset.

Use the suggested query structure and logic to ensure accurate reporting and avoid duplicates, even during database updates. Do not just use select on single reporting tables.

![Reporting plugin overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/reporting.png)

Apache Superset is an open-source software application for data exploration and data visualization able to handle data at a large scale. It enables users to connect their company's databases and perform data analysis, and build charts and assemble dashboards.

Superset is also an SQL IDE, so you can write SQL, join data, create datasets, and more.

> [card] [Superset documentation](https://superset.apache.org/docs/intro/)

### Plugin architecture

Here’s an overview of the reporting plugin architecture:

![Reporting plugin architecture diagram](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/Reporting_diagram_small2.png)

### Setting up reporting for a process definition

**1. Establish reporting data model to be extracted from process**

If you want to extract custom business parameters for a process, first you should set up the master reporting data model in the published version of that process. This is done in Designer, as explained below in the [**Reporting Data Model**](#reporting-data-model).

The master reporting data model that is applied to all historical versions is the one belonging to the version that is set as Published. If the currently published version is read-only, you might need to create a new version, create the data model in it, mark it for reporting and set it as published (as explained in the section below).

See [**Reporting Data Model**](#reporting-data-model) section for more details.

**2. Enable reporting on the process versions to be reported**

This is accomplished by checking the “Use process in reporting” button in the settings / general page of each process version you want to report. Please note that you will not be able to change that setting on read-only versions.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/use_proc_reporting.gif)

It is essential that the currently Published version has this setting enabled, as it is the master version for reporting all historical data.

Only the process instances belonging to reporting-enabled versions will be extracted to the database, using the master data model from the currently Published version.

> [!NOTE]
>
> The reason why you should first set up the data model on the published (or to-be-published) version is that all changes in the data model of the published version that is also marked “use\_in\_reporting” are instantly sent to the reporting plugin, potentially causing all historical process instances to be re-computed multiple times before you are done setting up the data model.

To optimize operations, you should always aim to finish the modifications on the master data model on a version that is either not published, or not marked as "use\_in\_reporting", before marking it as "use\_in\_reporting and ensuring it is published.

See [**Enabling Process Reporting**](#enabling-process-reporting) section for more details.

## Reporting data model

> [!NOTE]
>
> You can only create or modify the reporting data model in non-committed versions, as committed versions are read-only.

1. Open the branch view.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/branching_view.png)

2. If the current project version is committed, start a new version.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/start_new_version.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/rep6.png)

3. Make sure the new work-in-progress branch is selected, then go back to the process definition page.
4. Click on the Data Model icon and navigate in the object model to the target parameters.
5. Set up the business data structure to be reported by using the "Use in reporting" flag.

* Click "Show details".
* Click "Use in reporting".

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/data_to_be_reported.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flag_use_in_reporting.gif)

You can do this also for each parameter individually.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/parameter_type.png)

> [!NOTE]
>
> There are three parameter structures that you can report:
>
> **Singleton** or primitive, for which a single value is saved for each process instance. They can be of the types number, string, Boolean or date, and will all be found in the reporting table named `params_{process_alias}`. Date and zoned date-time attributes are reported as timestamp columns; any other type is reported as a string.
>
> **Array of primitives**, in which several rows are saved for each process instance, in a dedicated table (one value per row).
>
> **Array of objects**, in which the system extracts one or more “leaves” from each object of an array of objects. Also saved as a dedicated table.

### Primitive parameters reporting

In the following example, there are 3 simple parameters that will be extracted: `loan_approvalFee`, `loan_currency` and `loan_downPayment`.
They will be reported in the table `params_{process_alias}`, one row per instance.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/primitive_parameters_reporting.png)

### Arrays of primitives reporting

In the following example, the applicant can submit more than one email address, so each email will be extracted to a separate row in a dedicated table in the reporting database.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/arrays_of_primitives.png)

> [!WARNING]
>
> Extracting arrays is computationally intensive, do not use them if the only purpose is just to aggregate them afterward. Aggregation should be performed in the process, not in the reporting stage.

### Array of objects reporting

In this example, the applicant can have several real estate assets, so a subset of data items (`currentValue`, `mortgageBalance`, `propertyType`) will be extracted for each one of them.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/array_of_objects.png)

> [!WARNING]
>
> Extracting arrays of objects is even more is computationally intensive, do not use them if the only purpose is just to aggregate them afterward. Aggregation should be performed in the process, not in the reporting stage.

> [!WARNING]
>
> **Keep a reporting field's type stable across process versions.** A key mapped into the reporting data model is expected to hold the same type in every version. If you repurpose an existing reporting key to a different type between versions — for example, a key that held an array of objects is later used to store a plain string — reporting can stop for the affected versions, because the extracted value no longer matches the type already established for that field in the reporting database. If a field genuinely needs a different type, add a new key for it rather than reusing the existing one. If a key's type has already changed and reporting has stopped, removing that key from the reporting data model restores ingestion.

## Enabling process reporting

Enable reporting by checking the “Use process in reporting” button on the settings/general page of each process.

* Modifying the data model of a process version has no impact until the moment the version or build of the project is set in the "Active policy" tab and is also set to "use\_in\_reporting".

The reporting refresh schedule is set for a fixed interval (currently 5 minutes):

* No processing overlaps are allowed. If processing takes more than 5 minutes, the next processing is automatically postponed until the current one is finished.
* The reporting plugin chooses the number of Spark executors at each run, based on the volume of data to be processed: one executor for small deltas, up to the configured maximum for large ones. It does not use Spark dynamic allocation, and the `instances` value in the chart is only the driver's starting point.
* Rebuilding the whole history for a process (if the master data model, process name or the Published version change) typically takes more time. It is better to make these changes after the working hours.

## Reporting database

### Main tables

Common fields for joins:

* `inst_id`: Unique identifier for each process instance
* `query_time`: Timestamp for when the plugin extracts data
* `organization_id`, `workspace_id`, `build_app_version_id`: The organization, workspace and app version the instance belongs to

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/rep20.png)

**Useful fields from instances table**:

* `date_started/finished` timestamps
* `process_alias` (process name with "\_" instead of spaces)

> [!NOTE]
>
> The published version alias will be used for all the reported versions.

* State of the process (started, finished, etc.)
* `context_name`: Useful if the process is started by another process

**Useful fields from current\_nodes table**:

* `node_started/finished` timestamps for the nodes
* `node_name`, `node_type`
* `swimlane` of the current node
* `prev_node_end`: For calculating when a token is waiting for another process branch

**Useful fields from token\_history table**:

Similar to `current_nodes` but includes all nodes in the instance history.

### Parameters and object tables

Common fields, on which the joins are built:

* `inst_id`, unique identifier for each process instance
* `query_time`, recorded at the moment the plugin extracts data from the database
* `organization_id`, `workspace_id`, `build_app_version_id`, carried on every parameter and array table

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/reporting30.png)

For the `params_` table, there is a single row per process instance. For arrays and arrays of objects tables, there are multiple rows per process instance.

## Reporting for UI Flows and workflows

Besides process instances, the reporting plugin extracts **UI Flow sessions** and **integration workflow** runs into the same reporting database.

### Turning it on

For a UI Flow, open its **General settings** and toggle **Use UI flow in reporting** **ON**. For an integration workflow, open its **Settings** and toggle **Use workflow in reporting** **ON**.

As with processes, only resources that belong to the active build are extracted.

### How the columns are decided

Processes are reported attribute by attribute: you mark each data model attribute for reporting, and the plugin builds the columns from those definitions.

UI Flows and workflows have no per-attribute marking. The plugin infers the structure from the data itself on every run, so each variable present in a session or a token becomes a column, and every array is exploded into its own child table.

> [!NOTE]
>
> Because the structure is inferred rather than declared, the columns follow whatever the data contains. Renaming or restructuring variables changes the columns on the next run.

### UI Flow tables

| Table | Rows | Keys |
| - | - | - |
| `uiflow_sessions` | One per session | `session_id`, `uf_query_time` |
| `uiparams_{app_uiflow_id}` | One per session | `uf_session_id`, `uf_query_time` |
| `arr_{app_uiflow_id}_{branch}` | One per array element | `uf_session_id`, `uf_query_time` |

`uiflow_sessions` also carries `app_uiflow_id`, `resource_id`, `status`, `uf_started` and `uf_updated`.

> [!WARNING]
>
> The session identifier is named `session_id` in `uiflow_sessions` but `uf_session_id` in the parameter and array tables, so joins are `uiflow_sessions.session_id = uiparams_{app_uiflow_id}.uf_session_id`.

> [!NOTE]
>
> For a session that is still in progress, `uf_updated` falls back to the start date, because the engine only stamps the update date when a session finishes.

### Workflow tables

| Table | Rows | Keys |
| - | - | - |
| `wf_instances` | One per workflow instance | `wf_inst_uuid`, `wf_query_time` |
| `wf_tokens` | One per token | `token_uuid`, `wf_query_time` |
| `wfparams_{app_workflow_id}` | One per token | `wf_token_id`, `wf_query_time` |
| `arr_{app_workflow_id}_{branch}` | One per array element | `wf_token_id`, `wf_query_time` |

`wf_instances` also carries `app_workflow_id`, `workflow_resource_id`, `wf_status`, `wf_started` and `wf_finished`. `wf_tokens` adds `token_status` and `wf_updated`, and links to its instance through `wf_inst_uuid`.

The same naming difference applies here: the token identifier is `token_uuid` in `wf_tokens` and `wf_token_id` in the parameter and array tables.

Every table listed above also carries `organization_id`, `workspace_id` and `build_app_version_id`.

> [!NOTE]
>
> Array table names are truncated to 64 characters, so deeply nested branches with long names can produce shortened table names.

***

## Using Superset for data exploration

### Data sources

The **Data** tab represents the sources of all information:

* Databases
* CSV files
* Tables
* Excel files

Reporting plugin can be used with Superset by connecting it with a PostgreSQL DB.

### Charts

Charts represent the output of the information. There are multiple visualization charts/ plugins available.

### Dashboards

With the use of dashboards, you can share persuading flows, show how metrics change in various scenarios and match your company efforts with logical, evidence‐based visual indicators.

### Datasets

Contains all the information for extracting and processing data from the DB, including SQL queries, calculated metrics information, cache settings, etc. Datasets can also be exported / imported.

### Connecting to a database

Before using Superset, ensure you have a PostgreSQL database installed and configured. Follow these guides for setup:

[FlowX Engine DB configuration](../../../../../setup-guides/flowx-engine-setup-guide/engine-setup)

[Reporting DB configuration](../../../../../setup-guides/plugins-setup-guide/reporting-setup)

> [!NOTE]
>
> Read-only users should be used in production in the reporting-plugin cronjob.

To connect Superset to a database, follow the next steps:

1. From the Toolbar, hover your cursor over the **"+"** icon, then select **Data**, and then select **Connect Database**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/connecting_to_db.png)

2. The **Connect a database** window appears. Select the appropriate **database card** (in this case - PostgreSQL).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/connect_db_superset.png)

3. After you selected the DB, click **Connect this database with a SQLAlchemy URI string instead?**.
4. Fill in the **SQLALCHEMY URI** and then click **Connect**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_db_URI.png)

> [!NOTE]
>
> The **SQLAlchemy URI** for **reporting-db** should be in this format: `postgresql://postgres:XXXXXXXXXX@reporting-plugin-postgresql:{{port}}/reporting`.

### Creating and configuring charts

There are multiple ways in which you can create/configure a chart.

#### Creating charts using Datasets tab

To create a Chart using the first method, you must follow the next steps:

1. From the top toolbar, select **Data** and then **Datasets**.

> [!TIP]
>
> You need to have a dataset added to Superset first. From that particular dataset you can build a visualization.

2. Select the desired **dataset**.
3. On the **explore** page, choose the **visualization type** and click **Create chart**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_add_chart.gif)

4. When you select a dataset, by default **table** visualization type is selected.

> [!NOTE]
>
> To view all the existent visualization types, click **View all charts**, the charts' gallery will open.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_visualization_type.png)

#### Creating charts using Chart gallery

Using the Chart gallery is a useful method when you are not quite sure about which chart will be best for you.

To create a Chart using the second method, you must follow the next steps:

1. Select the **"+"** icon from the top toolbar and choose **Chart**.
2. Choose the **dataset** and **chart type**.
3. Review the description and example graphics of the selected chart, then click **Create new chart**.

> [!TIP]
>
> If you wish to explore all the chart types available, filter by **All charts**. The charts are also grouped by categories.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_add_chart_second.gif)

### Configuring a Chart

Configure the **Query** fields by dragging and dropping relevant columns to the matching fields. Note that time and query form attributes vary by chart type.

### Exporting/importing a Chart

You can export and import charts to help you analyze your data and manipulate dashboards. To export/import a chart, follow the next steps:

1. Open **Superset** and navigate to **Charts** from the top navigation bar.
2. Select the desired **chart** and click the **breadcrumbs** menu in the top-right corner.
3. Choose an export option: .CSV, .JSON, or Download as image.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/reporting_export_imp.png)

**Table example**:

* **Time** - time related form attributes
* **Query** - query attributes
  * **Dimensions** - one or many columns to group by
  * **Metrics** - metrics to display
  * **Percentage metrics** - metrics for which percentage of total are to be displayed, calculated from only data within the row limit
  * **Filters** - metric used for filtering
  * **Sort by** - metric used to define how the top series are sorted if a series or row limit is present
  * **Row limit** - limits the number of rows that get displayed

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/superset_query.png)

### Creating a dashboard

To create a dashboard follow the next steps:

1. Create a new chart and save it to a new dashboard.
2. To publish, click **Save and go to Dashboard**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/save_dashboard.gif)

For details on how to configure the FlowX.AI reporting plugin, check the following section:

> [card] [Reporting setup guide](../../../../../setup-guides/plugins-setup-guide/reporting-setup)


# WYSIWYG editor
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/plugins/wysiwyg

Create and edit notification and document templates in FlowX Designer with the WYSIWYG (What You See Is What You Get) editor.

Displaying how the document will be published or printed on the screen, the user can adjust the text, graphics, photos, or other document/notification elements before generating the final output.

## WYSIWYG Components

### Header

The formatting head of the editor allows users to manipulate/format the content of the document.

### Body

The Body is the main part of the editor where you can edit your template.

> [!TIP]
>
> After you defined some parameters in the **Data Model** tab, you can type "**#**" in the body to trigger a dropdown where you can choose which one you want to use.

### Source

The **Source** button can be used to switch to the HTML editor. You can use the HTML view/editor as a debugging tool, or you can edit the template directly by writing code here.

![Source Code](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_source.gif)

## Document templates

One of the main features of the [document management plugin](../core-extensions/content-management/documents-plugin/documents-plugin-overview) is the ability to generate new documents based on custom templates and prefilled with data related to the current process instance.

![Document template](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_document_template.png)

> [card] [Documents plugin](../core-extensions/content-management/documents-plugin/documents-plugin-overview)

## Notification templates

Notification WYSIWYG body has some additional fields (other than documents template):

* **Type** - that could be either MAIL or SMS (SMS, only if there is an external adapter)
* **Forward on Kafka** - if this box is checked, the notification is not being sent directly by the plugin to the destination, but forwarded to another adapter

![Notification template](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_notif_template.png)

> [card] [Managing notifications templates](../core-extensions/content-management/notifications-plugin/managing-notification-templates)

## Data model

Using the data model, you can define key pair values (parameters) that will be displayed and reused in the body. Multiple parameters can be added:

* STRING
* NUMBER
* BOOLEAN
* OBJECT
* ARRAY (which has an additional `item` field)

![Data model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/wysiwyg_data_model.png)

### Structured data model

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Notification and document templates use the structured data model: you build typed attributes on the **Data Model** tab, with validations and references to project or library data types, then choose the attributes the template expects on the **Input Parameters** tab. See [Configuring the data model](../core-extensions/content-management/notifications-plugin/managing-notification-templates#configuring-the-data-model) for notification templates and [Managing HTML templates](../core-extensions/content-management/documents-plugin/managing-html-templates) for document templates.

> [!NOTE]
>
> Parameters can be defined as mandatory or not. When you try to generate a template without filling in all the mandatory parameters, the following error message will be displayed: "*Provided data cannot be empty if there are any required properties defined."*


# Browser Automation
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/browser-automation

Automate interactions with web applications from a workflow node, driving a real browser with natural-language task instructions.

SaaS · 5.13

> [!NOTE]
>
> **Available starting with FlowX.AI 5.13.0** on SaaS deployments. Self-hosted deployments will receive it with the next LTS release family.

## Overview

The **Browser Automation** node drives a real browser to complete tasks on web applications that have no API: filling multi-page forms, navigating portals, and retrieving results. You describe the task in natural language, and an AI agent plans and executes the browser interactions, wrapped in the platform's execution, logging, and document storage layers.

> [card] Natural-language tasks
>
> Describe what to do on the target site; the agent plans the browser steps

> [card] Verified outcomes
>
> Results are checked against the target site's recorded state changes, not the agent's own success claim

> [card] Persistent sessions
>
> Multi-step automations continue in the same browser session across workflow steps

> [card] Full audit trail
>
> Every run is logged through the platform's execution and observability layers

***

## When to use it

Use Browser Automation when the system you need to reach exposes no API or integration point: legacy portals, third-party sites, and internal tools where the browser is the only interface. When the target exposes an API, prefer a [RESTful System integration](../../docs/platform-deep-dive/integrations/integration-designer); when you only need page content, use the [Web Page Extractor](./web-page-extractor) node.

***

## Reliability

The node's execution approach is grounded in FlowX.AI's published browser-agent benchmark: 405 verified runs across nine models and nine controlled web tasks, showing that outcome-state verification catches failures that agent self-reports miss. See the [research page](../research#browser-agent-reliability-benchmark) and the [full benchmark](https://www.flowx.ai/blog/browser-agents-dont-fail-on-capability-they-fail-on-consistency).

***

## Related resources

> [card] [Web Page Extractor](./web-page-extractor)
>
> Read-only content collection from web pages

> [card] [Browser-agent reliability benchmark](../research#browser-agent-reliability-benchmark)
>
> The 405-run benchmark behind the node's verification approach


# Context Retrieval
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/context-retrieval

Query Knowledge Bases and retrieve relevant chunks using RAG search without calling an LLM.

## Overview

The **Context Retrieval** node is a specialized [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) workflow node that performs RAG (Retrieval-Augmented Generation) searches against a Knowledge Base. Unlike the [Custom Agent](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) node, Context Retrieval does **not** call an LLM — it retrieves and returns matching chunks directly, giving you full control over how the results are processed downstream.

![Context Retrieval node configuration with Source, User Query, Search Type, and relevance settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)

> [!TIP]
>
> Use Context Retrieval when you want to separate the retrieval step from the generation step. This lets you inspect, filter, or transform retrieved chunks before passing them to an AI node for response generation.

***

## When to use Context Retrieval vs Custom Agent

| Scenario | Recommended node |
| - | - |
| You need the AI to reason about retrieved information and generate a response | **Custom Agent** with Knowledge Base enabled |
| You want raw chunks to process, filter, or route in your workflow | **Context Retrieval** |
| You need to combine chunks from multiple Knowledge Bases | **Context Retrieval** (one per KB) + downstream merge |
| You want a simple question-answer flow with RAG | **Custom Agent** with Knowledge Base enabled |

***

## Configuration

### Knowledge Base

**Knowledge Base** `select` *required*

Select the Knowledge Base resource reference to query. A Context Retrieval node queries one Knowledge Base; to combine several, add one node per Knowledge Base and merge the results.

### Source

**Source** `enum`

The source to query.

**Options:**

* **Knowledge Base** — Search the selected Knowledge Base (default)
* **Memory** — Search [conversation memory](/5.9/ai-platform/chat-driven-workflows#session-memory)

The **Memory** option is only available in [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).

**Default:** **Knowledge Base**

### Settings

The settings below are available inside the **Settings** expander on the node configuration panel.

#### Search type

**Search Type** `enum`

The strategy used for retrieving context from the Knowledge Base.

**Options:**

* `Hybrid` — Combines semantic and keyword search for balanced results (default)
* `Semantic` — Uses vector similarity for meaning-based search
* `Keywords` — Uses traditional keyword matching

**Default:** `HYBRID`

> [!TIP]
>
> When **Keywords** is selected, the **Min Relevance Score** slider is hidden because keyword search does not produce a relevance score.

#### Query parameters

**Max Number of Chunks** `number`

Maximum number of relevant chunks to return. Configurable from 1 to 10.

**Default:** `4`

**Min Relevance Score** `number`

Minimum relevance score threshold, expressed as a percentage (0–100). Only chunks with a relevance score above this threshold are returned. Not available when search type is set to **Keywords**.

**Default:** `50`

#### Metadata filters

**Metadata Filters** `button`

Opens a query builder modal where you compose conditions as **field / operator / value** triples. Operators depend on the metadata key type (equals, not equals, contains, in, not in, before, after, exists, etc.). Conditions can be grouped and combined with **AND** or **OR**.

To filter by store, add a condition on the system metadata key `source`.

> [!NOTE]
>
> Typed operators and AND/OR grouping are supported. See [Filtering by metadata](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#filtering-by-metadata) for the full operator list.

**Use advanced metadata filters** `boolean`

Toggle to turn on advanced metadata filter expressions for more complex filtering logic. When turned on, a JSON expression field becomes available for defining property-based filters.

**Default:** `false`

#### Re-ranking

**Use Re-Rank** `boolean`

When turned on, applies a re-ranking model to the retrieved chunks, reordering them by relevance to the query. This can improve result quality at the cost of slightly higher latency.

**Default:** `false`

***

## User Query

**User Query** `string` *required*

The query text sent to the Knowledge Base. Supports `${}` placeholder syntax for dynamic values from workflow input and configuration parameters.

**Example:**

```
${userMessage}
```

Both runtime input variables and configuration parameters are available for placeholder resolution.

***

## Response Key

**Response Key** `string` *required*

Key under which the retrieved chunks are stored in the workflow data, so downstream nodes can reference them.

**Default:** `responseKey`

***

## Output format

The Context Retrieval node returns an array of chunk objects. Each chunk contains:

| Field | Type | Description |
| - | - | - |
| **chunkContent** | `string` | The text content of the retrieved chunk |
| **chunkMetadata** | `object` | Metadata associated with the chunk (key-value pairs) |
| **relevanceScore** | `number` | Similarity score between the query and the chunk (0–1) |
| **searchType** | `string` | Search strategy that returned this chunk. One of `HYBRID`, `SEMANTIC`, or `KEYWORD`. Only emitted when the RAG service returns a non-null value. |
| **contentSource** | `string` | The name of the store the chunk belongs to (field name preserved for API compatibility) |

### Example output

```json theme={"dark"}
[
  {
    "chunkContent": "The onboarding process requires identity verification...",
    "chunkMetadata": {
      "source": "onboarding-guide.pdf",
      "page": "3"
    },
    "relevanceScore": 0.92,
    "contentSource": "Product Documentation"
  },
  {
    "chunkContent": "KYC checks must be completed within 48 hours...",
    "chunkMetadata": {
      "source": "compliance-policy.pdf",
      "page": "12"
    },
    "relevanceScore": 0.85,
    "contentSource": "Compliance Policies"
  }
]
```

***

## Error handling

If the Context Retrieval node fails, the workflow produces a `WORKFLOW_NODE_CONTEXT_RETRIEVAL_ERROR` error. Common causes include:

> [accordion] Knowledge Base not found
>
> The referenced Knowledge Base does not exist or is not accessible.
>
> **Solution:** Verify the Knowledge Base exists in your project or dependencies and that you have the required permissions.

> [accordion] Invalid query
>
> The operation prompt resolved to an empty or invalid query.
>
> **Solution:** Check that the `${}` placeholders in your operation prompt reference valid input or config variables.

> [accordion] Timeout
>
> The RAG search exceeded the configured timeout.
>
> **Solution:** The default timeout is 600 seconds (`flowx.ai-service.nodeRunnerTimeoutSeconds`). Consider simplifying your query or reducing the `topK` value.

***

## Best practices

> [!TIP]
>
> **Optimizing Context Retrieval:**
>
> * Start with **Hybrid** search type for the best balance of precision and recall
> * Use **Semantic** when your queries are natural-language questions; use **Keywords** for exact-match lookups
> * The default minimum relevance threshold (50%) is a good starting point — increase it to filter out lower-quality matches
> * Turn on **Use Re-Rank** when result quality is more important than latency
> * Use metadata filters to narrow results to specific stores (via the `source` key) or metadata values
> * Keep **Max Number of Chunks** reasonable (3–10) to avoid overwhelming downstream nodes with too much context

> [!TIP]
>
> **Building RAG pipelines:**
>
> * Chain Context Retrieval → Script Node → Custom Agent to build custom RAG flows with intermediate processing
> * Use the `relevanceScore` field to implement your own relevance filtering logic in a Script node
> * Combine results from multiple Context Retrieval nodes (querying different KBs) using a Script node before passing to generation

***

## Related resources

> [card] [Knowledge Base overview](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Create and manage Knowledge Bases

> [card] [Using Knowledge Base in workflows](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows)
>
> Query Knowledge Bases with Custom Agent nodes

> [card] [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
>
> AI agents with MCP tools and Knowledge Base access

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Build and manage integration workflows


# Extract Data from File
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/extract-data-from-file

Configure the Extract Data from File AI node to extract text and data from documents and images using LLM, OCR, or text parsing strategies.

## Overview

The **Extract Data from File** node extracts text and structured data from documents and images within Agent Builder workflows. It supports multiple extraction strategies so you can balance accuracy, speed, and cost based on your document types.

### Supported file formats

| Category | Formats |
| - | - |
| Documents | PDF, DOCX, XLSX, PPTX, HTML, CSV, Markdown, AsciiDoc |
| Images | JPG, JPEG, PNG, TIFF, BMP, WEBP |

> [!NOTE]
>
> `.xls` files are automatically converted to `.xlsx` and `.txt` files to Markdown before parsing. Images are processed directly through OCR by the Document Parser service.

***

## Configuration

To add the node to an Agent Builder workflow:

**1. Open your workflow**

Open your workflow in **Agent Builder**.

**2. Add the node**

Add an **Extract Data from File** node from the **Document Operations** category.

**3. Configure extraction settings**

Configure the extraction settings described below.

![Extract Data from File node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/extract_data_config_panel.png)

### Document source

**Document Source** `select` *required*

The source system for the document. Select **Document Plugin** to use files stored in the FlowX Documents Plugin.

**Default:** `Document Plugin`

### Use test file

**Use Test File** `boolean`

Toggle **ON** to use a test file during workflow configuration and testing, without requiring a live file path from process data.

**Default:** OFF

### File path

**File Path** `string` *required*

The path to the input file to process. This can reference a file stored in the Documents Plugin.

> [!TIP]
>
> When **Use Test File** is turned off, map this field to a process variable or workflow data key that contains the file path at runtime.

***

### Response key

**responseKey** `string` *required*

The key where the extraction results are stored in the workflow data.

**Example:** `extractedData`

***

### Extraction method

**Extraction Method** `select` *required*

Select the method used to extract content from the file. Each method has different accuracy, speed, and cost characteristics.

| Method | Best for | Speed | Cost | Accuracy |
| - | - | - | - | - |
| **Automatic** | Mixed document sets where you don't know the format up front | Varies | Varies | Varies |
| **LLM Model** | Complex layouts, handwritten text, mixed content | Slow | High | High |
| **OCR Engine** | Scanned documents, image-heavy files | Medium | Medium | Medium |
| **Text Parsing** | Clean digital PDFs with selectable text | Fast | Free | Low–Medium |

> [tab] Automatic
>
> The platform selects the best extraction method for each document automatically — *"AI will choose the best method for each document."* Use it for mixed document sets where the format varies and you don't want to pick a strategy per file.

> [tab] LLM Model
>
> Uses AI vision models (such as GPT-4o) to analyze document content. This strategy provides the highest accuracy and can handle:
>
> * Complex page layouts with multiple columns
>
> * Handwritten text and annotations
>
> * Mixed content (text, tables, images on the same page)
>
> * Documents with non-standard formatting
>
> > [!WARNING]
> >
> > LLM Model is the most expensive strategy due to AI API calls per page. Use it when accuracy is critical and the document structure is complex.

> [tab] OCR Engine
>
> Uses Optical Character Recognition engines (Tesseract or EasyOCR, plus RapidOCR up to 5.9.5) to extract text from images and scanned documents. Best for:
>
> * Scanned paper documents
>
> * Photographed documents
>
> * Image-heavy files where text is embedded in images
>
> > [!NOTE]
> >
> > The OCR engine used is configured at the service level. See the [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) for engine selection.

> [tab] Text Parsing
>
> Extracts text directly from the document file without AI or OCR processing. Best for:
>
> * Clean digital PDFs with selectable text
>
> * Documents generated by software (not scanned)
>
> * High-volume processing where speed matters
>
> > [!TIP]
> >
> > Text Parsing is the fastest and most cost-effective option. Use it as a first pass and fall back to OCR or LLM for documents with low extraction quality.

***

### Image extraction options

When using **LLM Model** or **OCR Engine**, you can configure how images found within the document are handled.

**Image Extraction** `select`

Select how images embedded in the document should be processed.

| Option | Description | When to use |
| - | - | - |
| **Image Description** | Generates a text description of images | When you need to understand what images depict (charts, photos, diagrams) |
| **Image Contents** | Extracts text and data from images | When images contain text, tables, or data you need to capture |

> [!NOTE]
>
> LLM Model supports both Image Description and Image Contents. OCR Engine supports only Image Contents.

> [!NOTE]
>
> Image extraction options are not available when using the Text Parsing strategy, since Text Parsing only handles selectable text content.

***

### Signature detection

**Detect Signatures** `boolean`

Turn on detection of signatures within the document.

**Default:** OFF

When enabled, the node identifies areas of the document that contain signatures and includes their locations in the extraction results.

> [!NOTE]
>
> Signature detection is only available when using **LLM Model** or **OCR Engine** strategies. It is not available for Text Parsing.

![Detect Signatures toggle in the Extract Data from File node settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/detect_signatures1.png)

#### Signature detection output

When **Detect Signatures** is on, the extraction result stored under the response key also includes:

```json theme={"dark"}
{
  "signature_found": true,
  "signatures": [
    {
      "page_index": 0,
      "signature_found": true,
      "who_signed": ["borrower", "bank_representative"],
      "notes": ["Handwritten signature next to the borrower label"]
    }
  ]
}
```

| Field | Type | Description |
| - | - | - |
| `signature_found` | boolean | Whether at least one signature was detected anywhere in the document |
| `signatures` | array | One entry per page that contains signatures; pages without signatures are omitted |
| `signatures[].page_index` | number | The page the signatures were found on, starting from `0` |
| `signatures[].who_signed` | array of strings | The **role category** of each signer, inferred from the surrounding text — one of `bank_representative`, `borrower`, `guarantor`, `notary`, `witness`, `carrier`, `shipper`, `consignee`, `client`, `legal_representative`, or `unknown` |
| `signatures[].notes` | array of strings | Short context notes for each detected signature |

> [!WARNING]
>
> `who_signed` identifies the signer's **role** (for example `borrower` or `notary`), not the person's name or title. Extract names separately through the regular data extraction fields if you need them.

### Personal Information Guard

For the full reference — sensitivity presets, the complete entity catalog, scan flow, and run-log fields — see [Personal Information Guard](/5.9/ai-platform/personal-information-guard).

**Personal Information Guard** `boolean`

Detects and replaces personal data in messages before they reach the model. A system instruction is automatically added so the agent handles redacted content naturally.

**Default:** OFF

When turned on, the following sub-options become available:

* **Detection Algorithm Sensitivity** — One of **Strict**, **Balanced** (default), **Relaxed**, or **Custom**. Controls how aggressively the detector flags potential matches.
* **Detection Target** — Check **Node Input**, **Node Output**, or both to choose which payloads are scanned.
* **Personal Info Types** — Opens the **Customize Entities** modal, the picker for which of the 24 supported entity types should be detected. All 24 are enabled by default. Entities are grouped into **Universal** and **Regional** (per-locale) sets.

> [accordion] Supported entity types (24)
>
> **Universal (8)**
>
> `EMAIL`, `PHONE`, `CREDIT_CARD`, `IBAN`, `MAC_ADDRESS`, `CRYPTO_WALLET`, `PERSON`, `ADDRESS`
>
> **Regional — EN (6)**
>
> `SSN`, `US_PASSPORT`, `US_BANK_ACCOUNT`, `US_ITIN`, `UK_NHS`, `EU_VAT_ID`
>
> **Regional — RO (10)**
>
> `CNP`, `CUI`, `RO_IBAN`, `RO_PHONE`, `RO_PASSPORT`, `RO_ID_CARD`, `LICENSE_PLATE`, `HEALTH_CARD`, `POSTAL_CODE`, `LANDLINE`

> [!NOTE]
>
> When a node runs with Personal Information Guard on, the scan lists each detected entity individually — its type, confidence score, original value, the replacement applied, and whether it was matched on the node input or output. Document and image scans report this per-entity list too, and each detection also includes the region (`x`, `y`, `width`, `height`) where the entity was found, so the run console can highlight its location.

***

## Examples

> [accordion] Processing a scanned invoice
>
> **Scenario:** Extract line items and totals from a scanned paper invoice.
>
> **Configuration:**
>
> * **Extraction Method:** OCR Engine
> * **Image Extraction:** Image Contents
> * **Detect Signatures:** ON (to capture the approval signature)
>
> The OCR engine processes the scanned image, extracts text from both the document body and any embedded images (such as company logos with text), and identifies signature areas.

> [accordion] Analyzing a contract with charts
>
> **Scenario:** Extract text and understand visual elements from a contract that includes charts and diagrams.
>
> **Configuration:**
>
> * **Extraction Method:** LLM Model
> * **Image Extraction:** Image Description
> * **Detect Signatures:** OFF
>
> The LLM analyzes each page, extracts the contract text, and generates descriptions of charts and diagrams (for example, "Bar chart showing quarterly revenue growth from Q1 to Q4 2025").

> [accordion] Extracting text from a clean PDF
>
> **Scenario:** Extract text from a digitally generated report PDF.
>
> **Configuration:**
>
> * **Extraction Method:** Text Parsing
> * **Image Extraction:** N/A (not available for Text Parsing)
> * **Detect Signatures:** N/A (not available for Text Parsing)
>
> Text Parsing directly extracts the selectable text from the PDF with no AI or OCR processing, making it the fastest and lowest-cost option.

***

## Best practices

> [card] Start with Text Parsing
>
> For digital PDFs, try Text Parsing first. Only use OCR or LLM if the results are insufficient.

> [card] Match strategy to document type
>
> Use OCR for scanned documents, LLM for complex layouts, and Text Parsing for clean digital files.

> [card] Consider cost at scale
>
> LLM processing costs increase linearly with page count. For high-volume workloads, use Text Parsing or OCR where possible.

> [card] Turn off unused features
>
> Turn off signature detection and image extraction when not needed to reduce processing time and cost.

***

## Related resources

> [card] [Document Parser setup](/5.9/setup-guides/document-parser-setup)
>
> Configure the Document Parser service, parsing engines, and deployment sizing

> [card] [AI node types](./node-types)
>
> Overview of all AI node types available in Agent Builder

> [card] [Agent Builder overview](./overview)
>
> Get started with Agent Builder workflows

> [card] [Use cases](./use-cases)
>
> See real-world Agent Builder workflow examples


# Intent Classification Agent
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/intent-classification

Classify user messages and route workflows to different branches using AI-powered intent detection.

## Overview

The **Intent Classification Agent** node is a specialized [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) workflow node that combines AI-powered message classification with workflow branching in a single node. It analyzes a user message, classifies it into one of your defined intents using an LLM, and automatically routes the workflow to the matching branch — replacing the previous two-node pattern (TEXT\_UNDERSTANDING + Condition).

![Intent Classification Agent node with intents list and the If No Intent Matches default branch](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/if_no_intent_matches.png)

> [!TIP]
>
> The Intent Classification Agent node is available in Integration Designer workflows alongside other node types like REST API Call, Script, Condition, and Custom Agent. For BPMN process workflows, use the [Start Integration Workflow](/5.9/docs/building-blocks/actions/start-integration-workflow) action to invoke workflows that contain Intent Classification Agent nodes.

> [card] AI + routing in one node
>
> Combines LLM classification and conditional branching — no separate Condition node needed

> [card] Natural language conditions
>
> Define intents as plain-text descriptions instead of code expressions

> [card] Conversation memory
>
> Optionally use past conversation context for more accurate classification

> [card] Built-in fallback
>
> Automatic "If No Intent Matches" branch handles unrecognized inputs

### How it compares to the pattern approach

| Aspect | Pattern (TEXT\_UNDERSTANDING + Condition) | Intent Classification Agent node |
| - | - | - |
| **Nodes required** | 2 (classify, then route) | 1 (classify and route) |
| **Conditions** | Python/JavaScript expressions | Natural language descriptions |
| **Max branches** | Unlimited | 10 intents + fallback |
| **Response schema** | Manual JSON schema | Automatic (handled internally) |
| **Rationale** | Must be added to prompt manually | Built-in toggle |

***

## Configuration

**1. Open your workflow**

Open your workflow in **Integration Designer**.

**2. Add the node**

Add an **Intent Classification Agent** node from the **AI Agents** category in the left panel.

**3. Configure the user message**

Set the **User message** field to the input text that should be classified. Use `${}` syntax to reference workflow data keys.

**4. Define intents**

Add intent descriptions — each intent becomes a separate output branch on the node.

**5. Connect output branches**

Connect each intent branch and the fallback branch to downstream nodes in your workflow.

***

### Personal Information Guard

For the full reference — sensitivity presets, the complete entity catalog, scan flow, and run-log fields — see [Personal Information Guard](/5.9/ai-platform/personal-information-guard).

**Personal Information Guard** `boolean`

Detects and replaces personal data in messages before they reach the model. A system instruction is automatically added so the agent handles redacted content naturally.

**Default:** OFF

When turned on, the following sub-options become available:

* **Detection Algorithm Sensitivity** — One of **Strict**, **Balanced** (default), **Relaxed**, or **Custom**. Controls how aggressively the detector flags potential matches.
* **Detection Target** — Check **Node Input**, **Node Output**, or both to choose which payloads are scanned.
* **Personal Info Types** — Opens the **Customize Entities** modal, the picker for which of the 24 supported entity types (Universal + Regional EN + Regional RO) should be detected. All 24 are enabled by default. See the [Extract Data from File](./extract-data-from-file#personal-information-guard) reference for the full entity list.

***

### User Message

**User Message** `string` *required*

The text input to classify. Use `${}` syntax to reference workflow data keys.

**Example:** `${userMessage}`

> [!TIP]
>
> Reference a workflow data key that contains the user's message rather than hardcoding text. This allows the node to classify different messages at runtime.

***

### Use conversation memory

**Use conversation memory** `boolean`

When turned on, the node sends the session ID to the AI platform and appends conversation history to the LLM call. This provides context from past messages for more accurate classification. See [Memory Capabilities](/5.9/ai-platform/agent-builder/memory-capabilities) for details on how memory retrieval works.

**Default:** OFF

> [!TIP]
>
> Turn on memory when classifying messages in multi-turn conversations where context matters — for example, distinguishing "yes" (confirming a previous offer) from "yes" (answering a question).

***

### Intents

**intentClassificationOptions.conditions** `array` *required*

A list of intent descriptions that define the classification categories. Each intent becomes an output branch on the node.

* **Minimum:** 1 intent + fallback
* **Maximum:** 10 intents + fallback
* Each intent description can be up to 3 lines of text
* The **If No Intent Matches** fallback branch is always present and cannot be removed

**Example intents:**

| Intent | Description |
| - | - |
| Intent 1 | The user is asking about product features, pricing, or availability |
| Intent 2 | The user wants to update their personal information or submit documents |
| Intent 3 | The user is greeting or making small talk |
| Fallback | If No Intent Matches |

> [!NOTE]
>
> For best accuracy, classify up to 10 intents per node. If you need more intents, chain multiple Intent Classification Agent nodes to narrow down in stages.

***

### Response key

**responseKey** `string` *required*

The key where the classification result is stored in the workflow data.

**Example:** `classificationResult`

***

### Include Reason for Selection

**intentClassificationOptions.includeRationale** `boolean`

When turned on, the agent includes a rationale explaining why it chose this intent in its response.

**Default:** OFF

> [!TIP]
>
> Turn on rationale during development and testing to understand classification decisions. You can turn it off in production to reduce response size.

***

## Output

The node stores its classification result under the configured **Response key** in the workflow data. The output contains:

| Field | Type | Description |
| - | - | - |
| `selected_intent` | string | The description text of the matched intent |
| `selected_branch` | number | The branch number (1–11) corresponding to the matched intent |
| `rationale` | string | Explanation of why the LLM chose this intent (only when **Include Reason for Selection** is ON) |

**Example output:**

```json theme={"dark"}
{
  "selected_intent": "The user is asking about product features, pricing, or availability",
  "selected_branch": 1,
  "rationale": "The user asked 'How much does the premium plan cost?' which is a direct inquiry about pricing."
}
```

### Workflow routing

After classification, the node routes the workflow token to the matching branch:

* **Intent branches** — the workflow continues along the branch whose intent description matched the user message
* **If No Intent Matches** — the fallback branch activates when the LLM response doesn't match any defined intent

This routing works like a Condition (Fork) node, but conditions are evaluated by the LLM using natural language instead of code expressions.

***

## Examples

> [accordion] Customer support routing
>
> **Scenario:** Route customer messages to specialized support handlers.
>
> **Intents:**
>
> 1. The customer is reporting a technical issue or bug
> 2. The customer is asking about billing, payments, or invoices
> 3. The customer wants to cancel or modify their subscription
> 4. The customer is asking a general question about the product
>
> **Fallback:** Routes to a human agent handoff workflow.
>
> Each branch connects to a specialized handler — for example, the billing branch triggers a workflow that looks up the customer's invoice history, while the technical issue branch creates a support ticket.

> [accordion] Banking chatbot
>
> **Scenario:** Classify banking customer requests in a chat-driven workflow.
>
> **Intents:**
>
> 1. The user wants to check their account balance or transaction history
> 2. The user wants to transfer money or make a payment
> 3. The user is asking about loan or mortgage options
> 4. The user is greeting or making small talk
>
> **Configuration:**
>
> * **Use conversation memory:** ON (to understand context in multi-turn conversations)
> * **Include Reason for Selection:** OFF (production deployment)
>
> The balance branch queries the account API, the transfer branch starts the payment workflow, and the loan branch triggers a knowledge base lookup.

> [accordion] Email triage pipeline
>
> **Scenario:** Classify incoming emails and route to appropriate processing.
>
> **Intents:**
>
> 1. The message is a complaint or escalation requiring urgent attention
> 2. The message is a new business inquiry or sales lead
> 3. The message is a support request with a reference to an existing ticket
> 4. The message is informational (newsletter reply, out-of-office, automated notification)
>
> **Fallback:** Routes to a manual review queue.
>
> **Configuration:**
>
> * **Use conversation memory:** OFF (each email is independent)
> * **Include Reason for Selection:** ON (for audit trail)

***

## Best practices

> [card] Write specific intent descriptions
>
> Describe each intent clearly and distinctly. Vague or overlapping descriptions reduce classification accuracy.

> [card] Chain nodes for complex taxonomies
>
> For more than 10 categories, use a first node to classify into broad groups, then a second node to classify within each group.

> [card] Always handle the fallback
>
> Connect the fallback branch to meaningful handling — a clarification prompt, a human handoff, or a default response.

> [card] Use rationale for debugging
>
> Turn on Include Reason for Selection during development to understand why the LLM routes to unexpected branches.

***

## Related resources

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Learn about Integration Designer workflows and all available node types

> [card] [AI node types](./node-types)
>
> Overview of all AI node types in Agent Builder

> [card] [Intent classification pattern](../patterns/intent-classification-routing)
>
> Alternative approach using TEXT\_UNDERSTANDING + Condition nodes

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Multi-turn chat with session memory

> [card] [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
>
> AI agents with MCP tools in Integration Designer workflows

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Build multi-turn chat experiences with intent routing


# Memory capabilities
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/memory-capabilities

Persist conversation context across messages with automatic session memory retrieval.

## Overview

Session memory lets AI nodes in chat-driven workflows access previous messages from the current
conversation. When enabled, FlowX automatically retrieves recent conversation history and injects it
into the LLM's context — giving the AI agent awareness of what was discussed earlier in the session.

Memory is **per-session** (identified by Chat Session ID) and managed entirely by FlowX. You don't
need to build any memory retrieval logic — just toggle it on per node.

> [card] Automatic retrieval
>
> The recent conversation history is retrieved and attached on each message

> [card] Verbatim context
>
> The last 30 turns are sent to the model in full, oldest to newest — no lossy summarization

> [card] Per-node control
>
> Turn memory on per AI (Custom Agent) or Intent Classification Agent node with the **Use conversation memory** toggle

> [card] Memory tab in console
>
> Inspect the conversation context that was sent to the model in the workflow console log

***

## How memory works

**1. User sends a message**

The Chat component sends the message + `chatSessionId` to the chat-driven workflow.

**2. Memory retrieval**

FlowX retrieves the recent conversation history for the session — the last 30 turns (each a user
message and the agent's response).

**3. Context injection**

For each node with **Use conversation memory** enabled, the retrieved turns are added to the LLM
prompt in full (oldest to newest), giving the AI agent context from earlier in the session.

**4. Response and storage**

After the AI generates a response, FlowX stores both the user message and the agent response,
so they're available as memory on the next message.

***

## What gets sent to the model

When memory is enabled, the recent turns are wrapped in a `<history>` block and added to the prompt,
introduced as "Prior conversation between the user and the assistant (oldest to newest)":

```
<history>
<turn>
<user>How do I verify my account?</user>
<assistant>Navigate to Settings and select Verification.</assistant>
</turn>
<turn>
<user>What documents do I need?</user>
<assistant>You need a valid ID and proof of address.</assistant>
</turn>
</history>
```

* The last **30 turns** are included **in full** — there is no summarization or truncation of older
  turns within that window.
* A turn the user cancelled mid-response is marked as cancelled rather than dropped.

> [!TIP]
>
> Only user messages and agent responses are included in memory. Internal workflow data, routing
> decisions, and intermediate node outputs are not part of the memory.

***

## Enabling memory

![AI node with the Use conversation memory toggle enabled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/custom_agent_use_memory.png)

Memory is controlled per node with the **Use conversation memory** toggle, in the node's **Background**
section. It's available on:

* **AI (Custom Agent)** nodes — for context-aware AI responses
* **Intent Classification Agent** nodes — for more accurate classification using conversation history

**Default:** OFF

When enabled, the node sends the `chatSessionId` with its request; FlowX retrieves the recent turns
and attaches them to the LLM call.

> [!WARNING]
>
> Memory is only available in **conversational** workflows. The toggle does not appear on nodes in
> output-focused workflows.

***

## Inspecting memory in the console

![Memory tab in the workflow console showing the conversation context sent to the model](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)

When an AI node with **Use conversation memory** enabled completes, the workflow console log includes
a **Memory** tab showing the conversation context that was available to the model for that run:

* A **Conversation Summary** heading followed by the conversation's title.
* The most recent user/agent turns from the session.

The node returns this as a `memoryUseSummary` object:

```json theme={"dark"}
{
  "summary": "Account setup",
  "chatMessages": [
    {
      "messageId": "msg-003",
      "userMessage": "What documents do I need?",
      "agentResponse": "You need a valid ID and proof of address."
    },
    {
      "messageId": "msg-002",
      "userMessage": "How do I verify my account?",
      "agentResponse": "Navigate to Settings and select Verification."
    }
  ]
}
```

> [!NOTE]
>
> The **Memory** tab is a preview of recent turns for debugging; the `summary` field carries the
> conversation's title, and `chatMessages` lists the most recent turns. The full set of turns sent to
> the model (up to 30) is what the AI node actually receives — see [What gets sent to the
> model](#what-gets-sent-to-the-model).

> [!TIP]
>
> The Memory tab only appears when `memoryUseSummary` data exists for the workflow instance. If you
> don't see it, verify that **Use conversation memory** is enabled on at least one node.

***

## Storage

| Data | Storage | Details |
| - | - | - |
| Session ID | Browser storage + FlowX Database | Links the client chat instance to the server session |
| Message history | FlowX Database | Complete record of user and agent messages per session |
| Session metadata | FlowX Database | Timestamps, workflow reference, user info |

Session memory is tied to the `chatSessionId` — the same session ID retrieves the same memory across
workflow runs. The Chat component manages session IDs automatically.

***

## Limitations

* Memory is **session-scoped** — there is no cross-session or cross-user memory.
* The last **30 turns** are sent to the model; turns older than that window are not included.
* Memory cannot be manually edited or cleared from the Designer UI.
* Only **user messages** and **agent responses** are stored — internal workflow data is excluded.

***

## Related resources

> [card] [Chat-driven workflows](/5.9/ai-platform/chat-driven-workflows)
>
> Full guide to building chat-driven workflows with memory and intent routing

> [card] [Chat component](/5.9/ai-platform/chat-component)
>
> Runtime behavior, session management, and display modes

> [card] [Intent Classification Agent](/5.9/ai-platform/agent-builder/intent-classification)
>
> Route conversations based on detected user intent with optional memory

> [card] [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
>
> Configure AI nodes with memory, chat reply, and response settings


# AI node types
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/node-types

Understanding the different AI node types available in Agent Builder for building AI workflows.

Agent Builder provides AI nodes organized into categories based on the type of content they process. Combine these nodes to create sophisticated workflows.

![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)

## Node categories

> [card] [Text operations](#ai-text-operations)
>
> Process and analyze text content

> [card] [Document operations](#ai-document-operations)
>
> Work with documents and files

> [card] [Image operations](#ai-image-operations)
>
> Analyze visual content

> [card] [Data operations](#ai-data-operations)
>
> Transform and enrich data

Additionally, the **Custom Agent**, **Context Retrieval**, **Intent Classification Agent**, and **Speech to Text** nodes provide specialized capabilities.

The palette also includes [document utility nodes](#document-utility-nodes) - **Tabular Data Extraction** and **Template Filling** - which process documents deterministically, without calling a model. On SaaS (5.13), Tabular Data Extraction is renamed [Data Parse](#data-parse-node) and also parses XML and JSON. On SaaS (6.0), [Generate Tabular File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node) writes workflow data to a CSV or XLSX file.

> [!NOTE]
>
> **Presets.** The text, document, image, and data operation nodes each come with **presets** — ready-made instruction templates for common tasks. Selecting a preset prefills the node's **Instructions** field (and, where useful, an example response schema), which you can then edit. The presets available depend on the node type — for example, **Document Understanding** offers Content Summarization, Key Information Extraction, Topic Analysis, and Sentiment Analysis, and **Document Extraction** offers Metadata Generation, Named Entity Recognition, and Table Extraction.

![Presets picker on a Text Understanding node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/presets.png)

***

## Intent Classification Agent

Classify user messages and automatically route the workflow to the matching branch — combining AI classification and conditional branching in a single node.

| Node type | Description | Use cases |
| - | - | - |
| **Intent Classification Agent** | Classifies a user message into defined intents and routes to the matching branch | Chatbot routing, email triage, support ticket classification |

### Configuration options

* **User message** — Input text to classify (supports `${}` references)
* **Intents** — Up to 10 natural language intent descriptions, each becoming an output branch
* **Use conversation memory** — Include conversation history for context-aware classification
* **Include Reason for Selection** — Add LLM explanation for the chosen intent
* **Fallback branch** — Automatic "If No Intent Matches" path

> [card] [Intent Classification Agent](./intent-classification)
>
> Learn more about configuring intents, output format, and routing behavior

***

## Context Retrieval

Perform RAG (Retrieval-Augmented Generation) searches against a Knowledge Base and return relevant chunks — without calling an LLM.

| Node type | Description | Use cases |
| - | - | - |
| **Context Retrieval** | Queries a Knowledge Base and returns matching chunks with relevance scores | RAG pipelines, document search, context gathering for downstream AI nodes |

### Configuration options

* **Source** — Knowledge Base or Memory (Memory only available in chat-driven workflows)
* **Knowledge Base** — Select which Knowledge Base to query (when source is Knowledge Base)
* **User Query** — the search query, supports process variable expressions
* **Search type** — Hybrid (default), Semantic, or Keywords
* **Max Number of Chunks** — how many chunks to return (1-10)
* **Min Relevance Score** — minimum relevance threshold (0-100%)
* **Metadata Filters** — structured filters with typed operators and AND/OR grouping to refine results by chunk metadata
* **Use advance metadata filters** — toggle for expression-based filtering
* **Use Re-rank** — re-rank retrieved chunks before returning

### Output format

The node outputs an array of retrieved chunks, each containing:

| Field | Description |
| - | - |
| `chunkContent` | The text content of the retrieved chunk |
| `chunkMetadata` | Metadata associated with the chunk |
| `relevanceScore` | Similarity score between the query and the chunk |
| `searchType` | Search strategy that returned this chunk: `HYBRID`, `SEMANTIC`, or `KEYWORD`. Only emitted when the RAG service returns a non-null value. |
| `contentSource` | The store the chunk belongs to (field name preserved for API compatibility) |

> [card] [Context Retrieval](./context-retrieval)
>
> Learn more about configuring Context Retrieval nodes

***

## Custom Agent

Create custom agents with advanced capabilities powered by Model Context Protocol (MCP) tools, optional Knowledge Base retrieval, and direct chat reply in Chat Driven workflows.

| Node | Description | Use cases |
| - | - | - |
| **Custom Agent** | Runs your own Instructions, and can grow into an agent with knowledge bases, tools, MCP servers, and conversation memory | Classification with your own categories, grounded Q\&A, multi-step tasks that call tools |

### Configuration options

* **Instructions** *(mandatory)* — The agent's role, tasks, and expected input/output. Sent as the System message and **cached** by the LLM between executions, so `${variable}` references are not allowed in this field. Limited to 10,000 characters (SaaS · 5.11).&#x20;
* **Background → Use conversation memory** — Include conversation history in the LLM call (Chat Driven workflows only)
* **Background → Knowledge Base** — Attach one or more knowledge bases for RAG retrieval; includes Search Type (Hybrid, Semantic, or Keywords) and Re-rank options. When several knowledge bases are attached, the agent searches all of them, with one retriever per knowledge base (available starting with 5.9.2).&#x20;
* **Background → Enable agentic knowledge base search** — When ON (available once a Knowledge Base is selected), the agent runs an agentic retrieval flow instead of a single fixed search, and gains **Additional controls → Settings** with **Max attempts** (default 1) and **Subqueries per attempt** (default 3). Off by default. (SaaS · 5.11)&#x20;
* **Background → Filtering options** — Once a Knowledge Base is attached: **Manual** (default) applies the **Metadata Filters** you configure; **Agentic** lets the agent build the metadata filter at runtime from the knowledge base's metadata keys, hides the Metadata Filters control, and notes `Agent builds the filter at runtime`. The per-knowledge-base retrieval block (Search Type / Number of Chunks / Min Relevance Score / Re-rank) also shows whenever a Knowledge Base is attached, independent of both toggles. For per-tenant isolation use Manual — an agent-authored filter is not an access-control mechanism. (SaaS · 5.11)&#x20;
* **Background → Context** — Free-text field for the per-execution prompt; supports `${variable}` references. Sent as the User message and not cached.
* **Background → Use only referenced values as input** — Send only values referenced in the prompt to the LLM; narrows context and reduces token usage
* **Tools → MCP Servers** — Attach MCP tools the agent can call
* **Tools → Add tool → Built-in Tools** — Select tool categories to give the agent ready-made helper tools: **Math tools**, **List tools**, **Date tools**, **Text tools**, and **Web search**. Each row lists the tools it enables; nothing is on by default. (SaaS · 5.12)&#x20;
* Before 5.12, built-in tools were two toggles: **Use Web Search Tool** and **Use built-in tools** (calculator, compare, sort, filter; SaaS · 5.10). A node last saved with those toggles keeps working; they map to the **Web search**, **Math tools**, and **List tools** categories.&#x20;
* **Tools → Workflow tools** — Attach FlowX workflows the agent can call as tools. For each workflow, add a **When should the agent use this workflow?** hint (max 2,000 characters) that tells the agent what the workflow does. The workflow's input parameters become the tool's arguments; a workflow with no input parameters is not eligible. Up to 10 workflow tools per agent. (SaaS · 5.11)&#x20;
* **Tools → Functions** — Attach [reusable functions](/5.9/docs/building-blocks/reusable-resources/reusable-functions) the agent can call as tools. A function needs typed input and output parameters to be eligible. (SaaS · 5.12)&#x20;
* **Personal Information Guard** — Toggle PII redaction on the node's input and/or output (see [Personal Information Guard](/5.9/ai-platform/personal-information-guard))
* **Response → Send as Chat Reply** — In Chat Driven workflows, deliver the response directly to the Chat component as Markdown
* **Response → Show Reasoning** — When ON, the agent explains how it reached its answer. The chat reply is unchanged; the reasoning is added to the node's output and run logs. (SaaS · 5.11)&#x20;
* **Response → Include Task for Prompt Suggestions** — In Chat Driven workflows, generate AI follow-up prompts shown in the Chat component after the response
* **Response Key** — Key where the node output is stored in the workflow data
* **Response Schema** — Expected JSON structure of the LLM response (hidden when Send as Chat Reply is ON). Supports `${variable}` placeholders resolved at runtime against workflow data, with substituted values coerced to the schema-declared types (SaaS · 5.10).&#x20;

> [!NOTE]
>
> **Web Search.** With the **Web search** category selected, the agent can look up up-to-date information from the public web and use it in its response. There are no extra settings to configure — the agent decides when to search based on its instructions and the user's request. Nothing is selected by default.

> [!NOTE]
>
> **Generate prompt and response schema.** Open the AI Developer assistant from the Custom Agent node header, describe what you want the node to do, and it generates the Instructions prompt, the Context prompt, and — with **Also generate response schema** enabled — the Response Schema, then applies them to the node. Use it to create a configuration from a description, or to refine an existing prompt or schema. (SaaS · 5.11)

> [card] [Custom Agent in Chat Driven workflows](/5.9/ai-platform/chat-driven-workflows#custom-agent-node)
>
> Full reference for Use conversation memory, Send as Chat Reply, Prompt Suggestions, and other Chat Driven specifics

***

## Speech to Text

Transcribe audio to text within integration workflows.

| Node type | Description | Use cases |
| - | - | - |
| **Speech to Text** | Transcribe audio files into text with language detection and confidence metadata | Voice message processing, audio transcription, accessibility, chat-driven workflows with voice input |

### Configuration options

* **File Source** — Document Plugin, S3, or Chat Input (chat-driven workflows)
* **File Path** — Path to the audio file (supports `${}` references); becomes a test-file dropdown when **Use Test File** is on
* **Use Test File** — Upload a sample audio file for development testing
* **Response Key** — Key under which the transcript and metadata are stored

> [card] [Speech to Text](./speech-to-text)
>
> Learn more about configuring transcription and chat voice integration

***

## AI Text Operations

Text nodes work on text you pass in through **Context**. Each node offers presets for common tasks.

| Node | Presets |
| - | - |
| **Text Generation** | Summarization, Paraphrasing, Completion, Expansion, Translation |
| **Text Understanding** | Sentiment Analysis, Topic Modeling, Named Entity Recognition, Intent Recognition, Language Detection, Contextual Understanding |
| **Text Transformation** | Formatting, Simplification, Complexification, Tone Adjustment |
| **Text Extraction** | Keyphrase Extraction, Metadata Generation, Table or Structured Data Extraction |

### Configuration options

* **Preset** — Pick a ready-made task to prefill **Instructions** and, where the preset has one, the **Response Schema**. Both stay editable.
* **Instructions** — The task and rules for the model
* **Context** — The input for each run; supports `${}` references
* **Response Schema** — Expected JSON structure of the response
* **Response Key** — Key where the node output is stored in the workflow data

***

## AI Document Operations

Process documents to extract data, generate reports, or understand content.

| Node | Description | Use cases |
| - | - | - |
| **Document Generation** | Automatically build reports or complete templates based on given inputs | Report generation, template completion |
| **Document Extraction** | Identify and extract structured data, entities or metadata from documents | Form processing, invoice data extraction |
| **Document Understanding** | Analyze documents to extract meaning, topics, sentiment, or important information | Document classification, content analysis |
| **Extract Data from File** | Extract text and data from documents and images with configurable extraction strategies | OCR, PDF text extraction, image data extraction, signature detection |

**Document Extraction** and **Document Understanding** take a file, not raw text: set **Document Source** and **File Path**, and the document is parsed before it reaches the model. To work on text you already have, use a [text node](#ai-text-operations) such as **Text Extraction**.

| Node | Presets |
| - | - |
| **Document Generation** | Automated Report Writing, Document Completion, Template Creation |
| **Document Extraction** | Metadata Generation, Named Entity Recognition, Table Extraction |
| **Document Understanding** | Content Summarization, Key Information Extraction, Topic Analysis, Sentiment Analysis |

> [card] [Extract Data from File](./extract-data-from-file)
>
> Learn more about configuring extraction strategies, image extraction, and signature detection

Document Generation, Document Extraction, and Document Understanding use the same **Preset**, **Instructions**, **Response Schema**, and **Response Key** settings as the [text nodes](#ai-text-operations).

***

## Document utility nodes

These nodes in the same palette handle documents without calling a model. They are not AI nodes: they run deterministically, cost no tokens, and take no instructions or response schema.

| Node | Description | Use cases |
| - | - | - |
| **Tabular Data Extraction** | Parse a CSV, XLS, or XLSX file into structured rows | Bulk imports, reference data loads, spreadsheet-driven onboarding. On SaaS (5.13), named **Data Parse** and also parses XML and JSON |
| **Template Filling** | Render a document template with variable data into a PDF or DOCX | Contracts, offer letters, statements, regulatory forms |
| **[Generate Tabular File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node)** | Write workflow data to a CSV or XLSX file stored against the current run (SaaS 6.0) | Report exports, reconciliation files, data handoffs to spreadsheet users |

> [!NOTE]
>
> Use **Tabular Data Extraction** for spreadsheets only. A table *inside* a PDF or a scanned payslip is not tabular data in this sense - reach for **Document Extraction** or **Extract Data from File** instead. On SaaS (5.13), [Data Parse](#data-parse-node) also accepts XML and JSON files.&#x20;

### Tabular Data Extraction configuration

| Option | Description |
| - | - |
| **File Path** | Path or expression pointing to the spreadsheet |
| **Sheet** | Sheet name, for XLS and XLSX files; leave empty for the first sheet |
| **Response Key** | Key under which the extracted rows land in workflow state |

![Tabular Data Extraction node configuration with File Path, Sheet, and Response Key](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/tabular-data-extraction-node-config.png)

### Data Parse node

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![Data Parse node on the workflow canvas with File Path, Sheet, and Response Key filled in, next to the Data Parse entry in the node palette](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/data-parse-node-config.png)

Tabular Data Extraction is renamed **Data Parse** and, besides CSV, XLS, XLSX, and XLSM spreadsheets, also parses **XML** and **JSON** files into structured JSON. The options are the same; **Sheet** applies to Excel files only and is ignored for CSV, XML, and JSON. The result lands under `<responseKey>.data`: rows for spreadsheets, an object tree for XML and JSON. Existing nodes keep working unchanged.

For the XML conversion rules and size limits, see [Data Parse: XML and JSON support](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support).

### Template Filling configuration

| Option | Description |
| - | - |
| **Template** | The document template to render |
| **Language** | Template language or locale, for example `en` |
| **Folder** | Destination folder for the generated file, for example `${client.id}` |
| **Document Tag** | Tag recorded for the generated file, for example `ContractTemplate` |
| **Document format** | `PDF` or `DOCX` |
| **Template Variables** | A value for each template variable, either fixed text or a `${}` expression |
| **Input Mapping** | On SaaS (5.13), maps workflow data onto the template's input parameters in the data mapper. Nodes created earlier show an **Enable data mapping** toggle that switches between this and **Template Variables** |
| **Response Key** | Key under which the generated document reference lands |

![Template Filling node configuration with Template, Language, Folder, Document Tag, and Document format](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/template-filling-node-config.png)

> [!NOTE]
>
> **Template**, **Language**, and **Document Tag** are mandatory - the node cannot render without them. **Response Key** is also required, since the generated document reference lands under it.

For a step-by-step guide to mapping workflow data into the template and building the download URL, see [Fill a document template from a workflow and download it](/5.9/cookbooks/generate-and-download-a-document).

***

## AI Image Operations

Analyze visual content to generate captions, extract details, or identify objects.

| Node | Presets |
| - | - |
| **Image Description** | Image Captioning, Image Detail Extraction |
| **Image Analysis** | Object Recognition, Emotion Analysis, Scene Understanding |

Image nodes take the image as a file through **Document Source** and **File Path**, and use the same **Preset**, **Instructions**, **Response Schema**, and **Response Key** settings as the [text nodes](#ai-text-operations). To read text from a scanned document or image, use **Extract Data from File**.

***

## AI Data Operations

Data nodes work on structured data you pass in through **Context**.

| Node | Presets |
| - | - |
| **Data Enrichment** | Data Annotation, Relationship Mapping, Contextual Information |
| **Data Generation** | Synthetic Data Creation, Template Filling, Data Completion |
| **Data Transformation** | Data Cleaning, Data Normalization, Data Aggregation, Data Restructuring |

Data nodes use the same **Preset**, **Instructions**, **Response Schema**, and **Response Key** settings as the [text nodes](#ai-text-operations).

***

## Structured-output validation and run diagnostics

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

When an AI node has a **Response Schema**, the platform validates the LLM response against it and automatically retries with a repair prompt when validation fails. If the response still cannot be repaired, the node fails with a categorized error instead of passing malformed output downstream. This validate-and-repair retry runs when the node has no tools. When the node uses a Knowledge Base, an MCP server, or a built-in tool such as web search, the schema still shapes the response, but the response isn't validated and repaired afterwards.

The node's **Logs** now surface richer run diagnostics: the failure category and reason, the rejected output, the model's reasoning summary (for reasoning models), and the number of schema-validation retry attempts.

***

## What happens when an AI node can't reach its AI service?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The platform retries an AI node automatically when its AI service can't be reached. This covers every AI node except Deep Research, including Custom Agent and Context Retrieval nodes. By default, a node retries up to 10 times, 30 seconds apart, when:

* the AI service is unreachable
* the LLM provider is unavailable
* the LLM provider rate-limits the request
* the connection to the LLM provider fails

Timeouts are not retried by default, because the node may already have called its tools. Deep Research nodes are left out because a retry repeats the whole research run.

### How do I change the retry settings?

Open the node's **Settings** tab and toggle **Allow Retry** **ON**. Then set:

| Field | What it controls |
| - | - |
| **Retry count** | How many times the node retries after the first attempt. Prefilled with `2`. |
| **Interval (ms)** | How long the node waits before a retry, in milliseconds. |
| **Exponential** | Increases the wait after each attempt instead of keeping it fixed. |
| **Backoff coefficient** | With **Exponential** on, the factor the wait grows by on each retry. Prefilled with `2`. |
| **Max interval (ms)** | With **Exponential** on, the longest the node waits between retries, in milliseconds. |

Fields you leave empty fall back to the defaults: 10 retries, 30 seconds apart, fixed wait. With **Exponential** on, the wait before retry *n* is **Interval** × **Backoff coefficient**<sup>n-1</sup>, capped at **Max interval**. For example, an interval of `2000` and a coefficient of `2` waits 2, 4, 8, then 16 seconds.

Your own settings retry more broadly than the default: the node also retries after a timeout and after any failed response, not only when the service is unreachable. Toggle **Allow Retry** **OFF** to return the node to the default retry.

### What happens after the last retry?

If the node has a failure exit connected, the workflow continues down that path. Otherwise the workflow run fails with the error from the AI service.

> [!NOTE]
>
> A single-node run from the Designer doesn't retry an unreachable service. In the workflow run logs, an AI node on the default retry shows one entry with its last attempt. With **Allow Retry** **ON**, the logs show each attempt as its own `Running node: <name> Retry N` line.

***

## Combining nodes

Nodes can be connected in workflows to create complex processing pipelines:

```
Extract Data from File → Text Understanding (Named Entity Recognition preset) → Script (validation) → End
```

### Best practices

> [accordion] Start simple
>
> Begin with a single node and add complexity incrementally. Test each addition before moving on.

> [accordion] Use validation nodes
>
> Add validation steps after extraction to ensure data quality before processing continues.

> [accordion] Handle errors
>
> Include fallback paths for when nodes fail or return low-confidence results.

> [accordion] Monitor performance
>
> Track execution times and accuracy metrics to identify bottlenecks and improvement opportunities.

## Related resources

> [card] [Agent Builder overview](./overview)
>
> Get started with Agent Builder

> [card] [Use cases](./use-cases)
>
> See real-world examples

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Multi-turn chat with Custom Agent node changes for chat replies and memory


# Agent Builder
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/overview

Create custom AI agents without code using the FlowX Agent Builder - a no-code/low-code platform for business users.

The FlowX Agent Builder is a no-code/low-code platform that enables business users to create custom AI agents without relying on IT or data science teams.

```mermaid theme={"dark"}
flowchart LR
    subgraph sources [" "]
        KB[Knowledge Base]
        API[APIs]
        DB[Database]
    end

    sources --> BUILD

    subgraph BUILD [Agent Builder]
        C[Configure] --> T[Test] --> D[Deploy]
    end

    D --> Chat
    D --> Workflows
    D --> API2[REST API]
```

Agents connect to your data through multiple integration options:

* **Knowledge Bases** - Ground responses in your documents using RAG
* **MCP servers** - Connect external tools via Model Context Protocol
* **REST APIs** - Call any HTTP endpoint
* **FlowX Database** - Query and store structured data
* **Kafka** - Event-driven integrations

## What can you build?

Agent Builder allows you to create specialized AI agents that can:

> [card] Process documents
>
> Extract, validate, and analyze data from various document types

> [card] Understand content
>
> Perform sentiment analysis, topic modeling, and named entity recognition

> [card] Generate content
>
> Create summaries, translations, and complete documents

> [card] Analyze images
>
> Recognize objects, extract text, and understand scenes

> [card] Make decisions
>
> Provide risk assessments and compliance checks with full auditability

## Key benefits

### Business empowerment

* **Drag-and-drop interface** accessible to non-technical users
* **Pre-built templates** for common use cases
* **Reduced time-to-market** for AI solutions

### Enterprise-grade features

* **Full audit trails** and explainable AI decisions
* **Integration with existing workflows** and systems
* **Compliance-ready** with regulatory requirements
* **Tool call limits** — agents are capped at 20 tool calls per run to prevent runaway operations, and at 10 calls to workflow tools within that run (SaaS · 5.11). Past the workflow-tool cap the call is not dispatched and the agent is asked to answer with what it already has, so the run continues rather than failing&#x20;

## Core agent categories

> [accordion] Document processing agents
>
> * Document extraction and validation
> * Cross-document consistency checks
> * Metadata creation and classification

> [accordion] Analysis agents
>
> * Sentiment and emotion analysis
> * Risk assessment and fraud detection
> * Customer behavior analysis for upselling

> [accordion] Generation agents
>
> * Report writing and document completion
> * Content summarization and paraphrasing
> * Multi-language translation

## Getting started

**1. Choose your approach**

* Start with **pre-built templates** for common scenarios
* Create **from scratch** with custom instructions

**2. Configure your agent**

* Define input sources (documents, images, structured data)
* Set processing logic and validation rules
* Configure output formats and destinations

**3. Test and deploy**

* Test with sample documents and data
* Review confidence scores and validation results
* Deploy into your FlowX workflows

## Agent Designer interface

The Agent Designer provides a visual canvas for building AI workflows:

| Component | Description |
| - | - |
| **Left panel** | Available actions and node types to drag onto canvas |
| **Canvas** | Visual workflow designer where you connect nodes |
| **Properties** | Configuration panel for selected nodes |
| **Test panel** | Run tests with sample data |

## Related resources

> [card] [Node types](./node-types)
>
> Learn about Generation, Understanding, Extraction, and Analysis nodes

> [card] [Use cases](./use-cases)
>
> Real-world examples: loan processing, mortgage validation, customer intelligence

> [card] [Config-time agents](../pre-built-agents/overview)
>
> Design-time AI assistants for FlowX Designer

> [card] [Using agents](../using-agents/overview)
>
> Learn how to integrate agents into your apps

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Build multi-turn chat experiences with session memory and intent routing


# Speech to Text
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/speech-to-text

Transcribe audio to text within integration workflows.

## Overview

The **Speech to Text** node is a workflow node that transcribes audio files into text. It reads audio from a configured source, sends it to the speech-to-text service, and returns the transcript along with language detection and confidence metadata. The node works in both standard and chat-driven workflows, and integrates with the FlowX Document Plugin for file storage.

![Speech to Text node configuration in Integration Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/speech_to_text.png)

> [card] Transcribe audio
>
> Convert audio recordings to text with language detection and confidence scores

> [card] Multiple file sources
>
> Read audio from Document Plugin, S3, or directly from chat voice input

> [card] Chat integration
>
> Automatically processes voice messages in chat-driven workflows

> [card] Test files for development
>
> Upload sample audio to validate your workflow before connecting a live source

***

## Configuration

**1. Open your workflow**

Open your workflow in **Integration Designer**.

**2. Add the node**

Add a **Speech to Text** node from the node palette.

**3. Configure the settings**

Configure the settings described below.

***

### File Source

**File Source** `enum` *required*

Where the audio file is located.

| Source | Description | Availability |
| - | - | - |
| **Document Plugin** | Read audio from a file stored in the FlowX Document Plugin | Standard workflows |
| **S3 Protocol** | Read audio from S3-compatible storage | Standard workflows |
| **Chat Input** | Automatically receive audio from a voice message in the chat UI | Chat-driven workflows only |

In chat-driven workflows, the file source is set to **Chat Input** automatically.

![Voice input configuration on a chat-driven workflow Start node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/voice_input_start_wkf_node.png)

**Use Test File** `boolean`

Upload and use a sample audio file for testing without connecting a live source. When turned on, **File Path** becomes a dropdown of available test files instead of a free-text input.

**Default:** OFF

**File Path** `string` *required*

Path to the audio file. The control changes based on **Use Test File**:

* **Use Test File OFF** — free-text input. Supports `${expression}` placeholders for dynamic values from workflow data. Only meaningful when **File Source** is `Document Plugin` or `S3 Protocol`.
* **Use Test File ON** — dropdown labelled **Select Test File**, listing the test files uploaded to this node.

**Example:** `${inputData.audioFilePath}`

**Response Key** `string` *required*

The key under which the transcript and metadata are stored in the workflow data.

**Example:** `speechResult`

***

## Supported audio formats

| Format | MIME Type |
| - | - |
| MP3 | `audio/mpeg` |
| WAV | `audio/wav` |
| M4A | `audio/x-m4a` |
| AAC | `audio/aac` |
| OGG | `audio/ogg` |

## File size limits

| Workflow type | Maximum size |
| - | - |
| Conversational | 5 MB |
| Standard | 10 MB |

Test files support the same audio formats listed above, with a maximum size of 10 MB, or 5 MB in a chat-driven workflow.

***

## Output

The node writes the transcript and metadata under the configured **Response Key**.

**Standard workflows** output nested under the response key:

```json theme={"dark"}
{
  "responseKey": {
    "transcript": "The transcribed text content",
    "language": "en",
    "confidence": 1.0,
    "responseTime": 2.34,
    "audioFileName": "recording.mp3"
  }
}
```

**Chat-driven workflows** output at the top level for chat integration:

```json theme={"dark"}
{
  "userMessage": "The transcribed text content",
  "userMessageConfidence": 1.0
}
```

| Field | Type | Description |
| - | - | - |
| `transcript` / `userMessage` | string | The transcribed text |
| `language` | string | Detected language code (e.g., `en`, `fr`, `de`) |
| `confidence` / `userMessageConfidence` | number | Confidence score (0.0 to 1.0) |
| `responseTime` | number | Processing time in seconds |
| `audioFileName` | string | Original audio file name |

***

## Chat-driven workflow integration

In chat-driven workflows, the Speech to Text node is required for the [Chat component](/5.9/ai-platform/chat-component) voice input feature to work: enabling **Enable Voice Input** on the Chat Input component only records and uploads the audio. Without this node in the workflow, incoming voice messages are never transcribed and the agent cannot respond to them.

The two features work together as follows:

1. A user records a voice message in the chat UI
2. The audio file is sent to the workflow as a chat input
3. The Speech to Text node (with **Chat Input** file source) transcribes the audio
4. The transcript is set as the `userMessage`, making it available to downstream nodes (Custom Agent, Intent Classification Agent) as if the user had typed it

> [!NOTE]
>
> When processing chat voice input, the audio file metadata is preserved in the conversation context. This allows conversation history to reference which messages originated from voice input.

***

## Node connections

The Speech to Text node has two output handles:

| Handle | Description |
| - | - |
| **Success** | The transcription completed and output is available under the response key |
| **Fail** | The transcription failed (unsupported format, file not found, service error) |

Connect downstream nodes to the appropriate handle to manage both successful and failed transcription scenarios.

***

## Best practices

> [card] Match file source to workflow type
>
> Use **Chat Input** for chat-driven workflows and **Document Plugin** or **S3** for standard workflows.

> [card] Keep audio files within size limits
>
> Audio files exceeding the size limit (5 MB conversational, 10 MB standard) will fail. Validate file size before reaching the node if the source is user-provided.

> [card] Use test files during development
>
> Upload a sample audio file to validate your workflow configuration before connecting to a live source.

> [card] Handle failures
>
> Always connect the **Fail** handle to a fallback path, especially when processing user-uploaded audio that may be in an unsupported format.

***

## Related resources

> [card] [Chat component](/5.9/ai-platform/chat-component)
>
> Voice input and conversational UI for chat-based workflows

> [card] [Chat-driven workflows](/5.9/ai-platform/chat-driven-workflows)
>
> Build multi-turn conversations with AI Triggers and context

> [card] [AI node types](./node-types)
>
> Overview of all AI workflow node types

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Build and manage integration workflows


# Agent Builder use cases
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/use-cases

Real-world examples of what you can build with FlowX.AI Agent Builder.

Agent Builder supports a wide range of AI-powered automation scenarios. Below are the primary categories with examples drawn from production implementations.

## Document processing and extraction

Extract structured data from unstructured documents — invoices, contracts, shipping documents, financial statements — using Document Extraction nodes with tailored instructions per document type.

> [accordion] Logistics document processing
>
> An email-triggered pipeline processes carrier emails and their attachments:
>
> * **Classify** documents by type (BOL, invoice, rate confirmation, lumper receipt, fuel receipt, and more)
> * **Extract** structured fields from each document type using specialized TEXT\_EXTRACTION nodes
> * **Reconcile** extracted data against a Transportation Management System (TMS)
> * **Surface exceptions** for human review via task management
>
> **AI nodes used:** Document Extraction (12 document types), Custom Agent (12 comparison workflows, email summary)
>
> **Patterns involved:** [Fan-out extraction](../patterns/fan-out-extraction), [AI comparison](../patterns/ai-comparison-reconciliation)
>
> **Build it:** the [Reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation) cookbook walks through a single-document version of this pipeline, step by step.

> [accordion] Mortgage document validation
>
> Process mortgage application packages by extracting product data from bank documentation:
>
> * **Extract** structured product details (interest rates, fees, insurance requirements) from bank product sheets
> * **Weight** income and debt values per bank-specific rules using AI extraction
> * **Validate** legal/regulatory eligibility using AI understanding
>
> **AI nodes used:** Document Extraction (income/debt/product extraction), Custom Agent (eligibility checks)
>
> **Patterns involved:** [Hybrid AI + business rules](../patterns/hybrid-ai-rules), [Fan-out extraction](../patterns/fan-out-extraction)

***

## Conversational AI

Build chat-based assistants that understand user intent, maintain conversation context, and provide personalized responses grounded in your data.

> [accordion] Mortgage advisor chatbot
>
> A conversational assistant that guides users through mortgage product selection:
>
> * **Detect intent** — classify user messages as greetings, product inquiries, data input, or other
> * **Route** to specialized handlers (small talk, personalized offers, knowledge base Q\&A)
> * **Generate** personalized mortgage consultant reports with comparative cost tables
> * **Maintain** conversation history across sessions
>
> **AI nodes used:** Intent Classification Agent (intent detection and routing), Custom Agent (responses, reports, knowledge base RAG)
>
> **Patterns involved:** [Intent classification](../patterns/intent-classification-routing), [Knowledge base RAG](../patterns/knowledge-base-rag), [Session state](../patterns/session-state-management)

***

## AI-augmented decision making

Combine AI capabilities with deterministic business logic for auditable, explainable decision-making.

> [accordion] Product eligibility and scoring
>
> Evaluate financial product eligibility using a pipeline that mixes AI and business rules:
>
> * **AI extracts** income weights and debt factors from bank-specific rule documents
> * **Business rules** compute PMT, DTI ratios, maximum loan amounts, and currency conversions
> * **AI filters** products by qualitative criteria (loan type, sustainability features) with fuzzy matching
> * **Business rules** normalize scores and rank the top products
> * **AI generates** a professional consultant report with the final recommendations
>
> **AI nodes used:** Document Extraction (income weights, debt factors), Custom Agent (product filtering, report generation)
>
> **Patterns involved:** [Hybrid AI + business rules](../patterns/hybrid-ai-rules)

> [accordion] Document reconciliation
>
> Compare AI-extracted document data against system-of-record values:
>
> * **Compare** field-by-field with structured exception reporting
> * **Generate** match rates and confidence scores per document
> * **Flag** mismatches, missing fields, and derived value discrepancies
> * **Route** exceptions to human reviewers based on severity
>
> **AI nodes used:** Custom Agent (comparison agents per document type)
>
> **Patterns involved:** [AI comparison and reconciliation](../patterns/ai-comparison-reconciliation)

***

## Email automation

Process incoming emails and their attachments automatically using email triggers and AI workflows.

> [accordion] Carrier email processing
>
> Monitor an email inbox for incoming carrier communications:
>
> * **Trigger** workflows automatically when emails arrive (IMAP integration)
> * **Summarize** email content and classify intent (invoice submission, payment inquiry, dispute)
> * **Extract** and process all attachments through the document pipeline
> * **Look up** related orders in external systems (TMS) by BOL number
> * **Notify** relevant staff of exceptions via email templates
>
> **AI nodes used:** Custom Agent (email summary, comparison), Document Extraction (attachments)
>
> **Data sources:** Email Trigger, REST API (TMS), FlowX Database

***

## Building your own use case

**1. Identify the AI tasks**

Map which steps in your process need AI (extraction, classification, generation, comparison) versus deterministic logic (calculations, routing, validation).

**2. Choose your patterns**

Select from the [AI patterns](../patterns/overview) that match your needs. Most apps combine 2-4 patterns.

**3. Design the data flow**

Define your data sources, data model, and how data moves between processes, workflows, and AI nodes.

**4. Build incrementally**

Start with a single AI node (e.g., one document type extraction), validate it works, then expand to the full pipeline.

**5. Add human review**

Use task management views for exception handling and quality assurance, especially for high-stakes decisions.

## Related resources

> [card] [Tutorials](../tutorials/overview)
>
> End-to-end build guides based on production apps

> [card] [AI patterns](../patterns/overview)
>
> Reusable architectural patterns

> [card] [Node types](./node-types)
>
> Detailed node reference

> [card] [Using agents](../using-agents/overview)
>
> Deploy agents in your apps


# Web Page Extractor
Source: https://docs.flowx.ai/5.9/ai-platform/agent-builder/web-page-extractor

Collect readable content from web page URLs with configurable crawling depth, link following, and scrape speed.

## Overview

The **Web Page Extractor** node is a workflow node that collects readable content from web page URLs. It supports static URL lists and dynamic URL generation, configurable crawling depth with link following, and adjustable scrape speed presets.

![Web Page Extractor node configuration with URLs, Crawl Depth, and Scrape Speed settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)

> [card] Static or dynamic URLs
>
> Provide a fixed list of URLs or generate them dynamically from workflow data

> [card] Link following
>
> Optionally follow links on pages up to a configurable depth

> [card] PDF processing
>
> Extract content from PDF files linked on the page

> [card] Scrape speed control
>
> Choose from speed presets or define custom rate limits and concurrency

> [card] File downloads
>
> Download attached files (.docx, .xlsx, .pdf) found during crawling and store them automatically

***

## Configuration

**1. Open your workflow**

Open your workflow in **Integration Designer**.

**2. Add the node**

Add a **Web Page Extractor** node from the **Tools** category in the left panel.

**3. Configure URL source and extraction settings**

Configure the settings described below.

***

### URL source

**URL Mode** `enum` *required*

How URLs are provided to the node.

| Mode | Description |
| - | - |
| **Static** | Provide a fixed list of up to 20 URLs |
| **Dynamic** | Generate URLs from a workflow data key using `${expression}` syntax |

**Default:** `Static`

**URLs** `string[]`

List of URLs to extract content from. Only available when **URL Mode** is `Static`.

**Maximum:** 20 URLs

URLs must use `http://` or `https://` protocol. Supports `${variable}` placeholders for dynamic values.

**Dynamic Link** `string`

A workflow data key or expression that resolves to a URL at runtime. Only available when **URL Mode** is `Dynamic`.

**Example:** `${inputData.targetUrl}`

***

### Crawl depth

**Follow Links** `boolean`

When turned on, the extractor follows links found on the page up to the configured depth.

**Default:** OFF

**Depth of Crawling** `number`

How many levels of links to follow from the starting page. Only available when **Follow Links** is turned on. Displayed in the panel as a slider with the current value shown to the right (for example, *2 levels*).

**Range:** 0–10

**Default:** `0`

**Crawl URLs Containing** `string[]`

Optional list of substring filters applied to discovered links — only URLs that contain at least one of the configured fragments are followed. Click **Set Filters** to open the filter editor. Only available when **Follow Links** is turned on.

**Process Linked PDFs** `boolean`

When turned on, extracts content from PDF files linked on the page. Only available when **Follow Links** is turned on.

**Default:** OFF

***

### Download attached files

When turned on, the extractor downloads attached files (.docx, .xlsx, .pdf) found during crawling and stores them using the configured document destination.

**Download Attached Files** `boolean`

When turned on, files discovered during crawling are downloaded and stored automatically. Supported file types include `.docx`, `.xlsx`, and `.pdf`.

**Default:** OFF

**Document Destination** `enum`

Where downloaded files are stored. Only available when **Download Attached Files** is turned on.

| Option | Description |
| - | - |
| **Document Plugin** | Store files through the FlowX Document Plugin. Requires **Folder Name**. |
| **S3 Protocol** | Store files directly using S3-compatible storage. |

**Folder Name** `string` *required*

Identifier used to associate the file with its business owner. Only available when **Download Attached Files** is turned on and **Document Destination** is `Document Plugin`.

***

### Scrape speed

**Scrape Speed** `enum` *required*

Controls how aggressively the node requests pages from the target server.

| Preset | Description |
| - | - |
| **Slow** | Conservative rate limiting — best for fragile or rate-limited servers |
| **Moderate** | Balanced speed and reliability |
| **Fast** | Aggressive crawling — assumes the target server can handle high traffic |
| **Custom** | Define your own rate limit and concurrency |

**Default:** `Moderate`

**Rate Limit** `number`

Maximum requests per second. Displayed in the panel as a slider labelled in `req/s`. Only available when **Scrape Speed** is `Custom`.

**Default:** `2 req/s`

**Concurrency** `number`

Number of concurrent requests. Displayed in the panel as a slider labelled in `parallel`. Only available when **Scrape Speed** is `Custom`.

**Default:** `3 parallel`

***

### Response key

**responseKey** `string` *required*

The key where extracted content is stored in the workflow data.

**Example:** `extractedContent`

***

### Timeout and retry

**Timeout** `number`

Request timeout in milliseconds. If the extraction exceeds this duration, the node fails.

**Retry Config** `object`

Optional retry strategy for failed requests.

| Field | Description | Default |
| - | - | - |
| **Retry Type** | `Fixed` or `Exponential` backoff | — |
| **Max Attempts** | Maximum retry attempts | `2` |
| **Backoff Period** | Delay between retries (ms) | `1000` |
| **Max Backoff Period** | Maximum delay for exponential backoff (ms) | `120000` |
| **Backoff Multiplier** | Multiplier for exponential backoff | `2` |

***

## Best practices

> [card] Start with Moderate speed
>
> Use the Moderate preset unless you know the target server's capacity. Switch to Fast only for internal or robust servers.

> [card] Limit crawl depth
>
> Keep **Depth of Crawling** low (1–3) to avoid excessive page requests. Deep crawls can be slow and may trigger rate limiting.

> [card] Use dynamic URLs for runtime flexibility
>
> When the target URL comes from user input or a previous workflow step, use Dynamic mode with `${expression}` placeholders.

> [card] Set timeouts for external sites
>
> Always configure a timeout when crawling external websites to avoid blocking the workflow on slow or unresponsive servers.

***

## Related resources

> [card] [Extract Data from File](./extract-data-from-file)
>
> Extract text and data from documents and images

> [card] [AI node types](./node-types)
>
> Overview of all AI workflow node types

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Build and manage integration workflows


# Agent catalog
Source: https://docs.flowx.ai/5.9/ai-platform/agent-catalog

The 246 pre-designed AI agents in the FlowX.AI agent catalog, listed by industry and business area, with pointers to the typologies and nodes used to build them.

The [FlowX.AI agent catalog](https://www.flowx.ai/ai-agents) publishes **246 pre-designed AI agents** for regulated industries: **Banking (80)**, **Insurance (69)**, and **Logistics (97)**. This page lists them for reference.

Catalog agents are **blueprints, not shipped components**: each one is a pre-designed combination of documented platform capabilities that you build with [Agent Builder](./agent-builder/overview) nodes and integration workflows. Behind the industry-specific names, every agent is a variation of a small set of recurring [agent typologies](/5.9/ai-platform/patterns/agent-typologies), and that page maps each typology to the exact nodes that implement it.

Agents are designed to work together: the **Business area** column below groups each industry's agents into [multi-agent stacks](https://www.flowx.ai/ai-agent-stacks) — for example, nine agents cover retail mortgage underwriting and seven cover commercial onboarding — coordinated with the documented [multi-agent orchestration](/5.9/ai-platform/patterns/overview#multi-agent-orchestration) patterns.

> [!NOTE]
>
> **Complexity** is the catalog's deployment-effort estimate (Low, Medium, or High), driven mainly by how many systems the agent integrates with. It is an indication for scoping, not a fixed implementation cost.

***

## Banking (80 agents)

| Agent | Business area | Complexity | What it does |
| - | - | - | - |
| **KYC Periodic Review Validator** | AML KYC | Medium | Checks completeness of KYC refresh packs |
| **Regulatory Rule Compliance & Filing** | AML KYC | Medium | Ensures rule adherence and filing prep |
| **SAR Draft Generator** | AML KYC | Medium | Drafts suspicious activity reports |
| **Transactional Behavior Risk Analyzer** | AML KYC | Medium | Flags risky patterns in KYC/AML |
| **Business Plan & Use-of-Funds Validator** | Commercial Lending | Medium | Validates purpose, KPIs, ROI linkages |
| **Cash-Flow & Repayment Capacity (DSCR) Validator** | Commercial Lending | Medium | Computes DSCR; validates assumptions |
| **Collateral & Security Package Validator** | Commercial Lending | Medium | Checks LTV, encumbrances, insurance |
| **Commercial Lending Completeness Agent** | Commercial Lending | Low | Ensures full pack pre-committee |
| **Contract & Revenue Stream Verifier** | Commercial Lending | Medium | Links contracts/POs to projections |
| **Financial Statement Analyzer** | Commercial Lending | Medium | Extracts financials and ratios |
| **Legal Entity & Shareholding Validator** | Commercial Lending | Medium | Checks company status vs registry |
| **Authorized Signatory & Empowerment Validator** | Commercial Onboarding | Medium | Validates POA/Board rights and co-signs rules |
| **Business Address & Location Verifier** | Commercial Onboarding | Medium | Confirms addresses across documents |
| **Company Identity Extractor** | Commercial Onboarding | Medium | Extracts company identity info from docs |
| **Document Completeness & Clarification Agent** | Commercial Onboarding | Low | Detects missing/expired docs; generates ask-backs |
| **Document Cross-Check Agent** | Commercial Onboarding | Medium | Cross-checks names, dates, addresses across docs |
| **Jurisdiction-Specific KYC Validator** | Commercial Onboarding | Medium | Applies country-specific KYC rules |
| **Shareholder & Beneficial Ownership Validator** | Commercial Onboarding | Medium | Extracts UBOs and flags risks |
| **Conversational Application Agent** | Conversational Origination | Medium | Transforms forms into natural dialogue; recognizes existing members; pre-fills known data; adapts questions dynamically |
| **Disclosure & Signature Agent** | Conversational Origination | Medium | Presents terms in plain language; captures e-signatures in-flow; ensures compliance without breaking conversation |
| **Fulfillment & Recovery Agent** | Conversational Origination | Medium | Guides approved members through activation and next steps; handles declines empathetically with alternatives |
| **Identity & Verification Agent** | Conversational Origination | High | Guides ID capture and verification conversationally; validates documents in real-time; handles soft-pull for eligibility |
| **Board Authority & Multi-POA Validator** | Corporate Account Opening | Medium | Validates group signing rights and expiry |
| **Compliance Risk Scanner & Jurisdiction Classifier** | Corporate Account Opening | Medium | Runs PEP/sanctions; classifies country risk |
| **Corporate Onboarding Completeness Agent** | Corporate Account Opening | Medium | Final completeness gate + smart prompts |
| **Group Document Consistency Cross-Check** | Corporate Account Opening | Medium | Coherence checks across group entities/docs |
| **Multi-Entity Legal Identity Extractor** | Corporate Account Opening | High | Extracts legal data across group entities |
| **Ownership Structure & UBO Mapping** | Corporate Account Opening | High | Traces UBO layers; flags offshore/nominee risks |
| **Churn Retention Exception Handler** | Customer Churn & Retention | Low | Handles edge churn cases |
| **Churn Signal Extractor** | Customer Churn & Retention | Medium | Detects churn signals from usage/behavior |
| **Document-Driven Feedback & Closure Validator** | Customer Churn & Retention | Low | Validates complaint closure docs |
| **Root Cause Identifier (Complaint & Sentiment)** | Customer Churn & Retention | Medium | Analyzes drivers of churn from feedback |
| **Alert Triage Agent** | Fraud Investigation Stack | Medium | Auto-prioritizes incoming alerts by risk score context and business impact; routes high-priority cases for immediate review |
| **Case Narrative Generator** | Fraud Investigation Stack | Low | Generates structured investigation memo from compiled evidence using standard format and terminology |
| **Evidence Compiler Agent** | Fraud Investigation Stack | High | Aggregates and correlates data from multiple source systems (core banking; logs; device; network) into unified case file |
| **False Positive Screener** | Fraud Investigation Stack | Medium | Reasons through transaction context to filter obvious false positives before human review |
| **SAR Report Compiler Agent** | Fraud Investigation Stack | Medium | Extracts required regulatory fields from investigation materials and compiles into SAR-ready submission format |
| **Timeline Generator** | Fraud Investigation Stack | Low | Transforms raw transaction and event logs into human-readable chronological timeline with device/channel/location context |
| **Voice Call Transcriber** | Fraud Investigation Stack | Medium | Converts MP3 call recordings to searchable timestamped transcripts with keyword indexing |
| **Customer & Account Matcher** | Garnishment Processing | Medium | Confirms debtor across core systems |
| **Funds Availability & Freezing Agent** | Garnishment Processing | Medium | Calculates enforceable balance; applies freezes |
| **Garnishment Exception Handler** | Garnishment Processing | Low | Flags missing data, duplicates, non-supported juris |
| **Garnishment Order Extractor** | Garnishment Processing | Medium | Parses court orders; extracts parties/amounts |
| **Multi-Order Prioritization Agent** | Garnishment Processing | Medium | Orders conflicts by priority and timing |
| **Notification & Communication Generator** | Garnishment Processing | Low | Drafts letters to customers/authorities |
| **AI Edge Case Handler** | Mortgage Broker Assistant | Medium | Handles complex scenarios requiring multi-step reasoning with explainable recommendations and escalation paths. |
| **AI Eligibility Analyzer** | Mortgage Broker Assistant | Medium | Extracts parameters from uploaded client files and evaluates multi-bank eligibility instantly. |
| **AI Income Validator** | Mortgage Broker Assistant | Medium | Normalizes income types and applies bank-specific coefficients to produce compliant calculations. |
| **AI Mortgage Chat Agent** | Mortgage Broker Assistant | Medium | Conversational agent that guides brokers through client discovery using intelligent questioning and knowledge base. |
| **AI Product Matcher** | Mortgage Broker Assistant | Medium | Matches client profile to optimal products across partner banks with fit scores and clear rationale. |
| **Appraisal Report Consistency** | Retail Mortgage Underwriting | Medium | Validates appraised value, license, method |
| **Collateral Documentation Verifier** | Retail Mortgage Underwriting | Medium | Checks P\&L, tax filings, seasonality |
| **Debt & Liability Disclosure Checker** | Retail Mortgage Underwriting | Medium | Compares declared debts vs bureau/statements |
| **EPC Verifier** | Retail Mortgage Underwriting | Low | Checks energy certificate validity & thresholds |
| **Income & Employment Validator** | Retail Mortgage Underwriting | Medium | Validates payslips, contracts, bank statements |
| **Land Registry and Title Deed Validator** | Retail Mortgage Underwriting | Medium | Confirms ownership, liens, parcel data |
| **Mortgage Document Completeness Agent** | Retail Mortgage Underwriting | Low | Final pack check; suggests missing pages |
| **Purchase Agreement & Contract Validator** | Retail Mortgage Underwriting | Medium | Validates property contract vs appraisal/loan app |
| **Self-Employed Income Validator** | Retail Mortgage Underwriting | Low | Validates insurance, pledge, coverage |
| **Balance Sheet Extractor** | SME/Corporate Underwriting - Financial Insights | Medium | Extracts and maps accounts from trial balances into standardized templates. |
| **Credit Memo Generator** | SME/Corporate Underwriting - Financial Insights | Medium | Auto-builds structured, regulator-ready credit memos. |
| **Financial Mapping Validator** | SME/Corporate Underwriting - Financial Insights | Medium | Validates correct data mapping of accounts |
| **Interdependency Checker** | SME/Corporate Underwriting - Financial Insights | Medium | Correlates KPIs such as sales, stock, liquidity, and credit. |
| **KPI Forecaster** | SME/Corporate Underwriting - Financial Insights | High | Predicts KPI evolution using market and historical data. |
| **KPI Trend Scanner** | SME/Corporate Underwriting - Financial Insights | Medium | Detects and interprets KPI shifts using internal and market data. |
| **Market Intelligence Report** | SME/Corporate Underwriting - Financial Insights | Medium | Aggregates sector, filing, and news data to enrich credit analysis. |
| **Market Pulse Aligner** | SME/Corporate Underwriting - Financial Insights | High | Brings sector benchmarks and peer context into underwriting. |
| **Adverse Media Screening Agent** | Stand-alone Quick Win | Medium | Adverse news checks for entities |
| **Alternative Risk Assessor** | Stand-alone Quick Win | Medium | Uses alternative data for thin-file customers |
| **Credit Score Improvement Assistant** | Stand-alone Quick Win | Low | Recommends actions to raise credit score |
| **Customer 360 Summary Generator** | Stand-alone Quick Win | Low | Unified customer summary for RMs |
| **Customer Profiling & Product Recommender** | Stand-alone Quick Win | Medium | Next-best-product recommendations |
| **Inbound Email Agent (RM Copilot)** | Stand-alone Quick Win | Low | Triage client emails; extract tasks |
| **Legal Contract Drafting Assistant** | Stand-alone Quick Win | Medium | Drafts contracts/letters with compliant phrasing |
| **Delivery Confirmation Verifier** | Trade Finance Invoice Factoring | Low | Confirms delivery signatures vs invoice |
| **Invoice Eligibility Validator** | Trade Finance Invoice Factoring | Medium | Validates invoice authenticity/eligibility |
| **Line-Item Subsidy Filter** | Trade Finance Invoice Factoring | Medium | Applies eligibility per invoice line item |
| **Supplier Contract & Identity Validator** | Trade Finance Invoice Factoring | Medium | Validates supplier contract and status |
| **Supporting Documents Completeness (Trade)** | Trade Finance Invoice Factoring | Low | Validates PO and delivery notes |
| **Trade Finance Exception Handler** | Trade Finance Invoice Factoring | Low | Aggregates red flags; prescribes next steps |

***

## Insurance (69 agents)

| Agent | Business area | Complexity | What it does |
| - | - | - | - |
| **Claims Document Completeness Checker** | Claims Processing | Low | Ensures all required claim documents/photos are present and valid. |
| **Damage Evidence & Estimate Extractor** | Claims Processing | Medium | Extracts damage details from images/docs; drafts repair cost estimates. |
| **Eligibility & Threshold Checker (Claims)** | Claims Processing | Medium | Validates deductibles, sub-limits, and other threshold rules. |
| **FNOL Intake & Triaging Agent** | Claims Processing | Medium | Captures First Notice of Loss and routes claim to the right path. |
| **Fraud Risk Signal Agent (Claims)** | Claims Processing | Medium | Flags suspicious patterns at FNOL and throughout assessment. |
| **Policy Terms & Coverage Validator (Claims)** | Claims Processing | Medium | Checks claim against policy terms, coverages, limits, deductibles. |
| **KYC Periodic Review Validator (Insurance)** | Complaint & Dispute | Medium | Validates KYC refresh for insurance customers. |
| **Regulatory Rule Compliance & Filing (Insurance)** | Complaint & Dispute | Medium | Ensures rule adherence and prepares required filings for disputes. |
| **SAR Draft Generator (Insurance)** | Complaint & Dispute | Medium | Prepares SAR-like summaries when required under local rules. |
| **Transactional Behavior Risk Analyzer (Complaints)** | Complaint & Dispute | Medium | Flags risky transactional patterns related to disputes/complaints. |
| **Suitability & Compliance Logger** | Compliance & Governance | Low | Logs all advisory decisions inputs and rationale for regulatory review and audit |
| **Behavioral Pattern Analyzer (Claims SIU)** | Fraud Detection & Alerting | Medium | Detects anomalous behavior across claims lifecycle. |
| **Claim vs Policy Consistency Checker** | Fraud Detection & Alerting | Medium | Checks claim statements against policy declarations and endorsements. |
| **Image & Document Authenticity Detector** | Fraud Detection & Alerting | Medium | Detects tampering or synthetic images/documents in claims. |
| **Network Association Risk Detector** | Fraud Detection & Alerting | Medium | Surfaces suspicious linkages across claimants, providers, and events. |
| **Suspicious Claim Escalation Agent** | Fraud Detection & Alerting | Medium | Escalates high-risk claims with a complete evidence packet. |
| **Agent Licensing & Appointment Verifier** | Insurance Distribution | Medium | Validates agent licensing, appointments, and renewals. |
| **Channel-Specific Suitability Checker** | Insurance Distribution | Medium | Validates product suitability rules per channel. |
| **Distributor Contract Validator** | Insurance Distribution | Medium | Checks distributor agreements for compliance and obligations. |
| **Incentive & Commission Rule Validator** | Insurance Distribution | Medium | Checks incentive and commission calculations against rules. |
| **Sales Script & Disclosure Consistency Agent** | Insurance Distribution | Medium | Ensures sales scripts/disclosures match policy and compliance wording. |
| **Audit Trail Completeness Verifier** | Insurance Regulatory & Compliance | Medium | Ensures decisions/actions have full audit evidence. |
| **Claims Settlement Timeline Validator** | Insurance Regulatory & Compliance | Medium | Tracks SLA deadlines and validates timely settlements. |
| **Customer Communication Consistency Agent** | Insurance Regulatory & Compliance | Medium | Checks communications match policy terms and regulatory phrasing. |
| **Policy Language Regulatory Check Agent** | Insurance Regulatory & Compliance | Medium | Validates policy wording against jurisdictional rules. |
| **Regulated Document Filing Assistant** | Insurance Regulatory & Compliance | Medium | Prepares and validates regulator-ready documents and submissions. |
| **Client Risk Profile Interpreter** | Investment Advisory & Suitability | Medium | Interprets client risk questionnaire and behavioral signals to produce a normalized risk profile used across investment journeys |
| **Fund Information Synthesizer** | Investment Advisory & Suitability | Low | Aggregates and summarizes fund characteristics performance and risk disclosures from approved sources |
| **Product-Risk Matching Agent** | Investment Advisory & Suitability | Medium | Matches available investment funds to client risk profile and product constraints |
| **Beneficiary & Nominee Validator** | Policy Onboarding | Medium | Validates beneficiary/nominee identities, relationships, and percentages. |
| **Identity & Document Extractor (Policy)** | Policy Onboarding | Medium | Extracts insured identity data and validates policy application documents. |
| **Jurisdictional Compliance Agent (Policy)** | Policy Onboarding | Medium | Applies local regulatory requirements and disclosures for the policy. |
| **Policy Terms Cross-Check Agent** | Policy Onboarding | Medium | Cross-checks policy terms, riders, limits, and exclusions across documents. |
| **Product Suitability & Match Validator** | Policy Onboarding | Medium | Checks that selected product fits customer risk profile and objectives. |
| **Risk Profile & Disclosure Analyzer** | Policy Onboarding | Medium | Evaluates disclosed conditions/activities and highlights missing or risky disclosures. |
| **Portfolio Performance Monitor** | Portfolio Monitoring & Insights | Medium | Monitors portfolio value performance and risk drift against client profile over time |
| **Rebalancing Recommendation Agent** | Portfolio Monitoring & Insights | Medium | Generates rebalancing suggestions when portfolio drifts from target allocation |
| **Conversational Underwriting Copilot** | Property Insurance - Conversational Stack | Medium | Allows underwriters to ask natural-language questions across claims, exposure, performance, and policy data and receive contextual, traceable answers. |
| **Explainability & Decision Rationale Agent** | Property Insurance - Conversational Stack | Low | Provides clear explanations for insights, calculations, and recommendations, including data sources and reasoning steps. |
| **De-Risking Guardrails & Validation Agent** | Property Insurance - Geo-Risk Calculation Stack | Medium | Applies deterministic validation rules and completeness checks before and after AI reasoning, ensuring traceability and human-in-the-loop control. |
| **Geo Exposure & Hazard Context Calculator** | Property Insurance - Geo-Risk Calculation Stack | High | Uses geolocation inputs and GIS layers to identify hazard zones, proximity to risks, and exposure clustering for insured sites. |
| **Proximity & Distance Risk Signal Agent** | Property Insurance - Geo-Risk Calculation Stack | Medium | Calculates distance-based risk indicators (e.g., proximity to rivers, industrial sites) and flags elevated exposure scenarios. |
| **Insured Entity Resolver & Data Integrator** | Property Insurance - Pre-Assessment Stack | Medium | Ingests structured inputs (policy, claims, exposure) and links them into a single insured-entity view using a unique identifier, performing normalization and cross-source validation. |
| **Loss Ratio & Claims Pattern Analyzer** | Property Insurance - Pre-Assessment Stack | Medium | Analyzes multi-year premium, claims, and loss ratio trends to detect deterioration, large-loss concentration, and performance anomalies. |
| **Underwriting Pre-Assessment Brief Generator** | Property Insurance - Pre-Assessment Stack | Medium | Generates an underwriter-ready summary with KPIs, historical performance, key risk indicators, and focus areas before manual review begins. |
| **Automatic Reporting Agent** | Regulatory Compliance Monitoring | Medium | Generates board-level reports on configurable cadence (monthly/weekly), customizable audience and content |
| **Department Impact Assessment Agent** | Regulatory Compliance Monitoring | Medium | Cross-references new regulations against internal policies/procedures KB, identifies which departments are impacted |
| **Intelligent Document Processing Agent** | Regulatory Compliance Monitoring | Medium | Extracts key attributes from legislation: source, type, phase, summary, effective dates. Multi-language (SL/EN/EU) |
| **Legal Cross-Reference Agent** | Regulatory Compliance Monitoring | Medium | Detects referenced statutes/articles, traces citation chains to build complete legal context |
| **Multi-Source Monitoring Agent** | Regulatory Compliance Monitoring | Medium | Continuous 24/7 crawling of legislative portals (PISRS, Uradni list, AZN, EIOPA, etc.) with real-time alerts |
| **Smart Filtering & Prioritization Agent** | Regulatory Compliance Monitoring | Medium | Scores relevance to life insurance business, assigns priority (high/med/low), tracks deadlines |
| **Cession Eligibility Checker** | Reinsurance Coordination | Medium | Determines which risks are eligible for cession under treaties. |
| **Claim Sharing Agreement Trigger Agent** | Reinsurance Coordination | Medium | Identifies and triggers claim sharing based on treaties/agreements. |
| **Reinsurance Treaty Cross-Referencer** | Reinsurance Coordination | Medium | Cross-references claim/policy data with relevant treaty clauses. |
| **Reinsurer Notification & Documentation Assistant** | Reinsurance Coordination | Medium | Prepares and sends documentation packets to reinsurers. |
| **Retention Limit Validator** | Reinsurance Coordination | Medium | Validates retained amounts vs. treaty limits and internal rules. |
| **Cross-Sell / Upsell Trigger Agent** | Renewals & Upsell | Medium | Suggests relevant add-ons or new products at renewal or life events. |
| **Lapse Risk Predictor** | Renewals & Upsell | Medium | Predicts policy lapse probability and drivers. |
| **Premium Change Impact Explainer** | Renewals & Upsell | Low | Explains premium changes to agents/customers with drivers. |
| **Product Suitability Re-Matcher** | Renewals & Upsell | Medium | Re-matches in-force policies to better-fitting products at renewal. |
| **Usage-Based Data Interpreter (Telematics)** | Renewals & Upsell | Medium | Interprets telematics/IoT usage patterns for pricing and advice. |
| **Investment Top-Up Validator** | Transaction Processing | Medium | Validates investment top-up requests against product rules limits and client eligibility |
| **Transaction Explainability Agent** | Transaction Processing | Low | Generates human-readable explanations for accepted or rejected investment transactions |
| **Asset & Usage Pattern Extractor (P\&C)** | Underwriting Assessment | Medium | Extracts asset attributes and usage patterns (e.g., mileage, occupancy). |
| **Health History & Diagnostic Validator** | Underwriting Assessment | Medium | Validates disclosed conditions vs. medical history; flags gaps. |
| **Income & Occupation Verifier (Life)** | Underwriting Assessment | Medium | Validates income and occupation for life insurance applications. |
| **Manual Exception Escalation Wrapper (UW)** | Underwriting Assessment | Low | Routes complex or borderline cases to human underwriters with context. |
| **Medical Questionnaire Analyzer** | Underwriting Assessment | Medium | Analyzes medical questionnaires for risk-relevant signals. |
| **Risk Tier Assignment Agent** | Underwriting Assessment | Medium | Assigns risk tier based on combined disclosures and data. |

***

## Logistics (97 agents)

| Agent | Business area | Complexity | What it does |
| - | - | - | - |
| **Carrier Intelligence Agent** | Carrier Matching | Medium | Profiles carriers by performance, lane history, and service quality. |
| **Network Optimization Agent** | Carrier Matching | Medium | Identifies underutilized carriers and rebalancing opportunities. |
| **Predictive Matching Agent** | Carrier Matching | Medium | Pairs loads with ideal carriers using performance and availability signals. |
| **Audit Prep Agent** | Compliance & Safety | Medium | Assembles audit-ready compliance packets automatically. |
| **Driver Log Validator Agent** | Compliance & Safety | Medium | Validates HOS and rest breaks to prevent violations. |
| **Incident Tracker Agent** | Compliance & Safety | Medium | Captures and classifies safety events to surface trends. |
| **Regulatory Monitor Agent** | Compliance & Safety | Medium | Monitors FMCSA/DOT and regional standards; flags compliance risks. |
| **Cost Aggregation Agent** | Cost Prediction | Medium | Consolidates carrier, port, duty, and tariff data into unified models. |
| **Predictive Modeling Agent** | Cost Prediction | Medium | Forecasts total landed cost by route or mode. |
| **Profitability Insights Agent** | Cost Prediction | Medium | Highlights cost-saving opportunities and margin risks pre-booking. |
| **Case Routing Agent** | Customer Service | Medium | Classifies and routes complex issues to the right team. |
| **Inquiry Automation Agent** | Customer Service | Medium | Answers routine client questions via email automatically. |
| **Tracking Intelligence Agent** | Customer Service | Medium | Retrieves shipment status and ETAs for proactive customer updates. |
| **Compliance Validation Agent** | Customs Validation | Medium | Confirms HS codes, declared values, and details meet customs rules. |
| **Compliance Validation Agent** | Customs Validation | Medium | Validates HS codes, values, and origin against tariff rules. |
| **Cross-Verification Agent** | Customs Validation | Medium | Checks internal bookings/invoices vs customs filings for consistency. |
| **Document Extraction Agent** | Customs Validation | Medium | Extracts structured data from internal and external trade documents. |
| **Document Verification Agent** | Customs Validation | Medium | Checks completeness and consistency across required trade documents. |
| **Exception Resolution Agent** | Customs Validation | Medium | Routes documentation issues for correction before filing. |
| **Exception Resolution Agent** | Customs Validation | Medium | Flags and routes errors for correction before submission. |
| **Capacity Planning Agent** | Demand Forecasting | Medium | Recommends bookings and capacity allocations by horizon. |
| **Data Aggregation Agent** | Demand Forecasting | Medium | Collects sales, promotions, and shipment history for forecasting. |
| **Forecasting Agent** | Demand Forecasting | Medium | Predicts order and shipment volumes by region and channel. |
| **Contract Management Agent** | Dynamic Pricing | Medium | Applies customer-specific terms, discounts, and rate rules consistently. |
| **Market Intelligence Agent** | Dynamic Pricing | Medium | Aggregates real-time rate, lane, and capacity data for pricing decisions. |
| **Rate Optimization Agent** | Dynamic Pricing | Medium | Calculates profitable yet competitive rates per shipment. |
| **Network Insights Agent** | Dynamic Routing | Medium | Analyzes route performance to pinpoint recurring bottlenecks. |
| **Real-Time Adjuster Agent** | Dynamic Routing | Medium | Re-optimizes routes when orders or conditions change. |
| **Route Optimization Agent** | Dynamic Routing | Medium | Calculates efficient routes under distance, capacity, and time constraints. |
| **Exception Detection Agent** | Exception Management | Medium | Monitors shipment events to flag delays, shortages, and deviations. |
| **Resolution Orchestrator Agent** | Exception Management | Medium | Triggers corrective workflows such as rescheduling or carrier swap. |
| **Root Cause Analysis Agent** | Exception Management | Medium | Explains disruptions using historical and contextual data. |
| **Load Matching Agent** | Fleet Optimization | Medium | Identifies ideal load combinations to minimize deadhead and boost productivity. |
| **Utilization Insights Agent** | Fleet Optimization | Medium | Surfaces underuse trends and asset performance to guide capacity plans. |
| **Market Rate Agent** | Freight Quoting | Medium | Aggregates benchmark rates and carrier quotes across modes. |
| **Procurement Insights Agent** | Freight Quoting | Medium | Surfaces negotiation levers and timing opportunities. |
| **Quote Comparison Agent** | Freight Quoting | Medium | Benchmarks offers against internal history and market data. |
| **Driver Performance Agent** | Fuel Efficiency | Low | Detects behavior patterns that correlate with delays and excess cost. |
| **Efficiency Insights Agent** | Fuel Efficiency | Low | Analyzes route, trip, and utilization data to uncover operational waste. |
| **Sustainability Analytics Agent** | Fuel Efficiency | High | Estimates emissions savings from operational improvements and reduced miles. |
| **Conversation Summary Agent** | Inbox Management | Medium | Summarizes threads and logs outcomes to CRM/TMS. |
| **Intent Detection Agent** | Inbox Management | Medium | Classifies and prioritizes incoming communications for action. |
| **Message Automation Agent** | Inbox Management | Medium | Drafts and sends shipment updates and notifications. |
| **Demand Forecasting Agent** | Inventory Optimization | Medium | Predicts SKU-level demand using orders, seasonality, and trends. |
| **Inventory Visibility Agent** | Inventory Optimization | Medium | Provides real-time visibility into stock positions and turnover by location. |
| **Replenishment Planner Agent** | Inventory Optimization | Medium | Automates reorder triggers and quantities from forecasts and lead times. |
| **Discrepancy Detection Agent** | Invoice Reconciliation | Medium | Flags mismatches or overcharges for quick resolution. |
| **Discrepancy Detection Agent** | Invoice Reconciliation | Medium | Identifies overcharges or missing documentation. |
| **Discrepancy Detection Agent** | Invoice Reconciliation | Medium | Flags anomalies, accessorial mismatches, and missing credits. |
| **Discrepancy Detector Agent** | Invoice Reconciliation | Medium | Flags rate/accessorial or documentation mismatches for review. |
| **Finance Sync Agent** | Invoice Reconciliation | Medium | Integrates approved invoices into accounting or payment systems. |
| **Finance Sync Agent** | Invoice Reconciliation | Medium | Routes approved invoices into ERP/payment systems. |
| **Finance Sync Agent** | Invoice Reconciliation | Medium | Integrates approved invoices into ERP/payment platforms. |
| **Invoice Validation Agent** | Invoice Reconciliation | Medium | Compares partner invoices against shipment data and agreed terms. |
| **Invoice Validation Agent** | Invoice Reconciliation | Medium | Cross-checks billed charges with agreed rates and delivery records. |
| **Invoice Validator Agent** | Invoice Reconciliation | Medium | Cross-verifies billing line items with shipment and contract data. |
| **Invoice Validator Agent** | Invoice Reconciliation | Medium | Cross-checks billed rates with contract terms and shipment data. |
| **Payment Reconciliation Agent** | Invoice Reconciliation | Medium | Matches payments to approved invoices and updates ledgers. |
| **Payment Matching Agent** | Invoicing | Medium | Reconciles payments, credits, and deductions to the correct invoices. |
| **Revenue Insights Agent** | Invoicing | Medium | Analyzes billing performance and aging to highlight margin risks. |
| **Smart Invoice Agent** | Invoicing | Medium | Creates line-item invoices directly from shipment and delivery data. |
| **Data Capture Agent** | Load Entry | Medium | Detects shipment details from incoming emails and EDI feeds. |
| **Data Enrichment Agent** | Load Entry | Medium | Fills missing fields (weights, codes, references) via internal/external lookups. |
| **Data Validation Agent** | Load Entry | Medium | Checks extracted fields against rules, SOPs, and history for consistency. |
| **Data Validation Agent** | Load Entry | Medium | Ensures completeness and SOP compliance before posting. |
| **Document Intelligence Agent** | Load Entry | Medium | Parses tenders, BOLs, and confirmations to extract structured shipment fields. |
| **Document Parsing Agent** | Load Entry | Medium | Extracts structured fields from tenders, BOLs, and confirmations. |
| **Document Processing Agent** | Load Entry | Medium | Extracts structured data from rate confirmations, tenders, and BOLs. |
| **Email Intake Agent** | Load Entry | Medium | Captures shipment details from emails and attachments in real time. |
| **Load Intake Agent** | Load Entry | Medium | Captures load requests from email and EDI in real time to start structured records. |
| **System Sync Agent** | Load Entry | Medium | Writes validated load data to TMS, accounting, and CRM systems. |
| **System Sync Agent** | Load Entry | Medium | Pushes verified shipments into the TMS in real time. |
| **TMS Sync Agent** | Load Entry | Medium | Uploads verified loads directly into the TMS or posting platforms. |
| **Validation Agent** | Load Entry | Medium | Checks completeness and rules before writing to TMS. |
| **Carrier Evaluation Agent** | Load Tendering | Medium | Scores carriers on performance, price, and on-time delivery. |
| **Contract Compliance Agent** | Load Tendering | Medium | Validates awarded rates and terms against contracts. |
| **Cost Optimization Agent** | Load Tendering | Medium | Optimizes awards to balance price, service level, and sustainability goals. |
| **Tender Automation Agent** | Load Tendering | Medium | Generates RFQs, evaluates bids, and auto-awards per rules. |
| **Carrier Performance Agent** | Performance Analysis | Medium | Monitors carrier reliability, on-time rates, and service KPIs. |
| **Profitability Insights Agent** | Performance Analysis | Medium | Analyzes margins and performance by lane, shipper, and carrier. |
| **Reporting Automation Agent** | Performance Analysis | Medium | Builds and distributes dashboards for stakeholders automatically. |
| **Cost Optimization Agent** | Predictive Maintenance | Medium | Identifies vendor and part savings opportunities across repairs. |
| **Failure Prediction Agent** | Predictive Maintenance | Medium | Forecasts breakdown risk using historical repair and usage data. |
| **Maintenance Planner Agent** | Predictive Maintenance | Medium | Recommends optimal service schedules based on utilization and condition. |
| **Service History Analyzer Agent** | Predictive Maintenance | Medium | Analyzes maintenance logs to detect recurring issues and root causes. |
| **Audit Intelligence Agent** | Risk & Compliance | Medium | Prepares regulator-ready compliance reports and documentation. |
| **Regulatory Monitor Agent** | Risk & Compliance | Medium | Tracks trade rule changes and embeds updates into checks. |
| **Sanctions Screening Agent** | Risk & Compliance | Medium | Screens partners and shipments against restricted lists. |
| **Margin Intelligence Agent** | Smart Quoting | Medium | Learns from outcomes to improve pricing guidance over time. |
| **Market Data Agent** | Smart Quoting | Medium | Aggregates live lane rates, carrier pricing, and fuel indices. |
| **Market Rate Agent** | Smart Quoting | Medium | Aggregates live rates from carriers, ports, and logistics partners. |
| **Optimization Agent** | Smart Quoting | Medium | Recommends mode/route combos balancing time and cost. |
| **Quote Builder Agent** | Smart Quoting | Medium | Generates customer-ready multimodal quotes instantly. |
| **Quote Optimization Agent** | Smart Quoting | High | Computes margin-aware, competitive rates for each shipment. |
| **Margin Performance Agent** | Smart Quoting & Rate Optimization | Medium | Monitors quote outcomes and tunes pricing models for profitability. |
| **Market Intelligence Agent** | Smart Quoting & Rate Optimization | Medium | Aggregates live rate indices, lane performance, and carrier availability. |
| **Rate Optimization Agent** | Smart Quoting & Rate Optimization | Medium | Calculates optimal bid prices based on demand, distance, and target margin. |

***

## Related resources

> [card] [Agent typologies](/5.9/ai-platform/patterns/agent-typologies)
>
> The recurring archetypes behind the catalog, and the nodes that build each one

> [card] [Agent Builder](./agent-builder/overview)
>
> Build any catalog agent with the documented node palette

> [card] [Evaluations](./evaluations)
>
> Score and regression-test the agents you build

> [card] [Live catalog on flowx.ai](https://www.flowx.ai/ai-agents)
>
> The browsable catalog with filters and detail views


# AI in FlowX
Source: https://docs.flowx.ai/5.9/ai-platform/ai-in-flowx

AI agents for every stage - config-time agents help you build apps faster, while business agents power intelligent experiences for your end-users.

AI Platform · FlowX.AI

AI agents for every stage.

FlowX AI Platform provides intelligent agents across your entire application lifecycle. Whether you're building apps or running them, AI agents accelerate your work and enhance user experiences.

[Explore Agent Builder](./agent-builder/overview)
[Pre-built agents](./pre-built-agents/overview)

01 · Agent types

## Two types of AI agents

FlowX provides agents for different stages of your application lifecycle:

01 · config time
FlowX Designer
Config-time agents help you build processes, UIs, and business rules.



02 · build
Agent Builder · Marketplace
Create custom business agents or start from pre-built accelerators.



03 · runtime
Business agents
Run inside your apps, serving your customers and employees.

01
Config-time agents
Help you build apps faster. AI assistants embedded in FlowX Designer that help developers and business analysts create processes, UIs, and business rules. Used by designers, developers, analysts.

02
Business agents
Power your end-user experiences. AI agents that run inside your applications, interacting with customers and employees to automate tasks and provide intelligent assistance.

***

02 · Config time

## Config-time agents

These agents are built into FlowX Designer to accelerate app development:

[01
Analyst
Build and optimize BPMN processes using AI to generate, validate, and enhance workflows.](./pre-built-agents/ai-analyst)

[02
Assistant
Answer questions about FlowX platform and your organization based on documentation.](./pre-built-agents/ai-assistant)

[03
Designer
Convert natural language prompts, Figma designs, or sketches into UI layouts.](./pre-built-agents/ai-designer)

[04
Developer
Generate business rules and code expressions using natural language.](./pre-built-agents/ai-developer)

> [accordion] See config-time agents in action
>
> <video />

For detailed documentation on each config-time agent, see the [pre-built agents overview](./pre-built-agents/overview).

On SaaS, starting with FlowX.AI 5.13, the [Developer Agentic Harness](./developer-agentic-harness) goes further: you describe a change to your app, and the agent plans it and carries it out on a dedicated branch for your review. It builds your app in the Designer. [Agent Builder](./agent-builder/overview), covered below, builds business agents that run inside your apps.

***

03 · Runtime

## Business agents

Agents that power intelligent experiences for your end-users. You have two options:

### FlowX accelerators

Pre-built business agents created by FlowX, ready to deploy:

* Industry-specific solutions for banking, insurance, and more
* Tested and optimized for common use cases
* Deploy immediately or customize to your needs

### Custom agents

Use **Agent Builder** to create AI agents tailored to your specific business processes:

documentsExtract data from forms, contracts, and statements.contentCreate personalized communications and reports.decisionsAnalyze data and provide recommendations.conversationsBuild chat-based customer interactions.

[→
Agent Builder
Create custom AI agents for your specific business needs.](./agent-builder/overview)

***

04 · Integrate

## Integrating agents into apps

Once you have business agents (custom or from marketplace), integrate them into your applications:

[01
Chat interface
Conversational UI for end-users.](./using-agents/chat-interface)

[02
BPMN integration
Trigger agents from workflows.](./using-agents/bpmn-integration)

[03
API access
Programmatic integration.](./integrations)

***

05 · Security

## Enterprise security

All FlowX AI agents are built for banking-grade security:

| Security feature | Description |
| - | - |
| **Zero-trust model** | All components authenticate each other, preventing unauthorized access |
| **Input/output scanning** | Detect prompt injection, ban sensitive substrings, sanitize outputs |
| **Custom fine-tuned models** | Purpose-built models with curated data for each use case |
| **Human oversight** | Human-in-the-loop controls for ethical decision-making |

***

06 · Data protection

## Personal data protection

FlowX ensures personal data never reaches AI models by design through controlled data ingestion, deterministic workflows, and encryption options.

### Data ingestion paths

Personal data enters the platform through three channels:

| Channel | Data handling |
| - | - |
| **Forms / UIs** | Input data mapped directly to the process data model |
| **3rd party APIs** | API responses mapped to the process data model |
| **Documents** | Structured docs (Word, Excel) have fields mapped automatically; unstructured docs require OCR extraction with optional human verification |

> [!NOTE]
>
> For unstructured documents containing sensitive data, a human operator can verify extracted data accuracy before it's mapped to the data model.

### Data storage

All ingested data ends up in **data models** - JSON collections stored in FlowX databases:

* Data models are only accessible to deterministic business process steps
* Process logic controls when, how, and which data is sent to AI steps
* This ensures **no personal data is sent to AI by design**

### Protection options

| Option | Description |
| - | - |
| **Database encryption** | Encrypt data at rest using database capabilities (e.g., pgcrypto in PostgreSQL) - prevents administrator access to business data |
| **Sensitive data masking** | Mark specific data model fields as sensitive to hide them in UIs and console outputs |
| **Custom guardrails** | Additional guardrails can be enforced in AI workflows |

> [card] [Data Model](../docs/building-blocks/process/data-model)
>
> Learn about process data models

> [card] [Sensitive Data](../docs/building-blocks/process/data-model#sensitive-data)
>
> Configure sensitive data masking

***

07 · Reliability

## Hallucination prevention

| Technique | Purpose |
| - | - |
| **RAG** | Ground responses in reliable external data sources |
| **Multi-agent architecture** | Dedicated agents for specific tasks with specialized processing |
| **Structured outputs** | Enforce JSON outputs for consistent, parseable responses |
| **Model evaluation** | Continuous testing to find optimal models for each task |
| **Prompt tuning** | Task-specific prompts to enhance accuracy and relevance |

***

08 · Resources

## Related resources

[01
Chat component
Technical reference for chat integration.](./chat-component)

[02
AI integrations
Connect agents to knowledge bases and external systems.](./integrations)

[03
AI Platform setup
Configure AI Platform for your environment.](/5.9/setup-guides/ai-platform-setup)

[04
Using agents
Integration patterns and best practices.](./using-agents/overview)

[05
Research
Open-source guardrails, open models, and the paper series.](./research)


# AI providers and model configuration
Source: https://docs.flowx.ai/5.9/ai-platform/ai-providers

Configure AI providers and assign default and fallback models per workspace type for text generation, image understanding, embeddings, and document processing.

## Overview

FlowX supports configuring AI providers at three levels:

* **Organization level**: Add and manage AI providers, set API keys, whitelist specific models
* **Organization level (per workspace type)**: Assign default and fallback models for each AI capability, scoped by workspace type (Sandbox, Staging, Production)
* **Node level**: Override the default model on individual workflow nodes

Organization admins define which providers and models are available, and configure model assignments per workspace type. Workflow designers can optionally override the model on individual AI nodes.

***

## Organization-level: Model providers

Access model providers from **Organization Settings** → **AI Settings** → **Model Providers**.

![Model Providers page in Organization Settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_org_settings.png)

An **OpenAI** provider card is present by default, using a FlowX-managed key. You can switch it to your own key or add additional providers.

### Adding a provider

**1. Navigate to Model Providers**

In FlowX Designer, go to your organization settings and select **Model Providers**.

**2. Add a provider**

Click the **+** button to open the **Provider Details** dialog. Configure:

| Field | Description |
| - | - |
| **Provider** | Select from the provider catalog (e.g., OpenAI) |
| **Base URL** | API endpoint (required). OpenAI offers presets (Global, EU, US) or select **Custom URL** to enter any OpenAI-compatible endpoint. |
| **API Key Source** | Select **Own** to provide your own API key, or **FlowX** to use the FlowX-provided API key |
| **Key** | Your provider API key (required, shown when **Own** is selected) |
| **Organization ID** | Provider organization ID (optional) |

> [!NOTE]
>
> You cannot add the same provider type twice. The system validates against the provider catalog and shows an error if a duplicate is attempted.

**3. Test the connection**

Click **Test Connection** to validate your credentials against the provider API.

* **Success:** "Connection successful. X models discovered."
* **Failure:** Error details are shown (e.g., invalid API key for 401, insufficient permissions for 403).

You cannot save the provider configuration until the connection test succeeds.

**4. Enable models**

After saving, click **Manage** to choose the models this provider offers. For a provider with a discovered model list, **Manage** opens the model whitelisting modal: enable specific models from the list. Only enabled models appear in workspace-type assignments (Sandbox, Staging, Production). For Azure OpenAI, **Manage** opens a list where you add your deployment models by hand instead, see [Manually configured models](#manually-configured-models).

### Custom URL endpoints

When you point the **OpenAI** provider at a **Custom URL**, such as an API gateway or proxy in your own network, FlowX sends every AI capability to that endpoint: text generation, image understanding, embeddings, and document processing. The endpoint must implement these OpenAI API operations, relative to the Base URL:

| Operation | Used for |
| - | - |
| `GET /models` | **Test Connection**. You can't save the provider until this call succeeds. |
| `POST /responses` | Text generation and image understanding (the OpenAI Responses API) |
| `POST /embeddings` | Knowledge base indexing and retrieval |
| `POST /chat/completions` | Document parsing with an AI vision model |

* Include the `/v1` version segment in the Base URL, for example `https://gateway.example.com/v1`.
* The API key is sent as a bearer token (`Authorization: Bearer <key>`). The provider doesn't acquire or refresh OAuth tokens.
* Requests use the standard OpenAI model IDs from the provider's model list, for example `gpt-4.1` or `text-embedding-3-small`. The endpoint must accept these IDs, because you can't add custom model names to the OpenAI provider.

### API Key Source

The **API Key Source** radio buttons control how the provider authenticates:

| Option | Description |
| - | - |
| **Own** | Provide your own API Key. You have full control over the key, Organization ID, and which models are enabled. |
| **FlowX** | Use the FlowX-provided API key. The Key and Organization ID fields are hidden and cannot be edited. |

When editing the OpenAI provider, switch between **Own** and **FlowX** under API Key Source.

### Model whitelisting

The **Models Whitelist** modal (opened from **Manage**) lets you control which discovered models are available downstream. It lists every discovered model as a single checkbox list. Capabilities you may see on a model include:

| Category | Description |
| - | - |
| **Text Generation** | Text responses, summaries, translations, extraction |
| **Code Generation** | Automated code generation for Developer Agents |
| **Embeddings** | Vector representations for knowledge base indexing and RAG |
| **Audio Capabilities** | Audio transcription for the Speech to Text workflow node |

Each model row shows the model name and up to three of its capabilities, or the model ID when the provider reports no capabilities.

* Use **Search** to filter models by name, model ID, or capability
* Use **Select All** / **Deselect All** for bulk actions
* The footer shows **Models enabled: X / Y**
* Click **Save Whitelist** to persist your selection

> [!WARNING]
>
> Disabling a model doesn't change the assignments that use it. A default or fallback set to that model in **Defaults & Fallbacks** keeps using it, so reassign them before you disable the model.

> [!NOTE]
>
> Model whitelisting is not available when using the FlowX-managed key for OpenAI.

### Manually configured models

Azure OpenAI has no discovered model list, so **Manage** opens the provider's **Models** modal (**Manually configure deployment models**) instead of the whitelist. On SaaS, the [Custom provider](#custom-provider-self-hosted-endpoints) opens the same modal. You register each model your deployment serves.

The list shows each model's display name, deployment name, context window, capabilities, whether it's a reasoning model, and the capabilities it's the default for. Click **Edit** or the delete icon on a model to change or remove it, and **Add Model** to register a new one:

| Field | Description |
| - | - |
| **Deployment Name** | Required. The deployment or model ID your endpoint expects, for example `gpt-4o-my-deployment`. |
| **Display Name** | Required. The name shown in FlowX, for example `GPT-4o`. |
| **Capabilities** | Required. One or more capabilities the model supports. |
| **Default for Capabilities** | Optional. Makes this model the provider's default for some of its selected capabilities. A capability that another model in the list already claims can't be selected. |
| **Reasoning model** | Turn on for reasoning models. |
| **Context Window** | Optional, for example `128k`. |

On SaaS, a model with the **Embeddings** capability also requires **Dimensions**: the number of dimensions of its embeddings, for example `384`.

### Editing a provider

When editing an existing provider (API key or Organization ID changed):

1. The **Save** button is disabled after any field edit
2. Click **Test Connection** to validate the new credentials
3. On success, **Save** becomes enabled
4. If the newly discovered model list differs from the previous one:
   * New models are added to the whitelist automatically
   * If any previously enabled models are no longer available, a replacement wizard guides you through selecting alternatives
   * Skipping the wizard removes the missing models from all dropdowns where they were used, and the fallback mechanism activates

### Deleting a provider

All providers except the default OpenAI (FlowX-managed) can be deleted. Deleting a provider:

1. Shows a confirmation with the impact: nodes and knowledge bases using this provider's models switch to their fallback model
2. If the fallback model is also from the deleted provider, a warning indicates that all LLM-related activities using those models will fail

### Provider card

Each provider card shows:

* Provider name and icon
* Masked API key (last 4 characters visible, e.g., `••••••••••••1234`)
* Model count: "Models enabled: X / Y"
* Organization ID (if configured)
* Connection status
* Available actions: **Manage**, **Edit**, **Delete**

***

## Defaults & Fallbacks

Access model assignments from **Organization Settings** → **AI Settings** → **Defaults & Fallbacks**.

![Defaults & Fallbacks configuration with workspace-type tabs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/workspace_level.png)

Organization admins assign a **Default Model** and an optional **Fallback Model** for each AI capability, scoped by **workspace type**. Use the **Sandbox**, **Staging**, and **Production** tabs to configure different model assignments per environment. Select **Use provider default** to inherit the catalog default for that capability.

| Capability | Used for |
| - | - |
| **Text Generation** | Text operations (summarization, translation, extraction), data operations (enrichment, generation, transformation), custom agents, and intent classification |
| **Image Understanding** | AI image nodes — image description and image analysis. Only models with vision capability are shown. |
| **Embeddings** | Knowledge base indexing and context retrieval (RAG). Used by context retrieval nodes in workflows. |
| **Document / OCR** | AI document nodes — document generation, extraction, understanding, and text extraction from documents. |
| **Developer Agents** | AI planner, developer, analyst, and designer agents. Used for automated code generation and analysis workflows. For best performance, this capability uses the FlowX tested and optimized model configured at the organization level. |
| **Audio Capabilities** | Speech-to-text transcription. Used by the Speech to Text workflow node. |

Default models from the OpenAI FlowX key are pre-assigned for each capability.

### Assigning models

For each capability:

1. Select a **Default model** from org-whitelisted models matching that capability, or use the **provider default**
2. Optionally select a **Fallback model**, used if the default model is unavailable or rate-limited

Assignments are configured per workspace type (Sandbox, Staging, Production). All workspaces of a given type inherit the same model assignments.

> [!WARNING]
>
> If the default and fallback models use the same provider, a warning is displayed. Using different providers for default and fallback improves resilience against provider outages.

> [!NOTE]
>
> When **Use provider default** is selected, the assignment inherits the catalog default model. Changes to the catalog default automatically propagate.

***

## Fallback behavior

When a primary model is unavailable, rate-limited, or disabled at the organization level, the system automatically switches to the configured fallback model. The resolution order is:

1. **Node-level override** (if configured) → its fallback model
2. **Workspace default** → its fallback model
3. **Error** if all options exhausted

| Scenario | Behavior |
| - | - |
| Primary model unavailable | Fallback model is used automatically |
| Node override model not found | Falls back to workspace default model |
| API key expired or revoked | Nodes using this provider's models fail with "API key invalid" in the execution log. Provider shows a warning at the organization level. |
| Both primary and fallback unavailable | Node fails with error: "Primary and fallback models unavailable. Contact your organization admin." |

***

## Per-node model override

Workflow designers can override the default model on individual AI nodes (Custom Agent, Intent Classification Agent, etc.) in the Integration Designer. This allows different nodes in the same workflow to use different models. For example, a fast model for intent classification and a more capable model for complex reasoning.

![Per-node model override in Integration Designer workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/node_level.png)

### How it works

When configuring an AI node, an optional **Model Override** section lets you select a specific model:

| Field | Description |
| - | - |
| **Provider type** | The provider to use (e.g., `OPENAI`) |
| **Model** | The specific model |
| **Fallback provider type** | Optional fallback provider if the primary is unavailable |
| **Fallback model** | Optional fallback model |

The override uses portable identifiers (`providerType` + `modelIdStr`) that resolve at runtime against the organization's available models. Only models enabled in the organization's whitelist can be selected.

When no override is set, the node uses the workspace default model for its capability (text generation, embeddings, etc.).

> [!NOTE]
>
> Per-node model overrides apply to the **text generation** capability only. Other capabilities (image understanding, embeddings, document/OCR) always use the workspace defaults.

***

## Supported providers

FlowX maintains a provider catalog with pre-configured provider types. Each provider type includes display metadata (name, icon) and optional base URL presets.

| Provider | Key mode | Notes |
| - | - | - |
| **OpenAI** | FlowX Managed or BYOK | EU, US, and Global base URL presets |
| **Azure OpenAI** | BYOK | Custom endpoint (your Azure deployment URL); uses an `api-key` header and requires an `api-version` query parameter. East US and West Europe presets |

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Mistral** is also available as a BYOK provider: add it with your own Mistral API key, then enable models from the seeded catalog. Mistral models cover chat, image understanding, embeddings, and document OCR (the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed lines).

### Custom provider (self-hosted endpoints)

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Custom** provider type connects FlowX to any self-hosted, OpenAI-compatible endpoint, for example a local text-embeddings server or an Ollama instance. It is designed for organizations that need embedding models to run on their own infrastructure so that sensitive content never leaves it.

A Custom provider differs from catalog providers:

* **Free-form Base URL**: point it at any OpenAI-compatible endpoint. No presets.
* **BYOK only**: there is no FlowX-managed key option.
* **No seeded model catalog**: you register models manually, with the model ID, its capability (embeddings), and the embedding dimensions.

Embedding models registered on a Custom provider appear as **local embedding models** in Knowledge Base configuration. A Knowledge Base with **Containing Personal Information** turned on is indexed with a local embedding model instead of the cloud default, so its content is never sent to an external embedding provider. See [Containing personal information](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information) in the Knowledge Base documentation.

***

## Permissions

| Permission | Description |
| - | - |
| `org_ai_providers_read` | View AI providers and model assignments at organization level |
| `org_ai_providers_edit` | Add, edit, delete providers, manage model whitelists, and configure Defaults & Fallbacks |

***

## Related resources

> [card] [AI in FlowX](./ai-in-flowx)
>
> Overview of AI capabilities in the FlowX platform

> [card] [Agent Builder](./agent-builder/overview)
>
> Build AI agents that use the configured models

> [card] [Chat-driven workflows](./chat-driven-workflows)
>
> Create chat experiences powered by AI models

> [card] [Organization Settings](/5.9/docs/saas/organization-settings)
>
> Manage organization-level settings


# Chat component
Source: https://docs.flowx.ai/5.9/ai-platform/chat-component

Technical reference for the Chat component - runtime behavior, session management, workflows, and SDK integration.

The Chat component enables interactive AI agent conversations with end-users within FlowX apps. This page covers runtime behavior, session management, and advanced integration patterns.

<video />

> [!NOTE]
>
> For UI configuration, settings, and styling, see the [Chat component in UI Designer](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat).

## Key features

> [card] Real-time messaging
>
> Send and receive messages instantly with streaming support

> [card] AI agent integration
>
> Connect to workflows powered by AI agents

> [card] Session management
>
> Automatic session handling and persistence across page refreshes

> [card] Message history
>
> Retrieve and display conversation history on refresh

> [card] Knowledge Base integration
>
> Ground AI responses in your organization's data using RAG capabilities

> [card] Reasoning transparency
>
> Show AI reasoning steps to users for trust and transparency

> [card] Flexible display modes
>
> Inline, Overlay, FullScreen, and Floating modes with per-mode theming for Web, Android, and iOS

***

## Display modes

> [!NOTE]
>
> The Chat component supports four distinct display modes, including mobile chat support.

When adding a Chat component, you choose a **display mode** that determines how the chat renders and behaves at runtime.

| Display mode | Description | Placement |
| - | - | - |
| **Inline** | Renders in place within the page layout (default) | Child of any container or card |
| **Overlay** | Positioned overlay panel with minimize and expand controls | Child of Page or Root Zone |
| **FullScreen** | Takes over the full viewport | Child of Page or Root Zone |
| **Floating** | Floating panel triggered by a FAB (Floating Action Button) | Child of Page or Root Zone |

> [!NOTE]
>
> You can change the display mode after creation if needed.

### Mode details

> [tab] Inline
>
> Renders within the parent component, filling the available space. This is the default mode.
>
> * Can be a child of **any container or card**
> * Embeds directly into the page layout
> * Best for dedicated chat pages or inline chat experiences
> * Width and height follow the parent container; supports **Fill** or **Fixed** sizing

> [tab] Overlay
>
> Renders as a positioned panel on top of the page content, with controls to minimize or expand.
>
> * Must be a child of **Page** or **Root Zone** (global scope)
> * Includes minimize and expand buttons in the chat header
> * Useful when the chat should be accessible without leaving the current page context

> [tab] FullScreen
>
> Takes over the full viewport when opened.
>
> * Must be a child of **Page** or **Root Zone**
> * Provides an immersive, distraction-free chat experience
> * Triggered via the chat header button or a FAB
> * Automatically dismissed when the user closes or navigates away

> [tab] Floating
>
> Renders as a floating panel anchored to a corner of the screen. Triggered by a **Floating Action Button (FAB)**.
>
> * Must be a child of **Page** or **Root Zone**
> * FAB defaults to bottom-right position (`right: 24px`, `bottom: 24px`)
> * FAB dimensions: `56 × 56px` (configurable)
> * Chat panel defaults: `420px` wide, `640px` tall
> * Best for persistent, always-accessible chat without interrupting main content

### Sizing defaults

| Display mode | Default width | Default height | Notes |
| - | - | - | - |
| **Inline** | Fill (parent) | Fill (parent) | Supports Fill or Fixed sizing |
| **Overlay** | Configurable | Configurable | Positioned over content |
| **FullScreen** | Full viewport | Full viewport | No sizing controls |
| **Floating** | `420px` (fixed) | `640px` (fixed) | FAB at `right: 24px`, `bottom: 24px` |

### Theming per display mode

Theme values can be set independently for each display mode and per platform (Web, Android, iOS) through **Design Assets** → **Themes** → **Components** → **Chat**.

| Platform | Configurable modes |
| - | - |
| **Web** | Inline, Floating, FullScreen |
| **Android** | Inline, Floating, FullScreen |
| **iOS** | Inline, Floating, FullScreen |

Each mode supports independent configuration for padding, margin, and other layout tokens.

### Chat header button and URL synchronization

The chat header includes a state-aware button that adapts based on the current display mode (for example, toggling between fullscreen and overlay views). Chat session state is also synchronized to the browser URL via `popstate`, so navigating back or refreshing the page restores the correct session context.

### Global component

The Chat component can be added as a **Global Component** in UI Flows, making it persist across pages without needing to add it to each page individually.

When configured as a global component:

* The chat appears in the **Global Components** section of the left navigation panel
* It persists as users navigate between pages in the UI Flow
* You can **attach** or **detach** the chat from specific pages to control where it appears
* The chat maintains its conversation state across page navigation

To add Chat as a global component, click **+** in the **Global Components** section of the UI Flow navigation panel, then select **Chat** and configure its display mode.

> [!TIP]
>
> Use Global Components when you want the chat to be available throughout the entire app experience without re-adding it to every page.

### Sizing

The Chat component and floating action button support **fixed sizing**, allowing you to set a specific width and/or height value for precise control over the chat container dimensions.

***

## Subcomponents

> [!NOTE]
>
> The Chat component includes specialized subcomponents for reasoning display, error handling, and message regeneration.

The Chat component is composed of the following subcomponents:

| Subcomponent | Description |
| - | - |
| **Header** | Configurable header with avatar, title, subtitle, new chat button, fullscreen toggle, and dock/collapse controls |
| **Messages** | Message display with sender/receiver differentiation, markdown rendering, and avatar support |
| **Chat History** | Conversation history list showing past chat sessions grouped by time, with the ability to resume previous conversations |
| **Suggested Prompts** | Pre-configured prompt suggestions displayed before the user types, allowing quick-start interactions |
| **Reasoning** | Displays AI reasoning steps (thinking indicators) during response generation |
| **Input** | Message input field with configurable placeholder and multiline support. Includes a Stop button to cancel an in-progress agent response. |
| **File Attachments** | Attach control in the input area, with a File Item row per pending file. Carries the accepted types, count and size limits, and the error copy |
| **Attached Files** | Files sent with a user message, with a File Item row per file |

### Reasoning display

The reasoning subcomponent shows users how the AI agent is processing their request. When enabled, a thinking indicator appears while the agent works through its reasoning steps.

| Property | Description |
| - | - |
| **reasoning** | Toggle to show/hide reasoning steps in the chat |
| **thinkingMessage** | Custom message to display during reasoning (e.g., "Thinking...") |

### Error handling and regeneration

When a message fails to generate, the chat displays an error state with an option to retry:

| Property | Description |
| - | - |
| **errorMessage** | Custom error message to display on failure |
| **canRegenerate** | Enable the regenerate button on failed messages |
| **regenerateLabel** | Custom label for the regenerate button |

### Chat History

Chat History displays a list of conversations started by the current user, grouped by time period: **Today**, **Yesterday**, **Previous 7 Days**, **Previous 30 Days**, and **Older**.

![Chat History panel showing past conversations grouped by time](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)

#### Behavior

* The chat history button is always visible in the chat header
* When opened, the list shows each conversation with its title and timestamp (displayed in a tooltip)
* Available actions: **New chat**, **Expand/Minimize**, **Dock** (hide chat)
* Opening a conversation from the list resumes the session:
  * Messages are prefilled with the last exchanged messages
  * Scrolling up loads older replies
  * New messages continue on the same session ID
* Conversations are **per-user** — attempting to access another user's history shows an access denied error and redirects to a new chat session

#### Theming

Chat History adds three new themed elements configurable per display mode (Inline, Floating, FullScreen) and per platform (Web, Android, iOS) through **Design Assets** → **Themes** → **Components** → **Chat**:

| Theme element | Description |
| - | - |
| **Chat History** | Container for the conversation list (padding, empty state font/color, gap) |
| **Chat History Section** | Time-group headers like "Today" or "Previous 7 Days" (title font/color, gap) |
| **Chat History Item** | Individual conversation entry with hover state (padding, font, border radius, background color) |

Two new system icons are added: `sys_ChatHistory` and `sys_ChatBack`.

#### Localization

Chat History uses system substitution tags for all labels. Override these in **CMS** → **Substitution Tags** to customize or localize:

| Substitution tag | Default (EN) |
| - | - |
| `sys_chat_tooltip_chat_history` | Chat History |
| `sys_chat_tooltip_new_chat` | New chat |
| `sys_chat_tooltip_expand` | Expand |
| `sys_chat_tooltip_minimize` | Exit full screen |
| `sys_chat_tooltip_dock` | Hide chat |
| `sys_chat_tooltip_back` | Back |
| `sys_chat_time_group_today` | Today |
| `sys_chat_time_group_yesterday` | Yesterday |
| `sys_chat_time_group_previous_7_days` | Previous 7 Days |
| `sys_chat_time_group_previous_30_days` | Previous 30 Days |
| `sys_chat_time_group_older` | Older |
| `sys_chat_conversations_empty_state` | No Conversations yet |
| `sys_chat_forbidden` | Access denied. This chat history belongs to another user. |

#### Search

Chat History includes a search box that filters the conversation list by a text query. Search runs on the server across the user's conversations, highlights matches in the results, and shows an empty state when nothing matches. (SaaS · 5.11)

***

### Chat notifications

The chat adds a themeable **Notification Dot** — an indicator you can position and size from the chat style panel — together with an unread-message indicator on the chat button that shows the number of unread agent messages. (SaaS · 5.11)

### Message actions

Each agent message supports per-message actions: **copy** the message content, show a **timestamp**, and give **thumbs up / thumbs down** feedback. Copy and timestamp visibility are controlled by the **Show Copy Action** and **Show Timestamp** toggles in the chat configuration. (SaaS · 5.11)

#### Rating an answer

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Rating an answer is a two-step interaction, and the two directions behave differently. A **thumbs up** is recorded straight away. A **thumbs down** opens a short form first, so a negative rating can carry a reason and a comment rather than just a score. Either rating can be withdrawn afterwards.

The reasons offered in that form are yours to define: supply the list you want, and the chat shows them as selectable chips. Leave the list empty and the reader can still submit a comment. Because the entries pass through localisation, they can be translation keys rather than fixed text.

| Setting | What it does | Default |
| - | - | - |
| **Show response feedback** | Whether the rating controls appear on agent messages | On |
| **Feedback reasons** | The reasons offered after a thumbs down | Empty |

Each rating is stored with the value, the chosen reason, the comment, and who submitted it and when. Ratings are recorded in [audit](/5.9/docs/platform-deep-dive/core-extensions/audit), so the quality of a deployed agent is something you can review rather than estimate.

The reason chips are themable, with separate selected and hover states, and the SDKs expose the same feedback state to a custom front end.

***

### Disabling the chat input

You can disable the chat input based on a business condition. When the condition evaluates to true, the input becomes read-only, shows a tooltip explaining why it is disabled, and clears any text already typed. (SaaS · 5.11)

***

### Markdown rendering in messages

Agent (receiver) messages support Markdown formatting, allowing AI-generated responses to include structured content. The renderer automatically converts Markdown syntax to styled HTML.

**Supported syntax:**

| Syntax | Renders as |
| - | - |
| `**bold**` | **Bold** text |
| `*italic*` | *Italic* text |
| `# Heading` through `###### Heading` | Heading levels 1–6 |
| `` `inline code` `` | Inline code |
| ` ``` code block ``` ` | Fenced code block |
| `- item` or `1. item` | Unordered and ordered lists |
| `[text](url)` | Hyperlink (opens in a new tab) |
| Single newline | Line break (`<br/>`) |

> [!TIP]
>
> When building AI agent prompts, you can instruct the agent to format responses using Markdown — the chat component renders the output automatically.

***

### Suggested Prompts

The Suggested Prompts subcomponent displays a set of pre-configured prompt suggestions to the user before they begin typing. When a suggestion is clicked, its text is sent as the user's input, starting the conversation immediately.

![Suggested Prompts displayed in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)

#### Props

| Property | Type | Default | Description |
| - | - | - | - |
| `title` | string | `"Suggested Prompts"` | Section heading displayed above the prompt list |
| `prompts` | string\[] | — | Array of prompt strings to display as suggestions |

#### Behavior

* The subcomponent only renders when at least one prompt is provided in the `prompts` array. If the array is empty or not set, the section is hidden entirely.
* Clicking a suggestion sends that prompt text as the user's input, triggering the chat workflow as if the user typed and submitted the message.
* Long prompt strings that exceed the display area are truncated and shown in full via a **tooltip** on hover.

#### Theming

Full theming support is available in both Angular and React SDKs. Styles can be configured per display mode (Inline, Floating, FullScreen) and per platform (Web, Android, iOS) through Theme Admin (**Design Assets** → **Themes** → **Components** → **Chat** → **Suggested Prompts**).

> [!TIP]
>
> Use suggested prompts to guide users toward the most common questions or actions in your chat experience. Keep individual prompts short and action-oriented so they remain readable without truncation.

#### AI-generated prompt suggestions

In addition to the static suggested prompts configured above, the chat component can display **AI-generated prompt suggestions** that are dynamically created by Custom Agent nodes in chat-driven workflows.

When a Custom Agent node has **Prompt Suggestions** enabled (via its satellite panel), the agent generates contextual follow-up suggestions alongside each reply. These appear as clickable chips below the agent's message, similar to static suggested prompts but tailored to the conversation context.

**Key differences from static suggested prompts:**

| | Static suggested prompts | AI-generated suggestions |
| - | - | - |
| **Source** | Configured on the chat component | Generated by Custom Agent node per reply |
| **When shown** | Empty state or as configured | After each agent reply that includes suggestions |
| **Content** | Fixed text | Dynamic, context-aware |
| **Configuration** | Chat component settings | Custom Agent node satellite panel |

When a user clicks an AI-generated suggestion, the chip's `label` is displayed as the user's message while the full `content` is sent as input to the next workflow run.

For configuration details, see the [Custom Agent node documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions).

***

### Voice input

Users can send voice messages in addition to typed text. When voice input is enabled, a microphone button appears in the chat input. Clicking it records audio in the browser; the recording is uploaded and sent as the user's next message, appearing in the chat history as an audio player alongside text messages.

#### Enabling voice input

Voice input is configured on the **Chat Input** sub-component in UI Designer:

| Property | Description | Default |
| - | - | - |
| **Enable Voice Input** | Toggle the microphone button in the chat input | `Off` |

When enabled, the microphone button is shown by default, the SDK handles recording, upload, and playback, and the agent receives the audio file as part of the message payload.

> [!WARNING]
>
> Enabling voice input only adds recording, upload, and playback in the chat UI — it does not transcribe the audio. The chat-driven workflow behind the chat must include a [Speech to Text node](/5.9/ai-platform/agent-builder/speech-to-text) with its file source set to **Chat Input**. Without it, the agent receives an audio file it cannot interpret, and voice messages go unanswered.

#### Runtime behavior

* **Recording limit:** 2 minutes per message. Longer recordings stop automatically.
* **Blocked during replies:** The microphone is disabled while the agent is streaming a response (SSE in progress) to prevent interleaved turns.
* **Single player:** Only one audio message can play at a time — starting a new playback pauses any other voice message.
* **History:** Voice messages are persisted with the rest of the conversation and replayed with a progress bar when the user scrolls back.

***

### File attachments

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Users can send files together with a text message. The attach button appears in the chat input once **Enable File Attachments** is turned on, and the files are uploaded before the message reaches the conversational workflow.

Configuration lives on the **File Attachments** sub-component in UI Designer. For the field-by-field reference, see [File Attachments](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat#settings-by-sub-component) in the UI Designer component guide.

#### Runtime behavior

* **File selection** uses the platform's native file picker, constrained to the configured accepted types where the picker supports type filtering.
* **Validation runs client-side** for accepted types, file count, and total size, before anything is uploaded.
* **Send is blocked** while any file row or the attachments area is in an error state.
* **Upload happens on send.** Files upload first, then the message is delivered to the workflow with the original file name, storage path, and MIME type for each file.
* **A whole batch fails together.** If any file in the batch fails to upload, the send fails rather than delivering a partial set.
* **Failed uploads keep the message.** The error is surfaced separately from the file rows, the send button stays enabled, and the typed text and selected files are kept so the user can send again.

> [!WARNING]
>
> The per-file limit the Designer enforces is **10 files**, and the size limit is a **total** for the batch rather than per file.

#### Where uploaded files go

Uploaded files are extracted and indexed into a knowledge base scoped to that chat session, so AI nodes in the conversational workflow answer grounded in their content. Session knowledge bases are isolated per conversation and per tenant, and are excluded from app export.

For the workflow side, see [File uploads](/5.9/ai-platform/chat-driven-workflows#file-uploads) in Chat-driven workflows.

#### Theming

**File Attachments** and **File Item** are themed per display mode (Inline, Floating, FullScreen) and per platform (Web, Android, iOS) through **Design Assets** → **Themes** → **Components** → **Chat**. File Item carries a default and an error state, so an invalid file can be styled distinctly from a valid one. The input area gains an attach icon, and File Item uses delete and download icons.

| Theme element | Description |
| - | - |
| **Chat Input File Attachments** | Container for pending files in the input area, including the error text style |
| **Chat Input File Item** | Pending-file row: padding, border, radius, file name and file info text, delete icon, default and error states |
| **Chat User File Attachments** | Container for files shown with a sent user message |
| **Chat User File Item** | Sent-file row, with the download icon |

#### Localization

Attachment labels are accessibility labels driven by system substitution tags. Override them in **CMS** → **Substitution Tags**:

| Substitution tag | Default (EN) |
| - | - |
| `sys_a11y_chat_attach_files` | Attach file |
| `sys_a11y_chat_remove_file` | Remove file |
| `sys_a11y_chat_download_file` | Download file |
| `sys_chat_attachments_upload_error` | There was an error uploading the files |

***

### Stop agent response

When the user presses Stop:

* The running chat-driven workflow is cancelled. If cancellation happens before any AI node executes, the user prompt is persisted as cancelled and no AI call is made. If it happens while an AI node is executing, the in-flight AI call is stopped and any partial response is discarded.
* The chat receives a `chatCancelled` SSE event on the `CHAT_WORKFLOW_RESPONSE` channel, signalling the UI to exit the streaming state.
* The user message is stored with a `cancelled: true` flag on the chat message record.

Stop is supported on Web (Standard, Floating, Full Screen), iOS, and Android.

For details on the underlying workflow cancel API and pre-AI vs during-AI behavior, see [Cancelling a running workflow](/5.9/ai-platform/chat-driven-workflows#cancelling-a-running-workflow).

#### Theming

The Stop button uses a system icon registered as `stopResponseIcon` under each chat input area. Defaults preloaded by `cms-core`:

| Theme content | Property | Default value |
| - | - | - |
| `chatInputArea`, `chatInputAreaFloating`, `chatInputAreaFullScreen` (Web) | `stopResponseIcon` | `sys_ChatStopResponse` |
| `chatInputArea` (iOS) | `stopResponseIcon` | `sys_ChatStopResponse` |
| `chatInputArea` (Android) | `stopResponseIcon` | `sys_ChatStopResponse` |

Override `stopResponseIcon` in the active theme to swap the icon, the same way you would override `sendMessageIcon` or `voiceInputIcon`.

#### Localization

The chat input action labels are configurable via system substitution tags. The `a11y` variants are used as accessibility labels (screen reader text); the non-`a11y` variants are used as visible labels and tooltips.

| Substitution tag | Purpose | Default English value |
| - | - | - |
| `sys_chat_cancel_request` | Stop button label | Stop generating response |
| `sys_a11y_chat_cancel_request` | Stop button accessibility label | Stop generating response |
| `sys_chat_submit_message` | Send button label | Send message |
| `sys_a11y_chat_submit_message` | Send button accessibility label | Send message |

***

### Chat configuration

The `chatConfig` object controls the behavior and appearance of the chat:

| Property | Type | Description |
| - | - | - |
| `welcomeMessage` | string | Initial message shown when the chat opens |
| `thinkingMessage` | string | Message displayed during AI reasoning |
| `title` | string | Header title text |
| `subtitle` | string | Header subtitle text |
| `showChatIcon` | boolean | Show/hide the chat icon |
| `showSeparator` | boolean | Show/hide the separator between messages |
| `newChatLabel` | string | Label for the new chat button |
| `errorMessage` | string | Message shown on errors |
| `canRegenerate` | boolean | Enable message regeneration on failure |
| `regenerateLabel` | string | Label for the regenerate button |
| `inputPlaceholder` | string | Placeholder text for the input field |
| `maxInputRows` | number | Maximum number of rows for multiline input |
| `historyTitle` | string | Title text displayed on the chat history panel |

***

## Runtime behavior

### Starting a chat

**1. User initiates chat**

User opens the chat from the UI Flow

**2. API call**

System calls the start chat API with the configured workflow

**3. Session created**

API returns a `chatSessionId` that is persisted for the user

**4. Initial message**

First message typically comes from the AI agent as a greeting or conversation starter

> [!NOTE]
>
> The initial system message can be configured in the workflow to provide a customized greeting or conversation starter.

### Message exchange

> [tab] Sending messages
>
> 1. User types message in input field
> 2. Message is sent to the workflow via Chat Input node
> 3. Workflow processes the message through AI nodes
> 4. Response is returned to the chat interface

> [tab] Receiving messages
>
> * Messages appear in real-time with streaming support
> * User messages aligned to one side
> * Agent messages aligned to the other side
> * Timestamps displayed (configurable)

### Session management

> [card] Session persistence
>
> * `sessionId` stored in browser session/local storage
> * Enables conversation continuity across page refreshes
> * Session data includes message history

> [card] Message history retrieval
>
> * On page refresh, system loads existing `sessionId`
> * Retrieves and displays previous messages
> * Restores conversation state automatically

### Data storage

Chat sessions are persisted in the **FlowX Database**:

> [!NOTE]
>
> Each chat session is stored as a **document** containing the complete chat history. The chat component works with the FlowX Database to save chat sessions, where each session document contains the full conversation record.

| Data Element | Storage Location | Description |
| - | - | - |
| **Session ID** | Browser storage + Database | Unique identifier linking client to server-side session |
| **Message history** | FlowX Database | Complete record of all messages in the conversation |
| **Session metadata** | FlowX Database | Timestamps, workflow reference, user information |

> [!TIP]
>
> **Transparent persistence**: Message persistence to the database is handled transparently by the platform. No additional configuration is required to enable chat history storage.

***

## Conversation history API

FlowX provides REST API endpoints for retrieving conversation history programmatically. These are useful for building custom dashboards, analytics, or integrating conversation data into external systems.

### List conversations

Retrieve all conversations for the current authenticated user within a workspace and app.

```bash theme={"dark"}
GET /api/runtime/wks/{workspaceId}/app/{appId}/conversations
```

**Path parameters:**

| Parameter | Type | Description |
| - | - | - |
| `workspaceId` | UUID | The workspace identifier |
| `appId` | UUID | The app identifier |

**Query parameters (optional):**

| Parameter | Type | Description |
| - | - | - |
| `startDate` | ISO 8601 timestamp | Filter conversations created after this date |
| `endDate` | ISO 8601 timestamp | Filter conversations created before this date |
| `businessCaseId` | UUID | Filter by business case identifier |
| `page` | integer | Page number for pagination |
| `size` | integer | Number of conversations per page |

**Response:**

```json theme={"dark"}
{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "state": "ACTIVE",
      "createdAt": "2026-03-10T14:30:00Z",
      "summary": "Customer asked about account verification process",
      "messageCount": 12
    }
  ],
  "total": 1
}
```

### Fetch a single conversation

Retrieve a single conversation with its full message history.

```bash theme={"dark"}
GET /api/runtime/wks/{workspaceId}/app/{appId}/conversations/{conversationId}
```

**Path parameters:**

| Parameter | Type | Description |
| - | - | - |
| `workspaceId` | UUID | The workspace identifier |
| `appId` | UUID | The app identifier |
| `conversationId` | UUID | The conversation (chat session) identifier |

**Query parameters (optional):**

| Parameter | Type | Description |
| - | - | - |
| `page` | integer | Page number for message pagination |
| `size` | integer | Number of messages per page |

**Response:**

```json theme={"dark"}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "ACTIVE",
  "summary": "Customer asked about account verification process",
  "createdAt": "2026-03-10T14:30:00Z",
  "userEmail": "user@example.com",
  "messages": [
    {
      "actor": "human",
      "message": "How do I verify my account?",
      "timestamp": "2026-03-10T14:30:05Z",
      "messageId": "msg-001"
    },
    {
      "actor": "agent",
      "message": "To verify your account, navigate to **Settings** → **Verification**...",
      "timestamp": "2026-03-10T14:30:08Z",
      "messageId": "msg-002"
    }
  ],
  "total": 2
}
```

**Error responses:**

| Status | Description |
| - | - |
| `404` | Conversation not found |
| `403` | User does not have access to this conversation |

> [!NOTE]
>
> These endpoints return conversations owned by the authenticated user only. The workspace must belong to the user's organization.

***

## Custom chat persistence workflow

For advanced use cases where you need full control over chat session storage, you can build a custom workflow that manages chat persistence using FlowX Database. This approach allows you to:

* Customize the chat data model
* Add additional metadata to chat sessions
* Integrate with external systems
* Implement custom session management logic

### Workflow overview

The chat persistence workflow handles two main scenarios:

1. **Loading chat history** - When a user returns to an existing chat session
2. **Processing new messages** - When a user sends a new message

```mermaid theme={"dark"}
flowchart TD
    A[Start] --> B[Get chat session]
    B --> C{Action type?}
    C -->|LOAD_HISTORY| D[Return chat history]
    C -->|NEW_MESSAGE| E{Session exists?}
    E -->|No| F[Create new session]
    E -->|Yes| G[Update session history]
    F --> H[Return response]
    G --> I[Update chat session]
    I --> H
```

### Setting up the FlowX database data source

**1. Create the data source**

Navigate to **Integrations** → **Data Sources** → **Add New Data Source** and select **FlowX Database**.

**2. Configure the collection**

Name the collection (e.g., `chat`) and define the schema based on your data model.

**3. Define the data model**

Create a data model with the following structure:

| Field | Type | Description |
| - | - | - |
| `chatSessionId` | string | Unique identifier for the chat session |
| `history` | array | List of message objects |
| `history[].actor` | string | Message sender (`human` or `agent`) |
| `history[].message` | string | The message content |

### Building the workflow

**1. Create the workflow**

Create a new workflow in Integration Designer with the following input parameters:

```json theme={"dark"}
{
  "humanMessage": "",
  "action": "",
  "chatSessionId": ""
}
```

The `action` parameter determines whether to load history (`LOAD_HISTORY`) or process a new message.

**2. Add Get chat session node**

Add a **Database Operation** node to retrieve the existing session:

| Property | Value |
| - | - |
| **Operation** | `db.chat.findOne` |
| **Description** | Chat session history |
| **Parameter: chatSessionId** | `${chatSessionId}` |
| **Response Key** | `chatSession` |

**3. Add action type condition**

Add a **Condition** node to check the action type:

```javascript theme={"dark"}
input.action == "LOAD_HISTORY"
```

* **If true**: Route to the "Return chat history" end node
* **Else**: Continue to message processing

**4. Add Return chat history end node**

For the `LOAD_HISTORY` branch, add an **End Flow** node that returns the chat history:

```json theme={"dark"}
{
  "history": "${chatSession.data.history}"
}
```

**5. Add session exists condition**

For new messages, add another **Condition** node to check if the session exists:

```javascript theme={"dark"}
input.chatSession.data == null
```

**6. Add Create chat session node**

If the session doesn't exist, add a **Database Operation** node to create it:

| Property | Value |
| - | - |
| **Operation** | `db.chat.insertOne` |
| **Description** | Create chat session |
| **Parameter: chatSessionId** | `${chatSessionId}` |
| **Parameter: history** | `[{ "actor": "human", "message": "${humanMessage}" }]` |
| **Response Key** | `responseKey` |

**7. Add Update history script node**

If the session exists, add a **Script** node to append the new messages:

```javascript theme={"dark"}
const history = input.chatSession.data.history;

const updatedHistory = [
  ...history,
  { actor: "human", message: input.humanMessage },
  { actor: "agent", message: input.agentMessage }
];

output.put("updatedHistory", updatedHistory);
```

**8. Add Update chat session node**

Add a **Database Operation** node to save the updated history:

| Property | Value |
| - | - |
| **Operation** | `db.chat.updateOne` |
| **Description** | Update chat session |
| **Parameter: chatSessionId** | `${chatSessionId}` |
| **Parameter: history** | `${updatedHistory}` |
| **Response Key** | `responseKey` |

**9. Add Return response end node**

Add an **End Flow** node that returns the response:

```json theme={"dark"}
{
  "message": {
    "chatSessionId": "${chatSessionId}",
    "agentMessage": "${agentMessage}"
  }
}
```

### Chat session data model example

```json theme={"dark"}
{
  "chatSessionId": "session-abc-123",
  "history": [
    {
      "actor": "human",
      "message": "Hello, I need help with my account"
    },
    {
      "actor": "agent",
      "message": "Hello! I'd be happy to help you with your account. What do you need assistance with?"
    }
  ]
}
```

***

## UI Flow integration

The Chat component integrates with UI Flows:

**Chat Component Wrapper**

* Chat component is embedded within UI Flow structure
* Follows UI template hierarchy
* Shares session context with other components

**Communication with Other Components**

> [accordion] Event-based communication
>
> * Components emit and listen for custom events
> * Enables loosely coupled interactions
> * Example: Chat triggers process start event

> [accordion] On-demand communication
>
> * Direct component-to-component calls
> * For tightly integrated features
> * Example: Chat updates task management state

***

## Audit and debugging

### UI Flows audit

> [card] Chat sessions tracking
>
> All chat sessions are logged in UI Flow audit:
>
> * Track when chats are started
> * Monitor active and completed sessions
> * View session duration and message count

> [card] Console logging
>
> Access detailed execution information:
>
> * View workflow execution logs
> * Debug conversation flow

### Debug interface

**UI Flow Sessions Console**

Access comprehensive debugging tools through the **UI Flow Sessions** panel:

> [tab] Nodes
>
> Track workflow execution with node-by-node timing:
>
> | Node | Typical Duration |
> | - | - |
> | Start | 0 ms |
> | Get chat session | \~133 ms |
> | Check action type | \~52 ms |
> | Return chat history | \~60 ms |

> [tab] Logs
>
> View detailed execution logs:
>
> * Workflow Run ID and timestamps
> * Triggered from: AUTOMATIC
> * Node execution start/finish events
> * Data Source operations (FlowX Database)
> * Collection: `chat`
> * Operations: `db.chat.findOne` - Chat session history
> * Status, Time, and Size metrics

> [tab] Input/Output
>
> Inspect workflow data:
>
> * Input parameters passed to the workflow
> * Output data returned from nodes
> * Session state changes

***

## SDK integration

The Chat component is available through the FlowX SDKs for both Angular and React applications.

> [card] [Angular SDK](../sdks/angular-renderer#chat-component)
>
> Use the `FlxChatRendererComponent` in Angular applications
>
> ```ts theme={"dark"}
> import { FlxChatRendererComponent } from '@flowx/angular-sdk';
> ```

> [card] [React SDK](../sdks/react-renderer#chat-component)
>
> Use the `FlxChatRenderer` component in React applications
>
> ```tsx theme={"dark"}
> import { FlxChatRenderer } from '@flowx/react-sdk';
> ```

### Key SDK parameters

| Parameter | Description | Required |
| - | - | - |
| `apiUrl` | Your base FlowX API URL | ✅ |
| `authToken` | Authorization token from auth provider | ✅ |
| `projectId` | The FlowX project ID | ✅ |
| `workspaceId` | The workspace ID | ✅ |
| `source` | Source object with workflow type and ID | ✅ |
| `chatConfig` | Chat configuration object (welcome message, title, etc.) | ❌ |
| `themeId` | Theme identifier for styling | ❌ |
| `language` | Language for localization | ❌ |

> [!NOTE]
>
> For the complete list of parameters and usage examples, see the respective SDK documentation pages linked above.

***

## Best practices

### Workflow design

> [card] Do
>
> * Keep chat workflows focused on a single use case
> * Use clear, natural language prompts
> * Test with various user inputs
> * Handle errors gracefully with helpful messages

> [card] Don't
>
> * Don't create overly complex conversation flows
> * Don't send responses from multiple Custom Agent nodes

### User experience

> [card] Do
>
> * Provide clear initial greeting messages
> * Show typing indicators during processing
> * Display helpful error messages
> * Allow users to restart conversations

> [card] Don't
>
> * Don't make users wait too long for responses
> * Don't use technical jargon in agent messages
> * Don't lose conversation context

### Performance

> [card] Do
>
> * Optimize workflow execution time
> * Cache frequently accessed data
> * Limit message history retrieval

> [card] Don't
>
> * Don't load entire conversation history every time
> * Don't make unnecessary API calls

***

## Troubleshooting

> [accordion] Chat not loading
>
> **Possible causes:**
>
> * Workflow is not properly configured
> * Workflow is not published
> * UI Flow has incorrect agent ID/workflow name
>
> **Solutions:**
>
> * Verify the workflow is properly configured
> * Check that the workflow is published and active
> * Ensure UI Flow has correct agent ID/workflow name

> [accordion] Messages not sending
>
> **Possible causes:**
>
> * Network connectivity issues
> * Workflow is in error state
> * Configuration errors
>
> **Solutions:**
>
> * Check network connectivity
> * Verify workflow is not in error state
> * Review workflow console logs for errors

> [accordion] Session lost on refresh
>
> **Possible causes:**
>
> * sessionId is not persisted in storage
> * Browser storage permissions issues
>
> **Solutions:**
>
> * Ensure sessionId is persisted in storage
> * Check browser storage permissions
> * Verify session management configuration

***

## Knowledge Base integration

The Chat component can use **Knowledge Bases** to provide contextual, grounded AI responses.

### How it works

**1. Create Knowledge Base**

Set up a Knowledge Base as a Data Source in Integration Designer and upload relevant content

**2. Content processing**

Documents are automatically split into "chunks" and indexed for semantic search

**3. Link to Custom Agent**

Connect the Knowledge Base to Custom Agent nodes in your workflow

**4. Context retrieval**

When a user sends a message, relevant chunks are retrieved based on semantic similarity

### Supported file formats

| Format | Description |
| - | - |
| **PDF** | Standard PDF documents |
| **Markdown** | `.md` files with formatted text |
| **Word** | Microsoft Word documents (`.docx`) |
| **Excel** | Spreadsheet data (`.xlsx`) |
| **PowerPoint** | Presentation files (`.pptx`) |
| **Images** | Image files with text content |

### Configuration options

| Option | Description |
| - | - |
| **Minimum relevance** | Threshold for chunk relevance scores (0-1) |
| **Number of responses** | Limit how many relevant chunks are returned to the LLM |
| **Content updates** | Use workflows to dynamically append, update, or replace content |

> [!NOTE]
>
> Knowledge Bases provide **Retrieval-Augmented Generation (RAG)** capabilities, ensuring AI responses are grounded in your organization's actual data.

> [card] [Knowledge Base Documentation](../docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> See the complete Knowledge Base documentation for setup guides and best practices.

***

## Platform availability

> [tab] Web
>
> * All four display modes: Inline, Overlay, FullScreen, Floating
> * Complete feature set including Suggested Prompts, Markdown rendering, and voice input
> * Angular and React renderer support

> [tab] Mobile
>
> * iOS and Android support via native renderers
> * Inline, Floating, and FullScreen display modes
> * Native chat experience optimized for mobile
> * Per-platform theme configuration (padding, margin per mode)

***

## Related resources

> [card] [Chat UI configuration](../docs/building-blocks/ui-designer/ui-component-types/chat)
>
> Settings, styling, and theme configuration

> [card] [Chat interface concepts](./using-agents/chat-interface)
>
> High-level integration patterns

> [card] [Custom Agent Node](../docs/platform-deep-dive/integrations/custom-agent-node)
>
> Custom Agent nodes in Integration Designer

> [card] [Knowledge Base](../docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Configure knowledge bases for grounded AI responses

> [card] [Chat-driven workflows](./chat-driven-workflows)
>
> Build multi-turn chat experiences with session memory and intent routing


# Chat-driven workflows
Source: https://docs.flowx.ai/5.9/ai-platform/chat-driven-workflows

Build multi-turn, AI-powered chat experiences with session memory, intent routing, and context-aware responses.

## Overview

Chat-driven workflows are a specialized workflow type designed for multi-turn chat interactions. Unlike output focused workflows that process structured input/output, chat-driven workflows manage ongoing dialogue between users and AI agents — handling message exchange, session memory, and response routing.

When creating a workflow in the Integration Designer, you choose the workflow type: **Chat Driven** or **Output Focused**. This choice is permanent and cannot be changed after creation.

![Chat-driven workflow canvas with Start, Custom Agent, and End Flow nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_canvas.png)

> [card] Session memory
>
> Automatically persist and retrieve conversation history across messages within a session

> [card] Dedicated Start node
>
> The Start node provides Chat Session ID, User Message, and optional UI Flow Context fields for receiving chat input

> [card] Chat replies
>
> AI agent nodes send responses directly to the Chat component in real time

> [card] Intent routing
>
> Classify user messages and route to appropriate workflow branches using the Intent Classification Agent node

***

## Chat Driven vs Output Focused workflows

| Aspect | Chat Driven | Output Focused |
| - | - | - |
| **Purpose** | Multi-turn dialogue with users | Structured input/output processing |
| **Start node** | Chat Session ID + User Message + optional UI Flow Context | Standard Start node (JSON input) |
| **Memory** | Built-in session memory | No memory |
| **Response delivery** | Direct chat reply from Custom Agent nodes | Output on End node |
| **Data model** | Input/Output tabs hidden | Full data model access |
| **Integration** | Chat component only | Process actions, subworkflows, API |

> [!WARNING]
>
> The workflow type cannot be changed after creation. Choose the appropriate type when creating the workflow.

***

## How it works

**1. User sends a message**

The Chat component sends the user's message and session ID to the workflow.

**2. Memory retrieval**

The Start node retrieves session memory — the last 30 turns of the conversation, sent to the model in full.

**3. AI processing**

The workflow processes the message through AI nodes. Nodes with **Use conversation memory** enabled receive the conversation history as context for their LLM calls.

**4. Response delivery**

The Custom Agent node with **Send as Chat Reply** enabled sends its response directly to the Chat component in Markdown format.

**5. Memory update**

The system stores the user message and AI response in session memory for retrieval on the next turn.

***

## Start node

In Chat Driven workflows, the Start node provides dedicated input fields instead of the standard JSON editor:

| Field | Description | Notes |
| - | - | - |
| **Chat Session ID** | Unique session identifier. Must be a valid UUID. At runtime, the Chat component generates this automatically. For testing, enter any valid UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`). | Required. Used for memory retrieval and storage |
| **User Message** | The user's message text | Required. Referenced in nodes using `${userMessage}` |
| **UI Flow Context** | JSON object passed alongside the user message to provide additional context (e.g., current page, customer ID, or other UI state). Collapsed by default under an expandable section on the Start node. | Optional. Must be a valid JSON object if provided |

At runtime, Chat Session ID and User Message are populated automatically by the Chat component, and the UI Flow Context is populated from the [Conversation Context](#setting-context-from-a-ui-flow) configured on the originating UI Flow. When testing manually via **Run Workflow**, you enter values directly in these fields on the Start node.

![Start node with Chat Session ID, User Message, and UI Flow Context fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)

> [!WARNING]
>
> The Chat Session ID **must be a valid UUID**. Using a plain string (e.g., `test-session-1`) causes a runtime error: `Invalid UUID string`.

> [!NOTE]
>
> The Start node in Chat Driven workflows is not a separate node type — it is the same Start node with a different layout tailored for chat input.

***

## Setting context from a UI Flow

UI Flows can attach a **Conversation Context** to the Chat interaction. At runtime, the resolved JSON is delivered to the chat-driven workflow as the Start node's **UI Flow Context**, giving the agent access to whatever UI state the page chose to share (active record IDs, selected filters, user profile fields, etc.).

![Conversation Context property with Parameters JSON field on a UI Flow Page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context_prop_ui_flow_ui_designer.png)

### Configuring the property

On a Page in the UI Flow designer, open the **Settings** panel and expand **Conversation Context**. Fill in the **Parameters** field with a JSON object containing the keys the workflow should receive.

**Example:**

```json theme={"dark"}
{
  "customerId": "${customerData.id}",
  "currentPage": "order-details"
}
```

> [!TIP]
>
> Use `${expression}` syntax to reference UI Flow data — values are resolved at runtime before the payload reaches the workflow.

***

## Custom Agent node

In Chat Driven workflows, the Custom Agent node has additional configuration options. The full layout from top to bottom:

![Custom Agent node configuration panel in a Chat Driven workflow showing Instructions, Context, Use only referenced values as input, Use conversation memory, Settings, and Response options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/custom_agent_node_conv.png)

### Instructions

The static system prompt for the LLM: role, behavior, and output constraints. The field rejects `${...}` references ("This field is static. Use Context for dynamic values.") — dynamic values go in the **Context** field instead.

### Context

Free text mixed with `${...}` keys, sent to the LLM alongside the Instructions. Use it to pass dynamic values — for example `User message: ${userMessage}`.

> [!NOTE]
>
> On SaaS from FlowX.AI 6.0 (SaaS · 6.0), the chat message is no longer appended to the end of the prompt automatically. It reaches the model only through `${userMessage}` in **Context**, or inside the input data when **Use only referenced values as input** is off. Reference `${userMessage}` whenever the agent should answer the user's message.

### Use only referenced values as input

When turned on, only the input values explicitly referenced with `${...}` placeholders in the **Context** field are sent to the LLM. Everything else in the node's input is dropped before the call.

* Narrows the context the agent sees, which helps it respond more precisely
* Reduces token usage on each call, improving overall performance
* Leave ON by default; turn OFF only if the agent needs to reason over data not referenced explicitly in the Context

### Use conversation memory

When enabled:

* The node includes the conversation history (retrieved via session ID) in the LLM prompt
* Memory consists of the last 30 turns of the conversation, included in full (no summarization)
* The session ID is sent to the AI platform, which attaches the conversation context to the prompt

### Settings

* **MCP Servers** — Select MCP tools available to the agent
* **Knowledge Base** — Connect a knowledge base for RAG-powered responses

### Response

#### Send as Chat Reply

When enabled:

* The node's output is sent directly to the Chat component as a Markdown-formatted response
* The Response Schema field is hidden (the LLM is instructed to return plain text)
* A **Chat Response** tag appears on the node header
* The response triggers a memory update (stores the user message + AI reply in the session memory)

> [!NOTE]
>
> At least one Custom Agent node in the workflow must have **Send as Chat Reply** enabled. If no node sends a chat reply, the console log displays an error.
>
> This is enforced rather than only logged (SaaS · 5.11): a run that completes without any Custom Agent having replied fails with *"No Custom Agent message is sending a response to chat."* A **Navigate in UI Flow** node that completes the turn also counts as the reply. Check every path the conversation can take, including branches that only handle errors or fallbacks.

#### Include Task for Prompt Suggestions

When enabled, the agent generates recommended follow-up prompts that are displayed in the Chat component after the main response. Use this to guide the user toward likely next questions or actions (e.g., "Show me the loan schedule", "Compare with other products").

Leave OFF unless you specifically want AI-generated suggestions shown to the user.

#### Response Key

Always visible. Defines the key where the node output is stored in the workflow data.

#### Response Schema

Only visible when **Send as Chat Reply** is OFF. Defines the expected JSON structure of the LLM response.

***

## Session memory

Chat Driven workflows use built-in session memory stored and managed by FlowX. On each message, the system retrieves the recent conversation history — the last 30 turns (each a user message and the agent's response) — and injects them in full into the LLM's prompt for nodes with **Use conversation memory** enabled.

> [card] [Memory Capabilities](/5.9/ai-platform/agent-builder/memory-capabilities)
>
> Full guide to what gets sent to the model, debugging, and storage

> [!TIP]
>
> The recent conversation history (up to the last 30 turns) is sent to the model in full on each message — there is no summarization. Only user messages and agent responses are included; internal workflow data is not part of the memory.

***

## File uploads

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

End users can attach **multiple files at once** in a chat-driven app, and the conversational workflow can receive those files as input. Uploaded files are extracted and indexed into a **knowledge base scoped to the chat session**, so AI nodes answer grounded in that content. File upload is configured in the Designer and themable, with runtime support on the web renderer.

Session knowledge bases are **isolated per conversation and per tenant**, and are **excluded from app export**.

> [!WARNING]
>
> When a workflow node references one uploaded file directly, do not use array indexing: `${uploadedFiles[0].filePath}` does not resolve and fails the node with "has no value set" even though the value is present. Extract the file with a Script node first (`output.firstFile = input.uploadedFiles[0];`) and reference `${firstFile.filePath}`. See [Referencing workflow data in node configurations](/5.9/docs/platform-deep-dive/integrations/integration-workflows#referencing-workflow-data-in-node-configurations).

***

## Console log

The workflow console log includes additional information for Chat Driven workflows:

> [tab] Workflow level
>
> * **Input tab** — Displays User Message and Chat Session ID in JSON format (read-only)
> * **Output tab** — Displays the chat response as text (not in JSON editor for readability)
> * **Memory tab** — Shows the conversation history and summary sent to the LLM for that workflow instance

> [tab] Custom Agent node
>
> * **Output tab** — Displays the response as text
> * **Logs tab** — Hides the response schema for nodes with **Send as Chat Reply** enabled

***

## Constraints

> [accordion] Cannot be used as a subworkflow
>
> Chat Driven workflows cannot be referenced as subworkflows. The subworkflow node filters out Chat Driven workflows from the selection list.

> [accordion] Cannot be started from Process Actions
>
> The **Start Integration Workflow** action in processes filters out Chat Driven workflows. They can only be started through the Chat component.

> [accordion] User message is mandatory
>
> Running a Chat Driven workflow without a user message triggers an error: *"The user message is mandatory in chat-driven workflows."*

> [accordion] End node is required
>
> A Chat Driven workflow requires an End Flow node to complete the execution path. The End Flow node is simplified (header only, no body configuration) since responses are sent from Custom Agent nodes. The End Flow node is **not auto-created** — you must add it manually from the node palette. It returns an empty output: results reach the user through chat replies, not through the End Flow node.

> [accordion] Chat component integration only
>
> Only Chat Driven workflows can be integrated into the Chat component. Output Focused workflows are filtered out from the Chat component workflow selection.

***

## Navigate in UI Flow node

The **Navigate in UI Flow** node is an action node exclusive to Chat Driven workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — allowing the AI conversation to open forms, dashboards, or any UI flow destination with contextual data.

![Navigate in UI Flow node configuration with UI Flow, Destination, and Parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)

> [!NOTE]
>
> This node only appears in the **Actions** category when editing a Chat Driven workflow. It is not available in Output Focused workflows.

### Configuration

**UI Flow** `select` *required*

Select the UI Flow resource to navigate to. Only UI Flows in the current project and its dependencies are available.

**Destination** `select` *required*

The specific screen (root view) within the selected UI Flow. The destination list is fetched dynamically and displays the navigation tree of the UI Flow.

Changing the destination resets all configured parameters.

**Parameters** `key-value[]`

Dynamic parameters passed to the destination screen as query parameters. The available parameters are defined by the destination's query parameter configuration.

* Use `${expression}` syntax to map workflow data to parameters
* Required parameters are marked with an asterisk (\*)
* Default values are shown when configured on the destination

**Example:** `${customerData.accountId}` maps the workflow's `customerData.accountId` to the destination's query parameter.

### How it works

When the node executes:

1. Validates that the workflow is Chat Driven (fails with error otherwise)
2. Resolves `${expression}` placeholders in parameter values using the current workflow context
3. Sends a navigation command to the Chat component via the events gateway
4. The Chat component opens the target UI Flow screen with the resolved parameters

> [!WARNING]
>
> If any required parameter resolves to an empty value after placeholder resolution, the node fails with an error. Verify that the referenced workflow data keys contain values at runtime.

> [!NOTE]
>
> A chat-driven workflow can't update part of the current screen in place. The Navigate in UI Flow node is the only way it changes which screen is displayed (replies still reach the user through the Chat component), and it always performs a navigation: the destination page loads with the passed parameters and runs its on-load actions again, even when the destination is the page the user is already on.

***

## AI Triggers

AI Triggers (labeled **Reply Triggers** in FlowX Designer) are named message templates that allow different UI Flow pages to launch the same chat-driven workflow with different starting contexts. Instead of passing a plain text user message, a trigger sends a structured message with parameters that get resolved at runtime.

This is useful when multiple pages in your app need to start a conversation with the same workflow but with different initial context — for example, a "Help with this order" button on an order details page vs. a "General support" entry point.

### Key concepts

> [card] Named templates
>
> Each trigger has a name, a message template with `${paramName}` placeholders, and optional parameters with default values

> [card] Parameterized context
>
> Parameters are resolved at runtime — different pages can pass different values for the same trigger

> [card] Transparent to the agent
>
> The resolved message is sent as standard user input — the agent processes it like any other message

> [card] Memory integration
>
> The trigger message is saved to conversation memory but not displayed in the user's chat history

### Defining triggers

![AI Trigger reply in a chat conversation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/reply_trigger.png)

Triggers are defined in the **Reply Triggers** side nav tab (lightning icon) on a chat-driven workflow.

![Reply Triggers configuration panel with trigger name, user message, and parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/reply_triggers.png)

**1. Open the Reply Triggers tab**

In the workflow editor, click the lightning icon in the secondary side nav. This tab only appears for Chat Driven workflows.

**2. Add a trigger**

Click **+**. The **New Trigger** form appears with the following fields:

**Trigger Name** `string` *required*

A descriptive name for the trigger (e.g., "Order Support", "Product Question").

**User Message** `string` *required*

The message template sent as user input when the trigger fires. Supports `${paramName}` interpolation. Maximum 2000 characters.

**Example:** `The customer needs help with order ${orderId}. Their account type is ${accountType}.`

**Parameters** `array`

Optional list of parameters referenced in the message template. Click **Add Parameter** to add a row. Each parameter has:

* **Params** (required) — the key used in `${paramName}` placeholders. A name starts with a letter, contains only letters and digits, and can use dots as separators (for example, `client.name`).
* **Default Value** (optional) — used when no value is provided at runtime
* **Description** (optional) — explains the parameter's purpose

**3. Save the trigger**

Click **Save Trigger** to persist the trigger. It becomes available for selection on the Start node and in UI Flow integrations.

> [!TIP]
>
> Parameters referenced in the message with `${paramName}` should match the parameter names defined in the params table. If a parameter value is left empty at runtime, the `${paramName}` placeholder is sent as-is — the workflow handles missing context.

### Using triggers on the Start node

The Start node of a chat-driven workflow provides a segmented toggle with **Text** (default), **Voice**, and **Reply Trigger** options:

> [tab] Text mode
>
> The default behavior — a free-text **User Message** field, **Chat Session ID**, and an optional **UI Flow Context** JSON editor.

> [tab] Voice mode
>
> A **Test Audio File** field replaces the **User Message** field. Turn on **Use Test File**, then upload an audio file or pick one of the workflow's test files (MP3, WAV, M4A, AAC, or OGG, up to 5 MB). The test run sends the audio as the user's message. **Chat Session ID** remains visible.

> [tab] Reply Trigger mode
>
> * The **Select Reply Trigger** dropdown lists all triggers defined on the workflow
> * Selecting a trigger shows:
>   * A read-only preview of the message template
>   * A code editor pre-filled with the trigger's parameters and their default values
> * **Chat Session ID** remains visible and required
>
> When no triggers are defined, the node shows a **No Triggers Yet** empty state. Define triggers in the **Reply Triggers** tab first.

### Chat integration

When the workflow is connected to a Chat component via a UI Flow, triggers are sent from the UI to the workflow:

* The available triggers (ID, name, and parameters) are exposed to the UI Flow
* The UI can invoke a trigger by sending the trigger ID along with parameter values
* The resolved message (with all `${paramName}` values substituted) is sent as the workflow's starting input
* The trigger message is **saved to conversation memory** for context continuity
* The trigger message is **not displayed** in the user's chat history

> [!NOTE]
>
> If a trigger is deleted from the workflow while still referenced by a UI Flow page, it is automatically removed from the page — the same behavior as when a REST API endpoint is removed from a system.

### Console and run logs

Workflow runs initiated via an AI Trigger show additional details in the run history:

| Field | Description |
| - | - |
| **User message type** | `text` or `AI trigger` |
| **Trigger** | The trigger name (e.g., "Triggered by: Order Support") |
| **User message** | The fully resolved message with all `${paramName}` values replaced |

The Start node's output tab displays the full resolved input as JSON, including `user_message_type`, `trigger`, and `user_message` fields.

***

## Testing chat-driven workflows

When testing via **Run Workflow**, the test modal provides two modes:

### Text mode

* **Chat Session ID** — A valid UUID that identifies the test conversation session (e.g., `550e8400-e29b-41d4-a716-446655440000`). Required. Used for memory storage and retrieval.
* **User Message** — The test message to send (e.g., "What is my account balance?")
* **UI Flow Context** — Optional JSON object to mock the context a UI Flow would normally supply at runtime (e.g., `{"customerId": "42"}`). Invalid JSON is rejected before the run starts.

### AI Triggers mode

* **Chat Session ID** — Same as above, required
* **Trigger** — Select from the workflow's defined triggers
* **Parameters** — Fill in test values for the trigger's parameters (e.g., `${orderId}` → `ORD-12345`)

Clicking **Run Workflow** with an AI Trigger selected substitutes the parameter values into the message template and sends the resolved message as the workflow's starting input.

> [!TIP]
>
> When testing, use the same Chat Session ID across multiple Run Workflow executions to test multi-turn memory — the system retrieves previous messages from that session.

![Run Workflow test modal with Chat Session ID and User Message fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_test_modal.png)

***

## Setting up a chat-driven workflow

**1. Create a new workflow**

In the Integration Designer, click **+** to create a new workflow. Enter a name and select **Chat Driven** as the workflow type.

![Create workflow modal with Chat Driven selected as the workflow type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/mainChat_chat_driven_create.png)

**2. Review the Start node**

The Start node is created automatically with **Chat Session ID**, **User Message**, and an optional **UI Flow Context** editor pre-configured.

**3. Add AI processing nodes**

Add Custom Agent nodes or [Intent Classification Agent](/5.9/ai-platform/agent-builder/intent-classification) nodes to process user messages.

**4. Enable Chat Reply**

On the Custom Agent node that generates the final response, toggle **Send as Chat Reply** to **ON**.

**5. Enable Memory (optional)**

On nodes that need conversation context, toggle **Use conversation memory** to **ON**.

**6. Add an End Flow node**

Add an End Flow node from the node palette and connect it to the final node in your workflow. The End Flow node has no body configuration in Chat Driven workflows.

**7. Integrate with a UI Flow**

Connect the chat-driven workflow to your UI:

* **Option A (5.7.0+):** Create a **Chat-Driven UI Flow** and set this workflow in the **AI Conversational Workflow** field. All Chat components in the UI Flow will use it automatically.
* **Option B:** In any UI Flow, add a Chat component and select the Chat Driven workflow directly on the component.

![Create UI Flow modal with Chat-Driven selected as the experience type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_chat_based.png)

![Chat-Driven UI Flow hosting a chat-driven workflow in a Chat component](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_ui_flow.png)

***

## Cancelling a running workflow

### Endpoint

```bash theme={"dark"}
POST /api/runtime/wks/{workspaceId}/app/{appId}/workflows/instances/{instanceUuid}/cancel
```

**Path parameters:**

| Parameter | Type | Description |
| - | - | - |
| `workspaceId` | UUID | The workspace identifier |
| `appId` | UUID | The app identifier |
| `instanceUuid` | string | The workflow instance to cancel |

The caller must have access to the target workspace within their organization.

### Cancellation behavior

What happens depends on where the workflow instance is when the cancel request arrives:

* **Before any AI node runs** — The user prompt is persisted on the chat message with `cancelled: true`. No AI call is made. The workflow stops.
* **While an AI node is executing** — The in-flight AI call is stopped, any partial response is discarded, and the user prompt is persisted with `cancelled: true`. The workflow stops.

In both cases, the Chat component receives a `chatCancelled` Server-Sent Event on the `CHAT_WORKFLOW_RESPONSE` channel so the UI can exit its streaming state.

***

## Related resources

> [card] [Chat component](/5.9/ai-platform/chat-component)
>
> Technical reference for runtime behavior, session management, and SDK integration

> [card] [AI node types](/5.9/ai-platform/agent-builder/node-types)
>
> Overview of all available AI workflow node types

> [card] [Chat interface](/5.9/ai-platform/using-agents/chat-interface)
>
> Conceptual overview of adding conversational AI to your apps

> [card] [Knowledge Base](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Connect knowledge bases for context-aware AI responses


# Build and change apps with the Developer Agentic Harness
Source: https://docs.flowx.ai/5.9/ai-platform/developer-agentic-harness

Describe a change in plain language and the FlowX Designer's AI agent surveys your app, plans the change, and builds it on its own branch for your review.

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

![The FlowX Designer with the AI agent rail open on the left, where the agent asks a clarifying question about a customer onboarding request with selectable options, while the Make view is active](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-rail-overview.png)

The FlowX Developer Agentic Harness is an AI agent in the Designer that builds and changes apps from natural-language instructions. You describe the outcome you want, for example "set up customer onboarding: a Customer data type, a CustomerStatus enumeration, and a UI flow with a form that captures the customer details", and the agent surveys your app, drafts a plan, and carries it out on a dedicated branch. You hold every gate: you give the plan the go-ahead, review each operation before it runs, and decide when the branch merges and when a new version is served to users.

<video>
  <track label="English" />
</video>

***

## How it works

**1. Open the agent rail**

Inside your app, select the **AI assist** toggle (the sparkle icon) in the header at the top of the Designer, or press **⌘K** (**Ctrl+K** on Windows and Linux). The agent opens in a chat rail on the left side. The rail header shows where the conversation writes, for example **Writes to** `customer-onboarding` · `main`. Each conversation is a separate thread: open the conversations list to search earlier threads or start a **New conversation** for a new piece of work. You can also open the agent from organization and workspace pages, see [Can I use the agent outside a project?](#can-i-use-the-agent-outside-a-project).

**2. Describe the change**

Write what you want to build or modify in plain language. The agent first surveys the app so it works with your real resources and names rather than guesses. While it works, the page is locked and shows its progress. Select **Cancel** at any point to ask the agent to stop: once the stop is confirmed, the conversation says *Stopped. Nothing was saved.* If the run can't be stopped, it keeps going and the conversation shows it as still running.&#x20;

**3. Answer its questions**

When a material decision is open, the agent asks instead of guessing. Questions come with selectable options, including a recommended one, and you can always answer in free text.

**4. Give the go-ahead**

The agent presents a one-pager: why the change, what changes, and the decisions it settled on. Select **Go ahead** to have the agent prepare the work items, or describe a change in the conversation instead. Nothing is written to your app at this point. Your go-ahead also lets the agent make small adjustments that stay within what you approved, see [Changes to a plan during a run](#changes-to-a-plan-during-a-run). If the agent still sees open questions, the button reads **Go ahead anyway**.

**5. Choose where it runs**

The prepared plan lists its work items with their constraints and the resources each one touches. Select **Implement this plan**, and the agent asks in the conversation where the implementation goes: keep implementing on the current branch, or **Make a new branch for this plan**. On a branch other than main, keeping it is the recommended option. On main, a new branch is the only option, because implementation never writes to the main branch itself. Either way, the review that follows shows any saved changes on the current branch, and nothing is built until you confirm committing them there.&#x20;

**6. Review before running**

The agent can only read saved changes, so save or discard your open editor changes first, then, for a plan without stories, select the checkbox **I have saved or discarded my unsaved editor changes** (SaaS · 6.0). The review pane lists the reviewed work items with the full content of every operation. Select **Start implementation** to run the plan, or **Run next item, then pause** to run one item at a time. When saved changes need committing first, the buttons read **Commit changes and start implementation** and **Commit changes and run next item, then pause**. To send the work to a different branch, select **Not now** and select **Implement this plan** again.

**7. Review the result**

The agent carries out the plan on its own branch, verifies each item, and commits it there. The plan panel tracks progress, for example **3 of 6 implemented**, and the conversation reports each step as it completes. When the run is done, review the committed version and its changed resources on that branch. **Open the branch** takes the Designer to the latest version of the branch the plan wrote to, from wherever you are, for example after the agent made a new branch or after you moved to another branch. When the built version has a web entry point, a process or a UI flow, the conversation also offers **Test run** (SaaS · 6.0): it opens that entry point on the built version so you can try the change before you merge. Test run needs permission to read process instances for a process, or UI flows for a UI flow. Merge the branch when you are satisfied. Your users are untouched throughout: the app keeps serving the served build until you serve a new version.&#x20;

<video>
  <track label="English" />
</video>

![Page-lock modal reading "The agent is working" with a progress indicator and a Cancel button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-agent-working.png)

![One-pager draft for the customer onboarding change in the plan panel, with the Go ahead button in the agent rail](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-plan-go-ahead-v2.png)

![Agent rail asking where the implementation should go, with Make a new branch for this plan marked Recommended because the conversation is on main, next to the Ready to implement card and its Implement this plan button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-branch-choice.png)

![Review before running card listing three reviewed work items, with the saved-changes checkbox and the Start implementation, Run next item then pause, and Not now buttons](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-review-work-items.png)

***

## Make and Plan views

The **Make** | **Plan** toggle appears next to the **AI assist** toggle while AI assist is on. It switches the main area between your app content and the agent's plan panel. While the agent is working, **Plan** shows a lock icon.

* **Make** shows the app itself: your processes, UI flows, templates, and the rest of the Designer, including any changes the agent has made.
* **Plan** shows the current plan: the one-pager for your go-ahead, then the work items with their constraints, what each one touches, and how many are implemented. Plan unlocks once the agent has drafted a plan in the current session.

![Close-up of the Make and Plan toggle in the Designer header](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-make-plan-toggle.png)

***

## What the agent can see and change

The agent works only with **design-time resources**, the things you author in the Designer. It can survey every resource type in your app, including processes, UI flows and views, workflows, systems, project data types, reusable functions and UI templates, enumerations, themes, media files, and document and notification templates.

Changes it can make include:

* Creating and editing **processes**: adding and renaming nodes, wiring sequences and gateway conditions, attaching business rules, notification steps, and workflow calls.
* Creating **UI flows** and binding components to your data model.
* Creating and editing **project data types** and their attributes.
* Creating **workflows**, including conversational workflows that back chat-based UI flows.

> [!NOTE]
>
> The agent never touches runtime data. Process instances, UI flow sessions, and other runtime records are refused by design: they are your users' in-flight journeys, not app definitions.

***

## Safety and review

* **Never on your main branch.** Implementation runs on a dedicated branch the agent creates for the plan, or on another branch you choose. Implementation on the main branch is not allowed, and the agent merges a branch only when you ask and confirm the merge. See [Merging a branch](#merging-a-branch).
* **You approve before anything runs.** The agent executes a plan only after you give its one-pager the go-ahead, choose where it runs, review the exact operations it will perform, and select **Start implementation**.
* **You approve changes to a running plan.** Changes beyond what you approved wait for your review, and work items that already ran stay as they are.
* **Verified before committed.** The agent validates its change and commits it on its own branch, where you review the version and its changed resources like any teammate's work.
* **Runtime stays untouched.** The app's launch link and its users keep the served build until you serve a new version. Runtime data, such as process instances and UI flow sessions, is refused by design.
* **Guarded destructive operations.** Deleting a process, for example, is refused while the process has running instances, is referenced by a subprocess or navigation, has start timers or triggers, or is still in use. The agent does not clean these up to force a delete through.
* **Cancel at any time.** A confirmed stop ends the run cleanly, and the session can be resumed later. A run that can't be stopped keeps going, and the conversation shows its progress.
* **Exact wording is preserved.** Names, conditions, and scripts you give the agent are used verbatim. If something needed is missing, the agent asks instead of inventing it.

![All Branches graph with the agent's branch selected, showing its committed version, the customerOnboarding UI flow among the changed resources, and the Merge Branch button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-branch-review.png)

![UI Flow editor on the agent's branch showing the Customer onboarding form the agent built, with First Name, Last Name, and Email fields and Cancel and Save buttons](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-result-form.png)

### Merging a branch

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When you ask the agent to merge its branch, it plans the merge as a separate step after the work it merges has run. By default it merges into the branch it was cut from; name another branch to merge there instead.

* **You confirm the merge itself.** The merge's review states what it changes: the destination branch changes for everyone, is locked while the merge runs, and the merge can't be undone once it completes. The agent merges only after you confirm that review. Approving the plan doesn't count as confirming the merge.
* **Conflicts are your call.** When the branches conflict, the agent asks you about each conflict, one at a time, with a recommended answer. Pick a side, or cancel to discard the merge.
* **Conflicted merges are checked first.** The agent makes a conflicted merge on a separate check branch, validates the result, and runs each process, workflow, and UI flow the conflicts touched. The destination changes only if the result adds no new errors. The check branch stays in the branch graph.
* **Other makers' work is safe.** When someone else has work in progress on the destination, the agent refuses the merge instead of discarding their work.

***

## Changes to a plan during a run

Plans can change after you approve them, either because you ask for a change or because the agent finds that the remaining work needs to differ.

* **Within what you approved:** the agent adjusts the plan and tells you in the conversation, for example "The agent adjusted the plan within what you approved — now v2."
* **Beyond what you approved:** the run pauses and the rail shows **A change to the remaining items is waiting for your review**. Select **Review the change** to open it in the plan panel.
* **A change to what the plan is for:** the review warns that approving it gives the description the go-ahead again.
* **A change you ask for while the plan runs:** it is queued, the run pauses after the current item, and you review the change there.

The review card, **A change to the plan**, shows the version change (for example `v1 → v2`) and every remaining item. Items already run stay as they are, and the rest run as shown. Select **Approve the change** to continue the run with the new version, or **Not now** to keep the plan as it was.

![A change to the plan card in the plan panel, marked v1 to v2, stating that items already run stay as they are and listing a completed item](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/builder-plan-change.png)

***

## Entry points, handovers, timeouts, and repairs

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

* **Entry point and serve are separate confirmations.** A plan sets or replaces an entry point only when you asked for it in the plan's description. When a plan ends on a version with no web entry point, the agent suggests one, the resource that opens the most of what the plan changed, as its own step. Serving the new version is a second confirmation, so you can stop with the work built but not served.
* **Handover buttons.** The agent can add a button to a user task that starts another process with prefilled data, either in this app or in another app's active build.
* **Waits for a workflow reply time out.** When the agent builds a screen that waits for a workflow's reply, it adds a timeout and an error route so a lost or failed reply doesn't strand the user. The wait defaults to 15 minutes, and the route goes back to the nearest user task with nothing written, unless you name another step. The preview states both defaults. A step that already has a timer or error event keeps it as it is.
* **Configuration errors are reported.** A work item that changes a process reports the new configuration errors it leaves, then completes.
* **Failed runs are repaired within budget.** When a step fails at run time, the agent reads that run and proposes a repair. Repairs of a step count across plan versions, so a repair you confirm after a plan change still spends the step's budget.
* **A platform that doesn't answer pauses the run.** When the platform doesn't answer a step, even after the agent waits and tries again, the run pauses instead of failing, and the conversation names the step that had to wait. Select **Resume remaining items** to try again: the agent first checks whether that step already went through, so nothing is applied twice.&#x20;
* **Small edits skip the one-pager.** When you ask for one exact change, such as renaming a resource, the agent drafts it, checks it against your app, and applies it straight away, then tells you in the conversation what changed. It stops for you to select **Start implementation** first only when the change can't be undone, when it affects other resources or another app that use what you're changing, or when the agent can't check what uses it.  When the name you gave matches more than one resource, the agent first asks which one you mean. A larger change, or one the agent can't check up front, goes through the one-pager and the plan as usual.&#x20;

***

## How does a plan with stories run?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Some plans split the work into stories, each a slice of the app you can try on its own. A plan with stories is implemented one story at a time, so you can check each slice before the next one starts.

* **Open a story** to see where it sits in the plan (for example **Story 2 of 5**), **How to test this story**, **What I need from you**, what was decided, **What this story touches** (a forecast that may change when the story starts), and the stories it depends on.
* **Implement the next story.** Only the next story in line offers **Implement**. Select **Implement this story**, review its operations, and run it. When saved changes need committing first, the button reads **Commit changes and implement this story**.
* **Follow the progress.** The plan counts implemented stories, and each implemented story shows the commit it landed as. The conversation reports each story as it's built, implemented, waiting for you, or stopped.
* **Run the rest.** Once a run exists, **Implement the remaining stories** runs every story still open. When a story needs an answer from you, answer it to continue. After a reload, choose how far to continue: **This story only** or **The remaining stories**.

***

## How do I comment on the running app?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Point at what you want changed instead of describing where it is. While the agent's panel is open on a running UI flow or process, select **Comment** in the header, beside **Config** and **Runtime**.

**1. Pick a component**

Select a component in the running app. Use the breadcrumb to pick the level you mean, for example the whole card rather than one field inside it.

**2. Say what should change**

The comment box quotes the component. Type what should change and select **Send**, or press Enter. Shift+Enter adds a new line.

**3. Continue in the conversation**

The comment goes to the agent with the component attached as context. It joins the open conversation when that conversation writes to the run's branch or has no target yet. Otherwise it starts a new conversation, and a run on the main branch always starts a new one.

Comment mode works only on a run started from the latest version of its branch: the work in progress or its latest commit. On any other version the button is unavailable and its tooltip reads **Comments are available on the latest version of** the branch. Select **Comment** again, **Leave comment mode**, to turn it off.

If you pick another component while a comment is unsent, the Designer asks **Discard this comment?**. If the component leaves the screen, the box says **This component is no longer on screen**.

***

## What happens when the agent asks to read another project?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The agent reads and writes inside the conversation's write target. When answering needs more, for example another project in the workspace, it asks first with a **Read from** card that names what it would read and why. The access is read-only: nothing there is ever written.

* Select **Allow for this conversation** to let it read. The access lasts for this conversation until it goes idle.
* Select **No**, and the agent answers from the write target alone.

To see or remove access you granted, open the **reads** link on the conversation's rail and select **Revoke**. Revoking drops what was read from the conversation right away.

***

## Can I use the agent outside a project?

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Yes. The **AI assist** toggle also appears on organization and workspace pages, so you can start a conversation before you open a project. Each page level has its own permission, and one level never stands in for another:

| Where you open the agent | Permission | Default roles that have it |
| - | - | - |
| Organization pages | `org_aiagent_edit` | Organization admin, Organization owner |
| Workspace pages | `wks_aiagent_edit` | Workspace admin, Workspace user |
| Inside a project | `aiagent_edit` | See the [roles and permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) |

A conversation outside a project can read projects but not change them:

* **Ask about a project by name.** The agent checks that you can read the project, then reads it as you, read-only, at its last commit on the main branch. If the name matches no project you can read, the agent says so and offers projects you can read instead.
* **To change a project,** open the project and work from there.
* **Attaching files** needs a project, so it isn't available outside one.

***

## Sessions

A conversation belongs to you (SaaS · 6.0) and stays open as you move around the Designer. It writes to one project and branch, set by the first change you confirm, and the rail shows that target after **Writes to**. Opening other pages adds context but never moves the target: on another project, the rail notes that the conversation still writes to the first one. A paused run waits at a verified item boundary: select **Resume remaining items** to continue, or **Run next item, then pause** to step through the rest. When a failed step stops the run, the plan keeps its run card and the rail tags it **run failed**.  When every item is implemented, **Finish the run** closes the run and lists what could not be proven. When the work is no longer wanted, select **Abandon the plan**: it closes the plan and keeps its history, and you start a new conversation for another change. After a run completes, describe the next change in the same conversation and the agent plans it there. The conversations list shows every conversation you have in the organization. Use **Search conversations** to find one, or filter by **All**, **This project** (on a project page), or **With plan** (SaaS · 6.0).

Each conversation keeps its own plan. Start a second conversation on the same branch to run a second plan against the same work, then switch back to the first one and find its plan and its history intact.

<video>
  <track label="English" />
</video>

### Delete a conversation

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

In the conversations list, open the row's **⋮** menu and select **Delete**. The **Delete conversation** window says what is kept and what is lost:

* **Commits stay.** Changes the agent committed, and the audit of who changed what, stay on their branch. The reasoning and anything planned but not run are lost. Select **Export plan** to download a plan as JSON before you delete.
* **Nothing committed:** deleting removes the conversation and everything planned in it.
* **Attached files** are listed, and they're deleted with the conversation.

You can't delete a conversation while the agent is still answering in it or a plan is running. Wait for it to finish, or pause the plan.

***

## Attach files to a conversation

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Give the agent your own material to work from, such as a requirements brief, a screenshot of an existing form, or a BPMN diagram. Select the paperclip (**Attach files**) in the composer, or drop files on it, then send them with your message. A message can also be only files: the agent summarizes what they contain and suggests next steps, without changing your app until you ask.

| File type | Maximum size |
| - | - |
| PDF | 15 MB |
| DOCX | 15 MB |
| PNG, JPEG, WebP | 5 MB |
| BPMN (`.bpmn`) | 2 MB |

You can attach up to 5 files to one message and up to 20 to one conversation. The **Attach files** button is hidden while you answer a question the agent asked you.

### What happens when you attach a file

* **Before upload:** files that break a rule are listed in a **This file wasn't attached** notice above the composer, with the reason for each. Reasons include an unsupported file type, an empty file, a file over the size limit for its type, a file already attached to the message or the conversation, a message over 5 files, a conversation over 20 files, and a file that can't be read. The other files still attach.
* **While uploading:** each file shows as a chip with its upload progress, then its size. **Send** waits until every upload finishes. If an upload fails because of a network or server error, select **Retry**, or remove the file: **Send** stays unavailable while a failed file is attached.
* **After sending:** the agent reads each file and indexes it so it can search the content while it plans and builds. A file shows **Processing…** until it's ready. A file the agent can't use shows **Not searchable** or **Indexing failed**, and the rest of the message still goes through.

### Manage a conversation's files

When a conversation has files, the conversation header shows a paperclip with the file count. Select it to open **Files in this conversation**. It lists every file sent in the conversation with its type, size, and when it was sent, and shows why a file couldn't be read.

* Select a file name to open it. PDF and BPMN files open in a new tab, images open in a preview, and DOCX files download.
* Select **Retry** on a file that failed indexing to index it again.
* Select **Remove from the conversation** to take a file out. The file is removed right away, without a confirmation step, and its row reads **Removed from the conversation**.

Files live with the conversation. When you delete a conversation, the confirmation lists its attached files, and they're deleted with it.

***

## Related resources

The Developer Agentic Harness builds and changes your app for you in the Designer. To create AI agents that run inside your apps and serve your users, use [Agent Builder](./agent-builder/overview) instead.

> [card] [AI in FlowX](./ai-in-flowx)
>
> Overview of config-time and business agents

> [card] [Agent Builder](./agent-builder/overview)
>
> Build business agents that run inside your apps

> [card] [Versioning](../docs/projects/managing-applications/versioning)
>
> Branches, commits, merging, and builds

> [card] [Pre-built agents](./pre-built-agents/overview)
>
> Config-time agents embedded in the Designer


# Evaluations
Source: https://docs.flowx.ai/5.9/ai-platform/evaluations

Score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Catalogue, datasets, experiments, and the evals-judge service.

> [!NOTE]
>
> Attach test cases to AI nodes in a workflow, pick from a catalogue of evaluators (correctness, hallucination, RAG groundedness, JSON match, and more), launch an experiment, and read per-evaluator aggregate scores plus per-test-case details. Powered by the async `evals-judge` service.

## Overview

An *evaluation* (eval) scores the output of an AI node against a known expected outcome. Use evals to:

* **Tune prompts and retrieval** — change a system prompt or KB chunk size, rerun the same experiment, and see whether your scores improved.
* **Regression-guard agents** — before promoting a new agent version, run the dataset of "hard" past inputs and compare scores against the previous version.
* **Pick a model** — run the same dataset against two different LLMs and compare correctness, conciseness, and cost.

Evals are workflow-centric. Each dataset is attached to a specific AI node in a specific workflow; experiments launch that workflow against the dataset and score the node's outputs.

***

## Core concepts

| Concept | What it is |
| - | - |
| **Dataset** | A named collection of test cases attached to a specific AI node in a workflow. Holds the node configuration snapshot at the time the dataset was last updated. |
| **Test case** | One row of input data plus an expected output. May include retrieved context. Sourced either **manually** or captured from a real **node execution** in a workflow run. |
| **Evaluator (scorer)** | A rule that scores a model output against the expected output. The built-in ones cover general quality, RAG quality and deterministic matching. You can also write your own. |
| **Experiment** | A run of the workflow against every test case in one or more datasets, scored by one or more evaluators. Produces aggregate scores per evaluator plus per-test-case details. |
| **Score** | Numeric (typically 0.0–1.0) or binary, depending on the evaluator. Numeric scorers have a default pass/fail threshold. |

***

## Get started

**1. Add an AI node to a workflow**

Drop a Custom Agent, Intent Classification Agent, Extract Data, or any other AI node into a workflow and configure it as usual.

**2. Create a dataset on the node**

From the node's side panel, open **Evaluations → Datasets** and click **New dataset**. Name it after what it tests (e.g. *Customer-intent-classification-baseline*).

**3. Add test cases**

Add at least one test case manually, or capture one from an existing process instance run (see [Add test cases](#add-test-cases)).

**4. Pick evaluators**

Open **Evaluations → Experiments → New experiment**. Choose one or more datasets and pick the evaluators you want to score against from the catalogue.

**5. Launch the experiment**

Click **Start**. The workflow runs against every test case; the `evals-judge` service scores each (test case × evaluator) pair asynchronously.

**6. Read the results**

Once the experiment moves to `PASSED` or `FAILED`, open the report for aggregate scores per evaluator and a list of test-case rows you can drill into.

***

## Create a dataset

A dataset belongs to a single AI node on a single workflow. Two datasets on the same node must have unique names.

Fields:

| Field | Description |
| - | - |
| **Name** | Human-readable label, unique per node. |
| **Description** | Optional. Useful for explaining "what is this dataset testing?" |
| **Multimodal** | Toggle on if test cases include image or file inputs as well as text. |
| **Output shape contract** | Optional JSON schema describing the expected output shape. Used by the JSON Match evaluator. |

The dataset persists a *schema snapshot* of the node's input/output at the time of last edit. This is what's used when a workflow is changed underneath an existing dataset — the experiment runs against the snapshot, not the live node, so older runs remain reproducible.

***

## Add test cases

A test case has three core fields:

* **Input** — the data the AI node receives.
* **Expected output** — what a correct response looks like. Required by exact-match and JSON-match evaluators; optional but recommended for LLM-as-judge.
* **Context** — optional retrieved context (KB chunks, retrieval results) used to score RAG evaluators.

Two ways to add them:

> [tab] Manual
>
> From the dataset's **Test cases** tab, click **Add test case**. Fill in **Input**, **Expected output**, and optional **Context**. Save.
>
> Use this for synthetic or hand-crafted cases — typical edge cases, known-difficult inputs, or cases borrowed from a spec or QA tracker.

> [tab] From a node execution
>
> Open a real process instance in the runtime, find the AI node execution you want to capture, and choose **Add to dataset**. FlowX serialises the node's input, captured output, and any retrieved context into a new test case on the chosen dataset.
>
> Use this to harvest "interesting" production cases (high-uncertainty completions, ones flagged by an operator) into a regression set.
>
> Captured cases are marked with `source: NODE_EXECUTION` and carry a back-reference to the originating execution.

***

## Launch an experiment

An experiment binds together:

* One or more datasets (all must be on the same AI node)
* One or more evaluators
* A node configuration snapshot (frozen at launch time)

When you click **Start**, the workflow runs end-to-end against every test case. Each output produces one judge job per (test case × evaluator), published to the `evals-judge.job.request` Kafka topic. `evals-judge` resolves the configured judge LLM, runs the scoring prompt, and returns a score + reasoning on `evals-judge.job.response`.

Experiment status moves through:

| Status | Meaning |
| - | - |
| `STARTED` | Experiment accepted, workflows are being scheduled. |
| `RUNNING` | At least one (test case × evaluator) pair is still scoring. |
| `PASSED` | All scoring jobs completed; overall score is above the pass threshold for the experiment. |
| `FAILED` | All scoring jobs completed; overall score is below threshold (or a non-trivial number of jobs hit the DLQ). |
| `CANCELLED` | Cancelled by a user before completion. |

The Designer streams progress updates as scoring jobs complete, so the report fills in live without a full reload.

### Multiple datasets

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

An experiment can run against **multiple datasets at once** (datasets sharing the same AI node). Overall metrics are aggregated across all of them, and the report adds a **dataset column** so you can see how each case scored per dataset.

***

## View results

Each experiment produces a **report** with two views:

### Aggregate scores

A row per evaluator with the mean (or pass-rate) across all test cases. Useful for "is this prompt better than the last one?" comparisons.

### Per-test-case details

A row per test case showing:

* The input, the model's actual output, and the expected output side-by-side.
* One score column per evaluator selected for the experiment.
* For LLM-as-judge evaluators, the judge's reasoning text (the model's own explanation of the score).
* Pass/fail badges against each evaluator's threshold.

Click into a row to see the full prompt, response, and any retrieved context — this is the screen you use to debug "why is this case failing?"

### Improvement suggestions

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

Experiment reports show **AI-generated suggestions** for improving the node's prompt, grouped per LLM-as-judge evaluator, beneath the score cards — turning a low score into a concrete next edit.

***

## Regression testing between agent versions

Every experiment freezes the node configuration at launch time, so two experiments on the same dataset give you a before/after comparison of an agent change: a new prompt, a different model, or tuned retrieval.

**1. Establish the baseline**

Run an experiment against your regression dataset before changing the agent. The report records the node configuration snapshot and the judge model used.

**2. Change the agent**

Edit the prompt, swap the model, or adjust retrieval on the AI node.

**3. Re-run the same experiment**

Launch a new experiment with the same datasets and the same evaluators. The new run freezes the changed node configuration.

**4. Compare the reports**

Open both reports from the **Experiments** list and compare the aggregate scores per evaluator. A drop on any evaluator is a regression; drill into the per-test-case rows to see which inputs got worse.

> [!TIP]
>
> Grow the regression dataset from production: capture flagged or high-uncertainty node executions with **Add to dataset** (see [Add test cases](#add-test-cases)). Keep the org's judge model unchanged between the two runs so the scores stay comparable.

If the change alters the node's input/output contract significantly, the existing dataset keeps its old schema snapshot and may no longer reflect the node's behaviour — create a new dataset instead (see [Limitations](#limitations)).

***

## Evaluator catalogue

The catalogue includes **10 built-in evaluators** in three categories, and a fourth category holds any you write yourself. The built-in evaluators cannot be edited or deleted.

### General quality

A judge LLM reads the model output (and optional expected output) and scores it on a single rubric. Score is numeric 0.0–1.0. In the Designer these appear under the **General Quality** group.

| Evaluator | What it scores | Needs expected output? |
| - | - | - |
| **Correctness** | How closely the output matches the expected meaning. | Yes |
| **Conciseness** | Whether the output is appropriately brief — penalises padding and rambling. | No |
| **Hallucination** | Whether the output contains claims not grounded in the input or provided context. | No |
| **Answer relevance** | Whether the output actually answers what the input asked. | No |

### RAG

Evaluators for RAG workflows, covering both the retrieval and the answer. Score is numeric 0.0–1.0.

| Evaluator | What it scores |
| - | - |
| **Groundedness** | Is every claim in the output traceable to the provided context, rather than the model's prior knowledge? |
| **Helpfulness** | Holistically, how useful is the answer to the end user, considering tone, completeness, and actionability? |
| **Retrieval relevance** | How relevant are the retrieved documents to the user's question? A quality check for the retrieval pipeline. |

### Code / deterministic

Deterministic, no LLM call. Useful for structured outputs.

| Evaluator | What it scores | Score type |
| - | - | - |
| **Exact match** | Output equals expected, character-for-character. | Binary |
| **Levenshtein** | Edit-distance similarity between output and expected (normalised). | Numeric |
| **JSON match** | Output is valid JSON and conforms to the dataset's output-shape contract. | Binary |

### Custom

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Write your own evaluator when none of the built-in rubrics measures what you actually care about. A custom evaluator is scored by the judge LLM following instructions you supply, and appears under the **Custom** group in the Designer, after the built-in ones.

Custom evaluators belong to **one workflow**. You create and manage them in the workflow you are working in, the same way datasets bind to a single workflow.

| Field | Required | What it does |
| - | - | - |
| **Start from a template** | No | Prefills the form from an existing evaluator, instructions included, so you can adapt a built-in rubric instead of starting from a blank prompt. |
| **Name** | Yes | Identifies the evaluator in the catalogue and in experiment reports. |
| **Description** | No | Records what the evaluator measures, for whoever reads the catalogue next. |
| **Instructions** | Yes | The scoring prompt the judge LLM follows. |
| **Scoring** | Yes | **Numeric** for a score in `[0.0, 1.0]`, or **Binary** for pass or fail. Numeric is the default. |
| **Pass threshold** | Only when scoring is **Numeric** | The score a row must reach to count as passing. Must be between `0` and `1`. |

> [!NOTE]
>
> **Binary scoring has no threshold.** Switch **Scoring** to **Binary** and the **Pass threshold** field is turned off, since pass or fail is already the result.

Unlike the built-in evaluators, the ones you create can be edited and deleted.

### Score types and thresholds

* **Numeric evaluators** return a score in `[0.0, 1.0]` and ship with a `defaultThreshold` (e.g. `0.7`). The report flags a row as failing if the score is below the threshold.
* **Binary evaluators** return pass or fail. No threshold.

***

## Judge model resolution

LLM-as-judge and RAG evaluators need a judge LLM to run their scoring prompts. The model is resolved **per organization** via a new LLM capability:

* The **`EVAL`** capability is part of the org-manager LLM catalogue (display order 7, alongside the existing capabilities).
* The platform-default judge model is **`gpt-5.4-mini`**, backfilled onto every org's catalogue on upgrade.
* An admin can change the judge model per org by assigning `EVAL` to a different model in **Settings → AI Providers → Models**.

This means the same experiment can produce slightly different scores in two different orgs if they've picked different judge models — the report records which model was used, so the comparison stays apples-to-apples within one org.

> [!NOTE]
>
> The judge LLM is *not* the same as the LLM your agent uses. The agent under test can use any provider; the judge runs separately and can be a cheaper, faster model dedicated to scoring.

***

## Permissions

Evals reuse existing workflow-level permissions — there is no new role.

| Capability | Permission |
| - | - |
| List, view datasets, experiments, reports | `WORKFLOW_READ` |
| Create / update / delete datasets, add / remove test cases, launch / cancel / delete experiments | `WORKFLOW_EDIT` |

Permissions are enforced per workflow resource ID — a user with `WORKFLOW_EDIT` on Workflow A but not Workflow B cannot launch an experiment against B's nodes.

***

## How it works

The runtime side has three pieces:

* **`integration-designer`** owns the dataset, test-case, and experiment REST APIs and the experiment orchestration. It publishes judge job requests to Kafka and writes results to MongoDB.
* **`evals-judge`** is a small Python service that consumes judge job requests, resolves the judge LLM via `organization-manager`, calls the LLM provider, and publishes scored responses.
* **`organization-manager`** owns the LLM catalogue and resolves the model bound to the `EVAL` capability for the org.

Scoring is fully async. A judge job's lifecycle:

1. `integration-designer` publishes a request on `ai.flowx.ai-platform.evals-judge.job.request.v1` with the test case, the evaluator id, and the node-config snapshot.
2. `evals-judge` consumes the request, resolves the judge model, runs the scoring prompt, and publishes the result on `ai.flowx.ai-platform.evals-judge.job.response.v1`.
3. `integration-designer` consumes the response, persists the score on the test-case row, and pushes a progress event over SSE to any open Designer report.
4. Permanent failures (no judge model resolvable, invalid request shape, repeated timeouts) end up on `ai.flowx.ai-platform.evals-judge.job.dlq.v1` for manual operator review — the report shows the test-case row as `ERROR`.

***

## REST API surface

The Designer is the primary entry point, but the same endpoints are usable from your own tooling. All are scoped to a workspace and require `WORKFLOW_READ` / `WORKFLOW_EDIT` on the relevant workflow.

| Method | Endpoint | Purpose |
| - | - | - |
| POST | `/api/workflows/datasets` | Create a dataset on a node |
| GET | `/api/workflows/datasets?nodeFlowxUuid={uuid}` | List datasets, optionally filtered to one node |
| GET / PUT / DELETE | `/api/workflows/datasets/{datasetUuid}` | Fetch, update name/description, or delete a dataset |
| POST | `/api/workflows/datasets/{datasetUuid}/test-cases` | Add a test case (manual) |
| POST | `/api/workflows/experiments/start` | Launch an experiment |
| GET | `/api/workflows/experiments` | List experiments (paginated) |
| GET | `/api/workflows/experiments/{experimentUuid}` | Experiment report with aggregate scores |
| GET | `/api/workflows/experiments/{experimentUuid}/test-cases/{testCaseUuid}` | One test-case row with all scores |
| POST | `/api/workflows/experiments/{experimentUuid}/cancel` | Cancel a running experiment |
| DELETE | `/api/workflows/experiments/{experimentUuid}` | Delete a completed or cancelled experiment |

***

## Operator setup

Evals add a new service and three new Kafka topics to the AI Platform deployment.

### evals-judge service

* **Language:** Python
* **Container image:** `{{flowx-ai}}/evals-judge`
* **Dependencies:** Kafka (request / response / DLQ), `organization-manager` (LLM resolution), the LLM provider configured for the `EVAL` capability, S3-compatible storage (MinIO env vars on multimodal test cases).
* **No exposed ingress.** Communication is Kafka-only.
* **Storage:** none of its own — state lives in `integration-designer`'s MongoDB and the LLM provider.

Add `evals-judge` to your AI Platform install. See [AI Platform setup](/5.9/setup-guides/ai-platform-setup#service-architecture) for the full Python services list.

### Kafka topics

Declare the following in your Kafka provisioning (`kafka-topics.yaml.gotmpl` for k8s, or your own topic management):

| Topic | Partitions | Purpose |
| - | - | - |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | 3 | Judge job requests from `integration-designer` |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | 3 | Scored responses back to `integration-designer` |
| `ai.flowx.ai-platform.evals-judge.job.dlq.v1` | 3 | Dead-letter queue for unscored jobs |
| `ai.flowx.evals.suggestions.job.request.v1` | 3 | Improvement-suggestion requests from `integration-designer` |
| `ai.flowx.evals.suggestions.job.response.v1` | 3 | Improvement suggestions back to `integration-designer` |
| `ai.flowx.evals.suggestions.job.dlq.v1` | 3 | Dead-letter queue for suggestion jobs that could not be completed |

The `integration-designer` consumer group for the judge response topic is `integration-designer-evals-judge-response-group` with 3 consumer threads by default. For the suggestions response topic it is `integration-designer-evals-suggestions-response-group` with 2 consumer threads.

### EVAL capability backfill

The migration `20260513_eval_capability.xml` runs on the first `organization-manager` boot after upgrade and:

* Registers the `EVAL` capability in `llm_capability_catalog` (display order 7).
* Backfills `gpt-5.4-mini` as the model bound to `EVAL` in `llm_model_catalog` (platform default).
* Backfills the same binding into every existing organization's `llm_model` table so evals work out-of-the-box on upgrade without manual configuration.

If your org uses a non-OpenAI provider, change the bound model in **Settings → AI Providers → Models** after the upgrade.

***

## Limitations

* **Workflow-scoped only.** Datasets bind to a single AI node on a single workflow. Cross-workflow shared datasets are out of scope.
* **Judge model is org-wide.** Picking a different judge per evaluator or per experiment is not supported.
* **No retroactive backfill across workflow rewrites.** If you change the AI node's contract significantly, existing datasets keep their snapshot — they don't fail, but they may no longer reflect the current workflow's behaviour. Create a new dataset.
* **DLQ is manual.** There is no automatic retry for jobs landing on the DLQ; an operator must inspect and decide whether to retry.

***

## Related resources

> [card] [AI Platform setup](../setup-guides/ai-platform-setup)
>
> Install evals-judge alongside the rest of the AI Platform.

> [card] [AI providers](./ai-providers)
>
> Configure the LLM bound to the `EVAL` capability for your org.

> [card] [Agent Builder overview](./agent-builder/overview)
>
> Build the AI agents whose outputs you'll score.

> [card] [Chat-driven workflows](./chat-driven-workflows)
>
> Chat-driven workflow nodes you can attach datasets to.


# AI integrations
Source: https://docs.flowx.ai/5.9/ai-platform/integrations

Connect AI agents to external data sources, APIs, and knowledge bases.

AI agents can connect to external systems and data sources to provide context-aware, informed responses. This page provides an overview of available integration options.

## Data source integrations

> [card] [Knowledge bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Connect document repositories for RAG-powered responses

> [card] [MCP integration](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
>
> Use Model Context Protocol to connect external tools and data

## Workflow integrations

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Build complex integration workflows with visual designer

> [card] [Custom Agent Node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
>
> Use AI agents within Integration Designer workflows

## API access

> [card] [REST APIs](/5.9/docs/api/start-process/start-by-process-name)
>
> Programmatic access to processes and agents

> [card] [Kafka integration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#configuring-kafka)
>
> Event-driven integration patterns

## Integration patterns

| Pattern | Description | Use case |
| - | - | - |
| **Knowledge retrieval** | Agent can query knowledge bases as a tool while it answers | Context-aware chat, document Q\&A |
| **External API calls** | Agent calls external services via MCP | Real-time data, third-party services |
| **Workflow orchestration** | Agent triggers or is triggered by workflows | Automated processing pipelines |
| **Event-driven** | Agent responds to Kafka events | Real-time processing, notifications |

## Related resources

> [card] [Agent Builder](./agent-builder/overview)
>
> Create custom AI agents

> [card] [Using agents](./using-agents/overview)
>
> Integration patterns for agents


# Personal Information Guard
Source: https://docs.flowx.ai/5.9/ai-platform/personal-information-guard

Detect and redact personal data (PII) before it reaches a model, on AI workflow nodes or with standalone mask and restore nodes, and restore it afterwards.

## Overview

Personal Information Guard (PII Guard) keeps personal data out of the payloads you send to a model. It works two ways: as a configuration block on every AI workflow node, and as standalone **Mask Personal Data** and **Restore Personal Data** nodes you place in a workflow yourself. When the node-level control is turned on, it detects personal data and replaces it with placeholders before the payload reaches the model, then handles the redacted content throughout the node run. Detection and redaction run in the **data-privacy** AI Platform service; the workflow node calls it synchronously and **fails closed** — if the service errors, the node stops and no redacted artifact is produced.

The node-level control applies to Custom Agent, Intent Classification Agent, Extract Data from File, and all AI Text, Document, Image, and Data Operations nodes.

> [!NOTE]
>
> PII Guard is the privacy control inside AI workflows. It is distinct from process-level [data anonymization](/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes) (`FLOWX_DATA_ANONYMIZATION`), which redacts process data by role.

> [!NOTE]
>
> PII Guard works two ways: as a **node-level** control on an AI node, which redacts a payload before it reaches the model and restores it in the response, and as **separate mask and restore nodes** you place in the workflow yourself. It is distinct from the Knowledge Base **Containing Personal Information** setting, which keeps a Knowledge Base's content on-box by indexing it with a local embedding model. A Knowledge Base does not run PII Guard, and PII Guard does not change how a Knowledge Base is embedded. See [Knowledge Base overview](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).

***

## Configuration

The guard is configured per node in the Designer. Turning it on exposes the detection options below.

The table describes the node-level control. The **Mask Personal Data** node offers the same detection options in its own **Detection settings** panel.

| Field | Description |
| - | - |
| **Enabled** | Turn the guard on for the node. **Default:** OFF. |
| **Detection Algorithm Sensitivity** | One of **Strict**, **Balanced** (default), **Relaxed**, or **Custom**. Maps to a server-side detection threshold. **Custom** exposes a sensitivity slider (`0.00`–`1.00`). |
| **Detection Target** | Choose which payloads are scanned: **Node Input**, **Node Output**, or both. At least one must be selected. **Default:** Node Input. |
| **Personal Info Types** | Opens the **Customize Entities** modal — the picker for which entity types are detected. All are enabled by default. The catalog is served from `GET /integration/api/workflows/personal-information-guard/entities`. |

> [accordion] Supported entity types (24)
>
> **Universal (8)**
>
> `EMAIL`, `PHONE`, `CREDIT_CARD`, `IBAN`, `MAC_ADDRESS`, `CRYPTO_WALLET`, `PERSON`, `ADDRESS`
>
> **Regional — EN (6)**
>
> `SSN`, `US_PASSPORT`, `US_BANK_ACCOUNT`, `US_ITIN`, `UK_NHS`, `EU_VAT_ID`
>
> **Regional — RO (10)**
>
> `CNP`, `CUI`, `RO_IBAN`, `RO_PHONE`, `RO_PASSPORT`, `RO_ID_CARD`, `LICENSE_PLATE`, `HEALTH_CARD`, `POSTAL_CODE`, `LANDLINE`

***

## How it works

* **Input scan** runs before the AI request is built, so placeholder substitution and user-message extraction both see redacted data. Values from earlier nodes that the prompt references are redacted as part of the inputs. The static **Instructions** text written on the node is not scanned, so example personal data in it, such as a sample email in a few-shot example, reaches the model unchanged.
* **Source-file scan** runs for document and image AI nodes. The data-privacy service uploads the redacted artifact back to the same storage as the source, so the file path used for the request is swapped without changing the data source binding.
* **Output scan** runs after the model completes, on a bounded-elastic scheduler so the data-privacy call does not pin the event loop.
* **Restoration (deanonymization)** — for the node-level control, when an input scan ran the guard keeps the placeholder-to-value mapping for the duration of that node's run and automatically restores the original values in the model's response, so downstream nodes and the end user see real data rather than placeholders. When an output scan is also on, PII the model newly introduced is redacted first, so only model-introduced values stay masked. Restoration also holds across chat-driven workflows that carry conversation memory.
* **Irreversible redaction for async file flows** — asynchronous document-parser flows keep permanent placeholders. Their mapping is never persisted, so values redacted in those flows are not restored.
* **System-prompt appender** — for Custom Agent nodes with an input scan, the runner appends a non-editable segment teaching the model to treat indexed placeholders like `<EMAIL_1>` or `<PERSON_2>` as opaque tokens and copy them back verbatim. It runs after the input and chat-history scans so its literal tags are not mistaken for PII.
* **Fail-closed** — any error from the data-privacy service stops execution, including a failed restoration (the node halts rather than let placeholder data reach downstream nodes). The error surfaces on the node run log; redacted artifacts are not produced on failure. This describes the **node-level control**. The standalone Restore Personal Data node behaves differently: see [Masking and restoring across several nodes](#masking-and-restoring-across-several-nodes).

***

## Masking and restoring across several nodes

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The node-level control redacts and restores inside a single AI node. To keep personal data redacted across several steps, use the **Mask Personal Data** and **Restore Personal Data** nodes instead. Both sit under **Tools** in the workflow node palette.

Place **Mask Personal Data** before the steps that must not see real values, and **Restore Personal Data** after them. The masking is reversible later in the same run.

![The Mask Personal Data and Restore Personal Data node panels side by side, with the Input field, detection settings on the Mask node, and the restore outcome banners on the Restore node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/pii-mask-restore-nodes.png)

Each node takes an **Input**, a reference to the text or object it should act on, written as a `${...}` binding such as `${application}`. It is a required field on both nodes.

> [!NOTE]
>
> **Masking does not overwrite your data.** The masked copy is written under the node's response key and the original value is left untouched, so a later step can still read the unmasked source if it is entitled to.

**Mask Personal Data** has its own **Detection settings** panel with two of the node-level control's options: **Detection Algorithm Sensitivity**, including the **Custom Sensitivity** slider, and **Personal Info Types**, opened from a **Customize List** link that shows how many of the entity types are selected. Both work exactly as described in [Configuration](#configuration).

> [!NOTE]
>
> There is no **Detection Target** on the Mask node. The node scans the value you point it at, so the direction is fixed rather than offered as a choice. **Restore Personal Data** has no detection settings at all: it matches the reference the Mask step left behind.

### Restoring is optional

Nothing requires a Restore node. The placeholder map belongs to the workflow run and is deleted when that run finishes, fails, or is cancelled, so leaving data masked for the rest of the run is a supported outcome. A retention limit clears the map for runs that end without reaching one of those points.

### Restore outcomes

**Restore Personal Data** reports one of three outcomes in the run log, along with the placeholders it matched, the ones it did not find, and any it did not recognise.

| Outcome | When | Result |
| - | - | - |
| **Complete** | Every placeholder the run stored was found and put back. | The node succeeds. |
| **Partial** | The input carries placeholder-shaped tokens this run never issued. | The node takes its **failure exit**, and still writes the restored payload. |
| **Failed** | Nothing could be restored: the input did not resolve, the map could not be read, or the input carries none of the stored placeholders. | The node takes its **failure exit** with no restored payload, only the error. |

> [!WARNING]
>
> The Restore node does not halt on failure the way the node-level control does. A partial or failed restore is routed down the node's failure exit so a branch can react to it. Connect that exit if a failed restore has to be handled; if you leave it unconnected, a restore problem stops the workflow the same way any unhandled node failure does.

A placeholder that the run stored but cannot find in the input does **not** make the restore partial. A step in between may legitimately have summarised or dropped the text it sat in, so it is reported and nothing more. Only unrecognised tokens change the outcome.

An input that carries no placeholders at all restores as **Complete**. A record with no personal data in it masks nothing, so an empty map is the normal result rather than a lost one.

The node writes `restored`, `outcome`, and an `integrity` breakdown under its response key, so a branch can read what happened without parsing the run log.

> [!NOTE]
>
> Use the standalone nodes when the redaction has to span more than one node, and the node-level control when a single AI node's payload is all that needs protecting. The two mechanisms share the same detection settings and the same entity catalog.

***

## Run-log and detections

Each enabled scan adds a `personalInformationGuard` block on the node response:

| Field | Description |
| - | - |
| `scanStatus` | `COMPLETED`, `SKIPPED`, or `FAILED`. |
| `totalDetections` | Total number of entities detected across `detections`. |
| `detections` | List of per-entity detection items (see below). Empty when nothing was detected. |
| `errorMessage` | Populated when `scanStatus = FAILED`. |
| `sourceType` | `TEXT`, `DOCUMENT`, or `IMAGE`. Identifies what the scan ran against. Null for text-only scans. |
| `originalStoragePath`, `redactedStoragePath` | Set for `DOCUMENT` and `IMAGE` scans; both point at the data source bound to the node. |

Each item in `detections` carries:

| Field | Description |
| - | - |
| `entityKey` | Entity type detected (for example `EMAIL`, `PHONE`, `IBAN`). |
| `confidence` | Detector confidence score, `0.00`–`1.00`. |
| `originalValue` | The exact substring matched in the source. |
| `replacement` | The placeholder string that replaced `originalValue` before the model call. Input-scan placeholders are indexed, for example `<EMAIL_1>` or `<PERSON_2>`. |
| `direction` | `INPUT` or `OUTPUT` — which scan direction produced this detection. |
| `sourceType` | `TEXT`, `DOCUMENT`, or `IMAGE` — which payload was scanned. |
| `timestamp` | When the detection was made. |
| `regions` | Bounding boxes (`x`, `y`, `width`, `height`) for `DOCUMENT` and `IMAGE` detections. Null for `TEXT`. |

Document and image scans surface the same per-entity detail as text scans, so the run console shows the matched values, replacements, and confidences regardless of which AI node type produced them.

### Request after PII anonymization

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When the input scan is enabled, the workflow run log adds a **Request after PII anonymization** entry right after the detections for that node. It shows the request exactly as the model received it, with placeholders in place of the detected values:

* **Instructions — system prompt**: the system prompt sent to the model.
* **Context and chat message — user prompt**: the context and message sent to the model.

If the scan found nothing to mask, the entry says **The model request is unchanged.** so you can confirm the model saw the original text.

***

## Setup

The data-privacy service connection is configured with `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` — see the [Integration Designer setup guide](/5.9/setup-guides/integration-designer-setup#service-communication).

***

## Related resources

> [card] [Custom Agent node](/5.9/ai-platform/agent-builder/node-types#custom-agent)
>
> Per-node configuration, including the PII Guard toggle

> [card] [Extract Data from File](/5.9/ai-platform/agent-builder/extract-data-from-file#personal-information-guard)
>
> PII Guard on document and image extraction nodes

> [card] [Intent Classification Agent](/5.9/ai-platform/agent-builder/intent-classification#personal-information-guard)
>
> PII Guard on intent classification nodes

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> AI workflow nodes and their configuration


# AI Analyst
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-analyst

Builds and optimizes BPMN processes using AI to generate, validate, and enhance workflows based on user-provided documents

## Overview

The AI Analyst is an intelligent agent that transforms various inputs into Business Process Model and Notation (BPMN) processes. It can generate complete workflows from text prompts, images, or documents, as well as modify existing BPMN processes. The agent uses advanced AI to interpret requirements and convert them into structured JSON representations that the FlowX.AI platform can interpret and visualize as proper BPMN diagrams.

<video />

***

## Key capabilities

The AI Analyst offers two main categories of capabilities:

> [card] Generate from prompt
>
> Creates a complete BPMN process based on natural language descriptions. Transforms textual requirements into a structured workflow and produces a JSON representation containing nodes (with name and type) and links between nodes.

> [card] Generate from image
>
> Extracts BPMN process information from uploaded images, identifies swimlanes and components, and processes various image resolutions. Accepts optional text descriptions for additional context.

> [card] Generate from document
>
> Extracts process descriptions from uploaded documents, analyzes textual content to identify workflow components and relationships, and creates a structured representation of the described process.

> [card] Generate from BPMN file
>
> Imports and interprets existing BPMN files and converts external BPMN formats into FlowX.AI-compatible representations.

> [card] Generate in-between nodes
>
> Adds missing steps between existing nodes in a workflow, enhancing process completeness and logical flow.

> [card] Generate from node
>
> Expands a process by adding subsequent steps after a specified node, allowing incremental development of complex workflows.

> [card] Edit existing process
>
> Modifies components of an existing process based on user instruction, updating node properties, connections, or process structure.

***

## How it works

The AI Analyst architecture integrates multiple AI components to process different input types and generate standardized BPMN output.

The workflow begins with a user query that gets rewritten for clarity. A quality check determines if more information is needed, in which case a human provides additional context. Once sufficient information is available, the process generation component creates the BPMN workflow, which is then delivered to the user.

> [tab] Generate new
>
> ### Generate from prompt
>
> Creates a complete BPMN process based on natural language descriptions. Transforms textual requirements into a structured workflow and produces a JSON representation containing nodes (with name and type) and links between nodes.
>
> ```mermaid theme={"dark"}
> %%{
>   init: {
>     'theme': 'base',
>     'themeVariables': {
>       'primaryColor': '#f1774a',
>       'primaryTextColor': '#000',
>       'primaryBorderColor': '#000',
>       'lineColor': '#6b6b6b',
>       'secondaryColor': '#f3b861',
>       'tertiaryColor': '#bababa'
>     }
>   }
> }%%
> graph TD;
>     Start([Start]):::primary
>     Check_Prompt[Check Prompt]:::secondary
>     Classify_Image[Classify Image]:::tertiary
>     Generate_Process[Generate Process]:::secondary
>     Generate_from_Node[Generate from Node]:::tertiary
>     Generate_between_Nodes[Generate between Nodes]:::tertiary
>     PostProcessing[PostProcessing]:::secondary
>     END([END]):::primary
>
>     subgraph Parallel_Processing [Parallel Processing]
>         Process_Swimlanes[Process Swimlanes]:::tertiary
>         Split_Image[Split Image]:::tertiary
>         Image_Analysis[Image Analysis]:::tertiary
>         Generate_Prompt[Generate Prompt]:::tertiary
>     end
>
>     Start ==> Check_Prompt;
>     Start --> Classify_Image;
>     Classify_Image --> Parallel_Processing;
>     Parallel_Processing --> Generate_Process;
>     Check_Prompt ==> Generate_Process;
>     Check_Prompt --> Generate_from_Node;
>     Check_Prompt --> Generate_between_Nodes;
>     Generate_Process ==> PostProcessing;
>     Generate_from_Node --> PostProcessing;
>     Generate_between_Nodes --> PostProcessing;
>     PostProcessing ==> END;
>
>     %% Styling
>     classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
>     classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
>     classDef tertiary fill:#bababa,stroke:#000,stroke-width:1px,color:#000;
> ```
>
> ### Generate from image
>
> Extracts BPMN process information from uploaded images, identifies swimlanes and components in diagram images, and can process various image resolutions (from small \< 4K to large > 8K). Accepts optional text descriptions for additional context and combines visual recognition with language processing for accurate interpretation.
>
> ```mermaid theme={"dark"}
> %%{
>   init: {
>     'theme': 'base',
>     'themeVariables': {
>       'primaryColor': '#f1774a',
>       'primaryTextColor': '#000',
>       'primaryBorderColor': '#000',
>       'lineColor': '#6b6b6b',
>       'secondaryColor': '#f3b861',
>       'tertiaryColor': '#bababa'
>     }
>   }
> }%%
> graph TD;
>     Start([Start]):::primary
>     Classify_Image[Classify Image]:::secondary
>     Check_Prompt[Check Prompt]:::tertiary
>     Generate_Process[Generate Process]:::secondary
>     Generate_from_Node[Generate from Node]:::tertiary
>     Generate_between_Nodes[Generate between Nodes]:::tertiary
>     Post_Processing[Post Processing]:::secondary
>     END([END]):::primary
>
>     subgraph Parallel_Processing [Parallel Processing]
>         Process_Swimlanes[Process Swimlanes]:::secondary
>         Split_Image[Split Image]:::secondary
>         Image_Analysis[Image Analysis]:::secondary
>         Generate_Prompt[Generate Prompt]:::secondary
>     end
>
>     Start ==> Classify_Image;
>     Start --> Check_Prompt;
>     Classify_Image ==> Parallel_Processing;
>     Parallel_Processing ==> Generate_Process;
>     Check_Prompt --> Generate_Process;
>     Check_Prompt --> Generate_from_Node;
>     Check_Prompt --> Generate_between_Nodes;
>     Generate_Process ==> Post_Processing;
>     Generate_from_Node --> Post_Processing;
>     Generate_between_Nodes --> Post_Processing;
>     Post_Processing ==> END;
>
>     %% Styling
>     classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
>     classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
>     classDef tertiary fill:#bababa,stroke:#000,stroke-width:1px,color:#000;
>     classDef secondary-highlight fill:#f3b861,stroke:#8a2be2,stroke-width:2px,color:#000;
> ```
>
> ### Generate from document
>
> Extracts process descriptions from uploaded documents, analyzes textual content to identify workflow components and relationships, and creates a structured representation of the described process.
>
> ![AI Analyst Diagram - Light Mode](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/AI%20Analyst.svg)

> [tab] Edit existing
>
> ### Generate process from BPMN file
>
> Imports and interprets existing BPMN files and converts external BPMN formats into FlowX.AI-compatible representations.
>
> ### Generate in-between nodes
>
> Adds missing steps between existing nodes in a workflow, enhancing process completeness and logical flow.
>
> ![AI Analyst Diagram - Light Mode](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/AI%20Analyst-existing.svg)
>
> ### Generate from node
>
> Expands a process by adding subsequent steps after a specified node, allowing incremental development of complex workflows.
>
> ![AI Analyst Diagram - Light Mode](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/AI%20Analyst-from-node.svg)
>
> ### Edit existing process
>
> Modifies components of an existing process based on user instruction, updating node properties, connections, or process structure.
>
> ![AI Analyst Diagram - Light Mode](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/AI%20Analyst-edit-existing.svg)

***

## How to use

The AI Analyst is accessed through the FlowX.AI Platform interface.

**1. Select the desired capability**

Choose the appropriate capability from the AI Analyst section based on your input type and goal.

**2. Provide input**

Supply input in the appropriate format: text prompt, image, document, or BPMN file.

**3. Add additional context**

Optionally add extra context or requirements to refine the generated output.

**4. Review the generated process**

Review the generated process in a visual BPMN format to verify it meets your expectations.

**5. Make adjustments**

Use the "Edit" capabilities to make adjustments if necessary.

**6. Implement the workflow**

Implement the final workflow in your project.

The interaction follows a human-in-the-loop approach, allowing for quality checks and iterative improvements to ensure the generated process meets requirements.

***

## Best practices

### DO the following

> [card]
>
> **Be specific about process goals:**
> Clearly state what the process should accomplish, including start and end points, major milestones, and desired outcomes.

> [card]
>
> **Describe key participants and roles:**
> Mention the different stakeholders or departments involved in the process and their responsibilities.

> [card]
>
> **Include decision points:**
> Specify any conditional logic or decision points that might create branches in the workflow.

> [card]
>
> **Provide process constraints:**
> Mention any business rules, regulations, or time constraints that should be incorporated into the process design.

### DON'T do these

> [card]
>
> **Don't be too technical with BPMN terms:**
> You don't need to use precise BPMN terminology; the AI Analyst can interpret business language and convert it to appropriate BPMN elements.

> [card]
>
> **Don't request subprocess details:**
> The AI Analyst has no knowledge about subprocesses or other platform-specific information not provided in your input.

> [card]
>
> **Don't upload low-quality images:**
> When generating from images, ensure the diagram is clear and readable to improve accuracy of the generated process.

> [card]
>
> **Don't expect platform-specific optimizations:**
> The AI Analyst generates standard BPMN representations and may not incorporate FlowX.AI platform-specific features automatically.

***

## Related resources

> [card] [Agent Builder](../agent-builder/overview)
>
> Build custom AI agents for your business workflows

> [card] [AI Designer](./ai-designer)
>
> Generate and refine UI components using AI

> [card] [AI Developer](./ai-developer)
>
> Generate business rules and integration logic with AI


# AI Architect
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-architect

Generate and extend project data models from natural language prompts, with a preview step before you apply anything to your project.

## Overview

The AI Architect is a design-time agent that turns natural language descriptions into project data models. Describe the business entities you need, with their attributes, types, and relationships, and the AI Architect proposes a data model you can preview in the data model builder and apply to your project. Follow-up messages refine or extend the proposed model instead of starting over, so you can build up a model iteratively.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2.** The AI Architect is not available in 5.9.0 or 5.9.1 — it requires the 5.9.2 platform and AI Platform components.

***

## Key capabilities

> [card] Generate a data model from text
>
> Describes-to-model: interprets a natural language description of your business domain and proposes entities, attributes, and types for your project data model.

> [card] Extend an existing model
>
> Follow-up messages continue the same conversation and refine the current proposal without regenerating from scratch. Against a model already saved to the project, the agent only adds new entities and attributes — it does not rename, retype, or remove existing data types.

> [card] Preview before applying
>
> The proposed model renders as a preview in the data model builder graph, so you can inspect entities and attributes before anything is written to the project.

> [card] Apply to your project
>
> Applying the preview creates the new entities and attributes in your project data model in one operation. Apply only adds — existing data types are never modified or removed. If a proposed type name collides with one already in the project, it is created under a new name and the conversation lists which types were renamed.

***

## How to use

**1. Open the data model builder**

In your project, open the **Data Model** section.

**2. Generate with AI**

Select **Generate with AI** and describe the data model you need — the entities, their attributes, and how they relate.&#x20;

**3. Review the preview**

The proposed model appears as a preview in the data model graph. Inspect the entities and attributes before accepting anything.

**4. Refine with follow-ups**

Send follow-up messages to extend or adjust the proposal. The agent continues the same thread instead of generating a new model.

**5. Apply the model**

When the preview matches what you need, apply it. The new entities and attributes are created in your project data model; existing data types stay untouched.&#x20;

***

## Generate a data model from a document

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.4**

Instead of describing the model in text, you can have the AI Architect build it from an existing document — for example, a data dictionary, a specification, or a form. The agent reads the document, extracts the entities and attributes it describes, and proposes a project data model that you preview and apply the same way as a text-generated model.

**1. Open Generate with AI**

In your project's **Data Model** section, select **Generate with AI**.

**2. Choose From document**

In the initial message, select **From document** and pick the document to generate from. The agent extracts the relevant entities and attributes from the document's content.

**3. Review and edit the proposal**

Inspect the proposed model in the preview. Before applying, you can adjust it — add keys by prompting the agent in a follow-up message, or use the **Modify keys** modal to edit keys directly.

**4. Apply the model**

Apply the preview to create the new entities and attributes in your project data model. Apply only adds — existing data types are never modified or removed.

***

## Best practices

> [card]
>
> **Describe entities and their relationships:**
> Name the business objects you need and how they relate. For example, "`a Customer with name, email, and date of birth, and a list of Accounts, each with an IBAN and a balance`".

> [card]
>
> **Refine instead of regenerating:**
> Use follow-up messages to add or adjust entities in the proposed model. The agent extends the existing proposal, which keeps the preview consistent.

> [card]
>
> **Don't apply without reviewing the preview:**
> The preview exists so you can check attribute names and types against your conventions before they are created in the project.

***

## Related resources

> [card] [AI Designer](./ai-designer)
>
> Generate UI layouts that map to your data model

> [card] [AI Developer](./ai-developer)
>
> Generate business rules and integration logic

> [card] [Agent Builder](../agent-builder/overview)
>
> Overview of AI agents and the Agent Builder


# AI Assistant
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-assistant

Answers questions about the FlowX.AI platform as well as your organization's business domain based on uploaded documentation.

## Overview

The AI Assistant provides intelligent documentation support for both the FlowX.AI platform and your organization's business domain. It functions as a knowledge hub that can quickly search, retrieve, and synthesize information from both built-in FlowX.AI documentation and custom uploaded documents. You can ask natural language questions and receive well-formatted, accurate answers drawn from up-to-date documentation sources.

<video />

***

## Key capabilities

The AI Assistant offers specialized content search functionality across different documentation sources:

> [card] Platform documentation search
>
> Provides answers to questions about the FlowX.AI platform, its features, configuration options, and best practices. Accesses a comprehensive repository of approximately 1,000 documentation chunks (318,000 tokens).

> [card] Custom document support
>
> Upload your organization's business domain documentation so the assistant can answer domain-specific questions alongside platform queries.

> [card] Natural language queries
>
> Handles direct questions, keyword searches, or general topic inquiries related to the platform and uploaded documentation.

> [card] Formatted responses
>
> Delivers answers in well-formatted markdown for readability, with rapid response times for most queries. Documentation ingestion takes approximately 12 seconds.

***

## How it works

The AI Assistant architecture follows a retrieval-augmented generation approach:

```mermaid theme={"dark"}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#f1774a',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#6b6b6b',
      'secondaryColor': '#f3b861',
      'tertiaryColor': '#000'
    }
  }
}%%
graph TD;
    Start([Start]):::primary
    Check_Prompt[Check Prompt]:::secondary
    Rewrite_Query[Rewrite Query]:::secondary
    Retrieve_Documents[Retrieve Documents]:::secondary
    Grade_Documents[Grade Documents]:::secondary
    Generate_Answer[Generate Answer]:::secondary
    Generate_Greetings[Generate Greetings]:::secondary
    END([END]):::primary

    Start --> Check_Prompt;
    Check_Prompt --> Rewrite_Query;
    Check_Prompt --> Generate_Greetings;
    Rewrite_Query --> Retrieve_Documents;
    Retrieve_Documents --> Grade_Documents;
    Grade_Documents --> Generate_Answer;
    Generate_Answer --> END;
    Generate_Greetings --> END;

    %% Styling
    classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
    classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
```

The workflow begins with query refinement, followed by document retrieval and relevance grading. Based on the quality of retrieved information, the system can generate an immediate response, process a more complex response asynchronously, or refuse to answer if no relevant documentation is found.

***

## How to use

The AI Assistant is accessible within the FlowX.AI Platform:

**1. Open the AI Assistant**

Find the AI Assistant in the help section of the platform interface.

**2. Ask a question**

Use the chat-based interface to type natural language questions. View responses in real-time with markdown formatting, and follow up with additional questions in a conversational manner.

**3. Upload custom documentation**

Upload your organization's documentation through the document upload interface in the assistant section. You can select files from your local system or provide URLs to documentation resources.

**4. Reference past conversations**

Access saved conversations to reference past interactions. The assistant maintains context between sessions.

***

## Best practices

### DO the following

> [card]
>
> **Be specific with your questions:**
> Clearly articulate what information you need about the FlowX.AI platform or your organization's business domain. The more specific your question, the more precise the answer will be.

> [card]
>
> **Reference platform components:**
> Mention specific features, modules, or functions you're asking about to help the assistant retrieve the most relevant documentation.

> [card]
>
> **Provide context:**
> When asking follow-up questions, include relevant context or reference your previous inquiry to help the assistant understand the conversation flow.

> [card]
>
> **Ask about best practices:**
> The assistant can provide guidance on recommended approaches and implementation strategies based on official documentation.

### DON'T do these

> [card]
>
> **Don't ask about undocumented features:**
> The assistant relies on available documentation and may not be able to provide information about unreleased or undocumented functionality.

> [card]
>
> **Don't expect troubleshooting of specific implementations:**
> While the assistant can provide general guidance, it cannot debug custom code or analyze specific implementation issues without detailed context.

> [card]
>
> **Don't assume complete knowledge:**
> If documentation doesn't cover a particular topic, the assistant may not be able to provide comprehensive information on that subject.

> [card]
>
> **Don't ask unrelated questions:**
> The assistant is specialized in FlowX.AI platform and your organization's business domain documentation and may not provide accurate answers on unrelated topics.

***

## Related resources

> [card] [Agent Builder overview](../agent-builder/overview)
>
> Create and configure custom AI agents for your organization

> [card] [AI Analyst](./ai-analyst)
>
> Assists with process analysis and optimization recommendations

> [card] [AI Designer](./ai-designer)
>
> Helps design and build UI components and process flows


# AI Designer
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-designer

Convert natural language prompts, Figma designs, or sketches into complete UI layouts with validations and data models.

## Overview

The AI Designer is a tool that transforms design concepts into functional UI components for the FlowX.AI platform. Whether you start with a text description, an image of a design, or a form structure, the AI Designer can generate complete, interactive UI layouts that are immediately usable in your apps. It also handles mapping UI elements to your data model and can modify existing designs based on natural language instructions, significantly accelerating the UI development process.

> [!NOTE]
>
> **Improved in FlowX.AI 5.9.1.** The AI Designer now generates layouts in a flat template format (replacing the previous three-level section/region/component nesting) for more reliable output, supports additional component types — **Multi-Select**, **Bulk File Upload**, **Table Cell**, **Collection**, **Message** banners, and **reusable template** references — and edits existing templates by applying incremental changes to the affected components instead of regenerating the whole layout.

***

## Key capabilities

The AI Designer offers two main categories of capabilities:

### Generate new UI

> [card] Generate UI from text
>
> Creates complete UI layouts based on natural language descriptions. Interprets design requirements and converts them into structured UI elements, maps generated UI components to data model entities when available, produces JSON representations that are automatically parsed into FlowX.AI components, and validates that prompts are UI-related before proceeding with generation.

> [card] Generate UI from image
>
> Extracts UI designs from uploaded images (sketches, mockups, screenshots). Works with hand-drawn sketches, Figma designs, or other visual UI representations. Processes complex images by splitting them into sections for parallel analysis, reconstructs the visual design as functional FlowX.AI UI components, and supports additional textual context to guide the interpretation.

> [card] Generate UI from form
>
> Creates structured form interfaces based on form descriptions or requirements. Automatically adds appropriate validations for form fields, organizes form elements in a logical, user-friendly layout, and connects form fields to the corresponding data model properties.

> [card] Edit UI from text
>
> Modifies specific containers or cards in existing UI designs. Updates layouts, components, or properties based on natural language instructions. Preserves the structure and functionality of unmodified UI elements, maintains data model connections while implementing requested changes, and validates that edit requests are UI-related before applying modifications.

### Project data model awareness

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**
>
> The AI Designer receives your project's data model, including data types defined in libraries, as context for every generate and edit request.

When mapping generated UI fields to data, the agent can reference the data types that already exist in your project or its libraries instead of inventing new attributes. A proposed attribute that matches an existing project data type is created as a reference to that type, not a copy, so the data model stays consistent as the referenced type evolves. Proposed data-model changes are still presented for review before you keep them.

***

### UI Flow generation and editing

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The AI Designer also works on whole **UI Flows**, not only on the UI of a single screen:

* **Generate a multi-page UI Flow** from a description. The agent first lays out the flow's structure, then fills the pages in parallel, and wires the navigation between them.
* **Edit an existing UI Flow** with natural-language instructions. Edits are applied to the affected pages rather than regenerating the flow, and adding a page keeps the flow's existing home page in place.
* **Preview before you keep it.** The proposed result is shown on the UI Flow canvas as a draft, and the editor is locked while a proposal is pending so the draft and your own edits cannot race each other.
* **Data-model outcomes on every turn.** As with single-screen generation, proposed data-model changes are presented for review before you keep them.

## How it works

The AI Designer integrates visual recognition and natural language processing to transform various inputs into structured UI representations.

```mermaid theme={"dark"}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#f1774a',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#6b6b6b',
      'secondaryColor': '#f3b861',
      'tertiaryColor': '#bababa'
    }
  }
}%%
graph TD;
    Start([Start]):::primary
    Check_Prompt[Check Prompt]:::secondary
    Classify_Image[Classify Image]:::tertiary
    Edit_Interface[Edit Interface]:::tertiary
    Design_UI[Design UI]:::secondary
    Map_to_Data_Model[Map to Data Model]:::secondary
    END([END]):::primary

    subgraph Parallel_Processing [Parallel Processing]
        Extract_Sections[Extract Sections]:::tertiary
        Component_Identification[Component Identification]:::tertiary
        Map_Components[Map Components]:::tertiary
        Grid_Correction[Grid Correction]:::tertiary
        Validate_Layout[Validate Layout]:::tertiary
    end

    Start --> Check_Prompt;
    Start --> Classify_Image;
    Check_Prompt --> Edit_Interface;
    Check_Prompt --> Design_UI;
    Edit_Interface --> Design_UI;
    Classify_Image --> Parallel_Processing;
    Parallel_Processing --> Design_UI;
    Design_UI --> Map_to_Data_Model;
    Map_to_Data_Model --> END;

    %% Styling
    classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
    classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
    classDef tertiary fill:#bababa,stroke:#000,stroke-width:1px,color:#000;
```

The workflow begins with user input being categorized and processed based on its type. All inputs undergo validation to ensure they describe UI elements. For valid requests, the UI Generator creates the appropriate components, which are then mapped to the data model if available. The final output is compiled into a JSON representation that the FlowX.AI platform can interpret and display as a functional UI.

***

## How to use

The AI Designer is accessed through the FlowX.AI Platform interface.

**1. Access the AI Designer**

Open the AI Designer from the platform's design tools section.

**2. Select the desired capability**

Choose between **Generate** or **Edit** mode depending on whether you are creating a new UI or modifying an existing one.

**3. Provide input in the appropriate format**

* Text description for generating or editing UI
* Image upload for visual-based UI generation
* Form structure for form-specific UI creation

**4. Link a data model (optional)**

Optionally link to an existing data model to enable automatic field mapping.

**5. Preview the generated UI**

Preview the generated UI components in real-time.

**6. Make adjustments if necessary**

Use the **Edit** capability to refine and adjust the generated UI through natural language instructions.

**7. Implement the final UI**

Implement the final UI components in your app.

The agent performs validation checks to ensure inputs are appropriate for UI generation, providing helpful feedback when adjustments are needed.

***

## Best practices

### DO the following

> [card]
>
> **Specify a type of screen:**
> This means specifying a signup screen, a profile page or anything else that you want to add to your design. Use a context

> [card]
>
> **Add extra context:**
> If designing a user bank app UI, and you want a screen solely about my expenses, include this in your prompt. For example, '`A expenses page that tracks a list of expenses that includes merchant value and transaction date`'. This ensures a tailored screen generation focused on expense-related content.

> [card]
>
> **Describe user interactions:**
> Explain how users should interact with the UI, including any specific workflows, validation requirements, or dynamic behaviors the UI should support.

> [card]
>
> **Have fun and be creative:**
> Most importantly, unleash creativity in your prompts. See what you can generate that will make your UI design stand out from the rest. The screen designer agent has a multitude of capabilities, so make sure to try them out.

### DON'T do these

> [card]
>
> **Don't specify colors:**
> The single-screen generator cannot create a new design screen in a different color. However, it is easy to switch up the colors of your generated screen using theming feature.

> [card]
>
> **Don't describe multiple screens**
> The screen generator can only generate one type of screen at once. So if you use a prompt referring to two different screens, only one type will be generated.

> [card]
>
> **Don't mention a different device:**
> The AI agents don't understand designing in different design screens. So if you want a different device design screen, check in UI designer how your generated design looks on different platforms (Mobile / Web).

> [card]
>
> **Don't expect platform-specific knowledge:**
> The AI Designer has no knowledge about other nodes or information in your project beyond what you provide in your prompt or the associated data model.

***

## Related resources

> [card] [Agent Builder](../agent-builder/overview)
>
> Overview of AI agents and the Agent Builder

> [card] [AI Analyst](./ai-analyst)
>
> Automate process analysis and optimization

> [card] [AI Developer](./ai-developer)
>
> Generate business rules and integration logic


# AI Developer
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/ai-developer

Generate specific business rules or code expressions from natural language prompts, without manual coding.

## Overview

The AI Developer is an intelligent agent that transforms natural language descriptions into functional code. It helps developers generate business rules, JavaScript expressions, and test data without requiring manual coding. The agent can also edit existing code, provide explanations, and translate between programming languages, significantly accelerating the development process.

<video />

***

## Key capabilities

The AI Developer offers two main categories of capabilities:

### Generate new code

> [card] Generate Business Rule
>
> Transforms natural language descriptions into code using the data model as context. Supports JavaScript, Python, and MVEL. Produces clean, functional business rule code based on text prompts.

> [card] Generate Business Rule from Document
>
> Extracts business rule definitions from uploaded documents. Identifies relevant text on each page that describes business rules, summarizes and presents the information to users in a dropdown, and generates corresponding code based on the selected rule description.

> [card] Generate (un)Hide JavaScript Expression
>
> Creates JavaScript expressions for conditional visibility of elements. Uses the data model as context for proper variable references.

> [card] Generate Computed JavaScript Expression
>
> Produces JavaScript code for calculated or derived values. Uses the data model to ensure proper variable referencing.

> [card] Generate Custom Component
>
> Generates a React Custom Component bundle (JSX, CSS, `package.json`, and sample input data) from a natural-language description. A sample input field lets you supply preview data so the generated component renders meaningfully on first run.

### Edit existing code

> [card] Edit Existing Business Rule
>
> Modifies existing code based on natural language instructions. Uses the data model as context for accurate updates.

> [card] Edit Custom Component
>
> Iterates on an existing Custom Component bundle through the same conversation. The agent keeps the component context across turns and updates JSX, CSS, `package.json`, or sample input data as requested.

> [card] Fix / Explain Code
>
> Fixes errors in business rules based on error logs. Provides clear explanations of what the code does.

> [card] Translate Code Between Languages
>
> Converts business rules from one language to another. Maintains functionality while adapting to language-specific syntax.

### Generate workflow script-node code

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

In the workflow designer, a **Script node** can call AI Developer to generate or refactor its code from a natural-language prompt. The generated code streams into the node's test area for a **Keep** or **Discard** review, with edits shown as a diff. It supports **JavaScript** and **Python**, and respects the same AI Developer permissions as the rest of the agent. To regenerate from scratch, clear the code first; configuration-parameter values are never sent to the model.

### Project data model awareness

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**
>
> The AI Developer receives your project's data model as context when generating or editing business rules, hide/unhide expressions, and computed expressions.

Generated code references the data-model keys that already exist in your project. When the requested logic needs keys that are not in the data model yet, the agent proposes data-model changes alongside the code: new keys to create and existing project data types to instantiate. The proposed changes are presented for review, so you decide whether to add them to the data model before using the generated code.

***

## How to use

The AI Developer is accessible through the FlowX.AI Platform interface. You can:

**1. Select the desired capability**

Choose the capability you need from the AI Developer section.

**2. Provide instructions or upload documents**

Provide natural language instructions or upload relevant documents.

**3. Specify programming language preferences**

Specify programming language preferences when applicable.

**4. Review and implement the generated code**

Review the generated code and implement it in your process.

For document-based generation, you can upload documents, view extracted rule descriptions in a dropdown, select the rule you want to generate, and receive the corresponding code.

***

## How it works

The AI Developer architecture integrates large language models with the FlowX.AI Platform to convert natural language to code.

```mermaid theme={"dark"}
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#f1774a',
      'primaryTextColor': '#000',
      'primaryBorderColor': '#000',
      'lineColor': '#6b6b6b',
      'secondaryColor': '#f3b861',
      'tertiaryColor': '#000'
    }
  }
}%%
graph TD;
    Start([Start]):::primary

    subgraph Document_intelligence [Document intelligence]
        Classify_Document[Classify Document]:::secondary
        Summarize[Summarize]:::secondary
        Identify_process[Identify process]:::secondary
        Extract_Prompt[Extract Prompt]:::secondary
    end

    Generate_Business_rule[Generate Business rule]:::secondary
    END([END]):::primary

    Start --> Document_intelligence;
    Document_intelligence --> Generate_Business_rule;
    Generate_Business_rule --> END;

    %% Styling
    classDef primary fill:#f1774a,stroke:#000,stroke-width:1px,color:#000;
    classDef secondary fill:#f3b861,stroke:#000,stroke-width:1px,color:#000;
```

***

## Best practices

### ✅ DO the following

> [card]
>
> **Be specific with your requirements:**
> Clearly state what the business rule should accomplish, including conditions, actions, and expected outcomes.

> [card]
>
> **Reference data model elements:**
> Mention specific data fields or entities that the code should interact with to ensure proper context.

> [card]
>
> **Specify the programming language:**
> Always indicate whether you need JavaScript, Python, or another supported language for your code generation.

> [card]
>
> **Provide edge cases:**
> Mention special conditions or exceptions that the business rule should handle to ensure reliable code.

### ⛔ **DON'T** do these

> [card]
>
> **Don't be vague:**
> Avoid ambiguous descriptions that can lead to incorrect implementation. Be precise about the logic you need.

> [card]
>
> **Don't reference external systems:**
> The AI Developer has no knowledge of external systems not defined in the provided context.

> [card]
>
> **Don't skip defining variables:**
> Make sure to define all variables or data fields that your business rule will use.

> [card]
>
> **Don't expect platform-specific knowledge:**
> The agent doesn't know about keys or information not defined in the data model or provided context.

***

## Related resources

> [card] [Agent Builder](../agent-builder/overview)
>
> Build and configure custom AI agents for your business needs

> [card] [AI Analyst](./ai-analyst)
>
> Generate process definitions and data models from natural language descriptions

> [card] [AI Designer](./ai-designer)
>
> Automatically generate UI components and screen layouts from process definitions


# Config-time agents
Source: https://docs.flowx.ai/5.9/ai-platform/pre-built-agents/overview

AI agents built into FlowX Designer that help you create processes, UIs, and business rules faster.

Config-time agents are AI assistants embedded directly in FlowX Designer. They help developers and business analysts build applications faster by automating repetitive tasks and providing intelligent suggestions.

![Config-time agents architecture](https://mintcdn.com/flowxai/CH7X7nDyzWRQEeu0/5.9/ai-platform/pre-built-agents/images/ai-core/ai-core-dark.svg?fit=max\&auto=format\&n=CH7X7nDyzWRQEeu0\&q=85\&s=ea718a83c0faf938cd784aa2f67e7d34)

***

## Available agents

> [card] [Analyst](./ai-analyst)
>
> Build and optimize BPMN processes using AI to generate, validate, and enhance workflows

> [card] [Architect](./ai-architect)
>
> Generate and extend project data models from natural language descriptions

> [card] [Assistant](./ai-assistant)
>
> Answer questions about FlowX platform and your organization based on documentation

> [card] [Designer](./ai-designer)
>
> Convert natural language prompts, Figma designs, or sketches into UI layouts

> [card] [Developer](./ai-developer)
>
> Generate business rules and code expressions using natural language

***

## Access AI in FlowX Designer

Use **Cmd/Ctrl+K** anywhere in FlowX Designer to open the Command Palette and access AI features.

![Command Palette](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/command_palette.png)

You can also look for the **✨ icon** throughout the interface to find AI-powered features.

***

## Human approval: Keep or Discard

Config-time agents never change your project on their own. Everything an agent generates is staged as a **draft** that a person must explicitly accept:

1. **Propose**: the agent renders its output as a visual draft directly on the target surface — a generated process on the BPMN canvas, generated UI in the UI Designer, generated code in the script editor. Data-model changes appear as a diff, with added and modified entities highlighted.
2. **Review**: you inspect the draft in place, refine it by sending another message, and for generated data-model keys you can edit each key or opt out of it individually.
3. **Keep or Discard**: clicking **Keep** applies the draft to the project. Clicking **Discard** drops it — nothing is persisted, and no partial changes remain. If you navigate away with an unkept draft, the Designer warns you before the draft is lost.

When an agent produces an execution plan from an uploaded document, each planned resource has its own **Implement** action, so a person drives every step of the plan.

> [!NOTE]
>
> The AI Assistant answers questions and cites its sources; it does not propose project changes, so it has no Keep step.

***

## LLM flexibility

Config-time agents support multiple LLM deployment options:

| Option | Description |
| - | - |
| **Custom models** | Run your own LLM models through the model registry |
| **Internal LLMs** | Connect to your organization's LLMs via OpenAI-compatible API |
| **Cloud providers** | Use OpenAI or Azure OpenAI, configured in [AI providers](/5.9/ai-platform/ai-providers) |

Access to LLMs can be configured through a proxy or gateway. Configure endpoints via environment variables.

***

## Related resources

> [card] [AI in FlowX](../ai-in-flowx)
>
> Overview of all AI capabilities

> [card] [Agent Builder](../agent-builder/overview)
>
> Create custom business agents


# Research
Source: https://docs.flowx.ai/5.9/ai-platform/research

FlowX.AI public research: the border open-source guardrails library, open models on Hugging Face, and the research paper series.

FlowX.AI publishes research as open tools, open models, and papers. This page indexes what is public; everything below links to its original home.

> [!NOTE]
>
> These are research artifacts and open-source tools published by FlowX.AI, not shipped platform features. For platform capabilities, see [AI in FlowX](./ai-in-flowx).

***

## border: open-source LLM guardrails

[border](https://border.flowx.ai) is an open-source Python library (Apache-2.0) that checks LLM inputs and outputs and signs an evidence record for each check. Evidence records hold hashes, the resolved policy hash, and the model revision that produced each finding, never the user's text. It runs on CPU with the network interface down, and every classifier is scored in 26 languages.

```bash theme={"dark"}
pip install flowx-border
```

> [card] [border.flowx.ai](https://border.flowx.ai)
>
> Project site and documentation

> [card] [GitHub](https://github.com/flowx-ai/border)
>
> Source, Apache-2.0

> [card] [Benchmarks](https://border.flowx.ai/benchmarks)
>
> Published latency and accuracy numbers

***

## Open models on Hugging Face

The [flowxai organization on Hugging Face](https://huggingface.co/flowxai) publishes 50 Apache-2.0 models focused on on-device AI for regulated industries: PII detection (`piiguard`, `cee-pii`), scam and fraud classification (`scam-guard`), content moderation, and regulated-advice detection, alongside two public benchmarks (`cee-pii-bench`, `scamguardbench`).

> [card] [huggingface.co/flowxai](https://huggingface.co/flowxai)
>
> All models and benchmark datasets

***

## Paper series

Seven technical papers on enterprise AI agents, published at [flowx.ai/research](https://www.flowx.ai/research):

| Paper | Scope |
| - | - |
| **VERA** | ROI measurement for production agents |
| **ORNA** | Agent self-adaptation |
| **HALO** | Hallucination prevention |
| **GAVEL** | Runtime governance and audit enforcement |
| **SIFT** | Self-teaching document classification |
| **RAILS** | Deterministic agent workflows |
| **MNEMĒ** | Structured memory with provenance tracking |

> [card] [flowx.ai/research](https://www.flowx.ai/research)
>
> The paper series, with arXiv links where available

***

## Browser-agent reliability benchmark

[Browser Agents Don't Fail on Capability. They Fail on Consistency](https://www.flowx.ai/blog/browser-agents-dont-fail-on-capability-they-fail-on-consistency) benchmarks nine LLMs driving the open-source [browser-use](https://github.com/browser-use/browser-use) library through nine controlled web tasks, five repetitions each: 405 runs in total. Tasks cover multi-page forms, iframes, shadow DOM elements, scrolling, and error recovery. Every outcome is verified against the target site's recorded submissions and state changes, not against the agent's own success claim.

Key findings:

* Several models passed all 45 of their runs, and the models that did span a 26.5x per-run cost difference: price does not predict reliability.
* Some models reported success even on runs that failed, with overconfidence rates reaching 26.7%.
* Checking only whether the requested action happened misses over-actions, such as an agent submitting the same claim twice; outcome-state verification catches them.

> [card] [Read the benchmark](https://www.flowx.ai/blog/browser-agents-dont-fail-on-capability-they-fail-on-consistency)
>
> Full methodology and per-model results on the FlowX.AI blog


# BPMN integration
Source: https://docs.flowx.ai/5.9/ai-platform/using-agents/bpmn-integration

Trigger AI agents from BPMN workflow nodes for automated document processing, decisions, and content generation.

Integrate AI agents directly into your BPMN processes to automate document processing, make intelligent decisions, and generate content without user interaction.

## Overview

BPMN integration allows you to:

* **Automate document processing** in the background
* **Make AI-powered decisions** at process gateways
* **Generate content** automatically within workflows
* **Validate data** using AI analysis

## Integration methods

### Method 1: Start Integration Workflow action

Use the **Start Integration Workflow** action to call an AI agent from any BPMN node.

**1. Add a Service Task**

Add a Service Task node to your process where you want to trigger the agent.

**2. Configure the action**

Add a **Start Integration Workflow** action and select your agent workflow.

**3. Map input data**

Configure which process data to send to the agent (documents, text, parameters).

**4. Handle the response**

Map the agent's response back to process variables.

> [card] [Start Integration Workflow](/5.9/docs/building-blocks/actions/start-integration-workflow)
>
> Detailed configuration reference

### Method 2: Custom Agent Node

For complex agent interactions, use the Custom Agent Node in Integration Designer:

| Feature | Start Integration Workflow | Custom Agent Node |
| - | - | - |
| **Setup complexity** | Simple | More complex |
| **Flexibility** | Standard call/response | Full workflow control |
| **Error handling** | Basic | Advanced |
| **Best for** | Single agent calls | Multi-step AI workflows |

> [card] [Custom Agent Node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
>
> Integration Designer agent configuration

## Common patterns

### Document extraction

Extract data from uploaded documents and continue the process with structured data.

```
User uploads document → Service Task calls extraction agent →
Agent returns structured data → Process continues with data
```

**Configuration:**

* Input: Document file ID or content
* Output: Extracted fields mapped to process variables
* Error handling: Route to manual review if confidence is low

### Automated decisions

Use AI to make or recommend decisions at process gateways.

```
Process reaches gateway → Service Task calls decision agent →
Agent returns recommendation → Gateway routes based on result
```

**Configuration:**

* Input: All relevant process data
* Output: Decision result and confidence score
* Human override: Optional review step for low-confidence decisions

### Content generation

Generate documents, emails, or reports automatically.

```
Process collects data → Service Task calls generation agent →
Agent produces content → Content stored/sent
```

**Configuration:**

* Input: Template reference and data to include
* Output: Generated content (text, HTML, or document)
* Review: Optional human approval before sending

## Input/Output mapping

### Sending data to agents

Map process variables to agent input in the Start Integration Workflow action's **Input Mapping**: select each process data attribute as the source path for an agent workflow input, for example `uploadedDocument.fileId` to `documentId`.

With **Legacy mapping** turned on, the input is a JSON template. Placeholders name process data paths from the root of the process data, with no prefix:

```json theme={"dark"}
{
  "documentId": "${uploadedDocument.fileId}",
  "applicantName": "${application.fullName}",
  "extractionType": "loan_application"
}
```

### Receiving agent responses

Map agent output back to process variables on a **Receive Message Task** after the node that starts the agent. In its **Data Stream**, set the source to **Workflow** and select the agent workflow, then map each End node's output with **Output Mapping**, for example to `extraction`. With **Legacy Mapping** turned on, set a single **Key Name** instead.

## Error handling

> [accordion] Timeout handling
>
> Configure timeouts for agent calls. If an agent doesn't respond in time, route to a fallback path or retry.

> [accordion] Low confidence results
>
> Check confidence scores in gateway conditions. Route low-confidence results to human review.

> [accordion] Agent failures
>
> Use boundary error events to catch agent failures and handle them gracefully.

## Best practices

> [card] Async processing
>
> Use async patterns for long-running agent tasks to avoid blocking the process

> [card] Idempotency
>
> Design agent calls to be safe to retry in case of failures

> [card] Monitoring
>
> Track agent call metrics (latency, success rate, confidence scores)

> [card] Fallbacks
>
> Always have a fallback path for when agents fail or return uncertain results

## Related resources

> [card] [Passing data between nodes](/5.9/docs/building-blocks/process/passing-data-between-nodes)
>
> How node outputs land in process variables and how downstream nodes read them

> [card] [Chat interface](./chat-interface)
>
> User-facing agent interaction

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> Build complex integration workflows

> [card] [Agent Builder](../agent-builder/overview)
>
> Create custom agents

> [card] [Service Tasks](/5.9/docs/building-blocks/node/task-node)
>
> BPMN task configuration


# Chat interface
Source: https://docs.flowx.ai/5.9/ai-platform/using-agents/chat-interface

Add conversational AI to your applications with the FlowX.AI Chat component.

The Chat component provides a conversational interface for users to interact with AI agents. It supports real-time messaging, context-aware responses, and direct integration with your business processes.

## Overview

> [card] Real-time messaging
>
> Instant responses with streaming support

> [card] AI agent integration
>
> Connect to custom agents or FlowX accelerators

> [card] Session management
>
> Persistent conversations across sessions

> [card] Knowledge base access
>
> Context-aware responses from your data

## How it works

The Chat component follows a simple flow:

**1. User initiates chat**

User opens your application and the Chat component loads with a welcome message.

**2. Message exchange**

User sends a message. The component sends it to the configured AI agent workflow.

**3. Agent processing**

The agent processes the message, optionally querying knowledge bases or external systems.

**4. Response delivery**

The agent's response streams back to the user in real-time.

## Key concepts

### Agent workflows

The Chat component connects to an **agent workflow** that defines how messages are processed:

* **Input handling** - How user messages are received
* **AI processing** - Which models and prompts are used
* **Knowledge access** - What data sources the agent can query
* **Response generation** - How responses are formatted

### Session persistence

Conversations can be persisted to maintain context:

| Mode | Description | Use case |
| - | - | - |
| **Session-based** | Conversation lasts for browser session | Quick queries, support |
| **Persistent** | Conversation saved to database | Ongoing cases, history |

### Knowledge base integration

Agents can access knowledge bases for informed responses:

* **RAG (Retrieval-Augmented Generation)** - Agent can search relevant documents while it answers
* **Semantic matching** - Finds conceptually similar content, not just keyword matches
* **Source attribution** - Responses can cite their sources

> [!NOTE]
>
> Knowledge base integration requires configuration in the agent workflow. See [Knowledge Base Overview](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview) for setup details.

## Display modes

The Chat component supports different display modes:

| Mode | Description |
| - | - |
| **Standalone** | Full-page chat experience |
| **Embedded** | Chat panel within a larger UI |
| **Floating** | Expandable chat button overlay |

## Best practices

> [accordion] Set clear expectations
>
> Use the welcome message to explain what the agent can help with. This reduces user frustration from mismatched expectations.

> [accordion] Provide context
>
> Pass relevant process data to the agent (user info, current step, etc.) so responses are contextually appropriate.

> [accordion] Handle limitations gracefully
>
> Configure fallback responses for when the agent can't help. Offer escalation to human support when needed.

> [accordion] Design for mobile
>
> Test the chat experience on mobile devices. Ensure the interface works well with on-screen keyboards.

## Implementation

For detailed configuration and styling options, see the UI Designer documentation:

> [card] [Chat component configuration](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat)
>
> Complete configuration reference for the Chat UI component

## Related resources

> [card] [BPMN integration](./bpmn-integration)
>
> Trigger agents from workflows

> [card] [Agent Builder](../agent-builder/overview)
>
> Create custom agents

> [card] [Chat intents](../patterns/intent-classification-routing)
>
> Configure intent-based routing

> [card] [Knowledge bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Connect your data sources

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Build multi-turn chat experiences with session memory


# Using AI agents
Source: https://docs.flowx.ai/5.9/ai-platform/using-agents/overview

Learn how to integrate and interact with AI agents in your FlowX.AI applications.

Once you've built or configured an AI agent, there are multiple ways to use it in your applications. This guide covers the different integration patterns available.

## Integration options

> [card] [Chat interface](./chat-interface)
>
> Add conversational AI to your apps with the Chat component

> [card] [BPMN integration](./bpmn-integration)
>
> Trigger agents from workflow nodes

> [card] [REST API](/5.9/docs/api/start-process/start-by-process-name)
>
> Call agents programmatically via API

> [card] [Custom Agent Node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
>
> Use agents within Integration Designer workflows

## Choosing an integration method

| Method | Best for | User interaction |
| - | - | - |
| **Chat interface** | Conversational experiences, Q\&A, guided assistance | Direct user interaction |
| **BPMN integration** | Automated processing, document handling, decisions | Background processing |
| **REST API** | External systems, custom frontends, batch processing | Programmatic access |
| **Custom Agent Node** | Complex integrations, multi-step workflows | Workflow orchestration |

## Common patterns

### Pattern 1: Conversational assistant

Add a chat interface to help users complete complex tasks with AI guidance.

```
User opens app → Chat component loads → User asks questions →
Agent responds → User completes task with guidance
```

**Use cases:** Customer support, employee helpdesk, guided form completion

### Pattern 2: Document processing

Automatically process documents submitted through your application.

```
User uploads document → BPMN triggers agent → Agent extracts data →
Data validated → Process continues with extracted data
```

**Use cases:** Loan applications, claims processing, onboarding

### Pattern 3: Decision support

Provide AI-powered recommendations within business processes.

```
Process reaches decision point → Agent analyzes data →
Recommendation generated → Human reviews and approves/rejects
```

**Use cases:** Credit decisions, risk assessment, fraud detection

### Pattern 4: Content generation

Generate documents, reports, or communications automatically.

```
Process collects data → Agent generates content →
Content reviewed → Document sent/stored
```

**Use cases:** Reports, notifications, contracts, summaries

## Session management

AI agents maintain conversation context through sessions:

| Concept | Description |
| - | - |
| **Session** | A conversation thread between user and agent |
| **Context** | Data and history available to the agent |
| **Persistence** | Sessions can be saved and resumed |
| **Isolation** | Each user/process has separate sessions |

> [!NOTE]
>
> Sessions are automatically managed when using the Chat component. For BPMN and API integrations, you control session lifecycle explicitly.

## Data flow

When using agents, data flows through several stages:

**1. Input preparation**

User input, documents, or process data is formatted for the agent

**2. Agent processing**

The agent processes input using configured workflows and AI models

**3. Response generation**

Agent produces output: text, structured data, or actions

**4. Result handling**

Output is displayed to user, stored, or used to continue the process

## Knowledge bases

Agents can access knowledge bases for context-aware responses:

* **Custom knowledge bases** - Your uploaded documents and data
* **External sources** - Connected via MCP integrations

> [card] [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Learn how to connect knowledge bases to your agents

## Best practices

> [accordion] Start with clear use cases
>
> Define specific tasks for your agent rather than general-purpose capabilities. Focused agents perform better.

> [accordion] Provide sufficient context
>
> Include relevant process data when calling agents. More context leads to better responses.

> [accordion] Handle errors gracefully
>
> Always include fallback paths for when agents fail or return low-confidence results.

> [accordion] Monitor and iterate
>
> Track agent performance and user feedback. Continuously improve prompts and workflows.

## Related resources

> [card] [Chat interface](./chat-interface)
>
> Conversational AI integration

> [card] [BPMN integration](./bpmn-integration)
>
> Workflow-based agent usage

> [card] [Agent Builder](../agent-builder/overview)
>
> Create custom agents

> [card] [Config-time agents](../pre-built-agents/overview)
>
> Design-time AI assistants


# Get build info by process instance
Source: https://docs.flowx.ai/5.9/docs/api/start-process/build-info-by-process-instance

GET {BASE_URL}/api/runtime/process-instance/{processInstanceUuid}/build/info
Retrieve the build associated with a running process instance, including the build settings used to render its UI.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).

Returns the build that an already-started process instance is running on, with its associated build settings. Renderers call this when continuing a process across page refreshes; an external app would call it to discover the build version a process started against (for example, before fetching media files, substitution tags, or theme assets keyed by build).

The runtime resolves authorisation by checking that the process instance belongs to a workspace inside your organisation.

## Path parameters

**processInstanceUuid** `string` *required*

The UUID of the process instance.

## Request headers

**Authorization** `string` *required*

Bearer token. Format: `Bearer <token>`.

## Response

Returns a `BuildInfoDTO` with the build identifier, the workspace that owns it, and the build settings (theme, platforms, locale defaults, formatting).

```json theme={"dark"}
{
  "workspaceId": "2ae77b6a-d284-4a0b-ab23-ceaa364c7122",
  "buildId": "7d5560be-3846-49fa-9c17-4059c54c7c5f",
  "applicationId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
  "buildSettings": {
    "applicationVersionId": "99f24e3f-e331-48ad-a503-2cc1cee5fb95",
    "platforms": "OMNICHANNEL",
    "themeId": "12345678-1234-1234-1234-123456789012",
    "defaultLanguageCode": "en"
  }
}
```

```bash theme={"dark"}
curl -X GET "{BASE_URL}/api/runtime/process-instance/{processInstanceUuid}/build/info" \
  -H "Authorization: Bearer <token>"
```


# Get build info by UI flow session
Source: https://docs.flowx.ai/5.9/docs/api/start-process/build-info-by-ui-flow-session

GET {BASE_URL}/api/runtime/ui-flow-session/{uiFlowSessionUuid}/build/info
Retrieve the build associated with a running UI flow session, including the build settings used to render it.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).

Returns the build that an already-started UI flow session is running on, with its associated build settings. Renderers call this when continuing a UI flow across page refreshes; external callers can use it to discover the build version a session is bound to.

Authorisation is enforced by checking that the UI flow session's workspace belongs to your organisation.

## Path parameters

**uiFlowSessionUuid** `string` *required*

The UUID of the UI flow session.

## Request headers

**Authorization** `string` *required*

Bearer token. Format: `Bearer <token>`.

## Response

Returns a `BuildInfoDTO` (same shape as [Get build info by process instance](./build-info-by-process-instance)).

```bash theme={"dark"}
curl -X GET "{BASE_URL}/api/runtime/ui-flow-session/{uiFlowSessionUuid}/build/info" \
  -H "Authorization: Bearer <token>"
```


# Get Build Info
Source: https://docs.flowx.ai/5.9/docs/api/start-process/get-build-info

GET https://admin.devmain.flowxai.dev/rtm/api/runtime/wks/{workspaceId}/app/{appId}/build/info
Retrieve the active build for an app and workspace. Returns the buildId you need to start a process via REST.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).

## Base URL

* Always prepend the endpoint with the correct Base URL.
* For different environments (like staging or production), switch the base URL accordingly.

> [!NOTE]
>
> This endpoint is only accessible via the admin environment. Ensure that you are using the correct admin base URL when making requests.

## Authorization

**Authorization** `string` *required*

Bearer authentication header of the form Bearer `<token>`, where `<token>` is your auth token.

## Request headers

**Authorization** `string` *required*

Bearer token required for authentication. Format: `Bearer <token>`.

**Accept** `string`

Specifies the media types that are acceptable for the response. Defaults to accepting JSON and plain text responses.

**Accept-Encoding** `string`

Indicates supported content encoding algorithms for the response.

**Accept-Language** `string`

Specifies language preferences for the response.

## Path Parameters

> [!NOTE]
>
> **Need help finding the Application ID or Workspace ID?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for detailed instructions on where to locate these values in FlowX Designer.

**workspaceId** `string` *required*

The unique identifier of the workspace that contains the application. This parameter is used to search for the appId within the specified workspace. This value is populated by the Configurator in the container app and varies across different environments (e.g., production, development, UAT).

**appId** `string` *required*

The unique identifier of the application whose build information is being retrieved.

```bash theme={"dark"}
curl --request GET \
  --url https://admin.devmain.flowxai.dev/rtm/api/runtime/wks/{workspaceId}/app/{appId}/build/info \
  --header "Authorization: Bearer <token>" \
  --header "Flowx-Platform: web"
```

## Response Fields

**workspaceId** `string`

The unique identifier of the workspace that contains the application.

**buildId** `string`

The unique identifier of the build entity.

**applicationId** `string`

The ID of the application associated with the build.

**buildSettings** `object`

Contains configuration settings related to the build.

**Properties**

**applicationVersionId** `string`

The version ID of the application associated with the build.

**platforms** `string`

Indicates the supported platforms for the build (e.g., `OMNICHANNEL`).

**themeId** `string`

The ID of the theme applied to the build.

**dateDisplayFormat** `object`

Defines the format used for displaying dates.

**Properties**

**format** `string`

Specifies the date format style (e.g., `short`).

**numberDisplayFormat** `object`

Configuration for displaying numerical values, including decimal precision.

**Properties**

**minDecimals** `integer`

The minimum number of decimal places to display in numerical values.

**maxDecimals** `integer`

The maximum number of decimal places to display in numerical values.

**currencyDisplayFormat** `object`

Defines the format used for displaying currency.

**Properties**

**format** `string`

Specifies the format for displaying currency (e.g., `isoCode`).

**defaultLanguageCode** `string`

The default language code for the build (e.g., `en` for English).

```json Success theme={"dark"}
{
  "workspaceId": "12341234-1234-1234-1234123412341234",
  "buildId": "11111111-1111-1111-1111-111111111111",
  "applicationId": "4ffeeb22-e84a-400f-9e07-b305ab0b4241",
  "buildSettings": {
    "applicationVersionId": "99f24e3f-e331-48ad-a503-2cc1cee5fb95",
    "platforms": "OMNICHANNEL",
    "themeId": "12345678-1234-1234-1234-123456789012",
    "dateDisplayFormat": {
      "format": "short"
    },
    "numberDisplayFormat": {
      "minDecimals": 1,
      "maxDecimals": 2
    },
    "currencyDisplayFormat": {
      "format": "isoCode"
    },
    "defaultLanguageCode": "en"
  }
}
```

## Response Headers

**Access-Control-Allow-Credentials** `boolean`

Indicates whether the response can be exposed when credentials are present. Example: `true`.

**Access-Control-Allow-Headers** `string`

Lists the allowed headers in the actual request.

**Access-Control-Allow-Methods** `string`

Specifies the allowed HTTP methods.

**Access-Control-Allow-Origin** `string`

Indicates the allowed origin for cross-origin requests.

**Content-Encoding** `string`

Specifies the encoding used to compress the response.

**Content-Type** `string`

Indicates the media type of the response content.

**Strict-Transport-Security** `string`

Enforces secure (HTTPS) connections to the server.

**Vary** `string`

Specifies that the response may vary based on the `Accept-Encoding` request header.

**X-Content-Type-Options** `string`

Prevents the browser from MIME-sniffing a response away from the declared `Content-Type`.

**X-XSS-Protection** `string`

Controls the cross-site scripting (XSS) filter. Example: `0` (disabled).


# Start process by build id and process name
Source: https://docs.flowx.ai/5.9/docs/api/start-process/rest2

POST https://admin.devmain.flowxai.dev/rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{processDefinitionName}/start
Start a FlowX process from your own app or backend by specifying the appId, buildId, and process definition name.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).

## Base URL

* Always prepend the endpoint with the correct Base URL.
* For different environments (like staging or production), switch the base URL accordingly.

## Path Parameters

> [!NOTE]
>
> **Need help finding these IDs?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for detailed instructions on where to locate these values in FlowX Designer.

> [!WARNING]
>
> The pair (`buildId`, `appId`) must be valid and associated in the system. The `workspaceId` is internally resolved using the `buildId` from the build collection.

**appId** `string` *required*

The ID of the application. Must form a valid pair with the `buildId`.

**buildId** `string` *required*

The build ID for the runtime environment. Must form a valid pair with the `appId`.

> [!TIP]
>
> When integrating from a frontend application or renderer, use the `buildId` value returned in the [build info response](./get-build-info).

**processDefinitionName** `string` *required*

The name of the process definition to start.

## Request headers

**Authorization** `string` *required*

Bearer token required for authentication. Format: `Bearer <token>`.

**Content-Type** `string` *required*

Indicates the media type of the request body. Must be set to `application/json`.

**Flowx-Platform** `string` *required*

Identifies the client platform (e.g., `web`).

**Accept** `string`

Specifies the media types that are acceptable for the response. Example: `application/json, text/plain, */*`.

**Accept-Encoding** `string`

Indicates supported content encoding algorithms for the response. Example: `gzip, deflate, br, zstd`.

**Accept-Language** `string`

Specifies language preferences for the response. Example: `en-GB,en-US;q=0.9,en;q=0.8`.

**User-Agent** `string`

Identifies the client software making the request (e.g., browser or tool).

**Referer** `string`

The address of the previous web page from which the request was made.

## Request Body

This endpoint requires a JSON request body. The exact payload structure should conform to the process definition schema associated with `{processDefinitionName}`.

**key1** `string` *required*

Description of what key1 represents

**key2** `string` *required*

Description of what key2 represents

### Example Request Body

```json theme={"dark"}
{
  "key1": "value1",
  "key2": "value2"
}
```

## Response

**processDefinitionFlowxUuid** `string`

The unique identifier of the process definition within FlowX.

**buildId** `string`

The ID of the build associated with the process.

**buildStatusAtStart** `string`

The status of the build at the time the process was started (e.g., "COMMITTED").

**applicationId** `string`

The ID of the application where the process was initiated.

**parentApplicationId** `string or null`

The ID of the parent application if applicable, otherwise `null`.

**rootApplicationId** `string or null`

The ID of the root application if applicable, otherwise `null`.

**processDefinitionName** `string`

The name of the process definition that was started.

**tokens** `array`

A list of tokens representing active workflow states within the process.

**state** `string`

The current state of the process instance (e.g., "STARTED").

**uuid** `string`

The unique identifier for the process instance.

**instanceMetadata** `object`

Metadata related to the process instance, including:

* `processInstanceId`: The numeric ID of the process instance.
* `processInstanceUuid`: The UUID of the process instance.

### Response Headers

**Access-Control-Allow-Credentials** `boolean`

Indicates whether the response can be exposed when credentials are present. Value is `true`.

**Access-Control-Allow-Headers** `string`

Lists the allowed headers in the actual request. Example: `DNT, Keep-Alive, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Range, Authorization, flowx-platform`.

**Access-Control-Allow-Methods** `string`

Specifies the allowed HTTP methods. Example: `GET, PUT, POST, DELETE, PATCH`.

**Access-Control-Allow-Origin** `string`

Indicates the allowed origin for cross-origin requests. Example: `https://demo-angular.devmain.flowxai.dev`.

**Content-Encoding** `string`

Specifies the encoding used to compress the response. Example: `gzip`.

**Content-Type** `string`

Indicates the media type of the response content. Example: `application/json`.

**Strict-Transport-Security** `string`

Enforces secure (HTTPS) connections to the server. Example: `max-age=31536000 ; includeSubDomains`.

**Vary** `string`

Specifies that the response may vary based on the `Accept-Encoding` request header. Example: `Accept-Encoding`.

**X-Content-Type-Options** `string`

Prevents the browser from MIME-sniffing a response away from the declared `Content-Type`. Example: `nosniff`.

**X-XSS-Protection** `string`

Controls the cross-site scripting (XSS) filter. Example: `0` (disabled).

```bash theme={"dark"}
curl -X POST "https://admin.devmain.flowxai.dev/rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{processDefinitionName}/start" \
  -H "Authorization: Bearer <token>" \                    # Required
  -H "Content-Type: application/json" \                   # Required
  -H "flowx-platform: web" \                              # Required
  -H "Accept: application/json, text/plain, */*" \        # Optional
  -H "Accept-Encoding: gzip, deflate, br, zstd" \         # Optional
  -H "Accept-Language: en-GB,en-US;q=0.9,en;q=0.8" \      # Optional
  -d '{
    "key": "value"
  }'
```


# Start process by workspace, app, and process name
Source: https://docs.flowx.ai/5.9/docs/api/start-process/start-by-process-name

POST {BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start
Start a process using the workspace's active build — the simplest public REST entry point for triggering a FlowX process from your own backend or scheduled job.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).

This is the recommended entry point when you want to start a process from outside FlowX (a backend service, a scheduled job, a partner system) and you do not want to manage `buildId` lookups yourself. The runtime resolves the active build for the given `(workspaceId, appId)` pair automatically.

If you need to pin to a specific build, use [Start process by build id and process name](./rest2) instead.

## Path parameters

> [!NOTE]
>
> **Need help finding these IDs?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide.

**workspaceId** `string` *required*

The ID of the workspace that owns the application.

**appId** `string` *required*

The ID of the application. Must exist in the specified workspace.

**processName** `string` *required*

The name of the process definition to start.

## Request headers

**Authorization** `string` *required*

Bearer token from the configured identity provider. Format: `Bearer <token>`.

**Content-Type** `string` *required*

Must be `application/json`.

## Request body

A JSON object with the initial process values. The exact shape depends on the process definition.

```json theme={"dark"}
{
  "customerEmail": "alice@example.com",
  "loanAmount": 25000
}
```

## Response

Returns the new process instance, including its `uuid` (use this for subsequent calls) and `state`.

```json theme={"dark"}
{
  "processDefinitionName": "customer_onboarding",
  "uuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d",
  "state": "STARTED",
  "applicationId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
  "buildId": "7d5560be-3846-49fa-9c17-4059c54c7c5f",
  "instanceMetadata": {
    "processInstanceUuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d"
  }
}
```

```bash theme={"dark"}
curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "alice@example.com",
    "loanAmount": 25000
  }'
```


# Start process from UI with resource definition and inherit values
Source: https://docs.flowx.ai/5.9/docs/api/start-process/start-process-rdi-inherit

POST {BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}
Start a process by resource definition ID and inherit parameter values from a related process instance. Typically used from event handlers.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).

## Base URL

* Always prepend the endpoint with the correct Base URL for your environment.
* For different environments (like staging or production), switch the base URL accordingly.

## Path Parameters

> [!NOTE]
>
> **Need help finding these IDs?** See the [Finding Identifiers and Parameters](../../platform-deep-dive/integrations/finding-identifiers-and-parameters) guide for detailed instructions on where to locate these values in FlowX Designer.

> [!WARNING]
>
> The combination of `workspaceId`, `appId`, and `resourceDefinitionId` must be valid and associated in the system. The `processInstanceId` must reference an existing process instance from which values will be inherited.

**workspaceId** `string` *required*

The ID of the workspace where the process will be started. This parameter is now required to support multi-workspace environments.

**appId** `string` *required*

The ID of the application in which the process will be started.

**resourceDefinitionId** `string` *required*

The ID of the resource definition that defines the process to be started. This is typically used when starting processes from event handlers.

**processInstanceId** `string` *required*

The UUID of the related process instance from which parameter values will be inherited. This allows the new process to start with data from an existing process.

## Request Headers

**Authorization** `string` *required*

Bearer token required for authentication. Format: `Bearer <token>`.

**Content-Type** `string` *required*

Indicates the media type of the request body. Must be set to `application/json`.

**Flowx-Platform** `string` *required*

Identifies the client platform (e.g., `web`, `mobile`).

**Accept** `string`

Specifies the media types that are acceptable for the response. Example: `application/json, text/plain, */*`.

**Accept-Encoding** `string`

Indicates supported content encoding algorithms for the response. Example: `gzip, deflate, br, zstd`.

**Accept-Language** `string`

Specifies language preferences for the response. Example: `en-GB,en-US;q=0.9,en;q=0.8`.

## Request Body

The request body should contain a `paramsToInherit` object that controls which parameter values are inherited from the related process instance.

**paramsToInherit** `object` *required*

A map containing information about which values to copy from the related process instance. This object can contain one of the following keys:

* **`paramsToCopy`** (array of strings): Use this to pick only a subset of parameters to be inherited from the parent process. It holds the list of key names that will be inherited from the parent parameters.
* **`withoutParams`** (array of strings): Use this to remove specific parameter values from the parent process before inheriting them. It holds the list of key names that will be removed from the parent parameters.

If neither key is provided or both are empty, all parameter values from the parent process will be inherited by the new process.

### Example Request Body

```json Inherit specific parameters theme={"dark"}
{
  "paramsToInherit": {
    "paramsToCopy": ["customerName", "customerId", "accountType"]
  }
}
```

```json Exclude specific parameters theme={"dark"}
{
  "paramsToInherit": {
    "withoutParams": ["temporaryToken", "sessionData"]
  }
}
```

```json Inherit all parameters theme={"dark"}
{
  "paramsToInherit": {}
}
```

> [!TIP]
>
> When designing your process inheritance strategy, consider which parameters are truly needed in the new process. Use `paramsToCopy` for explicit control or `withoutParams` to exclude sensitive or temporary data.

## Response

**processDefinitionFlowxUuid** `string`

The unique identifier of the process definition within FlowX.

**buildId** `string`

The ID of the build associated with the process.

**buildStatusAtStart** `string`

The status of the build at the time the process was started (e.g., "COMMITTED").

**applicationId** `string`

The ID of the application where the process was initiated.

**workspaceId** `string`

The ID of the workspace where the process was started.

**parentApplicationId** `string or null`

The ID of the parent application if applicable, otherwise `null`.

**rootApplicationId** `string or null`

The ID of the root application if applicable, otherwise `null`.

**processDefinitionName** `string`

The name of the process definition that was started.

**tokens** `array`

A list of tokens representing active workflow states within the process.

**state** `string`

The current state of the process instance (e.g., "STARTED").

**uuid** `string`

The unique identifier for the newly created process instance.

**instanceMetadata** `object`

Metadata related to the process instance, including:

* `processInstanceId`: The numeric ID of the process instance.
* `processInstanceUuid`: The UUID of the process instance.

### Response Headers

**Access-Control-Allow-Credentials** `boolean`

Indicates whether the response can be exposed when credentials are present. Value is `true`.

**Access-Control-Allow-Headers** `string`

Lists the allowed headers in the actual request.

**Access-Control-Allow-Methods** `string`

Specifies the allowed HTTP methods.

**Access-Control-Allow-Origin** `string`

Indicates the allowed origin for cross-origin requests.

**Content-Encoding** `string`

Specifies the encoding used to compress the response.

**Content-Type** `string`

Indicates the media type of the response content.

**Strict-Transport-Security** `string`

Enforces secure (HTTPS) connections to the server.

**X-Content-Type-Options** `string`

Prevents the browser from MIME-sniffing a response away from the declared `Content-Type`.

**X-XSS-Protection** `string`

Controls the cross-site scripting (XSS) filter.

```bash cURL - Inherit specific parameters theme={"dark"}
curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "flowx-platform: web" \
  -H "Accept: application/json" \
  -d '{
    "paramsToInherit": {
      "paramsToCopy": ["customerName", "customerId", "accountType"]
    }
  }'
```

```bash cURL - Exclude specific parameters theme={"dark"}
curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "flowx-platform: web" \
  -H "Accept: application/json" \
  -d '{
    "paramsToInherit": {
      "withoutParams": ["temporaryToken", "sessionData"]
    }
  }'
```

```bash cURL - Inherit all parameters theme={"dark"}
curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/rdi/{resourceDefinitionId}/start/inherit-from/{processInstanceId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "flowx-platform: web" \
  -H "Accept: application/json" \
  -d '{
    "paramsToInherit": {}
  }'
```

```json Success Response theme={"dark"}
{
  "processDefinitionFlowxUuid": "66e74ea1-0775-42b4-b27e-a4a21ea78dfc",
  "buildId": "7d5560be-3846-49fa-9c17-4059c54c7c5f",
  "buildStatusAtStart": "COMMITTED",
  "applicationId": "dbe0ab87-539b-4015-962d-6e73226b9e58",
  "workspaceId": "ws-123456789",
  "parentApplicationId": null,
  "rootApplicationId": null,
  "processDefinitionName": "customer_onboarding_child",
  "tokens": [
    {
      "id": 2112691,
      "state": "ACTIVE",
      "statusCurrentNode": "ARRIVED"
    }
  ],
  "state": "STARTED",
  "uuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d",
  "instanceMetadata": {
    "processInstanceId": 2112617,
    "processInstanceUuid": "24cb4216-83a4-4782-84cb-d702b54b9b7d"
  }
}
```

## Triggering from FlowX Designer

This endpoint is triggered through a **Send data to user interface** node action configured in FlowX Designer:

**1. Add node action**

Add a **Send data to user interface** action to the node where you want to trigger the child process.

**2. Configure message type**

Set the **Message type** to `action` to enable process triggering capabilities.

**3. Configure inheritance parameters**

In the action configuration, specify which parameters should be inherited using `paramsToCopy` or `withoutParams` in the action payload.

> [!NOTE]
>
> For detailed instructions on configuring node actions in FlowX Designer, see the [Managing a Process Flow](../../flowx-designer/managing-a-project-flow/starting-a-process) documentation.

## Use Cases

This endpoint is particularly useful for:

* **Multi-step workflows**: Starting a child process that continues work begun in a parent process
* **Process chaining**: Creating related processes that share common data
* **UI-triggered actions**: Starting processes from user interface actions that need to carry over existing data
* **Data inheritance**: Maintaining context across related process instances while controlling which data is passed forward

> [!NOTE]
>
> This endpoint is specifically designed for runtime operations initiated from event handlers. The `workspaceId` parameter ensures proper isolation in multi-tenant environments.


# Start process and copy data from another instance
Source: https://docs.flowx.ai/5.9/docs/api/start-process/start-with-copy-data

POST {BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start/copyDataFrom/{processInstanceId}
Start a new process whose initial data is copied from an existing process instance — useful for retry, resume, and clone-like workflows.

> [!TIP]
>
> Looking for end-to-end guidance on calling FlowX from your own app? See [Consuming FlowX from external apps](/5.9/docs/platform-deep-dive/integrations/consuming-flowx-from-external-apps).

Start a new process instance and seed its data from a previously executed process instance. The new process picks up the data values that were on the source instance at the moment of the call.

Common use cases:

* Replaying a failed workflow with the same input
* Cloning an existing case for a similar customer
* Resuming downstream processing after an interruption

## Path parameters

**workspaceId** `string` *required*

The ID of the workspace that owns the application.

**appId** `string` *required*

The ID of the application.

**processName** `string` *required*

The name of the process definition to start.

**processInstanceId** `string` *required*

The UUID of the source process instance. Its data is copied into the new instance at start time.

## Request headers

**Authorization** `string` *required*

Bearer token. Format: `Bearer <token>`.

**Content-Type** `string` *required*

Must be `application/json`.

## Request body

A JSON object with values to merge on top of the copied data. Pass `{}` to start with the source instance's data unchanged.

```json theme={"dark"}
{
  "retryReason": "manual-rerun",
  "operatorId": "u-9023"
}
```

## Response

Same shape as [Start process by workspace, app, and process name](./start-by-process-name) — the new instance's `uuid`, `state`, and metadata.

```bash theme={"dark"}
curl -X POST "{BASE_URL}/api/runtime/wks/{workspaceId}/app/{appId}/process-name/{processName}/start/copyDataFrom/{processInstanceId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "retryReason": "manual-rerun"
  }'
```


# Accessibility
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/accessibility

WCAG 2.1 Level AA accessibility support in FlowX.AI, including screen reader compatibility, keyboard navigation, and configurable accessibility properties across web and mobile platforms.

## Overview

FlowX.AI provides **WCAG 2.1 Level AA** accessibility compliance for applications built with the platform. Accessibility features are configured in the **UI Designer** and automatically applied by the renderers at runtime across web (Angular, React), iOS, and Android platforms.

> [card] Screen readers
>
> ARIA labels, hints, roles, and live regions automatically mapped to UI components

> [card] Keyboard navigation
>
> Full keyboard support with visible focus indicators and logical tab order

> [card] Cross-platform
>
> Web, iOS (VoiceOver), and Android (TalkBack) support from a single configuration

***

## Configuring accessibility in UI Designer

Accessibility properties are configured in the **Settings** tab of the component configuration panel. Properties are saved in `platformDisplayOptions.flowxProps.accessibility` for the generic platform and apply across all renderers.

```json theme={"dark"}
{
  "platformsDisplayOptions": [
    {
      "flowxProps": {
        "accessibility": {
          "label": "",
          "decorative": false,
          "altText": "",
          "role": ""
        }
      },
      "platform": "generic"
    }
  ]
}
```

### Available properties

| Property | Description |
| - | - |
| **label** | Accessibility label announced by screen readers. Use when the component has no visible label or needs a different label for assistive technologies. |
| **decorative** | Marks the element as decorative so it is ignored by assistive technologies. |
| **altText** | Short descriptive text alternative for images, announced by screen readers. |
| **role** | Landmark role for navigation areas. Options: `main`, `navigation`, `search`, `form`, `header`, `footer`, `aside`, `region`, `dialogue`, `alertdialogue`, `section`. |

***

## Accessibility properties by component

Not all components expose the same accessibility properties. The SDK automatically reads certain existing properties (like label and placeholder text) and exposes them to assistive technologies. Additional properties can be configured where needed.

### Form elements

| Component | Auto-read by SDK | Configurable in Designer |
| - | - | - |
| **Input** | label, text, placeholder, helper, error | accessibility label |
| **Single select** | label, text, placeholder, helper, error | accessibility label |
| **Multi select** | label, text, placeholder, helper, error | accessibility label |
| **Date picker** | label, text, placeholder, helper, error | accessibility label |
| **Text area** | label, text, placeholder, helper, error | accessibility label |
| **Slider** | label, value, helper, error | accessibility label |
| **Checkbox** | label, text, helper, error | accessibility label |
| **Radio button** | label, text, helper, error | accessibility label |
| **Switch** | label, text, helper, error | accessibility label |
| **Segmented button** | label, text, helper, error | accessibility label |

> [!TIP]
>
> Use the accessibility label when the component has no visible label or text, or when you need a different label for assistive technologies.

### Interactive elements

| Component | Auto-read by SDK | Configurable in Designer |
| - | - | - |
| **Button** | label | accessibility label (icon-only) |
| **File upload** | label | accessibility label (icon-only) |

> [!TIP]
>
> For icon-only buttons, always set an accessibility label so screen readers can announce the button's purpose.

### Display elements

| Component | Auto-read by SDK | Configurable in Designer |
| - | - | - |
| **Text** | text | decorative |
| **Link** | text | decorative |
| **Image** | — | alt text, decorative |
| **Message** | text | decorative |
| **Card** | title, subtitle | — |
| **Form** | title | — |
| **File preview** | title, subtitle | — |

### Navigation areas

| Component | Auto-read by SDK | Configurable in Designer |
| - | - | - |
| **Step** | title | accessibility label |
| **Tab** | title | accessibility label |
| **Modal** | title | accessibility label |

> [!TIP]
>
> Use the accessibility label for navigation areas when the area has no visible label or text, or when a different label is needed for assistive technologies.

***

## Landmark roles

Navigation areas are assigned landmark roles that help screen reader users understand the page structure and navigate between regions.

### Default roles

| Navigation area | Default role | Configurable |
| - | - | - |
| **Page** | `main` | No |
| **Stepper** | `navigation` | No |
| **Step** | `navigation` | No |
| **Tabbar** | `navigation` | No |
| **Tab** | `navigation` | No |
| **Modal** | `dialogue` | No |
| **Zone** | `section` | Yes |

### Zone roles

Zones can be configured with a landmark role to convey their purpose to assistive technologies:

* `main` — primary content area
* `section` — generic section (default)
* `nav` — navigation region
* `header` — page or section header
* `footer` — page or section footer
* `aside` — complementary content

***

## Keyboard navigation

FlowX.AI applications support full keyboard navigation with visible focus indicators. Focus is indicated by an outline around the active element.

### General patterns

| Key | Action |
| - | - |
| `Tab` | Move focus to the next interactive element |
| `Shift + Tab` | Move focus to the previous interactive element |
| `Enter` / `Space` | Activate the focused element (button, link, toggle) |
| `Escape` | Close modal or dismiss popup |
| Arrow keys | Navigate within a component (radio options, slider, select list, tabs) |

### Component-specific behavior

> [accordion] Button / File upload
>
> * `Tab` focuses the element (skipped if disabled)
> * `Space` / `Enter` executes the action

> [accordion] Input / Text area
>
> * `Tab` focuses the element and enables typing (skipped if disabled)
> * Arrow keys move within the text
> * If the element has a clear button, `Tab` navigates to it; `Space` / `Enter` clears the value

> [accordion] Checkbox
>
> * `Tab` focuses the first option, then subsequent options
> * `Space` / `Enter` selects or deselects the focused option
> * After the last option, `Tab` moves to the next element

> [accordion] Radio / Segmented button
>
> * `Tab` focuses the selected option (or the first option if none selected)
> * `Down` / `Right` arrow moves focus forward and selects
> * `Up` / `Left` arrow moves focus backward and selects
> * Navigation wraps cyclically through options

> [accordion] Switch
>
> * `Tab` focuses the element (skipped if disabled)
> * `Space` / `Enter` toggles the value

> [accordion] Slider
>
> * `Tab` focuses the slider knob
> * `Up` / `Right` arrow increases by one step
> * `Down` / `Left` arrow decreases by one step

> [accordion] Select
>
> * `Tab` focuses the element and enables typing (skipped if disabled)
> * `Up` / `Down` arrow opens the listbox
> * In the listbox: arrows navigate options, `Enter` selects and closes, `Escape` closes
> * Focus remains on the input while the listbox is open
> * If the element has a clear button, `Tab` navigates to it

> [accordion] Multi select
>
> * `Tab` focuses the element and enables typing (skipped if disabled)
> * In the listbox: arrows navigate options, `Enter` selects (without closing), `Escape` closes
> * Focus remains on the input while the listbox is open

> [accordion] Tabs
>
> * `Tab` moves focus to the active tab header
> * `Left` / `Right` arrow navigates between tab headers cyclically
> * `Space` / `Enter` activates the focused tab
> * `Tab` from the active tab header moves focus to the first focusable element in the tab content

> [accordion] Modal
>
> * When opened, focus moves to the first focusable element inside the modal
> * Focus is trapped within the modal — `Tab` cycles through modal content
> * `Escape` closes the modal

> [accordion] Accordion
>
> * `Tab` focuses the accordion trigger
> * `Enter` / `Space` expands or collapses the section
> * When expanded, `Tab` moves to the first focusable element in the content
> * When collapsed, `Tab` moves to the next accordion header cyclically

***

## Screen reader support

FlowX.AI renderers automatically apply ARIA attributes to components based on their type and configuration. Many attributes are auto-bound — no manual configuration needed.

### Auto-bound ARIA attributes

> [accordion] Form elements
>
> | Attribute | Applied to |
> | - | - |
> | `aria-describedby` | Helper text, error messages |
> | `aria-required` | Required fields |
> | `aria-invalid` | Fields with validation errors |
> | `aria-checked` | Checkbox, radio, switch state |
> | `aria-selected` | Select option state |
> | `aria-expanded` | Select/multiselect dropdown state |
> | `aria-autocomplete` | Select search input |
> | `aria-valuemin`, `aria-valuemax`, `aria-valuenow` | Slider |

> [accordion] Navigation and containers
>
> | Attribute | Applied to |
> | - | - |
> | `role="tablist"` | Tab container, stepper |
> | `role="tab"`, `aria-controls`, `aria-selected` | Individual tabs |
> | `role="tabpanel"`, `aria-describedby` | Tab content panels |
> | `role="dialog"`, `aria-modal` | Modals |
> | `aria-labelledby` | Modal (references title) |
> | `aria-current` | Active step in stepper |
> | `aria-expanded` | Accordion headers |
> | `role="radiogroup"` | Radio/segmented button container |

> [accordion] Interactive elements
>
> | Attribute | Applied to |
> | - | - |
> | `aria-label` | Buttons, links (from label/text) |
> | `aria-disabled` | Disabled buttons and inputs |
> | `aria-pressed` | Toggle buttons |
> | `role="button"` / `role="link"` | Buttons and links |
> | `aria-live="polite"` | Message components |

> [accordion] Display elements
>
> | Attribute | Applied to |
> | - | - |
> | `alt` | Images (from alt text property) |
> | `aria-hidden="true"` | Decorative images, text, links, messages |

***

## Platform support

### Implementation status

| Feature | Web (Angular/React) | iOS (VoiceOver) | Android (TalkBack) |
| - | :-: | :-: | :-: |
| Accessibility labels | ✅ | ✅ | ✅ |
| Decorative elements | ✅ | ✅ | ✅ |
| Image alt text | ✅ | ✅ | ✅ |
| Landmark roles | ✅ | — | — |
| Keyboard navigation | ✅ | N/A | N/A |
| ARIA auto-binding | ✅ | N/A | N/A |
| Form elements (screen reader) | ✅ | ✅ | ✅ |
| Date picker (screen reader) | 🚧 | 🚧 | 🚧 |
| Single select (screen reader) | 🚧 | 🚧 | 🚧 |
| Multi select (screen reader) | 🚧 | 🚧 | 🚧 |

> [!NOTE]
>
> 🚧 indicates components with partial screen reader support that is actively being improved.

### Version availability

| Platform | Accessibility feature | Available since |
| - | - | - |
| **Web** (Angular/React) | WCAG 2.1 Level AA compliance | FlowX.AI 5.1.1 |
| **Android** | Accessibility properties from UI Designer | FlowX.AI 5.1.2 |
| **iOS** | VoiceOver support | FlowX.AI 5.1.3 |

***

## Client responsibilities

FlowX.AI handles accessibility for platform-rendered components automatically. However, some accessibility aspects depend on the container application and content authored by the client.

### What FlowX.AI handles

* ARIA attributes on all rendered components
* Keyboard navigation and focus management
* Screen reader announcements for form states (errors, required fields)
* Focus trapping in modals
* Landmark roles for navigation areas

### What clients are responsible for

> [accordion] HTML and page structure
>
> * Set the `lang` attribute on the `html` element for correct screen reader pronunciation
> * Provide a unique `title` for each page
> * Ensure viewport zoom is not disabled (`user-scalable=yes`)
> * Use logical heading hierarchy (`h1` → `h2` → `h3`, no skipping levels)

> [accordion] Content authoring
>
> * Write descriptive button and link labels (avoid "click here", "read more")
> * Provide meaningful alt text for images
> * Mark decorative elements appropriately
> * Use plain language ([8th grade reading level](https://datayze.com/readability-analyzer.php))
> * Use left-aligned text for LTR languages, right-aligned for RTL

> [accordion] Color and contrast
>
> * Normal text: minimum **4.5:1** contrast ratio
> * Large text: minimum **3:1** contrast ratio
> * Icons and UI elements: minimum **3:1** contrast ratio
> * Do not use color as the only way to convey information
> * Ensure error, warning, and success states are distinguishable without color

> [accordion] Media and animation
>
> * Avoid autoplaying media
> * Provide captions for video content
> * Avoid strobing or flashing animations (seizure triggers)
> * Respect `prefers-reduced-motion` for custom animations

> [accordion] Mobile considerations
>
> * Support both portrait and landscape orientation
> * Ensure touch targets are large enough for easy activation
> * Provide sufficient space between interactive elements for scrolling
> * Avoid horizontal scrolling

***

## Testing recommendations

> [card] Keyboard testing
>
> Navigate your application using only the keyboard. Verify that all interactive elements are reachable via `Tab`, that focus is visible, and that focus order matches the visual layout.

> [card] Screen reader testing
>
> Test with VoiceOver (macOS/iOS), TalkBack (Android), or NVDA/JAWS (Windows). Verify labels are announced correctly and form states are communicated.

> [card] Automated testing
>
> Use axe-core or similar tools in your CI pipeline to catch common accessibility issues. Storybook's `addon-a11y` plugin provides real-time feedback during development.

> [card] High contrast modes
>
> Activate Windows High Contrast mode or inverted colors. Verify content is still legible and interactive elements are distinguishable.

***

## Related resources

> [card] [Platform considerations](../building-blocks/ui-designer/platform-considerations)
>
> Platform-specific configuration for web, iOS, and Android renderers

> [card] [UI Designer](../building-blocks/ui-designer/ui-designer)
>
> Overview of the UI Designer and component configuration

> [card] [Localization and i18n](../building-blocks/ui-designer/localization-and-i18n)
>
> Language, region, and formatting configuration

> [card] [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
>
> Official W3C quick reference for WCAG 2.1 success criteria


# Building a connector
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/building-a-connector

Build custom connectors to integrate external systems with FlowX.AI as independently deployable microservices.

## Connector essentials

At its core, a connector acts as an anti-corruption layer. It manages interactions with external systems and crucial data transformations for integrations.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/connector_structure.png)

## Key functions

Connectors act as lightweight business logic layers, performing essential tasks:

1. **Data Transformation**: Ensure compatibility between different data formats, like date formats, value lists, and units.

2. **Information Enrichment:** Add non-critical integration information like flags and tracing GUIDs.

## Creating a connector

1. **Create a Kafka Consumer:** Follow [**this guide**](./creating-a-kafka-consumer) to configure a Kafka consumer for your Connector.

2. **Create a Kafka Producer:** Refer to [**this guide**](./creating-a-kafka-producer) for instructions on setting up a Kafka producer.

> [!NOTE]
>
> Adaptable Kafka settings can yield advantageous event-driven communication patterns. Fine-tuning partition counts and consumers based on load testing is crucial for optimal performance.

### Design considerations

Efficient Connector design within an event-driven architecture demands:

* Load balancing solutions for varying communication types between the Connector and legacy systems.
* Custom implementations for request load balancing, Connector scaling, and more.

> [!TIP]
>
> Incorporate all received Kafka headers in responses to ensure proper communication with the FlowX Engine.

### Connector configuration sample

Here's a basic setup example for a connector:

* Configurations and examples for Kafka listeners and message senders.
* **OPTIONAL**: Activation examples for custom health checks.

[Sample available here](https://github.com/flowx-ai/quickstart-connector/tree/feature/easy-start)

Follow these steps and check the provided code snippets to effectively implement your custom FLOWX connector:

1. **Name Your Connector**: Choose a meaningful name for your connector service in the configuration file (`quickstart-connector/src/main/resources/config/application.yml`):

```yaml theme={"dark"}
spring:
  application:
    name: easy-connector-name # TODO 1. Choose a meaningful name for your connector service.
  jackson:
    serialization:
      write_dates_as_timestamps: false
      fail-on-empty-beans: false
```

2. **Select Listening Topic:** Decide the primary topic for your connector to listen on ( you can do this at the following path → `quickstart-connector/src/main/resources/config/application-kafka.yml`):

> [!TIP]
>
> If the connector needs to listen to multiple topics, ensure you add settings and configure a separate thread pool executor for each needed topic (refer to `KafkaConfiguration`, you can find it at `quickstart-connector/src/main/java/ai/flowx/quickstart/connector/config/KafkaConfiguration.java`).

3. **Define Reply Topic**: Determine the reply topic, aligning with the Engine's topic pattern.

4. **Adjust Consumer Threads**: Modify consumer thread counts to match partition numbers.

```yaml theme={"dark"}
kafka:
  consumer.threads: 3  # TODO 4. Adjust number of consumer threads. Make sure number of instances * number of threads = number of partitions per topic.
  auth-exception-retry-interval: 10
  topic:
    in: ai.flowx.easy-connector.in # TODO 2. Decide what topic should the connector listen on.
    out: ai.flowx.easy-connector.out # TODO 3. Decide what topic should the connector reply on (this topic name must match the topic pattern the Engine listens on).
```

> [!WARNING]
>
> The FlowX Engine does not consume replies from arbitrary topic names — it subscribes by **topic pattern**. Your reply topic must match one of the two patterns the process engine listens on:
>
> * **Default pattern**: `KAFKA_TOPIC_PATTERN` resolves to `<package><environment>engine.receive.*` (out of the box `ai.flowx.engine.receive.*`; the prefix follows your deployment's `KAFKA_TOPIC_NAMING_*` settings). Consumed with consumer group `adapters` (`KAFKA_CONSUMER_GROUPID_ADAPTERS`). A reply topic like `ai.flowx.engine.receive.easy-connector.results` matches; a name like `ai.flowx.easy-connector.out` does not.
> * **Dedicated connector pattern**: set `KAFKA_TOPIC_CONNECTOR_PATTERN` on the process engine to subscribe an additional listener for connector replies (consumer group `connectors`, `KAFKA_CONSUMER_GROUPID_CONNECTORS`). The listener starts only when the variable is non-empty. Use this when connector reply topics keep their own naming instead of the `engine.receive` convention.

**Topic provisioning**: the `in` and `out` topics belong to your connector — they are not part of the topic catalog FlowX provisions at deployment, and FlowX brokers run with topic auto-creation turned off. Create both topics in your Kafka cluster before starting the connector, with a partition count that matches your consumer scaling (instances × consumer threads).

> [!NOTE]
>
> Custom connectors are a **self-hosted** capability. On FlowX.AI SaaS the Kafka cluster is internal to the platform and not reachable from outside, so a customer-run connector cannot connect to it. On SaaS, integrate external systems through the [Integration Designer](./integration-designer) (REST data sources and workflows), [incoming webhooks](./incoming-webhooks), or email triggers instead.

5. **Define Incoming Data Format (DTO)**: Specify the structure for incoming and outgoing data using DTOs. This can be found at the path: `quickstart-connector/src/main/java/ai/flowx/quickstart/connector/dto/KafkaRequestMessageDTO.java`.

```java theme={"dark"}
//Example for incoming DTO Format
package ai.flowx.quickstart.connector.dto;

import lombok.Getter;
import lombok.Setter;
import lombok.ToString;

@Getter
@Setter
@ToString
public class KafkaRequestMessageDTO { // TODO 5. Define incoming DTO format.
    private String Id;
}
```

6. **Define Outgoing Data Format (DTO)**: Specify the structure for outgoing data at the following path → `quickstart-connector/src/main/java/ai/flowx/quickstart/connector/dto/KafkaResponseMessageDTO.java`.

```java theme={"dark"}
// Example for Outgoing DTO Format
package ai.flowx.quickstart.connector.dto;

import lombok.Builder;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;

@Getter
@Setter
@ToString
@Builder
public class KafkaResponseMessageDTO implements BaseApiResponseDTO { // TODO 6. Define outgoing DTO format.
    private String name;
    private String errorMessage;
}
```

7. **Implement Business Logic**: Develop logic for handling messages from the Engine and generating replies. Ensure to include the process instance UUID as a Kafka message key.

Optional Configuration Steps:

* **Health Checks:** Enable health checks for all utilized services in your setup.

```yaml theme={"dark"}
management: # TODO optional: enable health check for all the services you use in case you add any
  health:
    kafka.enabled: false

```

Upon completion, your configuration files (`application.yaml` and `application-kafka.yaml`) should resemble the provided samples, adjusting settings according to your requirements:

```yaml theme={"dark"}
logging:
  level:
    ROOT: INFO
    ai.flowx.quickstart.connector: INFO
    io.netty: INFO
    reactor.netty: INFO
    jdk.event.security: INFO
server:
  port: 8080
spring:
  application:
    name: easy-connector-name
  jackson:
    serialization:
      write_dates_as_timestamps: false
      fail-on-empty-beans: false
management: 
  health:
    kafka.enabled: false
spring.config.import: application-kafka.yml
logging.level.ROOT: DEBUG
logging.level.ai.flowx.quickstart.connector: DEBUG
```

And your Kafka configuration file (`application-kafka.yaml`) should look like this:

```yaml theme={"dark"}
spring:
  kafka:
    bootstrap-servers: localhost:9092
    security.protocol: "PLAINTEXT"
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
      properties:
        interceptor:
          classes: io.opentracing.contrib.kafka.TracingProducerInterceptor
        message:
          max:
            bytes: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
        max:
          request:
            size: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
    consumer:
      group-id: kafka-connector-group
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      properties:
        interceptor:
          classes: io.opentracing.contrib.kafka.TracingConsumerInterceptor

kafka:
  consumer.threads: 3  
  auth-exception-retry-interval: 10
  topic:
    in: ai.flowx.easy-connector.in 
    out: ai.flowx.easy-connector.out 
spring:
  kafka:
    security.protocol: "SASL_PLAINTEXT"
    properties:
      sasl:
        mechanism: "OAUTHBEARER"
        jaas.config: "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required oauth.client.id=\"${KAFKA_OAUTH_CLIENT_ID:kafka}\" oauth.client.secret=\"${KAFKA_OAUTH_CLIENT_SECRET:kafka-secret}\"  oauth.token.endpoint.uri=\"${KAFKA_OAUTH_TOKEN_ENDPOINT_URI:kafka.auth.localhost}\" ;"
        login.callback.handler.class: io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler
```

## Setting up the connector locally

For detailed setup instructions, refer to the Setting Up FlowX.AI Quickstart Connector Readme:

> [card] [Readme file](https://github.com/flowx-ai/quickstart-connector/tree/feature/easy-start/docs)

Prerequisites:

* a terminal to clone the GitHub repository
* a code editor and IDE
* JDK version 11 or later (the quickstart-connector sample targets Java 11)
* the Docker Desktop app
* an internet browser

## Integrating a connector in FlowX.AI Designer

To integrate and utilize the connector within FlowX.AI Designer, follow these steps:

1. **Process Designer Configuration**: Utilize the designated communication nodes within the [Process Designer](../../building-blocks/process/process):

* [**Send Message Task**](../../building-blocks/node/message-send-received-task-node#send-message-task): Transmit a message to a topic monitored by the connector. Make sure you choose **Kafka Send Action** type.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/connector_topic.png)

* [**Receive Message Task**](../../building-blocks/node/message-send-received-task-node#receive-message-task): Await a message from the connector on a topic monitored by the engine.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/3.5/connector_topic_out.png)

2. **Connector Operations**: The connector identifies and processes the incoming message.
3. **Handling Response**: Upon receiving a response, the connector serializes and deposits the message onto the specified OUT topic.
4. **Engine Processing**: The engine detects the new message, captures the entire content, and stores it within its variables based on the configured variable settings.

You can check another example of a more complex connector by checking the following repository:

> [card] [Currency Exchange Example Connector](https://github.com/flowx-ai/quickstart-connector/tree/example/currency-exchange)


# Creating a Kafka consumer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/creating-a-kafka-consumer

This guide focuses on creating a **Kafka** consumer using Spring Boot.

Here are some tips, including the required configurations and code samples, to help you implement a Kafka consumer in Java.

## Required dependencies

Ensure that you have the following dependencies in your project:

```xml theme={"dark"}
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

<dependency>
    <groupId>io.strimzi</groupId>
    <artifactId>kafka-oauth-client</artifactId>
    <version>0.6.1</version>
</dependency>

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>2.5.1</version>
</dependency>

<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-kafka-client</artifactId>
    <version>0.1.13</version>
</dependency>
```

## Configuration

Ensure that you have the following configuration in your `application.yml` or `application.properties` file:

```yaml theme={"dark"}
spring:
  kafka:
    bootstrap-servers: localhost:9092
    security.protocol: "PLAINTEXT"
    consumer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
      properties:
        max:
          partition:
            fetch:
              bytes: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB

kafka:
  consumer:
    group-id: 
    ...
    threads:
    ...
```

## Code sample for a Kafka Listener

Here's an example of a Kafka listener method:

```java theme={"dark"}
@KafkaListener(topics = "TOPIC_NAME_HERE")
public void listen(ConsumerRecord<String, String> record) throws JsonProcessingException {

  SomeDTO request = objectMapper.readValue(record.value(), SomeDTO.class);

  // process received DTO
  // Make sure to replace *"TOPIC_NAME_HERE"* with the actual name of the Kafka topic you want to consume from. Additionally, ensure that you have the necessary serialization and deserialization logic based on your specific use case.
}
```


# Creating a Kafka producer
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/creating-a-kafka-producer

This guide focuses on creating a **Kafka** producer using Spring Boot.

Here are some tips, including the required configurations and code samples, to help you implement a Kafka producer in Java.

## Required dependencies

Ensure that you have the following dependencies in your project:

```xml theme={"dark"}
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

<dependency>
    <groupId>io.strimzi</groupId>
    <artifactId>kafka-oauth-client</artifactId>
    <version>0.6.1</version>
</dependency>

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>2.5.1</version>
</dependency>

<dependency>
    <groupId>io.opentracing.contrib</groupId>
    <artifactId>opentracing-kafka-client</artifactId>
    <version>0.1.13</version>
</dependency>
```

## Configuration

Ensure that you have the following configuration in your `application.yml` or `application.properties` file:

```yaml theme={"dark"}
spring:
  kafka:
    bootstrap-servers: localhost:9092
    security.protocol: "PLAINTEXT"
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      properties:
        message:
          max:
            bytes: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
        max:
          request:
            size: ${KAFKA_MESSAGE_MAX_BYTES:52428800} #50MB
```

## Code sample for a Kafka producer

> [!WARNING]
>
> Ensure that you have the necessary KafkaTemplate bean autowired in your producer class. The sendMessage method demonstrates how to send a message to a Kafka topic with the specified headers and payload. Make sure to include all the received Kafka headers in the response that is sent back to the **FlowX Engine**.

```java theme={"dark"}
private final KafkaTemplate<String, Object> kafkaTemplate;

public void sendMessage(String topic, Headers headers, Object payload) {
  ProducerRecord<String, Object> producerRecord = new ProducerRecord<>(topic, payload);
  // make sure to send all the received headers back to the FlowX Engine
  headers.forEach(header -> producerRecord.headers().add(header));
  kafkaTemplate.send(producerRecord);
}
```

## Kafka headers

### Understanding Kafka headers in FlowX Integration

When integrating with FlowX Engine via Kafka, headers play a crucial role in message routing and processing. It's essential to preserve and include all received headers in responses back to the FlowX Engine.

> [!NOTE]
>
> **Need help finding identifier values?** Check out the [Finding Identifiers and Parameters](./finding-identifiers-and-parameters) guide to learn where to locate workspace IDs, application IDs, build IDs, process instance UUIDs, and other identifiers in FlowX Designer.

### Important headers

| Header | Purpose | Consequences If Missing |
| - | - | - |
| `Fx-Organization-Id` | Organization UUID for the target deployment | **Message rejected** — consumers throw `MissingKafkaHeaderException` (non-retryable) |
| `Fx-Workspace-Id` | Identifies the workspace context for multi-tenant environments | Workspace isolation may be compromised; data queries may fail |
| `jwt` | JWT token for authenticated operations (process start, task actions) | Operations requiring user context will fail authorization |
| `fxContext` | Identifies the target process/subprocess in the hierarchy | Messages may be incorrectly routed or not processed |
| `Fx-AppId` | Identifies the application processing the message | Application context may be lost |
| `Fx-RootAppId` | Identifies the original application that initiated the process chain | Process origin tracking may be lost; important for complex process hierarchies |
| `Fx-Build-App-Version-Id` | Contains the application version identifier for data querying | Version-specific behaviors may be affected; data queries may fail |
| `processInstanceId`/`processInstanceUuid` | Primary keys for message correlation | Message correlation may fail |
| `Fx-ProcessName` | Required for cross-process communication | "Start another process via Kafka" functionality may break |

### The Fx-Organization-Id header

All FlowX Kafka consumers validate the `Fx-Organization-Id` header on every incoming message. Messages without it are **rejected immediately** with a non-retryable `MissingKafkaHeaderException`.

Set this header to the Organization UUID for your deployment. In self-hosted deployments, this is the same `ORGANIZATION_ID` value configured on all services.

```java theme={"dark"}
producerRecord.headers().add("Fx-Organization-Id",
    "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx".getBytes(StandardCharsets.UTF_8));
```

### The fxContext header explained

The `fxContext` header is particularly important for routing messages in architectures with embedded processes and subprocesses:

* For kafka-receive nodes in the root process: `fxContext = "main"`
* For an embedded subprocess with nodeId=4: `fxContext = "main:4"`
* For an embedded sub-subprocess with nodeId=12: `fxContext = "main:4:12"`

This hierarchical format ensures messages are delivered to their intended recipients within the process structure.

### Understanding Fx-RootAppId

The `Fx-RootAppId` header is used to track the originating application throughout the entire process chain. This is particularly important when:

* Multiple applications are involved in a workflow
* Processes spawn subprocesses across different components
* You need to trace a complete transaction back to its originating application

Unlike `Fx-AppId` which may change as a message passes through different components, `Fx-RootAppId` preserves the original initiator's identity.

### Best Practices

1. **Preserve All Headers**: Always include all received Kafka headers in responses to the FlowX Engine.
   ```java theme={"dark"}
   headers.forEach(header -> producerRecord.headers().add(header));
   ```


# Custom Agent node
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/custom-agent-node

Create AI agents with advanced capabilities using MCP tools to execute complex tasks in Integration Designer workflows.

## Overview

The **Custom Agent Node** is a specialized Integration Designer workflow node that enables you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.

![Custom Agent Node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca1.png)

## Key features

* **Tool Access**: Connect to one or more MCP servers to provide tools to the AI agent
* **Reasoning & Acting**: Built-in ReAct (Reasoning and Acting) model for intelligent decision-making
* **Multi-Step Execution**: Agent can use multiple tools in sequence to accomplish complex tasks
* **Structured Responses**: Define expected response schemas for consistent output
* **Execution Tracking**: Monitor tool usage and agent reasoning in console logs

> [!NOTE]
>
> Custom Agent nodes automatically apply the ReAct (Reasoning and Acting) model, which enables the AI agent to think through problems, decide which tools to use, and take actions based on the results.

## When to use custom agent nodes

Custom Agent nodes are ideal for scenarios where you need:

* **Dynamic Decision Making**: The agent determines which tools to use based on the task
* **External System Integration**: Access external APIs, databases, or services through MCP tools
* **Complex Multi-Step Operations**: Execute workflows that require multiple tool interactions
* **Autonomous Problem Solving**: Let the AI agent figure out how to accomplish a goal using available tools

### Example use cases

> [accordion] Customer Support Automation
>
> Create an agent that can:
>
> * Look up customer information from a CRM system
> * Check order status from an order management system
> * Generate personalized responses based on the gathered data
> * Create support tickets if needed

> [accordion] Data Analysis & Reporting
>
> Build an agent that:
>
> * Queries multiple databases for relevant data
> * Performs calculations and aggregations
> * Generates charts and visualizations
> * Produces formatted reports

> [accordion] Process Automation
>
> Design an agent that:
>
> * Monitors external systems for events
> * Validates data across multiple sources
> * Triggers actions in integrated systems
> * Handles exceptions and error cases

> [accordion] Integration Orchestration
>
> Implement an agent that:
>
> * Coordinates operations across multiple systems
> * Transforms data between different formats
> * Handles complex business logic
> * Manages transaction workflows

## Adding a Custom Agent node

To add a Custom Agent node to an Integration Designer workflow:

1. Open **Integration Designer** and navigate to your workflow
2. Click **Select Next Node** dropdown
3. Select **Custom Agent** from the available node types
4. Configure the node settings

![Add Custom Agent](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca2.png)

> [!NOTE]
>
> Custom Agent nodes are available in Integration Designer workflows, alongside other node types like REST API Call, Script, Condition, and Subworkflow nodes.

> [!TIP]
>
> The Custom Agent node is specifically designed for Integration Designer workflows. For BPMN process workflows, use the **Start Integration Workflow** action to invoke workflows that contain Custom Agent nodes.

## Configuring a Custom Agent node

After adding a Custom Agent node to your Integration Designer workflow, configure it through the node configuration panel:

**instructions** `string` *required*

The agent's role, tasks, and expected input/output. Sent to the LLM as the **System message** and **cached** between executions to reduce cost and latency, so `${variable}` placeholders are not allowed in this field — use **Context** for dynamic values.

The field is limited to 10,000 characters (SaaS · 5.11).&#x20;

Describe:

* The agent's role and the task it should accomplish
* Specific requirements or constraints
* Expected output format and edge-case handling

**Example:**

```
You are a customer order assistant. For each request, retrieve the
customer's recent order history and summarize it as a JSON object
with fields: customerId, totalOrders, totalValue, recentOrders.
If the customer is not found, return an error explaining the
customer ID is invalid.
```

**context** `string`

The per-execution prompt text, located inside the **Background** section of the node configuration panel. Supports `${variable}` placeholders for values from process data. Sent to the LLM as the **User message** on every execution and is **not** cached.

**Example:**

```
Customer ID: ${application.customerId}
Look back window: last 6 months
```

The **Background** section also exposes the Knowledge Base selector and the **Use only referenced values as input** toggle. In Chat Driven workflows, it additionally contains the **Use conversation memory** and **Use uploaded files** toggles.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

Selecting multiple Knowledge Bases makes each one available to the agent as its own retrieval tool, so the agent queries all of them. On earlier releases, only the first selected Knowledge Base is used.

**useUploadedFiles** `boolean`

Lets the agent search the files the end user attached during the conversation. In the Designer this is the **Use uploaded files** toggle, in the **Background** section, with the tooltip *When enabled, the agent can reference documents uploaded by the user during the conversation.*

**Default:** on. A Custom Agent created in a Chat Driven workflow starts with the toggle enabled, so uploaded files are searchable unless you turn it off.

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The toggle appears in Chat Driven workflows only. A Custom Agent in a standard workflow has no conversation to draw uploads from, so the toggle is not shown at all.

Attached files are extracted and indexed into a Knowledge Base scoped to the chat session, so this is a retrieval source rather than a way of handing a file to the model. For how uploads reach the session, see [File uploads](/5.9/ai-platform/chat-driven-workflows#file-uploads).

Turning the toggle on reveals a retrieval block of its own, separate from the settings on any Knowledge Base you attached:

| Setting | Description | Default |
| - | - | - |
| **Search Type** | How the uploaded content is searched: **Hybrid**, **Semantic** or **Keywords**. | `Hybrid` |
| **Number of Chunks** | How many chunks to retrieve per search. | `4` |
| **Min Relevance Score** | The relevance score, as a percentage, a chunk must reach to be returned. | `50` |
| **Use Re-rank** | Re-order the retrieved chunks by relevance before they reach the model. | `false` |

> [!NOTE]
>
> This block has no **Metadata Filters** control, unlike the one on an attached Knowledge Base. There is nothing to configure beyond the four settings above.

### Knowledge base retrieval settings

When one or more Knowledge Bases are attached, the **Background** section shows a retrieval block that applies to them:

| Setting | Description | Default |
| - | - | - |
| **Search Type** | How the Knowledge Bases are searched: **Hybrid**, **Semantic** or **Keywords**. | `Hybrid` |
| **Number of Chunks** | How many chunks each retrieval returns. | `4` |
| **Min Relevance Score** | The relevance score, as a percentage, a chunk must reach to be returned. | `50` |
| **Use Re-rank** | Re-order the retrieved chunks by relevance before they reach the model. | `false` |
| **Metadata Filters** | A metadata predicate applied to every retrieval, so the agent only searches the slice of the Knowledge Base you scope it to. | — |

#### Filtering options

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Filtering options** decides who writes that metadata filter:

* **Manual** (the default) applies the **Metadata Filters** you configure.
* **Agentic** lets the agent write its own filter at run time from the Knowledge Base's metadata keys. The **Metadata Filters** control disappears, and the panel notes `Agent builds the filter at runtime`.

> [!WARNING]
>
> **For per-tenant or per-run isolation, use Manual.** A model-authored filter that omits your scoping condition is a filter that does not isolate. Agentic filtering narrows retrieval for relevance; it is not an access-control mechanism.

### Agentic knowledge base search

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When a Custom Agent has one or more Knowledge Bases attached, you can turn on **Enable agentic knowledge base search** in the **Background** section. Agentic search is off by default; when it is off, each Knowledge Base is queried once with a plain single-pass retriever.

When agentic search is on, the agent breaks the question into sub-queries, searches and grades the results for relevance, and retries with reworded queries if the first pass finds nothing useful. It is better on complex questions, but it is slower and uses more model calls.

> [!NOTE]
>
> Agentic search is fail-open: it never returns worse results than the plain retriever would have. It also returns the same chunk metadata (chunk id, source id, and relevance score), so citations and telemetry are unchanged.

When **Enable agentic knowledge base search** is on, an **Additional controls** row appears with a **Settings** button. Open it to configure two controls in the settings dialog:

| Setting | Description | Default |
| - | - | - |
| **Max attempts** | How many retrieval passes the agent may run. The first pass always includes the original question; extra passes reword the query and retry only if earlier passes find nothing relevant. | `1` |
| **Subqueries per attempt** | How many sub-queries the agent generates per pass to search the Knowledge Base in parallel. | `3` |

> [!TIP]
>
> Start with the defaults. Raise **Max attempts** only for questions where a single pass regularly misses relevant content, since each extra pass adds model calls and latency.

![Agentic knowledge base search enabled, with Max attempts and Subqueries per attempt settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca_enable_agentic_search.png)

![Additional controls Settings dialog for agentic knowledge base search](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca_enable_agentic_additional_settings.png)

![The Add tool menu on the Custom Agent node, offering MCP Server, Workflow, Function, Web Search, and Built-in Tools](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/ca-add-tool-menu.png)

**mcpServers** `array`

One or more MCP servers whose tools will be available to the AI agent.

**Configuration:**

* Select from locally defined MCP servers
* Include MCP servers from dependency libraries
* Multiple selections allowed

> [!NOTE]
>
> Only enabled tools from the selected MCP servers will be available to the agent. Tools can be managed in the MCP server details page.

**workflowTools** `array`

FlowX workflows attached to the agent as callable tools. When the agent decides a task needs one of these workflows, it calls the workflow like any other tool, passing arguments that match the workflow's input parameters.

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Configuration:**

* Open the **Tools** section of the node configuration panel and add one or more workflows.
* For each attached workflow, fill in the **When should the agent use this workflow?** field. This text tells the agent what the workflow does and when to reach for it, so write it as guidance the model can act on. Maximum 2,000 characters.
* A workflow's input parameters (defined on its Start node) become the tool's arguments. The agent fills them in from its reasoning when it makes the call.

> [!NOTE]
>
> A workflow with no configured input parameters cannot be attached as a tool. Add at least one input parameter to the workflow's Start node to make it eligible. Ineligible workflows still appear in the list, greyed out and with the note `Workflows with no configured input parameters are not eligible to be used.`, so you can see what needs fixing rather than wondering why a workflow is missing.

Two kinds of workflow are left out of the list entirely:

| Not listed | Why |
| - | - |
| The workflow you are editing | An agent cannot attach its own workflow as one of its tools. |
| Chat Driven workflows | Only standard workflows can be attached. A conversational workflow is started by a chat session, not by a tool call. |

> [!NOTE]
>
> A Custom Agent can have at most **10** workflow tools attached.

![Tools section of a Custom Agent node with an attached workflow tool card showing its when-to-use text, next to built-in tool category cards](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca-workflow-tools.png)

**functionTools** `array`

Reusable functions attached to the agent as callable tools. Reach for one when the work is deterministic and you would rather the agent call your code than reason its way to the answer.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Configuration:**

* Open the **Tools** section of the node configuration panel, choose **Function**, and pick a function from the list.
* Fill in the **When should the agent use this function?** field. Maximum 2,000 characters.
* The function's input parameters become the tool's arguments. The agent fills them in from its reasoning when it makes the call.

Functions defined in the project and functions coming from libraries both appear in the list.

> [!NOTE]
>
> A function is eligible only if it is **typed on both sides**: it needs an input slice and an output slice, each with at least one field. Functions that are not typed do not appear in the list at all, and a project with none shows `No eligible functions available`.

**Write a description on the function itself.** As with a workflow tool, the text the agent reads comes from the function's own description, joined with the when-to-use text you enter here. A function with no description is still attachable, but the tool card warns `This function has no description. Use Go to to open the function and add one.` and the agent is left with only the when-to-use text to go on.

> [!NOTE]
>
> The ten-tool limit on this page counts **workflow** tools only. Attaching a function does not consume one of those slots.

![Add tool menu open on the Function option, listing a local reusable function marked as already added, with the attached function tool card and its when-to-use text below](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca-function-tools.png)

**builtinToolCategories** `array`

Gives the agent ready-made helper tools, chosen by category, so exact work such as date math or regex matching runs as code instead of being estimated by the model. In the Designer, select **Add tool** → **Built-in Tools** and toggle the categories you want. Each category row lists the tools it contains, and a card is shown per selected category.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Selection is opt-in and per node: the agent gets every tool in the categories you selected, and nothing is added implicitly. A node with no tools selected keeps the lighter non-agentic execution path.

| Category | Tools |
| - | - |
| **Math tools** | Calculator, Compare, Unit convert |
| **List tools** | Filter, Sort list, List aggregate |
| **Date tools** | Business days, Current date and time, Date difference, Date sequence, Date shift, Duration, Format date, Parse date, Period bounds, Timezone convert |
| **Text tools** | Fuzzy match, Regex extract, Regex match |
| **Web search** | Web search |

The categories and their contents are served by the AI Platform, so the list can grow without a Designer change. A category is grouping only: what the agent runs is the tools themselves.

> [!NOTE]
>
> **Before FlowX.AI 5.12**, built-in tools were two toggles introduced in 5.10: **Use Web Search Tool** and **Use built-in tools**, the latter enabling a fixed set of four (calculator, compare, sort, filter). Web search is now the **Web search** category rather than a separate mechanism. A node last saved with the old toggles needs no edit: **Use built-in tools** maps to the **Math tools** and **List tools** categories, and **Use Web Search Tool** to **Web search**. Once you save a category selection, it becomes the node's source of truth.

**responseSchema** `string` *required*

JSON Schema defining the expected structure of the agent's response.

This ensures the agent returns data in a consistent, predictable format that can be easily processed by subsequent nodes.

**Example Schema:**

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "customerInfo": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "email": { "type": "string" }
      }
    },
    "orderSummary": {
      "type": "object",
      "properties": {
        "totalOrders": { "type": "number" },
        "totalValue": { "type": "number" },
        "recentOrders": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "orderId": { "type": "string" },
              "date": { "type": "string" },
              "total": { "type": "number" }
            }
          }
        }
      }
    }
  },
  "required": ["customerInfo", "orderSummary"]
}
```

**responseKey** `string` *required*

The key in the process data where the agent's response will be stored.

**Example**: `agentResponse`, `customerData`, `analysisResults`

If the key already exists in the process data, it will be overwritten with the agent's response.

### Show Reasoning

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Turn on **Show Reasoning** to have the agent state its reasoning before it answers. The reasoning is captured in the run log and on the node's completion event, and it is then removed from the agent's output.

**Show Reasoning** does not change the structured response stored at the response key, and in Chat Driven workflows it does not change the reply shown to the user. It only surfaces the model's reasoning summary for review in the [Console Logs](#monitoring-agent-execution).

> [!NOTE]
>
> When the resolved model is a reasoning model, its reasoning summary is returned on the completion event regardless of this toggle. **Show Reasoning** additionally asks non-reasoning models to state their reasoning so it can be captured the same way.

![Show Reasoning toggle in the Custom Agent node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/custom_agent_node_show_reasioning_prop.png)

![Agent reasoning summary surfaced in the run log](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca_run_log_reasoning.png)

![Custom Agent AI Config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca3.png)

## How custom agent nodes execute

When a Custom Agent node is executed in an Integration Designer workflow, the following process occurs:

**1. Initialization**

The FlowX Engine sends the Instructions (as the System message), the Context (as the User message), and the available tools to the AI Service.

**2. Reasoning**

The AI agent analyzes the prompt and determines which tools it needs to use and in what order.

**3. Tool Execution**

The agent requests tool execution through the MCP server:

* Agent provides input parameters based on its reasoning
* MCP server executes the tool
* Results are returned to the agent

**4. Iteration**

The agent evaluates the results and decides whether to:

* Use additional tools to gather more information
* Process the data and formulate a response
* Handle any errors or unexpected results

**5. Response Generation**

Once the agent has all necessary information, it generates a structured response according to the defined schema.

**6. Data Storage**

The response is stored in the process data at the specified response key and the workflow continues.

> [!NOTE]
>
> The agent's reasoning process, tool invocations, and results are all logged in the console for debugging and monitoring purposes.

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

If the AI service can't be reached, the platform retries the Custom Agent node automatically. To see the defaults and change them from the node's **Settings** tab, see [What happens when an AI node can't reach its AI service?](/5.9/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).

## Monitoring agent execution

After running a workflow with a Custom Agent node, you can monitor its execution in the **Console Logs**:

### Node logs tab

The **Logs** tab displays:

* **Execution Status**: Success, failure, or in-progress
* **Duration**: Time taken to complete the node execution
* **Tool Usage Summary**: Quick overview of which tools are used during the execution
* **Instructions** and **User Message**: The prompt the node sent to the model
* **Response schema**: The schema the response must follow, when the node has one
* **Standard Output**: Agent's final response

![Agent Node Logs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca5.png)

### Tools tab

> [!NOTE]
>
> The **Tools** tab is only displayed when MCP tools have been used during execution.

For each tool invocation, you can see:

**Tool** `string`

The name of the tool that was invoked.

**Thoughts** `string`

The AI agent's reasoning for using this tool - why it decided this tool was necessary and what it hoped to accomplish.

**Example**: "I need to retrieve the customer's information from the CRM system to get their contact details and account status."

**Input** `object`

The parameters sent by the AI agent to the MCP tool.

**Example**:

```json theme={"dark"}
{
  "customerId": "CUST-12345",
  "includeOrders": true
}
```

**Output** `object`

The response received from the MCP tool for the AI agent to interpret.

**Example**:

```json theme={"dark"}
{
  "customer": {
    "id": "CUST-12345",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "tier": "premium"
  },
  "orders": [
    {
      "orderId": "ORD-001",
      "date": "2025-03-15",
      "total": 299.99
    }
  ]
}
```

![Agent Tools Tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ca4.png)

### Workflow-level logs

If the Custom Agent node is part of a larger workflow, tool usage information is also displayed at the workflow level:

1. Navigate to the workflow instance in Console Logs
2. View the workflow's **Tools** tab for an aggregated view of all tool usage
3. Drill down into specific nodes to see detailed tool execution

### How workflow tools run

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When the agent calls a workflow tool, FlowX starts a fresh top-level run of that workflow and passes the agent's arguments to it. The workflow runs to completion and its output is returned to the agent, which uses it to continue reasoning or to produce its final response.

Each workflow-tool call is recorded in the **Console Logs**. The call appears in the agent node's **Tools** tab, and the workflow run it triggered is linked by its workflow instance identifier so you can open the child run and inspect it.

> [!WARNING]
>
> **Give the workflow output parameters, not just input parameters.** Output parameters are configured in the **Output Parameters** tab of the workflow's Data Model, and only input parameters are checked when you attach the tool. A workflow with no output parameters attaches, runs, and reports the call as successful, but hands the agent an empty result. The agent then reasons on nothing and the cause is not obvious from the agent's own logs, so check the child run's output when a tool call looks successful but the answer ignores it.

![Run Logs panel on the agent node's Tools tab: a workflow-tool call whose name links to the child run, with the output JSON showing the child workflow instance identifiers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/ca-workflow-tool-console.png)

## Best practices

### Writing effective Instructions

> [!TIP]
>
> **Be Specific**: Clearly define what the agent should accomplish
>
> ```
> Good: "Retrieve customer order history for the last 6 months and calculate total spend"
> Avoid: "Get customer info"
> ```

> [!TIP]
>
> **Set Expectations**: Describe the expected output format
>
> ```
> "Return a summary with: customer name, total orders, and average order value"
> ```

> [!TIP]
>
> **Handle Edge Cases**: Include guidance for error scenarios
>
> ```
> "If the customer is not found, return an error message explaining that 
> the customer ID is invalid"
> ```

> [!WARNING]
>
> Don't put `${variable}` placeholders in Instructions — they're rejected by the form because Instructions is the cached System message. Put per-execution values in **Context** instead.

### Writing effective Context

> [!TIP]
>
> **Pass per-request values via placeholders**: keep the dynamic surface area small and named
>
> ```
> "For customer ${application.customerId}, check pending orders 
> from the ${application.orderSystem} system"
> ```

> [!TIP]
>
> **Use "Use only referenced values as input"** to send just the placeholders you reference, instead of the entire node input — narrows the model's context window and reduces token cost.

### Selecting MCP servers

> [!TIP]
>
> **Relevance**: Only include MCP servers whose tools are relevant to the agent's task

> [!TIP]
>
> **Minimize Scope**: Fewer tools = faster decision-making and more predictable behavior

> [!TIP]
>
> **Tool Availability**: Ensure required tools are enabled in the MCP server configuration

### Defining response schemas

> [!TIP]
>
> **Match Use Case**: Design the schema to match downstream data requirements

> [!TIP]
>
> **Required Fields**: Mark essential fields as required in the schema

> [!TIP]
>
> **Type Safety**: Use appropriate JSON Schema types for validation

> [!TIP]
>
> **Documentation**: Add descriptions to schema properties for clarity

## Prompt suggestions

When a Custom Agent node has **Send as chat reply** enabled, you can configure it to generate recommended follow-up prompts alongside its chat response. These appear as clickable suggestion chips in the chat UI, guiding users toward relevant next steps in the conversation.

### How it works

When prompt suggestions are enabled:

1. The agent generates both a text reply and a list of follow-up suggestions in a single response
2. Suggestions appear as clickable chips below the agent's reply in the chat UI
3. Clicking a suggestion sends its content as the user's next message, continuing the conversation
4. Suggestions are one-time use — they disappear after one is clicked

### Configuring prompt suggestions

Prompt suggestions are configured through a **satellite panel** that appears on the workflow canvas, connected to the Custom Agent node.

**1. Enable Send as chat reply**

In the Custom Agent node configuration, toggle **Send as chat reply** to **ON**. This is required for prompt suggestions to be available.

**2. Enable prompt suggestions**

Toggle **Prompt Suggestions** to **ON** in the Response section. A satellite panel appears on the canvas, connected to the Custom Agent node.

**3. Configure the satellite panel**

The satellite panel contains the following settings:

**instructions** `string` *required*

Instructions that guide the agent on what kind of follow-up prompts to generate.

**Default:** `Generate contextual follow-up replies the user is most likely to take next. Focus on actionable next steps, not clarifying questions.`

Supports `${paramName}` interpolation for dynamic values from the process data.

**maxSuggestions** `number`

Maximum number of suggestions the agent should generate per reply.

**Default:** `3` (range: 1-5)

**maxCharacters** `number`

Maximum character length for each suggestion label displayed in the chat UI.

**Default:** `120` (range: 10-200)

![Prompt Suggestions satellite panel on a Custom Agent node in a chat-driven workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/prompt_suggestions.png)

> [!TIP]
>
> The satellite panel is draggable on the canvas. Its position is saved automatically. When you move the parent Custom Agent node, the satellite moves with it.

### Response structure

When prompt suggestions are enabled, the response schema is auto-generated. The agent's output is stored at the configured response key as a structured object instead of a plain string:

```json theme={"dark"}
{
  "reply": "The Pro plan costs $49/month and includes unlimited agents...",
  "suggestions": [
    {
      "label": "Compare all plans",
      "content": "Show me a detailed comparison of the Starter, Pro, and Enterprise plans."
    },
    {
      "label": "How do I upgrade?",
      "content": "What are the steps to upgrade my current account to the Pro plan?"
    }
  ]
}
```

| Field | Description |
| - | - |
| `reply` | The agent's text response displayed in the chat |
| `suggestions[].label` | Short text displayed on the suggestion chip in the chat UI |
| `suggestions[].content` | Full prompt sent to the agent when the user clicks the suggestion. If omitted, `label` is used |

> [!NOTE]
>
> When prompt suggestions are enabled, the response schema is managed automatically — you cannot edit it manually. Turning off prompt suggestions restores the standard editable response schema.

### Chat behavior

* **Display**: Suggestions render as clickable chips below the agent's reply message
* **Click**: Clicking a chip displays the `label` as the user's message and sends the `content` to the agent as the next input
* **Memory**: The `content` (not the label) is stored in conversation memory for context continuity
* **Conversation restore**: When restoring a previous conversation, suggestion labels are shown for past user selections, but active suggestions on the last message are not re-displayed

***

## Limitations

| Constraint | Value | Details |
| - | - | - |
| **Maximum tool calls per execution** | `20` | The agent can make up to 20 tool calls in a single workflow execution. If the limit is reached, the execution stops and returns the last available result. Configurable via the `AGENT_BUILDER_MAX_TOOL_CALLS` environment variable on the AI platform service. |

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Two additional guardrails apply when an agent uses **workflow tools**:

* **Workflow-tool fan-out limit.** Across a single node run, the agent can make at most **10** workflow-tool calls in total. The budget is shared by every workflow tool attached to the agent, so it is a total rather than a per-tool allowance, and it is separate from the overall tool-call limit above. A call is counted when it is attempted, including one that then fails, so a retrying tool spends the budget. Going over the limit does not fail the node: the call is not dispatched and the agent is told to answer with what it already has, keeping its earlier tool results and reasoning. Configurable via the `WORKFLOW_TOOL_MAX_CALLS` environment variable on the AI platform service. Function tools do not draw on this budget.
* **Recursion depth limit.** A workflow tool can itself contain a Custom Agent that calls further workflow tools. These call chains are limited to a depth of **5**. The depth is fixed when a run starts and checked once, so a run that is too deep fails immediately at its Start node with `WORKFLOW_TOOL_RECURSION_LIMIT: Maximum workflow-tool recursion depth reached`. Only runs started by a workflow-tool call are counted, and the limit is separate from, and much lower than, the subworkflow depth limit. Configurable via the `FLOWX_WORKFLOW_MAXWORKFLOWTOOLDEPTH` environment variable on the Integration Designer service.

***

## Troubleshooting

> [accordion] Agent Not Using Expected Tools
>
> **Problem**: The agent doesn't use the tools you expected.
>
> **Possible Causes**:
>
> * Instructions don't clearly indicate the need for specific tools
> * Tools are disabled in the MCP server configuration
> * Agent found an alternative approach
>
> **Solutions**:
>
> * Review and refine the Instructions to be more specific about when each tool should be used
> * Check MCP server tool status (enabled/disabled)
> * Review agent reasoning in the Tools tab to understand its decision-making

> [accordion] Response Doesn't Match Schema
>
> **Problem**: The agent's response doesn't conform to the defined schema.
>
> **Possible Causes**:
>
> * Schema is too restrictive or doesn't match the prompt
> * Tools return unexpected data structures
> * Agent encountered errors during execution
>
> **Solutions**:
>
> * Verify schema matches what the prompt asks for
> * Test tools independently to verify their outputs
> * Review error logs for execution issues
> * Adjust schema or prompt to align better

> [accordion] Agent Execution Times Out
>
> **Problem**: The Custom Agent node takes too long to execute.
>
> **Possible Causes**:
>
> * Too many MCP servers/tools available
> * Complex multi-step operations
> * External systems responding slowly
>
> **Solutions**:
>
> * Limit MCP servers to only those needed
> * Break complex tasks into multiple simpler agent nodes
> * Optimize external system performance
> * Increase timeout configuration if appropriate

> [accordion] Tool Invocation Fails
>
> **Problem**: A tool invocation fails during agent execution.
>
> **Possible Causes**:
>
> * MCP server connection issues
> * Invalid parameters sent by agent
> * Tool authentication or permission errors
>
> **Solutions**:
>
> * Test MCP server connection in Integration Designer
> * Review tool input schema and agent's input in the Tools tab
> * Verify authentication credentials for the MCP server
> * Check tool-specific error messages in console logs

## Next steps

> [card] [MCP Integration Overview](./mcp-integration/mcp-integration-overview)
>
> Learn about MCP integration capabilities

> [card] [MCP Data Sources](./mcp-integration/adding-mcp-data-source)
>
> Add, configure, and manage MCP servers and tools

> [card] [Integration Designer](./integration-designer)
>
> Learn about Integration Designer workflows

## Related resources

> [card] [Start Integration Workflow](../../building-blocks/actions/start-integration-workflow)
>
> Learn how to call Integration Designer workflows from BPMN processes


# Db2 Database
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/db2-database

Connect to IBM Db2 databases as a data source in FlowX workflows and run SQL queries against them.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

Db2 is a relational data source type that lets you connect FlowX workflows to **IBM Db2 databases that your organization manages independently**. You configure a connection, save named SQL queries against the schema, and call those queries from workflows.

> [card] Connect to your Db2 instance
>
> Pick the Db2 product, then fill in a connection shaped for it

> [card] Schema-aware SQL editor
>
> Monaco editor with SQL syntax highlighting, schema-aware autocomplete, and a side panel that lists tables, columns, primary keys, and foreign keys

> [card] Test before you ship
>
> Run any saved query with sample parameters and inspect the response: table view for SELECT, affected-row count for INSERT / UPDATE / DELETE

> [card] Reusable in workflows
>
> Reference Db2 queries from the Database Operation node alongside other data sources

***

## Supported Db2 products

Db2 ships as separate products that differ in JDBC driver, URL form and listener port, so a connection begins by naming which one it targets.

| Db2 Product | Use for | Default port |
| - | - | - |
| **Db2 for i (IBM i)** | Db2 on IBM i, formerly AS/400 and iSeries. This is the default | `8471`, or `9471` with SSL |
| **Db2 LUW** | Db2 on Linux, UNIX and Windows | `50000`, or `50001` with SSL |

> [!WARNING]
>
> **Db2 for z/OS** appears in the **Db2 Product** list but is not implemented in this release. Selecting it and testing the connection fails with an explicit error naming the product, rather than silently connecting through another driver.

***

## Prerequisites

* A Db2 instance accessible from your FlowX deployment, running one of the supported products above
* A database user with the privileges your queries require, plus read access to the catalog views used for schema discovery
* Network connectivity between the `nosql-db-runner` service and the Db2 instance
* For SSL connections: appropriate certificates configured on the Db2 instance and trusted by the FlowX deployment
* For Db2 for i, a job or user profile whose CCSID lets character data come back as text. See [character data returned as binary](#character-data-returned-as-binary)

***

## Creating a Db2 data source

**1. Open Data Sources**

Navigate to **Integration Designer** → **Data Sources** in your project.

**2. Add a new data source**

Click the **+** button to open the **Add Data Source** dialog. In the **Databases** category, select **Db2 Database**.

**3. Pick the Db2 product**

Set **Db2 Product**. The rest of the form follows from this choice, and the **Port** field is prefilled with that product's standard port. Db2 for i is preselected.

**4. Configure the connection**

Fill in the connection fields:

| Field | Description |
| - | - |
| **Host** | Db2 server hostname or IP |
| **Port** | Listener port. Prefilled from the product and the SSL toggle, and editable |
| **Library** | Optional. The default library or schema for queries and discovery |
| **SSL Enabled** | Toggle SSL on or off for the connection |
| **Username** | Database username |
| **Password** | Database password |

Each field accepts configuration parameters for environment-specific values.

**5. Set the Db2 for i options**

On Db2 for i, set **Naming** and, if you use system naming, **Library List**. See [Naming and the library list](#naming-and-the-library-list).

**6. Test the connection**

Click **Test Connection and Rescan** to verify connectivity and refresh the schema cache.

> [!NOTE]
>
> The data source is created even if the connection test fails, so you can save partial configuration and resolve connectivity later. Return to the **Settings** tab and click **Test Connection and Rescan** once the issue is fixed.

**7. Save**

Click **Save** to create the data source.

> [!NOTE]
>
> Db2 does not assume a port. The prefilled value is the product's standard listener port, offered so you can see and change it, and a port is required for every vendor.

***

## Naming and the library list

On Db2 for i, **Naming** decides how a library is addressed in your SQL:

| Naming | Meaning |
| - | - |
| **SQL, dot notation (MYLIB.MYTABLE)** | Qualify a table with its library, using a dot |
| **System, resolved through the library list (MYTABLE)** | Refer to a table by name alone, resolved through the library list of the job running the query |

SQL naming is the default. When you choose system naming, set **Library List** to the libraries the job should search.

***

## Character data returned as binary

If character columns come back as unreadable bytes, the Db2 for i job is most likely running without a translation CCSID.

The durable fix is on the server: change the job or user profile CCSID so Db2 returns character data as text.

As a client-side workaround, turn on **Translate binary data as character data**.

> [!WARNING]
>
> This switch also decodes genuinely binary columns as text, which can corrupt their contents. Prefer fixing the CCSID on the server, and use the switch only where you know the affected columns hold text.

***

## Queries

Db2 queries are written and tested the same way as for other relational data sources. See [Oracle Database](./oracle-database#queries) for the SQL editor, testing, and stored-procedure behavior, which are shared across relational data source types.

***

## Using in workflows

Db2 queries are called from the existing **Database Operation** node in workflows.

**1. Add a Database Operation node**

On the workflow canvas, drag a **Database Operation** node onto the workspace.

**2. Select the data source and query**

In the node configuration panel, pick the Db2 data source. The query picker then lists only the queries saved on that data source.

**3. Map parameters**

Map workflow inputs to the query's bind parameters. Map the response (rows or `affectedRows`) to a workflow variable.

***

## Deployment

No new microservices are required. Db2 queries run inside the existing **`nosql-db-runner`** service, which bundles the Db2 JDBC driver. Each Db2 data source uses its own connection pool.

Ensure the `nosql-db-runner` service has network access to your Db2 instance. If Db2 is behind a firewall, configure the appropriate network rules.

Global pool and query defaults are shared with the other relational data source types. See [Oracle Database](./oracle-database#configuration-defaults) for the `nosql-db-runner` environment variables that set them.

### Per-data-source advanced settings

Each Db2 data source can override the global defaults from its **Advanced settings** panel, grouped into **Pool size**, **Pool lifecycle**, **Liveness**, **Performance**, and **Session**. Fields left empty inherit the global value:

| Setting | Description |
| - | - |
| **Min Pool Size** | Minimum number of connections kept open in the pool |
| **Max Pool Size** | Maximum number of connections in the pool |
| **Connection Timeout (ms)** | Maximum time to wait for a connection from the pool |
| **Unused Timeout (ms)** | Time an idle connection may sit in the pool before being retired |
| **Aged Timeout (ms)** | Maximum lifetime of a pooled connection |
| **Keep Alive** | Keep-alive probing for pooled connections |
| **Maintenance Frequency (ms)** | Interval between pool housekeeping runs. Editable only when **Keep Alive** is turned on |
| **Validate Connection String** | Query used to validate connections before use |
| **Response Timeout (ms)** | Per-query execution timeout for this data source |
| **Transaction Isolation** | Isolation level for the JDBC session. See below |
| **Read-Only Connection** | Whether connections open read-only |

> [!NOTE]
>
> **Prepared Statement Cache Size**, offered for some other relational data source types, does not appear for Db2 for i, which has no equivalent driver knob. It is available for Db2 LUW.

### Read-only connections on Db2 for i

On **Db2 for i**, connections open **read-only by default**. Reading from a live system is the common case, and a read-only connection keeps queries from consuming interactive capacity on writes that were not asked for.

Turn **Read-Only Connection** off on the data source if your queries need to write.

> [!NOTE]
>
> This default applies to Db2 for i only. Other relational data source types, Db2 LUW included, open read-write unless you say otherwise.

### Transaction isolation

**Transaction Isolation** sets the isolation level for the JDBC session:

| Option | |
| - | - |
| **None, no commit control** | The default |
| **Read Uncommitted** | |
| **Read Committed** | |
| **Repeatable Read** | |
| **Serializable** | |

The default is **None** because many Db2 for i tables are not journaled, and a table without a journal cannot take part in a transaction. Asking for any other level would make every query against such a table fail.

> [!NOTE]
>
> The isolation level is validated when you save the data source, not when a query first runs, so an unsupported combination surfaces at configuration time.

***

## Related resources

> [card] [Oracle Database](./oracle-database)
>
> Connect to independently managed Oracle databases

> [card] [PostgreSQL Database](./postgresql-database)
>
> Connect to independently managed PostgreSQL databases

> [card] [Integration Designer](./integration-designer)
>
> Overview of all data source types and workflow building

> [card] [NoSQL DB Runner setup](/5.9/setup-guides/nosql-db-runner)
>
> Deployment configuration for the database runner service


# Deep Research node
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/deep-research-node

Research a question across the open web with a budgeted, multi-pass agent, and file the cited result into a knowledge base.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

The **Deep Research** node investigates a question across the open web and files a cited report into a Knowledge Base. It is a budgeted, multi-pass agent: it plans the work, sends sub-researchers to search and read pages, grades what they bring back, and keeps going until the budget runs out or it has enough to report.

Unlike a [Custom Agent](./custom-agent-node), you do not write the method. The research prompt is built into the node, so you describe the subject and the node decides how to pursue it.

> [!NOTE]
>
> **The result always lands in a Knowledge Base.** Research is filed as text so retrieval nodes and other agents can reach it later. A rendered document is optional, and off by default.

***

## Adding a Deep Research node

Open your workflow in **Integration Designer**, then pick **Deep Research** from the **AI Agents** group in the left node panel, alongside **Custom Agent** and **Intent Classification Agent**.

***

## Configuring the node

**researchQuestion** `string` *required*

What the node should investigate. Bind workflow data with `${...}` placeholders, and add any standing guidance you want the node to follow.

**Example:**

```
Research ${topic}. Prefer primary sources.
```

There is no **Instructions** field on this node. The research method itself is built in, so this field carries the subject and your guidance, and nothing about how to search.

**researchDepth** `string`

How far the node fans out, chosen from four options.

**Default:** `Standard`

**Quick**, **Standard** and **Deep** apply budgets tuned by the platform, shown under the control as a summary such as `24 passes · 6 tool calls per sub-researcher`:

| Depth | Passes | Tool calls per sub-researcher |
| - | - | - |
| **Quick** | 12 | 4 |
| **Standard** | 24 | 6 |
| **Deep** | 48 | 10 |

**Custom** replaces the summary with two fields you set yourself:

| Field | What it controls |
| - | - |
| **Passes** | How many model calls the whole run may make. More passes let the node dig further, and cost more. |
| **Tool calls** | How many searches and page fetches each sub-researcher may make before it has to report back. |

> [!NOTE]
>
> **The number of sub-researchers is always the node's decision.** It is not a setting, on any depth.

**sources** `object`

Which parts of the open web the node may read. Leave both lists empty to allow anything.

Open **Manage lists** to edit them:

| List | Effect |
| - | - |
| **Allow only** | When set, the node may read **only** these domains. |
| **Deny** | Domains the node must never read, even when no allow list is set. |

> [!WARNING]
>
> **An allow list is a hard restriction. Nothing outside it is read.** An over-strict list yields no sources and fails the node.

Each list holds up to **50** entries and takes either mode:

* **Static** — type hostnames such as `reuters.com`. Anything that is not a hostname is rejected, and a duplicate is refused with `Already in the list`.
* **Dynamic** — bind a single `${...}` expression that resolves to the whole list, such as `${allowedDomains}`. Anything past the first 50 entries is ignored at runtime.

**storeResponse** `object` *required*

Where the report is indexed so retrieval nodes and other agents can reach it. All three fields are required.

| Field | Description | Default |
| - | - | - |
| **Knowledge Base** | The Knowledge Base to write into. **Store** stays locked until you pick one. | — |
| **Write mode** | **Append Content** adds to what is there, **Replace** overwrites it. | `Append Content` |
| **Store** | The store inside that Knowledge Base. | — |
| **Metadata values** | Optional metadata attached to what is written. Shows `No metadata values` when empty. | — |

> [!WARNING]
>
> **Check the store name.** An unrecognised name creates a new store rather than failing, so a typo produces a second store that looks empty instead of an error you can see.

**generateReport** `boolean`

Renders the research as a document in addition to filing it as text, and lets you choose the format and where it lands.

**Default:** `false`

The research is always filed as raw text for the Knowledge Base, so turning this off does not lose the result. Turn it on when someone needs a document to read.

**subResearcherModel** `string`

The model the sub-researchers use, set on the **AI Model** tab.

**Default:** `Same as orchestrator`

A cheaper model here is the usual way to make a wide fan-out affordable, since the sub-researchers do most of the calls.

**responseKey** `string` *required*

The key the node's output lands under in workflow state.

**Default:** `responseKey`

> [!NOTE]
>
> This node has no **Request timeout** setting. The shared timeout does not apply to it, so the control is not shown rather than shown and ignored.

***

## Related resources

> [card] [Custom Agent node](./custom-agent-node)
>
> Agents where you write the instructions and attach the tools

> [card] [Knowledge Base overview](./knowledge-base-integration/knowledge-base-overview)
>
> Where the research is filed, and how to retrieve it


# Email Sender
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/email-sender

Configure SMTP email connections as data sources to send emails directly from your FlowX.AI processes, including replies to received emails and new outbound messages.

> [!TIP]
>
> For Microsoft Outlook mailboxes, you can also use the [Microsoft Outlook](./microsoft-outlook-data-source) data source which connects via the MS Graph API and supports both reading and sending emails in a single data source.

## Overview

![Add Data Source - Email Sender](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_email_sender_selected.png)

Email Sender is a data source type in Integration Designer that provides SMTP connectivity for sending emails from FlowX.AI processes. Combined with the [Send Notification](../../building-blocks/actions/send-notification-action) action, it enables use cases such as:

* **Replying to incoming emails**: Continue email conversation threads started by an [Email Trigger](./email-trigger)
* **Sending outbound notifications**: Send emails directly from business processes
* **Customer communication**: Automated responses, confirmations, and follow-ups

> [!NOTE]
>
> Email Sender handles **outbound** SMTP connections for sending emails. For **inbound** IMAP connections that trigger processes when emails arrive, see [Email Trigger](./email-trigger).

***

## How it works

**1. Create an Email Sender data source**

Configure an SMTP connection in Integration Designer with your mail server credentials.

**2. Link to a notification template**

Select the Email Sender in a notification template's **Email Sender** field.

**3. Add a Send Notification action**

Add a [Send Notification](../../building-blocks/actions/send-notification-action) action to a process node and select the notification template.

**4. Send emails from your process**

When the action executes, the email is sent directly through the configured SMTP server.

***

## Creating an Email Sender data source

### Prerequisites

Before configuring an Email Sender, ensure you have:

* Access to Integration Designer with appropriate permissions
* SMTP server credentials (host, port, username, password)

### Access Integration Designer

Navigate to **FlowX Designer** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources** and click the **+** button to open the **Add Data Source** dialog.

### Configuration fields

Select **Email Sender** from the **Select Data Source** dropdown. The dialog displays all configuration fields in a single view:

**Protocol** `select` *required*

The email protocol to use. Only **SMTP** is available for Email Sender data sources.

**Server Host** `string` *required*

The hostname or IP address of your SMTP server.

**Placeholder:** "Enter Server Host or a Configuration Parameter"

**Examples:**

* `smtp.gmail.com`
* `smtp.office365.com`
* `mail.yourcompany.com`

> [!TIP]
>
> This field accepts configuration parameters. Use `${configParam}` syntax to reference environment-specific values.

**Port** `number` *required*

The port number for the SMTP connection. The default value updates automatically based on the SSL/TLS setting.

| SSL/TLS | Default Port |
| - | - |
| ON | `587` |
| OFF | `465` |

**User** `string` *required*

The email account username or full email address used for authentication.

**Placeholder:** "Enter Username or a Configuration Parameter"

> [!TIP]
>
> This field accepts configuration parameters for environment-specific credentials.

**Password** `string` *required*

The password or app-specific password for the email account.

**Placeholder:** "Enter Password or a Configuration Parameter"

> [!WARNING]
>
> For Gmail and other providers with two-factor authentication (2FA) enabled, you may need to generate an app-specific password.

> [!TIP]
>
> Store sensitive credentials in configuration parameters and reference them here using `${configParam}` syntax.

**SSL/TLS** `boolean`

Turn on secure connection using SSL/TLS encryption. **Recommended: on.**

> [!NOTE]
>
> Toggling SSL/TLS updates the default port value automatically.

### Test the connection

Click the **Test Connection** button to verify your settings before creating the data source:

| Result | Message | Action |
| - | - | - |
| ✅ Success | "Established connection" | Proceed to set name and create |
| ❌ Error | "Failed to establish connection" | Check credentials and server settings |

> [!NOTE]
>
> When you click **Create**, another authentication test is performed. If the test fails, you'll be redirected to the **Authorization** tab with an error message, but the Email Sender will still be created.

### Name and description

**Name** `string` *required*

A unique, descriptive name for the Email Sender.

**Placeholder:** "Add a name"

**Validation rules:**

* Required field
* Must be unique within the project
* Only letters, numbers, and these characters allowed: `[]`, `()`, `.`, `_`, `-`
* Minimum 3 characters, maximum 50 characters
* Cannot be "Default Server" (this is a reserved name)

> [!WARNING]
>
> The name "Default Server" is reserved for the environment-level default SMTP connection and cannot be used. If entered, you will see the error: *"Default Server" is a reserved name and cannot be used.*

**Description** `string`

Optional description explaining the purpose of this Email Sender.

**Placeholder:** "Add a description"

Click **Create** to save the Email Sender data source.

***

## Using with notification templates

After creating an Email Sender data source, you can link it to notification templates:

1. Open a notification template in **Notification Templates**
2. Set **Email Server** to **Predefined Email Connection**
3. In the **Email Sender** field, select your Email Sender data source (or leave as **Default Server** to use the environment-level default)

For more details, see [Managing notification templates](../core-extensions/content-management/notifications-plugin/managing-notification-templates).

***

## Troubleshooting

> [accordion] Connection test fails
>
> Common causes:
>
> * **Incorrect credentials**: Verify username and password
> * **Wrong port**: Use `587` for SMTP with SSL/TLS, `465` without
> * **Firewall**: Ensure outbound connections to the SMTP server are allowed
> * **2FA enabled**: Generate an app-specific password for the email account

> [accordion] Emails not being sent
>
> Check:
>
> 1. Is the Email Sender linked to a notification template?
> 2. Is the notification template's **Email Server** set to **Predefined Email Connection**?
> 3. Is the [Send Notification](../../building-blocks/actions/send-notification-action) action configured correctly on the process node?
> 4. Review process instance logs for error details

> [accordion] 'Default Server' name validation error
>
> The name "Default Server" is reserved for the environment-level default connection. Choose a different name for your Email Sender data source.

***

## Related resources

> [card] [Send Notification Action](../../building-blocks/actions/send-notification-action)
>
> Configure the Send Notification action to send emails from process nodes

> [card] [Email Trigger](./email-trigger)
>
> Configure IMAP connections to trigger processes from incoming emails

> [card] [Microsoft Outlook](./microsoft-outlook-data-source)
>
> Connect to Outlook via MS Graph API for reading and sending emails

> [card] [Notification Templates](../core-extensions/content-management/notifications-plugin/managing-notification-templates)
>
> Create and manage email and SMS notification templates

> [card] [Integration Designer](./integration-designer)
>
> Learn about data source types and integration workflows


# Email Trigger
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/email-trigger

Configure email-based process triggers to automatically start process instances when emails are received. Email Triggers connect to IMAP mail servers and monitor specific mailboxes to initiate workflows.

> [card]
>
> Email Trigger is a data source type that enables process instances to be automatically started when emails are received via IMAP, bringing event-driven automation to your email workflows.

> [!TIP]
>
> For Microsoft Outlook mailboxes, you can also use the [Microsoft Outlook](./microsoft-outlook-data-source) data source which connects via the MS Graph API and supports both reading and sending emails in a single data source.

### Email Trigger vs Microsoft Outlook

| | Email Trigger + Email Sender | Microsoft Outlook |
| - | - | - |
| **Protocol** | IMAP (read) + SMTP (send) | MS Graph API |
| **Authentication** | Username + password / app password | Azure AD (client credentials) |
| **Read + Send** | Two separate data sources | Single data source (Read & Send scope) |
| **Reply threading** | Manual — requires `Message-ID` header forwarding | Native — uses MS Graph message ID to maintain conversation threads |
| **Provider support** | Any IMAP/SMTP-compatible mail server | Microsoft 365 / Outlook only |
| **Best for** | Gmail, self-hosted mail servers, or mixed environments | Organizations using Microsoft 365 |

## Overview

Email Trigger is a data source type in Integration Designer that allows FlowX.AI processes to be triggered automatically when emails arrive in a monitored mailbox. This enables use cases such as:

* **Customer support automation**: Automatically create support tickets when emails arrive
* **Document processing**: Trigger document workflows when emails with attachments are received
* **Request handling**: Start approval processes based on incoming email requests
* **Notification workflows**: Process automated alerts from monitoring systems

***

## How it works

The Email Trigger system follows a straightforward flow:

**1. Configure Email Connection**

Set up an IMAP connection to your email server as a Data Source in Integration Designer.

**2. Link to Message Start Event (Start Catch Message)**

Connect the Email Trigger to a Message Start Event node in your process definition.

**3. Activate the Trigger**

Turn on monitoring from the Manage Triggers section in Runtime Settings.

**4. Process Incoming Emails**

When emails arrive, FlowX.AI automatically creates process instances with the email data.

SaaS · 5.12

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.12.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

On SaaS, an Email Trigger can also start an integration workflow: bind it on the workflow's **Start** node instead of a Message Start Event. The email arrives in the workflow's data model as `emailMessage`. For details, see [External triggers](./workflow-nodes-control-flow#external-triggers).&#x20;

> [!WARNING]
>
> **Email Triggers process only new emails**
>
> An Email Trigger only processes emails that arrive **after the trigger is activated for the first time**. Existing emails in the mailbox — whether read or unread — are never picked up retroactively.
>
> This applies to **reactivation as well**: if you deactivate and then reactivate a trigger, only emails that arrive **after the reactivation** are processed. Anything that landed in the mailbox during the inactive period is ignored.
>
> For IMAP triggers, the email must also still be **unread** in the monitored folder when the trigger picks it up.

***

## Creating an email trigger data source

### Prerequisites

Before configuring an Email Trigger, ensure you have:

* Access to Integration Designer with appropriate permissions
* IMAP server credentials (host, port, username, password)
* Knowledge of the mailbox folder to monitor (defaults to `INBOX` if not specified)

### Step 1: Access Integration Designer

**1. Navigate to Data Sources**

Navigate to **FlowX Designer** → **Workspaces** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources**

**2. Add a new data source**

Click **Add New Data Source**

**3. Select Email Trigger**

Select **Email Trigger** as the data source type

![Select Email Trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/email_trigger_mock.png)

### Step 2: Configure connection settings

Configure the IMAP connection with the following fields:

**Protocol** `string` *required*

The email protocol to use. Currently only **IMAP** is supported.

**Server Host** `string` *required*

The hostname or IP address of your IMAP server.

**Examples:**

* `imap.gmail.com`
* `outlook.office365.com`
* `mail.yourcompany.com`

> [!TIP]
>
> This field accepts configuration parameters. Use `${configParam}` syntax to reference environment-specific values.

**Port** `number` *required*

The port number for the IMAP connection. The default value updates automatically based on the SSL/TLS setting.

| SSL/TLS | Default Port |
| - | - |
| ON | `993` |
| OFF | `143` |

**User** `string` *required*

The email account username or full email address used for authentication.

> [!TIP]
>
> This field accepts configuration parameters for environment-specific credentials.

**Password** `string` *required*

The password or app-specific password for the email account.

> [!WARNING]
>
> For Gmail and other providers with 2FA enabled, you may need to generate an app-specific password.

> [!TIP]
>
> Store sensitive credentials in configuration parameters and reference them here using `${configParam}` syntax.

**SSL/TLS** `boolean`

Turn on secure connection using SSL/TLS encryption. **Recommended: ON.**

> [!NOTE]
>
> The SSL/TLS setting determines the default port value. Change this setting before adjusting the port.

### Step 3: Test the connection

Click the **Test Connection** button to verify your settings:

| Result | Message | Action |
| - | - | - |
| ✅ Success | "Established connection" | Proceed to save |
| ❌ Error | "Failed to establish connection" | Check credentials and server settings |

> [!NOTE]
>
> When you click **Create**, another authentication test is performed. If the test fails, you'll be redirected to the **Authorization** tab with an error message, but the Email Trigger will still be created.

### Step 4: Configure basic information

**Name** `string` *required*

A unique, descriptive name for the Email Trigger.

**Validation rules:**

* Required field
* Must be unique within the project
* Only letters, numbers, and these characters allowed: `[]`, `()`, `.`, `_`, `-`
* Minimum 3 characters, maximum 50 characters

**Description** `string`

Optional description explaining the purpose of this Email Trigger.

***

## Configuring email trigger settings

After creating the Email Trigger, configure monitoring and validation settings in the **Settings** tab.

### Filtering criteria

Define which emails should trigger processes:

**Mailbox Folder** `string` *required*

The mailbox folder to monitor for incoming emails.

**Default:** `INBOX`

**Examples:**

* `INBOX`
* `Support`
* `Orders/New`

> [!TIP]
>
> This field accepts configuration parameters for environment-specific folder names.

![Email Trigger Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/trigger_email_props.png)

### Trigger condition and attachment forwarding

Email Trigger validation uses a two-stage model:

1. **Start Process for** — which incoming emails should create a process instance.
2. **Save email attachments on process** — which attachments are forwarded into the process data.

If a trigger condition fails, the email is rejected and appears in the **Failed Triggers** section. If an attachment is filtered out by the forwarding mode, it is dropped silently and no Failed Trigger is recorded.

#### Start Process for

Select which incoming emails create a process instance.

**All incoming emails** `radio`

Start the process for all emails received in the selected mailbox folder.

**Only emails with attachments** `radio`

Start the process only when the email has at least one attachment. Emails without attachments are rejected with cause **No attachments**.

**Only emails with these attachment file types** `radio`

Start the process if at least one attachment matches the selected file types. The **Allowed File Types** multiselect activates. Emails without a matching attachment are rejected with cause **No matching file types**.

On 5.9.x, you select allowed types from the file type categories below.

| Type | Extensions |
| - | - |
| PDF | `.pdf` |
| DOCUMENT | `.doc`, `.docx`, `.txt` |
| IMAGE | `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff`, `.gif` |
| EXCEL | `.xls`, `.xlsx`, `.csv` |
| ZIP | `.zip` |

> [!NOTE]
>
> **Individual file extensions (SaaS · 5.11)**
>
> **Allowed File Types** and **Forward File Types** select individual file extensions instead of these categories. The categories no longer exist in the runtime, so the table above serves only as a reference for what each one used to cover.
>
> Selected extensions are stored as bare uppercase values without a leading dot (`PDF`, `DOCX`). Input is tolerant of case and of a leading dot, so `pdf` and `.pdf` resolve to the same extension. Existing triggers are migrated automatically, with each stored category expanded into the individual extensions it covered.

#### Save email attachments on process

Select which attachments from the email are passed into the process.

**All attachments** `radio`

Save all attachments from the email to the process instance.

**No attachments, send only email metadata** `radio`

No files are forwarded. Only email metadata (subject, body, sender, headers) reaches the process. The **Maximum File Size** field is disabled.

**Only these attachment file types** `radio`

Save only attachments that match the selected file types. The **Forward File Types** multiselect activates. Non-matching attachments are dropped silently (no Failed Trigger entry).

#### Limits

**Maximum File Count** `number`

Maximum number of attachments allowed per email. If exceeded, the email is rejected at the trigger level and appears in **Failed Triggers** with cause **File count exceeded**.

Leave empty for no limit.

**Maximum File Size (MB)** `number`

Maximum allowed size per attachment file, in megabytes. Applies across all forwarding strategies.

**Maximum allowed value:** 25 MB

Leave empty to apply no per-file size limit beyond the 25 MB hard cap.

> [!NOTE]
>
> **Triggers migrated from an earlier deployment**
>
> When a deployment is upgraded, existing triggers are set to **All incoming emails** + **All attachments**. The `Allowed File Types` value is preserved on the trigger but no longer filters anything until you switch the trigger condition or forwarding mode to one of the file-type options. Reopen each trigger after the upgrade to confirm the new settings match your intent.

> [!TIP]
>
> All fields in the Settings section accept configuration parameters, enabling environment-specific configurations.

### Polling interval

> [!NOTE]
>
> The Email Trigger polls for new emails every **30 seconds** by default. This interval can be configured at the environment level but is not user-configurable in the UI.

***

## Connecting to a Message Start Event

To use the Email Trigger, connect it to a **Message Start Event** node in your process definition.

### Configuring the Message Start Event

**1. Open your process definition**

Open your process definition in the Process Designer.

**2. Add a Message Start Event node**

Add a **Message Start Event** node.

**3. Configure the Process Trigger**

In the node configuration, locate the **Process Trigger** section:

**Trigger Type** `select` *required*

Select the trigger type:

* **Internal Throw Message** - Traditional message-based triggering
* **Email Trigger** - Email-based triggering
* **Incoming Webhook** - Webhook-based triggering (see the [Incoming Webhooks](./incoming-webhooks) data source)

**Email Trigger** `select` *required*

Select the Email Trigger data source to use. Only Email Triggers created in the current project are available.

> [!NOTE]
>
> Tooltip: "The email connection that will be triggered"

![Message Start Event with Email Trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/trigger_email_trigger_type_process.png)

> [!WARNING]
>
> To start monitoring, you must activate the trigger from **Manage Triggers** in **Runtime Settings**.
>
> ![Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/et5.png)

***

## Email data schema

When an email triggers a process, the following data structure is available in your process variables:

```json theme={"dark"}
{
  "emailMessage": {
    "subject": "Support Request #12345",
    "dateTime": "2026-01-15T10:30:00Z",
    "sender": "customer@example.com",
    "replyTo": ["replies@example.com"],
    "body": "Email body content...",
    "fileAttachments": [
      {
        "filePath": "email-attachments/proc-123/invoice.pdf",
        "downloadPath": "internal/files/uuid-456/download"
      }
    ],
    "headerParams": {
      "Message-ID": "<abc123@example.com>",
      ...
    }
  }
}
```

![Email data schema](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/et6.png)

### Schema fields

| Field | Type | Description |
| - | - | - |
| `subject` | string | Email subject line |
| `dateTime` | string (ISO 8601) | Timestamp when email was received |
| `sender` | string | Sender's email address |
| `replyTo` | array of strings | Reply-To addresses from the email header. Use these when sending a reply via the [Email Sender](./email-sender) or [Send Notification Action](../../building-blocks/actions/send-notification-action) |
| `body` | string | Email body content (plain text) |
| `attachments` | array | List of attachment metadata objects |
| `fileAttachments[].filePath` | string | Storage path in Document Plugin |
| `fileAttachments[].downloadPath` | string | API path to download the file |
| `headerParams.Message-ID` | string | Unique email message identifier |

### Attachment handling

Email attachments are automatically:

1. **Uploaded** to the Document Plugin as temporary files
2. **Copied** to permanent storage linked to the process instance
3. **Referenced** in the `fileAttachments` array with download paths

> [!WARNING]
>
> Attachment processing happens asynchronously. The file copy to permanent storage may complete after the process instance starts. If your process needs to access attachments immediately, consider adding a wait step. Upload retries on `InterruptedException` only — up to 3 attempts with exponential backoff totaling roughly 7 seconds. Other failures (network, document plugin errors) fail fast.

### Forwarding incoming attachments to a reply

The inbound `fileAttachments[]` shape (`filePath`, `downloadPath`) differs from the outbound shape expected by the [Send Notification action](../../building-blocks/actions/send-notification-action)'s **Attachments** field (`path`, `filename`).

To forward original attachments on a reply, transform `emailMessage.fileAttachments` into the Send Notification shape — typically in a Script node — and pass the result through a process variable:

```javascript theme={"dark"}
const replyAttachments = emailMessage.fileAttachments.map(f => ({
  path: f.filePath,
  filename: f.filePath.substring(f.filePath.lastIndexOf('/') + 1)
}));
```

Reference the resulting variable (for example, `${replyAttachments}`) in the Send Notification action's **Attachments** field.

***

## Managing triggers at runtime

### Accessing Manage Triggers

Navigate to **Runtime** → **Runtime Settings** → **Manage Triggers** to view and control all configured Email Triggers.

### Trigger list columns

| Column | Description |
| - | - |
| **State** | Current status: `Active` or `Deactivated` |
| **Trigger Type** | Always "Email Trigger" for email-based triggers |
| **Event Name** | The Email Trigger data source name |
| **Location** | Dependency app name, or `Local` for the current build |

### Activation requirements

For an Email Trigger to appear in Manage Triggers:

1. ✅ Email Trigger must be created as a Data Source
2. ✅ Email Trigger must be added to a Message Start Event node
3. ✅ The process must be part of a build in the **Active Policy**

> [!NOTE]
>
> When the Active Policy changes, Email Triggers retain their previous state (Active or Deactivated). If an Email Trigger is deleted from the latest build, it will be automatically deactivated.

> [!NOTE]
>
> All Email Trigger configuration changes and runtime actions (activation, deactivation, trigger events) are recorded in the audit trail for compliance and debugging purposes.

### Activating and deactivating triggers

Open the row menu (**⋮**) on the trigger and select **Activate** or **Deactivate**, then confirm. The **State** column updates to:

* **Active**: The system monitors the mailbox and creates process instances for incoming emails
* **Deactivated**: Monitoring is paused; no new process instances are created

***

## Testing with mock email content

When running a process from the build list, you can provide mock email content to simulate an incoming email trigger. This is useful for:

* Testing process logic before connecting to a live mailbox
* Verifying attachment handling and validation rules
* Debugging email-triggered workflows in development

### How to test with mock email

**1. Open the start process dialog**

Navigate to your process definition and click **Start Process**. If the process has a Message Start Event configured with an Email Trigger, the dialog displays a mock email form instead of the standard start parameters.

**2. Fill in the mock email fields**

Complete the form fields to simulate an incoming email:

| Field | Description |
| - | - |
| **Subject** | The email subject line |
| **Sender** | The sender email address |
| **Datetime** | When the email was "received" (defaults to the current date and time) |
| **Body** | The email body content |
| **Upload files** | Attach files to simulate email attachments. Accepted types: PDF, DOCUMENT (.doc, .docx, .txt), IMAGE (.png, .jpg, .jpeg, .tif, .tiff, .gif), EXCEL (.xls, .xlsx, .csv), ZIP (.zip), up to 25 MB |
| **Theme** | Select the theme to use for the process instance |

**3. Start the process**

Click **Start Process** to create a process instance using the mock email data, just as if a real email had been received.

> [!TIP]
>
> Use mock testing to validate your process handles edge cases — emails without attachments, emails with multiple Reply-To addresses, or emails with large body content.

***

## Handling failed triggers

When emails fail validation or processing errors occur, they appear in the **Failed Triggers** section.

### Accessing Failed Triggers

Navigate to **Runtime** → **Processes** → **Failed Triggers** to view failed email processing attempts.

### Failed Triggers list

| Column | Description |
| - | - |
| **Timestamp** | Date and time (localized) |
| **Trigger Type** | "Email Trigger" |
| **Trigger Name** | The Email Trigger data source name |
| **Cause Type** | Type of failure |
| **Context** | Additional info, e.g., "Sender: [customer@example.com](mailto:customer@example.com)" |

### Cause types

> [tab] File type not permitted
>
> **Message:** "The file `{filename}` could not be uploaded because it is not on the list of permitted file types."
>
> **Resolution:** Update the Allowed File Types in the Email Trigger settings, or ask the sender to use an accepted format.

> [tab] File size exceeded
>
> **Message:** "`{filename}` is too large. Maximum allowed: 25 MB"
>
> **Resolution:** The attachment exceeds the maximum file size limit. Ask the sender to reduce the file size or split into multiple emails.

> [tab] File count exceeded
>
> **Message:** "File limit exceeded. For this Email Trigger there is a limit of `{limit}` files per email."
>
> **Resolution:** The email contains more attachments than the trigger-level **Maximum File Count**. Ask the sender to split attachments across multiple emails, or raise the limit on the trigger.

> [tab] No attachments
>
> **Message:** "Email rejected: trigger requires emails with attachments, but none were found."
>
> **Resolution:** The trigger is configured to **Start Process for → Only emails with attachments**, but the incoming email had none. Ask the sender to include an attachment, or switch the trigger condition to **All incoming emails**.

> [tab] No matching file types
>
> **Message:** "Email rejected: no attachments matching the allowed file types `{types}` were found."
>
> **Resolution:** The trigger is configured to **Start Process for → Only emails with these attachment file types**, and none of the inbound attachments matched the **Allowed File Types** list. Ask the sender to use an accepted format or widen the allowed list.

> [tab] Unable to connect to email server
>
> **Message:** "We couldn't connect to your email server. This might be due to:
>
> * Incorrect server settings
> * No internet connection
> * Firewall blocking the connection
>
> Please check your connection and try again."
>
> **Resolution:** Verify the IMAP server settings in the Email Trigger Authorization tab and test the connection.

### Failed trigger details page

Click on a failed trigger row to open the dedicated details page, which displays:

| Field | Description |
| - | - |
| **Email Subject** | Subject line of the failed email |
| **Email Sender** | Sender address |
| **Timestamp** | When the email was received |
| **Cause Type** | Failure classification |
| **Error Details** | Detailed error description, displayed in a code editor for easy reading |
| **Build Status** | Whether the associated build is WIP or Committed |
| **Monitored Email Address** | The email account being monitored |
| **Monitored Inbox Folder** | The mailbox folder being monitored |
| **Process Definition** | Link to navigate to the process definition (requires config rights) |
| **Build** | Build identifier |
| **Project/Library** | Source project or library |
| **Build Created From** | Branch name |
| **Project/Library Version ID** | Version identifier |

Use the breadcrumb navigation at the top of the page to return to the failed triggers list.

> [!NOTE]
>
> If an email fails for multiple reasons, all failure causes are listed in the details view.

***

## Use cases

### Customer support ticket creation

**1. Configure Email Trigger**

Create an Email Trigger connected to your support email (e.g., `support@company.com`).

**2. Design the process**

Create a process that:

* Extracts customer information from the email
* Creates a ticket in your CRM
* Assigns to the appropriate team
* Sends an acknowledgment email

**3. Handle attachments**

Configure validation to accept relevant file types (PDF, images) and route attachments to your document management system.

### Document processing workflow

```
Email received with attachments
       ↓
Extract document metadata
       ↓
Classify document type (invoice, contract, etc.)
       ↓
Route to appropriate processing workflow
       ↓
Notify relevant stakeholders
```

***

## Best practices

> [card] Use configuration parameters
>
> Store server credentials and environment-specific settings in configuration parameters for easy management across environments.

> [card] Set appropriate validations
>
> Configure file type, size, and count limits to prevent processing of unwanted or malicious content.

> [card] Monitor failed triggers
>
> Regularly review the Failed Triggers section to identify issues with email processing.

> [card] Handle attachments asynchronously
>
> Remember that attachment processing is asynchronous. Design your process to handle potential delays in file availability.

> [!WARNING]
>
> **Security Note:** Email attachments are uploaded without virus scanning in the current implementation. Consider implementing additional security measures for sensitive environments.

***

## Troubleshooting

> [accordion] Email Trigger not appearing in Manage Triggers
>
> Ensure all requirements are met:
>
> 1. Email Trigger is created as a Data Source
> 2. Email Trigger is linked to a Message Start Event
> 3. The process is included in an Active Policy build

> [accordion] Connection test fails
>
> Common causes:
>
> * **Incorrect credentials**: Verify username and password
> * **Wrong port**: Use 993 for IMAP with SSL/TLS
> * **Firewall**: Ensure outbound connections to the mail server are allowed
> * **2FA enabled**: Generate an app-specific password for the email account

> [accordion] Emails not triggering processes
>
> Check:
>
> 1. Is the trigger **Active** in Manage Triggers?
> 2. Is the correct mailbox folder configured?
> 3. Do incoming emails pass validation rules?
> 4. Review Failed Triggers for error details

> [accordion] Attachments not available in process
>
> Attachment processing is asynchronous. If you need immediate access:
>
> 1. Add a wait step or message catch event after the start node
> 2. Verify the email passed file validation rules
> 3. Check Document Plugin connectivity

***

## Related documentation

> [card] [Cookbook: reconcile invoices](/5.9/cookbooks/invoice-reconciliation)
>
> See the Email Trigger in a full build: invoices arrive by email, AI extracts them, and exceptions go to a reviewer

> [card] [Email Sender](./email-sender)
>
> Configure SMTP connections to send and reply to emails from processes

> [card] [Microsoft Outlook](./microsoft-outlook-data-source)
>
> Connect to Outlook via MS Graph API for reading and sending emails

> [card] [Send Notification Action](../../building-blocks/actions/send-notification-action)
>
> Send emails and reply to received emails directly from process nodes

> [card] [Integration Designer](./integration-designer)
>
> Learn about other data source types and workflow creation

> [card] [Message Start Event](../../building-blocks/node/message-events/message-catch-start-event)
>
> Configure message-based process triggers

> [card] [Document Plugin](../core-extensions/content-management/documents-plugin/documents-plugin-overview)
>
> Manage files and attachments in FlowX.AI

> [card] [Configuration Parameters](../core-extensions/configuration-parameters)
>
> Use environment variables for flexible configurations


# File Storage
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/file-storage

Connect to external file storage (FTP, SFTP, S3, or Azure Blob) as a data source and move files in and out of FlowX from your workflows.

## Overview

File Storage is a data source type that lets you connect FlowX workflows to **external file storage your organization manages independently** — an FTP/SFTP server, an S3 (or S3-compatible) bucket, or an Azure Blob Storage container. You configure a connection, define named file operations against it, and call those operations from workflows.

> [!NOTE]
>
> Here, **external** means the storage is managed by your organization rather than by FlowX — it can still run entirely inside your own network. Point the **Host** at an in-cluster or on-prem FTP/SFTP server, or set the S3 **Endpoint URL** to a self-hosted MinIO bucket. FlowX provides the connector (`file-gateway`); you provide the storage.

> [card] Connect to your storage
>
> FTP, SFTP, S3 / S3-compatible, and Azure Blob Storage, each with its own connection and authorization settings

> [card] Define file operations
>
> Save named List, Download, Upload, Delete, and Move operations scoped to a root path

> [card] Browse and test
>
> Browse files in the configured storage and run any operation live before you use it

> [card] Reusable in workflows
>
> Reference file operations from a Data Source node alongside other data sources

***

## Prerequisites

* An external file storage system reachable from your FlowX deployment: an FTP/SFTP server, an S3 or S3-compatible bucket (AWS S3, MinIO, Wasabi, Backblaze B2, DigitalOcean Spaces, Cloudflare R2, and similar), or an Azure Blob Storage container.
* Credentials for the storage system with the permissions your operations require (read for List/Download, write for Upload/Move, delete for Delete).
* The **`file-gateway`** service deployed and able to reach both the storage system and the **`document-plugin`** service. See [File Gateway setup](/5.9/setup-guides/file-gateway-setup).

***

## Creating a File Storage data source

**1. Open Data Sources**

Navigate to **Integration Designer** → **Data Sources** in your project.

**2. Add a new data source**

Click the **+** button to open the **Add Data Source** dialog. In the **Files** category, select **External File Storage**.

**3. Configure the connection on the Settings tab**

New File Storage data sources open on the **Settings** tab, which has three sections:

* **Protocol** — select the storage type: **FTP**, **SFTP**, **S3 / S3-compatible**, or **Azure Blob Storage**.
* **Authorization** — choose an authorization type and supply credentials (see [Authorization](#authorization)).
* **General Settings** — set the **Root Path** of the storage (all operations are scoped under this prefix) and the protocol-specific connection fields (see [Connection settings](#connection-settings)).

**4. Test the connection**

Click **Test connection** in the Authorization section to verify the credentials and connectivity. A successful test reports **Established connection**.

**5. Save**

Click **Save** to create the data source. Until a valid connection is saved, the **Files** tab shows *File storage is not configured* and the **Settings** tab shows a *Settings are not configured* warning.

***

## Connection settings

The connection fields depend on the protocol you select.

### FTP

| Field | Description | Default |
| - | - | - |
| **Host** | FTP server hostname or IP (required) | — |
| **Port** | FTP port (required) | `21` |
| **Mode** | Connection mode: **Active** or **Passive** | `Passive` |
| **Encryption** | **None**, **FTPS (Explicit)**, or **FTPS (Implicit)** | `None` |

### SFTP

| Field | Description | Default |
| - | - | - |
| **Host** | SFTP server hostname or IP (required) | — |
| **Port** | SFTP port (required) | `22` |
| **Strict host-key checking** | **Accept new** or **Require fingerprint** | `Accept new` |
| **Known-hosts fingerprint** | Optional. The expected host-key fingerprint when requiring verification | — |

### S3 / S3-compatible

| Field | Description |
| - | - |
| **Endpoint URL** | Optional. Leave blank for AWS S3. Set this only for S3-compatible stores (MinIO, Wasabi, Backblaze B2, DigitalOcean Spaces, Cloudflare R2, Localstack, and similar). |
| **Region** | Required, including for non-AWS stores such as MinIO. |
| **Bucket** | Required. Fixed for the lifetime of this data source. |
| **Path-style access** | Off by default (virtual-host style, the AWS default). Turn **ON** for path-style addressing, required by MinIO, Localstack, and most self-hosted stores. Rule of thumb: AWS S3 → off; MinIO / self-hosted → on. |

### Azure Blob Storage

| Field | Description |
| - | - |
| **Storage account name** | Required. The Azure storage account. |
| **Container name** | Required. The blob container. |
| **Endpoint** | Optional. A custom endpoint, when not using the default Azure endpoint. |

***

## Authorization

The available authorization types depend on the protocol:

| Protocol | Authorization types |
| - | - |
| **FTP** | No authorization, or **Basic** (username / password) |
| **SFTP** | **Basic** (username / password), or **Private key** (username + private key) |
| **S3** | **Access key** (access key ID + secret access key) |
| **Azure Blob Storage** | **Access key** (storage account name + account key), or **Service account** (tenant ID + client ID + client secret) |

For Azure with **Access key**, the credential fields are labeled **Storage Account Name** and **Account Key**.

***

## Certificates

SaaS · 6.0

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 6.0.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A File Storage data source that connects over TLS has the same **Certificates** panel as a REST data source, in its **Settings**. **Trust** decides what the server's certificate is checked against (**System CAs**, **Custom CA**, or **None (insecure)**), and **Identity** is the client certificate FlowX presents when the server asks for one (mutual TLS). For every option and field, see [Trust and identity certificates](./data-sources-and-endpoints#trust-and-identity-certificates).

The panel appears only when the connection uses TLS:

| Protocol | Certificates panel shown when |
| - | - |
| **FTP** | **Encryption** is **FTPS (Explicit)** or **FTPS (Implicit)** |
| **S3 / S3-compatible** | **Endpoint URL** is blank (AWS S3), starts with `https://`, or is a configuration parameter such as `${s3Endpoint}` |
| **Azure Blob Storage** | **Endpoint** is blank, starts with `https://`, or is a configuration parameter |
| **SFTP** | Never. SFTP runs over SSH, not TLS: authenticate with **Private key** under [Authorization](#authorization) |

> [!NOTE]
>
> For File Storage, **Path** points to the filesystem of the `file-gateway` service, not to your local machine. On SaaS deployments, use **Inline**.

An SFTP data source with **Private key** authorization that kept its SSH key in the earlier certificate settings has the key moved to the authorization automatically.

***

## File operations

Each File Storage data source holds a list of named operations, managed on the **Operations** tab. Click to add an operation, choose its **Operation type**, and give it a **Name** and optional **Description**. Each operation opens a details page where you configure its parameters, and a test modal runs it live against the storage.

| Operation | What it does |
| - | - |
| **List** | Lists file metadata inside the root path. Use **File Path** to target a subfolder and **File pattern** to filter results. |
| **Download** | Copies a file from external storage into Document Plugin internal storage for further processing. |
| **Upload** | Copies a file from Document Plugin internal storage to external storage. |
| **Delete** | Removes files from the external storage. |
| **Move** | Moves a file within the external storage. Move can also rename the file. |

### Operation parameters

| Operation | Parameters |
| - | - |
| **List** | **File Path** (optional subfolder), **File pattern** (optional wildcard, e.g. `*.csv`, `report-*.xml`, `2026/*.pdf`), **Recursive** toggle |
| **Download** | **Source File Path** (required), **Document folder** (required), **Document type** (optional), **File name override** (optional) |
| **Upload** | **Destination file path** (required), **Document plugin path** (required) |
| **Delete** | **File Path** (required) |
| **Move** | **Source File Path** (required), **Destination path** (required) |

> [!NOTE]
>
> Download and Upload exchange files with the **Document Plugin** internal storage rather than the workflow directly — Download brings an external file into FlowX, Upload sends a stored document out.

### What do the Download parameters mean?

A Download operation reads one file from the external storage and saves a copy in Document Plugin internal storage.

| Parameter | Description |
| - | - |
| **Source File Path** | Path of the file in the external storage, relative to the data source root path. The root path is added in front of it. |
| **Document folder** | Name of the Document Plugin folder the copy is saved in. |
| **Document type** | Optional document type assigned to the saved copy in Document Plugin. |
| **File name override** | Optional file name for the saved copy. When empty, the copy keeps the source file name. |

The operation output includes a `documentPluginMetadata` object with these keys:

| Key | Description |
| - | - |
| `filePath` | Storage path of the saved copy. Map it to the **Document plugin path** of an Upload operation, or to any step that reads the file from Document Plugin. |
| `downloadPath` | Download path of the saved copy in Document Plugin. |
| `fileEntryUuid` | ID of the Document Plugin file entry. |
| `fileName` | Name of the source file in the external storage. |
| `byteCount` | Size of the source file in bytes. |

### How do I get a file into Document Plugin storage before an Upload?

An Upload operation can only send a file that is already in Document Plugin internal storage. Its **Document plugin path** parameter takes the file's storage path, the `filePath` value returned when the file was saved. Each of these saves a file to Document Plugin storage and returns a `filePath`:

| Source of the file | How to save it | Where to read `filePath` |
| - | - | - |
| An external API response, including Base64 content in JSON | Turn on **Save Files** on the REST endpoint and set **File Destination** to **Document Plugin**. See [Receiving files](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#receiving-files-endpoint-response-configuration). | The workflow node output |
| Another external file storage | Run a File Storage **Download** operation | The `filePath` key inside `documentPluginMetadata` in the operation output |
| A file a user uploads in a process | Add an [Upload File action](/5.9/docs/building-blocks/actions/upload-file-action) to a user task | The Document Plugin reply. See [Receiving the reply](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document#receiving-the-reply). |

Map that `filePath` to **Document plugin path**, and set **Destination file path** to the path in the external storage, relative to the data source root path.

> [!NOTE]
>
> Pass the storage path, not a preview or download URL. If a business rule replaced `filePath` with a preview URL, keep the original storage path in a separate key for the Upload.

### Browsing files

The **Files** tab is a file browser for the configured storage. Once a valid connection is saved, you can navigate the storage, copy file paths, and preview files. The browser is available only after the connection is configured on the Settings tab.

***

## Using in workflows

File operations are called from a **Data Source node** in workflows.

**1. Add a Data Source node**

On the workflow canvas, add a **Data Source** node and select your File Storage data source.

**2. Select the operation**

Pick one of the operations defined on that data source. The picker lists only the operations saved on the selected data source.

**3. Map parameters**

Map workflow inputs to the operation's parameters, and map the operation result (file list, document reference, or status) to a workflow variable.

***

## Deployment

File Storage operations run in the **`file-gateway`** service.

* **`file-gateway`** is MongoDB-backed and connects to the **`document-plugin`** service to exchange files; Download and Upload operations move files between external storage and document-plugin internal storage.
* It does **not** require Redis.
* It authenticates using the **`flowx-file-gateway-sa`** service account.
* The default maximum file size for operations is **1 GiB**.

For deployment configuration, see [File Gateway setup](/5.9/setup-guides/file-gateway-setup).

***

## Troubleshooting

> [accordion] Error: There was an error while calling file-gateway service
>
> This message means the `file-gateway` service returned an error response that Integration Designer doesn't pass through. The actual status and response body are in the **integration-designer** logs, on a line that starts with `File gateway execute operation failed with status`. Check that line first.
>
> For a Download operation, a common cause is Document Plugin rejecting the copy of the file, so also check that the `document-plugin` service is running and that `file-gateway` can reach it.
>
> Problems with the external storage itself don't produce this message. A missing file, a file over the 1 GiB size limit, credentials the storage rejects, or an unreachable storage server make the operation fail with the storage's own error message instead.

> [accordion] Error: Cannot invoke FileStorageConfig.getProtocol() because cfg is null
>
> The File Storage data source has no saved connection settings, so the operation has no storage to connect to. Open the data source, fill in the **Settings** tab, click **Test connection**, and save. Until a valid connection is saved, the **Settings** tab shows a *Settings are not configured* warning.

***

## Related resources

> [card] [File Gateway setup](/5.9/setup-guides/file-gateway-setup)
>
> Deployment configuration for the file-gateway service

> [card] [Integration Designer](./integration-designer)
>
> Overview of all data source types and workflow building

> [card] [Oracle Database](./oracle-database)
>
> Connect to externally managed Oracle databases

> [card] [Unmanaged MongoDB](./unmanaged-mongodb)
>
> Connect to externally managed MongoDB instances


# Incoming Webhooks
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/incoming-webhooks

Start a FlowX process from an external HTTP POST, or resume a running process instance and inject the POST payload into it. Secured with API keys, event-driven, no polling.

## What is an incoming webhook?

A webhook is an HTTP endpoint that an external system calls to notify FlowX when an event happens. Instead of FlowX polling for updates, the third-party system sends an HTTP POST the moment something occurs — and FlowX starts a process in response. Common uses include receiving events from payment processors, CRMs, ERPs, or CI/CD pipelines.

## Overview

Incoming Webhooks allow external systems to trigger FlowX processes by sending HTTP POST requests to a generated URL. Each webhook gets a unique, cryptographically secure API key for authentication — no IMAP setup, no polling, just a direct HTTP call.

Use webhooks when you need to:

* **Receive events from third-party platforms** (payment processors, CRMs, ERPs) that support outbound webhooks
* **Trigger processes from CI/CD pipelines** or internal tools via simple HTTP calls
* **Replace polling-based integrations** with event-driven process starts

> [card] API key authentication
>
> Each webhook gets a unique, secure API key included in the URL

> [card] JSON payload forwarding
>
> Webhook body and HTTP headers are forwarded to the process instance as variables

> [card] Manage Triggers UI
>
> Activate, deactivate, and manage webhook URLs from Runtime Settings

> [card] Zero configuration
>
> No server settings needed — create the data source, connect to a process, activate

***

## How it works

A webhook does one of two things, depending on the **Webhook Behavior** you choose when you create the data source.

> [tab] Start a process
>
> Each POST creates a **new** process instance.
>
> **1. Create an Incoming Webhook data source**
>
> In Integration Designer, create a new data source and select **Incoming Webhook**. Provide a name and optional description, and leave **Webhook Behavior** on **Start a Process/Workflow**. No connection settings are required.
>
> **2. Connect to a Message Start Event**
>
> In your process definition, add a **Message Start Event** node. Set the **Trigger Type** to **Incoming Webhook** and select your webhook data source.
>
> **3. Commit and activate**
>
> Commit the version, then go to **Runtime** → **Manage Triggers**. The webhook appears as **Deactivated**. Click the action menu and select **Activate**.
>
> **4. Get the webhook URL**
>
> From the trigger's action menu, select **Get URL**. Copy the generated URL (includes the API key as a query parameter) and configure it in your external system.
>
> **5. External system sends POST request**
>
> When the external system POSTs JSON to the webhook URL, the `webhook-gateway` service validates the API key, publishes the event to Kafka, and the process engine starts a new process instance.

> [tab] Resume a waiting process
>
> Each POST resumes an **already-running** instance and hands it the payload. Use this to push data into a process in flight — for example, sending updated credit data into a loan application that is parked waiting on an external system.
>
> **1. Create an Incoming Webhook data source**
>
> In Integration Designer, create a new data source and select **Incoming Webhook**. Set **Webhook Behavior** to **Resume a Waiting Process**, then set **Webhook Correlation Key** to the path in the incoming payload that identifies the instance to resume (for example, `application.applicationId`).
>
> **2. Connect to a Message Catch Intermediate Event**
>
> In your process definition, add a **Webhook Trigger** message catch event where the process should pause. Select the webhook as its **Data Source**, then set **Process Correlation Key** to the matching process variable and **Process Key** to where the incoming data should land.
>
> **3. Commit and activate**
>
> Commit the version, then activate the webhook in **Runtime** → **Manage Triggers**, exactly as for a start webhook.
>
> **4. Get the webhook URL**
>
> From the trigger's action menu, select **Get URL** and configure that URL in your external system.
>
> **5. External system sends POST request**
>
> When the external system POSTs JSON, `webhook-gateway` validates the API key, reads the correlation value at the **Webhook Correlation Key** path, and publishes a message event. The process engine matches it against instances waiting on that catch event and resumes the one whose **Process Correlation Key** holds the same value, storing the incoming data at the **Process Key**.
>
> > [!NOTE]
> >
> > If no waiting instance matches the correlation value, or the correlation path does not resolve in the payload, the request is rejected and nothing is resumed. See [Error handling](#error-handling).

***

## Creating a webhook data source

**1. Navigate to Data Sources**

Go to **Integrations** → **Data Sources** in your project.

**2. Add a new data source**

Click **+** and select **Incoming Webhook** as the data source type.

**3. Configure basic information**

| Field | Required | Description |
| - | - | - |
| **Name** | Yes | A unique name for the webhook (3–50 characters, letters, numbers, `[] () . _ -`) |
| **Description** | No | Purpose or context for this webhook |
| **Webhook Behavior** | Yes | Whether each POST starts a new process or resumes a waiting one. See [Webhook Behavior](#webhook-behavior). |
| **Webhook Correlation Key** | Only for **Resume a Waiting Process** | Dotted path into the incoming payload whose value identifies which waiting process instance to resume. See [Webhook Correlation Key path syntax](#webhook-correlation-key-path-syntax). |

**4. Create**

Click **Create**. The webhook data source is ready to be connected to a process.

![Incoming Webhook data source page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_data_source_created.png)

> [!NOTE]
>
> Incoming Webhooks accept POST requests with JSON payloads (max 1 MB). No connection settings, credentials, or polling configuration is needed.

> [!WARNING]
>
> When deleting a webhook data source, deactivate it first and remove the URL from any third-party systems that use it. Deleting the webhook in FlowX does not notify external systems — they will continue sending requests that return errors.

***

## Connecting to a Message Catch Event

A webhook can drive two kinds of message catch events:

| Event placement | Webhook Behavior (API value) | What the webhook does |
| - | - | - |
| **Message Start Event** | `START_PROCESS` | Creates a new process instance on each POST |
| **Message Catch Intermediate Event** | `RESUME_PROCESS` | Resumes a process instance waiting on the catch |

You choose which of the two a webhook does when you create the data source, using the **Webhook Behavior** setting.

### Webhook Behavior

On the webhook data source's **Settings** tab, **Webhook Behavior** offers two options:

| Option | What it does | Attach the webhook to |
| - | - | - |
| **Start a Process/Workflow** | Creates a new process instance on each POST, with the webhook payload as its input. On SaaS (5.12), it can start an integration workflow instead; see [Activating a webhook](#activating-a-webhook). | A **Message Start Event** node |
| **Resume a Waiting Process** | Resumes a process instance already waiting on a catch event, using a correlation key. | A **Message Catch Intermediate Event** node |

![Webhook data source Settings tab with Resume a Waiting Process selected and a correlation key set](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/api_key_only.png)

Selecting **Resume a Waiting Process** enables **Webhook Correlation Key** in the **Process Connection** panel and marks it required. It is the dotted path into the incoming payload whose value identifies the instance to resume, and it is defined once on the data source rather than per node. Under **Start a Process/Workflow** the field is greyed out, and saving a value there is rejected.

> [!WARNING]
>
> **Webhook Behavior is immutable after the first save.** Once the webhook data source has been saved, the setting is locked in the Designer and the API rejects a change to it. To switch a webhook between starting and resuming, create a new webhook data source.

### On a Message Start Event

**1. Open your process definition**

Open the process in the Process Designer.

**2. Add a Message Start Event node**

Drag a **Message Start Event** from the Start Events section of the node palette onto the canvas.

**3. Configure the Process Trigger**

In the node configuration panel, under **Process Trigger**:

* Set **Trigger Type** to **Incoming Webhook**
* In **Select Webhook**, choose your webhook data source from the dropdown

**4. Save the node**

Click **Save** to persist the configuration.

![Message Start Event configured with Incoming Webhook trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_configured.png)

### On a Message Catch Intermediate Event

Use a webhook on an intermediate catch event to resume a process instance that is waiting for an external signal — for example, a callback from a third-party document scanner, a downstream system confirming an enqueued job, or a manual operator action delivered over HTTP.

**1. Add a Webhook Trigger intermediate catch event**

From the node palette, drag a **Webhook Trigger** message catch event onto the canvas at the point where the process should pause.

**2. Select the webhook data source**

In the node configuration panel, set the **Data Source** dropdown to the webhook that drives this catch event. The **Webhook Correlation Key** field appears as read-only and shows the correlation key defined on the webhook itself — included here so you can see how incoming requests are matched.

**3. Set the Process Correlation Key**

Set **Process Correlation Key** to a business or process variable from the data model (for example, `applicationId`, `orderId`). At runtime this value is matched against the incoming payload to identify which waiting process instance to resume.

**4. Set the Process Key**

Set **Process Key** to the data-model path where the incoming webhook data should be stored when the catch fires. The value stored there is the same `{ dateTime, payload, headers }` envelope described in [Webhook payload](#webhook-payload), not the bare POST body — read the request body from `payload` underneath it.

**5. Save the node**

Click **Save** to persist the configuration.

> [!NOTE]
>
> The same webhook data source can drive multiple intermediate catch events as long as the Process Correlation Key disambiguates which instance to resume. Without a valid correlation match, the inbound request is rejected.

#### Webhook Correlation Key path syntax

The **Webhook Correlation Key** points into the incoming webhook payload. It uses dotted-path notation and supports array indices in square brackets, so deeply nested provider payloads can be addressed directly.

| Path pattern | Resolves to |
| - | - |
| `application.applicationId` | `payload.application.applicationId` |
| `entry[0].changes[0].value.messages[0].text.body` | The first inbound text-message body in a Meta WhatsApp webhook payload |
| `data.orders[2].id` | The `id` of the third element of the `orders` array |

> [!NOTE]
>
> Array index syntax (`field[N]`) is supported in correlation keys, so the canonical Meta WhatsApp resume path works as-is. Paths like `entry[0]...` resolve directly and no longer need to be flattened in the producer before posting.

If the path does not resolve in an incoming request (missing field, index out of bounds, null leaf), the request is rejected and the waiting process instance is not resumed.

***

## Managing webhooks at runtime

### Activating a webhook

For a webhook to appear in Manage Triggers:

1. The webhook data source must be created
2. The webhook must be connected to a node that can carry a webhook trigger — a **Message Start Event** or a **Message Catch Intermediate Event**. On SaaS (5.12), a **Start a Process/Workflow** webhook can also be bound to the Start node of an integration workflow; see [External triggers](./workflow-nodes-control-flow#external-triggers)&#x20;
3. The version must be committed

Navigate to **Runtime** → **Manage Triggers** to view and control webhooks:

| Column | Description |
| - | - |
| **State** | `Active` or `Deactivated` |
| **Trigger Type** | `Webhook` |
| **Event Name** | The webhook data source name |
| **Location** | `Local`, or the library project the webhook comes from |

Use the action menu (three-dot icon) to:

* **Activate** — Start accepting webhook requests
* **Deactivate** — Stop accepting requests. The API key and URL are preserved, so you can reactivate later without reconfiguring external systems.
* **Get URL** — View and copy the webhook URL with API key

> [!TIP]
>
> A single webhook can trigger multiple processes — add the same webhook data source to Message Start Event nodes in different process definitions. Each incoming request starts all connected processes. On SaaS (5.12), integration workflows bound to the same webhook are started too.

![Manage Triggers showing active webhook](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)

***

### Webhook URL and API key

When you activate a webhook and select **Get URL**, a modal displays:

* **Webhook URL** — The full URL including the API key as a `flowxApiKey` query parameter
* **Copy button** — Copies the URL to clipboard
* **Reset API Key** — Generates a new API key (invalidates the previous URL)

![Webhook URL modal with API key and Reset button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_url_modal.png)

**URL format:**

```
https://{services-host}/webhooks/incoming/{orgId}/{workspaceId}/{appId}/{resourceDefinitionId}?flowxApiKey={apiKey}
```

A webhook with the **Slack** or **Meta** provider adds the provider as a lowercase path segment (`slack` or `meta`) after `/webhooks/incoming/`:

```
https://{services-host}/webhooks/incoming/{provider}/{orgId}/{workspaceId}/{appId}/{resourceDefinitionId}?flowxApiKey={apiKey}
```

> [!WARNING]
>
> Resetting the API key creates a new webhook URL. Update the URL in all third-party systems that use it, or they will receive `401 Unauthorized` errors.

***

## Provider adapters

When a webhook is created in the Integration Designer, the **Settings** tab now exposes:

* **Provider** — the dropdown offers three options. Like Webhook Behavior, the provider is a one-time selection: once saved it becomes immutable, and you create a new webhook to switch.

  | Dropdown label | API value | Signature validation |
  | - | - | - |
  | **Generic (API Key Only)** | `GENERIC` | None |
  | **Slack** | `SLACK` | `X-Slack-Signature` HMAC-SHA256 |
  | **Meta (WhatsApp, Messenger, Instagram, Threads)** | `META` | `X-Hub-Signature-256` HMAC-SHA256 |

* **Provider secret** — the signing secret(s) obtained from the provider. Stored encrypted; can be rotated independently of the API key. The field is labelled per provider and only appears once a provider that needs it is selected: **Signing Secret** for Slack, **Verify token** plus **App secret** for Meta. `Generic (API Key Only)` has no secret field.

![Provider dropdown on the webhook Settings tab, listing Generic, Slack and Meta](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/webhook_providers.png)

For SaaS-hosted secrets you can also reference a config parameter using the `${configParam.name}` placeholder syntax — placeholders are resolved at registration time the same way LLM provider secrets are.

### Generic provider

The default. No signature validation is performed; authentication relies on the FlowX `flowxApiKey` and HTTPS. Use `GENERIC` for systems that do not sign their webhooks, or where signature validation is handled inside the process via a business-rule action on the raw headers.

Slack and Meta are the only channels with dedicated adapters. Any other platform that can deliver an HTTPS POST — Microsoft Teams, Viber, Telegram, or an internal system — connects through the Generic provider; if that platform signs its requests, validate the signature inside the process from the raw headers.

### Slack provider

Performs Slack's standard signature check on every incoming request:

| Header | Purpose |
| - | - |
| `X-Slack-Signature` | HMAC-SHA256 signature of the version, timestamp, and raw body, prefixed with `v0=`. |
| `X-Slack-Request-Timestamp` | Unix timestamp; rejected if more than **5 minutes** out of skew. |

Requests that fail signature verification, that miss either header, or that arrive without a configured signing secret are rejected with `401 Unauthorized`.

Slack's URL-verification handshake is handled automatically — a `url_verification` POST with a `challenge` field receives the `challenge` value back as JSON, before the request is forwarded to the process. No process configuration is required for the handshake.

Selecting **Slack** adds a required **Signing Secret** field to the Settings tab. Find the value in your Slack app under **Basic Information** → **App Credentials** → **Signing Secret**. You can paste it directly or reference a config parameter.

![Webhook Settings tab with the Slack provider selected, showing the Signing Secret field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/slack_provider.png)

### Meta provider

Covers WhatsApp, Messenger, Instagram, and Threads. Meta-platform integrations share a common subscription model and signature scheme; the `META` adapter handles both.

Meta webhooks require **two** secrets, configured as masked inputs in the **Settings** panel:

| Field | Purpose | Where to find it |
| - | - | - |
| **Verify token** | Used during the GET URL-verification handshake. | Any random string you choose. Paste the same value in **Meta** → **Webhooks** → **Verify token**. |
| **App secret** | Verifies the `X-Hub-Signature-256` HMAC on every POST. | **Meta Developer Dashboard** → your App → **Settings** → **Basic** → **App Secret**. |

Both values are stored together as a JSON-packed pair in the existing webhook secret field, encrypted at rest. Both are required; saving without either returns `WEBHOOK_META_SECRETS_REQUIRED 400`.

![Webhook Settings tab with the Meta provider selected, showing the Verify token and App secret fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/meta_provider.png)

**GET URL verification.** Meta sends a GET request with `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge` query parameters when you save the webhook in the Meta App configuration. The gateway:

1. Confirms `hub.mode=subscribe`.
2. Confirms `hub.challenge` is present.
3. Compares the received `hub.verify_token` to the configured **Verify token** using a constant-time check.
4. Echoes the `hub.challenge` value back as plain text on success.

A mismatch or missing parameter returns `403 Forbidden` — Meta does not finalise the subscription.

**POST signature verification.** Every POST is signed by Meta with an `X-Hub-Signature-256` header (`sha256=<hex>`). The gateway recomputes the HMAC-SHA256 of the raw body with the configured **App secret** and rejects mismatches with `401 Unauthorized`.

### Path / provider mismatch

If a request hits the URL for one provider but the webhook registration is configured with a different provider, the gateway returns `400 Bad Request`. Always use the URL shown in the **Get URL** modal — it carries the correct provider segment for the registration.

***

## Webhook payload

When an external system POSTs to the webhook URL, the following data is available in the process instance:

```json theme={"dark"}
{
  "webhookMessage": {
    "dateTime": "2026-03-23T15:30:00Z",
    "payload": {
      "orderId": "ORD-12345",
      "status": "completed",
      "amount": 299.99
    },
    "headers": {
      "Content-Type": ["application/json"],
      "X-Custom-Header": ["value"]
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `dateTime` | string (ISO 8601) | Ingestion time at FlowX — when `webhook-gateway` received the request. If the provider includes its own event timestamp in the payload, use that for the original event time. |
| `payload` | object or string | The POST request body (parsed as JSON if valid, raw string otherwise) |
| `headers` | object | All HTTP headers from the incoming request. Each header maps to an array of values — access the first value with `webhookMessage.headers.Content-Type[0]` in process variables |

![webhookMessage paramValue on a process instance](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhookExample.png)

> [!NOTE]
>
> `headers` includes values added by the FlowX ingress in addition to what the caller sent — typically `X-Forwarded-For`, `X-Real-IP`, `X-Request-ID`, `X-Forwarded-Host`, `X-Forwarded-Proto`. These are useful for logging and tracing but should not be confused with provider-supplied headers.

> [!NOTE]
>
> The maximum payload size is **1 MB**. Requests exceeding this limit are rejected.

### How do I start a webhook-triggered process manually?

To test a process whose only start node is a webhook Message Start Event without sending a real request, start it manually (for example, run it from the Designer) and put `payload` and `headers` at the root of the start parameters. FlowX wraps them in `webhookMessage` for you:

```json theme={"dark"}
{
  "payload": {
    "orderId": "ORD-12345",
    "status": "completed"
  },
  "headers": {
    "X-Custom-Header": ["value"]
  }
}
```

![Start Process dialog in the Designer with payload and headers at the root of the start parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/webhook-manual-start-params.png)

The process instance then receives `webhookMessage.payload`, `webhookMessage.headers` and `webhookMessage.dateTime`, the same structure a real webhook request produces.

* FlowX reads only `payload` and `headers` and drops every other key, including a `webhookMessage` object you build yourself: wrapping the start parameters in `webhookMessage` leaves `webhookMessage.payload` and `webhookMessage.headers` set to `null`.
* `dateTime` is always the time the process starts. You can't pass your own value.
* `headers` must be an object. FlowX copies its values as you send them. A real request carries each header as an array of values, so pass arrays (`["value"]`) if your business rules read `webhookMessage.headers.X-Custom-Header[0]`.
* A manual start skips the webhook gateway, so the API key and provider signature checks don't run. It tests the process logic only. To test the integration end to end, POST to the webhook URL.

If the process also has a regular Start node, a manual start uses that node and the start parameters reach the instance as you send them, without the `webhookMessage` wrapper.

***

## Authentication

Webhook authentication uses API keys:

* Each webhook registration gets a unique **32-byte, base64-URL-encoded** API key
* The key is passed as the `flowxApiKey` query parameter in the webhook URL
* Validation uses **constant-time comparison** to prevent timing attacks
* Invalid or missing keys return `401 Unauthorized`
* Inactive webhooks return `404 Not Found`

> [!WARNING]
>
> FlowX validates provider signatures only for [providers with a built-in adapter](#provider-adapters). For the `GENERIC` provider — and for any third-party signature scheme without a dedicated adapter (`Stripe-Signature`, GitHub's `X-Hub-Signature-256` outside the Meta family, etc.) — signature headers are forwarded to the process in `webhookMessage.headers` but no validation is performed. Authentication for `GENERIC` registrations relies on the FlowX API key and HTTPS. The raw request body is not preserved after JSON parsing, which makes in-process HMAC verification impractical — for unsupported providers, design integrations assuming API key + HTTPS is the only authentication layer, or request a built-in adapter.

***

## Error handling

| HTTP Status | Cause | Resolution |
| - | - | - |
| `200 OK` | Webhook accepted and published to Kafka | — |
| `400 Bad Request` | The URL's provider segment doesn't match the webhook's **Provider** | Use the URL from the **Get URL** modal. A body that isn't valid JSON is accepted and reaches the process as a raw string in `payload` |
| `401 Unauthorized` | Invalid or missing API key | Check the `flowxApiKey` parameter matches the active webhook URL |
| `404 Not Found` | Webhook registration not found or deactivated | Verify the webhook is activated in Manage Triggers |
| `413 Payload Too Large` | Request body exceeds 1 MB | Reduce the payload size or split into multiple requests |
| `500 Internal Server Error` | Processing error | Check webhook-gateway service logs |

Failed webhook events appear in **Runtime** → **Processes** → **Failed Triggers** with details about the failure cause.

***

## Best practices

> [card] Use HTTPS
>
> Always use HTTPS URLs in production to protect the API key in transit

> [card] Validate payloads in your process
>
> Add validation logic in your process to handle unexpected or malformed payloads gracefully

> [card] Monitor Failed Triggers
>
> Regularly check the Failed Triggers section for webhook processing errors

> [card] Rotate keys periodically
>
> Use the Reset API Key feature to rotate webhook credentials, then update the URL in external systems

***

## Related resources

> [card] [Message Start Event](../../building-blocks/node/message-events/message-catch-start-event)
>
> Configure message-based and webhook process triggers

> [card] [Message Catch Intermediate Event](../../building-blocks/node/message-events/message-intermediate/message-catch-intermediate-event)
>
> Pause a process until an internal message or an external webhook resumes it

> [card] [Email Trigger](./email-trigger)
>
> Start processes from incoming emails via IMAP

> [card] [Integration Designer](./integration-designer)
>
> Build integration workflows and manage data sources

> [card] [Webhook Gateway setup](/5.9/setup-guides/webhook-gateway-setup)
>
> Deploy and configure the webhook-gateway microservice


# Microsoft Outlook
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source

Connect to Microsoft Outlook via MS Graph API to read and send emails directly from your FlowX.AI processes, using Azure AD authentication for native Outlook integration.

## Overview

Microsoft Outlook is a data source type in Integration Designer that provides native Outlook connectivity through the Microsoft Graph API. Unlike the [Email Trigger](./email-trigger) (IMAP) and [Email Sender](./email-sender) (SMTP) data sources, Microsoft Outlook uses Azure AD authentication and the MS Graph API for a unified read and send experience.

Use cases include:

* **Email-triggered workflows**: Automatically start processes when emails arrive in an Outlook mailbox
* **Customer communication**: Send emails and replies directly from business processes
* **Document processing**: Trigger workflows when emails with attachments are received
* **Unified inbox management**: Read and send from the same data source configuration

> [!NOTE]
>
> Microsoft Outlook supports three scope modes:
>
> * **Read Emails** — monitor a mailbox and trigger processes
> * **Send Emails** — send emails from processes via notification templates
> * **Read & Send Emails** — both capabilities in a single data source

### When to use Microsoft Outlook vs Email Trigger / Email Sender

FlowX.AI offers two ways to connect to email: **Microsoft Outlook** (MS Graph API) and **Email Trigger** / **Email Sender** (IMAP/SMTP). Choose based on your mail provider and requirements.

| | Microsoft Outlook | Email Trigger + Email Sender |
| - | - | - |
| **Protocol** | MS Graph API | IMAP (read) + SMTP (send) |
| **Authentication** | Azure AD (client credentials) | Username + password / app password |
| **Read + Send** | Single data source (Read & Send scope) | Two separate data sources |
| **Reply threading** | Native — uses MS Graph message ID to maintain conversation threads | Manual — requires `Message-ID` header forwarding |
| **Provider support** | Microsoft 365 / Outlook only | Any IMAP/SMTP-compatible mail server |
| **Best for** | Organizations using Microsoft 365 | Gmail, self-hosted mail servers, or mixed environments |

> [!TIP]
>
> If your organization uses Microsoft 365, the Outlook data source is the recommended approach. It simplifies configuration by combining read and send into a single data source with Azure AD authentication.

***

## How it works

**1. Register an Azure AD app**

Create an app registration in Azure AD with the required MS Graph permissions for your scope.

**2. Create a Microsoft Outlook data source**

Configure the connection in Integration Designer with your Azure AD credentials and select the desired scope.

**3. Connect to processes**

For **Read** scope: link to a Message Start Event node and activate from Manage Triggers.
For **Send** scope: link to a notification template and use the Send Notification action.

**4. Process emails**

FlowX.AI monitors the mailbox (Read) or sends emails (Send) through the MS Graph API.

***

## Creating a Microsoft Outlook data source

![Add Data Source - Microsoft Outlook](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_outlook_form.png)

### Prerequisites

Before configuring a Microsoft Outlook data source, ensure you have:

* Access to Integration Designer with appropriate permissions
* An Azure AD app registration with the required MS Graph API permissions:

| Scope | Required permissions (any one) |
| - | - |
| **Read Emails** | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
| **Send Emails** | `Mail.Send` or `Mail.ReadWrite` |
| **Read & Send Emails** | One read permission + one send permission |

* Azure AD credentials: **Tenant ID**, **Client ID**, and a **Client Secret** (or, starting with 5.9.1, a **certificate** — see [Step 2](#step-2-configure-authentication))

> [!WARNING]
>
> MS Graph permissions must be configured as **Application permissions** (not Delegated) in your Azure AD app registration, since the connection uses client credentials flow.

### Step 1: Access Integration Designer

1. Navigate to **FlowX Designer** → **Your workspace** → **Projects** → **Your project** → **Integrations** → **Data Sources**
2. Click the **+** button to open the **Add Data Source** dialog
3. Select **Microsoft Outlook** as the data source type

### Step 2: Configure authentication

**Tenant ID** `string` *required*

The Azure AD tenant ID for your organization.

> [!TIP]
>
> This field accepts configuration parameters. Use `${configParam}` syntax to reference environment-specific values.

**Client ID** `string` *required*

The application (client) ID from your Azure AD app registration.

> [!TIP]
>
> This field accepts configuration parameters for environment-specific credentials.

**Client Secret** `string` *required*

The client secret generated in your Azure AD app registration.

> [!TIP]
>
> Store sensitive credentials in configuration parameters and reference them here using `${configParam}` syntax.

**Use certificate** `boolean`

**Available starting with FlowX.AI 5.9.1.** Authenticate to Microsoft Graph with a certificate instead of a client secret. When you turn this **ON**, the **Client Secret** above is ignored and the certificate is used to authenticate. Configure:

* **Certificate type** — how the certificate is provided: **Base64** (paste the encoded certificate content) or **Path** (a path to the certificate file reachable by the integration).
* **Format** — the certificate format: **PEM** or **PKCS12**.
* **Password** — the certificate password. Required only when the format is **PKCS12**.

> [!TIP]
>
> This field accepts configuration parameters. Store the certificate content or path and the password in configuration parameters and reference them with `${configParam}` syntax.

### Step 3: Test the connection

Click the **Test Connection** button to verify your Azure AD credentials:

| Result | Message | Action |
| - | - | - |
| ✅ Success | "Established connection" | Proceed to configure scope |
| ❌ Error | "Failed to establish connection" | Check Azure AD credentials and permissions |

> [!NOTE]
>
> The data source can be created even if the test connection fails. If the test fails on creation, you will be redirected to the **Authorization** tab with a failed connection message instead of the **Settings** page.

### Step 4: Configure scope and email

**Scope** `select` *required*

The email capabilities for this data source:

| Option | Description |
| - | - |
| **Read Emails** | Monitor a mailbox and trigger processes when emails arrive |
| **Send Emails** | Send emails from processes via notification templates |
| **Read & Send Emails** | Both read and send capabilities |

**Email Address** `string` *required*

The email address of the mailbox to monitor or send from.

**Validation:** Must be a valid email format.

> [!TIP]
>
> This field accepts configuration parameters for environment-specific values.

### Step 5: Name and description

**Name** `string` *required*

A unique, descriptive name for the Microsoft Outlook data source.

**Validation rules:**

* Required field
* Must be unique within the project
* Only letters, numbers, and these characters allowed: `[]`, `()`, `.`, `_`, `-`
* Minimum 3 characters, maximum 50 characters

**Description** `string`

Optional description explaining the purpose of this data source.

Click **Create** to save the data source.

***

## Settings page

After creating the data source, configure monitoring and validation settings in the **Settings** tab. The available settings depend on the selected scope.

![Microsoft Outlook - Settings tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ms_outlook_settings.png)

### Read scope settings

For data sources with **Read Emails** or **Read & Send Emails** scope:

#### Filtering criteria

**Email Address** `string`

The email address that will be monitored. Editable after creation.

> [!TIP]
>
> This field accepts configuration parameters.

**Mailbox Folder** `string`

The mailbox folder to monitor for incoming emails.

**Default:** `Inbox`

Supported well-known folder names:

* `Inbox`, `Sent`, `Drafts`, `Deleted`, `Junk`, `Archive`, `Outbox`

> [!TIP]
>
> This field accepts configuration parameters for environment-specific folder names.

**Scope** `string`

Displays the scope selected during creation. This field is read-only.

#### Attachment validations

Toggle **ON** the **Add validations to Attachments** option to configure validation rules for incoming email attachments.

![Microsoft Outlook - Attachment validations](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ms_outlook_validations.png)

> [!NOTE]
>
> If any validation fails, the email will not be processed and a warning will appear in the **Failed Triggers** section in Runtime.

**Allowed File Types** `array`

Restrict which attachment file types are accepted:

On 5.9.x, you select allowed types from the file type categories below.

| Type | Extensions |
| - | - |
| PDF | `.pdf` |
| DOCUMENT | `.doc`, `.docx`, `.txt` |
| IMAGE | `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff`, `.gif` |
| EXCEL | `.xls`, `.xlsx`, `.csv` |
| ZIP | `.zip` |

> [!NOTE]
>
> Leave empty to accept all file types.

> [!NOTE]
>
> **Individual file extensions (SaaS · 5.11)**
>
> **Allowed File Types** selects individual file extensions instead of these categories. The categories no longer exist in the runtime, so the table above serves only as a reference for what each one used to cover.
>
> Selected extensions are stored as bare uppercase values without a leading dot (`PDF`, `DOCX`). Input is tolerant of case and of a leading dot, and existing data sources are migrated automatically, with each stored category expanded into the individual extensions it covered.

**Maximum File Size** `number`

Maximum allowed size per attachment file.

**Maximum:** 25 MB

**Maximum File Count** `number`

Maximum number of attachments allowed per email.

> [!TIP]
>
> All fields in the Settings section accept configuration parameters, enabling environment-specific configurations.

### Send scope settings

For data sources with **Send Emails** scope only, the Settings tab shows a simplified view:

**Email Address** `string`

The email address used as the sender ("From" address) for outgoing emails.

**Scope** `string`

Displays the scope selected during creation. This field is read-only.

> [!NOTE]
>
> Send-only data sources do not display the **Mailbox Folder** or **Attachment Validations** fields, since those apply only to the Read scope. Sent emails are automatically saved to the Sent Items folder.

***

## Authorization page

![Microsoft Outlook - Authorization tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ms_outlook_auth.png)

The **Authorization** tab displays the Azure AD credentials and allows you to update them or re-test the connection:

**Tenant ID** `string` *required*

Azure AD tenant ID.

**Client ID** `string` *required*

Azure AD application (client) ID.

**Client Secret** `string` *required*

Azure AD client secret.

**Use certificate** `boolean`

**Available starting with FlowX.AI 5.9.1.** Use a certificate instead of the client secret. When turned **ON**, the **Client Secret** is ignored. Set the **Certificate type** (**Base64** or **Path**), the **Format** (**PEM** or **PKCS12**), and, for PKCS12, the certificate **Password**. See [Step 2: Configure authentication](#step-2-configure-authentication) for details.

Click **Test Connection** to verify the credentials. The test validates both the authentication and the required MS Graph permissions for the configured scope.

***

## Connecting to processes

### Reading emails (process trigger)

To trigger processes when emails arrive:

**1. Configure the Message Start Event**

Open your process definition and add a **Message Start Event** (Start Catch Message) node.

**2. Select Microsoft Outlook as trigger type**

In the node configuration, set **Trigger Type** to **Microsoft Outlook**. Then select the Microsoft Outlook data source (only data sources with **Read** or **Read & Send** scope are shown).

**3. Activate the trigger**

Navigate to **Runtime Settings** → **Manage Triggers** and activate the trigger.

![Message Start Event - Microsoft Outlook trigger](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/email_trigger.png)

> [!WARNING]
>
> The trigger must be activated from **Manage Triggers** in Runtime Settings before email monitoring begins.

> [!NOTE]
>
> The Microsoft Outlook data source polls for new emails every **30 seconds** by default, using the same polling scheduler as the Email Trigger (configurable via `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL`). Each polling cycle processes up to **50 messages** (configurable via `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL`). Emails with the same timestamp as the last processed email are deduplicated automatically using their internet message ID.

### Sending emails (notification template)

To send emails from processes:

**1. Link to a notification template**

Open a notification template and set **Email Server** to **Predefined Email Connection**. Select the Microsoft Outlook data source (only data sources with **Send** or **Read & Send** scope are shown).

**2. Add a Send Notification action**

Add a [Send Notification](../../building-blocks/actions/send-notification-action) action to a process node and select the notification template.

![Notification template - Outlook data source](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/template.png)

### Replying to received emails

Microsoft Outlook supports replying to emails received via the Read scope, maintaining the original conversation thread in the recipient's inbox.

**1. Configure the Send Notification action**

Add a [Send Notification](../../building-blocks/actions/send-notification-action) action to a process node. In the action configuration, turn on the **Reply to received emails** toggle.

**2. Set the Reply to Email Header**

Specify the process key that holds the original email's header parameters (e.g., `emailMessage.headerParams`). This is required when the reply toggle is on.

**3. Configure recipients (optional)**

By default, the reply is sent to the original sender. You can override this by adding explicit **Receivers**, **CC**, or **BCC** addresses. Duplicate recipients are automatically removed.

> [!NOTE]
>
> The reply mechanism uses the `x-ms-graph-message-id` header from the original email to thread the reply correctly. If this header is not available, the system falls back to the standard `Message-ID` header and looks up the original message via the MS Graph API. Sent replies are automatically saved to the Sent Items folder.

***

## Email data schema

When an email triggers a process, the following data structure is available in your process variables:

```json theme={"dark"}
{
  "emailMessage": {
    "subject": "Support Request #12345",
    "dateTime": "2026-01-15T10:30:00Z",
    "sender": "customer@example.com",
    "body": "Email body content...",
    "fileAttachments": [
      {
        "filePath": "email-attachments/proc-123/invoice.pdf",
        "downloadPath": "internal/files/uuid-456/download"
      }
    ],
    "headerParams": {
      "Message-ID": "<abc123@example.com>",
      "x-ms-graph-message-id": "AAMk..."
    }
  }
}
```

### Schema fields

| Field | Type | Description |
| - | - | - |
| `subject` | string | Email subject line |
| `dateTime` | string (ISO 8601) | Timestamp when email was received |
| `sender` | string | Sender's email address |
| `body` | string | Email body content |
| `fileAttachments` | array | List of attachment metadata objects |
| `fileAttachments[].filePath` | string | Storage path in Document Plugin |
| `fileAttachments[].downloadPath` | string | API path to download the file |
| `headerParams.Message-ID` | string | Standard email message identifier |
| `headerParams.x-ms-graph-message-id` | string | MS Graph message ID (used for replies) |

***

## Managing triggers at runtime

### Manage Triggers

Navigate to **Runtime** → **Runtime Settings** → **Manage Triggers** to view and control Microsoft Outlook email triggers.

![Manage Triggers - Microsoft Outlook](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/triggers.png)

| Column | Description |
| - | - |
| **State** | Current status: `Active` or `Deactivated` |
| **Trigger Type** | "Email Trigger" for Microsoft Outlook email triggers |
| **Event Name** | The Microsoft Outlook data source name |
| **Location** | `Local`, or the library project the trigger comes from |

### Activation requirements

For a Microsoft Outlook trigger to appear in Manage Triggers:

1. Microsoft Outlook data source must be created with **Read** or **Read & Send** scope
2. Data source must be linked to a Message Start Event node
3. The process must be part of a build in the **Active Policy**

### Failed Triggers

When emails fail validation or processing errors occur, they appear in **Runtime** → **Processes** → **Failed Triggers**.

Failed triggers display the timestamp, trigger name, cause type, context (e.g., sender address), and detailed error messages. Click a row to open the details page with full diagnostic information.

#### Common failure causes

> [tab] File type not permitted
>
> **Message:** "The file `{filename}` could not be uploaded because it is not on the list of permitted file types."
>
> **Resolution:** Update the **Allowed File Types** in the data source Settings tab, or ask the sender to use an accepted format.

> [tab] File size exceeded
>
> **Message:** "`{filename}` is too large. Maximum allowed: 25 MB"
>
> **Resolution:** The attachment exceeds the configured maximum file size. Ask the sender to reduce the file size.

> [tab] File count exceeded
>
> **Message:** "File limit exceeded. For this trigger there is a limit of `{limit}` per email."
>
> **Resolution:** The email has more attachments than allowed. Ask the sender to split attachments across multiple emails.

> [tab] Authentication failure
>
> **Message:** "MS Graph connection failed: \[error details]"
>
> **Resolution:** Azure AD credentials may have expired or been revoked. The system retries once on 401/403 errors by refreshing the cached client. If the retry also fails, go to the **Authorization** tab, verify the Tenant ID, Client ID, and Client Secret, and click **Test Connection**. Regenerate the client secret in Azure AD if it has expired.

> [tab] Missing permissions
>
> **Message:** "MS Graph application is missing required permissions: \[list]. Please add these as Application permissions in Azure AD and grant admin consent."
>
> **Resolution:** The Azure AD app registration is missing one or more required MS Graph permissions. Add the listed permissions as **Application permissions** (not Delegated) in the Azure portal and ensure **admin consent** has been granted.

***

## Use case: document processing with auto-reply

This example walks through a complete email-triggered workflow: an email with an attachment arrives, the process extracts and classifies the document, then replies to the sender with a confirmation.

**1. Create a Microsoft Outlook data source**

Configure a data source with **Read & Send Emails** scope, pointed at your intake mailbox (e.g., `documents@company.com`). Set attachment validations to accept PDF and DOCUMENT types with a 25 MB size limit.

**2. Design the process**

Create a process with a **Message Start Event** node configured to trigger from the Outlook data source. The email data is available in process variables under `emailMessage`.

**3. Access email data in downstream nodes**

Use the email schema fields in Script or Business Rule nodes to route the process:

```javascript theme={"dark"}
// Access email fields in a Script node
var subject = input.get("emailMessage").get("subject");
var sender = input.get("emailMessage").get("sender");
var attachments = input.get("emailMessage").get("fileAttachments");

// Route based on subject keywords
if (subject.contains("invoice")) {
    output.put("documentType", "INVOICE");
} else {
    output.put("documentType", "GENERAL");
}
```

**4. Process the attachment**

Use the `fileAttachments[].downloadPath` to retrieve the file from the Document Plugin for classification, data extraction, or storage.

**5. Reply to the sender**

Add a **Send Notification** action with the **Reply to received emails** toggle turned on. Set the reply header to `emailMessage.headerParams`. The reply is threaded under the original email in the sender's inbox.

**6. Activate the trigger**

Navigate to **Runtime Settings** → **Manage Triggers** and activate the trigger to begin monitoring.

***

## Best practices

> [card] Use configuration parameters
>
> Store Azure AD credentials (Tenant ID, Client ID, Client Secret) in configuration parameters for secure, environment-specific management.

> [card] Set appropriate validations
>
> Configure file type, size, and count limits for Read scope to prevent processing of unwanted or oversized attachments.

> [card] Monitor failed triggers
>
> Regularly review the Failed Triggers section to identify issues with email processing or connection problems.

> [card] Use least-privilege permissions
>
> Grant only the minimum required MS Graph permissions for your scope. Use `Mail.Read` instead of `Mail.ReadWrite` if you only need read access.

***

## Troubleshooting

> [accordion] Connection test fails
>
> Common causes:
>
> * **Invalid credentials**: Verify Tenant ID, Client ID, and Client Secret in Azure AD
> * **Missing permissions**: Ensure the app registration has the required MS Graph application permissions
> * **Permissions not consented**: Admin consent may be required for application permissions
> * **Expired client secret**: Generate a new client secret in Azure AD

> [accordion] Emails not triggering processes
>
> Check:
>
> 1. Does the data source have **Read** or **Read & Send** scope?
> 2. Is the trigger **Active** in Manage Triggers?
> 3. Is the correct mailbox folder configured?
> 4. Do incoming emails pass attachment validation rules?
> 5. Review Failed Triggers for error details

> [accordion] Emails not sending
>
> Check:
>
> 1. Does the data source have **Send** or **Read & Send** scope?
> 2. Is the data source linked to a notification template?
> 3. Is the notification template's **Email Server** set to **Predefined Email Connection**?
> 4. Does the Azure AD app have `Mail.Send` permission?
> 5. Review process instance logs for error details

> [accordion] Permission errors
>
> Required MS Graph **application permissions** by scope:
>
> | Scope | Required permission |
> | - | - |
> | Read | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
> | Send | `Mail.Send` or `Mail.ReadWrite` |
>
> Ensure:
>
> * Permissions are set as **Application** (not Delegated)
> * **Admin consent** has been granted
> * The app registration is in the correct Azure AD tenant

***

## Related resources

> [card] [Email Trigger](./email-trigger)
>
> Configure IMAP connections to trigger processes from incoming emails

> [card] [Email Sender](./email-sender)
>
> Configure SMTP connections to send emails from processes

> [card] [Send Notification Action](../../building-blocks/actions/send-notification-action)
>
> Send emails and reply to received emails from process nodes

> [card] [Message Start Event](../../building-blocks/node/message-events/message-catch-start-event)
>
> Configure message-based and email-based process triggers

> [card] [Integration Designer](./integration-designer)
>
> Learn about other data source types and workflow creation

> [card] [Configuration Parameters](../core-extensions/configuration-parameters)
>
> Use environment variables for flexible configurations


# Mock integrations
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/mock-integrations

If you need to test the business process flow but haven't completed all integrations, you can still do so by utilizing the mock integrations server included in the platform.

## Setup

To begin, configure the microservice's DB settings to use a Postgres DB. Then, deploy the mocked adapter microservice.

## Adding a new integration

Setting up a mocked integration requires only one step: adding a mock Kafka request and response.

You have two options for accomplishing this:

1. Add the information directly to the DB.
2. Use the provided [**API**](../../api/mocks/add-kafka-mock).

For each Kafka message exchange between the engine and the integration, you need to create a separate entry.

> [!TIP]
>
> Check out the [**Add new exchange Kafka mock**](../../api/mocks/add-kafka-mock) API reference for more details.

> [!TIP]
>
> Check out the [**View all available Kafka exchanges**](../../api/mocks/view-kafka-exchanges) API reference for more details.


# Observability with OpenTelemetry
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/open-telemetry

Monitor and analyze FlowX.AI platform performance using OpenTelemetry for distributed tracing, metrics, and logging.

## What is Observability?

Observability is the capacity to infer the internal state of a system by analyzing its external outputs. In software development, this entails understanding the internal workings of a system through its telemetry data, which comprises traces, metrics, and logs.

## What is Open Telemetry?

OpenTelemetry is an observability framework and toolkit for generating and managing telemetry data, including traces, metrics, and logs. It is vendor-agnostic and compatible with various observability backends like Jaeger and Prometheus. Unlike observability backends, OpenTelemetry focuses on the creation, collection, and export of telemetry data, leaving storage and visualization to other tools.

> [!NOTE]
>
> FlowX supports distributed tracing with OpenTelemetry.

## How it works?

The monitoring and performance analysis system uses OpenTelemetry for comprehensive tracing and logging across our microservices architecture. By integrating with Grafana and other observability tools, we achieve detailed visibility into the lifecycle of requests, the performance of individual operations, and the interactions between different components of the system.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/otel_hla.drawio.png)

> [!NOTE]
>
> OTEL Collectors are designed in a vendor-agnostic way to receive, process and export telemetry data. For more information, see the [OTEL Collectors documentation](https://opentelemetry.io/docs/collector/).

> [!TIP]
>
> Recommended OpenTelemetry Collector Processors: Follow the [**recommended processors**](https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor#recommended-processors).

## Prerequisites

### Microservices

* **Java agent**: Configuration and deployment of the OpenTelemetry Java agent enables automatic instrumentation with no code changes required.
* **Manual instrumentation** (optional): Custom code additions for creating custom spans and enriching traces with business context. This is an advanced use case — automatic instrumentation via the Java agent is sufficient for most deployments.
* **Performance impact assessment**: Evaluate the overhead of instrumentation in your environment before enabling in production.

### Kubernetes

* Use of a Kubernetes Operator for managing instrumentation and tracing configuration.

## Instrumentation

### Auto-instrumentation with Java agent

* **Works**: Automatically wraps methods at the application edges (HTTP calls, Kafka messages, DB calls), creating spans and adding default span attributes.
* **Configuration**: Configure the Java agent for auto-instrumentation.

### Manual instrumentation

* **Custom Spans**: These were created for methods important to the business flow and enriched with technical attributes such as `fx.type`, `fx.methodName`, `fx.processInstanceUuid`, and others.
* **Custom BUSINESS Spans**: Create spans for business events.

## Business logic metadata in logs and spans

Spans now include custom FlowX attributes (e.g., node names, action names, process names, instance UUIDs), which can be used for filtering and searching in traces.

Here is the full list of included custom FlowX span attributes:

### Custom span attributes

* fx.type - BUSINESS/TECHNICAL
* fx.methodName
* fx.parentProcessInstanceId
* fx.parentProcessInstanceUuid
* fx.processInstanceUuid
* fx.processName
* fx.processVersionId
* fx.tokenInstanceUuid
* fx.nodeName
* fx.nodeId
* fx.nodeUuid
* fx.boundaryEventId
* fx.nextNodeId
* fx.triggeredByBoundaryEventId
* fx.actionUuid
* fx.actionName
* fx.context
* fx.platform

### Custom business spans

* identified by the `fx.type = BUSINESS` attribute

### Detailed trace operations

Trace specific operations and measure request time across different layers/services.

* **Process Start**: Auto-instrumentation enabled for Spring Data to show time spent in repository methods. JDBC query instrumentation can be added.
* **Token Creation and Advancing**: Custom tracing added.
* **Action Execution and Subprocess Start**: Custom tracing added.

## Controlling trace volume

By default, FlowX services sample **all** traces (`otel.traces.sampler=parentbased_always_on`). In high-throughput environments this can generate significant trace volume. You can reduce or scope trace collection at several levels **without turning off logs and metrics**, which use separate pipelines.

> [!NOTE]
>
> These controls apply to self-hosted deployments where you manage the OpenTelemetry operator and service configuration. Logs (`otel.logs.exporter`) and metrics (`otel.metrics.exporter`) are unaffected by trace sampling.

### Adjust the sampling rate (operator level)

Trace sampling is configured on the OpenTelemetry operator's `Instrumentation` resource. Lower the ratio to keep a representative sample instead of every trace:

```yaml theme={"dark"}
spec:
  sampler:
    type: parentbased_traceidratio
    argument: "0.1"   # sample ~10% of traces; "1" = all, "0" = none
```

To stop collecting traces entirely (while keeping logs and metrics), use:

```yaml theme={"dark"}
spec:
  sampler:
    type: parentbased_always_off
```

### Turn off tracing for a specific service

Trace instrumentation is injected per service via a pod annotation. Remove it from a service's deployment to stop tracing that service only:

```yaml theme={"dark"}
podAnnotations:
  instrumentation.opentelemetry.io/inject-java: "true"   # remove to disable tracing for this service
```

### Limit which libraries generate spans

Auto-instrumentation can be tuned per library through the service's OpenTelemetry properties. Turn off noisy instrumentations individually:

```properties theme={"dark"}
otel.instrumentation.jdbc.enabled=false
otel.instrumentation.hibernate.enabled=false
```

Or turn everything off by default and enable only what you need:

```properties theme={"dark"}
otel.instrumentation.common.default-enabled=false
otel.instrumentation.spring-web.enabled=true
otel.instrumentation.spring-kafka.enabled=true
```

For the full list of tunable instrumentation properties, see [Open Telemetry default properties](/5.9/setup-guides/ot-default-properties).

> [!WARNING]
>
> Some instrumentation depends on other instrumentation to work. When enabling selectively, enable the transitive dependencies too.

### Filter technical vs business spans at query time

FlowX tags every span with `fx.type` (`BUSINESS` or `TECHNICAL`). While sampling decisions are made per trace (not per span type), you can filter on `fx.type` in your observability backend. For example, query only `fx.type = BUSINESS` in Grafana/Tempo to focus on business-relevant traces without changing what's collected.

## Troubleshooting scenarios and common usages

### Scenario examples

* **Process Trace**: Analyze DB vs cache times, token advancement, node actions.
* **Parallel Gateway**: Trace split tokens.
* **DB Query Time**: Enable JDBC query tracing.
* **Endpoint Data Issues**: Check traces for Redis or DB source.
* **Token Stuck**: Filter by node name and process UUID.
* **Action Execution**: Trace action names for stuck tokens.
* **Subprocess Failures**: Analyze subprocess start and failures.
* **Latency Analysis**: Identify latencies in automatic actions.
* **Boundary Events**: Ensure Kafka schedule messages are sent and received correctly.
* **External Service Tracking**: Trace between process engine and external plugins.

### Business operation analysis

* **Long Running Operations**: Use Uptrace for identifying slow operations.
* **Failed Requests**: Filter traces by error status.

### Visualization of Traces

> [!TIP]
>
> We recommend to use Grafana, but any observability platform compatible with OpenTelemetry standards can be used.

Grafana integrates with tracing backends such as Tempo (for tracing) and Loki (for logging), allowing us to visualize the entire lifecycle of a request. This includes detailed views of spans, which are the basic units of work in a trace. By using Grafana, we can:

* **View Trace Trees**: Grafana provides an intuitive UI for viewing the hierarchy and relationships between spans, making it easier to understand the flow of a request through the system.
* **Filter and Search**: Use Grafana to filter and search spans based on custom attributes like `fx.processInstanceUuid`, `fx.nodeName`, `fx.actionName`, and others. This helps in pinpointing specific operations or issues within a trace.
* **Error Analysis**: Identify spans with errors and visualize the stack trace or error message, aiding in quick troubleshooting.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/custom_spans.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/custom_spans1.png)

Resources:

> [card] [OpenTelemetry Docs](https://opentelemetry.io/docs/)


# Oracle Database
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/oracle-database

Connect to Oracle databases as a data source in FlowX workflows and run SQL queries against them.

## Overview

Oracle Database is a relational data source type that lets you connect FlowX workflows to **Oracle databases that your organization manages independently**. You configure a connection, save named SQL queries against the schema, and call those queries from workflows.

> [card] Connect to your Oracle instance
>
> Connect via Service Name or SID, with an optional SSL toggle

> [card] Schema-aware SQL editor
>
> Monaco editor with SQL syntax highlighting, schema-aware autocomplete, and a side panel that lists tables, columns, primary keys, and foreign keys

> [card] Test before you ship
>
> Run any saved query with sample parameters and inspect the response: table view for SELECT, affected-row count for INSERT / UPDATE / DELETE

> [card] Reusable in workflows
>
> Reference Oracle queries from the Database Operation node alongside other data sources

***

## Prerequisites

* An Oracle Database 21c or 23ai instance accessible from your FlowX deployment
* A database user with the privileges your queries require (typically `SELECT`, `INSERT`, `UPDATE`, `DELETE` on the target schema, plus `SELECT` on data dictionary views for schema discovery)
* Network connectivity between the `nosql-db-runner` service and the Oracle instance
* For SSL connections: appropriate certificates configured on the Oracle instance and trusted by the FlowX deployment

***

## Creating an Oracle Database data source

![Oracle Database data source settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/oracle_data_source_settings.png)

**1. Open Data Sources**

Navigate to **Integration Designer** → **Data Sources** in your project.

**2. Add a new data source**

Click the **+** button to open the **Add Data Source** dialog. In the **Databases** category, select **Oracle Database**.

**3. Configure the connection**

Fill in the connection fields:

| Field | Description |
| - | - |
| **Host** | Oracle server hostname or IP |
| **Port** | Oracle listener port (default `1521`) |
| **Database Name / SID** | The service name or SID, depending on the connection type |
| **Schema Name** | Optional. The schema to use for queries and discovery |
| **SSL Enabled** | Toggle SSL on or off for the connection |
| **Connection Type** | **Service Name** or **SID** |
| **Username** | Database username |
| **Password** | Database password |

Each field accepts configuration parameters for environment-specific values.

**4. Test the connection**

Click **Test Connection and Rescan** to verify connectivity and refresh the schema cache.

> [!NOTE]
>
> The data source is created even if the connection test fails, so you can save partial configuration and resolve connectivity later. Return to the **Settings** tab and click **Test Connection and Rescan** once the issue is fixed.

**5. Save**

Click **Save** to create the data source.

***

## Queries

Each Oracle Database data source holds a list of named SQL queries. A query is a single parameterized SQL statement that you can call from a workflow.

### SQL editor

Open the **Queries** tab on the data source, then click **New query** to open the editor:

* **Query area**: Monaco editor with SQL syntax highlighting and schema-aware autocomplete. Reference declared parameters with `${paramName}` interpolation; matching suggestions appear in the editor autocomplete and in the parameters panel.
* **Parameters panel** (left): declare each bind parameter with a type. Supported types are `STRING`, `NUMBER`, `BOOLEAN`, `DATE`, and `CURRENCY`.
* **Schema browser** (right): pick a table from the dropdown to inspect its columns. Primary-key and foreign-key badges appear next to column names. Hover a foreign-key badge to see the referenced table and column.

> [!NOTE]
>
> The Monaco editor ships a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `${paramName}` interpolations resolved from the parameters panel. Hover and bracket matching match the rest of the FlowX code editors.

### Testing a query

Click **Test query** to open the test modal:

* **Parameters**: supply values for declared bind parameters.
* **Query and tables**: view the SQL and the resolved schema context.
* **Response**: for `SELECT`, results render as both a table and JSON, with `totalCount` and `executionTimeMs`. For `INSERT` / `UPDATE` / `DELETE`, the response is `affectedRows`. Errors include the Oracle `sqlState` and message (for example, `ORA-00942: table or view does not exist`).

The modal warns before discarding unsaved changes.

***

## Stored procedures, functions, and views

Beyond plain `SELECT` and DML statements, Oracle Database queries can also target **views**, **functions**, and **stored procedures**. The schema browser discovers each as a distinct entity type, so you can reference them the same way you reference tables.

| Entity | How to call it |
| - | - |
| **Views** | Query like any table: `SELECT * FROM V_MONTHLY_REVENUE WHERE month = ${m}`. Non-updatable views are read-only; an `UPDATE` against one is rejected. |
| **Scalar functions** | Wrap in a `SELECT` against `dual`: `SELECT FN_CALCULATE_VAT(${amount}, ${country}) AS vat FROM dual`. |
| **Table functions** | Wrap in `TABLE(...)`: `SELECT * FROM TABLE(FN_GET_ACTIVE_ORDERS(${customer_id}))`. |
| **Stored procedures** | Call inside an anonymous PL/SQL block: `BEGIN SP_CREATE_INVOICE(:order_id, :issue_date, :invoice_id, :invoice_pdf); END;`. Output parameters and `REF CURSOR` results are returned as described below. |

> [!NOTE]
>
> A function that has `OUT` (or `IN OUT`) parameters cannot be called from a `SELECT` — only from a PL/SQL block. To use a function inside a `SELECT`, it must take `IN` parameters only and return its value via `RETURN`.

### Returning data from stored procedures

A stored procedure returns its results through **output parameters**. Because output parameters are not part of the SQL result set by default, you must declare them explicitly so the engine knows what to read back.

Declare the output parameters in a `-- OUT:` comment at the top of the script, before the `BEGIN` block. List each parameter as `<parameter_name> <TYPE>`, separated by commas:

```sql theme={"dark"}
-- OUT: p_count NUMBER, p_status VARCHAR2
BEGIN
  my_package.my_procedure(p_count => :p_count, p_status => :p_status);
END;
```

Rules:

* The declaration must come at the top of the script, before the `BEGIN` block.
* `<parameter_name>` must exactly match the corresponding output parameter in the procedure's signature (`p_count` here maps to the procedure's `p_count` OUT parameter).
* `<TYPE>` must match the parameter's declared type in the procedure — for example `NUMBER`, `VARCHAR2`, or `DATE`.

> [!WARNING]
>
> If an output parameter is not declared this way, the script runs but no data is returned for it.

> [!TIP]
>
> This comment-based declaration is the current convention for surfacing procedure output. Procedure output parameters and Oracle `REF CURSOR` results are unwrapped into the response result set, so the calling workflow can map them to variables like any other query response.

***

## Using in workflows

Oracle queries are called from the existing **Database Operation** node in workflows.

**1. Add a Database Operation node**

On the workflow canvas, drag a **Database Operation** node onto the workspace.

**2. Select the data source and query**

In the node configuration panel, pick the Oracle data source. The query picker then lists only the queries saved on that data source.

**3. Map parameters**

Map workflow inputs to the query's bind parameters. Map the response (rows or `affectedRows`) to a workflow variable.

> [!TIP]
>
> Scoping the picker to the selected data source keeps Oracle queries and MongoDB operations separate, even when both data source types exist in the same project.

***

## Deployment

No new microservices are required. Oracle Database queries run inside the existing **`nosql-db-runner`** service, which bundles the Oracle JDBC driver. Each Oracle data source uses its own HikariCP connection pool.

### Configuration defaults

The following defaults apply to all Oracle data sources and can be tuned via environment variables on the `nosql-db-runner` service:

| Environment Variable | Description | Default |
| - | - | - |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools | `100` |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached connection pools | `1d` |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per data source | `5` |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout | `10` |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses | `1000` |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout | `30` |

### Per-data-source advanced settings

Each Oracle data source can override the global defaults from its **Advanced settings** panel, grouped into **Pool size**, **Pool lifecycle**, **Liveness**, and **Performance**. Fields left empty inherit the global value:

| Setting | Description |
| - | - |
| **Min Pool Size** | Minimum number of connections kept open in the pool |
| **Max Pool Size** | Maximum number of connections in the pool |
| **Connection Timeout (ms)** | Maximum time to wait for a connection from the pool |
| **Unused Timeout (ms)** | Time an idle connection may sit in the pool before being retired |
| **Aged Timeout (ms)** | Maximum lifetime of a pooled connection |
| **Keep Alive** | Keep-alive probing for pooled connections |
| **Maintenance Frequency (ms)** | Interval between pool housekeeping runs. Editable only when **Keep Alive** is turned on |
| **Validate Connection String** | Query used to validate connections before use |
| **Response Timeout (ms)** | Per-query execution timeout for this data source |
| **Prepared Statement Cache Size** | Number of prepared statements cached per connection |

Ensure the `nosql-db-runner` service has network access to your Oracle instance. If Oracle is behind a firewall, configure the appropriate network rules.

***

## Related resources

> [card] [FlowX Database](./flowx-database)
>
> Managed MongoDB data storage within FlowX

> [card] [Unmanaged MongoDB](./unmanaged-mongodb)
>
> Connect to externally managed MongoDB instances

> [card] [Integration Designer](./integration-designer)
>
> Overview of all data source types and workflow building

> [card] [NoSQL DB Runner setup](/5.9/setup-guides/nosql-db-runner)
>
> Deployment configuration for the database runner service


# PostgreSQL Database
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/postgresql-database

Connect to PostgreSQL databases as a data source in FlowX workflows and run SQL queries against them.

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

PostgreSQL Database is a relational data source type that lets you connect FlowX workflows to **PostgreSQL databases that your organization manages independently**. You configure a connection, save named SQL queries against the schema, and call those queries from workflows.

> [card] Connect to your PostgreSQL instance
>
> Connect with host, database, schema, and credentials, with an optional SSL toggle

> [card] Schema-aware SQL editor
>
> Monaco editor with SQL syntax highlighting, schema-aware autocomplete, and a side panel that lists tables, columns, primary keys, and foreign keys

> [card] Test before you ship
>
> Run any saved query with sample parameters and inspect the response: rows for SELECT, affected-row information for INSERT / UPDATE / DELETE

> [card] Reusable in workflows
>
> Reference PostgreSQL queries from the Database Operation node alongside other data sources

***

## Prerequisites

* A PostgreSQL database accessible from your FlowX deployment
* A database user with the privileges your queries require (typically `SELECT`, `INSERT`, `UPDATE`, `DELETE` on the target schema, plus read access to the system catalogs for schema discovery)
* Network connectivity between the `nosql-db-runner` service and the PostgreSQL instance
* For SSL connections: appropriate certificates configured on the PostgreSQL instance and trusted by the FlowX deployment

***

## Creating a PostgreSQL Database data source

![PostgreSQL Database in the Add Data Source dialog](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/postgres_data_source.png)

**1. Open Data Sources**

Navigate to **Integration Designer** → **Data Sources** in your project.

**2. Add a new data source**

Click **New Data Source** to open the creation modal. In the **Databases** category, select the **PostgreSQL Database** tile, give the data source a name, and click **Create**.

**3. Configure the connection**

On the **Settings** tab, fill in the connection fields:

| Field | Description |
| - | - |
| **Host** | PostgreSQL server hostname or IP |
| **Port** | PostgreSQL port (default `5432`) |
| **Database Name** | The database to connect to |
| **Schema Name** | Optional. The schema to use for queries and discovery |
| **SSL Enabled** | Toggle SSL on or off for the connection |
| **Username** | Database username |
| **Password** | Database password |

Each field accepts configuration parameters for environment-specific values.

**4. Test the connection**

Click **Test Connection and Rescan** to verify connectivity and refresh the schema cache.

> [!NOTE]
>
> The data source is created even if the connection test fails, so you can save partial configuration and resolve connectivity later. Return to the **Settings** tab and click **Test Connection and Rescan** once the issue is fixed.

**5. Save**

Click **Save** to create the data source.

The **Settings** tab holds the connection fields and the **Advanced settings** panel:

![PostgreSQL Database data source settings](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/postgres_data_source_settings.png)

***

## Queries

Each PostgreSQL Database data source holds a list of named SQL queries. A query is a single parameterized SQL statement that you can call from a workflow.

### SQL editor

Open the **Queries** tab on the data source, then click **New query** to open the editor:

![PostgreSQL query editor with Parameters, Query, and Response Caching panels](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/postgres_data_source_queries.png)

* **Query**: Monaco editor with SQL syntax highlighting and schema-aware autocomplete. Reference parameters in the query using `${paramName}` interpolation, as noted by the hint above the editor.
* **Parameters**: declare each parameter with a type, then in workflows assign values to them using node input paths. Supported types are `STRING`, `NUMBER`, `BOOLEAN`, `ENUM`, `DATE`, `CURRENCY`, and `OBJECT`.
* **Schema awareness**: discovered tables, columns, and primary/foreign keys feed the editor's autocomplete so you can reference schema objects as you type.

Use **Test** to run the query and **Save** to persist it.

> [!NOTE]
>
> The Monaco editor ships a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `${paramName}` interpolations resolved from the parameters panel. Hover and bracket matching match the rest of the FlowX code editors.

### Testing a query

Click **Test** to open the test modal:

* **Parameters**: supply values for declared parameters.
* **Query and tables**: view the SQL and the resolved schema context.
* **Response**: for `SELECT`, results render as both a table and JSON, along with `totalCount`, `responseTime` (in milliseconds), and `responseSize`. For `INSERT` / `UPDATE` / `DELETE`, the response reflects the affected rows. Errors are returned with a database error `code` and `message` (for example, a PostgreSQL `SQLSTATE` such as `42P01: relation does not exist`).

The modal warns before discarding unsaved changes.

### Response caching

Query responses can be cached from the **Response Caching** panel in the editor. Turn on **Caching Enabled**, then choose how long a cached response stays valid:

* **Expires after** a fixed duration from each request.
* **Expires at** a specific time, on a recurrence (for example, daily).

Caching cuts repeated database round-trips for stable data, using the same policy model as [endpoint response caching](./data-sources-and-endpoints#rest-endpoint-caching).

***

## Views, functions, and stored procedures

Beyond plain `SELECT` and DML statements, the schema browser discovers **views**, **functions**, and **stored procedures** as distinct entity types, so you can reference them the same way you reference tables.

| Entity | How to call it |
| - | - |
| **Views** | Query like any table: `SELECT * FROM monthly_revenue WHERE month = ${m}`. Non-updatable views are read-only. |
| **Functions** | Call in a `SELECT`: `SELECT * FROM get_active_orders(${customer_id})` for set-returning functions, or `SELECT calculate_vat(${amount}, ${country}) AS vat` for scalar functions. |
| **Stored procedures** | Invoke with `CALL`: `CALL create_invoice(${order_id}, ${issue_date})`. |

> [!TIP]
>
> Discovered functions and procedures show their signatures in the schema browser, so you can see the expected parameters before writing the call.

***

## Using in workflows

PostgreSQL queries are called from the existing **Database Operation** node in workflows.

**1. Add a Database Operation node**

On the workflow canvas, drag a **Database Operation** node onto the workspace.

**2. Select the data source and query**

In the node configuration panel, pick the PostgreSQL data source. The query picker then lists only the queries saved on that data source.

**3. Map parameters**

Map workflow inputs to the query's parameters. Map the response (rows or affected-row information) to a workflow variable.

> [!TIP]
>
> Scoping the picker to the selected data source keeps PostgreSQL queries, Oracle queries, and MongoDB operations separate, even when several data source types exist in the same project.

***

## Deployment

No new microservices are required. PostgreSQL Database queries run inside the existing **`nosql-db-runner`** service, which bundles the PostgreSQL JDBC driver. Each PostgreSQL data source uses its own HikariCP connection pool.

### Configuration defaults

The following defaults apply to all relational database data sources and can be tuned via environment variables on the `nosql-db-runner` service:

| Environment Variable | Description | Default |
| - | - | - |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools | `100` |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached connection pools | `1d` |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per data source | `5` |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout | `10` |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses | `1000` |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout | `30` |

### Per-data-source advanced settings

Each PostgreSQL data source can override the global defaults from its **Advanced settings** panel, grouped into **Pool size**, **Pool lifecycle**, **Liveness**, and **Performance**. Fields left empty inherit the global value:

| Setting | Description |
| - | - |
| **Min Pool Size** | Minimum number of connections kept open in the pool |
| **Max Pool Size** | Maximum number of connections in the pool |
| **Connection Timeout (ms)** | Maximum time to wait for a connection from the pool |
| **Unused Timeout (ms)** | Time an idle connection may sit in the pool before being retired |
| **Aged Timeout (ms)** | Maximum lifetime of a pooled connection |
| **Keep Alive** | Keep-alive probing for pooled connections |
| **Maintenance Frequency (ms)** | Interval between pool housekeeping runs. Editable only when **Keep Alive** is turned on |
| **Validate Connection String** | Query used to validate connections before use |
| **Response Timeout (ms)** | Per-query execution timeout for this data source |

Ensure the `nosql-db-runner` service has network access to your PostgreSQL instance. If PostgreSQL is behind a firewall, configure the appropriate network rules.

***

## Related resources

> [card] [Oracle Database](./oracle-database)
>
> Connect to Oracle databases with the same query and workflow experience

> [card] [FlowX Database](./flowx-database)
>
> Managed MongoDB data storage within FlowX

> [card] [Unmanaged MongoDB](./unmanaged-mongodb)
>
> Connect to externally managed MongoDB instances

> [card] [NoSQL DB Runner setup](/5.9/setup-guides/nosql-db-runner)
>
> Deployment configuration for the database runner service


# SOAP System
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/soap-system

Connect FlowX workflows to SOAP web services by importing a WSDL, then invoke the discovered operations as workflow nodes.

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

## Overview

The **SOAP System** data source connects Integration Designer to SOAP web services. Instead of hand-building envelopes through a REST endpoint, you import the service's **WSDL** — FlowX parses it into typed operations with input, output, and fault schemas — and call the discovered operations from workflows like any other data-source operation.

> [card] WSDL import
>
> Import from a URL or an uploaded file; operations, schemas, and the service URL are discovered automatically

> [card] Typed operations
>
> Each operation carries its input, output, and fault schemas from the WSDL's XSD, browsable as a data-model tree

> [card] Composed envelopes
>
> FlowX composes the SOAP envelope at runtime; you work with `${variable}` placeholders, not raw XML

> [card] Built-in testing
>
> Test operations with per-variable overrides and a curl preview before wiring them into workflows

Both **SOAP 1.1** and **SOAP 1.2** services are supported. The SOAP version is derived from the WSDL and is read-only.

***

## Creating a SOAP System data source

**1. Create the data source**

In **Data Sources**, create a new data source and pick **SOAP System** (under the **APIs** category, next to Restful System). Give it a name and description.

**2. Set the Service URL**

On the system page, set the **Service URL** — the endpoint the SOAP calls are sent to. The field supports configuration parameters, so you can write `https://${environment}.example.com/service` and vary it per environment. Importing a WSDL fills this in automatically when the WSDL declares a service address.

**3. Configure authorization**

On the **Settings** tab, configure the **Authorization** used for outgoing calls — the same authorization methods available to REST systems. See [Configuring authorization](./data-sources-and-endpoints#configuring-authorization).

**4. Import the WSDL**

On the **Operations** tab, click **Import from WSDL** to discover the service's operations (next section).

***

## Importing a WSDL

Operations are created **only** through WSDL import — there is no manual "add operation". The **Import WSDL** modal offers two sources:

* **Upload file** — a `.wsdl` or `.xml` file, up to 5 MB.
* **Paste URL** — a **WSDL URL** (for example `https://intra.acme.local/service?wsdl`) that FlowX fetches and parses.

Click **Preview** to fetch and parse the document. The preview shows the **Service URL detected** in the WSDL, the list of discovered operations (each as *name — SOAPAction*) with **Select all / Deselect all**, and any parser **Warnings**. Select the operations you want and click **Import**.

> [!NOTE]
>
> **Re-importing.** When the system already has operations, the modal becomes **Re-import WSDL**. Re-importing refreshes the WSDL-derived parts of each operation (the locked WSDL operation name, SOAPAction, and schemas) — your display names, descriptions, and other edits are preserved.

***

## Configuring an operation

Each imported operation has a details page. The WSDL-derived identity — **WSDL operation** and **SOAPAction** — is locked and refreshed on re-import; everything else is yours to configure:

| Property | Description |
| - | - |
| **Display name** | A friendly name for the operation (3–50 characters). Renaming does not change the underlying WSDL operation. |
| **Description** | Optional free text. |
| **Timeout** | Maximum time in milliseconds to wait for a response before aborting the SOAP call. Applies to this operation only. |
| **URL source** | **Service URL** (the system-level URL) or **Endpoint URL override** for this operation. |

**Show schemas** opens the operation's **Input**, **Output**, and **Fault** schemas as a browsable tree (element names, XSD types, cardinality, and documentation from the WSDL).

### Variables

The **Envelope** tab lists the operation's **Variables** — auto-extracted from the input XSD. Reference each as `${variableName}` in the envelope or SOAP header XML.

* **XSD-derived variables** are contract-locked: you can set a **Default value** and **Description**, but the key, type, and required flag come from the WSDL.
* **User-defined variables** can be added freely (key, XSD type, default, required) — useful for values referenced from the SOAP header XML.

### SOAP header XML

Toggle **SOAP header XML** on to provide a custom header block. It is injected verbatim into `<soap:Header>`, and `${variableName}` placeholders are substituted from the variables above.

### Envelope preview and HTTP headers

The **Envelope preview** shows the full SOAP envelope FlowX composes and sends at runtime, with variables shown as `${variableName}` placeholders — read-only, composed server-side.

The **Http Headers** tab adds custom headers to the outgoing HTTP request that wraps the envelope (for example `Authorization: Bearer ${token}`). The standard SOAP headers are derived automatically: SOAP 1.1 sends `Content-Type: text/xml` plus the `SOAPAction` header; SOAP 1.2 sends `Content-Type: application/soap+xml` with no SOAPAction header.

***

## Testing an operation

The **Test** button opens a test modal where you can:

* Enter per-variable values that replace `${variableName}` placeholders for this test run.
* Optionally override the **SOAP header XML** for this invocation only.
* Inspect the derived standard headers (tagged *from SOAP 1.1 / 1.2* and *from WSDL*) and set per-test header values.
* Copy a backend-generated **curl** preview that includes your current overrides.

The response panel shows the **Status**, **Time**, and **Size**, with the body viewable as **XML** or parsed **JSON**. A SOAP fault is rendered distinctly with its fault code, string, actor, and detail.

You can also test an operation against a **build**: in the builds list, use **Test SOAP operation** from the build's menu and pick the operation.

***

## Using in workflows

Add a **SOAP Operation** node (under **Data Operations** in the workflow node palette) and select the operation, searching by system or operation name. The node:

* Exposes the operation's variables as parameters, with per-node value overrides.
* Stores the parsed response under the node's **response key**, like a REST call.
* Has a **Settings** tab with a per-node **Timeout** and **Allow Retry** options (retry count, interval, exponential backoff).

**Failure semantics:** a non-2xx response fails the node with the real HTTP status; **SOAP faults are not retried** (they are contract errors, not transient failures); an unreachable service surfaces as a 503.

The workflow **run logs** show, per attempt, the system, operation, SOAPAction, URL, and SOAP version, with the full **request and response envelopes** expandable — retried attempts are logged separately.

***

## Current limitations

* **WS-Security is not supported.** For services that require credentials, use the system-level **Authorization** and custom HTTP or SOAP headers.
* **File and binary payloads are not supported** — operations exchange XML data only.
* Operations cannot be created manually; they always come from a WSDL import.

***

## Related resources

> [card] [Integration Designer](./integration-designer)
>
> Data sources, workflows, and REST integrations

> [card] [Receiving XML and SOAP responses](./endpoint-file-handling#receiving-xml-and-soap-responses)
>
> Calling SOAP services through a plain REST endpoint (available on all deployments)


# Testing data sources from Runtime
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/integrations/testing-data-sources

Run database operations and SQL queries against a deployed build to validate data sources without triggering a workflow.

> [!NOTE]
>
> Data sources on a deployed build can be tested directly from **Runtime**: run a database operation or an SQL query and inspect the response, without wiring it into a workflow first. Use this to validate a data source after deploy or to investigate why an operation misbehaves in an environment.

## Where to find it

**1. Open the Builds list**

In your project, go to **Runtime** and open the **Builds** list.

**2. Open the build's test menu**

On the build you want to test against, open the test actions menu.

**3. Pick the test action for your data source**

The available entry depends on the data source type configured in the build.

| Data source | Test action |
| - | - |
| FlowX Database, unmanaged MongoDB | **Test operation** (this page) |
| Oracle, PostgreSQL (SaaS 5.10) | **Test query** (this page) |
| RESTful system | **Test endpoint** |
| SOAP system (SaaS 5.10) | **Test SOAP operation** — see [SOAP system](./soap-system#testing-an-operation) |
| Knowledge Base | **Test knowledge base** — see [Testing a knowledge base](./knowledge-base-integration/testing-knowledge-base) |

The same menu also offers **Test build** (run a process from the build) and **Test workflow** (run an integration workflow) — see the [Builds](/5.9/docs/projects/runtime/builds) documentation for the full list.

![Build test actions menu in Runtime, with Test operation and Test query entries](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/test_build_options.png)

Testing data sources requires the **data\_source\_read** permission. Test runs are recorded in the audit log.

***

## Testing SQL queries (Oracle and PostgreSQL)

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

On 5.9 self-hosted, Oracle is the only SQL data source. PostgreSQL data sources are available on SaaS from 5.10.

**Test query** opens a full-screen testing modal for the SQL data sources in the build:

1. Pick a query from the selector in the modal header — queries are grouped by data source, and you can filter with **Search query**. Data sources without queries show **No queries available**.
2. Review or edit the query in the **Query Arguments** editor (SQL, with autocomplete and a schema preview of the data source's entities), and fill in any **Input Parameters** the query uses.
3. Click **Test**. The **Response** pane shows the result as JSON, along with status, execution time, and size. Failures are shown with the database error message.

When opened from Runtime, the modal is read-only for the query definition — edits you make in the editor are for the test run only and cannot be saved to the build.

> [!WARNING]
>
> **Queries run against the live database of that environment, and they are not restricted to read-only statements.** An `UPDATE`, `INSERT`, or `DELETE` executes for real and may modify data — the modal shows the same warning. Test destructive queries only against non-production environments.

***

## Testing database operations (FlowX Database and unmanaged MongoDB)

**Test operation** opens the equivalent modal for NoSQL data sources: pick an operation from the selector in the modal header (filter with **Search operation**), provide any input parameters, and click **Test** to see the operation's response. The data source's schema is available for reference from the modal.

### Browsing documents

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

For FlowX Database and unmanaged MongoDB data sources, the test modal gains a **Documents** tab alongside **Test**: browse the collection's documents directly, filtering either visually with the **Query Builder** or by writing **JSON** filter and sort expressions, then click **Run**. Use it to check what an operation actually changed without writing a query for it.

***

## Related resources

> [card] [FlowX Database](./flowx-database)
>
> Collections, operations, and usage in workflows

> [card] [Oracle database](./oracle-database)
>
> Add an Oracle data source and define queries

> [card] [PostgreSQL database](./postgresql-database)
>
> Add a PostgreSQL data source and define queries (SaaS · 5.10)

> [card] [Testing a knowledge base](./knowledge-base-integration/testing-knowledge-base)
>
> The equivalent testing surface for knowledge bases


# Third-party components
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/third-party-components

FlowX.AI uses a number of third-party software components

## Overview

FlowX.AI relies on various third-party components to deliver its functionality. These components fall into two categories:

* **Embedded components**: Third-party software packaged and managed by FlowX.AI
* **Client-managed components**: Third-party software that you deploy and maintain

> [!NOTE]
>
> For optimal performance and reliability, our internal QA process validates new releases using specific versions. While you can explore alternative versions that suit your requirements, we recommend referring to the compatibility matrix for guidance.

> [!NOTE]
>
> Licensing of third-party components is governed by each vendor and may change over time. Consult each vendor's official licensing documentation for current terms.

## Embedded components

> [!NOTE]
>
> Embedded components are shipped and configured as part of the FlowX.AI platform. FlowX.AI manages their versioning, patching, security updates, and provides L4 support coverage. They are deployed alongside the platform using the standard FlowX.AI deployment process.

### Authorization

> [card] [SpiceDB](https://authzed.com/spicedb)
>
> An open-source permissions database inspired by Google's Zanzibar paper. Powers FlowX.AI's multi-tenant authorization system with fine-grained access control and relationship-based permissions.
>
> **Key capabilities**: Google Zanzibar-inspired authorization, ReBAC, global consistency, reverse lookup, sub-millisecond response times

> [card] [SpiceDB Operator](https://github.com/authzed/spicedb-operator)
>
> A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. Handles upgrades, scaling, and configuration changes for consistent and reliable SpiceDB deployments.

> [card] [Qdrant](https://qdrant.tech/documentation/)
>
> **Supported Version**: 1.16.3
>
> Vector search engine used by the AI Platform RAG path (knowledgebase-rag, embedder, knowledgebase-indexer-v2) and by AI agents for semantic retrieval. Required for AI Platform deployments starting with 5.9.0.

## Client-managed components

> [!NOTE]
>
> Client-managed components are deployed and maintained by your team. FlowX.AI validates compatibility with supported versions listed in the [compatibility matrix](#compatibility-matrix) but does not provide direct support for these components.

### Core infrastructure

> [tab] Identity & access
>
> > [card] [Keycloak](https://www.keycloak.org/documentation)
> >
> > Open-source identity and access management solution enabling single sign-on for modern applications.

> [tab] Messaging
>
> > [card] [Apache Kafka](https://kafka.apache.org/documentation/)
> >
> > Distributed event streaming platform for high-volume, real-time data feeds with fault tolerance and low latency.
>
> > [card] [Elasticsearch Sink Connector](https://docs.confluent.io/kafka-connectors/elasticsearch/current/overview.html)
> >
> > Kafka Connect sink plugin that streams process-instance events into Elasticsearch indices. Required only if you enable indexing via Kafka in the process engine. Other sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch versions. See [Configuring Elasticsearch indexing](/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing).

> [tab] Databases
>
> > [card] [PostgreSQL](https://www.postgresql.org/docs/)
> >
> > Free and open-source relational database emphasizing extensibility and SQL compliance.
>
> > [card] [MongoDB](https://www.mongodb.com/docs/)
> >
> > Document-oriented NoSQL database for business process data and configuration storage.

> [tab] Caching & storage
>
> > [card] [Redis](https://redis.io/docs/)
> >
> > Fast in-memory key-value store for caching and pub/sub messaging with sub-millisecond response times.

### Infrastructure & monitoring

> [accordion] Web server & load balancing
>
> **NGINX Ingress Controller**
>
> Kubernetes ingress controller for routing web traffic from SPAs to backend services and the FlowX.AI Engine.
>
> > [!NOTE]
> >
> > Starting with 5.9.x, the FlowX.AI chart no longer assumes ingress-nginx as the bundled controller. Kubernetes Ingress remains fully supported with any compliant controller (Traefik, HAProxy, Istio, cloud-provider controllers), and Gateway API HTTPRoutes are supported as an alternative. See [Ingress routing and CORS changes](/5.9/migrating-from-5.1-lts/ingress-routing).
>
> > [card] [ingress-nginx documentation](https://kubernetes.github.io/ingress-nginx/)

> [accordion] Search & analytics
>
> **Elasticsearch (EFK Stack)**
>
> Distributed search and analytics engine for centralized data storage and business process transaction searching.
>
> > [card] [Elastic Stack](https://www.elastic.co/elastic-stack/)
>
> > [card] [Fluentd](https://docs.fluentd.org/)

> [accordion] Business intelligence
>
> **Apache Superset**
>
> Business intelligence web application for data exploration and visualization, from simple charts to detailed dashboards.
>
> > [card] [Superset documentation](https://superset.apache.org/docs/intro)

### Commercial components

> [card] [Oracle Database](https://www.oracle.com/database/technologies/)
>
> Enterprise relational database management system for mission-critical workloads.
>
> > [!NOTE]
> >
> > Oracle Database requires commercial licensing. Contact Oracle for licensing information.

## Compatibility matrix

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> Keycloak 26.6.3 and later (including 26.4.13 and later on the 26.4 line) no longer apply a wildcard to the host part of a client's redirect URIs. Before upgrading Keycloak past these versions, replace host-wildcard entries such as `https://designer*` with full-host, path-form patterns (`https://your-host/*`). See [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution) for details.

## Deprecation notice

> [!WARNING]
>
> The following versions are no longer supported. Versions are dropped from the supported list as support upstream is no longer provided.
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9 (3.8 dropped in 5.9.0)

## Support information

> [!NOTE]
>
> If you encounter compatibility issues with any of the supported versions listed above, please [open a support ticket](https://support.flowx.ai/) and our team will address any identified bugs through our standard support process.

## Related resources

> [card] [Event-driven Architecture](../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-kafka-concepts)
>
> Learn about Kafka concepts and implementation

> [card] [NGINX Configuration](../platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-nginx)
>
> Understanding NGINX in FlowX.AI architecture

> [card] [Data Architecture](../platform-overview/data-architecture)
>
> Which data stores FlowX.AI uses and what each stores


# Anonymous runtime access
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access

Run processes and UI flows for unauthenticated users using the built-in Anonymous role and the Share modal's public-access option.

> [!NOTE]
>
> A runtime app can be configured for unauthenticated end users. Anonymous users start processes and UI flows from a public link, with no login required.

## Overview

Anonymous runtime access lets an app serve users who have no FlowX identity. A typical use case is a public form, a quote calculator, or an appointment booking page reachable from a marketing site.

Two independent gates must both be open for a request to be served anonymously:

**1. The app must be shared publicly**

In the Share modal, **General Access** is set to **Anyone with the link**. Apps default to **Only invited people**.

**2. The resource must allow the Anonymous role**

The specific process or UI flow being started must have the **Anonymous** role assigned in its Permissions tab.

If either gate is closed, the runtime returns `403 Forbidden` with a `detail` of `Anonymous access not enabled for this application` (the app is not publicly shared) or `Anonymous access not enabled for this build` (the resource does not carry the Anonymous role). Mixed-access is supported — the same app can serve authenticated users with their assigned roles and anonymous users with the Anonymous role.

![Share modal with General Access set to Anyone with the link](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/anonymous-share-modal.png)

***

## The Anonymous role

`Anonymous` is a **built-in, system-level role**. It represents any user who arrives without a valid authentication token.

| Property | Value |
| - | - |
| **Role type** | System (built-in) |
| **Editable** | No — name, scope, and allowed operations are fixed |
| **Deletable** | No |
| **Allowed operations** | `VIEW`, `EXECUTE`, `SELF_ASSIGN` |
| **Selectable operations in the UI** | `VIEW` and `EXECUTE` only — `SELF_ASSIGN` is auto-populated and required |
| **Default on a project** | Not added — admin opts in via **End-User Roles** in Version settings |

> [!NOTE]
>
> `SELF_ASSIGN` is required because starting a process needs both `EXECUTE` and `SELF_ASSIGN`. The role auto-populates the three operations and locks `SELF_ASSIGN` so the role always behaves consistently across processes.

***

## Make an app publicly accessible

**1. Add the Anonymous role to the project**

Open the project's **Version settings → End-User Roles**, then add **Anonymous** to the available roles. Commit the version and build it.

The Share modal reads roles from the active build, so the **General Access** option stays disabled until the active build includes the Anonymous role.

**2. Open the Share modal**

Go to **Organization settings → Solutions**. On the solution's row, click **⋮**, then **Share**.

**3. Set General Access to Anyone with the link**

Under **Who has access? → General Access**, click the access row. In **Who can access?**, switch from **Only invited people** to **Anyone with the link**.

![Share Settings step with the Who can access options Anyone with the link and Only invited people](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/anonymous-share-settings.png)

> [!TIP]
>
> Switching back to **Only invited people** at any point closes the public gate immediately. Existing anonymous sessions in flight will start returning `403 Anonymous access not enabled for this application` on their next request.

**4. Save and copy the share link**

Click **Save**, then use **Copy Solution Link** to copy the URL. The runtime app is now reachable to anyone with the URL — subject to the per-resource role check below.

***

## Configure anonymous on a resource

The Anonymous role must be explicitly assigned to each process, UI flow, or reusable UI template you want runnable without authentication.

> [tab] Process
>
> Open the process and go to **Permissions**.
>
> 1. Add **Anonymous** to the role list (only available when the role is on the version).
> 2. The role's row shows `VIEW`, `SELF_ASSIGN`, and `EXECUTE` pre-populated. Toggle `VIEW` or `EXECUTE` as needed. All other operations are greyed out.
> 3. Adding Anonymous is **additive** — it does not affect other roles on the process.
>
> Anonymous can also be added to a swimlane. The component hide/disable rules below depend on this assignment.

> [tab] UI Flow
>
> Open the UI flow and go to **Settings → Permissions**.
>
> Add **Anonymous** to the role list. The same additive behaviour applies — other roles are preserved.
>
> Anonymous on a UI flow is required for that flow to be startable from a public URL, and for any integration workflows started from inside the flow to be reachable anonymously.

> [tab] Reusable UI template
>
> Reusable UI templates inherit role availability from **Process Version → End User Roles**. Once Anonymous is added there, it becomes selectable as a role-based hide/disable condition inside the template.

***

## Component visibility for anonymous users

UI Designer hide/disable rules support the Anonymous role in the **Role** condition type. The role must already be assigned at the right scope:

| Component lives in… | Anonymous must be on… |
| - | - |
| A process node | The corresponding **swimlane** |
| A UI flow | The UI flow's **Permissions** tab |
| A reusable UI template | The process version's **End User Roles** |

Common patterns:

* **Hide for anonymous** — show a "Sign in to continue" CTA only when the user is anonymous; hide an action button (e.g. "Save to account") for anonymous users.
* **Disable for anonymous** — keep a field visible but read-only; the same field becomes editable for authenticated users.

***

## Runtime behaviour scenarios

| # | App general access | Resource has Anonymous role | User | Outcome |
| - | - | - | - | - |
| 1a | Anyone with the link | Yes | Anonymous | Starts and uses the resource with Anonymous permissions. |
| 1b | Anyone with the link | Yes (Anonymous is the only role) | Authenticated | Starts with the same permissions Anonymous grants — the logged-in user is effectively treated as anonymous for that resource. |
| 1c | Anyone with the link | Yes (Anonymous + at least one other role) | Authenticated and assigned one of the other roles | Uses the assigned role; Anonymous is ignored. |
| 2a | Only invited people | n/a | Anonymous | `403` — `Anonymous access not enabled for this application` |
| 2b | Anyone with the link | No | Anonymous | `403` — `Anonymous access not enabled for this build` |

***

## The anonymous session

Anonymous traffic is isolated using a session ID — there is no user identity to bind state to.

* **Header:** `X-Fx-Anonymous-Session-Id`
* **Issued by:** the backend, on the first anonymous request that doesn't already carry one. The new session ID comes back in the response header `X-Fx-Anonymous-Session-Id` (exposed via `Access-Control-Expose-Headers`; the exposed-header list is controlled by the `APPLICATION_CORS_EXPOSEDHEADERS` env var, which carries this header by default).
* **Maintained by:** the SDK / container app. After receiving the session ID, the client must include it on every subsequent anonymous request.
* **Scope:** one anonymous session can only access the process and UI flow instances it created. Another session that knows the `processInstanceUuid` cannot read or act on it.
* **Lifetime:** fire-and-forget. Closing the browser ends the session. There is no resume mechanism in 5.9.0.

> [!WARNING]
>
> **Tokens take precedence over anonymous mode.** If the client sends an `Authorization: Bearer …` header, the backend treats the request as authenticated and ignores the anonymous session ID. There is no fallback to anonymous when a bearer token is invalid or expired — the request returns `401`.
>
> A common bug: a user logs in on `/private`, then opens `/public` in the same browser. The persisted bearer is attached to public-route requests and the backend returns the authenticated user's data. Container apps must scrub the `Authorization` header on public routes — see [SDK behaviour](#sdk-and-container-app-behaviour) below.

### Public build, public assets

Once a runtime build is published with the Anonymous role and the app is shared publicly, the build is considered **public**. All assets inside it are reachable anonymously — except UI flows and processes that have not been explicitly opened to the Anonymous role.

Public assets in a public build:

* **Enumerations** — `/rtm/api/runtime/app/{appId}/build/{buildId}/rt/enumeration/...`
* **Substitution tags** — `/rtm/api/runtime/app/{appId}/build/{buildId}/rt/substitutiontag`
* **Media files** — `/rtm/api/runtime/app/{appId}/build/{buildId}/rt/mediafile`
* **Themes** — `/cms/api/wks/{workspaceId}/themes/uuid/{themeId}/platform/{platform}/compiled` (globally unauthenticated)
* **Fonts** — `/cms/api/fonts` (globally unauthenticated)

Restricted assets (require authentication and a role grant):

* UI flows not configured with Anonymous
* Processes not configured with Anonymous
* Chat, task manager, and view-scoped endpoints — see [Restricted endpoints](#restricted-endpoints) below

***

## SDK and container app behaviour

### Renderer initialization

Process and UI flow renderer components decide their mode **at initialization** from the `authToken` parameter:

* `authToken` **present (non-null)** → renderer runs in authenticated mode. All outgoing requests carry the bearer token. If the token expires mid-flow the renderer surfaces `401` errors (existing behaviour).
* `authToken` **absent (null/undefined)** → renderer runs in anonymous mode. The renderer omits the `Authorization` header and uses `X-Fx-Anonymous-Session-Id` instead.

> [!WARNING]
>
> **The mode is locked at init.** Switching `authToken` from `null` to a value after the renderer has started will not flip it into authenticated mode, and vice versa. If you need both modes in the same container app, mount separate renderer instances on separate routes (e.g. `/public` and `/private`).

### Container apps

A container app that hosts both public and authenticated routes must guarantee that public routes do **not** pass an `Authorization` header to the renderer. The renderer uses an isolated HTTP client at runtime, so whatever the container does for its own pages does not automatically leak in — but if the container reads a token from `localStorage` and supplies it to the renderer, the token-precedence rule above applies and anonymous mode is silently bypassed.

The recommended pattern:

* Public route (e.g. `/public/...`) → mount renderer with `authToken={null}`
* Private route (e.g. `/private/...`) → mount renderer with `authToken={accessToken}`
* Clear any stored bearer when the user navigates from `/private` to `/public`.

### Platform support

| Capability | Web (React, Angular) | iOS | Android |
| - | - | - | - |
| Anonymous start of process / UI flow | ✅ | ✅ | ✅ |
| Anonymous session ID handling | ✅ | ✅ | ✅ |
| File uploads with anonymous session | ✅ | ✅ | ✅ |
| SSE streams (limited types) | ✅ | ✅ | ✅ |
| Task manager surfaces | n/a — restricted | n/a — restricted | n/a — restricted |
| Chat surfaces | n/a — restricted in 5.9.0 | n/a — restricted in 5.9.0 | n/a — restricted in 5.9.0 |

***

## What anonymous users can call

Anonymous traffic is allowed on a curated set of runtime endpoints. The full reference is the SDK endpoint table — the summary below is grouped by capability. Endpoints flagged **session ID required** must include `X-Fx-Anonymous-Session-Id`; the backend rejects requests where the session ID does not match the entity it refers to (`403 Anonymous session not found for entity`).

### Allowed

| Capability | Endpoints | Session ID |
| - | - | - |
| Build info | `/rtm/api/runtime/wks/{wks}/app/{appId}/build/info` `/rtm/api/runtime/process-instance/{piUuid}/build/info` `/rtm/api/runtime/ui-flow-session/{sessionUuid}/build/info` | Required on the last two |
| Process — start | `POST /rtm/api/runtime/app/{appId}/build/{buildId}/process-name/{name}/start` `POST /rtm/api/runtime/app/{appId}/build/{buildId}/process-rdi/{rid}/start` | Optional on start — issued by BE if missing |
| Process — status, data, details, actions, dismiss, subprocess | `GET /api/runtime/process/{piUuid}/status` `GET .../data`, `.../data/{templateConfigId}/context/{ctx}` `GET .../node/{nodeDefId}/context/{ctx}/details` `POST .../token/{tokenUuid}/ui-action/{uiActionUuid}/context/{ctx}/execute` `POST .../ui-action/.../subprocess` `POST .../dismiss` | Required |
| UI flow — start | `POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flows/{name}` `POST /rtm/api/runtime/app/{appId}/build/{buildId}/ui-flow-rdi/{rid}` | Optional on start |
| UI flow — status, file upload | `GET /api/runtime/ui-flow-session/{uuid}/status` `POST /api/runtime/wks/{wks}/appId/{appId}/ui-flow/{uuid}/upload` `POST .../upload-multiple` | Required |
| Workflow — start from UI flow | `POST /rtm/api/runtime/wks/{wks}/app/{appId}/rdi/{rid}/start-workflow?uiFlowSessionUuid={uuid}` | Required. The user must also be authorized for the parent UI flow. |
| Data model paths (gated by Anonymous role on the resource) | `GET /rtm/api/runtime/process-instance/{piUuid}/data-model-paths` `GET .../app/{appId}/build/{buildId}/process-name/{name}/data-model-paths` (and equivalent for processes by `rdi`, and UI flows by `ui-flow-session`, `ui-flow-name`, `ui-flow-rdi`) | Required on the process-instance and ui-flow-session forms |
| CMS — enumerations, substitution tags, media | See [Public build, public assets](#public-build-public-assets) above | n/a |
| Themes, fonts | Globally unauthenticated | n/a |
| SSE — process instance | `GET /api/events/process-instance/{piUuid}?offset={offset}` | Required |
| SSE — generic, allowed types only | `GET /api/events/generic/{id}?type={type}&offset={offset}` **Allowed types:** `UI_FLOW_WORKFLOW_RESPONSE`, `UI_FLOW_FILE_UPLOAD`, `UI_FLOW_FILE_UPLOAD_MULTIPLE` | Required — used to correlate the entity with the session |
| File uploads (UI flow scope) | `POST /document/internal/wks/{wks}/temp-files/upload` `POST .../upload-multiple` | Required |

### Restricted endpoints

The following are **never** served anonymously, regardless of the public gates:

* **Task manager** — every `/rtm/api/runtime/app/.../view/...` and `/task/api/tasks/...` endpoint
* **Chat** — `/rtm/api/runtime/wks/.../conversations`, chat-workflow start, chat-session upload (postponed past 5.9.0)
* **View-based SSE** — `/api/events/view/{viewId}`
* **Generic SSE other types** — `CHAT_WORKFLOW_RESPONSE`, `CHAT_FILE_UPLOAD`
* **Internal runtime endpoints** — anything under `/rtm/api/runtime-internal/wks/.../app-version/...` (including `process-resource-id/.../start/test` and `start/email-trigger`)

***

## Error responses

| Status | Body `detail` | Cause |
| - | - | - |
| 403 | `Anonymous access not enabled for this application` | The app is not publicly shared (General Access is **Only invited people**). |
| 403 | `Anonymous access not enabled for this build` | The build does not carry the Anonymous role on the requested resource. |
| 403 | `Anonymous session not found for entity` | The `X-Fx-Anonymous-Session-Id` header does not match the session the entity was created with. |
| 401 | `Full authentication is required to access this resource` | The endpoint requires authentication and no bearer token was provided. |
| 401 | (any) | A bearer token was sent but invalid or expired. The backend does **not** fall back to anonymous mode in this case. |

***

## CORS requirements

Two headers must be in the gateway's `Access-Control-Allow-Headers` allow-list and `Access-Control-Expose-Headers` response list:

```yaml theme={"dark"}
Access-Control-Allow-Headers:
  - X-Fx-Anonymous-Session-Id
  - Fx-BuildId

Access-Control-Expose-Headers:
  - X-Fx-Anonymous-Session-Id
```

`Fx-BuildId` is required on SSE connections so the backend can route the stream to the correct build when no user identity is present.

The default FlowX `commons-security-lib` CORS configuration includes both headers from 5.9.0. If you override CORS in your deployment, make sure these are preserved.

***

## Limitations (5.9.0)

* **Fire-and-forget sessions** — closing the browser ends the session. No resumption.
* **No task assignment** to anonymous users. Anonymous can start and act on a process they own via the session ID; they cannot be assigned an existing task.
* **Mode is locked at renderer init** — see [Renderer initialization](#renderer-initialization).
* **No anonymous chat** in 5.9.0.
* **Subprocesses** — `data-model-paths` calls for subprocesses are gated by the same session-ID check as the root process instance.
* **Anonymous role cannot be removed or renamed.** It can only be added to or removed from a project's End User Roles.

***

## Related resources

> [card] [Swimlanes](./swimlanes)
>
> Configuring swimlane roles, including Anonymous, for process steps.

> [card] [Business filters](./business-filters)
>
> Other role-driven runtime filtering.

> [card] [Roles & permissions matrix](../../../setup-guides/access-management/roles-permissions-matrix)
>
> Full list of system and end-user roles, with allowed operations.

> [card] [Web SDK renderer](../../../sdks/react-renderer)
>
> `authToken` initialization rules and container-app patterns.


# Business filters
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/user-roles-management/business-filters

An optional attribute, from the authorization token, that can be set to restrict access to process instances based on a business specific value (for example, bank branch name).

Business filters provide an additional layer of access control for runtime process instances by restricting access based on business-specific attributes such as bank branch, department, or region.

> [!NOTE]
>
> **Important distinction:** Business filters only apply to **runtime access** (container apps, task manager). They do not affect access in **FlowX Designer**, which is controlled by workspace and project-level permissions.

**Use case example**: in a banking app, you might need to ensure that only users from a specific branch can view and interact with process instances initiated from that branch.

## How business filters work

Business filters work in combination with runtime permissions, not as a replacement for them.

### Access control by context

| Context | Access controlled by |
| - | - |
| **FlowX Designer** | Workspace and project-level permissions only |
| **Container apps (runtime)** | Runtime permissions AND business filters (both required) |

Business filters add an additional restriction layer but do not bypass existing runtime permissions. Both conditions must be satisfied for a user to access a process instance.

## Prerequisites

Before configuring business filters, ensure you have:

* Access to your identity provider (IdP) configuration
* Organization administrator role to manage user attributes
* Understanding of your business access requirements (for example, which users should access which process instances)

## Configuration

Follow these steps to implement business filters in your app.

### 1. Configure the identity provider mapper

Configure a mapper in your identity management platform to add the business filter attribute to the authorization token as a claim. This mapper creates the connection between user attributes and the token claim that gets evaluated at runtime.

> [!WARNING]
>
> The business filter attribute must always be available on the token under the same key. Inconsistent mapper configuration can cause access control issues in production environments.

> [card] [Identity provider mapper configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#user-attribute-mapper)
>
> View detailed instructions for configuring the user attribute mapper

After configuration, the `businessFilter` attribute becomes visible at the user level:

![Business filter attribute displayed at user level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/bsF.png)

### 2. Assign business filter values to users

Assign business filter values to users through one of the following methods:

* **Identity provider**: Directly in the user profile settings
* **FlowX Designer**: Through the user management interface

> [!WARNING]
>
> **Important:** Business filter values must be set directly on user attributes in your identity provider, not only inherited from groups.
>
> When assigning business filters in FlowX Designer, you must use the `businessFilter` key.
>
> ![Assigning business filter values in Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/bsF1.png)

Users can have multiple business filter values assigned. For example: `["branch_01", "branch_02"]`

> [!NOTE]
>
> **Technical note:** While group-level attributes can propagate to the JWT via mappers, Task Manager uses a different mechanism to filter assignable users. It queries user attributes directly from the identity provider when listing users for task assignment. This means business filters must exist as direct user attributes, not only as group memberships.

### 3. Set business filters in process definition

Add a [**business rule action**](../../building-blocks/actions/business-rule-action/business-rule-action) in your process definition to store the business filter values in the process parameters.

**Syntax:**

Single value:

```javascript theme={"dark"}
output.put("task", {"businessFilters": ["branch_01"]});
```

Multiple values:

```javascript theme={"dark"}
output.put("task", {"businessFilters": ["branch_01", "branch_02"]});
```

> [!WARNING]
>
> **Important:** When configuring the business rule action node that sets `task.businessFilters`, you must also enable the **Update Task Manager** toggle in the node configuration. This ensures that the business filter values are properly propagated to Task Manager.

> [!NOTE]
>
> **Best practice:** Set business filters early in the process flow, typically on an automatic action at the start of the process.

## Runtime behavior

Once business filters are configured on a process instance, access restrictions apply based on the context:

We have a process instance with the business filter value `"branch_01"` (added in the process definition) and a user with the business filter value `"branch_01"`. The second user does not have the business filter value.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rt_pi_bf.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/rt_bf.png)

> [!NOTE]
>
> Business filters are applied to the process instance at runtime.
>
> * in the left screen there is a user with the business filter value `"branch_01"` (the process instance is visible to this user)
> * in the right screen there is a user without the business filter value (the process instance is not visible to this user)

### Task manager

Only users with matching business filter values can view and interact with tasks from the process instance.

![Task manager business filter example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/tm_bf.png)

When assigning or reassigning tasks to other users, the list of assignable users is filtered based on business filters. The system queries user attributes directly from the identity provider to determine which users can be assigned to a task.

> [!NOTE]
>
> Business filter checks apply to the tasks themselves. Custom views remain controlled by Designer permissions.

### Container apps

Only users with matching business filter values can execute READ operations on the process instance, such as:

* GET status
* GET details

### Designer

Business filters do not apply in FlowX Designer. All users with appropriate project permissions can view the process instance regardless of their business filter values.

## Example scenario

This example demonstrates how to restrict access to process instances based on bank branch affiliation.

### Setup

**Step 1**: configure the identity provider mapper for the `businessFilter` attribute.

**Step 2**: assign business filter values to users:

* User A: `"branch_downtown"`
* User B: No business filter assigned

**Step 3**: add a business rule in your process definition:

```javascript theme={"dark"}
output.put("task", {"businessFilters": ["branch_downtown"]});
```

### Expected behavior

When a process instance runs with this configuration:

| User | Business filter | Runtime access | Designer access |
| - | - | - | - |
| User A | `"branch_downtown"` | ✓ Can access | ✓ Can access (if has project permissions) |
| User B | None | ✗ Cannot access (even with runtime permissions) | ✓ Can access (if has project permissions) |

This demonstrates that:

* Business filters enforce runtime restrictions
* Designer access remains independent of business filters
* Runtime permissions alone are insufficient without matching business filter values


# Swimlanes
Source: https://docs.flowx.ai/5.9/docs/platform-deep-dive/user-roles-management/swimlanes

Swimlanes provide a way of grouping process nodes by process participants.

Using swimlanes we can make sure only certain user roles have access to certain process nodes.

In certain scenarios, it is necessary to restrict access to specific process [**nodes**](../../building-blocks/node/) based on user roles. This can be achieved by organizing nodes into different swimlanes.

Each swimlane can be configured to grant access only to users with specific runtime roles. Roles are defined at the organization level and listed on each project version. Which user or end-user group holds a role on a given solution is configured from the Share modal on the Solutions page — see [Runtime authorization](/5.9/setup-guides/access-management/runtime-authorization) for the full model (5.8.0+). Up to 5.7.0, the chosen identity provider platform was the source of truth for runtime roles.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/multiple_swimlanes.png)

Depending on the type of node added within a swimlane, only users with the corresponding swimlane roles will have the ability to initiate process instances, view process instances, and perform actions on them.

[Scopes and roles for managing processes](../../../setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/swimlanes_permissions.gif)

When creating a new process definition, a default swimlane will automatically be added.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/swimlanes_default.gif)

As the token moves from one node to the next, it may transition between swimlanes. If a user interacting with the process instance no longer has access to the new swimlane, they will observe the process in read-only mode and will be unable to interact with it until the token returns to a swimlane they have access to.

Users will receive notifications when they can no longer interact with the process or when they can resume actions on it.

***

## Related resources

> [card] [Permission-based expressions](../../building-blocks/process/permission-based-expressions)
>
> Control UI element visibility and interaction based on user roles

> [card] [Access roles configuration](/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes)
>
> Set up scopes and roles for managing processes

> [card] [From Zero to Build course](https://academy.flowx.ai/explore/5from-zero-build-onboarding-project)
>
> End-to-end project build course covering swimlanes, permissions, and all major platform features


# Error glossary
Source: https://docs.flowx.ai/5.9/docs/resources/error-glossary

The most common FlowX.AI error messages - what each one means, what usually causes it, and how to fix it.

This page lists the error messages FlowX.AI users hit most often, with the exact message text so you can find it by search. Each entry explains what the error means, its usual causes, and where to fix it.

> [!TIP]
>
> Copy the exact error message into the search bar or the AI assistant - the entries below use the platform's exact wording.

## How FlowX reports errors

**Process errors (incidents)**: when a process instance hits a problem, the error details attached to the instance include a **Source** (the node or action that failed), a **Cause Type** (one of the messages below), and a **Timestamp**. Example of what you'll see:

```
Source: ACTION (set_premium)
Cause Type: Invalid business rule expression.
Type: Business Rule
Timestamp: 2026-06-01T09:07:31.717Z
```

**API errors**: REST endpoints return errors in `application/problem+json` format, with a `type` of `https://www.flowx.ai/error`, a human-readable `title`, and an HTTP `status`:

```json theme={"dark"}
{
  "type": "https://www.flowx.ai/error",
  "title": "Entity not found.",
  "status": 404
}
```

***

## Business rules and gateways

### Invalid business rule expression.

The script attached to a business rule action could not be parsed or executed.

**Common causes:**

* Syntax that is invalid for the selected scripting language - a rule written for one language while the action is set to another.
* Referencing process data keys that don't exist yet at the time the rule runs.
* Language features that the embedded runtime doesn't support - the rule can pass an editor check but fail at runtime.

**Fix:** open the business rule on the failing node, confirm the selected language matches the syntax, and test with the data the instance actually has at that point. See [Business rule action](/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action).

### Could not execute condition.

A condition expression on an action failed to evaluate. Same causes and fixes as invalid business rule expressions - check the expression's language and the data it references.

### Invalid gateway rule. / The rule returned no result. / Missing sequence from gateway rule evaluation.

An exclusive gateway could not pick an outgoing branch:

* **Invalid gateway rule.** - the rule expression itself failed to evaluate.
* **The rule returned no result.** - the rule ran, but no branch condition matched the instance data.
* **Missing sequence from gateway rule evaluation.** - the rule picked a branch that has no outgoing sequence configured.

**Fix:** make sure the gateway's conditions cover every possible data state (add a default branch) and that each branch connects to a next node. See [Exclusive gateway](/5.9/docs/building-blocks/node/exclusive-gateway-node).

### Executing a script produced an error!

A **Script node inside an integration workflow** (not a process business rule) failed - the message is followed by the underlying cause, for example `SyntaxError: expected '(' at line 4, column 9`.

**Fix:** open the workflow's Script node and correct the JavaScript or Python code at the reported line. Test the node individually before re-running the workflow. See [Integration Designer](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#script-node).

***

## Timers

### Invalid timer definition. / Timer expression is not valid

The timer event's expression could not be parsed - typically a malformed cron or ISO 8601 duration expression.

**Fix:** validate the expression format against [Timer expressions](/5.9/docs/building-blocks/node/timer-events/timer-expressions).

### Timer could not be triggered due to invalid format of process parameter.

The timer is configured with a **dynamic value from process data**, and at runtime that parameter held a value that isn't a valid timer expression (wrong format, empty, or not a date/duration).

**Fix:** check the process data key the timer reads and make sure every path that reaches the timer sets it to a valid cron or ISO 8601 value. See [Timer events](/5.9/docs/building-blocks/node/timer-events/timer-events).

***

## Messages and correlation

### The message does not follow the custom integration data model.

A message received from an external system (or sent to one) doesn't match the data model configured on the integration.

The error often carries the underlying parser message appended after it. The most common variant is:

```
The message does not follow the custom integration data model. Unrecognized token '$': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
```

**`Unrecognized token '$'`** means the message body wasn't valid JSON when the engine parsed it - almost always because a `${...}` placeholder in the body did not resolve and was sent through as literal text. That happens when the process data key the placeholder references doesn't exist (or is misspelled) at the moment the message is sent.

**Fix:**

* For the `Unrecognized token '$'` variant: check every `${...}` placeholder in the message body against the instance's process data at the point the Send Message Task runs - the referenced keys must exist and hold values by then.
* Otherwise: compare the actual message payload against the data model defined for the integration - field names and structure must match exactly. See [Integrations](/5.9/docs/platform-deep-dive/integrations/integrations-overview).

### Invalid send message structure. / Invalid receive message structure.

The data mapped on a Send Message Task or Receive Message Task doesn't match what the node expects - usually a mapping that references missing keys or produces the wrong shape.

**Fix:** review the node's data mapping against the message structure. See [Message events](/5.9/docs/building-blocks/node/message-events/message-events).

### Correlation errors on throw and catch events

* **Correlation value null or empty for throw event.** / **Correlation key null or empty for throw event.** / **Event name null or empty for throw event.** - the throw event is missing its identification, usually because the process data key used as correlation is empty at runtime.
* **No catch events with event name and correlation value.** - the message was thrown, but no waiting catch event matched both the event name and the correlation value.
* **Duplicated correlation value.** - more than one waiting catch event matched the same correlation value, so the message can't be delivered unambiguously.

**Fix:** make sure the throw and catch events use the same event name, and that the correlation key resolves to a unique, non-empty value on both sides. See [Message events](/5.9/docs/building-blocks/node/message-events/message-events).

> [!NOTE]
>
> **Token waits forever at a Receive Message Task?** That is usually not an error but a correlation miss: the reply arrived with a different event name or correlation value than the catch event expects, or the workflow/subprocess completed without sending it. Check the three correlation errors above first.

***

## Integration workflow output

The first two errors below appear as a `WORKFLOW_PARAMETERS` incident on the process instance, with the Receive Message Task as the source and a cause type of `Invalid or incomplete workflow output`. The third surfaces in the workflow run details, on the failed End node.

### The mandatory output parameters of the workflow are missing at runtime.

The message appears on two surfaces with slightly different wording: the process incident reads `The mandatory output parameters of the <workflow> workflow are missing at runtime.`, while the workflow run details read `The following mandatory output parameters of the <workflow> workflow are missing at runtime: <parameter>.` - the run details name the missing parameter, so start there.

The workflow reached an End node, but a parameter declared in the workflow's output schema resolved to no value. Declared output parameters are a runtime contract: the workflow run fails when any of them ends up empty, and the calling process records the incident.

The data source call itself usually succeeded - the problem is the End node's output mapping expression. A placeholder that references a non-existent key resolves **silently to null** instead of raising an error, so this message is the only symptom.

**Common causes:**

* A misspelled key in the End node's output mapping - for example `${responeKey.data}` instead of `${responseKey.data}` (the Response Key configured on the REST node).
* An `input.` or `output.` prefix inside the placeholder - use the bare key: `${responseKey.data}`, never `${output.value}`.

**Fix:** open the workflow's End node output mapping and point every declared parameter at a key that exists at that point in the workflow. For a REST result, the response body lives at `${<responseKey>.data}`, where `<responseKey>` is the Response Key set on the REST node. Run the workflow from the editor and open the End node in the run details - it shows the exact input it received and the output JSON it produced, so a `null` value is immediately visible. See [End node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#end-node).

### Workflow output cannot be appended to the process instance due to missing mapping in the data stream.

Full form: `<workflow> workflow output cannot be appended to the process instance due to missing mapping in the data stream.`

The workflow finished and returned its output, but the **Receive Message Task** waiting for it has no output mapping saved on its data stream, so the engine doesn't know which process attribute should receive the result.

This often happens after the mapping was configured on screen but never persisted: in the mapping modal, **Test** only previews the result. Click **Confirm** to store the mapping, then save the node itself.

**Fix:** on the Receive Message Task, open the **Integration Output** data stream and the output mapping for the workflow's End node, map the workflow output to a process attribute, click **Confirm**, and save the node. See [Integration Output](/5.9/docs/building-blocks/node/message-send-received-task-node#integration-output).

### Executing an end node produced an error!

Shown as the run error in the workflow run details, with the End node marked **FAILED** and its output `null`. The End node could not render its return payload - most often because the payload stops being valid JSON once the `${...}` placeholders are substituted. Placeholders are substituted as **raw text**, so whatever the key resolves to lands in the payload verbatim.

Plain-text API responses are the classic trigger. A `text/plain` endpoint typically returns its value with a trailing newline (for example `"2395\n"`), and a raw newline inside a JSON string literal is invalid JSON. For such a value, the usual quoting rule inverts:

* `{"value": ${responseKey.data}}` - **works** when the value is numeric: the trailing newline falls outside the number, where JSON treats it as whitespace.
* `{"value": "${responseKey.data}"}` - **fails**: the newline lands inside the string literal.

**Fix:** keep the placeholder unquoted when the resolved value is a number or boolean. If the value must be a string, or the response may carry other control characters, clean it before the End node - for example a Script node with `output.value = input.responseKey.data.trim();` - and reference the cleaned key. The failed End node in the run details shows the exact input it received, which makes the offending character visible.

> [!WARNING]
>
> A failed workflow reply is not retried. A process instance whose workflow call failed with any of these errors stays blocked at the Receive Message Task permanently - after fixing the configuration, always test with a **new** process instance.

***

## Subprocesses

### Missing subprocess definition or a published version. / The subprocess couldn't start because we couldn't find a published version.

The parent process references a subprocess that either doesn't exist in the project (or its dependencies) or has no published version in the active build.

**Fix:** publish the subprocess and make sure the build that runs includes it. See [Subprocess](/5.9/docs/building-blocks/process/subprocess).

### Incorrect action configuration, the subprocess is missing or is not referenced correctly.

The Start Subprocess action (or embedded subprocess node) points at a subprocess name that can't be resolved - renamed, moved, or not referenced through the right dependency.

**Fix:** re-select the subprocess in the action/node configuration. See [Subprocess](/5.9/docs/building-blocks/process/subprocess).

### Could not render subprocess due to multiple swimlanes or missing Parent Process Area.

An embedded subprocess can't render its UI. The platform requires the embedded subprocess to have **exactly one swimlane** and to define a **Parent Process navigation area** that its UI renders into - this error means one of the two is missing.

**Fix:** in the subprocess definition, reduce to a single swimlane and add a Parent Process navigation area for its UI. See [Subprocess](/5.9/docs/building-blocks/process/subprocess).

### SubProcess params cannot be parsed.

The data passed to the subprocess at start couldn't be parsed - usually a mapping that produces malformed or unexpected data.

**Fix:** check the input mapping on the subprocess start configuration.

### Reference path not found in slice.

Shown when you save a data mapper, for example the input or output mapping of a call activity or a Start Subprocess action. In this message, the slice is the set of **Input parameters** or **Output parameters** defined on each side of the mapping. Every attribute a mapping row uses must exist in the parameters of its side. If one is missing, the save is rejected. The same check runs when you save mappings for reusable UI templates and custom components.

**Fix:** open the mapping and look for rows whose source or target attribute no longer appears in the parameters, for example after it was removed from the subprocess input parameters. Remove or re-map those rows, or add the attribute back to the parameters, then save again. If the subprocess comes from a library, update the dependency build first so the parent sees its current parameters. See [Managing parameter changes](/5.9/docs/building-blocks/process/data-mappers#managing-parameter-changes).

***

## Export and import

### Resource format incompatibility.

Shown when importing a project version or build. Two exact variants:

```
Resource format incompatibility: the resource format versions in the import do not match with current resource format versions on the environment.
```

```
Resource format incompatibility: the resource format versions in the import are missing.
```

Each resource type in an export archive is stamped with a format version. The import is rejected when those stamps don't match what the target environment supports (**do not match** variant - the archive was exported from a platform version whose resource formats differ from the target's) or aren't present at all (**are missing** variant - typically an archive produced by a much older version, before format stamping).

A sibling error, **`Configuration parameter format incompatibility: the config params format versions in the import do not match with current config params format versions on the environment.`**, reports the same condition for configuration parameters.

**Fix:** re-export from a source environment running a platform version compatible with the target, and use the export option that targets the destination version where available - incompatible resources are then excluded and listed in the manifest instead of failing the import. See [How incompatible content is handled](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#how-incompatible-content-is-handled).

***

## API errors

### Entity not found.

A `404` in the standard error envelope: the resource referenced by the request - a file, document, process instance, or other entity - doesn't exist or isn't accessible with the caller's permissions. Frequently seen on file previews and document URLs when the file ID is wrong or the underlying file was deleted.

**Fix:** verify the identifier being requested and that the caller's role can access it.

***

## Related resources

> [card] [Glossary](/5.9/docs/getting-started/glossary)
>
> The FlowX.AI vocabulary - what each core term means.

> [card] [Cookbooks](/5.9/cookbooks/overview)
>
> Tutorials, guides, and reusable patterns.


# Android SDK
Source: https://docs.flowx.ai/5.9/sdks/android-renderer

Install and configure the FlowX.AI Android SDK to render process-driven UI in native Android apps. Requires Android 8.0+ (API 26).

## Android project requirements

System requirements:

* **minSdk = 26** (Android 8.0)
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

## Installing the library

1. Add the maven repository in your project's `settings.gradle.kts` file:

```kotlin theme={"dark"}
dependencyResolutionManagement {
    ...
    repositories {
        ...
        maven {
            url = uri("https://nexus-jx.dev.rd.flowx.ai/repository/flowx-maven-releases/")
            credentials {
                username = "your_username"
                password = "your_password"
            }
        }
    }
}
```

2. Add the library as a dependency in your `app/build.gradle.kts` file:

```kotlin theme={"dark"}
dependencies {
    ...
    implementation("ai.flowx.android:sdk:<version>")
    ...
}
```

> [!NOTE]
>
> Replace `<version>` with the correct version corresponding to your platform version.\\
>
> To find the right version, navigate to:
> `Release Notes → Choose your platform version → Deployment guidelines → Component versions`

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**

### Public API

The SDK library is managed through the `Flowx` singleton instance, which exposes the following methods:

| Name | Description | Definition |
| - | - | - |
| `init` | Initializes the FlowX SDK. Must be called in your application's `onCreate()` | `fun init(context: Context, config: Config, customComponentsProvider: CustomComponentsProvider? = null, customStepperHeaderProvider: CustomStepperHeaderProvider? = null, customLoaderProvider: CustomLoaderProvider? = null, analyticsCollector: AnalyticsCollector? = null, onNewProcessStarted: NewProcessStartedHandler.Delegate? = null)` |
| `setAccessToken` | Updates the access token | `fun setAccessToken(accessToken: String?)` |
| `setupTheme` | Sets up the theme to be used when rendering a process | `fun setupTheme(workspaceUuid: String, appearance: ThemeAppearance = ThemeAppearance.LIGHT, themeUuid: String, fallbackThemeJsonFileAssetsPath: String? = null, @MainThread onCompletion: () -> Unit)` |
| `changeLocaleSettings` | Changes the current locale settings (i.e. locale and language) | `fun changeLocaleSettings(locale: Locale, language: String)` |
| `startProcess` | Starts a FlowX process instance, by returning a `@Composable` function where the process is rendered. | `fun startProcess(workspaceId: String, projectId: String, processName: String, params: JSONObject? = null, isModal: Boolean = false, onProcessStarted: ((String) -> Unit)? = null, onProcessEnded: (() -> Unit)? = null, closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null): @Composable () -> Unit` |
| `continueProcess` | Continues an existing FlowX process instance, by returning a `@Composable` function where the process is rendered. | `fun continueProcess(processUuid: String, isModal: Boolean = false, onProcessEnded: (() -> Unit)? = null, closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null): @Composable () -> Unit` |
| `startUiFlow` | Starts a FlowX UI Flow, by returning a `@Composable` function where the UI Flow is rendered. | `fun startUiFlow(workspaceId: String, projectId: String, uiFlowName: String, params: JSONObject? = null): @Composable () -> Unit` |

## Configuring the library

To configure the SDK, there are two things needed in the project's application class:

1. first, make it implement the `FlowxOwner` interface:

```kotlin theme={"dark"}
class MyApplication : Application(), FlowxOwner {
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() }
    // ...
}
```

2. then, call the `init` method inside the `onCreate()` method:

```kotlin theme={"dark"}
fun init(
    context: Context,
    config: Config,
    customComponentsProvider: CustomComponentsProvider? = null,
    customStepperHeaderProvider: CustomStepperHeaderProvider? = null,
    customLoaderProvider: CustomLoaderProvider? = null,
    logSink: LogSink.Collector? = null,
    analyticsCollector: AnalyticsCollector? = null,
    onNewProcessStarted: NewProcessStartedHandler.Delegate? = null,
)
```

#### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `context` | Android application `Context` | `Context` | Mandatory |
| `config` | SDK configuration parameters | `ai.flowx.android.sdk.api.Config` | Mandatory |
| `customComponentsProvider` | Provider for the `@Composable` custom components | `ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider?` | Optional. Defaults to `null`. |
| `customStepperHeaderProvider` | Provider for the `@Composable` custom stepper header view | `ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider?` | Optional. Defaults to `null`. |
| `customLoaderProvider` | Provider for the `@Composable` custom loader view | `ai.flowx.android.sdk.api.custom.loader.CustomLoaderProvider?` | Optional. Defaults to `null`. |
| `analyticsCollector` | Collector interface for SDK analytics events | `ai.flowx.android.sdk.api.analytics.AnalyticsCollector` | Optional. Defaults to `null`. |
| `logSink` | Collector interface for exposed logging events | `ai.flowx.android.sdk.api.logger.LogSink.Collector` | Optional. Defaults to `null`. |
| `onNewProcessStarted` | Callback for when a new process was started as a consequence for executing a `START_PROJECT` action | `ai.flowx.android.sdk.api.NewProcessStartedHandler.Delegate` | Optional. Defaults to `null`. |

• The `custom components` implementation is explained in [its own section](#custom-components).\

• The implementation for providing a `custom view for the header` of the [Stepper](../docs/building-blocks/process/navigation-areas#stepper) component is detailed in [its own section](#custom-header-view-for-the-stepper-component).\

• The implementation for providing a `custom loader` is explained in [its own section](#custom-loaders).\

• Collecting analytics events from the SDK is explained in [its own section](#collecting-analytics-events).\

• Handling the start of a new process while in a running process is explained in [its own section](#handling-start-of-a-new-process).\


#### Sample

```kotlin theme={"dark"}
class MyApplication : Application(), FlowxOwner {
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() }

    override fun onCreate() {
        super.onCreate()
        initFlowXSdk()
    }

    private fun initFlowXSdk() {
        Flowx.getInstance().init(
            context = applicationContext,
            config = object : Config {
                override val organizationId: String = "organization id"
                override val baseUrl = "URL to FlowX backend",
                override val imageBaseUrl = "URL to FlowX CMS Media Library",
                override val enginePath = "URL path segment used to identify the process engine service",
                override val language = "en",
                override val locale = Locale.getDefault(),
                override val validators: Map<String, (String) -> Boolean>? = mapOf("exact_25_in_length" to { it.length == 25 }),
                override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE,
            },
            customComponentsProvider = object : CustomComponentsProvider {...},
            customStepperHeaderProvider = object : CustomStepperHeaderProvider {...},
            customLoaderProvider = object : CustomLoaderProvider {...},
            analyticsCollector = { event ->
                // Process / Send the event to some specialized Analytics platform
            },
            onNewProcessStarted = { processInstanceUuid ->
                // Send a broadcast message to notify the Activity currently displaying the running process.
                // The Activity should handle the broadcast to reload and display the newly started process identified by `processInstanceUuid`.
            }
        )
    }
}
```

The configuration properties that should be passed as `Config` data for the `config` parameter above are:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `organizationId` | Id of the organization used by FLOWX to identify your installation | `String` | Mandatory |
| `baseUrl` | URL to connect to the FlowX back-end environment | `String` | Mandatory |
| `imageBaseUrl` | URL to connect to the FlowX Media Library module of the CMS | `String` | Mandatory |
| `enginePath` | URL path segment used to identify the process engine service | `String` | Mandatory |
| `language` | The language used for retrieving enumerations and substitution tags | `String` | Optional. Defaults to `en`. |
| `locale` | The locale used for date, number and currency formatting | `java.util.Locale` | Optional. Defaults to `Locale.getDefault()` |
| `validators` | Custom validators for form elements | `Map<String, (String) -> Boolean>?` | Optional. |
| `logEnabled` | Flag indicating if logs should be printed | `Boolean` | Optional. Defaults to `false` |

#### Where to find these values

The mandatory configuration values are properties of your FlowX deployment, not of the SDK. Your DevOps team holds them, in the same configuration the FlowX Designer web app connects through:

| Value | Where it comes from |
| - | - |
| `organizationId` | The UUID assigned at FlowX organization registration. It is the same value set as `ORGANIZATION_ID` on your backend services and it is also the name of your Keycloak user realm. All three must match. |
| `baseUrl` | The entry point of your FlowX backend, from your deployment's ingress configuration. |
| `imageBaseUrl` | The URL of the CMS Media Library module on your deployment, from the ingress configuration. If it is wrong, images and icons render blank. |
| `enginePath` | The URL path segment under which the process engine service is exposed, defined in your deployment's [ingress configuration](../setup-guides/ingress-configuration). On standard FlowX deployments this is `onboarding`. It is the mobile equivalent of the `PROCESS_API_PATH` variable used by the web container. If it is wrong, process start and advance calls return a 404 error. |

#### Custom validators

The `custom validators` map is a collection of lambda functions, referenced by *name* (i.e. the value of the `key` in this map), each returning a `Boolean` based on the `String` which needs to be validated.
For a custom validator to be evaluated for a form field, its *name* must be specified in the form field process definition.

> [!TIP]
>
> By looking at the example from above:
>
> ```kotlin theme={"dark"}
> mapOf("exact_25_in_length" to { it.length == 25 })
> ```
>
> if a form element should be validated using this lambda function, a custom validator named `"exact_25_in_length"` should be specified in the process definition.

## Using the library

### Authentication

To be able to use the SDK, **authentication is required**. Therefore, before calling any other method on the singleton instance, make sure that the access token is set by calling:

```kotlin theme={"dark"}
Flowx.getInstance().setAccessToken(accessToken = "your access token")
```

> [!TIP]
>
> Whenever the access token changes based on your own authentication logic, it must be updated in the renderer by calling the `setAccessToken` method again.

> [!TIP]
>
> Passing `null` or empty string (`""`) as an argument to the `setAccessToken` method clears the token

> [!WARNING]
>
> The SDK performs no authentication of its own: an authentication base URL or a Keycloak client ID are **not** SDK configuration parameters. Your container application runs its own OIDC flow against Keycloak and passes the resulting token through `setAccessToken`. If you are starting from the FlowX TemplateApp, the authentication values it sets belong to the application, not to the SDK.

### Theming

> [!WARNING]
>
> Prior setting up the theme, make sure the `access token` was set.\
> Check the [authentication](#authentication) section for details.

To be able to use styled components while rendering a process, the theming mechanism must be invoked by calling the `suspend`-ing `setupTheme(...)` method over the singleton instance of the SDK:

```kotlin theme={"dark"}
suspend fun setupTheme(
    workspaceUuid: String,
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: ThemeAppearance = ThemeAppearance.LIGHT,
    @MainThread onCompletion: () -> Unit
)
```

#### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceUuid` | UUID string identifier of the workspace that contains the theme to be loaded | `String` | Mandatory. Should not be empty |
| `themeUuid` | UUID string of the theme configured in FlowX Designer | `String` | Mandatory. Can be empty |
| `fallbackThemeJsonFileAssetsPath` | Android asset relative path to the corresponding JSON file to be used as fallback, in case fetching the theme fails and there is no cached version available | `String?` | Optional. Defaults to `null` |
| `appearance` | Indicator for the appearance of the theme (LIGHT, DARK) | `Flowx.ThemeAppearance` | Options. Defaults to `Flowx.ThemeAppearance.LIGHT` |
| `onCompletion` | `@MainThread` invoked closure, called when setting up the theme completes | `() -> Unit` | Mandatory |

> [!NOTE]
>
> If the `themeUuid` parameter value is empty (`""`), no theme will be fetched, and the mechanism will rely only on the fallback file, if set.\
> \\
>
> If the `fallbackThemeJsonFileAssetsPath` parameter value is `null`, there will be no fallback mechanism set in place, meaning if fetching the theme fails, the redered process will have no style applied over it's displayed components.

> [!NOTE]
>
> The SDK caches the fetched themes, so if a theme fetch fails, a cached version will be used, if available. Otherwise, it will use the file given as fallback.

#### Sample

```kotlin theme={"dark"}
viewModelScope.launch {
    Flowx.getInstance().setupTheme(
        workspaceUuid = "some workspace uuid string",
        themeUuid = "some uuid string",
        fallbackThemeJsonFileAssetsPath = "theme/a_fallback_theme.json",
        appearance = Flowx.ThemeAppearance.LIGHT,
    ) {
        // theme setup complete
        // do specific logic
    }
}
```

> [!TIP]
>
> The `fallbackThemeJsonFileAssetsPath` always search for files under your project's `assets/` directory, meaning the example parameter value is translated to `file://android_asset/theme/a_fallback_theme.json` before being evaluated.

> [!WARNING]
>
> Do not [start](#start-a-flowx-process) or [resume](#resume-a-flowx-process) a process before the completion of the theme setup mechanism.

### Changing current locale settings

The current `locale` and `language` can be also changed after the [initial setup](#configuring-the-library), by calling the `changeLocaleSettings` function:

```kotlin theme={"dark"}
fun changeLocaleSettings(locale: Locale, language: String)
```

#### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `locale` | The new locale | `java.util.Locale` | Mandatory |
| `language` | The code for the new language | `String` | Mandatory |

> [!WARNING]
>
> **Do not change the locale or the language while a process is rendered.**\\
>
> The change is successful only if made before [starting](#start-a-flowx-process) or [resuming](#resume-a-flowx-process) a process.

#### Sample

```kotlin theme={"dark"}
Flowx.getInstance().changeLocaleSettings(locale = Locale("en", "US"), language = "en")
```

> [!NOTE]
>
> The `Locale` satisfies the IETF BCP 47 standard for representing language and country/region codes.\
> \\
>
> More information regarding the standard can be found by reading [RFC 4647 "Matching of Language Tags"](https://datatracker.ietf.org/doc/html/rfc4647) and [RFC 5646 "Tags for Identifying Languages"](https://datatracker.ietf.org/doc/html/rfc5646).\
> \\
>
> An example of BCP 47 is `en-US` (language code `en` and country `US`).

### Start a FlowX process

> [!WARNING]
>
> Prior starting a process, make sure the [authentication](#authentication) and [theming](#theming) were correctly set up

After performing all the above steps and all the prerequisites are fulfilled, a new instance of a FlowX process can be started, by using the `startProcess` function:

```kotlin theme={"dark"}
fun startProcess(
    workspaceId: String,
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessStarted: ((String) -> Unit)? = null,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

#### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | The id of the workspace that contains the project and process to be started | `String` | Mandatory |
| `projectId` | The id of the project containing the process to be started | `String` | Mandatory |
| `processName` | The name of the process | `String` | Mandatory |
| `params` | The starting params for the process, if any | `JSONObject` | Optional. If omitted, if defaults to `JSONObject()` |
| `isModal` | Flag indicating whether the process can be closed at anytime by tapping the top-right close button | `Boolean` | Optional. It defaults to `false`. |
| \`onProcessStarted | Lambda function where you can do additional processing when the process starts | `((String) -> Unit)?` | Optional. It defaults to `null`. |
| `onProcessEnded` | Lambda function where you can do additional processing when the started process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |
| `closeModalFunc` | Lambda function where you should handle closing the process when `isModal` flag is `true` | `(CloseModalProcessScope.(processName: String) -> Unit)?` | Optional. It defaults to `null`. |

> [!TIP]
>
> The returned **[@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable)** function must be included in its own **[Activity](https://developer.android.com/reference/android/app/Activity)**, which is part of (controlled and maintained by) the container application.\
> \\
>
> This wrapper activity must display only the `@Composable` returned from the SDK (i.e. it occupies the whole activity screen space).

#### Sample

```kotlin theme={"dark"}
class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().startProcess(
                workspaceId = "your workspace id",
                projectId = "your project id",
                processName = "your process name",
                params: JSONObject = JSONObject(),
                isModal = true,
                onProcessStarted = { processInstanceUuid ->
                    // NOTE: possible processing could involve doing something based on the `processInstanceUuid` value received as argument
                },
                onProcessEnded = {
                    // NOTE: possible processing could involve doing something in the container app (i.e. navigating to a different screen)
                },
                closeModalFunc = { processName ->
                    // NOTE: possible handling could involve doing something differently based on the `processName` value
                },
            ).invoke()
        }
    }
    ...
}
```

### Resume a FlowX process

> [!WARNING]
>
> Prior resuming process, make sure the [authentication](#authentication) and [theming](#theming) were correctly set up

To resume an existing instance of a FlowX process, after fulfilling all the prerequisites, use the `continueProcess` function:

```kotlin theme={"dark"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

#### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `processUuid` | The UUID string of the process | `String` | Mandatory |
| `isModal` | Flag indicating whether the process can be closed at anytime by tapping the top-right close button | `Boolean` | Optional. It defaults to `false`. |
| `onProcessEnded` | Lambda function where you can do additional processing when the continued process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |
| `closeModalFunc` | Lambda function where you should handle closing the process when `isModal` flag is `true` | `(CloseModalProcessScope.(processName: String) -> Unit)?` | Optional. It defaults to `null`. |

> [!TIP]
>
> The returned **[@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable)** function must be included in its own **[Activity](https://developer.android.com/reference/android/app/Activity)**, which is part of (controlled and maintained by) the container application.\
> \\
>
> This wrapper activity must display only the `@Composable` returned from the SDK (i.e. it occupies the whole activity screen space).

#### Sample

```kotlin theme={"dark"}
class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().continueProcess(
                processUuid = "some process UUID string",
                isModal = true,
                onProcessEnded = {
                    // NOTE: possible processing could involve doing something in the container app (i.e. navigating to a different screen)
                },
                closeModalFunc = { processName ->
                    // NOTE: possible handling could involve doing something differently based on the `processName` value
                },
            ).invoke()
        }
    }
    ...
}
```

### `closeModalFunc` parameter

The `closeModalFunc` parameter is a function defined within the `CloseModalProcessScope` context.

This gives the ability to query for substitution tags or media library items to use them when handling this callback (i.e. showing an snackbar or an alert).

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}
```

#### Get a substitution tag value by key

```kotlin theme={"dark"}
fun replaceSubstitutionTag(key: String): String
```

All substitution tags will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns:

* the key's counterpart, if the `key` is valid and found
* the empty string, if the `key` is valid, but not found
* the unaltered string, if the key has the wrong format (i.e. not starting with `@@`)

#### Get a media item url by key

```kotlin theme={"dark"}
fun getMediaResourceUrl(key: String): String?
```

All media items will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns the `URL` string of the media resource, or `null`, if not found.

#### Sample

```kotlin theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    Flowx.getInstance().startProcess(
        workspaceId = "your workspace id",
        projectId = "your project id",
        processName = "your process name",
        isModal = true,
        onProcessStarted= { ... },
        onProcessEnded = { ... },
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    ).invoke()

    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            onDismissRequest = {},
            title = null,
            text = {
                Text(this@CloseModalProcessConfirmAlert.replaceSubstitutionTag("@@close_message")) // IMPORTANT: call `replaceSubstitutionTag` using the `CloseModalProcessScope` context
            },
            confirmButton = { ... },
            dismissButton = {
                Button(onClick = { show.value = false }) {
                    Text("Cancel")
                }
            }
        )
    }
}
```

### Start an UI Flow

> [!WARNING]
>
> Prior starting an UI Flow, make sure the [authentication](#authentication) and [theming](#theming) were correctly set up

After performing all the above steps and all the prerequisites are fulfilled, an UI Flow can be started, by using the `startUiFlow` function:

```kotlin theme={"dark"}
fun startUiFlow(
    workspaceId: String,
    projectId: String,
    uiFlowName: String,
    params: JSONObject? = null,
): @Composable () -> Unit
```

#### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | The id of the workspace that contains the project and UI Flow to be started | `String` | Mandatory |
| `projectId` | The id of the project containing the UI Flow to be started | `String` | Mandatory |
| `uiFlowName` | The name of the UI Flow | `String` | Mandatory |
| `params` | The starting params for the process, if any | `JSONObject` | Optional. If omitted, if defaults to `JSONObject()` |

> [!TIP]
>
> The returned **[@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable)** function must be included in its own **[Activity](https://developer.android.com/reference/android/app/Activity)**, which is part of (controlled and maintained by) the container application.\
> \\
>
> This wrapper activity must display only the `@Composable` returned from the SDK (i.e. it occupies the whole activity screen space).

#### Sample

```kotlin theme={"dark"}
class UiFlowActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().startUiFlow(
                workspaceId = "your workspace id",
                projectId = "your project id",
                uiFlowName = "your ui flow name",
                params = JSONObject(),
            ).invoke()
        }
    }
    ...
}
```

## Custom components

The container application should decide which custom component view to provide using the `componentIdentifier` configured in the UI designer.

A custom component receives `data` to populate the view and `actions` available to execute, as described below.\

It can also be validated and provide data back into the process when executing an action.

To handle custom components, an *implementation* of the `CustomComponentsProvider` interface should be passed as a parameter when initializing the SDK:

```kotlin theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}
```

#### Sample

```kotlin theme={"dark"}
class FxCustomComponentsProvider : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> object : CustomComponent {...}
            else -> null
        }
}
```

### CustomComponent

The implementation for providing a custom component is based on creating and binding a user defined [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function, through the `CustomComponent` interface:

```kotlin theme={"dark"}
interface CustomComponent {
    /**
     * Returns the [Composable]s for every custom component identifier defined in the FlowX Designer
     */
    val composable: @Composable CustomComponentScope.() -> Unit

    /**
     * This will be called when data is available for the custom component i.e. when the
     * User Task that contains the custom component is displayed.
     *
     * @param data used to populate the custom component
     */
    fun populateUi(data: Any?)

    /**
     * This will be called when actions are available for the custom component i.e. when the
     * User Task that contains the custom component is displayed.
     *
     * @param actions that need to be attached to the custom component (e.g. onClick events)
     */
    fun populateUi(actions: Map<String, CustomComponentAction>)

    /**
     * This will be called when executing an action, when the platform needs to know if the specified/marked components are valid.
     * Defaults to `true`.
     */
    fun validate(): Boolean = true

    /**
     * This will be called when executing an action, on computing the data to be sent as body on the network request.
     * Returning `null` (i.e. default) means it does not contribute with any data to be sent.
     */
    fun saveData(): JSONObject? = null
}
```

> [!TIP]
>
> The value for the `data` parameter received in the `populateUi(data: Any?)` could be:\\
>
> * `Boolean`
> * `String`
> * `java.lang.Number`
> * `org.json.JSONObject`
> * `org.json.JSONArray`
>
> The appropriate way to check and cast the data accordingly to the needs must belong to the implementation details of the custom component.

> [!TIP]
>
> Both validation and providing data back into process are optional, and, based on the needs, it may be included in the implementation or not.

### CustomComponentScope

The `composable` property of the [CustomComponent](#customcomponent) is a [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function which may be defined and run only within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
val composable: @Composable CustomComponentScope.() -> Unit
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun executeUploadAction(action: CustomComponentAction, fileUri: Uri, mimeType: String? = null, params: JSONObject? = null)
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

This allows calling predefined SDK methods for executing actions, querying for substitution tags, media resource URLs or obtaining enumerations data, directly from the custom component through the scope itself.

#### Execute action

The custom components which the container app provides may contain FlowX actions available for execution.\
\

These actions are received through the `actions` parameter of the `populateUi(actions: Map<String, CustomComponentAction>)` method.\
\

To run an action (e.g., on a click of a button in the custom component) you need to call the `executeAction` method, through the `CustomComponentScope` context:

```kotlin theme={"dark"}
fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
```

##### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `action` | Action object extracted from the `actions` received in the custom component | `ai.flowx.android.sdk.api.custom.components.CustomComponentAction` | Mandatory |
| `params` | Parameters needed to execute the `action` | `JSONObject?` | Optional. It defaults to `null` |

#### Execute upload action

A specific use case for executing actions from custom components involves uploading files into the FlowX platform.\
\

To run an upload action (e.g., on a click of a button in the custom component) you need to call the `executeUploadAction` method, through the `CustomComponentScope` context:

```kotlin theme={"dark"}
fun executeUploadAction(action: CustomComponentAction, fileUri: Uri, mimeType: String? = null, params: JSONObject? = null)
```

##### Parameters

| Name | Description | Type | Requirement |
| - | - | - | - |
| `action` | Action object extracted from the `actions` received in the custom component | `ai.flowx.android.sdk.api.custom.components.CustomComponentAction` | Mandatory |
| `fileUri` | The local URI for the file to be uploaded | `android.net.Uri` | Mandatory |
| `mimeType` | The mimeType of the file to be uploaded | `String?` | Optional. It defaults to `null` |
| `params` | Parameters needed to execute the `action` | `JSONObject?` | Optional. It defaults to `null` |

> [!TIP]
>
> It is recommended that a value for the `mimeType` parameter is always provided.\\
>
> When missing, the SDK tries computing it internally.

##### Sample

```kotlin expandable theme={"dark"}
class FileUploadCustomComponent : CustomComponent {
    var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel: FileUploadViewModel by lazy {
        FileUploadViewModel(actions = actions)
    }

    override val composable: @Composable CustomComponentScope.() -> Unit =
        @Composable {
            val rememberedViewModel = remember { viewModel }
            FileUpload(viewModel = rememberedViewModel)
        }

    override fun populateUi(data: Any?) { ... }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@FileUploadCustomComponent.actions.apply { clear(); putAll(actions) }
    }
}

@Composable
private fun CustomComponentScope.FileUpload(viewModel: FileUploadViewModel) {
    viewModel.setFlowxScope(this@FileUpload)
    val context = LocalContext.current
    val openDocumentLauncher =
        rememberLauncherForActivityResult(ActivityResultContracts.OpenDocument()) { uri ->
            uri?.let { viewModel.executeUploadAction(fileUri = it, mimeType = it.mimeType(context)) }
            Flowx.getInstance().configureUpdateState(enabled = true) // IMPORTANT: restore the SDK internal update mechanism after selecting a file to be uploaded
        }

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Button(
            onClick = {
                Flowx.getInstance().configureUpdateState(enabled = false) // IMPORTANT: disable SDK internal update mechanism while selecting a file to be uploaded
                openDocumentLauncher.launch(listOf("application/pdf").toTypedArray()) // select PDF files only
            }
        ) {
            Text(text = "Upload File")
        }
    }
}

private class FileUploadViewModel(
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    fun executeUploadAction(fileUri: Uri, mimeType: String?) {
        actions["uploadFile"]?.let { action ->
            if (this@FileUploadViewModel::flowxScope.isInitialized) {
                flowxScope.executeUploadAction(
                    action = action,
                    params = null,
                    fileUri = fileUri,
                    mimeType = mimeType,
                )
            }
        }
    }

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }
}

private fun Uri.mimeType(context: Context): String? = context.contentResolver.getType(this)
```

> [!NOTE]
>
> In order for the upload behave correctly, it's highly IMPORTANT to disable the SDK internal update mechanism while selecting a file.

#### Get a substitution tag value by key

```kotlin theme={"dark"}
fun replaceSubstitutionTag(key: String): String
```

All substitution tags will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns:

* the key's counterpart, if the `key` is valid and found
* the empty string, if the `key` is valid, but not found
* the unaltered string, if the key has the wrong format (i.e. not starting with `@@`)

#### Get a media item url by key

```kotlin theme={"dark"}
fun getMediaResourceUrl(key: String): String?
```

All media items will be retrieved by the SDK before starting the process and will be stored in memory.

Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url, through the `CustomComponentScope` context, using the method above, by providing the `key`.

It returns the `URL` string of the media resource, or `null`, if not found.

#### Obtain enumeration data

```kotlin theme={"dark"}
suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
```

Whenever the container app needs an enumeration data for populating the UI of the custom components, it can request the url, through the `CustomComponentScope` context, using the method above, by providing the `name` (and the `parentName`, if there's a hierarchy defined and the desired enumeration data (`name` is child of `parentName`).

It returns the enumeration data, as an `FxEnumeration` object, or `null`, if not found.

```kotlin theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

#### Sample

Among multiple existing custom components, there may be one that:

* allows the input of a value representing an `age`
* the value should be validated (e.g. to be at least 35 years old)
* the value will be passed back into the process
* execute an action, through the `CustomComponentScope` context, to skip setting the age

```kotlin expandable theme={"dark"}
class FxCustomComponentsProvider : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            when (componentIdentifier) {
                "other-custom-component-identifier" -> OtherCustomComponent()
                "age" -> AgeCustomComponent()
                else -> null
            }
        }
}

private class AgeCustomComponent() : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = AgeViewModel(data = data, actions = actions)

    override val composable: @Composable CustomComponentScope.() -> Unit
        get() = @Composable {
            Age(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@AgeCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@AgeCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    override fun validate(): Boolean = viewModel.isValid()

    override fun saveData(): JSONObject? = viewModel.buildDataToSave()
}

@Composable
private fun CustomComponentScope.Age(viewModel: AgeViewModel) {
    viewModel.setFlowxScope(this@Age) // IMPORTANT: keep a reference to the custom context/scope in order to access the available predefined SDK methods

    val age by viewModel.ageFlow.collectAsState()
    val error by viewModel.errorFlow.collectAsState()
    val isError by remember(error) { mutableStateOf(error.isNotBlank()) }

    Column {
        OutlinedTextField(
            value = age,
            onValueChange = { viewModel.updateAge(it) },
            modifier = Modifier.fillMaxWidth(),
            label = { Text("Age") },
        )

        if (isError) {
            Text(
                modifier = Modifier.fillMaxWidth(),
                text = error,
                style = TextStyle(fontSize = 12.sp),
                color = Color.Red,
                textAlign = TextAlign.Start,
            )
        }

        TextButton(
            onClick = { viewModel.executeSkipAction() }
        ) {
            Text(text = "Skip")
        }
    }
}

private class AgeViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope // IMPORTANT: keeps the custom context/scope which allows to call the available predefined methods exposed to custom component

    private val _ageFlow = MutableStateFlow("")
    val ageFlow: StateFlow<String> = _ageFlow.asStateFlow()

    private val _error = MutableStateFlow("")
    val errorFlow: StateFlow<String> = _error.asStateFlow()

    fun updateAge(text: String) {
        _ageFlow.value = text
    }

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    fun isValid(): Boolean = ageFlow.value.toIntOrNull().let {
        when {
            it == null -> false.also { _error.update { "Unrecognized format" } }
            it < 35 -> false.also { _error.update { "You have to be at least 35 years old" } }
            else -> true.also { _error.update { "" } }
        }
    }

    fun buildDataToSave(): JSONObject? = ageFlow.value.takeUnless { it.isBlank() }
        ?.let {
            JSONObject(
                """
            {
                "app": {
                    "age": "$it"
                }
            }
            """.trimIndent()
            )
        }

    fun executeSkipAction() {
        actions["skipAction"]?.let {
            if (this@AgeViewModel::flowxScope.isInitialized) { // IMPORTANT: if the custom context/scope was initialized, the action can be safely executed
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("AgeCustomComponent: `skipAction` action was not found")
    }
}

private class OtherCustomComponent() : CustomComponent {
    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            /* add some @Composable implementation */
        }

    override fun populateUi(data: Any?) {
        // extract the necessary data to be used for displaying the custom components
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        // extract the available actions that may be executed from the custom components
    }

    // Optional override, defaults to `true`.
    // Here one can pass validation logic from viewModel (e.g. by calling `viewModel.isValid()`)
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    // Here one can pass data to save from viewModel (e.g. by calling `viewModel.getDataToSave()`)
    override fun saveData(): JSONObject? = null
}
```

## Custom header view for the [STEPPER](../docs/building-blocks/process/navigation-areas#stepper) component

The container app can opt for providing a custom view to use for all the [Stepper](../docs/building-blocks/process/navigation-areas#stepper) components, as a replacement for the built-in header.\

The custom view receives `data` to populate its UI, as described below.

To provide a custom header for the [Stepper](../docs/building-blocks/process/navigation-areas#stepper), an *implementation* of the `CustomStepperHeaderProvider` interface should be passed as a parameter when initializing the SDK:

```kotlin theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}
```

#### Sample

```kotlin theme={"dark"}
class FxCustomStepperHeaderProvider : CustomStepperHeaderProvider {
    override fun provideCustomStepperHeader(): CustomStepperHeader? {
        return object : CustomStepperHeader {...}
    }
}
```

### CustomStepperHeader

To provide the custom header view as a [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function, you have to implement the `CustomStepperHeader` interface:

```kotlin theme={"dark"}
interface CustomStepperHeader {
    /**
     * Returns the [Composable]s used to render the stepper header.
     * The received argument contains the stepper header necessary data to render the view.
     */
    val composable: @Composable (data: Data) -> Unit

    interface Data {
        // title for the current step; can be empty or null
        val stepTitle: String?
        // title for the current selected substep; optional;
        // can be empty ("") if not defined or `null` if currently there is no selected substep
        val substepTitle: String?
        // 1-based index of the current step
        val step: Int
        // total number of steps
        val totalSteps: Int
        // 1-based index of the current substep; can be `null` when there are no defined substeps
        val substep: Int?
        // total number of substeps in the current step; can be `null` or `0`
        val totalSubsteps: Int?
    }
}
```

#### Sample

```kotlin theme={"dark"}
override fun provideCustomStepperHeader(): CustomStepperHeader? {
    return object : CustomStepperHeader {
        override val composable: @Composable ((CustomStepperHeader.Data) -> Unit)
            get() = @Composable { data ->
                /* add some @Composable implementation which displays the `data` */
            }
    }
}
```

## Custom loaders

The container application can decide to provide custom loaders to be displayed at certain moments based on a given predefined `actionName`.\

To provide custom loaders, an *implementation* of the `CustomLoaderProvider` interface should be passed as a parameter when initializing the SDK:

```kotlin theme={"dark"}
interface CustomLoaderProvider {
    fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader?
}
```

where the `CustomLoaderProvider.LoaderType` is defined like this:

```kotlin theme={"dark"}
interface LoaderType {
    interface StartProcess : LoaderType
    interface ReloadProcess : LoaderType
    interface Action : LoaderType { val name: String }
    interface Upload : LoaderType { val name: String }
}
```

> [!NOTE]
>
> The available types for the `loaderType` parameter are:
>
> * `LoaderType.StartProcess` - received for overriding the loader displayed when starting a new process
> * `LoaderType.ReloadProcess` - received for overriding the loader displayed when resuming an existing process
> * `LoaderType.Action` - received for overriding the loader displayed while the action having the `name` name is executed
> * `LoaderType.Upload` - received for overriding the loader displayed while the **upload** action having the `name` name is executed
>
> The `name` property received for the `LoaderType.Action` and `LoaderType.Upload` types represents the name of an action, as defined at process definition time, received for being able to override the loader displayed while that action is executed.

> [!NOTE]
>
> Returning an implementation of a `CustomLoader` replaces the built-in platform loader with the provided one for the specified use cases.\
> \\
>
> Returning `null` keeps the built-in platform loader for the specified use cases.

### CustomLoader

The implementation for providing a custom loader is based on creating and binding a user defined [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function, through the `CustomLoader` interface:

```kotlin theme={"dark"}
interface CustomLoader {
    val composable: @Composable CustomLoaderScope.() -> Unit
}
```

### CustomLoaderScope

The `composable` property of the [CustomLoader](#customloader) is a [@Composable](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable) function which may be defined and run only within the context of a `CustomLoaderScope` receiver.

```kotlin theme={"dark"}
val composable: @Composable CustomLoaderScope.() -> Unit
```

```kotlin theme={"dark"}
interface CustomLoaderScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}
```

This allows calling predefined SDK methods for querying for substitution tags and media resource URLs directly from the custom loader through the scope itself.

#### Sample

```kotlin expandable theme={"dark"}
class FxCustomLoaderProvider : CustomLoaderProvider {
    override fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader? =
        when (loaderType) {
            is CustomLoaderProvider.LoaderType.StartProcess -> MyCustomLoader(backgroundColor = Color.Black.copy(alpha = 0.38f), indicatorColor = Color.Red)
            is CustomLoaderProvider.LoaderType.ReloadProcess -> MyCustomLoader(backgroundColor = Color.Yellow.copy(alpha = 0.38f), indicatorColor = Color.Green)
            is CustomLoaderProvider.LoaderType.Action -> {
                when (loaderType.name) {
                    "action1" -> ActionCustomLoader()
                    "action2" -> ComplexCustomLoader()
                    else -> null
                }
            }
            is CustomLoaderProvider.LoaderType.Upload -> {
                when (loaderType.name) {
                    "upload1" -> ActionCustomLoader()
                    "upload2" -> ComplexCustomLoader()
                    else -> null
                }
            }
            else -> null
        }
}

class MyCustomLoader(val backgroundColor: Color, val indicatorColor: Color) : CustomLoader {
    override val composable: @Composable (CustomLoaderScope.() -> Unit)
        get() = @Composable {
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(color = backgroundColor),
                contentAlignment = Alignment.Center,
            ) {
                CircularProgressIndicator(color = indicatorColor)
                BackHandler(enabled = true) {} // block back navigation
            }
        }
}

class ActionCustomLoader() : CustomLoader {...}

class ComplexCustomLoader() : CustomLoader {
    private val animatedViewModel = AnimatedLoaderViewModel(...)
    override val composable: @Composable (CustomLoaderScope.() -> Unit)
        get() = @Composable {
            AnimatedLoader(viewModel = animatedViewModel)
        }
}

@Composable
private fun CustomLoaderScope.AnimatedLoader(
    viewModel: AnimatedLoaderViewModel
) {
    viewModel.setFlowxScope(this@AnimatedLoader) // IMPORTANT: keep a reference to the custom context/scope in order to access the available predefined SDK methods

    val state by viewModel.loaderState.collectAsStateWithLifecycle()

    Box {
        // use state to build what is to be displayed
    }
}

private class AnimatedLoaderViewModel(...) : ViewModel() {
    private lateinit var flowxScope: CustomLoaderScope // IMPORTANT: keeps the custom context/scope which allows to call the available predefined methods exposed to custom component

    val loaderState: StateFlow<AnimatedLoaderState?> =
        someData
            .process {
                if (this@AnimatedLoaderViewModel::flowxScope.isInitialized) { // IMPORTANT: if the custom context/scope was initialized, the substitution tag can be safely queried
                    flowxScope.replaceSubstitutionTag(it)
                } else {
                    it
                }
            }
            .stateIn(...)

    fun setFlowxScope(scope: CustomLoaderScope) {
        flowxScope = scope
    }
}

```

## Collecting log events

To be able to collect log events from the SDK, an implementation for the `LogSink.Collector` functional interface may be provided when initializing the SDK:

```kotlin theme={"dark"}
interface LogSink {
    fun interface Collector {
        fun onEvent(event: LogSink.Event)
    }
}
```

The `Event` is structured like this:

```kotlin theme={"dark"}
inteface LogSink {
    interface Event {
        /** Capture time, ISO 8601 @ UTC: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` */
        val timestamp: String

        /** One of "rest", "sse", "expression", "cms" */
        val category: String

        /**
        * The event type within [category]:
        * - rest → one of "request", "response", "error"
        * - sse → the raw server-sent event name
        * - expression → one of "hide", "disabled", "computed", "conditional", "validator", "localScript", "triggerCondition"
        * - cms → "fontRegistered"
        */
        val type: String

        val payload: JSONObject
    }
}
```

#### Sample

The implementation can be passed as a lambda, like:

```kotlin theme={"dark"}
logSink = { event ->
    // do whatever is needed (e.g. log the event, send it you external telemetry systems, etc.)
    android.util.Log.i("FxLogSink", event.toString())
}
```

> [!NOTE]
>
> The `payload` inside the `LogSink.Event` contains raw data specific to the event type.

## Collecting analytics events

To be able to collect analytics events from the SDK, an implementation for the `AnalyticsCollector` functional interface may be provided when initializing the SDK:

```kotlin theme={"dark"}
fun interface AnalyticsCollector {
    fun onEvent(event: Event)
}
```

There are two types of events, `Screen` and `Action`, both of them containing some `Data` and an optional `CustomPayload`, as defined at process definition time.

The `Event` is structured like this:

```kotlin theme={"dark"}
sealed interface Event {
    interface Screen : Event {
        val data: Screen.Data

        interface Data {
            val value: String
            val customPayload: CustomPayload?
        }
    }

    interface Action : Event {
        val data: Action.Data

        interface Data {
            val value: String
            val screen: String?
            val component: String?
            val label: String?
            val customPayload: CustomPayload?
        }
    }

    sealed interface CustomPayload {
        interface Object : CustomPayload {
            val data: JSONObject
        }

        interface Array : CustomPayload {
            val data: JSONArray
        }
    }
}
```

#### Sample

The implementation can be passed as a lambda, like:

```kotlin theme={"dark"}
analyticsCollector = { event ->
    // do whatever is needed (e.g. log the event)
    when (it) {
        is Event.Screen -> {
            val customPayload: String? =
                when (val payload = it.data.customPayload) {
                    is Event.CustomPayload.Object -> payload.data.toString()
                    is Event.CustomPayload.Array -> payload.data.toString()
                    else -> null
                }
            Log.i("Analytics", "Event.Screen(value = ${it.data.value}, customPayload = $customPayload)")
        }

        is Event.Action -> {
            val customPayload: String? =
                when (val payload = it.data.customPayload) {
                    is Event.CustomPayload.Object -> payload.data.toString()
                    is Event.CustomPayload.Array -> payload.data.toString()
                    else -> null
                }
            Log.i("Analytics", "Event.Action(value = ${it.data.value}, screen = ${it.data.screen}, component = ${it.data.component}, label = ${it.data.label}, customPayload = $customPayload)")
        }
    }
}
```

> [!NOTE]
>
> The `value` property represents the identifier set in the process definition.
>
> For action type events there are some additional properties provided:
>
> * `component` - The type of component triggering the action
> * `label` - The label of the component, if available. (E.g. title of a button or label of a form element)
> * `screen` - The identifier of the screen containing the component, if set
>
> The `customPayload` is defined at process definition time, and then processed inside the platform before sending it to being collected.

## Handling "Start of a new process"

When an action of type `START_PROJECT` is executed, the `onNewProcessStarted` lambda provided in the `Flowx.getInstance().init(...)` function is invoked.

This callback provides the UUID of the newly started process, which can be used to resume the process by calling the `Flowx.getInstance().continueProcess(...)` method.

It is the responsibility of the container application's developer to implement the necessary logic for displaying the appropriate UI for the newly started process.

#### Sample

One way to handle this is to send a broadcast message to notify the Activity currently displaying the running process.
The Activity should handle the broadcast to reload and display the newly started process identified by `processInstanceUuid` (received in the broadcast intent).

```kotlin theme={"dark"}
Flowx.getInstance().init(
    ...
    onNewProcessStarted = { processInstanceUuid ->
        applicationContext.sendBroadcast(
            Intent("some.intent.filter.indentifier").apply {
                putExtra("processInstanceUuid", processInstanceUuid)
                setPackage("your.application.package")
            }
        )
    }
    ...
)

class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        setContent {
            val yourBroadcastReceiver = remember {
                YourBroadcastReceiver(handler = { processInstanceUuid -> /* do your own logic to refresh `ProcessContent()` */ })
            }

            val context = LocalContext.current
            LifecycleStartEffect(true) {
                ContextCompat.registerReceiver(context.applicationContext, yourBroadcastReceiver, IntentFilter("some.intent.filter.indentifier"), ContextCompat.RECEIVER_NOT_EXPORTED)
                onStopOrDispose {
                    runCatching {
                        context.applicationContext.unregisterReceiver(yourBroadcastReceiver)
                    }
                }
            }

            ProcessContent()
        }
    }

    @Composable
    private fun ProcessContent(...) {...}
}

class YourBroadcastReceiver(private val handler: (String) -> Unit) : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        intent?.extras?.getString("processInstanceUuid")?.let { processUuid -> handler.invoke(processUuid) }
    }
}
```

## ProGuard / R8

The SDK ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## Known issues

* shadows are rendered only on **Android >= 28** having [hardware acceleration](https://developer.android.com/topic/performance/hardware-accel) **enabled**


# Angular SDK
Source: https://docs.flowx.ai/5.9/sdks/angular-renderer

The Angular renderer SDK renders UI configured in the FlowX Designer as a standalone Angular component.

## Angular project requirements

Your app MUST be created using Angular CLI \~21 and MUST use SCSS for styling.

```bash theme={"dark"}
npm install -g @angular/cli@21
ng new my-flowx-app
```

> [!TIP]
>
> To install the npm libraries provided by FlowX.AI you will need to obtain access to the private FlowX.AI Nexus registry. Please consult with your project DevOps.

> [!NOTE]
>
> **Angular \~21 starting with FlowX.AI 5.9.4**
>
> The library requires Angular **\~21**, **npm ≥ 11.0.0** and **node ≥ 24.0.0**.
>
> On **5.9.0 through 5.9.3**, the library requires Angular **\~20** instead. The npm and node requirements are the same on every 5.9.x release.

## Installing the library

Use the following command to install the **renderer** library and its required dependencies:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@21 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your platform version.
>
> To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.

A few configurations are needed in the project's `angular.json`. To successfully link the PDF viewer, add the following declaration in the assets property:

```json theme={"dark"}
{
  "glob": "**/*",
  "input": "node_modules/ng2-pdfjs-viewer/pdfjs",
  "output": "/assets/pdfjs"
}
```

## Initial setup

Once installed, `FlxProcessModule` is imported in the `AppModule` as `FlxProcessModule.withConfig({})`.

### Theming

Component theming is done through the `@flowx/angular-theme` library. The theme id is a required input for the renderer SDK component and is used to fetch the theme configuration. The id can be obtained from the admin panel in the themes section.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/2024-04-08%2013.45.10.gif)

### Authorization

> [!NOTE]
>
> It's the responsibility of the client app to implement the authorization flow (using the **OpenID Connect** standard). The renderer SDK expects the authToken to be passed to `flx-process-renderer` as an input.

```typescript theme={"dark"}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http';
import { FlxProcessModule } from '@flowx/angular-sdk';
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    HttpClientModule,
    FlxProcessModule.withConfig({
      components: {},
      services: {},
    }),
  ],
  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}
```

The `withConfig()` call is required in the app module where the process will be rendered. It accepts a config object where you can register **custom components**, **services**, and **custom validators**.

**Custom components** are referenced by name in the template config for a user task.

**Custom validators** are referenced by name (`currentOrLastYear`) in the template config panel under the validators section of each generated form field.

```typescript theme={"dark"}
FlxProcessModule.withConfig({
  components: {
    YourCustomComponentIdentifier: CustomComponent,
  },
  services: {
    NomenclatorService,
    LocalDataStoreService,
  },
  validators: { currentOrLastYear },
})
```

### Custom interceptors

Starting from FlowX SDK version 4.6, the Angular `HttpClientModule` is no longer used internally for HTTP requests. A new mechanism allows you to create custom interceptors.

#### Request interceptors

```typescript theme={"dark"}
import { FLX_REQUEST_INTERCEPTORS_CONFIG } from '@flowx/angular-sdk'
import { HttpRequestInterceptor } from '@flowx/core-sdk'

const customHeaderInterceptor: HttpRequestInterceptor[] = [
  {
    onFulfilled: (response) => {
      response.headers['custom-header'] = 'custom-value'
      return response
    },
  }
]

// Add to providers in the main app module
{
  provide: FLX_REQUEST_INTERCEPTORS_CONFIG,
  useValue: customHeaderInterceptor,
}
```

#### Response interceptors

```typescript theme={"dark"}
import { FLX_RESPONSE_INTERCEPTORS_CONFIG } from '@flowx/angular-sdk'
import { HttpResponseInterceptor } from '@flowx/core-sdk'

const customErrorInterceptor: HttpResponseInterceptor[] = [
  {
    onRejected: (response) => {
      if (response.status !== 200) {
        console.error('Something went wrong!', response.message)
      }
      return response
    }
  }
]

// Add to providers in the main app module
{
  provide: FLX_RESPONSE_INTERCEPTORS_CONFIG,
  useValue: customErrorInterceptor,
}
```

#### Interceptors that use dependency injection

If you need to use a service in your interceptor, use provider factories with the `deps` property:

```typescript theme={"dark"}
const interceptorFactory = (customService: CustomService): HttpRequestInterceptor[] => [{
  onFulfilled: (response) => {
    // use customService here
    return response
  }
}]

// Add to providers in the main app module
{
  provide: FLX_REQUEST_INTERCEPTORS_CONFIG,
  useFactory: (customService: CustomService) => [
    interceptorFactory(customService),
  ],
  deps: [CustomService],
}
```

### Using custom icons

```typescript theme={"dark"}
import { FlxIconModule } from '@flowx/angular-ui-toolkit'

const customIconDictionary = {
  'custom-icon': 'custom icon svg'
}

providers: [
  importProvidersFrom(FlxIconModule),
  provideExtraIconSet(customIconDictionary),
]
```

### Analytics

> [!NOTE]
>
> The SDK provides a mechanism for collecting analytics events through a unified `CustomEvent` system. These events can be used to track screens and action events.

To use analytics features, import the necessary SDK module:

```typescript theme={"dark"}
import {
   ANALYTICS_EVENTS,
   AnalyticsData,
   pushAnalyticsData,
} from '@flowx/core-sdk';
```

#### Emitting analytics events

Analytics events are dispatched using the `pushAnalyticsData(payload: AnalyticsData)` method. The SDK defines two event types:

```typescript theme={"dark"}
enum ANALYTICS_EVENTS {
  SCREEN = 'SCREEN',
  ACTION = 'ACTION',
}
```

Each analytics event should be an object of type `AnalyticsData`:

```typescript theme={"dark"}
type AnalyticsData = {
  type: ANALYTICS_EVENTS;
  value: string;
  screen?: string;
  component?: string;
  label?: string;
  customPayload?: object;
}
```

> [!NOTE]
>
> The `value` property represents the identifier set in the process definition.
>
> For `ACTION` type events there are additional properties:
>
> * `component` - the type of component triggering the action
> * `label` - the label of the component
> * `screen` - the identifier of the screen containing the component, if set

#### Listening for analytics events

```typescript theme={"dark"}
ngOnInit(): void {
  document.addEventListener('flowx:analytics', this.analyticsListener);
}

analyticsListener = (event: CustomEvent<AnalyticsData>) => {
  console.log('Received flowx:analytics event:', event.detail);
};

ngOnDestroy(): void {
  document.removeEventListener('flowx:analytics', this.analyticsListener);
}
```

> [!TIP]
>
> Ensure that you remove the event listener on component destruction to avoid memory leaks.

#### Custom payload

This allows you to capture and send custom data alongside standard analytics events.

When analytics custom payload is configured in FlowX Designer, the renderer automatically processes variable substitution and includes the resulting data in analytics events.

**1. Receive custom payload configuration**

The renderer receives the analytics configuration as a JSON string with variable placeholders:

```json theme={"dark"}
"analyticsCustomPayload": "{\n \"name\": ${app.input}\n}"
```

**2. Process variable substitution**

The SDK replaces variables with actual values from the process data store:

```json Template theme={"dark"}
{
    "name": "${app.input}",
    "client": "${app.client}",
    "amount": "${app.amount}"
}
```

```json Result theme={"dark"}
{
    "name": "john",
    "client": { "id": "123", "name": "John Doe" },
    "amount": 1500
}
```

**3. Add to analytics event**

The processed payload is included in the analytics event under the `customPayload` property:

```typescript theme={"dark"}
{
    type: 'ACTION', // or 'SCREEN'
    info: {
        value: 'Save personal data',
        screen: 'Personal Data',
        component: 'BUTTON',
        label: 'Save',
        customPayload: {
            name: "john",
            client: { id: "123", name: "John Doe" },
            amount: 1500
        }
    }
}
```

***

## Starting a process

### Prerequisites

* **Process name**: You need to know the name of the process you want to start. This name identifies the process in the system.
* **FlowX Project UUID**: You need the UUID of the FlowX Project that contains the process. Obtain it from the FlowX Dashboard.
* **Locale**: You can specify the locale to apply date, currency, and number formatting to data model values.
* **Language**: You can specify the language used to localize enumerations inside the app.

### Getting the project UUID

The project UUID can be obtained from the FlowX Dashboard. Navigate to the Projects section and select the project you want to start a process in. The UUID can be copied from the project actions popover.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/copy_uuid_application.png)

### Getting the process identifier

Open the FlowX Designer, navigate to the process, and copy the process name from the breadcrumbs. Use this value as `processName`.

### Initializing the process renderer

```typescript theme={"dark"}
import { Component } from '@angular/core';

@Component({
  selector: 'app-process',
  template: `
    <flx-process-renderer
      [apiUrl]="apiUrl"
      [processApiPath]="processApiPath"
      [authToken]="authToken"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [processName]="processName"
      [workspaceId]="workspaceId"
      [projectInfo]="projectInfo"
      [organizationId]="organizationId"
      [locale]="'en-US'"
      [language]="'en'"
      [logSink]="logSink"
    />
  `
})
export class ProcessComponent {
  projectInfo = { projectId: 'your-project-uuid' }
  logSink = console; // Example logSink, can be any valid logging object
}
```

The entry point of the library is the `<flx-process-renderer>` component. A list of accepted inputs is found below:

```html theme={"dark"}
<flx-process-renderer
  [apiUrl]="baseApiUrl"
  [processApiPath]="processApiPath"
  [authToken]="authToken"
  [themeId]="themeId"
  [staticAssetsPath]="staticAssetsPath"
  [processName]="processName"
  [processStartData]="processStartData"
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  [organizationId]="organizationId"
  [language]="language"
  [locale]="locale"
  [cache]="cache"
  [buildId]="buildId"
  [logSink]="logSink"
/>
```

**Parameters:**

| Name | Description | Type | Mandatory | Default value | Example |
| - | - | - | - | - | - |
| `apiUrl` | Your base URL | `string` | true | - | `https://yourDomain.dev` |
| `processApiPath` | Process subpath | `string` | true | - | `onboarding` |
| `authToken` | Authorization token | `string` | true | - | `'eyJhbGciOiJSUzI1NiIsIn....'` |
| `themeId` | Theme id used to style the process. Can be obtained from the themes section in the admin | `string` | true | - | `'123-456-789'` |
| `staticAssetsPath` | Path to static assets | `string` | true | - | - |
| `projectInfo` | Defines which FlowX Project will be run. Shape: `{ projectId: string, appVersionId?: string }` | `object` | true | - | `{ projectId: '111-222-333' }` |
| `organizationId` | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment). | `string` | true | - | `'10000001-0001-0001-8001-100000000001'` |
| `processName` | Identifies a process | `string` | true | - | `client_identification` |
| `processStartData` | Data required to start the process | `json` | true | - | `{ "firstName": "John", "lastName": "Smith" }` |
| `workspaceId` | Workspace id | `string` | true | - | `'8f52744-8403-4e8d....'` |
| `language` | Language used to localize the enumerations inside the app | `string` | false | `en` | - |
| `locale` | Locale used to apply date, currency, and number formatting to data model values | `string` | false | `ro-RO` | `'en-US'` |
| `isDraft` | When true, starts the process in draft state | `boolean` | false | `false` | - |
| `cache` | Enable caching of CMS resources (theme, substitution tags, enumerations, media library assets) | `boolean` | false | `true` | - |
| `legacyHttpVersion` | Set to `true` only for HTTP versions \< 2, required for SSE to work properly in those environments | `boolean` | false | `false` | - |
| `buildId` | Pinned build identifier | `string` | false | - | - |
| `customLoader` | Custom loader components for different loading scenarios | `object` | false | - | `{ startProcess: StartLoaderComponent }` |
| `logSink` | Custom log sink object for process-renderer logging. If provided, logs will be sent here instead of default console logging | `object` | false | `console` | `myCustomLogger` |

#### `projectInfo` shape

```typescript theme={"dark"}
projectInfo: {
  projectId: string      // required
  appVersionId?: string  // pin a specific app version
}
```

***

## Custom components

Custom components receive data through the `data$` signal input and are registered via `FlxProcessModule.withConfig({ components: {} })`.

> [!WARNING]
>
> The object keys passed in `components` **MUST** match the custom component names defined in the FlowX process.

`data$` is a signal holding an `Observable` that emits a `FlxCustomComponentData` object each time the process model updates:

```typescript theme={"dark"}
interface FlxCustomComponentData {
  data: any                                                         // value at the configured inputKey path - object or primitive
  actions: ProcessAction[]                                          // metadata for each bound action
  actionsFn: Record<string, (params?: any) => Observable<any>>     // call to trigger a process action; returns an Observable
}
```

```typescript theme={"dark"}
@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
  styleUrls: ['./custom-component.component.scss'],
})
export class CustomComponentComponent {
  data$ = input<Observable<FlxCustomComponentData> | null>(null)
}
```

To add a custom component in the template config tree, you need its unique identifier and the data it should receive from the process model.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom.png)

The properties that can be configured are:

* **Identifier** - enables the custom component to be displayed within the component hierarchy and determines available actions.
* **Input keys** - specify the path to process data that components will use to receive their information.
* [**Event Handlers**](../docs/building-blocks/ui-designer/event-handlers) - actions defined here will be made available to the custom component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom_settings.png#center)

### Prerequisites (before creation)

* **Angular knowledge**: Custom components are created and imported using Angular.
* **Development environment**: Node.js and npm set up for Angular development.
* **Component identifier**: A unique identifier used to reference the component within the app.

### Creating a custom component

1. Create a new Angular component.
2. Implement the HTML structure, TypeScript logic, and SCSS styling to define the appearance and behavior.

### Importing the component

Register the component in `FlxProcessModule.withConfig()`:

```typescript theme={"dark"}
FlxProcessModule.withConfig({
  components: {
    MyCustomComponentIdentifier: MyCustomComponent,
  },
})
```

### Using the custom component

Once declared, you can configure it in the FlowX Designer.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_component.gif)

### Data input and actions

The custom component receives input data from processes and can include actions extracted from a process. These allow you to configure and interact with the component dynamically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_input_data.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_loader_input.png)

> [!WARNING]
>
> Make sure that the Angular action names match the names of the process actions.

### Custom component validation

Custom components can validate their own status using the `FLX_VALIDATOR_SERVICE` injection token.

The service exposes:

* `validate(isValid: boolean)` - validates the component
* `saveData(data: any)` - saves data
* `validated$` - Observable for monitoring external submission from the process

```typescript theme={"dark"}
import { FLX_VALIDATOR_SERVICE } from '@flowx/angular-sdk'

@Component({
  selector: 'flx-custom-validation',
  imports: [CommonModule, ReactiveFormsModule],
  template: `
    Custom validation:
    <input [formControl]="fc" />
    @if (formSubmitted() && fc.invalid) {
      <span>error</span>
    }
  `
})
export class FlxCustomValidationComponent implements OnInit {
  data$ = input<Observable<any> | null>(null)

  validationService = inject(FLX_VALIDATOR_SERVICE)

  fc = new FormControl('', Validators.required)
  formSubmitted = signal(false)

  ngOnInit(): void {
    this.fc.statusChanges.subscribe((status) => {
      this.validationService.validate(status === 'VALID')
    })
    this.fc.valueChanges.subscribe((value) => {
      this.validationService.saveData({ app: { test1: value, test2: `${value}${value}` } })
    })
    this.validationService.validated$.subscribe(() => {
      this.formSubmitted.set(true)
    })
  }
}
```

***

## Custom validators

You may define custom validators in your FlowX processes and pass their implementation via `FlxProcessModule.withConfig({ validators: {} })`.

> [!WARNING]
>
> The object keys passed in `validators` **MUST** match the custom validator names defined in the FlowX process.

```typescript theme={"dark"}
currentOrLastYear: function currentOrLastYear(AC: AbstractControl): { [key: string]: any } {
  if (!AC) {
    return null;
  }

  const yearDate = moment(AC.value, YEAR_FORMAT, true);
  const currentDateYear = moment(new Date()).startOf('year');
  const lastYear = moment(new Date()).subtract(1, 'year').startOf('year');

  if (!yearDate.isSame(currentDateYear) && !yearDate.isSame(lastYear)) {
    return { currentOrLastYear: true };
  }

  return null;
}
```

> [!WARNING]
>
> The error that the validator returns **MUST** match the validator name.

***

## Process end handling

The SDK provides a mechanism for handling process completion events through the `(processEnd)` output event. This allows you to implement custom logic when a main process reaches an end state, such as redirecting users or triggering cleanup operations.

The `processEnd` event is triggered when the **main process** (not subprocesses) reaches any terminal state.

> [!NOTE]
>
> Only the main process triggers this event. Subprocess completions do not trigger it to avoid unnecessary interruptions during complex process flows.

### Implementation

```typescript theme={"dark"}
import { Component } from '@angular/core';
import { Router } from '@angular/router';

@Component({
  selector: 'app-process',
  template: `
    <flx-process-renderer
      [apiUrl]="apiUrl"
      [authToken]="authToken"
      [processName]="processName"
      [processStartData]="processStartData"
      [workspaceId]="workspaceId"
      [processApiPath]="processApiPath"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [projectInfo]="projectInfo"
      [organizationId]="organizationId"
      (processEnd)="onProcessEnd()"
    />
  `
})
export class ProcessComponent {
  constructor(private router: Router) {}

  onProcessEnd(): void {
    console.log('Process has ended');
    this.router.navigate(['/dashboard']);
  }
}
```

***

## Process start handling

The SDK provides a mechanism for reacting to process start events through the `(processStart)` output event. It emits the new `processInstanceUuid` once the main process instance has been created - useful for tracking, deep linking, or storing the instance reference for later resume.

### Implementation

```typescript theme={"dark"}
import { Component } from '@angular/core';

@Component({
  selector: 'app-process',
  template: `
    <flx-process-renderer
      [apiUrl]="apiUrl"
      [authToken]="authToken"
      [processName]="processName"
      [processStartData]="processStartData"
      [workspaceId]="workspaceId"
      [processApiPath]="processApiPath"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [projectInfo]="projectInfo"
      [organizationId]="organizationId"
      (processStart)="onProcessStart($event)"
    />
  `
})
export class ProcessComponent {
  onProcessStart(processInstanceUuid: string): void {
    console.log('process started', processInstanceUuid);
  }
}
```

***

## Custom loader

The SDK provides a mechanism for customizing the loader UI displayed during process execution.

### Configuration

Register custom loaders via `FlxProcessModule.withConfig({ customLoader: {} })`:

```typescript theme={"dark"}
import { FlxProcessModule } from '@flowx/angular-sdk';
import { Type } from '@angular/core';

@Component({
  selector: 'app-start-loader',
  template: `
    <div class="custom-start-loader">
      <div class="spinner"></div>
      <p>Starting process...</p>
    </div>
  `
})
export class StartProcessLoaderComponent {}

@Component({
  selector: 'app-specific-action-loader',
  template: `
    <div class="custom-specific-action-loader">
      <div class="spinner"></div>
      <p>Executing specific action...</p>
    </div>
  `
})
export class SpecificActionLoaderComponent {}

@NgModule({
  imports: [
    FlxProcessModule.withConfig({
      customLoader: {
        startProcess: StartProcessLoaderComponent,
        // reloadProcess: ReloadProcessLoaderComponent,
        // defaultAction: DefaultActionLoaderComponent,
        // defaultUpload: DefaultUploadLoaderComponent,
        actions: {
          action1: SpecificActionLoaderComponent,
        },
      },
      components: {},
      services: {},
    }),
  ],
})
export class AppModule {}
```

### API specification

The custom loader configuration accepts an object of type `CustomLoader`:

```typescript theme={"dark"}
type CustomLoader = {
  actions?: Record<string, Type<any>>
  startProcess?: Type<any>
  reloadProcess?: Type<any>
  defaultAction?: Type<any>
  defaultUpload?: Type<any>
}
```

#### Loader types

* **`startProcess`** - displayed when starting or resuming a process
* **`reloadProcess`** - displayed when reloading a process
* **`defaultAction`** - default loader for actions when `loaderType` is `'action'`. Used when no specific action loader is found in the `actions` record
* **`defaultUpload`** - default loader for file uploads when `loaderType` is `'upload'`
* **`actions`** - record mapping specific action identifiers to custom loaders. When an action is executed, the SDK checks this record before falling back to `defaultAction`

### Fallback behavior

> [!NOTE]
>
> If no custom loader is provided for a specific type, the SDK automatically falls back to the built-in FlowX loader. This ensures your app continues to function even with partial custom loader configuration.

> [!TIP]
>
> You can use substitution tags and media library assets within your custom loader components to create rich, branded loading experiences that match your app's design system.

***

## Chat component

To use the `FlxChatRendererComponent`, import the module in your project:

```typescript theme={"dark"}
import { FlxChatRendererComponent } from '@flowx/angular-sdk';
```

#### Usage

Include the component in your template:

```html theme={"dark"}
<flx-chat-renderer
  [apiUrl]="apiUrl"
  [authToken]="accessToken()"
  [staticAssetsPath]="staticAssetsPath"
  [language]="language()"
  [locale]="locale()"
  [themeId]="themeId()"
  [projectId]="projectId()"
  [workspaceId]="workspaceId()"
  [source]="source()"
  [chatConfig]="chatConfig()"
  [cache]="cache()"
/>
```

Parameters:

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `apiUrl` | Your base API URL | `string` | ✅ | `https://yourDomain.dev` |
| `authToken` | Authorization token | `string` | ✅ | (retrieved from auth provider) |
| `staticAssetsPath` | Path for static resources | `string` | ✅ | (set via environment) |
| `language` | Language used to localize the chat interface | `string` | ✅ | `en` |
| `locale` | Locale setting for date and number formatting | `string` | ✅ | `en-US` |
| `themeId` | Theme identifier for styling | `string` | ✅ | (retrieved dynamically) |
| `projectId` | The FlowX project ID | `string` | ✅ | (retrieved dynamically) |
| `workspaceId` | The workspace ID | `string` | ✅ | (retrieved dynamically) |
| `source` | Source object with type and id | `object` | ✅ | `{ type: 'WORKFLOW', id: '...' }` |
| `chatConfig` | Chat configuration object | `object` | ✅ | `{ welcomeMessage: '...', ... }` |
| `cache` | Enable caching for chat responses | `boolean` | ❌ | `true` |
| `buildId` | Pinned build identifier | `string` | ❌ | (retrieved dynamically) |

#### chatConfig parameters

The `chatConfig` object accepts the following properties:

| Name | Description | Type | Default value |
| - | - | - | - |
| `welcomeMessage` | Message displayed when chat is first opened | `string` | `'Welcome to the chat!'` |
| `thinkingMessage` | Message displayed while waiting for response | `string` | `'Thinking...'` |
| `title` | Chat window title | `string` | `'Chat'` |
| `subtitle` | Chat window subtitle | `string` | `'Chat subtitle'` |
| `showChatIcon` | Whether to display the chat icon | `boolean` | `true` |
| `showSeparator` | Whether to show separator between messages | `boolean` | `true` |
| `newChatLabel` | Label for the new chat button | `string` | `'New chat'` |
| `inputPlaceholder` | Placeholder text for the message input field | `string` | `'Enter your message'` |
| `maxInputRows` | Maximum number of rows for the input field | `number` | `10` |
| `historyTitle` | Title displayed on the chat history panel | `string` | - |
| `errorMessage` | Message shown when an error occurs | `string` | `'Error message'` |
| `canRegenerate` | Show a regenerate button on responses | `boolean` | `true` |
| `regenerateLabel` | Label for the regenerate button | `string` | `'Regenerate'` |

***

## Task management component

To use the `FlxTasksManagementComponent`, import the module in your project:

```typescript theme={"dark"}
import { FlxTasksManagementComponent } from '@flowx/angular-sdk';
```

#### Usage

Include the component in your template:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId()"
  [language]="language()"
  [themeId]="themeId()"
  [staticAssetsPath]="staticUrl"
  [viewDefinitionId]="viewDefinitionId()"
  [locale]="locale()"
  [buildId]="buildId()"
  [workspaceId]="workspaceId()"
/>
```

Parameters:

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `apiUrl` | Endpoint where the tasks are available | `string` | ✅ | `https://yourDomain.dev/tasks` |
| `authToken` | Authorization token | `string` | ✅ | (retrieved from local storage) |
| `appId` | The app ID | `string` | ✅ | (retrieved dynamically) |
| `viewDefinitionId` | The view configuration identifier | `string` | ❌ | (retrieved dynamically) |
| `workspaceId` | The workspace ID | `string` | ❌ | (retrieved dynamically) |
| `themeId` | The theme identifier | `string` | ❌ | (retrieved dynamically) |
| `language` | The selected language | `string` | ❌ | `en` |
| `locale` | The localization setting | `string` | ❌ | (retrieved dynamically) |
| `buildId` | The current build identifier | `string` | ❌ | (retrieved dynamically) |
| `staticAssetsPath` | Path for static resources | `string` | ❌ | (set via environment) |
| `stages` | Pre-loaded enumeration stages | `TMEnumeration[]` | ❌ | - |
| `cache` | Enable caching | `boolean` | ❌ | `true` |

***

## Task management public API

The Angular SDK provides a comprehensive public API for building custom task management interfaces. This API allows you to fetch tasks, manage comments, handle task actions, and interact with task data programmatically.

### Importing the service

Inject `PublicTasksService` from `@flowx/angular-sdk`:

```typescript theme={"dark"}
import { PublicTasksService } from '@flowx/angular-sdk';
import { inject } from '@angular/core';

export class MyComponent {
  private taskService = inject(PublicTasksService);
}
```

### Available types

```typescript theme={"dark"}
import {
  PublicTasksService,
  TMView,
  TMViewTask,
  TMViewColumn,
  TMTaskComment,
  TMTaskHistory,
  TMUser,
  TMEnumerations,
  TMEnumeration,
  TMFilterOperators,
  TMFilters,
  TMSort,
  TMPaginatedResponse,
  TMSetupOptions,
  TMExecuteTaskActions,
  TMOperatorsType,
} from '@flowx/angular-sdk';
```

### Initialization

Before using the task management API, initialize the task manager resources. This fetches the view configuration, enumerations, and filter operators.

```typescript theme={"dark"}
this.taskService.getTaskManagerResources({
  apiUrl: 'https://yourDomain.dev/tasks',
  authToken: 'your-auth-token',
  appInfo: { appId: 'app-123' },
  viewId: 'view-456',
  workspaceId: 'workspace-789',
  themeId: 'theme-012', // Optional
  language: 'en', // Optional
  locale: 'en-US', // Optional
  buildId: 'build-345', // Optional
  staticAssetsPath: '/static', // Optional
}).subscribe(({ view, enumerations, filterOperators }) => {
  // Use the view, enumerations, and filterOperators
});
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `apiUrl` | Endpoint where the tasks are available | `string` | ✅ | `https://yourDomain.dev/tasks` |
| `authToken` | Authorization token | `string` | ✅ | (retrieved from local storage) |
| `appInfo` | App information containing appId | `{ appId: string }` | ✅ | `{ appId: "app-123" }` |
| `viewId` | The view configuration identifier | `string` | ✅ | (retrieved dynamically) |
| `workspaceId` | The workspace ID | `string` | ✅ | (retrieved dynamically) |
| `themeId` | The theme identifier | `string` | ❌ | (retrieved dynamically) |
| `language` | The selected language | `string` | ❌ | `"en"` |
| `locale` | The localization setting | `string` | ❌ | `"en-US"` |
| `buildId` | The current build identifier | `string` | ❌ | (retrieved dynamically) |
| `staticAssetsPath` | Path for static resources | `string` | ❌ | (set via environment) |

**Returns:** Observable emitting an object containing:

* `view`: The view configuration object (`TMView`)
* `enumerations`: Available enumeration options for filters (`TMEnumerations`)
* `filterOperators`: Available filter operators for each column (`TMFilterOperators`)

### Fetching tasks

#### `getViewTasks`

Fetches tasks for a specific view with support for sorting, filtering, pagination, and search.

```typescript theme={"dark"}
this.taskService.getViewTasks(
  page,      // page number (0-based)
  sort,      // array of sort configurations
  filters,   // array of filter configurations
  keyword,   // search string
  size       // page size
).subscribe((response) => {
  const tasks = response.content;
});
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `page` | Page number (0-based) | `number` | ✅ | `0` |
| `sort` | Array of sort configurations | `TMSort[]` | ✅ | `[{ keyName: "priority", direction: "ASC" }]` |
| `filters` | Array of filter configurations | `TMFilters[]` | ✅ | See filter examples below |
| `keyword` | Search string for task search | `string` | ✅ | `"urgent"` |
| `size` | Number of items per page | `number` | ✅ | `10` |

**Returns:** Observable emitting `TMPaginatedResponse<TMViewTask>` with `content`, `totalElements`, `totalPages`.

#### `getViewTask`

Fetches a specific task by ID and token UUID.

```typescript theme={"dark"}
this.taskService.getViewTask(taskId, tokenUuid)
  .subscribe((task) => {
    // Use the task
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `tokenUuid` | The token UUID associated with task | `string` | ✅ | `"token-uuid-456"` |

**Returns:** Observable emitting a `TMViewTask` object.

### Task details

#### `getTaskComments`

Fetches all comments for a specific task.

```typescript theme={"dark"}
this.taskService.getTaskComments(taskId)
  .subscribe((comments) => {
    // TMTaskComment[]
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |

**Returns:** Observable emitting an array of `TMTaskComment` objects.

#### `getTaskHistory`

Fetches the history/audit trail for a specific task.

```typescript theme={"dark"}
this.taskService.getTaskHistory(taskId)
  .subscribe((history) => {
    // TMTaskHistory[]
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |

**Returns:** Observable emitting an array of `TMTaskHistory` objects.

#### `getAssignees`

Fetches available assignees for a task, with optional search filtering.

```typescript theme={"dark"}
this.taskService.getAssignees(task, { keyword: 'john' })
  .subscribe((users) => {
    // TMUser[]
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `task` | The task object | `TMViewTask` | ✅ | (task object) |
| `query` | Search options | `{ keyword: string }` | ✅ | `{ keyword: "john" }` |

**Note:** The keyword must be at least 4 characters long. If shorter, the Observable will emit an error.

**Returns:** Observable emitting an array of `TMUser` objects.

#### `getBulkAssignees`

Fetches available assignees for multiple tasks in bulk.

```typescript theme={"dark"}
this.taskService.getBulkAssignees(
  [{ id: 'task-1', tokenUuid: 'token-1' }, { id: 'task-2', tokenUuid: 'token-2' }],
  { keyword: 'john' }
).subscribe((users) => {
  // TMUser[]
});
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `tasks` | Array of task objects with `id` and `tokenUuid` | `{ id: string; tokenUuid: string }[]` | ✅ | `[{ id: "task-1", tokenUuid: "..." }]` |
| `query` | Search options | `{ keyword: string }` | ✅ | `{ keyword: "john" }` |

**Returns:** Observable emitting an array of `TMUser` objects.

### Task actions

#### `executeTaskAction`

Executes an action on a specific task (e.g., assign, complete, cancel).

```typescript theme={"dark"}
this.taskService.executeTaskAction(action, task, payload)
  .subscribe(() => {
    // action completed
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `action` | The action to execute | `TMExecuteTaskActions` | ✅ | `TaskActions.ASSIGN` |
| `task` | The task object | `TMViewTask` | ✅ | (task object) |
| `payload` | Additional payload (e.g. username) | `any` | ❌ | `"john.doe"` |

**Available actions:**

* `TaskActions.ASSIGN` - assign task to a user
* `TaskActions.COMPLETE` - mark task as complete
* `TaskActions.CANCEL` - cancel the task
* `TaskActions.CHANGE_PRIORITY` - change task priority
* `TaskActions.VIEW` - view task details

#### `bulkUpdate`

Applies an action to multiple tasks at once.

```typescript theme={"dark"}
this.taskService.bulkUpdate(
  [{ id: 'task-1', tokenUuid: 'token-1' }, { id: 'task-2', tokenUuid: 'token-2' }],
  TaskActions.COMPLETE,
  'username' // Optional, for assign action
).subscribe(() => {
  // bulk action completed
});
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `tasks` | Array of task objects with `id` and `tokenUuid` | `{ id: string; tokenUuid: string }[]` | ✅ | `[{ id: "task-1", tokenUuid: "..." }]` |
| `action` | The action to execute | `TMExecuteTaskActions` | ✅ | `TaskActions.COMPLETE` |
| `username` | Username for assign action | `string` | ❌ | `"john.doe"` |

#### `updatePriority`

Updates the priority of a specific task.

```typescript theme={"dark"}
this.taskService.updatePriority(taskId, priority)
  .subscribe(() => {
    // priority updated
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `priority` | New priority value | `number` | ✅ | `5` |

### Comments management

#### `addComment`

Adds a new comment to a task.

```typescript theme={"dark"}
this.taskService.addComment(taskId, { message: 'New comment text' })
  .subscribe((comment) => {
    // TMTaskComment
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `comment` | Comment data object | `{ message: string }` | ✅ | `{ message: "New comment text" }` |

**Returns:** Observable emitting the created `TMTaskComment` object.

#### `deleteComment`

Removes a comment from a task.

```typescript theme={"dark"}
this.taskService.deleteComment(taskId, commentId)
  .subscribe(() => {
    // comment deleted
  });
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `commentId` | The unique comment ID | `string` | ✅ | `"comment-456"` |

### Service state management

#### `getView`

Gets the current view configuration.

```typescript theme={"dark"}
const view = this.taskService.getView(); // TMView | null
```

#### `getEnumerations`

Gets the current enumerations.

```typescript theme={"dark"}
const enumerations = this.taskService.getEnumerations(); // TMEnumerations
```

#### `setView`

Sets the view configuration manually.

```typescript theme={"dark"}
this.taskService.setView(view, format);
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `view` | The view configuration object | `TMView` | ✅ | (view object) |
| `format` | Whether to format the view | `boolean` | ❌ | `false` |

### Real-time updates (SSE)

#### `initSse`

Initializes an SSE connection for real-time task updates. Call after `getTaskManagerResources()`.

```typescript theme={"dark"}
this.taskService.initSse();
```

#### `getSseEvents`

Gets an Observable stream of SSE events.

```typescript theme={"dark"}
this.taskService.getSseEvents()
  .subscribe((event) => {
    console.log('SSE event:', event);
  });
```

**Returns:** Observable emitting `MessageEvent<string>` objects.

#### `closeSseConnection`

Closes the SSE connection.

```typescript theme={"dark"}
ngOnDestroy(): void {
  this.taskService.closeSseConnection();
}
```

> [!NOTE]
>
> Always close the SSE connection when your component is destroyed to prevent memory leaks.

***

## UI Flow renderer

`FlxUiFlowRendererComponent` renders a full UI Flow (multi-view navigation, breadcrumbs, embedded processes, and an optional chat widget) from a single component.

```typescript theme={"dark"}
import { FlxUiFlowRendererComponent } from '@flowx/angular-sdk'
```

#### Usage

```html theme={"dark"}
<flx-ui-flow
  [apiUrl]="'https://yourDomain.dev'"
  [authToken]="authToken"
  [processApiPath]="'onboarding'"
  [language]="'en'"
  [locale]="'en-US'"
  [themeId]="themeId"
  [staticAssetsPath]="staticAssetsPath"
  [workspaceId]="workspaceId"
  [projectId]="projectId"
  [organizationId]="organizationId"
  [uiFlowName]="'my-ui-flow'"
  [isDraft]="false"
  [cache]="true"
  [buildId]="buildId"
/>
```

#### Parameters

| Name | Description | Type | Mandatory |
| - | - | - | - |
| `apiUrl` | Base API URL | `string` | ✅ |
| `authToken` | Authorization token | `string` | ✅ |
| `staticAssetsPath` | Static resources base path | `string` | ✅ |
| `workspaceId` | Workspace identifier | `string` | ✅ |
| `projectId` | FlowX Project ID | `string` | ✅ |
| `organizationId` | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade. See [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment) | `string` | ✅ |
| `uiFlowName` | Name of the UI Flow to start | `string` | ✅ |
| `themeId` | Theme identifier | `string` | ✅ |
| `language` | UI language | `string` | ✅ |
| `locale` | Date/number formatting locale | `string` | ✅ |
| `isDraft` | Render the draft version of the UI Flow | `boolean` | ✅ |
| `cache` | Enable caching | `boolean` | ✅ |
| `buildId` | Pinned build identifier | `string` | ❌ |
| `appVersionId` | Pin a specific app version | `string` | ❌ |
| `processApiPath` | Process subpath used by the embedded process renderer | `string` | ❌ |
| `startParams` | Initial query parameters passed to the UI Flow | `Record<string, unknown>` | ❌ |
| `customComponents` | Custom component registry | `Record<string, Type<any>>` | ❌ |
| `customValidators` | Custom validator registry | `Record<string, NgSyncValidator \| NgAsyncValidator>` | ❌ |

> [!NOTE]
>
> Angular uses separate `projectId` and optional `appVersionId?` inputs rather than a nested `appInfo` object.

### Starting a UI Flow

#### Prerequisites

* **UI Flow name**: The name of the UI Flow to start, passed as `uiFlowName`.
* **FlowX Project ID**: The `projectId` value, which identifies which project the UI Flow belongs to. Obtain it the same way as for processes: **FlowX Dashboard → Projects → copy UUID from the project actions popover**.
* **Process API path**: The `processApiPath` subpath used by the embedded process renderer when the UI Flow navigates into a full-screen process.

#### Getting the UI Flow name

Open FlowX Designer and navigate to **UI Flows**. The flow name displayed in the list is the value to pass as `uiFlowName`.

#### Initializing the UI Flow renderer

Minimal working example:

```typescript theme={"dark"}
import { Component } from '@angular/core';
import { FlxUiFlowRendererComponent } from '@flowx/angular-sdk';

@Component({
  selector: 'app-ui-flow',
  imports: [FlxUiFlowRendererComponent],
  template: `
    <flx-ui-flow
      [apiUrl]="'https://yourDomain.dev'"
      [authToken]="authToken"
      [processApiPath]="'onboarding'"
      [language]="'en'"
      [locale]="'en-US'"
      [themeId]="themeId"
      [staticAssetsPath]="staticAssetsPath"
      [workspaceId]="workspaceId"
      [projectId]="projectId"
      [organizationId]="organizationId"
      [uiFlowName]="uiFlowName"
      [isDraft]="false"
      [cache]="true"
    />
  `
})
export class UiFlowContainerComponent {
  authToken = '...'
  themeId = '...'
  staticAssetsPath = '...'
  workspaceId = '...'
  projectId = '...'
  organizationId = '...'
  uiFlowName = '...'
}
```

#### Passing initial parameters: `startParams`

Use `startParams` to inject query-string key/value pairs into the UI Flow at startup. The values are available inside the flow as URL query parameters.

```html theme={"dark"}
<flx-ui-flow
  [apiUrl]="apiUrl"
  [authToken]="authToken"
  [projectId]="projectId"
  [workspaceId]="workspaceId"
  [organizationId]="organizationId"
  [uiFlowName]="uiFlowName"
  [themeId]="themeId"
  [language]="language"
  [locale]="locale"
  [staticAssetsPath]="staticAssetsPath"
  [isDraft]="false"
  [cache]="true"
  [startParams]="{ referralCode: 'REF123', skipIntro: true }"
/>
```

> [!NOTE]
>
> `startParams` is read once at initialization. To trigger a full re-initialization, change one of the required inputs such as `uiFlowName`.

***

## Log Sink

The process and UI flow renderers can stream the SDK's internal activity — REST calls, SSE traffic and expression evaluations — to a callback you provide. Use it to debug a running process in the browser console, feed an in-app inspector, or forward events to your telemetry backend.

Attach it through two inputs available on both `<flx-process-renderer>` and `<flx-ui-flow>`:

| Input | Description | Type | Default |
| - | - | - | - |
| `logSink` | Log-event consumer(s). One function or an array — each receives every event. Subscribed when the renderer initializes, unsubscribed when it is destroyed | `FlxLogSink \| FlxLogSink[]` | - |
| `logCategories` | Restrict the stream to these categories. Omitted or empty delivers every category | `FlxLogCategory[]` | all |

## Quick start — print everything to the console

The SDK exports a ready-made console logger, `formattedLogger`. Pass it as the sink and every event is printed as a single colour-badged line.

```typescript theme={"dark"}
import { Component } from '@angular/core'
import { FlxProcessRendererComponent, formattedLogger } from '@flowx/angular-sdk'

@Component({
  selector: 'app-process-page',
  imports: [FlxProcessRendererComponent],
  template: `
    <flx-process-renderer
      [apiUrl]="apiUrl"
      [processApiPath]="processApiPath"
      [authToken]="token"
      [themeId]="themeId"
      [processName]="'onboarding'"
      [projectInfo]="{ projectId }"
      [staticAssetsPath]="staticAssetsPath"
      [organizationId]="organizationId"
      [logSink]="logSink"
    />
  `,
})
export class ProcessPageComponent {
  logSink = formattedLogger
}
```

Console output looks like:

```
 FlowX  rest        request POST https://…/api/process/onboarding/start
 FlowX  rest        response POST https://…/api/process/onboarding/start → 200 { … }
 FlowX  sse         connected https://…/api/process/…/events
 FlowX  expression  hide incomeSection → false { … }
 FlowX  sse         data { client: { firstName: 'Ion' } }
```

### Writing your own sink

A sink is any function that receives an `FlxLogEvent`. Pass one function or an array — each one receives every event.

```typescript theme={"dark"}
import { Component, inject } from '@angular/core'
import { FlxLogEvent, formattedLogger } from '@flowx/angular-sdk'

import { TelemetryService } from './telemetry.service'

@Component({
  selector: 'app-process-page',
  template: `<flx-process-renderer … [logSink]="logSink" />`,
})
export class ProcessPageComponent {
  #telemetry = inject(TelemetryService)

  logSink = [
    formattedLogger,
    (event: FlxLogEvent) =>
      this.#telemetry.track('flowx_sdk_event', {
        category: event.category,
        type: event.type,
        ...event.payload,
      }),
  ]
}
```

The inputs are read once when the renderer initializes; to change the sink, re-create the renderer.

### Filtering by category

Restrict the stream with `logCategories`. Omitting it (or passing an empty array) delivers every category.

```html theme={"dark"}
<flx-process-renderer
  …
  [logSink]="logSink"
  [logCategories]="['rest', 'sse']"
/>
```

### Using it with a UI flow

Attach the sink to the **UI flow renderer only**. Any process it opens — fullscreen or embedded through a Process Renderer component — reports on the same stream, so a single sink on `<flx-ui-flow>` already covers them. Attaching a second sink to an inner process renderer would deliver each event twice.

```html theme={"dark"}
<flx-ui-flow
  [apiUrl]="apiUrl"
  [processApiPath]="processApiPath"
  [authToken]="token"
  [themeId]="themeId"
  [uiFlowName]="'customer-portal'"
  [workspaceId]="workspaceId"
  [projectId]="projectId"
  [staticAssetsPath]="staticAssetsPath"
  [organizationId]="organizationId"
  [language]="language"
  [locale]="locale"
  [logSink]="logSink"
  [logCategories]="['expression']"
/>
```

### Console logger options

`formattedLogger` is tuned for a dark devtools console. Build your own variant with `createFormattedLogger`:

```typescript theme={"dark"}
import { createFormattedLogger } from '@flowx/angular-sdk'

// Light console palette
logSink = createFormattedLogger({ theme: 'light' })

// Log the raw FlxLogEvent object instead of the one-line summary —
// useful to see exactly what a custom sink would receive
logSink = createFormattedLogger({ raw: true })
```

### What you receive

```typescript theme={"dark"}
interface FlxLogEvent {
  timestamp: string // ISO 8601 with milliseconds, UTC
  category: 'rest' | 'sse' | 'expression' | 'cms'
  type: string
  payload: Record<string, unknown>
}
```

| Category | `type` values | Payload |
| - | - | - |
| `rest` | `request`, `response`, `error` | `url`, `method`, `status`, `headers` (request only), `body`, `message` (error only). Covers every call the SDK makes: process start/actions, enumerations, substitution tags, theme, images, documents, font metadata |
| `sse` | `connected`, `disconnected`, `error`, and each SSE event name (`data`, `processMetadata`, `runAction`, …) | `id`, `url`, `reason`, `event` (parsed JSON when the wire payload is JSON, otherwise the raw string). Heartbeats are not reported |
| `expression` | `hide`, `disabled`, `computed`, `conditional`, `validator`, `localScript` | `templateId`, `componentIdentifier`, `conditionIndex` (conditional styles only), `originalExpression` (as authored), `expression` (after data substitution), `result`, `error` (when evaluation threw) |
| `cms` | `fontRegistered`, `fontRegistrationFailed` | React Native only. On web, fonts load through the browser's `FontFace` API and emit no event |

Header values for `Authorization`, `Cookie`, `X-Api-Key` and `X-Fx-Anonymous-Session-Id` are redacted to their last 6 characters before reaching your sink.

***

## Utility API

These functions and pipes are exported from `@flowx/angular-sdk` and can be used independently of the renderer components.

```typescript theme={"dark"}
import {
  getEnumeration,
  getStaticAsset,
  getSubstitutionTag,
  FlxLocalizePipe,
} from '@flowx/angular-sdk'
```

> [!WARNING]
>
> These methods should only be used inside custom components and within a process context, because internal requests depend on the presence of running project details.

#### `getEnumeration`

Async function to fetch enumeration values.

```typescript theme={"dark"}
// get an enumeration by name
const enumeration = await getEnumeration('enumerationName')

// get enumeration with a parent
const enumeration = await getEnumeration('enumerationName', 'parentName')

// get enumeration and cache the result for subsequent calls
const enumeration = await getEnumeration('enumerationName', null, true)
```

| Parameter | Description | Type | Mandatory |
| - | - | - | - |
| `name` | Enumeration name | `string` | ✅ |
| `parentName` | Parent enumeration name for cascading | `string` | ❌ |
| `cached` | Use cached result when available | `boolean` | ❌ |

#### `getStaticAsset`

Resolves a static asset URL by its key.

```typescript theme={"dark"}
const url = getStaticAsset(key)
```

#### `getSubstitutionTag`

Resolves a substitution tag value by its key.

```typescript theme={"dark"}
const value = getSubstitutionTag(key)
```

#### `FlxLocalizePipe`

Standalone pipe for managing translations. Import it in the module or component where you want to use it:

```typescript theme={"dark"}
import { FlxLocalizePipe } from '@flowx/angular-sdk'

// In your module or component imports:
imports: [
  FlxLocalizePipe
]
```

Use in a template:

```html theme={"dark"}
<span>{{ 'hello' | flxLocalize }}</span>
```

Use in a component class:

```typescript theme={"dark"}
const localize = new FlxLocalizePipe()
const translatedText = localize.transform('@@substitution_tag')
```

***

## Custom CSS

The renderer SDK allows you to pass custom CSS classes on any component inside the process. These classes are applied to the component's root element.

To add a CSS custom class to a component, define the class in the process designer by navigating to the styles tab of the component, expanding the **Advanced** accordion and writing the CSS class.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/add_css_class.gif)

> [!WARNING]
>
> The classes will be applied last on the element, so they override the classes already defined on the element.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/css_class_inspector.png)

***

## Storybook

Below you find a Storybook which demonstrates how components behave under different states, props, and conditions. It allows you to preview and interact with individual UI components in isolation, without the need for a full-fledged app:

> [card] [Storybook](https://storybooks.flowxai.dev/)


# iOS SDK
Source: https://docs.flowx.ai/5.9/sdks/ios-renderer

Install and configure the FlowX.AI iOS SDK to render process-driven UI in native iOS apps. Requires iOS 15+ and Swift 5.9.

# Using the iOS Renderer

## iOS Project Requirements

The minimum requirements are:

* iOS 15
* Swift 5.9

## Installing the library

The iOS Renderer is available through Cocoapods.

### Cocoapods

#### Prerequisites

* Cocoapods gem installed

#### Cocoapods private trunk setup

Add the private trunk repo to your local Cocoapods installation with the command:

```ruby theme={"dark"}
pod repo add flowx-specs git@github.com:flowx-ai-external/flowx-ios-specs.git
```

#### Adding the dependency

Add the source of the private repository in the Podfile

```ruby theme={"dark"}
source 'git@github.com:flowx-ai-external/flowx-ios-specs.git'
```

Add a post install hook in the Podfile setting `BUILD_LIBRARY_FOR_DISTRIBUTION` to `YES`.

```ruby theme={"dark"}
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end
```

Add the pod and then run `pod install`

```ruby theme={"dark"}
pod 'FlowXRenderer'
```

Example

```ruby theme={"dark"}
source 'https://github.com/flowx-ai-external/flowx-ios-specs.git'
source 'https://github.com/CocoaPods/Specs.git'

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

target 'AppTemplate' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  
  # Pods for AppTemplate
  pod 'FlowXRenderer'
  
  target 'AppTemplateTests' do
    inherit! :search_paths
    # Pods for testing
  end
  
  target 'AppTemplateUITests' do
    # Pods for testing
  end
  
end
```

### Library dependencies

* Alamofire
* SDWebImageSwiftUI
* SDWebImageSVGCoder

## Info.plist permissions

Depending on which SDK features your processes and UI flows use, the host app must declare the corresponding usage descriptions in its `Info.plist`. Missing keys cause a crash the moment the feature is used.

| Info.plist key | Required when | SDK feature |
| - | - | - |
| `NSCameraUsageDescription` | The UI uses file/image upload actions with the camera source, or camera video recording | File upload components and upload actions (photo or video capture) |
| `NSMicrophoneUsageDescription` | The chat component has voice input enabled (audio-only recording), or upload actions record video with the camera (the video's audio track uses the microphone) | Chat voice messages; camera video upload |
| `NSPhotoLibraryUsageDescription` | The UI uses image upload from the photo library | File upload components and upload actions (library source). The SDK uses read-only pickers, so recent iOS versions may not prompt, but the key is recommended whenever library upload is enabled |

Notes:

* Document/file pickers (bulk file upload, chat file attachments) use the system files picker and require no permission keys.
* Sample declarations:

```xml theme={"dark"}
<key>NSCameraUsageDescription</key>
<string>Used to take photos and videos for uploads.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Used to record chat voice messages and video sound.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Used to pick photos for uploads.</string>
```

## Configuring the library

The SDK has 2 configurations, available through shared instances: `FXConfig` which holds general purpose properties, and `FXSessionConfig` which holds user session properties.

It is recommended to call the `FXConfig` configuration method at app launch.

Call the FXSessionConfig configure method after the user logs in and a valid user session is available.

### FXConfig

This config is used for general purpose properties.

#### Properties

| Name | Description | Type | Requirement |
| - | - | - | - |
| baseURL | The base URL used for REST networking | String | Mandatory |
| enginePath | The process engine url path component | String | Mandatory |
| imageBaseURL | The base URL used for static assets | String | Mandatory |
| organizationId | The UUID of the FlowX organization the host app belongs to | String | Mandatory |
| locale | The locale used for localization | String | Mandatory. Defaults to "en-us" |
| language | The language used for retrieving enumerations and substitution tags | String | Mandatory. Defaults to "en" |
| logLevel | Enum value indicating the log level logging. Default is none | FXLogLevel | Optional |
| logSink | Collector closure for structured log events (REST, SSE, expressions, CMS). See [Collecting log events](#collecting-log-events) | FXLogSink.Collector | Optional. Defaults to nil |
| additionalHttpHeaders | Additional HTTP headers included in all SDK network requests | \[String: String] | Optional. Defaults to \[:] |
| cacheDocuments | Whether to cache documents locally | Bool | Optional. Defaults to true |
| updateStateEnabled | Whether to check and update process state when the app returns to the foreground | Bool | Optional. Defaults to true |

#### Where to find these values

The mandatory configuration values are properties of your FlowX deployment, not of the SDK. Your DevOps team holds them, in the same configuration the FlowX Designer web app connects through:

| Value | Where it comes from |
| - | - |
| `organizationId` | The UUID assigned at FlowX organization registration. It is the same value set as `ORGANIZATION_ID` on your backend services and it is also the name of your Keycloak user realm. All three must match — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment). |
| `baseURL` | The entry point of your FlowX backend, from your deployment's ingress configuration. |
| `imageBaseURL` | The URL of the CMS Media Library module on your deployment, from the ingress configuration. If it is wrong, images and icons render blank. |
| `enginePath` | The URL path segment under which the process engine service is exposed, defined in your deployment's [ingress configuration](../setup-guides/ingress-configuration). On standard FlowX deployments this is `onboarding`. It is the mobile equivalent of the `PROCESS_API_PATH` variable used by the web container. The SDK's built-in default is `engine`, so set it explicitly unless your ingress actually exposes the engine under `/engine`. If it is wrong, process start and advance calls return a 404 error. |

**Sample**

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    config.baseURL = myBaseURL
    config.enginePath = "onboarding"
    config.imageBaseURL = myImageBaseURL
    config.organizationId = myOrganizationUuid
    config.locale = "en-us" 
    config.language = "en" 
    config.logLevel = .verbose
    config.logSink = { event in print("FxLogSink", event.jsonString) }
    config.additionalHttpHeaders = ["X-Custom-Header": "value"]
    config.cacheDocuments = true
    config.updateStateEnabled = true
}
```

#### Changing the current language

The current language and locale can be changed after the initial configuration, by calling the `changeLocaleSettings` method:

```swift theme={"dark"}
public func changeLocaleSettings(locale: String?,
                                 language: String?)
```

```swift theme={"dark"}
FXConfig.sharedInstance.changeLocaleSettings(locale: "ro-ro",
                                             language: "en")
```

> [!NOTE]
>
> For locale, use the format BCP 47. BCP 47 is the standard for representing language and region codes, here is a [link](https://www.w3.org/International/articles/language-tags/) to the BCP 47 specification.
> An example of BCP 47 is `en-us` (language code - `en` and region code - `us`).

### FXSessionConfig

This config is used for providing networking or auth session-specific properties.

The library expects either the JWT access token or an Alamofire Session instance managed by the container app. In case a session object is provided, the request adapting should be handled by the container app.

#### Properties

| Name | Description | Type |
| - | - | - |
| sessionManager | Alamofire session instance used for REST networking | Session |
| token | JWT authentication access token | String |
| anonymousSessionId | Identifier for anonymous sessions. When no `token` is set, the SDK sends this value as a header on its requests, for rendering processes exposed to unauthenticated users | String |

#### Sample for access token

```swift theme={"dark"}
    ...
    func configureFlowXSession() {
        FXSessionConfig.sharedInstance.configure { config in
            config.token = myAccessToken
        }
    }   

```

#### Sample for session

```swift theme={"dark"}
import Alamofire
```

```swift theme={"dark"}
    ...
    func configureFlowXSession() {
        FXSessionConfig.sharedInstance.configure { config in
            config.sessionManager = Session(interceptor: MyRequestInterceptor())
        }
    }   

```

```swift theme={"dark"}
class MyRequestInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest, for session: Session, completion: @escaping (Swift.Result<URLRequest, Error>) -> Void) {
        var urlRequest = urlRequest
        urlRequest.setValue("Bearer " + accessToken, forHTTPHeaderField: "Authorization")
        completion(.success(urlRequest))
    }    
}
```

### Theming

> [!WARNING]
>
> Make sure the `FXSessionConfig` configure method was called with a valid session before setting up the theme.

Before starting or resuming a process, the theme setup API should be called.
The start or continue process APIs should be called only after the theme setup was completed.

### Theme setup

The setup theme is called using the shared instance of `FXTheme`

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```

* `uuid` - the UUID of the theme configured in the FlowX Designer.

* `workspaceId` - the UUID of the workspace the theme belongs to.

* `localFileUrl` - optional parameter for providing a fallback theme file, in case the fetch theme request fails.

* `appearance` - optional SwiftUI `ColorScheme` (`.light` or `.dark`) used to render the theme. Defaults to `.light`.

* `completion` - a completion closure called when the theme setup finishes.

In addition to the `completion` parameter, FXTheme's shared instance also provides a Combine publisher named `themeFetched` which sends `true` if the theme setup was finished.

#### Sample

```swift theme={"dark"}
FXTheme.sharedInstance.setupTheme(withUuid: myThemeUuid,
                                  workspaceId: workspaceUuid,
                                  localFileUrl: Bundle.main.url(forResource: "theme", withExtension: "json"),
                                  appearance: .light,
                                  completion: {
    print("theme setup finished")
})
```

```swift theme={"dark"}
...
    var subscription: AnyCancellable?

    func myMethodForThemeSetupFinished() {
        subscription = FXTheme.sharedInstance.themeFetched.sink { result in
            if result {
                DispatchQueue.main.async {
                    // you can now start/continue a process
                }
            }
        }
    }
}
    
...

```

## Using the library

### Public API

The library's public APIs described in this section are called using the shared instance of FlowX, `FlowX.sharedInstance`.

### How to start and end FlowX session

After all the configurations are set, you can start a FlowX session by calling the `startSession()` method.

This is optional, as the session starts lazily when the first process is started.

`FlowX.sharedInstance.startSession()`

When you want to end a FlowX session, you can call the `endSession()` method. This also does a complete clean-up of the started processes.

You might want to use this method in a variety of scenarios, for instance when the user logs out.

`FlowX.sharedInstance.endSession()`

### How to start a process

There are 3 methods available for starting a FlowX process.
The container app is responsible with presenting the navigation controller or tab controller holding the process navigation.

1. Start a process which renders inside an instance of `UINavigationController` or `UITabBarController`, depending on the BPMN diagram of the process.

The controller to be presented is provided through the `completion` closure parameter of the method.

> [!TIP]
>
> Use this method when you want the process to be rendered inside a controller themed using the FlowX Theme defined in the FlowX Designer, regardless of the navigation type configured for the process.

```swift theme={"dark"}
public func startProcess(workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         completion: ((UIViewController?, String) -> Void)?,
                         onProcessEnded: (() -> Void)? = nil)
```

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the process

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the process.

* `completion` - a completion closure which passes either an instance of `UINavigationController` or `UITabBarController` to be presented, alongside the started process instance UUID. The UUID is an empty string if the process failed to start.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

2. Start a process which renders inside a provided instance of a `UINavigationController`.

> [!TIP]
>
> Use this method when you want the process to be rendered inside a custom instance of `UINavigationController`.\
> Optionally you can pass an instance of `FXNavigationViewController`, which has the appearance set in the FlowX Theme, using the `FXNavigationViewController`s class func `FXNavigationViewController.navigationController()`.

If you use this method, make sure that the process does not use a tab controller as root view.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessStarted: ((String) -> Void)? = nil,
                         onProcessEnded: (() -> Void)? = nil)
```

* `navigationController` - the instance of UINavigationController which will hold the process navigation stack

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the process

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the process.

* `onProcessStarted` - an optional closure called after the process has been started, providing the process instance UUID.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

3. Start a process which renders inside a provided instance of a `UITabBarController`.

> [!TIP]
>
> Use this method when you want the process to be rendered inside a custom instance of `UITabBarController`.

> [!WARNING]
>
> If you use this method, make sure that the process has a tab controller as root view.

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessStarted: ((String) -> Void)? = nil,
                         onProcessEnded: (() -> Void)? = nil)
```

* `tabBarController` - the instance of UITabBarController which will hold the process navigation

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the process

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the process.

* `onProcessStarted` - an optional closure called after the process has been started, providing the process instance UUID.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

#### Sample

```swift theme={"dark"}
FlowX.sharedInstance.startProcess(workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true) { processRootViewController, processInstanceUuid in
    if let processRootViewController = processRootViewController {
        processRootViewController.modalPresentationStyle = .overFullScreen
        self.present(processRootViewController, animated: false)
    }
    //TODO use processInstanceUuid if needed
} onProcessEnded: { [weak self] in
    //TODO handle process end
}
```

or

```swift theme={"dark"}
FlowX.sharedInstance.startProcess(navigationController: processNavigationController,
                                  workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true,
                                  onProcessStarted: { processInstanceUuid in
    //TODO use processInstanceUuid if needed
}, onProcessEnded: { [weak self] in
    //TODO handle process end
})

self.present(processNavigationController, animated: true, completion: nil)
```

or

```swift theme={"dark"}
FlowX.sharedInstance.startProcess(tabBarController: processTabController,
                                  workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true,
                                  onProcessStarted: { processInstanceUuid in
    //TODO use processInstanceUuid if needed
}, onProcessEnded: { [weak self] in
    //TODO handle process end
})

self.present(processTabController, animated: true, completion: nil)
```

### How to start a UI Flow

UI Flows are lightweight, screen-driven flows defined in the FlowX Designer. They run client-side on top of a data model, without requiring a BPMN process instance on the engine.

The container app is responsible with presenting the controller passed in the `completion` closure.

```swift theme={"dark"}
public func startUIFlow(workspaceId: String,
                        projectId: String,
                        name: String,
                        params: [String: Any]?,
                        isModal: Bool = false,
                        showLoader: Bool = false,
                        completion: ((UIViewController?) -> Void)?)
```

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project

* `name` - the name of the UI Flow

* `params` - the start parameters, if any

* `isModal` - a boolean indicating whether the UI Flow navigation is modally displayed. When the navigation is displayed modally, a close bar button item is displayed on each screen.

* `showLoader` - a boolean indicating whether the loader should be displayed when starting the UI Flow.

* `completion` - a completion closure which passes either an instance of `UINavigationController` or `UITabBarController` to be presented, depending on the navigation configured for the UI Flow.

#### Sample

```swift theme={"dark"}
FlowX.sharedInstance.startUIFlow(workspaceId: workspaceUuid,
                                 projectId: applicationUuid,
                                 name: uiFlowName,
                                 params: [:],
                                 isModal: true,
                                 showLoader: true) { rootViewController in
    if let rootViewController = rootViewController {
        rootViewController.modalPresentationStyle = .overFullScreen
        self.present(rootViewController, animated: false)
    }
}
```

### How to use the standalone chat

The chat component can be used on its own, outside of any process or UI Flow. The SDK exposes a self-contained SwiftUI view connected to an AI conversational workflow.

Prerequisites:

* `FXConfig` configured with the environment's `baseURL` (and `imageBaseURL` if themed icons are used)
* authorization configured through `FXSessionConfig` / `FlowX.sharedInstance.updateAuthorization(token:)`, or anonymous mode
* optionally, a theme loaded through `FXTheme.setupTheme`. Without one, the chat renders with system fallbacks
* `NSMicrophoneUsageDescription` in the host app's Info.plist when voice input is enabled

```swift theme={"dark"}
public enum FXChat {
    public static func chatView(configuration: FXChatConfiguration,
                                onClose: (() -> Void)? = nil) -> some View
}
```

* `configuration` - the connection and UI configuration of the chat

* `onClose` - an optional closure, called when the user taps the close button in the chat header. When omitted, the close button is not displayed.

`FXChatConfiguration` properties:

* `workspaceId` - the uuid of the workspace

* `projectId` - the uuid of the project the conversational workflow belongs to

* `workflowResDefId` - the resource definition uuid of the AI conversational workflow

* `buildId` - optional, the uuid of the active build, sent as part of the message context

* `uiFlowSessionUuid` / `uiFlowResDefId` - optional, link the chat to a UI Flow session when embedded alongside one

* `ui` - an `FXChatUIConfig` value controlling content and behaviour: header title and subtitle, welcome and thinking messages, input placeholder, suggested prompts, voice input and file attachments toggles, attachment limits, history title, etc. All fields have defaults.

The chat session lives as long as the returned view's identity. Recreating the view starts a fresh session.

#### Sample

```swift theme={"dark"}
struct ChatScreen: View {
    @Environment(\.dismiss) private var dismiss

    var body: some View {
        FXChat.chatView(configuration: chatConfiguration) {
            dismiss()
        }
    }

    private var chatConfiguration: FXChatConfiguration {
        var ui = FXChatUIConfig()
        ui.title = "Assistant"
        ui.welcomeMessage = "Hello! How can I help you today?"
        ui.voiceInputEnabled = true
        ui.fileAttachmentsEnabled = true

        return FXChatConfiguration(workspaceId: workspaceUuid,
                                   projectId: projectUuid,
                                   workflowResDefId: chatWorkflowResDefUuid,
                                   buildId: buildUuid,
                                   ui: ui)
    }
}
```

Presenting from UIKit:

```swift theme={"dark"}
let chatView = FXChat.chatView(configuration: chatConfiguration) { [weak self] in
    self?.presentedViewController?.dismiss(animated: true)
}
let controller = UIHostingController(rootView: chatView)
controller.modalPresentationStyle = .pageSheet
present(controller, animated: true)
```

### How to resume an existing process

There are 3 methods available for resuming a FlowX process.
The container app is responsible with presenting the navigation controller or tab controller holding the process navigation.

1. Continue a process which renders inside an instance of `UINavigationController` or `UITabBarController`, depending on the BPMN diagram of the process.

The controller to be presented will be provided inside the `completion` closure parameter of the method.

> [!TIP]
>
> Use this method when you want the process to be rendered inside a controller themed using the FlowX Theme defined in the FlowX Designer.

```swift theme={"dark"}
public func continueExistingProcess(uuid: String,
                                    name: String,
                                    isModal: Bool = false,
                                    showLoader: Bool = false,
                                    completion: ((UIViewController?) -> Void)? = nil,
                                    onProcessEnded: (() -> Void)? = nil)
```

* `uuid` - the UUID string of the process

* `name` - the name of the process

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when resuming the process.

* `completion` - a completion closure which passes either an instance of `UINavigationController` or `UITabBarController` to be presented.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

2. Continue a process which renders inside a provided instance of a `UINavigationController`.

> [!TIP]
>
> Use this method when you want the process to be rendered inside a custom instance of `UINavigationController`.\
> Optionally you can pass an instance of `FXNavigationViewController`, which has the appearance set in the FlowX Theme, using the `FXNavigationViewController`s class func `FXNavigationViewController.navigationController()`.

If you use this method, make sure that the process does not use a tab controller as root view.

```swift theme={"dark"}
public func continueExistingProcess(uuid: String,
                                    name: String,
                                    navigationController: UINavigationController,
                                    isModal: Bool = false,
                                    showLoader: Bool = false,
                                    onProcessEnded: (() -> Void)? = nil)
```

* `uuid` - the UUID string of the process

* `name` - the name of the process

* `navigationController` - the instance of UINavigationController which will hold the process navigation stack

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when resuming the process.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

3. Continue a process which renders inside a provided instance of a `UITabBarController`.

> [!TIP]
>
> Use this method when you want the process to be rendered inside a custom instance of `UITabBarController`.

> [!WARNING]
>
> If you use this method, make sure that the process has a tab controller as root view.

```swift theme={"dark"}
public func continueExistingProcess(uuid: String,
                                    name: String,
                                    tabBarController: UITabBarController,
                                    isModal: Bool = false,
                                    showLoader: Bool = false,
                                    onProcessEnded: (() -> Void)? = nil)
```

* `uuid` - the UUID string of the process

* `name` - the name of the process

* `tabBarController` - the instance of UITabBarController which will hold the process navigation

* `isModal` - a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation.

* `showLoader` - a boolean indicating whether the loader should be displayed when resuming the process.

* `onProcessEnded` - a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using \[weak self]

#### Sample

```swift theme={"dark"}
FlowX.sharedInstance.continueExistingProcess(uuid: uuid,
                                             name: processName,
                                             isModal: true) { processRootViewController in
    if let processRootViewController = processRootViewController {
        processRootViewController.modalPresentationStyle = .overFullScreen
        self.present(processRootViewController, animated: true)
    }
} onProcessEnded: { [weak self] in
    
}
```

or

```swift theme={"dark"}
FlowX.sharedInstance.continueExistingProcess(uuid: uuid,
                                             name: processName,
                                             navigationController: processNavigationController,
                                             isModal: true)
processNavigationController.modalPresentationStyle = .overFullScreen

self.present(processNavigationController, animated: true, completion: nil)
```

or

```swift theme={"dark"}
FlowX.sharedInstance.continueExistingProcess(uuid: uuid,
                                             name: processName,
                                             tabBarController: processTabBarController,
                                             isModal: false)
processTabBarController.modalPresentationStyle = .overFullScreen

self.present(processTabBarController, animated: true, completion: nil)
```

### How to resume the latest process

You can resume the most recently started process using `continueLatestProcess`. This method uses the internally tracked latest process instance UUID.

```swift theme={"dark"}
public func continueLatestProcess(name: String,
                                  navigationController: UINavigationController,
                                  isModal: Bool = false)
```

* `name` - the name of the process

* `navigationController` - the instance of UINavigationController which will hold the process navigation stack

* `isModal` - a boolean indicating whether the process navigation is modally displayed

#### Sample

```swift theme={"dark"}
FlowX.sharedInstance.continueLatestProcess(name: processName,
                                           navigationController: processNavigationController,
                                           isModal: true)

self.present(processNavigationController, animated: true, completion: nil)
```

### How to end a process

You can manually end a process by calling the `stopProcess(name: String)` method.

This is useful when you want to explicitly ask the FlowX shared instance to clean up the instance of the process sent as parameter.

For example, it could be used for modally displayed processes that are dismissed by the user, in which case the `dismissRequested(forProcess process: String, navigationController: UINavigationController)` method of the FXDataSource will be called.

#### Sample

```swift theme={"dark"}
FlowX.sharedInstance.stopProcess(name: processName)
```

### FXDataSource

The library offers a way of communication with the container app through the `FXDataSource` protocol.

The data source is a public property of FlowX shared instance.

`public weak var dataSource: FXDataSource?`

```swift theme={"dark"}
public protocol FXDataSource: AnyObject {
    func controllerFor(componentIdentifier: String) -> FXController?
    
    func viewFor(componentIdentifier: String) -> FXView?
    
    func viewFor(componentIdentifier: String, customComponentViewModel: FXCustomComponentViewModel) -> AnyView?

    func navigationController() -> UINavigationController?

    func errorReceivedForAction(name: String?)
    
    func validate(validatorName: String, value: Any, params: [String]?) -> Bool
    
    func dismissRequested(forProcess process: String, navigationController: UINavigationController)
    
    func viewForStepperHeader(stepViewModel: StepViewModel) -> AnyView?

    func collect(event: AnalyticsEvent)
 
    func newProcessStarted(processInstanceUuid: String)
    
    func customLoader(type: CustomLoaderType) -> AnyView?
}
```

* `func controllerFor(componentIdentifier: String) -> FXController?`

This method is used for providing a custom component using UIKit UIViewController, identified by the componentIdentifier argument.

* `func viewFor(componentIdentifier: String) -> FXView?`

This method is used for providing a custom component using UIKit UIView, identified by the componentIdentifier argument.

* `func viewFor(componentIdentifier: String, customComponentViewModel: FXCustomComponentViewModel) -> AnyView?`

This method is used for providing a custom component using SwiftUI View, identified by the componentIdentifier argument.
A view model is provided as an ObservableObject to be added as @ObservedObject inside the SwiftUI view for component data observation.

* `func navigationController() -> UINavigationController?`

This method is used for providing a navigation controller. It can be either a custom `UINavigationController` class, or just a regular `UINavigationController` instance themed by the container app.

* `func errorReceivedForAction(name: String?)`

This method is called when an error occurs after an action is executed.

* `func validate(validatorName: String, value: Any, params: [String]?) -> Bool`

This method is used for custom validators. It provides the name of the validator, the value to be validated, and an optional array of parameter strings. The method returns a boolean indicating whether the value is valid or not.

* `func dismissRequested(forProcess process: String, navigationController: UINavigationController)`

This method is called, on a modally displayed process navigation, when the user attempts to dismiss the modal navigation. Typically it is used when you want to present a confirmation pop-up.

The container app is responsible with dismissing the UI and calling the stop process APIs.

* `func viewForStepperHeader(stepViewModel: StepViewModel) -> AnyView?`

This method is used for providing a custom SwiftUI view for the stepper navigation header.

* `func collect(event: AnalyticsEvent)`

This method is used for collecting analytics events from the SDK. The parameter is a `AnalyticsEvent` enum, which can represent a screen or an action.

* `func newProcessStarted(processInstanceUuid: String)`

This method is used for handling the start of another main process as a result of a `START_PROJECT` action. The parameter is the uuid of the process instance. The container app is responsible for dismissing the navigation of the current process and displaying the new process navigation.

* `func customLoader(type: CustomLoaderType) -> AnyView?`

This method is used for providing a custom loader view. It is called by the SDK when a loading indicator needs to be displayed. The `type` parameter indicates the context in which the loader is shown. Return `nil` to use the default loader.

This method has a default implementation that returns `nil`.

```swift theme={"dark"}
public enum CustomLoaderType {
    case startProcess
    case reloadProcess
    case action(String?)
    case upload(String?)
}
```

* `startProcess` - the loader is displayed when a process is being started
* `reloadProcess` - the loader is displayed when a process is being reloaded
* `action(String?)` - the loader is displayed when an action is being executed. The associated value is the action name, if available.
* `upload(String?)` - the loader is displayed for an in-progress file upload. The associated value is the action name, if available.

#### Sample

```swift theme={"dark"}
class MyFXDataSource: FXDataSource {
    func controllerFor(componentIdentifier: String) -> FXController? {
        switch componentIdentifier {
        case "customComponent1":
            let customComponent: CustomViewController = viewController()
            return customComponent
        default:
            return nil
        }
    }
    
    func viewFor(componentIdentifier: String) -> FXView? {
        switch componentIdentifier {
        case "customComponent2":
            return CustomView()
        default:
            return nil
        }
    }
    
    func viewFor(componentIdentifier: String, customComponentViewModel: FXCustomComponentViewModel) -> AnyView? {
        switch componentIdentifier {
        case "customComponent2":
            return AnyView(SUICustomView(viewModel: customComponentViewModel))
        default:
            return nil
        }
    }
    
    func navigationController() -> UINavigationController? {
        nil
    }
    
    func errorReceivedForAction(name: String?) {
        
    }
    
    func validate(validatorName: String, value: Any, params: [String]?) -> Bool {
        switch validatorName {
        case "myCustomValidator":
            let myCustomValidator = MyCustomValidator(input: value as? String)
            return myCustomValidator.isValid()
        default:
            return true
        }
    }
    
    func dismissRequested(forProcess process: String, navigationController: UINavigationController) {
        navigationController.dismiss(animated: true, completion: nil)
        FlowX.sharedInstance.stopProcess(name: process)
    }

    func viewForStepperHeader(stepViewModel: StepViewModel) -> AnyView? {
        return AnyView(CustomStepperHeaderView(stepViewModel: stepViewModel))
    }

    func collect(event: AnalyticsEvent) {
        //TODO: collect event using the desired analytics tool.
    }
 
    func newProcessStarted(processInstanceUuid: String) {
        //TODO present new process instance navigation
    }

    func customLoader(type: CustomLoaderType) -> AnyView? {
        switch type {
        case .startProcess:
            return AnyView(MyStartProcessLoader())
        case .reloadProcess:
            return AnyView(MyReloadLoader())
        case .action(let actionName):
            return AnyView(MyActionLoader(actionName: actionName))
        case .upload(let actionName):
            return AnyView(MyUploadLoader(actionName: actionName))
        }
    }

}
```

### Custom components

#### FXController

FXController is an open class subclassing UIViewController, which helps the container app provide full custom screens the renderer.
It needs to be subclassed for each custom screen.

> [!WARNING]
>
> Use this only when the custom component configured in the UI Designer is the root component of the User Task node.

```swift theme={"dark"}
open class FXController: UIViewController {
    
    internal(set) public var data: Any?
    internal(set) public var actions: [ProcessActionModel]?

    open func titleForScreen() -> String? {
        return nil
    }
    
    open func populateUI() {
        
    }
    
    open func updateUI() {
        
    }
    
}
```

* `internal(set) public var data: Any?`

`data` is the property, containing the data model for the custom component. The type is Any, as it could be a primitive value, a dictionary or an array, depending on the component configuration.

* `internal(set) public var actions: [ProcessActionModel]?`

`actions` is the array of actions provided to the custom component.

* `func titleForScreen() -> String?`

This method is used for setting the screen title. It is called by the renderer when the view controller is displayed.

* `func populateUI()`

This method is called by the renderer, after the controller has been presented, when the data is available.

This will happen asynchronously. It is the container app's responsibility to make sure that the initial state of the view controller does not have default/residual values displayed.

* `func updateUI()`

This method is called by the renderer when an already displayed view controller needs to update the data shown.

#### FXView

FXView is a protocol that helps the container app provide custom UIKit subviews to the renderer. It needs to be implemented by `UIView` instances. Similar to `FXController` it has data and actions properties and a populate method.

```swift theme={"dark"}
public protocol FXView: UIView {
    var data: Any? { get set }
    var actions: [ProcessActionModel]? { get set }

    func populateUI()
}
```

* `var data: Any?`

`data` is the property containing the data model for the custom view. The type is Any, as it could be a primitive value, a dictionary or an array, depending on the component configuration.

* `var actions: [ProcessActionModel]?`

`actions` is the array of actions provided to the custom view.

* `func populateUI()`

This method is called by the renderer after the screen containing the view has been displayed.

It is the container app's responsibility to make sure that the initial state of the view does not have default/residual values displayed.

> [!WARNING]
>
> It is mandatory for views implementing the FXView protocol to provide the intrinsic content size.

```swift theme={"dark"}
override var intrinsicContentSize: CGSize {
    return CGSize(width: UIScreen.main.bounds.width, height: 100)
}
```

#### SwiftUI Custom components

Custom SwiftUI components can be provided as type-erased views.

`FXCustomComponentViewModel` is a class implementing the `ObservableObject` protocol. It is used for managing the state of custom SwiftUI views.
It has two published properties, for data and actions. It also includes a `saveData` dictionary and a `validate` closure used for submitting and validating data from the custom components.

```swift theme={"dark"}
    @Published public var data: Any?
    @Published public var actions: [ProcessActionModel] = []
    public var saveData: [String: Any]?
    public var validate: (() -> Bool)?
```

Example

```swift theme={"dark"}
struct SampleView: View {
    
    @ObservedObject var viewModel: FXCustomComponentViewModel
            
    var body: some View {
        Text("Lorem")
    }
}
```

### Validating SwiftUI Custom Components

A SwiftUI Custom Component can validate and submit data from a custom component, when executing an action from a FlowX.AI UI Component.

* `public var saveData: [String: Any]?`
  Used for setting data to be submitted from the custom component.

* `public var validate: (() -> Bool)?`
  Used for validating the custom component data before executing the action.

#### Sample

```swift theme={"dark"}
struct MyCustomView: View {

    @ObservedObject var viewModel: FXCustomComponentViewModel

    var body: some View {
        VStack {
            ...
        }
        .onAppear {
            viewModel.saveData = ["customKey": "customValue"]
            viewModel.validate = {
                return true
            }
        }
        .frame(height: 200)
    }
}
```

### Custom header view for Stepper navigation

The container application can provide a custom view that will be used as the stepper navigation header, using the `FXDataSource` protocol method `viewForStepperHeader`.
The method has a parameter, which provides the data needed for populating the view's UI.

```swift theme={"dark"}
public struct StepViewModel {
    // title for the current step; optional
    public var stepTitle: String?
    // title for the current substep, if there is a stepper in stepper configured; optional
    public var substepTitle: String?
    // 1-based index of the current step
    public var step: Int
    // total number of steps
    public var totalSteps: Int
    // 1-based index of the current substep, if there is a stepper in stepper configured; optional
    public var substep: Int?
    // total number of substeps in the current step, if there is a stepper in stepper configured; optional
    public var totalSubsteps: Int?
}
```

#### Sample

```swift theme={"dark"}
struct CustomStepperHeaderView: View {
    
    let viewModel: StepViewModel
            
    var body: some View {
        VStack(spacing: 16) {
            ProgressView(value: Float(stepViewModel.step) / Float(stepViewModel.totalSteps))
                .foregroundStyle(Color.blue)
            if let stepTitle = stepViewModel.stepTitle {
                Text(stepTitle)
            }
            if let substepTitle = stepViewModel.substepTitle {
                Text(substepTitle)
            }
        }
        .background(Color.white)
        .shadow(radius: 10)
    }
}
```

### How to run an action from a custom component

The custom components which the container app provides will contain FlowX actions to be executed. To run an action you need to call the following method:

```swift theme={"dark"}
public func runAction(action: ProcessActionModel,
                      params: [String: Any]? = nil)
```

`action` - the `ProcessActionModel` action object

`params` - the parameters for the action

### How to run an upload action from a custom component

```swift theme={"dark"}
public func runUploadAction(action: ProcessActionModel,
                            image: UIImage)
```

`action` - the `ProcessActionModel` action object

`image` - the image to upload

```swift theme={"dark"}
public func runUploadAction(action: ProcessActionModel,
                            fileURL: URL)
```

`action` - the `ProcessActionModel` action object

`fileURL` - the local URL of the file

### Getting a substitution tag value by key

```swift theme={"dark"}
public func getTag(withKey key: String) -> String?
```

All substitution tags will be retrieved by the SDK before starting the first process and will be stored in memory.&#x20;

Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag using the method above, providing the key.

### Getting a media item url by key

```swift theme={"dark"}
public func getMediaItemURL(withKey key: String) -> String?
```

All media items will be retrieved by the SDK before starting the first process and will be stored in memory.

Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url using the method above, providing the key.

### Getting enumeration values

The SDK provides two methods for fetching enumeration values, an async/await version and a callback version.

```swift theme={"dark"}
public func getEnumeration(name: String,
                           parentName: String?) async -> [EnumerationItem]?
```

```swift theme={"dark"}
public func getEnumeration(name: String,
                           parentName: String?,
                           completion: (([EnumerationItem]?) -> Void)?)
```

* `name` - the name of the enumeration to retrieve

* `parentName` - the parent enumeration name, if the enumeration is a child. Pass `nil` for root enumerations.

* `completion` - a closure called with the array of enumeration items, or `nil` if not found (callback version only)

The method first checks the local cache and returns cached items if available. If not cached, it fetches the enumeration from the server.

#### EnumerationItem

```swift theme={"dark"}
public struct EnumerationItem: Codable {
    public var type: String?
    public var order: Int?
    public var childContentDescription: EnumerationChildContentDescription?
    public var code: String?
    public var content: String?
}

public struct EnumerationChildContentDescription: Codable {
    public var name: String?
}
```

#### Sample

```swift theme={"dark"}
// Using async/await
let items = await FlowX.sharedInstance.getEnumeration(name: "cities",
                                                      parentName: "countries")

// Using completion handler
FlowX.sharedInstance.getEnumeration(name: "cities",
                                    parentName: "countries") { items in
    guard let items = items else { return }
    // use enumeration items
}
```

### Collecting analytics events

To collect analytics events from the SDK, the `collect(event: AnalyticsEvent)` func of the `FXDataSource` protocol needs to be implemented.

The func will be called by the SDK each time a screen or an action analytics event occurs.

The type of the event and relevant metadata are included in the func parameter `event` which is a `AnalyticsEvent` enum case.

```Swift theme={"dark"}
public enum AnalyticsEvent {
    case screen(AnalyticsScreenData)
    case action(AnalyticsActionData)
}

public struct AnalyticsScreenData {
    public var value: String
    public var customPayload: [String: Any]?
}

public struct AnalyticsActionData {
    public var value: String
    public var component: String?
    public var label: String?
    public var screen: String?
    public var customPayload: [String: Any]?
}
```

> [!NOTE]
>
> The value property represents the identifier set in the process definition.
>
> Both screen and action events include an optional `customPayload` dictionary for additional custom data configured in the process definition.
>
> For action type events there are some additional properties provided:
>
> * component - The type of component triggering the action
> * label - The label of the component, if available. (E.g. title of a button or label of a form element)
> * screen - The identifier of the screen containing the component, if set

### Collecting log events

To collect structured log events from the SDK — REST traffic, SSE traffic, JS expression evaluations and CMS font registrations — set a `logSink` collector closure on `FXConfig`. The collector is independent of `logLevel` (which drives the OSLog debug output).

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    // ...
    config.logSink = { event in
        // do whatever is needed (e.g. print the event, forward it to an external telemetry system, etc.)
        print("FxLogSink", event.jsonString)
    }
}
```

The collector receives `FXLogSink.Event` values, structured like this:

```swift theme={"dark"}
public enum FXLogSink {
    public typealias Collector = (Event) -> Void

    public struct Event {
        /// Capture time, ISO 8601 @ UTC: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`
        public let timestamp: String

        /// One of "rest", "sse", "expression", "cms"
        public let category: String

        /// The event type within `category`:
        /// - rest → one of "request", "response", "error"
        /// - sse → the raw server-sent event name (e.g. "data", "processMetadata", ...) or one of "connected", "disconnected", "error"
        /// - expression → one of "hide", "disabled", "computed", "conditional", "validator", "localScript", "triggerCondition"
        /// - cms → "fontRegistered"
        public let type: String

        /// JSON-compatible dictionary with raw data specific to the event type
        public let payload: [String: Any]

        /// The whole event serialized as a JSON string
        public var jsonString: String { get }
    }
}
```

The category and type constants are available as `FXLogSink.Category.*` and `FXLogSink.EventType.Rest.*` / `.Sse.*` / `.Expression.*` / `.Cms.*`.

> [!NOTE]
>
> Events are delivered one at a time, in emit order, on a background queue — dispatch to another queue before doing heavy work.
> The internal buffer is bounded: if the collector cannot keep up, the oldest buffered events are dropped.
> Leave `logSink` `nil` (the default) when not consuming events — a non-nil collector, even a no-op one, is the activation switch for the whole capture pipeline (HTTP body copies, JSON conversion) and pays its full cost.

### Handling authorization token changes

When the access token of the auth session changes, you can update it in the renderer using the `func updateAuthorization(token: String)` method.

```swift theme={"dark"}
FlowX.sharedInstance.updateAuthorization(token: accessToken)
```


# React Native SDK
Source: https://docs.flowx.ai/5.9/sdks/react-native-renderer

The React Native renderer SDK renders processes configured in the FlowX Designer inside a React Native app, using an imperative API.

## React Native project requirements

> [!NOTE]
>
> The FlowX packages declare `react-native` **≥ 0.83.0** and `react` **≥ 19.2.0** as peer dependencies. The validated target is **React Native 0.85.3 with Expo SDK 56**, which is what FlowX builds and tests against. Your `react` must also satisfy the peer dependency of your own React Native version (`^19.2.3` for `react-native@0.85.3`). React Native 0.85.3 requires Node `^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0`.

| Platform | Minimum | Notes |
| - | - | - |
| iOS deployment target | **15.1** bare React Native, **16.4** with Expo | 15.1 is the React Native 0.85 baseline and the minimum of the FlowX native module. Expo SDK 56 raises it to 16.4 (up from 15.1 in Expo 55); `expo prebuild` writes `platform :ios, '16.4'` into `ios/Podfile`. |
| Android `minSdkVersion` | **24** (Android 7.0) | Set in `android/build.gradle`. The FlowX native module falls back to 24 when the host app does not define it. |
| Android `compileSdkVersion` / `targetSdkVersion` | RN 0.85 + Expo SDK 56 defaults | Don't override unless required. Set by `react-native-gradle-plugin` / `expo-root-project` after `expo prebuild`. The FlowX native module falls back to 35 when the host app does not define them. |

> [!TIP]
>
> To install the npm libraries provided by FlowX.AI you will need access to the private FlowX.AI Nexus registry. Consult your project DevOps.

> [!WARNING]
>
> `react` must satisfy React Native's published peer dependency. For `react-native@0.85.3` this is `^19.2.3`; newer RN 0.85.x patches may shift it — check with `npm view react-native@<your-version> peerDependencies`. Installing React Native via the official template (Bare CLI) or Expo SDK 56 picks a compatible `react` automatically — don't override it with a manual pin unless you have a reason.

## Installation

> [tab] Bare React Native CLI
>
> For new projects, bootstrap with the official React Native template so `react` and `react-native` ship as a matched pair that satisfies the peer dependency in the Warning above:
>
> ```bash theme={"dark"}
> npx @react-native-community/cli@latest init MyApp
> cd MyApp
> ```
>
> For existing projects, ensure `react` already satisfies your installed `react-native`'s declared peer (`npm view react-native@<your-version> peerDependencies`) before installing the FlowX SDK.
>
> Then install the FlowX SDK and peers:
>
> ```bash theme={"dark"}
> npm install \
>   @flowx/react-native-sdk@<version> \
>   @flowx/react-native-ui-toolkit@<version> \
>   @flowx/react-native-theme@<version> \
>   @flowx/core-sdk@<version> \
>   @flowx/core-theme@<version> \
>   react-dom \
>   @react-native-async-storage/async-storage \
>   react-native-screens \
>   react-native-safe-area-context \
>   react-native-svg \
>   react-native-enriched-markdown \
>   react-native-pdf-renderer \
>   react-native-blob-util \
>   react-native-keyboard-controller \
>   react-native-reanimated \
>   react-native-worklets \
>   react-native-image-picker \
>   @react-native-documents/picker \
>   @react-native-community/datetimepicker \
>   @react-native-community/slider \
>   @react-native-segmented-control/segmented-control
> ```
>
> > [!WARNING]
> >
> > Replace `<version>` with the correct version corresponding to your platform version.
> >
> > To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.
>
> Then install iOS pods:
>
> ```bash theme={"dark"}
> cd ios && pod install && cd ..
> ```

> [tab] Expo (SDK 56)
>
> > [!NOTE]
> >
> > Expo Go is **not** supported. `react-native-keyboard-controller`, `react-native-reanimated@4`, and `react-native-worklets` require a custom native build. Use `expo-dev-client` with EAS builds or `expo prebuild`.
>
> This SDK release targets **Expo SDK 56** (stable).
>
> | Expo SDK | Status | React Native | React | Notes |
> | - | - | - | - | - |
> | **56** | **Recommended** | 0.85.3 | 19.2.3 (Expo SDK 56 pin; satisfies RN `^19.2.3`) | Validated target. New architecture is default. iOS 16.4 minimum. |
> | 55 | Installs, not validated | 0.83.x | 19.2.x | The peer floors reach down to the Expo 55 native-module set, so the packages install, but FlowX validates on 56 only. Move to 56 when you can. |
> | ≤54 | Not supported | - | - | Below the declared peer floors (React Native 0.83, React 19.2). |
>
> Align the project to Expo SDK 56:
>
> ```bash theme={"dark"}
> npx expo install expo --fix
> ```
>
> `--fix` aligns `react`, `react-native`, `react-native-reanimated`, `react-native-worklets`, `react-native-safe-area-context`, `react-native-screens`, and other Expo-tracked peers to the versions validated for the installed Expo SDK. Re-run after every Expo bump.
>
> Install the FlowX SDK and peers with `npx expo install` (it picks Expo-validated versions and warns on incompatibilities; use it instead of `npm install`):
>
> ```bash theme={"dark"}
> npx expo install \
>   @flowx/react-native-sdk@<version> \
>   @flowx/react-native-ui-toolkit@<version> \
>   @flowx/react-native-theme@<version> \
>   @flowx/core-sdk@<version> \
>   @flowx/core-theme@<version> \
>   react-dom \
>   @react-native-async-storage/async-storage \
>   react-native-screens \
>   react-native-safe-area-context \
>   react-native-svg \
>   react-native-enriched-markdown \
>   react-native-pdf-renderer \
>   react-native-blob-util \
>   react-native-keyboard-controller \
>   react-native-reanimated \
>   react-native-worklets \
>   react-native-image-picker \
>   @react-native-documents/picker \
>   @react-native-community/datetimepicker \
>   @react-native-community/slider \
>   @react-native-segmented-control/segmented-control \
>   expo-dev-client
> ```
>
> > [!WARNING]
> >
> > Replace `<version>` with the correct version corresponding to your platform version.
> >
> > To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.
>
> `react`, `react-native`, `expo`, and Expo built-ins are already in a fresh Expo project - don't reinstall them. They are pinned by Expo SDK 56's compatibility matrix; let `npx expo install --fix` resolve drift instead of pinning manually.
>
> ### Expo SDK 56 reference versions
>
> These are the versions Expo SDK 56 validates. Use `npx expo install <pkg>` to install at the right pin; do not pin manually unless you must. Packages Expo does not curate show the range the FlowX packages accept.
>
> | Package | Expo SDK 56 expected |
> | - | - |
> | `expo` | `~56.0.19` |
> | `expo-dev-client` | `~56.0.24` |
> | `expo-splash-screen` | `~56.0.14` |
> | `expo-status-bar` | `~56.0.4` |
> | `babel-preset-expo` | `~56.0.19` |
> | `@expo/cli` | `^56.1.23` (ships as a dependency of `expo`) |
> | `react` | `19.2.3` (Expo SDK 56 pin; satisfies `react-native@0.85.3` peer `^19.2.3`) |
> | `react-dom` | `19.2.3` |
> | `react-native` | `0.85.3` |
> | `react-native-reanimated` | `4.3.1` |
> | `react-native-worklets` | `0.8.3` |
> | `react-native-safe-area-context` | `~5.7.0` |
> | `react-native-screens` | `~4.26.0` |
> | `react-native-svg` | `15.15.4` |
> | `react-native-enriched-markdown` | `^0.7.4` |
> | `react-native-pdf-renderer` | `^2.3.0` |
> | `react-native-blob-util` | `^0.24.9` |
> | `react-native-keyboard-controller` | `1.21.6` |
> | `react-native-image-picker` | `^8.2.1` |
> | `@react-native-async-storage/async-storage` | `2.2.0` |
> | `@react-native-community/datetimepicker` | `9.1.0` |
> | `@react-native-community/slider` | `5.2.0` |
> | `@react-native-segmented-control/segmented-control` | `2.5.7` |
> | `@react-native-documents/picker` | `^12.0.1` |
>
> Generate native projects if your Expo project does not yet have `ios/` and `android/`:
>
> ```bash theme={"dark"}
> npx expo prebuild --clean
> ```
>
> Then install iOS pods:
>
> ```bash theme={"dark"}
> cd ios && pod install && cd ..
> ```
>
> `pod install` is also run automatically by `npx expo run:ios` on first launch.
>
> ### `app.json` plugins
>
> Most listed native modules autolink without an Expo config plugin. The one to register:
>
> ```json theme={"dark"}
> {
>   "expo": {
>     "plugins": [
>       "expo-dev-client"
>     ]
>   }
> }
> ```
>
> `react-native-keyboard-controller`, `react-native-reanimated`, and `react-native-worklets` need no config plugin - the Babel plugin handles reanimated and worklets. The `@flowx/react-native-ui-toolkit` plugin is covered in the Android Material 3 section below.
>
> ### Local build (no EAS)
>
> For development on your own machine without EAS:
>
> ```bash theme={"dark"}
> npx expo run:ios       # builds + runs on iOS simulator or device
> npx expo run:android   # builds + runs on Android emulator or device
> ```
>
> First invocation runs `expo prebuild` if `ios/` or `android/` are absent, then builds via Xcode / Gradle. Requires local Xcode (iOS) and Android SDK / JDK (Android).
>
> Useful flags:
>
> ```bash theme={"dark"}
> npx expo run:ios --device                 # pick a connected physical device
> npx expo run:ios --configuration Release  # release build
> npx expo run:android --variant release    # release build
> npx expo run:android --device <id>        # pick device
> ```
>
> After the first install, start Metro separately with the dev client:
>
> ```bash theme={"dark"}
> npx expo start --dev-client
> ```
>
> The installed app on the simulator or device connects to Metro automatically.
>
> ### EAS Build
>
> Add a development profile to `eas.json` with `developmentClient: true` so the artifact ships with the dev client:
>
> ```json theme={"dark"}
> {
>   "build": {
>     "development": {
>       "developmentClient": true,
>       "distribution": "internal"
>     }
>   }
> }
> ```
>
> Then build:
>
> ```bash theme={"dark"}
> eas build --profile development --platform ios
> eas build --profile development --platform android
> ```
>
> Install the resulting artifact on device. Run `npx expo start --dev-client` to connect Metro.
>
> ### Metro config (monorepo)
>
> The default Expo Metro config works in standard projects. For monorepos with symlinked workspaces, enable symlink resolution:
>
> ```js theme={"dark"}
> // metro.config.js
> const { getDefaultConfig } = require('expo/metro-config');
> const config = getDefaultConfig(__dirname);
> config.resolver.unstable_enableSymlinks = true;
> module.exports = config;
> ```

> [!WARNING]
>
> Some peer dependencies require additional setup beyond `npm install`: Babel plugins, Expo config plugins, native project edits (Podfile, `styles.xml`, `AndroidManifest.xml`), or app-root providers. Check each library's install guide and apply its setup steps. Examples: `react-native-worklets` needs a Babel plugin (see below), `@flowx/react-native-ui-toolkit` ships an Expo config plugin for the Android Material 3 date picker (see below), and `react-native-keyboard-controller` / `react-native-screens` / `react-native-safe-area-context` rely on autolinking plus the providers shown later in this page.

### Babel plugin

`react-native-worklets/plugin` **must be the last plugin** in your Babel config.

> [tab] Expo
>
> No manual config needed. `babel-preset-expo` (SDK 54+) auto-adds the worklets plugin when `react-native-worklets` is in `node_modules`.
>
> ```js theme={"dark"}
> // babel.config.js
> module.exports = function (api) {
>   api.cache(true);
>   return {
>     presets: ['babel-preset-expo'],
>   };
> };
> ```

> [tab] Bare RN CLI
>
> ```js theme={"dark"}
> // babel.config.js
> module.exports = {
>   presets: ['module:@react-native/babel-preset'],
>   plugins: [
>     'react-native-worklets/plugin',
>   ],
> };
> ```

### Android Material 3 date picker (opt-in)

`FlxDatePicker` on Android renders the legacy AppCompat calendar by default. To use the Material 3 picker, the host app's `AppTheme` must inherit from a Material 3 parent **and** the toolkit runtime flag `material3` must be `true`. With the flag off, the legacy calendar renders and the theme change is irrelevant.

> [tab] Expo (managed / prebuild)
>
> Register the `@flowx/react-native-ui-toolkit` config plugin. It rewrites `AppTheme` to a Material 3 parent and injects `extra.flxUiToolkit.material3 = true` into the app config, so no JS opt-in is needed:
>
> ```json theme={"dark"}
> {
>   "expo": {
>     "plugins": [
>       "@flowx/react-native-ui-toolkit"
>     ]
>   }
> }
> ```
>
> Then run `npx expo prebuild --clean --platform android`.
>
> > [!NOTE]
> >
> > The toolkit reads the injected `extra.flxUiToolkit.material3` value at runtime through `expo-constants`, which is already present in every Expo project. No JS opt-in call is needed.

> [tab] Bare React Native CLI
>
> Two steps.
>
> **Step 1.** Edit `android/app/src/main/res/values/styles.xml`:
>
> ```xml theme={"dark"}
> <!-- Before -->
> <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
>   <!-- ... -->
> </style>
>
> <!-- After -->
> <style name="AppTheme" parent="Theme.Material3.DayNight.NoActionBar">
>   <!-- ... -->
> </style>
> ```
>
> **Step 2.** Opt in from JS. Pick one:
>
> Option A. `FlxThemeProvider` prop:
>
> ```tsx theme={"dark"}
> import { FlxThemeProvider } from '@flowx/react-native-ui-toolkit'
>
> export default function App() {
>   return (
>     <FlxThemeProvider material3>
>       {/* ... */}
>     </FlxThemeProvider>
>   )
> }
> ```
>
> Option B. Explicit call at app bootstrap (top of `index.js`):
>
> ```ts theme={"dark"}
> import { configureFlxUiToolkit } from '@flowx/react-native-ui-toolkit'
>
> configureFlxUiToolkit({ material3: true })
> ```

> [!NOTE]
>
> No Gradle changes required. `com.google.android.material:material` is already on the classpath via `androidx.appcompat`. Skip both steps and `FlxDatePicker` keeps rendering the legacy calendar with no crash.

## App-root providers

The renderer expects safe-area and keyboard providers above it in the tree:

```tsx theme={"dark"}
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { KeyboardProvider } from 'react-native-keyboard-controller'

export default function App() {
  return (
    <SafeAreaProvider>
      <KeyboardProvider>
        {/* FlowX process view goes here */}
      </KeyboardProvider>
    </SafeAreaProvider>
  )
}
```

> [!NOTE]
>
> The SDK mounts its own `NavigationContainer` internally, wrapped in `NavigationIndependentTree`. A host `NavigationContainer` is **not** required. If your app already uses `@react-navigation/native`, keep its `NavigationContainer` at the root. The SDK's internal navigator stays isolated from it.

## Authorization

> [!NOTE]
>
> The client app implements the authorization flow (using the **OpenID Connect** standard). The SDK expects a bearer token to be set via `FlowX.setAccessToken(token)` before starting a process.

```ts theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk'

FlowX.setAccessToken(accessToken)
```

Call `setAccessToken` again whenever the token is refreshed.

## Configuring the SDK

`FlowX.configure(cfg)` sets global SDK config. Call it once at app bootstrap, before starting any process.

```ts theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk'

FlowX.configure({
  baseURL: 'https://yourDomain.dev',
  processApiPath: 'onboarding',
  organizationId: '10000001-0001-0001-8001-100000000001',
  language: 'en',
  locale: 'en-US',
  staticAssetsPath: 'https://yourDomain.dev/static',
  isDraft: false,
})
```

### `FlxConfig` parameters

| Name | Description | Type | Mandatory | Default |
| - | - | - | - | - |
| `baseURL` | Base API URL | `string` | true | - |
| `processApiPath` | Process subpath | `string` | true | - |
| `organizationId` | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment). | `string` | true | - |
| `language` | Language used to localize enumerations | `string` | false | - |
| `locale` | Locale used to format dates, currency, numbers | `string` | false | - |
| `staticAssetsPath` | Base path for static resources (icons, media). The SDK logs a warning if not set. | `string` | false | - |
| `themeId` | Theme identifier (reserved, not consumed by the RN renderer yet) | `string` | false | - |
| `isDraft` | Start the process in draft state | `boolean` | false | `false` |
| `components` | Self-managed custom components to register, keyed by component identifier. See [Custom components](#custom-components). | `Record<string, ComponentType>` | false | - |
| `validators` | Host-supplied named field validators, keyed by the validator name used in the process. See [Custom validators](#custom-validators). | `Record<string, ValidatorFn>` | false | - |
| `cacheDocuments` | Cache downloaded document files on disk so re-opening the same document skips the download. See [Document caching](#document-caching). | `boolean` | false | `true` |
| `updateStateEnabled` | Re-sync the process state when the app returns from background to foreground. See [Foreground state sync](#foreground-state-sync). | `boolean` | false | `true` |
| `customHeaders` | Extra HTTP headers sent on every network request the SDK makes. See [Custom headers](#custom-headers). | `Record<string, string>` | false | - |
| `requestInterceptors` | Axios request interceptors applied to the SDK's REST calls. See [Custom interceptors](#custom-interceptors). | `HttpRequestInterceptor[]` | false | - |
| `responseInterceptors` | Axios response interceptors applied to the SDK's REST calls. See [Custom interceptors](#custom-interceptors). | `HttpResponseInterceptor[]` | false | - |

## Starting a process

`FlowX.startProcess(opts)` starts a new process instance and returns a `FlxProcessHandle`. The handle exposes a `ProcessView` component that you mount inside a screen.

```tsx theme={"dark"}
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'
import { useEffect, useState } from 'react'

export function OnboardingScreen() {
  const [handle, setHandle] = useState<FlxProcessHandle | null>(null)

  useEffect(() => {
    let active = true
    let pending: FlxProcessHandle | null = null

    FlowX.startProcess({
      workspaceId: '8f52744-8403-4e8d-...',
      projectId: '111111-222222-333333-44444',
      processName: 'client_identification',
      params: { firstName: 'John', lastName: 'Smith' },
    }).then((h) => {
      if (!active) {
        h.dispose()
        return
      }
      pending = h
      setHandle(h)
    })

    return () => {
      active = false
      pending?.dispose()
    }
  }, [])

  if (!handle) return null
  const { ProcessView } = handle
  return <ProcessView />
}
```

### `StartProcessOptions`

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `workspaceId` | Workspace identifier | `string` | true | `'8f52744-8403-4e8d-...'` |
| `projectId` | FlowX Project UUID. Get it from **FlowX Dashboard → Projects → copy UUID from the project actions popover**. | `string` | true | `'111111-222222-...'` |
| `appVersionId` | Pin to a specific app version | `string` | false | - |
| `processName` | Identifies the process to start | `string` | true | `'client_identification'` |
| `params` | Data passed when starting the process | `Record<string, unknown>` | false | `{ firstName: 'John' }` |
| `resourceId` | Resource identifier | `string` | false | - |
| `buildId` | Pinned build identifier | `string` | false | - |
| `isModal` | Render the process as a modal screen | `boolean` | false | `false` |
| `onClose` | Called when the process view is closed | `() => void` | false | - |
| `onProcessStarted` | Called when the main process instance is started. Receives the new `processInstanceUuid`. | `(processInstanceUuid: string) => void` | false | - |

### Getting the process identifier

Open the FlowX Designer, navigate to the process, and copy the process name from the breadcrumbs. Use this value as `processName`.

## The process handle

`startProcess` resolves to a `FlxProcessHandle`:

```typescript theme={"dark"}
interface FlxProcessHandle {
  ProcessView: ComponentType
  dispose(): void
}
```

| Member | Description |
| - | - |
| `ProcessView` | React component that renders the process screens. Mount it inside a screen in your navigation tree. |
| `dispose()` | Tears down the running process and resets SDK stores. Call when the screen unmounts. |

> [!TIP]
>
> To capture the running instance UUID, pass an `onProcessStarted` callback to `startProcess`; it receives the new `processInstanceUuid`. The handle itself does not expose it.

> [!WARNING]
>
> Always call `handle.dispose()` when the host screen unmounts. Skipping it leaks SDK store state into the next process.

## Resuming a process

`FlowX.continueProcess(opts)` resumes an existing process instance instead of starting a new one. Pass the `processInstanceUuid` of the instance you want to reattach to. Like `startProcess`, it resolves to a `FlxProcessHandle` you mount through its `ProcessView`.

```tsx theme={"dark"}
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'
import { useEffect, useState } from 'react'

export function ResumeScreen({ processInstanceUuid }: { processInstanceUuid: string }) {
  const [handle, setHandle] = useState<FlxProcessHandle | null>(null)

  useEffect(() => {
    let active = true
    let pending: FlxProcessHandle | null = null

    FlowX.continueProcess({
      processInstanceUuid,
    }).then((h) => {
      if (!active) {
        h.dispose()
        return
      }
      pending = h
      setHandle(h)
    })

    return () => {
      active = false
      pending?.dispose()
    }
  }, [processInstanceUuid])

  if (!handle) return null
  const { ProcessView } = handle
  return <ProcessView />
}
```

### `ContinueProcessOptions`

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `processInstanceUuid` | UUID of the process instance to resume | `string` | true | `'8f52744-8403-4e8d-...'` |
| `isModal` | Render the process as a modal screen | `boolean` | false | `false` |
| `onClose` | Called when the process view is closed | `() => void` | false | - |

> [!NOTE]
>
> `continueProcess` reattaches to an already-started instance, so it takes no `processName`, `params`, or `onProcessStarted`. Those apply only when starting a new process. Configure the SDK with `FlowX.configure(...)` and set the access token before calling it, exactly as for `startProcess`.

## Starting a UI Flow

UI Flows are lightweight, screen-driven flows defined in the FlowX Designer. They run client-side on top of a data model, without requiring a BPMN process instance on the engine.

> [!WARNING]
>
> Prior starting a UI Flow, make sure the [authorization](#authorization) and the [SDK configuration](#configuring-the-sdk) were correctly set up.

`FlowX.startUiFlow(opts)` starts a UI Flow and returns a `FlxUiFlowHandle`. The handle exposes a `UiFlowView` component that you mount inside a screen.

```tsx theme={"dark"}
import { FlowX, type FlxUiFlowHandle } from '@flowx/react-native-sdk'
import { useEffect, useState } from 'react'

export function CustomerPortalScreen() {
  const [handle, setHandle] = useState<FlxUiFlowHandle | null>(null)

  useEffect(() => {
    let active = true
    let pending: FlxUiFlowHandle | null = null

    FlowX.startUiFlow({
      workspaceId: '8f52744-8403-4e8d-...',
      projectId: '111111-222222-333333-44444',
      uiFlowName: 'customer_portal',
      params: { firstName: 'John' },
    }).then((h) => {
      if (!active) {
        h.dispose()
        return
      }
      pending = h
      setHandle(h)
    })

    return () => {
      active = false
      pending?.dispose()
    }
  }, [])

  if (!handle) return null
  const { UiFlowView } = handle
  return <UiFlowView />
}
```

### `StartUiFlowOptions`

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `workspaceId` | Workspace identifier | `string` | true | `'8f52744-8403-4e8d-...'` |
| `projectId` | FlowX Project UUID. Get it from **FlowX Dashboard → Projects → copy UUID from the project actions popover**. | `string` | true | `'111111-222222-...'` |
| `uiFlowName` | Identifies the UI Flow to start | `string` | true | `'customer_portal'` |
| `params` | Data passed when starting the UI Flow | `Record<string, unknown>` | false | `{ firstName: 'John' }` |
| `isModal` | Render the UI Flow as a modal screen. When set together with `onClose`, a close button is displayed on each screen. | `boolean` | false | `false` |
| `onClose` | Called when the UI Flow view is closed. Receives the `uiFlowName` passed in. | `(uiFlowName?: string) => void` | false | - |

### Getting the UI Flow name

Open the FlowX Designer and navigate to **UI Flows**. The flow name displayed in the list is the value to pass as `uiFlowName`.

## The UI Flow handle

`startUiFlow` resolves to a `FlxUiFlowHandle`:

```typescript theme={"dark"}
interface FlxUiFlowHandle {
  UiFlowView: ComponentType
  dispose(): void
}
```

| Member | Description |
| - | - |
| `UiFlowView` | React component that renders the UI Flow screens. Mount it inside a screen in your navigation tree. |
| `dispose()` | Tears down the running UI Flow and resets SDK stores. Call when the screen unmounts. |

> [!WARNING]
>
> Always call `handle.dispose()` when the host screen unmounts. Skipping it leaks SDK store state into the next session.

## Custom components

Register host-authored **custom components** through the `components` field of `FlowX.configure(...)`. Each key is the component identifier defined in the FlowX process; the value is the React Native component that renders it. The registration is read when the process view mounts, so configure the SDK before starting or continuing a process.

```ts theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk'
import { customComponents } from './customComponents'

FlowX.configure({
  baseURL: 'https://yourDomain.dev',
  processApiPath: 'onboarding',
  organizationId: '10000001-0001-0001-8001-100000000001',
  components: customComponents,
})
```

> [!WARNING]
>
> The keys in the `components` object **MUST** match the custom component identifiers defined in the FlowX process.

> [!NOTE]
>
> React Native supports **self-managed** custom components only: components you author in your app and register by identifier. **Bundled** custom components (source compiled from the backend at runtime) are browser-only; on React Native they are skipped and a warning is logged in development. Re-author any bundled component as a self-managed one.

### Component contract

Each custom component receives the same contract as the React SDK:

```typescript theme={"dark"}
type FlxCustomComponentProps = {
  input: FlxCustomComponentData
  registerValidation: (fn: () => boolean | Promise<boolean>) => void
  saveData: (fn: () => Record<string, unknown>) => void
  isSubmitted: boolean
}

interface FlxCustomComponentData {
  data: Record<string, any>                                        // process data mapped via inputKeys
  actions: ProcessAction[]                                         // metadata for each bound action
  actionsFn: Record<string, (params?: Record<string, unknown> | FormData) => Promise<void>>  // trigger a process action; resolves when it completes
}
```

| Prop | Type | Description |
| - | - | - |
| `input` | `FlxCustomComponentData` | Process data (`input.data`) and bound actions (`input.actions`, `input.actionsFn`). |
| `registerValidation` | `(fn: () => boolean \| Promise<boolean>) => void` | Register a validation function. The SDK calls it when the user submits the process step. Return `true` to pass, `false` to block. |
| `saveData` | `(fn: () => Record<string, unknown>) => void` | Register a data extractor. The SDK calls it on submit to collect values to write back to the process model. |
| `isSubmitted` | `boolean` | `true` after the first submit attempt - use to show validation errors. |

> [!TIP]
>
> Process data mapped through `inputKeys` is available on `input.data`. Process actions are available on `input.actionsFn`, keyed by action name; calling one triggers the process action and returns a `Promise` that resolves when it completes.

### Example

```tsx theme={"dark"}
import { ComponentType } from 'react'
import { View } from 'react-native'
import { type FlxCustomComponentProps } from '@flowx/react-native-sdk'
import { FlxButton, FlxText } from '@flowx/react-native-ui-toolkit'

const ClientDetailsForm = ({ input }: FlxCustomComponentProps) => (
  <View>
    <FlxText variant="p2">First name: {input?.data?.firstName}</FlxText>
    <FlxButton onPress={() => input?.actionsFn?.submitClientDetails?.({ firstName: 'Jane' })}>
      Save
    </FlxButton>
  </View>
)

export const customComponents: Record<string, ComponentType<FlxCustomComponentProps>> = {
  ClientDetailsForm,
}
```

> [!WARNING]
>
> Make sure any action names you call through `input.actionsFn` match the process action names bound to the component in the FlowX Designer.

## Custom validators

Define **custom validators** on your form fields in the FlowX Designer, then pass their implementations through the `validators` field of `FlowX.configure(...)`. The SDK honors the error messages configured on each field in the process.

Each key in the `validators` object is the validator name referenced in the Designer; the value is a factory that receives the validator's configured params and returns the predicate the SDK runs against the field value. Return `true` to pass or `false` to fail. When it fails, the message configured on that validator in the Designer is shown.

```typescript theme={"dark"}
type ValidatorFn = (...params: string[]) => (value: unknown) => boolean | Promise<boolean>
```

> [!WARNING]
>
> The keys in the `validators` object **MUST** match the custom validator names defined in the FlowX process. If a field references a validator name that is not registered, the SDK logs `Custom validator <name> not found` and skips it.

### Example

```ts theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk'

const validators = {
  // No params: the field must equal a fixed value.
  mustBe45: () => (value) => value === '4.5',

  // Params come from the validator config in the Designer.
  minLength: (min: string) => (value) => String(value ?? '').length >= Number(min),
}

FlowX.configure({
  baseURL: 'https://yourDomain.dev',
  processApiPath: 'onboarding',
  organizationId: '10000001-0001-0001-8001-100000000001',
  validators,
})
```

## Full example

```tsx theme={"dark"}
import { useEffect, useState } from 'react'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { KeyboardProvider } from 'react-native-keyboard-controller'
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'

FlowX.configure({
  baseURL: 'https://yourDomain.dev',
  processApiPath: 'onboarding',
  organizationId: '10000001-0001-0001-8001-100000000001',
  language: 'en',
  locale: 'en-US',
  staticAssetsPath: 'https://yourDomain.dev/static',
  validators: {
    mustBe45: () => (value) => value === '4.5',
    minLength: (min: string) => (value) => String(value ?? '').length >= Number(min),
  },
})

function OnboardingScreen({ authToken }: { authToken: string }) {
  const [handle, setHandle] = useState<FlxProcessHandle | null>(null)

  useEffect(() => {
    FlowX.setAccessToken(authToken)

    let active = true
    let pending: FlxProcessHandle | null = null

    FlowX.startProcess({
      workspaceId: '8f52744-8403-4e8d-...',
      projectId: '111111-222222-333333-44444',
      processName: 'client_identification',
      params: { firstName: 'John' },
    }).then((h) => {
      if (!active) {
        h.dispose()
        return
      }
      pending = h
      setHandle(h)
    })

    return () => {
      active = false
      pending?.dispose()
    }
  }, [authToken])

  if (!handle) return null
  const { ProcessView } = handle
  return <ProcessView />
}

export default function App({ authToken }: { authToken: string }) {
  return (
    <SafeAreaProvider>
      <KeyboardProvider>
        <OnboardingScreen authToken={authToken} />
      </KeyboardProvider>
    </SafeAreaProvider>
  )
}
```

## Custom loader

The SDK provides a mechanism for container applications to customize the loader UI displayed during process execution. This allows you to replace the default FlowX loader with your own custom implementation based on different loading scenarios.

### Configuration

To configure custom loaders, pass them through the `customLoader` prop of the `<FlxProcessRenderer />` component:

```tsx theme={"dark"}
import { ActivityIndicator, StyleSheet, Text, View } from 'react-native';
import { FlxProcessRenderer } from '@flowx/react-native-sdk';

// Define your custom loader components
const StartProcessLoader = () => (
  <View style={styles.scrim}>
    <View style={styles.card}>
      <ActivityIndicator size="large" color="#ffffff" />
      <Text style={styles.label}>Starting process...</Text>
    </View>
  </View>
);

const SpecificActionLoader = () => (
  <View style={styles.scrim}>
    <View style={styles.card}>
      <ActivityIndicator size="large" color="#ffffff" />
      <Text style={styles.label}>Executing specific action...</Text>
    </View>
  </View>
);

const styles = StyleSheet.create({
  // The SDK renders your loader full-screen with no scrim or card of its own,
  // so the loader paints its own dim scrim. Use absolute fill: the SDK centers
  // the node, so a flex child would collapse to its content size instead of
  // covering the screen.
  scrim: {
    ...StyleSheet.absoluteFillObject,
    alignItems: 'center',
    justifyContent: 'center',
    backgroundColor: 'rgba(0, 0, 0, 0.25)',
  },
  card: {
    minHeight: 100,
    padding: 24,
    borderRadius: 32,
    alignItems: 'center',
    justifyContent: 'center',
    gap: 16,
    backgroundColor: '#1b1b3a',
  },
  label: {
    color: '#ffffff',
  },
});

// Register the custom loaders in your component
export function MyFlxContainer() {
  return (
    <FlxProcessRenderer
      {...otherProps}
      customLoader={{
        startProcess: <StartProcessLoader />,
        // reloadProcess: <ReloadProcessLoader />,
        // defaultAction: <DefaultActionLoader />,
        // defaultUpload: <DefaultUploadLoader />,
        actions: {
          action1: <SpecificActionLoader />,
          // action2: <SaveDataLoader />,
        },
      }}
    />
  );
}
```

If you drive the SDK through the `FlowX` config (`FlowX.startProcess()` / `FlowX.continueProcess()`) instead of rendering `<FlxProcessRenderer />` yourself, pass the same object through `FlowX.configure()`:

```tsx theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk';

FlowX.configure({
  // ...other configuration
  customLoader: {
    startProcess: <StartProcessLoader />,
    actions: {
      action1: <SpecificActionLoader />,
    },
  },
});
```

### API specification

The `customLoader` prop accepts an object of type `FlxCustomLoader`:

```typescript theme={"dark"}
type FlxCustomLoader = {
  actions?: Record<string, ReactNode>
  startProcess?: ReactNode
  reloadProcess?: ReactNode
  defaultAction?: ReactNode
  defaultUpload?: ReactNode
}
```

#### Loader types

* **`startProcess`** - Displayed when starting or resuming a process
* **`reloadProcess`** - Displayed when reloading a process
* **`defaultAction`** - Default loader for actions when `loaderType` is `'action'`. Used when no specific action loader is found in the `actions` record
* **`defaultUpload`** - Default loader for file uploads when `loaderType` is `'upload'`
* **`actions`** - Record mapping specific action identifiers to custom loaders. When an action is executed, the SDK will first check for a matching entry in this record before falling back to `defaultAction`

### Rendering behavior

Custom loaders on React Native differ from the web SDK in a few important ways:

* **The host owns every pixel.** Your loader node is rendered full-screen with no SDK scrim, card, or spinner behind it. If you want a dimmed backdrop or a centered card, paint them yourself (see the `scrim` style in the example above).
* **Size your root with absolute fill.** The SDK centers your node inside the overlay, so a plain `flex: 1` root collapses to its content size. Use `StyleSheet.absoluteFillObject` on the outermost view to cover the whole screen.
* **The loader lives in a native modal.** While visible it blocks all touch input, renders above native iOS page-sheet modals and Android dialogs, and swallows the Android hardware back button — the user cannot dismiss it.
* **Android debounces the loader.** On Android the loader appears only after \~250 ms, so fast responses never flash a loader; on iOS it appears immediately.
* **Theming gate.** Until the SDK finishes loading its theme resources (right after startup), an opaque placeholder is shown instead of any loader — default or custom — to avoid an unthemed flash.

### Fallback behavior

> [!NOTE]
>
> If no custom loader is provided for a specific type, the SDK will automatically fall back to the built-in FlowX loader, themed with the active FlowX theme. This ensures your app continues to function even with partial custom loader configuration.

> [!TIP]
>
> You can use any React Native components — including Reanimated animations, Lottie views, or your own design-system components — to create rich loading experiences that match your app's design.

## Public API methods

The SDK exposes a set of imperative helpers for reading CMS resources — enumerations, substitution tags, and media library items — from your own code, for example inside a custom component. Import them from `@flowx/core-sdk`:

```tsx theme={"dark"}
import { getEnumeration, getTag, getMediaItemURL } from '@flowx/core-sdk';
```

> [!NOTE]
>
> These methods read the configuration of the active process session (API URL, language, project and build identifiers), so they can only be called after a process has been started — for example from a custom component rendered by the SDK. Results are resolved in the language the SDK was configured with and are cached for the duration of the session.

### getEnumeration

Fetches the values of an enumeration by name.

```typescript theme={"dark"}
function getEnumeration(name: string, parentName?: string): Promise<NomenclatorValue[]>
```

* **`name`** - The name of the enumeration to fetch
* **`parentName`** - Optional name of the parent enumeration, used for hierarchical (parent–child) enumerations

Returns the enumeration values sorted by their configured order. Each value contains the localized display text in `label` and the enumeration code in `id` / `value`; for hierarchical enumerations, `nomenclatorId` holds the name of the child enumeration linked to that value.

```tsx theme={"dark"}
const countries = await getEnumeration('countries');
// [{ id: 'AT', value: 'AT', label: 'Austria', ... }, { id: 'RO', value: 'RO', label: 'Romania', ... }]
```

### getTag

Resolves a substitution tag — a localized UI string managed in the CMS — by its key.

```typescript theme={"dark"}
function getTag(tag: string): Promise<string | undefined>
```

* **`tag`** - The substitution tag key, with or without the `@@` localization prefix

Returns the tag's value in the current SDK language, or `undefined` if the key does not exist.

```tsx theme={"dark"}
const clearLabel = await getTag('@@sys_clear');
// The prefix is optional — this resolves the same tag:
const sameLabel = await getTag('sys_clear');
```

### getMediaItemURL

Resolves the download URL of a media library item by its key.

```typescript theme={"dark"}
function getMediaItemURL(mediaItemId: string): Promise<string | undefined>
```

* **`mediaItemId`** - The media item key, as defined in the project's media library

Returns the item's URL, or `undefined` if no media item matches the key. Both the bare media item key and the fully qualified key (prefixed with the owning application's UUID) are accepted.

```tsx theme={"dark"}
import { Image } from 'react-native';

const logoUrl = await getMediaItemURL('company_logo');

// e.g. render it:
{logoUrl && <Image source={{ uri: logoUrl }} style={styles.logo} />}
```

## Document caching

Documents downloaded by the SDK (for example when a process screen previews a generated file) are cached on disk, keyed by their URL, so re-renders and app relaunches skip the network round-trip. Caching is enabled by default.

* The URL → file path index is persisted to AsyncStorage; the files themselves live in the OS cache directory, so the operating system may evict them at any time — the SDK simply re-downloads on a cache miss.
* Set `cacheDocuments: false` if your documents can change behind the same URL and must always be fetched fresh.
* The flag can be toggled with a later `configure()` call and applies to document loads performed after the change.
* Mirrors `cacheDocuments` on the iOS SDK and `documentsCacheEnabled` on the Android SDK.

```tsx theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk';

FlowX.configure({
  // ...other configuration
  cacheDocuments: false, // always re-download documents
});
```

## Foreground state sync

When the app returns from background to foreground, the SDK re-fetches the root process status and rebuilds the process UI, catching up on anything that changed while the app was backgrounded. This is enabled by default.

* Set `updateStateEnabled: false` to skip the state catch-up. SSE reconnection is unaffected — the SDK still re-establishes the event stream and continues to receive live updates.
* Unlike `language` / `locale`, this flag also applies to the **live** session: it is read on each background → foreground return, so calling `configure()` with a new value takes effect immediately — no process restart needed.
* Mirrors `FXConfig.updateStateEnabled` on the iOS SDK and `Config.updateStateEnabled` on the Android SDK.

```tsx theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk';

FlowX.configure({
  // ...other configuration
  updateStateEnabled: false, // rely on SSE only, skip the foreground re-fetch
});
```

## Custom headers

`customHeaders` lets the container app attach its own HTTP headers — correlation IDs, API-gateway keys, WAF cookies — to the requests the SDK sends to the **FlowX backend**: REST calls, SSE event streams, and document downloads from the FlowX download endpoint. They are sent in both authenticated and anonymous mode.

* Requests to public or external hosts never carry the custom headers: image and icon fetches, native font downloads, and image/document URLs outside the FlowX download endpoint. Those requests carry no SDK auth either — custom headers travel exactly where the SDK's own auth headers travel, so a secret placed here cannot leak to third-party hosts referenced by process content.
* Custom headers are applied before the SDK-managed headers, so on a name collision the SDK wins — you cannot override `Authorization`, `flowx-platform`, and the other headers the SDK manages itself.
* The headers are live-updatable via `configure()`: REST requests and document downloads read them per request; SSE applies them to connections opened after the change.
* Each `configure()` call replaces the whole header set — pass the complete record every time, not just the headers that changed.

```tsx theme={"dark"}
import { FlowX } from '@flowx/react-native-sdk';

FlowX.configure({
  // ...other configuration
  customHeaders: {
    'x-correlation-id': sessionId,
    'x-api-key': gatewayKey,
  },
});

// Later — e.g. after the session rotates. Replaces the record above wholly:
FlowX.configure({
  customHeaders: {
    'x-correlation-id': newSessionId,
    'x-api-key': gatewayKey,
  },
});
```

## Custom interceptors

`requestInterceptors` and `responseInterceptors` attach your own [axios interceptors](https://axios-http.com/docs/interceptors) to the SDK's REST layer — for request/response logging, timing, custom error reporting, or per-request headers.

```typescript theme={"dark"}
type HttpRequestInterceptor = {
  onFulfilled?: (
    config: InternalAxiosRequestConfig
  ) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>
  onRejected?: (error: any) => any
}

type HttpResponseInterceptor = {
  onFulfilled?: (response: AxiosResponse) => AxiosResponse | Promise<AxiosResponse>
  onRejected?: (error: any) => any
}
```

* Interceptors apply to every REST call the SDK makes through its shared axios instance. They do **not** cover SSE event streams or the SDK's non-axios fetches (images, icons, documents, native fonts) — use [Custom headers](#custom-headers) to reach those.
* Like `language` / `locale`, they take effect on the **next** `startProcess()` / `continueProcess()` — interceptors are registered per session and cleared when the session is disposed; the live session keeps the ones it started with.
* Ordering relative to the SDK's built-in interceptors (auth and platform headers, logging, error toasts) is not guaranteed — don't rely on reading or overriding SDK-managed headers such as `Authorization`.
* Mirrors `requestInterceptors` / `responseInterceptors` on the web SDK's `<FlxProcessRenderer />`.

```tsx theme={"dark"}
import {
  FlowX,
  type HttpRequestInterceptor,
  type HttpResponseInterceptor,
} from '@flowx/react-native-sdk';

const requestTagging: HttpRequestInterceptor = {
  onFulfilled: (config) => {
    config.headers['x-request-id'] = generateRequestId();
    return config;
  },
};

const errorReporting: HttpResponseInterceptor = {
  onRejected: (error) => {
    crashReporting.recordError(error);
    return Promise.reject(error);
  },
};

FlowX.configure({
  // ...other configuration
  requestInterceptors: [requestTagging],
  responseInterceptors: [errorReporting],
});
```

## Flowx callbacks and logging

The `FlowX` config exposes hooks for observing what happens inside a process session: analytics events, new processes started by the backend, and a structured log stream. All three are config-level and session-independent: registrations survive `dispose()` and process restarts, so you can register them once at app startup.

### Analytics collector

`FlowX.analyticsCollector()` subscribes to analytics events. An event fires whenever an executed action has `analytics` defined in its params, with the resolved payload:

```typescript theme={"dark"}
type AnalyticsData = {
  type: 'SCREEN' | 'ACTION'
  value: string                                 // the analytics expression from the action params
  screen?: string
  component?: string
  label?: string
  customPayload?: Record<string, unknown> | null // the parsed analyticsCustomPayload
}
```

The method returns an unsubscribe function. Multiple collectors may be registered — each one receives every event.

```tsx theme={"dark"}
import { FlowX, type AnalyticsData } from '@flowx/react-native-sdk';

const unsubscribe = FlowX.analyticsCollector((data: AnalyticsData) => {
  analytics.track(data.value, {
    screen: data.screen,
    component: data.component,
    label: data.label,
    ...data.customPayload,
  });
});

// Stop collecting, e.g. on logout:
unsubscribe();
```

### New process started

Assign a callback to `FlowX.newProcessStarted` to be notified when the backend starts a new process out of the live session: a `START_PROJECT` action, signaled by the `newProcessStarted` SSE event. The callback receives the new process instance UUID.

This is a notification only. The SDK keeps rendering the current process. Showing the new one is up to the host app:

1. Call `dispose()` on the current process handle.
2. Call `FlowX.continueProcess({ processInstanceUuid })` with the UUID the callback received, and mount the new handle's `ProcessView`.

```tsx theme={"dark"}
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'
import { useEffect, useState } from 'react'

export function OnboardingScreen() {
  const [handle, setHandle] = useState<FlxProcessHandle | null>(null)

  useEffect(() => {
    let active = true
    let current: FlxProcessHandle | null = null

    const show = (next: Promise<FlxProcessHandle>) =>
      next.then((h) => {
        if (!active) {
          h.dispose()
          return
        }
        current = h
        setHandle(h)
      })

    // The backend started a new process: drop the current one, continue the new one.
    FlowX.newProcessStarted = (processInstanceUuid) => {
      current?.dispose()
      current = null
      setHandle(null)
      show(FlowX.continueProcess({ processInstanceUuid }))
    }

    show(
      FlowX.startProcess({
        workspaceId: '8f52744-8403-4e8d-...',
        projectId: '111111-222222-333333-44444',
        processName: 'client_identification',
      })
    )

    return () => {
      active = false
      // Single listener: assigning replaces the previous one; clear it with undefined.
      FlowX.newProcessStarted = undefined
      current?.dispose()
    }
  }, [])

  if (!handle) return null
  const { ProcessView } = handle
  return <ProcessView />
}
```

If the callback throws, the SDK logs the error and continues; the exception does not propagate into the SDK's event handling.

### Logging

`FlowX.logSink()` subscribes to the SDK's structured log-event stream — useful for debugging and for feeding your own telemetry. Events cover four categories:

* **`rest`** - API traffic, including the SDK's image, icon, and document fetches
* **`sse`** - SSE connection lifecycle and received events
* **`expression`** - expression evaluations (hide, disabled, computed, conditional, validator, local script)
* **`cms`** - CMS font registration

```typescript theme={"dark"}
type FlxLogEvent = {
  timestamp: string // ISO 8601 with milliseconds, UTC
  category: 'rest' | 'sse' | 'expression' | 'cms'
  type: string      // e.g. 'request' | 'response' | 'error' for the rest category
  payload: Record<string, unknown>
}
```

It accepts a single logger or an array of loggers, plus an optional `categories` filter, and returns an unsubscribe function. Secrets in headers (`Authorization` & co.) are redacted before events are emitted. Pass the exported `formattedLogger` to pretty-print events to the console.

```tsx theme={"dark"}
import { FlowX, formattedLogger } from '@flowx/react-native-sdk';

// Pretty-print every SDK event to the console:
const unsubscribe = FlowX.logSink(formattedLogger);

// Or send only network traffic to your own telemetry:
FlowX.logSink((event) => telemetry.log(event), { categories: ['rest', 'sse'] });
```

## Chat component

To use the `FlxChatRenderer` component, import it from the React Native SDK:

```tsx theme={"dark"}
import { FlxChatRenderer } from '@flowx/react-native-sdk';
```

#### Usage

The chat fills its parent, so give it a flexed container and let your screen own the safe area:

```tsx theme={"dark"}
import { SafeAreaView } from 'react-native-safe-area-context';

<SafeAreaView style={{ flex: 1 }} edges={['top', 'bottom']}>
  <FlxChatRenderer
    apiUrl={baseUrl}
    authToken={accessToken}
    staticAssetsPath={staticAssetsPath}
    language={language}
    locale={locale}
    themeId={themeId}
    organizationId={organizationId}
    projectId={projectId}
    workspaceId={workspaceId}
    source={source}
    chatConfig={chatConfig}
    cache={cache}
  />
</SafeAreaView>
```

Parameters:

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `apiUrl` | Your base API URL | `string` | ✅ | `https://yourDomain.dev` |
| `authToken` | Authorization token | `string` | ✅ | (retrieved from auth provider) |
| `staticAssetsPath` | Path for static resources | `string` | ✅ | (set via environment) |
| `language` | Language used to localize the chat interface | `string` | ✅ | `en` |
| `locale` | Locale setting for date and number formatting | `string` | ✅ | `en-US` |
| `themeId` | Theme identifier for styling | `string` | ✅ | (retrieved dynamically) |
| `organizationId` | Organization ID — fonts resolve under `/cms/api/organizations/{organizationId}/fonts` | `string` | ✅ | (retrieved dynamically) |
| `projectId` | The FlowX project ID | `string` | ✅ | (retrieved dynamically) |
| `workspaceId` | The workspace ID | `string` | ✅ | (retrieved dynamically) |
| `source` | Source object with type and id | `object` | ✅ | `{ type: 'WORKFLOW', id: '...' }` |
| `chatConfig` | Chat configuration object | `object` | ❌ | `{ welcomeMessage: '...', ... }` |
| `cache` | Cache the fetched resources for this build | `boolean` | ❌ | `true` |
| `buildId` | Pinned build identifier | `string` | ❌ | (retrieved dynamically) |
| `voiceInputEnabled` | Offer the microphone in the composer | `boolean` | ❌ | `false` |
| `testID` | Test identifier forwarded to the chat column | `string` | ❌ | `chat-screen` |

#### chatConfig parameters

The `chatConfig` object accepts the following properties:

| Name | Description | Type | Default value |
| - | - | - | - |
| `welcomeMessage` | Message displayed when chat is first opened | `string` | `'Welcome to the chat!'` |
| `thinkingMessage` | Message displayed while waiting for a response | `string` | - |
| `title` | Chat header title | `string` | - |
| `subtitle` | Chat header subtitle | `string` | - |
| `showChatIcon` | Whether to display the header avatar | `boolean` | `true` |
| `showAgentAvatar` | Whether agent replies carry an avatar | `boolean` | `true` |
| `showSeparator` | Whether to show a separator under the header | `boolean` | `true` |
| `hideHeader` | Render the transcript and composer with no header at all | `boolean` | `false` |
| `hideNewConversation` | Hide the new-chat action in the header | `boolean` | `false` |
| `hideHistory` | Hide the conversation-history action in the header | `boolean` | `false` |
| `newChatLabel` | Accessible label for the new chat button | `string` | `'New chat'` |
| `historyTitle` | Title displayed on the chat history panel | `string` | - |
| `inputPlaceholder` | Placeholder text for the message input field | `string` | - |
| `maxInputRows` | Maximum number of rows the input grows to | `number` | `10` |
| `errorMessage` | Message shown when an error occurs | `string` | `'Error message'` |
| `canRegenerate` | Show a regenerate action on failed responses | `boolean` | `true` |
| `regenerateLabel` | Label for the regenerate action | `string` | `'Regenerate'` |
| `suggestedPrompts` | Prompt pills offered before the first message | `{ label: string; prompt: string \| null }[]` | `[]` |
| `suggestedPromptsTitle` | Title shown above the suggested prompts | `string` | - |
| `headerIcon` | Overrides the themed header icon | `content icon` | (from theme) |
| `agentIcon` | Overrides the themed agent avatar | `content icon` | (from theme) |
| `sendIcon` | Overrides the themed send icon | `content icon` | (from theme) |
| `chatAvatar` | Header avatar used when no `headerIcon` resolves | `avatar` | - |

#### Voice input

Voice messages need a recorder engine and a microphone declaration in the **app**, which a library cannot add on its own:

1. Install the optional peer dependencies `react-native-nitro-sound` and `react-native-nitro-modules`. Without them the SDK installs no recorder and the microphone button is not drawn.
2. Add the toolkit's Expo config plugin, which declares `RECORD_AUDIO` on Android and fills `NSMicrophoneUsageDescription` on iOS (your own copy is kept if you already wrote one):

```json theme={"dark"}
{
  "expo": {
    "plugins": ["@flowx/react-native-ui-toolkit/app.plugin.js"]
  }
}
```

Set `voiceInputEnabled={false}` to hide the microphone even where an engine is installed. Voice messages recorded on other clients still play back either way.


# React SDK
Source: https://docs.flowx.ai/5.9/sdks/react-renderer

The React renderer SDK renders UI configured in the FlowX Designer as a standalone React component.

## React project requirements

Your app MUST use SCSS for styling.

> [!TIP]
>
> To install the npm libraries provided by FlowX.AI you will need to obtain access to the private FlowX.AI Nexus registry. Please consult with your project DevOps.

> [!NOTE]
>
> The library requires React **19**, **npm ≥ 11.0.0** and **node ≥ 24.0.0**.

## Installing the library

Use the following command to install the **renderer** library and its required dependencies:

> [!TIP]
>
> Installing `react` and `react-dom` can be skipped if you already have them installed in your project.

```bash theme={"dark"}
npm install \
  react@19 \
  react-dom@19 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your platform version.
>
> To find the right version, navigate to: **Release Notes → Choose your platform version → Deployment guidelines → Component versions**.

## Initial setup

Once installed, `FlxProcessRenderer` will be imported from the `@flowx/react-sdk` package.

### Theming

Component theming is done through the `@flowx/react-theme` library. The theme id is a required input for the renderer SDK component and is used to fetch the theme configuration. The id can be obtained from the admin panel in the themes section.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/2024-04-08%2013.45.10.gif)

### Authorization

> [!NOTE]
>
> It's the responsibility of the client app to implement the authorization flow (using the **OpenID Connect** standard). The renderer SDK will expect the authToken to be passed to the `FlxProcessRenderer` as an input.

```tsx theme={"dark"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
    return <FlxProcessRenderer
        apiUrl={'your API url'}
        authToken={...}
        processName={...}
        processStartData={...}
        workspaceId={...}
        processApiPath={...}
        themeId="12345678-1234-1234-1234-123456789012"
        staticAssetsPath={...}
        locale="en-US"
        language="en"
        projectInfo={{
            projectId: ...
        }}
        organizationId={...}
      />
}
```

The `FlxProcessRenderer` component is required in the app module where the process will be rendered. The component accepts a props where you can pass extra config info, register a **custom component** or **custom validators**.

**Custom components** will be referenced by name when creating the template config for a user task.

**Custom validators** will be referenced by name (`customValidator`) in the template config panel in the validators section of each generated form field.

```tsx theme={"dark"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
    return <FlxProcessRenderer
        apiUrl={'your API url'}
        language={...}
        authToken={...}
        processName={...}
        processStartData={...}
        workspaceId={...}
        processApiPath={...}
        themeId="12345678-1234-1234-1234-123456789012"
        components={{ MyCustomComponentIdentifier: MyCustomComponent }}
        validators={{ customValidator: (...params: string[]) => (v: string) => v === '4.5'}}
        staticAssetsPath={...}
        locale="en-US"
        language="en"
        projectInfo={{
            projectId: ...
        }}
        organizationId={...}
        logSink={console} // example: a log sink (e.g., console, custom logger)
      />
}

```

The entry point of the library is the `<FlxProcessRenderer />` component. A list of accepted inputs is found below:

```tsx theme={"dark"}
<FlxProcessRenderer
    apiUrl={apiUrl}
    language={language}
    authToken={authToken}
    processName={processName}
    processStartData={processStartData}
    workspaceId={workspaceId}
    processApiPath={apiPath}
    themeId={themeId}
    components={customComponents}
    validators={validators}
    staticAssetsPath={assetsPath}
    locale={locale}
    language={language}
    projectInfo={projectInfo}
    organizationId={organizationId}
    logSink={logSink}
    />
```

**Parameters**:

| Name | Description | Type | Mandatory | Default value | Example |
| - | - | - | - | - | - |
| `apiUrl` | Your base url | `string` | true | - | `https://yourDomain.dev` |
| `processApiPath` | Process subpath | `string` | true | - | `onboarding` |
| `authToken` | Authorization token | `string` | true | - | `'eyJhbGciOiJSUzI1NiIsIn....'` |
| `themeId` | Theme id used to style the process. Can be obtained from the themes section in the admin | `string` | true | - | `'123-456-789'` |
| `processName` | Identifies a process | `string` | true | - | `client_identification` |
| `processStartData` | Data required to start the process | `json` | true | - | `{ "firstName": "John", "lastName": "Smith"}` |
| `workspaceId` | Workspace id | `string` | true | - | `'8f52744-8403-4e8d....'` |
| `projectInfo` | Defines which FlowX Project will be run inside the process renderer. Shape: `{ projectId: string, appVersionId?: string }` | `object` | true | - | `{ "projectId": "111111-222222-333333-44444"}` |
| `organizationId` | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade — see [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment). | `string` | true | - | `'10000001-0001-0001-8001-100000000001'` |
| `language` | Language used to localize the enumerations inside the app. | `string` | false | `ro` | - |
| `locale` | Locale used to apply date, currency and number formatting to data model values | `string` | false | `ro-RO` | `"en-US"` |
| `isDraft` | When true, starts the process in draft state | `boolean` | false | `false` | - |
| `legacyHttpVersion` | Use legacy HTTP API version | `boolean` | false | `false` | - |
| `buildId` | Pinned build identifier | `string` | false | - | - |
| `cache` | Enable caching | `boolean` | false | - | - |
| `requestInterceptors` | Axios request interceptors applied to all SDK HTTP calls | `HttpRequestInterceptor[]` | false | - | - |
| `responseInterceptors` | Axios response interceptors applied to all SDK HTTP calls | `HttpResponseInterceptor[]` | false | - | - |
| `onProcessEnded` | Callback fired when the main process reaches a terminal state | `() => void` | false | - | - |
| `onProcessStarted` | Callback fired when the main process instance is started. Receives the new `processInstanceUuid`. | `(processInstanceUuid: string) => void` | false | - | - |
| `customLoader` | Custom loader components for different loading scenarios. | `object` | false | - | `{ startProcess: <LoaderComponent /> }` |
| `logSink` | Sink for log messages generated by the renderer. Can be set to `console` or a custom object implementing `log/info/warn/error` methods. | `object` | false | `undefined` | `console`, `myCustomLogger` |

#### `projectInfo` shape

```typescript theme={"dark"}
projectInfo: {
  projectId: string                    // required
  appVersionId?: string                // pin a specific app version
}
```

#### Interceptor types

```typescript theme={"dark"}
type HttpRequestInterceptor = {
  onFulfilled?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>
  onRejected?: (error: any) => any
}

type HttpResponseInterceptor = {
  onFulfilled?: (response: AxiosResponse) => AxiosResponse | Promise<AxiosResponse>
  onRejected?: (error: any) => any
}
```

### Analytics

> [!NOTE]
>
> The SDK provides a mechanism for collecting analytics events through a unified `CustomEvent` system. These events can be used to track screens and action events.

To use analytics features, make sure you've imported the necessary SDK module:

```ts theme={"dark"}
import {
   ANALYTICS_EVENTS,
   AnalyticsData,
   pushAnalyticsData,
} from '@flowx/core-sdk';
```

#### Emitting analytics events

Analytics events are dispatched using the `pushAnalyticsData(payload: AnalyticsData)` method. The SDK defines two event types:

```ts theme={"dark"}
enum ANALYTICS_EVENTS {
  SCREEN = 'SCREEN',
  ACTION = 'ACTION',
}
```

Each analytics event should be an object of type AnalyticsData:

```ts theme={"dark"}
type AnalyticsData = {
  type: ANALYTICS_EVENTS;
  value: string;
  screen?: string;
  component?: string;
  label?: string;
  customPayload?: object;
}
```

> [!NOTE]
>
> The value property represents the identifier set in the process definition.
>
> For ACTION type events there are some additional properties provided:
>
> * component - The type of component triggering the action
> * label - The label of the component
> * screen - The identifier of the screen containing the component, if set

#### Listening for analytics events

You can subscribe to analytics events using the standard CustomEvent API:

```ts theme={"dark"}
const analyticsListener = (event: CustomEvent<AnalyticsData>) => {
  console.log('Received flowx:analytics event:', event.detail);
}

useEffect(() => {
  document.addEventListener('flowx:analytics', analyticsListener)

  return () => {
    document.removeEventListener('flowx:analytics', analyticsListener)
  }
}, [])
```

> [!TIP]
>
> Ensure that you remove the event listener on component destruction to avoid memory leaks.

#### Custom payload

This allows you to capture and send custom data alongside standard analytics events.

When analytics custom payload is configured in FlowX Designer, the renderer automatically processes variable substitution and includes the resulting data in analytics events.

**1. Receive custom payload configuration**

The renderer receives the analytics configuration as a JSON string with variable placeholders:

```json theme={"dark"}
"analyticsCustomPayload": "{\n \"name\": ${app.input}\n}"
```

**2. Process variable substitution**

The SDK replaces variables with actual values from the process data store:

```json Template theme={"dark"}
{
    "name": "${app.input}",
    "client": "${app.client}",
    "amount": "${app.amount}"
}
```

```json Result theme={"dark"}
{
    "name": "john",
    "client": { "id": "123", "name": "John Doe" },
    "amount": 1500
}
```

**3. Add to analytics event**

The processed payload is included in the analytics event under the `customPayload` property:

```typescript theme={"dark"}
// Analytics event structure with custom payload
{
    type: 'ACTION', // or 'SCREEN'
    info: {
        value: 'Save personal data',
        screen: 'Personal Data',
        component: 'BUTTON',
        label: 'Save',
        customPayload: {
            name: "john",
            client: { id: "123", name: "John Doe" },
            amount: 1500
        }
    }
}
```

## Starting a process

### Prerequisites

* **Process Name**: You need to know the name of the process you want to start. This name is used to identify the process in the system.

* **FlowX Project UUID**: You need the UUID of the FlowX Project that contains the process you want to start. This UUID is used to identify the project in the system.

* **Locale**: You can specify the locale of the process to apply date, currency, and number formatting to data model values.

* **Language**: You can specify the language used to localize the enumerations inside the app.

### Getting the project UUID

The project UUID can be obtained from the FlowX Dashboard. Navigate to the Projects section and select the project you want to start a process in. The UUID can be copied from the project actions popover.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/copy_uuid_application.png)

### Getting the process identifier

Open the FlowX Designer, navigate to the process, and copy the process name from the breadcrumbs. Use this value as `processName`.

### Initializing the process renderer

To start a process, you need to initialize the `FlxProcessRenderer` component in your app. The component accepts various props that define the process to start, the theme to use, and other configuration options.

```tsx theme={"dark"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
    return <FlxProcessRenderer
        {...props}
        locale="en-US"
        language="en"
        processName={processName}
        projectInfo={{ projectId }}
      />
}
```

## Custom components

Custom components receive an `input` prop of type `FlxCustomComponentData` and are registered through the `components` parameter of `<FlxProcessRenderer />`.

> [!WARNING]
>
> The object keys passed in the `components` prop **MUST** match the custom component names defined in the FlowX process.

> [!TIP]
>
> Process data mapped through `inputKeys` is available on `input.data`. The value is whatever lives at the configured path in the process model - it can be an object or a primitive.

> [!TIP]
>
> Process actions are available on `input.actionsFn`, keyed by action name.

```typescript theme={"dark"}
interface FlxCustomComponentData {
  data: any                                                          // value at the configured inputKey path - object or primitive
  actions: ProcessAction[]                                           // metadata for each bound action
  actionsFn: Record<string, (params?: any) => Observable<any>>      // call to trigger a process action; returns an Observable
}
```

Each custom component receives four props:

| Prop | Type | Description |
| - | - | - |
| `input` | `FlxCustomComponentData` | Process data and bound actions |
| `registerValidation` | `(fn: () => boolean \| Promise<boolean>) => void` | Register a validation function. The SDK calls it when the user submits the process step. Return `true` to pass, `false` to block. |
| `saveData` | `(fn: () => Record<string, unknown>) => void` | Register a data extractor. The SDK calls it on submit to collect values to write back to the process model. |
| `isSubmitted` | `boolean` | `true` after the first submit attempt - use to show validation errors. |

```tsx theme={"dark"}
export const MyCustomComponent = ({
  input,
  registerValidation,
  saveData,
  isSubmitted,
}: {
  input: FlxCustomComponentData
  registerValidation: (fn: () => boolean | Promise<boolean>) => void
  saveData: (fn: () => Record<string, unknown>) => void
  isSubmitted: boolean
}) => {
  const { data, actionsFn } = input
  // data - the value mapped via inputKeys; e.g. { firstName: 'John' } or a primitive
  // actionsFn['save_order']() - triggers the 'save_order' process action
}
```

To add a custom component in the template config tree, we need to know its unique identifier and the data it should receive from the process model.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom.png)

The properties that can be configured are as follows:

* **Identifier** - This enables the custom component to be displayed within the component hierarchy and determines the actions available for the component.
* **Input keys** - These are used to specify the pathway to the process data that components will utilize to receive their information.
* [**Event Handlers**](../docs/building-blocks/ui-designer/event-handlers) - actions defined here will be made available to the custom component

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/ui_designer_custom_settings.png#center)

### Prerequisites (before creation)

* **React Knowledge**: You should have a good understanding of React, as custom components are created and imported using React.

* **Development Environment**: Set up a development environment for React development, including Node.js and npm (Node Package Manager).

* **Component Identifier**: You need a unique identifier for your custom component. This identifier is used for referencing the component within the app.

### Creating a custom component

To create a Custom Component in React, follow these steps:

1. Create a new React component.
2. Implement the necessary HTML structure, TypeScript logic, and SCSS styling to define the appearance and behavior of your custom component.

### Importing the component

After creating the Custom Component, you need to import it into your app.

In your `<FlxProcessRenderer />` component, add the following property:

```tsx theme={"dark"}
<FlxProcessRenderer
  {...otherProps}
  components={{ MyCustomComponentIdentifier: MyCustomComponent }}
/>
```

### Using the custom component

Once your Custom Component is declared, you can use it for configuration within your app.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/loader_component.gif)

### Data input and actions

The Custom Component accepts input data from processes and can also include actions extracted from a process. These inputs and actions allow you to configure and interact with the component dynamically.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_input_data.png)

### Extracting data from processes

There are multiple ways to extract data from processes to use within your Custom Component. You can utilize the data provided by the process or map actions from the BPMN process to React actions within your component.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/cst_loader_input.png)

> [!WARNING]
>
> Make sure that the React actions that you declare match the names of the process actions.

### Styling with CSS

To apply CSS classes to UI elements within your Custom Component, you first need to identify the UI element identifiers within your component's HTML structure. Once identified, you can apply defined CSS classes to style these elements as desired.

Example:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/Screenshot%202023-10-10%20at%2012.29.51.png)

### Additional considerations

* **Naming Conventions**: Be consistent with naming conventions for components, identifiers, and actions. Ensure that React action names match the names of process actions.

* **Component Hierarchy**: Understand how the component fits into the overall component hierarchy of your app. This will help determine where the component is displayed and what actions are available for it.

* **Documentation and Testing**: Document your custom component thoroughly for future reference. Additionally, testing is crucial to ensure that the component behaves as expected in various scenarios.

* **Security**: If your custom component interacts with sensitive data or performs critical actions, consider security measures to protect the app from potential vulnerabilities.

* **Integration with FlowX Designer**: Ensure that your custom component integrates with FlowX Designer, as it is part of the app's process modeling capabilities.

## Custom validators

You may also define custom validators in your FlowX processes and pass their implementation through the `validators` prop of the `<FlxProcessRenderer />` component.

The validators are processed through a custom validation layer backed by [Valtio](https://github.com/pmndrs/valtio) state management, taking into account how the error messages are defined in your process.

A validator must have the following type:

```typescript theme={"dark"}
const customValidator = (...params: string[]) => (v: any) => boolean | Promise<boolean>
```

> [!WARNING]
>
> The object keys passed in the `validators` prop **MUST** match the custom validator names defined in the FlowX process.

## Process end handling

The SDK provides a mechanism for container applications to handle process completion events through the `onProcessEnded` callback. This allows you to implement custom logic when a main process reaches an end state, such as redirecting users or triggering cleanup operations.

The `onProcessEnded` callback is triggered when the **main process** (not subprocesses) reaches any terminal state.

> [!NOTE]
>
> Only the main process triggers this callback. Subprocess completions do not trigger the callback to avoid unnecessary interruptions during complex process flows.

### Implementation

To handle process end events, pass a function to the `onProcessEnded` prop of the `<FlxProcessRenderer />` component:

```tsx theme={"dark"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

export function MyFlxContainer() {
  const handleProcessEnd = () => {
    // Your custom logic here
    console.log('Process has ended');
    
    // Example: Redirect to home page
    window.location.href = '/dashboard';
  };

  return (
    <FlxProcessRenderer
      {...otherProps}
      onProcessEnded={handleProcessEnd}
    />
  );
}
```

## Custom loader

The SDK provides a mechanism for container applications to customize the loader UI displayed during process execution. This allows you to replace the default FlowX loader with your own custom implementation based on different loading scenarios.

### Configuration

To configure custom loaders, pass them through the `customLoader` prop of the `<FlxProcessRenderer />` component:

```tsx theme={"dark"}
import { FlxProcessRenderer } from '@flowx/react-sdk';

// Define your custom loader components
const StartProcessLoader = () => (
  <div className="custom-start-loader">
    <div className="spinner" />
    <p>Starting process...</p>
  </div>
);

const SpecificActionLoader = () => (
  <div className="custom-specific-action-loader">
    <div className="spinner" />
    <p>Executing specific action...</p>
  </div>
);

// Register the custom loaders in your component
export function MyFlxContainer() {
  return (
    <FlxProcessRenderer
      {...otherProps}
      customLoader={{
        startProcess: <StartProcessLoader />,
        // reloadProcess: <ReloadProcessLoader />,
        // defaultAction: <DefaultActionLoader />,
        // defaultUpload: <DefaultUploadLoader />,
        actions: {
          action1: <SpecificActionLoader />,
          // action2: <SaveDataLoader />,
        },
      }}
    />
  );
}
```

### API specification

The `customLoader` prop accepts an object of type `CustomLoader`:

```typescript theme={"dark"}
type CustomLoader = {
  actions?: Record<string, ReactNode>
  startProcess?: ReactNode
  reloadProcess?: ReactNode
  defaultAction?: ReactNode
  defaultUpload?: ReactNode
}
```

#### Loader types

* **`startProcess`** - Displayed when starting or resuming a process
* **`reloadProcess`** - Displayed when reloading a process
* **`defaultAction`** - Default loader for actions when `loaderType` is `'action'`. Used when no specific action loader is found in the `actions` record
* **`defaultUpload`** - Default loader for file uploads when `loaderType` is `'upload'`
* **`actions`** - Record mapping specific action identifiers to custom loaders. When an action is executed, the SDK will first check for a matching entry in this record before falling back to `defaultAction`

### Fallback behavior

> [!NOTE]
>
> If no custom loader is provided for a specific type, the SDK will automatically fall back to the built-in FlowX loader. This ensures your app continues to function even with partial custom loader configuration.

> [!TIP]
>
> You can use any React components, including those with animations, styled components, or media assets, to create rich loading experiences that match your app's design system.

## Log Sink

The process and UI flow renderers can stream the SDK's internal activity — REST calls, SSE traffic and expression evaluations — to a callback you provide. Use it to debug a running process in the browser console, feed an in-app inspector, or forward events to your telemetry backend.

Attach it through two props available on both `<FlxProcessRenderer>` and `<FlxUiFlowRenderer>` (and their `FlxProcessRendererPortal` / `FlxUiFlowRendererPortal` variants):

| Prop | Description | Type | Default |
| - | - | - | - |
| `logSink` | Log-event consumer(s). One function or an array — each receives every event. Subscribed when the renderer mounts, unsubscribed when it unmounts | `FlxLogSink \| FlxLogSink[]` | - |
| `logCategories` | Restrict the stream to these categories. Omitted or empty delivers every category | `FlxLogCategory[]` | all |

### Quick start — print everything to the console

The SDK exports a ready-made console logger, `formattedLogger`. Pass it as the sink and every event is printed as a single colour-badged line.

```tsx theme={"dark"}
import { FlxProcessRenderer, formattedLogger } from '@flowx/react-sdk'

export function ProcessPage() {
  return (
    <FlxProcessRenderer
      apiUrl={apiUrl}
      processApiPath={processApiPath}
      authToken={token}
      themeId={themeId}
      processName="onboarding"
      projectInfo={{ projectId }}
      staticAssetsPath={staticAssetsPath}
      organizationId={organizationId}
      logSink={formattedLogger}
    />
  )
}
```

Console output looks like:

```
 FlowX  rest        request POST https://…/api/process/onboarding/start
 FlowX  rest        response POST https://…/api/process/onboarding/start → 200 { … }
 FlowX  sse         connected https://…/api/process/…/events
 FlowX  expression  hide incomeSection → false { … }
 FlowX  sse         data { client: { firstName: 'Ion' } }
```

### Writing your own sink

A sink is any function that receives an `FlxLogEvent`. Pass one function or an array — each one receives every event.

```tsx theme={"dark"}
import { FlxLogEvent, FlxProcessRenderer, formattedLogger } from '@flowx/react-sdk'

import { telemetry } from './telemetry'

const sendToTelemetry = (event: FlxLogEvent) =>
  telemetry.track('flowx_sdk_event', {
    category: event.category,
    type: event.type,
    ...event.payload,
  })

export function ProcessPage() {
  return (
    <FlxProcessRenderer
      {...processProps}
      logSink={[formattedLogger, sendToTelemetry]}
    />
  )
}
```

The renderer always calls the latest `logSink` you passed, so inline arrow functions and non-memoized arrays are fine — they do not cause a resubscription or drop events.

### Filtering by category

Restrict the stream with `logCategories`. Omitting it (or passing an empty array) delivers every category.

```tsx theme={"dark"}
<FlxProcessRenderer
  {...processProps}
  logSink={formattedLogger}
  logCategories={['rest', 'sse']}
/>
```

### Using it with a UI flow

Attach the sink to the **UI flow renderer only**. Any process it opens — fullscreen or embedded through a Process Renderer component — reports on the same stream, so a single sink on `<FlxUiFlowRenderer>` already covers them. Attaching a second sink to an inner process renderer would deliver each event twice.

```tsx theme={"dark"}
import { FlxUiFlowRenderer, formattedLogger } from '@flowx/react-sdk'

export function PortalPage() {
  return (
    <FlxUiFlowRenderer
      apiUrl={apiUrl}
      processApiPath={processApiPath}
      authToken={token}
      themeId={themeId}
      uiFlowName="customer-portal"
      workspaceId={workspaceId}
      appInfo={{ appId: projectId }}
      staticAssetsPath={staticAssetsPath}
      organizationId={organizationId}
      language={language}
      locale={locale}
      logSink={formattedLogger}
      logCategories={['expression']}
    />
  )
}
```

### Console logger options

`formattedLogger` is tuned for a dark devtools console. Build your own variant with `createFormattedLogger`:

```tsx theme={"dark"}
import { createFormattedLogger } from '@flowx/react-sdk'

// Light console palette
const lightLogger = createFormattedLogger({ theme: 'light' })

// Log the raw FlxLogEvent object instead of the one-line summary —
// useful to see exactly what a custom sink would receive
const rawLogger = createFormattedLogger({ raw: true })
```

### What you receive

```ts theme={"dark"}
interface FlxLogEvent {
  timestamp: string // ISO 8601 with milliseconds, UTC
  category: 'rest' | 'sse' | 'expression' | 'cms'
  type: string
  payload: Record<string, unknown>
}
```

| Category | `type` values | Payload |
| - | - | - |
| `rest` | `request`, `response`, `error` | `url`, `method`, `status`, `headers` (request only), `body`, `message` (error only). Covers every call the SDK makes: process start/actions, enumerations, substitution tags, theme, images, documents, font metadata |
| `sse` | `connected`, `disconnected`, `error`, and each SSE event name (`data`, `processMetadata`, `runAction`, …) | `id`, `url`, `reason`, `event` (parsed JSON when the wire payload is JSON, otherwise the raw string). Heartbeats are not reported |
| `expression` | `hide`, `disabled`, `computed`, `conditional`, `validator`, `localScript` | `templateId`, `componentIdentifier`, `conditionIndex` (conditional styles only), `originalExpression` (as authored), `expression` (after data substitution), `result`, `error` (when evaluation threw) |
| `cms` | `fontRegistered`, `fontRegistrationFailed` | React Native only. On web, fonts load through the browser's `FontFace` API and emit no event |

Header values for `Authorization`, `Cookie`, `X-Api-Key` and `X-Fx-Anonymous-Session-Id` are redacted to their last 6 characters before reaching your sink.

## Chat component

To use the `FlxChatRenderer` component, import the module in your project:

```tsx theme={"dark"}
import { FlxChatRenderer } from '@flowx/react-sdk';
```

#### Usage

Include the component in your template:

```tsx theme={"dark"}
  <FlxChatRenderer
    apiUrl={baseUrl}
    authToken={accessToken}
    staticAssetsPath={staticAssetsPath}
    language={language}
    locale={locale}
    themeId={themeId}
    projectId={projectId}
    workspaceId={workspaceId}
    source={source}
    chatConfig={chatConfig}
    cache={cache}
  />
```

Parameters:

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `apiUrl` | Your base API URL | `string` | ✅ | `https://yourDomain.dev` |
| `authToken` | Authorization token | `string` | ✅ | (retrieved from auth provider) |
| `staticAssetsPath` | Path for static resources | `string` | ❌ | (set via environment) |
| `language` | Language used to localize the chat interface | `string` | ❌ | `en` |
| `locale` | Locale setting for date and number formatting | `string` | ❌ | `en-US` |
| `themeId` | Theme identifier for styling | `string` | ❌ | (retrieved dynamically) |
| `projectId` | The FlowX project ID | `string` | ✅ | (retrieved dynamically) |
| `workspaceId` | The workspace ID | `string` | ✅ | (retrieved dynamically) |
| `source` | Source object with type and id | `object` | ✅ | `{ type: 'WORKFLOW', id: '...' }` |
| `chatConfig` | Chat configuration object | `object` | ❌ | `{ welcomeMessage: '...', ... }` |
| `cache` | Enable caching for chat responses | `boolean` | ❌ | `true` |
| `buildId` | Pinned build identifier | `string` | ❌ | (retrieved dynamically) |
| `legacyHttpVersion` | Use legacy HTTP API version | `boolean` | ❌ | - |

#### chatConfig parameters

The `chatConfig` object accepts the following properties:

| Name | Description | Type | Default value |
| - | - | - | - |
| `welcomeMessage` | Message displayed when chat is first opened | `string` | `'Welcome to the chat!'` |
| `thinkingMessage` | Message displayed while waiting for response | `string` | `'Thinking...'` |
| `title` | Chat window title | `string` | `'Chat'` |
| `subtitle` | Chat window subtitle | `string` | `'Chat subtitle'` |
| `showChatIcon` | Whether to display the chat icon | `boolean` | `true` |
| `showSeparator` | Whether to show separator between messages | `boolean` | `true` |
| `newChatLabel` | Label for the new chat button | `string` | `'New chat'` |
| `inputPlaceholder` | Placeholder text for the message input field | `string` | `'Enter your message'` |
| `maxInputRows` | Maximum number of rows for the input field | `number` | `10` |
| `historyTitle` | Title displayed on the chat history panel | `string` | - |
| `errorMessage` | Message shown when an error occurs | `string` | - |
| `canRegenerate` | Show a regenerate button on responses | `boolean` | - |
| `regenerateLabel` | Label for the regenerate button | `string` | - |

## Task management component

To use the `FlxTaskManager` component, import the module in your project:

```tsx theme={"dark"}
import { FlxTaskManager } from '@flowx/react-sdk';
```

#### Usage

Include the component in your template:

```tsx theme={"dark"}
  <FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    themeId={themeId}
    language={language}
    locale={locale}
    staticAssetsPath={staticAssetsPath}
    buildId={buildId}
  />
```

Parameters:

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `apiUrl` | Endpoint where the tasks are available | `string` | ✅ | `https://yourDomain.dev/tasks` |
| `authToken` | Authorization token | `string` | ✅ | (retrieved from local storage) |
| `appInfo` | App information object. Shape: `{ appId: string, appVersionId?: string }` | `object` | ✅ | `{ appId: "app-123" }` |
| `viewId` | The view configuration identifier | `string` | ✅ | (retrieved dynamically) |
| `workspaceId` | The workspace ID | `string` | ✅ | (retrieved dynamically) |
| `themeId` | The theme identifier | `string` | ❌ | (retrieved dynamically) |
| `language` | The selected language | `string` | ❌ | (retrieved dynamically) |
| `locale` | The localization setting | `string` | ❌ | (retrieved dynamically) |
| `buildId` | The current build identifier | `string` | ❌ | (retrieved dynamically) |
| `staticAssetsPath` | Path for static resources | `string` | ❌ | (set via environment) |
| `stages` | Pre-loaded enumeration stages | `TaskManagerEnumeration[]` | ❌ | - |
| `legacyHttpVersion` | Use legacy HTTP API version | `boolean` | ❌ | - |

## Task management public API

The React SDK provides a comprehensive public API for building custom task management interfaces.
This API allows you to fetch tasks, manage comments, handle task actions, and interact with task data programmatically.

### Importing the API

To use the task management public API, import the functions and types from `@flowx/react-sdk`:

```typescript theme={"dark"}
import {
  // Functions
  getTaskManagerResources,
  fetchView,
  fetchViewTasks,
  fetchTaskComments,
  fetchTaskHistory,
  fetchTaskAssignees,
  updateTaskAction,
  saveComment,
  removeComment,
  updateTaskPriority,
  updateBulkTaskAction,
  fetchBulkAssignees,
  getEnumerationOptions,
  initSseConnection,
  
  // Types and Interfaces
  TaskManagerSetupOptions,
  View,
  ViewTask,
  ViewColumn,
  ViewFilter,
  TaskActions,
  TaskComment,
  TaskHistory,
  Assignees,
  TaskManagerEnumeration,
  SseConnection,
  SseEventData,
  SseMessageType,
  SseTaskMessageType,
  SseTaskEventType,
} from '@flowx/react-sdk'
```

### Initialization

Before using the task management API, you need to initialize the task manager resources. This fetches the view configuration, enumerations, and filter operators.

```typescript theme={"dark"}
const { view, enumerations, filterOperators } = await getTaskManagerResources({
  apiUrl: 'https://yourDomain.dev/tasks',
  authToken: 'your-auth-token',
  appInfo: { appId: 'app-123' },
  viewId: 'view-456',
  workspaceId: 'workspace-789',
  themeId: 'theme-012', // Optional
  language: 'en', // Optional
  locale: 'en-US', // Optional
  buildId: 'build-345', // Optional
  staticAssetsPath: '/static', // Optional
})
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `apiUrl` | Endpoint where the tasks are available | `string` | ✅ | `https://yourDomain.dev/tasks` |
| `authToken` | Authorization token | `string` | ✅ | (retrieved from local storage) |
| `appInfo` | App information object containing appId | `{ appId: string }` | ✅ | `{ appId: "app-123" }` |
| `viewId` | The view configuration identifier | `string` | ✅ | (retrieved dynamically) |
| `workspaceId` | The workspace ID | `string` | ✅ | (retrieved dynamically) |
| `themeId` | The theme identifier | `string` | ❌ | (retrieved dynamically) |
| `language` | The selected language | `string` | ❌ | `"en"` |
| `locale` | The localization setting | `string` | ❌ | `"en-US"` |
| `buildId` | The current build identifier | `string` | ❌ | (retrieved dynamically) |
| `staticAssetsPath` | Path for static resources | `string` | ❌ | (set via environment) |

**Returns:** Promise resolving to an object containing:

* `view`: The view configuration object
* `enumerations`: Available enumeration options for filters
* `filterOperators`: Available filter operators for each column

### Fetching tasks

#### `fetchViewTasks`

Fetches tasks for a specific view with support for sorting, filtering, pagination, and search.

```typescript theme={"dark"}
const response = await fetchViewTasks(
  sort,           // Array of sort configurations
  filters,        // Array of filter configurations
  searchTerm,     // Search string
  view,           // View object from getTaskManagerResources
  pagination,     // Pagination object { page: number, size: number }
  enumerations    // Enumerations from getTaskManagerResources
)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `sort` | Array of sort configurations | `ViewTasksSort[]` | ✅ | `[{ keyName: "priority", direction: "ASC" }]` |
| `filters` | Array of filter configurations | `ViewTasksFilter[]` | ✅ | See filter examples below |
| `searchTerm` | Search string for task search | `string` | ✅ | `"urgent"` |
| `view` | View object from initialization | `View` | ✅ | (from `getTaskManagerResources`) |
| `pagination` | Pagination configuration | `{ page: number, size: number }` | ✅ | `{ page: 0, size: 10 }` |
| `enumerations` | Enumerations from initialization | `TaskManagerEnumerations` | ✅ | (from `getTaskManagerResources`) |

**Returns:** Promise resolving to a paginated response containing:

* `content`: Array of `ViewTask` objects
* `totalElements`: Total number of tasks
* `totalPages`: Total number of pages
* Other pagination metadata

**Example:**

```typescript theme={"dark"}
const sort = [{ keyName: 'priority', direction: 'ASC' }]
const filters = [
  {
    keyName: 'status',
    operator: 'EQUALS',
    value: ['PENDING'],
    keyType: 'enumType',
    columnType: 'status',
  },
]
const pagination = { page: 0, size: 10 }

const response = await fetchViewTasks(
  sort,
  filters,
  '', // searchTerm
  view,
  pagination,
  enumerations
)

const tasks = response.content // Array of ViewTask objects
```

#### `fetchView`

Fetches a specific view configuration by ID.

```typescript theme={"dark"}
const view = await fetchView(viewId)
```

### Task details

#### `fetchTaskComments`

Fetches all comments for a specific task.

```typescript theme={"dark"}
const comments = await fetchTaskComments(taskId)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |

**Returns:** Promise resolving to an array of `TaskComment` objects.

**Example:**

```typescript theme={"dark"}
const comments = await fetchTaskComments(selectedTask.id)
// Returns: [
//   {
//     commentId: "comment-1",
//     message: "This task needs attention",
//     author: { username: "john.doe", ... },
//     createdAt: "2024-01-15T10:30:00Z"
//   }
// ]
```

#### `fetchTaskHistory`

Fetches the history/audit trail for a specific task.

```typescript theme={"dark"}
const history = await fetchTaskHistory(taskId)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |

**Returns:** Promise resolving to an array of `TaskHistory` objects.

**Example:**

```typescript theme={"dark"}
const history = await fetchTaskHistory(selectedTask.id)
// Returns: [
//   {
//     historyId: "history-1",
//     events: [
//       {
//         type: "STATUS_CHANGED",
//         description: "Status changed from PENDING to IN_PROGRESS"
//       }
//     ]
//   }
// ]
```

#### `fetchTaskAssignees`

Fetches available assignees for a task, with optional search filtering.

```typescript theme={"dark"}
const assignees = await fetchTaskAssignees(
  taskId,
  tokenUuid,
  options
)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `tokenUuid` | The token UUID associated with task | `string` | ✅ | `"token-uuid-456"` |
| `options` | Search options | `object` | ❌ | `{ keyword: "john" }` |

**Returns:** Promise resolving to an array of `Assignees` objects.

**Example:**

```typescript theme={"dark"}
const users = await fetchTaskAssignees(
  selectedTask.id,
  selectedTask.tokenUuid,
  { keyword: 'john' }
)
// Returns: [
//   {
//     username: "john.doe",
//     firstName: "John",
//     lastName: "Doe",
//     email: "john.doe@example.com"
//   }
// ]
```

#### `fetchBulkAssignees`

Fetches available assignees for multiple tasks in bulk.

```typescript theme={"dark"}
const assignees = await fetchBulkAssignees(
  taskIds,
  options
)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskIds` | Array of task IDs | `string[]` | ✅ | `["task-1", "task-2"]` |
| `options` | Search options | `object` | ❌ | `{ keyword: "john" }` |

**Returns:** Promise resolving to an array of `Assignees` objects.

### Task actions

#### `updateTaskAction`

Executes an action on a specific task (e.g., assign, complete, cancel).

```typescript theme={"dark"}
await updateTaskAction(
  action,
  taskId,
  tokenUuid,
  username
)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `action` | The action to execute | `ExecuteTaskActions` | ✅ | `TaskActions.ASSIGN` |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `tokenUuid` | The token UUID associated with task | `string` | ✅ | `"token-uuid-456"` |
| `username` | Username for assign action (optional) | `string` | ❌ | `"john.doe"` |

**Available Actions:**

* `TaskActions.ASSIGN` - Assign task to a user
* `TaskActions.COMPLETE` - Mark task as complete
* `TaskActions.CANCEL` - Cancel the task
* `TaskActions.CHANGE_PRIORITY` - Change task priority
* `TaskActions.VIEW` - View task details

**Example:**

```typescript theme={"dark"}
// Assign task to a user
await updateTaskAction(
  TaskActions.ASSIGN,
  selectedTask.id,
  selectedTask.tokenUuid,
  'john.doe'
)

// Complete a task
await updateTaskAction(
  TaskActions.COMPLETE,
  selectedTask.id,
  selectedTask.tokenUuid
)
```

#### `updateBulkTaskAction`

Applies an action to multiple tasks at once.

```typescript theme={"dark"}
await updateBulkTaskAction(
  action,
  taskIds,
  options
)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `action` | The action to execute | `ExecuteTaskActions` | ✅ | `TaskActions.COMPLETE` |
| `taskIds` | Array of task IDs | `string[]` | ✅ | `["task-1", "task-2"]` |
| `options` | Additional options | `object` | ❌ | `{ username: "john.doe" }` |

**Example:**

```typescript theme={"dark"}
await updateBulkTaskAction(
  TaskActions.COMPLETE,
  ['task-1', 'task-2', 'task-3']
)
```

#### `updateTaskPriority`

Updates the priority of a specific task.

```typescript theme={"dark"}
await updateTaskPriority(taskId, priority)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `priority` | New priority value | `number` | ✅ | `5` |

**Example:**

```typescript theme={"dark"}
await updateTaskPriority(selectedTask.id, 10)
```

### Comments management

#### `saveComment`

Adds a new comment to a task.

```typescript theme={"dark"}
await saveComment(taskId, commentData)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `commentData` | Comment data object | `object` | ✅ | `{ message: "New comment text" }` |

**Example:**

```typescript theme={"dark"}
await saveComment(selectedTask.id, {
  message: 'This task requires immediate attention'
})

// Refresh comments after saving
const updatedComments = await fetchTaskComments(selectedTask.id)
```

#### `removeComment`

Removes a comment from a task.

```typescript theme={"dark"}
await removeComment(taskId, commentId)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `taskId` | The unique task ID | `string` | ✅ | `"task-123"` |
| `commentId` | The unique comment ID | `string` | ✅ | `"comment-456"` |

**Example:**

```typescript theme={"dark"}
await removeComment(selectedTask.id, comment.commentId)
```

### Enumerations

#### `getEnumerationOptions`

Retrieves enumeration options for a specific enumeration name.

```typescript theme={"dark"}
const options = await getEnumerationOptions(enumName)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `enumName` | The enumeration name | `string` | ✅ | `"Status"` |

**Returns:** Promise resolving to an array of `TaskManagerEnumeration` objects.

### Real-time updates (SSE)

#### `initSseConnection`

Initializes a Server-Sent Events (SSE) connection for real-time task updates.

```typescript theme={"dark"}
const sseConnection = initSseConnection(
  resourceId,
  eventHandler
)
```

**Parameters:**

| Name | Description | Type | Mandatory | Example |
| - | - | - | - | - |
| `resourceId` | The resource ID from the view | `string` | ✅ | `"resource-123"` |
| `eventHandler` | Callback function to handle SSE events | `(event: MessageEvent&lt;string&gt;, data: SseEventData \| null) => void` | ✅ | See example below |

**Returns:** `SseConnection` object with a `close()` method.

**Example:**

```typescript theme={"dark"}
const handleSseEvent = (event: MessageEvent<string>, eventData: SseEventData | null) => {
  if (event.type === SseMessageType.Data) {
    if (eventData?.eventType === SseTaskMessageType.VIEW_UPDATED) {
      // Reload tasks when view is updated
      loadTasks()
    }
  }
}

const sseConnection = initSseConnection(view.resourceId, handleSseEvent)

// Cleanup on component unmount
useEffect(() => {
  return () => {
    if (sseConnection) {
      sseConnection.close()
    }
  }
}, [])
```

**SSE Event Types:**

| Enum | Value | Description |
| - | - | - |
| `SseTaskMessageType` | `VIEW_UPDATED` | View configuration has been updated |
| `SseTaskEventType` | `TASK_UPDATED` | A task has been updated |
| `SseTaskEventType` | `TASK_CREATED` | A new task has been created |

## UI Flow renderer

`FlxUiFlowRenderer` renders a full UI Flow (multi-view navigation, breadcrumbs, embedded processes, and an optional chat widget) from a single component.

```typescript theme={"dark"}
import { FlxUiFlowRenderer } from '@flowx/react-sdk'
```

#### Usage

```tsx theme={"dark"}
<FlxUiFlowRenderer
  apiUrl="https://yourDomain.dev"
  authToken={authToken}
  processApiPath="onboarding"
  language="en"
  locale="en-US"
  themeId="12345678-1234-1234-1234-123456789012"
  staticAssetsPath={staticAssetsPath}
  workspaceId={workspaceId}
  appInfo={{ appId: projectId }}
  organizationId={organizationId}
  isDraft={false}
  cache={true}
  uiFlowName="my-ui-flow"
  buildId={buildId}
  components={{ MyCustomComponent }}
  validators={{ myValidator: () => (v) => v !== '' }}
/>
```

#### Parameters

| Name | Description | Type | Mandatory |
| - | - | - | - |
| `apiUrl` | Base API URL | `string` | ✅ |
| `authToken` | Authorization token | `string` | ✅ |
| `processApiPath` | Process subpath | `string` | ✅ |
| `language` | UI language | `string` | ❌ |
| `locale` | Date/number formatting locale | `string` | ❌ |
| `themeId` | Theme identifier | `string` | ✅ |
| `staticAssetsPath` | Static resources base path | `string` | ✅ |
| `workspaceId` | Workspace identifier | `string` | ✅ |
| `appInfo` | App identity. Shape: `{ appId: string, appVersionId?: string }` | `object` | ✅ |
| `organizationId` | FlowX-issued organization UUID. On self-hosted deployments it matches the `ORGANIZATION_ID` configured during the backend upgrade. See [License and organization configuration](/5.9/migrating-from-5.1-lts/organization-deployment) | `string` | ✅ |
| `isDraft` | Render the draft version of the UI Flow | `boolean` | ❌ |
| `cache` | Enable caching | `boolean` | ❌ |
| `uiFlowName` | Name of the UI Flow to start | `string` | ❌ |
| `buildId` | Pinned build identifier | `string` | ❌ |
| `startParams` | Initial query parameters passed to the UI Flow | `Record<string, unknown>` | ❌ |
| `components` | Custom component registry | `Record<string, ComponentType>` | ❌ |
| `validators` | Custom validator registry | `Record<string, ValidatorFn>` | ❌ |
| `legacyHttpVersion` | Use legacy HTTP API version | `boolean` | ❌ |

### Starting a UI Flow

#### Prerequisites

* **UI Flow name**: You need the name of the UI Flow to start, passed as `uiFlowName`.
* **FlowX Project UUID**: The `appInfo.appId` value, which identifies which project the UI Flow belongs to. Obtain it the same way as for processes: **FlowX Dashboard → Projects → copy UUID from the project actions popover**.
* **Process API path**: The `processApiPath` subpath used by the embedded process renderer when the UI Flow navigates into a full-screen process.

#### Getting the UI Flow name

Open the FlowX Designer and navigate to **UI Flows**. The flow name displayed in the list is the value to pass as `uiFlowName`.

#### Initializing the UI Flow renderer

Minimal working example:

```tsx theme={"dark"}
import { FlxUiFlowRenderer } from '@flowx/react-sdk'

export function MyUiFlowContainer() {
  return (
    <FlxUiFlowRenderer
      apiUrl="https://yourDomain.dev"
      authToken={authToken}
      processApiPath="onboarding"
      language="en"
      locale="en-US"
      themeId={themeId}
      staticAssetsPath={staticAssetsPath}
      workspaceId={workspaceId}
      appInfo={{ appId: projectId }}
      organizationId={organizationId}
      isDraft={false}
      cache={true}
      uiFlowName={uiFlowName}
    />
  )
}
```

#### Passing initial parameters: `startParams`

Use `startParams` to inject query-string key/value pairs into the UI Flow at startup. The values are available inside the flow as URL query parameters.

```tsx theme={"dark"}
<FlxUiFlowRenderer
  {...requiredProps}
  startParams={{ referralCode: 'REF123', skipIntro: true }}
/>
```

> [!NOTE]
>
> `startParams` is read once at initialization. To trigger a full re-initialization, change one of the primitive props such as `uiFlowName`.

***

## Utility API

These functions and hooks are exported from `@flowx/react-sdk` and can be used independently of the renderer components.

```typescript theme={"dark"}
import {
  useEnumeration,
  getEnumeration,
  getStaticAsset,
  getSubstitutionTag,
} from '@flowx/react-sdk'
```

#### `useEnumeration`

React hook that fetches enumeration values reactively. Re-fetches whenever `name` or `parentName` changes.

```typescript theme={"dark"}
const values = useEnumeration(name: string, parentName?: string, cached?: boolean): NomenclatorValue[]
```

| Parameter | Description | Type | Mandatory |
| - | - | - | - |
| `name` | Enumeration name | `string` | ✅ |
| `parentName` | Parent enumeration name for cascading | `string` | ❌ |
| `cached` | Use cached result when available | `boolean` | ❌ |

#### `getEnumeration`

Async function to fetch enumeration values imperatively.

```typescript theme={"dark"}
const values = await getEnumeration(name: string, parentName?: string, cached?: boolean)
```

#### `getStaticAsset`

Resolves a static asset URL by its key.

```typescript theme={"dark"}
const url = getStaticAsset(key: string)
```

#### `getSubstitutionTag`

Resolves a substitution tag value by its key.

```typescript theme={"dark"}
const value = getSubstitutionTag(key: string)
```

***

## Custom CSS

The renderer SDK allows you to pass custom CSS classes on any component inside the process. These classes are then applied to the component's root element.

To add a CSS custom class to a component, you need to define the class in the process designer by navigating to the styles tab of the component, expanding the Advanced accordion and writing down the CSS class.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/add_css_class.gif)

> [!WARNING]
>
> The classes will be applied last on the element, so they will override the classes already defined on the element.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/react/css_class_inspector.png)

## Storybook

Below you find a Storybook which demonstrates how components behave under different states, props, and conditions, it allows you to preview and interact with individual UI components in isolation, without the need for a full-fledged app:

> [card] [Storybook](https://storybooks.flowxai.dev/)


# SDKs overview
Source: https://docs.flowx.ai/5.9/sdks/sdks-overview

FlowX.AI web and native mobile SDKs auto-generate UIs from business process definitions for browser and banking app integration.

The FlowX.AI SDKs render process screens inside your own apps: each SDK connects to a running process instance, generates the UI from the process definition, and orchestrates your custom components. Use the Angular or React SDK for web apps, and the React Native, iOS, or Android SDK for native mobile apps.

> [card] [Angular SDK](angular-renderer)

> [card] [React SDK](react-renderer)

> [card] [React Native SDK](react-native-renderer)

> [card] [iOS SDK](ios-renderer)

> [card] [Android SDK](android-renderer)

***

## SDK versions by release

Install the SDK version listed for the FlowX.AI release you run. All `@flowx` web packages in a release share one version: `angular-sdk`, `angular-theme`, `angular-ui-toolkit`, `react-sdk`, `react-theme`, `react-ui-toolkit`, `core-sdk` and `core-theme`. The three `@flowx/react-native-*` packages also share one version.

| FlowX.AI release | Angular, React and core SDKs | React Native SDK | iOS SDK | Android SDK |
| - | - | - | - | - |
| [5.9.6](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6) | 10.285.4 | 10.285.4 | 10.9.2 | 10.10.2 |
| [5.9.5](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5) | 10.282.5 | 10.277.0 | 10.6.2 | 10.9.3 |
| [5.9.4](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4) | 10.275.0 | 10.277.0 | 10.6.0 | 10.8.0 |
| [5.9.3](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3) | 10.265.6 | 10.266.0 | 10.5.11 | 10.6.6 |
| [5.9.2](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2) | 10.260.7 | 10.262.0 | 10.5.6 | 10.5.6 |
| [5.9.1](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1) | 10.250.2 | 10.255.1 | 10.5.0 | 10.5.4 |
| [5.9.0](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) | 10.230.2 | 10.230.2 | 10.4.1 | 10.5.0 |

The release links open the deployment guidelines for that release, which list every component version.

## SDK requirements

| SDK | Requirements | Details |
| - | - | - |
| Angular | Angular \~21 from 5.9.4, Angular \~20 on 5.9.0 to 5.9.3. Node.js 24 or later, npm 11 or later | [Angular SDK](angular-renderer) |
| React | React 19. Node.js 24 or later, npm 11 or later | [React SDK](react-renderer) |
| React Native | React Native and Expo versions are listed on the SDK page | [React Native SDK](react-native-renderer) |
| iOS | iOS 15 or later, Swift 5.9 | [iOS SDK](ios-renderer) |
| Android | minSdk 26 (Android 8.0), compileSdk 35 | [Android SDK](android-renderer) |


# Release Notes
Source: https://docs.flowx.ai/release-notes/overview

What shipped in every FlowX.AI release - new features, bug fixes, deployment guidelines, and migration steps for the 5.9.x and 5.1.x LTS lines and monthly feature releases.

Release notes · FlowX.AI

What shipped.
Every release, every line.

What shipped in every FlowX.AI release: new features, bug fixes, deployment guidelines, and migration steps. Pick your line below, or jump straight to the latest LTS patch and feature release.

[Latest LTS: 5.9.6](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[Feature release: 6.0.0](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

> [!NOTE]
>
> **Long Term Support (LTS) Versions:** LTS versions receive extended support with security updates and critical bug fixes. **5.9.x** is the current FlowX.AI LTS line, recommended for production environments requiring stability and long-term support. Support for the **5.1.x** line ended with 5.1.14, its final maintenance release. To keep receiving fixes, move to 5.9.x: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview). Release notes for older lines, including 5.1.x and 4.7.x, remain published for reference.
>
> **Feature Releases:** Versions released between LTS lines (such as 5.10.0) introduce new capabilities and are deployed to FlowX.AI SaaS environments as they ship. Self-hosted deployments receive these features consolidated into the next LTS release.

01 · Latest

## Latest releases

[LTS
v5.9.6
Maintenance release for the 5.9.x LTS line. Released on October 20th, 2026.](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)

[FEATURE
v6.0.0
Feature release, live on FlowX.AI SaaS. Released on October 30th, 2026.](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[LTS
v5.1.14
Final maintenance release for the 5.1.x LTS line. Released on October 30th, 2026.](./v5.x/v5.1.x-lts/v5.1.14-october-2026)

> [!TIP]
>
> **New cookbook:** [reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation), from email intake to exception review. More end-to-end builds are in the [cookbooks](/5.9/cookbooks/overview).

***

02 · All releases

## All releases

Planning a 5.9.x upgrade? The [5.9.x LTS changelog](./v5.x/5.9-lts-changelog) lists every change in each 5.9.x maintenance release on one page, with an RSS feed.

Moving from 5.9.x to 6.0.0? The [5.9.x to 6.0.0 changelog](./v6.x/5.9-to-6.0-changelog) lists every change from the 5.10 to 5.13 feature releases and 6.0.0 on one page, with an RSS feed.

versionlinereleased

[v6.0.0FRfeature releaseOctober 30th, 2026→](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[v5.1.14LTSmaintenance · 5.1.x LTS lineOctober 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.14-october-2026)
[v5.9.6LTSmaintenance · 5.9.x LTS lineOctober 20th, 2026→](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[v5.13.0FRfeature releaseSeptember 28th, 2026→](./v5.x/v5.13.0-september-2026/v5.13.0-september-2026)
[v5.9.5LTSmaintenance · 5.9.x LTS lineSeptember 23rd, 2026→](./v5.x/v5.9.5-september-2026/v5.9.5-september-2026)
[v5.1.13LTSmaintenance · 5.1.x LTS lineSeptember 18th, 2026→](./v5.x/v5.1.x-lts/v5.1.13-september-2026)
[v5.12.0FRfeature releaseSeptember 3rd, 2026→](./v5.x/v5.12.0-september-2026/v5.12.0-september-2026)
[v5.9.4LTSmaintenance · 5.9.x LTS lineAugust 27th, 2026→](./v5.x/v5.9.4-august-2026/v5.9.4-august-2026)
[v5.1.12LTSmaintenance · 5.1.x LTS lineAugust 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.12-august-2026)
[v5.11.0FRfeature releaseAugust 11th, 2026→](./v5.x/v5.11.0-august-2026/v5.11.0-august-2026)
[v5.9.3LTSmaintenance · 5.9.x LTS lineJuly 30th, 2026→](./v5.x/v5.9.3-july-2026/v5.9.3-july-2026)
[v5.1.11LTSmaintenance · 5.1.x LTS lineJuly 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.11-july-2026)
[v5.9.2LTSmaintenance · 5.9.x LTS lineJuly 10th, 2026→](./v5.x/v5.9.2-july-2026/v5.9.2-july-2026)
[v5.10.0FRfeature releaseJuly 7th, 2026→](./v5.x/v5.10.0-july-2026/v5.10.0-july-2026)
[v5.1.10LTSmaintenance · 5.1.x LTS lineJune 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.10-june-2026)
[v5.9.1LTSmaintenance · 5.9.x LTS lineJune 15th, 2026→](./v5.x/v5.9.1-june-2026/v5.9.1-june-2026)
[v5.9.0LTSfirst release of the 5.9.x LTS lineJune 2nd, 2026→](./v5.x/v5.9.0-june-2026/v5.9.0-june-2026)
[v5.1.9LTSLTS maintenance releaseMay 29th, 2026→](./v5.x/v5.1.x-lts/v5.1.9-may-2026)
[v5.8.0FRfeature releaseMay 10th, 2026→](./v5.x/v5.8.0-may-2026/v5.8.0-may-2026)
[v5.1.8LTSLTS maintenance releaseApril 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.8-april-2026)
[v5.7.0FRfeature releaseApril 28th, 2026→](./v5.x/v5.7.0-april-2026/v5.7.0-april-2026)
[v5.6.0FRfeature releaseMarch 25th, 2026→](./v5.x/v5.6.0-march-2026/v5.6.0-march-2026)
[v5.1.7LTSLTS maintenance releaseMarch 26th, 2026→](./v5.x/v5.1.x-lts/v5.1.7-march-2026)
[v5.1.6LTSLTS maintenance releaseMarch 16th, 2026→](./v5.x/v5.1.x-lts/v5.1.6-march-2026)
[v5.5.0FRfeature releaseFebruary 27th, 2026→](./v5.x/v5.5.0-february-2026/v5.5.0-february-2026)
[v5.1.5LTSLTS maintenance releaseFebruary 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.5-february-2026)
[v5.1.4LTSLTS maintenance releaseFebruary 9th, 2026→](./v5.x/v5.1.x-lts/v5.1.4-february-2026)
[v5.4.0FRfeature releaseJanuary 30th, 2026→](./v5.x/v5.4.0-january-2026/v5.4.0-january-2026)
[v5.1.3LTSLTS maintenance releaseJanuary 15th, 2026→](./v5.x/v5.1.x-lts/v5.1.3-january-2026)
[v5.3.0FRfeature releaseDecember 24th, 2025→](./v5.x/v5.3.0-december-2025/v5.3.0-december-2025)
[v5.1.2LTSLTS maintenance releaseDecember 3rd, 2025→](./v5.x/v5.1.x-lts/v5.1.2-december-2025)
[v5.2.0FRfeature releaseNovember 10th, 2025→](./v5.x/v5.2.0-november-2025/v5.2.0-november-2025)
[v5.1.1LTSLTS maintenance releaseNovember 10th, 2025→](./v5.x/v5.1.x-lts/v5.1.1-november-2025)
[v4.7.11LTSLTS maintenance releaseDecember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025)
[v4.7.10LTSLTS maintenance releaseNovember 17th, 2025→](./v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025)
[v4.7.9LTSLTS maintenance releaseOctober 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025)
[v5.1.0LTSLTS maintenance releaseOctober 2nd, 2025→](./v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025)
[v4.7.8LTSLTS maintenance releaseSeptember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025)
[v4.7.7LTSLTS maintenance releaseAugust 20th, 2025→](./v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025)
[v5.0.0FRfeature releaseJuly 31st, 2025→](./v5.x/v5.0.0-july-2025/v5.0.0-july-2025)
[v4.7.6LTSLTS maintenance releaseJuly 18th, 2025→](./v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025)
[v4.7.5LTSLTS maintenance releaseJune 19th, 2025→](./v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025)
[v4.7.4LTSLTS maintenance releaseMay 15th, 2025→](./v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025)
[v4.7.3LTSLTS maintenance releaseApril 14th, 2025→](./v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025)
[v4.7.2LTSLTS maintenance releaseMarch 26th, 2025→](./v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025)
[v4.7.1LTSLTS maintenance releaseMarch 7th, 2025→](./v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025)
[v4.7.0LTSLTS maintenance releaseFebruary 24th, 2025→](./v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025)
[v4.6.1FRfeature releaseFebruary 7th, 2025→](./v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025)
[v4.6.0FRfeature releaseJanuary 23rd, 2025→](./v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025)
[v4.1.5LTSLTS maintenance releaseSeptember 23rd, 2024→](./v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024)
[v4.1.4LTSLTS maintenance releaseSeptember 6th, 2024→](./v4.x/v4.1.x/v4.1.4-september-2024/v4.1.4-september-2024)
[v4.1.3LTSLTS maintenance releaseAugust 12th, 2024→](./v4.x/v4.1.x/v4.1.3-august-2024/v4.1.3-august-2024)
[v4.1.2LTSLTS maintenance releaseJune 8th, 2024→](./v4.x/v4.1.x/v4.1.2-june-2024/v4.1.2-june-2024)
[v4.1.1LTSLTS maintenance releaseJune 17th, 2024→](./v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024)
[v4.1.0LTSLTS maintenance releaseMay 30th, 2024→](./v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024)
[v4.0.0FRfeature releaseApril 18th, 2024→](./v4.x/v4.0.0-april-2024/v4.0.0-april-2024)

> [!NOTE]
>
> Releases from the **4.5.x (tech preview)** and **4.2.x** lines are not listed above. You can find them in the sidebar under **Release Notes** → **v4.x**.

***

> [accordion] Version 3.x.x
>
> > [card] [v3.4.8 - June 2024](/release-notes/v3.x.x/v3.4.8-june-2024/v3.4.8-june-2024)
> >
> > Explore the latest enhancements and fixes introduced in June 2024.
>
> > [card] [v3.4.7 - January 2024](/release-notes/v3.x.x/v3.4.7-january-2024/v3.4.7-january-2024)
> >
> > Explore the latest enhancements and fixes introduced in January 2024.
>
> > [card] [v3.4.6 - December 2023](/release-notes/v3.x.x/v3.4.6-december-2023/v3.4.6-december-2023)
> >
> > Explore the latest enhancements and fixes introduced in December 2023.
>
> > [card] [v3.4.5 - November 2023](/release-notes/v3.x.x/v3.4.5-november-2023/v3.4.5-november-2023)
> >
> > Explore the latest enhancements and fixes introduced in November 2023.
>
> > [card] [v3.4.4 - November 2023](/release-notes/v3.x.x/v3.4.4-november-2023/v3.4.4-november-2023)
> >
> > Discover the significant changes and improvements made in November 2023.
>
> > [card] [v3.4.3 - October 2023](/release-notes/v3.x.x/v3.4.3-october-2023/v3.4.3-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.2 - October 2023](/release-notes/v3.x.x/v3.4.2-october-2023/v3.4.2-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.1 - September 2023](/release-notes/v3.x.x/v3.4.1-september-2023/v3.4.1-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.4.0 - September 2023](/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.3.0 - July 2023](/release-notes/v3.x.x/v3.3.0-july-2023/v3.3.0-july-2023)
> >
> > Discover the significant changes and improvements made in July 2023.
>
> > [card] [v3.2.0 - April 2023](/release-notes/v3.x.x/v3.2.0-april-2023/v3.2.0-april-2023)
> >
> > Discover the significant changes and improvements made in April 2023.
>
> > [card] [v3.1.0 - March 2023](/release-notes/v3.x.x/v3.1.0-march-2023/v3.1.0-march-2023)
> >
> > Discover the significant changes and improvements made in March 2023.
>
> > [card] [v3.0.0 - February 2023](/release-notes/v3.x.x/v3.0.0-february-2023/v3.0.0-february-2023)
> >
> > Discover the significant changes and improvements made in February 2023.


# FlowX.AI 5.9.x LTS changelog
Source: https://docs.flowx.ai/release-notes/v5.x/5.9-lts-changelog

Every change in each FlowX.AI 5.9.x LTS maintenance release, grouped by type and component, with an RSS feed for upgrade planning.

This page lists every change in each 5.9.x LTS maintenance release, newest first. Use the RSS button at the top of the page to subscribe and get each new patch as it ships. Mobile renderers and the React Native SDK are covered in their own release notes. Moving to 6.0.0? See the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog).

**5.9.6**

October 2026

**Upgrade actions:** migrate to the `flowx-ai` Helm chart if you installed the `ai-platform` chart, create the `ai.flowx.build.deployment-failed.v1` Kafka topic and allow it in your ACLs, re-publish any build whose deployment failed shortly before the upgrade, review workflow node retry settings, grant the connection-test permissions to custom roles, and allow extra Integration Designer startup time on a large `workflow_instances` collection. Details are in the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).

#### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

#### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect.
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#mongodb-setting-names).
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6) for its version.

#### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.6 release notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026) · [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6)

**5.9.5**

September 2026

**Upgrade actions:** let the `ai-services` consumer group reach zero lag and allow the new AI consumer groups in Kafka ACLs, add private database hosts to the NoSQL DB runner allowlist, set every service-account client secret on `authorization-system`, rename `cache_error_total` in dashboards and alerts, re-expose `loggers` if you change log levels at runtime, and review the deployment guidelines if you had already turned on data partitioning, because the conversion to native partitions is one way. Details are in the [5.9.5 upgrade notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#upgrade-notes).

#### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#native-postgresql-partitioning).

#### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.

#### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.5 release notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026) · [5.9.5 deployment guidelines](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5)

**5.9.4**

August 2026

**Upgrade actions:** move the registry out of `image.repository` if you embedded it there (no action if you set `global.imageRegistry`), grant the Liquibase lock permissions to each service's database user on Oracle, create the `flowx-events-gateway-sa` client yourself if you manage Keycloak clients outside the Helm charts, and move host apps that embed the Angular SDK to Angular 21. Details are in the [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4#configuration-changes).

#### Changed

* **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.
* **Angular SDK:** the Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps that embed the Angular SDK must be on Angular 21. The npm and node requirements are unchanged.
* **Cross-version import:** importing a project build or version exported from an older platform line completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten.
* **Database migrations:** the lock that guards Liquibase schema migrations at service startup is a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration releases its lock when the database closes the session. Service accounts no longer need the `pods/status` permission. Oracle deployments need new database grants.
* **Events Gateway:** authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`. Helm chart deployments where `authorization-system` runs its migrations with Keycloak admin access need no action.
* **Helm charts:** the container image reference is split into `image.registry` and `image.repository`. The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. The default image location is unchanged.
* **Integration Designer:** service startup no longer scans the full token-instance collection, and the run-list summary queries are indexed.
* **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.
* **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.

#### Fixed

* **Actions:** deleting an action whose business rule calls a function works instead of returning a server error.
* **Build export:** retrying a build export re-attempts a dependency library whose own export timed out, so the parent build can finish.
* **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output from trailing empty cells and rows.
* **Entry points:** the entry-point picker in version settings lists only processes and UI flows from the current project.
* **Gateways:** an expression that fails to evaluate on an exclusive gateway surfaces as an incident on the process instance instead of only in the service logs.
* **Generated documents:** a document whose storage write fails returns an error instead of being recorded as successful. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.
* **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is listed once instead of once per consuming project version.
* **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives during a background synchronization, and merging versions no longer fails with a navigation-areas error.
* **Renderers:** the document preview shows its subtitle, and the file-upload error message follows the configured theme.
* **Reusable UI templates:** static input mappings configured on a reusable template are applied at runtime.
* **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.
* **Task management:** the row-selection checkbox column no longer carries an invisible sort control that re-sorted the view and cleared the selection, and changing the page size no longer opens the wrong process from the list.
* **Themes and CMS resources:** exporting a theme no longer includes duplicate copies of system icons, and importing no longer leaves system substitution tags missing.
* **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.4 release notes](/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026) · [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4)

**5.9.3**

July 2026

**Upgrade actions:** none. The new Events Gateway and Integration Designer settings ship with working defaults. Details are in the [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3#configuration-changes).

#### Changed

* **Events Gateway:** new settings tune the dedicated Redis connection pool for blocking reads, and the default blocking-read duration is lowered from 5 seconds to 1 second. If you set the blocking-read duration explicitly, review it against the new default.
* **Integration Designer:** a new setting sets the number of partitions for auto-created workflow Kafka topics. Existing topics are not modified.
* **Media Library:** PDF assets in the list can be opened in a new tab.
* **Process start:** web renderers keep the loading indicator visible until the first user task renders.

#### Fixed

* **Build import:** a transient database write conflict during a multi-dependency import no longer drops a dependency's build, which caused runtime errors on substitution tags and enumerations. Large imports may take slightly longer.
* **Date Picker:** the calendar anchors to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.
* **Designer:** opening Runtime after expanding a component's Permissions section no longer freezes the Designer, and a pending AI UI-generation draft no longer locks the process diagram read-only.
* **Projects:** creating a project with the same name as a deleted project returns a validation error instead of an internal server error.
* **Real-time event delivery:** the Events Gateway no longer leaks Redis connections. Blocking reads run on a dedicated connection pool with Redis Cluster support, so the gateway no longer needs periodic restarts under sustained load.
* **Task management:** deleting a swimlane allocation rule removes only that rule, clicking Save twice no longer creates duplicate rules, and task views no longer reset when the same view is open from different workspaces.
* **Workflows:** a workflow no longer freezes silently after a step exhausts its retries.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.3 release notes](/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026) · [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3)

**5.9.2**

July 2026

**Upgrade actions:** update any Keycloak group mapper or external IdP claim that emits the end-user group `User` to `Users Group`, remove records of the organization-ID migration or other Liquibase changesets you marked as executed by hand on an earlier 5.9.x (contact FlowX support for the list first), upgrade the AI Platform chart and the core services together, and update dashboards, alerts, and log queries that match the `ai-platform-` service name prefix. Details are in the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#upgrade-overview).

#### New

* **AI agents and data models:** AI Designer and AI Developer use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it.
* **AI workflow nodes:** JSON schema fields support `${}` placeholders.
* **Chat file uploads:** end users can attach multiple files in a chat-driven app. Uploads are indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content.
* **Document Parser:** a new LiteParse engine parses PDFs and images locally without GPU or AI calls, and OCR supports English, Romanian, Hungarian, and Bulgarian.
* **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.
* **Knowledge bases:** a Custom Agent node can select multiple knowledge bases, each exposed to the agent as its own retrieval tool, and retrieval can span multiple knowledge bases in a workflow.
* **SQL data sources:** queries on SQL data sources can be tested from the builds list.
* **Use in reporting:** the reporting toggle is available on UI flows and workflows.

#### Changed

* **AI node structured output:** responses from AI nodes with a response schema are validated against it, with automatic repair retries, and node logs include the failure reason and rejected output.
* **AI Platform services:** services are deployed under their plain names, without the `ai-platform-` prefix on pod, service, and image names, and the bundled Qdrant subchart is renamed the same way. Core services resolve AI components by the new names.
* **Audit log:** records sharing, user invitations, designer-user, end-user, and group management, actions on process instances and UI flows, adding a dependency, and terminating process, workflow, or UI flow instances.
* **Copy to project:** copying a process or UI flow to another project also copies its roles.
* **Data archiving:** archiving detaches a partition only when every process or workflow instance in it has finished. New settings for terminating stuck instances and backfilling legacy rows are off by default.
* **Default end-user group:** the group that the 5.1.x upgrade migration creates is renamed from `User` to `Users Group`. Groups your admins created are not renamed.
* **Designer:** the Event Handlers section appears higher in the component configuration panel, and the keys to save for collection items and bundled custom-component inputs are computed automatically.
* **Kafka reconnects:** platform services use a gentler broker-reconnect backoff by default, and repeated Kafka connection errors log at a quieter level.

#### Fixed

* **Active policy:** the user list on the override active-policy form is no longer empty.
* **Application manager:** the runtime-application organization-ID migration converts existing data correctly.
* **Audit logs:** filtering audit entries by user works when the username differs from the email address.
* **Build export with media files:** exporting a build with media file content produces an archive that contains the binaries.
* **Chat:** the floating chat position is calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.
* **CMS enumerations:** cascading-enum value lookups resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.
* **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.
* **Data sync with private CA certificates:** data-sync migrations that call HTTPS endpoints, such as Keycloak, no longer fail certificate validation in environments that use an internal certificate authority.
* **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.
* **Project version merge:** a merge no longer fails with a 500 error.
* **Redis Cluster:** UI template cache keys map to the same cluster slot, which prevents cross-slot errors.
* **Reusable UI templates:** actions are no longer missing at runtime when a template is nested in multiple levels of containers.
* **Self-hosted installation and upgrade:** Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding work on self-hosted environments.
* **Workflow data:** archiving batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine is fixed.
* Stability fixes across the Designer, the renderers, and the backend services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.2 release notes](/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026) · [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2)

**5.9.1**

June 2026

**Upgrade actions:** none for deployments where the Helm chart provisions Kafka topics. If you provision Kafka topics or ACLs manually, create the topics added in 5.9.1. Details are in the [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics).

#### New

* **AI permissions:** AI runtime usage and AI build-time tooling (AI Designer, agent building, code generation) are governed by two separate permissions. When AI is turned off, AI icons and entry points are hidden instead of shown disabled, and build-time helpers such as code generation and "Add comment" follow the dev-agent permission.
* **File Preview:** scroll-trigger event handlers, including a "document end" trigger, let a flow detect when a user scrolls through a document or reaches its end, for example to enable an **Accept** button only after the user reaches the end of an agreement.
* **File upload:** the upload button supports a configurable icon, set in the Designer.
* **Microsoft Outlook:** connections support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
* **Script engine:** business rules, reusable functions, and node rules can each run on the native engine (the 5.9 default) or the legacy GraalVM engine. Rules created before the switch to native keep running on GraalVM until you migrate them, and new rules default to native.

#### Changed

* **AI Designer:** generates UI from a flat template format instead of 3-level nesting, supports more component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates incrementally instead of regenerating them, and can generate reusable UI templates.
* **Kafka topics:** new topics carry runtime config-param change events, runtime instance terminations, resource cache evictions, and evaluation improvement suggestions. The Helm chart provisions them.
* **Merge conflicts:** merge-conflict handling for custom components and UI Flows identifies resources more clearly.
* **Organization settings:** navigation and design improvements.
* **Platform Status:** reports AI Platform components and their databases alongside the core services.
* **Runtime config params:** changes reach the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
* **Workflows:** storage of running steps is optimized, workflows and processes launched from a UI Flow inherit the build of the parent UI Flow, and AI node failures show the error details and model reasoning in the workflow run logs.

#### Fixed

* **Actions:** GET actions no longer fire with undefined parameters.
* **AI chat:** agent responses no longer reappear in chat after stop and refresh, and the builder-agent chat no longer duplicates messages.
* **Copy to project:** copying a process or workflow to another project succeeds, and copied workflows appear in the target project.
* **End-user login:** a null value is no longer cached when looking up the "All end-users" group, which could block logins until data sync completed.
* **File Preview:** previews render correctly, events fire inside collections, a fixed height applies at runtime, and preview resources no longer fail with CORS errors.
* **File Storage:** FTP test connection and file operations resolve configuration-parameter placeholders, and FTP file preview works when the root path has no leading slash.
* **Forms to validate:** scrolling covers the full component hierarchy, placeholders update, and chat and tab-bar components are selected correctly.
* **Hide and disable conditions:** conditions on UI templates, processes, and UI Flows apply at runtime for Designer users without workspace access.
* **Invitations:** an invited Designer user added as an Organization owner is assigned to a workspace.
* **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
* **Modals:** dropdowns no longer flicker, and long key names no longer break the layout.
* **Process instances:** loading an instance with a very large execution graph no longer crashes the browser.
* **Task management:** headers follow the theme in React and Angular, and the filter window no longer disappears after applying criteria.
* **Theme admin:** "copy to" no longer loses theme content.
* **Timer events:** activating a start timer event after a new build regenerated the process resource ID no longer fails with a 500 (duplicate key) error.
* **UI Flow:** images display in preview after refresh, and returning from an expired UI Flow no longer loses the theme UUID.
* **Usage Overview:** opening a usage overview no longer fails with a 500 error.
* **Web renderer:** the button shadow and modal content padding are restored, and components render when a media-file storage path is null.
* **Workflows:** END PARALLEL output no longer includes data from before the parallel branches started, and NoSQL node run logs no longer crash when a node fails before building its options.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.1 release notes](/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026) · [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1)


# Deployment guidelines v5.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10

Component versions and deployment notes for FlowX.AI 5.10 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.10 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.10.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.10.0 |
| - | - |
| **admin** | 11.18.0 |
| **advancing-controller** | 11.12.0 |
| **application-manager** | 11.18.0 |
| **audit-core** | 11.11.0 |
| **authorization-system** | 11.14.0 |
| **cms-core** | 11.14.0 |
| **data-search** | 11.11.0 |
| **data-sync** | 11.9.0 |
| **designer** | 11.36.1 |
| **document-plugin** | 11.19.0 |
| **email-gateway** | 11.15.0 |
| **events-gateway** | 11.14.0 |
| **file-gateway** | 11.14.0 |
| **integration-designer** | 11.24.2 |
| **license** | 11.13.0 |
| **nosql-db-runner** | 11.14.0 |
| **notification-plugin** | 11.14.0 |
| **organization-manager** | 11.14.0 |
| **process-engine** | 11.19.3 |
| **runtime-manager** | 11.18.0 |
| **scheduler-core** | 11.11.0 |
| **task-management-plugin** | 11.15.0 |
| **webhook-gateway** | 11.13.0 |

### AI base components

| Component | 5.10.0 |
| - | - |
| **embedder** | 11.2.0 |
| **knowledgebase-indexer-v2** | 11.2.0 |
| **knowledgebase-rag** | 11.2.0 |
| **doc-parser** | 11.2.0 |

### AI dev-time components

| Component | 5.10.0 |
| - | - |
| **ai-gateway** | 11.15.1 |
| **ai-analyst** | 11.2.0 |
| **ai-assistant** | 11.2.0 |
| **ai-designer** | 11.2.0 |
| **ai-developer** | 11.2.0 |
| **kb-enrichment** | 11.2.0 |
| **planner** | 11.2.0 |

### AI runtime components

| Component | 5.10.0 |
| - | - |
| **agent-builder** | 11.2.0 |
| **data-privacy** | 11.2.0 |
| **doc-converter** | 11.2.0 |
| **dynamic-classifier** | 11.2.0 |
| **evals-judge** | 11.2.0 |
| **speech-to-text** | 11.2.0 |
| **web-crawler** | 11.2.0 |

### AI extensions

| Component | 5.10.0 |
| - | - |
| **modpod** | 11.2.0 |
| **observatory-api** | 11.0.2 |
| **observatory-platform** | 11.0.2 |
| **observatory-web** | 11.0.2 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments receive them, re-verified, with the next LTS release.

### New Kafka topics

| Topic | Producer → Consumer | Purpose |
| - | - | - |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin → process-engine | Resource cache eviction |
| `ai.flowx.config.params.events.v1` | application-manager → process-engine | Config-param change notifications |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine → integration-designer | Runtime-instance termination |
| `ai.flowx.evals.suggestions.job.request.v1` / `.response.v1` | integration-designer | Evals suggestions job requests and responses |

### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them when your environment moves to 5.10.

This release also adds a new AI Platform component, **dynamic-classifier** (listed under AI runtime components above), which backs document classification.

In `admin`, the single `FLOWX_FEATUREAVAILABILITY_AISERVICENAME` setting is replaced by two, reflecting the split between AI dev-time and AI runtime services: `FLOWX_FEATUREAVAILABILITY_AIDEVTIMESERVICENAME` (default `ai-gateway-mngt`) and `FLOWX_FEATUREAVAILABILITY_AIRUNTIMESERVICENAME` (default `agent-builder-mngt`).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.10.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026

What's new in FlowX.AI 5.10: PostgreSQL and SOAP data sources, AI Developer script-node code generation, file uploads in chat-driven apps, and AI and document-intelligence improvements.

[FlowX.AI 5.10 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.10.0.html)

> [!NOTE]
>
> **FlowX.AI 5.10 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments receive them with the next LTS release.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release adds PostgreSQL and SOAP data sources, multi-file upload in chat-driven apps, and a set of AI and document-intelligence capabilities, alongside broader audit coverage, roles that travel with copied resources, and workflow data-partitioning improvements.

***

**What's new?**

> [tab] Core & Platform
>
> 🗂️ [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions\
> 📑 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources\
> ⚡ [**Platform performance and fixes**](#platform-performance-and-fixes) - Task-manager user fetch, project versioning, export/merge

> [tab] Designer & Renderer
>
> 💬 [**Chat file upload**](#chat-file-upload) - Attach multiple files in conversational apps\
> ⬇️ [**File download component**](#file-download-component) - Download files from a rendered app (web and Android)\
> 🔀 [**Conditional event-handler triggers**](#conditional-event-handler-triggers) - Fire event handlers based on a condition\
> 🎨 [**Image color property**](#image-color-property) - Color control on the IMAGE component\
> 💾 [**Save local variable**](#save-local-variable-action) - Capture a collection row into local data on click\
> 🪟 [**Global header and footer**](#global-header-and-footer) - Consistent header and footer across a UI Flow\
> 🧩 [**Reusable UI templates**](#reusable-ui-templates) - Action mapping, undo/redo, and dependency-version fixes

> [tab] Integrations & Data
>
> 🐘 [**PostgreSQL data source**](#postgresql-data-source) - Connect workflows directly to PostgreSQL and run SQL queries\
> 🧼 [**SOAP integration**](#soap-integration) - Import a WSDL and call SOAP operations from workflows\
> 🧮 [**FlowX Database aggregation**](#flowx-database-aggregation) - MongoDB aggregation pipelines\
> 🗄️ [**Documents tab in database testing**](#documents-tab-in-database-testing) - Inspect data while testing DB operations

> [tab] AI & Documents
>
> 📊 [**Tabular data extraction node**](#tabular-data-extraction-node) - Read spreadsheets and CSV into workflow data\
> 🔁 [**Knowledge Base error handling**](#knowledge-base-error-handling-and-retry) - Retry failed KB ingestion\
> ✨ [**AI Developer: script-node code**](#ai-developer-generate-script-node-code) - Generate node code from a prompt\
> 🧪 [**AI evaluation experiments**](#ai-evaluation-experiments) - Multiple datasets and improvement suggestions\
> 🛡️ [**AI node output reliability**](#ai-node-output-reliability) - Schema validation with auto-repair and clearer run errors\
> 📝 [**Template Filling node**](#template-filling-node) - Generate documents from templates in workflows\
> 🗂️ [**File manipulation nodes**](#file-manipulation-nodes) - Combine and split files in workflows\
> 📄 [**DOCX document generation**](#docx-document-generation) - Generate documents as DOCX in addition to PDF\
> 🏷️ [**Document Tag**](#document-tag-renamed-from-document-type) - "Document Type" renamed\
> 🔑 [**Mistral model provider**](#mistral-model-provider) - Bring your own Mistral API key

### **Expanded audit logging**

> [card] Broader audit coverage for access and lifecycle actions
>
> Audit logging now records a wider set of actions: **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> All Deployments

### **Copy with roles**

> [card] Roles travel with copied resources
>
> Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> All Deployments

### **Platform performance and fixes**

> [card] Platform performance and fixes
>
> > [tab] Performance
> >
> > The task manager fetches users through the authorization-system instead of calling Keycloak directly, cutting per-request identity lookups.&#x20;
> >
> > MongoDB partition archiving scales for large datasets, with partition-ID backfill for legacy data and archiving fixes on PostgreSQL and Oracle.&#x20;
>
> > [tab] Bug fixes
> >
> > > [accordion] Core platform fixes
> > >
> > > * **Project selector:** projects without a work-in-progress branch are correctly shown as unavailable.&#x20;
> > > * **Start Solution:** no longer fails with "no entry point set" until the page is refreshed.&#x20;
> > > * **Export and merge:** fixed errors when exporting a project build with imported libraries and when merging project versions, including a 500 during merge.&#x20;
> > > * **Merge-conflict checks:** no longer fail on processes that contain conflicts.&#x20;
> > > * **Allocation roles:** candidate-user search works for users without runtime permissions on the asset.&#x20;
> > > * **Version switching:** the selected resource opens when changing app versions, and reusable-function code refreshes on version switch.&#x20;
> > > * **Process engine:** resolved an incident-save deadlock.&#x20;
> > > * **FlowX Database:** inserting a document with a reserved `_id` key is now rejected with a clear error instead of breaking later reads.&#x20;
>
> All Deployments

### **PostgreSQL data source**

> [card] Connect to PostgreSQL databases from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds **PostgreSQL** as a data source type, alongside Oracle. Connect a workflow directly to a PostgreSQL database and run SQL queries against it as a workflow node, without a custom REST wrapper. See the [PostgreSQL Database](/5.9/docs/platform-deep-dive/integrations/postgresql-database) documentation.
>
> > [tab] Key Features
> >
> > > [card] Direct connection
> > >
> > > Configure host, port, database, schema, and credentials, with an optional SSL connection and a **Test connection** check before saving.
> >
> > > [card] SQL query operations
> > >
> > > Define SQL query operations on the data source and call them from workflow nodes.
> >
> > > [card] Connection pool tuning
> > >
> > > Advanced settings cover pool size, connection and query timeouts, keep-alive, and a validation query.
> >
> > > [card] Familiar experience
> > >
> > > Shares the same configuration and operations experience as the existing Oracle data source.
>
> SaaS

### **SOAP integration**

> [card] Call SOAP web services from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds a **SOAP System** data source. Import the service's **WSDL** — from a URL or an uploaded file — and FlowX discovers the operations with their input, output, and fault schemas, composes the SOAP envelope at runtime, and lets you call each operation from workflows through a **SOAP Operation** node. See the [SOAP System](/5.9/docs/platform-deep-dive/integrations/soap-system) documentation.
>
> > [tab] Key Features
> >
> > > [card] WSDL import
> > >
> > > Preview and select the operations to import; re-import refreshes schemas while preserving your edits
> >
> > > [card] Typed variables
> > >
> > > Envelope variables extracted from the input XSD, referenced as workflow parameters
> >
> > > [card] SOAP 1.1 and 1.2
> > >
> > > Version derived from the WSDL, with standard headers set automatically
> >
> > > [card] Testing built in
> > >
> > > Test operations with value overrides, a curl preview, and full request/response envelopes in run logs
>
> SaaS

### **Reusable UI templates**

> [card] Reusable UI template fixes
>
> Reusable UI templates get more reliable action mapping, undo/redo, and dependency-version handling.
>
> All Deployments

### **Chat file upload**

> [card] Attach multiple files in conversational apps
>
> End users can attach multiple files at once in chat-driven apps, and conversational workflows can receive those files as input. Uploaded files are extracted and indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content. Configurable in the Designer and themable, with runtime support on the web renderer.
>
> Session knowledge bases are isolated per conversation and per tenant, and are excluded from app export.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **File download component**

> [card] Download files from a rendered app
>
> A new File Download component lets end users download files directly from a rendered app. Configured in the Designer, with runtime support on web and Android.
>
> For more information, see the [File download](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download) documentation.
> SaaS

### **Conditional event-handler triggers**

> [card] Fire event handlers based on a condition
>
> Event handlers can now fire conditionally, configured in the Designer and honored by the web and Android renderers.
>
> For more information, see the [event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers) documentation.
> SaaS

### **Image color property**

> [card] Color control on the IMAGE component
>
> The IMAGE component now honors a color property, configured in the Designer and rendered on web and Android.
>
> See the [Image component](/5.9/docs/building-blocks/ui-designer/ui-component-types/image) documentation.
> SaaS

### **Save local variable action**

> [card] Capture a collection row into local data
>
> Event handlers gain a **Save Local Variable** action type: on a component inside a collection, it saves the clicked row's item into local data under a configurable key, entirely client-side with no backend roundtrip — useful for capturing the selected row before a follow-up action fires. Not available inside Reusable UI Templates.
>
> See the [Save Local Variable](/5.9/docs/building-blocks/ui-designer/event-handlers#save-local-variable) documentation.
> SaaS

### **Global header and footer**

> [card] Consistent header and footer across a UI Flow
>
> UI Flows can now define a **global header and footer** that display consistently across every page of the flow. Each holds content components — containers, forms, buttons, links, custom components — with fixed or static positioning (header fixed by default), so you can build persistent navigation or action bars in one place instead of per page.
>
> See the [Global Header and Footer](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer) documentation.
> SaaS

### **Tabular data extraction node**

> [card] Extract spreadsheet and CSV data into workflows
>
> A new workflow node reads a spreadsheet or CSV file and returns its contents as structured JSON in the node's response key, so the data can drive conditions and data operations downstream. Each row is returned as an object keyed by the file's header row, and for Excel files you can select which sheet to read.
>
> For more information, see the [Tabular Data Extraction node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node) documentation.
> SaaS

### **Knowledge Base error handling and retry**

> [card] Recover from failed Knowledge Base ingestion
>
> When Knowledge Base ingestion fails, the Knowledge Base page now shows a clear failure status and reason, and a **Retry** button re-runs the last operation after cleaning up partial content so the store is not left inconsistent. The **Update Knowledge Base** workflow node gains a **FAIL** exit handle with per-operation rollback.
>
> Learn more about [Knowledge Bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview).
> SaaS

### **AI Developer: generate script-node code**

> [card] Generate script-node code with AI Developer
>
> In the workflow designer, a script node can call **AI Developer** to generate or refactor its code from a natural-language prompt. Output streams into the test area for a **Keep** or **Discard** review, with edits shown as a diff. Supports JavaScript and Python, and respects existing AI Developer permissions.
>
> Learn more about [AI Developer](/5.9/ai-platform/pre-built-agents/ai-developer).
> SaaS

### **FlowX Database aggregation**

> [card] Aggregation pipelines in FlowX Database
>
> The FlowX Database data source adds MongoDB **aggregation pipeline** support, so configurators can group, join, reshape, and compute across documents beyond what a single query allows.
>
> Learn more about the [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) data source.
> SaaS

### **AI evaluation experiments**

> [card] Richer AI evaluation experiments
>
> > [tab] Multiple datasets
> >
> > An evaluation experiment can run against **multiple datasets** at once (datasets sharing the same AI node), with overall metrics aggregated across them and a dataset column added to the report.
>
> > [tab] Improvement suggestions
> >
> > Experiment reports now show **AI-generated suggestions** for improving the node's prompt, grouped per LLM-as-judge evaluator, beneath the score cards.
>
> Learn more about [AI evaluations](/5.9/ai-platform/evaluations).
> SaaS

### **AI node output reliability**

> [card] Schema validation with auto-repair and clearer run errors
>
> > [tab] Validation and repair
> >
> > When an AI node has a **Response Schema**, the response is validated against it and automatically retried with a repair prompt on mismatch. Nodes that still fail return a **categorized error** instead of passing malformed output downstream, and the node's **Logs** show the failure reason, rejected output, the model's reasoning summary, and the retry count.
>
> > [tab] Schema placeholders
> >
> > Response schemas now support `${variable}` placeholders resolved at runtime against workflow data, with substituted values coerced to the schema-declared types — consistent with how other AI-node fields resolve placeholders.
>
> See [AI node types](/5.9/ai-platform/agent-builder/node-types#structured-output-validation-and-run-diagnostics) for details.
> SaaS

### **Template Filling node**

> [card] Generate documents from templates in workflows
>
> Integration workflows gain a **Template Filling** node, under **Tools** in the node palette, that generates a document from a document template populated with workflow data. Select a template and language, fill the template's variables from workflow data, and choose **PDF** or **DOCX** output. The generated file's ID and download path are returned on the node's response key.
>
> See the [Template Filling node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) documentation.
> SaaS

### **File manipulation nodes**

> [card] Combine and split files in workflows
>
> Integration workflows add two document nodes, under **Tools** in the node palette: **Combine Files** merges multiple PDFs into one in a given order, and **Split File** breaks a PDF into multiple files by page ranges or one file per page. Both bring document handling that was previously process-only into workflows.
>
> See the [Combine Files](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) documentation.
> SaaS

### **DOCX document generation**

> [card] Generate documents as DOCX
>
> Template-based document generation can now produce **DOCX** files in addition to PDF. Set `outputFormat` (`PDF` or `DOCX`; defaults to `PDF`) on the generation request, or pick the format from the new **Output format** dropdown when testing a template in the Designer. Generated DOCX files preserve the template's styles, data, and images. Barcodes apply to PDF output only.
>
> Learn more in the [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output) documentation.
> SaaS

### **Document Tag (renamed from Document Type)**

> [card] Document Type is now Document Tag
>
> The **Document Type** field is renamed **Document Tag** across the surfaces where a document is tagged for storage (Upload File action, Document-Plugin REST responses, AI Document Generation, and the Web Page Extractor). This is a label change; behavior is unchanged.
> SaaS

### **Documents tab in database testing**

> [card] Inspect data while testing database operations
>
> The Database Query testing modals gain a **Documents** tab, so you can inspect the database right after running an operation. Multi-record operations report an affected-record count.
> SaaS

### **Mistral model provider**

> [card] Bring your own Mistral API key
>
> **Mistral** joins the model provider catalog as a bring-your-own-key provider. Add it with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability: chat, image understanding, embeddings, and document OCR. The seeded catalog covers the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed model lines.
>
> Learn more about [AI providers](/5.9/ai-platform/ai-providers).
> SaaS

***

## Deployment guidelines

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.10 deployment guidelines](./deployment-guidelines-v5.10).&#x20;


# Deployment guidelines v5.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11

Component versions and deployment notes for FlowX.AI 5.11 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.11 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.11.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.11.0 |
| - | - |
| **admin** | 11.53.0 |
| **advancing-controller** | 11.31.0 |
| **application-manager** | 11.46.0 |
| **audit-core** | 11.30.0 |
| **authorization-system** | 11.38.0 |
| **cms-core** | 11.43.0 |
| **data-search** | 11.30.0 |
| **data-sync** | 11.27.0 |
| **designer** | 11.89.1 |
| **document-plugin** | 11.47.0 |
| **email-gateway** | 11.39.0 |
| **events-gateway** | 11.34.0 |
| **file-gateway** | 11.38.0 |
| **integration-designer** | 11.62.1 |
| **license** | 11.34.0 |
| **nosql-db-runner** | 11.35.0 |
| **notification-plugin** | 11.41.0 |
| **organization-manager** | 11.38.0 |
| **process-engine** | 11.53.1 |
| **runtime-manager** | 11.46.0 |
| **scheduler-core** | 11.30.0 |
| **task-management-plugin** | 11.42.0 |
| **webhook-gateway** | 11.37.0 |

### AI base components

| Component | 5.11.0 |
| - | - |
| **embedder** | 11.3.1 |
| **knowledgebase-indexer-v2** | 11.3.1 |
| **knowledgebase-rag** | 11.3.1 |
| **doc-parser** | 11.3.1 |

### AI dev-time components

| Component | 5.11.0 |
| - | - |
| **ai-gateway** | 11.39.0 |
| **ai-analyst** | 11.3.1 |
| **ai-assistant** | 11.3.1 |
| **ai-designer** | 11.3.1 |
| **ai-developer** | 11.3.1 |
| **kb-enrichment** | 11.3.1 |
| **planner** | 11.3.1 |

### AI runtime components

| Component | 5.11.0 |
| - | - |
| **agent-builder** | 11.3.1 |
| **ai-architect** | 11.3.1 |
| **data-privacy** | 11.3.1 |
| **doc-converter** | 11.3.1 |
| **dynamic-classifier** | 11.3.1 |
| **evals-judge** | 11.3.1 |
| **speech-to-text** | 11.3.1 |
| **web-crawler** | 11.3.1 |

### AI extensions

| Component | 5.11.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.89.1` for FlowX.AI 5.11.0). The native iOS and Android renderers version independently.

| Component | 5.11.0 |
| - | - |
| **@flowx/angular-sdk** | 11.89.1 |
| **@flowx/angular-theme** | 11.89.1 |
| **@flowx/angular-ui-toolkit** | 11.89.1 |
| **@flowx/react-sdk** | 11.89.1 |
| **@flowx/react-theme** | 11.89.1 |
| **@flowx/react-ui-toolkit** | 11.89.1 |
| **@flowx/react-native-sdk** | 11.89.1 |
| **@flowx/react-native-theme** | 11.89.1 |
| **@flowx/react-native-ui-toolkit** | 11.89.1 |
| **@flowx/core-sdk** | 11.89.1 |
| **@flowx/core-theme** | 11.89.1 |
| **react-saas** | 11.89.1 |
| **iOS renderer** | 11.1.0 |
| **Android renderer** | 11.7.1 |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.11 capabilities. On SaaS they are created and managed automatically.

**Structured template data model** (document and notification templates move to the structured data model):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.sync.out.v1` | document-plugin, notification-plugin → application-manager |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | document-plugin, notification-plugin → application-manager |

**Runtime content import/export** (Knowledge Base and database content):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → ai-platform |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | ai-platform → integration-designer |

**Document classification and ML extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | ai-platform → integration-designer |

### AI Platform packaging

FlowX.AI 5.11 consolidates the AI Platform services into a single **`ai-platform` umbrella chart** (version `11.3.1`). Services that were previously deployed as standalone releases, including `doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, and `evals-judge`, now ship as subcharts of that chart and continue to run under their plain service names. On SaaS this change is applied automatically. The [component versions](#component-versions) section lists each service at its effective `11.3.1` version.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.11.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026

What's new in FlowX.AI 5.11: workflow tools and agentic RAG on Custom Agents, per-Knowledge-Base embedding models, document classification, extended response caching, subworkflow data mapping, structured template data models, and chat and UI Flow renderer improvements.

[FlowX.AI 5.11 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.11.0.html)

> [!NOTE]
>
> **FlowX.AI 5.11 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.11** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release turns Custom Agents into orchestrators that call FlowX workflows as tools and search knowledge bases agentically, adds per-Knowledge-Base embedding models with local embedders for personal-information content, and introduces document classification. It also extends response caching and subworkflow data mapping in the Integration Designer, moves document and notification templates onto the structured data model, and adds chat notifications, session ownership, and richer runtime audit to the renderers.

### What changed since 5.10.0

| 5.10.0 | 5.11.0 |
| - | - |
| Custom Agents call MCP servers, built-in tools, web search, and Knowledge Bases | + **FlowX workflows as callable tools** on a Custom Agent, with per-tool usage hints and tool-calling caps |
| Knowledge Base retrieval is a plain vector search on the org default embedding model | + **Agentic knowledge base search** and **per-KB embedding models**, including keyless local embedders for personal-information content |
| REST caching covers GET; SQL operations are cacheable | + **POST** REST responses, **file-storage** reads, and **Mongo** reads are cacheable too |
| Subworkflow input/output is raw JSON | + **Input and output mappers** on the Subworkflow node, with per-mapping test and import/export |
| Document and notification templates use a free-form key/value Data model tab | + Templates use the **structured data model** with typed attributes, validators, and Input Parameters |

***

**What's new?**

> [tab] AI & Agents
>
> 🧰 [**Workflow tools on Custom Agents**](#workflow-tools-on-custom-agents) - Attach FlowX workflows as callable agent tools, with usage hints and tool-calling caps\
> 🔎 [**Agentic knowledge base search and Show Reasoning**](#agentic-knowledge-base-search-and-show-reasoning) - Query decomposition, relevance grading, and a reasoning summary in the run log\
> 🧠 [**Per-knowledge-base embedding models**](#per-knowledge-base-embedding-models) - Pick an embedding model per KB and keep personal-information content on a local embedder\
> 🗂️ [**Knowledge Base content lifecycle**](#knowledge-base-content-lifecycle) - Delete entries by metadata filter, structured failure handling, per-chunk timestamps\
> 🏷️ [**Document classification**](#document-classification) - Train or import a classifier and route document pages in a workflow\
> 💬 [**Conversational chat reply requirement**](#conversational-chat-reply-requirement) - A conversational run that never replies to chat now fails with a clear error\
> ✍️ [**Custom Agent instruction limit**](#custom-agent-instruction-limit) - The Instructions field is capped at 10,000 characters

> [tab] Integrations & Data
>
> 🔁 [**Reusable functions in Integration Designer**](#reusable-functions-in-integration-designer) - Call reusable functions from Script and Condition (Fork) nodes\
> ⚡ [**Extended response caching**](#extended-response-caching) - Cache POST REST, file-storage reads, and Mongo reads alongside GET and SQL\
> 🔗 [**Subworkflow data mapping**](#subworkflow-data-mapping) - Map data in and out of a subworkflow with input and output mappers\
> 📎 [**Email attachment filtering by extension**](#email-attachment-filtering-by-extension) - Filter attachments by individual file extension instead of broad categories

> [tab] Platform
>
> 🧱 [**Structured data model for templates**](#structured-data-model-for-templates) - Document and notification templates use typed attributes and Input Parameters\
> ✅ [**Data model attribute validators**](#data-model-attribute-validators) - Required, min/max, length, pattern, email, items, and currency rules on attributes\
> 🧾 [**UI Flow runtime audit**](#ui-flow-runtime-audit) - Audit workflow-instance runs, chat messages, conversation reads, and process renders\
> 📤 [**Cross-version export adaptation**](#cross-version-export-adaptation) - Exports adapt UI templates for older LTS targets by removing unsupported handlers\
> 🔐 [**Platform and runtime improvements**](#platform-and-runtime-improvements) - Runtime access-control hardening

> [tab] Renderers & UI Flows
>
> 🔔 [**Chat notifications and conversation search**](#chat-notifications-and-conversation-search) - Unread-message badge on the chat button and search across conversation history\
> 🚫 [**Disable chat input on a condition**](#disable-chat-input-on-a-condition) - A business condition can make the chat input read-only\
> 🧭 [**Navigate To form validation**](#navigate-to-form-validation) - Require form validation before a Navigate To action, on web, iOS, and Android\
> ⌛ [**Expired UI Flow sessions**](#expired-ui-flow-sessions) - Expired sessions show a session-expired screen with a start-fresh option\
> 👤 [**UI Flow session owner**](#ui-flow-session-owner) - Restrict a running session to a single user\
> 🏁 [**Process Renderer process-end handling**](#process-renderer-process-end-handling) - Run a configurable action when an embedded process ends\
> 🎛️ [**Renderer improvements**](#renderer-improvements) - Batched enumeration fetch and process-start loader alignment

### **Workflow tools on Custom Agents**

> [card] Attach FlowX workflows as callable tools on a Custom Agent
>
> > [tab] Overview
> >
> > **Before 5.11:** a Custom Agent's tools were MCP servers, built-in tools, web search, and Knowledge Base retrieval. **Now:** you can also attach FlowX workflows as callable tools.
> >
> > In the Custom Agent node's **Tools** section, add a workflow as a tool and fill the per-tool **When should the agent use this workflow?** hint that tells the agent when to call it. The agent calls the workflow like any other tool, passing arguments that match the workflow's Start-node input parameters. A workflow with no input parameters cannot be attached. Each tool call starts a fresh workflow run whose output returns to the agent, and the child run is linked in the console log.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Workflows as tools
> > >
> > > Attach up to ten workflows as tools on one Custom Agent, each with a usage hint the agent reads when deciding to call it.
> >
> > > [card] Typed arguments
> > >
> > > The agent passes arguments that match the workflow's Start-node input parameters; workflows without input parameters are not eligible.
> >
> > > [card] Tool-calling limits
> > >
> > > An agent is limited in how many tool calls it can make per run, and workflow-tool call chains are depth-limited so recursion cannot run away.
> >
> > > [card] Linked runs
> > >
> > > Each workflow tool call is a fresh run whose output returns to the agent and is linked in the console log.
>
> SaaS

### **Agentic knowledge base search and Show Reasoning**

> [card] Agentic knowledge base search and reasoning summaries
>
> > [tab] Overview
> >
> > The Custom Agent node gains **agentic knowledge base search** and a **Show Reasoning** toggle.
> >
> > With agentic search on, the agent breaks a question into sub-queries, retrieves and grades results for relevance, and retries with reworded queries if the first pass finds nothing. It is better on complex questions and uses more model calls; a single pass with three sub-queries is the default. Agentic search never returns worse results than plain retrieval. **Show Reasoning** captures the model's reasoning summary in the run and console log; the structured response and the chat reply shown to the user are unchanged.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Agentic search
> > >
> > > Turn on **Enable agentic knowledge base search**, then set **Max attempts** and **Subqueries per attempt** under Settings.
> >
> > > [card] Relevance grading
> > >
> > > Retrieved candidates are graded against the original question, with corrective retries until a relevant result is found or the attempt budget is spent.
> >
> > > [card] Show Reasoning
> > >
> > > Surface the model's reasoning in the run log without changing the answer returned to the user.
> >
> > > [card] Fail-open
> > >
> > > Agentic mode returns the same chunk metadata as plain retrieval, so citations and telemetry are unchanged.
>
> SaaS

### **Per-knowledge-base embedding models**

> [card] Per-KB embedding models and local embedders for personal information
>
> > [tab] Overview
> >
> > Knowledge Bases can now use a **per-KB embedding model**, and a KB that holds personal information can keep its content on a local embedder.
> >
> > Turn on **Containing Personal Information** on a Knowledge Base to enable a local embedding model, then pick one from the **Embedding model** list. Local embedders (for example a text-embedding-inference or Ollama endpoint, or any OpenAI-compatible endpoint) are configured as a single **CUSTOM** provider in the organization AI settings, with a free-form base URL and no API key. The embedding model is set before the first store and cannot be changed afterward. Non-personal-information Knowledge Bases use the organization's default embedding model.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See the Knowledge Base documentation.
>
> > [tab] Key Features
> >
> > > [card] Per-KB model
> > >
> > > Each Knowledge Base carries its own embedding-model reference; a new Settings tab shows the current model.
> >
> > > [card] Local embedders
> > >
> > > Keep personal-information content on-box using a keyless local embedder fronted by a CUSTOM AI provider.
> >
> > > [card] Model travels with export
> > >
> > > Project version export preserves the KB's embedding-model reference, so a re-import keeps the same model.
> >
> > > [card] Set once per KB
> > >
> > > A Knowledge Base's embedding model is chosen before its first store and cannot be changed afterward.
>
> SaaS

### **Knowledge Base content lifecycle**

> [card] Delete entries by filter, structured failure handling, and per-chunk timestamps
>
> > [tab] Overview
> >
> > The **Update Knowledge Base** node gains a **Delete entries** operation and structured failure handling, and retrieval results now carry per-chunk metadata.
> >
> > **Delete entries** soft-deletes chunks whose entry-level metadata matches a filter, in one store or across the Knowledge Base; an empty or match-all filter is rejected so a misconfigured node cannot wipe a store. When an update operation fails, the node's **FAIL** branch returns a structured output with the operation, store, failure reason, and how many chunks were rolled back, and any partial changes are reversed. Retrieval results now include a per-chunk identifier and an ingestion timestamp.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > >
> > > See the Managing Knowledge Base content documentation.
>
> > [tab] Key Features
> >
> > > [card] Filtered deletion
> > >
> > > Delete entries by metadata filter from a workflow, with an empty or match-all filter rejected as a safety guard.
> >
> > > [card] Failure output with rollback
> > >
> > > The FAIL branch reports the operation, store, reason, and rolled-back chunk count; partial changes are reversed.
> >
> > > [card] Per-chunk timestamps
> > >
> > > RAG results carry a chunk identifier and an ingestion timestamp (empty for chunks indexed before this shipped).
> >
> > > [card] Clear retry signal
> > >
> > > Retryable failures such as extraction or chunking errors are distinguished from non-retryable ones such as size or timeout.
>
> SaaS

### **Document classification**

> [card] Classify document pages with a trainable ML model
>
> > [tab] Overview
> >
> > FlowX.AI adds **Document Classifiers**: deterministic ML models that sort document pages into categories. Define classes, upload training data, and train or import a model, then route each page in a workflow with the new **Document Classification** node.
> >
> > The node runs the active model over a document, returns a predicted label and probability per page with a configurable confidence threshold, and flags low-confidence pages. A page-level failure does not fail the node.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer documentation.
>
> > [tab] Key Features
> >
> > > [card] Train or import
> > >
> > > Build classes and training data in the Designer, then train a model or import a pre-trained one.
> >
> > > [card] Per-page classification
> > >
> > > The Document Classification node returns a label and probability for each page, with a confidence threshold and low-confidence flags.
> >
> > > [card] Deterministic routing
> > >
> > > Combine the node with a condition to route pages by their predicted category.
> >
> > > [card] Resilient runs
> > >
> > > A page that cannot be classified is reported per page without failing the whole node.
>
> SaaS

### **Conversational chat reply requirement**

> [card] Conversational runs must reply to chat
>
> A conversational (chat-driven) workflow must send at least one chat reply, either from a Custom Agent node with **Send as Chat Reply** on or from a Navigate in UI Flow node that completes the turn. A run that reaches the end without replying now fails with a clear error instead of ending silently.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **Custom Agent instruction limit**

> [card] Instructions field capped at 10,000 characters
>
> The Custom Agent **Instructions** field is now limited to 10,000 characters.
> SaaS

### **Reusable functions in Integration Designer**

> [card] Call reusable functions from Script and Condition (Fork) nodes
>
> Reusable functions can now be called from **Script** nodes and **Condition (Fork)** nodes in the Integration Designer, not just from Business Rule actions in processes. Functions are referenced in the node's JavaScript or Python and resolved at runtime from the app version's function copies, including functions that call other functions and cross-app references. A Fork node resolves the references used across all of its branch conditions.
>
> For more information, see the [reusable functions](/5.9/docs/building-blocks/reusable-resources/reusable-functions) documentation.
> SaaS

### **Extended response caching**

> [card] Cache POST REST, file-storage reads, and Mongo reads
>
> > [tab] Overview
> >
> > Response caching in the Integration Designer now covers more operation types. **POST** REST endpoints are cacheable alongside GET, with the request body forming part of the cache key so different bodies cache separately. Read **file-storage** operations (LIST and DOWNLOAD) and read **Mongo** operations (FIND, FIND\_ONE, AGGREGATE) are cacheable alongside SQL. Mutating operations are never cached.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] POST caching
> > >
> > > Cache POST responses, keyed on the request body so distinct requests stay separate.
> >
> > > [card] File-storage reads
> > >
> > > LIST and DOWNLOAD operations are cacheable; UPLOAD, DELETE, and MOVE are not.
> >
> > > [card] Mongo reads
> > >
> > > FIND, FIND\_ONE, and AGGREGATE are cacheable alongside SQL; mutating Mongo operations are not.
> >
> > > [card] Shared policy
> > >
> > > All cacheable surfaces reuse the same time-based expiry and per-operation clear-cache action.
>
> SaaS

### **Subworkflow data mapping**

> [card] Map data in and out of a subworkflow with input and output mappers
>
> > [tab] Overview
> >
> > The **Subworkflow** node adds data mapping as an alternative to raw JSON. Turn on **Enable data mapping** to define an **Input mapping** per subworkflow start node and an **Output mapping** per end node, mapping individual data slices instead of hand-editing JSON. Output mapping does not apply to asynchronous subworkflows. Each mapping opens a mapper with a test action, and mappings travel with import, export, and clone.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] Input and output mappers
> > >
> > > Map data into the subworkflow per start node and out of it per end node, without editing raw JSON.
> >
> > > [card] Per-mapping test
> > >
> > > Test a mapping with source and target slices and apply values from a past instance.
> >
> > > [card] Travels with the project
> > >
> > > Mappings are preserved on import, export, and clone.
> >
> > > [card] Async-aware
> > >
> > > Output mapping is hidden for asynchronous subworkflows, which do not return data to the caller.
>
> SaaS

### **Email attachment filtering by extension**

> [card] Filter email attachments by individual file extension
>
> Email Trigger and Microsoft Outlook data sources now filter attachments by **individual file extension** instead of the five broad file-type categories. Choose the exact extensions to accept and to forward into a process. Existing category selections are migrated to their individual extensions automatically on upgrade, so current triggers keep working.
>
> For more information, see the [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger) documentation.
> SaaS

### **Structured data model for templates**

> [card] Document and notification templates use the structured data model
>
> > [tab] Overview
> >
> > **Before 5.11:** document and notification templates declared parameters in a free-form key/value Data model tab. **Now:** templates use the same structured data model as the rest of the platform.
> >
> > On the **Data Model** tab you define typed attributes with validations, sensitive-data and reporting flags, and references to project or library data types. On the **Input Parameters** tab you select which attributes the template expects. Values sent in the request are substituted for those attributes at generation time.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > >
> > > See the notification templates documentation.
>
> > [tab] Key Features
> >
> > > [card] Typed attributes
> > >
> > > Define string, number, boolean, enum, date, currency, object, and array attributes with validations.
> >
> > > [card] Input Parameters
> > >
> > > Pick the attributes the template expects on a dedicated Input Parameters tab.
> >
> > > [card] Reference shared types
> > >
> > > Reference project and library data types like other resources.
> >
> > > [card] OTP unchanged
> > >
> > > The OTP flow contract is unchanged; the reserved `otpValue` and request `data` object work as before.
>
> SaaS

### **Data model attribute validators**

> [card] Validators on data model attributes
>
> Data model attributes now support validators. Available rules depend on the attribute type and include **Required**, **Min/Max Value**, **Min/Max Length**, **Pattern**, **Email Format**, and **Min/Max Items**, plus currency-specific amount and code rules. Validators are stored on the attribute and apply wherever that data model is used, including project, process, template, and reusable UI template data models.
>
> For more information, see the [project data model](/5.9/docs/building-blocks/project-data-model) documentation.
> SaaS

### **UI Flow runtime audit**

> [card] Audit UI Flow runtime activity
>
> UI Flow runtime sessions are now audited in more detail. The audit log records **workflow-instance** runs, chat **message sends**, conversation **list** and **history** reads, and whether the Process Renderer performed a **render** or a start. Entries name the app and the workflow instance.
>
> For more information, see the [audit](/5.9/docs/platform-deep-dive/core-extensions/audit) documentation.
> SaaS

### **Cross-version export adaptation**

> [card] Exports adapt UI templates for older LTS targets
>
> When you export a project to an older platform version, UI-template features the target version cannot understand are removed during down-adaptation, so the export imports cleanly. This currently covers Process Renderer process-end event handlers and the Navigate To **forms to validate** setting.
>
> For more information, see [Cross-version export and import](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
> All Deployments

### **Platform and runtime improvements**

> [card] Runtime access-control hardening
>
> Runtime API requests are now authorized against the roles defined in the running build across start-process, start-workflow, task views, conversation history, and the public runtime API. Requests without a matching build role are denied, and enforcement is on by default.
> All Deployments

> [card] Theme import no longer duplicates system icons
>
> Exporting a theme no longer includes duplicate copies of built-in system icons, and importing a theme no longer creates new ones. Duplicate icon copies that accumulated in earlier versions are cleaned up automatically on upgrade — no action is required.
> All Deployments

### **Chat notifications and conversation search**

> [card] Unread-message badge and conversation search in chat
>
> > [tab] Overview
> >
> > The chat floating action button gains an **unread-message notification badge**, with a themeable **Notification Dot** you can position in the chat style panel. The chat panel also adds **search across conversation history**, which filters conversations by a text query, highlights matches, and shows an empty state when nothing matches.
> >
> > For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
>
> > [tab] Key Features
> >
> > > [card] Unread badge
> > >
> > > The chat button shows a badge with the unread agent-message count; it is hidden while the chat is open in full screen.
> >
> > > [card] Notification Dot
> > >
> > > Position and size the notification dot from the chat style panel, with theme support.
> >
> > > [card] Conversation search
> > >
> > > Search conversation history from the chat panel, with highlighted matches and an empty state.
>
> SaaS

### **Disable chat input on a condition**

> [card] Make the chat input read-only with a business condition
>
> The chat **Input** component can be disabled by a business-condition expression. When the condition evaluates true, the input becomes read-only with an explanatory tooltip, and any pending attachments and voice input are cleared.
>
> For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
> SaaS

### **Navigate To form validation**

> [card] Require form validation before a Navigate To action
>
> A **Navigate To** action can now require selected forms to pass validation before navigating, matching how Start Process and Start Workflow actions gate on validation. This is available on web, iOS, and Android.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Expired UI Flow sessions**

> [card] A session-expired screen with a start-fresh option
>
> Expired UI Flow sessions now show a **session-expired** screen with a start-fresh option instead of leaving the previous data visible in read-only form. Expired and unauthorized access is written to the audit log.
> SaaS

### **UI Flow session owner**

> [card] Restrict a running session to a single user
>
> A UI Flow can restrict a running session to a single owner. When **Allow multiple editors** is off, other users who try to open the session are shown an access-denied screen, and unauthorized access is audited. Newly created flows default to single-owner; imported and existing flows keep the previous shared behavior. A session-owner value type is available for permission-based hide and disable rules.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Process Renderer process-end handling**

> [card] Run a configurable action when an embedded process ends
>
> The Process Renderer can now run a configurable action when its embedded process ends, using a new process-end trigger on event handlers. Configure what happens at that point instead of leaving the renderer idle when the process completes.
>
> For more information, see [Process end handling](/5.9/docs/building-blocks/ui-flows#process-end-handling).
> SaaS

### **Renderer improvements**

> [card] Renderer performance and behavior
>
> * **Batched enumeration fetch:** renderers batch enumeration lookups into a single bulk request, cutting the number of calls when rendering enum-backed fields. Applies to web and mobile renderers.
> * **Process-start loader alignment:** the web renderer keeps the process-start loader visible until the first user task, matching the mobile SDKs.
>   SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

FlowX.AI 5.11 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.11 deployment guidelines](./deployment-guidelines-v5.11).


# Deployment guidelines v5.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12

Component versions and deployment notes for FlowX.AI 5.12 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.12 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.12.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.12.0 |
| - | - |
| **admin** | 11.69.2 |
| **advancing-controller** | 11.46.0 |
| **application-manager** | 11.68.3 |
| **audit-core** | 11.44.1 |
| **authorization-system** | 11.53.2 |
| **cms-core** | 11.61.1 |
| **data-search** | 11.44.1 |
| **data-sync** | 11.43.1 |
| **designer** | 11.126.1 |
| **document-plugin** | 11.68.1 |
| **email-gateway** | 11.58.1 |
| **events-gateway** | 11.49.2 |
| **file-gateway** | 11.55.1 |
| **integration-designer** | 11.90.2 |
| **license** | 11.48.1 |
| **nosql-db-runner** | 11.49.1 |
| **notification-plugin** | 11.61.2 |
| **organization-manager** | 11.53.1 |
| **process-engine** | 11.76.1 |
| **runtime-manager** | 11.68.3 |
| **scheduler-core** | 11.45.1 |
| **task-management-plugin** | 11.59.2 |
| **webhook-gateway** | 11.54.1 |

### AI base components

| Component | 5.12.0 |
| - | - |
| **embedder** | 11.5.0 |
| **knowledgebase-indexer-v2** | 11.5.0 |
| **knowledgebase-rag** | 11.5.0 |
| **doc-parser** | 11.5.0 |

### AI dev-time components

| Component | 5.12.0 |
| - | - |
| **ai-gateway** | 11.53.1 |
| **ai-analyst** | 11.5.0 |
| **ai-assistant** | 11.5.0 |
| **ai-designer** | 11.5.0 |
| **ai-developer** | 11.5.0 |
| **kb-enrichment** | 11.5.0 |
| **planner** | 11.5.0 |

### AI runtime components

| Component | 5.12.0 |
| - | - |
| **agent-builder** | 11.5.0 |
| **ai-architect** | 11.5.0 |
| **data-privacy** | 11.5.0 |
| **doc-converter** | 11.5.0 |
| **dynamic-classifier** | 11.5.0 |
| **evals-judge** | 11.5.0 |
| **speech-to-text** | 11.5.0 |
| **web-crawler** | 11.5.0 |

### AI extensions

| Component | 5.12.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.126.1` for FlowX.AI 5.12.0). The native iOS and Android renderers version independently.

| Component | 5.12.0 |
| - | - |
| **@flowx/angular-sdk** | 11.126.1 |
| **@flowx/angular-theme** | 11.126.1 |
| **@flowx/angular-ui-toolkit** | 11.126.1 |
| **@flowx/react-sdk** | 11.126.1 |
| **@flowx/react-theme** | 11.126.1 |
| **@flowx/react-ui-toolkit** | 11.126.1 |
| **@flowx/react-native-sdk** | 11.126.1 |
| **@flowx/react-native-theme** | 11.126.1 |
| **@flowx/react-native-ui-toolkit** | 11.126.1 |
| **@flowx/core-sdk** | 11.126.1 |
| **@flowx/core-theme** | 11.126.1 |
| **react-saas** | 11.126.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.12 capabilities. On SaaS they are created and managed automatically.

**Event-triggered workflows** (email and webhook triggers can start an integration workflow):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Deep Research node** (the node hands research jobs to the AI Platform over Kafka):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | dead-letter queue for failed research jobs |

**Bulk process-instance migration:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |

**Notifications:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.eventsgateway.user.notifications.v1` | application-manager, process-engine → events-gateway |

**Document classification:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → dead-letter sink (not consumed) |

### New service dependency: webhook-gateway and MongoDB

The webhook gateway now reads the runtime registry that backs event-triggered workflows, so it depends on the runtime MongoDB database in addition to its existing relational database. On SaaS this connection is provisioned and managed by FlowX.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map. | none (required) | integration-designer |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today. | `k1` | integration-designer |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index. | `PT24H` | integration-designer |

### Native PostgreSQL partitioning for the engine

On PostgreSQL, the engine converts its runtime tables to native `RANGE(partition_id)` partitioning the first time it starts on the new version, and archiving then detaches a partition instead of copying rows out of it. Deployments that never enabled partitioning are skipped entirely, and Oracle deployments are unaffected.

Unlike most 5.12 changes, this one also reaches self-hosted 5.9.x in the 5.9.5 patch rather than waiting for the next LTS release family.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Whether archiving detaches partitions with `DETACH CONCURRENTLY` on natively partitioned tables. Setting it to `false` returns archiving to the previous batched insert-and-delete, but does not undo the conversion: the tables stay natively partitioned. | `true` | process-engine |

For the conversion cost, table locking and the one-way caveat, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.12.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026

What's new in FlowX.AI 5.12: parallel multi-instance subworkflow fan-out, event-triggered integration workflows, bulk process-instance migration, personal-data mask and restore nodes, and a Db2 data source.

[FlowX.AI 5.12 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.12.0.html)

> [!NOTE]
>
> **FlowX.AI 5.12 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.12** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release lets an integration workflow fan out over a collection without a subprocess, starts workflows directly from email and webhook events, and migrates process instances to a new build in bulk. It also adds personal-data mask and restore nodes to the Integration Designer and a Db2 relational data source.

### What changed since 5.11.0

| 5.11.0 | 5.12.0 |
| - | - |
| A workflow ran once per call; fanning out over a collection needed a BPMN Call Activity and a subprocess | + **Multi-instance subworkflow node** fans a workflow over a collection directly in the Integration Designer |
| An email or webhook trigger could start a process | + **Event-triggered workflows** start an integration workflow from the same triggers |
| Process instances migrated to a new build one at a time | + **Bulk migration** moves a filtered set of instances in one operation |
| Personal-data handling was configured on the agent | + **Mask and restore nodes** place it as explicit workflow steps, with details in the run log |

***

**What's new?**

> [tab] Integrations & Data
>
> 🔀 [**Multi-instance subworkflow node**](#multi-instance-subworkflow-node) - Fan a workflow out over a collection\
> ⚡ [**Event-triggered workflows**](#event-triggered-workflows) - Start a workflow from an email or webhook\
> 🗄️ [**Db2 relational data source**](#db2-relational-data-source) - Connect to Db2 for i or Db2 LUW\
> 🔻 [**Subworkflow failure exit**](#subworkflow-failure-exit) - Send a failed mapping down its own branch\
> 🔓 [**Skip TLS verification on a REST data source**](#skip-tls-verification-on-a-rest-data-source) - Reach a trusted internal host with an untrusted certificate\
> 🔔 [**Send Notification node**](#send-notification-node) - Send a templated notification straight from a workflow

> [tab] AI Platform
>
> 🛡️ [**Personal-data mask and restore nodes**](#personal-data-mask-and-restore-nodes) - Explicit workflow steps with run-log detail\
> 🧩 [**Reusable functions as agent tools**](#reusable-functions-as-agent-tools) - Give an agent a deterministic function to call\
> 👍 [**Chat response feedback**](#chat-response-feedback) - Let users rate an agent's answer, and theme how it looks\
> 📏 [**Custom evaluators**](#custom-evaluators) - Score an agent against a rubric you write yourself\
> 🔍 [**Deep Research node**](#deep-research-node) - Research a question across the open web and file a cited report\
> 🛠️ [**Built-in agent tools by category**](#built-in-agent-tools-by-category) - Twenty ready-made tools an agent can use, picked by category\
> 🪄 [**AI Designer builds UI Flows**](#ai-designer-builds-ui-flows) - Generate and edit multi-page UI Flows from a description

> [tab] Platform
>
> 📦 [**Bulk process-instance migration**](#bulk-process-instance-migration) - Move a filtered set of instances to a new build\
> 🔎 [**Runtime list filters and a Workflow Instances page**](#runtime-list-filters-and-a-workflow-instances-page) - Find the failed run without scanning the list\
> 🎨 [**Process canvas editing**](#process-canvas-editing) - Connect, reshape and resize more directly on the BPMN canvas\
> ⚠️ [**Check a version for issues**](#check-a-version-for-issues) - Validate every workflow in the version from one panel\
> 🧱 [**Reusable UI Templates in UI Flows**](#reusable-ui-templates-in-ui-flows) - Reuse a template on UI Flow pages, not just User Tasks\
> 🌿 [**Branch management**](#branch-management) - Merge to any branch, archive or delete the ones you are done with

### **Multi-instance subworkflow node**

> [card] Multi-instance subworkflow node
>
> > [tab] Overview
> >
> > **Before 5.12.0:** running an integration workflow once per item in a collection meant leaving the Integration Designer, wrapping the workflow in a BPMN process and fanning out with a multi-instance Call Activity. **Now:** the Subworkflow node fans out over an array on its own, in parallel.
> >
> > Turn on **Parallel Multi-Instance** under **Execution** on a Subworkflow node, pick the **Input Array** to iterate, and pick the **Output Array** that collects each run's result. The node starts one subworkflow instance per element of the input array and gathers the results into the output array on the parent workflow.
>
> > [tab] Key Features
> >
> > > [card] Input Array
> > >
> > > The array of objects to iterate. One subworkflow instance starts per element. Required.
> >
> > > [card] Output Array
> > >
> > > The array each instance result is collected into. Required.
> >
> > > [card] Correlation attribute
> > >
> > > Optional. Decides which output array element each result updates. Results matching no element, or all results when no attribute is set, are appended.
> >
> > > [card] Runs in parallel
> > >
> > > Instances run in parallel, and fan-out stays inside the Integration Designer instead of requiring a BPMN Call Activity.
>
> For the full configuration reference, see [Parallel multi-instance](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) on the Subworkflow node.
> SaaS

### **Event-triggered workflows**

> [card] Event-triggered workflows
>
> > [tab] Overview
> >
> > **Before 5.12.0:** an incoming email or webhook could start a process. **Now:** the same triggers can start an integration workflow directly.
> >
> > A workflow declares the trigger it listens for, and the platform keeps a subscription registry so a change to that trigger takes effect without rebuilding the whole app. Incoming email and webhook events are routed to the workflow that subscribes to them.
>
> > [tab] Key Features
> >
> > > [card] Email and webhook triggers
> > >
> > > Both trigger types can start a workflow, not only a process.
> >
> > > [card] Subscription registry
> > >
> > > Trigger changes update the affected data source without a full build recompute.
>
> > [tab] Architecture
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Trigger subscription changes | admin, integration-designer, application-manager | Design-time changes update the runtime subscription registry |
> > | Event delivery | email-gateway, webhook-gateway, integration-designer | Events are routed to the subscribing workflow |
> > | Webhook state | webhook-gateway | The webhook gateway now also reads the runtime registry, adding a MongoDB dependency it did not previously have |
> >
> > On SaaS these changes are applied automatically. See [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12) for the topic and dependency detail.
>
> For the full configuration reference, see [External triggers](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers) on the Start node.
> SaaS

### **Bulk process-instance migration**

> [card] Bulk process-instance migration
>
> > [tab] Overview
> >
> > **Before 5.12.0:** moving running process instances onto a new build was a one-at-a-time operation. **Now:** a filtered set of instances migrates in a single run.
> >
> > Select the target build, filter the instances to move, check the migration for problems before committing to it, and then run it. Progress and per-instance outcomes are available while it runs, and terminated instances are handled explicitly rather than failing the batch.
> >
> > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > See migrating process instances.
>
> > [tab] Key Features
> >
> > > [card] Filter then migrate
> > >
> > > Move specific instance UUIDs, the instances matching a process, node and status filter, or every eligible instance.
> >
> > > [card] Pre-flight check
> > >
> > > Validate a migration before running it.
> >
> > > [card] Per-instance outcomes
> > >
> > > Inspect details and results for the instances in a batch.
> >
> > > [card] Audit trail
> > >
> > > Migrations are recorded against the instances they touch.
>
> For the full configuration reference, see the [Migrate process instances](/5.9/docs/projects/runtime/active-process/migrate-process-instances) documentation.
> SaaS

### **Runtime list filters and a Workflow Instances page**

> [card] Runtime list filters and a Workflow Instances page
>
> Finding a failed run no longer means scanning an unfiltered list. The **Process Instances** and **UI Flow Sessions** lists gain a multi-select **Status** filter and a start-date filter on their columns, so "every failed instance since last night" is two clicks.
>
> Workflow runs get more: a new **Workflow Instances** page under **Runtime** lists every run in the project, filterable by **Status**, by date, and by **Origin**: whether a run was started by a process, a UI Flow, a webhook, or an email trigger. Until now, a workflow's runs were only visible from inside that workflow in the Integration Designer.
>
> For details, see the [Workflow Instances](/5.9/docs/projects/runtime/workflow-instances) documentation.
> SaaS

***

### **Personal-data mask and restore nodes**

> [card] Personal-data mask and restore nodes
>
> > [tab] Overview
> >
> > **Before 5.12.0:** personal-information handling was configured on the agent rather than placed in the flow. **Now:** masking and restoring personal data are workflow nodes you position explicitly, and you choose which key from the node input they apply to.
> >
> > Put a mask node before the step that must not see the raw values and a restore node after it. The workflow run log shows what each node did, so a run can be inspected without exposing the underlying data.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See the Personal Information Guard documentation.
>
> > [tab] Key Features
> >
> > > [card] Mask and restore as nodes
> > >
> > > Personal-data handling becomes an explicit step in the workflow.
> >
> > > [card] Selectable input key
> > >
> > > Choose which key from the node input the node applies to.
> >
> > > [card] Run-log detail
> > >
> > > A restore reports whether it completed, partially completed or failed, and how many of the issued placeholders it put back.
>
> For the full configuration reference, see [Masking and restoring across several nodes](/5.9/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
> SaaS

### **Db2 relational data source**

> [card] Db2 relational data source
>
> IBM Db2 joins the relational database data sources available in the Integration Designer. Because Db2 products use different drivers, ports and catalogs, the connection starts with a **Db2 Product** choice and the rest of the form follows from it. **Db2 for i (IBM i)** is the default and **Db2 LUW** is also supported. **Db2 for z/OS** appears in the list but is not implemented in this release, and selecting it fails with an explicit error rather than falling back to another driver.
>
> The port is prefilled from the product and whether SSL is on. Db2 for i adds a naming convention, an optional library and library list, and a switch for returning character data that the host reports as binary. On Db2 for i, connections also open **read-only by default**, so turn that off if your queries need to write, and the transaction isolation level defaults to none, because a table without a journal cannot take part in a transaction. Isolation is validated when the data source is saved rather than when a query first runs.
>
> For the full configuration reference, see the [Db2 Database](/5.9/docs/platform-deep-dive/integrations/db2-database) documentation.
> SaaS

***

### **Subworkflow failure exit**

> [card] Subworkflow failure exit
>
> A Subworkflow node now has a second exit. Connect the red one and a failure takes its own branch instead of stopping the parent workflow. It is opt-in per node, so a node without that branch fails and blocks exactly as before and nothing changes for existing workflows.
>
> Only a mapping failure routes, which is the kind a workflow can be built to handle: the input mapper failing, the input not satisfying what the subworkflow expects, or the output mapper failing on merge-back. An unset subworkflow, a missing response key, no mapping at all, and the node and depth limits all still stop the run. The branch reads a fixed `subWorkflowError` key that says which mapping failed and, when a child did start, which run it was.
>
> For the full configuration reference, see [Routing a subworkflow failure](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
> SaaS

***

### **Skip TLS verification on a REST data source**

> [card] Skip TLS verification on a REST data source
>
> A REST data source can now be told to stop checking the certificate of the host it calls, for the cases where an internal endpoint presents a self-signed or mismatched certificate and the alternative is an infrastructure workaround. It is off by default and set per data source, so turning it on for one connector leaves every other call verified.
>
> The Designer warns while it is on, because the call can no longer tell the intended host from anything intercepting it. One consequence is worth knowing before you use it: a truststore configured under Certificates is ignored while verification is skipped, since skipping replaces it rather than adding to it.
>
> For the full configuration reference, see [TLS verification](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#tls-verification) on a REST data source.
> SaaS

***

### **Send Notification node**

> [card] Send Notification node
>
> Workflows can now send notifications themselves. A **Send Notification** node, under **Tools** in the workflow node palette, takes one of your project's notification templates, fills its variables from workflow data, and sends it, without routing through a process just to reach the Notifications plugin.
>
> Address it with **To**, **Cc** and **Bcc**, as fixed addresses or `${}` keys. Email options are all overridable per node: subject, sender name and email, attachments by file path or `${}` key, and custom headers. The node reports the outcome under its response key, including recipient counts and the error when sending fails, so the workflow can branch on it.
>
> For the full configuration reference, see the [Send Notification node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node) documentation.
> SaaS

***

### **Reusable functions as agent tools**

> [card] Reusable functions as agent tools
>
> An AI node's tools can now include a **Function**, alongside built-in web search, an MCP server, and a workflow. Point an agent at a reusable function when the work is deterministic and you would rather it call your code than reason its way there.
>
> A function has to be typed to qualify: it needs both an input and an output slice, and functions without them do not appear in the picker. Give it a description as well, since that is what tells the agent when to reach for it.
>
> For the full configuration reference, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **Chat response feedback**

> [card] Chat response feedback
>
> Users can rate an agent's answer in the chat component, and follow the rating with a reason. The ratings are recorded in audit, so the quality of a deployed agent becomes something you can look at rather than guess at.
>
> The feedback controls and the reason chips are themable, with their own selected and hover states, so they can be styled to match the rest of the interface. The SDKs expose the same feedback state to custom front ends.
>
> For the full configuration reference, see [Rating an answer](/5.9/ai-platform/chat-component#rating-an-answer) on the chat component.
> SaaS

***

### **Custom evaluators**

> [card] Custom evaluators
>
> The evaluator catalogue is no longer fixed. When none of the built-in rubrics measures what you care about, you can write your own evaluator, give it the scoring instructions the judge LLM should follow, and it appears in the catalogue under a **Custom** group alongside the built-in ones.
>
> Choose **Numeric** scoring for a score between 0 and 1 with a pass threshold, or **Binary** for a straight pass or fail. You can start from an existing evaluator to adapt a built-in rubric rather than writing a prompt from scratch. Custom evaluators belong to the workflow you create them in, and unlike the built-in ones they can be edited and deleted.
>
> For the full configuration reference, see the [Evaluations](/5.9/ai-platform/evaluations#custom) documentation.
> SaaS

***

### **Deep Research node**

> [card] Deep Research node
>
> A new AI node researches a question across the open web and files a cited report into a Knowledge Base. It plans the work, sends sub-researchers out to search and read pages, grades what they bring back, and keeps going until its budget is spent or it has enough to report.
>
> Unlike a Custom Agent, you do not write the method: the research prompt is built into the node, so you describe the subject and bind workflow data into it. Depth is a **Quick**, **Standard** or **Deep** preset, or **Custom** if you want to set the number of passes and tool calls yourself. You can restrict which domains the research may read, with an allow list, a deny list, or both.
>
> The result always lands in a Knowledge Base as text, so retrieval nodes and other agents can reach it later. Rendering it as a document is optional.
>
> For the full configuration reference, see the [Deep Research node](/5.9/docs/platform-deep-dive/integrations/deep-research-node) documentation.
> SaaS

***

### **Built-in agent tools by category**

> [card] Built-in agent tools by category
>
> A Custom Agent's built-in tools are now a catalog you pick from by category: **Math tools**, **List tools**, **Date tools**, **Text tools**, and **Web search**. Each category row shows exactly which tools it turns on, and the agent runs deterministic code for that work instead of estimating it in the model.
>
> The catalog holds twenty tools, fifteen of them new: a full date family (business days, date arithmetic, formatting, parsing, timezone conversion), text helpers (regex match and extract, fuzzy match), unit conversion, and list aggregation, joining the original calculator, compare, sort, and filter. Web search is part of the same catalog rather than a separate toggle.
>
> Selection stays opt-in and per node. Agents saved with the old toggles keep working without an edit.
>
> For details, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **AI Designer builds UI Flows**

> [card] AI Designer builds UI Flows
>
> The AI Designer now works at the level of a whole UI Flow. Describe the journey and it generates a multi-page flow: structure first, pages filled in parallel, navigation wired between them. Ask for a change and it edits the affected pages instead of regenerating everything.
>
> Proposals appear on the UI Flow canvas as a draft for you to review, the editor stays locked while one is pending, and any data-model changes the flow needs are presented for approval on every turn, the same way single-screen generation already works.
>
> For details, see the [AI Designer](/5.9/ai-platform/pre-built-agents/ai-designer#ui-flow-generation-and-editing) documentation.
> SaaS

***

### **Check a version for issues**

> [card] Check a version for issues
>
> The Designer can now validate the resources in a project version and collect what it finds in one **Issues** panel at the bottom of the screen. Findings are marked where they occur, on resource lists, page titles and workflow canvas nodes, and selecting a marker opens the panel on that finding.
>
> Checks run when you ask for one, and the panel says when it last ran so a stale result is obvious. You can scope the list to the whole version, the resource you are in, or the node you have selected, filter it by severity or text, and group it by resource or severity. Opening **Commit Changes to Version** runs a check on its own and shows each changed resource's state beside it, as a review step rather than a gate. Integration workflows are the resource type validated in this first iteration.
>
> For the full configuration reference, see the [Checking a version for issues](/5.9/docs/projects/managing-applications/checking-for-issues) documentation.
> SaaS

***

### **Branch management**

> [card] Branch management
>
> Project branches gained a management layer. The merge modal now offers every branch you can merge into, not just the current branch's parents, so a fix made anywhere can land anywhere it is needed.
>
> Branches you are done with no longer linger: **Archive Branch** retires one (with a required reason, shown later in its info panel), **Unarchive Branch** brings it back, and **Delete Branch** removes one permanently, guarded so it refuses while child branches, an uncommitted draft, or a running merge depend on it, and asks you to type the branch name when unmerged work would be lost. Deleting has its own permission.
>
> Branch and version info panels round it out: a version merged from another branch says where it came from, including whether that branch has since been archived.
>
> For details, see [Managing branches](/5.9/docs/projects/managing-applications/versioning#managing-branches).
> SaaS

***

### **Process canvas editing**

> [card] Process canvas editing
>
> The BPMN canvas gains a set of direct editing improvements. A **New Node** panel and
> drop-anywhere connecting make it quicker to add a node and wire it up, connecting to a nearby
> node no longer means aiming precisely at a handle, and sequence flows can be reshaped by
> dragging their control points. Swimlanes now resize from any of their four edges. The
> process-instance viewer picks up the same canvas.
>
> The canvas is deliberately unchanged to look at, so existing diagrams, habits and screenshots
> still hold.
>
> For the full configuration reference, see [Faster ways to build](/5.9/docs/building-blocks/process/process#faster-ways-to-build) on the Process Designer canvas.
> SaaS

***

### **Reusable UI Templates in UI Flows**

> [card] Reusable UI Templates in UI Flows
>
> A Reusable UI Template can now be built for **UI Flow** pages as well as for the User Tasks in a process. Each template declares where it is used when you create it, and the UI Flow editor can drop templates onto a page the same way the Process editor always could.
>
> The host type also decides which actions a template's event handlers offer, so a template built for UI Flows gets navigation and workflow actions while one built for processes gets node actions. Because of that the choice is fixed once the template exists, and templates you created before this release count as Process templates, so nothing you already built changes.
>
> For the full configuration reference, see [Where a template can be used](/5.9/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used) in the Reusable UI Templates documentation.
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12).


# Deployment guidelines v5.13.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13

Component versions and deployment-level changes for FlowX.AI 5.13.0.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.13 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency. Self-hosted deployments receive these capabilities with the next LTS release family.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.13.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.13.0 |
| - | - |
| **admin** | 11.97.0 |
| **advancing-controller** | 11.67.0 |
| **application-manager** | 11.101.0 |
| **audit-core** | 11.69.0 |
| **authorization-system** | 11.78.0 |
| **cms-core** | 11.88.0 |
| **data-search** | 11.67.0 |
| **data-sync** | 11.68.0 |
| **designer** | 11.168.1 |
| **designer-user** | 11.8.0 |
| **document-plugin** | 11.95.0 |
| **email-gateway** | 11.83.0 |
| **events-gateway** | 11.72.0 |
| **file-gateway** | 11.79.0 |
| **integration-designer** | 11.119.1 |
| **license** | 11.72.0 |
| **nosql-db-runner** | 11.73.0 |
| **notification-plugin** | 11.88.0 |
| **organization-manager** | 11.77.0 |
| **process-engine** | 11.104.0 |
| **runtime-manager** | 11.101.0 |
| **scheduler-core** | 11.69.0 |
| **task-management-plugin** | 11.84.0 |
| **webhook-gateway** | 11.78.0 |

**designer-user** is new in 5.13. It backs the Designer notification center.

### AI base components

| Component | 5.13.0 |
| - | - |
| **embedder** | 11.6.0 |
| **knowledgebase-indexer-v2** | 11.6.0 |
| **knowledgebase-rag** | 11.6.0 |
| **doc-parser** | 11.6.0 |

### AI dev-time components

| Component | 5.13.0 |
| - | - |
| **ai-gateway** | 11.85.0 |
| **ai-analyst** | 11.6.0 |
| **ai-architect** | 11.6.0 |
| **ai-assistant** | 11.6.0 |
| **ai-designer** | 11.6.0 |
| **ai-developer** | 11.6.0 |
| **harness** | 11.6.0 |
| **ai-render-host** | 11.168.1 |
| **kb-enrichment** | 11.6.0 |
| **planner** | 11.6.0 |

**harness** and **ai-render-host** are new in 5.13. Together they run the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness): harness is the agent service, and ai-render-host renders UI flows headlessly for the agent. ai-render-host ships at the designer version.

### AI runtime components

| Component | 5.13.0 |
| - | - |
| **agent-builder** | 11.6.0 |
| **cee-pii** | 11.6.0 |
| **data-privacy** | 11.6.0 |
| **doc-converter** | 11.6.0 |
| **dynamic-classifier** | 11.6.0 |
| **evals-judge** | 11.6.0 |
| **speech-to-text** | 11.6.0 |
| **web-crawler** | 11.6.0 |

### AI extensions

| Component | 5.13.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.10.2 |
| **observatory-platform** | 11.10.2 |
| **observatory-web** | 11.10.2 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.168.1` for FlowX.AI 5.13.0). The native iOS and Android renderers version independently.

| Component | 5.13.0 |
| - | - |
| **@flowx/angular-sdk** | 11.168.1 |
| **@flowx/angular-theme** | 11.168.1 |
| **@flowx/angular-ui-toolkit** | 11.168.1 |
| **@flowx/react-sdk** | 11.168.1 |
| **@flowx/react-theme** | 11.168.1 |
| **@flowx/react-ui-toolkit** | 11.168.1 |
| **@flowx/react-native-sdk** | 11.168.1 |
| **@flowx/react-native-theme** | 11.168.1 |
| **@flowx/react-native-ui-toolkit** | 11.168.1 |
| **@flowx/core-sdk** | 11.168.1 |
| **@flowx/core-theme** | 11.168.1 |
| **react-saas** | 11.168.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

***

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.13 capabilities. On SaaS they are created and managed automatically.

**Notification center:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |

Notifications now pass through designer-user, which stores them and forwards them to events-gateway on the existing `ai.flowx.eventsgateway.user.notifications.v1` topic for delivery to the Designer.

**Move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

### New services

The Developer Agentic Harness adds the **harness** and **ai-render-host** services to the AI dev-time group, with a dedicated PostgreSQL database for harness sessions. The notification center adds the **designer-user** core service, which uses MongoDB, Redis, and Kafka. On SaaS these services and their databases are provisioned and managed by FlowX.

### New service dependency: process-engine and object storage

Oversized workflow responses and UI flow updates are now offloaded to object storage instead of travelling inline on Kafka. The process engine reads these offloaded payloads, so it now depends on object storage in addition to its existing databases. On SaaS this connection is provisioned and managed by FlowX.

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` | process-engine, audit-core |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Self-hosted deployments receive this change with the next LTS release family. A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.13.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026

What's new in FlowX.AI 5.13: a user notification center in Designer, UI component copy and paste across contexts, commit descriptions on app versions, and move token on process instances.

[FlowX.AI 5.13 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.13.0.html)

> [!NOTE]
>
> **FlowX.AI 5.13 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.13** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. The headline: the FlowX Developer Agentic Harness, an AI agent in the Designer that builds and changes apps from a description, with you confirming the plan and every operation before it runs. The release also adds a notification center to the Designer, lets builders copy and paste UI components across apps with a review of what could not be placed, records a description on every app version commit, forwards runtime events to Mixpanel and GA4, and moves stuck tokens on running process instances.

### What changed since 5.12.0

| 5.12.0 | 5.13.0 |
| - | - |
| Apps were assembled by hand in the Designer | + **Developer Agentic Harness**: describe the change, confirm the plan, review the result on its own branch |
| Long-running operations surfaced as passing toasts | + **Notification center** keeps a searchable 30-day history with read state |
| UI components copied within one context | + **Copy and paste across contexts**, with a paste review and unique naming |
| App version commits had a name only | + **Commit descriptions** and a commit details view record why a version exists |
| A stuck process instance needed support intervention | + **Move token** relocates the token, guarded by a dedicated corrective-actions role |

***

**What's new?**

> [tab] Builders
>
> 🔔 [**User notification center**](#user-notification-center) - Bell, searchable history, read state in Designer\
> 📋 [**UI component copy and paste**](#ui-component-copy-and-paste) - Cross-context paste with review and unique naming\
> 📝 [**Commit descriptions and details**](#commit-descriptions-and-details) - Optional description on version commits plus a details view\
> 📦 [**Version export alignment**](#version-export-alignment) - Version exports bundle dependencies like build exports

> [tab] Platform
>
> 🚑 [**Move token and corrective actions**](#move-token-and-corrective-actions) - Relocate a token, gated by a dedicated role

> [tab] AI Platform
>
> 🪄 [**Developer Agentic Harness**](#developer-agentic-harness) - Describe a change, the agent plans and builds it on a branch\
> 🧠 [**ML corpus import and export**](#ml-corpus-import-and-export) - Move a document classifier corpus between environments\
> ⚖️ [**Fair scheduling for embedding jobs**](#fair-scheduling-for-embedding-jobs) - Knowledge Base ingestion no longer starves small jobs\
> 🧩 [**Data Parse node**](#data-parse-node) - Tabular Data Extraction generalized, now parses XML and JSON\
> 🔐 [**File Encryption node**](#file-encryption-node) - Encrypt and decrypt files inside a workflow

> [tab] Rendering & SDKs
>
> 💬 [**React Native chat component**](#react-native-chat-component) - Floating chat sheet with voice input on mobile\
> ▶️ [**Conditional start workflow trigger**](#conditional-start-workflow-trigger) - Start a workflow from the UI only when a condition holds

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > **Before 5.13.0:** every process, screen, and data type was assembled by hand in the Designer. **Now:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys your app first, so changes use your real resources and names, then drafts a plan for you to confirm.
> >
> > You hold every gate: the agent runs only after you confirm the plan and review each operation, the change lands on a dedicated branch that never touches your main line, and merging plus serving a new version stay human decisions. See the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness) page for the full flow.
> >
> > <video>
> >   <track label="English" />
> > </video>
>
> > [tab] Key Features
> >
> > > [card] Works on your real app
> > >
> > > Surveys existing resources first, so changes use your actual processes, data types, and names.
> >
> > > [card] Plan, confirm, then run
> > >
> > > You confirm the plan and review every operation; the change runs on a dedicated branch that only you can merge or serve.
> >
> > > [card] Broad resource coverage
> > >
> > > Creates and edits processes, UI flows, workflows, and project data types.
> >
> > > [card] Guarded operations
> > >
> > > Destructive changes are gated, and runtime data such as process instances is never touched.
>
> SaaS

### **User notification center**

> [card] User notification center
>
> > [tab] Overview
> >
> > **Before 5.13.0:** long-running operations such as app imports or instance migrations announced themselves once and were gone. **Now:** a bell in the Designer opens a notification center with a 30-day history.
> >
> > Notifications carry read state, search, and filters by unread status and workspace type. First producers: app version export and process instance migration results.
>
> > [tab] Key Features
> >
> > > [card] 30-day history
> > >
> > > Notifications persist for 30 days instead of disappearing with the toast.
> >
> > > [card] Read state and search
> > >
> > > Mark notifications read, search them, and filter by unread status or workspace type.
> >
> > > [card] Export and migration results
> > >
> > > Get notified when an app version export finishes, fails, or times out, and when a process instance migration completes.
> >
> > > [card] Live updates
> > >
> > > The center updates over a live stream, including read state changes from other sessions.
>
> SaaS

### **UI component copy and paste**

> [card] UI component copy and paste
>
> > [tab] Overview
> >
> > **Before 5.13.0:** copying UI components was limited to the context you were in. **Now:** builders copy components and paste them into another UI Flow, app, or context.
> >
> > Pasting responds with a review of what could not be placed instead of failing silently, and pasted components receive unique names automatically. The clipboard holds one consistent version of the copied structure.
>
> > [tab] Key Features
> >
> > > [card] Cross-context paste
> > >
> > > Paste a copied component into a different UI Flow or app through a dedicated modal.
> >
> > > [card] Paste review
> > >
> > > The paste result names anything it could not place, so nothing drops without a trace.
>
> SaaS

### **Commit descriptions and details**

> [card] Commit descriptions and details
>
> Committing or merging an app version now takes an optional description of up to 2000 characters, and a commit details view shows what a version contains and why it exists. Version history stops being a list of names.
> SaaS

### **Version export alignment**

> [card] Version export alignment
>
> Project version exports now bundle dependencies the same way build exports do, so a version export is self-contained. The export dialog pre-selects the target platform version, and the exported filename carries the target version and whether media is included.
> SaaS

### **Move token and corrective actions**

> [card] Move token and corrective actions
>
> > [tab] Overview
> >
> > **Before 5.13.0:** a process instance stuck on the wrong node needed support intervention. **Now:** an operator with the corrective-actions role moves the token to the right node from Runtime.
> >
> > Corrective actions, covering bulk instance migration and move token, are gated by a dedicated workspace-level role, so admins grant this power without handing out full admin rights.
> >
> > The **Workspace corrective actions editor** role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically. See [Move tokens](/5.9/docs/projects/runtime/active-process/move-token) and the [Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
>
> > [tab] Key Features
> >
> > > [card] Move token
> > >
> > > Relocate the token of a running instance to another node in the process definition.
> >
> > > [card] Dedicated role
> > >
> > > A workspace-level corrective-actions role scopes who can migrate instances and move tokens.
>
> SaaS

### **ML corpus import and export**

> [card] ML corpus import and export
>
> A document classifier corpus now moves between environments: export the corpus with the model, import it into a runtime classifier, and inspect it in a read-only view in the Data tab. Training data stops being trapped in the environment where labeling happened.
> SaaS

### **Fair scheduling for embedding jobs**

> [card] Fair scheduling for embedding jobs
>
> Knowledge Base embedding jobs are scheduled fairly by default, so a large ingestion no longer starves small jobs queued behind it. Uploads to one Knowledge Base stop delaying every other one on the environment.
> SaaS

### **Data Parse node**

> [card] Data Parse node
>
> The Tabular Data Extraction node is generalized into a **Data Parse** node: it still reads CSV and Excel files into workflow data, and now also parses **XML** and **JSON**. A file fetched by a File Storage Operation can be read into the workflow regardless of its structured format.
> SaaS

### **File Encryption node**

> [card] File Encryption node
>
> A new **File Encryption** workflow node encrypts or decrypts a file with a password directly in the workflow, so protecting a generated document or opening a protected upload no longer needs a custom integration. The file path and password take expressions, letting the password come from workflow data.
> SaaS

### **React Native chat component**

> [card] React Native chat component
>
> The React Native renderer gains the chat experience mobile apps were missing: a floating chat sheet with voice input, suggested prompts, and conversation history. Renderer updates in the same release cover form validation on navigation actions, action context on execute-URL, and bulk enum fetching on eager load.
> SaaS

### **Conditional start workflow trigger**

> [card] Conditional start workflow trigger
>
> A start workflow trigger in the UI now takes a condition, so the workflow starts only when the expression holds. Available in the web SDK and on iOS.
> SaaS

### **Smaller improvements**

> [card] Smaller improvements
>
> **Process details modal:** the process name moves from Settings into a Details modal.
>
> **Document and image sources:** Document and Image UI components share one source configuration. In process user tasks, the new **Document Plugin Path** source takes a Documents plugin `downloadPath` directly, so you no longer need a business rule to build the file URL. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13) for File Preview and the [Download component](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download#file-sources-in-flowx-ai-5-13).
>
> **Sign-up link to solution:** a sign-up link lands new users directly in the right solution.
>
> **Bulk invite:** inviting many users at once gets a reworked flow.
>
> **Task list search on translated labels:** the task list searches, filters, and sorts on the labels it displays, in the viewer's language, for status, enumeration, and substitution-tag columns. See [Search and sort on translated labels](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).&#x20;
>
> **Reserved substitution-tag prefix:** custom substitution tags can no longer start with `sys_`; the prefix is reserved for system tags.&#x20;
> **Intersects operator for array fields:** FlowX Database queries can match documents whose array field shares at least one value with a given list. See [Intersects on array fields](/5.9/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).&#x20;
>
> **Request after PII anonymization in the run log:** AI nodes with the input scan enabled log the request exactly as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/5.9/ai-platform/personal-information-guard#request-after-pii-anonymization).&#x20;
>
> **Elasticsearch replica auto-expansion:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Changed default: Elasticsearch replica auto-expansion](./deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).&#x20;
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.13.0](./deployment-guidelines-v5.13).


# FlowX.AI 5.9.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including the Events Gateway Redis connection-leak fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.2 → 5.9.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.3** is a maintenance release for the 5.9.x LTS:
>
> * **Real-time event delivery:** fixes a Redis connection leak in the Events Gateway that could previously require periodic restarts under sustained load
> * **Key fixes:** build import race during multi-dependency imports, task-management allocation rules, project re-creation error handling
> * **New configuration:** Events Gateway connection-pool tuning and workflow Kafka topic partitions
> * Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.2

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform improvements**](#platform-improvements) - Events Gateway stability, Designer and backend bug fixes, security patches.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Real-time event delivery:** fixed a Redis connection leak in the Events Gateway. Blocking reads now run on a dedicated connection pool with Redis Cluster support, eliminating the gradual connection buildup that could previously require periodic Events Gateway restarts. New tuning options are available — see the [deployment guidelines](./deployment-guidelines-v5.9.3#configuration-changes).
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it, and duplicate rules are no longer created when Save is clicked twice. Task views also no longer reset when the same view is open from different workspaces.&#x20;
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **Designer stability:** fixed a freeze when opening Runtime after expanding a component's Permissions section, and a pending AI UI-generation draft no longer locks the process diagram read-only.&#x20;
> > > > * **Date Picker:** the calendar now anchors correctly to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.&#x20;
> > > > * **Workflows:** fixed a silent workflow freeze that could occur after a step exhausted its retries.&#x20;
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior. UI Flows on iOS also gain support for the `additionalData` object.
> > > >   &#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Media Library:** PDF assets in the list can now be opened in a new tab directly from the Media Library.
> > > > * **Process start loading:** web renderers now keep the loading indicator visible until the first user task renders, matching the mobile SDK behavior.&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.3 is fully compatible with 5.9.2. No configuration changes are required on upgrade; new tuning options ship with working defaults.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.2 → 5.9.3 with no breaking changes
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps are required for this maintenance release. Upgrading directly from 5.9.0 or 5.9.1? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.3](./deployment-guidelines-v5.9.3).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4

Component versions, configuration, and deployment notes for FlowX.AI 5.9.4 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.4 is a maintenance release for the 5.9.x LTS line. The platform upgrade from 5.9.3 is non-breaking, but this release changes how the Helm charts express the container image location, so review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.3 → 5.9.4**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Helm values change.** The charts now express the image location as `image.registry` plus `image.repository` instead of one combined path. Deployments that set `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move it out before upgrading — see [Helm charts: image registry split](#helm-charts-image-registry-split).

> [!NOTE]
>
> **Upgrading from 5.9.0, 5.9.1, or 5.9.2 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.171.3 | 10.165.0 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.149.3 | 10.144.0 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.110.4 | 10.105.0 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.91.2 | 10.87.0 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.97.2 | 10.93.0 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.107.4 | 10.103.0 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.121.3 | 10.116.0 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.109.3 | 10.105.0 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.89.2 | 10.85.0 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.99.2 | 10.95.0 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.95.2 | 10.91.0 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.197.5 | 10.192.0 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.104.3 | 10.100.0 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.119.3 | 10.115.0 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.98.2 | 10.94.0 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.98.2 | 10.93.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.95.2 | 10.90.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.66.2 | 10.62.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.30.2 | 10.25.0 | 10.8.0 | - | - |
| **license** | 10.84.2 | 10.80.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.275.0 | 10.265.6 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.0 | 10.5.11 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.8.0 | 10.6.6 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.2 | 10.9.1 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.10.2 | 10.9.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.10.2 | 10.9.1 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.10.2 | 10.9.1 | 10.1.1 | - | - |
| **speech-to-text** | 10.10.2 | 10.9.1 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.10.2 | 10.9.1 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.32.2 | 10.27.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.10.2 | 10.9.1 | - | - | - |
| **ai-assistant** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.10.2 | 10.9.1 | - | - | - |
| **flowx-docs** | 5.9.4 | 5.9.3 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.4 introduces no new Kafka topics over 5.9.3. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Apply the Helm values change described in [Configuration changes](#configuration-changes), if it affects your setup.
2. Update container images to the 5.9.4 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Helm charts: image registry split

Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.

```yaml theme={"dark"}
# Before
image:
  repository: <registry>/<image-name>

# After
image:
  registry: <registry>
  repository: <image-name>
```

The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.

**Upgrade notes**

* **If you set `global.imageRegistry` to point the charts at your own registry** (the standard, documented approach): no action is required. Your override continues to work, and it now applies cleanly to the default bare repository names.
* **If you embedded the registry inside `image.repository`** (for example `image.repository: harbor.mycorp.internal/flowx/<image-name>`): move the registry portion out. Set it through `global.imageRegistry`, or the chart's `image.registry`, and let `image.repository` fall back to its default bare image name. Leaving the registry in `image.repository` alongside the now-populated `image.registry` prepends the registry twice.

  This applies to deployments configured from the FlowX setup guides before 5.9.4, which showed the combined form. If your values files were built from those examples, check them before upgrading.

#### Events Gateway service account

Events Gateway now authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`, in the service-accounts realm. It needs this identity to resolve and authorize a subscription before admitting the stream.

Two new configuration values are involved, and both take the **same secret**:

| Service | Environment Variable | Purpose |
| - | - | - |
| authorization-system | `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXEVENTSGATEWAYSA` | Secret the migration assigns to the client it creates |
| events-gateway | `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Secret Events Gateway authenticates with |

**Upgrade notes**

* **If you deploy with the FlowX Helm charts and authorization-system runs its migrations with Keycloak admin access**: no action is required. The chart already maps both values to the `KEYCLOAK_EVENTS_GATEWAY_CLIENT_SECRET` key of the `keycloak-flowx-realm-clients` secret, and the authorization-system migration creates the client and grants it the `SA_FLOWX` role.
* **If you manage Keycloak clients outside the chart** (external IdP, or authorization-system cannot provision clients): create `flowx-events-gateway-sa` in the service-accounts realm as a confidential client with service accounts enabled and only the client-credentials grant, then supply its secret to both values above.

> [!WARNING]
>
> If `flowx-events-gateway-sa` already exists, the migration leaves its secret untouched by design. A pre-existing client whose secret does not match the one given to Events Gateway will not be corrected on upgrade, and Events Gateway will fail to authorize subscriptions. Make the two match manually in that case.

#### Liquibase migration lock moves to database session locks

The lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so a stale `databasechangeloglock` row no longer needs clearing by hand. On any other database, Liquibase falls back to its standard row-based lock.

The previous mechanism verified the lock-holder pod through the Kubernetes API. That dependency is gone:

* Service accounts no longer need the `get pods/status` permission, and the FlowX Helm charts no longer create the corresponding Role and RoleBinding. If you maintain that RBAC outside the charts, you can remove the grant.
* The lock keeps working on Kubernetes 1.33 and newer, where the previous mechanism silently deactivated itself.

**Oracle deployments** must grant each FlowX service's database user the following before upgrading. A service whose grants are missing stops at startup with an error naming the missing grant:

```sql theme={"dark"}
GRANT EXECUTE ON SYS.DBMS_LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$SESSION TO <app_user>;
```

PostgreSQL deployments need no action: advisory locks require no additional grant.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, the Angular 21 renderer upgrade, and a Helm chart image-registry change.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. The platform upgrade from **5.9.3 → 5.9.4** requires no data migration, but it does change how the Helm charts express the container image location. Review the [deployment guidelines](./deployment-guidelines-v5.9.4#configuration-changes) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.4** is a maintenance release for the 5.9.x LTS:
>
> * **Helm charts:** the container image reference splits into `image.registry` and `image.repository`, making `global.imageRegistry` a single chart-wide override
> * **Angular 21:** the Angular renderer and the web SDKs move to Angular 21
> * **Key fixes:** branch merges no longer getting stuck, build export retry after a dependency timeout, deleting actions that call functions, gateway expression failures surfaced as incidents, library resource overview
> * **Cross-version import:** an imported theme is completed from the destination's system theme, so nothing is missing after importing an older export
> * Designer, renderer, and backend stability fixes plus security patches
> * No data migration; the only upgrade action is the Helm values change, and only for one override pattern

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, plus a Helm chart change that affects some self-hosted deployments.
>
> 📦 [**Helm chart image registry**](#helm-chart-image-registry) - `image.repository` splits into `image.registry` + `image.repository`\
> 🅰️ [**Angular 21**](#angular-21) - The Angular renderer and web SDKs move to Angular 21\
> 🔧 [**Platform improvements**](#platform-improvements) - Bug fixes and security patches
>
> ***
>
> ### **Helm chart image registry**
>
> > [card] image.repository splits into image.registry + image.repository
> >
> > Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.
> >
> > ```yaml theme={"dark"}
> > # Before
> > image:
> >   repository: <registry>/<image-name>
> >
> > # After
> > image:
> >   registry: <registry>
> >   repository: <image-name>
> > ```
> >
> > The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.
> >
> > > [!WARNING]
> > >
> > > **Check your values files before upgrading.** If you set `global.imageRegistry`, no action is needed. If you embedded the registry inside `image.repository`, move it out first, or the registry is prepended twice. This includes values files built from the FlowX setup guides before 5.9.4, which showed the combined form. Full before-and-after in the [deployment guidelines](./deployment-guidelines-v5.9.4#helm-charts-image-registry-split).
> >
> > All Deployments
>
> ***
>
> ### **Angular 21**
>
> > [card] Angular renderer and web SDKs on Angular 21
> >
> > The Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps embedding the Angular SDK should be on Angular 21 before taking 5.9.4.
> >
> > Angular does not support skipping a major in a single update, so step through the official update guide one major at a time. The **npm** and **node** requirements are unchanged from 5.9.3.
> >
> > See the [Angular SDK requirements](/5.9/sdks/angular-renderer#angular-project-requirements) for the current version floor, and the [Angular migration guide](/5.9/migrating-from-5.1-lts/angular#framework-upgrade-angular-19-→-21) for the upgrade path.
> >
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build export:** retrying a build export now re-attempts a dependency library whose own export ended in a timeout, instead of failing again immediately. Previously the retry skipped the timed-out dependency, so the parent build could never finish; the workaround was to export that dependency directly first.&#x20;
> > > > * **Actions:** deleting an action whose business rule calls a function now works instead of returning a server error. This affected any action at any nesting level, in both projects and libraries; the workaround was to delete the rule from the action first.&#x20;
> > > > * **Gateways:** an expression that fails to evaluate on an exclusive gateway now surfaces as an incident on the process instance. Previously the failure appeared only in the service logs, with no feedback in the platform.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection. Changing the page size no longer opens the wrong process from the list. &#x20;
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives while a background synchronization is still running, and merging versions no longer fails with a navigation-areas error.&#x20;
> > > > * **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds. The page index was previously lost on back-navigation.&#x20;
> > > > * **Reusable UI templates:** static input mappings configured on a reusable template are now applied at runtime.&#x20;
> > > > * **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.&#x20;
> > > > * **Entry points:** the entry-point picker in version settings now lists only processes and UI flows from the current project. Resources from dependency libraries were previously offered and could be selected.&#x20;
> > > > * **Themes and CMS resources:** exporting a theme no longer includes duplicate non-system copies of system icons, so repeated imports stop multiplying them, and importing no longer leaves system substitution tags missing.&#x20;
> > > > * **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output built from trailing empty cells and rows.&#x20;
> > > > * **Generated documents:** a document whose storage write fails now returns an error instead of being recorded as successful with a download path that cannot be opened. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.&#x20;
> > > > * **Renderers:** the document preview shows its subtitle again, and the file-upload error message picks up the configured theme.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Cross-version import:** importing a project build or version exported from an older platform line now completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten, so customizations survive.&#x20;
> > > > * **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.&#x20;
> > > > * **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.&#x20;
> > > > * **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.&#x20;
> > > > * **Integration Designer performance:** service startup no longer scans the full token-instance collection to warm up, and the run-list summary queries are indexed and gated.&#x20;
> > > > * **Database migrations:** the lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so there is no stale `databasechangeloglock` row to clear by hand. The previous mechanism recovered a stuck lock through the Kubernetes API, which required the `pods/status` permission on every service account and silently deactivated on Kubernetes 1.33 and newer. Oracle deployments need new database grants before upgrading: see the [deployment guidelines](./deployment-guidelines-v5.9.4#liquibase-migration-lock-moves-to-database-session-locks).&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade compatibility:** FlowX.AI 5.9.4 is compatible with 5.9.3. No data migration is required. One deployment-level change applies: the Helm charts split the image reference into `image.registry` and `image.repository`. Oracle deployments also need new database grants for the Liquibase migration session lock.
>
> > [!WARNING]
> >
> > **Helm values migration.** Deployments that redirect images through `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move the registry portion out before upgrading. See [Configuration changes](./deployment-guidelines-v5.9.4#configuration-changes).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Direct upgrade from 5.9.3 → 5.9.4. No data migration; review the Helm values change first.
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. The Angular SDK moves to Angular 21.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.4](./deployment-guidelines-v5.9.4).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5

Component versions, configuration, and deployment notes for FlowX.AI 5.9.5 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.5 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.4 is non-breaking and requires no data migration. The headline addition, native PostgreSQL partitioning, is opt-in: deployments that never enabled data partitioning are not affected. Review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.4 → 5.9.5**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.3 or earlier directly?** Review the [5.9.4 deployment guidelines](../v5.9.4-august-2026/deployment-guidelines-v5.9.4) first: the Helm image registry split applies when you skip 5.9.4. Upgrading from 5.9.0, 5.9.1, or 5.9.2, also review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) for the organization-ID migration fix and manually marked Liquibase changesets.

## Component versions

### Core components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.10 | 10.171.3 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.7 | 10.149.3 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.7 | 10.110.4 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.6 | 10.91.2 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.100.7 | 10.97.2 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.110.7 | 10.107.4 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.7 | 10.121.3 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.6 | 10.109.3 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.6 | 10.89.2 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.6 | 10.99.2 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.7 | 10.95.2 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.200.9 | 10.197.5 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.7 | 10.104.3 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.7 | 10.119.3 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.6 | 10.98.2 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.101.6 | 10.98.2 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.6 | 10.95.2 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.6 | 10.66.2 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.7 | 10.30.2 | 10.8.0 | - | - |
| **license** | 10.87.6 | 10.84.2 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB**: see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.282.5 | 10.275.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.2 | 10.6.0 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.9.3 | 10.8.0 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.0 | 10.10.2 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.0 | 10.10.2 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.0 | 10.10.2 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.0 | 10.10.2 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.0 | 10.10.2 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.0 | 10.10.2 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.6 | 10.32.2 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.0 | 10.10.2 | - | - | - |
| **ai-assistant** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.0 | 10.10.2 | - | - | - |
| **flowx-docs** | 5.9.5 | 5.9.4 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.5 introduces no new Kafka topics over 5.9.4. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Review [Configuration changes](#configuration-changes): everything new in this release is opt-in or ships with a safe default, so no values change is required for a standard upgrade.
2. Update container images to the 5.9.5 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Native PostgreSQL partitioning (opt-in)

Process-instance archiving on PostgreSQL can now use native declarative partitions instead of the legacy copy-based mechanism. Data partitioning itself remains **off by default** (`FLOWX_DATA_PARTITIONING_ENABLED` is `false`), so deployments that never enabled it are not affected.

New process-engine variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Use native PostgreSQL partitions for archiving when partitioning is enabled. PostgreSQL only; other databases keep the existing mechanism. | `true` |
| `FLOWX_DATA_PARTITIONING_PREMAKECRONEXPRESSION` | Schedule for the job that creates upcoming partitions in advance. | `0 0 23 * * ?` |
| `FLOWX_DATA_PARTITIONING_PREMAKEPARTITIONSAHEAD` | How many future partitions the job keeps created ahead of the current one. | `2` |

> [!WARNING]
>
> Enabling native partitioning converts the process-instance tables to partitioned tables, and the conversion is one way: there is no supported path back to unpartitioned tables. Review the [partitioning and archiving setup guide](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning) before turning it on.

#### Document plugin: processing size limits

The document plugin now enforces size limits on archive, encryption, and extraction operations. Input over the limit is rejected instead of processed. The defaults are generous; override them only if your documents legitimately exceed them.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOCUMENT_ARCHIVE_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for archive operations. | `209715200` (200 MB) |
| `DOCUMENT_ENCRYPTION_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for encryption. | `104857600` (100 MB) |
| `DOCUMENT_EXTRACT_MAX_UNCOMPRESSED_SIZE` | Maximum total uncompressed size, in bytes, an archive may expand to during extraction. | `209715200` (200 MB) |

#### Integration Designer: workflow output size guard

Workflow output published to Kafka is now size-checked before sending. A root workflow output that exceeds the limit fails the workflow run with the failure type `outputTooLargeForKafka` instead of being silently dropped by the broker's message-size limit. The check applies to root workflow outputs on automatic and default-path completion; subworkflow outputs are not checked.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_KAFKA_PAYLOAD_SIZE_LIMIT` | Maximum serialized size, in bytes, of a root workflow output published to Kafka. | `786432` |

> [!TIP]
>
> Keep this limit below your broker's `max.message.bytes`. The default, 768 KB, sits safely under the common 1 MB broker default.

#### Advancing datasource metrics

The process engine and Integration Designer now register their advancing datasource under a named connection pool (`advancing`), so its metrics are distinguishable from the main datasource pool in Prometheus. No configuration action is required.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026

Maintenance release for the 5.9.x LTS line. Native PostgreSQL partitioning for process data, bug fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. It also brings native PostgreSQL partitioning to process data. Review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.5** is a maintenance release for the 5.9.x LTS:
>
> * **Native PostgreSQL partitioning:** process data tables are partitioned by the database itself, so removing old data becomes a partition drop instead of a bulk delete
> * **Key fixes:** audit entries no longer missing or attributed to the wrong application, merge conflicts raised for changes inside embedded subprocesses, self-hosted Keycloak issuer derived from configuration
> * **Integrations:** an SFTP private key can be stored as a multi-line PEM
> * Backend, Designer, and renderer stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.5 is compatible with 5.9.4, and the upgrade requires no data migration. Native PostgreSQL partitioning is opt-in: if you had already enabled data partitioning, review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade, because the conversion to native partitions runs automatically for you and is one way.

**Before you upgrade, check these:**

* **AI job queues:** each AI service now consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group, and the new groups read only jobs published after they start. Wait until the `ai-services` group has no lag on the job topics before you upgrade, so no queued job is skipped. If your cluster restricts consumer groups with ACLs, allow the new groups first.
* **Relational data sources:** Oracle data sources connect only to hosts that resolve to a public address. Add private database hosts to the allowlist, as described in [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Service-account secrets:** confirm every service-account client secret is set on `authorization-system`, or the service stops at startup. The secrets are listed in the [Authorization setup guide](/5.9/setup-guides/authorization-setup-guide).
* **Dashboards and alerts:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total`.
* **Runtime log levels:** the `loggers` actuator endpoint is no longer exposed by default. Add it back as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Data partitioning:** if you had already turned on data partitioning, the conversion to native partitions runs automatically on upgrade and is one way. See the [deployment guidelines](./deployment-guidelines-v5.9.5).

**Upgrade path:** direct upgrade from 5.9.4. Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. Component versions are listed in the [5.9.5 deployment guidelines](./deployment-guidelines-v5.9.5).

***

## Native PostgreSQL partitioning

The process engine stores process data in tables that PostgreSQL itself partitions by time. Retention then
works by dropping whole partitions rather than deleting rows one at a time, which keeps the cost of
removing old data flat as the tables grow.

This is the same partitioning model described for the 5.12 line, delivered into the 5.9.x LTS.

For how partitioning interacts with archiving and retention, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving).

***

## Full changelog

### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.&#x20;
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](#native-postgresql-partitioning).&#x20;

### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.&#x20;
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.&#x20;
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.&#x20;
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.&#x20;
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.&#x20;
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.&#x20;
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.&#x20;
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](./deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).&#x20;
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](./deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).&#x20;
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).&#x20;
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).&#x20;
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.&#x20;
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.&#x20;

### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.&#x20;
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.&#x20;
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.&#x20;
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.&#x20;
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.&#x20;
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.&#x20;
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.&#x20;
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.&#x20;
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.&#x20;
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.&#x20;
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# Deployment guidelines v5.9.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6

Component versions, configuration, and deployment notes for FlowX.AI 5.9.6 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.6 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.5 adds one Kafka topic, a database table, and a MongoDB index. The table and the index are created automatically when the services start. Review [Kafka topics](#kafka-topics), [Configuration changes](#configuration-changes), and the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes) before you deploy.

> [card] Upgrade Path
>
> **5.9.5 → 5.9.6**: Direct upgrade. No manual data migration is required.
>
> **5.9.6 → 6.0.0**: See [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.4 or earlier directly?** Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first, then the earlier pages they point to.

## Component versions

### Core components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.17 | 10.174.10 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.14 | 10.152.7 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.13 | 10.113.7 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.11 | 10.94.6 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.101.1 | 10.100.7 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.111.1 | 10.110.7 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.13 | 10.124.7 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.12 | 10.112.6 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.8 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.11 | 10.92.6 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.11 | 10.102.6 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.12 | 10.98.7 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.201.2 | 10.200.9 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.13 | 10.107.7 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.13 | 10.122.7 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.13 | 10.101.6 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.102.1 | 10.101.6 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.12 | 10.98.6 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.12 | 10.69.6 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.14 | 10.33.7 | 10.8.0 | - | - |
| **license** | 10.87.12 | 10.87.6 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** 1.52.0, deployed and upgraded by the **SpiceDB operator** 1.25.1.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **solution-portal** (renamed from react-saas) | 10.285.4 | 10.282.5 | 10.230.2 | - | - |
| **iOS renderer** | 10.9.2 | 10.6.2 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.10.2 | 10.9.3 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.2 | 10.11.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.2 | 10.11.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.2 | 10.11.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.2 | 10.11.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.2 | 10.11.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.2 | 10.11.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.13 | 10.35.6 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.2 | 10.11.0 | - | - | - |
| **ai-assistant** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.2 | 10.11.0 | - | - | - |
| **flowx-docs** | 5.9.6 | 5.9.5 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.6 adds one Kafka topic. If your cluster does not create topics automatically, create it before you deploy, and allow both services in your ACLs.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.build.deployment-failed.v1` | runtime-manager | application-manager | Reports a build deployment that failed, so application-manager can queue it for a retry. |

The topic is included in the FlowX Kafka topics chart from version 10.2.0. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Create the `ai.flowx.build.deployment-failed.v1` Kafka topic if your cluster does not create topics automatically. See [Kafka topics](#kafka-topics).
2. Review [Configuration changes](#configuration-changes). No values change is required for a standard upgrade.
3. The `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes).
4. Update container images to the 5.9.6 versions listed in the tables above.
5. Deploy services using your standard deployment process.
6. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Build redeployment retries

When a build deployment fails, application-manager queues it for a retry. The queue is now stored in the application-manager database, in the new `failed_deployment` table, instead of in Redis. The table is created automatically on startup. runtime-manager reports each failure on the `ai.flowx.build.deployment-failed.v1` topic, and application-manager consumes it.

New application-manager variables (the defaults fit a standard deployment):

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_BUILD_DEPLOYMENTFAILED` | Topic that carries failed build deployments. | `ai.flowx.build.deployment-failed.v1` |
| `KAFKA_CONSUMER_GROUPID_BUILD_DEPLOYMENTFAILED` | Consumer group that reads the topic. | `build-deployment-failed-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_DEPLOYMENTFAILED` | Number of consumer threads for the topic. | `1` |

> [!WARNING]
>
> Retries that are still queued in Redis when you upgrade are not moved to the new table. Re-publish any build whose deployment failed shortly before the upgrade. The old entries stay in the Redis hash `build:failed-deployments:v3`, under the persistence key prefix configured for application-manager. Nothing reads them after the upgrade, so you can delete the hash.

#### MongoDB setting names

Services that use MongoDB now read their connection settings from new names. The previous `SPRING_DATA_MONGODB_*` variables still feed the new settings, so existing deployments need no change. Use the new names in new configuration.

| Previous variable | New variable |
| - | - |
| `SPRING_DATA_MONGODB_URI` | `SPRING_MONGODB_URI` |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | `SPRING_MONGODB_REPRESENTATION_UUID` |
| `SPRING_DATA_MONGODB_STORAGE` | `FLOWX_DATASOURCE_MONGO_STORAGE` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | `FLOWX_DATASOURCE_APPRUNTIME_ENABLED` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | `FLOWX_DATASOURCE_APPRUNTIME_URI` |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | `FLOWX_DATASOURCE_APPRUNTIME_REPRESENTATION_UUID` |

`SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION` no longer has any effect: indexes on the runtime database are never created automatically.

#### Document parser models

The document parser image now contains its layout, table, and OCR models, so the parser downloads nothing at startup or on the first parse. It runs without internet access and on a read-only filesystem. `USE_DOCLING` no longer has any effect on the document parser and can be removed from its configuration.

#### Integration Designer: document download timeout

A REST node JSON body can include `"@@base64File(<path>)"` to send a Document Plugin file as base64. Downloading the file from the Document Plugin is cancelled after this timeout. See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

New integration-designer variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` | Longest time a Document Plugin file download for a REST node JSON body may take before it is cancelled. | `PT5M` |

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026

Maintenance release for the 5.9.x LTS line. Durable build redeployment retries, project version merge fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Review the [deployment guidelines](./deployment-guidelines-v5.9.6) before you upgrade: this release adds one Kafka topic.

> [card] Release Highlight
>
> **FlowX.AI 5.9.6** is a maintenance release for the 5.9.x LTS:
>
> * **Durable build redeployments:** a build deployment that failed and waits for a retry is stored in the database, so a Redis flush or restart no longer drops it
> * **Key fixes:** project version merges no longer lose navigation areas, Resources Changed no longer flags unchanged resources, and Number attributes keep the selected subtype
> * Backend, Designer, and AI stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.6 is compatible with 5.9.5. The upgrade adds a database table and a MongoDB index, both created automatically when the services start.

**Before you upgrade, check these:**

* **AI Platform Helm chart:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime.&#x20;
* **Kafka topics:** create the `ai.flowx.build.deployment-failed.v1` topic if your cluster does not create topics automatically, and allow it in your ACLs. `runtime-manager` produces it and `application-manager` consumes it. See [Kafka topics](./deployment-guidelines-v5.9.6#kafka-topics).
* **Pending build redeployments:** retries that are still queued in Redis when you upgrade are not carried over. Re-publish any build whose deployment failed shortly before the upgrade. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Workflow node retries:** retry waits now grow exponentially and the max interval caps each wait instead of the whole retry window. Review the retry settings of nodes that rely on the previous timing.
* **Connection tests:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources. Grant these to custom roles that run connection tests.
* **Integration Designer startup:** the first start after the upgrade builds a new index on the `workflow_instances` MongoDB collection. On a large collection, allow extra time before the readiness check passes.
* **React Native SDK hosts:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` and keeps showing the current process, like the Android and iOS SDKs. Update your app to dispose the current process handle and continue the new process. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).

**Upgrade path:** direct upgrade from 5.9.5. Upgrading from 5.9.4 or earlier? Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/React Native/iOS/Android) and Designer 5.9.x. Component versions are listed in the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6).

***

## Full changelog

### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json) and [Integration Designer: document download timeout](./deployment-guidelines-v5.9.6#integration-designer-document-download-timeout).&#x20;

### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.&#x20;
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).&#x20;
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.&#x20;
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect. See [Document parser models](./deployment-guidelines-v5.9.6#document-parser-models).&#x20;
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.&#x20;
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.&#x20;
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](./deployment-guidelines-v5.9.6#mongodb-setting-names).&#x20;
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.&#x20;
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.&#x20;
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6) for its version.&#x20;

### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.&#x20;
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.&#x20;
* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.&#x20;
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.&#x20;
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.&#x20;
* **React Native SDK:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` instead of replacing the shown process itself, like the Android and iOS SDKs. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).&#x20;
* **React Native SDK:** a custom component keeps receiving data after the app returns from the background, for example from the Android document picker, so a document upload waiting for its link completes.&#x20;
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.9.x to 6.0.0 changelog
Source: https://docs.flowx.ai/release-notes/v6.x/5.9-to-6.0-changelog

Every change a self-hosted FlowX.AI 5.9.x installation picks up when it moves to 6.0.0, grouped by release and type, with an RSS feed.

This page lists what changes for a self-hosted FlowX.AI 5.9.x installation that moves to 6.0.0, newest first. Releases 5.10 to 5.13 shipped to SaaS first, and self-hosted installations get their features with 6.0.0. Changes already delivered in a 5.9.x patch are in the [5.9.x LTS changelog](/release-notes/v5.x/5.9-lts-changelog) and are not repeated here. Mobile renderers and the React Native SDK are covered in their own release notes.

On FlowX.AI SaaS, apps moved from 5.13.0 to 6.0.0, so only the 6.0.0 entry applies to them, including its upgrade actions.

**6.0.0**

October 2026

**Upgrade actions:** check these in your existing apps.

* **AI node prompts:** the chat message is no longer appended. Reference `${userMessage}` in **Context**. [Details](/6.x/ai-platform/chat-driven-workflows#context)
* **AI node retries:** on by default, up to 10 times, 30 seconds apart. [Details](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service)
* **Substitution tags:** `@@key` is rewritten to `${tag:key}`, and a missing `sys_*` tag now renders empty. [Details](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#what-changes-in-existing-apps-when-you-upgrade)
* **FlowX Database and Unmanaged MongoDB writes:** `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter are rejected. To match every document, pass `{"_id": {"$exists": true}}`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb)
* **Masked names:** data-privacy placeholders now carry the gender, such as `<NAME_F_1>`. Update prompts or scripts that match `<NAME_1>`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy)
* **Email triggers over IMAPS:** the mail server's certificate is now verified, so a self-signed or mismatched certificate stops the trigger from connecting. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway)
* **Evaluations:** datasets become test cases with no checks, so an experiment skips them until you add an assert or evaluator. [Details](/6.x/ai-platform/evaluations#datasets-from-earlier-versions)
* **Exports from 5.1.x:** they no longer import, and 5.1.x is no longer an export target. Import a 5.1.x export into a 5.9.x environment and export it again from there. [Details](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x)
* **Scripts on GraalVM:** they now stop at the same per-language time limit as the native engine, 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0 they had no limit. [Details](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits)

Self-hosted installations also follow the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) and the [migration guide](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview) for the Helm chart and renderer SDKs.

#### New

* **Developer Agentic Harness:** a plan can split the work into stories, delivered one at a time, each with how to test it. Comment mode lets you select a component in the running app and ask for a change, and conversations follow you across the Designer. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Integration Designer:** add schedules to a workflow's Start node to run it once on a date or repeatedly on an ISO or cron cycle. A schedule fires only after you activate it in **Runtime** → **Runtime Settings** → **Schedules**. See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
* **Integration Designer:** the Generate Tabular File node turns an array of rows into a CSV or XLSX file. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
* **FlowX Database:** an index can enforce unique values on one attribute or a compound key, and existing duplicates are reported when you run **Apply Indexes**. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
* **Knowledge Base:** **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
* **Resources:** **Documentation** in a resource's menu holds a short description and longer Markdown documentation. Media Library assets get a description, used as the image's alt text. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
* **Substitution tags:** write `${tag:key}` anywhere in a component's text, next to static text and process data. The upgrade rewrites whole-value `@@key` references to `${tag:key}`, and `@@key` keeps working as a whole value. See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).

#### Changed

* **Designer header:** the header holds the project name, the **Config** / **Runtime** switch, the **Build with AI** and **Comment** toggles, and **Run project**. Branching, the current version, and **Commit Changes** move to a version block in the footer. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
* **AI nodes:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when its AI service or provider can't be reached. Turn on **Allow Retry** to set your own count, interval, and backoff. See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
* **Chat-driven workflows:** the chat message is no longer appended to an AI node's prompt. Reference `${userMessage}` in the node's **Context**. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
* **Evaluations:** each workflow has its own test cases, grouped by tags, with **equals** and **equals as JSON** asserts and LLM evaluators. The upgrade converts datasets to test cases with no checks, so add an assert or evaluator to each one before you run it. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
* **Certificates:** the **Certificates** panel on REST and File Storage data sources has two parts: **Trust** (System CAs, Custom CA, or None (insecure)) and **Identity** for mutual TLS. Existing settings are converted automatically. See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates).
* **Knowledge Base:** turning **Containing Personal Information** on or off re-embeds the existing content with the new model. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested).
* **Issues Console:** a check also covers the version itself: entry points, theme, library builds, and unused dependencies. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
* **Notification center:** covers version imports and build exports and imports, alongside version exports and process instance migrations. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
* **Configuration parameters:** after you save a sensitive value, the Designer shows `********` in its place. The real value is still used at runtime. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
* **Script engine:** scripts on GraalVM stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
* **Canvas:** **Auto-arrange** on the workflow canvas and **Arrange** on the process canvas show a layout preview before anything moves. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).
* **Timer events:** timer nodes use the schedule editor. Dates and times are picked in local time and saved in UTC. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).
* **Versioning:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).
* **Datepicker:** **Allow manual input** lets users type a date in the pattern of the project's default locale. Web only.
* **Data mapping:** typing a new attribute path, such as `client.address.street`, creates the data types it names when you save the mapping.

#### Removed

* **AI agents:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors are removed. Open the agent rail with ⌘K (Ctrl+K) or the sparkle toggle in the header. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Evaluations:** the Code evaluators are removed. Use **equals** in place of Exact match and **equals as JSON** in place of JSON match. Levenshtein has no replacement. See [Evaluations](/6.x/ai-platform/evaluations).
* **Export and import:** exports from 5.1.x no longer import, and 5.1.x is no longer an export target. See [Exports from 5.1.x](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x).

#### Deprecated

* **GraalVM script engine:** deprecated. FlowX.AI 6.1.x is the last release family that supports it. Scripts on GraalVM keep working in 6.0.0; move them to the native engine. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).

[6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) · [6.0.0 deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)

**5.13.0**

September 2026

#### New

* **Developer Agentic Harness:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys the app, drafts a plan for you to confirm, and runs the change on its own branch; merging and serving a new version stay with you. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Notification center:** a bell in the Designer opens a 30-day notification history with read state, search, and filters. See [Notification center](/6.x/docs/flowx-designer/notification-center).
* **UI Designer:** copy UI components and paste them into another UI Flow, app, or context. The paste names anything it could not place, and pasted components get unique names.
* **Versioning:** committing or merging a version takes an optional description of up to 2000 characters, and a commit details view shows what a version contains. See [Commit descriptions and details](/6.x/docs/projects/managing-applications/versioning#commit-descriptions-and-details).
* **Runtime:** an operator with the corrective-actions role moves the token of a running process instance to another node. See [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
* **Document classifiers:** a classifier's corpus can be exported and imported between environments, and viewed read-only in the **Data** tab. See [What travels between environments](/6.x/docs/platform-deep-dive/integrations/document-classifiers#what-travels-between-environments).
* **Integration Designer:** the File Encryption node encrypts or decrypts a file with a password inside a workflow. The file path and password take expressions.
* **UI Designer:** a start workflow trigger takes a condition, so the workflow starts only when the condition holds.&#x20;
* **FlowX Database:** the Intersects operator matches documents whose array field shares at least one value with a given list. See [Intersects on array fields](/6.x/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).
* **Personal Information Guard:** AI nodes with the input scan on log the request as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/6.x/ai-platform/personal-information-guard#request-after-pii-anonymization).

#### Changed

* **Access management:** the Workspace corrective actions editor role replaces the Workspace operations editor role. Users and groups with the old role move to the new one automatically. See [Workspace corrective actions editor permission matrix](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
* **Export and import:** version exports bundle dependencies the same way build exports do, and the export dialog preselects the target platform version. See [Version exports that bundle dependencies](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#version-exports-that-bundle-dependencies).
* **Integration Designer:** the Tabular Data Extraction node becomes the Data Parse node and also parses XML and JSON. See [Data Parse: XML and JSON support](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support).
* **Knowledge Base:** embedding jobs are scheduled fairly by default, so a large ingestion no longer delays small jobs queued behind it.
* **File sources:** Document and Image components share one source configuration. In process user tasks, the **Document Plugin Path** source takes a Documents plugin `downloadPath` directly. See [Selecting the file to download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download#selecting-the-file-to-download).
* **Task management:** the task list searches, filters, and sorts on the translated labels it displays. See [Search and sort on translated labels](/6.x/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).
* **Substitution tags:** custom tags can no longer start with `sys_`, which is reserved for system tags. See [Substitution tags](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags).
* **Elasticsearch:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Elasticsearch replica auto-expansion](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).
* **Processes:** the process name moves from **Settings** into a **Details** modal.
* **User management:** inviting many users at once has a reworked flow, and a sign-up link takes new users directly to the right solution.

[5.13.0 release notes](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) · [5.13.0 deployment guidelines](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13)

**5.12.0**

September 2026

**Upgrade actions:** the webhook gateway now reads the runtime registry, which adds a MongoDB dependency it did not have before. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets).

#### New

* **Integration Designer:** turn on **Parallel Multi-Instance** on a Subworkflow node to start one subworkflow per element of an input array and collect the results in an output array. See [Parallel multi-instance](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance).
* **Integration Designer:** email and webhook triggers can start an integration workflow, not only a process. See [External triggers](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).
* **Integration Designer:** a Subworkflow node can route a mapping failure to its own branch instead of stopping the parent workflow. It is opt-in per node. See [Routing a subworkflow failure](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
* **Integration Designer:** the Send Notification node fills a project notification template from workflow data and sends it. See [Send Notification node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node).
* **Db2 data source:** IBM Db2 joins the relational data sources, with Db2 for i as the default and Db2 LUW also supported. Db2 for z/OS is listed but not implemented, and selecting it fails with an error. See [Db2 database](/6.x/docs/platform-deep-dive/integrations/db2-database).
* **Runtime:** bulk migration moves a filtered set of process instances to a new build in one run, with a check before it runs. See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances).
* **Runtime:** a Workflow Instances page lists every workflow run in the project, filterable by status, date, and origin. The Process Instances and UI Flow Sessions lists gain status and start-date filters. See [Workflow instances](/6.x/docs/projects/runtime/workflow-instances).
* **Personal Information Guard:** mask and restore nodes place personal-data handling as explicit workflow steps. See [Masking and restoring across several nodes](/6.x/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
* **Deep Research node:** researches a question across the open web and files a cited report into a Knowledge Base. Depth is Quick, Standard, Deep, or Custom, and domains can be restricted with an allow or deny list. See [Deep Research node](/6.x/docs/platform-deep-dive/integrations/deep-research-node).
* **Custom Agent:** a reusable function with input and output slices can be an agent tool. Built-in tools are a catalog of twenty tools in five categories: Math, List, Date, Text, and Web search. See [Tools tab](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#tools-tab).
* **Chat component:** users rate an agent's answer and add a reason, and the ratings are recorded in audit. See [Rating an answer](/6.x/ai-platform/chat-component#rating-an-answer).
* **Evaluations:** custom evaluators score with Numeric or Binary rules and belong to the workflow you create them in. See [Custom evaluators](/6.x/ai-platform/evaluations#custom).
* **Issues panel:** the Designer validates the resources in a project version and collects the findings in one **Issues** panel. See [Checking for issues](/6.x/docs/projects/managing-applications/checking-for-issues).
* **Versioning:** merge into any branch you can merge into, and archive, unarchive, or delete branches. See [Managing branches](/6.x/docs/projects/managing-applications/versioning#managing-branches).
* **Process canvas:** a **New Node** panel, drop-anywhere connecting, draggable control points on sequence flows, and swimlanes that resize from all four edges. See [Faster ways to build](/6.x/docs/building-blocks/process/process#faster-ways-to-build).
* **Reusable UI templates:** a template can be built for UI Flow pages as well as process user tasks. Templates created earlier count as Process templates. See [Where a template can be used](/6.x/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used).

[5.12.0 release notes](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026) · [5.12.0 deployment guidelines](/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12)

**5.11.0**

August 2026

#### New

* **Custom Agent:** attach FlowX workflows as tools, each with a hint that tells the agent when to call it. See [How workflow tools run](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run).
* **Custom Agent:** agentic knowledge base search breaks a question into sub-queries and retries with reworded queries when the first pass finds nothing. **Show Reasoning** records the model's reasoning summary in the logs. See [Agentic knowledge base search](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#agentic-knowledge-base-search).
* **Knowledge Base:** a Knowledge Base with **Containing Personal Information** on can use a local embedding model, set up as a CUSTOM provider in the organization AI settings. See [Containing personal information](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).
* **Knowledge Base:** the Update Knowledge Base node can delete entries that match a metadata filter, and its FAIL branch reports what failed and how many chunks were rolled back. See [Delete entries](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#delete-entries).
* **Document classifiers:** define classes, upload training data, and train or import a model, then route each document page with the Document Classification node. See [Document classifiers](/6.x/docs/platform-deep-dive/integrations/document-classifiers).
* **Reusable functions:** Script and Condition (Fork) nodes in the Integration Designer can call reusable functions. See [Reusable functions](/6.x/docs/building-blocks/reusable-resources/reusable-functions).
* **Integration Designer:** the Subworkflow node can map input per start node and output per end node instead of raw JSON. See [Subworkflow node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#subworkflow-node).
* **Data model:** attributes support validators such as Required, Min/Max Value, Min/Max Length, Pattern, and Email Format, wherever the data model is used. See [Attribute validations](/6.x/docs/building-blocks/project-data-model#attribute-validations).
* **Templates:** document and notification templates use the structured data model, with typed attributes and an **Input Parameters** tab. See [Managing notification templates](/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates).
* **Chat component:** the chat button shows an unread-message badge, the panel searches conversation history, and the input can be disabled by a condition. See [Chat](/6.x/docs/building-blocks/ui-designer/ui-component-types/chat).
* **UI Flows:** a **Navigate To** action can require selected forms to pass validation before it navigates. See [Navigate To action](/6.x/docs/building-blocks/ui-flows#navigate-to-action).
* **UI Flows:** with **Allow multiple editors** off, a running session is restricted to its owner. New flows default to single-owner; existing and imported flows keep the shared behavior. See [Session owner](/6.x/docs/building-blocks/ui-flows#session-owner).
* **Process Renderer:** a process-end trigger runs a configured action when the embedded process ends. See [Process end handling](/6.x/docs/building-blocks/ui-flows#process-end-handling).

#### Changed

* **Chat-driven workflows:** a conversational workflow must send at least one chat reply, or the run fails with an error. See [Chat-driven workflows](/6.x/ai-platform/chat-driven-workflows).
* **Custom Agent:** the **Instructions** field is limited to 10,000 characters. See [Custom Agent node](/6.x/docs/platform-deep-dive/integrations/custom-agent-node).
* **Response caching:** POST REST endpoints, file-storage LIST and DOWNLOAD, and Mongo FIND, FIND\_ONE, and AGGREGATE operations are cacheable. Mutating operations are never cached. See [REST endpoint caching](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching).
* **Email triggers:** Email Trigger and Microsoft Outlook data sources filter attachments by file extension. Existing category selections are migrated automatically. See [Attachment handling](/6.x/docs/platform-deep-dive/integrations/email-trigger#attachment-handling).
* **Audit:** UI Flow runtime sessions are audited in more detail, including workflow runs, chat messages, and conversation reads. See [Audit](/6.x/docs/platform-deep-dive/core-extensions/audit).
* **Export and import:** exporting to an older platform version removes UI-template features the target cannot read. See [Cross-version export and import](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
* **UI Flows:** an expired session shows a session-expired screen with a start-fresh option.
* **Renderers:** enumeration lookups are batched into a single request.

[5.11.0 release notes](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026) · [5.11.0 deployment guidelines](/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11)

**5.10.0**

July 2026

#### New

* **PostgreSQL data source:** connect a workflow to a PostgreSQL database and run SQL query operations from workflow nodes. See [PostgreSQL database](/6.x/docs/platform-deep-dive/integrations/postgresql-database).
* **SOAP data source:** import a WSDL from a URL or file, and call each operation from workflows with a SOAP Operation node. See [SOAP System](/6.x/docs/platform-deep-dive/integrations/soap-system).
* **FlowX Database:** MongoDB aggregation pipelines group, join, and reshape documents beyond a single query. See [Aggregation pipelines](/6.x/docs/platform-deep-dive/integrations/flowx-database#aggregation-pipelines).
* **Integration Designer:** the Tabular Data Extraction node reads a spreadsheet or CSV file into structured JSON, one object per row. See [Tabular Data Extraction node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node).
* **Integration Designer:** the Template Filling node generates a PDF or DOCX document from a document template filled with workflow data. See [Template Filling node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node).
* **Integration Designer:** the Combine Files node merges PDFs in a given order, and the Split File node splits a PDF by page ranges or per page. See [Combine Files node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node).
* **Documents plugin:** template-based generation can produce DOCX as well as PDF, set with `outputFormat`. See [Generating DOCX output](/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output).
* **Knowledge Base:** a failed ingestion shows its status and reason, and **Retry** re-runs the last operation after cleaning up partial content. The Update Knowledge Base node gains a FAIL exit with per-operation rollback. See [Error handling and retry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#error-handling-and-retry).
* **File Download component:** end users download files directly from a rendered app. See [File download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download).
* **Global header and footer:** a UI Flow can define a header and footer shown on every page. See [Global header and footer](/6.x/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer).
* **Event handlers:** event handlers can fire on a condition. The **Save Local Variable** action saves the clicked collection row into local data under a key. See [Conditional triggers](/6.x/docs/building-blocks/ui-designer/event-handlers#conditional-triggers) and [Save Local Variable](/6.x/docs/building-blocks/ui-designer/event-handlers#save-local-variable).
* **Image component:** the Image component honors a color property. See [Image](/6.x/docs/building-blocks/ui-designer/ui-component-types/image).
* **Data source testing:** the database query testing modals have a **Documents** tab, and multi-record operations report an affected-record count. See [Testing data sources](/6.x/docs/platform-deep-dive/integrations/testing-data-sources).
* **Mistral provider:** add Mistral with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability. See [AI providers](/6.x/ai-platform/ai-providers).

#### Changed

* **Documents:** the **Document Type** field is renamed **Document Tag**. Behavior is unchanged.

[5.10.0 release notes](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026) · [5.10.0 deployment guidelines](/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10)


# Deployment guidelines v6.0.0
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0

Component versions, Kafka topics, environment variables, and Helm chart changes for FlowX.AI 6.0.0, with the steps a self-hosted upgrade needs.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 6.0 is a feature release. On SaaS, FlowX applies every change on this page. Self-hosted deployments usually follow LTS releases and receive these changes with the next LTS release family. If you upgrade a self-hosted installation to 6.0.0, apply the changes below in the order given in [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

### Before you upgrade a self-hosted installation

* Set every AI service group flag explicitly. See [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart).
* Deploy designer-user, the new `core` service. harness and ui-driver (`devtime`) and dynamic-classifier (`runtime`) deploy only if you turn their group on. See [New services](#new-services).
* Create the new database users and secrets for the services you deploy. Every installation needs the four new keys in `keycloak-flowx-realm-clients`. See [New databases and secrets](#new-databases-and-secrets).
* Give process-engine read access to the integration-designer bucket. See [New databases and secrets](#new-databases-and-secrets).
* If you turn on dynamic-classifier, set its bucket name and provide its 20Gi volume. See [Update your values](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart#update-your-values).
* If you route with Kubernetes Ingress, move callers off the admin Ingress routes that the chart no longer creates. See [New databases and secrets](#new-databases-and-secrets).
* Create the new Kafka topics. If your cluster uses ACLs, also give the new clients of three existing topics access. See [New Kafka topics](#new-kafka-topics).
* Let audit-core reach Redis. It now uses Redis only to choose which replica runs its nightly cleanup job, not as a cache, and the chart connects it to the same Redis server as the other services. If you restrict which services can reach Redis, add audit-core. See [Configuring Redis](/6.x/setup-guides/audit-setup-guide#configuring-redis).
* Set the personal-data encryption master key on integration-designer. See [Personal-data encryption master key](#new-required-secret-personal-data-encryption-master-key).
* Choose how Elasticsearch replicates new indices. See [Elasticsearch replica auto-expansion](#changed-default-elasticsearch-replica-auto-expansion).
* Add the MongoDB hosts on your private network that data sources use to `FLOWX_SSRFALLOWEDHOSTS`. See [nosql-db-runner host restrictions](#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).
* Trust the certificates of the IMAP servers your email triggers read from. See [IMAPS certificate verification](#changed-default-imaps-certificate-verification-in-email-gateway).

Upgrading from 5.9.5 or earlier? Two changes from 5.9.6 also apply. See [Upgrading from an older patch release](#upgrading-from-an-older-patch-release).

## Component versions

The versions below are the component versions that make up FlowX.AI 6.0.0, next to FlowX.AI 5.9.6, the latest 5.9.x release a self-hosted installation upgrades from. A dash marks a component that is new since 5.9.6. On SaaS, FlowX manages these versions.

### Core components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **admin** | 11.132.0 | 10.152.14 |
| **advancing-controller** | 11.86.0 | 10.98.12 |
| **application-manager** | 11.143.0 | 10.159.3 |
| **audit-core** | 11.92.0 | 10.102.11 |
| **authorization-system** | 11.102.0 | 10.122.13 |
| **cms-core** | 11.114.0 | 10.113.13 |
| **data-search** | 11.87.0 | 10.92.11 |
| **data-sync** | 11.94.0 | 10.107.13 |
| **designer** | 11.252.0 | 10.285.4 |
| **designer-user** | 11.31.0 | - |
| **document-plugin** | 11.122.0 | 10.124.13 |
| **email-gateway** | 11.110.0 | 10.102.1 |
| **events-gateway** | 11.93.0 | 10.101.1 |
| **file-gateway** | 11.105.0 | 10.33.14 |
| **integration-designer** | 11.158.0 | 10.201.2 |
| **license** | 11.94.0 | 10.87.12 |
| **nosql-db-runner** | 11.98.0 | 10.101.13 |
| **notification-plugin** | 11.113.0 | 10.111.1 |
| **organization-manager** | 11.101.0 | 10.98.12 |
| **process-engine** | 11.137.1 | 10.174.17 |
| **runtime-manager** | 11.143.0 | 10.159.3 |
| **scheduler-core** | 11.89.0 | 10.94.11 |
| **task-management-plugin** | 11.109.0 | 10.112.12 |
| **webhook-gateway** | 11.102.0 | 10.69.12 |

### AI base components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-gateway** | 11.118.1 | 10.35.13 |
| **embedder** | 11.7.0 | 10.11.2 |
| **knowledgebase-indexer-v2** | 11.7.0 | 10.11.2 |
| **knowledgebase-rag** | 11.7.0 | 10.11.2 |
| **doc-parser** | 11.7.0 | 10.11.2 |

### AI dev-time components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-analyst** | 11.7.0 | 10.11.2 |
| **ai-architect** | 11.7.0 | 10.11.2 |
| **ai-assistant** | 11.7.0 | 10.11.2 |
| **ai-designer** | 11.7.0 | 10.11.2 |
| **ai-developer** | 11.7.0 | 10.11.2 |
| **harness** | 11.7.0 | - |
| **kb-enrichment** | 11.7.0 | 10.11.2 |
| **planner** | 11.7.0 | 10.11.2 |
| **ui-driver** | 11.252.0 | - |

### AI runtime components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **agent-builder** | 11.7.0 | 10.11.2 |
| **cee-pii** | 11.7.0 | - |
| **data-privacy** | 11.7.0 | 10.11.2 |
| **doc-converter** | 11.7.0 | 10.11.2 |
| **dynamic-classifier** | 11.7.0 | - |
| **evals-judge** | 11.7.0 | 10.11.2 |
| **speech-to-text** | 11.7.0 | 10.11.2 |
| **web-crawler** | 11.7.0 | 10.11.2 |

### AI extensions

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **modpod** | 11.0.1 | 10.0.7 |
| **observatory-api** | 11.29.4 | 10.7.2 |
| **observatory-platform** | 11.29.4 | 10.7.2 |
| **observatory-web** | 11.29.4 | 10.7.2 |

In FlowX.AI 6.0, the Observatory components run on environments operated by FlowX. They aren't included in client deployments in this release.

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart and deployed with the AI base group (see [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart)). Its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/6.x/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.252.0` for FlowX.AI 6.0.0). The native iOS and Android renderers version independently.

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **@flowx/angular-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/angular-theme** | 11.252.0 | 10.285.4 |
| **@flowx/angular-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/core-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/core-theme** | 11.252.0 | 10.285.4 |
| **solution-portal** | 11.252.0 | 10.285.4 |
| **iOS renderer** | 11.6.0 | 10.9.2 |
| **Android renderer** | 11.18.0 | 10.10.2 |

The **solution-portal** container app tracks the designer version.

***

## Configuration changes

This section compares environment variables, Kafka topics, and the `flowx-ai` Helm chart with FlowX.AI 5.9.6. It includes the changes that reached SaaS in 5.10 to 5.13, so a self-hosted upgrade from 5.9.6 needs only this page.

### New Kafka topics

Compared with 5.9.6, create these 42 topics. Create all of them, whatever your group flags: topics for services you don't deploy stay unused. On SaaS they are created and managed automatically.

**AI nodes as durable jobs:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.agent-node.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.progress.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.cancel.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Deep research node:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Validation findings:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.application-version.validation-findings.request-admin.v1` | application-manager → admin |
| `ai.flowx.application-version.validation-findings.request-cms.v1` | application-manager → cms-core |
| `ai.flowx.application-version.validation-findings.request-document-plugin.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.validation-findings.request-integration.v1` | application-manager → integration-designer |
| `ai.flowx.application-version.validation-findings.request-notification-plugin.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.validation-findings.request-application-manager.v1` | application-manager → application-manager |
| `ai.flowx.application-version.validation-findings.response.v1` | admin, cms-core, document-plugin, integration-designer, notification-plugin → application-manager |
| `ai.flowx.application-version.validation-findings.job-completed.v1` | application-manager → harness |

**Structured template data model:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |

**Runtime content import and export:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → embedder |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | embedder → integration-designer |

**Document classification and extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → none (dead-letter topic) |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | doc-parser → integration-designer |

**Event-triggered workflows:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Workflow schedules:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.workflow-schedules.updates.in.v1` | integration-designer → runtime-manager |
| `ai.flowx.core.notify.timer-event-schedule.state.v1` | scheduler-core → runtime-manager |

**Bulk instance migration and move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

**Designer notifications and preferences:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |
| `ai.flowx.eventsgateway.user.notifications.v1` | designer-user → events-gateway |
| `ai.flowx.designer-user.user-preferences.v1` | designer-user → designer-user |

> [!NOTE]
>
> If your Kafka cluster uses ACLs, also give the new clients of these existing topics access:
>
> * `ai.flowx.application-version.sync.out.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.correction-after-app-operation.response.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1`: document-plugin

### New services

Compared with 5.9.6, the `flowx-ai` Helm chart adds four services. On SaaS they are provisioned and managed by FlowX.

| Service | Group | What it does | Dependencies |
| - | - | - | - |
| designer-user | `core` | Stores Designer user preferences, such as the last-used workspace, and delivers Designer notifications | MongoDB, Redis, Kafka |
| harness | `devtime` | Runs the Developer Agentic Harness | PostgreSQL, Redis, Kafka |
| ui-driver | `devtime` | Renders UI flows in the background for the Developer Agentic Harness | None |
| dynamic-classifier | `runtime` | Classifies documents with trained models | PostgreSQL, a persistent volume, Kafka |

The databases, secrets, and volume are in [New databases and secrets](#new-databases-and-secrets).

The harness reuses the platform's existing Redis, so nothing new is provisioned. It uses Redis to stream a running turn to every open Designer session and to cancel a turn from any harness pod. Without Redis, turns still run, but live progress and cancellation across pods don't work.

The harness also consumes the existing `ai.flowx.llm.config.changed.v1` topic, so a change to an organization's AI model settings reaches it right away. Without Kafka, it picks up the change when its cache expires.

### AI service groups in the Helm chart

The `flowx-ai` Helm chart groups the services into four groups. Each group has its own flag, `groups.<group>.enabled`:

| Group | Services |
| - | - |
| `core` | Core platform services |
| `base` | The AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and the bundled Qdrant |
| `devtime` | ai-analyst, ai-architect, ai-assistant, ai-designer, ai-developer, harness, kb-enrichment, planner, ui-driver |
| `runtime` | agent-builder, data-privacy, doc-converter, dynamic-classifier, evals-judge, speech-to-text, web-crawler. cee-pii is in this group but needs `services.cee-pii.enabled: true` as well |

The groups are the same as in 5.9.6. The 6.0.0 chart adds designer-user to `core`, harness and ui-driver to `devtime`, and cee-pii and dynamic-classifier to `runtime`. The `base` group is unchanged.

Set all four flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

> [!WARNING]
>
> **Set every group flag explicitly for self-hosted upgrades.** Don't rely on the chart's group defaults. The `devtime` and `runtime` services call the AI base services, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

### New databases and secrets

Compared with the `flowx-ai` Helm chart in 5.9.6, these services need new databases. Create a database only if its service's group is on. designer-user is in `core`, so every installation needs its database:

| Service | Group | Database user | Secret |
| - | - | - | - |
| agent-builder | `runtime` | PostgreSQL `agent_builder` | `flowx-postgres-agent-builder` |
| dynamic-classifier | `runtime` | PostgreSQL `dynamic_classifier` | `flowx-postgres-dynamic-classifier` |
| harness | `devtime` | PostgreSQL `harness` | `flowx-postgres-harness` |
| designer-user | `core` | MongoDB `designer-user` | `mongodb-designer-user-designer-user` |

Each database has the same name as its user. Each secret holds the user's password under the key `password`.

The webhook-gateway also connects to the existing `app-runtime` MongoDB database with the `app-runtime` user.

The `keycloak-flowx-realm-clients` secret needs four new keys, one for each new service account:

| Secret key | Keycloak client |
| - | - |
| `KEYCLOAK_DESIGNER_USER_CLIENT_SECRET` | `flowx-designer-user-sa` |
| `KEYCLOAK_AI_HARNESS_CLIENT_SECRET` | `flowx-ai-harness-sa` |
| `KEYCLOAK_NOTIFICATION_PLUGIN_CLIENT_SECRET` | `flowx-notification-plugin-sa` |
| `KEYCLOAK_DOCUMENT_PLUGIN_CLIENT_SECRET` | `flowx-document-plugin-sa` |

Other chart changes:

* **process-engine** needs read-only access (`s3:GetObject`) to the integration-designer bucket, to download the Kafka payloads that integration-designer stores there. The chart reads the access key ID from `global.flowx.s3.credentials.processEngine.accessKey` (default `flowx-process-engine-accesskey`) and the secret access key from the `flowx-process-engine-s3` secret, key `SecretAccessKey`.
* **dynamic-classifier** stores its data on a 20Gi `ReadWriteOnce` persistent volume claim, `dynamic-classifier-data`, and uses the `Recreate` deployment strategy, so an upgrade stops the old pod before the new one starts.
* **dynamic-classifier** reads an OpenAI API key for its LLM judge from the `dynamic-classifier-openai` secret, key `OPENAI_API_KEY`. The secret is optional: without it, the pod still starts and classification keeps working.
* The chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier. ai-gateway keeps its own.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map | none (required) |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today | `k1` |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index | `PT24H` |

### New object storage bucket: runtime content

Runtime content export and import stores its files in a new shared bucket, `runtime-content-bucket`. Application Manager creates the bucket on first use, Integration Designer writes export files and reads imports there, and the embedder reads and writes Knowledge Base vectors at the paths each request names. Grant all three services access to the bucket.

Browsers upload import files and download export files directly, through presigned URLs that Application Manager signs. By default it signs them with the internal storage endpoint, which only pods can reach, so set `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` to a storage endpoint that browsers can reach.

New variables on application-manager and integration-designer. Set the bucket on both, and the presign settings on application-manager only:

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_RUNTIMECONTENTBUCKET` | Bucket for runtime content export and import files | `runtime-content-bucket` |
| `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` | Storage endpoint used to sign the presigned upload and download URLs. Leave empty to sign with the internal storage endpoint | empty |
| `APPLICATION_FILESTORAGE_S3_PRESIGNREGION` | Region used to sign the presigned URLs | `us-east-1` |

For the full list of buckets, see [Data architecture](/6.x/docs/platform-overview/data-architecture#s3-compatible-object-storage-buckets).

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

New process-engine and audit-core variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

### Changed behavior: nosql-db-runner host restrictions cover MongoDB

The host restriction that relational data sources already had now applies to external MongoDB connections too. The nosql-db-runner checks every address a MongoDB host resolves to, including replica-set members and SRV targets, and rejects the connection if any of them is private. For FlowX Database and Unmanaged MongoDB data sources alike, it also rejects `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter. To match every document, pass `{"_id": {"$exists": true}}`.

nosql-db-runner variables (both already existed for relational data sources):

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SSRFALLOWEDHOSTS` | Hosts or CIDR blocks, separated by commas, that may connect even though they resolve to a private address. Addresses on the local machine or in a link-local range stay blocked | empty |
| `FLOWX_SSRFPROTECTIONENABLED` | Turns the host restriction on or off | `true` |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS`.

### Changed behavior: name placeholders in data-privacy

When data-privacy masks a person's name, the placeholder now carries the gender, for example `<NAME_F_1>` or `<NAME_M_1>`. When the name doesn't show the gender, the placeholder stays `<NAME_1>`. Prompts or scripts that match the old placeholder form need updating.

### Changed behavior: Workspace operations editor role replaced

The upgrade replaces the Workspace operations editor role with the [Workspace corrective actions editor](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix) role. Users and groups that had the old role get the new one automatically and keep access to process instance migration and move token. No action is needed.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

New audit-core variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/6.x/setup-guides/audit-setup-guide#configuring-elasticsearch).

### Changed default: IMAPS certificate verification in email-gateway

The email-gateway now verifies the certificate of every IMAPS server it connects to. A server must present a certificate signed by a trusted authority and matching its host name.

New email-gateway variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS` | Mail hosts that skip certificate verification, separated by spaces or commas. Use `*` to skip it for every host | empty |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Email triggers that read from an IMAP server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`.

### Changed default: AI node retry

AI nodes without retry settings of their own now retry when a dependency is temporarily unavailable, such as an LLM provider outage, a rate limit, or a lost connection. Permanent errors aren't retried, and deep research nodes never retry by default. A node's own retry settings replace the default.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_ENABLED` | Turns the default retry for AI nodes on or off | `true` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_MAXATTEMPTS` | Maximum retry attempts | `10` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_BACKOFFPERIOD` | Wait between attempts, as an ISO-8601 duration | `PT30S` |

### Upgrading from an older patch release

Upgrading from 5.9.5 or earlier? Apply the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries) as well. Two 5.9.6 changes affect the upgrade:

* **Build redeployment retries:** the queue of build deployments waiting for a retry moved from Redis to the application-manager PostgreSQL database, with a new topic, `ai.flowx.build.deployment-failed.v1`. Deployments waiting for a retry in Redis when you upgrade aren't moved to the new queue. Re-publish those builds after the upgrade.
* **advancing-controller management port:** `MANAGEMENT_SECURITY_ENABLED` is no longer read. Actuator endpoints on the management port, including Prometheus, answer without authentication.

> [!WARNING]
>
> Keep the advancing-controller management port, `8081`, off any public ingress.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](/release-notes/overview).


# Android SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/android

Migrate the FlowX Android renderer SDK from 5.9.x to 6.0.0.

## Android SDK migration guide

FlowX.AI 6.0 moves the Android SDK to `compileSdk` 37, Android Gradle plugin 9 and Kotlin 2.4, and aligns the SDK's names with the iOS and web SDKs. Update your build setup first, then the renamed SDK APIs.

### System requirements

* **minSdk = 26** (unchanged)
* **compileSdk = 37**

The SDK library was built using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 9.5.0**
* **[Gradle](https://gradle.org/releases/) 9.8.2**
* **[Kotlin](https://kotlinlang.org/) 2.4.21**

Your container app must build with at least:

* **Android Gradle Plugin 9.1.0**
* **Gradle 9.3.1** (the minimum depends on your Android Gradle Plugin version)
* **Kotlin 2.4**
* **JDK 17**

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Android Core KTX](https://developer.android.com/kotlin/ktx#core) | 1.16.0 | **1.19.1** |
| [Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) | 1.10.1 | **1.13.0** |
| [Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) | 2025.09.01 | **2026.09.00** |
| [Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) | 2.9.1 | **2.10.2** |
| [Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) | 2.9.1 | **2.11.0** |
| [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | 1.10.2 | **1.11.0** |
| [Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) | 1.1.7 | **1.3.0** |
| [Android Security](https://developer.android.com/jetpack/androidx/releases/security) | 1.1.0-beta01 | **1.1.0** |
| [OkHttp BOM](https://square.github.io/okhttp/) | 4.12.0 | **5.5.1** |
| [Retrofit](https://square.github.io/retrofit/) | 2.12.0 | **3.0.0** |
| [Coil BOM](https://coil-kt.github.io/coil/) | 3.4.0 | **3.6.3** |
| [Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) | 4.31.1 | **4.36.2** |
| [Mozilla Rhino](https://github.com/mozilla/rhino) | 1.8.0 | **1.9.2** |
| [Accompanist Permissions](https://google.github.io/accompanist/permissions/) | 0.37.3 | 0.37.3 |
| [Moshi](https://github.com/square/moshi) | 1.15.2 | 1.15.2 |
| [Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) | 2.1.5 | 2.1.5 |

> [!WARNING]
>
> The SDK now depends on **OkHttp 5** and **Retrofit 3**. Gradle resolves your app to these versions even if you declare OkHttp 4 or Retrofit 2, so update any code in your app that uses APIs removed in these major versions. Align your app's versions of these libraries with the SDK's versions to avoid compatibility issues.

### Migration steps

To build and run your container app with the 6.0 SDK, follow these steps in order:

**1. Update the SDK version**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
implementation("ai.flowx.android:sdk:<5.9.x version>") // [!code --]
implementation("ai.flowx.android:sdk:<6.0 version>") // [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Increase the `compileSdk` version to `37`**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileSdk = 35 // [!code --]
    compileSdk = 37 // [!code ++]
}
```

> [!NOTE]
>
> The SDK and its AndroidX, OkHttp and Coil dependencies require `compileSdk` 37. Raising `targetSdk` is not required.

**3. Update the `Android Gradle plugin` version to at least `9.1.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "8.10.0" apply false // [!code --]
    id("com.android.application") version "9.5.0" apply false // [!code ++]
}
```

> [!TIP]
>
> Android Gradle plugin 9 is a major release with breaking build changes. Consult the [Android Gradle plugin 9.0 release notes](https://developer.android.com/build/releases/agp-9-0-0-release-notes).

**4. Update the `Gradle` version**

```properties [rootProject]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.2-bin.zip # [!code ++]
```

> [!NOTE]
>
> Android Gradle plugin 9.1 requires at least Gradle 9.3.1, and 9.5 requires at least Gradle 9.6.0. Check the minimum for your version in the [Android Gradle plugin release notes](https://developer.android.com/build/releases/gradle-plugin).

**5. Remove the `Kotlin Android` plugin**

Android Gradle plugin 9 compiles Kotlin by itself (built-in Kotlin), so the `org.jetbrains.kotlin.android` plugin must be removed:

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code --]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") // [!code --]
}
```

> [!TIP]
>
> Consult the [Migrate to built-in Kotlin](https://developer.android.com/build/migrate-to-built-in-kotlin) guide.

**6. Update the `Kotlin` version to at least `2.4`**

With built-in Kotlin, your app compiles with the version of the Kotlin Gradle plugins you declare, such as the Compose Compiler plugin. The Kotlin version that Android Gradle plugin uses by default is too old to read the SDK's classes. Use the same version for every Kotlin Gradle plugin your project declares, such as Parcelize or Serialization.

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code --]
    id("org.jetbrains.kotlin.plugin.compose") version "2.4.21" apply false // [!code ++]
}
```

> [!WARNING]
>
> With an older Kotlin version, the build fails with an error like: `The binary version of its metadata is 2.4.0, expected version is 2.2.0`.

**7. Make sure core library desugaring is enabled**

The SDK requires core library desugaring. If your app does not enable it yet, add:

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**8. Rename the `imageBaseUrl` and `customHeaders` properties of the `Config` interface**

`imageBaseUrl` is now `assetsBaseUrl`, and `customHeaders` is now `additionalHttpHeaders`:

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
Flowx.getInstance().init(
    context = applicationContext,
    config = object : Config {
        ...
        override val imageBaseUrl = "URL to FlowX CMS Media Library" // [!code --]
        override val assetsBaseUrl = "URL to FlowX CMS Media Library" // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code --]
        override val additionalHttpHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code ++]
        ...
    },
    ...
)
```

> [!NOTE]
>
> The default value of the `locale` property changed from `Locale.getDefault()` to `Locale.forLanguageTag("en-US")`. If your app relies on the device locale for date, number and currency formatting, set it explicitly:
>
> ```kotlin theme={"dark"}
> override val locale: Locale = Locale.getDefault()
> ```

**9. Stop passing `null` to the `setAccessToken` method**

The `setAccessToken` method no longer accepts `null`:

```kotlin theme={"dark"}
fun setAccessToken(accessToken: String?) // [!code --]
fun setAccessToken(accessToken: String) // [!code ++]
```

Remove the calls that clear the token (for example, on logout or after a failed login):

```kotlin theme={"dark"}
Flowx.getInstance().setAccessToken(null) // [!code --]
```

A token can't be cleared once set. When another user logs in, set that user's token. If no token is ever set, the SDK runs in anonymous mode. For details, see the [Authentication](/6.x/sdks/android-renderer#authentication) section of the Android SDK reference.
\[!WARNING] Passing an empty string (`""`) no longer clears the token. The SDK sends it as is and the backend rejects the requests.

**10. Rename the `closeModalFunc` parameter to `onDismissRequested`**

The parameter of the `startProcess` and `continueProcess` methods was renamed. Its lambda now runs in the `ProjectScope` context:

```kotlin theme={"dark"}
Flowx.getInstance().startProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)

Flowx.getInstance().continueProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)
```

> [!TIP]
>
> Replace the deprecated `CloseModalProcessScope` type with `ProjectScope`, as described in the [Replace deprecated APIs](#replace-deprecated-apis) section.

**11. Rename the `imageBaseUrl` parameter of the `changeEnvironment` method (if used)**

```kotlin theme={"dark"}
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code --]
fun changeEnvironment(baseUrl: String, assetsBaseUrl: String, enginePath: String) // [!code ++]
```

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. The parameters are unchanged:

| Deprecated (5.9) | Replacement (6.0) | Available on |
| - | - | - |
| `CloseModalProcessScope` | `ProjectScope` | The `onDismissRequested` lambda of `startProcess` and `continueProcess` |
| `replaceSubstitutionTag` | `getSubstitutionTagContent` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getMediaResourceUrl` | `getMediaItemUrl` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getEnumeration` | `getEnumerationItems` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `executeAction` | `runAction` | `CustomComponentScope` |
| `executeUploadAction` | `runUploadAction` | `CustomComponentScope` |
| `configureUpdateState` | `setUpdateStateEnabled` | `Flowx` |

> [!TIP]
>
> Android Studio offers a **Replace with** quick fix on every deprecated call.

These changes are reflected in an actual implementation as shown below:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope // [!code --]
import ai.flowx.android.sdk.api.ProjectScope // [!code ++]

// close process confirmation alert
@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code --]
private fun ProjectScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code ++]
    ...
    Text(replaceSubstitutionTag("@@close_message")) // [!code --]
    Text(getSubstitutionTagContent("@@close_message")) // [!code ++]
}

// custom component
flowxScope.executeAction(action = it, params = JSONObject()) // [!code --]
flowxScope.runAction(action = it, params = JSONObject()) // [!code ++]

// custom loader
flowxScope.replaceSubstitutionTag(text) // [!code --]
flowxScope.getSubstitutionTagContent(text) // [!code ++]
flowxScope.getMediaResourceUrl(key) // [!code --]
flowxScope.getMediaItemUrl(key) // [!code ++]
```

## Related resources

> [card] [Android SDK reference](/6.x/sdks/android-renderer)
>
> Android renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Angular SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/angular

Migrate the FlowX Angular renderer SDK from 5.9.x to 6.0.0.

## Angular SDK migration guide

6.0 moves the Angular renderer to Angular 22 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new input and function names. The framework upgrade, the custom component input, and the removed `logSink` and `logCategories` inputs need code changes.

### Framework upgrade: Angular 21 → 22

Upgrade your host app **before** you bump the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide) from `21.0` to `22.0`.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Angular CLI and `@angular/*` | \~21 | **\~22** |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |
| TypeScript | ≥ 5.9, \< 6.1 | **≥ 6.0, \< 6.1** |

The FlowX Angular packages declare `@angular/*` ≥ 22.0.0 as peer dependencies, so `npm install` fails on an Angular 21 app.

### FlowX SDK changes

#### Renamed inputs and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` input | `baseUrl` |
| `processApiPath` input | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` input | `assetsBaseUrl` |
| `authToken` input | `accessToken` |
| `withConfig({ customLoader })` | `customLoaderProvider` (same shape) |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers.

```diff theme={"dark"}
 <flx-process-renderer
-  [apiUrl]="baseUrl"
-  [processApiPath]="'onboarding'"
-  [staticAssetsPath]="mediaLibraryUrl"
-  [authToken]="token"
+  [baseUrl]="baseUrl"
+  [enginePath]="'onboarding'"
+  [assetsBaseUrl]="mediaLibraryUrl"
+  [accessToken]="token"
   ...
 />
```

#### Custom components: `data$` → `input` signal

Custom components receive their data through an `input` signal input instead of the `data$` Observable. The process data moves under `input().data`, and actions run through `runAction` and the new `runUploadAction`. Both return an Observable.

| 5.9 | 6.0 |
| - | - |
| `data$` input (Observable) | `input` signal input |
| Data fields read from the top level (`data.<field>`) | `input().data.<field>` |
| `data.actionsFn.<name>(params)` | `input().runAction(name, params?)` |
| None | `input().runUploadAction(name, file, params?)` |

```typescript theme={"dark"}
import { Component, computed, input } from '@angular/core';
import { FlxCustomComponentData } from '@flowx/angular-sdk';

@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
})
export class CustomComponentComponent {
  input = input<FlxCustomComponentData>()
  client = computed(() => this.input()?.data.client)

  submit(file: Blob) {
    this.input()?.runAction('action_one', { amount: 3 }).subscribe();
    this.input()?.runUploadAction('upload_document', file, { side: 'front' }).subscribe();
  }
}
```

#### `logSink` and `logCategories` inputs removed

The `[logSink]` and `[logCategories]` inputs on `<flx-process-renderer>` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- [logSink]="formattedLogger"
- [logCategories]="['rest', 'sse']"
```

```typescript theme={"dark"}
import { formattedLogger, logSink } from '@flowx/core-sdk';

const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] });
```

`@flowx/angular-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Inputs removed or deprecated without replacement

| Input | Status in 6.0 |
| - | - |
| `legacyHttpVersion` | Deprecated, no replacement. Still honored. |
| `debugLogs` | Removed. It never had any effect. Use `logSink()` from `@flowx/core-sdk`. |

#### Behavior changes

* `baseUrl` is required on the process, UI Flow, chat and task management renderers, and `assetsBaseUrl` on the process, UI Flow and chat renderers. Without them, the renderer throws ``[FlowX] `baseUrl` is required.`` (or `` `assetsBaseUrl` ``) at start. The template compiler doesn't report a missing value.
* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [Angular SDK reference](/6.x/sdks/angular-renderer)
>
> Angular renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Helm chart
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart

Upgrade a FlowX.AI installation on the flowx-ai Helm chart from 5.9.x to 6.0.0.

> [!NOTE]
>
> FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

This page covers the Helm side of an upgrade from FlowX.AI 5.9.x to 6.0.0 for an installation that already runs on the `flowx-ai` Helm chart. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list every change in detail. This page puts the ones that need action in the order you do them.

> [!NOTE]
>
> If you still run the per-service charts or the `ai-platform` umbrella chart, move to the `flowx-ai` chart on 5.9.x first, as described in [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart). That migration recreates every workload. Doing it separately keeps the 6.0.0 upgrade a single `helm upgrade` of one release.

## Before you begin

* Read the [FlowX.AI 6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) and [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0).
* Get pull access to the `flowx-ai` chart at the chart version for 6.0.0. The chart version is the platform release.
* Take a backup of PostgreSQL, MongoDB, the object store, and the Qdrant collections right before the upgrade.
* If you run a container app with a FlowX renderer SDK, plan its upgrade with the [renderer SDK guides](./migration-overview#renderer-sdk-migration).

The commands on this page read the namespace from `NS`:

```bash theme={"dark"}
export NS={your-flowx-namespace}
```

## Update your values

**1. Set every group flag explicitly**

Don't rely on the chart's group defaults. Set all four group flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

`base` is the AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and Qdrant. The `devtime` and `runtime` services call it, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

For example, to install the core, base, and runtime services:

```yaml theme={"dark"}
groups:
  core:
    enabled: true
  base:
    enabled: true
  devtime:
    enabled: false
  runtime:
    enabled: true
```

See [AI service groups in the Helm chart](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#ai-service-groups-in-the-helm-chart) for the services in each group, and [How do the switches combine?](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#how-do-the-switches-combine) for how group and service flags combine.

**2. Provision databases and secrets for the services you turn on**

In 6.0.0, these services need their own database users and secrets: agent-builder, dynamic-classifier, and harness in PostgreSQL, and designer-user in MongoDB. Create them before the upgrade for every service your group flags turn on. designer-user is in the `core` group, so it always needs its database.

The `keycloak-flowx-realm-clients` secret needs four new client secret keys, whatever your group flags. authorization-system reads all four at startup and, when it has Keycloak admin access (the default), creates the matching service-account clients with those secrets. If a key is missing, its database migration fails and authorization-system doesn't start. Without Keycloak admin access, create the four clients in Keycloak yourself.

See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the user, secret, key, and client names.

**3. Grant process-engine read access to the integration-designer bucket**

process-engine now reads Kafka payloads that integration-designer stores in its bucket. Give the process-engine credentials `s3:GetObject` on that bucket. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the secret names.

**4. Set a bucket name for dynamic-classifier**

If you turn on dynamic-classifier, set its bucket under `services.dynamic-classifier.component.s3.applicationFileStorage.bucketName`. The chart sets no bucket names, as described in [Migrate S3 buckets](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#migrate-s3-buckets). dynamic-classifier also stores data on a 20Gi `ReadWriteOnce` volume, so your cluster needs a storage class that can provide one.

Unlike the Qdrant volumes, this claim is part of the Helm release. `helm uninstall`, or deleting the Argo CD Application with cascading deletion, deletes it, and with a `Delete` reclaim policy its data too.

**5. Move callers off the removed admin Ingress routes**

If you route with Kubernetes Ingress, the chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier, and the upgrade deletes the existing ones. ai-gateway keeps its own. Platform services and frontends don't use these routes. If anything outside the cluster calls one of these paths on the admin host, such as `/speech-to-text`, move it to the service's in-cluster address before you upgrade.

Installations that use the Gateway API aren't affected.

**6. Allow private MongoDB hosts**

nosql-db-runner now applies its host restriction to external MongoDB connections. Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS` on nosql-db-runner. See [nosql-db-runner host restrictions](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).

**7. Trust your IMAP servers' certificates**

email-gateway now verifies the certificate of every IMAPS server it connects to. Email triggers that read from a server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`. See [IMAPS certificate verification](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway).

**8. Keep the management port private**

Upgrading from 5.9.5 or earlier? Since 5.9.6, advancing-controller no longer reads `MANAGEMENT_SECURITY_ENABLED`, and the actuator endpoints on its management port, `8081`, including Prometheus, answer without authentication. Check that no public Ingress or Gateway route exposes that port. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).

**9. Set the personal-data encryption key**

In 6.0.0, integration-designer needs `FLOWX_PII_ENCRYPTION_MASTER_KEY` for the Mask Personal Data and Restore Personal Data nodes. The variable has no default and the chart doesn't set it, so without it those nodes fail when a workflow runs them. Store a strong random value in a secret under the key `FLOWX_PII_ENCRYPTION_MASTER_KEY`, and load the secret into integration-designer:

```yaml theme={"dark"}
services:
  integration-designer:
    extraEnvVarsSecret: {your-pii-secret-name}
```

Keep the value identical on every pod and stable over time: changing it invalidates every in-flight placeholder map. See [Personal-data encryption master key](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-required-secret-personal-data-encryption-master-key).

**10. Choose how Elasticsearch replicates new indices**

In 6.0.0, process-engine and audit-core create new indices with the Elasticsearch `auto_expand_replicas` setting `0-1`, which overrides `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS`. On a cluster with two or more data nodes, the replica roughly doubles the disk space these indices use. To keep a fixed replica count instead, turn auto-expansion off on both services:

```yaml theme={"dark"}
services:
  process-engine:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
  audit-core:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
```

See [Elasticsearch replica auto-expansion](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-elasticsearch-replica-auto-expansion).

**11. Create the new Kafka topics**

New capabilities since 5.9.x depend on new Kafka topics. Create them before you upgrade. The 6.0.0 [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics) list every topic added since 5.9.6. Upgrading from 5.9.5 or earlier? Also create `ai.flowx.build.deployment-failed.v1`, added in 5.9.6. If your cluster uses ACLs, also give the new clients of three existing topics access, as listed in the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics).

If the chart creates your topics, add the new names to the list under `global.flowx.kafka.topics.topics`. The chart creates topics only when `global.flowx.kafka.topics.enabled` is `true`, as Strimzi `KafkaTopic` resources with 3 partitions and 3 replicas unless you set other values under `global.flowx.kafka.topics.defaults`:

```yaml theme={"dark"}
global:
  flowx:
    kafka:
      topics:
        enabled: true
        topics:
          - ai.flowx.build.deployment-failed.v1
```

## Render and compare

Render the 6.0.0 chart with your updated values before you upgrade, and compare it with what runs today:

```bash theme={"dark"}
helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml
```

Check that the rendered Deployments are the services you expect. A missing AI base service, or an AI runtime service you didn't plan for, means a group flag isn't set. The render fails if your values still contain top-level `devtime` or `runtime` keys, or service keys outside `services`. See [Render and compare](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#render-and-compare) for commands that compare environment variables per Deployment.

Using a mirrored or air-gapped registry? List the images the render references, mirror them, and point the chart at your registry with `global.imageRegistry`, as described in [Container images and registry](/6.x/setup-guides/setup-guides-overview#container-images-and-registry):

```bash theme={"dark"}
grep -E '^\s+image:' rendered.yaml | sort -u
```

## Upgrade

Run `helm upgrade` on your `flowx-ai` release with the 6.0.0 chart version and your updated values:

```bash theme={"dark"}
helm upgrade {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml
```

dynamic-classifier uses the `Recreate` deployment strategy, so its old pod stops before the new one starts.

## After the upgrade

* **Upgrading from 5.9.5 or earlier: re-publish builds that were waiting for a retry.** The retry queue for failed build deployments moves from Redis to PostgreSQL, and deployments waiting in Redis are not moved. 5.9.6 already uses the PostgreSQL queue. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).
* **Check component versions.** In FlowX.AI Designer, go to **Platform Status** and compare the versions with the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#component-versions).
* **Check files from before the upgrade.** Open a process attachment, a media library asset, and a knowledge base document, and confirm they load. A bucket-not-found error in the logs points at a bucket name that didn't carry over.
* **Update name placeholders.** data-privacy now masks names with gendered placeholders, such as `<NAME_F_1>`. Update prompts or scripts that match the old form. See [Name placeholders in data-privacy](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy).
* **Expect a new workspace role name.** Users and groups with the Workspace operations editor role now have the Workspace corrective actions editor role, and keep access to process instance migration and move token. See [Workspace operations editor role replaced](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-workspace-operations-editor-role-replaced).

## Related resources

> [card] [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)
>
> Component versions and every deployment-level change in 6.0.0

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single chart


# iOS SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/ios

Migrate the FlowX iOS renderer SDK from 5.9.x to 6.0.0.

## iOS SDK migration guide

FlowX.AI 6.0 aligns the names of five iOS SDK APIs with the Android and web SDKs. The build requirements and library dependencies are unchanged, and the 5.9 names still compile, so your app builds with the 6.0 SDK after you update the pod version. Replace the deprecated names afterwards.

### System requirements

| Requirement | 5.9.x | 6.0 |
| - | - | - |
| Minimum iOS | iOS 15 | iOS 15 |
| Swift | 5.9 | 5.9 |

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Alamofire](https://github.com/Alamofire/Alamofire) | `~> 5.9.0` | `~> 5.9.0` |
| [SDWebImageSwiftUI](https://github.com/SDWebImage/SDWebImageSwiftUI) | 3.0.3 | 3.0.3 |
| [SDWebImageSVGCoder](https://github.com/SDWebImage/SDWebImageSVGCoder) | `~> 1.7.0` | `~> 1.7.0` |

### Migration steps

**1. Update the SDK version**

```ruby Podfile theme={"dark"}
pod 'FlowXRenderer', '<5.9.x version>' # [!code --]
pod 'FlowXRenderer', '<6.0 version>' # [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Replace the deprecated APIs**

Replace the 5.9 names with the 6.0 names listed in the [Replace deprecated APIs](#replace-deprecated-apis) section. The parameters, types and behavior are unchanged.

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. `imageBaseURL` is a property of `FXConfig`; the others are methods of `FlowX.sharedInstance`:

| Deprecated (5.9) | Replacement (6.0) |
| - | - |
| `imageBaseURL` | `assetsBaseURL` |
| `updateAuthorization(token:)` | `setAccessToken(token:)` |
| `getTag(withKey:)` | `getSubstitutionTagContent(key:)` |
| `getEnumeration(name:parentName:)` | `getEnumerationItems(name:parentName:)`, async and completion versions |
| `continueExistingProcess(uuid:name:…)` | `continueProcess(uuid:name:…)`, all three versions |

> [!TIP]
>
> Xcode shows a deprecation warning on every deprecated call, with a **Fix-it** that replaces it with the new name.

These changes are reflected in an actual implementation as shown below:

```swift theme={"dark"}
// configuration
FXConfig.sharedInstance.configure { config in
    config.imageBaseURL = myImageBaseURL // [!code --]
    config.assetsBaseURL = myAssetsBaseURL // [!code ++]
}

// authorization token changes
FlowX.sharedInstance.updateAuthorization(token: accessToken) // [!code --]
FlowX.sharedInstance.setAccessToken(token: accessToken) // [!code ++]

// substitution tags
FlowX.sharedInstance.getTag(withKey: "@@close_message") // [!code --]
FlowX.sharedInstance.getSubstitutionTagContent(key: "@@close_message") // [!code ++]

// enumerations
let items = await FlowX.sharedInstance.getEnumeration(name: "cities", parentName: "countries") // [!code --]
let items = await FlowX.sharedInstance.getEnumerationItems(name: "cities", parentName: "countries") // [!code ++]

// resuming a process
FlowX.sharedInstance.continueExistingProcess(uuid: uuid, // [!code --]
FlowX.sharedInstance.continueProcess(uuid: uuid, // [!code ++]
                                     name: processName,
                                     navigationController: processNavigationController,
                                     isModal: true)
```

## Related resources

> [card] [iOS SDK reference](/6.x/sdks/ios-renderer)
>
> iOS renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Overview
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview

Migration guide for upgrading container apps and the flowx-ai Helm chart from FlowX.AI 5.9.x to 6.0.0

FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

> [!WARNING]
>
> A FlowX.AI 6.0.0 renderer SDK can need a newer framework version in your container app. Check the guide for your SDK, and upgrade the host app before you bump the FlowX SDK.

## Who is affected

Teams that run a container app with a FlowX renderer SDK (Angular, React, iOS, Android, or React Native) and move it to FlowX.AI 6.0.0. See [Renderer SDK migration](#renderer-sdk-migration).

Teams that run FlowX.AI on the `flowx-ai` Helm chart and upgrade it from 5.9.x to 6.0.0. See [Helm chart upgrade](#helm-chart-upgrade).

Teams with business rules, reusable functions, or workflow scripts that still run on the GraalVM script engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

## What's changing

An upgrade to 6.0.0 touches up to three areas, depending on what you run:

* **Helm chart:** set every AI service group flag explicitly, and create databases and secrets for the new services that need them. See [Helm chart upgrade](#helm-chart-upgrade).
* **GraalVM script engine:** deprecated. Scripts on GraalVM keep running after this upgrade, now with the same time limit as the native engine, and 6.1.x is the last release family that supports the engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).
* **Renderer SDKs:** container apps upgrade the FlowX renderer SDK, and the host framework where the SDK needs it. See [Renderer SDK migration](#renderer-sdk-migration).

## Migration process

Follow these steps in order, and skip the ones for areas you don't run.

**1. Check your starting point**

Upgrade to 6.0.0 from FlowX.AI 5.9.x on the `flowx-ai` Helm chart. If you still run the per-service charts or the `ai-platform` umbrella chart, first [migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart) on 5.9.x, as a separate change.

**2. Read the release notes and deployment guidelines**

The [release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) list what changes in 6.0.0. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list the component versions, environment variables, and other configuration changes. The [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog) lists every feature change since 5.9.x, including the 5.10 to 5.13 feature releases.

**3. Prepare the infrastructure**

Create what the 6.0.0 services need before the upgrade window: new PostgreSQL and MongoDB database users and their secrets, four new keys in the `keycloak-flowx-realm-clients` secret, read access for process-engine to the integration-designer bucket, and storage for a 20Gi `ReadWriteOnce` volume if you turn on dynamic-classifier. Create the new Kafka topics, or list them for the chart to create. Also set the personal-data encryption key for integration-designer, choose how Elasticsearch replicates new indices, and allow the private MongoDB hosts and IMAP servers that existing connections use. [Before you upgrade a self-hosted installation](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#before-you-upgrade-a-self-hosted-installation) is the full checklist, and [Update your values](./helm-chart#update-your-values) walks through each item.

**4. Check GraalVM scripts and plan the move off GraalVM**

Scripts on GraalVM keep running, but from 6.0.0 they stop at the same time limit as the native engine. Before the upgrade, check the scripts that can run longer than the limit, or raise it. Then plan their move to the native engine, as described in [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

**5. Back up**

Take the backups listed in [Before you begin](./helm-chart#before-you-begin) right before the upgrade.

**6. Upgrade the Helm release**

Update your values and upgrade the release, as described in [Helm chart](./helm-chart).

**7. Upgrade your container apps**

For each container app, upgrade the host framework first if the SDK needs it, then the FlowX renderer SDK. See [Renderer SDK migration](#renderer-sdk-migration). Container apps on a 5.9.x renderer SDK keep running against a 6.0.0 backend, but screens can render incorrectly wherever 6.0.0 changed behavior. Release the upgraded apps in the same window as the Helm upgrade. For iOS and Android apps, end users who don't install the app update stay on the 5.9.x SDK, so plan how you move them to the new version.

## Helm chart upgrade

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single `flowx-ai` chart

> [card] [Helm chart](./helm-chart)
>
> Upgrade an installation on the `flowx-ai` Helm chart from 5.9.x to 6.0.0

## Move scripts off the GraalVM engine

The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine for JavaScript and Python. Scripts that run on GraalVM keep running after the upgrade to 6.0.0, but they now stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0, a GraalVM script had no time limit. Before you upgrade, check the GraalVM scripts that can run longer than these limits, or raise the limits, as described in [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits). Then plan the move to the native engine.

**1. Find the scripts that run on GraalVM**

Business rules and reusable functions created before the move to the native engine run on GraalVM unless you switched them. The engine selector in each rule's script editor shows the engine it runs on. Workflow scripts run on GraalVM only if `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`.

**2. Test each script on the native engine**

The two engines don't always write the same output. Follow the step-by-step list in [Port a script from GraalVM to native](/6.x/docs/building-blocks/supported-scripts#port-a-script-from-graalvm-to-native), check the [common pitfalls](/6.x/docs/building-blocks/supported-scripts#common-pitfalls), and search scripts for Python imports the native engine blocks, such as `os` and `subprocess`, JavaScript `require(...)`, `process`, or `global`, and calls into Java classes such as `Java.type(...)`. The native engine supports none of these.

**3. Switch to the native engine**

Switch business rules [per rule](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule). Move a reusable function and the rules that call it together: a function written for GraalVM fails when a rule on the native engine calls it. For workflow scripts, remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer`. The default is `native`.

## Renderer SDK migration

> [card] [Angular SDK](./angular)
>
> Migrate the Angular renderer SDK to 6.0.0

> [card] [React SDK](./react)
>
> Migrate the React renderer SDK to 6.0.0

> [card] [iOS SDK](./ios)
>
> Migrate the iOS renderer SDK to 6.0.0

> [card] [Android SDK](./android)
>
> Migrate the Android renderer SDK to 6.0.0

> [card] [React Native SDK](./react-native)
>
> Migrate the React Native renderer SDK to 6.0.0


# React SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react

Migrate the FlowX React renderer SDK from 5.9.x to 6.0.0.

## React SDK migration guide

6.0 moves the React renderer to Node 26 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new prop and function names. The `logSink` and `logCategories` renderer props are removed and need a code change.

### Framework requirements

React stays on 19. Upgrade Node in your build and CI environments.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| React | 19 | 19 |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |

### FlowX SDK changes

#### Renamed props and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` prop | `baseUrl` |
| `processApiPath` prop | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` prop | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customLoader` prop | `customLoaderProvider` (same shape) |
| UI Flow `appInfo.selectedProcessResourceId` | `resourceId` |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `useEnumeration(name, parentName?)` | `useEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers. `customLoaderProvider` applies to the process and UI Flow renderers.

```diff theme={"dark"}
 <FlxProcessRenderer
-  apiUrl={baseUrl}
-  processApiPath="onboarding"
-  staticAssetsPath={mediaLibraryUrl}
-  authToken={token}
+  baseUrl={baseUrl}
+  enginePath="onboarding"
+  assetsBaseUrl={mediaLibraryUrl}
+  accessToken={token}
   ...
 />
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, file, params?)` to upload a file through an upload action. `params` are sent as extra form fields beside the file.

```typescript theme={"dark"}
input.runAction('action_one', { amount: 3 })
input.runUploadAction('upload_document', file, { side: 'front' })
```

`FlxCustomComponentData` is now generic (`FlxCustomComponentData<TFile = Blob>`) and requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### `logSink` and `logCategories` props removed

The `logSink` and `logCategories` props on `FlxProcessRenderer` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- <FlxProcessRenderer logSink={formattedLogger} logCategories={['rest', 'sse']} ... />
+ import { formattedLogger, logSink } from '@flowx/core-sdk'
+
+ const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] })
```

`@flowx/react-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Props removed or deprecated without replacement

| Prop | Status in 6.0 |
| - | - |
| `legacyHttpVersion` on the process renderer | Deprecated, no replacement. Still honored. |
| `legacyHttpVersion` on the UI Flow renderer | Removed. It never had any effect. |
| `customHeaders` | Removed. It never had any effect. |
| `updateStateEnabled` | Removed. It never had any effect. |
| `isAnonymousMode` | Removed. It never had any effect. |
| `fw` | Removed. It never had any effect. |

Delete the removed props from your process and UI Flow renderer props.

#### Behavior changes

* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [React SDK reference](/6.x/sdks/react-renderer)
>
> React renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# React Native SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react-native

Migrate the FlowX React Native renderer SDK from 5.9.x to 6.0.0.

## React Native SDK migration guide

6.0 moves the validated React Native target to Expo SDK 57 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new configuration and prop names. The Android Material 3 date picker opt-in is removed.

### Prerequisites and version range

The peer dependency floors are unchanged: `react-native` ≥ 0.83.0 and `react` ≥ 19.2.0. The validated target moves up one Expo SDK.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Validated target | Expo SDK 56, React Native 0.85.3 | **Expo SDK 57, React Native 0.86.3** |
| React | 19.2.3 (Expo SDK 56 pin) | 19.2.3 (Expo SDK 57 pin) |
| `react-native-blob-util` | ^0.24.9 | **^0.25.1** |
| `@react-native-community/datetimepicker` | Required peer | **No longer used** |

For an Expo project, align the project to Expo SDK 57, then reinstall the FlowX packages with `npx expo install`:

```bash theme={"dark"}
npx expo install expo@^57.0.0 --fix
```

For the full install command and the Expo SDK 57 reference versions, see the [React Native SDK reference](/6.x/sdks/react-native-renderer).

### FlowX SDK changes

#### Renamed configuration options and props

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `FlxConfig.baseURL`, `apiUrl` prop | `baseUrl` |
| `processApiPath` | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customHeaders` | `additionalHttpHeaders` |
| `customLoader` | `customLoaderProvider` (same shape) |
| `customStepperHeader` | `customStepperHeaderProvider` (same component) |
| `configure({ locale, language })` | `FlowX.changeLocaleSettings(locale?, language?)` |
| `configure({ updateStateEnabled })` | `FlowX.setUpdateStateEnabled(enabled)` |
| `setAccessToken(token: string)` | `setAccessToken(token?: string \| null)`: `null`, `undefined` or `''` switches to anonymous access |
| `processUuid` prop | `processInstanceUuid` |
| `onClose(name?)` | `onDismissRequested(name?)` (same argument) |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl`, `enginePath` and `assetsBaseUrl` apply to `FlowX.configure` and to the process, UI Flow and chat renderers. `onDismissRequested` applies to `startProcess`, `continueProcess`, `startUiFlow` and the process and UI Flow renderers.

In 5.9 the content helpers came only from `@flowx/core-sdk/rn`. `@flowx/react-native-sdk` now exports them too, under their new names only (`getEnumerationItems`, `getMediaItemUrl`, `getSubstitutionTagContent`).

```diff theme={"dark"}
 FlowX.configure({
-  baseURL: 'https://api.example.com',
-  processApiPath: 'onboarding',
-  staticAssetsPath: 'https://media.example.com',
-  customHeaders: { 'x-tenant': 'acme' },
-  language: 'en',
-  locale: 'en-US',
+  baseUrl: 'https://api.example.com',
+  enginePath: 'onboarding',
+  assetsBaseUrl: 'https://media.example.com',
+  additionalHttpHeaders: { 'x-tenant': 'acme' },
   organizationId,
 })
+FlowX.changeLocaleSettings('en-US', 'en')
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, { uri, name, type }, params?)` to upload a file through an upload action.

`FlxCustomComponentData` requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### Android Material 3 date picker removed

The opt-in Material 3 date picker for `FlxDatePicker` on Android is removed, along with the `@react-native-community/datetimepicker` peer dependency.

* Remove `material3` from any `configureFlxUiToolkit` call.
* The `@react-native-community/datetimepicker` package is no longer needed by FlowX. Uninstall it if nothing else in your app uses it.
* Keep the `@flowx/react-native-ui-toolkit` Expo config plugin registered. It no longer changes `AppTheme` or sets `extra.flxUiToolkit.material3`. It now adds `fontScale` to the main activity's `android:configChanges` and declares the microphone permissions used by chat voice input. Run `npx expo prebuild` again after the upgrade.

#### Behavior changes

* A session with no usable access token now starts as anonymous instead of failing. In 5.9, a token that was `null`, `undefined` (never set) or an empty string (`''`) made the start throw `Call FlowX.setAccessToken(...) before starting a process.` In 6.0 all three values start an anonymous session, and a backend that requires a token answers `401`. If your token fetch can return `null`, `undefined` or `''`, check the value before you start a process; otherwise the failure only shows up later as a `401`.
* Error and warning messages name `baseUrl` and `assetsBaseUrl` instead of `baseURL` and `staticAssetsPath`. Update any host code that matches on their text.

## Related resources

> [card] [React Native SDK reference](/6.x/sdks/react-native-renderer)
>
> React Native renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# FlowX.AI 6.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026

What's new in FlowX.AI 6.0: the Developer Agentic Harness builds story by story, plus bulk process-instance migration, scheduled workflows, and certificates.

[FlowX.AI 6.0.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/hero-6.0.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 6.0 is a feature release, live on FlowX.AI SaaS. Self-hosted installations usually wait for the next LTS release family, and can also upgrade to 6.0.0 now: see [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

> [!WARNING]
>
> **Check your existing apps:** 6.0.0 changes how AI node prompts and retries, substitution tags, FlowX Database writes, masked names, IMAPS email triggers, evaluations, 5.1.x exports, and GraalVM scripts behave. See the [upgrade actions](/release-notes/v6.x/5.9-to-6.0-changelog) for what to check in each. Coming from 5.9.x? On the same page, also check the **Changed** entries for 5.10 to 5.13.

> [accordion] What changed since 5.13.0
>
> | 5.13.0 | 6.0.0 |
> | - | - |
> | The harness built the whole approved plan in one run | **Story-by-story delivery**: build one slice of the app, test it, then continue |
> | Changes to the app were described in words | **Comment mode**: select a component in the running app and say what should change |
> | The Command Center and the AI buttons in each editor opened standalone AI agents | **One agent rail**: **⌘K** or the header toggle opens the harness, which uses those agents internally |
> | A workflow started only when a process or caller started it | **Scheduled workflows**: date or cycle schedules on the Start node |
> | TLS was configured with keystores, truststores, and a skip switch | **Trust and Identity**: choose what the host is checked against, and whether to present a client certificate |
> | The Issues Console checked resources only | **Version checks**: entry points, theme, and library dependencies |
> | Only version exports sent notifications | **Import and export notifications**: version imports, build exports, and build imports notify you too |
> | A substitution tag had to be a property's whole value | **Tags inside any text**: `${tag:key}` next to static text and process data |
> | An AI node failed as soon as its AI service or provider couldn't be reached | **AI node retries**: on by default, up to 10 times, 30 seconds apart |
> | The chat message was appended to the end of an AI node's prompt | **Chat message in prompts**: reference `${userMessage}` in **Context** where the agent should answer it |
> | Evaluations grouped test cases into datasets and checked outputs with Code evaluators | **Test cases and asserts**: tagged test cases per workflow, checked with asserts and LLM evaluators |
> | The embedding model was locked once a Knowledge Base held content | **Re-embedding**: change **Containing Personal Information** later and the content is re-embedded |
> | Exporting rows to a file needed a Script node | **Generate Tabular File node**: a CSV or XLSX file from an array of rows |
> | A FlowX Database index couldn't reject duplicate values | **Unique indexes**: **Enforce unique values** on one attribute or a compound key |
> | A sensitive configuration value was shown in the Designer after saving | **Sensitive values stay hidden**: the Designer shows `********` in its place |
> | GraalVM was a supported script engine | **GraalVM deprecated**: 6.1.x is the last release family that supports it |

### **Coming from 5.9.x**

Releases 5.10 to 5.13 shipped to SaaS first. An installation that moves from 5.9.x to 6.0.0 gets their features too, including the [corrective actions](#corrective-actions-on-running-instances) below. The highlights:

> [card] New data sources
>
> [PostgreSQL](/6.x/docs/platform-deep-dive/integrations/postgresql-database) and [Db2](/6.x/docs/platform-deep-dive/integrations/db2-database) databases, and [SOAP services](/6.x/docs/platform-deep-dive/integrations/soap-system) imported from a WSDL.

> [card] Document nodes in workflows
>
> [Fill a template](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) into a PDF or DOCX, [combine](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) or [split](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) PDFs, and [parse](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support) spreadsheets, CSV, XML, and JSON.

> [card] Multi-instance and triggered workflows
>
> Run [one subworkflow per array element](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) in parallel, and start a workflow from an [email or webhook trigger](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).

> [card] Workflow Instances page
>
> [Every workflow run in the project](/6.x/docs/projects/runtime/workflow-instances), filterable by status, date, and origin.

> [card] Branches and the Issues panel
>
> [Merge into any branch](/6.x/docs/projects/managing-applications/versioning#managing-branches), archive or delete branches, and [see validation findings](/6.x/docs/projects/managing-applications/checking-for-issues) in one panel.

> [card] Workflows as agent tools
>
> A Custom Agent node [calls FlowX workflows as tools](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run), each with a hint for when to use it.

Full list: the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog), and the [5.10](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026), [5.11](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026), [5.12](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026), and [5.13](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) release notes.

***

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > The Developer Agentic Harness is the Designer's AI agent: it surveys your app, plans the change, and builds it on its own branch.
> >
> > **Before 6.0:** the harness ran an approved plan as a single run, and a conversation stayed tied to the app and branch where you started it. **Now:** a plan can split the work into stories, each a slice of the app you can try on its own, delivered one story at a time. You can point at a component in the running app to ask for a change. Your conversations follow you across the Designer.
> >
> > Each story says how to test it and what the agent needs from you, so you check one working slice before the next one starts. Comment mode turns the running UI flow or process into the brief: select a component, say what should change, and the comment lands in the conversation with the component attached. A conversation writes to the project and branch set by the first change you confirm, wherever you navigate after that, and the agent asks before it reads beyond that target.
> >
> > > [!NOTE]
> > >
> > > **Removed:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors, such as **Generate** on the data model and the sparkle buttons in business rules, reusable functions, and Script nodes. Open the agent rail instead: press **⌘K** (**Ctrl+K** on Windows and Linux) or select the sparkle toggle in the header. The harness still uses those agents internally for focused generation work. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness#what-the-agent-can-see-and-change).
> >
> > <video>
> >   <track label="English" />
> > </video>
> >
> > See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
>
> > [tab] Key Features
> >
> > > [card] [Story-by-story delivery](/6.x/ai-platform/developer-agentic-harness#how-does-a-plan-with-stories-run)
> > >
> > > Implement the next story, test it with the steps the story gives, then continue with one story or all that remain.
> >
> > > [card] [Comment on the running app](/6.x/ai-platform/developer-agentic-harness#how-do-i-comment-on-the-running-app)
> > >
> > > Select **Comment** in the header, pick a component in the running UI flow or process, and say what should change.
> >
> > > [card] [Conversations that follow you](/6.x/ai-platform/developer-agentic-harness#sessions)
> > >
> > > Every conversation you have in the organization, searchable. Each keeps writing to the project and branch of its first confirmed change, wherever you navigate.
> >
> > > [card] [Asks before reading more](/6.x/ai-platform/developer-agentic-harness#what-happens-when-the-agent-asks-to-read-another-project)
> > >
> > > Read-only access to another project needs **Allow for this conversation**, and you can revoke it from the rail.
> >
> > > [card] [Attach your material](/6.x/ai-platform/developer-agentic-harness#attach-files-to-a-conversation)
> > >
> > > Give the agent PDF and DOCX briefs, screenshots, or BPMN diagrams to plan and build from.
> >
> > > [card] [Delete with a plan export](/6.x/ai-platform/developer-agentic-harness#delete-a-conversation)
> > >
> > > Deleting a conversation keeps its commits on the branch and offers **Export plan** for what wasn't run.
> >
> > > [card] [Entry points, handovers, and repairs](/6.x/ai-platform/developer-agentic-harness#entry-points-handovers-timeouts-and-repairs)
> > >
> > > The agent suggests an entry point and asks again before serving, adds handover buttons, times out workflow waits, and proposes a repair when a step fails, a limited number of times per step.
>
> SaaS

### **Corrective actions on running instances**

> [card] Corrective actions on running instances
>
> > [tab] Overview
> >
> > Corrective actions shipped in the 5.12 and 5.13 feature releases. They fix running process instances in place, without restarting them, from **Runtime** → **Runtime Control** → **Corrective Actions**.
> >
> > **Bulk process-instance migration** moves a filtered set of running instances from one build to another in one run, so a fix made in a newer build reaches instances already in flight. **Move token** takes the active token off the node the instances are stuck on and places it on another node of the same process, and the instances stay on their build.
> >
> > The **Workspace corrective actions editor** role grants both. It replaces the Workspace operations editor role, and the upgrade moves users and groups that had the old role to the new one.
> >
> > See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances) and [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
>
> > [tab] Key Features
> >
> > > [card] [Build to build, in bulk](/6.x/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > Pick the source build, the target build, and the instances to move, then review the eligible count and map any node missing from the target build before you start.
> >
> > > [card] [Move token](/6.x/docs/projects/runtime/active-process/move-token)
> > >
> > > Resume stuck instances from another node of the same process, on one or many instances at once.
> >
> > > [card] [Dedicated role](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix)
> > >
> > > Grant corrective actions without handing out workspace admin rights.
> >
> > > [card] [Notified when done](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification)
> > >
> > > The notification center reports when a bulk migration finishes.
>
> SaaS

### **New Designer header**

> [card] New Designer header
>
> **Before 6.0:** the branch selector, the version state, and **Commit Changes** sat in the project's top bar. **Now:** the header holds the project name, the **Config** / **Runtime** switch (**Config** to edit a version, **Runtime** for builds and their settings), the **Build with AI** and **Comment** toggles, and **Run project**, which starts the version's entry point. Branching, the current version, and **Commit Changes** move to a version block at the start of the footer on Config pages.
>
> ![Designer project on a Config page: the header shows the project name, the Config and Runtime switch, the Build with AI toggle, and Run project; the footer starts with the version block showing the main branch, the version name, and Start New Version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/designer-header-6-0.png)
>
> The Designer also opens the workspace you used last, and **Organization settings** is in the avatar menu. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
>
> SaaS

### **AI node retries**

> [card] AI node retries
>
> **Before 6.0:** an AI node failed as soon as its AI service or LLM provider couldn't be reached. **Now:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when the service is unreachable, the provider is unavailable or rate-limits the request, or the connection fails. Timeouts aren't retried by default, because the node may already have called its tools.
>
> Toggle **Allow Retry** on in the node's **Settings** to set your own count, interval, and exponential backoff. After the last retry, the workflow continues down the node's failure exit if one is connected. With **Allow Retry** on, the workflow run logs show each attempt on its own line.  See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
>
> SaaS

### **Knowledge Base re-embedding and entry lifecycle**

> [card] Knowledge Base re-embedding and entry lifecycle
>
> **Before 6.0:** the embedding model was locked once a Knowledge Base held content. **Now:** turning **Containing Personal Information** on or off later re-embeds the existing content with the new model. Search keeps using the current embedding while it runs, and content changes are locked until it finishes. If some documents fail, the Knowledge Base stays on its previous model and the header says how many weren't re-embedded.
>
> Entries also have their own lifecycle: **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested) and [disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
>
> SaaS

### **Chat message in AI node prompts**

> [card] Chat message in AI node prompts
>
> > [!WARNING]
> >
> > **Behavior change.** The chat message is no longer appended to the end of an AI node's prompt automatically. In chat-driven workflows, reference `${userMessage}` in the node's **Context** wherever the agent should answer the user's message.
>
> The message still reaches the model inside the input data when **Use only referenced values as input** is off. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
>
> SaaS

### **Evaluations: test cases replace datasets**

> [card] Evaluations: test cases replace datasets
>
> **Before 6.0:** test cases lived in datasets, and the Code evaluators checked outputs for an exact, JSON, or Levenshtein match. **Now:** each workflow has its own test cases, grouped by tags. Each case carries its checks: asserts for **equals** and **equals as JSON**, and LLM evaluators with a pass threshold. An experiment runs the test cases you select. See [Evaluations](/6.x/ai-platform/evaluations).
>
> > [!WARNING]
> >
> > **Behavior change.** The upgrade converts each dataset's test cases and keeps the dataset name as a tag, but adds no checks. An experiment skips a case with no enabled check, so add an assert or evaluator to each converted case before you run it. The Code evaluators are removed: use the **equals** assert in place of **Exact match**, and **equals as JSON** in place of **JSON match**. **Levenshtein** has no replacement. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
>
> SaaS

### **Scheduled workflows**

> [card] Scheduled workflows
>
> > [tab] Overview
> >
> > **Before 6.0:** an integration workflow started only when a process, a UI flow, or another caller started it. **Now:** add schedules to the workflow's **Start** node and it starts by itself at each fire time.
> >
> > Schedules fire once on a date or repeatedly on an ISO or cron cycle, and the dialog previews the next fire times in your local time zone. Saving a schedule or publishing a build never turns it on: activate it in **Runtime** → **Runtime Settings** → **Schedules**.
> >
> > See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
>
> > [tab] Key Features
> >
> > > [card] Date or cycle
> > >
> > > Fire once at a date and time, or repeatedly with an ISO or cron expression built from guided fields.
> >
> > > [card] Up to 50 per workflow
> > >
> > > Each schedule has a name that is unique on its workflow. Schedules are available on Output Focused workflows, which process structured input and output.
> >
> > > [card] Explicit activation
> > >
> > > A schedule fires only after you activate it on the **Schedules** page, for a workflow in the project's active build.
> >
> > > [card] Next fire times
> > >
> > > Check the previewed fire times before you save.
>
> SaaS

### **Certificates: trust and identity**

> [card] Certificates: trust and identity
>
> > [tab] Overview
> >
> > **Before 6.0:** a REST data source combined keystore, truststore, and a skip-verification switch in one TLS setup. **Now:** the **Certificates** panel has two independent parts. **Trust** decides what the host's certificate is checked against: **System CAs** (the default), a **Custom CA**, or **None (insecure)**. **Identity** is the client certificate FlowX presents for mutual TLS, turned on with **Present a certificate**.
> >
> > The same panel is available on File Storage data sources. Existing certificate settings are converted to the new model automatically.
> >
> > See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates) for when to use each option.
>
> > [tab] Key Features
> >
> > > [card] Trust per data source
> > >
> > > Changing trust on one data source leaves every other call verified as before.
> >
> > > [card] Mutual TLS when asked
> > >
> > > Present a client certificate only to hosts that require one.
> >
> > > [card] [File Storage too](/6.x/docs/platform-deep-dive/integrations/file-storage#certificates)
> > >
> > > S3-compatible storage uses the same Trust and Identity settings.
> >
> > > [card] Insecure, by name
> > >
> > > **None (insecure)** is labeled as such and accepted only on REST and File Storage data sources.
>
> SaaS

### **Generate Tabular File node**

> [card] Generate Tabular File node
>
> A new node under **Tools** in the workflow palette turns a workflow variable that holds an array of rows into a CSV or XLSX file, stored as a document linked to the workflow run. A workflow can now produce an export without a Script node. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
>
> SaaS

### **FlowX Database unique indexes**

> [card] FlowX Database unique indexes
>
> Toggle **Enforce unique values** when you add an index to reject documents that repeat a value already stored, on one attribute or on a compound key, with an option to exempt documents that leave the key empty. Existing duplicates are reported when you run **Apply Indexes**, before the index is created. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
>
> SaaS

### **Issues Console version checks**

> [card] Issues Console version checks
>
> **Before 6.0:** an Issues Console check, which validates the resources in a project version, covered processes, UI flows, and integration workflows. **Now:** it also checks the version itself: missing, broken, or mismatched entry points, a theme that isn't in the workspace, library builds that are missing directly or transitively, and dependencies the version doesn't use. Selecting a finding opens the version settings or the **Dependencies** page, where you fix it. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
>
> SaaS

### **Import and export notifications**

> [card] Import and export notifications
>
> The notification center now covers version imports and build exports and imports, alongside version exports and process instance migrations. Each operation notifies you when it starts and replaces that entry with its result: ready to download, imported, needs review with a conflict or excluded-resource count, failed, or timed out. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
>
> SaaS

### **Resource documentation**

> [card] Resource documentation
>
> Open **Documentation** from a resource's menu to give it a short description and longer Markdown documentation, written and previewed in the same window. Media Library assets in a project library get a description too, used as the image's alt text in the asset preview. Knowledge base stores, navigation areas, and user tasks in the process navigation panel have **Documentation** in their menus too. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
>
> SaaS

### **Sensitive values stay hidden**

> [card] Sensitive values stay hidden
>
> After you save a `value` configuration parameter with **Sensitive** on, the Designer shows `********` in place of the value in the parameters list, overrides, build details and lists, and the merge view. The real value is still used at runtime, and editing other fields keeps it. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
>
> SaaS

### **Substitution tags inside any text**

> [card] Substitution tags inside any text
>
> > [tab] Overview
> >
> > **Before 6.0:** a substitution tag resolved only when it was the whole value of a property, so `@@greeting ${firstName}` rendered as empty text. **Now:** write `${tag:key}` anywhere in a component's text, next to static text and process data, and the renderer fills in every tag: `${tag:greeting}, ${firstName}!` renders as "Hello, John!".
> >
> > The upgrade rewrites whole-value `@@key` references to `${tag:key}` in processes, UI flows, and reusable templates, so existing screens render as before. `@@key` keeps working as a whole value.
> >
> > See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).
>
> > [tab] Key Features
> >
> > > [card] Tags, text, and data together
> > >
> > > Use several tags and process data placeholders in one label, placeholder, message, validator message, or option label.
> >
> > > [card] Existing references converted
> > >
> > > Whole-value `@@key` references become `${tag:key}`. Option values and the default of choice components stay `@@key`.
> >
> > > [card] Task Manager columns
> > >
> > > A column value of exactly `${tag:key}` shows, filters, and sorts like `@@key`.
> >
> > > [card] Import from and export for 5.9
> > >
> > > Importing from 5.9 converts `@@key` forward. Exporting for 5.9 converts whole-value tags back to `@@key`.
>
> SaaS

### **GraalVM script engine deprecated**

> [card] GraalVM script engine deprecated
>
> The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports it, for every JavaScript and Python script: business rules, reusable functions, workflow Script nodes, and the rest. Scripts that run on GraalVM keep working in 6.0.0. Move them to the native engine, the default since 5.9.0, before support ends. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).
>
> **Time limits on GraalVM too:** scripts that run on GraalVM now stop at the same per-language time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default, set on the process engine and Integration Designer with `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` and `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`. Before 6.0.0, a GraalVM script had no time limit. A script that runs past its limit is stopped and fails with an error saying it did not finish within its time limit. Before you upgrade, check GraalVM scripts that can run longer than these limits, or raise the limits. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
>
> All Deployments

### **Smaller improvements**

> [card] Smaller improvements
>
> **Auto-arrange on both canvases:** select **Auto-arrange** on the workflow canvas, or **Arrange** on the process canvas, to see a tidied layout in the **Layout preview** bar before anything moves. Compare it with the current layout, then **Apply** or **Cancel**. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).&#x20;
>
> **Timers in local time:** timer nodes now use the same editor as workflow schedules. Dates and times you pick are in your local time and saved in UTC, one control switches between **Guided**, **Expression**, and **Process variable** entry, and cycle timers preview their next fires. Timers saved with the earlier date pickers can look shifted by your UTC offset in the panel, but they still fire at their stored time. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).&#x20;
>
> **Longer branch names:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).&#x20;
>
> **Organization branding:** a **Branding** page under **Organization settings** > **Customization** sets one brand for the organization: name, logos, legal and social links, container app colors and header, and the sender, signature, and text of the invite, verify email, and reset password emails, with a preview of each. Login page and email branding are available on FlowX SaaS only. See [Organization branding](/6.x/docs/saas/organization-branding).&#x20;
>
> **Typed dates in the Datepicker:** turn on **Allow manual input** to let users type a date in the pattern of the project's default locale instead of picking it. Web only, and not available while **Legacy component** is on.&#x20;
>
> **Data mapping creates data types:** type a new attribute path such as `client.address.street`, and saving the mapping creates the data types it names. Until then, the mapper marks them as not yet added to the data model. Required rows show an asterisk, and mapping an object onto a primitive field shows an error.&#x20;
>
> **Removed fields stay removed:** when a node's output sets a field to `null`, the field is removed from the workflow data and later steps no longer restore it with a `null` value. If a condition checks for `null`, make it handle a missing field too.&#x20;
>
> **Keys with dots stay whole:** a data key that contains a dot, such as `cash|31.12.2025`, now stays one key when a workflow saves its data. Before, the key was split into nested objects and later nodes could not read it.&#x20;
>
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, and Kafka topics, see [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0). To upgrade the Helm chart or a renderer SDK, follow [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).


# FlowX.AI 4.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025

FlowX.AI 4.7.0 is here to keep your projects vibing, your merges drama-free, and your configs under control—because struggling with your platform is *so* last season. 😎🔥

## What's new? 🆕

✅ Copy resources across projects\
✅ Duplicate resources (in the same project/library)\
✅ Resources usage tracking\
✅ Smarter merge conflict detection & resolution\
✅ Libraries can now define configuration parameters\
✅ Dynamic Kafka topics using configuration parameters

## Projects

### Copy resources across projects

Moving resources between projects is now **fast and seamless**. The new **Copy to Another Project** feature ensures all dependencies stay intact, eliminating the hassle of manual adjustments.

<video />

> [tab] How it works
>
> 1️⃣ **Select a destination** – Choose the target project or library.\
> 2️⃣ **Pick a branch (if applicable)** – For WIP versions, select the target branch.\
> 3️⃣ **Review dependencies** – The system displays referenced resources and validates dependencies.\
> 4️⃣ **Resolve identifier conflicts** – If an identifier already exists in the destination, you'll be prompted to either:
>
> * **Keep both** (create a duplicate)
> * **Replace** (overwrite the existing resource)
> * **Use destination** (retain the existing resource without copying)

> [tab] Why it’s better
>
> * **No broken references** – Everything stays connected.
> * **Auto-add missing dependencies** – No manual setup required.
> * **Works with WIP & committed versions (only from committed to WIP)** – Flexibility for your workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.48.33.png)

> [card] [Copy resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Duplicate resources

> [tab] What you can duplicate
>
> The **Duplicate Resource** feature lets users create a copy of an existing resource within the same project or library version, streamlining workflows and ensuring quick reusability.
>
> <video />
>
> You can duplicate the following resources:
>
> * **Processes**
> * **Enumerations**
> * **Media files (including Global media library files)**
> * **Notification templates**
> * **Document templates**
> * **Views**

> [tab] How it works
>
> * **Duplicate options** are available from each resource’s three-dot menu (table row & secondary navigation).
> * When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).
> * **Cancel** to discard changes or **Duplicate** to create an exact copy in the same project/library version.
> * **Success confirmation:** The system navigates to the newly created resource and displays a success message.
> * **Error handling:** If a resource with the same name/key exists, users will be prompted to rename it before proceeding.

> [tab] Why it’s useful
>
> 💡 **Use cases:**
>
> * Quickly iterate on existing resources.
> * Reduce redundant manual setup.
> * Maintain consistency within projects.
> * Easily clone complex configurations for testing and modifications.

> [card] [Duplicate resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Track where your resources are used

Monitoring your resources has never been simpler and more efficient. Stay on top of where and how they’re being used.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

> [card] [Process Usage](../../4.7.x/docs/projects/resources#process-usage)
>
> Track where a process is referenced, with a clear **Usage Overview modal** that dynamically updates when references change.

> [card] [Enumeration Usage](../../4.7.x/docs/projects/resources#enumeration-usage)
>
> See where enumerations are used across **UI, Data Models, Systems, and Workflows** before making changes.

> [card] [Media Library Usage](../../4.7.x/docs/projects/resources#media-library-usage)
>
> Identify **which UI elements reference media assets** so you don’t accidentally break designs.

📌 **Before deleting a resource, a confirmation modal lists all affected references. No more surprises!**

***

### Configuration parameters overrides

🔹 **Libraries can now define configuration parameters** to help test processes or workflows that use those parameters.

🔹 However, **libraries do not support overrides**.

* **Overrides for library config parameters must be done within a project** where the library is added as a dependency.
* **Overrides cannot be added in libraries directly.**

<video />

💡 **What this means:**

* Libraries provide **default values** for configuration parameters.
* Projects using those libraries **can override these values** as needed.
* This ensures **clear separation between library defaults and project-specific configurations** while maintaining flexibility.

> [!TIP]
>
> ✨ **Overrides take precedence** over library values—so you stay in control.

***

### Merge conflict enhancements

Merge conflicts are never fun, but at least now they’re **easier to handle**.

> [card] Better Conflict Detection
>
> 🚨 Prevents merging if identical resource identifiers exist in both branches (e.g., same name, key, or code).

> [card] Resizable Merge Conflict Tree
>
> 🖥️ Resize the merge conflict tree for better visibility and navigation.

> [card] New Conflict Type
>
> 📢 A new conflict detection system for parent changes/deletions in both branches.

***

## SDK changes

### Expose Enumerations API in Angular SDK

Developers can now dynamically retrieve enumerations via the Angular SDK, making it easier to use enums in custom components like dropdowns.

> [!TIP]
>
> How it Works?
>
> A new method in the Angular SDK allows direct access to enumerations, reducing manual imports and improving flexibility.

**Usage**

The `getEnumeration()` function returns key-value pairs that can be used in components that need enumeration data:

```typescript theme={"dark"}
getEnumeration(enumName: string): { value: string; label: string }[]
```

* `enumName` (string) – The name of the enumeration to retrieve (e.g., 'UserRoles', 'cities')
* Returns: An array of objects containing value-label pairs representing the requested enumeration

> [accordion] Example usage
>
> The enumeration service works seamlessly with Angular's resource API for reactive state management:
>
> ```typescript theme={"dark"}
> import { Component, effect, model, resource } from '@angular/core';
> import { getEnumeration } from '@flowx/angular-sdk';
>
> @Component({
>   selector: 'app-dynamic-enum-select',
>   template: `
>     <select>
>       @for (option of options.value(); track option.value) {
>         <option [value]="option.value">{{ option.label }}</option>
>       }
>     </select>
>
>     <button (click)="enumName.set('cities')">Load Cities</button>
>     <button (click)="enumName.set('countries')">Load Countries</button>
>   `
> })
> export class DynamicEnumSelectComponent {
>   // Create a signal to track the currently selected enum
>   enumName = model<string>('UserRoles');
>
>   // Use resource API to reactively load enumerations when enumName changes
>   options = resource({
>     request: this.enumName,
>     loader: ({ request: enumName }) => getEnumeration(enumName),
>   });
>
>   constructor() {
>     effect(() => {
>       if (this.options.isLoading()) {
>         console.log(`Loading enumeration: ${this.enumName()}`);
>       } else {
>         console.log(`Loaded enumeration: ${this.enumName()}`, this.options.value());
>       }
>     });
>   }
> }
> ```

***

## **Bug fixes** 🐞

✔️ Improved **merge conflict detection and resolution**\
✔️ Fixed **UI rendering issues**

***

## Changes

### Dynamic Kafka topics

FlowX 4.7.0 introduces **Dynamic Kafka Topics**, enabling more flexible and configurable messaging across processes.

🔹 **What’s new?**

* Use **Configuration Parameters** to dynamically assign Kafka topics in **Kafka Send** and **Kafka Receive** actions.
* Concatenate predefined parameters with process variables for **on-the-fly topic selection**.
* Reduce hardcoded values and **simplify environment-specific configurations**.

💡 **Why it matters:**

* Makes **Kafka integrations more scalable** across different deployments.
* Supports **multi-topic messaging** for different use cases without manual updates.
* Ensures better **reusability and maintainability** in process configurations.

📌 Check the [Kafka Send Action](../../4.7.x/docs/building-blocks/actions/kafka-send-action#dynamic-kafka-topics) section for setup details.

***

### Export/import compatibility

In version 4.7, the import-export functionality for application-version is no longer backward compatible.

* Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
* Similarly, zip files from earlier versions cannot be imported into 4.7.

> [!NOTE]
>
> Zip files for builds and specific resources remain unaffected.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.0](./deployment-guidelines-v4.7.0)\
📌 [Migration Guide (from v4.6.0)](./migrating-from-v4.1.x-to-v4.7.0)


# Deployment guidelines v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/deployment-guidelines-v4.7.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.1.

## Component versions

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.5.1** | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.7.6** | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.3.3** | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.4** | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.7** | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.3** | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.4** | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.6** | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.6** | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.6** | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.5** | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.9** | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.2** | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.7** | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.13** | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.27** | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.2** | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.17** | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.35** | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.4** | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.1 | Keycloak | 22.x, 26.x |
| 4.7.1 | Kafka | 3.2.x |
| 4.7.1 | PostgreSQL | 16.2.x |
| 4.7.1 | Oracle Database | 21c, 23ai |
| 4.7.1 | MongoDB | 7.0.x |
| 4.7.1 | Redis | 7.2.x |
| 4.7.1 | Elasticsearch | 7.17.x |
| 4.7.1 | Angular (Web SDK) | 19.x |
| 4.7.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/migrating-from-v4.1.x-to-v4.7.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025

FlowX.AI 4.7.1 brings enhanced resource navigation, better error detection, and workflow improvements to make your development journey even smoother! 🚀

## What's new? 🆕

✅ Enhanced resource usage tracking with direct navigation\
✅ Upgraded JavaScript support to ECMAScript 15 (2024) in Business Rules\
✅ Added Python 3 support with 3x performance improvement\
✅ Major performance enhancements for both design time and runtime\
✅ Security enhancements for runtime endpoints

## Projects

### Enhanced resource usage navigation

We've significantly improved how you navigate between resources and their references with direct navigation capabilities. Now you can easily jump from the usage tracking panel to the exact location where a resource is referenced.

<video />

> [tab] How it works
>
> 1️⃣ **Access resource usage** – View where a resource is being used through the usage panel.\
> 2️⃣ **One-click navigation** – Use the new redirect button to jump directly to the referenced location.\
> 3️⃣ **Missing resource detection** – Easily identify and fix missing resource references with clear indicators.

> [tab] Why it's better
>
> * **Faster troubleshooting** – Directly navigate to problem areas without manual searching.
> * **Improved productivity** – Less time spent hunting down references means more time building.
> * **Better error prevention** – Quickly spot and fix missing resources before they cause issues.

***

## Enhanced scripting capabilities

### ECMAScript 15 (2024) support for Business Rules

FlowX.AI 4.7.1 brings the latest JavaScript features to your business rules with an upgrade to ECMAScript 15 (2024).

> [tab] What's included
>
> * Access to the latest JavaScript language features
> * Modern syntax for cleaner, more maintainable rules
> * Enhanced tooling and IDE support

> [tab] Benefits
>
> * Write more concise and expressive business rules
> * Leverage modern JavaScript patterns and best practices
> * Improved developer experience with better IDE integration

> [!NOTE]
>
> **Important Configuration Note:** Nashorn engine remains the default runtime. To enable GraalJS support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Nashorn will be used.

### Python 3 support for Business Rules

We've upgraded our Python scripting capabilities to Python 3, delivering significant performance improvements while maintaining compatibility.

> [card] 3x Faster Execution
>
> Python scripts now run at least 3 times faster than with Python 2.7.

> [card] Modern Python Features
>
> Take advantage of Python 3's improved syntax, libraries, and security features.

> [!NOTE]
>
> **Important Configuration Note:** Python 2.7 remains the default runtime. To enable Python 3 support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Python 2.7 will be used.

More details about the scripting capabilities can be found in the [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts) section.

***

## Performance improvements 🚀

We've made significant performance enhancements throughout the platform to make your development and runtime experience smoother and faster.

### Design time improvements

For large processes, you'll notice dramatic improvements:

| Operation | Improvement |
| - | - |
| Cloning a process | **5x faster** |
| Opening a process | **70x faster** |

### Runtime enhancements

Platform average response time has been **reduced by 20%** in our comprehensive benchmark\*.

> [!NOTE]
>
> \*The benchmark simulates a typical business process with a combination of user and service tasks. It includes rules that automate decision-making, as well as events for time-sensitive actions and communication. The process also covers various system functions, ensuring the platform can efficiently manage complex workflows with both individual and parallel tasks.

***

## Security enhancements 🔒

We've significantly improved platform security by implementing proper endpoint access controls and separation between internal and public-facing APIs.

> [card] Enhanced API Security
>
> Runtime execution proxy vulnerability addressed with comprehensive endpoint updates.

> [card] Access Control Improvements
>
> Better separation between design-time and runtime endpoints with proper access controls.

### Endpoint security updates

We've implemented a comprehensive security update for runtime endpoints to prevent potential proxy vulnerabilities:

* Redesigned API structure to separate internal (`runtime-internal`) from external-facing (`runtime`) endpoints
* Migrated design-time operations to use `runtime-internal` endpoints for enhanced security
* Moved specific management operations to dedicated `build-mgmt` endpoints
* Updated all API clients to use the new secure endpoints

> [!NOTE]
>
> **Important:** Make sure to update to the corresponding  version of the [**`flowx-admin`**](./deployment-guidelines-v4.7.1#component-versions) to benefit from these security enhancements.

### Enhanced resource caching in Angular SDK

The Angular SDK now includes an improved caching mechanism for CMS resources, optimizing loading times and performance. The cache parameter on the `flx-process-renderer` component allows developers to control caching behavior in different environments.

> [card] [Read about caching in Angular SDK](../../4.7.x/sdks/angular-renderer#caching)
>
> Find details on controlling CMS resource caching during development and production.

## **Bug fixes** 🐞

* Fixed various minor issues to improve overall stability
* Resolved some UI inconsistencies
* Addresses performance optimizations
* Fixed general usability issues

***

## **Additional information**

📌 [Deployment Guidelines v4.7.1](./deployment-guidelines-v4.7.1)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.1)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.10
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/deployment-guidelines-v4.7.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.3** | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.8** | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.6** | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.5** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.4** | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.6** | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.4** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.3** | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.6** | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.2** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.32** | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.24** | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.10 | Keycloak | 22, 26+ |
| 4.7.10 | Kafka | 3.2 - 3.9 |
| 4.7.10 | PostgreSQL | 16 - 17 |
| 4.7.10 | OracleDB | 19c, 21c, 23ai |
| 4.7.10 | MongoDB | 7 - 8 |
| 4.7.10 | Redis | 7.2 - 8.0 |
| 4.7.10 | Elasticsearch | 7 - 8 |
| 4.7.10 | Angular (Web SDK) | 19.x |
| 4.7.10 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.10 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Updated Spring Boot to the latest release for enhanced security and performance\
✅ Updated Java libraries to fix vulnerabilities across all images\
✅ Selectors support for substitution tags across all platforms (Web, iOS, Android)\
✅ System substitution tags on all task management texts\
✅ CMS - Added system substitution tags with migration script support

### Security and Platform Updates

This release includes critical security updates to ensure your FlowX.AI platform remains secure and up-to-date:

* **Spring Boot Update**: Updated to the latest release on the 4.7.x LTS branch
* **Java Libraries Update**: Updated Java libraries to fix vulnerabilities across all LTS 4.7.x images

### Selectors Support for Substitution Tags

You can now use selectors with substitution tags when the source type is process data across all platforms (Web, iOS, and Android). This enhancement provides more flexibility in displaying dynamic content from your process data in selector components.

**Available on:**

* Angular Web Renderer
* React Web Renderer
* iOS Renderer

### System Substitution Tags for Task Management

Task management now includes comprehensive system substitution tags support:

* **Backend CMS**: Added system substitution tags with a migration script to help you transition existing content
* **Web Renderers**: System substitution tags are now available on all task management texts across Angular and React renderers
* This allows for more dynamic and flexible task management configurations

## Bug fixes

> [accordion] \[Designer] Error when copying/pasting nodes with misconfiguration
>
> Fixed an issue where attempting to copy and paste nodes with misconfigurations, or importing an app version/build with misconfigured nodes, would result in an error. The system now handles misconfigured nodes gracefully during these operations.
>
> **Issue**: Error when trying to copy and paste nodes with misconfiguration or import an app version/build with nodes with misconfigurations

> [accordion] \[React] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the React renderer.
>
> **Issue**: \[React] Card not expandable after finishing subprocess started from it

> [accordion] \[Angular] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the Angular renderer.
>
> **Issue**: \[Angular] Card not expandable after finishing subprocess started from it

> [accordion] \[React] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the React renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[React] Card shouldn't collapse when next nav area is modal

> [accordion] \[Angular] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the Angular renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[Angular] Card shouldn't collapse when next nav area is modal

> [accordion] \[Backend] Task Manager - System substitution tags not displayed in column names
>
> Fixed an issue where system substitution tags were not being displayed in the `columns.displayName` property of the Task Manager backend.
>
> **Issue**: \[BE] Task manager | System substitutionTags are not displayed in columns.displayName

> [accordion] \[Web Renderers] Task Manager - Substitution tags value override
>
> Resolved an issue where system substitution tags values were incorrectly overriding custom substitution tags when the value was not null in both React and Angular renderers.
>
> **Issue**: \[React]\[Angular] Task manager | System subTags values override de custom subTags when value is not null

> [accordion] \[Task Manager] Missing localization for Russian and Uzbek in table view
>
> Fixed localization support in Task Manager table view for Russian and Uzbek languages, ensuring proper display of translated content.
>
> **Issue**: \[Task manager localisation] Table view - Missing localisation support for Russian and Uzbek

> [accordion] \[Task Manager] View search field placeholder not localized
>
> Resolved an issue where the view search field placeholder in Task Manager was not being localized for any language. The placeholder now properly supports all configured languages.
>
> **Issue**: \[Task manager localisation] View search field placeholder not localised for any language


# Deployment guidelines v4.7.11
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/deployment-guidelines-v4.7.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.6** | 8.24.3 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.12** | 7.18.8 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.9** | 5.11.6 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.8** | 6.8.5 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.7** | 6.10.4 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.9** | 7.9.6 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.7** | 6.8.4 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.6** | 2.16.3 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.9** | 2.10.6 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.103.6** | 5.101.2 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.32 | 4.0.32 | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.27** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.25** | 1.8.24 | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.11 | Keycloak | 22, 26+ |
| 4.7.11 | Kafka | 3.2 - 3.9 |
| 4.7.11 | PostgreSQL | 16 - 17 |
| 4.7.11 | OracleDB | 19c, 21c, 23ai |
| 4.7.11 | MongoDB | 7 - 8 |
| 4.7.11 | Redis | 7.2 - 8.0 |
| 4.7.11 | Elasticsearch | 7 - 8 |
| 4.7.11 | Angular (Web SDK) | 19.x |
| 4.7.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.11 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025

Security and maintenance updates for the 4.7.x LTS release

## What's new?

This is a **security and maintenance release** for the FlowX.AI 4.7.x LTS branch, focused on keeping your platform secure and up-to-date with the latest security patches.

✅ **Security Updates** - Updated core libraries and dependencies to address known vulnerabilities\
✅ **Platform Stability** - Improved overall platform security and stability

***

## Migration notes

> [!WARNING]
>
> As this is a **patch release** on the 4.7.x LTS branch, it is designed to be a **drop-in replacement** with no breaking changes.

***

## Component versions

All FlowX.AI components have been updated to version **4.7.11** with the security patches applied. Refer to the deployment guidelines for the complete list of component versions.


# Deployment guidelines v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/deployment-guidelines-v4.7.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.2 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.2.

## Component versions

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.9.0** | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.5** | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.8** | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.10** | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.16** | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.12** | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.13** | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.14** | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.13** | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.14** | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.2.0** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.12** | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.16** | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.9** | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.35** | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.9** | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.24** | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.1** | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.9** | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.2 | Keycloak | 22.x, 26.x |
| 4.7.2 | Kafka | 3.2.x |
| 4.7.2 | PostgreSQL | 16.2.x |
| 4.7.2 | Oracle Database | 21c, 23ai |
| 4.7.2 | MongoDB | 7.0.x |
| 4.7.2 | Redis | 7.2.x |
| 4.7.2 | Elasticsearch | 7.17.x |
| 4.7.2 | Angular (Web SDK) | 19.x |
| 4.7.2 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## Additional configuration

Added new environment variable on Process Engine:

### Message routing configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

> [!NOTE]
>
> When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.


# Migrating from previous versions to v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/migrating-from-v4.1.x-to-v4.7.2

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 and v4.7.1 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.2 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025

FlowX.AI 4.7.2 delivers improved merge conflict handling with retry capabilities, deprecates DMN business rules, and fixes issues with subprocess handling, media file imports, and OCR functionality to enhance your development workflow! 🚀

## **What's new? 🆕**

✅ Improved merge conflict handling with retry functionality\
✅ Enhanced error messages during failed merges\
✅ Streamlined workflow for resolving merge conflicts

## Merge conflicts

### Improved error messages when merge fails

We've enhanced the merge conflict resolution experience with more informative error messages and a new retry functionality:

* When a merge fails, users can now see a "Retry merge" button on the Merge failed modal
* Clicking this button allows users to attempt the merge again without losing previous work

The system now handles two distinct scenarios:

**1. When conflicts exist:**

* The system opens the Merge conflicts panel with the previous state of the merge before the failed attempt
* This preserves all your conflict resolution work so you can fix the specific issues that caused the failure

![Merge failed with conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20conflicts.png)

**2. When no conflicts exist:**

* The system automatically retries the merge operation
* This streamlines the workflow when the merge failure was due to temporary issues rather than actual conflicts

![Merge failed without conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20no%20conflicts.png)

## Process engine

### Deprecated DMN rules

In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.

**What's changing:**

* DMN is no longer available as a language option when configuring business rule actions

**What's next:**
For guidance on using alternative business rule languages, please refer to our [supported scripting languages](../../../../4.7.x/docs/building-blocks/supported-scripts) documentation.

## **Bug fixes** 🐞

* Resolved export/import issues with media library files, particularly for applications migrated from earlier versions
* Fixed an issue where parallel multi-instance Call Activity would incorrectly trigger a subprocess when using an empty array list as a variable
* Fixed a display issue where not all subprocesses were visible in the subprocess list on smaller screens
* Fixed a bug where message events couldn't be caught when placed directly after an uninterrupting timer event
* Resolved "Unsupported Media Type" errors when importing application versions with media file binaries
* Fixed an issue where color palette changes in Theme settings couldn't be saved at 100% browser resolution on smaller screens
* Fixed a issue where OCR plugin failed due to missing correlation headers

***

## **Additional information**

📌 [Deployment Guidelines v4.7.2](./deployment-guidelines-v4.7.2)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.2)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/deployment-guidelines-v4.7.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.3 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.3.

## Component versions

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.13.0** | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.13** | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.12** | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.11** | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.17** | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.13** | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.16** | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.15** | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.14** | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.15** | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.14** | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.6.0** | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.11** | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.14** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.15** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.37** | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.12** | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.26** | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.3** | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.11** | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.3 | Keycloak | 22.x, 26.x |
| 4.7.3 | Kafka | 3.2.x |
| 4.7.3 | PostgreSQL | 16.2.x |
| 4.7.3 | Oracle Database | 21c, 23ai |
| 4.7.3 | MongoDB | 7.0.x |
| 4.7.3 | Redis | 7.2.x |
| 4.7.3 | Elasticsearch | 7.17.x |
| 4.7.3 | Angular (Web SDK) | 19.x |
| 4.7.3 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/migrating-from-v4.1.x-to-v4.7.3

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.3 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025

FlowX.AI 4.7.3 enhances workflow conflict resolution, adds configurable enumeration ordering, and fixes data streams, UI templates, and application export/import issues to improve your development experience! 🚀

## **What's new? 🆕**

✅ Enhanced workflow conflict resolution with improved visibility\
✅ Added ability to configure order attributes on enumerations\
✅ Upgraded conflict management interface for better user experience

## Merge conflicts - workflow improvements

### Enhanced workflow conflict resolution

We've significantly improved how [**workflow**](../../4.7.x/docs/platform-deep-dive/integrations/integration-designer#workflows) conflicts are handled in this release:

* Upgraded to a new version (v2) of the workflow conflict resolution interface
* Now only showing workflow entities that have actual conflicts, making it easier to identify and address issues
* Streamlined the conflict resolution process for a more efficient workflow

![Workflow conflict resolution](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/workflow_conflicts.png)

> [!NOTE]
>
> **Important note about sequence conflicts:**
>
> When resolving conflicts related to sequences, if you select one of the conflicting sequences, nodes that are no longer connected may remain "orphaned" on the canvas in the merged version. This design decision was made to prevent accidental node deletion. If these orphaned nodes are no longer needed, they can be manually removed in subsequent versions.

## Configurable enumeration ordering

You can now configure the **Order** attribute on enumerations, giving you greater control over how enumeration values are displayed in dropdown lists:

* Set specific order values for each enumeration entry
* Control the presentation sequence in UI components
* Improve user experience by arranging options in logical or prioritized order

![Enum order](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/enum_order.png)

> [!NOTE]
>
> **Limitation:** When changing the order value for an enumeration entry, the system does not automatically update the order values of other entries. You'll need to manually adjust the order values of other entries in the interface.

## **Bug fixes** 🐞

* Fixed an issue where workflow nodes could have two output sequences
* Resolved a problem with enumerations displaying in the wrong order in dropdown lists
* Fixed an authentication issue where users would receive 401 unauthorized errors when executing actions after token refresh
* Fixed a UI behavior issue where slider actions configured with "onChange" were incorrectly triggered when entering a screen instead of only when modified
* Fixed an issue with identical advancing IDs occurring in multi-pod deployments due to missing hostname command in GraalVM docker images
* Resolved an issue preventing media library migration from default application
* Fixed the "Go to reference" functionality from data model attributes that was not correctly redirecting to referenced elements
* Fixed an error during application export/import where "There already exists a tagged build for this project version" was preventing successful imports
* Restored support for multiple topics in Data Stream Topics feature, which was previously only listening to the first topic in the list
* Fixed a 500 error that occurred when attempting to create child actions on certain nodes
* Fixed a critical issue where UI templates would disappear when creating a new version of an application after performing undo operations on pasted templates
* Fixed a bug where updates to the subprocess in a Start subprocess action weren't being saved properly
* Fixed an issue with the "Send email" button remaining disabled in the Test notification template feature after correcting validation errors
* Fixed an error that occurred when trying to export document templates containing null values in templateMap
* Fixed a display issue where Tokens, Workflows, and Subprocesses information wasn't showing in process instances after migration from 4.7.1 to 4.7.2
* Fixed a UI issue where business rule code wasn't displayed when testing business rules in committed versions

***

## **Additional information**

📌 [Deployment Guidelines v4.7.3](./deployment-guidelines-v4.7.3)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.3)


# Deployment guidelines v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/deployment-guidelines-v4.7.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.4 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.4.

## Component versions

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.15.2** | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.9.2** | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.16** | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.13** | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.19** | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.15** | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.18** | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.17** | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.16** | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.17** | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.16** | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.7.2** | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.3.2** | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.19** | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.23** | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.39** | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.17** | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.28** | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.5** | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.13** | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.4 | Keycloak | 22.x, 26.x |
| 4.7.4 | Kafka | 3.2.x |
| 4.7.4 | PostgreSQL | 16.2.x |
| 4.7.4 | Oracle Database | 21c, 23ai |
| 4.7.4 | MongoDB | 7.0.x |
| 4.7.4 | Redis | 7.2.x |
| 4.7.4 | Elasticsearch | 7.17.x |
| 4.7.4 | Angular (Web SDK) | 19.x |
| 4.7.4 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## **Additional information**

* Added new environment variable `OPTIMISTIC_LOCKING_RETRIES` to control the number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

Elasticsearch indexing configuration:

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)


# Migrating from previous versions to v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/migrating-from-v4.1.x-to-v4.7.4

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.4 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025

FlowX.AI 4.7.4 enhances system stability with Spring Boot updates and resolves critical issues across build exports, reporting, SDK functionality, and cross-platform consistency to deliver a more reliable development experience! 🚀

## **What's new? 🆕**

✅ Platform enhancements\
✅ Added retry mechanism for ES indexing to handle key‑identifier errors\
✅ Fixed critical build export timeout issues\
✅ Improved reporting data representation\
✅ Enhanced cross-platform consistency

### Platform Enhancements ⚙️

* Enhanced system stability
* Latest security patches
* Improved performance

### Elasticsearch indexing - configurable retry mechanism

* `OPTIMISTIC_LOCKING_RETRIES`: Number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)

### Data-sync run status monitoring

* Added the ability to view the run status of data-sync jobs directly in the platform interface
* Monitor the execution status of all data-sync jobs from the Jobs dashboard
* Quickly identify failed jobs for faster troubleshooting

![Data-sync run status monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-20%20at%2010.55.19.png)

## **Bug fixes** 🐞

* **Build export timeouts**: Resolved intermittent timeout failures on projects with dependency libraries; exports now consistently complete or retry correctly.
* **Build creation on merge without conflicts**: Fixed an issue where merging one branch into another without conflicts—and switching the active policy—did not trigger a new build, forcing users to manually create a version; now, merges automatically update build resources and create the new version so merged changes appear at runtime.
* **Project version import stashing conflict**: Resolved an error where importing a branched project version across environments would inadvertently stash other versions—restoring successful import, fixing the GET history API response, and ensuring the Project versions history modal renders correctly.
* **CosmosDB workflows**: Fixed an issue preventing the workflow instances list from loading in the Integration Designer when using CosmosDB.
* **Reporting arrays**: Corrected array formatting in the `reporting_data` table (process-engine schema).
* **CMS permissions**: Restored backward compatibility for FlowX SDK v4.7+ by removing the unintended `media_library_read` requirement for processes containing images (behavior now matches v4.1).
* **onChange action behavior**: Standardized onChange/onBlur across web, Android, and iOS so users cannot continue typing after token advancement unless explicitly allowed.
* **React SDK ternary expressions**: Fixed an “Invalid Expression” error in SDK v5.86.1—ternary expressions in computed values (e.g. `return ${var1} ? "Onboarded" : (${var2} ? "Non-eligible" : "Ready for Onboarding");`) now parse correctly as they did in v5.62.1.
* **Elasticsearch indexing**: Fixed an issue where the engine was not retrying to index process instances when it encountered concurrent-update errors on key identifiers.
* **iOS SSE token refresh**: Fixed an issue in iOS SDK where Server-Sent Events connections would occasionally use expired JWT tokens instead of refreshed ones, causing 401 errors and process hangs in production environments.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.4](./deployment-guidelines-v4.7.4)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.4)


# Deployment guidelines v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/deployment-guidelines-v4.7.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.5 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.5.

## Component versions

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.17.0** | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.12.2** | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.5.1** | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.1.1** | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.1.1** | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.2.1** | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.4.1** | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.3.1** | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.1.1** | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.9.0** | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.4.1** | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.21** | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.24** | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.18** | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.5 | Keycloak | 22, 26+ |
| 4.7.5 | Kafka | 3.2 - 3.9 |
| 4.7.5 | PostgreSQL | 16 - 17 |
| 4.7.5 | Oracle Database | 21c, 23ai |
| 4.7.5 | MongoDB | 7 - 8 |
| 4.7.5 | Redis | 7.2 - 8.0 |
| 4.7.5 | Elasticsearch | 7 - 8 |
| 4.7.5 | Angular (Web SDK) | 19.x |
| 4.7.5 | React (Web SDK) | 18.x |

> [!NOTE]
>
> **New in 4.7.5: Support for more 3rd Party Dependencies**
>
> FlowX.AI 4.7.5 introduces support for more versions of third-party dependencies:
>
> * All versions are officially supported throughout the entire LTS lifetime
> * Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major release
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/migrating-from-v4.1.x-to-v4.7.5

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.5 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.5 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025

FlowX.AI 4.7.5 enhances system stability with introducing support for more 3rd party dependency and introduces High Availability improvements with Redis Sentinel mode support to deliver a more reliable and scalable development experience! 🚀

## **What's new? 🆕**

✅ **Platform enhancements**\
✅ **Analytics enhancements**

### Platform enhancements ⚙️

**Extended Third-Party Dependency Support** - Introducing support for more versions of third-party dependencies:

* All versions are officially supported throughout the entire LTS lifetime
* Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major releases for critical infrastructure components, ensuring all supported versions are officially maintained throughout the entire LTS lifetime. This enables organizations to perform gradual dependency upgrades during the LTS period, preparing infrastructure to meet the minimum requirements for the next FlowX.AI major release while maintaining full platform support and stability.

### Analytics enhancements ⚙️

* Improved analytics events with enriched metadata for action events across all platforms (Web, iOS, Android). Action events now include screen context, component type identification, and component labels, providing deeper insights into user interactions and enabling more granular analytics tracking for better user experience optimization.

More details:

> [card] [Angular Renderer](../../../../4.7.x/sdks/angular-renderer#analytics)

> [card] [React Renderer](../../../../4.7.x/sdks/react-renderer#analytics)

> [card] [iOS Renderer](../../../../4.7.x/sdks/ios-renderer#collecting-analytics-events)

> [card] [Android Renderer](../../../../4.7.x/sdks/android-renderer#collecting-analytics-events)

### Runtime Manager deployment changes

> [!NOTE]
>
> **Prior to 4.7.5:** Runtime Manager was deployed using `application-manager` chart/image with manual `SPRING_APPLICATION_NAME`: "runtime-manager" configuration.
> Starting with 4.7.5: Runtime Manager has its own dedicated chart and image with proper defaults.

> [!TIP]
>
> Migration Required

* Switch to new chart: Use runtime-manager chart instead of application-manager
* Verify image: Ensure image name is runtime-manager (default in new chart)
* Remove override: `SPRING_APPLICATION_NAME`: "runtime-manager" can be removed (optional)

> [!WARNING]
>
> You may need to delete the existing runtime-manager deployment before upgrading due to Kubernetes label changes that cause `kubectl apply` to fail.

## **Bug fixes** 🐞

* **Fixed Task Manager loading issue with data type changes** - Resolved critical issue where Task Manager would fail to load and throw `NullPointerException`   when process variables were changed from date to string data types, even after updating the data model and clearing cache
* **Fixed All Tasks view missing on build import** - Resolved issue where importing builds from one environment to another would fail to create the All Tasks view, when accessing the Task Manager area
* **Fixed unassign operation causing runtime errors** - Resolved 500 Internal Server Error when accessing process data after performing unassign operations via Kafka messages, where null ownerDetails would cause `NullPointerException` during JSON serialization
* **Fixed CMS-Core export failures with AWS S3 buckets** - Resolved issue where CMS-Core would add double slashes in S3 object paths when creating exports, causing 404 NoSuchKey errors with AWS S3 (while working correctly with MinIO). Fixed path construction to ensure compatibility with both AWS S3 and MinIO storage backends
* **Fixed active policy version resolution** - Resolved issue where importing application versions to environments with existing WIP versions would incorrectly activate the stashed WIP version instead of the imported committed version, causing graph display failures and incorrect active policy settings

***

## **Additional information**

📌 [Deployment Guidelines v4.7.5](./deployment-guidelines-v4.7.5)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.5)


# Deployment guidelines v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/deployment-guidelines-v4.7.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.6 will permanently prevent you from importing process definitions and resources created in versions 4.7.5 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

> [!WARNING]
>
> **Audit data retention change**
>
> Starting with FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. In 4.7.5 and earlier, the service created this policy only once, on the first installation.
>
> The policy it writes has a single hot phase that rolls the audit data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. The default is `30` days; in 4.7.5 and earlier, the rollover period was a fixed 1 day.
>
> Any phase you added to this policy directly in Elasticsearch, such as a delete phase, is removed the next time the Audit service starts. Without a delete phase, old audit indices are never deleted and audit storage keeps growing.
>
> To keep the previous daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1` on the Audit service.

## Component versions

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.21.1** | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.15.2** | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.8.2** | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.4.0** | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.4.0** | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.5.0** | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.7.0** | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.6.0** | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.5.0** | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.13.0** | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.7.1** | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.29** | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.19** | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.6 | Keycloak | 22, 26+ |
| 4.7.6 | Kafka | 3.2 - 3.9 |
| 4.7.6 | PostgreSQL | 16 - 17 |
| 4.7.6 | OracleDB | 21c, 23ai |
| 4.7.6 | MongoDB | 7 - 8 |
| 4.7.6 | Redis | 7.2 - 8.0 |
| 4.7.6 | Elasticsearch | 7 - 8 |
| 4.7.6 | Angular (Web SDK) | 19.x |
| 4.7.6 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8

## Configuration Parameters

Starting with FlowX.AI 4.7.6, Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment.

> [card] [Integration Designer setup](/4.7.x/setup-guides/integration-designer-setup#configuration-parameters)

> [card] [Process Engine setup](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters)

> [card] [Application Manager setup](/4.7.x/setup-guides/application-manager)


# Migrating from previous versions to v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/migrating-from-v4.1.x-to-v4.7.6

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.6 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.6](../v4.7.6-july-2025/deployment-guidelines-v4.7.6)

> [card] [Deployment guidelines v4.7.5](../v4.7.5-july-2025/deployment-guidelines-v4.7.5)

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1/)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.6 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025

This release includes significant improvements to logging configuration and resolves some issues across the Designer, Process Engine, and Integration Designer components.

> [!WARNING]
>
> Upgrading to 4.7.6 changes how the Audit service manages its Elasticsearch lifecycle policy: the policy is rewritten on every startup and the default rollover period changes from 1 day to 30 days. See the [Deployment guidelines](./deployment-guidelines-v4.7.6) before upgrading.

## **What's new? 🆕**

> [card] Improved default logging configuration
>
> Changed logging verbosity to reduce clutter & log sizes, increasing visibility for more relevant log messages.

> [card] Improved the ability to use deployment specific variables as Configuration Parameters (at process runtime)
>
> Now Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment. Check the [**Deployment Guidelines**](./deployment-guidelines-v4.7.6#configuration-parameters) for more details.

> [card] Improved runtime performance
>
> Improved runtime performance by better distributing the execution of nodes across all components.

> [card] Improved the speed of listing process instances
>
> Improved the speed of listing process instances by 4-6x on environments with a lot of process executions.

> [card] Added the ability to change logging levels at runtime
>
> This feature allows you to dynamically adjust logging levels without requiring a service restart, providing more flexibility in managing log output.

> [card] Reduced config deployment complexity
>
> The previously used `CONFIG_PROFILE` environment variable is no longer required as the default configs have been aligned with the recommended profiles.

## **Bug fixes** 🐞

> [accordion] \[Designer] Task view display issue
>
> Fixed task view list row content display issue where table rows were overlapping and text was not vertically centered in the latest Chrome browser version (138). The task view now properly displays centered content without text cutoff.

> [accordion] \[Integration Designer] JSON parsing error
>
> Fixed JSON parsing error when sending JSON result to REST body. Resolved issue where JSON objects generated in script tasks were causing "Unexpected character" errors when used in REST endpoint body parameters with \$ syntax.

> [accordion] \[Branch Merge] Media file export errors
>
> Fixed media file export errors during branch merges. Resolved issue where merging multiple branches created from the same main version would fail with "400 Bad Request" errors for media files after the first successful merge, even when no merge conflicts were present.

> [accordion] \[Process Designer] Rollback issue
>
> Fixed rollback issue during version submission errors. Resolved problem where processes were incorrectly marked as deleted in the database when submit version operations failed with 500 errors, preventing proper rollback and causing subsequent 404 "Process not found" errors.

> [accordion] \[Process Designer] Missing resources during copy operation
>
> Fixed missing resources during copy to another project/library operation. Resolved issue where forms with validation in UserTask nodes were not being copied when copying processes between projects or libraries.

> [accordion] \[Process Designer] Branch with missing resources and 404 errors
>
> Fixed issue where specific branches derived from main version would experience resource corruption, including missing process definitions (404 errors), missing Integration Designer resources, and commit failures.

> [accordion] \[Process Designer] Parallel multi-instance visual bug
>
> Fixed parallel multi-instance designer visual bug and database errors. Resolved issue where call activity nodes with parallel multi-instance enabled created duplicate "inputKey" and "outputKey" entries, causing visual bugs (missing collection key fields) and database update errors during node modifications.

> [accordion] \[Process Engine] Kafka message distribution
>
> Fixed Kafka message distribution across partitions. Resolved issue where Kafka messages were distributed as batches across partitions, causing increased usage of a limited number of partitions, instead of following the round-robin distribution per message strategy.

***

## **Additional information**

> [card] [Deployment Guidelines v4.7.6](./deployment-guidelines-v4.7.6)
>
> Step-by-step deployment instructions and configuration details for this release.

> [card] [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.6)
>
> Complete guide for migrating from version 4.1.x to 4.7.6 with breaking changes and migration steps.


# Deployment guidelines v4.7.7
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/deployment-guidelines-v4.7.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.7 will permanently prevent you from importing process definitions and resources created in versions 4.7.6 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.22.3** | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.16.3** | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.97.1** | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.9.2** | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.6.2** | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.8.2** | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.7.2** | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.6.2** | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.14.2** | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.8.1** | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.40** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.21** | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.29** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.14** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.7 | Keycloak | 22, 26+ |
| 4.7.7 | Kafka | 3.2 - 3.9 |
| 4.7.7 | PostgreSQL | 16 - 17 |
| 4.7.7 | OracleDB | 19c, 21c, 23ai |
| 4.7.7 | MongoDB | 7 - 8 |
| 4.7.7 | Redis | 7.2 - 8.0 |
| 4.7.7 | Elasticsearch | 7 - 8 |
| 4.7.7 | Angular (Web SDK) | 19.x |
| 4.7.7 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.7 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Improved robustness on auto-scaling process-engine and on Kafka node failures\
✅ Improvements on how configuration parameters can now be retrieved from Kubernetes secrets and ConfigMaps\
✅ Vulnerability fixes

## Configuration parameters

Improved configuration parameters retrieval from Kubernetes secrets and ConfigMaps. More details here:

> [card] [FlowX Engine](../../4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#dynamic-configuration-parameters-retrieval)

> [card] [Integration Designer](../../4.7.x/setup-guides/integration-designer-setup#dynamic-configuration-parameters-retrieval)

## Bug fixes

> [accordion] \[Designer] JSON size limit on input data
>
> Fixed JSON payload size limit issue causing "403 payload too large" errors when starting processes. More details [**here**](../../4.7.x/docs/flowx-designer/managing-a-project-flow/starting-a-process#starting-a-process-via-user-interface).

> [accordion] Improved robustness on Kafka node failures
>
> If one Kafka node fails, platform health check fails. This is now fixed.

> [accordion] \[UI Designer] Theming on accordion card
>
> Fixed theming issue where Card component styling was not properly applied when switched to accordion mode.

> [accordion] \[Angular SDK] Loader does not stop on subprocess end
>
> Fixed loader persistence issue where loaders initiated by "show loader" actions in subprocess UserTasks would continue displaying after subprocess completion.

> [accordion] \[Process Designer] Merge error with duplicate embed node keys
>
> Fixed merge conflict error occurring when copying and pasting embed nodes in processes.

> [accordion] \[Process Engine] Process execution stalls on REST-triggered flows when engine replica fails
>
> Fixed process execution recovery issue where REST API-triggered service tasks would hang indefinitely if the handling engine replica failed mid-execution.

> [accordion] \[Process Designer] Merge fails with duplicate key error after creating child branch to jump over broken WIP
>
> Fixed merge conflict error occurring when creating child branches from working commits to bypass broken WIP versions.


# Deployment guidelines v4.7.8
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/deployment-guidelines-v4.7.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.8 will permanently prevent you from importing process definitions and resources created in versions 4.7.7 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.23.2** | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.17.3** | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.10.3** | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.7.2** | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.9.2** | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.8.2** | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.7.2** | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.15.3** | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.9.2** | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.22** | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.8 | Keycloak | 22, 26+ |
| 4.7.8 | Kafka | 3.2 - 3.9 |
| 4.7.8 | PostgreSQL | 16 - 17 |
| 4.7.8 | OracleDB | 19c, 21c, 23ai |
| 4.7.8 | MongoDB | 7 - 8 |
| 4.7.8 | Redis | 7.2 - 8.0 |
| 4.7.8 | Elasticsearch | 7 - 8 |
| 4.7.8 | Angular (Web SDK) | 19.x |
| 4.7.8 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.8 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes\
✅ Support for [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title

### Support for Substitution Tags in Table column title

Now you can use [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title.

## Bug fixes

> [accordion] \[UI Designer] Card expansion state not calculated correctly
>
> Resolved an issue where, in certain situations, the expanded state of cards was not calculated correctly. This prevented users from expanding cards as expected.

> [accordion] \[UI Designer] Document preview component texts not translated
>
> Fixed localization issue where document preview component texts remained in English regardless of the selected language setting.

> [accordion] \[Designer] Groups tab fails to load with Keycloak 26.3
>
> Fixed compatibility issue with Keycloak 26.3 where the Groups tab would remain in loading state indefinitely due to new "description" field in group representations.

> [accordion] \[CMS] Import fails for PDF files with null thumbnail path
>
> Fixed import failure when PDF media files were exported with null `thumbnailStoragePath` values, preventing successful deployment of build or app versions to fresh environments.

> [accordion] \[Runtime Manager] Improved error logging for proxy failures
>
> Enhanced error logging detail when Runtime Manager proxy requests fail, providing better root cause information for debugging infrastructure issues like DNS problems or service unavailability.

> [accordion] \[Integration Designer] Slow performance on first workflow execution after pod restart
>
> Fixed performance issue where workflow IF node processing time increased from 3-5 seconds to 15-20 seconds on the first execution after Integration Designer pod restart.

> [accordion] \[Process Engine] Active step was incorrectly computed when the token is reset
>
> Fixed issue where the active step was incorrectly computed when the token is reset.


# Deployment guidelines v4.7.9
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/deployment-guidelines-v4.7.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.1** | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.4** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.1** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.1** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.1** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.2** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.30** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.26** | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.23** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.9 | Keycloak | 22, 26+ |
| 4.7.9 | Kafka | 3.2 - 3.9 |
| 4.7.9 | PostgreSQL | 16 - 17 |
| 4.7.9 | OracleDB | 19c, 21c, 23ai |
| 4.7.9 | MongoDB | 7 - 8 |
| 4.7.9 | Redis | 7.2 - 8.0 |
| 4.7.9 | Elasticsearch | 7 - 8 |
| 4.7.9 | Angular (Web SDK) | 19.x |
| 4.7.9 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.9 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes and security improvements\
✅ Support for dynamic keys in [**Link component**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/typography#link) URL property across all platforms\
✅ Added property on View for enabling or disabling row selection in tasks table

### Support for dynamic keys in Link component URL property

You can now use dynamic keys in the Link component's URL property across all platforms (Web, iOS, and Android). This enhancement allows you to dynamically construct URLs using process data, enabling more flexible navigation patterns in your applications.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)

### Task Manager rowSelection property on view

A new "Enable row selection" property has been added to Task Manager views, enabling you to control row selection behavior in task tables.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enable_row_select.png)

## Bug fixes

> [accordion] \[Designer] Merge fails if one branch contains past merges
>
> Fixed an issue where merging branches that contain multiple past merge commits would fail with an error. The merge conflict resolution now properly handles complex merge histories when adding values to enumerations or making other configuration changes.

> [accordion] \[CMS] Enumerations retrieve content endpoint should return content from dependencies
>
> Resolved an issue where the CMS enumerations Kafka endpoint only returned content from the local project and not from library dependencies. The endpoint now correctly retrieves enumeration content from both the current project and all dependency libraries.

> [accordion] \[Task Manager] Table doesn't use the current language
>
> Fixed localization issue in Task Manager where table content wasn't respecting the current language setting. Task Manager tables now properly use the selected language for all displayed content.

> [accordion] \[UI Designer]\[Angular]\[React] Modal fixed height is not applied
>
> Resolved an issue where setting a modal's height to "fixed" would not apply correctly in Angular and React renderers. Fixed height configuration now works as expected for modal components.

> [accordion] \[UI Designer]\[Angular] Fixed container should use overflow-y auto instead of scroll
>
> Fixed styling issue where fixed-height containers incorrectly used `overflow-y: scroll` instead of `overflow-y: auto`. Containers now only show scrollbars when content exceeds the container height.


# Deployment guidelines v5.0.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/deployment-guidelines-v5.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.29.2** | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.25.2** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.21.2** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.14.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.17.2** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.14.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.12.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.15.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.11.0** | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.26.2** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.11.0** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.14.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.11.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | |

### Embedded components

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **SpiceDB** | **1.42.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **DGraph** | **25.0.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

### Renderers

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.3** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.0.12** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.0.0 | Keycloak | 26+ |
| 5.0.0 | Kafka | 3.8 - 3.9 |
| 5.0.0 | PostgreSQL | 16 - 17 |
| 5.0.0 | Oracle Database | 21c, 23ai |
| 5.0.0 | MongoDB | 7 - 8 |
| 5.0.0 | Redis | 7.4 - 8.0 |
| 5.0.0 | Elasticsearch | 8 - 9 |
| 5.0.0 | Angular (Web SDK) | 19.x |
| 5.0.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/configuration-and-migration

This section contains the steps in the order we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](../../../../5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The Authorization System will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

> [!NOTE]
>
> The admin user imported here is the same service account referenced in the migration prerequisites. If you followed the prerequisites page and set up the admin Keycloak user beforehand, the Authorization System will pick it up automatically during this step — no additional action is needed.

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from Application Manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.0.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | 🆕 Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Kafka Configuration

> [!NOTE]
>
> Consumer group naming standardized to kebab-case across all FlowX.AI services with new messaging features for enhanced functionality.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group naming changes

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
> | | |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Application Manager specific features

#### New environment variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | 🆕 Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | 🆕 Maximum HTTP request header size |

#### New Kafka features

> [card] Resource Update Propagation
>
> Consumer Group: `app-resource-update-propagation-group`\
> Threads: 3\
> Topic: `ai.flowx.{env}.application-version.resource.update.propagation.v1`

> [card] Build Runtime Data
>
> Consumer Group: `build-runtime-data-group`\
> Threads: 2\
> Topic: `ai.flowx.{env}.build.runtime-data.v1`

> [card] Business Rule Sync
>
> Topic: `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> Purpose: Business rule synchronization

> [card] Process Sync (Restructured)
>
> Topic: `ai.flowx.{env}.application-version.sync.process.in.v1`\
> Purpose: Enhanced process synchronization

> [card] Reusable Templates sync
>
> Topic: `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> Purpose: Reusable template synchronization

#### Kafka environment variables (optional overrides)

```bash New Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_RESOURCEUPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Business Rule Sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1

# Process Sync (restructured)
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1


# Reusable Templates sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1
```

```bash Consumer Groups theme={"dark"}
# New Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
```

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides.

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | 🆕 Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | 🆕 Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | 🆕 S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | 🆕 S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | 🆕 S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | 🆕 S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | 🆕 S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | 🆕 S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | 🆕 Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | 🆕 Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | 🆕 Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | 🆕 Redis host |
| `SPRING_REDIS_PORT` | `6379` | 🆕 Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | 🆕 Redis password |
| `SPRING_REDIS_TTL` | `5000000` | 🆕 Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | 🆕 Redis host |

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/install-services

Step-by-step installation guide for new FlowX.AI 5.0 services

FlowX.AI 5.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](/5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](/5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.6 (or newer) to 5.0.0. If you’re on an earlier version, upgrade to the latest LTS version first.

## Success factors

> [!WARNING]
>
> The following steps are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB** must be installed before any FlowX.AI services. **DGraph** is only required if you are using FlowX AI agents — if not, you can skip DGraph installation, but SpiceDB is still mandatory.
>
> > [!NOTE]
> >
> > Only DGraph can be skipped (and only if you are not using FlowX AI agents). SpiceDB is mandatory for all deployments.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices migration** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](/5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites

This section contains the steps in the order we recommend for migrating data from FlowX v4.7.x to v5.0.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.6 | FlowX.AI 5.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.0#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip installing DGraph. SpiceDB is still mandatory.

> [card] [SpiceDB setup guide](../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.0.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

Before upgrading to FlowX.AI 5.0, you must run two operations on all existing Elasticsearch indices:

1. **Update index mappings** to include the `workspaceId` field (schema change)
2. **Migrate existing documents** to assign them to the default workspace (data migration)

These operations are required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable; if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

> [!WARNING]
>
> If Elasticsearch migration is not completed correctly, some process instances may not appear in search results, data-search features might return incomplete results, and workspace-scoped queries will fail for unmigrated data. Existing resources will also not be visible or accessible within the new workspace structure.

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.0.0.

***

## Authorization System Prerequisites

Before deploying the `authorization-system` service, you must configure the organization admin user. This is a critical prerequisite for ensuring that the authentication and user management features function correctly post-upgrade.

### Steps to Configure the Organization Admin User

Follow these guides to correctly set up the organization admin user:

> [card] [Bootstrap Organization Admin](../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Organization Admin Roles & Workspace Access](../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

> [!TIP]
>
> Configuration of the organization admin user must be completed **before** deploying the authorization-system service (see the [Install Services](./install-services) section for service deployment steps).

### Pre-migration preparation

Required configuration for the authorization-system service:

* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE`= `true` (mandatory for migrations)
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME`= `<admin-username>` (recommended method, default: `admin@flowx.ai`)

The system will search for this username in Keycloak and automatically copy the user's subject ID to the authorization-system database.

**Fallback method:** If the username method fails or you prefer to specify the subject ID directly:

* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID`= `<subject-id-of-admin-user>`

> [!TIP]
>
> To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.

![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users"
    ]
  }
}
```


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.06.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.0") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.0 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.0 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.0 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.0 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.0 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# FlowX.AI 5.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025

Latest features, improvements, and bug fixes in our newest release

> [!WARNING]
>
> This release includes the following features in Tech Preview. We encourage you to try them out and share your feedback to help us improve them. Please note that Tech Preview features may change before final release.

> [tab] What's New
>
> **What's new? 🆕**
>
> 🆕 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture)\
> 🆕 [**Project Data Model (PDM)**](#project-data-model-pdm)\
> 🆕 [**FlowX.AI Database**](#flowx-ai-database)\
> 🆕 [**Multi Select UI Component**](#multi-select-ui-component)\
> 🆕 [**Library-to-Library Dependencies**](#library-to-library-dependencies)\
> 🆕 [**Data Mappers**](#data-mappers)\
> 🆕 [**Reusable Resources**](#reusable-resources)\
> 🆕 [**Files in Integration Designer**](#files-in-integration-designer)\
> 🆕 [**Rendering improvements**](#rendering-improvements)
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Major Infrastructure Changes**: Workspaces introduces SpiceDB integration and new database schemas for multi-tenant architecture.
> > >
> > > **Key Changes:**
> > >
> > > * **SpiceDB Integration**: New permission management system requiring deployment
> > >
> > > * **Database Migration**: Schema updates for workspace support
> > >
> > > * **User Storage**: Only information about FlowX.AI Designer users is stored in FlowX.AI. The stored user data is limited to: unique identifier, username, first name, last name, and email address.
> > >
> > > * **Default Workspace**: All the projects and libraries are migrated to default workspace
> > >
> > > > [!TIP]
> > > >
> > > > **Backward Compatibility**: All existing functionality preserved in default workspace
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Login Flow**: After authentication, select your workspace before accessing FlowX.AI Designer. Once inside a workspace, everything works as before.
> > >
> > > **What's New:**
> > >
> > > * **Workspace Selection**: Choose workspace after login
> > > * **Resource Isolation**: Projects, libraries, themes are workspace-specific
> > > * **Enhanced Permissions**: Fine-grained access control with user groups and ACLs
> > > * **Workspace Management**: Create and manage workspaces (admin users)
> > >
> > > **What Stays the Same:**
> > >
> > > * Process design and configuration
> > > * UI Designer capabilities
> > > * Integration patterns
> > > * All existing FlowX.AI Designer features
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Transformation**: Workspaces enables enterprise multi-tenant architecture with independent business unit governance while sharing platform capabilities.
> > >
> > > **Business Impact:**
> > >
> > > * **Faster time-to-market** for new business verticals
> > > * **Enhanced compliance** with workspace-specific controls
> > > * **Improved governance** with fine-grained access management
> > >
> > > **Enterprise Benefits:**
> > >
> > > * Business unit autonomy with shared platform
> > > * Regulatory compliance through data isolation
> > > * Centralized upgrades and maintenance
> > > * Cross-business unit resource sharing when appropriate
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Infrastructure Impact**: PDM has minimal infrastructure impact - it's a design-time feature that improves development efficiency without affecting runtime resources.
> > >
> > > > [!TIP]
> > > >
> > > > **No deployment changes required** - PDM is part of the design platform, not runtime
> > >
> > > > [!TIP]
> > > >
> > > > **Backward compatible** - Existing processes continue to work unchanged
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer**: Define data types once at project level, use everywhere. No more recreating Customer or Order objects in every process.
> > >
> > > **How to Use PDM:**
> > >
> > > 1. Navigate to Project → Config → Data Model
> > > 2. Define your business entities (Customer, Product, etc.)
> > > 3. Set governance rules (sensitive data, reporting)
> > > 4. Use these types in any process within the project
> > >
> > > **Best Practices:**
> > >
> > > * Start with core business entities
> > > * Use clear, consistent naming
> > > * Mark sensitive fields appropriately
> > > * Leverage library data types when available
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: PDM transforms how your organization manages business data definitions. Define business entities once and ensure consistency across all processes and teams.
> > >
> > > **Business Benefits:**
> > >
> > > * **Enhanced compliance** through centralized governance and data sensitivity controls
> > > * **Reduced errors** from consistent data definitions
> > >
> > > **ROI Indicators:**
> > >
> > > * Development Efficiency: Measure reduction in process creation time
> > > * Error Reduction: Track fewer data-related production issues
> > > * Maintenance Cost: Monitor time spent on data structure updates
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Infrastructure Planning Required**: FlowX.AI Database creates additional MongoDB collections and requires infrastructure planning for storage, monitoring, and backup procedures.
> > >
> > > > [!TIP]
> > > >
> > > > New microservice: NoSQL DB Runner. Check the [setup guide](/5.1/setup-guides/nosql-db-runner) for more details.
> > >
> > > **Key Considerations:**
> > >
> > > * **Storage Planning**: Monitor usage as processes adopt internal database (plan for 20-30% increase)
> > > * **Performance Monitoring**: Set up alerts for FlowX.AI Database query performance
> > > * **Backup Strategy**: Include FlowX.AI Database collections in backup procedures
> > > * **Connection Pooling**: Additional connection pools for database operations
> > > * **Memory**: Additional 256MB-512MB per FlowX.AI instance for database operations
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Integration Option**: FlowX.AI Database appears as a new Data Source type in Integration Designer, right alongside RESTful System.
> > >
> > > **When to Use FlowX.AI Database:**
> > >
> > > * Customer data lookup across processes
> > > * Shared configuration and reference data
> > > * Process-to-process communication
> > > * Caching frequently accessed data
> > > * Temporary operational data storage
> > >
> > > **How to Implement:**
> > >
> > > 1. Add Data Source node to your process
> > >
> > > 2. Select "FlowX.AI Database" as type
> > >
> > > 3. Configure collection and operations
> > >
> > > 4. Use familiar MongoDB syntax (find, insert, update)
> > >
> > > > [!WARNING]
> > > >
> > > > **When NOT to Use**: Don't replace your core business systems. FlowX.AI Database is perfect for operational data, caching, and inter-process communication - but your CRM, ERP, and other systems of record should remain your primary data sources.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: FlowX.AI Database enables new operational patterns that were previously complex or impossible. It's not about replacing your core systems, but about enabling new ways to orchestrate business processes.
> > >
> > > **New Business Capabilities:**
> > >
> > > * **Cross-process workflows**: Loan application → Credit check → Approval across different process instances
> > > * **Real-time dashboards**: Operational data for business monitoring without system integration
> > > * **Agile experimentation**: Test new business rules without impacting core systems
> > > * **Process orchestration**: Complex business flows spanning multiple departments
> > >
> > > **ROI Considerations:**
> > >
> > > * **Time to Market**: Faster implementation of new business processes
> > > * **Agility**: Rapid prototyping and testing of business ideas
> > >
> > > **Use FlowX.AI Database when:**
> > >
> > > * Data is operational and process-specific (not master data)
> > > * You need rapid implementation without IT system changes
> > > * Process instances need to communicate with each other
> > > * You're prototyping new business capabilities
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **No Infrastructure Impact**: Multi Select is a pure UI component with no backend requirements. It works with existing form handling and data storage mechanisms.
> > >
> > > > [!TIP]
> > > >
> > > > **Zero deployment overhead** - Component is part of the UI framework upgrade
> > >
> > > > [!TIP]
> > > >
> > > > **Existing data handling** - Uses standard array storage, no schema changes needed
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Easy Integration**: Multi Select works just like other form elements in UI Designer. Drag, drop, configure - no new learning curve required.
> > >
> > > **Common Use Cases:**
> > >
> > > 1. **Skills Selection**: Job applications, team member profiles, contractor skills
> > > 2. **Product Features**: Insurance coverage options, software licensing features
> > > 3. **Categories & Tags**: Document classification, customer segmentation
> > >
> > > **Key Configuration:**
> > >
> > > * **Max selections**: Control input limits
> > > * **Display format**: Chips, lists, custom
> > > * **Search**: Filter large option sets
> > > * **Clear all**: Easy reset functionality
> > > * **Validation**: Min/max rules
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **User Experience Impact**: Multi Select eliminates user frustration in scenarios where single selection doesn't match real-world needs. This improves data quality and user satisfaction.
> > >
> > > **Before vs After:**
> > >
> > > * ❌ **Before**: "I can only select one skill, but I have multiple certifications"
> > > * ✅ **After**: "Perfect! I can select all my relevant skills at once"
> > >
> > > **Business Process Examples:**
> > >
> > > * **Employee Onboarding**: Select multiple skills, certifications, department access
> > >
> > > * **Product Configuration**: Select multiple features, add-ons, support packages
> > >
> > > * **Customer Preferences**: Select multiple communication channels, product interests
> > >
> > > > [!TIP]
> > > >
> > > > **Analytics Benefit**: Multi-select data provides richer analytics. Instead of knowing a customer chose "Primary Interest: Technology," you know they selected "AI, Cloud Computing, Cybersecurity, Mobile Development" - much more actionable for business intelligence.
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backwards Compatibility**: FlowX.AI 5.0 maintains full backwards compatibility with existing project-to-library dependencies from FlowX.AI 4.x. All existing dependencies will continue to work without modification.
> > >
> > > **Upgrade Process:**
> > >
> > > 1. **Existing dependencies** will be automatically migrated
> > >
> > > 2. **New library dependency features** become available immediately
> > >
> > > 3. **No breaking changes** to existing functionality
> > >
> > > 4. **Enhanced validation** may catch previously undetected issues
> > >
> > > > [!WARNING]
> > > >
> > > > **Post-Migration Required**: After the lib2lib migration is executed, you must clear the cache. This is necessary because a new field is added to the build mongo document.
> > >
> > > **Cache Clearing Steps:**
> > >
> > > 1. Complete the lib2lib migration process
> > > 2. Clear the application cache to ensure the new build document fields are properly recognized
> > > 3. Verify that library-to-library dependencies are functioning correctly
> > >
> > > **Key Changes:**
> > >
> > > * **Build Export Changes**: Build exports now automatically include entire dependency trees (larger packages but self-contained)
> > > * **Dependency Validation**: Build process now checks for dependency conflicts (enhanced validation may catch previously undetected issues)
> > > * **Deployment Consistency**: Single-version constraint prevents runtime conflicts (more predictable deployments)
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Enhanced Organization**: You can now create more sophisticated library structures where specialized libraries build upon common foundations. This reduces duplication and improves consistency.
> > >
> > > **How It Works:**
> > >
> > > 1. Navigate to Library → Config → Dependencies
> > > 2. Add other libraries as dependencies
> > > 3. FlowX.AI validates for conflicts automatically
> > > 4. Resources from all dependency levels become available
> > >
> > > **Best Practices:**
> > >
> > > * Plan your library hierarchy before implementation
> > >
> > > * Keep dependencies focused and purposeful
> > >
> > > * Avoid circular dependencies
> > >
> > > * Use semantic versioning consistently
> > >
> > > * Document dependency relationships clearly
> > >
> > > > [!NOTE]
> > > >
> > > > **Example**: Create a "US Banking Library" that depends on "Global Banking Library" and "US Compliance Library". This way, US-specific processes get both global banking functionality and local compliance requirements automatically.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Enterprise Architecture**: Library-to-Library Dependencies enable sophisticated organizational structures where different teams can own specific business domains while building on shared foundations.
> > >
> > > **Enterprise Use Cases:**
> > >
> > > **Multi-Country Operations:**
> > > Global Insurance Company: US-specific library depends on Global Compliance library
> > >
> > > ```
> > > US Insurance Library → Global Compliance Library → Base Insurance Library
> > > ```
> > >
> > > **Product Line Specialization:**
> > > Bank: Mortgage processes use specialized libraries that extend common banking operations
> > >
> > > ```
> > > Mortgage Library → Lending Library → Core Banking Library
> > > ```
> > >
> > > **Business Impact:**
> > >
> > > * **Team Autonomy**: Teams work independently while leveraging shared assets
> > >
> > > * **Faster Innovation**: New products build on proven foundation components
> > >
> > > * **Risk Reduction**: Tested, validated components reduce implementation risk
> > >
> > > > [!WARNING]
> > > >
> > > > **Change Management**: This capability requires coordination between teams. Establish clear ownership models, communication protocols, and upgrade procedures before implementing complex dependency hierarchies.
>
> ***
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **Zero Infrastructure Impact**: Data Mappers is a design-time feature that enhances the FlowX.AI Designer interface without requiring additional infrastructure or deployment changes.
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backward Compatibility**: All existing data transfer mechanisms (like `append to parent process` or `output.[outputKey]`) continue to work unchanged. Teams can adopt Data Mappers at their own pace.
> > >
> > > **Key Points:**
> > >
> > > * **No new microservices** - Enhancement to existing designer interface
> > > * **No runtime changes** - Data mapping occurs at design time
> > > * **Existing configurations preserved** - Zero impact on current implementations
> > > * **Optional adoption** - Teams choose when and where to use new functionality
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer for Integration**: No more complex syntax for data transfers. Visual drag-and-drop interface makes component integration intuitive and error-free.
> > >
> > > **How to Use Data Mappers:**
> > >
> > > 1. **Define Parameters**: Set input/output parameters on Start/End nodes
> > > 2. **Choose Implementation**: Select "Data Mapper" or "Current" method
> > > 3. **Visual Mapping**: Drag source parameters to destination parameters
> > > 4. **Save Configuration**: Store mappings for reuse and maintenance
> > >
> > > **When to Use:**
> > >
> > > * **Call Activities**: Passing data between parent and child processes
> > >
> > > * **Integration Workflows**: Connecting with external systems
> > >
> > > * **Complex Data Flows**: When visual mapping improves clarity
> > >
> > > * **Team Collaboration**: When multiple people work on integration logic
> > >
> > > > [!WARNING]
> > > >
> > > > **Parameter Changes**: When you modify input/output parameters, existing mappings must be manually updated. Changes don't automatically propagate to avoid unintended data flow modifications.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: Data Mappers transforms technical integration tasks into visual, business-friendly workflows. Non-technical stakeholders can now understand and validate data flows between business processes.
> > >
> > > **Business Impact:**
> > >
> > > * **Reduced Errors**: Visual mapping prevents data integration mistakes that cause process failures
> > > * **Faster Development**: Intuitive interface accelerates process configuration and testing
> > > * **Better Documentation**: Visual data flows serve as living documentation of business logic
> > > * **Team Collaboration**: Business and technical teams can discuss data flows using the same visual interface
> > >
> > > **ROI Indicators:**
> > >
> > > * **Development Speed**: Measure reduction in integration configuration time
> > > * **Error Rate**: Track fewer data-related production issues
> > > * **Team Efficiency**: Monitor cross-functional collaboration improvements
> > > * **Process Quality**: Assess improvement in first-time-right deployments
> > >
> > > **Use Cases by Industry:**
> > >
> > > * **Banking**: Loan application data flowing from customer intake → credit check → approval process
> > > * **Insurance**: Claim data mapping from initial report → investigation → settlement
> > > * **Manufacturing**: Order data flowing from sales → production planning → fulfillment
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Minimal Infrastructure Impact**: Reusable Resources is primarily a design-time enhancement that leverages existing FlowX infrastructure with minimal additional overhead.
> > >
> > > **Infrastructure Considerations:**
> > >
> > > * **Execution Context**: Functions execute within existing process engine contexts - no additional runtime infrastructure required
> > >
> > > > [!TIP]
> > > >
> > > > **No New Microservices**: Features are integrated into existing FlowX.AI platform components
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Development Game Changer**: Access the new "Reusable Resources" section in FlowX.AI Designer - located alongside "Reusable Functions" - to eliminate 60-80% of repetitive development work.
> > >
> > > **Key Capabilities:**
> > >
> > > * **Data Model Support**: Full integration with Project Data Model (PDM)
> > > * **Action Scenarios**: Template-defined actions assigned during instantiation OR form-centric actions handled by User Task
> > > * **Omnichannel**: Templates work across web, mobile, and other channels
> > >
> > > **Best Practices:**
> > >
> > > * **Start with common patterns**: Identify frequently repeated business logic and UI components
> > > * **Test thoroughly**: Use interactive testing for functions and preview mode for templates
> > > * **Document usage**: Include clear descriptions and example use cases
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Revolutionary Business Impact**: Reusable Resources fundamentally changes how organizations approach process development, transforming from "build every time" to "build once, leverage everywhere."
> > >
> > > **Strategic Business Value:**
> > >
> > > * **Quality Assurance**: Dramatic reduction in defects through reusable, tested components
> > > * **Maintenance Efficiency**: Update business rules once to instantly affect all processes
> > > * **Team Productivity**: Developers focus on new business capabilities instead of repetitive development
> > > * **Consistency**: Ensure uniform business rules and user experience across all touchpoints
> > >
> > > **Industry Use Cases:**
> > >
> > > * **Functions**: KYC validation, credit scoring, fraud detection, regulatory compliance checks
> > >
> > > * **UI Templates**: Customer onboarding forms, document upload sections, account summary dashboards, loan application interfaces
> > >
> > > * **Functions**: Premium calculations, risk evaluation, claims processing, policy validation
> > >
> > > * **UI Templates**: Quote request forms, claims submission interfaces, policy comparison tables, agent dashboards
> > >
> > > * **Functions**: Patient eligibility checks, treatment authorization, billing calculations, compliance validation
> > >
> > > * **UI Templates**: Patient registration forms, appointment scheduling interfaces, medical history cards, provider dashboards
>
> ### **Files in Integration Designer**
>
> > [card] File Handling in Integration Designer
> >
> > FlowX.AI 5.0 introduces native file handling capabilities in Integration Designer, enabling seamless file uploads and downloads with external systems directly within your integration workflows.
> >
> > > [card] Download Files
> > >
> > > Call external APIs and receive files in the response. Integration Designer saves files to Document Plugin or S3 and returns paths for further processing.
> >
> > > [card] Upload Files
> > >
> > > Send files stored in Document Plugin or S3 to external APIs via multipart/form-data or single binary requests.
> >
> > > [card] Multiple Formats
> > >
> > > Support for JSON responses with Base64 encoded files and single binary responses with automatic file identification.
> >
> > > [card] Flexible Storage
> > >
> > > Configure file destinations to Document Plugin (process-linked) or S3 Protocol (custom buckets) based on your needs.
> >
> > [Learn more about File Handling in Integration Designer](../../../5.1/docs/platform-deep-dive/integrations/integration-designer#file-handling)
> >
> > New Feature
>
> ### **Rendering Improvements**
>
> > [card] UI/UX Enhancements
> >
> > > [tab] Grid & Layout Improvements
> > >
> > > > [card] Enhanced Grid Component
> > > >
> > > > Improved performance, responsiveness, and customization options for data display and form organization
> > >
> > > > [card] Navigation Areas Redesign
> > > >
> > > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> > >
> > > > [card] Multi Actions Support
> > > >
> > > > Batch operations support for UI components, enabling simultaneous actions on multiple elements
> > >
> > > > [card] Permission-Based UI Editing
> > > >
> > > > Granular control over UI element editing based on user permissions with partial editing capabilities
> >
> > > [tab] Enhanced Form Controls
> > >
> > > > [card] Input Type Code
> > > >
> > > > Specialized input component for code entry
> > >
> > > > [card] Formatting Options
> > > >
> > > > Advanced formatting capabilities for Input and Slider components
> > >
> > > > [card] Switch Variants
> > > >
> > > > Enhanced switch component supporting both toggle and checkbox variants
> > >
> > > > [card] Disabled Options on Selectors
> > > >
> > > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > > [tab] Advanced Features
> > >
> > > > [card] Custom Loader
> > > >
> > > > Configurable loading indicators for improved user experience during data operations
> > >
> > > > [card] Custom Validators
> > > >
> > > > Advanced validation logic using dynamic computed expressions
> > >
> > > > [card] File Upload Button Type
> > > >
> > > > New specialized button variant designed for file upload operations
> > >
> > > > [card] Copy Styles
> > > >
> > > > Efficiently replicate styling across multiple UI components
> >
> > > [tab] Analytics & Process
> > >
> > > > [card] Analytics Enhancements
> > > >
> > > > Custom payload support for detailed user interaction tracking and business intelligence
> > >
> > > > [card] Process End Handling
> > > >
> > > > Improved user experience when processes complete or terminate
> > >
> > > > [card] Forms in Collections
> > > >
> > > > Enhanced support for form elements within collection components
> > >
> > > > [card] Template Management
> > > >
> > > > Streamlined template organization by consolidating functionality in Reusable Resources

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.0](./deployment-guidelines-v5.0)
> >
> > Instructions for deploying FlowX.AI 5.0.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.0/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.0.0


# Deployment guidelines v5.1.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.1 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.0 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.0 → 5.1.1**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.64.3** | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **9.66.5** | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **9.36.3** | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **9.29.1** | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **9.35.1** | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **9.34.2** | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **9.23.1** | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **9.30.1** | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **9.25.1** | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **9.50.0** | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **9.22.1** | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **9.34.2** | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **9.22.1** | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Renderers

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **9.0.5** | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **9.0.3** | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.0 | 0.2.4 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.5** | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.1 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.0 processes and configurations

### What's included in 5.1.1

This maintenance release includes:

* **WCAG 2.1 Level AA compliance** across all web components (28 improvements)
* **3 customer-reported issue fixes** for production environments
* **62 proactive quality improvements** identified through internal testing
* **Platform enhancements** for SSE handling, CMS tags, and infrastructure

For detailed information on all changes, see the [FlowX.AI 5.1.1 Release Notes](./v5.1.1-november-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.1 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.1 | PostgreSQL | 16 - 17 |
| 5.1.1 | Oracle Database | 21c, 23ai |
| 5.1.1 | MongoDB | 7 - 8 |
| 5.1.1 | Redis | 7.4 - 8.0 |
| 5.1.1 | Elasticsearch | 8 |
| 5.1.1 | Angular (Web SDK) | 19.x |
| 5.1.1 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.10 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.9 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.9 → 5.1.10**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **process-engine** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **admin** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **designer** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **cms-core** | 9.46.3 | 9.46.2 | 9.45.4 | 9.44.2 |
| **scheduler-core** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **events-gateway** | 9.36.4 | 9.36.2 | 9.35.4 | 9.34.1 |
| **notification-plugin** | 9.39.3 | 9.39.2 | 9.38.4 | 9.37.1 |
| **document-plugin** | 9.44.3 | 9.44.2 | 9.43.4 | 9.42.2 |
| **task-management-plugin** | 9.43.3 | 9.43.2 | 9.42.4 | 9.41.1 |
| **data-search** | 9.32.3 | 9.32.2 | 9.31.4 | 9.30.1 |
| **audit-core** | 9.40.3 | 9.40.2 | 9.39.4 | 9.38.1 |
| **advancing-controller** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **integration-designer** | 9.59.4 | 9.59.3 | 9.58.5 | 9.57.1 |
| **application-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **runtime-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **data-sync** | 9.33.4 | 9.33.2 | 9.32.3 | 9.31.1 |
| **authorization-system** | 9.43.5 | 9.43.2 | 9.42.4 | 9.41.1 |
| **nosql-db-runner** | 9.31.3 | 9.31.2 | 9.30.4 | 9.29.1 |

### Renderers

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **iOS renderer** | 9.0.25 | 9.0.20 | 9.0.19 | 9.0.12 |
| **Android renderer** | 9.0.31 | 9.0.24 | 9.0.19 | 9.0.13 |

### Plugins

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.7 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.10 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** starting with 5.1.10 the default Redis read mode is `polling` (`EVENTS_REDIS_MODE`). This is applied automatically on upgrade; no action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.9 processes and configurations

### What's included in 5.1.10

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.10 Release Notes](./v5.1.10-june-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.10 | Keycloak | 26+ |
| 5.1.10 | Kafka | 3.8 - 3.9 |
| 5.1.10 | PostgreSQL | 16 - 17 |
| 5.1.10 | Oracle Database | 21c, 23ai |
| 5.1.10 | MongoDB | 7 - 8 |
| 5.1.10 | Redis | 7.4 - 8.0 |
| 5.1.10 | Elasticsearch | 8 - 9 |
| 5.1.10 | Angular (Web SDK) | 19.2 |
| 5.1.10 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.11 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.10 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.10 → 5.1.11**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **process-engine** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **admin** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **designer** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **cms-core** | 9.47.3 | 9.46.3 | 9.46.2 | 9.45.4 |
| **scheduler-core** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **events-gateway** | 9.37.3 | 9.36.4 | 9.36.2 | 9.35.4 |
| **notification-plugin** | 9.40.3 | 9.39.3 | 9.39.2 | 9.38.4 |
| **document-plugin** | 9.45.3 | 9.44.3 | 9.44.2 | 9.43.4 |
| **task-management-plugin** | 9.44.4 | 9.43.3 | 9.43.2 | 9.42.4 |
| **data-search** | 9.33.3 | 9.32.3 | 9.32.2 | 9.31.4 |
| **audit-core** | 9.41.3 | 9.40.3 | 9.40.2 | 9.39.4 |
| **advancing-controller** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **integration-designer** | 9.60.3 | 9.59.4 | 9.59.3 | 9.58.5 |
| **application-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **runtime-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **data-sync** | 9.34.2 | 9.33.4 | 9.33.2 | 9.32.3 |
| **authorization-system** | 9.44.4 | 9.43.5 | 9.43.2 | 9.42.4 |
| **nosql-db-runner** | 9.32.3 | 9.31.3 | 9.31.2 | 9.30.4 |

### Renderers

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **iOS renderer** | 9.0.27 | 9.0.25 | 9.0.20 | 9.0.19 |
| **Android renderer** | 9.0.37 | 9.0.31 | 9.0.24 | 9.0.19 |

### Plugins

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.7 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.11 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.10 processes and configurations

### What's included in 5.1.11

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.11 Release Notes](./v5.1.11-july-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.11 | Keycloak | 26+ |
| 5.1.11 | Kafka | 3.8, 3.9 |
| 5.1.11 | PostgreSQL | 16, 17 |
| 5.1.11 | Oracle Database | 21c, 23ai |
| 5.1.11 | MongoDB | 7, 8 |
| 5.1.11 | Redis | 7, 8 |
| 5.1.11 | Elasticsearch | 8 |
| 5.1.11 | Angular (Web SDK) | 19.2 |
| 5.1.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.12

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.12 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.11 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.11 → 5.1.12**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **process-engine** | 9.76.7 | 9.76.3 | 9.75.7 | 9.75.3 |
| **admin** | 9.76.6 | 9.76.3 | 9.75.7 | 9.75.3 |
| **designer** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **cms-core** | 9.47.5 | 9.47.3 | 9.46.3 | 9.46.2 |
| **scheduler-core** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **events-gateway** | 9.37.4 | 9.37.3 | 9.36.4 | 9.36.2 |
| **notification-plugin** | 9.40.4 | 9.40.3 | 9.39.3 | 9.39.2 |
| **document-plugin** | 9.45.4 | 9.45.3 | 9.44.3 | 9.44.2 |
| **task-management-plugin** | 9.44.6 | 9.44.4 | 9.43.3 | 9.43.2 |
| **data-search** | 9.33.4 | 9.33.3 | 9.32.3 | 9.32.2 |
| **audit-core** | 9.41.4 | 9.41.3 | 9.40.3 | 9.40.2 |
| **advancing-controller** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **integration-designer** | 9.60.5 | 9.60.3 | 9.59.4 | 9.59.3 |
| **application-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **runtime-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **data-sync** | 9.34.3 | 9.34.2 | 9.33.4 | 9.33.2 |
| **authorization-system** | 9.44.5 | 9.44.4 | 9.43.5 | 9.43.2 |
| **nosql-db-runner** | 9.32.4 | 9.32.3 | 9.31.3 | 9.31.2 |

### Renderers

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **iOS renderer** | 9.0.29 | 9.0.27 | 9.0.25 | 9.0.20 |
| **Android renderer** | 9.0.39 | 9.0.37 | 9.0.31 | 9.0.24 |

### Plugins

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.7 | 0.2.6 |

### AI Platform

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.12 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.11 processes and configurations

### What's included in 5.1.12

This maintenance release includes:

* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.12 Release Notes](./v5.1.12-august-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.12 | Keycloak | 26+ |
| 5.1.12 | Kafka | 3.8, 3.9 |
| 5.1.12 | PostgreSQL | 16, 17 |
| 5.1.12 | Oracle Database | 21c, 23ai |
| 5.1.12 | MongoDB | 7, 8 |
| 5.1.12 | Redis | 7, 8 |
| 5.1.12 | Elasticsearch | 8 |
| 5.1.12 | Angular (Web SDK) | 19.2 |
| 5.1.12 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.13
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.13

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.13 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.12 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.12 → 5.1.13**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **process-engine** | 9.76.10 | 9.76.7 | 9.76.3 | 9.75.7 |
| **admin** | 9.76.8 | 9.76.6 | 9.76.3 | 9.75.7 |
| **designer** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **cms-core** | 9.47.6 | 9.47.5 | 9.47.3 | 9.46.3 |
| **scheduler-core** | 9.36.5 | 9.36.4 | 9.36.3 | 9.35.3 |
| **events-gateway** | 9.37.5 | 9.37.4 | 9.37.3 | 9.36.4 |
| **notification-plugin** | 9.40.5 | 9.40.4 | 9.40.3 | 9.39.3 |
| **document-plugin** | 9.45.5 | 9.45.4 | 9.45.3 | 9.44.3 |
| **task-management-plugin** | 9.44.7 | 9.44.6 | 9.44.4 | 9.43.3 |
| **data-search** | 9.33.5 | 9.33.4 | 9.33.3 | 9.32.3 |
| **audit-core** | 9.41.5 | 9.41.4 | 9.41.3 | 9.40.3 |
| **advancing-controller** | 9.36.6 | 9.36.4 | 9.36.3 | 9.35.3 |
| **integration-designer** | 9.60.7 | 9.60.5 | 9.60.3 | 9.59.4 |
| **application-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **runtime-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **data-sync** | 9.34.4 | 9.34.3 | 9.34.2 | 9.33.4 |
| **authorization-system** | 9.44.6 | 9.44.5 | 9.44.4 | 9.43.5 |
| **nosql-db-runner** | 9.32.5 | 9.32.4 | 9.32.3 | 9.31.3 |

### Renderers

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **iOS renderer** | 9.0.32 | 9.0.29 | 9.0.27 | 9.0.25 |
| **Android renderer** | 9.0.44 | 9.0.39 | 9.0.37 | 9.0.31 |

### Plugins

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.7 |

### AI Platform

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.13 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.12 processes and configurations

### What's included in 5.1.13

This maintenance release includes:

* **Reliability fixes** for process advancing under load
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.13 Release Notes](./v5.1.13-september-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.13 | Keycloak | 26+ |
| 5.1.13 | Kafka | 3.8, 3.9 |
| 5.1.13 | PostgreSQL | 16, 17 |
| 5.1.13 | Oracle Database | 21c, 23ai |
| 5.1.13 | MongoDB | 7, 8 |
| 5.1.13 | Redis | 7, 8 |
| 5.1.13 | Elasticsearch | 8 |
| 5.1.13 | Angular (Web SDK) | 19.2 |
| 5.1.13 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.14
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.14

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.14 is the final planned maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.13 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.13 → 5.1.14**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **process-engine** | 9.76.12 | 9.76.10 | 9.76.7 | 9.76.3 |
| **admin** | 9.76.10 | 9.76.8 | 9.76.6 | 9.76.3 |
| **designer** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **cms-core** | 9.47.8 | 9.47.6 | 9.47.5 | 9.47.3 |
| **scheduler-core** | 9.36.7 | 9.36.5 | 9.36.4 | 9.36.3 |
| **events-gateway** | 9.37.7 | 9.37.5 | 9.37.4 | 9.37.3 |
| **notification-plugin** | 9.40.7 | 9.40.5 | 9.40.4 | 9.40.3 |
| **document-plugin** | 9.45.7 | 9.45.5 | 9.45.4 | 9.45.3 |
| **task-management-plugin** | 9.44.9 | 9.44.7 | 9.44.6 | 9.44.4 |
| **data-search** | 9.33.7 | 9.33.5 | 9.33.4 | 9.33.3 |
| **audit-core** | 9.41.8 | 9.41.5 | 9.41.4 | 9.41.3 |
| **advancing-controller** | 9.36.8 | 9.36.6 | 9.36.4 | 9.36.3 |
| **integration-designer** | 9.60.9 | 9.60.7 | 9.60.5 | 9.60.3 |
| **application-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **runtime-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **data-sync** | 9.34.6 | 9.34.4 | 9.34.3 | 9.34.2 |
| **authorization-system** | 9.44.8 | 9.44.6 | 9.44.5 | 9.44.4 |
| **nosql-db-runner** | 9.32.7 | 9.32.5 | 9.32.4 | 9.32.3 |

### Renderers

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **iOS renderer** | 9.0.38 | 9.0.32 | 9.0.29 | 9.0.27 |
| **Android renderer** | 9.0.48 | 9.0.44 | 9.0.39 | 9.0.37 |

### Plugins

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.8 |

### AI Platform

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Version | Description |
| - | - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | 1.52.0 | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | 1.25.1 | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | 25.0.0-preview6 | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.14 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release. The audit index retention settings below are optional.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted | audit-core |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only | audit-core |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch).

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.13 processes and configurations

### What's included in 5.1.14

This maintenance release includes:

* **Android renderer fix** for the action loader on modal screens
* **Optional audit index retention** and shard-size rollover settings
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.14 Release Notes](./v5.1.14-october-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.14 | Keycloak | 26+ |
| 5.1.14 | Kafka | 3.8, 3.9 |
| 5.1.14 | PostgreSQL | 16, 17 |
| 5.1.14 | Oracle Database | 21c, 23ai |
| 5.1.14 | MongoDB | 7, 8 |
| 5.1.14 | Redis | 7, 8 |
| 5.1.14 | Elasticsearch | 8 |
| 5.1.14 | Angular (Web SDK) | 19.2 |
| 5.1.14 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.2 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.1 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.1 → 5.1.2**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **process-engine** | **9.67.0** | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **9.68.1** | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **9.39.0** | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **9.28.1** | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **9.29.0** | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **9.32.0** | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **9.37.1** | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **9.25.1** | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **9.33.0** | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **9.28.0** | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **9.52.1** | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **9.26.0** | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **9.24.1** | 9.22.1 | 9.21.0 | 9.11.0 |

### Renderers

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **9.0.7** | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **9.0.5** | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.0 |

### AI Platform

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.6** | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.2 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.1 processes and configurations

### What's included in 5.1.2

This maintenance release includes:

* **Bug fixes** addressing customer-reported issues
* **Stability improvements** for platform reliability
* **Quality enhancements** identified through internal testing

For detailed information on all changes, see the [FlowX.AI 5.1.2 Release Notes](./v5.1.2-december-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.2 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.2 | PostgreSQL | 16 - 17 |
| 5.1.2 | Oracle Database | 21c, 23ai |
| 5.1.2 | MongoDB | 7 - 8 |
| 5.1.2 | Redis | 7.4 - 8.0 |
| 5.1.2 | Elasticsearch | 8 |
| 5.1.2 | Angular (Web SDK) | 19.x |
| 5.1.2 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.3 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.2 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.2 → 5.1.3**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **process-engine** | **9.70.1** | 9.67.0 | 9.64.3 | 9.63.0 |
| **admin** | **9.70.2** | 9.68.1 | 9.66.5 | 9.65.0 |
| **designer** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **cms-core** | **9.41.1** | 9.39.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **9.30.1** | 9.28.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **9.31.2** | 9.29.0 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **9.34.1** | 9.32.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **9.39.1** | 9.37.1 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **9.38.2** | 9.36.1 | 9.34.2 | 9.33.0 |
| **data-search** | **9.27.1** | 9.25.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **9.35.1** | 9.33.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **9.30.2** | 9.28.0 | 9.25.1 | 9.24.0 |
| **integration-designer** | **9.54.1** | 9.52.1 | 9.50.0 | 9.49.1 |
| **application-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **data-sync** | **9.28.1** | 9.26.0 | 9.22.1 | 9.21.0 |
| **authorization-system** | **9.38.1** | 9.36.1 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **9.26.1** | 9.24.1 | 9.22.1 | 9.21.0 |

### Renderers

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **9.0.8** | 9.0.7 | 9.0.5 | 9.0.4 |
| **Android renderer** | **9.0.6** | 9.0.5 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.7** | 9.2.6 | 9.2.5 | 9.2.4 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.3 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes required\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.2 processes and configurations

### Optional configuration

A new optional environment variable is available for process-engine:

| Variable | Description | Default |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from platform components | Falls back to `KAFKA_TOPIC_PATTERN` |

> [!NOTE]
>
> This allows connectors to use custom topic patterns without affecting other components like document-plugin, data-search, and cms-core that use `ai.flowx.engine.receive.*`.

### What's included in 5.1.3

This maintenance release includes:

* **Security fixes**
* **Bug fixes** addressing customer-reported issues

For detailed information on all changes, see the [FlowX.AI 5.1.3 Release Notes](./v5.1.3-january-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.3 | Keycloak | 26+ |
| 5.1.3 | Kafka | 3.8 - 3.9 |
| 5.1.3 | PostgreSQL | 16 - 17 |
| 5.1.3 | Oracle Database | 21c, 23ai |
| 5.1.3 | MongoDB | 7 - 8 |
| 5.1.3 | Redis | 7.4 - 8.0 |
| 5.1.3 | Elasticsearch | 8 |
| 5.1.3 | Angular (Web SDK) | 19.2 |
| 5.1.3 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.4 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.3 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.3 → 5.1.4**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **process-engine** | **9.72.2** | 9.70.1 | 9.67.0 | 9.64.3 |
| **admin** | **9.72.0** | 9.70.2 | 9.68.1 | 9.66.5 |
| **designer** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **cms-core** | **9.43.1** | 9.41.1 | 9.39.0 | 9.36.3 |
| **scheduler-core** | **9.32.0** | 9.30.1 | 9.28.1 | 9.26.1 |
| **events-gateway** | **9.33.0** | 9.31.2 | 9.29.0 | 9.26.1 |
| **notification-plugin** | **9.36.0** | 9.34.1 | 9.32.0 | 9.29.1 |
| **document-plugin** | **9.41.1** | 9.39.1 | 9.37.1 | 9.35.1 |
| **task-management-plugin** | **9.40.0** | 9.38.2 | 9.36.1 | 9.34.2 |
| **data-search** | **9.29.0** | 9.27.1 | 9.25.1 | 9.23.1 |
| **audit-core** | **9.37.0** | 9.35.1 | 9.33.0 | 9.30.1 |
| **advancing-controller** | **9.32.0** | 9.30.2 | 9.28.0 | 9.25.1 |
| **integration-designer** | **9.56.0** | 9.54.1 | 9.52.1 | 9.50.0 |
| **application-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **runtime-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **data-sync** | **9.30.1** | 9.28.1 | 9.26.0 | 9.22.1 |
| **authorization-system** | **9.40.1** | 9.38.1 | 9.36.1 | 9.34.2 |
| **nosql-db-runner** | **9.28.0** | 9.26.1 | 9.24.1 | 9.22.1 |

### Renderers

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **iOS renderer** | **9.0.9** | 9.0.8 | 9.0.7 | 9.0.5 |
| **Android renderer** | **9.0.7** | 9.0.6 | 9.0.5 | 9.0.3 |

### Plugins

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.8** | 9.2.7 | 9.2.6 | 9.2.5 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.4 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.3 processes and configurations

#### New environment variables (optional)

The following optional environment variables have been added for the **process-engine** to configure config params caching:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120` | process-engine |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache | `500` | process-engine |

> [!NOTE]
>
> These variables are optional. If not configured, the default values will be used. Adjust these values based on how frequently your configuration changes and your memory constraints.
>
> For more details, see [Engine Setup - Config params cache](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).

### What's included in 5.1.4

This maintenance release includes:

* **Security patches** addressing identified vulnerabilities
* **Bug fixes** addressing customer-reported issues
* **Platform improvements** including cache improvements, Kafka environment variable alignment, SSE metrics enhancements, and infrastructure updates

For detailed information on all changes, see the [FlowX.AI 5.1.4 Release Notes](./v5.1.4-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.4 | Keycloak | 26+ |
| 5.1.4 | Kafka | 3.8 - 3.9 |
| 5.1.4 | PostgreSQL | 16 - 17 |
| 5.1.4 | Oracle Database | 21c, 23ai |
| 5.1.4 | MongoDB | 7 - 8 |
| 5.1.4 | Redis | 7.4 - 8.0 |
| 5.1.4 | Elasticsearch | 8 |
| 5.1.4 | Angular (Web SDK) | 19.2 |
| 5.1.4 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.5 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.4 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.4 → 5.1.5**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **process-engine** | **9.72.5** | 9.72.2 | 9.70.1 | 9.67.0 |
| **admin** | **9.72.2** | 9.72.0 | 9.70.2 | 9.68.1 |
| **designer** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **cms-core** | **9.43.3** | 9.43.1 | 9.41.1 | 9.39.0 |
| **scheduler-core** | **9.32.2** | 9.32.0 | 9.30.1 | 9.28.1 |
| **events-gateway** | **9.33.2** | 9.33.0 | 9.31.2 | 9.29.0 |
| **notification-plugin** | **9.36.2** | 9.36.0 | 9.34.1 | 9.32.0 |
| **document-plugin** | **9.41.3** | 9.41.1 | 9.39.1 | 9.37.1 |
| **task-management-plugin** | **9.40.2** | 9.40.0 | 9.38.2 | 9.36.1 |
| **data-search** | **9.29.2** | 9.29.0 | 9.27.1 | 9.25.1 |
| **audit-core** | **9.37.2** | 9.37.0 | 9.35.1 | 9.33.0 |
| **advancing-controller** | **9.32.1** | 9.32.0 | 9.30.2 | 9.28.0 |
| **integration-designer** | **9.56.2** | 9.56.0 | 9.54.1 | 9.52.1 |
| **application-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **runtime-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **data-sync** | **9.30.2** | 9.30.1 | 9.28.1 | 9.26.0 |
| **authorization-system** | **9.40.2** | 9.40.1 | 9.38.1 | 9.36.1 |
| **nosql-db-runner** | **9.28.2** | 9.28.0 | 9.26.1 | 9.24.1 |

### Renderers

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **iOS renderer** | **9.0.10** | 9.0.9 | 9.0.8 | 9.0.7 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.6 | 9.0.5 |

### Plugins

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.9** | 9.2.8 | 9.2.7 | 9.2.6 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.5 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No new environment variables
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.4 processes and configurations

### What's included in 5.1.5

This maintenance release includes:

* **Bug fixes** for process loop rendering issues in the Angular renderer
* **Bug fixes** for subprocess output data not being returned from embedded processes

For detailed information on all changes, see the [FlowX.AI 5.1.5 Release Notes](./v5.1.5-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.5 | Keycloak | 26+ |
| 5.1.5 | Kafka | 3.8 - 3.9 |
| 5.1.5 | PostgreSQL | 16 - 17 |
| 5.1.5 | Oracle Database | 21c, 23ai |
| 5.1.5 | MongoDB | 7 - 8 |
| 5.1.5 | Redis | 7.4 - 8.0 |
| 5.1.5 | Elasticsearch | 8 |
| 5.1.5 | Angular (Web SDK) | 19.2 |
| 5.1.5 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.6 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.5 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.5 → 5.1.6**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **process-engine** | **9.72.7** | 9.72.5 | 9.72.2 | 9.70.1 |
| **admin** | **9.72.4** | 9.72.2 | 9.72.0 | 9.70.2 |
| **designer** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **cms-core** | **9.43.5** | 9.43.3 | 9.43.1 | 9.41.1 |
| **scheduler-core** | **9.32.4** | 9.32.2 | 9.32.0 | 9.30.1 |
| **events-gateway** | **9.33.4** | 9.33.2 | 9.33.0 | 9.31.2 |
| **notification-plugin** | **9.36.4** | 9.36.2 | 9.36.0 | 9.34.1 |
| **document-plugin** | **9.41.5** | 9.41.3 | 9.41.1 | 9.39.1 |
| **task-management-plugin** | **9.40.4** | 9.40.2 | 9.40.0 | 9.38.2 |
| **data-search** | **9.29.4** | 9.29.2 | 9.29.0 | 9.27.1 |
| **audit-core** | **9.37.4** | 9.37.2 | 9.37.0 | 9.35.1 |
| **advancing-controller** | **9.32.3** | 9.32.1 | 9.32.0 | 9.30.2 |
| **integration-designer** | **9.56.3** | 9.56.2 | 9.56.0 | 9.54.1 |
| **application-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **runtime-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **data-sync** | **9.30.4** | 9.30.2 | 9.30.1 | 9.28.1 |
| **authorization-system** | **9.40.3** | 9.40.2 | 9.40.1 | 9.38.1 |
| **nosql-db-runner** | **9.28.4** | 9.28.2 | 9.28.0 | 9.26.1 |

### Renderers

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **iOS renderer** | **9.0.11** | 9.0.10 | 9.0.9 | 9.0.8 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.7 | 9.0.6 |

### Plugins

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.8 | 9.2.7 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.6 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> This release introduces optional environment variables for the process engine retry mechanism. These are not required — defaults work for most deployments.

#### Process engine — retry configuration (optional)

The following optional environment variables configure the exponential backoff with Equal Jitter strategy used for optimistic locking retries:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` | process-engine |

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.5 processes and configurations

### What's included in 5.1.6

This maintenance release includes:

* **Bug fixes** for React renderer: modals, sliders, datepicker, selectors, disabled state, and accessibility
* **Bug fixes** for Angular + React renderer: card accordion height, focus outlines, button icon layout
* **Bug fix** for process engine advancing getting stuck on pod crash
* **Bug fix** for connection leak in application-manager export/import
* **Improvement** for configurable retry mechanism with exponential backoff
* **Security patches** across all platform components

For detailed information on all changes, see the [FlowX.AI 5.1.6 Release Notes](./v5.1.6-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.6 | Keycloak | 26+ |
| 5.1.6 | Kafka | 3.8 - 3.9 |
| 5.1.6 | PostgreSQL | 16 - 17 |
| 5.1.6 | Oracle Database | 21c, 23ai |
| 5.1.6 | MongoDB | 7 - 8 |
| 5.1.6 | Redis | 7.4 - 8.0 |
| 5.1.6 | Elasticsearch | 8 |
| 5.1.6 | Angular (Web SDK) | 19.2 |
| 5.1.6 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.7
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.7 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.6 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.6 → 5.1.7**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **process-engine** | **9.73.1** | 9.72.7 | 9.72.5 | 9.72.2 |
| **admin** | **9.73.1** | 9.72.4 | 9.72.2 | 9.72.0 |
| **designer** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **cms-core** | **9.44.2** | 9.43.5 | 9.43.3 | 9.43.1 |
| **scheduler-core** | **9.33.1** | 9.32.4 | 9.32.2 | 9.32.0 |
| **events-gateway** | **9.34.1** | 9.33.4 | 9.33.2 | 9.33.0 |
| **notification-plugin** | **9.37.1** | 9.36.4 | 9.36.2 | 9.36.0 |
| **document-plugin** | **9.42.2** | 9.41.5 | 9.41.3 | 9.41.1 |
| **task-management-plugin** | **9.41.1** | 9.40.4 | 9.40.2 | 9.40.0 |
| **data-search** | **9.30.1** | 9.29.4 | 9.29.2 | 9.29.0 |
| **audit-core** | **9.38.1** | 9.37.4 | 9.37.2 | 9.37.0 |
| **advancing-controller** | **9.33.1** | 9.32.3 | 9.32.1 | 9.32.0 |
| **integration-designer** | **9.57.1** | 9.56.3 | 9.56.2 | 9.56.0 |
| **application-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **runtime-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **data-sync** | **9.31.1** | 9.30.4 | 9.30.2 | 9.30.1 |
| **authorization-system** | **9.41.1** | 9.40.3 | 9.40.2 | 9.40.1 |
| **nosql-db-runner** | **9.29.1** | 9.28.4 | 9.28.2 | 9.28.0 |

### Renderers

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **iOS renderer** | **9.0.12** | 9.0.11 | 9.0.10 | 9.0.9 |
| **Android renderer** | **9.0.13** | 9.0.7 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI Platform

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.8 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.7 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.6 processes and configurations

### What's included in 5.1.7

This maintenance release includes:

* **Bug fix** for build reimport failures with manifest issues
* **Security patches** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.7 Release Notes](./v5.1.7-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.7 | Keycloak | 26+ |
| 5.1.7 | Kafka | 3.8 - 3.9 |
| 5.1.7 | PostgreSQL | 16 - 17 |
| 5.1.7 | Oracle Database | 21c, 23ai |
| 5.1.7 | MongoDB | 7 - 8 |
| 5.1.7 | Redis | 7.4 - 8.0 |
| 5.1.7 | Elasticsearch | 8 |
| 5.1.7 | Angular (Web SDK) | 19.2 |
| 5.1.7 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.8
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.8 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.7 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.7 → 5.1.8**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **process-engine** | **9.74.4** | 9.73.1 | 9.72.7 | 9.72.5 |
| **admin** | **9.74.4** | 9.73.1 | 9.72.4 | 9.72.2 |
| **designer** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **cms-core** | **9.45.4** | 9.44.2 | 9.43.5 | 9.43.3 |
| **scheduler-core** | **9.34.4** | 9.33.1 | 9.32.4 | 9.32.2 |
| **events-gateway** | **9.35.4** | 9.34.1 | 9.33.4 | 9.33.2 |
| **notification-plugin** | **9.38.4** | 9.37.1 | 9.36.4 | 9.36.2 |
| **document-plugin** | **9.43.4** | 9.42.2 | 9.41.5 | 9.41.3 |
| **task-management-plugin** | **9.42.4** | 9.41.1 | 9.40.4 | 9.40.2 |
| **data-search** | **9.31.4** | 9.30.1 | 9.29.4 | 9.29.2 |
| **audit-core** | **9.39.4** | 9.38.1 | 9.37.4 | 9.37.2 |
| **advancing-controller** | **9.34.4** | 9.33.1 | 9.32.3 | 9.32.1 |
| **integration-designer** | **9.58.5** | 9.57.1 | 9.56.3 | 9.56.2 |
| **application-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **runtime-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **data-sync** | **9.32.3** | 9.31.1 | 9.30.4 | 9.30.2 |
| **authorization-system** | **9.42.4** | 9.41.1 | 9.40.3 | 9.40.2 |
| **nosql-db-runner** | **9.30.4** | 9.29.1 | 9.28.4 | 9.28.2 |

### Renderers

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **iOS renderer** | **9.0.19** | 9.0.12 | 9.0.11 | 9.0.10 |
| **Android renderer** | **9.0.19** | 9.0.13 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.8 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.7 processes and configurations

### What's included in 5.1.8

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.8 Release Notes](./v5.1.8-april-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.8 | Keycloak | 26+ |
| 5.1.8 | Kafka | 3.8 - 3.9 |
| 5.1.8 | PostgreSQL | 16 - 17 |
| 5.1.8 | Oracle Database | 21c, 23ai |
| 5.1.8 | MongoDB | 7 - 8 |
| 5.1.8 | Redis | 7.4 - 8.0 |
| 5.1.8 | Elasticsearch | 8 |
| 5.1.8 | Angular (Web SDK) | 19.2 |
| 5.1.8 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.9
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.9 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.8 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.8 → 5.1.9**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **process-engine** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.7 |
| **admin** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.4 |
| **designer** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **cms-core** | **9.46.2** | 9.45.4 | 9.44.2 | 9.43.5 |
| **scheduler-core** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.4 |
| **events-gateway** | **9.36.2** | 9.35.4 | 9.34.1 | 9.33.4 |
| **notification-plugin** | **9.39.2** | 9.38.4 | 9.37.1 | 9.36.4 |
| **document-plugin** | **9.44.2** | 9.43.4 | 9.42.2 | 9.41.5 |
| **task-management-plugin** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.4 |
| **data-search** | **9.32.2** | 9.31.4 | 9.30.1 | 9.29.4 |
| **audit-core** | **9.40.2** | 9.39.4 | 9.38.1 | 9.37.4 |
| **advancing-controller** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.3 |
| **integration-designer** | **9.59.3** | 9.58.5 | 9.57.1 | 9.56.3 |
| **application-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **runtime-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **data-sync** | **9.33.2** | 9.32.3 | 9.31.1 | 9.30.4 |
| **authorization-system** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.3 |
| **nosql-db-runner** | **9.31.2** | 9.30.4 | 9.29.1 | 9.28.4 |

### Renderers

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **iOS renderer** | **9.0.20** | 9.0.19 | 9.0.12 | 9.0.11 |
| **Android renderer** | **9.0.24** | 9.0.19 | 9.0.13 | 9.0.7 |

### Plugins

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.9 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.8 processes and configurations

### What's included in 5.1.9

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.9 Release Notes](./v5.1.9-may-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.9 | Keycloak | 26+ |
| 5.1.9 | Kafka | 3.8 - 3.9 |
| 5.1.9 | PostgreSQL | 16 - 17 |
| 5.1.9 | Oracle Database | 21c, 23ai |
| 5.1.9 | MongoDB | 7 - 8 |
| 5.1.9 | Redis | 7.4 - 8.0 |
| 5.1.9 | Elasticsearch | 8 - 9 |
| 5.1.9 | Angular (Web SDK) | 19.2 |
| 5.1.9 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/deployment-guidelines-v5.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.63.0** | 9.29.2 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.65.0** | 9.25.2 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.35.0** | 9.21.2 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.28.0** | 9.14.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.34.0** | 9.17.2 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.33.0** | 9.14.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.22.0** | 9.12.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.29.1** | 9.15.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.24.0** | 9.11.0 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.49.1** | 9.26.2 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.21.0** | 9.11.0 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.33.0** | 9.14.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.21.0** | 9.11.0 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.4** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.2** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | **0.2.4** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.4** | 9.2.3 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.3.1** | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.0 | Keycloak | 26+ |
| 5.1.0 | Kafka | 3.8 - 3.9 |
| 5.1.0 | PostgreSQL | 16 - 17 |
| 5.1.0 | Oracle Database | 21c, 23ai |
| 5.1.0 | MongoDB | 7 - 8 |
| 5.1.0 | Redis | 7.4 - 8.0 |
| 5.1.0 | Elasticsearch | 8 - 9 |
| 5.1.0 | Angular (Web SDK) | 19.x |
| 5.1.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/configuration-and-migration

This section contains the steps in order that we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](/5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.1.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.1.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.1.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The auth-system will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from app-manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Document plugin

> [!NOTE]
>
> New configuration option for test documents bucket customization.

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILE_STORAGE_TEST_FILES_BUCKET` | `-test-documents` | Overrides the default test documents bucket suffix. Use this to configure a custom bucket name for test files. |

> [!NOTE]
>
> This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed.

## Kafka configuration

> [!NOTE]
>
> Complete Kafka migration including consumer group standardization to kebab-case, comprehensive topic restructuring with new versioned naming patterns, and enhanced messaging features across all FlowX.AI services.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group migrations

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Kafka topic migrations

> [!NOTE]
>
> All Kafka topics migrate to versioned naming pattern `ai.flowx.{env}.{service}.{operation}.v1` for improved organization and future compatibility.

> [tab] Application Manager
>
> **Application resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
>
> **Sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS_IN` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE_IN` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE_IN` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN` | `ai.flowx.application-version.sync.out.v1` |
>
> **Resource update propagation:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | `ai.flowx.application-version.resource.update.propagation.v1` |
>
> **Build resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

> [tab] Admin
>
> **Consumer groups:**
>
> | Environment Variable | New Consumer Group | Threads |
> | - | - | - |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_SYNC` | `process-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC` | `business-rule-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC` | `reusable-template-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION` | `processCorrectionAfterAppOperationGroup` | `6` |
>
> **Application sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE` | `ai.flowx.application-version.sync.out.v1` |
> | `KAFKA_TOPIC_APPLICATION_PROCESS_SYNC` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
>
> **Application correction after app operation topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
>
> **Build topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

### New Kafka features

> [card] Resource Update Propagation
>
> **Consumer Group:** `app-resource-update-propagation-group`\
> **Threads:** 3\
> **Topic:** `ai.flowx.{env}.application-version.resource.update.propagation.v1`\
> **Purpose:** Real-time resource change propagation

> [card] Build Runtime Data
>
> **Consumer Group:** `build-runtime-data-group`\
> **Threads:** 2\
> **Topic:** `ai.flowx.{env}.build.runtime-data.v1`\
> **Purpose:** Build process data management

> [card] Business Rule Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> **Purpose:** Enhanced business rule synchronization\
> **Consumer Group:** `business-rule-sync-group`

> [card] Process Sync Enhanced
>
> **Topic:** `ai.flowx.{env}.application-version.sync.process.in.v1`\
> **Purpose:** Improved process synchronization\
> **Consumer Group:** `process-sync-group`

> [card] Reusable Template Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> **Purpose:** Template synchronization\
> **Consumer Group:** `reusable-template-sync-group`

> [card] Correction After App Operation
>
> **Multiple Topics:** Process, business rule, and template correction\
> **Purpose:** Post-deployment resource correction\
> **Consumer Group:** `processCorrectionAfterAppOperationGroup`

### Configure environment variables

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides. Only override when custom naming is required.

```bash Application Manager Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Sync Topics
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
```

```bash Admin Topics theme={"dark"}
# Application Sync
KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE=ai.flowx.dev.application-version.sync.out.v1
KAFKA_TOPIC_APPLICATION_PROCESS_SYNC=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT=ai.flowx.dev.application-version.correction-after-app-operation.response.v1
```

```bash Consumer Groups and Threads theme={"dark"}
# Application Manager Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Admin Consumer Groups  
KAFKA_CONSUMER_GROUPID_PROCESS_SYNC=process-sync-group
KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC=business-rule-sync-group
KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC=reusable-template-sync-group
KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION=processCorrectionAfterAppOperationGroup

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
KAFKA_CONSUMER_THREADS_PROCESS_SYNC=6
KAFKA_CONSUMER_THREADS_BUSINESS_RULE_SYNC=6
KAFKA_CONSUMER_THREADS_REUSABLE_TEMPLATE_SYNC=6
KAFKA_CONSUMER_THREADS_PROCESS_CORRECTIONAFTERAPPOPERATION=6
```

### Additional Application Manager variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | Maximum HTTP request header size |

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | Redis host |
| `SPRING_REDIS_PORT` | `6379` | Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | Redis password |
| `SPRING_REDIS_TTL` | `5000000` | Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | Redis host |

## FlowX Engine

> [!NOTE]
>
> The ADVANCING controller has been redesigned with separate picking and processing operations for improved performance and resource management.

### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.

### Elasticsearch indexing configuration

> [!NOTE]
>
> Elasticsearch indexing environment variables have been updated with new naming conventions for better consistency with FlowX naming standards.

#### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEXING_TYPE` | `FLOWX_INDEXING_TYPE` | `kafka` | `kafka` |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` | `process_instance` |
| `FLOWX_INDEXING_PROCESSINSTANCE_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `FLOWX_INDEXING_PROCESSINSTANCE_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

> [!NOTE]
>
> For complete Elasticsearch indexing setup including Kafka Connect configuration and time-based partitioning, see the [Configuring Elasticsearch indexing](/5.1/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing) guide.

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.

### Development environment exception

> [!NOTE]
>
> For development environments only, `CONFIG_PROFILE` migrates to the standard Spring configuration profile variable.

| Remove This Variable | Replace With | Environment |
| - | - | - |
| `CONFIG_PROFILE` | `SPRING_CONFIG_PROFILE` | devenv only |

## SpiceDB integration

> [!NOTE]
>
> FlowX.AI 5.1 introduces SpiceDB integration for enhanced authorization capabilities across all core services.

### Services affected

The following services require new SpiceDB configuration variables:

* Admin
* Application Manager
* Audit Core
* CMS Core
* Document Plugin
* Integration Designer
* Notification Plugin
* Process Engine
* Runtime Manager
* Task Management Plugin

### New variables to add

For every CAS configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_SPICEDB_TOKEN` | *(secret)* | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Data sync updates

### Data Sync additional variables

For every Data-Sync configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_URL` | - | Authentication system URL. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME` | - | Authentication system username. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` | - | Authentication system password. |
| `FLOWX_SPICEDB_TOKEN` | - | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Kafka topic naming

### Global configuration change

| Variable | Old Default | New Default | Description |
| - | - | - | - |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | (varies) | `""` | Moved to default empty environment |

> [!NOTE]
>
> This change standardizes topic naming across environments by defaulting to an empty environment identifier.

## CORS and ingress updates

> [!WARNING]
>
> All services with Kubernetes ingress configurations now require the `Fx-Workspace-Id` header for workspace identification in multi-tenant environments.

### Standard ingress pattern

FlowX.AI v5.1 introduces a standardized ingress configuration pattern for all services. The key change is adding the `Fx-Workspace-Id` header to the CORS configuration.

**Required annotation update:**

```yaml theme={"dark"}
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
```

### Services requiring updates

All FlowX.AI services that expose ingress endpoints require this update:

| Service | Fx-Workspace-Id Required | Reference |
| - | - | - |
| Admin | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Application Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Audit Core | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Authorization System | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Events Gateway | ❌ No (SSE) | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) |
| Integration Designer | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Process Engine | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Runtime Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Task Management | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |

> [card] [Complete Ingress Configuration Guide](../../../../../5.1/setup-guides/ingress-configuration)
>
> View the complete ingress configuration pattern including:
>
> * Standard template for all services
> * Service-specific paths and rewrite rules
> * Annotation explanations
> * Troubleshooting guide
> * Environment-specific customization

> [!NOTE]
>
> **Exception:** Events Gateway does not require the `Fx-Workspace-Id` header because it handles Server-Sent Events (SSE) with different security requirements. See the [Events Gateway exception](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) section for details.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/install-services

Step-by-step installation guide for new FlowX.AI 5.1.0 services

FlowX.AI 5.1.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](../../../../../5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](../../../../../5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.

> [!WARNING]
>
> **Continuing to 5.9.x?** If 5.1.x is only an intermediate stop on your path to 5.9.x, land on the **latest available 5.1.x patch**, not 5.1.0. Data migrations and their fixes accumulate across the patches of the family, and the latest patch is the level guaranteed to carry all of them. Before starting the next migration, confirm the environment is fully functional: every service up and healthy in **FlowX.AI Designer → Platform Status**, and the data-sync job completed successfully. See the [5.1 → 5.9 migration prerequisites](/5.9/migrating-from-5.1-lts/prerequisites).

## Success factors

> [!WARNING]
>
> Take care when following the steps below are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB and DGraph** must be installed before any FlowX.AI services
>
> > [!NOTE]
> >
> > DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices (data migration)** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration (Elasticsearch indices)

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation

> [card] [Troubleshooting](./troubleshooting)
>
> Common issues and solutions for post-upgrade problems


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/prerequisites

This section contains the steps in order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.8 | FlowX.AI 5.1.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.1#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.1.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip this step.

> [card] [SpiceDB setup guide](../../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.1.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

> [!WARNING]
>
> Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.1.0 to ensure workspace functionality works correctly.

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Prerequisites for migration

Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:

```json theme={"dark"}
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
```

This mapping update is required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable, if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

### Post-migration impact

**Without proper Elasticsearch migration, you will experience:**

* Some process instances may not appear in search results
* Data-search functionality may not return complete results
* Workspace-scoped queries will fail for unmigrated data
* **Existing resources will not be visible or accessible within the new workspace structure**

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.1.0.

***

## Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).

Details on how to configure the organization admin user:

> [card] [Authorization system](../../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Workspaces access rights](../../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

***

#### Pre-migration preparation

You must configure the authorization-system service before migration. There are two supported approaches:

> [tab] Recommended: Use admin email (simpler)
>
> Set the following authorization-system environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=<username-of-admin-user>`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.

> [tab] Alternative: Use admin subject ID
>
> Set the following environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
>
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=<subject-id-of-admin-user>`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).
>
> > [!TIP]
> >
> > To get the subject ID of the admin user, extract it from the JWT token of the admin user.
>
> ![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.1.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users",
      "manage-realm"
    ]
  }
}
```

***

## Process instances migration

All active process instances will be migrated under default workspace.

> [!WARNING]
>
> For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.1.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.2") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.2 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.2 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.2 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.2 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.2 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# Post-upgrade troubleshooting
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/troubleshooting

Common issues and solutions that may occur after upgrading from FlowX v4.7.x to v5.1.0.

This section covers common issues that may occur after completing the upgrade to FlowX.AI 5.1.0 and their solutions.

## Designer login issues

### DataIntegrityViolationException error

If you cannot login to FlowX Designer after the 5.x upgrade and encounter the following error in the authorization-system logs:

```
org.springframework.dao.DataIntegrityViolationException: could not execute statement [ERROR: duplicate key value violates unique constraint "cas_user_username_key"
  Detail: Key (username)=(admin@flowx.ai) already exists.] [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; SQL [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; constraint [cas_user_username_key]
```

**Root Cause**: This error occurs because the `sub` (subject ID) is missing from JWT tokens. Starting with Keycloak version 25, the `sub` claim is not added by default to lightweight access tokens.

**Solution**: Ensure the `basic` Client Scope is created in your Keycloak Realm and added to all FlowX clients.

> [!WARNING]
>
> Since Keycloak version 25, the `sub` claim is not added by default to JWT lightweight tokens. This is a breaking change that affects FlowX.AI authentication.

### How to verify if subject ID is missing

**1. Login attempt**

Try to login to FlowX Designer and note if the login fails.

**2. Capture the token**

1. Open your browser's Developer Tools
2. Navigate to the **Network** tab
3. Attempt to login again
4. Look for a call to: `https://<your-keycloak-address>/auth/realms/flowx/protocol/openid-connect/token`
5. Copy the access token from the response

**3. Decode the token**

1. Go to [https://jwt.io/](https://jwt.io/)
2. Paste the token in the **Encoded** section
3. Check the **Payload** section for the presence of the `sub` claim

> [!TIP]
>
> If the `sub` claim is present, the token should contain a field like: `"sub": "12345678-1234-1234-1234-123456789abc"`

**4. Verify Client Scope configuration**

If the `sub` claim is missing, you need to configure the Client Scope in Keycloak:

1. Login to your Keycloak Admin Console
2. Navigate to your FlowX realm
3. Go to **Client Scopes**
4. Ensure the `basic` client scope exists and includes the `sub` claim
5. Add this client scope to all FlowX clients (FlowX Designer, Admin, etc.)

### Additional resources

> [card] [Keycloak Release Notes](https://www.keycloak.org/docs/latest/release_notes/#lightweight-access-token-to-be-even-more-lightweight)
>
> Official Keycloak documentation about lightweight access token changes

***

## Other common issues

> [!NOTE]
>
> Additional troubleshooting sections will be added as common post-upgrade issues are identified. If you encounter issues not covered here, please consult the FlowX support team.


# FlowX.AI 5.1.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025

Introducing Workspaces, Project Data Model, Library-to-Library Dependencies, Data Mappers, Reusable Resources, and more for a more efficient and flexible development experience.

**What's new? 🆕**

> [tab] Reusability
>
> Build once, use everywhere. These features transform how you develop and maintain applications by eliminating duplication and enabling sophisticated modular architectures.
>
> 🔄 [**Project Data Model (PDM)**](#project-data-model-pdm) - Define reusable data types at the project level to ensure consistency across processes\
> 🔄 [**Library-to-Library Dependencies**](#library-to-library-dependencies) - Create complex dependency trees with multiple levels of library-to-library relationships\
> 🔄 [**Data Mappers**](#data-mappers) - Visual drag-and-drop data mapping with reusable parameter definitions\
> 🔄 [**Reusable Resources**](#reusable-resources) - Create and manage UI Templates and Business Functions across multiple processes\
> 🔄 [**Files in Integration Designer**](#files-in-integration-designer) - Enhanced file management and reusability in integration workflows\
> 🔄 [**Resources Overrides**](#resources-overrides) - Localization and customization of core applications across multiple regions with centralized management\
> 🔄 [**Active Policy Overrides**](#active-policy-overrides) - User-specific and role-specific deployment policies for independent testing and controlled rollouts
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.1.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.1.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> ***
>
> ### **Files in Integration Designer**
>
> > [card] Files in Integration Designer
> >
> > > [tab] Files Overview
> > >
> > > ![Integration Designer file workflows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh.png)
> > >
> > > FlowX.AI 5.1.0 introduces comprehensive file handling capabilities in Integration Designer, resolving previous limitations where sending or receiving documents, photos, or any files via Integration Designer was not supported. This powerful enhancement enables seamless file exchange with external systems through automated workflows.
> >
> > > [tab] Core File Scenarios
> > >
> > > > [card] File Downloads
> > > >
> > > > Process calls external API (GET/POST) and receives files in response. Integration Designer saves files to specified location and returns paths to workflow
> > >
> > > > [card] File Uploads
> > > >
> > > > Process sends files stored in Document Plugin or S3 Bucket to external API via POST request. Workflow transmits file path for seamless transfer
> > >
> > > > [card] Document Plugin Integration
> > > >
> > > > Seamless integration with FlowX.AI Document Plugin for process-specific file management and organization
> > >
> > > > [card] S3 Storage Support
> > > >
> > > > Custom S3 bucket storage for files not tied to specific process instances or when Document Plugin is unavailable
> >
> > > [tab] Enhanced Capabilities
> > >
> > > **1. Automated File Exchange**
> > >
> > > Enable seamless file transfer with external systems without manual handling or complex custom integrations
> > >
> > > **2. Flexible Storage Options**
> > >
> > > Choose between Document Plugin for process-specific files or S3 Protocol for independent file operations
> > >
> > > **3. Workflow Integration**
> > >
> > > Files are automatically integrated into workflow processes with proper path management and metadata handling
> > >
> > > **4. External Service Communication**
> > >
> > > Communicate effectively with document services, AI processing systems, report generators, and CMS platforms
> >
> > > [tab] Real-World Use Cases
> > >
> > > > [accordion] Contract Generation Workflows
> > > >
> > > > **Scenario**: Generate personalized contracts using external document services
> > > >
> > > > * **Process Flow**: Send customer data → External contract service → Receive generated PDF contract
> > > > * **Integration**: Customer information flows to document generation API, completed contracts return to process
> > > > * **Storage**: Generated contracts stored in Document Plugin for process tracking and audit trails
> > > > * **Business Value**: Automated contract creation with legal template compliance and version control
> > >
> > > > [accordion] Document Processing & OCR
> > > >
> > > > **Scenario**: Process uploaded documents through external AI/OCR services
> > > >
> > > > * **Process Flow**: Upload document → AI processing service → Receive extracted data and processed files
> > > > * **Integration**: Documents sent to AI services for text extraction, classification, or compliance validation
> > > > * **Storage**: Processed documents and extracted data stored for business logic processing
> > > > * **Business Value**: Automated document processing with intelligent data extraction capabilities
> > >
> > > > [accordion] Report Generation & Analytics
> > > >
> > > > **Scenario**: Generate business reports using external reporting services
> > > >
> > > > * **Process Flow**: Send business data → Reporting service → Receive formatted reports (PDF, Excel)
> > > > * **Integration**: Business metrics and KPIs sent to specialized reporting engines
> > > > * **Storage**: Generated reports available for download and distribution workflows
> > > > * **Business Value**: Professional report generation with advanced formatting and visualization capabilities
> > >
> > > > [accordion] CMS & Content Management
> > > >
> > > > **Scenario**: Integrate with content management systems for file organization
> > > >
> > > > * **Process Flow**: Upload files → CMS integration → Organize and categorize content
> > > > * **Integration**: Files uploaded to external CMS platforms with metadata and categorization
> > > > * **Storage**: S3 Protocol ideal for CMS integrations with unassociated documents
> > > > * **Business Value**: Centralized content management with automated workflow integration
> >
> > [Learn more about Integration Designer](../../../../5.1/docs/platform-deep-dive/integrations/integration-designer)
> >
> > Major Enhancement
>
> ***
>
> ### **Resources Overrides**
>
> > [card] Resources Overrides
> >
> > > [tab] Resources Overrides Overview
> > >
> > > ![Resources Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
> > >
> > > Resources Overrides enable localization and customization of core business applications across multiple regions while maintaining centralized updates from headquarters. This powerful feature allows organizations to adapt specific business logic, compliance requirements, or local regulations without losing connection to the master application.
> >
> > > [tab] Key Features
> > >
> > > > [card] Localization Control
> > > >
> > > > Customize processes, workflows, and enumerations for different countries or regions while maintaining core functionality
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all resource overrides through the Dependencies page with comprehensive override tracking and configuration
> > >
> > > > [card] Selective Overriding
> > > >
> > > > Override only specific resources that need localization while inheriting all other updates from the main library
> > >
> > > > [card] Export/Import Support
> > > >
> > > > Automatically include override configurations in project exports and imports for seamless environment management
> >
> > > [tab] Business Benefits
> > >
> > > **1. Accelerate Global Expansion**
> > >
> > > Deploy core applications to new regions quickly by overriding only country-specific elements instead of rebuilding from scratch
> > >
> > > **2. Maintain Compliance**
> > >
> > > Adapt business logic and data handling to meet local regulatory requirements while preserving global standards
> > >
> > > **3. Preserve Investment**
> > >
> > > Continue receiving updates and improvements from headquarters without losing local customizations
> > >
> > > **4. Reduce Maintenance Overhead**
> > >
> > > Manage regional variations centrally instead of maintaining completely separate application instances
> >
> > > [tab] Supported Resource Types
> > >
> > > > [card] Process Overrides
> > > >
> > > > Customize business process logic while maintaining input/output compatibility and core workflow structure
> > >
> > > > [card] Workflow Overrides
> > > >
> > > > Replace entire workflow implementations to adapt business rules for local requirements
> > >
> > > > [card] Enumeration Overrides
> > > >
> > > > Localize value lists, dropdown options, and classification systems for regional variations
> > >
> > > > [card] Runtime Resolution
> > > >
> > > > Overrides are resolved dynamically at runtime, ensuring the correct regional version is always used
> >
> > > [tab] Real-World Applications
> > >
> > > > [accordion] Multi-National Banking
> > > >
> > > > **Scenario**: Global bank with country-specific loan approval processes
> > > >
> > > > * **Global Library**: Common loan application workflow with standard validation steps
> > > > * **Country Overrides**: Local credit scoring algorithms, regulatory compliance checks, documentation requirements
> > > > * **Business Value**: Single platform maintenance with automated compliance for each country's banking regulations
> > >
> > > > [accordion] Insurance Operations
> > > >
> > > > **Scenario**: Insurance company operating across different regulatory environments
> > > >
> > > > * **Global Library**: Standard claims processing workflow and policy management
> > > > * **Regional Overrides**: Country-specific coverage types, claim validation rules, regulatory reporting
> > > > * **Business Value**: Consistent global operations with local market adaptation and compliance
> > >
> > > > [accordion] Manufacturing & Supply Chain
> > > >
> > > > **Scenario**: Manufacturing company with different operational requirements per region
> > > >
> > > > * **Global Library**: Core production planning and inventory management processes
> > > > * **Local Overrides**: Regional supplier networks, compliance standards, environmental regulations
> > > > * **Business Value**: Standardized operations with flexibility for local business practices and regulations
> >
> > [Learn more about Resources Overrides](../../../../5.1/docs/projects/resources#resources-overrides)
> >
> > Major Enhancement
>
> ***
>
> ### **Active Policy Overrides**
>
> > [card] Active Policy Overrides
> >
> > > [tab] Active Policy Overrides Overview
> > >
> > > ![Active Policy Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap2.png)
> > >
> > > Active Policy Overrides enable user-specific and role-specific deployment policies that allow independent testing of different builds or branches without affecting the global policy. This powerful feature provides granular control over which project versions different users access in runtime environments.
> >
> > > [tab] Key Features
> > >
> > > > [card] User-Specific Policies
> > > >
> > > > Create individual policy overrides for specific users to test different builds independently
> > >
> > > > [card] Role-Based Overrides
> > > >
> > > > Apply policy overrides to entire roles for team-based testing and deployment strategies
> > >
> > > > [card] Priority-Based Resolution
> > > >
> > > > Handle conflicts when multiple overrides apply using configurable priority systems
> > >
> > > > [card] Real-Time Switching
> > > >
> > > > Switch between different project versions instantly without deployment downtime
> >
> > > [tab] Business Benefits
> > >
> > > **1. Independent Testing**
> > >
> > > Enable QA teams and developers to test different builds simultaneously without interfering with production users
> > >
> > > **2. Controlled Rollouts**
> > >
> > > Gradually deploy new features to specific user groups before full production release
> > >
> > > **3. Emergency Rollback**
> > >
> > > Quickly revert specific users to stable versions during incidents without affecting the entire system
> > >
> > > **4. Branch-Specific Development**
> > >
> > > Allow different teams to work with different development branches in shared environments
> >
> > > [tab] Override Management
> > >
> > > > [card] Policy Types
> > > >
> > > > Support for both "Latest on Branch" and specific "Build" policies with flexible branch and version selection
> > >
> > > > [card] Search & Filter
> > > >
> > > > Real-time search functionality to quickly locate specific user or role overrides
> > >
> > > > [card] Activation Control
> > > >
> > > > Enable or disable overrides without deletion for temporary testing scenarios
> > >
> > > > [card] Conflict Resolution
> > > >
> > > > Clear hierarchy: User overrides > Role overrides > Global policy with priority-based resolution
> >
> > > [tab] Real-World Scenarios
> > >
> > > > [accordion] Development Team Testing
> > > >
> > > > **Scenario**: Frontend team needs to test with latest UI changes while backend team tests API updates
> > > >
> > > > * **Override Setup**: Create role-based overrides for "Frontend Developers" and "Backend Developers"
> > > > * **Policy Configuration**: Frontend role uses latest on `ui-redesign` branch, Backend role uses `api-v2` branch
> > > > * **Business Value**: Parallel development with isolated testing environments and no cross-team interference
> > >
> > > > [accordion] Gradual Feature Rollout
> > > >
> > > > **Scenario**: New premium features need testing with select customers before full release
> > > >
> > > > * **Override Setup**: Create user-specific overrides for beta customers and internal stakeholders
> > > > * **Policy Configuration**: Beta users get latest build with premium features, others remain on stable version
> > > > * **Business Value**: Risk mitigation through controlled exposure and real-world testing feedback
> > >
> > > > [accordion] Emergency Response
> > > >
> > > > **Scenario**: Critical bug discovered in production affecting specific user workflows
> > > >
> > > > * **Override Setup**: Create high-priority role override for affected user groups
> > > > * **Policy Configuration**: Temporarily revert affected users to last stable build while others continue normally
> > > > * **Business Value**: Immediate incident response with minimal user impact and service continuity
> >
> > [Learn more about Active Policy Overrides](../../../../5.1/docs/projects/runtime/active-policy)
> >
> > Major Enhancement

> [tab] Persistence
>
> Advanced data management and storage capabilities that enable new architectural patterns and improved data governance.
>
> 🔄 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture) - Logical separation of business contexts with shared infrastructure\
> 🔄 [**FlowX.AI Database**](#flowx-ai-database) - New persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.1.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature

> [tab] Rendering Improvements & UI/UX Enhancements
>
> Enhanced user experience through improved components, better performance, and streamlined interface design.
>
> 🎨 [**Rendering Improvements & UI/UX Enhancements**](#rendering-improvements-&-ui/ux-enhancements) - Enhanced grid components, navigation redesign, advanced form controls, and analytics capabilities\
> 📋 [**Forms in Collections**](#forms-in-collections) - Enhanced support for form elements within collection components, enabling complex data entry scenarios\
> 🔄 [**Multi Select UI Component**](#multi-select-ui-component) - Allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
>
> ### **Rendering Improvements & UI/UX Enhancements**
>
> > [card] Rendering Improvements & UI/UX Enhancements
> >
> > FlowX.AI 5.1.0 delivers comprehensive UI/UX improvements that enhance the user experience across all platform components, from streamlined navigation to advanced form controls and better workflow handling.
> >
> > ## Interface & Navigation Improvements
> >
> > > [card] Enhanced Grid Component
> > >
> > > Improved performance, responsiveness, and customization options for data display and form organization
> >
> > > [card] Navigation Areas Redesign
> > >
> > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> >
> > > [card] Multi Actions Support
> > >
> > > Batch operations support for UI components, enabling simultaneous actions on multiple elements, multi select, multi copy/paste, multi drag and drop, multi delete
> >
> > > [card] [Permission-Based UI Editing](../../../../5.1/docs/building-blocks/ui-designer/ui-designer#permission-based-expressions)
> > >
> > > Granular control over UI element editing based on user permissions with partial editing capabilities, allow multiple executors on swimlane level
> >
> > ## Enhanced Form Controls & Components
> >
> > > [card] [Input Type Code](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-types)
> > >
> > > Specialized input component for code entry
> >
> > > [card] Formatting Options
> > >
> > > Advanced formatting capabilities for Input and Slider components
> >
> > > [card] [Switch Variants](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field#switch-type)
> > >
> > > Enhanced switch component supporting both toggle and checkbox variants
> >
> > > [card] [Disabled Options on Selectors](/5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select#disabled-options)
> > >
> > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > ## User Experience Enhancements
> >
> > > [card] Custom Loader
> > >
> > > Configurable loading indicators for improved user experience during data operations
> >
> > > [card] [Custom Expression Validators](../../../../5.1/docs/building-blocks/ui-designer/validators#custom-validators)
> > >
> > > Advanced validation logic using dynamic computed expressions that can reference other process data values. Write JavaScript expressions that return boolean values for cross-field validation scenarios
> >
> > > [card] File Upload Button Type
> > >
> > > Introduces a specialized button variant for file upload operations, supporting **fill**, **ghost**, and **text** types for flexible UI styling.
> >
> > > [card] Copy Styles
> > >
> > > Efficiently replicate styling across multiple UI components
> >
> > ## Workflow & Analytics Improvements
> >
> > > [card] Analytics Enhancements
> > >
> > > Custom payload support for detailed user interaction tracking and business intelligence
> >
> > > [card] Process End Handling
> > >
> > > Improved user experience when processes complete or terminate
> >
> > > [card] Template Management
> > >
> > > Streamlined template organization by consolidating functionality in Reusable Resources
>
> ***
>
> ### **Forms in Collections**
>
> > [card] Forms in Collections
> >
> > A powerful new feature that enables dynamic, repeatable forms within collection prototypes, eliminating the need for custom development when building forms with repeatable sections like co-debtors, comments, or any list of similar items.
> >
> > <video />
> >
> > ## Key Capabilities
> >
> > > [card] No Custom Development
> > >
> > > Drag Form components directly into Collection Prototypes - they automatically repeat for each item in your data array
> >
> > > [card] Flexible Validation
> > >
> > > Choose between individual item validation or bulk validation across all collection items
> >
> > > [card] Two Saving Scenarios
> > >
> > > Individual save (one item at a time) or bulk save (entire collection) with different validation behaviors
> >
> > ## Common Use Cases Solved
> >
> > **1. Dynamic Forms**
> >
> > Build forms that show different elements based on conditions without custom development
> >
> > **2. Repeatable Sections**
> >
> > Create forms with sections like adding multiple co-debtors, comments, or family members
> >
> > **3. Complex Data Entry**
> >
> > Handle arrays of objects with proper validation and data management
> >
> > **4. Real-time vs Batch Processing**
> >
> > Choose individual saves for real-time editing or bulk saves for form completion workflows
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component

> [tab] AI Platform
>
> New AI capabilities in Integration Designer for processing text, documents, images, and data using AI-powered nodes.
>
> 🤖 [**AI Nodes in Integration Designer**](#ai-nodes-in-integration-designer) - Process text, documents, images, and data using AI-powered workflow nodes
>
> ### **AI Nodes in Integration Designer**
>
> > [card] AI Nodes in Integration Designer
> >
> > > [tab] AI Nodes Overview
> > >
> > > ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
> > >
> > > FlowX.AI 5.1.0 introduces AI-powered nodes in Integration Designer, enabling intelligent processing of text, documents, images, and data within your workflows. These nodes bring AI capabilities directly into your integration flows without requiring external AI services.
> >
> > > [tab] AI Text Operations
> > >
> > > > [card] Text Transformation
> > > >
> > > > Modify text tone, complexity or formatting for better clarity or style
> > >
> > > > [card] Text Understanding
> > > >
> > > > Analyze text to determine sentiment, topics, intent, language and named entities
> > >
> > > > [card] Text Generation
> > > >
> > > > Generate new text such as summaries, completions, translations or paraphrases
> > >
> > > > [card] Text Extraction
> > > >
> > > > Extract structured information, keywords or metadata from text
> >
> > > [tab] AI Document Operations
> > >
> > > > [card] Document Generation
> > > >
> > > > Automatically build reports or complete templates based on given inputs
> > >
> > > > [card] Document Extraction
> > > >
> > > > Identify and extract structured data, entities or metadata from documents
> > >
> > > > [card] Document Understanding
> > > >
> > > > Analyze documents to extract meaning, topics, sentiment, or important information
> > >
> > > > [card] Extract Text from Document
> > > >
> > > > Extract text content from documents (OCR, PDF text extraction)
> >
> > > [tab] AI Image & Data Operations
> > >
> > > **Image Operations:**
> > >
> > > > [card] Image Description
> > > >
> > > > Generate captions or extract detailed information from visual content
> > >
> > > > [card] Image Analysis
> > > >
> > > > Recognize objects, emotions and scenes in images for contextual understanding
> > >
> > > **Data Operations:**
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Add annotations, context or relationships to enhance raw data value
> > >
> > > > [card] Data Generation
> > > >
> > > > Produce synthetic or structured data using templates and logic-based rules
> > >
> > > > [card] Data Transformation
> > > >
> > > > Clean, normalize, aggregate, or restructure datasets into usable formats
> >
> > > [tab] Use Cases
> > >
> > > > [accordion] Intelligent Document Processing
> > > >
> > > > * Extract data from invoices, contracts, and forms
> > > > * Classify documents automatically
> > > > * Validate extracted information against business rules
> > >
> > > > [accordion] Customer Communication Analysis
> > > >
> > > > * Analyze customer feedback sentiment
> > > > * Extract key topics from support tickets
> > > > * Generate personalized responses
> > >
> > > > [accordion] Content Generation
> > > >
> > > > * Create summaries of long documents
> > > > * Translate content to multiple languages
> > > > * Generate reports from structured data
> > >
> > > > [accordion] Data Processing
> > > >
> > > > * Enrich customer data with AI-derived insights
> > > > * Transform unstructured data to structured formats
> > > > * Generate test data for development
> >
> > [Learn more about AI Node Types](../../../../5.1/docs/platform-deep-dive/integrations/ai-nodes)
> >
> > New Feature

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.1](./deployment-guidelines-v5.1)
> >
> > Instructions for deploying FlowX.AI 5.1.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.1/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.1.0


# FlowX.AI 5.1.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.1-november-2025

WCAG 2.1 Level AA compliance achieved, AI Platform enhancements, bug fixes, and quality improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **accessibility compliance**, **AI Platform enhancements**, **customer issue resolution**, and **proactive quality improvements**.
> Upgrades from **5.1.0 → 5.1.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Quality Achievement**: FlowX.AI 5.1.1 demonstrates our commitment to proactive quality improvement:
>
> * **[WCAG 2.1 Level AA compliance](https://www.w3.org/TR/WCAG21/)** achieved across all web components
> * **Proactive quality improvements** identified through internal QA before reaching customers
> * **Customer issues** resolved with full business context
> * **Zero breaking changes** - fully compatible upgrade from 5.1.0
>
> This release represents months of accessibility audits, automated testing, and quality assurance work to deliver exceptional software quality.

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.1 delivers comprehensive improvements across accessibility, stability, and platform reliability.
>
> ♿  [**WCAG 2.1 Compliance Achieved**](#wcag-2-1-compliance) - Full accessibility support across all web components\
> 🌍 [**Task Management Localization**](#task-management-localization) — Comprehensive multi-language support with 51 substitution tags\
> 🤖 [**AI Platform Enhancements**](#ai-platform-enhancements) — Multi-agent system improvements and AI workflow stability\
> 🎯 [**Customer Fixes**](#customer-fixes) — Critical issues resolved based on customer feedback\
> ✨ [**Proactive Improvements**](#proactive-quality-improvements) — Issues identified through internal QA before reaching customers\
> 🔧 [**Platform Enhancements**](#platform-enhancements) — SSE handling, audit logs, and infrastructure improvements
>
> ### **WCAG 2.1 compliance**
>
> > [card] WCAG 2.1 compliance
> >
> > > [tab] Overview
> > >
> > > **FlowX.AI is now WCAG 2.1 Level AA compliant**
> > >
> > > This release delivers full accessibility support through **28 comprehensive improvements** across Angular and React SDKs, making FlowX applications usable by everyone, including users with disabilities.
> > >
> > > ### Business value
> > >
> > > > [card] Government Compliance
> > > >
> > > > Meet accessibility requirements for government and public sector applications
> > >
> > > > [card] Healthcare Standards
> > > >
> > > > Comply with healthcare industry accessibility regulations and standards
> > >
> > > > [card] Financial Services
> > > >
> > > > Satisfy financial sector requirements for inclusive digital experiences
> > >
> > > > [card] Universal UX
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those with disabilities
> > >
> > > ### What changed
> > >
> > > * All components now fully keyboard-accessible
> > > * Complete screen reader support with ARIA labels
> > > * Proper focus management across all interactions
> > > * Accessible error announcements and validation
> > > * Semantic HTML structure throughout
> >
> > > [tab] Key features
> > >
> > > > [card] Auto-bindable ARIA Tags
> > > >
> > > > Automatically bind accessibility labels, descriptions, and ARIA attributes to all UI components from Designer configuration
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Full keyboard navigation support with proper focus management, tab order, and keyboard shortcuts in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > ARIA labels, descriptions, and live regions implemented across all form elements and interactive components
> > >
> > > > [card] UI Designer Integration
> > > >
> > > > Dedicated accessibility configuration section in UI Designer for managing labels and descriptions
> >
> > > [tab] Supported components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio/Segmented buttons, Slider, and File upload with labels, descriptions, and error announcements
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card with keyboard navigation, focus management, and state announcements
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with semantic HTML structure and proper labeling
> > >
> > > **4. Platform Support**
> > >
> > > Complete implementation for Angular and React SDKs (iOS and Android in future releases)
> >
> > > [tab] Implementation details
> > >
> > > **28 Improvements Delivered:**
> > >
> > > > [accordion] Angular SDK
> > > >
> > > > * Custom keyboard navigation implementation
> > > > * Focus management for Select/Multiselect components
> > > > * Modal focus trap and restoration
> > > > * Shift+Tab handling across form elements
> > > > * Listbox keyboard operations
> > > > * Table navigation improvements
> > > > * Switch and checkbox accessibility
> > > > * File preview focus indicators
> > > > * Button Space key activation
> > > > * Link focus outlines
> > > > * Disabled element keyboard behavior
> > >
> > > > [accordion] React SDK
> > > >
> > > > * BaseUI Combobox implementation for Select/Multiselect
> > > > * Keyboard navigation with clear buttons
> > > > * Focus restoration after interactions
> > > > * Outline theming for focus indicators
> > > > * Modal auto-focus on open
> > > > * Card accordion keyboard handling
> > > > * Table row navigation
> > > > * Option highlighting in dropdowns
> > >
> > > > [accordion] UI Designer
> > > >
> > > > * Accessibility configuration panel
> > > > * Auto-bindable tags for all components
> > > > * Label and description fields
> > > > * Alt text management for images
> > > > * ARIA attribute configuration
> > > > * Accessibility section styling
> > > > * Component-specific accessibility settings
> > >
> > > > [accordion] Technical tasks completed
> > > >
> > > > * Implemented BaseUI Combobox for Select/Multiselect
> > > > * Custom keyboard navigation for Angular
> > > > * React SDK keyboard navigation with clear button
> > > > * Auto-bindable accessibility tags for all components
> > > > * Accessibility configuration panel in UI Designer
> > > > * Removed conflicting title attribute tooltips
> > > > * Aligned Stepper accessibility between frameworks
> > > > * Bind labels and descriptions to form fields
> >
> > [Learn more about Accessibility Configuration](/5.1/docs/platform-deep-dive/accessibility)
> >
> > Major Achievement
>
> ***
>
> ### **Customer fixes**
>
> > [card] Customer fixes
> >
> > We prioritized and resolved **customer-reported issues** in this release, addressing critical functionality issues and workflow inefficiencies reported via Zendesk.
> >
> > > [accordion] Action parameters lost on copy/paste
> > >
> > > **Problem:**\
> > > When copying nodes with Kafka send actions, topic and message configurations were not preserved, forcing users to manually reconfigure all action parameters after paste operations.
> > >
> > > **Customer Impact:**
> > >
> > > * Development velocity significantly reduced
> > > * Risk of configuration errors during manual re-entry
> > > * Frustration with repetitive configuration work
> > >
> > > **Resolution:**\
> > > actionParamsMap now properly persists through copy/paste operations
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create send message node with Kafka action
> > > 2. Configure topic and message parameters
> > > 3. Copy and paste the node
> > > 4. All configurations now preserved correctly
> > >
> > > **Customer Benefit:**\
> > > Faster workflow development with reduced configuration errors and improved developer experience.
> >
> > > [accordion] Orphaned warnings block process deployments
> > >
> > > **Problem:**\
> > > When deleting parent actions that had child actions with warnings, the warnings remained in the system as orphans. These orphaned warnings prevented process export/import operations and blocked build deployments.
> > >
> > > **Customer Impact:**
> > >
> > > * Build pipelines blocked by stale warnings
> > > * Deployment delays requiring manual database cleanup
> > > * Process export/import operations failed
> > > * Development and testing workflows disrupted
> > >
> > > **Resolution:**\
> > > Warnings now cascade-delete automatically when parent actions are removed
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create action with subactions containing warnings
> > > 2. Delete the parent action
> > > 3. All child warnings now properly cleaned up
> > >
> > > **Customer Benefit:**\
> > > Clean deployments without manual intervention, faster development cycles, no more blocked pipelines.
> >
> > > [accordion] Default application cannot be removed
> > >
> > > **Problem:**\
> > > Auto-generated `default_application` in new environments existed only in app\_manager schema and could not be deleted through standard operations, returning validation errors.
> > >
> > > **Customer Impact:**
> > >
> > > * Environment cleanup difficulties
> > > * Testing complications with unwanted default projects
> > > * Confusion about application lifecycle management
> > >
> > > **Resolution:**\
> > > Added proper runtime validation for application deletion operations
> > >
> > > **Error (Fixed):**
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": 400,
> > >   "message": "error.validation.runtime.application.not_found",
> > >   "title": "Runtime project not found."
> > > }
> > > ```
> > >
> > > **Customer Benefit:**\
> > > Clean environment management with predictable application lifecycle operations.
>
> ***
>
> ### **Proactive quality improvements**
>
> > [card] Proactive quality improvements
> >
> > > [tab] Overview
> > >
> > > **Issues identified and resolved proactively**:
> > >
> > > ### Quality process
> > >
> > > > [card] Accessibility Audits
> > > >
> > > > WCAG 2.1 compliance testing identified keyboard navigation and focus management improvements
> > >
> > > > [card] Automated Testing
> > > >
> > > > Continuous integration pipelines caught component behavior issues and rendering problems
> > >
> > > > [card] Internal QA
> > > >
> > > > Manual testing uncovered edge cases in form interactions and modal behaviors
> > >
> > > > [card] Code Reviews
> > > >
> > > > Peer reviews identified potential stability issues in backend processing and dependency management
> > >
> > > ### Distribution by category
> > >
> > > * **Keyboard Navigation**: Fixes across Angular and React
> > > * **Focus Management**: Fixes for modals, forms, and interactive elements
> > > * **Component Behavior**: Fixes for proper state handling and rendering
> > > * **Backend Stability**: Fixes for processing and dependency management
> >
> > > [tab] Angular SDK
> > >
> > > > [accordion] Keyboard navigation improvements
> > > >
> > > > * Fixed listbox remaining open when pressing Shift+Tab
> > > > * Fixed Shift+Tab not working on Select with search
> > > > * Fixed Multiselect tab navigation moving to first element instead of next
> > > > * Fixed Select input focus not working properly
> > > > * Fixed Select list not scrolling during keyboard navigation
> > > > * Fixed up/down arrow scrolling screen alongside option list
> > > > * Fixed focus lost after loading new user task
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed Link in message focus missing outline
> > > > * Fixed modal close button not focused automatically
> > > > * Fixed file preview focus not highlighted and lost
> > > > * Fixed button inside modal not working with Space key
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Multiselect options list not opening
> > > > * Fixed MultiSelect and link focusable when disabled
> > > > * Fixed modal dismiss buttons not working with Space key
> > > > * Fixed modal without close button not easily focusable
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Space pressed on card with accordion scrolling page
> > > > * Fixed Switch with label position start focus issues
> >
> > > [tab] React SDK
> > >
> > > > [accordion] Keyboard Navigation Improvements
> > > >
> > > > * Fixed outline from theme not applied to modal close button and links
> > > > * Fixed Select selected option not highlighted in options list
> > > > * Fixed Select search not filtering after selection
> > > > * Fixed Input/textarea/select focus lost after using clear button
> > > > * Fixed Tab focus moving inside collapsed card
> > > > * Fixed table Tab navigation skipping rows
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed file preview retry focus not highlighted and lost
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Select and link focusable when disabled
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Datepicker clear icon focus not highlighted
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed doc preview modal not closable with Enter or Space
> > > > * Fixed button inside table focus not highlighted
> > > > * Fixed Slider decimal numbers not rendered correctly
> > > > * Fixed Substepper not rendered correctly
> > > > * Fixed doc preview display mode showing inline
> > > > * Fixed cards expandable before token reaches them
> >
> > > [tab] Designer & Backend
> > >
> > > > [accordion] UI Designer Improvements
> > > >
> > > > * Fixed missing accessibility section on Link component
> > > > * Fixed missing accessibility section on Image button
> > > > * Fixed missing space in accessibility label and info icon
> > > > * Fixed Alt text field disabled styling not applied
> > > > * Fixed console errors when changing pages from header
> > > > * Fixed Select/multiselect highlighted in preview and settings tabs
> > > > * Fixed outline theming in enumerations and inputs
> > > > * Fixed Workflows info points content not rendered correctly
> > > > * Fixed Workflows tabs content not showing properly
> > > > * Fixed padding missing on RUT UI Assets panel
> > >
> > > > [accordion] Backend Stability Improvements
> > > >
> > > > * Fixed wrong navigationTree response on overridden process
> > > > * Fixed incorrect navigationTree for resource override details
> > > > * Fixed error when trying to update dependency lib versions
> > > > * Fixed error returned when updating dependency with override
> > > > * Fixed no response on out topic for start process by name from Kafka
> > > > * Fixed checkbox "Allow back to this action" status not loaded
> > > > * Fixed empty screen when logging in without workspace access
> > > > * Fixed Elasticsearch scheduled task errors with failed documents
> > > > * Fixed services not logging when Liquibase crashing due to lock
> >
> > Proactive Quality
>
> ***
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 adds comprehensive localization support for Task Management, enabling multi-language task management interfaces through 51 system substitution tags. Table grid localization is automatic.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > >
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> > >
> > > > [!NOTE]
> > > >
> > > > This feature enables complete Task Management localization for global deployments, meeting requirements for government, healthcare, and financial services applications requiring multi-language support.
> >
> > > [tab] Key features
> > >
> > > > [card] FlowX Substitution Tags (51 Keys)
> > > >
> > > > Complete set of substitution tags for task actions, statuses, history events, and UI elements
> > >
> > > > [card] Table Grid Localization
> > > >
> > > > Table grid localizes automatically based on container app language; FlowX tags configured manually in CMS
> > >
> > > > [card] Web Renderer Integration
> > > >
> > > > Angular and React renderers use system substitution tags on all task management texts
> >
> > > [tab] What's localized
> > >
> > > **FlowX Substitution Tags (51 Keys):**
> > >
> > > * Table columns (title, stage, assignee, status, priority, last updated)
> > > * Process states (created, started, finished, failed, expired, etc.)
> > > * Task actions (assign, unassign, hold, unhold, execute, start)
> > > * Bulk operations (assign to, unassign all, hold all, etc.)
> > > * History events (task created, assigned, status changed, etc.)
> > > * User selection dialogs and UI states
> > >
> > > **Table Grid Localization**:
> > >
> > > * Filters (set, text, number, date with all operators)
> > > * Menus (column, context, aggregation, sorting)
> > > * Pagination (navigation, page size, row counts)
> > > * Data types (boolean, dates, numbers with formatting)
> > > * ARIA labels for accessibility
> >
> > > [tab] Implementation details
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization based on this setting
> > >
> > > **2. Configure CMS Tags**
> > >
> > > Add translations for all 51 sys\_tm\_\* tags in CMS for each supported language - this is the only manual configuration needed
> > >
> > > **3. Use in Renderers**
> > >
> > > Web renderers automatically apply system substitution tags to all task management UI elements
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> ***
>
> ### **AI Platform enhancements**
>
> > [card] AI Platform enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 delivers significant improvements to the AI Platform, enhancing multi-agent collaboration, conversation management, and AI workflow stability. These enhancements ensure more reliable AI-assisted development workflows and better user experience.
> > >
> > > > [card] Multi-Agent System
> > > >
> > > > Enhanced agent communication and thread management for improved collaborative AI workflows
> > >
> > > > [card] Conversation Stability
> > > >
> > > > Improved conversation handling with better error propagation and session management
> > >
> > > > [card] AI Developer Tools
> > > >
> > > > Enhanced AI Developer capabilities with proper data model integration and expression generation
> > >
> > > > [card] Document Intelligence
> > > >
> > > > Multi-page document generation support and improved content handling
> >
> > > [tab] Key improvements
> > >
> > > **Multi-Agent Conversation Management:**
> > >
> > > * Enhanced conversation thread handling with proper parent action status updates
> > > * Improved backend support for adding new messages on agent threads
> > > * Better session management with new session button in Command Center
> > > * Context switching prevention during execution plan generation
> > >
> > > **AI Developer Enhancements:**
> > >
> > > * Fixed data model integration for expressions and business rules generation
> > > * Improved action target saving and destination setting
> > > * Enhanced execution plan editing from user prompts
> > > * Better handling of empty execution plans
> > >
> > > **Error Handling & Stability:**
> > >
> > > * Graceful error propagation from internal AI agent operations
> > > * Improved CORS headers for document object downloads
> > > * Enhanced telemetry support for debugging and monitoring
> > > * Better handling of plan enhancement patches
> > >
> > > **Document & Content Features:**
> > >
> > > * Multi-page document generation support in AI nodes
> > > * Source selector component for image and document inputs
> > > * Improved messaging system for AI agents in command center
> > > * Enhanced UI feedback for AI-generated resources
> >
> > > [tab] Technical improvements
> > >
> > > **Backend Enhancements:**
> > >
> > > * Continuous patching support for action contexts during execution
> > > * Improved navigation tree responses for overridden processes
> > > * Enhanced dependency management for library overrides
> > > * Better error handling and logging across AI services
> > >
> > > **Frontend Improvements:**
> > >
> > > * Fixed target selector closing behavior in implementation threads
> > > * Improved preview mode handling after developer changes
> > > * Enhanced command center messaging and error display
> > > * Better UI state management for AI workflow interactions
> > >
> > > **Integration Updates:**
> > >
> > > * CORS headers properly configured for GraphQL object downloads
> > > * Process task destinations automatically set to current process
> > > * Improved integration between AI agents and execution plans
> > > * Enhanced audit logging for resource overrides
> >
> > AI Platform
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform enhancements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] SSE Disconnect Handling
> > > >
> > > > Improved Server-Sent Events disconnect handling to reduce error log flooding when clients disconnect
> > >
> > > > [card] Resource Overrides Audit
> > > >
> > > > Implemented audit logs for library resource overrides to track configuration changes
> > >
> > > > [card] Security Updates
> > > >
> > > > Fixed high vulnerabilities in Designer 5.1.x and main branch
> >
> > > [tab] Renderer Enhancements
> > >
> > > > [card] System Substitution Tags
> > > >
> > > > Web renderers now use system substitution tags on all task management texts
> > >
> > > > [card] Outline Theming
> > > >
> > > > Enhanced outline and select/multiselect option highlight theming for visual consistency
> >
> > > [tab] Technical Improvements
> > >
> > > **Code Quality:**
> > >
> > > * Eliminated deprecated code for Kafka start process
> > > * Improved error handling for Elasticsearch document updates
> > > * Enhanced dependency management for library overrides
> > > * Better logging and error reporting across services
> > >
> > > **Performance:**
> > >
> > > * Optimized SSE connection handling
> > > * Improved query performance for navigation tree
> > > * Better resource management in long-running processes
> >
> > Platform Updates

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.1 is fully compatible with 5.1.0. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.0 → 5.1.1 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Android and iOS accessibility properties implementation
> > * Additional Select component refinements
> > * UI Designer padding optimizations
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and critical bug fixes
> * Accessibility enhancements for mobile platforms
> * Performance optimizations
>
> Major new features are planned for future releases in the 5.x series. See the [5.2.0 release notes](../v5.2.0-november-2025/v5.2.0-november-2025) for upcoming capabilities.


# FlowX.AI 5.1.10 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.10-june-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.9 → 5.1.10** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.10 includes bug fixes and security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Active policy and iOS renderer fixes
> * Real-time event delivery stability improvement (Events Gateway)
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.9

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Reusable UI templates:** fixed several issues affecting reusable UI templates: actions remaining mapped after changing dependency versions, undo/redo leaving an action without a name or unable to save, data-slice and mapping requests returning 400 after a data-model key was renamed, duplicate entries returned for available templates, the "open in new tab" flag not being saved on UI action mappings, actions going missing when the same template is nested at multiple container levels, and conditional styling and validators being applied incorrectly when the same template is used more than once in a single user task.
> > > >
> > > > * **Active policy:** fixed an issue where the user list could appear empty on the override active-policy form.
> > > >
> > > > * **Project version merge:** fixed a 500 error that could occur when merging app versions.&#x20;
> > > >
> > > > * **Organization settings:** fixed the runtime users list failing to load.&#x20;
> > > >
> > > > - **Real-time event delivery:** improved Redis connection stability under sustained load. The Events Gateway now uses polling as the default mode for reading real-time events from Redis, preventing the gradual connection buildup that could previously require periodic Events Gateway restarts. The change applies automatically on upgrade; no configuration is required.
> > > > - **Renderer:** accordion card height and custom styles now follow the component's opened state, and gap spacing is applied correctly to collections.
> > > > - **Process instances:** fixed duplicate API calls and rendering errors when navigating between process instances.
> > > > - **iOS renderer:** broad VoiceOver and accessibility improvements across components (form fields, file preview, sliders, date picker, validation messages), and fixed form view-model lookup for forms nested in collections.
> > > > - **Android renderer:** component sizing now includes padding on text, link, markdown, and image components; fixed a TopAppBar crash in some configurations, tooltip icon overrides, slider step rounding, document preview caching, and resilience to process death.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.10 is fully compatible with 5.1.9. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.9 → 5.1.10 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.10](./deployment-guidelines-v5.1.10).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.11 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.11-july-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.10 → 5.1.11** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.11 includes bug fixes and security patches:
>
> * Audit log and task management fixes
> * Project creation error-handling fix
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.10

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Audit log:** filtering by user now returns results when a user's username differs from their email address.
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it.
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.11 is fully compatible with 5.1.10. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.10 → 5.1.11 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.11](./deployment-guidelines-v5.1.11).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.12 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.12-august-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.11 → 5.1.12** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.12 includes bug fixes for library resources and task management:
>
> * Library process resource overview fixes
> * Task management sort control fix
> * No breaking changes; fully compatible upgrade from 5.1.11

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes for library resource overview and task management
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.12 is fully compatible with 5.1.11. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.11 → 5.1.12 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.12](./deployment-guidelines-v5.1.12).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.13 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.13-september-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **security patches**. Upgrades from **5.1.12 → 5.1.13** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.13 includes reliability fixes for process advancing, a process designer fix, and security patches:
>
> * Process advancing fixes that prevent lost or stalled process advances under load
> * Action deletion fix for business rules that call reusable functions
> * Security patches and dependency upgrades across platform components
> * No breaking changes; fully compatible upgrade from 5.1.12

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and security patches across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Process advancing reliability fixes, a process designer fix, and security patches
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Process advancing:** the partition cleanup job no longer deletes advance events that are accepted while cleanup is running. Event insertion and cleanup now coordinate through database row locks, on both PostgreSQL and Oracle, so a process advance can no longer be lost to a concurrent cleanup.&#x20;
> > > > * **Process advancing:** advancing workers no longer pause for cooldown while work is still queued, and event completion is retried after a database deadlock instead of leaving an already-processed event marked as in progress.&#x20;
> > > > * **Process designer:** deleting an action no longer fails with a server error when one of its business rules calls a reusable function.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components. The Java runtime base images move to Eclipse Temurin 21.0.12 with a refreshed OS package layer.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.13 is fully compatible with 5.1.12. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.12 → 5.1.13 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.13](./deployment-guidelines-v5.1.13).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.14 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.14-october-2026

Final maintenance release for the FlowX.AI 5.1.x LTS line. Audit index retention settings, an Android SDK loader fix, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.1.x** line, focused on **bug fixes** and **security patches**. Upgrades from **5.1.13 → 5.1.14** are non-breaking and fully compatible. FlowX.AI 5.1.14 is the final planned maintenance release of the 5.1.x line. To keep receiving fixes, plan your move to the 5.9.x LTS line: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [card] Release Highlight
>
> **FlowX.AI 5.1.14** is a maintenance release for the 5.1.x LTS:
>
> * **Audit index retention:** optional settings to delete old audit data and roll audit indices over by shard size
> * **Key fixes:** the Android SDK loader shows on modal screens and no longer stays stuck after repeated taps
> * Security patches and dependency upgrades. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.1.14 is fully compatible with 5.1.13. No breaking changes, no database migrations, and no required configuration changes; standard deployment procedures apply.

**Upgrade path:** direct upgrade from 5.1.13.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x. Component versions are listed in the [5.1.14 deployment guidelines](./deployment-guidelines-v5.1.14).

***

## Full changelog

### New

* **Audit:** set how long audit data is kept, and roll audit indices over when a primary shard reaches a set size, with two new environment variables. Both are off by default, so the Audit service deletes nothing until you set a retention period. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch) and the [deployment guidelines](./deployment-guidelines-v5.1.14#new-environment-variables-audit-index-retention).&#x20;

### Fixed

* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.1.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.2-december-2025

Bug fixes, stability improvements, and quality enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes**, **stability improvements**, and **quality enhancements**.
> Upgrades from **5.1.1 → 5.1.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.2 provides continued quality, stability, and reliability for the platform:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * New features and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.2 delivers maintenance improvements focused on stability, reliability, and feature enhancements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — issues resolved including customer-reported and proactive fixes\
> ✨ [**New Features**](#new-features) — enhancements including new features and platform improvements\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure and stability enhancements
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Authorization service configuration
> > > >
> > > > **Problem:**\
> > > > Wrong service account client secret config parameter was used in Authorization service, causing authentication failures.
> > > >
> > > > **Resolution:**\
> > > > Fixed configu gration parameter mapping for service account client secret in Authorization service
> > >
> > > > [accordion] Token state changes on back navigation
> > > >
> > > > **Problem:**\
> > > > When performing back in steps actions, tokens incorrectly changed from Aborted to Active state when lazy actions finished.
> > > >
> > > > **Resolution:**\
> > > > Fixed token state management during back navigation to preserve correct state
> > >
> > > > [accordion] Action parameters not copied on node copy
> > > >
> > > > **Problem:**\
> > > > When copying nodes with child actions, action parameters (like Kafka topic and message configurations) were not preserved.
> > > >
> > > > **Resolution:**\
> > > > Fixed actionParamsMap persistence through copy/paste operations
> > >
> > > > [accordion] Permissions updated incorrectly during action execution
> > > >
> > > > **Problem:**\
> > > > hideRules and disableRules values were incorrectly updated in database when executing actions, causing permission issues.
> > > >
> > > > **Resolution:**\
> > > > Fixed permission rule handling during action execution
> > >
> > > > [accordion] Subprocess data mapping issues
> > > >
> > > > **Problem:**\
> > > > Starting subprocess with legacy mapping caused data to be incorrectly appended instead of replaced.
> > > >
> > > > **Resolution:**\
> > > > Fixed data mapping behavior for subprocess start actions
> > >
> > > > [accordion] Forms in collections - action not found
> > > >
> > > > **Problem:**\
> > > > When saving data from outside collection with forms to submit, actions were not found correctly.
> > > >
> > > > **Resolution:**\
> > > > Fixed action resolution for forms inside collections
> >
> > > [tab] AI Platform fixes
> > >
> > > > [accordion] AI Designer improvements
> > > >
> > > > * Fixed no feedback when uploading large documents in command center
> > > > * Fixed targets for business rules never being set by planner
> > > > * Fixed file upload limit lower than 3MB
> > > > * Fixed missing messages on Keep/Discard buttons for UI and BR
> > > > * Fixed Save & Close button not working in Data Model modal
> > > > * Fixed DM keys not created after keeping UI
> > > > * Fixed table key appearing as mapped when Data Model is empty
> > > > * Fixed pip window being clipped
> > > > * Fixed Submit prompt button color not indicating active state
> > > > * Fixed source not indicating uploaded document for some Plan actions
> > > > * Fixed UI outcome duplication until connected-graph keep method finishes
> > > > * Fixed missing scrollbar in Context Documents modal with multiple subprocesses
> > > > * Fixed command center not reopenable after closing in developer preview mode
> > > > * Fixed planner sample data import crashes
> > > > * Fixed business logic targets not correctly stored in execution plan
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Web renderer improvements
> > > >
> > > > * Fixed hide subprocess navigation closing parent navigation with multiple hierarchies
> > > > * Fixed card collapsing when next nav area is modal (Angular & React)
> > > > * Fixed card not expandable after finishing subprocess started from it (Angular & React)
> > > > * Fixed loader missing or not fully shown in React
> > > > * Fixed message icon and text rendered on different rows when width fill in React
> > > > * Fixed collection prototype shown when collection source array doesn't exist in React
> > > > * Fixed broken image rendered when missing url or base64 image in React
> > > > * Fixed switch component knob and container alignment in React
> > > > * Fixed multi select search not filtering available options in React SDK
> > > > * Fixed custom component keys duplicated in action body (React & Angular)
> > >
> > > > [accordion] Task Manager fixes
> > > >
> > > > * Fixed Task Manager theming not applied in Angular
> > > > * Fixed Task Manager header theming not applied in React
> > > > * Fixed assignee dropdown list and placeholder not displayed in React
> > >
> > > > [accordion] Reusable templates fixes
> > > >
> > > > * Fixed custom body being null at runtime for Reusable templates actions
> >
> > > [tab] Platform & Data fixes
> > >
> > > > [accordion] Data model and mappers
> > > >
> > > > * Fixed input/output parameters not deleted after updating parameters
> > > > * Fixed Go to reference button redirecting incorrectly
> > > > * Fixed parameters items deleted when updating Project Data Model object
> > >
> > > > [accordion] Process Designer
> > > >
> > > > * Fixed retry token button available for inactive tokens
> > > > * Fixed missing save action button when opening action config from UI designer
> > >
> > > > [accordion] Platform stability
> > > >
> > > > * Fixed advancing errors in partition event table
>
> ***
>
> ### **New features**
>
> > [card] New features
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation
> > > >
> > > > Generate Data Model for tables and table columns from AI Designer
> >
> > > [tab] Renderers
> > >
> > > > [card] Android Accessibility
> > > >
> > > > Accessibility properties from UI Designer now supported in Android renderer
> > >
> > > > [card] Substitution Tags in Selectors
> > > >
> > > > Selectors (checkbox, radio, select, multiselect) now support substitution tags when source type is process data across Angular, React, and iOS renderers
> > >
> > > > [card] Template Caching
> > > >
> > > > Improved caching for reusable templates at runtime
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Dgraph Upgrade
> > > >
> > > > Bring dgraph to flowx-release
> >
> > > [tab] Performance & Optimization
> > >
> > > > [card] Designer Static Assets
> > > >
> > > > Make designer nginx use compression & caching for static assets

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.2 is fully compatible with 5.1.1. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.1 → 5.1.2 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.2](./deployment-guidelines-v5.1.2).
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Task Manager theming issues in Angular and React
> > * Task Manager assignee dropdown display issues in React
> > * Custom component key duplication in action body
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.3-january-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.2 → 5.1.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.3 delivers security patches and significant performance improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.2

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.3 delivers comprehensive security, performance, and stability improvements across the platform.
>
> ♿ [**iOS Accessibility**](#improvements-and-enhancements) — VoiceOver accessibility support for iOS renderer\
> ✨ [**Improvements and enhancements**](#improvements-and-enhancements) — AI Platform improvements and enhancements for Data Model generation\
> ⚡ [**Performance Improvements**](#performance-improvements) — Performance improvements and optimizations across platform components and services\
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Improvements and enhancements**
>
> > [card] Improvements and enhancements
> >
> > > [tab] Renderers
> > >
> > > > [card] iOS Accessibility
> > > >
> > > > VoiceOver accessibility support for the iOS renderer. Accessibility properties configured in the UI Designer (labels, hints, traits, decorative flags) are now applied to iOS components including form elements, text, images, and links.
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation for Tables
> > > >
> > > > Generate Data Model mappings for table components from AI Designer. AI automatically creates array of objects DM keys for tables with type validation and visual feedback.
> > >
> > > > [card] Data Model Generation for Table Columns
> > > >
> > > > Extended DM generation for text and link elements within table columns, with automatic attribute mapping and support for partial matching.
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.3 delivers significant performance improvements to the process engine
> > >
> > > > [card] Optimized Writes
> > > >
> > > > Smart change detection skips unnecessary database writes when param\_values unchanged
> > >
> > > > [card] Reduced DB Calls
> > > >
> > > > N+1 query fixes and batch loading significantly reduce database round trips
> > >
> > > > [card] Request Caching
> > > >
> > > > Request-scoped caching for frequently accessed runtime configuration
> >
> > > [tab] Key optimizations
> > >
> > > > [accordion] ProcessInstance param\_values Optimization
> > > >
> > > > Optimized handling of large `param_values` to reduce network overhead and prevent optimistic locking conflicts:
> > > >
> > > > * **Change Detection**: Skip database writes when param\_values unchanged
> > > > * **Lightweight Queries**: Exclude param\_values from SELECT when not needed
> > >
> > > > [accordion] Runtime Improvements - Reduced DB Calls
> > > >
> > > > **Optimizations Implemented:**
> > > >
> > > > * Improved batch loading and caching to reduce redundant queries
> > > > * Streamlined process initiation
> > > > * Enhanced batching for database writes
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Task Manager View Not Updating
> > > >
> > > > **Problem:**\
> > > > When using a view with dataset config where assignee is set to blank, after assigning a task (or self-assigning), the view appeared unchanged. Similarly, when assignee is set to not blank and you unassign a task, the view did not update.
> > > >
> > > > **Resolution:**\
> > > > Fixed view refresh behavior after assign/unassign operations to properly reflect the updated task state and provide visual feedback to users.
> > >
> > > > [accordion] Forms in Collections - Backend Keys Calculation
> > > >
> > > > **Problem:**\
> > > > When saving data from outside a collection with forms to submit, the backend calculated keys for UUID entries in formsToSubmit. These keys were only partial (relative to the collection array) and could overwrite existing process values.
> > > >
> > > > **Resolution:**\
> > > > Added a flag on PATCH /actions requests to notify the backend to exclude backend keys calculation for forms in collections UUIDs from formsToSubmit.
> > >
> > > > [accordion] Variables Reset on Config Update
> > > >
> > > > **Problem:**\
> > > > Updating parameters in the config page caused existing parameters to be replaced with new ones, generating new flowxUuids. This caused variables in database nodes to no longer match, losing all references.
> > > >
> > > > **Resolution:**\
> > > > Fixed to always send id and flowxUuid for existing params when saving the operation, preserving variable references.
> > >
> > > > [accordion] Build Export Timeout
> > > >
> > > > **Problem:**\
> > > > When exporting builds with multiple resources, some resources remained in EXPORTING status, others got EXPORT\_TIMEOUT without the build export receiving the status, and others had EXPORTED status. This was caused by Kafka messages being processed before the MongoDB transaction was committed.
> > > >
> > > > **Resolution:**\
> > > > Fixed the export function to ensure proper sequencing of database transactions and Kafka messages during build export operations.
> >
> > > [tab] Designer fixes
> > >
> > > > [accordion] Table Row Deletable with Backspace in RUT
> > > >
> > > > **Problem:**\
> > > > In Reusable UI Templates, selecting a table row and pressing backspace would delete the row, even though table rows should not be deletable.
> > > >
> > > > **Resolution:**\
> > > > Fixed keyboard handling to prevent accidental table row deletion via backspace key.
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Android Upload Action Payload Missing
> > > >
> > > > **Problem:**\
> > > > Upload action payload data (except uploadFileTempFileId) was missing on execution in the Android renderer.
> > > >
> > > > **Resolution:**\
> > > > Fixed payload handling to include all required data in upload action execution.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Connector Topic Pattern
> > > >
> > > > Added dedicated KAFKA\_TOPIC\_CONNECTOR\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [tab] AI Platform
> > >
> > > > [card] Streaming Client Library
> > > >
> > > > Implemented client library for invoking the run AI node with streaming support for conversational API

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.3 is fully compatible with 5.1.2. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.2 → 5.1.3 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### New configuration options
>
> > [!NOTE]
> >
> > **Optional**: New environment variable available for process-engine
>
> | Variable | Description | Default |
> | - | - | - |
> | `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from other platform components | Falls back to `KAFKA_TOPIC_PATTERN` if not set |
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.3](./deployment-guidelines-v5.1.3).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.3 → 5.1.4** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.4 delivers security patches and stability improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.3

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.4 delivers comprehensive security, performance, and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components and stability improvements\
> ⚡ [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Form validators do not work inside collection prototypes
> > > >
> > > > **Summary:**
> > > >
> > > > Validators applied to forms within collection prototypes are not triggered as expected.
> > >
> > > > [accordion] Project editor could modify access permissions
> > > >
> > > > **Summary:**
> > > >
> > > > Project editors were incorrectly able to modify project access permissions and delete projects. This has been fixed: `project_editor` can no longer modify access management or delete projects/libraries. Only `project_owner` and `workspace_admin` can change project ownership, add/remove users and groups from projects/libraries, and delete projects/libraries.
> > >
> > > > [accordion] Subprocess UI still shown after subprocess is finished
> > > >
> > > > **Summary:**
> > > >
> > > > In processes with multiple subprocesses that have UI, the first subprocess UI remained visible after completion until the next user task details were received. The UI now correctly clears when a subprocess finishes.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Kafka environment variables alignment
> > > >
> > > > Kafka environment variables are now consistent across all services with backwards compatibility support for existing configurations.
> > >
> > > > [card] Config params cache improvements
> > > >
> > > > New environment variables for tuning config params cache: `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` and `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`. See [Engine Setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
> > >
> > > > [card] Project editor permissions update
> > > >
> > > > `project_editor` can no longer delete projects or modify access permissions. `projects_admin` permission now grants full project management capabilities. See [Roles Permissions Matrix](/5.1/setup-guides/access-management/roles-permissions-matrix).
> > >
> > > > [card] Advancing partition counter fix
> > > >
> > > > Fixed an issue where the advancing partition counter could go negative, causing event processing failures. Improves reliability in integration-designer and process-engine.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.4 is fully compatible with 5.1.3. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.3 → 5.1.4 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.4](./deployment-guidelines-v5.1.4).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.5-february-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.4 → 5.1.5** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.5 delivers bug fixes and stability improvements:
>
> * Fixes for process loop rendering issues in the Angular renderer
> * Fix for subprocess output data not being returned from embedded processes
> * No breaking changes — fully compatible upgrade from 5.1.4

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.5 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer and process engine fixes for process loop scenarios
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes
> > >
> > > Issues resolved in the Angular renderer:
> > >
> > > > [accordion] Validation shown without user interaction on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task for the second time, form validation errors were displayed immediately without any user interaction. Validation now correctly waits for user input before showing errors.
> > >
> > > > [accordion] Action executed continuously on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task that had a UI action configured on a form element, the action was executed continuously in a loop. Actions are now correctly triggered only on user interaction.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Subprocess not returning output from embedded process
> > > >
> > > > **Summary:**
> > > >
> > > > When a subprocess (call activity) was started from an embedded process, the output data was not passed back to the parent process instance after completion. Data mapping from subprocess to parent now works correctly in embedded process scenarios.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.5 is fully compatible with 5.1.4. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.4 → 5.1.5 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.5](./deployment-guidelines-v5.1.5).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026

Bug fixes, stability improvements, and platform enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.5 → 5.1.6** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.6 delivers bug fixes and stability improvements:
>
> * Multiple React and Angular renderer fixes for modals, sliders, buttons, and accessibility
> * Data mappers autocomplete fix for values not loading
> * Process engine fix for advancing getting stuck on pod crash with multiple partition events
> * Kafka health check fix for reporting UP despite consumer DNS failure
> * New health indicator for runtime MongoDB connection
> * Connection leak fix in application-manager export/import operations
> * Improved retry mechanism with configurable exponential backoff
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.5

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.6 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer, process engine, and application manager fixes
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Retry mechanism enhancements and security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes (React)
> > >
> > > Issues resolved in the React renderer:
> > >
> > > > [accordion] Clear icon present and clickable on disabled input/textarea
> > > >
> > > > **Summary:**
> > > >
> > > > When an input or textarea component was disabled, the clear icon was still visible and clickable. The clear icon is now hidden and non-interactive on disabled components.
> > >
> > > > [accordion] Options list not shown when selectors are inside modal
> > > >
> > > > **Summary:**
> > > >
> > > > When select or multiselect components were placed inside a modal, the options list was not displayed when opened. Selector dropdowns now render correctly within modal contexts.
> > >
> > > > [accordion] Datepicker calendar shown behind modal
> > > >
> > > > **Summary:**
> > > >
> > > > When a datepicker was placed inside a modal, the calendar popup appeared behind the modal overlay. The datepicker calendar now renders above the modal with correct z-index stacking.
> > >
> > > > [accordion] Slider min/max value not set when loading a screen
> > > >
> > > > **Summary:**
> > > >
> > > > When a slider shared a process data key with an input, or when slider min/max values depended on computed values from another slider, the min/max values were not set on load. Slider initialization now correctly applies min/max values and computed dependencies.
> > >
> > > > [accordion] Slider default value not set with multiple sliders on same page
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple sliders were present on the same page, some sliders did not receive their default values, especially when no explicit null value was set in the data store. Default value initialization now works correctly for all sliders on a page.
> > >
> > > > [accordion] Task management assignee clear icon clickable when disabled
> > > >
> > > > **Summary:**
> > > >
> > > > In the task management view, the assignee field's clear icon was visible and clickable even when the field was disabled (non-editable). The clear icon is now hidden when the assignee field cannot be edited.
> > >
> > > > [accordion] Input, select, datepicker, textarea, and table filters have incorrect inner outline
> > > >
> > > > **Summary:**
> > > >
> > > > Multiple form components displayed an incorrect inner outline styling. The outline now only appears during keyboard navigation, following proper accessibility patterns.
> > >
> > > > [accordion] Data mappers autocomplete values not loading
> > > >
> > > > **Summary:**
> > > >
> > > > Data mapper autocomplete suggestions were not loading values in certain configurations. Autocomplete now correctly fetches and displays available values.
> >
> > > [tab] Renderer fixes (Angular + React)
> > >
> > > Issues resolved in both Angular and React renderers:
> > >
> > > > [accordion] Card height does not update when accordion is collapsed
> > > >
> > > > **Summary:**
> > > >
> > > > When a card component with fixed height contained an accordion, the card height did not update when the accordion was collapsed. Card height now correctly recalculates when accordion state changes.
> > >
> > > > [accordion] Focus outline appears when interacting with card/file preview accordion
> > > >
> > > > **Summary:**
> > > >
> > > > When interacting with a card or file preview component that included an accordion, an unwanted focus outline appeared. The focus outline is now only displayed during keyboard navigation.
> > >
> > > > [accordion] Button icon not correctly rendered
> > > >
> > > > **Summary:**
> > > >
> > > > When a button was configured with a right-aligned icon, fill width, and right-aligned typography, the icon was not aligned with the text, the gap was missing, and text and icon were center-aligned instead of right-aligned. Button icon layout now respects all configured alignment and spacing settings.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Advancing gets stuck when multiple events are available for one partition and pod crashes
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple events were available for the same partition and a pod crashed, only the first event was picked up and the rest remained stuck. Event processing now correctly handles all pending events after a pod recovery.
> > >
> > > > [accordion] Kafka health check reported UP despite consumer DNS failure
> > > >
> > > > **Summary:**
> > > >
> > > > The Kafka health check indicator could report UP even when consumers had DNS resolution failures, masking connectivity issues. Health indicators now correctly reflect the actual state of Kafka consumer connections.
> > >
> > > > [accordion] Health indicator for runtime MongoDB connection
> > > >
> > > > **Summary:**
> > > >
> > > > A new health indicator has been added to monitor the runtime MongoDB connection. This improves observability and allows operators to detect MongoDB connectivity issues through the standard health endpoint.
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Theme not imported during build import
> > > >
> > > > **Summary:**
> > > >
> > > > When importing a build that included theme resources, the theme was not correctly imported. Build import now includes theme resources as expected.
> > >
> > > > [accordion] Connection leak in export/import services
> > > >
> > > > **Summary:**
> > > >
> > > > During import/export operations, database connections were held for the entire duration of long-running operations (MinIO file transfers, REST calls, Kafka messaging), which could exhaust the connection pool. Transaction boundaries have been refined so that database connections are only held during actual database operations.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Process engine
> > >
> > > > [accordion] Configurable retry mechanism with exponential backoff
> > > >
> > > > **Summary:**
> > > >
> > > > The retry mechanism for optimistic locking in the process engine now uses an Equal Jitter strategy and supports runtime configuration via environment variables. Previously, the jitter was nullified by the max delay cap, causing retrying threads to collide at the same millisecond.
> > > >
> > > > New environment variables for the `process-engine`:
> > > >
> > > > | Environment Variable | Description | Default Value |
> > > > | - | - | - |
> > > > | `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` |
> > > > | `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` |
> > > > | `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` |
> > > >
> > > > > [!TIP]
> > > > >
> > > > > Default settings give a total retry window of \~1.2 seconds, which covers most transient optimistic lock conflicts. Increase `FLOWX_RETRY_MAX_RETRIES` or `FLOWX_RETRY_MAX_DELAY_MS` if you see retry exhaustion under high contention.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Removed deprecated access rights endpoint
> > > >
> > > > **Summary:**
> > > >
> > > > A deprecated endpoint and its associated test for access rights have been removed from the codebase as they are no longer needed.
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across all platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.6 is fully compatible with 5.1.5. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.5 → 5.1.6 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.6](./deployment-guidelines-v5.1.6).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.7 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.7-march-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.6 → 5.1.7** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.7 delivers bug fixes and stability improvements:
>
> * Fix for build import issues with manifest (reimport failures)
> * Security patches
> * No breaking changes, fully compatible upgrade from 5.1.6

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.7 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Build import fix
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Build reimport failures with manifest issues
> > > >
> > > > **Summary:**
> > > >
> > > > When reimporting a build, the import could fail due to manifest validation issues, either stopping mid-import or reporting that the build was already being imported. Build reimport now correctly handles manifest validation and prevents duplicate import conflicts.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.7 is fully compatible with 5.1.6. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.6 → 5.1.7 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.7](./deployment-guidelines-v5.1.7).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.8 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.8-april-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.7 → 5.1.8** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.8 delivers security patches and dependency upgrades:
>
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.7

***

**What's new? 🆕**

> [tab] Highlights
>
> Security patches and dependency upgrades across platform components.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.8 is fully compatible with 5.1.7. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.7 → 5.1.8 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.8](./deployment-guidelines-v5.1.8).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.9 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.9-may-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.8 → 5.1.9** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.9 delivers notable bug fixes alongside security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Android renderer fixes
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.8

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Advancing workers** — Improved connection management so advancing workers no longer accumulate database connections across cooldown and rampup cycles, preventing connection growth on long-running runtime deployments.
> > > > * **Reusable UI templates** — Fixed an issue where input and output mappings on reusable UI templates could be silently lost when a referenced library version was updated.
> > > > * **Designer** — Fixed server errors when bulk-editing UI templates and when patching UI actions inside reusable UI templates.
> > > > * **Android renderer** — Fixed sticky container behavior across nested hierarchy levels, and deferred the custom loader display until CMS resources are available.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.9 is fully compatible with 5.1.8. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.8 → 5.1.9 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.9](./deployment-guidelines-v5.1.9).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.2.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/deployment-guidelines-v5.2

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.12.0** | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **10.12.0** | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **10.7.0** | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **10.7.0** | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **10.6.0** | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **10.4.1** | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **10.6.0** | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **10.4.1** | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **10.8.0** | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **10.3.1** | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **10.4.1** | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **10.0.0** | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **10.0.0** | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.0.1** | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | **10.2.0** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.2.0 | Keycloak | 26+ |
| 5.2.0 | Kafka | 3.8 - 3.9 |
| 5.2.0 | PostgreSQL | 16 - 17 |
| 5.2.0 | Oracle Database | 21c, 23ai |
| 5.2.0 | MongoDB | 7 - 8 |
| 5.2.0 | Redis | 7.4 - 8.0 |
| 5.2.0 | Elasticsearch | 8 - 9 |
| 5.2.0 | Angular (Web SDK) | 19.2 |
| 5.2.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.2.0

### Key infrastructure updates

> [card] SpiceDB Upgrade
>
> Upgraded to SpiceDB v1.38.0+ and spice-db-operator for improved permission management and stability

> [card] Security Enhancements
>
> Updated Java libraries and base images to Oracle 10-slim, resolving HIGH and CRITICAL vulnerabilities

> [card] Accessibility Support
>
> Enhanced renderer components with comprehensive WCAG 2.1 compliance features

> [card] Python IDE Features
>
> Added autocomplete and IntelliSense support in business rules editors

> [card] Parallel Workflow Branches
>
> Support for concurrent execution paths in Integration Designer workflows

> [card] Workflow Partitioning & Archiving
>
> Time-based partitioning and automatic archiving for Integration Designer workflow instances

## Upgrading from v5.1.0

### Key changes

* **Accessibility Features**: No breaking changes, but new accessibility properties available in UI Designer
* **Database Security**: FlowX Database now supports sensitive data masking (requires Project Data Model configuration)
* **IDE Enhancements**: Python autocomplete is automatically available in business rules editors
* **Infrastructure**: SpiceDB upgrade requires cache clearing after migration

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.

### Compatibility

* **Backward Compatible**: v5.2.0 maintains backward compatibility with v5.1.0 configurations
* **Renderer Updates**: Web SDKs include accessibility enhancements without breaking changes
* **Mobile Renderers**: iOS and Android renderers include accessibility improvements

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/update-environment-variables-5.2

Update environment variables for all existing FlowX.AI services

## Integration Designer

### Workflow partitioning and archiving

> [!NOTE]
>
> Integration Designer now supports workflow instance partitioning and automatic archiving for efficient data management in high-volume deployments.

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Enable or disable workflow instance partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Time interval for creating partitions (`DAY`, `WEEK`, `MONTH`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Enable or disable automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Cron expression for archiving schedule (default: daily at 1:00 AM) |

> [!NOTE]
>
> **Workflow partitioning configuration:**
>
> * **Partitioning**: When enabled, workflow instances are stored in time-based partitions according to the specified interval
> * **Retention**: Determines how many intervals to keep active. Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> * **Archiving schedule**: The cron expression controls when the archiving process runs
> * **Best practice**: Enable partitioning first without archiving, verify it works correctly, then enable archiving

> [!WARNING]
>
> Enable partitioning and archiving only after careful planning and testing. Ensure your database has sufficient storage for partition management operations. It's recommended to start with archiving disabled and enable it only after verifying that partitioning works correctly for your use case.

### Advancing controller improvements

> [!NOTE]
>
> Integration Designer now uses the new ADVANCING controller with separate picking and processing operations for improved performance and resource management.

#### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

#### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.


# FlowX.AI 5.2.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025

Accessibility improvements, new side panel navigation, FlowX Database sensitive data handling, REST API response caching, and Python IDE enhancements for business rules development.

**What's new?**

> [tab] Accessibility & UX
>
> Making FlowX applications more inclusive and user-friendly with comprehensive accessibility improvements and enhanced navigation.
>
> ♿ [**Accessibility Enhancements**](#accessibility-enhancements) - Comprehensive [WCAG](https://www.w3.org/TR/WCAG21/) (Web Content Accessibility Guidelines) compliance features across all UI components\
> 🎨 [**New Workflow Side Panel**](#new-workflow-side-panel) - Enhanced navigation experience with improved drag-and-drop functionality
>
> ### **Accessibility enhancements**
>
> > [card] Accessibility enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds accessibility features across all UI components, enabling you to build [WCAG 2.1 Level AA compliant](https://www.w3.org/TR/WCAG21/) applications. These features support users with assistive technologies such as screen readers and keyboard-only navigation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs1.png)
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs2.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Accessibility Configuration Panel
> > > >
> > > > Configure labels, descriptions, and ARIA attributes in a dedicated accessibility section within UI Designer
> > >
> > > > [card] Auto-bindable Tags
> > > >
> > > > Bind accessibility tags automatically to buttons, inputs, selects, modals, and other UI components
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Navigate using keyboard shortcuts with proper focus management and tab order in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > Use screen readers with ARIA labels, descriptions, and live regions on all components
> >
> > > [tab] Supported Components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio buttons, Slider, and File upload components with labels and descriptions
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card components with keyboard navigation and focus management
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with alt text support and semantic HTML structure
> > >
> > > **4. Cross-Platform Support**
> > >
> > > Web (Angular/React), iOS, and Android platforms
> >
> > > [tab] Benefits
> > >
> > > > [card] WCAG Compliance
> > > >
> > > > Build applications that meet WCAG 2.1 Level AA standards for web accessibility
> > >
> > > > [card] Inclusive Design
> > > >
> > > > Make your applications usable for people with diverse abilities and assistive technology users
> > >
> > > > [card] Improved User Experience
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those using assistive technologies
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Meet accessibility requirements for government, healthcare, financial services, and other regulated industries
> >
> > Major Enhancement
>
> ***
>
> ### **New workflow side panel**
>
> > [card] New workflow side panel
> >
> > > [tab] Overview
> > >
> > > The new Workflow Side Panel provides an enhanced navigation experience in Integration Designer workflows. It includes improved organization, better drag-and-drop functionality, and intuitive access to design components and resources.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_side_panel.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Drag & Drop
> > > >
> > > > Add and organize workflow nodes with drag-and-drop functionality
> > >
> > > > [card] Improved Organization
> > > >
> > > > Group nodes logically with expandable/collapsible sections
> > >
> > > > [card] Search & Filter
> > > >
> > > > Find nodes instantly with quick search functionality
> >
> > UI/UX Enhancement
>
> ***

> [tab] Data & Security
>
> Enhanced data management and security features for FlowX Database and business rules.
>
> 🔒 [**FlowX Database Sensitive Data**](#flowx-database-sensitive-data) - GDPR-compliant sensitive data handling for FlowX Database\
> 🚀 [**Performance Improvements**](#performance-improvements) - Caching optimizations for better system performance
>
> ### **FlowX database sensitive data**
>
> > [card] FlowX database sensitive data
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds sensitive data handling for FlowX Database to ensure GDPR compliance. Attributes marked as sensitive in your Project Data Model are automatically protected across all FlowX Database operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic Data Masking
> > > >
> > > > Hide sensitive attributes automatically in logs, console outputs, and testing interfaces
> > >
> > > > [card] Project Data Model Integration
> > > >
> > > > Mark attributes as sensitive in Project Data Model to apply protection across all FlowX Database operations
> > >
> > > > [card] Developer-Friendly
> > > >
> > > > Access full data at runtime while maintaining security in design-time interfaces
> > >
> > > > [card] Audit Trail Protection
> > > >
> > > > Mask sensitive data in workflow output logs and operational documents
> >
> > > [tab] Protected Areas
> > >
> > > **1. Documents Page**
> > >
> > > Sensitive attributes are masked when viewing FlowX Database documents in the designer
> > >
> > > **2. Test Operations Pages**
> > >
> > > Database operation testing interfaces automatically hide sensitive data
> > >
> > > **3. Workflow Console**
> > >
> > > Console logs and output panels mask sensitive information from FlowX Database responses
> > >
> > > **4. Full Runtime Access**
> > >
> > > Applications have full access to sensitive data at runtime - protection is design-time only
> >
> > > [tab] Benefits
> > >
> > > > [card] GDPR Compliance
> > > >
> > > > Meet data protection requirements by preventing sensitive data exposure in design tools
> > >
> > > > [card] Security by Design
> > > >
> > > > Sensitive data protection is automatic once attributes are marked in Project Data Model
> > >
> > > > [card] Developer Productivity
> > > >
> > > > Test and develop without worrying about accidentally exposing sensitive information
> > >
> > > > [card] Audit-Ready
> > > >
> > > > Demonstrate proper data handling practices with masked logs and interfaces
> >
> > Security Enhancement
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Caching Enhancements
> > >
> > > FlowX.AI 5.2.0 adds intelligent caching mechanisms that improve system performance by reducing redundant processing when identical values are sent at process start.
> >
> > > [tab] Key Features
> > >
> > > > [card] Smart Caching
> > > >
> > > > Cache and reuse results automatically when identical input values are detected
> > >
> > > > [card] Reduced Latency
> > > >
> > > > Start processes faster when repeating operations with the same parameters
> > >
> > > > [card] Resource Optimization
> > > >
> > > > Reduce server load and improve resource utilization
> > >
> > > > [card] Automatic Management
> > > >
> > > > Manage cache automatically with no configuration required
> >
> > > [tab] Benefits
> > >
> > > **1. Response Times**
> > >
> > > Initialize processes faster in cached scenarios
> > >
> > > **2. Scalability**
> > >
> > > Handle more concurrent users with the same infrastructure
> > >
> > > **3. Cost Efficiency**
> > >
> > > Use fewer compute resources for high-volume scenarios
> >
> > Performance

> [tab] Developer Experience
>
> Enhanced tools and features for business rules development, testing, and workflow design.
>
> 🔀 [**Parallel Branches in Workflows**](#parallel-branches-in-workflows) - Design and execute parallel execution paths in Integration Designer workflows\
> 💾 [**REST API Response Caching**](#integration-designer-rest-api-response-caching) - Cache GET endpoint responses in Integration Designer with flexible TTL policies\
> 📊 [**Workflow Partitioning & Archiving**](#workflow-partitioning-&-archiving) - Manage Integration Designer workflow data efficiently with time-based partitions and automatic archiving\
> 🐍 [**Python IDE Enhancements**](#python-ide-enhancements) - Autocomplete and IntelliSense for Python business rules\
> 🧪 [**Business Rules Testing**](#functions-testing) - Save test parameters in reusable functions modal
>
> ### **Parallel branches in workflows**
>
> > [card] Parallel branches in workflows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds the ability to design and execute parallel branches in Integration Designer workflows. This enables concurrent execution of independent workflow paths and improves performance for complex integrations.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Start Parallel Node
> > > >
> > > > Split workflow execution into multiple concurrent branches with start parallel nodes
> > >
> > > > [card] End Parallel Node
> > > >
> > > > Merge parallel branches with end parallel nodes that wait for all branches to complete
> > >
> > > > [card] Path Visualization
> > > >
> > > > View which nodes belong to which parallel branch with visual path indexing in the workflow diagram
> > >
> > > > [card] Runtime Monitoring
> > > >
> > > > Track parallel path execution with timing information for each branch and merge point
> >
> > > [tab] How It Works
> > >
> > > **1. Design Parallel Paths**
> > >
> > > Add a Start Parallel node and create multiple sequences from it. Each sequence represents an independent execution path
> > >
> > > **2. Configure Branch Logic**
> > >
> > > Add workflow nodes to each parallel branch, such as API calls, transformations, or database operations
> > >
> > > **3. Merge Paths**
> > >
> > > Close parallel branches with an End Parallel node. This node waits for all branches to complete before continuing
> > >
> > > **4. Runtime Execution**
> > >
> > > All branches execute concurrently at runtime. The End Parallel node completes when the slowest branch finishes
> >
> > > [tab] Use Cases
> > >
> > > > [card] Multiple API Calls
> > > >
> > > > Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Fetch data from multiple sources in parallel for comprehensive data aggregation
> > >
> > > > [card] Notification Broadcasting
> > > >
> > > > Send notifications through multiple channels (email, SMS, push) simultaneously
> > >
> > > > [card] Document Processing
> > > >
> > > > Process different document types or sections in parallel for faster throughput
> >
> > > [tab] Runtime Behavior
> > >
> > > > [accordion] Path Timing
> > > >
> > > > * **Path Time**: Sum of all node execution times within that branch
> > > > * **End Parallel Time**: Node processing time + maximum time across all parallel paths
> > > > * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
> > >
> > > > [accordion] Console Logging
> > > >
> > > > * **Start Parallel Node**: Displays Input tab showing data split across branches
> > > > * **End Parallel Node**: Displays Output tab showing merged results from all branches
> > > > * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
> > >
> > > > [accordion] Error Handling
> > > >
> > > > * If any branch fails, the workflow handles it according to standard error handling rules
> > > > * End Parallel node waits for all non-failed branches before continuing
> > > > * Runtime validation ensures parallel branches are configured correctly
> >
> > > [tab] Limitations
> > >
> > > > [!WARNING]
> > > >
> > > > **First Iteration Constraints**: This is the initial implementation of parallel branches with the following considerations:
> > >
> > > * **Array Processing**: Arrays are not merged across parallel branches. When multiple branches modify the same array path, the last branch to complete determines the final array value. You cannot process individual objects from the same array in different parallel branches (for example, first element in branch 1, second element in branch 2). To preserve data from all branches, save to different keys and merge manually using a script before the end node
> > >
> > > * **Branch Closure**: All start parallel branches must be closed with end parallel nodes. Nodes following a start parallel node must merge into the same end parallel node, except for nodes that terminate with end workflow nodes
> > >
> > > > [!NOTE]
> > > >
> > > > Based on user feedback and raised exceptions during runtime execution, additional configuration constraints and validations are planned for future releases.
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Reduce workflow execution time by running independent operations concurrently instead of sequentially
> > >
> > > **2. Resource Utilization**
> > >
> > > Maximize throughput by executing multiple operations simultaneously
> > >
> > > **3. Design Clarity**
> > >
> > > Model concurrent operations explicitly in your workflow diagrams
> > >
> > > **4. Monitoring**
> > >
> > > Track execution time for each parallel path to identify bottlenecks
> >
> > Integration Designer
>
> ***
>
> ### **Integration Designer REST API response caching**
>
> > [card] Integration Designer REST API response caching
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces intelligent response caching for REST API GET endpoints in Integration Designer. Cache responses based on flexible Time-To-Live (TTL) policies to reduce redundant API calls, avoid rate limits, and lower operational costs while maintaining data freshness.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Endpoint_Get.png)
> > >
> > > > [!NOTE]
> > > >
> > > > When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Flexible TTL Policies
> > > >
> > > > Configure caching with "Expires after" (duration-based) or "Expires at" (time-based) policies
> > >
> > > > [card] Cache Management
> > > >
> > > > Clear cached responses from endpoint definitions or testing modals as needed
> > >
> > > > [card] Cache Status Visibility
> > > >
> > > > View cache status, keys, and TTL information in testing modals and workflow console logs
> > >
> > > > [card] Automatic Fallback
> > > >
> > > > System automatically calls the external API if cache retrieval fails, ensuring reliability
> >
> > > [tab] TTL Configuration
> > >
> > > > [accordion] Expires After (Duration-Based)
> > > >
> > > > Cache responses for a specific duration after the request is made.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **ISO Duration**: Use ISO 8601 duration format (e.g., `PT1H` for 1 hour, `P1D` for 1 day, `P1W` for 1 week)
> > > > * **Dynamic Duration**: Reference configuration parameters (e.g., `${myConfigParam}`)
> > > > * **Default**: `R/P1D` (1 day)
> > > >
> > > > **Example**: Cache for 10 minutes after each request
> > > >
> > > > ```
> > > > PT10M
> > > > ```
> > >
> > > > [accordion] Expires At (Time-Based)
> > > >
> > > > Cache responses until a specific time of day with recurring patterns.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **Expire Time**: Set specific time (e.g., `23:00` for midnight, `08:00` for 8 AM)
> > > > * **Recurrency**: Set how often the pattern repeats (integer > 0, default: 1)
> > > > * **Time Unit**: Choose Day, Week, or Month (default: Day)
> > > >
> > > > **Example**: Cache until midnight every day
> > > >
> > > > ```
> > > > Expire Time: 00:00
> > > > Recurrency: 1
> > > > Time Unit: Day
> > > > ```
> > > >
> > > > **Example**: Cache until 6 PM every Friday
> > > >
> > > > ```
> > > > Expire Time: 18:00
> > > > Recurrency: 1
> > > > Time Unit: Week
> > > > ```
> >
> > > [tab] Cache Visibility
> > >
> > > **1. Testing Modal**
> > >
> > > View cache status directly in the endpoint testing modal with:
> > >
> > > * **Cache Hit/Miss Status**: Whether results came from cache
> > > * **Cache Key**: The unique identifier for the cached response
> > > * **TTL Information**: When the cache expires (e.g., "Expires after PT10M" or "Expires at 23:00 on 2025-11-04")
> > >
> > > **2. Workflow Console**
> > >
> > > Monitor cache usage in workflow execution logs with the same detailed information
> > >
> > > **3. Clear Cache Action**
> > >
> > > Clear cached responses from the endpoint page or testing modal when cache is configured
> >
> > > [tab] How It Works
> > >
> > > **1. Configure Caching**
> > >
> > > In Integration Designer, open a REST System and navigate to a GET endpoint. Enable caching and select your TTL policy (Expires After or Expires At)
> > >
> > > **2. First Request**
> > >
> > > When the endpoint is called for the first time, the response is fetched from the external API and stored in cache with the configured TTL
> > >
> > > **3. Subsequent Requests**
> > >
> > > If the cache is still valid (within TTL), subsequent requests return the cached response immediately without calling the external API
> > >
> > > **4. Cache Expiration**
> > >
> > > Once TTL expires, the next request fetches fresh data from the external API and updates the cache
> > >
> > > **5. Cache Management**
> > >
> > > Use the "Clear Cache" action to manually invalidate cached responses when needed (e.g., after data updates)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Reference Data
> > > >
> > > > Cache country lists, product catalogs, or other reference data that rarely changes
> > >
> > > > [card] Rate Limit Avoidance
> > > >
> > > > Reduce API calls to third-party services with strict rate limits
> > >
> > > > [card] Cost Optimization
> > > >
> > > > Lower operational costs by reducing billable API calls to external services
> > >
> > > > [card] Performance
> > > >
> > > > Improve workflow execution speed by eliminating network latency for cached responses
> >
> > > [tab] Error Handling
> > >
> > > > [!WARNING]
> > > >
> > > > **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. This ensures your workflows always receive correct data.
> > >
> > > **Failure Scenarios**:
> > >
> > > * Cache service unavailable → Direct API call
> > > * Cache corruption or invalid data → Direct API call
> > > * Cache storage failure → Direct API call (with warning logged)
> > >
> > > Your workflows continue to function normally even if caching fails.
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced API Costs
> > > >
> > > > Minimize charges from external APIs by serving cached responses when data hasn't changed
> > >
> > > > [card] Improved Performance
> > > >
> > > > Return responses instantly from cache instead of waiting for external API calls
> > >
> > > > [card] Rate Limit Compliance
> > > >
> > > > Stay within API rate limits by reducing the number of requests to external services
> > >
> > > > [card] Better Scalability
> > > >
> > > > Handle higher workflow volumes without increasing external API calls
> >
> > Integration Designer
>
> > [card] [REST Endpoint Caching](../../../5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching)
> >
> > Learn how to configure caching policies, manage cache, and optimize your REST API integrations
>
> ***
>
> ### **Workflow partitioning & archiving**
>
> > [card] Workflow partitioning & archiving
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces workflow instance partitioning and archiving for Integration Designer. This feature enables efficient management of workflow data by organizing instances into time-based partitions and automatically archiving old data to maintain optimal database performance in large-scale deployments.
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow partitioning is particularly beneficial for high-volume Integration Designer workflows where instances accumulate over time, helping to maintain query performance and manage storage efficiently.
> >
> > > [tab] Key Features
> > >
> > > > [card] Time-Based Partitioning
> > > >
> > > > Organize workflow instances into partitions based on configurable time intervals (Day, Week, or Month)
> > >
> > > > [card] Automatic Archiving
> > > >
> > > > Automatically archive partitions older than the specified retention period to optimize active database size
> > >
> > > > [card] Flexible Retention Policies
> > > >
> > > > Configure how many time intervals to retain before archiving with granular control
> > >
> > > > [card] Scheduled Archiving
> > > >
> > > > Use cron expressions to schedule archiving operations at optimal times
> >
> > > [tab] Configuration
> > >
> > > Configure workflow partitioning using environment variables in Integration Designer:
> > >
> > > > [accordion] Partitioning Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ENABLED`**: Enable or disable workflow instance partitioning
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_INTERVAL`**: Time interval for creating partitions
> > > >   * Default: `MONTH`
> > > >   * Options: `DAY`, `WEEK`, `MONTH`
> > >
> > > > [accordion] Archiving Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`**: Enable or disable automatic archiving
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`**: Number of intervals to retain before archiving
> > > >   * Default: `3`
> > > >   * Options: Any positive integer
> > > >   * Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`**: Schedule for archiving operations
> > > >   * Default: `0 0 1 * * ?` (runs daily at 1:00 AM)
> > > >   * Options: Any valid cron expression
> >
> > > [tab] How It Works
> > >
> > > **1. Enable Partitioning**
> > >
> > > Set `FLOWX_DATA_PARTITIONING_ENABLED=true` to start organizing workflow instances into time-based partitions
> > >
> > > **2. Configure Partition Interval**
> > >
> > > Choose a partition interval (DAY, WEEK, or MONTH) based on your workflow volume and retention needs
> > >
> > > **3. Set Retention Policy**
> > >
> > > Define how many intervals to retain. For example, with MONTH interval and 3 retention intervals, data older than 3 months will be archived
> > >
> > > **4. Enable and Schedule Archiving**
> > >
> > > Turn on archiving and configure the cron expression to run archiving operations during low-traffic periods
> > >
> > > **5. Monitor Performance**
> > >
> > > Track database performance improvements as old partitions are archived and active data size is optimized
> >
> > > [tab] Use Cases
> > >
> > > > [card] High-Volume Workflows
> > > >
> > > > Maintain performance for Integration Designer workflows processing thousands of instances daily
> > >
> > > > [card] Compliance Requirements
> > > >
> > > > Archive historical workflow data while maintaining access to recent instances for operational needs
> > >
> > > > [card] Database Optimization
> > > >
> > > > Keep active database size manageable by automatically moving old data to archive partitions
> > >
> > > > [card] Long-Running Deployments
> > > >
> > > > Prevent database bloat in production environments running for extended periods
> >
> > > [tab] Best Practices
> > >
> > > > [!WARNING]
> > > >
> > > > **Planning and Testing Required**: Enable partitioning and archiving only after careful planning and testing. Once enabled:
> > > >
> > > > * Ensure sufficient database storage for partition management operations
> > > > * Start with archiving disabled to verify partitioning works correctly
> > > > * Test thoroughly in non-production environments before enabling in production
> > > > * Monitor database performance during initial archiving operations
> > > > * Choose partition intervals based on your workflow volume and retention requirements
> > >
> > > **Recommended Approach**:
> > >
> > > 1. Enable partitioning first without archiving
> > > 2. Monitor partition creation and database performance
> > > 3. After verifying stable operation, enable archiving
> > > 4. Schedule archiving during low-traffic periods (e.g., overnight)
> > > 5. Start with longer retention periods and adjust based on requirements
> >
> > > [tab] Benefits
> > >
> > > > [card] Improved Performance
> > > >
> > > > Maintain fast query performance as workflow instance count grows over time
> > >
> > > > [card] Efficient Storage
> > > >
> > > > Optimize database storage by archiving historical data while keeping recent data accessible
> > >
> > > > [card] Automatic Management
> > > >
> > > > Set retention policies once and let the system handle archiving automatically
> > >
> > > > [card] Scalability
> > > >
> > > > Support long-running production deployments with predictable database growth
> >
> > Integration Designer
>
> > [card] [Integration Designer Setup](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration)
> >
> > Learn how to configure workflow partitioning and archiving for Integration Designer
>
> ***
>
> ### **Python IDE enhancements**
>
> > [card] Python IDE enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds professional IDE features to Python business rules development, including autocomplete, IntelliSense, and enhanced code editing capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Autocomplete
> > > >
> > > > Get intelligent code suggestions as you type, including Python standard library and FlowX APIs
> > >
> > > > [card] IntelliSense
> > > >
> > > > Use context-aware code completion with parameter hints and documentation
> > >
> > > > [card] Syntax Highlighting
> > > >
> > > > Read code more easily with enhanced Python syntax highlighting
> > >
> > > > [card] Error Detection
> > > >
> > > > Detect syntax errors in real-time with helpful error messages
> >
> > > [tab] Benefits
> > >
> > > **1. Development Speed**
> > >
> > > Write business rules faster with intelligent code suggestions
> > >
> > > **2. Error Reduction**
> > >
> > > Catch syntax errors before deployment with real-time validation
> > >
> > > **3. API Discovery**
> > >
> > > Discover available APIs and methods through IntelliSense
> > >
> > > **4. Professional Experience**
> > >
> > > Use IDE-quality editing features directly in FlowX Designer
> >
> > Developer Tools
>
> ***
>
> ### **Functions testing**
>
> > [card] Functions testing
> >
> > > [tab] Overview
> > >
> > > Test Reusable Functions more efficiently by saving test parameters directly from the testing modal. This enables faster iteration and better test coverage.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Save Test Parameters
> > > >
> > > > Save test inputs directly from the testing modal and reuse them in future test runs
> > >
> > > > [card] Test History
> > > >
> > > > Access previously saved test parameters for regression testing
> > >
> > > > [card] Faster Iteration
> > > >
> > > > Re-test functions quickly with saved parameter sets
> > >
> > > > [card] Test Coverage
> > > >
> > > > Build a library of test cases for comprehensive function validation
> >
> > > [tab] Benefits
> > >
> > > **1. Quality**
> > >
> > > Test functions more thoroughly to improve quality
> > >
> > > **2. Time Savings**
> > >
> > > Avoid re-entering test data for each test iteration
> > >
> > > **3. Documentation**
> > >
> > > Use saved test cases as examples of how to use the function
> >
> > Testing Enhancement

> [tab] Additional Improvements
>
> Platform improvements, security updates, and bug fixes.
>
> 🌍 [**Task Management Localization**](#task-management-localization) - Comprehensive localization support with automatic table grid localization and 51 substitution tags\
> 🔧 [**Platform Enhancements**](#platform-enhancements) - Infrastructure upgrades and security improvements\
> 🐛 [**Bug Fixes**](#bug-fixes) - Resolved issues and stability improvements
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds comprehensive localization support for Task Management, enabling you to customize all user-facing text elements including table columns, filters, and actions. This allows you to deliver Task Management experiences in multiple languages:
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> >
> > > [tab] Key Features
> > >
> > > > [card] Table Grid Localization (Automatic)
> > > >
> > > > Data table components (filters, menus, pagination, data types) are automatically localized based on container app language
> > >
> > > > [card] Substitution Tags (Manual)
> > > >
> > > > Configure 51 system substitution tags in CMS to localize table columns, task actions, and UI elements
> > >
> > > > [card] Multi-language Support
> > > >
> > > > Support for 34 languages including Arabic, Chinese, Japanese, Korean, and European languages
> > >
> > > > [card] Task Action Localization
> > > >
> > > > Localize all task actions, statuses, and workflow-related text elements
> >
> > > [tab] Localization components
> > >
> > > > [accordion] Table Grid Locale Keys
> > > >
> > > > FlowX Task Management uses a comprehensive table grid localization system. These keys are **automatically applied** by FlowX.AI based on your container app language and cover all table functionality:
> > > >
> > > > * **Filters**: Set filters, text filters, number filters, date filters with all operators (equals, contains, starts with, etc.)
> > > >
> > > > * **Menus**: Column menus, context menus, aggregation functions, sorting options
> > > >
> > > > * **Pagination**: Page navigation, page size selectors, row counts
> > > >
> > > > * **Data Types**: Boolean values, dates, numbers with proper formatting
> > > >
> > > > * **Advanced Features**: Pivot mode, charting, column grouping, and row operations
> > > >
> > > > * **ARIA Labels**: Accessibility labels for screen readers and assistive technologies
> > > >
> > > > > [!NOTE]
> > > > >
> > > > > **Automatic Localization**: Table grid locale keys are automatically translated by FlowX.AI based on your container app language. No manual configuration or setup required.
> > >
> > > > [accordion] FlowX substitution tags (51 keys)
> > > >
> > > > Use these substitution tags in CMS to localize custom Task Management interface elements. All tags include English default values:
> > > >
> > > > **Search & Navigation**
> > > >
> > > > * `sys_tm_search` - "Search"
> > > >
> > > > **Table Columns**
> > > >
> > > > * `sys_tm_title` - "Title"
> > > > * `sys_tm_stage` - "Stage"
> > > > * `sys_tm_assignee` - "Assignee"
> > > > * `sys_tm_status` - "Status"
> > > > * `sys_tm_priority` - "Priority"
> > > > * `sys_tm_last_updated` - "Last updated"
> > > >
> > > > **Process States (Status Values)**
> > > >
> > > > * `sys_tm_created` - "Created"
> > > > * `sys_tm_started` - "Started"
> > > > * `sys_tm_finished` - "Finished"
> > > > * `sys_tm_finished_with_error` - "Finished with error"
> > > > * `sys_tm_failed` - "Failed"
> > > > * `sys_tm_expired` - "Expired"
> > > > * `sys_tm_aborted` - "Aborted"
> > > > * `sys_tm_terminated` - "Terminated"
> > > > * `sys_tm_dismissed` - "Dismissed"
> > > > * `sys_tm_on_hold` - "On hold"
> > > >
> > > > **Bulk Actions**
> > > >
> > > > * `sys_tm_assign_to` - "Assign to…"
> > > > * `sys_tm_unassign_all` - "Unassign All"
> > > > * `sys_tm_assign_all_to_me` - "Assign All to me"
> > > > * `sys_tm_hold_all` - "Hold All"
> > > > * `sys_tm_unhold_all` - "Unhold All"
> > > >
> > > > **Task Actions**
> > > >
> > > > * `sys_tm_view_application` - "View Application"
> > > > * `sys_tm_unassign` - "Unassign"
> > > > * `sys_tm_assign_to_myself` - "Assign to myself"
> > > > * `sys_tm_unhold` - "Unhold"
> > > > * `sys_tm_hold` - "Hold"
> > > > * `sys_tm_assign` - "Assign"
> > > > * `sys_tm_execute` - "Execute"
> > > > * `sys_tm_start` - "Start"
> > > >
> > > > **Task Details Sections**
> > > >
> > > > * `sys_tm_assignee_deactivated` - "(Deactivated)"
> > > > * `sys_tm_comments` - "Comments"
> > > > * `sys_tm_write_a_comment` - "Write a comment…"
> > > > * `sys_tm_history` - "History"
> > > >
> > > > **History Events**
> > > >
> > > > * `sys_tm_task_created` - "Task created"
> > > > * `sys_tm_user_created_this_task` - "`${user}` created this task"
> > > > * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
> > > > * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
> > > > * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
> > > > * `sys_tm_task_moved_to` - "Task moved to"
> > > > * `sys_tm_task_status_changed_to` - "Task status changed to"
> > > > * `sys_tm_task_assigned_to` - "Task assigned to"
> > > > * `sys_tm_task_owner_removed` - "Task owner removed"
> > > >
> > > > **User Selection & Search**
> > > >
> > > > * `sys_tm_select_person` - "Select person..."
> > > > * `sys_tm_search_person` - "Search users"
> > > > * `sys_tm_search_term_validation` - "Type at least 4 characters..."
> > > >
> > > > **UI States**
> > > >
> > > > * `sys_tm_loading` - "Loading..."
> > > > * `sys_tm_nothing_found` - "Nothing Found"
> > > >
> > > > **Data Display**
> > > >
> > > > * `sys_tm_in` - "In" (custom filter operator)
> > > >
> > > > * `sys_tm_yes` - "Yes" (boolean value)
> > > >
> > > > * `sys_tm_no` - "No" (boolean value)
> > > >
> > > > > [!WARNING]
> > > > >
> > > > > **\*\*Manual Configuration Required**: These 51 FlowX substitution tags must be configured manually in CMS for each language. They control custom Task Management UI elements outside of the data table.
> >
> > > [tab] Implementation
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization (300+ keys for filters, menus, pagination, data types) based on this setting
> > >
> > > **2. Configure FlowX Substitution Tags in CMS**
> > >
> > > Add translations for all 51 FlowX substitution tags (sys\_tm\_\*) in CMS for each supported language. These control custom Task Management UI elements (task actions, bulk operations, history events, comments)
> > >
> > > **3. Configure Custom Column Names (Optional)**
> > >
> > > If you need custom columns beyond the defaults, use substitution tags for column display names in your Task Management configuration
> > >
> > > **4. Test Localization**
> > >
> > > Verify complete localization:
> > >
> > > * **Table grid elements** (automatic): filters, sorting, pagination, menus should display in container app language
> > >
> > > * **FlowX custom elements** (CMS): task actions, bulk operations, history events, comments should use your CMS translations
> > >
> > > > [!NOTE]
> > > >
> > > > **Simple Setup**: Configure only the 51 FlowX substitution tags in CMS. Table grid localization (300+ keys) is handled automatically by the platform.
> >
> > > [tab] Benefits
> > >
> > > > [card] Global Reach
> > > >
> > > > Deploy Task Management to users worldwide with native language support
> > >
> > > > [card] Consistent Experience
> > > >
> > > > Provide a fully localized experience across all Task Management components
> > >
> > > > [card] Easy Maintenance
> > > >
> > > > Manage translations centrally through CMS substitution tags
> > >
> > > > [card] Professional Quality
> > > >
> > > > Leverage professional translations for data grid components with automatic localization
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> > [card] [Task Management Overview](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
> >
> > Learn about Task Management features and configuration
>
> > [card] [Process Settings](../../../5.1/docs/building-blocks/process/process-definition#integrate-with-task-manager)
> >
> > Configure Task Management integration in process settings
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform Enhancements
> >
> > FlowX.AI 5.2.0 includes platform improvements focused on security, stability, and infrastructure.
> >
> > ## Security & Infrastructure Updates
> >
> > > [card] Vulnerability Fixes
> > >
> > > Update Java libraries and base images to address security vulnerabilities
> >
> > > [card] SpiceDB Upgrade
> > >
> > > Upgrade SpiceDB with new operator version
> >
> > > [card] Dependency Updates
> > >
> > > Update platform dependencies to latest secure versions
> >
> > ## Additional improvements
> >
> > > [card] Permission-based UI
> > >
> > > Add permission-based UI functionality in Reusable UI Templates
> >
> > > [card] Database Query Improvements
> > >
> > > Improve FlowX Database query handling and error messages
> >
> > > [card] System Substitution Tags
> > >
> > > Use system substitution tags in task management texts in CMS
> >
> > > [card] SSE Disconnect Handling
> > >
> > > Handle Server-Sent Events disconnections better to reduce log noise
> >
> > > [card] [Integration Designer Environment Variables](./update-environment-variables-5.2)
> > >
> > > Update environment variables for improved advancing controller with separate picking and processing operations, see details [here](./update-environment-variables-5.2)
> >
> > Platform Updates
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes & stability improvements
> >
> > FlowX.AI 5.2.0 includes bug fixes and stability improvements to improve the overall user experience.
> >
> > ## Notable fixes
> >
> > > [accordion] Fixes
> > >
> > > * **Process Instances Page**: Fix error when opening Runtime process instances page
> > > * **Resource Import**: Fix import requests that use incorrect content type
> > > * **Elasticsearch Updates**: Fix engine errors when updating documents in older indexes
> > > * **Navigation Tree**: Fix navigation tree response for overridden processes
> > > * **Dependency Management**: Fix errors when updating library dependency versions
> >
> > > [accordion] UI/UX fixes
> > >
> > > * **Accessibility**: Fix missing accessibility sections on various components
> > > * **Theme Configuration**: Fix element selection issues in segmented button panel
> > > * **Modal Behavior**: Improve modal focus management and keyboard navigation
> > > * **Select Components**: Fix highlighting and navigation issues in select/multiselect
> > > * **Task Manager**: Fix browser freeze when opening table configuration
> >
> > > [accordion] Renderer fixes
> > >
> > > * **Angular SDK**: Fix keyboard navigation issues with select components and shift+tab behavior
> > > * **React SDK**: Fix option highlighting and keyboard navigation in various components
> > > * **Workflow Display**: Fix rendering issues in Integration Designer workflows
> > > * **Collection Components**: Fix card expansion issues with accordions in navigation areas
> >
> > > [accordion] Backend fixes
> > >
> > > * **Events Gateway**: Improve SSE disconnect handling to reduce error log flooding
> > > * **Database Operations**: Improve error handling and validation for FlowX Database queries
> > > * **Process Navigation**: Fix back button redirects from process definitions
> > > * **Warning Management**: Clean up warnings properly when deleting parent actions

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.2.0](./deployment-guidelines-v5.2).
>
> ### Environment variables updates
>
> > [!NOTE]
> >
> > For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
>
> ### Coming soon
>
> Additional features currently in development for future releases:
>
> * Extended accessibility support for iOS and Android platforms
> * Additional Python IDE capabilities
> * Enhanced FlowX Database query preview and optimization tools


# Deployment guidelines v5.3.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/deployment-guidelines-v5.3

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.29.0** | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 |
| **admin** | **10.26.1** | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 |
| **designer** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **cms-core** | **10.16.0** | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 |
| **scheduler-core** | **10.11.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **events-gateway** | **10.12.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **notification-plugin** | **10.17.0** | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **document-plugin** | **10.16.0** | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 |
| **task-management-plugin** | **10.18.0** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 |
| **data-search** | **10.10.1** | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 |
| **audit-core** | **10.15.1** | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **advancing-controller** | **10.11.0** | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 |
| **integration-designer** | **10.24.0** | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 |
| **application-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **runtime-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **data-sync** | **10.14.1** | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 |
| **authorization-system** | **10.18.1** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - |
| **nosql-db-runner** | **10.10.1** | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **iOS renderer** | **10.1.0** | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 |
| **Android renderer** | **10.1.0** | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 |

### Plugins

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.1** | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 |
| **di-platform** | **10.2.5** | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 |
| **ai-platform-ai-developer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-connected-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agents** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-conversations** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-models** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-tenants** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-planner** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-analyst** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-designer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agent-builder** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-binaries** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.3.0 | Keycloak | 26+ |
| 5.3.0 | Kafka | 3.8 - 3.9 |
| 5.3.0 | PostgreSQL | 16 - 17 |
| 5.3.0 | Oracle Database | 21c, 23ai |
| 5.3.0 | MongoDB | 7 - 8 |
| 5.3.0 | Redis | 7.4 - 8.0 |
| 5.3.0 | Elasticsearch | 8 |
| 5.3.0 | Angular (Web SDK) | 19.2 |
| 5.3.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.3.0

### Key features and updates

> [card] UI Flows
>
> Build multi-platform applications with reusable UI components across web, iOS, and Android

> [card] UI Events
>
> Real-time user interaction handling with event-driven UI components

> [card] Workflow Data Models
>
> Workflow-level data models with input/output parameters and process-to-workflow data mapping

> [card] Mobile Accessibility
>
> WCAG 2.1 accessibility compliance extended to iOS and Android platforms

> [card] Custom Component Enhancements
>
> Standardized custom component integration across all platforms

> [card] SaaS Capabilities
>
> Multi-tenant SaaS capabilities with organization management

## Upgrading from v5.2.0

### Breaking changes

> [!WARNING]
>
> **FlowX Engine Configuration Changes**: The partitioning and archiving configuration structure has been reorganized. If you have enabled data partitioning, you **must** update your configuration files before or immediately after upgrading.

> [card] [Complete migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
>
> See the detailed migration guide with step-by-step instructions, configuration examples, and troubleshooting

### Key changes

* **UI Flows**: New feature for building multi-platform reusable UI components
* **Workflow Data Models**: Enhanced integration between processes and workflows with structured data models
* **Mobile Accessibility**: iOS and Android renderers now support WCAG 2.1 accessibility standards
* **Configuration Structure**: Breaking change in FlowX Engine partitioning/archiving configuration (see preceding section)

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.

### Compatibility

* **Breaking Changes**: FlowX Engine partitioning/archiving configuration structure has changed (action required if using partitioning)
* **Feature Additions**: UI Flows, UI Events, and Workflow Data Models are new features with no breaking changes
* **Renderer Updates**: Web and mobile SDKs include new features with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/migration-overview

Migration guide for upgrading from FlowX.AI v5.2.0 to v5.3.0

> [!NOTE]
>
> FlowX.AI v5.3.0 is an incremental update from v5.2.0 with one breaking change related to FlowX Engine configuration structure.

## What's changing

FlowX.AI v5.3.0 introduces a breaking change to the FlowX Engine partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings have been reorganized under `partitioning.archiving`.

## Who is affected

> [!WARNING]
>
> This breaking change **only affects** deployments that have:
>
> * Enabled data partitioning in FlowX Engine (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings (`SCHEDULER_DATAPARTITIONING_ENABLED=true`)
>
> If you have not enabled these features, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

## Migration process

**1. Review configuration changes**

Understand the new configuration structure and identify which settings need to be updated in your deployment

**2. Update configuration files**

Update your FlowX Engine configuration files (YAML or environment variables) following the migration steps

**3. Deploy and verify**

Deploy the updated configuration and verify that partitioning and archiving continue to work correctly

## Key changes summary

### Configuration structure

**What's removed:**

* `scheduler.dataPartitioning` section with `enabled` and `cronExpression` settings

**What's added:**

* `partitioning.archiving` subsection containing all archiving-related settings

**What's moved:**

* `retention-intervals` moved from `partitioning` to `partitioning.archiving`
* `detached-partition-compression` moved to `partitioning.archiving`
* `moved-data-batch-size` moved to `partitioning.archiving`
* `cronExpression` moved from `scheduler.dataPartitioning` to `partitioning.archiving`

### Environment variables

5 environment variables have been renamed to reflect the new structure:

| Old Variable | New Variable |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` |

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility**: The old configuration structure is not supported in v5.3.0 and causes FlowX Engine startup errors.
>
> You must update your configuration before or immediately after upgrading to v5.3.0.

## Rollback support

If you need to rollback from v5.3.0 to v5.2.x:

1. Revert your configuration files to the previous structure
2. Restore environment variables to their previous names
3. Downgrade the FlowX Engine container/pod to the previous version

> [!NOTE]
>
> Database schema changes are forward-compatible. Ensure you have database backups before any upgrade.

> [!NOTE]
>
> This is a configuration-only change. No code changes, data migration, or schema updates are required.

## Next steps

## Additional resources

> [card] [Partitioning & Archiving Setup](/5.1/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving)
>
> Complete guide to FlowX Engine partitioning and archiving

> [card] [Deployment Guidelines v5.3.0](../deployment-guidelines-v5.3)
>
> Component versions and deployment instructions

> [card] [Release Notes v5.3.0](../v5.3.0-december-2025)
>
> Full release notes for v5.3.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/update-environment-variables-5.3

Update environment variables for all existing FlowX.AI services

## FlowX Engine

### Partitioning and archiving configuration restructure

> [!NOTE]
>
> FlowX.AI v5.3.0 reorganizes the partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings are now under `partitioning.archiving`.

#### Variables to remove

If you are using environment variables to override FlowX Engine configuration, remove these variables:

| Remove This Variable | Reason |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |

#### Variables to replace

| Old Variable Name | New Variable Name | Default Value | Description |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of partition intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression level for archived partitions (Oracle only): `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for moving data during archiving (PostgreSQL only) |

#### New variables structure

The archiving configuration is now nested under `partitioning.archiving`:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Turn on or off data partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Partition interval: `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Turn on or off automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Schedule expression for archiving operations (default: daily at 1:00 AM) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression for archived partitions (Oracle only) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for data movement (PostgreSQL only) |

> [!NOTE]
>
> **Configuration structure changes:**
>
> * **Removed**: `scheduler.dataPartitioning` section
> * **Added**: `partitioning.archiving` subsection with all archiving-related settings
> * **Unchanged**: Core partitioning settings (`enabled`, `interval`) remain at `partitioning` level
> * **Moved**: Archiving-specific settings (`retention-intervals`, `cronExpression`, `detached-partition-compression`, `moved-data-batch-size`) are now under `partitioning.archiving`

> [!WARNING]
>
> **Action required if using partitioning:**
>
> If you have enabled data partitioning in FlowX Engine, you **must** update your configuration:
>
> 1. **YAML configuration**: Update your `application.yml` to follow the new structure (see [Deployment Guidelines](../deployment-guidelines-v5.3#breaking-changes))
> 2. **Environment variables**: Update variable names as shown in the tables above
> 3. **Deployment order**: Update configuration before or immediately after upgrading to v5.3.0

#### Configuration examples

> [tab] Environment Variables (Before)
>
> ```bash theme={"dark"}
> # Old structure (v5.2 and earlier)
> SCHEDULER_DATAPARTITIONING_ENABLED=true
> SCHEDULER_DATAPARTITIONING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS=3
> FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [tab] Environment Variables (After)
>
> ```bash theme={"dark"}
> # New structure (v5.3.0)
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true
> FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS=3
> FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [!NOTE]
>
> **Impact assessment:**
>
> This change only affects deployments that have:
>
> * Enabled data partitioning (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings
>
> If partitioning is disabled, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

### New optional variables

| Variable | Default Value | Description |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Falls back to `KAFKA_TOPIC_PATTERN` if not set | Dedicated topic pattern for FlowX connectors, separate from other platform components like document-plugin, data-search, and cms-core |

> [!NOTE]
>
> The `KAFKA_TOPIC_CONNECTOR_PATTERN` variable allows you to configure a custom Kafka topic pattern specifically for FlowX connectors without affecting other platform components.

> [card] [Complete migration guide](migration-overview)
>
> See the Deployment Guidelines for complete configuration examples, step-by-step migration instructions, and troubleshooting guidance.


# FlowX.AI 5.3.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025

UI Flows for multi-platform app building, UI Events for real-time interactions, enhanced custom component integration, and mobile accessibility improvements.

**What's new?**

> [tab] App builder & reusability
>
> Build multi-platform applications faster with UI Flows, enhance real-time interactions with UI Events, and integrate custom components across all platforms.
>
> 📱 [**UI Flows**](#ui-flows) - Build multi-platform applications with reusable UI components across web, iOS, and Android\
> ⚡  [**UI Events**](#ui-events) - Real-time user interaction handling with event-driven UI components\
> 🧩 [**Custom Component Enhancements**](#custom-component-enhancements) - Enhanced integration for custom components with standardized data mapping\
> 📤 [**File Upload Improvements**](#file-upload-improvements) - Enhanced file upload experience with better loading states and user feedback\
> ♿ [**Mobile Accessibility**](#mobile-accessibility) - WCAG 2.1 accessibility compliance for iOS and Android platforms\
> 🏢 [**Cross Workspace Projects**](#cross-workspace-projects) - Share projects across multiple workspaces for flexible environment testing\
> 🎯 [**Collection & Table Actions**](#collection-and-table-actions) - Execute actions from collections and tables in UI Flows
>
> ### **UI flows**
>
> > [card] UI flows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Flows, a powerful new capability that enables you to build reusable, multi-platform user interfaces that work across web (Angular/React), iOS, and Android applications. UI Flows separate UI definitions from process logic, enabling better reusability and faster application development without the overhead of full BPMN processes.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flows revolutionize how you build applications by allowing you to create a UI once and deploy it across all platforms, dramatically reducing development time and ensuring consistent user experiences.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Unnecessary process complexity
> > > >
> > > > Some use cases do not need a mapping of the business case in BPMN and the complexity and overhead that a FlowX process entails
> > >
> > > > [card] Subprocess overhead
> > > >
> > > > Unnecessary subprocess layers inside processes added complexity for simple UI scenarios
> > >
> > > > [card] Tight UI-process coupling
> > > >
> > > > UI definitions were tightly coupled to process logic, reducing reusability and increasing maintenance
> > >
> > > > [card] Platform-specific development
> > > >
> > > > Building the same UI for multiple platforms required separate implementations for each platform
> >
> > > [tab] Key Features
> > >
> > > > [card] UI Flows as project resources
> > > >
> > > > UI Flows are managed as independent project resources, separate from process definitions
> > >
> > > > [card] Navigation areas management
> > > >
> > > > Manage Navigation Areas inside UI Flows Designer for structured navigation and layout
> > >
> > > > [card] Start process UI action
> > > >
> > > > Launch FlowX processes directly from UI Flows, bridging UI and process execution
> > >
> > > > [card] Navigate to UI action
> > > >
> > > > Setup navigation to Nav areas or Container elements through scroll for seamless UX
> > >
> > > > [card] Task Manager component
> > > >
> > > > Embed Task Manager as a UI Component in UI Flows for task management capabilities
> > >
> > > > [card] Multi-platform support
> > > >
> > > > Create UI once and deploy to web (Angular/React), iOS, and Android with platform-specific configurations
> > >
> > > > [card] Import/export
> > > >
> > > > Export UI Flows as portable packages and import them across environments and applications
> > >
> > > > [card] Platform selection
> > > >
> > > > Configure platform-specific behaviors and overrides for web, iOS, and Android in the UI Flows designer
> > >
> > > > [card] Home page support
> > > >
> > > > Create UI Flows with dedicated home pages and home navigation icons for better UX
> >
> > > [tab] How It Works
> > >
> > > **1. Create UI flow**
> > >
> > > Create a UI Flow as a project resource in FlowX Designer, separate from process definitions
> > >
> > > **2. Design navigation**
> > >
> > > Manage Navigation Areas inside UI Flows Designer, defining pages and navigation structure
> > >
> > > **3. Add components**
> > >
> > > Add UI components including Task Manager, forms, custom components, and other UI elements
> > >
> > > **4. Configure actions**
> > >
> > > Setup UI Actions like Start Process (to launch processes) and Navigate To (for Nav areas or container scrolling)
> > >
> > > **5. Configure platforms**
> > >
> > > Set platform-specific configurations using the platform selection subheader (Web, iOS, Android)
> > >
> > > **6. Set home page**
> > >
> > > Designate a page as the home page with automatic home icon navigation support
> > >
> > > **7. Export & reuse**
> > >
> > > Export your UI Flow and import it into other applications or environments for maximum reusability
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced complexity
> > > >
> > > > Build UIs without the overhead of BPMN processes for use cases that don't require business process mapping
> > >
> > > > [card] Faster development
> > > >
> > > > Build UI once instead of creating separate interfaces for each platform
> > >
> > > > [card] Flexible architecture
> > > >
> > > > Eliminate unnecessary subprocess layers - use UI Flows for simple scenarios and processes for complex business logic
> > >
> > > > [card] Consistent UX
> > > >
> > > > Ensure identical user experiences across web, iOS, and Android applications
> > >
> > > > [card] Reusability
> > > >
> > > > Share UI Flows across multiple applications and projects
> > >
> > > > [card] Process integration
> > > >
> > > > Launch processes from UI Flows when needed, maintaining clean separation of concerns
> > >
> > > > [card] Maintainability
> > > >
> > > > Update UI in one place and propagate changes across all platforms
> > >
> > > > [card] Enhanced navigation
> > > >
> > > > Rich navigation capabilities with Nav areas, container scrolling, and Task Manager integration
> >
> > > [tab] Use Cases
> > >
> > > **When to Use UI Flows vs Processes:**
> > >
> > > **Use UI Flows for:**
> > >
> > > * **Information Display**: Dashboards, reports, and static content that doesn't require process orchestration
> > > * **Task Management**: Task lists and task management interfaces with embedded Task Manager component
> > > * **Navigation Shells**: Application navigation structures and home pages
> > > * **Form Collections**: Data entry forms that start processes but don't need their own process context
> > > * **Multi-Platform Apps**: Applications that need consistent UI across web and mobile platforms
> > >
> > > **Use Processes for:**
> > >
> > > * **Business Logic**: Complex workflows with business rules, approvals, and integrations
> > > * **State Management**: Applications requiring process state tracking and persistence
> > > * **Orchestration**: Multi-step operations with decision points and parallel execution
> > >
> > > **Combine Both:**
> > >
> > > Create UI Flows as the main application shell and use Start Process UI Actions to launch business processes when needed, keeping your architecture clean and maintainable.
> >
> > > [card] [UI Flows Documentation](/5.9/docs/building-blocks/ui-flows)
> > >
> > > Complete guide to creating and configuring UI Flows, including navigation management, UI actions, and platform considerations.
> >
> > Major Feature
>
> ***
>
> ### **UI events**
>
> > [card] UI events
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Events, enabling real-time interaction handling directly within Reusable UI Templates. UI Events allow you to capture user interactions like button clicks, form changes, or custom events and respond immediately without process execution, providing responsive and dynamic user experiences.
> >
> > > [tab] Key Features
> > >
> > > > [card] Event configuration
> > > >
> > > > Configure UI Events in UI Designer with custom event types and handling logic
> > >
> > > > [card] Cross-platform support
> > > >
> > > > UI Events work consistently across Angular, React, iOS, and Android renderers
> > >
> > > > [card] Runtime mapping
> > > >
> > > > UI Event results are mapped automatically in Reusable UI Template instances at runtime
> > >
> > > > [card] Design-time testing
> > > >
> > > > Test UI Events directly in UI Designer before deploying to runtime
> >
> > > [tab] Use Cases
> > >
> > > > [card] Form validation
> > > >
> > > > Validate form inputs in real-time as users type, providing immediate feedback
> > >
> > > > [card] Dynamic UI updates
> > > >
> > > > Show/hide fields, update options, or change UI state based on user interactions
> > >
> > > > [card] Client-side logic
> > > >
> > > > Execute lightweight client-side logic without triggering backend processes
> > >
> > > > [card] Responsive interactions
> > > >
> > > > Create highly responsive UI behaviors like autocomplete, live search, or conditional displays
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Handle UI interactions instantly without waiting for backend process execution
> > >
> > > **2. User experience**
> > >
> > > Provide immediate visual feedback and responsive interactions
> > >
> > > **3. Reduced complexity**
> > >
> > > Simplify process logic by handling UI-specific interactions at the component level
> >
> > UX Enhancement
>
> ***
>
> ### **Custom component enhancements**
>
> > [card] Custom component enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 standardizes custom component integration across all platforms (Angular, React, iOS, Android) with unified data mapping for input keys, data binding, save operations, and action handling. This provides a consistent developer experience when building custom components.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified data mapping
> > > >
> > > > Standard data, saveData, and action body mapping across all platforms
> > >
> > > > [card] Input key mapping
> > > >
> > > > Consistent input key handling for passing configuration and data to custom components
> > >
> > > > [card] Platform parity
> > > >
> > > > Identical custom component APIs across Angular, React, iOS, and Android
> > >
> > > > [card] Action integration
> > > >
> > > > Integration with FlowX actions for triggering backend operations
> >
> > > [tab] Benefits
> > >
> > > **1. Developer productivity**
> > >
> > > Build custom components once with knowledge that applies across all platforms
> > >
> > > **2. Code reusability**
> > >
> > > Share component logic and patterns across web and mobile implementations
> > >
> > > **3. Consistency**
> > >
> > > Ensure consistent behavior and data handling across all platforms
> >
> > Developer Experience
>
> ***
>
> ### **File upload improvements**
>
> > [card] File upload improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the file upload experience across all platforms with improved loading states, better user feedback, and more flexible configuration options. These improvements provide clearer status communication during file upload operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Enhanced loading behavior
> > > >
> > > > Configure loading behavior with optional overlay loader and custom loading messages
> > >
> > > > [card] Toast notifications
> > > >
> > > > Success and error messages displayed as toasts with customizable messages
> > >
> > > > [card] Dynamic messages
> > > >
> > > > Display dynamic key values in toast and loading messages for context-aware feedback
> > >
> > > > [card] Generic loader design
> > > >
> > > > Updated loader designs across Angular, React, iOS, and Android for consistent theming
> >
> > > [tab] Configuration
> > >
> > > **Loading Behavior Options:**
> > >
> > > * **NONE**: No loading overlay displayed during upload
> > > * **OVERLAY**: Full-screen overlay with spinner and optional loading message
> > >
> > > **Toast Notifications:**
> > >
> > > * **Success Toast**: Toggle to show success message when upload completes (auto-dismiss after 3-5 seconds)
> > > * **Error Toast**: Toggle to show error message when upload fails (auto-dismiss after 3-5 seconds)
> > > * **Custom Messages**: Configure success and error messages with dynamic substitutions
> > >
> > > **Theming Support:**
> > >
> > > * Apply custom themes to loaders and toast messages
> > > * Configure colors, sizes, and styling to match your brand
> > > * Consistent visual language across platforms
> >
> > UX Enhancement
>
> ***
>
> ### **Mobile accessibility**
>
> > [card] Mobile accessibility
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 extends WCAG 2.1 accessibility compliance to iOS and Android platforms, allowing you to configure accessibility properties directly from UI Designer and ensuring your mobile applications are accessible to all users.
> >
> > > [tab] Key Features
> > >
> > > > [card] iOS accessibility
> > > >
> > > > Configure labels, hints, traits, and accessibility properties for iOS components
> > >
> > > > [card] Android accessibility
> > > >
> > > > Set content descriptions and accessibility properties for Android components
> > >
> > > > [card] Designer integration
> > > >
> > > > Configure all accessibility properties from UI Designer without code changes
> > >
> > > > [card] Platform-specific options
> > > >
> > > > Set platform-specific accessibility configurations for optimal native experience
> >
> > > [tab] Benefits
> > >
> > > > [card] Inclusive mobile apps
> > > >
> > > > Make your mobile applications accessible to users with disabilities
> > >
> > > > [card] Regulatory compliance
> > > >
> > > > Meet mobile accessibility requirements for government, healthcare, and financial sectors
> > >
> > > > [card] Better UX
> > > >
> > > > Accessibility improvements benefit all users, not just those using assistive technologies
> > >
> > > > [card] Unified configuration
> > > >
> > > > Configure accessibility for all platforms from a single Designer interface
> >
> > Accessibility
>
> ***
>
> ### **Cross workspace projects**
>
> > [card] Cross workspace projects
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 removes the restriction that prevented importing the same project into multiple workspaces within the same environment. This enables organizations to use workspaces to represent different upper environments (UAT, Staging) for testing and development.
> > >
> > > > [!NOTE]
> > > >
> > > > A single project (identified by its UUID) can now exist independently across workspaces, each with its own lifecycle: separate active policies, configurations, and access controls.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Environment testing restrictions
> > > >
> > > > Organizations could not use workspaces on the same FlowX deployment to represent different upper environments for testing (e.g. UAT, Staging)
> > >
> > > > [card] Operational costs
> > > >
> > > > This feature is intended to allow organizations to use workspace functionality to emulate different environments and reduce operational costs.
> >
> > > [tab] Solution
> > >
> > > **What Changed:**
> > >
> > > **1. Restriction removed**
> > >
> > > The system now allows importing the same project (identified by UUID) into multiple workspaces within the same environment
> > >
> > > **2. Independent lifecycles**
> > >
> > > Each project instance in different workspaces maintains its own independent lifecycle with separate active policies, configurations, and access controls
> > >
> > > **3. Workspace isolation**
> > >
> > > Changes in one workspace do not affect the same project in other workspaces, ensuring proper isolation
> >
> > > [tab] How It Works
> > >
> > > **Import Behavior:**
> > >
> > > | Aspect | Behavior |
> > > | - | - |
> > > | **Import** | Import a project build (and optionally a version) into a different workspace on the same environment |
> > > | **Active Policy** | The imported build is automatically set as the active policy, regardless of what was active in the original workspace |
> > > | **User Access** | Workspace users must be granted appropriate project rights (e.g., project viewer) to interact with the imported project |
> > > | **Process Instances** | Workspace-specific; imported projects start with no instances until processes run in the new workspace |
> > > | **Database** | Projects across workspaces on the same environment share the same database |
> > > | **No Impact on Original** | Import does not affect the original project's settings, policies, information, or process instances |
> > >
> > > > [!WARNING]
> > > >
> > > > Only the build itself is transferred during cross-workspace import. Configuration and access controls are defined separately in each workspace.
> >
> > > [tab] Benefits
> > >
> > > > [card] Flexible testing environments
> > > >
> > > > Use workspaces to represent UAT, Staging, and other test environments on the same deployment
> > >
> > > > [card] Reduced costs
> > > >
> > > > Eliminate the need for additional deployments and DevOps resources for environment management
> > >
> > > > [card] Better organization
> > > >
> > > > Organize projects and environments more efficiently with workspace-based separation
> > >
> > > > [card] Independent control
> > > >
> > > > Maintain separate policies and configurations for each workspace while using the same project
> > >
> > > > [card] Simplified operations
> > > >
> > > > Streamline deployment and environment management workflows
> > >
> > > > [card] Faster environment setup
> > > >
> > > > Quickly create new test environments by importing existing projects into new workspaces
> >
> > > [tab] Use Cases
> > >
> > > **Example Scenarios:**
> > >
> > > 1. **Multi-Environment Testing**: Import the same project into UAT and Staging workspaces, each with different test data and configurations
> > >
> > > 2. **Development Lifecycle**: Maintain development, integration, and pre-production environments as separate workspaces with the same project
> > >
> > > 3. **Parallel Testing**: Run multiple test scenarios simultaneously by creating separate workspaces for each testing team
> > >
> > > 4. **Isolated Training Environments**: Create dedicated workspaces for training and demos while keeping production separate
> >
> > > [card] [Workspaces Documentation](/5.1/docs/projects/workspaces#cross-workspace-project-import)
> > >
> > > Complete guide to cross-workspace project import, including import behavior and best practices.
> >
> > Reusability Enhancement
>
> ***
>
> ### **Collection and table actions**
>
> > [card] Collection and table actions
> >
> > FlowX.AI 5.3 enables executing actions directly from collection and table rows within UI Flows across Angular and React platforms, providing contextual user interactions within data-driven UI Flow components.
> >
> > > [card] Row-level actions
> > >
> > > Configure and trigger actions with row context for edit, delete, or start process operations in UI Flows
> >
> > > [card] Cross-platform support
> > >
> > > Works in both Angular and React web renderers for UI Flows
> >
> > UI Flows
>
> ***

> [tab] Integration & data
>
> Enhanced workflow integration, data model management, and backend performance improvements.
>
> 🔄 [**Data mappers for workflow integration**](#data-mappers-for-workflow-integration) - Data mappers for workflow integration\
> 🗄️ [**Workflow data model**](#workflow-data-model) - New CRUD endpoints and runtime data model access\
> 🤖 [**MCP Integration**](#mcp-integration) - Connect AI agents with external tools and services through Model Context Protocol servers\
> 🤖 [**Custom Agent Nodes**](#custom-agent-nodes) - Custom Agent nodes for AI agents to use external tools and services
> 📚 [**Knowledge Base**](#knowledge-base) - Create and manage Knowledge Bases for AI agents with document ingestion and semantic search\
> 🔧 [**Update process variables**](#update-process-variables) - Operations teams can modify process variables on active instances to resolve production issues\
> 🔍 [**Token view improvements**](#token-view-improvements) - Enhanced token hierarchy visibility with horizontal scrolling, frozen columns, and context-aware columns\
> 🛡️ [**Access management enhancements**](#access-management-enhancements) - New operations editor role and granular workspace permissions\
> ⚡ [**Performance & stability**](#performance-and-stability) - Backend optimizations, caching improvements, and infrastructure updates\
> 🔀 [**Exclusive Gateways**](#exclusive-gateways) - Expression testing and validation improvements
>
> ### **Data mappers for workflow integration**
>
> > [card] Data mappers for workflow integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces data mappers that enable integration between processes and Integration Designer workflows. Similar to Process Definitions, you can now define structured data models at the workflow level with input and output parameters, ensuring consistent data lineage across your integration architecture.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
> > >
> > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process-workflow.png)
> > >
> > > Map data bidirectionally between processes and workflows using data mappers
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow Data Models provide the same structured data management capabilities as Process Data Models, enabling declarative data mapping between workflows and processes with full type safety and validation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow data model
> > > >
> > > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > > [card] Input parameter management
> > > >
> > > > Input parameters automatically pre-fill Start Nodes with structured data from the workflow data model
> > >
> > > > [card] Data parameters
> > > >
> > > > Use data parameters to define input and output data subsets for workflow operations
> > >
> > > > [card] Process ↔ workflow mapping
> > > >
> > > > Create data mappers on nodes to receive outputs from workflows and map data bidirectionally
> > >
> > > > [card] Generic CRUD endpoints
> > > >
> > > > Manage data models, entities, attributes, and data parameters programmatically via REST APIs
> > >
> > > > [card] Unique node validation
> > > >
> > > > Automatic node name uniqueness validation within workflow definitions to ensure clear data lineage
> >
> > > [tab] How It Works
> > >
> > > **1. Define workflow data model**
> > >
> > > Create a data model for your workflow with entities and attributes, similar to Process Data Models. Define which parameters are inputs and outputs
> > >
> > > **2. Configure input parameters**
> > >
> > > Input parameters automatically pre-fill the Start Node when you open the workflow diagram or test at runtime. No manual JSON editing required
> > >
> > > **3. Map process to workflow**
> > >
> > > When invoking a workflow from a process, create data mappers to map process data to workflow input parameters
> > >
> > > **4. Map workflow to process**
> > >
> > > Configure output mappings on nodes to receive workflow results and map them back to process data
> >
> > > [tab] Data Model Management
> > >
> > > **New API Capabilities:**
> > >
> > > * **Data Model CRUD**: Create, read, update, and delete workflow data models
> > > * **Entity Management**: Add, modify, and remove entities within data models
> > > * **Attribute Management**: Define and manage attributes with types and validation rules
> > > * **Data Parameters Operations**: Create input and output data parameters for workflows
> > > * **Usage Tracking**: Query references and usages for attributes and entities
> > > * **Import/Export**: Export and import complete data models across environments
> > >
> > > **Technical Implementation:**
> > >
> > > * Centralized data model library for common classes and interfaces
> > > * Generic endpoints for data model and data parameters manipulation
> > > * Integration Designer communicates with Admin service for data model operations
> > > * Automatic input body computation based on data model input parameters
> > > * Runtime workflow start data endpoint for testing and execution
> >
> > > [tab] Limitations & Compatibility
> > >
> > > **Current Limitations:**
> > >
> > > * **Start Subworkflow Node**: Works as-is without data model integration in this release
> > > * **Endpoint Schemas**: Imported Swagger schemas are not yet integrated with workflow data models (planned for future release)
> > > * **Database Schemas**: Database operation schemas are not mapped to workflow variables yet (planned for future release)
> > >
> > > **Backwards Compatibility:**
> > >
> > > * Existing workflows continue to work without changes
> > > * End nodes from existing workflows can be renamed manually to align with output parameters
> > > * No breaking changes to current workflow execution
> > >
> > > **Node Naming:**
> > >
> > > * Node names must be unique within a workflow definition
> > > * System automatically validates uniqueness when renaming nodes
> > > * If duplicate names exist, an index is incremented (e.g., "Transform", "Transform\_2")
> >
> > > [tab] Benefits
> > >
> > > > [card] Consistent data lineage
> > > >
> > > > Ensure data consistency across processes and workflows with structured data models
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Input parameters automatically pre-fill Start Nodes - no manual JSON editing
> > >
> > > > [card] Type safety
> > > >
> > > > Define data types and validation rules at the workflow level for runtime safety
> > >
> > > > [card] Reusability
> > > >
> > > > Create reusable workflows with clear input/output contracts that can be invoked from multiple processes
> > >
> > > > [card] Better testing
> > > >
> > > > Test workflows with structured input data based on the data model
> > >
> > > > [card] Clear interfaces
> > > >
> > > > Workflow data models document the expected inputs and outputs for each workflow
> >
> > > [card] [Workflow Data Models Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> > >
> > > Complete guide to creating workflow data models, input/output parameters, process integration, and API reference.
> >
> > Integration Designer
>
> ***
>
> ### **Workflow data model**
>
> > [card] Workflow data model
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 adds comprehensive workflow data model management capabilities with new CRUD endpoints and runtime access to data model paths. This enables dynamic data model operations and better runtime introspection.
> >
> > > [tab] Key Features
> > >
> > > > [card] CRUD endpoints
> > > >
> > > > Create, read, update, and delete workflow data models programmatically via REST APIs
> > >
> > > > [card] Data model paths
> > > >
> > > > Runtime endpoint for retrieving workflow data model paths and structure information
> > >
> > > > [card] RUT instance mappings
> > > >
> > > > Enhanced /status and /details endpoints with mappings per workflow instance
> > >
> > > > [card] Runtime caching
> > > >
> > > > Improved caching for reusable templates to reduce latency and improve performance
> >
> > > [tab] Use Cases
> > >
> > > > [card] Dynamic forms
> > > >
> > > > Build dynamic forms based on data model structure at runtime
> > >
> > > > [card] Data migration
> > > >
> > > > Automate data model synchronization across environments
> > >
> > > > [card] Documentation
> > > >
> > > > Generate data model documentation automatically from API responses
> > >
> > > > [card] Validation
> > > >
> > > > Implement runtime validation based on data model definitions
> >
> > API Enhancement
>
> ***
>
> ### **MCP integration**
>
> > [card] MCP integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Model Context Protocol (MCP) integration, enabling AI agents to connect with external MCP servers and use their tools within Custom Agent nodes. MCP provides a standardized protocol for AI agents to access external tools, databases, APIs, and services.
> > >
> > > > [!NOTE]
> > > >
> > > > MCP integration extends AI agent capabilities by providing access to external tools through a standardized protocol. Configure MCP servers as data sources in Integration Designer and use their tools in workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] MCP data sources
> > > >
> > > > Add MCP servers as data sources in Integration Designer with base URL and authentication configuration
> > >
> > > > [card] Tool management
> > > >
> > > > View, enable, and turn off specific tools exposed by MCP servers directly from Integration Designer
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Select MCP servers in Custom Agent nodes to make their tools available to AI agents during workflow execution
> > >
> > > > [card] Authentication support
> > > >
> > > > Support for no authentication and OAuth 2.0 service account authentication methods
> > >
> > > > [card] Tool discovery
> > > >
> > > > Automatic tool discovery from MCP servers with schema information for inputs and outputs
> > >
> > > > [card] Execution monitoring
> > > >
> > > > Track tool usage and execution details in console logs for debugging and monitoring
> >
> > > [tab] How It Works
> > >
> > > **1. Add MCP server**
> > >
> > > Configure an MCP server as a data source in Integration Designer with base URL and authentication details
> > >
> > > **2. Authenticate connection**
> > >
> > > Set up authentication using no authentication (for development) or OAuth 2.0 service account (for production)
> > >
> > > **3. Discover tools**
> > >
> > > View available tools exposed by the MCP server with their input/output schemas
> > >
> > > **4. Enable tools**
> > >
> > > Enable or turn off specific tools based on your workflow requirements
> > >
> > > **5. Configure custom agent**
> > >
> > > Add a Custom Agent node to your workflow and select which MCP servers the agent can access
> > >
> > > **6. Execute workflow**
> > >
> > > AI agents can now use MCP tools during workflow execution to interact with external systems
> > >
> > > **7. Monitor execution**
> > >
> > > View tool usage and execution details in console logs for debugging and performance tracking
> >
> > > [tab] Authentication
> > >
> > > **Supported Authentication Methods:**
> > >
> > > **None**
> > >
> > > * No authentication required
> > > * Use for public MCP servers or development environments
> > > * Quick setup for testing and prototyping
> > >
> > > **Service Account (OAuth 2.0)**
> > >
> > > * OAuth 2.0 service account authentication
> > > * Required configuration:
> > >   * **Client ID**: OAuth client identifier
> > >   * **Client Secret**: OAuth client secret
> > >   * **Identity Provider URL**: Authorization server endpoint
> > > * Use for production environments
> > > * Secure access to MCP servers
> >
> > > [tab] Use Cases
> > >
> > > > [card] External API integration
> > > >
> > > > Connect AI agents to external APIs and services for data retrieval and action execution
> > >
> > > > [card] Database operations
> > > >
> > > > Query databases and perform data operations through MCP tools within AI workflows
> > >
> > > > [card] Custom business logic
> > > >
> > > > Expose custom business logic as MCP tools for AI agents to execute
> > >
> > > > [card] Multi-system orchestration
> > > >
> > > > Use multiple MCP servers in a single Custom Agent node to orchestrate operations across systems
> >
> > > [tab] Benefits
> > >
> > > > [card] Standardized integration
> > > >
> > > > Use a standardized protocol for AI agent tool integration across different systems
> > >
> > > > [card] Extended capabilities
> > > >
> > > > Extend AI agent capabilities with external tools without custom code
> > >
> > > > [card] Flexible tool management
> > > >
> > > > Enable or turn off specific tools per MCP server based on workflow needs
> > >
> > > > [card] Secure connections
> > > >
> > > > Support for OAuth 2.0 authentication ensures secure access to external services
> > >
> > > > [card] Tool reusability
> > > >
> > > > Configure MCP servers once and use their tools across multiple workflows and Custom Agent nodes
> > >
> > > > [card] Monitoring & debugging
> > > >
> > > > Console logs provide visibility into tool execution for troubleshooting and optimization
> >
> > > [card] [MCP Integration Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> > >
> > > Complete guide to MCP integration including data source configuration, tool management, and Custom Agent node usage.
> >
> > AI Integration
>
> ***
>
> ### **Custom Agent nodes**
>
> > [card] Custom Agent nodes
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Custom Agent nodes, enabling you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
> >
> > > [card] [Custom Agent Node Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > Complete guide to Custom Agent nodes, including configuration, usage, and best practices.
> >
> > AI Integration
>
> ***
>
> ### **Knowledge base**
>
> > [card] Knowledge base
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Knowledge Base integration, enabling you to create and manage centralized repositories of information that AI agents can query when preparing responses. Upload static documents or ingest dynamic data from workflows into Knowledge Bases that use vector embeddings and semantic search for intelligent information retrieval.
> > >
> > > > [!NOTE]
> > > >
> > > > Knowledge Bases enable AI agents to provide contextual, accurate responses based on your organization's documentation, policies, and dynamic data.
> >
> > > [tab] Key Features
> > >
> > > > [card] Document upload
> > > >
> > > > Upload PDF documents directly into Knowledge Bases for AI agent access
> > >
> > > > [card] Workflow ingestion
> > > >
> > > > Ingest data dynamically from workflows using Knowledge Base operations (Append, Replace, Delete)
> > >
> > > > [card] Semantic search
> > > >
> > > > AI agents find relevant information using natural language queries with vector embeddings
> > >
> > > > [card] Content sources
> > > >
> > > > Organize content across multiple sources within a Knowledge Base for better management
> > >
> > > > [card] Relevance scoring
> > > >
> > > > Configure minimum relevance thresholds (0-100%) to control response quality
> > >
> > > > [card] Testing capabilities
> > > >
> > > > Test queries and operations in isolation before adding them to production workflows
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Enable Knowledge Base queries in Custom Agent nodes with configurable parameters
> > >
> > > > [card] Content versioning
> > > >
> > > > Append, replace, or delete content sources with full traceability and state management
> >
> > > [tab] How It Works
> > >
> > > **1. Create Knowledge Base**
> > >
> > > Add a new Knowledge Base data source in Integration Designer
> > >
> > > **2. Ingest content**
> > >
> > > Upload PDF documents or ingest data from workflows into content sources
> > >
> > > **3. Automatic chunking**
> > >
> > > Content is automatically split into chunks and indexed in the vector database
> > >
> > > **4. Configure Custom Agent**
> > >
> > > Enable Knowledge Base in Custom Agent nodes and configure query parameters
> > >
> > > **5. Query execution**
> > >
> > > AI agents query the Knowledge Base using semantic search and receive relevant chunks
> > >
> > > **6. Response generation**
> > >
> > > Agents use retrieved chunks as context to generate accurate, informed responses
> >
> > > [tab] Workflow Operations
> > >
> > > **Knowledge Base operations available in workflows:**
> > >
> > > | Operation | Description |
> > > | - | - |
> > > | **Append** | Add new content to an existing content source without removing existing data |
> > > | **Replace** | Delete all existing content and replace with new content |
> > > | **Delete** | Remove all content from a content source |
> > >
> > > **Configuration Options:**
> > >
> > > * **Knowledge Base**: Select from local project libraries or dependencies
> > > * **Content Source**: Use existing sources, create new ones, or use workflow variables
> > > * **Content**: Static text, workflow variables, or configuration parameters
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product documentation assistant
> > > >
> > > > Create Knowledge Bases with product documentation for AI agents to answer customer questions
> > >
> > > > [card] Policy compliance
> > > >
> > > > Upload company policies so AI agents can reference them when processing requests
> > >
> > > > [card] Dynamic knowledge updates
> > > >
> > > > Ingest data from external systems through workflows to keep AI knowledge current
> > >
> > > > [card] Multi-source synthesis
> > > >
> > > > Organize information across sources and let AI agents synthesize comprehensive answers
> >
> > > [tab] Benefits
> > >
> > > > [card] Contextual AI responses
> > > >
> > > > AI agents provide accurate responses based on your organization's actual documentation
> > >
> > > > [card] Dynamic updates
> > > >
> > > > Keep AI knowledge current by ingesting data from workflows automatically
> > >
> > > > [card] Quality control
> > > >
> > > > Relevance scoring ensures only high-quality, relevant information is used
> > >
> > > > [card] Centralized management
> > > >
> > > > Manage all AI knowledge sources from a single location in Integration Designer
> > >
> > > > [card] No code integration
> > > >
> > > > Configure Knowledge Base queries directly in Custom Agent nodes without code
> > >
> > > > [card] Testable
> > > >
> > > > Test queries and see relevance scores before deploying to production
> >
> > > [tab] Limitations
> > >
> > > **Current Limitations:**
> > >
> > > > [!WARNING]
> > > >
> > > > * Only PDF documents are supported for manual upload (images, PPT, DOC, XLS support coming in future releases)
> > > > * Custom metadata cannot be defined (only system metadata is available)
> > > > * AI agents can only use one Knowledge Base per Custom Agent node
> > > > * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
> >
> > > [card] [Knowledge Base Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > Complete guide to creating Knowledge Bases, ingesting content, and using them in Custom Agent workflows.
> >
> > AI Integration
>
> ***
>
> ### **Update process variables**
>
> > [card] Update process variables
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces the ability for operations teams to modify process variables on active (Started or On Hold) process instances, providing critical tools to resolve production issues without process restarts. Edit, add, or delete attributes and objects directly using an editor with JSON validation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Formatting%20_%20Custom%20Date%20Format.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Tokens%20table.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > > [!NOTE]
> > > >
> > > > Updated values automatically sync to Task Manager and Elasticsearch, ensuring consistency across all systems. Previous values are saved in a snapshot table, and all modifications are tracked in the audit log for complete traceability.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Limited correction tools
> > > >
> > > > Operations teams had minimal tools to correct production issues at the process-instance level
> > >
> > > > [card] Blocked instances
> > > >
> > > > No way to unblock stuck process instances without backend intervention or process restarts
> > >
> > > > [card] Data correction challenges
> > > >
> > > > Incorrect process data required complex workarounds or manual database modifications
> > >
> > > > [card] Operational delays
> > > >
> > > > Production issues required developer intervention, increasing resolution time
> >
> > > [tab] Key Features
> > >
> > > > [card] Editor
> > > >
> > > > Edit process variables in a JSON editor with syntax validation and formatting
> > >
> > > > [card] Multiple entry points
> > > >
> > > > Access from Process Instances page contextual menu or Process Instance page secondary navigation
> > >
> > > > [card] Dual view modes
> > > >
> > > > Switch between Tree View (existing) and JSON View for variable visualization and editing
> > >
> > > > [card] Full CRUD operations
> > > >
> > > > Edit existing attribute values, add new attributes/objects, or delete existing attributes/objects
> > >
> > > > [card] JSON validation
> > > >
> > > > Automatic JSON format validation before saving to ensure data integrity
> > >
> > > > [card] Snapshot history
> > > >
> > > > Previous process variables are saved in a new snapshot table before changes are applied
> > >
> > > > [card] Auto-sync to Task Manager
> > > >
> > > > Updated variables automatically sync to Task Manager using existing mechanism
> > >
> > > > [card] Elasticsearch integration
> > > >
> > > > Process variables configured for data search are automatically updated in Elasticsearch
> > >
> > > > [card] Permission-based access
> > > >
> > > > Role-based access control with process\_variables\_edit permission ensures only authorized users can modify variables
> > >
> > > > [card] Export functionality
> > > >
> > > > Export button available near the view dropdown for downloading process variables
> > >
> > > **Iteration 2 - Enhanced Review:**
> > >
> > > > [card] Compare feature
> > > >
> > > > Ability to review updated process variables through a compare feature, showing before/after values for better visibility and validation
> >
> > > [tab] How It Works
> > >
> > > **Accessing the Feature:**
> > >
> > > You can access the edit functionality from two entry points:
> > >
> > > 1. **Process Instances Page**: Use contextual menu on a process instance row → navigates to Process Instance page and opens Variables tab in edit mode
> > > 2. **Process Instance Page**: Use contextual menu in secondary navigation → opens Variables tab in edit mode
> > >
> > > **Editing Process Variables:**
> > >
> > > **1. Select active instance**
> > >
> > > Choose an active process instance (Started or On Hold status) that requires variable modification
> > >
> > > **2. Switch to JSON view**
> > >
> > > In the Variables tab, switch from Tree View to JSON View using the view dropdown
> > >
> > > **3. Click edit**
> > >
> > > Click the Edit button (visible only if you have process\_variables\_edit permission)
> > >
> > > **4. Modify in editor**
> > >
> > > Edit process variables in the JSON editor - you can edit existing values, add new attributes/objects, or delete existing ones
> > >
> > > **5. Validate JSON**
> > >
> > > Ensure your JSON format is valid before saving - the editor will highlight syntax errors
> > >
> > > **6. Save changes**
> > >
> > > Click Save to apply changes - a snapshot of previous values is automatically created
> > >
> > > **7. Auto-sync**
> > >
> > > System automatically syncs updated variables to Task Manager and Elasticsearch (for variables configured for data search)
> > >
> > > **8. Review audit log**
> > >
> > > Check the Audit Log tab to confirm the modification was recorded with all details
> >
> > > [tab] Permissions & Security
> > >
> > > **Permission Requirements:**
> > >
> > > * **New Permission**: `process_variables_edit` available at workspace level
> > > * **Default Roles**: Added to `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, and `workspace_operations_editor` roles
> > > * **New Role**: `workspace_operations_editor` - A dedicated workspace role for operations management including process variable editing and operations (migration & move token)
> > >
> > > **Access Control:**
> > >
> > > * Edit option in UI is only visible to users with `process_variables_edit` permission
> > > * Save functionality is restricted to users with the required permission
> > > * Unauthorized users can view process variables but cannot modify them
> > >
> > > **Audit Logging:**
> > >
> > > Every process variable modification creates an audit log entry with:
> > >
> > > * Workspace ID
> > > * Feature: Process variables
> > > * Section: Process Instance
> > > * Application UUID and name
> > > * Subject: Process variables
> > > * Event: Edit
> > > * Subject Identifier: Process instance UUID
> > > * Body: JSON with new version of process parameters
> > >
> > > Audit logs are displayed in the Audit Log tab within the process instance for easy tracking.
> >
> > > [tab] Data Synchronization
> > >
> > > **What Gets Updated:**
> > >
> > > > [card] Task Manager
> > > >
> > > > Variables are automatically updated in Task Manager using existing mechanisms - ensures task keywords and data remain consistent
> > >
> > > > [card] Elasticsearch
> > > >
> > > > Variables configured for data search are automatically updated in Elasticsearch - maintains search accuracy
> > >
> > > > [card] Process instance params
> > > >
> > > > Primary process instance parameters are updated immediately in the database
> > >
> > > > [card] Snapshot table
> > > >
> > > > Previous values are saved in a new snapshot table before changes are applied
> > >
> > > **What Does NOT Get Updated:**
> > >
> > > > [card] Process snapshots
> > > >
> > > > Process instance snapshots (used for back navigation/reset) are not updated - maintains historical integrity
> > >
> > > > [card] Debug table
> > > >
> > > > Process instance debug records remain unchanged - preserves execution history
> > >
> > > > [card] Existing audit logs
> > > >
> > > > Previously recorded audit logs (manual actions, integrations) are not modified - maintains compliance trail
> > >
> > > > [card] Subprocess variables
> > > >
> > > > Child subprocess variables are not automatically updated - parent changes don't cascade to children
> >
> > > [tab] Important Considerations
> > >
> > > **Limitations & Best Practices:**
> > >
> > > > [!WARNING]
> > > >
> > > > **Subprocess Impact**: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.
> > >
> > > > [!WARNING]
> > > >
> > > > **Back Navigation**: 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.
> > >
> > > > [!WARNING]
> > > >
> > > > **Integration Messages**: 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.
> > >
> > > **Best Practices:**
> > >
> > > * **Verify JSON Format**: Always ensure valid JSON before saving to prevent data corruption
> > > * **Document Changes**: Use audit logs to track all modifications and maintain operational documentation
> > > * **Test in Lower Environments**: When possible, test variable modifications in staging before production
> > > * **Understand Dependencies**: Review process flow and subprocess relationships before modifying variables
> > > * **Consider Timing**: Best used for stuck processes or data corrections, not for regular operational changes
> > > * **Check Search Data**: If variables are used in data search, verify Elasticsearch sync completed successfully
> >
> > > [tab] Benefits
> > >
> > > > [card] Faster issue resolution
> > > >
> > > > Operations teams can resolve production issues immediately without developer intervention
> > >
> > > > [card] Reduced downtime
> > > >
> > > > Unblock stuck instances quickly, minimizing impact on end users and business processes
> > >
> > > > [card] Operational independence
> > > >
> > > > Empower ops teams with self-service tools for process-instance management
> > >
> > > > [card] Data consistency
> > > >
> > > > Automatic sync ensures Task Manager and Elasticsearch reflect updated values
> > >
> > > > [card] Full traceability
> > > >
> > > > Snapshots and audit logs provide complete history of all modifications for compliance
> > >
> > > > [card] Reduced risk
> > > >
> > > > Permission-based access and comprehensive audit trail reduce risk of unauthorized changes
> > >
> > > > [card] Flexible editing
> > > >
> > > > The JSON editor provides powerful JSON editing capabilities with validation
> > >
> > > > [card] Historical preservation
> > > >
> > > > Original values preserved in snapshot table for rollback scenarios
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Correct User Input Errors**
> > >
> > > * Customer submitted incorrect data in a loan application (wrong income, invalid address)
> > > * Operations team edits the variables to correct the information
> > > * Process continues without requiring customer to restart the application
> > >
> > > **2. Unblock Stuck Process Instances**
> > >
> > > * Process is waiting for external data that will never arrive (integration timeout, external system down)
> > > * Ops team updates the variable to provide expected data or skip the condition
> > > * Instance is unblocked and continues execution
> > >
> > > **3. Fix Integration Data Issues**
> > >
> > > * External system returned incorrect or incomplete data
> > > * Operations team corrects process variables to match expected values
> > > * Process continues with accurate data without re-calling the integration
> > >
> > > **4. Emergency Data Updates**
> > >
> > > * Critical business information changed after process started (regulatory update, pricing change)
> > > * Ops team modifies variables to reflect current information
> > > * Process continues with updated data without restart
> > >
> > > **5. Add Missing Attributes**
> > >
> > > * Process needs additional data that wasn't collected at start
> > > * Operations team adds new attributes or objects to process variables
> > > * Process can now access the required information
> > >
> > > **6. Remove Invalid Data**
> > >
> > > * Process contains incorrect or test data that shouldn't be there
> > > * Ops team deletes the problematic attributes or objects
> > > * Process continues with clean, valid data only
> > >
> > > **7. Update Task Manager Keywords**
> > >
> > > * Task search keywords need updating based on corrected data
> > > * Variables are modified and automatically synced to Task Manager
> > > * Tasks become searchable with correct keywords
> > >
> > > **8. Fix Elasticsearch Search Data**
> > >
> > > * Process data indexed for search contains errors
> > >
> > > * Operations team corrects variables configured for data search
> > >
> > > * Elasticsearch automatically updates, ensuring accurate search results
> > >
> > > > [!NOTE]
> > > >
> > > > This capability, combined with the upcoming Move Token feature, provides comprehensive process-instance management tools for operations teams.
> >
> > > [card] [Update Process Variables Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > >
> > > Complete guide including step-by-step instructions, permissions, data synchronization, best practices, and troubleshooting.
> >
> > Operations Enhancement
>
> ***
>
> ### **Token view improvements**
>
> > [card] Token view improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the **Tokens tab** in the **Process Instance View** with improved visibility and comprehension of token hierarchy and context. The enhanced token view introduces horizontal scrolling, frozen columns, hierarchical nesting, and new context-related columns to provide better insights into process execution.
> > >
> > > > [!NOTE]
> > > >
> > > > These improvements make it easier to understand complex process flows with parallel gateways, embedded subprocesses, and boundary events by clearly displaying token relationships and execution context.
> >
> > > [tab] Key Features
> > >
> > > > [card] Horizontal scrolling
> > > >
> > > > The table supports horizontal scrolling to accommodate all columns, ensuring all token information remains accessible
> > >
> > > > [card] Frozen columns
> > > >
> > > > Token UUID and Actions columns remain fixed during horizontal scroll for constant visibility of key identifiers and actions
> > >
> > > > [card] Hierarchical nesting
> > > >
> > > > Tokens display in a tree structure with nested child tokens under parent tokens, showing clear parent-child relationships
> > >
> > > > [card] Auto-expanded rows
> > > >
> > > > All token rows are expanded by default, providing immediate visibility into the complete token hierarchy
> > >
> > > > [card] Dynamic indentation
> > > >
> > > > Indentation dynamically adjusts based on nesting depth, visually representing token relationships
> > >
> > > > [card] Context column
> > > >
> > > > New Context column displays subprocess names for tokens running within embedded subprocesses, or main process name for main process tokens
> > >
> > > > [card] Initiator node column
> > > >
> > > > New Initiator Node column shows the node name that generated the token (e.g., Parallel Gateway, Non-interrupting boundary event)
> > >
> > > > [card] First executed node column
> > > >
> > > > New First Executed Node column displays the first node executed after token generation
> > >
> > > > [card] UUID copy functionality
> > > >
> > > > Token UUID displays first 6 characters with a copy icon; clicking copies the full UUID to clipboard with success notification
> > >
> > > > [card] Color-coded status tags
> > > >
> > > > Token Status column uses color-coded tags for quick visual identification of token lifecycle states
> > >
> > > > [card] Tooltip support
> > > >
> > > > Long node names are truncated with tooltips showing full text on hover for better readability
> > >
> > > > [card] Timezone-aware timestamps
> > > >
> > > > Last Updated column displays full datetime in browser timezone for accurate local time representation
> >
> > > [tab] Table Columns
> > >
> > > The enhanced token view includes the following columns:
> > >
> > > | Column | Description | Special Behavior |
> > > | - | - | - |
> > > | **Token UUID** | Unique identifier of the token | Only first 6 characters displayed. Copy icon appears beside UUID. Clicking copies full UUID to clipboard with success toast: "Full Token UUID copied to clipboard." **Frozen column** (stays visible during horizontal scroll) |
> > > | **Context** | Displays contextual data for token | Shows main process name for tokens in main process. Shows embedded subprocess name for tokens in embedded subprocesses (any nesting level) |
> > > | **Initiator Node** | Shows the node name that generated the token | Applies to child tokens only. For parent tokens, displays "-". Examples: Parallel Gateway name, Non-interrupting boundary event name |
> > > | **First Executed Node** | Displays the first node executed after token generation | For parallel gateway tokens: first executed node on that parallel branch. For boundary event tokens: first executed node on branch started from boundary node. If first node is embedded subprocess, displays embedded subprocess name |
> > > | **Current Node** | Displays the last node executed within the token branch | For parallel gateway tokens: last node on branch. For boundary event tokens: last node executed on branch triggered by boundary. For tokens in embedded subprocess: displays current node from subprocess |
> > > | **Current Node Status** | Shows the current execution status | Examples: WAITING\_TIMER\_EVENT, ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL. Sortable column |
> > > | **Token Status** | Indicates lifecycle state | Values: ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, TERMINATED. **Color-coded tags** for visual identification |
> > > | **Last Updated** | Timestamp of latest token state change | Displays full datetime in browser timezone |
> > > | **Actions** | Available actions for the token | Includes Retry token and View (eye icon) actions. **Frozen column** (stays visible during horizontal scroll). Retry button only visible for ACTIVE tokens |
> >
> > > [tab] Nesting Behavior
> > >
> > > **Token Hierarchy Display:**
> > >
> > > **1. Parent-child relationships**
> > >
> > > Tokens created by parallel gateways or embedded subprocesses are displayed as nested child tokens under their parent tokens
> > >
> > > **2. Default expansion**
> > >
> > > All token rows are expanded by default, showing the complete token hierarchy immediately
> > >
> > > **3. Dynamic indentation**
> > >
> > > Indentation adjusts automatically based on nesting depth, with columns expanding accordingly to maintain alignment
> > >
> > > **4. Visual hierarchy**
> > >
> > > The tree structure makes it easy to identify which tokens belong to which parallel branch or subprocess
> > >
> > > **Initiator Node Logic:**
> > >
> > > * **Parent tokens**: Display "-" in Initiator Node column
> > > * **Child tokens from parallel gateway**: Display the parallel gateway node name
> > > * **Child tokens from boundary event**: Display the boundary event node name
> > > * **Child tokens from back in steps**: Display appropriate initiator information
> >
> > > [tab] Benefits
> > >
> > > > [card] Better visibility
> > > >
> > > > Horizontal scrolling and frozen columns ensure all token information remains accessible regardless of table width
> > >
> > > > [card] Clear hierarchy
> > > >
> > > > Hierarchical nesting with dynamic indentation makes parent-child token relationships immediately clear
> > >
> > > > [card] Context awareness
> > > >
> > > > Context column provides immediate visibility into which subprocess a token is executing within
> > >
> > > > [card] Execution tracking
> > > >
> > > > Initiator Node and First Executed Node columns help track token origin and execution path
> > >
> > > > [card] Quick actions
> > > >
> > > > Frozen Actions column ensures retry and view actions are always accessible without scrolling
> > >
> > > > [card] Easy UUID access
> > > >
> > > > Quick copy functionality for full UUIDs without needing to view token details
> > >
> > > > [card] Visual status identification
> > > >
> > > > Color-coded status tags enable quick identification of token states at a glance
> > >
> > > > [card] Improved readability
> > > >
> > > > Tooltips for truncated names and timezone-aware timestamps improve overall readability
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Parallel Gateway Debugging**
> > >
> > > * View all parallel branches simultaneously with clear parent-child relationships
> > > * Identify which branch each token belongs to through hierarchical nesting
> > > * Track execution progress across multiple parallel paths
> > >
> > > **2. Embedded Subprocess Analysis**
> > >
> > > * Context column immediately shows which subprocess tokens are executing within
> > > * Understand nested subprocess relationships through indentation
> > > * Track token flow across multiple subprocess levels
> > >
> > > **3. Boundary Event Monitoring**
> > >
> > > * Initiator Node column shows which boundary event triggered each token
> > > * First Executed Node shows the execution path started by boundary events
> > > * Monitor non-interrupting boundary event token execution
> > >
> > > **4. Process Instance Troubleshooting**
> > >
> > > * Frozen UUID column ensures token identification is always visible
> > > * Copy UUID functionality enables quick token reference in support tickets
> > > * Color-coded status tags help identify problematic tokens quickly
> > >
> > > **5. Multi-Level Process Analysis**
> > >
> > > * Hierarchical view supports complex processes with multiple nesting levels
> > > * Dynamic indentation adapts to any nesting depth
> > > * All tokens visible by default without manual expansion
> >
> > > [card] [Token Documentation](/5.1/docs/building-blocks/token)
> > >
> > > Complete guide to tokens, including token status values, current node status, and detailed token status view.
> >
> > UX Enhancement
>
> ***
>
> ### **Access management enhancements**
>
> > [card] Access management enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces new workspace-level permissions and a dedicated operations editor role, providing more granular control over process instance management and operations.
> > >
> > > > [!NOTE]
> > > >
> > > > These enhancements enable organizations to delegate operational tasks to dedicated teams without granting full runtime or admin access.
> >
> > > [tab] New Role
> > >
> > > **workspace\_operations\_editor**
> > >
> > > A new predefined workspace role designed for operations teams who need to manage process instances without requiring full runtime or admin capabilities.
> > >
> > > > [card] Operations management
> > > >
> > > > Full CRUD access for process instance operations including migration and move token functionality
> > >
> > > > [card] Process variables
> > > >
> > > > Edit permission for process variables on active instances across the workspace
> > >
> > > > [card] Process instances
> > > >
> > > > Read and edit access to all process instances in the workspace
> > >
> > > > [card] Workspace user inheritance
> > > >
> > > > Inherits all base permissions from workspace\_user role including project creation
> > >
> > > **Role Constraints:**
> > >
> > > * Cannot be edited or deleted (predefined role)
> > > * Extends workspace\_user with operations-specific permissions
> > > * Does not include broader runtime capabilities (builds, policies, scheduled processes)
> > >
> > > **Use Cases:**
> > >
> > > * Support engineers managing process migrations
> > > * Operations teams handling token movements
> > > * Technical support staff editing process variables
> >
> > > [tab] New Permissions
> > >
> > > **Workspace-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **Operations** (Read/Edit/Create/Delete) | Manage process instance operations including migration and move token | `org_admin`, `workspace_admin`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Operations** (Read/Create only) | Create operations and view all operations | `workspace_user` |
> > > | **Process Variables** (Edit) | Edit process variables on active instances | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Process Instances** (Edit) | Edit process instance data | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > >
> > > **Project-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **UI Flows** (Read/Edit/Create/Delete) | Full access to create and manage UI Flows | `project_owner`, `project_editor` |
> > > | **UI Flows** (Read only) | View UI Flows definitions | `project_viewer` |
> >
> > > [tab] Benefits
> > >
> > > > [card] Principle of least privilege
> > > >
> > > > Grant only the permissions needed for specific operational tasks
> > >
> > > > [card] Dedicated operations teams
> > > >
> > > > Enable operations teams to work independently without full admin access
> > >
> > > > [card] Clear separation of concerns
> > > >
> > > > Distinguish between runtime management (builds, policies) and operations management (migrations, variables)
> > >
> > > > [card] Flexible role combinations
> > > >
> > > > Combine with other workspace roles for customized access patterns
> >
> > > [card] [Access Management Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix)
> > >
> > > Complete permissions matrix and role specifications for all FlowX roles.
> >
> > Access Management
>
> ***
>
> ### **Performance and stability**
>
> > [card] Performance and stability
> >
> > FlowX.AI 5.3 includes platform improvements focused on performance, reliability, and operational excellence.
> >
> > ## Backend optimizations
> >
> > > [card] Optimistic lock improvements
> > >
> > > Replace retry pattern with capped exponential backoff and infinite retries for better concurrency handling
> >
> > > [card] Events gateway optimization
> > >
> > > Update Redis read mode to XREAD BLOCK for more efficient event streaming
> >
> > > [card] Database performance
> > >
> > > Remove unnecessary index on token\_instance.current\_node\_id to improve update performance
> >
> > > [card] Template caching
> > >
> > > Enhanced caching for reusable templates at runtime reduces latency and improves throughput
> >
> > ## Infrastructure updates
> >
> > > [card] Connector Topic Pattern
> > >
> > > Added dedicated KAFKA\_CONNECTORS\_TOPIC\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [card] SpiceDB backup
> > >
> > > Documented backup and restore procedures for SpiceDB for disaster recovery
> >
> > > [card] Observability
> > >
> > > Publish Prometheus and OpenTelemetry Helm charts and container images to Harbor
> >
> > > [card] Security updates
> > >
> > > Fix HIGH vulnerabilities in Designer 5.1.x and main branch
> >
> > > [card] Renderer improvements
> > >
> > > Enhanced Angular renderer with action form submit functionality and substitution tag support
> >
> > Platform Updates
>
> ***
>
> ### **Exclusive gateways**
>
> > [card] Exclusive gateways
> >
> > FlowX.AI 5.3 enhances Exclusive Gateway configuration with expression testing capabilities and improved validation.
> >
> > > [card] Expression testing
> > >
> > > Test gateway expressions directly from the configuration panel with real-time validation
> >
> > > [card] Committed version testing
> > >
> > > Test business rules and gateway expressions in committed versions
> >
> > > [card] Code editor integration
> > >
> > > Enhanced code editor with syntax highlighting for complex expressions
> >
> > > [card] Payload synchronization
> > >
> > > Test payloads automatically update when rules are saved
> >
> > Process Logic
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes and stability improvements across Designer, renderers, backend services, and data management.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI Designer and Integration Designer stability improvements\
> 🖥️ [**Renderer Fixes**](#renderer-fixes) - Cross-platform renderer bug fixes for web, iOS, and Android\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements\
> 🗄️ [**Data & Integration Fixes**](#data-and-integration-fixes) - Data mapper and workflow integration fixes
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.3 resolves numerous Designer issues to improve stability and user experience.
> >
> > ## UI designer improvements
> >
> > > [accordion] Configuration & styling
> > >
> > > * **Fixed styles not applied after undo/redo** in Reusable UI Template config panel
> > > * **Fixed UI blocking** when slider min value exceeds max value
> > > * **Fixed warning icon display** in config panel
> > > * **Fixed expression test modal styles** when opened in resized screen
> > > * **Fixed UI action section refresh** when selecting different UI template
> > > * **Fixed UI action section rendering** after clicking 'Add new ui action'
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed loading spinner toggle** not available for Overlay loading behavior
> > > * **Fixed incomplete loading behavior dropdown**
> > > * **Fixed default messages** not displayed after undo
> > > * **Fixed forms in collections handling** for patch actions requests
> >
> > > [accordion] UI Flows designer
> > >
> > > * **Fixed task management error state** when view is selected
> > > * **Fixed tab content preview** showing content from 2 tabs when adding new tab
> >
> > > [accordion] Output parameters
> > >
> > > * **Fixed currency key management** - can now add/remove currency key in output params
> >
> > > [accordion] Exclusive Gateways
> > >
> > > * **Fixed gateway decisions** can now be modified after initial save
> > > * **Fixed test payload** updates when rules are saved
> > > * **Fixed expression propagation** to test modal
> >
> > ## Frontend runtime fixes
> >
> > > [accordion] Process management
> > >
> > > * **Fixed context column** showing empty value for tokens in embedded subprocesses
> > > * **Fixed process params update** from running process instance modal
> > > * **Fixed long node names** overlapping adjacent columns in Tokens table
> > > * **Fixed workspace redirect** on page refresh
> >
> > > [accordion] Audit & logging
> > >
> > > * **Fixed audit log subject value** not displayed for process params updates
> > > * **Fixed toast error messages** to use text from backend request
> > > * **Added documentation link** to Modify Variables modal info text
> >
> > Designer Stability
>
> ***
>
> ### **Renderer fixes**
>
> > [card] Renderer fixes
> >
> > FlowX.AI 5.3 includes comprehensive renderer fixes across all platforms.
> >
> > ## Web renderers (Angular & React)
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed theming** not applied to general loader
> > > * **Fixed theming** not applied to toast messages
> > > * **Fixed dynamic key values** not displayed in toast/loading messages
> > > * **Fixed success toast** displayed when flag is false
> >
> > > [accordion] Card & navigation
> > >
> > > * **Fixed card not expandable** after finishing subprocess started from it (Angular & React)
> > > * **Fixed card collapse** when next nav area is modal (Angular & React)
> > > * **Fixed subprocess navigation** closing parent process navigation with multiple hierarchies
> >
> > > [accordion] UI events
> > >
> > > * **Fixed UI event triggering** without user interaction (Angular)
> >
> > > [accordion] Call activity
> > >
> > > * **Fixed call activity UT rendering** when started from embedded process
> >
> > > [accordion] Collections & forms
> > >
> > > * **Fixed button with forms to submit** no longer disabled until template edited (Angular & React)
> > > * **Fixed multi-select search** filtering (React)
> > > * **Fixed JSON generation** with special characters in CollectionsV2
> >
> > ## Mobile renderers
> >
> > > [accordion] Android
> > >
> > > * **Fixed SSE Event & UI Event** - UI event value displayed instead of SSE value
> >
> > Renderer Stability
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process management
> >
> > > [accordion] Process & build issues
> > >
> > > * **Fixed processes not displayed** in container app list for imported builds
> > > * **Fixed token state** changing from Aborted to Active during back navigation
> > > * **Fixed audit logs** for override operations after merge
> >
> > > [accordion] Performance
> > >
> > > * **Fixed /details endpoint** returning cache error for processes with many components
> >
> > > [accordion] Process engine
> > >
> > > * **Fixed token stuck** in receive node when message received after advancing
> > > * **Fixed action params** copied correctly for child actions when copying node
> > > * **Fixed metadata preservation** when importing process
> >
> > ## Security & configuration
> >
> > > [accordion] Authentication
> > >
> > > * **Fixed service account client secret** configuration parameter in Authorization service
> >
> > ## Data management
> >
> > > [accordion] Runtime issues
> > >
> > > * **Fixed FlowxProps.events** mapping at runtime for array of objects
> >
> > ## Infrastructure
> >
> > > [accordion] Database & events
> > >
> > > * **Fixed advancing errors** in partition event table
> > > * **Fixed Liquibase logging** when crashing due to lock
> >
> > Backend Stability
>
> ***
>
> ### **Data and integration fixes**
>
> > [card] Data and integration fixes
> >
> > Fixes for data mappers and workflow integration features.
> >
> > ## Data mapper issues
> >
> > > [accordion] Mapping operations
> > >
> > > * **Fixed 400 error** when saving mappings
> > > * **Fixed error** when saving mapping with empty parameters
> > > * **Fixed unsaved mapping modal** displayed when saving action
> > > * **Fixed array mapping** - arrays in mapper functions now work correctly
> > > * **Fixed slice deletion** when updating PDM objects
> >
> > > [accordion] Data streams & workflows
> > >
> > > * **Fixed data stream availability** for older exports during import
> > > * **Fixed workflow data stream** data appending issue
> > > * **Fixed legacy mapping** toggle now triggers correctly for call activity
> >
> > > [accordion] UI updates
> > >
> > > * **Fixed start node** not updated in UI after parameters update until refresh
> > > * **Fixed manifest resource** not found after switching versions
> >
> > > [!NOTE]
> > >
> > > Data mapper fixes ensure reliable workflow integration and process-to-workflow data synchronization.
> >
> > Integration Stability
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.3.0](./deployment-guidelines-v5.3).
>
> ### Environment variable updates
>
> > [!NOTE]
> >
> > For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.
>
> ### Breaking changes
>
> > [!WARNING]
> >
> > **FlowX Engine Configuration**: v5.3.0 includes a breaking change to the partitioning and archiving configuration structure. If you have enabled data partitioning, you must update your configuration files.
>
> > [card] [Migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
> >
> > Complete migration guide with step-by-step instructions, configuration examples, and troubleshooting
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.2.0 requires configuration changes for FlowX Engine partitioning/archiving
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.3


# Deployment guidelines v5.4.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/deployment-guidelines-v5.4

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.38.0** | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **10.38.0** | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **10.22.0** | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **10.15.0** | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **10.17.0** | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **10.22.0** | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **10.23.0** | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **10.25.0** | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **10.14.0** | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **10.21.0** | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **10.16.0** | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **10.38.0** | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **10.20.1** | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **10.28.0** | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **10.17.0** | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **email-gateway** | **10.9.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 |

### AI Platform

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.4.0 | Keycloak | 26+ |
| 5.4.0 | Kafka | 3.8 - 3.9 |
| 5.4.0 | PostgreSQL | 16 - 17 |
| 5.4.0 | Oracle Database | 21c, 23ai |
| 5.4.0 | MongoDB | 7 - 8 |
| 5.4.0 | Redis | 7.4 - 8.0 |
| 5.4.0 | Elasticsearch | 8 |
| 5.4.0 | Angular (Web SDK) | 20 |
| 5.4.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.4.0

### Key features and updates

> [card] Email Trigger
>
> Start processes automatically from incoming emails with configurable validation rules

> [card] MCP Server Improvements
>
> Enhanced audit logging, resource management, and tool refresh capabilities

> [card] Email Gateway
>
> New microservice for handling email communication workflows

## Upgrading from v5.3.0

### Breaking changes

> [!NOTE]
>
> FlowX.AI 5.4.0 does not introduce breaking changes for standard deployments. Upgrades from v5.3.0 should be straightforward.

### New environment variables

The following new environment variables have been introduced:

| Variable | Service | Description |
| - | - | - |
| `KAFKA_CONNECTORS_TOPIC_PATTERN` | process-engine | Dedicated Kafka topic pattern for connectors (optional, falls back to `KAFKA_TOPIC_PATTERN` if not set) |
| `KAFKA_BOOTSTRAP_SERVERS` | All services | Standardized Kafka bootstrap servers property (preferred over `SPRING_KAFKA_BOOTSTRAPSERVERS`, backwards compatible) |
| `KAFKA_SECURITY_PROTOCOL` | All services | Standardized Kafka security protocol property (preferred over `SPRING_KAFKA_SECURITY_PROTOCOL`, backwards compatible) |

### Key changes

* **Email Trigger**: New capability to start processes from email events
* **Connector Topics**: New dedicated topic pattern variable for connectors
* **Kafka Configuration**: Standardized Kafka property names (`KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_SECURITY_PROTOCOL`) aligned across all services with backwards compatibility
* **Email Gateway**: New microservice for email communication workflows

### New microservice: Email Gateway

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces a new optional microservice: **Email Gateway**. This service handles email communication workflows within the platform.

The Email Gateway requires the following infrastructure:

| Component | Requirement |
| - | - |
| PostgreSQL | Dedicated database named `email_gateway` |
| MongoDB | Connection to existing `app-runtime` database |
| Kafka | Access to the FlowX Kafka cluster |
| Redis | Shared Redis instance |
| Keycloak | Service account for authentication |

> [!NOTE]
>
> The Email Gateway operates as an internal service and does not require ingress configuration.

> [card] [Email Gateway Setup Guide](/5.9/setup-guides/email-gateway-setup)
>
> Complete setup instructions including Helm values, environment variables, and troubleshooting.

### Compatibility

* **No Breaking Changes**: Standard deployments can upgrade without configuration changes
* **Feature Additions**: SaaS features require additional infrastructure configuration for production use
* **Renderer Updates**: Web and mobile SDKs include bug fixes with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.4.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026

SaaS multi-tenant platform capabilities, database tenant isolation, email-triggered processes, MCP server enhancements, and backend performance improvements.

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces foundational support for a multi-tenant platform, enabling organization management and improved tenant isolation in the SaaS deployment model.

> [!NOTE]
>
> **Deployment models** - Starting with v5.4.0, FlowX.AI is available in two deployment models:
>
> * **Self-Managed** (On-Premises / Customer Cloud)
> * **FlowX SaaS** (FlowX-hosted)
>
> **Feature availability badges:**
>
> * SaaS Features exclusive to FlowX SaaS deployments
> * Self-Managed Features specific to self-managed deployments
> * All Deployments Features available in both deployment models

**What's new?**

> [tab] SaaS & multi-tenancy
>
> > [!NOTE]
> >
> > The features described in this section apply to **FlowX SaaS deployments**.\
> > Self-managed deployments are not affected unless explicitly stated.
>
> FlowX.AI 5.4.0 introduces initial SaaS capabilities enabling multi-tenant deployments with organization management and tenant isolation.
>
> 🏢 [**SaaS Multi-Tenancy**](#saas-multi-tenancy) - Multi-tenant platform with organization isolation and provisioning
>
> ### **SaaS multi-tenancy**
>
> > [card] SaaS multi-tenancy
> >
> > Multi-tenant SaaS capabilities enable multiple organizations to operate independently on shared infrastructure. Each organization receives dedicated resources while maintaining complete isolation from other tenants.
> >
> > > [card] Multi-tenant architecture
> > >
> > > Multiple organizations operate on shared infrastructure with complete isolation
> >
> > > [card] Tenant isolation
> > >
> > > Complete data and authentication isolation between organizations
> >
> > > [card] Organization provisioning
> > >
> > > Automatic provisioning of dedicated resources for each organization
> >
> > > [card] Resource management
> > >
> > > Each organization receives dedicated resources and project spaces
> >
> > > [card] [Documentation](/5.9/docs/saas/saas-overview)
> > >
> > > See the complete FlowX SaaS documentation for guides and best practices.
> >
> > Major FeatureSaaS
>
> ***

> [tab] AI & Integration
>
> Enhanced MCP server management.
>
> 📧 [**Email Trigger**](#email-trigger) - Start processes from external email events with configurable validation rules\
> 💬 [**Chat Component**](#chat-component) - Standalone chat tab for AI-powered conversational interfaces\
> 🔧 [**MCP Server Improvements**](#mcp-server-improvements) - Enhanced audit logging, resource management, and tool updates
>
> ### **Email trigger**
>
> > [card] Email trigger
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces Email Trigger as a new Data Source type in Integration Designer, enabling processes to be started automatically when emails are received. Connect to IMAP mail servers, monitor specific mailboxes, and create process instances with the email data.
> > >
> > > > [!NOTE]
> > > >
> > > > Email Triggers bridge external communication channels with FlowX.AI process automation, enabling organizations to automatically route and process incoming emails through defined business workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation for configuration guides and examples.
> >
> > > [tab] Key Features
> > >
> > > > [card] IMAP Connection
> > > >
> > > > Connect to any IMAP-compatible email server with SSL/TLS support
> > >
> > > > [card] Message Start Event
> > > >
> > > > New trigger type option in Message Start Event nodes to use Email Triggers
> > >
> > > > [card] Attachment handling
> > > >
> > > > Automatic upload of email attachments to Document Plugin with file validation
> > >
> > > > [card] Validation rules
> > > >
> > > > Configure allowed file types, maximum file size, and attachment count limits
> > >
> > > > [card] Manage triggers
> > > >
> > > > Central Runtime page to activate, deactivate, and monitor email triggers
> > >
> > > > [card] Failed triggers
> > > >
> > > > Dedicated page to view and troubleshoot failed email processing attempts
> >
> > > [tab] Configuration
> > >
> > > **Data Source Settings:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | IMAP (currently supported) |
> > > | Server Host | IMAP server hostname |
> > > | Port | Connection port (993 for SSL/TLS) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > > | SSL/TLS | Enable secure connection |
> > >
> > > **Filtering Criteria:**
> > >
> > > * **Email Address**: Monitored email address (read-only, based on authentication)
> > > * **Mailbox Folder**: Folder to monitor (default: Inbox)
> > >
> > > **Validation Options:**
> > >
> > > * **Allowed File Types**: PDF, DOCUMENT, IMAGE, EXCEL, ZIP
> > >
> > > * **Maximum File Size**: Up to 25 MB per attachment
> > >
> > > * **Maximum File Count**: Limit attachments per email
> > >
> > > > [!TIP]
> > > >
> > > > All fields accept configuration parameters using `${configParam}` syntax for environment-specific values.
> >
> > > [tab] Email Data Schema
> > >
> > > When an email triggers a process, the following data structure is available:
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "emailMessage": {
> > >     "subject": "Support Request #12345",
> > >     "dateTime": "2026-01-15T10:30:00Z",
> > >     "sender": "customer@example.com",
> > >     "body": "Email body content...",
> > >     "fileAttachments": [{
> > >       "filePath": "email-attachments/proc-123/file.pdf",
> > >       "downloadPath": "/api/internal/files/uuid/download"
> > >     }],
> > >     "headerParams": {
> > >       "Message-ID": "<abc123@example.com>"
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Use Cases
> > >
> > > > [card] Customer support automation
> > > >
> > > > Automatically create support tickets from incoming customer emails
> > >
> > > > [card] Document processing
> > > >
> > > > Process attached documents through automated workflows
> > >
> > > > [card] Request handling
> > > >
> > > > Route requests to appropriate departments based on email content
> > >
> > > > [card] Notification processing
> > > >
> > > > Process automated notifications from external systems
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat component**
>
> > [card] Chat component
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a standalone Chat tab in web container applications, enabling AI-powered conversational interfaces within your applications. The Chat component provides a dedicated space for users to interact with AI agents through a familiar messaging interface.
> > >
> > > > [!NOTE]
> > > >
> > > > The Chat component integrates with FlowX.AI's AI platform to enable intelligent conversational experiences powered by your configured AI agents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the complete Chat Component documentation for configuration guides and best practices.
> >
> > > [tab] Key Features
> > >
> > > > [card] Standalone chat tab
> > > >
> > > > Dedicated chat interface available as a standalone tab in web container apps
> > >
> > > > [card] Message history
> > > >
> > > > Persistent chat history with automatic scrolling to the latest messages
> > >
> > > > [card] AI agent integration
> > > >
> > > > Connect to workflows powered by AI agents
> > >
> > > > [card] Session management
> > > >
> > > > Automatic session handling with persistence across page refreshes
> > >
> > > > [card] Customizable UI
> > > >
> > > > Themeable components with comprehensive style configuration through Theme Admin
> >
> > > [tab] Configuration
> > >
> > > **Component setup:**
> > >
> > > * Add Chat component from UI Designer to your UI Flow
> > > * Select a workflow to handle chat interactions
> > > * Configure header, messages, and input properties
> > > * Apply custom styling through Theme Admin
> > >
> > > **Display modes:**
> > >
> > > * Full screen (v5.4.0)
> > > * Additional modes planned for v5.5
> >
> > > [tab] Improvements
> > >
> > > **Session handling:**
> > >
> > > * Chat session ID is now generated when the first message is sent (not when opening the chat)
> > > * Improved session tracking
> > >
> > > **Message display:**
> > >
> > > * Latest messages are automatically scrolled into view after loading chat history
> > > * User input formatting (JSON, multiline text) is now preserved in displayed messages
> > >
> > > **Platform support:**
> > >
> > > * Available in both Angular and React web renderers
> > > * Mobile support planned for v5.5
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **MCP server improvements**
>
> > [card] MCP server improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 enhances MCP (Model Context Protocol) server integration with improved audit logging, exception handling, and resource management capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audit logging
> > > >
> > > > Complete audit trail for MCP server operations including creation, updates, and tool execution
> > >
> > > > [card] Tool refresh
> > > >
> > > > Update MCP servers to fetch new tools without recreating the data source
> > >
> > > > [card] Resource tracking
> > > >
> > > > Track MCP server usage across workflows with proper resource management
> > >
> > > > [card] Copy support
> > > >
> > > > Properly preserve MCP server selections when copying or duplicating workflows
> > >
> > > > [card] SSE streaming
> > > >
> > > > Fixed SSE event streaming to deliver events individually as they complete
> > >
> > > > [card] Exception handling
> > > >
> > > > Improved error handling and reporting for MCP server operations
> >
> > > [tab] Bug Fixes
> > >
> > > * **Tool updates**: Updating MCP servers now correctly fetches new tools
> > > * **Workflow copy**: MCP server selections are preserved when copying workflows
> > > * **Resource usages**: Fixed resource usage tracking when copying workflows to other projects
> > > * **SSE events**: Events are now streamed individually instead of all at once
> > > * **Audit entries**: Fixed missing event and subject in audit log entries
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] Rendering
>
> UI component enhancements and navigation improvements for web applications.
>
> 🎴 [**Card Default Collapse State**](#card-default-collapse-state) - Configure cards to load in collapsed state by default\
> 🧭 [**UI Flow Breadcrumbs**](#ui-flow-breadcrumbs) - Navigation breadcrumbs ui component for UI Flows with theme configuration\
> 📊 [**UI Flow Sessions**](#ui-flow-sessions) - Monitor and manage UI Flow sessions with audit logs and process tracking\
> 📋 [**Tables in Collections**](#tables-in-collections) - Add support for Table UI components within Collection UI elements
>
> ### **Card default collapse state**
>
> > [card] Card default collapse state
> >
> > FlowX.AI 5.4.0 introduces a new **Default collapse state** property for Card components with accordion functionality, allowing you to configure cards that are collapsed when first loaded.
> >
> > > [tab] Overview
> > >
> > > When using Card components with the accordion feature enabled, you can now specify whether the card should be expanded or collapsed by default when the screen loads. This provides better control over the initial presentation of content and helps manage screen real estate.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> > > >
> > > > See the complete Card component documentation for configuration details.
> >
> > > [tab] Configuration
> > >
> > > **Default collapse state options:**
> > >
> > > | State | Description |
> > > | - | - |
> > > | **Expanded** | The card content is visible when the screen loads (default behavior) |
> > > | **Collapsed** | The card content is hidden when the screen loads; users click to expand |
> > >
> > > > [!NOTE]
> > > >
> > > > This property is only available when the **Has accordion** setting is enabled on the Card component.
> >
> > > [tab] Use Cases
> > >
> > > > [card] Progressive disclosure
> > > >
> > > > Start with collapsed sections to reduce initial visual complexity
> > >
> > > > [card] Optional content
> > > >
> > > > Hide less important information by default while keeping it accessible
> > >
> > > > [card] Long forms
> > > >
> > > > Break up lengthy forms into collapsible sections for better navigation
> > >
> > > > [card] FAQ sections
> > > >
> > > > Display questions collapsed with answers revealed on click
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Breadcrumbs**
>
> > [card] UI Flow Breadcrumbs
> >
> > > [tab] Overview
> > >
> > > Navigation breadcrumbs UI component for UI Flows provide users with clear context of their current location within the application hierarchy. Breadcrumbs display the navigation path and enable quick navigation to parent screens.
> > >
> > > > [!NOTE]
> > > >
> > > > Breadcrumbs enhance user experience by providing visual navigation context and allowing users to understand their position in the application structure.
> >
> > > [tab] Key Features
> > >
> > > > [card] Navigation breadcrumbs UI component
> > > >
> > > > Display breadcrumbs UI component for UI Flows showing the current navigation path
> > >
> > > > [card] Admin theme configuration
> > > >
> > > > Configure breadcrumb appearance and styling through Admin theme settings
> >
> > > [tab] Configuration
> > >
> > > **Theme Configuration:**
> > >
> > > * Configure breadcrumb styling through Admin theme settings
> > > * Customize colors, fonts, and spacing to match your application design
> > > * Apply consistent styling across all UI Flows
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Sessions**
>
> > [card] UI Flow Sessions
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces UI Flow Sessions monitoring in the Runtime view, providing comprehensive visibility into active user sessions with UI Flows. Monitor session activity, view audit logs, track associated processes, and debug UI Flow interactions in real-time.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flow Sessions enable administrators and developers to track user interactions, troubleshoot issues, and monitor the health of UI Flow-based applications.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> > > >
> > > > See the complete UI Flow Sessions documentation for detailed usage and troubleshooting guides.
> >
> > > [tab] Key Features
> > >
> > > > [card] Session monitoring
> > > >
> > > > View all active and historical UI Flow sessions with status, start date, and session IDs
> > >
> > > > [card] Audit log
> > > >
> > > > Comprehensive audit trail showing all events and actions within each session
> > >
> > > > [card] Process tracking
> > > >
> > > > Monitor process instances started from UI Flows with execution status and timing
> > >
> > > > [card] Workflow debugging
> > > >
> > > > View workflow execution details, node timing, and data transformations for troubleshooting
> > >
> > > > [card] Filtering and search
> > > >
> > > > Filter sessions by UI Flow definition and search by session ID for quick access
> > >
> > > > [card] Real-time status
> > > >
> > > > Track session status updates in real-time (STARTED, ACTIVE, FINISHED, FAILED)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Session monitoring
> > > >
> > > > Monitor active sessions to understand user engagement and identify sessions needing attention
> > >
> > > > [card] Audit and compliance
> > > >
> > > > Track all user interactions and actions for audit purposes and compliance requirements
> > >
> > > > [card] Debugging
> > > >
> > > > Investigate issues by reviewing audit logs, process instances, and workflow executions
> > >
> > > > [card] Performance analysis
> > > >
> > > > Analyze session duration, process start times, and workflow execution performance
> >
> > Runtime ManagementAll Deployments
>
> ***
>
> ### **Tables in Collections**
>
> > [card] Tables in Collections
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces support for Table UI components within Collection UI elements, enabling you to display structured tabular data as items within dynamic collections. This enhancement provides greater flexibility for presenting complex data structures in a consistent, organized format.
> > >
> > > > [!NOTE]
> > > >
> > > > You can now embed Table components inside Collection prototypes, allowing each collection item to display data in a structured table format with columns, rows, and table-specific features.
> > >
> > > > [card] [Table Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/table)
> > > >
> > > > See the complete Table component documentation for configuration details and usage examples.
> > >
> > > > [card] [Collection Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/collection/collection)
> > > >
> > > > Learn about Collection components and how to configure collection prototypes.
> >
> > > [tab] Key Features
> > >
> > > > [card] Table in collection items
> > > >
> > > > Embed Table components within Collection prototypes to display structured data for each collection item
> > >
> > > > [card] Structured data display
> > > >
> > > > Present complex data structures with columns, rows, and table-specific formatting within collections
> > >
> > > > [card] Table features
> > > >
> > > > Leverage full Table component capabilities including sorting, filtering, pagination, and row actions
> > >
> > > > [card] Dynamic content
> > > >
> > > > Combine Collection's dynamic data handling with Table's structured presentation for flexible layouts
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product catalogs
> > > >
> > > > Display product information in table format within a collection of products
> > >
> > > > [card] Data dashboards
> > > >
> > > > Create dashboard views with multiple tables showing different data sets in collection items
> > >
> > > > [card] Report listings
> > > >
> > > > Show report summaries in table format within a collection of reports
> > >
> > > > [card] Comparison views
> > > >
> > > > Compare multiple entities side-by-side using tables within collection items
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Platform & infrastructure
>
> Backend optimizations, connector improvements, and platform stability enhancements.
>
> 🔌 [**Connector Topic Pattern**](#connector-topic-pattern) - Dedicated Kafka topic pattern for connectors\
> ⚙️ [**Kafka Configuration Alignment**](#kafka-configuration-alignment) - Unified Kafka property names across all services with backwards compatibility\
> ⚡ [**Advancing Performance**](#advancing-performance) - Fixed advancing partition issues and improved concurrency handling
>
> ### **Connector topic pattern**
>
> > [card] Connector topic pattern
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a dedicated Kafka topic pattern variable (`KAFKA_CONNECTORS_TOPIC_PATTERN`) for connectors, allowing custom topic patterns without affecting other platform components like document-plugin, data-search, and cms-core.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Shared topic pattern
> > > >
> > > > Connectors used the same `KAFKA_TOPIC_PATTERN` as other components, limiting customization
> > >
> > > > [card] Security concerns
> > > >
> > > > Connectors could write to all topics with the pattern `ai.flowx.engine.receive.*`
> >
> > > [tab] Solution
> > >
> > > **New Configuration:**
> > >
> > > ```yaml theme={"dark"}
> > > # Old configuration (shared with all components)
> > > KAFKA_TOPIC_PATTERN: ai.flowx.engine.receive.*
> > >
> > > # New configuration (dedicated for connectors)
> > > KAFKA_CONNECTORS_TOPIC_PATTERN: ro.uniflow.*
> > > ```
> > >
> > > **Benefits:**
> > >
> > > * Connectors can use custom topic patterns
> > > * Other components continue using the standard pattern
> > > * Improved security through topic isolation
> >
> > InfrastructureSelf-Managed
>
> ***
>
> ### **Kafka configuration alignment**
>
> > [card] Kafka configuration alignment
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 aligns Kafka configuration properties across all services (core-services and AI platform services) by introducing standardized property names while maintaining full backwards compatibility with existing configurations.
> >
> > > [tab] New Properties
> > >
> > > **Standardized Kafka Properties:**
> > >
> > > The following new environment variables are now available across all services:
> > >
> > > | Environment Variable | Description | Fallback Property |
> > > | - | - | - |
> > > | `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers | `SPRING_KAFKA_BOOTSTRAP_SERVERS` |
> > > | `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka communication | `SPRING_KAFKA_SECURITY_PROTOCOL` |
> > >
> > > > [!NOTE]
> > > >
> > > > The new properties take precedence over the legacy `SPRING_KAFKA_*` properties. If the new properties are not set, the system automatically falls back to the legacy properties, ensuring backwards compatibility.
> >
> > > [tab] Benefits
> > >
> > > > [card] Property alignment
> > > >
> > > > Consistent property names across core-services and AI platform services
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing configurations using `SPRING_KAFKA_*` properties continue to work without changes
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Unified configuration approach across all FlowX.AI services
> > >
> > > > [card] Migration flexibility
> > > >
> > > > Migrate to new properties at your own pace without breaking existing deployments
> > >
> > > > [!NOTE]
> > > >
> > > > This change was implemented in core-services and automatically applies to all services that use the shared Kafka configuration. No action is required for existing deployments, but you can optionally migrate to the new property names for consistency.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Advancing performance**
>
> > [card] Advancing performance
> >
> > FlowX.AI 5.4.0 includes significant fixes and improvements to the advancing mechanism, resolving issues with stalled events and improving concurrency handling.
> >
> > > [accordion] Stalled events fix
> > >
> > > Fixed issue where NEW entries in `advancing_partition` and `advancing_partition_event` tables would become stalled and never processed. This occurred when multiple events were generated for the same partition during parallel processing.
> >
> > > [accordion] Numeric overflow fix
> > >
> > > Fixed numeric overflow error when `advancing_partition_event_seq` sequence exceeded `Integer.MAX_VALUE`. Now correctly uses `getLong()` instead of `getInt()` for sequence values.
> >
> > > [accordion] Concurrency improvements
> > >
> > > * Fixed issue with multiple events to the same partition causing negative `count_queued_events`
> > > * Replaced trigger-based solution with SQL transactions for atomic updates
> > > * Improved handling of embedded subprocess completion under concurrent load
> >
> > > [accordion] Automated test stability
> > >
> > > Resolved data inconsistencies and business exceptions that were causing automated tests to fail consistently.
> >
> > PerformanceAll Deployments
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes across SaaS features, Designer, and backend services.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI and navigation fixes for Designer\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.4.0 resolves Designer issues to improve stability and user experience.
> >
> > ## Navigation & routing
> >
> > > [accordion] Navigation fixes
> > >
> > > * **Fixed sidebar display** - sidebar menu now shows when accessing pages via URL
> > > * **Fixed subprocess navigation** - resolved 403 when navigating to subprocesses
> > > * **Fixed back navigation** - resolved 403 when going back from UI Flows page
> > > * **Fixed audit log access** - resolved errors when viewing process instance audit logs
> > > * **Fixed version history** - "Open version in new tab" now works correctly
> >
> > > [accordion] UI improvements
> > >
> > > * **Fixed default locale display** - locale now correctly shown in Version settings
> > > * **Fixed substitution calls** - resolved errors when starting processes or accessing UI Flows
> >
> > Designer StabilityAll Deployments
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process engine
> >
> > > [accordion] Advancing & concurrency
> > >
> > > * **Fixed stalled advancing events** - NEW entries no longer get stuck in advancing tables
> > > * **Fixed numeric overflow** - resolved overflow when sequence exceeds Integer.MAX\_VALUE
> > > * **Fixed concurrent updates** - resolved stale data errors for embedded subprocess completion
> > > * **Fixed negative counter** - resolved issue with `count_queued_events` going negative
> >
> > ## AI platform
> >
> > > [accordion] AI integration fixes
> > >
> > > * **Fixed multi-agent streaming** - streaming now works correctly for multi-agent chat
> > > * **Fixed SSE event delivery** - events are delivered individually as they complete
> >
> > ## Integration Designer
> >
> > > [accordion] Workflow & data model
> > >
> > > * **Fixed file upload multipart** - only file name is sent in multipart body, not full path
> > > * **Fixed data model duplicates** - resolved duplicate entries in mongo properties\_paths
> >
> > Backend StabilityAll Deployments
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.4.0](./deployment-guidelines-v5.4).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.3.0 - no breaking changes for standard deployments
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.4
>
> ### SaaS features
>
> > [!NOTE]
> >
> > The SaaS multi-tenant features introduced in this release require additional infrastructure configuration for production deployments. Contact your FlowX.AI representative for guidance on enabling SaaS capabilities.


# Deployment guidelines v5.5.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/deployment-guidelines-v5.5

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.60.0** | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 |
| **admin** | **10.53.0** | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 |
| **designer** | **10.91.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **cms-core** | **10.35.0** | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **10.25.0** | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **10.27.0** | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **10.35.0** | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **10.35.0** | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **10.35.0** | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 |
| **data-search** | **10.25.0** | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **10.31.0** | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **10.27.0** | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 |
| **integration-designer** | **10.63.0** | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 |
| **application-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **data-sync** | **10.31.1** | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 |
| **authorization-system** | **10.42.1** | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **10.27.0** | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 |
| **email-gateway** | **10.24.0** | 10.9.0 | - | - | - | - |
| **organization-manager** | **10.19.2** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 |
| **Android renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 |
| **di-platform** | **10.2.6** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **knowledgebase** | **TBD** | - | - | - | - | - |
| **knowledgebase-rag** | **10.2.0** | - | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.2.0** | - | - | - | - | - |
| **mcp** | **10.2.0** | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.5.0 | Keycloak | 26+ |
| 5.5.0 | Kafka | 3.8 - 3.9 |
| 5.5.0 | PostgreSQL | 16 - 17 |
| 5.5.0 | Oracle Database | 21c, 23ai |
| 5.5.0 | MongoDB | 7 - 8 |
| 5.5.0 | Redis | 7.4 - 8.0 |
| 5.5.0 | Elasticsearch | 8 - 9 |
| 5.5.0 | Angular (Web SDK) | 20 |
| 5.5.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.5.0

### Key features and updates

> [card] Chat Component Enhancements
>
> New subcomponents (reasoning, error, suggestions), display modes, and mobile support

> [card] UI Flows Improvements
>
> Process renderer component, start workflow action, and on load events

> [card] Microsoft Outlook Integration
>
> Native MS Graph data source for reading and sending Outlook emails

> [card] Send Notification Action
>
> Send emails and reply to received emails directly from processes via SMTP

> [card] Knowledge Base v2
>
> Updated Knowledge Base with audit, resource management, and improved UI

> [card] User Management Updates
>
> Password policy, DISABLED status, resend invitations, workspace environment types

## Upgrading from v5.4.0

### Breaking changes

> [!WARNING]
>
> FlowX.AI 5.5.0 introduces a **breaking change** to the default authentication mechanism across most platform services. If you rely on the default `SECURITY_TYPE` value or opaque-token introspection, action is required before upgrading.

#### Authentication mechanism change

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. This reflects a shift from opaque-token introspection to JWT-based authentication as the default security mechanism.

**Removed environment variables:**

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

**Changed default values:**

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

**Migration steps:**

**1. Update SECURITY\_TYPE if explicitly set**

If you explicitly set `SECURITY_TYPE=oauth2` in your deployment configuration, update it to `jwt-public-key` or remove it to use the new default.

**2. Remove deprecated opaque-token variables**

Remove all `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_*` variables from your Helm values, environment configs, or deployment manifests.

**3. Update service account client IDs**

Service account client IDs now follow the `flowx-{service-name}-sa` pattern (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Update your Keycloak service account configurations accordingly.

**4. Configure the service account realm**

Add the `security.oauth2.sa-realm` property to your configuration if your service account realm differs from the default.

**5. Remove legacy OAuth2 client variables**

Remove `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENT_ID`, `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`, and `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_*` variables from your configuration.

***

### Key changes

* **Authentication**: Default `SECURITY_TYPE` changed from `oauth2` to `jwt-public-key` (breaking change — see above)
* **Organization Manager**: New microservice for organization and tenant management
* **Chat Component**: Enhanced with new subcomponents (reasoning, error, suggestions), display modes, and mobile support
* **UI Flows**: New process renderer component, start workflow action, and on load UI event
* **Microsoft Outlook**: New MS Graph data source for Outlook email integration
* **Send Notification**: New action type for sending/replying to emails via SMTP
* **Knowledge Base v2**: Updated UI, audit trail, and resource management
* **Container Apps**: Enhanced authentication flow and landing page
* **File Upload**: Improved progress indicators, drag and drop, and large file support
* **File Encrypt/Decrypt**: New document plugin actions for file encryption and decryption
* **User Management**: Password policy updates, DISABLED status, resend invitations, workspace environment type
* **Process Variables Compare**: Monaco diff editor for comparing variable values
* **New Kafka topics**: Multiple new topics added across document-plugin, integration-designer, admin, application-manager, email-gateway, authorization-system, and notification-plugin

***

### New microservice: Organization Manager

> [!NOTE]
>
> **Available starting with FlowX.AI 5.5.0**
>
> The Organization Manager is a new microservice responsible for organization and tenant management, including user registration, organization lifecycle, and platform component health monitoring.

**Infrastructure requirements:**

| Dependency | Details |
| - | - |
| PostgreSQL | Dedicated database for organization data |
| Redis | Caching and session management |
| Kafka | Event publishing (organization events topic) |
| Keycloak/IAM | Authentication and realm management |
| SpiceDB | Authorization via CAS lib |

> [card] [Organization Manager Setup](/5.1/setup-guides/organization-manager-setup)
>
> Complete setup and configuration guide for the Organization Manager microservice

***

### New Kafka topics

FlowX.AI 5.5.0 introduces new Kafka topics across multiple services.

#### Document-plugin Kafka topics

New topics for file encryption, decryption, bulk document persistence, and UI Flow session document persistence operations.

**Input topics (document-plugin consumes from these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Triggers file decryption operations |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Triggers file encryption operations |
| `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Triggers bulk document persistence operations |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway |

**Output topics (document-plugin publishes to these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Results from file decryption operations |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Results from file encryption operations |
| `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Results from bulk document persistence |
| `ai.flowx.eventsgateway.receive.document.v1` | Document upload progress notifications sent to events-gateway for SSE delivery |

#### Integration-designer Kafka topics

New topics for integration-designer in 5.5.0. Integration-designer now participates in the application sync mechanism for system and workflow resources.

> [!NOTE]
>
> The `sync.out.v1` and `correction-after-app-operation.response.v1` topics already exist since 5.1.x (used by admin). In 5.5.0, integration-designer becomes an additional producer on these shared response topics.

**New topics:**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync requests | Inbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System resource correction requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow resource correction requests | Inbound |
| `ai.flowx.build.runtime-data.v1` | Build runtime data | Outbound |
| `ai.flowx.license.usage.v1` | License usage tracking | Outbound |

**Existing topics (new producer in 5.5.0):**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.out.v1` | Sync operation responses | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | Correction operation responses | Outbound |

#### Admin Kafka topics

New topics for UI flow synchronization and correction operations in 5.5.0.

> [!NOTE]
>
> The `sync.process.in.v1`, `sync.business-rule.in.v1`, `sync.reusable-template.in.v1`, `sync.out.v1`, and `correction-after-app-operation` topics for process, business-rule, and reusable-template already exist since 5.1.x. Only the UI flow topics below are new in 5.5.0.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Inbound |

#### Application-manager Kafka topics

New outbound topics for resource synchronization and correction of system, workflow, and UI flow resources in 5.5.0.

> [!NOTE]
>
> Application-manager already produces sync and correction topics for process, business-rule, and reusable-template since 5.1.x. The topics below extend the same mechanism to system, workflow, and UI flow resources.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync | Outbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync | Outbound |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow resource sync | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Outbound |

#### Email-gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.save.audit.v1` | Audit event logging | Outbound |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Trigger process start from email events | Outbound |

#### Authorization-system Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.organization.events.v1` | Organization lifecycle events | Outbound |

#### Notification-plugin Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.resources-usages.refresh.v1` | Resource usages refresh events | Inbound |
| `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` | Sub-resource validation responses | Outbound |
| `ai.flowx.application-version.resources-usages.operations.bulk.v1` | Bulk resource usage operations | Outbound |

> [!NOTE]
>
> These topics are automatically created if your Kafka cluster has auto-topic creation enabled. For production environments, it is recommended to create them manually with appropriate partition counts and replication factors.

***

### New environment variables

#### Platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

#### Document-plugin variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) | document-plugin |

> [!NOTE]
>
> This setting affects all file uploads handled by the document-plugin. Configure alongside the existing Spring multipart settings (`SPRING_SERVLET_MULTIPART_MAXFILESIZE`, `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`) for consistent upload limits. See [Documents Plugin Setup](/5.1/setup-guides/documents-plugin-setup#multipart-upload-configuration).

#### Authorization-system variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client. Required for new deployments. | ` ` (empty) | authorization-system |

> [!WARNING]
>
> **New deployments only**: If this variable is not set, the `flowx-platform-authenticate` Keycloak client will have no redirect URIs and OAuth2 login will fail. Set this to your Designer and app URLs (e.g., `https://designer.yourcompany.com/*,https://app.yourcompany.com/*`).
>
> Existing deployments upgrading to 5.5.0 are not affected — the Liquibase migration that uses this variable has already run.

> [card] [Authorization System Setup](/5.1/setup-guides/authorization-setup-guide#keycloak-redirect-uris)
>
> See the full redirect URI configuration details

#### Email-gateway variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` | email-gateway |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` | email-gateway |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL` | TTL for cached MS Graph client instances | `1d` | email-gateway |

> [!NOTE]
>
> For complete email-gateway configuration including database, Redis, and Kafka settings, see the [Email Gateway Setup](/5.9/setup-guides/email-gateway-setup) guide.

***

### Compatibility

* **Authentication**: Default `SECURITY_TYPE` changed to `jwt-public-key` — deployments using opaque-token introspection require migration (see [breaking changes](#authentication-mechanism-change))
* **Renderer Updates**: Web and mobile SDKs include new Chat component features and UI Flows enhancements
* **Database**: No schema changes required for this upgrade
* **Mobile Support**: Chat component now available on iOS and Android renderers
* **New Service**: Organization Manager requires PostgreSQL, Redis, Kafka, and Keycloak infrastructure

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/migration-overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!WARNING]
>
> FlowX.AI v5.5.0 introduces a **critical breaking change** to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

## What's changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (`oauth2`) to JWT-based authentication (`jwt-public-key`). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — **Organization Manager** — has been introduced for organization and tenant management.

## Who is affected

> [!WARNING]
>
> **All deployments** are affected by the authentication mechanism change. The default `SECURITY_TYPE` value has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services.
>
> If you explicitly set `SECURITY_TYPE=oauth2` or rely on opaque-token introspection, you **must** update your configuration before upgrading.

## Migration process

**1. Back up your configuration**

Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.

**2. Update Keycloak service accounts**

Update your Keycloak service account client IDs to follow the new `flowx-{service-name}-sa` naming pattern. See [Update Keycloak service accounts](#update-keycloak-service-accounts) for the full mapping.

**3. Update environment variables**

Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.

**4. Deploy Organization Manager**

If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.

**5. Deploy and verify**

Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

***

## Authentication mechanism change

### Overview

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. Opaque-token introspection has been **removed entirely**.

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

### Changed default values

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

***

## Update Keycloak service accounts

Service account client IDs now follow the `flowx-{service-name}-sa` pattern. Update your Keycloak configuration to match:

| Service | New Client ID |
| - | - |
| Admin | `flowx-admin-sa` |
| Process Engine | `flowx-process-engine-sa` |
| Integration Designer | `flowx-integration-designer-sa` |
| Authorization System | `flowx-authorization-system-sa` |
| Runtime Manager | `flowx-runtime-manager-sa` |
| Scheduler Core | `flowx-scheduler-core-sa` |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager | `flowx-organization-manager-sa` |
| License | `flowx-license-sa` |
| Email Gateway | `flowx-email-gateway-sa` |

> [!WARNING]
>
> Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

***

## New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the **Organization Manager** microservice for organization and tenant management, user registration, and platform component health monitoring.

**Infrastructure requirements:**

* PostgreSQL
* Redis
* Kafka
* Keycloak/IAM
* SpiceDB

For full setup instructions, see the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility** for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

## Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your `SECURITY_TYPE` and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

> [!NOTE]
>
> Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

***

## Additional resources

> [card] [Update Environment Variables](./update-environment-variables-5.5)
>
> Per-service environment variable changes for v5.5.0

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions and deployment instructions

> [card] [IAM Configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution)
>
> Keycloak setup and service account configuration

> [card] [Release Notes v5.5.0](../v5.5.0-february-2026)
>
> Full release notes for v5.5.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/update-environment-variables-5.5

Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!NOTE]
>
> This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"dark"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

> [tab] Before (v5.4)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "oauth2"
>
> # Service account client ID (example for admin service)
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"
>
> # Token URI using main realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
> ```

> [tab] After (v5.5)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "jwt-public-key"
>
> # Service account client ID follows flowx-{service-name}-sa pattern
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"
>
> # Token URI now uses separate sa-realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
> ```

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

***

## Document plugin

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

> [!NOTE]
>
> **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` |

***

## Additional resources

> [card] [Migration Overview](./migration-overview)
>
> Full migration guide with Keycloak and service account changes

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions, Kafka topics, and infrastructure requirements


# FlowX.AI 5.5.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/v5.5.0-february-2026

Enhanced Chat component, UI Flows improvements, Microsoft Outlook integration, container app authentication, and platform management updates.

> [!NOTE]
>
> FlowX.AI 5.5.0 introduces significant enhancements to the Chat component, UI Flows capabilities, email integrations, and platform management features including Knowledge Base v2, user management improvements, and new document processing capabilities.

![Data Source types in FlowX 5.5.0](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_type_selector_all.png)

**What's new?**

> [tab] AI Platform
>
> AI-powered features and document processing enhancements.
>
> 📄 [**Extract Data from File**](#extract-data-from-file) - Configurable document and image extraction with LLM, OCR, and text parsing strategies\
> 📚 [**Knowledge Base v2**](#knowledge-base-v2) - Updated Knowledge Base with audit, resource management, and improved UI
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 renames "Extract Text from Document" to **Extract Data from File** and adds configurable extraction strategies, image input support, and signature detection. Choose between LLM, OCR, or text parsing strategies based on your document types, accuracy requirements, and cost constraints.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Extraction strategies
> > > >
> > > > Choose between LLM Model, OCR Engine, or Text Parsing for optimal accuracy/cost balance
> > >
> > > > [card] Image support
> > > >
> > > > Process images (JPG, PNG, TIFF) in addition to documents — automatic PDF conversion
> > >
> > > > [card] Image extraction options
> > > >
> > > > Extract data from embedded images or generate image descriptions
> > >
> > > > [card] Signature detection
> > > >
> > > > Detect and locate signatures within documents (LLM and OCR modes)
> >
> > > [tab] Configuration
> > >
> > > **Extraction strategies:**
> > >
> > > | Strategy | Best for | Speed | Cost | Accuracy |
> > > | - | - | - | - | - |
> > > | LLM Model | Complex layouts, handwritten text | Slow | High | High |
> > > | OCR Engine | Scanned documents | Medium | Medium | Medium |
> > > | Text Parsing | Clean digital PDFs | Fast | Free | Low–Medium |
> > >
> > > **Image extraction options (LLM and OCR only):**
> > >
> > > | Option | Description |
> > > | - | - |
> > > | Image Description | Generates text descriptions of images |
> > > | Image Content | Extracts text and data from images |
> > >
> > > > [!TIP]
> > > >
> > > > A new [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) covers backend service configuration, deployment sizing, and cost optimization.
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Knowledge Base v2**
>
> > [card] [Knowledge Base v2](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 updates the Knowledge Base with a refreshed UI, audit capabilities, and improved resource management. Knowledge Base entries now support versioning and provide better traceability for AI-powered features.
> >
> > > [tab] Key Features
> > >
> > > > [card] Updated UI
> > > >
> > > > Refreshed Knowledge Base interface with improved navigation and search
> > >
> > > > [card] Audit trail
> > > >
> > > > Track changes to Knowledge Base entries with full audit history
> > >
> > > > [card] Resource management
> > > >
> > > > Improved management of Knowledge Base resources and documents
> > >
> > > > [card] Version tracking
> > > >
> > > > Version-aware Knowledge Base entries tied to app versions
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] UI Flows
>
> Enhanced UI Flows with new components, actions, and chat improvements.
>
> 💬 [**Chat Component Enhancements**](#chat-component-enhancements) - New subcomponents, display modes, and mobile support\
> 🧭 [**UI Flows Breadcrumbs**](#ui-flows-breadcrumbs) - Navigation breadcrumbs for UI Flows\
> 📄 [**Process Renderer Component**](#process-renderer-component) - Embed process renderers within UI Flows\
> 🚀 [**Start Workflow Action**](#start-workflow-action) - Start workflows directly from UI Flows\
> ⚡ [**On Load UI Event**](#on-load-ui-event) - Execute actions when UI Flows load
>
> ### **Chat component enhancements**
>
> > [card] [Chat component enhancements](/5.9/ai-platform/chat-component)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 significantly enhances the Chat component with new subcomponents for reasoning, error handling, and suggestions. The component now supports multiple display modes and is available on mobile platforms.
> >
> > > [tab] New Subcomponents
> > >
> > > > [card] Reasoning display
> > > >
> > > > Show AI reasoning and thought process to users for transparency
> > >
> > > > [card] Error handling
> > > >
> > > > Graceful error display with retry options and helpful messages
> > >
> > > > [card] Suggestions
> > > >
> > > > Display suggested responses or actions to guide user interactions
> >
> > > [tab] Display Modes
> > >
> > > **Available display modes:**
> > >
> > > | Mode | Description |
> > > | - | - |
> > > | **Full screen** | Chat occupies the entire screen (available since v5.4.0) |
> > > | **Sidebar** | Chat appears as a collapsible sidebar |
> > > | **Floating** | Chat appears as a floating widget |
> > > | **Embedded** | Chat embedded within a container component |
> >
> > > [tab] Mobile Support
> > >
> > > The Chat component is now fully supported on mobile platforms:
> > >
> > > > [card] iOS
> > > >
> > > > Native iOS renderer support with optimized touch interactions
> > >
> > > > [card] Android
> > > >
> > > > Native Android renderer support with material design integration
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **UI Flows breadcrumbs**
>
> > [card] [UI Flows breadcrumbs](/5.9/docs/building-blocks/ui-flows#breadcrumbs)
> >
> > FlowX.AI 5.5.0 enhances the breadcrumbs navigation component for UI Flows, providing users with clear context of their current location and enabling quick navigation to parent screens.
> >
> > > [card] Navigation path
> > >
> > > Display the full navigation path within UI Flows
> >
> > > [card] Click navigation
> > >
> > > Navigate to any parent screen by clicking breadcrumb items
> >
> > > [card] Theme configuration
> > >
> > > Customize breadcrumb appearance through Admin theme settings
> >
> > > [card] Responsive design
> > >
> > > Breadcrumbs adapt to different screen sizes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process renderer component**
>
> > [card] [Process renderer component](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > > [tab] Overview
> > >
> > > Embed process renderers directly within UI Flows using the new Process Renderer component. This enables hybrid applications that combine UI Flow navigation with traditional process-based screens.
> >
> > > [tab] Key Features
> > >
> > > > [card] Process embedding
> > > >
> > > > Embed any process renderer within a UI Flow screen
> > >
> > > > [card] Data passing
> > > >
> > > > Pass data between UI Flows and embedded processes
> > >
> > > > [card] Event handling
> > > >
> > > > Handle process events within the UI Flow context
> > >
> > > > [card] Consistent styling
> > > >
> > > > Maintain consistent styling and navigation across UI Flows and processes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Start workflow action**
>
> > [card] [Start workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action)
> >
> > > [tab] Overview
> > >
> > > Start integration workflows directly from UI Flows using the new Start Workflow action. This enables UI Flows to trigger backend workflows without requiring a full process instance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow selection
> > > >
> > > > Select from available integration workflows
> > >
> > > > [card] Input mapping
> > > >
> > > > Map UI Flow data to workflow input parameters
> > >
> > > > [card] Response handling
> > > >
> > > > Handle workflow responses and update UI state
> > >
> > > > [card] Error handling
> > > >
> > > > Configure error handling for failed workflow executions
> >
> > UI EnhancementAll Deployments
>
> ### **On load UI event**
>
> > [card] [On load UI event](/5.9/docs/building-blocks/ui-designer/event-handlers#triggers)
> >
> > > [tab] Overview
> > >
> > > Execute actions automatically when UI Flow screens load using the new On Load UI Event. This enables initialization logic, data fetching, and setup operations when users navigate to a screen.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic execution
> > > >
> > > > Actions execute automatically when the screen loads
> > >
> > > > [card] Data initialization
> > > >
> > > > Fetch and initialize data when entering a screen
> > >
> > > > [card] Conditional logic
> > > >
> > > > Execute different actions based on conditions
> > >
> > > > [card] Loading states
> > > >
> > > > Manage loading states during initialization
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Integrations
>
> Email integrations, document processing, and Integration Designer updates.
>
> 📬 [**Microsoft Outlook Data Source**](#microsoft-outlook-data-source) - Native MS Graph integration for reading and sending Outlook emails\
> 📧 [**Send Notification Action**](#send-notification-action) - Send emails and reply to received emails directly from processes\
> 🔌 [**Integration Designer Improvements**](#integration-designer-improvements) - Query parameter encoding, config param autocomplete\
> 🔑 [**Security Details in Workflows**](#security-details-in-workflows) - Access user security details in workflow scripts\
> 🔐 [**File Encrypt and Decrypt**](#file-encrypt-and-decrypt) - Encrypt and decrypt files in the Documents Plugin
>
> ### **Microsoft Outlook data source**
>
> > [card] Microsoft Outlook data source
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces a new **Microsoft Outlook** data source type that connects to Outlook mailboxes via the Microsoft Graph API. Unlike Email Trigger (IMAP) and Email Sender (SMTP), this provides a unified data source for both reading and sending emails through native Outlook integration with Azure AD authentication.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> > > >
> > > > See the complete Microsoft Outlook data source documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified read & send
> > > >
> > > > Single data source supports Read Emails, Send Emails, or Read & Send Emails scopes
> > >
> > > > [card] Azure AD authentication
> > > >
> > > > Service account authentication with Tenant ID, Client ID, and Client Secret
> > >
> > > > [card] Email monitoring
> > > >
> > > > Monitor Outlook mailboxes and trigger processes automatically when emails arrive
> > >
> > > > [card] Send & reply
> > > >
> > > > Send new emails or reply to received emails with conversation thread support
> > >
> > > > [card] Attachment validations
> > > >
> > > > Configure allowed file types, max file size, and max file count for incoming emails
> > >
> > > > [card] Test connection
> > > >
> > > > Validate Azure AD credentials and MS Graph permissions before saving
> >
> > > [tab] Configuration
> > >
> > > **Azure AD Authentication:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Tenant ID | Azure AD tenant ID |
> > > | Client ID | Azure AD application (client) ID |
> > > | Client Secret | Azure AD client secret |
> > >
> > > **Scope Options:**
> > >
> > > | Scope | MS Graph Permissions Required |
> > > | - | - |
> > > | Read Emails | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
> > > | Send Emails | `Mail.Send` or `Mail.ReadWrite` |
> > > | Read & Send Emails | One read + one send permission |
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Send Notification action**
>
> > [card] Send Notification action
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces the Send Notification action — a new action type that sends emails directly from process nodes through SMTP, without routing through Kafka. Combined with the new Email Sender data source type, it enables processes to send new emails or reply to emails that triggered the process via Email Trigger.
> > >
> > > > [!NOTE]
> > > >
> > > > Existing notification templates configured for Kafka-based sending continue to work without modification.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> > > >
> > > > See the complete Send Notification action documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Email Sender data source
> > > >
> > > > New SMTP data source type in Integration Designer with SSL/TLS smart port defaults
> > >
> > > > [card] Reply to emails
> > > >
> > > > Reply to emails that triggered the process, maintaining conversation threads
> > >
> > > > [card] Send new emails
> > > >
> > > > Send new outbound emails to specified recipients with CC/BCC support
> > >
> > > > [card] Notification template updates
> > > >
> > > > New Email Server and Email Sender fields for direct SMTP delivery
> > >
> > > > [card] Attachments
> > > >
> > > > Attach files using static paths or process variable keys
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing Kafka-based notification templates continue to work unchanged
> >
> > > [tab] Configuration
> > >
> > > **Email Sender Data Source (new):**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | SMTP (only option) |
> > > | Server Host | SMTP server hostname |
> > > | SSL/TLS | Enable secure connection (default: on) |
> > > | Port | `587` (SSL/TLS on) or `465` (SSL/TLS off) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > >
> > > **Send Notification Action:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Notification Template | Select a template with Predefined Email Connection |
> > > | Reply to received emails | Toggle on to reply to the email that triggered the process |
> > > | Reply to Email Header | Process variable with original email headers (reply mode) |
> > > | Receivers | Recipient email addresses or process variables |
> > > | CC/BCC Receivers | Optional CC and BCC recipients |
> > > | Language | Process variable key for template language |
> > > | Attachments | File path or process variable key |
> > > | Template Data | JSON key-value pairs for dynamic template content |
> > >
> > > > [!TIP]
> > > >
> > > > Available on Send Message Task, Task, and User Task nodes.
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Integration Designer improvements**
>
> > [card] Integration Designer improvements
> >
> > FlowX.AI 5.5.0 adds URL encoding options for REST endpoint query parameters, improved error handling for invalid REST responses, and configuration parameter autocomplete in data source forms.
> >
> > > [card] Query parameter encoding
> > >
> > > Configure whether query parameter values are URL-encoded automatically or sent as-is (for pre-encoded values)
> >
> > > [card] REST Content-Type handling
> > >
> > > Improved error handling when REST endpoints return responses with unexpected Content-Type headers
> >
> > > [card] Config param autocomplete
> > >
> > > Type `$` in data source configuration fields to autocomplete configuration parameters or create new ones inline
> >
> > > [!NOTE]
> > >
> > > See [Integration Designer - Query parameters](/5.1/docs/platform-deep-dive/integrations/integration-designer#query-parameters) for details.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Security details in workflows**
>
> > [card] Security details in workflows
> >
> > Workflow scripts can now access `additionalData.securityDetails` to retrieve the current user's identity. This works when a workflow is started from a **Chat component**, a **UI Flow**, or a **manual run**. Sub-workflows inherit security details from their parent.
> >
> > Unlike processes, where security details are grouped by swimlane and role, workflows use a simplified flat structure:
> >
> > ```json theme={"dark"}
> > {
> >   "securityDetails": {
> >     "username": "user@email.com",
> >     "identifier": "keycloak-subject-id",
> >     "details": {
> >       "firstName": "John",
> >       "lastName": "Snow",
> >       "email": "user@email.com"
> >     }
> >   }
> > }
> > ```
> >
> > > [!NOTE]
> > >
> > > See [Extracting additional data in business rules](/5.1/docs/building-blocks/actions/business-rule-action/extracting-additional-data) for full details and code examples for both processes and workflows.
> >
> > New FeatureAll Deployments
>
> ***
>
> ### **File encrypt and decrypt**
>
> > [card] [File encrypt and decrypt](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files)
> >
> > FlowX.AI 5.5.0 adds new file encryption and decryption actions to the Documents Plugin, enabling processes to encrypt files before storage and decrypt them for authorized access.
> >
> > > [card] File encryption
> > >
> > > Encrypt files using configurable encryption algorithms before storage
> >
> > > [card] File decryption
> > >
> > > Decrypt files for authorized access within process flows
> >
> > InfrastructureAll Deployments
>
> ***

> [tab] Platform & Management
>
> User management, workspace configuration, rendering, and platform improvements.
>
> 🔐 [**Container App Authentication**](#container-app-authentication) - Authentication flow and landing page improvements\
> 🔑 [**Password Policy Updates**](#password-policy-updates) - Updated password complexity requirements\
> 🚫 [**User status DISABLED**](#user-status-disabled) - New DISABLED status for user accounts\
> 📧 [**Resend User Invitation**](#resend-user-invitation) - Resend invitations for pending users\
> 🏷️ [**Workspace Environment Type**](#workspace-environment-type) - Sandbox, Staging, and Production labels for workspaces\
> 🏢 [**Organization ID Propagation**](#organization-id-propagation) - Enhanced multi-tenant isolation\
> ⚡ [**Rendering Runtime UX**](#rendering-runtime-ux) - Runtime UX improvements for rendering\
> 🔍 [**Process Variables Compare**](#process-variables-compare) - Monaco diff editor for process variable values\
> 📧 [**Failed Email Trigger Details Page**](#failed-email-trigger-details-page) - Dedicated details page for failed email triggers\
> 📐 [**Data Model Sidepanel**](#data-model-sidepanel) - Redesigned attribute settings, inline add, and path copy
>
> ### **Container app authentication**
>
> > [card] [Container app authentication](/5.9/docs/saas/container-app-authentication)
> >
> > > [tab] Overview
> > >
> > > Enhanced authentication flow and landing page for generic container applications. Configure authentication providers, customize login pages, and manage user sessions with improved security and user experience.
> >
> > > [tab] Key Features
> > >
> > > > [card] Authentication providers
> > > >
> > > > Support for multiple authentication providers
> > >
> > > > [card] Custom landing page
> > > >
> > > > Customize the landing page for unauthenticated users
> > >
> > > > [card] Session management
> > > >
> > > > Improved session handling and token refresh
> > >
> > > > [card] SSO integration
> > > >
> > > > Seamless single sign-on integration
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Password policy updates**
>
> > [card] [Password policy updates](/5.1/setup-guides/access-management/configuring-an-iam-solution#password-policy)
> >
> > FlowX.AI 5.5.0 updates the password policy with stricter complexity requirements for improved security.
> >
> > **New requirements:**
> >
> > | Rule | Value |
> > | - | - |
> > | Minimum length | 8 characters |
> > | Maximum length | 64 characters |
> > | Complexity | Must include uppercase, lowercase, number, and special character |
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **User status DISABLED**
>
> > [card] [User status DISABLED](/5.9/docs/saas/inviting-users#user-statuses)
> >
> > FlowX.AI 5.5.0 introduces a new **DISABLED** user status. Administrators can now enable or disable user accounts through the **Enable** and **Disable** actions in the user management menu, providing better control over user access without deleting accounts.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Resend user invitation**
>
> > [card] [Resend user invitation](/5.9/docs/saas/inviting-users#resending-invitations)
> >
> > FlowX.AI 5.5.0 adds the ability to resend invitations for users with a **Pending** status, ensuring users who missed or lost their initial invitation can still complete onboarding.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Workspace environment type**
>
> > [card] [Workspace environment type](/5.1/docs/projects/workspaces#workspace-environment-type)
> >
> > FlowX.AI 5.5.0 adds an **Environment Type** dropdown to workspace configuration, allowing administrators to label workspaces as **Sandbox**, **Staging**, or **Production**. This provides clearer context when working across multiple environments.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Organization ID propagation**
>
> > [card] Organization ID Propagation
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 enhances multi-tenant isolation by propagating organization ID across more runtime contexts. This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
> >
> > > [tab] Key Changes
> > >
> > > > [card] Scheduler execution
> > > >
> > > > Organization ID added to scheduled job context
> > >
> > > > [card] Event listeners
> > > >
> > > > Organization ID propagated to event handlers
> > >
> > > > [card] Process instances
> > > >
> > > > Organization ID captured from initiator
> > >
> > > > [card] Audit trail
> > > >
> > > > Enhanced audit logging with organization context
> >
> > InfrastructureSaaS
>
> ***
>
> ### **Rendering runtime UX**
>
> > [card] Rendering runtime UX
> >
> > FlowX.AI 5.5.0 includes various rendering runtime UX improvements for better performance and user experience.
> >
> > > [card] Loading states
> > >
> > > Improved loading state indicators and skeleton screens
> >
> > > [card] Transition animations
> > >
> > > Smoother transitions between screens and states
> >
> > > [card] Error boundaries
> > >
> > > Better error handling with graceful degradation
> >
> > > [card] Performance
> > >
> > > Optimized rendering performance for complex UIs
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process variables compare**
>
> > [card] [Process variables compare](/5.9/docs/projects/runtime/active-process/update-process-variables#compare-view)
> >
> > FlowX.AI 5.5.0 introduces a Monaco diff editor for comparing process variable values, making it easier to identify changes between versions or states.
> >
> > > [card] Diff editor
> > >
> > > Side-by-side comparison of process variable values using Monaco diff editor
> >
> > > [card] Version comparison
> > >
> > > Compare variable values across different process versions
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Failed email trigger details page**
>
> > [card] [Failed email trigger details page](/5.9/docs/platform-deep-dive/integrations/email-trigger#failed-trigger-details-page)
> >
> > FlowX.AI 5.5.0 adds a dedicated details page for failed email triggers, providing better visibility into email processing failures and enabling faster troubleshooting.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Data Model sidepanel**
>
> > [card] Data Model sidepanel
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 redesigns the Data Model editing experience with a new attribute settings side panel, inline add-attribute buttons, and attribute path display. These improvements make it faster to create, configure, and reference data model attributes without switching between menus.
> > >
> > > > [card] [Process Data Model](/5.1/docs/building-blocks/process/data-model#data-model-interface)
> > > >
> > > > See the updated Process Data Model documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Attribute settings side panel
> > > >
> > > > Select any attribute to open a settings panel with type, validations, sensitive data, and reporting options
> > >
> > > > [card] Inline add attribute
> > > >
> > > > Add attributes directly on each data type — button shows on hover after the first attribute
> > >
> > > > [card] Attribute path copy
> > > >
> > > > View and copy the full key path for any attribute for use in business rules and UI bindings
> > >
> > > > [card] Selection highlights
> > > >
> > > > Selecting a data type or connector highlights its location on the canvas
> > >
> > > > [card] Default minimized panel
> > > >
> > > > The Data Types panel starts minimized by default for a cleaner canvas view
> > >
> > > > [card] Confirmation toasts
> > > >
> > > > Success notifications when adding new data types
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### Additional improvements
>
> * **Workflow logs milliseconds** — Workflow execution logs now display timestamps with millisecond precision
> * **Single select in table edit** — SDK enhancement for single-select dropdowns within editable table cells. See [Table component](/5.1/docs/building-blocks/ui-designer/ui-component-types/table#editable-rows)
> * **UI Flows action name optional** — Action names in UI Flows are now optional, reducing configuration overhead
> * **Data mappers editable JSON testing** — Improved JSON testing experience in data mappers with editable input fields
> * **Solutions page load optimization** — Solutions page now loads only projects, improving performance for container apps
> * **Security patches** — General security improvements across platform services

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.5.0](./deployment-guidelines-v5.5).
>
> ### Compatibility
>
> > [!WARNING]
> >
> > **Breaking change:** The default `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 services. Opaque-token introspection has been removed. See the [Deployment Guidelines](./deployment-guidelines-v5.5#breaking-changes) for migration steps.
>
> > [card] Upgrade path
> >
> > Upgrade from v5.4.0 — requires authentication mechanism migration (`SECURITY_TYPE` change)
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.5


# Deployment guidelines v5.6.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/deployment-guidelines-v5.6

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.77.0** | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 |
| **admin** | **10.66.0** | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 |
| **designer** | **10.127.3** | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **cms-core** | **10.43.0** | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 |
| **scheduler-core** | **10.31.0** | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 |
| **events-gateway** | **10.33.1** | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 |
| **notification-plugin** | **10.42.1** | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 |
| **document-plugin** | **10.46.0** | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 |
| **task-management-plugin** | **10.41.1** | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 |
| **data-search** | **10.30.1** | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 |
| **audit-core** | **10.40.0** | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 |
| **advancing-controller** | **10.33.1** | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 |
| **integration-designer** | **10.84.0** | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 |
| **application-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **runtime-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **data-sync** | **10.38.0** | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 |
| **authorization-system** | **10.51.0** | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 |
| **nosql-db-runner** | **10.34.0** | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 |
| **email-gateway** | **10.32.1** | 10.24.0 | 10.9.0 | - | - | - |
| **organization-manager** | **10.26.1** | 10.19.2 | - | - | - | - |
| **webhook-gateway** | **10.1.1** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **iOS renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 |
| **Android renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 |

### Plugins

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.2.3** | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 |
| **di-platform** | **10.3.0** | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 |
| **ai-platform-ai-developer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-connected-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-knowledge-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agents** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-conversations** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-models** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-tenants** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-planner** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-analyst** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-designer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agent-builder** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-binaries** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **knowledgebase** | **10.6.0** | TBD | - | - | - | - |
| **knowledgebase-rag** | **10.6.0** | 10.2.0 | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.0** | 10.2.0 | - | - | - | - |
| **mcp** | **10.6.0** | 10.2.0 | - | - | - | - |
| **doc-converter** | **10.2.2** | - | - | - | - | - |
| **doc-parser** | **10.5.1** | - | - | - | - | - |

> [!NOTE]
>
> **New in 5.6.0:** `webhook-gateway` is a new microservice for processing incoming webhooks. It handles webhook event ingestion and routing to process instances.

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.6.0 | Keycloak | 26+ |
| 5.6.0 | Kafka | 3.8 - 3.9 |
| 5.6.0 | PostgreSQL | 16 - 17 |
| 5.6.0 | Oracle Database | 21c, 23ai |
| 5.6.0 | MongoDB | 7 - 8 |
| 5.6.0 | Redis | 7.4 - 8.0 |
| 5.6.0 | Angular (Web SDK) | 20 |
| 5.6.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.6.0

### Key features and updates

> [card] Chat Driven Workflows
>
> Multi-turn AI conversations with session memory and intent classification

> [card] Incoming Webhooks
>
> Trigger processes from external HTTP POST requests via the new webhook-gateway service

> [card] Web Page Extractor
>
> Collect readable content from web page URLs with crawling and link following

> [card] Proxy Server Connections
>
> Route integration traffic through HTTP/HTTPS proxy servers

> [card] UI Flow Route Management
>
> Query parameters, route maps, and breadcrumb navigation for UI Flows

> [card] MCP Authentication
>
> BEARER and BASIC auth for MCP server connections

## Upgrading from v5.5.0

### Breaking changes

#### WorkspaceCreatedEvent ownership change

> [!WARNING]
>
> The `WorkspaceCreatedEvent` Kafka topic ownership has moved from `authorization-system` to `organization-manager`.

**What changed:**

* `organization-manager` now produces `WorkspaceCreatedEvent` messages
* `authorization-system` no longer produces these events
* Update your Kafka topic ACLs if you manage topic-level permissions

***

#### gRPC thread pool configuration

> [!WARNING]
>
> The default gRPC client thread pool sizes in AI Platform have been updated. Review your deployment configuration if you have custom thread pool settings.

***

### New environment variables

#### Integration Designer

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_WEBHOOKS_BASE_URL` | Base URL for webhook-gateway service communication | `http://webhook-gateway:80` | integration-designer |
| `FLOWX_WEB_CRAWLER_BASE_URL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80` | integration-designer |

#### NoSQL DB Runner

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100` | nosql-db-runner |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL` | Time-to-live for cached external MongoDB connections | `1d` | nosql-db-runner |

#### Process Engine

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts for failed operations | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Base delay between retries (ms) | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum delay between retries (ms) | `200` | process-engine |

#### Authorization System

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD` | Initial password for default realm admin user | *(none)* | authorization-system |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY` | Force password change on first login | `true` | authorization-system |

#### Application Manager

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_RESOURCE_ID_FIELD` | Resource ID field for proxy connection merge | `resourceId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_ID_FIELDS` | Flatten map ID fields for proxy connection merge | `resourceId, name` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection flatten map | `authorization.configuration` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_COMPARE_REMOVED_JSON_PATHS` | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_CONFLICT_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection conflict detection | `resourceId, resourceDefinitionId` | application-manager |

#### Data Search

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | data-search |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | data-search |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | data-search |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | data-search |

#### Email Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | email-gateway |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | email-gateway |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | email-gateway |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | email-gateway |

> [!NOTE]
>
> The SpiceDB and CAS client variables for `data-search` and `email-gateway` are required for authorization integration. These services now use the same SpiceDB-based authorization as other platform services.

#### Webhook Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for webhook registrations database | `jdbc:postgresql://postgresql:5432/webhook_gateway` | webhook-gateway |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` | webhook-gateway |
| `SPRING_DATASOURCE_PASSWORD` | Database password | *(required)* | webhook-gateway |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | OAuth2/OIDC server base URL | — | webhook-gateway |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | — | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account client ID | `flowx-webhook-gateway-sa` | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account client secret | *(required)* | webhook-gateway |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Kafka topic for process start events | `ai.flowx.core.trigger.start-for-event.process.v1` | webhook-gateway |

> [!NOTE]
>
> `webhook-gateway` is a **new microservice** in 5.6.0. It requires its own PostgreSQL database (`webhook_gateway`), Kafka access, Keycloak service account (`flowx-webhook-gateway-sa`), and SpiceDB connectivity.

***

### New Kafka topics

#### Document Plugin

New topic for UI Flow session document persistence.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway | Inbound |
| `ai.flowx.eventsgateway.receive.document.v1` | Document events sent to events-gateway for SSE delivery | Outbound |

#### Webhook Gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Triggers process starts from incoming webhook events | Outbound |

> [!NOTE]
>
> The Webhook Gateway is a **producer-only** service — it receives HTTP webhook requests and publishes process start events to Kafka. It does not consume from any Kafka topics.

#### UI flow session variable updates

New topic for propagating document upload results and workflow completion results to the process-engine, which updates UI flow session variables.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | UI flow session variable updates after document upload or workflow completion | Inbound (process-engine) / Outbound (document-plugin, integration-designer) |

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | process-engine |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Consumer group ID for UI flow updates | `ui-flow-update` | process-engine |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of consumer threads for UI flow updates | `6` | process-engine |

***

### Compatibility

* **SpiceDB**: Now required for `data-search` and `email-gateway` in addition to existing services
* **Renderer Updates**: Web and mobile SDKs include route management, start parameters, enum label display, and chat enhancements
* **Database**: The `start_params` column on `ui_flow_session` table has been renamed to `variables` (auto-migrated via Liquibase). The column now stores all session variables, including start parameters and updates from document uploads and workflow completions

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026

Conversational AI with memory and intent routing, incoming webhooks, proxy connections, unmanaged MongoDB, UI Flow session variables, chat history, and 28 bug fixes.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html)

FlowX.AI 5.6.0 brings **conversational AI** to your apps. Build multi-turn chat experiences where agents remember context, classify user intent, and navigate users to the right screen — all within a single workflow. On the integration side, **incoming webhooks** let external systems start processes via HTTP, **proxy connections** route traffic through intermediary servers, and **unmanaged MongoDB** connects FlowX to your existing database infrastructure. The UI layer gains **session variables**, **route management**, **chat history**, and **suggested prompts** for richer end-user experiences.

> [card] [For AI builders](#conversational-workflows)
>
> Chat Driven workflows, session memory, intent routing, and context retrieval

> [card] [For integrators](#incoming-webhooks)
>
> Incoming webhooks, proxy connections, unmanaged MongoDB, and base64 certificates

> [card] [For UI developers](#ui-flow-session-variables)
>
> Session variables, route management, chat history, suggested prompts, and new UI events

### What changed since 5.5.0

| 5.5.0 | 5.6.0 |
| - | - |
| Output Focused workflows only | + **Chat Driven** workflows with multi-turn memory |
| No event-driven process starts from external systems | **Incoming webhooks** with API key auth |
| FlowX-managed MongoDB only | + **Unmanaged MongoDB** — bring your own database |
| No conversation persistence | **Chat History** — browse and resume past sessions |
| Static chat empty state | **Suggested Prompts** — guide users with one-click starters |
| Certificate file paths only | **Base64 certificates** — paste content directly, no file mounts |
| No cross-page data in UI Flows | **Session variables** — persist data across pages and workflows |

***

**What's new?**

> [tab] AI Platform
>
> Build complete conversational AI pipelines — from understanding what the user wants, to retrieving the right context, to navigating them to the right screen.
>
> 💬 [**Conversational Workflows**](#conversational-workflows) - New Chat Driven workflow type for multi-turn conversations\
> 🧠 [**Memory Capabilities**](#memory-capabilities) - Automatic session memory with summarization across turns\
> 🎯 [**Intent Classification node**](#intent-classification-node) - Classify user messages and route to the right branch in one step\
> 🧭 [**Navigate in UI Flow**](#navigate-in-ui-flow) - Let the AI open forms and screens with contextual data\
> 🔍 [**Context Retrieval node**](#context-retrieval-node) - RAG search against Knowledge Bases without calling an LLM\
> 📄 [**Extract Data from File**](#extract-data-from-file) - Three extraction methods, image support, and signature detection\
> 🌐 [**Web Page Extractor**](#web-page-extractor) - Crawl web pages and extract readable content for AI processing
>
> See also: [Chat History](#chat-history), [Suggested Prompts](#chat-suggested-prompts), and [Markdown in chat](#markdown-in-chat-messages) in the **UI & Designer** tab.
>
> ### **Conversational Workflows**
>
> > [card] Conversational Workflows
> >
> > > [tab] Overview
> > >
> > > Chat Driven workflows are a specialized workflow type for multi-turn chat interactions. Unlike Output Focused workflows that process structured input/output, Chat Driven workflows manage ongoing dialogue — handling message exchange, session memory, and response routing through a dedicated Start node layout (Chat Session ID + User Message) and Custom Agent nodes with direct chat reply capability.
> > >
> > > ![Conversational workflow with Custom Agent configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_config.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> > > >
> > > > See the complete Conversational Workflows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multi-turn conversations
> > > >
> > > > Support for back-and-forth conversations with persistent context
> > >
> > > > [card] Intent routing
> > > >
> > > > Automatically classify user messages and route to appropriate workflow branches
> > >
> > > > [card] Session memory
> > > >
> > > > Built-in session memory with automatic summarization across conversation turns
> > >
> > > > [card] Chat UI components
> > > >
> > > > Dedicated chat component with error handling and shared state management
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Memory Capabilities**
>
> > [card] Memory Capabilities
> >
> > > [tab] Overview
> > >
> > > Conversational workflows include built-in session memory that automatically persists and retrieves conversation history. On each message, the system retrieves the last 3 turns of raw messages plus a summary of earlier exchanges, injecting them into the AI node's system prompt for context-aware responses.
> > >
> > > ![Memory tab showing conversation summary and history](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> > > >
> > > > See the complete Memory Capabilities documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic retrieval
> > > >
> > > > Last 3 turns + summary of earlier exchanges retrieved on each message via sessionId
> > >
> > > > [card] Smart summarization
> > > >
> > > > Older conversation history is automatically summarized to fit within context limits
> > >
> > > > [card] Per-node control
> > > >
> > > > Turn on memory per Custom Agent node with the **Use memory** toggle
> > >
> > > > [card] Memory tab in console
> > > >
> > > > View retrieved memory (raw turns + summary) in the workflow console log
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Intent Classification node**
>
> > [card] Intent Classification Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that combines AI-powered message classification with workflow branching in a single step. Define up to 10 intents with natural language descriptions, and the node classifies user messages and routes to the matching branch automatically — replacing the previous TEXT\_UNDERSTANDING + Condition two-node pattern.
> > >
> > > ![Intent Classification node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intent_classification_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> > > >
> > > > See the complete Intent Classification documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] AI + routing in one node
> > > >
> > > > Combines LLM classification and conditional branching — no separate Condition node needed
> > >
> > > > [card] Natural language conditions
> > > >
> > > > Define intents as plain-text descriptions instead of code expressions
> > >
> > > > [card] Conversation memory
> > > >
> > > > Optionally use past conversation context for more accurate classification
> > >
> > > > [card] Built-in fallback
> > > >
> > > > Automatic "If No Intent Matches" branch handles unrecognized inputs
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Navigate in UI Flow**
>
> > [card] Navigate in UI Flow
> >
> > > [tab] Overview
> > >
> > > A new workflow node exclusive to **Chat Driven** (conversational) workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — for example, the AI says *"Let me open your account details"* and the user sees a pre-filled form with data from the conversation.
> > >
> > > ![Navigate in UI Flow node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node)
> > > >
> > > > See the Navigate in UI Flow section in Conversational Workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Conversational context
> > > >
> > > > Navigate users to UI screens directly from a Chat Driven workflow conversation
> > >
> > > > [card] Dynamic parameters
> > > >
> > > > Pass workflow data to the destination screen using `${expression}` syntax
> > >
> > > > [card] Destination picker
> > > >
> > > > Select from the UI Flow's navigation tree with auto-populated query parameters
> > >
> > > > [card] Chat Driven only
> > > >
> > > > Available exclusively in the Actions category of conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval node**
>
> > [card] Context Retrieval Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that performs RAG (Retrieval-Augmented Generation) searches against Knowledge Bases without calling an LLM. Returns raw chunks with relevance scores and metadata, giving you full control over downstream processing. Supports hybrid, semantic, and keyword search with configurable re-ranking and metadata filters.
> > >
> > > Use Context Retrieval when you need to inspect, filter, or transform chunks before passing them to an LLM — for example, checking relevance scores before generating a response. For all-in-one RAG, use a Custom Agent node with a Knowledge Base attached instead.
> > >
> > > ![Context Retrieval node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the complete Context Retrieval documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] No LLM required
> > > >
> > > > Retrieves chunks directly — no AI generation step, lower latency and cost
> > >
> > > > [card] Multiple search types
> > > >
> > > > Hybrid, semantic, or keyword search with configurable relevance thresholds
> > >
> > > > [card] Metadata filters
> > > >
> > > > Filter chunks by user-defined metadata for scoped retrieval
> > >
> > > > [card] Re-ranking
> > > >
> > > > Optional re-ranking for improved result ordering
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > The workflow node formerly known as "Extract Text from Document" has been renamed to **Extract Data from File** and gained three new configurable settings: **Extraction Method** (LLM Model, OCR Engine, or Text Parsing), **Image Extraction** (Image Description or Image Contents), and **Detect Signatures**. The node now also accepts image files (JPG, PNG, TIFF) in addition to documents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Three extraction methods
> > > >
> > > > Choose between LLM Model (AI vision), OCR Engine (scanned docs), or Text Parsing (digital PDFs) per use case
> > >
> > > > [card] Image support
> > > >
> > > > Process JPG, PNG, and TIFF files alongside PDF, DOCX, XLSX, and PPTX
> > >
> > > > [card] Signature detection
> > > >
> > > > Identify signature areas within documents when using LLM or OCR extraction
> > >
> > > > [card] Moved to Tools category
> > > >
> > > > The node is now in the **Tools** category in the workflow node palette
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor**
>
> > [card] Web Page Extractor
> >
> > > [tab] Overview
> > >
> > > A new workflow node in the **Tools** category that collects readable content from web page URLs. Crawl documentation sites to build a Knowledge Base, scrape product pages for competitive analysis, or extract terms and conditions for compliance review. Supports static URL lists or dynamic URL generation, configurable crawling depth with link following, PDF extraction from linked documents, and adjustable scrape speed presets.
> > >
> > > ![Web Page Extractor node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> > > >
> > > > See the complete Web Page Extractor documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Static or dynamic URLs
> > > >
> > > > Provide a fixed list of up to 20 URLs or generate them dynamically from workflow data
> > >
> > > > [card] Link following
> > > >
> > > > Follow links on pages up to a configurable depth (0–10 levels)
> > >
> > > > [card] PDF processing
> > > >
> > > > Extract content from PDF files linked on crawled pages
> > >
> > > > [card] Speed presets
> > > >
> > > > Choose Slow, Moderate, Fast, or Custom with manual rate limit and concurrency
> >
> > All Deployments

> [tab] Integrations
>
> Connect FlowX to more systems — trigger processes from external events, route traffic through proxies, and query your own MongoDB databases.
>
> 🔗 [**Incoming Webhooks**](#incoming-webhooks) - Trigger processes from external HTTP POST requests\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Route integration traffic through proxy servers\
> 🗄️ [**Unmanaged MongoDB Datasource**](#unmanaged-mongodb-datasource) - Connect to externally managed MongoDB instances\
> 📧 [**Email Trigger Enhancements**](#email-trigger-enhancements) - Resource management, reply-to, and mock email testing\
> 🔐 [**MCP Authentication**](#mcp-authentication) - BEARER and BASIC auth support for MCP server connections\
> 📜 [**Base64 Certificate Support**](#base64-certificate-support) - Provide certificates as base64-encoded strings instead of file paths\
> 📊 [**CSV/Excel to JSON Conversion**](#csv/excel-to-json-conversion) - Download CSV and Excel files as structured JSON on the fly
>
> ### **Incoming Webhooks**
>
> > [card] Incoming Webhooks
> >
> > > [tab] Overview
> > >
> > > A new data source type and microservice (`webhook-gateway`) that allows external systems to trigger FlowX processes via HTTP POST requests. Create a Webhook data source in Integration Designer, connect it to a Message Start Event in your process, and FlowX generates a unique URL with API key authentication. When external systems POST to this URL, a process instance starts automatically with the webhook payload and headers.
> > >
> > > ![Active webhook trigger in Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)
> > >
> > > > [!NOTE]
> > > >
> > > > Requires deploying the new `webhook-gateway` microservice. See [Deployment Guidelines](./deployment-guidelines-v5.6) for configuration.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> > > >
> > > > See the complete Incoming Webhooks documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] API key authentication
> > > >
> > > > Each webhook gets a unique, cryptographically secure API key for authentication
> > >
> > > > [card] JSON payload forwarding
> > > >
> > > > Webhook body and headers are forwarded to the process instance as variables
> > >
> > > > [card] Manage Triggers integration
> > > >
> > > > Activate, deactivate, and monitor webhooks from the Manage Triggers UI
> > >
> > > > [card] API key regeneration
> > > >
> > > > Regenerate API keys without recreating the webhook configuration
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Proxy Server Connections**
>
> > [card] Proxy Server Connections
> >
> > > [tab] Overview
> > >
> > > Create reusable proxy connections in Integration Designer and attach them to RESTful System data sources. Route outbound API traffic through HTTP or HTTPS proxy servers for environments that require intermediary routing for security or compliance.
> > >
> > > ![Proxy Connection configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> > > >
> > > > See the complete Proxy Connections documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] HTTP and HTTPS proxies
> > > >
> > > > Configure HTTP or HTTPS proxy servers with optional basic authentication
> > >
> > > > [card] Reusable connections
> > > >
> > > > Create a proxy once and attach it to multiple RESTful System data sources
> > >
> > > > [card] Test connectivity
> > > >
> > > > Validate proxy configuration before saving with the built-in test function
> > >
> > > > [card] Config parameter support
> > > >
> > > > Use `${param}` syntax in host and port fields for environment-specific values
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Unmanaged MongoDB Datasource**
>
> > [card] Unmanaged MongoDB Datasource
> >
> > > [tab] Overview
> > >
> > > Connect to externally managed MongoDB instances as a data source in FlowX. Unlike the built-in FlowX Database (which provisions and manages MongoDB collections automatically), Unmanaged MongoDB connects to databases and collections you control — with the same CRUD operations, connection discovery, and configurable connection pooling. Requires MongoDB 6.0 or later.
> > >
> > > ![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> > > >
> > > > See the complete Unmanaged MongoDB documentation.
> >
> > All Deployments
>
> ***
>
> ### **Email Trigger Enhancements**
>
> > [card] Email Trigger Enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.6.0 enhances the Email Trigger with resource management capabilities, reply-to-email support, process instance tracking for email-triggered processes, and mock email testing for development.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Resource management
> > > >
> > > > Manage email trigger resources with proper lifecycle controls
> > >
> > > > [card] Reply-to-email
> > > >
> > > > Support for reply-to patterns in email-triggered workflows
> > >
> > > > [card] Process instances
> > > >
> > > > View and track process instances created from email triggers
> > >
> > > > [card] Mock email testing
> > > >
> > > > Test email-triggered processes with mock email content during development
> >
> > All Deployments
>
> ***
>
> ### **MCP Authentication**
>
> > [card] MCP Authentication
> >
> > > [tab] Overview
> > >
> > > MCP server connections now support **BEARER** and **BASIC** authentication methods. Configure auth credentials when adding an MCP data source to connect to secured MCP servers.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source)
> > > >
> > > > See the Adding MCP Data Source documentation.
> >
> > All Deployments
>
> ***
>
> ### **Base64 Certificate Support**
>
> > [card] Base64 Certificate Support
> >
> > > [tab] Overview
> > >
> > > RESTful system data sources now support providing keystore and truststore content as **base64-encoded strings** instead of file paths. A new "Certificate type" selector lets you choose between Base64 (default for new configurations) and Path (existing behavior). Additionally, keystore and truststore passwords now support `${configParam}` placeholder syntax for dynamic per-environment resolution.
> > >
> > > ![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#certificates)
> > > >
> > > > See the Integration Designer certificates documentation.
> >
> > All Deployments
>
> ***
>
> ### **CSV/Excel to JSON Conversion**
>
> > [card] CSV/Excel to JSON Conversion
> >
> > > [tab] Overview
> > >
> > > Download CSV, XLS, or XLSX files as structured JSON directly from the file download endpoints. The conversion happens on the fly using the `Accept: application/json` header — no new files are created in storage. Supports two output formats: an array of objects (one per row) or a columnar structure.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats#csv/excel-to-json-conversion)
> > > >
> > > > See the Document Conversion documentation.
> >
> > All Deployments

> [tab] UI & Designer
>
> Richer end-user experiences with session state, chat history, and navigation — plus Designer productivity improvements.
>
> 🗺️ [**UI Flow Route Management**](#ui-flow-route-management) - Configure routes, query parameters, and navigation in UI Flows\
> ▶️ [**UI Flow Start Parameters**](#ui-flow-start-parameters) - Pass parameters when starting UI Flows\
> 💾 [**UI Flow Session Variables**](#ui-flow-session-variables) - Persist data across pages from workflows and file uploads\
> 📋 [**Chat History**](#chat-history) - Browse and resume past chat conversations\
> 💡 [**Chat Suggested Prompts**](#chat-suggested-prompts) - Pre-configured prompt suggestions in chat empty state\
> 🖱️ [**onClick UI events**](#onclick-ui-events) - Client-side data updates on Button and Collection Prototype clicks\
> ✨ [**Monaco Editor Autocomplete**](#monaco-editor-autocomplete) - Autocomplete from config params in code editors\
> 📊 [**KB query results in workflow console**](#kb-query-results-in-workflow-console) - View retrieved chunks and relevance scores during workflow runs\
> 📎 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Upload multiple files simultaneously\
> ❌ [**DISMISS UI action**](#dismiss-ui-action) - Dismiss modals automatically after Start Workflow completes\
> 🎨 [**Process Variables UX**](#process-variables-ux-improvements) - UI/UX improvements for updating process variables\
> 🏷️ [**Enum label display**](#enum-label-display) - Show enum labels instead of codes in text components\
> 📬 [**Notification template usages**](#notification-template-usages) - See where notification templates are used\
> 📐 [**Side Panel in Data Model**](#side-panel-in-data-model) - Improved data model navigation with side panel\
> 👁️ [**On Display UI event**](#on-display-ui-event) - Re-trigger actions every time a screen becomes visible\
> 🪟 [**On Load event on Modal**](#on-load-event-on-modal) - Modal components now support On Load events\
> 🏗️ [**KB user-defined metadata**](#kb-user-defined-metadata) - Define custom metadata keys on Knowledge Base content sources\
> ⚙️ [**Config params in workflow conditions**](#config-params-in-workflow-conditions) - Use config params and user details in workflow Fork node expressions\
> 🎨 [**Branding settings grouping**](#branding-settings-grouping) - Reorganized branding settings page\
> ✍️ [**Markdown in chat messages**](#markdown-in-chat-messages) - Render formatted text, links, and lists in chat responses\
> 🔗 [**External Action dynamic URL**](#external-action-dynamic-url) - Use expressions in External Action URLs for dynamic navigation\
> 📬 [**Notification history**](#notification-history) - View sent notification details and search by process instance
>
> ### **UI Flow Route Management**
>
> > [card] UI Flow Route Management
> >
> > > [tab] Overview
> > >
> > > Define query parameters on root views (Pages, Modals), pass data between screens via URL query strings, and get automatic breadcrumb generation from the navigation graph. Navigate To actions support destination parameter mapping with `${expression}` syntax for dynamic values.
> > >
> > > ![Route parameters modal with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#route-management)
> > > >
> > > > See the Route Management section in UI Flows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Route parameters
> > > >
> > > > Define named query parameters on root views with default values and required flags
> > >
> > > > [card] Parameter passing
> > > >
> > > > Map data from process store to destination query parameters using JSON expressions
> > >
> > > > [card] Auto breadcrumbs
> > > >
> > > > Breadcrumbs auto-generate from the navigation graph with proper parameter handling
> > >
> > > > [card] Modal URL state
> > > >
> > > > Modals add `modalId` to URL — survives page reload and supports deep linking
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Start Parameters**
>
> > [card] UI Flow Start Parameters
> >
> > > [tab] Overview
> > >
> > > Pass initial data when launching a UI Flow. Define start parameters as a JSON object in the Designer's Run dialog, extract them from URL query strings in SaaS container apps, or send them in the API request body. Parameters are persisted on the session and available throughout the UI Flow lifecycle.
> > >
> > > ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#start-parameters)
> > > >
> > > > See the Start Parameters section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Session Variables**
>
> > [card] UI Flow Session Variables
> >
> > > [tab] Overview
> > >
> > > UI Flow sessions can now persist variables across all pages sharing the same session ID. Data from start parameters, workflow outputs, and file upload responses is automatically collected and merged into session variables. Reference them in component configurations using `${}` syntax. A new **Variables** tab in the Designer session console shows current values for debugging.
> > >
> > > ![Variables tab in UI Flow session console](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#session-variables)
> > > >
> > > > See the Session Variables section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **Chat History**
>
> > [card] Chat History
> >
> > > [tab] Overview
> > >
> > > Users can now browse and resume past chat conversations. Chat History displays a list of previous sessions grouped by time (Today, Yesterday, Previous 7 Days, Previous 30 Days, Older), with the ability to open any conversation and continue where they left off. Conversations are per-user with access control enforced.
> > >
> > > ![Chat History panel with conversation list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#chat-history)
> > > >
> > > > See the Chat History section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Chat Suggested Prompts**
>
> > [card] Chat Suggested Prompts
> >
> > > [tab] Overview
> > >
> > > The Chat component now supports pre-configured **Suggested Prompts** — pill buttons displayed below the welcome message in the chat empty state. Configure a title and up to 5 prompt options in the Designer. When a user clicks a suggestion, it is submitted as their message, starting the conversation immediately.
> > >
> > > ![Suggested Prompts in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#suggested-prompts)
> > > >
> > > > See the Suggested Prompts section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Monaco Editor Autocomplete**
>
> > [card] Monaco Editor Autocomplete
> >
> > > [tab] Overview
> > >
> > > Code editors in the Designer now provide autocomplete suggestions from your project's configuration parameters. This speeds up writing business rules and expressions that reference config params.
> > >
> > > > [card] [Documentation](/5.1/docs/projects/runtime/configuration-parameters-overrides)
> > > >
> > > > See the Configuration Parameters documentation.
> >
> > All Deployments
>
> ***
>
> ### **Process Variables UX improvements**
>
> > [card] Process Variables UX
> >
> > > [tab] Overview
> > >
> > > UI/UX improvements to the Update Process Variables experience, making it easier to view and edit runtime process data.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > > >
> > > > See the Update Process Variables documentation.
> >
> > All Deployments
>
> ***
>
> ### **onClick UI events**
>
> > [card] onClick UI events
> >
> > > [tab] Overview
> > >
> > > Buttons and Collection Prototypes now support **onClick** UI events — client-side JavaScript expressions that execute immediately when clicked, *before* any configured UI actions fire. Use them for instant local data updates without server roundtrips.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-events)
> > > >
> > > > See the UI Events documentation.
> >
> > All Deployments
>
> ***
>
> ### **KB query results in workflow console**
>
> > [card] KB Query Results
> >
> > > [tab] Overview
> > >
> > > The workflow run console now includes a **Knowledge Base** tab that displays retrieved chunks, relevance scores, content sources, and metadata when Custom Agent nodes query a knowledge base. This makes it easier to debug and tune RAG-powered workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows)
> > > >
> > > > See Using Knowledge Base in Workflows.
> >
> > All Deployments
>
> ***
>
> ### **Multi-file bulk upload**
>
> > [card] Multi-file Bulk Upload
> >
> > > [tab] Overview
> > >
> > > Upload multiple files simultaneously at runtime using the new [Multiple File Upload](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload) component. Supports drag-and-drop, batch selection, per-file validation, and progress tracking. Available in both process screens and UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **DISMISS UI action**
>
> > [card] DISMISS Action
> >
> > > [tab] Overview
> > >
> > > The Start Workflow UI action now includes a **Dismiss modal** checkbox. When enabled, the modal closes automatically after the workflow completes — removing the need for a separate close action.
> >
> > All Deployments
>
> ***
>
> ### **Enum label display**
>
> > [card] Enum Label Display
> >
> > > [tab] Overview
> > >
> > > Text components can now display the human-readable **label** of an enumeration value instead of the raw code. When a data key references an enumeration, the renderer resolves the selected code to its label at display time. Enumeration values are also prefetched from the data model before action resolution for improved performance.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations#displaying-enum-labels-in-text-components)
> > > >
> > > > See the Enumerations documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification template usages**
>
> > [card] Notification Template Usages
> >
> > > [tab] Overview
> > >
> > > Notification templates now show a **usages** modal that lists all processes and workflows referencing the template. This helps you understand the impact of changes before editing or deleting a template.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > > >
> > > > See the Managing Notification Templates documentation.
> >
> > All Deployments
>
> ***
>
> ### **Side Panel in Data Model**
>
> > [card] Side Panel in Data Model
> >
> > > [tab] Overview
> > >
> > > The Data Model editor now includes a side panel for easier navigation and editing of data model attributes, improving the workflow when working with large data models.
> >
> > All Deployments
>
> ***
>
> ### **On Display UI event**
>
> > [card] On Display UI event
> >
> > > [tab] Overview
> > >
> > > A new `onDisplay` event type that triggers every time a screen becomes visible — on initial load, when navigating back, or when a modal is dismissed. Unlike On Load (which fires once), On Display re-triggers on every view, making it ideal for refreshing data.
> > >
> > > Supported on Page, Zone, and Tab Bar components in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **On Load event on Modal**
>
> > [card] On Load event on Modal
> >
> > > [tab] Overview
> > >
> > > Modal components in UI Flows now support the On Load event and Start Workflow action. This enables data fetching when a modal opens, allowing you to load context-specific data for modal content.
> >
> > All Deployments
>
> ***
>
> ### **KB user-defined metadata**
>
> > [card] KB user-defined metadata
> >
> > > [tab] Overview
> > >
> > > Define custom metadata keys on Knowledge Bases and assign values to content sources. User-defined metadata enables filtering and scoping when searching chunks — for example, by department, document version, or region. Metadata values are propagated to the vector database and can be used as filters in the Context Retrieval workflow node.
> >
> > All Deployments
>
> ***
>
> ### **Config params in workflow conditions**
>
> > [card] Config params in workflow conditions
> >
> > > [tab] Overview
> > >
> > > Workflow Fork (condition) nodes can now access configuration parameters via `additionalData.applicationConfiguration` and authenticated user details via `additionalData.securityDetails` in their expressions. This enables environment-aware routing and user-based branching in integration workflows.
> >
> > All Deployments
>
> ***
>
> ### **Branding settings grouping**
>
> > [card] Branding settings grouping
> >
> > > [tab] Overview
> > >
> > > The branding settings page has been reorganized with improved grouping and layout, making it easier to find and configure branding options.
> >
> > All Deployments
>
> ***
>
> ### **Markdown in chat messages**
>
> > [card] Markdown in Chat Messages
> >
> > > [tab] Overview
> > >
> > > Chat message components in web renderers now support Markdown rendering. AI-generated responses can include formatted text, headings, links, code blocks, and lists — displayed with proper styling in the chat interface.
> >
> > All Deployments
>
> ***
>
> ### **External Action dynamic URL**
>
> > [card] External Action Dynamic URL
> >
> > > [tab] Overview
> > >
> > > External Action URLs now support `${expression}` syntax for dynamic values. Build destination URLs using process data, config params, or computed values — enabling context-aware external navigation from UI Flows.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-actions#external-ui-actions)
> > > >
> > > > See the UI Actions documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification history**
>
> > [card] Notification History
> >
> > > [tab] Overview
> > >
> > > New REST API endpoints on the notification plugin let you retrieve sent notification history. Query a paginated summary list filtered by app and optionally by process instance, or fetch full notification details by ID — including recipients, subject, body, and the source process/action that triggered it.
> > >
> > > * `GET /api/notification/summary` — paginated summary list with filtering and sorting
> > > * `GET /api/notification/{id}` — full notification details including body and recipients
> >
> > > [tab] Key Features
> > >
> > > > [card] Summary and detail views
> > > >
> > > > Paginated summary list for browsing, with full detail drill-down by notification ID
> > >
> > > > [card] Source tracking
> > > >
> > > > Each notification records which process, node, and action triggered it for full traceability
> >
> > All Deployments

> [tab] SaaS
>
> User management and branding improvements for SaaS deployments.
>
> 👤 [**Runtime User Invitations**](#runtime-user-invitations) - Invite runtime users directly to test projects\
> 🏢 [**Workspace Type Display**](#workspace-type-display) - See workspace type within Designer\
> 🎨 [**Container App Branding**](#container-app-branding) - Customize branding for SaaS container apps\
> 👥 [**Designer User Invitations**](#designer-user-invitations) - Updated invite modal for designer users
>
> ### **Runtime User Invitations**
>
> > [card] Runtime User Invitations
> >
> > > [tab] Overview
> > >
> > > Invite runtime users directly to test projects from within the Designer. Simplifies the process of granting test access without requiring full workspace-level permissions.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS
>
> ***
>
> ### **Workspace Type Display**
>
> > [card] Workspace Type Display
> >
> > > [tab] Overview
> > >
> > > The Designer now displays the workspace type (development, staging, production) directly within the workspace view, making it easier to identify your current environment.
> >
> > SaaS
>
> ***
>
> ### **Container App Branding**
>
> > [card] Container App Branding
> >
> > > [tab] Overview
> > >
> > > Customize your SaaS container app branding at the organization level — upload a custom logo, set primary and secondary colors, toggle the header, and configure the solutions page background.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/container-app-branding)
> > > >
> > > > See the Container App Branding documentation.
> >
> > SaaS
>
> ***
>
> ### **Designer User Invitations**
>
> > [card] Designer User Invitations
> >
> > > [tab] Overview
> > >
> > > The invite modal for designer users has been redesigned with clearer role selection, group assignment, and a streamlined layout for inviting multiple users.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS

> [tab] Bug Fixes
>
> ## Bug fixes
>
> ### Core Platform
>
> * **Authorization-system Oracle DB startup** — Fixed an issue where the authorization-system service failed to start when using Oracle as the configured database.
> * **Process definition merge timing** — Fixed a race condition where the process definition was updated before the merge was finalized.
> * **Theme import with builds** — Fixed an issue where themes were not included when importing builds.
> * **Library import permissions** — Fixed an issue where importing a library into a workspace redirected to a 403 error page.
> * **App version reimport** — Fixed an error that occurred when reimporting an app version (project or library).
> * **Email resend after URL expiry** — Fixed an issue where the resend email endpoint returned 200 OK but no email was sent after the URL expired.
> * **Platform status discovery** — Fixed an authorization error when trying to force discover platform status.
> * **Runtime roles in permissions** — Fixed inconsistent runtime roles display in the permissions dropdown.
>
> ### AI Platform & Workflows
>
> * **gRPC thread pool sizing** — Fixed under-provisioned gRPC client thread pools that caused socket timeouts and dropped requests in production.
> * **API error trace IDs** — API errors now include a reference to the active traceID for easier debugging.
> * **Cross-project resource copy** — Fixed an issue where copying a workflow resource to another project did not include LDM objects.
> * **Multi-instance mappings** — Fixed a 400 error when saving multi-instance mappings in data mappers.
> * **Email trigger mock testing** — Fixed errors when starting a process from a build with mock email content.
> * **Multiple start nodes with email trigger** — Fixed an issue where only one start option was displayed when a process contained multiple start nodes with email triggers.
>
> ### Renderers & UI
>
> * **Angular input field crash** — Fixed an issue where pressing Enter in an input field caused the Angular UI to crash.
> * **Floating Chat interaction blocking** — Fixed an issue where the floating chat component blocked all interaction with page content while open.
> * **S3 internal bucket error** — Fixed an error when the integration-designer downloads files from document-plugin via downloadPath.
> * **File upload second attempt** — Fixed an issue where upload requests were not made when uploading a second file.
> * **UI Flow analytics** — Fixed issues where analytics events were not visible and not saved for Navigate-to action types.
> * **Task management column selection** — Fixed an issue where the Last Updated column remained selected in task management.
> * **Task Manager theming and UX** — Multiple fixes for Task Manager theming, dropdown display, comment field styling, and user assignment behavior.
> * **Toggle/checkbox label alignment** — Fixed an issue where the switch toggle/checkbox or label shifted position when in an error state.&#x20;
> * **Query parameters lost after refresh** — Fixed an issue where URL query parameters were lost after page refresh in UI Flows.&#x20;
> * **SSE connection management** — Fixed multiple issues where SSE connections were opened twice or not closed properly after messages were received.&#x20;
> * **Modal layering** — Fixed incorrect layering when a loader modal was displayed on top of another modal.&#x20;
> * **Card theming overrides** — Fixed an issue where card theming overrides were not applied when the card was collapsed.&#x20;
> * **On Display workflow triggering** — Fixed an issue where past On Display workflows were not re-triggered on page refresh.&#x20;
>
> ### Knowledge Base
>
> * **KB metadata handling** — Fixed multiple issues with Knowledge Base user-defined metadata: empty properties on content source creation, metadata not available for content sources added through apps, and incorrect cleanup when deleting metadata keys.&#x20;

> [tab] Info
>
> ## Additional information
>
> ### At a glance
>
> This release includes **30+ new features and enhancements** across AI Platform, Integrations, UI & Designer, and SaaS — plus **28 bug fixes** spanning Core Platform, AI/Workflows, Renderers, and Knowledge Base.
>
> ***
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6).
>
> For new environment variables and Kafka topics, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6#new-environment-variables).
>
> ### Changes to be aware of
>
> > [!NOTE]
> >
> > FlowX.AI 5.6.0 is a SaaS-managed release — deployment-level changes (infrastructure, Kafka topics, service configuration) are handled automatically by FlowX. The items below are listed for transparency and for future reference when on-prem support ships in 5.7+.
>
> #### API change (action required if you use this endpoint)
>
> > [!WARNING]
> >
> > **Process definition start metadata endpoint renamed** — `GET /api/process-definition/{uuid}/get-input-json` has been renamed to `GET /api/process-definition/{uuid}/get-start-metadata`. Update any API clients or custom integrations that call this endpoint directly.
> >
> > The response now includes an additional `hasEmailTriggerStart` boolean field.
>
> #### Infrastructure changes (managed by FlowX on SaaS)
>
> * **gRPC thread pool configuration** — Default gRPC client thread pool sizes have been updated for better production throughput.
> * **WorkspaceCreatedEvent ownership** — Kafka topic ownership moved from `authorization-system` to `organization-manager`.
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.5.0 — if you call `get-input-json` directly, update to `get-start-metadata`. All other changes are managed automatically on SaaS.
>
> > [card] [Component versions](./deployment-guidelines-v5.6#component-versions)
> >
> > See the Deployment Guidelines for the full component version matrix


# Deployment guidelines v5.7.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7

Component versions, environment variables, and configuration changes for FlowX.AI 5.7.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.96.0** | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 |
| **admin** | **10.83.0** | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 |
| **designer** | **10.164.0** | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **cms-core** | **10.58.0** | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 |
| **scheduler-core** | **10.45.0** | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 |
| **events-gateway** | **10.47.0** | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 |
| **notification-plugin** | **10.56.0** | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 |
| **document-plugin** | **10.64.0** | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 |
| **task-management-plugin** | **10.57.0** | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 |
| **data-search** | **10.44.0** | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 |
| **audit-core** | **10.54.0** | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 |
| **advancing-controller** | **10.45.0** | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 |
| **integration-designer** | **10.113.0** | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 |
| **application-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **runtime-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **data-sync** | **10.50.0** | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 |
| **authorization-system** | **10.68.0** | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 |
| **nosql-db-runner** | **10.48.0** | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 |
| **email-gateway** | **10.47.0** | 10.32.1 | 10.24.0 | 10.9.0 | - | - |
| **organization-manager** | **10.44.0** | 10.26.1 | 10.19.2 | - | - | - |
| **webhook-gateway** | **10.15.0** | 10.1.1 | - | - | - | - |
| **license** | **10.36.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |

### Plugins

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 |
| **ai-platform-ai-assistant** | **10.6.2** | - | - | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 |
| **ai-platform-ai-developer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-connected-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-knowledge-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agents** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-conversations** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-tenants** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-planner** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-analyst** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-designer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agent-builder** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-binaries** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **embedder** | **10.6.2** | - | - | - | - | - |
| **knowledgebase-rag** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **mcp** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **doc-converter** | **10.2.3** | 10.2.2 | - | - | - | - |
| **doc-parser** | **10.6.2** | 10.5.1 | - | - | - | - |
| **web-crawler** | **10.3.2** | - | - | - | - | - |
| **data-privacy** | **10.0.8** | - | - | - | - | - |
| **speech-to-text** | **10.3.3** | - | - | - | - | - |
| **modpod** | **10.0.7** | - | - | - | - | - |

> [!NOTE]
>
> **Note:** The `ai-platform-models` service has been removed in 5.7.0. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers) within the Organization Manager.

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.7.0 | Keycloak | 26+ |
| 5.7.0 | Kafka | 3.8 - 3.9 |
| 5.7.0 | PostgreSQL | 16 - 17 |
| 5.7.0 | Oracle Database | 21c, 23ai |
| 5.7.0 | MongoDB | 7 - 8 |
| 5.7.0 | Redis | 7.4 - 8.0 |
| 5.7.0 | Elasticsearch | 8 |
| 5.7.0 | Angular (Web SDK) | 20 |
| 5.7.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> The following versions of third-party dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

***

## Self-hosted deployment changes

> [!WARNING]
>
> **First on-premises release since 5.4.0.** This section covers critical configuration changes for self-hosted (on-premises) deployments.

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **Fresh install** | Supported | Guided setup flow on first launch. See [Organization Manager setup](/5.1/setup-guides/organization-manager-setup). |
| **5.1.x LTS** | Supported | Requires Organization ID on all 19 services. Liquibase migrates active process instances and realm data. Inactive instances require separate handling by FlowX. See details below. |
| **5.2 - 5.4** | FlowX-assisted only | These versions may have partial realm or organization changes. Contact your FlowX representative for a custom migration plan. Do **not** follow the 5.1.x upgrade path. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

### Organization ID (mandatory for upgrades)

The Organization ID is how FlowX identifies your installation. How it is obtained depends on your deployment path:

* **Fresh install:** The Organization ID is created automatically during the guided setup flow (Designer first-launch screen). No manual configuration needed.
* **Upgrade from 5.1.x:** FlowX registers your organization in the SaaS licensing infrastructure and provides an Organization ID (UUID). Set `ORGANIZATION_ID` on **all 19 services** before deploying 5.7.0 images — Liquibase migrations use it to replace the default organization.

```yaml theme={"dark"}
# Example — set on every service
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

**Affected services (all 19):** process-engine, admin, audit-core, authorization-system, advancing-controller, events-gateway, cms-core, scheduler-core, data-search, document-plugin, nosql-db-runner, notification-plugin, task-management-plugin, integration-designer, organization-manager, email-gateway, application-manager, runtime-manager, license.

> [!WARNING]
>
> Do **not** deploy 5.7.0 images without setting `ORGANIZATION_ID` on upgrade scenarios. Services will fail to start if Liquibase migrations cannot find the organization ID.

> [!NOTE]
>
> **Active vs inactive instances.** Liquibase migrations automatically update the Organization ID on **active process instances** only. Inactive or archived instances require separate migration handled by the FlowX team during guided deployment. Contact your FlowX representative for details.

### License service (new)

Self-hosted deployments must configure the License service to connect to FlowX SaaS for license validation and usage reporting. See the [License service setup guide](/5.9/setup-guides/license-engine-setup) for complete configuration.

### IAM / Keycloak changes

FlowX.AI now uses a **two-realm architecture** in Keycloak and **JWT public key validation** (replacing opaque-token introspection). These changes were introduced in 5.5.0 (SaaS) and are now relevant for self-hosted deployments.

* **Token validation**: `security.type` switches from `oauth2` to `jwt-public-key` on all services
* **Service accounts realm**: A dedicated realm (`00000002-0002-4002-8002-000000000002`) holds all service account clients, separate from the user realm
* **Organization manager**: Now a required dependency for all services (provides realm resolution)
* **`flowx-platform-authorize` client**: No longer needed — remove from Keycloak
* **Master realm credentials**: The authorization-system service needs Keycloak admin access for realm migrations. If you cannot provide admin credentials, see [Manual Keycloak configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).
* **SMTP**: Must be configured in Keycloak for password reset and user invitations

For complete IAM setup instructions, see the [Configuring an IAM solution](/5.1/setup-guides/access-management/configuring-an-iam-solution) guide.

***

## Environment info deprecation

The **Configure Environment Info** feature (`PATCH /api/platform/environment`) is deprecated and removed. Environment name is now set during organization registration. The following are no longer used:

* `FLOWX_CLIENT_NAME` environment variable
* `FLOWX_ENVIRONMENT_NAME` environment variable
* `environmentDetails` section in the `/api/init` response

***

## Kafka integration changes

### Fx-Organization-Id header (mandatory)

All FlowX Kafka consumers now validate the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected with a non-retryable `MissingKafkaHeaderException`.

> [!WARNING]
>
> **Action required for custom Kafka integrations.** If you have custom Kafka producers that publish directly to FlowX topics (starting processes, sending task events, responding to engine requests), you must add the `Fx-Organization-Id` header to every message. Set it to the Organization UUID (`ORGANIZATION_ID` value).
>
> ```java theme={"dark"}
> producerRecord.headers().add("Fx-Organization-Id",
>     organizationId.getBytes(StandardCharsets.UTF_8));
> ```
>
> See the [Creating a Kafka producer](/5.1/docs/platform-deep-dive/integrations/creating-a-kafka-producer#important-headers) guide for details.

### New Kafka topics

| Topic | Environment Variable | Producer | Consumer | Description |
| - | - | - | - | - |
| `ai.flowx.llm.config.changed.v1` | `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | organization-manager | integration-designer, AI Python services | Broadcast when LLM provider or model configuration changes at the organization level |

***

## Environment variables

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `ORGANIZATION_ID` | Organization UUID provided by FlowX. Required on all services for upgrades. Fresh installs get this automatically via the setup flow. | - | all services |
| `FLOWX_LICENSE_KEY` | License key for FlowX SaaS connection | - | license |
| `FLOWX_LICENSE_AUTHSERVERURL` | FlowX SaaS auth URL | - | license |
| `FLOWX_LICENSE_SERVERURL` | FlowX SaaS license API URL | - | license |
| `FLOWX_ORG_MANAGER_URL` | Organization Manager service URL for LLM provider configuration. Required on all Python AI services. | - | planner, ai-developer, ai-analyst, ai-designer, agent-builder, knowledgebase-rag, embedder, knowledgebase |
| `SECURITY_MASTERREALM_CLIENTID` | Master realm admin client ID for Keycloak management | `admin-cli` | authorization-system |
| `SECURITY_MASTERREALM_NAME` | Keycloak master realm name | `master` | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username for realm migrations | - | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password for realm migrations | - | authorization-system |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` | all services |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL for security lib | `http://organization-manager:80` | all services |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `60` | organization-manager |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `30` | organization-manager |
| `FLOWX_SPEECH_TO_TEXT_BASE_URL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` | integration-designer |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Topic for LLM config change notifications | `ai.flowx.llm.config.changed.v1` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys at rest. **Change from default in production.** | `default-dev-key-change-in-prod` | organization-manager |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required on on-prem deployments. | - | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required on on-prem deployments when the FlowX generic container app is deployed. | - | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If empty, derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` | organization-manager |
| `DEFAULT_ORGANIZATION_NAME` | Fallback organization code used by the Designer web app during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present. Required on on-prem — set to the organization code registered with FlowX. | - | designer |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for Oracle Database schema discovery responses cached for the SQL editor. | `24h` | integration-designer |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools used by Oracle Database data sources. | `100` | nosql-db-runner |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached JDBC connection pools. | `1d` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per Oracle Database data source. | `5` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout for Oracle Database data sources. | `10` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses for Oracle Database operations. | `1000` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout for Oracle Database operations. | `30` | nosql-db-runner |

### Removed environment variables

> [!WARNING]
>
> **For upgrades:** Remove these variables only **after** the Liquibase migrations have completed successfully. If you remove them before starting services for the first time on 5.7.0, the migrations may fail. The recommended sequence is: (1) add new variables, (2) deploy 5.7.0 images, (3) let migrations run, (4) verify services are healthy, (5) remove old variables in a follow-up deployment.

| Environment Variable | Reason | Component |
| - | - | - |
| `FLOWX_CLIENT_NAME` | Replaced by org code from registration | process-engine |
| `FLOWX_ENVIRONMENT_NAME` | Replaced by env name from registration | process-engine |
| `AI_SERVICE_MODELS_ENDPOINT` | The Models microservice (port 9104) has been removed. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers). Remove this service from your deployment. | ai-platform (all Python services) |
| `SECURITY_OAUTH2_REALM` | Replaced by per-organization realm resolution. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | Opaque-token introspection client no longer needed. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | Opaque-token introspection client secret no longer needed. | all services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_*` | Entire opaque-token introspection config removed. | all services |


# FlowX.AI 5.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/v5.7.0-april-2026

Single-org on-premises deployment, custom React components, AI providers self-service, chat-based UI Flows, voice input, end-user access management, and advanced query builder.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

FlowX.AI 5.7.0 makes on-premises deployment a first-class experience. **Single-org deployment** is now the default mode — configure your organization once, connect to FlowX licensing, and you're running. For builders, **Custom Components** let you write React code directly in the Designer, **AI Providers** configuration gives organizations self-service control over their LLM setup, and **Chat-based UI Flows** simplify conversational experiences. For organization admins, **End-user access management** separates runtime users, roles, and groups from Designer users.

> [card] [For platform teams](#single-org-deployment)
>
> Single-org deployment, license service, organization setup flow

> [card] [For builders](#custom-components)
>
> Custom React components, AI provider config, chat-based UI Flows, voice input

> [card] [For admins](#end-user-access-management)
>
> End-user access management, runtime roles, and groups

### What changed since 5.6.0

| 5.6.0 | 5.7.0 |
| - | - |
| SaaS-focused deployment | + **Single-org on-premises** as the default mode |
| Built-in UI components only | + **Custom React Components** with code editor and dependencies |
| AI models configured by FlowX | + **AI Providers self-service**: OpenAI (FlowX Managed or BYOK), custom URL, Defaults & Fallbacks per workspace type |
| Chat workflow set per component | + **Chat-based UI Flows**: set one workflow for the entire UI Flow |
| Text-only chat input | + **Voice input** for chat conversations |
| No audio processing in workflows | + **Speech to Text** node for transcription and text-to-speech |
| Runtime users mixed with Designer users | + **End-user access management**: separate org-level lists for end-users, roles, and groups, with CSV bulk invite |
| Basic query filters | + **Advanced Query Builder** for database operations |
| MongoDB-only database data sources | + **Oracle Database** as a new data source type with schema-aware SQL editor |
| Fixed search strategy for KB retrieval | + **Context Retrieval**: configurable search type (Hybrid/Semantic/Keyword) and re-ranking |
| Equality-only metadata filters, AND logic | + **Knowledge Base filter builder** with typed operators and AND/OR grouping; **Content Sources** tab renamed to **Stores** |
| Basic merge modal | + **Merge conflicts UX**: redesigned modal, diff viewer theme, keyboard support |

***

**What's new?**

> [tab] Platform
>
> FlowX 5.7.0 introduces single-org deployment as the default mode for on-premises installations, with self-service licensing, organization management, and runtime access controls.
>
> 🏢 [**Single-org deployment**](#single-org-deployment) - On-premises deployment with automatic organization setup\
> 🔑 [**License service**](#license-service) - Connect to FlowX SaaS for license validation and usage reporting\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level end-users, roles, and groups, separate from Designer users
>
> ### **Single-org deployment**
>
> > [card] Single-org deployment
> >
> > > [tab] Overview
> > >
> > > Self-hosted deployments now run as single-organization systems by default. FlowX registers your organization in the SaaS licensing infrastructure, provides an Organization ID, and your deployment connects to FlowX for license validation and usage reporting. The Designer guides you through a setup flow on first launch: enter a token, name your environment, and create your admin user.
> > >
> > > > [card] [Documentation](/5.1/setup-guides/organization-manager-setup#organization-id-configuration)
> > > >
> > > > See the Organization Manager setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Guided setup flow
> > > >
> > > > Designer walks you through organization registration on first launch
> > >
> > > > [card] Organization ID
> > > >
> > > > Mandatory on all services for Liquibase migrations on upgrades
> > >
> > > > [card] License connectivity
> > > >
> > > > On-premises license service connects to FlowX SaaS for validation and usage
> > >
> > > > [card] Multi-org features hidden
> > > >
> > > > Registration, org selection, and org switching are not available on-prem
> > >
> > > > [card] Explicit web app URLs
> > > >
> > > > Designer and Runtime URLs are configured via dedicated on-prem env vars on organization-manager, replacing hard-coded org-code lookup
> >
> > Major FeatureSelf-Hosted
>
> ***
>
> ### **License service**
>
> > [card] License service
> >
> > > [tab] Overview
> > >
> > > The License service is the bridge between your self-hosted deployment and FlowX SaaS. It validates your platform license, reports usage data, and ensures your subscription is active. Configure it with the license key and server URLs provided by FlowX during organization registration.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> > > >
> > > > See the License service setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] License validation
> > > >
> > > > Continuous license sync with FlowX SaaS
> > >
> > > > [card] Usage reporting
> > > >
> > > > AI node execution consumption reported to FlowX
> > >
> > > > [card] Organization events
> > > >
> > > > Listens to organization lifecycle events via Kafka
> > >
> > > > [card] Setup guide
> > > >
> > > > Complete setup guide with PostgreSQL, Kafka, Redis, and SpiceDB configuration
> >
> > Self-Hosted
>
> ***
>
> ### **End-user access management**
>
> > [card] End-user access management
> >
> > > [tab] Overview
> > >
> > > Organization admins can now manage the people who use published solutions separately from Designer users. A new **Access Management** section at the organization level holds three lists — **End-Users**, **End-Users Roles**, and **End-Users Groups** — each with its own permissions. Invite end users individually or import many at once from a CSV template, define roles that describe runtime access, and organize users into groups with custom attributes for filtering.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> > > >
> > > > See the End-user access management setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Separate end-user list
> > > >
> > > > End-Users are kept distinct from Designer users, with their own read/write permissions
> > >
> > > > [card] End-user roles
> > > >
> > > > Define named roles that describe runtime access at the organization level
> > >
> > > > [card] End-user groups
> > > >
> > > > Group users by department, region, or any attribute, and assign roles to the whole group
> > >
> > > > [card] Bulk invite
> > > >
> > > > Invite many users at once from a CSV template with names and attributes
> >
> > All Deployments
>
> ***

> [tab] AI & Chat
>
> Self-service AI provider configuration, chat-based UI Flows, AI Triggers, and voice input for conversational experiences.
>
> 🤖 [**AI Providers**](#ai-providers) - Organization-level LLM provider and model configuration\
> 💬 [**Chat-based UI Flows**](#chat-based-ui-flows) - Set a conversational workflow for the entire UI Flow\
> 🎤 [**Voice input**](#voice-input) - Speech-to-text input in chat conversations\
> ⏹️ [**Stop agent response**](#stop-agent-response) - Cancel an in-progress agent reply from the chat input\
> 🗣️ [**Speech to Text node**](#speech-to-text-node) - Transcription and text-to-speech workflow node\
> ⚡ [**AI Triggers**](#ai-triggers) - Named message templates for launching conversational workflows with context\
> 🧩 [**UI Flow Context**](#ui-flow-context) - Pass UI state from a Page to a conversational workflow\
> 🎯 [**Recommended prompts**](#recommended-prompts) - AI-generated follow-up suggestions in chat conversations\
> 🔎 [**Context Retrieval enhancements**](#context-retrieval-enhancements) - Configurable search type and re-ranking\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - Stores rename, typed metadata filters, AND/OR grouping\
> 🌐 [**Web Page Extractor enhancements**](#web-page-extractor-enhancements) - URL filtering, crawl depth, and file downloads
>
> ### **AI Providers**
>
> > [card] AI Providers
> >
> > > [tab] Overview
> > >
> > > Organizations can now configure their own AI providers and assign models at the organization level. Configure **OpenAI** (Bring Your Own Key or FlowX Managed) or **Azure OpenAI** for deployment-based access to GPT models, enable specific models, and assign default and fallback models per AI capability and workspace type (Sandbox, Staging, Production). **Defaults & Fallbacks** now includes an **Audio Capabilities** row used by the Speech to Text node, with `whisper-1` available in the OpenAI model catalog.
> > >
> > > ![Model Providers page with OpenAI and Azure OpenAI configured at the organization level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_view_org.png)
> > >
> > > ![Provider Details modal showing OpenAI and Azure OpenAI as provider options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_model_Provider.png)
> > >
> > > ![Defaults and Fallbacks page with capability rows including Audio Capabilities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/defaults_and_fallbacks.png)
> > >
> > > ![Model selection and configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ai_models_selection.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/ai-providers)
> > > >
> > > > See the AI providers and model configuration documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Organization-level providers
> > > >
> > > > Add and manage AI providers with API keys and connection settings
> > >
> > > > [card] Azure OpenAI
> > > >
> > > > Connect to Azure-hosted OpenAI deployments with a base URL and API version
> > >
> > > > [card] Custom model entry
> > > >
> > > > Add models manually for providers that use deployment names (Azure) or non-public catalogs
> > >
> > > > [card] Audio Capabilities
> > > >
> > > > New row in Defaults & Fallbacks for transcription and speech synthesis, used by the Speech to Text node
> > >
> > > > [card] Defaults & Fallbacks
> > > >
> > > > Assign default and fallback models per AI capability and workspace type
> > >
> > > > [card] Fallback strategy
> > > >
> > > > Set fallback models on different providers for resilience
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat-based UI Flows**
>
> > [card] Chat-based UI Flows
> >
> > > [tab] Overview
> > >
> > > UI Flows now support two experience types: **Flow-Based** (traditional) and **Chat-Based** (conversational). Chat-Based UI Flows connect to a conversational workflow at the UI Flow level, so all Chat components in the flow use the same workflow by default. A new Settings page with a Chat Options tab lets you configure or change the workflow after creation.
> > >
> > > ![Chat-based UI Flow configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_based_ui_flow.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> > > >
> > > > See the UI Flows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Experience types
> > > >
> > > > Choose Flow-Based or Chat-Based when creating a UI Flow
> > >
> > > > [card] UI Flow Settings
> > > >
> > > > New Settings page with Chat Options tab for workflow configuration
> > >
> > > > [card] Workflow filtering
> > > >
> > > > Chat components only show conversational workflows in the selector
> > >
> > > > [card] Navigate in UI Flow
> > > >
> > > > AI can open specific screens with parameters from a conversation
> >
> > All Deployments
>
> ***
>
> ### **Chat improvements**
>
> > [card] Chat improvements
> >
> > Configure which parts of the chat header are visible on a per-component basis. The Chat component (when display type is **Fill**) gains a **Show Header** toggle in its Properties panel, and the Chat Header component gets a new **Available Actions** accordion with toggles for **New Conversation** and **History**. Conversation history now loads in pages, with a **Load more** action, and conversations are sorted by creation date with the most recent first.
> >
> > All Deployments
>
> ***
>
> ### **Voice input**
>
> > [card] Voice input
> >
> > > [tab] Overview
> > >
> > > Chat components now support voice input, allowing users to record audio messages directly in the chat. Users can record, preview with an audio player, and send voice messages within conversations.
> > >
> > > > [!NOTE]
> > > >
> > > > Voice input captures and sends audio recordings. When paired with the [Speech to Text](/5.9/ai-platform/agent-builder/speech-to-text) workflow node, voice messages are automatically transcribed and processed as text in conversational workflows.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audio recording
> > > >
> > > > Record voice messages directly in the chat input
> > >
> > > > [card] Audio preview
> > > >
> > > > Preview recordings with a built-in audio player before sending
> >
> > All Deployments
>
> ***
>
> ### **Stop agent response**
>
> > [card] Stop agent response
> >
> > > [tab] Overview
> > >
> > > The chat input now shows a **Stop** button in place of Send while an agent reply is streaming. Pressing Stop cancels the conversational workflow instance: any in-flight AI call is aborted, partial output is discarded, and the user prompt is persisted with a `cancelled` flag so the chat history reflects what happened.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Cross-platform
> > > >
> > > > Available on Web (Standard, Floating, Full Screen), iOS, and Android
> > >
> > > > [card] Themeable
> > > >
> > > > New `stopResponseIcon` slot in `chatInputArea` themes; preloaded by cms-core
> > >
> > > > [card] Localized
> > > >
> > > > New system substitution tags for Stop and Send labels with a11y variants
> >
> > All Deployments
>
> ***
>
> ### **Speech to Text node**
>
> > [card] Speech to Text
> >
> > > [tab] Overview
> > >
> > > A new workflow node that converts between audio and text. **Transcribe** converts audio files (MP3, WAV, M4A, AAC, OGG) into text with language detection and confidence scores. **Text to Speech** generates audio files from text with configurable voice, speed, and format. In conversational workflows, the node processes voice messages from the chat UI automatically.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> > > >
> > > > See the Speech to Text node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Transcription
> > > >
> > > > Convert audio to text with language detection and confidence scores
> > >
> > > > [card] Text to Speech
> > > >
> > > > Generate audio from text with configurable voice, model, speed, and format
> > >
> > > > [card] Chat voice integration
> > > >
> > > > Automatically transcribes voice messages in conversational workflows
> > >
> > > > [card] Multiple file sources
> > > >
> > > > Read from Document Plugin, S3, or chat input
> >
> > > [!NOTE]
> > >
> > > The transcription model is resolved from the organization's **Audio** capability default, configured in **AI Settings** under [Defaults & Fallbacks](/5.9/ai-platform/ai-providers).
> >
> > All Deployments
>
> ***
>
> ### **AI Triggers**
>
> > [card] AI Triggers
> >
> > > [tab] Overview
> > >
> > > Define named message templates with parameters on conversational workflows, so different UI Flow pages can launch the same workflow with different starting contexts. Triggers are configured in a dedicated side nav tab and selected on the Start node or sent from the Chat component at runtime.
> > >
> > > ![Reply Triggers list in a conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_reply_trigger.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Parameterized messages
> > > >
> > > > Message templates with `${paramName}` placeholders resolved at runtime
> > >
> > > > [card] Multi-page reuse
> > > >
> > > > Different pages launch the same workflow with different context
> > >
> > > > [card] Start node integration
> > > >
> > > > Toggle between Text and AI Trigger modes on the Start node
> > >
> > > > [card] Memory aware
> > > >
> > > > Trigger messages saved to conversation memory but hidden from chat history
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Context**
>
> > [card] UI Flow Context
> >
> > > [tab] Overview
> > >
> > > Conversational workflows can now receive a JSON context alongside the user message. A new **Conversation Context** property on UI Flow Pages lets you define the Parameters payload (with `${expression}` resolution), and the Start node exposes it as a collapsible **UI Flow Context** editor — also available in the Run Workflow test modal for manual runs.
> > >
> > > ![Start node UI Flow Context and UI Flow Conversation Context property](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#setting-context-from-a-ui-flow)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] UI-driven context
> > > >
> > > > Pages attach a JSON payload to conversational runs without hard-coding it in the workflow
> > >
> > > > [card] Expression resolution
> > > >
> > > > Parameters support `${expression}` syntax to bind live UI Flow data at runtime
> > >
> > > > [card] Start node field
> > > >
> > > > Collapsible UI Flow Context editor on the Start node for both runtime and manual testing
> > >
> > > > [card] JSON validation
> > > >
> > > > Invalid JSON is rejected before the run starts, surfacing a clear error
> >
> > All Deployments
>
> ***
>
> ### **Recommended prompts**
>
> > [card] Recommended prompts
> >
> > > [tab] Overview
> > >
> > > Custom Agent nodes can now generate follow-up prompt suggestions alongside their chat replies. When enabled via the new **Prompt Suggestions** satellite panel on a Custom Agent node, the agent includes recommended next questions or actions in its response. These appear as clickable suggestions in the chat UI, guiding users toward relevant follow-up interactions.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions)
> > > >
> > > > See the Custom Agent node documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Satellite panel
> > > >
> > > > Configure prompt suggestions directly on Custom Agent nodes in the workflow editor
> > >
> > > > [card] AI-generated suggestions
> > > >
> > > > Agent generates contextual follow-up prompts based on the conversation
> > >
> > > > [card] Clickable in chat
> > > >
> > > > Suggestions render as tappable chips in the chat UI
> > >
> > > > [card] Conversational workflows
> > > >
> > > > Works with send-as-reply mode in conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval enhancements**
>
> > [card] Context Retrieval enhancements
> >
> > > [tab] Overview
> > >
> > > **Custom Agent** and **Context Retrieval** nodes now support configurable **search type** and **re-ranking** for Knowledge Base retrieval. Choose between Hybrid (default), Semantic, or Keyword search strategies depending on your use case. Turn on re-ranking to apply a secondary relevance model that reorders retrieved chunks for higher-quality results.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the Context Retrieval node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Search type
> > > >
> > > > Choose Hybrid, Semantic, or Keywords search for Knowledge Base retrieval on Custom Agent and Context Retrieval nodes
> > >
> > > > [card] Re-ranking
> > > >
> > > > Apply a re-ranking model to reorder results by relevance to the query — available on both Custom Agent and Context Retrieval nodes
> >
> > All Deployments
>
> ***
>
> ### **Knowledge Base enhancements**
>
> > [card] Knowledge Base enhancements
> >
> > > [tab] Overview
> > >
> > > The Knowledge Base data source gets a refreshed workspace and a more powerful metadata filter builder. The **Content Sources** tab is now called **Stores**, and the Chunks tab gains a structured query builder for metadata filters with typed operators, AND/OR logic, and grouping — replacing the previous equality-only filters.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > > >
> > > > See the Knowledge Base content management guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Stores tab
> > > >
> > > > The Content Sources tab is renamed to Stores. Same concept, clearer label.
> > >
> > > > [card] Typed filter operators
> > > >
> > > > Operators per metadata type: equals, not equals, contains, in, not in, before, after, exists, size equals, and more
> > >
> > > > [card] AND/OR grouping
> > > >
> > > > Combine conditions with AND or OR and nest them in groups for non-trivial logic
> > >
> > > > [card] Query builder on Chunks tab
> > > >
> > > > Test retrieval with Search Type (Hybrid/Semantic/Keywords), Use Re-rank, and the new filter builder
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor enhancements**
>
> > [card] Web Page Extractor enhancements
> >
> > > [tab] Overview
> > >
> > > The Web Page Extractor node now supports **URL filtering** to include or exclude specific URL patterns during crawling, **configurable crawl depth** for more control over how deep the crawler follows links, and **file downloads** to retrieve attached files from crawled pages.
> >
> > > [tab] Key Features
> > >
> > > > [card] URL filtering
> > > >
> > > > Include or exclude URLs matching specific patterns during crawling
> > >
> > > > [card] Crawl depth
> > > >
> > > > Configure how many levels deep the crawler follows links
> > >
> > > > [card] File downloads
> > > >
> > > > Download attached files from crawled web pages
> > >
> > > > [card] Bulk document type
> > > >
> > > > When file downloads are enabled, the document type auto-sets to **Bulk** so a single crawl can return multiple documents
> >
> > All Deployments
>
> ***

> [tab] UI & Components
>
> Custom React components, advanced query builder, and merge conflict improvements.
>
> 🧩 [**Custom Components**](#custom-components) - Write React code in Designer and use in UI Flows\
> 🔍 [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder for database operations\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor\
> 🔀 [**Merge conflicts UX**](#merge-conflicts-ux) - Improved merge modal and conflict resolution experience
>
> ### **Custom Components**
>
> > [card] Custom Components
> >
> > > [tab] Overview
> > >
> > > Create custom React components directly in FlowX Designer. Write JSX, CSS, and use pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Components receive process data through input keys and can trigger process actions. Define once in Reusable Resources, use across multiple User Tasks.
> > >
> > > ![Custom Components code editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> > > >
> > > > See the Custom Components documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Code editor
> > > >
> > > > Write React JSX and CSS with a built-in code editor and file tree
> > >
> > > > [card] Pre-defined packages
> > > >
> > > > React, Emotion, Lodash, Axios, and date-fns available out of the box
> > >
> > > > [card] Process integration
> > > >
> > > > Receive process data via input keys and trigger process actions
> > >
> > > > [card] Import/Export
> > > >
> > > > Export as ZIP and import into other projects
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Advanced Query Builder**
>
> > [card] Advanced Query Builder
> >
> > > [tab] Overview
> > >
> > > A visual query builder for database operations and metadata filters, replacing manual JSON query writing with a structured interface. Build complex queries with conditions, grouping, and sorting without writing raw queries. The operator set has expanded with NULL checks (`exists`, `is null`), set membership (`not in`), string matching (`contains`, `starts with`, `ends with`), boolean tests (`is true`, `is false`), and date comparators (`before`, `after`). The `between` operator has been removed from the UI.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> > > >
> > > > See the FlowX Database documentation for the full query builder reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] Visual conditions
> > > >
> > > > Build query conditions with a structured UI instead of raw JSON
> > >
> > > > [card] Grouping and sorting
> > > >
> > > > Combine conditions with AND/OR grouping and configure result sorting
> > >
> > > > [card] Schema awareness
> > > >
> > > > Fields auto-populated from your collection schema with type-aware operators
> > >
> > > > [card] Visual/Script toggle
> > > >
> > > > Switch between visual builder and raw code editor at any time
> >
> > All Deployments
>
> ***
>
> ### **Oracle Database integration**
>
> > [card] Oracle Database integration
> >
> > > [tab] Overview
> > >
> > > Connect FlowX workflows to externally managed Oracle databases. Configure a connection (Oracle 19c, 21c, or 23ai), save parameterized SQL queries against the schema, and call them from the existing Database Operation node alongside other data sources.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> > > >
> > > > See the Oracle Database integration guide for the full reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] SERVICE\_NAME or SID
> > > >
> > > > Connect via Service Name or SID, with an optional SSL toggle
> > >
> > > > [card] Schema-aware SQL editor
> > > >
> > > > Monaco editor with syntax highlighting, autocomplete, and a side panel for tables, columns, primary keys, and foreign keys
> > >
> > > > [card] Test queries inline
> > > >
> > > > Run SQL with sample parameters: table view for SELECT, affected-row count for INSERT, UPDATE, and DELETE
> > >
> > > > [card] Workflow integration
> > > >
> > > > Pick the Oracle data source and query from the Database Operation node, with no new node type required
> >
> > All Deployments
>
> ***
>
> ### **Datasource Experience**
>
> > [card] Datasource Experience
> >
> > The **Add Data Source** dialog now groups data source types into four categories (**AI Capabilities**, **APIs**, **Databases**, and **Connectors**) with a search box for finding a specific type. REST endpoint authoring also suggests common HTTP headers and values to speed up integration setup.
> >
> > ![New Add Data Source dialog with categorized data source types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_new_data_source.png)
> >
> > All Deployments
>
> ***
>
> ### **MongoDB-aware code editor**
>
> > [card] MongoDB-aware code editor
> >
> > Operation editors on MongoDB data sources now use a Monaco language provider tuned for MongoDB. The editor highlights MongoDB operators (Comparison, Logical, Element, Evaluation, Array, Update, Aggregation, Conditional) and `${param}` interpolations, including inside string literals. Three autocomplete flows speed up authoring: typing `$` lists MongoDB operators, opening a quote in a field-name position lists the schema field paths from the linked Project Data Type, and typing inside `${...}` lists the operation's parameter keys.
> >
> > All Deployments
>
> ***
>
> ### **Project Data Model authoring**
>
> > [card] Project Data Model authoring
> >
> > Three improvements make Project Data Model authoring easier and less error-prone.
> >
> > > [card] Go to source
> > >
> > > A new **Go to source** button on data-model usages and Data Model nodes jumps directly to the source definition without manual navigation.
> >
> > > [card] Type-aware example values
> > >
> > > The example-value input on each attribute now matches its declared type: number inputs for NUMBER, a date picker for DATE, a true/false dropdown for BOOLEAN, single-select for enums, multi-select chips for enum arrays, and so on. CURRENCY values use the currency code rather than the symbol.
> >
> > > [card] Type-aware test data
> > >
> > > The same type-aware inputs apply when running or testing a workflow node and when filling input parameters for a reusable function, replacing the previous generic text inputs.
> >
> > All Deployments
>
> ***
>
> ### **Stop Run for workflows**
>
> > [card] Stop Run for workflows
> >
> > You can now cancel a running workflow instance directly from the workflow editor. While a workflow is running, the **Run Workflow** button switches to **Stop Run** — clicking it cancels the instance and marks all in-progress and scheduled nodes as cancelled. Cancelled instances show a new **Cancelled** status alongside Started, Finished, and Failed.
> >
> > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#running-and-stopping-workflows)
> > >
> > > See Running and stopping workflows in the Integration Designer reference.
> >
> > All Deployments
>
> ***
>
> ### **Merge conflicts UX**
>
> > [card] Merge conflicts UX
> >
> > The merge branches experience has been improved with a redesigned merge modal, better form validation with detailed error messages, and keyboard support (submit with Enter). The conflict resolution diff viewer now uses a new CodeMirror theme that matches the Monaco editor styling for a consistent visual experience.
> >
> > All Deployments
>
> ***

> [tab] Bug fixes
>
> ## Bug fixes
>
> ### AI Platform
>
> | Issue | Description |
> | - | - |
> | Custom Agent WebSocket stability | Fixed WebSocket 1006 abnormal closure for Custom Agent nodes with large payloads by upgrading AI SDK to handle Spring Framework 7's 64KB frame aggregation limit |
> | Azure OpenAI structured output | Fixed silent hang on Azure OpenAI for Custom Agents, Intent Classification, and Recommended Prompts when the response JSON schema lacked title and description fields |
> | Custom Agent node stuck | Fixed Custom Agent node getting stuck in running state |
> | MCP tool updates not working | Fixed an issue where updating tools on an existing MCP Server did not persist changes |
> | KB append performance | Fixed slow execution of the Append Knowledge Base node |
> | KB chunking on append | Fixed an issue where appended content via JSON in the Update Knowledge Base node was not chunked |
> | REST node with base64 certificate | Fixed error when running a workflow with a REST node using a REST system with a base64 certificate |
> | Workflow dependencies copy | Fixed dependencies not being copied for already-copied workflows |
>
> ### Core Platform
>
> | Issue | Description |
> | - | - |
> | Import pipeline issues | Fixed API issues in the import pipeline |
> | Enum CSV import losing changes | Fixed an issue where importing enumerations via CSV on committed resources did not update the resource modified date, causing changes to appear lost |
> | Data model duplicate key on import | Fixed a MongoDB duplicate key error when importing data model slices with duplicate entries |
> | Config params page not loading | Fixed GET config params endpoint not being called when accessing the Configuration Parameters page |
> | Enum default values dropdown | Fixed only first-level enum objects being displayed in the default values dropdown |
> | Data model loading state | Fixed user getting stuck in loading state after an error on data model keep operation |
>
> ### UI & Renderers
>
> | Issue | Description |
> | - | - |
> | Select component clear icon | Fixed misaligned clear icon on Select components in both Angular and React renderers |

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > **Self-hosted deployments:** FlowX 5.7.0 introduces the Organization ID as a mandatory configuration on all services. See the [deployment guidelines](./deployment-guidelines-v5.7) for complete upgrade instructions.
>
> ### Compatibility
>
> > [card] [Upgrade path](./deployment-guidelines-v5.7#supported-upgrade-paths)
> >
> > See the deployment guidelines for supported upgrade paths from 5.1.x LTS, 5.2–5.4, and 5.5–5.6.
>
> > [card] [Component versions](./deployment-guidelines-v5.7#component-versions)
> >
> > See the deployment guidelines for the full component version matrix and third-party dependency support.


# Deployment guidelines v5.8.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/deployment-guidelines-v5.8

Component versions, environment variables, and configuration changes for FlowX.AI 5.8.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.106.0** | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 |
| **admin** | **10.93.0** | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 |
| **designer** | **10.181.0** | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 |
| **cms-core** | **10.67.0** | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 |
| **scheduler-core** | **10.53.0** | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 |
| **events-gateway** | **10.55.0** | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 |
| **notification-plugin** | **10.64.0** | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 |
| **document-plugin** | **10.75.0** | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 |
| **task-management-plugin** | **10.66.0** | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 |
| **data-search** | **10.52.0** | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 |
| **audit-core** | **10.63.0** | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 |
| **advancing-controller** | **10.55.0** | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 |
| **integration-designer** | **10.128.0** | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 |
| **application-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **runtime-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **data-sync** | **10.58.0** | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 |
| **authorization-system** | **10.77.0** | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 |
| **nosql-db-runner** | **10.56.0** | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 |
| **email-gateway** | **10.56.0** | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 | - |
| **organization-manager** | **10.53.0** | 10.44.0 | 10.26.1 | 10.19.2 | - | - |
| **webhook-gateway** | **10.25.0** | 10.15.0 | 10.1.1 | - | - | - |
| **license** | **10.46.0** | 10.36.0 | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |

### Plugins

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 |
| **ai-platform-ai-assistant** | **10.7.0** | 10.6.2 | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **ai-platform-ai-developer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-connected-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-knowledge-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agents** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-conversations** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-tenants** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-analyst** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-designer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agent-builder** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-binaries** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **embedder** | **10.7.0** | 10.6.2 | - | - | - |
| **knowledgebase-rag** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **knowledgebase-indexer-v2** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **mcp** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **doc-parser** | **10.7.0** | 10.6.2 | 10.5.1 | - | - |
| **web-crawler** | **10.3.5** | 10.3.2 | - | - | - |
| **data-privacy** | **10.1.0** | 10.0.8 | - | - | - |
| **speech-to-text** | 10.3.3 | 10.3.3 | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | - | - | - |

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.8.0 | Keycloak | 26+ |
| 5.8.0 | Kafka | 3.8 - 3.9 |
| 5.8.0 | PostgreSQL | 16 - 17 |
| 5.8.0 | Oracle Database | 21c, 23ai |
| 5.8.0 | MongoDB | 7 - 8 |
| 5.8.0 | Redis | 7.4 - 8.0 |
| 5.8.0 | Elasticsearch | 8 |
| 5.8.0 | Angular (Web SDK) | 20 |
| 5.8.0 | React (Web SDK) | 18.x |

***

## Self-hosted deployment changes

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **5.7.0** | Supported | Standard upgrade. |
| **5.1.x LTS** | Supported | Direct upgrade from 5.1.x to 5.8.0 is supported. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

***

## Kafka integration changes

### New Kafka topics

| Topic | Producer | Producer env var | Consumer | Consumer env var |
| - | - | - | - | - |
| `ai.flowx.license.events.v1` | organization-manager | `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | license | `KAFKA_TOPIC_LICENSE_IN_EVENTS` |
| `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | admin | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` | knowledgebase-indexer-v2 | n/a (Python constant) | embedder | n/a (Python constant) |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` | embedder | n/a (Python constant) | knowledgebase-indexer-v2 | n/a (Python constant) |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | (no env var; resolved from `kafka.topic.naming.*`) | document-plugin | `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` |

**License lifecycle events** are delivered from FlowX SaaS to the on-prem license service.

**Custom-component correction requests** complement the existing process / business-rule / reusable-template / ui-flow correction topics that the admin orchestrator already consumed.

**UI Flow multi-file upload** sends a single bulk command to document-plugin in place of the per-file pattern. The plugin persists each file in the session, emits one SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) at the end of the batch via events-gateway, and forwards per-file results to the existing `ai.flowx.core.trigger.ui-flow.update.v1` topic.

**KB embedding-request / embedding-response** replace the previous gRPC `EmbedderService` path (`BulkGenerateEmbeddings` / `GenerateEmbeddings`); the indexer now publishes one embedding job per chunk and the embedder writes points to Qdrant directly, emitting `KbStoreEntryStateChanged` once all chunks for an entry are persisted.

> [!NOTE]
>
> The two `core-services` topic names (`license.events`, `application-version.correction-after-app-operation.custom-component.request`) resolve from the standard `${kafka.topic.naming.prefix}` / `${kafka.topic.naming.suffix}` machinery: default prefix `ai.flowx.` (empty environment segment), default suffix `.v1`. Operators that want an environment-prefixed topic name (e.g., `ai.flowx.dev.license.events.v1`) set `kafka.topic.naming.environment` globally rather than overriding individual topics. The two AI Platform topics are hard-coded constants in the indexer and embedder and do not participate in the prefix machinery.

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX. Initialized with the `notset` sentinel; replace it with the value FlowX provides before the license service starts. Type changed from UUID to String in 5.8.0. | `notset` | license |
| `KAFKA_CONSUMER_GROUPID_LICENSE_EVENTS` | Kafka consumer group used by the license service to receive license events. | `license-events` | license |
| `KAFKA_CONSUMER_THREADS_LICENSE_EVENTS` | Listener container concurrency for the license-events consumer. | `1` | license |
| `KAFKA_TOPIC_LICENSE_IN_EVENTS` | License events topic consumed by the license service. | `ai.flowx.license.events.v1` | license |
| `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | Same topic, producer-side binding on organization-manager. | `ai.flowx.license.events.v1` | organization-manager |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | Custom-component correction-request topic, producer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` | Same topic, consumer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | admin |
| `MANAGEMENT_HEALTH_REDIS_TIMEOUT` | Spring Boot Actuator timeout for the Redis health indicator (in ms). | `5000` | all services using Redis |
| `SPRING_CACHE_REDIS_PERSISTENCEKEYPREFIX` | Prefix applied to Redis keys for the advancing-controller cache. | `flowx:core:cache:advancing-controller:` | advancing-controller |
| `REDIS_COMMAND_TIMEOUT` | Redis command timeout in ms. Fail-fast during master failover. Bound via `${REDIS_COMMAND_TIMEOUT:5000}` placeholder on `spring.data.redis.timeout`. | `5000` | all services using Redis |
| `REDIS_CONNECT_TIMEOUT` | Redis connection establishment timeout in ms. Bound via `${REDIS_CONNECT_TIMEOUT:5000}`. | `5000` | all services using Redis |
| `REDIS_POOL_MAX_ACTIVE` | Maximum number of active Redis connections in the pool. | `10` | all services using Redis |
| `REDIS_POOL_MAX_IDLE` | Maximum number of idle Redis connections retained in the pool. | `5` | all services using Redis |
| `REDIS_POOL_MIN_IDLE` | Minimum number of idle Redis connections kept warm in the pool. | `1` | all services using Redis |
| `REDIS_POOL_MAX_WAIT` | Maximum time to wait for an available connection from the pool, in ms. | `2000` | all services using Redis |
| `FLOWX_METRICS_STUCKCHECKINTERVALMS` | Interval at which the stuck-events metric scheduler runs (ms). Bound from the inline `@Value("${flowx.metrics.stuck-check-interval-ms:60000}")` default; not in `application.yml`. | `60000` | advancing-controller |
| `FLOWX_METRICS_STUCKTHRESHOLDMINUTES` | Age threshold (in minutes) above which an advancing event is considered stuck. Bound from `@Value("${flowx.metrics.stuck-threshold-minutes:5}")`. | `5` | advancing-controller |
| `FLOWX_DATAPRIVACY_BASEURL` | Base URL for the new Data Privacy service. Required when any AI workflow node enables the Personal Information Guard. | `http://data-privacy:80` | integration-designer |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60` | integration-designer |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. Producer-side is the matching `kafka.topic.session.upload.bulk.out` on process-engine, which resolves from the standard naming machinery. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | document-plugin |

### Removed environment variables

| Environment Variable | Replaced by | Component |
| - | - | - |
| `FLOWX_SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Removed with the move to single-pod scheduler execution (plat-1549, `commons-scheduler-lib`). No replacement; only one scheduler pod runs now. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_ENABLED` | Same. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_PROVIDER` | Same. | application-manager, license |
| `SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Same. | integration-designer, process-engine |

***


# FlowX.AI 5.8.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/v5.8.0-may-2026

Runtime authorization overhaul, UI Flow permissions, Custom Components in Processes, new theme components, Angular bulk file upload, and webhook provider adapters.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

Sharing a FlowX solution used to mean handing out admin keys. **5.8.0 changes that.** The AI Developer now ships the React component you wished you'd had time to build, PII never reaches your LLM by accident, and you can finally invite a reviewer without giving them the platform.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html)

### What changed since 5.7.0

| 5.7.0 | 5.8.0 |
| - | - |
| End-user access management with org-level roles and groups | + **Runtime authorization** with project-version-scoped roles, groups, and attribute-based assignment |
| UI Flows accessible to any runtime user | + **UI Flow permissions**: assign roles per UI Flow, evaluated at runtime |
| Custom Components in UI Flows only (Phase 1, React) | + **Custom Components in Processes** with shared data model, input/output mappings, and AI Developer generation |
| Built-in UI components | + **Tooltip, Markdown, Progress Bar, Separator** as new theme components |
| React-only multi-file upload | + **Angular SDK bulk file upload** |
| Generic webhook gateway | + **Webhook provider adapters** (Slack, with HMAC signing-secret validation) |
| Oracle Database (basic SQL editor) | + **Richer SQL autocomplete** in the Monaco editor: operators, schema-aware tables/columns, and `:paramName` interpolations |
| No personal-information guardrails on AI workflow nodes | + **PII Guard** with input/output scans, sensitivity presets, and an entity catalog |

***

**What's new?**

> [tab] Platform
>
> 🔐 [**Runtime authorization**](#runtime-authorization) - Project-scoped roles, end-user groups in FlowX, and Solutions → Share flow\
> 📋 [**UI Flow permissions**](#ui-flow-permissions) - Role-based UI Flow visibility with runtime enforcement

> [tab] Builders
>
> 🧩 [**Custom Components in Processes**](#custom-components-in-processes) - Bundled CCs in Process User Tasks with shared data model\
> 🎨 [**New UI components**](#new-ui-components) - Tooltip, Markdown, Progress Bar, Separator\
> 📥 [**Angular bulk file upload**](#angular-bulk-file-upload) - Multi-file upload component for the Angular SDK\
> 📦 [**UI Flow multi-file upload backend**](#ui-flow-multi-file-upload-backend) - Single bulk endpoint and one completion SSE event for batch uploads\
> 🪝 [**Webhook provider adapters**](#webhook-provider-adapters) - Slack inbound webhook support with HMAC signing\
> 🗄️ [**Richer SQL autocomplete**](#richer-sql-autocomplete) - Monaco editor enhancements for the Oracle data source SQL editor\
> 🧱 [**Data source UX redesign**](#data-source-ux-redesign) - Tile-based creation, type filters, unified settings, save with incomplete config\
> ➕ [**Context menu adds UI components in Processes**](#context-menu-adds-ui-components-in-processes) - Right-click Add UI component in Process User Tasks and Reusable UI Templates\
> 👆 [**Pointer cursor on actionable elements**](#pointer-cursor-on-actionable-elements) - Web renderers show pointer on action-bound components

> [tab] AI Platform
>
> 🛡️ [**PII Guard**](#pii-guard) - Personal information identification on AI inputs\
> 🤖 [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent now drafts Custom Component code\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - System metadata keys, Kafka indexer→embedder, Qdrant export/delete, error handling\
> 🌐 [**Web Crawler multi-URL filters**](#web-crawler-multi-url-filters) - Multiple URL filters per crawler config

### **Runtime authorization**

> [card] Runtime authorization overhaul
>
> > [tab] Overview
> >
> > **Before 5.8.0:** a role on a user matched every project that role appeared in. **Now:** roles live at the project version, sharing is explicit, and Designer users still bypass runtime so they can demo without standing up test accounts.
> >
> > Runtime access is reorganized around the project. Roles live at the **project version**, each org has a managed catalog of **end-user groups**, and access flows through a **Solutions → Share** modal. FlowX retains authentication and external-IDP federation in Keycloak; runtime roles, end-user groups, and project-scoped sharing live in FlowX itself, evaluated by a custom runtime authorization service tuned for the volume of runtime permission checks. SpiceDB remains the design-time permission engine for Designer access.
> >
> > > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> > >
> > > See Setup guides → Access management → Runtime authorization.
>
> > [tab] Key Features
> >
> > > [card] Project-scoped roles
> > >
> > > Each project version declares the runtime roles required to operate it. Roles are org-level entities, defined once and reusable across projects and libraries.
> >
> > > [card] Default `user` role on creation
> > >
> > > New projects spawn with a default `user` role so a fresh project is reachable on day one without extra wiring.
> >
> > > [card] Sharing from Solutions
> > >
> > > The Solutions page gains a **Share** modal. Pick a user or end-user group, assign a role, and the user can launch the solution at runtime.
> >
> > > [card] End-user groups in FlowX
> > >
> > > Groups previously managed in Keycloak now live in FlowX. Recommended pattern: an "All End Users" group per single-role solution; one group per role for multi-role solutions.
> >
> > > [card] Process swimlane roles
> > >
> > > BPMN swimlanes assign view, execute, and self-assign permissions per role.
> >
> > > [card] Designer-user bypass
> > >
> > > Designer users can run any project they have designer access to without holding a runtime role; they auto-receive view, execute, and self-assign on every swimlane.
> >
> > > [card] Active Policy gate
> > >
> > > The Share modal lists only roles defined in the build set as **Active Policy** for the project. Roles defined in a non-active build do not appear until promoted.
>
> > [tab] Architecture
> >
> > The 5.8.0 release introduces a clear split between authentication and runtime authorization:
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Authentication, sessions, MFA | Keycloak | Unchanged |
> > | External IDP federation | Keycloak | Configured per organization |
> > | User attributes (business filters) | Keycloak | Source of truth for token claims |
> > | Runtime roles | FlowX (custom CAS) | Defined per project version, evaluated at runtime |
> > | End-user groups | FlowX (custom CAS) | Replaces Keycloak group management |
> > | Project-scoped sharing | FlowX (custom CAS) | Solutions → Share modal |
> > | Design-time permissions | FlowX SpiceDB | Designer UI access; unchanged from prior releases |
> >
> > A `designer-user` Keycloak attribute is auto-managed on each user (`true` for designer users, `false` for end-users), with a mapper on the `flowx-platform-authenticate` client so the engine can check it cheaply on the access token.
>
> > [tab] Migration
> >
> > > [!WARNING]
> > >
> > > **Sharing settings do not export between environments or workspaces.** Configure sharing per environment as a deliberate step when promoting a project to a higher environment.
> >
> > Sharing data does not travel with the project export, so promoting a build from one environment to another (for example, dev to staging) requires a sharing pass in the target environment. Treat it as an explicit step in your deployment checklist.
> >
> > Existing FlowX organizations migrate as follows:
> >
> > * Roles previously assigned directly to users continue to work for backward compatibility while you rebuild assignments under the project-scoped model.
> > * End-user groups configured in Keycloak are migrated into FlowX and become the authoritative source going forward.
> > * Existing UI Flows receive the project-level **User** role automatically as their default allowed role on upgrade. See the [UI Flow permissions](#ui-flow-permissions) section for next steps.
>
> All Deployments

### **UI Flow permissions**

> [card] UI Flow permissions
>
> > [tab] Overview
> >
> > **Before 5.8.0:** every UI Flow was reachable by anyone with runtime access. **Now:** each UI Flow carries its own allow-list and components inside it can be hidden or disabled per role.
> >
> > Each UI Flow now carries a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API. Inside a UI Flow session, individual components can be hidden or disabled by permission-based rules evaluated at runtime against the user's permission set.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> > >
> > > See UI Flows → UI Flow permissions.
>
> > [tab] Key Features
> >
> > > [card] Permissions page
> > >
> > > A new **Settings → Permissions** page in the UI Flow editor lets you assign one or more runtime roles to each UI Flow.
> >
> > > [card] Default role on creation
> > >
> > > New UI Flows receive the project-level **User** role by default so they are reachable on day one; tighten the list before deploying.
> >
> > > [card] Per-component hide/disable
> > >
> > > Components can be hidden or made readonly based on the user's runtime permissions, using the same hide/disable rule machinery as JavaScript expressions.
> >
> > > [card] Permission toast
> > >
> > > Users without the required role see a permission toast in the Designer-hosted runtime preview; the deployed app returns 403 from the start endpoint.
> >
> > > [card] Input-parameter validation
> > >
> > > Input parameters are validated against the UI Flow's input schema before the session is created.
> >
> > > [card] Travels with import/export
> > >
> > > Allowed roles are saved on the UI Flow resource and travel with project export/import.
>
> > [tab] Migration
> >
> > UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.
>
> All Deployments

### **Custom Components in Processes**

> [card] Custom Components in Processes
>
> > [tab] Overview
> >
> > **Before 5.8.0:** Custom Components only ran in UI Flows. **Now:** drag one onto a Process User Task and the React SDK applies the input/output mappings at runtime.
> >
> > Bundled Custom Components, previously only usable in UI Flows, now render in **Process User Tasks**. Each Custom Component carries its own **data model** with explicit input and output slices, and you map process data into and out of the component at each use site. Renderer support ships in the React SDK.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components#using-custom-components-in-process-user-tasks)
> > >
> > > See Custom Components → Using Custom Components in Process User Tasks.
>
> > [tab] Key Features
> >
> > > [card] Process User Task host
> > >
> > > Drag a Custom Component onto a Process User Task layout the same way you do in UI Flows.
> >
> > > [card] Custom Component data model
> > >
> > > Each Custom Component declares its own data model. The Designer keeps input and output slices isolated so the component contract is clear at every use site.
> >
> > > [card] INPUT mappings
> > >
> > > Map process data attributes onto the Custom Component's input slice at runtime, so the component receives only the data it declared.
> >
> > > [card] OUTPUT mappings
> > >
> > > When the component triggers an action, the React SDK applies the configured OUTPUT mappings before piping `saveData` back to process variables.
> >
> > > [card] Test with sample inputs
> > >
> > > The Custom Component editor lets you fill input params with sample data for in-Designer preview, mirroring the UI Flow test flow.
> >
> > > [card] Import and export
> > >
> > > Custom Components export and import alongside the data model and mappings so a component travels intact between projects.
>
> > [tab] Limitations
> >
> > Phase 1 limitations from 5.7.0 still apply: React SDK only (no Angular renderer), pre-defined dependency set (React, Emotion, Lodash, Axios, date-fns), browser-side bundling, and client-side rendering only. See the [Custom Components limitations](/5.9/docs/building-blocks/reusable-resources/custom-components#limitations-phase-1) section.
>
> All Deployments

### **New UI components**

> [card] New UI components
>
> Four new theme components ship with renderer parity across React, Angular, and Android SDKs.
>
> > [card] [Tooltip](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Contextual hint anchored to any UI element. Configurable text (static, local variable, or computed expression), position handling, and an optional icon.
>
> > [card] [Markdown](/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown)
> >
> > Render Markdown content from a static string or computed expression, with localization formatting for numbers, dates, and currency. Six heading levels and link styling are theme-driven.
>
> > [card] [Progress Bar](/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar)
> >
> > Visual progress indicator. Set a value between `0` and `1` from a static value, local variable, or computed expression.
>
> > [card] [Separator](/5.9/docs/building-blocks/ui-designer/ui-component-types/separator)
> >
> > Visual divider with theme-driven color. Adjustable height for layout spacing.
>
> All four are exposed in the **Theme Admin** sidebar so theme overrides cascade through templates.
>
> All Deployments

### **Angular bulk file upload**

> [card] Angular bulk file upload
>
> > [tab] Overview
> >
> > The **Multiple File Upload** component (`BULK_FILE_UPLOAD`), previously available only in the React SDK, now ships in the Angular SDK with the same drag-and-drop area and theming. Existing UI Flows that use the component render across React and Angular containers without configuration changes.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> > >
> > > See the Multiple File Upload component reference.
>
> > [tab] Key Features
> >
> > > [card] Renderer parity
> > >
> > > Same component, same configuration, same theming across React and Angular containers.
> >
> > > [card] Drag-and-drop area
> > >
> > > Drop zone with click-to-browse fallback in both renderers.
> >
> > > [card] Theme-driven
> > >
> > > The component picks up theme overrides for typography, colors, and spacing the same way as built-in components.
> >
> > > [card] No flow changes needed
> > >
> > > UI Flows authored before 5.8.0 render in the Angular SDK without edits.
>
> All Deployments

### **UI Flow multi-file upload backend**

> [card] UI Flow multi-file upload backend
>
> > [tab] Overview
> >
> > Multi-file uploads from UI Flows now use a dedicated bulk endpoint and a single completion event in place of the per-file pattern. The upload action accepts a list of temp-file IDs in one request and the SDK receives a single SSE frame when the batch is persisted.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload#ui-flow-upload-flow)
> > >
> > > See Multiple file upload → UI Flow upload flow.
>
> > [tab] Key Features
> >
> > > [card] Single bulk endpoint
> > >
> > > `POST /ui-flow/{uiFlowSessionId}/upload-multiple` accepts a list of temp-file IDs and returns a server-generated `uploadBatchId`.
> >
> > > [card] Single completion event
> > >
> > > One SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) delivers per-file results once the batch is persisted.
> >
> > > [card] New Kafka topic
> > >
> > > `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` carries the bulk command from process-engine to document-plugin.
> >
> > > [card] Session variable mapping
> > >
> > > Per-file results are stored as a list under the upload action's `responseKey` in the UI Flow session.
>
> All Deployments

### **Webhook provider adapters**

> [card] Webhook provider adapters
>
> > [tab] Overview
> >
> > Inbound webhook registrations now select a **provider**: `GENERIC` or `SLACK`. The Slack adapter performs HMAC-SHA256 signature validation against the Slack signing secret on every request, including the `X-Slack-Request-Timestamp` skew check (5 minutes). Provider-segmented URLs (`/webhooks/incoming/slack/...`) keep generic and provider-specific registrations isolated. Future providers plug in behind the same `InboundProviderAdapter` interface without changing the URL contract.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#provider-adapters)
> > >
> > > See Incoming webhooks → Provider adapters.
>
> > [tab] Key Features
> >
> > > [card] Slack signature validation
> > >
> > > HMAC-SHA256 on `X-Slack-Signature`, with timestamp skew enforced
> >
> > > [card] Slack URL-verification handshake
> > >
> > > The gateway answers Slack's `url_verification` challenge automatically
> >
> > > [card] Provider-segmented URLs
> > >
> > > `/webhooks/incoming/{provider}/...` keeps providers isolated; mismatch returns 400
> >
> > > [card] Independent secret rotation
> > >
> > > Rotate the provider signing secret without touching the FlowX API key
> >
> > > [card] Settings tab
> > >
> > > Provider + signing secret moved to a dedicated Settings tab on the webhook system
> >
> > > [card] Pluggable
> > >
> > > New providers add an adapter and an enum value; no URL or registration schema changes
>
> All Deployments

### **Richer SQL autocomplete**

> [card] Richer SQL autocomplete
>
> > [tab] Overview
> >
> > The Monaco editor on the Oracle Database data source now ships with a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `:paramName` interpolations resolved from the parameters panel.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database#sql-editor)
> > >
> > > See the Oracle Database SQL editor documentation.
>
> > [tab] Key Features
> >
> > > [card] Keywords and operators
> > >
> > > Full SQL language definition powers keyword highlighting and completion.
> >
> > > [card] Schema-aware suggestions
> > >
> > > Tables and columns parsed from the saved schema context appear in completion lists.
> >
> > > [card] Parameter interpolation
> > >
> > > `:paramName` placeholders resolve against the parameters panel for inline preview.
> >
> > > [card] Editor consistency
> > >
> > > Matches the editor experience used by other code surfaces in the Designer.
>
> All Deployments

### **Data source UX redesign**

> [card] Data source UX redesign
>
> > [tab] Overview
> >
> > The Data Sources resource page is rebuilt around a tile-based creation flow and a unified details view. Each data source type has its own icon and a dedicated tile in the **New Data Source** modal, with a search box that filters tiles as you type. The list view shows the type next to each entry and adds a type filter so you can scope the list by connector. Settings panels for every data source type are normalized to the same card-based layout.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer reference for data source configuration.
>
> > [tab] Key Features
> >
> > > [card] Tile-based creation modal
> > >
> > > The **New Data Source** modal lists every connector type as a searchable tile, replacing the previous type dropdown.
> >
> > > [card] Type icons in the list
> > >
> > > Each entry in the data sources list shows the connector's icon and type, so a long list is easier to scan.
> >
> > > [card] Filter by type
> > >
> > > Filter the list to a specific connector type (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.) without scrolling.
> >
> > > [card] Unified settings layout
> > >
> > > Every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
> >
> > > [card] Save with incomplete config
> > >
> > > Create and save a data source even when some fields (credentials, endpoints) are not yet available. You can reference the data source in workflows and processes immediately and finish the configuration later — the data source will only operate at runtime once required fields are filled in.
>
> All Deployments

### **PII Guard**

> [card] Personal Information Guard
>
> > [tab] Overview
> >
> > **Before 5.8.0:** data-sensitive customers couldn't enable AI workflow nodes at all. **Now:** every AI node carries a per-node guardrail with sensitivity presets, scan directions, and a fail-closed contract.
> >
> > AI workflow nodes gain a per-node guardrail that detects and replaces personal information before it reaches the LLM and, optionally, scans LLM output before it flows downstream. The guard runs against the new **Data Privacy** service, configured per node with sensitivity presets, scan directions, and an entity catalog organized into Universal, Regional EN, and Regional RO scopes. Iteration 1 covers Custom Agent, Intent Classification, Extract Data from File, and all AI Text, Document, Image, and Data Operations, including Document Generation.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See Personal Information Guard.
>
> > [tab] Key Features
> >
> > > [card] Per-node toggle
> > >
> > > Enable on any AI node. Choose a sensitivity preset (Strict / Balanced / Relaxed) or set a custom threshold.
> >
> > > [card] Input and output scans
> > >
> > > Redacts inputs and `systemPrompt` before the LLM call; optionally scans LLM output before it leaves the node.
> >
> > > [card] File redaction
> > >
> > > Document and image nodes get a redacted source artifact uploaded back to the same storage; the file binding is swapped automatically.
> >
> > > [card] Entity catalog
> > >
> > > 24 entity types (email, phone, IBAN, etc.) grouped under Universal, Regional EN, and Regional RO. Modal supports search and section-level Select All.
> >
> > > [card] System-prompt appender
> > >
> > > Custom Agent nodes get a non-editable system-prompt segment teaching the LLM how to handle `<PII type=.../>` placeholders.
> >
> > > [card] Fail-closed
> > >
> > > Any error from the Data Privacy service stops node execution and surfaces on the run log; no partially-redacted prompts reach the LLM.
> >
> > > [card] Run-log visibility
> > >
> > > Each scan reports status, per-entity detection counts, and (for file scans) original and redacted storage paths.
> >
> > > [card] New Data Privacy service
> > >
> > > Backed by Presidio. Configured via `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` on integration-designer.
>
> All Deployments

### **Knowledge Base enhancements**

> [card] Knowledge Base
>
> > [tab] Overview
> >
> > Knowledge Bases gain richer metadata and a more resilient indexing path. Stores and chunks expose system metadata fields you can filter on in the Test KB modal and the Custom Agent node, the indexer and embedder communicate over Kafka instead of synchronous calls, and the Update Knowledge Base node can ingest files by path from inside a workflow.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See Knowledge Base → Overview.
>
> > [tab] Key Features
> >
> > > [card] System metadata on stores
> > >
> > > Filter entries by `Source` (Manual or Workflow), `Uploaded`, `Doc name`, `Doc type`, `Doc pages`, and `Store origin`
> >
> > > [card] System metadata on chunks
> > >
> > > Filter chunks by `Chunk counter`, `Chunk type`, `Chunk section`, `Chunk page start`, and `Chunk entry`
> >
> > > [card] Kafka between indexer and embedder
> > >
> > > Replaces the previous synchronous gRPC path; per-chunk embedding requests flow through `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1`
> >
> > > [card] Delete chunks from Qdrant
> > >
> > > Indexer forwards a delete job to the embedder, which removes matching points from Qdrant when an entry is deleted
> >
> > > [card] File path mode in Update KB node
> > >
> > > The Update Knowledge Base node accepts `contentType: FILE_PATH` so workflows can ingest content uploaded earlier in the run
> >
> > > [card] Doc pages in agent stream
> > >
> > > Custom Agent streaming responses include `doc_pages` and chunk metadata (counter, type, section, page start) for richer trace and debug
>
> All Deployments

### **Web Crawler multi-URL filters**

> [card] Web Crawler multi-URL filters
>
> > [tab] Overview
> >
> > The Web Crawler node now accepts up to 20 URL filter patterns per crawler configuration. Open the **URL Filters** modal on the Web Crawler node, add one row per pattern, and the crawler restricts its breadth-first traversal to URLs that match any of the configured filters.
> >
> > > [card] [Documentation](/5.9/setup-guides/web-crawler-setup)
> > >
> > > See the Web Crawler setup guide.
>
> > [tab] Key Features
> >
> > > [card] Up to 20 patterns per crawler
> > >
> > > Add one row per pattern in the URL Filters modal; deep crawls match any pattern.
> >
> > > [card] Replaces single-string filter
> > >
> > > The previous single-string filter is superseded by the new multi-pattern array. Existing crawlers are migrated automatically.
> >
> > > [card] Breadth-first scoping
> > >
> > > Filters apply to the crawler's breadth-first traversal so deep crawls stay within the intended scope.
> >
> > > [card] Per-pattern tuning
> > >
> > > Combine narrow and broad patterns in one configuration to handle multi-section sites without spawning multiple crawlers.
>
> All Deployments

### **AI Developer generates Custom Components**

> [card] AI Developer generates Custom Components
>
> > [tab] Overview
> >
> > **Before 5.8.0:** the AI Developer wrote business rules and JS expressions. **Now:** it ships entire React Custom Components — JSX, CSS, `package.json`, and sample input data — in one prompt.
> >
> > The AI Developer pre-built agent gains a **Generate Custom Component** action and an **Edit Custom Component** action. From the Designer's AI command center, describe the component you want, and the agent returns a complete React bundle (JSX, CSS, `package.json`, and sample input data) that you can preview, accept, or iterate on. The same conversation can edit existing components.
> >
> > > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> > >
> > > See AI Developer → Pre-built agents.
>
> > [tab] Key Features
> >
> > > [card] Generate from natural language
> > >
> > > Describe a component in plain language; receive JSX, CSS, `package.json`, and sample input data in one response.
> >
> > > [card] Sample input field
> > >
> > > A dedicated input field lets you provide preview data so the generated component renders meaningfully on first run.
> >
> > > [card] Edit existing components
> > >
> > > Iterate on a generated or hand-authored component through the same conversation. The agent keeps the component context.
> >
> > > [card] Inline preview
> > >
> > > The Designer's Preview area renders the generated bundle next to the conversation so you can validate before saving.
> >
> > > [card] Dependency summary
> > >
> > > A new dependency summary panel surfaces the npm packages the agent included in `package.json`.
> >
> > > [card] Keep / Discard
> > >
> > > Accept the generated bundle into the workspace or discard it without leaving the conversation.
>
> > [tab] Limitations
> >
> > The first iteration generates the component code, styles, and input parameters. Wiring component actions to host-side handlers (Process or UI Flow actions) is not yet inferred — connect actions manually after accepting the generated bundle.
>
> All Deployments

### **iframe logout postMessage contract**

> [card] iframe logout postMessage
>
> The runtime SaaS app now notifies an iframe parent when a user logs out. When the parent passes a `parentOrigin` query parameter on the `/{orgCode}/logout` URL, the runtime posts `{ type: 'logout-success' }` to `window.parent` immediately before the sign-out redirect. Host applications that embed the FlowX runtime in an iframe can listen for this message and react (clear local state, navigate, surface a UI cue) without polling the iframe URL.
>
> All Deployments

### **Context menu adds UI components in Processes**

> [card] Right-click Add UI component in Processes and Reusable UI Templates
>
> The right-click contextual menu for adding a UI component, previously available only in UI Flows, now works in **Process User Tasks** and **Reusable UI Templates** as well. Right-click a node in the components hierarchy panel to insert any allowed child component without dragging from the palette. Copy and paste styles are also exposed from the same menu.
>
> All Deployments

### **Pointer cursor on actionable elements**

> [card] Pointer cursor on actionable elements
>
> Web renderers now switch the cursor to a pointer when hovering over any UI component bound to an action, matching standard web affordances. No configuration change is required — the new behavior applies automatically to elements that already declare an action role.
>
> All Deployments

### **"Process Data" → "Local Variables" rename**

> [card] Process Data renamed to Local Variables
>
> In the UI Designer, the **Process Data** label is now displayed as **Local Variables** when you are editing a UI Flow or a Reusable UI Template. Process editing is unchanged and continues to use **Process Data**. The data source key and binding behavior are identical; only the user-visible label changed, so existing flows continue to work without any update.
>
> All Deployments

### **License billing guards**

> [card] License billing guards
>
> The license service no longer creates billing plans for periods past an organization's subscription end date. This prevents stale plan rows from accumulating after a subscription expires and aligns the on-prem billing trail with the SaaS-side license lifecycle.
>
> Self-Hosted

### **Speech-to-text and Web Crawler in AI consumption**

> [card] Speech-to-text and Web Crawler in AI consumption
>
> AI consumption tracking now includes Speech-to-text and Web Crawler workflow nodes alongside the existing AI Text, Document, Image, and Data Operations. Organizations on AI consumption-based plans see usage and billing reflected for these nodes from 5.8.0 onward.
>
> All Deployments

***

## Shipped by

This release is the work of the FlowX engineering team — backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.8.0](./deployment-guidelines-v5.8).


# Deployment guidelines v5.9.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9

Component versions, environment variables, and configuration changes for FlowX.AI 5.9.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

> [!NOTE]
>
> **Upgrading from 5.1.x LTS?** This page describes the steady-state 5.9.0 deployment. For the architecture delta, deprecation list, and upgrade steps, see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Deployment packaging.** 5.9.x is the last LTS release distributed as a multi-chart deployment, where each FlowX service is installed from its own Helm chart.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

The following tables list component versions per FlowX.AI release. Verify your installed versions against the 5.9.0 column in **FlowX.AI Designer → Platform Status**.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **process-engine** | 10.135.0 | 10.106.0 | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 |
| **admin** | 10.116.0 | 10.93.0 | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 |
| **designer** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 |
| **cms-core** | 10.86.0 | 10.67.0 | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 |
| **scheduler-core** | 10.70.0 | 10.53.0 | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 |
| **events-gateway** | 10.72.0 | 10.55.0 | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 |
| **notification-plugin** | 10.83.0 | 10.64.0 | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 |
| **document-plugin** | 10.94.0 | 10.75.0 | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 |
| **task-management-plugin** | 10.84.0 | 10.66.0 | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |
| **data-search** | 10.69.0 | 10.52.0 | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 |
| **audit-core** | 10.79.0 | 10.63.0 | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 |
| **advancing-controller** | 10.73.0 | 10.55.0 | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 |
| **integration-designer** | 10.162.0 | 10.128.0 | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 |
| **application-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **runtime-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **data-sync** | 10.81.0 | 10.58.0 | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 |
| **authorization-system** | 10.96.1 | 10.77.0 | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 |
| **nosql-db-runner** | 10.75.0 | 10.56.0 | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 |
| **email-gateway** | 10.74.0 | 10.56.0 | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 |
| **organization-manager** | 10.71.0 | 10.53.0 | 10.44.0 | 10.26.1 | 10.19.2 | - |
| **webhook-gateway** | 10.44.0 | 10.25.0 | 10.15.0 | 10.1.1 | - | - |
| **file-gateway** | 10.8.0 | - | - | - | - | - |
| **license** | 10.63.0 | 10.46.0 | 10.36.0 | - | - | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB**
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-native-sdk** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-theme** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-ui-toolkit** | 10.230.2 | - | - | - | - | - |
| **@flowx/core-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/core-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **react-saas** | 10.230.2 | - | - | - | - | - |
| **iOS renderer** | 10.4.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |
| **Android renderer** | 10.5.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |

The **react-saas** container app tracks the designer version.

### Plugins

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-knowledgebase-rag** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-embedder** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **doc-parser** | 10.9.0 | 10.7.0 | 10.6.2 | 10.5.1 | - | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-agent-builder** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **data-privacy** | 10.1.0 | 10.1.0 | 10.0.8 | - | - | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **evals-judge** | 10.1.1 | - | - | - | - | - |
| **speech-to-text** | 10.3.4 | 10.3.3 | 10.3.3 | - | - | - |
| **web-crawler** | 10.3.5 | 10.3.5 | 10.3.2 | - | - | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-gateway** | 10.7.0 | - | - | - | - | - |
| **ai-platform-ai-analyst** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-assistant** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **ai-platform-ai-designer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-developer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **di-platform** | 10.3.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **flowx-docs** | 5.9.0 | - | - | - | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - | - | - |
| **ai-observatory** | 10.3.2 | - | - | - | - | - |

***

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

***

## Kafka topics

### Document-plugin archive and extract listeners

5.9.0 exposes four Kafka topics for the document-plugin **archive** and **extract** operations. Both follow the encrypt/decrypt trigger and reply pattern: document-plugin consumes the `trigger.*.file` topic and process-engine consumes the matching `engine.receive.*.file.results` reply.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.archive.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.extract.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` | document-plugin | process-engine |

The four topic names are exposed as env vars on the document-plugin side (`KAFKA_TOPIC_FILE_ARCHIVE_IN`, `KAFKA_TOPIC_FILE_ARCHIVE_OUT`, `KAFKA_TOPIC_FILE_EXTRACT_IN`, `KAFKA_TOPIC_FILE_EXTRACT_OUT`). See [Documents plugin setup → File archive / File extract](/5.9/setup-guides/documents-plugin-setup#file-archive). Two new thread-pool entries are added: `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN` and `..._FILEEXTRACTIN`, both defaulting to `5`.

### Document-plugin encrypt and decrypt listeners

The **encrypt** and **decrypt** operations follow the same trigger-and-reply pattern: process-engine produces the `trigger.*.file` topic and document-plugin replies on the matching `engine.receive.*.file.results` topic.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | document-plugin | process-engine |

The topic names are exposed as env vars on the document-plugin side: `KAFKA_TOPIC_FILE_ENCRYPT_IN`, `KAFKA_TOPIC_FILE_ENCRYPT_OUT`, `KAFKA_TOPIC_FILE_DECRYPT_IN`, `KAFKA_TOPIC_FILE_DECRYPT_OUT`.

### Document-plugin session-upload listeners

Multi-file upload for UI flows routes uploaded files to the document-plugin for persistence. process-engine produces the trigger topic and document-plugin consumes it — `session` for a single upload session and `session.bulk` for batched multi-file uploads.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | process-engine | document-plugin |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | document-plugin |

The topic names are exposed on process-engine as `KAFKA_TOPIC_SESSION_UPLOAD_OUT` and `KAFKA_TOPIC_SESSION_UPLOAD_BULK_OUT`, and on document-plugin as `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN` and `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN`.

### AI Platform job topics

`integration-designer` dispatches asynchronous jobs to the standalone AI services over Kafka, using a request/response pair per service. Provision these topics when you deploy the corresponding AI service (see [AI components](#ai-components) above).

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.ai-platform.doc-parser.job.request.v1` | integration-designer | doc-parser |
| `ai.flowx.ai-platform.doc-parser.job.response.v1` | doc-parser | integration-designer |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | integration-designer | evals-judge |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | evals-judge | integration-designer |
| `ai.flowx.ai-platform.speech-to-text.job.request.v1` | integration-designer | speech-to-text |
| `ai.flowx.ai-platform.speech-to-text.job.response.v1` | speech-to-text | integration-designer |

On `integration-designer` the topic names are set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_REQUEST_OUT` and `..._RESPONSE_IN` (for example `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`). Each service also has a dead-letter topic — `ai.flowx.ai-platform.<service>.job.dlq.v1`, set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_DLQ_IN` — that integration-designer consumes for failed jobs.

### UI Flow runtime triggers

process-engine consumes two trigger topics that back the UI Flow runtime cache and expiration features. `update` invalidates a cached UI Flow when its definition changes; `expire` removes expired UI Flow runtime data.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer | process-engine |
| `ai.flowx.core.trigger.expire.ui-flow.v1` | scheduler-core | process-engine |

On process-engine these are set via `KAFKA_TOPIC_UIFLOW_UPDATE_IN` and `KAFKA_TOPIC_UIFLOW_EXPIRE_IN`; the producers expose `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`. The expire trigger uses the platform scheduler: when a UI Flow session is created, process-engine registers a delayed message with scheduler-core, which publishes it back to this topic at the expiry time. It is consumed by a dedicated consumer group (`KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE`, default `ui-flow-expire`).

### File and webhook process triggers

Two trigger topics let the file-gateway and webhook-gateway start or resume processes in process-engine. The **start-for-event** topic starts a process when a watched file arrives (file-gateway) or an incoming webhook fires (webhook-gateway); the **message event** topic resumes a running process that is waiting on an intermediate message catch event.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | file-gateway, webhook-gateway | process-engine |
| `ai.flowx.core.message.event.process.v1` | webhook-gateway | process-engine |

On the producers, the start-for-event topic is set via `KAFKA_TOPIC_TRIGGER_STARTFOREVENT_PROCESS_OUT` (file-gateway) and `KAFKA_TOPIC_PROCESS_START_OUT` (webhook-gateway); process-engine consumes it via `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`. The message event topic uses `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` on both webhook-gateway and process-engine. Like every service, file-gateway and webhook-gateway also publish to the shared audit topic `ai.flowx.core.trigger.save.audit.v1` via `KAFKA_TOPIC_AUDIT_OUT` (consumed by audit-core).

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Data-sync: Keycloak admin credentials

The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak on first run, using the Keycloak admin API. Configure the following on the data-sync job:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak` (the only supported provider). | `keycloak` | data-sync |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` | data-sync |
| `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` | data-sync |
| `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` | data-sync |
| `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Typically `admin-cli` for standard Keycloak deployments. Must be set explicitly. There is no default. | `-` | data-sync |

For full data-sync configuration, see [Data-sync job setup](/5.9/setup-guides/data-sync#openid-provider-configuration).

### Anonymous service account: shared client secret

5.9.x introduces a single shared service-account client, `flowx-anonymous-sa`, used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows. One client secret is reused across all consumers — it must be provided in two places.

**On `authorization-system`** — passed to Liquibase so the client is provisioned with the correct secret when FlowX manages Keycloak:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXANONYMOUSSA` | Client secret used by Liquibase to create the `flowx-anonymous-sa` client in the service-accounts realm at first boot. Required when `SECURITY_KEYCLOAKADMINENABLED=true`. | `-` | `authorization-system` |

**On every consuming service** — the Spring Security OAuth2 client registration for the `anonymousidentity` alias resolves the same secret at runtime:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Client secret for the `anonymousidentity` registration. **Must be the same value across every service** — it is a single shared service account. | `-` | `admin`, `application-manager`, `authorization-system`, `document-plugin`, `email-gateway`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `mock-server`, `nosql-db-runner`, `organization-manager`, `process-engine`, `scheduler-core`, `task-management-plugin`, `webhook-gateway` |

> [!WARNING]
>
> This is a secret. Store it in your secrets management solution (e.g., Kubernetes Secret, Vault) and reference it from there. Never commit it to version control.

For the Keycloak-side context (`flowx-anonymous-sa` client, `SA_FLOWX_ANONYMOUS` realm role, manual-configuration recipe for deployments without Keycloak admin access), see [Manual Keycloak configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).

### Knowledgebase-rag: Qdrant search tuning

Two env vars control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Defaults are tunable per environment.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. | `100` | knowledgebase-rag |
| `QDRANT_FUSION_LIMIT` | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker input. | `80` | knowledgebase-rag |

Raise both when recall is insufficient on very large or long-tailed Knowledge Bases. Lower them when Qdrant pods report memory pressure or filter-heavy queries time out.

### CORS handling: `APPLICATION_CORS_ALLOWORIGIN`

CORS is enforced at the application layer. Each backend service exposed via admin or public URLs reads its allowed-origin list from a single environment variable. Allowed methods, allowed headers, exposed headers, and credential handling are baked into each service's `application.yaml` with safe defaults. The 5.9.x default allow-headers set is `Accept, Content-Type, Authorization, Fx-Workspace-Id, Fx-Client-Host, Referer, User-Agent, Flowx-Platform, X-Fx-Anonymous-Session-Id, Fx-BuildId, Fx-AppId`, and `X-Fx-Anonymous-Session-Id` is exposed to the browser for anonymous runtime sessions. Only `APPLICATION_CORS_ALLOWORIGIN` is deployment-specific.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains (`https://*.yourcompany.com`). Must include every Designer, runtime renderer, and integration domain that calls FlowX APIs. | `-` | `admin`, `ai-gateway`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway` |
| `APPLICATION_CORS_EXPOSEDHEADERS` | Response headers exposed to browser JavaScript. The default carries the anonymous-session header; override only if you need to expose additional custom headers. | `X-Fx-Anonymous-Session-Id` | all services (shared security library) |

For migration guidance and the full list of removed NGINX CORS annotations, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

### Process-engine and integration-designer: native script engine

The default script engine for JavaScript and Python execution is a **native subprocess pool**. Scripts run in isolated Node.js and Python worker processes.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider | `native` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size | `16` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary | `/usr/bin/node` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS script execution timeout (ms) | `5000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a JS worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max JS input payload size (bytes) | `1048576` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size | `8` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary | `/usr/bin/python3` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python script execution timeout (ms) | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a Python worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max Python input payload size (bytes) | `1048576` | process-engine, integration-designer |

To use GraalVM instead of the native engine, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services.


# FlowX.AI 5.9.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026

First LTS in the 5.9.x family. Brings conversational AI, UI Flows and Custom Components, AI Platform, runtime authorization, new React Native and iOS UI Flow SDKs, and a wide set of integration and process-ops improvements.

[FlowX.AI 5.9.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-5.9.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted deployments
> * All Deployments Features available in both self-hosted and SaaS

### What 5.9.0 includes

* **Closes the runtime authorization rewrite**. Per-environment sharing, project-version-scoped roles, data-sync Keycloak provisioning.
* **Brings the full set of changes accumulated since the 5.1.x LTS line**. Conversational AI, UI Flows, Custom Components, AI Platform, runtime authorization.
* **Ships a new React Native SDK** and rounds out iOS UI Flow support.

> [!NOTE]
>
> **5.9.0 is the first LTS in the 5.9.x family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Self-hosted customers upgrading from 5.1.x LTS go directly to 5.9.0. See the [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview) guide for the consolidated upgrade path.

***

**What's in this LTS release?**

> [tab] Runtime authorization and sharing
>
> 🔐 [**Runtime authorization completion**](#runtime-authorization-completion) - Per-environment sharing checklist, project-level end-user roles, data-sync provisioning of Keycloak groups and roles.\
> 🌐 [**Anonymous runtime access**](#anonymous-runtime-access) - Built-in Anonymous role + Share modal "Everyone with the link" for unauthenticated end users; session-bound, SDK auth-skip mode.\
> 🛡️ [**Runtime authorization overhaul**](#runtime-authorization-overhaul) - Project-version-scoped roles, end-user groups moved from Keycloak into FlowX, Solutions → Share modal flow, Active Policy gate, designer-user bypass.\
> 🔒 [**UI Flow permissions**](#ui-flow-permissions) - Per-UI-Flow role allow-list with runtime 403 enforcement; assignments travel with import/export.\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.\
> 🎯 [**Active policy: group overrides**](#active-policy-group-overrides) - Override a project's active build per runtime group; legacy role overrides are excluded from runtime resolution and only kept for deletion.\
> 🧩 [**Roles carried across project-version merges**](#roles-carried-across-project-version-merges) - Application-version roles cloned onto the merged version automatically, no manual re-binding after merge.\
> 🏷️ [**Operations-editor role**](#operations-editor-role) - **Workspace operations editor** role and `wks_process_instance_variables_edit` permission for ops teams.\
> 🗂️ [**Cross-workspace projects**](#cross-workspace-projects) - Import the same project into multiple workspaces in the same environment.\
> 🔁 [**Cross-LTS import/export**](#cross-lts-import/export) - Move project versions and builds between the 5.1.x and 5.9.x LTS lines, in both directions.\
> 🚪 [**Log-in page redesign**](#log-in-page-redesign) - IdP provider button replaces the fallback link; refreshed labels across the log-in flow.

> [tab] Conversational AI
>
> 💬 [**Chat component**](#chat-component) - Standalone chat tab; Inline / Floating / FullScreen modes; iOS and Android support; Chat History; Suggested Prompts; Markdown.\
> 🌀 [**Conversational Workflows**](#conversational-workflows) - Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node.\
> 🎙️ [**Voice input + Speech-to-Text**](#voice-input-+-speech-to-text) - Audio recording in chat; Speech-to-Text node for transcription.\
> 🧠 [**Memory capabilities**](#memory-capabilities) - Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full; Use conversation memory toggle on the AI / Custom Agent node.\
> 🧭 [**Intent Classification node**](#intent-classification-node) - LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.\
> 💭 [**Chat-based UI Flows**](#chat-based-ui-flows) - Flow-Based vs Chat-Based experience type set at the UI Flow level.\
> ⚡ [**AI Triggers**](#ai-triggers) - Named parameterized message templates to launch conversational workflows with context.\
> 🏷️ [**Chat title generation and conversation search**](#chat-title-generation-and-conversation-search) - Auto-generated session titles + cross-conversation search on the chat history.\
> 🛑 [**Stop agent response**](#stop-agent-response) - Stop button while streaming; cancels the underlying workflow.

> [tab] AI Agents and Knowledge
>
> 📊 [**Evaluations (Evals)**](#evaluations) - LLM-as-judge, RAG-quality, and code evaluators score AI node outputs; datasets, experiments, per-org judge model via new `EVAL` capability.\
> 🤖 [**Custom Agent nodes**](#custom-agent-nodes) - AI agents that use MCP tools to act autonomously in workflows.\
> 🔎 [**Web Search tool for Custom Agents**](#web-search-tool-for-custom-agents) - Built-in web search so Custom Agents can look up up-to-date public-web information during a run.\
> 🔌 [**MCP integration**](#mcp-integration) - MCP servers as data sources; tools in Custom Agent nodes; OAuth 2.0, BEARER, BASIC auth.\
> 📖 [**Knowledge Bases**](#knowledge-bases) - PDF upload, workflow ingestion, semantic search, Custom Agent integration; Stores rename + typed filter builder; system metadata; Kafka indexer/embedder.\
> 🧰 [**AI Providers self-service**](#ai-providers-self-service) - Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability.\
> 🛡️ [**PII Guard: per-entity detections on documents and images**](#pii-guard-per-entity-detections-on-documents-and-images) - Document and image scans return the same per-entity detection list as text scans, with bounding regions.\
> 📝 [**Operational prompt split**](#operational-prompt-split) - System prompt split into operational guardrails and user-instruction layers, versioned independently.\
> 📄 [**Extract Data from File**](#extract-data-from-file) - LLM / OCR / Text Parsing strategies; image input; signature detection.\
> 🌐 [**Web Page Extractor / Web Crawler**](#web-page-extractor-/-web-crawler) - Static or dynamic URLs, link-following depth, PDF extraction, URL filtering, file downloads, multi-URL filters.\
> 📚 [**Manage Knowledge Base content from Runtime**](#manage-knowledge-base-content-from-runtime) - End users can add and update KB content at runtime without going back to the Designer.\
> ✨ [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent drafts React Custom Components from a brief.

> [tab] UI Flows and Custom Components
>
> 🪟 [**UI Flows**](#ui-flows) - Reusable multi-platform UI as project resources; Sessions monitoring; Process Renderer; Route Management; Start Parameters; Session Variables; onClick / On Display / On Load events.\
> ⏳ [**UI Flow session expiry**](#ui-flow-session-expiry) - Expire a UI Flow after a duration or on a schedule; expired sessions become read-only.\
> 🖼️ [**Configurable modal component**](#configurable-modal-component) - Title, subtitle, dismiss behavior, alignment and sizing on modals; theme-level shadow and dismiss icon.\
> 💻 [**Custom Components**](#custom-components) - React JSX / CSS in the Designer; Custom Components in Processes with INPUT/OUTPUT mappings.\
> 🎬 [**Event Handlers**](#event-handlers) - Typed Event Handlers section in the UI component config panel; UI events and AI triggers unified under one model.\
> ♿ [**Accessibility (WCAG 2.1 AA)**](#accessibility-wcag-2-1-aa) - Cross-platform accessibility model surfaced in the UI Designer.\
> 🧱 [**New theme components**](#new-theme-components) - Tooltip, Markdown, Progress Bar, Separator across React / Angular / Android.\
> 📤 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Multiple File Upload on process screens and UI Flows; Angular and React SDK support.\
> 🎨 [**Theming and Designer polish**](#theming-and-designer-polish) - Scoped variants and padding for form labels/errors/helpers, mandatory-label style.

> [tab] Integration and Data Platform
>
> 📨 [**Email Trigger**](#email-trigger) - IMAP-triggered processes; attachments to the `document-plugin`; validation rules.\
> 📧 [**Microsoft Outlook data source**](#microsoft-outlook-data-source) - Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes.\
> 🪝 [**Incoming Webhooks**](#incoming-webhooks) - New `webhook-gateway` microservice; trigger processes via HTTP POST; Slack provider adapter.\
> 🗄️ [**Oracle Database integration**](#oracle-database-integration) - Oracle 21c / 23ai data source; schema-aware Monaco editor.\
> 🍃 [**Unmanaged MongoDB data source**](#unmanaged-mongodb-data-source) - Connect to externally managed MongoDB 6.0+ instances.\
> 📁 [**File Storage data source**](#file-storage-data-source) - Move files in and out of external FTP / SFTP / S3 / Azure Blob storage from workflows.\
> 📨 [**Meta webhook provider**](#meta-webhook-provider) - WhatsApp / Messenger / Instagram / Threads webhook support with verify-token handshake and X-Hub-Signature-256 verification.\
> 📂 [**Documents in process instances**](#documents-in-process-instances) - Dedicated Documents section on each process instance.\
> 📤 [**Send Notification action + Email Sender**](#send-notification-action-+-email-sender) - SMTP data source; new action sends or replies email directly without Kafka.\
> 🎛️ [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder replacing manual JSON, with new operators.\
> 🧬 [**Parallel branches in workflows**](#parallel-branches-in-workflows) - Start / End Parallel nodes for concurrent execution.\
> ⚡ [**REST endpoint caching + workflow partitioning**](#rest-endpoint-caching-+-workflow-partitioning) - TTL-based REST GET caching; time-based workflow partitions with retention.\
> 🔗 [**Data mappers + workflow data models**](#data-mappers-+-workflow-data-models) - Workflow data models with input/output; process ↔ workflow mapping; CRUD endpoints.\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Reusable HTTP/HTTPS proxies attached to REST data sources.\
> ✉️ [**Two-stage attachment filtering for Email triggers**](#two-stage-attachment-filtering-for-email-triggers) - Choose which emails trigger the process and which attachments are forwarded into it.\
> ⏸️ [**Resume a process from an incoming webhook**](#resume-a-process-from-an-incoming-webhook) - Webhooks now drive Message Catch Intermediate Events with a Process Correlation Key.\
> 🌐 [**REST endpoints: content-type-aware responses**](#rest-endpoints-content-type-aware-responses) - Accept-driven JSON / text / XML parsing with XXE-safe XML; responses over 5 MiB are returned raw.\
> 📝 [**Raw endpoint payload type**](#raw-endpoint-payload-type) - Send request body as-is with the user's Content-Type preserved; XML / SOAP / form-urlencoded / plain text without MULTIPART wrapping.

> [tab] Process operations
>
> ✏️ [**Update Process Variables**](#update-process-variables) - JSON editor for variables on active instances; snapshot history; Compare diff.\
> 🛑 [**Stop workflow instances in runtime**](#stop-workflow-instances-in-runtime) - Authorized end users can stop running workflow instances from runtime.\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor.\
> 🔔 [**Notification history + template usages**](#notification-history-+-template-usages) - `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all references.\
> 📋 [**Token view improvements**](#token-view-improvements) - Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, color-coded status.\
> 🔧 **Fixed: names with square brackets** - Processes and UI flows whose names contain square brackets now start correctly again.

> [tab] Platform, deployment and infrastructure
>
> 🏢 [**Single-org self-hosted deployment**](#single-org-self-hosted-deployment) - Self-hosted default mode; guided setup wizard.\
> 🔑 [**License service**](#license-service) - Centralized license validation and usage reporting for self-hosted deployments.\
> 🔐 [**Authentication: opaque-token → JWT**](#authentication-opaque-token-→-jwt) - Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key`; dedicated service-accounts realm.\
> 🆕 [**New services to deploy**](#new-services-to-deploy) - `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. None existed in a 5.1.x deployment.\
> 🐍 [**Native script engine for JavaScript and Python**](#native-script-engine-for-javascript-and-python) - Default JS/Python execution moves from GraalVM to a Node.js + CPython subprocess pool; GraalVM available as opt-in.\
> 🌐 [**Ingress routing and CORS handling**](#ingress-routing-and-cors-handling) - NGINX ingress controller deprecated as the FlowX-shipped default; CORS moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on every backend service.\
> 📡 [**Kafka configuration alignment**](#kafka-configuration-alignment) - Standardized `KAFKA_*` env vars; mandatory `Fx-Organization-Id` header.\
> 📊 [**OpenTelemetry + SpiceDB DR**](#opentelemetry-+-spicedb-dr) - OpenTelemetry / Prometheus Helm charts published; SpiceDB backup and disaster-recovery procedures.\
> 🛡️ [**Durable message-processing**](#durable-message-processing) - Parked integration responses are persisted durably so in-flight responses survive runtime restarts, reducing stuck process tokens.\
> 🌍 [**Task management localization**](#task-management-localization) - 51 substitution tags + automatic table grid localization across 30 languages.

> [tab] Mobile & Renderers
>
> 📱 [**React Native SDK**](#react-native-sdk) - New SDK for React Native apps with process renderer, forms, navigation, and CMS integration. Demo app included.\
> 🍎 [**iOS UI Flows support**](#ios-ui-flows-support) - Full UI Flows renderer on iOS; sessions, document plugin subtypes, dismiss action, start parameters, new native components.\
> 📲 [**Mobile chat support**](#conversational-ai) - Chat component available on iOS and Android.\
> ⚛️ [**React 19 upgrade**](#react-19-upgrade) - React SDK upgraded to React 19; host apps must upgrade in lockstep.

> [tab] Info
>
> ℹ️ [**Deployment guidelines**](./deployment-guidelines-v5.9) - Component versions, environment variables, Kafka topics\
> 🗺️ [**Migrating from 5.1 LTS**](/5.9/migrating-from-5.1-lts/overview) - Consolidated upgrade path from 5.1.x LTS to 5.9.x LTS

> [card]
>
> ### **Runtime authorization completion**
>
> 5.9.0 completes the project-version-scoped runtime authorization model:
>
> * **Sharing checklist for environment promotion.** Sharing assignments do not export with builds. Each environment must be reconfigured when a project is promoted. The deployment checklist for this is now part of the setup guide.
> * **Project-level end-user roles.** Roles can be assigned at the project level from creation, so a fresh project is reachable without a separate share pass.
> * **Data-sync provisioning.** The data-sync job calls the Keycloak admin API on first run to provision FlowX-managed end-user groups and runtime roles. Five new `FLOWX_OPENID_*` env vars expose the admin credentials.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > See Setup guides → Access management → Runtime authorization for the day-to-day model.
>
> > [accordion] Key Features
> >
> > * **Per-environment sharing checklist.** When you promote a project from dev to uat to prod, the Share modal assignments do not travel with the build. The setup guide now documents the explicit per-environment reconfiguration step.
> > * **Project-level end-user roles.** Assign end-user roles at the project level so a freshly created project is reachable on day one. No separate Share-modal pass required for the default access pattern.
> > * **Data-sync Keycloak provisioning.** The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak the first time it runs against a 5.9.0 environment. Configure admin credentials with the new `FLOWX_OPENID_*` env vars on the data-sync job.
> > * **Deployment checklist included.** The runtime authorization setup guide now ships a deployment prerequisites section so the data-sync OpenID config and per-environment sharing reset are part of the standard promotion runbook.
>
> > [accordion] Configuration
> >
> > Required on the data-sync job from 5.9.0 onward:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak`. | `keycloak` |
> > | `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` |
> > | `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` |
> > | `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` |
> > | `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Set to `admin-cli` for standard Keycloak deployments. | `-` |
> >
> > See [Data-sync job setup → OpenID provider configuration](/5.9/setup-guides/data-sync#openid-provider-configuration) for the full setup.

> [card]
>
> ### **Anonymous runtime access**
>
> 5.9.0 introduces unauthenticated runtime access: an app can be made publicly reachable, and processes or UI flows inside it can be opened to anonymous end users via a new built-in role.
>
> * **Two independent gates.** The app must be set to **Everyone with the link** in the Share modal AND the process or UI flow must have the **Anonymous** role assigned. If either gate is closed, the runtime returns `403 Forbidden` (`Anonymous access not enabled for this application` / `Anonymous access not enabled for this build`).
> * **System-level Anonymous role.** Auto-seeded on every new app version, cannot be deleted or edited; allowed operations are `VIEW`, `EXECUTE`, and an auto-populated `SELF_ASSIGN`.
> * **Session-bound traffic.** Anonymous requests carry an `X-Fx-Anonymous-Session-Id` header. The backend issues a new session ID on first contact; instances are bound to that session and cannot be read by another.
> * **SDK auth-skip.** The renderer decides authenticated vs anonymous from the `authToken` parameter at initialization. Token-in-storage on the same browser silently bypasses anonymous mode — container apps must scrub the `Authorization` header on public routes.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access)
> >
> > See Platform deep-dive → User roles management → Anonymous runtime access for the full feature reference.
>
> > [accordion] Key Features
> >
> > * **Share modal public-access option.** A new **General access** section in the Share modal switches between **Everyone with the link** and **Only invited users and groups**. Default remains invited-only.
> > * **Anonymous role on processes, UI flows, and reusable UI templates.** Selectable in the Permissions tab once the role is on the version; additive to other roles.
> > * **Component hide / disable rules.** UI Designer supports an Anonymous condition in role-based hide/disable rules at the component level.
> > * **Public-build asset rule.** When a build has the Anonymous role and the app is shared publicly, all assets inside (enumerations, substitution tags, media files, themes, fonts) become reachable anonymously — except UI flows and processes that don't carry the Anonymous role.

> [card]
>
> ### **Runtime authorization overhaul**
>
> Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > Open the **Runtime authorization overhaul** documentation.

> [card]
>
> ### **UI Flow permissions**
>
> Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> >
> > Open the **UI Flow permissions** documentation.

> [card]
>
> ### **End-user access management**
>
> Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> >
> > Open the **End-user access management** documentation.

> [card]
>
> ### **Operations-editor role**
>
> New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix)
> >
> > Open the **Operations-editor role** documentation.

> [card]
>
> ### **Cross-workspace projects**
>
> Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/workspaces#cross-workspace-project-import)
> >
> > Open the **Cross-workspace projects** documentation.

> [card]
>
> ### **Cross-LTS import/export**
>
> Move project versions and builds between the **5.1.x** and **5.9.x** LTS lines, in both directions. A newer platform version imports exports produced by an older one, and exports produced on a newer version can target an older one — useful for shipping a hotfix to an environment that hasn't been upgraded yet. Compatibility is patch-agnostic: any 5.9.x patch works with any 5.1.x patch.
>
> When exporting to an older version, resources whose type doesn't exist there are excluded automatically and listed in a `manifest_excluded.json` file in the archive, so the import still succeeds. The lowest version in the export/import path defines the usable functionality.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import)
> >
> > Open the **Cross-version export and import** documentation.

> [card]
>
> ### **Active policy: group overrides**
>
> Active policy overrides can now target **runtime groups** instead of runtime roles. The override resolves the active build for every member of the group at runtime, with a priority field deciding which group wins when a user belongs to several.
>
> Role-based overrides are deprecated in the same change. The **Role** override type is gone from the Add / Edit modal, and any role overrides carried over from a 5.1.x upgrade are kept in the table for visibility only — they are flagged **DEPRECATED**, excluded from runtime resolution, and can only be deleted.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-policy)
> >
> > See Projects → Runtime → Active policy for the full configuration model.
>
> > [accordion] Key Features
> >
> > * **Group override type.** Add / Edit Policy Override now exposes **Username** and **Group**. The group picker lists runtime groups that have a runtime role configured for the current project.
> > * **Priority is mandatory and unique per project for group overrides.** Lower numbers win when several groups match the same user. Username overrides ignore priority and always take precedence.
> > * **Resolution order.** Username override → Group override (lowest priority wins) → Global policy.
> > * **Role overrides deprecated.** Removed from the Add / Edit modal. Existing role rows are rendered muted with a **DEPRECATED** marker and a red banner; only the delete action remains. Deprecated role overrides are excluded from runtime resolution.
> > * **Test panel.** The effective-policy test panel simulates resolution for a given user.
> > * **Audit log.** Group override create / update / delete / enable / disable events are recorded.
>
> > [accordion] Upgrade impact
> >
> > Upgrading from 5.1.x carries existing role overrides into the new table as deprecated entries. They no longer affect runtime behavior. Recreate the intended access using group overrides and delete the role rows. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.

> [card]
>
> ### **Roles carried across project-version merges**
>
> Application-level role definitions are now carried into the merged project version automatically. Before 5.9.0, merging two project versions could leave the role table in a partial state. Bindings defined on one side were not consistently propagated to the merged version. 5.9.0 clones the roles from the destination latest version onto the merged version atomically as part of the merge transaction, so merges with role changes complete without follow-up manual cleanup.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Roles propagated as part of the merge.** When a project version is merged, application-version roles from the destination latest version are cloned onto the merged version in the same transaction.
> > * **No manual role re-binding after merge.** Operators no longer need to re-apply role bindings on the merged version. The merge completes in a single commit; the merged version is immediately usable.

> [card]
>
> ### **Log-in page redesign**
>
> The Designer log-in page is refreshed to align with the platform's design system. When an organization has an external IdP configured, the previous fine-print fallback link is replaced with a primary button labeled with the IdP configuration's **Display name**. Field labels and call-to-action copy across the log-in flow are aligned with the rest of the UI.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **IdP provider button.** When the organization has an IdP configured, the log-in screen surfaces a primary button labeled with the IdP's **Display name**, instead of a fine-print link below the form.
> > * **Refreshed copy.** Updated labels across the flow: **Log In** replaces *Sign In*, **Reset Password** replaces *Forgot password?*, and the page title becomes **Log In**.

> [card]
>
> ### **Chat component**
>
> Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component)
> >
> > Open the **Chat component** documentation.

> [card]
>
> ### **Conversational Workflows**
>
> Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> >
> > Open the **Conversational Workflows** documentation.

> [card]
>
> ### **Voice input + Speech-to-Text**
>
> Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> >
> > Open the **Voice input + Speech-to-Text** documentation.

> [card]
>
> ### **Memory capabilities**
>
> Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> >
> > Open the **Memory capabilities** documentation.

> [card]
>
> ### **Intent Classification node**
>
> Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> >
> > Open the **Intent Classification node** documentation.

> [card]
>
> ### **Chat-based UI Flows**
>
> UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> >
> > Open the **Chat-based UI Flows** documentation.

> [card]
>
> ### **AI Triggers**
>
> Named parameterized message templates to launch conversational workflows with context.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> >
> > Open the **AI Triggers** documentation.

> [card]
>
> ### **Stop agent response**
>
> Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> >
> > Open the **Stop agent response** documentation.

> [card]
>
> ### **Chat title generation and conversation search**
>
> Chat sessions now get a meaningful title generated automatically from the user's first message. No more "untitled chat" entries in the history. End users can also search across all their conversations with a single query that scans both message bodies and session titles.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Auto-generated session title.** The first user message seeds a provisional title (first 7 words). A one-shot LLM call then refines it into a concise descriptive title; the chat list updates live via an SSE event.
> > * **Conversation search.** `/api/conversations` accepts a `q` query parameter (2–200 characters). Matches against both session titles and message bodies. Each result carries a `snippet` field showing the matched excerpt.
> > * **Title update event.** When the LLM title is generated, the gateway emits a `chatSessionRenamed` event on the chat session channel; the chat list shows the refined title on the next load.
> > * **Single-shot generation.** Title generation runs exactly once per session, on first persist. The provisional 7-word title remains in place if the LLM call fails. No error surfaces to the end user.

> [card]
>
> ### **Evaluations**
>
> 5.9.0 introduces Evaluations: score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Attach datasets to AI nodes, launch experiments, and read per-evaluator aggregate scores plus per-test-case details.
>
> * **10 built-in evaluators across three categories.** LLM-as-judge (Correctness, Conciseness, Hallucination, Answer relevance), RAG (Groundedness, Helpfulness, Retrieval relevance), and Code (Exact match, Levenshtein, JSON match). Numeric evaluators ship with default thresholds; binary evaluators return pass/fail.
> * **Datasets attached to AI nodes.** Test cases sourced manually or captured from real node executions. The dataset persists a schema snapshot so older runs remain reproducible if the workflow changes underneath.
> * **Async judge pipeline.** A new Python `evals-judge` event-driven worker consumes `ai.flowx.ai-platform.evals-judge.job.request.v1`, scores each (test case × evaluator) pair via the configured judge LLM, and publishes back on the response topic. Unscored jobs land on a DLQ for manual review.
> * **Per-org judge model.** A new `EVAL` capability is registered in the org-manager LLM catalogue. Platform default is `gpt-5.4-mini`, backfilled per org on upgrade so evals work out-of-the-box.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/evaluations)
> >
> > See AI Platform → Evaluations for the user workflow, evaluator catalogue, REST API surface, and operator setup.
>
> > [accordion] Key Features
> >
> > * **Designer workflow.** Add a dataset on an AI node, add test cases (manually or captured from a node execution), pick evaluators, launch an experiment, read aggregate + per-test-case reports.
> > * **LLM-as-judge scoring.** A judge LLM reads the model output (and optional expected output) and scores it on a single rubric, returning a numeric score plus its reasoning.
> > * **RAG-quality scoring.** Judges the retrieval side of a RAG workflow — is the retrieved context grounded, helpful, and relevant?
> > * **Deterministic code evaluators.** No LLM call. Exact match, normalized Levenshtein, and JSON-shape match against the dataset's output contract.

> [card]
>
> ### **PII Guard: per-entity detections on documents and images**
>
> PII Guard scans on document and image AI nodes now surface the same per-entity detection list already shown for text scans. The run console reports each match with its entity type, confidence, original value, and replacement, making it easy to verify what was redacted on file-based AI inputs.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Same shape as text scans.** Document and image scans now return a `detections` list with `entityKey`, `confidence`, `originalValue`, `replacement`, and `direction`, matching the existing text-scan output.
> > * **Bounding regions for document and image hits.** Each detection on a `DOCUMENT` or `IMAGE` source includes `regions` (`x`, `y`, `width`, `height`) so the run console can highlight where the entity was matched.
> > * **Source-type tagging.** Detections carry a `sourceType` of `TEXT`, `DOCUMENT`, or `IMAGE`, mirroring the wrapper's `sourceType` field so audit consumers can attribute matches to the right payload.
> > * **Backward-compatible upgrade.** On older data-privacy versions that don't yet return the analyzer pass for object endpoints, `detections` stays empty and the redacted artifacts continue to be produced and downloadable.

> [card]
>
> ### **Custom Agent nodes**
>
> AI agents that use MCP tools to act autonomously inside workflows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> >
> > Open the **Custom Agent nodes** documentation.

> [card]
>
> ### **Web Search tool for Custom Agents**
>
> Custom Agent nodes can call a built-in web search tool to look up up-to-date information from the public web during a run. Turn it on with a single toggle — the agent decides when to search based on its instructions and the user's request.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Single toggle.** Enable **Tools → Built-in tools → Use Web Search Tool** on a Custom Agent node. Off by default; no extra configuration.
> > * **Agent-driven.** The agent calls web search on its own when the task needs current information, and folds the results into its response.

> [card]
>
> ### **MCP integration**
>
> MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> >
> > Open the **MCP integration** documentation.

> [card]
>
> ### **Knowledge Bases**
>
> Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > Open the **Knowledge Bases** documentation.

> [card]
>
> ### **AI Providers self-service**
>
> Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/ai-providers)
> >
> > Open the **AI Providers self-service** documentation.

> [card]
>
> ### **Extract Data from File**
>
> LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> >
> > Open the **Extract Data from File** documentation.

> [card]
>
> ### **Web Page Extractor / Web Crawler**
>
> Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> >
> > Open the **Web Page Extractor / Web Crawler** documentation.

> [card]
>
> ### **Context Retrieval**
>
> RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> >
> > Open the **Context Retrieval** documentation.

> [card]
>
> ### **AI Developer generates Custom Components**
>
> Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> >
> > Open the **AI Developer generates Custom Components** documentation.

> [card]
>
> ### **Operational prompt split**
>
> The single Operation Prompt field on AI nodes is split into two inputs so the static portion of the prompt can be cached by the LLM provider while dynamic values are passed separately. **Instructions** holds the agent's role, tasks, and expected I/O, sent as the System message and cached between executions, so `${}` dynamic values are not allowed. The **Context** field, inside the **Background** section, takes the dynamic per-execution prompt text and supports `${}` references, sent as the User message and not cached.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Instructions: cached System message.** Mandatory. Holds the agent's role, tasks, and expected input/output. Sent as the System message and cached by the LLM between executions. `${}` references are rejected to keep the cache key stable.
> > * **Background section: dynamic User message.** Wraps the Knowledge Base selector, the **Context** textarea (free text with `${}` support), the **Use only referenced values as input** toggle, and, in Chat Driven workflows, the **Use conversation memory** toggle. Sent as the User message on every execution; not cached.
> > * **Lower LLM cost and latency.** The static portion of the prompt is sent once per cache window instead of on every execution, so each call pays only for the dynamic Background section. The longer the Instructions, the bigger the per-call saving.
> > * **Applies to every AI node subtype.** The split UI is now shared by all AI node subtypes that previously used the single Operation Prompt field.

> [card]
>
> ### **Manage Knowledge Base content from Runtime**
>
> A new **Test KB** option on the build is available in runtime, giving operators visibility into Knowledge Base content that was previously opaque after deployment. Authorized users can inspect chunks, add or replace sources, edit metadata, and query the KB without going back to the Designer. Useful for debugging retrieval issues and keeping KBs current as business knowledge evolves.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Six runtime operations.** Create store, Append content, Replace content, Delete store, Edit metadata, and Query. All from the Test KB option inside the running app.
> > * **Files and payloads.** Both file uploads and inline payloads can be added to the KB through this feature.
> > * **Permission-gated.** KB management at runtime is controlled by runtime authorization, so only users with the right role see the Test KB controls.
> > * **Visibility into chunking.** Inspect how documents were chunked and what metadata was captured, useful when debugging retrieval quality on client-uploaded content.

> [card]
>
> ### **UI Flows**
>
> 5.9.0 closes the UI Flows feature: reusable, multi-platform UI (web, iOS, Android) as first-class project resources with their own lifecycle and runtime sessions. UI Flows now reach feature parity with processes for end-user-facing apps that don't need a BPMN process underneath.
>
> * **Multi-platform.** Author once in the Designer; UI Flows render on web (React), iOS, and Android via the platform-specific renderers. Layouts and component bindings travel together as a single resource.
> * **Sessions and runtime monitoring.** Each UI Flow run is a `UiFlowSession` with its own state, navigation history, and SSE event stream. Operators can monitor and inspect sessions from the runtime.
> * **Process integration.** UI Flows can start processes (Start Process action), navigate to other UI Flows (Navigate UI action), and embed a Process Renderer to show a running process inside a UI Flow. Workflows can also be invoked from a UI Flow with a Start Workflow action.
> * **Per-UI-Flow permissions.** A dedicated Permissions tab on each UI Flow controls which roles can run it. Runtime enforces with `403`; assignments travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows)
> >
> > See Building blocks → UI Flows for the full feature reference, including Navigation Areas, session variables, route management, and the component reference.
>
> > [accordion] Key Features
> >
> > * **Navigation Areas.** Group UI components into named areas for layout, scroll, and per-area transitions.
> > * **Start Parameters and Session Variables.** Pass typed inputs into a UI Flow at start; persist state across nodes via Session Variables.
> > * **Route management.** Each UI Flow exposes a stable runtime route; nested navigation preserves browser history and back/forward behaviour.
> > * **Task Manager component.** Drop the Task Manager surface inside a UI Flow to drive process tasks from the same UI shell.
> > * **onClick and On Display events, plus a new On Load event.** Component-level events trigger workflows or UI actions, with the new On Load event firing when the UI Flow first opens.
> > * **Breadcrumbs.** Built-in breadcrumbs reflect the Navigation Area hierarchy and follow the active theme.
> > * **Process Renderer + Start Workflow action.** Embed a running process inside a UI Flow; trigger an integration workflow from a button or event without leaving the flow.

> [card]
>
> ### **UI Flow session expiry**
>
> A UI Flow session can be set to expire automatically after a fixed duration or on a schedule. Once expired, the session becomes read-only — the user keeps the data already loaded but cannot take further action.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Flexible expiry.** Set the **Expiry time** in **Settings → General** as an ISO-8601 duration (for example `PT3M22S`) or a cron expression (for example `0 0 9-17 * * MON-FRI`). Empty means no expiry.
> > * **Read-only on expiry.** Expired sessions block all actions; loaded data stays visible and nothing is wiped.
> > * **Server-enforced.** The platform marks sessions `EXPIRED` server-side, so it applies the same way in the deployed app and the Designer preview.

> [card]
>
> ### **Configurable modal component**
>
> Modals on process screens and UI Flows gain configurable content and layout. Set a title and subtitle, control dismiss behavior, and align and size the modal from the Designer.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Content.** Set the modal **Title** and **Subtitle** from the Settings panel.
> > * **Dismiss behavior.** Toggle **Dismissible**, allow **Backdrop click**, and optionally show a **Confirmation alert** with custom title, message, and button labels.
> > * **Layout.** Align content **Left**, **Center**, or **Right**, and set **Width**/**Height** to **Fixed** or **Auto**.
> > * **Theme-level styling.** The modal **shadow** and **dismiss icon** are defined once in the theme's Modal section.

> [card]
>
> ### **Custom Components**
>
> Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> >
> > Open the **Custom Components** documentation.

> [card]
>
> ### **Process Renderer in UI Flows**
>
> Embed process renderers inside UI Flows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > Open the **Process Renderer in UI Flows** documentation.

> [card]
>
> ### **UI Flow sessions monitoring**
>
> Runtime view with session list, audit log, process tracking, workflow debugging.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> >
> > Open the **UI Flow sessions monitoring** documentation.

> [card]
>
> ### **Accessibility (WCAG 2.1 AA)**
>
> Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> All Deployments

> [card]
>
> ### **New theme components**
>
> Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Open the **New theme components** documentation.

> [card]
>
> ### **Multi-file bulk upload**
>
> Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> >
> > Open the **Multi-file bulk upload** documentation.

> [card]
>
> ### **Card default collapse + Tables in Collections**
>
> Cards configurable to load collapsed; Table UI components inside Collection prototypes.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> >
> > Open the **Card default collapse + Tables in Collections** documentation.

> [card]
>
> ### **Event Handlers**
>
> The UI component configuration panel introduces a dedicated **Event Handlers** section. The legacy `flowx_props` bag is replaced by a typed, per-handler form covering action type, optional analytics, custom body, destination, and collection save-key fields. Container components (Page, Zone, Modal, Tab Bar in UI Flows; Tab on process screens) and inline components resolve their actions through the same model.
>
> Existing UI events and AI triggers are migrated automatically. A Liquibase migration runs on the first 5.9.0 boot and moves the data into the new `ui_action` model. No project re-export or re-import is required.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Typed Event Handlers.** Each handler is a named, typed entity instead of a free-form prop, making configuration easier to validate and audit.
> > * **Action type selector.** Pick the action type from a dropdown that knows which fields are required for that type.
> > * **Analytics, body, destination, save-key.** Per-handler sub-forms cover analytics events, custom request bodies, destination resolution, and collection save-key fields.
> > * **Unified for inline and container components.** Page, Zone, Modal, and Tab Bar containers in UI Flows use the same Event Handlers model as inline components; on process screens, Tab containers use it.

> [card]
>
> ### **Theming and Designer polish**
>
> > [accordion] Theming
> >
> > Form field labels, error messages, and helper text gain padding controls and scoped style variants in the theme model. Theme Admin exposes the new padding properties on segmented buttons, sliders, and input selections; the React and Angular SDKs apply the values in the renderers; the Designer preview reflects them in place. Form fields also pick up a consistent **mandatory label** style applied automatically when a field is required.
> >
> > * **Scoped variants for labels, errors, helpers.** Theme configs can override label, error, and helper styles per component without affecting other parts of the form.
> > * **Padding for segmented buttons, sliders, input selections.** Theme Admin adds label, error, and helper padding controls for these components; values flow through to all renderers.
> > * **Mandatory label style.** A consistent style for mandatory-field labels, applied automatically when a form field is required.
> > * **Designer preview parity.** Theme overrides and paddings are visible in the Designer preview without round-tripping through a runtime app.
> >
> > All Deployments
>
> > [accordion] Designer polish
> >
> > The command center floating action button is now hidden on the running-instance screens of Processes, UI Flows, and UI Templates, where it overlapped with the instance view; it reappears when the instance data panel is open. The command center remains reachable through the standard keyboard shortcut and from screens where it does not interfere.
> >
> > All Deployments

> [card]
>
> ### **Email Trigger**
>
> New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> >
> > Open the **Email Trigger** documentation.

> [card]
>
> ### **Microsoft Outlook data source**
>
> Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> >
> > Open the **Microsoft Outlook data source** documentation.

> [card]
>
> ### **Incoming Webhooks**
>
> New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> >
> > Open the **Incoming Webhooks** documentation.

> [card]
>
> ### **Oracle Database integration**
>
> Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL. Beyond tables and `SELECT`, queries can also target views, functions, and stored procedures, with output parameters returned to the workflow.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> >
> > Open the **Oracle Database integration** documentation.

> [card]
>
> ### **Unmanaged MongoDB data source**
>
> Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> >
> > Open the **Unmanaged MongoDB data source** documentation.

> [card]
>
> ### **File Storage data source**
>
> A new data source connecting workflows to external file storage — FTP, SFTP, S3 / S3-compatible, or Azure Blob Storage. Define named List, Download, Upload, Delete, and Move operations scoped to a root path, browse and test them in Designer, and call them from a Data Source node. Operations run in the new `file-gateway` service, exchanging files with the `document-plugin`.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/file-storage)
> >
> > Open the **File Storage data source** documentation.

> [card]
>
> ### **Send Notification action + Email Sender**
>
> SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> >
> > Open the **Send Notification action + Email Sender** documentation.

> [card]
>
> ### **Advanced Query Builder**
>
> Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> >
> > Open the **Advanced Query Builder** documentation.

> [card]
>
> ### **Parallel branches in workflows**
>
> Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> All Deployments

> [card]
>
> ### **REST endpoint caching + workflow partitioning**
>
> TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> All Deployments

> [card]
>
> ### **Data mappers + workflow data models**
>
> Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> >
> > Open the **Data mappers + workflow data models** documentation.

> [card]
>
> ### **Proxy Server Connections**
>
> Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> >
> > Open the **Proxy Server Connections** documentation.

> [card]
>
> ### **Faster authoring loop**
>
> 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.
>
> All Deployments

> [card]
>
> ### **Meta webhook provider**
>
> Incoming Webhooks add **Meta** as a built-in provider alongside Generic and Slack, covering WhatsApp, Messenger, Instagram, and Threads. The webhook-gateway handles the Meta-specific subscription handshake and signature verification natively. No custom adapter code required to wire a Meta-platform integration into a FlowX process.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Subscription handshake.** The gateway answers Meta's GET URL-verification request by validating `hub.mode=subscribe` and the provided `hub.verify_token` against the configured verify token, then echoes `hub.challenge` back. Constant-time token comparison.
> > * **X-Hub-Signature-256 verification.** Every POST is authenticated with the `X-Hub-Signature-256` HMAC-SHA256 signature using the configured app secret. Requests with missing or invalid signatures are rejected before reaching the process engine.
> > * **Two secrets per webhook.** When you create a Meta webhook in Integration Designer, two masked inputs appear in the configuration panel: **Verify token** (used during the handshake) and **App secret** (used for signature verification). Both are required.
> > * **Multi-product support.** A single Meta webhook can receive events from WhatsApp, Messenger, Instagram, and Threads. The provider is configured at the webhook level; the channel is part of the payload.
>
> > [accordion] Configuration
> >
> > Select **Meta** in the provider dropdown when creating the webhook data source. Both secret fields are required:
> >
> > | Field | Description |
> > | - | - |
> > | **Verify token** | The token Meta sends back during the GET URL-verification handshake. Choose any string; configure the same value on the Meta App developer console. |
> > | **App secret** | The App secret from the Meta App configuration; used to verify the `X-Hub-Signature-256` HMAC on every POST. |
> >
> > Both values are stored as a JSON-packed pair on the existing webhook secret field. No schema migration is required.
> >
> > See [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#meta-provider) for the full setup walk-through.

> [card]
>
> ### **Documents in process instances**
>
> Each process instance now exposes a dedicated **Documents** tab. A single source of truth for every document handled during the process, regardless of how it entered the instance. Operations teams can review tracking metadata, preview, and download attached files from one place rather than walking through the process timeline.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **All document sources in one place.** End-user uploads via the file-upload component, attachments from email triggers, files generated from HTML templates, OCR output, and files produced by AI workflow nodes, all listed under one tab.
> > * **Tracking metadata and preview.** Each row shows source, timestamp, and uploader, with inline preview for supported file types.
> > * **Direct download.** Download any attached document directly from the Documents tab.
> > * **Faster operations review.** No more clicking through the process timeline to reconstruct which file came in at which step.

> [card]
>
> ### **Two-stage attachment filtering for Email triggers**
>
> Email triggers (IMAP and Microsoft Outlook) now expose a two-stage filter on each trigger: choose which incoming emails create a process instance, then choose which attachments are forwarded into the process. The previous single on/off validations toggle is replaced with explicit, per-trigger control over inbound mail.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start Process for.** Trigger the process for all emails, only emails with attachments, or only emails carrying selected file types (PDF, DOCUMENT, IMAGE, EXCEL, ZIP).
> > * **Save email attachments on process.** Forward all attachments, none (metadata-only), or only specific file types into the process instance.
> > * **Trigger-level rejection.** Emails that fail the trigger condition or exceed **Maximum File Count** are rejected with explicit Failed Triggers causes. **No attachments**, **No matching file types**, **File count exceeded**.
> > * **Backward-compatible upgrade.** Existing triggers are migrated to **All incoming emails** + **All attachments** with no manual intervention. Reopen each trigger to reapply file-type filtering if you previously relied on the validations toggle.

> [card]
>
> ### **Resume a process from an incoming webhook**
>
> Incoming Webhooks can now drive a **Message Catch Intermediate Event**, not just a Message Start Event. When a process is paused on an intermediate catch event, an external system can POST to the webhook to resume that specific instance. Useful for callbacks from third-party services, asynchronous job completions, or operator actions delivered over HTTP.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start or resume from one webhook model.** The same webhook data source can start new processes (on a Message Start Event) or resume waiting ones (on a Message Catch Intermediate Event). The trigger type is set automatically based on where the webhook is attached.
> > * **Process Correlation Key.** Each intermediate catch event declares a Process Correlation Key (a business variable like `applicationId`). The webhook-gateway matches this value against the incoming payload to route the resume to the right process instance. The Webhook Correlation Key now accepts array indices in square brackets (`entry[0].changes[0].value.messages[0].text.body`), so the canonical Meta WhatsApp resume path works without flattening upstream.
> > * **Validation at design time.** Process Correlation Key and Process Key are required on intermediate webhook catch events and are validated when the message event is created or updated.
> > * **Backward-compatible upgrade.** Existing webhooks are migrated to `triggerType=START_PROCESS` with no manual intervention. New webhooks attached to an intermediate catch event are flagged `RESUME_PROCESS` automatically.

> [card]
>
> ### **REST endpoints: content-type-aware responses**
>
> REST endpoint responses in Integration Designer are now parsed by content type rather than assumed to be JSON. The endpoint's `Accept` header drives parsing: JSON, plain text, and XML responses are each handled with the right parser, and the original XML string is preserved alongside the parsed map so downstream nodes can read either form. Existing JSON-returning endpoints continue to work without configuration changes.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Accept-driven response parsing.** The endpoint's `Accept` header decides how the response is parsed. JSON variants (`application/json`, `application/hal+json`, `application/problem+json`, any `+json` suffix) are parsed as JSON; `text/*` is returned as a string; XML variants (`application/xml`, `text/xml`, `application/soap+xml`, any `+xml` suffix) are parsed into a JSON-shaped map. When `Accept` is missing, the endpoint falls back to `Content-Type`, then to **AUTO** best-effort.
> >
> > * **XML responses parsed into JSON-shaped objects.** XML response bodies are auto-converted to maps so existing path expressions (`response.body.someField`) work without code changes. The original XML string is preserved on `sourceBody` for callers that need it raw.
> >
> > * **Loud failures on declared mismatches.** When an endpoint declares JSON or XML and the upstream returns a different category, or returns a body that fails to parse, the node fails with a precise error message (for example, `Expected response content type "application/json" but received "text/plain"`). The original body is preserved on `rawBody`.
> >
> > * **Tolerant under AUTO and wildcards.** Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) and inferred categories (no `Accept` declared) fall back to the raw string instead of failing. Flaky or mislabelled upstreams don't break the node.
> >
> > * **XXE-safe XML parser.** XML parsing has DTD processing and external-entity resolution disabled by construction. External-entity attack payloads are neutralized; billion-laughs / entity-expansion attacks cannot fire.
> >
> > * **File downloads bypass Content-Type checks.** File-download endpoints (BINARY or BASE64) deliver the platform's own JSON payload regardless of upstream `Content-Type`, so legacy PDF, octet-stream, and image downloads work unchanged.
> >
> > * **Large XML returned raw.** XML response bodies larger than 5 MiB are returned as the raw string instead of a parsed map, so very large payloads don't block the node.
> >
> > > [!WARNING]
> > >
> > > **Mixed-content XML responses expose a new `value` key.** An XML element with both attributes and inner text (`<leaf attr="v">text</leaf>`) is now parsed to `{attr: "v", value: "text"}`. The inner text used to be silently dropped. Downstream nodes that iterate response keys or assert the exact key set on mixed-content elements may see an additional `value` entry. Path expressions that addressed attributes or child elements directly are unaffected.

> [card]
>
> ### **Raw endpoint payload type**
>
> REST endpoint configuration adds a **Raw** content type alongside JSON, Multipart, and Binary. Raw bodies are sent to the upstream system as-is. Useful for XML, SOAP envelopes, form-urlencoded payloads, or any plain-text body where you need to set the `Content-Type` header yourself.
>
> Before 5.9.0, the only way to send a non-JSON textual body was to use Multipart, which wrapped the payload in `multipart/form-data` and overrode the `Content-Type` header. Raw removes that wrapping.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Body sent as-is.** The body field is sent verbatim. The dispatcher does not transform, wrap, or pretty-print it.
> > * **Caller controls Content-Type.** Set the `Content-Type` header on the endpoint to whatever the upstream expects (`text/xml`, `application/soap+xml`, `application/x-www-form-urlencoded`, `text/plain`). The dispatcher does not override it.
> > * **Monaco plain-text mode.** The endpoint editor switches Monaco to plain text when Raw is selected. XML and SOAP indentation are preserved on paste and edit instead of being reformatted as JSON.
> > * **Shares the JSON body slot.** Raw and JSON payloads use the same storage field on the endpoint definition, so no schema migration is required. Existing endpoints continue to work without changes.

> [card]
>
> ### **Update Process Variables**
>
> JSON editor for variables on active instances with snapshot history; Compare diff.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> >
> > Open the **Update Process Variables** documentation.

> [card]
>
> ### **Stop Run for workflows**
>
> Cancel a running workflow instance from the editor.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-workflows#running-and-stopping-workflows)
> >
> > Open the **Stop Run for workflows** documentation.

> [card]
>
> ### **Notification history + template usages**
>
> `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> >
> > Open the **Notification history + template usages** documentation.

> [card]
>
> ### **Token view improvements**
>
> Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/token)
> >
> > Open the **Token view improvements** documentation.

> [card]
>
> ### **Stop workflow instances in runtime**
>
> Authorized end users can now stop running workflow instances directly from runtime. Previously, stopping a workflow required Designer access or a direct API call. The new control surfaces the action inside the runtime application alongside other workflow-instance management options.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **One-click stop.** Stop a running workflow instance from the runtime instance list.
> > * **Permission-gated.** The stop control is governed by runtime authorization.
> > * **Audited.** Stop actions are recorded on the workflow-instance audit log with the actor and timestamp.

> [card]
>
> ### **Native script engine for JavaScript and Python**
>
> The default script engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a **native subprocess pool**. Scripts run in long-running Node.js and Python worker processes managed by `process-engine` and `integration-designer`. Existing scripts that read from `input` and write to `output` keep working, including `output.put(...)`, `output.get(...)`, and bracket assignment.
>
> The change is opt-out: set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services to keep the previous engine.
>
> Self-HostedAll Deployments
>
> > [accordion] Key Features
> >
> > * **Node.js workers for JavaScript.** JavaScript runs in isolated Node.js worker processes. Each script executes in a fresh V8 context with an explicit globals allowlist and a V8-level execution timeout.
> > * **CPython workers for Python.** Python 3 runs in isolated worker processes with a curated sandbox. Common standard-library modules (`random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64`) are available without `import`. Process, OS, and network modules are blocked.
> > * **Worker pools with recycling.** Worker pools default to 16 Node.js workers and 8 Python workers, sized per service. Workers are recycled after a configurable number of executions to prevent state leakage.
> > * **HashMap method compatibility.** The familiar `output.put(key, value)`, `output.get(key)`, and `output.containsKey(key)` methods continue to work on both JavaScript and Python. The same scripts that ran under GraalVM polyglot context keep working without rewrites.
> > * **GraalVM still available as opt-in.** Set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine, useful if a script depends on GraalVM-specific polyglot features.
> > * **Hardened execution sandbox.** Per-execution fresh scope, environment variables cleared at worker startup, dangerous Python module references scrubbed before user code runs, no `require` / `process` / `global` access in JavaScript.
>
> > [accordion] Configuration
> >
> > The native engine is the default on `process-engine` and `integration-designer`. Tune worker pools and timeouts as needed:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider. `native` or `graalvm`. | `native` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size. | `16` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS execution timeout per script (ms). | `5000` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size. | `8` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python execution timeout per script (ms). | `10000` |
> >
> > See [Process engine setup → Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration) and [Integration Designer setup → Script engine configuration](/5.9/setup-guides/integration-designer-setup#script-engine-configuration) for the full set including payload size and worker recycling.
>
> > [accordion] Migration impact
> >
> > For most existing scripts the change is transparent. The `input`, `output`, `additionalData`, and `instanceMetadata` bindings behave the same, and HashMap-style access on `output` is preserved.
> >
> > Scripts that need attention:
> >
> > * **Python scripts that `import` modules outside the curated allowlist.** Narrow the script to use only the pre-loaded modules, or stay on GraalVM via the opt-out env var.
> > * **JavaScript scripts that reach for `require(...)`, `process`, or `global`.** Those references were never part of the supported surface area but may have worked under GraalVM. Rewrite to use only the bindings provided, or stay on GraalVM via the opt-out env var.
> > * **Scripts that depended on GraalVM-specific polyglot APIs** (calling Java classes from JavaScript / Python). Stay on GraalVM via the opt-out env var.
> >
> > See [Script runtime change for JavaScript and Python business rules](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit checklist.

> [card]
>
> ### **Single-org self-hosted deployment**
>
> Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/organization-deployment)
> >
> > Open the **Single-org self-hosted deployment** documentation.

> [card]
>
> ### **License service**
>
> Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> >
> > Open the **License service** documentation.

> [card]
>
> ### **Authentication: opaque-token → JWT**
>
> Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/authentication-iam)
> >
> > Open the **Authentication: opaque-token → JWT** documentation.

> [card]
>
> ### **New services to deploy**
>
> `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/prerequisites#new-services-to-deploy)
> >
> > Open the **New services to deploy** documentation.

> [card]
>
> ### **Ingress routing and CORS handling**
>
> The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/ingress-routing)
> >
> > Open the **Ingress routing and CORS handling** documentation.

> [card]
>
> ### **Kafka configuration alignment**
>
> Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/kafka)
> >
> > Open the **Kafka configuration alignment** documentation.

> [card]
>
> ### **OpenTelemetry + SpiceDB DR**
>
> OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> All Deployments

> [card]
>
> ### **Durable message-processing**
>
> The process engine now persists parked integration and external-message responses durably, so a response that arrives before its process is ready to consume it survives a runtime restart instead of being lost. This removes a class of stuck process-token failures and improves message-processing robustness at runtime.
>
> All Deployments

> [card]
>
> ### **Task management localization**
>
> 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Open the **Task management localization** documentation.

> [card]
>
> ### **React Native SDK**
>
> FlowX 5.9.0 ships a brand-new **React Native SDK**, bringing the same process renderer model that has powered the React, Angular, iOS, and Android SDKs to React Native apps. Teams building cross-platform mobile or embedded React Native experiences can now host FlowX processes natively, with forms, navigation, and CMS integration handled by the SDK.
>
> A companion demo app is included as a reference integration, covering authentication, the showcase page, and the wiring needed to start a process from inside a container app.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Process renderer.** Render FlowX processes inside any React Native screen with the same component model as the other SDKs.
> > * **Forms and basic components.** Page, Button, Text, Container, Card, and form components ship out of the box.
> > * **CMS integration.** Static content and theming load from the FlowX CMS, including dynamic display values.
> > * **Navigation.** Basic process navigation between screens follows the same patterns as the iOS and Android SDKs.
> > * **Demo app included.** A demo app with authentication and a showcase page is shipped alongside the SDK as a reference integration.

> [card]
>
> ### **iOS UI Flows support**
>
> The iOS renderer reaches feature parity with the React and Angular renderers on UI Flows. iOS apps can now start UI Flows from container apps, manage UI Flow sessions, dismiss modals, handle UI actions, and render document-plugin subtypes (images and document previews).
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start UI Flow from container app.** Container apps can launch a UI Flow with start parameters and handle the response.
> > * **UI Flow session management.** The renderer manages a UI Flow session lifecycle on iOS the same way it does on web.
> > * **onLoad UI Event for Page.** Pages emit an `onLoad` UI Event that iOS handlers can listen to, matching the cross-platform event model.
> > * **Dismiss action and dismiss-on-completion.** A `dismiss` action type cleanly closes modals; `dismiss on completion` on `START_WORKFLOW` actions auto-closes the launching modal when the workflow finishes.
> > * **UI Flow start params.** Pass typed start parameters into a UI Flow at launch.
> > * **Upload File support.** UI Flows on iOS support file upload, including image and document-preview document-plugin subtypes.
> > * **Updated start-process endpoint.** The iOS renderer uses the latest start-process endpoint and `data` property on Start UI Flow, aligned with the web SDKs.
> > * **New native components.** Tooltip, Separator, Progress View, and Markdown components are now rendered natively on iOS, bringing the iOS component set closer to parity with the React and Angular renderers.
> > * **Accessibility properties from UI Designer.** Accessibility properties configured in the UI Designer flow through to the iOS renderer, so screen reader labels and traits are honored on native screens.

> [card]
>
> ### **React 19 upgrade**
>
> The React SDK upgrades to **React 19**, picking up the runtime improvements and APIs that ship with that release. Surrounding `@flowx/*` packages are upgraded in lockstep so the renderer continues to work as a single coherent bundle.
>
> Host apps embedding the React renderer should plan a React 19 upgrade on their side and run the standard React migration checks before adopting 5.9.0.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **React 19 runtime.** Adopts the React 19 reconciler and the APIs that ship with that release.
> > * **Packages upgraded in lockstep.** All `@flowx/*` web SDK packages move to the same baseline so the renderer ships as one coherent bundle.
>
> > [accordion] Host app impact
> >
> > Host apps that embed the React renderer must be on React 19 themselves. Run the React 19 codemods and verify any third-party React libraries you depend on are compatible before upgrading FlowX.

> [card]
>
> ### **Runtime authorization and sharing**
>
> This is the biggest governance change in the 5.1 → 5.9 upgrade. End-user identities, runtime roles, and sharing assignments move out of Keycloak into FlowX-managed records, with project-version-scoped roles and a dedicated Share modal flow on Solutions.
>
> > [card] [Runtime authorization completion](#runtime-authorization-completion)
> >
> > Closes the rewrite: per-environment sharing checklist, project-level end-user roles, data-sync Keycloak provisioning. See the 5.9.0 card above.
>
> > [card] [Anonymous runtime access](#anonymous-runtime-access)
> >
> > Built-in `Anonymous` role + Share modal "Everyone with the link" option for unauthenticated end users. Session-bound (`X-Fx-Anonymous-Session-Id`), fire-and-forget; per-component hide/disable rules; SDK auth-skip mode.
>
> > [card] [Runtime authorization overhaul](#runtime-authorization-overhaul)
> >
> > Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> > [card] [UI Flow permissions](#ui-flow-permissions)
> >
> > Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> > [card] [End-user access management](#end-user-access-management)
> >
> > Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> > [card] [Operations-editor role](#operations-editor-role)
> >
> > New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> > [card] [Cross-workspace projects](#cross-workspace-projects)
> >
> > Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.

> [card]
>
> ### **Conversational AI**
>
> 5.9 takes FlowX from no chat to production conversational AI: the Chat component, conversational workflows with memory and intent classification, voice and speech-to-text, chat-based UI Flows, and runtime controls.
>
> > [card] [Chat component](#chat-component)
> >
> > Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> > [card] [Conversational Workflows](#conversational-workflows)
> >
> > Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> > [card] [Voice input + Speech-to-Text](#voice-input-+-speech-to-text)
> >
> > Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> > [card] [Memory capabilities](#memory-capabilities)
> >
> > Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> > [card] [Intent Classification node](#intent-classification-node)
> >
> > Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> > [card] [Chat-based UI Flows](#chat-based-ui-flows)
> >
> > UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> > [card] [AI Triggers](#ai-triggers)
> >
> > Named parameterized message templates to launch conversational workflows with context.
>
> > [card] [Stop agent response](#stop-agent-response)
> >
> > Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.

> [card]
>
> ### **AI Agents and Knowledge**
>
> The agent-builder story: Custom Agents, MCP integration, Knowledge Bases for RAG, document and web extraction, AI Providers self-service, and PII Guard.
>
> > [card] [Evaluations (Evals)](#evaluations)
> >
> > Score AI node outputs against test cases with 10 built-in evaluators (LLM-as-judge: correctness, conciseness, hallucination, answer-relevance; RAG: groundedness, helpfulness, retrieval-relevance; code: exact-match, Levenshtein, JSON-match). Datasets attached to AI nodes, async judge pipeline via the new `evals-judge` service + 3 Kafka topics, per-org judge model via the new `EVAL` capability (default `gpt-5.4-mini`).
>
> > [card] [Custom Agent nodes](#custom-agent-nodes)
> >
> > AI agents that use MCP tools to act autonomously inside workflows.
>
> > [card] [MCP integration](#mcp-integration)
> >
> > MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> > [card] [Knowledge Bases](#knowledge-bases)
> >
> > Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> > [card] [AI Providers self-service](#ai-providers-self-service)
> >
> > Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> > [card] [PII Guard](#pii-guard-per-entity-detections-on-documents-and-images)
> >
> > Per-AI-node guardrail with Strict / Balanced / Relaxed presets, input/output scans, file redaction. 5.9.0 adds per-entity detections on documents and images. See the 5.9.0 card above.
>
> > [card] [Extract Data from File](#extract-data-from-file)
> >
> > LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> > [card] [Web Page Extractor / Web Crawler](#web-page-extractor-/-web-crawler)
> >
> > Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> > [card] [Context Retrieval](#context-retrieval)
> >
> > RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> > [card] [AI Developer generates Custom Components](#ai-developer-generates-custom-components)
> >
> > Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.

> [card]
>
> ### **UI Flows and Custom Components**
>
> Build user-facing apps without a process. UI Flows reach feature parity with processes; Custom Components let teams ship React code inside the Designer.
>
> > [card] [UI Flows](#ui-flows)
> >
> > Reusable multi-platform UI (web / iOS / Android) as project resources. Navigation Areas, Start Process / Navigate UI actions, Task Manager component. Breadcrumbs + Sessions monitoring. Process Renderer + Start Workflow action + On Load event. Route management + Start Parameters + Session Variables + onClick / On Display events. UI Flow permissions.
>
> > [card] [Custom Components](#custom-components)
> >
> > Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> > [card] [Process Renderer in UI Flows](#process-renderer-in-ui-flows)
> >
> > Embed process renderers inside UI Flows.
>
> > [card] [UI Flow sessions monitoring](#ui-flow-sessions-monitoring)
> >
> > Runtime view with session list, audit log, process tracking, workflow debugging.
>
> > [card] [Accessibility (WCAG 2.1 AA)](#accessibility-wcag-2-1-aa)
> >
> > Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> > [card] [New theme components](#new-theme-components)
> >
> > Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> > [card] [Multi-file bulk upload](#multi-file-bulk-upload)
> >
> > Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> > [card] [Card default collapse + Tables in Collections](#card-default-collapse-+-tables-in-collections)
> >
> > Cards configurable to load collapsed; Table UI components inside Collection prototypes.

> [card]
>
> ### **Integration and Data Platform**
>
> For builders connecting FlowX to enterprise systems, 5.9 adds new data sources, new triggers, parallel workflow execution, REST resilience, and visual query authoring.
>
> > [card] [Email Trigger](#email-trigger)
> >
> > New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> > [card] [Microsoft Outlook data source](#microsoft-outlook-data-source)
> >
> > Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> > [card] [Incoming Webhooks](#incoming-webhooks)
> >
> > New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> > [card] [Oracle Database integration](#oracle-database-integration)
> >
> > Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL.
>
> > [card] [Unmanaged MongoDB data source](#unmanaged-mongodb-data-source)
> >
> > Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> > [card] [Send Notification action + Email Sender](#send-notification-action-+-email-sender)
> >
> > SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> > [card] [Advanced Query Builder](#advanced-query-builder)
> >
> > Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> > [card] [Parallel branches in workflows](#parallel-branches-in-workflows)
> >
> > Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> > [card] [REST endpoint caching + workflow partitioning](#rest-endpoint-caching-+-workflow-partitioning)
> >
> > TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> > [card] [Data mappers + workflow data models](#data-mappers-+-workflow-data-models)
> >
> > Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> > [card] [Proxy Server Connections](#proxy-server-connections)
> >
> > Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> > [card] [Faster authoring loop](#faster-authoring-loop)
> >
> > 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.

> [card]
>
> ### **Process operations**
>
> Day-2 operations for runtime teams: edit live process state, inspect tokens with more context, audit notifications, and operate on workflow instances.
>
> > [card] [Update Process Variables](#update-process-variables)
> >
> > JSON editor for variables on active instances with snapshot history; Compare diff.
>
> > [card] [Stop Run for workflows](#stop-run-for-workflows)
> >
> > Cancel a running workflow instance from the editor.
>
> > [card] [Notification history + template usages](#notification-history-+-template-usages)
> >
> > `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> > [card] [Token view improvements](#token-view-improvements)
> >
> > Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> 5.9.0 adds **Stop workflow instances in runtime** and **Documents in process instances**. See the 5.9.0 cards above.

> [card]
>
> ### **Platform, deployment and infrastructure**
>
> Read this first if you operate a self-hosted deployment. 5.9 adds new microservices, a new deployment mode, and the auth architecture transition.
>
> > [card] [Single-org self-hosted deployment](#single-org-self-hosted-deployment)
> >
> > Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> > [card] [License service](#license-service)
> >
> > Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> > [card] [Authentication: opaque-token → JWT](#authentication-opaque-token-→-jwt)
> >
> > Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> > [card] [New services to deploy](#new-services-to-deploy)
> >
> > `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> > [card] [Native script engine for JavaScript and Python](#native-script-engine-for-javascript-and-python)
> >
> > JavaScript and Python business rules and workflow scripts run on a Node.js + CPython subprocess pool by default. HashMap-style access on `output` is preserved; GraalVM remains available via `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`. See the 5.9.0 card above and the migration audit checklist.
>
> > [card] [Ingress routing and CORS handling](#ingress-routing-and-cors-handling)
> >
> > The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> > [card] [Kafka configuration alignment](#kafka-configuration-alignment)
> >
> > Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> > [card] [OpenTelemetry + SpiceDB DR](#opentelemetry-+-spicedb-dr)
> >
> > OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> > [card] [Task management localization](#task-management-localization)
> >
> > 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.

***

## Deployment notes

> [card] [Deployment guidelines v5.9.0](./deployment-guidelines-v5.9)
>
> Component versions, environment variables, Kafka topics, and self-hosted upgrade guidance.

> [card] [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview)
>
> Consolidated 5.1 LTS → 5.9 LTS migration guide. Direct upgrade to 5.9.0.


# Deployment guidelines v5.9.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1

Component versions, configuration, and deployment notes for FlowX.AI 5.9.1 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.1 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.0 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.0 → 5.9.1**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

## Component versions

### Core components

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **process-engine** | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.3 |
| **admin** | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.3 |
| **designer** | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.4 |
| **cms-core** | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.2 |
| **scheduler-core** | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.2 |
| **events-gateway** | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.2 |
| **notification-plugin** | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.2 |
| **document-plugin** | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.2 |
| **task-management-plugin** | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.2 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |
| **data-search** | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.2 |
| **audit-core** | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.2 |
| **advancing-controller** | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.2 |
| **integration-designer** | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.3 |
| **application-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **runtime-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **data-sync** | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.2 |
| **authorization-system** | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.2 |
| **nosql-db-runner** | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.2 |
| **email-gateway** | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-native-sdk** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/core-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **react-saas** | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.20 |
| **Android renderer** | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.24 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-knowledgebase-rag** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-embedder** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-agent-builder** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-gateway** | 10.17.0 | 10.7.0 | - | - |
| **ai-platform-ai-analyst** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-assistant** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-ai-designer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-developer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-planner** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-kb-enrichment** | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.1 adds two Kafka topics. Both are **auto-provisioned by the Helm chart** — no manual creation is required for standard deployments. The names and env vars are listed here for environments that provision topics or ACLs manually.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | application-manager | process-engine | Runtime config-param change events; invalidates the build cache |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine | integration-designer | Notifies that a runtime instance has been terminated |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin | process-engine | Resource cache eviction triggered when a process version changes |
| `ai.flowx.evals.suggestions.job.request.v1` | integration-designer | AI Platform | Evaluation improvement-suggestion job requests |
| `ai.flowx.evals.suggestions.job.response.v1` | AI Platform | integration-designer | Evaluation improvement-suggestion job responses |

Topic env vars and consumer groups:

| Topic | Producer var (OUT) | Consumer var (IN) | Consumer group |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | `config-params` |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_OUT` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_IN` | `integration-designer-runtime-instance-terminated-group` |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT_IN` | `resource-cache-evict` |
| `ai.flowx.evals.suggestions.job.request.v1` | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT` | — (consumed by AI Platform) | — |
| `ai.flowx.evals.suggestions.job.response.v1` | — (produced by AI Platform) | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN` | `integration-designer-evals-suggestions-response-group` |

For the config-param cache-invalidation behavior, see [Engine setup → Topics related to runtime config params](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-runtime-config-params). For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.1 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including split AI permissions, the legacy script flag, and File Storage and document-preview fixes.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.0 → 5.9.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.1** is a maintenance release for the 5.9.x LTS with bug fixes, security patches, and a few targeted improvements:
>
> * **Import/export:** stability and cross-version compatibility fixes
> * **Split AI permissions:** separate governance for AI runtime usage and AI build-time tooling
> * **Legacy script flag:** per-rule Native / GraalVM script runtime selection
> * **File Storage and document-preview improvements**
> * Wide set of Designer, Renderer, and platform bug fixes
> * No breaking changes; fully compatible upgrade from 5.9.0

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Split AI permissions**](#split-ai-permissions) - Independent governance for AI usage and AI build tooling.\
> 📝 [**Legacy script flag**](#legacy-script-flag) - Per-rule Native / GraalVM script runtime selection.\
> 🗂️ [**File Storage improvements**](#file-storage-improvements) - FTP connection and preview fixes.\
> 📄 [**File Preview scroll events**](#file-preview-scroll-events) - Scroll-trigger event handlers for the File Preview component.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, Workflows, and backend bug fixes plus security patches.
>
> ***
>
> ### **Split AI permissions**
>
> > [card] Separate governance for AI usage and AI build tooling
> >
> > > [tab] Overview
> > >
> > > AI permissions are now split into two independent controls, so administrators can govern **AI runtime usage** separately from **AI build-time tooling** (AI Designer, agent building, code generation).
> >
> > > [tab] Behavior
> > >
> > > * When AI is turned off, AI-related icons and entry points are hidden rather than shown in a disabled state.
> > > * AI nodes in workflows behave consistently with the gateway's availability.
> > > * Build-time AI helpers (code generation, "Add comment") follow the dev-agent permission rather than the runtime AI permission.
> >
> > All Deployments
>
> ***
>
> ### **Legacy script flag**
>
> > [card] Per-rule Native / GraalVM script runtime
> >
> > Business rules, reusable functions, and node rules can now choose their script engine individually: the current **native** engine (the 5.9 default) or the legacy **GraalVM** engine. Rules created before the switch to native keep running on GraalVM until you migrate them, while new rules default to native, so teams can move scripts across at their own pace. The per-rule selector only appears for rules that support GraalVM; new rules run on native.
> > All Deployments
>
> ***
>
> ### **File Storage improvements**
>
> > [card] FTP connection and preview fixes
> >
> > * FTP **test connection** now resolves configuration-parameter placeholders before connecting.
> > * **File operations** also resolve configuration-parameter placeholders at runtime.
> > * FTP **file preview** works when the root path has no leading slash.
> >   All Deployments
>
> ***
>
> ### **File Preview scroll events**
>
> > [card] Scroll-trigger event handlers for File Preview
> >
> > The **File Preview** component now supports **scroll-trigger event handlers** (including a "document end" trigger), configurable in the Designer and handled by the web, iOS, and Android renderers. They let a flow detect when a user scrolls through a document or reaches its end.
> >
> > This is built for consent and disclosure use cases such as banking flows that must prove, per local regulation, that the user actually read an agreement. You can keep an action such as a **Submit** or **Accept** button hidden or disabled until the document-end event handler fires; that handler can be a simple local script that sets a flag to enable the button.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Forms to validate:** fixed scrolling through the full component hierarchy, placeholder updates, and incorrect selection of chat and tab-bar components.
> > > > * **Process instances:** fixed a browser crash when loading instances with very large execution graphs.
> > > > * **Theme admin:** fixed theme content being lost when using "copy to".
> > > > * **UI Flow:** fixed images not displaying in preview after refresh, and a missing theme UUID when returning from an expired UI Flow.
> > > > * **Actions:** stopped GET actions firing with undefined parameters.
> > > > * **Modals:** fixed dropdown flicker and layout issues with long key names.
> > >
> > > > [accordion] Renderer fixes (Web / React / React Native)
> > > >
> > > > * **Web:** fixed missing button shadow, modal content padding, and rendering when a media-file storage path is null.
> > > > * **File Preview:** fixed preview not rendering correctly, events not firing inside collections, fixed height not applied at runtime, and CORS errors when accessing preview resources.
> > > > * **React Native:** fixed date-picker shifting to a previous day and input/textarea retaining focus after moving to another component.
> > > > * **Task management:** fixed header theming (React/Angular) and the filter window disappearing after applying criteria.
> > > > * **File upload:** the upload button now supports a configurable icon, set in the Designer and rendered on web, iOS, and Android.
> >
> > > [tab] Workflows & AI
> > >
> > > > [accordion] Workflow fixes
> > > >
> > > > * Fixed END PARALLEL output including data from before the parallel branches started.
> > > > * Optimized storage of running steps for workflows.
> > > > * Fixed a crash in NoSQL node run logs when a node failed before building its options.
> > > > * Workflows and processes launched from a UI Flow now inherit the build from the parent UI Flow.
> > > > * AI node failures now surface the error details and model reasoning in the workflow run logs, making failed AI steps easier to diagnose.
> > >
> > > > [accordion] AI improvements & fixes
> > > >
> > > > * **AI Designer** generates more reliable UI from a flat template format (replacing the previous 3-level nesting), supports additional component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates by applying changes incrementally instead of regenerating from scratch, and can now generate **reusable UI templates**.
> > > > * Fixed agent responses reappearing in chat after stop and refresh.
> > > > * Fixed duplicated messages in the builder-agent chat.
> > > > * **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
> > > > * **Platform Status** now reports AI Platform components and their databases alongside the core services.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * Fixed a null value being wrongly cached when looking up the "All end-users" group, which could block logins until data-sync completed.
> > > > * Fixed copying a process or workflow to another project: the copy now succeeds, and copied workflows appear in the target project.
> > > > * Fixed an invited Designer user added as an Organization owner not being assigned to a workspace.
> > > > * Improved merge-conflict handling for custom components and UI Flows, with clearer resource identification.
> > > > * Hide/disable conditions on UI templates, processes, and UI Flows are now applied at runtime for Designer users without workspace access.
> > > > * Fixed a 500 (duplicate key) error when activating a start timer event after a new build regenerated the process resource ID.
> > > > * Fixed a 500 error when opening a Usage Overview.
> > > > * Organization settings navigation and design improvements.
> > > > * **Runtime config params:** changes to runtime configuration parameters now propagate to the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
> > > > * **Microsoft Outlook connections** now support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.1 is fully compatible with 5.9.0. No breaking changes; standard deployment procedures apply.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.0 → 5.9.1 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.1 are tracked in the [5.9.1 deployment guidelines](./deployment-guidelines-v5.9.1).&#x20;
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2

Component versions, configuration, and deployment notes for FlowX.AI 5.9.2 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.2 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.1 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.1 → 5.9.2**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and converts your data. If you did not apply that workaround, no action is needed.

> [!WARNING]
>
> **Manually marked Liquibase changesets.** If any Liquibase changesets were manually marked as executed (MARK\_RAN) to work around failures during earlier 5.9.x upgrade attempts, those records must be removed after upgrading to 5.9.2 so the corrected changesets can run. Contact FlowX support for the exact list of affected changesets before removing anything. If you did not mark any changesets manually, no action is needed.

## Component versions

### Core components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.162.1 | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.7 |
| **admin** | 10.141.1 | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.7 |
| **designer** | 10.260.7 | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.10 |
| **cms-core** | 10.102.3 | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.3 |
| **scheduler-core** | 10.85.1 | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.3 |
| **events-gateway** | 10.90.1 | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.4 |
| **notification-plugin** | 10.100.2 | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.3 |
| **document-plugin** | 10.113.2 | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.3 |
| **task-management-plugin** | 10.102.1 | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.3 |
| **reporting-plugin**\* | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.7 |
| **data-search** | 10.83.1 | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.3 |
| **audit-core** | 10.93.1 | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.3 |
| **advancing-controller** | 10.89.1 | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.3 |
| **integration-designer** | 10.189.2 | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.4 |
| **application-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **runtime-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **data-sync** | 10.98.0 | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.4 |
| **authorization-system** | 10.112.1 | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.5 |
| **nosql-db-runner** | 10.92.1 | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.3 |
| **email-gateway** | 10.91.1 | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.88.1 | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.60.1 | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.23.1 | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.78.1 | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-native-sdk** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/core-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **react-saas** | 10.260.7 | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.6 | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.25 |
| **Android renderer** | 10.5.6 | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.31 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.0 | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.0 | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.0 | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.0 | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.0 | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.0 | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.25.0 | 10.17.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.0 | - | - | - | - |
| **ai-assistant** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.0 | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.2 | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.2 introduces no new Kafka topics over 5.9.1. For the topics added in 5.9.1, see the [5.9.1 deployment guidelines](../v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics); for the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.2 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

* **Kafka reconnect backoff:** platform services now default to a gentler broker-reconnect backoff — `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MS` `1000` / `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MAX_MS` `10000` (and the consumer equivalents) — and repetitive Kafka NetworkClient connection errors log at a quieter level, tunable via `LOGGING_LEVEL_KAFKA_NETWORK_CLIENT` (default `ERROR`). No action needed unless you previously tuned these.&#x20;
* **Resource-server security type:** the default for `idp.resourceServer.securityType` on the AI services changes to `jwt`. If you previously set the security type to `jwt` explicitly as a workaround, that override is no longer needed and can be removed.&#x20;

#### Data partitioning and archiving

5.9.2 adds configuration for the archiving lifecycle on the process-engine and Integration Designer. All new settings default to off, so no action is required on upgrade.&#x20;

* **Stuck-instance termination:** an optional sweep (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`, default `false`) terminates instances that would otherwise block archiving. Enable it, plus its cron and batch-size, if archiving stalls on unfinished data.
* **Legacy backfill:** one-shot backfills of `partition_id` (`FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED`) and `organization_id` (`FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED`), both default `false`, populate legacy rows when you first turn partitioning on. The organization-ID backfill is optional on self-hosted and can remain `false`.

> [!WARNING]
>
> **Partitions that still contain unfinished instances are not archived.** Starting with 5.9.2, the archiving job detaches a partition only when every process instance in it has reached a finished state (`FINISHED`, `FINISHED_WITH_ERROR`, `FAILED`, `EXPIRED`, `ABORTED`, `DISMISSED`, or `TERMINATED`). A single instance still in `CREATED`, `STARTED`, or `ON_HOLD` blocks the entire partition; it is retried on the next archiving run. The same rule applies to workflow instances on the Integration Designer, where a `STARTED` workflow instance blocks its partition. If partitions accumulate unarchived, terminate the blocking instances — set process expiry, or turn on the stuck-instance termination sweep above.

For the full property tables and defaults, see [Partitioning & archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) (process-engine) and [Integration Designer setup → Workflow partitioning](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration).

#### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them as part of this upgrade. The bundled Qdrant subchart is renamed the same way, so any explicit references to its service host must be updated too.

> [!WARNING]
>
> Core platform services resolve AI Platform components by these new names. Upgrade the AI Platform chart and the core platform services to 5.9.2 together — running a 5.9.1 AI Platform chart against 5.9.2 core services (or the reverse) breaks AI features.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including expanded audit logging, copy-with-roles, and the app-manager organization-ID migration fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.1 → 5.9.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.2** is a maintenance release for the 5.9.x LTS. It pairs a broad bug-fix pass with a few targeted improvements:
>
> * **Expanded audit logging:** coverage for sharing, invitations, user and group management, and process-instance and UI-flow actions
> * **Copy with roles:** copying a resource now also copies its associated roles
> * **Self-hosted upgrade fixes:** smoother installation and upgrade from 5.1.x on self-hosted environments
> * **Key fixes:** active-policy override user list, project-version merge, reusable UI templates in nested containers, and audit-log user filtering&#x20;
> * Wide set of Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.9.2 brings bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions.\
> 👥 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, and backend bug fixes plus security patches.
>
> ***
>
> ### **Expanded audit logging**
>
> > [card] Broader audit coverage for access and lifecycle actions
> >
> > Audit logging now records a wider set of actions, including **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> > All Deployments
>
> ***
>
> ### **Copy with roles**
>
> > [card] Roles travel with copied resources
> >
> > Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Reusable UI templates:** fixed actions missing at runtime when a template is nested in multiple levels of containers.&#x20;
> > > > * **Use in reporting:** the reporting toggle is now available on UI flows and workflows, matching the existing process setting.
> > > > * **UI action keys:** keys to save for collection items and bundled custom-component inputs are now computed automatically, and mapped object keys for collections and custom components are available in runtime data.&#x20;
> > > > * **SQL data sources:** queries on SQL data sources can now be tested from the builds list, mirroring the existing NoSQL runtime test flow.&#x20;
> > > > * **Event handlers:** the Event Handlers section now appears higher in the component configuration panel.&#x20;
> > > > * **Audit logs:** filtering audit entries by user now works when the username differs from the email address.&#x20;
> > > > * **AI agents and data models:** AI Designer and AI Developer now use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it. &#x20;
> > >
> > > > [accordion] Renderer fixes
> > > >
> > > > * **Chat:** the floating chat position is now calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.&#x20;
> > > >
> > > > This release also includes stability fixes across the web, React, React Native, Android, and iOS renderers.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * **Active policy:** fixed the user list appearing empty on the override active-policy form.&#x20;
> > > > * **Project version merge:** fixed a 500 error that could occur during project-version merge.&#x20;
> > > > * **CMS enumerations:** cascading-enum value lookups now resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.&#x20;
> > > > * **Build export with media files:** exporting a build with media file content included now produces an archive that actually contains the binaries.&#x20;
> > > > * **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.&#x20;
> > > > * **Redis Cluster:** UI-template cache keys are now hash-tagged so related keys map to the same cluster slot, preventing cross-slot errors on Redis Cluster deployments.&#x20;
> > > > * **Workflow data:** Mongo partition archiving now batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine was fixed. See [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) for the partitioning and archiving settings.&#x20;
> > > > * **Data sync with private CA certificates:** the data-sync job now runs the same certificate-initialization step as the other platform services, so data-sync migrations that call HTTPS endpoints (such as Keycloak) no longer fail certificate validation in environments using an internal certificate authority.&#x20;
> > > > * **Self-hosted installation and upgrade:** fixed Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding on self-hosted environments. As part of this, the migration-created default end-user group is renamed from `User` to `Users Group`; check the upgrade warning under Additional information if you map IDP groups into FlowX.&#x20;
> > > > * **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.&#x20;
> > > > * **AI workflow nodes:** JSON schema fields now support `${}` placeholders.&#x20;
> > > > * **Multi-KB retrieval:** retrieval can span multiple knowledge bases in a workflow.&#x20;
> > > > * **AI structured output:** responses from AI nodes with a response schema are now validated against it, with automatic repair retries, and node logs include richer run diagnostics such as the failure reason and rejected output.&#x20;
> > > > * **Document Parser:** a new LiteParse engine parses PDFs and images fully locally without GPU or AI calls, and OCR language support expands to English, Romanian, Hungarian, and Bulgarian.&#x20;
> > > > * **Knowledge bases:** a Custom Agent node can now select multiple knowledge bases, each exposed to the agent as its own retrieval tool, replacing the parallel-nodes workaround.&#x20;
> > > > * **Chat file uploads:** end users can attach multiple files in a chat-driven app; uploads are indexed into a knowledge base scoped to the chat session so AI nodes answer grounded in that content.&#x20;
> > > > * **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.&#x20;
> > > >
> > > > This release also includes a broad set of additional fixes and stability improvements across Designer and backend services.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.2 is fully compatible with 5.9.1; standard deployment procedures apply. One migration renames a default end-user group, which needs attention only if group membership is mapped from Keycloak or an external IDP (see the warning below).
>
> > [!WARNING]
> >
> > **Default end-user group renamed from `User` to `Users Group`.** The group that the 5.1.x upgrade migration creates for users who held the `FLOWX_ROLE` realm role is renamed from `User` to `Users Group` when you upgrade to 5.9.2 or any later release. Runtime group matching is by exact name: if a Keycloak **Group Membership** mapper or an external IDP claim emits the old name `User` into `attributes.runtimeGroups`, those values no longer match any FlowX group and affected users **lose solution access on their next sign-in, with no error logged**. Update the mapper or source group name to `Users Group` as part of the upgrade. Groups your admins created themselves, including any you named `User`, are not renamed. See the [runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) setup for where this value is configured.
>
> > [!WARNING]
> >
> > **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration so it converts existing data correctly. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and actually converts your data. If you did not apply that workaround, no action is needed.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.1 → 5.9.2 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.2 are tracked in the [5.9.2 deployment guidelines](./deployment-guidelines-v5.9.2).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3

Component versions, configuration, and deployment notes for FlowX.AI 5.9.3 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.3 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.2 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.2 → 5.9.3**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.0 or 5.9.1 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.165.0 | 10.162.1 | 10.135.0 | 10.106.0 | 9.76.3 |
| **admin** | 10.144.0 | 10.141.1 | 10.116.0 | 10.93.0 | 9.76.3 |
| **designer** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **cms-core** | 10.105.0 | 10.102.3 | 10.86.0 | 10.67.0 | 9.47.3 |
| **scheduler-core** | 10.87.0 | 10.85.1 | 10.70.0 | 10.53.0 | 9.36.3 |
| **events-gateway** | 10.93.0 | 10.90.1 | 10.72.0 | 10.55.0 | 9.37.3 |
| **notification-plugin** | 10.103.0 | 10.100.2 | 10.83.0 | 10.64.0 | 9.40.3 |
| **document-plugin** | 10.116.0 | 10.113.2 | 10.94.0 | 10.75.0 | 9.45.3 |
| **task-management-plugin** | 10.105.0 | 10.102.1 | 10.84.0 | 10.66.0 | 9.44.4 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.85.0 | 10.83.1 | 10.69.0 | 10.52.0 | 9.33.3 |
| **audit-core** | 10.95.0 | 10.93.1 | 10.79.0 | 10.63.0 | 9.41.3 |
| **advancing-controller** | 10.91.0 | 10.89.1 | 10.73.0 | 10.55.0 | 9.36.3 |
| **integration-designer** | 10.192.0 | 10.189.2 | 10.162.0 | 10.128.0 | 9.60.3 |
| **application-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **runtime-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **data-sync** | 10.100.0 | 10.98.0 | 10.81.0 | 10.58.0 | 9.34.2 |
| **authorization-system** | 10.115.0 | 10.112.1 | 10.96.1 | 10.77.0 | 9.44.4 |
| **nosql-db-runner** | 10.94.0 | 10.92.1 | 10.75.0 | 10.56.0 | 9.32.3 |
| **email-gateway** | 10.93.0 | 10.91.1 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.90.0 | 10.88.1 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.62.0 | 10.60.1 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.25.0 | 10.23.1 | 10.8.0 | - | - |
| **license** | 10.80.0 | 10.78.1 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-native-sdk** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/core-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **react-saas** | 10.265.6 | 10.260.7 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.11 | 10.5.6 | 10.4.1 | 10.3.0 | 9.0.27 |
| **Android renderer** | 10.6.6 | 10.5.6 | 10.5.0 | 10.3.0 | 9.0.37 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](../v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.1 | 10.9.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.1 | 10.9.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.1 | 10.9.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.1 | 10.9.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.1 | 10.9.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.1 | 10.9.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.27.0 | 10.25.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.1 | 10.9.0 | - | - | - |
| **ai-assistant** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.1 | 10.9.0 | - | - | - |
| **flowx-docs** | 5.9.3 | 5.9.2 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.3 introduces no new Kafka topics over 5.9.2. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.3 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Events Gateway — Redis connection pool for blocking mode

The Events Gateway's blocking read path is rebuilt on a dedicated Redis connection pool, fixing a connection leak that could previously require periodic Events Gateway restarts under sustained load. The new settings ship with working defaults — no action is required on upgrade.

| Environment variable | Default | Change in 5.9.3 |
| - | - | - |
| `EVENTS_REDIS_POOL_ENABLED` | `true` | New — dedicated connection pool for blocking reads |
| `EVENTS_REDIS_POOL_MAXTOTAL` | `50` | New — maximum pooled connections |
| `EVENTS_REDIS_POOL_MAXIDLE` | `50` | New — maximum idle pooled connections |
| `EVENTS_REDIS_POOL_MINIDLE` | `5` | New — minimum idle pooled connections |
| `EVENTS_REDIS_POOL_MAXWAITMILLIS` | `5000` | New — wait time for a pooled connection before failing |
| `EVENTS_REDIS_SSE_BUFFERSIZE` | `256` | New — per-subscriber SSE backpressure buffer |
| `EVENTS_REDIS_BLOCKDURATIONSECONDS` | `1` | Default lowered from `5` — shortens the blocking-read reissue interval |

If you previously set `EVENTS_REDIS_BLOCKDURATIONSECONDS` explicitly, review whether the new default suits your setup. See the [Events Gateway setup guide](/5.9/setup-guides/events-gateway-setup#events) for the full configuration reference.

#### Integration Designer — workflow topic partitions

`FLOWX_WORKFLOW_TOPICPARTITIONS` (default `1`) sets the number of partitions for auto-created workflow Kafka topics (used with `FLOWX_WORKFLOW_CREATETOPICS`). Existing topics are not modified; the setting applies to newly created topics only.&#x20;

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# Agent typologies
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/agent-typologies

The recurring agent archetypes behind the FlowX.AI agent catalog, and the workflow nodes you combine to build each one.

The [FlowX.AI agent catalog](https://www.flowx.ai/ai-agents) publishes pre-designed AI agents for banking, insurance, and logistics. Behind the industry-specific names, every agent in the catalog is a variation of a small set of recurring **typologies** - reusable pipeline shapes you can build yourself with integration workflow and Agent Builder nodes.

This page describes each typology and how to implement it with the documented node palette.

> [!NOTE]
>
> The node decompositions shown in the catalog are illustrative. The implementations below use the nodes as they exist in the platform - see [AI node types](../agent-builder/node-types) for the full palette.

## The typologies at a glance

| Typology | What it does | Built with |
| - | - | - |
| [Document extractor and validator](#document-extractor-and-validator) | Extracts structured data from documents and gates on confidence | **Document Extraction** / **Extract Data from File** + **Condition** |
| [Grounded generator](#grounded-generator) | Drafts narratives, reports, and letters grounded in your content | **Context Retrieval** + **Custom Agent** |
| [Classifier and router](#classifier-and-router) | Classifies incoming text and routes it to the right handler | **Intent Classification Agent** or **Text Understanding** + **Condition** |
| [Voice intake](#voice-intake) | Transcribes audio and extracts meaning from it | **Speech to Text** + **Text Understanding** |
| [Predictive scorer](#predictive-scorer) | Enriches data, scores it, and gates on a threshold | **REST API Call** / **Database Operation** + **Condition** |
| [Privacy-guarded extractor](#privacy-guarded-extractor) | Document extraction with PII redaction in the pipeline | **Document Extraction** + **Personal Information Guard** |
| [Knowledge-validated extractor](#knowledge-validated-extractor) | Extraction checked against domain reference data | **Document Extraction** + **Context Retrieval** + **Custom Agent** |
| [Relationship reasoner](#relationship-reasoner) | Reasons over entities and their relationships | **Context Retrieval** + **Custom Agent** with response schema |
| [Human handoff](#human-handoff) | Escalates decisions above a threshold to a person | **Condition** + BPMN **User Task** |

***

## Document extractor and validator

The most common typology in the catalog: KYC pack validators, completeness checkers, cross-document consistency agents.

**When to use:** a document set arrives (identity documents, contracts, invoices, claims) and you need structured fields out of it, plus a decision on whether the result is good enough to proceed.

**How to build it:** a **Document Extraction** or **Extract Data from File** node extracts fields against a schema, then a **Condition** node gates on the extraction confidence - high-confidence results continue automatically, low-confidence results route to a review branch.

See [Fan-out extraction](./fan-out-extraction) for the multi-document-type variant, and [AI comparison and reconciliation](./ai-comparison-reconciliation) for cross-checking extracted data against a system of record.

## Grounded generator

The catalog's report writers: SAR drafts, case narratives, credit memos, customer letters.

**When to use:** the output is a document or narrative that must be grounded in verified content - policy texts, case data, templates - rather than generated freely.

**How to build it:** a **Context Retrieval** node pulls relevant chunks from a Knowledge Base, then a **Custom Agent** node generates the draft from those chunks. Constrain the output with a **Response Schema** so downstream nodes receive predictable structure, and turn on the **Personal Information Guard** where the input may contain PII.

See [Knowledge base RAG](./knowledge-base-rag) for the retrieval setup.

## Classifier and router

Complaint root-cause identifiers, alert triage screeners, exception handlers.

**When to use:** free-form input (a message, an alert, an email) must be understood and dispatched to the right specialized handler.

**How to build it:** an **Intent Classification Agent** node classifies the input into up to 10 intents and routes each to its own branch in a single node - including a fallback branch when nothing matches. For classification against a custom label set with custom gating, use a **Text Understanding** node followed by a **Condition** node.

See [Intent classification and routing](./intent-classification-routing).

## Voice intake

Call transcribers, first-notice-of-loss agents, voice-driven notification generators.

**When to use:** the input is audio - customer calls, voice messages, dictated notes.

**How to build it:** a **Speech to Text** node transcribes the audio, then a **Text Understanding** node extracts the entities, topics, or sentiment you need from the transcript.

See [Speech to Text](../agent-builder/speech-to-text).

## Predictive scorer

Risk analyzers, churn predictors, KPI forecasters, failure-prediction agents.

**When to use:** a numeric or categorical prediction drives the decision - a score, a probability, a forecast - and you gate the flow on a threshold.

**How to build it:** FlowX orchestrates the pipeline around your scoring model rather than replacing it. Enrich the input with **REST API Call** or **Database Operation** nodes, call your model (or a third-party scoring service) with a **REST API Call** node, then gate with a **Condition** node on the returned score. Deterministic scoring logic can also run directly in a **Script** node.

See [Hybrid AI and business rules](./hybrid-ai-rules) for combining AI outputs with auditable deterministic logic.

## Privacy-guarded extractor

Identity and KYC extraction agents that must not leak personal data downstream.

**When to use:** documents contain PII and the extracted output crosses a trust boundary - external models, logs, or downstream systems that shouldn't see raw identifiers.

**How to build it:** the document-extractor pipeline above, with the **Personal Information Guard** enabled on the AI nodes' input and/or output to redact personal information.

See [Personal Information Guard](../personal-information-guard).

## Knowledge-validated extractor

Board-authority validators, contract-term checkers, coverage validators.

**When to use:** extracted data must be checked against domain reference content - policy rules, product terms, jurisdiction requirements - not just against a schema.

**How to build it:** extract with a **Document Extraction** node, retrieve the applicable reference content with a **Context Retrieval** node, then have a **Custom Agent** node compare the two and return a structured verdict with reasons via its **Response Schema**.

## Relationship reasoner

Ownership-structure mappers, treaty cross-referencers, entity-network agents.

**When to use:** the question is about how entities relate - who ultimately owns what, which contracts reference each other - rather than about a single document.

**How to build it:** there is no dedicated graph node; model the reference relationships in a Knowledge Base, retrieve the relevant slice with **Context Retrieval**, and let a **Custom Agent** node reason over it, returning the reconstructed structure through a **Response Schema**. For relationship data held in your own systems, enrich with **Database Operation** or **REST API Call** nodes first.

## Human handoff

Escalation wrappers that route edge cases to a person.

**When to use:** any of the typologies above produces a low-confidence or high-stakes result that a human must approve.

**How to build it:** a **Condition** node detects the escalation case, and the surrounding BPMN process presents it to a person as a **User Task** - the agent workflow and the human step share the same process context.

See [Integrating agents in BPMN processes](../using-agents/bpmn-integration).

***

## Combining typologies

Catalog agents rarely ship alone - each lists companion agents, and the same is true when you build your own. Typical combinations:

| Scenario | Typology combination |
| - | - |
| Case investigation | Classifier and router → Document extractor → Grounded generator (the narrative) |
| Onboarding validation | Document extractor → Knowledge-validated extractor → Human handoff |
| Voice-driven claims | Voice intake → Document extractor → Predictive scorer |

***

## Related resources

> [card] [AI node types](../agent-builder/node-types)
>
> The full AI node palette these typologies are built from

> [card] [AI patterns](./overview)
>
> Implementation-level patterns with prompts and schemas

> [card] [Agent catalog](https://www.flowx.ai/ai-agents)
>
> The full industry catalogs on flowx.ai

> [card] [Tutorials](../tutorials/overview)
>
> End-to-end builds that use these typologies


# AI patterns
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/overview

Reusable architectural patterns for building AI-powered apps on FlowX.AI.

Patterns are proven solutions to common challenges when building AI apps on FlowX. Each pattern is extracted from production implementations and can be combined to build complex apps.

## Available patterns

> [card] [Agent typologies](./agent-typologies)
>
> The nine recurring agent archetypes behind the FlowX.AI agent catalog, mapped to the nodes that implement them. Start here to pick a shape.

> [card] [Intent classification and routing](./intent-classification-routing)
>
> Use a TEXT\_UNDERSTANDING node to classify user input and route to specialized handlers. The foundation of any conversational AI app.

> [card] [Knowledge base RAG](./knowledge-base-rag)
>
> Ground AI responses in your documents using retrieval-augmented generation with Qdrant vector search and the CUSTOM\_AGENT node.

> [card] [Fan-out extraction](./fan-out-extraction)
>
> Classify documents by type, then route each to a specialized TEXT\_EXTRACTION node with tailored prompts and schemas. Scale to dozens of document types.

> [card] [AI comparison and reconciliation](./ai-comparison-reconciliation)
>
> Compare AI-extracted document data against system-of-record values and generate structured exception reports with match rates and confidence scores.

> [card] [Hybrid AI + business rules](./hybrid-ai-rules)
>
> Combine AI extraction and understanding with deterministic business logic (formulas, eligibility checks, scoring) for auditable decision-making.

> [card] [Session state management](./session-state-management)
>
> Manage conversation history and session state across multi-turn interactions using FlowX Database workflows.

***

## How to use patterns

Each pattern page includes:

* **When to use** — the problem it solves and when to reach for it
* **Architecture** — how the workflow nodes connect
* **Implementation** — key configuration: prompts, schemas, fork conditions
* **Real-world example** — where this pattern appears in the tutorials
* **Variations** — common adaptations

Patterns are building blocks. A typical AI app combines 2-4 patterns:

| App type | Common pattern combination |
| - | - |
| **Conversational advisor** | Intent routing + Knowledge base RAG + Session state + Hybrid AI rules |
| **Document processor** | Fan-out extraction + AI comparison + Hybrid AI rules |
| **Email automation** | Fan-out extraction + AI comparison + Session state |

***

## Multi-agent orchestration

Combining patterns produces **multi-agent apps**: several specialized agents coordinated inside one workflow, each with its own prompt, schema, and model.

* **Router and specialists**: an [intent classification](./intent-classification-routing) agent reads the input and dispatches to specialized handler agents — the foundation of conversational apps.
* **Parallel specialists**: [fan-out extraction](./fan-out-extraction) classifies documents by type and routes each to a dedicated extraction agent with a tailored prompt and schema, scaling to dozens of document types processed in parallel.
* **Agents plus deterministic logic**: [hybrid AI + business rules](./hybrid-ai-rules) places auditable business logic and approval gates between agent steps, so multi-agent output stays governed.

Each agent in the composition can use a [different model](../ai-providers), and the whole orchestration is testable with [evaluations](../evaluations) per AI node.

***

## Pattern origins

These patterns are extracted from two production-grade FlowX apps:

* **Mortgage advisor** — a chatbot that evaluates loan eligibility across 7 banks using conversational AI, document extraction, and financial calculations
* **Logistics document processor** — an email-triggered pipeline that processes 17 document types from carrier emails, reconciles them against a TMS, and surfaces exceptions for review

See the [Tutorials](../tutorials/overview) for full implementations.

***

## Related resources

> [card] [Tutorials](../tutorials/overview)
>
> End-to-end implementations using these patterns

> [card] [Node types](../agent-builder/node-types)
>
> AI node type reference

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Multi-turn chat with session memory

> [card] [Using agents](../using-agents/overview)
>
> Integration and deployment options


# Customer onboarding with KYC
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/customer-onboarding

Build a multi-step customer onboarding process with identity verification, document generation, manual review routing, and email notifications.

Tested · August 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** The process ran end to end through the manual review path: the forms, the KYC verification workflow, and the routing to the review task. The timer escalation and rejection steps were built and validated in the Designer.

In this tutorial, you build a **customer onboarding process** — a BPMN-driven app that collects personal data through multi-step forms, verifies the customer's identity via an external KYC API, generates a welcome letter, and routes failed verifications to a manual review queue.

**What you will build:**

* A **multi-step form** that collects personal details, address, employment, and document uploads
* A **KYC verification** integration that calls an external REST API via an integration workflow
* An **exclusive gateway** that routes the process based on verification results
* A **document generation** step that produces a personalized welcome letter
* A **manual review task** assigned to compliance officers when KYC fails
* An **email notification** sent upon successful onboarding
* A **timer boundary event** for SLA tracking on the review task

**Node types used:** User Task, Send Message Task, Receive Message Task, Exclusive Gateway, Timer Boundary Event

**Patterns demonstrated:** Multi-step form collection, REST API integration via workflows, conditional branching, document generation, task assignment, notification sending

***

## Architecture overview

The process follows a **collect-verify-decide** pattern. Customer data is gathered through a series of user task nodes, sent to a KYC service for verification, and then routed based on the result.

```mermaid theme={"dark"}
flowchart TD
    A(("Start")) --> B["User Task:<br/>Personal Information"]
    B --> C["User Task:<br/>Address Details"]
    C --> D["User Task:<br/>Employment & Income"]
    D --> E["User Task:<br/>Document Upload"]
    E --> F["Send Message Task:<br/>Start KYC Check"]
    F -. "Workflow:<br/>kycVerification" .-> F
    F --> G["Receive Message Task:<br/>KYC Result"]
    G --> H{"Exclusive Gateway:<br/>KYC Decision"}
    H -- "PASSED" --> I["Generate Welcome Letter<br/>(Send/Receive Message)"]
    H -- "FAILED / REVIEW" --> J["User Task: Manual Review<br/>⏱ 48h Timer Boundary"]
    J -- "APPROVED" --> I
    J -- "REJECTED" --> K(("End<br/>(Rejected)"))
    I --> L["Send Email Notification<br/>(Send/Receive Message)"]
    L --> M(("End<br/>(Success)"))
```

The main process orchestrates four form steps, delegates KYC verification to an integration workflow, and uses an exclusive gateway to branch into success or manual review paths.

***

## Prerequisites

Before starting, make sure you have:

* Access to a FlowX Designer workspace
* The **Documents Plugin** deployed and configured (for document generation)
* The **Notifications Plugin** deployed and configured (for email sending)
* A document template named `welcomeLetter` created in **Document Templates** (HTML template with placeholders for customer name and date)
* Familiarity with creating processes, user tasks, and actions in FlowX

> [!WARNING]
>
> HTML template generation is turned **off** by default on the Documents Plugin. Turn it on for the document-plugin deployment before testing [Step 6](#step-6-build-the-success-path) — otherwise the welcome letter is never produced and the process stalls at `receiveWelcomeLetter`.
>
> Either variable sets it: `HTML_TEMPLATES_ENABLED` (referenced directly in the plugin configuration) or `FLOWX_HTML_TEMPLATES_ENABLED` (the property name `flowx.html.templates.enabled` in environment-variable form).
>
> **Default:** `false`

> [!TIP]
>
> If you do not have a real KYC service available, you can simulate one using a mock REST API endpoint (for example, a simple service that returns `PASSED` or `FAILED` based on predefined rules). The integration workflow calls this endpoint the same way it would call a production KYC provider.

***

## Data model

Define the following keys in your process data model. All keys use camelCase and are nested under logical groups.

| Key path | Type | Description |
| - | - | - |
| `customer.firstName` | String | Customer first name |
| `customer.lastName` | String | Customer last name |
| `customer.dateOfBirth` | String | Date of birth (ISO format) |
| `customer.nationalId` | String | National ID or passport number |
| `customer.email` | String | Email address |
| `customer.phone` | String | Phone number |
| `address.street` | String | Street address |
| `address.city` | String | City |
| `address.postalCode` | String | Postal code |
| `address.country` | String | Country (ISO 3166 code) |
| `employment.status` | String | `EMPLOYED`, `SELF_EMPLOYED`, `UNEMPLOYED`, `RETIRED` |
| `employment.employer` | String | Employer name (if employed) |
| `employment.monthlyIncome` | Number | Monthly income in local currency |
| `employment.startDate` | String | Employment start date |
| `documents.identityDoc` | Object | Uploaded identity document reference |
| `documents.proofOfAddress` | Object | Uploaded proof of address reference |
| `kycResult` | Object | KYC verification response from external API |
| `kycResult.status` | String | `PASSED`, `FAILED`, or `REVIEW` |
| `kycResult.score` | Number | Risk score (0-100) |
| `kycResult.reasons` | Array | List of reasons if not passed |
| `kycResult.verificationId` | String | Verification reference returned by the KYC provider |
| `escalation.managerEmail` | String | Manager email notified when the review SLA is breached |
| `onboarding.currentDate` | String | Current date, set by a business rule before document generation |
| `reviewDecision` | String | Manual review outcome: `APPROVED` or `REJECTED` |
| `reviewNotes` | String | Notes from the compliance reviewer |
| `generatedDocs.welcomeLetter` | Object | Generated welcome letter document reference |
| `notificationResult` | Object | Email notification delivery result |

***

## Step 1: Create the process definition

**1. Create a new process**

In FlowX Designer, navigate to your project and create a new process definition named `customerOnboarding`.

Set the platform to **Web Only** (or **Omnichannel** if you plan to support mobile).

**2. Add swimlanes**

Create two swimlanes:

* **Customer** — for the user-facing form steps
* **BackOffice** — for the manual review task (assigned to a compliance role)

This ensures the review task is routed to the right team while the customer interacts with the form steps.

> [!NOTE]
>
> For details on configuring swimlanes and role-based access, see the [Swimlanes](../../docs/platform-deep-dive/user-roles-management/swimlanes) documentation.

***

## Step 2: Build the data collection forms

Create four **User Task** nodes in the **Customer** swimlane, connected in sequence. Each node represents one step of the onboarding form.

### User Task 1: Personal information

**Node name:** `personalInfo`

Open the UI Designer and add a **Card** with a **Form** containing these fields:

| Component | Label | Key | Validation |
| - | - | - | - |
| Input | First name | `customer.firstName` | Required |
| Input | Last name | `customer.lastName` | Required |
| Datepicker | Date of birth | `customer.dateOfBirth` | Required, must be 18+ |
| Input | National ID | `customer.nationalId` | Required |
| Input | Email | `customer.email` | Required, email format |
| Input | Phone | `customer.phone` | Required |

Add a **Button** labeled **Next** with an action of type **Save Data** to persist the form values.

### User Task 2: Address details

**Node name:** `addressInfo`

| Component | Label | Key | Validation |
| - | - | - | - |
| Input | Street address | `address.street` | Required |
| Input | City | `address.city` | Required |
| Input | Postal code | `address.postalCode` | Required |
| Select | Country | `address.country` | Required (populate from enumeration) |

> [!TIP]
>
> Use an [enumeration](../../docs/platform-deep-dive/core-extensions/content-management/enumerations) for the country dropdown. Create an enumeration named `countries` with ISO 3166 country codes and labels.

Add **Back** and **Next** buttons. Set `canGoBack: true` on this node so the customer can return to the previous step.

### User Task 3: Employment and income

**Node name:** `employmentInfo`

| Component | Label | Key | Validation |
| - | - | - | - |
| Radio | Employment status | `employment.status` | Required |
| Input | Employer name | `employment.employer` | Required if EMPLOYED |
| Input | Monthly income | `employment.monthlyIncome` | Required, numeric |
| Datepicker | Start date | `employment.startDate` | Required if EMPLOYED |

> [!NOTE]
>
> Use a [conditional expression](../../docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field) on the Employer and Start Date fields to show them only when `employment.status` is `EMPLOYED` or `SELF_EMPLOYED`.

### User Task 4: Document upload

**Node name:** `documentUpload`

| Component | Label | Key |
| - | - | - |
| File Upload | Identity document (passport or ID card) | `documents.identityDoc` |
| File Upload | Proof of address (utility bill or bank statement) | `documents.proofOfAddress` |

Add a **Submit** button that triggers the process to move to the KYC verification step.

> [!WARNING]
>
> Uploaded files are stored via the Documents Plugin. Make sure the plugin is configured with an S3-compatible storage backend before testing this step.

***

## Step 3: Set up the KYC verification integration

The KYC check is handled by an integration workflow that calls an external REST API. This keeps the BPMN process clean and the integration logic reusable.

### Create the data source

**1. Add a RESTful System data source**

Navigate to **Integrations** > **Data Sources** and create a new data source:

* **Type:** RESTful System
* **Name:** KYC Provider
* **Code:** `kycProvider`
* **Base URL:** `https://api.{your-kyc-provider}.com/v1`
* **Authorization:** Bearer Token (configure the token value using a [Configuration Parameter Override](../../docs/projects/runtime/configuration-parameters-overrides) so it differs per environment)

**2. Define the verification endpoint**

Under the data source, add an endpoint:

* **Method:** POST
* **Path:** `/verify`
* **Body type:** JSON
* **Request body example:**

```json theme={"dark"}
{
  "firstName": "Jane",
  "lastName": "Smith",
  "dateOfBirth": "1990-05-15",
  "nationalId": "AB1234567",
  "country": "GB"
}
```

* **Response example:**

```json theme={"dark"}
{
  "status": "PASSED",
  "score": 92,
  "reasons": [],
  "verificationId": "kyc-20260311-001"
}
```

### Create the integration workflow

**1. Create the workflow**

Navigate to **Integrations** > **Workflows** and create a new workflow named `kycVerification`.

**2. Add a REST API Call node**

Add a **REST API Call** node connected to the Start node. Configure it to use the `kycProvider` data source and the `/verify` endpoint.

Map the input variables to the request body:

```json theme={"dark"}
{
  "firstName": "${customer.firstName}",
  "lastName": "${customer.lastName}",
  "dateOfBirth": "${customer.dateOfBirth}",
  "nationalId": "${customer.nationalId}",
  "country": "${address.country}"
}
```

**3. Add a Script node to unwrap the response**

A REST node does not put the HTTP body directly on its response key. It wraps it, so `kycResponse` looks like this:

```json theme={"dark"}
{
  "data": { "status": "PASSED", "score": 92, "reasons": [], "verificationId": "kyc-20260311-001" },
  "hasError": false,
  "metadata": { "statusCode": 200, "headers": { } }
}
```

Add a **Script** node after the REST API Call, routed on its **SUCCESS** output, to lift the provider's fields to the top level:

```javascript theme={"dark"}
var resp = input.kycResponse || {};
var body = resp.data || {};

output.status = body.status;
output.score = body.score;
output.reasons = body.reasons || [];
output.verificationId = body.verificationId;
```

**4. Add an End Flow node**

Add an **End Flow** node after the Script node and give it an **OUTPUT data slice** declaring `status`, `score`, `reasons`, and `verificationId`.

The output slice is the workflow's contract: it returns exactly the fields you declare, and drops everything else that accumulated during the run. That is what makes `kycResult.status` readable in [Step 4](#step-4-trigger-kyc-from-the-bpmn-process).

> [!WARNING]
>
> Do not return the raw response with an End Flow payload of `{"output": ${kycResponse}}`. That hands the BPMN process the entire HTTP envelope — headers and cookies included — and pushes the values you want down to `kycResult.output.data.status` instead of `kycResult.status`.

> [!TIP]
>
> Wrap placeholders in quotes in the REST request body: write `"${firstName}"`, with the quotes. An unquoted `${firstName}` is substituted as a bare token rather than a JSON string, producing an invalid body like `{"firstName": Jane}`. Many endpoints still answer `200` to that while silently parsing nothing, so every node reports success and the workflow returns empty values.

> [!NOTE]
>
> For a detailed guide on building integration workflows, see the [Integration Designer](../../docs/platform-deep-dive/integrations/integration-designer) documentation.

***

## Step 4: Trigger KYC from the BPMN process

Back in the `customerOnboarding` process, add a **Send Message Task** and a **Receive Message Task** after the `documentUpload` user task.

### Send Message Task: Start KYC check

**Node name:** `sendKycRequest`

Add an action:

* **Action type:** Start Integration Workflow
* **Workflow:** `kycVerification`
* **Input mapping:**

```json theme={"dark"}
{
  "customer": "${customer}",
  "address": "${address}"
}
```

* **Trigger:** Automatic
* **Mandatory:** Yes

### Receive Message Task: Receive KYC result

**Node name:** `receiveKycResult`

* **Key Name:** `kycResult`

The workflow output is captured at this key. Subsequent nodes can access `kycResult.status`, `kycResult.score`, and `kycResult.reasons`.

> [!NOTE]
>
> The process waits at the Receive Message Task until the integration workflow completes and returns its output. For details on this pattern, see [Start Integration Workflow Action](../../docs/building-blocks/actions/start-integration-workflow).

***

## Step 5: Add the KYC decision gateway

Add an **Exclusive Gateway** node after the `receiveKycResult` node.

**Node name:** `kycDecision`

Configure two outgoing branches:

| Branch | Condition (JavaScript) | Target |
| - | - | - |
| Passed | `kycResult.status === "PASSED"` | Go to document generation (success path) |
| Failed / Review | Default (else) | Go to manual review task |

> [!TIP]
>
> Using the default branch for the failure path ensures that any unexpected status value (not just `FAILED`) is routed to human review rather than slipping through.

For details on configuring exclusive gateways, see the [Exclusive Gateway Node](../../docs/building-blocks/node/exclusive-gateway-node) documentation.

***

## Step 6: Build the success path

The success path generates a welcome letter and sends a confirmation email.

### Generate the welcome letter

Add a **Send Message Task** and **Receive Message Task** pair for document generation.

#### Send Message Task: Generate welcome letter

**Node name:** `sendGenerateWelcomeLetter`

Add a **Kafka Send Action** with:

* **Topic:** `ai.flowx.plugin.document.trigger.generate.html.v1`
* **Message body:**

```json theme={"dark"}
{
  "documentList": [
    {
      "customId": "welcomeLetter",
      "templateName": "welcomeLetter",
      "language": "en",
      "data": {
        "customerName": "${customer.firstName} ${customer.lastName}",
        "currentDate": "${onboarding.currentDate}",
        "accountReference": "${kycResult.verificationId}"
      },
      "includeBarcode": false
    }
  ]
}
```

> [!NOTE]
>
> The `templateName` must match a document template you created in **Document Templates**. Use the WYSIWYG editor to design the welcome letter with placeholders like `{{customerName}}` and `{{currentDate}}`. For details, see [Generating documents from templates](../../docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates).

> [!WARNING]
>
> `${...}` placeholders in message payloads reference existing process data only — the engine does not evaluate functions or expressions inside them. Set `onboarding.currentDate` with a business rule (for example, a **Save Data** action running a short script that writes today's date) on a node before `sendGenerateWelcomeLetter`.

#### Receive Message Task: Receive letter result

**Node name:** `receiveWelcomeLetter`

* **Data stream Topic Name** (in **Integration Output**): use the value from `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT`, configured on the **document-plugin** deployment (default: `ai.flowx.engine.receive.plugin.document.generate.html.results.v1`)
* **Key Name:** `generatedDocs.welcomeLetter`

### Send the confirmation email

Add another **Send Message Task** and **Receive Message Task** pair for notification.

#### Send Message Task: Send email

**Node name:** `sendEmailNotification`

Add a **Kafka Send Action** with:

* **Topic:** `ai.flowx.plugin.notification.trigger.send.notification.v1`
* **Message body:**

```json theme={"dark"}
{
  "templateName": "onboardingComplete",
  "language": "en",
  "receivers": [
    "${customer.email}"
  ],
  "subject": "Welcome - Your account is ready",
  "data": {
    "customerName": "${customer.firstName} ${customer.lastName}"
  }
}
```

> [!NOTE]
>
> Create the `onboardingComplete` notification template in the Notifications Plugin before testing. For configuration details, see the [Notifications Plugin](../../docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/notifications-plugin-overview) documentation.

#### Receive Message Task: Receive email confirmation

**Node name:** `receiveEmailConfirmation`

* **Data stream topic:** use the value from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT`, configured on the **notification-plugin** deployment (default: `ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1`)
* **Key Name:** `notificationResult`

After this node, add an **End Event** node to close the success path.

***

## Step 7: Build the manual review path

When KYC fails or returns a `REVIEW` status, the process routes to a human reviewer.

### User Task: Manual review

**Node name:** `manualReview`

Place this node in the **BackOffice** swimlane.

Open the UI Designer and create a review interface:

| Component | Label | Key | Notes |
| - | - | - | - |
| Text | Customer name | `customer.firstName` + `customer.lastName` | Read-only display |
| Text | National ID | `customer.nationalId` | Read-only display |
| Text | KYC status | `kycResult.status` | Read-only display |
| Text | Risk score | `kycResult.score` | Read-only display |
| Text | Reasons | `kycResult.reasons` | Read-only list |
| Select | Decision | `reviewDecision` | Options: `APPROVED`, `REJECTED` |
| Input (textarea) | Notes | `reviewNotes` | Required |

Add two buttons:

* **Approve** — sets `reviewDecision` to `APPROVED` and advances
* **Reject** — sets `reviewDecision` to `REJECTED` and advances

> [!TIP]
>
> Enable **Update Task Management** on this node so the task appears in the Task Manager inbox for compliance officers. Assign the node to a swimlane with the appropriate role (for example, `COMPLIANCE_REVIEWER`).

### Timer boundary event: SLA escalation

Attach a **Timer Boundary Event** to the `manualReview` node to enforce a 48-hour SLA.

* **Timer type:** Duration
* **Duration:** `PT48H` (ISO 8601 format — 48 hours)
* **Interrupting:** No (non-interrupting — the review can still complete after escalation)

Connect the timer to a **Send Message Task** that sends an escalation notification:

```json theme={"dark"}
{
  "templateName": "reviewEscalation",
  "language": "en",
  "receivers": [
    "${escalation.managerEmail}"
  ],
  "subject": "Overdue: KYC review pending for 48 hours",
  "data": {
    "customerName": "${customer.firstName} ${customer.lastName}",
    "hoursOverdue": "48"
  }
}
```

> [!NOTE]
>
> For details on timer configuration, see [Timer Boundary Event](../../docs/building-blocks/node/timer-events/timer-boundary-event) and [Timer Expressions](../../docs/building-blocks/node/timer-events/timer-expressions).

### Review decision gateway

Add a second **Exclusive Gateway** after the `manualReview` node.

**Node name:** `reviewDecisionGateway`

| Branch | Condition (JavaScript) | Target |
| - | - | - |
| Approved | `reviewDecision === "APPROVED"` | Go to document generation (same success path) |
| Rejected | Default (else) | Go to rejection End Event |

For the **Approved** branch, connect to the same document generation and email notification nodes used in the success path (or duplicate them if your process layout requires separate paths).

For the **Rejected** branch, add an **End Event** node labeled `endRejected`.

***

## Step 8: Add a business rule for risk scoring (optional)

You can add a **Business Rule Action** on the `receiveKycResult` node to enrich the KYC response with custom logic before the gateway evaluates it.

**Action type:** Business Rule
**Language:** JavaScript

```javascript theme={"dark"}
// Normalize the KYC result for downstream processing
var status = input.kycResult.status;
var score = input.kycResult.score;

// Override status based on custom score thresholds
if (status === "REVIEW" && score >= 75) {
  output.put("kycResult", { "status": "PASSED" });
} else if (status === "REVIEW" && score < 50) {
  output.put("kycResult", { "status": "FAILED" });
}

// Flag high-risk countries for additional review
var highRiskCountries = ["XX", "YY", "ZZ"];
if (highRiskCountries.indexOf(input.address.country) !== -1 && status === "PASSED") {
  output.put("kycResult", {
    "status": "REVIEW",
    "reasons": ["High-risk jurisdiction flagged for manual review"]
  });
}
```

> [!WARNING]
>
> Always `put` an object on the top-level key, as above. A dotted key like `output.put("kycResult.status", ...)` creates a flat key literally named `kycResult.status` instead of updating the nested value, so gateway conditions and `${kycResult.status}` placeholders would silently keep reading the old value. Objects put this way are deep-merged into the existing key.

> [!NOTE]
>
> Business rules execute synchronously within the process engine. Use them for lightweight data transformations and decision logic. For details, see [Business Rule Action](../../docs/building-blocks/actions/business-rule-action/business-rule-action).

***

## Step 9: Configure stages for Task Manager

Define [stages](../../docs/platform-deep-dive/core-extensions/task-management/using-stages) to track progress in the Task Manager:

| Stage name | Assigned to nodes |
| - | - |
| Data Collection | `personalInfo`, `addressInfo`, `employmentInfo`, `documentUpload` |
| KYC Verification | `sendKycRequest`, `receiveKycResult` |
| Manual Review | `manualReview` |
| Completion | `sendGenerateWelcomeLetter`, `sendEmailNotification` |

Enable **Update Task Management** on the first user task node (`personalInfo`) and the manual review node (`manualReview`) so that process instances appear in the Task Manager with their current stage.

***

## Testing

**1. Test the happy path (KYC passes)**

Start a new process instance and fill in all four form steps with valid data. Use a national ID that your mock KYC service recognizes as valid.

Verify:

* The KYC integration workflow completes and returns `status: PASSED`
* The welcome letter is generated (check the document storage)
* The confirmation email is sent to the customer email address
* The process ends at the success End Event

```json theme={"dark"}
{
  "customer": {
    "firstName": "Jane",
    "lastName": "Smith",
    "dateOfBirth": "1990-05-15",
    "nationalId": "AB1234567",
    "email": "jane.smith@example.com",
    "phone": "+44 7700 900000"
  },
  "address": {
    "street": "42 Oak Lane",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "employment": {
    "status": "EMPLOYED",
    "employer": "Acme Corp",
    "monthlyIncome": 4500,
    "startDate": "2020-03-01"
  }
}
```

**2. Test the manual review path (KYC fails)**

Start a new instance with data that triggers a `FAILED` or `REVIEW` KYC status.

Verify:

* The process routes to the `manualReview` user task
* The task appears in the Task Manager for the BackOffice swimlane
* Approving the review generates the welcome letter and sends the email
* Rejecting the review ends the process at the rejection End Event

**3. Test SLA escalation**

Start a manual review scenario and let the 48-hour timer expire (for testing, temporarily change the duration to `PT1M` — one minute).

Verify:

* The escalation email is sent to the configured manager address
* The review task remains active (non-interrupting timer)
* The reviewer can still approve or reject after escalation

**4. Test form navigation**

Verify that the **Back** button on each form step returns the user to the previous step without losing entered data.

Verify that required field validations prevent advancing to the next step when fields are empty.

***

## What you learned

In this tutorial, you built a complete customer onboarding process that demonstrates several core FlowX capabilities:

* **Multi-step forms** — using sequential User Task nodes with form components to collect structured data across multiple screens
* **Integration workflows** — delegating external API calls (KYC verification) to reusable integration workflows triggered via the Start Integration Workflow action
* **Conditional routing** — using Exclusive Gateway nodes with JavaScript conditions to branch process logic based on data values
* **Document generation** — using the Documents Plugin with Kafka Send/Receive Message Tasks to generate documents from HTML templates
* **Notifications** — using the Notifications Plugin to send email confirmations
* **Task assignment** — using swimlanes and the Task Management plugin to route manual review tasks to specific roles
* **SLA tracking** — using Timer Boundary Events to enforce and escalate overdue tasks
* **Business rules** — using JavaScript business rules to enrich and transform data within the process

***

## Next steps

> [card] [Process definitions](../../docs/building-blocks/process/process-definition)
>
> Deep-dive into process configuration options

> [card] [Integration Designer](../../docs/platform-deep-dive/integrations/integration-designer)
>
> Build more integration workflows for external systems

> [card] [Task Management](../../docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> Configure task routing and assignment rules

> [card] [Mortgage advisor chatbot](./mortgage-advisor)
>
> Build a conversational AI app as a companion to this BPMN tutorial


# Document processing pipeline
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/document-processing

Build an AI document verification pipeline where a Custom Agent classifies each uploaded document, calls the matching extraction workflow, and reconciles the result against application data.

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Tested · September 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** Each stage was run on its own: the tool workflows, the verification agent and its tool calls, the summary workflow, and the process data mappings and business rule.

In this tutorial, you build a **document processing pipeline** that verifies customer onboarding documents against application data. The customer uploads files (ID card, proof of address, salary slip). For each file, a **Custom Agent** reads the document, decides what it is, calls the matching extraction workflow as a tool, and compares the extracted fields to what the applicant declared. Documents with discrepancies go to a human reviewer.

**What you will build:**

* Four small **tool workflows** that read a document's text and extract structured fields per document type
* A **verification agent** that classifies each document, picks the right extraction tool, and reconciles the result
* A **summary generation** workflow that writes the verification report
* A **BPMN process** with a file upload UI, **business rules** that aggregate the per-document verdicts, and a **human review** task

**AI node types used:** Custom Agent, Extract Data from File, Document Extraction, Text Generation

**Patterns demonstrated:** [Fan-out extraction](../patterns/fan-out-extraction), [AI comparison and reconciliation](../patterns/ai-comparison-reconciliation)

> [!NOTE]
>
> The verification agent needs workflow tools. If your deployment doesn't have them yet, see [Explicit pipeline alternative](#explicit-pipeline-alternative) for the same verification built from explicit classification, routing, and comparison steps.

***

## Architecture overview

The pipeline processes documents in four phases: upload, verify each document, aggregate, and review.

```mermaid theme={"dark"}
flowchart TD
    A["User uploads documents"] --> B["User Task<br/>(file upload UI)"]
    B --> C["Send / Receive Message Task<br/>(once per document)"]
    C -. "Workflow: verifyDocuments<br/>(Custom Agent + tool workflows)" .-> C
    C --> E["Business Rule<br/>(aggregate verdicts)"]
    E --> F{"Exclusive Gateway"}
    F -- "All valid" --> G["Auto-approve"]
    F -- "Exceptions found" --> H["Human Review Task"]
    G --> I["Send / Receive Message Task"]
    H --> I
    I -. "Workflow: generateSummary" .-> I
    I --> J(("End Event"))

    style A fill:#f0f4ff,stroke:#4a6fa5
    style J fill:#f0f4ff,stroke:#4a6fa5
```

**Workflow breakdown:**

| Workflow | AI nodes | Purpose |
| - | - | - |
| `readDocumentText` | Extract Data from File | Tool: return the raw text of a document so the agent can classify it |
| `extractIdCard`, `extractProofOfAddress`, `extractSalarySlip` | Document Extraction | Tools: extract structured fields for one document type |
| `verifyDocuments` | Custom Agent | Classify the document, call one extraction tool, reconcile against the declared data |
| `generateSummary` | Text Generation | Produce a human-readable verification report |

***

## Prerequisites

Before starting, make sure you have:

* Access to a FlowX Designer workspace with AI Platform enabled
* An AI model available to your project. The AI nodes use the project default unless you override the model on the node.
* A project with the Documents Plugin configured (for file uploads)
* Sample documents to test with: an ID card, a proof of address (for example, a utility bill), and a salary slip, as PDF files
* Familiarity with creating processes, workflows, and UI flows in FlowX, including workflow [input and output parameters](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)

***

## Data model

Define the following keys in your process data model. They hold the application data submitted by the customer, the agent's verdict per document, and the results of the later steps.

```json theme={"dark"}
{
  "applicant": {
    "firstName": "STRING",
    "lastName": "STRING",
    "dateOfBirth": "STRING",
    "address": {
      "street": "STRING",
      "city": "STRING",
      "postalCode": "STRING",
      "country": "STRING"
    },
    "monthlyIncome": "FLOAT",
    "employer": "STRING"
  },
  "documents": {
    "uploadedFiles": [
      {
        "fileId": "STRING",
        "filePath": "STRING",
        "fileName": "STRING"
      }
    ]
  },
  "currentFile": {
    "fileId": "STRING",
    "filePath": "STRING",
    "fileName": "STRING"
  },
  "verification": {
    "doc1": {
      "documentType": "STRING",
      "overallStatus": "STRING",
      "matchRate": "FLOAT",
      "exceptionSummary": "STRING"
    },
    "doc2": { "...": "same fields as doc1" },
    "doc3": { "...": "same fields as doc1" }
  },
  "validation": {
    "missingDocuments": {
      "idCard": "BOOLEAN",
      "proofOfAddress": "BOOLEAN",
      "salarySlip": "BOOLEAN"
    },
    "anyRejected": "BOOLEAN",
    "requiresReview": "BOOLEAN",
    "lowestMatchRate": "FLOAT"
  },
  "summaryInput": {
    "applicantName": "STRING",
    "decision": "STRING",
    "findings": "STRING"
  },
  "review": {
    "reviewerDecision": "STRING",
    "reviewerNotes": "STRING"
  },
  "summary": {
    "report": "STRING"
  }
}
```

> [!TIP]
>
> Define these keys under your process data model before building the process. The business rules, gateways, and UI components reference these paths at runtime.

***

## Step 1: Build the tool workflows

The agent doesn't extract fields itself. It calls four small workflows as tools: one that returns the document's raw text, and one extractor per document type. Every tool workflow follows the same contract:

* On the Data Model **Input Parameters** tab, add `filePath` (STRING). A workflow with no input parameters can't be attached as a tool.
* On the **Output Parameters** tab, add the fields the tool returns. Without output parameters, the tool returns nothing useful to the agent.
* Set the workflow **Description**. The agent sees it, together with the "when to use" hint you add in Step 2, when it chooses a tool.
* On the AI node, set **Document Source** to **Document Plugin** and reference the file as `${filePath}`. The workflow's input parameters resolve by name, whether you run the workflow on its own or the agent calls it as a tool.

### 1.1 Build readDocumentText

Create a workflow named **`readDocumentText`** with one **Extract Data from File** node:

* **Extraction Method:** **Automatic**. The format varies per upload in a mixed document set like this one, so let the node pick a strategy per file.
* **Response Key:** `documentText`
* **Output parameter:** `documentText`
* **Description:** `Return the raw text of an uploaded document so the agent can classify it. Uses the Automatic extraction method.`

Connect the node's SUCCESS exit to the End Flow node.

![Extract Data from File node with Extraction Method set to Automatic and Response Key documentText](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/dp-02-extract-data-from-file-automatic.png)

See [Extract Data from File](../agent-builder/extract-data-from-file) for a comparison of the extraction methods, image extraction, and signature detection.

### 1.2 Build the three extraction workflows

Create one workflow per document type: **`extractIdCard`**, **`extractProofOfAddress`**, and **`extractSalarySlip`**. Each contains a **Document Extraction** node with the instructions and response schema for its type, followed by a **Script** node that lifts the fields into the output parameters.

> [!WARNING]
>
> Use **Document Extraction** for this step, not Extract Data from File. The two nodes are not interchangeable:
>
> * **Document Extraction** takes **Instructions** and a **Response schema**, and returns structured fields. It has no extraction-method setting.
> * **Extract Data from File** takes an **Extraction Method** (Automatic, LLM Model, OCR Engine, Text Parsing) plus image and signature options, and returns text. It accepts no instructions or response schema.
>
> A single node cannot combine a prompt, a response schema, and an extraction method.

![Document Extraction node configuration with Instructions, Document Source, Response Schema, and Response Key](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/dp-01-document-extraction-config.png)

Document Extraction returns its result as a JSON string, under `responseObjects[0]` of the Response Key. The Script node parses it and maps each field to an output parameter.

> [tab] ID card
>
> **Description:** `Extract identity fields from an ID document (passport, national ID, driver's licence). Exposed to the verification agent as a tool.`
>
> **Instructions:**
>
> ```text theme={"dark"}
> Extract all personal identification fields from this ID document.
> The document may be a passport, national ID card, or driver's license.
> If a field is not present or not legible, return null for that field.
> ```
>
> **Response schema:**
>
> ```json theme={"dark"}
> {
>   "type": "object",
>   "properties": {
>     "document_number": { "type": "string" },
>     "first_name": { "type": "string" },
>     "last_name": { "type": "string" },
>     "date_of_birth": {
>       "type": "string",
>       "description": "Format: YYYY-MM-DD"
>     },
>     "nationality": { "type": "string" },
>     "expiry_date": {
>       "type": "string",
>       "description": "Format: YYYY-MM-DD"
>     },
>     "issuing_authority": { "type": "string" },
>     "address": {
>       "type": "object",
>       "properties": {
>         "street": { "type": "string" },
>         "city": { "type": "string" },
>         "postal_code": { "type": "string" },
>         "country": { "type": "string" }
>       }
>     }
>   },
>   "required": ["first_name", "last_name", "date_of_birth"]
> }
> ```
>
> **Response Key:** `extractedData`
>
> **Output parameters:** `firstName`, `lastName`, `dateOfBirth`, `documentNumber`, `expiryDate` (all STRING)
>
> **Script:**
>
> ```javascript theme={"dark"}
> var raw = input.extractedData.responseObjects[0];
> var r = JSON.parse(raw);
> output.firstName = r.first_name;
> output.lastName = r.last_name;
> output.dateOfBirth = r.date_of_birth;
> output.documentNumber = r.document_number;
> output.expiryDate = r.expiry_date;
> ```

> [tab] Proof of address
>
> **Description:** `Extract resident name, address and document date from a proof-of-address document. Exposed to the verification agent as a tool.`
>
> **Instructions:**
>
> ```text theme={"dark"}
> Extract the resident's name, full address, document date, and issuing
> organization from this proof of address document. The document may be a
> utility bill, bank statement, or government letter.
> If a field is not present, return null for that field.
> ```
>
> **Response schema:**
>
> ```json theme={"dark"}
> {
>   "type": "object",
>   "properties": {
>     "resident_name": { "type": "string" },
>     "address": {
>       "type": "object",
>       "properties": {
>         "street": { "type": "string" },
>         "city": { "type": "string" },
>         "postal_code": { "type": "string" },
>         "country": { "type": "string" }
>       }
>     },
>     "document_date": {
>       "type": "string",
>       "description": "Format: YYYY-MM-DD"
>     },
>     "issuing_organization": { "type": "string" },
>     "document_type_detail": {
>       "type": "string",
>       "description": "e.g., electricity bill, water bill, bank statement"
>     }
>   },
>   "required": ["resident_name", "address"]
> }
> ```
>
> **Response Key:** `extractedData`
>
> **Output parameters:** `residentName`, `street`, `city`, `postalCode`, `documentDate` (all STRING)
>
> **Script:**
>
> ```javascript theme={"dark"}
> var raw = input.extractedData.responseObjects[0];
> var r = JSON.parse(raw);
> output.residentName = r.resident_name;
> output.street = r.address ? r.address.street : null;
> output.city = r.address ? r.address.city : null;
> output.postalCode = r.address ? r.address.postal_code : null;
> output.documentDate = r.document_date;
> ```

> [tab] Salary slip
>
> **Description:** `Extract employer, pay period and salary components from a payslip. Exposed to the verification agent as a tool.`
>
> **Instructions:**
>
> ```text theme={"dark"}
> Extract salary and employment details from this payslip document.
> Capture the employee name, employer, pay period, and all salary
> components (gross, deductions, net).
> If a field is not present, return null for that field.
> ```
>
> **Response schema:**
>
> ```json theme={"dark"}
> {
>   "type": "object",
>   "properties": {
>     "employee_name": { "type": "string" },
>     "employer_name": { "type": "string" },
>     "pay_period": {
>       "type": "string",
>       "description": "e.g., January 2025, 2025-01"
>     },
>     "gross_salary": { "type": "number" },
>     "net_salary": { "type": "number" },
>     "deductions": {
>       "type": "object",
>       "properties": {
>         "tax": { "type": "number" },
>         "social_security": { "type": "number" },
>         "health_insurance": { "type": "number" },
>         "other": { "type": "number" }
>       }
>     },
>     "currency": { "type": "string" },
>     "employee_id": { "type": "string" }
>   },
>   "required": ["employee_name", "employer_name", "net_salary"]
> }
> ```
>
> **Response Key:** `extractedData`
>
> **Output parameters:** `employeeName`, `employerName`, `payPeriod`, `currency` (STRING) and `netSalary` (FLOAT)
>
> **Script:**
>
> ```javascript theme={"dark"}
> var raw = input.extractedData.responseObjects[0];
> var r = JSON.parse(raw);
> output.employeeName = r.employee_name;
> output.employerName = r.employer_name;
> output.payPeriod = r.pay_period;
> output.netSalary = r.net_salary;
> output.currency = r.currency;
> ```

> [!NOTE]
>
> Both Document Extraction and Extract Data from File support the **Personal Information Guard**, which detects and replaces personal data before it reaches the model. Consider turning it on for this pipeline: ID documents, addresses, and payslips all carry personal data. See [Personal Information Guard](../personal-information-guard).

***

## Step 2: Configure the verification agent

Create a workflow named **`verifyDocuments`**. It receives one document and the applicant's declared data, and a single **Custom Agent** node does the classification, the extraction tool call, and the reconciliation.

```mermaid theme={"dark"}
flowchart LR
    IN["Input: filePath +<br/>declared data"] --> AGENT["Custom Agent<br/>(classifies, reconciles)"]
    AGENT -->|"call 1: read text"| READ["readDocumentText"]
    AGENT -->|"call 2: one extractor"| ID["extractIdCard"]
    AGENT -->|"call 2: one extractor"| POA["extractProofOfAddress"]
    AGENT -->|"call 2: one extractor"| SAL["extractSalarySlip"]
    AGENT --> OUT["Output: documentType, overallStatus,<br/>matchRate, exceptionSummary"]
```

**Input parameters:** `filePath`, `declaredFirstName`, `declaredLastName`, `declaredCity` (STRING) and `declaredMonthlyIncome` (FLOAT)

**Output parameters:** `documentType`, `overallStatus`, `exceptionSummary` (STRING) and `matchRate` (FLOAT)

Add a **Custom Agent** node after the Start node.

**Instructions** (static; dynamic values go in **Context**):

```text theme={"dark"}
You are a document verification agent for a bank's customer onboarding
process.

You receive one uploaded document and the applicant's declared data.

Step 1 - Call readDocumentText once to read the document.

Step 2 - Classify it as ID_CARD, PROOF_OF_ADDRESS, SALARY_SLIP or UNKNOWN
from that text, based on its layout, headers and field labels.

Step 3 - Call exactly ONE extraction tool that matches the classification:
- ID_CARD uses extractIdCard
- PROOF_OF_ADDRESS uses extractProofOfAddress
- SALARY_SLIP uses extractSalarySlip
If the type is UNKNOWN, call no extraction tool and return overallStatus
REVIEW_REQUIRED.
Never call the same tool twice. Stop calling tools once you have the
extracted fields.

Step 4 - Reconcile the extracted fields against the declared data:
- Names use fuzzy matching. Case differences are a match; a different
  spelling is a WARNING.
- Compare addresses per component. Minor formatting differences are
  acceptable.
- Normalise dates to YYYY-MM-DD before comparing.
- Flag net salary that differs from declared monthly income by more than
  10 percent.
- An expired document is CRITICAL.

Return matchRate as a percentage from 0 to 100, overallStatus as APPROVED,
REVIEW_REQUIRED or REJECTED, and exceptionSummary as one short sentence
naming each mismatch found.
```

**Context:**

```text theme={"dark"}
Document to verify: ${filePath}
Declared first name: ${declaredFirstName}
Declared last name: ${declaredLastName}
Declared city: ${declaredCity}
Declared monthly income: ${declaredMonthlyIncome}
```

**Tools:** click **Add tool** → **Workflow** and attach the four tool workflows. Only workflows with input parameters appear in the list. For each one, fill in **When should the agent use this workflow?**:

| Workflow | When to use |
| - | - |
| `readDocumentText` | Call FIRST, exactly once, to read the raw text of the uploaded document so you can classify it. Returns documentText. |
| `extractIdCard` | Call for a passport, national ID card or driver's licence. Returns first name, last name, date of birth, document number and expiry date. |
| `extractProofOfAddress` | Call for a utility bill, bank statement or government letter used as proof of address. Returns resident name, street, city, postal code and document date. |
| `extractSalarySlip` | Call for a payslip or salary certificate. Returns employee name, employer name, pay period, net salary and currency. |

> [!TIP]
>
> The agent sees each tool as its workflow **Description** plus the **When should the agent use this workflow?** text. Write both as if you were telling a colleague when to use the tool, and put ordering rules and stop conditions ("exactly once", "call FIRST") in the hint.

![Custom Agent node Tools section listing the readDocumentText, extractIdCard, extractProofOfAddress, and extractSalarySlip workflow tools, each with its when-to-use hint](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/dp-04-agent-workflow-tools.png)

**Response schema:**

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "documentType": {
      "type": "string",
      "enum": ["ID_CARD", "PROOF_OF_ADDRESS", "SALARY_SLIP", "UNKNOWN"]
    },
    "matchRate": { "type": "number" },
    "overallStatus": {
      "type": "string",
      "enum": ["APPROVED", "REVIEW_REQUIRED", "REJECTED"]
    },
    "exceptionSummary": { "type": "string" }
  },
  "required": ["documentType", "matchRate", "overallStatus", "exceptionSummary"]
}
```

**Response Key:** `verification`

The agent's answer lands under the Response Key, so lift it into the output parameters with a **Script** node before the End Flow:

```javascript theme={"dark"}
output.documentType = input.verification.documentType;
output.overallStatus = input.verification.overallStatus;
output.matchRate = input.verification.matchRate;
output.exceptionSummary = input.verification.exceptionSummary;
```

> [!NOTE]
>
> Agents are capped at 20 tool calls per run, 10 of them to workflow tools, and an agent can have at most 10 workflow tools attached. A verification run stays far below the caps: it makes exactly two calls.

### Verified run

With declared data `John Smith, monthly income 5000` and a payslip showing employee Jonathan Smith and net salary 4,200 (the mismatch case from [Testing](#testing)), the agent returns:

```json theme={"dark"}
{
  "documentType": "SALARY_SLIP",
  "overallStatus": "REVIEW_REQUIRED",
  "matchRate": 60,
  "exceptionSummary": "Name mismatch: document shows Jonathan Smith vs declared John Smith, and net salary £4,200.00 differs from declared monthly income 5000.0 by more than 10%."
}
```

The run trace shows the agent called `readDocumentText` first, classified the document as `SALARY_SLIP`, called `extractSalarySlip` exactly once, and produced the reconciliation verdict.

![Run Logs for verifyDocuments showing the Custom Agent node with two child tool calls, readDocumentText then extractSalarySlip, and the Tools tab listing both calls](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/dp-05-agent-run-trace.png)

***

## Step 3: Build the summary generation workflow

Create a workflow named **`generateSummary`**. It receives the aggregated findings from the process and writes the verification report with a single **Text Generation** node.

**Input parameters:** `applicantName`, `decision`, `findings` (STRING) and `reviewerNotes` (STRING, optional)

**Output parameters:** `report` (STRING)

Add a **Text Generation** node after the Start node.

**Instructions:**

```text theme={"dark"}
You are a compliance documentation assistant. Write a document
verification report from the applicant name, the decision, the
per-document findings, and the reviewer notes provided in the context.

Structure the report as follows:

1. VERIFICATION OVERVIEW
   - Applicant name
   - Number of documents processed
   - Lowest match rate across the documents
   - Verification status (Approved / Review Required / Rejected)

2. DOCUMENT DETAILS
   For each document: document type, status, match rate, and the
   mismatches found.

3. EXCEPTIONS
   - List every mismatch named in the findings
   - Highlight anything marked REJECTED

4. RECOMMENDATION
   - Clear recommendation based on the findings and the reviewer notes
   - Specific follow-up actions if needed

Use professional, concise language. Format the report in Markdown.
```

**Context:**

```text theme={"dark"}
Applicant: ${applicantName}
Decision: ${decision}
Findings per document:
${findings}
Reviewer notes: ${reviewerNotes}
```

The workflow can only reference its own input parameters here. The process maps its data into them in Step 4.

**Response schema:**

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "report": {
      "type": "string",
      "description": "The verification report in Markdown"
    }
  },
  "required": ["report"]
}
```

**Response Key:** `summaryReport`

Add a **Script** node before the End Flow to lift the report into the output parameter:

```javascript theme={"dark"}
output.report = input.summaryReport.report;
```

***

## Step 4: Build the BPMN process

Create a process named **`documentVerify`** that orchestrates the full pipeline using the workflows you built.

> [!NOTE]
>
> The mappings below use the data mapping modals, the default. If you turn on **Legacy Mapping**, the **Start Integration Workflow** action takes a JSON input body and the Receive Message Task's data stream takes a single **Key Name** instead. See [Legacy mapping vs data mappers](/5.9/docs/building-blocks/node/message-send-received-task-node#legacy-mapping-vs-data-mappers).

> [!WARNING]
>
> Turn off **Use Test File** on the AI node of every tool workflow before you run this process. While it's on, the node reads its selected test file and ignores the `filePath` the agent passes in, even when a process starts the run, so every uploaded document is verified against the same sample.

**1. Add a User Task for file upload**

Add a **User Task** node after the Start Event. This task presents the file upload UI to the user.

Configure the task with:

* **Task name:** `Upload documents`
* **Assignment:** Assigned to the initiating user

The upload UI is designed directly on this node - you build it in Step 5. A User Task cannot attach a standalone UI Flow; its UI lives on the node.

**2. Verify each uploaded document**

Call `verifyDocuments` once per uploaded file. Array-indexed `${...}` expressions do not resolve in data mappings, so first copy the current file into a named object: add a **Service Task** with a **Business Rule** action that sets `output.currentFile = input.documents.uploadedFiles[0];`. See [Referencing workflow data in node configurations](/5.9/docs/platform-deep-dive/integrations/integration-workflows#referencing-workflow-data-in-node-configurations).

Then add a **Send Message Task** with a **Start Integration Workflow** action pointing to `verifyDocuments`, and map its input parameters:

| Workflow input | Process data |
| - | - |
| `filePath` | `${currentFile.filePath}` |
| `declaredFirstName` | `${applicant.firstName}` |
| `declaredLastName` | `${applicant.lastName}` |
| `declaredCity` | `${applicant.address.city}` |
| `declaredMonthlyIncome` | `${applicant.monthlyIncome}` |

Add a **Receive Message Task** node to capture the agent's verdict. Add a data stream with **Source** set to **Workflow**, select `verifyDocuments`, and in the **Output Mapping** of its End node map `documentType`, `overallStatus`, `matchRate`, and `exceptionSummary` to the fields of the same name under `verification.doc1`. Click **Confirm**, then save the node.

![Output mapping modal for the verifyDocuments End node, mapping documentType, overallStatus, matchRate, and exceptionSummary to the same fields under verification.doc1](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/dp-06-receive-output-mapping.png)

> [!TIP]
>
> Click **Test** in a mapping modal to check the mapping in **Preview results**. If the preview shows a `${...}` expression as literal text, the process sends that literal text at run time. Re-enter the path until the preview resolves it.

> [accordion] Legacy mapping equivalent
>
> With **Legacy Mapping** turned on, the action's JSON input body is:
>
> ```json theme={"dark"}
> {
>   "filePath": "${currentFile.filePath}",
>   "declaredFirstName": "${applicant.firstName}",
>   "declaredLastName": "${applicant.lastName}",
>   "declaredCity": "${applicant.address.city}",
>   "declaredMonthlyIncome": "${applicant.monthlyIncome}"
> }
> ```
>
> On the Receive Message Task, set the data stream's **Key Name** to `verification.doc1`.

Repeat the three nodes for the second and third file (`uploadedFiles[1]` into `verification.doc2`, `uploadedFiles[2]` into `verification.doc3`).

**3. Add a business rule to aggregate the verdicts**

Add a **Service Task** with a **Business Rule** action (JavaScript). The agent already checked each document against the declared data; this rule combines the three verdicts, checks that every required document type is present, and prepares the input for the summary. Business rules read process data through `input.` and write results through `output.`.

```javascript theme={"dark"}
// One verdict per uploaded document, as returned by verifyDocuments
var results = [input.verification.doc1, input.verification.doc2, input.verification.doc3];

var types = [];
var findings = [];
var anyRejected = false;
var anyNotApproved = false;
var lowestMatchRate = 100;

for (var i = 0; i < results.length; i++) {
  var r = results[i];
  if (!r) {
    continue;
  }
  types.push(r.documentType);
  if (r.overallStatus === "REJECTED") {
    anyRejected = true;
  }
  if (r.overallStatus !== "APPROVED") {
    anyNotApproved = true;
  }
  if (r.matchRate < lowestMatchRate) {
    lowestMatchRate = r.matchRate;
  }
  findings.push(r.documentType + ": " + r.overallStatus + " (" + r.matchRate + "%) - " + r.exceptionSummary);
}

// Check all required document types are present
var missingId = types.indexOf("ID_CARD") === -1;
var missingAddress = types.indexOf("PROOF_OF_ADDRESS") === -1;
var missingSalary = types.indexOf("SALARY_SLIP") === -1;
var requiresReview = anyNotApproved || missingId || missingAddress || missingSalary;

output.validation = {
  missingDocuments: {
    idCard: missingId,
    proofOfAddress: missingAddress,
    salarySlip: missingSalary
  },
  anyRejected: anyRejected,
  requiresReview: requiresReview,
  lowestMatchRate: lowestMatchRate
};

output.summaryInput = {
  applicantName: input.applicant.firstName + " " + input.applicant.lastName,
  decision: anyRejected ? "REJECTED" : (requiresReview ? "REVIEW_REQUIRED" : "APPROVED"),
  findings: findings.join(" | ")
};
```

> [!TIP]
>
> Business rules provide deterministic, auditable checks. Use them alongside the agent to enforce what must never depend on a model's judgment, such as the set of required document types.

**4. Add the routing gateway**

Add an **Exclusive Gateway** after the business rule. Configure two branches:

| Branch | Condition | Target |
| - | - | - |
| Auto-approve | `input.validation.requiresReview == false && input.validation.lowestMatchRate >= 90` | Proceed to summary generation |
| Human review | *(default)* | Human review User Task |

> [!WARNING]
>
> A gateway needs its evaluation rule defined in addition to the outgoing branches - without one, the process fails at runtime with "No rules found for gateway node". Gateway conditions read process data with the `input.` prefix.

**5. Add the human review task**

Add a **User Task** node for manual review. The reviewer sees:

* Uploaded documents (viewable in a File Preview component)
* The agent's verdict for each document, with its exception summary
* Validation flags from the business rule

The reviewer submits a decision:

* **Approve** — continue to summary
* **Reject** — end process with rejection status
* **Request re-upload** — loop back to the upload step

Store the decision in `review.reviewerDecision` and any notes in `review.reviewerNotes`.

**6. Route on the reviewer's decision**

Add a second **Exclusive Gateway** after the review task - the three reviewer outcomes each need a branch:

| Branch | Condition | Target |
| - | - | - |
| Approve | `input.review.reviewerDecision == 'APPROVE'` | Summary generation |
| Request re-upload | `input.review.reviewerDecision == 'REUPLOAD'` | Upload documents User Task |
| Reject | *(default)* | End Event |

**7. Trigger the summary generation workflow**

After both the auto-approve and human-review-approve paths converge, add a **Send Message Task** with a **Start Integration Workflow** action pointing to `generateSummary`, and map its input parameters:

| Workflow input | Process data |
| - | - |
| `applicantName` | `${summaryInput.applicantName}` |
| `decision` | `${summaryInput.decision}` |
| `findings` | `${summaryInput.findings}` |
| `reviewerNotes` | `${review.reviewerNotes}` |

Add a **Receive Message Task** with a **Workflow** data stream for `generateSummary`, and in the **Output Mapping** of its End node map `report` to `summary.report`. Click **Confirm**, then save the node.

> [accordion] Legacy mapping equivalent
>
> With **Legacy Mapping** turned on, the action's JSON input body is:
>
> ```json theme={"dark"}
> {
>   "applicantName": "${summaryInput.applicantName}",
>   "decision": "${summaryInput.decision}",
>   "findings": "${summaryInput.findings}",
>   "reviewerNotes": "${review.reviewerNotes}"
> }
> ```
>
> On the Receive Message Task, set the data stream's **Key Name** to `summary`.

**8. Add the End Event**

Add an **End Event** after the summary is received. The process instance now contains the full verification report at `summary.report`.

***

## Step 5: Build the upload UI

Design the upload page directly on the **Upload documents** User Task: select the node and open its UI Designer. A User Task's UI lives on the node - a standalone UI Flow cannot be attached to a BPMN task.

**1. Add an upload component**

Add a **File Upload** component to the node's UI and restrict the accepted file types to PDF, JPG, and PNG.

**2. Add the Upload file action**

On a User Task, the File Upload component does not come with an action - create an **Upload file** action on the node and link the component to it. The action posts the file to the Documents Plugin over Kafka; configure the **Address** (the document-persist topic) and the **Document Type**. For the full parameter list and the multi-file behavior, see the [Upload file action](/5.9/docs/building-blocks/actions/upload-file-action) guide.

The AI document nodes read uploaded files with **Document Source** set to **Document Plugin**, which resolves paths produced by this upload.

**3. Add applicant data display**

Add form fields (read-only) that display the applicant's declared data from `applicant`. This gives context to the person uploading documents.

**4. Add a submit button**

Add a **Button** component labeled **Submit documents**. Configure it to save the data and advance the User Task.

> [!NOTE]
>
> In a standalone **UI Flow** (for example, a chat-driven app that triggers workflows directly), the File Upload component behaves differently: it arrives with an **Upload** action already attached, and the upload result lands under that action's **Response Key** - not under the component's data key. With the default key of `response`, a successful upload produces:
>
> ```json theme={"dark"}
> {
>   "response": {
>     "filePath": "flowx-dev-ui-flow/{realm}/{workspace}/{session}/payslip.pdf",
>     "downloadPath": "internal/files/{id}/download",
>     "originalFileName": "payslip.pdf",
>     "mimeType": "application/pdf",
>     "error": null
>   }
> }
> ```
>
> Pass `response.filePath` to the workflow in that setup.
>
> ![File Upload component in a UI Flow with its Upload action open, showing the Response Key field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/dp-03-upload-response-key.png)

> [!NOTE]
>
> For the human review step, design a second page the same way - on the **Human review** User Task node - displaying the agent's verdict and exception summary for each document alongside the original documents. Use a side-by-side layout so the reviewer can compare easily.

***

## Step 6: Build the review UI

Design the review page on the **Human review** User Task node, the same way you built the upload page in Step 5.

The review page should include:

| Section | Data source | Component |
| - | - | - |
| Applicant info | `applicant` | Read-only form fields |
| Uploaded documents | One key per document that holds its preview URL, for example `preview.doc1.filePath` | One File Preview per document |
| Verdict per document | `verification.doc1`, `verification.doc2`, `verification.doc3` | Read-only fields with status badges |
| Findings | `summaryInput.findings` | Read-only text |
| Validation flags | `validation` | Alert components for each flag |
| Decision | `review.reviewerDecision` | Radio buttons (Approve / Reject / Request re-upload) |
| Notes | `review.reviewerNotes` | Text area |

> [!NOTE]
>
> A File Preview shows one file, and its **Process Data** source uses the key's value as-is, so the value must be a complete, absolute URL. Don't bind it to `documents.uploadedFiles`: that key holds a list, and each entry's `filePath` is a storage object path, not a URL. For each document, build the URL from the upload reply's `downloadPath` in a business rule and bind the File Preview to the result, as shown in [Preview an uploaded file](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#preview-an-uploaded-file).

> [!TIP]
>
> Use conditional visibility to highlight documents whose `overallStatus` is `REVIEW_REQUIRED` or `REJECTED`. This draws the reviewer's attention to the issues that need their judgment.

***

## Testing

**1. Test classification through the agent**

The `verifyDocuments` workflow has no file node of its own, so the sample documents go on the tool workflows. Upload them as test files on the AI nodes, turn on **Use Test File**, and select the document under test on `readDocumentText` and the matching sample on each extractor. Then open `verifyDocuments`, use **Run Workflow** with sample declared data, and check the `documentType` in the output and the tool calls in the run trace.

| Test document | Expected `documentType` | Expected extraction tool |
| - | - | - |
| Scanned passport | `ID_CARD` | `extractIdCard` |
| Electricity bill PDF | `PROOF_OF_ADDRESS` | `extractProofOfAddress` |
| Monthly payslip | `SALARY_SLIP` | `extractSalarySlip` |
| Random brochure | `UNKNOWN` | none, with `overallStatus` `REVIEW_REQUIRED` |

**2. Test extraction accuracy**

For each document type, compare the extracted fields in the run trace against the actual document content. Check that:

* Names are captured correctly (including accented characters)
* Dates are in the expected `YYYY-MM-DD` format
* Numeric values (salary, postal code) are accurate
* Null is returned for missing fields (not hallucinated values)

**3. Test reconciliation with known mismatches**

Run `verifyDocuments` with deliberate mismatches: declared John Smith with monthly income 5000, and a salary slip showing Jonathan Smith with net salary 4200. Expect:

* `documentType`: `SALARY_SLIP`
* `overallStatus`: `REVIEW_REQUIRED`
* `exceptionSummary` naming both the name variation and the income discrepancy (16%)

The run trace should show exactly two tool calls: `readDocumentText`, then `extractSalarySlip`.

**4. Test the business rule**

Verify the JavaScript business rule catches:

* Missing required document types
* Any document the agent marked `REJECTED` or `REVIEW_REQUIRED`
* A lowest match rate below the auto-approve threshold

Test edge cases: all documents valid (auto-approve path), one missing document (review path), expired ID (the agent flags it as CRITICAL, so the process takes the review path).

**5. Test the full end-to-end flow**

Run the complete `documentVerify` process:

1. Upload three documents (ID, proof of address, salary slip)
2. Verify that `verification.doc1` to `verification.doc3` are filled in
3. Check the `validation` flags and `summaryInput.findings`
4. If routed to review, complete the reviewer task
5. Verify the summary report is generated at `summary.report`

Test both the auto-approve path (all documents match) and the human review path (with discrepancies).

***

## Troubleshooting

> [accordion] The placeholder input.filePath has no value set!
>
> **Cause:** the AI node references the file as `${input.filePath}`. Workflow input parameters resolve by name, with no `input.` prefix.
>
> **Fix:** set the node's file reference to `${filePath}`. The same reference works when you run the workflow on its own and when the agent calls it as a tool.

***

## Explicit pipeline alternative

The verification agent decides at run time which extraction tool to call. If you need every routing decision to be visible on the canvas, or your deployment doesn't have workflow tools yet, build the same verification as explicit steps instead:

1. **Classify and extract:** classify each document, then branch to a type-specific Document Extraction node with a Condition node. The instructions and response schemas from [Step 1](#step-1-build-the-tool-workflows) carry over unchanged. See [Fan-out extraction](../patterns/fan-out-extraction).
2. **Reconcile:** compare the extracted fields against the applicant data in a separate comparison step with a structured exception report. See [AI comparison and reconciliation](../patterns/ai-comparison-reconciliation).

AI nodes return their result under the Response Key, and Document Extraction returns it as a JSON string. Parse it with a Script node before a Condition node branches on it, and before the End Flow node returns it.

Steps 3 to 6 stay the same. In Step 4, point the aggregation business rule at the reconciliation output instead of `verification.doc1` to `verification.doc3`.

***

## What you learned

In this tutorial, you built a document processing pipeline that demonstrates several key patterns:

* **Agentic tool-calling:** a Custom Agent that classifies each document and chooses the right extraction workflow at run time
* **Fan-out extraction:** a specialized extraction workflow per document type, with tailored instructions and schemas
* **AI reconciliation:** comparing AI-extracted data against application data and returning a structured verdict
* **Hybrid AI + business rules:** combining the agent's verdicts with deterministic checks (missing document types, match-rate threshold)
* **Human-in-the-loop:** routing edge cases to a reviewer while auto-approving clean results
* **Workflow composition:** building small, typed workflows for tools, verification, and summary generation, then orchestrating them from a BPMN process

***

## Next steps

> [card] [Fan-out extraction pattern](../patterns/fan-out-extraction)
>
> Scale the classification and extraction pattern to dozens of document types

> [card] [AI comparison and reconciliation](../patterns/ai-comparison-reconciliation)
>
> Deep-dive into the reconciliation pattern with threshold tuning

> [card] [Extract Data from File](../agent-builder/extract-data-from-file)
>
> Configure extraction strategies, image extraction, and signature detection

> [card] [AI node types](../agent-builder/node-types)
>
> Reference for all AI node types available in Agent Builder


# Mortgage advisor chatbot
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/mortgage-advisor

Build a Chat Driven conversational AI mortgage advisor with built-in session memory, intent routing, an agentic knowledge base, and a workflow-as-tool for deterministic recommendations.

In this tutorial, you build a **mortgage advisor chatbot** — a Chat Driven conversational AI app that guides users through mortgage product selection. The app detects what the user wants, answers questions from a knowledge base, collects financial data across conversation turns, and generates personalized recommendations by letting an AI agent call a deterministic calculation workflow as a tool.

**What you will build:**

* A **main Chat Driven workflow** that uses an **Intent Classification Agent** to route messages
* **Built-in session memory** that carries financial data across conversation turns
* A **knowledge base Q\&A** handler that answers mortgage questions from uploaded documents, using **agentic search**
* A **data collection** handler that captures the user's financial data from free-text messages
* A **personalized offer** generator where a Custom Agent calls a **workflow-as-tool** for auditable calculations
* A **small talk** responder and **fallback handler**

**AI node types used:** Intent Classification Agent, Custom Agent (with Knowledge Base, workflow tools, and Send as Chat Reply)

**Patterns demonstrated:** [Intent classification](../patterns/intent-classification-routing), [Knowledge base RAG](../patterns/knowledge-base-rag), [Hybrid AI + business rules](../patterns/hybrid-ai-rules), [Session state management](../patterns/session-state-management)

***

## Architecture overview

The app is a **Chat Driven workflow** that uses an **Intent Classification Agent** to classify each user message and route it to the right handler. Each intent maps to a separate output branch on the node, eliminating the need for a Condition node. Each handler is a **Custom Agent** with **Send as Chat Reply** enabled, which delivers the response directly to the Chat component and updates session memory.

```mermaid theme={"dark"}
flowchart TD
    A["Start<br/>(Chat Session ID, User Message)"] --> B["Intent Classification Agent"]
    B -- "Greetings" --> C["answerSmalltalk<br/>(Custom Agent → chat reply)"]
    B -- "Offer" --> D["answerPersonalisedOffer<br/>(Custom Agent + tool → chat reply)"]
    B -- "KB question" --> E["knowledgeBaseQA<br/>(Custom Agent + agentic KB → chat reply)"]
    B -- "Data Input" --> F["handleDataInput<br/>(Custom Agent → chat reply)"]
    B -- "If No Intent Matches" --> G["fallback<br/>(Custom Agent → chat reply)"]
    C --> H["End Flow"]
    D --> H
    E --> H
    F --> H
    G --> H
    D -. "calls as tool" .-> T["mortgageOfferCalc<br/>(workflow: PMT · DTI · rank)"]
```

> [!NOTE]
>
> In Chat Driven workflows, responses are delivered to the user by Custom Agent nodes with **Send as Chat Reply** enabled, not by the End Flow node. The End Flow node has no body configuration.

***

## Data model

In a Chat Driven workflow, the Start node provides **Chat Session ID**, **User Message**, and an optional **UI Flow Context** as dedicated input fields — you reference them as `${chatSessionId}`, `${userMessage}`, and `${context}` in downstream nodes. These are not keys you declare in the data model.

### mainChat data model

The mainChat workflow does not need any chat-specific keys in its data model — everything comes from the Start node fields and from the offer tool's output.

### mortgageOfferCalc data contract

The offer calculation workflow is exposed to the offer agent as a tool, so it declares an explicit input and output contract:

| Parameter | Direction | Type | Description |
| - | - | - | - |
| `age` | Input | INTEGER | Client age |
| `income` | Input | INTEGER | Monthly income |
| `loanAmount` | Input | INTEGER | Requested loan amount |
| `loanDuration` | Input | INTEGER | Loan term in years |
| `reportText` | Output | STRING | Generated recommendation text delivered by the offer agent |

> [!NOTE]
>
> **Built-in session memory**
>
> Chat Driven workflows retrieve the last 30 turns of the conversation automatically and send them to the model in full. Any Custom Agent node with **Use conversation memory** enabled receives this history as LLM context, so data mentioned in earlier turns (age, income, loan amount) is available to later turns without manual persistence. See [Session state management](../patterns/session-state-management) and [Chat-driven workflows — Session memory](../chat-driven-workflows#session-memory).

***

## Prerequisites

Before starting, make sure you have:

* Access to a FlowX Designer workspace with AI Platform enabled
* Familiarity with creating workflows in FlowX
* A **Knowledge Base** data source with mortgage-related documents uploaded (see [Step 4](#step-4-build-the-knowledge-base-q\&a-handler))

***

## Step 1: Build the main orchestration workflow

Create a workflow named **`mainChat`** and select **Chat Driven** as the workflow type.

> [!WARNING]
>
> The workflow type cannot be changed after creation. Make sure you select **Chat Driven** — Output Focused workflows cannot be used from the Chat component.

### Review the Start node

The Start node is created automatically with three fields:

* **Chat Session ID** — a UUID populated by the Chat component at runtime (referenced as `${chatSessionId}`)
* **User Message** — the user's text message (referenced as `${userMessage}`)
* **UI Flow Context** — optional JSON object passed from the UI (referenced as `${context}`)

No Start body configuration is needed in Chat Driven workflows.

### Add the Intent Classification Agent

From the node palette, drag an **Intent Classification Agent** node onto the canvas and connect it to the **Start** node.

Configure the node:

**User Message:** `${userMessage}`

**Intents:** in the **Intents** section, click **+ New Intent** for each row below and type the description into the field ("Describe the intent in a few words"). Each intent is a single description, and the node adds up to 10. The short names in the first column are only how this tutorial refers to each branch.

| Intent | Short name | Description to enter |
| - | - | - |
| 1 | Greetings | Greetings and small talk: hellos, thanks, casual conversation not tied to a mortgage question or data |
| 2 | Offer | The user asks for a product recommendation, a mortgage offer, product suggestions, or asks what mortgage fits them |
| 3 | KB question | Knowledge base questions about mortgage products, rates, policies, DTI, LTV, or required documents |
| 4 | Data Input | User is providing or updating personal financial data like income, age, loan amount, or loan duration |

**Response Key:** `intentResult`

The **If No Intent Matches** branch is a default output port that fires when the classifier can't confidently match any intent. It's always present on the node — you connect it to the fallback handler in Step 2.

![Intent Classification Agent with four intents, the If No Intent Matches branch, and Include Reason for Selection enabled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/02-intent-classification-node.png)

> [!TIP]
>
> Toggle **Include Reason for Selection** ON while tuning intent labels. When enabled, the agent returns a rationale explaining why it chose each intent — useful for diagnosing misclassifications. Turn it off once the intents are stable.

> [!NOTE]
>
> Each intent creates a separate output port on the node. When the agent classifies a message, the workflow continues along the matching branch — no Condition node needed. Leave **Use conversation memory** OFF so each message is classified on its own; turn it ON only if you want the classifier to resolve ambiguous follow-ups against prior turns.

### Connect handler nodes to each branch

Add the following nodes and connect each to its corresponding intent output:

| Intent branch | Handler node | Type |
| - | - | - |
| **Intent 1** (Greetings) | `answerSmalltalk` | Custom Agent |
| **Intent 2** (Offer) | `answerPersonalisedOffer` | Custom Agent with a workflow tool |
| **Intent 3** (KB question) | `knowledgeBaseQA` | Custom Agent with Knowledge Base |
| **Intent 4** (Data Input) | `handleDataInput` | Custom Agent |
| **No Match** | `fallback` | Custom Agent |

### Add the End Flow node

Add an **End Flow** node from the palette (it is not auto-created for Chat Driven workflows) and connect every handler branch to it. The End Flow node has no body configuration — responses are already delivered by the Custom Agent nodes upstream.

***

## Step 2: Build the inline handlers

Every handler in this tutorial is a **Custom Agent** placed directly in the `mainChat` workflow.

> [!NOTE]
>
> **Shared Custom Agent settings**
>
> Every Custom Agent in `mainChat` uses the same two defaults:
>
> * **Use only referenced values as input:** ON — keeps each call scoped to the values referenced with `${...}` in the **Context** field and reduces token usage.
> * **Include Task for Prompt Suggestions:** OFF — turn ON only if you want AI-generated follow-up prompts shown in the Chat component.
>
> Only the **Use conversation memory** and **Send as Chat Reply** toggles vary per handler, so those are called out on each node below.

![Custom Agent node showing Instructions, Use conversation memory, and Send as Chat Reply](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/03-custom-agent-config.png)

### answerSmalltalk (Custom Agent)

Add a **Custom Agent** node named `answerSmalltalk` to the Greetings branch.

**Instructions:**

```text theme={"dark"}
Role: You are a friendly and professional Mortgage Assistant. Your goal
is to respond to greetings or casual conversation in a warm, trustworthy
manner, and subtly steer the conversation back toward the user's
mortgage goals.

Response Guidelines:
- Tone: Warm, professional, and pragmatic.
- Acknowledge & Validate: Respond directly to what the user said.
- Subtle Pivot: End your response with a gentle nudge toward the
  mortgage process, without being pushy.
- Constraint: Keep the response under 3 sentences.
```

**Context:**

```text theme={"dark"}
User message: ${userMessage}
```

> [!NOTE]
>
> The **Instructions** field is static — the node rejects `${...}` references inside it with "This field is static. Use Context for dynamic values." Put dynamic values in the **Context** field, which accepts mixed text and `${...}` keys. This split applies to every AI node in this tutorial.

**Use conversation memory:** ON — lets the agent tie small talk back to anything the user already shared.

**Send as Chat Reply:** ON — sends the response to the Chat component as Markdown.

### fallback (Custom Agent)

Add a **Custom Agent** node named `fallback` on the No Match branch.

**Instructions:**

```text theme={"dark"}
Role: You are a mortgage assistant. The user sent a message that did not
match any known intent (greetings, product offer, knowledge base
question, or data input).

Respond with a short, friendly message that acknowledges you did not
understand and offers three concrete options the user can try: asking a
mortgage question, sharing their financial details, or requesting a
product recommendation. Keep it under 3 sentences.
```

**Context:**

```text theme={"dark"}
User message: ${userMessage}
```

**Use conversation memory:** OFF — the fallback response is self-contained.

**Send as Chat Reply:** ON.

***

## Step 3: Build the data input handler

The Data Input branch is a single **Custom Agent** named `handleDataInput`. With built-in session memory, the agent both captures the financial data from the message and confirms it back — no separate extraction script is needed.

**Instructions:**

```text theme={"dark"}
Role: You are a mortgage assistant that captures the user's financial
data from their message and confirms what you recorded.

From the user's message, identify any of: age, monthly income, loan
amount, loan duration (years). Confirm back exactly the values you
captured in a friendly one-line summary, then ask what else you can help
with. Do not invent numbers — only confirm values actually present in
the conversation. If nothing is extractable, ask them to share their
age, income, loan amount, or loan duration.
```

**Context:**

```text theme={"dark"}
User message: ${userMessage}
```

**Use conversation memory:** ON — so captured values persist across turns and reach the offer agent later.

**Send as Chat Reply:** ON.

> [!TIP]
>
> If you need strictly deterministic extraction (for example, to write values to a database), add a **Script** node before this agent to parse the message, and have the agent confirm the script's result. The single-agent version here is simpler and relies on session memory to carry values forward.

***

## Step 4: Build the knowledge base Q\&A handler

The KB question branch is a single **Custom Agent** node named `knowledgeBaseQA`, placed inline on the Intent 3 branch, with a Knowledge Base attached and **Send as Chat Reply** enabled.

### Set up the Knowledge Base

**1. Create a Knowledge Base data source**

In the **Integration Designer**, add a new **Knowledge Base** data source. Name it something descriptive like `MortgageKnowledgeBase`.

**2. Upload mortgage documents**

On the Knowledge Base's **Stores** tab, upload your own PDF documents covering product sheets (rates, terms, eligibility), FAQ documents (DTI, LTV), and regulatory guides (required documents, application process). This tutorial doesn't ship sample documents. Wait for automatic chunking and vector indexing to complete.

**3. Test queries**

On the **Chunks** tab, type a query like "What is DTI?" or "What documents do I need?" in **Query Input**, then click **Run** to check that relevant chunks come back.

> [!NOTE]
>
> For detailed Knowledge Base setup, see the [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview) documentation.

### Configure the Custom Agent node

Add a **Custom Agent** node named `knowledgeBaseQA` on the Intent 3 branch. In the node's **Background** section, select your `MortgageKnowledgeBase` data source from the **Knowledge Base** dropdown. The knowledge base options below appear once a knowledge base is selected.

Turn on **Enable agentic knowledge base search**. Instead of a single lookup, the agent issues several sub-queries per turn and merges the results, which improves recall on multi-part questions. To tune it, click **Settings** next to **Additional controls** and set **Max attempts** and **Subqueries per attempt**.

Under **Filtering options**, keep **Manual** unless you want the model to write its own metadata filter at run time (**Agentic**).

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

**Retrieval parameters:**

| Parameter | Value |
| - | - |
| **Search Type** | `Hybrid` |
| **Number of Chunks** | `4` |
| **Use Re-rank** | ON |
| **Enable agentic knowledge base search** | ON |
| **Filtering options** | Manual (no filters) |

![Knowledge Base Q\&A agent with agentic knowledge base search enabled and Manual/Agentic filtering](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/04-kb-agent-agentic-search.png)

> [!NOTE]
>
> Under **Hybrid** search the **Min Relevance Score** slider does not filter results — a hybrid score is a rank, not a similarity. To gate strictly on relevance, use **Semantic** search, or bound retrieval with **Number of Chunks** and re-rank.

**Instructions:**

```text theme={"dark"}
Role: You are a Mortgage Knowledge Base Expert who uses an integrated
Knowledge Base to provide accurate, data-grounded answers.

Operating Procedure:
1. Query Analysis: Identify key terms from the user's question.
2. Knowledge Base Search: Find the most relevant document fragments.
3. Response Synthesis: Formulate a clear answer using ONLY the
   information found.

Strict Rules:
- If the information is not in the Knowledge Base, respond:
  "Our current knowledge base does not contain specific information
  about this topic."
- Reference the source document when possible.
- Never fabricate rates, terms, or requirements.
- Keep responses concise (under 200 words).
```

**Context:**

```text theme={"dark"}
User question: ${userMessage}
```

**Use conversation memory:** ON — so the agent can resolve follow-ups like "what about the second one?" against the previous answer.

**Send as Chat Reply:** ON.

> [!WARNING]
>
> Without explicit grounding rules in the prompt, the LLM may fall back to its general training data and produce inaccurate mortgage information. Always include the "ONLY from knowledge base" instruction.

For more details on this pattern, see [Knowledge base RAG](../patterns/knowledge-base-rag).

***

## Step 5: Build the personalized offer handler

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

This handler implements the [Hybrid AI + business rules](../patterns/hybrid-ai-rules) pattern. In 5.11 you build it as a single **Custom Agent** that calls a deterministic calculation workflow as a **tool**: the agent handles the natural-language work (extract the client's numbers, present the result), while the tool handles the auditable math. This replaces the older pattern of an Output Focused subworkflow followed by a separate terminal agent.

### Step 5a: Build the mortgageOfferCalc workflow

Create a workflow named **`mortgageOfferCalc`** with **Output Focused** as the workflow type. In its **Description**, say what the workflow computes, for example `Deterministic mortgage offer calculator: monthly payment, DTI, maximum eligible loan, and ranked products.` The agent reads this description when it decides whether to call the tool.

Open the workflow's **Data Model** and give it an input and output contract so it can be exposed as a tool:

* **Input Parameters** tab: `age`, `income`, `loanAmount`, `loanDuration` (all INTEGER)
* **Output Parameters** tab: `reportText` (STRING)

> [!WARNING]
>
> The output contract is a promise the workflow has to keep. A node writes its result under its own **Response Key**, and only the parameters declared in the output contract are returned to the caller — so if the two do not line up, the workflow returns `SUCCESS` with every field `null` and the agent has no way to tell that apart from a genuinely empty result.
>
> The Script node below writes to `reportText`, which is the declared output parameter, so nothing extra is needed. An **AI node** is the case to watch: its Response Key holds a result object, so add a Script node after it that copies the values into the declared output parameters.

![mortgageOfferCalc data model with age, income, loanAmount, loanDuration inputs and reportText output](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/shot-08.png)

Add a single **Script** node (JavaScript) between Start and End Flow. It computes the monthly payment, debt-to-income ratio, and maximum eligible loan, scores the products, and writes the recommendation to `reportText`.

```javascript theme={"dark"}
var income = parseFloat(input.income) || 0;
var loanAmount = parseFloat(input.loanAmount) || 0;
var loanDuration = parseInt(input.loanDuration) || 20;
var termMonths = loanDuration * 12;

function computePMT(principal, annualRate, months) {
  var r = annualRate / 12;
  if (r === 0) return principal / months;
  return principal * (r * Math.pow(1 + r, months)) /
          (Math.pow(1 + r, months) - 1);
}

function pct(rate) { return Math.round(rate * 10000) / 100; }

var estimatedRate = 0.045;
var monthlyPayment = income > 0
  ? computePMT(loanAmount, estimatedRate, termMonths) : 0;
var dti = income > 0 ? monthlyPayment / income : 1;
var maxDtiShare = 0.43;
var allowablePayment = maxDtiShare * income;
var maxLoan = allowablePayment > 0
  ? allowablePayment * ((Math.pow(1 + estimatedRate / 12, termMonths) - 1) /
    (estimatedRate / 12 * Math.pow(1 + estimatedRate / 12, termMonths)))
  : 0;

var catalog = [
  {id: "fixed30", bankName: "Alpha Bank", rate: 0.045, allowsPrepayment: true,  flexibleTerm: false, term: 30},
  {id: "variable20", bankName: "Beta Bank", rate: 0.035, allowsPrepayment: false, flexibleTerm: true,  term: 20},
  {id: "fixed15", bankName: "Gamma Bank", rate: 0.04,  allowsPrepayment: true,  flexibleTerm: true,  term: 15}
];

var scored = [];
for (var i = 0; i < catalog.length; i++) {
  var d = catalog[i];
  var rateScore = 1 - (d.rate / 0.10);
  var flexScore = (d.allowsPrepayment ? 0.5 : 0) + (d.flexibleTerm ? 0.5 : 0);
  var totalScore = (rateScore * 0.5) + (0.8 * 0.3) + (flexScore * 0.2);
  scored.push({productId: d.id, bankName: d.bankName, rate: d.rate, term: d.term,
    totalScore: Math.round(totalScore * 1000) / 1000});
}
scored.sort(function(a, b) { return b.totalScore - a.totalScore; });

var eligible = dti <= maxDtiShare;
var report = "Mortgage Recommendation Report. ";
report += "Estimated monthly payment: " + (Math.round(monthlyPayment * 100) / 100) + " EUR. ";
report += "Debt-to-income ratio: " + pct(dti).toFixed(1) + "%. ";
report += "Maximum eligible loan: " + Math.round(maxLoan) + " EUR. ";
report += "Status: " + (eligible ? "Eligible" : "May need adjustment") + ". ";
report += "Top Recommendations: ";
for (var k = 0; k < scored.length; k++) {
  var p = scored[k];
  report += (k + 1) + ". " + p.bankName + " (" + p.productId + ") - "
    + pct(p.rate) + "% for " + p.term + " years. Score: " + p.totalScore + ". ";
}
report += "Next Steps: Compare the options above, gather required documents, "
  + "and schedule a consultation with your preferred bank.";

output.reportText = report;
```

![mortgageOfferCalc workflow: Start, calc-and-rank Script, End Flow returning reportText](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/shot-07.png)

> [!NOTE]
>
> Keeping the numbers in a Script node rather than an LLM keeps them deterministic and auditable. For any recommendation, you can trace exactly which formula produced each figure.

### Step 5b: Attach the workflow as a tool on the offer agent

Switch back to `mainChat`. On the Offer branch, add a **Custom Agent** node named `answerPersonalisedOffer`. Under **Tools**, click **Add tool** → **Workflow** and select `mortgageOfferCalc`. Only workflows with input parameters appear in the list.

In the tool's **When should the agent use this workflow?** field, name the arguments and add a stop condition:

```text theme={"dark"}
Compute the personalized mortgage recommendation report (monthly payment,
DTI, max eligible loan, ranked products). Pass all four integer arguments:
age, income (monthly), loanAmount, and loanDuration (years). Call at most
once per turn; a SUCCESS with a non-empty reportText completes the lookup,
so do not call it again after it returns.
```

![Offer Custom Agent with the mortgageOfferCalc workflow attached as a callable tool](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/05-offer-agent-workflow-tool.png)

**Instructions:**

```text theme={"dark"}
Role: You are a mortgage advisor that produces a personalized
recommendation for the client.

Procedure:
1. From the conversation (current message and prior turns), determine the
   client's age, monthly income, loan amount, and loan duration in years.
2. Call the mortgageOfferCalc tool with those four integers to compute the
   recommendation report. Never invent the numbers yourself — always use
   the tool. Call it at most once per turn; a successful result completes
   the lookup.
3. Present the tool's report to the client in a warm, professional tone,
   preserving every number and product name exactly. Close by inviting
   follow-up questions.

If any of the four values is missing and cannot be inferred from the
conversation, ask the client for the missing value instead of calling
the tool.
```

**Context:**

```text theme={"dark"}
User message: ${userMessage}
```

**Use conversation memory:** ON — so the agent can reuse age, income, loan amount, and duration shared in earlier turns.

**Send as Chat Reply:** ON.

Connect this Custom Agent to the **End Flow** node on `mainChat`.

> [!NOTE]
>
> A workflow can be attached as a tool only if it declares input parameters, and it needs output parameters to return anything useful (Step 5a). The agent sees the workflow's **Description** plus the **When should the agent use this workflow?** text as the tool description, so name the arguments it needs and add a stop condition there. An agent node is capped at 10 workflow-tool calls per run — past the cap the call is not dispatched and the agent is told to answer with what it already has, so the prompt is still what stops a model from re-calling a tool that already succeeded.

***

## Step 6: Connect to the chat UI

**1. Create a Chat-Driven UI Flow**

Go to **UI Flows** and create a new UI Flow, selecting **Chat-Driven** as the experience type. Set `mainChat` in the **AI Conversational Workflow** field.

**2. Add a Chat component**

Add a **Chat** component to the page. In a Chat-Driven UI Flow it uses `mainChat` by default — no per-component configuration needed.

**3. Test the chat**

Click **Run** to preview the UI Flow and interact with the chatbot.

![Chat-Driven UI Flow with the Chat component bound to the mainChat conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/shot-09.png)

> [!NOTE]
>
> For details on configuring chat experiences with built-in session memory, see [Chat-driven workflows](../chat-driven-workflows). For the Chat component reference, see [Chat component](../chat-component).

***

## Testing

**1. Test the mainChat workflow directly**

Open `mainChat` and click **Run Workflow**. In the test modal, provide a valid UUID for **Chat Session ID** (click **Generate Chat Session ID** to create one, and reuse the same one across runs to verify multi-turn memory) and a **User Message**.

> [!WARNING]
>
> The Chat Session ID must be a valid UUID. A plain string like `test-session-1` causes a runtime error: `Invalid UUID string`.

**2. Test the full chat flow**

Run the UI Flow that embeds the Chat component. With built-in session memory, financial details captured in earlier turns are available to later turns:

| Turn | Message | Expected behavior |
| - | - | - |
| 1 | "Hi there!" | Greeting response, nudge toward mortgage |
| 2 | "I'm 35, I earn 6000 EUR a month, and I want to borrow 250000 EUR over 20 years." | Acknowledges the recorded data |
| 3 | "Give me a product recommendation now." | Recommendation report using the data from turn 2 |

![Mortgage advisor chat returning a recommendation report with payment, DTI, max loan, and ranked products](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/06-chat-running.png)

**3. Test edge cases**

| Test message | Expected intent branch | Expected behavior |
| - | - | - |
| "What documents do I need to apply?" | KB question | Answer from knowledge base |
| "asdfghjk" | No Match | Fallback response |
| "I changed my mind, my income is 6000" | Data Input | Updates income, confirms change |

***

## What you learned

In this tutorial, you built a full-featured Chat Driven app that demonstrates:

* **Chat Driven workflow basics** — dedicated Start node fields, `${userMessage}` interpolation, simplified End Flow ([guide](../chat-driven-workflows))
* **Built-in session memory** — multi-turn context without manually persisting conversation history
* **Intent classification and routing** — using an Intent Classification Agent to route messages to handler branches automatically ([pattern](../patterns/intent-classification-routing))
* **Agentic knowledge base search** — grounding answers in uploaded documents with multi-query retrieval and re-rank ([pattern](../patterns/knowledge-base-rag))
* **Workflow-as-tool** — letting a Custom Agent call a deterministic calculation workflow for auditable, hybrid AI + business-rule recommendations ([pattern](../patterns/hybrid-ai-rules))

***

## Next steps

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Full reference for Chat Driven workflows, AI Triggers, and session memory

> [card] [AI patterns](../patterns/overview)
>
> Deep-dive into the patterns used in this tutorial

> [card] [Node types reference](../agent-builder/node-types)
>
> Detailed configuration reference for all AI node types

> [card] [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Create and manage Knowledge Bases for RAG


# Tutorials
Source: https://docs.flowx.ai/5.9/ai-platform/tutorials/overview

Step-by-step guides for building real-world AI apps with FlowX.AI, based on production-grade examples.

Learn how to build AI-powered apps on FlowX by following end-to-end tutorials based on real implementations.

## Available tutorials

> [card] [Mortgage advisor chatbot](./mortgage-advisor)
>
> Build a Chat Driven conversational AI mortgage advisor that collects client data across turns, evaluates eligibility across multiple banks, and generates personalized product recommendations.
>
> **You will learn:** Chat Driven workflows, built-in session memory, the Intent Classification Agent with a branch per intent, agentic knowledge base search with re-ranking, calling a workflow as an agent tool for auditable calculations, hybrid AI + business rules, Send as Chat Reply, chat UI integration

> [card] [Document processing pipeline](./document-processing)
>
> Build an AI-powered document verification pipeline that classifies uploaded documents, extracts structured data, and reconciles it against application data.
>
> **You will learn:** fan-out extraction, document classification, AI reconciliation, business rules validation, human-in-the-loop review

> [card] [Customer onboarding with KYC](./customer-onboarding)
>
> Build a multi-step customer onboarding process with identity verification, document generation, manual review routing, and email notifications.
>
> **You will learn:** multi-step forms, REST API integration via workflows, exclusive gateways, document generation, task assignment, timer events, notifications

***

## What makes these different

These tutorials are derived from **production apps**, not hypothetical examples. Each one:

* Uses **real workflow structures** exported from working FlowX projects
* Shows how to combine **multiple AI node types** (extraction, understanding, generation) in a single app
* Demonstrates **integration patterns** (REST APIs, databases, email triggers, chat UI)
* Includes the **business logic layer** — not just the AI parts

***

## Before you start

> [!NOTE]
>
> These tutorials assume familiarity with FlowX Designer basics — creating processes, workflows, data sources, and UI flows. If you are new to FlowX, start with the [FlowX Academy](https://academy.flowx.ai) courses first.

Each tutorial is structured as:

1. **Architecture overview** — what you are building and how the pieces fit together
2. **Data model** — the data types and sources you need
3. **Workflows** — step-by-step workflow construction with AI nodes
4. **Process orchestration** — BPMN processes that tie workflows together
5. **UI** — the user-facing interface (chat or task management)
6. **Testing** — how to validate the end-to-end flow

***

## Related resources

> [card] [AI patterns](../patterns/overview)
>
> Reusable patterns extracted from these tutorials

> [card] [Agent Builder](../agent-builder/overview)
>
> Node types and configuration reference

> [card] [Node types](../agent-builder/node-types)
>
> Detailed reference for each AI node type

> [card] [Using agents](../using-agents/overview)
>
> Integration options for deploying agents


# Call an external API from a process
Source: https://docs.flowx.ai/5.9/cookbooks/call-external-api

Connect a public REST API through a data source, wrap it in an integration workflow, and map the result back into process data - the send, workflow, receive pattern end to end.

Tested · September 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** The process ran end to end: it called the workflow, the workflow called the random.org API, and the process received the generated number.

Every FlowX integration that fetches data for a running process follows the same round trip: the process **sends** a request to an integration workflow, the workflow calls the external system and shapes the result, and the process **receives** the output into its instance data. This cookbook builds that round trip once, end to end, with a real public API - and shows you where each hop breaks, what the error looks like, and how to fix it.

You build a one-time-code generator: a process asks the [random.org](https://www.random.org) integers API for a 4-digit number and displays it. The API is deliberately minimal - no authentication, a plain-text response - so every step stays visible. Swap in your own API and the steps are identical.

> [!NOTE]
>
> **Prerequisites**: a project in your workspace and access to FlowX.AI Designer. If integration workflows are new to you, read [Build your first workflow](/5.9/docs/getting-started/building-your-first-workflow) first - it introduces the same three building blocks conceptually. This cookbook is the hands-on companion: a concrete build you can reproduce click for click, plus the runtime failure modes.

***

## The pattern

Three resources, one hop each:

1. A **data source** holds the connection: base URL, authorization, and reusable endpoint definitions.
2. An **integration workflow** calls the endpoint and declares what it returns. Whatever the workflow declares as output becomes a runtime contract.
3. In the process, a **Send Message Task** starts the workflow and a **Receive Message Task** maps its output into process data.

Each hop has its own key namespace, and each has its own failure signature when a key doesn't match - the [When it fails](#when-it-fails) section maps all three.

***

## Step 1: Create the data source

**1. Add a RESTful System**

In FlowX.AI Designer, go to your project → **Integrations** → **Data Sources**, click **+**, and pick **RESTful System**:

* **Name**: `RandomNumber`
* **Base URL**: `https://www.random.org/`
* **Authorization**: **No Auth** - the random.org integers endpoint is public

**2. Define the endpoint**

Add an endpoint named `getNumber`:

* **Method**: `GET`
* **Path**: `integers/`
* **Query parameters**:

| Parameter | Value | What it does |
| - | - | - |
| `num` | `1` | One number per request |
| `min` | `1000` | Lower bound |
| `max` | `9999` | Upper bound - together with `min`, always a 4-digit code |
| `col` | `1` | One column of output |
| `base` | `10` | Decimal |
| `format` | `plain` | Plain-text response body |
| `rnd` | `new` | Freshly generated randomness |

![The getNumber endpoint in the RandomNumber data source, with the base URL, the integers/ path, and the seven query parameters defined in the Query tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-01-data-source-endpoint.png)

> [!NOTE]
>
> `format=plain` means the API answers with `text/plain` - the body is the bare number followed by a newline, for example `7841\n`, not JSON. That trailing newline is invisible in most tools but matters later: see [Plain-text responses](#plain-text-responses-and-the-end-node) below.

***

## Step 2: Build the workflow

**1. Create the workflow**

Go to **Integrations** → **Workflows** and create a workflow named `getNumber`. It starts with a **Start** node - this workflow needs no input, so leave it empty.

**2. Add the REST API Call node**

Add a **REST API Call** node after Start and select the `getNumber` endpoint (endpoints are grouped by data source). Set its **Response Key** to `responseKey`.

The node stores its full result under that key: the response body at `responseKey.data`, plus `responseKey.metadata` (status code and headers) and `responseKey.hasError`. Every placeholder downstream references the body as `${responseKey.data}`.

![The getNumber workflow canvas: Start, the Call random.org REST node, a success End node with the output schema, and an End failure node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-02-workflow-canvas.png)

![The REST API Call node with the getNumber endpoint selected, the seven query parameters inherited from the endpoint, and the Response Key set to responseKey](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-03-rest-node-config.png)

**3. Branch success and failure**

Connect the REST node to two **End** nodes: one on the **success** branch, one on the **failure** branch. The failure branch keeps a timeout or non-2xx response from masquerading as a result.

**4. Test the REST node on its own**

Run the workflow from the editor and open the REST node in the run details - it shows the exact input it sent and the output it stored. Confirm the body sits at `responseKey.data` before wiring anything else.

***

## Step 3: Declare the workflow output

The calling process only receives what the workflow declares as output. Declare it through the workflow data model, then mark it as the success End node's output.

**1. Model the output attribute**

In the workflow's data model, add an object attribute `responseKey` with a string attribute `data` under it - mirroring where the REST node stores the body.

**2. Set the End node output**

On the success End node, set the output to `responseKey.data`. This is the declared output parameter: the value the calling process gets back.

![The workflow's Output Parameters tab with the End node selected and the responseKey object with its data string attribute declared as the output schema](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-04-output-data-model.png)

> [!WARNING]
>
> Declared output parameters are a **runtime contract**. If any declared parameter resolves to no value when the run reaches the End node, the run fails and the calling process records an incident - see [mandatory output parameters missing](/5.9/docs/resources/error-glossary#the-mandatory-output-parameters-of-the-workflow-are-missing-at-runtime). A misspelled key resolves silently to `null`, so the contract failing is often the only symptom.

### Plain-text responses and the End node

If you hand-write the End node's payload as JSON instead of mapping the data model, placeholders are substituted as raw text. For this API the body is `7841\n`, and the trailing newline makes `{"value": "${responseKey.data}"}` invalid JSON - the run fails with [Executing an end node produced an error!](/5.9/docs/resources/error-glossary#executing-an-end-node-produced-an-error). Keep the placeholder unquoted for numeric values, or clean the value in a Script node first. The data-model mapping used in this cookbook carries the value as a string and avoids the problem entirely.

***

## Step 4: Start the workflow from the process

**1. Add the Send Message Task**

In your BPMN process, add a **Send Message Task** node where the code should be requested.

**2. Configure the Start Integration Workflow action**

Add a **Start Integration Workflow** action on the node and select the `getNumber` workflow. This workflow declares no input, so there is nothing to map - for an API that takes parameters, map process data to the workflow's declared input parameters here.

![The Start Integration Workflow action on the Request code Send Message Task, showing the input mapping panel for the selected getNumber workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-05-send-action.png)

For the action's full options, including when to use it on Task and User Task nodes, see [Start integration workflow](/5.9/docs/building-blocks/actions/start-integration-workflow).

***

## Step 5: Receive the output

**1. Add the Receive Message Task**

Add a **Receive Message Task** directly after the Send Message Task. The process waits here until the workflow replies.

**2. Select the workflow as the data stream**

In the node's **Integration Output** section, add a data stream (**Add Stream**), set its **Source** to **Workflow**, and select `getNumber` in the **Select workflow** dropdown.

![The Receive Message Task node config with the Output Mapping section listing the workflow's End and End failure nodes, each with its own mapping](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-06-receive-data-stream.png)

**3. Map the output**

Open the **Output Mapping** for the workflow's success End node and map the workflow output to the process attribute that should receive it - for example `generatedNumber`. Click **Test** to preview the mapped result, then **Confirm** to store the mapping.

![The data mapping modal for the workflow's End node: responseKey.data mapped to the generatedNumber process attribute, with the Test button and the previewed mapping output](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-07-output-mapping-modal.png)

**4. Save the node**

Save the Receive Message Task itself. The mapping is persisted only when the node is saved.

> [!WARNING]
>
> **Test only previews - Confirm stores.** Closing the mapping modal without clicking **Confirm**, or skipping the node save, leaves the node with no mapping. Every reply then fails at runtime with [missing mapping in the data stream](/5.9/docs/resources/error-glossary#workflow-output-cannot-be-appended-to-the-process-instance-due-to-missing-mapping-in-the-data-stream) - and the workflow run itself finishes cleanly, which makes this one easy to misdiagnose.

> [!TIP]
>
> The mapping modal belongs to the **data mappers** mode, the default. Older configurations use the **Legacy Mapping** toggle and a single hand-typed key instead - both modes work at runtime. See [Legacy mapping vs data mappers](/5.9/docs/building-blocks/node/message-send-received-task-node#legacy-mapping-vs-data-mappers).

***

## Step 6: Run it end to end

Start a process instance and let it pass the Send Message Task. When the Receive Message Task completes, the instance data holds the code under `generatedNumber` - every node after it can read the value, display it in the UI, or branch on it.

To see the round trip from the workflow's side, open the workflow's run details: each node shows the exact input it received and the output it produced, so you can watch `responseKey.data` travel from the REST node through the End node.

![Workflow run details with the End node selected and its Output tab showing the responseKey object carrying the plain-text number in data](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cookbooks/cb-ext-api-08-run-details.png)

> [!TIP]
>
> You built a reusable data source, a workflow with a declared output contract, and a process that delegates the call and maps the result - the pattern behind most FlowX integrations.

***

## When it fails

Each hop fails with its own signature. All three are documented in depth in the [error glossary](/5.9/docs/resources/error-glossary#integration-workflow-output):

| Symptom | Broken hop | Where to look |
| - | - | - |
| `The mandatory output parameters of the workflow are missing at runtime.` | The End node's output resolved to `null` - usually a misspelled key. The REST call itself likely succeeded. | [Glossary entry](/5.9/docs/resources/error-glossary#the-mandatory-output-parameters-of-the-workflow-are-missing-at-runtime) |
| `Workflow output cannot be appended to the process instance due to missing mapping in the data stream.` | The Receive Message Task has no persisted output mapping - **Confirm** or the node save was skipped. The workflow run finishes fine. | [Glossary entry](/5.9/docs/resources/error-glossary#workflow-output-cannot-be-appended-to-the-process-instance-due-to-missing-mapping-in-the-data-stream) |
| `Executing an end node produced an error!` | The End node's hand-written payload stopped being valid JSON after placeholder substitution - typically a plain-text response with a trailing newline inside a quoted string. | [Glossary entry](/5.9/docs/resources/error-glossary#executing-an-end-node-produced-an-error) |

> [!WARNING]
>
> A failed workflow reply is **not retried**. An instance whose call failed stays blocked at the Receive Message Task permanently - after fixing the configuration, always test with a new process instance.

***

## Related resources

> [card] [Build your first workflow](/5.9/docs/getting-started/building-your-first-workflow)
>
> The conceptual introduction to data sources, workflows, and process actions.

> [card] [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer)
>
> The full reference: endpoint parameters, authorization, variables, and every workflow node.

> [card] [Send and Receive Message Tasks](/5.9/docs/building-blocks/node/message-send-received-task-node)
>
> Node configuration in detail, including data streams and mapping modes.

> [card] [Error glossary: integration workflow output](/5.9/docs/resources/error-glossary#integration-workflow-output)
>
> The three runtime errors of this pattern, with causes and fixes.


# Fill a document template from a workflow and download it
Source: https://docs.flowx.ai/5.9/cookbooks/generate-and-download-a-document

Map a Script node's output into the Template Filling node, fix a node that shows no mapping options, and turn the returned downloadPath into a working download URL.

Tested · October 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** The workflow ran end to end: a Script node's output was mapped into the Template Filling node, the PDF was generated with the mapped values, and the download URL returned the file with a token and rejected the request without one.

This guide answers three questions about generating a document in an integration workflow:

1. How do I pass a Script node's output into the **Template Filling** node?
2. Why does the Template Filling node show no mapping options?
3. How do I build the download URL for the generated document?

The first two questions apply to the Template Filling node, which is available on SaaS. The download URL section applies to every deployment, including self-hosted FlowX.AI 5.9.x and 5.1.x.

> [!NOTE]
>
> **Prerequisites**: a project with an integration workflow, and a document template in the project's **Document templates**. For creating and editing templates, see [Managing templates](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/managing-html-templates).

***

## How do I pass a Script node's output into the Template Filling node?

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

A Script node's `output` is merged into the root of the workflow data, with no prefix for the node name. A key the script writes as `output.customer` is available to every later node as `customer`, and its fields as `customer.fullName`. The Template Filling node reads its template values from that workflow data.

**1. Write the values from the Script node**

Assign each value the template needs to a key on `output`:

```javascript theme={"dark"}
// Script node placed before the Template Filling node
output.customer = {
  fullName: input.applicant.firstName + " " + input.applicant.lastName,
  contractNumber: input.contractNumber
};
```

Later nodes reference these values as `${customer.fullName}` and `${customer.contractNumber}`. For the expression rules, see [Referencing workflow data in node configurations](/5.9/docs/platform-deep-dive/integrations/integration-workflows#referencing-workflow-data-in-node-configurations).

**2. Declare the keys in the workflow data model**

The data mapper in the Template Filling node lists the attributes of the workflow's **Data Model** as its source, and a key the Script node writes isn't offered until it's declared there. Add the keys to the workflow data model with the same names and nesting (in this example, a `customer` object with `fullName` and `contractNumber`). See [Workflow data models](/5.9/docs/platform-deep-dive/integrations/workflow-data-models).

> [!TIP]
>
> You can also declare a key from inside the mapper. In a template field, type the path, for example `${customer.fullName}`, click **Add new attribute**, and save the **Attribute Settings**. The attribute is added to the workflow data model when you save the mapping.

**3. Define the template's input parameters**

The mapper fills only the template attributes selected as input parameters. Open the document template and:

1. On the **Data Model** tab, add an attribute for each value, for example `fullName` and `contractNumber` of type string.
2. On the **Input Parameters** tab, click **Define parameters**, select the attributes, and click **Done**.

In the template markup, insert each value with a Thymeleaf `th:text` attribute:

```html theme={"dark"}
<p>Contract number: <strong th:text="${contractNumber}"></strong></p>
<p>Customer: <strong th:text="${fullName}"></strong></p>
```

A bare `${fullName}` outside a `th:` attribute is printed as is in the generated document.

![Template Input Parameters tab listing contractNumber and fullName as string input parameters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/final-3-template-input-parameters.png)

**4. Add and configure the Template Filling node**

Add **Template Filling** from the node palette after the Script node and set:

* **Template**: the document template to fill, from this project or one of its library dependencies
* **Language**: the template language
* **Document Tag**: the tag stored with the generated file, for example `ContractTemplate`
* **Document format**: **PDF** (default) or **DOCX**
* **Response Key**: the key that holds the generated file's details, for example `generatedContract`

**Template**, **Language**, **Document Tag**, and **Response Key** are required.

**5. Map the workflow attributes onto the template**

Under **Input Mapping**, click the wrench icon (**Configure mapping**) on the **Template Input** card. In the **Input Mapping** window:

1. In the workflow panel on the left, click **Define parameters**, select the workflow attributes to map (for example `customer`), and click **Done**.
2. In the field next to each template attribute, type `${customer.` and pick the suggested path, for example `${customer.fullName}`.
3. Optionally, click **Test** to see the mapped output under **Preview results**.
4. Click **Save**.

![Input Mapping window with customer.fullName and customer.contractNumber mapped onto the fullName and contractNumber template attributes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/final-2-input-mapping-modal.png)

The **Template Input** card then shows how many attributes are mapped, for example **2 mapped**.

![Template Filling node after the Script node, with the Template Input card showing 2 mapped](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/final-1-template-filling-node.png)

### Template Filling nodes created before data mapping

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Data mapping arrived in FlowX.AI 5.13. Template Filling nodes created before then show an **Enable data mapping** toggle:

* **On**: the node uses the data mapper (**Configure mapping** on the **Template Input** card). Values typed by hand are ignored.
* **Off**: under **Template Variables**, click **Configure Variables** and enter a value for each template variable, either fixed text or an expression such as `${customer.fullName}`.

New nodes always use the mapper and don't show the toggle.

***

## Why does the Template Filling node show no mapping options?

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The mapper needs a selected template whose data model has input attributes. Find the message or symptom you see in the table below:

| What you see | Cause | Fix |
| - | - | - |
| **No template selected** | No template is set in **Template**. | Select a template. |
| **This template has no input attributes to map onto** | The template has no data model attributes, or none is selected as an input parameter. | Open the template, add attributes on its **Data Model** tab, and select them on the **Input Parameters** tab. Then reopen the node. |
| The same message, followed by **so it can only be filled in by hand**, and the **Enable data mapping** toggle is unavailable | The node predates data mapping, and the template has no input attributes. | Add input parameters to the template as in the previous row, or fill the values by hand under **Template Variables**. |
| The mapper opens with **No workflow parameters** on the left | No workflow attributes have been added to the mapper yet. | Click **Define parameters**, select the attributes, and click **Done**. |
| The mapper opens, but the Script node's keys aren't listed as sources | The keys aren't declared in the workflow data model. | Add them to the workflow **Data Model**, as in [Declare the keys in the workflow data model](#how-do-i-pass-a-script-node’s-output-into-the-template-filling-node). |
| The document is generated, but every template value is empty | Data mapping is on, but no mapping was saved. The node sends empty template data. | Click **Configure mapping**, map the attributes, and save. |
| The document shows `${fullName}` literally instead of the value | The template markup uses a bare `${...}` placeholder. | Insert the value with a `th:text` attribute, for example `<strong th:text="${fullName}"></strong>`. |
| The run fails with **Workflow is missing outgoing sequences** | The Template Filling node failed and the document wasn't generated. Only the node's green (success) exit is connected, so the failed run has no path to follow. | Connect the node's red (failure) exit to a branch that handles a failed generation. |

For the template data model and the **Input Parameters** tab, see [Managing templates](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/managing-html-templates).

***

## How do I build the download URL for the generated document?

All Deployments

The download URL is the Documents plugin base URL followed by the `downloadPath` the plugin returns:

```
https://{your-flowx-api-host}/document/ + downloadPath
```

`downloadPath` is relative, for example `internal/files/{fileId}/download`, so the complete URL has the form `https://{your-flowx-api-host}/document/internal/files/{fileId}/download`. The `/document` prefix is the route the Documents plugin is exposed on, as listed in the [ingress service route reference](/5.9/setup-guides/ingress-configuration). Keep the trailing slash after `document`, because `downloadPath` doesn't start with one.

### What does the Template Filling node return?

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The node stores the Documents plugin response under its **Response Key**. With the response key `generatedContract`, the workflow data contains:

```json theme={"dark"}
{
  "generatedContract": {
    "customId": null,
    "fileId": "{fileId}",
    "documentType": "ContractTemplate",
    "documentLabel": "GENERATED_PDF",
    "filePath": "{storage-object-path}",
    "downloadPath": "internal/files/{fileId}/download",
    "originalFileName": "ContractTemplate.pdf",
    "noOfPages": 1,
    "error": null
  }
}
```

`customId` holds the **Folder** value, and is `null` when **Folder** is empty. The response also carries `minioPath`, which is deprecated: use `filePath` instead. `filePath` is the object path in file storage, not a URL.

If generation fails, the node run fails. The Documents plugin error is returned under the response key, or, when the node can't reach the plugin, the output holds an `error` message and an `errorType`.

### Build the URL in the workflow

SaaS · 5.10

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.10.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Add a Script node after the Template Filling node and prefix `downloadPath`:

```javascript theme={"dark"}
var downloadPath = input.generatedContract.downloadPath;

if (downloadPath != null) {
  output.contractUrl = "https://{your-flowx-api-host}/document/" + downloadPath;
}
```

Return `contractUrl` in the End node output, then map it into process data in the process that started the workflow. For the round trip from process to workflow and back, see [Call an external API from a process](/5.9/cookbooks/call-external-api).

### Build the URL in a process

On self-hosted FlowX.AI 5.9.x and 5.1.x, you generate documents from a process through the Documents plugin, and the reply carries the same `downloadPath`. Build the complete URL in a business rule:

* **5.9.x**: see [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates) for the request and reply, and [Preview an uploaded file](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#preview-an-uploaded-file) for the business rule.
* **5.1.x**: see [Generating documents](/5.1/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates) and [Creating and uploading a new document](/5.1/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document) for the same business rule.

> [!TIP]
>
> On SaaS with FlowX.AI 5.13, File Preview doesn't need the complete URL: set its **Source** to **Document Plugin Path** and point it at `downloadPath` directly. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13).

> [!NOTE]
>
> The download endpoint requires authentication. The FlowX renderer recognizes a Documents plugin download by the URL ending in `download`, which is how `downloadPath` ends, and fetches it with the user's token. A plain browser link to the same URL has no token and is rejected. For linking to a stored file from a **File download** component, see [File download](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download).

***

## Related resources

> [card] [Template Filling node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node)
>
> Every field of the Template Filling node.

> [card] [Script node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#script-node)
>
> How Script node output merges into workflow data.

> [card] [Managing templates](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/managing-html-templates)
>
> Create document templates and define their data model.

> [card] [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates)
>
> Generate documents from a process through the Documents plugin.


# Reconcile supplier invoices against purchase orders
Source: https://docs.flowx.ai/5.9/cookbooks/invoice-reconciliation

Receive supplier invoices by email, extract them with AI, match each one against its purchase order in a FlowX Database, approve clean matches automatically, and route every exception to a reviewer.

Tested · September 2026

> [!TIP]
>
> **Built and run by the FlowX docs team on a live FlowX environment.** Both sample invoices ran end to end from a mock email: matching invoices were approved automatically, and mismatched invoices opened a review task, which a reviewer completed.

Accounts payable (AP) teams in logistics check every carrier invoice against the purchase order (PO) it bills: same vendor, same currency, the agreed rates, no extra lines. Most invoices match and only need a signature. The ones that don't are why the check exists. This cookbook automates the matching and keeps a person in the loop only for the exceptions.

You build a pipeline for two fictional carriers, Acme Freight SRL and Northwind Haulage Ltd. An invoice arrives as a PDF attachment, AI extracts it into structured data, a script compares it with the PO stored in a FlowX Database, and the process either approves it automatically or opens a review task that lists every difference it found.

> [!NOTE]
>
> **Prerequisites**: a project in your workspace, access to FlowX.AI Designer, and the AI platform turned on for your environment (the workflow uses the **Document Extraction** node). To receive real invoices you also need an IMAP mailbox. You can build and test everything without one: the workflow runs on uploaded test files and the process accepts mock email content. If integration workflows are new to you, start with [Call an external API from a process](./call-external-api), which covers the send, workflow, receive round trip this cookbook builds on.

***

## The pattern

Two halves, joined by one workflow call:

1. A **FlowX Database** holds the approved purchase orders that invoices are matched against.
2. An **integration workflow** does the matching: it extracts the invoice, looks up its PO, and returns `MATCHED` or `EXCEPTION` together with the list of reasons. It never decides anything a person should decide.
3. A **process** owns the business flow: an **Email Trigger** starts it for each invoice email, it hands the attachment to the workflow, and it routes the result either to automatic approval or to a reviewer.

Keeping the matching in the workflow means you can test it on sample PDFs in isolation, long before a mailbox is connected.

![The invoiceIntake process in the Accounts payable swimlane: Invoice email received, Pick invoice attachment, Reconcile invoice, Receive reconciliation, Summarize exceptions, the Matched? gateway, and the two outcomes Approved automatically and Review exception](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-process-canvas.png)

***

## Step 1: Store the purchase orders

**1. Model a purchase order**

In your project, create two data types:

| Data type | Attribute | Type |
| - | - | - |
| `PurchaseOrderLine` | `description` | String |
| | `quantity` | Number |
| | `unitPrice` | Number |
| `PurchaseOrder` | `poNumber` | String |
| | `vendorName` | String |
| | `currency` | String |
| | `subtotal` | Number |
| | `status` | String |
| | `lines` | Array of `PurchaseOrderLine` |

**2. Create the FlowX Database**

Go to **Integrations** → **Data Sources**, add a **FlowX Database** named `PurchaseOrders`, and select `PurchaseOrder` as its schema. Keep the default partition key `_id`.

**3. Add a lookup operation**

Add a **FindOne** operation named `findPurchaseOrder` with one String parameter, `poNumber`, and this filter:

```json theme={"dark"}
{"poNumber": "${poNumber}"}
```

![The findPurchaseOrder FindOne operation of the PurchaseOrders database: a poNumber String parameter on the left and a filter on poNumber that uses that parameter under Query Arguments on the right](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-db-operation.png)

**4. Load sample purchase orders**

Add an **InsertMany** operation named `insertPurchaseOrders` with an Object parameter `orders` and the payload `${orders}`. Then create a run-once workflow, `seedPurchaseOrders`: a **Script** node that builds the orders, followed by a **Data Source** node that calls `insertPurchaseOrders` with `orders` bound to `${orders}`.

```javascript theme={"dark"}
output.orders = [
  {
    poNumber: "PO-4501",
    vendorName: "Acme Freight SRL",
    currency: "EUR",
    subtotal: 2035.00,
    status: "OPEN",
    lines: [
      { description: "Road freight FTL Bucharest - Vienna", quantity: 1, unitPrice: 1850.00 },
      { description: "Fuel surcharge", quantity: 1, unitPrice: 185.00 }
    ]
  },
  {
    poNumber: "PO-4502",
    vendorName: "Northwind Haulage Ltd",
    currency: "EUR",
    subtotal: 730.00,
    status: "OPEN",
    lines: [
      { description: "Container handling, 40 ft", quantity: 4, unitPrice: 120.00 },
      { description: "Customs clearance", quantity: 1, unitPrice: 250.00 }
    ]
  },
  {
    poNumber: "PO-4503",
    vendorName: "Acme Freight SRL",
    currency: "EUR",
    subtotal: 3200.00,
    status: "OPEN",
    lines: [
      { description: "Road freight FTL Constanta - Budapest", quantity: 2, unitPrice: 1600.00 }
    ]
  }
];
```

Run the workflow once, then check the **Documents** tab of `PurchaseOrders`: it lists the three orders. In a real deployment, your ERP feeds this collection instead.

For the other operation types and how their parameters bind in workflows, see [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database).

***

## Step 2: Extract the invoice

Create a workflow named `reconcileInvoice`. It takes one input, the path of the invoice file in the Document Plugin, and returns the reconciliation result.

![The reconcileInvoice workflow canvas: Start with a filePath start payload, Extract invoice data, Parse invoice, Find purchase order, Compare to purchase order, and End with the reconciliation output schema, plus an End failure node on the failure branches](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-workflow-canvas.png)

**1. Declare the input**

In the workflow's data model, add a String attribute `filePath` and declare it as the Start node's input parameter.

**2. Add the Document Extraction node**

Add a **Document Extraction** node named `Extract invoice data` after Start:

* **Presets**: **Metadata Generation**, then replace the prefilled instructions with the ones below
* **Document Source**: **Document Plugin**
* **File Path**: `${filePath}`
* **Response Key**: `invoice`

**Instructions:**

```text theme={"dark"}
You extract data from a supplier invoice for accounts payable.

Return only values printed on the document. Do not calculate, infer, or correct anything.
- invoiceNumber, poNumber: copy exactly as printed, including prefixes such as "PO-".
- vendorName: the legal name of the company issuing the invoice, not the bill-to party.
- currency: the ISO 4217 code, for example EUR.
- subtotal: the amount before VAT, as a number without thousands separators.
- lines: one entry per invoice line, with quantity and unitPrice as numbers.
If a value is not on the document, return null for it.
```

**Response Schema:**

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "invoiceNumber": { "type": "string" },
    "invoiceDate": { "type": "string" },
    "poNumber": { "type": "string" },
    "vendorName": { "type": "string" },
    "currency": { "type": "string" },
    "subtotal": { "type": "number" },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "quantity": { "type": "number" },
          "unitPrice": { "type": "number" }
        }
      }
    }
  }
}
```

![The Extract invoice data node: the accounts payable instructions, Document Source set to Document Plugin, Use Test File off, and File Path set to the filePath workflow input](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-extraction-node.png)

**3. Branch the failure path**

Connect the node's failure branch to an **End** node named `End failure`. An unreadable file or a model error then ends the run visibly instead of passing empty data downstream.

> [!TIP]
>
> The instructions ask for values **as printed** and forbid calculation. Matching is the script's job: a model that "helpfully" corrects a wrong subtotal hides exactly the discrepancy AP needs to see.

***

## Step 3: Match the invoice against its purchase order

**1. Parse the extraction result**

Add a **Script** node named `Parse invoice` on the extraction node's success branch. Document Extraction returns its answer as a JSON **string** in `responseObjects[0]`, so parse it and copy the fields into a plain object:

```javascript theme={"dark"}
// Document Extraction returns its answer as a JSON string
var parsed = JSON.parse(input.invoice.responseObjects[0]);

var lines = [];
var src = parsed.lines || [];
for (var i = 0; i < src.length; i++) {
  lines.push({
    description: src[i].description,
    quantity: Number(src[i].quantity),
    unitPrice: Number(src[i].unitPrice)
  });
}

output.invoiceData = {
  invoiceNumber: parsed.invoiceNumber,
  poNumber: parsed.poNumber,
  vendorName: parsed.vendorName,
  currency: parsed.currency,
  subtotal: Number(parsed.subtotal),
  lines: lines
};

// The raw extraction is no longer needed downstream: null clears it, {} would not
output.invoice = null;
```

**2. Look up the purchase order**

Add a **Data Source** node named `Find purchase order`. Select the `PurchaseOrders` database and the `findPurchaseOrder` operation, set the `poNumber` parameter to `${invoiceData.poNumber}`, and set **Response Key** to `purchaseOrder`. Connect its failure branch to `End failure`.

![The Find purchase order node: FlowX Database, the findPurchaseOrder findOne operation, the poNumber parameter set to the extracted invoiceData.poNumber, and the Response Key purchaseOrder](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-find-po-node.png)

A FindOne result lands one level down, at `purchaseOrder.data`.

**3. Compare invoice and PO**

Add a **Script** node named `Compare to purchase order`. It checks the PO's status, vendor, currency, subtotal, and every invoice line, and collects one readable message per difference:

```javascript theme={"dark"}
var TOLERANCE = 0.02; // accept up to 2% difference on amounts

function round2(n) { return Math.round(n * 100) / 100; }
function norm(s) { return String(s || "").toLowerCase().trim(); }
function num(n) { var v = Number(n); return isNaN(v) ? 0 : v; }

var inv = input.invoiceData;
var po = input.purchaseOrder ? input.purchaseOrder.data : null;
var exceptions = [];
// Every declared output needs a value, so amounts default to 0 instead of null
var invoiceSubtotal = num(inv.subtotal);
var poSubtotal = 0;
var variance = 0;

if (!po || !po.poNumber) {
  exceptions.push("No purchase order found for " + (inv.poNumber || "an invoice without a PO number"));
} else {
  poSubtotal = num(po.subtotal);
  variance = round2(invoiceSubtotal - poSubtotal);

  if (po.status !== "OPEN") {
    exceptions.push("Purchase order " + po.poNumber + " is " + po.status);
  }
  if (norm(po.vendorName) !== norm(inv.vendorName)) {
    exceptions.push("Vendor mismatch: invoice from " + inv.vendorName + ", PO issued to " + po.vendorName);
  }
  if (po.currency !== inv.currency) {
    exceptions.push("Currency mismatch: invoice in " + inv.currency + ", PO in " + po.currency);
  }
  if (Math.abs(variance) > poSubtotal * TOLERANCE) {
    exceptions.push("Subtotal differs from PO by " + variance + " " + inv.currency);
  }

  // Line check: each invoice line must match a PO line on description, quantity, and unit price
  var poLines = po.lines || [];
  var invLines = inv.lines || [];
  for (var i = 0; i < invLines.length; i++) {
    var line = invLines[i];
    var match = null;
    for (var j = 0; j < poLines.length; j++) {
      if (norm(line.description).indexOf(norm(poLines[j].description)) === 0) { match = poLines[j]; break; }
    }
    if (!match) {
      exceptions.push("Line not on PO: " + line.description);
      continue;
    }
    var poPrice = num(match.unitPrice);
    if (Math.abs(num(line.unitPrice) - poPrice) > poPrice * TOLERANCE) {
      exceptions.push("Unit price for " + match.description + ": invoiced " + line.unitPrice + ", PO " + poPrice);
    }
    if (num(line.quantity) > num(match.quantity)) {
      exceptions.push("Quantity for " + match.description + ": invoiced " + line.quantity + ", PO " + match.quantity);
    }
  }
}

output.reconciliation = {
  status: exceptions.length === 0 ? "MATCHED" : "EXCEPTION",
  invoiceNumber: inv.invoiceNumber || "",
  poNumber: inv.poNumber || "",
  vendorName: inv.vendorName || "",
  currency: inv.currency || "",
  invoiceSubtotal: invoiceSubtotal,
  poSubtotal: poSubtotal,
  variance: variance,
  exceptions: exceptions
};

// Last consumer of these keys: set them to null so they don't ride along in the token
output.purchaseOrder = null;
output.invoiceData = null;
```

A line matches a PO line when its description **starts with** the PO line's description, so a carrier that prints `Road freight FTL Bucharest - Vienna, 13.6 m trailer` still matches the PO line `Road freight FTL Bucharest - Vienna`.

**4. Declare the output**

In the workflow's data model, add an object `reconciliation` with `status`, `invoiceNumber`, `poNumber`, `vendorName`, and `currency` (String), `invoiceSubtotal`, `poSubtotal`, and `variance` (Number), and `exceptions` (Array of String). Declare it as the output of the success **End** node.

![The workflow's Output Parameters tab with the End node selected and the reconciliation object with its nine attributes declared as the output schema](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-output-params.png)

> [!WARNING]
>
> Declared output parameters are a runtime contract: a parameter that resolves to no value when the run reaches the End node fails the run. That is why the Compare script defaults every field to `""` or `0` instead of `null`, including when no PO is found. See [mandatory output parameters missing](/5.9/docs/resources/error-glossary#the-mandatory-output-parameters-of-the-workflow-are-missing-at-runtime).

> [!NOTE]
>
> Script nodes receive workflow data as Java-backed objects, not plain JavaScript. Both scripts read fields one by one and loop with an index instead of calling `.map()` or `JSON.stringify()` on their input, and they only put plain objects in `output`. Setting `invoice`, `purchaseOrder`, and `invoiceData` to `null` once they are consumed keeps the data that travels between nodes small.
>
> Use `null`, not `{}`, to clear a key. Script node output is deep-merged into the existing workflow data, the same way business rule output is merged into process data, so writing an empty object over an existing object leaves that object unchanged. See [how output is merged into process data](/5.9/docs/building-blocks/supported-scripts#how-output-is-merged-into-process-data).

***

## Step 4: Test the workflow on sample invoices

Create two PDF invoices to test with. Any tool that prints a PDF works; what matters is the content:

| | Matched invoice | Exception invoice |
| - | - | - |
| **Issued by** | Acme Freight SRL | Northwind Haulage Ltd |
| **Invoice number** | `AF-2026-0917` | `NH-3310` |
| **PO number** | `PO-4501` | `PO-4502` |
| **Lines** | Road freight FTL Bucharest - Vienna, 13.6 m trailer: 1 × 1,850.00 Fuel surcharge: 1 × 185.00 | Container handling, 40 ft: 4 × 135.00 Customs clearance: 1 × 250.00 |
| **Subtotal** | EUR 2,035.00 | EUR 790.00 |

On the extraction node, turn on **Use Test File**, attach a sample invoice, and click **Run Workflow**. The run details show each node's input and output. The two invoices produce:

| Invoice | `status` | `variance` | `exceptions` |
| - | - | - | - |
| Acme Freight `AF-2026-0917` | `MATCHED` | `0` | none |
| Northwind Haulage `NH-3310` | `EXCEPTION` | `60` | `Subtotal differs from PO by 60 EUR` `Unit price for Container handling, 40 ft: invoiced 135, PO 120` |

The Northwind invoice bills container handling at 135.00 against an agreed 120.00, which is 12.5% above the rate and well past the 2% tolerance.

> [!WARNING]
>
> Turn **Use Test File** off again before you connect the process. With it on, the node ignores `${filePath}` and extracts the test file on every run.

***

## Step 5: Receive invoices by email

**1. Create the Email Trigger**

Go to **Integrations** → **Data Sources** and add an **Email Trigger** named `Invoice mailbox`. Enter the IMAP connection of your AP mailbox. Reference the host, user, and password as configuration parameters (`${configParam}`) instead of typing them in, so each environment uses its own mailbox and the password never sits in the project.

Under the filtering criteria, set:

* **Start Process/Workflow for**: **Only emails with these attachment file types**, `.pdf`
* **Save email attachments on process/workflow**: **Only these attachment file types**, `.pdf`

Emails without a PDF are then rejected and listed under **Failed Triggers**, and a signature image or logo attached next to the invoice never reaches the process.

![The Invoice mailbox Email Trigger: IMAP connection fields referencing configuration parameters on the left, and the filtering criteria on the right with INBOX as the folder and both the start condition and the attachment forwarding limited to .pdf](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-trigger-settings.png)

**2. Start the process from the trigger**

Create a process named `invoiceIntake` with a swimlane named `Accounts payable`. Its start node is a **Message Start Event** named `Invoice email received`. In its node config, set **Trigger Type** to **Email Trigger** and select `Invoice mailbox`.

![The Invoice email received node config: Trigger Type set to Email Trigger and Invoice mailbox selected, with the hint that Email Triggers can be activated from Manage Triggers in Runtime](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-start-event.png)

Each accepted email starts one process instance. Before the first node runs, the platform stores the attachments in the Document Plugin and adds them to the instance data at `emailMessage.fileAttachments`, one entry per file with its `filePath`. For the full email schema, see [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger#email-data-schema).

***

## Step 6: Hand the invoice to the workflow

**1. Pick the attachment**

Add a **Service Task** named `Pick invoice attachment` with a business rule action:

```javascript theme={"dark"}
// The reconciliation workflow takes one file path: pass the first attachment's path as a plain key
var attachments = input.emailMessage ? input.emailMessage.fileAttachments : null;
var path = "";
if (attachments != null && attachments.length > 0) {
  path = attachments[0].filePath;
}
output.invoice = { filePath: path };
```

The trigger forwards PDFs only, so the first attachment is the invoice. If your suppliers send several invoices in one email, start the workflow once per attachment instead.

**2. Start the workflow**

Add a **Send Message Task** named `Reconcile invoice` with a **Start Integration Workflow** action. Select `reconcileInvoice` and map its `filePath` input to `${invoice.filePath}`.

![The data mapping modal for the reconcileInvoice Start node: the invoice.filePath process attribute mapped to the workflow's filePath input](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-input-mapping.png)

**3. Receive the result**

Add a **Receive Message Task** named `Receive reconciliation`. Add a data stream with **Source** set to **Workflow**, select `reconcileInvoice`, and in the **Output Mapping** of its success End node map each of the nine `reconciliation` fields to the process attribute of the same name. Click **Update**, then save the node.

![The data mapping modal for the workflow's End node: the nine reconciliation fields, from status to exceptions, each mapped to the matching reconciliation process attribute](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-output-mapping.png)

For how data streams and mapping modes work, see [Send and Receive Message Tasks](/5.9/docs/building-blocks/node/message-send-received-task-node).

***

## Step 7: Route exceptions to a reviewer

**1. Summarize the exceptions**

Add a **Service Task** named `Summarize exceptions` with a business rule that joins the list into one block of text the review form can show:

```javascript theme={"dark"}
// Join the exception list into one line for the reviewer's form
var list = input.reconciliation.exceptions;
var parts = [];
if (list != null) {
  for (var i = 0; i < list.length; i++) { parts.push(list[i]); }
}
var rec = input.reconciliation;
rec.exceptionSummary = parts.join("\n");
output.reconciliation = rec;
```

**2. Branch on the result**

Add an **Exclusive Gateway** named `Matched?`. Send the flow to an **End** node named `Approved automatically` when `input.reconciliation.status == "MATCHED"`, and to a **User Task** named `Review exception` otherwise.

**3. Build the review form**

Place `Review exception` in a navigation area (for example a **Page** named `Invoice review`), then open its UI and add a **Card** titled `Review invoice exception` that holds a **Form** with:

| Component | Key | Label |
| - | - | - |
| Input | `reconciliation.invoiceNumber` | Invoice number |
| Input | `reconciliation.poNumber` | Purchase order |
| Input | `reconciliation.vendorName` | Vendor |
| Input | `reconciliation.currency` | Currency |
| Input (number) | `reconciliation.invoiceSubtotal` | Invoice subtotal |
| Input (number) | `reconciliation.poSubtotal` | PO subtotal |
| Text Area | `reconciliation.exceptionSummary` | Exceptions |
| Radio | `review.decision` | Decision: **Approve for payment** or **Reject and return to vendor** |
| Text Area | `review.comment` | Comment |

Add a **Submit review** button that runs the user task's `saveData` action, and connect the task to an **End** node named `Review complete`.

![The Review exception user task in the UI Designer, inside the Invoice review navigation page: the invoice and PO fields, the Exceptions text area, the Decision radio with Approve for payment and Reject and return to vendor, a Comment field, and the Submit review button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-user-task.png)

> [!WARNING]
>
> A user task outside a navigation area doesn't render at runtime. Designer flags it on the node: "The Node is not included in a Navigation Area and will not be rendered properly." See [Navigation areas](/5.9/docs/building-blocks/process/navigation-areas).

> [!TIP]
>
> The reviewer sees the invoice and PO values side by side with every difference already spelled out, so the decision takes seconds. To act on it, add the next step after `Review exception`: post approved invoices to your ERP, or send the rejection and the reviewer's comment back to the vendor with a [Send Notification action](/5.9/docs/building-blocks/actions/send-notification-action).

***

## Step 8: Run it end to end

**1. Test with mock email content**

Start `invoiceIntake` with mock email content instead of a real email: fill in a subject, a sender, and a body, and upload the Northwind sample invoice. See [Testing with mock email content](/5.9/docs/platform-deep-dive/integrations/email-trigger#testing-with-mock-email-content).

![The Start Process dialog with mock email content: an invoice subject, a sender at northwind-haulage.example, a short body, and the uploaded Northwind invoice PDF](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-mock-email.png)

**2. Review the exception**

The instance stops at `Review exception` with both differences listed. Choose a decision, add a comment, and click **Submit review**. The instance finishes at `Review complete`.

![The Review invoice exception task at runtime for invoice NH-3310 from Northwind Haulage Ltd against PO-4502: EUR, invoice subtotal 790, PO subtotal 730, the two exceptions listed, the Decision radio, an empty Comment field, and the Submit review button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/cb-invoice-review-task.png)

**3. Watch a clean match pass**

Start a second instance with the Acme Freight invoice. It passes the gateway and finishes at `Approved automatically` without creating a task.

**4. Go live**

Activate `Invoice mailbox` from **Manage Triggers** in **Runtime Settings**. From then on, each PDF invoice that arrives in the mailbox starts an instance.

> [!TIP]
>
> You built an AP pipeline that reads invoices from a mailbox, extracts them with AI, matches them against purchase orders in a FlowX Database, approves clean matches on its own, and sends each exception to a person with the reasons attached.

***

## Adapt the matching rules

The Compare script is the one place where AP policy lives. Common changes:

* **Tolerance**: `TOLERANCE = 0.02` accepts a 2% difference on the subtotal and on unit prices. Set it to `0` for exact matching, or split it into separate rate and total tolerances.
* **Partial deliveries**: the quantity check only flags invoiced quantities *above* the PO. To bill against the remaining PO balance, store the quantity invoiced so far on each PO line and compare against the balance.
* **Duplicate invoices**: add a FlowX Database of processed invoice numbers, look it up before the comparison, and raise an exception when the vendor has billed the same number before.
* **Line matching**: prefix matching on descriptions suits carriers that append details. When suppliers print item codes, add a `code` attribute to `PurchaseOrderLine` and match on it instead.

***

## When it fails

| Symptom | Likely cause | Where to look |
| - | - | - |
| Every invoice gets `No purchase order found for ...` | The invoice prints the PO number differently from the database, for example `4502` instead of `PO-4502`. | The `Parse invoice` output in the workflow run details. Normalize the number there, or adjust the extraction instructions. |
| Lines are reported as `Line not on PO` although they are | The printed description doesn't start with the PO line's description. | The Compare script's line matching. See [Adapt the matching rules](#adapt-the-matching-rules). |
| `vendorName` holds your own company's name | The model read the bill-to party. | The extraction instructions, which ask for the issuing company. Make the rule stricter for your invoice layouts. |
| `The mandatory output parameters of the workflow are missing at runtime.` | A declared output field resolved to no value. | [Glossary entry](/5.9/docs/resources/error-glossary#the-mandatory-output-parameters-of-the-workflow-are-missing-at-runtime). Default every output field in the Compare script. |
| An email doesn't start an instance | The trigger isn't active, or the email has no PDF attachment. | **Manage Triggers** and **Failed Triggers**, see [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger#handling-failed-triggers). |
| The review task doesn't render | `Review exception` isn't in a navigation area. | The node's navigation area in the process UI. |

> [!WARNING]
>
> A failed workflow reply is **not retried**. An instance whose reconciliation failed stays at `Receive reconciliation`. After fixing the configuration, test with a new process instance.

***

## Related resources

> [card] [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger)
>
> Connection settings, filtering criteria, the email data schema, and mock email testing.

> [card] [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database)
>
> Operations, parameters, and how Data Source nodes bind them in workflows.

> [card] [AI comparison and reconciliation](/5.9/ai-platform/patterns/ai-comparison-reconciliation)
>
> The general pattern behind this cookbook, and when to compare with AI instead of rules.

> [card] [Document processing tutorial](/5.9/ai-platform/tutorials/document-processing)
>
> Classify and extract several document types in one flow.


# Cookbooks
Source: https://docs.flowx.ai/5.9/cookbooks/overview

Hands-on tutorials, guides, and reusable patterns for building on FlowX.AI, from your first process to production-grade AI apps.

Cookbooks · FlowX.AI

Learn by building.
Recipes you can ship.

Tutorials take you from an empty project to a working app. Cookbooks and guides walk through one real task end to end. AI patterns are reusable solutions you drop into your own processes and workflows.

[Build your first process](/5.9/docs/getting-started/building-your-first-proc)
[Try the invoice cookbook](/5.9/cookbooks/invoice-reconciliation)

All23

Cookbooks3

Tutorials5

Guides8

AI patterns7

Conversational AI5

Documents6

Integrations7

UI2

[CookbookDocument AIIntegrations
Reconcile supplier invoices against purchase orders
Receive invoices by email, extract them with AI, match each one against its purchase order in a FlowX Database, and send only the exceptions to a reviewer.](/5.9/cookbooks/invoice-reconciliation)

[CookbookIntegrations
Call an external API from a process
The send, workflow, receive round trip end to end: a REST data source, an integration workflow, and the output mapped back into process data - including what each failure looks like.](/5.9/cookbooks/call-external-api)

[CookbookDocuments
Generate and download a document from a workflow
Map a Script node's output into the Template Filling node, fix a node with no mapping options, and build the download URL.](/5.9/cookbooks/generate-and-download-a-document)

[TutorialConversational AIRAG
Mortgage advisor chatbot
A conversational AI advisor with session memory, intent routing, a knowledge base, and hybrid AI plus business rule recommendations.](/5.9/ai-platform/tutorials/mortgage-advisor)

[TutorialDocument AI
Document processing pipeline
An AI-powered verification pipeline that classifies uploaded documents, extracts structured data, and reconciles it against application data.](/5.9/ai-platform/tutorials/document-processing)

[TutorialProcess automation
Customer onboarding with KYC
A multi-step onboarding process with identity verification, document generation, manual review routing, and email notifications.](/5.9/ai-platform/tutorials/customer-onboarding)

[TutorialProcess automationBasics
Build your first process
Start from zero: model a BPMN process, design its UI, and run it. The foundation every other cookbook builds on.](/5.9/docs/getting-started/building-your-first-proc)

[TutorialIntegrationsBasics
Build your first workflow
Connect an external REST API through a data source, build an integration workflow around it, and call it from a process.](/5.9/docs/getting-started/building-your-first-workflow)

[GuideConversational AI
Chat-driven workflows
Build multi-turn, AI-powered chat experiences with session memory, intent routing, and context-aware responses.](/5.9/ai-platform/chat-driven-workflows)

[GuideIntegrations
Trigger processes with webhooks
Start FlowX processes when an external system sends an HTTP POST. Secured with API keys, event-driven, no polling.](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)

[GuideIntegrations
Start processes from email
Connect an IMAP mailbox and automatically start process instances when emails arrive.](/5.9/docs/platform-deep-dive/integrations/email-trigger)

[GuideIntegrations
Read and send email with Outlook
Connect Microsoft Outlook via the MS Graph API and Azure AD to read and send emails from your processes.](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)

[GuideIntegrationsData
Store data with FlowX Database
Store and access structured data across processes and apps, without standing up an external database.](/5.9/docs/platform-deep-dive/integrations/flowx-database)

[GuideDocuments
Generate documents from templates
Generate documents from custom templates, pre-filled with data from the current process instance.](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates)

[GuideUI
Build a custom UI component
Create custom React components that integrate with FlowX process data and actions, extending the built-in palette.](/5.9/docs/building-blocks/reusable-resources/custom-components)

[GuideUIBasics
Create a user interface
Design and configure the UI for a process flow with the UI Designer: layout, form components, and navigation.](/5.9/docs/flowx-designer/managing-a-project-flow/creating-a-user-interface)

[AI patternAgents
Agent typologies
The nine recurring agent archetypes behind the FlowX.AI agent catalog, and the nodes you combine to build each one.](/5.9/ai-platform/patterns/agent-typologies)

[PatternConversational AI
Intent classification and routing
Classify user input into intent categories and route each one to a specialized handler.](/5.9/ai-platform/patterns/intent-classification-routing)

[PatternConversational AIRAG
Knowledge base RAG
Ground AI responses in your documents using retrieval-augmented generation with vector search.](/5.9/ai-platform/patterns/knowledge-base-rag)

[PatternDocument AI
Fan-out extraction
Classify documents by type, then route each to a specialized extraction node with tailored prompts and schemas.](/5.9/ai-platform/patterns/fan-out-extraction)

[PatternDocument AI
AI comparison and reconciliation
Compare AI-extracted document data against system-of-record values and generate structured exception reports.](/5.9/ai-platform/patterns/ai-comparison-reconciliation)

[PatternDecisioning
Hybrid AI + business rules
Combine AI extraction and understanding with deterministic business logic for auditable, explainable decisions.](/5.9/ai-platform/patterns/hybrid-ai-rules)

[PatternConversational AI
Session state management
Manage conversation history and session state across multi-turn interactions using FlowX Database workflows.](/5.9/ai-platform/patterns/session-state-management)

Browse by section:
[Tutorials](/5.9/ai-platform/tutorials/overview)
[AI patterns](/5.9/ai-platform/patterns/overview)
[What shipped recently](/release-notes/overview)


# Deployment guidelines v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/deployment-guidelines-v4.6.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.0 FlowX.AI release, you cannot import old process definitions or resources into the new platform from older versions .

## Component versions

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.0.2** | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.3** | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.1.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.0** | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.0.3** | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.0.3** | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | **4.1.3** | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | **7.0.3** | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.0** | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.0** | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.1.12** | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.0** | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.1** | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.0.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.3** | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.9** | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.10** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.9** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.3** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.24** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.5.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.0 | Keycloak | 22.x |
| 4.6.0 | Kafka | 3.2.x |
| 4.6.0 | PostgreSQL | 16.2.x |
| 4.6.0 | MongoDB | 7.0.x |
| 4.6.0 | Redis | 7.2.x |
| 4.6.0 | Elasticsearch | 7.17.x |
| 4.6.0 | Oracle Database | 21C/ 21-XE |
| 4.6.0 | Angular (Web SDK) | 19.x |
| 4.6.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

## New microservices - setup guides

> [card] [Application-manager](/4.7.x/setup-guides/application-manager)

> [card] [Runtime-manager](/4.7.x/setup-guides/runtime-manager)

> [card] [Integration Designer](/4.7.x/setup-guides/integration-designer-setup)

> [card] [Data-sync job](/4.7.x/setup-guides/data-sync)

## New access rights and roles

> [card] [Integration Designer access rights](/4.7.x/setup-guides/access-management/configuring-access-rights-for-integration-designer)

> [card] [Application Manager access rights](/4.7.x/setup-guides/access-management/app-manager-access-rights)

## Updated access rights and roles

> [card] [Task Manager access rights](/4.7.x/setup-guides/plugins-access-rights/configuring-access-rights-for-task-management)
>
> Added new roles for **manage-views**.

## New service accounts

> [card] [Runtime manager service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#runtime-manager-service-account)

> [card] [Integration Designer service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#integration-designer-service-account)


# Deployment changes for v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x

This document outlines the configuration and infrastructure changes introduced from v4.1.x to v4.6.0 for deploying the FlowX.AI platform.

## CMS Setup

### MongoDB configuration

In version 4.6.0, the CMS setup includes a more comprehensive MongoDB configuration, especially for runtime data handling:

* **Runtime MongoDB Instance**: A dedicated MongoDB instance for managing runtime data.
  * **New Environment Variables**:
    * `RUNTIME_DB_USERNAME`: Username for runtime MongoDB access.
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: Connection URI for the runtime MongoDB instance.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`). Default is `mongodb`.
  * **Transaction Settings for Mongock Library**:
    * `MONGOCK_TRANSACTIONENABLED`: Controls MongoDB transaction support with Mongock, defaulting to `false` due to compatibility concerns with MongoDB 5.

### Private storage configuration

Private CMS to securely store uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints. This CMS will support AI services and workflows while maintaining strict access controls.

> [!NOTE]
>
> Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from project builds as they aren't needed at runtime.

* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL`: This environment variable specifies the URL of the S3 server used for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME`: This environment variable specifies the name of the S3 bucket dedicated to private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET`: This environment variable indicates whether the private S3 bucket should be created if it does not already exist. It can be set to true or false.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY`: This environment variable holds the access key used to authenticate to the S3 server for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY`: This environment variable holds the secret key used to authenticate to the S3 server for private file storage.

> [card] [CMS setup guide](/4.7.x/setup-guides/cms-setup)

***

## Admin setup

### MongoDB configuration

Version 4.6.0 introduces a new MongoDB setup in the Admin service for managing data model information:

* **New MongoDB Data Model Configuration**:
  * **Environment Variables**:
    * `SPRING_DATA_MONGODB_URI`: URI for connecting to the MongoDB data model instance.
    * `DB_USERNAME`: Set to `data-model` for data model access.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`).

***

## Engine setup

### MongoDB configuration

The Engine configuration now includes additional setup for a runtime MongoDB instance to manage runtime builds:

* **Runtime MongoDB for Engine**:
  * **New Environment Variables**:
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: URI for connecting to the runtime MongoDB.
    * `DB_USERNAME`: Set to `app-runtime` for runtime data access.


# Configuration and migration guide
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/process-configuration

This guide outlines changes in process and UI configuration from v4.1.x to 4.6.0 version.

## Projects

The **Projects** feature in FlowX AI v4.6.0 is a new structure that organizes all dependencies and resources required for a project into a single deployable view. This enhancement simplifies configuration, deployment, and maintenance by layering projects on top of processes, offering a centralized workspace that encapsulates everything needed for project execution.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)

Several key configuration changes impact how resources and dependencies are managed, deployed, and maintained. This guide provides a breakdown of the configuration changes, automatic migration processes, and manual steps required to ensure a smooth transition.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)

***

### Consolidated resource management

* **Change**: All resources that were previously managed individually within processes are now grouped within Projects. This includes content management elements, integrations, themes, task configurations, and permissions.
* **Impact**: Resources like **enumerations**, **substitution tags**, and **generic parameters** are now managed within Projects, allowing centralized configuration and version control.
* **Migration**: All process-related resources will be migrated automatically into a **default project**, ensuring continuity of functionality in the new framework. After migration, you should verify that all critical resources are correctly configured within this default project.

> [card] [What are resources?](/4.7.x/docs/projects/resources)

### Enhanced version control and dependency management

* **Impact**: Projects support **dependency management** through **Libraries** and enforce version-controlled resources. Setting up a project now requires careful dependency management and versioning to prevent unintended updates.
* **Benefit**: Allows for modular, reusable resources and stable deployments across projects, reducing resource duplication and enhancing project compatibility.

### Migration checklist

To ensure a smooth transition, complete the following steps:

1. **Verify Process Migration**: Confirm that all existing process definitions have been correctly migrated into the default project.
2. **Set Configuration Parameter Overrides**: Post-deployment, adjust environment-specific Configuration Parameters in the default project.
3. **Update Task Views**: Replace the global "All Tasks" feature with project-specific Views in each project.
4. **Transfer Processes and Dependencies Manually**: If moving a process from the default project to another project, manually transfer associated resources and re-check dependencies.

***

## Generic parameters migration

* **Overview**: In version 4.6.0, global generic parameters (from versions prior to 4.6.0) have been migrated to project-level as Configuration Parameters, consolidating parameter management within specific projects for improved organization and control.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/Screenshot%202024-11-06%20at%2019.04.49.png)

* **Migration**: All generic parameters will be automatically migrated to Configuration Parameters section under a default project.
* **Business Rules Unaffected**: There is no impact on existing business rules; they will continue to function as before without requiring updates.
* **Process Export Considerations**: If you export a process from one project to another, ensure that you also transfer the associated configuration parameters. This step is crucial to maintain process functionality and consistency across projects.
* **Important Note**: Only values of generic parameters associated with the specific environment, or where `env = null` (displayed as "all" in the interface in versions prior to 4.6.0), will be migrated. You must ensure that you have correctly set the values for generic parameters, paying attention to environment values (which are case-sensitive), and export these generic parameters before migration to avoid any potential data loss.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.39.29.png)

* **Post-Deployment Step**: After the first deployment to an upper environment, you will need to create configuration parameter overrides with the specific values required for that environment. This ensures that all environment-specific configurations are accurately maintained and applied across different deployment stages.

> [!TIP]
>
> To set configuration parameter overrides, navigate to **Your App -> Runtime -> Configuration Parameters Overrides**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.42.06.png)

***

## Source systems migration

* **Change**: Source systems have not been migrated automatically and need to be manually recreated.
* **New Location**: In v4.6.0, source systems have been moved under Integration Designer.
* Manual Migration Required:
  1. Navigate to Integration Designer.
  2. Recreate each source system manually with the same code as in the original configuration.
  3. Ensure the "Enable enumeration value mapping" checkbox is enabled.
* **Impact**: Failure to manually migrate source systems may result in broken integrations and missing data mappings.

**v4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2009.53.30.png)

**\< v.4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2010.09.12.png)

## Task management

* "All Tasks" as a View: The global "All Tasks" feature is no longer standalone and will now function as a View in a project.

**v4.6.0:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

**v4.1.x:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/all_tasks.png)

***

## General

Before starting the migration, complete the following steps:

1. **Merge All Feature Branches**: Ensure all feature branches for processes are merged into the latest version on the main branch.
2. **Remove Unnecessary Resources**: Delete any test processes or resources that are no longer needed.
3. **Export Generic Parameters**: Export generic parameters as a backup to ensure they migrate accurately to project-specific Configuration Parameters.

### Migration steps

During migration, resources will be transferred into a single **default project** with one committed version.

* **Process Definitions**: Only the last committed process version on the main branch will migrate. If no committed version exists, the latest WIP version will be used.
* **Enumerations, Substitution Tags, and Task Manager**: These resources will be migrated to the default project.
* **Generic Parameters**: Migrated as **Configuration Parameters** within the default project, covering only values where `env = null` or that match the platform’s environment setting.
* **Languages**: Language settings (available languages and default) will be moved to project settings. Languages remain globally available.

### Resources excluded from migration

Some resources will remain globally available or are deprecated:

* **Themes**
* **Fonts**
* **Global Media Library** (for media used in themes)
* **Out of Office (Task Manager)**
* **Integration Management** (will not be available in v4.6.0)

***

## Datepicker Migration

In version 4.6.0, significant updates have been introduced to the **Datepicker** component to ensure compatibility with ISO 8601 date formats and enhanced handling of date attributes within the **Data Model**. This migration affects both newly created and existing processes.

### Key changes

1. **Introduction of Date Types**:
   * **Standard Date**: Stores and displays date values in ISO 8601 format, respecting the project's locale and timezone settings.
   * **Legacy Date**: Retains previous formatting to ensure compatibility with existing business rules and processes.

2. **Properties Updates**:
   * The **Datepicker** now supports dependent properties such as `minDate`, `maxDate`, and `defaultValue`. These properties:
     * Follow the formatting rules of the selected date type (Standard or Legacy).
     * Ensure that dynamic date values pulled from the **Data Model** are displayed correctly.

3. **Backward Compatibility**:
   * **Existing Processes**: All migrated processes with legacy Datepicker components will default to `Legacy Date` type. This preserves the original formatting and ensures no disruption in business rules or workflows.
   * **New Processes**: Newly created processes will default to `Standard Date` type, saving values in ISO 8601 format.

***

### Migration process

1. **Legacy Datepickers**:

   * Automatically flagged during migration.
   * Continue to work with existing business rules.
   * Require manual review for future updates to transition to the **Standard Date** format.

2. **Business Rules Updates**:
   * Legacy Datepickers may require manual adjustments if associated business rules reference hardcoded date formats.
   * Ensure that any dynamic dates used in business rules are compatible with the ISO 8601 standard.

3. **Standard Datepickers**:
   * All new Datepicker components save date values directly in ISO 8601 format.
   * Fully compatible with updated **Data Model** attributes, allowing seamless integration with external systems, adaptors, and reporting plugins.

### Considerations

* **Default Values**:
  * For **Standard Datepickers**, the `defaultValue` must be in ISO 8601 format.
  * Dynamic defaults can also be set using **Data Model** attributes or process data.
* **Data Model Integration**:
  * All external and internal date attributes, including those used by adaptors or business rules, must be explicitly defined in the **Data Model**.
* **UI Designer Overrides**:
  * Overrides can be applied to display dates differently for specific UI elements, ensuring flexibility for localized formatting.

### Recommendations for transition

* **Existing Processes**:
  * Leave Datepicker components in `Legacy` mode unless business rules and workflows are updated to support ISO 8601.
* **New Processes**:
  * Use `Standard Date` to ensure future compatibility and alignment with ISO 8601 formatting.
* **Documentation**:
  * Review and update all timer expressions, adaptors, and external data feeds to use ISO 8601 format for consistency.

***

## Updates to expression evaluation

**What Changed:**

* A fix was implemented in the web expression evaluator regarding how string values are handled during process value replacement.
* Previously, when evaluating dynamic and computed expressions, string variables required manual insertion of double quotes (`""`) because the system did not automatically add them.
* With the recent fix, the system now **automatically adds the necessary quotes** for string replacements.

**Impact:**

* **Existing Expressions:** If your current dynamic or computed expressions include manually added quotes around string values, these might now result in redundant quotes or incorrect string formatting.
* **Behavioral Shift:** The automatic quote addition alters how string values are processed, which might affect outputs if the expressions were structured with the expectation of manual quotes.

**Action Required:**

1. **Review Your Expressions:** Check any dynamic and computed expressions in your processes that currently include manual double quotes around string values.
2. **Modify as Needed:** Remove unnecessary double quotes where the system now handles them automatically to prevent duplicate quoting or formatting issues.

***

## Export/import enumerations (CSV)

In the transition from version 4.1.x to 4.6.0, the following columns have been removed from the enum CSV export format:

* description.application
* description.draft
* contentValue.childContentDescription.application
* contentValue.childContentDescription.draft
* contentValue.childContentDescription.type

Existing CSV export/import processes should be updated to remove references to these columns to ensure compatibility with the 4.6.0 release.

***

## Post-migration recommendations

For complex projects with multiple use cases, **do not use the default project for ongoing development or production builds**. Instead:

1. **Create Branches within the Default Project**: Organize and streamline resources by creating branches. This enables a lightweight build focused on production.
2. **Split the Default Project into Smaller Projects**: Use the import/export feature to separate the default project into individual projects by use case.
   * **Note**: When importing processes into a new project, resource references may need to be manually reconfigured.

***


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/renderers

This guide assists in migrating from FlowX v4.1.x to v4.6.0.

## Android SDK migration guide

### Initialization config changes

A new configuration parameter named `locale` was added to improve formatting the dates, numbers and currencies.

When the SDK initialization happens through the `FlowxSdkApi.getInstance().init(...)` method, the argument must be included inside the `config: SdkConfig` parameter value:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().init(
    ...
    config = SdkConfig(
        baseUrl = "URL to FlowX backend",
        imageBaseUrl = "URL to FlowX CMS Media Library",
        enginePath = "some_path",
        language = "en",
        locale = Locale.getDefault(), // e.g. Locale("en", "US"), Locale("fr", "CA")
        validators = mapOf("exact_25_in_length" to { it.length == 25 }),
        enableLog = false,
    ),
    ...
)
```

### Changes when starting a Flowx process

Two new parameters were added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The id of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun startProcess(
    projectId: String,
    processName: String,
    params: JSONObject = JSONObject(),
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes when resuming a Flowx process

One new parameter was added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the continued process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes regarding the implementation of Custom Components

The support for classical **[Android View](https://developer.android.com/reference/android/view/View)** system has been dropped.\

A Custom Component can now be implemented only by using the **[Compose](https://developer.android.com/compose)** UI system.

This means that the `CustomViewComponent` is now ignored in the internals of the SDK and has been marked as `@Deprecated` and will be completely removed in the next release.

> [!NOTE]
>
> There is no immediate need to update any of the existing components.

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```kotlin theme={"dark"}
fun changeLocaleSettings(locale: Locale, language: String)
```

### Library dependencies updates

* **[Kotlin](https://kotlinlang.org/)**: 1.9.22 **↗** **1.9.24**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping)**: 2024.02.00 **↗** **2024.06.00**
* **[Compose Compiler](https://developer.android.com/jetpack/androidx/releases/compose-compiler)**: 1.5.9 **↗** **1.5.14**
* **[Gson](https://github.com/google/gson)**: 2.10.1 **↗** **2.11.0**

***

## iOS SDK migration guide

### Initialization config changes

A new configuration parameter, named `locale` was added to improve formatting the dates, numbers and currencies.

The locale needs to be set on the `FXConfig.sharedInstance.configure` method

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    config.locale = "en-US"
    ...
}
```

### Changes when starting a process

Two new parameters were added on the 3 available start process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The uuid string of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func startProcess(projectId: String, 
                  name: String, 
                  params: [String : Any]?, 
                  isModal: Bool = false, 
                  showLoader: Bool = false, 
                  completion: ((UIViewController?) -> Void)?, 
                  onProcessEnded: (() -> Void)? = nil)
```

### Changes when resuming a Flowx process

One new parameter was added on the 3 available continue process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func continueExistingProcess(uuid: String, 
                             name: String, 
                             isModal: Bool = false, 
                             completion: ((UIViewController?) -> Void)? = nil, 
                             onProcessEnded: (() -> Void)? = nil)
```

### Updated FXDataSource protocol

A new method has been added to the `FXDataSource` protocol. Update conformance to protocol by adding the implementation of the new func.

```swift theme={"dark"}
func newProcessStarted(processInstanceUuid: String) {
    
}
```

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```swift theme={"dark"}
func changeLocaleSettings(locale: String?, language: String?)
```

***

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated and will use the latest versions Angular (version 19), thus all container apps that want to use the new SDKs should first update the Angular version of the container apps.

In the following we cover the migration guide for a container app from Angular v17 to v19 and the new SDKs.

**1. Remove old packages and their explicit dependencies (required dependency packages for new sdks are bundled in the libraries so we don't need)**

* remove `material-moment-adapter` unless it is used in custom components (usually together with material datepicker) and also the `moment` package (unless used elsewhere in the project )

```bash theme={"dark"}
npm uninstall @angular/material-moment-adapter
npm uninstall moment
```

* remove old FlowX SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/ui-sdk @flowx/ui-theme @flowx/ui-toolkit 
```

* in `angular.json` remove references to old stylesheets:

```bash theme={"dark"}
"./node_modules/@flowx/ui-sdk/src/assets/scss/style.scss"
"./node_modules/paperflow-web-components/src/assets/scss"
"./node_modules/@flowx/ui-sdk/src/assets/scss"
```

* remove old FlowX SDKs explicit dependencies. Please check before removing that packages are not used in the container app or custom components.

```bash theme={"dark"}
npm uninstall date-fns event-source-polyfill inputmask ng2-pdfjs-viewer vanillajs-datepicker @ngneat/input-mask deepmerge-ts marked-mangle
```

* remove deprecated `Angular Flex` library (the new sdks don't use it anymore and the package has been deprecated by the Angular team) unless it is not used in container app or custom components

```bash theme={"dark"}
npm uninstall @angular/flex-layout
```

**2. Update container app to Angular 18**

* Make sure to have the Angular CLI installed at version 18 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@18
```

* Run the Angular update for version 18

```bash theme={"dark"}
ng update @angular/core@18 @angular/cli@18
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@18
```

or, if the container app uses Angular Material, run:

```bash theme={"dark"}
ng update @angular/material@18
```

* Optionally, if your project uses other angular packages (ex. `NgRx`) please run migrations to v18 for each of them before proceeding. You can find details on the libraries documentation pages.

* Angular has changed the default build path in the `dist` folder, it now uses a `browser` folder for the build output. To place the output of the build command directly in the `dist/[APP_NAME]` folder, add the following change in `angular.json`:

```json theme={"dark"}
{
  ...
  "architect": {
    ...
    "build": {
      ...
      "options": {
        ...
        "outputPath": {
          "base": "dist/flowx-demo-app",
          "browser": "" <-- add this line
        },
      }
    }
  }
}

```

**3. Update container app to Angular 19**

* Make sure to have the Angular CLI installed at version 19 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Run the Angular update for version 19

```bash theme={"dark"}
ng update @angular/core@19 @angular/cli@19
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@19
```

or, if the container app uses Angular material, run:

```bash theme={"dark"}
ng update @angular/material@19
```

* Optionally, if your project uses other Angular packages (ex. `NgRx`) please run migrations to v19 for each of them before proceeding. You can find details on the libraries documentation pages.

* Also, it is recommended that you update the `target` and `module` settings in the `tsconfig.json` file to the new version, although be advised that this might require additional changes in the codebase due to new compilation errors that might arise.

```json theme={"dark"}
{
  ...
  "compilerOptions": {
      ...
      "target": "ES2022",
      "module": "ES2022"
  }
}
```

**4. Install the new FlowX SDK packages**

**Adding overrides for libraries that have a dependency on Angular version \< 19**

For some libraries, the required angular version might not be up to date or compatible with the new Angular version. In this case, you can add an override in the `package.json` file to force the library to use the new Angular version.

* For example, the `ng2-pdfjs-viewer` library has a dependency on Angular version 18 and will not work with the installed Angular version 19. To force the library to use the new Angular version, add the following override in the `package.json` file:

```json theme={"dark"}
{
  ...
  "overrides": {
    "ng2-pdfjs-viewer": {
      "@angular/common": "^19.0.0",
      "@angular/core": "^19.0.0",
      "ng-packagr": "^19.0.0"
    }
  }
}
```

**Install new packages**:

> [!WARNING]
>
> **ACTION REQUIRED**: Update to the latest version 4.6 to ensure optimal performance and compatibility.

```bash theme={"dark"}
npm install @flowx/core-sdk@5.63.0 @flowx/core-theme@5.63.0 @flowx/angular-sdk@5.63.0 @flowx/angular-theme@5.63.0 @flowx/angular-ui-toolkit@5.62.1 
```

* Install a type dependency for the SSE library:

```bash theme={"dark"}
npm install --save-dev @types/event-source-polyfill
```

* run through all the migration steps in the [New SDK Api changes](#new-sdk-api-changes) section below.

> [!NOTE]
>
> Each migration requires a 'clean' repository state. Make sure to commit all changes before starting the next migration step.

> [!TIP]
>
> After each Angular update it is recommended you restart your editor or TS Server, to use the new TS version since some import errors might appear.

### New SDK API changes

#### Renderer SDK component usage

In the Angular SDK, the `<flx-process-renderer>` component has two new parameters have been introduced: `projectInfo` and `locale`. These additions help support localization and project-specific configurations.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectInfo` | Object containing an `projectId` key, which identifies the project of the process to be started | `{projectId: string}` | Mandatory |
| `locale` | Provides region-specific settings for localization. | `string` | Mandatory |

Add the definitions for these properties in the class file of the component that uses the process renderer component:

```typescript theme={"dark"}
projectInfo = { projectId: 'your-project-id' },
locale = 'en-US',
```

Use these parameters in the template as inputs for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  ...
  [projectInfo]="projectInfo"
  [locale]="locale"
/>
```

#### API changes

Process Renderer:

| Category | Old Approach | New Approach |
| - | - | - |
| **Process Renderer** | `FlxProcessModule.forRoot({...})` | `FlxProcessModule.withConfig({...})` |

#### Import path updates

| Category | Old Approach | New Approach |
| - | - | - |
| **Import Paths** | `@flowx/ui-sdk` | `@flowx/angular-sdk` (or, in some cases `@flowx/core-sdk`) |
| | `@flowx/ui-theme` | `@flowx/angular-theme` |
| | `@flowx/ui-toolkit` | `@flowx/angular-ui-toolkit` |
| **Process Module** | `import {FlxProcessModule} from '@flowx/ui-sdk';` | `import {FlxProcessModule} from @flowx/angular-sdk` |
| **Localization Module** | `import {FlxLocalizationModule} from '@flowx/ui-sdk';`  Include in module imports | `import {FlxLocalizePipe} from '@flowx/angular-sdk';` Remove from module imports |
| **Task Management** | `import {FlxTaskManagementModule} from '@flowx/ui-sdk';` | `import {FlxTasksManagementComponent} from '@flowx/angular-sdk';` |
| **Client Store Interface** | `import {ClientStoreInterface} from '@flowx/ui-sdk';` | `import {ClientStoreInterface} from '@flowx/core-sdk';` |

> [!NOTE]
>
> You can also remove the `FlxLocalizationModule` from any `imports` arrays in modules, and import the `FlxLocalizePipe` instead

### Icon module update

The `withExtraIconSet` method has been replaced with `provideExtraIconSet`, which should now be used in the providers array.

```typescript theme={"dark"}
@NgModule({
  imports: [
    IconModule,  // Import the IconModule
  ],
  providers: [
    // Use provideExtraIconSet to add your custom icon set
    provideExtraIconSet({
      customIcon1: 'path/to/custom-icon1.svg',
      customIcon2: 'path/to/custom-icon2.svg',
      // Add more icons as needed
    })
  ]
})
export class AppModule {}
```

### Custom Interceptors

The new FlowX SDKs do not depend on Angular's `HttpClient` to make API calls, so existing interceptors must be adapted to a new format, for Request Interceptors (eg. custom headers) and Response Interceptors (eg. error handling)

For an overview of implementation details, please refer to the respective sections of the renderer documentation for the new API changes.

> [card] [Custom Interceptors](/4.7.x/sdks/angular-renderer#custom-interceptors)


# FlowX.AI 4.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025

Welcome, FlowX fam! The 4.6.0 update is here, and it’s packed with features designed to save you time, boost efficiency, and maybe even make you chuckle. Let’s dive into the details, feature by glorious feature. 🎉

## **What's new?** 🆕

### Projects: Order out of chaos

The new Project concept introduces a streamlined approach to managing and deploying complex projects within FlowX. By grouping all related resources—such as processes, enumerations, integrations, and assets—into a single, organized workspace, projects provide a cohesive view for efficient development and deployment.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

💼 **Key Benefits**:

* **Unified Workspace**: Group related processes, integrations, assets, and configurations into one tidy space.
* **Version Control**: Manage multiple builds and versions effortlessly. Rollbacks? No sweat.
* **Resource Sharing**: Reuse processes and configurations across projects like a boss.

> [!TIP]
>
> **Why you’ll love it**: It’s like going from a messy desk to an organized digital office.

🎥 **Quick Demo**: (Who needs text when you have visuals?)

<video />

> [card] [Projects](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

#### 🛠 Config vs Build Mode

**Config Mode**: Tinker, tweak, and perfect.

* Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's the workspace where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

**Build Mode**: Lock it, load it, deploy it.

* Build mode is the stage where the configurations you've set up are packaged into a deployable form. This is the runtime-ready version of your project, containing everything needed for it to function in a production environment. A build includes a snapshot of the project’s state at a given point, ensuring stability and predictability when deployed.

<video />

> [card] [Configuration](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

> [card] [Runtime](/4.7.x/docs/projects/runtime/builds)
>
> For more details, check out this section

***

### Integration Designer: Connect like a pro

It’s like a dating app for your systems: drag, drop, connect, and let the workflows flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)

API integration just got easier! Integration Designer simplifies connecting FlowX with external systems using REST APIs.

✨ **The magic of it**:

* **Drag-and-Drop Interface**: Map data, define workflows, and configure endpoints like a breeze.
* **Flexible Authorization**: Use Service Tokens, Bearer tokens, or go authentication-free.
* **Error Management**: Built-in tools ensure your integrations don’t ghost you.

> [!TIP]
>
> **Fun Fact**: Integration Designer doesn’t just test APIs (we love you, [Postman](https://www.postman.com/)❤️). It automates workflows, saving you tons of time.

> [card] [Integration Designer](/4.7.x/docs/platform-deep-dive/integrations/integration-designer)
>
> For more details, check out this section

***

### Merge Conflicts 2.0: Merge without the drama

Merging branches? We've overhauled the process to make it faster, smarter, and far less painful.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)

🧩 **What’s New**:

* **Advanced Conflict Detection**: Pinpoint issues by resource type (Processes, Enumerations, Media, etc.).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)

* **Resource-Level Resolution**: Resolve conflicts directly in the UI with:
  * JSON comparisons (color-coded for clarity!).
  * Navigation tools to jump between differences.
  * Progress tracking for reviewed items.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

> [!TIP]
>
> **Pro Tip**: Use the “Merge Anyway” option if you need to override unresolved conflicts (but use it wisely!).

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)

> [card] [Merge conflicts](/4.7.x/docs/projects/managing-applications/versioning#managing-conflicts)

***

### AI Agents: Smart, adaptable, always ready to help

FlowX AI Agents bring automation to your fingertips, powered by a flexible, LLM-agnostic core.

🤖 **Why It’s Cool**:

* Works with both open-source and private language models.
* Secure, on-premise deployments available.
* Automates business processes and interactions.

🎥 Check out a quick demo:

<video />

Stay tuned for more.

***

### Localization and Internationalization

FlowX is now more global-friendly with enhanced localization features.

> [card] Flexible Date, Time, Number, and Unit Formatting
>
> Enhanced formatting options for dates, times, numbers, and currencies with support for various international standards including short, medium, long, full, and custom formats.

> [card] Currency Customization
>
> Support for currency formatting with options to display values using ISO codes or symbols, adapting to user-selected locales and regional preferences.

> [card] Locale-Based Configurations
>
> Comprehensive settings for pluralization, capitalization, alignment, and sorting that adapt to regional requirements, helping cater to a diverse global user base.

> [card] Enhanced UI Component Formatting
>
> New options in the UI Designer to override general settings for text, messages, links, and form elements based on locale and region.

> [card] Document Localization
>
> Static and dynamically generated legal documents can now be customized based on regional and locale settings, improving compliance and communication with local audiences.

> [card] [Localization and internationalization](/4.7.x/docs/building-blocks/ui-designer/localization-and-i18n)
>
> For more details, check out this section

***

### Data Model 2.0: Data handling, but make it fashion

In this release, we've introduced Data Model 2.0, a major upgrade designed to simplify and enhance data handling. Key improvements include the introduction of reusable objects, a visual representation of complex data structures, and dynamic data binding, all aimed at creating a more reliable and intuitive experience. The new model ensures references are automatically updated when changes are made, streamlining data management across the platform.

**Highlights**:

* **New Root Element**: Provides a structural basis without impacting business logic, ensuring a clear and organized data structure.
* **Enhanced Data Binding**: Expanded to more areas, with dynamic updates based on changes in the data model.
* **Localization**: Added handling mechanism for locale-specific formatting, ensuring accurate data representation.

<video />

> [card] [Data model](/4.7.x/docs/building-blocks/process/data-model)
>
> For more details, check out this section

***

### Task management 2.0

We've enhanced Task Management capabilities, making it easier to create, track, and manage tasks efficiently. The updated Task Management features include customizable views and advanced filtering and sorting options for task data. Additionally, users can now implement both low-code and full-code solutions for a tailored Task Management experience, ensuring maximum flexibility for different business needs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

> [card] [Task Management](/4.7.x/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> For more details, check out this section

***

### UI Designer

#### Grid layout

We are excited to introduce the Grid Layout feature in this release, enhancing the flexibility and usability of the UI Designer for creating structured and responsive layouts. With the new Grid Layout, users can organize form elements, tables, and other components using a multi-column and row system, allowing for more complex, bidirectional designs compared to the previous flex-based layout.

<video />

> [accordion] This might happen after using it for the first time:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid-layout-first-time.jpg)

#### Table

The Table component is a simple and flexible way to display data in web applications. It lets you customize columns, add pagination, sort and filter data, and apply your own styling. You can resize columns, scroll through data, and even add actions like editing or deleting rows directly in the table. It’s easy to set up, with default columns and rows generated automatically based on your data.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)

> [card] [Table](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/table)
>
> For more details, check out this section

#### FlowX.AI UI Designer new navigator

We are thrilled to introduce the new and improved **UI Designer Navigator**, a major update designed to streamline your UI design process.

> [card] Enhanced UI Layer Panel Design and Functionality
>
> The UI layer panel has been redesigned for a more intuitive experience, making it easier to manage and navigate through your design elements.

> [card] Improved Drag and Drop Experience
>
> Dragging and dropping components in the preview is now smoother and more precise, allowing for faster and easier creation of UIs.

> [card] Flexible Root Component Management
>
> You can now change the root component from a form group to a container or vice versa, offering greater flexibility when copying nodes or resolving configuration problems.

> [card] Clearer Component Hierarchy
>
> It is now simpler to identify where you are placing a component within the hierarchy, thanks to the enhanced drag/reorder functionality in the right panel.

<video />

#### Conditional formatting for UI elements

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)

> [!NOTE]
>
> Conditional styling is available for **text**, **link**, and **container** UI elements based on specific conditions.

#### Hide expressions enhancements

Expanded hide expressions functionality to include:

* Cards
* Collection prototypes and children
* Table cell children (e.g., texts, images, buttons, links)

#### UI actions

* Added a new UI action **Start new project instance**
* Removed the **Start Process Inherit** UI action type.

#### UI action form updates

* Introduced **Functional** and **UX sections** for all action types, with a checkbox for **Add Analytics Name** in the UX section.
* Simplified custom and exclude key management.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2015.20.01.png)

***

### Start new project instance action

We’ve introduced the Start New Project Instance node action, enabling users to initiate a completely new process from within an ongoing one. This functionality is perfect for scenarios where isolated use cases are managed across different projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)

> [card] [Start new project instance action](/4.7.x/docs/building-blocks/actions/start-new-project-instance)

***

### Custom components validation

You are able to validate and retrieve data from a generated screen, including data from a custom form section. Additionally, you’ll have the ability to trigger and manage data directly within that section. This will be a major benefit for clients who have chosen to create custom components for the entire screen (for example, a form that isn’t supported natively by the platform).

> [card] [Validating elements](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/root-components/card#validating-elements)

***

### Autocomputed data to send

In previous platform versions, when creating your UI screens and working with data, you had to ensure that all the data stored in your process keys was saved in the process instance. This required adding an extra parameter called "Data to send" to the "Save Data" node action.

**Older versions** vs **v4.6.0**:

![older versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.x-aut.png)

![v.4.6](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.2-aut.png)

Now, with the autocompute feature, this step is no longer necessary, as the data is automatically saved and sent on your process instance.

> [!TIP]
>
> You no longer need to add "Save Data" node actions, but make sure to include "Forms to Validate" on the UI Actions. This helps ensure that data is submitted correctly and automatically activates any added validators where they exist.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/forms_to_validate.png)

However, you still have the option to customize which keys are included or excluded as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/include_exclude_keys.png)

***

### **Scripting UX Improvements**: *Write code like a wizard*

* **Autocomplete**: Get tailored suggestions based on your data model.
* **New Editors**: JSON and hide/disable expressions editors now include examples, syntax help, and better visual feedback.

<video />

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide%3Adisable%20editor.png)

***

### React & Angular SDKs

Dev friends, we heard you. FlowX now integrates smoothly into your React and Angular apps. It’s like peanut butter and jelly, but make it code.

#### React SDK

With the 4.6.0 release, we're excited to announce the launch of the FlowX React SDK! This new SDK empowers developers to seamlessly integrate FlowX.AI capabilities into React applications, making it easier than ever to build highly interactive, responsive, and dynamic user experiences.

To get started, simply install the FlowX React SDK via npm and check our documentation for examples and best practices!

> [card] [React SDK](/4.7.x/sdks/react-renderer)

#### New Angular SDK

We're excited to announce new releases for FlowX packages to support web applications:

* `@flowx/core-sdk`
* `@flowx/angular-sdk`
* `@flowx/angular-theme`
* `@flowx/angular-ui-toolkit`
* `@flowx/core-theme`

> [!WARNING]
>
> We recommend upgrading to the **latest** versions of all @flowx packages to take full advantage of these new features and improvements. Check the deployment guidelines for version details.

> [card] [Angular SDK migration guide](migrating-from-v4.1.x-to-v4.6.0/renderers#angular-sdk-migration-guide)

***

### Analytics integration for Container Apps

Container apps now support tracking "Screen Displayed" and "Action Executed" events, configurable in the UI Designer to improve insights into user interactions.

**UI Designer updates**

* **Analytics Screen Name:** Configurable under Root UI components (Cards and Containers) to enable tracking in analytics platforms like Google Analytics.

> [!TIP]
>
> "Screen Displayed" events support user task-based reporting, such as when a user task screen is shown.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.01.58.png)

> [!NOTE]
>
> The configured values are stored in `flowxProps.analytics`, making them accessible for integration with analytics tools.

* **Action Analytics:** Tracks user actions (e.g., button clicks) with tags set directly in the UI Action Form.

> [!NOTE]
>
> Added analytics configuration in the **UX Section** for all UI action types.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.20.53.png)

> [!NOTE]
>
> Values are saved in `params.analytics` via the PATCH `/actions` request.

**Renderers updates**

Renderers now expose a public API for triggering analytics events:

* **Screen Events:** Triggered on user task display, using `flowxProps.analytics`.
* **Action Events:** Triggered on action execution, using `params.analytics`.

Dynamic values such as process store keys and replace tags are supported for more contextual tracking.

***

### Plugin updates

**Notifications** and **Documents** plugins have been integrated as **project resources**.

***

### Scheduled Processes: Timer management reimagined

We've completely redesigned how you manage timer-triggered processes. Before 4.6.0, timer activation was managed through a quick actions menu in process definition headers; now it's handled via dedicated UI section in the Runtime tab under Scheduled Processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

🕒 Key Improvements:

* **Centralized Timer Management:** All process timers are now visible and manageable in one dedicated location
* **Persistent Settings:** Timer configurations persist across build exports/imports
* **Environment Control:** Activate or deactivate timers without redeploying your application

For more details, check out this section

> [card] [Scheduled Processes](/4.7.x/docs/projects/runtime/scheduled-processes)

## Bug fixes 🐞

### Rendering

* **Default Value Initialization for UI Elements**: Resolved an issue where certain UI elements were initialized with incorrect default values.

* **Improved Security for Hidden Fields**: Fixed a vulnerability where hidden fields could be accessed through browser developer tools.

* **Form Validation Reset on UI Dismissal**: Addressed an issue where form validation errors persisted after the UI was closed.

* **Keybinding Issues on Windows**: Fixed a bug where pressing specific keys triggered unintended operations in the designer.

* **Input Field Validation for Number Type**: Corrected the validation logic for number input fields to ensure consistent behavior.

* **Improved Datepicker Popup Positioning**: Resolved an issue where the datepicker popup overlapped the associated input field.

* **Manual Date Entry in Datepicker**: Fixed an issue where manually entering a date after selecting one from the datepicker caused errors.

* **Enhanced Update Mechanism for Custom Components**: Improved the reliability of updates for custom components to reflect changes consistently.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **New substitution tags with the same name on different branches aren’t flagged**: Merging branches that include new substitution tags with identical names on different branches does not trigger a conflict. Instead, both tags are retained, resulting in duplicate substitution tags with the same name but different values. This issue bypasses expected conflict detection and can lead to inconsistencies in substitution tag usage.
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] Notification and document templates
>
> * Branches with notification and document templates fail to merge into the main branch

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Changes 🔧

* **Web Renderer Caching:** Improved resource caching with browser mechanisms keyed to build IDs.
* **Process Designer:** Enhanced drag-and-drop functionality for node placement.

***

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.0](./deployment-guidelines-v4.6.0)

Migrating from v4.1.x:

> [card] [Migrating from v4.1.x to v4.6.0](./migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x)

> [card] [Changes in process configuration](./migrating-from-v4.1.x-to-v4.6.0/process-configuration)

> [card] [Renderer SDKs](./migrating-from-v4.1.x-to-v4.6.0/renderers)


# Deployment guidelines v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/deployment-guidelines-v4.6.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.

## Component versions

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.1.1** | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.6** | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.2** | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | 4.1.3 | 4.1.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.4** | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.25** | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.4** | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.11** | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

> [!NOTE]
>
> Note: The same container image and Helm chart are used for **Application Manager** and **Runtime Manager**.

## AI Agents

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.16** | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.15** | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.6** | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.27** | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.6.5** | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.1 | Keycloak | 22.x |
| 4.6.1 | Kafka | 3.2.x |
| 4.6.1 | PostgreSQL | 16.2.x |
| 4.6.1 | MongoDB | 7.0.x |
| 4.6.1 | Redis | 7.2.x |
| 4.6.1 | Elasticsearch | 7.17.x |
| 4.6.1 | Oracle Database | 21C/ 21-XE |
| 4.6.1 | Angular (Web SDK) | 19.x |
| 4.6.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.


# Migrating from previous versions to v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/migrating-from-v4.1.x-to-v4.6.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.0 version, make sure to first review the migration guide for v4.6.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

If you're moving from v4.1.x to v4.6.1, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.6.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025

FlowX.AI 4.6.1 is here with important fixes and improvements to keep things running smoothly. No new features this time—just focused updates to improve stability, fix bugs, and enhance overall performance. Simple, clean, and efficient.

## **What's new?** 🆕

### Rendering

**Form Elements** improvements:

* **Default Value Handling**: Defaults are applied only when no existing value is found, and set upon first display (with specific exceptions).
* **Data Consistency**: Form elements now save data in standardized formats based on type for improved reliability.
* **Smart Defaults**: Clear fallback behaviors for elements like switches, sliders, and checkboxes when no value is present.
* **Synchronized Inputs**: Linked form elements (e.g., input + slider) stay in sync with automatic value adjustments within set limits.
* **Dynamic Dependencies**: Form elements can dynamically adjust based on related components’ values for greater flexibility.

### Merge conflicts

* Improvement: merged version is now selected after a successful merge in versioning modal.

## Bug fixes 🐞

### Merge conflicts

* Fixed an issue that caused conflicts involving notification and document templates to fail.
* Fixed an issue where merges failed when a deleted configuration parameter was updated on a branch.
* Fixed an issue that resulted in duplicate substitution tag keys appearing in the merged version.
* Fixed an issue where merges failed due to the same dependency being added to both the source and target branches.
* Fixed issues related to workflow conflicts.

### Rendering

* Fixed an issue where documents from the media library were not loading correctly when added as a file preview in a user task.

### Integration Designer

* Fixed issue causing a 400 error when adding an enum mapper to the body tab due to incorrect data validation.
* Fixed issue where the last attribute in the objects table was not visible at higher zoom levels due to UI rendering constraints.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.1](./deployment-guidelines-v4.6.1)

Migrating from v4.6.0:

> [card] [Migrating from previous versions](./migrating-from-v4.1.x-to-v4.6.1)


# Deployment guidelines v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/deployment-guidelines-v4.7.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.0 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.
>
> In version 4.7, the import-export functionality for application-version is no longer backward compatible.
>
> * Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
>
> * Similarly, zip files from earlier versions cannot be imported into 4.7.
>
> Note: Zip files for builds and specific resources remain unaffected.

## Component versions

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.3.1** | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.5.1** | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.11** | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.2** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.5** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.0** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.1** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.2** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.4** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.4** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.3** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.2** | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.1.0** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.5** | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.12** | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.21** | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.7.2** | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.13** | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.31** | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.0** | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.0 | Keycloak | 22.x, 26.x |
| 4.7.0 | Kafka | 3.2.x |
| 4.7.0 | PostgreSQL | 16.2.x |
| 4.7.0 | Oracle Database | 21c, 23ai |
| 4.7.0 | MongoDB | 7.0.x |
| 4.7.0 | Redis | 7.2.x |
| 4.7.0 | Elasticsearch | 7.17.x |
| 4.7.0 | Angular (Web SDK) | 19.x |
| 4.7.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/migrating-from-v4.1.x-to-v4.7.0

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# AI comparison and reconciliation
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/ai-comparison-reconciliation

Compare AI-extracted document data against system-of-record values and generate structured exception reports with match rates and confidence scores.

The AI comparison and reconciliation pattern uses TEXT\_UNDERSTANDING nodes as comparison agents to perform field-by-field validation between AI-extracted data and expected values from a system of record. The output is a structured exception report that drives downstream routing: auto-approve, human review, or reject.

***

## When to use

Use this pattern when you need to:

* Validate AI-extracted document data against a trusted source (TMS, ERP, core banking system, database)
* Produce auditable, structured comparison results with per-field match status
* Route exceptions based on severity and overall match rate
* Replace manual spot-checking of document extraction results

This pattern typically follows the [fan-out extraction](./fan-out-extraction) pattern in a document processing pipeline.

***

## Architecture

The workflow accepts two data sets as input, runs them through a TEXT\_UNDERSTANDING comparison agent, and routes the result based on the exception report.

```
Extracted Data + System Data
        |
        v
 TEXT_UNDERSTANDING (compare)
        |
        v
   Exception Report
        |
        v
   Condition (severity routing)
      /       |       \
     v        v        v
Auto-approve  Human   Reject
              review
```

**Node breakdown:**

| Node | Type | Purpose |
| - | - | - |
| **Compare** | TEXT\_UNDERSTANDING | Field-by-field comparison of extracted vs. expected values |
| **Route** | Condition | Branch based on overall match rate and exception severity |
| **Auto-approve** | End / next step | High-match documents proceed without intervention |
| **Human review** | End / next step | Medium-match documents queued for manual review |
| **Reject** | End / next step | Low-match documents flagged for rejection |

***

## Implementation

### Input structure

The comparison node receives two objects: the AI-extracted values and the system-of-record values.

```json theme={"dark"}
{
  "extractedData": {
    "shipperName": "Acme Logistics Ltd.",
    "consigneeName": "Beta Corp",
    "totalWeight": "14500",
    "weightUnit": "KG",
    "containerCount": 3,
    "bolNumber": "MSKU-2024-78432"
  },
  "systemData": {
    "shipperName": "Acme Logistics",
    "consigneeName": "Beta Corporation",
    "totalWeight": "14500",
    "weightUnit": "KG",
    "containerCount": 3,
    "bolNumber": "MSKU-2024-78432"
  }
}
```

### Comparison prompt

Configure the TEXT\_UNDERSTANDING node with a prompt that instructs the LLM to perform structured comparison.

```text theme={"dark"}
You are a document reconciliation agent. Compare the AI-extracted values against
the system-of-record values and produce a structured exception report.

Instructions:
1. Compare each field individually. Use fuzzy matching for names and addresses
   (e.g., "Acme Logistics Ltd." vs "Acme Logistics" is a MATCH).
2. For numeric fields, compare exact values. Flag unit mismatches separately.
3. For derived values (e.g., total weight = sum of line items), verify the
   calculation independently.
4. Compute an overall match rate as a percentage (0-100).
5. Assign a confidence score (0-100) reflecting how certain you are in the
   comparison results.
6. Flag each exception with a severity: CRITICAL, WARNING, or INFO.

Extracted data:
{{extractedData}}

System-of-record data:
{{systemData}}
```

### Output schema

Define the output schema on the TEXT\_UNDERSTANDING node to enforce structured results.

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "matchRate": {
      "type": "number",
      "description": "Overall match rate from 0 to 100"
    },
    "confidenceScore": {
      "type": "number",
      "description": "Confidence in comparison accuracy from 0 to 100"
    },
    "fieldResults": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": { "type": "string" },
          "extractedValue": { "type": "string" },
          "expectedValue": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["MATCH", "MISMATCH", "MISSING"]
          },
          "severity": {
            "type": "string",
            "enum": ["CRITICAL", "WARNING", "INFO"]
          },
          "note": { "type": "string" }
        },
        "required": ["fieldName", "status"]
      }
    },
    "exceptions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": { "type": "string" },
          "description": { "type": "string" },
          "severity": {
            "type": "string",
            "enum": ["CRITICAL", "WARNING", "INFO"]
          }
        },
        "required": ["fieldName", "description", "severity"]
      }
    }
  },
  "required": ["matchRate", "confidenceScore", "fieldResults", "exceptions"]
}
```

### Severity routing

Configure a Condition node after the comparison to route based on the exception report.

| Route | Condition | Action |
| - | - | - |
| **Auto-approve** | `matchRate >= 95` and no CRITICAL exceptions | Proceed to next processing step |
| **Human review** | `matchRate >= 70` and `matchRate < 95`, or any WARNING exceptions | Queue for manual review |
| **Reject** | `matchRate < 70` or any CRITICAL exception | Flag for rejection and notify |

> [!TIP]
>
> Adjust the match rate thresholds based on your business requirements. Start conservative (higher thresholds for auto-approve) and relax them as you gain confidence in extraction quality.

***

## Configuration reference

| Setting | Value | Description |
| - | - | - |
| **Node type** | TEXT\_UNDERSTANDING | Comparison agent |
| **Output format** | JSON schema | Structured exception report |

***

## Exception severity levels

| Severity | Description | Examples |
| - | - | - |
| **CRITICAL** | Data integrity issue that blocks processing | Missing required field, numeric value off by more than 10%, wrong document matched to shipment |
| **WARNING** | Discrepancy that requires human judgment | Name variation beyond fuzzy match threshold, date format ambiguity, unit conversion needed |
| **INFO** | Minor difference, typically acceptable | Abbreviation vs. full name, trailing whitespace, formatting differences |

***

## Variations

### Threshold-based routing

Instead of fixed severity categories, use configurable thresholds stored in a FlowX Database data source. This allows business users to adjust auto-approve and reject boundaries without modifying the workflow.

### Multi-document cross-reference

Extend the pattern to compare fields across multiple documents in the same shipment. For example, verify that the total weight on the bill of lading matches the sum of weights on the packing list and that both align with the commercial invoice.

### Audit trail generation

Add a downstream node that persists the full exception report (including all MATCH results) to a database or document store. This provides a complete audit trail for compliance and quality monitoring over time.

***

## Related resources

> [card] [Cookbook: reconcile invoices](/5.9/cookbooks/invoice-reconciliation)
>
> Build a reconciliation end to end: extract invoices, match them against purchase orders, route exceptions to a reviewer

> [card] [AI patterns overview](./overview)
>
> All available AI patterns and how to combine them

> [card] [Fan-out extraction](./fan-out-extraction)
>
> Classify and extract from multiple document types

> [card] [Hybrid AI + business rules](./hybrid-ai-rules)
>
> Combine AI with deterministic logic for auditable decisions

> [card] [AI node types](../agent-builder/node-types)
>
> Reference for all AI node types including TEXT\_UNDERSTANDING


# Fan-out extraction
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/fan-out-extraction

Classify documents by type, then route each to a specialized extraction node with tailored prompts and schemas. Scale to dozens of document types.

## When to use

Use fan-out extraction when your app needs to process documents that vary significantly in structure and content. A single extraction prompt cannot handle the differences between an invoice, a bill of lading, and a fuel receipt — each has different fields, layouts, and validation rules.

This pattern is the right choice when:

* You receive **mixed document types** in a single pipeline (email attachments, bulk uploads)
* Each document type has a **distinct schema** with specialized fields
* You need **high extraction accuracy** per type rather than a generic best-effort pass
* The number of document types may **grow over time** without rearchitecting the workflow

***

## Architecture

The pattern follows two phases: classification, then type-specific extraction.

```text theme={"dark"}
Document
  │
  ▼
DOCUMENT_UNDERSTANDING (classify type)
  │
  ▼
Condition (fork by type)
  ├──► DOCUMENT_EXTRACTION (Type A) ──►─┐
  ├──► DOCUMENT_EXTRACTION (Type B) ──►─┤
  ├──► DOCUMENT_EXTRACTION (Type C) ──►─┤
  └──► DOCUMENT_EXTRACTION (Type N) ──►─┘
                                        │
                                        ▼
                            Shared downstream node
```

> [!NOTE]
>
> This pattern uses the document nodes because they accept files directly. The TEXT\_UNDERSTANDING and TEXT\_EXTRACTION nodes work on **text input only** — to use them here, you would first need to convert the file to text with the **Extract Data from File** node.

### Phase 1: Classification

A **DOCUMENT\_UNDERSTANDING** node receives the document file and classifies it into one of the known types. The classification instructions constrain the output to an enumerated list, so the Condition node can route deterministically.

### Phase 2: Type-specific extraction

Each branch contains a **DOCUMENT\_EXTRACTION** node configured with:

* **Instructions** tailored to that document type, telling the model which fields to look for
* A **response schema** defining the exact JSON structure expected for that type
* An **Extraction Method** suited to the document format (text-heavy PDFs vs. scanned images)

The branches reconnect on a shared downstream node, which receives the output of whichever branch executed.

***

## Implementation

### Step 1: Configure the classification node

Add a **DOCUMENT\_UNDERSTANDING** node and configure it to classify the document type.

**Example classification instructions:**

```text theme={"dark"}
You are a document classifier. Analyze the provided document and determine its type.

Respond with exactly one of the following values:
- BOL
- INVOICE
- RATE_CONFIRMATION
- LUMPER_RECEIPT
- FUEL_RECEIPT

Base your classification on the document layout, headers, and field labels.
If the document does not match any known type, respond with UNKNOWN.
```

**Example response schema:**

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "document_type": {
      "type": "string",
      "enum": ["BOL", "INVOICE", "RATE_CONFIRMATION", "LUMPER_RECEIPT", "FUEL_RECEIPT", "UNKNOWN"]
    },
    "confidence": {
      "type": "number",
      "description": "Classification confidence between 0 and 1"
    }
  },
  "required": ["document_type", "confidence"]
}
```

### Step 2: Add the Condition node

Add a **Condition** node after the classification node. Configure branches based on the `document_type` value:

| Branch | Condition | Target |
| - | - | - |
| BOL | `document_type == "BOL"` | DOCUMENT\_EXTRACTION (BOL) |
| Invoice | `document_type == "INVOICE"` | DOCUMENT\_EXTRACTION (Invoice) |
| Rate confirmation | `document_type == "RATE_CONFIRMATION"` | DOCUMENT\_EXTRACTION (Rate confirmation) |
| Lumper receipt | `document_type == "LUMPER_RECEIPT"` | DOCUMENT\_EXTRACTION (Lumper receipt) |
| Fuel receipt | `document_type == "FUEL_RECEIPT"` | DOCUMENT\_EXTRACTION (Fuel receipt) |
| Default | `document_type == "UNKNOWN"` | Manual review queue |

### Step 3: Configure type-specific extraction nodes

Each branch gets its own **DOCUMENT\_EXTRACTION** node with instructions and a schema optimized for that document type. The node works directly on the uploaded file.

> [tab] BOL (Bill of Lading)
>
> **Prompt:**
>
> ```text theme={"dark"}
> Extract all relevant fields from this Bill of Lading document.
> Pay special attention to carrier information, shipment details, and freight charges.
> If a field is not present, return null for that field.
> ```
>
> **Response schema:**
>
> ```json theme={"dark"}
> {
>   "type": "object",
>   "properties": {
>     "bol_number": { "type": "string" },
>     "carrier": {
>       "type": "object",
>       "properties": {
>         "name": { "type": "string" },
>         "mc_number": { "type": "string" },
>         "scac_code": { "type": "string" }
>       }
>     },
>     "shipper": {
>       "type": "object",
>       "properties": {
>         "name": { "type": "string" },
>         "address": { "type": "string" },
>         "city": { "type": "string" },
>         "state": { "type": "string" },
>         "zip": { "type": "string" }
>       }
>     },
>     "consignee": {
>       "type": "object",
>       "properties": {
>         "name": { "type": "string" },
>         "address": { "type": "string" },
>         "city": { "type": "string" },
>         "state": { "type": "string" },
>         "zip": { "type": "string" }
>       }
>     },
>     "ship_date": { "type": "string" },
>     "delivery_date": { "type": "string" },
>     "pieces": { "type": "integer" },
>     "weight": { "type": "number" },
>     "freight_charges": { "type": "number" }
>   }
> }
> ```

> [tab] Invoice
>
> **Prompt:**
>
> ```text theme={"dark"}
> Extract all fields from this invoice document.
> Capture line items as an array. Extract totals, tax amounts, and payment terms.
> If a field is not present, return null for that field.
> ```
>
> **Response schema:**
>
> ```json theme={"dark"}
> {
>   "type": "object",
>   "properties": {
>     "invoice_number": { "type": "string" },
>     "invoice_date": { "type": "string" },
>     "due_date": { "type": "string" },
>     "vendor_name": { "type": "string" },
>     "line_items": {
>       "type": "array",
>       "items": {
>         "type": "object",
>         "properties": {
>           "description": { "type": "string" },
>           "quantity": { "type": "number" },
>           "unit_price": { "type": "number" },
>           "amount": { "type": "number" }
>         }
>       }
>     },
>     "subtotal": { "type": "number" },
>     "tax": { "type": "number" },
>     "total": { "type": "number" },
>     "payment_terms": { "type": "string" }
>   }
> }
> ```

> [tab] Rate confirmation
>
> **Prompt:**
>
> ```text theme={"dark"}
> Extract all fields from this rate confirmation document.
> Focus on load details, rate amounts, pickup and delivery information.
> If a field is not present, return null for that field.
> ```
>
> **Response schema:**
>
> ```json theme={"dark"}
> {
>   "type": "object",
>   "properties": {
>     "confirmation_number": { "type": "string" },
>     "load_number": { "type": "string" },
>     "broker_name": { "type": "string" },
>     "carrier_name": { "type": "string" },
>     "rate_amount": { "type": "number" },
>     "pickup_date": { "type": "string" },
>     "pickup_location": { "type": "string" },
>     "delivery_date": { "type": "string" },
>     "delivery_location": { "type": "string" },
>     "equipment_type": { "type": "string" },
>     "commodity": { "type": "string" }
>   }
> }
> ```

> [!TIP]
>
> Keep schemas as flat as possible for simple document types (like fuel receipts and lumper receipts). Reserve nested objects for complex types that genuinely have grouped fields (like BOL with shipper/consignee blocks).

***

## Configuration reference

| Component | Node type | Key settings |
| - | - | - |
| **Classifier** | DOCUMENT\_UNDERSTANDING | Instructions with enumerated types, constrained response schema |
| **Router** | Condition | Branch per document type, default branch for unknown types |
| **Extractor (per type)** | DOCUMENT\_EXTRACTION | Type-specific instructions, tailored response schema, extraction method |
| **Convergence** | Any downstream node | Branches reconnect here; only the matched branch executes |

> [!NOTE]
>
> If you need the raw text rather than schema-based extraction, use the **Extract Data from File** node instead — it supports PDF, DOCX, XLSX, PPTX, HTML, CSV, Markdown, AsciiDoc, and image formats (JPG, PNG, TIFF, BMP, WEBP), processing images directly through OCR. Its text output can then feed TEXT\_UNDERSTANDING or TEXT\_EXTRACTION nodes.

***

## Scaling to many document types

This pattern scales well because adding a new document type requires only:

1. Adding the new type to the classifier's enumerated list
2. Adding a new branch in the Condition node
3. Adding a new DOCUMENT\_EXTRACTION node with the type-specific instructions and schema

No existing branches are modified. This makes the pattern suitable for domains with dozens of document types.

| Domain | Example document types |
| - | - |
| **Logistics** | BOL, invoice, rate confirmation, lumper receipt, fuel receipt, proof of delivery, customs declaration |
| **Mortgage** | Product sheets, income statements, bank statements, tax returns, appraisal reports, title documents, regulatory disclosures |
| **Insurance** | Claims forms, medical records, police reports, repair estimates, coverage declarations |

***

## Variations

### Parallel extraction

Instead of classifying first, run extraction for all document types simultaneously and pick the result with the highest confidence. This trades compute cost for lower latency and avoids classification errors.

> [!NOTE]
>
> Parallel extraction works best when you have a small number of document types (under 5). Beyond that, the cost of running every extractor on every document becomes impractical.

### Hierarchical classification

For large document sets, classify in two stages: first into a broad category (financial, shipping, legal), then into a specific type within that category. This reduces the number of options the classifier evaluates at each stage.

```text theme={"dark"}
Document
  │
  ▼
DOCUMENT_UNDERSTANDING (broad category)
  │
  ├──► DOCUMENT_UNDERSTANDING (financial subtypes) ──► Condition ──► Extractors
  ├──► DOCUMENT_UNDERSTANDING (shipping subtypes)  ──► Condition ──► Extractors
  └──► DOCUMENT_UNDERSTANDING (legal subtypes)     ──► Condition ──► Extractors
```

### Confidence fallback

Add a confidence threshold to the classification step. If the classifier returns a confidence below the threshold, route the document to a manual classification queue instead of risking an incorrect extraction.

```text theme={"dark"}
Condition logic:
  confidence >= 0.8  → route to type-specific extractor
  confidence < 0.8   → route to manual classification
```

> [!TIP]
>
> Start with a confidence threshold of 0.8 and adjust based on your observed accuracy. Track classification accuracy over time to identify document types that need prompt refinement.

***

## Related resources

> [card] [Patterns overview](./overview)
>
> All available AI patterns and how to combine them

> [card] [AI node types](../agent-builder/node-types)
>
> Reference for DOCUMENT\_UNDERSTANDING, DOCUMENT\_EXTRACTION, and other node types

> [card] [Extract Data from File](../agent-builder/extract-data-from-file)
>
> Configuration guide for the Extract Data from File node

> [card] [AI comparison and reconciliation](./ai-comparison-reconciliation)
>
> Compare extracted data against system-of-record values


# Hybrid AI + business rules
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/hybrid-ai-rules

Combine AI extraction and understanding with deterministic business logic for auditable, explainable decision-making.

## When to use

Use this pattern when your workflow requires both AI capabilities (extracting data from unstructured documents, classifying items with fuzzy matching, generating natural language reports) and deterministic business logic (financial formulas, eligibility checks, compliance scoring). The key requirement is **auditability** — you need to trace exactly how a decision was reached, which means the AI handles what humans cannot codify as rules, and business rules handle everything else.

Common scenarios:

* Financial product eligibility where income data comes from scanned documents but calculations must follow exact regulatory formulas
* Insurance underwriting that extracts risk factors from free-text medical reports, then applies deterministic scoring tables
* Procurement workflows that classify vendor proposals with AI, then rank them using weighted scoring matrices

Without this pattern, you face two bad options: pure AI (fast but opaque, hard to audit) or pure rules (auditable but unable to handle unstructured input).

***

## Architecture

The pattern alternates between AI nodes and Script/Business Rule nodes in a pipeline:

```
Documents / unstructured input
    |
    v
AI EXTRACTION
(extract structured data from documents)
    |
    v
BUSINESS RULES
(deterministic calculations, formulas)
    |
    v
AI UNDERSTANDING
(fuzzy matching, qualitative filtering)
    |
    v
BUSINESS RULES
(scoring, ranking, normalization)
    |
    v
AI GENERATION
(produce human-readable report)
    |
    v
Final output (structured data + report)
```

Each AI node produces structured JSON output that feeds directly into the next Script node. Each Script node produces deterministic, reproducible results that feed into the next AI node. This alternating structure means every decision point is either fully deterministic (and logged) or clearly marked as AI-assisted (with the prompt and response recorded).

> [!NOTE]
>
> The alternating AI-then-rules structure creates a natural audit trail. For any final decision, you can trace backwards: which AI extraction produced the input values, which formula computed the result, and which AI classification influenced the filtering. This is critical for regulated industries where decisions must be explainable.

***

## Implementation

### AI vs. business rule responsibilities

The core principle is a clean separation: AI handles what cannot be expressed as deterministic rules, and business rules handle everything that can.

| Responsibility | Handled by | Why |
| - | - | - |
| Extract income, debts, employment data from bank statements | **AI** (DOCUMENT\_EXTRACTION) | Unstructured documents, varying formats |
| Compute monthly payment (PMT), debt-to-income ratio | **Business rules** (Script node) | Exact financial formulas, must be auditable |
| Filter products by qualitative criteria (loan type, sustainability features) | **AI** (TEXT\_UNDERSTANDING) | Fuzzy matching, natural language descriptions |
| Normalize scores, rank products, apply weight matrices | **Business rules** (Script node) | Deterministic scoring, reproducible results |
| Generate consultant report with recommendations | **AI** (TEXT\_GENERATION) | Natural language output, professional formatting |

***

### Step 1: AI extraction

Configure a DOCUMENT\_EXTRACTION node to pull structured data from unstructured documents. The node receives bank-specific rule documents as files and extracts the parameters your business rules need. (For plain-text input, TEXT\_EXTRACTION works the same way — the text nodes do not accept files.)

#### Instructions

```text theme={"dark"}
Extract the following financial parameters from the provided bank rule document:

- income_weights: object mapping income source types to their weight factors
- debt_factors: object mapping debt types to their monthly burden factors
- max_ltv: maximum loan-to-value ratio (as decimal)
- min_income_threshold: minimum gross monthly income required
- supported_currencies: array of accepted currency codes
- special_conditions: any additional eligibility conditions described in the document

Return a JSON object with these fields. Use null for any parameter not found in the document.
```

#### Response Schema

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "income_weights": {
      "type": "object",
      "description": "Income source type to weight factor mapping"
    },
    "debt_factors": {
      "type": "object",
      "description": "Debt type to monthly burden factor mapping"
    },
    "max_ltv": {
      "type": "number"
    },
    "min_income_threshold": {
      "type": "number"
    },
    "supported_currencies": {
      "type": "array",
      "items": { "type": "string" }
    },
    "special_conditions": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["income_weights", "debt_factors", "max_ltv", "min_income_threshold"]
}
```

| Setting | Value |
| - | - |
| **Node type** | `DOCUMENT_EXTRACTION` |
| **Input** | Bank rule document (PDF file) |
| **Response Key** | `extractedParams` |

***

### Step 2: Business rules (calculations)

Add a Script node immediately after the extraction. This node takes the AI-extracted parameters and applies deterministic financial formulas. Because this is a Script node, every calculation is reproducible and auditable.

#### Example script

```javascript theme={"dark"}
// Inputs from AI extraction
const params = input.extractedParams.output;
const client = input.clientData;

// Weighted income calculation
let weightedIncome = 0;
for (const [source, amount] of Object.entries(client.incomeSources)) {
  const weight = params.income_weights[source] || 0;
  weightedIncome += amount * weight;
}

// Monthly debt burden
let monthlyDebt = 0;
for (const [debtType, balance] of Object.entries(client.debts)) {
  const factor = params.debt_factors[debtType] || 0.05;
  monthlyDebt += balance * factor;
}

// PMT calculation (monthly payment for a given loan amount)
function computePMT(principal, annualRate, termMonths) {
  const r = annualRate / 12;
  if (r === 0) return principal / termMonths;
  return principal * (r * Math.pow(1 + r, termMonths)) /
         (Math.pow(1 + r, termMonths) - 1);
}

// Debt-to-income ratio
const dti = (monthlyDebt) / weightedIncome;

// Maximum loan amount (iterative solve for PMT <= allowed DTI share)
const maxDtiShare = 0.43; // Standard threshold
const allowablePayment = (maxDtiShare * weightedIncome) - monthlyDebt;
const maxLoan = allowablePayment > 0
  ? allowablePayment * ((Math.pow(1 + client.rate / 12, client.termMonths) - 1) /
    (client.rate / 12 * Math.pow(1 + client.rate / 12, client.termMonths)))
  : 0;

// Currency conversion (if needed)
const loanInClientCurrency = maxLoan * (client.exchangeRate || 1);

output.calculationResults = {
  weightedIncome,
  monthlyDebt,
  dti: Math.round(dti * 10000) / 10000,
  ltv: Math.round((client.requestedLoan / client.propertyValue) * 10000) / 10000,
  maxLoanAmount: Math.round(loanInClientCurrency),
  meetsIncomeThreshold: weightedIncome >= params.min_income_threshold,
  meetsLtvRequirement: (client.requestedLoan / client.propertyValue) <= params.max_ltv
};
```

> [!TIP]
>
> Keep Script nodes focused on a single calculation domain (e.g., financial formulas in one node, scoring in another). This makes each node independently testable and easier to audit.

***

### Step 3: AI understanding (qualitative filtering)

Add a TEXT\_UNDERSTANDING node to filter or classify products based on criteria that do not reduce to simple boolean checks — loan type preferences, sustainability features, qualitative fit.

#### Instructions

```text theme={"dark"}
You are a mortgage product filter. Given the client's preferences and a list of available
products, evaluate each product against the qualitative criteria.

Client preferences:
- Loan type preference: {{input.clientData.loanTypePreference}}
- Values sustainability features: {{input.clientData.sustainabilityPreference}}
- Risk tolerance: {{input.clientData.riskTolerance}}

For each product, return:
- product_id: the product identifier
- qualitative_match_score: a number between 0 and 1
- match_reasons: brief explanation of why it matches or does not match
- disqualified: boolean, true if the product is fundamentally incompatible

Only return products where disqualified is false.
```

#### Response Schema

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "filtered_products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "product_id": { "type": "string" },
          "qualitative_match_score": { "type": "number" },
          "match_reasons": { "type": "string" },
          "disqualified": { "type": "boolean" }
        },
        "required": ["product_id", "qualitative_match_score", "disqualified"]
      }
    }
  },
  "required": ["filtered_products"]
}
```

| Setting | Value |
| - | - |
| **Node type** | `TEXT_UNDERSTANDING` |
| **Input** | Client preferences + product catalog |
| **Response Key** | `filteredProducts` |

***

### Step 4: Business rules (scoring and ranking)

Add a second Script node to normalize scores and produce a final ranked list. This node combines the deterministic calculation results from Step 2 with the AI qualitative scores from Step 3 into a single weighted ranking.

#### Example script

```javascript theme={"dark"}
const calcResults = input.calculationResults;
const aiFiltered = input.filteredProducts.output.filtered_products;

// Scoring weights
const WEIGHT_RATE = 0.35;
const WEIGHT_QUALITATIVE = 0.25;
const WEIGHT_LTV = 0.20;
const WEIGHT_FLEXIBILITY = 0.20;

const scored = aiFiltered.map(product => {
  const details = input.productCatalog.find(p => p.id === product.product_id);
  if (!details) return null;

  // Normalize rate score (lower rate = higher score)
  const rateScore = 1 - (details.rate / 0.10); // Normalize against 10% max

  // LTV score (how close to max allowed)
  const ltvScore = details.maxLtv >= calcResults.ltv ? 1.0 : details.maxLtv / calcResults.ltv;

  // Flexibility score (prepayment, term options)
  const flexScore = (details.allowsPrepayment ? 0.5 : 0) +
                    (details.flexibleTerm ? 0.5 : 0);

  const totalScore = (rateScore * WEIGHT_RATE) +
                     (product.qualitative_match_score * WEIGHT_QUALITATIVE) +
                     (ltvScore * WEIGHT_LTV) +
                     (flexScore * WEIGHT_FLEXIBILITY);

  return {
    productId: product.product_id,
    bankName: details.bankName,
    totalScore: Math.round(totalScore * 1000) / 1000,
    breakdown: { rateScore, qualitativeScore: product.qualitative_match_score, ltvScore, flexScore },
    matchReasons: product.match_reasons
  };
}).filter(Boolean);

// Sort descending by total score
scored.sort((a, b) => b.totalScore - a.totalScore);

output.rankedProducts = scored.slice(0, 5); // Top 5
output.topRecommendation = scored[0] || null;
```

***

### Step 5: AI generation (report)

Add a TEXT\_GENERATION node at the end to produce a professional consultant report summarizing the analysis and recommendations.

#### Instructions

```text theme={"dark"}
You are a professional mortgage consultant. Generate a concise recommendation report
for the client based on the following analysis results.

Client profile:
- Weighted monthly income: {{input.calculationResults.weightedIncome}}
- Debt-to-income ratio: {{input.calculationResults.dti}}
- Maximum eligible loan: {{input.calculationResults.maxLoanAmount}}

Top recommended products (ranked):
{{input.rankedProducts}}

Structure the report as:
1. Executive summary (2-3 sentences)
2. Eligibility assessment (income qualification, DTI status)
3. Top 3 product recommendations with key differentiators
4. Next steps for the client

Use professional financial language. Do not include disclaimers about being an AI.
```

| Setting | Value |
| - | - |
| **Node type** | `TEXT_GENERATION` |
| **Input** | Calculation results + ranked products |
| **Response Key** | `consultantReport` |

***

## Pipeline summary

| Step | Node type | Purpose | Output |
| - | - | - | - |
| 1 | DOCUMENT\_EXTRACTION | Extract income weights, debt factors from bank rule documents | Structured financial parameters |
| 2 | Script node | Compute PMT, DTI, max loan amount, currency conversion | Deterministic calculation results |
| 3 | TEXT\_UNDERSTANDING | Filter products by qualitative criteria with fuzzy matching | Scored and filtered product list |
| 4 | Script node | Normalize scores, apply weight matrix, rank top products | Final ranked recommendations |
| 5 | TEXT\_GENERATION | Generate professional consultant report | Human-readable recommendation report |

***

## Real-world example

The [Mortgage advisor chatbot](../tutorials/mortgage-advisor) tutorial implements this pattern in its product recommendation handler. When a user asks for mortgage product recommendations, the workflow:

1. Extracts financial parameters from each bank's rule documents
2. Computes eligibility using exact financial formulas (PMT, DTI)
3. Filters the product catalog using AI-driven qualitative matching
4. Ranks the remaining products with a deterministic scoring matrix
5. Generates a personalized consultant report

The full pipeline processes 7 banks in parallel using a fan-out structure, then merges results for the final ranking.

***

## Variations

### Human-in-the-loop

Add approval gates after AI steps to let a human reviewer verify the AI output before it feeds into business rules. This is useful during initial deployment or in high-stakes decisions.

```
AI EXTRACTION --> [Human review gate] --> BUSINESS RULES --> AI UNDERSTANDING --> [Human review gate] --> BUSINESS RULES --> AI GENERATION
```

Implement the review gates using User Task nodes in the parent BPMN process. The reviewer sees the AI output and can correct it before the workflow continues.

### Confidence-weighted rules

Instead of treating AI output as binary (pass/fail), feed the AI confidence score into the business rules as a weight. Low-confidence AI extractions trigger stricter thresholds or flag the result for manual review.

```javascript theme={"dark"}
// Adjust DTI threshold based on extraction confidence
const extractionConfidence = input.extractedParams.confidence || 1.0;
const baseMaxDti = 0.43;

// Lower confidence = stricter threshold (more conservative)
const adjustedMaxDti = baseMaxDti * extractionConfidence;

output.meetsAdjustedDti = calcResults.dti <= adjustedMaxDti;
output.confidenceAdjustment = {
  original: baseMaxDti,
  adjusted: adjustedMaxDti,
  confidence: extractionConfidence
};
```

### Multi-source comparison

Extend the pattern to process documents from multiple banks or sources in parallel (using the [Fan-out extraction](./fan-out-extraction) pattern), then merge the results into a single comparison matrix before the scoring step. This is the approach used in the mortgage advisor for comparing products across 7 banks.

***

## Related resources

> [card] [AI patterns overview](./overview)
>
> All available patterns and how to combine them

> [card] [Fan-out extraction](./fan-out-extraction)
>
> Parallel document classification and extraction

> [card] [Mortgage advisor tutorial](../tutorials/mortgage-advisor)
>
> Full implementation of hybrid AI + business rules

> [card] [AI node types](../agent-builder/node-types)
>
> Reference for DOCUMENT\_EXTRACTION, TEXT\_UNDERSTANDING, and TEXT\_GENERATION


# Intent classification and routing
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/intent-classification-routing

Classify user input into intent categories and route to specialized handlers. Use the dedicated Intent Classification Agent node (5.6+) for most cases, or the TEXT_UNDERSTANDING + Condition pattern for advanced scenarios.

## When to use

Use this pattern when your workflow must handle multiple types of user input and respond differently depending on what the user wants. Intent classification is the foundation of any conversational AI app on FlowX — it determines what happens next.

Common scenarios:

* A chatbot that must distinguish greetings from product inquiries from data submissions
* An email triage pipeline that routes messages to different processing branches
* Any multi-turn conversation where the next step depends on user intent

Without intent classification, a workflow can only follow a single linear path regardless of what the user says.

***

## Recommended: Intent Classification Agent node (5.6+)

```
User message
    |
    v
Intent Classification Agent node
(one output port per intent + built-in If No Intent Matches fallback)
    |
    +--> Handler A (e.g., greeting response)
    +--> Handler B (e.g., product inquiry)
    +--> Handler C (e.g., data input)
    +--> If No Intent Matches (fallback, always present)
```

Benefits over the legacy pattern:

* **No Condition node** — each intent gets its own output port automatically
* **Built-in fallback** — `If No Intent Matches` is always-present and can't be accidentally omitted
* **Use conversation memory** (Chat Driven workflows) — the classifier can factor in the last few turns when resolving ambiguous messages (e.g., "yes", "tell me more")
* **Include Reason for Selection** — the classifier can emit its rationale, useful for tuning labels during development
* **Up to 10 intents per node** — chain multiple Intent Classification Agent nodes for deeper taxonomies

See the [Intent Classification Agent node reference](../agent-builder/intent-classification) for full configuration details.

### When to use the legacy pattern below

The TEXT\_UNDERSTANDING + Condition pattern remains valid for advanced cases the dedicated node does not cover:

* **Confidence-based routing** — branching on a numeric confidence score, not just the winning label
* **Multi-label classification** — one message may match several intents simultaneously; the Condition node can fire multiple downstream paths
* **Custom post-processing** — applying business rules on the raw LLM output before routing (e.g., demoting an intent below a business-defined threshold)

***

## Legacy pattern: TEXT\_UNDERSTANDING + Condition

The pattern follows a detect-then-route structure:

```
User message
    |
    v
TEXT_UNDERSTANDING node
(classifies intent, returns structured JSON)
    |
    v
Condition node (Python expressions)
    |
    +--> Handler A (e.g., greeting response)
    +--> Handler B (e.g., product inquiry)
    +--> Handler C (e.g., data input)
    +--> Fallback (unrecognized intent)
```

The TEXT\_UNDERSTANDING node analyzes the user message and returns a structured JSON object with the detected intent. The Condition node evaluates that output and forks the workflow to the appropriate handler branch.

### Implementation

#### 1. Configure the TEXT\_UNDERSTANDING node

Add a TEXT\_UNDERSTANDING node to your workflow. This node sends the user message to an LLM with a classification prompt and enforces a structured response via a Response Schema.

#### Prompt

The prompt should instruct the LLM to classify the input into one of your defined intent categories. Be explicit about the categories and expected output format.

```text theme={"dark"}
You are an intent classifier. Analyze the user message and classify it into exactly one
of the following intent categories:

- GREETING_SMALL_TALK — greetings, pleasantries, general conversation
- PRODUCT_OFFER_INQUIRY — questions about products, services, pricing, or features
- DATA_INPUT_UPDATE — the user is providing or updating personal data, documents, or form fields
- OTHER — anything that does not fit the above categories

Return a JSON object with:
- detected_intent: one of the categories above (exact string)
- confidence_score: a number between 0 and 1
- thought_process: a brief explanation of why you chose this category
- extracted_entities: (optional) any relevant entities found in the message

Do NOT include any text outside the JSON object.
```

> [!TIP]
>
> Keep the prompt focused on classification only. Resist adding response generation here — that belongs in the handler branches downstream.

#### Response Schema

Define a Response Schema on the TEXT\_UNDERSTANDING node to enforce structured output. This guarantees the LLM returns valid JSON matching your expected shape.

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "detected_intent": {
      "type": "string",
      "enum": [
        "GREETING_SMALL_TALK",
        "PRODUCT_OFFER_INQUIRY",
        "DATA_INPUT_UPDATE",
        "OTHER"
      ]
    },
    "confidence_score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "thought_process": {
      "type": "string"
    },
    "extracted_entities": {
      "type": "object"
    }
  },
  "required": ["detected_intent", "confidence_score", "thought_process"]
}
```

#### Configuration summary

| Setting | Value |
| - | - |
| **Node type** | `TEXT_UNDERSTANDING` |
| **Input** | User message (from Chat Input node or upstream variable) |
| **Response Key** | Configure a response key (e.g., `routesKey`) to store the classification result |
| **Response Schema** | The JSON schema from the [Response Schema](#response-schema) section |

***

#### 2. Configure the Condition node

After the TEXT\_UNDERSTANDING node, add a Condition node to fork the workflow based on the detected intent. Each branch uses a Python expression that evaluates to `True` or `False`.

#### Condition expressions

Use substring matching with the `in` operator for resilience. This handles cases where the LLM wraps the intent in extra whitespace or slightly different formatting.

```python theme={"dark"}
# Branch: Greeting / small talk
"GREETING" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))
```

```python theme={"dark"}
# Branch: Product inquiry
"PRODUCT_OFFER" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))
```

```python theme={"dark"}
# Branch: Data input / update
"DATA_INPUT" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))
```

```python theme={"dark"}
# Branch: Fallback (default)
# No condition needed — this is the default/else branch
```

> [!WARNING]
>
> Always include a fallback branch. Even with a Response Schema, edge cases can produce unexpected intent values. The fallback branch prevents the workflow from stalling.

> [!TIP]
>
> Use substring matching (`in` operator) instead of exact equality (`==`). This makes the condition resilient to minor LLM output variations without sacrificing accuracy.

#### Condition node summary

| Branch | Expression | Routes to |
| - | - | - |
| **Greeting** | `"GREETING" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))` | Greeting handler |
| **Product inquiry** | `"PRODUCT_OFFER" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))` | Product info handler |
| **Data input** | `"DATA_INPUT" in str(input.get("routesKey", {}).get("output", {}).get("detected_intent", ""))` | Data processing handler |
| **Fallback** | Default branch | Generic response or clarification prompt |

***

#### 3. Build handler branches

Each handler branch is a self-contained sub-workflow tailored to the classified intent. Examples:

* **Greeting handler** — responds with a welcome message or continues small talk using a text generation node
* **Product inquiry handler** — queries a knowledge base (see the [Knowledge base RAG](./knowledge-base-rag) pattern) and returns product information
* **Data input handler** — validates and stores user-provided data, then confirms receipt
* **Fallback handler** — asks the user to rephrase or provides a generic help message

After all branches complete their work, they converge back to a shared endpoint (typically the End Flow node).

***

## Real-world example

The [Mortgage advisor chatbot](../tutorials/mortgage-advisor) tutorial implements this pattern as its core routing mechanism. User messages are classified into intents such as greeting, product inquiry (mortgage offers), data submission (income, employment), and general questions — then routed to specialized handlers that combine knowledge base lookups, financial calculations, and conversational responses.

***

## Variations

### Binary classification

When you only need to distinguish between two outcomes (e.g., yes/no, relevant/irrelevant), simplify the schema to a single boolean or two-value enum. Use a single Condition branch instead of multiple forks.

```json theme={"dark"}
{
  "type": "object",
  "properties": {
    "is_relevant": {
      "type": "boolean"
    },
    "confidence_score": {
      "type": "number"
    }
  },
  "required": ["is_relevant", "confidence_score"]
}
```

### Multi-label classification

Some inputs may belong to multiple categories simultaneously (e.g., a message that both provides data and asks a question). Modify the schema to return an array of intents, and use parallel paths (**Start Parallel Path** / **End Parallel Path** nodes) to handle each detected intent.

### Confidence-based routing

Add a confidence threshold check before routing. If the confidence score falls below a threshold (e.g., 0.7), route to a human review queue or ask the user to clarify instead of proceeding with low-confidence automation.

```python theme={"dark"}
# High confidence — route normally
float(input.get("routesKey", {}).get("output", {}).get("confidence_score", 0)) >= 0.7
```

```python theme={"dark"}
# Low confidence — route to human review or clarification
float(input.get("routesKey", {}).get("output", {}).get("confidence_score", 0)) < 0.7
```

***

## Related resources

> [card] [AI patterns overview](./overview)
>
> All available patterns and how to combine them

> [card] [AI node types](../agent-builder/node-types)
>
> Reference for TEXT\_UNDERSTANDING and other node types

> [card] [Mortgage advisor tutorial](../tutorials/mortgage-advisor)
>
> End-to-end implementation using intent classification

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Multi-turn chat with session memory and intent routing


# Knowledge base RAG
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/knowledge-base-rag

Ground AI responses in your documents using retrieval-augmented generation with Qdrant vector search and the CUSTOM_AGENT node.

Retrieval-augmented generation (RAG) lets an AI agent answer questions by searching your documents first, then synthesizing a response from only the retrieved context. This eliminates hallucinations and keeps answers grounded in your actual content.

SaaS · 5.11

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.11.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Each Knowledge Base indexes its content with a single embedding model, chosen before the first store is built and then locked. From FlowX.AI 6.0 on SaaS (SaaS · 6.0), turning **Containing Personal Information** on or off later re-embeds the existing content with the new model. Knowledge Bases that do not hold personal data use the organization default cloud embedding model. Knowledge Bases marked as **Containing Personal Information** use a **local** embedding model instead, so their content is embedded on-box and never sent to an external provider. A local embedding model is a **CUSTOM** organization AI provider that fronts any OpenAI-compatible on-box endpoint. See [Knowledge Base overview](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).

***

## When to use

Use this pattern when:

* Users need accurate answers drawn from a specific document corpus (product sheets, FAQs, regulatory guides, policies)
* Responses must cite sources and avoid fabrication
* The knowledge changes over time and you want to update documents without retraining a model
* You need domain-specific answers that a general-purpose LLM cannot reliably provide

Do **not** use this pattern when:

* The answer requires real-time data from an external API (use an MCP integration instead)
* The task is classification or extraction rather than open-ended Q\&A (use TEXT\_UNDERSTANDING or TEXT\_EXTRACTION nodes)
* The corpus is very small (fewer than 5 documents) and could fit entirely in a system prompt

***

## Architecture

```
User question
    |
    v
+---------------------------+
| CUSTOM_AGENT node         |
| (with Knowledge Base tool)|
+---------------------------+
    |
    v
+---------------------------+
| Qdrant vector search      |
| (Top K chunks retrieved)  |
+---------------------------+
    |
    v
+---------------------------+
| LLM synthesis             |
| (answer from context only)|
+---------------------------+
    |
    v
Grounded response
```

The CUSTOM\_AGENT node handles the full cycle internally. The Knowledge Base is a retrieval tool, so the agent decides when to search it; to retrieve on every run, add a [Context Retrieval](/5.9/ai-platform/agent-builder/context-retrieval) node before the agent. A typical run:

1. Analyzes the user query for key terms and intent
2. Searches the connected Qdrant collection for relevant document chunks
3. Receives the top matching chunks ranked by relevance score
4. Synthesizes a response using **only** the retrieved context
5. Returns a grounded answer with source references

***

## Implementation

### Prerequisites

Before configuring the workflow:

* Create a **Knowledge Base** data source in Integration Designer
* Upload your documents (PDFs) to one or more stores in the Knowledge Base
* Wait for automatic chunking and vector indexing to complete

> [!NOTE]
>
> Knowledge Bases use vector embeddings stored in Qdrant for semantic search. Documents are automatically chunked and indexed when uploaded. For details, see the [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview) documentation.

### Configure the CUSTOM\_AGENT node

**1. Add a CUSTOM\_AGENT node to your workflow**

In the Agent Builder canvas, drag a **Custom Agent** node into your workflow.

**2. Turn on Knowledge Base**

In the node configuration panel, scroll to the **Knowledge Base** section and turn it on. Select the Knowledge Base you created.

**3. Set retrieval parameters**

Configure how the agent searches your documents.

**4. Write the Instructions**

In the **Instructions** field, define the agent behavior, retrieval guidance, and response constraints (see the template below).

### Retrieval parameters

| Parameter | Description | Recommended value |
| - | - | - |
| **Number of Chunks** | Number of document chunks retrieved per query (1-10) | `10` |
| **Min. Relevance Score** | Relevance threshold (0-100%). Chunks below this score are excluded | `10` |
| **Metadata Filters** | Restrict search using typed conditions. Use the system `source` key to scope to a specific store | No filters (search all stores) |

> [!TIP]
>
> Start with a low **Min. Relevance Score** (around 10%) and increase it if the agent returns too much irrelevant context. A high threshold may cause the agent to miss relevant chunks that use different terminology than the query.

### Instructions template

The Instructions must tell the agent to search the Knowledge Base and follow strict grounding rules.

```text theme={"dark"}
You are a knowledgeable assistant. Your job is to answer user questions
accurately using ONLY information retrieved from the knowledge base.

INSTRUCTIONS:
1. Analyze the user's question to identify key terms and concepts.
2. Search the knowledge base for relevant information.
3. Synthesize a clear, concise response from ONLY the retrieved context.

STRICT RULES:
- Source fidelity: Base every claim on retrieved document chunks. If the
  knowledge base does not contain relevant information, say: "I don't have
  information about that in my current knowledge base."
- Citations: Reference the source document when possible.
- No hallucinations: Never fabricate information, statistics, or claims
  not present in the retrieved context.
- Stay on topic: Only answer questions related to the knowledge base domain.
```

> [!WARNING]
>
> The grounding rules are critical. Without explicit instructions to admit gaps in knowledge, the LLM may fall back to its general training data and produce inaccurate answers.

### Input and output

| Direction | Key | Description |
| - | - | - |
| **Input** | User message (from chat or process data) | The question to answer |
| **Output** | Agent response text | The grounded answer synthesized from retrieved chunks |

> [!NOTE]
>
> Each retrieved chunk in the RAG result carries a `chunkId` and a `createdAt` ingestion timestamp (UTC), alongside its content, relevance score, and metadata. `createdAt` is `null` for chunks that were indexed before the timestamp was introduced.

***

## Real-world example

The **mortgage advisor chatbot** tutorial uses this pattern in its `knowledgeBaseQA` workflow. When the intent classifier detects a `KNOWLEDGE_QA` intent, the router calls a CUSTOM\_AGENT node connected to a Knowledge Base containing mortgage product sheets, regulatory guides, and FAQ documents.

The agent answers questions such as:

* "What is DTI?" (retrieves debt-to-income ratio definition from the FAQ)
* "What are the requirements for a fixed-rate mortgage?" (retrieves eligibility criteria from product sheets)
* "What documents do I need to apply?" (retrieves checklist from the regulatory guide)

> [card] [Mortgage advisor tutorial](../tutorials/mortgage-advisor)
>
> Build the full chatbot including intent routing, knowledge base Q\&A, and recommendation generation

***

## Variations

### Multi-KB search

Query multiple Knowledge Base collections in a single workflow. Use parallel CUSTOM\_AGENT nodes, each connected to a different Knowledge Base, then merge the results in a downstream node.

**When to use:** Your documents span distinct domains (for example, product documentation and regulatory compliance) that are better organized in separate collections.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

Starting with 5.9.2, a single Custom Agent node can select **multiple Knowledge Bases** directly in its Knowledge Base section, replacing the parallel-nodes workaround for most cases.

### Hybrid search

Combine vector (semantic) search with keyword search for better recall. Set **Search Type** to `Hybrid` (the default — since 5.7 on the CUSTOM\_AGENT node, since 5.6 on CONTEXT\_RETRIEVAL). Choose `Semantic` for purely meaning-based retrieval, or `Keywords` when exact-token matches matter more than similarity.

**When to use:** Your documents contain precise terminology (part numbers, policy codes, legal references) where exact keyword matching outperforms semantic similarity alone.

### Re-ranking

Turn on **Use Re-rank** on the CUSTOM\_AGENT or CONTEXT\_RETRIEVAL node to apply a second-pass ranking step to the retrieved chunks before the LLM sees them. Combined with Hybrid search, re-ranking materially improves answer quality on mixed numeric + natural-language queries.

**When to use:** The initial retrieval returns many marginally relevant chunks and you need higher precision in the final response. Pre-5.7, this required a manual two-step pattern (separate TEXT\_GENERATION node scoring the chunks) — now it's a single toggle.

***

## Best practices

> [accordion] Prepare your documents
>
> Upload clean, well-structured documents. Remove headers, footers, and boilerplate that add noise. Organize documents into separate stores by topic for easier filtering.

> [accordion] Test retrieval before building the workflow
>
> Use the Knowledge Base test interface to run sample queries and verify that relevant chunks are returned with acceptable relevance scores before wiring the node into a workflow.

> [accordion] Tune retrieval parameters iteratively
>
> Start with a higher Number of Chunks (8-10) and a lower Min. Relevance Score (10-20%). Monitor the chunks returned and adjust. Too few results leads to incomplete answers; too many leads to diluted context.

> [accordion] Keep prompts explicit about limitations
>
> Always include instructions for what the agent should do when the Knowledge Base does not contain relevant information. This prevents the LLM from falling back to general knowledge.

***

## Related resources

> [card] [Patterns overview](./overview)
>
> All available AI patterns

> [card] [Node types](../agent-builder/node-types)
>
> AI node type reference including Custom Agent

> [card] [Knowledge Base integration](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
>
> Create and manage Knowledge Bases

> [card] [Mortgage advisor tutorial](../tutorials/mortgage-advisor)
>
> Full tutorial using this pattern


# Session state management
Source: https://docs.flowx.ai/5.9/ai-platform/patterns/session-state-management

Manage conversation history and session state across multi-turn interactions using FlowX Database workflows.

## Overview

AI nodes in FlowX workflows are stateless — each invocation starts fresh with no memory of previous turns. For multi-turn conversations such as chatbots, advisors, or guided flows, you need a strategy to persist and reload conversation history between interactions.

This pattern uses a **FlowX Database** data source to store session state, loading it at the start of each turn and saving the updated history after the AI response.

***

## When to use

* Multi-turn chatbots or conversational assistants
* Guided workflows where the AI needs context from earlier steps
* Any scenario where the user returns to a conversation after a delay
* Task-oriented workflows requiring custom memory strategies

***

## Architecture

The session state management pattern follows a read-process-write cycle on every turn:

```
User message
  → Load session (DB read)
    → Inject history into prompt
      → AI processing
        → Append exchange to history
          → Save session (DB write)
            → Response to user
```

Each workflow invocation performs these steps:

1. **Load** — Query the `ChatSessions` data source by `sessionId` to retrieve existing conversation history.
2. **Inject** — Insert the retrieved history into the AI node's operation prompt as context.
3. **Process** — The AI node generates a response informed by the full conversation context.
4. **Append** — Add both the user message and the AI response to the `messages` array.
5. **Save** — Write the updated session back to the data source.

***

## Data model

Create a **FlowX Database** data source named `ChatSessions` with the following schema:

| Field | Type | Description |
| - | - | - |
| **sessionId** | `STRING` | Unique identifier for the conversation session |
| **messages** | `OBJECT[]` | Array of message objects storing the conversation history |

Each entry in the `messages` array follows this structure:

| Field | Type | Description |
| - | - | - |
| **role** | `STRING` | The message author — `user` or `assistant` |
| **content** | `STRING` | The text content of the message |

Example stored session:

```json theme={"dark"}
{
  "sessionId": "sess-a1b2c3d4",
  "messages": [
    { "role": "user", "content": "I want to apply for a mortgage." },
    { "role": "assistant", "content": "I can help with that. What type of property are you looking to finance?" },
    { "role": "user", "content": "A single-family home, around 250,000 EUR." },
    { "role": "assistant", "content": "Great. Do you have a preferred loan term — 15, 20, or 30 years?" }
  ]
}
```

***

## Implementation

**1. Create the ChatSessions data source**

In the **Integration Designer**, add a new **FlowX Database** data source named `ChatSessions`. For its collection schema, select a project data model type with a `sessionId` attribute (type STRING) and a `messages` attribute (type OBJECT with the **Array** flag).

**2. Load session history at workflow start**

Add a **Database Operation** node at the beginning of your workflow, configured with a `findOne` operation that reads from `ChatSessions`, filtering by the incoming `sessionId`. If no session exists, initialize an empty messages array.

**3. Inject history into the AI node context**

In the AI node's **Context** field, include the loaded conversation history. Format the messages array into a readable block:

```text theme={"dark"}
Previous conversation:
User: I want to apply for a mortgage.
Assistant: I can help with that. What type of property are you looking to finance?
User: A single-family home, around 250,000 EUR.
Assistant: Great. Do you have a preferred loan term — 15, 20, or 30 years?

Current user message: {currentMessage}
```

Use a **Script** node before the AI node to transform the `messages` array into this string format, and reference the result in the AI node's **Context** field with a `${...}` key.

**4. Append the new exchange to history**

After the AI node produces a response, use a **Script** node to append two new entries to the `messages` array:

```json theme={"dark"}
[
  { "role": "user", "content": "{currentMessage}" },
  { "role": "assistant", "content": "{aiResponse}" }
]
```

**5. Save the updated session**

Add a **Database Operation** node that writes the updated session back to the `ChatSessions` data source. Use an `updateOne` operation keyed by `sessionId` for existing sessions; when the initial `findOne` returned no session, route to an `insertOne` operation instead (for example, via a Condition node on the load result).

***

## Context window management

Long conversations can exceed the AI model's context window or degrade response quality. Use these strategies to keep history manageable:

### Summarization

For conversations exceeding a threshold (for example, 20 turns), use a separate AI node to generate a summary of older messages. Replace the full history with:

```text theme={"dark"}
Summary of earlier conversation:
The user is applying for a 30-year mortgage on a 250,000 EUR single-family home.
They have a 50,000 EUR down payment and prefer a fixed rate.

Recent conversation:
User: What documents do I need to provide?
Assistant: You will need proof of income, bank statements, and a property appraisal.
```

This preserves key context while staying within token limits.

### Token counting

Track approximate token usage for the history block. When it approaches 60-70% of the model's context window, trigger summarization. This leaves sufficient room for the system prompt, current message, and the AI response.

***

## Real-world example

The **Mortgage advisor chatbot** tutorial shows multi-turn advising using the built-in session memory. Use that tutorial for a Chat Driven walkthrough; refer to this pattern if you need a custom memory strategy (sliding window, topic-based, cross-session) for a task-oriented workflow instead.

For the tutorial, see the [Mortgage advisor tutorial](../tutorials/mortgage-advisor).

***

## Variations

### Sliding window

Keep only the last **N** turns (for example, 10) in the prompt context. Older messages remain stored in the database for audit purposes but are not injected into the prompt. This is the simplest approach and works well for short, focused conversations.

### Topic-based memory

Partition conversation history by topic. When the user switches subjects, start a new topic segment while retaining a brief summary of previous topics. This works well for advisor-style bots that cover multiple domains in one session.

### Cross-session memory

Maintain a persistent **user profile** that carries context across separate conversations. Store preferences, decisions, and key facts in a dedicated data source keyed by user ID rather than session ID. Inject a profile summary at the start of each new session so the AI can reference prior interactions.

***

## Related resources

> [card] [AI patterns overview](./overview)
>
> All available AI integration patterns

> [card] [Chat-driven workflows](../chat-driven-workflows)
>
> Built-in session memory in FlowX 5.6+

> [card] [Mortgage advisor tutorial](../tutorials/mortgage-advisor)
>
> End-to-end chatbot with session persistence

> [card] [Intent classification pattern](./intent-classification-routing)
>
> Route user messages to specialized handlers


# Container app authentication
Source: https://docs.flowx.ai/5.9/docs/saas/container-app-authentication

Configure authentication flows, landing pages, and session management for container applications that embed FlowX UI Flows.

## Overview

A **container app** is any web or mobile application that embeds FlowX UI Flows using the FlowX renderers (Angular, React, React Native, iOS, or Android SDKs). Container apps are responsible for authenticating end users before rendering FlowX content.

The container app authentication flow provides built-in support for OAuth2/OIDC authentication, custom landing pages, and session management.

***

## Key features

> [card] Authentication providers
>
> Support for multiple OAuth2/OIDC authentication providers via Keycloak integration

> [card] Custom landing page
>
> Configure a landing page for unauthenticated users with organization branding

> [card] Session management
>
> Automatic token refresh, silent refresh support, and redirect URI persistence

> [card] SSO integration
>
> Single sign-on across container apps within the same organization

***

## How it works

The container app authentication flow handles the following:

**1. Organization resolution**

The container app resolves the organization context using the hostname or an organization code. This determines which Keycloak realm and authentication configuration to use.

**2. Authentication redirect**

Unauthenticated users are redirected to the configured identity provider (Keycloak) for login. The redirect URI is persisted in local storage to restore the user's navigation state after authentication.

**3. Token management**

After successful authentication, the container app manages access tokens with automatic refresh. Silent refresh keeps the session alive without requiring user interaction.

**4. UI Flow rendering**

Once authenticated, the container app renders FlowX UI Flows with the user's identity and permissions.

***

## Configuration

### Authentication setup

Container apps authenticate using OAuth2/OIDC with the following configuration:

| Parameter | Description |
| - | - |
| **Organization code** | Identifies the organization for multi-tenant environments. Can be derived from the hostname or provided explicitly. |
| **Keycloak realm** | The Keycloak realm associated with the organization |
| **Client ID** | The OAuth2 client ID registered in Keycloak for the container app |
| **Redirect URI** | The URI to redirect to after authentication. Persisted across browser sessions. |

> [!TIP]
>
> For multi-tenant SaaS deployments, the organization code is typically extracted from the subdomain (e.g., `acme.flowx.ai` resolves to organization `acme`).

### Landing page

You can configure a custom landing page that appears for unauthenticated users. This page can include:

* Organization branding and logo
* Login button that initiates the authentication flow
* Links to support or documentation

> [card] [Container app branding](./container-app-branding)
>
> Customize colors, logo, and header appearance for the container app

### Session behavior

| Behavior | Description |
| - | - |
| **Token refresh** | Access tokens are refreshed automatically before expiration |
| **Silent refresh** | Background token renewal without user interaction |
| **Redirect persistence** | The user's intended destination is stored and restored after login |
| **Session timeout** | Configurable session duration based on Keycloak realm settings |

***

## SDK integration

Each FlowX renderer SDK handles container app authentication:

> [tab] Angular
>
> The Angular SDK integrates with `angular-oauth2-oidc` for authentication handling. Configure the OAuth2 module in your app with the Keycloak endpoints for your organization.
>
> For setup details, see the [Angular SDK documentation](/5.9/sdks/angular-renderer).

> [tab] React
>
> The React SDK provides authentication hooks that connect to your Keycloak instance.
>
> For setup details, see the [React SDK documentation](/5.9/sdks/react-renderer).

> [tab] React Native
>
> The React Native SDK is being introduced in FlowX.AI 5.9.0. Authentication integration details will be added once the SDK ships.
>
> For setup details, see the [React Native SDK documentation](/5.9/sdks/react-native-renderer).

> [tab] iOS
>
> The iOS renderer handles OAuth2 authentication natively with secure token storage in the keychain.
>
> For setup details, see the [iOS SDK documentation](/5.9/sdks/ios-renderer).

> [tab] Android
>
> The Android renderer integrates with AppAuth for secure OAuth2 authentication.
>
> For setup details, see the [Android SDK documentation](/5.9/sdks/android-renderer).

***

## Related resources

> [card] [IAM Configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution)
>
> Set up Keycloak realms, clients, and service accounts

> [card] [UI Flows](/5.9/docs/building-blocks/ui-flows)
>
> Learn about UI Flows and how they render in container apps

> [card] [FlowX SaaS Overview](/5.9/docs/saas/saas-overview)
>
> Understand the FlowX SaaS deployment model

> [card] [Workspaces & Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights)
>
> Configure workspace-level access control


# Container app branding
Source: https://docs.flowx.ai/5.9/docs/saas/container-app-branding

Customize the visual appearance of the SaaS container app with organization-level branding settings.

## Overview

**Container app branding** lets organization administrators customize the visual appearance of the SaaS container app — the runtime that wraps FlowX solutions for end users. Branding settings apply organization-wide across all workspaces and projects.

> [card] Custom colors
>
> Set primary, secondary, header, and page background colors

> [card] Logo upload
>
> Replace the default logo with your organization's branding

> [card] Header control
>
> Show or hide the container app header (useful for iframe embeds)

> [card] Live preview
>
> Preview branding changes before saving

***

## Accessing branding settings

To configure branding:

1. Navigate to **Organization Admin** in FlowX Designer
2. Select **Generic App Branding** under **Design Assets**

> [!NOTE]
>
> Branding settings require the `org_branding_read` permission to view and `org_branding_edit` permission to modify.

The branding page has a form panel on the left and a live preview on the right. Use the layout toggle in the header to switch between flat view, accordion view, or form-only mode.

***

## Branding properties

### General

**Primary Color** `hex color`

Accent color used for buttons, active states, and interactive elements on the solutions page.

**Secondary Color** `hex color`

Used for avatar backgrounds and secondary accents.

***

### Header

**Show Header** `boolean`

Toggle the container app header on or off.

**Default:** ON

> [!TIP]
>
> Turn off the header when embedding the container app in an iframe where the parent app provides its own navigation.

**Logo** `file upload`

Custom logo displayed in the header. Replaces the default FlowX logo.

**Supported formats:** PNG, JPG, SVG, WEBP

**Max file size:** 2 MB

**Background Color** `hex color`

Header background color.

**Default:** `#2A313A`

**Shadow** `preset`

Header drop shadow. Choose from preset sizes or turn off completely.

**Options:** None, XS, S, M, L, XL

Each preset configures the shadow color, opacity, and blur radius.

***

### Solutions page

**Page Background Color** `hex color`

Background color of the solutions landing page where users select which solution to open.

***

## How branding is applied

When an end user loads the container app:

1. The app resolves the organization context (from the hostname or organization code)
2. Branding configuration is included in the organization lookup API response
3. The container app applies branding values as CSS custom properties
4. Colors, logo, and header settings apply as soon as the app loads

Because branding travels with the organization lookup at app load, changes saved in the Designer reach end users the next time the container app loads. An already-open app keeps the branding it fetched at startup until it is reloaded.

> [!NOTE]
>
> Branding is applied before authentication, so the login landing page also reflects the organization's branding.

### Troubleshooting

> [accordion] Branding changes don't show up in the container app
>
> * **Reload the app fully.** Branding is fetched with the organization lookup when the app loads, so refresh the browser tab (or restart the mobile app) after saving changes.
> * **Check the organization.** The app resolves branding from the hostname or organization code it was opened with — confirm it matches the organization where you edited the branding settings.
> * **Confirm the save.** Reopen the branding settings in the Designer and verify the values (including the logo) were persisted and branding is turned on.

***

## Related resources

> [card] [Container app authentication](./container-app-authentication)
>
> Configure authentication flows and session management for container apps

> [card] [Organization settings](./organization-settings)
>
> Manage organization-level configuration

> [card] [FlowX SaaS overview](./saas-overview)
>
> Understand the FlowX SaaS deployment model


# Inviting Users
Source: https://docs.flowx.ai/5.9/docs/saas/inviting-users

Learn how Organization Admins can invite designer users to their organization via email with role assignments and secure activation.

## Overview

Organization Admins can invite designer users to their organization via email. Invited users receive a secure invitation link, can be pre-assigned roles and groups, and go through a guided activation flow before becoming active members.

> [!NOTE]
>
> Only users with the **Organization Admin** role can invite new designer users.

> [!NOTE]
>
> **SMTP is required.** Invitations and password-recovery emails are dispatched by Keycloak. On self-hosted deployments the client must configure SMTP in Keycloak (per realm) before either flow will work — without it, invitations fail silently. See [Email (SMTP) configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#email-smtp-configuration).

## Accessing user invitations

The invitation feature is available from the Designer Users page:

**1. Navigate to Designer Users**

Go to **Organization Settings** → **Access Management** → **Designer Users**

**2. Open the invite dialog**

Click **+** and select **Invite user**

![Invite User button in Designer Users page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/mti3.png)

## Invitation form

When inviting a new user, you can configure the following options:

| Field | Required | Description |
| - | - | - |
| **User Email** | Yes | Email address the invitation is sent to |
| **Organization Role** | Yes | **Organization Admin** or **Organization Owner** |
| **Set User First and Last Name** | No | Optionally pre-fill the user's first and last name |
| **Attributes** | No | Set custom user attributes |

End-users are invited from **Organization Settings** → **Access Management** → **End-Users**. The end-user invite form has **User Email**, **Set User First and Last Name**, **Groups**, and **Attributes**, with no organization role.

![Invitation form with email, roles, and groups fields](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/saas2.png)

> [!TIP]
>
> Pre-assigning roles and groups during invitation saves time and ensures users have the correct access from their first login.

## Creating a user directly

Instead of sending an invitation, an Organization Admin can create the account and set its password in one step. No invitation email is sent: share the credentials with the user through your own channel.

**1. Open the create dialog**

On the **Designer Users** or **End-Users** page, click **+** and select **Create user**. The **Create Designer User** or **Create End-User** dialog opens.

**2. Enter the account details**

Fill in **Email**, **First name**, **Last name**, **Password**, and **Confirm password**. **Username** is filled in from the email address. **User Status** is **ACTIVE** by default.

**3. Add groups and attributes (optional)**

For an end user, pick the groups the user belongs to. Add runtime attributes if needed.

**4. Create the user**

Click **Create**. A "User created successfully" notification confirms the account.

## Invitation workflow

### Sending an invitation

**1. Enter email address**

Provide the email address of the user you want to invite

**2. Configure access (optional)**

Select the organization role (designer users) or groups (end-users), and any attributes

**3. Send invitation**

Click **Send Invitation** to create the user and trigger the invitation email

When you send an invitation:

1. A user account is created in Keycloak with:
   * The provided email address
   * Selected runtime roles and groups
   * email verified set to `false`
   * Required actions: update password and update profile

2. A user record is created in FlowX with:
   * Assigned selections (roles, groups, attributes)
   * Status: **Pending**
   * Organization Owner role (if selected)

3. An invitation email is sent to the user

> [!TIP]
>
> A success notification confirms: "Invitation sent successfully"

### Invitation email

The invited user receives an email with the following content:

> [card] Invitation email
>
> **Subject:** You've been invited to your FlowX.ai account
>
> Hi,
>
> You've been invited to join the FlowX Platform to test our new Agentic Apps.
>
> This early access will let you explore how Agentic Apps work and give feedback on the experience before the broader rollout.
>
> **\[Accept Invitation]**
>
> Best

> [!WARNING]
>
> Invitation links are valid for **2 days**. After expiration, the user will need a new invitation.

## Inviting users from a CSV file

To invite many users at once, upload a CSV file.

**1. Open the bulk import dialog**

On the **Designer Users** or **End-Users** page, open the **⋮** menu and select **Import from CSV**. The **Bulk Import Designer Users from CSV** or **Bulk Import End-Users from CSV** dialog opens.

**2. Prepare the file**

Click **Download CSV Template** to get the expected columns, then fill in one user per row.

**3. Upload and import**

Add the file to the dialog, then click **Import File**. The dialog accepts CSV files up to 25 MB, with up to 500 users per file.

**4. Review the results**

The **Import Complete** screen shows how many users were invited (**Users Invited**) and how many were skipped (**Users Skipped**). Download the skipped rows as `import-skipped.csv` to see which rows were not imported.

The template columns depend on the page:

| Page | Columns |
| - | - |
| **Designer Users** | `email`, `firstName`, `lastName`, `organizationRole`, `allowNameEdit`, then one column per runtime attribute |
| **End-Users** | `email`, `firstName`, `lastName`, `groups`, `allowNameEdit`, then one column per runtime attribute. Separate several groups with `\|`. |

Rows whose email already belongs to a user in the organization are skipped. Imported users receive the same invitation email as a single invite.

## User activation flow

When the invited user clicks the invitation link, they complete a two-step activation process:

### Step 1: Set password

The user creates a secure password for their account:

* Minimum 8 characters, maximum 64 characters
* Must include at least one uppercase letter, one lowercase letter, one number, and one special character (`!@#$%^&*()_+-`)
* Cannot be the same as the user's email address
* Upon submission, proceeds to profile setup

### Step 2: Complete profile

The user provides their profile information:

| Field | Required | Description |
| - | - | - |
| **First name** | Yes | User's first name |
| **Last name** | Yes | User's last name |

Upon submission:

* User profile is updated with the provided information
* email is marked as verified
* User is redirected to the login page with a success message

### First login

After completing activation and logging in for the first time:

* User status changes from **Pending** to **Active**
* First name and last name are populated in the FlowX user profile
* User appears in the Designer Users list with Active status

## Handling expired invitations

If a user clicks an invitation link after it has expired (more than 2 days), they see an "Invite link expired" page.

> [!WARNING]
>
> To resolve an expired invitation, the Organization Admin needs to send a new invitation to the user.

## User statuses

| Status | Description |
| - | - |
| **Pending** | User has been invited but hasn't completed activation |
| **Active** | User has completed activation and logged in at least once |
| **Disabled** | User account has been deactivated by an administrator |

### Disabling and enabling users

Administrators can change an end-user's status from the **End-Users** page:

**1. Open user actions**

Find the user in the users list and open the context menu (three-dot menu)

**2. Select the action**

Choose **Disable** to deactivate an active user, or **Activate** to reactivate a disabled user

**3. Confirm the action**

Confirm the action in the dialog. The user's status updates immediately.

> [!NOTE]
>
> The **Disable** and **Activate** actions are available only for **End-Users**. Disabled users cannot log in until their account is re-enabled.

### Resending invitations

If a user's invitation has expired or was lost, you can resend it:

**1. Find the pending user**

Find the user with **Pending** status in the **Designer Users** or **End-Users** list.

**2. Select Resend Invitation**

Open the context menu and select **Resend Invitation**.

**3. Invitation sent**

A new invitation email is sent with a fresh activation link.

> [!TIP]
>
> **Resend Invitation** is available for both designer users and end-users with Pending status.

## Best practices

> [accordion] Pre-assign appropriate roles
>
> Configure the correct organization role during invitation to ensure users have proper access from day one.

> [accordion] Use groups for end-user teams
>
> Add end-users to groups during invitation to organize them into teams and apply group-based permissions.

> [accordion] Monitor pending invitations
>
> Regularly check the Designer Users page for users with Pending status to identify invitations that may need to be resent.

> [accordion] Communicate invitation timing
>
> Let invited users know to expect the invitation email and complete activation within 2 days to avoid expiration.

## Limitations

> [!NOTE]
>
> The following features are planned for future releases:
>
> * **Cancel invite** - Ability to cancel a pending invitation
> * **Copy invite link** - Ability to copy the invitation link directly

## Related documentation

> [card] [FlowX SaaS Overview](/5.9/docs/saas/saas-overview)
>
> Learn about FlowX SaaS deployment and multi-tenancy

> [card] [Access Management](/5.9/setup-guides/access-management/access-management-overview)
>
> Configure IAM and Keycloak settings

> [card] [Workspaces](/5.9/docs/projects/workspaces)
>
> Understand workspace organization

> [card] [Roles & Permissions](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> View the complete roles and permissions reference


# Organization settings
Source: https://docs.flowx.ai/5.9/docs/saas/organization-settings

Configure AI providers, manage access, design assets, and platform settings for your FlowX organization.

## Overview

Organization settings provide administrative controls for managing your FlowX organization. Access these settings from the left sidebar in FlowX Designer by clicking your organization name.

> [!NOTE]
>
> Most organization settings require the **Organization Admin** role. The **Organization Owner** role can access account, dashboard, usage, and end-user (runtime) settings, but Designer user, workspace, and role management require Organization Admin. See the [roles & permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#organization-owner-permission-matrix) for the full breakdown.

***

## Settings sections

> [card] Solutions
>
> View published solutions available for end users in the runtime container app.

> [card] Usage Stats
>
> Monitor AI node runs across your organization (**Usage Stats on AI Nodes Run**). Organizations that don't run AI nodes see no data here.

> [card] [Model Providers](/5.9/ai-platform/ai-providers)
>
> Configure LLM providers, manage API keys, and control which AI models are available across workspaces.

> [card] [Workspaces](/5.9/docs/projects/workspaces)
>
> View and manage workspaces associated with your organization.

### Design Assets

> [card] [Fonts](/5.9/docs/flowx-designer/design-assets/font-files)
>
> Manage custom fonts available across your organization's UI Flows.

> [card] [Branding](/5.9/docs/saas/container-app-branding)
>
> Configure branding settings for the container app (logo, colors, favicon).

### Access Management

> [card] [Designer Users](/5.9/docs/saas/inviting-users)
>
> Invite and manage users who build processes and workflows in FlowX Designer.

> [card] [Designer Roles](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> Configure roles and permissions for Designer users.

> [card] [End-Users](/5.9/setup-guides/access-management/end-user-access-management#end-users)
>
> Manage end users who access published solutions at runtime.

> [card] [End-Users Groups](/5.9/setup-guides/access-management/end-user-access-management#end-users-groups)
>
> Organize end users into groups for role assignment and access control.

> [!NOTE]
>
> End-user roles are defined per project in **Version Settings** → **End-User Roles**, not in Access Management. See [End-user access management](/5.9/setup-guides/access-management/end-user-access-management#end-users-roles).

### Platform

> [card] Task Manager
>
> Configure task management settings including out-of-office schedules.

> [card] Platform Status
>
> View installed component versions and service health status.

> [card] Audit Logs
>
> Review organization-level audit trail for user actions and configuration changes.

***

## Related resources

> [card] [AI providers](/5.9/ai-platform/ai-providers)
>
> Configure LLM providers and model assignments

> [card] [Workspaces](/5.9/docs/projects/workspaces)
>
> Organize projects and resources

> [card] [Roles and permissions](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> Complete roles and permissions reference

> [card] [Container app branding](/5.9/docs/saas/container-app-branding)
>
> Customize your runtime app appearance


# FlowX SaaS Overview
Source: https://docs.flowx.ai/5.9/docs/saas/saas-overview

Learn about FlowX.AI SaaS deployment model and multi-tenant architecture.

> [!NOTE]
>
> FlowX.AI is available as a managed SaaS offering. For self-managed deployments, see the [Setup Guides](/5.9/setup-guides/setup-guides-overview).

## Deployment models

FlowX.AI is available in two deployment models:

> [card] Self-Hosted
>
> **Customer Cloud**
>
> Deploy FlowX.AI in your own infrastructure as a single-organization setup, with full control over configuration, security, and data residency.
>
> * Single-organization deployment
> * Complete infrastructure control
> * Custom security configurations
> * Data residency compliance

> [card] FlowX SaaS
>
> **FlowX-hosted**
>
> Get started quickly with FlowX.AI hosted and managed by FlowX, with automatic updates and maintenance.
>
> * Automatic provisioning
> * Managed infrastructure
> * Built-in multi-tenancy
> * Automatic updates

**How new features reach each model:** FlowX SaaS receives each feature release as it ships. Self-hosted deployments receive those features when they are consolidated into the next LTS release. Pages that describe a feature not yet available to self-hosted deployments carry a **SaaS** availability badge. For the release schedule and what each release contains, see the [release notes overview](/release-notes/overview).

> [!NOTE]
>
> **Self-hosted licensing**
>
> Self-hosted deployments connect to the FlowX SaaS licensing infrastructure for license validation and usage reporting. The License service on your environment communicates with the FlowX SaaS license server. Ensure your network allows outbound connectivity to the FlowX SaaS endpoints provided during setup.
>
> For more details, see the [License service setup guide](/5.9/setup-guides/license-engine-setup).

## Available regions

FlowX SaaS is available in the following regions:

> [card] European Union
>
> Hosted in the EU for organizations requiring European data residency.

> [card] United States
>
> Hosted in the US for organizations requiring North American data residency.

***

## Updates and maintenance

FlowX manages all platform updates and maintenance for SaaS environments. No action is required from your team.

***

## Workspace types

Each workspace in FlowX SaaS is assigned a type that indicates its purpose in the delivery lifecycle:

| Workspace Type | Purpose |
| - | - |
| **Sandbox** | Building and iterating on apps and workflows |
| **Staging** | Testing and validation before production |
| **Production** | Live environment serving end users |

The workspace type is visible in the Designer workspace selector, so you can identify which environment you are working in.

***

## FlowX SaaS capabilities

FlowX SaaS provides a secure multi-tenant platform with organization management and tenant isolation.

**Multi-tenant architecture**

FlowX SaaS implements workspace-level isolation to ensure data security across organizations:

> [card] Authentication isolation
>
> Each organization has its own identity provider

> [card] Database isolation
>
> Each organization has its own database

> [card] Resource isolation
>
> Each organization has its own resources


# Migrating from 5.1 LTS
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/overview

Plan and execute a direct upgrade from FlowX.AI 5.1.x LTS to 5.9.x LTS.

This guide consolidates every breaking change, new service, and required configuration accumulated since the 5.1.x LTS line into the single supported self-hosted upgrade path: **5.1.x → 5.9.x LTS**.

> [!NOTE]
>
> **5.9.0 is the first release in the 5.9.x LTS family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Direct upgrade from 5.1.x LTS to 5.9.0 is the supported self-hosted path.

## What changes at a glance

![FlowX.AI 5.1.x LTS → 5.9.0 LTS architecture delta](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/flowx-5.1-to-5.9-delta.svg)

The diagram above summarizes the upgrade scope: four new backend microservices, an AI Platform reorganization (deprecated services dropped, new services added, the lineup consolidated to 10), a new React Native client SDK, and a new client-provisioned vector database (Qdrant). The sections below cover each area in detail.

### New services since 5.1.x LTS

5.9.0 introduces 13 microservices that did not exist in 5.1.x.

**Backend microservices (4):**

* `email-gateway`. Outbound email delivery
* `organization-manager`. Organization, workspace, and LLM configuration (absorbs the deprecated `ai-platform-models` service)
* `webhook-gateway`. Inbound webhook intake
* `license`. License verification

**AI Platform services (4):**

* `ai-platform-ai-assistant` (named `ai-assistant` from 5.9.2 on — the `ai-platform-` prefix is dropped from AI service names). Replaces the 5.1.x standalone `ai-assistant` service
* `embedder`. Embedding generation
* `knowledgebase-rag`. Retrieval-augmented generation backend
* `knowledgebase-indexer-v2`. Knowledge base indexing pipeline

**Standalone AI services (5)**. Separate repositories under `flowx-ai/`, installed independently from the AI Platform umbrella chart:

* `doc-parser`
* `doc-converter`
* `web-crawler`
* `data-privacy` (PII Guard)
* `modpod`

**Deprecated in 5.9.0 (9 AI Platform services):** `ai-assistant`, `ai-platform-connected-graph`, `ai-platform-knowledge-graph`, `ai-platform-agents`, `ai-platform-conversations`, `ai-platform-tenants`, `ai-platform-binaries`, `mcp`, `ai-platform-models`. Plan their removal from your deployment manifests during the upgrade.

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **5.1.x LTS** | Supported | Direct upgrade from 5.1.x to 5.9.x is supported. The sections below cover the full migration. |
| Any other self-hosted source | FlowX-assisted only | Custom migration plan required. Contact your FlowX representative. |

> [!NOTE]
>
> **Phased upgrades:** if you upgrade lower environments (dev, test) to 5.9.x while upper environments (staging, production) stay on 5.1.x for a while, you can still ship fixes to the not-yet-upgraded environments. See [Cross-version export and import](../docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).

***

## How this guide is organized

Each section below is a self-contained topic. Read them in the order shown for a first-time upgrade; experienced operators can jump directly to the topics that affect them.

> [card] [Prerequisites & upgrade path](./prerequisites)
>
> Audience, supported source versions, inventory you should gather before starting, and what FlowX assists with.

> [card] [Authentication & IAM migration](./authentication-iam)
>
> Keycloak two-realm architecture, service-account client renames, opaque-token removal, SMTP configuration. The largest single break.

> [card] [Runtime authorization migration](./runtime-authorization)
>
> Org-level roles become project-version-scoped. End-user groups move from Keycloak into FlowX. Per-environment sharing.

> [card] [Organization & deployment configuration](./organization-deployment)
>
> Single-org default mode, the `ORGANIZATION_ID` Liquibase parameter on 9 services, the new `license` microservice, and the env-info deprecation.

> [card] [Kafka migration](./kafka)
>
> Mandatory `Fx-Organization-Id` header for every custom producer, new Kafka topics that did not exist in 5.1.x, and one topic-ownership move.

> [card] [Ingress routing and CORS](./ingress-routing)
>
> NGINX ingress controller deprecation, CORS handling moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable, and the optional Gateway API HTTPRoute path.

> [card] [API & integration breaking changes](./api-breaking-changes)
>
> Endpoint rename (`get-input-json` → `get-start-metadata`), `PATCH /api/platform/environment` removed, `Fx-Organization-Id` header mandatory, and opaque-token removal.

> [card] [Engine partitioning configuration](./engine-partitioning)
>
> The partitioning config consolidated under `flowx.data.partitioning.archiving`; the standalone `SCHEDULER_DATA_PARTITIONING_*` variables are gone and the archiving scheduler now defaults to off.

### Renderer SDK migration

> [card] [Android SDK](./android)
>
> Migrate the Android renderer from 5.1.x (9.0.x) to 5.9.x (10.x).

> [card] [iOS SDK](./ios)
>
> Migrate the iOS renderer from 5.1.x to 5.9.x.

> [card] [React SDK](./react)
>
> Migrate the React renderer from 5.1.x to 5.9.x (includes React 19 upgrade).

> [card] [Angular SDK](./angular)
>
> Migrate the Angular renderer from 5.1.x to 5.9.x.

***

## What this guide assumes

* You are upgrading a **self-hosted 5.1.x LTS deployment**.
* You have agreed the upgrade plan with FlowX in advance. Some 5.1.x deployments may need a custom migration path that this guide does not cover; your FlowX representative will confirm the path before you start.
* You have engaged FlowX for the **Liquibase migration of inactive/archived process instances**. Active instances are migrated automatically; inactive ones require FlowX assistance.

If any of these are not true, contact your FlowX representative before starting. Your path may differ from the one described here.


# Prerequisites & upgrade path
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/prerequisites

Audience, supported source versions, and the inventory you should gather before starting the 5.1 LTS → 5.9 LTS upgrade.

## Audience and scope

This guide is for **operators of self-hosted FlowX.AI 5.1.x LTS deployments** upgrading to **5.9.x LTS**. The 5.9.x LTS family opens with **5.9.0** (target 2026-06-02) and continues with monthly LTS patches from July 2026 onward.

* **In scope:** Self-hosted deployments running any 5.1.x patch level.
* **Out of scope:** SaaS deployments. They are continuously upgraded on the SaaS line and do not perform this migration. Any other self-hosted source version requires a FlowX-assisted custom migration plan.

The upgrade jumps directly from the 5.1.x LTS line to the 5.9.x LTS line.

> [!WARNING]
>
> **Confirm your upgrade plan with FlowX before starting.** Some 5.1.x deployment configurations require a custom migration path that this guide does not cover. Your FlowX representative will validate compatibility and provide any tailored migration scripts ahead of the upgrade window.

### Coming from 4.7.x or earlier

There is no direct path from 4.7.x to 5.9.x. First complete the [4.7.x → 5.1 migration](/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/migration-overview), then follow this guide.

When your upgrade path passes through an LTS family you do not operate day-to-day (5.1.x, on a 4.7.x → 5.1.x → 5.9.x path), upgrade to the **latest available 5.1.x patch** as the intermediate step, not 5.1.0 or an arbitrary patch level. Data migrations and their fixes accumulate across the patches of an LTS family, and the latest patch is the level guaranteed to carry all of them.

> [!NOTE]
>
> This applies to skipped families only. If you already operate on 5.1.x, any patch level is a supported starting point for this upgrade.

### Start from a fully functional environment

Run every migration over an environment that is fully functional. Before opening the 5.9.x upgrade window, and again after each intermediate upgrade on the path, confirm:

* **FlowX.AI Designer → Platform Status** shows every service up and healthy, nothing degraded.
* The **data-sync job** from the upgrade you just completed finished successfully.

Skipping these checks and stacking the next upgrade on a partially migrated environment produces data inconsistencies that are much harder to diagnose and repair after the fact.

***

## Get your Organization UUID

FlowX issues an Organization UUID when your organization registers with FlowX SaaS for license validation and usage reporting. Request it from your FlowX representative before the upgrade window starts.

You will need this single UUID for:

* The `ORGANIZATION_ID` Liquibase parameter on 9 services (`application-manager`, `authorization-system`, `cms-core`, `document-plugin`, `integration-designer`, `notification-plugin`, `organization-manager`, `process-engine`, `scheduler-core`). See [Organization & deployment configuration](./organization-deployment#organization_id-where-it-is-actually-required) for the full behavior.
* The `FLOWX_LICENSE_ORGANIZATIONID` runtime env var on the `license` service (OAuth client-id for the FlowX SaaS license handshake. Different env var, same UUID value).
* The `Fx-Organization-Id` Kafka header on every custom producer.

***

## Inventory to gather

Before the upgrade window, capture the following from your current 5.1.x deployment:

**1. Current component versions**

Open **FlowX.AI Designer → Platform Status** and record the version of each FlowX component. You will compare these against the 5.9.x targets in the [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) after the upgrade.

**2. Current SDK versions**

List the `@flowx/*` web SDK package versions in each container app, plus the iOS and Android renderer versions. iOS and Android renderers ship on the 9.0.x line in 5.1.x; 5.9.x targets the 10.x line. Web `@flowx/*` packages follow the Designer version baseline, not the renderer 9/10 numbering.

**3. Keycloak realms and clients**

Export the list of realms, clients, client scopes, and protocol mappers from your current Keycloak. 5.9.x introduces a dedicated service-accounts realm and renames every service-account client to a `flowx-{service}-sa` pattern. See [Authentication & IAM migration](./authentication-iam).

**4. Kafka topic ACLs and custom producers**

If you manage Kafka topic ACLs manually, list every topic and its producers/consumers. The `WorkspaceCreatedEvent` topic ownership changes on 5.9.x. List every custom Kafka producer your team operates. Each must add the `Fx-Organization-Id` header on 5.9.x.

**5. Custom API clients**

Identify any internal tooling that calls:

* `GET /api/process-definition/{uuid}/get-input-json`. Renamed to `/get-start-metadata` on 5.9.x.
* `PATCH /api/platform/environment`. Removed on 5.9.x.

**6. Partitioning configuration**

If you enabled data partitioning on 5.1.x, capture the current `scheduler.dataPartitioning` YAML block and the five related env vars. The structure and names change on 5.9.x; your FlowX representative will share the new YAML during the upgrade plan.

**7. Backups**

Take fresh backups of:

* All Postgres databases (per-service).
* All MongoDB databases (per-service).
* Keycloak realm exports.
* SpiceDB schema and relations.

These backups are the only way back. There is no in-place downgrade from 5.9.x to 5.1.x — reverting means restoring every one of these stores to its pre-upgrade state and losing everything written after it. See [Rollback considerations](#rollback-considerations) below.

> [!WARNING]
>
> **Carry forward every required configuration from your 5.1.x deployment.** This guide documents what *changes* on 5.9.x; it does not re-list every configuration value your services already require. Values your 5.1.x services depend on — such as SpiceDB connection and credentials, Redis, and database settings — remain required on 5.9.x and must be carried over. If a service fails to start and its logs report a missing configuration, that value is required: take it from your existing 5.1.x configuration.

***

## Dropped third-party dependency versions

The following third-party versions are no longer supported in 5.9.0. Upgrade them before the FlowX 5.9 upgrade window — running an unsupported version after the FlowX upgrade is not covered by the standard support process.

| Dependency | Dropped versions | Minimum supported in 5.9.0 |
| - | - | - |
| Kafka | 3.8 and older | 3.9 |

> [!NOTE]
>
> Versions are dropped from the supported list as upstream support is no longer provided. For the full supported-version matrix (Keycloak, PostgreSQL, MongoDB, Oracle, Elasticsearch Sink Connector, renderer SDKs), see the [v5.9.0 deployment guidelines — Third-party supported component versions](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#third-party-supported-component-versions).

***

## Infrastructure deltas

The 5.1 → 5.9 jump adds several runtime dependencies your 5.1.x environment may not already have:

| Dependency | Used by |
| - | - |
| **Qdrant** | Knowledge Base infrastructure (vector storage) |
| **SpiceDB** | Expanded coverage on 5.9.x — `data-search` and `email-gateway` join the existing SpiceDB consumers |
| **Outbound HTTPS to FlowX SaaS** | `license` service (license validation, usage reporting) |
| **SMTP server** | Keycloak (password reset, user invitations) |

### New services to deploy

5.9.x ships several microservices that do not exist in a 5.1.x deployment. Ensure Helm charts and infrastructure are provisioned for these before upgrading:

| Service | Purpose | Setup guide |
| - | - | - |
| **webhook-gateway** | Receives incoming HTTP webhooks from external systems and routes them to processes via Kafka | [Webhook Gateway setup](/5.9/setup-guides/webhook-gateway-setup) |
| **email-gateway** | IMAP/Outlook email trigger and sender for processes and workflows | [Email Gateway setup](/5.9/setup-guides/email-gateway-setup) |
| **file-gateway** | Ingests files from FTP/SFTP/S3/Azure Blob and delivers generated files back; can trigger processes when new files arrive | [File Gateway setup](/5.9/setup-guides/file-gateway-setup) |
| **ai-gateway** | Powers the AI chat experience in FlowX Designer, streaming AI assistant responses to the browser and routing requests to the AI agents | [AI Gateway setup](/5.9/setup-guides/ai-gateway-setup) |
| **license** | License validation and usage reporting (requires outbound HTTPS to FlowX SaaS) | [License setup](/5.9/setup-guides/license-engine-setup) |
| **organization-manager** | Organization and multi-tenancy management | [Organization Manager setup](/5.9/setup-guides/organization-manager-setup) |

> [!WARNING]
>
> **Deployments running without the Documents or Notifications plugin.** Some 5.1.x deployments run without `document-plugin` and `notification-plugin`. On 5.9.x these are core platform components: deploy both, with their databases, before the upgrade window. The data-sync job waits for a connection to every core component and does not start while any of them is missing.

> [!NOTE]
>
> The **AI Platform** is also new on 5.9.x. If your deployment uses AI features, refer to the [AI Platform setup](/5.9/setup-guides/ai-platform-setup) guide for the full list of AI services (agent-builder, knowledgebase-rag, embedder, and others) and their infrastructure requirements (Qdrant and S3).
>
> The AI Platform also ships a versioned documentation image (`flowx-docs:5.9.0`) that is mounted into the **AI Assistant** so it can answer from the FlowX documentation. It is a content image, not a standalone service; pull the version matching your release (see the component versions in the deployment guidelines).

Confirm minimum versions against the [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) Third-party supported component versions table before scheduling the upgrade window.

***

## Rollback considerations

> [!WARNING]
>
> **Plan the 5.1.x → 5.9.x upgrade as a one-way move.** There is no downgrade path from 5.9.x back to 5.1.x: no reverse migration, no configuration switch, no partial revert. The only way back is a **full point-in-time restore of every FlowX datastore** — all Postgres databases, all MongoDB databases, the Keycloak realms, and SpiceDB — to the backups taken before the upgrade window opened. Everything written after that point is discarded with the restore: process instances, tasks, documents, audit records, and every user, group, and role change.

The upgrade migrates identity, configuration, and runtime data in place across systems that reference each other, which is what rules out a partial rollback. Restoring one of them while the rest stay on 5.9.x leaves the platform inconsistent rather than recovered.

### What the upgrade changes for good

Most of what makes the upgrade one-way sits in these areas:

* **Identity.** Keycloak realms and every service account are reorganized during the upgrade. Going back means returning to the realm export taken beforehand, and with it losing the end users onboarded, passwords reset, and MFA enrolled since cutover.
* **Platform data.** The database migrations are forward-only, and process instances are migrated in place. Runtime work that advanced on 5.9.x has no 5.1.x equivalent to return to.
* **Access model.** End-user groups, solution sharing, and UI Flow permissions become FlowX-managed records with no 5.1.x counterpart, so the access configuration your teams rebuild after the upgrade does not survive a restore.
* **AI capabilities.** Knowledge Base content is indexed into a new vector database, and the AI services it replaces leave the deployment. Returning to 5.1.x means standing the previous AI stack back up and rebuilding its indexed content.
* **Client applications.** The web, iOS, and Android renderers move to a new SDK line, and custom integrations adopt a changed API surface. Reverting the platform means reverting those releases too — for mobile apps, on app-store review timelines.

Individual settings that changed shape can be reverted on their own, and each topic page notes where that applies. None of them add up to a way back to 5.1.x.

### Plan the window around this

Because rollback costs data, the mitigations all sit before and during the upgrade rather than after it.

**1. Rehearse on a full copy of production**

Restore a recent production backup into an isolated environment and run the complete upgrade against it, including the restore procedure itself. The rehearsal is where you find out whether your backups are actually restorable.

**2. Take the backups immediately before cutover, with runtime traffic stopped**

Stop runtime traffic before the backups so the restore point sits as close as possible to the cutover. Every minute of traffic accepted after the backup is data a rollback would discard.

**3. Put the go/no-go decision before first login**

Everything up to and including the data-sync job is platform work on already-migrated data. Once users log in and runtime traffic resumes, new business data accumulates on 5.9.x and the cost of restoring climbs with every hour. Make the abort decision at that boundary — see [the data-sync step](./organization-deployment#liquibase-migration) for what has to complete before anyone logs in.

**4. Agree the acceptable data loss with the business**

Confirm before the window who accepts the loss of post-cutover runtime data if a restore is called, and how long the platform may stay unavailable while it runs.

> [!NOTE]
>
> This applies to crossing the LTS boundary. Moving between patch releases inside the 5.9.x family (5.9.1 to 5.9.2, for example) is a routine in-family upgrade covered by the LTS compatibility guarantee, and carries none of the migrations above.

***

## Next

> [card] [Authentication & IAM migration](./authentication-iam)
>
> Start with this. It is the largest single break.

> [card] [Runtime authorization migration](./runtime-authorization)
>
> Project-scoped roles, end-user groups, per-environment sharing.


# EU AI Act
Source: https://docs.flowx.ai/5.9/observatory/compliance/eu-ai-act

18 EU AI Act requirements mapped to Observatory controls, with scope by risk tier.

Observatory ships with 18 EU AI Act requirements pre-mapped to operational controls. The scope of each requirement depends on the **risk tier** of the app (minimal / limited / high), set in the [AI Registry](../governance/ai-registry).

***

## Requirement scope by risk tier

| Risk tier | Number of EU AI Act requirements in scope |
| - | - |
| **Minimal** | Transparency obligations only |
| **Limited** | Transparency + user information |
| **High** | All 18 requirements |
| **Unacceptable** | Banned — flagged for removal |

If an app's tier is set incorrectly, the wrong requirements light up. Confirm the tier before reading status.

***

## The 18 mapped requirements

These are grouped roughly along the Act's structure. Observatory tracks them individually; the grouping is for readability.

### Risk management and quality (Articles 9, 17)

| Requirement | Backing controls |
| - | - |
| Risk management system | Risk Dashboard + Assessments |
| Quality management system | Audit Trail + Evidence |

### Data and data governance (Article 10)

| Requirement | Backing controls |
| - | - |
| Training data governance | Manual evidence (data lineage docs) |
| Validation and testing data | Datasets + Experiments |
| Bias detection in training | Manual evidence + drift monitor on protected attributes |

### Technical documentation (Articles 11, 12, 13)

| Requirement | Backing controls |
| - | - |
| Technical documentation | Manual evidence + registry metadata |
| Record-keeping (logging) | Telemetry + 7-year retention setting |
| Transparency to users | Manual evidence + UI screenshots |

### Human oversight (Article 14)

| Requirement | Backing controls |
| - | - |
| Human-in-the-loop | Manual evidence + tool definitions |
| Override mechanisms | Manual evidence |

### Accuracy and robustness (Article 15)

| Requirement | Backing controls |
| - | - |
| Accuracy levels | Evaluations + Experiments |
| Cybersecurity | Policies (prompt-injection) + Audit Trail |
| Robustness to errors | Alerts + Drift Monitor |

### Post-market monitoring (Article 61)

| Requirement | Backing controls |
| - | - |
| Post-market monitoring plan | Manual evidence (the plan document) |
| Continuous monitoring data | Telemetry + Analytics |
| Serious-incident reporting | Alerts with `incident` tag + Audit Trail |

### Notifications (Article 62)

| Requirement | Backing controls |
| - | - |
| Conformity assessment | Assessments template |
| Registration in EU database | Manual evidence (registration confirmation) |

***

## Status semantics

Each requirement evaluates to:

* **Met** — all backing controls have approved, in-date evidence
* **Partial** — some controls met, others have gaps
* **Gap** — at least one control has no current evidence
* **Out of scope** — risk tier doesn't trigger this requirement

The Article-level roll-up is the worst status of its requirements (any Gap → Gap).

***

## Producing the audit pack

The EU AI Act view supports a one-click export of the audit pack:

* Per-requirement evidence list with timestamps
* Backing telemetry summaries
* Assessment results
* Gap analysis with remediation plan

```http theme={"dark"}
POST /api/compliance/export?framework=eu-ai-act&app_id=...
```

Returns a ZIP with PDF and JSON outputs.

***

## Related resources

> [card] [Gap analysis & heatmap](./gap-analysis-heatmap)
>
> Cross-framework view that includes EU AI Act.

> [card] [NIST AI RMF](./nist-ai-rmf)
>
> Many EU AI Act requirements overlap with NIST controls.


# Gap analysis & heatmap
Source: https://docs.flowx.ai/5.9/observatory/compliance/gap-analysis-heatmap

Cross-framework view that prioritises remediation by the impact of closing each gap.

The gap analysis and heatmap views answer two questions at once: where do we stand against every framework, and where will one piece of work move the most needles?

***

## The heatmap

Each cell in the heatmap is one requirement × one framework. The colour is the status:

| Colour | Status |
| - | - |
| Green | Met |
| Yellow | Partial |
| Red | Gap |
| Grey | Out of scope |

Reading the heatmap horizontally tells you about cross-framework overlap. A red row across all three frameworks means closing that single requirement closes three gaps at once.

***

## Gap analysis

The gap analysis is the heatmap pivoted: list of all open gaps, sorted by remediation impact.

### Sort options

| Sort by | Use for |
| - | - |
| **Cross-framework impact** | Maximise leverage. Default sort. |
| **Severity** | Tackle the worst gaps first. |
| **Estimated effort** | Quick wins first. |
| **Framework** | Scope to one auditor's view. |

### What "impact" measures

A single requirement's impact is `count of frameworks affected × max severity`. So an EU AI Act high-severity gap that also fails NIST and ISO 42001 outranks an isolated low-severity gap, even if the latter looks scarier individually.

***

## Reading the heatmap

**1. Start with the rows**

Sort by severity descending. The top rows are the most painful gaps.

**2. Look at the row's colour pattern**

A row red across all three columns is high-leverage. A row red in one column only is framework-specific.

**3. Click the cell**

Each cell drills into the requirement detail — backing controls, current evidence, what's missing.

**4. Take action**

Either provide manual evidence, schedule an [assessment](../governance/assessments), or fix the underlying telemetry/policy that drives the control.

***

## Exporting

Both views support PDF and CSV export. The exported gap analysis is the format most GRC teams paste into their tracking tool.

```http theme={"dark"}
POST /api/compliance/heatmap/export
GET  /api/compliance/gaps?sort=impact
```

***

## Related resources

> [card] [Evidence](../governance/evidence)
>
> The mechanism for closing manual-evidence gaps.

> [card] [Compliance overview](./overview)
>
> Per-framework views the heatmap aggregates.


# ISO 42001
Source: https://docs.flowx.ai/5.9/observatory/compliance/iso-42001

12 ISO/IEC 42001:2023 requirements mapped to Observatory controls for AI management systems.

ISO/IEC 42001:2023 is the international standard for AI management systems. Observatory maps 12 of its key clauses to operational controls. Unlike the EU AI Act (regulatory) and NIST RMF (voluntary framework), ISO 42001 is the certifiable standard your auditor will audit against.

***

## What ISO 42001 expects

ISO 42001 follows the same plan-do-check-act structure as other ISO management-system standards (9001, 27001). Observatory's mappings focus on the AI-specific clauses where evidence is hardest to gather by hand.

***

## Mapped clauses

| Clause | Title | Backing controls |
| - | - | - |
| 4.1 | Understanding the organization | AI Registry + manual evidence |
| 4.4 | AI management system scope | Manual evidence (scope document) |
| 5.1 | Leadership and commitment | Manual evidence |
| 6.1 | Actions for risks and opportunities | Risk Dashboard + Assessments |
| 7.4 | Communication | Audit Trail + Alerts |
| 7.5 | Documented information | Evidence + retention setting |
| 8.1 | Operational planning and control | Policies + Audit Trail |
| 8.4 | AI system development | Assessments (release-readiness) |
| 8.5 | Operation | Telemetry + Drift Monitor |
| 9.1 | Performance evaluation | Analytics + Experiments |
| 9.2 | Internal audit | Audit Trail + manual evidence |
| 10.1 | Continual improvement | Manual evidence (improvement log) |

***

## Status semantics

ISO 42001 audits typically reach a binary conformance per clause. Observatory's three-state status reflects how close you are to that bar:

* **Met** — conformant
* **Partial** — conformant for some sub-elements only (likely a finding at audit)
* **Gap** — non-conformant
* **Out of scope** — clause excluded from scope statement (rare)

***

## What auditors typically want

Most ISO 42001 auditors ask for:

1. The AI management system scope document (clause 4.4) — manual evidence
2. Risk register with treatment plans (clause 6.1) — Risk Dashboard export + treatment notes
3. Records of operational telemetry (clauses 7.5, 8.5) — Observatory's standard retention
4. Internal audit reports (clause 9.2) — manual evidence
5. Continual-improvement evidence (clause 10.1) — improvement log

The export bundle covers items 2 and 3 directly; items 1, 4, and 5 need manual evidence in Observatory.

```http theme={"dark"}
POST /api/compliance/export?framework=iso-42001&app_id=...
```

***

## Overlap with EU AI Act

Clause 6.1 (risk treatment) overlaps with EU AI Act Article 9. Clause 8.5 (operation) overlaps with Article 17. The [gap analysis](./gap-analysis-heatmap) treats these as joint priorities.

***

## Related resources

> [card] [EU AI Act](./eu-ai-act)
>
> Regulatory framework that overlaps with ISO 42001 risk treatment.

> [card] [Audit Trail](../governance/overview)
>
> Where ISO auditors expect to find every change.


# NIST AI RMF
Source: https://docs.flowx.ai/5.9/observatory/compliance/nist-ai-rmf

16 NIST AI Risk Management Framework requirements mapped to Observatory controls across Govern, Map, Measure, Manage.

NIST AI RMF organises risk management around four functions: **Govern**, **Map**, **Measure**, **Manage**. Observatory maps 16 of the framework's high-impact subcategories to operational controls.

***

## The four functions

```mermaid theme={"dark"}
flowchart LR
    Govern["Govern<br/>(culture, policy, accountability)"] --> Map
    Map["Map<br/>(context, classification, scope)"] --> Measure
    Measure["Measure<br/>(testing, monitoring, evaluation)"] --> Manage
    Manage["Manage<br/>(prioritise, treat, communicate)"] -.feedback.-> Govern
```

A healthy AI RMF posture closes the loop: governance decisions feed mapping, mapping feeds measurement, measurement feeds management, and management updates governance.

***

## Mapped subcategories

### Govern (4 mapped)

| Subcategory | Backing controls |
| - | - |
| Govern 1.1 — policies and procedures | Policies + Audit Trail |
| Govern 1.4 — accountability and roles | RBAC + AI Registry ownership |
| Govern 4.1 — AI risk management training | Manual evidence |
| Govern 5.1 — communication channels | Manual evidence (incident-comms plan) |

### Map (4 mapped)

| Subcategory | Backing controls |
| - | - |
| Map 1.1 — AI system context | AI Registry metadata |
| Map 1.2 — intended use and limitations | AI Registry + manual evidence |
| Map 3.3 — record-keeping | Telemetry + retention setting |
| Map 5.1 — third-party AI components | AI Registry vendor section |

### Measure (4 mapped)

| Subcategory | Backing controls |
| - | - |
| Measure 1.1 — relevant metrics | Analytics |
| Measure 2.3 — performance over time | Drift Monitor |
| Measure 2.7 — security tests | Policies (prompt-injection) + Evidence |
| Measure 4.2 — feedback mechanisms | Thread feedback + Evidence |

### Manage (4 mapped)

| Subcategory | Backing controls |
| - | - |
| Manage 1.1 — prioritise risks | Risk Dashboard |
| Manage 2.3 — incident response | Alerts + Audit Trail |
| Manage 3.1 — manage third-party risks | AI Registry vendor section |
| Manage 4.1 — communicate to stakeholders | Compliance heatmap export |

***

## Overlap with EU AI Act

Several NIST subcategories overlap directly with [EU AI Act](./eu-ai-act) requirements:

| NIST subcategory | Overlaps with |
| - | - |
| Govern 1.1 | EU AI Act Article 9 (risk management) |
| Map 3.3 | EU AI Act Article 12 (record-keeping) |
| Measure 2.3 | EU AI Act Article 15 (robustness) |
| Manage 2.3 | EU AI Act Article 62 (incident notification) |

Closing one usually closes both. The [gap analysis](./gap-analysis-heatmap) prioritises remediation by cross-framework impact.

***

## Producing the audit pack

Same shape as EU AI Act: a ZIP with per-subcategory evidence and the framework score.

```http theme={"dark"}
POST /api/compliance/export?framework=nist-ai-rmf&app_id=...
```

***

## Related resources

> [card] [EU AI Act](./eu-ai-act)
>
> Sister framework with significant overlap.

> [card] [Risk Dashboard](../governance/risk-dashboard)
>
> Where Manage 1.1 (prioritise risks) is operationalised.


# Compliance
Source: https://docs.flowx.ai/5.9/observatory/compliance/overview

EU AI Act, NIST AI RMF, and ISO 42001 mapped to your runtime — controls evaluated continuously, gaps surfaced automatically.

Compliance turns governance work into framework-specific status you can put in front of an auditor. Each framework's requirements are pre-mapped to Observatory controls; the controls evaluate continuously against your telemetry, evidence, and assessments.

***

## Frameworks covered

> [card] [EU AI Act](./eu-ai-act)
>
> 18 requirements mapped, with scope by risk tier (minimal / limited / high).

> [card] [NIST AI RMF](./nist-ai-rmf)
>
> 16 requirements across Govern, Map, Measure, Manage.

> [card] [ISO 42001](./iso-42001)
>
> 12 requirements for AI management systems.

> [card] [Gap analysis & heatmap](./gap-analysis-heatmap)
>
> Cross-framework view with prioritised remediation.

***

## How a control becomes a status

```mermaid theme={"dark"}
flowchart LR
    Framework[Framework requirement] --> Controls[Mapped Observatory controls]
    Controls --> Inputs{Inputs}
    Inputs --> Telemetry[Telemetry]
    Inputs --> Policy[Policy evaluations]
    Inputs --> Evidence[Approved evidence]
    Inputs --> Assessment[Assessment answers]
    Telemetry & Policy & Evidence & Assessment --> Status[Per-control status]
    Status --> Roll[Framework score]
```

Each requirement maps to one or more controls. Each control draws on the same operational inputs (telemetry, policies, evidence, assessments). Status is one of:

* **Met** — sufficient approved evidence within freshness window
* **Partial** — some evidence but gaps remain
* **Gap** — no current evidence
* **Out of scope** — risk tier doesn't trigger this requirement

***

## When to use the compliance views

| Audience | Page |
| - | - |
| Auditor preparing a review | The framework page they care about + the heatmap export |
| GRC team planning sprints | Gap analysis sorted by severity |
| Security team checking posture | Heatmap, scoped by risk tier |
| Engineering team during a release | Requirement detail for the one control that flipped to Gap |

***

## Cross-framework mapping

Many requirements overlap. Observatory's mapping engine recognises this — closing a gap in one framework often resolves a gap in another:

* EU AI Act Article 9 (risk management) overlaps with NIST RMF Govern-1.1 and ISO 42001 6.1.
* EU AI Act Article 12 (record-keeping) overlaps with NIST RMF Map-3.3 and ISO 42001 8.5.

The heatmap shows these overlaps; the gap analysis prioritises remediation by impact across frameworks.

***

## Related resources

> [card] [Evidence](../governance/evidence)
>
> Where the artefacts that satisfy controls live.

> [card] [AI Registry](../governance/ai-registry)
>
> Risk tier in the registry determines which requirements apply.


# Getting started
Source: https://docs.flowx.ai/5.9/observatory/getting-started

Connect your first project, instrument an agent, and see traces in Observatory in under 15 minutes.

This guide walks you from an empty Observatory to a live trace flowing in from your first agent. Plan on 10–15 minutes.

## Prerequisites

* An Observatory instance (managed cloud, or [self-hosted](./setup/self-hosted))
* Python 3.12 or newer
* An LLM provider key (OpenAI, Anthropic, Google, or Ollama)
* Permission to create projects in your Observatory organization and workspace

***

## Steps

**1. Create a project**

Sign in to Observatory and open **Projects**. Click **Add Project**, give it a name, and confirm. Observatory creates the project and an API key in the same step.

**2. Copy your API key**

On the **Home** page, the API key panel shows the key for the selected organization and workspace. Click **Copy** and store the value as the `FLOWX_OBSERVATORY_API_KEY` environment variable in your app, alongside your organization, workspace, and project IDs.

```bash theme={"dark"}
export FLOWX_OBSERVATORY_API_KEY="FX-..."
export FLOWX_OBSERVATORY_API_URL="https://your-observatory.example.com"
export FLOWX_OBSERVATORY_ORG_ID="..."
export FLOWX_OBSERVATORY_WORKSPACE_ID="..."
export FLOWX_OBSERVATORY_APP_ID="..."
```

> [!WARNING]
>
> Treat the API key like a database password. Don't commit it to source control.

**3. Install the SDK**

Add the SDK to your Python project:

```bash theme={"dark"}
pip install flx-observatory-lib
```

The distribution is `flx-observatory-lib`; you import it as `flowxobservatory`. The SDK ships an event queue and a background consumer that batches events to `POST /api/report`. You don't need to manage the connection yourself.

**4. Instrument an agent**

Decorate the function that runs your agent with `@agent`. The SDK captures inputs, outputs, timings, and any nested chains or tool calls automatically.

```python theme={"dark"}
from flowxobservatory import agent

@agent("claims-approval")
def run(ctx, payload):
    # your existing logic
    return decide(payload)
```

The string argument names the agent and is what appears in the **Agent** column on the LLM Calls page.

> [!TIP]
>
> Inner LangChain or LangGraph chains are picked up automatically through the `FlowxObservatoryCallbackHandler`. You don't need to instrument them by hand.

**5. Run the agent and confirm traces**

Invoke the agent once with realistic input. The SDK flushes events every few seconds.

Open **Observability** → **Traces** in Observatory. Within \~30 seconds you should see the run, agent name, model, duration, and token count.

> [!TIP]
>
> You see a row for your run with status `success`, the right agent name, and a non-zero duration.

**6. Open the trace**

Click the run. The detail drawer shows the full chain-of-calls — every LLM call, tool invocation, and event with inputs, outputs, latencies, and token usage.

***

## Validate the rest of the platform

Once one trace lands, the rest of Observatory has data to work with:

> [card] [Analytics](./observability/analytics)
>
> p50/p95 latency, cost by model, error rate.

> [card] [Risk Dashboard](./governance/risk-dashboard)
>
> The 6-dimensional risk score updates automatically.

> [card] [Compliance heatmap](./compliance/gap-analysis-heatmap)
>
> Controls start evaluating against the new evidence.

> [card] [ROI overview](./roi/overview)
>
> Configure baselines to start producing ROI numbers.

***

## Troubleshooting

> [accordion] No traces appear after 30 seconds
>
> * Confirm `FLOWX_OBSERVATORY_API_KEY` is set in the environment your app actually reads from (not just your shell).
> * Check the app logs for `flowxobservatory` errors — connection refused usually means `FLOWX_OBSERVATORY_API_URL` points at the wrong host or is missing the scheme.
> * Confirm the project you're looking at in the UI matches the API key you exported.

> [accordion] Traces show but the agent name is empty
>
> The function must be decorated with `@agent("name")` (not bare `@agent`). The string is what populates the **Agent** column.

> [accordion] Token counts are zero
>
> Token counting requires the provider's response metadata. If you're calling a custom or proxied endpoint that strips usage fields, Observatory has nothing to count. See [Event reporting](./sdk/event-reporting) for the rules.

***

## Related resources

> [card] [SDK decorators](./sdk/decorators)
>
> Full reference for `@agent`, `@chain`, and `@tool`.

> [card] [Observability overview](./observability/overview)
>
> What you can do once traces are flowing.


# AI Registry
Source: https://docs.flowx.ai/5.9/observatory/governance/ai-registry

Catalogue every model, deployment, and owner across your portfolio — the inventory layer for governance.

The AI Registry is the inventory layer. Before you can govern a portfolio, you need to know what's in it. The registry catalogues models, where they're deployed, who owns them, and what data they touch.

***

## What the registry tracks

| Entity | Fields |
| - | - |
| **Model** | Name, provider, version, modality, capabilities, intended use. |
| **Deployment** | Environment (dev/stage/prod), endpoint, region, app linkage. |
| **Owner** | A user or team. Multiple owners allowed per model. |
| **Data tags** | Data classifications the model touches (PII, financial, health). |
| **Risk tier** | Manual classification or computed from data tags + capability. |

***

## Why this matters

Governance, compliance, and ROI calculations all need the registry as the inventory of record:

```mermaid theme={"dark"}
flowchart LR
    Registry[AI Registry] --> Risk["Risk Dashboard<br/>(data + model risk)"]
    Registry --> Compliance["Compliance<br/>(scope of high-risk apps)"]
    Registry --> ROI["ROI<br/>(per-model cost analysis)"]
    Registry --> Audit["Audit Trail<br/>(ownership for changes)"]
```

If a model isn't in the registry, it doesn't show up in any of the downstream views. The first job of a new Observatory org is usually populating the registry.

***

## Populating the registry

Three ways:

> [card] From telemetry
>
> Models that show up in runs are auto-registered. You confirm and fill in metadata.

> [card] Manual entry
>
> Add a model that isn't running yet (preview, eval, planned).

> [card] Import
>
> Bulk import from CSV or from FlowX AI Platform's agent definitions.

> [card] API
>
> Programmatic registration through `POST /api/registry/models`.

***

## Risk tiering

The default tiers map roughly to the EU AI Act risk pyramid:

| Tier | Examples |
| - | - |
| **Minimal** | Internal-tool agents, productivity helpers. |
| **Limited** | Customer-facing chatbots without consequential decisions. |
| **High** | Credit decisions, claims approvals, hiring-adjacent. |
| **Unacceptable** | Banned by regulation — flagged for removal. |

Tiering can be manual or computed. Computed tiering uses data tags and capability flags (e.g. "makes decisions about people" + "trained on personal data" → High).

***

## API

| Endpoint | Use |
| - | - |
| `GET /api/registry/models` | List models. |
| `POST /api/registry/models` | Register a model. |
| `PUT /api/registry/models/{id}` | Update metadata. |
| `GET /api/registry/deployments` | List deployments. |
| `POST /api/registry/deployments` | Link a model to an environment/app. |

***

## Related resources

> [card] [Risk Dashboard](./risk-dashboard)
>
> Where data and model tags become risk scores.

> [card] [Compliance](../compliance/overview)
>
> Risk tier drives which frameworks apply.


# Assessments
Source: https://docs.flowx.ai/5.9/observatory/governance/assessments

Dynamic, weighted-scoring questionnaires for repeatable governance reviews.

Assessments are structured questionnaires you fill in on a recurring cadence you define — per app, per release, or per audit. Each template scores answers and feeds the result into the [Risk Dashboard](./risk-dashboard) and [Compliance heatmap](../compliance/gap-analysis-heatmap).

***

## Concepts

| Model | What it represents |
| - | - |
| **AssessmentTemplate** | The questionnaire definition. Ordered sections, ordered questions, scoring weights. |
| **Assessment** | One filled-in (or in-progress) instance of a template, scoped to an app or org. |

A template renders dynamically: questions can be conditional ("if previous answer was 'yes', show…"). The total score is a weighted sum across answered questions.

***

## Building a template

**1. Open Assessments → Templates**

Click **New template**.

**2. Add sections**

Sections group related questions. They render as collapsible blocks when the assessment is taken.

**3. Add questions**

Each question has: type (yes/no, multi-choice, free-text), weight, and an optional conditional reveal rule.

**4. Define the scoring**

Map each answer to a numeric value. The template score is sum of (answer value × question weight).

**5. Publish**

Once published, the template appears under **Take assessment** for everyone in the org.

***

## Taking an assessment

The take-assessment drawer renders the template progressively:

* Conditional questions appear only after their trigger answer is selected
* Progress bar at the top
* Save-as-draft button to leave and resume later
* Submit button only enabled when all required questions are answered

On submit, Observatory computes the score, stores the answers, and surfaces the result on Risk Dashboard and Compliance heatmap.

***

## Use cases

> [card] Pre-deployment review
>
> Run an "AI release readiness" template against each app before promoting to production.

> [card] Quarterly risk review
>
> A "risk review" template per app, scheduled by the GRC team.

> [card] Vendor model intake
>
> A "third-party model assessment" template that gates onboarding of new providers.

> [card] Compliance attestation
>
> Framework-specific templates that produce evidence-ready answers (EU AI Act, NIST RMF).

***

## API

| Endpoint | Use |
| - | - |
| `GET /api/assessments/templates` | List templates. |
| `POST /api/assessments/templates` | Create. |
| `GET /api/assessments` | List assessments (draft + submitted). |
| `POST /api/assessments` | Start a new assessment from a template. |
| `POST /api/assessments/{id}/submit` | Submit final answers. |

***

## Related resources

> [card] [Risk Dashboard](./risk-dashboard)
>
> Assessment scores are one input to the risk score.

> [card] [Evidence](./evidence)
>
> Submitted assessments can be promoted to evidence.


# Evidence
Source: https://docs.flowx.ai/5.9/observatory/governance/evidence

Collect, review, and approve evidence for governance controls — automated and manual, with gap analysis.

Evidence is what turns "we have policies" into "we can prove it". Observatory collects evidence automatically where it can (runs, evaluations, alerts) and lets reviewers attach manual artefacts where it can't (sign-offs, screenshots, external reports).

***

## Types of evidence

| Source | What it captures | Collection |
| - | - | - |
| **Automated — runs** | A successful or violating run that satisfies (or breaches) a control. | Automatic. |
| **Automated — policy evaluations** | An evaluation result tied to a policy and run. | Automatic. |
| **Automated — alert events** | An alert and its resolution. | Automatic. |
| **Manual — document** | Uploaded PDFs, screenshots, sign-off forms. | Manual. |
| **Manual — text attestation** | A reviewer's typed statement. | Manual. |

***

## Workflow

```mermaid theme={"dark"}
flowchart LR
    Source["Source: run, evaluation,<br/>alert, or upload"] --> Draft[Evidence: draft]
    Draft --> Review{Reviewer}
    Review -->|Approve| Approved[Approved]
    Review -->|Reject| Rejected[Rejected with reason]
    Approved --> Mapped[Mapped to controls]
    Rejected --> Discard[Discarded / retried]
```

Every piece of evidence goes through review unless the control is explicitly configured to auto-approve automated sources.

***

## Reviewing evidence

**1. Open Evidence**

The default view shows everything in the **Draft** state ordered by oldest first.

**2. Inspect the artefact**

For automated evidence, the run, evaluation, or alert is linked. For manual evidence, the upload is rendered inline.

**3. Pick a control**

Map the evidence to one or more controls (e.g. an EU AI Act requirement). One artefact can support multiple controls.

**4. Approve or reject**

Approving moves the artefact into the audit-ready set. Rejecting requires a reason — useful for training the team on what's acceptable.

***

## Gap analysis

The **Gaps** card flags controls that have no approved evidence. Use it to prioritise:

* Sort by framework (EU AI Act, NIST, ISO 42001)
* Sort by severity of the underlying control
* See last-approved-evidence age — anything older than a quarter shows as stale

```http theme={"dark"}
GET /api/evidence/gaps?framework=eu-ai-act
```

Returns the controls that lack approved evidence and the time since the last approval.

***

## API

| Endpoint | Use |
| - | - |
| `GET /api/evidence` | List with filters (state, control, framework). |
| `POST /api/evidence` | Submit manual evidence. |
| `POST /api/evidence/{id}/approve` | Approve. |
| `POST /api/evidence/{id}/reject` | Reject with reason. |
| `POST /api/evidence/collect` | Trigger an automated collection run. |
| `GET /api/evidence/gaps` | Gap analysis. |

> [!WARNING]
>
> Static routes (`/collect`, `/gaps`) are defined before `/{org_id}` in the router. Maintain that order on forks.

***

## Related resources

> [card] [Policies](./policies)
>
> Many evidence sources are policy evaluations.

> [card] [Compliance](../compliance/overview)
>
> Where mapped evidence shows up in the heatmap.


# Governance
Source: https://docs.flowx.ai/5.9/observatory/governance/overview

Policy engine, risk scoring, evidence collection, and assessments — the controls layer for production AI.

Governance is the layer that turns "we can see what the agent does" into "we know it's allowed to do that". Use it to enforce policies before runs reach users, score risk per app, gather evidence with a review workflow, and run repeatable assessments.

***

## What's inside

> [card] [Policies](./policies)
>
> Define and assign governance rules, evaluate them against runs, score compliance.

> [card] [Evidence](./evidence)
>
> Collect, review, and approve evidence — automated or manual.

> [card] [Assessments](./assessments)
>
> Dynamic questionnaires with weighted scoring.

> [card] [Risk Dashboard](./risk-dashboard)
>
> Six-dimensional risk score per app, rolled up to the org.

> [card] [AI Registry](./ai-registry)
>
> Catalogue of models, deployments, and ownership.

***

## How governance fits together

```mermaid theme={"dark"}
flowchart LR
    Registry["AI Registry<br/>(what we have)"] --> Risk
    Policies["Policies<br/>(what's allowed)"] --> Risk
    Assessments["Assessments<br/>(how we check)"] --> Evidence
    Evidence["Evidence<br/>(proof)"] --> Risk
    Risk["Risk score<br/>(where to focus)"] --> Compliance[Compliance heatmap]
```

The AI Registry is the inventory layer — what exists in your portfolio. Policies and Assessments produce the inputs to risk scoring. Evidence is the artefact layer that proves controls are met. Risk rolls up the four into a single per-app score, and Compliance translates the score into framework-specific status.

***

## When to start where

| Maturity | Start with |
| - | - |
| You just got Observatory running | [AI Registry](./ai-registry) — catalogue what you have before governing it. |
| You have telemetry but no controls | [Policies](./policies) — the highest-leverage place to add guardrails. |
| You have policies but no audit trail | [Evidence](./evidence) — turn enforcement into proof. |
| You report to a risk committee | [Risk Dashboard](./risk-dashboard) — give them one number per app. |
| You need formal sign-off | [Assessments](./assessments) — structured, repeatable, scoreable. |

***

## Related resources

> [card] [Compliance](../compliance/overview)
>
> Map controls to EU AI Act, NIST AI RMF, and ISO 42001.

> [card] [Observability](../observability/overview)
>
> The telemetry that policies and risk scoring read from.


# Policies
Source: https://docs.flowx.ai/5.9/observatory/governance/policies

Define, assign, and evaluate governance rules. Bundle rules into packs. Track compliance across apps.

Policies are the rules your runtime has to obey. Observatory's policy engine defines those rules, assigns them to apps, evaluates them against actual runs, and rolls the results up into a compliance score per app and per policy.

***

## Concepts

| Model | What it represents |
| - | - |
| **Policy** | A single rule. Carries severity (`low`, `medium`, `high`, `critical`) and an evaluator expression. |
| **PolicyPack** | A named bundle of policies that ship together (e.g. "PII basics", "EU AI Act high-risk app"). |
| **PolicyAssignment** | A pack assigned to one app. |
| **PolicyEvaluation** | One evaluation of one policy against one run. Stores the outcome and any captured violation context. |

```mermaid theme={"dark"}
flowchart LR
    Policy[Policy] --> Pack[PolicyPack]
    Pack --> Assignment[PolicyAssignment]
    App[App] --> Assignment
    Run[Run] --> Eval[PolicyEvaluation]
    Assignment --> Eval
    Policy --> Eval
```

***

## Severities

| Severity | Use for | Default behaviour |
| - | - | - |
| **critical** | Things that must never happen — PII leak, credential exposure | Page on first violation. |
| **high** | Serious deviations from expected behaviour | Alert, surfaces on Risk Dashboard. |
| **medium** | Quality issues — refusals, low confidence | Counted, no immediate alert. |
| **low** | Style or formatting | Counted only. |

***

## Creating a policy

**1. Open Policies → Policies**

Click **Add policy**.

**2. Name and describe**

The description is what reviewers see during an audit. Be specific.

**3. Pick a severity**

Critical and high contribute to the **Compliance** roll-up score; medium and low are reported but don't block.

**4. Define the evaluator**

Built-in evaluators cover PII detection, toxicity, prompt-injection patterns, and a few model-specific checks. Custom evaluators are user-defined Python predicates.

**5. Test against past runs**

Use **Evaluate** to dry-run the policy against the last N runs of a chosen app. The preview shows which runs would have violated.

***

## Bundling into packs

Policies travel in packs. A pack is what you assign — never an individual policy.

Typical packs:

* **PII basics** — emails, phone numbers, government IDs.
* **EU AI Act high-risk** — full set of obligations for high-risk apps.
* **Internal data hygiene** — no production data in development environments.
* **Customer-facing assistant** — refusal patterns, escalation triggers.

Create a pack from **Policies → Packs**, add policies to it, then assign the pack to one or more apps under **Assignments**.

***

## Compliance roll-up

The **Compliance** tab scores each app against the policies assigned to it. The score weights by severity — critical violations dominate, low violations contribute proportionally.

```http theme={"dark"}
GET /api/policies/compliance?app_id=...
```

Returns:

* `score` — 0–100
* `violations_by_severity`
* `top_violated_policies` — useful for prioritising remediation

***

## API

| Endpoint | Use |
| - | - |
| `GET /api/policies` | List policies. |
| `POST /api/policies` | Create. |
| `GET /api/policies/packs` | List packs. |
| `POST /api/policies/packs` | Create. |
| `POST /api/policies/assignments` | Assign a pack to an app. |
| `POST /api/policies/evaluate` | Run evaluation against a run or batch. |
| `GET /api/policies/compliance` | Roll-up score. |

> [!WARNING]
>
> FastAPI route ordering matters. Static routes (`/evaluate`, `/compliance`) must be defined before the `/{org_id}` catch-all. If you fork the router, keep that order.

***

## Related resources

> [card] [Evidence](./evidence)
>
> Capture the artefacts that prove policy enforcement.

> [card] [Risk Dashboard](./risk-dashboard)
>
> See how policy compliance feeds the per-app risk score.


# Risk Dashboard
Source: https://docs.flowx.ai/5.9/observatory/governance/risk-dashboard

Six-dimensional risk scoring per app, rolled up to the org for leadership visibility.

The Risk Dashboard answers one question: where in our AI portfolio should we focus first? Each app gets a score across six dimensions; the dashboard rolls those into a single number per app and an aggregate per org.

***

## The six dimensions

| Dimension | What it measures |
| - | - |
| **Operational risk** | Error rate, latency stability, drift events. |
| **Compliance risk** | Open compliance gaps weighted by framework severity. |
| **Policy risk** | Policy violations weighted by severity. |
| **Data risk** | Sensitivity of data the app handles and exposure. |
| **Model risk** | Model maturity, provider concentration, vendor dependencies. |
| **Governance risk** | Stale assessments, missing evidence, owner gaps. |

Each dimension scores 0–100. The composite is a weighted average; weights are configurable per org.

***

## How scores update

Scores recompute whenever the inputs change:

```mermaid theme={"dark"}
flowchart LR
    Telemetry["Telemetry<br/>(runs, drift, alerts)"] --> Op[Operational]
    Policies[Policy evaluations] --> Pol[Policy]
    Compliance[Compliance evaluations] --> Comp[Compliance]
    Registry["AI Registry<br/>(model, data tags)"] --> Data
    Registry --> Model
    Assessments[Assessments] --> Gov[Governance]
    Evidence[Evidence approvals] --> Gov
    Op & Pol & Comp & Data & Model & Gov --> Composite[Composite score]
```

Telemetry inputs update minute-by-minute. Governance inputs (assessments, evidence) update on submit.

***

## Reading the dashboard

**1. Start at the org roll-up**

Top card shows the org-wide composite plus distribution across the six dimensions. Spikes are where to look first.

**2. Pick the worst app**

The app list is sorted by composite score descending. Click the top row.

**3. Inspect the radar**

The radar chart shows which dimension dominates. A high "Policy risk" with low "Operational risk" means the app runs fine but is breaking rules.

**4. Drill into the inputs**

Click any dimension to see the underlying records — violating policies, stale evidence, recent drift events.

***

## Weighting the score

Default weights treat every dimension equally. Most orgs override:

| Profile | Typical weighting |
| - | - |
| Financial services | Compliance and policy weighted heavier. |
| Internal-tools team | Operational weighted heavier. |
| Healthcare | Data risk weighted heavier. |

Adjust weights from **Settings → Risk weighting**.

***

## Use cases

> [card] Where do we invest in remediation?
>
> The top of the app list is the answer.

> [card] Is risk going up or down?
>
> The trendline on the org card shows 30-day movement.

> [card] What does the board see?
>
> Export the org roll-up to PDF for governance committee packs.

> [card] Which apps are audit-ready?
>
> Sort ascending by **Governance risk** — lowest scores are best documented.

***

## Related resources

> [card] [Policies](./policies)
>
> Policy compliance feeds the Policy risk dimension.

> [card] [AI Registry](./ai-registry)
>
> The registry's data and model tags feed Data risk and Model risk.


# Alerts
Source: https://docs.flowx.ai/5.9/observatory/observability/alerts

Threshold-based alerting with cooldowns and SLA tracking across eight LLM metrics.

Alerts close the loop between observability and action. When a metric breaches the threshold you set, Observatory raises an event, optionally notifies an external system, and tracks SLA against acknowledgement and resolution times.

***

## Anatomy of an alert

```mermaid theme={"dark"}
flowchart LR
    Metric[Live metric] --> Rule{"Above<br/>threshold?"}
    Rule -->|Yes| Cooldown{"Inside<br/>cooldown?"}
    Cooldown -->|No| Fire[Create AlertEvent]
    Cooldown -->|Yes| Sleep[Skip]
    Fire --> Notify[Webhook / email]
    Fire --> SLA[Start SLA timer]
```

Two records back this:

* **AlertRule** — the user-defined rule. Metric, operator, threshold, cooldown, notification channel.
* **AlertEvent** — one occurrence of a rule firing. Carries acknowledged-at and resolved-at timestamps.

***

## Supported metrics

| Metric | Description |
| - | - |
| **error\_rate** | Share of errored runs in the window. |
| **p50\_latency** | Median latency in seconds. |
| **p95\_latency** | 95th-percentile latency in seconds. |
| **cost\_per\_hour** | Aggregated cost across runs in the last hour. |
| **token\_volume** | Total tokens in the window. |
| **drift\_composite** | Composite drift score from [Drift Monitor](./drift-monitor). |
| **policy\_violations** | Count of policy evaluations marked as violated. |
| **feedback\_negative** | Count of negative feedback events. |

***

## Operators

Pick the comparison that matches the metric:

| Operator | Use for |
| - | - |
| `>` | "Above threshold" — most common, used with latency, error rate, cost. |
| `<` | "Below threshold" — used with feedback scores, success rate. |
| `>=` | Inclusive variants of the above. |
| `<=` | |

***

## Creating a rule

**1. Open Alerts → Rules**

Click **Add rule**.

**2. Pick a metric and threshold**

For example, `p95_latency > 8` seconds.

**3. Set the cooldown**

Default 15 minutes. The same rule won't fire again inside the cooldown window even if the metric stays breached. This is what prevents flapping.

**4. Choose the destination**

Email, webhook, or both. The webhook payload mirrors the `AlertEvent` shape.

**5. Save and test**

Use the **Evaluate now** button on the rule row to fire a one-shot evaluation against current data, without touching the cooldown.

***

## API

| Endpoint | Use |
| - | - |
| `GET /api/alerts/rules` | List rules. |
| `POST /api/alerts/rules` | Create a rule. |
| `PUT /api/alerts/rules/{id}` | Update a rule. |
| `DELETE /api/alerts/rules/{id}` | Delete a rule. |
| `POST /api/alerts/rules/{id}/evaluate` | One-shot evaluation. |
| `GET /api/alerts/events` | List historical events. |
| `POST /api/alerts/events/{id}/ack` | Acknowledge an event (starts SLA clock). |
| `POST /api/alerts/events/{id}/resolve` | Resolve an event (stops SLA clock). |

***

## SLA tracking

When an event fires, two timers start: time-to-acknowledge and time-to-resolve. The Alerts page shows current values and historical compliance against the SLA targets you set per rule. Use this to:

* Prove operational readiness to auditors
* Spot rules that fire too often (noise) or never get acknowledged (ignored)

***

## Related resources

> [card] [Drift Monitor](./drift-monitor)
>
> The source of the `drift_composite` metric.

> [card] [Audit Trail](../governance/overview)
>
> Every ack and resolve is captured in the audit log.


# Analytics
Source: https://docs.flowx.ai/5.9/observatory/observability/analytics

Cost, latency, error rate, and model performance trends across all your projects.

Analytics aggregates the same telemetry you see in LLM Calls and Traces into trends you can act on at the team or portfolio level. Use it to spend less, not slower agents, and catch regressions across releases.

***

## What you can answer

> [card] Where is my LLM bill going?
>
> Cost by model and by agent, broken down per day. Drill into the dominant cost driver.

> [card] Are my agents getting slower?
>
> p50 / p95 / p99 latency over time, per agent and per model.

> [card] What's failing and how often?
>
> Error rate per model and per agent, with click-through to the failing runs.

> [card] Which model is best for this job?
>
> Model performance comparison — cost, latency, and error rate side by side.

***

## Key endpoints

These are the analytics API endpoints the UI is built on. You can call them directly to feed BI tools.

| Endpoint | Returns |
| - | - |
| `GET /api/analytics/usage/costs` | Daily cost by model and agent. |
| `GET /api/analytics/usage/models` | Per-model p50, p95, latency, error rate. |
| `GET /api/analytics/usage/agents` | Per-agent volume and cost. |
| `GET /api/analytics/usage/errors` | Error breakdown by reason and model. |

Filter parameters mirror the run filters: time range, app, agent, status, model.

***

## Cost tracking

Cost is computed at write time as `tokens × per-1k-token rate` for each LLM call. The rate table lives in `utils/model_costs.py`. Two consequences worth knowing:

* Adding a new model means adding a row to the cost table. Until that happens, calls with that model show `cost = 0`.
* Cost only applies to events of type `llm` — chain or tool spans don't accumulate cost themselves.

> [!NOTE]
>
> The cost column on the `Run` model is denormalised. Any backfill (price change, retroactive rate) requires re-running the cost recalc job.

***

## Performance views

The **Model performance** view sorts models on three axes you usually care about together:

* p50 and p95 latency
* Error rate (errors ÷ total)
* Average cost per call

A model that's cheaper but ten times slower is only worth it for batch workloads. The view shows them side by side so the trade-off is visible.

***

## Related resources

> [card] [Drift Monitor](./drift-monitor)
>
> For distribution-level changes the aggregate charts miss.

> [card] [Financial ROI](../roi/financial-roi)
>
> Turn cost and volume into per-agent ROI.


# Drift Monitor
Source: https://docs.flowx.ai/5.9/observatory/observability/drift-monitor

Distribution-level monitoring across five metrics, with composite scoring and timeline charts.

Aggregate dashboards catch the obvious. Drift Monitor catches the slow, distributional changes that aggregate charts miss — a small but steady increase in tool-call retries, a quiet shift in response length, a gradually rising refusal rate.

***

## What "drift" means here

Drift Monitor compares the distribution of a metric in a recent window against a baseline distribution. When the shape of the distribution moves enough, it's flagged. The composite drift score combines movement across all five tracked metrics.

```mermaid theme={"dark"}
flowchart LR
    Baseline[Baseline window] --> Compare{"Distribution<br/>comparison"}
    Recent[Recent window] --> Compare
    Compare --> Metric[Per-metric score]
    Metric --> Composite[Composite score]
    Composite --> Alert{Above threshold?}
    Alert -->|Yes| Notify[Drift event]
    Alert -->|No| Sleep[No-op]
```

***

## The five metrics

| Metric | What it captures |
| - | - |
| **Latency distribution** | Wall-clock duration of each call. |
| **Token-count distribution** | Total tokens (input + output) per call. |
| **Cost distribution** | Cost per call. |
| **Error rate** | Share of errored calls in the window. |
| **Output-length distribution** | Character or token count of completions. |

Each contributes to the composite score with a configurable weight.

***

## Running a drift check

Drift snapshots can run on a schedule or be triggered ad hoc through the API.

```http theme={"dark"}
POST /api/drift/compute
{
  "app_id": "...",
  "baseline_window": { "days": 30 },
  "recent_window": { "days": 7 }
}
```

Each computation produces a `DriftSnapshot` and one `DriftResult` per metric. The snapshot powers the timeline chart; the per-metric results power the distribution histograms.

***

## Reading the results

**1. Open the timeline**

The timeline plots the composite score over time. Spikes are the moments worth investigating.

**2. Drill into one snapshot**

Click a snapshot. The detail view splits the score into the five per-metric contributions.

**3. Compare distributions**

For each metric, the histogram overlays the baseline and recent distributions so the shift is visible.

**4. Jump to the runs**

From the snapshot detail, link out to the affected runs in [LLM Calls](./llm-calls) for ground-truth inspection.

***

## When to wire drift in

> [card] After a model swap
>
> Compare 7 days before vs 7 days after to confirm the new model behaves consistently.

> [card] After a prompt change
>
> Use the deployment timestamp as the boundary between baseline and recent.

> [card] As a regression backstop
>
> Schedule daily drift checks against a 30-day baseline. Spikes flag silent regressions.

> [card] Before regulatory reviews
>
> Auditors care about stability. Drift evidence is one of the artefacts they ask for.

***

## Related resources

> [card] [Alerts](./alerts)
>
> Trigger alerts when the composite score breaches a threshold.

> [card] [Compliance heatmap](../compliance/gap-analysis-heatmap)
>
> Drift evidence feeds into the operational-control views.


# LLM Calls
Source: https://docs.flowx.ai/5.9/observatory/observability/llm-calls

A searchable, filterable table of every LLM invocation from every project, with full input and output capture.

The LLM Calls page is the single place to find any LLM invocation that has ever passed through Observatory. Use it when you know what you're looking for — a user, an agent, an error spike, a slow call — and you want to drill into the actual prompt and completion.

***

## Key features

> [card] Lazy-loaded table
>
> Server-side pagination, sorting, and filtering. The page stays fast on datasets of millions of rows.

> [card] Global text search
>
> The search box runs across agent name, model, input, and output.

> [card] Filter by agent
>
> Quick filter to scope the table to a single agent name.

> [card] Time range
>
> Last Hour, 3H, 24H, 7D, 1M, 6M selector at the page header level.

> [card] Status badges
>
> Success, error, in-progress, and timed-out are colour-coded at a glance.

> [card] Detail drawer
>
> Click any row to open the full input, output, metadata, and cost breakdown.

***

## Columns

| Column | What it shows |
| - | - |
| **Status** | `success`, `error`, `started`, or timed-out (started > 5 min). |
| **Start time** | When the call began, in the viewer's local timezone. |
| **Agent** | The `@agent("name")` decorator value. |
| **Model** | Provider model identifier — `gpt-4`, `claude-opus-4-7`, etc. |
| **Duration** | Wall-clock seconds. Below 4s is success, 4–8s warning, >8s danger. |
| **User** | The user who triggered the call, when available in event metadata. |
| **Tokens** | Total tokens for the call (prompt + completion). |
| **Requests** | Number of HTTP requests bundled into the same logical call. |

***

## Filtering and search

The text search box matches `contains` against the agent name, model, input, and output fields. The agent dropdown is the equivalent of an exact-match filter on the **Agent** column.

For more complex queries — status, model, tags, latency bounds, cost — use the API directly:

```http theme={"dark"}
GET /api/run/?status=error&model=gpt-4&min_latency_s=8
```

See [LLMRunsQuery](../sdk/event-reporting#advanced-filtering) for the full parameter list.

***

## The detail drawer

Click any row to open the run detail drawer. It contains:

* The full prompt and completion (rendered as text or JSON depending on payload)
* The chain-of-calls tree if the run contained nested chains or tools — links to [Traces](./traces)
* Token and cost breakdown by model
* Metadata extracted by the SDK (`user_email`, custom tags, request ID)

> [!TIP]
>
> Long outputs are virtualised. Use the **Copy** button in the drawer header to grab the full payload when you need to paste it into a bug report.

***

## Common workflows

> [accordion] Find every failed call for one agent in the last 24 hours
>
> 1. Set the time range to **24H**.
> 2. Pick the agent from the **Filter by agent** dropdown.
> 3. Sort by **Status** to bring errors to the top.

> [accordion] Find calls slower than 8 seconds
>
> Sort by **Duration** descending. Rows with the red `danger` badge are above the 8s threshold.

> [accordion] Find a call by something the user typed
>
> Paste a snippet of the user's input into the search box. Matching rows surface immediately.

***

## Related resources

> [card] [Traces](./traces)
>
> For runs that contain nested chains and tools, see the trace view.

> [card] [Analytics](./analytics)
>
> Aggregate trends across the same data.


# Observability
Source: https://docs.flowx.ai/5.9/observatory/observability/overview

Real-time tracing, analytics, drift detection, and threshold alerts for every LLM call, chain, and tool invocation.

Observability is what tells you what your agents are actually doing. Every run is captured as a chain of events with inputs, outputs, timings, token counts, and cost. From those events you get search, analytics, drift detection, and alerts — without writing any of the plumbing yourself.

## What's inside

> [card] [LLM Calls](./llm-calls)
>
> Table of every LLM invocation with filters, search, and a detail drawer.

> [card] [Traces](./traces)
>
> Full chain-of-calls per run — chains, tools, retries, and durations.

> [card] [Analytics](./analytics)
>
> Cost by model, p50/p95 latency, error rate, and model performance.

> [card] [Threads](./threads)
>
> Multi-turn conversations grouped from `chat` events.

> [card] [Drift Monitor](./drift-monitor)
>
> Distribution monitoring across five metrics with composite scoring.

> [card] [Alerts](./alerts)
>
> Threshold rules with cooldown, escalation, and SLA tracking.

***

## When to use what

| You want to... | Use |
| - | - |
| Find a specific run by user, agent, or input text | [LLM Calls](./llm-calls) |
| Debug why a particular run failed | [Traces](./traces) |
| Track cost and latency over time | [Analytics](./analytics) |
| Inspect a multi-turn conversation | [Threads](./threads) |
| Catch behavioural shifts before users do | [Drift Monitor](./drift-monitor) |
| Get paged when something breaks | [Alerts](./alerts) |

***

## The data behind the views

Every event the SDK emits lands as one of two records in the database:

* A **Run** — one execution of an agent, chain, or tool. Carries the aggregate cost, duration, status, and saved flag.
* An **Event** — a leaf record inside a run, such as `chain_start`, `tool_end`, `chat`, or `saved`.

The Observability views are all built on top of these two tables. The [SDK reference](../sdk/overview) describes the event flow and how custom events plug in.

***

## Related resources

> [card] [SDK event reporting](../sdk/event-reporting)
>
> How events are batched, sent, and persisted.

> [card] [Governance](../governance/overview)
>
> Once you can see runs, the next step is shaping them.


# Threads
Source: https://docs.flowx.ai/5.9/observatory/observability/threads

Multi-turn conversations grouped from chat events, with per-message latency, cost, and feedback.

Threads group runs that share a conversational context, so you can review a multi-turn dialogue end-to-end instead of jumping between isolated runs.

***

## How threads are built

A thread is constructed from events with name `chat`. The SDK groups consecutive `chat` events that share the same `thread_id` (or, when none is supplied, the same agent and user within a time window).

```python theme={"dark"}
from flowxobservatory import track_event

track_event(
    "chat",
    role="user",
    content="What's my policy number?",
    thread_id="cust-42",
)
```

Each emitted `chat` event becomes one `ThreadMessage`. The aggregate `Thread` record carries:

* `started_at`, `ended_at`, `message_count`
* Total tokens and total cost across the thread
* Last message preview for the thread list

***

## What you see per thread

| Field | Meaning |
| - | - |
| **Thread** | A short preview of the most recent message. |
| **Agent** | The agent handling the conversation. |
| **User** | The user the conversation belongs to. |
| **Messages** | Total number of messages so far. |
| **Tokens** | Sum of all message tokens. |
| **Cost** | Sum of cost across all messages. |
| **Last activity** | When the most recent message landed. |

***

## Drilling into a thread

Click any thread row to open the full conversation. Each message exposes:

* The full `content`
* Per-message latency
* The associated run, with a link out to the [trace](./traces)
* Any user feedback attached via the feedback API

User feedback collected through the [User Feedback](../governance/overview) flow is rendered inline next to the corresponding assistant message.

***

## Filtering

| Filter | What it does |
| - | - |
| **Agent** | Scope to one agent. |
| **User** | Scope to one user. |
| **With feedback** | Show only threads that have at least one feedback record. |
| **Time range** | Standard time selector. |

***

## Common workflows

> [accordion] Find every conversation a user had with one agent
>
> Filter by **Agent** and **User**. Threads list returns the matching conversations chronologically.

> [accordion] Audit a conversation that received negative feedback
>
> Toggle **With feedback** and sort by **Last activity** descending. Open each thread and inspect the feedback annotation per message.

> [accordion] See the trace behind a single message
>
> Open the thread, click the **Run** link next to the message you care about — that opens the trace detail for the underlying run.

***

## Related resources

> [card] [Traces](./traces)
>
> Underlying chain-of-calls per message.

> [card] [Event reporting](../sdk/event-reporting)
>
> How `chat` events are emitted.


# Traces
Source: https://docs.flowx.ai/5.9/observatory/observability/traces

The chain-of-calls view for a single run — every chain, tool call, and event with timings and payloads.

Traces show the hierarchy of work inside one run. Use this view when you need to understand what happened end-to-end — which sub-chain decided to call which tool, how long each step took, and where the request went wrong.

***

## Span hierarchy

A trace is a tree of spans. Each span is one event the SDK reported:

```mermaid theme={"dark"}
flowchart TD
    Root[agent_start: claims-approval]
    Root --> C1[chain_start: extract-claim-data]
    C1 --> T1[tool_start: lookup_policy_holder]
    T1 --> T1E[tool_end]
    C1 --> C1E[chain_end]
    Root --> C2[chain_start: assess-risk]
    C2 --> L1[llm_call: gpt-4]
    C2 --> C2E[chain_end]
    Root --> RootE[agent_end]
```

Spans are nested by `parent_run_id`. The first span (root) is the agent call itself. Each chain or tool nested inside gets its own span. Leaf spans are the LLM calls or tool invocations.

***

## What you see per span

| Field | Meaning |
| - | - |
| **Name** | Decorator string from `@chain("...")`, `@tool("...")`, or the LangChain class name. |
| **Type** | `agent`, `chain`, `tool`, `llm`, or a custom event. |
| **Duration** | Wall-clock milliseconds between `*_start` and `*_end`. |
| **Status** | `success`, `error`, or `in_progress`. |
| **Input / output** | Raw payloads, rendered as text or JSON. |
| **Tokens** | Per-LLM-call token usage when the provider reports it. |
| **Cost** | Derived from token usage × the model's per-1k-token rate. |

***

## Reading a trace

**1. Open the run**

From [LLM Calls](./llm-calls) or [Threads](./threads), click a row to open the trace detail.

**2. Scan the tree for red**

Failed spans are highlighted. Their parent chain typically captures the error message in the output.

**3. Inspect the slow spans**

Sort or eyeball the duration column. A single tool call dominating the duration usually points at the bottleneck.

**4. Open the LLM call**

Click any `llm` span to see the prompt, system message, and completion alongside token usage.

***

## Comparing two runs

Observatory ships a comparison endpoint that surfaces side-by-side diffs of two runs. From the trace view, click **Compare** and pick a second run. Useful for:

* Investigating a regression after a prompt change
* Comparing the same input across two model versions
* Diffing a passing dataset run against a failing one

```http theme={"dark"}
POST /api/run/compare
{ "run_id_a": "...", "run_id_b": "..." }
```

***

## Saved runs

A run is marked **saved** when an event with name `saved` is emitted for it. Saved runs persist beyond retention windows and surface in dataset workflows.

```python theme={"dark"}
from flowxobservatory import track_event

track_event("saved", run_id=ctx.run_id)
```

See [Event reporting](../sdk/event-reporting#custom-events) for the full list of custom events.

***

## Related resources

> [card] [LLM Calls](./llm-calls)
>
> The table view that links into trace detail.

> [card] [Threads](./threads)
>
> Multi-turn views built on the same trace data.


# Observatory
Source: https://docs.flowx.ai/5.9/observatory/overview

Observe, govern, and prove the value of every AI agent running on FlowX from one platform.

Observatory · FlowX.AI

Run AI agents in production.
See it. Govern it. Prove it.

The operational layer for AI agents. Observatory turns raw LLM telemetry into the four things you need in production: visibility, control, regulatory evidence, and a credible ROI story.

[Get started](./getting-started)
[Instrument your SDK](./sdk/overview)

## What problem this solves

Generic LLM dashboards stop where the hard work starts. Observatory covers the full path: from the first trace your SDK emits to the EU AI Act control your auditor wants signed off, and the Net Present Value your CFO wants to see.

Reach for Observatory when you need to:

* See exactly what every agent, chain, and tool call did
* Enforce policies before unsafe behaviour reaches users
* Stay continuously aligned with EU AI Act, NIST AI RMF, or ISO 42001
* Quantify the financial impact of AI investments

## The four pillars

> [card] [Observability](./observability/overview)
>
> Real-time tracing, cost and latency analytics, drift detection, and threshold alerts for every LLM call.

> [card] [Governance](./governance/overview)
>
> Policy engine, risk scoring, evidence collection, and assessments to keep agents accountable.

> [card] [Compliance](./compliance/overview)
>
> EU AI Act, NIST AI RMF, and ISO 42001 controls mapped to your runtime with automated evaluation.

> [card] [ROI & value](./roi/overview)
>
> Risk-adjusted financial ROI, payback, NPV, and Monte Carlo sensitivity per agent and per project.

***

## How the pieces fit together

```mermaid theme={"dark"}
flowchart LR
    subgraph apps [Your apps]
        SDK[Observatory SDK]
    end

    subgraph platform [Observatory platform]
        API[Observatory API]
        DB[("PostgreSQL")]
        Guards[Observatory Guards]
    end

    subgraph ui [Observatory UI]
        Obs[Observability]
        Gov[Governance]
        Comp[Compliance]
        ROI[ROI & value]
    end

    SDK -->|/api/report| API
    API --> DB
    API -.->|safety checks| Guards
    DB --> Obs
    DB --> Gov
    DB --> Comp
    DB --> ROI
```

The SDK decorates your agents, chains, and tools and streams events to the Observatory API. The API stores telemetry in PostgreSQL and optionally forwards content through Observatory Guards for safety checks. Every pillar of the UI reads from the same data — what you observe is what you govern, certify, and report on.

***

## Concept glossary

| Term | What it means in Observatory |
| - | - |
| **Org** | The top-level tenant. Owns apps, datasets, prompts, and experiments. |
| **App** | A single AI app. Owns runs and API keys. |
| **Run** | One execution trace of an agent, chain, or tool. |
| **Event** | A log entry inside a run — for example `chain_start`, `tool_end`, `chat`. |
| **Dataset** | A test set of inputs used for evaluations. |
| **Prompt** | A versioned prompt template. |
| **Experiment** | An evaluation run that scores a prompt or model against a dataset. |
| **Policy** | A governance rule evaluated against runs. |
| **Evidence** | An artefact that proves a control is met. |
| **Risk score** | A six-dimensional score per app. |

***

## Where to go next

> [card] [Getting started](./getting-started)
>
> Connect your first project and emit your first trace in 15 minutes.

> [card] [SDK reference](./sdk/overview)
>
> Install the SDK and learn the `@agent`, `@chain`, and `@tool` decorators.

> [card] [Self-hosted setup](./setup/self-hosted)
>
> Stand up Observatory with Docker Compose for development or on-premise deployments.

> [card] [AI Platform](/5.9/ai-platform/ai-in-flowx)
>
> Build the agents that Observatory observes.


# Compliance ROI
Source: https://docs.flowx.ai/5.9/observatory/roi/compliance-roi

Quantify audit-labour savings and risk reduction from automated governance and evidence collection.

Compliance ROI is the half of the AI investment case that usually gets left off the slide. The cost of audits, evidence gathering, and regulatory response is real — and automating it has measurable financial impact.

***

## What this captures

| Component | What it measures |
| - | - |
| **Audit labour saved** | Hours that would have been spent gathering evidence manually, now produced automatically. |
| **Response time reduction** | Time-to-respond to a regulator or auditor, before vs after. |
| **Risk mitigation value** | Expected loss from a compliance failure × probability reduction. |
| **Continuous-control cost** | Cost of automated control evaluation — usually small. |

The net is `(audit_saved + risk_mitigation_value) − continuous_control_cost`.

***

## Audit labour saved

For each evidence type, Observatory tracks:

* Number of automated-evidence records produced
* Estimated manual-collection hours that would have been needed
* Loaded hourly rate for the role that would have collected them

Multiplied together, this is the audit-labour saved per period.

Default assumptions (configurable):

| Evidence type | Estimated manual hours per record |
| - | - |
| Run-based evidence | 0.10 |
| Policy evaluation evidence | 0.05 |
| Alert-event evidence | 0.25 |
| Manual evidence (your reviewer) | Not automated — these still cost time. |

***

## Risk mitigation value

Compliance failures have expected losses. The dashboard estimates two numbers:

* **Expected loss before Observatory** — based on framework severity and your risk-tier mix
* **Expected loss after Observatory** — same calculation with current gap status

The difference is the risk mitigation value attributed to Observatory's compliance work.

> [!NOTE]
>
> Risk mitigation is the most assumption-heavy part of the calculation. Show it alongside the audit-labour number — the latter is closer to ground truth.

***

## Where this rolls up

Compliance ROI is one of the inputs to the per-project [Financial ROI](./financial-roi). For projects where compliance work is substantial (banking, insurance, healthcare), it's typically 15–30% of the total ROI case.

***

## Reporting

Two reports executives ask for:

* **Quarterly audit-labour saved** — the audit-hours chart broken out by framework
* **Compliance-risk exposure trend** — month-over-month change in expected loss

Both export to PDF and CSV from **ROI → Compliance**.

***

## Related resources

> [card] [Evidence](../governance/evidence)
>
> Where the audit-labour numbers come from.

> [card] [Compliance](../compliance/overview)
>
> The frameworks that frame the risk-mitigation calculation.


# Financial ROI
Source: https://docs.flowx.ai/5.9/observatory/roi/financial-roi

Per-agent and per-project payback period, annual ROI %, and 5-year Net Present Value.

Financial ROI is the bottom of the stack — the actual numbers your CFO needs. Per-agent payback, annual ROI %, 5-year Net Present Value, with risk adjustment.

***

## Configuring agent baselines

The ROI calculation hinges on the baseline — what manual effort the agent replaces. Without a baseline, an agent has no measurable upside.

Each agent baseline carries:

| Field | Meaning |
| - | - |
| **Manual hours per case** | How long a human takes to do what the agent now does. |
| **Hourly rate** | Loaded cost — salary, benefits, overhead. |
| **Volume per month** | Realistic monthly throughput. |
| **Replacement ratio** | 1.0 means the agent fully replaces the human; lower values reflect partial replacement. |

The monthly labour saved is `hours × rate × volume × replacement_ratio`.

***

## The four numbers

| Number | Formula | What it tells you |
| - | - | - |
| **Monthly savings** | Labour saved − LLM cost − ops overhead | Run-rate impact. |
| **Payback period** | Implementation cost ÷ monthly savings | How fast the investment pays for itself. |
| **Annual ROI %** | (Annual savings − annual cost) ÷ implementation cost | Percentage return on the up-front investment. |
| **5-year NPV** | Discounted sum of net cashflows over 5 years | The standard finance comparison number. |

Default discount rate is 10% — configurable per org.

***

## Risk adjustment

A favourable headline ROI that ignores compliance risk is a fiction. Observatory adjusts:

```
risk_adjusted_npv = npv × (1 − risk_penalty)
```

The risk penalty is derived from the app's [Risk Dashboard](../governance/risk-dashboard) score. High-risk apps see a meaningful haircut on their NPV; low-risk apps see \~none.

This means an agent with low LLM cost and high compliance gaps may rank below an agent with higher LLM cost but a clean governance posture.

***

## Per-project view

Project-level ROI is the sum of per-agent ROI for agents in the project, with shared implementation costs amortised across them. The project view shows:

* Aggregate payback period
* Per-agent contribution stacked
* Sensitivity bands from [Monte Carlo](./sensitivity-analysis)

***

## Worked example

A claims-approval agent in production:

| Input | Value |
| - | - |
| Manual hours per case | 0.6 |
| Hourly rate | \$52 |
| Volume / month | 4,200 |
| Replacement ratio | 0.85 |
| LLM cost / month | \$1,180 |
| Implementation cost | \$48,000 |
| Risk penalty | 0.08 |

Computed:

* Monthly labour saved: 0.6 × 52 × 4,200 × 0.85 = \$111,384
* Monthly savings: 111,384 − 1,180 = \$110,204
* Payback: 48,000 ÷ 110,204 ≈ **0.4 months**
* Annual ROI %: ≈ **2,650%**
* 5-year NPV (10% discount): ≈ \$5.0M
* Risk-adjusted NPV: ≈ **\$4.6M**

***

## Related resources

> [card] [Compliance ROI](./compliance-roi)
>
> The audit-savings half of the calculation.

> [card] [Sensitivity analysis](./sensitivity-analysis)
>
> Replace point estimates with confidence ranges.


# ROI & value
Source: https://docs.flowx.ai/5.9/observatory/roi/overview

Risk-adjusted financial ROI, Value Outcome Units, and Monte Carlo sensitivity — board-grade numbers for AI investment.

ROI & value is the layer that turns telemetry into the kind of numbers a CFO will sign off on. Per-agent, per-project, risk-adjusted, with payback and NPV — and confidence ranges instead of single-point estimates.

***

## What's inside

> [card] [Value Outcome Units](./value-outcome-units)
>
> Group agents by business outcome to translate technical metrics into board-level language.

> [card] [Financial ROI](./financial-roi)
>
> Per-agent and per-project ROI: monthly savings, payback, annual ROI %, 5-year NPV.

> [card] [Compliance ROI](./compliance-roi)
>
> Quantify audit-labour savings and risk reduction from governance automation.

> [card] [Sensitivity analysis](./sensitivity-analysis)
>
> Monte Carlo simulations across ROI inputs — present a range, not a guess.

***

## Why this exists

LLM ops dashboards report cost and latency. They don't answer the question executives actually ask: **is this AI investment worth it?**

Observatory's ROI module exists because:

* Per-call cost is meaningless without a baseline ("what would humans cost?")
* A favourable point estimate hides the downside — what if adoption is half what we expected?
* Compliance work has a real cost that needs to live in the same calculation
* "We saved time" is rejected by finance unless it ties to a Value Outcome Unit with revenue or cost attached

***

## The ROI calculation

```mermaid theme={"dark"}
flowchart LR
    Baselines["Agent baselines<br/>(hours, rate, volume)"] --> Savings[Labour savings]
    Telemetry["Telemetry<br/>(actual cost, volume)"] --> LLMCost[LLM cost]
    Savings --> Net[Net contribution]
    LLMCost --> Net
    Risk[Compliance risk] -->|adjust| Net
    Net --> Payback[Payback period]
    Net --> NPV[5-year NPV]
    Net --> Monte[Monte Carlo bands]
```

Each agent has a **baseline** — what manual effort it replaces (hours, rate, volume). Observatory combines the baseline with actual telemetry-derived cost to compute net contribution. Compliance risk modifies the contribution. The numbers roll up through Value Outcome Units to per-project ROI.

***

## Where to start

| Maturity | Start with |
| - | - |
| You have agents but no baselines | [Financial ROI](./financial-roi) — configure baselines per agent. |
| You have multiple agents per outcome | [Value Outcome Units](./value-outcome-units) — group them. |
| You're presenting to executives | [Sensitivity analysis](./sensitivity-analysis) — show the range. |
| You're including governance in the case | [Compliance ROI](./compliance-roi) — add audit savings. |

***

## Related resources

> [card] [AI Registry](../governance/ai-registry)
>
> The inventory layer ROI rolls up against.

> [card] [Analytics](../observability/analytics)
>
> Cost telemetry the ROI numbers consume.


# Sensitivity analysis
Source: https://docs.flowx.ai/5.9/observatory/roi/sensitivity-analysis

Monte Carlo simulations across ROI inputs to show confidence ranges instead of single-point estimates.

A single ROI number invites a single objection — "what if your adoption number is wrong?" Sensitivity analysis pre-empts that by running thousands of simulations across the input distributions and reporting confidence bands.

***

## What gets simulated

Each ROI input has a distribution, not a point value. The defaults Observatory ships with:

| Input | Distribution | Why |
| - | - | - |
| **Volume** | Normal, ±20% | Adoption typically lands within 20% of forecast. |
| **Manual hours per case** | Normal, ±15% | Real measurements vary; 15% covers the noise. |
| **LLM cost per call** | Normal, ±10% | Provider pricing and prompt tuning swing it. |
| **Replacement ratio** | Beta(α=8, β=2) | Centred high, with a long tail toward partial replacement. |
| **Discount rate** | Triangular(0.07, 0.10, 0.13) | Treasury-tied, but uncertain. |

You can override any of these per agent or per project.

***

## What the analysis produces

Each Monte Carlo run produces:

* **p10 / p50 / p90** for monthly savings, payback, annual ROI, and NPV
* A **tornado chart** showing which inputs drive the most variance
* A **histogram** of NPV outcomes

The numbers most executives respond to:

* "Base case (p50) NPV is \$4.6M"
* "There's a 90% chance NPV is above \$2.9M"
* "There's a 10% chance NPV is above \$6.1M"

A point estimate of $4.6M is unfalsifiable. A 90% band of $2.9M–\$6.1M is something a board can plan around.

***

## Running an analysis

**1. Open ROI → Sensitivity**

Pick the project or VOU to analyse.

**2. Confirm or adjust input distributions**

The defaults are reasonable starting points. For mature deployments with measured variance, tighten them.

**3. Pick the iteration count**

1,000 iterations is enough for most use cases. 10,000 for board-grade reports. Anything beyond is overkill.

**4. Run**

Results appear in under a minute. They persist as a `SensitivityRun` so you can compare two analyses side by side.

***

## Reading the tornado

The tornado chart sorts inputs by how much variance they contribute to NPV. Typical result for a mature agent:

1. Volume — usually dominates
2. Replacement ratio — second largest
3. Manual hours per case — meaningful
4. LLM cost — surprisingly small (cost is small vs savings)
5. Discount rate — minor

If volume is the dominant driver and you don't have a tight forecast, that's where to invest measurement effort, not in tuning LLM cost.

***

## When to present this

> [card] Quarterly business reviews
>
> Pair the p50 with the p10–p90 band. Discuss what's driving the spread.

> [card] Investment committee
>
> A 90% confidence floor that's still positive is the strongest case you can make.

> [card] Post-mortems on miss
>
> When actuals come in below p50, the tornado tells you which assumption was wrong.

> [card] Pre-implementation sign-off
>
> Show the p10 — if the worst case is unacceptable, scope or delay.

***

## Related resources

> [card] [Financial ROI](./financial-roi)
>
> The point-estimate calculation sensitivity builds on.

> [card] [Value Outcome Units](./value-outcome-units)
>
> Sensitivity bands also apply at the VOU level.


# Value Outcome Units
Source: https://docs.flowx.ai/5.9/observatory/roi/value-outcome-units

Group agents by business outcome so technical metrics translate to board-level revenue and cost language.

A Value Outcome Unit (VOU) is a named business outcome you can attach agents to — Customer Onboarding, Fraud Detection, Claims Processing. Each VOU rolls up the ROI of every agent contributing to it, so the conversation moves from "GPT-4 is expensive" to "Claims Processing nets us \$1.4M a year".

***

## Why VOUs matter

LLM cost dashboards talk about agents. Executives talk about outcomes. VOUs are the bridge.

| Technical view | Executive view (VOU) |
| - | - |
| "claims-approval p95 is 2.1s" | "Claims Processing handles 14k cases/month" |
| "intake-bot costs \$0.07/call" | "Customer Onboarding saves \$480k/year" |
| "fraud-classifier error rate is 1.2%" | "Fraud Detection prevented \$2.1M in losses" |

***

## Anatomy of a VOU

| Field | Meaning |
| - | - |
| **Name** | Business-readable, e.g. "Claims Processing". |
| **Owner** | The business sponsor (not the engineering owner). |
| **Member agents** | One or many agents that contribute. |
| **Outcome metric** | The KPI the unit moves — cases handled, calls resolved, revenue saved. |
| **Baseline cost** | What this outcome cost before AI (manual labour, RPA, outsourcing). |
| **Risk factor** | A scalar 0.0–1.0 that adjusts net contribution for compliance risk. |

***

## Setting up a VOU

**1. Open ROI → Value Outcomes**

Click **New Value Outcome**.

**2. Name and assign an owner**

Use language the business uses. The owner sees this VOU in their executive view.

**3. Add agents**

Pick from the registered agents in your AI Registry. One agent can belong to multiple VOUs (e.g. a triage agent feeding both Onboarding and Support).

**4. Define the baseline**

Specify the manual cost for this outcome — for example, "12 FTE × $65/hr × 1,800 hrs/year" = $1.4M annual baseline.

**5. Set the risk factor**

Default 1.0 (no adjustment). Reduce for outcomes with significant compliance risk; the dashboard shows risk-adjusted net contribution alongside the raw number.

***

## What the VOU dashboard shows

For each Value Outcome:

* **Labour saved** — derived from baseline minus current ops cost
* **LLM cost** — sum of telemetry-derived cost across member agents
* **Net contribution** — labour saved minus LLM cost
* **Risk-adjusted net contribution** — net × risk factor
* **Volume** — outcome metric over time
* **Top contributing agents** — which agents drive most of the net

***

## Mapping to financial ROI

VOUs are the natural roll-up level for [Financial ROI](./financial-roi). The same payback, NPV, and annual ROI % numbers exist per agent and per VOU; most executive conversations live at the VOU level.

***

## Related resources

> [card] [Financial ROI](./financial-roi)
>
> Where VOU contributions become payback and NPV.

> [card] [Sensitivity analysis](./sensitivity-analysis)
>
> Show executives the range of outcomes, not just a point estimate.


# Decorators
Source: https://docs.flowx.ai/5.9/observatory/sdk/decorators

Reference for the @agent, @chain, and @tool decorators that auto-instrument your code.

Three decorators cover the vast majority of instrumentation needs. Each captures inputs and outputs, measures duration, and emits `*_start` and `*_end` events to Observatory.

***

## `@agent`

The top-level decorator. Wrap the function that handles one user request.

```python theme={"dark"}
from flowxobservatory import agent

@agent("claims-approval")
def run(ctx, payload):
    # business logic
    return result
```

### Parameters

**name** `string` *required*

The agent identifier. Shows up in the **Agent** column on LLM Calls, in Risk Dashboard, and in ROI baselines. Use kebab-case.

**user\_id** `string`

Identifier of the user this run belongs to. Surfaces in filters and Threads grouping.

**user\_props** `dict`

Arbitrary user properties attached to the run (e.g. `{"plan": "enterprise"}`).

**tags** `list[str]`

Tags attached to every run of this agent (e.g. `["claims", "prod"]`). Used for filtering in LLM Calls and analytics.

***

## `@chain`

Use for sub-steps that aren't external work but are worth seeing in the trace.

```python theme={"dark"}
from flowxobservatory import chain

@chain("extract-claim-data")
def extract(payload):
    return {"holder": payload["policy_id"], ...}
```

### Parameters

Same shape as `@agent`. The chain inherits the parent run's app and project context — you only need to name it.

> [!TIP]
>
> If you're using LangChain or LangGraph, the callback handler creates chain spans automatically. Use `@chain` for handwritten Python that lives between LangChain calls or for non-LangChain frameworks.

***

## `@tool`

Use for the leaf-level units of work — database queries, REST calls, file operations, computation.

```python theme={"dark"}
from flowxobservatory import tool

@tool("lookup_policy_holder")
def lookup_policy_holder(policy_id):
    return db.fetch(policy_id)
```

### Parameters

Same signature as `@agent` — `name`, `user_id`, `user_props`, `tags`.

***

## Async functions

All three decorators detect `async def` and wrap it natively. No different syntax.

```python theme={"dark"}
@agent("claims-approval")
async def run(ctx, payload):
    data = await extract(payload)
    return await decide(data)
```

***

## Error handling

If the wrapped function raises, the SDK:

1. Emits an `*_end` event with `status=error` and the exception's class and message.
2. Re-raises the exception unchanged.

Your error handling does not need to change. Observatory captures the error context; your `try/except` still runs.

***

## Class-based instrumentation

The decorators also work on methods. Use `@agent` on the entry method of a class:

```python theme={"dark"}
class ClaimsAgent:
    @agent("claims-approval")
    def run(self, ctx, payload):
        ...
```

`self` is excluded from captured inputs automatically.

***

## When NOT to use a decorator

| Situation | Better choice |
| - | - |
| You want to attach a custom event (`saved`, `chat`) | Call `track_event()` directly. |
| The function runs millions of times per request | Decorate the parent, not the leaf. |
| You only want to record success metrics | Use the analytics API on the recorded run instead. |

***

## Related resources

> [card] [Event reporting](./event-reporting)
>
> Custom events and the wire protocol.

> [card] [SDK overview](./overview)
>
> Install and configuration.


# Event reporting
Source: https://docs.flowx.ai/5.9/observatory/sdk/event-reporting

The event protocol, custom events, and how `saved` and `chat` shape downstream views.

Everything Observatory shows is built on top of a stream of events. The decorators emit them for you, but you can also call `track_event()` directly when you need a custom signal.

***

## The wire protocol

Events are HTTP-POSTed to `/api/report` as a JSON object with an `events` array. Each event is one object:

```json theme={"dark"}
{
  "name": "agent_start",
  "app_id": "...",
  "run_id": "...",
  "parent_run_id": null,
  "timestamp": "2026-05-29T08:42:11.123Z",
  "type": "agent",
  "metadata": {"user_email": "..."},
  "input": { ... },
  "output": null
}
```

The API authenticates each request with `Authorization: Bearer <FLOWX_OBSERVATORY_API_KEY>` and resolves `app_id` from the metadata or, failing that, from the project the key belongs to.

***

## Batching

The SDK queues events in memory and a background consumer flushes them on a short interval, posting each batch as `{"events": [...]}` to `/api/report`. On shutdown, the SDK flushes the remaining queue. Delivery is best-effort — if a flush fails, those events are dropped rather than blocking your app.

***

## Cost and token rules

The Observatory API computes cost only for events with `type=llm`. The rules:

1. The event must include `prompt_tokens` and `completion_tokens` (or `total_tokens`).
2. The event must include `model`.
3. There must be a row for the model in the API's model cost table.

Missing any of these → `cost = 0` for that event.

> [!WARNING]
>
> Adding a new model to your stack requires adding a cost row. Until that happens, the model's calls show up in traces but accumulate zero cost. Run the cost recalc job after editing the table.

***

## Custom events

Three custom events have semantic meaning to Observatory:

### `saved`

Marking a run as **saved** persists it past retention windows and surfaces it for dataset workflows.

```python theme={"dark"}
from flowxobservatory import track_event

track_event("saved", run_id=ctx.run_id)
```

Use after a human has signed off on the run — e.g. a reviewer approving a generated document.

### `chat`

A `chat` event represents one message in a conversation. The Threads view groups consecutive `chat` events by `thread_id` into a single thread.

```python theme={"dark"}
track_event(
    "chat",
    role="user" or "assistant",
    content="...",
    thread_id="cust-42",
)
```

Without `thread_id`, the SDK falls back to grouping by agent + user within a 30-minute window.

### `feedback`

Attaching feedback to a run or thread message.

```python theme={"dark"}
track_event(
    "feedback",
    run_id=ctx.run_id,
    rating="positive" or "negative",
    comment="...",
)
```

Feedback shows up alongside the run in LLM Calls, on the message in Threads, and contributes to the Manage 4.2 NIST control.

***

## Advanced filtering

The runs endpoint accepts the full filter set used by the LLM Calls UI:

```http theme={"dark"}
GET /api/run/?app_id=...&status=error&model=gpt-4&min_latency_s=8&tags=high-risk
```

Supported filters:

| Parameter | Type | Notes |
| - | - | - |
| `status` | enum | `success` / `error` / `started`. |
| `model` | string | Exact match. |
| `agent` | string | Exact match. |
| `min_latency_s` / `max_latency_s` | float | Wall-clock seconds. |
| `min_cost` / `max_cost` | float | USD. |
| `tags` | list | Any-of match. |
| `user_email` | string | Exact match. |
| `from` / `to` | ISO timestamp | Inclusive window. |

***

## Direct API use

If you can't use the Python SDK (different language, edge environment), report events directly:

```bash theme={"dark"}
curl -X POST "$FLOWX_OBSERVATORY_API_URL/api/report" \
  -H "Authorization: Bearer $FLOWX_OBSERVATORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "name": "agent_start",
    "type": "agent",
    "run_id": "01HXYZ...",
    "timestamp": "2026-05-29T08:42:11.123Z",
    "input": {"prompt": "..."},
    "metadata": {"agent": "claims-approval"}
  }]}'
```

The shape mirrors the Python SDK's payload exactly.

***

## Related resources

> [card] [Decorators](./decorators)
>
> The Python wrappers that emit standard events for you.

> [card] [Threads](../observability/threads)
>
> Where `chat` events become conversations.


# SDK overview
Source: https://docs.flowx.ai/5.9/observatory/sdk/overview

Install the Observatory Python SDK, configure the API key, and learn where instrumentation belongs.

The Observatory SDK is the bridge between your code and the Observatory platform. Decorate your agents, chains, and tools; the SDK captures inputs, outputs, timings, token usage, and cost, then ships events to `/api/report` in the background.

***

## Install

```bash theme={"dark"}
pip install flx-observatory-lib
```

The distribution is named `flx-observatory-lib`; the import name is `flowxobservatory`. Optional extras pull in framework integrations — for example `pip install flx-observatory-lib[langchain]` or `flx-observatory-lib[openai]`. Python 3.12 or newer is required.

***

## Configure

Call `configure()` once at startup, or set the equivalent environment variables — the SDK reads them on import.

```python theme={"dark"}
from flowxobservatory import configure

configure(
    org_id="your-org-id",
    workspace_id="your-workspace-id",
    project_id="your-project-id",
    api_url="https://your-observatory.example.com",
    api_key="FX-...",
)
```

| Variable | Required | Purpose |
| - | - | - |
| `FLOWX_OBSERVATORY_API_KEY` | Yes | API key from the Observatory **Home** page (scoped to organization + workspace). |
| `FLOWX_OBSERVATORY_API_URL` | Yes | Base URL of your Observatory API. |
| `FLOWX_OBSERVATORY_ORG_ID` | Yes | Organization ID. |
| `FLOWX_OBSERVATORY_WORKSPACE_ID` | Yes | Workspace ID. |
| `FLOWX_OBSERVATORY_APP_ID` | Yes | Project ID (maps to `project_id`). |
| `OBSERVATORY_TRACING` | No | Set to `false` to turn off instrumentation without removing decorators. |

```bash theme={"dark"}
export FLOWX_OBSERVATORY_API_KEY="FX-..."
export FLOWX_OBSERVATORY_API_URL="https://your-observatory.example.com"
export FLOWX_OBSERVATORY_ORG_ID="..."
export FLOWX_OBSERVATORY_WORKSPACE_ID="..."
export FLOWX_OBSERVATORY_APP_ID="..."
```

> [!WARNING]
>
> Don't ship the API key in source control. Use your platform's secret manager.

***

## How the SDK works

```mermaid theme={"dark"}
flowchart LR
    Code["Your code<br/>@agent / @chain / @tool"] --> Track[track_event]
    Track --> Queue["Event queue<br/>(in-memory)"]
    Queue --> Consumer["Background consumer<br/>(thread)"]
    Consumer --> API["POST /api/report<br/>(batched)"]
```

* Calls into decorated functions emit `*_start` and `*_end` events through `track_event`.
* The event queue is in-memory and non-blocking — your hot path is not on the critical send path.
* A background consumer flushes batches to `/api/report` on a short interval.
* Delivery is best-effort: if a batch fails to send, those events are dropped rather than blocking your app.

***

## Where instrumentation belongs

| Layer | Decorator | When to use |
| - | - | - |
| **Agent** | `@agent("name")` | The top-level function that handles one user request. |
| **Chain** | `@chain("name")` | A sub-step inside the agent — retrieval, planning, formatting. |
| **Tool** | `@tool("name")` | A unit of external work — DB query, REST call, file fetch. |

Use them like Russian dolls. Each level nests under the previous one, producing the chain-of-calls visible in [Traces](../observability/traces).

```python theme={"dark"}
from flowxobservatory import agent, chain, tool

@tool("lookup_policy_holder")
def lookup_policy_holder(policy_id):
    return db.fetch(policy_id)

@chain("extract-claim-data")
def extract(payload):
    holder = lookup_policy_holder(payload["policy_id"])
    return {"holder": holder, "claim": payload["claim"]}

@agent("claims-approval")
def run(ctx, payload):
    data = extract(payload)
    return decide(data)
```

***

## LangChain and LangGraph

The SDK ships a callback handler that auto-captures LangChain's `on_*_start` / `on_*_end` hooks. Register it once and every chain, tool, and LLM call inside the LangChain runtime emits events without further decoration.

```python theme={"dark"}
from flowxobservatory.integrations.langchain import FlowxObservatoryCallbackHandler
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(callbacks=[FlowxObservatoryCallbackHandler()])
```

LangGraph nodes are picked up through the same handler.

***

## Where to go next

> [card] [Decorators](./decorators)
>
> Full reference for `@agent`, `@chain`, `@tool`.

> [card] [Event reporting](./event-reporting)
>
> The event protocol, custom events, and `saved` / `chat` semantics.


# Environment variables
Source: https://docs.flowx.ai/5.9/observatory/setup/environment-variables

Reference for the environment variables each Observatory service reads.

Each Observatory service reads its configuration from environment variables. This page lists the variables grouped by service. Defaults shown are what the standard Docker Compose stack uses.

***

## Observatory API

### Database

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `POSTGRES_OBSERVATORY_URI` | PostgreSQL host and port. | `observatory-db:5432` | observatory-api |
| `POSTGRES_OBSERVATORY_DATABASE` | Database name. | `observatory` | observatory-api |
| `POSTGRES_OBSERVATORY_USERNAME` | Database username. | `observatory` | observatory-api |
| `POSTGRES_OBSERVATORY_PASSWORD` | Database password. | `S3cret` | observatory-api |

### Authentication (Keycloak)

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | Base URL of the auth server. | *(set per env)* | observatory-api |
| `SECURITY_OAUTH2_REALM` | Realm name (the organization ID). | *(set per env)* | observatory-api |
| `SECURITY_OAUTH2_CLIENT_ID` | OAuth2 client ID. | `flowx-platform-authenticate` | observatory-api |
| `SECURITY_OAUTH2_CLIENT_SECRET` | Client secret. | *(set per env)* | observatory-api |

> [!NOTE]
>
> Observatory authenticates against an external FlowX identity provider — the platform does not bundle its own Keycloak. Point these at your auth server; the realm is your organization ID.

### LLM providers

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `OPENAI_API_KEY` | OpenAI API key. | *(required for OpenAI)* | observatory-api |
| `ANTHROPIC_API_KEY` | Anthropic API key. | *(optional)* | observatory-api |
| `GOOGLE_API_KEY` | Google API key. | *(optional)* | observatory-api |
| `XAI_API_KEY` | xAI API key. | *(optional)* | observatory-api |
| `MISTRAL_API_KEY` | Mistral API key. | *(optional)* | observatory-api |
| `OLLAMA_BASE_URL` | Local Ollama URL. | `http://host.docker.internal:11434` | observatory-api |

### Operational

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `URL_PREFIX` | Path prefix the API is served under. | `/ai-observatory` | observatory-api |
| `CACHE_SIZE` | In-memory cache size (entries). | `1000` | observatory-api |
| `CACHE_TTL` | Cache TTL in seconds. | `3600` | observatory-api |
| `GUNICORN_WORKERS` | Worker processes. | `1` | observatory-api |
| `GUNICORN_TIMEOUT` | Worker timeout in seconds. | `600` | observatory-api |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of allowed CORS origins. | *(set per env)* | observatory-api |

***

## Observatory Web

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `BASE_API_URL` | Base URL of `observatory-api`. | `http://localhost:8091` | observatory-web |
| `PLATFORM_API_URL` | Base URL of `observatory-platform`. | `http://localhost:8092` | observatory-web |
| `KEYCLOAK_ISSUER` | OIDC issuer URL (auth server + realm). | *(set per env)* | observatory-web |
| `KEYCLOAK_REDIRECT_URI` | Post-login redirect. | `http://localhost:4900` | observatory-web |
| `KEYCLOAK_CLIENT_ID` | Public client ID. | `flowx-platform-authenticate` | observatory-web |
| `KEYCLOAK_SCOPES` | OAuth2 scopes. | `openid profile email offline_access` | observatory-web |

***

## Observatory Platform

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `LOG_LEVEL` | Logger level. | `INFO` | observatory-platform |
| `PROMETHEUS_ENABLED` | Toggle Prometheus metrics. | `false` | observatory-platform |
| `ALLOWED_ORIGINS` | Comma-separated list of allowed CORS origins. | *(set per env)* | observatory-platform |

***

## Observatory SDK

Set these in the environment of the app that uses the SDK — not on the platform itself:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_OBSERVATORY_API_KEY` | API key from the Observatory Home page. | *(required)* |
| `FLOWX_OBSERVATORY_API_URL` | Base URL of the Observatory API. | *(required)* |
| `FLOWX_OBSERVATORY_ORG_ID` | Organization ID. | *(required)* |
| `FLOWX_OBSERVATORY_WORKSPACE_ID` | Workspace ID. | *(required)* |
| `FLOWX_OBSERVATORY_APP_ID` | Project ID. | *(required)* |
| `OBSERVATORY_TRACING` | Set to `false` to turn off instrumentation. | `true` |

***

## PostgreSQL initialization

The default database setup creates these databases via `init_dbs/multiple-databases.sh` (`POSTGRES_MULTIPLE_DATABASES`):

* `observatory` — the main API store
* `dip`, `writer`, `agent_history`, `builder`, `insights`, `maildb` — companion services in the FlowX AI stack

Default local credentials: `observatory` / `S3cret`. Override via the `POSTGRES_OBSERVATORY_*` env vars in production.

***

## Related resources

> [card] [Self-hosted setup](./self-hosted)
>
> The Compose flow that consumes these variables.

> [card] [SDK overview](../sdk/overview)
>
> SDK-side environment configuration.


# Self-hosted setup
Source: https://docs.flowx.ai/5.9/observatory/setup/self-hosted

Stand up Observatory locally with Docker Compose for development, evaluation, or on-premise deployment.

Observatory ships as a set of containers you can bring up together. This guide is the fastest path from zero to a running platform you can point the SDK at.

***

## Prerequisites

* Docker 24+ and Docker Compose v2
* 8 GB RAM available for containers
* 20 GB disk available for PostgreSQL data
* Network access to the upstream LLM providers you intend to use

The default Compose stack includes:

| Service | Port | Purpose |
| - | - | - |
| `observatory-api` | 8091 | FastAPI backend |
| `observatory-web` | 4900 | Angular dashboard |
| `observatory-platform` | 8092 | Platform service (organizations, RBAC, Kubernetes integration) |
| `observatory-db` | 5432 | PostgreSQL |
| `observatory-docs` | 4903 | Bundled docs site |

> [!NOTE]
>
> Observatory authenticates against an **external** FlowX identity provider (Keycloak) — it is not bundled in the Compose stack. Point `SECURITY_OAUTH2_*` / `KEYCLOAK_*` at your auth server.

***

## Steps

**1. Clone the repo**

```bash theme={"dark"}
git clone --recurse-submodules git@github.com:flowx-ai/observatory2.0.git
cd observatory2.0
```

The submodules carry the API, web, platform, and SDK source. If you forgot `--recurse-submodules`, run:

```bash theme={"dark"}
git submodule update --init --recursive
```

**2. Create the network**

The platform expects an external Docker network shared with other FlowX services:

```bash theme={"dark"}
docker network create ai-services_node-network 2>/dev/null || true
```

**3. Configure the .env file**

Copy the example and edit the placeholders:

```bash theme={"dark"}
cp observatory-api/env.example observatory-api/.env
```

At minimum set `OPENAI_API_KEY` (or your provider equivalent), the `SECURITY_OAUTH2_*` values for your identity provider, and any custom LLM endpoints. See [Environment variables](./environment-variables) for the full table.

**4. Bring up the stack**

```bash theme={"dark"}
docker compose up -d --build
```

First start takes a few minutes — the databases initialise and schemas are created.

> [!TIP]
>
> `docker compose ps` shows all services in state `Up` or `healthy`.

**5. Confirm the web UI**

Open [http://localhost:4900](http://localhost:4900). You should see the login page. Sign in with credentials from your FlowX identity provider.

**6. Confirm the API**

```bash theme={"dark"}
curl http://localhost:8091/health
```

A `{"status": "ok"}` response means the API is reachable. The `/docs` endpoint serves the OpenAPI explorer.

***

## Rebuilding after code changes

When you edit source code in a submodule, always rebuild — restarting alone won't pick up the changes:

```bash theme={"dark"}
docker compose up -d --build
```

> [!WARNING]
>
> `docker compose restart` does not rebuild images. Always use `up -d --build` after touching service code.

***

## Persistence

The Compose stack persists:

* `pgdata` volume — all telemetry, evidence, runs
* `hf_hub` volume — cached model files

Both survive `docker compose down`. To wipe the platform back to factory state:

```bash theme={"dark"}
docker compose down -v
```

***

## Production deployment

The Compose stack is for development and evaluation. For production, see the Kubernetes manifests under `deployment/` and the deployment guide in the repo. Notable production-only concerns:

* Configure persistent volumes for the database
* Set up TLS at the ingress layer
* Point auth at your production identity provider

***

## Troubleshooting

> [accordion] Containers start but the UI shows 503
>
> Most often a missing port name in the service definition. Confirm `observatory-api` is reachable on port 8091 from the `observatory-web` container with `docker compose exec observatory-web curl http://observatory-api:8091/health`.

> [accordion] Postgres fails to start with 'database does not exist'
>
> The init script in `init_dbs/multiple-databases.sh` creates the companion databases on first start. If it didn't run, your existing pgdata volume is from an older build. Wipe and start over: `docker compose down -v && docker compose up -d --build`.

> [accordion] The SDK can't reach the API from outside Docker
>
> `FLOWX_OBSERVATORY_API_URL` must be `http://localhost:8091` for a host-machine app, not `http://observatory-api:8091` (which only resolves inside the Docker network).

***

## Related resources

> [card] [Environment variables](./environment-variables)
>
> Full reference for every env var the platform reads.

> [card] [Getting started](../getting-started)
>
> Once the platform is up, instrument your first agent.


# IAM solution
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/access-management-overview

Identity and access management (IAM) framework of processes, policies, and technologies for controlling access to digital identities.

## What is an Identity Provider (IdP)?

The IdP, Identity-as-a-Service (IDaaS), Privileged Identity/Access Management (PIM/PAM), Multi-factor/Two-factor Authentication (MFA/2FA), and numerous other subcategories are included in the IAM category.

IdP is a subset of an IAM solution that is dedicated to handling fundamental user IDs. The IdP serves as the authoritative source for defining and confirming user identities.

The IdP can be considered maybe the most important subcategory of the IAM field because it often lays the foundation of an organization's overall identity management infrastructure. In fact, other IAM categories and solutions, such as [IDaaS](https://jumpcloud.com/blog/identity-as-a-service-idaas), PIM/PAM, MFA/2FA, and others are often layered on top of the core IdP and serve to federate core user identities from the IdP to various endpoints. Therefore, your choice in IdP will have a profound influence on your overall IAM architecture.

> [!NOTE]
>
> We recommend **Keycloak**, a component that allows you to create users and store credentials.
>
> Every communication that comes from a consumer application, goes through a public entry point (API Gateway). To communicate with this component, the consumer application tries to start a process and the public entry point will check for authentication (Keycloak will send you a token) and the entry point validates it.

> [!NOTE]
>
> **Authorization split (5.8.0+):** Keycloak is authoritative for authentication, user attributes (used by [business filters](/5.9/docs/platform-deep-dive/user-roles-management/business-filters)), and federation with external IDPs. End-user roles, end-user groups, and project-scoped role assignment are managed in FlowX. See [Runtime authorization](./runtime-authorization).
>
> Up to 5.7.0, end-user groups were also managed in Keycloak.

> [!TIP]
>
> For more information on how to add roles and how to configure an IdP solution, check the following section:
>
> > [card] [Configuring an IAM solution](configuring-an-iam-solution)

## Roles and Keycloak entities reference

Use this section as a quick reference for the named roles, service accounts, and Keycloak realms you will encounter across the FlowX setup guides. Each entry links out to the full configuration page.

### End-user roles

| Name | Where it lives | What it does |
| - | - | - |
| **`FLOWX_ROLE`** | Keycloak realm role | Grants permission to start process instances and access active process data from the Designer. Required on the user (or on a mapped end-user group) for any process-start request. The default runtime role assigned when a process is created is the project-level **User** role, managed through [runtime authorization](./runtime-authorization). See [Configuring access roles for processes](../flowx-engine-setup-guide/configuring-access-roles-for-processes). |
| **End-user roles** (5.8.0+) | FlowX | Project-scoped roles assigned in FlowX, not in Keycloak. Used to gate Designer-time and runtime actions against specific projects. See [Runtime authorization](./runtime-authorization). |
| **End-user groups** | FlowX (5.8.0+); Keycloak (≤ 5.7.0) | Group end users for bulk role assignment. Managed in FlowX from 5.8.0 onward; previously held in Keycloak. |

### Backend service accounts

These are Keycloak clients used by FlowX backend services to authenticate against the platform. They live in the **service-accounts realm** (`00000002-0002-4002-8002-000000000002`) and are shared across the installation.

| Client | Used by |
| - | - |
| **`flowx-admin-sa`** | Admin / config services |
| **`flowx-process-engine-sa`** | Process engine, task-management plugin |

For the full list and the role assignments each one needs, see [Adding service accounts](./configuring-an-iam-solution#adding-service-accounts).

### Keycloak realms

| Realm ID | Purpose |
| - | - |
| **`master`** | Keycloak's built-in admin realm. |
| **`flowx`** (default name; configurable) | The realm where end-user identities, groups, and the `FLOWX_ROLE` realm role live. |
| **`service-accounts`** (`00000002-0002-4002-8002-000000000002`) | Backend service-account clients. Shared across the installation. |

> [!NOTE]
>
> End-user **roles** and **groups** are no longer modeled as Keycloak roles or groups starting with 5.8.0. If you are searching for a FlowX role name that is not listed in this quick reference, it is most likely either an end-user role configured in your own FlowX project (see [Runtime authorization](./runtime-authorization)) or a Keycloak group that was created in your local deployment for token-mapping purposes.

## Using Keycloak with an external IdP

> [!NOTE]
>
> Recommended Keycloak version: **26.x**

In all cases, IdP authentication is mandatory but otherwise, all attribute mapping is configurable, including roles and groups or the entire authorization can be performed by keycloak.

![Keycloak integration architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_1.png)

### AD or LDAP provider

In Lightweight Directory Access Protocol (LDAP) and Active Directory, Keycloak functionality is called federation or external storage. Keycloak includes an LDAP/AD provider.

![Keycloak LDAP federation architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/keycloak_2.png)

More details:

> [card] [Server admin LDAP](https://www.keycloak.org/docs/latest/server_admin/index.html#_ldap)

Configuration example:

> [card] [LDAP Keycloak](https://blog.please-open.it/posts/ldap-bind-proxy/)

### SAML, OpenID Connect, OAuth 2.0

Keycloak functionality is called brokering. Synchronization is performed during user login.

More details:

> [card] [Identity broker](https://www.keycloak.org/docs/22.0.5/server_admin/index.html#_identity_broker_first_login)

Configuration examples for ADFS:

> [card] [SAML for React SPA](https://blog.samlsecurity.com/post/saml-for-react-spa/)

> [card] [Keycloak ADFS-OIDC](https://www.michaelboeynaems.com/keycloak-ADFS-OIDC.html)

For the full picture of platform security, including runtime authorization, audit, and AI data protection, see the [Security overview](/5.9/docs/platform-overview/security).


# Configuring an IAM solution (Keycloak)
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/configuring-an-iam-solution

This guide provides step-by-step instructions for configuring a minimal Keycloak setup to manage users, roles, and apps efficiently.

This guide walks through configuring a minimal Keycloak setup to efficiently manage users, roles, and apps. Keycloak is an open-source Identity and Access Management (IAM) solution that secures apps and services with little to no coding.

## Prerequisites

Before you begin, ensure you have the following:

* Keycloak installed
* Administrative access to the Keycloak server
* Basic understanding of IAM concepts

***

> [!NOTE]
>
> Recommended Keycloak version: **26.x**
>
> **Note for Keycloak 26+**: If using Keycloak version 26 or above, additional email configuration is required in the realm settings to prevent bad request errors when creating users. See the realm configuration section for details.

> [!NOTE]
>
> **Custom certificates (truststore):** trust for your Keycloak server's own outbound TLS connections, for example to an LDAP server or an external identity provider signed by an internal certificate authority, is configured on Keycloak, not in FlowX. Keycloak recommends the `--truststore-paths` option (`KC_TRUSTSTORE_PATHS` environment variable) over setting Java `javax.net.ssl` truststore properties. See the [Keycloak trusted certificates guide](https://www.keycloak.org/server/keycloak-truststore). Trust that FlowX services need to reach Keycloak over TLS is a separate setting on the FlowX deployment, not on Keycloak.

## Recommended Keycloak setup

To configure a minimal required Keycloak setup, this guide covers the following steps:

**1. Create a new realm**

Define available roles and realm-level roles assigned to new users.

**2. Create new users**

**3. Add clients**

Configure the client authentication, valid redirect URIs, and enable the necessary flows.

**4. Add mappers**

**5. Add service accounts**

Set up **admin**, **task management**, **process engine**, **scheduler**, **integration designer**, **runtime manager**, **organization manager**, **email gateway**, and **license** service accounts.

Before starting, if you need further information or a broader understanding of Keycloak, refer to the official Keycloak documentation:

> [card] [Keycloak documentation](https://www.keycloak.org/documentation)

***

## Creating a new realm

> [!NOTE]
>
> The guided setup flow via the Organization Manager creates both the user realm and the service accounts realm automatically. You only need to follow this section if you are configuring Keycloak manually, or if you need to customize realm settings beyond the defaults.

A realm is a space where you manage objects, including users, apps, roles, and groups. Creating a new realm is the first step in setting up Keycloak manually. Follow the steps below to create a new realm in Keycloak:

**1. Log in to the Keycloak Admin Console**

Log in to the Keycloak Admin Console using the appropriate URL for your environment (e.g., QA, development, production).

![Keycloak Admin Console login page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_admin_login.png)

**2. Create realm**

In the top left corner dropdown menu, click **Manage realms** then click **Create realm**.

> [!NOTE]
>
> If you are logged in to the master realm, this dropdown menu lists all the realms created.

**3. Enter realm details**

Set the **Realm name** to your organization ID and click **Create**. This is the UUID provided by FlowX during organization registration — the same value you configure as the `ORGANIZATION_ID` parameter on the backend services. A friendly name such as the organization code can go in the **Display name** field under **Realm settings** → **General**.

> [!WARNING]
>
> **The Realm name must be identical to the organization ID provided by FlowX.** FlowX resolves the organization from the token issuer URI (`<auth-server>/realms/<organization-id>`), and the `org_id` token claim carries the same value. If the realm name differs from the organization ID, user tokens will not match any organization and authentication fails.

![Create realm dialog in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_create_realm.png)

**4. Configure realm settings**

**Tokens** → **Access Token Lifespan**: Set to **30 Minutes** (recommended).

![Access token lifespan setting in realm configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_access_token_lifespan.png)

**Login** → **Email settings**: Configure email authentication settings.

![Email settings in Keycloak Login tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_email_settings.png)

> [!WARNING]
>
> **For Keycloak versions 26 and above**: You must configure the email settings in the **Login** tab to avoid bad request errors when creating users in FlowX Designer. Make sure to enable **Email as username** and **Login with email** toggles as shown in the realm settings.

> [!TIP]
>
> Verify your realm is created correctly: navigate to the realm selector dropdown in Keycloak and confirm your new realm appears in the list.

***

## Creating new users

Creating new users is a fundamental part of managing access within Keycloak. Follow these steps to create a new user in a realm and generate a temporary password:

**1. Navigate to users**

In the left menu bar, click **Users** to open the user list page.

**2. Add a new user**

Click **Create new user**.

Fill in the user details and set **Email Verified** to **Yes**.

![Create new user form in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_create_user.png)

**3. Set temporary password**

Save the user, go to the **Credentials** tab, and set a temporary password. Ensure the **Temporary** checkbox is checked.

![Setting temporary password in Keycloak Credentials tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_temporary_password.png)

> [!TIP]
>
> Verify the user is created: navigate to **Users** and confirm the new user appears in the list with **Email Verified** set to **Yes**.

### Password policy

FlowX.AI enforces the following password policy for all user accounts:

| Rule | Requirement |
| - | - |
| Minimum length | 8 characters |
| Maximum length | 64 characters |
| Uppercase | At least one uppercase letter |
| Lowercase | At least one lowercase letter |
| Number | At least one digit |
| Special character | At least one of `!@#$%^&*()_+-` |
| Additional | Cannot match the user’s email address |

> [!TIP]
>
> Configure your Keycloak realm password policy to match these requirements. In Keycloak, go to **Authentication** → **Policies** → **Password Policy** and add the corresponding policy rules.

***

## Adding clients

A client represents an application instance that is associated with a specific realm.

### Adding an OAuth 2.0 client

Add a client named `flowx-platform-authenticate`, used for login, logout, and refresh token operations by web and mobile apps.

**1. Navigate to Clients**

Click **Clients** in the top left menu, then click **Create client**.

![Keycloak Clients page with Create client button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_create_client.png)

**2. Configure general settings**

In the **General Settings** tab configure the following properties:

* Set a client ID to `{your-client-name}-authenticate`.
* Set the **Client type** to `OpenID Connect`.

![Client general settings with Client ID and Client type](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_client.png)

**3. Configure capability config**

Now click **Next** and configure the **Capability config** details:

* Enable **Direct Access Grants**.
* Enable **Implicit Flow Enabled**.

![Capability config with Direct Access Grants and Implicit Flow enabled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_auth_client_config.png)

**4. Set valid redirect URIs**

Click **Next** and configure **Login settings**:

* Set **Valid redirect URIs**, specifying the URI patterns a browser can redirect to after a successful login or logout. Spell out the full host and place the wildcard in the path: `https://your-designer-host/*`. Never place the wildcard inside or immediately after the host (`https://your-designer-host*`).

![Login settings with Valid redirect URIs](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_auth_client_login_settings.png)

> [!WARNING]
>
> Starting with Keycloak 26.6.3 (also backported to the 26.4 line in 26.4.13), the trailing `*` in a redirect URI applies only to the path, never to the host. A host-wildcard pattern such as `https://designer*` is saved by Keycloak without any error but never matches, so login fails with `Invalid parameter: redirect_uri`. Before upgrading an existing Keycloak past these versions, review the client's **Valid redirect URIs** and replace any host-wildcard entries with full-host, path-form patterns (`https://your-host/*`), either in the admin console or with `kcadm.sh`.

> [!NOTE]
>
> **Self-hosted:** The Organization Manager can populate Keycloak redirect URIs for you. If you leave `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` empty, the allowed list is derived from `FLOWX_DEFAULT_DESIGNER_HOMEURI` and `FLOWX_DEFAULT_RUNTIME_HOMEURI` with a `/*` suffix. See [Organization Manager setup — Self-hosted URL configuration](/5.9/setup-guides/organization-manager-setup#self-hosted-url-configuration).

**5. Configure additional settings**

After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

* **Front Channel Logout**: Toggle OFF.

* **Backchannel Logout Session Required**: Toggle OFF.

![Logout settings with Front Channel Logout and Backchannel toggled OFF](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/kc_auth_client_logout_settings.png)

**6. Add mappers**

Add **mappers** to `{your-client-name}-authenticate` client.

> [!TIP]
>
> For instructions on adding mappers and understanding which mappers to add to your clients, refer to the section on [**Adding Protocol Mappers**](#adding-protocol-mappers).

#### Example configuration for microservices

FlowX services validate incoming tokens using **JWT public key** validation. The shared security library (`application-security-client.yaml`) handles most configuration automatically.

```yaml theme={"dark"}
security:
  type: jwt-public-key                                # JWT public key validation
  oauth2:
    base-server-url: https://keycloak.example.com      # Base URL of the Keycloak server
    sa-realm: 00000002-0002-4002-8002-000000000002      # Service accounts realm name (fixed UUID convention) — must match the Realm name field in Keycloak

# Organization manager is a required dependency for all services
flowx:
  lib:
    security:
      services:
        organization-manager:
          base-url: http://organization-manager:80
```

| Configuration Key | Value/Example | Description |
| - | - | - |
| `security.type` | `jwt-public-key` | Validates tokens using JWT public key (no introspection endpoint needed). |
| `security.oauth2.base-server-url` | `https://keycloak.example.com` | Base URL of the Keycloak server. |
| `security.oauth2.sa-realm` | `00000002-0002-4002-8002-000000000002` | Fixed-UUID name of the service accounts realm — must match the **Realm name** field in Keycloak (not the Display name). |
| `flowx.lib.security.services.organization-manager.base-url` | `http://organization-manager:80` | Organization manager URL (required dependency for all services). |

***

## Adding protocol mappers

Protocol mappers in Keycloak allow you to transform tokens and documents, enabling actions such as mapping user data into protocol claims and modifying requests between clients and the authentication server. This provides greater customization and control over the information contained in tokens and exchanged during authentication processes.

![Protocol mappers overview in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_dedicated_scope_mappers.png)

To enhance your clients' functionality, add the following common mappers:

* [Group Membership mapper ](#group-membership-mapper) (`realm-groups`)
  * Maps user groups to the authorization token.
* [User Attribute mapper](#user-attribute-mapper) (`business filter mapper`)
  * Maps custom attributes, for example, mapping the [businessFilters ](../../docs/platform-deep-dive/user-roles-management/business-filters) list, to the token claim.
* [User Realm role](#user-realm-role-mapper) (`realm-roles`)
  * Maps a user's realm role to a token claim.

> [!NOTE]
>
> The mappers should be configured to be included in the **token introspection** response. Previously, mappers were primarily added to the `/userinfo` endpoint, but modern Keycloak versions support adding them to token introspection, which is the recommended approach for better security and performance.

By incorporating these mappers, you can further customize and enrich the information contained within your tokens, ensuring they carry the necessary data for your applications.

### Group membership mapper

Steps to add a Group Membership mapper:

**1. Navigate to Clients**

From the Keycloak admin console, go to **Clients** and select your desired client.

![Clients list in Keycloak](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_clients_list.png)

**2. Select Client Scopes**

In the client settings, click on **Client Scopes**.

Select the **dedicated client scope**: `{your-client-name}-authenticate-dedicated` to open its settings.

![Dedicated client scope selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_client_scopes_dedicated.png)

**3. Select client scope**

Make sure the **Mappers** tab is selected within the dedicated client scope.

![Mappers tab in client scope](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_dedicated_scope_mappers.png)

**4. Add a New Mapper**

Click **Add Mapper**. From the list of available mappers, choose **Group Membership**.

![Add Group Membership mapper from predefined list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_predefined_mapper_groups.png)

**5. Provide mapper details**

**Name**: Enter a descriptive name for the mapper to easily identify its purpose, for example `realm-groups`.

**Token Claim Name**: Set the token claim name, typically as `groups`, for including group information in the token.

**Add to ID Token**: Toggle OFF.

**Add to token introspection**: Toggle ON.

![Group Membership mapper configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_group_membership_mapper.png)

This group membership mapper includes the user's group information in the token for authorization purposes.

### User attribute mapper

To include custom attributes such as business filters in the token claim, follow these steps to add a user attribute mapper:

**1. Navigate to Client Scopes**

From the Keycloak admin console, go to **Clients** and select your desired client.

Click on **Client Scopes** and choose `{your-client-name}-authenticate-dedicated` to open its settings.

Ensure the **Mappers** tab is selected.

![Client scopes Mappers tab for attribute mapper](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/attrMapper1.png)

**2. Add a New Mapper**

Click **Add mapper**. From the list of available mappers, select **User Attribute**.

**3. Provide mapper details**

* **Mapper Type**: Select **User Attribute**.
* **Name**: Enter a descriptive name for the mapper, such as "Business Filters Mapper".
* **User Attribute**: Enter `businessFilter`.
* **Token Claim Name**: Enter `attributes.businessFilters`.
* **Add to access token**: Toggle ON.
* **Add to token introspection**: Toggle ON (recommended).
* **Multivalued**: Toggle ON.
* **Aggregate attribute values**: Toggle ON.

![User Attribute mapper configuration for business filters](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/attrMapper.png)

This user attribute mapper includes the custom attribute "businessFilters" in the token claim under the name "attributes.businessFilters", making business filter information available within your app.

For more information about business filters, refer to the following section:

> [card] [Business filters](../../docs/platform-deep-dive/user-roles-management/business-filters)

### Runtime groups attribute mapper

The runtime authorization service reads each user's FlowX end-user group memberships from the `attributes.runtimeGroups` claim on the access token, matching every value against the names of [end-user groups](./runtime-authorization#end-user-groups) defined in FlowX by exact string comparison.

> [!WARNING]
>
> **No `attributes.runtimeGroups` mapper ships in the realm template.** The `flowx-platform-authenticate` client ships with mappers for realm roles, realm groups, business filters, and the designer-user flag, but none for runtime groups. Add one only when group membership is maintained **outside FlowX** — as native Keycloak groups, or in a federated identity provider. When an admin assigns users to end-user groups directly in the Designer, the membership is stored in FlowX and needs no token claim.

> [!WARNING]
>
> **Migration-created default group renamed in 5.9.2.** The end-user group that the 5.1.x upgrade migration creates for former `FLOWX_ROLE` holders is named **Users Group** as of 5.9.2 — on 5.9.0 and 5.9.1 it was created as `User`, and upgrading to 5.9.2 or later renames it. If a mapper or external IDP claim emits the old name `User`, the value no longer matches any group and affected users lose solution access on their next sign-in, with no error logged. Update the emitted group name to `Users Group` (or to the group's current name, if you have renamed it since). Groups created by your own admins are not renamed.

There are two ways to populate the claim, depending on where you maintain membership. Use one for a given group source, not both.

#### From native Keycloak groups

Use this when your end users are organized into **Keycloak groups** in the FlowX realm (for example, users imported into the realm and managed there). A **Group Membership** mapper emits the user's group names directly as `attributes.runtimeGroups`.

**1. Navigate to Client Scopes**

From the Keycloak admin console, go to **Clients** and select `flowx-platform-authenticate`. Click **Client Scopes** and choose `flowx-platform-authenticate-dedicated`. Open the **Mappers** tab.

**2. Add a New Mapper**

Click **Add mapper**. From the list of available mappers, select **Group Membership**.

**3. Provide mapper details**

* **Mapper Type**: Select **Group Membership**.
* **Name**: Enter a descriptive name, such as "Runtime Groups Mapper".
* **Token Claim Name**: Enter `attributes.runtimeGroups`.
* **Full group path**: Toggle OFF. The claim then carries plain group names (for example `someGroup`) instead of paths (`/someGroup`), so they match FlowX end-user group names.
* **Add to ID token**: Toggle OFF.
* **Add to access token**: Toggle ON.
* **Add to token introspection**: Toggle ON.

A Keycloak group name only grants access if an end-user group with the same name exists in FlowX. Names in the claim that don't match a FlowX end-user group are ignored.

#### From a federated identity provider

Use this when an external IDP supplies group membership through federation. The [external IDP federation mapper](#external-idp-federation-mapper) writes the source claim into the `flowxIdPGroups` user attribute; a **User Attribute** mapper then promotes that attribute onto the access token as `attributes.runtimeGroups`.

**1. Navigate to Client Scopes**

From the Keycloak admin console, go to **Clients** and select `flowx-platform-authenticate`. Click **Client Scopes** and choose `flowx-platform-authenticate-dedicated`. Open the **Mappers** tab.

**2. Add a New Mapper**

Click **Add mapper**. From the list of available mappers, select **User Attribute**.

**3. Provide mapper details**

* **Mapper Type**: Select **User Attribute**.
* **Name**: Enter a descriptive name, such as "Runtime Groups Mapper".
* **User Attribute**: Enter `flowxIdPGroups`.
* **Token Claim Name**: Enter `attributes.runtimeGroups`.
* **Add to access token**: Toggle ON.
* **Add to token introspection**: Toggle ON (recommended).
* **Multivalued**: Toggle ON.
* **Aggregate attribute values**: Toggle ON.

The values that appear in `attributes.runtimeGroups` must match the names of [end-user groups](./runtime-authorization#end-user-groups) defined in FlowX. Federated logins populate `flowxIdPGroups` automatically through the [external IDP federation mapper](#external-idp-federation-mapper) below.

> [!WARNING]
>
> **User attribute schema must accept `flowxIdPGroups`.** This attribute is FlowX-internal and is not part of the realm's declared user profile. The realm's **unmanaged attributes** policy under **Realm settings → User profile** must be set to **Enabled** (the Keycloak default), otherwise the IDP mapper silently drops the value and `attributes.runtimeGroups` arrives empty. The same applies to `businessFilter` and `designerUser`. If your security posture requires unmanaged attributes to be disabled, declare `flowxIdPGroups`, `businessFilter`, and `designerUser` explicitly in the user profile with admin-only edit permissions.

> [!TIP]
>
> **Data hygiene at the source.** Group identifiers are matched against FlowX end-user group names by exact string comparison, so trailing whitespace, mixed casing, or stray punctuation in the source IDP's user record will silently break authorization. The `designerUser` attribute is stored on the user record as the string `"true"` or `"false"`; the client mapper handles the conversion to a JSON boolean at token emission via the **Claim JSON Type** setting.

### Designer user attribute

The `designerUser` user attribute is a boolean that flags whether a user has Designer access to the project. The `flowx-platform-authenticate` client exposes it on the access token as `attributes.designerUser`; the runtime authorization service reads the claim to skip role checks for designers running their own projects.

In FlowX-managed Keycloak deployments the attribute is set automatically at organization provisioning, and the mapper ships with the standard client setup. Add the mapper manually only when you operate Keycloak yourself.

**1. Navigate to Client Scopes**

From the Keycloak admin console, go to **Clients** and select `flowx-platform-authenticate`. Click **Client Scopes** and choose `flowx-platform-authenticate-dedicated`. Open the **Mappers** tab.

**2. Add a New Mapper**

Click **Add mapper**. From the list of available mappers, select **User Attribute**.

**3. Provide mapper details**

* **Mapper Type**: Select **User Attribute**.
* **Name**: Enter a descriptive name, such as "Designer User Mapper".
* **User Attribute**: Enter `designerUser`.
* **Token Claim Name**: Enter `attributes.designerUser`.
* **Add to access token**: Toggle ON.
* **Add to token introspection**: Toggle ON (recommended).
* **Multivalued**: Toggle OFF.
* **Claim JSON Type**: Select **boolean**.

### External IDP federation mapper

This mapper reads the source IDP's group claim and writes the value into the FlowX-side `flowxIdPGroups` user attribute. The [Runtime groups attribute mapper](#runtime-groups-attribute-mapper) above then promotes that user attribute onto the FlowX access token as `attributes.runtimeGroups`.

**1. Open the federated IDP entry**

From the Keycloak admin console, go to **Identity providers** and open the entry for the federated IDP. Click the **Mappers** tab.

**2. Add a New Mapper**

Click **Add mapper**. From the **Mapper Type** list, select **Attribute Importer** (Keycloak's `oidc-user-attribute-idp-mapper`; some versions label it **OpenID Connect Attribute to User Attribute**).

**3. Provide mapper details**

* **Name**: Enter a descriptive name, such as "Source groups to flowxIdPGroups".
* **Sync Mode Override**: Select **Force** so subsequent logins re-import the value and pick up source-side group changes.
* **Claim**: Enter the name of the source IDP claim that carries the user's group memberships. The exact name depends on the source IDP — for example, FlowX-to-FlowX federation typically uses `groupsList`; Entra ID typically uses the `groups` claim or a custom extension; AD FS uses whatever the source-side claim emitter is configured to send.
* **User Attribute**: Enter `flowxIdPGroups`.

> [!NOTE]
>
> **Same recipe for business filters.** If the organization uses business filters, configure a second Attribute Importer mapper that reads the source IDP's business-filter claim and writes it into the `businessFilter` user attribute. The [User attribute mapper](#user-attribute-mapper) section above then exposes it on the token as `attributes.businessFilters`.

> [!WARNING]
>
> **Source-side claim shaping.** Most external IDPs do not emit a single multivalued claim that maps 1:1 to FlowX end-user group names. You typically need a chained mapper on the source IDP side, or on the federated IDP entry, to construct the multivalued array before this mapper imports it. See [Source IDP claim emission](#source-idp-claim-emission) below for the customer-side recipe.

### Source IDP claim emission

The Attribute Importer mapper above reads a single claim from the source IDP's token and writes it into `flowxIdPGroups`. The customer's IDP is responsible for producing that claim. The contract is:

* **Claim name:** customer-choice. The Attribute Importer's **Claim** field absorbs the difference — pick whatever the source IDP already emits (`groups`, `memberOf`, `roles`, a vendor-specific path).
* **Claim type:** multivalued string. Each value is a group identifier that must match an [end-user group](./runtime-authorization#end-user-groups) name in FlowX.
* **Token destinations:** the source IDP must add the claim to the **access token** (Keycloak's broker reads it from there). Adding it to the ID token and userinfo as well is harmless and recommended.

If the customer maintains group data across multiple user attributes — for example, some users have a `groups` array and others have a single-value `role` attribute — they can configure two protocol mappers on the source IDP, both targeting the **same** outgoing claim name with **Aggregate attribute values** toggled ON. Keycloak unions the values into one array before emitting the claim. The same trick works for business filters.

> [!TIP]
>
> **Verify the claim before configuring the importer.** Decode a sample access token issued by the source IDP (the **Evaluate** tab on the source-side client is the quickest way) and confirm the group claim is present with the expected name and values. Trailing whitespace, accidental nesting, or single-value strings (instead of arrays) are the most common reasons the FlowX-side Attribute Importer appears to do nothing.

### User realm role mapper

To add a roles mapper to the `{your-client-name}-authenticate` client, so roles will be available in the OAuth user info response, follow these steps:

**1. Navigate to Client Scopes**

From the Keycloak admin console, go to **Clients** and select your desired client.

Click on **Client Scopes** and choose `{your-client-name}-authenticate-dedicated` to open its settings.

Ensure the **Mappers** tab is selected.

**2. Add a New Mapper**

Click **Add Mapper**. From the list of available mappers, select **User Realm Role**.

![User Realm Role mapper in predefined list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_predefined_mapper_realm_roles.png)

**3. Provide mapper details**

* **Name**: Enter a descriptive name for the mapper, such as "Roles Mapper".
* **Mapper Type**: Select **User Realm Role**.
* **Token Claim Name**: Enter `roles`.
* **Add to ID Token**: Toggle OFF.
* **Add to access token**: Toggle OFF.
* **Add to token introspection**: Toggle ON.

![User Realm Role mapper configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_user_realm_role_mapper.png)

This roles mapper includes the user's assigned realm roles in the OAuth user info response under the claim name "roles".

> [!NOTE]
>
> You can repeat these steps to add multiple roles mappers if you need to include multiple realm roles in the token claim.

> [!NOTE]
>
> **Legacy realm roles.** Realms created from older FlowX realm exports may contain role families such as `ROLE_ADMIN_MANAGE_*`, `ROLE_TASK_MANAGER_*`, or `ROLE_CMS_*`, sometimes already assigned to users. FlowX services assign no built-in meaning to these roles — Designer and platform access is governed by workspace and organization roles plus permissions (see the [roles & permissions matrix](./roles-permissions-matrix)). Realm roles are only evaluated where your own configuration references them, such as swimlane access rules or business filters. Realms provisioned by current FlowX versions no longer include these legacy roles.

### Creating a basic client scope

To ensure consistent token configuration across all clients, you should create a default client scope named "basic" with predefined mappers.

**1. Navigate to Client Scopes**

From the Keycloak admin console, go to **Client Scopes** in the left menu.

Click **Create client scope**.

**2. Configure client scope settings**

* **Name**: Enter `basic`.
* **Type**: Select **Default**.
* **Protocol**: Select **OpenID Connect**.
* **Display on consent screen**: Toggle OFF.
* **Include in token scope**: Toggle ON.

Click **Save**.

**3. Add predefined mappers**

In the newly created **basic** client scope, navigate to the **Mappers** tab.

Add the following predefined mappers:

1. **sub** mapper:
   * Click **Add mapper** → **From predefined mappers**
   * Select **sub**
   * Click **Add**

2. **auth\_time** mapper:
   * Click **Add mapper** → **From predefined mappers**
   * Select **auth\_time**
   * Click **Add**

**4. Assign to All Clients**

After creating the basic client scope, assign it to all your clients:

1. Navigate to **Clients** in the left menu
2. For each client (e.g., `flowx-platform-authenticate` and all service accounts):
   * Open the client settings
   * Go to the **Client Scopes** tab
   * Click **Add client scope**
   * Select **basic** from the list
   * Choose **Default** as the assignment type
   * Click **Add**

> [!NOTE]
>
> The **basic** client scope ensures that all clients have consistent token claims for subject identification (sub) and authentication time (auth\_time), which are essential for proper token validation and session management.

***

### Examples

#### Login

To request a login token:

```bash theme={"dark"}
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=admin@flowx.ai' \
--data-urlencode 'password=password' \
--data-urlencode 'client_id={your-client-name}-authenticate'
```

#### Refresh token

To refresh an existing token:

```bash theme={"dark"}
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id={your-client-name}-authenticate' \
--data-urlencode 'refresh_token=ACCESS_TOKEN'
```

#### User info

To retrieve user information:

```bash theme={"dark"}
curl --location --request GET 'localhost:8080/realms/flowx/protocol/openid-connect/userinfo' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
```

***

## Adding service accounts

> [!NOTE]
>
> **What is a service account?**
>
> A service account grants direct access to the Keycloak API for a specific component. Each client can have a built-in service account that allows it to obtain an access token.
>
> To use this feature you must turn on **Client authentication** (access type) for your client. When you do this, the **Service Accounts Enabled** switch will appear.

### Realm architecture

FlowX uses three Keycloak realms that separate Keycloak administration, user authentication, and service-to-service communication:

| Realm | Name | Purpose | Which services touch it |
| - | - | - | - |
| **Master realm** | `master` (Keycloak built-in) | Keycloak's built-in administration realm. FlowX uses admin credentials here briefly during initial provisioning to create the realms below; the master realm itself is not used as a FlowX-managed realm at runtime. | `authorization-system` (and `data-sync` during the runtime-authorization migration) — **only when `SECURITY_KEYCLOAKADMINENABLED=true`**. No other service ever touches it. |
| **User realm** | The organization ID — the UUID provided by FlowX during organization registration (e.g., `00000001-0001-4001-8001-000000000001` for the default organization) | Main FlowX realm where end users live: users, roles, groups, and the `flowx-platform-authenticate` client. | Frontend apps and end-user authentication flows. Backend services also reach this realm to fetch the public JWKS keys used to validate inbound tokens issued by it. Almost every service is configured with its URL. |
| **Service accounts realm** | `00000002-0002-4002-8002-000000000002` (fixed) | Holds the backend service-account clients (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Managed and isolated from the user realm. | **Every backend service** — they obtain access tokens here via `security.oauth2.sa-realm`. |

This separation improves security isolation — service accounts cannot access user tokens, user realm changes do not affect service-to-service authentication, and the master realm stays restricted to administrative use.

**Where to create each client:**

* **User-facing clients** (`flowx-platform-authenticate`) go in the **user realm**
* **All service account clients** (`flowx-*-sa`) go in the **service accounts realm**
* **No FlowX clients** are created in the master realm — it only holds Keycloak's built-in `admin-cli`

> [!NOTE]
>
> Both realms are created automatically by the guided setup flow on fresh installations, and by Liquibase migrations on upgrades — the existing user realm is renamed to the organization ID and the service accounts are moved out into the new SA realm. For the full upgrade flow, see the [Authentication & IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam).
>
> If your deployment does not grant Keycloak admin credentials to FlowX services, you must create the service accounts realm and move the service account clients manually. See [Manual Keycloak configuration](#manual-keycloak-configuration) below.

**Authorization system master realm configuration**

By default, the authorization-system service accesses the Keycloak master realm to manage realms and run migrations. This is controlled by `SECURITY_KEYCLOAKADMINENABLED` (default `true`). Configure the following properties on the authorization-system service only:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_KEYCLOAKADMINENABLED` | Whether FlowX has Keycloak admin access and manages realms. Set to `false` to skip FlowX-managed realm administration; the `SECURITY_MASTERREALM_*` variables are then not required. | `true` |
| `SECURITY_MASTERREALM_ADMIN_CLIENTID` | Master realm admin client ID | `admin-cli` |
| `SECURITY_MASTERREALM_NAME` | Master realm name | `master` |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username | - |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password | - |

The admin user supplied here must hold the **Admin** role on the master realm with permission to create realms — at first boot, the authorization-system service creates the user realm and the service-accounts realm, along with the clients, users, and service accounts within them.

> [!WARNING]
>
> These credentials grant full Keycloak administrative access. Store them securely using your secrets management solution (e.g., Vault, Kubernetes secrets). Never commit them to version control.

***

### Admin service account

The admin service account is used by the admin microservice to connect with Keycloak, enabling user and group management features within the FlowX.AI Designer.

Steps to add an Admin service account:

**1. Create the Client**

Navigate to **Clients** and select **Create client**.

Enter a **Client ID** for your new client.

![Admin service account client ID setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_admin_sa_settings.png)

**2. Configure capability config**

* Enable **Client authentication** (access type).
* Disable **Standard flow**.
* Disable **Direct access grants**.
* Enable **Service accounts roles**.

![Service account capability config with Client authentication and Service accounts roles enabled](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_admin_sa_capability_config.png)

**3. Configure additional settings**

After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

* **Backchannel Logout Session Required**: Toggle OFF.

* **Front Channel Logout**: Toggle OFF.

![Logout settings toggled OFF for service account](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_admin_sa_logout_settings.png)

**4. Configure service account roles**

In the newly created client, navigate to the **Service accounts roles** tab.

![Service accounts roles tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_admin_sa_service_account_roles.png)

> [!WARNING]
>
> **Important**: The admin service account no longer requires client roles from realm-management. If you have existing roles assigned, remove them to follow the updated security model.

The admin service account is now configured to work without specific client roles. Authentication and authorization will be managed through the service account token itself.

> [!NOTE]
>
> The admin service account does not require mappers or specific client roles. Authentication is handled through the service account token itself.

### Task Management service account

The task management service account facilitates process initiation and enables the use of the task management plugin (requiring the `FLOWX_ROLE` and role mapper).

> [!NOTE]
>
> Starting with 5.9.0, the Task Management plugin no longer reads user data from Keycloak; task operations resolve users through FlowX runtime authorization. The service account no longer needs any realm-management client roles.

Steps to Add a Task Management service account:

**1. Create the Service Account**

Follow steps **1**-**3** as in the Admin Service account configuration: [Admin service account](#admin-service-account).

**2. Add a realm roles mapper**

In the newly created task management plugin service account, select **Client Scopes**:

Click on `{your-client-name}-service-account` to open its settings.

> [!NOTE]
>
> Ensure the Mappers tab is selected within the dedicated client scope.

Click **Add mapper**. From the list of available mappers, select **User Realm Role**.

![Adding User Realm Role mapper to task management SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_predefined_mapper_realm_roles.png)

**3. Configure the mapper**

**Name**: Enter a descriptive name for the mapper to easily identify its purpose, for example `realm-roles`.

**Token Claim Name**: Set it to `roles`.

Disable **Add to ID token**.

![Realm roles mapper configuration for task management SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_taskmgmt_sa_realm_roles_mapper.png)

Click **Save**.

![Saved realm roles mapper](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_taskmgmt_sa_mappers_list.png)

**4. Add the service account realm role**

Assign the `FLOWX_ROLE` service account realm role (used to grant permissions for starting processes).

> [!NOTE]
>
> The `FLOWX_ROLE` realm role is used to grant permissions for starting processes in the FlowX.AI Designer platform.

### Process engine service account

The process engine requires a service account for service-to-service authentication and authorization.

> [!NOTE]
>
> This service account is also needed to be able to use [**Start Catch Event**](../../docs/building-blocks/node/message-events/message-catch-start-event) node.

**1. Create the Client**

Follow steps **1-3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

**2. Configure service account roles**

In the newly created client, navigate to the **Service accounts roles** tab.

The process engine service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.

**3. Add a realm roles mapper**

In the newly created process engine service account, select **Client Scopes**.

Click on `{your-client-name}-service-account` to open its settings.

Ensure the **Mappers** tab is selected within the dedicated client scope.

Click **Add mapper**. From the list of available mappers, select **User Realm Role**.

Configure the mapper:

* **Name**: Enter `realm-roles`
* **Token Claim Name**: Set it to `roles`
* **Add to ID token**: Toggle OFF
* **Add to token introspection**: Toggle ON

![Adding realm roles mapper to process engine SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/realm_roles_engine.gif)

### Scheduler service account

> [!NOTE]
>
> This service account is used for [**Start Timer Event**](../../docs/building-blocks/node/timer-events/timer-start-event) node. The registered timers in the scheduler require sending a process start message to Kafka. Authentication is also necessary for this operation.

The configuration is similar to the **process engine service account**:

**1. Create the Client**

Follow steps **1-3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

**2. Configure service account roles**

In the newly created client, navigate to the **Service accounts roles** tab.

The scheduler service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.

**3. Add a realm roles mapper**

Add a **realm-roles** mapper (as shown in the example for process-engine service account):

In the scheduler service account, select **Client Scopes**.

Click on `{your-client-name}-service-account` to open its settings.

Ensure the **Mappers** tab is selected within the dedicated client scope.

Click **Add mapper**. From the list of available mappers, select **User Realm Role**.

Configure the mapper:

* **Name**: Enter `realm-roles`
* **Token Claim Name**: Set it to `roles`
* **Add to ID token**: Toggle OFF
* **Add to token introspection**: Toggle ON

![Realm roles mapper for scheduler SA](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_taskmgmt_sa_realm_roles_mapper.png)

### Integration Designer service account

The Integration Designer service account is used by the integration designer microservice to interact securely with Keycloak, enabling it to manage various integrations within the FlowX.AI platform.

Steps to set up an Integration Designer service account:

**1. Create the Client**

* In Keycloak, navigate to **Clients** and select **Create client**.
* Enter a **Client ID** for your new client (e.g., `flowx-integration-designer-sa`).

![Integration Designer SA client ID setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_integration_designer_sa_settings.png)

**2. Configure client capabilities**

* Enable **Client authentication** under access type.
* Enable **Service accounts roles** to allow the account to manage integrations.

![Integration Designer SA capability config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_integration_designer_sa_capability_config.png)

**3. Save the Client Configuration**

* Skip the **Login settings** page.
* Click **Save** to apply the configuration.

**4. Assign service account client roles**

In the newly created client, navigate to the **Service accounts roles** tab.

Click **Assign role** and in the Filter field, select **Filter by clients**.

Assign only the **view-users** role from realm-management:

> [!NOTE]
>
> Remove any other roles if they are assigned. The integration designer service account should only have the **view-users** client role.

### Authorization System service account

The Authorization System service account is used for managing user authentication and authorization operations, including user management, realm configuration, and access control within the FlowX.AI platform.

Steps to set up an Authorization System service account:

**1. Create the Client**

Navigate to **Clients** and select **Create client**.

Enter a **Client ID** for your new client (e.g., `flowx-authorization-system-sa`).

**2. Configure capability config**

* Enable **Client authentication** (access type).
* Disable **Standard flow**.
* Disable **Direct access grants**.
* Enable **Service accounts roles**.

**3. Configure additional settings**

After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

* **Backchannel Logout Session Required**: Toggle OFF.
* **Front Channel Logout**: Toggle OFF.

**4. Assign service account client roles**

In the newly created client, navigate to the **Service accounts roles** tab.

Click **Assign role** and in the Filter field, select **Filter by clients**.

Assign the following service account client roles from realm-management:

* **view-users**
* **query-users**
* **manage-users**
* **manage-realm**

> [!NOTE]
>
> These roles are essential for the Authorization System service account to perform user and realm management operations within Keycloak.

### Runtime manager service account

The runtime manager service account is used by both Application Manager and Runtime Manager services to connect with Keycloak and perform export/import operations for builds, application versions, or other resource-specific tasks.

Steps to add a Runtime manager service account:

**1. Create the Client**

Navigate to **Clients** and select **Create client**.

Enter a **Client ID** for your new client.

![Runtime manager SA client ID setup](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_runtime_manager_sa_settings.png)

**2. Configure capability config**

* Enable **Client authentication** (access type).
* Disable **Standard flow**.
* Disable **Direct access grants**.
* Enable **Service accounts roles**.

![Runtime manager SA capability config](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_runtime_manager_sa_capability_config.png)

**3. Configure additional settings**

After creating the client, scroll down in the **Settings** tab and configure additional settings - **Logout Settings**:

* **Backchannel Logout Session Required**: Toggle OFF.

* **Front Channel Logout**: Toggle OFF.

![Logout settings toggled OFF for service account](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_admin_sa_logout_settings.png)

**4. Configure service account roles**

In the newly created client, navigate to the **Service accounts roles** tab.

![Service accounts roles tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_admin_sa_service_account_roles.png)

> [!WARNING]
>
> **Important**: The runtime manager service account no longer requires specific realm roles. If you have existing roles assigned (such as ROLE\_TASK\_MANAGER\_HOOKS\_ADMIN, ROLE\_ADMIN\_MANAGE\_PROCESS\_ADMIN, etc.), remove them to follow the updated security model.

The runtime manager service account is now configured to work without specific realm roles. Authentication and authorization for export/import operations will be managed through the service account token itself.

### Organization manager service account

The organization manager service account is used by the organization manager microservice to handle organization and workspace management within the FlowX.AI platform.

**1. Create the Client**

Follow steps **1**-**3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

Enter a **Client ID** of `flowx-organization-manager-sa`.

**2. Configure service account roles**

In the newly created client, navigate to the **Service accounts roles** tab.

The organization manager service account does not require specific client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.

### Email gateway service account

The email gateway service account is used by the email gateway microservice to manage email sending and receiving operations within the FlowX.AI platform.

**1. Create the Client**

Follow steps **1**-**3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

Enter a **Client ID** of `flowx-email-gateway-sa`.

> [!NOTE]
>
> The email gateway service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.

### License service account

The license service account is used by the license microservice to manage license validation and enforcement within the FlowX.AI platform.

**1. Create the Client**

Follow steps **1**-**3** as in the Admin Service Account Configuration: [Admin service account](#admin-service-account).

Enter a **Client ID** of `flowx-license-sa`.

> [!NOTE]
>
> The license service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the `SA_FLOWX` realm role.

***

## Configuring SA\_FLOWX realm role

The `SA_FLOWX` role is a realm-level role that should be assigned to all service accounts to ensure proper authentication and authorization across the FlowX.AI platform.

> [!NOTE]
>
> Create the `SA_FLOWX` role in the **service accounts realm** (`00000002-0002-4002-8002-000000000002`), since that is where all service account clients reside.

**1. Create the SA\_FLOWX Realm Role**

1. In the Keycloak admin console, navigate to the service accounts realm (`00000002-0002-4002-8002-000000000002`).
2. Go to **Realm roles** in the left menu.
3. Click **Create role**.
4. Enter `SA_FLOWX` as the **Role name**.
5. Add a description: "Service account role for FlowX.AI platform services".
6. Click **Save**.

**2. Assign SA\_FLOWX to service accounts**

For each service account listed below, assign the `SA_FLOWX` realm role:

* **flowx-process-engine-sa**
* **flowx-admin-sa**
* **flowx-runtime-manager-sa**
* **flowx-integration-designer-sa**
* **flowx-scheduler-core-sa**
* **flowx-authorization-system-sa**
* **flowx-task-management-plugin-sa**
* **flowx-organization-manager-sa**
* **flowx-email-gateway-sa**
* **flowx-license-sa**
* **flowx-webhook-gateway-sa**
* **flowx-file-gateway-sa**
* **flowx-ai-gateway-sa**
* **flowx-events-gateway-sa** (5.9.4 and later)

To assign the role to each service account:

1. Navigate to **Clients** and select the service account client.
2. Go to the **Service accounts roles** tab.
3. Click **Assign role**.
4. In the Filter field, select **Filter by realm roles**.
5. Find and select **SA\_FLOWX** from the list.
6. Click **Assign**.

![Assigning SA\_FLOWX realm role to a service account](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release40/flowx_role.gif)

**3. Verify role assignment**

After assigning the role to all service accounts, verify that each service account has the `SA_FLOWX` role listed in its **Service accounts roles** tab.

> [!NOTE]
>
> The `SA_FLOWX` role ensures consistent authentication and authorization behavior across all FlowX.AI platform services. Make sure all service accounts have this role assigned for proper system operation.

***

## Email (SMTP) configuration

> [!NOTE]
>
> **Required for self-hosted deployments**
>
> On self-hosted deployments, SMTP must be configured by the client directly in Keycloak. This is required for password reset flows and user invitation emails sent from FlowX Designer.

To configure email delivery:

**1. Navigate to email settings**

In Keycloak, go to your organization realm, then **Realm settings** → **Email**.

**2. Configure SMTP connection details**

Fill in your SMTP server details:

| Field | Description |
| - | - |
| **Host** | SMTP server hostname (e.g., `smtp.example.com`) |
| **Port** | SMTP port (typically `587` for TLS or `465` for SSL) |
| **From** | Sender email address (e.g., `noreply@example.com`) |
| **Enable SSL** / **Enable StartTLS** | Toggle **ON** based on your mail server requirements |
| **Authentication** | Toggle **ON** if your SMTP server requires credentials |
| **Username** / **Password** | SMTP authentication credentials |

**3. Test the connection**

Use the **Test connection** button in Keycloak to verify emails can be sent.

> [!WARNING]
>
> Without SMTP configured, the following features will not work:
>
> * **Password reset** — users cannot reset their passwords via email
> * **User invitations** — inviting new users from FlowX Designer will fail

***

## Manual Keycloak configuration

If FlowX services do not have Keycloak admin access, perform the following steps manually in the Keycloak Admin Console:

> [!WARNING]
>
> The user realm's **Realm name** must be identical to your organization ID — the UUID provided by FlowX during organization registration (the same value set as `ORGANIZATION_ID` on the backend services). Only the **Display name** is free-form (e.g., the organization code). See [Creating a new realm](#creating-a-new-realm).

**1. Create the service accounts realm**

1. Log in to the Keycloak Admin Console.
2. Click **Create realm**.
3. Set the **Realm name** to `00000002-0002-4002-8002-000000000002`.
4. Set the **Display name** to `Flowx Administration Realm`.
5. Click **Create**.

Configure the realm settings:

* **Login** tab: Enable **Email as username** and **Login with email**
* **Authentication** → **Policies** → **Password Policy**: Add uppercase, digit, special character, and minimum length (8) rules

**2. Move service account clients to the SA realm**

For each service account client listed in [Adding service accounts](#adding-service-accounts), create the client in the **service accounts realm** (not the user realm):

![Service accounts realm clients list with flowx-\*-sa clients](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/kc_sa_realm_clients_list.png)

1. In the SA realm, go to **Clients** → **Create client**.
2. Enter the **Client ID** (e.g., `flowx-admin-sa`).
3. Enable **Client authentication** and **Service accounts roles**. Disable **Standard flow** and **Direct access grants**.
4. Configure **Logout Settings**: Toggle **OFF** both Backchannel Logout and Front Channel Logout.
5. Assign the `SA_FLOWX` realm role (create it first in the SA realm if it does not exist).

**3. Create the anonymous service account**

The `flowx-anonymous-sa` client is used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows (see the full list of consuming services in the [v5.9 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#anonymous-service-account-shared-client-secret)). It is intentionally scoped to a separate, lower-privilege realm role so a leaked token cannot exercise authenticated paths.

1. In the SA realm, create a new realm role named **`SA_FLOWX_ANONYMOUS`**. Do **not** reuse `SA_FLOWX`.
2. Go to **Clients** → **Create client**.
3. Enter the **Client ID** `flowx-anonymous-sa`.
4. Enable **Client authentication** and **Service accounts roles**. Disable **Standard flow** and **Direct access grants**.
5. Configure **Logout Settings**: Toggle **OFF** both Backchannel Logout and Front Channel Logout.
6. Assign **only** the `SA_FLOWX_ANONYMOUS` realm role to this client's service account. Do not assign `SA_FLOWX`.

> [!WARNING]
>
> **Do not assign `SA_FLOWX` to `flowx-anonymous-sa`.** The whole point of this client is to keep the anonymous-flow blast radius narrow — if the token leaks, the attacker can only invoke paths reachable to an anonymous internet visitor on processes or UI flows that explicitly opted into the `Anonymous` runtime role. Granting `SA_FLOWX` removes that boundary.

> [!NOTE]
>
> After creating the client, take the generated client secret and configure it on every consuming service via `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET`. The same secret must be set on all of them. See [Anonymous service account: shared client secret](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#anonymous-service-account-shared-client-secret) in the v5.9 deployment guidelines for the full list of services and the matching Liquibase parameter.

**4. Configure the org\_id protocol mapper**

In the **user realm**, ensure the `flowx-platform-authenticate` client has a protocol mapper that adds the `org_id` claim to access tokens:

1. Go to **Clients** → `flowx-platform-authenticate` → **Client scopes** → dedicated scope.
2. **Add mapper** → **By configuration** → **Hardcoded claim**.
3. Set **Name** to `org_id`, **Token Claim Name** to `org_id`, **Claim value** to the organization ID provided by FlowX (which is also the user realm name), and **Claim JSON Type** to `String`.
4. Enable **Add to access token** and **Add to token introspection**.

**5. Remove service accounts from user realm**

After creating the service account clients in the SA realm, delete the old service account clients from the user realm. Keep only user-facing clients (`flowx-platform-authenticate`) in the user realm.

> [!WARNING]
>
> If you skip manual configuration, service-to-service authentication will fail. All FlowX backend services expect service accounts to exist in the realm identified by `security.oauth2.sa-realm` (`00000002-0002-4002-8002-000000000002`).

***

## Changing the Keycloak base URL after install

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.5**
>
> On self-hosted deployments running 5.9.5 or later, the token issuer is derived from configuration, so moving Keycloak to a new domain is a configuration change and never a database edit. Earlier versions behave differently — see the warning at the end of this section.

FlowX resolves the organization from the token issuer URI, which is always the auth server URL plus the organization ID:

```
<public-keycloak-url>/realms/<organization-id>
```

Two settings carry that auth server URL, and they can point at different hosts:

| Environment Variable | Description | Component |
| - | - | - |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | Keycloak URL used for service-to-service calls, typically the in-cluster address. | All backend services |
| `SECURITY_OAUTH2_PUBLIC_SERVER_URL` | Browser-facing Keycloak URL. Falls back to `SECURITY_OAUTH2_BASE_SERVER_URL` when unset. | organization-manager, authorization-system |

The public URL is the one that ends up in the issuer, so it decides whether Designer login still works after the move.

**1. Point Keycloak at the new hostname**

Update Keycloak's own hostname configuration so it issues tokens under the new URL. See the [Keycloak hostname documentation](https://www.keycloak.org/server/hostname) for the settings your Keycloak version expects.

**2. Update the FlowX configuration**

Set the new URL on the FlowX services:

* `SECURITY_OAUTH2_BASE_SERVER_URL` on every backend service.
* `SECURITY_OAUTH2_PUBLIC_SERVER_URL` on **organization-manager** and **authorization-system**.

When deploying with the FlowX Helm chart, these come from the chart values `flowx.keycloak.baseServerUrl` (in-cluster) and `flowx.keycloak.serverUrl` (public), so changing the two values covers every service.

**3. Restart the services whose configuration changed**

The issuer is read at startup, so each service picks up the new URL on restart.

**4. Sign in again and validate**

Everyone signs in again: tokens issued under the old URL carry the old issuer, which no longer matches the configured one and is rejected. Confirm that login to FlowX Designer succeeds and that the address in the browser's authentication redirect is the new Keycloak host.

> [!NOTE]
>
> The Designer needs no separate change. It reads the issuer and token endpoint from organization-manager, which derives both from the configuration above.

> [!WARNING]
>
> **On 5.9.0 through 5.9.4, and on the 5.1.x line, this procedure is not sufficient.** Those versions serve the issuer from the organization record written at install, so the stored value still points at the old Keycloak URL after you change the configuration, and Designer login fails. Contact FlowX support before moving Keycloak to a new domain on those versions.

> [!NOTE]
>
> SaaS deployments are unaffected. FlowX manages the authentication domain, and the organization's issuer is maintained with it.

***

## Troubleshooting

> [accordion] Bad request error when creating users in FlowX Designer
>
> **Keycloak 26+ only**: You must configure email settings in the **Login** tab of realm settings. Toggle **ON** both **Email as username** and **Login with email**. Without this configuration, user creation requests from FlowX Designer fail with a bad request error.

> [accordion] Realm name conflict
>
> Ensure the realm name is unique within your Keycloak instance. Duplicate realm names cause creation failures.

> [accordion] Service account authentication fails
>
> Verify the following:
>
> * The service account client has **Client authentication** enabled and **Service accounts roles** toggled **ON**.
> * The `SA_FLOWX` realm role is assigned to the service account.
> * The client secret in your deployment matches the secret in Keycloak (**Clients** → select client → **Credentials** tab).
> * `security.oauth2.sa-realm` is set to `00000002-0002-4002-8002-000000000002` and the service account client exists in the SA realm (not the user realm).

> [accordion] Token missing groups, roles, or business filters
>
> Check that the required protocol mappers are configured on the correct client scope:
>
> * **Group Membership** mapper with **Add to token introspection** toggled **ON**.
> * **User Realm Role** mapper with **Add to token introspection** toggled **ON**.
> * **User Attribute** mapper for business filters with **Multivalued** and **Aggregate attribute values** toggled **ON**.
> * The `org_id` protocol mapper is configured on the `flowx-platform-authenticate` client in the user realm.

> [accordion] JWT validation fails
>
> * Verify `security.type` is set to `jwt-public-key`.
> * Ensure `security.oauth2.sa-realm` is set to `00000002-0002-4002-8002-000000000002`.
> * Verify that `flowx.lib.security.services.organization-manager.base-url` is set and the organization-manager service is reachable.

***

## Summary

By following these steps, you have a minimal Keycloak setup to manage users, roles, and apps efficiently.

Your Keycloak setup should include:

* A **user realm** (named with the organization ID provided by FlowX) containing the `flowx-platform-authenticate` client, protocol mappers, users, roles, and groups
* A **service accounts realm** (`00000002-0002-4002-8002-000000000002`) containing all `flowx-*-sa` service account clients with the `SA_FLOWX` realm role
* **SMTP configured** in the user realm for password reset and user invitations (required for self-hosted deployments)
* **JWT public key validation** (`security.type: jwt-public-key`) on all services
* **Master realm credentials** configured on the authorization-system service

For more detailed configurations and advanced features, refer to the official Keycloak documentation.

***

## Related resources

> [card] [Access Management overview](./access-management-overview)
>
> User roles, groups, and access control

> [card] [Business filters](../../docs/platform-deep-dive/user-roles-management/business-filters)
>
> Data-level access control using business filters

> [card] [Keycloak documentation](https://www.keycloak.org/documentation)
>
> Official Keycloak documentation


# Configuring an IAM solution (EntraID)
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/configuring-an-iam-solution-entra

This guide provides step-by-step instructions for configuring a minimal EntraId setup to manage users, roles, and applications efficiently.

## Overview

Microsoft Entra is Microsoft’s unified identity and access management solution designed to protect access to applications, resources, and user data across an organization’s environment. It provides an identity and access management (IAM) framework, allowing secure access control, role management, and integration of various applications under a single directory. Entra is crucial for managing multi-cloud and hybrid environments securely, enforcing policies, and supporting both self-hosted and cloud resources.

## Prerequisites

* Application Administrator role
* Basic understanding of IAM and OIDC concepts

## Recommended EntraID setup

This setup configures Microsoft Entra to manage and secure access for FlowX.AI applications, handling user roles, custom attributes, and application-specific permissions. The setup covers these main components:

> [accordion] 1. Application Registrations
>
> * Flowx-Web and Flowx-API are the core applications that act as entry points for the FlowX.AI platform. Additional applications like Flowx-Admin, Task Management Plugin, and Scheduler Core are registered to support specific functionalities.
> * Each application registration includes settings for authentication, API permissions, and role assignments.

> [accordion] 2. Authentication and Authorization
>
> * Configures OAuth 2.0 and OIDC protocols, enabling secure access to resources.
> * Roles and permissions are assigned through Entra, and single sign-on (SSO) is set up for ease of access across applications.

> [accordion] 3. Token and API Permissions
>
> * Token Configuration includes defining claims (e.g., `email`, `groups`) for use in JWTs, which are used for secure identity validation across services.
> * API Permissions are managed using Microsoft Graph, which governs access to resources like user profiles and groups within FlowX.AI.

> [accordion] 4. Custom Attributes
>
> Custom attribute extensions (e.g., `businessFilter`) allow organizations to apply additional filters or metadata to user and group profiles, configured and managed using Microsoft Graph CLI.

> [accordion] 5. Helm Chart Configuration
>
> * Helm charts provide a structured setup for deploying FlowX.AI applications in containerized environments.
> * Key values such as `tenant_id`, `client_id`, and `client_secret` are configured to support authentication and secure access.

> [accordion] 6. Example JWT Tokens
>
> JWT tokens are configured to carry user claims, roles, and custom attributes, ensuring that each token provides comprehensive identity details for FlowX.AI applications.

### Flowx-web app registration

The Flowx-web application serves as the main entry point for logging into FloWX Designer or container applications.

#### Appplication registration steps

To register the Flowx-web application, follow these steps:

1. Navigate to [https://portal.azure.com](https://portal.azure.com) and log in to your EntraID directory, which will host your FlowX.AI application registrations.
2. Go to **Microsoft EntraID > App registrations > New registration**

![Entra ID App registrations page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%283%29.png)

3. Enter a name for your application, then select **Accounts in this organizational directory only (Single tenant)** to limit access to your organization’s directory.

![Flowx-web app registration form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2010.56.35.png)

4. Click **Register** to complete the setup.

> [!NOTE]
>
> You will be redirected to the overview of the newly created app registration.

#### Authentication steps

Follow these steps to configure authentication for the Flowx-web application:

1. Go to the **Authentication** tab. Under **Platform configurations**, add a new platform by selecting **Single-page application (SPA)**. Then, set the **Redirect URIs** to point to the URIs of your Designer application.

![Adding SPA platform configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/2024-11-04%2010.54.45.gif)

![SPA redirect URI configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2010.58.31.png)

2. Click **Configure** to save the platform settings.
3. Next, click **Add URI** to include an additional redirect URI, this time pointing to your container application's URI.

![Adding additional redirect URI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2017.14.29.png)

![Container app redirect URI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.31.19.png)

4. Click **Save** to confirm the redirect URI changes.
5. Scroll down to **Advanced Settings**. Under **Mobile and Desktop Applications**, toggle **Enable the following mobile and desktop flows** to **Yes**.

![Mobile and desktop flow toggle setting](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2017.16.55.png)

6. Click **Save** again to apply all changes.

#### API permissions

To configure the necessary API permissions, follow these steps:

1. Navigate the **API permissions** tab and click **Add a permission**.

![API permissions tab with Add a permission button](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.33.31.png)

2. In the permissions menu, select **Microsoft Graph** and then choose **Delegated permissions**.

![Selecting Microsoft Graph permissions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.35.56.png)

![Delegated permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.36.46.png)

3. Add the following permissions by selecting each option under **OpenId permissions**:

* email
* offline\_access
* openid
* profile

![OpenID permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.38.35.png)

4. After adding these permissions, click **Add permissions** to confirm.

#### Token configuration

Configure the claims you want to include in the ID token.

1. Navigate to the **Token configuration** tab. Click **Add optional claim**, then select **Token type > Access**.

* Choose the following claims to include in the token:
  * email
  * family\_name
  * given\_name
  * preferred

![Adding optional token claims](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.40.21.png)

2. Click **Add** to save these optional claims.

![Optional claims confirmation dialog](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.41.33.png)

3. Next, add group claims to the token by clicking **Add groups claim**.
4. Select **All groups** and, under each token type, select **sAMAccountName** (this may differ for your specific organization).

![Group claims configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%285%29.png)

#### Setting token expiration policies

For organizations that require specific control over token lifetimes, Microsoft Entra allows customization of token expiration policies.

1. **Create a Custom Token Lifetime Policy**: Define the desired expiration settings for access, ID, and refresh tokens in the policy.
2. **Assign the Policy to a Service Principal**: Apply the policy to your Flowx-web or Flowx-API app registrations to enforce token lifetime requirements.

> [!TIP]
>
> For more details on creating and assigning policies for token expiration, refer to [**Microsoft's guide on configuring token lifetimes**](https://learn.microsoft.com/en-us/entra/identity-platform/configure-token-lifetimes#create-a-policy-and-assign-it-to-a-service-principal).

> [!NOTE]
>
> Adjusting token lifetimes can enhance security by reducing the window for unauthorized access.

***

### Flowx-API app registration

The Flowx-API application is used to configure the access token necessary for secure communication between the browser and all exposed FlowX APIs.

#### Appplication registration steps

To register the Flowx-API application, follow these steps:

1. Navigate to [https://portal.azure.com](https://portal.azure.com) and log in to your EntraID directory, which will host your FlowX.AI application registrations.
2. Go to **Microsoft EntraID > App registrations > New registration**

![Entra ID App registrations page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%283%29.png)

3. Enter a name for your application, then select **Accounts in this organizational directory only (Single tenant)** to limit access to your organization’s directory.

![Flowx-API app registration form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2012.04.27.png)

4. Click **Register** to complete the setup.

> [!NOTE]
>
> You will be redirected to the overview page of the newly created app registration.

#### API permissions

To configure the necessary API permissions, follow these steps:

1. Go to the **API permissions** tab and click **Add a permission**.

![Flowx-API API permissions tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/ent1.png)

2. In the permissions menu, select **Microsoft Graph** and then choose **Delegated permissions**.

![Selecting Microsoft Graph permissions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.35.56.png)

![Delegated permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.36.46.png)

3. Add the following permissions by selecting each option under **OpenId permissions**:

* email
* offline\_access
* openid
* profile

![OpenID permissions selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2011.38.35.png)

4. After adding these permissions, click **Add permissions** to confirm.

#### Token configuration

Configure the claims you want to include in the ID token.

1. Navigate to the **Token configuration** tab. Click **Add optional claim**, then select **Token type > Access**.

* Choose the following claims to include in the token:
  * email
  * family\_name
  * given\_name
  * preferred

![Flowx-API optional token claims selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2015.36.40.png)

2. Click **Add** to save these optional claims.
3. Next, add group claims to the token by clicking **Add groups claim**.
4. Select **All groups** and, under each token type, select **sAMAccountName** (this may differ for your specific organization).

![Flowx-API group claims configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2016.14.01.png)

#### Expose an API

To configure the API exposure and define scopes:

1. In the **Expose an API** section, click **Add** under **Application ID URI**. It’s recommended to use the application’s name for consistency.

![Expose an API section with Application ID URI](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.11.53.png)

2. Click **Save**.
3. Under **Scopes defined by this API**, click **Add a scope** and configure it as follows:

* **Scope name**: `FlowxAI.ReadWrite.All`
* **Who can consent**: Admins and users
* **Admin consent display name**: Full API Access for FlowX.AI Platform
* **Admin consent description**: Grants this application full access to all available APIs, allowing it to read, write, and manage resources across the FlowX.AI platform.
* **User consent display name**: Same as admin consent display name
* **User consent description**: Same as admin consent description
* **State**: Enabled

![API scope configuration form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.16.52.png)

> [!NOTE]
>
> This scope is not used directly to grant permissions. Instead, it is included in login requests made from a web client. When a client makes a login request with this scope, Entra ID uses it to identify and provide the appropriate access token configured here, ensuring secure access.

4. Under **Authorized client applications**, click **Add a client application**. Add each of the following client applications, selecting the `FlowxAI.ReadWrite.All` scope:

* flowx-web
* flowx-admin
* flowx-process-engine
* flowx-integration-designer
* flowx-task-management-plugin
* flowx-scheduler-core

![Authorized client applications list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.38.41.png)

> [!NOTE]
>
> Client IDs for these applications can be found on the **Overview** page of each respective application. If some applications are not created yet, you can return and add them to this section after their creation.
>
> ![Application overview showing Client ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.36.39.png)

#### Application roles

To configure application roles, follow these steps:

1. Navigate to **App roles** and click **Create app role**.
2. Select **Allowed member types** select **Both (Users/Groups + Applications)**.

![Create app role form](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.43.05.png)

3. Complete the role details with the following information:

* Display name: The name displayed for the role.
* Value: A unique identifier for the role within applications.
* Description: A description of the role’s purpose.

> [!NOTE]
>
> App role list should be the same as the Keycloak setup. A list of default roles can be found in the [Keycloak IAM configuration guide](./configuring-an-iam-solution).

### Other applications registration

The following FlowX.AI applications require similar steps for registration:

* Flowx-Admin
* Flowx-Process-Engine
* Flowx-Integration-designer
* Flowx-Task-Management-Plugin
* Flowx-Scheduler-Core

***

### Flowx-Admin app registration

1. **Create a New Application Registration**
   * Go to [https://portal.azure.com](https://portal.azure.com) and log in to your Entra ID directory where you will host FlowX.AI application registrations.

2. **Register the Application**
   * Navigate to **Microsoft Entra ID > App registrations > New registration**.
   * Set the application name and select **Accounts in this organizational directory only (Single tenant)**.
   * Click **Register**. You will be redirected to the overview page of the newly created app registration.

> [!NOTE]
>
> You will now see the overview for your new app registration.

#### Configure client secrets

1. Navigate to **Certificates & secrets**.
2. Under **Client secrets**, click **New client secret**.
3. Set a **description** and choose an **expiration time** for the client secret, then click **Add**.

![New client secret configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.57.31.png)

> [!NOTE]
>
> Copy the generated client secret value. This will be used to configure `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`.
>
> ![Generated client secret value](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2018.59.12.png)

#### Configure API permissions

1. Go to the **API permissions** tab and click **Add a permission**.
2. Select **Microsoft Graph > Application permissions**.
3. Add the following permissions for **flowx-admin**:
   * **Application.Read.All**

![Application.Read.All permission selection](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.01.20.png)

> [!NOTE]
>
> If you have admin privileges, you can click **Grant admin consent** to apply these permissions. If not, contact your tenant administrator to grant consent.
>
> ![Grant admin consent confirmation](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.03.00.png)

***

### Flowx-Process-Engine app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

* **API Permissions**: No additional permissions required.

***

### Flowx-Integration-Designer app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

* **API Permissions**: No additional permissions required.

***

### Flowx-Task-Management-Plugin app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

1. Go to the **API permissions** tab and click **Add a permission**.
2. Select **Microsoft Graph > Application permissions**.
3. Add the following permissions for **flowx-task-management-plugin**:
   * **Application.Read.All**
   * **Group.Read.All**
   * **User.Read.All**

> [!NOTE]
>
> If you have admin privileges, you can click **Grant admin consent** to apply these permissions. If not, contact your tenant administrator to grant consent.

***

### Flowx-Scheduler-Core app registration

Follow the same **Application Registration Steps** and **Configure Client Secrets** steps as above.

#### Configure API permissions

* **API Permissions**: No additional permissions required.

***

### Assigning a role to a user/group

To assign a role to a user or group for your FlowX.AI applications, follow these steps:

1. Go to [https://portal.azure.com](https://portal.azure.com) and log in to your Entra ID directory that hosts your FlowX.AI application registrations.

2. Navigate to **Microsoft Entra ID > Enterprise applications** and search for your **flowx-api** app registration name.\
   (An enterprise application with the same name was automatically created when the app registration was set up.)

![Enterprise applications search](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.11.43.png)

![Flowx-API enterprise application overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.12.51.png)

3. Under **Users and groups**, select **Add user/group**.

![Users and groups assignment page](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.14.17.png)

* Choose the user or group you want to assign.

![Selecting user or group for role assignment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.16.53.png)

* Select the appropriate role from the available options.

4. Click **Assign** to complete the role assignment.

![Completed role assignment](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.19.39.png)

> [!NOTE]
>
> It is recommended to provide roles through group membership for easier management and scalability.

***

### Adding custom attributes

Using Microsoft Graph CLI, you can add custom attributes such as `businessFilter`.

> [!TIP]
>
> For more information about Microsoft Graph CLI, check the following docs:
>
> > [card] [Get started with Microsoft Graph CLI](https://github.com/microsoftgraph/msgraph-cli)

#### Prerequisites

* [Install the Microsoft Graph CLI](https://github.com/microsoftgraph/msgraph-cli).

#### Create an attribute extension property

Create an Attribute Extension Property on the flowx-api app registration:

1. Log in to Microsoft Graph CLI with the necessary permissions:

```bash theme={"dark"}
   $ mgc login --scopes Directory.Read.All
```

> [!TIP]
>
> You can add additional permissions by repeating the mgc login command with the new permission scopes.

2. Create the attribute extension property by running the following command. Replace `<application_object_id>` with the object ID of your flowx-api application:

```bash theme={"dark"}
$ mgc applications extension-properties create --application-id <application_object_id> --body '
{
  "dataType": "String",
  "name": "businessFilter",
  "targetObjects": [
    "User", "Group"
  ]
}'
```

#### Retrieve the attribute extension name

To confirm the attribute extension name, use the command below. This will output the exact name of the created extension property.

```bash theme={"dark"}
$ mgc applications extension-properties list --application-id <application_object_id> --select name
```

Example output:

```json theme={"dark"}
{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications(\u0027<application_object_id>\u0027)/extensionProperties(name)",
  "value": [
    {
      "name": "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter"
    }
  ]
}
```

#### Configure token claim

1. Go to the **flowx-api** app registration in the Azure portal.
2. Navigate to **Token configuration**.
3. Click **Add optional claim**.
   * Select **Token type** as **Access**.
   * Check the box for `extn.businessFilter`.
4. Click Add to save the changes.

![Adding businessFilter custom claim to token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/Screenshot%202024-11-04%20at%2019.31.05.png)

#### Assign attribute extension to a user

1. Log in with the required permissions to modify user attributes:

```bash theme={"dark"}
$ mgc login --scopes User.ReadWrite.All
```

2. Assign the `businessFilter` attribute to a user by running the command below. Replace `<user_object_id>` with the user's `object ID`:

```bash theme={"dark"}
$ mgc users patch --user-id <user_object_id> --body '
{
  "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter": "docs"
}'
```

#### Assign attribute extension to a group

Follow similar steps to assign the `businessFilter` attribute to a group. Replace `<group_object_id>` with the group’s `object ID` and use the following command:

1. Log in with the required permissions to modify group attributes:

```bash theme={"dark"}
$ mgc login --scopes User.ReadWrite.All
```

2. Assign the custom attribute by  the command below, replacing `<user_object_id>` with the user’s object ID. The businessFilter attribute is set to "docs" in this example.

```bash theme={"dark"}
$ mgc groups patch --group-id <group_object_id> --body '
{
  "extension_ec959542898b42bcb6922e7d3f9df282_businessFilter": "docs"
}'
```

***

## Example JWT token for user

To verify that the custom attributes and roles have been correctly applied, you can inspect a sample JWT token issued to a user. This token will include standard claims along with any custom attributes and roles configured in your Entra ID setup.

### Steps to retrieve a JWT token

1. **Login to the FlowX.AI Application**\
   Log in to the FlowX.AI application as the user for whom the JWT token needs to be inspected.

2. **Retrieve the JWT Token**\
   After logging in, retrieve the JWT token by one of the following methods:
   * Using browser developer tools to inspect network requests (look for requests with an `Authorization` header).
   * Accessing a token endpoint if available, using a tool like Postman.

3. **Decode the JWT Token**\
   Use a JWT decoding tool, such as [jwt.io](https://jwt.io/), to decode and inspect the token.

***

### Sample JWT token structure

Below is an example JWT token structure that includes key claims, custom attributes, and roles:

> [accordion] JWT token example
>
> ```json theme={"dark"}
> {
>   "aud": "api://rd-p-example-flowx-api",
>   "iss": "https://sts.windows.net/673cac6c-3d63-40cf-a43f-07408dd91072/",
>   "iat": 1730720856,
>   "nbf": 1730720856,
>   "exp": 1730726397,
>   "acr": "1",
>   "aio": "ATQAy/8YAAAAj3ca5D/znraYUsif7RVc7TmWJPj66tqsUon0oon1xPamN1W7wN070R1JwaCwUQyQ",
>   "amr": [
>     "pwd"
>   ],
>   "appid": "673b5314-a9c8-40ec-beb5-636fa9a781b4",
>   "appidacr": "0",
>   "email": "john.doe@flowx.ai",
>   "extn.businessFilter": [
>     "docs"
>   ],
>   "family_name": "Doe",
>   "given_name": "John",
>   "groups": [
>     "ef731a0d-b44f-44da-bd78-67363c901bb1",
>     "db856713-0dfa-4d3d-aefa-bbb598257084",
>     "4336202b-6fc4-4132-afab-7f6573993325",
>     "5dc0b52e-823b-4ce9-b3e4-b3070912a4ef",
>     "ce006d40-555f-4247-890b-1053fa3cb172",
>     "291ac248-4e29-4c91-8e1d-19cbeec64eb8",
>     "b82dc551-f3f0-4d28-aaf0-a0a74fe3b3e3",
>     "42b39b5f-7545-48be-88d1-6e88716236db",
>     "cc0f776a-1cb2-4b8c-a472-8e1393764442",
>     "6eac9487-e04c-41e6-81ce-364f09c22bbf",
>     "01c30789-6862-4085-b5c4-f0cb02fb41b0",
>     "75ac188b-61c4-4aa9-ad7e-af1d543e199a",
>     "e726fda5-79f0-440b-b86c-8a9820d14d2e",
>     "259980bb-e881-4d93-9912-d2562441a257",
>     "9146edd4-6194-4487-b524-79956635f514",
>     "ce046ce2-6ef8-40f2-9f4e-a70f1ca14ecf",
>     "62d1f9f5-858c-43e2-af92-94bcc575681b",
>     "69df5ff6-1da9-49d1-9871-b7e62de2b212",
>     "043d25fc-a507-47ee-83e3-1d31ce0d9b35"
>   ],
>   "ipaddr": "86.126.6.183",
>   "name": "Jonh Doe",
>   "oid": "61159071-3fd6-4373-8aec-77ee58675776",
>   "preferred_username": "john.doe@flowx.ai",
>   "rh": "1.AYEAbKw8Z2M9z0CkPwdAjdkQckKVleyLibxCtpIufT-d8oKBAAeBAA.",
>   {/* Most `ROLE_*` entries below are legacy realm roles that may exist in realms created from older FlowX realm exports. FlowX 5.x services do not evaluate them — Designer and platform access is governed by workspace and organization roles plus permissions; see the [Complete roles & permissions matrix](./roles-permissions-matrix). Realm roles are only evaluated where your own configuration references them (for example, swimlane access rules). */}
>   "roles": [
>     "ROLE_DOCUMENT_TEMPLATES_IMPORT",
>     "FLOWX_ROLE",
>     "ROLE_TASK_MANAGER_OOO_ADMIN",
>     "ROLE_ADMIN_MANAGE_CONFIG_IMPORT",
>     "ROLE_INTEGRATION_SYSTEM_READ",
>     "ROLE_INTEGRATION_WORKFLOW_READ_RESTRICTED",
>     "ROLE_ADMIN_MANAGE_PROCESS_ADMIN",
>     "ROLE_MANAGE_NOTIFICATIONS_ADMIN",
>     "ROLE_ADMIN_MANAGE_INTEGRATIONS_EDIT",
>     "ROLE_TASK_MANAGER_HOOKS_IMPORT",
>     "ROLE_THEMES_READ",
>     "ROLE_ENGINE_MANAGE_PROCESS_EDIT",
>     "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_ADMIN",
>     "ROLE_AI_OPTIMIZER_EDIT",
>     "ROLE_ENGINE_MANAGE_INSTANCE_READ",
>     "ROLE_ADMIN_MANAGE_INTEGRATIONS_ADMIN",
>     "ROLE_ADMIN_MANAGE_PROCESS_IMPORT",
>     "ROLE_COPO_TELLER",
>     "ROLE_CMS_CONTENT_READ",
>     "ROLE_CMS_CONTENT_IMPORT",
>     "ROLE_INTEGRATION_WORKFLOW_ADMIN",
>     "ROLE_AI_ARCHITECT_EDIT",
>     "ROLE_TASK_MANAGER_HOOKS_READ",
>     "ROLE_AI_WRITER_EDIT",
>     "ROLE_TASK_MANAGER_HOOKS_ADMIN",
>     "ROLE_MEDIA_LIBRARY_EDIT",
>     "ROLE_CMS_TAXONOMIES_READ",
>     "ROLE_AI_INSPECTOR_EDIT",
>     "FLOWX_FRONTOFFICE",
>     "ROLE_START_EXTERNAL",
>     "ROLE_DOCUMENT_TEMPLATES_READ",
>     "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_IMPORT",
>     "VIEW_INSTANCES",
>     "ROLE_ADMIN_MANAGE_INTEGRATIONS_IMPORT",
>     "ROLE_ADMIN_MANAGE_USERS_READ",
>     "ROLE_THEMES_ADMIN",
>     "ROLE_ADMIN_MANAGE_PLATFORM_READ",
>     "ROLE_TASK_MANAGER_OOO_EDIT",
>     "ROLE_CMS_TAXONOMIES_EDIT",
>     "ROLE_THEMES_IMPORT",
>     "ROLE_AI_DEVELOPER_EDIT",
>     "ROLE_MANAGE_NOTIFICATIONS_READ",
>     "ROLE_INTEGRATION_SYSTEM_EDIT",
>     "ROLE_MANAGE_NOTIFICATIONS_SEND",
>     "FLOWX_ADMIN",
>     "ROLE_INTEGRATION_READ",
>     "FLOWX_BACKOFFICE",
>     "ROLE_DOCUMENT_TEMPLATES_EDIT",
>     "ROLE_MEDIA_LIBRARY_IMPORT",
>     "ROLE_AI_ASSISTANT_READ",
>     "ROLE_ADMIN_MANAGE_CONFIG_EDIT",
>     "ROLE_CMS_TAXONOMIES_IMPORT",
>     "ROLE_ADMIN_MANAGE_CONFIG_ADMIN",
>     "ROLE_TASK_MANAGER_TASKS_READ",
>     "ROLE_DOCUMENT_TEMPLATES_ADMIN",
>     "ROLE_INTEGRATION_WORKFLOW_READ",
>     "ROLE_COPO_VIEWER",
>     "ROLE_MEDIA_LIBRARY_ADMIN",
>     "ROLE_NOTIFICATION_TEMPLATES_EDIT",
>     "ROLE_ADMIN_MANAGE_PROCESS_READ",
>     "ROLE_AI_INTEGRATOR_EDIT",
>     "ROLE_AI_SUPERVISOR_EDIT",
>     "ROLE_INTEGRATION_WORKFLOW_EDIT",
>     "ROLE_CMS_CONTENT_ADMIN",
>     "ROLE_CMS_CONTENT_EDIT",
>     "FLOWX_SUPERVISOR",
>     "ROLE_ADMIN_MANAGE_CONFIG_READ",
>     "ROLE_TASK_MANAGER_OOO_READ",
>     "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_EDIT",
>     "ROLE_INTEGRATION_ADMIN",
>     "ROLE_NOTIFICATION_TEMPLATES_READ",
>     "ROLE_AI_AUDITOR_EDIT",
>     "ROLE_ENGINE_MANAGE_INSTANCE_ADMIN",
>     "ROLE_INTEGRATION_SYSTEM_ADMIN",
>     "ROLE_ADMIN_MANAGE_PROCESS_EDIT",
>     "ROLE_INTEGRATION_EDIT",
>     "ROLE_AI_DESIGNER_EDIT",
>     "ROLE_TASK_MANAGER_HOOKS_EDIT",
>     "ROLE_AI_COMMAND_READ",
>     "ROLE_CMS_TAXONOMIES_ADMIN",
>     "ROLE_ADMIN_MANAGE_USERS_ADMIN",
>     "ROLE_AI_ANALYST_EDIT",
>     "ROLE_TASK_MANAGER_VIEWS_ADMIN",
>     "ROLE_ADMIN_MANAGE_PLATFORM_ADMIN",
>     "ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_READ",
>     "ROLE_AI_STRATEGIST_EDIT",
>     "ROLE_THEMES_EDIT",
>     "ROLE_NOTIFICATION_TEMPLATES_ADMIN",
>     "ROLE_INTEGRATION_IMPORT",
>     "ROLE_NOTIFICATION_TEMPLATES_IMPORT",
>     "ROLE_ADMIN_MANAGE_INTEGRATIONS_READ",
>     "ROLE_ADMIN_MANAGE_USERS_EDIT",
>     "ROLE_MEDIA_LIBRARY_READ"
>   ],
>   "scp": "FlowxAI.ReadWrite.All",
>   "sub": "tMG9A1npM9hK89AV9rdUvTAKVlli3oLkyI1E8F7bV5Y",
>   "tid": "673cac6c-3d63-40cf-a43f-07408dd91072",
>   "unique_name": "john.doe@flowx.ai",
>   "upn": "john.doe@flowx.ai",
>   "uti": "v3igRE_kEUqZC4nbXII3AA",
>   "ver": "1.0",
>   "wids": [
>     "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
>     "fe930be7-5e62-47db-91af-98c3a49a38b1",
>     "e3973bdf-4987-49ae-837a-ba8e231c7286",
>     "158c047a-c907-4556-b7ef-446551a6b5f7",
>     "e8611ab8-c189-46e8-94e1-60213ab1f814",
>     "b79fbf4d-3ef9-4689-8143-76b194e85509"
>   ]
> }
> ```

## Configure helm charts

This section provides details on configuring Helm charts for FlowX.AI applications, including where to retrieve required values and setting environment variables for different application components.

***

### Where to get the values

* **tenant\_id**: The unique identifier for your Entra ID tenant.

  ![Tenant ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%286%29.png)

* **client\_id**: The client ID for the specific FlowX.AI application.

  ![Client ID](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%287%29.png)

* **client\_secret**: The client secret generated during app registration (only visible at creation).

  ![Client Secret](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/entra/image%20%288%29.png)

***

### Helm chart values

These configurations are required for different FlowX.AI application components. Substitute `<tenant_id>`, `<flowx_web_client_id>`, and `<client_id>` with your specific values.

***

#### Designer

For the Designer component, use the following settings:

```yaml theme={"dark"}
SKIP_ISSUER_CHECK: true
STRICT_DISCOVERY_DOCUMENT_VALIDATION: false
KEYCLOAK_ISSUER: https://login.microsoftonline.com/<tenant_id>/v2.0
KEYCLOAK_CLIENT_ID: <flowx_web_client_id>
KEYCLOAK_SCOPES: "openid profile email offline_access api://rd-e-example-flowx-api/FlowxAI.ReadWrite.All"
KEYCLOAK_REDIRECT_URI: https://flowx.example.az1.cloud.flowxai.dev
```

#### All Java application

```yaml theme={"dark"}
SECURITY_TYPE: jwt-public-key
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI: https://sts.windows.net/<tenant_id>/
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI: https://login.microsoftonline.com/<tenant_id>/discovery/v2.0/keys
```

#### Java applications with a Service Principal

These settings apply to Java applications that require a service principal, such as Admin, Integration Designer, Process Engine, Scheduler Core, and Task Management Plugin.

```yaml theme={"dark"}
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID: <client_id>
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: <client_secret>
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_SCOPE: api://rd-p-example-flowx-api/.default
```

#### Java applications with access to Microsoft Graph API

The following configuration is required for Java applications that need access to the Microsoft Graph API, such as Admin and Task Management Plugin.

```yaml theme={"dark"}
OPENID_PROVIDER: entra
OPENID_ENTRA_TENANT_ID: <tenant_id>
OPENID_ENTRA_PRINCIPAL_ID: <flowx_admin_client_id>
```


# End-user access management
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/end-user-access-management

Manage end-user roles, groups, and attributes for controlling access to published solutions at runtime.

> [!NOTE]
>
> **5.8.0+: assignment model changed.** Up to 5.7.0, a role assigned to a user or group at organization level granted access on every project that listed the role. Starting with 5.8.0, role assignment is **per-solution**: define roles and groups here at organization level, then assign them to users or groups from the **Share** modal on the Solutions page. End-user groups also moved from Keycloak to FlowX. See [Runtime authorization](./runtime-authorization) for the new model.

## Overview

End-user access management lets organization admins control who can access published solutions at runtime. Unlike Designer users (who build processes and workflows), end users interact with the finished solutions through the container app.

Manage end users from **Organization Settings** → **Access Management**, where two sections handle runtime access:

* **End-Users**: Invite and manage users who access solutions
* **End-Users Groups**: Organize users into groups with role assignments and custom attributes

You define end-user roles per project, not in Access Management: see [End-users roles](#end-users-roles) below.

***

## End-users

View and manage the list of end users in your organization. End users are separate from Designer users. They access published solutions but cannot modify processes or workflows.

To invite an end user:

1. Navigate to **Organization Settings** → **Access Management** → **End-Users**
2. Click **Add** to invite a new user
3. Enter the user's details

> [!NOTE]
>
> End users authenticate through the same Keycloak realm as the organization. SMTP must be configured in Keycloak for invitation emails to be sent.

***

## End-users roles

Roles define what end users can access at runtime. Roles live in an organization-level catalog, so the same role is reusable across projects, but you create and manage them from a project's version settings. There is no roles section under **Access Management**.

### Managing roles

**1. Open the project's version settings**

In your project, go to **Version Settings** → **End-User Roles**.

**2. Add a role to the version**

Click **Add Role**, then pick an existing role from the organization catalog or select **Create New Role** to define a new one. The role name is visible to end users when the solution is shared.

**3. Assign roles to resources**

Assign the version's roles on process swimlanes and UI Flow permissions to control what each role can access at runtime.

Roles become assignable to users and groups in the **Share** modal once the build that defines them is set as the project's **Active Policy**. See [Runtime authorization](./runtime-authorization) for the assignment model.

***

## End-users groups

Groups organize end users and assign them roles and custom attributes. A group can have multiple roles and multiple key-value attributes.

### Managing groups

**1. Navigate to End-Users Groups**

Go to **Organization Settings** → **Access Management** → **End-Users Groups**.

**2. Create a group**

Click **Add new** and configure:

| Field | Description |
| - | - |
| **Name** | Group name (alphanumeric, dashes, underscores, spaces) |
| **Roles** | Select one or more end-user roles to assign to all members of this group |
| **Attributes** | Optional key-value pairs for custom metadata (e.g., department, region) |

**3. Add attributes (optional)**

Click **Add attribute** to add custom key-value pairs. Each attribute has a **Key** and one or more comma-separated **Values**. Attributes can be used for business filters and data-driven access control.

***

## Permissions

| Permission | Description |
| - | - |
| `org_runtime_users_read` | View the end-users list |
| `org_runtime_users_create` | Invite, create, and import end users |
| `org_runtime_users_edit` | Edit end users |
| `org_runtime_users_delete` | Delete end users |
| `org_runtime_roles_read` | View end-user roles |
| `org_runtime_roles_edit` | Create, edit, and delete end-user roles |
| `org_runtime_groups_read` | View end-user groups |
| `org_runtime_groups_edit` | Create, edit, and delete end-user groups |

These permissions are available to **Organization Admin** and **Organization Owner** roles.

***

## Related resources

> [card] [Organization settings](/5.9/docs/saas/organization-settings)
>
> Overview of all organization-level settings

> [card] [Roles and permissions matrix](./roles-permissions-matrix)
>
> Complete reference for all platform roles and permissions

> [card] [Swimlanes](/5.9/docs/platform-deep-dive/user-roles-management/swimlanes)
>
> Configure role-based task assignment in processes

> [card] [Business filters](/5.9/docs/platform-deep-dive/user-roles-management/business-filters)
>
> Filter data visibility based on user roles and attributes


# Permission reference guide
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/permission-reference-guide

Technical reference for FlowX Designer permissions, naming conventions, and UI mappings

> [!NOTE]
>
> **Documentation Navigation:**
>
> * [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights) - Role overview and concepts
> * [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) - Detailed permission specifications
> * **Permission Reference Guide** (Current) - Technical implementation details
> * [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide) - Practical scenarios and best practices

> [!NOTE]
>
> This guide provides technical reference information for FlowX Designer permissions, including naming conventions, UI element mappings, and implementation details. Use this guide when you need to understand how permissions work at a technical level.

## Permission naming conventions

### Naming structure

FlowX permissions follow a consistent naming pattern that helps identify scope and purpose:

```
[scope_prefix]_[resource]_[operation]
```

### Scope prefixes

| Prefix | Scope Level | Example Permissions | Usage |
| - | - | - | - |
| `org_` | Organization | `org_users_read` • `org_workspaces_edit` • `org_audit_log_read` | Cross-workspace administration and system-level operations |
| `wks_` | Workspace | `wks_users_read` • `wks_builds_create` • `wks_font_delete` | Workspace-level resources that apply across all projects in the workspace |
| `proj_` | Project | `proj_mediafile_read` • `proj_data_type_edit` | Project-specific resources when disambiguation from workspace resources is needed |
| *(none)* | Context-dependent | `process_read` • `workflow_edit` • `enum_create` | Project-level resources where context is clear from usage |

> [!NOTE]
>
> **Why some project permissions lack the `proj_` prefix:**
>
> Most project-level configuration resources (processes, workflows, enumerations, etc.) don't use the `proj_` prefix because:
>
> * Their context is always project-scoped
> * There's no workspace-level equivalent that would create naming conflicts
> * Shorter names improve readability
>
> The `proj_` prefix is used when:
>
> * A workspace-level equivalent exists (e.g., `proj_mediafile_*` vs `mediafile_*` for workspace media)
> * Disambiguation is necessary (e.g., `proj_data_type_*` for project data model)

### Operation suffixes

| Suffix | Description | Typical Actions | Example Permissions |
| - | - | - | - |
| `_read` | View and access resource | • View lists • See details • Export data • Access audit logs | `process_read` • `wks_users_read` • `theme_read` |
| `_edit` | Modify existing resource | • Update properties • Change configurations • Save modifications | `workflow_edit` • `wks_active_policy_edit` • `enum_edit` |
| `_create` | Create new instances | • Add new items • Import data • Duplicate existing items | `project_create` • `wks_builds_create` • `notification_templates_create` |
| `_delete` | Remove resource | • Delete items • Remove from system | `stage_delete` • `wks_groups_delete` • `process_delete` |
| `_admin` | Administrative control | • Grant/revoke access • Manage permissions • Full governance | `projects_admin` • `workspaces_admin` |

### Special naming cases

> [accordion] Properties named 'id' or 'url'
>
> When a resource property is named "id" or "url" (case insensitive), it must be prefixed with `userDefined:` to avoid conflicts with system properties.
>
> **Examples:**
>
> * `userDefined:URL` - For a custom URL property
> * `userDefined:id` - For a custom ID field
>
> This applies when working with:
>
> * Database properties
> * Configuration parameters
> * Custom data model fields

> [accordion] Date and place properties
>
> **Date Properties** are split into multiple permission fields:
>
> ```
> date:`{property_name}`:start
> date:`{property_name}`:end (optional)
> date:`{property_name}`:is_datetime (0 or 1)
> ```
>
> **Place Properties** are split into multiple fields:
>
> ```
> place:`{property_name}`:name
> place:`{property_name}`:address
> place:`{property_name}`:latitude
> place:`{property_name}`:longitude
> place:`{property_name}`:google_place_id (optional)
> ```
>
> These expanded formats provide granular control over complex property types.

> [accordion] Checkbox property values
>
> Checkbox properties use special string values instead of boolean:
>
> * `__YES__` for checked
> * `__NO__` for unchecked
>
> **Example:**
>
> ```json theme={"dark"}
> {
>   "Is Complete": "__YES__",
>   "Requires Approval": "__NO__"
> }
> ```

> [accordion] Number property format
>
> Number properties must use JavaScript number format, not strings:
>
> **Correct:**
>
> ```json theme={"dark"}
> {"Priority": 5}
> ```
>
> **Incorrect:**
>
> ```json theme={"dark"}
> {"Priority": "5"}
> ```

> [accordion] Substitution tags consolidation
>
> Substitution tags use the enumeration permission set:
>
> * `enum_read`
> * `enum_edit`
> * `enum_create`
> * `enum_delete`
>
> There are no separate `substitution_tags_*` permissions - enumeration permissions cover both resource types.

> [accordion] AI agent permissions
>
> AI agent permissions deviate from the standard pattern:
>
> * Only `aiagent_edit` exists
> * No separate `_read`, `_create`, or `_delete` permissions
> * The edit permission grants access to all AI agent functionality (developer, analyst, designer)

### Permission examples by category

> [tab] Organization Level
>
> | Permission | Scope | Resource | Operation |
> | - | - | - | - |
> | `org_users_read` | Organization | Users | Read |
> | `org_users_create` | Organization | Users | Create |
> | `org_roles_read` | Organization | Roles | Read |
> | `org_workspaces_edit` | Organization | Workspaces | Edit |
> | `org_audit_log_read` | Organization | Audit log | Read |
>
> > [!NOTE]
> >
> > `org_admin` is a predefined **role**, not a permission. Organization administration is granted through the `org_` permissions above plus `workspaces_admin`. See the [Complete roles & permissions matrix](./roles-permissions-matrix) for what each predefined role carries.

> [tab] Workspace Level
>
> | Permission | Scope | Resource | Operation |
> | - | - | - | - |
> | `wks_users_read` | Workspace | Users | Read |
> | `wks_users_create` | Workspace | Users | Create |
> | `wks_groups_edit` | Workspace | Groups | Edit |
> | `wks_roles_delete` | Workspace | Roles | Delete |
> | `wks_builds_create` | Workspace | Builds | Create |
> | `wks_active_policy_edit` | Workspace | Active Policy | Edit |
> | `wks_config_param_overrides_read` | Workspace | Config Param Overrides | Read |
> | `wks_process_instances_edit` | Workspace | Process Instances | Edit |
> | `wks_process_instance_variables_edit` | Workspace | Process Variables | Edit |
> | `wks_platform_status_read` | Workspace | Platform Status | Read |
> | `wks_env_info_edit` ⚠️ | Workspace | Environment Info ⚠️ *Deprecated in 5.7.0; the Configure Environment Info UI has been removed.* | Edit |
> | `wks_audit_log_read` | Workspace | Audit Log | Read |
> | `mediafile_create` | Workspace | Media Files | Create |
> | `theme_edit` | Workspace | Themes | Edit |
> | `wks_font_delete` | Workspace | Fonts | Delete |
> | `proxy_connection_read` | Workspace | Proxy Connections | Read |
> | `proxy_connection_edit` | Workspace | Proxy Connections | Edit |
> | `proxy_connection_create` | Workspace | Proxy Connections | Create |
> | `proxy_connection_delete` | Workspace | Proxy Connections | Delete |

> [tab] Project Level
>
> | Permission | Scope | Resource | Operation |
> | - | - | - | - |
> | `project_read` | Project | Project/Library | Read |
> | `project_owner` | Project | Project/Library | Owner (special) |
> | `projects_admin` | Project | Projects | Admin |
> | `process_edit` | Project | Processes | Edit |
> | `proj_data_type_create` | Project | Data Model | Create |
> | `enum_delete` | Project | Enumerations | Delete |
> | `proj_mediafile_read` | Project | Media Library | Read |
> | `notification_templates_create` | Project | Notification Templates | Create |
> | `document_templates_edit` | Project | Document Templates | Edit |
> | `task_view_read` | Project | Views | Read |
> | `stage_create` | Project | Stages | Create |
> | `allocation_rule_edit` | Project | Allocation Rules | Edit |
> | `data_source_delete` | Project | Data Sources | Delete |
> | `workflow_read` | Project | Workflows | Read |
> | `reusable_ui_create` | Project | Reusable UI | Create |
> | `reusable_br_edit` | Project | Reusable Business Rules | Edit |
> | `dependency_read` | Project | Dependencies | Read |
> | `config_param_create` | Project | Config Parameters | Create |
> | `version_edit` | Project | Version Settings | Edit |
> | `aiagent_edit` | Project | AI Agents | Edit (special) |

## Permission-to-UI action mapping

> [!NOTE]
>
> This section shows how permissions control specific UI elements and actions in FlowX Designer. When a user lacks a permission, the corresponding UI element is hidden or disabled.

### Understanding UI behavior

> [card] Permission Enforcement Rules
>
> **Read Permission Behavior:**
>
> * Read permission must be explicitly declared
> * Not automatically implied by other permissions
> * Exception: `workspace_read` is auto-included with any workspace permission
>
> **UI Display Rules:**
>
> * Missing permission = Hidden UI element
> * Read-only permission = View mode with disabled controls
> * No error messages shown for hidden elements

### Workspace level permissions

> [tab] Themes
>
> #### Theme Permissions (`theme_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `theme_read` | • View themes • Export theme | • Theme entry in main menu • Theme list in read-only mode • Export button |
> | `theme_edit` | • Modify theme settings • Set as default • Configure theme sections • Copy from other themes | • Configure in contextual menu • Set as default button • Save button • All edit controls in theme sections • Copy from actions |
> | `theme_create` | • Create new theme • Import theme • Duplicate existing theme | • Add button • Import action • Duplicate in contextual menu |
> | `theme_delete` | • Remove theme | • Delete in contextual menu |
>
> > [!NOTE]
> >
> > When user has only `theme_read`, the theme page displays in read-only mode with all edit controls disabled.

> [tab] Fonts
>
> #### Font Permissions (`wks_font_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_font_read` | • View font list • Export fonts | • Fonts entry in main menu • Font list in read-only mode • Export actions |
> | `wks_font_create` | • Upload new fonts • Import font packages | • Add button • Import action |
> | `wks_font_delete` | • Remove fonts | • Delete icon in contextual menu |
>
> > [!NOTE]
> >
> > Font editing is implicit with create permission - fonts are replaced rather than edited.

> [tab] Media Library
>
> #### Media Library Permissions (`mediafile_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `mediafile_read` | • View media assets • Export media files | • Global media library entry in main menu • Media list in read-only mode • Export button |
> | `mediafile_edit` | • Update media metadata • Replace media files | • Edit controls for media properties |
> | `mediafile_create` | • Upload new media • Import media packages | • Add button • Import action |
> | `mediafile_delete` | • Remove media files | • Delete in contextual menu |

> [tab] Users & Groups
>
> #### User Management Permissions (`wks_users_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_users_read` | • View workspace users • See user details | • Users entry in main menu • User list in read-only mode |
> | `wks_users_edit` | • Modify user workspace access • Update user roles | • Edit controls for user properties |
> | `wks_users_create` | • Add users to workspace • Grant workspace access | • Add button • Grant access action |
> | `wks_users_delete` | • Remove workspace access | • Delete in contextual menu |
>
> #### Group Management Permissions (`wks_groups_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_groups_read` | • View workspace groups • See group members | • Groups entry in main menu • Group list in read-only mode |
> | `wks_groups_edit` | • Modify group membership • Update group properties | • Edit controls for groups • Add/remove member actions |
> | `wks_groups_create` | • Create new groups | • Add button |
> | `wks_groups_delete` | • Remove groups | • Delete in contextual menu |
>
> #### Role Management Permissions (`wks_roles_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_roles_read` | • View workspace roles • See role permissions | • Roles entry in main menu • Role list in read-only mode |
> | `wks_roles_edit` | • Modify role permissions • Update role properties | • Edit controls for roles • Permission checkboxes |
> | `wks_roles_create` | • Create custom roles • Duplicate existing roles | • Add button • Duplicate action |
> | `wks_roles_delete` | • Remove custom roles | • Delete in contextual menu |
>
> > [!WARNING]
> >
> > Predefined roles (`workspace_admin`, `workspace_user`, etc.) cannot be edited or deleted regardless of permissions.

> [tab] Runtime Operations
>
> #### Build Permissions (`wks_builds_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_builds_read` | • View all workspace builds • See build details | • Runtime > Builds menu entry • Build list for all libraries |
> | `wks_builds_create` | • Import build packages • Create builds from versions | • Import build button • Create build action on library versions |
>
> > [!NOTE]
> >
> > `wks_builds_read` allows viewing builds from **all** libraries in the workspace, not just accessible projects.
>
> #### Active Policy Permissions (`wks_active_policy_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_active_policy_read` | • View active policies • See policy configurations • Access audit logs | • Active policy entry in Runtime tab • Policy page in read-only mode • Type and branch selectors disabled • Audit logs in contextual menu |
> | `wks_active_policy_edit` | • Select branch/build • Update active policy • Change policy type | • Save button enabled • Branch/build dropdown selectors enabled • Policy type selector enabled |
>
> #### Configuration Parameter Overrides (`wks_config_param_overrides_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_config_param_overrides_read` | • View parameter overrides • See override values • Access audit logs | • Configuration parameters overrides menu entry • Override list in read-only mode • View icon on rows • Audit log in contextual menu |
> | `wks_config_param_overrides_create` | • Add new overrides | • Add configuration parameter override button |
> | `wks_config_param_overrides_edit` | • Modify override values | • Edit icon on table rows • Update override modal |
> | `wks_config_param_overrides_delete` | • Remove overrides | • Delete in contextual menu |
>
> #### Process Variables (`wks_process_instance_variables_edit`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `wks_process_instance_variables_edit` | • Edit process variables on active instances • Add/delete attributes/objects | • Edit option in contextual menu • Edit button in Variables tab • Monaco editor for JSON editing • Save button |
>
> > [!NOTE]
> >
> > This permission is assigned to the `WORKSPACE_ADMIN` and `WORKSPACE_OPERATIONS_EDITOR` roles. On SaaS (5.13), `WORKSPACE_CORRECTIVE_ACTIONS_EDITOR` replaces `WORKSPACE_OPERATIONS_EDITOR` and carries this permission.&#x20;

### Project level permissions

> [tab] Project Management
>
> #### Project Permissions (`project_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `project_read` | • View project details • Copy project UUID • Access audit logs | • Configure (shown as "View") in contextual menu • Copy UUID action • Audit log access • Project details in read-only mode |
> | `project_edit` | • Modify project settings • Configure project properties | • Configure in contextual menu • Edit controls enabled • Save button active |
> | `project_create` | • Create new projects • Import project versions | • Add button • Import version action |
> | `project_delete` | • Remove projects | • Delete in contextual menu |
>
> > [!WARNING]
> >
> > `project_create` is granted at workspace level. Users create projects within their workspace, not within other projects.

> [tab] Process Configuration
>
> #### Process Permissions (`process_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `process_read` | • View process list • Export processes • Copy to another project • Access audit logs | • Processes list • Export all button • Export in contextual menu • Copy to another project/library action • Audit logs access • Read-only process view |
> | `process_edit` | • Modify process definitions • Configure process details • Edit process settings • Clear cache | • Configure details in contextual menu • Edit settings action • Save button • All edit controls on process designer • Clear cache action |
> | `process_create` | • Create new processes • Import processes • Duplicate processes | • Add button • Import from ZIP (bulk) • Duplicate in contextual menu |
> | `process_delete` | • Remove processes | • Delete in contextual menu |
>
> > [!NOTE]
> >
> > When user has only `process_read`, the process designer opens in read-only mode with all edit controls disabled.

> [tab] Content Management
>
> #### Enumeration Permissions (`enum_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `enum_read` | • View enumerations • Export enumerations • See enum values | • Enumerations entry in Project menu • Export to ZIP button • Export to CSV button • Read icon on enum rows • Read-only enum view |
> | `enum_edit` | • Modify enum values • Configure enum settings • Add enum values • Create child enums • Remove enum values | • Edit icon on enum rows (replaces read icon) • Configure in contextual menu • Edit icon on enum value rows • Create child enum icon • Delete icon on enum value rows • Add value button |
> | `enum_create` | • Create new enumerations • Import enumerations • Duplicate enumerations | • Add button • Import from ZIP • Import from CSV • Duplicate in contextual menu |
> | `enum_delete` | • Remove enumerations | • Delete in contextual menu |
>
> > [!NOTE]
> >
> > The read icon automatically changes to an edit icon when the user has `enum_edit` permission.

> [tab] Workflows
>
> #### Workflow Permissions (`workflow_*`)
>
> | Permission | UI Actions Enabled | UI Elements |
> | - | - | - |
> | `workflow_read` | • View workflows • Export workflows | • Workflows entry in Project menu • Export all (bulk) • Export in contextual menu |
> | `workflow_edit` | • Modify workflow logic • Configure workflow settings • Edit workflow details • Clear cache • Delete condition nodes • Save code changes | • Configure in contextual menu • Edit details in resource page contextual menu • Clear cache in resource page contextual menu • Delete icon on Condition type nodes • Save changes in expanded code editor |
> | `workflow_create` | • Create new workflows • Import workflows • Duplicate workflows | • Add button • Import from ZIP • Duplicate in contextual menu • Duplicate in resource page contextual menu |
> | `workflow_delete` | • Remove workflows | • Delete in contextual menu |

### Permission dependency rules

> [card] Critical Permission Dependencies
>
> **Workspace Level:**
>
> `workspace_read` - Automatically included when any other workspace permission is granted. Required for basic workspace visibility and validation.
>
> `workspace_edit` - Should be included when granting any workspace edit permission. Provides general workspace modification context.
>
> **Project Level:**
>
> `project_read` - Automatically sent to backend when any project-level permission is selected, even though not displayed in UI as selectable. Required for basic project access validation.
>
> **Rule:** Read permissions establish the foundation for all other permissions on a resource.

## Groups technical reference

> [!NOTE]
>
> Understanding how groups work at a technical level helps administrators implement effective access control strategies.

### System-managed groups

#### Everyone in workspace group

> [card] Technical Implementation
>
> **Display Name:** `Everyone in workspace` (identical for every workspace; the workspace name is not embedded)
>
> **Identifier:** a system-generated UUID (there is no semantic `all_users_*` identifier)
>
> **Automatic Behaviors:**
>
> * Created during workspace provisioning by the authorization-system service
> * System-owned — cannot be manually modified via UI or API
> * Membership managed through workspace access events
> * Pre-populated in project access grant interfaces
> * Included in user/group search result sets
>
> **Use Cases:**
>
> * Default access patterns for new projects
> * Workspace-wide policy application
> * Bulk access management operations
> * Simplified onboarding workflows

### Custom group architecture

> [tab] Group Structure
>
> **Group Properties:**
>
> * Unique identifier (UUID)
> * Display name (user-defined)
> * Description (optional)
> * Workspace scope (cannot span workspaces)
> * Member list (user IDs)
> * Role assignments (workspace-level)
>
> **Group Membership:**
>
> * Direct user assignments
> * No nested group support
> * Membership changes propagate immediately
> * Audit trail maintained for membership changes

> [tab] Permission Resolution
>
> **When user has multiple group memberships:**
>
> 1. Collect all permissions from all groups
> 2. Union permissions (more permissive wins)
> 3. Combine with individual user permissions
> 4. Apply most permissive result
>
> **Example:**
>
> ```
> User is member of:
> - Group A: project_viewer on Project X
> - Group B: project_editor on Project X
>
> Result: User has project_editor access (more permissive)
> ```
>
> **Individual Override:**
> Individual permission assignments take precedence over group-based assignments when more restrictive.

> [tab] Performance Considerations
>
> **Optimization Strategies:**
>
> * Group permissions cached per user session
> * Membership changes invalidate affected user caches
> * Batch operations recommended for large groups
> * Avoid excessive group count per user (recommend \< 20)
>
> **Best Practices:**
>
> * Use groups for >5 users with same access pattern
> * Prefer groups over individual assignments at scale
> * Regular cleanup of unused groups
> * Monitor group membership sizes

## Advanced topics

### Permission override scenarios

> [accordion] Multiple Role Assignments
>
> **Scenario:** User assigned multiple roles at same level
>
> **Resolution:**
>
> * Permissions are combined (union)
> * Most permissive permission wins
> * Cannot have conflicting restrictions
>
> **Example:**
>
> ```
> User has both:
> - theme_editor (theme permissions)
> - workspace_runtime_editor (runtime permissions)
>
> Result: User has both theme AND runtime permissions
> ```

> [accordion] Cross-Level Permission Conflicts
>
> **Scenario:** Workspace role vs. project role
>
> **Resolution:**
>
> * Project-level permissions are additive to workspace permissions
> * Workspace role doesn't auto-grant project access
> * Explicit project access required even with workspace admin role
>
> **Example:**
>
> ```
> User is workspace_admin:
> - Has admin rights at workspace level
> - Still needs project role to access specific projects
> - Project owner can still restrict workspace admin
> ```

> [accordion] Group vs Individual Permissions
>
> **Scenario:** User has both group-based and individual permissions
>
> **Resolution:**
>
> * Combine all permissions from all sources
> * More permissive permission wins
> * Individual cannot override to be more restrictive
>
> **Example:**
>
> ```
> Group A grants: project_viewer
> Individual grant: project_editor
>
> Result: User has project_editor (more permissive)
> ```

### Permission caching and propagation

> [card] Caching Behavior
>
> **Cache Locations:**
>
> * User session cache (browser)
> * Backend permission cache (per user)
> * Database role definitions (persistent)
>
> **Cache Invalidation:**
>
> * User logout clears session cache
> * Role changes propagate within 5 minutes
> * Group membership changes immediate
> * Manual cache clear via re-login
>
> **Troubleshooting Cache Issues:**
>
> 1. User logs out completely
> 2. Clear browser cache and cookies
> 3. User logs back in
> 4. Permissions refresh from database
> 5. If still not working, check role assignments

## Related documentation

> [card] [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights)
>
> Overview of FlowX workspace access rights and role hierarchy

> [card] [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> Detailed permission matrices for all FlowX roles

> [card] [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide)
>
> Practical guidance for choosing and assigning roles

> [card] [Access Management Overview](/5.9/setup-guides/access-management/access-management-overview)
>
> Overview of FlowX access management system


# Role selection & management guide
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/role-selection-guide

Practical guidance for selecting and assigning the right roles in FlowX Designer

> [!NOTE]
>
> **Documentation Navigation:**
>
> * [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights) - Role overview and concepts
> * [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) - Detailed permission specifications
> * [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide) - Technical implementation details
> * **Role Selection Guide** (Current) - Practical scenarios and best practices

> [!NOTE]
>
> This guide helps you choose the appropriate roles for different users based on their responsibilities, expertise, and access requirements.

## Role selection decision tree

Use this decision tree to quickly identify the appropriate role:

```mermaid theme={"dark"}
graph TD
    A[Need to assign role] --> B{User manages multiple workspaces?}
    B -->|Yes| C[org_admin]
    B -->|No| D{User manages workspace resources?}
    D -->|Yes, full management| E[workspace_admin]
    D -->|No| F{What is user's primary responsibility?}
    F -->|Visual design & branding| G[theme_editor]
    F -->|Runtime deployments| H[workspace_runtime_editor]
    F -->|Process operations & migrations| N[workspace_operations_editor]
    F -->|Project configuration| I{Access level needed?}
    F -->|General workspace access| J[workspace_user]
    I -->|Full control & ownership| K[project_owner]
    I -->|Full configuration access| L[project_editor]
    I -->|View only for audit/review| M[project_viewer]
```

## Role selection by persona

### Platform administrators

> [card] Organization Administrator
>
> **Role:** `org_admin`
>
> **Typical Responsibilities:**
>
> * Managing the entire FlowX platform
> * Creating and organizing workspaces
> * Managing organization-wide users and groups
> * Overseeing system health and configurations
> * Implementing organization-wide policies
>
> **Example Users:**
>
> * Platform administrators
> * IT managers
> * System architects
>
> **Key Considerations:**
>
> * Assign sparingly - only to users needing cross-workspace access
> * Has access to ALL projects across ALL workspaces
> * Should be limited to 2-3 trusted individuals

### Business unit managers

> [card] Workspace Administrator
>
> **Role:** `workspace_admin`
>
> **Typical Responsibilities:**
>
> * Managing workspace users and access
> * Overseeing all workspace projects
> * Managing workspace themes and branding
> * Configuring workspace-level settings
> * Handling workspace resource allocation
>
> **Example Users:**
>
> * Department heads
> * Business unit managers
> * Team leads with administrative duties
>
> **Key Considerations:**
>
> * Has admin access to all projects in their workspace
> * Cannot access other workspaces without explicit assignment
> * Should be assigned to responsible leaders only

### Developers and configurators

> [card] Project Owner
>
> **Role:** `project_owner`
>
> **Assignment:** Automatic (assigned to project creator)
>
> **Typical Responsibilities:**
>
> * Complete project governance
> * Managing project team access
> * Final approval on project changes
> * Project lifecycle management
>
> **Example Users:**
>
> * Project leads
> * Technical architects
> * Product owners
>
> **Key Considerations:**
>
> * Automatically assigned at project creation
> * Can transfer ownership to another user
> * Only one owner per project

> [card] Project Editor
>
> **Role:** `project_editor`
>
> **Typical Responsibilities:**
>
> * Building and configuring processes
> * Designing workflows
> * Creating UI configurations
> * Managing integrations
> * Creating builds and deployments
>
> **Example Users:**
>
> * Senior developers
> * Business analysts
> * Technical configurators
>
> **Key Considerations:**
>
> * Full configuration access without ownership
> * Cannot grant/revoke project access
> * Standard role for project team members
>
> **Runtime Policy Access:**
>
> * Configurators who need to change active policy should be assigned `workspace_runtime_editor` role in their workspace
> * Even if they only have `project_viewer` access on specific projects, the workspace-level runtime role allows policy changes

### Specialized roles

> [card] UI/UX Designer
>
> **Role:** `theme_editor`
>
> **Typical Responsibilities:**
>
> * Designing application themes
> * Managing brand assets
> * Creating and organizing fonts
> * Managing media library
> * Ensuring visual consistency
>
> **Example Users:**
>
> * UI/UX designers
> * Brand managers
> * Visual designers
> * Marketing team members
>
> **Key Considerations:**
>
> * Extends workspace\_user with design permissions
> * Can create projects but focused on visual aspects
> * Read-only for projects without explicit access

> [card] DevOps Engineer
>
> **Role:** `workspace_runtime_editor`
>
> **Typical Responsibilities:**
>
> * Creating and managing builds
> * Configuring runtime environments
> * Managing deployment policies
> * Overriding configuration parameters
> * Monitoring process instances
>
> **Example Users:**
>
> * DevOps engineers
> * Release managers
> * Technical operations staff
> * System administrators
>
> **Key Considerations:**
>
> * Extends workspace\_user with runtime permissions
> * Can manage deployments across workspace
> * Does not grant automatic project configuration access

> [card] Operations Engineer
>
> **Role:** `workspace_operations_editor`
>
> **Typical Responsibilities:**
>
> * Managing process instance operations (migration & move token)
> * Editing process variables on active instances
> * Managing operational tasks across the workspace
> * Supporting process migrations and token movements
>
> **Example Users:**
>
> * Support engineers
> * Operations team members
> * Technical support staff
> * Process operations managers
>
> **Key Considerations:**
>
> * Extends workspace\_user with operations permissions
> * Can manage operations across workspace
> * Does not include broader runtime capabilities (builds, policies)

#### Operations Engineer role on SaaS

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Assign the **Workspace corrective actions editor** role to Operations Engineers. It replaces the Workspace operations editor role, and existing assignments are moved to the new role automatically. The role lets users run migration and move token on process instances and edit process instance variables. See the [Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).

### Stakeholders and reviewers

> [card] General Workspace User
>
> **Role:** `workspace_user`
>
> **Typical Responsibilities:**
>
> * Creating new projects
> * Working on assigned projects
> * Viewing workspace resources
> * Basic workspace participation
>
> **Example Users:**
>
> * Junior developers
> * Business analysts
> * Process designers
> * General team members
>
> **Key Considerations:**
>
> * Default role for most workspace members
> * Can create projects (becomes owner automatically)
> * Needs explicit project access to work on others' projects

> [card] Viewer / Auditor
>
> **Role:** `project_viewer`
>
> **Typical Responsibilities:**
>
> * Reviewing project configurations
> * Auditing processes and workflows
> * Compliance checking
> * Documentation and training
>
> **Example Users:**
>
> * Business stakeholders
> * Quality assurance personnel
> * Compliance officers
> * External consultants
> * New team members (onboarding)
>
> **Key Considerations:**
>
> * Completely read-only access
> * Can test processes through interface
> * Safe for sensitive stakeholders

## Common role assignment scenarios

### Scenario 1: New employee onboarding

**1. Day 1: View-only access**

Assign `workspace_user` role at workspace level

Grant `project_viewer` role for relevant projects

**Rationale:** Allow new employee to explore and learn without risk

**2. Week 2-4: Limited editing**

Grant `project_editor` role for specific training projects

Keep viewer access for production projects

**Rationale:** Hands-on learning in safe environment

**3. After onboarding: Full access**

Grant `project_editor` role for assigned projects

Remove training project access

**Rationale:** Ready for production work with appropriate permissions

### Scenario 2: External consultant engagement

> [accordion] Short-term review (1-2 weeks)
>
> **Recommended Role:** `project_viewer`
>
> **Access Pattern:**
>
> * Grant access only to specific projects under review
> * No workspace-level role assignment
> * Time-bound access (remove after engagement)
>
> **Benefits:**
>
> * Complete visibility for review purposes
> * No risk of accidental modifications
> * Easy to audit consultant's activities

> [accordion] Implementation project (3-6 months)
>
> **Recommended Roles:**
>
> * Workspace level: `workspace_user`
> * Project level: `project_editor` for specific projects
>
> **Access Pattern:**
>
> * Create dedicated workspace for consultant projects
> * Grant editor access only to contracted projects
> * Regular access reviews during engagement
>
> **Benefits:**
>
> * Consultant can work independently
> * Clear boundaries on accessible projects
> * Easy cleanup after engagement ends

> [accordion] Long-term partnership (6+ months)
>
> **Recommended Roles:**
>
> * Workspace level: `workspace_user` or specialized role
> * Project level: `project_editor` or `project_owner` as needed
>
> **Access Pattern:**
>
> * Treat similar to internal team member
> * Consider dedicated workspace for partner projects
> * Quarterly access reviews and adjustments
>
> **Benefits:**
>
> * Full integration with team workflows
> * Appropriate access for extended engagement
> * Maintains security through regular reviews

### Scenario 3: Cross-functional team project

> [tab] Small Project (2-5 people)
>
> **Team Composition:**
>
> * 1 Project Owner (automatically assigned to creator)
> * 2-3 Project Editors (developers/analysts)
> * 1 Project Viewer (stakeholder)
>
> **Access Setup:**
>
> ```
> 1. Creator starts project → becomes project_owner
> 2. Grant project_editor to development team
> 3. Grant project_viewer to business stakeholder
> 4. Use "Everyone in workspace" group if all team members need access
> ```
>
> **Best Practices:**
>
> * Keep team small and roles simple
> * Regular sync meetings reduce need for complex permissions
> * Document decisions in project comments

> [tab] Medium Project (5-15 people)
>
> **Team Composition:**
>
> * 1 Project Owner (technical lead)
> * 5-8 Project Editors (developers, analysts, designers)
> * 1 Theme Editor (UI/UX specialist)
> * 2-3 Project Viewers (stakeholders, QA)
> * 1 Runtime Editor (DevOps)
>
> **Access Setup:**
>
> ```
> 1. Create workspace groups:
>    - "ProjectName_Developers" → project_editor
>    - "ProjectName_Stakeholders" → project_viewer
> 2. Assign specialized workspace roles as needed
> 3. Use groups for bulk permission management
> ```
>
> **Best Practices:**
>
> * Use groups instead of individual assignments
> * Regular access reviews (monthly)
> * Document group purposes clearly

> [tab] Large Project (15+ people)
>
> **Team Composition:**
>
> * 1 Project Owner (product owner/architect)
> * 10-15 Project Editors (multiple teams)
> * 2-3 Theme Editors (design team)
> * 1-2 Runtime Editors (DevOps team)
> * 5-8 Project Viewers (stakeholders, compliance, QA)
>
> **Access Setup:**
>
> ```
> 1. Create hierarchical groups:
>    - "ProjectName_Core_Team" → project_editor
>    - "ProjectName_Design_Team" → theme_editor + project_editor
>    - "ProjectName_DevOps_Team" → runtime_editor + project_editor
>    - "ProjectName_Stakeholders" → project_viewer
> 2. Use workspace admin to manage groups centrally
> 3. Implement approval workflow for access requests
> ```
>
> **Best Practices:**
>
> * Dedicated workspace admin for project
> * Automated access reviews (bi-weekly)
> * Clear escalation path for access issues
> * Document architecture decisions and ownership

### Scenario 4: Multi-workspace organization

> [card] Enterprise Organization Structure
>
> **Organizational Setup:**
>
> **Organization Level:**
>
> * 2-3 `org_admin` (Platform administrators)
>
> **Workspace Level (per business unit):**
>
> * 1 `workspace_admin` (Business unit manager)
> * 15-30 `workspace_user` (Standard members)
> * 2-3 `theme_editor` (Design team)
> * 1-2 `workspace_runtime_editor` (DevOps team)
> * 1-2 `workspace_operations_editor` (Operations/Support team)
>
> **Project Level (varies by project):**
>
> * Projects follow patterns from Scenario 3
>
> **Access Patterns:**
>
> * Each business unit has dedicated workspace
> * Cross-workspace collaboration via library sharing
> * Central DevOps team has runtime\_editor in all workspaces
> * Central design team has theme\_editor in relevant workspaces
> * Central operations team has operations\_editor for process management
>
> **Governance:**
>
> * Monthly access reviews by workspace\_admin
> * Quarterly organization-wide audit by org\_admin
> * Automated alerts for inactive users
> * Clear documentation of cross-workspace access

## Role escalation matrix

When should you upgrade a user's role?

| Current Role | Escalate To | Trigger Conditions | Approval Required |
| - | - | - | - |
| `project_viewer` | `project_editor` | User needs to make configuration changes Completed onboarding period | Project Owner |
| `workspace_user` | `theme_editor` | User assigned to design responsibilities Demonstrated design skills | Workspace Admin |
| `workspace_user` | `runtime_editor` | User assigned to DevOps responsibilities Deployment management needed | Workspace Admin |
| `workspace_user` | `operations_editor` | User assigned to operations responsibilities Process migration needs | Workspace Admin |
| `project_editor` | `project_owner` | Original owner leaving User taking over project leadership | Current Owner or Workspace Admin |
| `workspace_user` | `workspace_admin` | User promoted to management Administrative duties assigned | Organization Admin |
| `workspace_admin` | `org_admin` | User taking platform-wide responsibilities Multi-workspace management | Existing Org Admin + Management |

> [!WARNING]
>
> Always follow the principle of least privilege. Escalate roles only when necessary and document the business justification.

## Role de-escalation and removal

### When to downgrade roles

> [accordion] Project Completion
>
> **Scenario:** Project is completed and moved to maintenance
>
> **Action:**
>
> * Downgrade most `project_editor` to `project_viewer`
> * Keep 1-2 editors for maintenance
> * Keep project\_owner for governance
>
> **Timing:** At project completion milestone

> [accordion] Role Change
>
> **Scenario:** User moves to different team or responsibilities
>
> **Action:**
>
> * Remove access to old projects
> * Assign appropriate role for new responsibilities
> * Transfer project\_owner if applicable
>
> **Timing:** During role transition period

> [accordion] Contractor End
>
> **Scenario:** Contractor engagement ends
>
> **Action:**
>
> * Remove all workspace access
> * Document contractor's contributions
> * Archive or transfer project ownership if needed
>
> **Timing:** On contractor's last day

> [accordion] Security Incident
>
> **Scenario:** Suspicious activity or policy violation
>
> **Action:**
>
> * Immediate suspension of access
> * Investigation by security/admin team
> * Appropriate remediation based on findings
>
> **Timing:** Immediately upon detection

### Access removal checklist

**1. Identify all access points**

* List all workspaces user has access to
* Identify all projects with direct access
* Check group memberships
* Review project ownership assignments

**2. Transfer ownership**

* Transfer project\_owner role if user owns projects
* Update project documentation with new owner
* Notify project stakeholders of change

**3. Remove access**

* Remove from workspace-level roles
* Remove from project-level access
* Remove from all groups
* Verify removal in system

**4. Document and communicate**

* Document reason for removal
* Update team rosters and directories
* Communicate changes to affected teams
* Archive for compliance if needed

## Role assignment anti-patterns

> [!WARNING]
>
> Avoid these common mistakes when assigning roles:

### Anti-pattern 1: Everyone is an admin

**Problem:**

* Assigning `workspace_admin` or `org_admin` to too many users
* "Just in case" administrative access

**Impact:**

* Reduced security and accountability
* Increased risk of accidental changes
* Difficult to audit who made changes

**Solution:**

* Limit admin roles to actual administrators
* Use `project_editor` or `project_owner` for project-level needs
* Implement proper access request workflow

### Anti-pattern 2: Never updating roles

**Problem:**

* Roles assigned during onboarding never reviewed
* Users retain access after role changes
* Inactive users still have full access

**Impact:**

* Security vulnerabilities accumulate
* Compliance issues with access audits
* Potential data breaches

**Solution:**

* Quarterly access reviews
* Automated inactive user detection
* Role-based access recertification

### Anti-pattern 3: Individual assignments instead of groups

**Problem:**

* Assigning roles to individual users instead of groups
* Not using the "Everyone in workspace" group
* Managing access one user at a time

**Impact:**

* High administrative overhead
* Inconsistent access patterns
* Difficult to scale

**Solution:**

* Create groups for teams and functions
* Use groups for project access
* Individual assignments only for exceptions

### Anti-pattern 4: Too granular or too broad

**Problem:**

* Creating overly complex permission structures
* OR giving everyone the same high-level access

**Impact:**

* Confusion about who can do what
* Either too restrictive or too permissive
* Difficult to maintain

**Solution:**

* Start with predefined roles
* Use workspace/project boundaries naturally
* Add granularity only when truly needed

### Anti-pattern 5: No documentation

**Problem:**

* Access decisions not documented
* No record of why users have certain roles
* No clear ownership of access management

**Impact:**

* Cannot audit access decisions
* Difficult to troubleshoot access issues
* Compliance problems

**Solution:**

* Document all non-standard role assignments
* Maintain role assignment justifications
* Clear ownership of access management process

## Groups and access management

> [!NOTE]
>
> FlowX uses groups to simplify access management across users. Understanding built-in groups and creating custom groups efficiently manages permissions at scale.

### Built-in workspace groups

#### Everyone in workspace group

Every workspace automatically includes a special system-managed group for all workspace members:

> [card] all\_users\_\[workspace\_name]
>
> **Display Name in UI:** `Everyone from <workspace name>`
>
> **Purpose:**
> Provides convenient access management for all users associated with a workspace.
>
> **Automatic Behavior:**
>
> * Created automatically during workspace provisioning
> * Cannot be edited, deleted, or duplicated
> * Users automatically added when granted workspace access (direct or through another group)
> * Users automatically removed when workspace access is revoked
> * Pre-selected by default when creating new projects/libraries
> * Appears in user/group search results when granting project access
>
> **Common Use Cases:**
>
> * Grant all workspace members read access to reference projects
> * Provide baseline visibility across all workspace projects
> * Simplify onboarding by giving new users automatic access to shared resources
> * Create workspace-wide announcements or shared libraries
>
> **Example:**
>
> ```
> Workspace: "Product Development"
> Auto-created group: "all_users_product_development"
> Display name: "Everyone from Product Development"
> ```
>
> When creating a new project in "Product Development" workspace, the group "Everyone from Product Development" appears pre-selected, allowing immediate assignment of a role (viewer, editor, etc.) to all workspace members.

> [!WARNING]
>
> **Cannot Exclude Individual Members**
>
> The "Everyone in workspace" group includes ALL workspace members without exception. You cannot:
>
> * Remove specific users from this group
> * Create exceptions or exclusions
> * Modify group membership manually
>
> If you need selective access, create custom groups for specific teams or roles.

### Custom groups

> [tab] Creating Groups
>
> #### When to create custom groups
>
> Create custom groups when you need:
>
> * Team-based access (e.g., "Development Team", "QA Team")
> * Role-based access (e.g., "Senior Developers", "Stakeholders")
> * Project-specific access (e.g., "Project Alpha Team")
> * Cross-functional teams (e.g., "Release Management", "Architecture Board")
>
> #### Group creation best practices
>
> **1. Plan group structure**
>
> Identify natural team boundaries and access patterns before creating groups.
>
> **Good Examples:**
>
> * `dev_team_frontend`
> * `stakeholders_finance_dept`
> * `project_phoenix_core_team`
>
> **Poor Examples:**
>
> * `random_users`
> * `temp_group_1`
> * `johns_team` (too specific, not transferable)
>
> **2. Use descriptive names**
>
> Group names should clearly indicate purpose and membership.
>
> **Naming Convention:**
> `[function]_[department/project]_[sub-group]`
>
> **Examples:**
>
> * `developers_mobile_ios`
> * `viewers_executive_leadership`
> * `editors_project_migration`
>
> **3. Document group purpose**
>
> Add clear descriptions explaining:
>
> * Who should be members
> * What access the group provides
> * When to use the group for access grants
>
> **4. Assign appropriate permissions**
>
> Grant groups workspace-level roles, then use groups when assigning project access:
>
> ```
> 1. Create group: "Mobile Development Team"
> 2. Add members: All mobile developers
> 3. Grant workspace role: workspace_user
> 4. Use group for project access: Grant project_editor to "Mobile Development Team" on mobile projects
> ```

> [tab] Managing Groups
>
> #### Group lifecycle management
>
> **Adding Members:**
>
> * Add users individually
> * Bulk import from CSV
> * Integrate with identity provider groups (if configured)
>
> **Removing Members:**
>
> * Individual removal
> * Automatic removal when user leaves workspace
> * Bulk update operations
>
> **Modifying Groups:**
>
> * Update group name and description
>
> * Change group membership
>
> * Review and audit group access
>
> > [!WARNING]
> >
> > **Deleting Groups Impact**
> >
> > Deleting a group:
> >
> > * Removes all access granted through that group
> > * Does NOT delete the users themselves
> > * Cannot be undone
> > * May leave users without expected access
> >
> > Always verify group usage before deletion:
> >
> > 1. Check which projects use the group
> > 2. Identify affected users
> > 3. Plan alternative access methods
> > 4. Communicate changes to affected users

> [tab] Group Strategies
>
> #### Access patterns using groups
>
> **Pattern 1: Hierarchical Teams**
>
> ```
> all_users_product_development (workspace)
> ├── team_backend_developers
> ├── team_frontend_developers
> ├── team_qa_engineers
> └── team_product_owners
> ```
>
> Each sub-group receives different project roles based on responsibilities.
>
> **Pattern 2: Project-Based Groups**
>
> ```
> project_alpha_core_team → project_editor
> project_alpha_stakeholders → project_viewer
> project_alpha_devops → project_editor + workspace_runtime_editor
> project_alpha_operations → project_viewer + workspace_operations_editor
> ```
>
> Groups organized around specific projects for clear access boundaries.
>
> **Pattern 3: Cross-Functional Groups**
>
> ```
> architecture_review_board → project_viewer on all projects
> release_management_team → workspace_runtime_editor
> security_team → project_viewer + audit access
> ```
>
> Groups that span multiple projects with specialized access needs.
>
> **Pattern 4: External Collaboration**
>
> ```
> external_consultants_acme → project_editor on assigned projects only
> external_auditors_bigfour → project_viewer on compliance projects
> partners_vendor_xyz → project_viewer on integration projects
> ```
>
> Separate groups for external parties with time-bound access.

### Group vs. individual assignment decision matrix

| Scenario | Use Group | Use Individual Assignment |
| - | - | - |
| 5+ users need same access | ✅ Yes | ❌ No |
| Access pattern is temporary (\< 1 month) | ❌ No | ✅ Yes |
| Access follows team structure | ✅ Yes | ❌ No |
| One-off exception for specific user | ❌ No | ✅ Yes |
| Access will change frequently | ❌ No | ✅ Yes |
| Multiple projects need same team access | ✅ Yes | ❌ No |
| Executive/stakeholder with unique access | ❌ No | ✅ Yes |
| New team being formed | ✅ Yes | ❌ No |

## Troubleshooting permission issues

> [!NOTE]
>
> Common permission-related issues and their solutions. Use this guide to quickly diagnose and resolve access problems.

### Common error scenarios

> [accordion] Error: "Cannot see Projects menu"
>
> **Symptoms:**
>
> * Projects menu entry not visible
> * Workspace appears empty
> * Cannot navigate to any projects
>
> **Possible Causes:**
>
> 1. No workspace access granted
> 2. Missing `workspace_read` permission
> 3. Not a member of any workspace
>
> **Solutions:**
>
> **1. Verify workspace membership**
>
> Check if user has been granted access to the workspace:
>
> * Contact workspace administrator
> * Verify user appears in workspace Users list
> * Check group membership if access is group-based
>
> **2. Confirm workspace role**
>
> User needs at minimum `workspace_user` role:
>
> * Review user's assigned roles in workspace
> * Verify `workspace_read` permission is included
> * If missing, workspace admin should assign appropriate role
>
> **3. Clear cache and re-login**
>
> Sometimes permissions don't update immediately:
>
> * Log out of FlowX Designer
> * Clear browser cache
> * Log back in
> * Check if Projects menu now appears

> [accordion] Error: "Can see project but cannot edit"
>
> **Symptoms:**
>
> * Project appears in list
> * Can open project but all controls disabled
> * Configure shows as "View" instead
> * No Save buttons visible
>
> **Possible Causes:**
>
> 1. Have `project_viewer` role instead of `project_editor`
> 2. Have read-only permissions on project
> 3. Project is locked or archived
>
> **Solutions:**
>
> **1. Check project role**
>
> Verify assigned project role:
>
> * Open project
> * Look for edit controls (should be hidden if viewer)
> * Check contextual menu (Configure vs View)
>
> **2. Request role upgrade**
>
> Contact project owner to grant edit access:
>
> * Identify project owner (automatic creator or transferred owner)
> * Request `project_editor` role
> * Provide business justification for edit access
>
> **3. Verify project status**
>
> Ensure project is active:
>
> * Check if project is archived
> * Verify project version is editable
> * Confirm no system locks in place

> [accordion] Error: "Cannot create builds"
>
> **Symptoms:**
>
> * No "Create build" button visible
> * Import build action missing
> * Runtime menu entries not accessible
>
> **Possible Causes:**
>
> 1. Missing `wks_builds_create` permission
> 2. Don't have `workspace_runtime_editor` role
> 3. Workspace-level runtime access not granted
>
> **Solutions:**
>
> **1. Request runtime access**
>
> Contact workspace administrator:
>
> * Explain need for build creation
> * Request `workspace_runtime_editor` role
> * Alternative: Request specific `wks_builds_create` permission
>
> **2. Understand scope change**
>
> Note that runtime permissions moved to workspace level in v5.0:
>
> * Old: Per-project runtime access
> * New: Workspace-wide runtime access
> * May need different permission strategy

> [accordion] Error: "User added to group but still no access"
>
> **Symptoms:**
>
> * User appears in group membership list
> * User still cannot access expected resources
> * Group-based permissions not applying
>
> **Possible Causes:**
>
> 1. Group not assigned to project
> 2. Group has insufficient permissions
> 3. Permission cache not refreshed
> 4. Individual permission overrides group
>
> **Solutions:**
>
> **1. Verify group assignments**
>
> Check where group is used:
>
> * Check project-level access for group
> * Verify group has appropriate roles assigned
>
> **2. Check permission hierarchy**
>
> Understand permission precedence:
>
> * Individual permissions may override group
> * Multiple groups combine permissions
> * A user's permissions in the context of a project is the reunion of their permissions given though groups or individual assignments
>
> **3. Force refresh**
>
> Clear permission cache:
>
> * User logs out completely
> * Clear browser cache and cookies
> * User logs back in
> * Permissions should refresh from backend
>
> **4. Review group role**
>
> Ensure group has correct role:
>
> * Check group's workspace-level role
> * Verify group's project-level role
> * Confirm role includes needed permissions

> [accordion] Error: "Project owner left, cannot manage access"
>
> **Symptoms:**
>
> * Original project owner no longer with organization
> * Cannot grant/revoke project access
> * Project governance blocked
>
> **Possible Causes:**
>
> 1. Project ownership not transferred
> 2. No other users have admin rights on project
> 3. Workspace admin access not configured
>
> **Solutions:**
>
> **1. Contact workspace administrator**
>
> Workspace admin can help:
>
> * Has `projects_admin` permission
> * Can grant access to projects
> * Can help identify new owner
>
> **2. Transfer project ownership**
>
> Workspace admin or org admin can:
>
> * Assign new project owner
> * Transfer governance rights
> * Update project documentation
>
> **3. Prevent future issues**
>
> Implement ownership best practices:
>
> * Always have 2+ users with project\_editor minimum
> * Document ownership succession plan
> * Review project ownership quarterly
> * Assign workspace admin as backup owner for critical projects

## Best practices summary

> [card] Start Conservative
>
> Begin with `project_viewer` or `workspace_user` and escalate as needed based on demonstrated needs

> [card] Use Groups
>
> Create and use groups for teams and functions rather than managing individual user access

> [card] Regular Reviews
>
> Quarterly access reviews, remove inactive users, validate permissions match responsibilities

> [card] Document Decisions
>
> Maintain records of role assignments, especially for elevated privileges and exceptions

> [card] Use Automation
>
> Use group memberships and role inheritance to reduce manual access management

> [card] Plan for Transitions
>
> Have clear processes for role changes, project ownership transfers, and access removal

## Keycloak roles vs Designer roles

FlowX uses two separate role systems. Understanding the difference prevents common confusion:

| Aspect | Keycloak realm roles | FlowX Designer roles |
| - | - | - |
| **Managed in** | Keycloak Admin Console | FlowX Designer (Workspaces) |
| **Purpose** | Service authentication, runtime process access | Designer UI access, project permissions |
| **Assigned to** | Users and service accounts | Users and groups within workspaces |
| **Examples** | `SA_FLOWX`, `default-roles-flowx` | `org_admin`, `workspace_admin`, `project_editor` |

### Keycloak realm roles quick reference

| Role | Purpose | Who needs it |
| - | - | - |
| `SA_FLOWX` | Service account role. Identifies FlowX platform services for inter-service communication. | Service accounts only, not human users |
| `default-roles-flowx` | Default realm role automatically assigned to new users in the FlowX Keycloak realm. | All users (assigned automatically) |

> [!NOTE]
>
> In FlowX 4.x, roles like `FLOWX_ADMIN`, `FLOWX_CONFIGURATOR`, and `FLOWX_VIEWER` were Keycloak realm roles that controlled Designer access. In FlowX 5.0+, these have been replaced by the Designer role system (workspace\_admin, project\_editor, etc.). See the [legacy role migration](/5.9/setup-guides/access-management/workspaces-access-rights#legacy-role-migration) for the full conversion table.

> [!WARNING]
>
> Do not confuse Keycloak realm roles with FlowX Designer roles. Assigning a user `workspace_admin` in Keycloak has no effect — it must be assigned through the FlowX Designer interface. Keycloak only handles authentication (login), while Designer handles authorization (what you can access).

***

## Related documentation

> [card] [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights)
>
> Overview of FlowX workspace access rights and role hierarchy

> [card] [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> Detailed permission matrices for all FlowX roles

> [card] [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide)
>
> Technical implementation details, UI mappings, and naming conventions

> [card] [Access Management Overview](/5.9/setup-guides/access-management/access-management-overview)
>
> Overview of FlowX access management system

> [card] [Configuring IAM Solution](/5.9/setup-guides/access-management/configuring-an-iam-solution)
>
> Setting up identity and access management

> [card] [Workspaces](/5.9/docs/projects/workspaces)
>
> Understanding workspaces and organizing projects


# Complete roles & permissions matrix
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/roles-permissions-matrix

Detailed permission matrices for all FlowX roles across organization, workspace, and project levels

> [!NOTE]
>
> **Documentation Navigation:**
>
> * [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights) - Role overview and concepts
> * **Complete Permissions Matrix** (Current) - Detailed permission specifications
> * [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide) - Technical implementation details
> * [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide) - Practical scenarios and best practices

> [!NOTE]
>
> This page provides comprehensive permission matrices for all predefined roles in FlowX. Use this as a reference when planning access control strategies.

## How to use this reference

**1. Identify the role level**

Determine whether you need organization, workspace, or project-level access

**2. Find the appropriate role**

Review the role descriptions and select the one matching your requirements

**3. Verify permissions**

Check the detailed permission matrix to ensure it meets your needs

**4. Implement access control**

Assign roles according to the principle of least privilege

## Permission legend

The permission matrices use the following symbols:

| Symbol | Meaning |
| - | - |
| ✅ | Permission is assigned |
| ❌ | Permission is not assigned |
| ⬜ | Permission is not available for this context |

## Organization level permissions

### Organization admin permission matrix

The `org_admin` role has the following permissions:

> [tab] Organization Administration
>
> | Resource | Read | Edit | Create | Delete | Admin | Comments |
> | - | - | - | - | - | - | - |
> | Organization | ⬜ | ✅ | ⬜ | ⬜ | ⬜ | Organization settings management |
> | Workspaces | ✅ | ✅ | ✅ | ✅ | ✅ | Complete workspace lifecycle control |
> | Users | ✅ | ✅ | ✅ | ✅ | ⬜ | Organization user management |
> | Groups | ✅ | ✅ | ✅ | ✅ | ⬜ | User group management |

> [tab] System Management
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Out of office | ✅ | ✅ | ✅ | ✅ | Out of office policy management |
> | Fonts | ✅ | ✅ | ✅ | ✅ | Global font resource management |
> | AI providers | ✅ | ✅ | ⬜ | ⬜ | Gated by `org_ai_providers_read` / `org_ai_providers_edit`. Controls the AI Settings nav entry, Model Providers, and Defaults & Fallbacks pages in the organization admin space. |

> [tab] Monitoring & Audit
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Audit logs | ✅ | ❌ | ❌ | ❌ | Read-only access to system audit |
> | Platform status | ✅ | ❌ | ❌ | ❌ | System health monitoring |
> | Org Env Info | ⚠️ | ⚠️ | ❌ | ❌ | *Deprecated in 5.7.0.* Manual Configure Environment Info form removed; permission retained for backward compatibility but no longer surfaces a UI entry point. |
> | Org Audit log | ✅ | ❌ | ❌ | ❌ | Organization-specific audit access |

> [tab] End-user Management
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Runtime users | ✅ | ✅ | ✅ | ✅ | Manage end users at the organization level (`org_runtime_users_*`) |
> | Runtime groups | ✅ | ✅ | ✅ | ✅ | Manage end-user groups (`org_runtime_groups_*`) |
> | Runtime roles | ✅ | ✅ | ✅ | ✅ | Manage end-user roles (`org_runtime_roles_*`) |
> | Runtime projects | ✅ | ⬜ | ⬜ | ⬜ | Read-only visibility of runtime projects (`org_runtime_projects_read`) |
>
> For details on end-user (runtime) access management, see the [End-user access management](/5.9/setup-guides/access-management/end-user-access-management) guide.

> [card] Organization Admin Role Constraints
>
> **Management Rules:**
>
> * Cannot be edited, duplicated, or deleted
> * Can only be assigned in the Organization admin space
> * Hidden from workspace role lists
> * Cannot be assigned at workspace level
> * Must be assigned to at least one user during initial setup

### Organization owner permission matrix

The `Organization Owner` is a predefined organization-level role focused on account, dashboard, usage, and end-user (runtime) administration. It is **not** interchangeable with Organization Admin: managing Designer users, workspaces, and Designer roles, including promoting another user to organization admin, requires the [Organization Admin](#organization-admin-permission-matrix) role.

| Capability | Organization Owner | Notes |
| - | - | - |
| Organization dashboard | ✅ | Read access to the organization dashboard |
| Account settings | ✅ | Manage the organization account |
| Usage statistics | ✅ | View organization usage |
| End-user (runtime) users, groups, roles | ✅ | Full management of end-user access (`org_runtime_*`) |
| Runtime projects | ✅ | Read-only visibility |
| Designer users | ❌ | Cannot view or manage Designer users, or promote org admins |
| Workspaces | ❌ | Cannot create or manage workspaces |
| Designer roles & groups | ❌ | Cannot manage Designer-level roles or groups |

> [card] Organization Owner Role Constraints
>
> **Management Rules:**
>
> * Predefined organization-level role
> * Focused on account and end-user administration, not Designer platform administration
> * For Designer user, workspace, and role management, use the Organization Admin role

## Workspace level permissions

### Workspace admin permission matrix

The `workspace_admin` role has the following permissions:

> [tab] Workspace Entities
>
> | Resource | Read | Edit | Create | Admin | Delete | Comments |
> | - | - | - | - | - | - | - |
> | Projects & libraries | ⬜ | ⬜ | ✅ | ✅ | ⬜ | Can create projects and has admin rights on projects/libraries in the workspace (even without being given explicit access) |
> | Fonts | ✅ | ✅ | ✅ | ⬜ | ✅ | Can see all Fonts available for the workspace but is not allowed to edit or add new ones |
> | Global media library | ✅ | ✅ | ✅ | ⬜ | ✅ | Can add new Global media files as well as edit/delete all Global media files available for the workspace |
> | Themes | ✅ | ✅ | ✅ | ⬜ | ✅ | Can add new themes as well as edit/delete all themes available for the workspace |
> | Workspace audit logs | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | Can see and filter all audit logs for that workspace |
> | AI models | ✅ | ✅ | ⬜ | ⬜ | ⬜ | Gated by `wks_ai_models_read` / `wks_ai_models_edit`. Controls workspace-level AI model assignments (defaults, fallbacks) per workspace type. |

> [tab] Runtime Entities
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Workspace builds | ✅ | ⬜ | ✅ | ⬜ | Can create a build for any project/library, as well as see and run all builds within the workspace |
> | Workspace active policy | ✅ | ✅ | ⬜ | ⬜ | Can add a new active policy override as well as see and edit the active policy and its overrides on all projects/libraries in the workspace |
> | Scheduled processes | ✅ | ✅ | ⬜ | ✅ | Can see all scheduled processes on all projects/libraries in the workspace as well as enable/disable them |
> | Configuration parameters overrides | ✅ | ✅ | ✅ | ✅ | Can add new configuration parameters overrides as well as see all overrides on all projects/libraries in the workspace |
> | Process instances | ✅ | ✅ | ⬜ | ⬜ | Can see and filter all process instances on all projects/libraries in the workspace |
> | Tasks | ✅ | ⬜ | ⬜ | ⬜ | Can see and filter all tasks available for them on all projects/libraries in the workspace |
> | Operations | ✅ | ✅ | ✅ | ✅ | Can create, view, edit, and delete all operations within the workspace (migration & move token) |
> | Process variables | ⬜ | ✅ | ⬜ | ⬜ | Can edit process variables on all projects/libraries in the workspace |

> [tab] Access Management
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Workspace management | ✅ | ✅ | ⬜ | ⬜ | Permission added so that the user can see the resources he creates or is assigned to |
> | Users | ✅ | ✅ | ✅ | ✅ | Can see and modify all users assigned to the workspace, as well as their groups and access within the current workspace |
> | Workspace groups | ✅ | ✅ | ✅ | ✅ | Can add new groups as well as edit/delete all groups available for the workspace |
> | Workspace roles | ✅ | ✅ | ✅ | ✅ | Complete workspace role management |
> | Workspace platform status | ✅ | ⬜ | ⬜ | ⬜ | Can see and export the Platform status details |
> | Workspace environment information | ⚠️ | ⬜ | ⬜ | ⬜ | *Deprecated in 5.7.0.* Environment Info UI removed; permission retained for backward compatibility. |

> [card] Workspace Admin Role Constraints
>
> **Management Rules:**
>
> * Cannot be edited or deleted (predefined role)
> * Listed in workspace role management interfaces
> * Can be assigned to users/groups within the workspace
> * Can be assigned when granting access to workspace
> * Cannot manage organization-wide settings

### Workspace user permission matrix

The `workspace_user` role has the following permissions:

> [tab] Workspace Entities
>
> | Resource | Read | Edit | Create | Admin | Delete | Comments |
> | - | - | - | - | - | - | - |
> | Projects & libraries | ⬜ | ⬜ | ✅ | ⬜ | ⬜ | Can create projects, can edit and see projects/libraries they are given explicit access to or where they are owners. See [Project level](#project-level-permissions) permissions for more details. |
> | Fonts | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | Can see all Fonts available for the workspace but is not allowed to edit or add new ones |
> | Global media library | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | Is able to view all global media files, but is not allowed to edit or add new files |
> | Themes | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | Can see all Themes available for the workspace but is not allowed to edit or add new ones |
> | Workspace audit logs | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | Can see and filter all audit logs for that workspace |

> [tab] Runtime Entities
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Workspace builds | ✅ | ⬜ | ⬜ | ⬜ | Can see and run all builds on projects/libraries they create or they are given explicit access to |
> | Workspace active policy | ✅ | ⬜ | ⬜ | ⬜ | Can see the active policy and its overrides on projects/libraries they create or they are given explicit access to |
> | Scheduled processes | ✅ | ⬜ | ⬜ | ⬜ | Can see all scheduled processes on projects/libraries they create or they are given explicit access to |
> | Configuration parameters overrides | ✅ | ⬜ | ⬜ | ⬜ | Can see all configuration parameters overrides on projects/libraries they create or they are given explicit access to |
> | Process instances | ✅ | ✅ | ⬜ | ⬜ | Can see and filter all process instances on projects/libraries they create or they are given explicit access to |
> | Tasks | ✅ | ⬜ | ⬜ | ⬜ | Can see and filter all tasks available for them on projects/libraries they create or they are given explicit access to |
> | Operations | ⬜ | ⬜ | ⬜ | ⬜ | No access to operations (migration & move token); requires the operations editor role (on SaaS 5.13: Workspace corrective actions editor) |
> | Process variables | ⬜ | ✅ | ⬜ | ⬜ | Can edit process variables on projects/libraries they create or are given explicit access to |

> [tab] Access Management
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Workspace management | ✅ | ⬜ | ⬜ | ⬜ | Permission added so that the user can see the resources he creates or is assigned to |
> | Users | ✅ | ⬜ | ⬜ | ⬜ | Can see all users assigned to the workspace, as well as their groups and access within the current workspace |
> | Workspace groups | ✅ | ⬜ | ⬜ | ⬜ | View workspace groups but can't manage |
> | Workspace roles | ✅ | ⬜ | ⬜ | ⬜ | View workspace roles but can't manage |
> | Workspace platform status | ✅ | ⬜ | ⬜ | ⬜ | Can see and export the Platform status details |
> | Workspace environment information | ⚠️ | ⬜ | ⬜ | ⬜ | *Deprecated in 5.7.0.* Environment Info UI removed; permission retained for backward compatibility. |

> [card] Workspace User Role Constraints
>
> **Management Rules:**
>
> * Cannot be edited or deleted (predefined role)
> * Can be duplicated to create custom variations (future feature)
> * Default role for most workspace members
> * Can be assigned when granting access to workspace
> * Limited administrative capabilities

### Theme editor permission matrix

The `theme_editor` role extends `workspace_user` with additional permissions:

> [tab] Additional Permissions
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Fonts | ✅ | ✅ | ✅ | ✅ | Can see all Fonts available for the workspace but is not allowed to edit or add new ones |
> | Global media library | ✅ | ✅ | ✅ | ✅ | Can add new Global media files as well as edit/delete all Global media files available for the workspace |
> | Themes | ✅ | ✅ | ✅ | ✅ | Can add new themes as well as edit/delete all themes available for the workspace |

> [tab] Inherited from workspace\_user
>
> All other permissions are inherited from the `workspace_user` role. See the workspace user permission matrix above for complete details.

> [card] Theme Editor Role Constraints
>
> **Management Rules:**
>
> * Same base constraints as `workspace_user`
> * Cannot be edited or deleted (predefined role)
> * Can be duplicated to create custom variations (future feature)
> * Specialized role for UI/UX designers and brand managers

### Workspace runtime editor permission matrix

The `workspace_runtime_editor` role extends `workspace_user` with additional permissions:

> [tab] Additional Runtime Permissions
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Workspace builds | ✅ | ⬜ | ✅ | ⬜ | Can create a build for any project/library, as well as see and run all builds within the workspace |
> | Workspace active policy | ✅ | ✅ | ⬜ | ⬜ | Can add a new active policy override as well as see and edit the active policy and its overrides on all projects/libraries in the workspace |
> | Scheduled processes | ✅ | ✅ | ⬜ | ✅ | Can see all scheduled processes on all projects/libraries in the workspace as well as enable/disable them |
> | Configuration parameters overrides | ✅ | ✅ | ✅ | ✅ | Can add new configuration parameters overrides as well as see all overrides on all projects/libraries in the workspace |
> | Process instances | ✅ | ✅ | ⬜ | ⬜ | Can see and filter all process instances on all projects/libraries in the workspace |
> | Tasks | ✅ | ⬜ | ⬜ | ⬜ | Can see and filter all tasks available for them on all projects/libraries in the workspace |
> | Operations | ⬜ | ⬜ | ⬜ | ⬜ | No access to operations (migration & move token); requires the operations editor role (on SaaS 5.13: Workspace corrective actions editor) |
> | Process variables | ⬜ | ✅ | ⬜ | ⬜ | Can edit process variables on all projects/libraries in the workspace |

> [tab] Inherited from workspace\_user
>
> All other permissions are inherited from the `workspace_user` role. See the workspace user permission matrix above for complete details.

> [card] Runtime Editor Role Constraints
>
> **Management Rules:**
>
> * Same base constraints as `workspace_user`
> * Cannot be edited or deleted (predefined role)
> * Can be duplicated to create custom variations (future feature)
> * Specialized role for DevOps and runtime environment administrators

### Workspace operations editor permission matrix

On SaaS (5.13), this role is replaced by the [Workspace corrective actions editor](#workspace-corrective-actions-editor-permission-matrix).&#x20;

The `workspace_operations_editor` role extends `workspace_user` with additional permissions:

> [tab] Additional Operations Permissions
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Process instances | ✅ | ✅ | ⬜ | ⬜ | Can see and filter all process instances on all projects/libraries in the workspace |
> | Operations | ✅ | ✅ | ✅ | ✅ | Can create, view, edit, and delete all operations within the workspace (migration & move token) |
> | Process variables | ⬜ | ✅ | ⬜ | ⬜ | Can edit process variables on all projects/libraries in the workspace |

> [tab] Inherited from workspace\_user
>
> All other permissions are inherited from the `workspace_user` role. See the workspace user permission matrix above for complete details.

> [card] Operations Editor Role Constraints
>
> **Management Rules:**
>
> * Same base constraints as `workspace_user`
> * Cannot be edited or deleted (predefined role)
> * Can be duplicated to create custom variations (future feature)
> * Specialized role for operations management (process migration & token operations)

### Workspace corrective actions editor permission matrix

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

The **Workspace corrective actions editor** role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically. The role extends `workspace_user` with these permissions:

> [tab] Additional Corrective Actions Permissions
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Process instances | ✅ | ✅ | ⬜ | ⬜ | Can see and filter all process instances on all projects/libraries in the workspace |
> | Process instance corrective actions | ✅ | ⬜ | ✅ | ⬜ | Can view and run corrective actions in the workspace (migration & move token) |
> | Process instance variables | ⬜ | ✅ | ⬜ | ⬜ | Can edit process instance variables on all projects/libraries in the workspace |

> [tab] Inherited from workspace\_user
>
> All other permissions are inherited from the `workspace_user` role. See the workspace user permission matrix above for complete details.

`workspace_admin` also holds the corrective actions permissions, and organization admins have them through their workspace admin access. No other predefined role includes them.

## Project level permissions

### Project owner permission matrix

The `project_owner` role has the following permissions:

> [tab] Project Administration
>
> | Resource | Read | Edit | Create | Delete | Admin/Owner | Comments |
> | - | - | - | - | - | - | - |
> | Projects & Libraries | ✅ | ✅ | ⬜ | ✅ | ✅ | Has admin rights on all projects/libraries in the workspace he is the owner of |

> [tab] Configuration Resources
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Processes | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Project data model | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Enumerations | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Media library & Document Intelligence | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Notification templates | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Document templates | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Views | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Stages | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Allocation rules | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Data Sources | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Workflow | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Reusable UI | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | UI Flows | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete UI Flows within the project (5.3+) |
> | Reusable Business Rules | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Dependencies | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Configuration parameters | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | AI agents | ⬜ | ✅ | ⬜ | ⬜ | Gated by the `aiagent_edit` permission. Controls visibility of config-time agents (AI Assistant, Analyst, Designer, Developer), the AI floating action button, the Chat UI component, and AI actions on BPMN nodes. |

> [card] Project Owner Role Constraints
>
> **Management Rules:**
>
> * System-managed role, cannot be edited or deleted
> * Automatically assigned to user who creates project
> * Hidden from role selection interfaces
> * Cannot be manually assigned through UI
> * Permanent assignment for project lifecycle
> * Can be transferred to another user (ownership transfer)

### Project editor permission matrix

The `project_editor` role has the following permissions:

> [tab] Project Management
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Projects & Libraries | ✅ | ✅ | ⬜ | ❌ | Can read and edit any project for which they are a project\_editor |

> [tab] Configuration Resources
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Processes | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Project data model | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Enumerations | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Media library & Document Intelligence | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Notification templates | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Document templates | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Views | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Stages | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Allocation rules | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Data Sources | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Workflow | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Reusable UI | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | UI Flows | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete UI Flows within the project (5.3+) |
> | Reusable Business Rules | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Dependencies | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | Configuration parameters | ✅ | ✅ | ✅ | ✅ | Can create/edit/delete all resources within the project |
> | AI agents | ⬜ | ✅ | ⬜ | ⬜ | Gated by the `aiagent_edit` permission. Same surfaces as `project_owner`. |

> [card] Project Editor Role Constraints
>
> **Management Rules:**
>
> * Cannot be edited or deleted (predefined role)
> * Can be duplicated to create custom variations (future feature)
> * Can be assigned to users/groups when granting project access
> * Standard role for project team members
> * No ownership rights (cannot grant/revoke project access)

### Project viewer permission matrix

The `project_viewer` role has the following permissions:

> [tab] Project Access
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Projects & Libraries | ✅ | ⬜ | ⬜ | ❌ | Read-only access to project and library information |

> [tab] Configuration Resources
>
> | Resource | Read | Edit | Create | Delete | Comments |
> | - | - | - | - | - | - |
> | Processes | ✅ | ❌ | ❌ | ❌ | View process definitions and workflows |
> | Project data model | ✅ | ❌ | ❌ | ❌ | Read-only access to project data structure |
> | Enumerations | ✅ | ❌ | ❌ | ❌ | View enumeration values and data structures |
> | Media library & Document Intelligence | ✅ | ❌ | ❌ | ❌ | View media assets and document intelligence configurations |
> | Notification templates | ✅ | ❌ | ❌ | ❌ | View notification template configurations |
> | Document templates | ✅ | ❌ | ❌ | ❌ | View document template configurations |
> | Views | ✅ | ❌ | ❌ | ❌ | View UI configuration definitions |
> | Stages | ✅ | ❌ | ❌ | ❌ | View process stage definitions |
> | Allocation rules | ✅ | ❌ | ❌ | ❌ | View task and resource allocation rules |
> | Data Sources | ✅ | ❌ | ❌ | ❌ | View system integrations and endpoints |
> | Workflow | ✅ | ❌ | ❌ | ❌ | View workflow definitions and configurations |
> | Reusable UI | ✅ | ❌ | ❌ | ❌ | Read-only UI component access with permission inheritance |
> | UI Flows | ✅ | ❌ | ❌ | ❌ | View UI Flows definitions (5.3+) |
> | Reusable Business Rules | ✅ | ❌ | ❌ | ❌ | Read-only function component access with permission inheritance |
> | Dependencies | ✅ | ❌ | ❌ | ❌ | View project and library dependencies |
> | Configuration parameters | ✅ | ❌ | ❌ | ❌ | View project configuration parameters |
> | AI agents | ⬜ | ❌ | ⬜ | ⬜ | `aiagent_edit` not granted. No `aiagent_read` exists, so project viewers do not see AI agent surfaces at all. |

> [card] Project Viewer Role Constraints
>
> **Management Rules:**
>
> * Cannot be edited or deleted (predefined role)
> * Can be duplicated to create custom variations (future feature)
> * Can be assigned to users/groups when granting project access
> * Safe role for stakeholders needing visibility
> * No modification capabilities
> * Can test processes and workflows through the interface

## Role comparison matrix

### Quick reference: All roles compared

| Permission Category | org\_admin | workspace\_admin | workspace\_user | theme\_editor | runtime\_editor | operations\_editor | project\_owner | project\_editor | project\_viewer |
| - | - | - | - | - | - | - | - | - | - |
| **Workspace Management** | | | | | | | | | |
| Create workspace | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Manage workspace users | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Create projects | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | N/A | N/A |
| **Theme & Media** | | | | | | | | | |
| Edit themes | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | N/A | N/A | N/A |
| Manage fonts | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | N/A | N/A | N/A |
| Edit media library | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | N/A | N/A | N/A |
| **Runtime Management** | | | | | | | | | |
| Create builds | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| Edit active policy | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| Manage config parameters | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| **Operations Management** | | | | | | | | | |
| Manage operations | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | N/A | N/A | N/A |
| Edit process instances | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| Edit process variables | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | N/A | N/A | N/A |
| **Project Configuration** | | | | | | | | | |
| Edit processes | ✅ | ✅\* | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ✅ | ❌ |
| Manage templates | ✅ | ✅\* | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ✅ | ❌ |
| Configure integrations | ✅ | ✅\* | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ✅ | ❌ |
| **Access Control** | | | | | | | | | |
| Grant project access | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| Manage workspace access | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

> [!NOTE]
>
> \* Workspace-level roles can only edit project resources for projects they have been explicitly granted access to. Having a workspace role does not automatically grant access to all projects.

## Detailed capability breakdown

### Organization-level capabilities

| Capability | org\_admin | Notes |
| - | - | - |
| **Workspace Operations** | | |
| Create new workspaces | ✅ | No limit on number of workspaces |
| Edit workspace settings | ✅ | Can modify any workspace configuration |
| Delete workspaces | ✅ | Permanent deletion with confirmation |
| View all workspaces | ✅ | Unrestricted visibility |
| **User Management** | | |
| Add organization users | ✅ | Can invite users to organization |
| Remove organization users | ✅ | Can revoke organization access |
| Assign organization roles | ✅ | Can grant org\_admin to other users |
| View all user access | ✅ | Cross-workspace user visibility |
| **System Management** | | |
| Configure organization settings | ✅ | Organization-wide policies |
| Manage global font resources | ✅ | Fonts available to all workspaces |
| Configure out of office policies | ✅ | Organization-level OOO rules |
| **Monitoring** | | |
| View all audit logs | ✅ | Organization and workspace level |
| Monitor platform status | ✅ | System health across organization |
| Access environment information | ⚠️ | *Deprecated in 5.7.0.* Configure Environment Info UI removed. |

### Workspace-level capabilities

| Capability | workspace\_admin | workspace\_user | theme\_editor | runtime\_editor | operations\_editor | Notes |
| - | - | - | - | - | - | - |
| **Project Management** | | | | | | |
| Create projects/libraries | ✅ | ✅ | ✅ | ✅ | ✅ | All workspace users can create |
| View all workspace projects | ✅ | ❌ | ❌ | ❌ | ❌ | Only admin sees all projects |
| Admin access to all projects | ✅ | ❌ | ❌ | ❌ | ❌ | Admin has implicit access |
| **User & Access Management** | | | | | | |
| Add workspace users | ✅ | ❌ | ❌ | ❌ | ❌ | Admin only |
| Remove workspace users | ✅ | ❌ | ❌ | ❌ | ❌ | Admin only |
| Create/manage groups | ✅ | ❌ | ❌ | ❌ | ❌ | Admin only |
| Assign workspace roles | ✅ | ❌ | ❌ | ❌ | ❌ | Admin only |
| **Design & Branding** | | | | | | |
| Create themes | ✅ | ❌ | ✅ | ❌ | ❌ | Admin and theme editor |
| Edit themes | ✅ | ❌ | ✅ | ❌ | ❌ | Admin and theme editor |
| Delete themes | ✅ | ❌ | ✅ | ❌ | ❌ | Admin and theme editor |
| Manage fonts | ✅ | ❌ | ✅ | ❌ | ❌ | Admin and theme editor |
| Manage media library | ✅ | ❌ | ✅ | ❌ | ❌ | Admin and theme editor |
| **Runtime Operations** | | | | | | |
| Create builds | ✅ | ❌ | ❌ | ✅ | ❌ | Admin and runtime editor |
| Edit active policies | ✅ | ❌ | ❌ | ✅ | ❌ | Admin and runtime editor |
| Manage scheduled processes | ✅ | ❌ | ❌ | ✅ | ❌ | Admin and runtime editor |
| Manage config param overrides | ✅ | ❌ | ❌ | ✅ | ❌ | Admin and runtime editor |
| **Operations Management** | | | | | | |
| Edit process instances | ✅ | ❌ | ❌ | ✅ | ✅ | Admin, runtime editor, and operations editor; project owners and editors in their projects |
| Edit process variables | ✅ | ❌ | ❌ | ❌ | ✅ | Admin and operations editor |
| Manage operations | ✅ | ❌ | ❌ | ❌ | ✅ | Admin and operations editor |
| Create operations | ✅ | ❌ | ❌ | ❌ | ✅ | Admin and operations editor |

### Project-level capabilities

| Capability | project\_owner | project\_editor | project\_viewer | Notes |
| - | - | - | - | - |
| **Access Control** | | | | |
| Grant project access | ✅ | ❌ | ❌ | Owner only |
| Revoke project access | ✅ | ❌ | ❌ | Owner only |
| Transfer project ownership | ✅ | ❌ | ❌ | Owner can transfer |
| **Project Administration** | | | | |
| Delete project | ✅ | ❌ | ❌ | Owner only (permanent) |
| Edit project settings | ✅ | ✅ | ❌ | Owner and editor |
| Archive project | ✅ | ❌ | ❌ | Owner only |
| **Process Design** | | | | |
| Create processes | ✅ | ✅ | ❌ | Owner and editor |
| Edit processes | ✅ | ✅ | ❌ | Owner and editor |
| Delete processes | ✅ | ✅ | ❌ | Owner and editor |
| View processes | ✅ | ✅ | ✅ | All roles can view |
| Test processes | ✅ | ✅ | ✅ | All roles can test |
| **Configuration** | | | | |
| Manage enumerations | ✅ | ✅ | ❌ | Owner and editor |
| Configure templates | ✅ | ✅ | ❌ | Owner and editor |
| Set up integrations | ✅ | ✅ | ❌ | Owner and editor |
| Manage workflows | ✅ | ✅ | ❌ | Owner and editor |
| Configure UI components | ✅ | ✅ | ❌ | Owner and editor |
| **Runtime** | | | | |
| Create builds | ✅ | ✅ | ❌ | Owner and editor |
| Manage active policies | ✅ | ✅ | ❌ | Owner and editor |
| View runtime status | ✅ | ✅ | ✅ | All roles |
| **Export & Audit** | | | | |
| Export project | ✅ | ✅ | ❌ | Owner and editor |
| View audit logs | ✅ | ✅ | ✅ | All roles |

## Permission inheritance patterns

### Workspace to project inheritance

> [!NOTE]
>
> Understanding how workspace roles interact with project roles is critical for proper access management.

**Key Principles:**

1. **Workspace roles DO NOT automatically grant project access**
   * A user with `workspace_admin` still needs explicit project role to access specific projects
   * Exception: `workspace_admin` can grant themselves access via admin privileges
   * Exception: Users with `projects_admin` permission (included in `workspace_admin`) automatically receive `project_owner` capabilities on all projects in that workspace

2. **Project roles are additive to workspace permissions**
   * User can have `workspace_user` + `project_editor` on specific project
   * Permissions combine (union), not override

3. **Most permissive permission wins**
   * If user has `project_viewer` via one group and `project_editor` via another, they get editor access

4. **Multiple workspace roles can be assigned simultaneously**
   * Users can combine workspace roles for specialized access patterns
   * Example: A user can be both `theme_editor` and `runtime_editor` in the same workspace
   * Permissions from all assigned roles combine (union), enabling flexible role compositions

**Examples:**

```
Scenario 1: Workspace User Creates Project
- User role: workspace_user
- Action: Creates new project "Project X"
- Result: User automatically becomes project_owner of "Project X"

Scenario 2: Workspace Admin Needs Project Access
- User role: workspace_admin
- Action: Wants to edit "Project Y" (not owner)
- Required: Must be granted project_editor or project_owner role on "Project Y"
- Note: Admin can grant themselves this access via admin privileges

Scenario 3: Multiple Role Assignments
- User role: workspace_user
- Project roles: project_viewer on "Project A", project_editor on "Project B"
- Result: Read-only access to Project A, full edit access to Project B

Scenario 4: Mix and Match Roles (Development Environment)
- User roles: theme_editor + runtime_editor
- Context: Development/QA environments where designers and developers need combined access
- Combined capabilities:
  - Full theme management (fonts, media library, theme creation/editing) from theme_editor
  - Runtime operations (create builds, edit policies, manage scheduled processes, config parameters) from runtime_editor
  - Base workspace capabilities (create projects, view workspace resources) from workspace_user inheritance
- Use case: UI/UX developers working in dev environments who need both design and deployment capabilities

Scenario 5: Operations Editor Role
- User role: operations_editor
- Context: Users who need to manage process operations without full runtime access
- Capabilities:
  - Full operations management (migration & move token) across the workspace
  - Edit process instances and process variables
  - Base workspace capabilities (create projects, view workspace resources) from workspace_user inheritance
- Use case: Support engineers or operations teams managing process migrations and token movements
```

### Group-based permission inheritance

**Group Membership Resolution:**

1. User's permissions = Union of (individual permissions + all group permissions)
2. More permissive permission always wins
3. No negative permissions (cannot restrict via groups)

**Example:**

```
User: John
- Individual: project_viewer on Project X
- Group A membership: project_editor on Project X
- Group B membership: workspace_runtime_editor

Result:
- Project X access: project_editor (more permissive than viewer)
- Workspace: workspace_runtime_editor capabilities
- Combined: Full project editing + runtime management
```

## Special permission features

### Read-only view behavior

> [card] Read-Only Mode Characteristics
>
> When a user has read-only permissions (e.g., `project_viewer` role), they experience:
>
> **Visible but Disabled:**
>
> * All configuration elements visible but not editable
> * Save buttons hidden or disabled
> * Edit controls grayed out or absent
> * Delete actions not available
>
> **Available Functionality:**
>
> * Export operations (where applicable)
> * Audit log access
> * Usage overview and tracking
> * Copy operations to other projects/libraries (for reference)
> * Process and workflow testing through interface
>
> **UI Indicators:**
>
> * "View" label instead of "Configure" in contextual menus
> * Read-only badges or indicators
> * No modification prompts or warnings

### Bulk permission selection

> [!NOTE]
>
> When configuring custom roles (future feature), bulk selection simplifies permission assignment.

**Bulk Selection Categories:**

| Category | Applies To | Selectable Operations |
| - | - | - |
| **Workspace Entities** | Projects, Themes, Fonts, Media, Audit Logs | Read, Edit, Create, Delete |
| **Access Management** | Users, Groups, Roles, Platform Status | Read, Edit, Create, Delete |
| **Runtime Permissions** | Builds, Policies, Processes, Config Params | Read, Edit, Create, Delete |
| **Project Configuration** | All project resources | Read, Edit, Create, Delete |

**How Bulk Selection Works:**

1. Select permission category (e.g., "Workspace Entities")
2. Choose operation level (e.g., "Read")
3. All resources in category receive selected permission
4. Individual permissions can be adjusted afterward
5. Saves time when creating roles with consistent patterns

### Permission dependencies

> [card] Auto-Included Permissions
>
> Certain permissions automatically include others to ensure functionality:
>
> **Workspace Level:**
>
> * Any workspace permission → automatically includes `workspace_read`
> * Any workspace edit permission → should include `workspace_edit`
>
> **Project Level:**
>
> * Any project permission → automatically includes `project_read` (backend)
> * Note: `project_read` not displayed in UI but sent to backend
>
> **Rationale:**
> Read permissions provide the foundation for all other operations. Without read access, users cannot see resources to edit, create, or delete them.

## Related documentation

> [card] [Workspaces Access Rights](/5.9/setup-guides/access-management/workspaces-access-rights)
>
> Overview of FlowX workspace access rights and role hierarchy

> [card] [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide)
>
> Technical implementation details, UI mappings, and naming conventions

> [card] [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide)
>
> Practical guidance for choosing and assigning appropriate roles

> [card] [Access Management Overview](/5.9/setup-guides/access-management/access-management-overview)
>
> Overview of authentication and authorization in FlowX

> [card] [Configuring IAM Solution](/5.9/setup-guides/access-management/configuring-an-iam-solution)
>
> Setting up identity and access management with Keycloak

> [card] [Workspaces](/5.9/docs/projects/workspaces)
>
> Understanding workspaces and organizing projects


# Runtime authorization
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/runtime-authorization

Project-scoped roles, end-user groups, and solution sharing for controlling who can access a published FlowX solution at runtime.

***

## Overview

On FlowX.AI 5.1.x, an end-user role granted access to **every** project and workspace where that role appeared. Enterprise customers needed finer granularity: "this role on this solution, not on every other solution that happens to use the same role name."

5.9.x changes the assignment model. The role itself is still organization-level (defined once, reusable across projects). What's new is **where the role is granted**: on a specific project, through the **Share** modal on a solution.

| 5.1.x | 5.9.x |
| - | - |
| Role assigned **directly to user** at organization level | Role assigned to user **in the context of a project** via the solution's Share modal |
| One role grants access on every project that lists it | Role grants access only on the solutions it has been explicitly shared on |
| End-user groups managed in Keycloak | End-user groups managed in **FlowX** (org-level), assigned to roles on each solution |

The role catalog is still organization-level under the hood, but roles are created from a project's **Version Settings** → **End-User Roles** tab, not from a dedicated Access Management section. See [End-user access management](./end-user-access-management) for managing end users, roles, and groups.

***

## Where roles live

> [card] Organization
>
> The role catalog. Roles are created and named once per organization and reusable across all projects and libraries.

> [card] Project version (build)
>
> Each project version carries the list of roles required at runtime. New projects spawn with a default `User` role.

> [card] Per resource
>
> On process swimlanes: which role(s) can view, execute, or self-assign tasks. On UI Flows: which role(s) can interact (UI Flows have a single "interact" permission).

> [!NOTE]
>
> **Designer-time vs runtime permissions.** FlowX uses **SpiceDB** for designer-time (build-time) permissions — who can edit which resource in the Designer. Runtime permissions are a separate, custom implementation; SpiceDB does not handle runtime checks because the volume of runtime permission evaluations made the SpiceDB latency unacceptable. Both systems coexist and don't interact at runtime.

***

## Sharing a solution

A solution becomes accessible to end users through the **Share** modal, which you open from FlowX Designer or from the generic container app.

> [!NOTE]
>
> **Where is the Solutions page?** In two places: in FlowX Designer under **Organization Settings** → **Solutions**, and in the **generic container app**, the separate runtime app that end users sign in to. Each environment runs its own container app at its own URL; if you don't have your environment's container app URL, ask your platform administrator.

### From FlowX Designer

**1. Open the Share modal**

Go to **Organization Settings** → **Solutions**. On the solution you want to share, open the row menu (**⋮**) and select **Share**. The **Who has access?** section lists the users and groups that already have access.

**2. Invite users or groups**

Click **Invite**. Under **Invite Users**, add names, emails, or groups (comma separated), select a role, and click **Invite**.

**3. Choose who can open the solution (optional)**

Under **General Access**, open the access setting. In **Share Settings**, choose **Anyone with the link** (no sign-in required) or **Only invited people**, then click **Save**. You can change this setting only when the active build has an `Anonymous` role.

### From the generic container app

**1. Open the Solutions page**

In the generic container app, open **Solutions**. Each card represents a runtime application backed by a project version.

**2. Open the Share modal**

On the solution you want to share, click **Share**. The modal shows the roles that the project version exposes at runtime, plus the search inputs for users and groups.

**3. Pick a user or group, then a role**

Type a name to search. Existing FlowX users appear in the dropdown; you can also invite a brand-new user from the same modal — the user receives a Keycloak invitation email.

Assign one role per user or group. Repeat per role to give the same user multiple roles.

**4. Save**

Sharing changes take effect for the next sign-in.

> [!WARNING]
>
> **Active Policy gotcha.** The Share modal lists only the roles available in the build set as the project's **Active Policy**. If a role is defined in a non-active build (for example, in build 2 while build 1 is active), it does not appear in the modal until that build is promoted to Active Policy.

> [!WARNING]
>
> **Sharing settings do not export between environments.** When you promote a project to a new environment or workspace, the Share modal assignments are not carried over. Re-configure sharing per environment as part of your deployment checklist.&#x20;

***

## End-user groups

Groups previously managed in Keycloak are now managed inside FlowX. Each group is a named bucket of users; you assign the group to a role on a solution rather than assigning the role to each user individually.

Manage groups under **Organization Settings** → **Access Management** → **End-Users Groups**. See [End-user access management](./end-user-access-management#end-users-groups) for the org-level group lifecycle (create, archive, search).

### End-user groups page

The End-User Groups list shows every group in the organization with a **Members** column for the current member count, so it's easy to scan a long list. Click a group to open its detail page, which has two tabs:

> [card] Members
>
> The list of end users in the group. Use the **Add Members** action to attach users (search by name or email) and remove members inline. Saving updates the group membership immediately; the next sign-in for those users picks up any solution access changes.

> [card] Solution Access
>
> The list of solutions the group is granted on, plus the role it carries on each (**Role in Solution**). Click **Add Solutions**, pick a solution, and pick the role to grant. The Active Policy of the chosen solution determines which roles appear in the role dropdown.

### Two ways to grant access

Sharing a solution with an end-user group can be done from either side; the resulting permission is the same.

| From | When to use |
| - | - |
| **Solutions page → Share modal** on a solution | When you want to set up everyone who can use a single solution in one place — typical for app owners reviewing a deployment. |
| **End-Users Groups → group → Solution Access** tab | When you want to set up everything a single group can reach — typical for onboarding a new cohort or an end-user group that spans multiple solutions. |

> [!NOTE]
>
> **Solutions with multiple roles.** When a project version exposes more than one runtime role (for example `User` and `supervisor`), both Share modal entries and Solution Access entries let you pick which role to grant to the user or group. Repeat the entry to grant the same group multiple roles on the same solution.

### Recommended patterns

> [card] Single-role solution
>
> Use the built-in **All end-users** group (FlowX creates it automatically and adds every end user to it) and grant it the `User` role on the solution. New end users get access as soon as they onboard.

> [card] Multi-role solution
>
> Create one group per role on the solution. Add users to the group that matches the access they need. Reuse groups across solutions when the same cohort needs the same access on more than one app.

***

## Designer-user bypass

A user with **Designer access to a project** can run that project at runtime without being assigned any runtime role on it.

* Auto-grants **view, execute, and self-assign** on every swimlane in the project.
* The bypass is explicit on purpose: it lets a project's designers run their own work while building, without filing themselves into the runtime role catalog.
* Designer users **cannot** test scenarios "as another runtime role." To verify role-specific behavior, create a test end-user, assign the role to that user via the Share modal, and sign in as that user.

The bypass is implemented through a `designerUser` Keycloak user attribute (boolean) auto-managed at organization provisioning. It is exposed on the access token as the `attributes.designerUser` claim so the engine can decide cheaply whether to apply runtime checks. For environments that block FlowX from administering Keycloak directly, the mapper recipe is in [Configuring an IAM solution → Designer user attribute](./configuring-an-iam-solution#designer-user-attribute).

***

## What stays in Keycloak vs FlowX

| Concern | System of record |
| - | - |
| Authentication, password policy, MFA | Keycloak |
| User attributes used by [business filters](../../docs/platform-deep-dive/user-roles-management/business-filters) | Keycloak |
| Federation with external IDPs | Keycloak |
| Runtime role catalog | FlowX |
| End-user groups | FlowX |
| Project-scoped role assignment (sharing) | FlowX |

External IDP federation (per-organization) is configured separately — see [Per-organization IDP federation](#per-organization-idp-federation) below.

***

## Per-organization IDP federation

Enterprise customers typically own their identity provider (Microsoft Entra ID, Okta, Keycloak in another tenancy, AD FS). Rather than managing those users a second time inside FlowX, you can federate the customer's IDP into the **FlowX Keycloak realm for that organization**, so end users sign in with their existing IDP credentials and FlowX picks up their group memberships automatically.

The contract between the federated IDP and FlowX is a set of namespaced claims under `attributes.*` on the FlowX-issued access token. FlowX-specific user data — group memberships, business-filter values, the designer-user flag — all flow through this `attributes` object so that downstream services have a single, predictable read path.

### Token-claim contract

The FlowX access token carries the following claims under the top-level `attributes` object:

| Claim | Type | Required | What it carries |
| - | - | - | - |
| `attributes.runtimeGroups` | multivalued string | yes (for federated logins) | List of FlowX end-user group names the user belongs to. The names must match groups defined under **Organization Settings → Access Management → End-Users Groups**. |
| `attributes.businessFilters` | multivalued string | only if the org uses business filters | Values of business-filter attributes for the user. See [Business filters](../../docs/platform-deep-dive/user-roles-management/business-filters) for how filter values gate which records a runtime user can act on. |
| `attributes.designerUser` | boolean | always present | `true` when the user has Designer access to the project; FlowX uses this to apply the [designer-user bypass](#designer-user-bypass). |
| `org_id` | string | always present | The organization realm UUID. Hardcoded by Keycloak at organization provisioning. |

> [!NOTE]
>
> **Behind these claims, on the Keycloak user record:** the `attributes.runtimeGroups` claim is fed by a user attribute named `flowxIdPGroups`; `attributes.businessFilters` is fed by `businessFilter`; `attributes.designerUser` is fed by `designerUser`. Federated logins populate these user attributes automatically through IDP mappers; manual Keycloak setups can write them directly.

### How the sync runs

The federation chain is wired with three Keycloak mappers per attribute. Group memberships are the canonical example:

1. **Source IDP claim emitter.** The customer's IDP issues a token containing whatever attribute they maintain — commonly `memberOf`, `groups`, `roles`, or a vendor-specific path.
2. **IDP-to-user-attribute mapper** (on the federated IDP instance inside the FlowX Keycloak realm). Reads the source claim and writes its value into the `flowxIdPGroups` user attribute on the FlowX-side Keycloak user record. In the demo configuration the source claim is `groupsList`, but the source name is customer-specific — you only need to make sure this mapper writes to `flowxIdPGroups`. Set **Sync Mode** to **Force** at both the federated IDP entry and on this mapper so that source-side group changes propagate on every login; the IDP-level setting controls profile resync, the mapper-level setting controls per-attribute resync, and both need to be Force for the per-login refresh customers expect.
3. **User-attribute-to-token-claim mapper** (on the `flowx-platform-authenticate` client). Reads `flowxIdPGroups` from the user record and adds it to the access token as `attributes.runtimeGroups` (multivalued, aggregated). This mapper is **not provisioned automatically**; it has to be added once per organization. See [Runtime groups attribute mapper](./configuring-an-iam-solution#runtime-groups-attribute-mapper) for the setup steps.

The exact same pattern syncs business filters: source IDP claim → `businessFilter` user attribute → `attributes.businessFilters` token claim. The first and last steps are FlowX-managed; only the middle "IDP-to-user-attribute" mapper needs per-customer configuration.

On the **first permission check** after sign-in, FlowX reads `attributes.runtimeGroups` from the token, looks up the matching FlowX end-user groups, and writes the user's membership rows into FlowX's `group_membership` table. Subsequent permission checks read from that table directly.

> [!NOTE]
>
> **Lazy sync, not push.** FlowX does not poll the source IDP and does not implement SCIM. A change to a user's groups in the source IDP only propagates after the user's current FlowX access token expires and they sign in again. Plan token lifetimes accordingly: very long lifetimes mask group changes, very short lifetimes increase auth overhead.

> [!WARNING]
>
> **Sign-out and user-deletion are partial.** Signing out in the source IDP does **not** invalidate the FlowX session. Deleting a user in the source IDP does **not** delete the user record in FlowX Keycloak; the next sign-in attempt will fail at the IDP, but the FlowX-side record persists. Both are intentional: federation maps logins, not the full user lifecycle.

***

## Deployment prerequisites

The first time the data-sync job runs against a 5.9.0 environment, it provisions FlowX-managed end-user groups and runtime roles in Keycloak. Configure Keycloak admin credentials on the data-sync job (`FLOWX_OPENID_PROVIDER`, `FLOWX_OPENID_SERVERURL`, `FLOWX_OPENID_USER`, `FLOWX_OPENID_PASSWORD`, `FLOWX_OPENID_CLIENTID`) before deploying — see [Data-sync job setup → OpenID provider configuration](../data-sync#openid-provider-configuration).

***

## Migration notes

If you upgrade from 5.1.x with existing role-on-user assignments, those assignments continue to work. New solutions and new role assignments use the project-scoped model.

End-user groups previously managed in Keycloak are created in FlowX automatically by the data-sync Liquibase migration on first boot — no manual recreation required. Confirm the migrated group list under **Organization Settings → Access Management → End-Users Groups** after the upgrade and adjust as needed.

For details on the end-user group + runtime-role transition during a 5.1.x → 5.9.x upgrade, see [Runtime authorization migration](/5.9/migrating-from-5.1-lts/runtime-authorization).

***

## Related resources

> [card] [End-user access management](./end-user-access-management)
>
> Org-level end-user, role, and group management

> [card] [Workspaces access rights](./workspaces-access-rights)
>
> Designer-side access to workspaces and projects

> [card] [Roles & permissions matrix](./roles-permissions-matrix)
>
> Full matrix of designer and end-user roles

> [card] [Configuring access roles for processes](../flowx-engine-setup-guide/configuring-access-roles-for-processes)
>
> Per-swimlane role configuration on process definitions


# Workspaces access rights
Source: https://docs.flowx.ai/5.9/setup-guides/access-management/workspaces-access-rights

Overview of FlowX workspaces access rights and role-based access control

> [!NOTE]
>
> **Documentation Navigation:**
>
> * **Workspaces Access Rights** (Current) - Role overview and concepts
> * [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix) - Detailed permission specifications
> * [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide) - Technical implementation details
> * [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide) - Practical scenarios and best practices

> [!NOTE]
>
> FlowX provides a comprehensive role-based access control system with predefined roles at organization, workspace, and project levels.

## Overview of workspaces access rights

FlowX provides a structured role hierarchy designed to support multi-tenant workspace architecture while maintaining security and governance. The system includes predefined roles that cannot be modified, ensuring consistent access patterns across all FlowX deployments.

![Default Roles Hierarchy](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/default_roles.png)

## Authentication and authorization architecture

FlowX separates authentication and authorization into distinct systems:

> [tab] Authentication (Keycloak)
>
> **Handles user identity and login**
>
> * User login and identity verification
> * Token generation for authenticated users
> * User creation and management in identity provider
> * Service account identification with `SA_FLOWX` role

> [tab] Authorization (CAS/auth-system)
>
> **Manages access control and permissions**
>
> * Endpoint access control within FlowX Designer
> * Workspace and project permissions
> * Role and group management
> * ACL-based fine-grained access control
> * Database-stored permissions for better performance

> [!NOTE]
>
> **Designer vs Runtime Permissions**
>
> * **Designer Permissions**: Control access to FlowX Designer interface, managed through workspaces and the role system
> * **Runtime Permissions**: Control process execution and data access, managed through Keycloak roles
>
> All roles and permissions described in this document apply only to FlowX Designer access.

## Configuration and Runtime access

> [card] Configuration Access
>
> **Project-level roles for design and building**
>
> * Process and workflow design
> * UI templates and integrations
> * Project settings and resources
> * **Roles**: Owner, Editor, Viewer
> * **Scope**: Per-project assignment

> [card] Runtime Access
>
> **Workspace-level roles for deployment and execution**
>
> * Build creation and deployment
> * Process instance management
> * Scheduled processes and policies
> * Runtime environment overrides
> * **Roles**: Runtime Editor, Admin
> * **Scope**: Workspace-wide application

> [!WARNING]
>
> **Key Distinction**: Project roles provide **configuration access only**. Runtime operations require separate workspace-level roles like `workspace_runtime_editor`, `workspace_admin` or `workspace_user`, etc.

## User types

FlowX distinguishes between two primary user types, each with different access patterns and authentication requirements:

### Designer users

> [card] Designer Users
>
> **Users who access FlowX Designer to configure and manage applications**
>
> **Characteristics:**
>
> * Created in FlowX database upon first login to Designer
> * Managed through the workspace and role system described in this document
> * Authentication handled by external provider (e.g., Keycloak)
> * Authorization controlled by FlowX Designer roles and permissions
>
> **Use Cases:**
>
> * Platform administrators
> * Business analysts and configurators
> * Process designers and developers
> * UI/UX designers and theme editors

### Runtime users

> [!NOTE]
>
> Organization admins invite and manage end users in FlowX Designer under **Organization Settings** → **Access Management** → **End-Users** and **End-Users Groups**. See [End-user access management](./end-user-access-management).

> [card] Runtime Users
>
> **Users who interact with applications built using FlowX, but do not necessarily have access to FlowX Designer**
>
> **Characteristics:**
>
> * Not created in FlowX database unless they also log into FlowX Designer
> * Receive access to applications powered by FlowX via runtime roles and groups from external authentication system (e.g., Keycloak)
> * Permissions at runtime (e.g., swimlane access, task management) are granted based on roles/groups parsed from user's access token
> * No visibility in Designer unless they have both runtime and Designer access
>
> **Subtypes:**
>
> > [accordion] Business Users (Operational Staff)
> >
> > **Internal staff using FlowX-powered applications**
> >
> > * Bank tellers, loan officers, branch staff
> > * Customer service representatives
> > * Back-office operational teams
> > * Task management and workflow execution capabilities
> > * Access granted through organizational roles and group memberships
>
> > [accordion] End Users (Customers)
> >
> > **Organization's customers interfacing with customer-facing applications**
> >
> > * External customers using digital banking, insurance, or other services
> > * Indirect users of FlowX runtime via organization's digital channels
> > * Typically authenticated through customer identity systems
> > * Limited to self-service and customer-facing workflows

> [!WARNING]
>
> **User Overlap Between Designer and Runtime**
>
> Users can have both Designer access and Runtime access simultaneously. When this occurs:
>
> * The user is created in FlowX database with Designer roles and permissions
> * The same user can also interact with runtime applications using their runtime roles from Keycloak
> * Designer permissions control what they can configure in FlowX Designer
> * Runtime permissions control what processes and tasks they can access in deployed applications

> [!NOTE]
>
> **Organization ID propagation**
>
> FlowX propagates the organization ID across runtime contexts for multi-tenant isolation:
>
> * **Scheduler execution**: Organization ID added to scheduled job context
> * **Event listeners**: Organization ID propagated to event handlers
> * **Process instances**: Organization ID captured from the initiator
>
> This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.

## Role architecture

> [card] Organization Level
>
> Cross-workspace administrative access for managing the entire FlowX organization
>
> **Roles:**
>
> * Organization Admin

> [card] Workspace Level
>
> Workspace-specific roles for managing resources, users, and configurations within a workspace
>
> **Roles:**
>
> * Workspace Admin
> * Workspace User
> * Theme Editor
> * Workspace Runtime Editor
> * Workspace Operations Editor

> [card] Project Level
>
> Project-specific roles for controlling access to individual projects and their resources
>
> **Roles:**
>
> * Project Owner
> * Project Editor
> * Project Viewer

## Organization level roles

### Organization admin

> [card] Organization Admin
>
> **Full administrative access across the entire FlowX organization**
>
> **Key Responsibilities:**
>
> * Managing all workspaces across the organization
> * Creating and organizing workspace structure
> * Managing organization-wide users and groups
> * Overseeing system health and platform status
> * Implementing organization-wide policies and configurations
>
> **Key Characteristics:**
>
> * Cannot be edited, duplicated, or deleted
> * Can only be assigned in the Organization admin interface
> * Hidden from workspace role lists
> * Highest level of access in the FlowX hierarchy
> * Should be limited to 2-3 trusted platform administrators
>
> **Use Cases:**
>
> * Platform administrators managing FlowX deployment
> * IT managers responsible for multi-workspace environments
> * System architects overseeing enterprise FlowX usage

#### Key permissions summary

> [tab] Organization Management
>
> ✅ Create, edit, and delete workspaces\
> ✅ Configure organization settings\
> ✅ Manage organization-wide users and groups\
> ✅ Access all projects across all workspaces

> [tab] System Management
>
> ✅ Manage global font resources\
> ✅ Configure out of office policies\
> ✅ Monitor platform status
> ⚠️ Manage environment information *(deprecated in 5.7.0 — Configure Environment Info UI removed)*

> [tab] Monitoring
>
> ✅ View organization audit logs\
> ✅ Access all workspace audit logs\
> ✅ Monitor system health across organization\
> ❌ Cannot edit or delete audit entries (read-only)

> [!WARNING]
>
> **Critical Security Note**
>
> The Organization Admin role should be assigned sparingly. Organization admins have access to **all projects in all workspaces** without exception. Limit this role to trusted platform administrators only.

> [!TIP]
>
> For complete permission specifications, see the [Organization Admin Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#organization-admin-permission-matrix).

## Workspace level roles

### Workspace admin

> [card] Workspace Admin
>
> **Complete control over workspace-level resources and users**
>
> **Key Responsibilities:**
>
> * Managing workspace users, groups, and roles
> * Overseeing all projects within the workspace
> * Configuring workspace themes and branding
> * Managing workspace-level settings and policies
> * Handling workspace resource allocation
> * Granting and revoking project access
>
> **Key Characteristics:**
>
> * Cannot be edited or deleted (predefined role)
> * Can be assigned to users and groups within the workspace
> * Listed in workspace role management interfaces
> * Cannot manage organization-wide settings
> * Has admin access to all projects in their workspace
>
> **Use Cases:**
>
> * Business unit managers
> * Department heads overseeing team projects
> * Workspace administrators with full workspace responsibility
> * Team leads managing workspace access and resources

#### Key permissions summary

> [tab] Workspace Management
>
> ✅ Create projects and libraries\
> ✅ Manage workspace themes and fonts\
> ✅ Manage global media library\
> ✅ Configure workspace settings\
> ✅ View workspace audit logs

> [tab] User Management
>
> ✅ Add and remove workspace users\
> ✅ Create and manage groups\
> ✅ Assign workspace roles\
> ✅ Manage user permissions\
> ❌ Cannot create or delete workspaces

> [tab] Runtime Management
>
> ✅ Create and view builds\
> ✅ Manage active policies\
> ✅ Configure scheduled processes\
> ✅ Manage configuration parameter overrides\
> ✅ View and edit process instances
> ✅ Edit process variables on active instances

> [!TIP]
>
> For complete permission specifications, see the [Workspace Admin Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-admin-permission-matrix).

### Workspace user

> [card] Workspace User
>
> **Standard workspace access with project creation capabilities**
>
> **Key Responsibilities:**
>
> * Creating new projects within the workspace
> * Working on assigned projects with appropriate project-level roles
> * Viewing workspace resources (themes, fonts, media)
> * Basic workspace participation
>
> **Key Characteristics:**
>
> * Cannot be edited or deleted (predefined role)
> * Default role for most workspace members
> * Can create projects (becomes project owner automatically)
> * Needs explicit project access to work on others' projects
> * Limited administrative capabilities
>
> **Use Cases:**
>
> * Business analysts and configurators
> * Process designers and developers
> * Junior team members
> * Team members who build projects within defined boundaries
> * General workspace members

#### Key permissions summary

> [tab] Workspace Access
>
> ✅ Create projects and libraries\
> ✅ View workspace themes (read-only)\
> ✅ View workspace fonts (read-only)\
> ✅ View global media library (read-only)\
> ✅ View workspace users, groups, and roles (read-only)\
> ❌ Cannot manage workspace settings

> [tab] Runtime Access
>
> ✅ View builds for accessible projects\
> ✅ View active policies (read-only)\
> ✅ View scheduled processes (read-only)\
> ✅ View configuration parameters (read-only)\
> ✅ View process instances for accessible projects (read-only)\
> ❌ Cannot create or modify runtime configurations

> [tab] Project Access
>
> ✅ Create new projects (becomes owner)\
> ✅ Access granted projects based on project role (read-only)\
> ❌ Cannot view all workspace projects by default\
> ❌ Needs explicit project access from project owner (read-only)

> [!TIP]
>
> For complete permission specifications, see the [Workspace User Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-user-permission-matrix).

### Theme editor

> [card] Theme Editor
>
> **Specialized role for visual design and branding management**
>
> **Key Responsibilities:**
>
> * Designing and customizing application themes
> * Managing workspace fonts and typography
> * Organizing and maintaining media library
> * Creating visual design assets
> * Ensuring brand consistency across projects
>
> **Key Characteristics:**
>
> * Extends workspace\_user with design permissions
> * Same base permissions as workspace\_user
> * Additional permissions for visual asset management
> * Cannot be edited or deleted (predefined role)
> * Focused on design and branding elements
>
> **Use Cases:**
>
> * UI/UX designers
> * Brand managers ensuring visual consistency
> * Visual design specialists
> * Marketing team members managing brand assets
> * Design teams customizing FlowX applications

#### Key permissions summary

> [tab] Design Management
>
> ✅ Create, edit, and delete themes\
> ✅ Manage workspace fonts (full access)\
> ✅ Manage global media library\
> ✅ Set default themes\
> ✅ Configure theme sections

> [tab] Inherited from Workspace User
>
> ✅ Create projects and libraries\
> ✅ View workspace resources\
> ✅ View runtime information (read-only)\
> ✅ Standard workspace user capabilities

> [!NOTE]
>
> Theme editors have the same project access rules as workspace users. They can create projects but need explicit access to work on others' projects.

> [!TIP]
>
> For complete permission specifications, see the [Theme Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#theme-editor-permission-matrix).

### Workspace runtime editor

> [card] Workspace Runtime Editor
>
> **Extended workspace user role with runtime configuration capabilities**
>
> **Key Responsibilities:**
>
> * Creating and managing workspace builds
> * Configuring runtime environments and deployments
> * Managing active policies and deployment strategies
> * Overriding configuration parameters for runtime
> * Monitoring and managing process instances
> * Scheduling process executions
>
> **Key Characteristics:**
>
> * Extends workspace\_user with runtime permissions
> * Same base permissions as workspace\_user
> * Additional permissions for runtime environment management
> * Cannot be edited or deleted (predefined role)
> * Focused on deployment and runtime operations
>
> **Use Cases:**
>
> * DevOps engineers managing deployments
> * Release managers handling build processes
> * Runtime environment administrators
> * Technical operations staff
> * System administrators with runtime responsibilities

#### Key permissions summary

> [tab] Runtime Management
>
> ✅ Create builds from library versions\
> ✅ Edit active policies\
> ✅ Manage scheduled processes (activate, deactivate, delete)\
> ✅ Create, edit, and delete configuration parameter overrides\
> ✅ Edit process instances

> [tab] Inherited from Workspace User
>
> ✅ Create projects and libraries\
> ✅ View workspace resources\
> ✅ Standard workspace user capabilities

> [!WARNING]
>
> **Runtime access is workspace-scoped**
>
> Runtime permissions are managed at the workspace level, not the project level. Users with workspace\_runtime\_editor can manage runtime configurations across **all projects in the workspace**, not just specific projects.

> [!TIP]
>
> For complete permission specifications, see the [Workspace Runtime Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-runtime-editor-permission-matrix).

### Workspace operations editor

On SaaS (5.13), this role is replaced by the [Workspace corrective actions editor](#workspace-corrective-actions-editor).&#x20;

> [card] Workspace Operations Editor
>
> **Extended workspace user role with operations management capabilities**
>
> **Key Responsibilities:**
>
> * Managing process instance operations (migration & move token)
> * Editing process variables on active instances
> * Managing operational tasks across the workspace
> * Viewing and editing process instances
>
> **Key Characteristics:**
>
> * Extends workspace\_user with operations permissions
> * Same base permissions as workspace\_user
> * Additional permissions for operations management
> * Cannot be edited or deleted (predefined role)
> * Focused on process operations and instance management
>
> **Use Cases:**
>
> * Support engineers managing process migrations
> * Operations teams handling token movements
> * Technical support staff editing process variables
> * Operations managers overseeing process instances

#### Key permissions summary

> [tab] Operations Management
>
> ✅ Create, view, edit, and delete operations (migration & move token)\
> ✅ Edit process instances\
> ✅ Edit process variables on active instances\
> ✅ View all process instances across workspace

> [tab] Inherited from Workspace User
>
> ✅ Create projects and libraries\
> ✅ View workspace resources\
> ✅ Standard workspace user capabilities

> [!NOTE]
>
> The workspace\_operations\_editor role provides focused permissions for operations management without the broader runtime capabilities of workspace\_runtime\_editor.

> [!TIP]
>
> For complete permission specifications, see the [Workspace Operations Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix).

### Workspace corrective actions editor

SaaS · 5.13

> [!NOTE]
>
> **Available on SaaS with FlowX.AI 5.13.** This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

> [card] Workspace Corrective Actions Editor
>
> **Extended workspace user role that can run corrective actions on process instances**
>
> This role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically.
>
> **Key Responsibilities:**
>
> * Running corrective actions on process instances: [migration](/5.9/docs/projects/runtime/active-process/migrate-process-instances) and [move token](/5.9/docs/projects/runtime/active-process/move-token)
> * Viewing and editing process instances across the workspace
> * Editing process instance variables
>
> **Key Characteristics:**
>
> * Extends workspace\_user with corrective actions permissions
> * Corrective actions can be viewed and created, not edited or deleted
> * `workspace_admin` also holds these permissions; organization admins have them through workspace admin access
> * Cannot be edited or deleted (predefined role)

> [!TIP]
>
> For complete permission specifications, see the [Workspace Corrective Actions Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).

## Project level roles

### Project owner

> [card] Project Owner
>
> **Complete ownership and governance of project resources**
>
> **Key Responsibilities:**
>
> * Full project governance and decision-making authority
> * Granting and revoking project access to other users
> * Managing all project configurations and resources
> * Approving major project changes
> * Overseeing project lifecycle
>
> **Key Characteristics:**
>
> * Automatically assigned to project creator
> * Cannot be edited, duplicated, deleted, or manually assigned through UI
> * Hidden from role selection interfaces
> * System-managed role with highest project-level access
> * Permanent assignment for project lifecycle
> * Only one owner per project
>
> **Automatic Assignment:**
>
> * Automatically granted when creating a project
> * Can be transferred to another user (ownership transfer)
> * Cannot be removed without transferring to another user
>
> **Use Cases:**
>
> * Project leads with full authority
> * Technical architects owning project decisions
> * Product owners managing project direction
> * Users who created the project

#### Key permissions summary

> [tab] Project Administration
>
> ✅ Complete project ownership and governance\
> ✅ Grant/revoke project access\
> ✅ Delete project\
> ✅ Transfer project ownership\
> ✅ Full administrative control

> [tab] Configuration
>
> ✅ All configuration resources (full access)\
> ✅ Processes, workflows, enumerations\
> ✅ Templates, media, integrations\
> ✅ AI agents, reusable resources\
> ✅ All project settings

> [!NOTE]
>
> **Non-Configurable Permissions**
>
> Project owner permissions are not configurable in the UI. The role automatically includes all project-level permissions without exception.

> [!TIP]
>
> For complete permission specifications, see the [Project Owner Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#project-owner-permission-matrix).

### Project editor

> [card] Project Editor
>
> **Full project configuration and management capabilities**
>
> **Key Responsibilities:**
>
> * Building and configuring project processes
> * Designing workflows and integrations
> * Creating UI configurations
> * Managing project resources
> * Creating builds and deployments
> * Day-to-day project development
>
> **Key Characteristics:**
>
> * Can be assigned to users and groups
> * Comprehensive project access without ownership rights
> * Cannot grant/revoke project access to others
> * Standard role for project team members
> * Cannot be edited or deleted (predefined role)
>
> **Use Cases:**
>
> * Senior developers and configurators
> * Technical leads on project teams
> * Business analysts with advanced permissions
> * Team members with full project configuration needs
> * Development team members

#### Key permissions summary

> [tab] Configuration
>
> ✅ All configuration resources (full access)\
> ✅ Processes, workflows, enumerations\
> ✅ Templates, media, integrations\
> ✅ AI agents, reusable resources\
> ✅ All project settings\
> ❌ Cannot manage project access

> [tab] Limitations
>
> ❌ Cannot grant/revoke project access\
> ❌ Cannot delete project\
> ❌ No administrative rights over project

> [!TIP]
>
> For complete permission specifications, see the [Project Editor Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#project-editor-permission-matrix).

### Project viewer

> [card] Project Viewer
>
> **Read-only access to project configuration and settings**
>
> **Key Responsibilities:**
>
> * Reviewing project configurations
> * Auditing processes and workflows
> * Compliance checking and documentation
> * Understanding project structure for training
> * Monitoring project status
>
> **Key Characteristics:**
>
> * Can be assigned when granting project access
> * Completely read-only access
> * Safe role for stakeholders needing visibility
> * No modification capabilities
> * Can test processes through interface
> * Suitable for audit and review purposes
>
> **Use Cases:**
>
> * Business stakeholders and executives
> * Quality assurance team members
> * External consultants needing project visibility
> * Audit and compliance personnel
> * New team members during onboarding
> * Documentation and training purposes

#### Key permissions summary

> [tab] View Access
>
> ✅ View all configuration resources\
> ✅ View processes, workflows, enumerations\
> ✅ View templates, media, integrations\
> ✅ View project settings and dependencies\
> ✅ Export project resources
> ✅ Test processes and workflows

> [tab] Restrictions
>
> ❌ Cannot edit any resources
> ❌ Cannot create any resources\
> ❌ Cannot delete any resources\
> ❌ Cannot modify configurations\
> ❌ Cannot create builds or deployments

> [!NOTE]
>
> **Testing Capability**
>
> Project viewers can test processes and workflows through the interface, allowing them to understand how processes work without the ability to modify configurations.

> [!TIP]
>
> For complete permission specifications, see the [Project Viewer Permission Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#project-viewer-permission-matrix).

## Role comparison matrix

### Quick capability comparison

The following table provides a high-level comparison of key capabilities across all roles:

| Capability | org\_admin | workspace\_admin | workspace\_user | theme\_editor | runtime\_editor | operations\_editor | project\_owner | project\_editor | project\_viewer |
| - | - | - | - | - | - | - | - | - | - |
| **Workspace Management** | | | | | | | | | |
| Create workspace | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Manage workspace users | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Create projects | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | N/A | N/A |
| **Design & Branding** | | | | | | | | | |
| Edit themes | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | N/A | N/A | N/A |
| Manage fonts | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | N/A | N/A | N/A |
| **Runtime Operations** | | | | | | | | | |
| Create builds | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| Edit active policy | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage config parameters | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| **Operations Management** | | | | | | | | | |
| Manage operations | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | N/A | N/A | N/A |
| Edit process variables | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | N/A | N/A | N/A |
| **Project Configuration** | | | | | | | | | |
| Edit processes | ✅ | ✅\* | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ✅ | ❌ |
| Manage templates | ✅ | ✅\* | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ✅ | ❌ |
| Configure integrations | ✅ | ✅\* | ✅\* | ✅\* | ✅\* | ✅\* | ✅ | ✅ | ❌ |
| **Access Control** | | | | | | | | | |
| Grant project access | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| Manage workspace access | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

> [!NOTE]
>
> \* Workspace-level roles can only edit project resources for projects they have been explicitly granted access to. Having a workspace role does not automatically grant access to all projects.

> [!NOTE]
>
> The active policy is a workspace-level permission. Project roles do not grant it: a project owner or editor needs the workspace runtime editor or workspace admin role to change it.

## Default groups

### Everyone in workspace group

> [!NOTE]
>
> Every workspace automatically includes a special system-managed group for simplified access management to all workspace users.

> [card] all\_users\_\[workspace\_name]
>
> **Display Name:** Everyone from \<workspace name>
>
> **Purpose:**
> Provides convenient access management for all users associated with a workspace, enabling efficient bulk access grants.
>
> **Automatic Behavior:**
>
> * ✅ Created automatically during workspace provisioning
> * ✅ Users automatically added when granted workspace access
> * ✅ Users automatically removed when workspace access revoked
> * ✅ Pre-selected when creating new projects/libraries
> * ✅ Appears in user/group search results
> * ❌ Cannot be edited, deleted, or duplicated
> * ❌ Membership cannot be manually modified
>
> **Common Use Cases:**
>
> * Grant all workspace members read access to reference projects
> * Provide baseline visibility across workspace projects
> * Simplify onboarding by giving new users automatic access to shared resources
> * Create workspace-wide shared libraries
>
> **Example:**
>
> ```
> Workspace: "Product Development"
> Group: "all_users_product_development"
> Display: "Everyone from Product Development"
> ```

> [!WARNING]
>
> **No Individual Exclusions**
>
> The "Everyone in workspace" group includes ALL workspace members without exception. You cannot remove specific users from this group or create exclusions. If you need selective access, create custom groups instead.

### Custom groups

> [accordion] Creating Custom Groups
>
> **When to create custom groups:**
>
> * Team-based access (e.g., "Development Team", "QA Team")
> * Role-based access (e.g., "Senior Developers", "Stakeholders")
> * Project-specific access (e.g., "Project Alpha Team")
> * Cross-functional teams (e.g., "Release Management")
>
> **Group naming best practices:**
>
> * Use descriptive names indicating purpose
> * Follow consistent naming conventions
> * Example format: `[function]_[department]_[sub-group]`
> * Good examples: `dev_team_frontend`, `stakeholders_finance`, `editors_project_phoenix`

> [accordion] Managing Groups
>
> **Group operations:**
>
> * Add members individually or bulk import
> * Assign workspace-level roles to groups
> * Use groups when granting project access
> * Remove members or delete entire groups
>
> **Best practices:**
>
> * Use groups instead of individual assignments when possible
> * Document group purposes clearly
> * Review group memberships regularly
> * Plan group structure before implementation

> [!TIP]
>
> For comprehensive groups documentation and strategies, see the [Role Selection & Management Guide](/5.9/setup-guides/access-management/role-selection-guide#groups-and-access-management).

## Quick start guide

### Grant workspace access

**1. Navigate to workspace users**

Go to your workspace → Access Management → Users

**2. Add user**

Click "Add" button → Search for user by name or email

**3. Assign role**

Select appropriate role (typically `workspace_user` for standard access) → Confirm

### Assign user to project

**1. Open project access management**

Go to project → Settings → Access Management

**2. Grant access**

Click "Grant Access" → Search for user or group

**3. Select role**

Choose role (`project_editor` for full access, `project_viewer` for read-only) → Confirm

### Create a custom group

**1. Navigate to groups**

Go to workspace → Access Management → Groups

**2. Create group**

Click "Add" → Enter descriptive group name and description

**3. Add members and assign role**

Add users to group → Assign workspace-level role to group → Save

## Legacy role migration

### FlowX 4.x to 5.0 role mapping

> [!WARNING]
>
> FlowX 4.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required in FlowX 5.0.

| FlowX 4.x Role | FlowX 5.0 Equivalent | Scope Change | Notes |
| - | - | - | - |
| `FLOWX_ADMIN` | `workspace_admin` | Now workspace-scoped | Was global, now per-workspace |
| `FLOWX_CONFIGURATOR` | `workspace_user` or `project_editor` | Depends on needs | Choose based on required access |
| `FLOWX_UI_DESIGNER` | `theme_editor` | Workspace-scoped | Enhanced capabilities |
| `FLOWX_VIEWER` | `project_viewer` | Now project-specific | Was global, now per-project |
| Custom Keycloak roles | Manual review required | N/A | Assess against new structure |

### Key migration considerations

> [card] Scope Changes
>
> Roles are now workspace-scoped rather than global. Reassign within workspace context.

> [card] Runtime Permissions
>
> Runtime permissions moved to workspace level. Use `workspace_runtime_editor` role.

> [card] Database Storage
>
> Roles now stored in FlowX database for better performance and control.

> [card] Hierarchy Changes
>
> New role hierarchy requires review of user access patterns.

## Best practices summary

> [card] Start Conservative
>
> Begin with minimum required access (e.g., `project_viewer`) and escalate as needed based on demonstrated requirements.

> [card] Use Groups
>
> Create and use groups for teams and functions rather than managing individual user access.

> [card] Regular Reviews
>
> Conduct quarterly access reviews, remove inactive users, and validate permissions match responsibilities.

> [card] Document Decisions
>
> Maintain records of role assignments, especially for elevated privileges and exceptions.

> [card] Principle of Least Privilege
>
> Always grant the minimum permissions necessary for users to perform their job functions.

> [card] Plan for Transitions
>
> Have clear processes for role changes, project ownership transfers, and access removal.

> [!TIP]
>
> For detailed best practices and practical scenarios, see the [Role Selection & Management Guide](/5.9/setup-guides/access-management/role-selection-guide#best-practices-summary).

## Current limitations

> [!WARNING]
>
> The following features have specific limitations:

**Role Management:**

* Custom roles not available
* Bulk role assignment tools not available

**Workspace Features:**

* Workspace deletion functionality not available
* Moving projects/libraries between workspaces not supported

**Integration Features:**

* Runtime roles and groups will return errors if Keycloak isn't used as the authentication provider

## Troubleshooting common issues

> [accordion] User Cannot Access Workspace
>
> **Possible Causes:**
>
> * User not assigned to workspace
> * No role assigned in workspace
> * User not in any workspace groups
>
> **Solutions:**
>
> 1. Verify user is in workspace user list
> 2. Check role assignments
> 3. Validate group memberships
> 4. Contact workspace administrator for access

> [accordion] Cannot See Project
>
> **Possible Causes:**
>
> * No project-level access granted
> * Workspace role doesn't auto-grant project access
> * Project visibility restrictions
>
> **Solutions:**
>
> 1. Contact project owner for access
> 2. Verify workspace membership
> 3. Check if project exists in current workspace
> 4. Request appropriate project role

> [accordion] Permissions Not Working After Assignment
>
> **Possible Causes:**
>
> * Cached permissions not updated
> * User hasn't logged out and back in
> * Conflicting role assignments
>
> **Solutions:**
>
> 1. Log out completely and log back in
> 2. Clear browser cache
> 3. Wait a few minutes for permissions to propagate
> 4. Contact workspace administrator if issue persists

> [!TIP]
>
> For comprehensive troubleshooting with detailed diagnostic procedures, see [Troubleshooting Permission Issues](/5.9/setup-guides/access-management/role-selection-guide#troubleshooting-permission-issues).

## Related documentation

> [card] [Complete Permissions Matrix](/5.9/setup-guides/access-management/roles-permissions-matrix)
>
> Detailed permission specifications for all FlowX roles with comprehensive matrices

> [card] [Permission Reference Guide](/5.9/setup-guides/access-management/permission-reference-guide)
>
> Technical implementation details, UI mappings, and permission naming conventions

> [card] [Role Selection Guide](/5.9/setup-guides/access-management/role-selection-guide)
>
> Practical scenarios, best practices, troubleshooting, and migration guidance

> [card] [Access Management Overview](/5.9/setup-guides/access-management/access-management-overview)
>
> Overview of FlowX access management system and authentication architecture

> [card] [Configuring IAM Solution](/5.9/setup-guides/access-management/configuring-an-iam-solution)
>
> Setting up identity and access management with Keycloak

> [card] [Workspaces](/5.9/docs/projects/workspaces)
>
> Understanding workspaces and their role in organizing projects


# FlowX Admin setup
Source: https://docs.flowx.ai/5.9/setup-guides/admin-setup-guide

Complete configuration reference for the FlowX Admin microservice, including logging, databases, Kafka, and various subsystems.

This guide provides a comprehensive reference for configuring the FlowX Admin microservice using environment variables and configuration files.

## Infrastructure prerequisites

Before setting up the Admin microservice, ensure the following components are properly set up:

* **Database Instance**: The Admin microservice connects to the same database as the FlowX.AI Engine.
* **MongoDB**: For additional data management.
* **Redis**: For caching and transient data storage.
* **Kafka**: For audit logs, events, and messaging (if using FlowX.AI Audit functionality).

***

## Core configuration

### Server configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SERVER_PORT` | Port on which the Admin service will run | `8080` |
| `SPRING_APPLICATION_NAME` | Name of the application used for service discovery | `admin` |
| `SPRING_JACKSON_SERIALIZATION_INDENTOUTPUT` | Enable indented JSON output | `true` |

***

## Database configuration

The Admin microservice connects to the same PostgreSQL or Oracle database as the FlowX.AI Engine for storing process definitions.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC URL for database connection | `jdbc:postgresql://localhost:5432/flowx` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `[your-secure-password]` |

> [!WARNING]
>
> You will need to make sure that the user, password, connection link and database name are configured correctly, otherwise, you will receive errors at start time.

> [!NOTE]
>
> The database schema is managed by a [Liquibase](https://www.liquibase.org/) script provided with the Engine.

***

## MongoDB configuration

The Admin microservice also connects to a MongoDB database instance for additional data management.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DB_USERNAME` | MongoDB username | `data-model` |
| `DB_PASSWORD` | MongoDB password | `[your-secure-password]` |
| `DB_NAME` | MongoDB database name | `data-model` |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@localhost:27017/${DB_NAME}?retryWrites=true` |
| `SPRING_DATA_MONGODB_UUIDREPRESENTATION` | UUID representation format | `standard` |
| `SPRING_DATA_MONGODB_STORAGE` | Storage type (Azure environments) | `mongodb` or `cosmosdb` |
| `MONGOCK_CHANGELOGSSCANPACKAGE_0_` | Mongock changelog scan package | `ai.flowx.admin.data.model.config.mongock` |
| `MONGOCK_TRANSACTIONENABLED` | Enable transactions for Mongock operations | `false` |

> [!NOTE]
>
> Ensure that the MongoDB configuration is compatible with the same database requirements as the FlowX.AI Engine, especially if sharing database instances.

***

## Redis and caching configuration

Admin Service uses Redis for caching and storing transient data. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

***

## Kafka configuration

The Admin microservice uses Kafka for sending audit logs, managing scheduled timer events, platform component versions, and start timer event updates.

### General Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Kafka broker addresses | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol | `PLAINTEXT` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size in bytes | `52428800` (50MB) |

### Kafka producer configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_PRODUCER_KEYSERIALIZER` | Key serializer class | `org.apache.kafka.common.serialization.StringSerializer` |
| `SPRING_KAFKA_PRODUCER_VALUESERIALIZER` | Value serializer class | `org.springframework.kafka.support.serializer.JsonSerializer` |
| `SPRING_KAFKA_PRODUCER_MAXREQUESTSIZE` | Maximum request size | `52428800` (50MB) |

### Kafka consumer configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_GROUPID_GENERICPROCESSING` | Generic processing consumer group | `generic-processing-group` |
| `KAFKA_CONSUMER_THREADS_GENERICPROCESSING` | Generic processing threads | `6` |
| `KAFKA_CONSUMER_GROUPID_PROCESSSYNC` | Process sync consumer group | `process-sync-group` |
| `KAFKA_CONSUMER_THREADS_PROCESSSYNC` | Process sync consumer threads | `6` |
| `KAFKA_CONSUMER_GROUPID_BUSINESSRULESYNC` | Business rule sync consumer group | `business-rule-sync-group` |
| `KAFKA_CONSUMER_THREADS_BUSINESSRULESYNC` | Business rule sync consumer threads | `6` |
| `KAFKA_CONSUMER_GROUPID_REUSABLETEMPLATESYNC` | Reusable template sync consumer group | `reusable-template-sync-group` |
| `KAFKA_CONSUMER_THREADS_REUSABLETEMPLATESYNC` | Reusable template sync consumer threads | `6` |
| `KAFKA_CONSUMER_GROUPID_UIFLOWSYNC` | UI flow sync consumer group | `ui-flow-sync-group` |
| `KAFKA_CONSUMER_THREADS_UIFLOWSYNC` | UI flow sync consumer threads | `6` |
| `KAFKA_CONSUMER_GROUPID_PROCESSCORRECTIONAFTERAPPOPERATION` | Process correction after app operation consumer group | `processCorrectionAfterAppOperationGroup` |
| `KAFKA_CONSUMER_THREADS_PROCESSCORRECTIONAFTERAPPOPERATION` | Process correction after app operation consumer threads | `6` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Auth exception retry interval (seconds) | `10` |

### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOT` | Reference to the primary separator | `${kafka.topic.naming.separator}` |
| `DASH` | Reference to the secondary separator | `${kafka.topic.naming.separator2}` |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Base package name | `ai${dot}flowx${dot}` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment name | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Topic version | `${dot}v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator | `-` |
| `KAFKA_TOPIC_NAMING_PREFIX` | Combined prefix | `${kafka.topic.naming.package}${kafka.topic.naming.environment}` |
| `KAFKA_TOPIC_NAMING_SUFFIX` | Combined suffix | `${kafka.topic.naming.version}` |

### Kafka topics configuration

#### Application topics

| Environment Variable | Description | Pattern | Default Value |
| - | - | - | - |
| `KAFKA_TOPIC_APPLICATION_SYNCRESPONSE` | Sync response topic | `${kafka.topic.naming.prefix}application-version.sync.out${kafka.topic.naming.suffix}` | `ai.flowx.application-version.sync.out.v1` |
| `KAFKA_TOPIC_APPLICATION_PROCESSSYNC` | Process sync topic | `${kafka.topic.naming.prefix}application-version.sync.process.in${kafka.topic.naming.suffix}` | `ai.flowx.application-version.sync.process.in.v1` |
| `KAFKA_TOPIC_APPLICATION_BUSINESSRULESYNC` | Business rule sync topic | `${kafka.topic.naming.prefix}application-version.sync.business-rule.in${kafka.topic.naming.suffix}` | `ai.flowx.application-version.sync.business-rule.in.v1` |
| `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATESYNC` | Reusable template sync topic | `${kafka.topic.naming.prefix}application-version.sync.reusable-template.in${kafka.topic.naming.suffix}` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCEUPDATEPROPAGATION` | Resource update propagation topic | `${kafka.topic.naming.prefix}application-version.resource.update.propagation${kafka.topic.naming.suffix}` | `ai.flowx.application-version.resource.update.propagation.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS` | Correction after app operation → process request | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.process.request${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE` | Correction after app operation → business rule | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.business-rule.request${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | Correction after app operation → reusable template | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.reusable-template.request${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_UIFLOW` | Correction after app operation → UI flow | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.ui-flow.request${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` | Correction after app operation → custom component | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.custom-component.request${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT` | Correction after app operation response topic | `${kafka.topic.naming.prefix}application-version.correction-after-app-operation.response${kafka.topic.naming.suffix}` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
| `KAFKA_TOPIC_APPLICATION_UIFLOWSYNC` | UI flow sync topic | `${kafka.topic.naming.prefix}application-version.sync.ui-flow.in${kafka.topic.naming.suffix}` | `ai.flowx.application-version.sync.ui-flow.in.v1` |

#### Audit topics

| Environment Variable | Description | Pattern | Default Value |
| - | - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Audit output topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}save${dot}audit${kafka.topic.naming.suffix}` | `ai.flowx.core.trigger.save.audit.v1` |

#### Platform Topics

| Environment Variable | Description | Pattern | Default Value |
| - | - | - | - |
| `KAFKA_TOPIC_PLATFORM_COMPONENTSVERSIONS_IN` | Components versions caching topic | `${kafka.topic.naming.prefix}core${dot}trigger${dot}platform${dot}versions${dot}caching${kafka.topic.naming.suffix}` | `ai.flowx.core.trigger.platform.versions.caching.v1` |

#### Events gateway topics

| Environment Variable | Description | Pattern | Default Value |
| - | - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Commands message output topic | `${kafka.topic.naming.prefix}eventsgateway${dot}process${dot}commands${dot}message${kafka.topic.naming.suffix}` | `ai.flowx.eventsgateway.process.commands.message.v1` |

#### Build topics

| Environment Variable | Description | Pattern | Default Value |
| - | - | - | - |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | Build runtime data topic | `${kafka.topic.naming.prefix}build${dot}runtime-data${kafka.topic.naming.suffix}` | `ai.flowx.build.runtime-data.v1` |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_OUT_UPDATES` | Start timer events updates topic | `${kafka.topic.naming.prefix}build${dot}start${dash}timer${dash}events${dot}updates${dot}in${kafka.topic.naming.suffix}` | `ai.flowx.build.start-timer-events.updates.in.v1` |

#### Resource topics

| Environment Variable | Description | Pattern | Default Value |
| - | - | - | - |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Resources usages refresh topic | `${kafka.topic.naming.prefix}application${dash}version${dot}resources${dash}usages${dot}refresh${kafka.topic.naming.suffix}` | `ai.flowx.application-version.resources-usages.refresh.v1` |
| `KAFKA_TOPIC_RESOURCE_CACHEEVICT` | Resource cache-eviction topic, published when a process version changes so the engine clears its cached resources (available from FlowX.AI 5.9.1) | `${kafka.topic.naming.prefix}core${dot}trigger${dot}resource${dot}cache${dash}evict${kafka.topic.naming.suffix}` | `ai.flowx.core.trigger.resource.cache-evict.v1` |

### OAuth authentication for Kafka

When using the `kafka-auth` profile, the following variables configure OAuth for Kafka:

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

***

## CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

***

## Logging configuration

The FlowX Admin microservice provides granular control over logging levels for different components:

| Environment Variable | Description | Default Value | |
| - | - | - | - |
| `LOGGING_LEVEL_ROOT` | Log level for root Spring Boot microservice | `INFO` | |
| `LOGGING_LEVEL_APP` | Log level for application-specific code | `INFO` | |

### Changing log levels at runtime

> [!WARNING]
>
> **Changed in FlowX.AI 5.9.5.** The `loggers` actuator endpoint is no longer in the default exposure list, so it is not reachable by default on 5.9.5 and later. To keep changing log levels at runtime, add `loggers` to `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE` (for example `health,info,metrics,prometheus,loggers`). Otherwise, set log levels with the `LOGGING_LEVEL_*` environment variables and restart the service.

You can adjust log levels dynamically without restarting the service using Spring Boot Actuator endpoints. This is particularly useful for troubleshooting and debugging in production environments.

**Example: Change log level for a specific package**

```bash theme={"dark"}
curl 'http://localhost:8081/actuator/loggers/ai.flowx.admin' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'
```

**Common logger packages:**

* `ai.flowx.admin` - Application-specific logs
* `org.springframework` - Spring Framework logs
* `org.mongodb.driver` - MongoDB driver logs
* `org.apache.kafka` - Kafka client logs

**Available log levels:**

`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`

> [!WARNING]
>
> Using `DEBUG` or `TRACE` log levels in production may impact performance and generate large log volumes. Revert to `INFO` or `WARN` after troubleshooting is complete.

***

## Localization settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_DEFAULTLOCALE` | Default locale for the application | `en` |
| `APPLICATION_SUPPORTEDLOCALES` | List of supported locales | `en, ro` |

***

## Health monitoring

| Environment Variable | Description | Default Value |
| - | - | - |
| `MANAGEMENT_HEALTH_DB_ENABLED` | Enable database health checks | `true` |
| `MANAGEMENT_HEALTH_KAFKA_ENABLED` | Enable Kafka health checks | `true` |
| `MANAGEMENT_SERVER_ADDRESS` | Management server bind address | `0.0.0.0` |
| `MANAGEMENT_SERVER_PORT` | Management server port | `8081` |
| `MANAGEMENT_SERVER_BASEPATH` | Base path for management endpoints | `/manage` |
| `MANAGEMENT_SECURITY_ENABLED` | Enable security for management endpoints | `false` |
| `MANAGEMENT_ENDPOINTS_WEB_BASEPATH` | Base path for actuator endpoints | `/actuator` |
| `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE` | Endpoints to expose. Add `loggers` to change log levels at runtime (included by default on 5.9.4 and earlier) | `health,info,metrics,prometheus` |
| `MANAGEMENT_ENDPOINT_HEALTH_PROBES_ENABLED` | Enable Kubernetes probes | `true` |
| `MANAGEMENT_ENDPOINT_HEALTH_SHOWDETAILS` | Show health check details | `always` |
| `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` | Enable Prometheus metrics export | `false` |

### Platform health configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PLATFORMHEALTH_NAMESPACE` | Kubernetes namespace for health checks | `flowx` |
| `FLOWX_PLATFORMHEALTH_MANAGEMENTBASEPATH` | Base path for management endpoints | `${management.server.base-path}` |
| `FLOWX_PLATFORMHEALTH_ACTUATORBASEPATH` | Base path for actuator endpoints | `${management.endpoints.web.base-path}` |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONNAME` | Kubernetes annotation name for health checks | `flowx.ai/health` |
| `FLOWX_PLATFORMHEALTH_ANNOTATIONVALUE` | Kubernetes annotation value for health checks | `true` |
| `FLOWX_PLATFORMHEALTH_DISCOVERYINTERVAL` | Interval at which the platform re-discovers deployed services automatically | `PT5M` |
| `FLOWX_PLATFORMHEALTH_DISCOVERYINITIALDELAY` | Delay before the first automatic service discovery run after startup | `PT30S` |

***

## Multi-edit and undo/redo configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_MULTIEDIT_TTL` | Time-to-live for multi-edit sessions in seconds | `45` |
| `FLOWX_UNDOREDO_TTL` | Time-to-live for undo/redo actions in seconds | `86400` |
| `FLOWX_UNDOREDO_CLEANUP_CRONEXPRESSION` | Cron expression for undo/redo cleanup | `0 0 2 ? * *` |
| `FLOWX_UNDOREDO_CLEANUP_DAYS` | Days to keep deleted undo/redo items | `2` |

***

## Resources usage configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LIB_RESOURCESUSAGES_ENABLED` | Enable resources usage tracking | `true` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLED` | Enable listener for resource usage refreshes | `true` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNT` | Thread count for resource usage collector | `5` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZE` | Maximum batch size for resource usage collection | `1000` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGESREFRESH` | Consumer group ID for resource usage refresh | `admin-resources-usages-refresh-group` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGESREFRESH` | Number of consumer threads for resource usage refresh | `3` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_TOPIC_RESOURCE_USAGES_REFRESH` | Kafka topic for resource usage refresh | `${kafka.topic.resources-usages.refresh}` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval in seconds after auth exceptions | `3` |

***

## Authentication and Authorization Configuration

The FlowX Admin microservice supports authentication and authorization through OpenID Connect (with Keycloak as the default provider) and allows detailed role-based access control.

### Security type

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2CLIENT` | Enable OAuth2 client | `enabled` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

### Service account configuration

The Admin service authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-admin-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. The `OPENID_PROVIDER` / `OPENID_KEYCLOAK_*` / `OPENID_ENTRA_*` identity-provider block was also removed from the Admin service in 5.9.0. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

> [!NOTE]
>
> When deploying with the FlowX Helm chart, `SECURITY_OAUTH2_BASESERVERURL` is supplied through the chart value `flowx.keycloak.baseServerUrl` and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.

### Designer authentication client

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_AUTHENTICATE_CLIENTID` | Client ID for authentication service | `flowx-platform-authenticate` |

> [!NOTE]
>
> The role-based access control is configured in the application YAML and grants specific permissions for platform management, user management, process management, integrations management, and configuration management.

***

## Ingress and CORS

The Admin service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/` | `/` |

The path is set through `services.admin.ingress.admin.path` (or `services.admin.gateway.admin.paths`) in the chart values. Override only if you serve FlowX Admin under a different prefix.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Admin. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

> [!WARNING]
>
> In production environments, never use the default service account credentials. Always configure secure, environment-specific credentials for authentication.

> [!WARNING]
>
> Sensitive information such as passwords and client secrets should be managed securely using environment variables or a secrets management solution in production environments.

***

## Troubleshooting

### Common issues

> [accordion] Admin service fails to start
>
> **Symptoms:** Service crashes on startup or fails health checks.
>
> **Solutions:**
>
> 1. Verify PostgreSQL connection parameters (`SPRING_DATASOURCE_URL`, credentials) are correct and the database is reachable
> 2. Check that MongoDB is running and the connection URI is valid
> 3. Ensure Kafka brokers are accessible at the configured `SPRING_KAFKA_BOOTSTRAPSERVERS` address
> 4. Review startup logs for specific error messages indicating which dependency is unavailable

> [accordion] Cannot export or import resources
>
> **Symptoms:** Import/export operations fail with permission or authentication errors.
>
> **Solutions:**
>
> 1. Verify the Keycloak service account has the required roles for import/export operations
> 2. Check that `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` and `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` are configured correctly
> 3. Ensure the service account has `canImport` access rights in the target workspace
> 4. Confirm the target application version is in a WIP state

> [accordion] Build creation fails
>
> **Symptoms:** Creating a build returns errors or times out.
>
> **Solutions:**
>
> 1. Check connectivity between Admin and the application-manager service
> 2. Verify that the Kafka topics for build operations (`KAFKA_TOPIC_BUILD_RUNTIMEDATA`) are created and accessible
> 3. Ensure version compatibility between Admin and application-manager services
> 4. Review Kafka consumer group lag for build-related topics

> [accordion] UI not loading in Designer
>
> **Symptoms:** Designer interface fails to render or returns blank pages.
>
> **Solutions:**
>
> 1. Verify the Designer service is running and healthy
> 2. Check ingress configuration — ensure the Admin ingress (`admin-admin`) is correctly routing traffic
> 3. Review CORS settings in the [Ingress Configuration Guide](./ingress-configuration)
> 4. Confirm that the `Fx-Workspace-Id` header is being passed correctly through the ingress

***

## Related resources

> [card] [Configuring an IAM Solution](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup for Keycloak and Microsoft Entra ID

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Ingress Configuration](./ingress-configuration)
>
> Centralized ingress guide with CORS configuration and best practices


# FlowX Advancing Controller setup
Source: https://docs.flowx.ai/5.9/setup-guides/advancing-controller-setup-guide

This guide provides step-by-step instructions to help you configure and deploy the Advancing Controller effectively.

## Infrastructure prerequisites

Before setting up the Advancing Controller, ensure the following components are properly set up:

* **FlowX.AI Engine Deployment**: The Advancing Controller depends on the FlowX Engine and must be deployed in the same environment. Refer to the FlowX Engine [**setup guide**](./flowx-engine-setup-guide/engine-setup) for more information on setting up the Engine.
* **Database Instance**: The Advancing Controller uses a PostgreSQL or Oracle Database instance as its database.

***

## Dependencies

Ensure the following dependencies are met:

* [Database](#database-configuration): Properly configured database instance.
* [Datasource](#configuring-datasource): Configuration details for connecting to the database.
* [FlowX.AI Engine](./flowx-engine-setup-guide/engine-setup): Must be set up and running. Refer to the FlowX Engine setup guide.

### Database compatibility

The Advancing Controller supports both PostgreSQL and Oracle databases. However, the FlowX.AI Engine and the Advancing Controller must be configured to use the same type of database at any given time. The FlowX.AI Engine employs two databases: one shared with the FlowX.AI Admin microservice for process metadata and instances, and the other dedicated to advancement.

> [!WARNING]
>
> Mixing PostgreSQL and Oracle Database is not supported; both databases must be of the same type.

***

## Database configuration

### PostgreSQL

A basic PostgreSQL configuration for Advancing.

> [!WARNING]
>
> If the parallel advancing configuration already exists, you must reset the 'advancing' database by executing the SQL command `DROP DATABASE advancing;`. Once the database has been dropped, the Liquibase script will automatically re-enable it.

***

## Configuration

The Advancing Controller uses a PostgreSQL or an Oracle database as a dependency.

* Ensure that the user, password, connection link, and database name are correctly configured. If these details are not configured correctly, errors will occur at startup.
* The datasource is configured automatically via a Liquibase script inside the engine. All updates will include migration scripts.

### Configuring datasource

If you need to change the datasource configuration detail, you can use the following environment variables:

| Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC URL for database connection | `jdbc:postgresql://postgresql:5432/advancing` |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class name | `org.postgresql.Driver` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `[your-secure-password]` |
| `SPRING_JPA_DATABASE` | Database type (accepted values: `oracle` or `postgresql`) | `postgresql` |
| `SPRING_JPA_SHOWSQL` | Toggle SQL query logging | `false` |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULT_SCHEMA` | Default database schema (❗️only for Oracle DBs) | `public` |
| `SPRING_LIQUIBASE_CHANGELOG` | Path to Liquibase changelog for database migrations | `classpath:config/liquibase/master.xml` |

> [!NOTE]
>
> It's important to keep in mind that the Advancing Controller is tightly integrated with the FlowX.AI Engine. Therefore, it is crucial to ensure that both the Engine and the Advancing Controller are configured correctly and are in sync.

***

## Health monitoring

| Variable | Description | Default Value |
| - | - | - |
| `MANAGEMENT_HEALTH_DB_ENABLED` | Enable database health checks | `true` |

***

## Troubleshooting

### Common issues

> [accordion] Process instances stuck and not advancing
>
> **Symptoms:** Process instances remain in a pending state and do not advance to the next node.
>
> **Solutions:**
>
> 1. Check Kafka connectivity and verify that the Advancing Controller can reach the Kafka brokers
> 2. Review the Advancing Controller logs for errors or warnings related to message consumption
> 3. Monitor consumer group lag to determine if messages are accumulating without being processed
> 4. Verify that the FlowX Engine is running and responsive

> [accordion] Advancing Controller fails to start
>
> **Symptoms:** The service crashes or exits during startup with connection errors.
>
> **Solutions:**
>
> 1. Verify the PostgreSQL (or Oracle) connection string and credentials are correct
> 2. Check that the Kafka broker configuration is valid and the brokers are reachable
> 3. Ensure the PostgreSQL (or Oracle) database is accessible and the `advancing` database exists
> 4. Review the Liquibase migration logs for schema issues

> [accordion] Timeout errors during token advancement
>
> **Symptoms:** Logs show timeout exceptions when advancing tokens between nodes.
>
> **Solutions:**
>
> 1. Review process complexity — deeply nested subprocesses or large parallel gateways may require longer timeouts
> 2. Monitor Kafka response times to identify broker-side latency
> 3. Verify that downstream services responding via Kafka are healthy and not overloaded

> [accordion] High CPU usage
>
> **Symptoms:** The Advancing Controller pod shows consistently high CPU utilization.
>
> **Solutions:**
>
> 1. Check thread pool settings and reduce concurrency if the system is over-provisioned
> 2. Monitor the number of concurrent process instances being advanced
> 3. Review Kafka consumer configuration — a high number of partitions with aggressive polling can increase CPU load
> 4. Consider scaling horizontally by adding additional replicas

***

## Related resources

> [card] [Advancing Controller](../docs/platform-deep-dive/core-components/advancing-controller)
>
> Learn how the Advancing Controller manages process instance progression

> [card] [FlowX Engine Setup](./flowx-engine-setup-guide/engine-setup)
>
> Configure the FlowX Engine that the Advancing Controller depends on

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes


# AI Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/ai-gateway-setup

Set up the AI Gateway microservice — powers the AI chat experience in the FlowX Designer, streaming AI assistant responses to the browser and routing requests to the config-time agents.

> [!NOTE]
>
> The AI Gateway is a core service that owns the Designer AI chat surface. It streams AI assistant responses to the browser over Server-Sent Events (SSE) and routes chat requests to the config-time agents.

## Dependencies

Before setting up the AI Gateway, ensure you have the following dependencies in place:

* **MongoDB** for storing conversation context
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained, workspace-level authorization on AI interactions
* **AI Platform** — the config-time agents the gateway routes chat requests to

## Infrastructure prerequisites

| Component | Description |
| - | - |
| MongoDB | Stores AI chat conversation context |
| Keycloak | Identity provider for service authentication |
| SpiceDB | Authorization service for workspace validation |
| AI Platform | Config-time agents that handle chat requests |

***

## Configuration

### Authorization configuration

The AI Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-ai-gateway-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

***

### AI Platform routing

The AI Gateway forwards chat requests to the config-time agents and the planner. In Kubernetes these default to the in-cluster service names — override them only for custom networking or mixed deployments.

> [!WARNING]
>
> Starting with 5.9.2, AI Platform services are deployed under their plain names — the `ai-platform-` prefix is dropped. The defaults below reflect the new names. If you upgrade the core services and the AI Platform chart separately, or you overrode these variables with the old prefixed names, align them — mixed naming breaks AI features. See the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming).

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PLANNER_HOST` | Planner service hostname | `planner` |
| `FLOWX_PLANNER_PORT` | Planner service port | `9100` |
| `FLOWX_AGENTS_AIANALYST_BASEURL` | AI Analyst agent base URL | `http://ai-analyst:9100` |
| `FLOWX_AGENTS_AIARCHITECT_BASEURL` | AI Architect agent base URL | `http://ai-architect:9100` |
| `FLOWX_AGENTS_AIASSISTANT_BASEURL` | AI Assistant agent base URL | `http://ai-assistant:9100` |
| `FLOWX_AGENTS_AIDESIGNER_BASEURL` | AI Designer agent base URL | `http://ai-designer:9100` |
| `FLOWX_AGENTS_AIDEVELOPER_BASEURL` | AI Developer agent base URL | `http://ai-developer:9100` |
| `FLOWX_DOCUMENTPLUGIN_BASEURL` | Document plugin base URL | `http://document-plugin:80` |

***

### MongoDB configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | - |

***

### CAS lib configuration (SpiceDB)

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB gRPC port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. Keep the default unless instructed by FlowX. | `CUSTOM` |

***

### Logging configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |

***

## Secrets management

| Secret Name | Description |
| - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI (contains credentials) |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token |

***

## Ingress and CORS

The AI Gateway is exposed on the admin host because the Designer connects to it directly from the browser. Because it streams chat responses over SSE, the ingress must allow long-lived connections — the FlowX deploy chart raises the default proxy read/send timeouts for this service so streams are not cut mid-flight.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Must include every Designer domain that uses AI chat. Supports wildcard subdomains (`https://*.yourcompany.com`). | `-` |

Allowed methods, allowed headers, and credential handling are baked into the service's `application.yaml` with safe defaults. For the complete route reference and Gateway API HTTPRoute configuration, see the [ingress configuration guide](./ingress-configuration).

***

## Deployment

### Helm values example

```yaml theme={"dark"}
fullnameOverride: ai-gateway

image:
  registry: <your-registry>
  repository: ai-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # OAuth2
  SECURITY_TYPE: oauth2
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

  # CORS — origins that use the Designer AI chat
  APPLICATION_CORS_ALLOWORIGIN: https://designer.example.com

extraEnvVarsMultipleSecretsCustomKeys:
  - name: mongodb-generic
    secrets:
      SPRING_DATA_MONGODB_URI: mongodb-uri
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: true
  admin:
    enabled: true

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/routing-name: "ai-gateway"
  flowx.ai/prometheus-scrape: "ai-gateway"
```

> [!NOTE]
>
> The `image.registry` and `image.repository` split applies to **5.9.4 and later**. To redirect every chart at once, use `global.imageRegistry`. See [Container images and registry](./setup-guides-overview#container-images-and-registry).

> [!NOTE]
>
> The AI Gateway requires ingress to be enabled because the Designer connects to it from the browser to open AI chat streams.

***

## Verify your setup

> [!TIP]
>
> The AI Gateway pod is running and healthy: `kubectl get pods -l app=ai-gateway`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://ai-gateway:8080/actuator/health`

> [!TIP]
>
> SpiceDB connection is established — check pod logs for successful CAS client initialization

> [!TIP]
>
> AI chat opens in the Designer and streams a response without the connection dropping

***

## Troubleshooting

> [accordion] AI chat stream drops mid-response
>
> **Solutions:**
>
> 1. Confirm the ingress proxy read/send timeouts are raised for the AI Gateway route (SSE needs long-lived connections)
> 2. Check that no intermediate proxy buffers or closes the SSE stream
> 3. Review pod logs for upstream errors from the config-time agents

> [accordion] AI chat returns a CORS error in the browser
>
> **Solutions:**
>
> 1. Add the Designer origin to `APPLICATION_CORS_ALLOWORIGIN`
> 2. Verify the request reaches the AI Gateway on the admin host

> [accordion] SpiceDB connection failures
>
> **Solutions:**
>
> 1. Verify SpiceDB is running and reachable at the configured host and port
> 2. Check that the SpiceDB token is correct
> 3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`

***

## Related resources

> [card] [AI Platform setup](./ai-platform-setup)
>
> Config-time agents and AI infrastructure

> [card] [SpiceDB Configuration](./spicedb)
>
> Fine-grained authorization setup

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup

> [card] [Ingress configuration](./ingress-configuration)
>
> Routing and CORS reference


# AI Platform setup
Source: https://docs.flowx.ai/5.9/setup-guides/ai-platform-setup

Infrastructure requirements, service configuration, and deployment guide for the FlowX.AI AI Platform.

> [!WARNING]
>
> **AI Platform is required infrastructure in 5.5+.** At startup, the `integration-designer` core service unconditionally opens gRPC channels to the **Agent Builder** (`flowx.agent-builder.host`/`flowx.agent-builder.port`) and **Knowledge Base RAG** (`flowx.kb-rag.host`/`flowx.kb-rag.port`) services — there is no `@ConditionalOnProperty` flag to skip them. These properties default to the in-cluster service names (`agent-builder`, `knowledgebase-rag` starting with 5.9.2; `ai-platform-agent-builder`, `ai-platform-knowledgebase-rag` on 5.9.0/5.9.1), so the service starts out of the box, but AI workflow nodes and knowledge-base retrieval fail at runtime unless those services are reachable.
>
> To run FlowX without AI features, you still need to deploy the AI Platform chart (or point the env vars at reachable stub endpoints). Hiding AI surfaces (the AI floating action button, Chat UI component, AI agents) is controlled separately and has two paths:
>
> * **Globally — deployment-level kill switch.** Point the AI service-name properties on the `admin` service at services that are not deployed in your environment. The `/api/init` response then reports the corresponding flag as `false` under `environmentConfiguration.admin-mngt`, and the Designer hides the matching AI surfaces for everyone regardless of role. This is the right option for deployments that do not use AI at all.
> * **Per-user — role permissions.** Strip the AI permission keys (`aiagent_edit`, `org_ai_providers_*`, `wks_ai_models_*`) from specific roles via the role-mapper. See the [Complete roles & permissions matrix](/5.9/setup-guides/access-management/roles-permissions-matrix).
>
> Both gates apply: an AI surface appears only when its availability flag is true **and** the user has the matching permission.

> [!NOTE]
>
> **Starting with FlowX.AI 5.9.1**, AI availability is split into two independent flags so you can enable runtime AI and build-time AI separately. The single `aiServiceName` property (and its `ai-is-enabled` flag) is replaced by:
>
> | Property (on `admin`) | `/api/init` flag | Governs |
> | - | - | - |
> | `flowx.feature-availability.aiRuntimeServiceName` | `ai-runtime-is-enabled` | Runtime AI: AI workflow nodes, chat-driven workflows, evaluations |
> | `flowx.feature-availability.aiDevtimeServiceName` | `ai-devtime-is-enabled` | Build-time AI: AI Designer, Agent Builder, AI Assistant/Analyst/Developer, AI-assisted code generation |
>
> Point a property at a service that is not deployed to turn off that group of AI surfaces. To turn off all AI, set both.

## Overview

The AI Platform consists of two layers:

* **Python services** — AI agent and orchestration services for planning, code generation, analysis, design, knowledge retrieval, and embeddings (REST + gRPC)
* **Event-driven workers** — Background services consuming Kafka topics for knowledge-base indexing

All inter-service communication uses gRPC with Protobuf contracts, except the config-time agents (AI Developer, AI Analyst, AI Designer) and Agent Builder, which expose REST endpoints.

***

## Infrastructure requirements

> [card] Qdrant
>
> Vector database for embeddings. Cluster mode recommended for production.

> [card] S3-compatible storage
>
> Object storage for binaries and files. Any S3-compatible provider works (MinIO, AWS S3, etc.).

> [card] PostgreSQL
>
> Job and state store for AI services such as Document Parser, Speech to Text, and KB Enrichment. Each service uses its own database.

> [card] Kafka
>
> Message broker for event-driven communication. KRaft mode supported.

> [card] Keycloak
>
> Identity provider for OAuth2 authentication across all services.

> [card] SpiceDB
>
> Fine-grained authorization system for access control.

***

## Service architecture

The AI Platform is a set of Python services. In Kubernetes, every service listens on port **9100** (set via the `SERVICE_PORT` variable).

| Service (Kubernetes name) | Protocol | Purpose |
| - | - | - |
| `planner` | gRPC | Generates execution plans from user prompts (intent understanding and orchestration) |
| `agent-builder` | gRPC | Configuration and runtime for low-code AI nodes |
| `knowledgebase-rag` | gRPC | Retrieval-augmented generation over the knowledge base |
| `embedder` | gRPC | Embedding generation (also consumes durable embedding jobs from Kafka) |
| `knowledgebase-indexer-v2` | Kafka worker | Generates retrieval vectors; event-driven, consumes the knowledge-base index-request topic |
| `kb-enrichment` | gRPC + Kafka worker | Design-time document intelligence over knowledge-base documents (replaces `di-platform`); consumes the enrichment-request topic |
| `ai-analyst` | HTTP | Process-design expertise (config-time agent) |
| `ai-architect` | HTTP | Project data model generation (config-time agent) |
| `ai-assistant` | HTTP | FlowX.AI documentation assistant |
| `ai-designer` | HTTP | UI design and implementation expertise (config-time agent) |
| `ai-developer` | HTTP | Coding expertise (config-time agent) |

> [!NOTE]
>
> **Starting with 5.9.2**, AI Platform services are deployed under the plain names shown above — the `ai-platform-` prefix is dropped from pod and service names. On 5.9.0 and 5.9.1 the same services carry the `ai-platform-` prefix (for example, `ai-platform-planner`). If you have monitoring, alerts, or host overrides that use the prefixed names, update them when upgrading — see the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming). The `ai-architect` service is available only starting with 5.9.2 — it does not exist in 5.9.0 or 5.9.1 deployments.

> [!NOTE]
>
> The Designer AI chat surface routes through the **`ai-gateway`** service (part of the core services), which calls `planner` and the agent services. The **`evals-judge`** worker, deployed alongside the AI Platform, consumes `ai.flowx.ai-platform.evals-judge.job.request.v1` for [evaluations](../ai-platform/evaluations).

### Per-service setup guides

Most AI Platform services deploy as subcharts with no standalone configuration and are covered by this guide. Services with their own operator-facing setup — external dependencies, secrets, storage, ports, or tunables — have a dedicated setup guide, grouped by the same deployment tiers as the [deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#ai-components):

| Tier | Service | Setup guide |
| - | - | - |
| AI Base | Qdrant (vector database) | [Qdrant setup](/5.9/setup-guides/qdrant) |
| AI Base | Document Parser | [Document Parser setup](/5.9/setup-guides/document-parser-setup) |
| AI Runtime | Speech-to-Text | [Speech-to-Text setup](/5.9/setup-guides/speech-to-text-setup) |
| AI Runtime | Web Crawler | [Web Crawler setup](/5.9/setup-guides/web-crawler-setup) |
| AI Dev Time | AI Gateway | [AI Gateway setup](/5.9/setup-guides/ai-gateway-setup) |
| AI Dev Time | KB Enrichment | [KB Enrichment setup](/5.9/setup-guides/kb-enrichment) |
| AI Extensions | ModPod | [ModPod setup](/5.9/setup-guides/modpod-setup) |
| AI Extensions | Observatory | [Observatory setup](/5.9/observatory/setup/self-hosted) |

All other AI services (`embedder`, `knowledgebase-rag`, `knowledgebase-indexer-v2`, `planner`, `agent-builder`, the config-time agents, `data-privacy`, `doc-converter`, `evals-judge`) are pure subcharts configured through this guide. `flowx-docs` (the in-product documentation host) also deploys as a subchart with no operator-facing configuration.

### KB Enrichment

`ai-platform-kb-enrichment` (new in 5.9.1) replaces `di-platform` for design-time document intelligence. It deploys as a subchart but has extra requirements — a dedicated `kbenrichment` PostgreSQL database, an object-storage bucket, a Hugging Face model download on first start, `doc-parser` enabled, and an organization `TEXT_GENERATION` LLM capability. See the [KB Enrichment setup guide](/5.9/setup-guides/kb-enrichment) for the full steps. The Qdrant collection `knowledgebases_design` is auto-created by the `embedder` service.

***

## Environment variables

> [tab] Service discovery
>
> These variables control how services locate each other within the cluster:
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `GRPC_HOST_RESOLVER` | Service discovery method | `k8s` |
> | `GRPC_HOST_RESOLVER_HELM_CHART` | Helm chart name for K8s service resolution | — |
> | `GRPC_HOST_RESOLVER_FIXED_IP` | Fixed IP/hostname when using `host` resolver | `ai-platform` |
> | `SERVICE_PORT` | Port the service listens on | `9100` (production) |
>
> **Kubernetes deployment:**
>
> ```bash theme={"dark"}
> GRPC_HOST_RESOLVER=k8s
> GRPC_HOST_RESOLVER_HELM_CHART=ai-platform
> ```
>
> **Docker Compose / local deployment:**
>
> ```bash theme={"dark"}
> GRPC_HOST_RESOLVER=host
> GRPC_HOST_RESOLVER_FIXED_IP=localhost
> ```

> [tab] Authentication
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `SECURITY_OAUTH2_BASE_SERVER_URL` | Keycloak auth server base URL | — |
> | `SECURITY_OAUTH2_REALM` | OAuth2 realm name | — |
> | `SECURITY_OAUTH2_CLIENT_ID` | OAuth2 client ID | — |
>
> #### SpiceDB authorization
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | — |
> | `FLOWX_SPICEDB_PORT` | SpiceDB server port | — |
> | `FLOWX_SPICEDB_TOKEN` | SpiceDB API token | — |
>
> #### Organization manager
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL` | Organization Manager service URL | `http://organization-manager:80` |

> [tab] Infrastructure
>
> #### Qdrant (vector database)
>
> Qdrant connection (`QDRANT_CONNECTION_GRPC_ENDPOINT`, `QDRANT_CONNECTION_API_KEY`, `QDRANT__CLUSTER__ENABLED`), search-tuning (`QDRANT_PREFETCH_LIMIT`, `QDRANT_FUSION_LIMIT`), and planner-seeding (`PLANNER_SEED_ENABLED`) variables are documented in the [Qdrant setup guide](/5.9/setup-guides/qdrant).
>
> #### Kafka
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses | — |
> | `KAFKA_SECURITY_MODE` | Kafka security protocol | `NONE` |
>
> #### S3-compatible storage
>
> AI services read their object storage settings under one of two prefixes. Storage blocks with the `documents` alias in the Helm chart render as `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_*`, and all other storage blocks render as `APPLICATION_FILE_STORAGE_S3_*`. For the bucket each AI service uses, see [AI Platform buckets](/5.9/docs/platform-overview/data-architecture#ai-platform-buckets).
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `APPLICATION_FILE_STORAGE_S3_SERVER_URL` | S3 endpoint URL | — |
> | `APPLICATION_FILE_STORAGE_S3_ACCESS_KEY` | S3 access key | — |
> | `APPLICATION_FILE_STORAGE_S3_SECRET_KEY` | S3 secret key | — |
> | `APPLICATION_FILE_STORAGE_S3_BUCKET_NAME` | S3 bucket name | — |
> | `APPLICATION_FILE_STORAGE_S3_ROOT_DIRECTORY` | Root directory within bucket | — |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SERVER_URL` | S3 endpoint URL, `documents` storage block | — |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_ACCESS_KEY` | S3 access key, `documents` storage block | — |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SECRET_KEY` | S3 secret key, `documents` storage block | — |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` | S3 bucket name, `documents` storage block | — |
> | `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET` | Auto-create bucket if missing | `true` |
> | `APPLICATION_FILE_STORAGE_ENABLED` | Enable file storage for conversations | `false` |

> [tab] AI models
>
> > [!NOTE]
> >
> > LLM provider and model configuration lives in the **AI Providers** UI in FlowX Designer. Configure providers and models at the organization and workspace level rather than via per-service env vars.
> >
> > See the [AI providers and model configuration](/5.9/ai-platform/ai-providers) page for details.
>
> #### Organization manager connection
>
> All Python AI services require a connection to the Organization Manager to resolve LLM provider configuration:
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL` | Organization Manager service URL for LLM config resolution | `http://organization-manager:80` |
>
> These variables must be set on all Python services (Planner, AI Developer, AI Analyst, AI Designer, Agent Builder, Knowledgebase RAG, Embedder).

> [tab] Observability
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `FLOWX_OTEL_ENDPOINT` | OpenTelemetry Collector endpoint | — |
> | `FLOWX_OTEL_DEBUG` | Enable OTEL debug logging | `false` |
>
> #### Observatory integration (optional)
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `FLOWX_OBSERVATORY_API_URL` | Observatory API endpoint | — |
> | `FLOWX_OBSERVATORY_APP_ID` | Observatory app identifier | — |
> | `FLOWX_OBSERVATORY_VERBOSE` | Enable verbose Observatory logging | `0` |
>
> #### Debug logging
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `VERBOSE` | Enable verbose logging | `0` |

> [tab] Service endpoints
>
> Override individual service endpoints using the `AI_SERVICE_<SERVICE_ID>_ENDPOINT` pattern:
>
> | Environment Variable | Target Service | Default Port |
> | - | - | - |
> | `AI_SERVICE_PLANNER_ENDPOINT` | Planner | 9150 |
> | `AI_SERVICE_AI_DEVELOPER_ENDPOINT` | AI Developer | 9151 |
> | `AI_SERVICE_AI_ANALYST_ENDPOINT` | AI Analyst | 9152 |
> | `AI_SERVICE_AI_DESIGNER_ENDPOINT` | AI Designer | 9153 |
> | `AI_SERVICE_AGENT_BUILDER_ENDPOINT` | Agent Builder | 9154 |
> | `AI_SERVICE_KNOWLEDGEBASE_RAG_ENDPOINT` | Knowledgebase RAG | 9155 |
> | `AI_SERVICE_KB_ENRICHMENT_ENDPOINT` | KB Enrichment | 9158 |
>
> **Example:**
>
> ```bash theme={"dark"}
> AI_SERVICE_AGENT_BUILDER_ENDPOINT=host.docker.internal:9154
> ```
>
> > [!NOTE]
> >
> > When using Kubernetes service discovery (`GRPC_HOST_RESOLVER=k8s`), these overrides are typically not needed. Use them only for custom networking or mixed deployment scenarios.

***

## Agent Builder configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `AGENT_BUILDER_MAX_TOOL_CALLS` | Maximum number of tool calls an agent can make in a single workflow execution | `20` |

***

## Kafka topics

The AI Platform uses the following internal Kafka topics:

| Topic | Partitions | Purpose |
| - | - | - |
| `ai.flowx.ai-platform.knowledgebase.store-entry.index-request.v1` | 1 | Indexing requests consumed by Knowledgebase Indexer v2 |
| `ai.flowx.ai-platform.knowledgebase.store-entry.index-response.v1` | 1 | Indexing results produced by Knowledgebase Indexer v2 |
| `ai.flowx.ai-platform.knowledgebase.internal.enrichment-request.v1` | 3 | Enrichment requests from Knowledgebase Indexer v2 to KB Enrichment |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | 3 | Judge job requests from `integration-designer` to `evals-judge` |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | 3 | Scored responses from `evals-judge` back to `integration-designer` |
| `ai.flowx.ai-platform.evals-judge.job.dlq.v1` | 3 | Dead-letter queue for unscored judge jobs (manual operator review) |
| `ai.flowx.evals.suggestions.job.request.v1` | 3 | Improvement-suggestion requests from `integration-designer` to `evals-judge` |
| `ai.flowx.evals.suggestions.job.response.v1` | 3 | Improvement suggestions from `evals-judge` back to `integration-designer` |
| `ai.flowx.evals.suggestions.job.dlq.v1` | 3 | Dead-letter queue for suggestion jobs that could not be completed |

> [!NOTE]
>
> For production environments, create these topics manually with appropriate replication factors. For development, Kafka auto-topic creation handles them automatically.

***

## Deployment

> [tab] Kubernetes (Helm)
>
> > [!WARNING]
> >
> > **FlowX.AI 5.9.6 and later:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](./migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).
>
> Up to FlowX.AI 5.9.5, the AI Platform ships as an umbrella Helm chart aggregating all microservices and infrastructure dependencies.
>
> **Install or upgrade (FlowX.AI 5.9.5 and earlier):**
>
> ```bash theme={"dark"}
> helm dependency update deployment/helm/ai-platform
> helm upgrade --install ai-platform deployment/helm/ai-platform \
>   --set global.aiPlatformVersion=<version>
> ```
>
> **After deployment, initialize the platform:**
>
> ```bash theme={"dark"}
> make initialize-platform
> ```
>
> #### Key Helm values
>
> **Replica counts:**
>
> | Service | Default Replicas |
> | - | - |
> | Planner | 2 |
> | AI Developer | 2 |
> | AI Analyst | 2 |
> | AI Designer | 2 |
> | Agent Builder | 2 |
> | Knowledgebase RAG | 2 |
> | Embedder | 2 |
>
> **Global configuration:**
>
> ```yaml theme={"dark"}
> global:
>   flowx:
>     idp:
>       provider: keycloak
>       keycloak:
>         url:
>           host: <your-keycloak-host>
>         realm: <your-realm>
>   telemetry:
>     prometheus: enabled
>     otelCollector: enabled
> ```

> [tab] Docker Compose
>
> > [!WARNING]
> >
> > Docker Compose deployment is intended for **local development only**. Do not use it for production workloads.
>
> ```bash theme={"dark"}
> make run-in-docker AI_PLATFORM_VERSION=<version> AI_PLATFORM_ARCH=linux/arm64
> ```
>
> This starts all microservices plus infrastructure (Qdrant, MinIO, Kafka, monitoring stack).
>
> **Local Kubernetes (Kind):**
>
> ```bash theme={"dark"}
> make run-in-k8s AI_PLATFORM_VERSION=<version>
> ```

***

## Storage requirements

| Component | Default Persistent Volume | Notes |
| - | - | - |
| Qdrant data | 30Gi | Vector embeddings |
| Qdrant snapshots | 30Gi | Backup snapshots |
| MinIO | Distributed across 4 nodes | Configured per deployment |
| Kafka | 1Gi minimum | Adjust based on message volume |

***

## Troubleshooting

> [accordion] Service discovery issues
>
> **Kubernetes DNS resolution:**
>
> ```bash theme={"dark"}
> # Verify AI Platform services are running
> kubectl get services -l app=ai-platform
>
> # Check Helm deployment
> helm list -n ai-platform
>
> # Test DNS resolution (5.9.2+; on 5.9.0/5.9.1 use ai-platform-planner)
> nslookup planner.default.svc.cluster.local
> ```
>
> **Common causes:**
>
> * Incorrect `GRPC_HOST_RESOLVER_HELM_CHART` value
> * Services not in the same namespace
> * DNS not resolving due to CoreDNS issues

> [accordion] Database connectivity
>
> **Qdrant health check:**
>
> ```bash theme={"dark"}
> curl http://<qdrant-host>:6333/healthz
> ```
>
> **Common causes:**
>
> * Missing `QDRANT_CONNECTION_API_KEY`
> * Qdrant cluster not fully initialized

> [accordion] Kafka connectivity
>
> **Verify broker availability:**
>
> ```bash theme={"dark"}
> kafka-broker-api-versions --bootstrap-server <kafka-host>:9092
> ```
>
> **Verify topics exist:**
>
> ```bash theme={"dark"}
> kafka-topics --bootstrap-server <kafka-host>:9092 --list | grep ai-platform
> ```
>
> **Common causes:**
>
> * Wrong `KAFKA_BOOTSTRAP_SERVERS` address
> * Topics not auto-created and not manually provisioned
> * Security mode mismatch (`KAFKA_SECURITY_MODE`)

> [accordion] Authentication problems
>
> **Verify Keycloak connectivity:**
>
> ```bash theme={"dark"}
> curl https://<keycloak-host>/auth/realms/<realm>/.well-known/openid-configuration
> ```
>
> **Common causes:**
>
> * Incorrect `SECURITY_OAUTH2_BASE_SERVER_URL`
> * Realm name mismatch
> * Client ID not registered in Keycloak
> * SpiceDB token expired or misconfigured

> [accordion] AI model configuration errors
>
> If AI nodes fail with model-related errors:
>
> * Verify that an AI provider is configured at **Organization Settings** → **AI Settings** → **Model Providers** with a successful connection test
> * Check that models are enabled in the provider's whitelist
> * Verify that workspace-type model assignments are set for the relevant AI capability (text generation, image understanding, embeddings, document/OCR) under **AI Settings** → **Defaults & Fallbacks**
> * Ensure `FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL` is set on all Python AI services and points to a reachable Organization Manager instance
>
> See the [AI providers and model configuration](/5.9/ai-platform/ai-providers) page for setup details.

***

## Related resources

> [card] [AI in FlowX](../ai-platform/ai-in-flowx)
>
> Overview of config-time and business AI agents

> [card] [Agent Builder](../ai-platform/agent-builder/overview)
>
> Build custom AI agents with the no-code agent builder

> [card] [Deployment guidelines v5.9.1](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1)
>
> Component versions and upgrade instructions


# Application Manager setup
Source: https://docs.flowx.ai/5.9/setup-guides/application-manager

Set up the Application Manager backend microservice for managing FlowX apps, libraries, versions, manifests, and builds.

The Application Manager is a backend microservice in FlowX.AI that:

✅ Manages FlowX applications, versions, manifests, and configurations.\
✅ Acts as a proxy for front-end resource requests.

## Infrastructure prerequisites

Before you start setting up the Application Manager service, ensure the following infrastructure components are in place:

| Component | Purpose |
| - | - |
| PostgreSQL | Storing application data |
| MongoDB | Managing runtime builds |
| Redis | Caching needs |
| Kafka | Event-driven communication |
| OAuth2 Server | Authentication |

> [!NOTE]
>
> Ensure that the database for storing application data is properly set up and configured before starting the service.

## Dependencies

The Application Manager relies on other FlowX services and components to function properly:

* [**Database configuration**](#database-configuration): For storing application details, manifests, and configurations.
* [**Authorization & Access Management**](#authentication-configuration): For securing access to resources and managing roles.
* [**Kafka Event Bus**](#kafka-configuration): For enabling event-driven operations.
* [**Resource Proxy**](#resource-proxy-configuration): To forward resource-related requests to appropriate services.

## Core configuration environment variables

### Basic service configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_FILE_SIZE` | Maximum file upload size | `25MB` |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum request size | `25MB` |
| `LOGGING_CONFIG` | Logging configuration file | `logback-spring.xml` |

### Database configuration

#### PostgreSQL configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | PostgreSQL JDBC URL | `jdbc:postgresql://postgresql:5432/app_manager` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `password` |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class | `org.postgresql.Driver` |

#### MongoDB configuration

The Application Manager requires MongoDB to store runtime build information. Use the following environment variables for configuration:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME` | MongoDB username | `app-runtime` |
| `DB_PASSWORD` | MongoDB password | `password` |
| `SPRING_DATA_MONGODB_STORAGE` | Storage type (Azure environments only) | `mongodb` (alternative: `cosmosdb`) |

## Redis configuration

Application Manager uses Redis for caching when required. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

## Kafka configuration

### Kafka connection and security variables

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Kafka broker addresses | `kafka-flowx-kafka-bootstrap:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol | `PLAINTEXT` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size | `52428800` (50MB) |
| `FLOWX_KAFKA_PAYLOADSIZELIMIT` | Payload size limit | `512000` (500KB) |

### Kafka producer configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_PRODUCER_KEYSERIALIZER` | Key serializer class | `org.apache.kafka.common.serialization.StringSerializer` |
| `SPRING_KAFKA_PRODUCER_PROPERTIES_MAX_REQUEST_SIZE` | Maximum request size | `52428800` (50MB) |

### OAuth authentication variables (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

### Kafka consumer configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_EXPORT` | Application export consumer group | `app-resource-export-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_IMPORT` | Application import consumer group | `app-resource-import-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_USAGES` | Resource usages consumer group | `app-resource-usages-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATIONRESP` | Resource element validation group | `app-resource-elem-usage-validation-resp` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_COPY` | Resource copy consumer group | `app-resource-copy-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_SYNC` | Resource sync consumer group | `app-resource-sync-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION` | Resource update propagation consumer group | `app-resource-update-propagation-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_CORRECTIONAFTERAPPOPERATION` | Correction after app operation consumer group | `app-correction-after-app-operation-group` |
| `KAFKA_CONSUMER_GROUPID_APPLICATION_MERGE` | Application merge consumer group | `app-merge-item-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_CREATE` | Build create consumer group | `build-create-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_UPDATE` | Build update consumer group | `build-update-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_EXPORT` | Build export consumer group | `build-resource-export-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_IMPORT` | Build import consumer group | `build-resource-import-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA` | Build runtime data consumer group | `build-runtime-data-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_STARTTIMEREVENTS_UPDATES` | Build timer events updates consumer | `build-start-timer-events-updates-group` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_START` | Process start consumer group | `process-start-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_DEPLOYMENTFAILED` | Failed build deployment consumer group (available from FlowX.AI 5.9.6) | `build-deployment-failed-group` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Auth exception retry interval (seconds) | `10` |

### Kafka consumer threads configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_EXPORT` | Application export consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_IMPORT` | Application import consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_USAGES` | Resource usages consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATIONRESP` | Resource validation response threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_COPY` | Resource copy consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_SYNC` | Resource sync consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION` | Resource update propagation consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_MERGE` | Application merge consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_APPLICATION_CORRECTIONAFTERAPPOPERATION` | Correction after app operation consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_BUILD_CREATE` | Build create consumer threads | `2` |
| `KAFKA_CONSUMER_THREADS_BUILD_UPDATE` | Build update consumer threads | `4` |
| `KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA` | Build runtime data consumer threads | `2` |
| `KAFKA_CONSUMER_THREADS_BUILD_RESOURCE_EXPORT` | Build export consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_BUILD_RESOURCE_IMPORT` | Build import consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_BUILD_STARTTIMEREVENTS_UPDATES` | Build timer events updates consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_BUILD_DEPLOYMENTFAILED` | Failed build deployment consumer threads (available from FlowX.AI 5.9.6) | `1` |

### Topic naming convention and pattern creation

The Application Manager uses a sophisticated topic naming convention that follows a structured pattern. This ensures consistency across environments and makes topics easily identifiable.

### Topic naming components

| Component | Default Value | Environment Variable | Description |
| - | - | - | - |
| `package` | `ai.flowx.` | `KAFKA_TOPIC_NAMING_PACKAGE` | Base package identifier |
| `environment` | ` ` | `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Deployment environment |
| `version` | `.v1` | `KAFKA_TOPIC_NAMING_VERSION` | Topic version |
| `separator` | `.` | `KAFKA_TOPIC_NAMING_SEPARATOR` | Main separator (referred to as `dot`) |
| `separator2` | `-` | `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator (as `dash`) |
| `prefix` | `${KAFKA_TOPIC_NAMING_PACKAGE}${KAFKA_TOPIC_NAMING_ENVIRONMENT}` | `KAFKA_TOPIC_NAMING_PREFIX` | Combined `package` and `environment` |
| `suffix` | `${KAFKA_TOPIC_NAMING_VERSION}` | `KAFKA_TOPIC_NAMING_SUFFIX` | The version suffix |

### Topic pattern creation

Topics are constructed using the following pattern:

```
{prefix} + service + {separator/dot} + action + {separator/dot} + detail + {suffix}
```

For example, a typical topic might look like:

```
ai.flowx.application-version.export.v1
```

Where:

* `ai.flowx` is the prefix (package + environment)
* `application-version` is the service
* `export` is the action
* `.v1` is the suffix (version)

For more complex topics, additional components are added:

```
ai.flowx.application-version.resources-usages.sub-res-validation.response.v1
```

Where:

* `resources-usages` represents the resource type
* `sub-res-validation` represents the operation type
* `response` indicates it's a response message

### Kafka topic configuration

#### Application resource topics

| Environment Variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_EXPORT` | Application resource export topic | `ai.flowx.application-version.export.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_IMPORT` | Application resource import topic | `ai.flowx.application-version.import.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_IN` | Resource usages in topic | `ai.flowx.application-version.resources-usages.operations.bulk.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_OUT` | Resource usages out topic | `ai.flowx.application-version.resources-usages.operations.bulk.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_REFRESH` | Resource usages refresh topic | `ai.flowx.application-version.resources-usages.refresh.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_RESPONSE` | Resource element usage validation response | `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_OUT_INTEGRATION` | Resource validation integration topic | `ai.flowx.application-version.resources-usages.sub-res-validation.request-integration.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_OUT_CMS` | Resource validation CMS topic | `ai.flowx.application-version.resources-usages.sub-res-validation.cms.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_COPY` | Resource copy topic | `ai.flowx.application-version.copy-resource.v1` |
| `KAFKA_TOPIC_APPLICATION_MERGE` | Application merge topic | `ai.flowx.application-version.merge.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN` | Correction after app operation response (in) | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS` | Correction after app operation → process request | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE` | Correction after app operation → business-rule request | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | Correction after app operation → reusable-template request | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_SYSTEM` | Correction after app operation → system request | `ai.flowx.application-version.correction-after-app-operation.system.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_WORKFLOW` | Correction after app operation → workflow request | `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_UIFLOW` | Correction after app operation → UI flow request | `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | Correction after app operation → custom-component request | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS` | Sync → process (in) | `ai.flowx.application-version.sync.process.in.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE` | Sync → business-rule (in) | `ai.flowx.application-version.sync.business-rule.in.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE` | Sync → reusable-template (in) | `ai.flowx.application-version.sync.reusable-template.in.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_SYSTEM` | Sync → system (in) | `ai.flowx.application-version.sync.system.in.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_WORKFLOW` | Sync → workflow (in) | `ai.flowx.application-version.sync.workflow.in.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_UIFLOW` | Sync → UI flow (in) | `ai.flowx.application-version.sync.ui-flow.in.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN` | Sync in (general response channel) | `ai.flowx.application-version.sync.out.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | Resource update propagation | `ai.flowx.application-version.resource.update.propagation.v1` |

#### Build resource topics

| Environment Variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_BUILD_UPDATE` | Build update topic | `ai.flowx.build.update.v1` |
| `KAFKA_TOPIC_BUILD_CREATE` | Build create topic | `ai.flowx.build.create.v1` |
| `KAFKA_TOPIC_BUILD_RESOURCE_EXPORT` | Build export topic | `ai.flowx.build.export.v1` |
| `KAFKA_TOPIC_BUILD_RESOURCE_IMPORT` | Build import topic | `ai.flowx.build.import.v1` |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_IN_UPDATES` | Timer events updates topic | `ai.flowx.build.start-timer-events.updates.in.v1` |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | Build runtime data topic | `ai.flowx.build.runtime-data.v1` |
| `KAFKA_TOPIC_BUILD_DEPLOYMENTFAILED` | Failed build deployments waiting for a retry, produced by `runtime-manager` (available from FlowX.AI 5.9.6) | `ai.flowx.build.deployment-failed.v1` |

#### Process topics

| Environment Variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN` | Process start for event topic | `ai.flowx.core.trigger.start-for-event.process.v1` |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_IN` | Process start by name topic | `ai.flowx.core.trigger.start-by-name.process.v1` |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_OUT` | Process start by name out topic | `ai.flowx.engine.receive.core.trigger.start-by-name.process.out.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET` | Set timer schedule topic | `ai.flowx.core.trigger.set.timer-event-schedule.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP` | Stop timer schedule topic | `ai.flowx.core.trigger.stop.timer-event-schedule.v1` |

#### Other topics

| Environment Variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Audit topic | `ai.flowx.core.trigger.save.audit.v1` |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Events gateway messages topic | `ai.flowx.eventsgateway.receive.copyresource.v1` |
| `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT` | Topic for publishing runtime config-param change events to the process engine (available from FlowX.AI 5.9.1) | `ai.flowx.config.params.events.v1` |

> [!NOTE]
>
> These Kafka topics use predefined naming conventions for ease of use. Optional adjustments may be made if the desired topic name cannot be achieved with the standard structure.

## Authentication configuration

### Security type

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

### Service account configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-runtime-manager-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!NOTE]
>
> The Application Manager and the Runtime Manager are built from the same artifact and share the `flowx-runtime-manager-sa` service account, which is why the default client ID here is not `flowx-application-manager-sa`.

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

Refer to the dedicated section for configuring user roles and access rights:

> [card] [Access Management](./access-management/access-management-overview)

## File storage configuration

> [!NOTE]
>
> S3 is used in the Application Manager for:
>
> * Storing imported and exported resources
> * Storing application versions and builds that are imported or exported

| Environment Variable | Description | Default Value | Default |
| - | - | - | - |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | S3 server URL | `http://minio-service:9000` | None |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | S3 access key | `minio` | None |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | S3 secret key | `minio123` | None |
| `APPLICATION_FILESTORAGE_TYPE` | Storage type | `s3` | `s3` |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | File deletion strategy | `delete` | `delete` |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | Enable S3 storage | `true` | `true` |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | Enable S3 encryption | `false` | `false` |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | S3 bucket name prefix | `applications-bucket` | `applications-bucket` |

## Monitoring and health check configuration

| Environment Variable | Description | Default Value | Default |
| - | - | - | - |
| `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` | Prometheus metrics | `false` | `false` |
| `MANAGEMENT_HEALTH_KUBERNETES_ENABLED` | Kubernetes health check | `false` | `true` |
| `MANAGEMENT_HEALTH_REDIS_ENABLED` | Redis health check | `false` | `true` |
| `MANAGEMENT_HEALTH_KAFKA_ENABLED` | Kafka health check | `true` | `true` |
| `MANAGEMENT_HEALTH_LIVENESSSTATE_ENABLED` | Liveness state | `true` | `false` |
| `MANAGEMENT_HEALTH_READINESSSTATE_ENABLED` | Readiness state | `true` | `false` |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_LIVENESS_INCLUDE` | Liveness probes | `ping,diskSpace,accessInfo,buildInfo,db,mongo,kafkaClusterHealthCheckIndicator` | `ping` |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDE` | Readiness probes | `ping,diskSpace,accessInfo,buildInfo` | `ping` |

## Resource proxy configuration

The Resource Proxy module forwards resource-related requests to the appropriate services, handling CRUD operations on the manifest. The following settings tune its retries and web client:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_RESOURCEPROXY_RETRYGETRESOURCETIMEOUTMS` | Resource retrieval timeout | `500` |
| `FLOWX_RESOURCEPROXY_RETRYGETRESOURCEMAXCOUNT` | Maximum resource retrieval retries | `10` |
| `FLOWX_RESOURCEPROXY_WEBCLIENT_RETRYATTEMPTS` | Web client retry attempts | `2` |
| `FLOWX_RESOURCEPROXY_WEBCLIENT_RETRYBACKOFF` | Retry backoff time (seconds) | `1` |
| `FLOWX_RESOURCEPROXY_WEBCLIENT_MAXINMEMORYSIZE` | Maximum in-memory size | `5242880` (5 MB) |
| `FLOWX_RUNTIMEEXECUTIONPROXY_WEBCLIENT_MAXINMEMORYSIZE` | Maximum REST request size | `5242880` (5 MB) |

> [!NOTE]
>
> `FLOWX_RUNTIMEEXECUTIONPROXY_WEBCLIENT_MAXINMEMORYSIZE` - Specifies the maximum size (in bytes) of in-memory data for REST requests. This is particularly useful when dealing with large payloads to prevent excessive memory consumption.
>
> * Default Value: 5242880 (5 MB)
> * Usage Example: Set to 10485760 (10 MB) to allow larger in-memory request sizes.

## Proxy connection merge configuration

Configuration for how proxy connection resources are handled during application merges (import, export, conflict resolution).

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_RESOURCEIDFIELD` | Resource ID field for proxy connection merge | `resourceId` |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_FLATTENMAP_IDFIELDS` | Flatten map ID fields for proxy connection merge | `resourceId, name` |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_FLATTENMAP_EXCLUDEDJSONPATHS` | Excluded JSON paths for proxy connection flatten map | `authorization.configuration` |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_COMPARE_REMOVEDJSONPATHS` | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` |
| `FLOWX_APPLICATIONMERGE_RESOURCES_PROXYCONNECTION_CONFLICT_EXCLUDEDJSONPATHS` | Excluded JSON paths for proxy connection conflict detection | `resourceId, resourceDefinitionId` |

***

## Scheduler configuration

The Application Manager scheduler retries failed deployments and times out stalled application version import/export sessions:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SCHEDULER_RETRYFAILEDDEPLOYMENTSCRON` | Failed deployment retry cron | `0 * * * * *` |
| `FLOWX_SCHEDULER_APPVERSIONTIMEOUT` | Application version import/export timeout, in seconds | `14400` |
| `FLOWX_SCHEDULER_APPVERSIONIMPEXTIMEOUTCRON` | Application version import/export timeout check cron | `0 */10 * * * *` |
| `FLOWX_SCHEDULER_INVALIDATEUNSTARTEDIMPORTSESSIONCRON` | Unstarted import session invalidation cron | `0 */10 * * * *` |

### Retry failed deployments

Configures a cron job to retry updating builds in the runtime database every minute when previous attempts have failed.

### Application version import/export timeouts

An application version import or export that stays in progress longer than `FLOWX_SCHEDULER_APPVERSIONTIMEOUT` is moved to `IMPORT_TIMEOUT` or `EXPORT_TIMEOUT`. The default of `14400` seconds is 4 hours. `FLOWX_SCHEDULER_APPVERSIONIMPEXTIMEOUTCRON` controls how often the check runs, every 10 minutes by default.

> [!NOTE]
>
> The equivalent timeouts for **build** import/export are configured on the Runtime Manager, not here. See [Runtime Manager scheduler configuration](./runtime-manager#scheduler-configuration).

### Unstarted import sessions

Resource import sessions that are created but never resumed are moved to `TIMEOUT` status. The expiry is fixed at one hour and is not configurable. `FLOWX_SCHEDULER_INVALIDATEUNSTARTEDIMPORTSESSIONCRON` controls only how often the check runs.

## Configuring logging

To control the logging levels for the Application Manager, use the following environment variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root Spring Boot logs level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-level logs level | `INFO` |
| `LOGGING_LEVEL_DB` | Database interactions log level | `INFO` |

## CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

## Data model overview

The Application Manager stores application data using a relational database schema, with key entities such as application, application\_version, and application\_manifest. Below are descriptions of primary entities:

* **Application** - Defines an application with its details like name, type, and metadata.
* **Application Branch** - Represents branches for versioning within an application.
* **Application Version** - Keeps track of each version of an application, including committed and WIP statuses.
* **Application Manifest** - Contains the list of resources associated with a specific application version.

## Ingress and CORS

The Application Manager service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/appmanager` | `/` |

The path is set through `services.application-manager.ingress.admin.path` (or `services.application-manager.gateway.admin.paths`) in the chart values. The chart also applies `nginx.ingress.kubernetes.io/proxy-body-size: 50m` by default to allow larger application-manifest uploads — adjust the annotation if you need a different limit.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Application Manager. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).


# Audit setup
Source: https://docs.flowx.ai/5.9/setup-guides/audit-setup-guide

This guide will walk you through the process of setting up the Audit service and configuring it to meet your needs.

## Infrastructure prerequisites

The Audit service requires the following components to be set up before it can be started:

* **Docker engine**
* **Kafka**
* **Elasticsearch**

> [!NOTE]
>
> **Redis is not required.** audit-core does not depend on Redis. If you previously configured Redis for this service, those environment variables can be removed from your deployment.

***

## Dependencies

The Audit service is built as a Docker image and runs on top of Kafka and Elasticsearch. Therefore, these services must be set up and running before starting the Audit service.

* [**Kafka configuration**](./setup-guides-overview#kafka-configuration)
* [**Authorization & access roles**](./setup-guides-overview#authorization-&-access-management)
* [**Elasticsearch**](#configuring-elasticsearch)
* [**Logging**](./setup-guides-overview#logging-configuration)

***

## Configuration

### Configuring Kafka

To configure the Kafka server for the Audit service, set the following environment variables:

#### Connection settings

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |

#### Consumer configuration

| Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group ID for audit logs | `audit-gid` |
| `KAFKA_CONSUMER_THREADS` | Number of consumer threads | `1` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after auth failure (seconds) | `10` |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Topic naming configuration

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

#### Kafka topics

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_IN` | Topic for receiving audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Configuring Elasticsearch

Configure Elasticsearch connection for audit data storage:

| Variable | Description | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_REST_PROTOCOL` | Connection protocol | `https` |
| `SPRING_ELASTICSEARCH_REST_URIS` | URL(s) of Elasticsearch nodes (no protocol) | - |
| `SPRING_ELASTICSEARCH_REST_DISABLESSL` | Disable SSL verification | `false` |
| `SPRING_ELASTICSEARCH_REST_USERNAME` | Authentication username | - |
| `SPRING_ELASTICSEARCH_REST_PASSWORD` | Authentication password | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | Audit data stream name | `audit-logs` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | Number of primary shards | `2` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | Number of replica shards | `0` |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | Days before the data stream rolls over to a new backing index | `30` |

> [!NOTE]
>
> The Elasticsearch index settings determine how your audit data is distributed and replicated across the cluster. The number of shards affects search performance and indexing, while replicas provide redundancy.

> [!WARNING]
>
> The Audit service rewrites the index lifecycle management (ILM) policy `{FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME}_policy` (by default `audit-logs_policy`) every time it starts. The policy it writes has a single hot phase that rolls the data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase.
>
> Any change you make to this policy directly in Elasticsearch, such as adding a delete or warm phase, is lost the next time the Audit service restarts or is upgraded.

### CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-` |

### Configuring logging

To control the log levels, set the following environment variables:

| Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Log level for root service | `INFO` |
| `LOGGING_LEVEL_APP` | Log level for application | `INFO` |

***

## Ingress and CORS

The Audit Core service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/audit` | `/` |

The path is set through `services.audit-core.ingress.admin.path` (or `services.audit-core.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Audit Core. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

> [accordion] Audit logs not appearing
>
> **Symptoms:** Audit events are not being recorded or are missing from search results.
>
> **Solutions:**
>
> 1. Verify the `KAFKA_TOPIC_AUDIT_IN` topic exists and matches the topic other services publish to (`ai.flowx.core.trigger.save.audit.v1`)
> 2. Check that the consumer group ID (`SPRING_KAFKA_CONSUMER_GROUPID`) is correctly configured and not conflicting with another consumer
> 3. Ensure Kafka connectivity by verifying `KAFKA_BOOTSTRAP_SERVERS` is reachable from the pod
> 4. Check consumer thread count (`KAFKA_CONSUMER_THREADS`) — increase if throughput is insufficient

> [accordion] Elasticsearch connection errors
>
> **Symptoms:** Service fails to start or throws connection errors related to Elasticsearch.
>
> **Solutions:**
>
> 1. Verify `SPRING_ELASTICSEARCH_REST_URIS` points to a reachable Elasticsearch node (do not include the protocol in this value)
> 2. Check that `SPRING_ELASTICSEARCH_REST_PROTOCOL` matches your Elasticsearch setup (`https` or `http`)
> 3. If using SSL, ensure `SPRING_ELASTICSEARCH_REST_DISABLESSL` is set appropriately and certificates are valid
> 4. Verify `SPRING_ELASTICSEARCH_REST_USERNAME` and `SPRING_ELASTICSEARCH_REST_PASSWORD` credentials are correct

> [accordion] High storage consumption
>
> **Symptoms:** Elasticsearch disk usage grows rapidly or cluster health turns yellow/red.
>
> **Solutions:**
>
> 1. Check the backing indices of the audit data stream: the `{FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME}_policy` ILM policy that the Audit service writes rolls indices over but never deletes them
> 2. Adjust `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` and `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` — fewer replicas reduce storage at the cost of redundancy
> 3. Check the `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` data stream for excessive index count
> 4. Don't set audit retention by editing `{FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME}_policy` in Elasticsearch: the Audit service rewrites that policy on every startup, so the change doesn't last

> [accordion] Audit events delayed
>
> **Symptoms:** Audit entries appear in Elasticsearch with significant delay after the triggering action.
>
> **Solutions:**
>
> 1. Check Kafka consumer lag for the audit consumer group using your Kafka monitoring tools
> 2. Increase `KAFKA_CONSUMER_THREADS` to allow parallel consumption if lag is consistently high
> 3. Verify Elasticsearch cluster health — a degraded cluster slows down indexing
> 4. Check `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` — frequent auth failures with long retry intervals can cause delays

***

## Related resources

> [card] [Audit Log](../docs/platform-deep-dive/core-extensions/audit)
>
> Learn about the audit logging system and how to view audit trails

> [card] [Elasticsearch Indexing](./flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing)
>
> Configure Elasticsearch indexing for process data


# Authorization system setup
Source: https://docs.flowx.ai/5.9/setup-guides/authorization-setup-guide

Configure these environment variables for the authorization-system microservice deployment.

The authorization-system microservice provides centralized authorization services for the FlowX.AI platform, managing workspaces, users, groups, roles, and permissions. It works alongside SpiceDB to deliver fine-grained access control and supports the  Workspaces feature.

## Database configuration

> [!WARNING]
>
> The authorization-system **must** use a dedicated PostgreSQL database. Do not share with other FlowX.AI services.

```bash Environment Variables theme={"dark"}
SPRING_DATASOURCE_URL=jdbc:postgresql://postgresql:5432/authorization_system
SPRING_DATASOURCE_USERNAME=flowx
SPRING_DATASOURCE_PASSWORD=<password>  # Use Kubernetes Secret
```

**Requirements:**

* Database user needs full access to `authorization_system` database
* PostgreSQL must be available before service startup

## CAS client library configuration

> [!NOTE]
>
> The authorization-system uses the CAS client library to communicate with SpiceDB for ACL operations.

```bash Environment Variables theme={"dark"}
FLOWX_SPICEDB_HOST=spicedb
FLOWX_SPICEDB_PORT=50051
FLOWX_SPICEDB_TOKEN=<spicedb-token>  # Use Kubernetes Secret
```

> [!TIP]
>
> The SpiceDB token must match the `preshared_key` value from the [SpiceDB Kubernetes secret](./spicedb#step-3-create-kubernetes-secret). This same value is used as:
>
> * `preshared_key` in the SpiceDB Kubernetes secret
> * `SPICEDB_GRPC_PRESHARED_KEY` for SpiceDB configuration
> * `FLOWX_SPICEDB_TOKEN` for FlowX services

**Configuration Parameters:**

* **SpiceDB Host**: Service hostname (typically `spicedb`)
* **SpiceDB Port**: gRPC port (standard: `50051`)
* **SpiceDB Token**: Authentication token for SpiceDB access

### Runtime authorization backend

Selects which backend the CAS client library uses for runtime authorization checks. With `CUSTOM` (the default), authorization requests are served by the authorization-system service over REST. With `SPICEDB`, checks are delegated directly to SpiceDB. The value is defined once in the shared CAS client library and inherited by every service; override it only if instructed by FlowX.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. | `CUSTOM` |
| `FLOWX_LIB_CASCLIENT_CACHE_WORKSPACEVALIDATION_LOCALTTLSECONDS` | Local cache TTL (seconds) for workspace-validation results in the CAS client library. Shared by every service that embeds the CAS client. | `3600` |

## OAuth2/Keycloak configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server (internal) | - |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-authorization-system-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Token endpoint, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

***

## Redis configuration

Authorization System uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

## Kafka configuration

### Connection settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Kafka broker addresses | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka | `PLAINTEXT` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size | `52428800` (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval for auth exceptions (seconds) | `10` |

### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

### Audit topic

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Organization events topic

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_ORGANIZATION_EVENTS_OUT` | Topic for organization lifecycle events | `ai.flowx.organization.events.v1` |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

## Service account realm secrets

These variables configure the client secrets for service accounts in the dedicated service accounts realm. Liquibase uses these secrets when provisioning the SA realm during deployment.

By default, secrets are left empty and auto-generated. Set explicit values only if you need to reference specific service account credentials in custom integrations.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXORGANIZATIONMANAGERSA` | Client secret for the organization-manager service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXADMINSA` | Client secret for the admin service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXAUTHORIZATIONSYSTEMSA` | Client secret for the authorization-system service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXINTEGRATIONDESIGNERSA` | Client secret for the integration-designer service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXPROCESSENGINESA` | Client secret for the process-engine service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXRUNTIMEMANAGERSA` | Client secret for the runtime-manager service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXSCHEDULERCORESA` | Client secret for the scheduler-core service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXTASKMANAGEMENTPLUGINSA` | Client secret for the task-management-plugin service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXLICENSESA` | Client secret for the license service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXEMAILGATEWAYSA` | Client secret for the email-gateway service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXWEBHOOKGATEWAYSA` | Client secret for the webhook-gateway service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXFILEGATEWAYSA` | Client secret for the file-gateway service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXAIGATEWAYSA` | Client secret for the ai-gateway service account | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXANONYMOUSSA` | Client secret for the anonymous service account, used for inter-service calls on anonymous runtime flows | Auto-generated |
| `FLOWX_SAREALM_SECRETS_SERVICEACCOUNTS_FLOWXEVENTSGATEWAYSA` | Client secret for the events-gateway service account (5.9.4 and later) | Auto-generated |

***

## Management

```bash Environment Variables theme={"dark"}
MANAGEMENT_SERVER_PORT=8081
```

## Organization admin bootstrap

> [!WARNING]
>
> The authorization-system uses a fallback mechanism to create the first organization administrator when no admin users exist.

### Primary method (recommended)

Set `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME` (default: `admin@flowx.ai`)

**Process:**

* System searches for this username in Keycloak
* Copies the user's `sub_id` (subject ID) to authorization-system database
* Grants organization admin privileges automatically

### Fallback method

Set `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID` with a specific Keycloak subject ID

**Process:**

* Creates user directly in authorization-system database
* Assigns organization admin roles
* Used when username method fails or is set to null

### Error handling

**If incorrect subject\_id is provided:**

* Login will fail
* No org-admin privileges granted
* Manual database correction required

> [!NOTE]
>
> If you've deployed with an incorrect subject\_id, use this SQL script to fix it:
>
> ```sql theme={"dark"}
> -- Replace the incorrect subject_id with the correct one from Keycloak
> UPDATE public.cas_user
> SET subject_id = 'PASTE_CORRECT_SUBJECT_ID_FROM_KEYCLOAK_HERE'
> WHERE id = '00000000-0000-0000-0000-100000000001';
> ```
>
> The first organization administrator always has the ID `00000000-0000-0000-0000-100000000001` in the authorization-system database.

## Keycloak redirect URIs

On first startup, the authorization-system runs a Liquibase migration that creates (or updates) the default Keycloak realm and configures the `flowx-platform-authenticate` client. You can control which redirect URIs are set on this client using:

```bash Environment Variables theme={"dark"}
SPRING_LIQUIBASE_PARAMETERS_ALLOWEDREDIRECTURIS=https://designer.yourcompany.com/*,https://app.yourcompany.com/*
```

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWEDREDIRECTURIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client | ` ` (empty) |

> [!WARNING]
>
> For **new deployments**, if this variable is left empty, the Keycloak client will have **no redirect URIs configured** and OAuth2 login flows will fail. Set this to match your Designer and app URLs.
>
> For **existing deployments** upgrading to 5.5.0, the migration has already run and will not re-execute. Your current Keycloak redirect URIs remain unchanged.
>
> Use full-host, path-form patterns (`https://your-host/*`). Starting with Keycloak 26.6.3 (also backported to the 26.4 line in 26.4.13), a wildcard no longer applies to the host part of a redirect URI: a pattern such as `https://designer*` is stored without any error but never matches, and login fails with `Invalid parameter: redirect_uri`.

**Examples:**

* `https://designer.yourcompany.com/*` — Designer access
* `https://app.yourcompany.com/*` — Container app access
* `http://localhost/*` — Local development (the loopback host accepts any port)

> [!TIP]
>
> You can also configure redirect URIs manually in Keycloak after deployment. This variable only applies during the initial Liquibase migration. See the [IAM Configuration](./access-management/configuring-an-iam-solution) guide for manual Keycloak setup.

***

## Default realm admin credentials

During the initial Liquibase migration, the authorization-system creates the default FlowX Keycloak realm along with an admin user. You must set an initial password for this admin user:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME` | Email/username for the default realm admin user | `admin@flowx.ai` |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULTREALMADMININITIALPASSWORD` | Initial password for the default realm admin user. The user will be required to change this password on first login. | ` ` (empty) |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULTREALMADMININITIALPASSWORDISTEMPORARY` | Whether the initial password is temporary. When `true`, the admin user is required to change the password on first login. | `true` |

> [!NOTE]
>
> **Self-hosted deployments**: leave these variables empty. The bootstrap admin password is supplied through the first-time setup screen in Designer the first time the platform starts. See [Self-hosted initialization](./organization-manager-setup#self-hosted-initialization) for the registration flow.

> [!WARNING]
>
> For **new deployments**, this variable **must be set** to a non-empty value. If left empty, the Liquibase migration will fail with `Cannot create default realm` when attempting to create the default admin user, and the authorization-system will not start. The Keycloak realm itself may be created successfully, but the migration will still fail at the user creation step.
>
> For **existing deployments**, this parameter only applies during the initial migration. If the admin user already exists in the realm, it has no effect.

***

## Customer-specific variables

> [!NOTE]
>
> **Required Customization**: These variables must be updated for each deployment environment.

* `SECURITY_OAUTH2_BASESERVERURL` — Your Keycloak server URL
* `SECURITY_MASTERREALM_ADMIN_PASSWORD` — Master realm admin password
* `SPRING_DATASOURCE_URL` — Your PostgreSQL connection details
* `SPRING_LIQUIBASE_PARAMETERS_ALLOWEDREDIRECTURIS` — Designer and app redirect URIs
* Service hostnames — Update to match your Kubernetes service names

## Secrets management

> [!WARNING]
>
> **Security**: Always use Kubernetes Secrets for sensitive configuration values.

**Required Kubernetes Secrets:**

* `SPRING_DATASOURCE_PASSWORD`
* `FLOWX_SPICEDB_TOKEN`
* `SPRING_REDIS_PASSWORD`
* `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`
* `SECURITY_MASTERREALM_ADMIN_PASSWORD`

## Deployment prerequisites

> [card] Infrastructure
>
> * PostgreSQL with `authorization_system` database
> * SpiceDB with authentication configured
> * Redis for caching

> [card] Identity & Access
>
> * Keycloak with configured realm
> * OAuth2 clients created
> * Admin user exists in Keycloak

## Architecture notes

> [!NOTE]
>
> **Database Access Control**: Only authorization-system has direct write access to the CAS PostgreSQL database. Other services communicate via REST APIs only.

> [!NOTE]
>
> **SpiceDB Integration**: Uses PostgreSQL as backend storage and communicates via gRPC through the CAS client library.

## Ingress and CORS

The Authorization System is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives | Example client URL |
| - | - | - | - |
| admin | `/auth` | `/` | `https://admin.{host}/auth/api/...` |

The path is set through `services.authorization-system.ingress.admin.path` (or `services.authorization-system.gateway.admin.paths`) in the chart values. The `/auth` prefix is also used by Keycloak (configured separately via `global.flowx.idp.keycloak.contextPath`); the chart wires both behind the same prefix.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Authorization System. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).


# FlowX CMS setup
Source: https://docs.flowx.ai/5.9/setup-guides/cms-setup

Set up the FlowX CMS Docker microservice for managing taxonomies and content inside an app.

Ensure the following infrastructure components are available before starting the CMS service:

* **MongoDB**
* **Redis**
* **Kafka**
* **Elasticsearch**

> [!NOTE]
>
> The service is pre-configured with most default values. However, some environment variables require customization during setup.

## Dependencies overview

* [**MongoDB instance**](#configuring-mongodb)
* [**Authorization & access roles**](#configuring-authorization-&-access-roles)
* [**Redis**](#configuring-redis)
* [**Kafka**](#configuring-kafka)

***

## Configuration

### Set application defaults

Define the default application name for retrieving content:

```yaml theme={"dark"}
application:
    defaultApplication: ${DEFAULT_APPLICATION:flowx}
```

> [!NOTE]
>
> If this configuration is not provided, the default value will be set to `flowx`.

***

## Configuring authorization & access roles

The CMS validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:

| Environment variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

***

## Configuring Runtime Manager service account

The CMS service requires access to the Runtime Manager service account for operations such as merging media file updates, managing builds, and handling application version transitions.

| Environment variable | Description | Default value |
| - | - | - |
| `APPLICATION_FLOWXRUNTIMESANAME` | Name of the Runtime Manager service account in Keycloak | `flowx-runtime-manager-sa` |

> [!NOTE]
>
> This service account is required for CMS to perform operations like merging media file updates and coordinating with the Runtime Manager service. The service account must exist in Keycloak with the appropriate roles assigned.

***

## Configuring MongoDB

The CMS requires MongoDB for taxonomy and content storage. Configure MongoDB with the following variables:

| Environment variable | Description | Default value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | URI for connecting to the CMS MongoDB instance. The database name (`cms-core`) is fixed in the URI path; only the credentials are parameterized. | Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/cms-core?retryWrites=false` |
| `DB_USERNAME` | MongoDB username (shared by the CMS and runtime connections) | `paperflow` |
| `DB_PASSWORD` | MongoDB password (shared by the CMS and runtime connections) | `password` |
| `MONGOCK_TRANSACTIONENABLED` | Enables transactions in MongoDB for Mongock library | `false` (Set to `false` to support successful migrations) |

> [!NOTE]
>
> Set `MONGOCK_TRANSACTIONENABLED` to `false` due to known issues with transactions in MongoDB version 5.

### Configuring MongoDB (runtime database - additional data)

CMS also connects to a Runtime MongoDB instance for operational data. It reuses the same `DB_USERNAME` and `DB_PASSWORD` as the primary connection — there are no separate runtime credential variables:

| Environment variable | Description | Default value |
| - | - | - |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable the Runtime MongoDB connection | `true` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | URI for connecting to Runtime MongoDB. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path. | Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/app-runtime?retryWrites=false` |
| `SPRING_DATA_MONGODB_STORAGE` | Storage type for Runtime MongoDB (Azure environments only) | `mongodb` (Options: `mongodb`, `cosmosdb`) |

***

## Configuring Redis

CMS uses Redis for caching content. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

***

## Configuring Kafka

### Connection settings

| Environment variable | Description | Default value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Address of the Kafka server | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka | `"PLAINTEXT"` |

### Auth and retry configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after an authorization exception | `10` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size in bytes | `52428800` (50MB) |

### Consumer group configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_CONSUMER_GROUPID_CONTENTTRANSLATE` | Group ID for content translation | `cms-consumer-group` |
| `KAFKA_CONSUMER_GROUPID_RESUSAGEVALIDATION` | Group ID for resource usage validation | `cms-res-usage-validation-group` |

### Consumer thread configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_CONSUMER_THREADS_CONTENTTRANSLATE` | Threads for content translation | `1` |
| `KAFKA_CONSUMER_THREADS_RESUSAGEVALIDATION` | Threads for resource usage validation | `2` |

### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern | `engine.receive.` |

### Content request topics

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_REQUEST_CONTENT_IN` | Topic for incoming content retrieval requests | `ai.flowx.plugin.cms.trigger.retrieve.content.v1` |
| `KAFKA_TOPIC_REQUEST_CONTENT_OUT` | Topic for content retrieval results | `ai.flowx.engine.receive.plugin.cms.retrieve.content.results.v1` |

### Audit topics

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Application resource usage validation

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION` | Topic for resource usage validation | `ai.flowx.application-version.resources-usages.sub-res-validation.cms.v1` |

> [!TIP]
>
> All actions that match a configured pattern will be consumed by the engine.

### Inter-Service topic coordination

When configuring Kafka topics in the FlowX ecosystem, it's critical to ensure proper coordination between services:

1. **Topic name matching**: Output topics from one service must match the expected input topics of another service.

   For example:

   * `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_OUT_CMS` on Application Manager must match `KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION` on CMS

2. **Pattern consistency**: The pattern values must be consistent across services:

   * Process Engine listens to topics matching: `ai.flowx.engine.receive.*`
   * Integration Designer listens to topics matching: `ai.flowx.integration.receive.*`

3. **Communication flow**:
   * Other services write to topics matching the Engine's pattern → Process Engine listens
   * Process Engine writes to topics matching the Integration Designer's pattern → Integration Designer listens

> [!NOTE]
>
> The exact pattern value isn't critical, but it must be identical across all connected services. Some deployments require manually creating Kafka topics in advance rather than dynamically. In these cases, all topic names must be explicitly defined and coordinated.

### Kafka authentication

For secure environments, enable OAuth authentication with the following environment variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

***

## CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-` |

***

## Configuring logging

| Environment variable | Description |
| - | - |
| `LOGGING_LEVEL_ROOT` | Log level for root service logs |
| `LOGGING_LEVEL_APP` | Log level for application-specific logs |

***

## Configuring file storage

### Public storage

| Environment variable | Description |
| - | - |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | URL of S3 server for file storage |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | Access key for the S3 server |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | Secret key for the S3 server |
| `APPLICATION_FILESTORAGE_S3_BUCKETNAME` | S3 bucket name |
| `APPLICATION_FILESTORAGE_S3_ROOTDIRECTORY` | Root directory in S3 bucket |
| `APPLICATION_FILESTORAGE_S3_CREATEBUCKET` | Auto-create bucket if it doesn't exist (`true`/`false`) |
| `APPLICATION_FILESTORAGE_S3_PUBLICURL` | Browser-reachable base URL prepended to stored object keys. Must not point at the internal S3 endpoint |

#### Private storage

Private CMS securely stores uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints.

> [!NOTE]
>
> Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from application builds.

| Environment variable | Description |
| - | - |
| `APPLICATION_FILESTORAGE_S3_PRIVATESERVERURL` | URL of S3 server for private storage |
| `APPLICATION_FILESTORAGE_S3_PRIVATEBUCKETNAME` | S3 bucket name for private storage |
| `APPLICATION_FILESTORAGE_S3_PRIVATECREATEBUCKET` | Auto-create private bucket (`true`/`false`) |
| `APPLICATION_FILESTORAGE_S3_PRIVATEACCESSKEY` | Access key for private S3 server |
| `APPLICATION_FILESTORAGE_S3_PRIVATESECRETKEY` | Secret key for private S3 server |

***

## Configuring file upload size

| Environment variable | Description | Default value |
| - | - | - |
| `SPRING_SERVLET_MULTIPART_MAXFILESIZE` | Maximum file size for uploads | `50MB` |
| `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE` | Maximum request size for uploads | `50MB` |

> [!WARNING]
>
> Setting high file size limits may increase vulnerability to potential attacks. Consider security implications before increasing these limits.

***

## Configuring application management

***

## Ingress and CORS

The CMS Core service is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/cms` | `/` |
| public | `/cms` | `/` |

Paths are set through `services.cms-core.ingress.admin.path` / `services.cms-core.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls CMS. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

> [accordion] CMS service fails to start
>
> **Symptoms:** Service crashes on startup or fails health checks.
>
> **Solutions:**
>
> 1. Verify MongoDB connection URI is correct and the `cms-core` database is accessible
> 2. Check that Kafka bootstrap servers are reachable and topic names are properly configured
> 3. Ensure Redis is running and connection parameters are correct
> 4. Review startup logs for specific error messages related to database migrations (`MONGOCK_TRANSACTIONENABLED` should be `false`)

> [accordion] Enumerations not syncing
>
> **Symptoms:** Enumeration values are outdated or not appearing across services.
>
> **Solutions:**
>
> 1. Verify Kafka topics for content translation are correctly configured (`KAFKA_TOPIC_REQUEST_CONTENT_IN` and `KAFKA_TOPIC_REQUEST_CONTENT_OUT`)
> 2. Check that consumer group IDs are unique and not conflicting with other service instances
> 3. Ensure Redis cache is not serving stale data — restart the CMS service to force cache invalidation
> 4. Confirm the resource usage validation topic (`KAFKA_TOPIC_APPLICATION_IN_RESUSAGEVALIDATION`) is properly configured

> [accordion] Media library uploads failing
>
> **Symptoms:** File uploads return errors or files are not visible in the Media Library.
>
> **Solutions:**
>
> 1. Verify S3/MinIO server URL and bucket configuration (`APPLICATION_FILESTORAGE_S3_SERVERURL`, `APPLICATION_FILESTORAGE_S3_BUCKETNAME`)
> 2. Check that the bucket exists or `APPLICATION_FILESTORAGE_S3_CREATEBUCKET` is set to `true`
> 3. Ensure file size limits are appropriate (`SPRING_SERVLET_MULTIPART_MAXFILESIZE` and `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`)
> 4. For private storage, verify access key and secret key credentials are correct

> [accordion] Media Library images broken at retrieval
>
> **Symptoms:** Uploads succeed and files appear in the Media Library, but images render as broken in the Designer or in running applications (404, 403, or connection errors on the asset URL).
>
> Media files are stored under a bare object key (`{orgId}/{workspaceId}/{appId}/{key}/{timestamp}_{filename}`); the browser fetches them from a public base URL prepended to that key, not through the CMS service. Retrieval breaks when that base is wrong or unreachable even though uploads work.
>
> **Solutions:**
>
> 1. Open browser developer tools and check the URL the failing image actually requests — the host is the public base, the rest is the object key
> 2. Verify `APPLICATION_FILESTORAGE_S3_PUBLICURL` points to a browser-reachable endpoint. The default (`http://minio:9000`) is the internal S3 address and must be overridden on any real deployment
> 3. Verify the Designer and renderer containers set `STATIC_ASSETS_PATH` to the same base — the browser prepends it to stored keys at render time. See the [Designer setup guide](./designer-setup-guide)
> 4. If a CDN or proxy fronts the bucket, map it at bucket root so the full tenant-prefixed key resolves; if `APPLICATION_FILESTORAGE_S3_ROOTDIRECTORY` is set, the public base must include it. A prefix mismatch returns 403/404 on assets even when the bucket is healthy
> 5. Private files are served through authenticated CMS endpoints instead, so the `/cms` route must be exposed on the public host — see [Ingress and CORS](#ingress-and-cors)

> [accordion] Content not appearing in Designer
>
> **Symptoms:** CMS content (enumerations, media files) is not visible in the FlowX Designer.
>
> **Solutions:**
>
> 1. Verify CMS service is running and healthy by checking the `/actuator/health` endpoint
> 2. Ensure the CMS service is reachable from the Designer — check network policies and ingress configuration
> 3. Verify CORS settings allow requests from the Designer domain
> 4. Check that the authorization configuration is correct and the Designer can authenticate with the CMS service

***

## Related resources

> [card] [Enumerations](../docs/platform-deep-dive/core-extensions/content-management/enumerations)
>
> Manage taxonomies and enumeration values for your applications

> [card] [Media Library](../docs/platform-deep-dive/core-extensions/content-management/media-library)
>
> Store and manage media assets used across your applications

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes


# Configure the flowx-ai Helm chart for your infrastructure
Source: https://docs.flowx.ai/5.9/setup-guides/configure-flowx-ai-helm-chart

Connect flowx-ai Helm chart services to your databases, identity provider, and CA certificates with definitions, selectors, Kubernetes secrets, and render guards.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.6.** This page describes the `flowx-ai` chart, which deploys the core and AI services as one Helm release.

The `flowx-ai` chart turns a small set of values into the environment of every service: database URLs, credentials, identity provider settings, and trusted certificates. This page explains the model behind those values so you can point the chart at your own infrastructure and read what it renders.

For the `global`, `groups`, and `services` layout, and for moving from the per-service or `ai-platform` charts, see [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](./migrate-to-flowx-ai-helm-chart).

***

## How do values reach a service?

Each service renders from its own `services.<name>` block plus the whole `global` block. Nothing else in the values tree is visible to it.

| Layer | What it holds | Who reads it |
| - | - | - |
| `global` | Image registry, pod defaults, `global.env` | Every service |
| `global.flowx` | Connection definitions, identity provider, certificates, domains | Every service |
| `groups.<group>` | One switch per service group | The chart, to decide which services deploy |
| `services.<name>` | The image version, `env`, and the `component` block that selects what the service connects to | That service only |

When the same setting exists in more than one place, these rules apply:

* **Environment variables:** `global.env` and `services.<name>.env` are merged, and the service value wins for the same name.
* **Connection definitions:** the chart reads servers and credentials from `global.flowx.<dependency>`. The chart already ships a definition there for PostgreSQL, MongoDB, Redis, Elasticsearch, S3, SpiceDB, SMTP, and Qdrant, so a definition placed under `services.<name>.<dependency>` is not read. Change the global one.
* **Chart defaults:** Helm merges your values file into the chart defaults key by key. Set only the keys you change, for example `global.flowx.postgresql.servers.flowx.host`, and keep the rest.

***

## How does a service connect to a dependency?

Every dependency connection has two halves: a **definition**, which says where a server is and how to log in, and a **selector**, which says which service uses it. This schema is defined by the `flowx-ai` chart. It is not a Kubernetes or Helm convention.

**1. Define the server**

Under `global.flowx.<dependency>.servers.<key>`, set the connection details, such as `host` and `port`. The key is a name you choose, for example `flowx`.

**2. Define the credentials**

Under `global.flowx.<dependency>.credentials.<key>`, set the login, either as plain values or from a Kubernetes secret. One credentials entry usually belongs to one service.

**3. Select them in the service**

Under `services.<name>.component.<dependency>.<entry>`, reference the server with `serverRef` and the credentials with `credentials`, then add what is specific to this service, such as `database`.

Several services can share one server definition and still log in with their own credentials and use their own database.

### Which selector fields can I set?

PostgreSQL selectors take these fields. The other dependencies follow the same pattern with fields of their own.

| Field | Description | Default |
| - | - | - |
| **`serverRef`** | Key of a server under `global.flowx.postgresql.servers` | - |
| **`credentials`** | Key of an entry under `global.flowx.postgresql.credentials` | - |
| **`database`** | Database name. Required when the URL is built from the server definition | - |
| **`url`** | A complete connection URL. When set, it replaces the URL built from `serverRef` and `database`. Java services only | - |
| **`alias`** | Distinguishes a second connection of the same service. See [Several connections to one dependency](#several-connections-to-one-dependency) | None |
| **`prefix`** and **`renderingTemplate`** | Control the names under which the connection is rendered. Leave them unset unless the chart sets them: the service expects the names it renders | Set by the chart |

The chart builds the PostgreSQL URL as `jdbc:postgresql://<host>:<port>/<database><parameters>`, where `port` defaults to `5432` and `parameters` is an optional string on the server definition, such as `?sslmode=require`.

> [!WARNING]
>
> A `serverRef` or `credentials` value that matches no key is not a render error. For PostgreSQL and MongoDB, the service then gets no connection URL or no credentials, and fails when it starts. After you rename a server or credentials key, update every selector that references it.

### Several connections to one dependency

A service can select more than one entry for the same dependency, for example the main database and a second one. Only one entry per dependency may omit `alias`: the unaliased entry is the service's main connection, and each aliased entry is rendered under its alias. The render fails when two entries have no alias.

The `process-engine` service ships with two PostgreSQL entries:

```yaml theme={"dark"}
services:
  process-engine:
    component:
      postgresql:
        processEngine:
          serverRef: "flowx"
          credentials: "processEngine"
          database: "process_engine"
        advancingController:
          serverRef: "flowx"
          credentials: "advancingController"
          database: "advancing_controller"
          alias: "advancing"
```

Keep the aliases the chart sets. A service reads each connection under the alias it expects, so a renamed alias leaves that connection unconfigured.

### Example: point the services at your PostgreSQL server

The chart's selectors already reference a server named `flowx` and one credentials entry per service. To use your own PostgreSQL server, override the server definition and, where needed, the credentials:

```yaml theme={"dark"}
global:
  flowx:
    postgresql:
      servers:
        flowx:
          host: "postgres.db.svc.cluster.local"
          port: 5432
          parameters: "?sslmode=require"
      credentials:
        processEngine:
          username: "process_engine"
          existingSecret:
            name: "flowx-postgres-process-engine"
            keyMapping:
              password: password
```

Every service whose selector uses `serverRef: "flowx"` now connects to `postgres.db.svc.cluster.local`. With these values, `process-engine` connects to `jdbc:postgresql://postgres.db.svc.cluster.local:5432/process_engine?sslmode=require` as `process_engine`, and reads the password from the `password` key of the `flowx-postgres-process-engine` secret.

To send one service to a different server, add a second server definition and change only that service's `serverRef`:

```yaml theme={"dark"}
global:
  flowx:
    postgresql:
      servers:
        reporting:
          host: "pg-reporting.db.svc.cluster.local"
services:
  document-plugin:
    component:
      postgresql:
        documentPlugin:
          serverRef: "reporting"
```

Because Helm merges values key by key, `document-plugin` keeps the `credentials` and `database` of its `documentPlugin` entry and changes only its server.

***

## How do I keep passwords in Kubernetes secrets?

Any definition that holds a secret value, such as credentials or a client secret, can read it from an existing Kubernetes secret through `existingSecret`. The chart never creates these secrets: create them before you install.

```yaml theme={"dark"}
credentials:
  license:
    username: license
    existingSecret:
      name: flowx-postgres-license
      keyMapping:
        password: password
```

For each field, the chart decides where the value comes from:

| `existingSecret` | `keyMapping` | Result |
| - | - | - |
| Set | Lists the field | Read from the secret, under the key the mapping gives |
| Set | Present, but doesn't list the field | Taken from the plain value, such as `username: license` above |
| Set | Absent | Read from the secret, under a key named like the field, for example `password` |
| Not set | - | Taken from the plain value |

An object has one `existingSecret`, so all its secret fields come from the same Kubernetes secret. To keep a username in a secret as well, list it in `keyMapping`:

```yaml theme={"dark"}
existingSecret:
  name: flowx-postgres-license
  keyMapping:
    username: username
    password: password
```

> [!TIP]
>
> Prefer `existingSecret` over plain passwords in your values file. Plain values end up in the rendered manifests and in the Helm release history.

***

## What does configmap mode change?

By default, every rendered setting is an environment variable in the pod spec. With configmap mode on, the chart moves the plain settings into a ConfigMap and keeps only the secret references in the pod spec:

| | Configmap mode off (default) | Configmap mode on |
| - | - | - |
| Plain settings, such as URLs and client IDs | Environment variables in the container spec | A ConfigMap named `<service>-env`, attached with `envFrom` |
| Secret settings, such as passwords | Environment variables that reference the secret | Unchanged: environment variables that reference the secret |

Turn it on for every service with `global.flowx.configmapMode: true`, or for one service with `services.<name>.configmapMode: true`.

**Default:** `false`

> [!NOTE]
>
> `global.flowx.configmapMode` takes precedence over the service value when it is set. To turn configmap mode on for a single service, leave the global key unset.

***

## How do I update one service to a newer version?

The chart builds each service's image tag from `services.<name>.version` and sets it to the version that ships with the platform release. To roll out a fix for one service without upgrading the platform, set that key to the version FlowX gives you, then run `helm upgrade` with the chart version you already run:

```yaml theme={"dark"}
services:
  process-engine:
    version: "{patched-version}"
```

If the service also has `image.tag` set, the chart uses that tag instead, so remove it.

Remove the `version` key again when you upgrade the chart. Your values override the chart defaults on every upgrade, so a leftover key keeps that service on the old image while the rest of the platform moves to the new release.

***

## How do I read what the chart rendered?

Render the chart locally and look at the environment of one service:

```bash theme={"dark"}
helm template flowx-ai <chart> -f values.yaml --show-only templates/deployment.yaml
```

The chart writes a comment before each block it generates, naming the source of the block, for example `# postgresql: processEngine` for the selector entry `processEngine`, `# oauth client: admin` for a client, or `# java resource server variables`. With configmap mode on, the comments appear in the `<service>-env` ConfigMap instead of the pod spec.

***

## Why does the render stop with an error?

The chart checks each enabled service before rendering it. A check that fails stops the whole render with a message that starts with the service name in brackets, so nothing reaches the cluster in a half-configured state.

| Message | What to fix |
| - | - |
| `[<service>] IDP setup incorrect. Valid configurations are keycloak:opaque \| keycloak:jwt \| entraid:jwt` | The resource server the service selects has a `securityType` that the provider doesn't support. See [Resource servers](#resource-servers) |
| `[<service>] IDP host setup incorrect. Configure idp.keycloak.url.host or idp.keycloak.subDomain + .rootDomain` | The Keycloak URL can't be built. Set `global.flowx.idp.keycloak.url.host`, or both `global.flowx.idp.keycloak.subDomain` and `global.flowx.rootDomain` |
| `[<service>] IDP host setup incorrect. Configure idp.keycloak.url.host or .rootDomain` | The same, with `global.flowx.singleDomain: true` |
| `[<service>] IDP entraid setup incorrect. Configure idp.entraid.tenantId` | Set `global.flowx.idp.entraid.tenantId` |
| `[<service>] idp.entraid.appRolesobjectId required when ...` | Set `global.flowx.idp.entraid.appRolesObjectId` for services that call Microsoft Graph |
| `[<service>] Only one PostgreSQL entry may omit an alias` | Give every extra entry an `alias`. The same check exists for Mongo, CosmosMongo, s3, and redis |
| `[<service>] kafka.security.tls.existingSecret required when kafka.security.tls is true` | Point the Kafka TLS settings at the secret that holds the CA |
| `[<service>] cannot enable kafka mtls without tls` | Turn on Kafka TLS before mutual TLS |
| `[<service>] Host for admin ingress not computable. ...` | The service's admin hostname can't be built from its hostname, subdomain, and root domain. The same check exists for the public and admin instances routes |

The chart also stops when the values file still has the old layout: top-level `devtime` or `runtime` flags, service keys at the root instead of under `services:`, a root-level `image` or `podLabels`, or a service whose `group` isn't declared under `groups:`. These keys would otherwise be ignored without any warning. The message names the key and where it moved.

***

## How do I trust a private certificate authority?

When a dependency presents a certificate from a private certificate authority (CA), the services that call it need that CA in their trust store. The chart adds it with an init container:

**1. Store the CA in a secret**

Create a Kubernetes secret that holds the CA certificate in PEM format.

**2. Define the certificate**

Add an entry under `global.flowx.certs` with `type: ca`, the secret name, and one `keyMapping` entry that points to the key of the certificate in the secret.

**3. Select it in each service**

List the entry in `services.<name>.component.certs` for every service that calls the dependency.

```yaml theme={"dark"}
global:
  flowx:
    certs:
      internal-ca:
        type: ca
        existingSecret:
          name: internal-ca-cert
          keyMapping:
            ca: ca.crt
services:
  integration-designer:
    component:
      certs: ["internal-ca"]
```

Before the service starts, the init container builds a trust store and mounts it over the default one:

| Runtime | What the init container does | Mounted at |
| - | - | - |
| Java | Copies the image's Java trust store and imports each selected CA into it | `/opt/java/openjdk/lib/security/cacerts` |
| Python | Appends each selected CA to the system CA bundle | `/etc/ssl/certs/ca-certificates.crt` |

The chart ships one definition, `elasticsearch`, which reads `ca.crt` from the `elasticsearch-es-http-certs-public` secret. It is selected by admin, audit-core, data-search, document-plugin, and process-engine. When you add a certificate to a service that already selects `elasticsearch`, keep it in the list: `certs: ["elasticsearch", "internal-ca"]`.

| Setting | Description | Default |
| - | - | - |
| **`global.flowx.certsInitContainer.enabled`** | Turns the init container on for all services. It runs only for services that select at least one certificate | `true` |
| **`global.flowx.certsInitContainer.resources`** | Resources of the init container | Requests: `100m` CPU, `128Mi` memory |
| **`services.<name>.component.certsMountPathOverride`** | Directory to mount the trust store in, for images whose Java runtime or CA bundle is somewhere else. The chart already sets it where an image needs it: keep that value | None |

> [!NOTE]
>
> Only entries with `type: ca` are imported. Each entry uses one key of its secret: when `keyMapping` lists several, the first one in alphabetical order is used. Use one entry per CA.

***

## Configure the identity provider

The chart renders the identity provider settings of every service from `global.flowx.idp`. A service reads three parts of it: the provider, the clients it selects, and the resource server it selects.

### Choose the provider

Set `global.flowx.idp.provider` to `keycloak` or `entraid`.

**Default:** `keycloak`

**Keycloak**

| Setting | Description | Default |
| - | - | - |
| **`global.flowx.idp.keycloak.realm`** | Realm the FlowX.AI clients live in | `flowx` |
| **`global.flowx.idp.keycloak.url.host`** | Keycloak host name. When set, it is used as is | None |
| **`global.flowx.idp.keycloak.url.protocol`** | Protocol of the Keycloak URL | `https` |
| **`global.flowx.idp.keycloak.url.port`** | Port of the Keycloak URL. `0` or unset leaves the port out | None |
| **`global.flowx.idp.keycloak.subDomain`** | Used to build the host as `<subDomain>.<rootDomain>` when `url.host` isn't set | `auth` |
| **`global.flowx.idp.keycloak.contextPath`** | Path Keycloak is served under | `/auth` |

Without `url.host`, the Keycloak URL is `https://auth.<rootDomain>` by default, built from `global.flowx.rootDomain`. With `global.flowx.singleDomain: true`, it is `https://<rootDomain>`.

```yaml theme={"dark"}
global:
  flowx:
    idp:
      provider: "keycloak"
      keycloak:
        realm: "flowx"
        url:
          host: "auth.example.com"
          protocol: "https"
        contextPath: "/auth"
```

For the realm, clients, and roles to create in Keycloak, see [Configuring an IAM solution](./access-management/configuring-an-iam-solution).

**Microsoft Entra ID**

| Setting | Description | Default |
| - | - | - |
| **`global.flowx.idp.entraid.tenantId`** | Directory (tenant) ID. Required with `provider: entraid` | `""` |
| **`global.flowx.idp.entraid.appRolesObjectId`** | Object ID used by services that read app roles through Microsoft Graph. Required for the services that set `component.usesMicrosoftGraph: true` | `""` |

For the Entra ID side, see [Configuring Microsoft Entra ID](./access-management/configuring-an-iam-solution-entra).

### Clients

A client is an identity a service uses to call the identity provider. Like connections, clients have a definition and a selector, and a service needs both:

* **Definition:** `global.flowx.idp.clients.<key>`, with `grantType`, `clientId`, and the client secret.
* **Selector:** `services.<name>.component.idpClients`, a list of client keys.

```yaml theme={"dark"}
global:
  flowx:
    idp:
      clients:
        admin:
          alias: "mainIdentity"
          grantType: "client_credentials"
          clientId: flowx-admin-sa
          existingSecret:
            name: "keycloak-flowx-realm-clients"
            keyMapping:
              clientSecret: "KEYCLOAK_ADMIN_CLIENT_SECRET"
services:
  admin:
    component:
      idpClients: ["admin", "anonymous"]
```

| Field | Description |
| - | - |
| **`grantType`** | `client_credentials` for a service account that a backend service uses to call other services, `authorization_code` for the browser login of FlowX Designer and the solution portal |
| **`clientId`** | Client ID in the identity provider |
| **`alias`** | Name the service registers the client under. Backend services read their own service account as `mainIdentity` and the anonymous one as `anonymousIdentity`: keep these names |
| **`existingSecret`** | Secret that holds the client secret, under `keyMapping.clientSecret` |
| **`scopes`** | Scopes to request. The `designer` and `solution-portal` clients request `openid profile email` |
| **`url`** | Identity provider URL for this client only, when it differs from the global Keycloak URL |

The chart ships a client for each backend service, plus `anonymous`, `designer`, and `solution-portal`. All service account secrets are read from the `keycloak-flowx-realm-clients` secret, one key per client, such as `KEYCLOAK_ADMIN_CLIENT_SECRET` or `KEYCLOAK_PROCESS_ENGINE_CLIENT_SECRET`. Create that secret with the client secrets from your identity provider, or point each client's `existingSecret` at your own secret.

### Resource servers

A resource server is how a service checks the access tokens it receives. A service selects one with `services.<name>.component.resourceServer`, and the chart reads its settings from `global.flowx.idp.resourceServers.<key>`.

**Default selection:** `default`

The `securityType` of the selected resource server must match the provider:

| Provider | `securityType` | How tokens are checked |
| - | - | - |
| `keycloak` | `jwt` | Locally, against the Keycloak signing keys |
| `keycloak` | `opaque` | By asking Keycloak about each token (token introspection), with the `opaque.clientId` client and its secret |
| `entraid` | `jwt` | Locally, against the Entra ID signing keys of the tenant. Set `jwt.audience` to the expected audience |

Any other combination stops the render with `IDP setup incorrect`.

The 5.9.6 chart's values define only one resource server, `aiPlatform`, while every service selects `default`. To set how the core services check tokens, define `default`:

```yaml theme={"dark"}
global:
  flowx:
    idp:
      resourceServers:
        default:
          securityType: "jwt"
```

> [!WARNING]
>
> Use `securityType: jwt` for the `default` resource server. With `opaque`, the Java services also need a token introspection URL, which the chart doesn't render, and they fail at startup with `Could not resolve placeholder 'spring.security.oauth2.resource-server.opaque-token.introspection-uri'`.

***

## How do I connect to Kafka with SASL?

By default, the chart connects every service to Kafka with OAuth: `global.flowx.kafka.security.authentication.type` is `oauth`, with the `flowx-service-client` client in the `infra` realm. To log in with a username and password instead, switch the type to `sasl`:

```yaml theme={"dark"}
global:
  flowx:
    kafka:
      bootstrapServers: "kafka.example.com:9093"
      security:
        enabled: true
        authentication:
          enabled: true
          type: sasl
          sasl:
            mechanism: SCRAM-SHA-512
            username: flowx
            existingSecret:
              name: flowx-kafka-sasl
              keyMapping:
                password: password
        tls:
          enabled: true
          existingSecret:
            name: kafka-ca
            keyMapping:
              ca: ca.crt
```

| Setting | Description | Default |
| - | - | - |
| **`security.authentication.sasl.mechanism`** | `SCRAM-SHA-256` or `SCRAM-SHA-512` | None |
| **`security.authentication.sasl.username`** | Kafka user | None |
| **`security.authentication.sasl.password`** or **`existingSecret`** | Password, as a plain value or from a secret under the `password` key | None |
| **`security.authentication.sasl.producer`** and **`.consumer`** | Separate credentials for the producer and the consumer, each with `username` and `password` or `existingSecret` | None |
| **`security.tls.enabled`** | Connect over TLS. Requires `security.tls.existingSecret`, with the broker's CA under the `ca` key | Off |

All settings are under `global.flowx.kafka`. With TLS on, the services connect with `SASL_SSL`, otherwise with `SASL_PLAINTEXT`. When you set `producer` or `consumer`, the chart uses only those credentials and ignores `sasl.username` and `sasl.password`, so set both.

> [!WARNING]
>
> The chart configures SASL for the Java services only. The AI services that run on Python get Kafka client security only with `type: oauth`: with `sasl`, the chart renders no Kafka authentication for them. Keep that in mind before you remove the OAuth listener from your Kafka cluster.

***

## How do I use Redis Sentinel or Redis Cluster?

The chart's services select the `default` Redis server, a standalone Redis at `redis-master:6379`, through `services.<name>.component.redis.cache`. To use Redis Sentinel or Redis Cluster, change the `default` server definition. The chart picks the connection mode in this order, and the first one that is set wins:

1. `url` on the service's selector
2. `host` on the server
3. `sentinel` on the server
4. `cluster` on the server

Because Helm merges your values into the chart's, the `default` server keeps `host: redis-master` unless you clear it. Set `host: ""` for Sentinel or Cluster, or the services keep connecting to the standalone host.

> [tab] Sentinel
>
> ```yaml theme={"dark"}
> global:
>   flowx:
>     redis:
>       servers:
>         default:
>           host: ""
>           sentinel:
>             master: mymaster
>             nodes:
>               - "redis-sentinel-0.redis-sentinel:26379"
>               - "redis-sentinel-1.redis-sentinel:26379"
>               - "redis-sentinel-2.redis-sentinel:26379"
> ```
>
> The services log in to Sentinel with the credentials entry their selector names in `sentinelCredentials`, which is `root` in the chart, the same as for Redis. To use a separate Sentinel password, add a credentials entry under `global.flowx.redis.credentials` and point each service's `component.redis.cache.sentinelCredentials` at it.

> [tab] Cluster
>
> ```yaml theme={"dark"}
> global:
>   flowx:
>     redis:
>       servers:
>         default:
>           host: ""
>           cluster:
>             nodes:
>               - "redis-cluster-0.redis-cluster:6379"
>               - "redis-cluster-1.redis-cluster:6379"
>               - "redis-cluster-2.redis-cluster:6379"
> ```

The password comes from the `root` credentials entry, which reads the `redis-password` key of the `flowx-redis` secret. Change `global.flowx.redis.credentials.root` to read it from your own secret.

***

## How do I use Oracle instead of PostgreSQL?

The chart can render an Oracle connection for the Java services. The chart ships no Oracle definitions and every Java service selects PostgreSQL, so you add the definitions, then replace each service's PostgreSQL selector with an Oracle one. Check each service's setup guide for Oracle support before you switch it.

**1. Define the server and the credentials**

```yaml theme={"dark"}
global:
  flowx:
    oracle:
      servers:
        flowx:
          host: "oracle.db.example.com"
          port: 1521
      credentials:
        processEngine:
          username: "process_engine"
          existingSecret:
            name: "flowx-oracle-process-engine"
            keyMapping:
              password: password
        advancingController:
          username: "advancing_controller"
          existingSecret:
            name: "flowx-oracle-advancing-controller"
            keyMapping:
              password: password
```

The chart builds the URL as `jdbc:oracle:thin:@//<host>:<port>/<database><parameters>`, where `port` defaults to `1521` and `parameters` is an optional string on the server definition. Set `url` on a selector to use a complete URL instead.

**2. Replace the PostgreSQL selector of each service**

Set `component.postgresql` to `~` to remove the chart's PostgreSQL selector, and add an Oracle entry for each connection the service had. Keep the entry keys and aliases of the PostgreSQL selector:

```yaml theme={"dark"}
services:
  process-engine:
    component:
      postgresql: ~
      oracle:
        processEngine:
          serverRef: "flowx"
          credentials: "processEngine"
          database: "{process-engine-service-name}"
        advancingController:
          serverRef: "flowx"
          credentials: "advancingController"
          database: "{advancing-service-name}"
          alias: "advancing"
```

`database` is the Oracle service name in the URL. The FlowX.AI Engine and the Advancing Controller must use the same database type, so move `process-engine`, `advancing-controller`, and the advancing connection of `integration-designer` together. See [Advancing controller setup](./advancing-controller-setup-guide).

**3. Switch data-sync too**

The data-sync job reads the databases of process-engine, application-manager, authorization-system, and license. Under `dataSync.component`, set `postgresql: ~` and add an `oracle` entry for each of them that moved, with the alias the job uses (`engine`, `appmanager`, `authsystem`, or `license`) and `renderingTemplate: "FLOWX_DATASOURCE_{{ .alias }}"`, as in the job's PostgreSQL entries.

> [!NOTE]
>
> The AI services that run on Python don't connect to Oracle through the chart.

***

## How do I scale a service and keep it available?

Each service has its own replica count, autoscaler, and disruption budget under `services.<name>`. All are off by default, and every service runs `global.replicaCount` replicas, which is `1` unless you change it.

| Setting | Description | Default |
| - | - | - |
| **`replicaCount`** | Replicas of this service when autoscaling is off | `global.replicaCount` |
| **`autoscaling.enabled`** | Renders a HorizontalPodAutoscaler for the service | `false` |
| **`autoscaling.minReplicas`** | Lowest replica count | `1` |
| **`autoscaling.maxReplicas`** | Highest replica count. Required when autoscaling is on | None |
| **`autoscaling.targetCPUUtilizationPercentage`** | Average CPU use, as a percentage of the CPU request, that the autoscaler keeps | None |
| **`autoscaling.targetMemoryUtilizationPercentage`** | The same, for memory | None |
| **`podDisruptionBudget.enabled`** | Renders a PodDisruptionBudget for the service | `false` |
| **`podDisruptionBudget.minAvailable`** | Pods that must stay up during a voluntary disruption, such as a node drain | None |
| **`podDisruptionBudget.maxUnavailable`** | Pods that may be down during a voluntary disruption. Set this or `minAvailable` | None |

```yaml theme={"dark"}
services:
  process-engine:
    autoscaling:
      enabled: true
      minReplicas: 2
      maxReplicas: 6
      targetCPUUtilizationPercentage: 75
    podDisruptionBudget:
      enabled: true
      minAvailable: 1
```

With autoscaling on, the chart leaves `replicas` out of the Deployment so that the autoscaler owns it, and `replicaCount` has no effect. Utilization targets are percentages of the container's resource requests, so the service needs CPU or memory requests for the target you set. A `minAvailable` equal to the replica count blocks node drains: keep it below `minReplicas`.

***

## How do I restrict network traffic to a service?

Set `services.<name>.networkPolicy.enabled: true` to render a NetworkPolicy for the service. By default, it allows inbound traffic from anywhere, but only to the ports under `services.<name>.service.ports`, which is the HTTP port `8080` by default.

| Setting | Description | Default |
| - | - | - |
| **`networkPolicy.enabled`** | Renders the NetworkPolicy | `false` |
| **`networkPolicy.allowExternal`** | `true` allows the service ports from any source. `false` allows them only from pods labeled `<service>-client: "true"`, from the service's own pods, and from the namespaces in `ingressNSMatchLabels` | `true` |
| **`networkPolicy.ingressNSMatchLabels`** | Labels of namespaces whose pods may connect when `allowExternal` is `false` | None |
| **`networkPolicy.ingressNSPodMatchLabels`** | Narrows `ingressNSMatchLabels` to pods with these labels | None |
| **`networkPolicy.extraIngress`** | More ingress rules, in NetworkPolicy syntax | None |
| **`networkPolicy.extraEgress`** | Egress rules. Setting it restricts outbound traffic: the service can then reach only DNS and the destinations you list | None |

> [!WARNING]
>
> The policy doesn't open the management port, where Prometheus scrapes metrics. On the Java services that is port `8081`. The AI services set their own, under `services.<name>.mngt.service.ports.mngt.targetPort`. If you [collect metrics with Prometheus](#how-do-i-collect-metrics-with-prometheus), add a rule for it:
>
> ```yaml theme={"dark"}
> services:
>   process-engine:
>     networkPolicy:
>       enabled: true
>       extraIngress:
>         - ports:
>             - port: 8081
>           from:
>             - namespaceSelector:
>                 matchLabels:
>                   kubernetes.io/metadata.name: monitoring
> ```
>
> With `extraEgress`, list every dependency the service calls, such as its databases, Kafka, Redis, the identity provider, and the other FlowX.AI services. Anything you leave out is blocked.

***

## How do I collect metrics with Prometheus?

The chart renders a Prometheus Operator `ServiceMonitor` for each service where you turn it on. The `ServiceMonitor` resource type comes with the Prometheus Operator, so install it first, or the release fails to install.

```yaml theme={"dark"}
services:
  process-engine:
    metrics:
      enabled: true
      serviceMonitor:
        enabled: true
        interval: 30s
        additionalLabels:
          release: prometheus
```

The `ServiceMonitor` scrapes the service's management port, `mngt`, at `/manage/actuator/prometheus`, the path the Java services serve. The service must have its management port turned on with `mngt.enabled`, which the chart sets for its services by default.

| Setting | Description | Default |
| - | - | - |
| **`metrics.enabled`** and **`metrics.serviceMonitor.enabled`** | Both must be `true` to render the `ServiceMonitor` | `false` |
| **`metrics.serviceMonitor.namespace`** | Namespace to create the `ServiceMonitor` in | The release namespace |
| **`metrics.serviceMonitor.path`** | Metrics path | `/manage/actuator/prometheus` |
| **`metrics.serviceMonitor.interval`** and **`.scrapeTimeout`** | Scrape interval and timeout | The Prometheus defaults |
| **`metrics.serviceMonitor.additionalLabels`** | Labels that your Prometheus uses to select `ServiceMonitor` resources | None |
| **`metrics.serviceMonitor.honorLabels`** | Keeps the labels of scraped metrics when they clash with Prometheus labels | None |
| **`metrics.serviceMonitor.relabellings`** | Metric relabeling rules. Note the spelling of the key | None |
| **`metrics.podAnnotations`** | Annotations added to the service's pods, for a Prometheus that discovers targets by annotation | None |

***

## Troubleshooting

> [accordion] The render stops with a message that starts with a service name in brackets
>
> A check failed for that service. Find the message in [Why does the render stop with an error?](#why-does-the-render-stop-with-an-error) and fix the value it names. The checks run on the merged values, so the value may come from `global.flowx` rather than the service block.

> [accordion] A service starts without a database URL or credentials
>
> Check that the `serverRef` and `credentials` of its selector match keys under `global.flowx.<dependency>.servers` and `.credentials` exactly. A key that matches nothing renders nothing. Run `helm template` and look for the `# postgresql: <entry>` comment to see what was rendered for the entry.

> [accordion] A pod stays in CreateContainerConfigError
>
> The pod references a secret or a secret key that doesn't exist. Compare every `existingSecret.name` and `keyMapping` value in your values file with `kubectl get secret <name> -o jsonpath='{.data}'`. Without `keyMapping`, the key must be named like the field, for example `password`.

> [accordion] Java services fail at startup with an opaque-token introspection placeholder error
>
> The `default` resource server uses `securityType: opaque`. Set it to `jwt`, as described in [Resource servers](#resource-servers).

> [accordion] Calls to a dependency fail with a certificate path or PKIX error
>
> The service doesn't trust the dependency's CA. Add the CA under `global.flowx.certs` and list it in that service's `component.certs`, keeping `elasticsearch` if it was already listed. See [How do I trust a private certificate authority?](#how-do-i-trust-a-private-certificate-authority)

> [accordion] The render stops because autoscaling.maxReplicas is missing
>
> A service has `autoscaling.enabled: true` without `autoscaling.maxReplicas`. Set it, see [How do I scale a service and keep it available?](#how-do-i-scale-a-service-and-keep-it-available)

> [accordion] Services still connect to the standalone Redis after you configured Sentinel or Cluster
>
> The `default` Redis server still has `host: redis-master` from the chart, and `host` wins over `sentinel` and `cluster`. Set `host: ""` on the server, see [How do I use Redis Sentinel or Redis Cluster?](#how-do-i-use-redis-sentinel-or-redis-cluster)

> [accordion] Prometheus shows the ServiceMonitor target as down after you turned on the network policy
>
> The network policy doesn't open the management port. Add an `extraIngress` rule for it, see [How do I restrict network traffic to a service?](#how-do-i-restrict-network-traffic-to-a-service)

***

## Related resources

> [card] [Migrate to the flowx-ai Helm chart](./migrate-to-flowx-ai-helm-chart)
>
> Service groups, global settings, and the cutover

> [card] [Configuring an IAM solution](./access-management/configuring-an-iam-solution)
>
> Keycloak realm, clients, and roles

> [card] [AI Platform setup](./ai-platform-setup)
>
> AI services, configuration, and deployment

> [card] [SpiceDB](./spicedb)
>
> Authorization service setup


# Data-Sync job setup
Source: https://docs.flowx.ai/5.9/setup-guides/data-sync

Comprehensive guide for configuring and deploying the Data-Sync Job in your Kubernetes environment

## Overview

The Data-Sync Job synchronizes data across multiple databases to maintain consistency and up-to-date information throughout your system. It operates by connecting to various databases, retrieving data, and synchronizing changes across them. The job logs all actions and can be scheduled to run at regular intervals.

***

## Quick start

```bash theme={"dark"}
# 1. Configure your environment variables in a data-sync-job.yaml file
# 2. Apply the configuration
kubectl apply -f data-sync-job.yaml
# 3. Monitor the job status
kubectl get jobs
# 4. Check logs if needed
kubectl logs job/data-sync-job
```

***

## Required environment variables

> [!WARNING]
>
> The Data-Sync Job synchronizes **all core platform components** and requires a database connection for each of them, including the Documents and Notifications plugins. All core platform components must be installed — skipping services during synchronization is not supported, and the job does not start if a connection is missing.

### Database connections

The Data-Sync Job requires connection details for multiple databases. Configure the following sections based on your deployment.

#### MongoDB connections

Each MongoDB-based service requires the following variables:

| Component | Required Variables |
| - | - |
| **CMS** | `FLOWX_DATASOURCE_CMS_URI`, `CMS_MONGO_USERNAME`, `CMS_MONGO_PASSWORD`, `CMS_MONGO_DATABASE` |
| **Scheduler** | `FLOWX_DATASOURCE_SCHEDULER_URI`, `SCHEDULER_MONGO_USERNAME`, `SCHEDULER_MONGO_PASSWORD`, `SCHEDULER_MONGO_DATABASE` |
| **Task Manager** | `FLOWX_DATASOURCE_TASKMANAGER_URI`, `TASKMANAGER_MONGO_USERNAME`, `TASKMANAGER_MONGO_PASSWORD`, `TASKMANAGER_MONGO_DATABASE` |
| **Document Plugin** | `FLOWX_DATASOURCE_DOCUMENTPLUGIN_URI`, `DOCUMENTPLUGIN_MONGO_USERNAME`, `DOCUMENTPLUGIN_MONGO_PASSWORD`, `DOCUMENTPLUGIN_MONGO_DATABASE` |
| **Notification Plugin** | `FLOWX_DATASOURCE_NOTIFICATIONPLUGIN_URI`, `NOTIFICATIONPLUGIN_MONGO_USERNAME`, `NOTIFICATIONPLUGIN_MONGO_PASSWORD`, `NOTIFICATIONPLUGIN_MONGO_DATABASE` |
| **App Runtime** | `FLOWX_DATASOURCE_APPRUNTIME_URI`, `APPRUNTIME_MONGO_USERNAME`, `APPRUNTIME_MONGO_PASSWORD`, `APPRUNTIME_MONGO_DATABASE` |
| **Integration Designer** | `FLOWX_DATASOURCE_INTEGRATIONDESIGNER_URI`, `INTEGRATIONDESIGNER_MONGO_USERNAME`, `INTEGRATIONDESIGNER_MONGO_PASSWORD`, `INTEGRATIONDESIGNER_MONGO_DATABASE` |
| **Admin** | `FLOWX_DATASOURCE_ADMIN_URI`, `ADMIN_MONGO_USERNAME`, `ADMIN_MONGO_PASSWORD`, `ADMIN_MONGO_DATABASE` |

##### MongoDB URI format

```
mongodb://${USERNAME}:${PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/${DATABASE}
```

#### PostgreSQL connections

| Component | Required Variables |
| - | - |
| **Process Engine** | `FLOWX_DATASOURCE_ENGINE_URL`, `FLOWX_DATASOURCE_ENGINE_USERNAME`, `FLOWX_DATASOURCE_ENGINE_PASSWORD`, `FLOWX_DATASOURCE_ENGINE_DRIVERCLASSNAME` |
| **Application Manager** | `FLOWX_DATASOURCE_APPMANAGER_URL`, `FLOWX_DATASOURCE_APPMANAGER_USERNAME`, `FLOWX_DATASOURCE_APPMANAGER_PASSWORD`, `FLOWX_DATASOURCE_APPMANAGER_DRIVERCLASSNAME` |
| **Authentication System** | `FLOWX_DATASOURCE_AUTHSYSTEM_URL`, `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME`, `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` |
| | |

### OpenID provider configuration

Starting with 5.9.0, data-sync provisions FlowX-managed end-user groups and runtime roles in Keycloak as part of the [runtime authorization](./access-management/runtime-authorization) rollout. Provide admin credentials so the job can call the Keycloak admin API.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak` (the only supported provider). | `-` |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path (for example, `https://auth.example.com/auth/`). | `-` |
| `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` |
| `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` |
| `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. | `admin-cli` |

##### Driver class names

* PostgreSQL: `org.postgresql.Driver`
* Oracle: `oracle.jdbc.OracleDriver`

### Additional configuration

| Variable | Description |
| - | - |
| `SPRING_JPA_DATABASE` | Database type for Spring JPA (e.g., `postgresql`, `oracle`) |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULTSCHEMA` | Default schema for Hibernate |
| `LOGGING_CONFIG` | Path to logging configuration file |

***

## Service to database mapping

Each service in your environment corresponds to specific database datasources:

| Service | Datasources |
| - | - |
| `scheduler-core` | scheduler |
| `cms-core` | cms |
| `task-management-plugin` | task-manager |
| `document-plugin` | document-plugin |
| `notification-plugin` | notification-plugin |
| `runtime-manager` | app-runtime, app-manager |
| `integration-designer` | integration-designer |
| `admin` | admin, engine |
| `process-engine` | engine |
| `application-manager` | app-manager |
| `authorization-system` | auth-system |

***

## Sample configuration

```yaml theme={"dark"}
apiVersion: batch/v1
kind: Job
metadata:
  name: data-sync-job
spec:
  template:
    spec:
      containers:
      - name: data-sync
        image: your-registry/data-sync:latest
        env:
        # MongoDB connections
        - name: FLOWX_DATASOURCE_CMS_URI
          value: "mongodb://${CMS_MONGO_USERNAME}:${CMS_MONGO_PASSWORD}@mongodb-0.mongodb-headless:27017/${CMS_MONGO_DATABASE}"
        # Add all other required environment variables
      restartPolicy: Never
  backoffLimit: 3
```

***

## SpiceDB configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-` |

***

## Best practices

1. Store sensitive credentials in Kubernetes Secrets and reference them in your deployment
2. Include the Data-Sync Job in your CI/CD pipeline for automated deployment
3. Schedule regular runs using a Kubernetes CronJob for periodic synchronization
4. Monitor job execution and set up alerts for failures

***

## Troubleshooting

> [accordion] Database connection failures
>
> **Symptoms:** The Data-Sync Job fails to start or exits with database connection errors.
>
> **Solutions:**
>
> 1. Verify MongoDB and PostgreSQL connection strings are correctly formatted
> 2. Check that database credentials are correct and the user has appropriate permissions
> 3. Ensure network connectivity between the job pod and database services
> 4. For MongoDB, confirm the replica set is healthy and reachable
> 5. For PostgreSQL, verify the JDBC URL format and driver class name

> [accordion] Sync failures
>
> **Symptoms:** Data synchronization completes partially or fails.
>
> **Note:** The Data-Sync Job does **not** use Kafka. It is a batch job that connects directly to each service's database to synchronize data.
>
> **Solutions:**
>
> 1. Check job logs for specific error messages: `kubectl logs job/data-sync-job`
> 2. Verify all database connection strings are correct and reachable from the job pod
> 3. Ensure database users have the required read/write permissions
> 4. Confirm that all core platform components are installed and their connection variables are set

> [accordion] Data inconsistencies after sync
>
> **Symptoms:** Data across services appears out of date or mismatched after the job completes.
>
> **Solutions:**
>
> 1. Check the service-to-database mapping to ensure each service points to the right datasource
> 2. Re-run the Data-Sync Job and monitor logs for partial failures
> 3. Confirm that no concurrent writes occurred during the sync window

> [accordion] Missing required variables
>
> **Symptoms:** Job fails immediately on startup with configuration errors.
>
> **Solutions:**
>
> 1. Ensure all required environment variables are set for each database connection
> 2. Check for typos in environment variable names
> 3. Set the connection variables for every core platform component — the job requires all of them, including components your processes may not actively use

***

## Related resources

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# FlowX Designer setup
Source: https://docs.flowx.ai/5.9/setup-guides/designer-setup-guide

To set up FlowX Designer in your environment, follow this guide.

## Prerequisites management

### Ingress routing

The FlowX Designer is a single-page application (SPA) served from its own pod, with backend API calls proxied to the Process Engine, Application Manager, and the various plugins. Routing for the Designer and every backend service is rendered by the FlowX Helm chart — there is no separate hand-authored NGINX configuration in 5.9.x.

The Designer itself is exposed on the public host at `/` (path preserved), with a wildcard `*.public-host` rule that supports workspace-per-subdomain access. Each backend service the Designer calls has its own ingress rule rendered by the chart (see [Ingress configuration guide](./ingress-configuration) for the complete route reference).

For SPA-specific concerns — TLS, cookie affinity, custom domains — configure these through the chart values (`services.designer.ingress.public.annotations`, `services.designer.ingress.public.extraTls`) or share your requirements with FlowX so they are wired in during the upgrade.

Upgrading from 5.1.x? See [Ingress routing and CORS migration](/5.9/migrating-from-5.1-lts/ingress-routing) for the NGINX → chart-rendered routing transition.

### Outbound network access

In restricted or air-gapped networks, the FlowX Designer loads a few assets over HTTPS from external domains **at runtime, from the end user's browser**. Allowlist the following domains, or route them through an approved outbound proxy, so the Designer works correctly:

| Domain | Port | Used for |
| - | - | - |
| `cdn.ckeditor.com` | 443 | Rich-text editor for document and notification templates |
| `esm.sh` | 443 | Runtime dependencies for custom (code) components |
| `fonts.googleapis.com` | 443 | Web font stylesheets (Roboto, Material Icons) |
| `fonts.gstatic.com` | 443 | Web font files referenced by the stylesheets above |

> [!NOTE]
>
> These requests originate from the user's browser, not from the cluster, so the allowlist must apply to the network the Designer is accessed from (corporate proxy, VPN, or client firewall), not only to cluster egress.

***

## Steps to deploy Frontend app

The FlowX.AI Designer is an SPA application that is packaged in a docker image with `nginx`. The web application allows an authenticated user to administrate the FlowX platform. Environment variables are injected at container startup via `envsubst`.

### Application configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `BASE_API_URL` | Backend API base URL (the host configured in the NGINX ingress) | - |
| `ADMIN_API_URL` | Admin API URL, used for admin-specific backend calls | - |
| `PROCESS_API_PATH` | API path prefix for the process engine (e.g. `/onboarding`, matching the process engine ingress path) | - |
| `STATIC_ASSETS_PATH` | Public URL for static assets / media library CDN | - |
| `BASE_HREF` | HTML base href override for non-root deployments | `/` |
| `VERSION` | Application version string displayed in the UI | - |
| `ROOT_DOMAIN` | Root domain for the application | - |
| `COLLABORATION_POLLING_INTERVAL` | Polling interval in milliseconds for collaboration features | - |
| `LEGACY_HTTP_VERSION` | Enables legacy HTTP polling mode with SSE reconnect on page visibility change | `false` |

### Authentication (OpenID Connect)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KEYCLOAK_ISSUER` | OpenID Connect provider issuer URL (e.g. `https://your-idp/auth/realms/realmName`) | - |
| `KEYCLOAK_REDIRECT_URI` | OAuth redirect URI (URL of the SPA) | - |
| `KEYCLOAK_CLIENT_ID` | OAuth client ID | - |
| `KEYCLOAK_SCOPES` | OAuth scopes requested during authentication | `openid profile email` |
| `DEFAULT_ORGANIZATION_NAME` | Default organization name for login | - |
| `REQUIRE_HTTPS` | Require HTTPS for OAuth communication | `true` |
| `SHOW_DEBUG_INFORMATION` | Show OAuth debug information in the browser console | `true` |
| `DISABLE_AT_HASH_CHECK` | Disable `at_hash` claim validation | `false` |
| `SKIP_ISSUER_CHECK` | Skip OAuth issuer URL validation | - |
| `STRICT_DISCOVERY_DOCUMENT_VALIDATION` | Enforce strict OIDC discovery document validation | - |

***

## Troubleshooting

### Common issues

> [accordion] NGINX configuration errors
>
> **Symptoms:** 502 Bad Gateway or 404 errors when accessing the Designer.
>
> **Solutions:**
>
> 1. Verify the ingress annotations are correct, especially `rewrite-target` paths
> 2. Check that backend service names and ports match your Kubernetes service definitions
> 3. Ensure CORS origins include all domains the Designer is accessed from
> 4. Validate the `host` values in ingress rules match your DNS configuration
> 5. Check NGINX controller logs for detailed routing errors: `kubectl logs -n ingress-nginx <controller-pod>`

> [accordion] SSO/authentication failures
>
> **Symptoms:** Redirect loops, blank screens after login, or 401 errors.
>
> **Solutions:**
>
> 1. Verify `KEYCLOAK_ISSUER` matches the realm URL exactly (including `/auth/realms/<realm>`)
> 2. Ensure `KEYCLOAK_REDIRECT_URI` matches the SPA URL configured in the Keycloak client
> 3. Check that the Keycloak client ID (`KEYCLOAK_CLIENT_ID`) exists and is enabled
> 4. Confirm the Keycloak client has the correct redirect URIs and web origins configured
> 5. Clear browser cookies and local storage, then try again

> [accordion] WebSocket connection issues
>
> **Symptoms:** Real-time updates not working, SSE events not received, process testing hangs.
>
> **Solutions:**
>
> 1. Verify the SSE ingress configuration routes `/api/events` to the events-gateway service
> 2. Check that `APPLICATION_CORS_ALLOWORIGIN` on the events-gateway service includes the Designer origin. On 5.9.x, each backend service handles CORS, and the NGINX `cors-*` annotations have no effect. See [CORS handling in the ingress configuration](./ingress-configuration#application_cors_alloworigin)
> 3. Ensure the events-gateway service is running and healthy
> 4. Confirm network policies allow traffic from the Designer ingress to the events-gateway pod
> 5. Check for proxy timeout settings that may terminate long-lived connections

***

## Related resources

> [card] [Ingress Configuration](./ingress-configuration)
>
> Configure routing, CORS, and TLS for FlowX services

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# Document Converter setup
Source: https://docs.flowx.ai/5.9/setup-guides/document-converter-setup

Configure the Document Converter service that converts Office documents, images, and text into PDF for downstream parsing.

The Document Converter (`doc-converter`) is a lightweight service that converts source files into PDF. It normalizes Office documents, images, and plain text into a single format the [Document Parser](./document-parser-setup) and other AI workflows can process. It is a separate service from the Document Parser.

> [!NOTE]
>
> The Document Converter is **CPU-only** — it loads no ML models and does not use a GPU. Conversion runs through headless LibreOffice and image libraries.

## Dependencies

The Document Converter connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — event-driven conversion of files stored in object storage
* **Object storage** (S3-compatible / MinIO) — source and result files for the object-conversion endpoint and Kafka mode
* [**CMS Core**](/5.9/setup-guides/cms-setup) — file retrieval from FlowX content management

## Capabilities

The service converts the following input formats to PDF:

| Input | Extensions | Conversion |
| - | - | - |
| Office documents | `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, `.odt`, `.ods`, `.odp`, `.rtf` | Headless LibreOffice |
| Images | `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff`, `.webp`, `.gif` | Placed on an A4 canvas, aspect ratio preserved |
| Text | `.txt` | Rendered to PDF |
| PDF | `.pdf` | Passed through unchanged |

The service runs in two modes:

* **HTTP API** — synchronous conversion of an uploaded file or a file in storage
* **Kafka consumer** — event-driven conversion of files stored in object storage

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/doc-converter`).

| Endpoint | Method | Purpose |
| - | - | - |
| `/api/v1/doc-converter/convert/file` | POST | Convert an uploaded file to PDF |
| `/api/v1/doc-converter/convert/object` | POST | Convert a file from CMS/object storage to PDF |
| `/api/v1/doc-converter/image/file` | POST | Convert an uploaded image to PDF |
| `/api/v1/doc-converter/image/object` | POST | Convert an image from CMS/object storage to PDF |
| `/api/v1/doc-converter/info/health` | GET | Health check |

***

## Configuration

### Server configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `URL_PREFIX` | FastAPI root path for reverse proxy routing | `/doc-converter` |
| `MAX_UPLOAD_MB` | Maximum upload size per request, in MB | `100` |
| `VERBOSE` | Enable verbose/debug logging | `0` |

The service listens on port `8080`.

### Image conversion

| Environment Variable | Description | Default Value |
| - | - | - |
| `IMAGE_MAX_PIXELS` | Maximum pixel count for an input image before it is downscaled | `14960000` (3400 × 4400) |
| `IMAGE_JPEG_QUALITY` | JPEG quality used when normalizing images | `80` |

### Object storage

Required for the object-conversion endpoints and the Kafka consumer, which read and write files in S3-compatible storage.

Set either the `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_*` variables or the `MINIO_DOCUMENTS_*` variables. When both are set, the `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_*` value is used. Include the scheme in the endpoint URL: an `https://` URL turns on TLS.

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SERVER_URL` | Object storage endpoint URL. Takes precedence over `MINIO_DOCUMENTS_URL` | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` | Bucket for source and result files. Takes precedence over `MINIO_DOCUMENTS_BUCKET` | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_ACCESS_KEY` | Object storage access key. Takes precedence over `MINIO_DOCUMENTS_ACCESS_KEY` | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SECRET_KEY` | Object storage secret key. Takes precedence over `MINIO_DOCUMENTS_SECRET_KEY` | - |
| `MINIO_DOCUMENTS_URL` | Object storage endpoint URL | `none` |
| `MINIO_DOCUMENTS_BUCKET` | Bucket for source and result files | `none` |
| `MINIO_DOCUMENTS_ACCESS_KEY` | Object storage access key | `none` |
| `MINIO_DOCUMENTS_SECRET_KEY` | Object storage secret key | `none` |
| `CMS_USE_PRIVATE` | Retrieve files through the private CMS path | `1` |

> [!NOTE]
>
> The Kafka consumer is enabled by default. Configure Kafka connection and authentication as described in the [Kafka authentication configuration](/5.9/setup-guides/kafka-authentication-config) guide. CORS for the HTTP endpoints is configured through the standard `APPLICATION_CORS_ALLOW_*` variables — see the [Ingress configuration](/5.9/setup-guides/ingress-configuration) guide.

### Observability (optional)

| Environment Variable | Description | Default Value |
| - | - | - |
| `USE_OBSERVATORY` | Send telemetry to FlowX Observatory | `0` |
| `FLOWX_OBSERVATORY_API_URL` | FlowX Observatory API URL | - |

***

## Deployment and sizing

The Document Converter is a lightweight, **CPU-only** service — it needs no GPU. Conversions run as short-lived LibreOffice subprocesses, so memory is the main resource to size for; large Office documents can briefly increase memory use.

| Setting | Value |
| - | - |
| Replicas | 1 (default) |
| Autoscaling | Min 1, Max 5, HPA target CPU 50% |
| RAM requests/limits | \~1 Gi (FlowX Cloud production runs 896 Mi) |
| GPU | None |

> [!TIP]
>
> Increase the memory limit if you convert large or complex Office documents. Scale horizontally with more replicas for higher conversion throughput.

***

## Verify your setup

> [!TIP]
>
> The Document Converter pod is running: `kubectl get pods -l app=doc-converter`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://doc-converter:8080/api/v1/doc-converter/info/health`

> [!TIP]
>
> Test a conversion against the `/api/v1/doc-converter/convert/file` endpoint and verify the response is a PDF.

***

## Related resources

> [card] [Document Parser setup](./document-parser-setup)
>
> Configure the Document Parser for text extraction and OCR

> [card] [AI Platform setup](./ai-platform-setup)
>
> Configure AI Platform services and service discovery

> [card] [Kafka authentication](./kafka-authentication-config)
>
> Configure Kafka connection and authentication

> [card] [CMS Core setup](./cms-setup)
>
> Configure content management for file retrieval


# Document Parser setup
Source: https://docs.flowx.ai/5.9/setup-guides/document-parser-setup

Configure the Document Parser service for document text extraction, OCR processing, and AI-powered document parsing.

The Document Parser service handles document and image processing for AI workflows. It provides multiple parsing engines, OCR capabilities, table extraction, document classification, and signature detection.

## Dependencies

The Document Parser connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — async document processing and inter-service communication
* [**Identity provider**](/5.9/setup-guides/access-management/configuring-an-iam-solution) (Keycloak or Azure AD) — authentication
* [**CMS Core**](/5.9/setup-guides/cms-setup) — file retrieval from FlowX content management
* **AI provider** (OpenAI, Azure OpenAI, Ollama, Anthropic, or GCP) — required for LLM and VLM parsing engines
* **Vector database** (Qdrant) — optional, for RAG use cases
* **PostgreSQL** — job store for parse jobs from Integration Designer (see [Job store](#job-store-postgresql))

> [!NOTE]
>
> The Document Parser retrieves CMS files through CMS Core, but it also connects to the documents object storage directly. It offloads Kafka job payloads larger than 512,000 bytes there, and it reads files passed as a `bucket/key` reference. Set the connection with `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SERVER_URL` (include the scheme: an `https://` URL turns on TLS), `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_ACCESS_KEY` and `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SECRET_KEY`, or the equivalent `MINIO_DOCUMENTS_URL`, `MINIO_DOCUMENTS_ACCESS_KEY` and `MINIO_DOCUMENTS_SECRET_KEY`. Offloaded payloads go to `KAFKA_OFFLOAD_BUCKET`, then to the documents bucket (`APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` or `MINIO_DOCUMENTS_BUCKET`), and to `workflows-bucket` when neither is set.

> [!NOTE]
>
> The Document Parser is a Python 3.13 service that loads ML models at startup. Plan for longer startup times (5–20 minutes) compared to Java-based FlowX services.

***

## Capabilities

### What it can do

* **Multi-format parsing**: PDF, DOCX, XLSX/XLS/XLSM, PPTX, JPG, PNG, TIFF
* **Three parsing engine families**: Classic, LLM, and Docling (with Auto/Simple/OCR/VLM modes)
* **OCR text extraction**: Tesseract, EasyOCR, and RapidOCR (RapidOCR up to 5.9.5 only)
* **Table structure extraction**: Detect and extract tabular data
* **Document classification**: Keyword-based or LLM-based
* **Signature detection**: Locate signatures within documents
* **Page rotation detection**: Detect and correct rotated pages
* **Semantic chunking**: Smart chunking for Retrieval-Augmented Generation (RAG) workflows
* **Vector store integration**: Store embeddings in Qdrant

### What it cannot do

* Cannot process encrypted or password-protected PDFs
* Cannot process audio or video files
* Cannot edit or modify source documents
* Does not perform language translation

***

## Supported formats

| Format | Extensions | Notes |
| - | - | - |
| PDF | `.pdf` | All parsing engines supported |
| Word | `.docx` | Docling and Classic engines |
| Excel | `.xlsx`, `.xls`, `.xlsm` | Table extraction supported |
| PowerPoint | `.pptx` | Slide-by-slide extraction |
| Images | `.jpg`, `.png`, `.tiff` | Converted to PDF before parsing |

***

## Parsing engines

The Document Parser supports six parsing modes organized into three engine families:

| Engine | API Value | Best for | Speed | Cost | Accuracy |
| - | - | - | - | - | - |
| Classic | `ClassicParser` | Clean text PDFs | Fast | Free | Low–Medium |
| LLM | `LLMParser` | Any document via AI vision | Slow | High | High |
| Docling Simple | `DoclingParserSimple` | Standard business documents | Medium | Low | Medium |
| Docling OCR | `DoclingParserOCR` | Scanned/image-heavy documents | Slow | Medium–High | High |
| Docling VLM | `DoclingParserVLM` | Complex layouts | Slow | High | Highest |
| Docling Auto | `DoclingParserAuto` | Unknown documents (auto-routes) | Varies | Varies | Varies |

> [!NOTE]
>
> **Docling Auto** analyzes each page using text density, gibberish ratio, image area coverage, and layout metrics. It then routes each page to the cheapest engine that can handle it: **Standard** (simple extraction), **OCR** (text-poor/garbled pages), or **VLM** (complex visual layouts).

### Engine selection guide

> [tab] Classic
>
> Uses PyMuPDF for direct text extraction from the PDF file structure, with Tesseract OCR as a fallback for empty pages.
>
> * Zero cost (no external API calls)
> * Fastest processing
> * Only works with digital PDFs that have selectable text
> * Falls back to Tesseract OCR when pages have no text layer

> [tab] LLM
>
> Encodes each page as a base64 image and sends it to an AI vision model for extraction.
>
> * Highest accuracy for complex documents
> * Most expensive (AI API call per page)
> * Handles any document type including handwritten text
> * Supports multiple providers: OpenAI, Azure OpenAI, Ollama, Anthropic, GCP

> [tab] Docling
>
> IBM's open-source document processing library with multiple modes:
>
> * **Simple** — Layout analysis without OCR, good for standard business documents
> * **OCR** — Adds OCR processing for scanned documents
> * **VLM** — Uses vision-language models for the highest accuracy on complex layouts
> * **Auto** — Automatically selects the best mode per page based on content analysis

### LiteParse engine

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.2**

**LiteParse** (`parser_engine` value: `LiteParse`) adds a seventh parsing mode that runs fully locally, built on PDFium with bundled Tesseract OCR. It makes no AI calls and requires no GPU, so it offers fast, zero-cost parsing of PDFs and images, including scanned pages that the Classic engine cannot read, without the cost of the LLM or VLM engines.

In the same release, OCR language support across all engines expands to English, Romanian, Hungarian, and Bulgarian.

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/doc-parser`).

| Endpoint | Method | Purpose |
| - | - | - |
| `/api/v1/doc-parser/extract/parse_file` | POST | Parse an uploaded file (multipart form) |
| `/api/v1/doc-parser/extract/parse_object` | POST | Parse a file from CMS or MinIO (JSON body) |
| `/api/v1/doc-parser/extract/store_text` | POST | Store extracted text as embeddings in a vector database |
| `/api/v1/doc-parser/info/health` | GET | Health check |

***

## Configuration

### Server configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `URL_PREFIX` | FastAPI root path for reverse proxy routing | `/doc-parser` |
| `GUNICORN_WORKERS` | Number of Gunicorn worker processes | `1` |
| `GUNICORN_TIMEOUT` | Worker timeout in seconds | `600` |
| `GUNICORN_GRACEFUL_TIMEOUT` | Graceful shutdown timeout in seconds | `320` |
| `USE_DOCLING` | Pre-download Docling models at startup. No effect starting with 5.9.6 | `0` |
| `VERBOSE` | Enable verbose/debug logging | `0` |

> [!WARNING]
>
> Keep `GUNICORN_WORKERS` at `1` per pod. The Document Parser loads large ML models into memory — multiple workers per pod will cause out-of-memory (OOM) errors. Scale horizontally by adding more pods instead.

> [!TIP]
>
> Starting with FlowX.AI 5.9.6, the layout, table, and OCR models are part of the Document Parser image, so nothing is downloaded at startup or on the first document, and the parser runs without internet access or on a read-only filesystem. `USE_DOCLING` has no effect.
>
> On 5.9.5 and earlier, set `USE_DOCLING` to `1` if you use Docling parsing engines. This pre-downloads models at startup rather than on first request, avoiding timeout issues on the first document.

***

### AI model configuration

The Document Parser uses three types of AI models, each independently configurable:

| Model type | Variable | Purpose | Default |
| - | - | - | - |
| Chat | `MODEL_TYPE` | LLM-based parsing, classification, structured extraction | `OPENAI` |
| Vision | `VISION_MODEL_TYPE` | VLM parsing, image analysis | `OPENAI` |
| Embedding | `EMBEDDING_MODEL_TYPE` | Vector store embeddings, semantic chunking | `OPENAI` |

| Environment Variable | Description | Default Value |
| - | - | - |
| `FALLBACK_MODEL_TYPE` | Fallback LLM provider if primary fails | - |
| `STRUCTURED_OUTPUT_METHOD` | Structured output method for LLM | `json_schema` |
| `VLM_API_TIMEOUT` | Timeout in seconds for VLM API calls | `300` |

> [!NOTE]
>
> All three model types support the same providers: `OPENAI`, `AZUREOPENAI`, `OLLAMA`, `ANTHROPIC`, `GCP`, `GCP_VERTEX`, `CUSTOM_OPENAI`, `OPENAI_COMPATIBLE`. Embedding models additionally support `HUGGINGFACE` and `AWS`.

#### Provider-specific variables

> [tab] OpenAI
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `OPENAI_API_KEY` | OpenAI API key | - |
> | `OPENAI_MODEL_NAME` | Chat model name | `gpt-5.4-mini` |
> | `OPENAI_VISION_MODEL_NAME` | Vision model name | `gpt-5.4-mini` |
> | `OPENAI_EMBEDDING_MODEL_NAME` | Embedding model name | `text-embedding-3-large` |
> | `OPENAI_CHUNK_SIZE` | Embedding chunk size | `1000` |

> [tab] Azure OpenAI
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `AZURE_OPENAI_API_KEY` | Azure OpenAI API key | - |
> | `AZURE_OPENAI_INSTANCE_NAME` | Azure OpenAI instance name | - |
> | `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version | `2025-01-01-preview` |
> | `AZURE_OPENAI_MODEL` | Azure model deployment name | `gpt-5.4-mini` |
> | `AZUREOPENAI_MODEL_NAME` | Chat model name | `gpt-5.4-mini` |
> | `AZUREOPENAI_VISION_MODEL_NAME` | Vision model name | `gpt-5.4-mini` |
> | `AZUREOPENAI_EMBEDDING_MODEL_NAME` | Embedding model name | `text-embedding-3-large` |

> [tab] Ollama
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `OLLAMA_BASE_URL` | Ollama server URL | - |
> | `OLLAMA_MODEL_NAME` | Chat model name | `llama3.2:latest` |
> | `OLLAMA_VISION_MODEL_NAME` | Vision model name | `llava:7b-v1.6` |
> | `OLLAMA_EMBEDDING_MODEL_NAME` | Embedding model name | `all-minilm:33m` |

> [tab] Other providers
>
> **Anthropic:**
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `ANTHROPIC_MODEL_NAME` | Chat model name | `anthropic-1.0` |
> | `ANTHROPIC_VISION_MODEL_NAME` | Vision model name | `anthropic-1.0` |
>
> **Google Cloud / Vertex AI:**
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `GCP_PROJECT_ID` | Google Cloud project ID | - |
> | `GCP_LOCATION` | Google Cloud region | - |
> | `GCP_MODEL_NAME` | Chat model name | `gemini-1.5-pro` |
> | `GCP_VISION_MODEL_NAME` | Vision model name | `gemini-1.5-pro` |
>
> **Custom OpenAI-compatible:**
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `CUSTOM_OPENAI_BASE_URL` | API base URL | - |
> | `CUSTOM_OPENAI_CLIENT_ID` | Client ID | - |
> | `CUSTOM_OPENAI_SECRET_KEY` | Secret key | - |
> | `CUSTOM_OPENAI_MODEL_NAME` | Chat model name | `gpt-5.4-mini` |
> | `CUSTOM_OPENAI_VISION_MODEL_NAME` | Vision model name | `gpt-5.4-mini` |
> | `CUSTOM_OPENAI_EMBEDDING_MODEL_NAME` | Embedding model name | `text-embedding-3-large` |

***

### OCR configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `OMP_NUM_THREADS` | Number of threads for OCR processing | `4` |

> [!NOTE]
>
> The OCR engine is selected per-request via the API `ocr_engine` parameter. Available engines: `tesseract-cli` (default), `tesseract-ocr`, `rapidocr`, `easyocr`. Starting with FlowX.AI 5.9.6, a request for `rapidocr` runs `tesseract-cli` instead.

***

### Vector database configuration (optional)

Required only if using semantic chunking and RAG workflows. The Document Parser stores embeddings in Qdrant.

| Environment Variable | Description | Default Value |
| - | - | - |
| `QDRANT_HOST` | Qdrant server URL | `http://localhost:6333` |

***

### Job store (PostgreSQL)

The Document Parser runs parse jobs from Integration Designer through a durable job queue that keeps each job's state in PostgreSQL. The queue is on by default. With the `flowx-ai` Helm chart, the connection variables point at the `doc_parser` database.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DURABLE_ENABLED` | Run parse jobs through the durable job queue (`0` to turn off). With `0`, the service does not consume the job request topic, so Integration Designer parse jobs are not processed | `1` |
| `POSTGRES_URI` | PostgreSQL host and port, without a scheme | `postgresql:5432` |
| `POSTGRES_DATABASE` | Database name | `doc_parser` |
| `POSTGRES_USERNAME` | Database user | `flowx` |
| `POSTGRES_PASSWORD` | Required. Database password | - |
| `POSTGRES_DSN` | Full connection string (`postgresql+asyncpg://user:password@host:port/database`). When set, the four variables above are ignored | - |
| `DOC_PARSER_KAFKA_CONSUMER_GROUP` | Kafka consumer group for the job queue | `doc-parser-jobs` |

> [!WARNING]
>
> If `POSTGRES_PASSWORD` is not set (and `POSTGRES_DSN` is not used), the service fails at startup with a `postgres_dsn is required` error.

The job queue uses these Kafka topics:

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_JOB_REQUEST_TOPIC` | Parse job requests from Integration Designer | `ai.flowx.ai-platform.doc-parser.job.request.v1` |
| `KAFKA_JOB_RESPONSE_TOPIC` | Parse job responses to Integration Designer | `ai.flowx.ai-platform.doc-parser.job.response.v1` |
| `KAFKA_JOB_DLQ_TOPIC` | Dead-letter topic for failed parse jobs | `ai.flowx.ai-platform.doc-parser.job.dlq.v1` |

***

### Observability (optional)

#### Langfuse

| Environment Variable | Description | Default Value |
| - | - | - |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key | - |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key | - |
| `LANGFUSE_HOST` | Langfuse server URL | - |

***

## Deployment and sizing

The Document Parser ships as a single image that **auto-detects an NVIDIA GPU**. If a GPU is scheduled to the pod, the service uses it to accelerate the local Docling OCR and VLM engines; with no GPU, it runs CPU-only. A GPU is optional — the Classic engine and the LLM (AI-vision) engine don't benefit from it, since LLM parsing offloads to an external AI provider.

> [!NOTE]
>
> GPU acceleration applies only to the local **Docling** engines — the document layout model, OCR, and VLM. Classic parsing and LLM/AI-vision parsing see no speedup from a GPU.

### Kubernetes configuration (15,000 pages/day)

The following profiles size a **CPU-only** deployment. For GPU sizing, see [GPU acceleration](#gpu-acceleration) below.

> [tab] Steady load
>
> For predictable, consistent workloads:
>
> | Setting | Value |
> | - | - |
> | Replicas | 3 |
> | CPU requests | 3 cores |
> | CPU limits | 4 cores |
> | RAM requests | 4 Gi |
> | RAM limits | 6 Gi |
> | `GUNICORN_WORKERS` | `1` |
> | `OMP_NUM_THREADS` | `4` |

> [tab] Autoscaling
>
> For variable workloads with burst capacity:
>
> | Setting | Value |
> | - | - |
> | Min replicas | 2 |
> | Max replicas | 7 |
> | CPU requests | 3 cores |
> | CPU limits | 4 cores |
> | RAM requests | 4 Gi |
> | RAM limits | 6 Gi |
> | `GUNICORN_WORKERS` | `1` |
> | `OMP_NUM_THREADS` | `4` |
> | HPA target CPU | 70% |

### GPU acceleration

To speed up the local Docling OCR and VLM engines on scanned or complex documents, schedule the Document Parser on GPU nodes. The image detects the GPU automatically — no configuration flag is required. FlowX Cloud production environments run this profile.

| Setting | Value |
| - | - |
| GPU | 1 × NVIDIA GPU per pod (`nvidia.com/gpu: 1`), CUDA 12.x |
| CPU requests | 3 cores |
| RAM requests/limits | 13 Gi |
| Node scheduling | GPU node pool via `nodeSelector` + toleration for the GPU taint |
| `GUNICORN_WORKERS` | `1` |

> [!NOTE]
>
> FlowX Cloud runs the Document Parser on NVIDIA T4 GPUs (AWS `g4dn.xlarge`). Self-hosted deployments can use any CUDA 12.x-compatible NVIDIA GPU.

> [!WARNING]
>
> GPU nodes must have the [NVIDIA device plugin](https://github.com/NVIDIA/k8s-device-plugin) installed. Add a matching `nodeSelector` and toleration so the Document Parser pod lands on the GPU pool, and request exactly one GPU per pod.

### Important deployment notes

> [!WARNING]
>
> **Pod startup time:** 5–20 minutes. The service loads ML models (OCR, Docling) into memory at startup. Configure your readiness probes and deployment strategy accordingly.

* Set `GUNICORN_TIMEOUT` to at least `600` (10 minutes) — increase for very large documents
* Use `1` Gunicorn worker per pod — scale horizontally with more pods
* Configure liveness probes with a generous initial delay (at least 300 seconds)
* Consider using a `RollingUpdate` strategy with `maxUnavailable: 0` to avoid downtime during deploys
* The service listens on port `8080`

***

## Cost considerations

Estimated monthly costs for a 15,000 pages/day workload using LLM-based parsing:

| Component | Monthly cost estimate |
| - | - |
| OpenAI API calls | \~\$960 |
| Kubernetes compute (3 pods) | \~\$150–500 |
| **Total** | **\~\$1,100–1,460** |

### Cost reduction tips

> [card] Use keyword-only classification
>
> Set `use_llm_to_classify` to `false` in API calls instead of LLM-based classification. Saves \~\$450/month.

> [card] Use Docling Auto
>
> Let Docling Auto route pages to the cheapest engine that works. Saves \~\$240/month compared to forcing OCR on all pages.

> [card] Turn off signature detection
>
> Set `detect_signature` to `false` in API calls when not needed. Saves \~\$90/month.

> [card] Use Classic for clean PDFs
>
> Route clean digital PDFs to the Classic engine (free, no API calls). Reserve LLM/Docling for scanned or complex documents.

***

## Verify your setup

> [!TIP]
>
> The Document Parser pod is running: `kubectl get pods -l app=document-parser`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://document-parser:8080/api/v1/doc-parser/info/health`

> [!TIP]
>
> ML models loaded successfully — check pod logs for model initialization messages (this can take 5–20 minutes)

> [!TIP]
>
> Test a document parse request against the `/api/v1/doc-parser/extract/parse_file` endpoint and verify the response contains extracted text

***

## Troubleshooting

> [accordion] OOM kills (out of memory)
>
> **Symptoms:** Pods restart with OOMKilled status.
>
> **Solutions:**
>
> * Increase memory limits (try 8 Gi)
> * Ensure `GUNICORN_WORKERS` is set to `1`
> * Reduce `OMP_NUM_THREADS` to `2`
> * Check for concurrent large document processing

> [accordion] Slow document processing
>
> **Symptoms:** Documents take much longer than expected to process.
>
> **Solutions:**
>
> * For the local Docling OCR/VLM engines, deploy on GPU nodes (see [GPU acceleration](#gpu-acceleration)) — on CPU these engines work but are significantly slower
> * Verify network latency to the AI provider
> * Use Docling Auto instead of forcing VLM on all documents
> * Check pod CPU utilization — may need more replicas

> [accordion] Low extraction accuracy
>
> **Symptoms:** Extracted text is incomplete or garbled.
>
> **Solutions:**
>
> * Try VLM or LLM mode for complex documents
> * Check source document quality (low resolution images reduce OCR accuracy)
> * Ensure the correct OCR engine is configured for your document language
> * Use `apply_rotation: true` for scanned documents that may be rotated

> [accordion] Pod fails to start
>
> **Symptoms:** Pod stays in CrashLoopBackOff or never becomes ready.
>
> **Solutions:**
>
> * Increase readiness probe initial delay to 600 seconds
> * Check that ML model files are accessible (network or storage issues)
> * Verify memory limits are sufficient for model loading (minimum 4 Gi)
> * Review pod logs for specific error messages

***

## Related services

The **Document Converter** (`doc-converter`) is a separate, CPU-only service that converts Office documents, images, and text into PDF before parsing. See the [Document Converter setup](./document-converter-setup) guide.

***

## Related resources

> [card] [Extract Data from File](/5.9/ai-platform/agent-builder/extract-data-from-file)
>
> Configure the Extract Data from File AI node in Agent Builder

> [card] [AI Platform setup](/5.9/setup-guides/ai-platform-setup)
>
> Configure AI Platform services and service discovery

> [card] [Agent Builder overview](/5.9/ai-platform/agent-builder/overview)
>
> Get started with Agent Builder workflows


# Documents plugin setup
Source: https://docs.flowx.ai/5.9/setup-guides/documents-plugin-setup

The Documents plugin provides functionality for generating, persisting, combining, and manipulating documents within the FlowX.AI system.

The plugin is available as a docker image.

## Dependencies

Before setting up the plugin, ensure that you have the following dependencies installed and configured:

* [PostgreSQL](https://www.postgresql.org/) Database: You will need a PostgreSQL database to store data related to document templates and documents.
* [MongoDB](https://www.mongodb.com/2) Database: MongoDB is required for the HTML templates feature of the plugin.
* Kafka: Establish a connection to the Kafka instance used by the FlowX.AI engine.
* [Redis](https://redis.io/): Set up a Redis instance for caching purposes.
* S3-Compatible File Storage Solution: Deploy an S3-compatible file storage solution to store document files.

***

## Configuration

The plugin comes with pre-filled configuration properties, but you need to set up a few custom environment variables to tailor it to your specific setup. Here are the key configuration steps:

### Redis server

The plugin can utilize the [Redis component](https://app.gitbook.com/@flowx-ai/s/flowx-docs/flowx-engine/setup-guide#2-redis-server) already deployed for the FLOWX.AI engine. Make sure it is configured properly.

### Authorization configuration

The Documents plugin validates incoming tokens with the JWT public key mechanism:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

### Document processing configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DEFAULTCLIENTTYPE` | Default client type | `PF` |
| `FLOWX_HTML_TEMPLATES_ENABLED` | Enable HTML templates feature | `false` |
| `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` | Paths to fonts for HTML templates | `/statics/fonts/Calibri.ttf, /statics/fonts/DejaVuSans.ttf` |
| `FLOWX_CONVERT_DPI` | DPI setting for PDF to image conversion | `150` |

> [!NOTE]
>
> Set the `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` config to select the font used for generating documents based on PDF templates.

> [!NOTE]
>
> If you want to use specific fonts in your PDF templates, override the `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` config. By default, Calibri and DejaVuSans are available fonts.

> [!NOTE]
>
> `FLOWX_CONVERT_DPI`:	Sets the DPI (dots per inch) for PDF to JPEG conversion. Higher values result in higher resolution images. (Default value: `150`).

After making these configurations, the fonts will be available for use within PDF templates.

### Database configuration

#### SQL database (PostgreSQL)

The Documents Plugin uses a PostgreSQL database for relational data storage.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for PostgreSQL | `jdbc:postgresql://jx-documentdb:5432/document` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | - |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class | `org.postgresql.Driver` |

#### Primary MongoDB configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://flowx:password@jx-document-mongodb:27017/document` |
| `MONGODB_USERNAME` | MongoDB username | `flowx` |
| `MONGODB_PASSWORD` | MongoDB password | `password` |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | UUID representation format | `standard` |
| `SPRING_DATA_MONGODB_STORAGE` | MongoDB storage type | `mongodb` |

#### Runtime MongoDB configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection | `true` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | Runtime MongoDB connection URI | `mongodb://${DB_USERNAME:paperflow}:${DB_PASSWORD:password}@jx-app-runtime-mdb:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME` | Runtime MongoDB username, referenced as a placeholder by the default URI. Optional — if you override the full URI, set the credentials there instead. | `paperflow` |
| `DB_PASSWORD` | Runtime MongoDB password, referenced as a placeholder by the default URI. Optional — see `DB_USERNAME`. | `password` |
| `SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION` | Enable automatic index creation. Up to 5.9.5 only: starting with 5.9.6 it has no effect and indexes on the runtime database are never created automatically | `false` |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | UUID representation format for runtime connection | `standard` |

### Redis configuration

Document Plugin uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

### Multipart upload configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_SERVLET_CONTEXTPATH` | Servlet context path | `/` |
| `SPRING_SERVLET_MULTIPART_MAXFILESIZE` | Maximum file size for uploads | `50MB` |
| `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE` | Maximum request size for multipart uploads | `50MB` |

### Processing size limits

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.5**

The plugin enforces size limits on archive, encryption, and extraction operations. Input over the limit is rejected instead of processed. Values are in bytes.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOCUMENT_ARCHIVE_MAX_FILE_SIZE` | Maximum size of a file accepted for archive operations | `209715200` (200 MB) |
| `DOCUMENT_ENCRYPTION_MAX_FILE_SIZE` | Maximum size of a file accepted for encryption | `104857600` (100 MB) |
| `DOCUMENT_EXTRACT_MAX_UNCOMPRESSED_SIZE` | Maximum total uncompressed size an archive may expand to during extraction | `209715200` (200 MB) |

***

## Basic Kafka configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Address of Kafka server(s) (also accepts `SPRING_KAFKA_BOOTSTRAPSERVERS`) | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka (also accepts `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT` |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group ID for the service | `kafka-svc-document-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size in bytes | `52428800` (50MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval for auth exceptions | `10` (seconds) |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

***

## Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |

***

## Thread configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTGENERATEHTMLIN` | Threads for HTML document generation | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTPERSISTIN` | Threads for document persistence | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTSPLITIN` | Threads for document splitting | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_DOCUMENTGETURLSIN` | Threads for document URL retrieval | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_OCRIN` | Threads for OCR processing | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEDELETEIN` | Threads for file deletion | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEUPDATEIN` | Threads for file updates | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILECONVERTIN` | Threads for file conversion | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEPERSISTIN` | Threads for file persistence | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILECOMBINEIN` | Threads for file combining | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEENCRYPTIN` | Threads for file encryption | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEDECRYPTIN` | Threads for file decryption | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN` | Threads for file archive | `5` |
| `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEEXTRACTIN` | Threads for file extract | `5` |

***

## Document topics

### Generate HTML documents

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN` | Topic for incoming HTML generation requests | `ai.flowx.plugin.document.trigger.generate.html.v1` |
| `KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_OUT` | Topic for HTML generation results | `ai.flowx.engine.receive.plugin.document.generate.html.results.v1` |

### Document persistence

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_IN` | Topic for incoming document persistence requests | `ai.flowx.plugin.document.trigger.persist.document.v1` |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_OUT` | Topic for document persistence results | `ai.flowx.engine.receive.plugin.document.persist.document.results.v1` |

### Document splitting

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_DOCUMENT_SPLIT_IN` | Topic for incoming document splitting requests | `ai.flowx.plugin.document.trigger.split.document.v1` |
| `KAFKA_TOPIC_DOCUMENT_SPLIT_OUT` | Topic for document splitting results | `ai.flowx.engine.receive.plugin.document.split.document.results.v1` |

### Document URL retrieval

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_DOCUMENT_GET_URLS_IN` | Topic for incoming URL retrieval requests | `ai.flowx.plugin.document.retrieve.urls.v1` |
| `KAFKA_TOPIC_DOCUMENT_GET_URLS_OUT` | Topic for URL retrieval results | `ai.flowx.engine.receive.plugin.document.urls.results.v1` |

### OCR processing

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_OCR_IN` | Topic for incoming OCR requests | `ai.flowx.plugin.document.store.ocr.v1` |
| `KAFKA_TOPIC_OCR_OUT` | Topic for OCR processing results | `ai.flowx.engine.receive.plugin.document.ocr.results.v1` |

***

## File operation topics

### File deletion

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_DELETE_IN` | Topic for incoming file deletion requests | `ai.flowx.plugin.document.trigger.delete.file.v1` |
| `KAFKA_TOPIC_FILE_DELETE_OUT` | Topic for file deletion results | `ai.flowx.engine.receive.plugin.document.delete.file.results.v1` |

### File update

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_UPDATE_IN` | Topic for incoming file update requests | `ai.flowx.plugin.document.trigger.update.file.v1` |
| `KAFKA_TOPIC_FILE_UPDATE_OUT` | Topic for file update results | `ai.flowx.engine.receive.plugin.document.update.file.results.v1` |

### File conversion

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_CONVERT_IN` | Topic for incoming file conversion requests | `ai.flowx.plugin.document.trigger.convert.file.v1` |
| `KAFKA_TOPIC_FILE_CONVERT_OUT` | Topic for file conversion results | `ai.flowx.engine.receive.plugin.document.convert.file.results.v1` |

### File persistence

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_PERSIST_IN` | Topic for incoming file persistence requests | `ai.flowx.plugin.document.trigger.persist.file.v1` |
| `KAFKA_TOPIC_FILE_PERSIST_OUT` | Topic for file persistence results | `ai.flowx.engine.receive.plugin.document.persist.file.results.v1` |

### File combination

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_COMBINE_IN` | Topic for incoming file combination requests | `ai.flowx.plugin.document.trigger.combine.file.v1` |
| `KAFKA_TOPIC_FILE_COMBINE_OUT` | Topic for file combination results | `ai.flowx.engine.receive.plugin.document.combine.file.results.v1` |

### File encryption

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_ENCRYPT_IN` | Topic for incoming file encryption requests | `ai.flowx.plugin.document.trigger.encrypt.file.v1` |
| `KAFKA_TOPIC_FILE_ENCRYPT_OUT` | Topic for file encryption results | `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` |

### File decryption

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_DECRYPT_IN` | Topic for incoming file decryption requests | `ai.flowx.plugin.document.trigger.decrypt.file.v1` |
| `KAFKA_TOPIC_FILE_DECRYPT_OUT` | Topic for file decryption results | `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` |

### File archive

Bundle a list of `fileId`s into a single (optionally password-protected) ZIP, persisted as a new Document/File. Uses the same trigger/reply pattern as encryption.

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_ARCHIVE_IN` | Topic for incoming file archive requests | `ai.flowx.plugin.document.trigger.archive.file.v1` |
| `KAFKA_TOPIC_FILE_ARCHIVE_OUT` | Topic for file archive results | `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` |

### File extract

Unpack a ZIP `fileId` into N persisted Documents/Files. Supports plain and password-protected archives.

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_FILE_EXTRACT_IN` | Topic for incoming file extract requests | `ai.flowx.plugin.document.trigger.extract.file.v1` |
| `KAFKA_TOPIC_FILE_EXTRACT_OUT` | Topic for file extract results | `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` |

### Bulk document persistence

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_BULK_IN` | Topic for incoming bulk document persistence | `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_BULK_OUT` | Topic for bulk document persistence results | `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` |

### UI flow session variable updates

After a UI Flow session document upload completes, the document-plugin sends the result to the process-engine so the session variables are updated automatically.

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending document upload results to process-engine for UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` |

### UI Flow multi-file upload

When a UI Flow uploads several files at once, the process-engine sends a single bulk command to document-plugin instead of one command per file. The document-plugin persists each file in the session and emits a single SSE frame (`eventType=UI_FLOW_FILE_UPLOAD_MULTIPLE`, `namespace=uploadBatchId`) at the end of the batch via events-gateway, then forwards the per-file results to `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`.

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN` | Topic consumed by document-plugin to persist a single UI Flow upload session. | `ai.flowx.plugin.document.trigger.persist.document.session.v1` |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` |

### Events Gateway messages

The document-plugin publishes real-time SSE frames to the frontend through the Events Gateway — for example, the single `UI_FLOW_FILE_UPLOAD_MULTIPLE` frame emitted at the end of a multi-file upload batch. These messages are sent to the Events Gateway on a dedicated topic.

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Topic for sending SSE messages to the Events Gateway | `ai.flowx.eventsgateway.receive.document.v1` |

***

## Audit

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### General storage configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_DEFAULTLOCALE` | Default locale for the application | `en` |
| `APPLICATION_SUPPORTEDLOCALES` | Comma-separated list of supported locales | `en, ro` |
| `APPLICATION_FILESTORAGE_TYPE` | Storage type to use (`s3` or `fileSystem`) | `s3` |
| `APPLICATION_FILESTORAGE_DISKDIRECTORY` | Directory for file storage when using filesystem | `MS_SVC_DOCUMENT` |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | Strategy for file organization (`NONE` or `PROCESS_DATE`) | `NONE` |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | Strategy for deleting files (`delete`, `disabled`, or `deleteBypassingGovernanceRetention`) | `delete` |
| `APPLICATION_FILESTORAGE_TESTFILESBUCKET` | Custom bucket name for test files (overrides default `-test-documents` suffix) | `{bucket-prefix}-test-documents` |

> [!NOTE]
>
> `APPLICATION_FILESTORAGE_DELETIONSTRATEGY`:
>
> * `disabled`: This will disable entirely the deletion of temporary files from the temporary bucket, and the responsibility to delete and clean up the bucket will move in the ownership of the admins of the implementing project.
> * `deleteBypassingGovernanceRetention`: This will still delete the temporary files and further more will add in the delete request the header: `x-amz-bypass-governance-retention:true` , to enable deletion of governed files, in case the s3 configured user for document-plugin, will have the `s3:BypassGovernanceRetention` permission.

> [!NOTE]
>
> `APPLICATION_FILESTORAGE_TESTFILESBUCKET`: This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed. This is particularly useful when the client environment has restrictions on bucket naming conventions or doesn't have permissions to create new buckets.

### Runtime buckets configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_ENABLED` | Enable dedicated runtime buckets for file storage | `false` |
| `APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_BUCKETNAME` | Name of the runtime bucket | `runtime-bucket` |
| `APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_PARTITIONBYDATE` | Enable date-based partitioning for runtime bucket files | `true` |
| `APPLICATION_FILESTORAGE_S3_RUNTIMEBUCKETS_STATICFILETYPE` | File-type subfolder used for non-partitioned (static) runtime files | `static` |

### Zip extraction configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `ZIP_EXTRACTION_ALLOWEDEXTENSIONS` | Comma-separated list of allowed file extensions in ZIP uploads | `pdf,xls,xlsx,doc,docx,txt,jpg,jpeg,png,gif` |

***

## S3-Compatible storage configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | Enable S3-compatible storage | `true` |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | URL of S3-compatible server | `http://minio-service:9000` |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | Access key for S3 | `minio` |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | Secret key for S3 | `minio123` |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | Prefix for bucket names | `flowx-dev-bucket` |
| `APPLICATION_FILESTORAGE_S3_TEMPBUCKET` | Name of temporary bucket for initial file uploads | `temp-bucket` |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | Enable server-side encryption | `false` |

> [!NOTE]
>
> Make sure to follow the recommended [bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html) when choosing the bucket prefix name.

### Azure Blob Storage through an S3 proxy

Azure Blob Storage does not expose a native S3 API. Deployments on Azure typically place an S3 proxy, such as the open-source [S3Proxy](https://github.com/gaul/s3proxy) project, between the FlowX.AI services and the storage account. S3Proxy is a third-party component: it is not shipped or versioned with FlowX.AI, and you deploy and operate it yourself.

> [!WARNING]
>
> **Multipart uploads require blob index tag permissions**
>
> Files large enough to trigger S3 multipart upload (over 5 MB) fail with an authorization error when the identity used by the S3 proxy holds only the `Storage Blob Data Contributor` role, while smaller uploads work. S3Proxy versions up to 3.3.0 track a multipart upload by writing a blob index tag on a stub blob and reading it back when the upload completes, and `Storage Blob Data Contributor` does not include blob index tag permissions.
>
> Grant the identity used by the S3 proxy one of the following:
>
> * **Storage Blob Data Owner**: includes blob index tag permissions.
> * A custom role based on `Storage Blob Data Contributor` plus the data actions `Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/read` and `Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write`.
>
> S3Proxy 4.0.0 and later record the multipart upload target in blob metadata instead of a blob index tag, which `Storage Blob Data Contributor` covers.

***

## CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

***

## Logging configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_APP` | Log level for application logs | `INFO` |
| `LOGGING_LEVEL_MONGO_DRIVER` | Log level for MongoDB driver | `INFO` |
| `LOGGING_LEVEL_LIQUIBASE` | Log level for Liquibase database migrations | `INFO` |
| `LOGGING_LEVEL_REDIS` | Log level for Redis/Lettuce client | `OFF` |
| `LOGGING_LEVEL_ROOT` | Root logging level for the application | - |

***

## Ingress and CORS

The Document plugin is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/document` | `/` |
| public | `/document` | `/` |

Paths are set through `services.document-plugin.ingress.admin.path` / `services.document-plugin.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values. The chart also applies `nginx.ingress.kubernetes.io/proxy-body-size: 50m` by default on both routes to allow larger document uploads — adjust the annotation if you need a different limit.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that uploads or fetches documents from the browser. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

> [accordion] File upload fails
>
> **Symptoms:** File uploads return errors or time out.
>
> **Solutions:**
>
> 1. Verify the S3/MinIO connection by checking `APPLICATION_FILESTORAGE_S3_SERVERURL`, `APPLICATION_FILESTORAGE_S3_ACCESSKEY`, and `APPLICATION_FILESTORAGE_S3_SECRETKEY`
> 2. Ensure the target bucket exists and the configured user has read/write permissions
> 3. Check that `SPRING_SERVLET_MULTIPART_MAXFILESIZE` is large enough for the files being uploaded
> 4. Verify network connectivity between the pod and the S3-compatible storage service
> 5. On Azure Blob Storage behind an S3 proxy, if only uploads over 5 MB fail with an authorization error, the proxy identity is missing blob index tag permissions; see [Azure Blob Storage through an S3 proxy](#azure-blob-storage-through-an-s3-proxy)

> [accordion] Document generation not working
>
> **Symptoms:** HTML-to-PDF document generation fails or produces empty documents.
>
> **Solutions:**
>
> 1. Verify `FLOWX_HTML_TEMPLATES_ENABLED` is set to `true`
> 2. Check that the font paths in `FLOWX_HTML_TEMPLATES_PDFFONTPATHS` are valid and the font files exist at those paths
> 3. Ensure the Kafka topics for HTML generation (`KAFKA_TOPIC_DOCUMENT_GENERATE_HTML_IN` / `OUT`) are created and accessible
> 4. Verify MongoDB connectivity, as HTML templates are stored in MongoDB

> [accordion] Files not being deleted from temporary storage
>
> **Symptoms:** The temporary S3 bucket grows continuously and files are not cleaned up.
>
> **Solutions:**
>
> 1. Check that `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` is set to `delete` (not `disabled`)
> 2. If using governance-locked buckets, set the strategy to `deleteBypassingGovernanceRetention` and ensure the S3 user has the `s3:BypassGovernanceRetention` permission
> 3. Verify the temporary bucket name configured in `APPLICATION_FILESTORAGE_S3_TEMPBUCKET` matches the actual bucket
> 4. Check application logs for deletion errors or permission issues

> [accordion] PDF conversion fails
>
> **Symptoms:** File conversion requests fail or return errors.
>
> **Solutions:**
>
> 1. Check that the source file format is in the supported list configured via `ZIP_EXTRACTION_ALLOWEDEXTENSIONS`
> 2. Verify `FLOWX_CONVERT_DPI` is set to a valid value (default `150`)
> 3. Ensure the file is not corrupted and uses valid encoding
> 4. Check that the Kafka topics for file conversion (`KAFKA_TOPIC_FILE_CONVERT_IN` / `OUT`) are properly configured

***

## Related resources

> [card] [Uploading Documents](../docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document)
>
> Upload documents to processes using the Documents plugin

> [card] [Generating Documents](../docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates)
>
> Generate documents from HTML templates

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes


# Email Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/email-gateway-setup

This guide provides step-by-step instructions for setting up the Email Gateway microservice.

The Email Gateway is a FlowX.AI microservice that handles email communication workflows. It is available as a Docker image and requires specific infrastructure components to function properly.

## Dependencies

Before setting up the Email Gateway, ensure you have the following dependencies in place:

* **PostgreSQL** database for storing email gateway data
* **MongoDB** connection to the app-runtime database for runtime data access
* **Kafka** for event-driven communication with other FlowX.AI services
* **Redis** for caching
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization

> [!NOTE]
>
> The Email Gateway does not require an ingress configuration as it operates as an internal service communicating via Kafka.

## Infrastructure prerequisites

| Component | Description |
| - | - |
| PostgreSQL | Dedicated database named `email_gateway` |
| MongoDB | Shared connection to the `app-runtime` database |
| Kafka | Message broker for inter-service communication |
| Redis | Caching layer for improved performance |
| Keycloak | Identity provider for service authentication |

***

## Configuration

### Authorization configuration

The Email Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-email-gateway-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

### PostgreSQL configuration

The Email Gateway uses its own dedicated PostgreSQL database for storing email-related data.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for PostgreSQL | `jdbc:postgresql://postgresql:5432/email_gateway` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | - |

> [!WARNING]
>
> Ensure the `email_gateway` database is created before deploying the service. The Email Gateway will manage its own schema migrations.

### MongoDB configuration (app-runtime)

The Email Gateway connects to the shared `app-runtime` MongoDB database for accessing runtime data.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | MongoDB connection URI for app-runtime | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME` | MongoDB username | `app-runtime` |
| `DB_PASSWORD` | MongoDB password | - |

> [!NOTE]
>
> The `retryWrites=false` parameter is required for compatibility with MongoDB replica set configurations that include arbiters.

### Redis configuration

Email Gateway uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

### Kafka configuration

#### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections | `PLAINTEXT` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10` |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

### IMAP configuration

Configure the Email Gateway's IMAP polling behavior for inbound email processing:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` |

### Microsoft Graph configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50` |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL` | TTL for cached MS Graph client instances | `1d` |

> [!TIP]
>
> The client cache TTL controls how long authenticated MS Graph client instances are kept in memory before being refreshed. Increase this value in stable environments to reduce token refresh overhead.

### Master election configuration

The Email Gateway uses a master election mechanism to coordinate work across multiple replicas:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` |

### Rebalancing configuration

Configure how email accounts are distributed across service instances:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance | `100` |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` |

### Kafka topics

The Email Gateway publishes to the following Kafka topics:

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for audit event logging | `ai.flowx.core.trigger.save.audit.v1` |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Topic for triggering process starts from email events | `ai.flowx.core.trigger.start-for-event.process.v1` |

### Logging configuration

Control logging levels for different components:

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |
| `LOGGING_CONFIG` | Path to external logging config file | - |

***

## Secrets management

The Email Gateway requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name | Description |
| - | - |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL database password |
| `DB_PASSWORD` | MongoDB password for app-runtime access |
| `SPRING_REDIS_PASSWORD` | Redis authentication password |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `KAFKA_OAUTH_CLIENT_SECRET` | Kafka OAuth client secret (if using OAuth) |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the Email Gateway:

```yaml theme={"dark"}
fullnameOverride: email-gateway

image:
  registry: <your-registry>
  repository: email-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production
  
  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/email_gateway
  SPRING_DATASOURCE_USERNAME: flowx
  
  # MongoDB (app-runtime)
  SPRING_DATA_MONGODB_RUNTIME_URI: "mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false"
  DB_USERNAME: app-runtime
  
  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092
  KAFKA_OAUTH_CLIENT_ID: kafka-client
  KAFKA_OAUTH_TOKEN_ENDPOINT_URI: https://keycloak.example.com/auth/realms/kafka-authz/protocol/openid-connect/token
  
  # OAuth2
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth
  SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID: flowx-email-gateway-sa
  
  # Redis
  SPRING_REDIS_HOST: redis-master

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: mongodb-generic
    secrets:
      DB_PASSWORD: mongodb-password
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakEmailGatewayClientSecret

rbac:
  create: true

# Email Gateway does not expose HTTP endpoints externally
ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/egress-s-mongodb: "true"
  flowx.ai/routing-name: "email-gateway"
  flowx.ai/prometheus-scrape: "email-gateway"
```

> [!NOTE]
>
> The `image.registry` and `image.repository` split applies to **5.9.4 and later**. To redirect every chart at once, use `global.imageRegistry`. See [Container images and registry](./setup-guides-overview#container-images-and-registry).

### Network policies

The Email Gateway requires network access to the following services:

| Service | Purpose | Pod Label |
| - | - | - |
| Kafka | Message broker communication | `flowx.ai/egress-s-kafka` |
| PostgreSQL | Primary data storage | `flowx.ai/egress-s-postgresql` |
| MongoDB | App-runtime data access | `flowx.ai/egress-s-mongodb` |

***

## Monitoring

The Email Gateway exposes Prometheus metrics for monitoring. Enable scraping by setting the pod label:

```yaml theme={"dark"}
podLabels:
  flowx.ai/prometheus-scrape: "email-gateway"
```

### Health endpoints

| Endpoint | Description |
| - | - |
| `/actuator/health` | Health check endpoint |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info` | Application info endpoint |

***

## Troubleshooting

### Common issues

> [accordion] Database connection failures
>
> **Symptoms:** Service fails to start with database connection errors.
>
> **Solutions:**
>
> 1. Verify the `email_gateway` database exists in PostgreSQL
> 2. Check that the database user has appropriate permissions
> 3. Ensure network connectivity between the pod and PostgreSQL service
> 4. Verify the JDBC URL format is correct

> [accordion] MongoDB connection issues
>
> **Symptoms:** Errors accessing app-runtime data.
>
> **Solutions:**
>
> 1. Verify MongoDB replica set is healthy
> 2. Check that `retryWrites=false` is set in the connection URI
> 3. Ensure the MongoDB user has read access to the `app-runtime` database
> 4. Verify network policies allow MongoDB traffic

> [accordion] Kafka authentication failures
>
> **Symptoms:** Kafka consumer/producer fails to connect.
>
> **Solutions:**
>
> 1. Verify OAuth token endpoint is accessible
> 2. Check Kafka OAuth client credentials
> 3. Ensure the `kafka-authz` realm exists in Keycloak
> 4. Verify network connectivity to both Kafka and Keycloak

> [accordion] Service account authentication errors
>
> **Symptoms:** 401/403 errors when calling other FlowX services.
>
> **Solutions:**
>
> 1. Verify the Keycloak service account is properly configured
> 2. Check that client secrets match between configuration and Keycloak
> 3. Ensure the service account has required roles assigned

***

## Related resources

> [card] [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger)
>
> Configure IMAP connections to trigger processes from incoming emails

> [card] [Email Sender](/5.9/docs/platform-deep-dive/integrations/email-sender)
>
> Configure SMTP connections to send emails from processes

> [card] [Microsoft Outlook](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
>
> Connect to Outlook via MS Graph API for reading and sending emails

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# FlowX Events Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/events-gateway-setup

This guide will walk you through the process of setting up the events-gateway service.

## Infrastructure prerequisites

Before proceeding with the setup, ensure that the following components have been set up:

* **Redis**
* **Kafka**

***

## Configuration

### Configuring Kafka

Set the following Kafka-related configurations using environment variables:

| Configuration Parameter | Default Value | Description |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | `localhost:9092` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) |
| `KAFKA_SECURITY_PROTOCOL` | `PLAINTEXT` | Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) |
| `KAFKA_MESSAGE_MAX_BYTES` | `52428800` | Maximum message size in bytes (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | `10` | Retry interval for auth exceptions (seconds) |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Topic naming configuration

| Configuration Parameter | Default Value | Description |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | `ai.flowx.` | Package prefix for topic names |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | ` ` | Environment segment for topic names |
| `KAFKA_TOPIC_NAMING_VERSION` | `.v1` | Version suffix for topic names |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | `.` | Primary separator for topic names |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | `-` | Secondary separator for topic names |

#### Group IDs

The configuration parameters "KAFKA\_CONSUMER\_GROUPID\_\*" are used to set the consumer group name for Kafka consumers that consume messages from topics. Consumer groups in Kafka allow for parallel message processing by distributing the workload among multiple consumer instances. By configuring the consumer group ID, you can specify the logical grouping of consumers that work together to process messages from the same topic, enabling scalable and fault-tolerant message consumption in your Kafka application.

| Configuration Parameter | Default value | Description |
| - | - | - |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_MESSAGE` | `engine-commands-message` | Consumer group ID for processing engine commands messages |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_DISCONNECT` | `engine-commands-disconnect` | Consumer group ID for processing engine commands disconnect messages |
| `KAFKA_CONSUMER_GROUPID_PROCESSENGINECOMMANDS_CONNECT` | `engine-commands-connect` | Consumer group ID for processing engine commands connect messages |
| `KAFKA_CONSUMER_GROUPID_TASKCOMMANDS_MESSAGE` | `task-commands-message` | Consumer group ID for processing task commands messages |
| `KAFKA_CONSUMER_GROUPID_PROCESSCOMMANDS_MESSAGE` | `process-commands-message` | Consumer group ID for processing process commands messages |
| `KAFKA_CONSUMER_GROUPID_GENERICCOMMANDS` | `generic-commands-message` | Consumer group ID for processing generic commands messages |
| `KAFKA_CONSUMER_GROUPID_USERBROADCASTCOMMANDS` | `user-broadcast-commands-message` | Consumer group ID for processing user broadcast commands messages |

#### Threads

The configuration parameters "KAFKA\_CONSUMER\_THREADS\_\*" are utilized to specify the number of threads assigned to Kafka consumers for processing messages from topics. These parameters allow you to fine-tune the concurrency and parallelism of your Kafka consumer application, enabling efficient and scalable message consumption from Kafka topics.

| Configuration Parameter | Default value | Description |
| - | - | - |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_MESSAGE` | `10` | Number of threads for processing engine commands messages |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_DISCONNECT` | `5` | Number of threads for processing engine commands disconnect messages |
| `KAFKA_CONSUMER_THREADS_PROCESSENGINECOMMANDS_CONNECT` | `5` | Number of threads for processing engine commands connect messages |
| `KAFKA_CONSUMER_THREADS_TASKCOMMANDS` | `10` | Number of threads for task commands messages |
| `KAFKA_CONSUMER_THREADS_PROCESSCOMMANDS` | `10` | Number of threads for processing process commands messages |
| `KAFKA_CONSUMER_THREADS_GENERICCOMMANDS` | `10` | Number of threads for processing generic commands messages |
| `KAFKA_CONSUMER_THREADS_USERBROADCASTCOMMANDS` | `10` | Number of threads for processing user broadcast commands messages |

#### Events Gateway pattern

| Configuration Parameter | Default value | Description |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_PATTERN` | `ai.flowx.eventsgateway.receive.*` | Pattern for Events Gateway communication |

#### Kafka topics related to process instances

| Configuration Parameter | Default value | Description |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_MESSAGE` | `ai.flowx.eventsgateway.engine.commands.message.v1` | Topic for engine commands messages |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_DISCONNECT` | `ai.flowx.eventsgateway.engine.commands.disconnect.v1` | Topic for engine commands disconnect messages |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESSINSTANCE_IN_CONNECT` | `ai.flowx.eventsgateway.engine.commands.connect.v1` | Topic for engine commands connect messages |

#### Kafka topics related to process commands

| Configuration Parameter | Default value | Description |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_PROCESS_IN_MESSAGE` | `ai.flowx.eventsgateway.process.commands.message.v1` | Topic for process commands messages |

#### Kafka topics related to user messages

| Configuration Parameter | Default value | Description |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_USERMESSAGES_IN_MESSAGE` | `ai.flowx.core.designer.notification.user.v1` | Topic for user notification messages |

### Configuring authorization & access roles

Events Gateway validates incoming tokens with the JWT public key mechanism, and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-events-gateway-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.4**
>
> The `mainIdentity` service account is required because Events Gateway calls the Runtime Manager to resolve and authorize a subscription before admitting the stream. Without a valid `mainIdentity`, that call cannot obtain a bearer token and the authorization step fails before the stream is opened. Anonymous subscriptions continue to use `anonymousIdentity`.

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

### Service communication

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_URLS_RUNTIMEMANAGER` | Base URL of the Runtime Manager service | `http://runtime-manager/` |

### Redis configuration

FlowX Events Gateway uses Redis for real-time message distribution. The process engine sends messages to the events-gateway, which is responsible for sending them to Redis.

Events Gateway supports all Redis deployment modes (Standalone, Sentinel, and Cluster). For detailed Redis configuration including all deployment modes and parameters, see the [Redis Configuration](/5.9/setup-guides/redis-configuration) guide.

#### Quick reference

Common Redis configuration parameters:

| Configuration Parameter | Description | Example Value |
| - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname (Standalone mode) | `localhost` |
| `SPRING_DATA_REDIS_PORT` | Redis server port (Standalone mode) | `6379` |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | `yourpassword` |
| `SPRING_DATA_REDIS_SENTINEL_MASTER` | Sentinel master name (Sentinel mode) | `mymaster` |
| `SPRING_DATA_REDIS_SENTINEL_NODES` | Sentinel nodes (Sentinel mode) | `host1:26379,host2:26379` |
| `SPRING_DATA_REDIS_CLUSTER_NODES` | Cluster nodes (Cluster mode) | `host1:6379,host2:6379` |

> [!NOTE]
>
> For complete Redis configuration details including Sentinel mode, Cluster mode, SSL/TLS setup, and troubleshooting, refer to the [Redis Configuration guide](/5.9/setup-guides/redis-configuration).

### Events

This configuration helps manage how event data is stored and accessed in Redis.

| Configuration Parameter | Default | Description |
| - | - | - |
| `EVENTS_REDIS_MODE` | blocking | How the events gateway reads real-time events from Redis. `blocking` holds a Redis connection open per read; `polling` checks for new events at the `EVENTS_REDIS_FREQUENCYMILLIS` interval instead |
| `EVENTS_REDIS_FREQUENCYMILLIS` | 300 | Time interval (in milliseconds) between Redis queries by the events gateway to check for new messages (polling mode only) |
| `EVENTS_REDIS_TTLHOURS` | 4 | Lifetime (in hours) of the allowed-swimlanes set in Redis. On 5.9.5 and earlier, it also sets the lifetime of event streams; starting with 5.9.6, event streams use the [event stream retention](#event-stream-retention) settings instead |

#### Event stream retention

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.6**
>
> Each event stream in Redis keeps a capped number of entries and expires a fixed time after it is created. Publishing new events no longer extends the lifetime, so the stream of a long-running process instance no longer grows for the life of the instance.

| Configuration Parameter | Default | Description |
| - | - | - |
| `EVENTS_REDIS_STREAM_DEFAULTS_MAXLENGTH` | 1000 | Approximate maximum number of entries one event stream keeps. Older entries are trimmed as new events arrive |
| `EVENTS_REDIS_STREAM_DEFAULTS_TTLHOURS` | 4 | Lifetime (in hours) of an event stream, set once when the stream is created and never refreshed |

These defaults apply to any stream type without its own entry. The following stream types have their own limits, set as `events.redis.stream.types.[<type>].max-length` and `events.redis.stream.types.[<type>].ttl-hours` properties. These keys contain brackets, so they can't be set as plain environment variables.

| Stream type | Max length | TTL (hours) |
| - | - | - |
| `events:process` | 500 | 1 |
| `task-man:task` | 200 | 1 |
| `task-man:view` | 200 | 1 |
| `BROADCAST` | 500 | 4 |

#### Blocking-mode connection pool and delivery buffer

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.3**
>
> Blocking mode now uses a dedicated Redis connection pool, and each Server-Sent Events subscriber gets a bounded delivery buffer. These settings resolve a connection buildup that could previously require periodic Events Gateway restarts under sustained load.

| Configuration Parameter | Default | Description |
| - | - | - |
| `EVENTS_REDIS_BLOCKDURATIONSECONDS` | 1 | How long (in seconds) a blocking read waits on Redis before reissuing. Also bounds the delay before a new subscriber joins an in-progress blocking read (blocking mode only) |
| `EVENTS_REDIS_POOL_ENABLED` | true | Turns the dedicated Redis connection pool for blocking reads on or off. Required when `EVENTS_REDIS_MODE` is `blocking` — each blocking read needs its own connection |
| `EVENTS_REDIS_POOL_MAXTOTAL` | 50 | Maximum number of Redis connections in the blocking-read pool |
| `EVENTS_REDIS_POOL_MAXIDLE` | 50 | Maximum number of idle connections kept in the pool |
| `EVENTS_REDIS_POOL_MINIDLE` | 5 | Minimum number of idle connections kept warm in the pool |
| `EVENTS_REDIS_POOL_MAXWAITMILLIS` | 5000 | How long (in milliseconds) a read waits for a pooled connection before failing |
| `EVENTS_REDIS_SSE_BUFFERSIZE` | 256 | Per-subscriber backpressure buffer (in events). Approximate memory use is buffer size × \~500 bytes × connected SSE clients per pod. On overflow the SSE connection is closed so the client reconnects |

### SSE cleanup configuration

Configure how Server-Sent Events (SSE) connections are cleaned up:

| Configuration Parameter | Default | Description |
| - | - | - |
| `EVENTS_SSE_CLEANUP_INTERVAL_MINUTES` | `5` | Interval in minutes between SSE connection cleanup cycles |
| `EVENTS_SSE_CLEANUP_MAX_AGE_MINUTES` | `10` | Maximum age in minutes before an inactive SSE connection is removed |

### Configuring logging

The following environment variables control log levels:

| Configuration Parameter | Description |
| - | - |
| `LOGGING_LEVEL_ROOT` | Logging level for the root Spring Boot microservice logs |
| `LOGGING_LEVEL_APP` | Logging level for the application-level logs |

***

## Ingress and CORS

The Events Gateway is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. The path is preserved end-to-end (no rewrite), because Server-Sent Events use the same path on the backend as on the client.

### Service routes

| Host group | External path | Backend receives | Notes |
| - | - | - | - |
| admin | `/api/events` | `/api/events/...` | Path preserved |
| public | `/api/events` | `/api/events/...` | Path preserved |

Paths are set through `services.events-gateway.ingress.admin.path` / `services.events-gateway.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values. No rewrite is applied because Events Gateway expects the same path on the backend.

> [!NOTE]
>
> Server-Sent Events are long-lived HTTP connections. If you front Events Gateway with a custom ingress controller or reverse proxy, set generous read timeouts (300s+) and disable response buffering on the SSE path.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to open SSE connections from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that subscribes to events. | `-` |

Allowed methods, allowed headers, and credential handling are baked into the service's `application.yaml` with safe defaults for SSE traffic. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

> [accordion] SSE connections dropping unexpectedly
>
> **Symptoms:** Clients lose real-time updates intermittently, SSE connections close after a timeout period.
>
> **Solutions:**
>
> 1. Check your ingress timeout settings — SSE connections require longer timeouts than standard HTTP requests. Set `proxy-read-timeout` and `proxy-send-timeout` to at least `3600` seconds
> 2. Verify keep-alive configuration on your load balancer and ingress controller
> 3. Review the `EVENTS_SSE_CLEANUP_MAX_AGE_MINUTES` setting — ensure it is not set too low for your use case
> 4. Check for network proxies or firewalls that may terminate long-lived connections

> [accordion] Events not reaching the UI
>
> **Symptoms:** Process updates do not appear in the Designer or end-user interface, despite successful process execution.
>
> **Solutions:**
>
> 1. Verify Kafka consumer configuration — check that the consumer group IDs match expected values
> 2. Confirm that the `KAFKA_TOPIC_EVENTSGATEWAY_PATTERN` matches the topics being published to by the process engine
> 3. Check Kafka consumer lag using your monitoring tools to identify backpressure issues
> 4. Ensure the events-gateway service has network access to Kafka brokers

> [accordion] High latency on events
>
> **Symptoms:** Noticeable delay between process execution and UI updates.
>
> **Solutions:**
>
> 1. Check the Redis connection — verify `SPRING_DATA_REDIS_HOST` and `SPRING_DATA_REDIS_PORT` are correct and the Redis instance is responsive
> 2. Review `EVENTS_REDIS_FREQUENCYMILLIS` — lower values reduce latency but increase Redis load
> 3. Check Kafka partition configuration — ensure sufficient partitions for your consumer thread count
> 4. Monitor Kafka consumer thread counts (`KAFKA_CONSUMER_THREADS_*`) and increase if threads are saturated

> [accordion] WebSocket connection failures
>
> **Symptoms:** Browser console shows WebSocket or SSE connection errors, CORS-related error messages.
>
> **Solutions:**
>
> 1. Verify CORS settings in your ingress configuration allow the Designer and application domains
> 2. Ensure the ingress controller supports WebSocket upgrades and SSE connections
> 3. Check that the ingress path pattern `/api/events(/|$)(.*)(/|$)(.*)` is correctly configured
> 4. Confirm that the `events-gateway` service is reachable from the ingress controller

***

## Related resources

> [card] [Ingress Configuration](./ingress-configuration)
>
> Configure routing, CORS, and SSE-specific ingress settings

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [FlowX Engine Setup](./flowx-engine-setup-guide/engine-setup)
>
> Configure the process engine that publishes events to the gateway


# File Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/file-gateway-setup

Set up the File Gateway microservice — ingests files from FTP, SFTP, S3, and Azure Blob storage into FlowX workflows, delivers generated files back, and can trigger processes when new files arrive.

> [!NOTE]
>
> The File Gateway lets workflows exchange files with external storage systems (FTP, SFTP, S3, Azure Blob) and start processes when new files land in a watched location.

## Dependencies

Before setting up the File Gateway, ensure you have the following dependencies in place:

* **MongoDB** for storing file-trigger definitions and poll state
* **Kafka** for publishing process start events
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained, workspace-level authorization
* **Document service** for storing ingested and generated files
* **File storage targets** — the FTP, SFTP, S3, or Azure Blob systems you connect to (credentials are tenant-supplied per connection, not set as service env vars)

## Infrastructure prerequisites

| Component | Description |
| - | - |
| MongoDB | Stores `file_triggers`, `seen_file_cursors`, `failed_files`, `poll_leases` collections (shares the runtime MongoDB instance) |
| Kafka | Message broker for triggering process starts |
| Keycloak | Identity provider for service authentication |
| SpiceDB | Authorization service for workspace validation |
| Document | Receives uploaded files via the document service internal API |

***

## Configuration

### Authorization configuration

The File Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-file-gateway-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

***

### MongoDB configuration

The File Gateway uses the runtime MongoDB instance (the same one used by the Email Gateway) to store file-trigger definitions and polling state.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | - |

***

### Kafka configuration

The File Gateway publishes a process-start event when a watched location receives a new file (a file trigger).

#### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections | `PLAINTEXT` |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Kafka topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_TRIGGER_STARTFOREVENT_PROCESS_OUT` | Topic for starting a process when a watched file arrives | `ai.flowx.core.trigger.start-for-event.process.v1` |

***

### CAS lib configuration (SpiceDB)

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB gRPC port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. Keep the default unless instructed by FlowX. | `CUSTOM` |

***

### Service communication

The File Gateway communicates with the following FlowX services:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization Manager base URL | `http://organization-manager:80` |
| `FLOWX_LIB_CASCLIENT_SERVICES_AUTHORIZATIONSYSTEM_BASEURL` | Authorization System base URL | `http://authorization-system:80` |
| `FLOWX_DOCUMENTPLUGIN_BASEURL` | Document Plugin base URL used to store ingested files | `http://document-plugin:80` |

***

### Logging configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |

***

## File storage connections

File storage targets (FTP, SFTP, S3, Azure Blob) are **not** configured through service environment variables. Each connection — including its host, path, and credentials — is defined per workspace in the FlowX Designer as a **File Storage** data source. Credentials are tenant-supplied and stored securely; the File Gateway never uses pod identity, IAM roles, or managed identities to reach a customer's storage.

Supported authentication methods:

| Protocol | Authentication |
| - | - |
| FTP / FTPS | Username + password |
| SFTP | Username + password, or private key |
| S3 | Access key + secret |
| Azure Blob | Shared key (access key) |

***

## Secrets management

| Secret Name | Description |
| - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI (contains credentials) |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token |
| `KAFKA_OAUTH_CLIENT_SECRET` | Kafka OAuth client secret (if using OAuth) |

***

## Deployment

### Helm values example

```yaml theme={"dark"}
fullnameOverride: file-gateway

image:
  registry: <your-registry>
  repository: file-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # OAuth2
  SECURITY_TYPE: oauth2
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

extraEnvVarsMultipleSecretsCustomKeys:
  - name: mongodb-generic
    secrets:
      SPRING_DATA_MONGODB_URI: mongodb-uri
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakFileGatewayClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/routing-name: "file-gateway"
  flowx.ai/prometheus-scrape: "file-gateway"
```

> [!NOTE]
>
> The `image.registry` and `image.repository` split applies to **5.9.4 and later**. To redirect every chart at once, use `global.imageRegistry`. See [Container images and registry](./setup-guides-overview#container-images-and-registry).

> [!NOTE]
>
> The File Gateway makes outbound connections to customer-managed FTP/SFTP/S3/Azure Blob endpoints. Ensure egress network policies allow traffic to those destinations.

***

## Verify your setup

> [!TIP]
>
> The File Gateway pod is running and healthy: `kubectl get pods -l app=file-gateway`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://file-gateway:8080/actuator/health`

> [!TIP]
>
> MongoDB collections appear (`file_triggers`, `seen_file_cursors`, `failed_files`, `poll_leases`) with the expected indexes

> [!TIP]
>
> SpiceDB connection is established — check pod logs for successful CAS client initialization

***

## Troubleshooting

> [accordion] Files are not picked up from a watched location
>
> **Solutions:**
>
> 1. Confirm the File Storage data source and file trigger are configured and toggled ON in the Designer
> 2. Verify the connection credentials and path in the data source
> 3. Check egress network policies allow the File Gateway to reach the storage host
> 4. Review pod logs for poll or authentication errors

> [accordion] SpiceDB connection failures
>
> **Solutions:**
>
> 1. Verify SpiceDB is running and reachable at the configured host and port
> 2. Check that the SpiceDB token is correct
> 3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`

> [accordion] Processes not starting from file triggers
>
> **Solutions:**
>
> 1. Verify Kafka bootstrap servers are reachable
> 2. Check that the `ai.flowx.core.trigger.start-for-event.process.v1` topic exists
> 3. Confirm the bound Message Start Event and active build for the process

***

## Related resources

> [card] [SpiceDB Configuration](./spicedb)
>
> Fine-grained authorization setup

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [Email Gateway setup](./email-gateway-setup)
>
> The email-trigger gateway this service mirrors

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# Configuring access roles for processes
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/configuring-access-roles-for-processes

Learn how to set up user role-based access control for process definitions using swimlanes, business filters, and permissions configuration.

Process access control in FlowX.AI is managed through a flexible role-based system that allows you to control who can access, view, and interact with different parts of your processes. This guide covers the complete setup and configuration of access roles for processes.

## Overview

FlowX.AI provides two main mechanisms for controlling process access:

* **Swimlanes**: Group process nodes by participants and control access at the node level
* **Business filters**: Restrict access based on dynamic business rules and user attributes

Both mechanisms work together to provide granular control over process security and user permissions.

## Prerequisites

Before configuring process access roles, ensure you have:

1. **Identity Provider Setup**: A configured identity provider (Keycloak, Entra ID, etc.) with user roles defined
2. **Service Account**: A service account with appropriate permissions in your identity provider
3. **Platform Configuration**: Proper platform configuration to connect to your identity provider

> [card] [Identity Provider Setup Guide](../designer-setup-guide)
>
> Complete guide for setting up identity provider integration

## Access control with swimlanes

### What are swimlanes?

Swimlanes provide a way of grouping process nodes by process participants. They allow you to ensure that only users with specific roles can access certain process nodes.

**Key characteristics:**

* By default, all process nodes belong to the same swimlane
* When a token moves between swimlanes, user access is evaluated
* Users without access to a swimlane will see the process in read-only mode
* Users receive notifications when access changes

### Configuring swimlanes

#### Step 1: Set up roles in identity provider

First, configure the desired user roles in your identity provider solution and assign users to the appropriate roles.

> [!TIP]
>
> Use the **Access Management** tab under **General Settings** in FlowX Designer to administrate all roles and view their current assignments.
>
> ![Access Management Roles](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/access_management_roles.png)

#### Step 2: Configure service account

> [!NOTE]
>
> A [service account](../access-management/configuring-an-iam-solution#process-engine-service-account) with appropriate permissions must be configured in your identity provider to allow FlowX.AI to access role information.

#### Step 3: Configure swimlane permissions

Navigate to your process definition and access the **Permissions** tab in the process settings panel. Here you can configure access for each swimlane.

After defining roles in your identity provider solution, they will be available in the process definition settings panel for configuring swimlane access. When you create a new swimlane, it automatically comes with two default permissions assigned.

### Default swimlane permissions

Every process comes with a **Default** swimlane that includes two standard permissions:

![Default Swimlane Roles](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/swimlane_default_roles.png)

* **Execute**: You can start process instances and run actions on them
* **Self-assign**: You can assign process instances to themselves and begin working on them

> [!NOTE]
>
> These default permissions are available in FlowX.AI platform version **2.11.0 and later**.

### Swimlane execution control

#### Allow multiple swimlane executors

For each swimlane, you can control execution permissions by switching between:

* **Swimlane owner + multiple executors** (default)
* **Only Swimlane Owner**

> [!NOTE]
>
> This setting can be configured individually for each swimlane in your process definition.

![Allow Multiple Executors Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/allow_multiple_executors.png)

When **multiple executors** is enabled, you gain additional flexibility to configure permissions at the UI Element level within User Tasks for the selected swimlane.

![Permission-Based UI Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/pemission_%20based_ui.png)

This granular control allows you to:

* Assign different UI elements to different roles within the same swimlane
* Create more complex permission structures for sophisticated workflows
* Maintain security while enabling collaborative work on process instances

### Additional permissions

You can manually add additional permissions based on your specific requirements:

#### Core permissions

* **View**: View process instance data
* **Execute**: Start process instances and run actions
* **Self-assign**: Assign process instances to yourself

#### Task management permissions

These permissions are specifically for use with the [Task Management plugin](../../docs/platform-deep-dive/core-extensions/task-management/task-management-overview):

* **Assign**: Assign tasks to other users
* **Unassign**: Remove task assignments from other users
* **Hold**: Mark process instances as on hold
* **Unhold**: Remove hold status from process instances
* **Change Priority**: Modify task priority levels

![Process Permissions Configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/process_permissions.png)

> [!WARNING]
>
> **Version Compatibility**:
>
> * **2.11.0+**: Specific roles must be configured for each operation, otherwise restrictions will be applied
> * **\< 2.11.0**: If no role is configured, no restrictions are applied

## Access control with business filters

### What are business filters?

Business filters allow you to restrict process access based on dynamic business rules. For example, you might want only users from a specific bank branch to view process instances started from that branch.

### How business filters work

Business filters use attributes that are:

1. Configured in your identity management platform
2. Made available on the authorization token
3. Assigned to application users
4. Stored in process instance parameters

When a business filter is applied, only users with matching attributes can interact with the process instance.

### Configuring business filters

#### Step 1: Identity provider configuration

Configure business filter attributes in your identity provider as:

* A list of filters on the authorization token
* Attributes assigned to specific users

#### Step 2: Process definition setup

In your process definition, include nodes with actions that store the current business filter value to:

```
task.businessFilters
```

This value must be set in the process instance parameters.

#### Step 3: Runtime behavior

Once configured, only users with the correct business filter attribute can interact with process instances that have the filter applied.

> [card] [Business Filters Guide](../../docs/platform-deep-dive/user-roles-management/business-filters)
>
> Detailed guide on implementing business filters

## Configuration examples

### Standard user configuration

For regular users who need basic process interaction:

![Regular User Roles Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/regular_user_roles.png)

```yaml theme={"dark"}
Permissions:
  - execute: USER_ROLE
  - self-assign: USER_ROLE  
  - view: USER_ROLE
```

### Administrator configuration

For administrators who need full process management capabilities:

![Admin User Roles Example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/admin_user_roles.png)

```yaml theme={"dark"}
Permissions:
  - execute: ADMIN_ROLE
  - self-assign: ADMIN_ROLE
  - view: ADMIN_ROLE
  - assign: ADMIN_ROLE
  - unassign: ADMIN_ROLE
  - hold: ADMIN_ROLE
  - unhold: ADMIN_ROLE
  - change-priority: ADMIN_ROLE
```

### Team lead configuration

For team leads who can manage their team's tasks:

```yaml theme={"dark"}
Permissions:
  - execute: TEAM_LEAD_ROLE
  - self-assign: TEAM_LEAD_ROLE
  - view: TEAM_LEAD_ROLE
  - assign: TEAM_LEAD_ROLE
  - unassign: TEAM_LEAD_ROLE
```

## Platform configuration

### Engine configuration

Configure the FlowX Engine with the necessary environment variables for your identity provider:

#### Required variables

```bash theme={"dark"}
SECURITY_TYPE=jwt-public-key
SECURITY_OAUTH2_BASESERVERURL=https://your-keycloak-server.com
SECURITY_OAUTH2_SAREALM=00000002-0002-4002-8002-000000000002
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID=flowx-process-engine-sa
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET={your-sa-client-secret}
```

#### Optional variables

```bash theme={"dark"}
# Data anonymization for sensitive information
FLOWX_DATA_ANONYMIZATION=true
```

### REST API access control

To restrict API calls by user role, configure path authorizations:

```yaml theme={"dark"}
security:
  pathAuthorizations:
    - path: "/api/**"
      rolesAllowed: "ANY_AUTHENTICATED_USER"
    - path: "/api/admin/**"  
      rolesAllowed: "ADMIN_ROLE"
```

## Process instance management

### Viewing process instances

You can view active process instances and their data from FlowX Designer if you have the appropriate role (default: `FLOWX_ROLE`).

**Data Privacy**: Use the `FLOWX_DATA_ANONYMIZATION` environment variable to configure whether sensitive user data should be hidden in process views.

### Starting processes

The `FLOWX_ROLE` (or your configured default role) is required for users to start new process instances.

## Troubleshooting

### Common issues

**Users can't see processes**: Verify that the correct roles are assigned in your identity provider and that the service account is properly configured.

**Permission denied errors**: Check that the required permissions are configured for the specific operations and that users have the appropriate roles.

**Business filters not working**: Ensure that business filter attributes are properly configured in the identity provider and available on the authorization token.

### Version-specific considerations

> [!WARNING]
>
> **Platform Version \< 2.11.0**: If no role is configured on an operation, no restrictions will be applied. This behavior changed in version 2.11.0 where explicit role configuration became mandatory.

## Best practices

1. **Principle of Least Privilege**: Only grant the minimum permissions necessary for users to perform their tasks

2. **Role Hierarchy**: Design roles hierarchically (e.g., Admin > Team Lead > User) to simplify management

3. **Regular Audits**: Periodically review role assignments and permissions to ensure they remain appropriate

4. **Documentation**: Maintain clear documentation of what each role can do and who should have each role

5. **Testing**: Always test permission changes in a non-production environment first

6. **Business Filters**: Use business filters for dynamic, data-driven access control rather than static role-based restrictions

## Related topics

> [card] [Swimlanes](../../docs/platform-deep-dive/user-roles-management/swimlanes)
>
> Detailed swimlanes configuration guide

> [card] [Business filters](../../docs/platform-deep-dive/user-roles-management/business-filters)
>
> Advanced business rules for access control


# Configure Elasticsearch indexing for process instances
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing

Enable process instance indexing in Elasticsearch with Kafka or HTTP transport, set up the indexing topics and index, and fix common indexing issues.

> [!NOTE]
>
> **Scope.** This guide covers process-instance indexing only — the `process_instance-*` indices written by `process-engine`. Audit logs (`audit-logs` index, written directly by `audit-core` over HTTPS) and search workloads (`data-search`, read-only) do **not** flow through this pipeline.

## Before you start

* **Read the prerequisites**: Review the [Intro to Elasticsearch](../../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch) section first
* **Choose your strategy**: Decide between Kafka (recommended for production) or HTTP indexing based on your infrastructure
* **Check permissions**: Ensure you have access to modify process-engine configurations

## Quick decision: Kafka vs HTTP

| Strategy | Best for | Pros | Cons |
| - | - | - | - |
| **Kafka** (recommended) | Production environments with high throughput | Fire-and-forget communication, time-based partitioning, better performance, decoupled architecture | Requires Kafka Connect setup |
| **HTTP** | Development or simple setups | Direct connection, easier setup | Blocking operations, no time-based partitioning, tighter coupling |

> [!TIP]
>
> **Why Kafka is recommended**: The Kafka strategy allows for fire-and-forget communication, eliminating the need for the process engine to wait for indexing requests to complete. This significantly improves performance in high-throughput scenarios.

> [!NOTE]
>
> **Critical difference**: Only the Kafka strategy provides out-of-the-box support for time-based partitioning through the `transforms.routeTS.timestamp.format` configuration (see later in this guide). The HTTP strategy does not support time-based partitioning as a built-in feature.

***

## Configuration overview

All indexing is controlled by these core settings:

### Global indexing control

```bash theme={"dark"}
FLOWX_INDEXING_ENABLED=false  # Set only when you want to disable indexing
```

> [!NOTE]
>
> `FLOWX_INDEXING_ENABLED` defaults to true. Only set this variable if you want to disable indexing by setting it to false.

### Strategy selection

```bash theme={"dark"}
FLOWX_INDEXING_TYPE=kafka  # Options: kafka, http, no-indexing
```

### Performance considerations (FlowX defaults)

**Default configuration:**

* **Monthly indices**: `yyyyMM` format for time-based partitioning (Kafka only)
* **2 shards + 0 replicas** (code default): bump replicas based on your high-availability requirements
* **Primary shards per year**: 24 (2 primary × 12 monthly indices) — well under Elasticsearch's 1000 shard default limit; each replica adds another 24

**Scaling guidelines:**

* **If indexing becomes slow**: Check physical resources and shard size
* **If monthly indices become too large**: Switch to weekly indices (`yyyyww`)
* **For high parallel indexing load**: Add more primary shards
* **High availability**: Set `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` to at least `1` in production for resilience to a single node loss

> [!WARNING]
>
> **Important**: Each replica is applied per shard, so monitor resource usage when increasing replicas.

### HTTP-only setting

```bash theme={"dark"}
FLOWX_INDEXING_OPTIMISTICLOCKINGRETRIES=3  # Only used with HTTP strategy
```

***

## Setup: Kafka indexing (recommended)

### Step 1: Configure the process engine

Add these environment variables to your process-engine configuration:

```bash theme={"dark"}
# Elasticsearch connection settings
SPRING_ELASTICSEARCH_REST_PROTOCOL=https
SPRING_ELASTICSEARCH_REST_URIS=elasticsearch:9200
SPRING_ELASTICSEARCH_REST_DISABLESSL=false
SPRING_ELASTICSEARCH_REST_USERNAME=
SPRING_ELASTICSEARCH_REST_PASSWORD=

# Use Kafka strategy
FLOWX_INDEXING_TYPE=kafka

# Index settings (optional - these are the defaults)
FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME=process_instance
FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS=2
FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=0
```

> [!WARNING]
>
> **`process-engine` still needs HTTPS connectivity to Elasticsearch in Kafka mode.** Even with `FLOWX_INDEXING_TYPE=kafka`, `process-engine` creates the `process_instance_template` index template directly against Elasticsearch at startup. If `process-engine` cannot reach Elasticsearch, the template silently fails to apply and indices fall back to default mappings — search and aggregations break in non-obvious ways.

### Step 2: Deploy Kafka Connect

#### Compatibility matrix

| Component | Supported in 5.9.0 |
| - | - |
| Kafka cluster | 3.9 – 4.2 (set `KafkaConnect.spec.version` to match) |
| Elasticsearch Sink Connector plugin | 15+ |
| Elasticsearch (target cluster) | 8.x |
| Kafka Connect runtime | matches Kafka cluster version, run by the Strimzi operator |

> [!NOTE]
>
> Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version deployed. This guide uses the Confluent `kafka-connect-elasticsearch` plugin as the reference path.

**Prerequisites:**

* Kafka cluster (installed with Strimzi operator)
* Elasticsearch cluster (installed with eck-operator)
* Convert ES certificates to JKS format (see commands below)

**Certificate conversion commands:**

```bash theme={"dark"}
# 1. Extract the CA certificate
kubectl get secret elasticsearch-es-http-certs-public -n flowx \
  -o jsonpath='{.data.ca\.crt}' | base64 --decode > es-ca.crt

# 2. Create JKS keystore
keytool -importcert -alias elasticsearch -file es-ca.crt \
  -keystore keystore.jks -storepass flowx123456 -noprompt

# 3. Create Kubernetes secret
kubectl -n flowx create secret generic kafka-connect-elastic-jks --from-file=keystore.jks
```

**Deploy KafkaConnect:**

> [!WARNING]
>
> **FlowX does not publish a Kafka Connect image.** You build and host the container image yourself. Strimzi's `spec.build` block below downloads the connector plugin, bakes it into a new image, and pushes it to your registry. Use an immutable tag that ties the image to the plugin version so upgrades are auditable.

```yaml theme={"dark"}
apiVersion: kafka.strimzi.io/v1beta2
kind: KafkaConnect
metadata:
  name: flowx-elasticsearch-kafka-connect
  annotations:
    strimzi.io/use-connector-resources: "true"
spec:
  version: 3.9.0  # FlowX 5.9 supports Kafka 3.9 – 4.2; set this to your deployed cluster version
  replicas: 1
  bootstrapServers: flowx-kafka-bootstrap:9092

  # OAuth configuration (if using Keycloak)
  authentication:
    type: oauth
    clientId: flowx-service-client
    clientSecret:
      secretName: keycloak-kafka-cluster-client
      key: KEYCLOAK_KAFKA_CLUSTER_CLIENT_SECRET
    tokenEndpointUri: https://YOUR_KEYCLOAK_URL/auth/realms/YOUR_REALM/protocol/openid-connect/token
    tlsTrustedCertificates:
      - secretName: self-signed-certificate
        certificate: tls.crt
    disableTlsHostnameVerification: true

  config:
    group.id: flowx-kafka-connect-es-plugin
    offset.storage.topic: ai.flowx.kafka-connect-cluster-offsets
    config.storage.topic: ai.flowx.kafka-connect-cluster-configs
    status.storage.topic: ai.flowx.kafka-connect-cluster-status
    config.storage.replication.factor: -1
    offset.storage.replication.factor: -1
    status.storage.replication.factor: -1
    # Auto-creates Kafka Connect's internal bookkeeping topics (offsets / configs / status).
    # The SOURCE topic (ai.flowx.<env>.core.index.process.v1) is NOT covered here — you must
    # declare it via your Strimzi KafkaTopic resources before starting the connector.
    topic.creation.enable: true
    config.providers: env
    config.providers.env.class: org.apache.kafka.common.config.provider.EnvVarConfigProvider

  build:
    output:
      type: docker
      # YOU build and host this image. FlowX does not publish a Kafka Connect image.
      # Strimzi pulls the upstream Connect base, downloads the plugin below, bakes a new
      # container, and pushes it here. Tag it with the plugin version for traceability.
      image: <YOUR_REGISTRY>/<your-connect-image-name>:<your-tag>
      pushSecret: registry-credentials  # K8s secret of type kubernetes.io/dockerconfigjson
    plugins:
      - name: kafka-connect-elasticsearch
        artifacts:
          - type: zip
            url: https://hub-downloads.confluent.io/api/plugins/confluentinc/kafka-connect-elasticsearch/versions/15.1.2/confluentinc-kafka-connect-elasticsearch-15.1.2.zip
            # sha512sum: <recommended for supply-chain integrity — fill in the published checksum>

  template:
    pod:
      volumes:
        - name: elasticsearch-keystore
          secret:
            secretName: kafka-connect-elastic-jks
    connectContainer:
      env:
        - name: ELASTIC_PASSWORD
          valueFrom:
            secretKeyRef:
              name: elasticsearch-es-elastic-user
              key: elastic
      volumeMounts:
        - name: elasticsearch-keystore
          mountPath: /mnt/elasticsearch-keystore
          readOnly: true
```

### Step 3: Configure the Elasticsearch Sink Connector

> [!WARNING]
>
> **Indices are partitioned by process start month, not update month.** The `TimestampRouter` uses the Kafka record timestamp, which `process-engine` populates with the process instance's `dateStarted`. Late updates to old process instances land in the *original* start-month index, not the index for the current month. Plan archiving alignment accordingly, and use the body field `indexLastUpdatedTime` (not the index name) for "activity in last X days" queries.

> [!WARNING]
>
> **The source topic must be pre-declared.** `topic.creation.enable: true` on the `KafkaConnect` cluster only creates Kafka Connect's internal offsets/configs/status topics — it does **not** create the source topic the connector consumes. Add `ai.flowx.<env>.core.index.process.v1` to your Strimzi `KafkaTopic` resources before the connector starts.

**Key settings explained:**

* `transforms.routeTS.timestamp.format`: Controls index partitioning (monthly=`yyyyMM`, daily=`yyyyMMdd`)
* `transforms.routeTS.topic.format`: Must start with your configured index name
* `batch.size`: Adjust based on throughput needs (1000 is good default)

> [!WARNING]
>
> **Process instance data archiving integration**: If you're using FlowX's process instance data archiving feature, ensure your Elasticsearch partitioning configuration aligns with your database partitioning strategy. This is essential because:
>
> * When archiving process instances, data must be deleted from both the database and Elasticsearch
> * The partitioning intervals should be similar between database and Elasticsearch for consistent data lifecycle management
> * Elasticsearch indexing strategy must be enabled when partitioning is configured

```yaml theme={"dark"}
apiVersion: kafka.strimzi.io/v1beta2
kind: KafkaConnector
metadata:
  name: flowx-elasticsearch-sink-connector
  labels:
    strimzi.io/cluster: flowx-elasticsearch-kafka-connect
spec:
  class: io.confluent.connect.elasticsearch.ElasticsearchSinkConnector
  config:
    # Connection settings - UPDATE THESE
    connection.url: https://elasticsearch-es-http.flowx.svc:9200
    connection.username: elastic
    connection.password: ${env:ELASTIC_PASSWORD}
    
    # SSL settings
    elastic.security.protocol: SSL
    elastic.https.ssl.truststore.type: JKS
    elastic.https.ssl.truststore.location: /mnt/elasticsearch-keystore/keystore.jks
    elastic.https.ssl.truststore.password: "flowx123456"
    
    # Source topic - must match your Kafka topic naming
    topics: ai.flowx.core.index.process.v1
    
    # Time-based routing - IMPORTANT: Choose your partitioning strategy
    transforms: routeTS
    transforms.routeTS.type: org.apache.kafka.connect.transforms.TimestampRouter
    transforms.routeTS.timestamp.format: yyyyMM  # Monthly indices (change as needed)
    transforms.routeTS.topic.format: process_instance-${timestamp}  # Must start with your index name
    
    # Performance settings
    batch.size: 1000
    read.timeout.ms: 30000
    flush.synchronously: "true"
    
    # Data handling
    behavior.on.malformed.documents: IGNORE
    behavior.on.null.values: IGNORE
    drop.invalid.message: "true"
    schema.ignore: "true"
    write.method: UPSERT
    type.name: _doc
    
    # Converters
    key.converter: org.apache.kafka.connect.storage.StringConverter
    key.converter.schemas.enable: "false"
    value.converter: org.apache.kafka.connect.json.JsonConverter
    value.converter.schemas.enable: "false"
```

### Step 4: Verify the setup

**Check Kafka Connect status:**

```bash theme={"dark"}
kubectl get kafkaconnect flowx-elasticsearch-kafka-connect -o yaml
```

**Check connector status:**

```bash theme={"dark"}
kubectl get kafkaconnector flowx-elasticsearch-sink-connector -o yaml
```

**Verify indices are being created:**

```bash theme={"dark"}
# Port-forward to Elasticsearch
kubectl port-forward svc/elasticsearch-es-http 9200:9200

# Check indices (should see process_instance-YYYYMM pattern)
curl -k -u elastic:$ELASTIC_PASSWORD https://localhost:9200/_cat/indices?v
```

***

## Setup: HTTP indexing (simple)

### Configure the process engine

For HTTP indexing, update your process-engine configuration:

```bash theme={"dark"}
# Elasticsearch connection settings
SPRING_ELASTICSEARCH_REST_PROTOCOL=https
SPRING_ELASTICSEARCH_REST_URIS=elasticsearch:9200
SPRING_ELASTICSEARCH_REST_DISABLESSL=false
SPRING_ELASTICSEARCH_REST_USERNAME=
SPRING_ELASTICSEARCH_REST_PASSWORD=

# Use HTTP strategy
FLOWX_INDEXING_TYPE=http

# Index settings (optional - these are the defaults)
FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME=process_instance
FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS=2
FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=0

# HTTP-specific setting
FLOWX_INDEXING_OPTIMISTICLOCKINGRETRIES=3
```

***

## Kafka topics

The process engine publishes indexing records to a topic whose name is composed from the standard FlowX Kafka naming triple:

```
<package><environment>core.index.process<version>
```

Each segment is set independently via environment variables on the `process-engine` deployment:

| Environment Variable | Typical value | Notes |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | `ai.flowx.` | Vendor prefix. Same for all FlowX topics. |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | `dev.` or \`\` (empty) | Environment segment. Empty in production. |
| `KAFKA_TOPIC_NAMING_VERSION` | `.v1` | Schema version suffix. |

**Worked examples:**

| Environment | Composed source topic |
| - | - |
| Dev (`ENVIRONMENT=dev.`) | `ai.flowx.dev.core.index.process.v1` |
| Production (`ENVIRONMENT=` empty) | `ai.flowx.core.index.process.v1` |

**Important:** The `topics:` value in your `KafkaConnector` configuration must match the composed topic for your environment. You must also declare that topic explicitly via your Strimzi `KafkaTopic` resources — see the warning under Step 3.

***

## Index management

### Automatic template creation

The process engine automatically creates Elasticsearch index templates during startup:

* **HTTP strategy**: Creates the index directly with configured shards/replicas
* **Kafka strategy**: Creates an index template that applies to dynamically created indices

### Time-based partitioning (Kafka only)

Choose your partitioning strategy based on data volume and retention needs:

| Database Partitioning | Elasticsearch Format | Index Pattern | Best For |
| - | - | - | - |
| Monthly | `yyyyMM` | `process_instance-202406` | Medium volume |
| Weekly | `yyyyww` | `process_instance-202426` | High volume |
| Daily | `yyyyMMdd` | `process_instance-20240615` | Very high volume |

### Efficient data deletion

**Best practice:** Delete entire indices rather than individual documents for better performance.

With time-based partitioning, you can:

```bash theme={"dark"}
# Delete old monthly index
curl -X DELETE "https://localhost:9200/process_instance-202401"

# Delete multiple old indices
curl -X DELETE "https://localhost:9200/process_instance-2024*"
```

***

## Troubleshooting

### Common issues

**Indexing not working:**

1. Check if indexing is disabled (only if you explicitly set `FLOWX_INDEXING_ENABLED=false`)
2. Verify Elasticsearch connectivity
3. Check process-engine logs for errors

**Kafka Connect issues:**

```bash theme={"dark"}
# Check connect cluster status
kubectl describe kafkaconnect flowx-elasticsearch-kafka-connect

# Check connector logs
kubectl logs -l strimzi.io/kind=KafkaConnect -f
```

**Certificate issues:**

```bash theme={"dark"}
# Verify JKS keystore
keytool -list -keystore keystore.jks -storepass flowx123456

# Check secret exists
kubectl get secret kafka-connect-elastic-jks -o yaml
```

**Performance issues:**

* Increase `batch.size` in connector config
* Adjust number of shards based on cluster size
* Monitor Elasticsearch cluster health

### Verification queries

**Check index pattern:**

```bash theme={"dark"}
# List all process instance indices
curl -k -u elastic:$PASSWORD "https://localhost:9200/_cat/indices/process_instance*?v"

# Check template exists
curl -k -u elastic:$PASSWORD "https://localhost:9200/_template/process_instance*"
```

**Query across time-based indices:**

```bash theme={"dark"}
# Search across all process instance indices
curl -k -u elastic:$PASSWORD -X GET "https://localhost:9200/process_instance-*/_search" \
  -H "Content-Type: application/json" \
  -d '{"query": {"match_all": {}}}'
```


# Indexing config guidelines
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/process-instance-indexing-config-guidelines

Guidelines for sizing and configuring Elasticsearch for process instance indexing based on app load and indexed keys per process.

## Indexing strategy

* Advantages of Multiple Small Indices:
  * Fast indexing process.
  * Flexibility in cleaning up old data.
* Potential Drawbacks:
  * Hitting the maximum number of shards per node, resulting in exceptions when creating new indices.
  * Increased search response time and memory footprint.
* Deletion
  * When deleting data in Elasticsearch, it's recommended to delete entire indices instead of individual documents. Creating multiple smaller indices provides the flexibility to delete entire indices of old data that are no longer needed.

Alternatively, you can create fewer indices that span longer periods of time, such as one index per year. This approach offers small search response times but may result in longer indexing times and difficulty in cleaning up and recovering data in case of failure.

> [card] [What is indexing?](../../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch#indexing)

## Shard and replica configuration

The solution includes an index template that gets created with the settings from the process-engine app (name, shards, replicas) when running the app for the first time. This template controls the settings and mapping of all newly created indices.

> [card] [What is sharding?](../../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-elasticsearch#sharding)

> [card] [Index template](./elasticsearch-indexing#automatic-template-creation)

Once an index is created, you cannot update its number of shards and replicas. However, you can update the settings from the index template at runtime in Elasticsearch, and new indices will be created with the updated settings. Note that the mapping should not be altered as it is required by the application.

## Recommendations for resource management

To manage functional indexing operations and resources efficiently, consider the following recommendations:

* [Sizing indexes upon creation](#sizing-indexes-upon-creation)
* [Balancing](#balancing)
* [Delete unneeded indices](#delete-unneeded-indices)
* [Reindex large indices](#reindex-large-indices)
* [Force merge indices](#force-merge-indices)
* [Shrink indices](#shrink-indices)
* [Combine indices](#combine-indices)

#### Sizing indexes upon creation

Recommendations:

* Start with monthly indexes that have 2 shards and 1 replica. This setup is typically sufficient for handling up to 200k process instances per day; ensures a parallel indexing in two main shards and has also 1 replica per each main shard (4 shards in total). This would create 48 shards per year in the Elasticsearch nodes; A lot less than the default 1000 shards, so you will have enough space for other indexes as well.
  * If you observe that the indexing gets really, really slow, then you should look at the physical resources / shard size and start adapting the config.
  * If you observe that indexing one monthly index gets massive and affects the performance, then think about switching to weekly indices.
  * If you have huge spikes of parallel indexing load (even though that depends on the Kafka connect cluster configuration), then think about adding more main shards.
* Consider having at least one replica for high availability. However, keep in mind that the number of replicas is applied to each shard, so creating many replicas may lead to increased resource usage.
* Monitor the number of shards created and estimate when you might reach the maximum shards per node, taking into account the number of nodes in your cluster.

#### Balancing

When configuring index settings, consider the number of nodes in your cluster. The total number of shards (calculated by the formula: primary\_shards\_number \* (replicas\_number +1)) for an index should be directly proportional to the number of nodes. This helps Elasticsearch distribute the load evenly across nodes and avoid overloading a single node. Avoid adding shards and replicas unnecessarily.

#### Delete unneeded indices

Deleting unnecessary indices reduces memory footprint, the number of used shards, and search time.

#### Reindex large indices

If you have large indices, consider reindexing them. Process instance indexing involves multiple updates on an initially indexed process instance, resulting in multiple versions of the same document in the index. Reindexing creates a new index with only the latest version, reducing storage size, memory footprint, and search response time.

#### Force merge indices

If there are indices with no write operations performed anymore, perform force merge to reduce the number of segments in the index. This operation reduces memory footprint and response time. Only perform force merge during off-peak hours when the index is no longer used for writing.

#### Shrink indices

If you have indices with many shards, consider shrinking them using the shrink operation. This reindexes the data into an index with fewer shards. Perform this operation during off-peak hours.

#### Combine indices

If there are indices with no write operations performed anymore (e.g., process\_instance indices older than 6 months), combine these indices into a larger one and delete the smaller ones. Use the reindexing operation during off-peak hours. Ensure that write operations are no longer needed from the FLOWX platform for these indices.


# FlowX Engine setup
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/engine-setup

This guide provides instructions on how to set up and configure the FlowX.AI Engine.

## Infrastructure prerequisites

Before installing the FlowX.AI Engine, verify that the following infrastructure components are installed and configured:

* **Kafka**
* **Elasticsearch**
* **PostgreSQL** or **Oracle**
* **MongoDB**

***

## Dependencies

The FlowX Engine requires the following components:

* **Database**: Primary storage for the engine (PostgreSQL or Oracle)
* **Redis Server**: Used for caching. See [Redis Configuration](../redis-configuration)
* **Kafka**: Handles messaging and event-driven architecture. See [Configuring Kafka](#configuring-kafka)

For a microservices architecture, services typically manage their data via dedicated databases.

### Required external services

* **Redis Cluster**: Caches process definitions, compiled scripts, and Kafka responses
* **Kafka Cluster**: Enables communication with external plugins and integrations

***

## Configuration setup

FlowX.AI Engine uses environment variables for configuration. This section covers key configuration areas:

* [Database configuration](#database-configuration)
* [Authorization & access roles](#authorization-&-access-roles)
* [Kafka configuration](#configuring-kafka)
* [File upload size](#configuring-file-upload-size)
* [Elasticsearch connection](#configuring-elasticsearch-connection)

### Database configuration

The FlowX Engine supports both PostgreSQL and Oracle as its primary relational database.

#### PostgreSQL

| Environment variable | Description |
| - | - |
| `SPRING_DATASOURCE_URL` | Database URL for PostgreSQL |
| `SPRING_DATASOURCE_USERNAME` | Username for PostgreSQL |
| `SPRING_DATASOURCE_PASSWORD` | Password for PostgreSQL |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | Driver class for PostgreSQL |

#### Oracle

| Environment variable | Description |
| - | - |
| `SPRING_DATASOURCE_URL` | Database URL for Oracle |
| `SPRING_DATASOURCE_USERNAME` | Username for Oracle |
| `SPRING_DATASOURCE_PASSWORD` | Password for Oracle |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | Driver class for Oracle |

**Default:** `oracle.jdbc.OracleDriver`

#### MongoDB configuration

Configure connection to the Runtime MongoDB instance:

| Environment variable | Description | Default value |
| - | - | - |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | URI for connecting to Runtime MongoDB. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path. | Format: `mongodb://${DB_USERNAME}:${DB_PASSWORD}@<host1>,<host2>,<arbiter-host>:<port>/app-runtime?retryWrites=false` |

### Configuration parameters

There are two types of Config Params that can be read from the environment: **variables** and **secrets**. There is one provider for variables and secrets extracted from the environment variables, and two providers for the ones extracted from Kubernetes. By default, the variables and secrets are extracted from environment variables (`env` provider).

#### Configuration parameters from environment variables (default)

The `env` provider used for variables and secrets extracts them from environment variables. For security reasons, the `env` provider uses an allow list regex which defaults to `FLOWX_CONFIGPARAM_.*`. This means only environment variables that match this naming pattern can be read at runtime into configuration params (either as variables or secrets). Feel free to edit it to match the environment variables that you use in your deployment.

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER` | Provider type for variables | `env` |
| `FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX` | Regular expression to match allowed env variables for variables | `FLOWX_CONFIGPARAM_.*` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | Provider type for secrets | `env` |
| `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX` | Regular expression to match allowed env variables for secrets | `FLOWX_CONFIGPARAM_.*` |

#### Configuration parameters from Kubernetes Secrets and ConfigMaps

Use the following configuration to read Config Params from Kubernetes Secrets and ConfigMaps:

| Environment variable | Description | Values |
| - | - | - |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER` | Provider type for variables | `k8s-configmaps` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | Provider type for secrets | `k8s-secrets` |

These providers can be configured as follows:

| Environment variable | Description | Values |
| - | - | - |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_0_` | Name of the ConfigMap to use for variables | `flowx-configparams` |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_0_` | Name of the Secret to use for secrets | `flowx-configparams` |

> [!NOTE]
>
> You can configure multiple secrets and ConfigMaps by incrementing the index number (e.g., `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_1`, `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_1`). Values are overridden based on the order in which the maps are defined.
>
> The default provider is `env`, but there is a built-in allowlist with the regex pattern `FLOWX_CONFIGPARAM_.*`. This means only configuration parameters that match this naming pattern can be read at runtime, whether they are environment variables or secret variables.

#### Config params cache

Configure caching behavior for configuration parameters to optimize performance:

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120` |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache | `500` |

> [!NOTE]
>
> These settings control how long configuration parameters are cached in memory before being refreshed from the source (environment variables, ConfigMaps, or Secrets). Adjust these values based on how frequently your configuration changes and your memory constraints.

### Authorization & access roles

This section covers OAuth2 configuration settings for securing the Spring application.

#### Security configuration

| Environment variable | Description | Default value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_BASIC_ENABLED` | Enable basic authentication | `false` |
| `SECURITY_PUBLICPATHS_0` | Public path not requiring authentication | `/api/platform/components-versions` |
| `SECURITY_PUBLICPATHS_1` | Public path not requiring authentication | `/manage/actuator/health` |
| `SECURITY_PATHAUTHORIZATIONS_0_PATH` | Security path pattern | `"/api/**"` |
| `SECURITY_PATHAUTHORIZATIONS_0_ROLESALLOWED` | Roles allowed for path access | `"ANY_AUTHENTICATED_USER"` |

#### Service-to-service authentication

The engine validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment variable | Description | Default value |
| - | - | - |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-process-engine-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

> [!NOTE]
>
> When deploying with the FlowX Helm chart, `SECURITY_OAUTH2_BASESERVERURL` is supplied through the chart value `flowx.keycloak.baseServerUrl` and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.

For more information about the necessary service account, see [Process Engine Service Account](../access-management/configuring-an-iam-solution#process-engine-service-account).

### Configuring Kafka

Kafka handles all communication between the FlowX.AI Engine, external plugins, and integrations. It also notifies running process instances when certain events occur.

#### Kafka connection settings

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka bootstrap servers (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT` |

#### Message routing configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

> [!NOTE]
>
> When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.

#### Kafka consumer retry settings

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Interval between retries after `AuthorizationException` (seconds) | `10` |

#### Consumer groups & consumer threads configuration

Both a producer and a consumer must be configured:

> [card] [Configuring a Kafka Producer](../../docs/platform-deep-dive/integrations/creating-a-kafka-producer)

> [card] [Configuring a Kafka Consumer](../../docs/platform-deep-dive/integrations/creating-a-kafka-consumer)

![FlowX Engine Kafka communication pattern](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/engine_kafka_pattern.svg)

##### About consumer groups and threads

A consumer group is a set of consumers that jointly consume messages from one or more Kafka topics. Each consumer group has a unique identifier (group ID) that Kafka uses to manage message distribution.

Thread numbers refer to the number of threads a consumer application uses to process messages. Increasing thread count can improve parallelism and efficiency, especially with high message volumes.

##### Consumer group configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_CONSUMER_GROUPID_NOTIFYADVANCE` | Group ID for notifying advance actions | `advance` |
| `KAFKA_CONSUMER_GROUPID_NOTIFYPARENT` | Group ID for notifying when a subprocess is blocked | `notify-parent` |
| `KAFKA_CONSUMER_GROUPID_ADAPTERS` | Group ID for messages related to adapters | `adapters` |
| `KAFKA_CONSUMER_GROUPID_SCHEDULERRUNACTION` | Group ID for running scheduled actions | `scheduler-run-action` |
| `KAFKA_CONSUMER_GROUPID_SCHEDULERADVANCING` | Group ID for messages indicating continuing advancement | `scheduler-advancing` |
| `KAFKA_CONSUMER_GROUPID_MESSAGEEVENTS` | Group ID for message events | `message-events` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_START` | Group ID for starting processes | `process-start` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_STARTFOREVENT` | Group ID for starting processes for an event | `process-start-for-event` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_EXPIRE` | Group ID for expiring processes | `process-expire` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_OPERATIONS` | Group ID for processing operations from Task Management plugin | `process-operations` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_BATCHPROCESSING` | Group ID for processing bulk operations from Task Management plugin | `process-batch-processing` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Group ID for processing UI flow session variable updates | `ui-flow-update` |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE` | Group ID for processing UI flow session expiry triggers | `ui-flow-expire` |
| `KAFKA_CONSUMER_GROUPID_CONFIGPARAMS` | Group ID for runtime config-param change events | `config-params` |

##### Consumer thread configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_CONSUMER_THREADS_NOTIFYADVANCE` | Number of threads for notifying advance actions | `6` |
| `KAFKA_CONSUMER_THREADS_NOTIFYPARENT` | Number of threads for notifying when a subprocess is blocked | `6` |
| `KAFKA_CONSUMER_THREADS_ADAPTERS` | Number of threads for processing messages related to adapters | `6` |
| `KAFKA_CONSUMER_THREADS_SCHEDULERADVANCING` | Number of threads for continuing advancement | `6` |
| `KAFKA_CONSUMER_THREADS_SCHEDULERRUNACTION` | Number of threads for running scheduled actions | `6` |
| `KAFKA_CONSUMER_THREADS_MESSAGEEVENTS` | Number of threads for message events | `6` |
| `KAFKA_CONSUMER_THREADS_PROCESS_START` | Number of threads for starting processes | `6` |
| `KAFKA_CONSUMER_THREADS_PROCESS_STARTFOREVENT` | Number of threads for starting processes for an event | `2` |
| `KAFKA_CONSUMER_THREADS_PROCESS_EXPIRE` | Number of threads for expiring processes | `6` |
| `KAFKA_CONSUMER_THREADS_PROCESS_OPERATIONS` | Number of threads for processing operations from task management | `6` |
| `KAFKA_CONSUMER_THREADS_PROCESS_BATCHPROCESSING` | Number of threads for processing bulk operations from task management | `6` |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of threads for processing UI flow session variable updates | `6` |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWEXPIRE` | Number of threads for processing UI flow session expiry triggers | `6` |

All events that start with a configured pattern will be consumed by the Engine. This enables you to create new integrations and connect them to the engine without changing the configuration.

#### Configuring Kafka topics

##### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern | `engine.receive.` |
| `KAFKA_TOPIC_NAMING_INTEGRATIONRECEIVEPATTERN` | Integration receive pattern | `integration.receive.` |

##### Core engine topics

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_NOTIFY_ADVANCE` | Topic used internally for advancing processes | `ai.flowx.core.notify.advance.process.v1` |
| `KAFKA_TOPIC_PROCESS_NOTIFY_PARENT` | Topic used for sub-processes to notify the parent process | `ai.flowx.core.notify.parent.process.v1` |
| `KAFKA_TOPIC_PATTERN` | Pattern the Engine listens on for incoming events | `ai.flowx.engine.receive.*` |
| `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` | Topic for process message events | `ai.flowx.core.message.event.process.v1` |

##### Topics related to the Task Management plugin

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_TASK_OUT` | Topic used for sending notifications to the plugin | `ai.flowx.plugin.tasks.trigger.save.task.v1` |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_IN` | Topic for receiving information about operations performed | `ai.flowx.core.trigger.operation.v1` |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_BULKIN` | Topic where operations can be performed in bulk | `ai.flowx.core.trigger.operations.bulk.v1` |

##### Topics related to the Notification plugin

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_NOTIFICATION_OUT` | Topic for sending notification requests to the Notification plugin | `ai.flowx.plugin.notification.trigger.send.notification.v1` |

> [!NOTE]
>
> The `KAFKA_TOPIC_NOTIFICATION_OUT` topic must resolve to the same value as `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` in the Notification plugin configuration.

##### Topics related to the Document plugin

The process-engine receives results from document-plugin operations on topics matching the pattern `ai.flowx.engine.receive.plugin.document.*`. The following topics are used for file encryption and decryption operations:

| Topic name | Description |
| - | - |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Topic for receiving file encryption results from document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Topic for receiving file decryption results from document-plugin |

> [!NOTE]
>
> These topics are automatically matched by the Engine's `KAFKA_TOPIC_PATTERN` configuration (default: `ai.flowx.engine.receive.*`). No additional configuration is required. The topics must be created in your Kafka infrastructure before deployment.

The process-engine also **produces** trigger topics consumed by document-plugin to persist files uploaded from UI Flows:

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_SESSION_UPLOAD_OUT` | Topic for persisting a single UI Flow upload session | `ai.flowx.plugin.document.trigger.persist.document.session.v1` |
| `KAFKA_TOPIC_SESSION_UPLOAD_BULK_OUT` | Topic for persisting a batch of UI Flow files in a single multi-file upload | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` |

###### OPERATIONS\_IN request example

```json theme={"dark"}
{
  "operationType": "UNASSIGN", //type of operation performed in Task Management plugin
  "taskId": "some task id",
  "processInstanceUuid": "1cff0b7d-966b-4b35-9e9b-63b1d6757ec6",
  "swimlaneName": "Default",
  "swimlaneId": "51ec1241-fe06-4576-9c84-31598c05c527",
  "owner": {
    "firstName": null,
    "lastName": null,
    "username": "service-account-flowx-process-engine-account",
    "enabled": false
  },
  "author": "admin@flowx.ai"
}
```

###### BULK\_IN request example

```json theme={"dark"}
{
  "operations": [
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223", // the id of the process instance
      "swimlaneName": "Default", //name of the swimlane
      "owner": null,
      "author": "john.doe@flowx.ai"
    },
    {
      "operationType": "HOLD",
      "taskId": "some task id",
      "processInstanceUuid": "d3aabfd8-d041-4c62-892f-22d17923b223",
      "swimlaneName": "Default", //name of the swimlane
      "owner": null,
      "author": "john.doe@flowx.ai"
    }
  ]
}      
```

> [!NOTE]
>
> To send additional keys in the response, attach them in the header. For example, you can use a `requestID` key.

> [!TIP]
>
> A response should be sent on a `callbackTopic` if it is mentioned in the headers:
>
> ![Callback topic with requestID header example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/bulk_requestid.png)
>
> ```json theme={"dark"}
> {"processInstanceId": ${processInstanceId}, "callbackTopic": "test.operations.out", "requestID":"1234567890"}
> ```

> [!NOTE]
>
> Process operations on this topic include: assignment, unassignment, hold, unhold, terminate. The Task Manager produces the assignment and hold operations on its `...operations.out` topic; terminate is available only to direct Kafka producers. For more information, see the Task Management plugin documentation:
>
> 📄 [**Task management plugin**](../../docs/platform-deep-dive/core-extensions/task-management/task-management-overview)

##### Topics related to UI flow session updates

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` |
| `KAFKA_TOPIC_UIFLOW_EXPIRE_IN` | Topic for receiving UI flow session expiry triggers, published by scheduler-core when a session's expiry time is reached | `ai.flowx.core.trigger.expire.ui-flow.v1` |

##### Topics related to runtime config params

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1**

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | Topic for receiving runtime config-param change events from Application Manager, used to invalidate the build cache | `ai.flowx.config.params.events.v1` |

When a runtime config param is created, updated, or deleted, Application Manager publishes a change event to this topic. The Engine consumes it and clears the cached build configuration for the affected `workspaceId` and `appVersionId`, then broadcasts the invalidation to its other replicas through a Redis pub/sub channel:

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_CONFIGPARAMS_EVENTS_REDISCHANNEL` | Redis pub/sub channel used to propagate config-param cache invalidation across Engine replicas | `config-params-redis-channel` |

##### Topics related to resource cache eviction

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1**

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_RESOURCE_CACHEEVICT_IN` | Topic for resource cache-eviction triggers, published by Admin when a process version changes so the Engine clears its cached resources | `ai.flowx.core.trigger.resource.cache-evict.v1` |

##### Topics related to runtime instance termination

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1**

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_OUT` | Topic on which the Engine notifies that a runtime instance has been terminated; consumed by Integration Designer | `ai.flowx.core.notify.terminated.runtime-instance.v1` |

##### Topics related to the scheduler extension

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_EXPIRE_IN` | Topic for requests to expire processes | `ai.flowx.core.trigger.expire.process.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_SET` | Topic used for scheduling process expiration | `ai.flowx.core.trigger.set.schedule.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_STOP` | Topic used for stopping process expiration | `ai.flowx.core.trigger.stop.schedule.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_IN_RUN_ACTION` | Topic for requests to run scheduled actions | `ai.flowx.core.trigger.run.action.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_IN_ADVANCE` | Topic for events related to advancing through a database | `ai.flowx.core.trigger.advance.process.v1` |

##### Topics related to Timer Events

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET` | Used to communicate with Scheduler microservice | `ai.flowx.core.trigger.set.timer-event-schedule.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP` | Used to communicate with Scheduler microservice | `ai.flowx.core.trigger.stop.timer-event-schedule.v1` |

##### Topics related to the Search Data service

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_DATA_SEARCH_IN` | Topic that the Engine listens on for search requests | `ai.flowx.core.trigger.search.data.v1` |
| `KAFKA_TOPIC_DATA_SEARCH_OUT` | Topic used by the Engine to reply after finding a process | `ai.flowx.engine.receive.core.search.data.results.v1` |

##### Topics related to the Audit service

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

##### Topics related to Elasticsearch indexing

| Environment variable | Default value |
| - | - |
| `KAFKA_TOPIC_PROCESS_INDEX_OUT` | `ai.flowx.core.index.process.v1` |

##### Processes that can be started by sending messages to a Kafka topic

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_START_IN` | Topic for requests to start a new process instance | `ai.flowx.core.trigger.start.process.v1` |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Topic for sending the reply after starting a new process instance | `ai.flowx.core.confirm.start.process.v1` |

##### Topics related to Message Events

| Environment variable | Default value |
| - | - |
| `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN` | `ai.flowx.core.trigger.start-for-event.process.v1` |
| | |

##### Topics related to Events-gateway microservice

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Outgoing messages from process-engine to events-gateway | `ai.flowx.eventsgateway.engine.commands.message.v1` |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_DISCONNECT` | Disconnect commands from process-engine to events-gateway | `ai.flowx.eventsgateway.engine.commands.disconnect.v1` |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_CONNECT` | Connect commands from process-engine to events-gateway | `ai.flowx.eventsgateway.engine.commands.connect.v1` |

##### Topics related to platform components

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_PLATFORM_COMPONENTSVERSIONS_OUT` | Topic for platform version caching | `ai.flowx.core.trigger.platform.versions.caching.v1` |

##### Inter-service topic coordination

When configuring FlowX services, ensure the following:

1. The Engine's `pattern` must match the pattern used by services sending messages to the Engine
2. The `integrationPattern` must match the pattern used by the Integration Designer
3. Output topics from one service must match the expected input topics of another service

For example:

* Services send to topics matching `ai.flowx.engine.receive.*` → Engine listens
* Engine sends to topics matching `ai.flowx.integration.receive.*` → Integration Designer listens

##### Kafka message size configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size in bytes | `52428800` (50MB) |

This setting affects:

* Producer message max bytes
* Producer max request size
* Consumer max partition fetch bytes

##### Kafka authentication (when using SASL\_PLAINTEXT)

For secure environments, enable OAuth authentication with the following environment variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

### Configuring Elasticsearch connection

The Process Engine uses Elasticsearch for process instance indexing and search capabilities. Configure the connection using these environment variables:

| Variable | Description | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_REST_PROTOCOL` | Connection protocol | `https` |
| `SPRING_ELASTICSEARCH_REST_URIS` | URL(s) of Elasticsearch nodes (no protocol) | - |
| `SPRING_ELASTICSEARCH_REST_DISABLESSL` | Disable SSL verification | `false` |
| `SPRING_ELASTICSEARCH_REST_USERNAME` | Authentication username | - |
| `SPRING_ELASTICSEARCH_REST_PASSWORD` | Authentication password | - |

> [!NOTE]
>
> For indexing setup, check the [Configuring Elasticsearch indexing](./configuring-elasticsearch-indexing/elasticsearch-indexing) section.

#### Indexing settings

| Variable | Description | Default Value |
| - | - | - |
| `FLOWX_INDEXING_ENABLED` | Enable/disable indexing globally | `true` |
| `FLOWX_INDEXING_TYPE` | Indexing strategy (http, kafka, no-indexing) | `http` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | Name of the Elasticsearch index | `process_instance` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | Number of primary shards | `2` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | Number of replica shards | `0` |
| `FLOWX_INDEXING_OPTIMISTICLOCKINGRETRIES` | Retry attempts for optimistic locking (HTTP only) | `3` |

### Configuring file upload size

| Environment variable | Description | Default value |
| - | - | - |
| `SPRING_SERVLET_MULTIPART_MAXFILESIZE` | Maximum file size allowed for uploads | `50MB` |
| `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE` | Maximum request size allowed for uploads | `50MB` |

#### Connecting the Advancing controller

To use the advancing controller, configure the following variables:

| Environment variable | Description | Default value |
| - | - | - |
| `ADVANCING_DATASOURCE_URL` | Connection URL for Advancing Postgres DB | `jdbc:postgresql://postgresql:5432/advancing` |
| `ADVANCING_DATASOURCE_USERNAME` | Username for Advancing DB connection | `flowx` |
| `ADVANCING_DATASOURCE_PASSWORD` | Password for Advancing DB connection | `-` |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | Maximum size of the advancing datasource connection pool. Worker threads open their own connections, configured separately via `ADVANCING_PICKINGTHREADS` and `ADVANCING_PROCESSINGTHREADS` | `20` |

#### Configuring the Advancing controller

| Environment variable | Description | Default value |
| - | - | - |
| `ADVANCING_TYPE` | Type of advancing mechanism | `PARALLEL` (alternatives: `KAFKA`, `PARALLEL`) |
| `ADVANCING_PICKINGTHREADS` | Number of worker threads for reading from database (picking operations) | `1` |
| `ADVANCING_PROCESSINGTHREADS` | Number of threads for parallel processing of advancing events | `20` |
| `ADVANCING_PROCESSINGBUFFERSIZE` | Maximum buffer size for processing queue. Controls how many events can be queued | `20` |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | Block picking operations when no worker threads are available | `true` |
| `ADVANCING_PICKINGPAUSEMILLIS` | Pause duration between picking batches (ms) | `50` |
| `ADVANCING_COOLDOWNAFTERSECONDS` | Cooldown period after processing a batch (seconds) | `120` |
| `ADVANCING_SCHEDULER_HEARTBEAT_CRONEXPRESSION` | Cron expression for the heartbeat | `"*/2 * * * * ?"` |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space (even just 1 position), that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.

> [card] [Advancing controller setup](../advancing-controller-setup-guide)

### CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - |

### Configuring cleanup mechanism

| Environment variable | Description | Default value |
| - | - | - |
| `SCHEDULER_THREADS` | Number of threads for the scheduler | `10` |
| `SCHEDULER_PROCESSCLEANUP_ENABLED` | Activates the cron job for process cleanup | `false` |
| `SCHEDULER_PROCESSCLEANUP_CRONEXPRESSION` | Cron expression for the process cleanup scheduler | `0 */5 0-5 * * ?` (every 5 minutes between 12 AM and 5 AM) |
| `SCHEDULER_PROCESSCLEANUP_BATCHSIZE` | Number of processes to clean up in one batch | `1000` |

### Managing subprocesses expiration

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_PROCESS_EXPIRESUBPROCESSES` | When true, terminates all subprocesses upon parent process expiration. When false, subprocesses follow their individual expiration settings | `true` |

### Configuring application management

| Environment variable | Description | Default value |
| - | - | - |
| `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` | Enables Prometheus metrics export | `false` |

> [!NOTE]
>
> `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED`, the variable used before 4.1, is still read: `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` takes its default from it. Use `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` in new configurations.

***

## RBAC configuration

Process Engine requires specific RBAC permissions for proper access to Kubernetes resources:

```yaml theme={"dark"}
rbac:
  create: true
  rules:
    - apiGroups:
        - ""
      resources:
        - secrets
        - configmaps
        - pods
      verbs:
        - get
        - list
        - watch
```

***

## Ingress and CORS

The Process Engine is exposed on both the admin and public hosts, with a dedicated route for runtime process instances on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives | Notes |
| - | - | - | - |
| admin | `/onboarding/api` | `/api/...` | Strip `/onboarding` |
| public | `/onboarding/api` | `/api/...` | Strip `/onboarding` |
| admin-instances | `/api/instances` | `/api/instances/...` | Path preserved |

Paths are set through `services.process-engine.ingress.<key>.path` (or `gateway.<key>.paths`) in the chart values. The admin and public routes share the same backend route family — the `/onboarding` prefix is stripped before forwarding so the backend receives `/api/...`.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Process Engine. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](../ingress-configuration).

> [!NOTE]
>
> For SSE (Server-Sent Events) communication configuration, refer to the [Events Gateway setup](../events-gateway-setup) guide.

***

### Script engine configuration

The process engine uses a native script engine for executing JavaScript and Python business rules. The native engine runs scripts in separate Node.js and Python worker processes.

| Environment variable | Description | Default value |
| - | - | - |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Number of Node.js worker processes | `16` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary used for the JS worker pool | `/usr/bin/node` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | Execution timeout per script (ms) | `5000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a worker is recycled | `10000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max input payload size (bytes) | `1048576` (1 MB) |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Number of Python worker processes | `8` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary used for the Python worker pool | `/usr/bin/python3` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Execution timeout per script (ms) | `10000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a worker is recycled | `10000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max input payload size (bytes) | `1048576` (1 MB) |

> [!NOTE]
>
> The `native` script engine is the default starting with 5.9.0, replacing the previous GraalVM-based engine. Scripts run in isolated subprocess pools. Starting with 5.9.1, the engine has no service-level provider switch — keeping a business rule on GraalVM is selected **per rule** in its script editor. See [Script engine per rule](/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule).

> [!TIP]
>
> If a script fails with a payload-too-large error, or a run reports a worker as not healthy, the input passed to the script likely exceeds its worker pool's payload limit. Raise `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` or `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` for the affected language. The JavaScript and Python limits are independent — keep them aligned when scripts in both languages handle the same data.

### Stuck token recovery

Automatically recovers process tokens that get stuck due to transient failures.

| Environment variable | Description | Default value |
| - | - | - |
| `SCHEDULER_STUCKTOKENRECOVERY_ENABLED` | Turn on or off stuck token recovery | `false` |
| `SCHEDULER_STUCKTOKENRECOVERY_CRONEXPRESSION` | Cron expression for recovery sweeps | `0 */5 * * * ?` |
| `SCHEDULER_STUCKTOKENRECOVERY_THRESHOLDMINUTES` | Minutes a token must be stuck before recovery triggers | `10` |
| `SCHEDULER_STUCKTOKENRECOVERY_BATCHSIZE` | Max tokens recovered per sweep | `100` |
| `SCHEDULER_STUCKTOKENRECOVERY_MAXAGEHOURS` | Max age (hours) of stuck tokens to consider | `4` |

***

## Troubleshooting

### Common issues

> [accordion] Engine fails to start
>
> **Symptoms:** The process-engine pod crashes or restarts repeatedly during startup.
>
> **Solutions:**
>
> 1. Verify PostgreSQL connectivity and that the database exists and is accessible
> 2. Check Redis connection settings (`SPRING_REDIS_HOST`, `SPRING_REDIS_PORT`) and ensure Redis is running
> 3. Confirm Kafka bootstrap servers are reachable (`SPRING_KAFKA_BOOTSTRAPSERVERS`)
> 4. Review pod logs for specific connection errors — the first failing dependency is usually the root cause
> 5. Ensure all required secrets (database passwords, OAuth credentials) are correctly mounted

> [accordion] Process instances not advancing
>
> **Symptoms:** Processes get stuck at certain nodes and do not move forward.
>
> **Solutions:**
>
> 1. Verify the advancing controller is running and properly connected (`ADVANCING_DATASOURCE_JDBCURL`)
> 2. Check that advancing-related Kafka topics exist and are correctly configured (`KAFKA_TOPIC_PROCESS_NOTIFY_ADVANCE`)
> 3. Review the advancing controller type (`ADVANCING_TYPE`) and thread configuration
> 4. Ensure the scheduler extension topics are properly set up for timer-based advances
> 5. Check Kafka consumer group lag for `advance` and `scheduler-advancing` groups

> [accordion] Elasticsearch indexing not working
>
> **Symptoms:** Process instances are not appearing in search results or the indexing service reports errors.
>
> **Solutions:**
>
> 1. Confirm `FLOWX_INDEXING_ENABLED` is set to `true`
> 2. Verify Elasticsearch connection settings (`SPRING_ELASTICSEARCH_REST_URIS`, credentials)
> 3. Check that the indexing type matches your setup (`FLOWX_INDEXING_TYPE`: `kafka` or `http`)
> 4. If using Kafka indexing, ensure the `KAFKA_TOPIC_PROCESS_INDEX_OUT` topic exists
> 5. Verify the Elasticsearch index name and shard configuration are valid

> [accordion] High memory usage
>
> **Symptoms:** The process-engine pod experiences OOM kills or high memory consumption.
>
> **Solutions:**
>
> 1. Review Redis caching configuration — large process definitions and compiled scripts are cached in Redis
> 2. Check `ADVANCING_PROCESSINGBUFFERSIZE` and `ADVANCING_PROCESSINGTHREADS` — high values increase memory usage
> 3. Ensure the cleanup mechanism is enabled (`SCHEDULER_PROCESSCLEANUP_ENABLED`) to remove completed process instances
> 4. Review Kafka consumer thread counts — each thread consumes memory for message buffering
> 5. Monitor the config params cache settings (`FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`) and reduce if needed

***

## Related resources

> [card] [Redis Configuration](../redis-configuration)
>
> Cache and session configuration including Sentinel and Cluster modes

> [card] [Elasticsearch Indexing](./configuring-elasticsearch-indexing/elasticsearch-indexing)
>
> Configure process instance indexing and search capabilities

> [card] [Process Instance Archiving](./process-instance-data-archiving)
>
> Archive and manage historical process instance data

> [card] [Access Roles for Processes](./configuring-access-roles-for-processes)
>
> Configure role-based access control for process definitions


# Partitioning & archiving
Source: https://docs.flowx.ai/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving

Improving data management using data partitioning and the archival processes.

## Overview

> [!TIP]
>
> This page covers partitioning and archiving for the **FlowX.AI Engine**, which partitions **process instances** in Oracle or PostgreSQL. Integration Designer partitions **workflow instances** separately, in MongoDB, and is configured on its own. See [Integration Designer setup, Workflow partitioning](../integration-designer-setup#workflow-partitioning-configuration).

Partitioning and archiving are data management strategies used to handle large volumes of data efficiently. They improve database performance, manageability, and storage optimization. By dividing data into partitions and archiving older or less frequently accessed data, organizations can ensure better data management, quicker query responses, and optimized storage use.

## Partitioning

Partitioning is the process of dividing a large database table into smaller, more manageable pieces, called partitions. Each partition can be managed and queried independently. The primary goal is to improve performance, enhance manageability, and simplify maintenance tasks such as backups and archiving.

Partitions can be created per day, week or month. This means that a partition ID is computed at insert time for each row of process\_instance and related tables.

Afterwards, a retention period can be setup (eg: 3 partitions). A flowx engine-driven cron job (with configurable start interval) will check if there is any partition which needs to be archived and will perform the necessary actions.

### Benefits of partitioning

* **Improved Query Performance**: By scanning only relevant partitions instead of the entire table.
* **Simplified Maintenance**: Easier to perform maintenance tasks like backups and index maintenance.
* **Data Management**: Better data organization and management by dividing data based on specific criteria such as date, range, or list.

> [!NOTE]
>
> Database Compatibility: Oracle Database and PostgreSQL.

## Archiving

Archiving involves moving old data from the primary tables to separate archive tables. This helps in reducing the load on the primary tables, thus improving performance and manageability.

### Benefits of archiving

* **Storage Optimization**: Archived data can be compressed, saving storage space.
* **Performance Improvement**: Reduces the volume of data in primary tables, leading to faster query responses.
* **Historical Data Management**: Maintains historical data in a separate, manageable form.

## Partitioning and archiving in Oracle Database

### Oracle Database partitioning

**1. Concept**

Oracle Database [**partitioned tables**](https://docs.oracle.com/en/database/oracle/oracle-database/18/vldbg/partition-concepts.html#GUID-6D369646-16AF-487B-BF32-5F6569D27C8A) are utilized, allowing for efficient data management and query performance.

**2. Implementation**

Each partition can be managed and queried independently.

Example: The `process_instance` table can be partitioned by day, week, or month.

**3. Benefits**

Improved query performance by scanning only relevant partitions.

Simplified maintenance tasks like backups and archiving.

### Oracle Database archiving

**1. Process**

Detaching the partition from the main table.

Converting the detached partition into a new table named `archived_${table_name}_${interval_name}_${reference}` for example: `archived_process_instance_monthly_2024_03` .

> [!NOTE]
>
> The DATE is in the format `yyyy-MM-dd` if the interval is `DAY`, or in the format `yyyy-MM` if the interval is `MONTH`, or in the format `yyyy-weekOfYear` if the interval is `WEEK`.

**2. Steps**

Identify partitions eligible for archiving based on retention settings.

Detach the partition from the main table.

Create a new table with the data from the detached partition.

Optionally compress the new table to save space.

**3. Benefits**

Manages historical data by moving it to separate tables, reducing the load on the main table.

Compression options (OFF, BASIC, ADVANCED) further optimize storage.

> [!NOTE]
>
> Oracle offers several compression options—OFF, BASIC, and ADVANCED—that optimize storage. Each option provides varying levels of data compression, impacting storage savings and performance differently.
>
> * **OFF**: No compression is applied.
> * **BASIC**: Suitable for read-only or read-mostly environments, it compresses data without requiring additional licenses.
> * **ADVANCED**: Offers the highest level of compression, supporting a wide range of data types and operations. It requires an Advanced Compression license and provides significant storage savings and performance improvements by keeping data compressed in memory.
>
> For more details, you can refer to Oracle's [**Advanced Compression documentation**](https://www.oracle.com/database/advanced-compression/#rc30related).

## PostgreSQL archiving

**1. Process**

Creating a new table for the partition being archived.

Moving data from the main table to the new archive table (in batches).

> [!NOTE]
>
> Since here the DB has more work to do than just changing some labels (actual data insert and delete vs relabel a partition into a table, for Oracle Database) the data move is batched and the batch size is configurable.

**2. Steps**

Identify partitions eligible for archiving based on retention settings.

Create a new table following this naming convention: `archived__${table_name}__${interval_name}_${reference}`, example: *archived\_\_process\_instance\_\_weekly\_2024\_09* .

> [!TIP]
>
> The new table is created (same name format as for Oracle Database: `archived__${table_name}__${interval_name}_${reference}`) and data is moved from the primary table here.

Configure the batch size for data movement to control the load on the database.

**3. Benefits**

Efficiently manages historical data.

Batch processing allows for better control over the archiving process and system performance.

> [!NOTE]
>
> Differences from Oracle DBs:
>
> Archiving involves actual data movement (insert and delete operations), unlike Oracle Databases where it is mainly a relabeling of partitions.
>
> The batch size for data movement is configurable, allowing fine-tuning of the archiving process.

***

## Native PostgreSQL partitioning

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.5**
>
> Also part of FlowX.AI 5.12. Unlike most 5.12 features, this one reaches self-hosted 5.9.x deployments in a patch rather than waiting for the next LTS.

On PostgreSQL, the engine's runtime tables are converted to **native PostgreSQL partitioning**. The nine tables below become `RANGE(partition_id)` partitioned tables with a composite primary key of `(id, partition_id)`:

`process_instance` · `token_instance` · `incident` · `embedded_subprocess_instance` · `process_instance_debug` · `process_instance_initiator` · `process_instance_snapshot` · `process_inst_swimlane_owner` · `process_instance_param_values_backup`

The conversion is a database migration that runs automatically the first time the engine starts on the new version. Oracle deployments are unaffected.

### Who this affects

> [!NOTE]
>
> **Only deployments that already had partitioning enabled.** The migration checks whether this deployment has ever partitioned data, and skips the conversion entirely if it has not. If you never enabled `FLOWX_DATA_PARTITIONING_ENABLED`, there is no conversion, no lock and no extra disk use.

> [!WARNING]
>
> **The conversion runs only once.** If the migration skips because partitioning was never enabled, it is recorded as complete for that database and does not run again. Enabling partitioning after you upgrade does not convert the tables to native PostgreSQL partitioning.

### What the conversion costs

The conversion rewrites each table in full, which is why it is skipped where it would bring no benefit. While it runs, expect:

| | |
| - | - |
| **Table locking** | Each table takes an `ACCESS EXCLUSIVE` lock from the start of its rewrite until it finishes. |
| **Disk** | Roughly twice a table's size in additional space while that table is being rewritten. |
| **WAL** | A large volume of write-ahead log. |

Two things limit the impact. Each table is committed on its own, so its lock is released as soon as that table is done rather than being held across all nine. And the migration is resumable: if startup is interrupted, the next run skips the tables that already converted and continues from where it stopped.

> [!WARNING]
>
> **The conversion is one way.** Once a table is natively partitioned it stays that way. Nothing in the migration converts the tables back, and the reverse path is untested.

> [!NOTE]
>
> This is separate from steady-state storage, which does not grow. Once converted, the engine writes straight into a partitioned table instead of writing to one large table and copying rows into archive tables, so the ongoing footprint is no larger than before.

### How archiving changes

Once tables are natively partitioned, archiving detaches a partition rather than copying rows out of it, using `DETACH CONCURRENTLY`. That makes PostgreSQL archiving behave much like Oracle's, where archiving is mainly a relabelling rather than a data move, so the batched insert-and-delete described under [PostgreSQL archiving](#postgresql-archiving) no longer applies.

This is controlled by `flowx.data.partitioning.archiving.postgres-native`, which defaults to **`true`**. Setting it to `false` returns archiving to the previous batched behaviour, but it does not undo the conversion: the tables remain natively partitioned.

## Daily operations

Once set up, the partitioning and archiving process involves the following operations:

**1. Partition ID Calculation**

The `partition_id` is automatically calculated based on the configured interval (DAY, WEEK, MONTH).
Example for daily partitioning: `2024-03-01 13:00:00` results in `partition_id = 124061`. See the [**Partition ID calculation**](#partition-id-calculation) section.

**2. Retention Management**

Data older than the configured retention interval becomes eligible for archiving and compressing.

**3. Archiving process**

A cron job checks for eligible partitions.

Eligible partitions are archived and optionally compressed.

The process includes deactivating foreign keys, creating new archive tables, moving data references, reactivating foreign keys, and dropping the original partition.

**4. Space management**

Archived tables remain in the database but occupy less space if compression is enabled.

**Recommendation**: to free up space, consider moving archived tables to a different database or tablespace. Additionally, you have the option to move only process instances or copy definitions depending on your needs.

> [!WARNING]
>
> **Partitions that still contain unfinished process instances are not archived.** The archiving job detaches a partition only when every process instance in it has reached a finished state: `FINISHED`, `FINISHED_WITH_ERROR`, `FAILED`, `EXPIRED`, `ABORTED`, `DISMISSED`, or `TERMINATED`. A single instance still in `CREATED`, `STARTED`, or `ON_HOLD` blocks the entire partition from being archived; the partition is retried on the next archiving run.
>
> To keep partitions archivable:
>
> * **Set process expiry** so instances don't stay unfinished indefinitely. See [Timer Expressions](../../docs/building-blocks/node/timer-events/timer-expressions) for setting up process expiration in FlowX Designer.
> * **Turn on the stuck-instance termination sweep** (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`) to terminate instances older than the retention window that would otherwise block archiving. See [Configuring partitioning and archiving](#configuring-partitioning-and-archiving) below.
>
> Archiving removes process instance data from the working data set, making it no longer available in FlowX.

> [!NOTE]
>
> Future schema updates or migrations will not affect archived tables. They retain the schema from the moment of archiving.

## Configuring partitioning and archiving

> [!NOTE]
>
> The Partitioning and Archiving feature is optional and can be configured as needed.

> [!TIP]
>
> When starting a new version of the process-engine, we recommend manually executing the setup SQL commands from Liquibase, as they may take more time. After setup, all existing information will go into the initial partition.

Partitioning and archiving are configured under the `flowx.data.partitioning` block on the process-engine. Archiving settings — including the scheduler that detaches and archives old partitions — live in the nested `archiving` block:

```yaml theme={"dark"}
flowx:
  data:
    partitioning:
      enabled: false        # master switch for data partitioning
      interval: MONTH        # DAY, WEEK, MONTH
      premake-cron-expression: "0 0 23 * * ?"   # creates upcoming partitions ahead of the rollover
      premake-partitions-ahead: 2               # future partitions kept created ahead of the current one
      archiving:
        enabled: false       # runs the cron job that detaches and archives old partitions
        cronExpression: "0 0 1 * * ?"   # daily at 01:00
        retention-intervals: 3          # intervals kept in the FlowX database before archiving
        detached-partition-compression: OFF   # OFF, BASIC, ADVANCED (Oracle only)
        moved-data-batch-size: 5000           # PostgreSQL only
        postgres-native: true                 # PostgreSQL only, see Native PostgreSQL partitioning
        stuck-terminate:
          enabled: false                      # terminate stuck instances so archiving isn't blocked
          cron-expression: "0 0 3 * * ?"      # runs before the archiving sweep
          batch-size: 100
      backfill:
        enabled: false                        # one-shot backfill of partition_id on legacy rows
        batch-size: 250
        sleep-between-batches-ms: 500
      org-id-backfill:
        enabled: false                        # one-shot backfill of organization_id on legacy rows
```

The equivalent environment variables:

| Environment Variable | Description | Default Value | Possible Values |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | Master switch for data partitioning. | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | Interval contained in a partition. | `MONTH` | `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_PREMAKECRONEXPRESSION` | Cron expression for the job that creates upcoming partitions in advance. | `0 0 23 * * ?` (daily at 23:00) | Cron expression |
| `FLOWX_DATA_PARTITIONING_PREMAKEPARTITIONSAHEAD` | Number of future partitions kept created ahead of the current one. | `2` | Integer values |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | Runs the cron job that detaches and archives old partitions. | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | Cron expression for the archiving scheduler. | `0 0 1 * * ?` (daily at 01:00) | Cron expression |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | Number of intervals retained in the FlowX database before archiving. | `3` | Integer values (e.g., `1`, `2`, `3`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHEDPARTITIONCOMPRESSION` | Compression for archived (detached) partitions (Oracle only). | `OFF` | `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVEDDATABATCHSIZE` | Batch size for moving data (PostgreSQL only). | `5000` | Integer values (e.g., `1000`, `5000`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Archives natively partitioned tables with `DETACH CONCURRENTLY` (PostgreSQL only). See [Native PostgreSQL partitioning](#native-postgresql-partitioning). | `true` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED` | Terminates stuck process instances so unfinished data doesn't block archiving. | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_CRONEXPRESSION` | Cron for the stuck-instance termination sweep. Runs before the archiving cron. | `0 0 3 * * ?` (daily at 03:00) | Cron expression |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_BATCHSIZE` | Batch size for the stuck-instance termination sweep. | `100` | Integer values |
| `FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED` | One-shot backfill of `partition_id` on legacy rows created before partitioning was turned on. Turn off once it drains. | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_BACKFILL_BATCHSIZE` | Batch size for the `partition_id` backfill. | `250` | Integer values |
| `FLOWX_DATA_PARTITIONING_BACKFILL_SLEEPBETWEENBATCHESMS` | Pause between backfill batches, in milliseconds. | `500` | Integer values |
| `FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED` | One-shot backfill of `organization_id` on legacy rows. Optional on self-hosted; can remain `false`. | `false` | `true`, `false` |

> [!NOTE]
>
> Set `FLOWX_DATA_PARTITIONING_INTERVAL` to the same value on the process-engine and Integration Designer. A mismatch desynchronizes archive alignment between the two services. See [Integration Designer setup, Workflow partitioning](../integration-designer-setup#workflow-partitioning-configuration) for the Integration Designer settings.

> [!WARNING]
>
> **Upgrading from 5.1.x?** The configuration changed. The standalone `SCHEDULER_DATA_PARTITIONING_ENABLED` and `SCHEDULER_DATA_PARTITIONING_CRON_EXPRESSION` variables no longer exist — the archiving scheduler now lives under `flowx.data.partitioning.archiving`. The archiving scheduler also defaults to **off** (`archiving.enabled: false`), whereas the old scheduler defaulted to on. See [FlowX Engine partitioning migration](/5.9/migrating-from-5.1-lts/engine-partitioning) for the full mapping.

> [!NOTE]
>
> Compression for archived (detached) partitions is available only for Oracle DBs.

> [!NOTE]
>
> The batch size setting for archiving data is available only for PostgreSQL DBs.

## Logging information

Partitioning and archiving actions are logged in two tables:

* `DATA_PARTITIONING_LOG`: For tracking archived partitions.

![Data partitioning log table](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/partitioning_log.png)

* `DATA_PARTITIONING_LOG_ENTRY`: For logging SQL commands executed for archiving.

![Data partitioning log entry table](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/partitioning_log_entry.png)

## Enabling partitioning and Elasticsearch indexing strategy

When partitioning is enabled, the Elasticsearch indexing strategy must also be enabled and configured on FlowX Engine setup.

> [card]
>
> **Why?**
>
> * When archiving process instances, data from Elasticsearch must be deleted, not just the cache but also indexed keys (e.g., those indexed for data search on process instances).

### Elasticsearch indexing configuration

Check the Elasticsearch indexing setup here:

> [card] [Elasticsearch indexing setup](./configuring-elasticsearch-indexing/)

The partitioning configuration must be aligned with the configuration extracted from the Kafka Elasticsearch Connector, especially with the following environment variables, so the intervals are similar:

### Index partitioning

* `transforms.routeTS.topic.format: "process_instance-${timestamp}"`: This value must start with the index name defined in the process-engine config: flowx.indexing.processInstance.index-name. In this example, the index name is prefixed with "process\_instance-" and appended with a timestamp for dynamic index creation. For backward compatibility, the prefix must be "process\_instance-". However, backward compatibility is not strictly required here.
  yaml

* `transforms.routeTS.timestamp.format: "yyyyMMdd"`: This format ensures that timestamps are consistently represented and easily parsed when creating or searching for indices based on the process instance start date. You can adjust this value as needed (e.g., for monthly indexes, use "yyyyMM"). However, note that changing this format will cause existing indexed objects to remain unchanged, and update messages will be treated as new objects, indexed again in new indices. It is crucial to determine your index size and maintain consistency.

Check the following Kafka Elasticsearch Connector configuration example for more details:

> [card] [Kafka Elasticsearch Connector](./configuring-elasticsearch-indexing/elasticsearch-indexing#step-3-configure-the-elasticsearch-sink-connector)

## Technical details

### Partition ID calculation

* The `partition_id` format follows this structure: `<LEVEL || YEAR || BIN_ID_OF_YEAR>`. This ID is calculated based on the start date of the `process_instance`, the partition interval, and the partition level.
  * `LEVEL`: This represents the "Partitioning level," which increments with each change in the partitioning interval (for example, if it changes from `DAY` to `MONTH` or vice versa).
  * `YEAR`: The year extracted from the `process_instance` date.
  * `BIN_ID_OF_YEAR`: This is the ID of a bucket associated with the `YEAR`. It is created for all instances within the selected partitioning interval. The maximum number of buckets is determined by the partitioning frequency:
    * **Daily**: Up to 366 buckets per year
    * **Weekly**: Up to 53 buckets per year
    * **Monthly**: Up to 12 buckets per year

#### Calculation example

For a timestamp of `2024-03-01 13:00:00` with a daily partitioning interval, the `partition_id`would be `124061`:

* `1`: Partitioning Level (`LEVEL`)
* `24`:  Year - 2024 (`YEAR`)
* `061`: Bucket per configuration (61st day of the year)

### Archived tables

* Naming format: `archived__${table_name}__${interval_name}_${reference}`. Examples:
  * archived\_\_process\_instance\_\_monthly\_2024\_03
  * archived\_\_process\_instance\_\_weekly\_2024\_09
  * archived\_\_process\_instance\_\_daily\_2024\_03\_06


# Routing
Source: https://docs.flowx.ai/5.9/setup-guides/ingress-configuration

How FlowX services are exposed externally on 5.9.x, the per-service route table, and CORS handling at the application layer.

This guide describes how external traffic reaches FlowX services on 5.9.x: the two-host model (admin and public), the per-service route table, and CORS handling per deployment.

## Overview

On 5.9.x, FlowX services are exposed through either Kubernetes Ingress resources (the default) or Gateway API HTTPRoutes, with each service toggled independently. CORS handling moved out of ingress annotations and into the service code, with allowed origins set via an environment variable on each backend service.

Two things changed in 5.9.x compared to 5.1.x routing:

1. **Gateway API HTTPRoutes** are available as an opt-in alternative to Kubernetes Ingress. Switching a service to HTTPRoute mode is coordinated with FlowX during the upgrade window and requires the Gateway API CRDs (`gateway.networking.k8s.io/v1`) plus a compatible controller on the cluster.
2. **CORS moves to the application layer.** NGINX CORS annotations are no longer the source of truth. Each backend service reads its allowed origins from `APPLICATION_CORS_ALLOWORIGIN`; allowed methods, headers, and credentials are baked into each service's `application.yaml` with sensible defaults.

For the migration path from 5.1.x to 5.9.x, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

***

## Service route reference

FlowX services route under two host groups: **admin** (designer and admin-side APIs) and **public** (runtime renderer and integration callers). A few services additionally use a third group called **admin-instances** for runtime instance APIs on the admin host.

### Admin routes

| Service | External path | Backend receives |
| - | - | - |
| `admin` | `/` | `/` |
| `application-manager` | `/appmanager` | `/` |
| `audit-core` | `/audit` | `/` |
| `authorization-system` | `/auth` | `/` |
| `cms-core` | `/cms` | `/` |
| `document-plugin` | `/document` | `/` |
| `events-gateway` | `/api/events` | `/api/events/...` (path preserved) |
| `integration-designer` | `/integration` | `/` |
| `license` | `/license` | `/` |
| `notification-plugin` | `/notification` | `/` |
| `organization-manager` | `/org` | `/` |
| `process-engine` | `/onboarding/api` | `/api/...` |
| `runtime-manager` | `/rtm/api/build-mgmt` | `/api/build-mgmt/...` |
| `task-management-plugin` | `/task` | `/` |
| `webhook-gateway` | `/webhooks` | `/webhooks/...` (path preserved) |

### Public routes

| Service | External path | Backend receives |
| - | - | - |
| `cms-core` | `/cms` | `/` |
| `designer` | `/` | `/` |
| `document-plugin` | `/document` | `/` |
| `events-gateway` | `/api/events` | `/api/events/...` (path preserved) |
| `organization-manager` | `/org` | `/` |
| `process-engine` | `/onboarding/api` | `/api/...` |
| `runtime-manager` | `/rtm/api/runtime` | `/api/runtime/...` |
| `task-management-plugin` | `/task` | `/` |

The Designer also gets a wildcard host rule (`*.<public-host>`) for workspace-per-subdomain access; this is set up by FlowX and does not require additional configuration on your side.

### Admin-instances routes

A third group on the admin host carries runtime process and instance APIs:

| Service | External path | Backend receives |
| - | - | - |
| `process-engine` | `/api/instances` | `/api/instances/...` (path preserved) |
| `runtime-manager` | `/rtm/api/runtime`, `/rtm/api/runtime-internal` | `/api/runtime/...`, `/api/runtime-internal/...` |

### Internal-only services

The following services are not exposed externally and have no ingress or HTTPRoute rendered: `advancing-controller`, `data-search`, `email-gateway`, `nosql-db-runner`, `scheduler-core`.

***

## CORS configuration

CORS is handled inside each backend service rather than at the ingress layer. Only the allowed-origins list is deployment-specific; allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into each service's `application.yaml` with safe defaults.

### `APPLICATION_CORS_ALLOWORIGIN`

Set this environment variable on every backend service exposed via admin or public URLs:

```yaml theme={"dark"}
env:
  APPLICATION_CORS_ALLOWORIGIN: "https://designer.yourcompany.com,https://*.yourcompany.com"
```

Wildcard subdomain patterns are supported. The variable must be set on each of the 15 backend services listed in [Service route reference](#service-route-reference); designer and other frontend-only services do not need it.

The per-service rows are listed in the [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9#cors-handling-application_cors_alloworigin).

### Removed NGINX annotations

The following NGINX-specific annotations are no longer rendered on the default ingress templates and have no effect on 5.9.x:

* `nginx.ingress.kubernetes.io/enable-cors`
* `nginx.ingress.kubernetes.io/cors-allow-credentials`
* `nginx.ingress.kubernetes.io/cors-allow-headers`
* `nginx.ingress.kubernetes.io/cors-allow-methods`
* `nginx.ingress.kubernetes.io/cors-allow-origin`

Any leftover overrides referencing these should be removed during the upgrade.

***

## Customizing routes

Per-service annotations (proxy body size, timeouts, TLS, affinity, cert-manager wiring) are applied to the rendered Ingress through your deployment's chart values. Common customizations and how they map between Ingress mode and HTTPRoute mode:

| Customization | Ingress mode (annotation) | HTTPRoute mode |
| - | - | - |
| Proxy body size (uploads) | `nginx.ingress.kubernetes.io/proxy-body-size: "50m"` (annotation-driven) | Controller-specific policy CRD (Envoy Gateway `BackendTrafficPolicy`, Istio `EnvoyFilter`, Traefik `Middleware`) |
| Request timeouts | `nginx.ingress.kubernetes.io/proxy-read-timeout`, `proxy-connect-timeout` | `spec.rules[].timeouts.request` on the HTTPRoute |
| URL rewrite | `nginx.ingress.kubernetes.io/rewrite-target` | `URLRewrite` filter on the HTTPRoute |
| Session affinity | `nginx.ingress.kubernetes.io/affinity: "cookie"` | Controller-specific (Gateway API `sessionPersistence` field, v1.1+) |
| TLS certificate management | `cert-manager.io/cluster-issuer` | Same — cert-manager annotations are not NGINX-specific |

Share your existing customizations with your FlowX representative during the upgrade window so they can be carried forward.

### Default proxy body size

Three services ship with a default `proxy-body-size: 50m` annotation to support larger uploads:

* `application-manager` — admin route (application manifests)
* `document-plugin` — admin and public routes (document uploads)
* `runtime-manager` — admin route (application-version manifests)

If you need a higher limit, coordinate the override with your FlowX representative.

### Ingress controller

Kubernetes Ingress resources work with any compliant controller (Traefik, HAProxy, Istio, F5 Container Ingress Services, cloud-provider controllers). Confirm the deployment's `ingressClassName` matches the controller actually running on your cluster with your FlowX representative.

### Turning off rendered routing globally

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1**

Two global chart values control whether the FlowX chart renders routing resources at all. They act as global switches on top of the per-service `ingress.*` and `gateway.*` flags: a route is rendered only when the global switch and the per-service flag are both on. The chart routes through Gateway API by default, so it renders Kubernetes Ingress resources only after you set `global.flowx.ingress.enabled: true`. Turning Ingress on doesn't turn the Gateway API routes off.

| Property | Description | Default |
| - | - | - |
| **global.flowx.ingress.enabled** | Renders Kubernetes Ingress resources (admin, admin-instances, and public routes) | `false` |
| **global.flowx.gateway.enabled** | Renders Gateway API HTTPRoute resources (admin, admin-instances, and public routes) | `true` |

Set the relevant switch to `false` when routing is managed outside the FlowX chart — for example, when a platform team provisions Ingresses or HTTPRoutes separately. The chart then renders no routing resources of that kind, without changing any per-service configuration.

***

## Troubleshooting

### CORS errors in the browser

The browser console shows `Access-Control-Allow-Origin` errors but the request reaches the backend successfully.

1. Confirm the origin is listed in `APPLICATION_CORS_ALLOWORIGIN` on the affected service (deployment guidelines table lists the variable per service).
2. Check the value is a comma-separated string of full origins, including the scheme (`https://`).
3. Restart the service after changing the env var — Spring reads it at startup.

### 413 Request Entity Too Large

A file upload or large request body fails with HTTP 413.

1. The default `proxy-body-size: 50m` applies to the three upload-heavy routes (`application-manager`, `document-plugin`, `runtime-manager` admin). Raise the value with your FlowX representative if you need higher.
2. If you front the FlowX cluster with an external reverse proxy (F5, corporate gateway, cloud LB), check the body size limit at that layer too.

### 404 / path routing issues

A request returns 404 even though the service is healthy.

1. Cross-check the external path against [Service route reference](#service-route-reference) — the path your client sends must match the table.
2. Confirm the deployment's `ingressClassName` (Ingress mode) or attached Gateway (HTTPRoute mode) matches the controller actually running in the cluster.

***

## Related resources

> [card] [Migrating ingress from 5.1.x](/5.9/migrating-from-5.1-lts/ingress-routing)
>
> NGINX controller change, CORS env var, and the upgrade-window action checklist.

> [card] [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9)
>
> Component versions, Kafka topics, and the `APPLICATION_CORS_ALLOWORIGIN` row per service.

> [card] [Gateway API documentation](https://gateway-api.sigs.k8s.io/docs/introduction/)
>
> Upstream documentation for HTTPRoute, GatewayClass, and Gateway resources.

> [card] [Setup guides](./setup-guides-overview)
>
> Per-service configuration including each service's own routing and CORS section.


# Integration Designer setup
Source: https://docs.flowx.ai/5.9/setup-guides/integration-designer-setup

This guide explains how to configure the Integration Designer service using environment variables.

## Configuration

### Core service configuration

| Environment variable | Description | Default value |
| - | - | - |
| `LOGGING_LEVEL_APP` | Application logging level | `INFO` |

### Service communication

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_CMS_BASEURL` | Base URL for the CMS service | `http://cms-core:80` |
| `FLOWX_NOSQLDBRUNNER_BASEURL` | Base URL for the NoSQL DB Runner service | `http://nosql-db-runner:80` |
| `FLOWX_DOCUMENTPLUGIN_BASEURL` | Base URL for the Document Plugin service | `http://document-plugin:80` |
| `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` | Longest time a Document Plugin file download for a REST node JSON body (`@@base64File`) may take before it is cancelled (available from FlowX.AI 5.9.6) | `PT5M` |
| `FLOWX_WEBHOOKGATEWAY_BASEURL` | Base URL for the Webhook Gateway service | `http://webhook-gateway:80` |
| `FLOWX_WEBCRAWLER_BASEURL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80` |
| `FLOWX_ADMIN_BASEURL` | Base URL for the Admin service | `http://admin:80` |
| `FLOWX_EMAILGATEWAY_BASEURL` | Base URL for the Email Gateway service | `http://email-gateway:80` |
| `FLOWX_NOTIFICATIONPLUGIN_BASEURL` | Base URL for the Notification Plugin service | `http://notification-plugin:80` |
| `FLOWX_DATAMODEL_BASEURL` | Base URL for the Data Model service | `http://admin:80` |
| `FLOWX_DOCPARSER_BASEURL` | Base URL for the Document Parser service | `http://doc-parser:80` |
| `FLOWX_SPEECHTOTEXT_BASEURL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` |
| `FLOWX_FILEGATEWAY_BASEURL` | Base URL for the File Gateway service, used by the File Storage data source | `http://file-gateway:80` |

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_DATAPRIVACY_BASEURL` | Base URL for the Data Privacy service used by the Personal Information Guard on AI workflow nodes (input/output PII detection and redaction). | `http://data-privacy:80` |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60` |

### Storage configuration

S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | 🆕 Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | 🆕 Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | 🆕 S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://127.0.0.1:9000/` | S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | 🆕 S3 bucket prefix |

#### Redis

Integration Designer uses Redis for caching workflow execution data.

**Cache-specific configuration:**

| Variable | Description | Default Value |
| - | - | - |
| `SPRING_CACHE_TYPE` | Cache type | `redis` |
| `SPRING_CACHE_REDIS_KEYPREFIX` | Cache key prefix | `flowx:core:cache:integration-designer:` |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | Cache time to live | `5000000` |

**Redis connection:**

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

### WebClient configuration

Integration Designer interacts with various APIs, some of which return large responses. To handle such cases efficiently, the FlowX WebClient buffer size must be configured to accommodate larger payloads, especially when working with legacy APIs that do not support pagination.

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_WEBCLIENT_BUFFERSIZE` | Buffer size (in bytes) for FlowX WebClient | `52428800` (50MB) |
| `FLOWX_WEBCLIENT_BUFFERSIZEFORDOCUMENTPLUGIN` | Buffer size for Document Plugin calls | `20971520` (20MB) |
| `FLOWX_WEBCLIENT_COMPRESSIONENABLED` | Enable response compression | `true` |

### Workflow execution configuration

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_WORKFLOW_MAXEXECUTEDNODES` | Maximum number of nodes a workflow can execute | `1000` |
| `FLOWX_WORKFLOW_MAXSUBWORKFLOWDEPTH` | Maximum nesting depth for subworkflows | `100` |
| `FLOWX_SCRIPTENGINE_ALLOWUNSAFEEVAL` | Allow unsafe eval in workflow scripts | `false` |

### AI service configuration

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_AISERVICE_NODERUNNERTIMEOUTSECONDS` | Timeout (seconds) for how long an AI workflow node may run before it is cut off. Increase for Custom Agent nodes with many tool calls. | `600` |

> [!WARNING]
>
> `FLOWX_WORKFLOW_MAXEXECUTEDNODES` is a safety guardrail — workflows that exceed this limit are terminated. Increase only if your workflows legitimately require more node executions.

### Agent Builder configuration

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_AGENTBUILDER_HOST` | Hostname of the AI Platform Agent Builder service | `agent-builder` |
| `FLOWX_AGENTBUILDER_PORT` | gRPC port of the AI Platform Agent Builder service | `9100` |

> [!NOTE]
>
> Starting with 5.9.2, AI Platform services are deployed under their plain names — the `ai-platform-` prefix is dropped from the default hostnames. If you overrode these variables with the old prefixed names, update them when upgrading. See the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming).

### Process Engine configuration

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_PROCESSENGINE_BASEURL` | Base URL of the Process Engine service | `http://process-engine:80` |

### MCP client configuration

Timeouts for MCP (Model Context Protocol) server connections used by MCP Server data sources.

| Environment variable | Description | Default value |
| - | - | - |
| `MCP_CLIENT_CONNECTTIMEOUT` | TCP connect timeout for MCP server connections | `5s` |
| `MCP_CLIENT_REQUESTTIMEOUT` | Request timeout for MCP server calls | `30s` |
| `MCP_CLIENT_PREFLIGHTCONNECTTIMEOUT` | Connect timeout for preflight (health) checks | `5s` |
| `MCP_CLIENT_PREFLIGHTREADTIMEOUT` | Read timeout for preflight checks | `5s` |
| `MCP_CLIENT_CLIENTNAME` | Client name sent in MCP handshake | `flowx-integration-designer` |

### Async AI callback configuration

Controls how timed-out AI node callbacks are reaped.

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_ASYNC_AI_CALLBACK_TTL` | Time-to-live for pending AI callbacks before they expire | `PT24H` |
| `FLOWX_ASYNC_AI_REAPER_FIXED_DELAY_MS` | Interval (ms) between reaper sweeps for expired callbacks | `5000` |
| `FLOWX_ASYNC_AI_REAPER_MAX_PER_TICK` | Maximum expired callbacks reaped per sweep | `200` |

### Script engine configuration

Integration Designer uses a native script engine for executing JavaScript and Python scripts in workflow nodes. The native engine runs scripts in separate Node.js and Python worker processes.

| Environment variable | Description | Default value |
| - | - | - |
| `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider (`native` or `graalvm`) | `native` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Number of Node.js worker processes | `16` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary used for the JS worker pool | `/usr/bin/node` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | Execution timeout per script (ms) | `5000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a worker is recycled | `10000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max input payload size (bytes) | `1048576` (1 MB) |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Number of Python worker processes | `8` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary used for the Python worker pool | `/usr/bin/python3` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Execution timeout per script (ms) | `10000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a worker is recycled | `10000` |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max input payload size (bytes) | `1048576` (1 MB) |

> [!NOTE]
>
> The `native` script engine is the default starting with 5.9.0. It replaces the previous GraalVM-based engine and runs scripts in isolated Node.js / Python subprocess pools. If you need to revert to GraalVM, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`.

> [!TIP]
>
> If a script fails with a payload-too-large error, or a run reports a worker as not healthy, the input passed to the script likely exceeds its worker pool's payload limit. Raise `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` or `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` for the affected language. The JavaScript and Python limits are independent — keep them aligned when scripts in both languages handle the same data.

### Knowledge Base RAG configuration

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_KBRAG_HOST` | Hostname of the AI Platform Knowledge Base RAG service | `knowledgebase-rag` |
| `FLOWX_KBRAG_PORT` | gRPC port of the AI Platform Knowledge Base RAG service | `9100` |

### Oracle SQL schema discovery

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for cached schema discovery responses (duration format, e.g. `24h`, `1h`) | `24h` |

### Retry configuration

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_RETRY_THREADS` | Worker threads for retry processing | `20` |
| `FLOWX_RETRY_PICKINGPAUSEMILLIS` | Pause between retry picking batches (ms) | `500` |
| `FLOWX_RETRY_COOLDOWNAFTERSECONDS` | Cooldown period after retry processing (sec) | `120` |
| `FLOWX_RETRY_SCHEDULER_UNBLOCKRETRIES_CRONEXPRESSION` | Cron expression for unblocking retries | `"*/2 * * * * ?"` |

### Database configuration

#### Advancing database

The [Advancing Controller](../docs/platform-deep-dive/core-components/advancing-controller) is a support service that optimizes advancing operations by ensuring efficient, balanced workload distribution—especially during scale-up and scale-down events. To enable Integration Designer to interact with the Advancing database, configure the following environment variables:

> [!NOTE]
>
> It can connect to the same database as the FlowX.AI Engine.

| Environment variable | Description | Default value |
| - | - | - |
| `ADVANCING_DATASOURCE_URL` | Database JDBC URL | `jdbc:postgresql://localhost:5432/advancing` |
| `ADVANCING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `ADVANCING_DATASOURCE_PASSWORD` | Database password | - |
| `ADVANCING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class | `org.postgresql.Driver` |

#### Configuring the Advancing controller

| Environment variable | Description | Default value |
| - | - | - |
| `ADVANCING_PICKINGTHREADS` | Number of worker threads for reading from database (picking operations) | `1` |
| `ADVANCING_PROCESSINGTHREADS` | Number of threads for parallel processing of advancing events | `20` |
| `ADVANCING_PROCESSINGBUFFERSIZE` | Maximum buffer size for processing queue. Controls how many events can be queued | `20` |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | Block picking operations when no worker threads are available | `true` |
| `ADVANCING_PICKINGPAUSEMILLIS` | Pause duration between picking batches (ms) | `50` |
| `ADVANCING_COOLDOWNAFTERSECONDS` | Cooldown period after processing a batch (seconds) | `120` |
| `ADVANCING_SCHEDULER_HEARTBEAT_CRONEXPRESSION` | Cron expression for the heartbeat | `"*/2 * * * * ?"` |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space (even just 1 position), that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.

> [!NOTE]
>
> The Advancing Controller supports multiple database systems including PostgreSQL and Oracle. Ensure you configure the appropriate JDBC URL and driver class for your chosen database system.

### Workflow partitioning configuration

Workflow partitioning allows you to manage workflow instance data more efficiently by organizing data into time-based partitions. This is particularly useful for large-scale deployments where workflow instances accumulate over time.

> [!NOTE]
>
> This is separate from process-instance partitioning on the FlowX.AI Engine. Integration Designer partitions **workflow instances** in MongoDB and archives them into separate collections, while the engine partitions **process instances** in Oracle or PostgreSQL table partitions. Configure each service on its own. See [Partitioning & archiving](./flowx-engine-setup-guide/process-instance-data-archiving) for the engine side.

| Environment variable | Description | Default value | Options |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | Turn on or off workflow instance partitioning | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | Time interval for creating partitions | `MONTH` | `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | Turn on or off automatic archiving of old partitions | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | Number of intervals to retain before archiving | `3` | Any positive integer |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | Cron expression for the archiving schedule | `0 0 1 * * ?` | Any valid cron expression |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_BATCHSIZE` | Batch size for moving documents into archive collections | `5000` | Integer values |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MAXDURATIONMINUTES` | Maximum time a single partition archive may run before it times out | `240` | Integer values |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_SLEEPBETWEENBATCHESMS` | Pause between archive batches, in milliseconds | `200` | Integer values |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED` | Terminate stuck workflow instances so archiving isn't blocked | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_CRONEXPRESSION` | Cron for the stuck-instance termination sweep. Runs before the archiving cron. | `0 0 3 * * ?` | Any valid cron expression |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_BATCHSIZE` | Batch size for the stuck-instance termination sweep | `100` | Integer values |
| `FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED` | One-shot backfill of `partition_id` on legacy documents. Turn off once it drains. | `false` | `true`, `false` |
| `FLOWX_DATA_PARTITIONING_BACKFILL_BATCHSIZE` | Batch size for the `partition_id` backfill | `5000` | Integer values |
| `FLOWX_DATA_PARTITIONING_BACKFILL_SLEEPBETWEENBATCHESMS` | Pause between backfill batches, in milliseconds | `100` | Integer values |
| `FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED` | One-shot backfill of `organization_id` on legacy documents. Optional on self-hosted; can remain `false`. | `false` | `true`, `false` |

> [!NOTE]
>
> Set `FLOWX_DATA_PARTITIONING_INTERVAL` to the same value on Integration Designer and the process-engine. A mismatch desynchronizes archive alignment between the two services.

> [!NOTE]
>
> **How workflow partitioning works:**
>
> * **Partitioning**: When turned on, workflow instances are stored in time-based partitions according to the specified interval.
> * **Partition interval**: Determines how frequently new partitions are created (`DAY`, `WEEK`, or `MONTH`).
> * **Archiving**: When turned on, automatically archives partitions older than the specified retention intervals. For example, with `MONTH` interval and `3` retention intervals, partitions older than 3 months will be archived.
> * **Archiving schedule**: The cron expression controls when the archiving process runs. The default `0 0 1 * * ?` runs daily at 1:00 AM.

> [!WARNING]
>
> **Partitions that still contain unfinished workflow instances are not archived.** The archiving job processes a partition only when every workflow instance in it has reached a finished state: `FINISHED`, `FAILED`, or `CANCELLED`. A single workflow instance still in `STARTED` blocks the entire partition; the partition is retried on the next archiving run. If archiving stalls, turn on the stuck-instance termination sweep (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`) to force blocking workflow instances into a final state so archiving can advance.

> [!WARNING]
>
> Turn on partitioning and archiving only after careful planning and testing. Once turned on, ensure that your database has sufficient storage for partition management operations. It's recommended to start with archiving turned off and turn it on only after verifying that partitioning works correctly for your use case.

#### MongoDB

Integration Designer requires two MongoDB databases for managing integration-specific data and runtime data:

* **Integration Designer Database** (`integration-designer`): Stores data specific to Integration Designer, such as integration configurations, metadata, and other operational data.
* **Shared Runtime Database** (`app-runtime`): Shared across multiple services, this database manages runtime data essential for integration and data flow execution.

| Environment variable | Description | Default value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | Integration Designer MongoDB URI | `mongodb://mongodb-0.mongodb-headless:27017/integration-designer` |
| `SPRING_DATA_MONGODB_USERNAME` | MongoDB username | `integration-designer` |
| `SPRING_DATA_MONGODB_PASSWORD` | MongoDB password | |
| `SPRING_DATA_MONGODB_STORAGE` | Storage type (Azure environments only) | `mongodb` (or `cosmosdb`) |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | Runtime MongoDB URI | `mongodb://mongodb-0.mongodb-headless:27017/app-runtime` |
| `SPRING_DATA_MONGODB_RUNTIME_USERNAME` | Runtime MongoDB username | `app-runtime` |
| `SPRING_DATA_MONGODB_RUNTIME_PASSWORD` | Runtime MongoDB password | |

> [!NOTE]
>
> Integration Designer requires a runtime connection to function correctly. Starting the service without a configured and active runtime MongoDB connection is not supported.

### Configuration parameters

There are two types of Config Params that can be read from the environment: **variables** and **secrets**. There is one provider for variables and secrets extracted from the environment variables, and two providers for the ones extracted from Kubernetes. By default, the variables and secrets are extracted from environment variables (`env` provider).

#### Configuration parameters from environment variables (default)

The `env` provider used for variables and secrets extracts them from environment variables. For security reasons, the `env` provider uses an allow list regex which defaults to `FLOWX_CONFIGPARAM_.*`. This means only environment variables that match this naming pattern can be read at runtime into configuration params (either as variables or secrets). Feel free to edit it to match the environment variables that you use in your deployment.

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER` | Provider type for variables | `env` |
| `FLOWX_CONFIGPARAMS_VARS_ALLOWLISTREGEX` | Regular expression to match allowed env variables for variables | `FLOWX_CONFIGPARAM_.*` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | Provider type for secrets | `env` |
| `FLOWX_CONFIGPARAMS_SECRETS_ALLOWLISTREGEX` | Regular expression to match allowed env variables for secrets | `FLOWX_CONFIGPARAM_.*` |

#### Configuration parameters from Kubernetes Secrets and ConfigMaps

Use the following configuration to read Config Params from Kubernetes Secrets and ConfigMaps:

| Environment variable | Description | Values |
| - | - | - |
| `FLOWX_CONFIGPARAMS_VARS_PROVIDER` | Provider type for variables | `k8s-configmaps` |
| `FLOWX_CONFIGPARAMS_SECRETS_PROVIDER` | Provider type for secrets | `k8s-secrets` |

These providers can be configured as follows:

| Environment variable | Description | Values |
| - | - | - |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_0` | Name of the ConfigMap to use for variables | `flowx-configparams` |
| `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_0` | Name of the Secret to use for secrets | `flowx-configparams` |

> [!NOTE]
>
> You can configure multiple secrets and ConfigMaps by incrementing the index number (e.g., `FLOWX_CONFIGPARAMS_PROVIDERS_K8SSECRETS_SECRETSLIST_1`, `FLOWX_CONFIGPARAMS_PROVIDERS_K8SCONFIGMAPS_CONFIGMAPSLIST_1`). In dev environments, the typical ConfigMap/Secret name is `flowx-rt`. Values are overridden based on the order in which the maps are defined.
>
> The default provider is `env`, but there is a built-in allowlist with the regex pattern `FLOWX_CONFIGPARAM_.*`. This means only configuration parameters that match this naming pattern can be read at runtime, whether they are environment variables or secret variables.

### Kafka configuration

#### Kafka connection and security variables

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT` or `SASL_PLAINTEXT` |
| `FLOWX_WORKFLOW_CREATETOPICS` | When `true`, Integration Designer creates each workflow's input and output topics through the Kafka admin API. See [Engine and Integration communication topics](#engine-and-integration-communication-topics) | `false` (default) |
| `FLOWX_WORKFLOW_TOPICPARTITIONS` | Number of partitions for auto-created workflow topics (available starting with FlowX.AI 5.9.3; must be 1 or higher) | `1` |

#### Message size configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size | `52428800` (50MB) |

This setting affects:

* Producer message max bytes
* Producer max request size

#### Consumer configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_CONSUMER_GROUPID_STARTWORKFLOWS` | Start workflows consumer group | `start-workflows-group` |
| `KAFKA_CONSUMER_GROUPID_RESELEMUSAGEVALIDATION` | Resource usage validation consumer group | `integration-designer-res-elem-usage-validation-group` |
| `KAFKA_CONSUMER_GROUPID_SYSTEMSYNC` | System sync consumer group | `system-sync-group` |
| `KAFKA_CONSUMER_GROUPID_WORKFLOWSYNC` | Workflow sync consumer group | `workflow-sync-group` |
| `KAFKA_CONSUMER_GROUPID_CORRECTIONAFTERAPPOPERATION` | Correction after app operation consumer group | `correction-after-app-operation-group` |
| `KAFKA_CONSUMER_GROUPID_STOREENTRYINDEXERRESPONSE` | KB store entry indexer response consumer group | `store-entry-indexer-response-group` |
| `KAFKA_CONSUMER_THREADS_STARTWORKFLOWS` | Start workflows consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_RESELEMUSAGEVALIDATION` | Resource usage validation consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_SYSTEMSYNC` | System sync consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_WORKFLOWSYNC` | Workflow sync consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_CORRECTIONAFTERAPPOPERATION` | Correction after app operation consumer threads | `3` |
| `KAFKA_CONSUMER_THREADS_STOREENTRYINDEXERRESPONSE` | KB store entry indexer response consumer threads | `3` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization errors | `10` (seconds) |

#### Topic naming convention and pattern creation

The Integration Designer uses a structured topic naming convention that follows a standardized pattern, ensuring consistency across environments and making topics easily identifiable.

##### Topic naming components

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Base package for topics | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment identifier | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Topic version | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Topic name separator | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Alternative separator | `-` |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern | `engine.receive.` |
| `KAFKA_TOPIC_NAMING_INTEGRATIONRECEIVEPATTERN` | Integration receive pattern | `integration.receive.` |

Topics are constructed using the following pattern:

```
{prefix} + service + {separator/dot} + action + {separator/dot} + detail + {suffix}
```

For example, a typical topic might look like:

```
ai.flowx.eventsgateway.receive.workflowinstances.v1
```

Where:

* `ai.flowx.` is the prefix (package + environment)
* `eventsgateway` is the service
* `receive` is the action
* `workflowinstances` is the detail
* `.v1` is the suffix (version)

#### Kafka topic configuration

##### Core topics

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

##### Events gateway topics

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Topic for workflow instances communication | `ai.flowx.eventsgateway.receive.workflowinstances.v1` |

##### UI flow session variable updates

When a workflow triggered by a UI Flow finishes, the integration-designer sends the result to the process-engine so the session variables are updated automatically.

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending workflow results to process-engine for UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` |

##### Knowledge Base store entry lifecycle topics

These topics handle communication between Integration Designer and the AI Platform for Knowledge Base store entry indexing operations.

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_KB_STOREENTRYLIFECYCLE_IN` | Topic for receiving KB store entry index responses from AI Platform (consumed) | `ai.flowx.ai-platform.knowledgebase.store-entry.index-response.v1` |
| `KAFKA_TOPIC_KB_STOREENTRYLIFECYCLE_OUT` | Topic for sending KB store entry index requests to AI Platform (produced) | `ai.flowx.ai-platform.knowledgebase.store-entry.index-request.v1` |

##### AI Platform job topics

Integration Designer dispatches document parsing, speech-to-text, and evaluation jobs to the AI Platform over Kafka. Each job family has a request topic (produced), a response topic (consumed), and a dead-letter topic (consumed).

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_AI_DOCPARSER_JOB_REQUEST_OUT` | Document Parser job requests (produced) | `ai.flowx.ai-platform.doc-parser.job.request.v1` |
| `KAFKA_TOPIC_AI_DOCPARSER_JOB_RESPONSE_IN` | Document Parser job responses (consumed) | `ai.flowx.ai-platform.doc-parser.job.response.v1` |
| `KAFKA_TOPIC_AI_DOCPARSER_JOB_DLQ_IN` | Document Parser job dead-letter queue (consumed) | `ai.flowx.ai-platform.doc-parser.job.dlq.v1` |
| `KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_REQUEST_OUT` | Speech-to-Text job requests (produced) | `ai.flowx.ai-platform.speech-to-text.job.request.v1` |
| `KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_RESPONSE_IN` | Speech-to-Text job responses (consumed) | `ai.flowx.ai-platform.speech-to-text.job.response.v1` |
| `KAFKA_TOPIC_AI_SPEECHTOTEXT_JOB_DLQ_IN` | Speech-to-Text job dead-letter queue (consumed) | `ai.flowx.ai-platform.speech-to-text.job.dlq.v1` |
| `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT` | Evaluations judge job requests (produced) | `ai.flowx.ai-platform.evals-judge.job.request.v1` |
| `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_RESPONSE_IN` | Evaluations judge job responses (consumed) | `ai.flowx.ai-platform.evals-judge.job.response.v1` |
| `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_DLQ_IN` | Evaluations judge job dead-letter queue (consumed) | `ai.flowx.ai-platform.evals-judge.job.dlq.v1` |
| `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT` | Evaluation improvement-suggestions job requests (produced) — available from FlowX.AI 5.9.1 | `ai.flowx.evals.suggestions.job.request.v1` |
| `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN` | Evaluation improvement-suggestions job responses (consumed) — available from FlowX.AI 5.9.1 | `ai.flowx.evals.suggestions.job.response.v1` |

##### Engine and Integration communication topics

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_ENGINEPATTERN` | Pattern for Engine communication | `ai.flowx.engine.receive.` |
| `KAFKA_TOPIC_INTEGRATIONPATTERN` | Pattern for Integration communication | `ai.flowx.integration.receive.*` |

Each workflow uses its own pair of topics, named from these patterns and the workflow's resource definition ID:

| Direction | Default topic |
| - | - |
| Process → workflow: the start message | `ai.flowx.integration.receive.<workflow-id>.in` |
| Workflow → process: the workflow output | `ai.flowx.engine.receive.<workflow-id>.out` |

> [!NOTE]
>
> **Kafka brokers with topic auto-creation turned off**
>
> If your brokers run with `auto.create.topics.enable=false`, a new workflow's topics exist only if something creates them. Use one of these options:
>
> * Set `FLOWX_WORKFLOW_CREATETOPICS=true`. Integration Designer then creates both topics when a workflow is created, duplicated, or imported. It uses the Kafka admin API, which works whatever the broker setting, so the Kafka user of Integration Designer needs permission to create topics. Partitions come from `FLOWX_WORKFLOW_TOPICPARTITIONS`. The replication factor equals the number of brokers. Topics aren't created at startup for workflows that already exist. If creation fails, Integration Designer logs `Topics could not be created.` and still saves the workflow.
> * Create both topics yourself for every new workflow, with the partition count and replication factor your load needs.

##### Application topics

**Outbound topics:**

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_APPLICATION_OUT_SYNCRESPONSE` | Sync response messages | `ai.flowx.application-version.sync.out.v1` |
| `KAFKA_TOPIC_APPLICATION_OUT_CORRECTIONAFTERAPPOPERATIONRESPONSE` | Correction after app operation response | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | Build runtime data | `ai.flowx.build.runtime-data.v1` |
| `KAFKA_TOPIC_LICENSE_OUT_USAGE` | License usage tracking | `ai.flowx.license.usage.v1` |

> [!NOTE]
>
> The `sync.out.v1` and `correction-after-app-operation.response.v1` topics exist since 5.1.x (produced by admin). Starting with 5.5.0, integration-designer also produces to these shared response topics for system and workflow sync/correction operations.

**Inbound topics:**

| Environment variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_APPLICATION_IN_RESELEMUSAGEVALIDATION` | Resource usage validation requests | `ai.flowx.application-version.resources-usages.sub-res-validation.request-integration.v1` |
| `KAFKA_TOPIC_APPLICATION_IN_SYSTEMSYNCREQUEST` | System sync requests | `ai.flowx.application-version.sync.system.in.v1` |
| `KAFKA_TOPIC_APPLICATION_IN_WORKFLOWSYNCREQUEST` | Workflow sync requests | `ai.flowx.application-version.sync.workflow.in.v1` |
| `KAFKA_TOPIC_APPLICATION_IN_CORRECTIONAFTERAPPOPERATION_SYSTEM` | System correction after app operation | `ai.flowx.application-version.correction-after-app-operation.system.request.v1` |
| `KAFKA_TOPIC_APPLICATION_IN_CORRECTIONAFTERAPPOPERATION_WORKFLOW` | Workflow correction after app operation | `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Resource usage refresh commands | `ai.flowx.application-version.resources-usages.refresh.v1` |

#### OAuth authentication variables (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Inter-Service topic coordination

When configuring Kafka topics in the FlowX ecosystem, ensure proper coordination between services:

1. **Topic name matching**: Output topics from one service must match the expected input topics of another service.

2. **Pattern consistency**: The pattern values must be consistent across services:

   * Process Engine listens to topics matching: `ai.flowx.engine.receive.*`
   * Integration Designer listens to topics matching: `ai.flowx.integration.receive.*`

3. **Communication flow**:
   * Other services write to topics matching the Engine's pattern → Process Engine listens
   * Process Engine writes to topics matching the Integration Designer's pattern → Integration Designer listens

> [!NOTE]
>
> The exact pattern value isn't critical, but it must be identical across all connected services. Some deployments require manually creating Kafka topics in advance rather than dynamically. In these cases, all topic names must be explicitly defined and coordinated.

### Kafka topics best practices

#### Large message handling for workflow instances topic

The workflow instances topic requires special configuration to handle large messages. By default, Kafka has message size limitations that may prevent Integration Designer from processing large workflow payloads.

**Recommended `max.message.bytes` value**: `10485760` (10 MB)

#### Workflow output size limit

Starting with FlowX.AI 5.9.5, Integration Designer checks the size of a workflow's output before publishing it to Kafka. A root workflow output larger than the limit fails the workflow run with the failure type `outputTooLargeForKafka`, instead of being dropped by the broker after the run is marked finished.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_KAFKA_PAYLOAD_SIZE_LIMIT` | Maximum serialized size, in bytes, of a root workflow output published to Kafka | `786432` |

> [!TIP]
>
> Keep this limit below the `max.message.bytes` value of the topic that receives the output.

#### Method: update using AKHQ (recommended)

1. **Access AKHQ**
   * Open the AKHQ web interface
   * Log in if authentication is required

2. **Navigate to Topic**
   * Go to the "Topics" section
   * Find the topic: `ai.flowx.eventsgateway.receive.workflowinstances.v1`

3. **Edit Configuration**
   * Click on the topic name
   * Go to the "Configuration" tab
   * Locate or add `max.message.bytes`
   * Set the value to `10485760`
   * Save changes

### CAS lib configuration

CAS lib is used to communicate with the authorization-service through SpiceDB.

| Environment variable | Description | Default value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | Spicedb host | `spicedb` |
| `FLOWX_SPICEDB_PORT` | Spicedb port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | Spicedb db token | `REPLACEME` |

### Configuring authentication and access roles

Integration Designer validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment variable | Description | Default value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-integration-designer-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

For detailed instructions on configuring user roles and access rights, refer to:

> [card] [Access Management](./access-management/access-management-overview)

For configuring a service account, refer to:

> [card] [Integration Designer service account](./access-management/configuring-an-iam-solution#integration-designer-service-account)

### Configuring logging

To control the log levels for Integration Designer, set the following environment variables:

| Environment variable | Description | Default value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root Spring Boot logs level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-level logs level | `INFO` |

### Configuring admin ingress

The Integration Designer service uses the standard FlowX.AI ingress pattern. For complete setup instructions including the full ingress template, CORS configuration, and troubleshooting, see the [Ingress Configuration Guide](./ingress-configuration).

**Service-specific values for Integration Designer:**

* **Ingress name:** `integration-designer-admin`
* **Service path:** `/integration(/|$)(.*)`
* **Service name:** `integration-designer`
* **Rewrite target:** `/$2`
* **Fx-Workspace-Id:** Required

> [card] [Complete Ingress Configuration](./ingress-configuration)
>
> View the centralized ingress guide for the complete configuration template, annotations reference, and best practices.

### Monitoring and maintenance

To monitor the performance and health of the Integration Designer, use tools like Prometheus or Grafana. Configure Prometheus metrics with:

| Environment variable | Description | Default value |
| - | - | - |
| `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` | Enable Prometheus metrics export | `false` |

### RBAC configuration

Integration Designer requires specific RBAC (Role-Based Access Control) permissions to access Kubernetes ConfigMaps and Secrets, which store necessary configurations and credentials. Set up these permissions by enabling RBAC and defining the required rules:

```yaml theme={"dark"}
rbac:
  create: true
  rules:
    - apiGroups:
        - ""
      resources:
        - secrets
        - configmaps
        - pods
      verbs:
        - get
        - list
        - watch
```

This configuration grants read access (`get`, `list`, `watch`) to ConfigMaps, Secrets, and Pods, which is essential for retrieving application settings and credentials required by Integration Designer.

***

## Ingress and CORS

The Integration Designer service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/integration` | `/` |

The path is set through `services.integration-designer.ingress.admin.path` (or `services.integration-designer.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Integration Designer. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

> [accordion] Integration Designer fails to start
>
> **Symptoms:** Service crashes on startup or fails health checks.
>
> **Solutions:**
>
> 1. Verify MongoDB connection URIs for both the `integration-designer` and `app-runtime` databases
> 2. Check that Kafka broker addresses are reachable and the security protocol is correct
> 3. Ensure the Keycloak service account is properly configured and the client secret is valid
> 4. Review logs at `LOGGING_LEVEL_APP=DEBUG` for detailed startup error messages

> [accordion] REST connector calls failing
>
> **Symptoms:** Workflow executions fail at REST connector nodes with timeout or connection errors.
>
> **Solutions:**
>
> 1. Verify network connectivity between the Integration Designer pod and the target system
> 2. Check SSL/TLS certificates if the target system uses HTTPS
> 3. Review timeout settings and increase `FLOWX_WEBCLIENT_BUFFERSIZE` if responses are large
> 4. Ensure firewall rules and network policies allow outbound traffic to the target host and port

> [accordion] Workflow execution errors
>
> **Symptoms:** Workflows start but fail during execution with Kafka or data mapping errors.
>
> **Solutions:**
>
> 1. Verify that all required Kafka topics exist and are correctly named across services
> 2. Check that input/output parameter mappings match the expected data model
> 3. Ensure the `KAFKA_TOPIC_ENGINEPATTERN` and `KAFKA_TOPIC_INTEGRATIONPATTERN` values are consistent with the Process Engine configuration
> 4. Review the events gateway topic (`KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE`) for message delivery issues

> [accordion] Data sources not connecting
>
> **Symptoms:** Data sources configured in Integration Designer show connection errors or timeouts.
>
> **Solutions:**
>
> 1. Verify that the credentials for the target data source are correct and not expired
> 2. Check network access between the Integration Designer pod and the data source endpoint
> 3. Ensure firewall rules allow traffic on the required ports
> 4. For S3-compatible storage issues, verify `APPLICATION_FILESTORAGE_S3_SERVERURL` and access key configuration

***

## Related resources

> [card] [Integration Designer](../docs/platform-deep-dive/integrations/integration-designer)
>
> Learn about the Integration Designer and how to build integration workflows

> [card] [Building a Connector](../docs/platform-deep-dive/integrations/building-a-connector)
>
> Step-by-step guide for creating connectors in Integration Designer

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup

> [card] [Events Gateway Setup](./events-gateway-setup)
>
> Configure the Events Gateway for inter-service communication


# Kafka Authentication profile
Source: https://docs.flowx.ai/5.9/setup-guides/kafka-authentication-config

Enable secure Kafka communication across Java microservices using Spring configuration profiles

The FlowX.AI platform supports enabling **Kafka authentication** across all Java microservices using a dedicated **Spring configuration profile**. This feature simplifies the activation of secure Kafka communication by centralizing the configuration in one place.

> [!NOTE]
>
> Currently, **kafka-auth is the only supported profile** provided by the platform for Kafka authentication.

## Understanding SPRING\_PROFILES\_ACTIVE

`SPRING_PROFILES_ACTIVE` is an environment variable used by Spring Boot to determine which configuration profiles should be active at runtime.

### Key characteristics

* **Multiple profiles**: Can contain one or more profile names, separated by commas
  * Example: `SPRING_PROFILES_ACTIVE=dev,kafka-auth`
* **Environment-specific behavior**: Profiles allow different sets of configuration to be loaded depending on the environment or required feature set
* **Special kafka-auth profile**: Activates Kafka authentication across services

> [!WARNING]
>
> If `SPRING_PROFILES_ACTIVE` is not set, the application runs with the **default profile**, which does **not** include Kafka authentication.

## Configuration details

When the `kafka-auth` profile is enabled, the following **Spring Kafka properties** are automatically applied:

```yaml theme={"dark"}
spring.config.activate.on-profile: kafka-auth

spring:
  kafka:
    security.protocol: "SASL_PLAINTEXT"
    properties:
      sasl:
        mechanism: "OAUTHBEARER"
        jaas.config: >
          org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required
          oauth.client.id="${KAFKA_OAUTH_CLIENT_ID:kafka}"
          oauth.client.secret="${KAFKA_OAUTH_CLIENT_SECRET:kafka-secret}"
          oauth.token.endpoint.uri="${KAFKA_OAUTH_TOKEN_ENDPOINT_URI:kafka.auth.localhost}" ;
        login.callback.handler.class: io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler
```

### Configuration properties explained

| Property | Purpose | Value |
| - | - | - |
| `spring.kafka.security.protocol` | Defines Kafka communication protocol | `SASL_PLAINTEXT` |
| `spring.kafka.properties.sasl.mechanism` | Authentication mechanism used for SASL | `OAUTHBEARER` |
| `spring.kafka.properties.sasl.jaas.config` | JAAS login configuration referencing environment variables | See configuration |
| `spring.kafka.properties.sasl.login.callback.handler.class` | Callback handler for OAuth authentication | `io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler` |

## Required environment variables

The Kafka authentication profile uses environment variables to configure OAuth parameters dynamically. These variables should be set in the runtime environment for each microservice.

| Environment Variable | Default Value | Description |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | `kafka` | OAuth client ID used to authenticate with the token endpoint |
| `KAFKA_OAUTH_CLIENT_SECRET` | `kafka-secret` | Secret associated with the OAuth client ID |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | `kafka.auth.localhost` | OAuth token endpoint URI from which access tokens are obtained |

> [!WARNING]
>
> These variables should be set in the runtime environment. If they are not provided, the defaults listed above will be used.

## Benefits

Enabling the Kafka authentication profile provides several advantages:

* **Centralized enablement**: Activates OAuth-based Kafka authentication consistently across services.
* **Configurable via environment variables**: No hardcoding of sensitive data in app configuration.
* **Simple activation**: Controlled entirely by the `SPRING_PROFILES_ACTIVE` variable.

## Notes and limitations

* Only the kafka-auth profile is currently supported for Kafka authentication.
* The profile enforces **SASL/OAUTHBEARER with plaintext transport**. Secure networking (for example, VPN, mTLS) should be ensured where required.


# KB Enrichment setup
Source: https://docs.flowx.ai/5.9/setup-guides/kb-enrichment

Deployment and configuration of the AI Platform KB Enrichment service, which provides design-time document intelligence over knowledge-base documents.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.1.** `ai-platform-kb-enrichment` replaces the decommissioned `di-platform` service.

## Overview

`ai-platform-kb-enrichment` provides **design-time document intelligence** over knowledge-base documents — chunking, enrichment, and preparing content for indexing. It is a Python service in the AI Platform, exposing gRPC and consuming a Kafka enrichment-request topic.

It deploys as a sub-chart of the AI Platform umbrella Helm chart like every other AI service (listening on port `9100` via `SERVICE_PORT` in Kubernetes), but has a few extra deployment requirements covered below.

## Prerequisites

> [card] Infrastructure
>
> * AI Platform chart deployed (KB Enrichment is a subchart)
> * PostgreSQL instance (shared with the other AI Platform databases)
> * S3-compatible object storage (MinIO, AWS S3, …)
> * Kafka

> [card] Platform dependencies
>
> * `doc-parser` deployed (`doc-parser.installed: true`)
> * An organization `TEXT_GENERATION` LLM capability configured
> * Egress to `huggingface.co` on first start (or a pre-seeded model cache)

## Deployment

KB Enrichment is enabled as part of the AI Platform chart. The dependencies below are provisioned automatically by the FlowX Helm charts in standard deployments — the notes call out what each one needs.

### PostgreSQL database

KB Enrichment uses a dedicated **`kbenrichment`** database on the same instance and credentials as the other AI Platform databases (for example, next to the `embedder` database). The FlowX Helm dependencies chart provisions it automatically.

> [!NOTE]
>
> KB Enrichment uses PostgreSQL only for service/job state — vector embeddings are stored in Qdrant. The `knowledgebases_design` Qdrant collection is auto-created by the `embedder` service; no provisioning step is required.

### Object storage

Parse offloads go to the **`kb-enrichment-bucket`** bucket (auto-created on MinIO), shared with Knowledge Base Indexer v2: the indexer writes offload documents and KB Enrichment reads them back.

KB Enrichment reads the offloads with the platform `APPLICATION_FILE_STORAGE_S3_*` connection. Knowledge Base Indexer v2 writes them through the same connection, so set these variables on both services. If a required variable is missing, the first enrichment fails with a `please set ... environment variable` error. Include the scheme in the server URL: an `https://` URL turns on TLS.

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILE_STORAGE_S3_SERVER_URL` | Required. Object storage endpoint URL | - |
| `APPLICATION_FILE_STORAGE_S3_ACCESS_KEY` | Required. Object storage access key | - |
| `APPLICATION_FILE_STORAGE_S3_SECRET_KEY` | Required. Object storage secret key | - |
| `APPLICATION_FILE_STORAGE_S3_BUCKET_NAME` | Required. Bucket that holds the parse offloads. Must be set even when `KB_ENRICHMENT_OFFLOAD_BUCKET` overrides it | - |
| `APPLICATION_FILE_STORAGE_S3_ROOT_DIRECTORY` | Prefix added to every offload object key | `""` |
| `KB_ENRICHMENT_OFFLOAD_BUCKET` | Optional override for the offload bucket name. Leave unset to use the shared default. | `kb-enrichment-bucket` |

### Model cache and egress

On first start the service downloads its `model2vec` chunking model from `huggingface.co`. The Helm chart already points the model caches at writable paths, so no manual configuration is needed:

| Environment Variable | Description | Default Value |
| - | - | - |
| `HF_HOME` | Hugging Face cache directory | `/tmp` |
| `XDG_CACHE_HOME` | XDG cache directory | `/tmp` |
| `NLTK_DATA` | NLTK data directory | `/tmp` |

> [!WARNING]
>
> Air-gapped environments must allow the `huggingface.co` download on first start or pre-seed the model cache; otherwise the service cannot initialize its chunking model.

### Kafka topic

KB Enrichment consumes enrichment requests produced by Knowledge Base Indexer v2:

| Topic | Partitions | Direction |
| - | - | - |
| `ai.flowx.ai-platform.knowledgebase.internal.enrichment-request.v1` | 3 | Indexer v2 → KB Enrichment (consume) |

The topic is provisioned automatically by the FlowX Kafka chart — no manual creation is required for standard deployments.

## Required platform configuration

**1. Turn on doc-parser**

AI Base ships with `doc-parser.installed: false`. Document ingestion through KB Enrichment requires `doc-parser` to be deployed — set `doc-parser.installed: true` in your AI Platform values. See the [Document Parser setup guide](/5.9/setup-guides/document-parser-setup).

**2. Seed the LLM configuration**

The organization needs a `TEXT_GENERATION` capability with a default model and provider API key configured in the **AI Providers** UI. Without it, enrichment fails with a `no capability TEXT_GENERATION` error. See [AI providers](/5.9/ai-platform/ai-providers).

> [!NOTE]
>
> Service accounts and Keycloak clients follow the standard AI Platform pattern — nothing new is required for KB Enrichment.

## Verification

**1. Check the pod**

```bash theme={"dark"}
kubectl get pods -l app=kb-enrichment   # 5.9.1: -l app=ai-platform-kb-enrichment
```

**2. Confirm dependencies**

Verify the `kbenrichment` database exists, the `kb-enrichment-bucket` was created on object storage, and the enrichment-request topic is present.

**3. Review logs**

On a healthy first start the logs show the `model2vec` model downloading and the service connecting to PostgreSQL and Kafka. A `no capability TEXT_GENERATION` error means the organization LLM configuration is missing (see [AI providers](/5.9/ai-platform/ai-providers)).

## Related resources

> [card] [AI Platform setup](/5.9/setup-guides/ai-platform-setup)
>
> Full AI Platform deployment and shared configuration

> [card] [Document Parser setup](/5.9/setup-guides/document-parser-setup)
>
> Required dependency for document ingestion

> [card] [AI providers](/5.9/ai-platform/ai-providers)
>
> Configure the TEXT\_GENERATION LLM capability

> [card] [Qdrant setup](/5.9/setup-guides/qdrant)
>
> Vector store for knowledge-base embeddings


# License service setup
Source: https://docs.flowx.ai/5.9/setup-guides/license-engine-setup

Set up the License service (formerly License Engine) — manages platform and application licensing, subscription plans, feature quotas, and usage tracking across SaaS and self-hosted deployments.

## Dependencies

Before setting up the License service, ensure you have the following dependencies in place:

* **[Organization Manager](/5.9/setup-guides/organization-manager-setup)** for organization lifecycle events and realm resolution
* **PostgreSQL** database for storing license and usage data
* **Kafka** for event-driven communication with other FlowX.AI services
* **Redis** for caching and master election
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained authorization

## Infrastructure prerequisites

| Component | Description |
| - | - |
| PostgreSQL | Dedicated database for license data |
| Kafka | Message broker for inter-service communication |
| Redis | Caching layer and distributed lock for master election |
| Keycloak | Identity provider for service authentication |
| SpiceDB | Authorization service for fine-grained access control |

***

## Configuration

### Authorization configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Security type (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-license-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret. Must be the same value across every service that uses `flowx-anonymous-sa`. | |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL | `http://organization-manager:80` |

***

### PostgreSQL configuration

The License service uses its own dedicated PostgreSQL database.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for PostgreSQL | `jdbc:postgresql://flowxlicensedb:5432/license` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | - |

> [!NOTE]
>
> **PostgreSQL and Redis credentials: plain env vars still work.** The License service is a standard Spring Boot service — it reads the `SPRING_DATASOURCE_*` and `SPRING_DATA_REDIS_*` environment variables shown here. The `postgresql.servers/credentials` and `redis.servers/credentials` blocks in the FlowX Helm chart's `values.yaml` are the chart's own secret-to-env-var mapping; they exist to template the same plain env vars from your secrets. You can keep injecting credentials through plain environment variables exactly as before.

> [!WARNING]
>
> Ensure the database is created before deploying the service. The License service will manage its own schema migrations via Liquibase.

***

### Redis configuration

The License service includes Redis in its configuration for caching and master election. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

> [!NOTE]
>
> Redis is required. The License service uses it as its cache and to elect the instance that runs the usage and license schedulers, so only one replica runs each scheduled job.

***

### Kafka configuration

#### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |

#### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

#### Kafka topics

The License service consumes events from the following topics:

| Topic | Default Value | Description |
| - | - | - |
| License usage | `ai.flowx.license.usage.v1` | Receives usage reporting events from other services |
| Organization events | `ai.flowx.organization.events.v1` | Receives organization lifecycle events |
| License events | `ai.flowx.license.events.v1` | Receives license-scoped change events from Organization Manager |

#### Kafka consumer threads

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_THREADS_LICENSE_USAGE` | Thread count for license usage consumer | `6` |
| `KAFKA_CONSUMER_THREADS_ORGANIZATION_EVENTS` | Thread count for organization events consumer | `2` |
| `KAFKA_CONSUMER_THREADS_LICENSE_EVENTS` | Thread count for license events consumer | `1` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after auth exception (seconds) | `10` |

***

### CAS lib configuration (SpiceDB)

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB gRPC port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX. | `CUSTOM` |

***

### FlowX SaaS connection (self-hosted only)

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX during self-hosted registration. Initialized with the `notset` sentinel so the OAuth client can start before the self-hosted client injects the real value at runtime. | `notset` |
| `FLOWX_LICENSE_KEY` | License key issued by FlowX for this self-hosted deployment. | - |
| `FLOWX_LICENSE_AUTHSERVERURL` | Auth endpoint provided by FlowX licensing. | - |
| `FLOWX_LICENSE_SERVERURL` | License API endpoint provided by FlowX licensing. | - |

> [!WARNING]
>
> These values are provided by FlowX during the organization registration process. Without them, the License service cannot validate the platform license or report usage data.
>
> Your network must allow outbound connectivity to the FlowX SaaS endpoints configured above.

### Usage upload tuning

The License service uploads usage records to FlowX SaaS once an hour, at a minute randomized per instance to spread load. These defaults work for most deployments and only need tuning for very large organizations:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SCHEDULER_USAGEUPLOAD_LOADFETCHSIZE` | Number of usage records loaded from the database per scheduler tick | `100` |
| `FLOWX_SCHEDULER_USAGEUPLOAD_UPLOADBATCHSIZE` | Number of usage records sent per upload request to FlowX SaaS | `500` |

***

### Logging configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |
| `LOGGING_LEVEL_LIQUIBASE` | Liquibase migration log level | `INFO` |

***

## Secrets management

The License service requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name | Description |
| - | - |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL database password |
| `SPRING_REDIS_PASSWORD` | Redis authentication password |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the License service:

```yaml theme={"dark"}
fullnameOverride: license

image:
  registry: <your-registry>
  repository: license

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/license
  SPRING_DATASOURCE_USERNAME: postgres

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # Security
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth
  SECURITY_OAUTH2_SAREALM: 00000002-0002-4002-8002-000000000002

  # Redis
  SPRING_REDIS_HOST: redis-master

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakLicenseClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/egress-s-redis: "true"
  flowx.ai/routing-name: "license"
  flowx.ai/prometheus-scrape: "license"
```

> [!NOTE]
>
> The `image.registry` and `image.repository` split applies to **5.9.4 and later**. To redirect every chart at once, use `global.imageRegistry`. See [Container images and registry](./setup-guides-overview#container-images-and-registry).

### Network policies

The License service requires network access to the following services:

| Service | Purpose | Pod Label |
| - | - | - |
| Kafka | Message broker communication | `flowx.ai/egress-s-kafka` |
| PostgreSQL | Primary data storage | `flowx.ai/egress-s-postgresql` |
| Redis | Caching and master election | `flowx.ai/egress-s-redis` |
| Keycloak | Authentication | `flowx.ai/egress-s-keycloak` |
| SpiceDB | Authorization | `flowx.ai/egress-s-spicedb` |

***

## Monitoring

The License service exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:

```yaml theme={"dark"}
podLabels:
  flowx.ai/prometheus-scrape: "license"
```

### Health endpoints

The health endpoints are served on the management port, `8081`, not the application port.

| Endpoint | Description |
| - | - |
| `/manage/actuator/health` | Health check endpoint |
| `/manage/actuator/metrics` | Prometheus metrics endpoint |
| `/manage/actuator/info` | App info endpoint |

***

## Verify your setup

> [!TIP]
>
> The License service pod is running and healthy: `kubectl get pods -l app.kubernetes.io/component=license`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://license:8081/manage/actuator/health`

> [!TIP]
>
> Database migrations completed successfully — check pod logs for `Liquibase: Update has been successful`

> [!TIP]
>
> SpiceDB connection is established — check pod logs for successful CAS client initialization

> [!TIP]
>
> Kafka topics `ai.flowx.license.usage.v1` and `ai.flowx.organization.events.v1` exist and the service can consume from them

***

## Ingress and CORS

The License service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/license` | `/` |

The path is set through `services.license.ingress.admin.path` (or `services.license.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer domain that issues browser requests against License. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

> [accordion] Database connection failures
>
> **Symptoms:** Service fails to start with database connection errors.
>
> **Solutions:**
>
> 1. Verify the `license` database exists in PostgreSQL
> 2. Check that the database user has appropriate permissions
> 3. Ensure network connectivity between the pod and PostgreSQL service
> 4. Verify the JDBC URL format is correct

> [accordion] SpiceDB connection failures
>
> **Symptoms:** Authorization errors or service fails to initialize CAS client.
>
> **Solutions:**
>
> 1. Verify SpiceDB is running and reachable at the configured host and port
> 2. Check that the SpiceDB token is correct
> 3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
> 4. Review pod logs for specific CAS client error messages

> [accordion] Kafka consumer issues
>
> **Symptoms:** License usage events or organization events not being processed.
>
> **Solutions:**
>
> 1. Verify Kafka bootstrap servers are reachable
> 2. Check that the `ai.flowx.license.usage.v1` and `ai.flowx.organization.events.v1` topics exist
> 3. Ensure the service has consumer permissions on the topics
> 4. Check consumer group offsets for lag

> [accordion] Service account authentication errors
>
> **Symptoms:** 401/403 errors when communicating with other FlowX services.
>
> **Solutions:**
>
> 1. Verify the Keycloak service account `flowx-license-sa` is properly configured
> 2. Check that client secrets match between configuration and Keycloak
> 3. Ensure the service account has the `view-users` client role assigned
> 4. Verify the service account realm UUID is correct

***

## Related resources

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Access Management](./access-management/access-management-overview)
>
> Configure roles and access rights

> [card] [SpiceDB Configuration](./spicedb)
>
> Fine-grained authorization setup

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup including License service account


# Migrate self-hosted FlowX.AI to the flowx-ai Helm chart
Source: https://docs.flowx.ai/5.9/setup-guides/migrate-to-flowx-ai-helm-chart

Move self-hosted FlowX.AI from the per-service or ai-platform Helm charts to the single flowx-ai chart, keeping your databases, files, and qdrant data.

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.6.** The `flowx-ai` chart deploys the core and AI services as one Helm release.

> [!NOTE]
>
> In FlowX.AI 5.9.6 you can still install the core services with one Helm chart per service. Starting with the next LTS release family, the `flowx-ai` chart is the only supported way to deploy the platform.

## Overview

The migration replaces your platform workloads once. Your databases, stored files, and indexed qdrant collections are kept.

| | Before | After |
| - | - | - |
| **Core services** | One Helm release per service, each from its own FlowX chart | `services.<name>` entries in one `flowx-ai` release |
| **AI services** | The `ai-platform` umbrella chart, one sub-chart per service | `services.<name>` entries in the same release, switched on by group |
| **Values** | One values file per release. A `global` value reaches only its own release. | One values tree with `global`, `groups`, and `services` |
| **Workload labels** | `app.kubernetes.io/name: <service>` | `app.kubernetes.io/name: flowx-ai`, `app.kubernetes.io/instance: <release>`, `app.kubernetes.io/component: <service>`. The bundled qdrant keeps `app.kubernetes.io/name: qdrant`. |

### What stays the same?

* **Your data.** Databases, files in the object store, and qdrant collections carry over.
* **Datastores.** The chart does not install, change, or delete PostgreSQL, MongoDB, Redis, Elasticsearch, Kafka, or your object store.
* **Persistent volumes.** The qdrant volume claims keep their names and are reattached. See [PVC behavior](#pvc-behavior).
* **Resource names.** Deployments, Services, and Ingresses keep their per-service names, except for the objects listed in [Other behavior changes](#other-behavior-changes).

### What changes?

The workload labels change, and they are part of `spec.selector`. Kubernetes does not allow the selector of an existing Deployment or StatefulSet to change, so `helm upgrade` cannot move a workload from the old charts to the new one. Every Deployment must be deleted and recreated. The qdrant StatefulSet must be recreated too, unless the `flowx-ai` release keeps the release name of your `ai-platform` release: qdrant keeps its `app` and `app.kubernetes.io/name` labels, so its selector changes only through `app.kubernetes.io/instance`.

> [!WARNING]
>
> The services are unavailable from the time you delete the old workloads until the new pods are ready. Plan a maintenance window.

The `flowx-ai` chart deploys the platform version it was released with, so the migration also upgrades every service to that version. Before the window, read the upgrade notes of every release between your current version and the chart's version, including the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).

***

## Before you begin

### Support for the previous charts

* **`ai-platform` umbrella chart:** retired. From FlowX.AI 5.9.6, the AI services ship in the `flowx-ai` chart.
* **Per-service charts:** move to the `flowx-ai` chart so that later upgrades are a single `helm upgrade` of one release.

### Prerequisites

* Helm 3 and `kubectl`, with access to the namespace that runs FlowX.AI
* `jq` and `yq` v4 (the mikefarah Go version), for the commands in this guide
* Pull access to the `flowx-ai` chart in the chart registry FlowX provides for your installation, at the chart version for your target release. The chart version is the platform release, for example `5.9.6`.
* For the default Gateway API mode: the Gateway API CRDs (`gateway.networking.k8s.io/v1`) in the cluster, a Gateway controller, and a Gateway named `default-gateway` with an `https` listener in the FlowX.AI namespace. The chart attaches its HTTPRoutes to that Gateway but does not create it. To use an existing Gateway, set its name and namespace in `gatewayName` and `gatewayNamespace` under `global.flowx.gateway.public`, `global.flowx.gateway.admin`, and `global.flowx.gateway.adminInstances`. Without the CRDs the chart does not render and fails with `Gateway API HTTPRoute CRD (gateway.networking.k8s.io/v1) not found`. To use Kubernetes Ingress instead, see [Check the global settings](#check-the-global-settings).
* Image pull secrets for every service in the namespace, AI services included. The chart applies `imagePullSecrets` to all pods.
* The `flowx-events-gateway-sa` client and its secret in your identity provider realm. events-gateway authenticates with it in the `flowx-ai` chart.
* If SpiceDB already runs in your environment: `spicedb-operator.enabled: false` and `spicedb-cluster.enabled: false` in your values. The chart installs both by default. To move that SpiceDB into the chart later, see [Move an existing SpiceDB into the chart](#move-an-existing-spicedb-into-the-chart).
* A backup of PostgreSQL, MongoDB, the object store, and the qdrant collections, taken right before the maintenance window. It is your recovery point for a rollback.
* A maintenance window. Measure the delete-to-ready time in a test environment first.

The commands in this guide read the namespace from `NS`. Set it once in your shell:

```bash theme={"dark"}
export NS={your-flowx-namespace}
```

***

## Service groups

Every service in the chart belongs to exactly one group, set in `services.<name>.group`. A service with no group belongs to `base`. You turn a whole group on or off under `groups`. The groups replace the `devtime` and `runtime` flags of the `ai-platform` umbrella chart.

| Group | Purpose | Members |
| - | - | - |
| `core` | FlowX.AI platform services | admin, advancing-controller, application-manager, audit-core, authorization-system, cms-core, data-search, designer, document-plugin, email-gateway, events-gateway, file-gateway, integration-designer, license, nosql-db-runner, notification-plugin, organization-manager, process-engine, runtime-manager, scheduler-core, solution-portal, task-management-plugin, webhook-gateway |
| `base` | The AI foundation that the other AI services call | ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and the bundled qdrant |
| `devtime` | AI assistance in FlowX Designer | ai-analyst, ai-architect, ai-assistant, ai-designer, ai-developer, kb-enrichment, planner |
| `runtime` | AI capabilities used by running processes | agent-builder, data-privacy, doc-converter, evals-judge, speech-to-text, web-crawler |

The qdrant vector database follows the `base` group. `qdrant.enabled` overrides the group when you set it: `true` deploys qdrant with `base` off, and `false` leaves it out with `base` on.

### How do the switches combine?

The chart decides whether a service runs in this order:

1. `services.<name>.enabled`, if you set it, wins.
2. Otherwise, `groups.<group>.enabled` applies. Set it for every group in your values.

For example, these values turn on the `runtime` group but leave out speech-to-text:

```yaml theme={"dark"}
groups:
  runtime:
    enabled: true
services:
  speech-to-text:
    enabled: false
```

### Which group combinations are valid?

Don't rely on the chart's group defaults. Set all four group flags in your values, using one of these combinations:

| To install | `core` | `base` | `devtime` | `runtime` |
| - | - | - | - | - |
| Core services only | `true` | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `true` | `false` | `true` |
| All services | `true` | `true` | `true` | `true` |

The `devtime` and `runtime` services call the `base` services, so turn `base` on whenever either of them is on. The chart doesn't check this for you. qdrant is left out together with `base`.

### How do the umbrella flags map?

| `ai-platform` umbrella | `flowx-ai` chart |
| - | - |
| `devtime.enabled` | `groups.devtime.enabled` |
| `runtime.enabled` | `groups.runtime.enabled` |
| `runtime.<name>.enabled` | `services.<name>.enabled` |
| Base services, always on | `groups.base.enabled`, required when `devtime` or `runtime` is on, or `services.<name>.enabled` per service |

If your values still contain a top-level `devtime` or `runtime` key, the chart fails to render with the message `top-level devtime/runtime flags moved`. This is intentional: left in place, those keys would be ignored and the groups would keep their chart defaults.

***

## Convert your values

The `flowx-ai` chart reads one values tree. Most of your settings go under three top-level keys:

* `global`: settings shared by every service, such as domain, identity provider, datastore servers, registry, and ingress
* `groups`: turns service groups on and off. See [Service groups](#service-groups).
* `services.<name>`: the settings of one service

The bundled components keep their own top-level keys: `qdrant`, `spicedb-operator`, `spicedb-cluster`, and `dataSync`.

The chart validates the shape of your values. It fails to render if it finds a service key at the top level instead of under `services`, a top-level `image` or `podLabels` key, or a group that the chart does not declare.

The per-service charts and the `flowx-ai` chart use the same values structure for a service, so most keys inside a service keep their names. The work is mostly moving keys and removing duplicates.

### From the per-service charts

**1. Merge the global blocks**

Take the `global` block of each release's current values and merge them into one `global` block. Where two releases set the same key to different values, choose the value that is correct for the whole platform.

**2. Move each service's keys under services**

Move every other top-level key of a service's values file under `services.<name>`. For example, `resources` in `values-application-manager.yaml` becomes `services.application-manager.resources`:

```yaml theme={"dark"}
# Before: values-application-manager.yaml
replicaCount: 2
resources:
  limits:
    memory: 2Gi

# After: one values file for the flowx-ai release
services:
  application-manager:
    replicaCount: 2
    resources:
      limits:
        memory: 2Gi
```

**3. Remove image tag overrides**

Delete `image.tag` from each service's values. The service version moves to `services.<name>.version`, which the chart pins to the platform release of the chart version. A leftover tag override keeps that service on its old version while the rest of the platform moves.

### From the ai-platform umbrella chart

**1. Move each service key under services**

Move each root-level service key under `services`. For example, `embedder:` becomes `services.embedder:`.

**2. Replace the devtime and runtime flags**

Use the mapping in [How do the umbrella flags map?](#how-do-the-umbrella-flags-map).

**3. Merge the global block**

Merge the umbrella's `global` block into the shared `global` block.

### Check the global settings

In the old layout, a `global` value reached only the services of its own release. In the `flowx-ai` chart, a `global` value reaches every service. Review these cases before you render:

* **Ingress or Gateway API.** The chart routes traffic through Gateway API by default, and `global.flowx.ingress.enabled` defaults to `false`. To keep Kubernetes Ingress, set `global.flowx.ingress.enabled: true`, and set `global.flowx.gateway.enabled: false` if the cluster has no Gateway API CRDs: turning Ingress on does not turn the Gateway API routes off. A service then gets an Ingress only when its own `ingress.enabled` is also on. Ingress mode does not strip path prefixes, so services served under a prefix, such as `/license`, `/ai`, and `/integration`, need regex paths with `rewrite-target` annotations. With Ingress on, five AI services also get an admin Ingress by default: ai-gateway, doc-converter, data-privacy, speech-to-text, and web-crawler. Set `ingress.admin.enabled: false` on any of them that has none today.
* **`global.env`, `global.podAnnotations`, and `global.replicaCount`.** If these came from your core releases, they now also apply to the AI services, for example a Java agent annotation on Python pods. Move them onto the core services that need them.
* **Values set to `null` to unset a default.** The chart validates values against one schema for all services and rejects some of these. Delete them: the result is the same when the chart sets no default for that key.

### Choose the release name

The release name becomes part of the name of the CA certificates init container. It is also passed to doc-parser, doc-converter, evals-judge, data-privacy, speech-to-text, and web-crawler in the `GRPC_HOST_RESOLVER_HELM_CHART` environment variable, for service discovery.

Choose a name that no other release in the namespace uses, and keep it for the life of the installation. A name that contains `flowx-ai`, such as `flowx-ai`, keeps the generated names short, because the chart does not append `-flowx-ai` to it.

### Render and compare

Render the chart with your new values before the maintenance window, and compare the result with what runs today. Use the chart reference from your FlowX chart registry, and the platform release as the chart version:

```bash theme={"dark"}
helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml

# Environment variables per Deployment, today
kubectl -n "$NS" get deploy -o json | jq -r '.items[] | .metadata.name as $n
  | .spec.template.spec.containers[0].env[]? | "\($n)\t\(.name)=\(.value // "")"' \
  | sort > env-live.txt

# Environment variables per Deployment, after the migration
yq -o json 'select(.kind == "Deployment")' rendered.yaml | jq -rs '.[] | .metadata.name as $n
  | .spec.template.spec.containers[0].env[]? | "\($n)\t\(.name)=\(.value // "")"' \
  | sort > env-new.txt

diff env-live.txt env-new.txt
```

Every line in the diff is a behavior change. Resolve each one, or confirm that you expect it, before you continue. Pay particular attention to variables that contain `BUCKET`, `URL`, and `REALM`.

The comparison covers inline `env` values of the first container only. Compare variables that come from `valueFrom` or `envFrom` (Secrets and ConfigMaps), and any other containers, separately.

***

## Migrate S3 buckets

The `flowx-ai` chart sets no bucket names and no bucket prefixes. Carry over the names your services use today, or they start writing to new, empty buckets.

> [!WARNING]
>
> A wrong bucket name does not always fail loudly. A service that is allowed to create buckets creates a missing bucket on first use. New files go to the new bucket, and files stored under the old name are no longer found. Nothing is deleted, but uploaded documents, media library assets, and knowledge base files appear to be missing.

### How do bucket names reach a service?

If a value is set, the chart renders it as an environment variable, such as `APPLICATION_FILE_STORAGE_S3_BUCKET_PREFIX` as rendered by the chart. If it is not set, the chart renders nothing, and the service falls back to the default built into its image. Several of those image defaults are empty.

A service that uses a prefix derives its bucket names from it: `<prefix>-<file type>` for regular uploads, and `<prefix>` alone for date-partitioned files. Dots become dashes.

### Bucket keys and previous defaults

The following table lists every bucket setting and the name a previous chart set when you did not.

| Service | Key in `flowx-ai` values | Per-service chart default | `ai-platform` umbrella default |
| - | - | - | - |
| application-manager | `services.application-manager.component.s3.main.bucketPrefix` | None (image default) | Not in this chart |
| runtime-manager | `services.runtime-manager.component.s3.main.bucketPrefix` | None (image default) | Not in this chart |
| integration-designer | `services.integration-designer.component.s3.main.bucketPrefix` | None (image default) | Not in this chart |
| document-plugin | `services.document-plugin.component.s3.main.bucketPrefix` | `flowx-dev` | Not in this chart |
| notification-plugin | `services.notification-plugin.component.s3.main.bucketPrefix` | `flowx-dev` | Not in this chart |
| cms-core, public | `services.cms-core.component.s3.public.bucketName` and `.rootDirectory` | `dev-env-media-library`, root directory `pr` | Not in this chart |
| cms-core, private | `services.cms-core.component.s3.private.bucketName` and `.rootDirectory` | `cms-private-bucket`, root directory `devtest` | Not in this chart |
| agent-builder | `services.agent-builder.component.s3.workflows.bucketName` | `workflows-bucket` | `workflows-bucket` |
| doc-parser | `services.doc-parser.component.s3.documents.bucketName` | `email-ingest` | `email-ingest` |
| kb-enrichment | `services.kb-enrichment.component.s3.applicationFileStorage.bucketName` | `kb-enrichment-bucket` | `kb-enrichment-bucket` |
| knowledgebase-indexer-v2 | `services.knowledgebase-indexer-v2.component.s3.applicationFileStorage.bucketName` | `kb-enrichment-bucket` (shared with kb-enrichment) | `kb-enrichment-bucket` |
| data-privacy | `services.data-privacy.component.s3.documents.bucketName` | `data-privacy-bucket` | `data-privacy-bucket` |

What this means for your previous charts:

* **From the per-service charts:** document-plugin, notification-plugin, cms-core, and the AI services in the table had bucket names set by their chart. The `flowx-ai` chart does not set them, so set them yourself, even if you never changed them.
* **From the `ai-platform` umbrella chart:** set the AI bucket names explicitly. Most AI image defaults are empty.
* **Services marked None:** they used their image default, and keep it if you leave the key unset.

### Step 1: Find the names in use

List the bucket and root directory variables that each running service uses:

```bash theme={"dark"}
kubectl -n "$NS" get deploy -o json | jq -r '.items[] | .metadata.name as $n
  | .spec.template.spec.containers[0].env[]?
  | select(.name | test("BUCKET|ROOT"))
  | "\($n)\t\(.name)=\(.value)"'
```

The filter is broad on purpose, so it can also list unrelated variables, such as a root log level. A service that is missing from the output uses its image default. In your object store, confirm which buckets hold the data, for example with the MinIO console, `mc ls`, or `aws s3 ls`.

### Step 2: Set the names in your values

Set every name from step 1 under the keys in the table:

```yaml theme={"dark"}
services:
  application-manager:
    component:
      s3:
        main:
          bucketPrefix: "{your-bucket-prefix}"
  cms-core:
    component:
      s3:
        public:
          bucketName: "{your-public-media-bucket}"
          rootDirectory: "{your-public-root-directory}"
        private:
          bucketName: "{your-private-media-bucket}"
          rootDirectory: "{your-private-root-directory}"
  doc-parser:
    component:
      s3:
        documents:
          bucketName: "{your-documents-bucket}"
```

Leave a key unset only for a service that should keep its image default. If an earlier values file sets a name you want to clear, remove the key from that file. Do not set it to `null`.

Two differences from the per-service charts need attention when you copy values across:

* **Entry name.** The per-service core charts named the S3 entry `minio`. In `flowx-ai` the entry is `main`. Set the prefix under `component.s3.main` and remove the `minio` entry: if both are present, the chart fails to render with `Only one s3 entry may omit an alias`.
* **cms-core root directory.** The per-service chart also set a `rootDirectory` for each cms-core bucket. Files are stored under that directory, so carry over `rootDirectory` together with `bucketName`.

If you set the document-plugin prefix with the older `MINIO_BUCKET_PREFIX` environment variable, move it to `bucketPrefix`. document-plugin reads `MINIO_BUCKET_PREFIX` only as a fallback, so a prefix that the chart renders takes precedence.

Before the maintenance window, check the names in the render:

```bash theme={"dark"}
yq -o json 'select(.kind == "Deployment")' rendered.yaml | jq -rs '.[] | .metadata.name as $n
  | .spec.template.spec.containers[0].env[]?
  | select(.name | test("BUCKET|ROOT"))
  | "\($n)\t\(.name)=\(.value)"'
```

Every name from step 1 must appear with the same value.

### Step 3: Verify the bucket names after the cutover

**1. Check the running values**

Run the command from step 1 again and check each value.

**2. Open files uploaded before the migration**

Open a process attachment, a media library asset, a notification template asset, and a knowledge base document.

**3. Check the logs**

Look for `bucket not found` errors in the service logs. They point to a name mismatch.

> [!WARNING]
>
> Do not rename buckets or change root directories as part of this migration. The databases reference stored files by bucket and path, so keep every bucket name, prefix, and `rootDirectory` exactly as it is today.

***

## PVC behavior

qdrant is the only workload in the chart that stores data on a PersistentVolumeClaim (PVC). Its volumes survive the cutover and are reattached to the new StatefulSet, as long as the conditions in this section hold.

If the `base` group is off and `qdrant.enabled` is not set, or if you set `qdrant.enabled: false`, the chart deploys no qdrant StatefulSet. Existing qdrant claims then stay in the namespace unused, until you delete them or turn qdrant back on.

### Volumes the chart uses

| PVC | Mounted by | Default size | Values key |
| - | - | - | - |
| `qdrant-storage-qdrant-0` | qdrant, collection data | `30Gi` | `qdrant.persistence` |
| `qdrant-snapshots-qdrant-0` | qdrant, snapshots | `30Gi` | `qdrant.snapshotPersistence` |

Databases, Kafka, and the object store run in their own releases. The chart does not create, change, or delete their volumes.

### Why do the volumes survive?

* **PVC names do not change.** A StatefulSet names each claim `<volumeClaimTemplate>-<StatefulSet name>-<ordinal>`. The chart names the StatefulSet `qdrant` through `qdrant.fullnameOverride`, so the new StatefulSet requests the same claims and binds the existing volumes.
* **Deleting the StatefulSet keeps its PVCs.** Kubernetes applies the StatefulSet's `persistentVolumeClaimRetentionPolicy`. The qdrant chart does not set it, so the default `whenDeleted: Retain` applies. The StorageClass `reclaimPolicy` plays no part, because the PVCs are never deleted and the volumes are never released.
* **`helm uninstall` keeps them too.** Helm deletes only the objects in the release manifest, and PVCs that a StatefulSet creates from its templates are not in the manifest.

> [!WARNING]
>
> Do not delete the qdrant StatefulSet with `--cascade=orphan`. That option keeps the old pod running, but the new StatefulSet has a different selector and cannot adopt it, so it cannot start its own pod either.

### Before the cutover: check the volumes

**1. Confirm the claim names**

```bash theme={"dark"}
kubectl -n "$NS" get pvc | grep qdrant
```

Expect `qdrant-storage-qdrant-0` and, if snapshots were on, `qdrant-snapshots-qdrant-0`.

**2. Check the retention policy**

```bash theme={"dark"}
kubectl -n "$NS" get statefulset -o custom-columns=NAME:.metadata.name,WHEN_DELETED:.spec.persistentVolumeClaimRetentionPolicy.whenDeleted
```

An empty value or `Retain` is safe. If the value is `Delete`, the PVCs are deleted together with the StatefulSet. Change the policy to `Retain` before the cutover:

```bash theme={"dark"}
kubectl -n "$NS" patch statefulset qdrant --type merge \
  -p '{"spec":{"persistentVolumeClaimRetentionPolicy":{"whenDeleted":"Retain"}}}'
```

**3. Compare sizes and StorageClass**

Compare your existing claims with `qdrant.persistence` and `qdrant.snapshotPersistence`. The StatefulSet reuses an existing claim as is, whatever the template says, but matching values keep the release definition accurate.

**4. Decide on a snapshots claim**

If your installation never had a snapshots claim, decide whether you want one. With `qdrant.snapshotPersistence.enabled: true`, the default, the chart creates a new `30Gi` claim. Set it to `false` to keep the current layout.

### What if your claim names are different?

If the first check shows other names, for example because the qdrant StatefulSet carried a release prefix, the new StatefulSet does not find your volumes. It creates new, empty claims instead, and the AI services lose their indexed collections.

Before the cutover, do one of the following, and test it in a non-production environment first:

* Set `qdrant.fullnameOverride` to the existing StatefulSet name, and set `global.flowx.qdrant.servers.flowx.grpc.host` to that name's headless Service, `{existing-name}-headless`, so that both the claim names and the service address match. The chart default is `qdrant-headless`.
* Take a qdrant snapshot of each collection, migrate with new claims, and restore the snapshots afterwards.

### After the cutover

Confirm that the new pod uses the existing claims and that no new claim appeared:

```bash theme={"dark"}
kubectl -n "$NS" get pvc | grep qdrant
kubectl -n "$NS" get pod qdrant-0 -o jsonpath='{.spec.volumes[*].persistentVolumeClaim.claimName}'
```

The `AGE` column of each claim must show its original age.

***

## Other behavior changes

Review these changes against your installation before the cutover. Most need no action.

| Area | Change | What to do |
| - | - | - |
| **Labels** | `app.kubernetes.io/name` is `flowx-ai` on every platform service object, and the service name moves to `app.kubernetes.io/component`. `app.kubernetes.io/version` is no longer set on those objects. The bundled qdrant keeps its `app.kubernetes.io/name: qdrant` and `app.kubernetes.io/version` labels. | Update dashboards, alerts, network policies, and scripts that select on the old labels. |
| **Renamed objects** | The release ConfigMap is `flowx-ai-release` instead of `flowx-release`. The data-sync Job is named `data-sync-<chart-version>`, with dots in the version replaced by dashes, such as `data-sync-5-9-6`. | Delete the old `flowx-release` ConfigMap and data-sync Job after the cutover, if your deploy tool does not prune them. |
| **Web app rename** | The `react-saas` web app is renamed `solution-portal`, so its objects get the new name. With Ingress on, the chart also renders a transitional `react-saas-public` Ingress on an unused path, so that the renamed Ingress can take over the host. `migrations.reactSaasIngressOverride` controls it and is on by default. | Remove the old `react-saas` workload with the other old workloads. If an old release still owns a `react-saas-public` Ingress, remove it or hand it over to the `flowx-ai` release, or the install fails on ownership. |
| **SpiceDB** | The chart installs the SpiceDB operator and a SpiceDB cluster by default. | If SpiceDB already runs in your environment, set `spicedb-operator.enabled: false` and `spicedb-cluster.enabled: false`. Never run two SpiceDB clusters on one datastore. To move it into the chart later, see [Move an existing SpiceDB into the chart](#move-an-existing-spicedb-into-the-chart). |
| **Identity provider clients** | events-gateway authenticates with its own client, `flowx-events-gateway-sa`. | Make sure the client and its secret exist in your realm. Without it, real-time updates fail with `403`. |
| **Identity provider URL** | Services use one identity provider URL from `global.flowx.idp`. FlowX Designer and the web app take their public URL from their own client entry. | If you point the global URL at an in-cluster address, set the public URL on the `designer` and `solution-portal` clients. Otherwise make sure pods can reach the public URL. |
| **Ingress routing** | In Ingress mode the chart does not strip path prefixes. Gateway API mode does, through `stripPrefix`. | In Ingress mode, add regex paths with `rewrite-target` annotations for services served under a prefix, such as `/license`, `/ai`, and `/integration`. Or use Gateway API mode. |
| **Ingress TLS** | An Ingress gets TLS when `tls` is `"true"`, which names the secret `<host>-tls`, or when `ingress.<type>.extraTls` is set. `global.flowx.ingress.<type>.tls` overrides the per-service `tls` value. | `<host>-tls` suits cert-manager. With a wildcard certificate, set `extraTls` on each service with your secret name. |
| **Image pull secrets** | The chart applies the global image pull secrets to every pod, AI services included. | Create the pull secrets in the namespace and list them in your `global` values. |
| **Probes** | Probe timings are set per service by the chart, and some AI services have no probes. | If you tuned probes in your previous values, compare `livenessProbe`, `readinessProbe`, and `startupProbe` in `rendered.yaml` with your running Deployments. |
| **CA certificates init container** | Services that import a certificate run a CA certificates init container that requests `100m` CPU and `128Mi` memory. By default these are admin, audit-core, data-search, document-plugin, and process-engine, which import the Elasticsearch CA. | Check namespace quotas if they are tight. |
| **Document storage** | The chart sets the file partition strategy of document-plugin and integration-designer to `PROCESS_DATE`, so new files are stored in date-partitioned paths. The per-service charts did not set it, and the service default is `NONE`. Existing files stay readable: each service stores a file's full path when it saves the file and reads it back from that path. With `PROCESS_DATE`, document-plugin rejects Kafka document requests that have no `processStartDate` header and sends an error to the reply topic. The process engine sends this header. | If you migrate from the per-service charts, expect `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY=PROCESS_DATE`, as rendered by the chart, in the render diff for these two services. If your own apps publish directly to the document-plugin topics, make sure they send the `processStartDate` header. To keep the previous layout, set `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY: "NONE"` under `services.document-plugin.env` and `services.integration-designer.env`. |

***

## Run the cutover

The cutover replaces the old releases with the `flowx-ai` release. How you carry it out depends on your deployment tooling: this section describes what the cutover must achieve.

Complete [Convert your values](#convert-your-values), [Migrate S3 buckets](#migrate-s3-buckets), the checks in [PVC behavior](#pvc-behavior), and the review of [Other behavior changes](#other-behavior-changes) first.

### Prepare

**1. Freeze the namespace**

Freeze all other changes to the namespace, so that the cutover changes only the charts.

**2. Take the backups**

Take the backups listed in [Prerequisites](#prerequisites).

**3. Keep the old definitions**

Keep a copy of the old releases' values and rendered manifests. You need them to [roll back](#roll-back).

**4. Rehearse**

Measure how long the cutover takes in a test environment, and size the maintenance window from it.

### What must the cutover do?

**1. Stop the old releases from managing their workloads**

Make sure nothing recreates the old Deployments or StatefulSet while you replace them, for example an automated sync or a scheduled pipeline.

**2. Remove the old Deployments and the qdrant StatefulSet**

Their selectors cannot change, so they must be deleted before the new release can create its own. **The outage starts here.**

* Remove only the platform workloads. If your databases, Kafka, or object store run in the same namespace, make sure their StatefulSets are not caught by the same operation.
* Delete the qdrant StatefulSet with normal cascading deletion, not as an orphan. See [PVC behavior](#pvc-behavior). If the `flowx-ai` release keeps the release name of your `ai-platform` release, the qdrant selector does not change and the StatefulSet can stay.

**3. Hand over or remove the other objects of the old releases**

Services, Ingresses, ServiceAccounts, ConfigMaps, and RBAC objects keep their names in `flowx-ai`, but Helm refuses to install an object that another release owns. Either remove them with the old releases, or transfer their ownership to the new release.

Helm reads ownership from the annotations `meta.helm.sh/release-name` and `meta.helm.sh/release-namespace` and the label `app.kubernetes.io/managed-by: Helm`. To hand an object over, set the two annotations to the `flowx-ai` release name and namespace.

**4. Preserve what the new release does not create**

If the old releases created Secrets or ConfigMaps through their values that your services still need, recreate them outside the old releases, or make sure your `flowx-ai` values create them.

**5. Install the flowx-ai release**

Install it with your new values. The outage ends when every Deployment is available and the qdrant pod has reattached its volumes.

**6. Remove objects that changed name**

The release ConfigMap `flowx-release` is replaced by `flowx-ai-release`, and the data-sync Job gets a new name that includes the chart version. Jobs are immutable, so the old data-sync Job is not updated in place. After the cutover, delete the old objects if your tooling does not prune them.

> [!TIP]
>
> With plain Helm, the simplest cutover is: recreate outside Helm any Secrets the old releases created, run `helm uninstall` for each old release (the qdrant claims are kept), then run `helm install {your-release-name} {flowx-ai-chart-reference} --version {chart-version} -n "$NS" -f values-flowx-ai.yaml`.

> [!NOTE]
>
> Do not leave a force-replace or recreate option turned on permanently in your tooling to get through the removal step. It would delete and recreate workloads on every later deployment, not only during the cutover.

***

## Verify the migration

Run these checks right after the cutover, and again after the first day of normal use:

* Every Deployment is available, and only the services of your enabled groups run: `kubectl -n "$NS" get deploy`.
* No workload from an old release remains: `kubectl -n "$NS" get deploy,statefulset -L app.kubernetes.io/name,app.kubernetes.io/instance` shows `flowx-ai` on every platform workload and `qdrant` on the qdrant StatefulSet, all with your release name as the instance.
* The qdrant pod uses the original claims. See [After the cutover](#after-the-cutover).
* The bucket variables match the names you set. See [Step 3: Verify the bucket names after the cutover](#step-3-verify-the-bucket-names-after-the-cutover).
* You can sign in to FlowX Designer and to a deployed app.
* A process instance starts, and its UI updates in real time. This exercises events-gateway.
* A file uploaded before the migration opens, and a new upload succeeds.
* If AI groups are on, an AI feature answers, for example a chat through ai-gateway or a knowledge base query.
* Scheduled jobs run at their next trigger.
* The service logs show no `bucket not found`, `401`, `403`, or connection errors that were not there before.
* Your monitoring still finds the services. Dashboards, alerts, and scripts that select on `app.kubernetes.io/name=<service>` must now select on `app.kubernetes.io/component=<service>`.

***

## Roll back

A rollback crosses the same selector change in the other direction, so it is also a delete and recreate. A Helm release history rollback cannot do it, because the old and new workloads belong to different releases.

The qdrant PVCs were never deleted, so the old releases reattach them. If the new services changed data that the old versions cannot read, restore the backup you took before the window.

**1. Remove the flowx-ai release**

Stop your tooling from managing the `flowx-ai` release, then run `helm uninstall` for it, or remove its workloads and the objects it owns. The qdrant claims are kept. If the release installed the SpiceDB operator and cluster, they are removed with it: make sure the old releases bring back the SpiceDB setup you ran before.

**2. Restore the datastores if needed**

Restore PostgreSQL, MongoDB, and the object store from the backup.

**3. Reinstall the old releases**

Use their previous values, at the chart versions you ran before.

**4. Check qdrant**

Confirm that the qdrant pod reattached its claims. If you need to restore the qdrant collections, restore them from the snapshots now, while qdrant is running.

> [!NOTE]
>
> Files written while `flowx-ai` was running go to the buckets that its values named. If those names differed from the old ones, the old releases cannot see those files after a rollback. Carrying over the bucket names as described in [Migrate S3 buckets](#migrate-s3-buckets) avoids this. document-plugin and integration-designer also stored new files in date-partitioned paths. Test the rollback in a non-production environment before you rely on it.

Keep the old values and manifests until you have signed off the migration.

***

## Move an existing SpiceDB into the chart

If SpiceDB runs as its own Helm releases or Argo CD Applications, with the SpiceDB operator and the SpiceDB cluster installed separately from FlowX.AI, you can move it into the operator and cluster that the `flowx-ai` chart bundles. Skip this section if the chart you migrated from already installed SpiceDB.

> [!WARNING]
>
> Move SpiceDB in its own maintenance window, after the cutover to the `flowx-ai` chart has run for a while. Every permission check fails while SpiceDB is down, so the move is a platform outage. Never combine it with the cutover.

### How the move keeps your data

SpiceDB keeps no state in its pods. Every relationship and the permission schema live in the PostgreSQL datastore that its `datastore_uri` points at. The move copies no data: the chart's SpiceDB cluster serves the same datastore that the old one did.

Before the operator starts any SpiceDB pods for a cluster, it runs a migration Job that brings the datastore to the SpiceDB version you set. At the version the datastore already runs, the Job changes nothing. Migrations only go forward, so move SpiceDB at the version you run today and upgrade it afterwards. That also keeps a rollback free of data loss.

| | Separate installation | `flowx-ai` chart |
| - | - | - |
| **Operator** | Its own release | Deployment in the FlowX.AI namespace, watching only that namespace |
| **Cluster** | Named after its release, often `spicedb` | `SpiceDBCluster` named `spicedb-cluster` |
| **Address the services use** | `{old-cluster-name}:50051` | `spicedb-cluster:50051`, from `global.flowx.spicedb.servers.flowx.host` |
| **CRD** | Installed by the old operator release | Shipped in the operator subchart. Helm installs it only when it's missing and never upgrades or deletes it |
| **Versions** | Whatever you pinned | SpiceDB v1.52.0 and operator v1.25.1. The operator can migrate a PostgreSQL datastore from any version between v1.2.0 and v1.52.0 |
| **Credentials** | A Secret with `preshared_key` and `datastore_uri` | The same keys, in a Secret named `spicedb` |

### Before the window

**1. Record what runs today**

You need these values for a rollback:

```bash theme={"dark"}
kubectl -n "$NS" get spicedbcluster \
  -o custom-columns=NAME:.metadata.name,VERSION:.status.version.name,MIGRATION:.status.migration
kubectl get deploy -A | grep -i spicedb-operator
mkdir -p rollback
kubectl -n "$NS" get spicedbcluster {old-cluster-name} -o yaml > rollback/old-spicedbcluster.yaml
helm -n "$NS" get values {old-operator-release} > rollback/old-operator-values.yaml
helm -n "$NS" get values {old-cluster-release} > rollback/old-cluster-values.yaml
```

**2. Choose the version for the move**

If `VERSION` is `v1.52.0`, there's nothing to set. If it's older, pin the chart's cluster to it:

```yaml theme={"dark"}
spicedb-cluster:
  version: {running-version}
```

A cluster newer than v1.52.0, or an operator newer than v1.25.1, can't move into this chart version.

**3. Protect the CRD**

Check whether the old operator release manages the `spicedbclusters.authzed.com` CRD as a regular resource:

```bash theme={"dark"}
helm -n "$NS" get manifest {old-operator-release} | grep -c CustomResourceDefinition
```

`0` means the CRD isn't part of the release's manifest, and uninstalling the release leaves it in place. Any other result means uninstalling the release deletes the CRD, and with it every `SpiceDBCluster` in the cluster. In that case, keep it before the window:

```bash theme={"dark"}
kubectl annotate crd spicedbclusters.authzed.com helm.sh/resource-policy=keep
```

An Argo CD Application that manages the CRD deletes it on a cascading delete.

**4. Prepare the Secret**

The chart reads a Secret named `spicedb` with the keys `preshared_key` and `datastore_uri`. If your Secret has another name, create `spicedb` with the same values. Don't rotate the preshared key in this window.

**5. Check the datastore user and the images**

The migration Job needs a datastore user that can create and alter tables and indexes. Make sure the namespace can pull the `spicedb` and `spicedb-operator` images from your registry.

**6. Rehearse the backup**

Back up the SpiceDB PostgreSQL database and restore it on a copy. That backup is your recovery point.

### Run the move

**1. Cut over with SpiceDB outside the chart**

Do this in an earlier window, as part of the cutover, with these values:

```yaml theme={"dark"}
spicedb-operator:
  enabled: false
spicedb-cluster:
  enabled: false
global:
  flowx:
    spicedb:
      servers:
        flowx:
          host: {old-cluster-name}
```

**2. Apply the chart's CRD**

Take `crds/authzed.com_spicedbclusters.yaml` from the `spicedb-operator` subchart in the `flowx-ai` chart and apply it. This is safe while the old operator runs:

```bash theme={"dark"}
kubectl apply --server-side -f authzed.com_spicedbclusters.yaml
```

**3. Back up the datastore**

Back up the SpiceDB PostgreSQL database now. A rollback restores this state.

**4. Delete the old cluster**

Delete it while the old operator still runs, so the operator removes its pods and Service. The outage starts here.

```bash theme={"dark"}
helm -n "$NS" uninstall {old-cluster-release}
kubectl -n "$NS" get spicedbcluster,deploy,svc | grep -i spicedb
```

The second command must return nothing from the old cluster.

**5. Remove the old operator and keep the CRD**

Uninstall the old operator release. If you installed the upstream operator bundle, delete its Deployment, ServiceAccount, roles, and bindings by name, and never delete the bundle file as a whole, because it contains the CRD. With Argo CD, delete the Application without cascading, then delete the Deployment and roles by hand.

```bash theme={"dark"}
kubectl get crd spicedbclusters.authzed.com
kubectl get deploy -A | grep -i spicedb-operator
```

The CRD must still exist, and no operator Deployment may remain.

**6. Turn on SpiceDB in the chart**

Upgrade the release with:

```yaml theme={"dark"}
spicedb-operator:
  enabled: true
spicedb-cluster:
  enabled: true
  version: {running-version}   # omit when it's v1.52.0
  replicas: {replicas-you-ran-before}
global:
  flowx:
    spicedb:
      servers:
        flowx:
          host: spicedb-cluster
```

**7. Wait for the migration Job**

Nothing else starts until the Job completes:

```bash theme={"dark"}
kubectl -n "$NS" get spicedbcluster spicedb-cluster -o yaml \
  | yq '.status | {"conditions": .conditions, "migration": .migration, "version": .version}'
kubectl -n "$NS" get jobs | grep spicedb-cluster
```

The move is through when the cluster no longer reports a migration in progress, `status.migration` matches what you recorded, and the `spicedb-cluster` Deployment exists and is ready. If the Job fails, read its log: a wrong `datastore_uri`, an `sslmode` mismatch, or a datastore user without rights to change tables are the usual causes. Fix the cause and let the operator run the Job again. Don't delete the cluster, and don't start the old cluster on the same datastore.

**8. Check the services**

Changing the host restarts the services that connect to SpiceDB. Check that every pod runs and that authorization-system logs no SpiceDB errors, then sign in to FlowX.AI Designer and do one action that needs a permission. The outage ends here.

Keep the `rollback` folder and the backup until you sign off. To upgrade SpiceDB to v1.52.0 afterwards, remove the `version` pin. The operator then runs a migration Job for each step, which you watch the same way.

### Roll back the move

If the migration Job can't pass in the window, or the services can't authorize after the move, roll back:

**1. Turn SpiceDB off in the chart again**

Apply the values from the first step of the move, with the host set back to `{old-cluster-name}`. The chart's cluster and operator are removed.

**2. Restore the datastore if the schema moved**

Compare `status.migration` from the migration Job step with the value you recorded before the window. If it changed, the old SpiceDB version can't start on the datastore: restore the backup you took in the window. Anything written after that backup is lost. If it didn't change, skip the restore.

**3. Reinstall the old operator and cluster**

Use the values in the `rollback` folder, at the versions you ran before. Wait for the old operator's migration Job, then check the services as in the last step of the move.

> [!WARNING]
>
> Never delete the `spicedbclusters.authzed.com` CRD, never run two operators that watch the same namespace or two SpiceDB clusters on one datastore, and never delete the migration Job, the cluster, or the operator while a migration runs.

***

## Troubleshooting

> [accordion] The render fails with top-level devtime/runtime flags moved
>
> Your values still contain the `devtime` or `runtime` key of the `ai-platform` umbrella chart. Replace them with `groups.devtime.enabled`, `groups.runtime.enabled`, and `services.<name>.enabled`, as described in [How do the umbrella flags map?](#how-do-the-umbrella-flags-map).

> [accordion] The render fails with Only one s3 entry may omit an alias
>
> A service has both the old `minio` S3 entry and the new `main` entry. Move the settings to `component.s3.main` and remove the `minio` entry.

> [accordion] The install fails with invalid ownership metadata
>
> An object from an old release still exists, and Helm will not take it over. Remove it, or hand it over by setting the `meta.helm.sh/release-name` and `meta.helm.sh/release-namespace` annotations to the `flowx-ai` release. See [What must the cutover do?](#what-must-the-cutover-do).

> [accordion] The upgrade fails with field is immutable
>
> You ran `helm upgrade` against an existing Deployment or StatefulSet whose selector the new chart changes. Delete the old workload first, as described in [What must the cutover do?](#what-must-the-cutover-do).

> [accordion] Files are missing, or the logs show bucket not found
>
> A bucket name or prefix did not carry over. Compare the values from [Step 1: Find the names in use](#step-1-find-the-names-in-use) with the running Deployments, set the missing names, and upgrade the release. Files stored under the old name are still in the old bucket.

> [accordion] qdrant starts with an empty collection set
>
> The new StatefulSet created new claims instead of reattaching yours. Check the claim names as described in [What if your claim names are different?](#what-if-your-claim-names-are-different), or restore the collections from your qdrant snapshots.

***

## Related resources

> [card] [AI Platform setup](./ai-platform-setup)
>
> AI services, configuration, and deployment

> [card] [Qdrant setup](./qdrant)
>
> Vector database configuration

> [card] [SpiceDB](./spicedb)
>
> Authorization service setup

> [card] [5.9.6 release notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes)
>
> Upgrade notes for FlowX.AI 5.9.6


# ModPod setup
Source: https://docs.flowx.ai/5.9/setup-guides/modpod-setup

Configure the ModPod service for ML model serving with LightGBM, scikit-learn, and SHAP explainability.

ModPod is a standalone Python service. It does not depend on Kafka, Keycloak, or object storage — model artifacts and the model registry live on a local persistent volume.

***

## Dependencies

ModPod is self-contained. It does not require any other FlowX infrastructure service to run.

* **Persistent volume** — required for model artifacts and the SQLite registry
* **Identity provider** — not used; authentication is a static bearer token
* **Kafka** — not used
* **Object storage (S3/MinIO)** — not used; models are stored on the mounted volume

***

## Capabilities

* Upload model packages as ZIP archives with a `metadata.json` manifest
* Manage model registry (list, fetch, delete by name/version)
* Load models into memory on demand
* Run inference with SHAP-based top-factor explanations
* Support for **LightGBM** (Booster text format) and **Logistic Regression** (scikit-learn, joblib-serialized)

***

## Authentication

ModPod uses a static bearer token. Set the `AUTHORIZATION_APIKEY` environment variable and include the token on every request except the health check:

```http theme={"dark"}
Authorization: Bearer <AUTHORIZATION_APIKEY>
```

> [!WARNING]
>
> The API key is a static secret. Store it in a Kubernetes `Secret` (or equivalent) and never commit it to source control.

***

## API endpoints

All endpoints are prefixed with `/modpod`.

### Health

| Method | Path | Auth | Description |
| - | - | - | - |
| `GET` | `/modpod/info/healthcheck` | None | Service health check |

### Model upload

| Method | Path | Auth | Description |
| - | - | - | - |
| `POST` | `/modpod/upload` | Bearer | Upload a ZIP archive containing model files and `metadata.json` |

The ZIP must contain a `metadata.json` file with `name` and `version` fields. Files are extracted to `<MODPOD_MODELS_DIR>/<name>/<version>/`.

### Model registry

| Method | Path | Auth | Description |
| - | - | - | - |
| `GET` | `/modpod/models` | Bearer | List all registered models |
| `GET` | `/modpod/models/{name}` | Bearer | Get model details and versions |
| `GET` | `/modpod/models/{name}/versions` | Bearer | List versions for a given model |
| `DELETE` | `/modpod/models/{name}/{version}` | Bearer | Delete a specific model version |
| `DELETE` | `/modpod/models` | Bearer | Delete all models |

### Inference

| Method | Path | Auth | Description |
| - | - | - | - |
| `POST` | `/modpod/inference/load` | Bearer | Load a model into memory |
| `POST` | `/modpod/inference/predict` | Bearer | Run prediction on a loaded model |

#### Predict request

```json theme={"dark"}
{
  "model_name": "call-propensity",
  "model_version": "1.0",
  "model_type": "propensity",
  "input_data": {
    "feature1": 0.5,
    "feature2": "category_a",
    "feature3": 100
  }
}
```

#### Predict response

```json theme={"dark"}
{
  "output_data": {
    "model": "call-propensity:1.0",
    "input": { "...": "..." },
    "result": {
      "prediction": 0.73,
      "top_factors": "feature1=0.50 (avg=0.30); feature2=category_a"
    }
  }
}
```

***

## Supported model types

| Type | Format | File name |
| - | - | - |
| **LightGBM** | Booster text format | `encoders/model-{type}.txt` |
| **Logistic Regression** | joblib-serialized scikit-learn model | `encoders/model-{type}.joblib` |

Both types produce SHAP-based top-factor explanations alongside the prediction. LightGBM uses the built-in `pred_contrib` output; Logistic Regression uses `shap.LinearExplainer`.

***

## Model package structure

Model packages are uploaded as ZIP archives with the following layout:

```text theme={"dark"}
model.zip/
├── metadata.json
└── encoders/
    ├── model-{type}.txt         # LightGBM model (or .joblib for Logistic Regression)
    ├── {type}-feature-context.csv  # Feature metadata (mean, direction, type)
    ├── standard_scaler.pkl      # StandardScaler (Logistic Regression only)
    ├── shap_background.pkl      # SHAP background data (Logistic Regression only)
    └── {feature}-classes.pkl    # LabelEncoder per categorical feature (LightGBM)
```

The `metadata.json` file must contain at least `name` and `version`:

```json theme={"dark"}
{
  "name": "call-propensity",
  "version": "1.0",
  "description": "Propensity-to-call scoring model"
}
```

***

## Environment variables

### Authentication

| Environment Variable | Description | Default Value |
| - | - | - |
| `AUTHORIZATION_APIKEY` | Bearer token required on all authenticated endpoints. | - (required) |

### Storage

| Environment Variable | Description | Default Value |
| - | - | - |
| `MODPOD_MODELS_DIR` | Directory where uploaded model artifacts are stored. Mount a persistent volume here. | `./models` |
| `MODPOD_DATABASE_URL` | Database URL for the model registry. SQLite is used by default. | `sqlite:///modpod.db` |
| `MODPOD_DB_PATH` | SQLite file path. Used only when `MODPOD_DATABASE_URL` is not set. | `./modpod.db` |

### Server

| Environment Variable | Description | Default Value |
| - | - | - |
| `GUNICORN_WORKERS` | Number of Gunicorn worker processes. | `1` |
| `GUNICORN_TIMEOUT` | Request timeout in seconds. | `600` |

> [!NOTE]
>
> Recommended worker count is `1`. Inference is CPU-bound and loaded models are held in per-process memory; additional workers multiply the memory footprint without increasing throughput for a single model.

### CORS

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of allowed origins. Set to the frontend origin(s) that call ModPod. | - |
| `APPLICATION_CORS_ALLOW_HEADERS` | Comma-separated list of allowed request headers. | Standard FlowX headers |
| `APPLICATION_CORS_ALLOW_METHODS` | Comma-separated list of allowed HTTP methods. | `GET,PUT,POST,DELETE,PATCH,OPTIONS` |

***

## Deployment

ModPod is packaged as a Docker image based on `python:3.13.3-slim-bookworm` and runs as a non-root user.

| Setting | Value |
| - | - |
| Container port | `8080` |
| Health check path | `/modpod/info/healthcheck` |
| Models directory (in container) | `/code/models` |
| SQLite database (in container) | `/code/modpod.db` |

### Resource recommendations

| Resource | Recommendation |
| - | - |
| Memory | 512 MB – 1 GB, depending on the number and size of loaded models |
| CPU | 1 vCPU (inference is CPU-bound) |
| Gunicorn workers | `1` |
| Persistent volume | Minimum `5Gi` for `/code/models` (grows with the number of models) |

> [!WARNING]
>
> The SQLite registry is file-based and stored on the same volume as model artifacts. To scale ModPod horizontally, switch to an external database by setting `MODPOD_DATABASE_URL` to a shared database URL.

***

## Validation

> [!TIP]
>
> Health check returns `200 OK`:
>
> ```bash theme={"dark"}
> curl http://<modpod-host>/modpod/info/healthcheck
> ```

> [!TIP]
>
> Authenticated listing returns an empty list (fresh install) or your registered models:
>
> ```bash theme={"dark"}
> curl -H "Authorization: Bearer $AUTHORIZATION_APIKEY" \
>   http://<modpod-host>/modpod/models
> ```

***

## Related resources

> [card] [Ingress configuration](./ingress-configuration)
>
> Routing and CORS for FlowX services

> [card] [Setup guides overview](./setup-guides-overview)
>
> Full list of FlowX service setup guides


# NoSQL DB Runner
Source: https://docs.flowx.ai/5.9/setup-guides/nosql-db-runner

Set up the NoSQL DB Runner microservice that powers FlowX Database with MongoDB and Azure Cosmos DB support.

> [!WARNING]
>
> **Behavior change in FlowX.AI 5.9.1.** Insert operations no longer accept a custom `_id` field.
>
> `_id` is reserved and assigned internally by MongoDB. Supplying your own `_id` on insert was never supported and could cause errors on later reads, so `Insert` and `Insert Many` now reject any payload that contains an `_id` field with `400 Bad Request` and the message `_id is a reserved keyword`. Remove `_id` from insert payloads; if you need to keep a custom identifier, store it under a different key (for example, `externalId`). Update and query operations are not affected.

## Configuration

The service comes with most of the needed configuration properties filled in, but there are several environment variables that need to be set up for your specific deployment.

### Database configuration

The NoSQL DB Runner connects to MongoDB for data persistence. Configure the following variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `DB_USERNAME` | MongoDB username for the service | `nosql-db-runner` |
| `DB_PASSWORD` | MongoDB password (should be stored as secret) | `secret(mongodb-generic)` |
| `SPRING_DATA_MONGODB_URI` | Complete MongoDB connection string | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/nosql-db-runner` |

> [!NOTE]
>
> The MongoDB URI supports replica set configuration for high availability. The connection string includes multiple MongoDB instances and an arbiter for proper replica set functionality.

### Configuring authorization & access roles

The NoSQL DB Runner validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-nosql-db-runner-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

### FlowX operations document limit

This setting allows you to configure the maximum number of documents that can be retrieved from MongoDB in a single request.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_RUNOPERATIONS_DOCUMENTLIMIT` | Maximum number of documents to be processed in a single operation | `1000` |

### External MongoDB connection caching

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100` |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL` | Time-to-live for cached connections (duration format, e.g. `1d`, `12h`) | `1d` |

> [!TIP]
>
> If you connect to many distinct external MongoDB instances, increase `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` to avoid frequent reconnections. Lower the TTL if your MongoDB credentials rotate frequently.

### Relational database connection pooling

These defaults apply to all relational database data sources: Oracle, and PostgreSQL on SaaS from 5.10.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools | `100` |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached connection pools (duration format, e.g. `1d`, `12h`) | `1d` |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per data source | `5` |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout | `10` |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses | `1000` |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout | `30` |

> [!TIP]
>
> Increase `FLOWX_SQL_DEFAULTS_ROW_LIMIT` if your workflows need to read more than 1000 rows in a single query. Adjust `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` for long-running analytical queries.

### Relational database host restrictions

> [!NOTE]
>
> **Available starting with FlowX.AI 5.9.5**

Relational data sources (Oracle, and PostgreSQL on SaaS) may only connect to hosts that resolve to a public address. If **any** address the hostname resolves to is private, the connection is rejected with `400 Bad Request`, error key `error.sql.internalHostNotPermitted`, and the message `Connection to internal addresses is not permitted: <host>`. MongoDB connections are not affected by this restriction.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SSRF_PROTECTION_ENABLED` | Turns the host restriction on or off. Set to `false` to skip the check entirely. | `true` |
| `FLOWX_SSRF_ALLOWED_HOSTS` | Comma-separated hostnames, IP addresses, or CIDR blocks that are permitted even though they resolve to a private address, for example a database on a private network reached over a site-to-site VPN. Hostname entries must match the configured host exactly (case-insensitive, no wildcards). | |

> [!TIP]
>
> Prefer a hostname entry over a CIDR block. A hostname covers every address that name resolves to, so it keeps working if the DNS record later gains another address. A CIDR block is matched per address, so every private address the hostname returns must fall inside an allowed block, or the connection is still rejected.

> [!NOTE]
>
> Loopback, link-local, and wildcard addresses are never permitted, even when the host is listed in `FLOWX_SSRF_ALLOWED_HOSTS`.

### Configuring logging

Control log levels for different components of the service:

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_CONFIG` | Path to the logging configuration file | `logback-spring.xml` |
| `LOGGING_LEVEL_ROOT` | Root logger level for the Spring Boot service | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |

> [!WARNING]
>
> Using DEBUG log levels in production environments may impact performance and generate large log volumes. Consider using INFO or WARN levels for production deployments.

### Configuring application management

Configure management endpoints and monitoring capabilities:

| Environment Variable | Description | Default Value |
| - | - | - |
| `MANAGEMENT_SERVER_PORT` | Port for management endpoints | `8081` |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_LIVENESS_INCLUDE` | Health checks for liveness probes | `ping,buildInfo` |
| `MANAGEMENT_ENDPOINT_HEALTH_GROUP_READINESS_INCLUDE` | Health checks for readiness probes | `ping,buildInfo,mongo` |
| `MANAGEMENT_HEALTH_KUBERNETES_ENABLED` | Enable Kubernetes health checks | `false` |

### Prometheus metrics configuration

Enable Prometheus metrics export for monitoring:

| Environment Variable | Description | Default Value |
| - | - | - |
| `MANAGEMENT_PROMETHEUS_METRICS_EXPORT_ENABLED` | Enable Prometheus metrics export | `false` |

> [!NOTE]
>
> The older form `MANAGEMENT_METRICS_EXPORT_PROMETHEUS_ENABLED` also works (both resolve to the same setting). The property path above is the preferred form.

***

## Troubleshooting

### Common issues

> [accordion] MongoDB connection failures
>
> **Symptoms:** Service fails to start with database connection errors.
>
> **Solutions:**
>
> 1. Verify MongoDB connection string format and credentials
> 2. Ensure MongoDB replica set is properly configured and accessible
> 3. Check network connectivity between service and MongoDB instances
> 4. Verify MongoDB user permissions and database access rights

> [accordion] Kafka connectivity issues
>
> **Symptoms:** Service cannot consume or produce Kafka messages.
>
> **Solutions:**
>
> 1. Verify `SPRING_KAFKA_BOOTSTRAP_SERVERS` points to the correct broker(s)
> 2. Check Kafka security protocol and authentication configuration
> 3. Ensure network policies allow traffic to the Kafka cluster
> 4. Verify topic names and consumer group assignments are correct

> [accordion] OAuth authentication errors
>
> **Symptoms:** 401/403 errors when communicating with other FlowX services.
>
> **Solutions:**
>
> 1. Verify OAuth client ID and client secret are correct
> 2. Check OAuth server URL and realm configuration
> 3. Ensure OAuth provider is accessible from the service
> 4. Validate token endpoint URI configuration

> [accordion] Insert fails with '\_id is a reserved keyword'
>
> **Symptoms:** An `Insert` or `Insert Many` operation returns `400 Bad Request` with the message `_id is a reserved keyword`.
>
> **Cause:** `_id` is reserved and assigned by MongoDB. Supplying it on insert was never supported and could break later reads, so starting with FlowX.AI 5.9.1 it is rejected.
>
> **Solution:** Remove the `_id` field from the insert payload. If you need to keep a specific identifier, store it under a different key (for example, `externalId`).

> [accordion] Relational connection fails with 'Connection to internal addresses is not permitted'
>
> **Symptoms:** An Oracle data source (or, on SaaS, a PostgreSQL one) returns `400 Bad Request` with the message `Connection to internal addresses is not permitted: <host>` (error key `error.sql.internalHostNotPermitted`).
>
> **Cause:** The hostname resolves to at least one private address. Every address a hostname resolves to is checked, so a host with several DNS records is rejected if any one of them is private, even when the others are public.
>
> **Solution:** If the database is legitimately on a private network, for example reached over a site-to-site VPN, add its hostname to `FLOWX_SSRF_ALLOWED_HOSTS`. See [Relational database host restrictions](#relational-database-host-restrictions).

***

## Related resources

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# Notifications plugin setup
Source: https://docs.flowx.ai/5.9/setup-guides/notifications-plugin-setup

The Notifications plugin is available as a Docker image, and it has the following dependencies.

## Dependencies

Before setting up the plugin, ensure you have the following dependencies:

* A [MongoDB](https://www.mongodb.com/2) database for storing notification templates and records
* Access to the Kafka instance used by the FlowX.AI Engine
* A [Redis](https://redis.io/) instance for caching notification templates
* An S3-compatible file storage solution (for example [MinIO](http://min.io/)) if you need to attach documents to notifications

***

## Authorization configuration

The Notifications plugin validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

***

## MongoDB configuration

The only thing that needs to be configured is the DB access info, the rest will be handled by the plugin.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://paperflow:password@jx-notification-mdb:27017/notification` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection | `true` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | Runtime MongoDB connection URI | `mongodb://${DB_USERNAME:paperflow}:${DB_PASSWORD:password}@jx-app-runtime-mdb:27017/app-runtime?retryWrites=false` |
| `DB_USERNAME` | Runtime MongoDB username, referenced as a placeholder by the default runtime URI. Optional — if you override the full URI, set the credentials there instead. | `paperflow` |
| `DB_PASSWORD` | Runtime MongoDB password, referenced as a placeholder by the default runtime URI. Optional — see `DB_USERNAME`. | `password` |

***

## Redis configuration

Notification Plugin uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

***

## Kafka configuration

### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections | `PLAINTEXT` |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group identifier | `notification-plugin-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10` |
| `KAFKA_CONSUMER_THREADS` | Number of consumer threads | `1` |

### Consumer error handling

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_ERRORHANDLING_ENABLED` | Enable consumer error handling | `false` |
| `KAFKA_CONSUMER_ERRORHANDLING_RETRIES` | Number of retry attempts for failed messages | `0` |
| `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL` | Interval between retries (milliseconds) | `1000` |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern | `engine.receive.` |

### Topic configurations

Each action in the service corresponds to a Kafka event on a specific topic. Configure the following topics:

#### OTP topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_OTP_GENERATE_IN` | Topic for incoming OTP generation requests | `ai.flowx.plugin.notification.trigger.generate.otp.v1` |
| `KAFKA_TOPIC_OTP_GENERATE_OUT` | Topic for OTP generation results | `ai.flowx.engine.receive.plugin.notification.generate.otp.results.v1` |
| `KAFKA_TOPIC_OTP_VALIDATE_IN` | Topic for incoming OTP validation requests | `ai.flowx.plugin.notification.trigger.validate.otp.v1` |
| `KAFKA_TOPIC_OTP_VALIDATE_OUT` | Topic for OTP validation results | `ai.flowx.engine.receive.plugin.notification.validate.otp.results.v1` |

#### Notification topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN` | Topic for incoming notification requests from the process engine (used by both Kafka-forwarded notifications and the [Send Notification action](../docs/building-blocks/actions/send-notification-action)) | `ai.flowx.plugin.notification.trigger.send.notification.v1` |
| `KAFKA_TOPIC_NOTIFICATION_INTERNAL_OUT` | Topic for notification delivery confirmations | `ai.flowx.engine.receive.plugin.notification.confirm.send.notification.v1` |
| `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` | Topic for forwarding notifications to external systems | `ai.flowx.plugin.notification.trigger.forward.notification.v1` |

#### Audit topic

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Topic for sending audit logs | `ai.flowx.core.trigger.save.audit.v1` |

#### Resource usages topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Topic for resource usages refresh events | `ai.flowx.application-version.resources-usages.refresh.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_RESELEMUSAGEVALIDATION_RESPONSE` | Topic for sub-resource validation responses | `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_USAGES_OUT` | Topic for bulk resource usage operations | `ai.flowx.application-version.resources-usages.operations.bulk.v1` |

***

## File storage configuration

Based on use case you can use directly a file system or an S3 compatible cloud storage solution (for example [min.io](http://min.io/)).

The file storage solution can be configured using the following environment variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | Storage type to use (`s3` or `fileSystem`) | `s3` |
| `APPLICATION_FILESTORAGE_DISKDIRECTORY` | Directory for file storage when using filesystem | `MS_SVC_NOTIFICATION` |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | Enable S3-compatible storage | `true` |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | URL of MinIO or S3-compatible server | `http://minio-service:9000` |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | Enable server-side encryption | `false` |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | Access key for S3 | `minio` |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | Secret key for S3 | `minio123` |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | Prefix for bucket names | `qdevlocal-preview-paperflow` |

> [!NOTE]
>
> When using S3-compatible storage for notifications with attachments, the S3 user configured through `APPLICATION_FILESTORAGE_S3_ACCESSKEY` and `APPLICATION_FILESTORAGE_S3_SECRETKEY` must have read access to multiple buckets beyond its own:
>
> Required bucket access:
>
> * **Own bucket** - defined by `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
> * [**Documents Plugin bucket**](./documents-plugin-setup#general-storage-configuration) - defined in the Documents Plugin configuration via `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
> * [**CMS Core public bucket**](./cms-setup#configuring-file-storage) - defined in the CMS Core configuration via `APPLICATION_FILESTORAGE_S3_BUCKETNAME`
> * [**Integration Designer bucket**](./integration-designer-setup#storage-configuration) - defined in the Integration Designer configuration via `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX`
>
> Ensure your S3 user has appropriate read permissions to all releva dnt buckets to avoid attachment failures.

***

## SMTP setup

> [!NOTE]
>
> The Notifications plugin sends email over **SMTP only**. It does not support Microsoft 365 / Microsoft Graph authentication (Azure AD client secret or certificate). To send through Microsoft 365, configure a **Microsoft Outlook** data source in the Integration Designer — that path runs through the email-gateway and uses the MS Graph API. See [Microsoft Outlook](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source).

Configure SMTP settings for sending email notifications:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SIMPLEJAVAMAIL_SMTP_HOST` | SMTP server hostname | `smtp.gmail.com` |
| `SIMPLEJAVAMAIL_SMTP_PORT` | SMTP server port | `587` |
| `SIMPLEJAVAMAIL_SMTP_USERNAME` | SMTP server username | `notification.test@flowx.ai` |
| `SIMPLEJAVAMAIL_SMTP_PASSWORD` | SMTP server password | `paswword` |
| `SIMPLEJAVAMAIL_TRANSPORTSTRATEGY` | Email transport strategy (e.g., `SMTP`, `EXTERNAL_FORWARD`) | `SMTP` |
| `SIMPLEJAVAMAIL_JAVAXMAIL_DEBUG` | Verbose JavaMail SMTP debug logging | `false` |
| `APPLICATION_MAIL_FROMEMAIL` | Default sender email address | `notification.test@flowx.ai` |
| `APPLICATION_MAIL_FROMNAME` | Default sender name | `Notification` |

### Advanced SMTP options

The notification plugin sends email through the [simple-java-mail](https://www.simplejavamail.org/) library, which auto-binds every `simplejavamail.*` property — set them as environment variables the same way as the values above. The options below come up most often when connecting to corporate SMTP relays:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SIMPLEJAVAMAIL_DEFAULTS_VERIFYSERVERIDENTITY` | Verify that the hostname in the server's TLS certificate matches the configured SMTP host. Set to `false` for relays whose certificate doesn't match the configured hostname; the connection stays encrypted | `true` |
| `SIMPLEJAVAMAIL_DEFAULTS_TRUSTEDHOSTS` | Semicolon-delimited list of hosts whose TLS certificates are trusted without chain validation | – |
| `SIMPLEJAVAMAIL_DEFAULTS_TRUSTALLHOSTS` | Accept any TLS certificate without chain validation. Prefer `SIMPLEJAVAMAIL_DEFAULTS_TRUSTEDHOSTS` | `false` |
| `SIMPLEJAVAMAIL_DEFAULTS_SESSIONTIMEOUTMILLIS` | Socket timeout (in milliseconds) for the SMTP session. Raise for slow relays | `60000` |

> [!WARNING]
>
> These defaults load into the library's global configuration, so they apply to **all** mailers the plugin creates — including the ones built dynamically for Email Sender systems configured in the Integration Designer, whose settings override only the connection fields (host, port, username, password, transport strategy). Changing `SIMPLEJAVAMAIL_DEFAULTS_VERIFYSERVERIDENTITY` or `SIMPLEJAVAMAIL_DEFAULTS_TRUSTALLHOSTS` therefore affects every configured email system.

For the full list of available properties (connection pooling, embedded image resolution, and more), see the [simple-java-mail configuration reference](https://www.simplejavamail.org/configuration.html).

***

## Email attachments configuration

Configure handling of email attachments:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_HTTP_MULTIPART_MAXFILESIZE` | Maximum file size for attachments | `15MB` |
| `SPRING_HTTP_MULTIPART_MAXREQUESTSIZE` | Maximum request size for multipart uploads | `15MB` |

***

## OTP configuration

Configure One-Time Password generation and validation:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_OTP_LENGTH` | Number of characters in generated OTPs | `4` |
| `FLOWX_OTP_EXPIRETIMEINSECONDS` | Expiry time for OTPs (seconds) | `6000` (100 minutes) |

***

## Logging configuration

Control logging levels for different components:

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | - |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver log level | `INFO` |
| `LOGGING_LEVEL_THYMELEAF` | Thymeleaf template engine log level | `INFO` |
| `LOGGING_LEVEL_FCM_CLIENT` | Firebase Cloud Messaging client log level | `OFF` |
| `LOGGING_LEVEL_REDIS` | Redis/Lettuce client log level | `OFF` |

***

## CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-` |

***

## Usage notes

### Topic naming convention

Topics follow a standardized naming convention:

* Example: `ai.flowx.plugin.notification.trigger.generate.otp.v1`
* Structure: `{package}{environment}.{component}.{action}.{subject}.{version}`

### Consumer error handling

When `KAFKA_CONSUMER_ERRORHANDLING_ENABLED` is set to `true`:

* The application will retry processing failed messages according to `KAFKA_CONSUMER_ERRORHANDLING_RETRIES`
* Between retries, the application will wait for the duration specified by `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL`

For example, if `KAFKA_CONSUMER_ERRORHANDLING_RETRYINTERVAL` is set to 5000 (5 seconds) and `KAFKA_CONSUMER_ERROR_HANDLING_RETRIES` is set to 5, the consumer application will make up to 5 attempts, waiting 5 seconds between each attempt.

### Message size configuration

The `KAFKA_MESSAGE_MAX_BYTES` setting affects multiple Kafka properties:

* `spring.kafka.producer.properties.message.max.bytes`
* `spring.kafka.producer.properties.max.request.size`
* `spring.kafka.consumer.properties.max.partition.fetch.bytes`

### OAuth authentication

When using the 'kafka-auth' profile, the security protocol changes to 'SASL\_PLAINTEXT' and requires OAuth configuration via the `KAFKA_OAUTH_*` variables.

***

## Ingress and CORS

The Notification plugin is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/notification` | `/` |

The path is set through `services.notification-plugin.ingress.admin.path` (or `services.notification-plugin.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Notification. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

### Common issues

> [accordion] Notifications not being sent
>
> **Symptoms:** Notification requests are accepted but emails or messages are never delivered.
>
> **Solutions:**
>
> 1. Verify Kafka topics are correctly configured and the notification plugin is consuming from `KAFKA_TOPIC_NOTIFICATION_INTERNAL_IN`
> 2. Check SMTP configuration (`SIMPLEJAVAMAIL_SMTP_HOST`, port, credentials) and ensure the SMTP server is reachable from the pod
> 3. If using the Email Gateway for forwarding, verify `KAFKA_TOPIC_NOTIFICATION_EXTERNAL_OUT` is configured and the Email Gateway is running
> 4. Check application logs for delivery errors by setting `LOGGING_LEVEL_APP` to `DEBUG`

> [accordion] OTP generation fails
>
> **Symptoms:** OTP requests return errors or no OTP is generated.
>
> **Solutions:**
>
> 1. Verify OTP configuration values (`FLOWX_OTP_LENGTH`, `FLOWX_OTP_EXPIRETIMEINSECONDS`) are set correctly
> 2. Check that Kafka topics `KAFKA_TOPIC_OTP_GENERATE_IN` and `KAFKA_TOPIC_OTP_GENERATE_OUT` are created and accessible
> 3. Ensure MongoDB is reachable and the notification plugin database has write permissions
> 4. Verify Kafka consumer group `SPRING_KAFKA_CONSUMER_GROUPID` is not conflicting with another instance

> [accordion] Notification templates not rendering
>
> **Symptoms:** Notifications are sent but contain raw template syntax or missing values.
>
> **Solutions:**
>
> 1. Verify substitution tags in the template match the keys provided in the notification request payload
> 2. Check that the Thymeleaf engine is functioning by reviewing logs at `LOGGING_LEVEL_THYMELEAF` set to `DEBUG`
> 3. Ensure the template exists in MongoDB and is in the correct format
> 4. Verify Redis cache is not serving stale templates — clear the cache or restart the plugin if templates were recently updated

> [accordion] Firebase push notifications not working
>
> **Symptoms:** Push notifications are not delivered to mobile devices.
>
> **Solutions:**
>
> 1. Verify Firebase Cloud Messaging credentials are correctly configured
> 2. Check that the target device has a valid FCM registration token
> 3. Enable FCM client logging by setting `LOGGING_LEVEL_FCM_CLIENT` to `DEBUG` to inspect request/response details
> 4. Ensure network policies allow outbound HTTPS traffic to Firebase servers (`fcm.googleapis.com`)

***

## Related resources

> [card] [Sending Notifications](../docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/sending-a-notification)
>
> Learn how to configure and send notifications from your processes

> [card] [Email Gateway Setup](./email-gateway-setup)
>
> Configure the Email Gateway for inbound and outbound email processing

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes


# Deployment configuration for OpenTelemetry
Source: https://docs.flowx.ai/5.9/setup-guides/open-telemetry-config

Guide to deploying OpenTelemetry components and configuring associated services.

### Step 1: Install OpenTelemetry Operator

Ensure you have the OpenTelemetry Operator version **0.56.1** or higher:

```yaml theme={"dark"}
    - repoURL: https://open-telemetry.github.io/opentelemetry-helm-charts
      chart: opentelemetry-operator
      targetRevision: 0.56.1
```

#### Configuration:

```yaml theme={"dark"}
# Source: https://github.com/open-telemetry/opentelemetry-helm-charts/blob/opentelemetry-operator-0.56.1/charts/opentelemetry-operator/values.yaml
## Provide OpenTelemetry Operator manager container image and resources
manager:
  image:
    repository: ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator
    tag: ""
  collectorImage:
    repository: "otel/opentelemetry-collector-contrib"
    tag: 0.98.0
  opampBridgeImage:
    repository: ""
    tag: ""
  targetAllocatorImage:
    repository: ""
    tag: ""
  autoInstrumentationImage:
    java:
      repository: ""
      tag: ""
    nodejs:
      repository: ""
      tag: ""
    python:
      repository: ""
      tag: ""
    dotnet:
      repository: ""
      tag: ""
    # The Go instrumentation support in the operator is disabled by default.
    # To enable it, use the operator.autoinstrumentation.go feature gate.
    go:
      repository: ""
      tag: ""
  # Feature Gates are a comma-delimited list of feature gate identifiers.
  # Prefix a gate with '-' to disable support.
  # Prefixing a gate with '+' or no prefix will enable support.
  # A full list of valid identifiers can be found here: https://github.com/open-telemetry/opentelemetry-operator/blob/main/pkg/featuregate/featuregate.go
  featureGates: ""
  ports:
    metricsPort: 8080
    webhookPort: 9443
    healthzPort: 8081
  resources:
    limits:
      cpu: 100m
      memory: 128Mi
    requests:
      cpu: 100m
      memory: 64Mi
  ## Adds additional environment variables
  ## e.g ENV_VAR: env_value
  env:
    ENABLE_WEBHOOKS: "true"

## Admission webhooks make sure only requests with correctly formatted rules will get into the Operator.
## They also enable the sidecar injection for OpenTelemetryCollector and Instrumentation CR's
admissionWebhooks:
  create: true
  servicePort: 443
  failurePolicy: Fail
```

> [!NOTE]
>
> Ensure you use the appropriate distribution and version:

```yaml theme={"dark"}
    repository: "otel/opentelemetry-collector-contrib"
    tag: 0.98.0
```

### Step 2: Deploy OpenTelemetry Resources

Apply the OpenTelemetry resources:

#### OpenTelemetry Collector

```yaml theme={"dark"}
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
  name: otel
  namespace: {{ .Release.Namespace }}
spec:
  mode: deployment
  resources:
    limits:
      cpu: "2"
      memory: 6Gi
    requests:
      cpu: 200m
      memory: 2Gi

  config: |
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            # Since this collector needs to receive data from the web, enable cors for all origins
            # `allowed_origins` can be refined for your deployment domain
            endpoint: 0.0.0.0:4318
            cors:
              allowed_origins:
                - "http://*"
                - "https://*"
      zipkin:
    exporters:
      debug: {}
      ## Create an exporter to Jaeger using the standard `otlp` export format
      otlp/tempo:
        endpoint: 'otel-tempo:4317'
        tls:
          insecure: true
      # Create an exporter to Prometheus (metrics)
      otlphttp/prometheus:
        endpoint: 'http://otel-prometheus-server:9090/api/v1/otlp'
        tls:
          insecure: true
      loki:
        endpoint: "http://otel-loki:3100/loki/api/v1/push"
        default_labels_enabled:
          exporter: true
          job: true

    extensions:
      health_check:
      memory_ballast: {}

    processors:
      batch: {}
      k8sattributes:
        extract:
          metadata:
          - k8s.namespace.name
          - k8s.deployment.name
          - k8s.statefulset.name
          - k8s.daemonset.name
          - k8s.cronjob.name
          - k8s.job.name
          - k8s.node.name
          - k8s.pod.name
          - k8s.pod.uid
          - k8s.pod.start_time
        passthrough: false
        pod_association:
        - sources:
          - from: resource_attribute
            name: k8s.pod.ip
        - sources:
          - from: resource_attribute
            name: k8s.pod.uid
        - sources:
          - from: connection
      resource:
        attributes:
        - key: service.instance.id
          from_attribute: k8s.pod.uid
          action: insert
      memory_limiter:
        check_interval: 5s
        limit_percentage: 80
        spike_limit_percentage: 25

    connectors:
      spanmetrics: {}

    service:
      extensions:
        - health_check
        - memory_ballast
      pipelines:
        traces:
          processors: [memory_limiter, resource, batch]
          exporters: [otlp/tempo, debug, spanmetrics]
          receivers: [otlp]
        metrics:
          receivers: [otlp, spanmetrics]
          processors: [memory_limiter, resource, batch]
          exporters: [otlphttp/prometheus, debug]
        logs:
          processors: [memory_limiter, resource, batch]
          exporters: [loki, debug]
          receivers: [otlp]
```

#### OpenTelemetry Instrumentation

```yaml theme={"dark"}
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: flowx-otel-instrumentation
  namespace: {{ .Release.Namespace }}
spec:
  exporter:
    endpoint: http://otel-collector:4317
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.1.0
    env:
      - name: OTEL_INSTRUMENTATION_LOGBACKAPPENDER_ENABLED
        value: "true"
      - name: OTEL_LOGS_EXPORTER
        value: otlp
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: http://otelcol-operator-collector:4317
      - name: OTEL_EXPORTER_OTLP_PROTOCOL
        value: grpc
```

### Step 3: Instrument Flowx Services

Update Flowx services to enable Java instrumentation by adding the following pod annotation:

```yaml theme={"dark"}
podAnnotations:
  instrumentation.opentelemetry.io/inject-java: "true"
```

### Step 4: Configure Grafana, Prometheus and Tempo

#### Configure Grafana

```yaml theme={"dark"}
##Source: https://github.com/grafana/helm-charts/blob/grafana-7.3.10/charts/grafana/values.yaml
rbac:
  create: true
  namespaced: true
serviceAccount:
  create: true
replicas: 1

ingress:
  enabled: true
  ingressClassName: nginx
  path: /
  hosts:
  - {{ .Values.flowx.ingress.grafana }}

## Enable persistence using Persistent Volume Claims
## ref: http://kubernetes.io/docs/user-guide/persistent-volumes/
##
persistence:
  enabled: true
  accessModes:
    - ReadWriteOnce
  size: 5Gi
  finalizers: []

datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Loki
        uid: loki
        type: loki
        access: proxy
        url: http://otel-loki:3100
        timeout: 300
        version: 1
        jsonData:
          derivedFields:
            - datasourceUid: tempo
              # matches variations of "traceID" fields, either in JSON or logfmt
              # marian-fx: matcherRegex: '"traceid":"(\w+)"'
              matcherRegex: (?:[Tt]race[-_]?[Ii][Dd])[\\]?["]?[=:][ ]?[\\]?["]?(\w+)
              name: traceid
              # url will be interpreted as query for the datasource
              url: "$${__value.raw}"
              urlDisplayLabel: See traces

      - name: Prometheus
        uid: prometheus
        type: prometheus
        url: 'http://otel-prometheus-server:9090'
        editable: true
        isDefault: true
        jsonData:
          exemplarTraceIdDestinations:
            - datasourceUid: tempo
              name: traceid

      - name: Tempo
        uid: tempo
        type: tempo
        access: proxy
        url: http://otel-tempo:3100
        version: 1
        jsonData:
          tracesToLogs:
            datasourceUid: loki
          lokiSearch:
            datasourceUid: loki
          nodeGraph:
            enabled: true
          serviceMap:
            datasourceUid: prometheus
          tracesToLogsV2:
            customQuery: false
            datasourceUid: loki
            filterBySpanID: true
            filterByTraceID: true
            spanEndTimeShift: 1s
            spanStartTimeShift: '-1s'
            tags:
              - key: service.name
                value: job

dashboardProviders:
  dashboardproviders.yaml:
    apiVersion: 1
    providers:
      - name: 'default'
        orgId: 1
        folder: ''
        type: file
        disableDeletion: false
        editable: true
        options:
          path: /var/lib/grafana/dashboards/default

resources:
  limits:
    memory: 150Mi

grafana.ini:
  auth:
    disable_login_form: true
  auth.anonymous:
    enabled: false
    org_name: Main Org.
    org_role: Admin
  auth.generic_oauth:
    enabled: true
    name: Keycloak-OAuth
    allow_sign_up: true
    client_id: private-management-sa
    client_secret: xTs4yGYySrHaNDIpCiniHJUGqBKbyCtp
    scopes: openid email profile offline_access roles
    email_attribute_path: email
    login_attribute_path: username
    name_attribute_path: full_name
    auth_url: https://{{ .Values.flowx.keycloak.host }}/auth/realms/{{ .Values.flowx.keycloak.realm }}/protocol/openid-connect/auth
    token_url: https://{{ .Values.flowx.keycloak.host }}/auth/realms/{{ .Values.flowx.keycloak.realm }}/protocol/openid-connect/token
    api_url: https://{{ .Values.flowx.keycloak.host }}/auth/realms/{{ .Values.flowx.keycloak.realm }}/protocol/openid-connect/userinfo
    # role_attribute_path: contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
  server:
    root_url: "https://{{ .Values.flowx.ingress.grafana }}/grafana"
    serve_from_sub_path: true
adminPassword: admin

# assertNoLeakedSecrets is a helper function defined in _helpers.tpl that checks if secret
# values are not exposed in the rendered grafana.ini configmap. It is enabled by default.
#
# To pass values into grafana.ini without exposing them in a configmap, use variable expansion:
# https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#variable-expansion
#
# Alternatively, if you wish to allow secret values to be exposed in the rendered grafana.ini configmap,
# you can disable this check by setting assertNoLeakedSecrets to false.
assertNoLeakedSecrets: false
```

#### Configure Prometheus

```yaml theme={"dark"}
# https://github.com/prometheus-community/helm-charts/blob/prometheus-22.6.7/charts/prometheus/values.yaml

rbac:
  create: true

podSecurityPolicy:
  enabled: false

## Define serviceAccount names for components. Defaults to component's fully qualified name.
##
serviceAccounts:
  server:
    create: true

alertmanager:
  enabled: false
alertmanagerFiles:
  alertmanager.yml:
    global: {}
      # slack_api_url: ''

    receivers:
      - name: default-receiver
        # slack_configs:
        #  - channel: '@you'
        #    send_resolved: true

    route:
      group_wait: 10s
      group_interval: 5m
      receiver: default-receiver
      repeat_interval: 3h

configmapReload:
  prometheus:
    enabled: false
kube-state-metrics:
  enabled: false
prometheus-node-exporter:
  enabled: false
prometheus-pushgateway:
  enabled: false

server:
  useExistingClusterRoleName: prometheus-server

  ## If set it will override prometheus.server.fullname value for ClusterRole and ClusterRoleBinding
  ##
  clusterRoleNameOverride: ""

  # Enable only the release namespace for monitoring. By default all namespaces are monitored.
  # If releaseNamespace and namespaces are both set a merged list will be monitored.
  releaseNamespace: false

  ## namespaces to monitor (instead of monitoring all - clusterwide). Needed if you want to run without Cluster-admin privileges.
  # namespaces:
  #   - namespace

  extraFlags:
    - "web.enable-lifecycle"
    - "enable-feature=exemplar-storage"
    - "enable-feature=otlp-write-receiver"
  global:
    scrape_interval: 5s
    scrape_timeout: 3s
    evaluation_interval: 30s
  persistentVolume:
    enabled: true
    mountPath: /data
    ## Prometheus server data Persistent Volume size
    ##
    size: 10Gi

  service:
    servicePort: 9090
  ## Prometheus server resource requests and limits
  ## Ref: http://kubernetes.io/docs/user-guide/compute-resources/
  ##
  resources:
    limits:
      cpu: 2000m
      memory: 4096Mi
    requests:
      cpu: 500m
      memory: 2048Mi
  ## Prometheus data retention period (default if not specified is 15 days)
  ##
  retention: "3d"

  ## Prometheus' data retention size. Supported units: B, KB, MB, GB, TB, PB, EB.
  ##
  retentionSize: ""

serverFiles:
  prometheus.yml:
    scrape_configs:
      - job_name: prometheus
        static_configs:
          - targets:
            - localhost:9090

      - job_name: 'otel-collector'
        honor_labels: true
        kubernetes_sd_configs:
          - role: pod
            namespaces:
              own_namespace: true
        relabel_configs:
          - source_labels: [__meta_kubernetes_pod_annotation_opentelemetry_community_demo]
            action: keep
            regex: true
```

#### Configure Loki with a Minio backend

```yaml theme={"dark"}
# https://raw.githubusercontent.com/grafana/loki/helm-loki-6.2.0/production/helm/loki/single-binary-values.yaml
loki:
  auth_enabled: false # https://grafana.com/docs/loki/latest/operations/multi-tenancy/#multi-tenancy
  commonConfig:
    replication_factor: 1
  schemaConfig:
    configs:
      - from: 2024-04-01
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  ingester:
    chunk_encoding: snappy
  tracing:
    enabled: true
  querier:
    # Default is 4, if you have enough memory and CPU you can increase, reduce if OOMing
    max_concurrent: 2

deploymentMode: SingleBinary
singleBinary:
  replicas: 1
  resources:
    limits:
      cpu: 3
      memory: 4Gi
    requests:
      cpu: 1
      memory: 2Gi
  extraEnv:
    # Keep a little bit lower than memory limits
    - name: GOMEMLIMIT
      value: 3750MiB

chunksCache:
  # default is 500MB, with limited memory keep this smaller
  writebackSizeLimit: 10MB

# Enable minio for storage
minio:
  enabled: true
  rootUser: enterprise-logs
  rootPassword: supersecret
  buckets:
    - name: chunks
      policy: none
      purge: false
    - name: ruler
      policy: none
      purge: false
    - name: admin
      policy: none
      purge: false
  persistence:
    size: 10Gi

lokiCanary:
  enabled: false

# Zero out replica counts of other deployment modes
backend:
  replicas: 0
read:
  replicas: 0
write:
  replicas: 0

ingester:
  replicas: 0
querier:
  replicas: 0
queryFrontend:
  replicas: 0
queryScheduler:
  replicas: 0
distributor:
  replicas: 0
compactor:
  replicas: 0
indexGateway:
  replicas: 0
bloomCompactor:
  replicas: 0
bloomGateway:
  replicas: 0
```

#### Configure Tempo

```yaml theme={"dark"}
# https://github.com/grafana/helm-charts/blob/tempo-1.7.2/charts/tempo/values.yaml

tempo:
  # configure a 3 days retention by default
  retention: 72h
  # enable opentelemetry protocol & jaeger receivers
  # this configuration will listen on all ports and protocols that tempo is capable of.
  # the receives all come from the OpenTelemetry collector.  more configuration information can
  # be found there: https://github.com/open-telemetry/opentelemetry-collector/tree/master/receiver
  receivers:
    jaeger:
      protocols:
        grpc:
          endpoint: 0.0.0.0:14250
        thrift_binary:
          endpoint: 0.0.0.0:6832
        thrift_compact:
          endpoint: 0.0.0.0:6831
        thrift_http:
          endpoint: 0.0.0.0:14268
    otlp:
      protocols:
        grpc:
          endpoint: "0.0.0.0:4317"
        http:
          endpoint: "0.0.0.0:4318"
persistence:
  enabled: true
  size: 10Gi

# -- Pod Annotations
podAnnotations:
  prometheus.io/port: prom-metrics
  prometheus.io/scrape: "true"
```


# Organization Manager setup
Source: https://docs.flowx.ai/5.9/setup-guides/organization-manager-setup

This guide provides step-by-step instructions for setting up the Organization Manager microservice.

## Dependencies

Before setting up the Organization Manager, ensure you have the following dependencies in place:

* **PostgreSQL** database for storing organization and tenant data
* **Kafka** for event-driven communication with other FlowX.AI services
* **Redis** for caching
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained authorization

## Infrastructure prerequisites

| Component | Description |
| - | - |
| PostgreSQL | Dedicated database for organization data |
| Kafka | Message broker for inter-service communication |
| Redis | Caching layer for improved performance |
| Keycloak | Identity provider for service authentication |
| SpiceDB | Authorization service for fine-grained access control |

***

## Configuration

### Authorization configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Security type (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-organization-manager-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret. Must be the same value across every service that uses `flowx-anonymous-sa`. | |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL (self-reference for security lib) | `http://organization-manager:80` |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to the authorization-system service during organization provisioning. Increase if provisioning calls time out on slow networks. | `60` |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for the same HTTP calls from organization-manager to the authorization-system service during organization provisioning. | `30` |

***

### PostgreSQL configuration

The Organization Manager uses its own dedicated PostgreSQL database.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for PostgreSQL | `jdbc:postgresql://postgresql:5432/organization_manager` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | - |

> [!NOTE]
>
> **PostgreSQL and Redis credentials: plain env vars still work.** Organization Manager is a standard Spring Boot service — it reads the `SPRING_DATASOURCE_*` and `SPRING_DATA_REDIS_*` environment variables shown here. The `postgresql.servers/credentials` and `redis.servers/credentials` blocks in the FlowX Helm chart's `values.yaml` are the chart's own secret-to-env-var mapping; they exist to template the same plain env vars from your secrets. You can keep injecting credentials through plain environment variables exactly as before.

> [!WARNING]
>
> Ensure the database is created before deploying the service. The Organization Manager will manage its own schema migrations via Liquibase.

***

### Redis configuration

Organization Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

***

### Kafka configuration

#### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |

#### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

#### Kafka topics

The Organization Manager publishes organization lifecycle events:

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_ORGANIZATION_EVENTS_OUT` | Topic for organization lifecycle events | `ai.flowx.organization.events.v1` |
| `KAFKA_TOPIC_LLMCONFIG_CHANGED` | Notifies services when LLM provider or model configuration changes | `ai.flowx.llm.config.changed.v1` |

| Environment Variable | Description | Default Value |
| - | - | - |
| `LLM_ENCRYPTION_MASTERKEY` | Encryption key for LLM provider API keys stored in the database. **Must be changed from the default in production.** | `default-dev-key-change-in-prod` |

> [!WARNING]
>
> Do not use the default encryption key in production. Generate a unique key and keep it consistent across restarts — changing the key after providers are configured will make existing encrypted API keys unreadable.

***

### CAS lib configuration (SpiceDB)

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB gRPC port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX. | `CUSTOM` |

***

### Organization ID configuration

The Organization ID is provided by FlowX during the organization registration process. Before starting a deployment or upgrade, this ID must be configured as an environment variable on all FlowX services that run Liquibase migrations.

> [!WARNING]
>
> On self-hosted upgrades (from 5.1 or later), services will not start correctly without the Organization ID. Migration scripts require it to populate the organization ID across all database records.
>
> This is **not needed** for clean installations where no existing data is present in the database.

Set the `ORGANIZATION_ID` Liquibase parameter on the 9 services that backfill `organization_id` columns: `application-manager`, `authorization-system`, `cms-core`, `document-plugin`, `integration-designer`, `notification-plugin`, `organization-manager`, `process-engine`, `scheduler-core`.

```yaml theme={"dark"}
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

> [!WARNING]
>
> In self-hosted (non-SaaS) deployments, each of these 9 services **fails to start** if `ORGANIZATION_ID` is missing or not a valid UUID. Set it on all 9 before booting 5.9.x.

For the migrate-vs-fresh-install behavior across the three upgrade scenarios, see the [5.1 → 5.9 organization & deployment configuration guide](/5.9/migrating-from-5.1-lts/organization-deployment#organization_id-where-it-is-actually-required).

***

### Self-hosted URL configuration

Set the Designer and Runtime home URIs to the public URLs clients use to reach each web app. The Organization Manager uses these values to compose Keycloak redirect URIs and email links sent from the platform.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DEFAULT_DESIGNER_HOMEURI` | Base URL of the Designer web app. Required. | - |
| `FLOWX_DEFAULT_RUNTIME_HOMEURI` | Base URL of the Runtime (generic container) web app. Required when the FlowX generic container app is deployed. | - |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` | Comma-separated list of additional Keycloak redirect URIs. If left empty, the value is derived automatically from `FLOWX_DEFAULT_DESIGNER_HOMEURI` and `FLOWX_DEFAULT_RUNTIME_HOMEURI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNTVERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` (2 days) |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USERINVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` (2 days) |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOTPASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` (1 hour) |

> [!TIP]
>
> In most deployments, setting `FLOWX_DEFAULT_DESIGNER_HOMEURI` (and `FLOWX_DEFAULT_RUNTIME_HOMEURI` when the generic container app is deployed) is enough — leave `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` empty and the Organization Manager will populate it for you.

#### Designer web app — organization code fallback

Self-hosted deployments must also set the organization code on the **Designer** web app pod. The Designer uses it as a fallback during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `DEFAULT_ORGANIZATION_NAME` | Organization code registered with FlowX. Used by the Designer auth flow as a fallback. | - | designer |

> [!WARNING]
>
> Leaving `DEFAULT_ORGANIZATION_NAME` unset on the Designer pod prevents authentication when users access the app at the root URL (no organization in path or subdomain).

***

> [!NOTE]
>
> **License service required.** Self-hosted deployments must also configure the [License service](/5.9/setup-guides/license-engine-setup), which connects to FlowX SaaS for license validation and usage reporting. The Organization Manager publishes organization lifecycle events via Kafka that the License service consumes.

### Self-hosted initialization

When a self-hosted deployment starts for the first time, the Organization Manager provides endpoints for environment setup and organization registration.

#### Environment status endpoint

`GET /org/api/env` (unauthenticated)

Returns the current installation type and status:

| Status | Description |
| - | - |
| `ONPREM` + `MISSING_ORGANIZATION` | Organization not yet registered. The setup screen is displayed in Designer. |
| `ONPREM` + `MISSING_LICENCE` | Organization exists but the license has not been synced yet. |
| `ONPREM` + `OK` | Fully configured. Returns organization info (org ID, issuer, token endpoint, client ID, redirect URI). |

#### Organization registration endpoint

`POST /org/api/org/single` (not available on SaaS)

Creates the self-hosted organization using a token provided by FlowX. This endpoint is called from the Designer setup screen and:

* Validates the token against the FlowX SaaS license server
* Creates the organization with the org ID and org code from the token claims
* Creates two Keycloak realms (one for users, one for service accounts)
* Creates the initial org admin user with the credentials provided in the setup screen

> [!NOTE]
>
> For **upgrades from 5.1**, the org admin user already exists and the setup screen is not displayed. The Organization Manager will update the existing Keycloak realm with the new organization ID.

***

### Logging configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |

***

### Multipart upload configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_FILE_SIZE` | Maximum file size per upload | `50MB` |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum total request size | `50MB` |

***

## Secrets management

The Organization Manager requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name | Description |
| - | - |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL database password |
| `SPRING_REDIS_PASSWORD` | Redis authentication password |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the Organization Manager:

```yaml theme={"dark"}
fullnameOverride: organization-manager

image:
  registry: <your-registry>
  repository: organization-manager

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/organization_manager
  SPRING_DATASOURCE_USERNAME: postgres

  # Kafka
  SPRING_KAFKA_BOOTSTRAPSERVERS: kafka:9092

  # Security
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth
  SECURITY_OAUTH2_SAREALM: 00000002-0002-4002-8002-000000000002

  # Redis
  SPRING_REDIS_HOST: redis-master

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: redis-generic
    secrets:
      SPRING_REDIS_PASSWORD: redis-password
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakOrgManagerClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: false

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/routing-name: "organization-manager"
  flowx.ai/prometheus-scrape: "organization-manager"
```

> [!NOTE]
>
> The `image.registry` and `image.repository` split applies to **5.9.4 and later**. To redirect every chart at once, use `global.imageRegistry`. See [Container images and registry](./setup-guides-overview#container-images-and-registry).

### Network policies

The Organization Manager requires network access to the following services:

| Service | Purpose | Pod Label |
| - | - | - |
| Kafka | Message broker communication | `flowx.ai/egress-s-kafka` |
| PostgreSQL | Primary data storage | `flowx.ai/egress-s-postgresql` |
| Redis | Caching | `flowx.ai/egress-s-redis` |
| Keycloak | Authentication | `flowx.ai/egress-s-keycloak` |
| SpiceDB | Authorization | `flowx.ai/egress-s-spicedb` |

***

## Monitoring

The Organization Manager exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:

```yaml theme={"dark"}
podLabels:
  flowx.ai/prometheus-scrape: "organization-manager"
```

### Health endpoints

| Endpoint | Description |
| - | - |
| `/actuator/health` | Health check endpoint |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info` | App info endpoint |

***

## Verify your setup

> [!TIP]
>
> The Organization Manager pod is running and healthy: `kubectl get pods -l app=organization-manager`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://organization-manager:8080/actuator/health`

> [!TIP]
>
> Database migrations completed successfully — check pod logs for `Liquibase: Update has been successful`

> [!TIP]
>
> SpiceDB connection is established — check pod logs for successful CAS client initialization

> [!TIP]
>
> Kafka topic `ai.flowx.organization.events.v1` exists and the service can publish to it

***

## Ingress and CORS

The Organization Manager service is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/org` | `/` |
| public | `/org` | `/` |

Paths are set through `services.organization-manager.ingress.admin.path` / `services.organization-manager.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Organization Manager. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

> [accordion] Database connection failures
>
> **Symptoms:** Service fails to start with database connection errors.
>
> **Solutions:**
>
> 1. Verify the `organization_manager` database exists in PostgreSQL
> 2. Check that the database user has appropriate permissions
> 3. Ensure network connectivity between the pod and PostgreSQL service
> 4. Verify the JDBC URL format is correct

> [accordion] SpiceDB connection failures
>
> **Symptoms:** Authorization errors or service fails to initialize CAS client.
>
> **Solutions:**
>
> 1. Verify SpiceDB is running and reachable at the configured host and port
> 2. Check that the SpiceDB token is correct
> 3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
> 4. Review pod logs for specific CAS client error messages

> [accordion] Kafka publishing failures
>
> **Symptoms:** Organization events not reaching downstream services.
>
> **Solutions:**
>
> 1. Verify Kafka bootstrap servers are reachable
> 2. Check that the `ai.flowx.organization.events.v1` topic exists
> 3. Ensure the service has producer permissions on the topic
> 4. Review `KAFKA_MESSAGE_MAX_BYTES` if large messages fail

> [accordion] Service account authentication errors
>
> **Symptoms:** 401/403 errors when communicating with other FlowX services.
>
> **Solutions:**
>
> 1. Verify the Keycloak service account is properly configured
> 2. Check that client secrets match between configuration and Keycloak
> 3. Ensure the service account has required roles assigned
> 4. Verify `SECURITY_TYPE` is set to `jwt-public-key`

***

## Related resources

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Access Management](./access-management/access-management-overview)
>
> Configure roles and access rights

> [card] [SpiceDB Configuration](./spicedb)
>
> Fine-grained authorization setup

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# Open Telemetry default properties
Source: https://docs.flowx.ai/5.9/setup-guides/ot-default-properties

Default OpenTelemetry configuration properties for FlowX.AI services, including Java agent settings, exporters, and resource attributes.

* `otel.resource.attributes=service.name=flowx-process-engine,service.version=1.1.1`: Environment variable.

> [!NOTE]
>
> Will be overridden as environment variable by Kubernetes operator. Useful for local development.

### Java agent configuration

* `otel.javaagent.enabled=true`
* `otel.javaagent.logging=simple`
* `otel.javaagent.debug=false`

### Disable OTEL SDK

* `otel.sdk.disabled=false`

## Exporters configuration (common config for all exporters)

* `otel.traces.exporter=otlp`
* `otel.metrics.exporter=otlp`
* `otel.logs.exporter=otlp`

### OTLP exporter

* `otel.exporter.otlp.endpoint=http://localhost:4317`

> [!NOTE]
>
> Endpoint will be overridden by Kubernetes operator. Useful for local development.

* `otel.exporter.otlp.protocol=grpc`
* `otel.exporter.otlp.timeout=10000`
* `otel.exporter.otlp.compression=gzip`
* `otel.exporter.otlp.metrics.temporality.preference=cumulative`
* `otel.exporter.otlp.metrics.default.histogram.aggregation=explicit_bucket_histogram`

### Tracer provider

> [!NOTE]
>
> `SdkTracerProvider` specific configuration options.

> [!NOTE]
>
> * Sampler: see the [OpenTelemetry sampler documentation](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#sampler)
> * The default sampler is: `parentbased_always_on`
> * To disable FlowX technical spans, add sampler: `fxTechnicalSpanFilterSampler`

* `otel.traces.sampler=parentbased_always_on`

### Batch span processor

* `otel.bsp.schedule.delay=5000`
* `otel.bsp.max.queue.size=2048`
* `otel.bsp.max.export.batch.size=512`
* `otel.bsp.export.timeout=30000`

### Meter provider

> [!NOTE]
>
> The following configuration options are specific to `SdkMeterProvider`.

* `otel.metric.export.interval=60000`
* `otel.metric.export.timeout=10000`

### Logger provider

> [!NOTE]
>
> The following configuration options are specific to `SdkLoggerProvider`.

* `otel.blrp.schedule.delay=1000`
* `otel.blrp.max.queue.size=2048`
* `otel.blrp.max.export.batch.size=512`
* `otel.blrp.export.timeout=30000`

## Agent auto-instrumentation

* `otel.instrumentation.messaging.experimental.receive-telemetry.enabled=false`
* `otel.instrumentation.common.experimental.controller-telemetry.enabled=true`
* `otel.instrumentation.common.experimental.view-telemetry.enabled=true`
* `otel.instrumentation.common.default-enabled=false`

> [!NOTE]
>
> Disable all auto instrumentation and enable only what's necessary. This has to be commented out entirely to work as default.

### Disable annotated methods

* `otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods=my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`

### Instrumentation config per library

> [!NOTE]
>
> Some instrumentation relies on other instrumentation to function properly. When selectively enabling instrumentation, be sure to enable the transitive dependencies too.

* `otel.instrumentation.opentelemetry-api.enabled=true`
* `otel.instrumentation.opentelemetry-instrumentation-annotations.enabled=true`
* `otel.instrumentation.opentelemetry-extension-annotations.enabled=false`
* `otel.instrumentation.methods.enabled=true`
* `otel.instrumentation.external-annotations.enabled=true`
* `otel.instrumentation.kafka.enabled=true`
* `otel.instrumentation.tomcat.enabled=true`
* `otel.instrumentation.elasticsearch-transport.enabled=true`
* `otel.instrumentation.elasticsearch-rest.enabled=true`
* `otel.instrumentation.grpc.enabled=true`
* `otel.instrumentation.hibernate.enabled=false`

> [!NOTE]
>
> Hibernate and JDBC kind of duplicate the queries traces

* `otel.instrumentation.hikaricp.enabled=false`

* `otel.instrumentation.java-http-client.enabled=true`

* `otel.instrumentation.http-url-connection.enabled=true`

* `otel.instrumentation.jdbc.enabled=false`

* `otel.instrumentation.jdbc-datasource.enabled=false`

* `otel.instrumentation.runtime-telemetry.enabled=true`

* `otel.instrumentation.servlet.enabled=true`

* `otel.instrumentation.executors.enabled=true`

* `otel.instrumentation.java-util-logging.enabled=true`

* `otel.instrumentation.log4j-appender.enabled=true`

* `otel.instrumentation.log4j-mdc.enabled=true`

* `otel.instrumentation.log4j-context-data.enabled=true`

* `otel.instrumentation.logback-appender.enabled=true`

* `otel.instrumentation.logback-mdc.enabled=true`

* `otel.instrumentation.mongo.enabled=true`

* `otel.instrumentation.rxjava.enabled=false`

* `otel.instrumentation.reactor.enabled=false`

### Redis client imported by spring-redis-data

* `otel.instrumentation.lettuce.enabled=true`

## Spring instrumentation props

* `otel.instrumentation.spring-batch.enabled=false`
* `otel.instrumentation.spring-core.enabled=true`
* `otel.instrumentation.spring-data.enabled=true`
* `otel.instrumentation.spring-jms.enabled=false`
* `otel.instrumentation.spring-integration.enabled=false`
* `otel.instrumentation.spring-kafka.enabled=true`
* `otel.instrumentation.spring-rabbit.enabled=false`
* `otel.instrumentation.spring-rmi.enabled=false`
* `otel.instrumentation.spring-scheduling.enabled=false`
* `otel.instrumentation.spring-web.enabled=true`
* `otel.instrumentation.spring-webflux.enabled=false`
* `otel.instrumentation.spring-webmvc.enabled=true`
* `otel.instrumentation.spring-ws.enabled=false`


# OCR plugin setup
Source: https://docs.flowx.ai/5.9/setup-guides/plugins-setup-guide/ocr-plugin-setup

The OCR plugin is a Docker image that can be deployed using the following infrastructure prerequisites.

## Infrastructure prerequisites

* S3 bucket or alternative (for example, minio)
* Kafka cluster

## Deployment/configuration

To deploy the OCR plugin, you will need to deploy `ocr-plugin` Helm chart with custom values file.

Most important sections are these, but more can be extracted from Helm chart.

```yaml theme={"dark"}
image:
  repository: <repository>/ocr-plugin

applicationSecrets: {}

replicaCount: 2

resources: {}
  
env: []
```

### Kafka configuration

You can override the following environment variables:

| Environment Variable | Definition | Default Value | Example |
| - | - | - | - |
| `ENABLE_KAFKA_SASL` | Indicates whether Kafka SASL authentication is enabled | `False` | - |
| `KAFKA_ADDRESS` | The address of the Kafka bootstrap server in the format `<hostname>:<port>` | - | `kafka-server1:9092` |
| `KAFKA_CONSUME_SCHEDULE` | The interval (in seconds) at which Kafka messages are consumed | `30` | - |
| `KAFKA_INPUT_TOPIC` | The Kafka topic from which input messages are consumed | - | - |
| `KAFKA_OCR_CONSUMER_GROUPID` | The consumer group ID for the OCR Kafka consumer | `ocr_group` | - |
| `KAFKA_CONSUMER_AUTO_COMMIT` | Determines whether Kafka consumer commits offsets automatically | `True` | - |
| `KAFKA_CONSUMER_AUTO_COMMIT_INTERVAL` | The interval (in milliseconds) at which Kafka consumer commits offsets automatically | `1000` | - |
| `KAFKA_CONSUMER_TIMEOUT` | The timeout (in milliseconds) for Kafka consumer operations | `28000` | - |
| `KAFKA_CONSUMER_MAX_POLL_INTERVAL` | The maximum interval (in milliseconds) between consecutive polls for Kafka consume | `25000` | - |
| `KAFKA_CONSUMER_AUTO_OFFSET_RESET` | The strategy for resetting the offset when no initial offset is available or if the current offset is invalid | `earliest` | - |
| `KAFKA_OUTPUT_TOPIC` | The Kafka topic to which output messages are sent | - | - |

Please note that the default values and examples provided here are for illustrative purposes. Make sure to replace them with the appropriate values based on your Kafka configuration.

> [!NOTE]
>
> When configuring the OCR plugin, make sure to use the correct outgoing topic names that match [**the pattern expected by the Engine**](../flowx-engine-setup-guide/engine-setup#configuring-kafka), which listens for messages on topics with specific names.

### Authorization

You can override the following environment variables:

| Environment Variable | Definition | Default Value | Example |
| - | - | - | - |
| `OAUTH_CLIENT_ID` | The client ID for OAuth authentication | - | `your_client_id` |
| `OAUTH_CLIENT_SECRET` | The client secret for OAuth authentication | - | `your_client_secret` |
| `OAUTH_TOKEN_ENDPOINT_URI` | The URI of the token endpoint for OAuth authentication | - | `https://oauth.example.com/token` |

Please note that the default values and examples provided here are for illustrative purposes. Make sure to replace them with the appropriate values based on your OAuth authentication configuration.

### Storage (S3 configuration)

You can override the following environment variables:

| Environment Variable | Definition | Default Value | Example |
| - | - | - | - |
| `STORAGE_S3_HOST` | The host address of the S3 storage service | - | `minio:9000`, `https://s3.eu-west-1.amazonaws.com/` |
| `STORAGE_S3_SECURE_CONNECTION` | Indicates whether to use a secure connection (HTTPS) for S3 storage | `False` | |
| `STORAGE_S3_LOCATION` | The location of the S3 storage service | - | `eu-west-1` |
| `STORAGE_S3_OCR_SCANS_BUCKET` | The name of the S3 bucket for storing OCR scans | - | `pdf-scans` |
| `STORAGE_S3_OCR_SIGNATURE_BUCKET` | The name of the S3 bucket for storing OCR signatures | - | `extracted-signatures` |
| `STORAGE_S3_OCR_SIGNATURE_FILENAME` | The filename pattern for extracted OCR signatures | - | `extracted_signature_{}.png` |
| `STORAGE_S3_ACCESS_KEY` | The access key for connecting to the S3 storage service | - | |
| `STORAGE_S3_SECRET_KEY` | The secret key for connecting to the S3 storage service | - | |

Please note that the default values and examples provided here are for illustrative purposes. Make sure to replace them with the appropriate values based on your S3 storage configuration.

### Performance

| Environment Variable | Definition | Default Value |
| - | - | - |
| `ENABLE_PERFORMANCE_PAYLOAD` | When set to true, the response payload will contain performance metrics related to various stages of the process. | `true` |

#### Example

```yaml theme={"dark"}
  "perf": {
    "total_time": 998,
    "split": {
      "get_file": 248,
      "extract_images": 172,
      "extract_barcodes": 37,
      "extract_signatures": 238,
      "minio_signature_save": 301
    }
  }
```

### Certificates

You can override the following environment variables:

| Environment Variable | Definition | Default Value |
| - | - | - |
| `REQUESTS_CA_BUNDLE` | The path to the certificate bundle file used for secure requests | `5` |
| `CERT_REQUESTS` | If no activity has occurred for a certain number of seconds, an attempt will be made to refresh the workers | `'CERT_REQUIRED'` |

### Workers behavior

You can override the following environment variables:

| Environment Variable | Definition | Default Value |
| - | - | - |
| `OCR_WORKER_COUNT` | Number of workers | `5` |
| `OCR_WORK_QUEUE_TIMEOUT` | If no activity has occurred for a certain number of seconds, an attempt will be made to refresh the workers | `10` |

> [!NOTE]
>
> If no worker is released after `OCR_WORK_QUEUE_TIMEOUT` seconds, the application will verify whether any workers have become unresponsive and need to be restarted.
>
> If none of the workers have died, it means they are likely blocked in some process. In this case, the application will terminate all the workers and shut down itself, hoping that the container will be restarted.

### Control aspect ratio

| Environment Variable | Definition | Default Value |
| - | - | - |
| `OCR_SIGNATURE_MAX_RATIO` | This variable sets the maximum acceptable aspect ratio for a signed scanned document (the OCR plugin will recognize a signature only if the document aspect ratio is less than or equal to the specified maximum ratio) | `1.43` |
| `OCR_SIGNATURE_MIN_RATIO` | This variable sets the minimum acceptable aspect ratio for a signed scanned document (the OCR plugin will consider a detected signature only if the document ratio is greater than or equal to the specified minimum ratio) | `1.39` |

> [!NOTE]
>
> The plugin has been tested with aspect ratio values between 1.39 and 1.43. However, caution is advised when using untested values outside this range, as they may potentially disrupt the functionality. Adjust these parameters at your own risk and consider potential consequences, as untested values might lead to plugin instability or undesired behavior.


# Plugins setup
Source: https://docs.flowx.ai/5.9/setup-guides/plugins-setup-guide/plugins-setup-guide-overview

To set up a plugin in your environment, you must go through the next steps.

* make sure you have all the prerequisites deployed on your environment (for example a [Redis](../../docs/platform-overview/frameworks-and-standards/event-driven-architecture-frameworks/intro-to-redis) cache instance, a DB instance, etc)
* make the necessary configurations for each plugin (DB connection data, related Kafka topic names, etc)

Once you have deployed the necessary plugins in your environment, you can start integrating them in your process definitions.

All of them listen for Kafka events sent by the **FlowX Engine** and perform certain actions depending on the received data. They can also send data back to the Engine.

Some of them require some custom templates to be configured, for these cases, a [WYSIWYG Editor](../../docs/platform-deep-dive/plugins/wysiwyg) is provided.

Let's go into more details on setting up and using each of them:

> [card] [OCR plugin](ocr-plugin-setup)

> [card] [Reporting](reporting-setup)


# Reporting setup
Source: https://docs.flowx.ai/5.9/setup-guides/plugins-setup-guide/reporting-setup

The Reporting setup guide assists in configuring the reporting plugin, relying on specific dependencies and configurations.

The FlowX Reporting solution provides data analytics and visualization capabilities for your FlowX platform. This guide offers step-by-step instructions for setting up and configuring all components of the reporting system.

The reporting solution consists of three main components:

* **Reporting Plugin**: Extracts and processes data from the FlowX Engine
* **Spark Application**: Handles data transformation and loading operations
* **Apache Superset**: Provides the visualization interface and dashboard capabilities

## Dependencies

The reporting plugin, available as a Docker image, requires the following dependencies:

* **PostgreSQL or Oracle**: Dedicated instance for reporting data storage.
* **MongoDB**: Read access to the `app-runtime` and `integration-designer` databases, which the plugin reads to resolve app versions and active builds.
* **Reporting-plugin Helm Chart**:
  * Utilizes a Spark Application to extract data from the FLOWX.AI Engine database and populate the Reporting plugin database.
  * Utilizes Spark Operator. For more information, see the [Spark Operator documentation](https://www.kubeflow.org/docs/components/spark-operator).
* **Superset**:
  * Requires a dedicated PostgreSQL database for its operation.
  * Utilizes Redis for efficient caching.
  * Exposes its user interface via an ingress.

## Prerequisites

Before starting the installation, ensure you have:

* Kubernetes cluster with Helm installed
* Access to the source and destination databases, each on PostgreSQL or Oracle:
  * FlowX Engine database (source)
  * Reporting database (destination)
* A PostgreSQL database for Superset metadata
* Access to the MongoDB databases `app-runtime` and `integration-designer`, each with its own user (typically `app-runtime` and `integration-designer`)
* Read access is enough on the engine database and on both MongoDB databases. Only the reporting database is written to.
* Access to the container registry that serves your reporting plugin image and Helm chart
* Redis instance for Superset caching
* Ingress controller for exposing Superset UI

> [!NOTE]
>
> The engine and reporting databases each run on PostgreSQL or Oracle. Set `ENGINE_DATABASE_TYPE` and `REPORTING_DATABASE_TYPE` to `postgres` or `oracle` to match. The runtime and integration databases are always MongoDB.
>
> On Oracle, the plugin reads the UUID columns as `RAW(16)`, which is what the FlowX Liquibase scripts create.

> [!WARNING]
>
> Create a separate MongoDB user for each of the two databases, inside the database it reads. The plugin's connection string carries no `authSource`, so each connection authenticates against the database it targets. A single user created in a shared authentication database fails to authenticate.

## Reporting plugin helm chart configuration

Configuring the reporting plugin involves several steps:

### Installation of Spark Operator

1. Install the Spark Operator using Helm:

```bash theme={"dark"}
helm install local-spark-release spark-operator/spark-operator \
--namespace spark-operator --create-namespace \
--set webhook.enable=true \
--set logLevel=6
```

2. Apply RBAC configurations:

```bash theme={"dark"}
kubectl apply -f spark-rbac.yaml
```

3. Pull the reporting plugin image from the container registry provisioned for your deployment. Building the image locally is not required.

4. Update the `reporting-image` URL in the `spark-app.yml` file.

5. Configure the correct database ENV variables in the `spark-app.yml` file (check them in the above examples with/without webhook).

6. Deploy the application:

```bash theme={"dark"}
kubectl apply -f operator/spark-app.yaml
```

## Spark Operator deployment options

### Without webhook

For deployments without a webhook, manage secrets and environmental variables for security:

```yaml theme={"dark"}
sparkApplication: #Defines the Spark application configuration.
  enabled: "true" #Indicates that the Spark application is enabled for deployment.
  schedule: "@every 5m" #A cronJob that should run at every 5 minutes.
  driver: # This section configures the driver component of the Spark application.
    envVars: #Environment variables for driver setup.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      RUNTIME_DATABASE_USER: app-runtime
      RUNTIME_DATABASE_URL: mongodb:27017
      RUNTIME_DATABASE_NAME: app-runtime
      RUNTIME_DATABASE_TYPE: mongo
      INTEGRATION_DATABASE_USER: integration-designer
      INTEGRATION_DATABASE_URL: mongodb:27017
      INTEGRATION_DATABASE_NAME: integration-designer
      INTEGRATION_DATABASE_TYPE: mongo
      ENGINE_DATABASE_PASSWORD: "password"
      REPORTING_DATABASE_PASSWORD: "password"
      RUNTIME_DATABASE_PASSWORD: "password"
      INTEGRATION_DATABASE_PASSWORD: "password"

  executor: #This section configures the executor component of the Spark application.
    envVars: #Environment variables for executor setup.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      RUNTIME_DATABASE_USER: app-runtime
      RUNTIME_DATABASE_URL: mongodb:27017
      RUNTIME_DATABASE_NAME: app-runtime
      RUNTIME_DATABASE_TYPE: mongo
      INTEGRATION_DATABASE_USER: integration-designer
      INTEGRATION_DATABASE_URL: mongodb:27017
      INTEGRATION_DATABASE_NAME: integration-designer
      INTEGRATION_DATABASE_TYPE: mongo
      ENGINE_DATABASE_PASSWORD: "password"
      REPORTING_DATABASE_PASSWORD: "password"
      RUNTIME_DATABASE_PASSWORD: "password"
      INTEGRATION_DATABASE_PASSWORD: "password"
      
```

> [!NOTE]
>
> NOTE: Passwords are currently set as plain strings, which is not secure practice in a production environment.

### With webhook

When using the webhook, employ environmental variables with secrets for a balanced security approach:

```yaml theme={"dark"}
sparkApplication:
  enabled: "true"
  schedule: "@every 5m"
  driver:
    env: #Environment variables for driver setup with secrets.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle     
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      RUNTIME_DATABASE_USER: app-runtime
      RUNTIME_DATABASE_URL: mongodb:27017
      RUNTIME_DATABASE_NAME: app-runtime
      RUNTIME_DATABASE_TYPE: mongo
      INTEGRATION_DATABASE_USER: integration-designer
      INTEGRATION_DATABASE_URL: mongodb:27017
      INTEGRATION_DATABASE_NAME: integration-designer
      INTEGRATION_DATABASE_TYPE: mongo
    extraEnvVarsMultipleSecretsCustomKeys: 
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
      - name: mongodb-generic
        secrets:
          RUNTIME_DATABASE_PASSWORD: mongodb-password
          INTEGRATION_DATABASE_PASSWORD: mongodb-password
  executor:
    env: #Environment variables for executor setup with secrets.
      ENGINE_DATABASE_USER: flowx
      ENGINE_DATABASE_URL: postgresql:5432
      ENGINE_DATABASE_NAME: process_engine
      ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
      REPORTING_DATABASE_USER: flowx
      REPORTING_DATABASE_URL: postgresql:5432
      REPORTING_DATABASE_NAME: reporting
      REPORTING_DATABASE_TYPE: postgres
      RUNTIME_DATABASE_USER: app-runtime
      RUNTIME_DATABASE_URL: mongodb:27017
      RUNTIME_DATABASE_NAME: app-runtime
      RUNTIME_DATABASE_TYPE: mongo
      INTEGRATION_DATABASE_USER: integration-designer
      INTEGRATION_DATABASE_URL: mongodb:27017
      INTEGRATION_DATABASE_NAME: integration-designer
      INTEGRATION_DATABASE_TYPE: mongo
    extraEnvVarsMultipleSecretsCustomKeys:
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
      - name: mongodb-generic
        secrets:
          RUNTIME_DATABASE_PASSWORD: mongodb-password
          INTEGRATION_DATABASE_PASSWORD: mongodb-password
```

> [!NOTE]
>
> In Kubernetes-based Spark deployments managed by the Spark Operator, you can define the sparkApplication configuration to customize the behavior, resources, and environment for both the driver and executor components of Spark jobs. The driver section allows fine-tuning of parameters specifically pertinent to the driver part of the Spark application.

Below are the configurable values within the chart values.yml file (with webhook):

```yml theme={"dark"}
apiVersion: "sparkoperator.k8s.io/v1beta2"
kind: ScheduledSparkApplication
metadata:
  name: reporting-plugin-spark-app
  namespace: dev
  labels:
    app.kubernetes.io/component: reporting
    app.kubernetes.io/instance: reporting-plugin
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: reporting-plugin
    app.kubernetes.io/release: 0.0.1-FLOWXRELEASE
    app.kubernetes.io/version: 0.0.1-FLOWXVERSION
    helm.sh/chart: reporting-plugin-0.2.4
spec:
  schedule: '@every 5m'
  concurrencyPolicy: Forbid
  template:
    type: Python
    pythonVersion: "3"
    mode: cluster
    image: <your-registry>/reporting-plugin:<version>
    imagePullPolicy: IfNotPresent
    mainApplicationFile: local:///opt/spark/work-dir/main.py
    sparkVersion: "3.5.8"
    restartPolicy:
      type: Never
      onFailureRetries: 0
      onFailureRetryInterval: 10
      onSubmissionFailureRetries: 5
      onSubmissionFailureRetryInterval: 20
    driver:
      cores: 1
      coreLimit: 1200m
      memory: 1024m
      labels:
        version: 3.5.8
      serviceAccount: spark
      env:
        ENGINE_DATABASE_USER: flowx
        ENGINE_DATABASE_URL: postgresql:5432
        ENGINE_DATABASE_NAME: process_engine
        ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
        REPORTING_DATABASE_USER: flowx
        REPORTING_DATABASE_URL: postgresql:5432
        REPORTING_DATABASE_NAME: reporting
        REPORTING_DATABASE_TYPE: postgres
        RUNTIME_DATABASE_USER: app-runtime
        RUNTIME_DATABASE_URL: mongodb:27017
        RUNTIME_DATABASE_NAME: app-runtime
        RUNTIME_DATABASE_TYPE: mongo
        INTEGRATION_DATABASE_USER: integration-designer
        INTEGRATION_DATABASE_URL: mongodb:27017
        INTEGRATION_DATABASE_NAME: integration-designer
        INTEGRATION_DATABASE_TYPE: mongo
        ENGINE_DATABASE_PASSWORD: "password"
        REPORTING_DATABASE_PASSWORD: "password"
        RUNTIME_DATABASE_PASSWORD: "password"
        INTEGRATION_DATABASE_PASSWORD: "password"
    extraEnvVarsMultipleSecretsCustomKeys: 
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
      - name: mongodb-generic
        secrets:
          RUNTIME_DATABASE_PASSWORD: mongodb-password
          INTEGRATION_DATABASE_PASSWORD: mongodb-password
    executor:
      cores:  1
      instances: 1
      memory: 512m
      labels:
        version: 3.5.8
      env: #Environment variables for executor setup with secrets.
        ENGINE_DATABASE_USER: flowx
        ENGINE_DATABASE_URL: postgresql:5432
        ENGINE_DATABASE_NAME: process_engine
        ENGINE_DATABASE_TYPE: postgres # To set the type of engine database, can be also changed to oracle
        REPORTING_DATABASE_USER: flowx
        REPORTING_DATABASE_URL: postgresql:5432
        REPORTING_DATABASE_NAME: reporting
        REPORTING_DATABASE_TYPE: postgres
        RUNTIME_DATABASE_USER: app-runtime
        RUNTIME_DATABASE_URL: mongodb:27017
        RUNTIME_DATABASE_NAME: app-runtime
        RUNTIME_DATABASE_TYPE: mongo
        INTEGRATION_DATABASE_USER: integration-designer
        INTEGRATION_DATABASE_URL: mongodb:27017
        INTEGRATION_DATABASE_NAME: integration-designer
        INTEGRATION_DATABASE_TYPE: mongo
    extraEnvVarsMultipleSecretsCustomKeys:
      - name: postgresql-generic
        secrets: #Secrets retrieved from a generic source.
          ENGINE_DATABASE_PASSWORD: postgresql-password
          REPORTING_DATABASE_PASSWORD: postgresql-password
      - name: mongodb-generic
        secrets:
          RUNTIME_DATABASE_PASSWORD: mongodb-password
          INTEGRATION_DATABASE_PASSWORD: mongodb-password
```

> [!NOTE]
>
> `sparkApplication.sparkVersion` has no default in the chart, so it must be set explicitly. It has to match the Spark version in the plugin image.

The values below are the chart defaults.

| Parameter | Default | Description |
| - | - | - |
| **sparkApplication.driver.cores** | `1` | Driver CPU request |
| **sparkApplication.driver.coreLimit** | `1200m` | Driver CPU limit |
| **sparkApplication.driver.memory** | `1024m` | Driver memory |
| **sparkApplication.executor.cores** | `1` | See the note on executor sizing below |
| **sparkApplication.executor.instances** | `1` | See the note on executor sizing below |
| **sparkApplication.executor.memory** | `512m` | See the note on executor sizing below |
| **sparkApplication.schedule** | `@every 5m` | Extraction interval |
| **sparkApplication.concurrencyPolicy** | `Forbid` | Prevents overlapping runs |

Driver cores and memory are the values to raise if the extraction job does not finish inside the refresh interval.

> [!NOTE]
>
> Executor sizing is not driven by the chart values. The plugin builds its Spark session from the `spark.conf` file in the image, which ships `spark.executor.cores = 2`, `spark.executor.memory = 1024m` and `spark.executor.inst.max = 5`, the ceiling on the number of executors. It then recalculates the executor count at every run from the volume of data to be processed: one executor for small deltas, up to that ceiling for large ones.

### Limiting the reporting scope

By default the plugin reports on every workspace. To restrict it to a single workspace, set `WORKSPACE_ID` on the driver and executor to that workspace UUID.

***

### Superset configuration

Detailed Superset Configuration Guide:

> [card] [Superset configuration](https://github.com/apache/superset/blob/master/helm/superset/README.md)

> [card] [Superset docker image](https://hub.docker.com/r/apache/superset)

Refer to Superset Documentation for in-depth information:

> [card] [Superset documentation](https://superset.apache.org/docs/intro/)

## Post-installation steps

After installation, perform the following essential configurations:

### Datasource configuration

For document-related data storage, configure these environment variables:

* `SPRING_DATASOURCE_URL`
* `SPRING_DATASOURCE_USERNAME`
* `SPRING_DATASOURCE_PASSWORD`

Ensure accurate details to prevent startup errors. The Liquibase script manages schema and migrations.

### Redis configuration

The following values should be set with the corresponding Redis-related values:

* `SPRING_REDIS_HOST`
* `SPRING_REDIS_PORT`

## Superset single sign-on

Superset authenticates users against your identity provider over OpenID Connect, using Flask-AppBuilder's OAuth support, and maps a claim from the token to a Superset role at every login.

> [!WARNING]
>
> Configure `AUTH_OAUTH`, not `AUTH_OID`. The older `flask-oidc` approach is not the configuration FlowX runs and is not what the Superset image is built for.

### Image requirements

The Superset image needs `authlib` for OAuth and `psycopg2-binary` for its PostgreSQL metadata database. Build them into the image rather than installing them at pod start, so the cluster needs no access to a public package index.

### Superset configuration

Add the following to `configOverrides` in your Superset values, replacing the provider details with your own:

```python theme={"dark"}
import os
from flask_appbuilder.security.manager import AUTH_OAUTH
from superset.security import SupersetSecurityManager

SECRET_KEY = os.environ["SUPERSET_SECRET_KEY"]

ENABLE_PROXY_FIX = True

AUTH_TYPE = AUTH_OAUTH
AUTH_USER_REGISTRATION = True
AUTH_USER_REGISTRATION_ROLE = "Public"
AUTH_ROLES_SYNC_AT_LOGIN = True
AUTH_ROLES_MAPPING = {
    "superset-admins": ["Admin"],
    "superset-analysts": ["Alpha"],
}

OAUTH_PROVIDERS = [
    {
        "name": "keycloak",
        "icon": "fa-key",
        "token_key": "access_token",
        "remote_app": {
            "client_id": "superset",
            "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
            "server_metadata_url": f"{os.environ['KEYCLOAK_ISSUER']}/.well-known/openid-configuration",
            "client_kwargs": {"scope": "openid email profile"},
        },
    }
]

class KeycloakSecurityManager(SupersetSecurityManager):
    def get_oauth_user_info(self, provider, response=None):
        if provider == "keycloak":
            remote = self.appbuilder.sm.oauth_remotes[provider]
            me = (response or {}).get("userinfo") or remote.userinfo()
            name = (me.get("name") or "").strip()
            first, _, last = name.partition(" ")
            return {
                "username": me.get("email"),
                "email": me.get("email"),
                "first_name": me.get("given_name") or first,
                "last_name": me.get("family_name") or last,
                "role_keys": me.get("groups", []),
            }
        return super().get_oauth_user_info(provider, response)

CUSTOM_SECURITY_MANAGER = KeycloakSecurityManager
```

`role_keys` is what `AUTH_ROLES_MAPPING` matches on, so the group names returned by your identity provider have to match the keys in that map. A user who is in none of the mapped groups gets the role set in `AUTH_USER_REGISTRATION_ROLE`.

> [!NOTE]
>
> `SECRET_KEY` must be a strong random value, supplied as a Kubernetes secret, and it has to stay stable for the lifetime of the installation. Rotating it invalidates active sessions and any encrypted metadata Superset holds.

### Identity provider setup

Register a confidential client for Superset using the authorization code flow, then:

**1. Set the redirect URI**

The callback path is `/oauth-authorized/{provider-name}`, where the provider name is the `name` field from `OAUTH_PROVIDERS`. With the example above, the redirect URI is `https://{your-superset-host}/oauth-authorized/keycloak`.

**2. Add the scopes and a group claim**

Request `openid email profile`, and add a mapper that puts the user's groups into the user-info response. Superset reads that claim at every login to assign a role, so without it no user gets access beyond the default role.

On Keycloak, attach the mapper to the client itself, as described below. Some other providers expose groups only through a dedicated scope, in which case add that scope to `client_kwargs`.

**3. Create the access groups**

Create one group per Superset role you want to grant and add the members. Map them in `AUTH_ROLES_MAPPING`.

> [!WARNING]
>
> Superset runs behind a proxy-aware configuration. Your ingress must forward the original protocol and host through `X-Forwarded-*` headers, otherwise the sign-on redirect is built with the wrong scheme and login fails.

### Group claim on Keycloak

The groups claim comes from a **Group Membership** mapper on the Superset client, the same mapper type FlowX uses on the platform client. For the step-by-step, see [Group membership mapper](../access-management/configuring-an-iam-solution#group-membership-mapper), and set it as follows:

| Setting | Value | Why |
| - | - | - |
| **Mapper Type** | Group Membership | Puts the user's group memberships into the token |
| **Token Claim Name** | `groups` | Must match the claim the security manager reads |
| **Full group path** | Toggle **OFF** for plain names, **ON** for paths | Determines whether the claim carries `superset-admins` or `/superset-admins` |
| **Add to userinfo** | Toggle **ON** | The security manager above reads the claim from the user-info response, so this is required |
| **Add to access token** | Toggle **ON** | |

> [!WARNING]
>
> The keys in `AUTH_ROLES_MAPPING` must match the claim exactly. With **Full group path** ON, the group appears as `/superset-admins` and a key of `superset-admins` never matches, leaving every user on the default role.

> [!WARNING]
>
> **If your users are federated from another identity provider**, a Group Membership mapper emits nothing for them. Federated users are not members of any Keycloak group unless something puts them in one: FlowX's own [IDP federation](../access-management/runtime-authorization#per-organization-idp-federation) carries group names in a user attribute instead. You have two options:
>
> * Map the incoming claim to real Keycloak groups with an **Advanced Claim to Group** mapper on the federated identity provider, then use the Group Membership mapper above.
> * Or emit the user attribute directly, by replacing the Group Membership mapper with a **User Attribute** mapper whose token claim name is `groups`.
>
> Either way, confirm which form actually reaches Superset before writing the `AUTH_ROLES_MAPPING` keys. Group identifiers from an external provider are often opaque IDs rather than names.

For the full list of provider options, see the [Flask-AppBuilder OAuth documentation](https://flask-appbuilder.readthedocs.io/en/latest/security.html).


# Qdrant setup
Source: https://docs.flowx.ai/5.9/setup-guides/qdrant

This guide covers the deployment and configuration of Qdrant, the vector database used by the FlowX AI Platform for knowledge-base embeddings and retrieval.

## Overview

Qdrant is a vector database used by the FlowX AI Platform to store and search the dense and sparse embeddings that power Knowledge Base indexing and retrieval (RAG). It is consumed by the AI Platform services — primarily the `embedder` and `knowledgebase-rag` services.

> [!NOTE]
>
> **Bundled with the AI Platform.** Qdrant is shipped by FlowX as a subchart of the AI Platform Helm chart — it is deployed and version-managed by that chart, not installed separately. Configure it through the `qdrant:` block of your AI Platform values. The version is set by the chart and is not pinned in the FlowX component matrix.

> [!NOTE]
>
> For more information about Qdrant, see the [Qdrant documentation](https://qdrant.tech/documentation/).

## Prerequisites

> [card] Infrastructure
>
> * Kubernetes cluster with admin access
> * Persistent storage (block storage) for vector data and snapshots
> * Network connectivity between Qdrant and the AI Platform services

> [card] FlowX Integration
>
> * AI Platform chart deployed (Qdrant is a subchart of it)
> * A Kubernetes secret holding the Qdrant API key
> * AI services configured with the Qdrant connection variables

## Deployment

Qdrant is enabled and configured through the `qdrant:` block of the AI Platform Helm values. A typical configuration:

```yaml theme={"dark"}
qdrant:
  resources:
    requests:
      cpu: 200m
      memory: 1Gi
    limits:
      cpu: 2
      memory: 2Gi
  config:
    cluster:
      enabled: false
  apiKey:
    valueFrom:
      secretKeyRef:
        name: qdrant-generic
        key: apikey
```

> [!NOTE]
>
> The Qdrant service is exposed inside the cluster as `qdrant-headless` starting with 5.9.2 (`ai-platform-qdrant-headless` on 5.9.0/5.9.1), serving gRPC on port **6334** and the REST/health API on port **6333**. If you reference the Qdrant host explicitly in any service configuration, update it when upgrading to 5.9.2 — see the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming).

### API key secret

Qdrant authenticates clients with an API key, supplied through a Kubernetes secret. Create a secret named `qdrant-generic` with an `apikey` entry:

```yaml theme={"dark"}
apiVersion: v1
kind: Secret
metadata:
  name: qdrant-generic
type: Opaque
data:
  apikey: <base64-encoded-api-key>
```

> [!TIP]
>
> Generate a secure API key with `openssl rand -base64 32` and base64-encode it for the secret.

> [!WARNING]
>
> The API key in the `qdrant-generic` secret must match the `QDRANT_CONNECTION_API_KEY` configured on the AI Platform services that connect to Qdrant.

### Storage

Provision persistent volumes for Qdrant. Recommended baseline sizes:

| Volume | Size | Purpose |
| - | - | - |
| Qdrant data | 30Gi | Vector embeddings |
| Qdrant snapshots | 30Gi | Backup snapshots |

> [!WARNING]
>
> Size the data volume to your Knowledge Base footprint. Vector storage grows with the number and dimensionality of indexed documents.

## Connecting the AI Platform services

The AI Platform services read the following variables to reach Qdrant. The connection values are set by default in the chart; supply the API key from the `qdrant-generic` secret.

| Variable | Description | Default Value |
| - | - | - |
| `QDRANT_CONNECTION_GRPC_ENDPOINT` | Qdrant gRPC endpoint | — |
| `QDRANT_CONNECTION_API_KEY` | Qdrant API key | — |
| `QDRANT__CLUSTER__ENABLED` | Enable Qdrant cluster mode | `true` |

> [!NOTE]
>
> The `knowledgebases_design` collection is created automatically by the `embedder` service on first use — no manual provisioning step is required.

### Search tuning (knowledgebase-rag)

These limits control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Both are read at request time, so changing them does not require a redeploy beyond the env-var rollout.

| Variable | Description | Default Value |
| - | - | - |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. Lower values reduce Qdrant memory pressure on large KBs. | `100` |
| `QDRANT_FUSION_LIMIT` | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker's input set. | `80` |

> [!TIP]
>
> Defaults are tuned for typical Knowledge Bases. Raise them only if recall is insufficient for very large or long-tailed KBs; lower them if you see Qdrant memory pressure or slow queries under filter-heavy workloads.

### Planner seeding

| Variable | Description | Default Value |
| - | - | - |
| `PLANNER_SEED_ENABLED` | When `true`, the `planner` service seeds its Qdrant benchmark collection on startup. Leave off unless seeding is required. | `false` |

## Verification

**1. Check Qdrant pods**

Ensure the Qdrant pods are running:

```bash theme={"dark"}
kubectl get pods -l app.kubernetes.io/name=qdrant
```

**2. Test the health endpoint**

Verify Qdrant is responding on the REST port:

```bash theme={"dark"}
kubectl port-forward svc/qdrant-headless 6333:6333   # 5.9.0/5.9.1: svc/ai-platform-qdrant-headless
# From another terminal
curl http://localhost:6333/healthz
```

**3. Check AI Platform integration**

Review the embedder logs for a successful Qdrant connection:

```bash theme={"dark"}
kubectl logs -l app=embedder | grep -i qdrant   # 5.9.0/5.9.1: -l app=ai-platform-embedder
```

> [!WARNING]
>
> Common connection failures: a missing `QDRANT_CONNECTION_API_KEY`, a key that does not match the `qdrant-generic` secret, or the Qdrant cluster not being fully initialized.

## Related resources

> [card] [AI Platform setup](/5.9/setup-guides/ai-platform-setup)
>
> Full AI Platform deployment, including the services that consume Qdrant

> [card] [Knowledge Base RAG](/5.9/ai-platform/patterns/knowledge-base-rag)
>
> How retrieval-augmented generation uses the vector store


# Redis configuration
Source: https://docs.flowx.ai/5.9/setup-guides/redis-configuration

Configure Redis deployment modes for FlowX platform services

## Overview

FlowX platform services use Redis for caching and real-time data management. Redis can be deployed in three different modes depending on your availability and scalability requirements.

All FlowX Java microservices support the same Redis configuration properties based on Spring Boot's Redis data configuration.

## Supported deployment modes

FlowX supports three Redis deployment modes:

* **Standalone**: Single Redis instance (suitable for development and low-traffic environments)
* **Sentinel**: High availability with automatic failover (recommended for production)
* **Cluster**: Horizontal scaling with data sharding (for high-throughput applications)

> [!WARNING]
>
> Master-Replica mode is not supported. Use Sentinel mode for high availability with automatic failover, or Cluster mode for horizontal scaling.

## Standalone mode

The default configuration for single Redis instance deployments.

### Configuration parameters

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Hostname of the Redis server | `localhost` or `redis.example.com` | Yes |
| `SPRING_DATA_REDIS_PORT` | Port number for Redis server | `6379` (default) | Yes |
| `SPRING_DATA_REDIS_PASSWORD` | Password for Redis authentication | `yourpassword` | If authentication is enabled |
| `SPRING_DATA_REDIS_SSL_ENABLED` | Enable SSL/TLS connection | `true` or `false` | No |

### Example configuration

```yaml theme={"dark"}
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: yourpassword
      ssl:
        enabled: false
```

## Sentinel mode

For high-availability Redis with automatic failover. Sentinel provides monitoring, notification, and automatic failover capabilities.

### Configuration parameters

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SPRING_DATA_REDIS_SENTINEL_MASTER` | Name of the Redis master instance | `mymaster` | Yes |
| `SPRING_DATA_REDIS_SENTINEL_NODES` | Comma-separated list of Sentinel nodes (host:port format) | `host1:26379,host2:26379,host3:26379` | Yes |
| `SPRING_DATA_REDIS_SENTINEL_PASSWORD` | Password for Sentinel authentication | `sentinelpassword` | If Sentinel authentication is enabled |
| `SPRING_DATA_REDIS_PASSWORD` | Password for Redis data node authentication | `yourpassword` | If Redis authentication is enabled |

### Example configuration

```yaml theme={"dark"}
spring:
  data:
    redis:
      sentinel:
        master: mymaster
        nodes: sentinel1:26379,sentinel2:26379,sentinel3:26379
        password: sentinelpassword
      password: yourpassword
```

### Important notes

> [!NOTE]
>
> * The `SPRING_DATA_REDIS_SENTINEL_NODES` must include all Sentinel instances for redundancy
> * Sentinel typically runs on port `26379` (different from Redis data port `6379`)
> * The master name (`SPRING_DATA_REDIS_SENTINEL_MASTER`) must match the master configured in your Sentinel setup
> * Both Sentinel password and Redis password can be configured independently

## Cluster mode

For Redis cluster deployments with data sharding across multiple nodes, providing horizontal scalability.

### Configuration parameters

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SPRING_DATA_REDIS_CLUSTER_NODES` | Comma-separated list of cluster nodes (host:port format) | `host1:6379,host2:6379,host3:6379` | Yes |
| `SPRING_DATA_REDIS_PASSWORD` | Password for Redis cluster authentication | `yourpassword` | If authentication is enabled |

### Example configuration

```yaml theme={"dark"}
spring:
  data:
    redis:
      cluster:
        nodes: node1:6379,node2:6379,node3:6379
      password: yourpassword
```

### Important notes

> [!NOTE]
>
> * You only need to specify a subset of cluster nodes; the Redis client will discover all nodes automatically
> * At least 3 master nodes are recommended for a production Redis cluster
> * Data is automatically sharded across cluster nodes

## Choosing the right deployment mode

Use this guide to select the appropriate Redis deployment mode:

> [tab] Development & Testing
>
> **Standalone mode** is suitable for:
>
> * Development environments
> * Testing and staging environments
> * Low-traffic applications
> * Single-server deployments
>
> **Considerations:**
>
> * No automatic failover
> * Single point of failure
> * Simplest to set up and maintain

> [tab] Production - High Availability
>
> **Sentinel mode** is recommended for:
>
> * Production environments requiring high availability
> * Applications that need automatic failover
> * Deployments where downtime is not acceptable
> * Single-master write scenarios
>
> **Considerations:**
>
> * Automatic failover to replica nodes
> * Monitoring and notifications
> * More complex setup than standalone
> * No data sharding (vertical scaling)

> [tab] Production - High Throughput
>
> **Cluster mode** is ideal for:
>
> * High-throughput applications
> * Large datasets requiring data sharding
> * Horizontal scaling requirements
> * Multi-master write scenarios
>
> **Considerations:**
>
> * Data automatically distributed across nodes
> * Horizontal scalability
> * Most complex to set up and maintain
> * Different behavior than single-instance Redis (some commands not supported)

## SSL/TLS configuration

For secure Redis connections, you can enable SSL/TLS:

| Environment Variable | Description | Example Value |
| - | - | - |
| `SPRING_DATA_REDIS_SSL_ENABLED` | Enable SSL/TLS for Redis connections | `true` |

```yaml theme={"dark"}
spring:
  data:
    redis:
      ssl:
        enabled: true
```

> [!NOTE]
>
> SSL/TLS configuration is supported in all deployment modes (Standalone, Sentinel, and Cluster).

## Additional configuration options

### Connection timeout

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_REDIS_TIMEOUT` | Connection timeout in milliseconds | `2000` |

### TTL (Time To Live)

Some services support custom TTL configuration for cached data:

| Environment Variable | Description | Default Value |
| - | - | - |
| `REDIS_TTL` | Time to live for cached entries in milliseconds | Service-specific |

> [!NOTE]
>
> Check individual service setup guides for service-specific Redis configuration options.

## Applying configuration

**1. Choose your deployment mode**

Select the appropriate Redis deployment mode based on your requirements (Standalone, Sentinel, or Cluster).

**2. Set environment variables**

Configure the required environment variables for your chosen deployment mode in your deployment configuration (Kubernetes ConfigMap, Docker Compose, etc.).

**3. Verify Redis connectivity**

Ensure your FlowX services can reach the Redis instance(s) on the network level.

**4. Test the configuration**

Deploy your services and verify Redis connectivity through service logs and health checks.

## Services using Redis

The following FlowX services use Redis and support these configuration options:

* Events Gateway
* Authorization System
* FlowX Engine
* Notification Plugin
* Document Plugin
* OCR Plugin
* Task Management Plugin

> [!NOTE]
>
> For service-specific Redis configuration details, refer to the individual setup guides in the [Setup Guides section](/5.9/setup-guides/setup-guides-overview).

## Troubleshooting

### Connection issues

If services cannot connect to Redis:

1. **Verify network connectivity**: Ensure the service can reach Redis hosts on the configured ports
2. **Check authentication**: Verify the password is correct
3. **Review firewall rules**: Ensure no firewall is blocking Redis ports
4. **Validate configuration**: Double-check environment variable names and values

### Sentinel mode issues

If Sentinel failover is not working:

1. **Verify master name**: Ensure `SPRING_DATA_REDIS_SENTINEL_MASTER` matches your Sentinel configuration
2. **Check all Sentinel nodes**: All Sentinel instances should be reachable
3. **Review Sentinel logs**: Check Sentinel logs for failover events
4. **Validate Sentinel password**: If using Sentinel authentication, ensure `SPRING_DATA_REDIS_SENTINEL_PASSWORD` is correct

### Cluster mode issues

If cluster operations fail:

1. **Verify cluster health**: Check Redis cluster status with `CLUSTER INFO`
2. **Ensure minimum nodes**: At least 3 master nodes should be running
3. **Check node discovery**: Ensure the service can discover all cluster nodes
4. **Review unsupported commands**: Some Redis commands are not supported in cluster mode

## Related documentation

> [card] [Kafka Authentication](/5.9/setup-guides/kafka-authentication-config)
>
> Configure secure Kafka communication

> [card] [Events Gateway Setup](/5.9/setup-guides/events-gateway-setup)
>
> Complete Events Gateway configuration

> [card] [Setup Guides Overview](/5.9/setup-guides/setup-guides-overview)
>
> View all setup guides


# Runtime manager setup
Source: https://docs.flowx.ai/5.9/setup-guides/runtime-manager

This guide provides a step-by-step process for setting up and configuring the Runtime Manager module, including database, Kafka, and OAuth2 authentication settings to manage runtime and build configurations.

> [!NOTE]
>
> The [**Application Manager**](./application-manager) and **Runtime Manager** share the same container image and Helm chart. Refer to the **Deployment Guidelines** in the release notes to ensure compatibility and verify the correct version.

## Infrastructure prerequisites

The Runtime Manager service requires the following components to be set up before it can be started:

* **PostgreSQL**
* **MongoDB**
* **Redis**
* **Kafka**
* **OAuth2 Authentication**

## Dependencies

* [**Database configuration**](#database-configuration)
* [**Kafka configuration**](#kafka-configuration)
* [**Authentication & access roles**](#authentication-configuration)
* [**Logging**](./setup-guides-overview#logging-configuration)

## Change the application name

| Environment Variable | Description | Example Value |
| - | - | - |
| `SPRING_APPLICATION_NAME` | Service identifier used for service discovery and logging | `runtime-manager` |

> [!WARNING]
>
> Default Value: `application-manager -> must be changed to `runtime-manager

## Core service configuration

| Environment Variable | Description | Example Value |
| - | - | - |
| `LOGGING_CONFIG` | Path to logging configuration file | `logback-spring.xml` |
| `MULTIPART_MAX_FILE_SIZE` | Maximum file size for uploads | `25MB` |
| `MULTIPART_MAX_REQUEST_SIZE` | Maximum total request size | `25MB` |

## Database configuration

The Runtime Manager uses the same PostgreSQL (to store application data) and MongoDB (to manage runtime data) as [**application-manager**](application-manager). Configure these database connections with the following environment variables:

### PostgreSQL (Application data)

| Environment Variable | Description | Example Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC URL for PostgreSQL connection | `jdbc:postgresql://postgresql:5432/app_manager` |
| `SPRING_DATASOURCE_USERNAME` | PostgreSQL username | `flowx` |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL password | *sensitive* |

### MongoDB (Runtime data)

| Environment Variable | Description | Example Value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | URI for MongoDB connection | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-headless:27017/${DB_NAME}?retryWrites=false` |
| `DB_NAME` | MongoDB database name | `app-runtime` |
| `DB_USERNAME` | MongoDB username | `app-runtime` |
| `DB_PASSWORD` | MongoDB password | *sensitive* |

## Redis configuration

Runtime Manager uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

## Kafka configuration

### Kafka connection

| Environment Variable | Description | Example Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Kafka broker addresses | `kafka-flowx-kafka-bootstrap:9092` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment prefix for Kafka topics | |

### Kafka OAuth authentication

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

### Kafka topics

Since the Runtime Manager shares the same container image as the [Application Manager](./application-manager), it uses the same Kafka topic definitions. However, the Runtime Manager conditionally activates a listener for the `build.runtime-data` topic (based on `spring.application.name=runtime-manager`), which is how it receives runtime data from the Admin service.

> [!WARNING]
>
> The `KAFKA_TOPIC_BUILD_RUNTIMEDATA` topic must resolve to the same value in both Admin and Runtime Manager. If the `KAFKA_TOPIC_NAMING_ENVIRONMENT` prefix differs between services (common after export/import to a new environment), Admin will produce to one topic and Runtime Manager will consume from another, causing data not to be passed back to the calling process after subprocess execution.

#### Build topics

| Environment Variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | Build runtime data topic (consumed only by Runtime Manager) | `ai.flowx.build.runtime-data.v1` |
| `KAFKA_TOPIC_BUILD_UPDATE` | Build update topic | `ai.flowx.build.update.v1` |
| `KAFKA_TOPIC_BUILD_CREATE` | Build create topic | `ai.flowx.build.create.v1` |
| `KAFKA_TOPIC_BUILD_RESOURCE_EXPORT` | Build export topic | `ai.flowx.build.export.v1` |
| `KAFKA_TOPIC_BUILD_RESOURCE_IMPORT` | Build import topic | `ai.flowx.build.import.v1` |
| `KAFKA_TOPIC_BUILD_STARTTIMEREVENTS_IN_UPDATES` | Timer events updates topic | `ai.flowx.build.start-timer-events.updates.in.v1` |

#### Consumer configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA` | Build runtime data consumer group | `build-runtime-data-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_CREATE` | Build create consumer group | `build-create-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_UPDATE` | Build update consumer group | `build-update-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_EXPORT` | Build export consumer group | `build-resource-export-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_RESOURCE_IMPORT` | Build import consumer group | `build-resource-import-group` |
| `KAFKA_CONSUMER_GROUPID_BUILD_STARTTIMEREVENTS_UPDATES` | Build timer events updates consumer group | `build-start-timer-events-updates-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA` | Build runtime data consumer threads | `2` |
| `KAFKA_CONSUMER_THREADS_BUILD_UPDATE` | Build update consumer threads | `4` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Auth exception retry interval (seconds) | `10` |

#### Process topics

| Environment Variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN` | Process start for event topic | `ai.flowx.core.trigger.start-for-event.process.v1` |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_IN` | Process start by name topic | `ai.flowx.core.trigger.start-by-name.process.v1` |
| `KAFKA_TOPIC_PROCESS_STARTBYNAME_OUT` | Process start by name out topic | `ai.flowx.engine.receive.core.trigger.start-by-name.process.out.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_SET` | Set timer schedule topic | `ai.flowx.core.trigger.set.timer-event-schedule.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULEDTIMEREVENTS_OUT_STOP` | Stop timer schedule topic | `ai.flowx.core.trigger.stop.timer-event-schedule.v1` |

#### Other topics

| Environment Variable | Description | Default Pattern |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_OUT` | Audit topic | `ai.flowx.core.trigger.save.audit.v1` |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Events gateway messages topic | `ai.flowx.eventsgateway.receive.copyresource.v1` |

> [!NOTE]
>
> For the full list of application resource topics (export, import, sync, resource usages, etc.), see the [Application Manager Kafka configuration](./application-manager#kafka-topic-configuration).

***

## Scheduler configuration

The Runtime Manager scheduler times out stalled build import/export sessions:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SCHEDULER_BUILDTIMEOUT` | Build import/export timeout, in seconds | `14400` |
| `FLOWX_SCHEDULER_BUILDIMPEXTIMEOUTCRON` | Build import/export timeout check cron | `0 */10 * * * *` |

A build import or export that stays in progress longer than `FLOWX_SCHEDULER_BUILDTIMEOUT` is moved to `IMPORT_TIMEOUT` or `EXPORT_TIMEOUT`. The default of `14400` seconds is 4 hours. `FLOWX_SCHEDULER_BUILDIMPEXTIMEOUTCRON` controls how often the check runs, every 10 minutes by default.

> [!NOTE]
>
> Raise `FLOWX_SCHEDULER_BUILDTIMEOUT` if large builds are legitimately being marked as timed out before they finish. The equivalent timeouts for **application version** import/export are configured on the Application Manager. See [Application Manager scheduler configuration](./application-manager#scheduler-configuration).

***

## Authentication configuration

### Security type

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

### Service account configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-runtime-manager-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | *sensitive* |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | *sensitive* |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!NOTE]
>
> The Runtime Manager and the Application Manager are built from the same artifact and share the `flowx-runtime-manager-sa` service account.

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

## File storage configuration

| Environment Variable | Description | Example Value |
| - | - | - |
| `APPLICATION_FILE_STORAGE_S3_SERVER_URL` | S3-compatible storage server URL | `http://minio:9000` |
| `APPLICATION_FILE_STORAGE_S3_ACCESS_KEY` | S3 access key | *sensitive* |
| `APPLICATION_FILE_STORAGE_S3_SECRET_KEY` | S3 secret key | *sensitive* |

> [!NOTE]
>
> S3-compatible storage is used for storing application files, exports, and imports. The Runtime Manager supports MinIO, AWS S3, and other S3-compatible storage solutions.

## Temporary storage for build exports and imports

Runtime Manager uses the container's `/tmp` directory as working space for build exports and imports. It writes each exported resource and assembles the export archive in `/tmp` before uploading it to S3-compatible storage, and it unpacks imported builds there.

Size `/tmp` to hold your largest build both unpacked and as a zip archive, for every export or import that runs at the same time. Builds exported with **Include media file content** turned on are larger.

When the container runs with a read-only root filesystem, mount a writable volume at `/tmp`. Prefer a disk-backed `emptyDir`: a memory-backed one (`medium: Memory`) counts against the container's memory limit.

To increase the volume, override the Runtime Manager volumes in your Helm values:

```yaml theme={"dark"}
services:
  runtime-manager:
    extraVolumes:
      - name: tmpdir
        emptyDir:
          sizeLimit: 2Gi
    extraVolumeMounts:
      - name: tmpdir
        mountPath: /tmp
        readOnly: false
```

If your Runtime Manager values aren't nested under `services`, set `extraVolumes` and `extraVolumeMounts` at the top level of those values instead.

> [!NOTE]
>
> `extraVolumes` and `extraVolumeMounts` are lists, so your values replace the whole list. Include any other volumes the Runtime Manager already mounts.

## Ingress and CORS

The Runtime Manager is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| - | - | - |
| public | `/rtm/api/runtime` | `/api/runtime/...` |
| admin | `/rtm/api/build-mgmt` | `/api/build-mgmt/...` |
| admin-instances | `/rtm/api/runtime`, `/rtm/api/runtime-internal` | `/api/runtime/...`, `/api/runtime-internal/...` |

All routes strip the `/rtm` prefix before forwarding to the backend. Paths are set through `services.runtime-manager.ingress.<key>.path` (or `gateway.<key>.paths`) in the chart values; the chart also applies `nginx.ingress.kubernetes.io/proxy-body-size: 50m` on the admin route by default to support larger application-version uploads. The admin-instances ingress uses a regex pattern (`/rtm/api/(runtime|runtime-internal)`) with a rewrite annotation under Ingress mode; under Gateway API mode the chart renders two separate `PathPrefix` rules instead.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Runtime Manager. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

> **Note:** Replace placeholders in environment variables with the appropriate values for your environment before starting the service.

***

## Troubleshooting

### Common issues

> [accordion] Database connection failures
>
> **Symptoms:** Service fails to start with database connection errors.
>
> **Solutions:**
>
> 1. Verify the PostgreSQL database exists and is accessible
> 2. Check that the database user has appropriate permissions
> 3. Ensure network connectivity between the pod and PostgreSQL service
> 4. Verify the JDBC URL format is correct
> 5. For MongoDB, confirm the replica set is healthy and `retryWrites=false` is set in the connection URI

> [accordion] Kafka publishing failures
>
> **Symptoms:** Messages not reaching consumers, runtime data not syncing between Admin and Runtime Manager.
>
> **Solutions:**
>
> 1. Verify that `KAFKA_TOPIC_BUILD_RUNTIMEDATA` resolves to the same value in both Admin and Runtime Manager
> 2. Check that `KAFKA_TOPIC_NAMING_ENVIRONMENT` is consistent across services
> 3. Ensure Kafka broker addresses are correct and reachable
> 4. Review consumer group IDs for conflicts with other deployments
> 5. Check Kafka logs for authorization or connectivity errors

> [accordion] Service account authentication errors
>
> **Symptoms:** 401/403 errors when communicating with other FlowX services.
>
> **Solutions:**
>
> 1. Verify the Keycloak service account (`flowx-runtime-manager-sa`) is properly configured
> 2. Check that client secrets match between configuration and Keycloak
> 3. Ensure the service account has required roles assigned
> 4. Confirm `SECURITY_TYPE` is set to `jwt-public-key`
> 5. Verify the Keycloak base server URL is accessible from the pod

> [accordion] Build exports fail with No space left on device
>
> **Symptoms:** Some build exports or imports fail with `No space left on device` while others succeed, and the failures look random.
>
> **Solutions:**
>
> 1. Check the size of the volume mounted at `/tmp` in the Runtime Manager pod
> 2. Increase its `sizeLimit` as described in [Temporary storage for build exports and imports](#temporary-storage-for-build-exports-and-imports)
> 3. Switch a memory-backed `emptyDir` (`medium: Memory`) to a disk-backed one
> 4. To free the space right away, replace the Runtime Manager pods, for example with `kubectl rollout restart`. An `emptyDir` volume is emptied only when its pod is removed, not when the container restarts.

***

## Related resources

> [card] [Application Manager](./application-manager)
>
> Companion service sharing the same container image and Helm chart

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# Scheduler setup
Source: https://docs.flowx.ai/5.9/setup-guides/scheduler-setup-guide

This guide will walk you through the process of setting up the Scheduler service.

## Infrastructure prerequisites

* **MongoDB**
* **Kafka**
* **OpenID Connect Settings**

***

## Dependencies

* [MongoDB](https://www.mongodb.com/2) database
* Ability to connect to a Kafka instance used by the FlowX Engine
* Scheduler service account - required for using Start Timer event node. For more information, see the [scheduler service account configuration](./access-management/configuring-an-iam-solution#scheduler-service-account).

The service comes with most of the required configuration properties pre-filled. However, certain custom environment variables need to be set up.

> [!WARNING]
>
> This service needs to connect to a Mongo database that has replicas to work correctly.

***

## Scheduler configuration

### Scheduler

```yaml theme={"dark"}
scheduler:
  thread-count: 30  # Configure the number of threads to be used for sending expired messages.
  callbacks-thread-count: 60 # Configure the number of threads for handling Kafka responses, whether the message was successfully sent or not
  cronExpression: "*/10 * * * * *" #every 10 seconds
  retry: # new retry mechanism
    max-attempts: 3
    seconds: 1
    thread-count: 3
    cronExpression: "*/10 * * * * *" #every 10 seconds
  cleanup:
    cronExpression: "*/25 * * * * *" #every 25 seconds
```

* `SCHEDULER_THREAD_COUNT`: Used to configure the number of threads to be used for sending expired.
* `SCHEDULER_CALLBACKS_THREAD_COUNT`: Used to configure the number of threads for handling Kafka responses, whether the message was successfully sent or not.

> [!NOTE]
>
> The "scheduler.cleanup.cronExpression" is valid for both scheduler and timer event scheduler.

#### Retry mechanism

* `SCHEDULER_RETRY_THREAD_COUNT`: Specify the number of threads to use for resending messages that need to be retried.
* `SCHEDULER_RETRY_MAX_ATTEMPTS`: This configuration parameter sets the number of retry attempts. For instance, if it's set to 3, it means that the system will make a maximum of three retry attempts for message resending.
* `SCHEDULER_RETRY_SECONDS`: This configuration parameter defines the time interval, in seconds, for retry attempts. For example, when set to 1, it indicates that the system will retry the operation after a one-second delay.

#### Cleanup

* `SCHEDULER_CLEANUP_CRONEXPRESSION`: It specifies how often, in seconds, events that have already been processed should be cleaned up from the database.

#### Recovery mechanism

```yaml theme={"dark"}
flowx:
  timer-calculator:
    delay-max-repetitions: 1000000
```

> [!TIP]
>
> You have a "next execution" set for 10:25, and the cycle step is 10 minutes. If the instance goes down for 2 hours, the next execution time should be 12:25, not 10:35. To calculate this, you add 10 minutes repeatedly to 10:25 until you reach the current time. So, it would be 10:25 + 10 min + 10 min + 10 min, until you reach the current time of 12:25. This ensures that the next execution time is adjusted correctly after the downtime.

* `FLOWX_TIMER_CALCULATOR_DELAY_MAX_REPETITIONS`: This means that, for example, if our cycle step is set to one second and the system experiences a downtime of two weeks, which is equivalent to 1,209,600 seconds, and we have the "max repetitions" set to 1,000,000, it will attempt to calculate the next schedule. However, when it reaches the maximum repetitions, an exception is thrown, making it impossible to calculate the next schedule. As a result, the entry remains locked and needs to be rescheduled. This scenario represents a critical case where the system experiences extended downtime, and the cycle step is very short (e.g., 1 second), leading to the inability to determine the next scheduled event.

### Timer event scheduler

> [!NOTE]
>
> Configuration for Timer Event scheduler designed to manage timer events. Similar configuration to scheduler.

```yaml theme={"dark"}
timer-event-scheduler:
  thread-count: 30
  callbacks-thread-count: 60
  cronExpression: "*/1 * * * * *" #every 1 seconds
  retry:
    max-attempts: 3
    seconds: 1
    thread-count: 3
    cronExpression: "*/5 * * * * *" #every 5 seconds
```

***

## OpenID connect settings

| Environment variable | Description | Default value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SECURITY_PATHAUTHORIZATIONS_0_PATH` | Security path pattern | `/api/**` |
| `SECURITY_PATHAUTHORIZATIONS_0_ROLESALLOWED` | Roles allowed for path access | `ANY_AUTHENTICATED_USER` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-scheduler-core-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

> [!NOTE]
>
> When deploying with the FlowX Helm chart, `SECURITY_OAUTH2_BASESERVERURL` is supplied through the chart value `flowx.keycloak.baseServerUrl` and the service-account client secrets are injected from the chart-managed Keycloak secret. The remaining values ship as image defaults.

The service account is essential for enabling the [**Start Timer**](../docs/building-blocks/node/timer-events/timer-start-event) event node.

More details about the necessary service account, here:

[Scheduler service account](./access-management/configuring-an-iam-solution#scheduler-service-account)

***

## Configuring data source (MongoDB)

The MongoDB database is used to persist scheduled messages until they are sent back. The following configurations need to be set using environment variables:

* `SPRING_DATA_MONGODB_URI`: The URI for the MongoDB database.

***

## Configuring Kafka

### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT` |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group identifier | `scheduler-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10` |

### Consumer configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_CONSUMER_THREADS` | Number of Kafka consumer threads | `1` |
| `KAFKA_CONSUMER_SCHEDULEDTIMEREVENTS_THREADS` | Number of threads for starting Timer Events | `1` |
| `KAFKA_CONSUMER_SCHEDULEDTIMEREVENTS_GROUPID` | Consumer group for starting timer events | `scheduled-timer-events` |
| `KAFKA_CONSUMER_STOPSCHEDULEDTIMEREVENTS_THREADS` | Number of threads for stopping Timer Events | `1` |
| `KAFKA_CONSUMER_STOPSCHEDULEDTIMEREVENTS_GROUPID` | Consumer group for stopping timer events | `stop-scheduled-timer-events` |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

### Kafka topics

#### Schedule topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_SCHEDULE_IN_SET` | Receives scheduled message setting requests | `ai.flowx.core.trigger.set.schedule.v1` |
| `KAFKA_TOPIC_SCHEDULE_IN_STOP` | Handles requests to terminate scheduled messages | `ai.flowx.core.trigger.stop.schedule.v1` |

#### Timer events topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_SET` | Topic for setting timer events | `ai.flowx.core.trigger.set.timer-event-schedule.v1` |
| `KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_STOP` | Topic for stopping timer events | `ai.flowx.core.trigger.stop.timer-event-schedule.v1` |

> [!NOTE]
>
> Make sure the topics configured for this service don't follow the engine pattern.

***

## Configuring logging

The following environment variables can be set to control log levels:

* `LOGGING_LEVEL_ROOT`: Root Spring Boot microservice logs (Default: `INFO`)
* `LOGGING_LEVEL_APP`: App level logs (Default: `INFO`)

***

## Troubleshooting

### Common issues

> [accordion] Scheduled processes not triggering
>
> **Symptoms:** Scheduled processes do not start at the expected times.
>
> **Solutions:**
>
> 1. Verify the cron expressions in `SCHEDULER_CLEANUP_CRONEXPRESSION` and the scheduler `cronExpression` settings are correct
> 2. Check that Kafka topics (`KAFKA_TOPIC_SCHEDULE_IN_SET`, `KAFKA_TOPIC_SCHEDULE_IN_STOP`) are correctly configured and accessible
> 3. Confirm the scheduler service is healthy by checking `/actuator/health`
> 4. Review scheduler logs at `DEBUG` level for missed or skipped executions

> [accordion] Duplicate schedule executions
>
> **Symptoms:** Scheduled messages are sent multiple times for the same event.
>
> **Solutions:**
>
> 1. Check the replica count — running multiple replicas without proper leader election can cause duplicates
> 2. Verify that the MongoDB replica set is healthy, as the scheduler relies on it for distributed locking
> 3. Review `SCHEDULER_THREAD_COUNT` and `SCHEDULER_CALLBACKS_THREAD_COUNT` to ensure they are not excessively high for your workload

> [accordion] Scheduler fails to start
>
> **Symptoms:** The scheduler service crashes or fails during startup.
>
> **Solutions:**
>
> 1. Verify MongoDB connectivity and ensure the database has replicas enabled (required for the scheduler to work correctly)
> 2. Check that Kafka bootstrap servers are reachable (`KAFKA_BOOTSTRAP_SERVERS`)
> 3. Confirm the service account credentials are valid — verify `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` and `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET`
> 4. Review startup logs for specific connection error messages

> [accordion] Timer events not firing
>
> **Symptoms:** Timer event nodes in processes do not trigger at the configured times.
>
> **Solutions:**
>
> 1. Verify the timer event configuration in the process definition (Start Timer, Intermediate Timer)
> 2. Check that the timer event Kafka topics are correctly set (`KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_SET`, `KAFKA_TOPIC_SCHEDULEDTIMEREVENTS_IN_STOP`)
> 3. Ensure the scheduler service account has the necessary permissions — see the [Scheduler service account](./access-management/configuring-an-iam-solution#scheduler-service-account) configuration
> 4. Review the `FLOWX_TIMER_CALCULATOR_DELAY_MAX_REPETITIONS` setting if the system experienced recent downtime

***

## Related resources

> [card] [Scheduled Processes](../docs/projects/runtime/scheduled-processes)
>
> Configure and manage scheduled process executions

> [card] [Timer Events](../docs/building-blocks/node/timer-events/timer-events)
>
> Timer event node types and configuration options

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes


# FlowX Data Search setup
Source: https://docs.flowx.ai/5.9/setup-guides/search-data-service-setup-guide

Comprehensive guide for installing, configuring, and deploying the FlowX Data Search service

The FlowX Data Search service enables searching capabilities across your FlowX platform. This guide provides detailed instructions for setting up, configuring, and deploying the service in your environment.

***

## Infrastructure prerequisites

The FlowX Data Search service requires the following infrastructure components:

| Component | Purpose |
| - | - |
| **Redis** | Caching search results and configurations |
| **Kafka** | Message-based communication with the engine |
| **Elasticsearch** | Indexing and searching data |

***

## Configuration

### Kafka configuration

Configure Kafka communication using these environment variables and properties:

#### Basic Kafka settings

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT` |
| `KAFKA_CONSUMER_THREADS` | Number of Kafka consumer threads | `1` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size | `52428800` (50 MB) |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Topic naming configuration

The Data Search service uses a structured topic naming convention:

```
{package}{environment}.{component}.{action}.{version}
```

For example: `ai.flowx.core.trigger.search.data.v1`

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic naming | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator | `-` |
| `KAFKA_TOPIC_NAMING_ENGINERECEIVEPATTERN` | Engine receive pattern | `engine.receive.` |

#### Kafka topics

The service uses these specific topics:

| Topic | Default Value | Purpose |
| - | - | - |
| `KAFKA_TOPIC_DATA_SEARCH_IN` | `ai.flowx.core.trigger.search.data.v1` | Incoming search requests |
| `KAFKA_TOPIC_DATA_SEARCH_OUT` | `ai.flowx.engine.receive.core.search.data.results.v1` | Outgoing search results |

### Elasticsearch configuration

Configure Elasticsearch connection using the following environment variables:

| Variable | Description | Default Value | Default Value |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | URL(s) of Elasticsearch nodes (no protocol) | - | `elasticsearch:9200` |
| `SPRING_ELASTICSEARCH_REST_PROTOCOL` | Connection protocol | `https` | `https` or `http` |
| `SPRING_ELASTICSEARCH_REST_DISABLESSL` | Disable SSL verification | `false` | `false` |
| `SPRING_ELASTICSEARCH_REST_USERNAME` | Authentication username | - | `elastic` |
| `SPRING_ELASTICSEARCH_REST_PASSWORD` | Authentication password | - | `your-password` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | Index name for search data | `process_instance` | `process_instance` |

### Security configuration

The Search Data service validates incoming tokens with the JWT public key mechanism. It does not initiate service-to-service calls, so it has no service-account client registration:

| Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, and `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

### Logging configuration

Control the verbosity of logs with these variables:

| Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root Spring Boot log level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |

***

## Elasticsearch index configuration

The Data Search service creates and manages Elasticsearch indices based on the configured index pattern. The default index name is `process_instance`.

### Index pattern

The service derives the index pattern from the `spring.elasticsearch.index-settings.name` property. This pattern is used to query across multiple indices that match the pattern.

### Sample search query

Below is an example of a search query generated by the Data Search service for Elasticsearch:

```json theme={"dark"}
{
  "query": {
    "bool": {
      "adjust_pure_negative": true,
      "boost": 1,
      "must": [
        {
          "nested": {
            "boost": 1,
            "ignore_unmapped": false,
            "path": "keyIdentifiers",
            "query": {
              "bool": {
                "adjust_pure_negative": true,
                "boost": 1,
                "must": [
                  {
                    "match": {
                      "keyIdentifiers.key.keyword": {
                        "query": "astonishingAttribute",
                        "operator": "OR"
                      }
                    }
                  },
                  {
                    "match": {
                      "keyIdentifiers.originalValue.keyword": {
                        "query": "OriginalGangsta",
                        "operator": "OR"
                      }
                    }
                  }
                ]
              }
            },
            "score_mode": "none"
          }
        },
        {
          "terms": {
            "boost": 1,
            "processDefinitionName.keyword": [
              "TEST_PORCESS_NAME_0",
              "TEST_PORCESS_NAME_1"
            ]
          }
        }
      ]
    }
  }
}
```

***

## Integration with Kibana

Kibana provides an interface for visualizing and exploring data indexed by the Data Search service.

### Using Kibana with FlowX Data Search

1. Connect Kibana to the same Elasticsearch instance
2. Create an index pattern matching your configured index name
3. Use the Discover tab to explore indexed data
4. Create visualizations and dashboards based on your data

> [!NOTE]
>
> Kibana is an open-source data visualization and exploration tool designed primarily for Elasticsearch. It serves as the visualization layer for the Elastic Stack, allowing users to interact with their data stored in Elasticsearch to perform various activities such as querying, analyzing, and visualizing data. For more information, visit the [Kibana official documentation](https://www.elastic.co/guide/en/kibana/current/index.html).

***

## Best practices

1. **Security**:
   * Store sensitive credentials in Kubernetes Secrets
   * Use TLS for Elasticsearch and Kafka communication
   * Implement network policies to restrict access

2. **Performance**:
   * Scale the number of replicas based on query load
   * Adjust Kafka consumer threads based on message volume
   * Configure appropriate resource limits and requests

3. **Monitoring**:
   * Set up monitoring for Elasticsearch, Kafka, and Redis
   * Create alerts for service availability and performance
   * Monitor disk space for Elasticsearch data nodes

***

## Troubleshooting

> [accordion] Elasticsearch connection failures
>
> **Symptoms:** Service fails to start or search requests return errors.
>
> **Solutions:**
>
> 1. Verify Elasticsearch is running and accessible at the configured URL
> 2. Check that credentials in `SPRING_ELASTICSEARCH_REST_USERNAME` and `SPRING_ELASTICSEARCH_REST_PASSWORD` are correct
> 3. Ensure SSL settings match your environment — set `SPRING_ELASTICSEARCH_REST_DISABLESSL` to `true` if not using TLS
> 4. Confirm the protocol in `SPRING_ELASTICSEARCH_REST_PROTOCOL` matches your Elasticsearch setup (`https` or `http`)

> [accordion] Database and Redis issues
>
> **Symptoms:** Cache misses, stale search results, or Redis connection errors.
>
> **Solutions:**
>
> 1. Verify Redis is running and accessible
> 2. Check Redis authentication credentials
> 3. Ensure network policies allow traffic between the Data Search pod and Redis
> 4. Monitor Redis memory usage — eviction policies may cause cache misses under high load

> [accordion] Kafka sync failures
>
> **Symptoms:** Search requests are not received or results are not delivered back to the engine.
>
> **Solutions:**
>
> 1. Verify Kafka topics exist — check that `KAFKA_TOPIC_DATA_SEARCH_IN` and `KAFKA_TOPIC_DATA_SEARCH_OUT` topics are created
> 2. Check Kafka permissions for the consumer group
> 3. Ensure bootstrap servers in `KAFKA_BOOTSTRAP_SERVERS` are correctly specified
> 4. If using OAuth, verify the token endpoint is accessible and credentials are valid

> [accordion] Indexing performance
>
> **Symptoms:** Slow search responses, high latency, or timeouts.
>
> **Solutions:**
>
> 1. Increase `KAFKA_CONSUMER_THREADS` to process more messages in parallel
> 2. Verify the Elasticsearch cluster health — yellow or red status impacts performance
> 3. Check index size and shard distribution in Elasticsearch
> 4. Monitor Elasticsearch JVM heap usage and adjust resource limits if needed
> 5. Review the `KAFKA_MESSAGE_MAX_BYTES` setting if large payloads are being processed

***

## Related resources

> [card] [Elasticsearch Indexing](./flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing)
>
> Configure Elasticsearch indexing for process data

> [card] [Redis Configuration](./redis-configuration)
>
> Complete Redis setup including Sentinel and Cluster modes

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# Microservices setup guides
Source: https://docs.flowx.ai/5.9/setup-guides/setup-guides-overview

Complete reference for deploying and configuring FlowX.AI microservices in your environment

This page is the starting point for deploying FlowX.AI in your own environment. It covers deployment prerequisites, container-image and registry configuration, the environment variables shared across services, deployment best practices, and troubleshooting, and it links to the per-service setup guide for every FlowX.AI microservice. Each service ships as a Docker container, so you can deploy on Kubernetes or any other container orchestration platform.

## Deployment strategy

Deploying FlowX.AI microservices involves breaking down the application into modular components that can be independently deployed, scaled, and maintained. All microservices are delivered as Docker containers, making them suitable for deployment on any container orchestration platform, such as Kubernetes or Docker Swarm.

### Deployment prerequisites

Before beginning the deployment process, ensure you have:

* A Kubernetes cluster or Docker environment
* Access to a container registry
* Persistent storage for databases
* Network policies configured for inter-service communication
* Resource quotas and limits defined for each environment

### Container images and registry

Every FlowX.AI service ships as a Docker image, and each service chart resolves its image from three values: the registry, the repository (the image name), and the tag.

Starting with **5.9.4**, the registry and the image name are separate fields:

```yaml theme={"dark"}
image:
  registry: <your-registry>
  repository: ai-gateway
```

On **5.9.0 through 5.9.3**, the two are a single combined path:

```yaml theme={"dark"}
image:
  repository: <your-registry>/ai-gateway
```

The recommended way to point every chart at your own registry is `global.imageRegistry`. It takes precedence over each chart's own `image.registry`, so mirrored or air-gapped deployments set it once instead of overriding image values service by service:

```yaml theme={"dark"}
global:
  imageRegistry: <your-registry>
  imagePullSecrets:
    - my-registry-credentials
```

> [!WARNING]
>
> On **5.9.4 and later**, do not leave the registry inside `image.repository` while `image.registry` or `global.imageRegistry` is also set. The registry is prepended twice and the image fails to resolve. If you previously used the combined path, move the registry portion out and let `image.repository` hold just the image name.

### Recommended installation order

> [!TIP]
>
> Following the correct installation sequence is crucial for a successful deployment. This ordered approach prevents dependency issues and ensures each service has the required dependencies available when it initializes.

**1. Infrastructure Components**

First, deploy the foundational infrastructure:

* **Databases**: PostgreSQL/Oracle for relational data, MongoDB for document storage
* **Message Broker**: Kafka and ZooKeeper
* **Caching**: Redis
* **Identity Management**: Keycloak or other OAuth2 provider

**2. Core Components**

Next, deploy these core services in order:

1. **Advancing Controller**: Manages process advancement and orchestration
2. **Process Engine**: Handles business process execution and state management

**3. Backend Services**

Once the core components are operational, deploy these services (can be deployed in parallel):

* **Admin Service**: Platform administration and configuration management
* **Audit Core**: Compliance auditing and activity tracking
* **Task Management**: Human task assignment and workflow
* **Scheduler Core**: Job scheduling and time-based operations
* **Data Search**: Indexing and searching capabilities
* **Events Gateway**: Event routing and processing
* **Document Plugin**: Document generation and management
* **Notification Plugin**: Communication and alerts management
* **Any additional plugins or extensions**

**4. AI Platform Services**

Deploy the AI Platform services for intelligent automation capabilities:

The AI Platform is a set of Python services:

* **Planner**: Intent understanding and task orchestration
* **Agent Builder**: Configuration and runtime for low-code AI nodes
* **Knowledgebase RAG**: Retrieval-augmented generation over the knowledge base
* **Embedder**: Embedding generation
* **Knowledgebase Indexer v2**: Event-driven retrieval-vector indexing
* **AI Developer**: Automated code generation capabilities
* **AI Analyst**: Process analysis and optimization
* **AI Designer**: UI generation and design automation
* **AI Assistant**: FlowX.AI documentation assistant
* **KB Enrichment**: Design-time document intelligence over knowledge-base documents (new in 5.9.1, replaces `di-platform`)

> [!NOTE]
>
> AI *features* (chat, AI nodes, agents) are optional, but the AI Platform chart itself is **required infrastructure in 5.5+** — `integration-designer` has hard startup dependencies on AI Platform endpoints and will not start without them. See the [AI Platform setup guide](../setup-guides/ai-platform-setup) for how to run FlowX without AI features.

**5. Frontend Components**

Finally, deploy the frontend services:

* **Designer**: Process design environment for business analysts
* **Web Components**: UI components for custom applications
* **Customer-facing UIs and portals**

## Environment variables reference

Environment variables are the primary configuration mechanism for FlowX.AI microservices. They provide a secure and flexible way to customize service behavior without modifying the container images.

The following sections detail the most commonly used environment variables across FlowX.AI microservices. For service-specific variables, refer to the dedicated setup guides for each component.

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Authorization & access management

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the OAuth2/OIDC server | `https://keycloak.example.com/auth` | Yes |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` (default) | No |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | Defaults to the service's own account, for example `flowx-process-engine-sa` | No |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret | `secret` | Yes |

**Upgrading from 5.1.x?** `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_REALM` belong to the removed opaque-token model. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for what replaces them.

### Database configuration

#### PostgreSQL/Oracle

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL | `jdbc:postgresql://postgres:5432/flowx` | Yes |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx_user` | Yes |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `securePassword123` | Yes |
| `SPRING_DATASOURCE_DRIVERCLASSNAME` | JDBC driver class (Oracle only) | `oracle.jdbc.OracleDriver` | Yes\* |
| `SPRING_JPA_PROPERTIES_HIBERNATE_DEFAULTSCHEMA` | Default schema (Oracle only) | `FLOWX` | Yes\* |

\*Required only for Oracle databases

#### MongoDB (NoSQL)

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://mongo1,mongo2,mongo3:27017/flowx?replicaSet=rs0` | Yes |
| `DB_USERNAME` | MongoDB username for services that need it | `flowx_mongo_user` | Yes |
| `DB_PASSWORD` | MongoDB password | `mongoSecurePass456` | Yes |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection | `true` | No |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | URI for runtime MongoDB connection | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-runtime:27017/app-runtime` | No\* |

\*Required if runtime MongoDB connection is enabled

### Kafka configuration

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers (preferred) | `kafka-0:9092,kafka-1:9092,kafka-2:9092` | Yes\* |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Legacy property for Kafka brokers (fallback) | `kafka-0:9092,kafka-1:9092,kafka-2:9092` | Yes\* |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka (preferred) | `SASL_PLAINTEXT` | No |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Legacy property for security protocol (fallback) | `SASL_PLAINTEXT` | No |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group ID | `flowx-process-engine-group` | Yes |
| `KAFKA_CONSUMER_THREADS` | Number of Kafka consumer threads | `5` | No |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval for auth exceptions (seconds) | `10` | No |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka message size (bytes) | `52428800` (50 MB) | No |

> [!NOTE]
>
> The `KAFKA_BOOTSTRAP_SERVERS` and `KAFKA_SECURITY_PROTOCOL` properties are preferred and aligned across all services. The legacy `SPRING_KAFKA_BOOTSTRAPSERVERS` and `SPRING_KAFKA_SECURITY_PROTOCOL` properties remain supported for backwards compatibility. If both are set, the new properties take precedence.
>
> \*At least one of `KAFKA_BOOTSTRAP_SERVERS` or `SPRING_KAFKA_BOOTSTRAPSERVERS` must be set.

#### Kafka authentication profile

FlowX.AI supports enabling Kafka authentication across all Java microservices using the `kafka-auth` Spring configuration profile. This feature simplifies the activation of secure Kafka communication.

To enable Kafka authentication, set the `SPRING_PROFILES_ACTIVE` environment variable:

```bash theme={"dark"}
SPRING_PROFILES_ACTIVE=kafka-auth
```

> [!NOTE]
>
> You can activate multiple profiles by separating them with commas: `SPRING_PROFILES_ACTIVE=dev,kafka-auth`

**Additional environment variables for OAuth-based Kafka authentication:**

| Environment Variable | Description | Example Value | Required |
| - | - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID used to authenticate with the token endpoint | `kafka-client` | Yes\* |
| `KAFKA_OAUTH_CLIENT_SECRET` | Secret associated with the OAuth client ID | `kafka-secret` | Yes\* |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint URI from which access tokens are obtained | `https://keycloak.example.com/auth/token` | Yes\* |

\*Required when `kafka-auth` profile is active

> [!WARNING]
>
> The kafka-auth profile enforces SASL/OAUTHBEARER with plaintext transport. Ensure secure networking (VPN, mTLS) is configured where required.

For more details, see the [Kafka Authentication Configuration](./kafka-authentication-config) guide.

### Redis configuration

FlowX.AI microservices use Redis for caching and real-time data management. Redis can be deployed in three modes: Standalone, Sentinel (high availability), and Cluster (horizontal scaling).

**Quick reference for common Redis variables:**

| Environment Variable | Description | Example Value | Mode |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | Standalone |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | Standalone |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | `yourpassword` | All modes |
| `SPRING_DATA_REDIS_SENTINEL_MASTER` | Sentinel master name | `mymaster` | Sentinel |
| `SPRING_DATA_REDIS_SENTINEL_NODES` | Sentinel nodes list | `host1:26379,host2:26379` | Sentinel |
| `SPRING_DATA_REDIS_CLUSTER_NODES` | Cluster nodes list | `host1:6379,host2:6379` | Cluster |

> [!NOTE]
>
> For complete Redis configuration including all deployment modes, SSL/TLS setup, and troubleshooting, see the [Redis Configuration](./redis-configuration) guide.

### Logging configuration

| Environment Variable | Description | Default Value | Required |
| - | - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` | No |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | No |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | No |
| `LOGGING_LEVEL_KAFKA_NETWORK_CLIENT` | Kafka network client logging level | `ERROR` | No |
| `LOGGING_LEVEL_REDIS` | Redis client logging level | `OFF` | No |

#### Changing log levels at runtime

> [!WARNING]
>
> **Changed in FlowX.AI 5.9.5.** The `loggers` actuator endpoint is no longer in the default exposure list, so it is not reachable by default on 5.9.5 and later. To keep changing log levels at runtime, add `loggers` to `MANAGEMENT_ENDPOINTS_WEB_EXPOSURE_INCLUDE` (for example `health,info,metrics,prometheus,loggers`). Otherwise, set log levels with the `LOGGING_LEVEL_*` environment variables and restart the service.

All FlowX microservices support dynamic log level adjustment without requiring a restart. This capability uses Spring Boot Actuator's loggers endpoint and is particularly useful for troubleshooting production issues.

**Prerequisites:**

Ensure the `loggers` endpoint is exposed in your management endpoints configuration:

**Example usage:**

```bash theme={"dark"}
curl 'http://localhost:8081/manage/actuator/loggers/ai.flowx' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'
```

Replace `ai.flowx` with the specific logger package you want to modify.

**Available log levels:** `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`

> [!WARNING]
>
> Dynamic log level changes are not persisted. They will reset to the configured values when the service restarts. Using `DEBUG` or `TRACE` levels in production may impact performance and generate large log volumes.

## Deployment best practices

### High availability considerations

For production environments, configure these high availability features:

* **Database Clustering**: Implement PostgreSQL/Oracle with replication
* **MongoDB Replica Sets**: Deploy MongoDB as a replica set with at least 3 nodes
* **Kafka Clustering**: Use at least 3 Kafka brokers with replication factor ≥ 3
* **Redis Sentinel/Cluster**: Configure Redis for high availability
* **Service Replicas**: Run multiple instances of each microservice
* **Load Balancing**: Implement proper load balancing for service instances
* **Affinity/Anti-Affinity Rules**: Distribute service instances across nodes

### Security recommendations

Secure your FlowX.AI deployment with these measures:

1. **Network Segmentation**: Isolate microservices using network policies
2. **Secret Management**: Use Kubernetes Secrets or a vault solution
3. **TLS Everywhere**: Enable TLS for all service-to-service communication
4. **OAuth2 Scopes**: Configure fine-grained OAuth2 scopes for services
5. **Resource Isolation**: Use namespaces and pod security policies
6. **Regular Updates**: Keep all components updated with security patches
7. **Audit Logging**: Enable comprehensive audit logging via the Audit Core service

## Troubleshooting

### Common issues and solutions

| Issue | Possible cause | Solution |
| - | - | - |
| Service fails to start | Missing environment variables | Check logs for "Configuration property not found" errors |
| Database connection errors | Incorrect credentials or URL | Verify database connection parameters |
| Services can't communicate | Kafka misconfiguration | Ensure topic names match between producer and consumer services |
| Authentication failures | OAuth2 configuration issues | Verify client IDs, secrets, and server URLs |
| Performance degradation | Insufficient resources | Monitor CPU/memory usage and scale resources appropriately |
| Data inconsistency | Redis cache not synchronized | Check Redis connection and consider cache invalidation |

### Diagnostic procedures

When troubleshooting FlowX.AI microservices:

1. **Check Service Logs**: Examine logs for error messages
2. **Verify Configurations**: Ensure all required environment variables are set correctly
3. **Test Connectivity**: Verify network connectivity between services
4. **Monitor Resources**: Check CPU, memory, and disk usage
5. **Inspect Kafka Topics**: Use Kafka tools to inspect message flow
6. **Review Database State**: Examine database for data integrity issues
7. **Check OAuth2 Tokens**: Verify token validity and permissions

## Service-specific documentation

For detailed configuration of individual services, refer to:

### Core platform components

> [card] [Process Engine Setup](../setup-guides/flowx-engine-setup-guide/engine-setup)

> [card] [Admin Setup](../setup-guides/admin-setup-guide)

> [card] [Advancing Controller Setup](../setup-guides/advancing-controller-setup-guide)

> [card] [Application Manager Setup](../setup-guides/application-manager)

> [card] [Runtime Manager Setup](../setup-guides/runtime-manager)

> [card] [Scheduler Core Setup](../setup-guides/scheduler-setup-guide)

> [card] [Audit Setup](../setup-guides/audit-setup-guide)

> [card] [Authorization Setup](../setup-guides/authorization-setup-guide)

> [card] [Task Management Setup](../setup-guides/task-management-plugin-setup)

> [card] [Notifications Setup](../setup-guides/notifications-plugin-setup)

> [card] [Document Setup](../setup-guides/documents-plugin-setup)

> [card] [Events Gateway Setup](../setup-guides/events-gateway-setup)

### AI Platform services

> [!NOTE]
>
> The AI Platform is a suite of AI services that provide intelligent automation capabilities across the entire application lifecycle.

> [card] [AI Platform Setup](../setup-guides/ai-platform-setup)

### Plugins & extensions

> [card] [OCR Plugin Setup](../setup-guides/plugins-setup-guide/ocr-plugin-setup)

> [card] [Reporting Setup](../setup-guides/plugins-setup-guide/reporting-setup)

### Integration & data services

> [card] [Integration Designer Setup](../setup-guides/integration-designer-setup)

> [card] [Data Search Setup](../setup-guides/search-data-service-setup-guide)

> [card] [Data Sync Setup](../setup-guides/data-sync)

> [card] [NoSQL DB Runner Setup](../setup-guides/nosql-db-runner)

### User interface & designer

> [card] [Designer Setup](../setup-guides/designer-setup-guide)

> [card] [CMS Setup](../setup-guides/cms-setup)

### Infrastructure & extensions

> [card] [SpiceDB Setup](../setup-guides/spicedb)

### Observability & configuration

> [card] [OpenTelemetry Config](../setup-guides/open-telemetry-config)

> [card] [OT Default Properties](../setup-guides/ot-default-properties)


# Speech to Text setup
Source: https://docs.flowx.ai/5.9/setup-guides/speech-to-text-setup

Configure the Speech to Text service for audio transcription and text-to-speech capabilities.

The Speech to Text service is a Python-based microservice that provides audio transcription using OpenAI Whisper (local or API) and text-to-speech via the OpenAI TTS API. It supports both synchronous REST calls and asynchronous Kafka job processing for long-running audio files.

## Dependencies

The Speech to Text service connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — async job processing for transcription requests from Integration Designer, plus subscription to the AI Providers cache invalidation topic
* **S3-compatible storage** (MinIO or AWS S3) — audio file retrieval and result storage
* **PostgreSQL** — job store for transcription jobs from Integration Designer (see [Job store](#job-store-postgresql))
* **organization-manager** — resolves OpenAI credentials and model assignments from the AUDIO capability configured in [AI Providers](/5.9/ai-platform/ai-providers)
* **OpenAI API key** (fallback) — used for local development, MCP usage, or when no tenant context is available on a request
* **ffmpeg** — required for audio decoding (included in Docker image)

> [!NOTE]
>
> The local Whisper transcription engine runs on-device and does not require any OpenAI credentials. Only cloud transcription (`/transcribe/openai`) and TTS (`/tts/openai`) need credentials, which are resolved from the organization's AUDIO capability when tenant headers are present on the request.

***

## Capabilities

### What it can do

* **Local transcription**: On-device transcription using any Whisper model (`base`, `small`, `medium`, `large`, `turbo`) with automatic language detection
* **Cloud transcription**: OpenAI Whisper API with automatic chunking of long audio into 10-minute segments
* **Text-to-speech**: OpenAI TTS API with multiple models (`tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`) and voice options
* **Segment-level timing**: Returns word-level segments with start/end timestamps
* **Language detection**: Automatic source language detection with confidence probabilities
* **Long audio support**: Kafka-based async processing for files over 15 minutes

### Supported audio formats

| Format | Extensions |
| - | - |
| MP3 | `.mp3` |
| WAV | `.wav` |
| FLAC | `.flac` |
| AAC | `.aac`, `.m4a` |
| OGG | `.ogg` |

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/speech-to-text`).

| Endpoint | Method | Purpose |
| - | - | - |
| `/api/v1/speech-to-text/transcribe` | POST | Transcribe audio using local Whisper model |
| `/api/v1/speech-to-text/transcribe/openai` | POST | Transcribe audio using OpenAI Whisper API |
| `/api/v1/speech-to-text/tts/openai` | POST | Text-to-speech using OpenAI TTS API |
| `/api/v1/speech-to-text/info/health` | GET | Health check |

***

## Configuration

### Server configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `URL_PREFIX` | FastAPI root path for reverse proxy routing | `/speech-to-text` |
| `PORT` | API port | `8080` |
| `GUNICORN_WORKERS` | Number of Gunicorn worker processes | `2` |
| `GUNICORN_TIMEOUT` | Worker timeout in seconds | `600` |

> [!TIP]
>
> Increase `GUNICORN_TIMEOUT` for long audio files. The default `600` seconds works for most files; increase it further for very long recordings.

***

### Whisper model configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `WHISPER_MODEL` | Local Whisper model name | `turbo` |
| `OPENAI_API_KEY` | OpenAI API key — fallback for local dev, MCP, or requests without tenant context. In production, credentials resolve from the organization's AUDIO capability. | - |
| `OPENAI_WHISPER_MODEL` | Fallback model for OpenAI cloud transcription when no tenant context is present or the resolver returns no model | `whisper-1` |

> [!NOTE]
>
> The primary source for OpenAI credentials and the transcription model is the **AUDIO capability** configured under **Organization Settings** → **AI Settings** → **Defaults & Fallbacks**. The env vars above are used only when tenant context is missing or AUDIO is not configured for the organization. See [AI providers and model configuration](/5.9/ai-platform/ai-providers).

Available local Whisper models:

| Model | Size | Speed | Accuracy | Use case |
| - | - | - | - | - |
| `base` | 74 MB | Fastest | Low | Quick prototyping, non-critical transcription |
| `small` | 244 MB | Fast | Medium | General use with limited resources |
| `medium` | 769 MB | Medium | Good | Balanced speed and accuracy |
| `large` | 1.55 GB | Slow | High | High-accuracy requirements |
| `turbo` | 809 MB | Fast | High | Recommended default — best speed/accuracy trade-off |

> [!WARNING]
>
> Larger Whisper models require significantly more memory. The `large` model needs at least 4 Gi RAM per worker. Plan memory limits accordingly and keep `GUNICORN_WORKERS` low when using larger models.

***

### Text-to-speech configuration

TTS is configured per-request via the API. Available options:

| Parameter | Options | Default |
| - | - | - |
| Model | `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts` | `tts-1` |
| Voice | `alloy`, `ash`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer` | `alloy` |

> [!NOTE]
>
> The `gpt-4o-mini-tts` model supports additional voices: `ballad`, `verse`, `marin`, `cedar`.

***

### Tenant context

The Speech to Text service resolves OpenAI credentials per organization via the `llm-config` library. To route a request to the correct organization's AUDIO capability, the caller must propagate tenant context.

#### REST requests

Integration Designer and other upstream services must include these headers on every call to `/transcribe/openai` and `/tts/openai`:

| Header | Purpose |
| - | - |
| `Fx-Organization-Id` | Organization UUID — used to resolve the AUDIO capability |
| `Fx-Workspace-Id` | Workspace UUID — used when workspace-scoped overrides exist |

The `TenantContextMiddleware` reads these headers and sets the tenant context for the duration of the request. When neither header is present, the service falls back to the `OPENAI_API_KEY` env var.

#### Kafka jobs

Transcription requests published to `ai.flowx.ai-platform.speech-to-text.job.request.v1` must include `organizationId` and `workspaceId` fields in the payload. The job consumer reads these fields and sets the tenant context before invoking the transcription resolver.

> [!NOTE]
>
> Cache invalidation for AI provider configuration changes is delivered via Kafka. The service subscribes to `ai.flowx.llm.config.changed.v1` automatically on startup — no manual topic creation is required for invalidation, but the topic must exist in the cluster.

***

### Kafka configuration (optional)

The Speech to Text service supports Kafka for async job processing of long-running audio files (15+ minutes) that would timeout via REST. The request, response, and DLQ topics are declared in the standard FlowX Kafka topics values (`kafka-topics.yaml.gotmpl`) and are provisioned automatically with the standard deployment.

> [!NOTE]
>
> If you run a non-standard Kafka setup that does not use the FlowX-managed topic provisioning, create the request and response topics manually before enabling the consumer.

#### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker address | `kafka:9092` |
| `KAFKA_CONSUMER_ENABLED` | Check the Kafka broker connection at startup (`0` to skip the check). It does not stop the service from consuming jobs | `1` |
| `SPEECH_TO_TEXT_KAFKA_CONSUMER_GROUP` | Consumer group ID for transcription jobs | `speech-to-text-jobs` |
| `KAFKA_SECURITY_ENABLED` | Enable SASL/OAUTHBEARER auth (`0` to turn off) | `0` |
| `KAFKA_MAX_POLL_INTERVAL_MS` | Max poll interval (ms) | `600000` |

> [!TIP]
>
> The default `KAFKA_MAX_POLL_INTERVAL_MS` is set to 10 minutes (600000 ms) to prevent consumer rebalancing during long transcriptions. Increase this value if you regularly process audio files longer than 10 minutes.

#### Topic configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_JOB_REQUEST_TOPIC` | Incoming transcription requests (from Integration Designer) | `ai.flowx.ai-platform.speech-to-text.job.request.v1` |
| `KAFKA_JOB_RESPONSE_TOPIC` | Outgoing transcription responses (to Integration Designer) | `ai.flowx.ai-platform.speech-to-text.job.response.v1` |
| `KAFKA_JOB_DLQ_TOPIC` | Dead-letter topic for failed transcription jobs | `ai.flowx.ai-platform.speech-to-text.job.dlq.v1` |
| *(subscribed automatically)* | AI Providers cache invalidation — consumed by the `llm-config` resolver to refresh cached AUDIO capability assignments when an organization admin updates Defaults & Fallbacks | `ai.flowx.llm.config.changed.v1` |

> [!NOTE]
>
> The Speech to Text service uses the FlowX async job-processing library (`flx-job-lib`). On startup, the service verifies Kafka connectivity and starts a background consumer.

***

### Job store (PostgreSQL)

The Speech to Text service runs transcription jobs from Integration Designer through a durable job queue that keeps each job's state in PostgreSQL. The queue is on by default. With the `flowx-ai` Helm chart, the connection variables point at the `speech_to_text` database.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DURABLE_ENABLED` | Run transcription jobs through the durable job queue (`0` to turn off). With `0`, the service consumes the job request topic with its earlier Kafka consumer, without the job store | `1` |
| `POSTGRES_URI` | PostgreSQL host and port, without a scheme | `postgresql:5432` |
| `POSTGRES_DATABASE` | Database name | `speech_to_text` |
| `POSTGRES_USERNAME` | Database user | `flowx` |
| `POSTGRES_PASSWORD` | Required. Database password | - |
| `POSTGRES_DSN` | Full connection string (`postgresql+asyncpg://user:password@host:port/database`). When set, the four variables above are ignored | - |

> [!WARNING]
>
> If `POSTGRES_PASSWORD` is not set (and `POSTGRES_DSN` is not used), the service fails at startup with a `postgres_dsn is required` error.

***

### Storage configuration (MinIO / S3)

The Speech to Text service reads audio files from and writes results to S3-compatible storage. Job payloads larger than 512,000 bytes are offloaded to `KAFKA_OFFLOAD_BUCKET`, then to the documents bucket, and to `workflows-bucket` when neither is set.

Set either the `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_*` variables or the `MINIO_DOCUMENTS_*` variables. When both are set, the `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_*` value is used. Include the scheme in the endpoint URL: an `https://` URL turns on TLS.

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SERVER_URL` | MinIO/S3 endpoint URL. Takes precedence over `MINIO_DOCUMENTS_URL` | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_ACCESS_KEY` | MinIO/S3 access key. Takes precedence over `MINIO_DOCUMENTS_ACCESS_KEY` | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SECRET_KEY` | MinIO/S3 secret key. Takes precedence over `MINIO_DOCUMENTS_SECRET_KEY` | - |
| `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` | MinIO/S3 bucket name. Takes precedence over `MINIO_DOCUMENTS_BUCKET` | - |
| `MINIO_DOCUMENTS_URL` | MinIO/S3 endpoint URL | - |
| `MINIO_DOCUMENTS_ACCESS_KEY` | MinIO access key | - |
| `MINIO_DOCUMENTS_SECRET_KEY` | MinIO secret key | - |
| `MINIO_DOCUMENTS_BUCKET` | MinIO bucket name | - |

***

### Observability (optional)

| Environment Variable | Description | Default Value |
| - | - | - |
| `USE_OBSERVATORY` | Enable FlowX Observatory middleware (`1` to enable) | `0` |

***

### FLEURS evaluation (optional)

The service can optionally download Google FLEURS datasets at startup for language evaluation and benchmarking.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLEURS_LANGS` | Comma-separated FLEURS language codes | `en_us,hu_hu` |
| `FLEURS_SPLIT` | FLEURS dataset split | `test` |
| `FLEURS_CACHE_DIR` | Dataset cache directory | `/flowx/code/data/fleurs` |

> [!NOTE]
>
> FLEURS datasets are used for evaluating transcription accuracy across languages. This is not required for production use — skip this configuration unless you are benchmarking transcription quality.

***

## Kafka job processing

The Speech to Text service processes transcription requests asynchronously via Kafka. Integration Designer sends requests to the job request topic, and the service writes results to S3 and responds through the job response topic.

### Request payload

| Field | Type | Default | Description |
| - | - | - | - |
| `fileStoragePath` | `string` | *(required)* | Path to audio file in MinIO/S3 |
| `provider` | `string` | `local` | `local` for on-device Whisper, `openai` for OpenAI Whisper API |
| `organizationId` | `string` | *(required for `openai` provider)* | Organization UUID — sets tenant context so the resolver can fetch AUDIO capability credentials |
| `workspaceId` | `string` | - | Workspace UUID — used for workspace-scoped overrides |

### Response flow

1. Integration Designer publishes a transcription request to `ai.flowx.ai-platform.speech-to-text.job.request.v1`
2. Speech to Text downloads the audio file from S3, transcribes it, and stores the result in S3
3. Speech to Text publishes a response with the result path to `ai.flowx.ai-platform.speech-to-text.job.response.v1`
4. Integration Designer retrieves the result (text, language, segments with timestamps) from S3

***

## Deployment and sizing

### Docker

* Base image: Python 3.13
* Port: `8080`
* Health check: `/speech-to-text/api/v1/speech-to-text/info/health`
* Requires ffmpeg (included in Docker image)

### Kubernetes configuration

> [tab] Turbo model (recommended)
>
> | Setting | Value |
> | - | - |
> | Replicas | 2 |
> | CPU requests | 2 cores |
> | CPU limits | 4 cores |
> | RAM requests | 2 Gi |
> | RAM limits | 4 Gi |
> | `WHISPER_MODEL` | `turbo` |
> | `GUNICORN_WORKERS` | `2` |

> [tab] Large model (high accuracy)
>
> | Setting | Value |
> | - | - |
> | Replicas | 2 |
> | CPU requests | 4 cores |
> | CPU limits | 8 cores |
> | RAM requests | 4 Gi |
> | RAM limits | 8 Gi |
> | `WHISPER_MODEL` | `large` |
> | `GUNICORN_WORKERS` | `1` |

> [!WARNING]
>
> The Whisper model is loaded into memory at startup. Each Gunicorn worker loads its own copy of the model. With the `large` model (\~1.55 GB), keep `GUNICORN_WORKERS` at `1` to avoid OOM kills. Scale horizontally with more pods instead.

***

## Verify your setup

> [!TIP]
>
> The Speech to Text pod is running: `kubectl get pods -l app=speech-to-text`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://speech-to-text:8080/api/v1/speech-to-text/info/health`

> [!TIP]
>
> Whisper model loaded successfully — check pod logs for model initialization messages at startup

> [!TIP]
>
> Kafka consumer is connected — check pod logs for `Kafka consumer started` message at startup

> [!TIP]
>
> Integration Designer can reach the service — verify `FLOWX_SPEECHTOTEXT_BASEURL` is set in [Integration Designer setup](/5.9/setup-guides/integration-designer-setup)

***

## Troubleshooting

> [accordion] Pod fails to start or crashes
>
> **Symptoms:** Pod stays in CrashLoopBackOff or never becomes ready.
>
> **Solutions:**
>
> * Check that memory limits are sufficient for the configured Whisper model
> * Verify ffmpeg is available (included in Docker image, may need manual install for local dev)
> * Review pod logs for model download or loading errors
> * Ensure the S3/MinIO endpoint is reachable if Kafka consumer is enabled

> [accordion] Transcription jobs not being processed
>
> **Symptoms:** Integration Designer sends transcription requests but no results are returned.
>
> **Solutions:**
>
> * Verify `DURABLE_ENABLED` is `1` and the [job store](#job-store-postgresql) PostgreSQL connection is set (with `DURABLE_ENABLED=0`, verify `KAFKA_ENABLED` is `1`)
> * Check that `KAFKA_JOB_REQUEST_TOPIC` matches the topic Integration Designer publishes to
> * Ensure the Kafka consumer group (`SPEECH_TO_TEXT_KAFKA_CONSUMER_GROUP`) has no conflicting consumers
> * Review pod logs for Kafka connection or authentication errors

> [accordion] Transcription quality is poor
>
> **Symptoms:** Transcription text is inaccurate or contains many errors.
>
> **Solutions:**
>
> * Upgrade to a larger Whisper model (`turbo` or `large` instead of `base`)
> * Check audio quality — low bitrate or noisy recordings reduce accuracy
> * For non-English audio, use the `large` model which has better multilingual support
> * Try the OpenAI Whisper API (`provider: openai`) for comparison

> [accordion] Consumer rebalancing during long transcriptions
>
> **Symptoms:** Kafka consumer drops out mid-transcription, causing job failures.
>
> **Solutions:**
>
> * Increase `KAFKA_MAX_POLL_INTERVAL_MS` beyond the expected transcription time
> * For very long audio files (30+ minutes), set to `1800000` (30 minutes)
> * Consider splitting long audio files before submitting

> [accordion] OOM kills with large Whisper models
>
> **Symptoms:** Pods restart with OOMKilled status.
>
> **Solutions:**
>
> * Reduce `GUNICORN_WORKERS` to `1` — each worker loads its own model copy
> * Increase memory limits (4 Gi minimum for `turbo`, 8 Gi for `large`)
> * Use a smaller model (`small` or `base`) if accuracy requirements allow
> * Scale horizontally with more single-worker pods

> [accordion] OpenAI API errors
>
> **Symptoms:** Cloud transcription or TTS requests fail with API errors.
>
> **Solutions:**
>
> * Confirm the request includes `Fx-Organization-Id` (REST) or `organizationId` (Kafka). Without tenant context, the service falls back to `OPENAI_API_KEY`, which may not be set in production deployments.
> * Verify the organization's AUDIO capability is configured under **Organization Settings** → **AI Settings** → **Defaults & Fallbacks**. Pod logs show `no AUDIO capability configured for org, falling back to env` when missing.
> * If falling back to env, verify `OPENAI_API_KEY` is set and valid.
> * Check API rate limits on your OpenAI account.
> * For large files, the service automatically chunks audio into 10-minute segments — ensure network is stable.
> * Review pod logs for specific API error messages.

> [accordion] AI Providers cache not refreshing
>
> **Symptoms:** Organization admin updates the AUDIO model in Defaults & Fallbacks, but the service continues to use the previous model.
>
> **Solutions:**
>
> * Verify the Kafka topic `ai.flowx.llm.config.changed.v1` exists in the cluster and the service has consumer permissions.
> * Check pod logs at startup for `LLM config resolver initialized`. If this line is missing or followed by `falling back to env vars`, the resolver did not start — the service is permanently in fallback mode and will not pick up AI Providers changes.
> * Restart the pods to force a cache refresh if the Kafka topic is unreachable.

***

## Related resources

> [card] [Integration Designer setup](./integration-designer-setup)
>
> Configure Integration Designer, which orchestrates Speech to Text jobs

> [card] [Speech to Text node](../ai-platform/agent-builder/speech-to-text)
>
> Configure the Speech to Text workflow node in Integration Designer

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [Web Crawler setup](./web-crawler-setup)
>
> Configure the Web Crawler service for web page extraction


# SpiceDB setup
Source: https://docs.flowx.ai/5.9/setup-guides/spicedb

This guide covers the step-by-step installation and configuration of SpiceDB for FlowX deployments, including operator installation, database setup, and service integration.

## Overview

SpiceDB is a database for managing authorization policies. It is used to store and manage the authorization policies for the Authorization Service in FlowX's multi-tenant architecture.

> [!NOTE]
>
> **Scope: design-time permissions only.** SpiceDB backs build-time access checks in the FlowX Designer (who can edit which workspace, project, or resource). Runtime permissions — which end users can interact with which solution at execution time — use a separate, custom implementation that does not call SpiceDB. The two systems coexist and don't interact at runtime. See [Runtime authorization](./access-management/runtime-authorization) for the runtime model.

> [!NOTE]
>
> For more information about SpiceDB, see the [SpiceDB documentation](https://authzed.com/docs/spicedb/getting-started/discovering-spicedb).

## Prerequisites

> [card] Infrastructure
>
> * Kubernetes cluster with admin access
> * PostgreSQL database server
> * Network connectivity between SpiceDB and FlowX services

> [card] FlowX Integration
>
> * FlowX platform components that integrate with SpiceDB
> * CAS client library configuration in all FlowX services
> * Proper secret management for authentication

## FlowX customizations

The FlowX platform includes several customizations to the standard SpiceDB deployment:

* **Namespace-restricted operator**: Uses Role and RoleBinding instead of ClusterRole and ClusterRoleBinding for enhanced security
* **Platform Health Monitoring**: Automatic health check configuration for FlowX platform monitoring (`/healthz` endpoint on port 8443)
* **Migration Job Optimization**: Configured retry limits (3 attempts) and timeouts (30 minutes) for schema migrations
* **Resource Optimization**: Production-ready resource requests and limits based on real-world usage
* **Service Annotations**: FlowX-specific service annotations for platform integration

> [!WARNING]
>
> These customizations ensure SpiceDB operates securely within the FlowX platform architecture and integrates properly with platform monitoring and status systems.

## Installation steps

### Step 1: Install SpiceDB operator

> [!NOTE]
>
> The FlowX platform uses a customized SpiceDB operator that operates within a specific namespace, using Role and RoleBinding instead of ClusterRole and ClusterRoleBinding for enhanced security and isolation.

Install the namespace-restricted SpiceDB operator using Helm:

```bash theme={"dark"}
# Install the operator in the same namespace as FlowX
helm install spicedb-operator your-org/spicedb-operator \
  --namespace your-flowx-namespace \
  --create-namespace \
  --version <OPERATOR_VERSION>
```

> [!NOTE]
>
> The operator must be installed in the same namespace as FlowX because it operates with namespace-scoped permissions and cannot access other namespaces.

**Example values.yaml for the operator:**

```yaml theme={"dark"}
# SpiceDB Operator Configuration
replicaCount: 1

serviceAccount:
  create: true
  name: "spicedb-operator"

# Resource limits
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi
```

> [!WARNING]
>
> This operator is restricted to operate within a single namespace (the namespace where it is installed) and does not require cluster-wide permissions. The operator automatically watches the namespace where it is deployed.

Verify the operator is running:

```bash theme={"dark"}
kubectl get pods -l app.kubernetes.io/name=spicedb-operator -n your-flowx-namespace
```

> [!NOTE]
>
> The operator pod will have a name in the format: `spicedb-operator-<hash>-<hash>` (e.g., `spicedb-operator-dd8f97d95-s78fc`)

### Step 2: Create SpiceDB database

Create a dedicated PostgreSQL database and user for SpiceDB:

```sql theme={"dark"}
-- Connect to PostgreSQL as admin user
CREATE DATABASE spicedb;
CREATE USER spicedb_user WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE spicedb TO spicedb_user;
```

> [!WARNING]
>
> SpiceDB requires a dedicated PostgreSQL database. Do not share with other FlowX services.

### Step 3: Create Kubernetes Secret

Create the `spicedb` secret with the required credentials:

```yaml theme={"dark"}
apiVersion: v1
kind: Secret
metadata:
  name: spicedb
type: Opaque
data:
  datastore_uri: <base64-encoded-postgres-connection-string>
  preshared_key: <base64-encoded-secure-token>
```

The secret should contain:

```bash theme={"dark"}
# Raw values (encode these in base64 for the secret)
datastore_uri='postgres://USERNAME:PASSWORD@postgresql:5432/spicedb?sslmode=disable'
preshared_key='REPLACEME'
```

> [!TIP]
>
> Generate a secure preshared key using: `openssl rand -base64 32`

### Step 4: Deploy SpiceDB cluster

> [!NOTE]
>
> The FlowX platform uses a customized SpiceDB cluster chart that includes additional patches for platform status monitoring, health checks, and optimized resource configurations. The deployment uses a dedicated `spicedb` service account for proper RBAC permissions.

Install the SpiceDB cluster using Helm (includes platform-status patches):

```bash theme={"dark"}
# Install the cluster (using your organization's Helm repository)
helm install spicedb your-org/spicedb-cluster \
  --namespace your-namespace \
  --version <CHART_VERSION> \
  --set version=<SPICEDB_VERSION> \
  --set secretName=spicedb
```

**Custom values.yaml (optional):**

```yaml theme={"dark"}
# FlowX SpiceDB Cluster Configuration
version: <SPICEDB_VERSION>
logLevel: debug
datastoreEngine: postgres
httpEnabled: true
secretName: spicedb
replicas: 2

# Optimized resource requests (matches production)
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "1"
    memory: 1Gi
```

> [!NOTE]
>
> **FlowX Platform Integration**: The FlowX SpiceDB chart automatically configures health monitoring annotations on the Service resource. These annotations are hardcoded in the chart and include:
>
> * `flowx.ai/health: "true"`
> * `flowx.ai/health-path: "/healthz"`
> * `flowx.ai/health-port: "8443"`
>
> No additional configuration is needed for platform health monitoring.

> [!WARNING]
>
> For production deployments, ensure `replicas: 2` or higher for high availability. The FlowX chart includes automatic health monitoring and migration job configurations.

### Step 5: Update FlowX services

> [!NOTE]
>
> The following services need a cas-lib configuration:
>
> * authorization-service
> * application-manager
> * authorization-system
> * cms-core
> * data-sync
> * document-plugin
> * integration-designer
> * notification-plugin
> * process-engine
> * runtime-manager
> * task-management-plugin

Configure FlowX services to connect to SpiceDB. The following configuration values are already set by default in FlowX:

```bash theme={"dark"}
FLOWX_SPICEDB_HOST: spicedb #default value
FLOWX_SPICEDB_PORT: 50051 #default value
```

**required configuration**: Add the SpiceDB token to your FlowX services:

```bash theme={"dark"}
FLOWX_SPICEDB_TOKEN: REPLACEME
```

#### Helm values configuration

Add the token reference to your Helm values using `extraEnvVarsMultipleSecretsCustomKeys`:

```yaml theme={"dark"}
extraEnvVarsMultipleSecretsCustomKeys:
  - name: spicedb
    secrets:
      FLOWX_SPICEDB_TOKEN: preshared_key
```

> [!NOTE]
>
> This configuration tells Helm to:
>
> 1. Look for the existing Kubernetes Secret named `spicedb` (created in Step 3)
> 2. Take the value from the `preshared_key` key in that secret
> 3. Mount it as environment variable `FLOWX_SPICEDB_TOKEN` in FlowX service pods

> [!WARNING]
>
> **Token Synchronization**: The `preshared_key` value in the SpiceDB secret must match the `FLOWX_SPICEDB_TOKEN` in all FlowX microservices.

## Verification

Verify your SpiceDB deployment:

**1. Check SpiceDB Pods**

Ensure SpiceDB pods are running:

```bash theme={"dark"}
kubectl get pods -l app.kubernetes.io/name=spicedb
```

**2. Test Connectivity**

Verify SpiceDB is accessible on port 50051:

```bash theme={"dark"}
kubectl port-forward svc/spicedb 50051:50051
# Test connection from another terminal
grpcurl -plaintext localhost:50051 list
```

**3. Check FlowX Integration**

Review FlowX service logs for successful SpiceDB connection:

```bash theme={"dark"}
kubectl logs -l app=authorization-system | grep -i spicedb
```

## Configuration reference

### Required environment variables

| Variable | Required | Description | Default Value | Notes |
| - | - | - | - | - |
| `SPICEDB_DATASTORE_ENGINE` | ✅ | Database engine type | `postgres` | Only PostgreSQL is supported in FlowX |
| `SPICEDB_DATASTORE_CONN_URI` | ✅ | PostgreSQL connection string | `postgres://postgres:password@postgresql:5432/spicedb?sslmode=disable` | Use Kubernetes Secret - include `sslmode=disable` for internal cluster communication |
| `SPICEDB_GRPC_PRESHARED_KEY` | ✅ | Pre-shared key for gRPC authentication | `your-secure-key-here` | **This becomes `FLOWX_SPICEDB_TOKEN` in FlowX services** |

### Optional configuration

| Variable | Required | Description | Default Value | Notes |
| - | - | - | - | - |
| `SPICEDB_DISPATCH_CLUSTER_ENABLED` | ⚠️ | Enable cluster mode for multiple replicas | `true` | Required for production deployments with multiple replicas |
| `SPICEDB_LOG_LEVEL` | ⚠️ | Logging verbosity level | `debug` | Use `debug` for troubleshooting, `info` for production |

## Customer-specific configuration

> [!WARNING]
>
> **Required Customization**: These values must be updated for each deployment environment.

* **Database Connection**: Update `datastore_uri` with your PostgreSQL credentials and hostname
* **Security Token**: Generate a unique `preshared_key` for your deployment


# Task management setup
Source: https://docs.flowx.ai/5.9/setup-guides/task-management-plugin-setup

Configure and deploy the Task Management plugin as a Docker microservice within the FlowX platform.

The Task Management plugin is available as a Docker image and serves as a dedicated microservice within the FlowX platform ecosystem.

## Dependencies

Before setting up the plugin, ensure you have the following dependencies:

* A [MongoDB](https://www.mongodb.com/) database for task storage
* A connection to the RuntimeDB for operational data
* Access to the database used by the FlowX Engine
* Connection to the Kafka instance used by the FlowX Engine
* A [Redis](https://redis.io/) instance for caching and performance optimization

While many configuration properties come pre-configured, several environment variables must be explicitly set for proper functionality.

## Authorization configuration & access roles

The Task Management plugin validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service, used by the security library | `http://organization-manager:80` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-task-management-plugin-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!NOTE]
>
> **Starting with 5.9.0, the Task Management plugin no longer connects to the identity provider for user lookup.** Task operations resolve users through FlowX runtime authorization instead. The previously required `view-users`, `query-users`, and `query-groups` realm-management roles on the service account, the `OPENID_PROVIDER` / `OPENID_ENTRA_*` settings, and the `openid:` Helm values block are obsolete and can be removed from your deployment.

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

For more detailed information about configuring the service account:

> [card] [Task Management Service Account](../setup-guides/access-management/configuring-an-iam-solution#task-management-service-account)

### FlowX Engine datasource configuration

The service needs access to process instance data from the engine database. Configure these connection parameters:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC URL for the engine database | `jdbc:postgresql://onboardingdb:5432/onboarding` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `postgres` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | `password` |

### MongoDB configuration

Configure access to the primary MongoDB instance:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_URI` | MongoDB connection URI | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/task-management-plugin` |
| `DB_USERNAME` | MongoDB username | `task-management-plugin` |
| `DB_PASSWORD` | MongoDB password | `password` |

> [!NOTE]
>
> Task Manager requires a runtime connection to function correctly. Starting the service without a configured and active runtime MongoDB connection is not supported.

### Runtime MongoDB configuration

> [!NOTE]
>
> Task Manager requires a runtime connection to function correctly. Starting the service without a configured and active runtime MongoDB connection is not supported.

Enable the Runtime MongoDB connection:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | Enable runtime MongoDB connection | `true` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | URI for connecting to MongoDB Runtime. Reuses `DB_USERNAME` / `DB_PASSWORD`; the database name (`app-runtime`) is fixed in the URI path. | `mongodb://${DB_USERNAME}:${DB_PASSWORD}@mongodb-0.mongodb-headless,mongodb-1.mongodb-headless,mongodb-arbiter-0.mongodb-arbiter-headless:27017/app-runtime?retryWrites=false` |

### Redis configuration

Task Management Plugin uses Redis for caching. Configure Redis connection using the standard Redis environment variables.

**Quick reference:**

| Environment Variable | Description | Example Value | Status |
| - | - | - | - |
| `SPRING_DATA_REDIS_HOST` | Redis server hostname | `localhost` | **Recommended** |
| `SPRING_DATA_REDIS_PORT` | Redis server port | `6379` | **Recommended** |
| `SPRING_DATA_REDIS_PASSWORD` | Redis authentication password | - | **Recommended** |
| `REDIS_TTL` | Cache TTL in milliseconds | `5000000` | Optional |

> [!NOTE]
>
> Both `SPRING_DATA_REDIS_*` and `SPRING_REDIS_*` variable prefixes are supported. The `SPRING_DATA_REDIS_*` prefix is the modern Spring Boot standard and is recommended for new deployments.

> [!NOTE]
>
> For advanced Redis deployment modes (Sentinel, Cluster) and SSL/TLS setup, see the [Redis Configuration](/5.1/setup-guides/redis-configuration) guide. Note that Sentinel and Cluster modes are only supported by the Events Gateway service.

## Kafka configuration

Configure the Kafka integration using these environment variables:

### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAPSERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections | `PLAINTEXT` |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group identifier | `task-management-plugin-consumer` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10` |
| `KAFKA_CONSUMER_THREADS` | Number of consumer threads | `3` |
| `KAFKA_CONSUMER_EXCLUDEUSERSTHREADS` | Number of threads for processing user exclusion events | `3` |

### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |

### Kafka topics

#### Process management topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Topic for running hooks | `ai.flowx.core.trigger.start.process.v1` |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_OUT` | Topic for task operations (assign, unassign, etc.) | `ai.flowx.core.trigger.operation.v1` |
| `KAFKA_TOPIC_PROCESS_OPERATIONS_BULKOUT` | Topic for bulk operations on tasks | `ai.flowx.core.trigger.operations.bulk.v1` |

#### Scheduling topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_IN` | Topic for receiving scheduler messages for hooks | `ai.flowx.plugin.tasks.trigger.run.hook.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_SET` | Topic for setting schedules | `ai.flowx.core.trigger.set.schedule.v1` |
| `KAFKA_TOPIC_PROCESS_SCHEDULE_OUT_STOP` | Topic for stopping schedules | `ai.flowx.core.trigger.stop.schedule.v1` |

#### User management topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_EXCLUDEUSERS_SCHEDULE_IN` | Topic for user exclusion events | `ai.flowx.plugin.tasks.trigger.exclude.users.v1` |

#### Task operations topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_TASK_IN` | Topic for incoming task creation messages | `ai.flowx.plugin.tasks.trigger.save.task.v1` |

#### Events and integration topics

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_EVENTSGATEWAY_OUT_MESSAGE` | Topic for Events Gateway messages | `ai.flowx.eventsgateway.receive.taskmanager.commands.message.v1` |
| `KAFKA_TOPIC_RESOURCESUSAGES_REFRESH` | Topic for resource usage refresh events | `ai.flowx.application-version.resources-usages.refresh.v1` |

> [!NOTE]
>
> The Engine listens for messages on topics with specific naming patterns. Ensure you use the correct outgoing topic names when configuring the Task Management plugin to maintain proper communication with the engine.

## CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `spicedb-token` |

## Logging configuration

Control logging verbosity with these environment variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root Spring Boot microservice logs | - |
| `LOGGING_LEVEL_APP` | Application-level logs | `INFO` |
| `LOGGING_LEVEL_MONGO_DRIVER` | MongoDB driver logs | `INFO` |
| `LOGGING_LEVEL_REDIS` | Redis/Lettuce client log level | `OFF` |

## Ingress and CORS

The Task Management plugin is exposed on both the admin and public hosts. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service routes

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/task` | `/` |
| public | `/task` | `/` |

Paths are set through `services.task-management-plugin.ingress.admin.path` / `services.task-management-plugin.ingress.public.path` (or the corresponding `gateway.<key>.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer, runtime renderer, and integration domain that calls Task Management. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

## Filtering feature

| Environment Variable | Description |
| - | - |
| `FLOWX_ALLOW_USERNAME_SEARCH_PARTIAL` | Enables filtering possible assignees by partial names |

## Scheduled jobs

Configure scheduled maintenance jobs:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SCHEDULER_USERSCACHESCLEANUP_CRONEXPRESSION` | Cron expression for user cache cleanup | `0 0 0 * *?` (daily at midnight) |

### Resource usage monitoring

The plugin includes a resource usage monitoring feature that can be configured:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LIB_RESOURCESUSAGES_ENABLED` | Enable resource usage tracking | `true` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_ENABLED` | Enable refresh listener | `true` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_THREADCOUNT` | Number of threads for resource collection | `5` |
| `FLOWX_LIB_RESOURCESUSAGES_REFRESHLISTENER_COLLECTOR_MAXBATCHSIZE` | Maximum batch size for collection | `1000` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_GROUPID_RESOURCESUSAGES_REFRESH` | Consumer group for resource usage refresh events | `taskMgmtResourcesUsagesRefreshGroup` |
| `FLOWX_LIB_RESOURCESUSAGES_KAFKA_CONSUMER_THREADS_RESOURCESUSAGES_REFRESH` | Number of threads for processing resource usage events | `3` |

### Database migration

The Task Management plugin uses Mongock for MongoDB migrations:

| Environment Variable | Description | Default Value |
| - | - | - |
| `MONGOCK_CHANGELOGSSCANPACKAGE` | Package to scan for database change logs | `ai.flowx.task.management.config.mongock` |


# Web Crawler setup
Source: https://docs.flowx.ai/5.9/setup-guides/web-crawler-setup

Configure the Web Crawler service for web page crawling, content extraction, and AI-driven browser automation.

The Web Crawler is a Python-based microservice that crawls web pages using Playwright and extracts content as Markdown. It also provides AI-driven browser automation for multi-step web interactions.

## Dependencies

The Web Crawler connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — async job processing for crawl requests from Integration Designer
* [**Identity provider**](/5.9/setup-guides/access-management/configuring-an-iam-solution) (Keycloak or Azure AD) — authentication and Kafka OAuth
* [**CMS Core**](/5.9/setup-guides/cms-setup) — content management integration
* [**Document Plugin**](/5.9/setup-guides/documents-plugin-setup) — file upload for downloaded documents
* **S3-compatible storage** (MinIO or AWS S3) — storing crawl results and offloaded Kafka payloads
* **AI provider** (OpenAI, Anthropic, Ollama, Azure OpenAI, or GCP) — required only for browser automation features

***

## Capabilities

### What it can do

* **Single-page crawling**: Extract content from individual web pages as Markdown
* **Deep crawling**: Breadth-first crawling with configurable depth, concurrency, and rate limiting
* **PDF processing**: Dedicated scraping strategy for linked PDF documents
* **File downloads**: Automatic detection and upload of downloadable files (.docx, .xlsx, .pdf) to the Document Plugin
* **AI browser automation**: Multi-step browser interactions using Claude or GPT-4o via the browser-use library
* **Session management**: Persistent browser sessions for multi-step automation workflows
* **Per-level URL caps**: Configurable maximum pages per depth level during deep crawls
* **Multiple URL filters**: Configure up to 20 URL filter patterns per crawler from the **URL Filters** modal on the Web Crawler node to restrict deep crawls to matching URLs

### What it cannot do

* Cannot crawl pages that require JavaScript-based authentication (unless using browser automation)
* Cannot process audio or video content
* Cannot bypass CAPTCHAs or bot protection without proxy configuration

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/web-crawler`).

| Endpoint | Method | Purpose |
| - | - | - |
| `/api/v1/web-crawler/parse` | POST | Crawl URLs and extract Markdown content |
| `/api/v1/web-crawler/interact` | POST | Start AI browser automation session |
| `/api/v1/web-crawler/interact/{session_id}` | POST | Continue automation in existing session |
| `/api/v1/web-crawler/interact/{session_id}` | DELETE | Close browser session |
| `/api/v1/web-crawler/info/health` | GET | Health check |

***

## Configuration

### Server configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `URL_PREFIX` | FastAPI root path for reverse proxy routing | `/web-crawler` |
| `VERSION` | Service version identifier | `DEV` |
| `VERBOSE` | Enable verbose/debug logging (`1` to enable) | `0` |
| `GUNICORN_WORKERS` | Number of Gunicorn worker processes | `1` |
| `GUNICORN_TIMEOUT` | Worker timeout in seconds | `600` |

> [!TIP]
>
> Set `GUNICORN_TIMEOUT` to at least `600` (10 minutes). Deep crawls with multiple pages can take significant time depending on target site responsiveness and configured depth.

***

### Authentication configuration

#### Keycloak / OAuth2

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | Keycloak server URL | *(required)* |
| `SECURITY_OAUTH2_REALM` | Default Keycloak realm | `flowx` |
| `SECURITY_OAUTH2_CLIENT_ID` | Platform auth client ID | `flowx-platform-authenticate` |
| `SECURITY_OAUTH2_CLIENT_SECRET` | Platform auth client secret | `flowx-platform-authenticate-secret` |
| `SECURITY_PROVIDER` | Auth provider (`KEYCLOAK` or `AZURE`) | `KEYCLOAK` |

#### Service account

The Web Crawler uses a service account for platform API calls (CMS, Document Plugin).

| Environment Variable | Description | Default Value |
| - | - | - |
| `SERVICE_OAUTH_CLIENT_ID` | Service account client ID | `flowx-scheduler-core-sa` |
| `SERVICE_OAUTH_CLIENT_SECRET` | Service account client secret | - |
| `SERVICE_OAUTH_CLIENT_REALM` | Service account Keycloak realm | - |

***

### Kafka configuration

The Web Crawler uses Kafka for async job processing. Integration Designer sends crawl requests, and the Web Crawler returns results through Kafka topics.

#### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker address | `kafka:9092` |
| `KAFKA_CONSUMER_ENABLED` | Enable Kafka consumer (`0` to turn off) | `1` |
| `KAFKA_PRODUCER_ENABLED` | Enable Kafka producer (`0` to turn off) | `1` |
| `KAFKA_CONSUMER_GROUPID` | Consumer group ID | `ai-services` |

#### Consumer tuning

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_MAX_POLL_INTERVAL_MS` | Max poll interval (ms) | `300000` |
| `KAFKA_SESSION_TIMEOUT_MS` | Session timeout (ms) | `300000` |
| `KAFKA_HEARTBEAT_INTERVAL_MS` | Heartbeat interval (ms) | `10000` |

> [!TIP]
>
> Increase `KAFKA_MAX_POLL_INTERVAL_MS` if deep crawls regularly exceed 5 minutes. The consumer will be removed from the group if processing takes longer than this interval.

#### OAuth authentication

When using `KAFKA_SECURITY_ENABLED=1`, the Web Crawler authenticates to Kafka using SASL/OAUTHBEARER via Keycloak.

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_SECURITY_ENABLED` | Enable SASL/OAUTHBEARER auth (`0` to turn off) | `1` |
| `KAFKA_OAUTH_CLIENT_ID` | Service account for Kafka SASL | `flowx-service-client` |
| `KAFKA_OAUTH_CLIENT_SECRET` | Service account secret | - |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | Keycloak token endpoint for Kafka OAuth | `{SECURITY_OAUTH2_BASE_SERVER_URL}/realms/kafka-authz/protocol/openid-connect/token` |

#### Topic configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_JOB_REQUEST_TOPIC` | Incoming crawl job requests (from Integration Designer) | `ai.flowx.web-crawler.job.request` |
| `KAFKA_JOB_RESPONSE_TOPIC` | Outgoing crawl job responses (to Integration Designer) | `ai.flowx.web-crawler.job.response` |

> [!NOTE]
>
> The Web Crawler uses the FlowX async job-processing library (`flx-job-lib`). On startup, the service verifies Kafka connectivity and starts a background consumer.

#### Kafka payload offloading

When crawl results exceed the size limit, payloads are offloaded to S3-compatible storage.

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OFFLOAD_BACKEND` | Storage backend (`minio` or `azure`) | `minio` |
| `KAFKA_OFFLOAD_SIZE_LIMIT` | Payload size threshold (bytes) before offloading | `512000` |
| `KAFKA_OFFLOAD_ROOT_FOLDER` | Root folder for offloaded payloads | `payload-offload` |
| `KAFKA_OFFLOAD_BUCKET` | Bucket (or Azure container) for offloaded payloads. When unset, the documents bucket (`APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` or `MINIO_DOCUMENTS_BUCKET`) or `AZURE_STORAGE_CONTAINER` is used | - |
| `KAFKA_OFFLOAD_REGION` | Storage region for offloaded payloads. When unset, `AWS_REGION`, then `AWS_DEFAULT_REGION` is used. Leave empty for MinIO | - |

***

### Storage configuration

The Web Crawler stores crawl results in S3-compatible storage. Configure one of the following storage backends.

> [tab] MinIO / S3
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SERVER_URL` | MinIO/S3 endpoint URL, including the scheme (`https://` turns on TLS). Takes precedence over `MINIO_DOCUMENTS_URL` and `MINIO_DOCUMENTS_SECURE` | - |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_ACCESS_KEY` | MinIO/S3 access key. Takes precedence over `MINIO_DOCUMENTS_ACCESS_KEY` | - |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SECRET_KEY` | MinIO/S3 secret key. Takes precedence over `MINIO_DOCUMENTS_SECRET_KEY` | - |
> | `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_BUCKET_NAME` | MinIO/S3 bucket name. Takes precedence over `MINIO_DOCUMENTS_BUCKET` | - |
> | `MINIO_DOCUMENTS_URL` | MinIO/S3 endpoint URL | - |
> | `MINIO_DOCUMENTS_ACCESS_KEY` | MinIO access key | - |
> | `MINIO_DOCUMENTS_SECRET_KEY` | MinIO secret key | - |
> | `MINIO_DOCUMENTS_BUCKET` | MinIO bucket name | - |
> | `MINIO_DOCUMENTS_SECURE` | Use HTTPS for `MINIO_DOCUMENTS_URL` (`1` to enable). Ignored when `APPLICATION_FILE_STORAGE_S3_DOCUMENTS_SERVER_URL` is set | `0` |

> [tab] AWS S3
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY` | AWS S3 access key | - |
> | `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY` | AWS S3 secret key | - |
> | `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL` | AWS S3 endpoint URL | - |
> | `APPLICATION_FILE_STORAGE_S3_PRIVATE_REGION` | AWS S3 region | - |
> | `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME` | AWS S3 bucket name | - |

> [tab] Azure Blob Storage
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `AZURE_STORAGE_CONNECTION_STRING` | Azure blob storage connection string | - |
> | `AZURE_STORAGE_CONTAINER` | Azure blob container name | - |

***

### Platform service URLs

| Environment Variable | Description | Default Value |
| - | - | - |
| `CMS_API_URL` | CMS Core service URL | `http://cms-core:80` |
| `DOCUMENT_PLUGIN_URL` | Document Plugin URL (for file uploads) | `http://document-plugin:80` |
| `APP_MANAGER_API_URL` | App Manager service URL | `http://application-manager:80` |
| `CMS_STATIC_ASSETS_PATH` | Static assets CDN path for CMS downloads | - |

***

### AI model configuration

Required only for the browser automation feature (`/interact` endpoints). The Web Crawler uses LLM models to drive browser interactions.

| Model type | Variable | Purpose | Default |
| - | - | - | - |
| Chat | `MODEL_TYPE` | Primary LLM for browser automation | `OPENAI` |
| Vision | `VISION_MODEL_TYPE` | Visual page understanding | `OPENAI` |
| Embedding | `EMBEDDING_MODEL_TYPE` | Text embeddings | `OPENAI` |

| Environment Variable | Description | Default Value |
| - | - | - |
| `FALLBACK_MODEL_TYPE` | Fallback LLM provider if primary fails | - |
| `STRUCTURED_OUTPUT_METHOD` | Structured output method for LLM | `json_schema` |

> [!NOTE]
>
> All model types support the same providers: `OPENAI`, `AZURE`, `OLLAMA`, `ANTHROPIC`, `GCP`, `CUSTOM_OPENAI`.

#### Provider-specific variables

> [tab] OpenAI
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `OPENAI_API_KEY` | OpenAI API key | - |
> | `OPENAI_MODEL_NAME` | Chat model name | `gpt-4o-2024-08-06` |
> | `OPENAI_VISION_MODEL_NAME` | Vision model name | `gpt-4o-2024-08-06` |
> | `OPENAI_EMBEDDING_MODEL_NAME` | Embedding model name | `text-embedding-3-large` |
> | `OPENAI_CHUNK_SIZE` | Embedding chunk size | `1000` |

> [tab] Anthropic
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `ANTHROPIC_API_KEY` | Anthropic API key | - |
> | `ANTHROPIC_MODEL_NAME` | Chat model name | - |
> | `ANTHROPIC_VISION_MODEL_NAME` | Vision model name | - |

> [tab] Ollama
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `OLLAMA_BASE_URL` | Ollama server URL | - |
> | `OLLAMA_MODEL_NAME` | Chat model name | `llama3.2:latest` |
> | `OLLAMA_VISION_MODEL_NAME` | Vision model name | `llava:7b-v1.6` |
> | `OLLAMA_EMBEDDING_MODEL_NAME` | Embedding model name | `all-minilm:33m` |

> [tab] Other providers
>
> **Azure OpenAI:**
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `AZUREOPENAI_MODEL_NAME` | Chat model name | `gpt-4o-2024-08-06` |
>
> **Google Cloud / Vertex AI:**
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `GCP_PROJECT_ID` | Google Cloud project ID | - |
> | `GCP_LOCATION` | Google Cloud region | - |
> | `GCP_MODEL_NAME` | Chat model name | `gemini-1.5-pro` |
>
> **Custom OpenAI-compatible:**
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `CUSTOM_OPENAI_BASE_URL` | API base URL | `https://api.openai.com` |
> | `CUSTOM_OPENAI_CLIENT_ID` | Client ID | - |
> | `CUSTOM_OPENAI_SECRET_KEY` | Secret key | - |
> | `CUSTOM_OPENAI_CHAT_URL` | Chat endpoint path | `/chat/completions` |
> | `CUSTOM_OPENAI_EMBEDDING_URL` | Embedding endpoint path | `/embeddings` |

***

### PostgreSQL configuration

The Web Crawler uses PostgreSQL for embedding storage, memory, and chat history.

> [tab] Embedding database
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `POSTGRES_EMBEDDING_URI` | Host and port | `postgresql-ai:5432` |
> | `POSTGRES_EMBEDDING_USERNAME` | Username | `dip` |
> | `POSTGRES_EMBEDDING_PASSWORD` | Password | - |
> | `POSTGRES_EMBEDDING_DATABASE` | Database name | `dip` |

> [tab] Memory store
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `POSTGRES_MEMORY_URI` | Host and port | `postgresql-ai:5432` |
> | `POSTGRES_MEMORY_USERNAME` | Username | `memory` |
> | `POSTGRES_MEMORY_PASSWORD` | Password | - |
> | `PG_MEMORY_DB` | Database name | `memory` |

> [tab] Chat history
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `POSTGRES_HISTORY_URI` | Host and port | `postgresql-ai:5432` |
> | `POSTGRES_HISTORY_USERNAME` | Username | `chat_history` |
> | `POSTGRES_HISTORY_PASSWORD` | Password | - |
> | `POSTGRES_HISTORY_DATABASE` | Database name | `chat_history` |

***

### Observability (optional)

#### FlowX Observatory

| Environment Variable | Description | Default Value |
| - | - | - |
| `USE_OBSERVATORY` | Enable Observatory middleware (`1` to enable) | `0` |
| `FLOWX_OBSERVATORY_API_URL` | Observatory API URL | `http://observatory-api:80` |
| `FLOWX_OBSERVATORY_APP_ID` | Application ID for Observatory | - |
| `FLOWX_OBSERVATORY_VERBOSE` | Verbose Observatory logging | `0` |

#### Langfuse

| Environment Variable | Description | Default Value |
| - | - | - |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key | - |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key | - |
| `LANGFUSE_HOST` | Langfuse server URL | - |

#### LLM Guard

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LLMGUARD_URL` | LLMGuard service URL | `http://llmguard:8000` |

***

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Allowed origins (comma-separated) | - |
| `APPLICATION_CORS_ALLOW_HEADERS` | Allowed headers | `Accept,Content-Type,Authorization,...` |
| `APPLICATION_CORS_ALLOW_METHODS` | Allowed methods | `GET,PUT,POST,DELETE,PATCH,OPTIONS` |
| `APPLICATION_CORS_ALLOW_CREDENTIALS` | Allow credentials | `true` |

***

### MCP server configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `MCP_AUTH_KEY` | Authentication key for MCP server endpoints | - |

***

## Kafka job processing

The Web Crawler processes crawl requests asynchronously via Kafka. Integration Designer sends requests to the job request topic, and the Web Crawler writes results to S3 and sends a response to the job response topic.

### Request payload

| Field | Type | Default | Description |
| - | - | - | - |
| `urls` | `string[]` | *(required)* | URLs to crawl |
| `depth` | `int` | `1` | Crawl depth (1 = single page) |
| `maxPages` | `int` | `50` | Max total pages to crawl |
| `maxPagesPerLevel` | `int` | `10` | Max pages per depth level |
| `followLinks` | `bool` | `true` | Follow links on crawled pages |
| `processLinkedPdfs` | `bool` | `true` | Process linked PDF documents |
| `acceptDownloads` | `bool` | `false` | Download files and upload to Document Plugin |
| `pageTimeout` | `int` | `30000` | Page navigation timeout (ms) |
| `proxyUrl` | `string` | `null` | Proxy URL for requests |
| `applicationId` | `string` | `null` | Application ID (required for file uploads) |

### Response flow

1. Integration Designer publishes a crawl request to `ai.flowx.web-crawler.job.request`
2. Web Crawler processes the request and stores the result (Markdown content) in S3
3. Web Crawler publishes a response with the result path to `ai.flowx.web-crawler.job.response`
4. Integration Designer retrieves the result from S3

***

## Deployment and sizing

### Docker

* Base image: Python 3.13-slim-bookworm
* Runs as non-root user (`aiservices`)
* Port: `8080`
* Health check: `/web-crawler/api/v1/web-crawler/info/health`

### Kubernetes configuration

| Setting | Value |
| - | - |
| Replicas | 2 |
| CPU requests | 1 core |
| CPU limits | 2 cores |
| RAM requests | 1 Gi |
| RAM limits | 2 Gi |
| `GUNICORN_WORKERS` | `1` |

> [!WARNING]
>
> The Web Crawler runs headless Chromium browsers for page rendering. Each concurrent crawl consumes significant memory. Monitor memory usage and increase limits if pods are OOM-killed during deep crawls.

***

## Verify your setup

> [!TIP]
>
> The Web Crawler pod is running: `kubectl get pods -l app=web-crawler`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://web-crawler:8080/web-crawler/api/v1/web-crawler/info/health`

> [!TIP]
>
> Kafka consumer is connected — check pod logs for `Kafka consumer started` message at startup

> [!TIP]
>
> Integration Designer can reach the Web Crawler — verify `FLOWX_WEBCRAWLER_BASEURL` is set in [Integration Designer setup](/5.9/setup-guides/integration-designer-setup)

***

## Troubleshooting

> [accordion] Pod fails to start or crashes
>
> **Symptoms:** Pod stays in CrashLoopBackOff or never becomes ready.
>
> **Solutions:**
>
> * Verify Chromium/Playwright dependencies are available (included in Docker image)
> * Check that Kafka broker addresses are reachable
> * Ensure the Keycloak server URL is correct and accessible
> * Review pod logs for specific startup errors

> [accordion] Crawl jobs not being processed
>
> **Symptoms:** Integration Designer sends crawl requests but no results are returned.
>
> **Solutions:**
>
> * Verify `KAFKA_CONSUMER_ENABLED` is set to `1`
> * Check that `KAFKA_JOB_REQUEST_TOPIC` matches the topic Integration Designer publishes to
> * Ensure the Kafka consumer group (`KAFKA_CONSUMER_GROUPID`) has no conflicting consumers
> * Review pod logs for Kafka connection or authentication errors

> [accordion] Crawl results are empty or incomplete
>
> **Symptoms:** Pages return no content or partial Markdown.
>
> **Solutions:**
>
> * Increase `pageTimeout` in the crawl request for slow-loading pages
> * Check if the target site blocks headless browsers (try configuring a `proxyUrl`)
> * Verify network connectivity from the pod to the target URLs
> * Review verbose logs (`VERBOSE=1`) for page-level errors

> [accordion] File downloads not uploading
>
> **Symptoms:** `acceptDownloads` is enabled but files are not appearing in the Document Plugin.
>
> **Solutions:**
>
> * Verify `DOCUMENT_PLUGIN_URL` is set and reachable
> * Ensure `applicationId` is provided in the crawl request payload
> * Check service account credentials (`SERVICE_OAUTH_CLIENT_ID` / `SERVICE_OAUTH_CLIENT_SECRET`)
> * Review pod logs for upload errors or authentication failures

> [accordion] OOM kills during deep crawls
>
> **Symptoms:** Pods restart with OOMKilled status during multi-page crawls.
>
> **Solutions:**
>
> * Increase memory limits (try 4 Gi)
> * Reduce `maxPages` and `maxPagesPerLevel` in crawl requests
> * Reduce `GUNICORN_WORKERS` to limit concurrent browser instances
> * Scale horizontally with more pods instead of larger pods

***

## Related resources

> [card] [Integration Designer setup](./integration-designer-setup)
>
> Configure Integration Designer, which orchestrates Web Crawler jobs

> [card] [Integration Designer](../docs/platform-deep-dive/integrations/integration-designer)
>
> Learn about building integration workflows

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [Document Plugin setup](./documents-plugin-setup)
>
> Configure the Document Plugin for file storage


# Webhook Gateway setup
Source: https://docs.flowx.ai/5.9/setup-guides/webhook-gateway-setup

Set up the Webhook Gateway microservice — the public endpoint that receives incoming webhook calls from external systems and routes them to FlowX processes via Kafka.

## Dependencies

Before setting up the Webhook Gateway, ensure you have the following dependencies in place:

* **PostgreSQL** database for storing webhook registration data
* **Kafka** for publishing process start events
* **Keycloak** (or compatible OAuth2 provider) for authentication and authorization
* **SpiceDB** for fine-grained authorization

## Infrastructure prerequisites

| Component | Description |
| - | - |
| PostgreSQL | Dedicated database named `webhook_gateway` |
| Kafka | Message broker for triggering process starts |
| Keycloak | Identity provider for service authentication |
| SpiceDB | Authorization service for workspace validation |

***

## Configuration

### Authorization configuration

The Webhook Gateway validates incoming tokens with the JWT public key mechanism and authenticates to other FlowX services with a dedicated service account (the `mainIdentity` client registration) in the service-accounts realm:

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism (JWT public key validation) | `jwt-public-key` |
| `SECURITY_OAUTH2_BASESERVERURL` | Base URL of the Keycloak server | |
| `SECURITY_OAUTH2_SAREALM` | Service-accounts realm ID | `00000002-0002-4002-8002-000000000002` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | Service account client ID | `flowx-webhook-gateway-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Service account client secret (Keycloak-issued) | |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTID` | Anonymous service account client ID, used for [anonymous runtime access](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access) | `flowx-anonymous-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Anonymous service account client secret | |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Provider token URI, resolved against the service-accounts realm | `${SECURITY_OAUTH2_BASESERVERURL}/realms/${SECURITY_OAUTH2_SAREALM}/protocol/openid-connect/token` |

> [!WARNING]
>
> **Upgrading from 5.1.x?** Remove the legacy opaque-token env vars: `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENTID`, `SECURITY_OAUTH2_CLIENT_CLIENTSECRET`, and `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_*`. These belong to the removed introspection model and prevent the service from starting on 5.9.x. See the [authentication and IAM migration guide](/5.9/migrating-from-5.1-lts/authentication-iam) for the full list.

> [!NOTE]
>
> The Webhook Gateway exposes `/webhooks/**` as public (unauthenticated) paths for receiving incoming webhooks. The `/api/**` paths require a valid JWT token.

***

### PostgreSQL configuration

The Webhook Gateway uses its own dedicated PostgreSQL database for storing webhook registration data.

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for PostgreSQL | `jdbc:postgresql://postgresql:5432/webhook_gateway` |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` |
| `SPRING_DATASOURCE_PASSWORD` | Database password | - |

> [!WARNING]
>
> Ensure the `webhook_gateway` database is created before deploying the service. The Webhook Gateway will manage its own schema migrations via Liquibase.

***

### Kafka configuration

The Webhook Gateway is a **producer-only** service — it publishes messages to Kafka but does not consume from any topics. It publishes to two topics: one for starting new processes and one for resuming waiting process instances.

#### Core Kafka settings

| Environment Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_BOOTSTRAP_SERVERS` | Address of the Kafka server(s) | `localhost:9092` |
| `SPRING_KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections | `PLAINTEXT` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after authorization exceptions (seconds) | `10` |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Topic naming configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

#### Kafka topics

The Webhook Gateway publishes to the following Kafka topics:

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Topic for triggering process starts from webhook events (Message Start Event) | `ai.flowx.core.trigger.start-for-event.process.v1` |
| `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` | Topic for resuming running process instances from webhook events (Message Catch Intermediate Event) | `ai.flowx.core.message.event.process.v1` |

***

### CAS lib configuration (SpiceDB)

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB gRPC port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - |
| `FLOWX_LIB_CASCLIENT_RUNTIME_IMPLEMENTATION` | Runtime authorization backend used by the CAS client. `CUSTOM` routes checks through authorization-system; `SPICEDB` delegates to SpiceDB. Keep the default unless instructed by FlowX. | `CUSTOM` |

***

### Service communication

The Webhook Gateway communicates with the following FlowX services:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization Manager base URL | `http://organization-manager:80` |
| `FLOWX_LIB_CASCLIENT_SERVICES_AUTHORIZATIONSYSTEM_BASEURL` | Authorization System base URL | `http://authorization-system:80` |

***

### Logging configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Root logging level | `INFO` |
| `LOGGING_LEVEL_APP` | Application-specific log level | `INFO` |

***

## Secrets management

The Webhook Gateway requires several secrets to be configured. These should be stored securely and referenced via Kubernetes secrets or a secrets management solution.

| Secret Name | Description |
| - | - |
| `SPRING_DATASOURCE_PASSWORD` | PostgreSQL database password |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Keycloak service account secret |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token |
| `KAFKA_OAUTH_CLIENT_SECRET` | Kafka OAuth client secret (if using OAuth) |

***

## Deployment

### Helm values example

Below is an example Helm values configuration for deploying the Webhook Gateway:

```yaml theme={"dark"}
fullnameOverride: webhook-gateway

image:
  registry: <your-registry>
  repository: webhook-gateway

replicaCount: 1

env:
  SPRING_PROFILES_ACTIVE: production

  # PostgreSQL
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgresql:5432/webhook_gateway
  SPRING_DATASOURCE_USERNAME: flowx

  # Kafka
  SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092

  # OAuth2
  SECURITY_TYPE: jwt-public-key
  SECURITY_OAUTH2_BASESERVERURL: https://keycloak.example.com/auth

  # SpiceDB
  FLOWX_SPICEDB_HOST: spicedb
  FLOWX_SPICEDB_PORT: 50051

# Secrets configuration
extraEnvVarsMultipleSecretsCustomKeys:
  - name: postgresql-generic
    secrets:
      SPRING_DATASOURCE_PASSWORD: postgresql-password-key
  - name: flowx-auth
    secrets:
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET: keycloakWebhookGatewayClientSecret
  - name: spicedb-generic
    secrets:
      FLOWX_SPICEDB_TOKEN: spicedb-token

rbac:
  create: true

ingress:
  enabled: true
  admin:
    enabled: true
    path: /webhooks

podLabels:
  flowx.ai/network-log: "true"
  flowx.ai/egress-s-kafka: "true"
  flowx.ai/egress-s-postgresql: "true"
  flowx.ai/routing-name: "webhook-gateway"
  flowx.ai/prometheus-scrape: "webhook-gateway"
```

> [!NOTE]
>
> The `image.registry` and `image.repository` split applies to **5.9.4 and later**. To redirect every chart at once, use `global.imageRegistry`. See [Container images and registry](./setup-guides-overview#container-images-and-registry).

> [!NOTE]
>
> Unlike most FlowX services, the Webhook Gateway requires ingress to be enabled because it receives incoming HTTP requests from external systems on the `/webhooks` path.

### Network policies

The Webhook Gateway requires network access to the following services:

| Service | Purpose | Pod Label |
| - | - | - |
| Kafka | Message broker communication | `flowx.ai/egress-s-kafka` |
| PostgreSQL | Webhook registration storage | `flowx.ai/egress-s-postgresql` |
| Keycloak | Authentication | `flowx.ai/egress-s-keycloak` |
| SpiceDB | Authorization | `flowx.ai/egress-s-spicedb` |
| Organization Manager | Organization context resolution | `flowx.ai/egress-s-organization-manager` |
| Authorization System | Access control | `flowx.ai/egress-s-authorization-system` |

***

## Monitoring

The Webhook Gateway exposes Prometheus metrics for monitoring. Turn on scraping by setting the pod label:

```yaml theme={"dark"}
podLabels:
  flowx.ai/prometheus-scrape: "webhook-gateway"
```

### Health endpoints

| Endpoint | Description |
| - | - |
| `/actuator/health` | Health check endpoint |
| `/actuator/metrics` | Prometheus metrics endpoint |
| `/actuator/info` | App info endpoint |

***

## Verify your setup

> [!TIP]
>
> The Webhook Gateway pod is running and healthy: `kubectl get pods -l app=webhook-gateway`

> [!TIP]
>
> The health endpoint returns HTTP 200: `curl http://webhook-gateway:8080/actuator/health`

> [!TIP]
>
> Database migrations completed successfully — check pod logs for `Liquibase: Update has been successful`

> [!TIP]
>
> SpiceDB connection is established — check pod logs for successful CAS client initialization

> [!TIP]
>
> The `/webhooks` ingress path is accessible from external systems

***

## Ingress and CORS

The Webhook Gateway is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. The path is preserved end-to-end (no rewrite), because the webhook endpoint URL is the same on the backend as on the client.

### Service route

| Host group | External path | Backend receives | Notes |
| - | - | - | - |
| admin | `/webhooks` | `/webhooks/...` | Path preserved |

The path is set through `services.webhook-gateway.ingress.admin.path` (or `services.webhook-gateway.gateway.admin.paths`) in the chart values. No rewrite is applied — webhook URLs your upstream systems POST to must match the path exactly.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Most webhook traffic is server-to-server and unaffected; set this only if a Designer or integration UI calls the Webhook Gateway from the browser. | `-` |

Allowed methods, allowed headers, and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](./ingress-configuration).

***

## Troubleshooting

> [accordion] Database connection failures
>
> **Symptoms:** Service fails to start with database connection errors.
>
> **Solutions:**
>
> 1. Verify the `webhook_gateway` database exists in PostgreSQL
> 2. Check that the database user has appropriate permissions
> 3. Ensure network connectivity between the pod and PostgreSQL service
> 4. Verify the JDBC URL format is correct

> [accordion] SpiceDB connection failures
>
> **Symptoms:** Authorization errors or service fails to initialize CAS client.
>
> **Solutions:**
>
> 1. Verify SpiceDB is running and reachable at the configured host and port
> 2. Check that the SpiceDB token is correct
> 3. Ensure network policies allow gRPC traffic to SpiceDB on port `50051`
> 4. Review pod logs for specific CAS client error messages

> [accordion] Kafka publishing failures
>
> **Symptoms:** Webhook events not triggering process starts.
>
> **Solutions:**
>
> 1. Verify Kafka bootstrap servers are reachable
> 2. Check that the `ai.flowx.core.trigger.start-for-event.process.v1` topic exists
> 3. Ensure the service has producer permissions on the topic
> 4. Review pod logs for Kafka producer errors

> [accordion] Webhook endpoint not reachable
>
> **Symptoms:** External systems cannot reach the webhook URL.
>
> **Solutions:**
>
> 1. Verify ingress is enabled and the `/webhooks` path is configured
> 2. Check that network policies allow inbound traffic to the Webhook Gateway
> 3. Ensure DNS resolves correctly for the webhook URL
> 4. Verify the service is listening on port `8080`

> [accordion] Service account authentication errors
>
> **Symptoms:** 401/403 errors when communicating with other FlowX services.
>
> **Solutions:**
>
> 1. Verify the Keycloak service account is properly configured
> 2. Check that client secrets match between configuration and Keycloak
> 3. Ensure the service account has required roles assigned
> 4. Verify `SECURITY_TYPE` is set to `jwt-public-key`

***

## Related resources

> [card] [SpiceDB Configuration](./spicedb)
>
> Fine-grained authorization setup

> [card] [Kafka Authentication](./kafka-authentication-config)
>
> Configure Kafka security and authentication

> [card] [IAM Configuration](./access-management/configuring-an-iam-solution)
>
> Identity and access management setup


# Android SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/android

Migrate the FlowX Android renderer SDK from 5.1.x LTS to 5.9.x.

## Android SDK migration guide

### SDK API changes

#### Config

The `Config` interface used when initializing the SDK now requires a new, mandatory, property, named `organizationId` (the ID of the organization used to identify your installation):

```kotlin diff 5.1.x LTS..5.9.x version theme={"dark"}
Flowx.getInstance().init(
    ...
    config = object : Config {
        override val organizationId: String = "organization id" // [!code ++]
        override val baseUrl = "URL to FlowX backend",
        override val imageBaseUrl = "URL to FlowX CMS Media Library",
        override val enginePath = "some_path",
        override val language = "en",
        override val locale = Locale.getDefault(),
        override val validators: Map<String, (String) -> Boolean>? = mapOf("exact_25_in_length" to { it.length == 25 }),
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE,
    },
    ...
)
```

#### Custom loaders

The `CustomLoaderProvider` interface has been changed from:

```kotlin 5.1.x LTS version theme={"dark"}
interface CustomLoaderProvider {
    fun provideCustomLoader(actionName: String?): CustomLoader?
}
```

to

```kotlin 5.9.x version theme={"dark"}
interface CustomLoaderProvider {
    fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader?
}
```

where the `CustomLoaderProvider.LoaderType` is defined like this:

```kotlin theme={"dark"}
interface LoaderType {
    interface StartProcess : LoaderType
    interface ReloadProcess : LoaderType
    interface Action : LoaderType { val name: String }
    interface Upload : LoaderType { val name: String }
}
```

> [!NOTE]
>
> The available types for the `loaderType` parameter are:
>
> * `LoaderType.StartProcess` - received for overriding the loader displayed when starting a new process
> * `LoaderType.ReloadProcess` - received for overriding the loader displayed when resuming an existing process
> * `LoaderType.Action` - received for overriding the loader displayed while the action having the `name` name is executed
> * `LoaderType.Upload` - received for overriding the loader displayed while the **upload** action having the `name` name is executed
>
> The `name` property received for the `LoaderType.Action` and `LoaderType.Upload` types represents the name of an action, as defined at process definition time, received for being able to override the loader displayed while that action is executed.

> [!NOTE]
>
> Returning an implementation of a `CustomLoader` replaces the built-in platform loader with the provided one for the specified use cases.\
> \\
>
> Returning `null` keeps the built-in platform loader for the specified use cases.

## Related resources

> [card] [Android SDK reference](/5.9/sdks/android-renderer)
>
> Android renderer SDK documentation

> [card] [Migration overview](./overview)
>
> Return to the 5.1 LTS → 5.9 LTS migration hub


# Angular SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/angular

Migrate the FlowX Angular renderer SDK from 5.1.x LTS to 5.9.x.

## Angular SDK migration guide

5.9 bumps the Angular renderer to Angular 21. A new required input is introduced on `<flx-process-renderer>`, one legacy input is removed, and two top-level props are added.

### Framework upgrade: Angular 19 → 21

Upgrade your host app **before** bumping the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide), stepping one major at a time: `19.0` → `20.0`, then `20.0` → `21.0`. Angular does not support skipping a major in a single update.

| Requirement | 5.1 | 5.9.0 - 5.9.3 | 5.9.4 and later |
| - | - | - | - |
| Angular CLI | \~19.2 | \~20 | **\~21** |
| Node | ≥ 20.9.0 | ≥ 24.0.0 | **≥ 24.0.0** |
| npm | ≥ 10.1.0 | ≥ 11.0.0 | **≥ 11.0.0** |
| TypeScript | \~5.5 | ≥ 5.8 | **≥ 5.8** |

> [!NOTE]
>
> Angular 21 arrives in **5.9.4**. If you are migrating onto an earlier patch in the family, target Angular 20 and upgrade to 21 when you move to 5.9.4 or later.

### FlowX SDK changes

#### Organization ID property

We've added a new `organizationId` mandatory input to the `<flx-process-renderer>` component. See SDK documentation for more details.

```html theme={"dark"}
<flx-process-renderer
  ...
  [organizationId]="'10000001-0001-0001-8001-100000000001'"
/>
```

#### `keepState` removed

The `[keepState]` input was removed in 5.9. Process data is always reset when the component is destroyed.

```diff theme={"dark"}
- [keepState]="keepState"
```

## Related resources

> [card] [Angular SDK reference](/5.9/sdks/angular-renderer)
>
> Angular renderer SDK documentation

> [card] [Migration overview](./overview)
>
> Full 5.1.x LTS → 5.9.x upgrade guide


# API & integration breaking changes
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/api-breaking-changes

REST endpoint renames, removals, mandatory headers, and token-format changes that custom API clients and integrations must adapt to between 5.1.x and 5.9.x.

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.

> [!NOTE]
>
> 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-json` | `GET /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.

***

## `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:

```http theme={"dark"}
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](./organization-deployment) for where to obtain it and [Kafka migration](./kafka) 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.

| Aspect | Before (5.1.x) | After (5.9.x) |
| - | - | - |
| JavaScript runtime | GraalJS on GraalVM 24.x | Node.js V8 |
| Python runtime | GraalPy on GraalVM 24.x | CPython 3.11 |
| `input` / `output` / `additionalData` / `instanceMetadata` bindings | Available | Available, unchanged |
| `output.put(...)` / `output.get(...)` / `output.containsKey(...)` | Java HashMap methods | Preserved on both JavaScript and Python |
| Python `import` of arbitrary stdlib | Allowed | Curated 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` / `global` | Worked via GraalVM polyglot context | Not available; scripts run in an isolated V8 context with an explicit globals allowlist |
| Calling Java classes from scripts (`Java.type(...)`, polyglot bindings) | Worked via GraalVM | Not 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 options 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

GraalVM is bundled and supported alongside the native engine, but the opt-out works differently per service:

* **Business rules (process-engine)** — the engine is selected **per rule**, not per service. Rules imported from 5.1 keep running on GraalVM automatically; each rule's script editor has a runtime selector, so you can move rules to native one at a time after testing. See [Script engine per rule](/5.9/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule).
* **Workflow scripts (integration-designer)** — set the service-level opt-out:

  ```yaml theme={"dark"}
  APPLICATION_SCRIPTENGINE_PROVIDER: graalvm
  ```

Use these as transitional settings while you adapt scripts.

> [!WARNING]
>
> **The GraalVM script engine is deprecated.** FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine. Scripts that depend on polyglot calls into Java classes have no equivalent on the native engine, so plan to rewrite them.

See [Native script engine for JavaScript and Python](/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026#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](./authentication-iam) 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. 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.

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

**4. 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, keep the affected business rules on GraalVM with the per-rule runtime selector, or set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `integration-designer` for workflow scripts.

***

## Related resources

> [card] [Authentication & IAM migration](./authentication-iam)
>
> Keycloak two-realm architecture, service-account client renames, opaque-token removal.

> [card] [Organization & deployment configuration](./organization-deployment)
>
> Organization UUID, single-org default mode, removed env-info env vars.

> [card] [Kafka migration](./kafka)
>
> `Fx-Organization-Id` on Kafka producers; new topics and ownership moves.

> [card] [Migration overview](./overview)
>
> Return to the migration hub.


# Authentication & IAM migration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/authentication-iam

Keycloak two-realm architecture, service-account renames, opaque-token removal, and the new env vars required on 5.9.x.

Authentication is the single largest break in the 5.1 → 5.9 upgrade. The model changes in three coordinated areas: service-account client naming, two-realm architecture, and JWT token validation. 5.1.x customers absorb the full transition during the upgrade.

> [!WARNING]
>
> **Hard prerequisite for booting any 5.9.x service.** All FlowX services validate access tokens against the new Keycloak two-realm architecture and reject the legacy opaque-token + per-service realm configuration. Plan this section before the upgrade window. Services will not start with 5.1.x auth env vars left in place.

***

## What changed at the platform level

| Concern | 5.1.x | 5.9.x |
| - | - | - |
| Token validation | Opaque-token introspection against Keycloak | JWT public-key validation (`SECURITY_TYPE: jwt-public-key`) |
| Service-account client naming | Per-service ad-hoc names | Standardized `flowx-{service-name}-sa` pattern |
| Realm architecture | Single Keycloak realm | Two realms — user realm + dedicated service-accounts realm |
| User realm name | `flowx` (or custom) | Your organization ID — the UUID provided by FlowX during organization registration |
| Service-accounts realm UUID | n/a | `00000002-0002-4002-8002-000000000002` |
| `flowx-platform-authorize` client | Used for legacy token introspection | Removed — no longer needed |
| SMTP | Optional | Required in Keycloak for password reset and user invitations |

***

## Service-account client renames

Every FlowX service authenticates to Keycloak through a service-account client. On 5.9.x these clients all follow the `flowx-{service-name}-sa` pattern, in the dedicated service-accounts realm (`00000002-0002-4002-8002-000000000002`).

On a 5.1 → 5.9 upgrade, **the `authorization-system` service migrates the existing `flowx` realm — renaming it to your organization ID — and provisions the new service-accounts realm at first boot**, including the clients below. The list is provided as a verification reference and as the source list for the Manual Keycloak Configuration path.

| Client ID | Used by |
| - | - |
| `flowx-admin-sa` | admin |
| `flowx-process-engine-sa` | process-engine |
| `flowx-integration-designer-sa` | integration-designer |
| `flowx-authorization-system-sa` | authorization-system |
| `flowx-runtime-manager-sa` | runtime-manager |
| `flowx-scheduler-core-sa` | scheduler-core |
| `flowx-task-management-plugin-sa` | task-management-plugin |
| `flowx-organization-manager-sa` | organization-manager |
| `flowx-email-gateway-sa` | email-gateway |
| `flowx-license-sa` | license |
| `flowx-webhook-gateway-sa` | webhook-gateway |
| `flowx-file-gateway-sa` | file-gateway |
| `flowx-ai-gateway-sa` | ai-gateway |
| `flowx-events-gateway-sa` | events-gateway (5.9.4 and later) |
| `flowx-anonymous-sa` | admin, application-manager, authorization-system, document-plugin, email-gateway, events-gateway, file-gateway, integration-designer, license, mock-server, nosql-db-runner, organization-manager, process-engine, scheduler-core, task-management-plugin, webhook-gateway — for inter-service calls on anonymous (unauthenticated) runtime flows |

> [!NOTE]
>
> **`flowx-anonymous-sa` uses a dedicated, low-privilege realm role.** Unlike the other service-account clients above, this one is **not** assigned `SA_FLOWX`. The migration creates a new `SA_FLOWX_ANONYMOUS` realm role in the service-accounts realm and assigns it only that role. This caps the blast radius if the token leaks: an attacker can only invoke endpoints reachable to an anonymous internet visitor on processes or UI flows that explicitly opted into the `Anonymous` runtime role.

> [!NOTE]
>
> **Manual Keycloak Configuration path.** If your environment does not allow FlowX to administer Keycloak directly (for example, restricted enterprise deployments), follow the Manual Keycloak Configuration recipe. On this path the realm rename is your responsibility: the user realm's **Realm name** must equal your organization ID, because services resolve the organization from the token issuer URI (`<auth-server>/realms/<organization-id>`). See [Manual Keycloak configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration) for the complete realm, client, and mapper setup.

> [!NOTE]
>
> **End-user group membership from Keycloak or an external IDP.** This page covers authentication only. If your 5.1.x setup sources end-user group membership from Keycloak groups or a federated IDP — rather than administering it in FlowX after the upgrade — that membership reaches runtime authorization through the `attributes.runtimeGroups` token claim, which needs a mapper that is **not** provisioned automatically. See [Runtime authorization migration → keeping group membership in Keycloak](./runtime-authorization) and the [Runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) setup steps.

***

## Remove legacy authentication env vars

Strip the following from every service's Helm values / env files. These belong to the opaque-token introspection model and will prevent services from starting on 5.9.x.

| Environment Variable | Affected services |
| - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_INTROSPECTIONURI` | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTID` | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_CLIENTSECRET` | 14 services |
| `SECURITY_OAUTH2_REALM` | 14 services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | 14 services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | 14 services |
| `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTID` | 8 services |
| `SECURITY_OAUTH2_SERVICEACCOUNT_ADMIN_CLIENTSECRET` | 8 services |

> [!WARNING]
>
> **`flowx-platform-authorize` Keycloak client.** This client was used for legacy authorization paths and is no longer referenced anywhere in 5.9.x. Delete it from your Keycloak configuration after the upgrade completes.

***

## New required env vars

Add the following across all services. Defaults shown are the canonical 5.9.x defaults. Override only when your environment requires a different value.

### On every service (19 of 19)

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_TYPE` | Token validation mechanism. Replaces opaque-token introspection. | `jwt-public-key` |
| `SECURITY_OAUTH2_SAREALM` | Realm UUID for service-to-service authentication. | `00000002-0002-4002-8002-000000000002` |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | URL of the organization-manager service. | `-` (set per deployment) |

> [!WARNING]
>
> **Set `SECURITY_TYPE` explicitly on every service — do not rely on a chart default.** JWT validation only activates when `SECURITY_TYPE` is set to `jwt-public-key`. The legacy opaque-token mode runs under `SECURITY_TYPE: oauth2`. If your Helm values, or a wrapper chart layered on top of the FlowX chart, leave `SECURITY_TYPE` unset, services keep validating tokens with opaque-token introspection and authentication fails against the 5.9.x two-realm setup. Set `jwt-public-key` on all 19 services as part of the upgrade.

> [!NOTE]
>
> `ORGANIZATION_ID` is **not** required on every service. Only on the 9 services that backfill `organization_id` columns via Liquibase (`application-manager`, `authorization-system`, `cms-core`, `document-plugin`, `integration-designer`, `notification-plugin`, `organization-manager`, `process-engine`, `scheduler-core`). The `license` service consumes the same UUID through a separate env var, `FLOWX_LICENSE_ORGANIZATIONID`. See [Organization & deployment configuration](./organization-deployment#organization_id-where-it-is-actually-required) for the exact behavior across fresh-install vs upgrade scenarios.

### On the 8 services that initiate service-to-service calls

These services have a `MAINIDENTITY` client registration that follows the new service-account naming convention.

| Environment Variable | New Default |
| - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTID` | `flowx-${spring.application.name}-sa` |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | `-` (Keycloak-issued) |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKENURI` | Now references `${security.oauth2.sa-realm}` instead of `${security.oauth2.realm}` |

### On `authorization-system` (master-realm administration)

By default, the authorization-system performs realm migrations on startup and needs master-realm admin credentials. This behavior is controlled by `SECURITY_KEYCLOAKADMINENABLED`, which defaults to `true` (FlowX administers Keycloak).

| Environment Variable | Description | Default Value |
| - | - | - |
| `SECURITY_KEYCLOAKADMINENABLED` | Whether FlowX has Keycloak admin access and manages realms itself. Set to `false` if your environment does not grant FlowX admin access — the `SECURITY_MASTERREALM_*` variables below are then not required. | `true` |
| `SECURITY_MASTERREALM_ADMIN_CLIENTID` | Master-realm admin client. | `admin-cli` |
| `SECURITY_MASTERREALM_NAME` | Master realm name. | `master` |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Master-realm admin username. | `-` |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Master-realm admin password. Store in a Secret. | `-` |

The admin user supplied here must hold the **Admin** role on the master realm with permission to create realms — the migrations provision a new user realm and a service-accounts realm at first boot, and they also create clients, users, and service accounts in those realms.

> [!NOTE]
>
> When `SECURITY_KEYCLOAKADMINENABLED=false`, FlowX does not manage Keycloak realms and the `SECURITY_MASTERREALM_*` credentials are not needed. Use the Manual Keycloak Configuration path to create the realms and service accounts yourself. The same flag governs the `data-sync` master-realm credentials below.

Service-account client secrets for the service-accounts realm must also be supplied as Liquibase parameters on `authorization-system`. One per service, via `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICE_ACCOUNTS_FLOWX_*_SA` (15 secrets in total on 5.9.4 and later, matching the service-account clients listed above).

> [!WARNING]
>
> **Set every SA secret before booting 5.9.x.** If `SECURITY_MASTERREALM_ADMIN_PASSWORD` is missing, the service refuses to start. Easy to diagnose. What happens when individual `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICE_ACCOUNTS_FLOWX_*_SA` values are missing or blank depends on the version:
>
> * **5.9.5 and later:** `authorization-system` refuses to start, and the log names each service-account client without a secret and the setting to supply.
> * **5.9.0 to 5.9.4:** the realm-migration changeset logs an error but the service starts. The SA realm ends up half-populated, and service-to-service authentication breaks at runtime.
>
> Verify all 15 secrets are set before booting 5.9.x.

### On `data-sync` (runtime authorization migration)

The runtime-authorization migration step in `data-sync` connects directly to Keycloak to refresh runtime user/group/role assignments. Configure the same master-realm admin credentials on `data-sync`:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_OPENID_PROVIDER` | Identity provider type. | `keycloak` |
| `FLOWX_OPENID_SERVERURL` | Keycloak base URL — same as `SECURITY_OAUTH2_PUBLIC_SERVER_URL`. | `-` |
| `FLOWX_OPENID_USER` | Master-realm admin username — same as `SECURITY_MASTERREALM_ADMIN_USERNAME`. | `admin` |
| `FLOWX_OPENID_PASSWORD` | Master-realm admin password — same as `SECURITY_MASTERREALM_ADMIN_PASSWORD`. | `-` |
| `FLOWX_OPENID_CLIENTID` | Master-realm admin client — same as `SECURITY_MASTERREALM_ADMIN_CLIENTID`. | `admin-cli` |

> [!NOTE]
>
> These reuse the master-realm admin you set on `authorization-system`. They are required for the runtime-authorization migration to complete; without them, `data-sync` cannot refresh runtime role assignments and post-migration login validation fails.

***

## Configure SMTP in Keycloak

On 5.9.x, Keycloak is the system of record for password resets and user invitations. Configure an SMTP server on each Keycloak realm that will issue invitations. At minimum the user realm. Without SMTP, invitations and password-reset flows fail silently.

See your Keycloak documentation for the realm-level SMTP settings (host, port, encryption, sender address, credentials). FlowX-issued invitation emails are templated by Keycloak.

> [!NOTE]
>
> On self-hosted deployments this SMTP configuration is yours to set directly in Keycloak — it is not provisioned for you. See [Email (SMTP) configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#email-smtp-configuration) for the field-by-field steps.

***

## What happens to existing tokens and sessions

* **Existing user sessions** are invalidated by the realm transition. Users must sign in again after the upgrade.
* **Existing service-account tokens** are invalidated. The new `flowx-{service}-sa` clients re-establish service-to-service authentication on first request.
* **Existing API tokens issued to integration partners** must be re-issued from the new service-accounts realm.

Plan the upgrade window with a clean post-upgrade login + re-issue pass.

***

## Verify the configuration

After services boot on 5.9.x, confirm:

> [!TIP]
>
> The two Keycloak realms exist. User realm (named with your organization ID) + service-accounts realm (`00000002-0002-4002-8002-000000000002`).

> [!TIP]
>
> Every service-account client listed above exists in the service-accounts realm and has client credentials configured.

> [!TIP]
>
> All services started cleanly. Service logs show JWT validation rather than opaque-token introspection. Search for `jwt-public-key` in startup logs.

> [!TIP]
>
> Test user sign-in completes end to end against the user realm.

> [!TIP]
>
> Test password-reset email arrives (validates Keycloak SMTP).

***

## Related resources

> [card] [Configuring an IAM solution](/5.9/setup-guides/access-management/configuring-an-iam-solution)
>
> Full Keycloak realm, client, and mapper setup, including the Manual Keycloak Configuration recipe.

> [card] [Access Management overview](/5.9/setup-guides/access-management/access-management-overview)
>
> How authentication and authorization fit together in 5.9.x.

> [card] [Runtime authorization migration](./runtime-authorization)
>
> Next step. The runtime authorization rewrite that depends on this auth foundation.

> [card] [Organization & deployment configuration](./organization-deployment)
>
> `ORGANIZATION_ID` propagation and the new `license` service.


# Engine partitioning configuration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/engine-partitioning

The process-instance partitioning and archiving configuration consolidated under flowx.data.partitioning.archiving. This page maps the old 5.1.x keys to the 5.9.x structure.

## Who this affects

Only deployments that had **data partitioning enabled** on 5.1.x. If you never set `FLOWX_DATA_PARTITIONING_ENABLED=true`, there is nothing to migrate — the defaults are unchanged and partitioning stays off.

If you did use partitioning, the configuration shape changed between 5.1.x and 5.9.x. You must rename your settings before the upgrade; the old keys no longer bind.

***

## What changed

In 5.1.x, partitioning settings and the archiving scheduler lived in **two separate blocks** — `flowx.data.partitioning.*` for partitioning and a standalone `scheduler.dataPartitioning.*` block for the archiving cron job.

In 5.9.x, everything is consolidated under a single `flowx.data.partitioning` block, with all archiving settings nested in an `archiving` sub-block. The standalone `SCHEDULER_DATA_PARTITIONING_*` variables no longer exist.

> [!WARNING]
>
> **This is a hard cutover.** 5.9.x does not read the old `SCHEDULER_DATA_PARTITIONING_*` keys or the old flat archiving variables. Settings left under the old names are silently ignored, falling back to defaults.

***

## Configuration: before and after

**5.1.x (old):**

```yaml theme={"dark"}
flowx:
  data:
    partitioning:
      enabled: true
      interval: MONTH
      retention-intervals: 3
      detached-partition-compression: OFF
      moved-data-batch-size: 5000
scheduler:
  dataPartitioning:
    enabled: true
    cronExpression: "0 0 1 * * ?"
```

**5.9.x (new):**

```yaml theme={"dark"}
flowx:
  data:
    partitioning:
      enabled: true
      interval: MONTH
      archiving:
        enabled: true                  # was scheduler.dataPartitioning.enabled
        cronExpression: "0 0 1 * * ?"   # was scheduler.dataPartitioning.cronExpression
        retention-intervals: 3          # moved under archiving
        detached-partition-compression: OFF   # moved under archiving (Oracle only)
        moved-data-batch-size: 5000           # moved under archiving (PostgreSQL only)
```

***

## Environment variable mapping

| 5.1.x variable | 5.9.x variable |
| - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ENABLED` (unchanged) |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `FLOWX_DATA_PARTITIONING_INTERVAL` (unchanged) |
| `SCHEDULER_DATA_PARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATA_PARTITIONING_CRON_EXPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |
| `FLOWX_DATA_PARTITIONING_RETENTIONINTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` |
| `FLOWX_DATA_PARTITIONING_DETACHEDPARTITIONCOMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHEDPARTITIONCOMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVEDDATABATCHSIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVEDDATABATCHSIZE` |

***

## Default behavior change

> [!WARNING]
>
> The archiving scheduler now defaults to **off**. In 5.1.x the scheduler defaulted to on (`SCHEDULER_DATA_PARTITIONING_ENABLED=true`); in 5.9.x `archiving.enabled` defaults to `false`. If you relied on the old default to run archiving, you must explicitly set `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true` after the upgrade, or partitions will accumulate without being archived.

***

## Migration steps

**1. Move archiving settings under the archiving block**

Rename your retention, compression, and batch-size settings to the `FLOWX_DATA_PARTITIONING_ARCHIVING_*` form shown in the mapping table.

**2. Replace the standalone scheduler variables**

Drop `SCHEDULER_DATA_PARTITIONING_ENABLED` and `SCHEDULER_DATA_PARTITIONING_CRON_EXPRESSION`. Set `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true` and `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` in their place.

**3. Re-enable archiving explicitly**

Because the scheduler now defaults to off, confirm `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true` is set if you want archiving to run.

**4. Redeploy and verify**

Redeploy process-engine and confirm the archiving cron job runs on schedule. Check the `DATA_PARTITIONING_LOG` table for new archiving entries.

***

## Integration Designer

5.9.x also adds partitioning and archiving for **workflow instances** in Integration Designer, using the same `flowx.data.partitioning` structure. It is opt-in and defaults to off, so it is not a required migration step — enable it only if you want to partition workflow instance data. Note that the Integration Designer block does not include the Oracle compression or PostgreSQL batch-size settings.

***

## Rollback

**The configuration rename on this page** is reversible. It is configuration-only, and the database schema is forward-compatible, so reverting to the old block names restores the previous behavior without a schema change.

> [!WARNING]
>
> This does not apply to the native PostgreSQL partitioning conversion available starting with the 5.9.5 patch (and in 5.12). That one does change the schema and is one way. See [Native PostgreSQL partitioning](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning).

***

## Related resources

> [card] [Partitioning & archiving setup](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving)
>
> Full partitioning and archiving configuration reference.

> [card] [Prerequisites & upgrade path](./prerequisites)
>
> Inventory to gather before the upgrade, including your current partitioning config.


# Ingress routing and CORS
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/ingress-routing

NGINX ingress controller no longer assumed, CORS handling moved to the application layer, and the optional Gateway API HTTPRoute migration path.

5.1.x deployments route external traffic through Kubernetes Ingress resources rendered by the FlowX Helm chart, with NGINX as the assumed ingress controller. CORS is handled at the ingress layer through `nginx.ingress.kubernetes.io/cors-*` annotations on every per-service Ingress. 5.9.x changes both: the chart no longer assumes ingress-nginx as the bundled controller, and CORS handling moves to the application layer via an environment variable on each backend service.

The chart on 5.9.x ships Kubernetes Ingress and Gateway API HTTPRoute templates side-by-side; each service can be toggled independently between the two modes. The Service Route Reference and full configuration are documented in the [ingress configuration guide](/5.9/setup-guides/ingress-configuration).

> [!NOTE]
>
> This migration is operated by FlowX during the 5.1.x → 5.9.x upgrade window for self-hosted deployments. The customer-facing actions are limited to verifying CORS origins and confirming the post-upgrade ingress controller choice with your FlowX representative.

***

## CORS handling moves into the services

On 5.9.x, CORS is handled inside each backend service's code rather than at the ingress layer. Each service's `application.yaml` ships with sensible defaults for allowed methods, headers, and credentials. Only the **allowed origins** list is deployment-specific and must be configured per environment.

The change applies to every backend service that is exposed through an admin or public URL: `admin`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway`. Internal-only services do not serve browser traffic and are unaffected.

### Set `APPLICATION_CORS_ALLOWORIGIN` per deployment

`APPLICATION_CORS_ALLOWORIGIN` accepts a comma-separated list of origins:

```yaml theme={"dark"}
env:
  APPLICATION_CORS_ALLOWORIGIN: "https://designer.yourcompany.com,https://*.yourcompany.com"
```

Wildcard subdomain patterns are supported. The list must include every domain that your Designer, runtime renderers, and custom integrations are served from. The variable must be set on each of the 15 services listed above.

> [!WARNING]
>
> Origins that are not listed in `APPLICATION_CORS_ALLOWORIGIN` will be rejected at the service layer with a CORS error in the browser, even if the request reaches the backend successfully. CORS failures surface only in the browser console. Backend logs show the request as successful.

### Other CORS settings use safe defaults

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`, and the other FlowX-specific headers used by the platform), and credential handling are baked into each service's `application.yaml` with the correct values. The defaults are overridable via environment variables but rarely need to change; consult your FlowX representative if you have a non-standard requirement.

### What is removed

The following NGINX-specific annotations are no longer rendered on the chart's ingress templates and are no longer effective for CORS handling:

* `nginx.ingress.kubernetes.io/enable-cors`
* `nginx.ingress.kubernetes.io/cors-allow-credentials`
* `nginx.ingress.kubernetes.io/cors-allow-headers`
* `nginx.ingress.kubernetes.io/cors-allow-methods`
* `nginx.ingress.kubernetes.io/cors-allow-origin`

Custom overrides that referenced these annotations should be removed during the upgrade. They have no effect on 5.9.x.

***

## NGINX ingress controller is no longer assumed

The chart no longer assumes ingress-nginx as the bundled controller in 5.9.x.

Kubernetes Ingress resources themselves remain fully supported with any compliant controller (Traefik, HAProxy, Istio, F5 Container Ingress Services, cloud-provider controllers, etc.). The change applies to the bundled controller the chart historically assumed. Not to Kubernetes Ingress as a routing mechanism. Deployments that already terminate ingress on a non-NGINX controller are unaffected; only the CORS env var change above applies.

### What this means for your deployment

| Current 5.1.x setup | 5.9.x action |
| - | - |
| ingress-nginx controller deployed alongside FlowX | Plan the controller change with your FlowX representative — another Kubernetes Ingress controller, or opt in to Gateway API HTTPRoutes (see below). |
| Existing non-NGINX ingress controller (Traefik, HAProxy, F5, etc.) | No controller change required. Confirm the chart's `ingressClassName` is set to your controller. |
| External reverse proxy in front of Kubernetes (F5, corporate API gateway) | No controller change required. The chart's Ingress resources continue to apply behind your proxy. |

***

## Optional: Gateway API HTTPRoutes

5.9.x ships Gateway API HTTPRoute templates alongside the existing Ingress templates, as an opt-in alternative for customers who want a controller-agnostic routing model. Kubernetes Ingress remains the default for every service; switching to HTTPRoute mode is coordinated with FlowX during the upgrade window and requires the Gateway API CRDs (`gateway.networking.k8s.io/v1`) plus a compatible controller (Envoy Gateway, Istio, Traefik with Gateway API enabled, etc.) on the cluster.

For details, see the [routing guide](/5.9/setup-guides/ingress-configuration).

> [!NOTE]
>
> HTTPRoute adoption is not required at the 5.1.x → 5.9.x upgrade window. Customers staying on Kubernetes Ingress for the 5.9.x release cycle will continue to be supported on the chart's Ingress templates.

***

## Customizing routes

If your 5.1.x deployment carries custom NGINX annotations (body-size tuning, timeouts, sticky sessions, custom rewrites, cert-manager, WAF), share the full set with your FlowX representative before the upgrade window so they can be carried forward. See [Routing → Customizing routes](/5.9/setup-guides/ingress-configuration#customizing-routes) for the Ingress ↔ HTTPRoute mapping of common annotations.

***

## Pre-upgrade audit checklist

Before the upgrade window, walk through the following with your FlowX representative:

**1. Inventory CORS origins**

List every domain that calls FlowX REST APIs from the browser. Include Designer URLs, custom domains, runtime renderer domains, third-party integration hosts, and any local-development origins that need to remain authorized in production.

**2. Confirm ingress controller**

Confirm which Kubernetes ingress controller your deployment currently uses. If you are on ingress-nginx, decide with FlowX whether to migrate to another controller, adopt Gateway API HTTPRoutes, or stay on ingress-nginx for the 5.9.x cycle.

**3. Share custom annotations**

If your 5.1.x deployment carries custom annotations on FlowX Ingress resources (body size, timeouts, affinity, custom rewrite, cert-manager, WAF), share the full set with FlowX. They will be carried forward via the chart values.

**4. Verify upstream proxy settings**

If you have an external reverse proxy in front of Kubernetes (F5, corporate gateway, cloud LB), confirm that origin-rewriting or header-stripping at that layer does not interfere with the new application-level CORS handling.

**5. Plan post-upgrade verification**

After the upgrade, validate one request from each origin in `APPLICATION_CORS_ALLOWORIGIN` against each affected service. CORS failures surface only in the browser. Backend logs show successful requests.

***

## Related resources

> [card] [Ingress configuration guide](/5.9/setup-guides/ingress-configuration)
>
> Service Route Reference, Gateway API HTTPRoute configuration, and route customization for the 5.9.x baseline.

> [card] [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9)
>
> Component versions, `APPLICATION_CORS_ALLOWORIGIN` environment variable per service, and self-hosted upgrade guidance.

> [card] [Prerequisites](./prerequisites)
>
> Complete the pre-upgrade inventory before working through this page.

> [card] [Migration overview](./overview)
>
> Return to the consolidated 5.1 LTS → 5.9 LTS migration guide.


# iOS SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/ios

Migrate the FlowX iOS renderer SDK from 5.1.x LTS to 5.9.x.

## iOS SDK migration guide

5.9 bumps the `FlowXRenderer` pod from the 9.x line to the 10.x line. The host-app surface that changes is small: a new mandatory `organizationId` on `FXConfig`, one breaking signature on the callback-based `startProcess`, one new case on `CustomLoaderType`, and a few additive APIs around UI Flows and process-start callbacks.

### Prerequisites and version range

| Requirement | 5.1.x | 5.9.x |
| - | - | - |
| `FlowXRenderer` | `~> 9.0` | `~> 10.3` |
| Minimum iOS | iOS 15 | iOS 15 |
| Swift | 5.9 | 5.9 |
| Xcode | 18+ | 26+ |

### Configuration changes

#### New mandatory `FXConfig.organizationId`

5.9 introduces `organizationId` as a mandatory `FXConfig` property. It carries the FlowX-issued organization UUID. The same value used to backfill `organization_id` columns during the backend upgrade (see [License and organization configuration](./organization-deployment)).

```swift v9.x theme={"dark"}
FXConfig.sharedInstance.configure { config in
    config.baseURL = myBaseURL
    config.enginePath = "engine"
    config.imageBaseURL = myImageBaseURL
    // ...
}
```

```swift v10.x theme={"dark"}
FXConfig.sharedInstance.configure { config in
    config.baseURL = myBaseURL
    config.enginePath = "engine"
    config.imageBaseURL = myImageBaseURL
    config.organizationId = myOrganizationUuid
    // ...
}
```

### Breaking API changes

#### `startProcess` (workspaceId callback variant): completion signature

The `completion` closure of the navigation-agnostic `startProcess(workspaceId:projectId:...)` now receives the started process instance UUID alongside the root view controller.

```swift v9.x theme={"dark"}
public func startProcess(workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         completion: ((UIViewController?) -> Void)?,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift v10.x theme={"dark"}
public func startProcess(workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         completion: ((UIViewController?, String) -> Void)?,
                         onProcessEnded: (() -> Void)? = nil)
```

Update the closure to accept the second argument. The UUID is an empty string if the process failed to start.

```swift theme={"dark"}
FlowX.sharedInstance.startProcess(workspaceId: workspaceUuid,
                                  projectId: applicationUuid,
                                  name: processName,
                                  params: [:],
                                  isModal: true,
                                  showLoader: true) { rootViewController, processInstanceUuid in
    // present rootViewController; persist processInstanceUuid if you need to resume later
}
```

The other two `startProcess` variants (`navigationController:` and `tabBarController:`) keep the same shape. They only gain an optional `onProcessStarted` callback, which has a default of `nil` and is non-breaking.

#### `CustomLoaderType`: new `.upload` case

A fourth case is added to the enum returned by `FXDataSource.customLoader(type:)`.

```swift v9.x theme={"dark"}
public enum CustomLoaderType {
    case startProcess
    case reloadProcess
    case action(String?)
}
```

```swift v10.x theme={"dark"}
public enum CustomLoaderType {
    case startProcess
    case reloadProcess
    case action(String?)
    case upload(String?)
}
```

Exhaustive `switch` statements on `CustomLoaderType` stop compiling until `.upload` is handled. Return `nil` to keep the built-in upload loader, or return a custom view to override it.

```swift theme={"dark"}
func customLoader(type: CustomLoaderType) -> AnyView? {
    switch type {
    case .startProcess:        return AnyView(MyStartProcessLoader())
    case .reloadProcess:       return AnyView(MyReloadLoader())
    case .action(let name):    return AnyView(MyActionLoader(actionName: name))
    case .upload(let name):    return AnyView(MyUploadLoader(actionName: name))
    }
}
```

The associated `String?` on `.upload` is the upload action name as configured in the process definition.

### App-side migration steps

**1. Bump the pod**

In your `Podfile`, point `FlowXRenderer` to the version shipped with 5.9 (see *Release Notes → 5.9 Deployment guidelines → Component versions*) and run `pod install`:

```ruby theme={"dark"}
pod 'FlowXRenderer', '~> <version>'  # see Release Notes → 5.9 Deployment guidelines
```

**2. Set organizationId in FXConfig**

In the existing `FXConfig.sharedInstance.configure { ... }` block, set `config.organizationId` to your FlowX-issued organization UUID. Apply this before starting the first FlowX session.

**3. Update startProcess call sites**

For every call to `FlowX.sharedInstance.startProcess(workspaceId:projectId:...)`, update the trailing `completion` closure to accept `(UIViewController?, String)` instead of `(UIViewController?)`.

**4. Handle the new CustomLoaderType.upload case**

In each `FXDataSource.customLoader(type:)` implementation, add a branch for `.upload(let actionName)`. Return `nil` to keep the default loader.

**5. Rebuild and run**

`pod install` then a clean build (`Cmd+Shift+K`, then `Cmd+B`). Resolve any remaining type-mismatch warnings the compiler surfaces around the two changed signatures.

### Verification

> [!TIP]
>
> Start a process from the host app and confirm the `completion` closure receives a non-empty `processInstanceUuid`. Persist it, kill the app, and resume with `FlowX.sharedInstance.continueExistingProcess(uuid:name:...)`. The previously running task should reopen at the correct screen.

> [!TIP]
>
> Trigger a file upload action on a screen that exposes one. With a custom loader registered, confirm `.upload(actionName)` is hit (e.g. by setting a breakpoint or logging the case). Without a custom loader, confirm the built-in upload spinner appears.

## New capabilities

These are additive in 5.9; existing 5.1 integrations keep working without adopting them. See the [iOS SDK reference](/5.9/sdks/ios-renderer) for full signatures and samples.

* **UI Flows**. `FlowX.sharedInstance.startUIFlow(workspaceId:projectId:name:params:isModal:showLoader:completion:)` starts a UI Flow defined in the FlowX Designer. UI Flows run client-side over a data model and do not require a BPMN process instance on the engine.
* **`onProcessStarted` callback**. `startProcess(navigationController:)` and `startProcess(tabBarController:)` accept an optional `onProcessStarted: ((String) -> Void)?` that fires with the new process instance UUID once the engine has accepted the start request.

## Related resources

> [card] [iOS SDK reference](/5.9/sdks/ios-renderer)
>
> iOS renderer SDK documentation

> [card] [Migration overview](./overview)
>
> Full 5.1.x LTS → 5.9.x upgrade guide


# Kafka migration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/kafka

One mandatory new header, new Kafka topics that did not exist in 5.1.x, a topic-ownership move, and the custom-producer audit you must run before upgrading.

5.1.x deployments interact with FlowX over Kafka in two ways: messages produced **by** FlowX services (process start, task events, audit, document operations) and messages produced **into** FlowX by your own integrations. The 5.1 → 5.9 jump introduces one breaking change that affects custom producers, several new topics introduced by new services, and one topic-ownership move that affects Kafka ACLs.

***

## Mandatory `Fx-Organization-Id` header

On 5.9.x, every FlowX Kafka consumer validates the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected immediately and not retried.

This is the single most likely cause of silent breakage post-upgrade for customers who maintain custom Kafka producers (process start, task operations, engine responses, integration callbacks).

### What to set

Set the header value to the Organization UUID provided by FlowX during organization registration. The same value you configure as the `ORGANIZATION_ID` environment variable on every FlowX service. See [Prerequisites](./prerequisites#get-your-organization-uuid).

```java theme={"dark"}
producerRecord.headers().add("Fx-Organization-Id",
    "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx".getBytes(StandardCharsets.UTF_8));
```

### Where this applies

| Surface | Behavior in 5.9.0 |
| - | - |
| Kafka topics consumed by FlowX | Header is **mandatory**. Missing → message rejected, not retried. |
| Kafka responses sent **back** to FlowX | Preserve all received headers (including `Fx-Organization-Id`) when responding from your connector. |
| REST API endpoints | Header is read into security context when present, but **not enforced** in 5.9.0. Enforcement on authenticated REST requests is tracked separately and will land in a later release. |

> [!WARNING]
>
> Pre-existing 5.1.x integrations that simply forward Kafka messages back to FlowX without copying the headers will break. Audit every custom Kafka producer and connector before the upgrade window.

### Affected consumer surfaces

Validation runs on **every** FlowX Kafka listener. Concretely, custom producers that target the following topic families must add the header:

* Process start (`*.core.trigger.start.process.*`, `*.core.trigger.start-for-event.process.*`)
* Process operations (`*.core.trigger.operation.*`, `*.core.trigger.operations.bulk.*`): task assign/unassign, hold/unhold, terminate, including bulk
* Connector responses (`*.engine.receive.*`)
* Webhook ingestion, document plugin triggers, integration sync topics

***

## New Kafka topics that did not exist in 5.1.x

The 5.1 → 5.9 jump adds new microservices (`organization-manager`, `webhook-gateway`, `license`) and new features (Knowledge Base, Multi-file Upload, UI Flow session variables, Email Trigger). Each brings its own topics. For the complete list with producer/consumer mapping, see the deployment guidelines linked at the bottom of this page.

The high-level groups your platform/SRE team should be aware of:

| Theme | Notable topics |
| - | - |
| `organization-manager` + Document plugin enhancements | `ai.flowx.organization.events.v1`, `ai.flowx.application-version.resources-usages.*`, `ai.flowx.plugin.document.trigger.persist.document.*`, `ai.flowx.build.runtime-data.v1` |
| `webhook-gateway` + UI Flow session variables | `ai.flowx.core.trigger.start-for-event.process.v1`, `ai.flowx.core.trigger.ui-flow.update.v1`, `ai.flowx.plugin.document.trigger.persist.document.session.v1` |
| AI Providers UI (LLM config) | `ai.flowx.llm.config.changed.v1` |
| `license` service + KB internal Kafka path + bulk document persistence | `ai.flowx.license.events.v1`, `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` / `-response.v1`, `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` |

> [!NOTE]
>
> If you manage Kafka topic creation manually (rather than letting FlowX auto-create), pre-create the topics listed in each release's deployment guidelines before deploying the corresponding service versions.

***

## New producer on `WorkspaceCreatedEvent`: `organization-manager`

`organization-manager` now publishes `WorkspaceCreatedEvent` as part of the organization-provisioning flow. `authorization-system` continues to publish the event on regular workspace creation, so on 5.9.x the topic has **two producers**, not one.

If you manage Kafka ACLs at the topic level, grant producer access to **both** services:

* `authorization-system`. Publishes on user-driven workspace create (unchanged from 5.1.x).
* `organization-manager`. Publishes during org provisioning (new in 5.9.x).

Consumers of the topic do not change. If you rely on FlowX's default Kafka ACL provisioning (no manual ACL management), no action is required.

***

## Knowledge Base indexer ↔ embedder moves to Kafka

On 5.9.x, the Knowledge Base indexer → embedder path uses a Kafka request/response pair instead of synchronous gRPC:

* `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` (indexer producer, embedder consumer)
* `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` (embedder producer, indexer consumer)

This is internal to FlowX. Your integrations are unaffected. The implication for operators is that the embedder no longer needs to receive gRPC calls from the indexer; both services connect to Kafka for KB indexing traffic.

***

## Custom-producer audit checklist

Before the upgrade window, walk through every Kafka integration that produces into FlowX:

**1. Inventory**

List every system that publishes to a FlowX Kafka topic. Common sources: backends that start processes by name, task-management automations, connector implementations that respond to engine requests, scheduled jobs that emit events.

**2. Add `Fx-Organization-Id` to producer code**

For each producer, add the header before sending. The value is your Organization UUID (same as the `ORGANIZATION_ID` env var).

**3. Preserve headers on Kafka responses**

Connectors that respond to FlowX engine requests must copy **all** received Kafka headers (including `Fx-Organization-Id`, `Fx-Workspace-Id`, `fxContext`, `Fx-AppId`) into the response. The simplest pattern: `originalHeaders.forEach(producerRecord.headers()::add)`.

**4. Verify in staging**

Run end-to-end with a 5.9.x staging environment before production. The failure mode is non-retryable rejection: messages are dropped, not queued for retry, so the breakage stays silent unless you read the consumer logs.

**5. Update Kafka topic ACLs**

If you manage ACLs manually, switch the `WorkspaceCreatedEvent` producer ACL from `authorization-system` to `organization-manager`. Pre-create any new topics from the table above that aren't already provisioned.

***

## Related resources

> [card] [Creating a Kafka producer](/5.9/docs/platform-deep-dive/integrations/creating-a-kafka-producer)
>
> Full reference for required Kafka headers on the 5.9.x baseline, including the `Fx-Organization-Id`, `Fx-Workspace-Id`, and `jwt` headers.

> [card] [Finding identifiers and parameters](/5.9/docs/platform-deep-dive/integrations/finding-identifiers-and-parameters)
>
> Where to find the Organization UUID, workspace ID, project ID, and other identifiers required in Kafka and REST integrations.

> [card] [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9)
>
> Component versions, Kafka topic ownership, and env vars for the 5.9.x baseline.

> [card] [Prerequisites](./prerequisites)
>
> Get your Organization UUID and complete the pre-upgrade inventory before working through this page.


# License and organization configuration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/organization-deployment

ORGANIZATION_ID Liquibase parameter on the 9 services that backfill org_id columns, the license microservice that connects self-hosted deployments to FlowX SaaS, and the env vars that replace the legacy Configure Environment Info UI.

Four configuration areas need attention during the 5.1.x → 5.9.x upgrade: the `ORGANIZATION_ID` Liquibase parameter on services that backfill `organization_id` columns, the new `license` microservice that connects self-hosted deployments to FlowX SaaS, the deployment-time env vars that replace the legacy "Configure Environment Info" UI, and the organization registration step at first launch.

> [!WARNING]
>
> **Confirm your upgrade plan with FlowX before starting.** Some 5.1.x deployment configurations require a custom migration path that this guide does not cover. Your FlowX representative will validate compatibility and provide any tailored migration scripts ahead of the upgrade window.

***

## `ORGANIZATION_ID`: where it is actually required

`ORGANIZATION_ID` is a Liquibase parameter used to backfill new `organization_id` columns on existing tables. It is NOT a service-wide config. Only the services that ship a Liquibase changeset reading `${organization-id}` consume it.

Set the UUID issued by FlowX (see [Prerequisites](./prerequisites#get-your-organization-uuid)) on these **9 services**:

* `application-manager`
* `authorization-system`
* `cms-core`
* `document-plugin`
* `integration-designer`
* `notification-plugin`
* `organization-manager`
* `process-engine`
* `scheduler-core`

Each of these services refuses to start without `ORGANIZATION_ID` set in a non-SaaS deployment. **Behavior depends on the deployment scenario:**

| Scenario | Is `ORGANIZATION_ID` required? | What happens |
| - | - | - |
| **Upgrade from 5.1.x** (this guide) | **Required** on the 9 services above | Liquibase backfills `organization_id` on existing rows with your UUID, then enforces `NOT NULL`. Missing → migration fails. |
| **Fresh 5.9.x install** (empty databases) | Not required | Each affected Liquibase changeset pre-checks for rows; with no rows to backfill, it skips the value-required step. |

The remaining services (`admin`, `advancing-controller`, `audit-core`, `data-search`, `data-sync`, `email-gateway`, `events-gateway`, `license`, `nosql-db-runner`, `runtime-manager`, `task-management-plugin`, `webhook-gateway`) do NOT declare `ORGANIZATION_ID` as a Liquibase parameter. Setting it on those is harmless but unnecessary.

> [!WARNING]
>
> **Do not set `ORGANIZATION_ID` on a SaaS deployment** (`FLOWX_SAAS=true`). The value is intended only for self-hosted upgrades and will conflict with the SaaS provisioning flow if set.

| Environment Variable | Description | Default Value |
| - | - | - |
| `ORGANIZATION_ID` | Organization UUID issued by FlowX. Liquibase backfill parameter on the 9 services above. | `-` (FlowX-provided) |

***

## The `license` service uses a separate env var

The `license` service does NOT read the Liquibase `ORGANIZATION_ID` parameter. Instead, it consumes `FLOWX_LICENSE_ORGANIZATIONID` at runtime as the OAuth client-id for the FlowX SaaS license handshake.

Both env vars carry the same UUID value, but they bind to different Spring properties on different services. See the next section for the full `license` service env var table.

***

## Liquibase migration

When you boot 5.9.x for the first time against your 5.1.x databases:

* **Active process instances** are migrated automatically. The default organization is replaced with your registered Organization UUID.
* **Inactive and archived process instances** are not migrated automatically. **FlowX provides custom migration scripts on demand**. Request these from your FlowX representative before resuming runtime traffic, otherwise inactive instances will not be visible to users post-upgrade.

Plan the upgrade window with enough margin for Liquibase to complete; large deployments with many active instances will see migration runtime measured in minutes per service.

> [!TIP]
>
> **Verify migration completion** by running the data-sync job after services boot. It surfaces any migration that failed silently or was skipped.

> [!WARNING]
>
> **Run the data-sync job before users log in.** Organizations provisioned on 5.1.x do not have the "All end-users" runtime group — it is created during organization provisioning or by the data-sync job. Until data-sync finishes, every login (including FlowX Designer) fails with an Internal Server Error in `authorization-system`:
>
> ```
> Could not find all end-users group for this organization
> ```
>
> Once data-sync completes, the group is created and the next login succeeds automatically — no cache clearing is required (the failed lookup is no longer cached).
>
> On `authorization-system` versions **older than 10.97.0**, the failed lookup is cached in Redis until the cache TTL (`REDIS_TTL`) expires. On those versions, clear the `authorization-system` cache entries (key prefix `flowx:core:cache:authorization-system:`) after data-sync completes, then log in again. FlowX.AI 5.9.1 ships `authorization-system` 10.103.0 or later, which includes this fix.

***

## The `license` microservice

5.9.x ships a `license` service (PostgreSQL + Redis + Kafka + SpiceDB) that connects self-hosted deployments to FlowX SaaS for:

* License validation against the registered Organization UUID.
* Usage reporting (process instances, active users, AI usage counters).
* Receipt of license events (renewal, expiry, plan changes).

Configure the connection. **All four values are provided by FlowX licensing** for the self-hosted deployment; none are derivable from the self-hosted environment:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_LICENSE_KEY` | License key issued by FlowX. Required — without it the license service cannot authenticate to FlowX SaaS, and the wizard's token validation step fails. | `-` |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization UUID issued by FlowX. Same value used as the `ORGANIZATION_ID` Liquibase parameter. The default `notset` must be replaced before the license service starts. | `notset` |
| `FLOWX_LICENSE_AUTHSERVERURL` | Auth endpoint provided by FlowX licensing. | `-` |
| `FLOWX_LICENSE_SERVERURL` | License API endpoint provided by FlowX licensing. | `-` |

> [!NOTE]
>
> **The `license` service authenticates against two Keycloak instances.** Inbound authentication uses the self-hosted Keycloak (configured via `SECURITY_OAUTH2_BASE_SERVER_URL` like every other service). Outbound calls to FlowX SaaS use a separate OAuth client, configured via the `FLOWX_LICENSE_*` env vars above.

> [!WARNING]
>
> **Outbound HTTPS to the FlowX-provided license endpoints** must be open from the `license` service. Confirm with your network team before the upgrade. Restricted environments may need an outbound proxy and an allow-list entry for the endpoints supplied with your license key.

***

## Required self-hosted env vars

The legacy environment-info UI is no longer available. Its values move to deployment-time env vars, set on the services below:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `DEFAULT_ORGANIZATION_NAME` | Organization code registered with FlowX. Used for Designer routing and display. | `''` | designer |
| `FLOWX_DEFAULT_DESIGNER_HOMEURI` | URL of the Designer container app served to this deployment. | `-` | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOMEURI` | URL of the generic runtime container app served to end users. | `-` | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWEDREDIRECTURIS` | Comma-separated list of redirect URIs allowed on the user realm. If empty, derived from the Designer/Runtime home URIs above. | `[]` | organization-manager |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | Self-hosted Keycloak base URL. | `-` | organization-manager |
| `SECURITY_OAUTH2_PUBLIC_SERVER_URL` | Public-facing Keycloak URL. Falls back to `SECURITY_OAUTH2_BASE_SERVER_URL` if unset. | `-` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Master key used to encrypt AI Provider credentials at rest. **Change from default before production.** | `default-dev-key-change-in-prod` | organization-manager |

> [!WARNING]
>
> **`LLM_ENCRYPTION_MASTER_KEY` must be changed from its default value before going to production.** The default `default-dev-key-change-in-prod` encrypts BYOK LLM provider credentials in the AI Providers UI. Leaving it in place means anyone with read access to the source code or default deployment manifests can decrypt your provider keys.

> [!NOTE]
>
> **Env var naming convention.** Spring relaxed binding accepts both the canonical UPPER\_SNAKE form (`FLOWX_DEFAULT_DESIGNER_HOMEURI`) and the squished form (`FLOWX_DEFAULT_DESIGNER_HOMEURI`). Examples in this guide use the canonical form to match the k8s base templates; if you copy env vars from an older Helm chart and see the squished form, both bind to the same property.

In addition, the `authorization-system` service requires master-realm admin credentials and service-account secrets. See [Authentication & IAM migration](./authentication-iam) for the full list.

***

## Creating the self-hosted organization

FlowX licensing provisions the organization and license for your deployment. After the platform is deployed, the Designer's first-time **Environment Setup** wizard captures the environment name and organization-admin credentials, then completes provisioning automatically.

![Environment Setup wizard with environment name and organization admin details](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/env_setup.png)

For environments where FlowX drives the installation, your FlowX representative leads this step. Self-installing operators receive the required values directly from FlowX licensing.

> [!WARNING]
>
> **Outbound HTTPS connectivity to FlowX SaaS is required during provisioning.** The wizard validates the license token and retrieves the subscription via the FlowX-provided endpoints. Without that connectivity the organization row is created and Keycloak realms are provisioned, but license validation fails. Restricted or air-gapped deployments must coordinate an offline-licensing path with FlowX before provisioning.

> [!TIP]
>
> **Manual Keycloak alternative.** If your environment does not allow the self-hosted platform to administer Keycloak (no master-realm admin available), follow the [Manual Keycloak Configuration recipe](/5.9/setup-guides/access-management/configuring-an-iam-solution) instead of the wizard. Realms, clients, and roles are then created manually in Keycloak; the platform reads them on first boot.

***

## Deprecated: "Configure Environment Info"

The Configure Environment Info UI in Designer is no longer available. Environment naming now happens during organization registration with FlowX.

The following API surface is changed; update any custom client tooling that relied on it:

* **`PATCH /api/platform/environment`**. Endpoint removed.

***

## Verify the configuration

After services boot on 5.9.x, confirm:

> [!TIP]
>
> Every service shows the new Organization UUID in its startup logs (search for `ORGANIZATION_ID` log lines).

> [!TIP]
>
> **Designer → Platform Status** shows all components at their 5.9.x target versions.

> [!TIP]
>
> Liquibase migrations completed on every service. No service is in a "migration pending" state.

> [!TIP]
>
> The `license` service is reachable from your network to FlowX SaaS. License validation succeeds and usage events are being published.

> [!TIP]
>
> `LLM_ENCRYPTION_MASTER_KEY` is set to a non-default value before any LLM provider is configured.

***

## Related resources

> [card] [v5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9)
>
> Component versions, third-party dependency versions, and the complete env var diff.

> [card] [License engine setup](/5.9/setup-guides/license-engine-setup)
>
> Full license service setup including PostgreSQL, Redis, and Kafka topology.

> [card] [Organization manager setup](/5.9/setup-guides/organization-manager-setup)
>
> Deeper reference for organization-manager configuration.

> [card] [Authentication & IAM migration](./authentication-iam)
>
> Prerequisite. The Keycloak transition that supports this configuration.


# React SDK
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/react

Migrate the FlowX React renderer SDK from 5.1.x LTS to 5.9.x.

## React SDK migration guide

5.9 bumps the React renderer to React 19, Node 24, and npm 11. Custom validators move to a Valtio-based layer, and the SDK exposes new top-level props (`cache`, interceptors, `onProcessEnded`, `buildId`).

### Framework upgrade: React 18 → 19

The 5.9 React SDK requires React 19 in the host app. Follow the official [React 19 upgrade guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide).

| Requirement | 5.1 | 5.9 |
| - | - | - |
| React | \~18 | **19** |
| Node | 18.16.9 | **≥ 24.0.0** |
| npm | v10.8.0 | **≥ 11.0.0** |

> [!WARNING]
>
> The host app **must** be on React 19 before installing the 5.9 SDK. Mixed-React trees fail at runtime with hook-mismatch errors.

### FlowX SDK changes

#### Organization ID property

We've added a new `organizationId` mandatory prop to the `FlxProcessRenderer` component. See SDK documentation for more details.

```typescript theme={"dark"}
<FlxProcessRenderer
  ...
  organizationId={'10000001-0001-0001-8001-100000000001'}
/>
```

#### Custom validators no longer use React Hook Form

In 5.1, validators were piped through React Hook Form. In 5.9 they are processed through a custom Valtio-based validation layer.

The validator function signature is unchanged:

```typescript theme={"dark"}
const myValidator = (...params: string[]) => (v: any) => boolean | Promise<boolean>
```

If you relied on React Hook Form internals (e.g. `register`, `setError`, `getValues`) inside a custom validator, refactor to use only the value argument `v`.

### Theming and components

`@flowx/react-sdk` now depends directly on `date-fns@4`. Host apps that pin `date-fns` must move to the 4.x line.

`@flowx/react-ui-toolkit` bumps `air-datepicker` to `3.6.0` and adds `marked` and `sanitize-html` to support markdown rendering in rich-text components.

## Related resources

> [card] [React SDK reference](/5.9/sdks/react-renderer)
>
> React renderer SDK documentation

> [card] [Migration overview](./overview)
>
> Full 5.1.x LTS → 5.9.x upgrade guide


# Runtime authorization migration
Source: https://docs.flowx.ai/5.9/migrating-from-5.1-lts/runtime-authorization

How runtime roles, end-user groups, and solution sharing change between FlowX.AI 5.1.x and 5.9.x, and what you need to redo per environment after the upgrade.

In 5.1.x, runtime roles were assigned to end users at the organization level and granted access across every project that listed that role. 5.9.x ships a rewritten runtime authorization model: role assignments are **project-version-scoped**, end-user groups move out of Keycloak into FlowX-managed records, and sharing is configured per environment via the Solutions → Share modal.

This page covers the migration concepts. For day-to-day operation of the new model, see the [Runtime authorization setup guide](/5.9/setup-guides/access-management/runtime-authorization).

***

## Mental model: what changed

> [!WARNING]
>
> **Keycloak realm roles no longer drive runtime access.** In 5.1.x, a user's Keycloak realm roles were consulted at request time to authorize runtime access. In 5.9.x they are not — runtime authorization is decided entirely by FlowX's own model, through project-scoped role assignments made in the **Solutions → Share** modal. If your 5.1.x rollout granted end users runtime access through Keycloak roles, that access stops at the upgrade until it is reassigned in FlowX.
>
> Keycloak still authenticates users and can still supply **group membership** — not roles — to the FlowX model through the [`attributes.runtimeGroups` claim](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper). Only membership carries over; role-based authorization does not.

| Concern | 5.1.x | 5.9.x |
| - | - | - |
| Where runtime roles are assigned | Directly to users at organization level | To users **in the context of a project**, via the Solutions → Share modal |
| Cross-project effect | One role grants access on every project that lists it | Role grants access only on the solutions it has been explicitly shared on |
| End-user groups | Managed in Keycloak | Managed in **FlowX**, assigned to roles on each solution |
| Authentication of end users | Keycloak | Keycloak (unchanged) |
| Authorization decisions | Keycloak-issued roles consulted at request time | FlowX-managed runtime authorization service tuned for the volume of runtime permission checks |
| Designer-time permissions | SpiceDB | SpiceDB (unchanged — separate engine) |

> [!NOTE]
>
> **Why two engines?** SpiceDB stays as the design-time permission engine for Designer access. Runtime authorization is a separate custom service because the volume of runtime permission evaluations made SpiceDB latency unacceptable. Both coexist and don't interact at runtime.

***

## What migrates automatically

The 5.9.x Liquibase migrations handle the bulk of the role + group transition for you:

**1. Existing role-on-user assignments preserved**

If your 5.1.x users have runtime roles assigned directly, those assignments continue to work after the upgrade. New solutions and new role assignments use the project-scoped model going forward.

**2. Default `User` role on every UI Flow**

5.9.x gates access per UI Flow with an explicit role allow-list. On upgrade, each UI Flow's allow-list is populated from the runtime roles carried by its latest build (typically the default `User` role), so existing end users generally keep access. **Review each UI Flow** after the upgrade to confirm the resolved roles and tighten them as part of the post-upgrade pass.

**3. End-user groups created in FlowX**

End-user groups previously held in Keycloak are migrated into FlowX-managed records (org-level, named buckets of users). The migration also creates a group named **Users Group**, populated with the users who held the `FLOWX_ROLE` realm role in 5.1.x. On 5.9.0 and 5.9.1 this group was created as `User`; upgrading to 5.9.2 or later renames it to `Users Group`. Confirm the migrated group list under **Organization Settings → Access Management → End-User Groups** after the upgrade and adjust as needed.

> [!NOTE]
>
> **Migrated end users appear only after their first sign-in.** Users carried over from your 5.1.x Keycloak realm are not listed under **End-Users** until each one signs in to 5.9.x for the first time. On that first login the user is placed in the built-in **All end-users** group, which on its own grants access to no solution — they gain runtime access only once assigned a role on a solution (directly or through a runtime group). Expect the End-Users list to fill in gradually as users log in, not all at once at upgrade.

> [!NOTE]
>
> **Keeping group membership in Keycloak or an external IDP.** The migration moves the group *definitions* into FlowX, but you choose where *membership* is administered going forward. If you assign users to end-user groups directly in FlowX (Designer / Organization Settings), no Keycloak token claim is involved. If you keep membership in **native Keycloak groups or a federated IDP** — the model most 5.1.x rollouts are built on — runtime authorization reads each user's groups from the `attributes.runtimeGroups` access-token claim and matches those values against FlowX end-user group names by **exact string comparison**. No `attributes.runtimeGroups` mapper ships in the realm template; add one per organization so existing Keycloak/IDP group members keep runtime access without being reassigned in FlowX one by one. If a mapper or IDP claim references the migration-created group by its pre-5.9.2 name `User`, update the emitted value to `Users Group` when upgrading to 5.9.2 — the old name no longer matches any group. See [Runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) for the setup steps.

***

## What does not migrate (and must be redone per environment)

> [!WARNING]
>
> **Sharing assignments do not export between environments.** This is intentional. When you promote a project build from one environment to another (dev → uat → prod), the Solutions → Share modal assignments are **not** carried over. Re-configure sharing per environment as part of every deployment.

Plan your post-upgrade pass, and every future promotion, around:

* Pick the **Active Policy** for each project. The Share modal only lists roles available in the build set as Active Policy.
* Re-create end-user group assignments per environment.
* Re-issue invitations through Keycloak SMTP for new end users that were created in FlowX as part of the migration.

***

## UI Flow permissions

5.9.x adds an allow-list of roles on every UI Flow. After the upgrade:

**1. Audit the default assignment**

Every UI Flow carried over from 5.1.x lists the runtime roles resolved from its latest build (typically the default `User` role). This preserves access for existing end users but is often broader than most production deployments want.

**2. Tighten per UI Flow**

Open each UI Flow in the Designer and reduce the role list to the minimum that needs interactive access. Components inside UI Flows can also be hidden or disabled per role. Use this for finer-grained restrictions inside flows that several roles can still launch.

**3. Test as each role**

Create a test end-user assigned to a single role, sign in, and verify the UI Flow allow-list and component-level visibility behave as expected.

***

## Designer-user bypass

A user with **Designer access to a project** can run that project at runtime without being assigned a runtime role on it.

* Auto-grants view, execute, and self-assign on every swimlane in the project.
* Lets a project's designers test their own work without being filed into the runtime role catalog.
* Designer users **cannot** test scenarios "as another runtime role." To verify role-specific behavior, create a test end-user, assign the role through the Share modal, and sign in as that user.

The bypass is implemented through a `designerUser` Keycloak user attribute (boolean) auto-managed at organization provisioning. If your environment uses a federated IDP for designer accounts, you may need to add this attribute via an IDP mapper. See [Configuring an IAM solution → Designer user attribute](/5.9/setup-guides/access-management/configuring-an-iam-solution#designer-user-attribute).

***

## What stays in Keycloak vs FlowX

| Concern | System of record |
| - | - |
| Authentication, password policy, MFA | Keycloak |
| User attributes used by [business filters](/5.9/docs/platform-deep-dive/user-roles-management/business-filters) | Keycloak |
| Federation with external IDPs | Keycloak |
| Runtime role catalog | FlowX |
| End-user group definitions | FlowX |
| End-user group **membership** | FlowX, or Keycloak / a federated IDP via the [`attributes.runtimeGroups` mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) |
| Project-scoped role assignment (sharing) | FlowX |

***

## Active policy: convert role overrides to group overrides

5.9.0 removes the **Role** override type from active policy. Existing role overrides survive the upgrade visually — they appear in the overrides table with a **DEPRECATED** marker — but they are excluded from runtime resolution. If your 5.1.x setup relied on role overrides to serve a specific build or branch to a subset of end users, redo that targeting with group overrides before promoting the upgrade to production.

**1. List the role overrides you had in 5.1.x**

For each project, open **Runtime Settings → Active Policy** and note the role, policy type (Latest on Branch or Build), branch/build, and priority of every role override you relied on.

**2. Identify the matching runtime group**

In 5.9.x, end-user access is configured via runtime groups in the Solutions → Share modal. For each former role override, identify the runtime group whose members should receive the same build or branch. Where you previously targeted a role used by multiple groups, decide whether one group override is enough or whether you need a per-group entry.

**3. Create the group overrides**

In **Runtime Settings → Active Policy**, click **Add**, choose **Group**, pick the runtime group, set the policy and branch/build, and assign a unique priority. Priority is mandatory for group overrides and decides which one wins when a user belongs to several matching groups. Username overrides always take precedence over group overrides.

**4. Delete the deprecated role overrides**

Once the equivalent group overrides are in place, delete each deprecated role override row from the table. They have no runtime effect, but removing them keeps the overrides table clean and avoids confusion during audits.

> [!TIP]
>
> Repeat this conversion per environment. Like sharing assignments, active policy overrides are not exported with the build and must be reconfigured on each environment the project is promoted to.

***

## Post-upgrade checklist

> [!TIP]
>
> End-user groups visible under **Organization Settings → Access Management → End-User Groups** match the groups you had in Keycloak.

> [!TIP]
>
> Every UI Flow's role allow-list reviewed and tightened from the default `User` assignment.

> [!TIP]
>
> For each project, the **Active Policy** build is the one you want sharing assigned against.

> [!TIP]
>
> Active policy role overrides from 5.1.x replaced with equivalent group overrides; deprecated role rows deleted.

> [!TIP]
>
> Sharing assignments rebuilt per environment. Confirm at least one end user can access each solution as expected.

***

## Related resources

> [card] [Runtime authorization setup guide](/5.9/setup-guides/access-management/runtime-authorization)
>
> Project-scoped roles, the Share modal, end-user groups, and IDP federation in day-to-day operation.

> [card] [End-user access management](/5.9/setup-guides/access-management/end-user-access-management)
>
> Org-level end-user, role, and group management.

> [card] [Authentication & IAM migration](./authentication-iam)
>
> Previous step. The Keycloak transition this rewrite depends on.

> [card] [License and organization configuration](./organization-deployment)
>
> Next step. `ORGANIZATION_ID` Liquibase parameter, the new `license` service, and the env vars that replace the legacy Configure Environment Info UI.


# Release Notes
Source: https://docs.flowx.ai/release-notes/overview

What shipped in every FlowX.AI release - new features, bug fixes, deployment guidelines, and migration steps for the 5.9.x and 5.1.x LTS lines and monthly feature releases.

Release notes · FlowX.AI

What shipped.
Every release, every line.

What shipped in every FlowX.AI release: new features, bug fixes, deployment guidelines, and migration steps. Pick your line below, or jump straight to the latest LTS patch and feature release.

[Latest LTS: 5.9.6](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[Feature release: 6.0.0](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

> [!NOTE]
>
> **Long Term Support (LTS) Versions:** LTS versions receive extended support with security updates and critical bug fixes. **5.9.x** is the current FlowX.AI LTS line, recommended for production environments requiring stability and long-term support. Support for the **5.1.x** line ended with 5.1.14, its final maintenance release. To keep receiving fixes, move to 5.9.x: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview). Release notes for older lines, including 5.1.x and 4.7.x, remain published for reference.
>
> **Feature Releases:** Versions released between LTS lines (such as 5.10.0) introduce new capabilities and are deployed to FlowX.AI SaaS environments as they ship. Self-hosted deployments receive these features consolidated into the next LTS release.

01 · Latest

## Latest releases

[LTS
v5.9.6
Maintenance release for the 5.9.x LTS line. Released on October 20th, 2026.](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)

[FEATURE
v6.0.0
Feature release, live on FlowX.AI SaaS. Released on October 30th, 2026.](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[LTS
v5.1.14
Final maintenance release for the 5.1.x LTS line. Released on October 30th, 2026.](./v5.x/v5.1.x-lts/v5.1.14-october-2026)

> [!TIP]
>
> **New cookbook:** [reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation), from email intake to exception review. More end-to-end builds are in the [cookbooks](/5.9/cookbooks/overview).

***

02 · All releases

## All releases

Planning a 5.9.x upgrade? The [5.9.x LTS changelog](./v5.x/5.9-lts-changelog) lists every change in each 5.9.x maintenance release on one page, with an RSS feed.

Moving from 5.9.x to 6.0.0? The [5.9.x to 6.0.0 changelog](./v6.x/5.9-to-6.0-changelog) lists every change from the 5.10 to 5.13 feature releases and 6.0.0 on one page, with an RSS feed.

versionlinereleased

[v6.0.0FRfeature releaseOctober 30th, 2026→](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[v5.1.14LTSmaintenance · 5.1.x LTS lineOctober 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.14-october-2026)
[v5.9.6LTSmaintenance · 5.9.x LTS lineOctober 20th, 2026→](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[v5.13.0FRfeature releaseSeptember 28th, 2026→](./v5.x/v5.13.0-september-2026/v5.13.0-september-2026)
[v5.9.5LTSmaintenance · 5.9.x LTS lineSeptember 23rd, 2026→](./v5.x/v5.9.5-september-2026/v5.9.5-september-2026)
[v5.1.13LTSmaintenance · 5.1.x LTS lineSeptember 18th, 2026→](./v5.x/v5.1.x-lts/v5.1.13-september-2026)
[v5.12.0FRfeature releaseSeptember 3rd, 2026→](./v5.x/v5.12.0-september-2026/v5.12.0-september-2026)
[v5.9.4LTSmaintenance · 5.9.x LTS lineAugust 27th, 2026→](./v5.x/v5.9.4-august-2026/v5.9.4-august-2026)
[v5.1.12LTSmaintenance · 5.1.x LTS lineAugust 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.12-august-2026)
[v5.11.0FRfeature releaseAugust 11th, 2026→](./v5.x/v5.11.0-august-2026/v5.11.0-august-2026)
[v5.9.3LTSmaintenance · 5.9.x LTS lineJuly 30th, 2026→](./v5.x/v5.9.3-july-2026/v5.9.3-july-2026)
[v5.1.11LTSmaintenance · 5.1.x LTS lineJuly 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.11-july-2026)
[v5.9.2LTSmaintenance · 5.9.x LTS lineJuly 10th, 2026→](./v5.x/v5.9.2-july-2026/v5.9.2-july-2026)
[v5.10.0FRfeature releaseJuly 7th, 2026→](./v5.x/v5.10.0-july-2026/v5.10.0-july-2026)
[v5.1.10LTSmaintenance · 5.1.x LTS lineJune 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.10-june-2026)
[v5.9.1LTSmaintenance · 5.9.x LTS lineJune 15th, 2026→](./v5.x/v5.9.1-june-2026/v5.9.1-june-2026)
[v5.9.0LTSfirst release of the 5.9.x LTS lineJune 2nd, 2026→](./v5.x/v5.9.0-june-2026/v5.9.0-june-2026)
[v5.1.9LTSLTS maintenance releaseMay 29th, 2026→](./v5.x/v5.1.x-lts/v5.1.9-may-2026)
[v5.8.0FRfeature releaseMay 10th, 2026→](./v5.x/v5.8.0-may-2026/v5.8.0-may-2026)
[v5.1.8LTSLTS maintenance releaseApril 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.8-april-2026)
[v5.7.0FRfeature releaseApril 28th, 2026→](./v5.x/v5.7.0-april-2026/v5.7.0-april-2026)
[v5.6.0FRfeature releaseMarch 25th, 2026→](./v5.x/v5.6.0-march-2026/v5.6.0-march-2026)
[v5.1.7LTSLTS maintenance releaseMarch 26th, 2026→](./v5.x/v5.1.x-lts/v5.1.7-march-2026)
[v5.1.6LTSLTS maintenance releaseMarch 16th, 2026→](./v5.x/v5.1.x-lts/v5.1.6-march-2026)
[v5.5.0FRfeature releaseFebruary 27th, 2026→](./v5.x/v5.5.0-february-2026/v5.5.0-february-2026)
[v5.1.5LTSLTS maintenance releaseFebruary 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.5-february-2026)
[v5.1.4LTSLTS maintenance releaseFebruary 9th, 2026→](./v5.x/v5.1.x-lts/v5.1.4-february-2026)
[v5.4.0FRfeature releaseJanuary 30th, 2026→](./v5.x/v5.4.0-january-2026/v5.4.0-january-2026)
[v5.1.3LTSLTS maintenance releaseJanuary 15th, 2026→](./v5.x/v5.1.x-lts/v5.1.3-january-2026)
[v5.3.0FRfeature releaseDecember 24th, 2025→](./v5.x/v5.3.0-december-2025/v5.3.0-december-2025)
[v5.1.2LTSLTS maintenance releaseDecember 3rd, 2025→](./v5.x/v5.1.x-lts/v5.1.2-december-2025)
[v5.2.0FRfeature releaseNovember 10th, 2025→](./v5.x/v5.2.0-november-2025/v5.2.0-november-2025)
[v5.1.1LTSLTS maintenance releaseNovember 10th, 2025→](./v5.x/v5.1.x-lts/v5.1.1-november-2025)
[v4.7.11LTSLTS maintenance releaseDecember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025)
[v4.7.10LTSLTS maintenance releaseNovember 17th, 2025→](./v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025)
[v4.7.9LTSLTS maintenance releaseOctober 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025)
[v5.1.0LTSLTS maintenance releaseOctober 2nd, 2025→](./v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025)
[v4.7.8LTSLTS maintenance releaseSeptember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025)
[v4.7.7LTSLTS maintenance releaseAugust 20th, 2025→](./v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025)
[v5.0.0FRfeature releaseJuly 31st, 2025→](./v5.x/v5.0.0-july-2025/v5.0.0-july-2025)
[v4.7.6LTSLTS maintenance releaseJuly 18th, 2025→](./v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025)
[v4.7.5LTSLTS maintenance releaseJune 19th, 2025→](./v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025)
[v4.7.4LTSLTS maintenance releaseMay 15th, 2025→](./v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025)
[v4.7.3LTSLTS maintenance releaseApril 14th, 2025→](./v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025)
[v4.7.2LTSLTS maintenance releaseMarch 26th, 2025→](./v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025)
[v4.7.1LTSLTS maintenance releaseMarch 7th, 2025→](./v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025)
[v4.7.0LTSLTS maintenance releaseFebruary 24th, 2025→](./v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025)
[v4.6.1FRfeature releaseFebruary 7th, 2025→](./v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025)
[v4.6.0FRfeature releaseJanuary 23rd, 2025→](./v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025)
[v4.1.5LTSLTS maintenance releaseSeptember 23rd, 2024→](./v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024)
[v4.1.4LTSLTS maintenance releaseSeptember 6th, 2024→](./v4.x/v4.1.x/v4.1.4-september-2024/v4.1.4-september-2024)
[v4.1.3LTSLTS maintenance releaseAugust 12th, 2024→](./v4.x/v4.1.x/v4.1.3-august-2024/v4.1.3-august-2024)
[v4.1.2LTSLTS maintenance releaseJune 8th, 2024→](./v4.x/v4.1.x/v4.1.2-june-2024/v4.1.2-june-2024)
[v4.1.1LTSLTS maintenance releaseJune 17th, 2024→](./v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024)
[v4.1.0LTSLTS maintenance releaseMay 30th, 2024→](./v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024)
[v4.0.0FRfeature releaseApril 18th, 2024→](./v4.x/v4.0.0-april-2024/v4.0.0-april-2024)

> [!NOTE]
>
> Releases from the **4.5.x (tech preview)** and **4.2.x** lines are not listed above. You can find them in the sidebar under **Release Notes** → **v4.x**.

***

> [accordion] Version 3.x.x
>
> > [card] [v3.4.8 - June 2024](/release-notes/v3.x.x/v3.4.8-june-2024/v3.4.8-june-2024)
> >
> > Explore the latest enhancements and fixes introduced in June 2024.
>
> > [card] [v3.4.7 - January 2024](/release-notes/v3.x.x/v3.4.7-january-2024/v3.4.7-january-2024)
> >
> > Explore the latest enhancements and fixes introduced in January 2024.
>
> > [card] [v3.4.6 - December 2023](/release-notes/v3.x.x/v3.4.6-december-2023/v3.4.6-december-2023)
> >
> > Explore the latest enhancements and fixes introduced in December 2023.
>
> > [card] [v3.4.5 - November 2023](/release-notes/v3.x.x/v3.4.5-november-2023/v3.4.5-november-2023)
> >
> > Explore the latest enhancements and fixes introduced in November 2023.
>
> > [card] [v3.4.4 - November 2023](/release-notes/v3.x.x/v3.4.4-november-2023/v3.4.4-november-2023)
> >
> > Discover the significant changes and improvements made in November 2023.
>
> > [card] [v3.4.3 - October 2023](/release-notes/v3.x.x/v3.4.3-october-2023/v3.4.3-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.2 - October 2023](/release-notes/v3.x.x/v3.4.2-october-2023/v3.4.2-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.1 - September 2023](/release-notes/v3.x.x/v3.4.1-september-2023/v3.4.1-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.4.0 - September 2023](/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.3.0 - July 2023](/release-notes/v3.x.x/v3.3.0-july-2023/v3.3.0-july-2023)
> >
> > Discover the significant changes and improvements made in July 2023.
>
> > [card] [v3.2.0 - April 2023](/release-notes/v3.x.x/v3.2.0-april-2023/v3.2.0-april-2023)
> >
> > Discover the significant changes and improvements made in April 2023.
>
> > [card] [v3.1.0 - March 2023](/release-notes/v3.x.x/v3.1.0-march-2023/v3.1.0-march-2023)
> >
> > Discover the significant changes and improvements made in March 2023.
>
> > [card] [v3.0.0 - February 2023](/release-notes/v3.x.x/v3.0.0-february-2023/v3.0.0-february-2023)
> >
> > Discover the significant changes and improvements made in February 2023.


# FlowX.AI 5.9.x to 6.0.0 changelog
Source: https://docs.flowx.ai/release-notes/v6.x/5.9-to-6.0-changelog

Every change a self-hosted FlowX.AI 5.9.x installation picks up when it moves to 6.0.0, grouped by release and type, with an RSS feed.

This page lists what changes for a self-hosted FlowX.AI 5.9.x installation that moves to 6.0.0, newest first. Releases 5.10 to 5.13 shipped to SaaS first, and self-hosted installations get their features with 6.0.0. Changes already delivered in a 5.9.x patch are in the [5.9.x LTS changelog](/release-notes/v5.x/5.9-lts-changelog) and are not repeated here. Mobile renderers and the React Native SDK are covered in their own release notes.

On FlowX.AI SaaS, apps moved from 5.13.0 to 6.0.0, so only the 6.0.0 entry applies to them, including its upgrade actions.

**6.0.0**

October 2026

**Upgrade actions:** check these in your existing apps.

* **AI node prompts:** the chat message is no longer appended. Reference `${userMessage}` in **Context**. [Details](/6.x/ai-platform/chat-driven-workflows#context)
* **AI node retries:** on by default, up to 10 times, 30 seconds apart. [Details](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service)
* **Substitution tags:** `@@key` is rewritten to `${tag:key}`, and a missing `sys_*` tag now renders empty. [Details](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#what-changes-in-existing-apps-when-you-upgrade)
* **FlowX Database and Unmanaged MongoDB writes:** `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter are rejected. To match every document, pass `{"_id": {"$exists": true}}`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb)
* **Masked names:** data-privacy placeholders now carry the gender, such as `<NAME_F_1>`. Update prompts or scripts that match `<NAME_1>`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy)
* **Email triggers over IMAPS:** the mail server's certificate is now verified, so a self-signed or mismatched certificate stops the trigger from connecting. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway)
* **Evaluations:** datasets become test cases with no checks, so an experiment skips them until you add an assert or evaluator. [Details](/6.x/ai-platform/evaluations#datasets-from-earlier-versions)
* **Exports from 5.1.x:** they no longer import, and 5.1.x is no longer an export target. Import a 5.1.x export into a 5.9.x environment and export it again from there. [Details](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x)
* **Scripts on GraalVM:** they now stop at the same per-language time limit as the native engine, 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0 they had no limit. [Details](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits)

Self-hosted installations also follow the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) and the [migration guide](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview) for the Helm chart and renderer SDKs.

#### New

* **Developer Agentic Harness:** a plan can split the work into stories, delivered one at a time, each with how to test it. Comment mode lets you select a component in the running app and ask for a change, and conversations follow you across the Designer. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Integration Designer:** add schedules to a workflow's Start node to run it once on a date or repeatedly on an ISO or cron cycle. A schedule fires only after you activate it in **Runtime** → **Runtime Settings** → **Schedules**. See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
* **Integration Designer:** the Generate Tabular File node turns an array of rows into a CSV or XLSX file. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
* **FlowX Database:** an index can enforce unique values on one attribute or a compound key, and existing duplicates are reported when you run **Apply Indexes**. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
* **Knowledge Base:** **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
* **Resources:** **Documentation** in a resource's menu holds a short description and longer Markdown documentation. Media Library assets get a description, used as the image's alt text. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
* **Substitution tags:** write `${tag:key}` anywhere in a component's text, next to static text and process data. The upgrade rewrites whole-value `@@key` references to `${tag:key}`, and `@@key` keeps working as a whole value. See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).

#### Changed

* **Designer header:** the header holds the project name, the **Config** / **Runtime** switch, the **Build with AI** and **Comment** toggles, and **Run project**. Branching, the current version, and **Commit Changes** move to a version block in the footer. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
* **AI nodes:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when its AI service or provider can't be reached. Turn on **Allow Retry** to set your own count, interval, and backoff. See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
* **Chat-driven workflows:** the chat message is no longer appended to an AI node's prompt. Reference `${userMessage}` in the node's **Context**. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
* **Evaluations:** each workflow has its own test cases, grouped by tags, with **equals** and **equals as JSON** asserts and LLM evaluators. The upgrade converts datasets to test cases with no checks, so add an assert or evaluator to each one before you run it. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
* **Certificates:** the **Certificates** panel on REST and File Storage data sources has two parts: **Trust** (System CAs, Custom CA, or None (insecure)) and **Identity** for mutual TLS. Existing settings are converted automatically. See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates).
* **Knowledge Base:** turning **Containing Personal Information** on or off re-embeds the existing content with the new model. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested).
* **Issues Console:** a check also covers the version itself: entry points, theme, library builds, and unused dependencies. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
* **Notification center:** covers version imports and build exports and imports, alongside version exports and process instance migrations. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
* **Configuration parameters:** after you save a sensitive value, the Designer shows `********` in its place. The real value is still used at runtime. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
* **Script engine:** scripts on GraalVM stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
* **Canvas:** **Auto-arrange** on the workflow canvas and **Arrange** on the process canvas show a layout preview before anything moves. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).
* **Timer events:** timer nodes use the schedule editor. Dates and times are picked in local time and saved in UTC. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).
* **Versioning:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).
* **Datepicker:** **Allow manual input** lets users type a date in the pattern of the project's default locale. Web only.
* **Data mapping:** typing a new attribute path, such as `client.address.street`, creates the data types it names when you save the mapping.

#### Removed

* **AI agents:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors are removed. Open the agent rail with ⌘K (Ctrl+K) or the sparkle toggle in the header. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Evaluations:** the Code evaluators are removed. Use **equals** in place of Exact match and **equals as JSON** in place of JSON match. Levenshtein has no replacement. See [Evaluations](/6.x/ai-platform/evaluations).
* **Export and import:** exports from 5.1.x no longer import, and 5.1.x is no longer an export target. See [Exports from 5.1.x](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x).

#### Deprecated

* **GraalVM script engine:** deprecated. FlowX.AI 6.1.x is the last release family that supports it. Scripts on GraalVM keep working in 6.0.0; move them to the native engine. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).

[6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) · [6.0.0 deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)

**5.13.0**

September 2026

#### New

* **Developer Agentic Harness:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys the app, drafts a plan for you to confirm, and runs the change on its own branch; merging and serving a new version stay with you. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Notification center:** a bell in the Designer opens a 30-day notification history with read state, search, and filters. See [Notification center](/6.x/docs/flowx-designer/notification-center).
* **UI Designer:** copy UI components and paste them into another UI Flow, app, or context. The paste names anything it could not place, and pasted components get unique names.
* **Versioning:** committing or merging a version takes an optional description of up to 2000 characters, and a commit details view shows what a version contains. See [Commit descriptions and details](/6.x/docs/projects/managing-applications/versioning#commit-descriptions-and-details).
* **Runtime:** an operator with the corrective-actions role moves the token of a running process instance to another node. See [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
* **Document classifiers:** a classifier's corpus can be exported and imported between environments, and viewed read-only in the **Data** tab. See [What travels between environments](/6.x/docs/platform-deep-dive/integrations/document-classifiers#what-travels-between-environments).
* **Integration Designer:** the File Encryption node encrypts or decrypts a file with a password inside a workflow. The file path and password take expressions.
* **UI Designer:** a start workflow trigger takes a condition, so the workflow starts only when the condition holds.&#x20;
* **FlowX Database:** the Intersects operator matches documents whose array field shares at least one value with a given list. See [Intersects on array fields](/6.x/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).
* **Personal Information Guard:** AI nodes with the input scan on log the request as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/6.x/ai-platform/personal-information-guard#request-after-pii-anonymization).

#### Changed

* **Access management:** the Workspace corrective actions editor role replaces the Workspace operations editor role. Users and groups with the old role move to the new one automatically. See [Workspace corrective actions editor permission matrix](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
* **Export and import:** version exports bundle dependencies the same way build exports do, and the export dialog preselects the target platform version. See [Version exports that bundle dependencies](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#version-exports-that-bundle-dependencies).
* **Integration Designer:** the Tabular Data Extraction node becomes the Data Parse node and also parses XML and JSON. See [Data Parse: XML and JSON support](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support).
* **Knowledge Base:** embedding jobs are scheduled fairly by default, so a large ingestion no longer delays small jobs queued behind it.
* **File sources:** Document and Image components share one source configuration. In process user tasks, the **Document Plugin Path** source takes a Documents plugin `downloadPath` directly. See [Selecting the file to download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download#selecting-the-file-to-download).
* **Task management:** the task list searches, filters, and sorts on the translated labels it displays. See [Search and sort on translated labels](/6.x/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).
* **Substitution tags:** custom tags can no longer start with `sys_`, which is reserved for system tags. See [Substitution tags](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags).
* **Elasticsearch:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Elasticsearch replica auto-expansion](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).
* **Processes:** the process name moves from **Settings** into a **Details** modal.
* **User management:** inviting many users at once has a reworked flow, and a sign-up link takes new users directly to the right solution.

[5.13.0 release notes](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) · [5.13.0 deployment guidelines](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13)

**5.12.0**

September 2026

**Upgrade actions:** the webhook gateway now reads the runtime registry, which adds a MongoDB dependency it did not have before. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets).

#### New

* **Integration Designer:** turn on **Parallel Multi-Instance** on a Subworkflow node to start one subworkflow per element of an input array and collect the results in an output array. See [Parallel multi-instance](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance).
* **Integration Designer:** email and webhook triggers can start an integration workflow, not only a process. See [External triggers](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).
* **Integration Designer:** a Subworkflow node can route a mapping failure to its own branch instead of stopping the parent workflow. It is opt-in per node. See [Routing a subworkflow failure](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
* **Integration Designer:** the Send Notification node fills a project notification template from workflow data and sends it. See [Send Notification node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node).
* **Db2 data source:** IBM Db2 joins the relational data sources, with Db2 for i as the default and Db2 LUW also supported. Db2 for z/OS is listed but not implemented, and selecting it fails with an error. See [Db2 database](/6.x/docs/platform-deep-dive/integrations/db2-database).
* **Runtime:** bulk migration moves a filtered set of process instances to a new build in one run, with a check before it runs. See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances).
* **Runtime:** a Workflow Instances page lists every workflow run in the project, filterable by status, date, and origin. The Process Instances and UI Flow Sessions lists gain status and start-date filters. See [Workflow instances](/6.x/docs/projects/runtime/workflow-instances).
* **Personal Information Guard:** mask and restore nodes place personal-data handling as explicit workflow steps. See [Masking and restoring across several nodes](/6.x/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
* **Deep Research node:** researches a question across the open web and files a cited report into a Knowledge Base. Depth is Quick, Standard, Deep, or Custom, and domains can be restricted with an allow or deny list. See [Deep Research node](/6.x/docs/platform-deep-dive/integrations/deep-research-node).
* **Custom Agent:** a reusable function with input and output slices can be an agent tool. Built-in tools are a catalog of twenty tools in five categories: Math, List, Date, Text, and Web search. See [Tools tab](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#tools-tab).
* **Chat component:** users rate an agent's answer and add a reason, and the ratings are recorded in audit. See [Rating an answer](/6.x/ai-platform/chat-component#rating-an-answer).
* **Evaluations:** custom evaluators score with Numeric or Binary rules and belong to the workflow you create them in. See [Custom evaluators](/6.x/ai-platform/evaluations#custom).
* **Issues panel:** the Designer validates the resources in a project version and collects the findings in one **Issues** panel. See [Checking for issues](/6.x/docs/projects/managing-applications/checking-for-issues).
* **Versioning:** merge into any branch you can merge into, and archive, unarchive, or delete branches. See [Managing branches](/6.x/docs/projects/managing-applications/versioning#managing-branches).
* **Process canvas:** a **New Node** panel, drop-anywhere connecting, draggable control points on sequence flows, and swimlanes that resize from all four edges. See [Faster ways to build](/6.x/docs/building-blocks/process/process#faster-ways-to-build).
* **Reusable UI templates:** a template can be built for UI Flow pages as well as process user tasks. Templates created earlier count as Process templates. See [Where a template can be used](/6.x/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used).

[5.12.0 release notes](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026) · [5.12.0 deployment guidelines](/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12)

**5.11.0**

August 2026

#### New

* **Custom Agent:** attach FlowX workflows as tools, each with a hint that tells the agent when to call it. See [How workflow tools run](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run).
* **Custom Agent:** agentic knowledge base search breaks a question into sub-queries and retries with reworded queries when the first pass finds nothing. **Show Reasoning** records the model's reasoning summary in the logs. See [Agentic knowledge base search](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#agentic-knowledge-base-search).
* **Knowledge Base:** a Knowledge Base with **Containing Personal Information** on can use a local embedding model, set up as a CUSTOM provider in the organization AI settings. See [Containing personal information](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).
* **Knowledge Base:** the Update Knowledge Base node can delete entries that match a metadata filter, and its FAIL branch reports what failed and how many chunks were rolled back. See [Delete entries](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#delete-entries).
* **Document classifiers:** define classes, upload training data, and train or import a model, then route each document page with the Document Classification node. See [Document classifiers](/6.x/docs/platform-deep-dive/integrations/document-classifiers).
* **Reusable functions:** Script and Condition (Fork) nodes in the Integration Designer can call reusable functions. See [Reusable functions](/6.x/docs/building-blocks/reusable-resources/reusable-functions).
* **Integration Designer:** the Subworkflow node can map input per start node and output per end node instead of raw JSON. See [Subworkflow node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#subworkflow-node).
* **Data model:** attributes support validators such as Required, Min/Max Value, Min/Max Length, Pattern, and Email Format, wherever the data model is used. See [Attribute validations](/6.x/docs/building-blocks/project-data-model#attribute-validations).
* **Templates:** document and notification templates use the structured data model, with typed attributes and an **Input Parameters** tab. See [Managing notification templates](/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates).
* **Chat component:** the chat button shows an unread-message badge, the panel searches conversation history, and the input can be disabled by a condition. See [Chat](/6.x/docs/building-blocks/ui-designer/ui-component-types/chat).
* **UI Flows:** a **Navigate To** action can require selected forms to pass validation before it navigates. See [Navigate To action](/6.x/docs/building-blocks/ui-flows#navigate-to-action).
* **UI Flows:** with **Allow multiple editors** off, a running session is restricted to its owner. New flows default to single-owner; existing and imported flows keep the shared behavior. See [Session owner](/6.x/docs/building-blocks/ui-flows#session-owner).
* **Process Renderer:** a process-end trigger runs a configured action when the embedded process ends. See [Process end handling](/6.x/docs/building-blocks/ui-flows#process-end-handling).

#### Changed

* **Chat-driven workflows:** a conversational workflow must send at least one chat reply, or the run fails with an error. See [Chat-driven workflows](/6.x/ai-platform/chat-driven-workflows).
* **Custom Agent:** the **Instructions** field is limited to 10,000 characters. See [Custom Agent node](/6.x/docs/platform-deep-dive/integrations/custom-agent-node).
* **Response caching:** POST REST endpoints, file-storage LIST and DOWNLOAD, and Mongo FIND, FIND\_ONE, and AGGREGATE operations are cacheable. Mutating operations are never cached. See [REST endpoint caching](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching).
* **Email triggers:** Email Trigger and Microsoft Outlook data sources filter attachments by file extension. Existing category selections are migrated automatically. See [Attachment handling](/6.x/docs/platform-deep-dive/integrations/email-trigger#attachment-handling).
* **Audit:** UI Flow runtime sessions are audited in more detail, including workflow runs, chat messages, and conversation reads. See [Audit](/6.x/docs/platform-deep-dive/core-extensions/audit).
* **Export and import:** exporting to an older platform version removes UI-template features the target cannot read. See [Cross-version export and import](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
* **UI Flows:** an expired session shows a session-expired screen with a start-fresh option.
* **Renderers:** enumeration lookups are batched into a single request.

[5.11.0 release notes](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026) · [5.11.0 deployment guidelines](/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11)

**5.10.0**

July 2026

#### New

* **PostgreSQL data source:** connect a workflow to a PostgreSQL database and run SQL query operations from workflow nodes. See [PostgreSQL database](/6.x/docs/platform-deep-dive/integrations/postgresql-database).
* **SOAP data source:** import a WSDL from a URL or file, and call each operation from workflows with a SOAP Operation node. See [SOAP System](/6.x/docs/platform-deep-dive/integrations/soap-system).
* **FlowX Database:** MongoDB aggregation pipelines group, join, and reshape documents beyond a single query. See [Aggregation pipelines](/6.x/docs/platform-deep-dive/integrations/flowx-database#aggregation-pipelines).
* **Integration Designer:** the Tabular Data Extraction node reads a spreadsheet or CSV file into structured JSON, one object per row. See [Tabular Data Extraction node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node).
* **Integration Designer:** the Template Filling node generates a PDF or DOCX document from a document template filled with workflow data. See [Template Filling node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node).
* **Integration Designer:** the Combine Files node merges PDFs in a given order, and the Split File node splits a PDF by page ranges or per page. See [Combine Files node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node).
* **Documents plugin:** template-based generation can produce DOCX as well as PDF, set with `outputFormat`. See [Generating DOCX output](/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output).
* **Knowledge Base:** a failed ingestion shows its status and reason, and **Retry** re-runs the last operation after cleaning up partial content. The Update Knowledge Base node gains a FAIL exit with per-operation rollback. See [Error handling and retry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#error-handling-and-retry).
* **File Download component:** end users download files directly from a rendered app. See [File download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download).
* **Global header and footer:** a UI Flow can define a header and footer shown on every page. See [Global header and footer](/6.x/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer).
* **Event handlers:** event handlers can fire on a condition. The **Save Local Variable** action saves the clicked collection row into local data under a key. See [Conditional triggers](/6.x/docs/building-blocks/ui-designer/event-handlers#conditional-triggers) and [Save Local Variable](/6.x/docs/building-blocks/ui-designer/event-handlers#save-local-variable).
* **Image component:** the Image component honors a color property. See [Image](/6.x/docs/building-blocks/ui-designer/ui-component-types/image).
* **Data source testing:** the database query testing modals have a **Documents** tab, and multi-record operations report an affected-record count. See [Testing data sources](/6.x/docs/platform-deep-dive/integrations/testing-data-sources).
* **Mistral provider:** add Mistral with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability. See [AI providers](/6.x/ai-platform/ai-providers).

#### Changed

* **Documents:** the **Document Type** field is renamed **Document Tag**. Behavior is unchanged.

[5.10.0 release notes](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026) · [5.10.0 deployment guidelines](/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10)


# Deployment guidelines v6.0.0
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0

Component versions, Kafka topics, environment variables, and Helm chart changes for FlowX.AI 6.0.0, with the steps a self-hosted upgrade needs.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 6.0 is a feature release. On SaaS, FlowX applies every change on this page. Self-hosted deployments usually follow LTS releases and receive these changes with the next LTS release family. If you upgrade a self-hosted installation to 6.0.0, apply the changes below in the order given in [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

### Before you upgrade a self-hosted installation

* Set every AI service group flag explicitly. See [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart).
* Deploy designer-user, the new `core` service. harness and ui-driver (`devtime`) and dynamic-classifier (`runtime`) deploy only if you turn their group on. See [New services](#new-services).
* Create the new database users and secrets for the services you deploy. Every installation needs the four new keys in `keycloak-flowx-realm-clients`. See [New databases and secrets](#new-databases-and-secrets).
* Give process-engine read access to the integration-designer bucket. See [New databases and secrets](#new-databases-and-secrets).
* If you turn on dynamic-classifier, set its bucket name and provide its 20Gi volume. See [Update your values](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart#update-your-values).
* If you route with Kubernetes Ingress, move callers off the admin Ingress routes that the chart no longer creates. See [New databases and secrets](#new-databases-and-secrets).
* Create the new Kafka topics. If your cluster uses ACLs, also give the new clients of three existing topics access. See [New Kafka topics](#new-kafka-topics).
* Let audit-core reach Redis. It now uses Redis only to choose which replica runs its nightly cleanup job, not as a cache, and the chart connects it to the same Redis server as the other services. If you restrict which services can reach Redis, add audit-core. See [Configuring Redis](/6.x/setup-guides/audit-setup-guide#configuring-redis).
* Set the personal-data encryption master key on integration-designer. See [Personal-data encryption master key](#new-required-secret-personal-data-encryption-master-key).
* Choose how Elasticsearch replicates new indices. See [Elasticsearch replica auto-expansion](#changed-default-elasticsearch-replica-auto-expansion).
* Add the MongoDB hosts on your private network that data sources use to `FLOWX_SSRFALLOWEDHOSTS`. See [nosql-db-runner host restrictions](#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).
* Trust the certificates of the IMAP servers your email triggers read from. See [IMAPS certificate verification](#changed-default-imaps-certificate-verification-in-email-gateway).

Upgrading from 5.9.5 or earlier? Two changes from 5.9.6 also apply. See [Upgrading from an older patch release](#upgrading-from-an-older-patch-release).

## Component versions

The versions below are the component versions that make up FlowX.AI 6.0.0, next to FlowX.AI 5.9.6, the latest 5.9.x release a self-hosted installation upgrades from. A dash marks a component that is new since 5.9.6. On SaaS, FlowX manages these versions.

### Core components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **admin** | 11.132.0 | 10.152.14 |
| **advancing-controller** | 11.86.0 | 10.98.12 |
| **application-manager** | 11.143.0 | 10.159.3 |
| **audit-core** | 11.92.0 | 10.102.11 |
| **authorization-system** | 11.102.0 | 10.122.13 |
| **cms-core** | 11.114.0 | 10.113.13 |
| **data-search** | 11.87.0 | 10.92.11 |
| **data-sync** | 11.94.0 | 10.107.13 |
| **designer** | 11.252.0 | 10.285.4 |
| **designer-user** | 11.31.0 | - |
| **document-plugin** | 11.122.0 | 10.124.13 |
| **email-gateway** | 11.110.0 | 10.102.1 |
| **events-gateway** | 11.93.0 | 10.101.1 |
| **file-gateway** | 11.105.0 | 10.33.14 |
| **integration-designer** | 11.158.0 | 10.201.2 |
| **license** | 11.94.0 | 10.87.12 |
| **nosql-db-runner** | 11.98.0 | 10.101.13 |
| **notification-plugin** | 11.113.0 | 10.111.1 |
| **organization-manager** | 11.101.0 | 10.98.12 |
| **process-engine** | 11.137.1 | 10.174.17 |
| **runtime-manager** | 11.143.0 | 10.159.3 |
| **scheduler-core** | 11.89.0 | 10.94.11 |
| **task-management-plugin** | 11.109.0 | 10.112.12 |
| **webhook-gateway** | 11.102.0 | 10.69.12 |

### AI base components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-gateway** | 11.118.1 | 10.35.13 |
| **embedder** | 11.7.0 | 10.11.2 |
| **knowledgebase-indexer-v2** | 11.7.0 | 10.11.2 |
| **knowledgebase-rag** | 11.7.0 | 10.11.2 |
| **doc-parser** | 11.7.0 | 10.11.2 |

### AI dev-time components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-analyst** | 11.7.0 | 10.11.2 |
| **ai-architect** | 11.7.0 | 10.11.2 |
| **ai-assistant** | 11.7.0 | 10.11.2 |
| **ai-designer** | 11.7.0 | 10.11.2 |
| **ai-developer** | 11.7.0 | 10.11.2 |
| **harness** | 11.7.0 | - |
| **kb-enrichment** | 11.7.0 | 10.11.2 |
| **planner** | 11.7.0 | 10.11.2 |
| **ui-driver** | 11.252.0 | - |

### AI runtime components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **agent-builder** | 11.7.0 | 10.11.2 |
| **cee-pii** | 11.7.0 | - |
| **data-privacy** | 11.7.0 | 10.11.2 |
| **doc-converter** | 11.7.0 | 10.11.2 |
| **dynamic-classifier** | 11.7.0 | - |
| **evals-judge** | 11.7.0 | 10.11.2 |
| **speech-to-text** | 11.7.0 | 10.11.2 |
| **web-crawler** | 11.7.0 | 10.11.2 |

### AI extensions

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **modpod** | 11.0.1 | 10.0.7 |
| **observatory-api** | 11.29.4 | 10.7.2 |
| **observatory-platform** | 11.29.4 | 10.7.2 |
| **observatory-web** | 11.29.4 | 10.7.2 |

In FlowX.AI 6.0, the Observatory components run on environments operated by FlowX. They aren't included in client deployments in this release.

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart and deployed with the AI base group (see [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart)). Its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/6.x/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.252.0` for FlowX.AI 6.0.0). The native iOS and Android renderers version independently.

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **@flowx/angular-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/angular-theme** | 11.252.0 | 10.285.4 |
| **@flowx/angular-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/core-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/core-theme** | 11.252.0 | 10.285.4 |
| **solution-portal** | 11.252.0 | 10.285.4 |
| **iOS renderer** | 11.6.0 | 10.9.2 |
| **Android renderer** | 11.18.0 | 10.10.2 |

The **solution-portal** container app tracks the designer version.

***

## Configuration changes

This section compares environment variables, Kafka topics, and the `flowx-ai` Helm chart with FlowX.AI 5.9.6. It includes the changes that reached SaaS in 5.10 to 5.13, so a self-hosted upgrade from 5.9.6 needs only this page.

### New Kafka topics

Compared with 5.9.6, create these 42 topics. Create all of them, whatever your group flags: topics for services you don't deploy stay unused. On SaaS they are created and managed automatically.

**AI nodes as durable jobs:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.agent-node.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.progress.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.cancel.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Deep research node:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Validation findings:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.application-version.validation-findings.request-admin.v1` | application-manager → admin |
| `ai.flowx.application-version.validation-findings.request-cms.v1` | application-manager → cms-core |
| `ai.flowx.application-version.validation-findings.request-document-plugin.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.validation-findings.request-integration.v1` | application-manager → integration-designer |
| `ai.flowx.application-version.validation-findings.request-notification-plugin.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.validation-findings.request-application-manager.v1` | application-manager → application-manager |
| `ai.flowx.application-version.validation-findings.response.v1` | admin, cms-core, document-plugin, integration-designer, notification-plugin → application-manager |
| `ai.flowx.application-version.validation-findings.job-completed.v1` | application-manager → harness |

**Structured template data model:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |

**Runtime content import and export:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → embedder |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | embedder → integration-designer |

**Document classification and extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → none (dead-letter topic) |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | doc-parser → integration-designer |

**Event-triggered workflows:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Workflow schedules:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.workflow-schedules.updates.in.v1` | integration-designer → runtime-manager |
| `ai.flowx.core.notify.timer-event-schedule.state.v1` | scheduler-core → runtime-manager |

**Bulk instance migration and move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

**Designer notifications and preferences:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |
| `ai.flowx.eventsgateway.user.notifications.v1` | designer-user → events-gateway |
| `ai.flowx.designer-user.user-preferences.v1` | designer-user → designer-user |

> [!NOTE]
>
> If your Kafka cluster uses ACLs, also give the new clients of these existing topics access:
>
> * `ai.flowx.application-version.sync.out.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.correction-after-app-operation.response.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1`: document-plugin

### New services

Compared with 5.9.6, the `flowx-ai` Helm chart adds four services. On SaaS they are provisioned and managed by FlowX.

| Service | Group | What it does | Dependencies |
| - | - | - | - |
| designer-user | `core` | Stores Designer user preferences, such as the last-used workspace, and delivers Designer notifications | MongoDB, Redis, Kafka |
| harness | `devtime` | Runs the Developer Agentic Harness | PostgreSQL, Redis, Kafka |
| ui-driver | `devtime` | Renders UI flows in the background for the Developer Agentic Harness | None |
| dynamic-classifier | `runtime` | Classifies documents with trained models | PostgreSQL, a persistent volume, Kafka |

The databases, secrets, and volume are in [New databases and secrets](#new-databases-and-secrets).

The harness reuses the platform's existing Redis, so nothing new is provisioned. It uses Redis to stream a running turn to every open Designer session and to cancel a turn from any harness pod. Without Redis, turns still run, but live progress and cancellation across pods don't work.

The harness also consumes the existing `ai.flowx.llm.config.changed.v1` topic, so a change to an organization's AI model settings reaches it right away. Without Kafka, it picks up the change when its cache expires.

### AI service groups in the Helm chart

The `flowx-ai` Helm chart groups the services into four groups. Each group has its own flag, `groups.<group>.enabled`:

| Group | Services |
| - | - |
| `core` | Core platform services |
| `base` | The AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and the bundled Qdrant |
| `devtime` | ai-analyst, ai-architect, ai-assistant, ai-designer, ai-developer, harness, kb-enrichment, planner, ui-driver |
| `runtime` | agent-builder, data-privacy, doc-converter, dynamic-classifier, evals-judge, speech-to-text, web-crawler. cee-pii is in this group but needs `services.cee-pii.enabled: true` as well |

The groups are the same as in 5.9.6. The 6.0.0 chart adds designer-user to `core`, harness and ui-driver to `devtime`, and cee-pii and dynamic-classifier to `runtime`. The `base` group is unchanged.

Set all four flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

> [!WARNING]
>
> **Set every group flag explicitly for self-hosted upgrades.** Don't rely on the chart's group defaults. The `devtime` and `runtime` services call the AI base services, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

### New databases and secrets

Compared with the `flowx-ai` Helm chart in 5.9.6, these services need new databases. Create a database only if its service's group is on. designer-user is in `core`, so every installation needs its database:

| Service | Group | Database user | Secret |
| - | - | - | - |
| agent-builder | `runtime` | PostgreSQL `agent_builder` | `flowx-postgres-agent-builder` |
| dynamic-classifier | `runtime` | PostgreSQL `dynamic_classifier` | `flowx-postgres-dynamic-classifier` |
| harness | `devtime` | PostgreSQL `harness` | `flowx-postgres-harness` |
| designer-user | `core` | MongoDB `designer-user` | `mongodb-designer-user-designer-user` |

Each database has the same name as its user. Each secret holds the user's password under the key `password`.

The webhook-gateway also connects to the existing `app-runtime` MongoDB database with the `app-runtime` user.

The `keycloak-flowx-realm-clients` secret needs four new keys, one for each new service account:

| Secret key | Keycloak client |
| - | - |
| `KEYCLOAK_DESIGNER_USER_CLIENT_SECRET` | `flowx-designer-user-sa` |
| `KEYCLOAK_AI_HARNESS_CLIENT_SECRET` | `flowx-ai-harness-sa` |
| `KEYCLOAK_NOTIFICATION_PLUGIN_CLIENT_SECRET` | `flowx-notification-plugin-sa` |
| `KEYCLOAK_DOCUMENT_PLUGIN_CLIENT_SECRET` | `flowx-document-plugin-sa` |

Other chart changes:

* **process-engine** needs read-only access (`s3:GetObject`) to the integration-designer bucket, to download the Kafka payloads that integration-designer stores there. The chart reads the access key ID from `global.flowx.s3.credentials.processEngine.accessKey` (default `flowx-process-engine-accesskey`) and the secret access key from the `flowx-process-engine-s3` secret, key `SecretAccessKey`.
* **dynamic-classifier** stores its data on a 20Gi `ReadWriteOnce` persistent volume claim, `dynamic-classifier-data`, and uses the `Recreate` deployment strategy, so an upgrade stops the old pod before the new one starts.
* **dynamic-classifier** reads an OpenAI API key for its LLM judge from the `dynamic-classifier-openai` secret, key `OPENAI_API_KEY`. The secret is optional: without it, the pod still starts and classification keeps working.
* The chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier. ai-gateway keeps its own.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map | none (required) |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today | `k1` |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index | `PT24H` |

### New object storage bucket: runtime content

Runtime content export and import stores its files in a new shared bucket, `runtime-content-bucket`. Application Manager creates the bucket on first use, Integration Designer writes export files and reads imports there, and the embedder reads and writes Knowledge Base vectors at the paths each request names. Grant all three services access to the bucket.

Browsers upload import files and download export files directly, through presigned URLs that Application Manager signs. By default it signs them with the internal storage endpoint, which only pods can reach, so set `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` to a storage endpoint that browsers can reach.

New variables on application-manager and integration-designer. Set the bucket on both, and the presign settings on application-manager only:

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_RUNTIMECONTENTBUCKET` | Bucket for runtime content export and import files | `runtime-content-bucket` |
| `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` | Storage endpoint used to sign the presigned upload and download URLs. Leave empty to sign with the internal storage endpoint | empty |
| `APPLICATION_FILESTORAGE_S3_PRESIGNREGION` | Region used to sign the presigned URLs | `us-east-1` |

For the full list of buckets, see [Data architecture](/6.x/docs/platform-overview/data-architecture#s3-compatible-object-storage-buckets).

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

New process-engine and audit-core variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

### Changed behavior: nosql-db-runner host restrictions cover MongoDB

The host restriction that relational data sources already had now applies to external MongoDB connections too. The nosql-db-runner checks every address a MongoDB host resolves to, including replica-set members and SRV targets, and rejects the connection if any of them is private. For FlowX Database and Unmanaged MongoDB data sources alike, it also rejects `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter. To match every document, pass `{"_id": {"$exists": true}}`.

nosql-db-runner variables (both already existed for relational data sources):

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SSRFALLOWEDHOSTS` | Hosts or CIDR blocks, separated by commas, that may connect even though they resolve to a private address. Addresses on the local machine or in a link-local range stay blocked | empty |
| `FLOWX_SSRFPROTECTIONENABLED` | Turns the host restriction on or off | `true` |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS`.

### Changed behavior: name placeholders in data-privacy

When data-privacy masks a person's name, the placeholder now carries the gender, for example `<NAME_F_1>` or `<NAME_M_1>`. When the name doesn't show the gender, the placeholder stays `<NAME_1>`. Prompts or scripts that match the old placeholder form need updating.

### Changed behavior: Workspace operations editor role replaced

The upgrade replaces the Workspace operations editor role with the [Workspace corrective actions editor](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix) role. Users and groups that had the old role get the new one automatically and keep access to process instance migration and move token. No action is needed.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

New audit-core variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/6.x/setup-guides/audit-setup-guide#configuring-elasticsearch).

### Changed default: IMAPS certificate verification in email-gateway

The email-gateway now verifies the certificate of every IMAPS server it connects to. A server must present a certificate signed by a trusted authority and matching its host name.

New email-gateway variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS` | Mail hosts that skip certificate verification, separated by spaces or commas. Use `*` to skip it for every host | empty |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Email triggers that read from an IMAP server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`.

### Changed default: AI node retry

AI nodes without retry settings of their own now retry when a dependency is temporarily unavailable, such as an LLM provider outage, a rate limit, or a lost connection. Permanent errors aren't retried, and deep research nodes never retry by default. A node's own retry settings replace the default.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_ENABLED` | Turns the default retry for AI nodes on or off | `true` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_MAXATTEMPTS` | Maximum retry attempts | `10` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_BACKOFFPERIOD` | Wait between attempts, as an ISO-8601 duration | `PT30S` |

### Upgrading from an older patch release

Upgrading from 5.9.5 or earlier? Apply the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries) as well. Two 5.9.6 changes affect the upgrade:

* **Build redeployment retries:** the queue of build deployments waiting for a retry moved from Redis to the application-manager PostgreSQL database, with a new topic, `ai.flowx.build.deployment-failed.v1`. Deployments waiting for a retry in Redis when you upgrade aren't moved to the new queue. Re-publish those builds after the upgrade.
* **advancing-controller management port:** `MANAGEMENT_SECURITY_ENABLED` is no longer read. Actuator endpoints on the management port, including Prometheus, answer without authentication.

> [!WARNING]
>
> Keep the advancing-controller management port, `8081`, off any public ingress.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](/release-notes/overview).


# FlowX.AI 6.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026

What's new in FlowX.AI 6.0: the Developer Agentic Harness builds story by story, plus bulk process-instance migration, scheduled workflows, and certificates.

[FlowX.AI 6.0.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/hero-6.0.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 6.0 is a feature release, live on FlowX.AI SaaS. Self-hosted installations usually wait for the next LTS release family, and can also upgrade to 6.0.0 now: see [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

> [!WARNING]
>
> **Check your existing apps:** 6.0.0 changes how AI node prompts and retries, substitution tags, FlowX Database writes, masked names, IMAPS email triggers, evaluations, 5.1.x exports, and GraalVM scripts behave. See the [upgrade actions](/release-notes/v6.x/5.9-to-6.0-changelog) for what to check in each. Coming from 5.9.x? On the same page, also check the **Changed** entries for 5.10 to 5.13.

> [accordion] What changed since 5.13.0
>
> | 5.13.0 | 6.0.0 |
> | - | - |
> | The harness built the whole approved plan in one run | **Story-by-story delivery**: build one slice of the app, test it, then continue |
> | Changes to the app were described in words | **Comment mode**: select a component in the running app and say what should change |
> | The Command Center and the AI buttons in each editor opened standalone AI agents | **One agent rail**: **⌘K** or the header toggle opens the harness, which uses those agents internally |
> | A workflow started only when a process or caller started it | **Scheduled workflows**: date or cycle schedules on the Start node |
> | TLS was configured with keystores, truststores, and a skip switch | **Trust and Identity**: choose what the host is checked against, and whether to present a client certificate |
> | The Issues Console checked resources only | **Version checks**: entry points, theme, and library dependencies |
> | Only version exports sent notifications | **Import and export notifications**: version imports, build exports, and build imports notify you too |
> | A substitution tag had to be a property's whole value | **Tags inside any text**: `${tag:key}` next to static text and process data |
> | An AI node failed as soon as its AI service or provider couldn't be reached | **AI node retries**: on by default, up to 10 times, 30 seconds apart |
> | The chat message was appended to the end of an AI node's prompt | **Chat message in prompts**: reference `${userMessage}` in **Context** where the agent should answer it |
> | Evaluations grouped test cases into datasets and checked outputs with Code evaluators | **Test cases and asserts**: tagged test cases per workflow, checked with asserts and LLM evaluators |
> | The embedding model was locked once a Knowledge Base held content | **Re-embedding**: change **Containing Personal Information** later and the content is re-embedded |
> | Exporting rows to a file needed a Script node | **Generate Tabular File node**: a CSV or XLSX file from an array of rows |
> | A FlowX Database index couldn't reject duplicate values | **Unique indexes**: **Enforce unique values** on one attribute or a compound key |
> | A sensitive configuration value was shown in the Designer after saving | **Sensitive values stay hidden**: the Designer shows `********` in its place |
> | GraalVM was a supported script engine | **GraalVM deprecated**: 6.1.x is the last release family that supports it |

### **Coming from 5.9.x**

Releases 5.10 to 5.13 shipped to SaaS first. An installation that moves from 5.9.x to 6.0.0 gets their features too, including the [corrective actions](#corrective-actions-on-running-instances) below. The highlights:

> [card] New data sources
>
> [PostgreSQL](/6.x/docs/platform-deep-dive/integrations/postgresql-database) and [Db2](/6.x/docs/platform-deep-dive/integrations/db2-database) databases, and [SOAP services](/6.x/docs/platform-deep-dive/integrations/soap-system) imported from a WSDL.

> [card] Document nodes in workflows
>
> [Fill a template](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) into a PDF or DOCX, [combine](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) or [split](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) PDFs, and [parse](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support) spreadsheets, CSV, XML, and JSON.

> [card] Multi-instance and triggered workflows
>
> Run [one subworkflow per array element](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) in parallel, and start a workflow from an [email or webhook trigger](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).

> [card] Workflow Instances page
>
> [Every workflow run in the project](/6.x/docs/projects/runtime/workflow-instances), filterable by status, date, and origin.

> [card] Branches and the Issues panel
>
> [Merge into any branch](/6.x/docs/projects/managing-applications/versioning#managing-branches), archive or delete branches, and [see validation findings](/6.x/docs/projects/managing-applications/checking-for-issues) in one panel.

> [card] Workflows as agent tools
>
> A Custom Agent node [calls FlowX workflows as tools](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run), each with a hint for when to use it.

Full list: the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog), and the [5.10](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026), [5.11](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026), [5.12](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026), and [5.13](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) release notes.

***

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > The Developer Agentic Harness is the Designer's AI agent: it surveys your app, plans the change, and builds it on its own branch.
> >
> > **Before 6.0:** the harness ran an approved plan as a single run, and a conversation stayed tied to the app and branch where you started it. **Now:** a plan can split the work into stories, each a slice of the app you can try on its own, delivered one story at a time. You can point at a component in the running app to ask for a change. Your conversations follow you across the Designer.
> >
> > Each story says how to test it and what the agent needs from you, so you check one working slice before the next one starts. Comment mode turns the running UI flow or process into the brief: select a component, say what should change, and the comment lands in the conversation with the component attached. A conversation writes to the project and branch set by the first change you confirm, wherever you navigate after that, and the agent asks before it reads beyond that target.
> >
> > > [!NOTE]
> > >
> > > **Removed:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors, such as **Generate** on the data model and the sparkle buttons in business rules, reusable functions, and Script nodes. Open the agent rail instead: press **⌘K** (**Ctrl+K** on Windows and Linux) or select the sparkle toggle in the header. The harness still uses those agents internally for focused generation work. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness#what-the-agent-can-see-and-change).
> >
> > <video>
> >   <track label="English" />
> > </video>
> >
> > See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
>
> > [tab] Key Features
> >
> > > [card] [Story-by-story delivery](/6.x/ai-platform/developer-agentic-harness#how-does-a-plan-with-stories-run)
> > >
> > > Implement the next story, test it with the steps the story gives, then continue with one story or all that remain.
> >
> > > [card] [Comment on the running app](/6.x/ai-platform/developer-agentic-harness#how-do-i-comment-on-the-running-app)
> > >
> > > Select **Comment** in the header, pick a component in the running UI flow or process, and say what should change.
> >
> > > [card] [Conversations that follow you](/6.x/ai-platform/developer-agentic-harness#sessions)
> > >
> > > Every conversation you have in the organization, searchable. Each keeps writing to the project and branch of its first confirmed change, wherever you navigate.
> >
> > > [card] [Asks before reading more](/6.x/ai-platform/developer-agentic-harness#what-happens-when-the-agent-asks-to-read-another-project)
> > >
> > > Read-only access to another project needs **Allow for this conversation**, and you can revoke it from the rail.
> >
> > > [card] [Attach your material](/6.x/ai-platform/developer-agentic-harness#attach-files-to-a-conversation)
> > >
> > > Give the agent PDF and DOCX briefs, screenshots, or BPMN diagrams to plan and build from.
> >
> > > [card] [Delete with a plan export](/6.x/ai-platform/developer-agentic-harness#delete-a-conversation)
> > >
> > > Deleting a conversation keeps its commits on the branch and offers **Export plan** for what wasn't run.
> >
> > > [card] [Entry points, handovers, and repairs](/6.x/ai-platform/developer-agentic-harness#entry-points-handovers-timeouts-and-repairs)
> > >
> > > The agent suggests an entry point and asks again before serving, adds handover buttons, times out workflow waits, and proposes a repair when a step fails, a limited number of times per step.
>
> SaaS

### **Corrective actions on running instances**

> [card] Corrective actions on running instances
>
> > [tab] Overview
> >
> > Corrective actions shipped in the 5.12 and 5.13 feature releases. They fix running process instances in place, without restarting them, from **Runtime** → **Runtime Control** → **Corrective Actions**.
> >
> > **Bulk process-instance migration** moves a filtered set of running instances from one build to another in one run, so a fix made in a newer build reaches instances already in flight. **Move token** takes the active token off the node the instances are stuck on and places it on another node of the same process, and the instances stay on their build.
> >
> > The **Workspace corrective actions editor** role grants both. It replaces the Workspace operations editor role, and the upgrade moves users and groups that had the old role to the new one.
> >
> > See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances) and [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
>
> > [tab] Key Features
> >
> > > [card] [Build to build, in bulk](/6.x/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > Pick the source build, the target build, and the instances to move, then review the eligible count and map any node missing from the target build before you start.
> >
> > > [card] [Move token](/6.x/docs/projects/runtime/active-process/move-token)
> > >
> > > Resume stuck instances from another node of the same process, on one or many instances at once.
> >
> > > [card] [Dedicated role](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix)
> > >
> > > Grant corrective actions without handing out workspace admin rights.
> >
> > > [card] [Notified when done](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification)
> > >
> > > The notification center reports when a bulk migration finishes.
>
> SaaS

### **New Designer header**

> [card] New Designer header
>
> **Before 6.0:** the branch selector, the version state, and **Commit Changes** sat in the project's top bar. **Now:** the header holds the project name, the **Config** / **Runtime** switch (**Config** to edit a version, **Runtime** for builds and their settings), the **Build with AI** and **Comment** toggles, and **Run project**, which starts the version's entry point. Branching, the current version, and **Commit Changes** move to a version block at the start of the footer on Config pages.
>
> ![Designer project on a Config page: the header shows the project name, the Config and Runtime switch, the Build with AI toggle, and Run project; the footer starts with the version block showing the main branch, the version name, and Start New Version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/designer-header-6-0.png)
>
> The Designer also opens the workspace you used last, and **Organization settings** is in the avatar menu. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
>
> SaaS

### **AI node retries**

> [card] AI node retries
>
> **Before 6.0:** an AI node failed as soon as its AI service or LLM provider couldn't be reached. **Now:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when the service is unreachable, the provider is unavailable or rate-limits the request, or the connection fails. Timeouts aren't retried by default, because the node may already have called its tools.
>
> Toggle **Allow Retry** on in the node's **Settings** to set your own count, interval, and exponential backoff. After the last retry, the workflow continues down the node's failure exit if one is connected. With **Allow Retry** on, the workflow run logs show each attempt on its own line.  See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
>
> SaaS

### **Knowledge Base re-embedding and entry lifecycle**

> [card] Knowledge Base re-embedding and entry lifecycle
>
> **Before 6.0:** the embedding model was locked once a Knowledge Base held content. **Now:** turning **Containing Personal Information** on or off later re-embeds the existing content with the new model. Search keeps using the current embedding while it runs, and content changes are locked until it finishes. If some documents fail, the Knowledge Base stays on its previous model and the header says how many weren't re-embedded.
>
> Entries also have their own lifecycle: **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested) and [disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
>
> SaaS

### **Chat message in AI node prompts**

> [card] Chat message in AI node prompts
>
> > [!WARNING]
> >
> > **Behavior change.** The chat message is no longer appended to the end of an AI node's prompt automatically. In chat-driven workflows, reference `${userMessage}` in the node's **Context** wherever the agent should answer the user's message.
>
> The message still reaches the model inside the input data when **Use only referenced values as input** is off. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
>
> SaaS

### **Evaluations: test cases replace datasets**

> [card] Evaluations: test cases replace datasets
>
> **Before 6.0:** test cases lived in datasets, and the Code evaluators checked outputs for an exact, JSON, or Levenshtein match. **Now:** each workflow has its own test cases, grouped by tags. Each case carries its checks: asserts for **equals** and **equals as JSON**, and LLM evaluators with a pass threshold. An experiment runs the test cases you select. See [Evaluations](/6.x/ai-platform/evaluations).
>
> > [!WARNING]
> >
> > **Behavior change.** The upgrade converts each dataset's test cases and keeps the dataset name as a tag, but adds no checks. An experiment skips a case with no enabled check, so add an assert or evaluator to each converted case before you run it. The Code evaluators are removed: use the **equals** assert in place of **Exact match**, and **equals as JSON** in place of **JSON match**. **Levenshtein** has no replacement. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
>
> SaaS

### **Scheduled workflows**

> [card] Scheduled workflows
>
> > [tab] Overview
> >
> > **Before 6.0:** an integration workflow started only when a process, a UI flow, or another caller started it. **Now:** add schedules to the workflow's **Start** node and it starts by itself at each fire time.
> >
> > Schedules fire once on a date or repeatedly on an ISO or cron cycle, and the dialog previews the next fire times in your local time zone. Saving a schedule or publishing a build never turns it on: activate it in **Runtime** → **Runtime Settings** → **Schedules**.
> >
> > See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
>
> > [tab] Key Features
> >
> > > [card] Date or cycle
> > >
> > > Fire once at a date and time, or repeatedly with an ISO or cron expression built from guided fields.
> >
> > > [card] Up to 50 per workflow
> > >
> > > Each schedule has a name that is unique on its workflow. Schedules are available on Output Focused workflows, which process structured input and output.
> >
> > > [card] Explicit activation
> > >
> > > A schedule fires only after you activate it on the **Schedules** page, for a workflow in the project's active build.
> >
> > > [card] Next fire times
> > >
> > > Check the previewed fire times before you save.
>
> SaaS

### **Certificates: trust and identity**

> [card] Certificates: trust and identity
>
> > [tab] Overview
> >
> > **Before 6.0:** a REST data source combined keystore, truststore, and a skip-verification switch in one TLS setup. **Now:** the **Certificates** panel has two independent parts. **Trust** decides what the host's certificate is checked against: **System CAs** (the default), a **Custom CA**, or **None (insecure)**. **Identity** is the client certificate FlowX presents for mutual TLS, turned on with **Present a certificate**.
> >
> > The same panel is available on File Storage data sources. Existing certificate settings are converted to the new model automatically.
> >
> > See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates) for when to use each option.
>
> > [tab] Key Features
> >
> > > [card] Trust per data source
> > >
> > > Changing trust on one data source leaves every other call verified as before.
> >
> > > [card] Mutual TLS when asked
> > >
> > > Present a client certificate only to hosts that require one.
> >
> > > [card] [File Storage too](/6.x/docs/platform-deep-dive/integrations/file-storage#certificates)
> > >
> > > S3-compatible storage uses the same Trust and Identity settings.
> >
> > > [card] Insecure, by name
> > >
> > > **None (insecure)** is labeled as such and accepted only on REST and File Storage data sources.
>
> SaaS

### **Generate Tabular File node**

> [card] Generate Tabular File node
>
> A new node under **Tools** in the workflow palette turns a workflow variable that holds an array of rows into a CSV or XLSX file, stored as a document linked to the workflow run. A workflow can now produce an export without a Script node. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
>
> SaaS

### **FlowX Database unique indexes**

> [card] FlowX Database unique indexes
>
> Toggle **Enforce unique values** when you add an index to reject documents that repeat a value already stored, on one attribute or on a compound key, with an option to exempt documents that leave the key empty. Existing duplicates are reported when you run **Apply Indexes**, before the index is created. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
>
> SaaS

### **Issues Console version checks**

> [card] Issues Console version checks
>
> **Before 6.0:** an Issues Console check, which validates the resources in a project version, covered processes, UI flows, and integration workflows. **Now:** it also checks the version itself: missing, broken, or mismatched entry points, a theme that isn't in the workspace, library builds that are missing directly or transitively, and dependencies the version doesn't use. Selecting a finding opens the version settings or the **Dependencies** page, where you fix it. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
>
> SaaS

### **Import and export notifications**

> [card] Import and export notifications
>
> The notification center now covers version imports and build exports and imports, alongside version exports and process instance migrations. Each operation notifies you when it starts and replaces that entry with its result: ready to download, imported, needs review with a conflict or excluded-resource count, failed, or timed out. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
>
> SaaS

### **Resource documentation**

> [card] Resource documentation
>
> Open **Documentation** from a resource's menu to give it a short description and longer Markdown documentation, written and previewed in the same window. Media Library assets in a project library get a description too, used as the image's alt text in the asset preview. Knowledge base stores, navigation areas, and user tasks in the process navigation panel have **Documentation** in their menus too. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
>
> SaaS

### **Sensitive values stay hidden**

> [card] Sensitive values stay hidden
>
> After you save a `value` configuration parameter with **Sensitive** on, the Designer shows `********` in place of the value in the parameters list, overrides, build details and lists, and the merge view. The real value is still used at runtime, and editing other fields keeps it. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
>
> SaaS

### **Substitution tags inside any text**

> [card] Substitution tags inside any text
>
> > [tab] Overview
> >
> > **Before 6.0:** a substitution tag resolved only when it was the whole value of a property, so `@@greeting ${firstName}` rendered as empty text. **Now:** write `${tag:key}` anywhere in a component's text, next to static text and process data, and the renderer fills in every tag: `${tag:greeting}, ${firstName}!` renders as "Hello, John!".
> >
> > The upgrade rewrites whole-value `@@key` references to `${tag:key}` in processes, UI flows, and reusable templates, so existing screens render as before. `@@key` keeps working as a whole value.
> >
> > See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).
>
> > [tab] Key Features
> >
> > > [card] Tags, text, and data together
> > >
> > > Use several tags and process data placeholders in one label, placeholder, message, validator message, or option label.
> >
> > > [card] Existing references converted
> > >
> > > Whole-value `@@key` references become `${tag:key}`. Option values and the default of choice components stay `@@key`.
> >
> > > [card] Task Manager columns
> > >
> > > A column value of exactly `${tag:key}` shows, filters, and sorts like `@@key`.
> >
> > > [card] Import from and export for 5.9
> > >
> > > Importing from 5.9 converts `@@key` forward. Exporting for 5.9 converts whole-value tags back to `@@key`.
>
> SaaS

### **GraalVM script engine deprecated**

> [card] GraalVM script engine deprecated
>
> The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports it, for every JavaScript and Python script: business rules, reusable functions, workflow Script nodes, and the rest. Scripts that run on GraalVM keep working in 6.0.0. Move them to the native engine, the default since 5.9.0, before support ends. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).
>
> **Time limits on GraalVM too:** scripts that run on GraalVM now stop at the same per-language time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default, set on the process engine and Integration Designer with `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` and `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`. Before 6.0.0, a GraalVM script had no time limit. A script that runs past its limit is stopped and fails with an error saying it did not finish within its time limit. Before you upgrade, check GraalVM scripts that can run longer than these limits, or raise the limits. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
>
> All Deployments

### **Smaller improvements**

> [card] Smaller improvements
>
> **Auto-arrange on both canvases:** select **Auto-arrange** on the workflow canvas, or **Arrange** on the process canvas, to see a tidied layout in the **Layout preview** bar before anything moves. Compare it with the current layout, then **Apply** or **Cancel**. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).&#x20;
>
> **Timers in local time:** timer nodes now use the same editor as workflow schedules. Dates and times you pick are in your local time and saved in UTC, one control switches between **Guided**, **Expression**, and **Process variable** entry, and cycle timers preview their next fires. Timers saved with the earlier date pickers can look shifted by your UTC offset in the panel, but they still fire at their stored time. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).&#x20;
>
> **Longer branch names:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).&#x20;
>
> **Organization branding:** a **Branding** page under **Organization settings** > **Customization** sets one brand for the organization: name, logos, legal and social links, container app colors and header, and the sender, signature, and text of the invite, verify email, and reset password emails, with a preview of each. Login page and email branding are available on FlowX SaaS only. See [Organization branding](/6.x/docs/saas/organization-branding).&#x20;
>
> **Typed dates in the Datepicker:** turn on **Allow manual input** to let users type a date in the pattern of the project's default locale instead of picking it. Web only, and not available while **Legacy component** is on.&#x20;
>
> **Data mapping creates data types:** type a new attribute path such as `client.address.street`, and saving the mapping creates the data types it names. Until then, the mapper marks them as not yet added to the data model. Required rows show an asterisk, and mapping an object onto a primitive field shows an error.&#x20;
>
> **Removed fields stay removed:** when a node's output sets a field to `null`, the field is removed from the workflow data and later steps no longer restore it with a `null` value. If a condition checks for `null`, make it handle a missing field too.&#x20;
>
> **Keys with dots stay whole:** a data key that contains a dot, such as `cash|31.12.2025`, now stays one key when a workflow saves its data. Before, the key was split into nested objects and later nodes could not read it.&#x20;
>
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, and Kafka topics, see [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0). To upgrade the Helm chart or a renderer SDK, follow [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).


# Deployment guidelines v4.7.10
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/deployment-guidelines-v4.7.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.3** | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.8** | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.6** | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.5** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.4** | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.6** | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.4** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.3** | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.6** | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.2** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.32** | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.24** | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.10 | Keycloak | 22, 26+ |
| 4.7.10 | Kafka | 3.2 - 3.9 |
| 4.7.10 | PostgreSQL | 16 - 17 |
| 4.7.10 | OracleDB | 19c, 21c, 23ai |
| 4.7.10 | MongoDB | 7 - 8 |
| 4.7.10 | Redis | 7.2 - 8.0 |
| 4.7.10 | Elasticsearch | 7 - 8 |
| 4.7.10 | Angular (Web SDK) | 19.x |
| 4.7.10 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.10 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Updated Spring Boot to the latest release for enhanced security and performance\
✅ Updated Java libraries to fix vulnerabilities across all images\
✅ Selectors support for substitution tags across all platforms (Web, iOS, Android)\
✅ System substitution tags on all task management texts\
✅ CMS - Added system substitution tags with migration script support

### Security and Platform Updates

This release includes critical security updates to ensure your FlowX.AI platform remains secure and up-to-date:

* **Spring Boot Update**: Updated to the latest release on the 4.7.x LTS branch
* **Java Libraries Update**: Updated Java libraries to fix vulnerabilities across all LTS 4.7.x images

### Selectors Support for Substitution Tags

You can now use selectors with substitution tags when the source type is process data across all platforms (Web, iOS, and Android). This enhancement provides more flexibility in displaying dynamic content from your process data in selector components.

**Available on:**

* Angular Web Renderer
* React Web Renderer
* iOS Renderer

### System Substitution Tags for Task Management

Task management now includes comprehensive system substitution tags support:

* **Backend CMS**: Added system substitution tags with a migration script to help you transition existing content
* **Web Renderers**: System substitution tags are now available on all task management texts across Angular and React renderers
* This allows for more dynamic and flexible task management configurations

## Bug fixes

> [accordion] \[Designer] Error when copying/pasting nodes with misconfiguration
>
> Fixed an issue where attempting to copy and paste nodes with misconfigurations, or importing an app version/build with misconfigured nodes, would result in an error. The system now handles misconfigured nodes gracefully during these operations.
>
> **Issue**: Error when trying to copy and paste nodes with misconfiguration or import an app version/build with nodes with misconfigurations

> [accordion] \[React] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the React renderer.
>
> **Issue**: \[React] Card not expandable after finishing subprocess started from it

> [accordion] \[Angular] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the Angular renderer.
>
> **Issue**: \[Angular] Card not expandable after finishing subprocess started from it

> [accordion] \[React] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the React renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[React] Card shouldn't collapse when next nav area is modal

> [accordion] \[Angular] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the Angular renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[Angular] Card shouldn't collapse when next nav area is modal

> [accordion] \[Backend] Task Manager - System substitution tags not displayed in column names
>
> Fixed an issue where system substitution tags were not being displayed in the `columns.displayName` property of the Task Manager backend.
>
> **Issue**: \[BE] Task manager | System substitutionTags are not displayed in columns.displayName

> [accordion] \[Web Renderers] Task Manager - Substitution tags value override
>
> Resolved an issue where system substitution tags values were incorrectly overriding custom substitution tags when the value was not null in both React and Angular renderers.
>
> **Issue**: \[React]\[Angular] Task manager | System subTags values override de custom subTags when value is not null

> [accordion] \[Task Manager] Missing localization for Russian and Uzbek in table view
>
> Fixed localization support in Task Manager table view for Russian and Uzbek languages, ensuring proper display of translated content.
>
> **Issue**: \[Task manager localisation] Table view - Missing localisation support for Russian and Uzbek

> [accordion] \[Task Manager] View search field placeholder not localized
>
> Resolved an issue where the view search field placeholder in Task Manager was not being localized for any language. The placeholder now properly supports all configured languages.
>
> **Issue**: \[Task manager localisation] View search field placeholder not localised for any language


# Deployment guidelines v4.7.11
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/deployment-guidelines-v4.7.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.6** | 8.24.3 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.12** | 7.18.8 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.9** | 5.11.6 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.8** | 6.8.5 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.7** | 6.10.4 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.9** | 7.9.6 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.7** | 6.8.4 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.6** | 2.16.3 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.9** | 2.10.6 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.103.6** | 5.101.2 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.32 | 4.0.32 | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.27** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.25** | 1.8.24 | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.11 | Keycloak | 22, 26+ |
| 4.7.11 | Kafka | 3.2 - 3.9 |
| 4.7.11 | PostgreSQL | 16 - 17 |
| 4.7.11 | OracleDB | 19c, 21c, 23ai |
| 4.7.11 | MongoDB | 7 - 8 |
| 4.7.11 | Redis | 7.2 - 8.0 |
| 4.7.11 | Elasticsearch | 7 - 8 |
| 4.7.11 | Angular (Web SDK) | 19.x |
| 4.7.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.11 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025

Security and maintenance updates for the 4.7.x LTS release

## What's new?

This is a **security and maintenance release** for the FlowX.AI 4.7.x LTS branch, focused on keeping your platform secure and up-to-date with the latest security patches.

✅ **Security Updates** - Updated core libraries and dependencies to address known vulnerabilities\
✅ **Platform Stability** - Improved overall platform security and stability

***

## Migration notes

> [!WARNING]
>
> As this is a **patch release** on the 4.7.x LTS branch, it is designed to be a **drop-in replacement** with no breaking changes.

***

## Component versions

All FlowX.AI components have been updated to version **4.7.11** with the security patches applied. Refer to the deployment guidelines for the complete list of component versions.


# Deployment guidelines v4.7.9
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/deployment-guidelines-v4.7.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.1** | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.4** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.1** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.1** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.1** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.2** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.30** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.26** | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.23** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.9 | Keycloak | 22, 26+ |
| 4.7.9 | Kafka | 3.2 - 3.9 |
| 4.7.9 | PostgreSQL | 16 - 17 |
| 4.7.9 | OracleDB | 19c, 21c, 23ai |
| 4.7.9 | MongoDB | 7 - 8 |
| 4.7.9 | Redis | 7.2 - 8.0 |
| 4.7.9 | Elasticsearch | 7 - 8 |
| 4.7.9 | Angular (Web SDK) | 19.x |
| 4.7.9 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.9 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes and security improvements\
✅ Support for dynamic keys in [**Link component**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/typography#link) URL property across all platforms\
✅ Added property on View for enabling or disabling row selection in tasks table

### Support for dynamic keys in Link component URL property

You can now use dynamic keys in the Link component's URL property across all platforms (Web, iOS, and Android). This enhancement allows you to dynamically construct URLs using process data, enabling more flexible navigation patterns in your applications.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)

### Task Manager rowSelection property on view

A new "Enable row selection" property has been added to Task Manager views, enabling you to control row selection behavior in task tables.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enable_row_select.png)

## Bug fixes

> [accordion] \[Designer] Merge fails if one branch contains past merges
>
> Fixed an issue where merging branches that contain multiple past merge commits would fail with an error. The merge conflict resolution now properly handles complex merge histories when adding values to enumerations or making other configuration changes.

> [accordion] \[CMS] Enumerations retrieve content endpoint should return content from dependencies
>
> Resolved an issue where the CMS enumerations Kafka endpoint only returned content from the local project and not from library dependencies. The endpoint now correctly retrieves enumeration content from both the current project and all dependency libraries.

> [accordion] \[Task Manager] Table doesn't use the current language
>
> Fixed localization issue in Task Manager where table content wasn't respecting the current language setting. Task Manager tables now properly use the selected language for all displayed content.

> [accordion] \[UI Designer]\[Angular]\[React] Modal fixed height is not applied
>
> Resolved an issue where setting a modal's height to "fixed" would not apply correctly in Angular and React renderers. Fixed height configuration now works as expected for modal components.

> [accordion] \[UI Designer]\[Angular] Fixed container should use overflow-y auto instead of scroll
>
> Fixed styling issue where fixed-height containers incorrectly used `overflow-y: scroll` instead of `overflow-y: auto`. Containers now only show scrollbars when content exceeds the container height.


# FlowX.AI 5.9.x LTS changelog
Source: https://docs.flowx.ai/release-notes/v5.x/5.9-lts-changelog

Every change in each FlowX.AI 5.9.x LTS maintenance release, grouped by type and component, with an RSS feed for upgrade planning.

This page lists every change in each 5.9.x LTS maintenance release, newest first. Use the RSS button at the top of the page to subscribe and get each new patch as it ships. Mobile renderers and the React Native SDK are covered in their own release notes. Moving to 6.0.0? See the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog).

**5.9.6**

October 2026

**Upgrade actions:** migrate to the `flowx-ai` Helm chart if you installed the `ai-platform` chart, create the `ai.flowx.build.deployment-failed.v1` Kafka topic and allow it in your ACLs, re-publish any build whose deployment failed shortly before the upgrade, review workflow node retry settings, grant the connection-test permissions to custom roles, and allow extra Integration Designer startup time on a large `workflow_instances` collection. Details are in the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).

#### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

#### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect.
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#mongodb-setting-names).
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6) for its version.

#### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.6 release notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026) · [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6)

**5.9.5**

September 2026

**Upgrade actions:** let the `ai-services` consumer group reach zero lag and allow the new AI consumer groups in Kafka ACLs, add private database hosts to the NoSQL DB runner allowlist, set every service-account client secret on `authorization-system`, rename `cache_error_total` in dashboards and alerts, re-expose `loggers` if you change log levels at runtime, and review the deployment guidelines if you had already turned on data partitioning, because the conversion to native partitions is one way. Details are in the [5.9.5 upgrade notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#upgrade-notes).

#### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#native-postgresql-partitioning).

#### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.

#### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.5 release notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026) · [5.9.5 deployment guidelines](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5)

**5.9.4**

August 2026

**Upgrade actions:** move the registry out of `image.repository` if you embedded it there (no action if you set `global.imageRegistry`), grant the Liquibase lock permissions to each service's database user on Oracle, create the `flowx-events-gateway-sa` client yourself if you manage Keycloak clients outside the Helm charts, and move host apps that embed the Angular SDK to Angular 21. Details are in the [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4#configuration-changes).

#### Changed

* **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.
* **Angular SDK:** the Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps that embed the Angular SDK must be on Angular 21. The npm and node requirements are unchanged.
* **Cross-version import:** importing a project build or version exported from an older platform line completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten.
* **Database migrations:** the lock that guards Liquibase schema migrations at service startup is a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration releases its lock when the database closes the session. Service accounts no longer need the `pods/status` permission. Oracle deployments need new database grants.
* **Events Gateway:** authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`. Helm chart deployments where `authorization-system` runs its migrations with Keycloak admin access need no action.
* **Helm charts:** the container image reference is split into `image.registry` and `image.repository`. The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. The default image location is unchanged.
* **Integration Designer:** service startup no longer scans the full token-instance collection, and the run-list summary queries are indexed.
* **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.
* **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.

#### Fixed

* **Actions:** deleting an action whose business rule calls a function works instead of returning a server error.
* **Build export:** retrying a build export re-attempts a dependency library whose own export timed out, so the parent build can finish.
* **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output from trailing empty cells and rows.
* **Entry points:** the entry-point picker in version settings lists only processes and UI flows from the current project.
* **Gateways:** an expression that fails to evaluate on an exclusive gateway surfaces as an incident on the process instance instead of only in the service logs.
* **Generated documents:** a document whose storage write fails returns an error instead of being recorded as successful. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.
* **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is listed once instead of once per consuming project version.
* **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives during a background synchronization, and merging versions no longer fails with a navigation-areas error.
* **Renderers:** the document preview shows its subtitle, and the file-upload error message follows the configured theme.
* **Reusable UI templates:** static input mappings configured on a reusable template are applied at runtime.
* **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.
* **Task management:** the row-selection checkbox column no longer carries an invisible sort control that re-sorted the view and cleared the selection, and changing the page size no longer opens the wrong process from the list.
* **Themes and CMS resources:** exporting a theme no longer includes duplicate copies of system icons, and importing no longer leaves system substitution tags missing.
* **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.4 release notes](/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026) · [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4)

**5.9.3**

July 2026

**Upgrade actions:** none. The new Events Gateway and Integration Designer settings ship with working defaults. Details are in the [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3#configuration-changes).

#### Changed

* **Events Gateway:** new settings tune the dedicated Redis connection pool for blocking reads, and the default blocking-read duration is lowered from 5 seconds to 1 second. If you set the blocking-read duration explicitly, review it against the new default.
* **Integration Designer:** a new setting sets the number of partitions for auto-created workflow Kafka topics. Existing topics are not modified.
* **Media Library:** PDF assets in the list can be opened in a new tab.
* **Process start:** web renderers keep the loading indicator visible until the first user task renders.

#### Fixed

* **Build import:** a transient database write conflict during a multi-dependency import no longer drops a dependency's build, which caused runtime errors on substitution tags and enumerations. Large imports may take slightly longer.
* **Date Picker:** the calendar anchors to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.
* **Designer:** opening Runtime after expanding a component's Permissions section no longer freezes the Designer, and a pending AI UI-generation draft no longer locks the process diagram read-only.
* **Projects:** creating a project with the same name as a deleted project returns a validation error instead of an internal server error.
* **Real-time event delivery:** the Events Gateway no longer leaks Redis connections. Blocking reads run on a dedicated connection pool with Redis Cluster support, so the gateway no longer needs periodic restarts under sustained load.
* **Task management:** deleting a swimlane allocation rule removes only that rule, clicking Save twice no longer creates duplicate rules, and task views no longer reset when the same view is open from different workspaces.
* **Workflows:** a workflow no longer freezes silently after a step exhausts its retries.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.3 release notes](/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026) · [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3)

**5.9.2**

July 2026

**Upgrade actions:** update any Keycloak group mapper or external IdP claim that emits the end-user group `User` to `Users Group`, remove records of the organization-ID migration or other Liquibase changesets you marked as executed by hand on an earlier 5.9.x (contact FlowX support for the list first), upgrade the AI Platform chart and the core services together, and update dashboards, alerts, and log queries that match the `ai-platform-` service name prefix. Details are in the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#upgrade-overview).

#### New

* **AI agents and data models:** AI Designer and AI Developer use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it.
* **AI workflow nodes:** JSON schema fields support `${}` placeholders.
* **Chat file uploads:** end users can attach multiple files in a chat-driven app. Uploads are indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content.
* **Document Parser:** a new LiteParse engine parses PDFs and images locally without GPU or AI calls, and OCR supports English, Romanian, Hungarian, and Bulgarian.
* **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.
* **Knowledge bases:** a Custom Agent node can select multiple knowledge bases, each exposed to the agent as its own retrieval tool, and retrieval can span multiple knowledge bases in a workflow.
* **SQL data sources:** queries on SQL data sources can be tested from the builds list.
* **Use in reporting:** the reporting toggle is available on UI flows and workflows.

#### Changed

* **AI node structured output:** responses from AI nodes with a response schema are validated against it, with automatic repair retries, and node logs include the failure reason and rejected output.
* **AI Platform services:** services are deployed under their plain names, without the `ai-platform-` prefix on pod, service, and image names, and the bundled Qdrant subchart is renamed the same way. Core services resolve AI components by the new names.
* **Audit log:** records sharing, user invitations, designer-user, end-user, and group management, actions on process instances and UI flows, adding a dependency, and terminating process, workflow, or UI flow instances.
* **Copy to project:** copying a process or UI flow to another project also copies its roles.
* **Data archiving:** archiving detaches a partition only when every process or workflow instance in it has finished. New settings for terminating stuck instances and backfilling legacy rows are off by default.
* **Default end-user group:** the group that the 5.1.x upgrade migration creates is renamed from `User` to `Users Group`. Groups your admins created are not renamed.
* **Designer:** the Event Handlers section appears higher in the component configuration panel, and the keys to save for collection items and bundled custom-component inputs are computed automatically.
* **Kafka reconnects:** platform services use a gentler broker-reconnect backoff by default, and repeated Kafka connection errors log at a quieter level.

#### Fixed

* **Active policy:** the user list on the override active-policy form is no longer empty.
* **Application manager:** the runtime-application organization-ID migration converts existing data correctly.
* **Audit logs:** filtering audit entries by user works when the username differs from the email address.
* **Build export with media files:** exporting a build with media file content produces an archive that contains the binaries.
* **Chat:** the floating chat position is calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.
* **CMS enumerations:** cascading-enum value lookups resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.
* **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.
* **Data sync with private CA certificates:** data-sync migrations that call HTTPS endpoints, such as Keycloak, no longer fail certificate validation in environments that use an internal certificate authority.
* **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.
* **Project version merge:** a merge no longer fails with a 500 error.
* **Redis Cluster:** UI template cache keys map to the same cluster slot, which prevents cross-slot errors.
* **Reusable UI templates:** actions are no longer missing at runtime when a template is nested in multiple levels of containers.
* **Self-hosted installation and upgrade:** Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding work on self-hosted environments.
* **Workflow data:** archiving batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine is fixed.
* Stability fixes across the Designer, the renderers, and the backend services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.2 release notes](/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026) · [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2)

**5.9.1**

June 2026

**Upgrade actions:** none for deployments where the Helm chart provisions Kafka topics. If you provision Kafka topics or ACLs manually, create the topics added in 5.9.1. Details are in the [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics).

#### New

* **AI permissions:** AI runtime usage and AI build-time tooling (AI Designer, agent building, code generation) are governed by two separate permissions. When AI is turned off, AI icons and entry points are hidden instead of shown disabled, and build-time helpers such as code generation and "Add comment" follow the dev-agent permission.
* **File Preview:** scroll-trigger event handlers, including a "document end" trigger, let a flow detect when a user scrolls through a document or reaches its end, for example to enable an **Accept** button only after the user reaches the end of an agreement.
* **File upload:** the upload button supports a configurable icon, set in the Designer.
* **Microsoft Outlook:** connections support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
* **Script engine:** business rules, reusable functions, and node rules can each run on the native engine (the 5.9 default) or the legacy GraalVM engine. Rules created before the switch to native keep running on GraalVM until you migrate them, and new rules default to native.

#### Changed

* **AI Designer:** generates UI from a flat template format instead of 3-level nesting, supports more component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates incrementally instead of regenerating them, and can generate reusable UI templates.
* **Kafka topics:** new topics carry runtime config-param change events, runtime instance terminations, resource cache evictions, and evaluation improvement suggestions. The Helm chart provisions them.
* **Merge conflicts:** merge-conflict handling for custom components and UI Flows identifies resources more clearly.
* **Organization settings:** navigation and design improvements.
* **Platform Status:** reports AI Platform components and their databases alongside the core services.
* **Runtime config params:** changes reach the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
* **Workflows:** storage of running steps is optimized, workflows and processes launched from a UI Flow inherit the build of the parent UI Flow, and AI node failures show the error details and model reasoning in the workflow run logs.

#### Fixed

* **Actions:** GET actions no longer fire with undefined parameters.
* **AI chat:** agent responses no longer reappear in chat after stop and refresh, and the builder-agent chat no longer duplicates messages.
* **Copy to project:** copying a process or workflow to another project succeeds, and copied workflows appear in the target project.
* **End-user login:** a null value is no longer cached when looking up the "All end-users" group, which could block logins until data sync completed.
* **File Preview:** previews render correctly, events fire inside collections, a fixed height applies at runtime, and preview resources no longer fail with CORS errors.
* **File Storage:** FTP test connection and file operations resolve configuration-parameter placeholders, and FTP file preview works when the root path has no leading slash.
* **Forms to validate:** scrolling covers the full component hierarchy, placeholders update, and chat and tab-bar components are selected correctly.
* **Hide and disable conditions:** conditions on UI templates, processes, and UI Flows apply at runtime for Designer users without workspace access.
* **Invitations:** an invited Designer user added as an Organization owner is assigned to a workspace.
* **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
* **Modals:** dropdowns no longer flicker, and long key names no longer break the layout.
* **Process instances:** loading an instance with a very large execution graph no longer crashes the browser.
* **Task management:** headers follow the theme in React and Angular, and the filter window no longer disappears after applying criteria.
* **Theme admin:** "copy to" no longer loses theme content.
* **Timer events:** activating a start timer event after a new build regenerated the process resource ID no longer fails with a 500 (duplicate key) error.
* **UI Flow:** images display in preview after refresh, and returning from an expired UI Flow no longer loses the theme UUID.
* **Usage Overview:** opening a usage overview no longer fails with a 500 error.
* **Web renderer:** the button shadow and modal content padding are restored, and components render when a media-file storage path is null.
* **Workflows:** END PARALLEL output no longer includes data from before the parallel branches started, and NoSQL node run logs no longer crash when a node fails before building its options.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.1 release notes](/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026) · [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1)


# Deployment guidelines v5.0.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/deployment-guidelines-v5.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.29.2** | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.25.2** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.21.2** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.14.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.17.2** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.14.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.12.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.15.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.11.0** | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.26.2** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.11.0** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.14.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.11.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | |

### Embedded components

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **SpiceDB** | **1.42.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **DGraph** | **25.0.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

### Renderers

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.3** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.0.12** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.0.0 | Keycloak | 26+ |
| 5.0.0 | Kafka | 3.8 - 3.9 |
| 5.0.0 | PostgreSQL | 16 - 17 |
| 5.0.0 | Oracle Database | 21c, 23ai |
| 5.0.0 | MongoDB | 7 - 8 |
| 5.0.0 | Redis | 7.4 - 8.0 |
| 5.0.0 | Elasticsearch | 8 - 9 |
| 5.0.0 | Angular (Web SDK) | 19.x |
| 5.0.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/configuration-and-migration

This section contains the steps in the order we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](../../../../5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The Authorization System will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

> [!NOTE]
>
> The admin user imported here is the same service account referenced in the migration prerequisites. If you followed the prerequisites page and set up the admin Keycloak user beforehand, the Authorization System will pick it up automatically during this step — no additional action is needed.

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from Application Manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.0.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | 🆕 Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Kafka Configuration

> [!NOTE]
>
> Consumer group naming standardized to kebab-case across all FlowX.AI services with new messaging features for enhanced functionality.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group naming changes

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
> | | |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Application Manager specific features

#### New environment variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | 🆕 Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | 🆕 Maximum HTTP request header size |

#### New Kafka features

> [card] Resource Update Propagation
>
> Consumer Group: `app-resource-update-propagation-group`\
> Threads: 3\
> Topic: `ai.flowx.{env}.application-version.resource.update.propagation.v1`

> [card] Build Runtime Data
>
> Consumer Group: `build-runtime-data-group`\
> Threads: 2\
> Topic: `ai.flowx.{env}.build.runtime-data.v1`

> [card] Business Rule Sync
>
> Topic: `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> Purpose: Business rule synchronization

> [card] Process Sync (Restructured)
>
> Topic: `ai.flowx.{env}.application-version.sync.process.in.v1`\
> Purpose: Enhanced process synchronization

> [card] Reusable Templates sync
>
> Topic: `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> Purpose: Reusable template synchronization

#### Kafka environment variables (optional overrides)

```bash New Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_RESOURCEUPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Business Rule Sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1

# Process Sync (restructured)
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1


# Reusable Templates sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1
```

```bash Consumer Groups theme={"dark"}
# New Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
```

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides.

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | 🆕 Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | 🆕 Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | 🆕 S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | 🆕 S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | 🆕 S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | 🆕 S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | 🆕 S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | 🆕 S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | 🆕 Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | 🆕 Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | 🆕 Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | 🆕 Redis host |
| `SPRING_REDIS_PORT` | `6379` | 🆕 Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | 🆕 Redis password |
| `SPRING_REDIS_TTL` | `5000000` | 🆕 Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | 🆕 Redis host |

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/install-services

Step-by-step installation guide for new FlowX.AI 5.0 services

FlowX.AI 5.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](/5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](/5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.6 (or newer) to 5.0.0. If you’re on an earlier version, upgrade to the latest LTS version first.

## Success factors

> [!WARNING]
>
> The following steps are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB** must be installed before any FlowX.AI services. **DGraph** is only required if you are using FlowX AI agents — if not, you can skip DGraph installation, but SpiceDB is still mandatory.
>
> > [!NOTE]
> >
> > Only DGraph can be skipped (and only if you are not using FlowX AI agents). SpiceDB is mandatory for all deployments.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices migration** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](/5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites

This section contains the steps in the order we recommend for migrating data from FlowX v4.7.x to v5.0.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.6 | FlowX.AI 5.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.0#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip installing DGraph. SpiceDB is still mandatory.

> [card] [SpiceDB setup guide](../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.0.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

Before upgrading to FlowX.AI 5.0, you must run two operations on all existing Elasticsearch indices:

1. **Update index mappings** to include the `workspaceId` field (schema change)
2. **Migrate existing documents** to assign them to the default workspace (data migration)

These operations are required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable; if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

> [!WARNING]
>
> If Elasticsearch migration is not completed correctly, some process instances may not appear in search results, data-search features might return incomplete results, and workspace-scoped queries will fail for unmigrated data. Existing resources will also not be visible or accessible within the new workspace structure.

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.0.0.

***

## Authorization System Prerequisites

Before deploying the `authorization-system` service, you must configure the organization admin user. This is a critical prerequisite for ensuring that the authentication and user management features function correctly post-upgrade.

### Steps to Configure the Organization Admin User

Follow these guides to correctly set up the organization admin user:

> [card] [Bootstrap Organization Admin](../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Organization Admin Roles & Workspace Access](../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

> [!TIP]
>
> Configuration of the organization admin user must be completed **before** deploying the authorization-system service (see the [Install Services](./install-services) section for service deployment steps).

### Pre-migration preparation

Required configuration for the authorization-system service:

* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE`= `true` (mandatory for migrations)
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME`= `<admin-username>` (recommended method, default: `admin@flowx.ai`)

The system will search for this username in Keycloak and automatically copy the user's subject ID to the authorization-system database.

**Fallback method:** If the username method fails or you prefer to specify the subject ID directly:

* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID`= `<subject-id-of-admin-user>`

> [!TIP]
>
> To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.

![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users"
    ]
  }
}
```


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.06.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.0") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.0 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.0 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.0 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.0 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.0 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# FlowX.AI 5.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025

Latest features, improvements, and bug fixes in our newest release

> [!WARNING]
>
> This release includes the following features in Tech Preview. We encourage you to try them out and share your feedback to help us improve them. Please note that Tech Preview features may change before final release.

> [tab] What's New
>
> **What's new? 🆕**
>
> 🆕 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture)\
> 🆕 [**Project Data Model (PDM)**](#project-data-model-pdm)\
> 🆕 [**FlowX.AI Database**](#flowx-ai-database)\
> 🆕 [**Multi Select UI Component**](#multi-select-ui-component)\
> 🆕 [**Library-to-Library Dependencies**](#library-to-library-dependencies)\
> 🆕 [**Data Mappers**](#data-mappers)\
> 🆕 [**Reusable Resources**](#reusable-resources)\
> 🆕 [**Files in Integration Designer**](#files-in-integration-designer)\
> 🆕 [**Rendering improvements**](#rendering-improvements)
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Major Infrastructure Changes**: Workspaces introduces SpiceDB integration and new database schemas for multi-tenant architecture.
> > >
> > > **Key Changes:**
> > >
> > > * **SpiceDB Integration**: New permission management system requiring deployment
> > >
> > > * **Database Migration**: Schema updates for workspace support
> > >
> > > * **User Storage**: Only information about FlowX.AI Designer users is stored in FlowX.AI. The stored user data is limited to: unique identifier, username, first name, last name, and email address.
> > >
> > > * **Default Workspace**: All the projects and libraries are migrated to default workspace
> > >
> > > > [!TIP]
> > > >
> > > > **Backward Compatibility**: All existing functionality preserved in default workspace
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Login Flow**: After authentication, select your workspace before accessing FlowX.AI Designer. Once inside a workspace, everything works as before.
> > >
> > > **What's New:**
> > >
> > > * **Workspace Selection**: Choose workspace after login
> > > * **Resource Isolation**: Projects, libraries, themes are workspace-specific
> > > * **Enhanced Permissions**: Fine-grained access control with user groups and ACLs
> > > * **Workspace Management**: Create and manage workspaces (admin users)
> > >
> > > **What Stays the Same:**
> > >
> > > * Process design and configuration
> > > * UI Designer capabilities
> > > * Integration patterns
> > > * All existing FlowX.AI Designer features
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Transformation**: Workspaces enables enterprise multi-tenant architecture with independent business unit governance while sharing platform capabilities.
> > >
> > > **Business Impact:**
> > >
> > > * **Faster time-to-market** for new business verticals
> > > * **Enhanced compliance** with workspace-specific controls
> > > * **Improved governance** with fine-grained access management
> > >
> > > **Enterprise Benefits:**
> > >
> > > * Business unit autonomy with shared platform
> > > * Regulatory compliance through data isolation
> > > * Centralized upgrades and maintenance
> > > * Cross-business unit resource sharing when appropriate
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Infrastructure Impact**: PDM has minimal infrastructure impact - it's a design-time feature that improves development efficiency without affecting runtime resources.
> > >
> > > > [!TIP]
> > > >
> > > > **No deployment changes required** - PDM is part of the design platform, not runtime
> > >
> > > > [!TIP]
> > > >
> > > > **Backward compatible** - Existing processes continue to work unchanged
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer**: Define data types once at project level, use everywhere. No more recreating Customer or Order objects in every process.
> > >
> > > **How to Use PDM:**
> > >
> > > 1. Navigate to Project → Config → Data Model
> > > 2. Define your business entities (Customer, Product, etc.)
> > > 3. Set governance rules (sensitive data, reporting)
> > > 4. Use these types in any process within the project
> > >
> > > **Best Practices:**
> > >
> > > * Start with core business entities
> > > * Use clear, consistent naming
> > > * Mark sensitive fields appropriately
> > > * Leverage library data types when available
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: PDM transforms how your organization manages business data definitions. Define business entities once and ensure consistency across all processes and teams.
> > >
> > > **Business Benefits:**
> > >
> > > * **Enhanced compliance** through centralized governance and data sensitivity controls
> > > * **Reduced errors** from consistent data definitions
> > >
> > > **ROI Indicators:**
> > >
> > > * Development Efficiency: Measure reduction in process creation time
> > > * Error Reduction: Track fewer data-related production issues
> > > * Maintenance Cost: Monitor time spent on data structure updates
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Infrastructure Planning Required**: FlowX.AI Database creates additional MongoDB collections and requires infrastructure planning for storage, monitoring, and backup procedures.
> > >
> > > > [!TIP]
> > > >
> > > > New microservice: NoSQL DB Runner. Check the [setup guide](/5.1/setup-guides/nosql-db-runner) for more details.
> > >
> > > **Key Considerations:**
> > >
> > > * **Storage Planning**: Monitor usage as processes adopt internal database (plan for 20-30% increase)
> > > * **Performance Monitoring**: Set up alerts for FlowX.AI Database query performance
> > > * **Backup Strategy**: Include FlowX.AI Database collections in backup procedures
> > > * **Connection Pooling**: Additional connection pools for database operations
> > > * **Memory**: Additional 256MB-512MB per FlowX.AI instance for database operations
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Integration Option**: FlowX.AI Database appears as a new Data Source type in Integration Designer, right alongside RESTful System.
> > >
> > > **When to Use FlowX.AI Database:**
> > >
> > > * Customer data lookup across processes
> > > * Shared configuration and reference data
> > > * Process-to-process communication
> > > * Caching frequently accessed data
> > > * Temporary operational data storage
> > >
> > > **How to Implement:**
> > >
> > > 1. Add Data Source node to your process
> > >
> > > 2. Select "FlowX.AI Database" as type
> > >
> > > 3. Configure collection and operations
> > >
> > > 4. Use familiar MongoDB syntax (find, insert, update)
> > >
> > > > [!WARNING]
> > > >
> > > > **When NOT to Use**: Don't replace your core business systems. FlowX.AI Database is perfect for operational data, caching, and inter-process communication - but your CRM, ERP, and other systems of record should remain your primary data sources.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: FlowX.AI Database enables new operational patterns that were previously complex or impossible. It's not about replacing your core systems, but about enabling new ways to orchestrate business processes.
> > >
> > > **New Business Capabilities:**
> > >
> > > * **Cross-process workflows**: Loan application → Credit check → Approval across different process instances
> > > * **Real-time dashboards**: Operational data for business monitoring without system integration
> > > * **Agile experimentation**: Test new business rules without impacting core systems
> > > * **Process orchestration**: Complex business flows spanning multiple departments
> > >
> > > **ROI Considerations:**
> > >
> > > * **Time to Market**: Faster implementation of new business processes
> > > * **Agility**: Rapid prototyping and testing of business ideas
> > >
> > > **Use FlowX.AI Database when:**
> > >
> > > * Data is operational and process-specific (not master data)
> > > * You need rapid implementation without IT system changes
> > > * Process instances need to communicate with each other
> > > * You're prototyping new business capabilities
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **No Infrastructure Impact**: Multi Select is a pure UI component with no backend requirements. It works with existing form handling and data storage mechanisms.
> > >
> > > > [!TIP]
> > > >
> > > > **Zero deployment overhead** - Component is part of the UI framework upgrade
> > >
> > > > [!TIP]
> > > >
> > > > **Existing data handling** - Uses standard array storage, no schema changes needed
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Easy Integration**: Multi Select works just like other form elements in UI Designer. Drag, drop, configure - no new learning curve required.
> > >
> > > **Common Use Cases:**
> > >
> > > 1. **Skills Selection**: Job applications, team member profiles, contractor skills
> > > 2. **Product Features**: Insurance coverage options, software licensing features
> > > 3. **Categories & Tags**: Document classification, customer segmentation
> > >
> > > **Key Configuration:**
> > >
> > > * **Max selections**: Control input limits
> > > * **Display format**: Chips, lists, custom
> > > * **Search**: Filter large option sets
> > > * **Clear all**: Easy reset functionality
> > > * **Validation**: Min/max rules
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **User Experience Impact**: Multi Select eliminates user frustration in scenarios where single selection doesn't match real-world needs. This improves data quality and user satisfaction.
> > >
> > > **Before vs After:**
> > >
> > > * ❌ **Before**: "I can only select one skill, but I have multiple certifications"
> > > * ✅ **After**: "Perfect! I can select all my relevant skills at once"
> > >
> > > **Business Process Examples:**
> > >
> > > * **Employee Onboarding**: Select multiple skills, certifications, department access
> > >
> > > * **Product Configuration**: Select multiple features, add-ons, support packages
> > >
> > > * **Customer Preferences**: Select multiple communication channels, product interests
> > >
> > > > [!TIP]
> > > >
> > > > **Analytics Benefit**: Multi-select data provides richer analytics. Instead of knowing a customer chose "Primary Interest: Technology," you know they selected "AI, Cloud Computing, Cybersecurity, Mobile Development" - much more actionable for business intelligence.
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backwards Compatibility**: FlowX.AI 5.0 maintains full backwards compatibility with existing project-to-library dependencies from FlowX.AI 4.x. All existing dependencies will continue to work without modification.
> > >
> > > **Upgrade Process:**
> > >
> > > 1. **Existing dependencies** will be automatically migrated
> > >
> > > 2. **New library dependency features** become available immediately
> > >
> > > 3. **No breaking changes** to existing functionality
> > >
> > > 4. **Enhanced validation** may catch previously undetected issues
> > >
> > > > [!WARNING]
> > > >
> > > > **Post-Migration Required**: After the lib2lib migration is executed, you must clear the cache. This is necessary because a new field is added to the build mongo document.
> > >
> > > **Cache Clearing Steps:**
> > >
> > > 1. Complete the lib2lib migration process
> > > 2. Clear the application cache to ensure the new build document fields are properly recognized
> > > 3. Verify that library-to-library dependencies are functioning correctly
> > >
> > > **Key Changes:**
> > >
> > > * **Build Export Changes**: Build exports now automatically include entire dependency trees (larger packages but self-contained)
> > > * **Dependency Validation**: Build process now checks for dependency conflicts (enhanced validation may catch previously undetected issues)
> > > * **Deployment Consistency**: Single-version constraint prevents runtime conflicts (more predictable deployments)
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Enhanced Organization**: You can now create more sophisticated library structures where specialized libraries build upon common foundations. This reduces duplication and improves consistency.
> > >
> > > **How It Works:**
> > >
> > > 1. Navigate to Library → Config → Dependencies
> > > 2. Add other libraries as dependencies
> > > 3. FlowX.AI validates for conflicts automatically
> > > 4. Resources from all dependency levels become available
> > >
> > > **Best Practices:**
> > >
> > > * Plan your library hierarchy before implementation
> > >
> > > * Keep dependencies focused and purposeful
> > >
> > > * Avoid circular dependencies
> > >
> > > * Use semantic versioning consistently
> > >
> > > * Document dependency relationships clearly
> > >
> > > > [!NOTE]
> > > >
> > > > **Example**: Create a "US Banking Library" that depends on "Global Banking Library" and "US Compliance Library". This way, US-specific processes get both global banking functionality and local compliance requirements automatically.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Enterprise Architecture**: Library-to-Library Dependencies enable sophisticated organizational structures where different teams can own specific business domains while building on shared foundations.
> > >
> > > **Enterprise Use Cases:**
> > >
> > > **Multi-Country Operations:**
> > > Global Insurance Company: US-specific library depends on Global Compliance library
> > >
> > > ```
> > > US Insurance Library → Global Compliance Library → Base Insurance Library
> > > ```
> > >
> > > **Product Line Specialization:**
> > > Bank: Mortgage processes use specialized libraries that extend common banking operations
> > >
> > > ```
> > > Mortgage Library → Lending Library → Core Banking Library
> > > ```
> > >
> > > **Business Impact:**
> > >
> > > * **Team Autonomy**: Teams work independently while leveraging shared assets
> > >
> > > * **Faster Innovation**: New products build on proven foundation components
> > >
> > > * **Risk Reduction**: Tested, validated components reduce implementation risk
> > >
> > > > [!WARNING]
> > > >
> > > > **Change Management**: This capability requires coordination between teams. Establish clear ownership models, communication protocols, and upgrade procedures before implementing complex dependency hierarchies.
>
> ***
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **Zero Infrastructure Impact**: Data Mappers is a design-time feature that enhances the FlowX.AI Designer interface without requiring additional infrastructure or deployment changes.
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backward Compatibility**: All existing data transfer mechanisms (like `append to parent process` or `output.[outputKey]`) continue to work unchanged. Teams can adopt Data Mappers at their own pace.
> > >
> > > **Key Points:**
> > >
> > > * **No new microservices** - Enhancement to existing designer interface
> > > * **No runtime changes** - Data mapping occurs at design time
> > > * **Existing configurations preserved** - Zero impact on current implementations
> > > * **Optional adoption** - Teams choose when and where to use new functionality
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer for Integration**: No more complex syntax for data transfers. Visual drag-and-drop interface makes component integration intuitive and error-free.
> > >
> > > **How to Use Data Mappers:**
> > >
> > > 1. **Define Parameters**: Set input/output parameters on Start/End nodes
> > > 2. **Choose Implementation**: Select "Data Mapper" or "Current" method
> > > 3. **Visual Mapping**: Drag source parameters to destination parameters
> > > 4. **Save Configuration**: Store mappings for reuse and maintenance
> > >
> > > **When to Use:**
> > >
> > > * **Call Activities**: Passing data between parent and child processes
> > >
> > > * **Integration Workflows**: Connecting with external systems
> > >
> > > * **Complex Data Flows**: When visual mapping improves clarity
> > >
> > > * **Team Collaboration**: When multiple people work on integration logic
> > >
> > > > [!WARNING]
> > > >
> > > > **Parameter Changes**: When you modify input/output parameters, existing mappings must be manually updated. Changes don't automatically propagate to avoid unintended data flow modifications.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: Data Mappers transforms technical integration tasks into visual, business-friendly workflows. Non-technical stakeholders can now understand and validate data flows between business processes.
> > >
> > > **Business Impact:**
> > >
> > > * **Reduced Errors**: Visual mapping prevents data integration mistakes that cause process failures
> > > * **Faster Development**: Intuitive interface accelerates process configuration and testing
> > > * **Better Documentation**: Visual data flows serve as living documentation of business logic
> > > * **Team Collaboration**: Business and technical teams can discuss data flows using the same visual interface
> > >
> > > **ROI Indicators:**
> > >
> > > * **Development Speed**: Measure reduction in integration configuration time
> > > * **Error Rate**: Track fewer data-related production issues
> > > * **Team Efficiency**: Monitor cross-functional collaboration improvements
> > > * **Process Quality**: Assess improvement in first-time-right deployments
> > >
> > > **Use Cases by Industry:**
> > >
> > > * **Banking**: Loan application data flowing from customer intake → credit check → approval process
> > > * **Insurance**: Claim data mapping from initial report → investigation → settlement
> > > * **Manufacturing**: Order data flowing from sales → production planning → fulfillment
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Minimal Infrastructure Impact**: Reusable Resources is primarily a design-time enhancement that leverages existing FlowX infrastructure with minimal additional overhead.
> > >
> > > **Infrastructure Considerations:**
> > >
> > > * **Execution Context**: Functions execute within existing process engine contexts - no additional runtime infrastructure required
> > >
> > > > [!TIP]
> > > >
> > > > **No New Microservices**: Features are integrated into existing FlowX.AI platform components
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Development Game Changer**: Access the new "Reusable Resources" section in FlowX.AI Designer - located alongside "Reusable Functions" - to eliminate 60-80% of repetitive development work.
> > >
> > > **Key Capabilities:**
> > >
> > > * **Data Model Support**: Full integration with Project Data Model (PDM)
> > > * **Action Scenarios**: Template-defined actions assigned during instantiation OR form-centric actions handled by User Task
> > > * **Omnichannel**: Templates work across web, mobile, and other channels
> > >
> > > **Best Practices:**
> > >
> > > * **Start with common patterns**: Identify frequently repeated business logic and UI components
> > > * **Test thoroughly**: Use interactive testing for functions and preview mode for templates
> > > * **Document usage**: Include clear descriptions and example use cases
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Revolutionary Business Impact**: Reusable Resources fundamentally changes how organizations approach process development, transforming from "build every time" to "build once, leverage everywhere."
> > >
> > > **Strategic Business Value:**
> > >
> > > * **Quality Assurance**: Dramatic reduction in defects through reusable, tested components
> > > * **Maintenance Efficiency**: Update business rules once to instantly affect all processes
> > > * **Team Productivity**: Developers focus on new business capabilities instead of repetitive development
> > > * **Consistency**: Ensure uniform business rules and user experience across all touchpoints
> > >
> > > **Industry Use Cases:**
> > >
> > > * **Functions**: KYC validation, credit scoring, fraud detection, regulatory compliance checks
> > >
> > > * **UI Templates**: Customer onboarding forms, document upload sections, account summary dashboards, loan application interfaces
> > >
> > > * **Functions**: Premium calculations, risk evaluation, claims processing, policy validation
> > >
> > > * **UI Templates**: Quote request forms, claims submission interfaces, policy comparison tables, agent dashboards
> > >
> > > * **Functions**: Patient eligibility checks, treatment authorization, billing calculations, compliance validation
> > >
> > > * **UI Templates**: Patient registration forms, appointment scheduling interfaces, medical history cards, provider dashboards
>
> ### **Files in Integration Designer**
>
> > [card] File Handling in Integration Designer
> >
> > FlowX.AI 5.0 introduces native file handling capabilities in Integration Designer, enabling seamless file uploads and downloads with external systems directly within your integration workflows.
> >
> > > [card] Download Files
> > >
> > > Call external APIs and receive files in the response. Integration Designer saves files to Document Plugin or S3 and returns paths for further processing.
> >
> > > [card] Upload Files
> > >
> > > Send files stored in Document Plugin or S3 to external APIs via multipart/form-data or single binary requests.
> >
> > > [card] Multiple Formats
> > >
> > > Support for JSON responses with Base64 encoded files and single binary responses with automatic file identification.
> >
> > > [card] Flexible Storage
> > >
> > > Configure file destinations to Document Plugin (process-linked) or S3 Protocol (custom buckets) based on your needs.
> >
> > [Learn more about File Handling in Integration Designer](../../../5.1/docs/platform-deep-dive/integrations/integration-designer#file-handling)
> >
> > New Feature
>
> ### **Rendering Improvements**
>
> > [card] UI/UX Enhancements
> >
> > > [tab] Grid & Layout Improvements
> > >
> > > > [card] Enhanced Grid Component
> > > >
> > > > Improved performance, responsiveness, and customization options for data display and form organization
> > >
> > > > [card] Navigation Areas Redesign
> > > >
> > > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> > >
> > > > [card] Multi Actions Support
> > > >
> > > > Batch operations support for UI components, enabling simultaneous actions on multiple elements
> > >
> > > > [card] Permission-Based UI Editing
> > > >
> > > > Granular control over UI element editing based on user permissions with partial editing capabilities
> >
> > > [tab] Enhanced Form Controls
> > >
> > > > [card] Input Type Code
> > > >
> > > > Specialized input component for code entry
> > >
> > > > [card] Formatting Options
> > > >
> > > > Advanced formatting capabilities for Input and Slider components
> > >
> > > > [card] Switch Variants
> > > >
> > > > Enhanced switch component supporting both toggle and checkbox variants
> > >
> > > > [card] Disabled Options on Selectors
> > > >
> > > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > > [tab] Advanced Features
> > >
> > > > [card] Custom Loader
> > > >
> > > > Configurable loading indicators for improved user experience during data operations
> > >
> > > > [card] Custom Validators
> > > >
> > > > Advanced validation logic using dynamic computed expressions
> > >
> > > > [card] File Upload Button Type
> > > >
> > > > New specialized button variant designed for file upload operations
> > >
> > > > [card] Copy Styles
> > > >
> > > > Efficiently replicate styling across multiple UI components
> >
> > > [tab] Analytics & Process
> > >
> > > > [card] Analytics Enhancements
> > > >
> > > > Custom payload support for detailed user interaction tracking and business intelligence
> > >
> > > > [card] Process End Handling
> > > >
> > > > Improved user experience when processes complete or terminate
> > >
> > > > [card] Forms in Collections
> > > >
> > > > Enhanced support for form elements within collection components
> > >
> > > > [card] Template Management
> > > >
> > > > Streamlined template organization by consolidating functionality in Reusable Resources

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.0](./deployment-guidelines-v5.0)
> >
> > Instructions for deploying FlowX.AI 5.0.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.0/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.0.0


# Deployment guidelines v5.1.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.1 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.0 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.0 → 5.1.1**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.64.3** | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **9.66.5** | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **9.36.3** | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **9.29.1** | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **9.35.1** | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **9.34.2** | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **9.23.1** | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **9.30.1** | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **9.25.1** | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **9.50.0** | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **9.22.1** | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **9.34.2** | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **9.22.1** | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Renderers

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **9.0.5** | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **9.0.3** | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.0 | 0.2.4 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.5** | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.1 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.0 processes and configurations

### What's included in 5.1.1

This maintenance release includes:

* **WCAG 2.1 Level AA compliance** across all web components (28 improvements)
* **3 customer-reported issue fixes** for production environments
* **62 proactive quality improvements** identified through internal testing
* **Platform enhancements** for SSE handling, CMS tags, and infrastructure

For detailed information on all changes, see the [FlowX.AI 5.1.1 Release Notes](./v5.1.1-november-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.1 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.1 | PostgreSQL | 16 - 17 |
| 5.1.1 | Oracle Database | 21c, 23ai |
| 5.1.1 | MongoDB | 7 - 8 |
| 5.1.1 | Redis | 7.4 - 8.0 |
| 5.1.1 | Elasticsearch | 8 |
| 5.1.1 | Angular (Web SDK) | 19.x |
| 5.1.1 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.10 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.9 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.9 → 5.1.10**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **process-engine** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **admin** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **designer** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **cms-core** | 9.46.3 | 9.46.2 | 9.45.4 | 9.44.2 |
| **scheduler-core** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **events-gateway** | 9.36.4 | 9.36.2 | 9.35.4 | 9.34.1 |
| **notification-plugin** | 9.39.3 | 9.39.2 | 9.38.4 | 9.37.1 |
| **document-plugin** | 9.44.3 | 9.44.2 | 9.43.4 | 9.42.2 |
| **task-management-plugin** | 9.43.3 | 9.43.2 | 9.42.4 | 9.41.1 |
| **data-search** | 9.32.3 | 9.32.2 | 9.31.4 | 9.30.1 |
| **audit-core** | 9.40.3 | 9.40.2 | 9.39.4 | 9.38.1 |
| **advancing-controller** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **integration-designer** | 9.59.4 | 9.59.3 | 9.58.5 | 9.57.1 |
| **application-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **runtime-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **data-sync** | 9.33.4 | 9.33.2 | 9.32.3 | 9.31.1 |
| **authorization-system** | 9.43.5 | 9.43.2 | 9.42.4 | 9.41.1 |
| **nosql-db-runner** | 9.31.3 | 9.31.2 | 9.30.4 | 9.29.1 |

### Renderers

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **iOS renderer** | 9.0.25 | 9.0.20 | 9.0.19 | 9.0.12 |
| **Android renderer** | 9.0.31 | 9.0.24 | 9.0.19 | 9.0.13 |

### Plugins

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.7 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.10 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** starting with 5.1.10 the default Redis read mode is `polling` (`EVENTS_REDIS_MODE`). This is applied automatically on upgrade; no action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.9 processes and configurations

### What's included in 5.1.10

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.10 Release Notes](./v5.1.10-june-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.10 | Keycloak | 26+ |
| 5.1.10 | Kafka | 3.8 - 3.9 |
| 5.1.10 | PostgreSQL | 16 - 17 |
| 5.1.10 | Oracle Database | 21c, 23ai |
| 5.1.10 | MongoDB | 7 - 8 |
| 5.1.10 | Redis | 7.4 - 8.0 |
| 5.1.10 | Elasticsearch | 8 - 9 |
| 5.1.10 | Angular (Web SDK) | 19.2 |
| 5.1.10 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.11 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.10 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.10 → 5.1.11**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **process-engine** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **admin** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **designer** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **cms-core** | 9.47.3 | 9.46.3 | 9.46.2 | 9.45.4 |
| **scheduler-core** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **events-gateway** | 9.37.3 | 9.36.4 | 9.36.2 | 9.35.4 |
| **notification-plugin** | 9.40.3 | 9.39.3 | 9.39.2 | 9.38.4 |
| **document-plugin** | 9.45.3 | 9.44.3 | 9.44.2 | 9.43.4 |
| **task-management-plugin** | 9.44.4 | 9.43.3 | 9.43.2 | 9.42.4 |
| **data-search** | 9.33.3 | 9.32.3 | 9.32.2 | 9.31.4 |
| **audit-core** | 9.41.3 | 9.40.3 | 9.40.2 | 9.39.4 |
| **advancing-controller** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **integration-designer** | 9.60.3 | 9.59.4 | 9.59.3 | 9.58.5 |
| **application-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **runtime-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **data-sync** | 9.34.2 | 9.33.4 | 9.33.2 | 9.32.3 |
| **authorization-system** | 9.44.4 | 9.43.5 | 9.43.2 | 9.42.4 |
| **nosql-db-runner** | 9.32.3 | 9.31.3 | 9.31.2 | 9.30.4 |

### Renderers

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **iOS renderer** | 9.0.27 | 9.0.25 | 9.0.20 | 9.0.19 |
| **Android renderer** | 9.0.37 | 9.0.31 | 9.0.24 | 9.0.19 |

### Plugins

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.7 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.11 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.10 processes and configurations

### What's included in 5.1.11

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.11 Release Notes](./v5.1.11-july-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.11 | Keycloak | 26+ |
| 5.1.11 | Kafka | 3.8, 3.9 |
| 5.1.11 | PostgreSQL | 16, 17 |
| 5.1.11 | Oracle Database | 21c, 23ai |
| 5.1.11 | MongoDB | 7, 8 |
| 5.1.11 | Redis | 7, 8 |
| 5.1.11 | Elasticsearch | 8 |
| 5.1.11 | Angular (Web SDK) | 19.2 |
| 5.1.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.12

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.12 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.11 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.11 → 5.1.12**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **process-engine** | 9.76.7 | 9.76.3 | 9.75.7 | 9.75.3 |
| **admin** | 9.76.6 | 9.76.3 | 9.75.7 | 9.75.3 |
| **designer** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **cms-core** | 9.47.5 | 9.47.3 | 9.46.3 | 9.46.2 |
| **scheduler-core** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **events-gateway** | 9.37.4 | 9.37.3 | 9.36.4 | 9.36.2 |
| **notification-plugin** | 9.40.4 | 9.40.3 | 9.39.3 | 9.39.2 |
| **document-plugin** | 9.45.4 | 9.45.3 | 9.44.3 | 9.44.2 |
| **task-management-plugin** | 9.44.6 | 9.44.4 | 9.43.3 | 9.43.2 |
| **data-search** | 9.33.4 | 9.33.3 | 9.32.3 | 9.32.2 |
| **audit-core** | 9.41.4 | 9.41.3 | 9.40.3 | 9.40.2 |
| **advancing-controller** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **integration-designer** | 9.60.5 | 9.60.3 | 9.59.4 | 9.59.3 |
| **application-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **runtime-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **data-sync** | 9.34.3 | 9.34.2 | 9.33.4 | 9.33.2 |
| **authorization-system** | 9.44.5 | 9.44.4 | 9.43.5 | 9.43.2 |
| **nosql-db-runner** | 9.32.4 | 9.32.3 | 9.31.3 | 9.31.2 |

### Renderers

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **iOS renderer** | 9.0.29 | 9.0.27 | 9.0.25 | 9.0.20 |
| **Android renderer** | 9.0.39 | 9.0.37 | 9.0.31 | 9.0.24 |

### Plugins

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.7 | 0.2.6 |

### AI Platform

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.12 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.11 processes and configurations

### What's included in 5.1.12

This maintenance release includes:

* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.12 Release Notes](./v5.1.12-august-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.12 | Keycloak | 26+ |
| 5.1.12 | Kafka | 3.8, 3.9 |
| 5.1.12 | PostgreSQL | 16, 17 |
| 5.1.12 | Oracle Database | 21c, 23ai |
| 5.1.12 | MongoDB | 7, 8 |
| 5.1.12 | Redis | 7, 8 |
| 5.1.12 | Elasticsearch | 8 |
| 5.1.12 | Angular (Web SDK) | 19.2 |
| 5.1.12 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.13
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.13

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.13 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.12 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.12 → 5.1.13**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **process-engine** | 9.76.10 | 9.76.7 | 9.76.3 | 9.75.7 |
| **admin** | 9.76.8 | 9.76.6 | 9.76.3 | 9.75.7 |
| **designer** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **cms-core** | 9.47.6 | 9.47.5 | 9.47.3 | 9.46.3 |
| **scheduler-core** | 9.36.5 | 9.36.4 | 9.36.3 | 9.35.3 |
| **events-gateway** | 9.37.5 | 9.37.4 | 9.37.3 | 9.36.4 |
| **notification-plugin** | 9.40.5 | 9.40.4 | 9.40.3 | 9.39.3 |
| **document-plugin** | 9.45.5 | 9.45.4 | 9.45.3 | 9.44.3 |
| **task-management-plugin** | 9.44.7 | 9.44.6 | 9.44.4 | 9.43.3 |
| **data-search** | 9.33.5 | 9.33.4 | 9.33.3 | 9.32.3 |
| **audit-core** | 9.41.5 | 9.41.4 | 9.41.3 | 9.40.3 |
| **advancing-controller** | 9.36.6 | 9.36.4 | 9.36.3 | 9.35.3 |
| **integration-designer** | 9.60.7 | 9.60.5 | 9.60.3 | 9.59.4 |
| **application-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **runtime-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **data-sync** | 9.34.4 | 9.34.3 | 9.34.2 | 9.33.4 |
| **authorization-system** | 9.44.6 | 9.44.5 | 9.44.4 | 9.43.5 |
| **nosql-db-runner** | 9.32.5 | 9.32.4 | 9.32.3 | 9.31.3 |

### Renderers

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **iOS renderer** | 9.0.32 | 9.0.29 | 9.0.27 | 9.0.25 |
| **Android renderer** | 9.0.44 | 9.0.39 | 9.0.37 | 9.0.31 |

### Plugins

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.7 |

### AI Platform

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.13 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.12 processes and configurations

### What's included in 5.1.13

This maintenance release includes:

* **Reliability fixes** for process advancing under load
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.13 Release Notes](./v5.1.13-september-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.13 | Keycloak | 26+ |
| 5.1.13 | Kafka | 3.8, 3.9 |
| 5.1.13 | PostgreSQL | 16, 17 |
| 5.1.13 | Oracle Database | 21c, 23ai |
| 5.1.13 | MongoDB | 7, 8 |
| 5.1.13 | Redis | 7, 8 |
| 5.1.13 | Elasticsearch | 8 |
| 5.1.13 | Angular (Web SDK) | 19.2 |
| 5.1.13 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.14
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.14

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.14 is the final planned maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.13 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.13 → 5.1.14**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **process-engine** | 9.76.12 | 9.76.10 | 9.76.7 | 9.76.3 |
| **admin** | 9.76.10 | 9.76.8 | 9.76.6 | 9.76.3 |
| **designer** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **cms-core** | 9.47.8 | 9.47.6 | 9.47.5 | 9.47.3 |
| **scheduler-core** | 9.36.7 | 9.36.5 | 9.36.4 | 9.36.3 |
| **events-gateway** | 9.37.7 | 9.37.5 | 9.37.4 | 9.37.3 |
| **notification-plugin** | 9.40.7 | 9.40.5 | 9.40.4 | 9.40.3 |
| **document-plugin** | 9.45.7 | 9.45.5 | 9.45.4 | 9.45.3 |
| **task-management-plugin** | 9.44.9 | 9.44.7 | 9.44.6 | 9.44.4 |
| **data-search** | 9.33.7 | 9.33.5 | 9.33.4 | 9.33.3 |
| **audit-core** | 9.41.8 | 9.41.5 | 9.41.4 | 9.41.3 |
| **advancing-controller** | 9.36.8 | 9.36.6 | 9.36.4 | 9.36.3 |
| **integration-designer** | 9.60.9 | 9.60.7 | 9.60.5 | 9.60.3 |
| **application-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **runtime-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **data-sync** | 9.34.6 | 9.34.4 | 9.34.3 | 9.34.2 |
| **authorization-system** | 9.44.8 | 9.44.6 | 9.44.5 | 9.44.4 |
| **nosql-db-runner** | 9.32.7 | 9.32.5 | 9.32.4 | 9.32.3 |

### Renderers

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **iOS renderer** | 9.0.38 | 9.0.32 | 9.0.29 | 9.0.27 |
| **Android renderer** | 9.0.48 | 9.0.44 | 9.0.39 | 9.0.37 |

### Plugins

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.8 |

### AI Platform

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Version | Description |
| - | - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | 1.52.0 | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | 1.25.1 | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | 25.0.0-preview6 | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.14 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release. The audit index retention settings below are optional.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted | audit-core |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only | audit-core |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch).

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.13 processes and configurations

### What's included in 5.1.14

This maintenance release includes:

* **Android renderer fix** for the action loader on modal screens
* **Optional audit index retention** and shard-size rollover settings
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.14 Release Notes](./v5.1.14-october-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.14 | Keycloak | 26+ |
| 5.1.14 | Kafka | 3.8, 3.9 |
| 5.1.14 | PostgreSQL | 16, 17 |
| 5.1.14 | Oracle Database | 21c, 23ai |
| 5.1.14 | MongoDB | 7, 8 |
| 5.1.14 | Redis | 7, 8 |
| 5.1.14 | Elasticsearch | 8 |
| 5.1.14 | Angular (Web SDK) | 19.2 |
| 5.1.14 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.2 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.1 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.1 → 5.1.2**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **process-engine** | **9.67.0** | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **9.68.1** | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **9.39.0** | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **9.28.1** | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **9.29.0** | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **9.32.0** | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **9.37.1** | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **9.25.1** | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **9.33.0** | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **9.28.0** | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **9.52.1** | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **9.26.0** | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **9.24.1** | 9.22.1 | 9.21.0 | 9.11.0 |

### Renderers

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **9.0.7** | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **9.0.5** | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.0 |

### AI Platform

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.6** | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.2 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.1 processes and configurations

### What's included in 5.1.2

This maintenance release includes:

* **Bug fixes** addressing customer-reported issues
* **Stability improvements** for platform reliability
* **Quality enhancements** identified through internal testing

For detailed information on all changes, see the [FlowX.AI 5.1.2 Release Notes](./v5.1.2-december-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.2 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.2 | PostgreSQL | 16 - 17 |
| 5.1.2 | Oracle Database | 21c, 23ai |
| 5.1.2 | MongoDB | 7 - 8 |
| 5.1.2 | Redis | 7.4 - 8.0 |
| 5.1.2 | Elasticsearch | 8 |
| 5.1.2 | Angular (Web SDK) | 19.x |
| 5.1.2 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.3 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.2 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.2 → 5.1.3**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **process-engine** | **9.70.1** | 9.67.0 | 9.64.3 | 9.63.0 |
| **admin** | **9.70.2** | 9.68.1 | 9.66.5 | 9.65.0 |
| **designer** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **cms-core** | **9.41.1** | 9.39.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **9.30.1** | 9.28.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **9.31.2** | 9.29.0 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **9.34.1** | 9.32.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **9.39.1** | 9.37.1 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **9.38.2** | 9.36.1 | 9.34.2 | 9.33.0 |
| **data-search** | **9.27.1** | 9.25.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **9.35.1** | 9.33.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **9.30.2** | 9.28.0 | 9.25.1 | 9.24.0 |
| **integration-designer** | **9.54.1** | 9.52.1 | 9.50.0 | 9.49.1 |
| **application-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **data-sync** | **9.28.1** | 9.26.0 | 9.22.1 | 9.21.0 |
| **authorization-system** | **9.38.1** | 9.36.1 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **9.26.1** | 9.24.1 | 9.22.1 | 9.21.0 |

### Renderers

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **9.0.8** | 9.0.7 | 9.0.5 | 9.0.4 |
| **Android renderer** | **9.0.6** | 9.0.5 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.7** | 9.2.6 | 9.2.5 | 9.2.4 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.3 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes required\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.2 processes and configurations

### Optional configuration

A new optional environment variable is available for process-engine:

| Variable | Description | Default |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from platform components | Falls back to `KAFKA_TOPIC_PATTERN` |

> [!NOTE]
>
> This allows connectors to use custom topic patterns without affecting other components like document-plugin, data-search, and cms-core that use `ai.flowx.engine.receive.*`.

### What's included in 5.1.3

This maintenance release includes:

* **Security fixes**
* **Bug fixes** addressing customer-reported issues

For detailed information on all changes, see the [FlowX.AI 5.1.3 Release Notes](./v5.1.3-january-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.3 | Keycloak | 26+ |
| 5.1.3 | Kafka | 3.8 - 3.9 |
| 5.1.3 | PostgreSQL | 16 - 17 |
| 5.1.3 | Oracle Database | 21c, 23ai |
| 5.1.3 | MongoDB | 7 - 8 |
| 5.1.3 | Redis | 7.4 - 8.0 |
| 5.1.3 | Elasticsearch | 8 |
| 5.1.3 | Angular (Web SDK) | 19.2 |
| 5.1.3 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.4 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.3 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.3 → 5.1.4**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **process-engine** | **9.72.2** | 9.70.1 | 9.67.0 | 9.64.3 |
| **admin** | **9.72.0** | 9.70.2 | 9.68.1 | 9.66.5 |
| **designer** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **cms-core** | **9.43.1** | 9.41.1 | 9.39.0 | 9.36.3 |
| **scheduler-core** | **9.32.0** | 9.30.1 | 9.28.1 | 9.26.1 |
| **events-gateway** | **9.33.0** | 9.31.2 | 9.29.0 | 9.26.1 |
| **notification-plugin** | **9.36.0** | 9.34.1 | 9.32.0 | 9.29.1 |
| **document-plugin** | **9.41.1** | 9.39.1 | 9.37.1 | 9.35.1 |
| **task-management-plugin** | **9.40.0** | 9.38.2 | 9.36.1 | 9.34.2 |
| **data-search** | **9.29.0** | 9.27.1 | 9.25.1 | 9.23.1 |
| **audit-core** | **9.37.0** | 9.35.1 | 9.33.0 | 9.30.1 |
| **advancing-controller** | **9.32.0** | 9.30.2 | 9.28.0 | 9.25.1 |
| **integration-designer** | **9.56.0** | 9.54.1 | 9.52.1 | 9.50.0 |
| **application-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **runtime-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **data-sync** | **9.30.1** | 9.28.1 | 9.26.0 | 9.22.1 |
| **authorization-system** | **9.40.1** | 9.38.1 | 9.36.1 | 9.34.2 |
| **nosql-db-runner** | **9.28.0** | 9.26.1 | 9.24.1 | 9.22.1 |

### Renderers

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **iOS renderer** | **9.0.9** | 9.0.8 | 9.0.7 | 9.0.5 |
| **Android renderer** | **9.0.7** | 9.0.6 | 9.0.5 | 9.0.3 |

### Plugins

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.8** | 9.2.7 | 9.2.6 | 9.2.5 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.4 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.3 processes and configurations

#### New environment variables (optional)

The following optional environment variables have been added for the **process-engine** to configure config params caching:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120` | process-engine |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache | `500` | process-engine |

> [!NOTE]
>
> These variables are optional. If not configured, the default values will be used. Adjust these values based on how frequently your configuration changes and your memory constraints.
>
> For more details, see [Engine Setup - Config params cache](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).

### What's included in 5.1.4

This maintenance release includes:

* **Security patches** addressing identified vulnerabilities
* **Bug fixes** addressing customer-reported issues
* **Platform improvements** including cache improvements, Kafka environment variable alignment, SSE metrics enhancements, and infrastructure updates

For detailed information on all changes, see the [FlowX.AI 5.1.4 Release Notes](./v5.1.4-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.4 | Keycloak | 26+ |
| 5.1.4 | Kafka | 3.8 - 3.9 |
| 5.1.4 | PostgreSQL | 16 - 17 |
| 5.1.4 | Oracle Database | 21c, 23ai |
| 5.1.4 | MongoDB | 7 - 8 |
| 5.1.4 | Redis | 7.4 - 8.0 |
| 5.1.4 | Elasticsearch | 8 |
| 5.1.4 | Angular (Web SDK) | 19.2 |
| 5.1.4 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.5 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.4 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.4 → 5.1.5**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **process-engine** | **9.72.5** | 9.72.2 | 9.70.1 | 9.67.0 |
| **admin** | **9.72.2** | 9.72.0 | 9.70.2 | 9.68.1 |
| **designer** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **cms-core** | **9.43.3** | 9.43.1 | 9.41.1 | 9.39.0 |
| **scheduler-core** | **9.32.2** | 9.32.0 | 9.30.1 | 9.28.1 |
| **events-gateway** | **9.33.2** | 9.33.0 | 9.31.2 | 9.29.0 |
| **notification-plugin** | **9.36.2** | 9.36.0 | 9.34.1 | 9.32.0 |
| **document-plugin** | **9.41.3** | 9.41.1 | 9.39.1 | 9.37.1 |
| **task-management-plugin** | **9.40.2** | 9.40.0 | 9.38.2 | 9.36.1 |
| **data-search** | **9.29.2** | 9.29.0 | 9.27.1 | 9.25.1 |
| **audit-core** | **9.37.2** | 9.37.0 | 9.35.1 | 9.33.0 |
| **advancing-controller** | **9.32.1** | 9.32.0 | 9.30.2 | 9.28.0 |
| **integration-designer** | **9.56.2** | 9.56.0 | 9.54.1 | 9.52.1 |
| **application-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **runtime-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **data-sync** | **9.30.2** | 9.30.1 | 9.28.1 | 9.26.0 |
| **authorization-system** | **9.40.2** | 9.40.1 | 9.38.1 | 9.36.1 |
| **nosql-db-runner** | **9.28.2** | 9.28.0 | 9.26.1 | 9.24.1 |

### Renderers

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **iOS renderer** | **9.0.10** | 9.0.9 | 9.0.8 | 9.0.7 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.6 | 9.0.5 |

### Plugins

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.9** | 9.2.8 | 9.2.7 | 9.2.6 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.5 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No new environment variables
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.4 processes and configurations

### What's included in 5.1.5

This maintenance release includes:

* **Bug fixes** for process loop rendering issues in the Angular renderer
* **Bug fixes** for subprocess output data not being returned from embedded processes

For detailed information on all changes, see the [FlowX.AI 5.1.5 Release Notes](./v5.1.5-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.5 | Keycloak | 26+ |
| 5.1.5 | Kafka | 3.8 - 3.9 |
| 5.1.5 | PostgreSQL | 16 - 17 |
| 5.1.5 | Oracle Database | 21c, 23ai |
| 5.1.5 | MongoDB | 7 - 8 |
| 5.1.5 | Redis | 7.4 - 8.0 |
| 5.1.5 | Elasticsearch | 8 |
| 5.1.5 | Angular (Web SDK) | 19.2 |
| 5.1.5 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.6 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.5 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.5 → 5.1.6**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **process-engine** | **9.72.7** | 9.72.5 | 9.72.2 | 9.70.1 |
| **admin** | **9.72.4** | 9.72.2 | 9.72.0 | 9.70.2 |
| **designer** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **cms-core** | **9.43.5** | 9.43.3 | 9.43.1 | 9.41.1 |
| **scheduler-core** | **9.32.4** | 9.32.2 | 9.32.0 | 9.30.1 |
| **events-gateway** | **9.33.4** | 9.33.2 | 9.33.0 | 9.31.2 |
| **notification-plugin** | **9.36.4** | 9.36.2 | 9.36.0 | 9.34.1 |
| **document-plugin** | **9.41.5** | 9.41.3 | 9.41.1 | 9.39.1 |
| **task-management-plugin** | **9.40.4** | 9.40.2 | 9.40.0 | 9.38.2 |
| **data-search** | **9.29.4** | 9.29.2 | 9.29.0 | 9.27.1 |
| **audit-core** | **9.37.4** | 9.37.2 | 9.37.0 | 9.35.1 |
| **advancing-controller** | **9.32.3** | 9.32.1 | 9.32.0 | 9.30.2 |
| **integration-designer** | **9.56.3** | 9.56.2 | 9.56.0 | 9.54.1 |
| **application-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **runtime-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **data-sync** | **9.30.4** | 9.30.2 | 9.30.1 | 9.28.1 |
| **authorization-system** | **9.40.3** | 9.40.2 | 9.40.1 | 9.38.1 |
| **nosql-db-runner** | **9.28.4** | 9.28.2 | 9.28.0 | 9.26.1 |

### Renderers

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **iOS renderer** | **9.0.11** | 9.0.10 | 9.0.9 | 9.0.8 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.7 | 9.0.6 |

### Plugins

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.8 | 9.2.7 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.6 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> This release introduces optional environment variables for the process engine retry mechanism. These are not required — defaults work for most deployments.

#### Process engine — retry configuration (optional)

The following optional environment variables configure the exponential backoff with Equal Jitter strategy used for optimistic locking retries:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` | process-engine |

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.5 processes and configurations

### What's included in 5.1.6

This maintenance release includes:

* **Bug fixes** for React renderer: modals, sliders, datepicker, selectors, disabled state, and accessibility
* **Bug fixes** for Angular + React renderer: card accordion height, focus outlines, button icon layout
* **Bug fix** for process engine advancing getting stuck on pod crash
* **Bug fix** for connection leak in application-manager export/import
* **Improvement** for configurable retry mechanism with exponential backoff
* **Security patches** across all platform components

For detailed information on all changes, see the [FlowX.AI 5.1.6 Release Notes](./v5.1.6-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.6 | Keycloak | 26+ |
| 5.1.6 | Kafka | 3.8 - 3.9 |
| 5.1.6 | PostgreSQL | 16 - 17 |
| 5.1.6 | Oracle Database | 21c, 23ai |
| 5.1.6 | MongoDB | 7 - 8 |
| 5.1.6 | Redis | 7.4 - 8.0 |
| 5.1.6 | Elasticsearch | 8 |
| 5.1.6 | Angular (Web SDK) | 19.2 |
| 5.1.6 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.7
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.7 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.6 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.6 → 5.1.7**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **process-engine** | **9.73.1** | 9.72.7 | 9.72.5 | 9.72.2 |
| **admin** | **9.73.1** | 9.72.4 | 9.72.2 | 9.72.0 |
| **designer** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **cms-core** | **9.44.2** | 9.43.5 | 9.43.3 | 9.43.1 |
| **scheduler-core** | **9.33.1** | 9.32.4 | 9.32.2 | 9.32.0 |
| **events-gateway** | **9.34.1** | 9.33.4 | 9.33.2 | 9.33.0 |
| **notification-plugin** | **9.37.1** | 9.36.4 | 9.36.2 | 9.36.0 |
| **document-plugin** | **9.42.2** | 9.41.5 | 9.41.3 | 9.41.1 |
| **task-management-plugin** | **9.41.1** | 9.40.4 | 9.40.2 | 9.40.0 |
| **data-search** | **9.30.1** | 9.29.4 | 9.29.2 | 9.29.0 |
| **audit-core** | **9.38.1** | 9.37.4 | 9.37.2 | 9.37.0 |
| **advancing-controller** | **9.33.1** | 9.32.3 | 9.32.1 | 9.32.0 |
| **integration-designer** | **9.57.1** | 9.56.3 | 9.56.2 | 9.56.0 |
| **application-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **runtime-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **data-sync** | **9.31.1** | 9.30.4 | 9.30.2 | 9.30.1 |
| **authorization-system** | **9.41.1** | 9.40.3 | 9.40.2 | 9.40.1 |
| **nosql-db-runner** | **9.29.1** | 9.28.4 | 9.28.2 | 9.28.0 |

### Renderers

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **iOS renderer** | **9.0.12** | 9.0.11 | 9.0.10 | 9.0.9 |
| **Android renderer** | **9.0.13** | 9.0.7 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI Platform

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.8 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.7 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.6 processes and configurations

### What's included in 5.1.7

This maintenance release includes:

* **Bug fix** for build reimport failures with manifest issues
* **Security patches** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.7 Release Notes](./v5.1.7-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.7 | Keycloak | 26+ |
| 5.1.7 | Kafka | 3.8 - 3.9 |
| 5.1.7 | PostgreSQL | 16 - 17 |
| 5.1.7 | Oracle Database | 21c, 23ai |
| 5.1.7 | MongoDB | 7 - 8 |
| 5.1.7 | Redis | 7.4 - 8.0 |
| 5.1.7 | Elasticsearch | 8 |
| 5.1.7 | Angular (Web SDK) | 19.2 |
| 5.1.7 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.8
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.8 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.7 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.7 → 5.1.8**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **process-engine** | **9.74.4** | 9.73.1 | 9.72.7 | 9.72.5 |
| **admin** | **9.74.4** | 9.73.1 | 9.72.4 | 9.72.2 |
| **designer** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **cms-core** | **9.45.4** | 9.44.2 | 9.43.5 | 9.43.3 |
| **scheduler-core** | **9.34.4** | 9.33.1 | 9.32.4 | 9.32.2 |
| **events-gateway** | **9.35.4** | 9.34.1 | 9.33.4 | 9.33.2 |
| **notification-plugin** | **9.38.4** | 9.37.1 | 9.36.4 | 9.36.2 |
| **document-plugin** | **9.43.4** | 9.42.2 | 9.41.5 | 9.41.3 |
| **task-management-plugin** | **9.42.4** | 9.41.1 | 9.40.4 | 9.40.2 |
| **data-search** | **9.31.4** | 9.30.1 | 9.29.4 | 9.29.2 |
| **audit-core** | **9.39.4** | 9.38.1 | 9.37.4 | 9.37.2 |
| **advancing-controller** | **9.34.4** | 9.33.1 | 9.32.3 | 9.32.1 |
| **integration-designer** | **9.58.5** | 9.57.1 | 9.56.3 | 9.56.2 |
| **application-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **runtime-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **data-sync** | **9.32.3** | 9.31.1 | 9.30.4 | 9.30.2 |
| **authorization-system** | **9.42.4** | 9.41.1 | 9.40.3 | 9.40.2 |
| **nosql-db-runner** | **9.30.4** | 9.29.1 | 9.28.4 | 9.28.2 |

### Renderers

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **iOS renderer** | **9.0.19** | 9.0.12 | 9.0.11 | 9.0.10 |
| **Android renderer** | **9.0.19** | 9.0.13 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.8 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.7 processes and configurations

### What's included in 5.1.8

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.8 Release Notes](./v5.1.8-april-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.8 | Keycloak | 26+ |
| 5.1.8 | Kafka | 3.8 - 3.9 |
| 5.1.8 | PostgreSQL | 16 - 17 |
| 5.1.8 | Oracle Database | 21c, 23ai |
| 5.1.8 | MongoDB | 7 - 8 |
| 5.1.8 | Redis | 7.4 - 8.0 |
| 5.1.8 | Elasticsearch | 8 |
| 5.1.8 | Angular (Web SDK) | 19.2 |
| 5.1.8 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.9
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.9 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.8 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.8 → 5.1.9**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **process-engine** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.7 |
| **admin** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.4 |
| **designer** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **cms-core** | **9.46.2** | 9.45.4 | 9.44.2 | 9.43.5 |
| **scheduler-core** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.4 |
| **events-gateway** | **9.36.2** | 9.35.4 | 9.34.1 | 9.33.4 |
| **notification-plugin** | **9.39.2** | 9.38.4 | 9.37.1 | 9.36.4 |
| **document-plugin** | **9.44.2** | 9.43.4 | 9.42.2 | 9.41.5 |
| **task-management-plugin** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.4 |
| **data-search** | **9.32.2** | 9.31.4 | 9.30.1 | 9.29.4 |
| **audit-core** | **9.40.2** | 9.39.4 | 9.38.1 | 9.37.4 |
| **advancing-controller** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.3 |
| **integration-designer** | **9.59.3** | 9.58.5 | 9.57.1 | 9.56.3 |
| **application-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **runtime-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **data-sync** | **9.33.2** | 9.32.3 | 9.31.1 | 9.30.4 |
| **authorization-system** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.3 |
| **nosql-db-runner** | **9.31.2** | 9.30.4 | 9.29.1 | 9.28.4 |

### Renderers

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **iOS renderer** | **9.0.20** | 9.0.19 | 9.0.12 | 9.0.11 |
| **Android renderer** | **9.0.24** | 9.0.19 | 9.0.13 | 9.0.7 |

### Plugins

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.9 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.8 processes and configurations

### What's included in 5.1.9

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.9 Release Notes](./v5.1.9-may-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.9 | Keycloak | 26+ |
| 5.1.9 | Kafka | 3.8 - 3.9 |
| 5.1.9 | PostgreSQL | 16 - 17 |
| 5.1.9 | Oracle Database | 21c, 23ai |
| 5.1.9 | MongoDB | 7 - 8 |
| 5.1.9 | Redis | 7.4 - 8.0 |
| 5.1.9 | Elasticsearch | 8 - 9 |
| 5.1.9 | Angular (Web SDK) | 19.2 |
| 5.1.9 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/deployment-guidelines-v5.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.63.0** | 9.29.2 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.65.0** | 9.25.2 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.35.0** | 9.21.2 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.28.0** | 9.14.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.34.0** | 9.17.2 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.33.0** | 9.14.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.22.0** | 9.12.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.29.1** | 9.15.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.24.0** | 9.11.0 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.49.1** | 9.26.2 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.21.0** | 9.11.0 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.33.0** | 9.14.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.21.0** | 9.11.0 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.4** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.2** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | **0.2.4** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.4** | 9.2.3 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.3.1** | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.0 | Keycloak | 26+ |
| 5.1.0 | Kafka | 3.8 - 3.9 |
| 5.1.0 | PostgreSQL | 16 - 17 |
| 5.1.0 | Oracle Database | 21c, 23ai |
| 5.1.0 | MongoDB | 7 - 8 |
| 5.1.0 | Redis | 7.4 - 8.0 |
| 5.1.0 | Elasticsearch | 8 - 9 |
| 5.1.0 | Angular (Web SDK) | 19.x |
| 5.1.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/configuration-and-migration

This section contains the steps in order that we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](/5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.1.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.1.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.1.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The auth-system will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from app-manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Document plugin

> [!NOTE]
>
> New configuration option for test documents bucket customization.

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILE_STORAGE_TEST_FILES_BUCKET` | `-test-documents` | Overrides the default test documents bucket suffix. Use this to configure a custom bucket name for test files. |

> [!NOTE]
>
> This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed.

## Kafka configuration

> [!NOTE]
>
> Complete Kafka migration including consumer group standardization to kebab-case, comprehensive topic restructuring with new versioned naming patterns, and enhanced messaging features across all FlowX.AI services.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group migrations

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Kafka topic migrations

> [!NOTE]
>
> All Kafka topics migrate to versioned naming pattern `ai.flowx.{env}.{service}.{operation}.v1` for improved organization and future compatibility.

> [tab] Application Manager
>
> **Application resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
>
> **Sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS_IN` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE_IN` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE_IN` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN` | `ai.flowx.application-version.sync.out.v1` |
>
> **Resource update propagation:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | `ai.flowx.application-version.resource.update.propagation.v1` |
>
> **Build resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

> [tab] Admin
>
> **Consumer groups:**
>
> | Environment Variable | New Consumer Group | Threads |
> | - | - | - |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_SYNC` | `process-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC` | `business-rule-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC` | `reusable-template-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION` | `processCorrectionAfterAppOperationGroup` | `6` |
>
> **Application sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE` | `ai.flowx.application-version.sync.out.v1` |
> | `KAFKA_TOPIC_APPLICATION_PROCESS_SYNC` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
>
> **Application correction after app operation topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
>
> **Build topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

### New Kafka features

> [card] Resource Update Propagation
>
> **Consumer Group:** `app-resource-update-propagation-group`\
> **Threads:** 3\
> **Topic:** `ai.flowx.{env}.application-version.resource.update.propagation.v1`\
> **Purpose:** Real-time resource change propagation

> [card] Build Runtime Data
>
> **Consumer Group:** `build-runtime-data-group`\
> **Threads:** 2\
> **Topic:** `ai.flowx.{env}.build.runtime-data.v1`\
> **Purpose:** Build process data management

> [card] Business Rule Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> **Purpose:** Enhanced business rule synchronization\
> **Consumer Group:** `business-rule-sync-group`

> [card] Process Sync Enhanced
>
> **Topic:** `ai.flowx.{env}.application-version.sync.process.in.v1`\
> **Purpose:** Improved process synchronization\
> **Consumer Group:** `process-sync-group`

> [card] Reusable Template Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> **Purpose:** Template synchronization\
> **Consumer Group:** `reusable-template-sync-group`

> [card] Correction After App Operation
>
> **Multiple Topics:** Process, business rule, and template correction\
> **Purpose:** Post-deployment resource correction\
> **Consumer Group:** `processCorrectionAfterAppOperationGroup`

### Configure environment variables

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides. Only override when custom naming is required.

```bash Application Manager Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Sync Topics
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
```

```bash Admin Topics theme={"dark"}
# Application Sync
KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE=ai.flowx.dev.application-version.sync.out.v1
KAFKA_TOPIC_APPLICATION_PROCESS_SYNC=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT=ai.flowx.dev.application-version.correction-after-app-operation.response.v1
```

```bash Consumer Groups and Threads theme={"dark"}
# Application Manager Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Admin Consumer Groups  
KAFKA_CONSUMER_GROUPID_PROCESS_SYNC=process-sync-group
KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC=business-rule-sync-group
KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC=reusable-template-sync-group
KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION=processCorrectionAfterAppOperationGroup

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
KAFKA_CONSUMER_THREADS_PROCESS_SYNC=6
KAFKA_CONSUMER_THREADS_BUSINESS_RULE_SYNC=6
KAFKA_CONSUMER_THREADS_REUSABLE_TEMPLATE_SYNC=6
KAFKA_CONSUMER_THREADS_PROCESS_CORRECTIONAFTERAPPOPERATION=6
```

### Additional Application Manager variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | Maximum HTTP request header size |

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | Redis host |
| `SPRING_REDIS_PORT` | `6379` | Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | Redis password |
| `SPRING_REDIS_TTL` | `5000000` | Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | Redis host |

## FlowX Engine

> [!NOTE]
>
> The ADVANCING controller has been redesigned with separate picking and processing operations for improved performance and resource management.

### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.

### Elasticsearch indexing configuration

> [!NOTE]
>
> Elasticsearch indexing environment variables have been updated with new naming conventions for better consistency with FlowX naming standards.

#### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEXING_TYPE` | `FLOWX_INDEXING_TYPE` | `kafka` | `kafka` |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` | `process_instance` |
| `FLOWX_INDEXING_PROCESSINSTANCE_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `FLOWX_INDEXING_PROCESSINSTANCE_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

> [!NOTE]
>
> For complete Elasticsearch indexing setup including Kafka Connect configuration and time-based partitioning, see the [Configuring Elasticsearch indexing](/5.1/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing) guide.

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.

### Development environment exception

> [!NOTE]
>
> For development environments only, `CONFIG_PROFILE` migrates to the standard Spring configuration profile variable.

| Remove This Variable | Replace With | Environment |
| - | - | - |
| `CONFIG_PROFILE` | `SPRING_CONFIG_PROFILE` | devenv only |

## SpiceDB integration

> [!NOTE]
>
> FlowX.AI 5.1 introduces SpiceDB integration for enhanced authorization capabilities across all core services.

### Services affected

The following services require new SpiceDB configuration variables:

* Admin
* Application Manager
* Audit Core
* CMS Core
* Document Plugin
* Integration Designer
* Notification Plugin
* Process Engine
* Runtime Manager
* Task Management Plugin

### New variables to add

For every CAS configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_SPICEDB_TOKEN` | *(secret)* | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Data sync updates

### Data Sync additional variables

For every Data-Sync configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_URL` | - | Authentication system URL. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME` | - | Authentication system username. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` | - | Authentication system password. |
| `FLOWX_SPICEDB_TOKEN` | - | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Kafka topic naming

### Global configuration change

| Variable | Old Default | New Default | Description |
| - | - | - | - |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | (varies) | `""` | Moved to default empty environment |

> [!NOTE]
>
> This change standardizes topic naming across environments by defaulting to an empty environment identifier.

## CORS and ingress updates

> [!WARNING]
>
> All services with Kubernetes ingress configurations now require the `Fx-Workspace-Id` header for workspace identification in multi-tenant environments.

### Standard ingress pattern

FlowX.AI v5.1 introduces a standardized ingress configuration pattern for all services. The key change is adding the `Fx-Workspace-Id` header to the CORS configuration.

**Required annotation update:**

```yaml theme={"dark"}
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
```

### Services requiring updates

All FlowX.AI services that expose ingress endpoints require this update:

| Service | Fx-Workspace-Id Required | Reference |
| - | - | - |
| Admin | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Application Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Audit Core | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Authorization System | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Events Gateway | ❌ No (SSE) | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) |
| Integration Designer | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Process Engine | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Runtime Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Task Management | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |

> [card] [Complete Ingress Configuration Guide](../../../../../5.1/setup-guides/ingress-configuration)
>
> View the complete ingress configuration pattern including:
>
> * Standard template for all services
> * Service-specific paths and rewrite rules
> * Annotation explanations
> * Troubleshooting guide
> * Environment-specific customization

> [!NOTE]
>
> **Exception:** Events Gateway does not require the `Fx-Workspace-Id` header because it handles Server-Sent Events (SSE) with different security requirements. See the [Events Gateway exception](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) section for details.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/install-services

Step-by-step installation guide for new FlowX.AI 5.1.0 services

FlowX.AI 5.1.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](../../../../../5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](../../../../../5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.

> [!WARNING]
>
> **Continuing to 5.9.x?** If 5.1.x is only an intermediate stop on your path to 5.9.x, land on the **latest available 5.1.x patch**, not 5.1.0. Data migrations and their fixes accumulate across the patches of the family, and the latest patch is the level guaranteed to carry all of them. Before starting the next migration, confirm the environment is fully functional: every service up and healthy in **FlowX.AI Designer → Platform Status**, and the data-sync job completed successfully. See the [5.1 → 5.9 migration prerequisites](/5.9/migrating-from-5.1-lts/prerequisites).

## Success factors

> [!WARNING]
>
> Take care when following the steps below are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB and DGraph** must be installed before any FlowX.AI services
>
> > [!NOTE]
> >
> > DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices (data migration)** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration (Elasticsearch indices)

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation

> [card] [Troubleshooting](./troubleshooting)
>
> Common issues and solutions for post-upgrade problems


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/prerequisites

This section contains the steps in order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.8 | FlowX.AI 5.1.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.1#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.1.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip this step.

> [card] [SpiceDB setup guide](../../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.1.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

> [!WARNING]
>
> Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.1.0 to ensure workspace functionality works correctly.

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Prerequisites for migration

Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:

```json theme={"dark"}
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
```

This mapping update is required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable, if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

### Post-migration impact

**Without proper Elasticsearch migration, you will experience:**

* Some process instances may not appear in search results
* Data-search functionality may not return complete results
* Workspace-scoped queries will fail for unmigrated data
* **Existing resources will not be visible or accessible within the new workspace structure**

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.1.0.

***

## Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).

Details on how to configure the organization admin user:

> [card] [Authorization system](../../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Workspaces access rights](../../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

***

#### Pre-migration preparation

You must configure the authorization-system service before migration. There are two supported approaches:

> [tab] Recommended: Use admin email (simpler)
>
> Set the following authorization-system environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=<username-of-admin-user>`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.

> [tab] Alternative: Use admin subject ID
>
> Set the following environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
>
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=<subject-id-of-admin-user>`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).
>
> > [!TIP]
> >
> > To get the subject ID of the admin user, extract it from the JWT token of the admin user.
>
> ![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.1.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users",
      "manage-realm"
    ]
  }
}
```

***

## Process instances migration

All active process instances will be migrated under default workspace.

> [!WARNING]
>
> For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.1.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.2") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.2 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.2 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.2 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.2 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.2 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# Post-upgrade troubleshooting
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/troubleshooting

Common issues and solutions that may occur after upgrading from FlowX v4.7.x to v5.1.0.

This section covers common issues that may occur after completing the upgrade to FlowX.AI 5.1.0 and their solutions.

## Designer login issues

### DataIntegrityViolationException error

If you cannot login to FlowX Designer after the 5.x upgrade and encounter the following error in the authorization-system logs:

```
org.springframework.dao.DataIntegrityViolationException: could not execute statement [ERROR: duplicate key value violates unique constraint "cas_user_username_key"
  Detail: Key (username)=(admin@flowx.ai) already exists.] [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; SQL [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; constraint [cas_user_username_key]
```

**Root Cause**: This error occurs because the `sub` (subject ID) is missing from JWT tokens. Starting with Keycloak version 25, the `sub` claim is not added by default to lightweight access tokens.

**Solution**: Ensure the `basic` Client Scope is created in your Keycloak Realm and added to all FlowX clients.

> [!WARNING]
>
> Since Keycloak version 25, the `sub` claim is not added by default to JWT lightweight tokens. This is a breaking change that affects FlowX.AI authentication.

### How to verify if subject ID is missing

**1. Login attempt**

Try to login to FlowX Designer and note if the login fails.

**2. Capture the token**

1. Open your browser's Developer Tools
2. Navigate to the **Network** tab
3. Attempt to login again
4. Look for a call to: `https://<your-keycloak-address>/auth/realms/flowx/protocol/openid-connect/token`
5. Copy the access token from the response

**3. Decode the token**

1. Go to [https://jwt.io/](https://jwt.io/)
2. Paste the token in the **Encoded** section
3. Check the **Payload** section for the presence of the `sub` claim

> [!TIP]
>
> If the `sub` claim is present, the token should contain a field like: `"sub": "12345678-1234-1234-1234-123456789abc"`

**4. Verify Client Scope configuration**

If the `sub` claim is missing, you need to configure the Client Scope in Keycloak:

1. Login to your Keycloak Admin Console
2. Navigate to your FlowX realm
3. Go to **Client Scopes**
4. Ensure the `basic` client scope exists and includes the `sub` claim
5. Add this client scope to all FlowX clients (FlowX Designer, Admin, etc.)

### Additional resources

> [card] [Keycloak Release Notes](https://www.keycloak.org/docs/latest/release_notes/#lightweight-access-token-to-be-even-more-lightweight)
>
> Official Keycloak documentation about lightweight access token changes

***

## Other common issues

> [!NOTE]
>
> Additional troubleshooting sections will be added as common post-upgrade issues are identified. If you encounter issues not covered here, please consult the FlowX support team.


# FlowX.AI 5.1.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025

Introducing Workspaces, Project Data Model, Library-to-Library Dependencies, Data Mappers, Reusable Resources, and more for a more efficient and flexible development experience.

**What's new? 🆕**

> [tab] Reusability
>
> Build once, use everywhere. These features transform how you develop and maintain applications by eliminating duplication and enabling sophisticated modular architectures.
>
> 🔄 [**Project Data Model (PDM)**](#project-data-model-pdm) - Define reusable data types at the project level to ensure consistency across processes\
> 🔄 [**Library-to-Library Dependencies**](#library-to-library-dependencies) - Create complex dependency trees with multiple levels of library-to-library relationships\
> 🔄 [**Data Mappers**](#data-mappers) - Visual drag-and-drop data mapping with reusable parameter definitions\
> 🔄 [**Reusable Resources**](#reusable-resources) - Create and manage UI Templates and Business Functions across multiple processes\
> 🔄 [**Files in Integration Designer**](#files-in-integration-designer) - Enhanced file management and reusability in integration workflows\
> 🔄 [**Resources Overrides**](#resources-overrides) - Localization and customization of core applications across multiple regions with centralized management\
> 🔄 [**Active Policy Overrides**](#active-policy-overrides) - User-specific and role-specific deployment policies for independent testing and controlled rollouts
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.1.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.1.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> ***
>
> ### **Files in Integration Designer**
>
> > [card] Files in Integration Designer
> >
> > > [tab] Files Overview
> > >
> > > ![Integration Designer file workflows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh.png)
> > >
> > > FlowX.AI 5.1.0 introduces comprehensive file handling capabilities in Integration Designer, resolving previous limitations where sending or receiving documents, photos, or any files via Integration Designer was not supported. This powerful enhancement enables seamless file exchange with external systems through automated workflows.
> >
> > > [tab] Core File Scenarios
> > >
> > > > [card] File Downloads
> > > >
> > > > Process calls external API (GET/POST) and receives files in response. Integration Designer saves files to specified location and returns paths to workflow
> > >
> > > > [card] File Uploads
> > > >
> > > > Process sends files stored in Document Plugin or S3 Bucket to external API via POST request. Workflow transmits file path for seamless transfer
> > >
> > > > [card] Document Plugin Integration
> > > >
> > > > Seamless integration with FlowX.AI Document Plugin for process-specific file management and organization
> > >
> > > > [card] S3 Storage Support
> > > >
> > > > Custom S3 bucket storage for files not tied to specific process instances or when Document Plugin is unavailable
> >
> > > [tab] Enhanced Capabilities
> > >
> > > **1. Automated File Exchange**
> > >
> > > Enable seamless file transfer with external systems without manual handling or complex custom integrations
> > >
> > > **2. Flexible Storage Options**
> > >
> > > Choose between Document Plugin for process-specific files or S3 Protocol for independent file operations
> > >
> > > **3. Workflow Integration**
> > >
> > > Files are automatically integrated into workflow processes with proper path management and metadata handling
> > >
> > > **4. External Service Communication**
> > >
> > > Communicate effectively with document services, AI processing systems, report generators, and CMS platforms
> >
> > > [tab] Real-World Use Cases
> > >
> > > > [accordion] Contract Generation Workflows
> > > >
> > > > **Scenario**: Generate personalized contracts using external document services
> > > >
> > > > * **Process Flow**: Send customer data → External contract service → Receive generated PDF contract
> > > > * **Integration**: Customer information flows to document generation API, completed contracts return to process
> > > > * **Storage**: Generated contracts stored in Document Plugin for process tracking and audit trails
> > > > * **Business Value**: Automated contract creation with legal template compliance and version control
> > >
> > > > [accordion] Document Processing & OCR
> > > >
> > > > **Scenario**: Process uploaded documents through external AI/OCR services
> > > >
> > > > * **Process Flow**: Upload document → AI processing service → Receive extracted data and processed files
> > > > * **Integration**: Documents sent to AI services for text extraction, classification, or compliance validation
> > > > * **Storage**: Processed documents and extracted data stored for business logic processing
> > > > * **Business Value**: Automated document processing with intelligent data extraction capabilities
> > >
> > > > [accordion] Report Generation & Analytics
> > > >
> > > > **Scenario**: Generate business reports using external reporting services
> > > >
> > > > * **Process Flow**: Send business data → Reporting service → Receive formatted reports (PDF, Excel)
> > > > * **Integration**: Business metrics and KPIs sent to specialized reporting engines
> > > > * **Storage**: Generated reports available for download and distribution workflows
> > > > * **Business Value**: Professional report generation with advanced formatting and visualization capabilities
> > >
> > > > [accordion] CMS & Content Management
> > > >
> > > > **Scenario**: Integrate with content management systems for file organization
> > > >
> > > > * **Process Flow**: Upload files → CMS integration → Organize and categorize content
> > > > * **Integration**: Files uploaded to external CMS platforms with metadata and categorization
> > > > * **Storage**: S3 Protocol ideal for CMS integrations with unassociated documents
> > > > * **Business Value**: Centralized content management with automated workflow integration
> >
> > [Learn more about Integration Designer](../../../../5.1/docs/platform-deep-dive/integrations/integration-designer)
> >
> > Major Enhancement
>
> ***
>
> ### **Resources Overrides**
>
> > [card] Resources Overrides
> >
> > > [tab] Resources Overrides Overview
> > >
> > > ![Resources Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
> > >
> > > Resources Overrides enable localization and customization of core business applications across multiple regions while maintaining centralized updates from headquarters. This powerful feature allows organizations to adapt specific business logic, compliance requirements, or local regulations without losing connection to the master application.
> >
> > > [tab] Key Features
> > >
> > > > [card] Localization Control
> > > >
> > > > Customize processes, workflows, and enumerations for different countries or regions while maintaining core functionality
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all resource overrides through the Dependencies page with comprehensive override tracking and configuration
> > >
> > > > [card] Selective Overriding
> > > >
> > > > Override only specific resources that need localization while inheriting all other updates from the main library
> > >
> > > > [card] Export/Import Support
> > > >
> > > > Automatically include override configurations in project exports and imports for seamless environment management
> >
> > > [tab] Business Benefits
> > >
> > > **1. Accelerate Global Expansion**
> > >
> > > Deploy core applications to new regions quickly by overriding only country-specific elements instead of rebuilding from scratch
> > >
> > > **2. Maintain Compliance**
> > >
> > > Adapt business logic and data handling to meet local regulatory requirements while preserving global standards
> > >
> > > **3. Preserve Investment**
> > >
> > > Continue receiving updates and improvements from headquarters without losing local customizations
> > >
> > > **4. Reduce Maintenance Overhead**
> > >
> > > Manage regional variations centrally instead of maintaining completely separate application instances
> >
> > > [tab] Supported Resource Types
> > >
> > > > [card] Process Overrides
> > > >
> > > > Customize business process logic while maintaining input/output compatibility and core workflow structure
> > >
> > > > [card] Workflow Overrides
> > > >
> > > > Replace entire workflow implementations to adapt business rules for local requirements
> > >
> > > > [card] Enumeration Overrides
> > > >
> > > > Localize value lists, dropdown options, and classification systems for regional variations
> > >
> > > > [card] Runtime Resolution
> > > >
> > > > Overrides are resolved dynamically at runtime, ensuring the correct regional version is always used
> >
> > > [tab] Real-World Applications
> > >
> > > > [accordion] Multi-National Banking
> > > >
> > > > **Scenario**: Global bank with country-specific loan approval processes
> > > >
> > > > * **Global Library**: Common loan application workflow with standard validation steps
> > > > * **Country Overrides**: Local credit scoring algorithms, regulatory compliance checks, documentation requirements
> > > > * **Business Value**: Single platform maintenance with automated compliance for each country's banking regulations
> > >
> > > > [accordion] Insurance Operations
> > > >
> > > > **Scenario**: Insurance company operating across different regulatory environments
> > > >
> > > > * **Global Library**: Standard claims processing workflow and policy management
> > > > * **Regional Overrides**: Country-specific coverage types, claim validation rules, regulatory reporting
> > > > * **Business Value**: Consistent global operations with local market adaptation and compliance
> > >
> > > > [accordion] Manufacturing & Supply Chain
> > > >
> > > > **Scenario**: Manufacturing company with different operational requirements per region
> > > >
> > > > * **Global Library**: Core production planning and inventory management processes
> > > > * **Local Overrides**: Regional supplier networks, compliance standards, environmental regulations
> > > > * **Business Value**: Standardized operations with flexibility for local business practices and regulations
> >
> > [Learn more about Resources Overrides](../../../../5.1/docs/projects/resources#resources-overrides)
> >
> > Major Enhancement
>
> ***
>
> ### **Active Policy Overrides**
>
> > [card] Active Policy Overrides
> >
> > > [tab] Active Policy Overrides Overview
> > >
> > > ![Active Policy Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap2.png)
> > >
> > > Active Policy Overrides enable user-specific and role-specific deployment policies that allow independent testing of different builds or branches without affecting the global policy. This powerful feature provides granular control over which project versions different users access in runtime environments.
> >
> > > [tab] Key Features
> > >
> > > > [card] User-Specific Policies
> > > >
> > > > Create individual policy overrides for specific users to test different builds independently
> > >
> > > > [card] Role-Based Overrides
> > > >
> > > > Apply policy overrides to entire roles for team-based testing and deployment strategies
> > >
> > > > [card] Priority-Based Resolution
> > > >
> > > > Handle conflicts when multiple overrides apply using configurable priority systems
> > >
> > > > [card] Real-Time Switching
> > > >
> > > > Switch between different project versions instantly without deployment downtime
> >
> > > [tab] Business Benefits
> > >
> > > **1. Independent Testing**
> > >
> > > Enable QA teams and developers to test different builds simultaneously without interfering with production users
> > >
> > > **2. Controlled Rollouts**
> > >
> > > Gradually deploy new features to specific user groups before full production release
> > >
> > > **3. Emergency Rollback**
> > >
> > > Quickly revert specific users to stable versions during incidents without affecting the entire system
> > >
> > > **4. Branch-Specific Development**
> > >
> > > Allow different teams to work with different development branches in shared environments
> >
> > > [tab] Override Management
> > >
> > > > [card] Policy Types
> > > >
> > > > Support for both "Latest on Branch" and specific "Build" policies with flexible branch and version selection
> > >
> > > > [card] Search & Filter
> > > >
> > > > Real-time search functionality to quickly locate specific user or role overrides
> > >
> > > > [card] Activation Control
> > > >
> > > > Enable or disable overrides without deletion for temporary testing scenarios
> > >
> > > > [card] Conflict Resolution
> > > >
> > > > Clear hierarchy: User overrides > Role overrides > Global policy with priority-based resolution
> >
> > > [tab] Real-World Scenarios
> > >
> > > > [accordion] Development Team Testing
> > > >
> > > > **Scenario**: Frontend team needs to test with latest UI changes while backend team tests API updates
> > > >
> > > > * **Override Setup**: Create role-based overrides for "Frontend Developers" and "Backend Developers"
> > > > * **Policy Configuration**: Frontend role uses latest on `ui-redesign` branch, Backend role uses `api-v2` branch
> > > > * **Business Value**: Parallel development with isolated testing environments and no cross-team interference
> > >
> > > > [accordion] Gradual Feature Rollout
> > > >
> > > > **Scenario**: New premium features need testing with select customers before full release
> > > >
> > > > * **Override Setup**: Create user-specific overrides for beta customers and internal stakeholders
> > > > * **Policy Configuration**: Beta users get latest build with premium features, others remain on stable version
> > > > * **Business Value**: Risk mitigation through controlled exposure and real-world testing feedback
> > >
> > > > [accordion] Emergency Response
> > > >
> > > > **Scenario**: Critical bug discovered in production affecting specific user workflows
> > > >
> > > > * **Override Setup**: Create high-priority role override for affected user groups
> > > > * **Policy Configuration**: Temporarily revert affected users to last stable build while others continue normally
> > > > * **Business Value**: Immediate incident response with minimal user impact and service continuity
> >
> > [Learn more about Active Policy Overrides](../../../../5.1/docs/projects/runtime/active-policy)
> >
> > Major Enhancement

> [tab] Persistence
>
> Advanced data management and storage capabilities that enable new architectural patterns and improved data governance.
>
> 🔄 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture) - Logical separation of business contexts with shared infrastructure\
> 🔄 [**FlowX.AI Database**](#flowx-ai-database) - New persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.1.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature

> [tab] Rendering Improvements & UI/UX Enhancements
>
> Enhanced user experience through improved components, better performance, and streamlined interface design.
>
> 🎨 [**Rendering Improvements & UI/UX Enhancements**](#rendering-improvements-&-ui/ux-enhancements) - Enhanced grid components, navigation redesign, advanced form controls, and analytics capabilities\
> 📋 [**Forms in Collections**](#forms-in-collections) - Enhanced support for form elements within collection components, enabling complex data entry scenarios\
> 🔄 [**Multi Select UI Component**](#multi-select-ui-component) - Allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
>
> ### **Rendering Improvements & UI/UX Enhancements**
>
> > [card] Rendering Improvements & UI/UX Enhancements
> >
> > FlowX.AI 5.1.0 delivers comprehensive UI/UX improvements that enhance the user experience across all platform components, from streamlined navigation to advanced form controls and better workflow handling.
> >
> > ## Interface & Navigation Improvements
> >
> > > [card] Enhanced Grid Component
> > >
> > > Improved performance, responsiveness, and customization options for data display and form organization
> >
> > > [card] Navigation Areas Redesign
> > >
> > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> >
> > > [card] Multi Actions Support
> > >
> > > Batch operations support for UI components, enabling simultaneous actions on multiple elements, multi select, multi copy/paste, multi drag and drop, multi delete
> >
> > > [card] [Permission-Based UI Editing](../../../../5.1/docs/building-blocks/ui-designer/ui-designer#permission-based-expressions)
> > >
> > > Granular control over UI element editing based on user permissions with partial editing capabilities, allow multiple executors on swimlane level
> >
> > ## Enhanced Form Controls & Components
> >
> > > [card] [Input Type Code](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-types)
> > >
> > > Specialized input component for code entry
> >
> > > [card] Formatting Options
> > >
> > > Advanced formatting capabilities for Input and Slider components
> >
> > > [card] [Switch Variants](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field#switch-type)
> > >
> > > Enhanced switch component supporting both toggle and checkbox variants
> >
> > > [card] [Disabled Options on Selectors](/5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select#disabled-options)
> > >
> > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > ## User Experience Enhancements
> >
> > > [card] Custom Loader
> > >
> > > Configurable loading indicators for improved user experience during data operations
> >
> > > [card] [Custom Expression Validators](../../../../5.1/docs/building-blocks/ui-designer/validators#custom-validators)
> > >
> > > Advanced validation logic using dynamic computed expressions that can reference other process data values. Write JavaScript expressions that return boolean values for cross-field validation scenarios
> >
> > > [card] File Upload Button Type
> > >
> > > Introduces a specialized button variant for file upload operations, supporting **fill**, **ghost**, and **text** types for flexible UI styling.
> >
> > > [card] Copy Styles
> > >
> > > Efficiently replicate styling across multiple UI components
> >
> > ## Workflow & Analytics Improvements
> >
> > > [card] Analytics Enhancements
> > >
> > > Custom payload support for detailed user interaction tracking and business intelligence
> >
> > > [card] Process End Handling
> > >
> > > Improved user experience when processes complete or terminate
> >
> > > [card] Template Management
> > >
> > > Streamlined template organization by consolidating functionality in Reusable Resources
>
> ***
>
> ### **Forms in Collections**
>
> > [card] Forms in Collections
> >
> > A powerful new feature that enables dynamic, repeatable forms within collection prototypes, eliminating the need for custom development when building forms with repeatable sections like co-debtors, comments, or any list of similar items.
> >
> > <video />
> >
> > ## Key Capabilities
> >
> > > [card] No Custom Development
> > >
> > > Drag Form components directly into Collection Prototypes - they automatically repeat for each item in your data array
> >
> > > [card] Flexible Validation
> > >
> > > Choose between individual item validation or bulk validation across all collection items
> >
> > > [card] Two Saving Scenarios
> > >
> > > Individual save (one item at a time) or bulk save (entire collection) with different validation behaviors
> >
> > ## Common Use Cases Solved
> >
> > **1. Dynamic Forms**
> >
> > Build forms that show different elements based on conditions without custom development
> >
> > **2. Repeatable Sections**
> >
> > Create forms with sections like adding multiple co-debtors, comments, or family members
> >
> > **3. Complex Data Entry**
> >
> > Handle arrays of objects with proper validation and data management
> >
> > **4. Real-time vs Batch Processing**
> >
> > Choose individual saves for real-time editing or bulk saves for form completion workflows
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component

> [tab] AI Platform
>
> New AI capabilities in Integration Designer for processing text, documents, images, and data using AI-powered nodes.
>
> 🤖 [**AI Nodes in Integration Designer**](#ai-nodes-in-integration-designer) - Process text, documents, images, and data using AI-powered workflow nodes
>
> ### **AI Nodes in Integration Designer**
>
> > [card] AI Nodes in Integration Designer
> >
> > > [tab] AI Nodes Overview
> > >
> > > ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
> > >
> > > FlowX.AI 5.1.0 introduces AI-powered nodes in Integration Designer, enabling intelligent processing of text, documents, images, and data within your workflows. These nodes bring AI capabilities directly into your integration flows without requiring external AI services.
> >
> > > [tab] AI Text Operations
> > >
> > > > [card] Text Transformation
> > > >
> > > > Modify text tone, complexity or formatting for better clarity or style
> > >
> > > > [card] Text Understanding
> > > >
> > > > Analyze text to determine sentiment, topics, intent, language and named entities
> > >
> > > > [card] Text Generation
> > > >
> > > > Generate new text such as summaries, completions, translations or paraphrases
> > >
> > > > [card] Text Extraction
> > > >
> > > > Extract structured information, keywords or metadata from text
> >
> > > [tab] AI Document Operations
> > >
> > > > [card] Document Generation
> > > >
> > > > Automatically build reports or complete templates based on given inputs
> > >
> > > > [card] Document Extraction
> > > >
> > > > Identify and extract structured data, entities or metadata from documents
> > >
> > > > [card] Document Understanding
> > > >
> > > > Analyze documents to extract meaning, topics, sentiment, or important information
> > >
> > > > [card] Extract Text from Document
> > > >
> > > > Extract text content from documents (OCR, PDF text extraction)
> >
> > > [tab] AI Image & Data Operations
> > >
> > > **Image Operations:**
> > >
> > > > [card] Image Description
> > > >
> > > > Generate captions or extract detailed information from visual content
> > >
> > > > [card] Image Analysis
> > > >
> > > > Recognize objects, emotions and scenes in images for contextual understanding
> > >
> > > **Data Operations:**
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Add annotations, context or relationships to enhance raw data value
> > >
> > > > [card] Data Generation
> > > >
> > > > Produce synthetic or structured data using templates and logic-based rules
> > >
> > > > [card] Data Transformation
> > > >
> > > > Clean, normalize, aggregate, or restructure datasets into usable formats
> >
> > > [tab] Use Cases
> > >
> > > > [accordion] Intelligent Document Processing
> > > >
> > > > * Extract data from invoices, contracts, and forms
> > > > * Classify documents automatically
> > > > * Validate extracted information against business rules
> > >
> > > > [accordion] Customer Communication Analysis
> > > >
> > > > * Analyze customer feedback sentiment
> > > > * Extract key topics from support tickets
> > > > * Generate personalized responses
> > >
> > > > [accordion] Content Generation
> > > >
> > > > * Create summaries of long documents
> > > > * Translate content to multiple languages
> > > > * Generate reports from structured data
> > >
> > > > [accordion] Data Processing
> > > >
> > > > * Enrich customer data with AI-derived insights
> > > > * Transform unstructured data to structured formats
> > > > * Generate test data for development
> >
> > [Learn more about AI Node Types](../../../../5.1/docs/platform-deep-dive/integrations/ai-nodes)
> >
> > New Feature

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.1](./deployment-guidelines-v5.1)
> >
> > Instructions for deploying FlowX.AI 5.1.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.1/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.1.0


# FlowX.AI 5.1.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.1-november-2025

WCAG 2.1 Level AA compliance achieved, AI Platform enhancements, bug fixes, and quality improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **accessibility compliance**, **AI Platform enhancements**, **customer issue resolution**, and **proactive quality improvements**.
> Upgrades from **5.1.0 → 5.1.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Quality Achievement**: FlowX.AI 5.1.1 demonstrates our commitment to proactive quality improvement:
>
> * **[WCAG 2.1 Level AA compliance](https://www.w3.org/TR/WCAG21/)** achieved across all web components
> * **Proactive quality improvements** identified through internal QA before reaching customers
> * **Customer issues** resolved with full business context
> * **Zero breaking changes** - fully compatible upgrade from 5.1.0
>
> This release represents months of accessibility audits, automated testing, and quality assurance work to deliver exceptional software quality.

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.1 delivers comprehensive improvements across accessibility, stability, and platform reliability.
>
> ♿  [**WCAG 2.1 Compliance Achieved**](#wcag-2-1-compliance) - Full accessibility support across all web components\
> 🌍 [**Task Management Localization**](#task-management-localization) — Comprehensive multi-language support with 51 substitution tags\
> 🤖 [**AI Platform Enhancements**](#ai-platform-enhancements) — Multi-agent system improvements and AI workflow stability\
> 🎯 [**Customer Fixes**](#customer-fixes) — Critical issues resolved based on customer feedback\
> ✨ [**Proactive Improvements**](#proactive-quality-improvements) — Issues identified through internal QA before reaching customers\
> 🔧 [**Platform Enhancements**](#platform-enhancements) — SSE handling, audit logs, and infrastructure improvements
>
> ### **WCAG 2.1 compliance**
>
> > [card] WCAG 2.1 compliance
> >
> > > [tab] Overview
> > >
> > > **FlowX.AI is now WCAG 2.1 Level AA compliant**
> > >
> > > This release delivers full accessibility support through **28 comprehensive improvements** across Angular and React SDKs, making FlowX applications usable by everyone, including users with disabilities.
> > >
> > > ### Business value
> > >
> > > > [card] Government Compliance
> > > >
> > > > Meet accessibility requirements for government and public sector applications
> > >
> > > > [card] Healthcare Standards
> > > >
> > > > Comply with healthcare industry accessibility regulations and standards
> > >
> > > > [card] Financial Services
> > > >
> > > > Satisfy financial sector requirements for inclusive digital experiences
> > >
> > > > [card] Universal UX
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those with disabilities
> > >
> > > ### What changed
> > >
> > > * All components now fully keyboard-accessible
> > > * Complete screen reader support with ARIA labels
> > > * Proper focus management across all interactions
> > > * Accessible error announcements and validation
> > > * Semantic HTML structure throughout
> >
> > > [tab] Key features
> > >
> > > > [card] Auto-bindable ARIA Tags
> > > >
> > > > Automatically bind accessibility labels, descriptions, and ARIA attributes to all UI components from Designer configuration
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Full keyboard navigation support with proper focus management, tab order, and keyboard shortcuts in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > ARIA labels, descriptions, and live regions implemented across all form elements and interactive components
> > >
> > > > [card] UI Designer Integration
> > > >
> > > > Dedicated accessibility configuration section in UI Designer for managing labels and descriptions
> >
> > > [tab] Supported components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio/Segmented buttons, Slider, and File upload with labels, descriptions, and error announcements
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card with keyboard navigation, focus management, and state announcements
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with semantic HTML structure and proper labeling
> > >
> > > **4. Platform Support**
> > >
> > > Complete implementation for Angular and React SDKs (iOS and Android in future releases)
> >
> > > [tab] Implementation details
> > >
> > > **28 Improvements Delivered:**
> > >
> > > > [accordion] Angular SDK
> > > >
> > > > * Custom keyboard navigation implementation
> > > > * Focus management for Select/Multiselect components
> > > > * Modal focus trap and restoration
> > > > * Shift+Tab handling across form elements
> > > > * Listbox keyboard operations
> > > > * Table navigation improvements
> > > > * Switch and checkbox accessibility
> > > > * File preview focus indicators
> > > > * Button Space key activation
> > > > * Link focus outlines
> > > > * Disabled element keyboard behavior
> > >
> > > > [accordion] React SDK
> > > >
> > > > * BaseUI Combobox implementation for Select/Multiselect
> > > > * Keyboard navigation with clear buttons
> > > > * Focus restoration after interactions
> > > > * Outline theming for focus indicators
> > > > * Modal auto-focus on open
> > > > * Card accordion keyboard handling
> > > > * Table row navigation
> > > > * Option highlighting in dropdowns
> > >
> > > > [accordion] UI Designer
> > > >
> > > > * Accessibility configuration panel
> > > > * Auto-bindable tags for all components
> > > > * Label and description fields
> > > > * Alt text management for images
> > > > * ARIA attribute configuration
> > > > * Accessibility section styling
> > > > * Component-specific accessibility settings
> > >
> > > > [accordion] Technical tasks completed
> > > >
> > > > * Implemented BaseUI Combobox for Select/Multiselect
> > > > * Custom keyboard navigation for Angular
> > > > * React SDK keyboard navigation with clear button
> > > > * Auto-bindable accessibility tags for all components
> > > > * Accessibility configuration panel in UI Designer
> > > > * Removed conflicting title attribute tooltips
> > > > * Aligned Stepper accessibility between frameworks
> > > > * Bind labels and descriptions to form fields
> >
> > [Learn more about Accessibility Configuration](/5.1/docs/platform-deep-dive/accessibility)
> >
> > Major Achievement
>
> ***
>
> ### **Customer fixes**
>
> > [card] Customer fixes
> >
> > We prioritized and resolved **customer-reported issues** in this release, addressing critical functionality issues and workflow inefficiencies reported via Zendesk.
> >
> > > [accordion] Action parameters lost on copy/paste
> > >
> > > **Problem:**\
> > > When copying nodes with Kafka send actions, topic and message configurations were not preserved, forcing users to manually reconfigure all action parameters after paste operations.
> > >
> > > **Customer Impact:**
> > >
> > > * Development velocity significantly reduced
> > > * Risk of configuration errors during manual re-entry
> > > * Frustration with repetitive configuration work
> > >
> > > **Resolution:**\
> > > actionParamsMap now properly persists through copy/paste operations
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create send message node with Kafka action
> > > 2. Configure topic and message parameters
> > > 3. Copy and paste the node
> > > 4. All configurations now preserved correctly
> > >
> > > **Customer Benefit:**\
> > > Faster workflow development with reduced configuration errors and improved developer experience.
> >
> > > [accordion] Orphaned warnings block process deployments
> > >
> > > **Problem:**\
> > > When deleting parent actions that had child actions with warnings, the warnings remained in the system as orphans. These orphaned warnings prevented process export/import operations and blocked build deployments.
> > >
> > > **Customer Impact:**
> > >
> > > * Build pipelines blocked by stale warnings
> > > * Deployment delays requiring manual database cleanup
> > > * Process export/import operations failed
> > > * Development and testing workflows disrupted
> > >
> > > **Resolution:**\
> > > Warnings now cascade-delete automatically when parent actions are removed
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create action with subactions containing warnings
> > > 2. Delete the parent action
> > > 3. All child warnings now properly cleaned up
> > >
> > > **Customer Benefit:**\
> > > Clean deployments without manual intervention, faster development cycles, no more blocked pipelines.
> >
> > > [accordion] Default application cannot be removed
> > >
> > > **Problem:**\
> > > Auto-generated `default_application` in new environments existed only in app\_manager schema and could not be deleted through standard operations, returning validation errors.
> > >
> > > **Customer Impact:**
> > >
> > > * Environment cleanup difficulties
> > > * Testing complications with unwanted default projects
> > > * Confusion about application lifecycle management
> > >
> > > **Resolution:**\
> > > Added proper runtime validation for application deletion operations
> > >
> > > **Error (Fixed):**
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": 400,
> > >   "message": "error.validation.runtime.application.not_found",
> > >   "title": "Runtime project not found."
> > > }
> > > ```
> > >
> > > **Customer Benefit:**\
> > > Clean environment management with predictable application lifecycle operations.
>
> ***
>
> ### **Proactive quality improvements**
>
> > [card] Proactive quality improvements
> >
> > > [tab] Overview
> > >
> > > **Issues identified and resolved proactively**:
> > >
> > > ### Quality process
> > >
> > > > [card] Accessibility Audits
> > > >
> > > > WCAG 2.1 compliance testing identified keyboard navigation and focus management improvements
> > >
> > > > [card] Automated Testing
> > > >
> > > > Continuous integration pipelines caught component behavior issues and rendering problems
> > >
> > > > [card] Internal QA
> > > >
> > > > Manual testing uncovered edge cases in form interactions and modal behaviors
> > >
> > > > [card] Code Reviews
> > > >
> > > > Peer reviews identified potential stability issues in backend processing and dependency management
> > >
> > > ### Distribution by category
> > >
> > > * **Keyboard Navigation**: Fixes across Angular and React
> > > * **Focus Management**: Fixes for modals, forms, and interactive elements
> > > * **Component Behavior**: Fixes for proper state handling and rendering
> > > * **Backend Stability**: Fixes for processing and dependency management
> >
> > > [tab] Angular SDK
> > >
> > > > [accordion] Keyboard navigation improvements
> > > >
> > > > * Fixed listbox remaining open when pressing Shift+Tab
> > > > * Fixed Shift+Tab not working on Select with search
> > > > * Fixed Multiselect tab navigation moving to first element instead of next
> > > > * Fixed Select input focus not working properly
> > > > * Fixed Select list not scrolling during keyboard navigation
> > > > * Fixed up/down arrow scrolling screen alongside option list
> > > > * Fixed focus lost after loading new user task
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed Link in message focus missing outline
> > > > * Fixed modal close button not focused automatically
> > > > * Fixed file preview focus not highlighted and lost
> > > > * Fixed button inside modal not working with Space key
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Multiselect options list not opening
> > > > * Fixed MultiSelect and link focusable when disabled
> > > > * Fixed modal dismiss buttons not working with Space key
> > > > * Fixed modal without close button not easily focusable
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Space pressed on card with accordion scrolling page
> > > > * Fixed Switch with label position start focus issues
> >
> > > [tab] React SDK
> > >
> > > > [accordion] Keyboard Navigation Improvements
> > > >
> > > > * Fixed outline from theme not applied to modal close button and links
> > > > * Fixed Select selected option not highlighted in options list
> > > > * Fixed Select search not filtering after selection
> > > > * Fixed Input/textarea/select focus lost after using clear button
> > > > * Fixed Tab focus moving inside collapsed card
> > > > * Fixed table Tab navigation skipping rows
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed file preview retry focus not highlighted and lost
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Select and link focusable when disabled
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Datepicker clear icon focus not highlighted
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed doc preview modal not closable with Enter or Space
> > > > * Fixed button inside table focus not highlighted
> > > > * Fixed Slider decimal numbers not rendered correctly
> > > > * Fixed Substepper not rendered correctly
> > > > * Fixed doc preview display mode showing inline
> > > > * Fixed cards expandable before token reaches them
> >
> > > [tab] Designer & Backend
> > >
> > > > [accordion] UI Designer Improvements
> > > >
> > > > * Fixed missing accessibility section on Link component
> > > > * Fixed missing accessibility section on Image button
> > > > * Fixed missing space in accessibility label and info icon
> > > > * Fixed Alt text field disabled styling not applied
> > > > * Fixed console errors when changing pages from header
> > > > * Fixed Select/multiselect highlighted in preview and settings tabs
> > > > * Fixed outline theming in enumerations and inputs
> > > > * Fixed Workflows info points content not rendered correctly
> > > > * Fixed Workflows tabs content not showing properly
> > > > * Fixed padding missing on RUT UI Assets panel
> > >
> > > > [accordion] Backend Stability Improvements
> > > >
> > > > * Fixed wrong navigationTree response on overridden process
> > > > * Fixed incorrect navigationTree for resource override details
> > > > * Fixed error when trying to update dependency lib versions
> > > > * Fixed error returned when updating dependency with override
> > > > * Fixed no response on out topic for start process by name from Kafka
> > > > * Fixed checkbox "Allow back to this action" status not loaded
> > > > * Fixed empty screen when logging in without workspace access
> > > > * Fixed Elasticsearch scheduled task errors with failed documents
> > > > * Fixed services not logging when Liquibase crashing due to lock
> >
> > Proactive Quality
>
> ***
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 adds comprehensive localization support for Task Management, enabling multi-language task management interfaces through 51 system substitution tags. Table grid localization is automatic.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > >
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> > >
> > > > [!NOTE]
> > > >
> > > > This feature enables complete Task Management localization for global deployments, meeting requirements for government, healthcare, and financial services applications requiring multi-language support.
> >
> > > [tab] Key features
> > >
> > > > [card] FlowX Substitution Tags (51 Keys)
> > > >
> > > > Complete set of substitution tags for task actions, statuses, history events, and UI elements
> > >
> > > > [card] Table Grid Localization
> > > >
> > > > Table grid localizes automatically based on container app language; FlowX tags configured manually in CMS
> > >
> > > > [card] Web Renderer Integration
> > > >
> > > > Angular and React renderers use system substitution tags on all task management texts
> >
> > > [tab] What's localized
> > >
> > > **FlowX Substitution Tags (51 Keys):**
> > >
> > > * Table columns (title, stage, assignee, status, priority, last updated)
> > > * Process states (created, started, finished, failed, expired, etc.)
> > > * Task actions (assign, unassign, hold, unhold, execute, start)
> > > * Bulk operations (assign to, unassign all, hold all, etc.)
> > > * History events (task created, assigned, status changed, etc.)
> > > * User selection dialogs and UI states
> > >
> > > **Table Grid Localization**:
> > >
> > > * Filters (set, text, number, date with all operators)
> > > * Menus (column, context, aggregation, sorting)
> > > * Pagination (navigation, page size, row counts)
> > > * Data types (boolean, dates, numbers with formatting)
> > > * ARIA labels for accessibility
> >
> > > [tab] Implementation details
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization based on this setting
> > >
> > > **2. Configure CMS Tags**
> > >
> > > Add translations for all 51 sys\_tm\_\* tags in CMS for each supported language - this is the only manual configuration needed
> > >
> > > **3. Use in Renderers**
> > >
> > > Web renderers automatically apply system substitution tags to all task management UI elements
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> ***
>
> ### **AI Platform enhancements**
>
> > [card] AI Platform enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 delivers significant improvements to the AI Platform, enhancing multi-agent collaboration, conversation management, and AI workflow stability. These enhancements ensure more reliable AI-assisted development workflows and better user experience.
> > >
> > > > [card] Multi-Agent System
> > > >
> > > > Enhanced agent communication and thread management for improved collaborative AI workflows
> > >
> > > > [card] Conversation Stability
> > > >
> > > > Improved conversation handling with better error propagation and session management
> > >
> > > > [card] AI Developer Tools
> > > >
> > > > Enhanced AI Developer capabilities with proper data model integration and expression generation
> > >
> > > > [card] Document Intelligence
> > > >
> > > > Multi-page document generation support and improved content handling
> >
> > > [tab] Key improvements
> > >
> > > **Multi-Agent Conversation Management:**
> > >
> > > * Enhanced conversation thread handling with proper parent action status updates
> > > * Improved backend support for adding new messages on agent threads
> > > * Better session management with new session button in Command Center
> > > * Context switching prevention during execution plan generation
> > >
> > > **AI Developer Enhancements:**
> > >
> > > * Fixed data model integration for expressions and business rules generation
> > > * Improved action target saving and destination setting
> > > * Enhanced execution plan editing from user prompts
> > > * Better handling of empty execution plans
> > >
> > > **Error Handling & Stability:**
> > >
> > > * Graceful error propagation from internal AI agent operations
> > > * Improved CORS headers for document object downloads
> > > * Enhanced telemetry support for debugging and monitoring
> > > * Better handling of plan enhancement patches
> > >
> > > **Document & Content Features:**
> > >
> > > * Multi-page document generation support in AI nodes
> > > * Source selector component for image and document inputs
> > > * Improved messaging system for AI agents in command center
> > > * Enhanced UI feedback for AI-generated resources
> >
> > > [tab] Technical improvements
> > >
> > > **Backend Enhancements:**
> > >
> > > * Continuous patching support for action contexts during execution
> > > * Improved navigation tree responses for overridden processes
> > > * Enhanced dependency management for library overrides
> > > * Better error handling and logging across AI services
> > >
> > > **Frontend Improvements:**
> > >
> > > * Fixed target selector closing behavior in implementation threads
> > > * Improved preview mode handling after developer changes
> > > * Enhanced command center messaging and error display
> > > * Better UI state management for AI workflow interactions
> > >
> > > **Integration Updates:**
> > >
> > > * CORS headers properly configured for GraphQL object downloads
> > > * Process task destinations automatically set to current process
> > > * Improved integration between AI agents and execution plans
> > > * Enhanced audit logging for resource overrides
> >
> > AI Platform
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform enhancements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] SSE Disconnect Handling
> > > >
> > > > Improved Server-Sent Events disconnect handling to reduce error log flooding when clients disconnect
> > >
> > > > [card] Resource Overrides Audit
> > > >
> > > > Implemented audit logs for library resource overrides to track configuration changes
> > >
> > > > [card] Security Updates
> > > >
> > > > Fixed high vulnerabilities in Designer 5.1.x and main branch
> >
> > > [tab] Renderer Enhancements
> > >
> > > > [card] System Substitution Tags
> > > >
> > > > Web renderers now use system substitution tags on all task management texts
> > >
> > > > [card] Outline Theming
> > > >
> > > > Enhanced outline and select/multiselect option highlight theming for visual consistency
> >
> > > [tab] Technical Improvements
> > >
> > > **Code Quality:**
> > >
> > > * Eliminated deprecated code for Kafka start process
> > > * Improved error handling for Elasticsearch document updates
> > > * Enhanced dependency management for library overrides
> > > * Better logging and error reporting across services
> > >
> > > **Performance:**
> > >
> > > * Optimized SSE connection handling
> > > * Improved query performance for navigation tree
> > > * Better resource management in long-running processes
> >
> > Platform Updates

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.1 is fully compatible with 5.1.0. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.0 → 5.1.1 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Android and iOS accessibility properties implementation
> > * Additional Select component refinements
> > * UI Designer padding optimizations
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and critical bug fixes
> * Accessibility enhancements for mobile platforms
> * Performance optimizations
>
> Major new features are planned for future releases in the 5.x series. See the [5.2.0 release notes](../v5.2.0-november-2025/v5.2.0-november-2025) for upcoming capabilities.


# FlowX.AI 5.1.10 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.10-june-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.9 → 5.1.10** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.10 includes bug fixes and security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Active policy and iOS renderer fixes
> * Real-time event delivery stability improvement (Events Gateway)
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.9

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Reusable UI templates:** fixed several issues affecting reusable UI templates: actions remaining mapped after changing dependency versions, undo/redo leaving an action without a name or unable to save, data-slice and mapping requests returning 400 after a data-model key was renamed, duplicate entries returned for available templates, the "open in new tab" flag not being saved on UI action mappings, actions going missing when the same template is nested at multiple container levels, and conditional styling and validators being applied incorrectly when the same template is used more than once in a single user task.
> > > >
> > > > * **Active policy:** fixed an issue where the user list could appear empty on the override active-policy form.
> > > >
> > > > * **Project version merge:** fixed a 500 error that could occur when merging app versions.&#x20;
> > > >
> > > > * **Organization settings:** fixed the runtime users list failing to load.&#x20;
> > > >
> > > > - **Real-time event delivery:** improved Redis connection stability under sustained load. The Events Gateway now uses polling as the default mode for reading real-time events from Redis, preventing the gradual connection buildup that could previously require periodic Events Gateway restarts. The change applies automatically on upgrade; no configuration is required.
> > > > - **Renderer:** accordion card height and custom styles now follow the component's opened state, and gap spacing is applied correctly to collections.
> > > > - **Process instances:** fixed duplicate API calls and rendering errors when navigating between process instances.
> > > > - **iOS renderer:** broad VoiceOver and accessibility improvements across components (form fields, file preview, sliders, date picker, validation messages), and fixed form view-model lookup for forms nested in collections.
> > > > - **Android renderer:** component sizing now includes padding on text, link, markdown, and image components; fixed a TopAppBar crash in some configurations, tooltip icon overrides, slider step rounding, document preview caching, and resilience to process death.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.10 is fully compatible with 5.1.9. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.9 → 5.1.10 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.10](./deployment-guidelines-v5.1.10).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.11 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.11-july-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.10 → 5.1.11** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.11 includes bug fixes and security patches:
>
> * Audit log and task management fixes
> * Project creation error-handling fix
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.10

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Audit log:** filtering by user now returns results when a user's username differs from their email address.
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it.
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.11 is fully compatible with 5.1.10. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.10 → 5.1.11 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.11](./deployment-guidelines-v5.1.11).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.12 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.12-august-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.11 → 5.1.12** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.12 includes bug fixes for library resources and task management:
>
> * Library process resource overview fixes
> * Task management sort control fix
> * No breaking changes; fully compatible upgrade from 5.1.11

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes for library resource overview and task management
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.12 is fully compatible with 5.1.11. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.11 → 5.1.12 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.12](./deployment-guidelines-v5.1.12).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.13 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.13-september-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **security patches**. Upgrades from **5.1.12 → 5.1.13** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.13 includes reliability fixes for process advancing, a process designer fix, and security patches:
>
> * Process advancing fixes that prevent lost or stalled process advances under load
> * Action deletion fix for business rules that call reusable functions
> * Security patches and dependency upgrades across platform components
> * No breaking changes; fully compatible upgrade from 5.1.12

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and security patches across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Process advancing reliability fixes, a process designer fix, and security patches
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Process advancing:** the partition cleanup job no longer deletes advance events that are accepted while cleanup is running. Event insertion and cleanup now coordinate through database row locks, on both PostgreSQL and Oracle, so a process advance can no longer be lost to a concurrent cleanup.&#x20;
> > > > * **Process advancing:** advancing workers no longer pause for cooldown while work is still queued, and event completion is retried after a database deadlock instead of leaving an already-processed event marked as in progress.&#x20;
> > > > * **Process designer:** deleting an action no longer fails with a server error when one of its business rules calls a reusable function.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components. The Java runtime base images move to Eclipse Temurin 21.0.12 with a refreshed OS package layer.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.13 is fully compatible with 5.1.12. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.12 → 5.1.13 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.13](./deployment-guidelines-v5.1.13).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.14 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.14-october-2026

Final maintenance release for the FlowX.AI 5.1.x LTS line. Audit index retention settings, an Android SDK loader fix, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.1.x** line, focused on **bug fixes** and **security patches**. Upgrades from **5.1.13 → 5.1.14** are non-breaking and fully compatible. FlowX.AI 5.1.14 is the final planned maintenance release of the 5.1.x line. To keep receiving fixes, plan your move to the 5.9.x LTS line: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [card] Release Highlight
>
> **FlowX.AI 5.1.14** is a maintenance release for the 5.1.x LTS:
>
> * **Audit index retention:** optional settings to delete old audit data and roll audit indices over by shard size
> * **Key fixes:** the Android SDK loader shows on modal screens and no longer stays stuck after repeated taps
> * Security patches and dependency upgrades. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.1.14 is fully compatible with 5.1.13. No breaking changes, no database migrations, and no required configuration changes; standard deployment procedures apply.

**Upgrade path:** direct upgrade from 5.1.13.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x. Component versions are listed in the [5.1.14 deployment guidelines](./deployment-guidelines-v5.1.14).

***

## Full changelog

### New

* **Audit:** set how long audit data is kept, and roll audit indices over when a primary shard reaches a set size, with two new environment variables. Both are off by default, so the Audit service deletes nothing until you set a retention period. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch) and the [deployment guidelines](./deployment-guidelines-v5.1.14#new-environment-variables-audit-index-retention).&#x20;

### Fixed

* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.1.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.2-december-2025

Bug fixes, stability improvements, and quality enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes**, **stability improvements**, and **quality enhancements**.
> Upgrades from **5.1.1 → 5.1.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.2 provides continued quality, stability, and reliability for the platform:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * New features and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.2 delivers maintenance improvements focused on stability, reliability, and feature enhancements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — issues resolved including customer-reported and proactive fixes\
> ✨ [**New Features**](#new-features) — enhancements including new features and platform improvements\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure and stability enhancements
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Authorization service configuration
> > > >
> > > > **Problem:**\
> > > > Wrong service account client secret config parameter was used in Authorization service, causing authentication failures.
> > > >
> > > > **Resolution:**\
> > > > Fixed configu gration parameter mapping for service account client secret in Authorization service
> > >
> > > > [accordion] Token state changes on back navigation
> > > >
> > > > **Problem:**\
> > > > When performing back in steps actions, tokens incorrectly changed from Aborted to Active state when lazy actions finished.
> > > >
> > > > **Resolution:**\
> > > > Fixed token state management during back navigation to preserve correct state
> > >
> > > > [accordion] Action parameters not copied on node copy
> > > >
> > > > **Problem:**\
> > > > When copying nodes with child actions, action parameters (like Kafka topic and message configurations) were not preserved.
> > > >
> > > > **Resolution:**\
> > > > Fixed actionParamsMap persistence through copy/paste operations
> > >
> > > > [accordion] Permissions updated incorrectly during action execution
> > > >
> > > > **Problem:**\
> > > > hideRules and disableRules values were incorrectly updated in database when executing actions, causing permission issues.
> > > >
> > > > **Resolution:**\
> > > > Fixed permission rule handling during action execution
> > >
> > > > [accordion] Subprocess data mapping issues
> > > >
> > > > **Problem:**\
> > > > Starting subprocess with legacy mapping caused data to be incorrectly appended instead of replaced.
> > > >
> > > > **Resolution:**\
> > > > Fixed data mapping behavior for subprocess start actions
> > >
> > > > [accordion] Forms in collections - action not found
> > > >
> > > > **Problem:**\
> > > > When saving data from outside collection with forms to submit, actions were not found correctly.
> > > >
> > > > **Resolution:**\
> > > > Fixed action resolution for forms inside collections
> >
> > > [tab] AI Platform fixes
> > >
> > > > [accordion] AI Designer improvements
> > > >
> > > > * Fixed no feedback when uploading large documents in command center
> > > > * Fixed targets for business rules never being set by planner
> > > > * Fixed file upload limit lower than 3MB
> > > > * Fixed missing messages on Keep/Discard buttons for UI and BR
> > > > * Fixed Save & Close button not working in Data Model modal
> > > > * Fixed DM keys not created after keeping UI
> > > > * Fixed table key appearing as mapped when Data Model is empty
> > > > * Fixed pip window being clipped
> > > > * Fixed Submit prompt button color not indicating active state
> > > > * Fixed source not indicating uploaded document for some Plan actions
> > > > * Fixed UI outcome duplication until connected-graph keep method finishes
> > > > * Fixed missing scrollbar in Context Documents modal with multiple subprocesses
> > > > * Fixed command center not reopenable after closing in developer preview mode
> > > > * Fixed planner sample data import crashes
> > > > * Fixed business logic targets not correctly stored in execution plan
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Web renderer improvements
> > > >
> > > > * Fixed hide subprocess navigation closing parent navigation with multiple hierarchies
> > > > * Fixed card collapsing when next nav area is modal (Angular & React)
> > > > * Fixed card not expandable after finishing subprocess started from it (Angular & React)
> > > > * Fixed loader missing or not fully shown in React
> > > > * Fixed message icon and text rendered on different rows when width fill in React
> > > > * Fixed collection prototype shown when collection source array doesn't exist in React
> > > > * Fixed broken image rendered when missing url or base64 image in React
> > > > * Fixed switch component knob and container alignment in React
> > > > * Fixed multi select search not filtering available options in React SDK
> > > > * Fixed custom component keys duplicated in action body (React & Angular)
> > >
> > > > [accordion] Task Manager fixes
> > > >
> > > > * Fixed Task Manager theming not applied in Angular
> > > > * Fixed Task Manager header theming not applied in React
> > > > * Fixed assignee dropdown list and placeholder not displayed in React
> > >
> > > > [accordion] Reusable templates fixes
> > > >
> > > > * Fixed custom body being null at runtime for Reusable templates actions
> >
> > > [tab] Platform & Data fixes
> > >
> > > > [accordion] Data model and mappers
> > > >
> > > > * Fixed input/output parameters not deleted after updating parameters
> > > > * Fixed Go to reference button redirecting incorrectly
> > > > * Fixed parameters items deleted when updating Project Data Model object
> > >
> > > > [accordion] Process Designer
> > > >
> > > > * Fixed retry token button available for inactive tokens
> > > > * Fixed missing save action button when opening action config from UI designer
> > >
> > > > [accordion] Platform stability
> > > >
> > > > * Fixed advancing errors in partition event table
>
> ***
>
> ### **New features**
>
> > [card] New features
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation
> > > >
> > > > Generate Data Model for tables and table columns from AI Designer
> >
> > > [tab] Renderers
> > >
> > > > [card] Android Accessibility
> > > >
> > > > Accessibility properties from UI Designer now supported in Android renderer
> > >
> > > > [card] Substitution Tags in Selectors
> > > >
> > > > Selectors (checkbox, radio, select, multiselect) now support substitution tags when source type is process data across Angular, React, and iOS renderers
> > >
> > > > [card] Template Caching
> > > >
> > > > Improved caching for reusable templates at runtime
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Dgraph Upgrade
> > > >
> > > > Bring dgraph to flowx-release
> >
> > > [tab] Performance & Optimization
> > >
> > > > [card] Designer Static Assets
> > > >
> > > > Make designer nginx use compression & caching for static assets

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.2 is fully compatible with 5.1.1. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.1 → 5.1.2 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.2](./deployment-guidelines-v5.1.2).
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Task Manager theming issues in Angular and React
> > * Task Manager assignee dropdown display issues in React
> > * Custom component key duplication in action body
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.3-january-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.2 → 5.1.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.3 delivers security patches and significant performance improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.2

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.3 delivers comprehensive security, performance, and stability improvements across the platform.
>
> ♿ [**iOS Accessibility**](#improvements-and-enhancements) — VoiceOver accessibility support for iOS renderer\
> ✨ [**Improvements and enhancements**](#improvements-and-enhancements) — AI Platform improvements and enhancements for Data Model generation\
> ⚡ [**Performance Improvements**](#performance-improvements) — Performance improvements and optimizations across platform components and services\
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Improvements and enhancements**
>
> > [card] Improvements and enhancements
> >
> > > [tab] Renderers
> > >
> > > > [card] iOS Accessibility
> > > >
> > > > VoiceOver accessibility support for the iOS renderer. Accessibility properties configured in the UI Designer (labels, hints, traits, decorative flags) are now applied to iOS components including form elements, text, images, and links.
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation for Tables
> > > >
> > > > Generate Data Model mappings for table components from AI Designer. AI automatically creates array of objects DM keys for tables with type validation and visual feedback.
> > >
> > > > [card] Data Model Generation for Table Columns
> > > >
> > > > Extended DM generation for text and link elements within table columns, with automatic attribute mapping and support for partial matching.
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.3 delivers significant performance improvements to the process engine
> > >
> > > > [card] Optimized Writes
> > > >
> > > > Smart change detection skips unnecessary database writes when param\_values unchanged
> > >
> > > > [card] Reduced DB Calls
> > > >
> > > > N+1 query fixes and batch loading significantly reduce database round trips
> > >
> > > > [card] Request Caching
> > > >
> > > > Request-scoped caching for frequently accessed runtime configuration
> >
> > > [tab] Key optimizations
> > >
> > > > [accordion] ProcessInstance param\_values Optimization
> > > >
> > > > Optimized handling of large `param_values` to reduce network overhead and prevent optimistic locking conflicts:
> > > >
> > > > * **Change Detection**: Skip database writes when param\_values unchanged
> > > > * **Lightweight Queries**: Exclude param\_values from SELECT when not needed
> > >
> > > > [accordion] Runtime Improvements - Reduced DB Calls
> > > >
> > > > **Optimizations Implemented:**
> > > >
> > > > * Improved batch loading and caching to reduce redundant queries
> > > > * Streamlined process initiation
> > > > * Enhanced batching for database writes
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Task Manager View Not Updating
> > > >
> > > > **Problem:**\
> > > > When using a view with dataset config where assignee is set to blank, after assigning a task (or self-assigning), the view appeared unchanged. Similarly, when assignee is set to not blank and you unassign a task, the view did not update.
> > > >
> > > > **Resolution:**\
> > > > Fixed view refresh behavior after assign/unassign operations to properly reflect the updated task state and provide visual feedback to users.
> > >
> > > > [accordion] Forms in Collections - Backend Keys Calculation
> > > >
> > > > **Problem:**\
> > > > When saving data from outside a collection with forms to submit, the backend calculated keys for UUID entries in formsToSubmit. These keys were only partial (relative to the collection array) and could overwrite existing process values.
> > > >
> > > > **Resolution:**\
> > > > Added a flag on PATCH /actions requests to notify the backend to exclude backend keys calculation for forms in collections UUIDs from formsToSubmit.
> > >
> > > > [accordion] Variables Reset on Config Update
> > > >
> > > > **Problem:**\
> > > > Updating parameters in the config page caused existing parameters to be replaced with new ones, generating new flowxUuids. This caused variables in database nodes to no longer match, losing all references.
> > > >
> > > > **Resolution:**\
> > > > Fixed to always send id and flowxUuid for existing params when saving the operation, preserving variable references.
> > >
> > > > [accordion] Build Export Timeout
> > > >
> > > > **Problem:**\
> > > > When exporting builds with multiple resources, some resources remained in EXPORTING status, others got EXPORT\_TIMEOUT without the build export receiving the status, and others had EXPORTED status. This was caused by Kafka messages being processed before the MongoDB transaction was committed.
> > > >
> > > > **Resolution:**\
> > > > Fixed the export function to ensure proper sequencing of database transactions and Kafka messages during build export operations.
> >
> > > [tab] Designer fixes
> > >
> > > > [accordion] Table Row Deletable with Backspace in RUT
> > > >
> > > > **Problem:**\
> > > > In Reusable UI Templates, selecting a table row and pressing backspace would delete the row, even though table rows should not be deletable.
> > > >
> > > > **Resolution:**\
> > > > Fixed keyboard handling to prevent accidental table row deletion via backspace key.
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Android Upload Action Payload Missing
> > > >
> > > > **Problem:**\
> > > > Upload action payload data (except uploadFileTempFileId) was missing on execution in the Android renderer.
> > > >
> > > > **Resolution:**\
> > > > Fixed payload handling to include all required data in upload action execution.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Connector Topic Pattern
> > > >
> > > > Added dedicated KAFKA\_TOPIC\_CONNECTOR\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [tab] AI Platform
> > >
> > > > [card] Streaming Client Library
> > > >
> > > > Implemented client library for invoking the run AI node with streaming support for conversational API

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.3 is fully compatible with 5.1.2. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.2 → 5.1.3 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### New configuration options
>
> > [!NOTE]
> >
> > **Optional**: New environment variable available for process-engine
>
> | Variable | Description | Default |
> | - | - | - |
> | `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from other platform components | Falls back to `KAFKA_TOPIC_PATTERN` if not set |
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.3](./deployment-guidelines-v5.1.3).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.3 → 5.1.4** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.4 delivers security patches and stability improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.3

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.4 delivers comprehensive security, performance, and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components and stability improvements\
> ⚡ [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Form validators do not work inside collection prototypes
> > > >
> > > > **Summary:**
> > > >
> > > > Validators applied to forms within collection prototypes are not triggered as expected.
> > >
> > > > [accordion] Project editor could modify access permissions
> > > >
> > > > **Summary:**
> > > >
> > > > Project editors were incorrectly able to modify project access permissions and delete projects. This has been fixed: `project_editor` can no longer modify access management or delete projects/libraries. Only `project_owner` and `workspace_admin` can change project ownership, add/remove users and groups from projects/libraries, and delete projects/libraries.
> > >
> > > > [accordion] Subprocess UI still shown after subprocess is finished
> > > >
> > > > **Summary:**
> > > >
> > > > In processes with multiple subprocesses that have UI, the first subprocess UI remained visible after completion until the next user task details were received. The UI now correctly clears when a subprocess finishes.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Kafka environment variables alignment
> > > >
> > > > Kafka environment variables are now consistent across all services with backwards compatibility support for existing configurations.
> > >
> > > > [card] Config params cache improvements
> > > >
> > > > New environment variables for tuning config params cache: `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` and `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`. See [Engine Setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
> > >
> > > > [card] Project editor permissions update
> > > >
> > > > `project_editor` can no longer delete projects or modify access permissions. `projects_admin` permission now grants full project management capabilities. See [Roles Permissions Matrix](/5.1/setup-guides/access-management/roles-permissions-matrix).
> > >
> > > > [card] Advancing partition counter fix
> > > >
> > > > Fixed an issue where the advancing partition counter could go negative, causing event processing failures. Improves reliability in integration-designer and process-engine.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.4 is fully compatible with 5.1.3. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.3 → 5.1.4 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.4](./deployment-guidelines-v5.1.4).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.5-february-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.4 → 5.1.5** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.5 delivers bug fixes and stability improvements:
>
> * Fixes for process loop rendering issues in the Angular renderer
> * Fix for subprocess output data not being returned from embedded processes
> * No breaking changes — fully compatible upgrade from 5.1.4

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.5 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer and process engine fixes for process loop scenarios
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes
> > >
> > > Issues resolved in the Angular renderer:
> > >
> > > > [accordion] Validation shown without user interaction on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task for the second time, form validation errors were displayed immediately without any user interaction. Validation now correctly waits for user input before showing errors.
> > >
> > > > [accordion] Action executed continuously on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task that had a UI action configured on a form element, the action was executed continuously in a loop. Actions are now correctly triggered only on user interaction.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Subprocess not returning output from embedded process
> > > >
> > > > **Summary:**
> > > >
> > > > When a subprocess (call activity) was started from an embedded process, the output data was not passed back to the parent process instance after completion. Data mapping from subprocess to parent now works correctly in embedded process scenarios.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.5 is fully compatible with 5.1.4. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.4 → 5.1.5 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.5](./deployment-guidelines-v5.1.5).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026

Bug fixes, stability improvements, and platform enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.5 → 5.1.6** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.6 delivers bug fixes and stability improvements:
>
> * Multiple React and Angular renderer fixes for modals, sliders, buttons, and accessibility
> * Data mappers autocomplete fix for values not loading
> * Process engine fix for advancing getting stuck on pod crash with multiple partition events
> * Kafka health check fix for reporting UP despite consumer DNS failure
> * New health indicator for runtime MongoDB connection
> * Connection leak fix in application-manager export/import operations
> * Improved retry mechanism with configurable exponential backoff
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.5

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.6 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer, process engine, and application manager fixes
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Retry mechanism enhancements and security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes (React)
> > >
> > > Issues resolved in the React renderer:
> > >
> > > > [accordion] Clear icon present and clickable on disabled input/textarea
> > > >
> > > > **Summary:**
> > > >
> > > > When an input or textarea component was disabled, the clear icon was still visible and clickable. The clear icon is now hidden and non-interactive on disabled components.
> > >
> > > > [accordion] Options list not shown when selectors are inside modal
> > > >
> > > > **Summary:**
> > > >
> > > > When select or multiselect components were placed inside a modal, the options list was not displayed when opened. Selector dropdowns now render correctly within modal contexts.
> > >
> > > > [accordion] Datepicker calendar shown behind modal
> > > >
> > > > **Summary:**
> > > >
> > > > When a datepicker was placed inside a modal, the calendar popup appeared behind the modal overlay. The datepicker calendar now renders above the modal with correct z-index stacking.
> > >
> > > > [accordion] Slider min/max value not set when loading a screen
> > > >
> > > > **Summary:**
> > > >
> > > > When a slider shared a process data key with an input, or when slider min/max values depended on computed values from another slider, the min/max values were not set on load. Slider initialization now correctly applies min/max values and computed dependencies.
> > >
> > > > [accordion] Slider default value not set with multiple sliders on same page
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple sliders were present on the same page, some sliders did not receive their default values, especially when no explicit null value was set in the data store. Default value initialization now works correctly for all sliders on a page.
> > >
> > > > [accordion] Task management assignee clear icon clickable when disabled
> > > >
> > > > **Summary:**
> > > >
> > > > In the task management view, the assignee field's clear icon was visible and clickable even when the field was disabled (non-editable). The clear icon is now hidden when the assignee field cannot be edited.
> > >
> > > > [accordion] Input, select, datepicker, textarea, and table filters have incorrect inner outline
> > > >
> > > > **Summary:**
> > > >
> > > > Multiple form components displayed an incorrect inner outline styling. The outline now only appears during keyboard navigation, following proper accessibility patterns.
> > >
> > > > [accordion] Data mappers autocomplete values not loading
> > > >
> > > > **Summary:**
> > > >
> > > > Data mapper autocomplete suggestions were not loading values in certain configurations. Autocomplete now correctly fetches and displays available values.
> >
> > > [tab] Renderer fixes (Angular + React)
> > >
> > > Issues resolved in both Angular and React renderers:
> > >
> > > > [accordion] Card height does not update when accordion is collapsed
> > > >
> > > > **Summary:**
> > > >
> > > > When a card component with fixed height contained an accordion, the card height did not update when the accordion was collapsed. Card height now correctly recalculates when accordion state changes.
> > >
> > > > [accordion] Focus outline appears when interacting with card/file preview accordion
> > > >
> > > > **Summary:**
> > > >
> > > > When interacting with a card or file preview component that included an accordion, an unwanted focus outline appeared. The focus outline is now only displayed during keyboard navigation.
> > >
> > > > [accordion] Button icon not correctly rendered
> > > >
> > > > **Summary:**
> > > >
> > > > When a button was configured with a right-aligned icon, fill width, and right-aligned typography, the icon was not aligned with the text, the gap was missing, and text and icon were center-aligned instead of right-aligned. Button icon layout now respects all configured alignment and spacing settings.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Advancing gets stuck when multiple events are available for one partition and pod crashes
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple events were available for the same partition and a pod crashed, only the first event was picked up and the rest remained stuck. Event processing now correctly handles all pending events after a pod recovery.
> > >
> > > > [accordion] Kafka health check reported UP despite consumer DNS failure
> > > >
> > > > **Summary:**
> > > >
> > > > The Kafka health check indicator could report UP even when consumers had DNS resolution failures, masking connectivity issues. Health indicators now correctly reflect the actual state of Kafka consumer connections.
> > >
> > > > [accordion] Health indicator for runtime MongoDB connection
> > > >
> > > > **Summary:**
> > > >
> > > > A new health indicator has been added to monitor the runtime MongoDB connection. This improves observability and allows operators to detect MongoDB connectivity issues through the standard health endpoint.
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Theme not imported during build import
> > > >
> > > > **Summary:**
> > > >
> > > > When importing a build that included theme resources, the theme was not correctly imported. Build import now includes theme resources as expected.
> > >
> > > > [accordion] Connection leak in export/import services
> > > >
> > > > **Summary:**
> > > >
> > > > During import/export operations, database connections were held for the entire duration of long-running operations (MinIO file transfers, REST calls, Kafka messaging), which could exhaust the connection pool. Transaction boundaries have been refined so that database connections are only held during actual database operations.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Process engine
> > >
> > > > [accordion] Configurable retry mechanism with exponential backoff
> > > >
> > > > **Summary:**
> > > >
> > > > The retry mechanism for optimistic locking in the process engine now uses an Equal Jitter strategy and supports runtime configuration via environment variables. Previously, the jitter was nullified by the max delay cap, causing retrying threads to collide at the same millisecond.
> > > >
> > > > New environment variables for the `process-engine`:
> > > >
> > > > | Environment Variable | Description | Default Value |
> > > > | - | - | - |
> > > > | `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` |
> > > > | `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` |
> > > > | `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` |
> > > >
> > > > > [!TIP]
> > > > >
> > > > > Default settings give a total retry window of \~1.2 seconds, which covers most transient optimistic lock conflicts. Increase `FLOWX_RETRY_MAX_RETRIES` or `FLOWX_RETRY_MAX_DELAY_MS` if you see retry exhaustion under high contention.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Removed deprecated access rights endpoint
> > > >
> > > > **Summary:**
> > > >
> > > > A deprecated endpoint and its associated test for access rights have been removed from the codebase as they are no longer needed.
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across all platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.6 is fully compatible with 5.1.5. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.5 → 5.1.6 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.6](./deployment-guidelines-v5.1.6).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.7 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.7-march-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.6 → 5.1.7** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.7 delivers bug fixes and stability improvements:
>
> * Fix for build import issues with manifest (reimport failures)
> * Security patches
> * No breaking changes, fully compatible upgrade from 5.1.6

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.7 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Build import fix
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Build reimport failures with manifest issues
> > > >
> > > > **Summary:**
> > > >
> > > > When reimporting a build, the import could fail due to manifest validation issues, either stopping mid-import or reporting that the build was already being imported. Build reimport now correctly handles manifest validation and prevents duplicate import conflicts.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.7 is fully compatible with 5.1.6. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.6 → 5.1.7 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.7](./deployment-guidelines-v5.1.7).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.8 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.8-april-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.7 → 5.1.8** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.8 delivers security patches and dependency upgrades:
>
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.7

***

**What's new? 🆕**

> [tab] Highlights
>
> Security patches and dependency upgrades across platform components.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.8 is fully compatible with 5.1.7. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.7 → 5.1.8 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.8](./deployment-guidelines-v5.1.8).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.9 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.9-may-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.8 → 5.1.9** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.9 delivers notable bug fixes alongside security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Android renderer fixes
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.8

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Advancing workers** — Improved connection management so advancing workers no longer accumulate database connections across cooldown and rampup cycles, preventing connection growth on long-running runtime deployments.
> > > > * **Reusable UI templates** — Fixed an issue where input and output mappings on reusable UI templates could be silently lost when a referenced library version was updated.
> > > > * **Designer** — Fixed server errors when bulk-editing UI templates and when patching UI actions inside reusable UI templates.
> > > > * **Android renderer** — Fixed sticky container behavior across nested hierarchy levels, and deferred the custom loader display until CMS resources are available.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.9 is fully compatible with 5.1.8. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.8 → 5.1.9 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.9](./deployment-guidelines-v5.1.9).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10

Component versions and deployment notes for FlowX.AI 5.10 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.10 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.10.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.10.0 |
| - | - |
| **admin** | 11.18.0 |
| **advancing-controller** | 11.12.0 |
| **application-manager** | 11.18.0 |
| **audit-core** | 11.11.0 |
| **authorization-system** | 11.14.0 |
| **cms-core** | 11.14.0 |
| **data-search** | 11.11.0 |
| **data-sync** | 11.9.0 |
| **designer** | 11.36.1 |
| **document-plugin** | 11.19.0 |
| **email-gateway** | 11.15.0 |
| **events-gateway** | 11.14.0 |
| **file-gateway** | 11.14.0 |
| **integration-designer** | 11.24.2 |
| **license** | 11.13.0 |
| **nosql-db-runner** | 11.14.0 |
| **notification-plugin** | 11.14.0 |
| **organization-manager** | 11.14.0 |
| **process-engine** | 11.19.3 |
| **runtime-manager** | 11.18.0 |
| **scheduler-core** | 11.11.0 |
| **task-management-plugin** | 11.15.0 |
| **webhook-gateway** | 11.13.0 |

### AI base components

| Component | 5.10.0 |
| - | - |
| **embedder** | 11.2.0 |
| **knowledgebase-indexer-v2** | 11.2.0 |
| **knowledgebase-rag** | 11.2.0 |
| **doc-parser** | 11.2.0 |

### AI dev-time components

| Component | 5.10.0 |
| - | - |
| **ai-gateway** | 11.15.1 |
| **ai-analyst** | 11.2.0 |
| **ai-assistant** | 11.2.0 |
| **ai-designer** | 11.2.0 |
| **ai-developer** | 11.2.0 |
| **kb-enrichment** | 11.2.0 |
| **planner** | 11.2.0 |

### AI runtime components

| Component | 5.10.0 |
| - | - |
| **agent-builder** | 11.2.0 |
| **data-privacy** | 11.2.0 |
| **doc-converter** | 11.2.0 |
| **dynamic-classifier** | 11.2.0 |
| **evals-judge** | 11.2.0 |
| **speech-to-text** | 11.2.0 |
| **web-crawler** | 11.2.0 |

### AI extensions

| Component | 5.10.0 |
| - | - |
| **modpod** | 11.2.0 |
| **observatory-api** | 11.0.2 |
| **observatory-platform** | 11.0.2 |
| **observatory-web** | 11.0.2 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments receive them, re-verified, with the next LTS release.

### New Kafka topics

| Topic | Producer → Consumer | Purpose |
| - | - | - |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin → process-engine | Resource cache eviction |
| `ai.flowx.config.params.events.v1` | application-manager → process-engine | Config-param change notifications |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine → integration-designer | Runtime-instance termination |
| `ai.flowx.evals.suggestions.job.request.v1` / `.response.v1` | integration-designer | Evals suggestions job requests and responses |

### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them when your environment moves to 5.10.

This release also adds a new AI Platform component, **dynamic-classifier** (listed under AI runtime components above), which backs document classification.

In `admin`, the single `FLOWX_FEATUREAVAILABILITY_AISERVICENAME` setting is replaced by two, reflecting the split between AI dev-time and AI runtime services: `FLOWX_FEATUREAVAILABILITY_AIDEVTIMESERVICENAME` (default `ai-gateway-mngt`) and `FLOWX_FEATUREAVAILABILITY_AIRUNTIMESERVICENAME` (default `agent-builder-mngt`).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.10.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026

What's new in FlowX.AI 5.10: PostgreSQL and SOAP data sources, AI Developer script-node code generation, file uploads in chat-driven apps, and AI and document-intelligence improvements.

[FlowX.AI 5.10 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.10.0.html)

> [!NOTE]
>
> **FlowX.AI 5.10 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments receive them with the next LTS release.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release adds PostgreSQL and SOAP data sources, multi-file upload in chat-driven apps, and a set of AI and document-intelligence capabilities, alongside broader audit coverage, roles that travel with copied resources, and workflow data-partitioning improvements.

***

**What's new?**

> [tab] Core & Platform
>
> 🗂️ [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions\
> 📑 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources\
> ⚡ [**Platform performance and fixes**](#platform-performance-and-fixes) - Task-manager user fetch, project versioning, export/merge

> [tab] Designer & Renderer
>
> 💬 [**Chat file upload**](#chat-file-upload) - Attach multiple files in conversational apps\
> ⬇️ [**File download component**](#file-download-component) - Download files from a rendered app (web and Android)\
> 🔀 [**Conditional event-handler triggers**](#conditional-event-handler-triggers) - Fire event handlers based on a condition\
> 🎨 [**Image color property**](#image-color-property) - Color control on the IMAGE component\
> 💾 [**Save local variable**](#save-local-variable-action) - Capture a collection row into local data on click\
> 🪟 [**Global header and footer**](#global-header-and-footer) - Consistent header and footer across a UI Flow\
> 🧩 [**Reusable UI templates**](#reusable-ui-templates) - Action mapping, undo/redo, and dependency-version fixes

> [tab] Integrations & Data
>
> 🐘 [**PostgreSQL data source**](#postgresql-data-source) - Connect workflows directly to PostgreSQL and run SQL queries\
> 🧼 [**SOAP integration**](#soap-integration) - Import a WSDL and call SOAP operations from workflows\
> 🧮 [**FlowX Database aggregation**](#flowx-database-aggregation) - MongoDB aggregation pipelines\
> 🗄️ [**Documents tab in database testing**](#documents-tab-in-database-testing) - Inspect data while testing DB operations

> [tab] AI & Documents
>
> 📊 [**Tabular data extraction node**](#tabular-data-extraction-node) - Read spreadsheets and CSV into workflow data\
> 🔁 [**Knowledge Base error handling**](#knowledge-base-error-handling-and-retry) - Retry failed KB ingestion\
> ✨ [**AI Developer: script-node code**](#ai-developer-generate-script-node-code) - Generate node code from a prompt\
> 🧪 [**AI evaluation experiments**](#ai-evaluation-experiments) - Multiple datasets and improvement suggestions\
> 🛡️ [**AI node output reliability**](#ai-node-output-reliability) - Schema validation with auto-repair and clearer run errors\
> 📝 [**Template Filling node**](#template-filling-node) - Generate documents from templates in workflows\
> 🗂️ [**File manipulation nodes**](#file-manipulation-nodes) - Combine and split files in workflows\
> 📄 [**DOCX document generation**](#docx-document-generation) - Generate documents as DOCX in addition to PDF\
> 🏷️ [**Document Tag**](#document-tag-renamed-from-document-type) - "Document Type" renamed\
> 🔑 [**Mistral model provider**](#mistral-model-provider) - Bring your own Mistral API key

### **Expanded audit logging**

> [card] Broader audit coverage for access and lifecycle actions
>
> Audit logging now records a wider set of actions: **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> All Deployments

### **Copy with roles**

> [card] Roles travel with copied resources
>
> Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> All Deployments

### **Platform performance and fixes**

> [card] Platform performance and fixes
>
> > [tab] Performance
> >
> > The task manager fetches users through the authorization-system instead of calling Keycloak directly, cutting per-request identity lookups.&#x20;
> >
> > MongoDB partition archiving scales for large datasets, with partition-ID backfill for legacy data and archiving fixes on PostgreSQL and Oracle.&#x20;
>
> > [tab] Bug fixes
> >
> > > [accordion] Core platform fixes
> > >
> > > * **Project selector:** projects without a work-in-progress branch are correctly shown as unavailable.&#x20;
> > > * **Start Solution:** no longer fails with "no entry point set" until the page is refreshed.&#x20;
> > > * **Export and merge:** fixed errors when exporting a project build with imported libraries and when merging project versions, including a 500 during merge.&#x20;
> > > * **Merge-conflict checks:** no longer fail on processes that contain conflicts.&#x20;
> > > * **Allocation roles:** candidate-user search works for users without runtime permissions on the asset.&#x20;
> > > * **Version switching:** the selected resource opens when changing app versions, and reusable-function code refreshes on version switch.&#x20;
> > > * **Process engine:** resolved an incident-save deadlock.&#x20;
> > > * **FlowX Database:** inserting a document with a reserved `_id` key is now rejected with a clear error instead of breaking later reads.&#x20;
>
> All Deployments

### **PostgreSQL data source**

> [card] Connect to PostgreSQL databases from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds **PostgreSQL** as a data source type, alongside Oracle. Connect a workflow directly to a PostgreSQL database and run SQL queries against it as a workflow node, without a custom REST wrapper. See the [PostgreSQL Database](/5.9/docs/platform-deep-dive/integrations/postgresql-database) documentation.
>
> > [tab] Key Features
> >
> > > [card] Direct connection
> > >
> > > Configure host, port, database, schema, and credentials, with an optional SSL connection and a **Test connection** check before saving.
> >
> > > [card] SQL query operations
> > >
> > > Define SQL query operations on the data source and call them from workflow nodes.
> >
> > > [card] Connection pool tuning
> > >
> > > Advanced settings cover pool size, connection and query timeouts, keep-alive, and a validation query.
> >
> > > [card] Familiar experience
> > >
> > > Shares the same configuration and operations experience as the existing Oracle data source.
>
> SaaS

### **SOAP integration**

> [card] Call SOAP web services from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds a **SOAP System** data source. Import the service's **WSDL** — from a URL or an uploaded file — and FlowX discovers the operations with their input, output, and fault schemas, composes the SOAP envelope at runtime, and lets you call each operation from workflows through a **SOAP Operation** node. See the [SOAP System](/5.9/docs/platform-deep-dive/integrations/soap-system) documentation.
>
> > [tab] Key Features
> >
> > > [card] WSDL import
> > >
> > > Preview and select the operations to import; re-import refreshes schemas while preserving your edits
> >
> > > [card] Typed variables
> > >
> > > Envelope variables extracted from the input XSD, referenced as workflow parameters
> >
> > > [card] SOAP 1.1 and 1.2
> > >
> > > Version derived from the WSDL, with standard headers set automatically
> >
> > > [card] Testing built in
> > >
> > > Test operations with value overrides, a curl preview, and full request/response envelopes in run logs
>
> SaaS

### **Reusable UI templates**

> [card] Reusable UI template fixes
>
> Reusable UI templates get more reliable action mapping, undo/redo, and dependency-version handling.
>
> All Deployments

### **Chat file upload**

> [card] Attach multiple files in conversational apps
>
> End users can attach multiple files at once in chat-driven apps, and conversational workflows can receive those files as input. Uploaded files are extracted and indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content. Configurable in the Designer and themable, with runtime support on the web renderer.
>
> Session knowledge bases are isolated per conversation and per tenant, and are excluded from app export.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **File download component**

> [card] Download files from a rendered app
>
> A new File Download component lets end users download files directly from a rendered app. Configured in the Designer, with runtime support on web and Android.
>
> For more information, see the [File download](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download) documentation.
> SaaS

### **Conditional event-handler triggers**

> [card] Fire event handlers based on a condition
>
> Event handlers can now fire conditionally, configured in the Designer and honored by the web and Android renderers.
>
> For more information, see the [event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers) documentation.
> SaaS

### **Image color property**

> [card] Color control on the IMAGE component
>
> The IMAGE component now honors a color property, configured in the Designer and rendered on web and Android.
>
> See the [Image component](/5.9/docs/building-blocks/ui-designer/ui-component-types/image) documentation.
> SaaS

### **Save local variable action**

> [card] Capture a collection row into local data
>
> Event handlers gain a **Save Local Variable** action type: on a component inside a collection, it saves the clicked row's item into local data under a configurable key, entirely client-side with no backend roundtrip — useful for capturing the selected row before a follow-up action fires. Not available inside Reusable UI Templates.
>
> See the [Save Local Variable](/5.9/docs/building-blocks/ui-designer/event-handlers#save-local-variable) documentation.
> SaaS

### **Global header and footer**

> [card] Consistent header and footer across a UI Flow
>
> UI Flows can now define a **global header and footer** that display consistently across every page of the flow. Each holds content components — containers, forms, buttons, links, custom components — with fixed or static positioning (header fixed by default), so you can build persistent navigation or action bars in one place instead of per page.
>
> See the [Global Header and Footer](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer) documentation.
> SaaS

### **Tabular data extraction node**

> [card] Extract spreadsheet and CSV data into workflows
>
> A new workflow node reads a spreadsheet or CSV file and returns its contents as structured JSON in the node's response key, so the data can drive conditions and data operations downstream. Each row is returned as an object keyed by the file's header row, and for Excel files you can select which sheet to read.
>
> For more information, see the [Tabular Data Extraction node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node) documentation.
> SaaS

### **Knowledge Base error handling and retry**

> [card] Recover from failed Knowledge Base ingestion
>
> When Knowledge Base ingestion fails, the Knowledge Base page now shows a clear failure status and reason, and a **Retry** button re-runs the last operation after cleaning up partial content so the store is not left inconsistent. The **Update Knowledge Base** workflow node gains a **FAIL** exit handle with per-operation rollback.
>
> Learn more about [Knowledge Bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview).
> SaaS

### **AI Developer: generate script-node code**

> [card] Generate script-node code with AI Developer
>
> In the workflow designer, a script node can call **AI Developer** to generate or refactor its code from a natural-language prompt. Output streams into the test area for a **Keep** or **Discard** review, with edits shown as a diff. Supports JavaScript and Python, and respects existing AI Developer permissions.
>
> Learn more about [AI Developer](/5.9/ai-platform/pre-built-agents/ai-developer).
> SaaS

### **FlowX Database aggregation**

> [card] Aggregation pipelines in FlowX Database
>
> The FlowX Database data source adds MongoDB **aggregation pipeline** support, so configurators can group, join, reshape, and compute across documents beyond what a single query allows.
>
> Learn more about the [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) data source.
> SaaS

### **AI evaluation experiments**

> [card] Richer AI evaluation experiments
>
> > [tab] Multiple datasets
> >
> > An evaluation experiment can run against **multiple datasets** at once (datasets sharing the same AI node), with overall metrics aggregated across them and a dataset column added to the report.
>
> > [tab] Improvement suggestions
> >
> > Experiment reports now show **AI-generated suggestions** for improving the node's prompt, grouped per LLM-as-judge evaluator, beneath the score cards.
>
> Learn more about [AI evaluations](/5.9/ai-platform/evaluations).
> SaaS

### **AI node output reliability**

> [card] Schema validation with auto-repair and clearer run errors
>
> > [tab] Validation and repair
> >
> > When an AI node has a **Response Schema**, the response is validated against it and automatically retried with a repair prompt on mismatch. Nodes that still fail return a **categorized error** instead of passing malformed output downstream, and the node's **Logs** show the failure reason, rejected output, the model's reasoning summary, and the retry count.
>
> > [tab] Schema placeholders
> >
> > Response schemas now support `${variable}` placeholders resolved at runtime against workflow data, with substituted values coerced to the schema-declared types — consistent with how other AI-node fields resolve placeholders.
>
> See [AI node types](/5.9/ai-platform/agent-builder/node-types#structured-output-validation-and-run-diagnostics) for details.
> SaaS

### **Template Filling node**

> [card] Generate documents from templates in workflows
>
> Integration workflows gain a **Template Filling** node, under **Tools** in the node palette, that generates a document from a document template populated with workflow data. Select a template and language, fill the template's variables from workflow data, and choose **PDF** or **DOCX** output. The generated file's ID and download path are returned on the node's response key.
>
> See the [Template Filling node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) documentation.
> SaaS

### **File manipulation nodes**

> [card] Combine and split files in workflows
>
> Integration workflows add two document nodes, under **Tools** in the node palette: **Combine Files** merges multiple PDFs into one in a given order, and **Split File** breaks a PDF into multiple files by page ranges or one file per page. Both bring document handling that was previously process-only into workflows.
>
> See the [Combine Files](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) documentation.
> SaaS

### **DOCX document generation**

> [card] Generate documents as DOCX
>
> Template-based document generation can now produce **DOCX** files in addition to PDF. Set `outputFormat` (`PDF` or `DOCX`; defaults to `PDF`) on the generation request, or pick the format from the new **Output format** dropdown when testing a template in the Designer. Generated DOCX files preserve the template's styles, data, and images. Barcodes apply to PDF output only.
>
> Learn more in the [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output) documentation.
> SaaS

### **Document Tag (renamed from Document Type)**

> [card] Document Type is now Document Tag
>
> The **Document Type** field is renamed **Document Tag** across the surfaces where a document is tagged for storage (Upload File action, Document-Plugin REST responses, AI Document Generation, and the Web Page Extractor). This is a label change; behavior is unchanged.
> SaaS

### **Documents tab in database testing**

> [card] Inspect data while testing database operations
>
> The Database Query testing modals gain a **Documents** tab, so you can inspect the database right after running an operation. Multi-record operations report an affected-record count.
> SaaS

### **Mistral model provider**

> [card] Bring your own Mistral API key
>
> **Mistral** joins the model provider catalog as a bring-your-own-key provider. Add it with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability: chat, image understanding, embeddings, and document OCR. The seeded catalog covers the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed model lines.
>
> Learn more about [AI providers](/5.9/ai-platform/ai-providers).
> SaaS

***

## Deployment guidelines

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.10 deployment guidelines](./deployment-guidelines-v5.10).&#x20;


# Deployment guidelines v5.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11

Component versions and deployment notes for FlowX.AI 5.11 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.11 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.11.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.11.0 |
| - | - |
| **admin** | 11.53.0 |
| **advancing-controller** | 11.31.0 |
| **application-manager** | 11.46.0 |
| **audit-core** | 11.30.0 |
| **authorization-system** | 11.38.0 |
| **cms-core** | 11.43.0 |
| **data-search** | 11.30.0 |
| **data-sync** | 11.27.0 |
| **designer** | 11.89.1 |
| **document-plugin** | 11.47.0 |
| **email-gateway** | 11.39.0 |
| **events-gateway** | 11.34.0 |
| **file-gateway** | 11.38.0 |
| **integration-designer** | 11.62.1 |
| **license** | 11.34.0 |
| **nosql-db-runner** | 11.35.0 |
| **notification-plugin** | 11.41.0 |
| **organization-manager** | 11.38.0 |
| **process-engine** | 11.53.1 |
| **runtime-manager** | 11.46.0 |
| **scheduler-core** | 11.30.0 |
| **task-management-plugin** | 11.42.0 |
| **webhook-gateway** | 11.37.0 |

### AI base components

| Component | 5.11.0 |
| - | - |
| **embedder** | 11.3.1 |
| **knowledgebase-indexer-v2** | 11.3.1 |
| **knowledgebase-rag** | 11.3.1 |
| **doc-parser** | 11.3.1 |

### AI dev-time components

| Component | 5.11.0 |
| - | - |
| **ai-gateway** | 11.39.0 |
| **ai-analyst** | 11.3.1 |
| **ai-assistant** | 11.3.1 |
| **ai-designer** | 11.3.1 |
| **ai-developer** | 11.3.1 |
| **kb-enrichment** | 11.3.1 |
| **planner** | 11.3.1 |

### AI runtime components

| Component | 5.11.0 |
| - | - |
| **agent-builder** | 11.3.1 |
| **ai-architect** | 11.3.1 |
| **data-privacy** | 11.3.1 |
| **doc-converter** | 11.3.1 |
| **dynamic-classifier** | 11.3.1 |
| **evals-judge** | 11.3.1 |
| **speech-to-text** | 11.3.1 |
| **web-crawler** | 11.3.1 |

### AI extensions

| Component | 5.11.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.89.1` for FlowX.AI 5.11.0). The native iOS and Android renderers version independently.

| Component | 5.11.0 |
| - | - |
| **@flowx/angular-sdk** | 11.89.1 |
| **@flowx/angular-theme** | 11.89.1 |
| **@flowx/angular-ui-toolkit** | 11.89.1 |
| **@flowx/react-sdk** | 11.89.1 |
| **@flowx/react-theme** | 11.89.1 |
| **@flowx/react-ui-toolkit** | 11.89.1 |
| **@flowx/react-native-sdk** | 11.89.1 |
| **@flowx/react-native-theme** | 11.89.1 |
| **@flowx/react-native-ui-toolkit** | 11.89.1 |
| **@flowx/core-sdk** | 11.89.1 |
| **@flowx/core-theme** | 11.89.1 |
| **react-saas** | 11.89.1 |
| **iOS renderer** | 11.1.0 |
| **Android renderer** | 11.7.1 |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.11 capabilities. On SaaS they are created and managed automatically.

**Structured template data model** (document and notification templates move to the structured data model):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.sync.out.v1` | document-plugin, notification-plugin → application-manager |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | document-plugin, notification-plugin → application-manager |

**Runtime content import/export** (Knowledge Base and database content):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → ai-platform |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | ai-platform → integration-designer |

**Document classification and ML extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | ai-platform → integration-designer |

### AI Platform packaging

FlowX.AI 5.11 consolidates the AI Platform services into a single **`ai-platform` umbrella chart** (version `11.3.1`). Services that were previously deployed as standalone releases, including `doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, and `evals-judge`, now ship as subcharts of that chart and continue to run under their plain service names. On SaaS this change is applied automatically. The [component versions](#component-versions) section lists each service at its effective `11.3.1` version.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.11.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026

What's new in FlowX.AI 5.11: workflow tools and agentic RAG on Custom Agents, per-Knowledge-Base embedding models, document classification, extended response caching, subworkflow data mapping, structured template data models, and chat and UI Flow renderer improvements.

[FlowX.AI 5.11 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.11.0.html)

> [!NOTE]
>
> **FlowX.AI 5.11 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.11** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release turns Custom Agents into orchestrators that call FlowX workflows as tools and search knowledge bases agentically, adds per-Knowledge-Base embedding models with local embedders for personal-information content, and introduces document classification. It also extends response caching and subworkflow data mapping in the Integration Designer, moves document and notification templates onto the structured data model, and adds chat notifications, session ownership, and richer runtime audit to the renderers.

### What changed since 5.10.0

| 5.10.0 | 5.11.0 |
| - | - |
| Custom Agents call MCP servers, built-in tools, web search, and Knowledge Bases | + **FlowX workflows as callable tools** on a Custom Agent, with per-tool usage hints and tool-calling caps |
| Knowledge Base retrieval is a plain vector search on the org default embedding model | + **Agentic knowledge base search** and **per-KB embedding models**, including keyless local embedders for personal-information content |
| REST caching covers GET; SQL operations are cacheable | + **POST** REST responses, **file-storage** reads, and **Mongo** reads are cacheable too |
| Subworkflow input/output is raw JSON | + **Input and output mappers** on the Subworkflow node, with per-mapping test and import/export |
| Document and notification templates use a free-form key/value Data model tab | + Templates use the **structured data model** with typed attributes, validators, and Input Parameters |

***

**What's new?**

> [tab] AI & Agents
>
> 🧰 [**Workflow tools on Custom Agents**](#workflow-tools-on-custom-agents) - Attach FlowX workflows as callable agent tools, with usage hints and tool-calling caps\
> 🔎 [**Agentic knowledge base search and Show Reasoning**](#agentic-knowledge-base-search-and-show-reasoning) - Query decomposition, relevance grading, and a reasoning summary in the run log\
> 🧠 [**Per-knowledge-base embedding models**](#per-knowledge-base-embedding-models) - Pick an embedding model per KB and keep personal-information content on a local embedder\
> 🗂️ [**Knowledge Base content lifecycle**](#knowledge-base-content-lifecycle) - Delete entries by metadata filter, structured failure handling, per-chunk timestamps\
> 🏷️ [**Document classification**](#document-classification) - Train or import a classifier and route document pages in a workflow\
> 💬 [**Conversational chat reply requirement**](#conversational-chat-reply-requirement) - A conversational run that never replies to chat now fails with a clear error\
> ✍️ [**Custom Agent instruction limit**](#custom-agent-instruction-limit) - The Instructions field is capped at 10,000 characters

> [tab] Integrations & Data
>
> 🔁 [**Reusable functions in Integration Designer**](#reusable-functions-in-integration-designer) - Call reusable functions from Script and Condition (Fork) nodes\
> ⚡ [**Extended response caching**](#extended-response-caching) - Cache POST REST, file-storage reads, and Mongo reads alongside GET and SQL\
> 🔗 [**Subworkflow data mapping**](#subworkflow-data-mapping) - Map data in and out of a subworkflow with input and output mappers\
> 📎 [**Email attachment filtering by extension**](#email-attachment-filtering-by-extension) - Filter attachments by individual file extension instead of broad categories

> [tab] Platform
>
> 🧱 [**Structured data model for templates**](#structured-data-model-for-templates) - Document and notification templates use typed attributes and Input Parameters\
> ✅ [**Data model attribute validators**](#data-model-attribute-validators) - Required, min/max, length, pattern, email, items, and currency rules on attributes\
> 🧾 [**UI Flow runtime audit**](#ui-flow-runtime-audit) - Audit workflow-instance runs, chat messages, conversation reads, and process renders\
> 📤 [**Cross-version export adaptation**](#cross-version-export-adaptation) - Exports adapt UI templates for older LTS targets by removing unsupported handlers\
> 🔐 [**Platform and runtime improvements**](#platform-and-runtime-improvements) - Runtime access-control hardening

> [tab] Renderers & UI Flows
>
> 🔔 [**Chat notifications and conversation search**](#chat-notifications-and-conversation-search) - Unread-message badge on the chat button and search across conversation history\
> 🚫 [**Disable chat input on a condition**](#disable-chat-input-on-a-condition) - A business condition can make the chat input read-only\
> 🧭 [**Navigate To form validation**](#navigate-to-form-validation) - Require form validation before a Navigate To action, on web, iOS, and Android\
> ⌛ [**Expired UI Flow sessions**](#expired-ui-flow-sessions) - Expired sessions show a session-expired screen with a start-fresh option\
> 👤 [**UI Flow session owner**](#ui-flow-session-owner) - Restrict a running session to a single user\
> 🏁 [**Process Renderer process-end handling**](#process-renderer-process-end-handling) - Run a configurable action when an embedded process ends\
> 🎛️ [**Renderer improvements**](#renderer-improvements) - Batched enumeration fetch and process-start loader alignment

### **Workflow tools on Custom Agents**

> [card] Attach FlowX workflows as callable tools on a Custom Agent
>
> > [tab] Overview
> >
> > **Before 5.11:** a Custom Agent's tools were MCP servers, built-in tools, web search, and Knowledge Base retrieval. **Now:** you can also attach FlowX workflows as callable tools.
> >
> > In the Custom Agent node's **Tools** section, add a workflow as a tool and fill the per-tool **When should the agent use this workflow?** hint that tells the agent when to call it. The agent calls the workflow like any other tool, passing arguments that match the workflow's Start-node input parameters. A workflow with no input parameters cannot be attached. Each tool call starts a fresh workflow run whose output returns to the agent, and the child run is linked in the console log.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Workflows as tools
> > >
> > > Attach up to ten workflows as tools on one Custom Agent, each with a usage hint the agent reads when deciding to call it.
> >
> > > [card] Typed arguments
> > >
> > > The agent passes arguments that match the workflow's Start-node input parameters; workflows without input parameters are not eligible.
> >
> > > [card] Tool-calling limits
> > >
> > > An agent is limited in how many tool calls it can make per run, and workflow-tool call chains are depth-limited so recursion cannot run away.
> >
> > > [card] Linked runs
> > >
> > > Each workflow tool call is a fresh run whose output returns to the agent and is linked in the console log.
>
> SaaS

### **Agentic knowledge base search and Show Reasoning**

> [card] Agentic knowledge base search and reasoning summaries
>
> > [tab] Overview
> >
> > The Custom Agent node gains **agentic knowledge base search** and a **Show Reasoning** toggle.
> >
> > With agentic search on, the agent breaks a question into sub-queries, retrieves and grades results for relevance, and retries with reworded queries if the first pass finds nothing. It is better on complex questions and uses more model calls; a single pass with three sub-queries is the default. Agentic search never returns worse results than plain retrieval. **Show Reasoning** captures the model's reasoning summary in the run and console log; the structured response and the chat reply shown to the user are unchanged.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Agentic search
> > >
> > > Turn on **Enable agentic knowledge base search**, then set **Max attempts** and **Subqueries per attempt** under Settings.
> >
> > > [card] Relevance grading
> > >
> > > Retrieved candidates are graded against the original question, with corrective retries until a relevant result is found or the attempt budget is spent.
> >
> > > [card] Show Reasoning
> > >
> > > Surface the model's reasoning in the run log without changing the answer returned to the user.
> >
> > > [card] Fail-open
> > >
> > > Agentic mode returns the same chunk metadata as plain retrieval, so citations and telemetry are unchanged.
>
> SaaS

### **Per-knowledge-base embedding models**

> [card] Per-KB embedding models and local embedders for personal information
>
> > [tab] Overview
> >
> > Knowledge Bases can now use a **per-KB embedding model**, and a KB that holds personal information can keep its content on a local embedder.
> >
> > Turn on **Containing Personal Information** on a Knowledge Base to enable a local embedding model, then pick one from the **Embedding model** list. Local embedders (for example a text-embedding-inference or Ollama endpoint, or any OpenAI-compatible endpoint) are configured as a single **CUSTOM** provider in the organization AI settings, with a free-form base URL and no API key. The embedding model is set before the first store and cannot be changed afterward. Non-personal-information Knowledge Bases use the organization's default embedding model.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See the Knowledge Base documentation.
>
> > [tab] Key Features
> >
> > > [card] Per-KB model
> > >
> > > Each Knowledge Base carries its own embedding-model reference; a new Settings tab shows the current model.
> >
> > > [card] Local embedders
> > >
> > > Keep personal-information content on-box using a keyless local embedder fronted by a CUSTOM AI provider.
> >
> > > [card] Model travels with export
> > >
> > > Project version export preserves the KB's embedding-model reference, so a re-import keeps the same model.
> >
> > > [card] Set once per KB
> > >
> > > A Knowledge Base's embedding model is chosen before its first store and cannot be changed afterward.
>
> SaaS

### **Knowledge Base content lifecycle**

> [card] Delete entries by filter, structured failure handling, and per-chunk timestamps
>
> > [tab] Overview
> >
> > The **Update Knowledge Base** node gains a **Delete entries** operation and structured failure handling, and retrieval results now carry per-chunk metadata.
> >
> > **Delete entries** soft-deletes chunks whose entry-level metadata matches a filter, in one store or across the Knowledge Base; an empty or match-all filter is rejected so a misconfigured node cannot wipe a store. When an update operation fails, the node's **FAIL** branch returns a structured output with the operation, store, failure reason, and how many chunks were rolled back, and any partial changes are reversed. Retrieval results now include a per-chunk identifier and an ingestion timestamp.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > >
> > > See the Managing Knowledge Base content documentation.
>
> > [tab] Key Features
> >
> > > [card] Filtered deletion
> > >
> > > Delete entries by metadata filter from a workflow, with an empty or match-all filter rejected as a safety guard.
> >
> > > [card] Failure output with rollback
> > >
> > > The FAIL branch reports the operation, store, reason, and rolled-back chunk count; partial changes are reversed.
> >
> > > [card] Per-chunk timestamps
> > >
> > > RAG results carry a chunk identifier and an ingestion timestamp (empty for chunks indexed before this shipped).
> >
> > > [card] Clear retry signal
> > >
> > > Retryable failures such as extraction or chunking errors are distinguished from non-retryable ones such as size or timeout.
>
> SaaS

### **Document classification**

> [card] Classify document pages with a trainable ML model
>
> > [tab] Overview
> >
> > FlowX.AI adds **Document Classifiers**: deterministic ML models that sort document pages into categories. Define classes, upload training data, and train or import a model, then route each page in a workflow with the new **Document Classification** node.
> >
> > The node runs the active model over a document, returns a predicted label and probability per page with a configurable confidence threshold, and flags low-confidence pages. A page-level failure does not fail the node.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer documentation.
>
> > [tab] Key Features
> >
> > > [card] Train or import
> > >
> > > Build classes and training data in the Designer, then train a model or import a pre-trained one.
> >
> > > [card] Per-page classification
> > >
> > > The Document Classification node returns a label and probability for each page, with a confidence threshold and low-confidence flags.
> >
> > > [card] Deterministic routing
> > >
> > > Combine the node with a condition to route pages by their predicted category.
> >
> > > [card] Resilient runs
> > >
> > > A page that cannot be classified is reported per page without failing the whole node.
>
> SaaS

### **Conversational chat reply requirement**

> [card] Conversational runs must reply to chat
>
> A conversational (chat-driven) workflow must send at least one chat reply, either from a Custom Agent node with **Send as Chat Reply** on or from a Navigate in UI Flow node that completes the turn. A run that reaches the end without replying now fails with a clear error instead of ending silently.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **Custom Agent instruction limit**

> [card] Instructions field capped at 10,000 characters
>
> The Custom Agent **Instructions** field is now limited to 10,000 characters.
> SaaS

### **Reusable functions in Integration Designer**

> [card] Call reusable functions from Script and Condition (Fork) nodes
>
> Reusable functions can now be called from **Script** nodes and **Condition (Fork)** nodes in the Integration Designer, not just from Business Rule actions in processes. Functions are referenced in the node's JavaScript or Python and resolved at runtime from the app version's function copies, including functions that call other functions and cross-app references. A Fork node resolves the references used across all of its branch conditions.
>
> For more information, see the [reusable functions](/5.9/docs/building-blocks/reusable-resources/reusable-functions) documentation.
> SaaS

### **Extended response caching**

> [card] Cache POST REST, file-storage reads, and Mongo reads
>
> > [tab] Overview
> >
> > Response caching in the Integration Designer now covers more operation types. **POST** REST endpoints are cacheable alongside GET, with the request body forming part of the cache key so different bodies cache separately. Read **file-storage** operations (LIST and DOWNLOAD) and read **Mongo** operations (FIND, FIND\_ONE, AGGREGATE) are cacheable alongside SQL. Mutating operations are never cached.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] POST caching
> > >
> > > Cache POST responses, keyed on the request body so distinct requests stay separate.
> >
> > > [card] File-storage reads
> > >
> > > LIST and DOWNLOAD operations are cacheable; UPLOAD, DELETE, and MOVE are not.
> >
> > > [card] Mongo reads
> > >
> > > FIND, FIND\_ONE, and AGGREGATE are cacheable alongside SQL; mutating Mongo operations are not.
> >
> > > [card] Shared policy
> > >
> > > All cacheable surfaces reuse the same time-based expiry and per-operation clear-cache action.
>
> SaaS

### **Subworkflow data mapping**

> [card] Map data in and out of a subworkflow with input and output mappers
>
> > [tab] Overview
> >
> > The **Subworkflow** node adds data mapping as an alternative to raw JSON. Turn on **Enable data mapping** to define an **Input mapping** per subworkflow start node and an **Output mapping** per end node, mapping individual data slices instead of hand-editing JSON. Output mapping does not apply to asynchronous subworkflows. Each mapping opens a mapper with a test action, and mappings travel with import, export, and clone.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] Input and output mappers
> > >
> > > Map data into the subworkflow per start node and out of it per end node, without editing raw JSON.
> >
> > > [card] Per-mapping test
> > >
> > > Test a mapping with source and target slices and apply values from a past instance.
> >
> > > [card] Travels with the project
> > >
> > > Mappings are preserved on import, export, and clone.
> >
> > > [card] Async-aware
> > >
> > > Output mapping is hidden for asynchronous subworkflows, which do not return data to the caller.
>
> SaaS

### **Email attachment filtering by extension**

> [card] Filter email attachments by individual file extension
>
> Email Trigger and Microsoft Outlook data sources now filter attachments by **individual file extension** instead of the five broad file-type categories. Choose the exact extensions to accept and to forward into a process. Existing category selections are migrated to their individual extensions automatically on upgrade, so current triggers keep working.
>
> For more information, see the [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger) documentation.
> SaaS

### **Structured data model for templates**

> [card] Document and notification templates use the structured data model
>
> > [tab] Overview
> >
> > **Before 5.11:** document and notification templates declared parameters in a free-form key/value Data model tab. **Now:** templates use the same structured data model as the rest of the platform.
> >
> > On the **Data Model** tab you define typed attributes with validations, sensitive-data and reporting flags, and references to project or library data types. On the **Input Parameters** tab you select which attributes the template expects. Values sent in the request are substituted for those attributes at generation time.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > >
> > > See the notification templates documentation.
>
> > [tab] Key Features
> >
> > > [card] Typed attributes
> > >
> > > Define string, number, boolean, enum, date, currency, object, and array attributes with validations.
> >
> > > [card] Input Parameters
> > >
> > > Pick the attributes the template expects on a dedicated Input Parameters tab.
> >
> > > [card] Reference shared types
> > >
> > > Reference project and library data types like other resources.
> >
> > > [card] OTP unchanged
> > >
> > > The OTP flow contract is unchanged; the reserved `otpValue` and request `data` object work as before.
>
> SaaS

### **Data model attribute validators**

> [card] Validators on data model attributes
>
> Data model attributes now support validators. Available rules depend on the attribute type and include **Required**, **Min/Max Value**, **Min/Max Length**, **Pattern**, **Email Format**, and **Min/Max Items**, plus currency-specific amount and code rules. Validators are stored on the attribute and apply wherever that data model is used, including project, process, template, and reusable UI template data models.
>
> For more information, see the [project data model](/5.9/docs/building-blocks/project-data-model) documentation.
> SaaS

### **UI Flow runtime audit**

> [card] Audit UI Flow runtime activity
>
> UI Flow runtime sessions are now audited in more detail. The audit log records **workflow-instance** runs, chat **message sends**, conversation **list** and **history** reads, and whether the Process Renderer performed a **render** or a start. Entries name the app and the workflow instance.
>
> For more information, see the [audit](/5.9/docs/platform-deep-dive/core-extensions/audit) documentation.
> SaaS

### **Cross-version export adaptation**

> [card] Exports adapt UI templates for older LTS targets
>
> When you export a project to an older platform version, UI-template features the target version cannot understand are removed during down-adaptation, so the export imports cleanly. This currently covers Process Renderer process-end event handlers and the Navigate To **forms to validate** setting.
>
> For more information, see [Cross-version export and import](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
> All Deployments

### **Platform and runtime improvements**

> [card] Runtime access-control hardening
>
> Runtime API requests are now authorized against the roles defined in the running build across start-process, start-workflow, task views, conversation history, and the public runtime API. Requests without a matching build role are denied, and enforcement is on by default.
> All Deployments

> [card] Theme import no longer duplicates system icons
>
> Exporting a theme no longer includes duplicate copies of built-in system icons, and importing a theme no longer creates new ones. Duplicate icon copies that accumulated in earlier versions are cleaned up automatically on upgrade — no action is required.
> All Deployments

### **Chat notifications and conversation search**

> [card] Unread-message badge and conversation search in chat
>
> > [tab] Overview
> >
> > The chat floating action button gains an **unread-message notification badge**, with a themeable **Notification Dot** you can position in the chat style panel. The chat panel also adds **search across conversation history**, which filters conversations by a text query, highlights matches, and shows an empty state when nothing matches.
> >
> > For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
>
> > [tab] Key Features
> >
> > > [card] Unread badge
> > >
> > > The chat button shows a badge with the unread agent-message count; it is hidden while the chat is open in full screen.
> >
> > > [card] Notification Dot
> > >
> > > Position and size the notification dot from the chat style panel, with theme support.
> >
> > > [card] Conversation search
> > >
> > > Search conversation history from the chat panel, with highlighted matches and an empty state.
>
> SaaS

### **Disable chat input on a condition**

> [card] Make the chat input read-only with a business condition
>
> The chat **Input** component can be disabled by a business-condition expression. When the condition evaluates true, the input becomes read-only with an explanatory tooltip, and any pending attachments and voice input are cleared.
>
> For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
> SaaS

### **Navigate To form validation**

> [card] Require form validation before a Navigate To action
>
> A **Navigate To** action can now require selected forms to pass validation before navigating, matching how Start Process and Start Workflow actions gate on validation. This is available on web, iOS, and Android.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Expired UI Flow sessions**

> [card] A session-expired screen with a start-fresh option
>
> Expired UI Flow sessions now show a **session-expired** screen with a start-fresh option instead of leaving the previous data visible in read-only form. Expired and unauthorized access is written to the audit log.
> SaaS

### **UI Flow session owner**

> [card] Restrict a running session to a single user
>
> A UI Flow can restrict a running session to a single owner. When **Allow multiple editors** is off, other users who try to open the session are shown an access-denied screen, and unauthorized access is audited. Newly created flows default to single-owner; imported and existing flows keep the previous shared behavior. A session-owner value type is available for permission-based hide and disable rules.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Process Renderer process-end handling**

> [card] Run a configurable action when an embedded process ends
>
> The Process Renderer can now run a configurable action when its embedded process ends, using a new process-end trigger on event handlers. Configure what happens at that point instead of leaving the renderer idle when the process completes.
>
> For more information, see [Process end handling](/5.9/docs/building-blocks/ui-flows#process-end-handling).
> SaaS

### **Renderer improvements**

> [card] Renderer performance and behavior
>
> * **Batched enumeration fetch:** renderers batch enumeration lookups into a single bulk request, cutting the number of calls when rendering enum-backed fields. Applies to web and mobile renderers.
> * **Process-start loader alignment:** the web renderer keeps the process-start loader visible until the first user task, matching the mobile SDKs.
>   SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

FlowX.AI 5.11 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.11 deployment guidelines](./deployment-guidelines-v5.11).


# Deployment guidelines v5.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12

Component versions and deployment notes for FlowX.AI 5.12 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.12 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.12.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.12.0 |
| - | - |
| **admin** | 11.69.2 |
| **advancing-controller** | 11.46.0 |
| **application-manager** | 11.68.3 |
| **audit-core** | 11.44.1 |
| **authorization-system** | 11.53.2 |
| **cms-core** | 11.61.1 |
| **data-search** | 11.44.1 |
| **data-sync** | 11.43.1 |
| **designer** | 11.126.1 |
| **document-plugin** | 11.68.1 |
| **email-gateway** | 11.58.1 |
| **events-gateway** | 11.49.2 |
| **file-gateway** | 11.55.1 |
| **integration-designer** | 11.90.2 |
| **license** | 11.48.1 |
| **nosql-db-runner** | 11.49.1 |
| **notification-plugin** | 11.61.2 |
| **organization-manager** | 11.53.1 |
| **process-engine** | 11.76.1 |
| **runtime-manager** | 11.68.3 |
| **scheduler-core** | 11.45.1 |
| **task-management-plugin** | 11.59.2 |
| **webhook-gateway** | 11.54.1 |

### AI base components

| Component | 5.12.0 |
| - | - |
| **embedder** | 11.5.0 |
| **knowledgebase-indexer-v2** | 11.5.0 |
| **knowledgebase-rag** | 11.5.0 |
| **doc-parser** | 11.5.0 |

### AI dev-time components

| Component | 5.12.0 |
| - | - |
| **ai-gateway** | 11.53.1 |
| **ai-analyst** | 11.5.0 |
| **ai-assistant** | 11.5.0 |
| **ai-designer** | 11.5.0 |
| **ai-developer** | 11.5.0 |
| **kb-enrichment** | 11.5.0 |
| **planner** | 11.5.0 |

### AI runtime components

| Component | 5.12.0 |
| - | - |
| **agent-builder** | 11.5.0 |
| **ai-architect** | 11.5.0 |
| **data-privacy** | 11.5.0 |
| **doc-converter** | 11.5.0 |
| **dynamic-classifier** | 11.5.0 |
| **evals-judge** | 11.5.0 |
| **speech-to-text** | 11.5.0 |
| **web-crawler** | 11.5.0 |

### AI extensions

| Component | 5.12.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.126.1` for FlowX.AI 5.12.0). The native iOS and Android renderers version independently.

| Component | 5.12.0 |
| - | - |
| **@flowx/angular-sdk** | 11.126.1 |
| **@flowx/angular-theme** | 11.126.1 |
| **@flowx/angular-ui-toolkit** | 11.126.1 |
| **@flowx/react-sdk** | 11.126.1 |
| **@flowx/react-theme** | 11.126.1 |
| **@flowx/react-ui-toolkit** | 11.126.1 |
| **@flowx/react-native-sdk** | 11.126.1 |
| **@flowx/react-native-theme** | 11.126.1 |
| **@flowx/react-native-ui-toolkit** | 11.126.1 |
| **@flowx/core-sdk** | 11.126.1 |
| **@flowx/core-theme** | 11.126.1 |
| **react-saas** | 11.126.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.12 capabilities. On SaaS they are created and managed automatically.

**Event-triggered workflows** (email and webhook triggers can start an integration workflow):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Deep Research node** (the node hands research jobs to the AI Platform over Kafka):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | dead-letter queue for failed research jobs |

**Bulk process-instance migration:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |

**Notifications:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.eventsgateway.user.notifications.v1` | application-manager, process-engine → events-gateway |

**Document classification:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → dead-letter sink (not consumed) |

### New service dependency: webhook-gateway and MongoDB

The webhook gateway now reads the runtime registry that backs event-triggered workflows, so it depends on the runtime MongoDB database in addition to its existing relational database. On SaaS this connection is provisioned and managed by FlowX.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map. | none (required) | integration-designer |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today. | `k1` | integration-designer |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index. | `PT24H` | integration-designer |

### Native PostgreSQL partitioning for the engine

On PostgreSQL, the engine converts its runtime tables to native `RANGE(partition_id)` partitioning the first time it starts on the new version, and archiving then detaches a partition instead of copying rows out of it. Deployments that never enabled partitioning are skipped entirely, and Oracle deployments are unaffected.

Unlike most 5.12 changes, this one also reaches self-hosted 5.9.x in the 5.9.5 patch rather than waiting for the next LTS release family.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Whether archiving detaches partitions with `DETACH CONCURRENTLY` on natively partitioned tables. Setting it to `false` returns archiving to the previous batched insert-and-delete, but does not undo the conversion: the tables stay natively partitioned. | `true` | process-engine |

For the conversion cost, table locking and the one-way caveat, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.12.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026

What's new in FlowX.AI 5.12: parallel multi-instance subworkflow fan-out, event-triggered integration workflows, bulk process-instance migration, personal-data mask and restore nodes, and a Db2 data source.

[FlowX.AI 5.12 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.12.0.html)

> [!NOTE]
>
> **FlowX.AI 5.12 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.12** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release lets an integration workflow fan out over a collection without a subprocess, starts workflows directly from email and webhook events, and migrates process instances to a new build in bulk. It also adds personal-data mask and restore nodes to the Integration Designer and a Db2 relational data source.

### What changed since 5.11.0

| 5.11.0 | 5.12.0 |
| - | - |
| A workflow ran once per call; fanning out over a collection needed a BPMN Call Activity and a subprocess | + **Multi-instance subworkflow node** fans a workflow over a collection directly in the Integration Designer |
| An email or webhook trigger could start a process | + **Event-triggered workflows** start an integration workflow from the same triggers |
| Process instances migrated to a new build one at a time | + **Bulk migration** moves a filtered set of instances in one operation |
| Personal-data handling was configured on the agent | + **Mask and restore nodes** place it as explicit workflow steps, with details in the run log |

***

**What's new?**

> [tab] Integrations & Data
>
> 🔀 [**Multi-instance subworkflow node**](#multi-instance-subworkflow-node) - Fan a workflow out over a collection\
> ⚡ [**Event-triggered workflows**](#event-triggered-workflows) - Start a workflow from an email or webhook\
> 🗄️ [**Db2 relational data source**](#db2-relational-data-source) - Connect to Db2 for i or Db2 LUW\
> 🔻 [**Subworkflow failure exit**](#subworkflow-failure-exit) - Send a failed mapping down its own branch\
> 🔓 [**Skip TLS verification on a REST data source**](#skip-tls-verification-on-a-rest-data-source) - Reach a trusted internal host with an untrusted certificate\
> 🔔 [**Send Notification node**](#send-notification-node) - Send a templated notification straight from a workflow

> [tab] AI Platform
>
> 🛡️ [**Personal-data mask and restore nodes**](#personal-data-mask-and-restore-nodes) - Explicit workflow steps with run-log detail\
> 🧩 [**Reusable functions as agent tools**](#reusable-functions-as-agent-tools) - Give an agent a deterministic function to call\
> 👍 [**Chat response feedback**](#chat-response-feedback) - Let users rate an agent's answer, and theme how it looks\
> 📏 [**Custom evaluators**](#custom-evaluators) - Score an agent against a rubric you write yourself\
> 🔍 [**Deep Research node**](#deep-research-node) - Research a question across the open web and file a cited report\
> 🛠️ [**Built-in agent tools by category**](#built-in-agent-tools-by-category) - Twenty ready-made tools an agent can use, picked by category\
> 🪄 [**AI Designer builds UI Flows**](#ai-designer-builds-ui-flows) - Generate and edit multi-page UI Flows from a description

> [tab] Platform
>
> 📦 [**Bulk process-instance migration**](#bulk-process-instance-migration) - Move a filtered set of instances to a new build\
> 🔎 [**Runtime list filters and a Workflow Instances page**](#runtime-list-filters-and-a-workflow-instances-page) - Find the failed run without scanning the list\
> 🎨 [**Process canvas editing**](#process-canvas-editing) - Connect, reshape and resize more directly on the BPMN canvas\
> ⚠️ [**Check a version for issues**](#check-a-version-for-issues) - Validate every workflow in the version from one panel\
> 🧱 [**Reusable UI Templates in UI Flows**](#reusable-ui-templates-in-ui-flows) - Reuse a template on UI Flow pages, not just User Tasks\
> 🌿 [**Branch management**](#branch-management) - Merge to any branch, archive or delete the ones you are done with

### **Multi-instance subworkflow node**

> [card] Multi-instance subworkflow node
>
> > [tab] Overview
> >
> > **Before 5.12.0:** running an integration workflow once per item in a collection meant leaving the Integration Designer, wrapping the workflow in a BPMN process and fanning out with a multi-instance Call Activity. **Now:** the Subworkflow node fans out over an array on its own, in parallel.
> >
> > Turn on **Parallel Multi-Instance** under **Execution** on a Subworkflow node, pick the **Input Array** to iterate, and pick the **Output Array** that collects each run's result. The node starts one subworkflow instance per element of the input array and gathers the results into the output array on the parent workflow.
>
> > [tab] Key Features
> >
> > > [card] Input Array
> > >
> > > The array of objects to iterate. One subworkflow instance starts per element. Required.
> >
> > > [card] Output Array
> > >
> > > The array each instance result is collected into. Required.
> >
> > > [card] Correlation attribute
> > >
> > > Optional. Decides which output array element each result updates. Results matching no element, or all results when no attribute is set, are appended.
> >
> > > [card] Runs in parallel
> > >
> > > Instances run in parallel, and fan-out stays inside the Integration Designer instead of requiring a BPMN Call Activity.
>
> For the full configuration reference, see [Parallel multi-instance](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) on the Subworkflow node.
> SaaS

### **Event-triggered workflows**

> [card] Event-triggered workflows
>
> > [tab] Overview
> >
> > **Before 5.12.0:** an incoming email or webhook could start a process. **Now:** the same triggers can start an integration workflow directly.
> >
> > A workflow declares the trigger it listens for, and the platform keeps a subscription registry so a change to that trigger takes effect without rebuilding the whole app. Incoming email and webhook events are routed to the workflow that subscribes to them.
>
> > [tab] Key Features
> >
> > > [card] Email and webhook triggers
> > >
> > > Both trigger types can start a workflow, not only a process.
> >
> > > [card] Subscription registry
> > >
> > > Trigger changes update the affected data source without a full build recompute.
>
> > [tab] Architecture
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Trigger subscription changes | admin, integration-designer, application-manager | Design-time changes update the runtime subscription registry |
> > | Event delivery | email-gateway, webhook-gateway, integration-designer | Events are routed to the subscribing workflow |
> > | Webhook state | webhook-gateway | The webhook gateway now also reads the runtime registry, adding a MongoDB dependency it did not previously have |
> >
> > On SaaS these changes are applied automatically. See [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12) for the topic and dependency detail.
>
> For the full configuration reference, see [External triggers](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers) on the Start node.
> SaaS

### **Bulk process-instance migration**

> [card] Bulk process-instance migration
>
> > [tab] Overview
> >
> > **Before 5.12.0:** moving running process instances onto a new build was a one-at-a-time operation. **Now:** a filtered set of instances migrates in a single run.
> >
> > Select the target build, filter the instances to move, check the migration for problems before committing to it, and then run it. Progress and per-instance outcomes are available while it runs, and terminated instances are handled explicitly rather than failing the batch.
> >
> > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > See migrating process instances.
>
> > [tab] Key Features
> >
> > > [card] Filter then migrate
> > >
> > > Move specific instance UUIDs, the instances matching a process, node and status filter, or every eligible instance.
> >
> > > [card] Pre-flight check
> > >
> > > Validate a migration before running it.
> >
> > > [card] Per-instance outcomes
> > >
> > > Inspect details and results for the instances in a batch.
> >
> > > [card] Audit trail
> > >
> > > Migrations are recorded against the instances they touch.
>
> For the full configuration reference, see the [Migrate process instances](/5.9/docs/projects/runtime/active-process/migrate-process-instances) documentation.
> SaaS

### **Runtime list filters and a Workflow Instances page**

> [card] Runtime list filters and a Workflow Instances page
>
> Finding a failed run no longer means scanning an unfiltered list. The **Process Instances** and **UI Flow Sessions** lists gain a multi-select **Status** filter and a start-date filter on their columns, so "every failed instance since last night" is two clicks.
>
> Workflow runs get more: a new **Workflow Instances** page under **Runtime** lists every run in the project, filterable by **Status**, by date, and by **Origin**: whether a run was started by a process, a UI Flow, a webhook, or an email trigger. Until now, a workflow's runs were only visible from inside that workflow in the Integration Designer.
>
> For details, see the [Workflow Instances](/5.9/docs/projects/runtime/workflow-instances) documentation.
> SaaS

***

### **Personal-data mask and restore nodes**

> [card] Personal-data mask and restore nodes
>
> > [tab] Overview
> >
> > **Before 5.12.0:** personal-information handling was configured on the agent rather than placed in the flow. **Now:** masking and restoring personal data are workflow nodes you position explicitly, and you choose which key from the node input they apply to.
> >
> > Put a mask node before the step that must not see the raw values and a restore node after it. The workflow run log shows what each node did, so a run can be inspected without exposing the underlying data.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See the Personal Information Guard documentation.
>
> > [tab] Key Features
> >
> > > [card] Mask and restore as nodes
> > >
> > > Personal-data handling becomes an explicit step in the workflow.
> >
> > > [card] Selectable input key
> > >
> > > Choose which key from the node input the node applies to.
> >
> > > [card] Run-log detail
> > >
> > > A restore reports whether it completed, partially completed or failed, and how many of the issued placeholders it put back.
>
> For the full configuration reference, see [Masking and restoring across several nodes](/5.9/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
> SaaS

### **Db2 relational data source**

> [card] Db2 relational data source
>
> IBM Db2 joins the relational database data sources available in the Integration Designer. Because Db2 products use different drivers, ports and catalogs, the connection starts with a **Db2 Product** choice and the rest of the form follows from it. **Db2 for i (IBM i)** is the default and **Db2 LUW** is also supported. **Db2 for z/OS** appears in the list but is not implemented in this release, and selecting it fails with an explicit error rather than falling back to another driver.
>
> The port is prefilled from the product and whether SSL is on. Db2 for i adds a naming convention, an optional library and library list, and a switch for returning character data that the host reports as binary. On Db2 for i, connections also open **read-only by default**, so turn that off if your queries need to write, and the transaction isolation level defaults to none, because a table without a journal cannot take part in a transaction. Isolation is validated when the data source is saved rather than when a query first runs.
>
> For the full configuration reference, see the [Db2 Database](/5.9/docs/platform-deep-dive/integrations/db2-database) documentation.
> SaaS

***

### **Subworkflow failure exit**

> [card] Subworkflow failure exit
>
> A Subworkflow node now has a second exit. Connect the red one and a failure takes its own branch instead of stopping the parent workflow. It is opt-in per node, so a node without that branch fails and blocks exactly as before and nothing changes for existing workflows.
>
> Only a mapping failure routes, which is the kind a workflow can be built to handle: the input mapper failing, the input not satisfying what the subworkflow expects, or the output mapper failing on merge-back. An unset subworkflow, a missing response key, no mapping at all, and the node and depth limits all still stop the run. The branch reads a fixed `subWorkflowError` key that says which mapping failed and, when a child did start, which run it was.
>
> For the full configuration reference, see [Routing a subworkflow failure](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
> SaaS

***

### **Skip TLS verification on a REST data source**

> [card] Skip TLS verification on a REST data source
>
> A REST data source can now be told to stop checking the certificate of the host it calls, for the cases where an internal endpoint presents a self-signed or mismatched certificate and the alternative is an infrastructure workaround. It is off by default and set per data source, so turning it on for one connector leaves every other call verified.
>
> The Designer warns while it is on, because the call can no longer tell the intended host from anything intercepting it. One consequence is worth knowing before you use it: a truststore configured under Certificates is ignored while verification is skipped, since skipping replaces it rather than adding to it.
>
> For the full configuration reference, see [TLS verification](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#tls-verification) on a REST data source.
> SaaS

***

### **Send Notification node**

> [card] Send Notification node
>
> Workflows can now send notifications themselves. A **Send Notification** node, under **Tools** in the workflow node palette, takes one of your project's notification templates, fills its variables from workflow data, and sends it, without routing through a process just to reach the Notifications plugin.
>
> Address it with **To**, **Cc** and **Bcc**, as fixed addresses or `${}` keys. Email options are all overridable per node: subject, sender name and email, attachments by file path or `${}` key, and custom headers. The node reports the outcome under its response key, including recipient counts and the error when sending fails, so the workflow can branch on it.
>
> For the full configuration reference, see the [Send Notification node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node) documentation.
> SaaS

***

### **Reusable functions as agent tools**

> [card] Reusable functions as agent tools
>
> An AI node's tools can now include a **Function**, alongside built-in web search, an MCP server, and a workflow. Point an agent at a reusable function when the work is deterministic and you would rather it call your code than reason its way there.
>
> A function has to be typed to qualify: it needs both an input and an output slice, and functions without them do not appear in the picker. Give it a description as well, since that is what tells the agent when to reach for it.
>
> For the full configuration reference, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **Chat response feedback**

> [card] Chat response feedback
>
> Users can rate an agent's answer in the chat component, and follow the rating with a reason. The ratings are recorded in audit, so the quality of a deployed agent becomes something you can look at rather than guess at.
>
> The feedback controls and the reason chips are themable, with their own selected and hover states, so they can be styled to match the rest of the interface. The SDKs expose the same feedback state to custom front ends.
>
> For the full configuration reference, see [Rating an answer](/5.9/ai-platform/chat-component#rating-an-answer) on the chat component.
> SaaS

***

### **Custom evaluators**

> [card] Custom evaluators
>
> The evaluator catalogue is no longer fixed. When none of the built-in rubrics measures what you care about, you can write your own evaluator, give it the scoring instructions the judge LLM should follow, and it appears in the catalogue under a **Custom** group alongside the built-in ones.
>
> Choose **Numeric** scoring for a score between 0 and 1 with a pass threshold, or **Binary** for a straight pass or fail. You can start from an existing evaluator to adapt a built-in rubric rather than writing a prompt from scratch. Custom evaluators belong to the workflow you create them in, and unlike the built-in ones they can be edited and deleted.
>
> For the full configuration reference, see the [Evaluations](/5.9/ai-platform/evaluations#custom) documentation.
> SaaS

***

### **Deep Research node**

> [card] Deep Research node
>
> A new AI node researches a question across the open web and files a cited report into a Knowledge Base. It plans the work, sends sub-researchers out to search and read pages, grades what they bring back, and keeps going until its budget is spent or it has enough to report.
>
> Unlike a Custom Agent, you do not write the method: the research prompt is built into the node, so you describe the subject and bind workflow data into it. Depth is a **Quick**, **Standard** or **Deep** preset, or **Custom** if you want to set the number of passes and tool calls yourself. You can restrict which domains the research may read, with an allow list, a deny list, or both.
>
> The result always lands in a Knowledge Base as text, so retrieval nodes and other agents can reach it later. Rendering it as a document is optional.
>
> For the full configuration reference, see the [Deep Research node](/5.9/docs/platform-deep-dive/integrations/deep-research-node) documentation.
> SaaS

***

### **Built-in agent tools by category**

> [card] Built-in agent tools by category
>
> A Custom Agent's built-in tools are now a catalog you pick from by category: **Math tools**, **List tools**, **Date tools**, **Text tools**, and **Web search**. Each category row shows exactly which tools it turns on, and the agent runs deterministic code for that work instead of estimating it in the model.
>
> The catalog holds twenty tools, fifteen of them new: a full date family (business days, date arithmetic, formatting, parsing, timezone conversion), text helpers (regex match and extract, fuzzy match), unit conversion, and list aggregation, joining the original calculator, compare, sort, and filter. Web search is part of the same catalog rather than a separate toggle.
>
> Selection stays opt-in and per node. Agents saved with the old toggles keep working without an edit.
>
> For details, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **AI Designer builds UI Flows**

> [card] AI Designer builds UI Flows
>
> The AI Designer now works at the level of a whole UI Flow. Describe the journey and it generates a multi-page flow: structure first, pages filled in parallel, navigation wired between them. Ask for a change and it edits the affected pages instead of regenerating everything.
>
> Proposals appear on the UI Flow canvas as a draft for you to review, the editor stays locked while one is pending, and any data-model changes the flow needs are presented for approval on every turn, the same way single-screen generation already works.
>
> For details, see the [AI Designer](/5.9/ai-platform/pre-built-agents/ai-designer#ui-flow-generation-and-editing) documentation.
> SaaS

***

### **Check a version for issues**

> [card] Check a version for issues
>
> The Designer can now validate the resources in a project version and collect what it finds in one **Issues** panel at the bottom of the screen. Findings are marked where they occur, on resource lists, page titles and workflow canvas nodes, and selecting a marker opens the panel on that finding.
>
> Checks run when you ask for one, and the panel says when it last ran so a stale result is obvious. You can scope the list to the whole version, the resource you are in, or the node you have selected, filter it by severity or text, and group it by resource or severity. Opening **Commit Changes to Version** runs a check on its own and shows each changed resource's state beside it, as a review step rather than a gate. Integration workflows are the resource type validated in this first iteration.
>
> For the full configuration reference, see the [Checking a version for issues](/5.9/docs/projects/managing-applications/checking-for-issues) documentation.
> SaaS

***

### **Branch management**

> [card] Branch management
>
> Project branches gained a management layer. The merge modal now offers every branch you can merge into, not just the current branch's parents, so a fix made anywhere can land anywhere it is needed.
>
> Branches you are done with no longer linger: **Archive Branch** retires one (with a required reason, shown later in its info panel), **Unarchive Branch** brings it back, and **Delete Branch** removes one permanently, guarded so it refuses while child branches, an uncommitted draft, or a running merge depend on it, and asks you to type the branch name when unmerged work would be lost. Deleting has its own permission.
>
> Branch and version info panels round it out: a version merged from another branch says where it came from, including whether that branch has since been archived.
>
> For details, see [Managing branches](/5.9/docs/projects/managing-applications/versioning#managing-branches).
> SaaS

***

### **Process canvas editing**

> [card] Process canvas editing
>
> The BPMN canvas gains a set of direct editing improvements. A **New Node** panel and
> drop-anywhere connecting make it quicker to add a node and wire it up, connecting to a nearby
> node no longer means aiming precisely at a handle, and sequence flows can be reshaped by
> dragging their control points. Swimlanes now resize from any of their four edges. The
> process-instance viewer picks up the same canvas.
>
> The canvas is deliberately unchanged to look at, so existing diagrams, habits and screenshots
> still hold.
>
> For the full configuration reference, see [Faster ways to build](/5.9/docs/building-blocks/process/process#faster-ways-to-build) on the Process Designer canvas.
> SaaS

***

### **Reusable UI Templates in UI Flows**

> [card] Reusable UI Templates in UI Flows
>
> A Reusable UI Template can now be built for **UI Flow** pages as well as for the User Tasks in a process. Each template declares where it is used when you create it, and the UI Flow editor can drop templates onto a page the same way the Process editor always could.
>
> The host type also decides which actions a template's event handlers offer, so a template built for UI Flows gets navigation and workflow actions while one built for processes gets node actions. Because of that the choice is fixed once the template exists, and templates you created before this release count as Process templates, so nothing you already built changes.
>
> For the full configuration reference, see [Where a template can be used](/5.9/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used) in the Reusable UI Templates documentation.
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12).


# Deployment guidelines v5.13.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13

Component versions and deployment-level changes for FlowX.AI 5.13.0.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.13 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency. Self-hosted deployments receive these capabilities with the next LTS release family.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.13.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.13.0 |
| - | - |
| **admin** | 11.97.0 |
| **advancing-controller** | 11.67.0 |
| **application-manager** | 11.101.0 |
| **audit-core** | 11.69.0 |
| **authorization-system** | 11.78.0 |
| **cms-core** | 11.88.0 |
| **data-search** | 11.67.0 |
| **data-sync** | 11.68.0 |
| **designer** | 11.168.1 |
| **designer-user** | 11.8.0 |
| **document-plugin** | 11.95.0 |
| **email-gateway** | 11.83.0 |
| **events-gateway** | 11.72.0 |
| **file-gateway** | 11.79.0 |
| **integration-designer** | 11.119.1 |
| **license** | 11.72.0 |
| **nosql-db-runner** | 11.73.0 |
| **notification-plugin** | 11.88.0 |
| **organization-manager** | 11.77.0 |
| **process-engine** | 11.104.0 |
| **runtime-manager** | 11.101.0 |
| **scheduler-core** | 11.69.0 |
| **task-management-plugin** | 11.84.0 |
| **webhook-gateway** | 11.78.0 |

**designer-user** is new in 5.13. It backs the Designer notification center.

### AI base components

| Component | 5.13.0 |
| - | - |
| **embedder** | 11.6.0 |
| **knowledgebase-indexer-v2** | 11.6.0 |
| **knowledgebase-rag** | 11.6.0 |
| **doc-parser** | 11.6.0 |

### AI dev-time components

| Component | 5.13.0 |
| - | - |
| **ai-gateway** | 11.85.0 |
| **ai-analyst** | 11.6.0 |
| **ai-architect** | 11.6.0 |
| **ai-assistant** | 11.6.0 |
| **ai-designer** | 11.6.0 |
| **ai-developer** | 11.6.0 |
| **harness** | 11.6.0 |
| **ai-render-host** | 11.168.1 |
| **kb-enrichment** | 11.6.0 |
| **planner** | 11.6.0 |

**harness** and **ai-render-host** are new in 5.13. Together they run the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness): harness is the agent service, and ai-render-host renders UI flows headlessly for the agent. ai-render-host ships at the designer version.

### AI runtime components

| Component | 5.13.0 |
| - | - |
| **agent-builder** | 11.6.0 |
| **cee-pii** | 11.6.0 |
| **data-privacy** | 11.6.0 |
| **doc-converter** | 11.6.0 |
| **dynamic-classifier** | 11.6.0 |
| **evals-judge** | 11.6.0 |
| **speech-to-text** | 11.6.0 |
| **web-crawler** | 11.6.0 |

### AI extensions

| Component | 5.13.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.10.2 |
| **observatory-platform** | 11.10.2 |
| **observatory-web** | 11.10.2 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.168.1` for FlowX.AI 5.13.0). The native iOS and Android renderers version independently.

| Component | 5.13.0 |
| - | - |
| **@flowx/angular-sdk** | 11.168.1 |
| **@flowx/angular-theme** | 11.168.1 |
| **@flowx/angular-ui-toolkit** | 11.168.1 |
| **@flowx/react-sdk** | 11.168.1 |
| **@flowx/react-theme** | 11.168.1 |
| **@flowx/react-ui-toolkit** | 11.168.1 |
| **@flowx/react-native-sdk** | 11.168.1 |
| **@flowx/react-native-theme** | 11.168.1 |
| **@flowx/react-native-ui-toolkit** | 11.168.1 |
| **@flowx/core-sdk** | 11.168.1 |
| **@flowx/core-theme** | 11.168.1 |
| **react-saas** | 11.168.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

***

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.13 capabilities. On SaaS they are created and managed automatically.

**Notification center:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |

Notifications now pass through designer-user, which stores them and forwards them to events-gateway on the existing `ai.flowx.eventsgateway.user.notifications.v1` topic for delivery to the Designer.

**Move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

### New services

The Developer Agentic Harness adds the **harness** and **ai-render-host** services to the AI dev-time group, with a dedicated PostgreSQL database for harness sessions. The notification center adds the **designer-user** core service, which uses MongoDB, Redis, and Kafka. On SaaS these services and their databases are provisioned and managed by FlowX.

### New service dependency: process-engine and object storage

Oversized workflow responses and UI flow updates are now offloaded to object storage instead of travelling inline on Kafka. The process engine reads these offloaded payloads, so it now depends on object storage in addition to its existing databases. On SaaS this connection is provisioned and managed by FlowX.

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` | process-engine, audit-core |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Self-hosted deployments receive this change with the next LTS release family. A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.13.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026

What's new in FlowX.AI 5.13: a user notification center in Designer, UI component copy and paste across contexts, commit descriptions on app versions, and move token on process instances.

[FlowX.AI 5.13 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.13.0.html)

> [!NOTE]
>
> **FlowX.AI 5.13 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.13** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. The headline: the FlowX Developer Agentic Harness, an AI agent in the Designer that builds and changes apps from a description, with you confirming the plan and every operation before it runs. The release also adds a notification center to the Designer, lets builders copy and paste UI components across apps with a review of what could not be placed, records a description on every app version commit, forwards runtime events to Mixpanel and GA4, and moves stuck tokens on running process instances.

### What changed since 5.12.0

| 5.12.0 | 5.13.0 |
| - | - |
| Apps were assembled by hand in the Designer | + **Developer Agentic Harness**: describe the change, confirm the plan, review the result on its own branch |
| Long-running operations surfaced as passing toasts | + **Notification center** keeps a searchable 30-day history with read state |
| UI components copied within one context | + **Copy and paste across contexts**, with a paste review and unique naming |
| App version commits had a name only | + **Commit descriptions** and a commit details view record why a version exists |
| A stuck process instance needed support intervention | + **Move token** relocates the token, guarded by a dedicated corrective-actions role |

***

**What's new?**

> [tab] Builders
>
> 🔔 [**User notification center**](#user-notification-center) - Bell, searchable history, read state in Designer\
> 📋 [**UI component copy and paste**](#ui-component-copy-and-paste) - Cross-context paste with review and unique naming\
> 📝 [**Commit descriptions and details**](#commit-descriptions-and-details) - Optional description on version commits plus a details view\
> 📦 [**Version export alignment**](#version-export-alignment) - Version exports bundle dependencies like build exports

> [tab] Platform
>
> 🚑 [**Move token and corrective actions**](#move-token-and-corrective-actions) - Relocate a token, gated by a dedicated role

> [tab] AI Platform
>
> 🪄 [**Developer Agentic Harness**](#developer-agentic-harness) - Describe a change, the agent plans and builds it on a branch\
> 🧠 [**ML corpus import and export**](#ml-corpus-import-and-export) - Move a document classifier corpus between environments\
> ⚖️ [**Fair scheduling for embedding jobs**](#fair-scheduling-for-embedding-jobs) - Knowledge Base ingestion no longer starves small jobs\
> 🧩 [**Data Parse node**](#data-parse-node) - Tabular Data Extraction generalized, now parses XML and JSON\
> 🔐 [**File Encryption node**](#file-encryption-node) - Encrypt and decrypt files inside a workflow

> [tab] Rendering & SDKs
>
> 💬 [**React Native chat component**](#react-native-chat-component) - Floating chat sheet with voice input on mobile\
> ▶️ [**Conditional start workflow trigger**](#conditional-start-workflow-trigger) - Start a workflow from the UI only when a condition holds

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > **Before 5.13.0:** every process, screen, and data type was assembled by hand in the Designer. **Now:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys your app first, so changes use your real resources and names, then drafts a plan for you to confirm.
> >
> > You hold every gate: the agent runs only after you confirm the plan and review each operation, the change lands on a dedicated branch that never touches your main line, and merging plus serving a new version stay human decisions. See the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness) page for the full flow.
> >
> > <video>
> >   <track label="English" />
> > </video>
>
> > [tab] Key Features
> >
> > > [card] Works on your real app
> > >
> > > Surveys existing resources first, so changes use your actual processes, data types, and names.
> >
> > > [card] Plan, confirm, then run
> > >
> > > You confirm the plan and review every operation; the change runs on a dedicated branch that only you can merge or serve.
> >
> > > [card] Broad resource coverage
> > >
> > > Creates and edits processes, UI flows, workflows, and project data types.
> >
> > > [card] Guarded operations
> > >
> > > Destructive changes are gated, and runtime data such as process instances is never touched.
>
> SaaS

### **User notification center**

> [card] User notification center
>
> > [tab] Overview
> >
> > **Before 5.13.0:** long-running operations such as app imports or instance migrations announced themselves once and were gone. **Now:** a bell in the Designer opens a notification center with a 30-day history.
> >
> > Notifications carry read state, search, and filters by unread status and workspace type. First producers: app version export and process instance migration results.
>
> > [tab] Key Features
> >
> > > [card] 30-day history
> > >
> > > Notifications persist for 30 days instead of disappearing with the toast.
> >
> > > [card] Read state and search
> > >
> > > Mark notifications read, search them, and filter by unread status or workspace type.
> >
> > > [card] Export and migration results
> > >
> > > Get notified when an app version export finishes, fails, or times out, and when a process instance migration completes.
> >
> > > [card] Live updates
> > >
> > > The center updates over a live stream, including read state changes from other sessions.
>
> SaaS

### **UI component copy and paste**

> [card] UI component copy and paste
>
> > [tab] Overview
> >
> > **Before 5.13.0:** copying UI components was limited to the context you were in. **Now:** builders copy components and paste them into another UI Flow, app, or context.
> >
> > Pasting responds with a review of what could not be placed instead of failing silently, and pasted components receive unique names automatically. The clipboard holds one consistent version of the copied structure.
>
> > [tab] Key Features
> >
> > > [card] Cross-context paste
> > >
> > > Paste a copied component into a different UI Flow or app through a dedicated modal.
> >
> > > [card] Paste review
> > >
> > > The paste result names anything it could not place, so nothing drops without a trace.
>
> SaaS

### **Commit descriptions and details**

> [card] Commit descriptions and details
>
> Committing or merging an app version now takes an optional description of up to 2000 characters, and a commit details view shows what a version contains and why it exists. Version history stops being a list of names.
> SaaS

### **Version export alignment**

> [card] Version export alignment
>
> Project version exports now bundle dependencies the same way build exports do, so a version export is self-contained. The export dialog pre-selects the target platform version, and the exported filename carries the target version and whether media is included.
> SaaS

### **Move token and corrective actions**

> [card] Move token and corrective actions
>
> > [tab] Overview
> >
> > **Before 5.13.0:** a process instance stuck on the wrong node needed support intervention. **Now:** an operator with the corrective-actions role moves the token to the right node from Runtime.
> >
> > Corrective actions, covering bulk instance migration and move token, are gated by a dedicated workspace-level role, so admins grant this power without handing out full admin rights.
> >
> > The **Workspace corrective actions editor** role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically. See [Move tokens](/5.9/docs/projects/runtime/active-process/move-token) and the [Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
>
> > [tab] Key Features
> >
> > > [card] Move token
> > >
> > > Relocate the token of a running instance to another node in the process definition.
> >
> > > [card] Dedicated role
> > >
> > > A workspace-level corrective-actions role scopes who can migrate instances and move tokens.
>
> SaaS

### **ML corpus import and export**

> [card] ML corpus import and export
>
> A document classifier corpus now moves between environments: export the corpus with the model, import it into a runtime classifier, and inspect it in a read-only view in the Data tab. Training data stops being trapped in the environment where labeling happened.
> SaaS

### **Fair scheduling for embedding jobs**

> [card] Fair scheduling for embedding jobs
>
> Knowledge Base embedding jobs are scheduled fairly by default, so a large ingestion no longer starves small jobs queued behind it. Uploads to one Knowledge Base stop delaying every other one on the environment.
> SaaS

### **Data Parse node**

> [card] Data Parse node
>
> The Tabular Data Extraction node is generalized into a **Data Parse** node: it still reads CSV and Excel files into workflow data, and now also parses **XML** and **JSON**. A file fetched by a File Storage Operation can be read into the workflow regardless of its structured format.
> SaaS

### **File Encryption node**

> [card] File Encryption node
>
> A new **File Encryption** workflow node encrypts or decrypts a file with a password directly in the workflow, so protecting a generated document or opening a protected upload no longer needs a custom integration. The file path and password take expressions, letting the password come from workflow data.
> SaaS

### **React Native chat component**

> [card] React Native chat component
>
> The React Native renderer gains the chat experience mobile apps were missing: a floating chat sheet with voice input, suggested prompts, and conversation history. Renderer updates in the same release cover form validation on navigation actions, action context on execute-URL, and bulk enum fetching on eager load.
> SaaS

### **Conditional start workflow trigger**

> [card] Conditional start workflow trigger
>
> A start workflow trigger in the UI now takes a condition, so the workflow starts only when the expression holds. Available in the web SDK and on iOS.
> SaaS

### **Smaller improvements**

> [card] Smaller improvements
>
> **Process details modal:** the process name moves from Settings into a Details modal.
>
> **Document and image sources:** Document and Image UI components share one source configuration. In process user tasks, the new **Document Plugin Path** source takes a Documents plugin `downloadPath` directly, so you no longer need a business rule to build the file URL. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13) for File Preview and the [Download component](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download#file-sources-in-flowx-ai-5-13).
>
> **Sign-up link to solution:** a sign-up link lands new users directly in the right solution.
>
> **Bulk invite:** inviting many users at once gets a reworked flow.
>
> **Task list search on translated labels:** the task list searches, filters, and sorts on the labels it displays, in the viewer's language, for status, enumeration, and substitution-tag columns. See [Search and sort on translated labels](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).&#x20;
>
> **Reserved substitution-tag prefix:** custom substitution tags can no longer start with `sys_`; the prefix is reserved for system tags.&#x20;
> **Intersects operator for array fields:** FlowX Database queries can match documents whose array field shares at least one value with a given list. See [Intersects on array fields](/5.9/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).&#x20;
>
> **Request after PII anonymization in the run log:** AI nodes with the input scan enabled log the request exactly as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/5.9/ai-platform/personal-information-guard#request-after-pii-anonymization).&#x20;
>
> **Elasticsearch replica auto-expansion:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Changed default: Elasticsearch replica auto-expansion](./deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).&#x20;
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.13.0](./deployment-guidelines-v5.13).


# Deployment guidelines v5.2.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/deployment-guidelines-v5.2

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.12.0** | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **10.12.0** | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **10.7.0** | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **10.7.0** | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **10.6.0** | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **10.4.1** | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **10.6.0** | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **10.4.1** | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **10.8.0** | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **10.3.1** | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **10.4.1** | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **10.0.0** | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **10.0.0** | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.0.1** | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | **10.2.0** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.2.0 | Keycloak | 26+ |
| 5.2.0 | Kafka | 3.8 - 3.9 |
| 5.2.0 | PostgreSQL | 16 - 17 |
| 5.2.0 | Oracle Database | 21c, 23ai |
| 5.2.0 | MongoDB | 7 - 8 |
| 5.2.0 | Redis | 7.4 - 8.0 |
| 5.2.0 | Elasticsearch | 8 - 9 |
| 5.2.0 | Angular (Web SDK) | 19.2 |
| 5.2.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.2.0

### Key infrastructure updates

> [card] SpiceDB Upgrade
>
> Upgraded to SpiceDB v1.38.0+ and spice-db-operator for improved permission management and stability

> [card] Security Enhancements
>
> Updated Java libraries and base images to Oracle 10-slim, resolving HIGH and CRITICAL vulnerabilities

> [card] Accessibility Support
>
> Enhanced renderer components with comprehensive WCAG 2.1 compliance features

> [card] Python IDE Features
>
> Added autocomplete and IntelliSense support in business rules editors

> [card] Parallel Workflow Branches
>
> Support for concurrent execution paths in Integration Designer workflows

> [card] Workflow Partitioning & Archiving
>
> Time-based partitioning and automatic archiving for Integration Designer workflow instances

## Upgrading from v5.1.0

### Key changes

* **Accessibility Features**: No breaking changes, but new accessibility properties available in UI Designer
* **Database Security**: FlowX Database now supports sensitive data masking (requires Project Data Model configuration)
* **IDE Enhancements**: Python autocomplete is automatically available in business rules editors
* **Infrastructure**: SpiceDB upgrade requires cache clearing after migration

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.

### Compatibility

* **Backward Compatible**: v5.2.0 maintains backward compatibility with v5.1.0 configurations
* **Renderer Updates**: Web SDKs include accessibility enhancements without breaking changes
* **Mobile Renderers**: iOS and Android renderers include accessibility improvements

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/update-environment-variables-5.2

Update environment variables for all existing FlowX.AI services

## Integration Designer

### Workflow partitioning and archiving

> [!NOTE]
>
> Integration Designer now supports workflow instance partitioning and automatic archiving for efficient data management in high-volume deployments.

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Enable or disable workflow instance partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Time interval for creating partitions (`DAY`, `WEEK`, `MONTH`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Enable or disable automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Cron expression for archiving schedule (default: daily at 1:00 AM) |

> [!NOTE]
>
> **Workflow partitioning configuration:**
>
> * **Partitioning**: When enabled, workflow instances are stored in time-based partitions according to the specified interval
> * **Retention**: Determines how many intervals to keep active. Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> * **Archiving schedule**: The cron expression controls when the archiving process runs
> * **Best practice**: Enable partitioning first without archiving, verify it works correctly, then enable archiving

> [!WARNING]
>
> Enable partitioning and archiving only after careful planning and testing. Ensure your database has sufficient storage for partition management operations. It's recommended to start with archiving disabled and enable it only after verifying that partitioning works correctly for your use case.

### Advancing controller improvements

> [!NOTE]
>
> Integration Designer now uses the new ADVANCING controller with separate picking and processing operations for improved performance and resource management.

#### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

#### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.


# FlowX.AI 5.2.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025

Accessibility improvements, new side panel navigation, FlowX Database sensitive data handling, REST API response caching, and Python IDE enhancements for business rules development.

**What's new?**

> [tab] Accessibility & UX
>
> Making FlowX applications more inclusive and user-friendly with comprehensive accessibility improvements and enhanced navigation.
>
> ♿ [**Accessibility Enhancements**](#accessibility-enhancements) - Comprehensive [WCAG](https://www.w3.org/TR/WCAG21/) (Web Content Accessibility Guidelines) compliance features across all UI components\
> 🎨 [**New Workflow Side Panel**](#new-workflow-side-panel) - Enhanced navigation experience with improved drag-and-drop functionality
>
> ### **Accessibility enhancements**
>
> > [card] Accessibility enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds accessibility features across all UI components, enabling you to build [WCAG 2.1 Level AA compliant](https://www.w3.org/TR/WCAG21/) applications. These features support users with assistive technologies such as screen readers and keyboard-only navigation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs1.png)
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs2.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Accessibility Configuration Panel
> > > >
> > > > Configure labels, descriptions, and ARIA attributes in a dedicated accessibility section within UI Designer
> > >
> > > > [card] Auto-bindable Tags
> > > >
> > > > Bind accessibility tags automatically to buttons, inputs, selects, modals, and other UI components
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Navigate using keyboard shortcuts with proper focus management and tab order in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > Use screen readers with ARIA labels, descriptions, and live regions on all components
> >
> > > [tab] Supported Components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio buttons, Slider, and File upload components with labels and descriptions
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card components with keyboard navigation and focus management
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with alt text support and semantic HTML structure
> > >
> > > **4. Cross-Platform Support**
> > >
> > > Web (Angular/React), iOS, and Android platforms
> >
> > > [tab] Benefits
> > >
> > > > [card] WCAG Compliance
> > > >
> > > > Build applications that meet WCAG 2.1 Level AA standards for web accessibility
> > >
> > > > [card] Inclusive Design
> > > >
> > > > Make your applications usable for people with diverse abilities and assistive technology users
> > >
> > > > [card] Improved User Experience
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those using assistive technologies
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Meet accessibility requirements for government, healthcare, financial services, and other regulated industries
> >
> > Major Enhancement
>
> ***
>
> ### **New workflow side panel**
>
> > [card] New workflow side panel
> >
> > > [tab] Overview
> > >
> > > The new Workflow Side Panel provides an enhanced navigation experience in Integration Designer workflows. It includes improved organization, better drag-and-drop functionality, and intuitive access to design components and resources.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_side_panel.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Drag & Drop
> > > >
> > > > Add and organize workflow nodes with drag-and-drop functionality
> > >
> > > > [card] Improved Organization
> > > >
> > > > Group nodes logically with expandable/collapsible sections
> > >
> > > > [card] Search & Filter
> > > >
> > > > Find nodes instantly with quick search functionality
> >
> > UI/UX Enhancement
>
> ***

> [tab] Data & Security
>
> Enhanced data management and security features for FlowX Database and business rules.
>
> 🔒 [**FlowX Database Sensitive Data**](#flowx-database-sensitive-data) - GDPR-compliant sensitive data handling for FlowX Database\
> 🚀 [**Performance Improvements**](#performance-improvements) - Caching optimizations for better system performance
>
> ### **FlowX database sensitive data**
>
> > [card] FlowX database sensitive data
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds sensitive data handling for FlowX Database to ensure GDPR compliance. Attributes marked as sensitive in your Project Data Model are automatically protected across all FlowX Database operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic Data Masking
> > > >
> > > > Hide sensitive attributes automatically in logs, console outputs, and testing interfaces
> > >
> > > > [card] Project Data Model Integration
> > > >
> > > > Mark attributes as sensitive in Project Data Model to apply protection across all FlowX Database operations
> > >
> > > > [card] Developer-Friendly
> > > >
> > > > Access full data at runtime while maintaining security in design-time interfaces
> > >
> > > > [card] Audit Trail Protection
> > > >
> > > > Mask sensitive data in workflow output logs and operational documents
> >
> > > [tab] Protected Areas
> > >
> > > **1. Documents Page**
> > >
> > > Sensitive attributes are masked when viewing FlowX Database documents in the designer
> > >
> > > **2. Test Operations Pages**
> > >
> > > Database operation testing interfaces automatically hide sensitive data
> > >
> > > **3. Workflow Console**
> > >
> > > Console logs and output panels mask sensitive information from FlowX Database responses
> > >
> > > **4. Full Runtime Access**
> > >
> > > Applications have full access to sensitive data at runtime - protection is design-time only
> >
> > > [tab] Benefits
> > >
> > > > [card] GDPR Compliance
> > > >
> > > > Meet data protection requirements by preventing sensitive data exposure in design tools
> > >
> > > > [card] Security by Design
> > > >
> > > > Sensitive data protection is automatic once attributes are marked in Project Data Model
> > >
> > > > [card] Developer Productivity
> > > >
> > > > Test and develop without worrying about accidentally exposing sensitive information
> > >
> > > > [card] Audit-Ready
> > > >
> > > > Demonstrate proper data handling practices with masked logs and interfaces
> >
> > Security Enhancement
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Caching Enhancements
> > >
> > > FlowX.AI 5.2.0 adds intelligent caching mechanisms that improve system performance by reducing redundant processing when identical values are sent at process start.
> >
> > > [tab] Key Features
> > >
> > > > [card] Smart Caching
> > > >
> > > > Cache and reuse results automatically when identical input values are detected
> > >
> > > > [card] Reduced Latency
> > > >
> > > > Start processes faster when repeating operations with the same parameters
> > >
> > > > [card] Resource Optimization
> > > >
> > > > Reduce server load and improve resource utilization
> > >
> > > > [card] Automatic Management
> > > >
> > > > Manage cache automatically with no configuration required
> >
> > > [tab] Benefits
> > >
> > > **1. Response Times**
> > >
> > > Initialize processes faster in cached scenarios
> > >
> > > **2. Scalability**
> > >
> > > Handle more concurrent users with the same infrastructure
> > >
> > > **3. Cost Efficiency**
> > >
> > > Use fewer compute resources for high-volume scenarios
> >
> > Performance

> [tab] Developer Experience
>
> Enhanced tools and features for business rules development, testing, and workflow design.
>
> 🔀 [**Parallel Branches in Workflows**](#parallel-branches-in-workflows) - Design and execute parallel execution paths in Integration Designer workflows\
> 💾 [**REST API Response Caching**](#integration-designer-rest-api-response-caching) - Cache GET endpoint responses in Integration Designer with flexible TTL policies\
> 📊 [**Workflow Partitioning & Archiving**](#workflow-partitioning-&-archiving) - Manage Integration Designer workflow data efficiently with time-based partitions and automatic archiving\
> 🐍 [**Python IDE Enhancements**](#python-ide-enhancements) - Autocomplete and IntelliSense for Python business rules\
> 🧪 [**Business Rules Testing**](#functions-testing) - Save test parameters in reusable functions modal
>
> ### **Parallel branches in workflows**
>
> > [card] Parallel branches in workflows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds the ability to design and execute parallel branches in Integration Designer workflows. This enables concurrent execution of independent workflow paths and improves performance for complex integrations.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Start Parallel Node
> > > >
> > > > Split workflow execution into multiple concurrent branches with start parallel nodes
> > >
> > > > [card] End Parallel Node
> > > >
> > > > Merge parallel branches with end parallel nodes that wait for all branches to complete
> > >
> > > > [card] Path Visualization
> > > >
> > > > View which nodes belong to which parallel branch with visual path indexing in the workflow diagram
> > >
> > > > [card] Runtime Monitoring
> > > >
> > > > Track parallel path execution with timing information for each branch and merge point
> >
> > > [tab] How It Works
> > >
> > > **1. Design Parallel Paths**
> > >
> > > Add a Start Parallel node and create multiple sequences from it. Each sequence represents an independent execution path
> > >
> > > **2. Configure Branch Logic**
> > >
> > > Add workflow nodes to each parallel branch, such as API calls, transformations, or database operations
> > >
> > > **3. Merge Paths**
> > >
> > > Close parallel branches with an End Parallel node. This node waits for all branches to complete before continuing
> > >
> > > **4. Runtime Execution**
> > >
> > > All branches execute concurrently at runtime. The End Parallel node completes when the slowest branch finishes
> >
> > > [tab] Use Cases
> > >
> > > > [card] Multiple API Calls
> > > >
> > > > Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Fetch data from multiple sources in parallel for comprehensive data aggregation
> > >
> > > > [card] Notification Broadcasting
> > > >
> > > > Send notifications through multiple channels (email, SMS, push) simultaneously
> > >
> > > > [card] Document Processing
> > > >
> > > > Process different document types or sections in parallel for faster throughput
> >
> > > [tab] Runtime Behavior
> > >
> > > > [accordion] Path Timing
> > > >
> > > > * **Path Time**: Sum of all node execution times within that branch
> > > > * **End Parallel Time**: Node processing time + maximum time across all parallel paths
> > > > * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
> > >
> > > > [accordion] Console Logging
> > > >
> > > > * **Start Parallel Node**: Displays Input tab showing data split across branches
> > > > * **End Parallel Node**: Displays Output tab showing merged results from all branches
> > > > * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
> > >
> > > > [accordion] Error Handling
> > > >
> > > > * If any branch fails, the workflow handles it according to standard error handling rules
> > > > * End Parallel node waits for all non-failed branches before continuing
> > > > * Runtime validation ensures parallel branches are configured correctly
> >
> > > [tab] Limitations
> > >
> > > > [!WARNING]
> > > >
> > > > **First Iteration Constraints**: This is the initial implementation of parallel branches with the following considerations:
> > >
> > > * **Array Processing**: Arrays are not merged across parallel branches. When multiple branches modify the same array path, the last branch to complete determines the final array value. You cannot process individual objects from the same array in different parallel branches (for example, first element in branch 1, second element in branch 2). To preserve data from all branches, save to different keys and merge manually using a script before the end node
> > >
> > > * **Branch Closure**: All start parallel branches must be closed with end parallel nodes. Nodes following a start parallel node must merge into the same end parallel node, except for nodes that terminate with end workflow nodes
> > >
> > > > [!NOTE]
> > > >
> > > > Based on user feedback and raised exceptions during runtime execution, additional configuration constraints and validations are planned for future releases.
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Reduce workflow execution time by running independent operations concurrently instead of sequentially
> > >
> > > **2. Resource Utilization**
> > >
> > > Maximize throughput by executing multiple operations simultaneously
> > >
> > > **3. Design Clarity**
> > >
> > > Model concurrent operations explicitly in your workflow diagrams
> > >
> > > **4. Monitoring**
> > >
> > > Track execution time for each parallel path to identify bottlenecks
> >
> > Integration Designer
>
> ***
>
> ### **Integration Designer REST API response caching**
>
> > [card] Integration Designer REST API response caching
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces intelligent response caching for REST API GET endpoints in Integration Designer. Cache responses based on flexible Time-To-Live (TTL) policies to reduce redundant API calls, avoid rate limits, and lower operational costs while maintaining data freshness.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Endpoint_Get.png)
> > >
> > > > [!NOTE]
> > > >
> > > > When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Flexible TTL Policies
> > > >
> > > > Configure caching with "Expires after" (duration-based) or "Expires at" (time-based) policies
> > >
> > > > [card] Cache Management
> > > >
> > > > Clear cached responses from endpoint definitions or testing modals as needed
> > >
> > > > [card] Cache Status Visibility
> > > >
> > > > View cache status, keys, and TTL information in testing modals and workflow console logs
> > >
> > > > [card] Automatic Fallback
> > > >
> > > > System automatically calls the external API if cache retrieval fails, ensuring reliability
> >
> > > [tab] TTL Configuration
> > >
> > > > [accordion] Expires After (Duration-Based)
> > > >
> > > > Cache responses for a specific duration after the request is made.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **ISO Duration**: Use ISO 8601 duration format (e.g., `PT1H` for 1 hour, `P1D` for 1 day, `P1W` for 1 week)
> > > > * **Dynamic Duration**: Reference configuration parameters (e.g., `${myConfigParam}`)
> > > > * **Default**: `R/P1D` (1 day)
> > > >
> > > > **Example**: Cache for 10 minutes after each request
> > > >
> > > > ```
> > > > PT10M
> > > > ```
> > >
> > > > [accordion] Expires At (Time-Based)
> > > >
> > > > Cache responses until a specific time of day with recurring patterns.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **Expire Time**: Set specific time (e.g., `23:00` for midnight, `08:00` for 8 AM)
> > > > * **Recurrency**: Set how often the pattern repeats (integer > 0, default: 1)
> > > > * **Time Unit**: Choose Day, Week, or Month (default: Day)
> > > >
> > > > **Example**: Cache until midnight every day
> > > >
> > > > ```
> > > > Expire Time: 00:00
> > > > Recurrency: 1
> > > > Time Unit: Day
> > > > ```
> > > >
> > > > **Example**: Cache until 6 PM every Friday
> > > >
> > > > ```
> > > > Expire Time: 18:00
> > > > Recurrency: 1
> > > > Time Unit: Week
> > > > ```
> >
> > > [tab] Cache Visibility
> > >
> > > **1. Testing Modal**
> > >
> > > View cache status directly in the endpoint testing modal with:
> > >
> > > * **Cache Hit/Miss Status**: Whether results came from cache
> > > * **Cache Key**: The unique identifier for the cached response
> > > * **TTL Information**: When the cache expires (e.g., "Expires after PT10M" or "Expires at 23:00 on 2025-11-04")
> > >
> > > **2. Workflow Console**
> > >
> > > Monitor cache usage in workflow execution logs with the same detailed information
> > >
> > > **3. Clear Cache Action**
> > >
> > > Clear cached responses from the endpoint page or testing modal when cache is configured
> >
> > > [tab] How It Works
> > >
> > > **1. Configure Caching**
> > >
> > > In Integration Designer, open a REST System and navigate to a GET endpoint. Enable caching and select your TTL policy (Expires After or Expires At)
> > >
> > > **2. First Request**
> > >
> > > When the endpoint is called for the first time, the response is fetched from the external API and stored in cache with the configured TTL
> > >
> > > **3. Subsequent Requests**
> > >
> > > If the cache is still valid (within TTL), subsequent requests return the cached response immediately without calling the external API
> > >
> > > **4. Cache Expiration**
> > >
> > > Once TTL expires, the next request fetches fresh data from the external API and updates the cache
> > >
> > > **5. Cache Management**
> > >
> > > Use the "Clear Cache" action to manually invalidate cached responses when needed (e.g., after data updates)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Reference Data
> > > >
> > > > Cache country lists, product catalogs, or other reference data that rarely changes
> > >
> > > > [card] Rate Limit Avoidance
> > > >
> > > > Reduce API calls to third-party services with strict rate limits
> > >
> > > > [card] Cost Optimization
> > > >
> > > > Lower operational costs by reducing billable API calls to external services
> > >
> > > > [card] Performance
> > > >
> > > > Improve workflow execution speed by eliminating network latency for cached responses
> >
> > > [tab] Error Handling
> > >
> > > > [!WARNING]
> > > >
> > > > **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. This ensures your workflows always receive correct data.
> > >
> > > **Failure Scenarios**:
> > >
> > > * Cache service unavailable → Direct API call
> > > * Cache corruption or invalid data → Direct API call
> > > * Cache storage failure → Direct API call (with warning logged)
> > >
> > > Your workflows continue to function normally even if caching fails.
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced API Costs
> > > >
> > > > Minimize charges from external APIs by serving cached responses when data hasn't changed
> > >
> > > > [card] Improved Performance
> > > >
> > > > Return responses instantly from cache instead of waiting for external API calls
> > >
> > > > [card] Rate Limit Compliance
> > > >
> > > > Stay within API rate limits by reducing the number of requests to external services
> > >
> > > > [card] Better Scalability
> > > >
> > > > Handle higher workflow volumes without increasing external API calls
> >
> > Integration Designer
>
> > [card] [REST Endpoint Caching](../../../5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching)
> >
> > Learn how to configure caching policies, manage cache, and optimize your REST API integrations
>
> ***
>
> ### **Workflow partitioning & archiving**
>
> > [card] Workflow partitioning & archiving
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces workflow instance partitioning and archiving for Integration Designer. This feature enables efficient management of workflow data by organizing instances into time-based partitions and automatically archiving old data to maintain optimal database performance in large-scale deployments.
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow partitioning is particularly beneficial for high-volume Integration Designer workflows where instances accumulate over time, helping to maintain query performance and manage storage efficiently.
> >
> > > [tab] Key Features
> > >
> > > > [card] Time-Based Partitioning
> > > >
> > > > Organize workflow instances into partitions based on configurable time intervals (Day, Week, or Month)
> > >
> > > > [card] Automatic Archiving
> > > >
> > > > Automatically archive partitions older than the specified retention period to optimize active database size
> > >
> > > > [card] Flexible Retention Policies
> > > >
> > > > Configure how many time intervals to retain before archiving with granular control
> > >
> > > > [card] Scheduled Archiving
> > > >
> > > > Use cron expressions to schedule archiving operations at optimal times
> >
> > > [tab] Configuration
> > >
> > > Configure workflow partitioning using environment variables in Integration Designer:
> > >
> > > > [accordion] Partitioning Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ENABLED`**: Enable or disable workflow instance partitioning
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_INTERVAL`**: Time interval for creating partitions
> > > >   * Default: `MONTH`
> > > >   * Options: `DAY`, `WEEK`, `MONTH`
> > >
> > > > [accordion] Archiving Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`**: Enable or disable automatic archiving
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`**: Number of intervals to retain before archiving
> > > >   * Default: `3`
> > > >   * Options: Any positive integer
> > > >   * Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`**: Schedule for archiving operations
> > > >   * Default: `0 0 1 * * ?` (runs daily at 1:00 AM)
> > > >   * Options: Any valid cron expression
> >
> > > [tab] How It Works
> > >
> > > **1. Enable Partitioning**
> > >
> > > Set `FLOWX_DATA_PARTITIONING_ENABLED=true` to start organizing workflow instances into time-based partitions
> > >
> > > **2. Configure Partition Interval**
> > >
> > > Choose a partition interval (DAY, WEEK, or MONTH) based on your workflow volume and retention needs
> > >
> > > **3. Set Retention Policy**
> > >
> > > Define how many intervals to retain. For example, with MONTH interval and 3 retention intervals, data older than 3 months will be archived
> > >
> > > **4. Enable and Schedule Archiving**
> > >
> > > Turn on archiving and configure the cron expression to run archiving operations during low-traffic periods
> > >
> > > **5. Monitor Performance**
> > >
> > > Track database performance improvements as old partitions are archived and active data size is optimized
> >
> > > [tab] Use Cases
> > >
> > > > [card] High-Volume Workflows
> > > >
> > > > Maintain performance for Integration Designer workflows processing thousands of instances daily
> > >
> > > > [card] Compliance Requirements
> > > >
> > > > Archive historical workflow data while maintaining access to recent instances for operational needs
> > >
> > > > [card] Database Optimization
> > > >
> > > > Keep active database size manageable by automatically moving old data to archive partitions
> > >
> > > > [card] Long-Running Deployments
> > > >
> > > > Prevent database bloat in production environments running for extended periods
> >
> > > [tab] Best Practices
> > >
> > > > [!WARNING]
> > > >
> > > > **Planning and Testing Required**: Enable partitioning and archiving only after careful planning and testing. Once enabled:
> > > >
> > > > * Ensure sufficient database storage for partition management operations
> > > > * Start with archiving disabled to verify partitioning works correctly
> > > > * Test thoroughly in non-production environments before enabling in production
> > > > * Monitor database performance during initial archiving operations
> > > > * Choose partition intervals based on your workflow volume and retention requirements
> > >
> > > **Recommended Approach**:
> > >
> > > 1. Enable partitioning first without archiving
> > > 2. Monitor partition creation and database performance
> > > 3. After verifying stable operation, enable archiving
> > > 4. Schedule archiving during low-traffic periods (e.g., overnight)
> > > 5. Start with longer retention periods and adjust based on requirements
> >
> > > [tab] Benefits
> > >
> > > > [card] Improved Performance
> > > >
> > > > Maintain fast query performance as workflow instance count grows over time
> > >
> > > > [card] Efficient Storage
> > > >
> > > > Optimize database storage by archiving historical data while keeping recent data accessible
> > >
> > > > [card] Automatic Management
> > > >
> > > > Set retention policies once and let the system handle archiving automatically
> > >
> > > > [card] Scalability
> > > >
> > > > Support long-running production deployments with predictable database growth
> >
> > Integration Designer
>
> > [card] [Integration Designer Setup](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration)
> >
> > Learn how to configure workflow partitioning and archiving for Integration Designer
>
> ***
>
> ### **Python IDE enhancements**
>
> > [card] Python IDE enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds professional IDE features to Python business rules development, including autocomplete, IntelliSense, and enhanced code editing capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Autocomplete
> > > >
> > > > Get intelligent code suggestions as you type, including Python standard library and FlowX APIs
> > >
> > > > [card] IntelliSense
> > > >
> > > > Use context-aware code completion with parameter hints and documentation
> > >
> > > > [card] Syntax Highlighting
> > > >
> > > > Read code more easily with enhanced Python syntax highlighting
> > >
> > > > [card] Error Detection
> > > >
> > > > Detect syntax errors in real-time with helpful error messages
> >
> > > [tab] Benefits
> > >
> > > **1. Development Speed**
> > >
> > > Write business rules faster with intelligent code suggestions
> > >
> > > **2. Error Reduction**
> > >
> > > Catch syntax errors before deployment with real-time validation
> > >
> > > **3. API Discovery**
> > >
> > > Discover available APIs and methods through IntelliSense
> > >
> > > **4. Professional Experience**
> > >
> > > Use IDE-quality editing features directly in FlowX Designer
> >
> > Developer Tools
>
> ***
>
> ### **Functions testing**
>
> > [card] Functions testing
> >
> > > [tab] Overview
> > >
> > > Test Reusable Functions more efficiently by saving test parameters directly from the testing modal. This enables faster iteration and better test coverage.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Save Test Parameters
> > > >
> > > > Save test inputs directly from the testing modal and reuse them in future test runs
> > >
> > > > [card] Test History
> > > >
> > > > Access previously saved test parameters for regression testing
> > >
> > > > [card] Faster Iteration
> > > >
> > > > Re-test functions quickly with saved parameter sets
> > >
> > > > [card] Test Coverage
> > > >
> > > > Build a library of test cases for comprehensive function validation
> >
> > > [tab] Benefits
> > >
> > > **1. Quality**
> > >
> > > Test functions more thoroughly to improve quality
> > >
> > > **2. Time Savings**
> > >
> > > Avoid re-entering test data for each test iteration
> > >
> > > **3. Documentation**
> > >
> > > Use saved test cases as examples of how to use the function
> >
> > Testing Enhancement

> [tab] Additional Improvements
>
> Platform improvements, security updates, and bug fixes.
>
> 🌍 [**Task Management Localization**](#task-management-localization) - Comprehensive localization support with automatic table grid localization and 51 substitution tags\
> 🔧 [**Platform Enhancements**](#platform-enhancements) - Infrastructure upgrades and security improvements\
> 🐛 [**Bug Fixes**](#bug-fixes) - Resolved issues and stability improvements
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds comprehensive localization support for Task Management, enabling you to customize all user-facing text elements including table columns, filters, and actions. This allows you to deliver Task Management experiences in multiple languages:
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> >
> > > [tab] Key Features
> > >
> > > > [card] Table Grid Localization (Automatic)
> > > >
> > > > Data table components (filters, menus, pagination, data types) are automatically localized based on container app language
> > >
> > > > [card] Substitution Tags (Manual)
> > > >
> > > > Configure 51 system substitution tags in CMS to localize table columns, task actions, and UI elements
> > >
> > > > [card] Multi-language Support
> > > >
> > > > Support for 34 languages including Arabic, Chinese, Japanese, Korean, and European languages
> > >
> > > > [card] Task Action Localization
> > > >
> > > > Localize all task actions, statuses, and workflow-related text elements
> >
> > > [tab] Localization components
> > >
> > > > [accordion] Table Grid Locale Keys
> > > >
> > > > FlowX Task Management uses a comprehensive table grid localization system. These keys are **automatically applied** by FlowX.AI based on your container app language and cover all table functionality:
> > > >
> > > > * **Filters**: Set filters, text filters, number filters, date filters with all operators (equals, contains, starts with, etc.)
> > > >
> > > > * **Menus**: Column menus, context menus, aggregation functions, sorting options
> > > >
> > > > * **Pagination**: Page navigation, page size selectors, row counts
> > > >
> > > > * **Data Types**: Boolean values, dates, numbers with proper formatting
> > > >
> > > > * **Advanced Features**: Pivot mode, charting, column grouping, and row operations
> > > >
> > > > * **ARIA Labels**: Accessibility labels for screen readers and assistive technologies
> > > >
> > > > > [!NOTE]
> > > > >
> > > > > **Automatic Localization**: Table grid locale keys are automatically translated by FlowX.AI based on your container app language. No manual configuration or setup required.
> > >
> > > > [accordion] FlowX substitution tags (51 keys)
> > > >
> > > > Use these substitution tags in CMS to localize custom Task Management interface elements. All tags include English default values:
> > > >
> > > > **Search & Navigation**
> > > >
> > > > * `sys_tm_search` - "Search"
> > > >
> > > > **Table Columns**
> > > >
> > > > * `sys_tm_title` - "Title"
> > > > * `sys_tm_stage` - "Stage"
> > > > * `sys_tm_assignee` - "Assignee"
> > > > * `sys_tm_status` - "Status"
> > > > * `sys_tm_priority` - "Priority"
> > > > * `sys_tm_last_updated` - "Last updated"
> > > >
> > > > **Process States (Status Values)**
> > > >
> > > > * `sys_tm_created` - "Created"
> > > > * `sys_tm_started` - "Started"
> > > > * `sys_tm_finished` - "Finished"
> > > > * `sys_tm_finished_with_error` - "Finished with error"
> > > > * `sys_tm_failed` - "Failed"
> > > > * `sys_tm_expired` - "Expired"
> > > > * `sys_tm_aborted` - "Aborted"
> > > > * `sys_tm_terminated` - "Terminated"
> > > > * `sys_tm_dismissed` - "Dismissed"
> > > > * `sys_tm_on_hold` - "On hold"
> > > >
> > > > **Bulk Actions**
> > > >
> > > > * `sys_tm_assign_to` - "Assign to…"
> > > > * `sys_tm_unassign_all` - "Unassign All"
> > > > * `sys_tm_assign_all_to_me` - "Assign All to me"
> > > > * `sys_tm_hold_all` - "Hold All"
> > > > * `sys_tm_unhold_all` - "Unhold All"
> > > >
> > > > **Task Actions**
> > > >
> > > > * `sys_tm_view_application` - "View Application"
> > > > * `sys_tm_unassign` - "Unassign"
> > > > * `sys_tm_assign_to_myself` - "Assign to myself"
> > > > * `sys_tm_unhold` - "Unhold"
> > > > * `sys_tm_hold` - "Hold"
> > > > * `sys_tm_assign` - "Assign"
> > > > * `sys_tm_execute` - "Execute"
> > > > * `sys_tm_start` - "Start"
> > > >
> > > > **Task Details Sections**
> > > >
> > > > * `sys_tm_assignee_deactivated` - "(Deactivated)"
> > > > * `sys_tm_comments` - "Comments"
> > > > * `sys_tm_write_a_comment` - "Write a comment…"
> > > > * `sys_tm_history` - "History"
> > > >
> > > > **History Events**
> > > >
> > > > * `sys_tm_task_created` - "Task created"
> > > > * `sys_tm_user_created_this_task` - "`${user}` created this task"
> > > > * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
> > > > * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
> > > > * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
> > > > * `sys_tm_task_moved_to` - "Task moved to"
> > > > * `sys_tm_task_status_changed_to` - "Task status changed to"
> > > > * `sys_tm_task_assigned_to` - "Task assigned to"
> > > > * `sys_tm_task_owner_removed` - "Task owner removed"
> > > >
> > > > **User Selection & Search**
> > > >
> > > > * `sys_tm_select_person` - "Select person..."
> > > > * `sys_tm_search_person` - "Search users"
> > > > * `sys_tm_search_term_validation` - "Type at least 4 characters..."
> > > >
> > > > **UI States**
> > > >
> > > > * `sys_tm_loading` - "Loading..."
> > > > * `sys_tm_nothing_found` - "Nothing Found"
> > > >
> > > > **Data Display**
> > > >
> > > > * `sys_tm_in` - "In" (custom filter operator)
> > > >
> > > > * `sys_tm_yes` - "Yes" (boolean value)
> > > >
> > > > * `sys_tm_no` - "No" (boolean value)
> > > >
> > > > > [!WARNING]
> > > > >
> > > > > **\*\*Manual Configuration Required**: These 51 FlowX substitution tags must be configured manually in CMS for each language. They control custom Task Management UI elements outside of the data table.
> >
> > > [tab] Implementation
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization (300+ keys for filters, menus, pagination, data types) based on this setting
> > >
> > > **2. Configure FlowX Substitution Tags in CMS**
> > >
> > > Add translations for all 51 FlowX substitution tags (sys\_tm\_\*) in CMS for each supported language. These control custom Task Management UI elements (task actions, bulk operations, history events, comments)
> > >
> > > **3. Configure Custom Column Names (Optional)**
> > >
> > > If you need custom columns beyond the defaults, use substitution tags for column display names in your Task Management configuration
> > >
> > > **4. Test Localization**
> > >
> > > Verify complete localization:
> > >
> > > * **Table grid elements** (automatic): filters, sorting, pagination, menus should display in container app language
> > >
> > > * **FlowX custom elements** (CMS): task actions, bulk operations, history events, comments should use your CMS translations
> > >
> > > > [!NOTE]
> > > >
> > > > **Simple Setup**: Configure only the 51 FlowX substitution tags in CMS. Table grid localization (300+ keys) is handled automatically by the platform.
> >
> > > [tab] Benefits
> > >
> > > > [card] Global Reach
> > > >
> > > > Deploy Task Management to users worldwide with native language support
> > >
> > > > [card] Consistent Experience
> > > >
> > > > Provide a fully localized experience across all Task Management components
> > >
> > > > [card] Easy Maintenance
> > > >
> > > > Manage translations centrally through CMS substitution tags
> > >
> > > > [card] Professional Quality
> > > >
> > > > Leverage professional translations for data grid components with automatic localization
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> > [card] [Task Management Overview](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
> >
> > Learn about Task Management features and configuration
>
> > [card] [Process Settings](../../../5.1/docs/building-blocks/process/process-definition#integrate-with-task-manager)
> >
> > Configure Task Management integration in process settings
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform Enhancements
> >
> > FlowX.AI 5.2.0 includes platform improvements focused on security, stability, and infrastructure.
> >
> > ## Security & Infrastructure Updates
> >
> > > [card] Vulnerability Fixes
> > >
> > > Update Java libraries and base images to address security vulnerabilities
> >
> > > [card] SpiceDB Upgrade
> > >
> > > Upgrade SpiceDB with new operator version
> >
> > > [card] Dependency Updates
> > >
> > > Update platform dependencies to latest secure versions
> >
> > ## Additional improvements
> >
> > > [card] Permission-based UI
> > >
> > > Add permission-based UI functionality in Reusable UI Templates
> >
> > > [card] Database Query Improvements
> > >
> > > Improve FlowX Database query handling and error messages
> >
> > > [card] System Substitution Tags
> > >
> > > Use system substitution tags in task management texts in CMS
> >
> > > [card] SSE Disconnect Handling
> > >
> > > Handle Server-Sent Events disconnections better to reduce log noise
> >
> > > [card] [Integration Designer Environment Variables](./update-environment-variables-5.2)
> > >
> > > Update environment variables for improved advancing controller with separate picking and processing operations, see details [here](./update-environment-variables-5.2)
> >
> > Platform Updates
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes & stability improvements
> >
> > FlowX.AI 5.2.0 includes bug fixes and stability improvements to improve the overall user experience.
> >
> > ## Notable fixes
> >
> > > [accordion] Fixes
> > >
> > > * **Process Instances Page**: Fix error when opening Runtime process instances page
> > > * **Resource Import**: Fix import requests that use incorrect content type
> > > * **Elasticsearch Updates**: Fix engine errors when updating documents in older indexes
> > > * **Navigation Tree**: Fix navigation tree response for overridden processes
> > > * **Dependency Management**: Fix errors when updating library dependency versions
> >
> > > [accordion] UI/UX fixes
> > >
> > > * **Accessibility**: Fix missing accessibility sections on various components
> > > * **Theme Configuration**: Fix element selection issues in segmented button panel
> > > * **Modal Behavior**: Improve modal focus management and keyboard navigation
> > > * **Select Components**: Fix highlighting and navigation issues in select/multiselect
> > > * **Task Manager**: Fix browser freeze when opening table configuration
> >
> > > [accordion] Renderer fixes
> > >
> > > * **Angular SDK**: Fix keyboard navigation issues with select components and shift+tab behavior
> > > * **React SDK**: Fix option highlighting and keyboard navigation in various components
> > > * **Workflow Display**: Fix rendering issues in Integration Designer workflows
> > > * **Collection Components**: Fix card expansion issues with accordions in navigation areas
> >
> > > [accordion] Backend fixes
> > >
> > > * **Events Gateway**: Improve SSE disconnect handling to reduce error log flooding
> > > * **Database Operations**: Improve error handling and validation for FlowX Database queries
> > > * **Process Navigation**: Fix back button redirects from process definitions
> > > * **Warning Management**: Clean up warnings properly when deleting parent actions

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.2.0](./deployment-guidelines-v5.2).
>
> ### Environment variables updates
>
> > [!NOTE]
> >
> > For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
>
> ### Coming soon
>
> Additional features currently in development for future releases:
>
> * Extended accessibility support for iOS and Android platforms
> * Additional Python IDE capabilities
> * Enhanced FlowX Database query preview and optimization tools


# Deployment guidelines v5.3.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/deployment-guidelines-v5.3

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.29.0** | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 |
| **admin** | **10.26.1** | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 |
| **designer** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **cms-core** | **10.16.0** | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 |
| **scheduler-core** | **10.11.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **events-gateway** | **10.12.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **notification-plugin** | **10.17.0** | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **document-plugin** | **10.16.0** | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 |
| **task-management-plugin** | **10.18.0** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 |
| **data-search** | **10.10.1** | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 |
| **audit-core** | **10.15.1** | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **advancing-controller** | **10.11.0** | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 |
| **integration-designer** | **10.24.0** | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 |
| **application-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **runtime-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **data-sync** | **10.14.1** | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 |
| **authorization-system** | **10.18.1** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - |
| **nosql-db-runner** | **10.10.1** | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **iOS renderer** | **10.1.0** | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 |
| **Android renderer** | **10.1.0** | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 |

### Plugins

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.1** | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 |
| **di-platform** | **10.2.5** | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 |
| **ai-platform-ai-developer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-connected-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agents** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-conversations** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-models** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-tenants** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-planner** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-analyst** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-designer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agent-builder** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-binaries** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.3.0 | Keycloak | 26+ |
| 5.3.0 | Kafka | 3.8 - 3.9 |
| 5.3.0 | PostgreSQL | 16 - 17 |
| 5.3.0 | Oracle Database | 21c, 23ai |
| 5.3.0 | MongoDB | 7 - 8 |
| 5.3.0 | Redis | 7.4 - 8.0 |
| 5.3.0 | Elasticsearch | 8 |
| 5.3.0 | Angular (Web SDK) | 19.2 |
| 5.3.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.3.0

### Key features and updates

> [card] UI Flows
>
> Build multi-platform applications with reusable UI components across web, iOS, and Android

> [card] UI Events
>
> Real-time user interaction handling with event-driven UI components

> [card] Workflow Data Models
>
> Workflow-level data models with input/output parameters and process-to-workflow data mapping

> [card] Mobile Accessibility
>
> WCAG 2.1 accessibility compliance extended to iOS and Android platforms

> [card] Custom Component Enhancements
>
> Standardized custom component integration across all platforms

> [card] SaaS Capabilities
>
> Multi-tenant SaaS capabilities with organization management

## Upgrading from v5.2.0

### Breaking changes

> [!WARNING]
>
> **FlowX Engine Configuration Changes**: The partitioning and archiving configuration structure has been reorganized. If you have enabled data partitioning, you **must** update your configuration files before or immediately after upgrading.

> [card] [Complete migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
>
> See the detailed migration guide with step-by-step instructions, configuration examples, and troubleshooting

### Key changes

* **UI Flows**: New feature for building multi-platform reusable UI components
* **Workflow Data Models**: Enhanced integration between processes and workflows with structured data models
* **Mobile Accessibility**: iOS and Android renderers now support WCAG 2.1 accessibility standards
* **Configuration Structure**: Breaking change in FlowX Engine partitioning/archiving configuration (see preceding section)

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.

### Compatibility

* **Breaking Changes**: FlowX Engine partitioning/archiving configuration structure has changed (action required if using partitioning)
* **Feature Additions**: UI Flows, UI Events, and Workflow Data Models are new features with no breaking changes
* **Renderer Updates**: Web and mobile SDKs include new features with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/migration-overview

Migration guide for upgrading from FlowX.AI v5.2.0 to v5.3.0

> [!NOTE]
>
> FlowX.AI v5.3.0 is an incremental update from v5.2.0 with one breaking change related to FlowX Engine configuration structure.

## What's changing

FlowX.AI v5.3.0 introduces a breaking change to the FlowX Engine partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings have been reorganized under `partitioning.archiving`.

## Who is affected

> [!WARNING]
>
> This breaking change **only affects** deployments that have:
>
> * Enabled data partitioning in FlowX Engine (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings (`SCHEDULER_DATAPARTITIONING_ENABLED=true`)
>
> If you have not enabled these features, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

## Migration process

**1. Review configuration changes**

Understand the new configuration structure and identify which settings need to be updated in your deployment

**2. Update configuration files**

Update your FlowX Engine configuration files (YAML or environment variables) following the migration steps

**3. Deploy and verify**

Deploy the updated configuration and verify that partitioning and archiving continue to work correctly

## Key changes summary

### Configuration structure

**What's removed:**

* `scheduler.dataPartitioning` section with `enabled` and `cronExpression` settings

**What's added:**

* `partitioning.archiving` subsection containing all archiving-related settings

**What's moved:**

* `retention-intervals` moved from `partitioning` to `partitioning.archiving`
* `detached-partition-compression` moved to `partitioning.archiving`
* `moved-data-batch-size` moved to `partitioning.archiving`
* `cronExpression` moved from `scheduler.dataPartitioning` to `partitioning.archiving`

### Environment variables

5 environment variables have been renamed to reflect the new structure:

| Old Variable | New Variable |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` |

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility**: The old configuration structure is not supported in v5.3.0 and causes FlowX Engine startup errors.
>
> You must update your configuration before or immediately after upgrading to v5.3.0.

## Rollback support

If you need to rollback from v5.3.0 to v5.2.x:

1. Revert your configuration files to the previous structure
2. Restore environment variables to their previous names
3. Downgrade the FlowX Engine container/pod to the previous version

> [!NOTE]
>
> Database schema changes are forward-compatible. Ensure you have database backups before any upgrade.

> [!NOTE]
>
> This is a configuration-only change. No code changes, data migration, or schema updates are required.

## Next steps

## Additional resources

> [card] [Partitioning & Archiving Setup](/5.1/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving)
>
> Complete guide to FlowX Engine partitioning and archiving

> [card] [Deployment Guidelines v5.3.0](../deployment-guidelines-v5.3)
>
> Component versions and deployment instructions

> [card] [Release Notes v5.3.0](../v5.3.0-december-2025)
>
> Full release notes for v5.3.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/update-environment-variables-5.3

Update environment variables for all existing FlowX.AI services

## FlowX Engine

### Partitioning and archiving configuration restructure

> [!NOTE]
>
> FlowX.AI v5.3.0 reorganizes the partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings are now under `partitioning.archiving`.

#### Variables to remove

If you are using environment variables to override FlowX Engine configuration, remove these variables:

| Remove This Variable | Reason |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |

#### Variables to replace

| Old Variable Name | New Variable Name | Default Value | Description |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of partition intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression level for archived partitions (Oracle only): `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for moving data during archiving (PostgreSQL only) |

#### New variables structure

The archiving configuration is now nested under `partitioning.archiving`:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Turn on or off data partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Partition interval: `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Turn on or off automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Schedule expression for archiving operations (default: daily at 1:00 AM) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression for archived partitions (Oracle only) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for data movement (PostgreSQL only) |

> [!NOTE]
>
> **Configuration structure changes:**
>
> * **Removed**: `scheduler.dataPartitioning` section
> * **Added**: `partitioning.archiving` subsection with all archiving-related settings
> * **Unchanged**: Core partitioning settings (`enabled`, `interval`) remain at `partitioning` level
> * **Moved**: Archiving-specific settings (`retention-intervals`, `cronExpression`, `detached-partition-compression`, `moved-data-batch-size`) are now under `partitioning.archiving`

> [!WARNING]
>
> **Action required if using partitioning:**
>
> If you have enabled data partitioning in FlowX Engine, you **must** update your configuration:
>
> 1. **YAML configuration**: Update your `application.yml` to follow the new structure (see [Deployment Guidelines](../deployment-guidelines-v5.3#breaking-changes))
> 2. **Environment variables**: Update variable names as shown in the tables above
> 3. **Deployment order**: Update configuration before or immediately after upgrading to v5.3.0

#### Configuration examples

> [tab] Environment Variables (Before)
>
> ```bash theme={"dark"}
> # Old structure (v5.2 and earlier)
> SCHEDULER_DATAPARTITIONING_ENABLED=true
> SCHEDULER_DATAPARTITIONING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS=3
> FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [tab] Environment Variables (After)
>
> ```bash theme={"dark"}
> # New structure (v5.3.0)
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true
> FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS=3
> FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [!NOTE]
>
> **Impact assessment:**
>
> This change only affects deployments that have:
>
> * Enabled data partitioning (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings
>
> If partitioning is disabled, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

### New optional variables

| Variable | Default Value | Description |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Falls back to `KAFKA_TOPIC_PATTERN` if not set | Dedicated topic pattern for FlowX connectors, separate from other platform components like document-plugin, data-search, and cms-core |

> [!NOTE]
>
> The `KAFKA_TOPIC_CONNECTOR_PATTERN` variable allows you to configure a custom Kafka topic pattern specifically for FlowX connectors without affecting other platform components.

> [card] [Complete migration guide](migration-overview)
>
> See the Deployment Guidelines for complete configuration examples, step-by-step migration instructions, and troubleshooting guidance.


# FlowX.AI 5.3.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025

UI Flows for multi-platform app building, UI Events for real-time interactions, enhanced custom component integration, and mobile accessibility improvements.

**What's new?**

> [tab] App builder & reusability
>
> Build multi-platform applications faster with UI Flows, enhance real-time interactions with UI Events, and integrate custom components across all platforms.
>
> 📱 [**UI Flows**](#ui-flows) - Build multi-platform applications with reusable UI components across web, iOS, and Android\
> ⚡  [**UI Events**](#ui-events) - Real-time user interaction handling with event-driven UI components\
> 🧩 [**Custom Component Enhancements**](#custom-component-enhancements) - Enhanced integration for custom components with standardized data mapping\
> 📤 [**File Upload Improvements**](#file-upload-improvements) - Enhanced file upload experience with better loading states and user feedback\
> ♿ [**Mobile Accessibility**](#mobile-accessibility) - WCAG 2.1 accessibility compliance for iOS and Android platforms\
> 🏢 [**Cross Workspace Projects**](#cross-workspace-projects) - Share projects across multiple workspaces for flexible environment testing\
> 🎯 [**Collection & Table Actions**](#collection-and-table-actions) - Execute actions from collections and tables in UI Flows
>
> ### **UI flows**
>
> > [card] UI flows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Flows, a powerful new capability that enables you to build reusable, multi-platform user interfaces that work across web (Angular/React), iOS, and Android applications. UI Flows separate UI definitions from process logic, enabling better reusability and faster application development without the overhead of full BPMN processes.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flows revolutionize how you build applications by allowing you to create a UI once and deploy it across all platforms, dramatically reducing development time and ensuring consistent user experiences.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Unnecessary process complexity
> > > >
> > > > Some use cases do not need a mapping of the business case in BPMN and the complexity and overhead that a FlowX process entails
> > >
> > > > [card] Subprocess overhead
> > > >
> > > > Unnecessary subprocess layers inside processes added complexity for simple UI scenarios
> > >
> > > > [card] Tight UI-process coupling
> > > >
> > > > UI definitions were tightly coupled to process logic, reducing reusability and increasing maintenance
> > >
> > > > [card] Platform-specific development
> > > >
> > > > Building the same UI for multiple platforms required separate implementations for each platform
> >
> > > [tab] Key Features
> > >
> > > > [card] UI Flows as project resources
> > > >
> > > > UI Flows are managed as independent project resources, separate from process definitions
> > >
> > > > [card] Navigation areas management
> > > >
> > > > Manage Navigation Areas inside UI Flows Designer for structured navigation and layout
> > >
> > > > [card] Start process UI action
> > > >
> > > > Launch FlowX processes directly from UI Flows, bridging UI and process execution
> > >
> > > > [card] Navigate to UI action
> > > >
> > > > Setup navigation to Nav areas or Container elements through scroll for seamless UX
> > >
> > > > [card] Task Manager component
> > > >
> > > > Embed Task Manager as a UI Component in UI Flows for task management capabilities
> > >
> > > > [card] Multi-platform support
> > > >
> > > > Create UI once and deploy to web (Angular/React), iOS, and Android with platform-specific configurations
> > >
> > > > [card] Import/export
> > > >
> > > > Export UI Flows as portable packages and import them across environments and applications
> > >
> > > > [card] Platform selection
> > > >
> > > > Configure platform-specific behaviors and overrides for web, iOS, and Android in the UI Flows designer
> > >
> > > > [card] Home page support
> > > >
> > > > Create UI Flows with dedicated home pages and home navigation icons for better UX
> >
> > > [tab] How It Works
> > >
> > > **1. Create UI flow**
> > >
> > > Create a UI Flow as a project resource in FlowX Designer, separate from process definitions
> > >
> > > **2. Design navigation**
> > >
> > > Manage Navigation Areas inside UI Flows Designer, defining pages and navigation structure
> > >
> > > **3. Add components**
> > >
> > > Add UI components including Task Manager, forms, custom components, and other UI elements
> > >
> > > **4. Configure actions**
> > >
> > > Setup UI Actions like Start Process (to launch processes) and Navigate To (for Nav areas or container scrolling)
> > >
> > > **5. Configure platforms**
> > >
> > > Set platform-specific configurations using the platform selection subheader (Web, iOS, Android)
> > >
> > > **6. Set home page**
> > >
> > > Designate a page as the home page with automatic home icon navigation support
> > >
> > > **7. Export & reuse**
> > >
> > > Export your UI Flow and import it into other applications or environments for maximum reusability
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced complexity
> > > >
> > > > Build UIs without the overhead of BPMN processes for use cases that don't require business process mapping
> > >
> > > > [card] Faster development
> > > >
> > > > Build UI once instead of creating separate interfaces for each platform
> > >
> > > > [card] Flexible architecture
> > > >
> > > > Eliminate unnecessary subprocess layers - use UI Flows for simple scenarios and processes for complex business logic
> > >
> > > > [card] Consistent UX
> > > >
> > > > Ensure identical user experiences across web, iOS, and Android applications
> > >
> > > > [card] Reusability
> > > >
> > > > Share UI Flows across multiple applications and projects
> > >
> > > > [card] Process integration
> > > >
> > > > Launch processes from UI Flows when needed, maintaining clean separation of concerns
> > >
> > > > [card] Maintainability
> > > >
> > > > Update UI in one place and propagate changes across all platforms
> > >
> > > > [card] Enhanced navigation
> > > >
> > > > Rich navigation capabilities with Nav areas, container scrolling, and Task Manager integration
> >
> > > [tab] Use Cases
> > >
> > > **When to Use UI Flows vs Processes:**
> > >
> > > **Use UI Flows for:**
> > >
> > > * **Information Display**: Dashboards, reports, and static content that doesn't require process orchestration
> > > * **Task Management**: Task lists and task management interfaces with embedded Task Manager component
> > > * **Navigation Shells**: Application navigation structures and home pages
> > > * **Form Collections**: Data entry forms that start processes but don't need their own process context
> > > * **Multi-Platform Apps**: Applications that need consistent UI across web and mobile platforms
> > >
> > > **Use Processes for:**
> > >
> > > * **Business Logic**: Complex workflows with business rules, approvals, and integrations
> > > * **State Management**: Applications requiring process state tracking and persistence
> > > * **Orchestration**: Multi-step operations with decision points and parallel execution
> > >
> > > **Combine Both:**
> > >
> > > Create UI Flows as the main application shell and use Start Process UI Actions to launch business processes when needed, keeping your architecture clean and maintainable.
> >
> > > [card] [UI Flows Documentation](/5.9/docs/building-blocks/ui-flows)
> > >
> > > Complete guide to creating and configuring UI Flows, including navigation management, UI actions, and platform considerations.
> >
> > Major Feature
>
> ***
>
> ### **UI events**
>
> > [card] UI events
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Events, enabling real-time interaction handling directly within Reusable UI Templates. UI Events allow you to capture user interactions like button clicks, form changes, or custom events and respond immediately without process execution, providing responsive and dynamic user experiences.
> >
> > > [tab] Key Features
> > >
> > > > [card] Event configuration
> > > >
> > > > Configure UI Events in UI Designer with custom event types and handling logic
> > >
> > > > [card] Cross-platform support
> > > >
> > > > UI Events work consistently across Angular, React, iOS, and Android renderers
> > >
> > > > [card] Runtime mapping
> > > >
> > > > UI Event results are mapped automatically in Reusable UI Template instances at runtime
> > >
> > > > [card] Design-time testing
> > > >
> > > > Test UI Events directly in UI Designer before deploying to runtime
> >
> > > [tab] Use Cases
> > >
> > > > [card] Form validation
> > > >
> > > > Validate form inputs in real-time as users type, providing immediate feedback
> > >
> > > > [card] Dynamic UI updates
> > > >
> > > > Show/hide fields, update options, or change UI state based on user interactions
> > >
> > > > [card] Client-side logic
> > > >
> > > > Execute lightweight client-side logic without triggering backend processes
> > >
> > > > [card] Responsive interactions
> > > >
> > > > Create highly responsive UI behaviors like autocomplete, live search, or conditional displays
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Handle UI interactions instantly without waiting for backend process execution
> > >
> > > **2. User experience**
> > >
> > > Provide immediate visual feedback and responsive interactions
> > >
> > > **3. Reduced complexity**
> > >
> > > Simplify process logic by handling UI-specific interactions at the component level
> >
> > UX Enhancement
>
> ***
>
> ### **Custom component enhancements**
>
> > [card] Custom component enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 standardizes custom component integration across all platforms (Angular, React, iOS, Android) with unified data mapping for input keys, data binding, save operations, and action handling. This provides a consistent developer experience when building custom components.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified data mapping
> > > >
> > > > Standard data, saveData, and action body mapping across all platforms
> > >
> > > > [card] Input key mapping
> > > >
> > > > Consistent input key handling for passing configuration and data to custom components
> > >
> > > > [card] Platform parity
> > > >
> > > > Identical custom component APIs across Angular, React, iOS, and Android
> > >
> > > > [card] Action integration
> > > >
> > > > Integration with FlowX actions for triggering backend operations
> >
> > > [tab] Benefits
> > >
> > > **1. Developer productivity**
> > >
> > > Build custom components once with knowledge that applies across all platforms
> > >
> > > **2. Code reusability**
> > >
> > > Share component logic and patterns across web and mobile implementations
> > >
> > > **3. Consistency**
> > >
> > > Ensure consistent behavior and data handling across all platforms
> >
> > Developer Experience
>
> ***
>
> ### **File upload improvements**
>
> > [card] File upload improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the file upload experience across all platforms with improved loading states, better user feedback, and more flexible configuration options. These improvements provide clearer status communication during file upload operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Enhanced loading behavior
> > > >
> > > > Configure loading behavior with optional overlay loader and custom loading messages
> > >
> > > > [card] Toast notifications
> > > >
> > > > Success and error messages displayed as toasts with customizable messages
> > >
> > > > [card] Dynamic messages
> > > >
> > > > Display dynamic key values in toast and loading messages for context-aware feedback
> > >
> > > > [card] Generic loader design
> > > >
> > > > Updated loader designs across Angular, React, iOS, and Android for consistent theming
> >
> > > [tab] Configuration
> > >
> > > **Loading Behavior Options:**
> > >
> > > * **NONE**: No loading overlay displayed during upload
> > > * **OVERLAY**: Full-screen overlay with spinner and optional loading message
> > >
> > > **Toast Notifications:**
> > >
> > > * **Success Toast**: Toggle to show success message when upload completes (auto-dismiss after 3-5 seconds)
> > > * **Error Toast**: Toggle to show error message when upload fails (auto-dismiss after 3-5 seconds)
> > > * **Custom Messages**: Configure success and error messages with dynamic substitutions
> > >
> > > **Theming Support:**
> > >
> > > * Apply custom themes to loaders and toast messages
> > > * Configure colors, sizes, and styling to match your brand
> > > * Consistent visual language across platforms
> >
> > UX Enhancement
>
> ***
>
> ### **Mobile accessibility**
>
> > [card] Mobile accessibility
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 extends WCAG 2.1 accessibility compliance to iOS and Android platforms, allowing you to configure accessibility properties directly from UI Designer and ensuring your mobile applications are accessible to all users.
> >
> > > [tab] Key Features
> > >
> > > > [card] iOS accessibility
> > > >
> > > > Configure labels, hints, traits, and accessibility properties for iOS components
> > >
> > > > [card] Android accessibility
> > > >
> > > > Set content descriptions and accessibility properties for Android components
> > >
> > > > [card] Designer integration
> > > >
> > > > Configure all accessibility properties from UI Designer without code changes
> > >
> > > > [card] Platform-specific options
> > > >
> > > > Set platform-specific accessibility configurations for optimal native experience
> >
> > > [tab] Benefits
> > >
> > > > [card] Inclusive mobile apps
> > > >
> > > > Make your mobile applications accessible to users with disabilities
> > >
> > > > [card] Regulatory compliance
> > > >
> > > > Meet mobile accessibility requirements for government, healthcare, and financial sectors
> > >
> > > > [card] Better UX
> > > >
> > > > Accessibility improvements benefit all users, not just those using assistive technologies
> > >
> > > > [card] Unified configuration
> > > >
> > > > Configure accessibility for all platforms from a single Designer interface
> >
> > Accessibility
>
> ***
>
> ### **Cross workspace projects**
>
> > [card] Cross workspace projects
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 removes the restriction that prevented importing the same project into multiple workspaces within the same environment. This enables organizations to use workspaces to represent different upper environments (UAT, Staging) for testing and development.
> > >
> > > > [!NOTE]
> > > >
> > > > A single project (identified by its UUID) can now exist independently across workspaces, each with its own lifecycle: separate active policies, configurations, and access controls.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Environment testing restrictions
> > > >
> > > > Organizations could not use workspaces on the same FlowX deployment to represent different upper environments for testing (e.g. UAT, Staging)
> > >
> > > > [card] Operational costs
> > > >
> > > > This feature is intended to allow organizations to use workspace functionality to emulate different environments and reduce operational costs.
> >
> > > [tab] Solution
> > >
> > > **What Changed:**
> > >
> > > **1. Restriction removed**
> > >
> > > The system now allows importing the same project (identified by UUID) into multiple workspaces within the same environment
> > >
> > > **2. Independent lifecycles**
> > >
> > > Each project instance in different workspaces maintains its own independent lifecycle with separate active policies, configurations, and access controls
> > >
> > > **3. Workspace isolation**
> > >
> > > Changes in one workspace do not affect the same project in other workspaces, ensuring proper isolation
> >
> > > [tab] How It Works
> > >
> > > **Import Behavior:**
> > >
> > > | Aspect | Behavior |
> > > | - | - |
> > > | **Import** | Import a project build (and optionally a version) into a different workspace on the same environment |
> > > | **Active Policy** | The imported build is automatically set as the active policy, regardless of what was active in the original workspace |
> > > | **User Access** | Workspace users must be granted appropriate project rights (e.g., project viewer) to interact with the imported project |
> > > | **Process Instances** | Workspace-specific; imported projects start with no instances until processes run in the new workspace |
> > > | **Database** | Projects across workspaces on the same environment share the same database |
> > > | **No Impact on Original** | Import does not affect the original project's settings, policies, information, or process instances |
> > >
> > > > [!WARNING]
> > > >
> > > > Only the build itself is transferred during cross-workspace import. Configuration and access controls are defined separately in each workspace.
> >
> > > [tab] Benefits
> > >
> > > > [card] Flexible testing environments
> > > >
> > > > Use workspaces to represent UAT, Staging, and other test environments on the same deployment
> > >
> > > > [card] Reduced costs
> > > >
> > > > Eliminate the need for additional deployments and DevOps resources for environment management
> > >
> > > > [card] Better organization
> > > >
> > > > Organize projects and environments more efficiently with workspace-based separation
> > >
> > > > [card] Independent control
> > > >
> > > > Maintain separate policies and configurations for each workspace while using the same project
> > >
> > > > [card] Simplified operations
> > > >
> > > > Streamline deployment and environment management workflows
> > >
> > > > [card] Faster environment setup
> > > >
> > > > Quickly create new test environments by importing existing projects into new workspaces
> >
> > > [tab] Use Cases
> > >
> > > **Example Scenarios:**
> > >
> > > 1. **Multi-Environment Testing**: Import the same project into UAT and Staging workspaces, each with different test data and configurations
> > >
> > > 2. **Development Lifecycle**: Maintain development, integration, and pre-production environments as separate workspaces with the same project
> > >
> > > 3. **Parallel Testing**: Run multiple test scenarios simultaneously by creating separate workspaces for each testing team
> > >
> > > 4. **Isolated Training Environments**: Create dedicated workspaces for training and demos while keeping production separate
> >
> > > [card] [Workspaces Documentation](/5.1/docs/projects/workspaces#cross-workspace-project-import)
> > >
> > > Complete guide to cross-workspace project import, including import behavior and best practices.
> >
> > Reusability Enhancement
>
> ***
>
> ### **Collection and table actions**
>
> > [card] Collection and table actions
> >
> > FlowX.AI 5.3 enables executing actions directly from collection and table rows within UI Flows across Angular and React platforms, providing contextual user interactions within data-driven UI Flow components.
> >
> > > [card] Row-level actions
> > >
> > > Configure and trigger actions with row context for edit, delete, or start process operations in UI Flows
> >
> > > [card] Cross-platform support
> > >
> > > Works in both Angular and React web renderers for UI Flows
> >
> > UI Flows
>
> ***

> [tab] Integration & data
>
> Enhanced workflow integration, data model management, and backend performance improvements.
>
> 🔄 [**Data mappers for workflow integration**](#data-mappers-for-workflow-integration) - Data mappers for workflow integration\
> 🗄️ [**Workflow data model**](#workflow-data-model) - New CRUD endpoints and runtime data model access\
> 🤖 [**MCP Integration**](#mcp-integration) - Connect AI agents with external tools and services through Model Context Protocol servers\
> 🤖 [**Custom Agent Nodes**](#custom-agent-nodes) - Custom Agent nodes for AI agents to use external tools and services
> 📚 [**Knowledge Base**](#knowledge-base) - Create and manage Knowledge Bases for AI agents with document ingestion and semantic search\
> 🔧 [**Update process variables**](#update-process-variables) - Operations teams can modify process variables on active instances to resolve production issues\
> 🔍 [**Token view improvements**](#token-view-improvements) - Enhanced token hierarchy visibility with horizontal scrolling, frozen columns, and context-aware columns\
> 🛡️ [**Access management enhancements**](#access-management-enhancements) - New operations editor role and granular workspace permissions\
> ⚡ [**Performance & stability**](#performance-and-stability) - Backend optimizations, caching improvements, and infrastructure updates\
> 🔀 [**Exclusive Gateways**](#exclusive-gateways) - Expression testing and validation improvements
>
> ### **Data mappers for workflow integration**
>
> > [card] Data mappers for workflow integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces data mappers that enable integration between processes and Integration Designer workflows. Similar to Process Definitions, you can now define structured data models at the workflow level with input and output parameters, ensuring consistent data lineage across your integration architecture.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
> > >
> > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process-workflow.png)
> > >
> > > Map data bidirectionally between processes and workflows using data mappers
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow Data Models provide the same structured data management capabilities as Process Data Models, enabling declarative data mapping between workflows and processes with full type safety and validation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow data model
> > > >
> > > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > > [card] Input parameter management
> > > >
> > > > Input parameters automatically pre-fill Start Nodes with structured data from the workflow data model
> > >
> > > > [card] Data parameters
> > > >
> > > > Use data parameters to define input and output data subsets for workflow operations
> > >
> > > > [card] Process ↔ workflow mapping
> > > >
> > > > Create data mappers on nodes to receive outputs from workflows and map data bidirectionally
> > >
> > > > [card] Generic CRUD endpoints
> > > >
> > > > Manage data models, entities, attributes, and data parameters programmatically via REST APIs
> > >
> > > > [card] Unique node validation
> > > >
> > > > Automatic node name uniqueness validation within workflow definitions to ensure clear data lineage
> >
> > > [tab] How It Works
> > >
> > > **1. Define workflow data model**
> > >
> > > Create a data model for your workflow with entities and attributes, similar to Process Data Models. Define which parameters are inputs and outputs
> > >
> > > **2. Configure input parameters**
> > >
> > > Input parameters automatically pre-fill the Start Node when you open the workflow diagram or test at runtime. No manual JSON editing required
> > >
> > > **3. Map process to workflow**
> > >
> > > When invoking a workflow from a process, create data mappers to map process data to workflow input parameters
> > >
> > > **4. Map workflow to process**
> > >
> > > Configure output mappings on nodes to receive workflow results and map them back to process data
> >
> > > [tab] Data Model Management
> > >
> > > **New API Capabilities:**
> > >
> > > * **Data Model CRUD**: Create, read, update, and delete workflow data models
> > > * **Entity Management**: Add, modify, and remove entities within data models
> > > * **Attribute Management**: Define and manage attributes with types and validation rules
> > > * **Data Parameters Operations**: Create input and output data parameters for workflows
> > > * **Usage Tracking**: Query references and usages for attributes and entities
> > > * **Import/Export**: Export and import complete data models across environments
> > >
> > > **Technical Implementation:**
> > >
> > > * Centralized data model library for common classes and interfaces
> > > * Generic endpoints for data model and data parameters manipulation
> > > * Integration Designer communicates with Admin service for data model operations
> > > * Automatic input body computation based on data model input parameters
> > > * Runtime workflow start data endpoint for testing and execution
> >
> > > [tab] Limitations & Compatibility
> > >
> > > **Current Limitations:**
> > >
> > > * **Start Subworkflow Node**: Works as-is without data model integration in this release
> > > * **Endpoint Schemas**: Imported Swagger schemas are not yet integrated with workflow data models (planned for future release)
> > > * **Database Schemas**: Database operation schemas are not mapped to workflow variables yet (planned for future release)
> > >
> > > **Backwards Compatibility:**
> > >
> > > * Existing workflows continue to work without changes
> > > * End nodes from existing workflows can be renamed manually to align with output parameters
> > > * No breaking changes to current workflow execution
> > >
> > > **Node Naming:**
> > >
> > > * Node names must be unique within a workflow definition
> > > * System automatically validates uniqueness when renaming nodes
> > > * If duplicate names exist, an index is incremented (e.g., "Transform", "Transform\_2")
> >
> > > [tab] Benefits
> > >
> > > > [card] Consistent data lineage
> > > >
> > > > Ensure data consistency across processes and workflows with structured data models
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Input parameters automatically pre-fill Start Nodes - no manual JSON editing
> > >
> > > > [card] Type safety
> > > >
> > > > Define data types and validation rules at the workflow level for runtime safety
> > >
> > > > [card] Reusability
> > > >
> > > > Create reusable workflows with clear input/output contracts that can be invoked from multiple processes
> > >
> > > > [card] Better testing
> > > >
> > > > Test workflows with structured input data based on the data model
> > >
> > > > [card] Clear interfaces
> > > >
> > > > Workflow data models document the expected inputs and outputs for each workflow
> >
> > > [card] [Workflow Data Models Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> > >
> > > Complete guide to creating workflow data models, input/output parameters, process integration, and API reference.
> >
> > Integration Designer
>
> ***
>
> ### **Workflow data model**
>
> > [card] Workflow data model
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 adds comprehensive workflow data model management capabilities with new CRUD endpoints and runtime access to data model paths. This enables dynamic data model operations and better runtime introspection.
> >
> > > [tab] Key Features
> > >
> > > > [card] CRUD endpoints
> > > >
> > > > Create, read, update, and delete workflow data models programmatically via REST APIs
> > >
> > > > [card] Data model paths
> > > >
> > > > Runtime endpoint for retrieving workflow data model paths and structure information
> > >
> > > > [card] RUT instance mappings
> > > >
> > > > Enhanced /status and /details endpoints with mappings per workflow instance
> > >
> > > > [card] Runtime caching
> > > >
> > > > Improved caching for reusable templates to reduce latency and improve performance
> >
> > > [tab] Use Cases
> > >
> > > > [card] Dynamic forms
> > > >
> > > > Build dynamic forms based on data model structure at runtime
> > >
> > > > [card] Data migration
> > > >
> > > > Automate data model synchronization across environments
> > >
> > > > [card] Documentation
> > > >
> > > > Generate data model documentation automatically from API responses
> > >
> > > > [card] Validation
> > > >
> > > > Implement runtime validation based on data model definitions
> >
> > API Enhancement
>
> ***
>
> ### **MCP integration**
>
> > [card] MCP integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Model Context Protocol (MCP) integration, enabling AI agents to connect with external MCP servers and use their tools within Custom Agent nodes. MCP provides a standardized protocol for AI agents to access external tools, databases, APIs, and services.
> > >
> > > > [!NOTE]
> > > >
> > > > MCP integration extends AI agent capabilities by providing access to external tools through a standardized protocol. Configure MCP servers as data sources in Integration Designer and use their tools in workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] MCP data sources
> > > >
> > > > Add MCP servers as data sources in Integration Designer with base URL and authentication configuration
> > >
> > > > [card] Tool management
> > > >
> > > > View, enable, and turn off specific tools exposed by MCP servers directly from Integration Designer
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Select MCP servers in Custom Agent nodes to make their tools available to AI agents during workflow execution
> > >
> > > > [card] Authentication support
> > > >
> > > > Support for no authentication and OAuth 2.0 service account authentication methods
> > >
> > > > [card] Tool discovery
> > > >
> > > > Automatic tool discovery from MCP servers with schema information for inputs and outputs
> > >
> > > > [card] Execution monitoring
> > > >
> > > > Track tool usage and execution details in console logs for debugging and monitoring
> >
> > > [tab] How It Works
> > >
> > > **1. Add MCP server**
> > >
> > > Configure an MCP server as a data source in Integration Designer with base URL and authentication details
> > >
> > > **2. Authenticate connection**
> > >
> > > Set up authentication using no authentication (for development) or OAuth 2.0 service account (for production)
> > >
> > > **3. Discover tools**
> > >
> > > View available tools exposed by the MCP server with their input/output schemas
> > >
> > > **4. Enable tools**
> > >
> > > Enable or turn off specific tools based on your workflow requirements
> > >
> > > **5. Configure custom agent**
> > >
> > > Add a Custom Agent node to your workflow and select which MCP servers the agent can access
> > >
> > > **6. Execute workflow**
> > >
> > > AI agents can now use MCP tools during workflow execution to interact with external systems
> > >
> > > **7. Monitor execution**
> > >
> > > View tool usage and execution details in console logs for debugging and performance tracking
> >
> > > [tab] Authentication
> > >
> > > **Supported Authentication Methods:**
> > >
> > > **None**
> > >
> > > * No authentication required
> > > * Use for public MCP servers or development environments
> > > * Quick setup for testing and prototyping
> > >
> > > **Service Account (OAuth 2.0)**
> > >
> > > * OAuth 2.0 service account authentication
> > > * Required configuration:
> > >   * **Client ID**: OAuth client identifier
> > >   * **Client Secret**: OAuth client secret
> > >   * **Identity Provider URL**: Authorization server endpoint
> > > * Use for production environments
> > > * Secure access to MCP servers
> >
> > > [tab] Use Cases
> > >
> > > > [card] External API integration
> > > >
> > > > Connect AI agents to external APIs and services for data retrieval and action execution
> > >
> > > > [card] Database operations
> > > >
> > > > Query databases and perform data operations through MCP tools within AI workflows
> > >
> > > > [card] Custom business logic
> > > >
> > > > Expose custom business logic as MCP tools for AI agents to execute
> > >
> > > > [card] Multi-system orchestration
> > > >
> > > > Use multiple MCP servers in a single Custom Agent node to orchestrate operations across systems
> >
> > > [tab] Benefits
> > >
> > > > [card] Standardized integration
> > > >
> > > > Use a standardized protocol for AI agent tool integration across different systems
> > >
> > > > [card] Extended capabilities
> > > >
> > > > Extend AI agent capabilities with external tools without custom code
> > >
> > > > [card] Flexible tool management
> > > >
> > > > Enable or turn off specific tools per MCP server based on workflow needs
> > >
> > > > [card] Secure connections
> > > >
> > > > Support for OAuth 2.0 authentication ensures secure access to external services
> > >
> > > > [card] Tool reusability
> > > >
> > > > Configure MCP servers once and use their tools across multiple workflows and Custom Agent nodes
> > >
> > > > [card] Monitoring & debugging
> > > >
> > > > Console logs provide visibility into tool execution for troubleshooting and optimization
> >
> > > [card] [MCP Integration Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> > >
> > > Complete guide to MCP integration including data source configuration, tool management, and Custom Agent node usage.
> >
> > AI Integration
>
> ***
>
> ### **Custom Agent nodes**
>
> > [card] Custom Agent nodes
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Custom Agent nodes, enabling you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
> >
> > > [card] [Custom Agent Node Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > Complete guide to Custom Agent nodes, including configuration, usage, and best practices.
> >
> > AI Integration
>
> ***
>
> ### **Knowledge base**
>
> > [card] Knowledge base
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Knowledge Base integration, enabling you to create and manage centralized repositories of information that AI agents can query when preparing responses. Upload static documents or ingest dynamic data from workflows into Knowledge Bases that use vector embeddings and semantic search for intelligent information retrieval.
> > >
> > > > [!NOTE]
> > > >
> > > > Knowledge Bases enable AI agents to provide contextual, accurate responses based on your organization's documentation, policies, and dynamic data.
> >
> > > [tab] Key Features
> > >
> > > > [card] Document upload
> > > >
> > > > Upload PDF documents directly into Knowledge Bases for AI agent access
> > >
> > > > [card] Workflow ingestion
> > > >
> > > > Ingest data dynamically from workflows using Knowledge Base operations (Append, Replace, Delete)
> > >
> > > > [card] Semantic search
> > > >
> > > > AI agents find relevant information using natural language queries with vector embeddings
> > >
> > > > [card] Content sources
> > > >
> > > > Organize content across multiple sources within a Knowledge Base for better management
> > >
> > > > [card] Relevance scoring
> > > >
> > > > Configure minimum relevance thresholds (0-100%) to control response quality
> > >
> > > > [card] Testing capabilities
> > > >
> > > > Test queries and operations in isolation before adding them to production workflows
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Enable Knowledge Base queries in Custom Agent nodes with configurable parameters
> > >
> > > > [card] Content versioning
> > > >
> > > > Append, replace, or delete content sources with full traceability and state management
> >
> > > [tab] How It Works
> > >
> > > **1. Create Knowledge Base**
> > >
> > > Add a new Knowledge Base data source in Integration Designer
> > >
> > > **2. Ingest content**
> > >
> > > Upload PDF documents or ingest data from workflows into content sources
> > >
> > > **3. Automatic chunking**
> > >
> > > Content is automatically split into chunks and indexed in the vector database
> > >
> > > **4. Configure Custom Agent**
> > >
> > > Enable Knowledge Base in Custom Agent nodes and configure query parameters
> > >
> > > **5. Query execution**
> > >
> > > AI agents query the Knowledge Base using semantic search and receive relevant chunks
> > >
> > > **6. Response generation**
> > >
> > > Agents use retrieved chunks as context to generate accurate, informed responses
> >
> > > [tab] Workflow Operations
> > >
> > > **Knowledge Base operations available in workflows:**
> > >
> > > | Operation | Description |
> > > | - | - |
> > > | **Append** | Add new content to an existing content source without removing existing data |
> > > | **Replace** | Delete all existing content and replace with new content |
> > > | **Delete** | Remove all content from a content source |
> > >
> > > **Configuration Options:**
> > >
> > > * **Knowledge Base**: Select from local project libraries or dependencies
> > > * **Content Source**: Use existing sources, create new ones, or use workflow variables
> > > * **Content**: Static text, workflow variables, or configuration parameters
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product documentation assistant
> > > >
> > > > Create Knowledge Bases with product documentation for AI agents to answer customer questions
> > >
> > > > [card] Policy compliance
> > > >
> > > > Upload company policies so AI agents can reference them when processing requests
> > >
> > > > [card] Dynamic knowledge updates
> > > >
> > > > Ingest data from external systems through workflows to keep AI knowledge current
> > >
> > > > [card] Multi-source synthesis
> > > >
> > > > Organize information across sources and let AI agents synthesize comprehensive answers
> >
> > > [tab] Benefits
> > >
> > > > [card] Contextual AI responses
> > > >
> > > > AI agents provide accurate responses based on your organization's actual documentation
> > >
> > > > [card] Dynamic updates
> > > >
> > > > Keep AI knowledge current by ingesting data from workflows automatically
> > >
> > > > [card] Quality control
> > > >
> > > > Relevance scoring ensures only high-quality, relevant information is used
> > >
> > > > [card] Centralized management
> > > >
> > > > Manage all AI knowledge sources from a single location in Integration Designer
> > >
> > > > [card] No code integration
> > > >
> > > > Configure Knowledge Base queries directly in Custom Agent nodes without code
> > >
> > > > [card] Testable
> > > >
> > > > Test queries and see relevance scores before deploying to production
> >
> > > [tab] Limitations
> > >
> > > **Current Limitations:**
> > >
> > > > [!WARNING]
> > > >
> > > > * Only PDF documents are supported for manual upload (images, PPT, DOC, XLS support coming in future releases)
> > > > * Custom metadata cannot be defined (only system metadata is available)
> > > > * AI agents can only use one Knowledge Base per Custom Agent node
> > > > * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
> >
> > > [card] [Knowledge Base Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > Complete guide to creating Knowledge Bases, ingesting content, and using them in Custom Agent workflows.
> >
> > AI Integration
>
> ***
>
> ### **Update process variables**
>
> > [card] Update process variables
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces the ability for operations teams to modify process variables on active (Started or On Hold) process instances, providing critical tools to resolve production issues without process restarts. Edit, add, or delete attributes and objects directly using an editor with JSON validation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Formatting%20_%20Custom%20Date%20Format.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Tokens%20table.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > > [!NOTE]
> > > >
> > > > Updated values automatically sync to Task Manager and Elasticsearch, ensuring consistency across all systems. Previous values are saved in a snapshot table, and all modifications are tracked in the audit log for complete traceability.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Limited correction tools
> > > >
> > > > Operations teams had minimal tools to correct production issues at the process-instance level
> > >
> > > > [card] Blocked instances
> > > >
> > > > No way to unblock stuck process instances without backend intervention or process restarts
> > >
> > > > [card] Data correction challenges
> > > >
> > > > Incorrect process data required complex workarounds or manual database modifications
> > >
> > > > [card] Operational delays
> > > >
> > > > Production issues required developer intervention, increasing resolution time
> >
> > > [tab] Key Features
> > >
> > > > [card] Editor
> > > >
> > > > Edit process variables in a JSON editor with syntax validation and formatting
> > >
> > > > [card] Multiple entry points
> > > >
> > > > Access from Process Instances page contextual menu or Process Instance page secondary navigation
> > >
> > > > [card] Dual view modes
> > > >
> > > > Switch between Tree View (existing) and JSON View for variable visualization and editing
> > >
> > > > [card] Full CRUD operations
> > > >
> > > > Edit existing attribute values, add new attributes/objects, or delete existing attributes/objects
> > >
> > > > [card] JSON validation
> > > >
> > > > Automatic JSON format validation before saving to ensure data integrity
> > >
> > > > [card] Snapshot history
> > > >
> > > > Previous process variables are saved in a new snapshot table before changes are applied
> > >
> > > > [card] Auto-sync to Task Manager
> > > >
> > > > Updated variables automatically sync to Task Manager using existing mechanism
> > >
> > > > [card] Elasticsearch integration
> > > >
> > > > Process variables configured for data search are automatically updated in Elasticsearch
> > >
> > > > [card] Permission-based access
> > > >
> > > > Role-based access control with process\_variables\_edit permission ensures only authorized users can modify variables
> > >
> > > > [card] Export functionality
> > > >
> > > > Export button available near the view dropdown for downloading process variables
> > >
> > > **Iteration 2 - Enhanced Review:**
> > >
> > > > [card] Compare feature
> > > >
> > > > Ability to review updated process variables through a compare feature, showing before/after values for better visibility and validation
> >
> > > [tab] How It Works
> > >
> > > **Accessing the Feature:**
> > >
> > > You can access the edit functionality from two entry points:
> > >
> > > 1. **Process Instances Page**: Use contextual menu on a process instance row → navigates to Process Instance page and opens Variables tab in edit mode
> > > 2. **Process Instance Page**: Use contextual menu in secondary navigation → opens Variables tab in edit mode
> > >
> > > **Editing Process Variables:**
> > >
> > > **1. Select active instance**
> > >
> > > Choose an active process instance (Started or On Hold status) that requires variable modification
> > >
> > > **2. Switch to JSON view**
> > >
> > > In the Variables tab, switch from Tree View to JSON View using the view dropdown
> > >
> > > **3. Click edit**
> > >
> > > Click the Edit button (visible only if you have process\_variables\_edit permission)
> > >
> > > **4. Modify in editor**
> > >
> > > Edit process variables in the JSON editor - you can edit existing values, add new attributes/objects, or delete existing ones
> > >
> > > **5. Validate JSON**
> > >
> > > Ensure your JSON format is valid before saving - the editor will highlight syntax errors
> > >
> > > **6. Save changes**
> > >
> > > Click Save to apply changes - a snapshot of previous values is automatically created
> > >
> > > **7. Auto-sync**
> > >
> > > System automatically syncs updated variables to Task Manager and Elasticsearch (for variables configured for data search)
> > >
> > > **8. Review audit log**
> > >
> > > Check the Audit Log tab to confirm the modification was recorded with all details
> >
> > > [tab] Permissions & Security
> > >
> > > **Permission Requirements:**
> > >
> > > * **New Permission**: `process_variables_edit` available at workspace level
> > > * **Default Roles**: Added to `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, and `workspace_operations_editor` roles
> > > * **New Role**: `workspace_operations_editor` - A dedicated workspace role for operations management including process variable editing and operations (migration & move token)
> > >
> > > **Access Control:**
> > >
> > > * Edit option in UI is only visible to users with `process_variables_edit` permission
> > > * Save functionality is restricted to users with the required permission
> > > * Unauthorized users can view process variables but cannot modify them
> > >
> > > **Audit Logging:**
> > >
> > > Every process variable modification creates an audit log entry with:
> > >
> > > * Workspace ID
> > > * Feature: Process variables
> > > * Section: Process Instance
> > > * Application UUID and name
> > > * Subject: Process variables
> > > * Event: Edit
> > > * Subject Identifier: Process instance UUID
> > > * Body: JSON with new version of process parameters
> > >
> > > Audit logs are displayed in the Audit Log tab within the process instance for easy tracking.
> >
> > > [tab] Data Synchronization
> > >
> > > **What Gets Updated:**
> > >
> > > > [card] Task Manager
> > > >
> > > > Variables are automatically updated in Task Manager using existing mechanisms - ensures task keywords and data remain consistent
> > >
> > > > [card] Elasticsearch
> > > >
> > > > Variables configured for data search are automatically updated in Elasticsearch - maintains search accuracy
> > >
> > > > [card] Process instance params
> > > >
> > > > Primary process instance parameters are updated immediately in the database
> > >
> > > > [card] Snapshot table
> > > >
> > > > Previous values are saved in a new snapshot table before changes are applied
> > >
> > > **What Does NOT Get Updated:**
> > >
> > > > [card] Process snapshots
> > > >
> > > > Process instance snapshots (used for back navigation/reset) are not updated - maintains historical integrity
> > >
> > > > [card] Debug table
> > > >
> > > > Process instance debug records remain unchanged - preserves execution history
> > >
> > > > [card] Existing audit logs
> > > >
> > > > Previously recorded audit logs (manual actions, integrations) are not modified - maintains compliance trail
> > >
> > > > [card] Subprocess variables
> > > >
> > > > Child subprocess variables are not automatically updated - parent changes don't cascade to children
> >
> > > [tab] Important Considerations
> > >
> > > **Limitations & Best Practices:**
> > >
> > > > [!WARNING]
> > > >
> > > > **Subprocess Impact**: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.
> > >
> > > > [!WARNING]
> > > >
> > > > **Back Navigation**: 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.
> > >
> > > > [!WARNING]
> > > >
> > > > **Integration Messages**: 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.
> > >
> > > **Best Practices:**
> > >
> > > * **Verify JSON Format**: Always ensure valid JSON before saving to prevent data corruption
> > > * **Document Changes**: Use audit logs to track all modifications and maintain operational documentation
> > > * **Test in Lower Environments**: When possible, test variable modifications in staging before production
> > > * **Understand Dependencies**: Review process flow and subprocess relationships before modifying variables
> > > * **Consider Timing**: Best used for stuck processes or data corrections, not for regular operational changes
> > > * **Check Search Data**: If variables are used in data search, verify Elasticsearch sync completed successfully
> >
> > > [tab] Benefits
> > >
> > > > [card] Faster issue resolution
> > > >
> > > > Operations teams can resolve production issues immediately without developer intervention
> > >
> > > > [card] Reduced downtime
> > > >
> > > > Unblock stuck instances quickly, minimizing impact on end users and business processes
> > >
> > > > [card] Operational independence
> > > >
> > > > Empower ops teams with self-service tools for process-instance management
> > >
> > > > [card] Data consistency
> > > >
> > > > Automatic sync ensures Task Manager and Elasticsearch reflect updated values
> > >
> > > > [card] Full traceability
> > > >
> > > > Snapshots and audit logs provide complete history of all modifications for compliance
> > >
> > > > [card] Reduced risk
> > > >
> > > > Permission-based access and comprehensive audit trail reduce risk of unauthorized changes
> > >
> > > > [card] Flexible editing
> > > >
> > > > The JSON editor provides powerful JSON editing capabilities with validation
> > >
> > > > [card] Historical preservation
> > > >
> > > > Original values preserved in snapshot table for rollback scenarios
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Correct User Input Errors**
> > >
> > > * Customer submitted incorrect data in a loan application (wrong income, invalid address)
> > > * Operations team edits the variables to correct the information
> > > * Process continues without requiring customer to restart the application
> > >
> > > **2. Unblock Stuck Process Instances**
> > >
> > > * Process is waiting for external data that will never arrive (integration timeout, external system down)
> > > * Ops team updates the variable to provide expected data or skip the condition
> > > * Instance is unblocked and continues execution
> > >
> > > **3. Fix Integration Data Issues**
> > >
> > > * External system returned incorrect or incomplete data
> > > * Operations team corrects process variables to match expected values
> > > * Process continues with accurate data without re-calling the integration
> > >
> > > **4. Emergency Data Updates**
> > >
> > > * Critical business information changed after process started (regulatory update, pricing change)
> > > * Ops team modifies variables to reflect current information
> > > * Process continues with updated data without restart
> > >
> > > **5. Add Missing Attributes**
> > >
> > > * Process needs additional data that wasn't collected at start
> > > * Operations team adds new attributes or objects to process variables
> > > * Process can now access the required information
> > >
> > > **6. Remove Invalid Data**
> > >
> > > * Process contains incorrect or test data that shouldn't be there
> > > * Ops team deletes the problematic attributes or objects
> > > * Process continues with clean, valid data only
> > >
> > > **7. Update Task Manager Keywords**
> > >
> > > * Task search keywords need updating based on corrected data
> > > * Variables are modified and automatically synced to Task Manager
> > > * Tasks become searchable with correct keywords
> > >
> > > **8. Fix Elasticsearch Search Data**
> > >
> > > * Process data indexed for search contains errors
> > >
> > > * Operations team corrects variables configured for data search
> > >
> > > * Elasticsearch automatically updates, ensuring accurate search results
> > >
> > > > [!NOTE]
> > > >
> > > > This capability, combined with the upcoming Move Token feature, provides comprehensive process-instance management tools for operations teams.
> >
> > > [card] [Update Process Variables Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > >
> > > Complete guide including step-by-step instructions, permissions, data synchronization, best practices, and troubleshooting.
> >
> > Operations Enhancement
>
> ***
>
> ### **Token view improvements**
>
> > [card] Token view improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the **Tokens tab** in the **Process Instance View** with improved visibility and comprehension of token hierarchy and context. The enhanced token view introduces horizontal scrolling, frozen columns, hierarchical nesting, and new context-related columns to provide better insights into process execution.
> > >
> > > > [!NOTE]
> > > >
> > > > These improvements make it easier to understand complex process flows with parallel gateways, embedded subprocesses, and boundary events by clearly displaying token relationships and execution context.
> >
> > > [tab] Key Features
> > >
> > > > [card] Horizontal scrolling
> > > >
> > > > The table supports horizontal scrolling to accommodate all columns, ensuring all token information remains accessible
> > >
> > > > [card] Frozen columns
> > > >
> > > > Token UUID and Actions columns remain fixed during horizontal scroll for constant visibility of key identifiers and actions
> > >
> > > > [card] Hierarchical nesting
> > > >
> > > > Tokens display in a tree structure with nested child tokens under parent tokens, showing clear parent-child relationships
> > >
> > > > [card] Auto-expanded rows
> > > >
> > > > All token rows are expanded by default, providing immediate visibility into the complete token hierarchy
> > >
> > > > [card] Dynamic indentation
> > > >
> > > > Indentation dynamically adjusts based on nesting depth, visually representing token relationships
> > >
> > > > [card] Context column
> > > >
> > > > New Context column displays subprocess names for tokens running within embedded subprocesses, or main process name for main process tokens
> > >
> > > > [card] Initiator node column
> > > >
> > > > New Initiator Node column shows the node name that generated the token (e.g., Parallel Gateway, Non-interrupting boundary event)
> > >
> > > > [card] First executed node column
> > > >
> > > > New First Executed Node column displays the first node executed after token generation
> > >
> > > > [card] UUID copy functionality
> > > >
> > > > Token UUID displays first 6 characters with a copy icon; clicking copies the full UUID to clipboard with success notification
> > >
> > > > [card] Color-coded status tags
> > > >
> > > > Token Status column uses color-coded tags for quick visual identification of token lifecycle states
> > >
> > > > [card] Tooltip support
> > > >
> > > > Long node names are truncated with tooltips showing full text on hover for better readability
> > >
> > > > [card] Timezone-aware timestamps
> > > >
> > > > Last Updated column displays full datetime in browser timezone for accurate local time representation
> >
> > > [tab] Table Columns
> > >
> > > The enhanced token view includes the following columns:
> > >
> > > | Column | Description | Special Behavior |
> > > | - | - | - |
> > > | **Token UUID** | Unique identifier of the token | Only first 6 characters displayed. Copy icon appears beside UUID. Clicking copies full UUID to clipboard with success toast: "Full Token UUID copied to clipboard." **Frozen column** (stays visible during horizontal scroll) |
> > > | **Context** | Displays contextual data for token | Shows main process name for tokens in main process. Shows embedded subprocess name for tokens in embedded subprocesses (any nesting level) |
> > > | **Initiator Node** | Shows the node name that generated the token | Applies to child tokens only. For parent tokens, displays "-". Examples: Parallel Gateway name, Non-interrupting boundary event name |
> > > | **First Executed Node** | Displays the first node executed after token generation | For parallel gateway tokens: first executed node on that parallel branch. For boundary event tokens: first executed node on branch started from boundary node. If first node is embedded subprocess, displays embedded subprocess name |
> > > | **Current Node** | Displays the last node executed within the token branch | For parallel gateway tokens: last node on branch. For boundary event tokens: last node executed on branch triggered by boundary. For tokens in embedded subprocess: displays current node from subprocess |
> > > | **Current Node Status** | Shows the current execution status | Examples: WAITING\_TIMER\_EVENT, ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL. Sortable column |
> > > | **Token Status** | Indicates lifecycle state | Values: ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, TERMINATED. **Color-coded tags** for visual identification |
> > > | **Last Updated** | Timestamp of latest token state change | Displays full datetime in browser timezone |
> > > | **Actions** | Available actions for the token | Includes Retry token and View (eye icon) actions. **Frozen column** (stays visible during horizontal scroll). Retry button only visible for ACTIVE tokens |
> >
> > > [tab] Nesting Behavior
> > >
> > > **Token Hierarchy Display:**
> > >
> > > **1. Parent-child relationships**
> > >
> > > Tokens created by parallel gateways or embedded subprocesses are displayed as nested child tokens under their parent tokens
> > >
> > > **2. Default expansion**
> > >
> > > All token rows are expanded by default, showing the complete token hierarchy immediately
> > >
> > > **3. Dynamic indentation**
> > >
> > > Indentation adjusts automatically based on nesting depth, with columns expanding accordingly to maintain alignment
> > >
> > > **4. Visual hierarchy**
> > >
> > > The tree structure makes it easy to identify which tokens belong to which parallel branch or subprocess
> > >
> > > **Initiator Node Logic:**
> > >
> > > * **Parent tokens**: Display "-" in Initiator Node column
> > > * **Child tokens from parallel gateway**: Display the parallel gateway node name
> > > * **Child tokens from boundary event**: Display the boundary event node name
> > > * **Child tokens from back in steps**: Display appropriate initiator information
> >
> > > [tab] Benefits
> > >
> > > > [card] Better visibility
> > > >
> > > > Horizontal scrolling and frozen columns ensure all token information remains accessible regardless of table width
> > >
> > > > [card] Clear hierarchy
> > > >
> > > > Hierarchical nesting with dynamic indentation makes parent-child token relationships immediately clear
> > >
> > > > [card] Context awareness
> > > >
> > > > Context column provides immediate visibility into which subprocess a token is executing within
> > >
> > > > [card] Execution tracking
> > > >
> > > > Initiator Node and First Executed Node columns help track token origin and execution path
> > >
> > > > [card] Quick actions
> > > >
> > > > Frozen Actions column ensures retry and view actions are always accessible without scrolling
> > >
> > > > [card] Easy UUID access
> > > >
> > > > Quick copy functionality for full UUIDs without needing to view token details
> > >
> > > > [card] Visual status identification
> > > >
> > > > Color-coded status tags enable quick identification of token states at a glance
> > >
> > > > [card] Improved readability
> > > >
> > > > Tooltips for truncated names and timezone-aware timestamps improve overall readability
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Parallel Gateway Debugging**
> > >
> > > * View all parallel branches simultaneously with clear parent-child relationships
> > > * Identify which branch each token belongs to through hierarchical nesting
> > > * Track execution progress across multiple parallel paths
> > >
> > > **2. Embedded Subprocess Analysis**
> > >
> > > * Context column immediately shows which subprocess tokens are executing within
> > > * Understand nested subprocess relationships through indentation
> > > * Track token flow across multiple subprocess levels
> > >
> > > **3. Boundary Event Monitoring**
> > >
> > > * Initiator Node column shows which boundary event triggered each token
> > > * First Executed Node shows the execution path started by boundary events
> > > * Monitor non-interrupting boundary event token execution
> > >
> > > **4. Process Instance Troubleshooting**
> > >
> > > * Frozen UUID column ensures token identification is always visible
> > > * Copy UUID functionality enables quick token reference in support tickets
> > > * Color-coded status tags help identify problematic tokens quickly
> > >
> > > **5. Multi-Level Process Analysis**
> > >
> > > * Hierarchical view supports complex processes with multiple nesting levels
> > > * Dynamic indentation adapts to any nesting depth
> > > * All tokens visible by default without manual expansion
> >
> > > [card] [Token Documentation](/5.1/docs/building-blocks/token)
> > >
> > > Complete guide to tokens, including token status values, current node status, and detailed token status view.
> >
> > UX Enhancement
>
> ***
>
> ### **Access management enhancements**
>
> > [card] Access management enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces new workspace-level permissions and a dedicated operations editor role, providing more granular control over process instance management and operations.
> > >
> > > > [!NOTE]
> > > >
> > > > These enhancements enable organizations to delegate operational tasks to dedicated teams without granting full runtime or admin access.
> >
> > > [tab] New Role
> > >
> > > **workspace\_operations\_editor**
> > >
> > > A new predefined workspace role designed for operations teams who need to manage process instances without requiring full runtime or admin capabilities.
> > >
> > > > [card] Operations management
> > > >
> > > > Full CRUD access for process instance operations including migration and move token functionality
> > >
> > > > [card] Process variables
> > > >
> > > > Edit permission for process variables on active instances across the workspace
> > >
> > > > [card] Process instances
> > > >
> > > > Read and edit access to all process instances in the workspace
> > >
> > > > [card] Workspace user inheritance
> > > >
> > > > Inherits all base permissions from workspace\_user role including project creation
> > >
> > > **Role Constraints:**
> > >
> > > * Cannot be edited or deleted (predefined role)
> > > * Extends workspace\_user with operations-specific permissions
> > > * Does not include broader runtime capabilities (builds, policies, scheduled processes)
> > >
> > > **Use Cases:**
> > >
> > > * Support engineers managing process migrations
> > > * Operations teams handling token movements
> > > * Technical support staff editing process variables
> >
> > > [tab] New Permissions
> > >
> > > **Workspace-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **Operations** (Read/Edit/Create/Delete) | Manage process instance operations including migration and move token | `org_admin`, `workspace_admin`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Operations** (Read/Create only) | Create operations and view all operations | `workspace_user` |
> > > | **Process Variables** (Edit) | Edit process variables on active instances | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Process Instances** (Edit) | Edit process instance data | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > >
> > > **Project-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **UI Flows** (Read/Edit/Create/Delete) | Full access to create and manage UI Flows | `project_owner`, `project_editor` |
> > > | **UI Flows** (Read only) | View UI Flows definitions | `project_viewer` |
> >
> > > [tab] Benefits
> > >
> > > > [card] Principle of least privilege
> > > >
> > > > Grant only the permissions needed for specific operational tasks
> > >
> > > > [card] Dedicated operations teams
> > > >
> > > > Enable operations teams to work independently without full admin access
> > >
> > > > [card] Clear separation of concerns
> > > >
> > > > Distinguish between runtime management (builds, policies) and operations management (migrations, variables)
> > >
> > > > [card] Flexible role combinations
> > > >
> > > > Combine with other workspace roles for customized access patterns
> >
> > > [card] [Access Management Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix)
> > >
> > > Complete permissions matrix and role specifications for all FlowX roles.
> >
> > Access Management
>
> ***
>
> ### **Performance and stability**
>
> > [card] Performance and stability
> >
> > FlowX.AI 5.3 includes platform improvements focused on performance, reliability, and operational excellence.
> >
> > ## Backend optimizations
> >
> > > [card] Optimistic lock improvements
> > >
> > > Replace retry pattern with capped exponential backoff and infinite retries for better concurrency handling
> >
> > > [card] Events gateway optimization
> > >
> > > Update Redis read mode to XREAD BLOCK for more efficient event streaming
> >
> > > [card] Database performance
> > >
> > > Remove unnecessary index on token\_instance.current\_node\_id to improve update performance
> >
> > > [card] Template caching
> > >
> > > Enhanced caching for reusable templates at runtime reduces latency and improves throughput
> >
> > ## Infrastructure updates
> >
> > > [card] Connector Topic Pattern
> > >
> > > Added dedicated KAFKA\_CONNECTORS\_TOPIC\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [card] SpiceDB backup
> > >
> > > Documented backup and restore procedures for SpiceDB for disaster recovery
> >
> > > [card] Observability
> > >
> > > Publish Prometheus and OpenTelemetry Helm charts and container images to Harbor
> >
> > > [card] Security updates
> > >
> > > Fix HIGH vulnerabilities in Designer 5.1.x and main branch
> >
> > > [card] Renderer improvements
> > >
> > > Enhanced Angular renderer with action form submit functionality and substitution tag support
> >
> > Platform Updates
>
> ***
>
> ### **Exclusive gateways**
>
> > [card] Exclusive gateways
> >
> > FlowX.AI 5.3 enhances Exclusive Gateway configuration with expression testing capabilities and improved validation.
> >
> > > [card] Expression testing
> > >
> > > Test gateway expressions directly from the configuration panel with real-time validation
> >
> > > [card] Committed version testing
> > >
> > > Test business rules and gateway expressions in committed versions
> >
> > > [card] Code editor integration
> > >
> > > Enhanced code editor with syntax highlighting for complex expressions
> >
> > > [card] Payload synchronization
> > >
> > > Test payloads automatically update when rules are saved
> >
> > Process Logic
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes and stability improvements across Designer, renderers, backend services, and data management.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI Designer and Integration Designer stability improvements\
> 🖥️ [**Renderer Fixes**](#renderer-fixes) - Cross-platform renderer bug fixes for web, iOS, and Android\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements\
> 🗄️ [**Data & Integration Fixes**](#data-and-integration-fixes) - Data mapper and workflow integration fixes
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.3 resolves numerous Designer issues to improve stability and user experience.
> >
> > ## UI designer improvements
> >
> > > [accordion] Configuration & styling
> > >
> > > * **Fixed styles not applied after undo/redo** in Reusable UI Template config panel
> > > * **Fixed UI blocking** when slider min value exceeds max value
> > > * **Fixed warning icon display** in config panel
> > > * **Fixed expression test modal styles** when opened in resized screen
> > > * **Fixed UI action section refresh** when selecting different UI template
> > > * **Fixed UI action section rendering** after clicking 'Add new ui action'
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed loading spinner toggle** not available for Overlay loading behavior
> > > * **Fixed incomplete loading behavior dropdown**
> > > * **Fixed default messages** not displayed after undo
> > > * **Fixed forms in collections handling** for patch actions requests
> >
> > > [accordion] UI Flows designer
> > >
> > > * **Fixed task management error state** when view is selected
> > > * **Fixed tab content preview** showing content from 2 tabs when adding new tab
> >
> > > [accordion] Output parameters
> > >
> > > * **Fixed currency key management** - can now add/remove currency key in output params
> >
> > > [accordion] Exclusive Gateways
> > >
> > > * **Fixed gateway decisions** can now be modified after initial save
> > > * **Fixed test payload** updates when rules are saved
> > > * **Fixed expression propagation** to test modal
> >
> > ## Frontend runtime fixes
> >
> > > [accordion] Process management
> > >
> > > * **Fixed context column** showing empty value for tokens in embedded subprocesses
> > > * **Fixed process params update** from running process instance modal
> > > * **Fixed long node names** overlapping adjacent columns in Tokens table
> > > * **Fixed workspace redirect** on page refresh
> >
> > > [accordion] Audit & logging
> > >
> > > * **Fixed audit log subject value** not displayed for process params updates
> > > * **Fixed toast error messages** to use text from backend request
> > > * **Added documentation link** to Modify Variables modal info text
> >
> > Designer Stability
>
> ***
>
> ### **Renderer fixes**
>
> > [card] Renderer fixes
> >
> > FlowX.AI 5.3 includes comprehensive renderer fixes across all platforms.
> >
> > ## Web renderers (Angular & React)
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed theming** not applied to general loader
> > > * **Fixed theming** not applied to toast messages
> > > * **Fixed dynamic key values** not displayed in toast/loading messages
> > > * **Fixed success toast** displayed when flag is false
> >
> > > [accordion] Card & navigation
> > >
> > > * **Fixed card not expandable** after finishing subprocess started from it (Angular & React)
> > > * **Fixed card collapse** when next nav area is modal (Angular & React)
> > > * **Fixed subprocess navigation** closing parent process navigation with multiple hierarchies
> >
> > > [accordion] UI events
> > >
> > > * **Fixed UI event triggering** without user interaction (Angular)
> >
> > > [accordion] Call activity
> > >
> > > * **Fixed call activity UT rendering** when started from embedded process
> >
> > > [accordion] Collections & forms
> > >
> > > * **Fixed button with forms to submit** no longer disabled until template edited (Angular & React)
> > > * **Fixed multi-select search** filtering (React)
> > > * **Fixed JSON generation** with special characters in CollectionsV2
> >
> > ## Mobile renderers
> >
> > > [accordion] Android
> > >
> > > * **Fixed SSE Event & UI Event** - UI event value displayed instead of SSE value
> >
> > Renderer Stability
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process management
> >
> > > [accordion] Process & build issues
> > >
> > > * **Fixed processes not displayed** in container app list for imported builds
> > > * **Fixed token state** changing from Aborted to Active during back navigation
> > > * **Fixed audit logs** for override operations after merge
> >
> > > [accordion] Performance
> > >
> > > * **Fixed /details endpoint** returning cache error for processes with many components
> >
> > > [accordion] Process engine
> > >
> > > * **Fixed token stuck** in receive node when message received after advancing
> > > * **Fixed action params** copied correctly for child actions when copying node
> > > * **Fixed metadata preservation** when importing process
> >
> > ## Security & configuration
> >
> > > [accordion] Authentication
> > >
> > > * **Fixed service account client secret** configuration parameter in Authorization service
> >
> > ## Data management
> >
> > > [accordion] Runtime issues
> > >
> > > * **Fixed FlowxProps.events** mapping at runtime for array of objects
> >
> > ## Infrastructure
> >
> > > [accordion] Database & events
> > >
> > > * **Fixed advancing errors** in partition event table
> > > * **Fixed Liquibase logging** when crashing due to lock
> >
> > Backend Stability
>
> ***
>
> ### **Data and integration fixes**
>
> > [card] Data and integration fixes
> >
> > Fixes for data mappers and workflow integration features.
> >
> > ## Data mapper issues
> >
> > > [accordion] Mapping operations
> > >
> > > * **Fixed 400 error** when saving mappings
> > > * **Fixed error** when saving mapping with empty parameters
> > > * **Fixed unsaved mapping modal** displayed when saving action
> > > * **Fixed array mapping** - arrays in mapper functions now work correctly
> > > * **Fixed slice deletion** when updating PDM objects
> >
> > > [accordion] Data streams & workflows
> > >
> > > * **Fixed data stream availability** for older exports during import
> > > * **Fixed workflow data stream** data appending issue
> > > * **Fixed legacy mapping** toggle now triggers correctly for call activity
> >
> > > [accordion] UI updates
> > >
> > > * **Fixed start node** not updated in UI after parameters update until refresh
> > > * **Fixed manifest resource** not found after switching versions
> >
> > > [!NOTE]
> > >
> > > Data mapper fixes ensure reliable workflow integration and process-to-workflow data synchronization.
> >
> > Integration Stability
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.3.0](./deployment-guidelines-v5.3).
>
> ### Environment variable updates
>
> > [!NOTE]
> >
> > For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.
>
> ### Breaking changes
>
> > [!WARNING]
> >
> > **FlowX Engine Configuration**: v5.3.0 includes a breaking change to the partitioning and archiving configuration structure. If you have enabled data partitioning, you must update your configuration files.
>
> > [card] [Migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
> >
> > Complete migration guide with step-by-step instructions, configuration examples, and troubleshooting
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.2.0 requires configuration changes for FlowX Engine partitioning/archiving
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.3


# Deployment guidelines v5.4.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/deployment-guidelines-v5.4

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.38.0** | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **10.38.0** | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **10.22.0** | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **10.15.0** | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **10.17.0** | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **10.22.0** | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **10.23.0** | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **10.25.0** | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **10.14.0** | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **10.21.0** | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **10.16.0** | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **10.38.0** | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **10.20.1** | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **10.28.0** | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **10.17.0** | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **email-gateway** | **10.9.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 |

### AI Platform

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.4.0 | Keycloak | 26+ |
| 5.4.0 | Kafka | 3.8 - 3.9 |
| 5.4.0 | PostgreSQL | 16 - 17 |
| 5.4.0 | Oracle Database | 21c, 23ai |
| 5.4.0 | MongoDB | 7 - 8 |
| 5.4.0 | Redis | 7.4 - 8.0 |
| 5.4.0 | Elasticsearch | 8 |
| 5.4.0 | Angular (Web SDK) | 20 |
| 5.4.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.4.0

### Key features and updates

> [card] Email Trigger
>
> Start processes automatically from incoming emails with configurable validation rules

> [card] MCP Server Improvements
>
> Enhanced audit logging, resource management, and tool refresh capabilities

> [card] Email Gateway
>
> New microservice for handling email communication workflows

## Upgrading from v5.3.0

### Breaking changes

> [!NOTE]
>
> FlowX.AI 5.4.0 does not introduce breaking changes for standard deployments. Upgrades from v5.3.0 should be straightforward.

### New environment variables

The following new environment variables have been introduced:

| Variable | Service | Description |
| - | - | - |
| `KAFKA_CONNECTORS_TOPIC_PATTERN` | process-engine | Dedicated Kafka topic pattern for connectors (optional, falls back to `KAFKA_TOPIC_PATTERN` if not set) |
| `KAFKA_BOOTSTRAP_SERVERS` | All services | Standardized Kafka bootstrap servers property (preferred over `SPRING_KAFKA_BOOTSTRAPSERVERS`, backwards compatible) |
| `KAFKA_SECURITY_PROTOCOL` | All services | Standardized Kafka security protocol property (preferred over `SPRING_KAFKA_SECURITY_PROTOCOL`, backwards compatible) |

### Key changes

* **Email Trigger**: New capability to start processes from email events
* **Connector Topics**: New dedicated topic pattern variable for connectors
* **Kafka Configuration**: Standardized Kafka property names (`KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_SECURITY_PROTOCOL`) aligned across all services with backwards compatibility
* **Email Gateway**: New microservice for email communication workflows

### New microservice: Email Gateway

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces a new optional microservice: **Email Gateway**. This service handles email communication workflows within the platform.

The Email Gateway requires the following infrastructure:

| Component | Requirement |
| - | - |
| PostgreSQL | Dedicated database named `email_gateway` |
| MongoDB | Connection to existing `app-runtime` database |
| Kafka | Access to the FlowX Kafka cluster |
| Redis | Shared Redis instance |
| Keycloak | Service account for authentication |

> [!NOTE]
>
> The Email Gateway operates as an internal service and does not require ingress configuration.

> [card] [Email Gateway Setup Guide](/5.9/setup-guides/email-gateway-setup)
>
> Complete setup instructions including Helm values, environment variables, and troubleshooting.

### Compatibility

* **No Breaking Changes**: Standard deployments can upgrade without configuration changes
* **Feature Additions**: SaaS features require additional infrastructure configuration for production use
* **Renderer Updates**: Web and mobile SDKs include bug fixes with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.4.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026

SaaS multi-tenant platform capabilities, database tenant isolation, email-triggered processes, MCP server enhancements, and backend performance improvements.

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces foundational support for a multi-tenant platform, enabling organization management and improved tenant isolation in the SaaS deployment model.

> [!NOTE]
>
> **Deployment models** - Starting with v5.4.0, FlowX.AI is available in two deployment models:
>
> * **Self-Managed** (On-Premises / Customer Cloud)
> * **FlowX SaaS** (FlowX-hosted)
>
> **Feature availability badges:**
>
> * SaaS Features exclusive to FlowX SaaS deployments
> * Self-Managed Features specific to self-managed deployments
> * All Deployments Features available in both deployment models

**What's new?**

> [tab] SaaS & multi-tenancy
>
> > [!NOTE]
> >
> > The features described in this section apply to **FlowX SaaS deployments**.\
> > Self-managed deployments are not affected unless explicitly stated.
>
> FlowX.AI 5.4.0 introduces initial SaaS capabilities enabling multi-tenant deployments with organization management and tenant isolation.
>
> 🏢 [**SaaS Multi-Tenancy**](#saas-multi-tenancy) - Multi-tenant platform with organization isolation and provisioning
>
> ### **SaaS multi-tenancy**
>
> > [card] SaaS multi-tenancy
> >
> > Multi-tenant SaaS capabilities enable multiple organizations to operate independently on shared infrastructure. Each organization receives dedicated resources while maintaining complete isolation from other tenants.
> >
> > > [card] Multi-tenant architecture
> > >
> > > Multiple organizations operate on shared infrastructure with complete isolation
> >
> > > [card] Tenant isolation
> > >
> > > Complete data and authentication isolation between organizations
> >
> > > [card] Organization provisioning
> > >
> > > Automatic provisioning of dedicated resources for each organization
> >
> > > [card] Resource management
> > >
> > > Each organization receives dedicated resources and project spaces
> >
> > > [card] [Documentation](/5.9/docs/saas/saas-overview)
> > >
> > > See the complete FlowX SaaS documentation for guides and best practices.
> >
> > Major FeatureSaaS
>
> ***

> [tab] AI & Integration
>
> Enhanced MCP server management.
>
> 📧 [**Email Trigger**](#email-trigger) - Start processes from external email events with configurable validation rules\
> 💬 [**Chat Component**](#chat-component) - Standalone chat tab for AI-powered conversational interfaces\
> 🔧 [**MCP Server Improvements**](#mcp-server-improvements) - Enhanced audit logging, resource management, and tool updates
>
> ### **Email trigger**
>
> > [card] Email trigger
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces Email Trigger as a new Data Source type in Integration Designer, enabling processes to be started automatically when emails are received. Connect to IMAP mail servers, monitor specific mailboxes, and create process instances with the email data.
> > >
> > > > [!NOTE]
> > > >
> > > > Email Triggers bridge external communication channels with FlowX.AI process automation, enabling organizations to automatically route and process incoming emails through defined business workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation for configuration guides and examples.
> >
> > > [tab] Key Features
> > >
> > > > [card] IMAP Connection
> > > >
> > > > Connect to any IMAP-compatible email server with SSL/TLS support
> > >
> > > > [card] Message Start Event
> > > >
> > > > New trigger type option in Message Start Event nodes to use Email Triggers
> > >
> > > > [card] Attachment handling
> > > >
> > > > Automatic upload of email attachments to Document Plugin with file validation
> > >
> > > > [card] Validation rules
> > > >
> > > > Configure allowed file types, maximum file size, and attachment count limits
> > >
> > > > [card] Manage triggers
> > > >
> > > > Central Runtime page to activate, deactivate, and monitor email triggers
> > >
> > > > [card] Failed triggers
> > > >
> > > > Dedicated page to view and troubleshoot failed email processing attempts
> >
> > > [tab] Configuration
> > >
> > > **Data Source Settings:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | IMAP (currently supported) |
> > > | Server Host | IMAP server hostname |
> > > | Port | Connection port (993 for SSL/TLS) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > > | SSL/TLS | Enable secure connection |
> > >
> > > **Filtering Criteria:**
> > >
> > > * **Email Address**: Monitored email address (read-only, based on authentication)
> > > * **Mailbox Folder**: Folder to monitor (default: Inbox)
> > >
> > > **Validation Options:**
> > >
> > > * **Allowed File Types**: PDF, DOCUMENT, IMAGE, EXCEL, ZIP
> > >
> > > * **Maximum File Size**: Up to 25 MB per attachment
> > >
> > > * **Maximum File Count**: Limit attachments per email
> > >
> > > > [!TIP]
> > > >
> > > > All fields accept configuration parameters using `${configParam}` syntax for environment-specific values.
> >
> > > [tab] Email Data Schema
> > >
> > > When an email triggers a process, the following data structure is available:
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "emailMessage": {
> > >     "subject": "Support Request #12345",
> > >     "dateTime": "2026-01-15T10:30:00Z",
> > >     "sender": "customer@example.com",
> > >     "body": "Email body content...",
> > >     "fileAttachments": [{
> > >       "filePath": "email-attachments/proc-123/file.pdf",
> > >       "downloadPath": "/api/internal/files/uuid/download"
> > >     }],
> > >     "headerParams": {
> > >       "Message-ID": "<abc123@example.com>"
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Use Cases
> > >
> > > > [card] Customer support automation
> > > >
> > > > Automatically create support tickets from incoming customer emails
> > >
> > > > [card] Document processing
> > > >
> > > > Process attached documents through automated workflows
> > >
> > > > [card] Request handling
> > > >
> > > > Route requests to appropriate departments based on email content
> > >
> > > > [card] Notification processing
> > > >
> > > > Process automated notifications from external systems
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat component**
>
> > [card] Chat component
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a standalone Chat tab in web container applications, enabling AI-powered conversational interfaces within your applications. The Chat component provides a dedicated space for users to interact with AI agents through a familiar messaging interface.
> > >
> > > > [!NOTE]
> > > >
> > > > The Chat component integrates with FlowX.AI's AI platform to enable intelligent conversational experiences powered by your configured AI agents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the complete Chat Component documentation for configuration guides and best practices.
> >
> > > [tab] Key Features
> > >
> > > > [card] Standalone chat tab
> > > >
> > > > Dedicated chat interface available as a standalone tab in web container apps
> > >
> > > > [card] Message history
> > > >
> > > > Persistent chat history with automatic scrolling to the latest messages
> > >
> > > > [card] AI agent integration
> > > >
> > > > Connect to workflows powered by AI agents
> > >
> > > > [card] Session management
> > > >
> > > > Automatic session handling with persistence across page refreshes
> > >
> > > > [card] Customizable UI
> > > >
> > > > Themeable components with comprehensive style configuration through Theme Admin
> >
> > > [tab] Configuration
> > >
> > > **Component setup:**
> > >
> > > * Add Chat component from UI Designer to your UI Flow
> > > * Select a workflow to handle chat interactions
> > > * Configure header, messages, and input properties
> > > * Apply custom styling through Theme Admin
> > >
> > > **Display modes:**
> > >
> > > * Full screen (v5.4.0)
> > > * Additional modes planned for v5.5
> >
> > > [tab] Improvements
> > >
> > > **Session handling:**
> > >
> > > * Chat session ID is now generated when the first message is sent (not when opening the chat)
> > > * Improved session tracking
> > >
> > > **Message display:**
> > >
> > > * Latest messages are automatically scrolled into view after loading chat history
> > > * User input formatting (JSON, multiline text) is now preserved in displayed messages
> > >
> > > **Platform support:**
> > >
> > > * Available in both Angular and React web renderers
> > > * Mobile support planned for v5.5
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **MCP server improvements**
>
> > [card] MCP server improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 enhances MCP (Model Context Protocol) server integration with improved audit logging, exception handling, and resource management capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audit logging
> > > >
> > > > Complete audit trail for MCP server operations including creation, updates, and tool execution
> > >
> > > > [card] Tool refresh
> > > >
> > > > Update MCP servers to fetch new tools without recreating the data source
> > >
> > > > [card] Resource tracking
> > > >
> > > > Track MCP server usage across workflows with proper resource management
> > >
> > > > [card] Copy support
> > > >
> > > > Properly preserve MCP server selections when copying or duplicating workflows
> > >
> > > > [card] SSE streaming
> > > >
> > > > Fixed SSE event streaming to deliver events individually as they complete
> > >
> > > > [card] Exception handling
> > > >
> > > > Improved error handling and reporting for MCP server operations
> >
> > > [tab] Bug Fixes
> > >
> > > * **Tool updates**: Updating MCP servers now correctly fetches new tools
> > > * **Workflow copy**: MCP server selections are preserved when copying workflows
> > > * **Resource usages**: Fixed resource usage tracking when copying workflows to other projects
> > > * **SSE events**: Events are now streamed individually instead of all at once
> > > * **Audit entries**: Fixed missing event and subject in audit log entries
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] Rendering
>
> UI component enhancements and navigation improvements for web applications.
>
> 🎴 [**Card Default Collapse State**](#card-default-collapse-state) - Configure cards to load in collapsed state by default\
> 🧭 [**UI Flow Breadcrumbs**](#ui-flow-breadcrumbs) - Navigation breadcrumbs ui component for UI Flows with theme configuration\
> 📊 [**UI Flow Sessions**](#ui-flow-sessions) - Monitor and manage UI Flow sessions with audit logs and process tracking\
> 📋 [**Tables in Collections**](#tables-in-collections) - Add support for Table UI components within Collection UI elements
>
> ### **Card default collapse state**
>
> > [card] Card default collapse state
> >
> > FlowX.AI 5.4.0 introduces a new **Default collapse state** property for Card components with accordion functionality, allowing you to configure cards that are collapsed when first loaded.
> >
> > > [tab] Overview
> > >
> > > When using Card components with the accordion feature enabled, you can now specify whether the card should be expanded or collapsed by default when the screen loads. This provides better control over the initial presentation of content and helps manage screen real estate.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> > > >
> > > > See the complete Card component documentation for configuration details.
> >
> > > [tab] Configuration
> > >
> > > **Default collapse state options:**
> > >
> > > | State | Description |
> > > | - | - |
> > > | **Expanded** | The card content is visible when the screen loads (default behavior) |
> > > | **Collapsed** | The card content is hidden when the screen loads; users click to expand |
> > >
> > > > [!NOTE]
> > > >
> > > > This property is only available when the **Has accordion** setting is enabled on the Card component.
> >
> > > [tab] Use Cases
> > >
> > > > [card] Progressive disclosure
> > > >
> > > > Start with collapsed sections to reduce initial visual complexity
> > >
> > > > [card] Optional content
> > > >
> > > > Hide less important information by default while keeping it accessible
> > >
> > > > [card] Long forms
> > > >
> > > > Break up lengthy forms into collapsible sections for better navigation
> > >
> > > > [card] FAQ sections
> > > >
> > > > Display questions collapsed with answers revealed on click
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Breadcrumbs**
>
> > [card] UI Flow Breadcrumbs
> >
> > > [tab] Overview
> > >
> > > Navigation breadcrumbs UI component for UI Flows provide users with clear context of their current location within the application hierarchy. Breadcrumbs display the navigation path and enable quick navigation to parent screens.
> > >
> > > > [!NOTE]
> > > >
> > > > Breadcrumbs enhance user experience by providing visual navigation context and allowing users to understand their position in the application structure.
> >
> > > [tab] Key Features
> > >
> > > > [card] Navigation breadcrumbs UI component
> > > >
> > > > Display breadcrumbs UI component for UI Flows showing the current navigation path
> > >
> > > > [card] Admin theme configuration
> > > >
> > > > Configure breadcrumb appearance and styling through Admin theme settings
> >
> > > [tab] Configuration
> > >
> > > **Theme Configuration:**
> > >
> > > * Configure breadcrumb styling through Admin theme settings
> > > * Customize colors, fonts, and spacing to match your application design
> > > * Apply consistent styling across all UI Flows
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Sessions**
>
> > [card] UI Flow Sessions
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces UI Flow Sessions monitoring in the Runtime view, providing comprehensive visibility into active user sessions with UI Flows. Monitor session activity, view audit logs, track associated processes, and debug UI Flow interactions in real-time.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flow Sessions enable administrators and developers to track user interactions, troubleshoot issues, and monitor the health of UI Flow-based applications.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> > > >
> > > > See the complete UI Flow Sessions documentation for detailed usage and troubleshooting guides.
> >
> > > [tab] Key Features
> > >
> > > > [card] Session monitoring
> > > >
> > > > View all active and historical UI Flow sessions with status, start date, and session IDs
> > >
> > > > [card] Audit log
> > > >
> > > > Comprehensive audit trail showing all events and actions within each session
> > >
> > > > [card] Process tracking
> > > >
> > > > Monitor process instances started from UI Flows with execution status and timing
> > >
> > > > [card] Workflow debugging
> > > >
> > > > View workflow execution details, node timing, and data transformations for troubleshooting
> > >
> > > > [card] Filtering and search
> > > >
> > > > Filter sessions by UI Flow definition and search by session ID for quick access
> > >
> > > > [card] Real-time status
> > > >
> > > > Track session status updates in real-time (STARTED, ACTIVE, FINISHED, FAILED)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Session monitoring
> > > >
> > > > Monitor active sessions to understand user engagement and identify sessions needing attention
> > >
> > > > [card] Audit and compliance
> > > >
> > > > Track all user interactions and actions for audit purposes and compliance requirements
> > >
> > > > [card] Debugging
> > > >
> > > > Investigate issues by reviewing audit logs, process instances, and workflow executions
> > >
> > > > [card] Performance analysis
> > > >
> > > > Analyze session duration, process start times, and workflow execution performance
> >
> > Runtime ManagementAll Deployments
>
> ***
>
> ### **Tables in Collections**
>
> > [card] Tables in Collections
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces support for Table UI components within Collection UI elements, enabling you to display structured tabular data as items within dynamic collections. This enhancement provides greater flexibility for presenting complex data structures in a consistent, organized format.
> > >
> > > > [!NOTE]
> > > >
> > > > You can now embed Table components inside Collection prototypes, allowing each collection item to display data in a structured table format with columns, rows, and table-specific features.
> > >
> > > > [card] [Table Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/table)
> > > >
> > > > See the complete Table component documentation for configuration details and usage examples.
> > >
> > > > [card] [Collection Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/collection/collection)
> > > >
> > > > Learn about Collection components and how to configure collection prototypes.
> >
> > > [tab] Key Features
> > >
> > > > [card] Table in collection items
> > > >
> > > > Embed Table components within Collection prototypes to display structured data for each collection item
> > >
> > > > [card] Structured data display
> > > >
> > > > Present complex data structures with columns, rows, and table-specific formatting within collections
> > >
> > > > [card] Table features
> > > >
> > > > Leverage full Table component capabilities including sorting, filtering, pagination, and row actions
> > >
> > > > [card] Dynamic content
> > > >
> > > > Combine Collection's dynamic data handling with Table's structured presentation for flexible layouts
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product catalogs
> > > >
> > > > Display product information in table format within a collection of products
> > >
> > > > [card] Data dashboards
> > > >
> > > > Create dashboard views with multiple tables showing different data sets in collection items
> > >
> > > > [card] Report listings
> > > >
> > > > Show report summaries in table format within a collection of reports
> > >
> > > > [card] Comparison views
> > > >
> > > > Compare multiple entities side-by-side using tables within collection items
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Platform & infrastructure
>
> Backend optimizations, connector improvements, and platform stability enhancements.
>
> 🔌 [**Connector Topic Pattern**](#connector-topic-pattern) - Dedicated Kafka topic pattern for connectors\
> ⚙️ [**Kafka Configuration Alignment**](#kafka-configuration-alignment) - Unified Kafka property names across all services with backwards compatibility\
> ⚡ [**Advancing Performance**](#advancing-performance) - Fixed advancing partition issues and improved concurrency handling
>
> ### **Connector topic pattern**
>
> > [card] Connector topic pattern
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a dedicated Kafka topic pattern variable (`KAFKA_CONNECTORS_TOPIC_PATTERN`) for connectors, allowing custom topic patterns without affecting other platform components like document-plugin, data-search, and cms-core.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Shared topic pattern
> > > >
> > > > Connectors used the same `KAFKA_TOPIC_PATTERN` as other components, limiting customization
> > >
> > > > [card] Security concerns
> > > >
> > > > Connectors could write to all topics with the pattern `ai.flowx.engine.receive.*`
> >
> > > [tab] Solution
> > >
> > > **New Configuration:**
> > >
> > > ```yaml theme={"dark"}
> > > # Old configuration (shared with all components)
> > > KAFKA_TOPIC_PATTERN: ai.flowx.engine.receive.*
> > >
> > > # New configuration (dedicated for connectors)
> > > KAFKA_CONNECTORS_TOPIC_PATTERN: ro.uniflow.*
> > > ```
> > >
> > > **Benefits:**
> > >
> > > * Connectors can use custom topic patterns
> > > * Other components continue using the standard pattern
> > > * Improved security through topic isolation
> >
> > InfrastructureSelf-Managed
>
> ***
>
> ### **Kafka configuration alignment**
>
> > [card] Kafka configuration alignment
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 aligns Kafka configuration properties across all services (core-services and AI platform services) by introducing standardized property names while maintaining full backwards compatibility with existing configurations.
> >
> > > [tab] New Properties
> > >
> > > **Standardized Kafka Properties:**
> > >
> > > The following new environment variables are now available across all services:
> > >
> > > | Environment Variable | Description | Fallback Property |
> > > | - | - | - |
> > > | `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers | `SPRING_KAFKA_BOOTSTRAP_SERVERS` |
> > > | `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka communication | `SPRING_KAFKA_SECURITY_PROTOCOL` |
> > >
> > > > [!NOTE]
> > > >
> > > > The new properties take precedence over the legacy `SPRING_KAFKA_*` properties. If the new properties are not set, the system automatically falls back to the legacy properties, ensuring backwards compatibility.
> >
> > > [tab] Benefits
> > >
> > > > [card] Property alignment
> > > >
> > > > Consistent property names across core-services and AI platform services
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing configurations using `SPRING_KAFKA_*` properties continue to work without changes
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Unified configuration approach across all FlowX.AI services
> > >
> > > > [card] Migration flexibility
> > > >
> > > > Migrate to new properties at your own pace without breaking existing deployments
> > >
> > > > [!NOTE]
> > > >
> > > > This change was implemented in core-services and automatically applies to all services that use the shared Kafka configuration. No action is required for existing deployments, but you can optionally migrate to the new property names for consistency.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Advancing performance**
>
> > [card] Advancing performance
> >
> > FlowX.AI 5.4.0 includes significant fixes and improvements to the advancing mechanism, resolving issues with stalled events and improving concurrency handling.
> >
> > > [accordion] Stalled events fix
> > >
> > > Fixed issue where NEW entries in `advancing_partition` and `advancing_partition_event` tables would become stalled and never processed. This occurred when multiple events were generated for the same partition during parallel processing.
> >
> > > [accordion] Numeric overflow fix
> > >
> > > Fixed numeric overflow error when `advancing_partition_event_seq` sequence exceeded `Integer.MAX_VALUE`. Now correctly uses `getLong()` instead of `getInt()` for sequence values.
> >
> > > [accordion] Concurrency improvements
> > >
> > > * Fixed issue with multiple events to the same partition causing negative `count_queued_events`
> > > * Replaced trigger-based solution with SQL transactions for atomic updates
> > > * Improved handling of embedded subprocess completion under concurrent load
> >
> > > [accordion] Automated test stability
> > >
> > > Resolved data inconsistencies and business exceptions that were causing automated tests to fail consistently.
> >
> > PerformanceAll Deployments
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes across SaaS features, Designer, and backend services.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI and navigation fixes for Designer\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.4.0 resolves Designer issues to improve stability and user experience.
> >
> > ## Navigation & routing
> >
> > > [accordion] Navigation fixes
> > >
> > > * **Fixed sidebar display** - sidebar menu now shows when accessing pages via URL
> > > * **Fixed subprocess navigation** - resolved 403 when navigating to subprocesses
> > > * **Fixed back navigation** - resolved 403 when going back from UI Flows page
> > > * **Fixed audit log access** - resolved errors when viewing process instance audit logs
> > > * **Fixed version history** - "Open version in new tab" now works correctly
> >
> > > [accordion] UI improvements
> > >
> > > * **Fixed default locale display** - locale now correctly shown in Version settings
> > > * **Fixed substitution calls** - resolved errors when starting processes or accessing UI Flows
> >
> > Designer StabilityAll Deployments
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process engine
> >
> > > [accordion] Advancing & concurrency
> > >
> > > * **Fixed stalled advancing events** - NEW entries no longer get stuck in advancing tables
> > > * **Fixed numeric overflow** - resolved overflow when sequence exceeds Integer.MAX\_VALUE
> > > * **Fixed concurrent updates** - resolved stale data errors for embedded subprocess completion
> > > * **Fixed negative counter** - resolved issue with `count_queued_events` going negative
> >
> > ## AI platform
> >
> > > [accordion] AI integration fixes
> > >
> > > * **Fixed multi-agent streaming** - streaming now works correctly for multi-agent chat
> > > * **Fixed SSE event delivery** - events are delivered individually as they complete
> >
> > ## Integration Designer
> >
> > > [accordion] Workflow & data model
> > >
> > > * **Fixed file upload multipart** - only file name is sent in multipart body, not full path
> > > * **Fixed data model duplicates** - resolved duplicate entries in mongo properties\_paths
> >
> > Backend StabilityAll Deployments
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.4.0](./deployment-guidelines-v5.4).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.3.0 - no breaking changes for standard deployments
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.4
>
> ### SaaS features
>
> > [!NOTE]
> >
> > The SaaS multi-tenant features introduced in this release require additional infrastructure configuration for production deployments. Contact your FlowX.AI representative for guidance on enabling SaaS capabilities.


# Deployment guidelines v5.5.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/deployment-guidelines-v5.5

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.60.0** | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 |
| **admin** | **10.53.0** | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 |
| **designer** | **10.91.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **cms-core** | **10.35.0** | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **10.25.0** | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **10.27.0** | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **10.35.0** | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **10.35.0** | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **10.35.0** | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 |
| **data-search** | **10.25.0** | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **10.31.0** | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **10.27.0** | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 |
| **integration-designer** | **10.63.0** | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 |
| **application-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **data-sync** | **10.31.1** | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 |
| **authorization-system** | **10.42.1** | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **10.27.0** | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 |
| **email-gateway** | **10.24.0** | 10.9.0 | - | - | - | - |
| **organization-manager** | **10.19.2** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 |
| **Android renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 |
| **di-platform** | **10.2.6** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **knowledgebase** | **TBD** | - | - | - | - | - |
| **knowledgebase-rag** | **10.2.0** | - | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.2.0** | - | - | - | - | - |
| **mcp** | **10.2.0** | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.5.0 | Keycloak | 26+ |
| 5.5.0 | Kafka | 3.8 - 3.9 |
| 5.5.0 | PostgreSQL | 16 - 17 |
| 5.5.0 | Oracle Database | 21c, 23ai |
| 5.5.0 | MongoDB | 7 - 8 |
| 5.5.0 | Redis | 7.4 - 8.0 |
| 5.5.0 | Elasticsearch | 8 - 9 |
| 5.5.0 | Angular (Web SDK) | 20 |
| 5.5.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.5.0

### Key features and updates

> [card] Chat Component Enhancements
>
> New subcomponents (reasoning, error, suggestions), display modes, and mobile support

> [card] UI Flows Improvements
>
> Process renderer component, start workflow action, and on load events

> [card] Microsoft Outlook Integration
>
> Native MS Graph data source for reading and sending Outlook emails

> [card] Send Notification Action
>
> Send emails and reply to received emails directly from processes via SMTP

> [card] Knowledge Base v2
>
> Updated Knowledge Base with audit, resource management, and improved UI

> [card] User Management Updates
>
> Password policy, DISABLED status, resend invitations, workspace environment types

## Upgrading from v5.4.0

### Breaking changes

> [!WARNING]
>
> FlowX.AI 5.5.0 introduces a **breaking change** to the default authentication mechanism across most platform services. If you rely on the default `SECURITY_TYPE` value or opaque-token introspection, action is required before upgrading.

#### Authentication mechanism change

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. This reflects a shift from opaque-token introspection to JWT-based authentication as the default security mechanism.

**Removed environment variables:**

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

**Changed default values:**

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

**Migration steps:**

**1. Update SECURITY\_TYPE if explicitly set**

If you explicitly set `SECURITY_TYPE=oauth2` in your deployment configuration, update it to `jwt-public-key` or remove it to use the new default.

**2. Remove deprecated opaque-token variables**

Remove all `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_*` variables from your Helm values, environment configs, or deployment manifests.

**3. Update service account client IDs**

Service account client IDs now follow the `flowx-{service-name}-sa` pattern (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Update your Keycloak service account configurations accordingly.

**4. Configure the service account realm**

Add the `security.oauth2.sa-realm` property to your configuration if your service account realm differs from the default.

**5. Remove legacy OAuth2 client variables**

Remove `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENT_ID`, `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`, and `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_*` variables from your configuration.

***

### Key changes

* **Authentication**: Default `SECURITY_TYPE` changed from `oauth2` to `jwt-public-key` (breaking change — see above)
* **Organization Manager**: New microservice for organization and tenant management
* **Chat Component**: Enhanced with new subcomponents (reasoning, error, suggestions), display modes, and mobile support
* **UI Flows**: New process renderer component, start workflow action, and on load UI event
* **Microsoft Outlook**: New MS Graph data source for Outlook email integration
* **Send Notification**: New action type for sending/replying to emails via SMTP
* **Knowledge Base v2**: Updated UI, audit trail, and resource management
* **Container Apps**: Enhanced authentication flow and landing page
* **File Upload**: Improved progress indicators, drag and drop, and large file support
* **File Encrypt/Decrypt**: New document plugin actions for file encryption and decryption
* **User Management**: Password policy updates, DISABLED status, resend invitations, workspace environment type
* **Process Variables Compare**: Monaco diff editor for comparing variable values
* **New Kafka topics**: Multiple new topics added across document-plugin, integration-designer, admin, application-manager, email-gateway, authorization-system, and notification-plugin

***

### New microservice: Organization Manager

> [!NOTE]
>
> **Available starting with FlowX.AI 5.5.0**
>
> The Organization Manager is a new microservice responsible for organization and tenant management, including user registration, organization lifecycle, and platform component health monitoring.

**Infrastructure requirements:**

| Dependency | Details |
| - | - |
| PostgreSQL | Dedicated database for organization data |
| Redis | Caching and session management |
| Kafka | Event publishing (organization events topic) |
| Keycloak/IAM | Authentication and realm management |
| SpiceDB | Authorization via CAS lib |

> [card] [Organization Manager Setup](/5.1/setup-guides/organization-manager-setup)
>
> Complete setup and configuration guide for the Organization Manager microservice

***

### New Kafka topics

FlowX.AI 5.5.0 introduces new Kafka topics across multiple services.

#### Document-plugin Kafka topics

New topics for file encryption, decryption, bulk document persistence, and UI Flow session document persistence operations.

**Input topics (document-plugin consumes from these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Triggers file decryption operations |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Triggers file encryption operations |
| `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Triggers bulk document persistence operations |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway |

**Output topics (document-plugin publishes to these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Results from file decryption operations |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Results from file encryption operations |
| `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Results from bulk document persistence |
| `ai.flowx.eventsgateway.receive.document.v1` | Document upload progress notifications sent to events-gateway for SSE delivery |

#### Integration-designer Kafka topics

New topics for integration-designer in 5.5.0. Integration-designer now participates in the application sync mechanism for system and workflow resources.

> [!NOTE]
>
> The `sync.out.v1` and `correction-after-app-operation.response.v1` topics already exist since 5.1.x (used by admin). In 5.5.0, integration-designer becomes an additional producer on these shared response topics.

**New topics:**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync requests | Inbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System resource correction requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow resource correction requests | Inbound |
| `ai.flowx.build.runtime-data.v1` | Build runtime data | Outbound |
| `ai.flowx.license.usage.v1` | License usage tracking | Outbound |

**Existing topics (new producer in 5.5.0):**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.out.v1` | Sync operation responses | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | Correction operation responses | Outbound |

#### Admin Kafka topics

New topics for UI flow synchronization and correction operations in 5.5.0.

> [!NOTE]
>
> The `sync.process.in.v1`, `sync.business-rule.in.v1`, `sync.reusable-template.in.v1`, `sync.out.v1`, and `correction-after-app-operation` topics for process, business-rule, and reusable-template already exist since 5.1.x. Only the UI flow topics below are new in 5.5.0.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Inbound |

#### Application-manager Kafka topics

New outbound topics for resource synchronization and correction of system, workflow, and UI flow resources in 5.5.0.

> [!NOTE]
>
> Application-manager already produces sync and correction topics for process, business-rule, and reusable-template since 5.1.x. The topics below extend the same mechanism to system, workflow, and UI flow resources.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync | Outbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync | Outbound |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow resource sync | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Outbound |

#### Email-gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.save.audit.v1` | Audit event logging | Outbound |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Trigger process start from email events | Outbound |

#### Authorization-system Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.organization.events.v1` | Organization lifecycle events | Outbound |

#### Notification-plugin Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.resources-usages.refresh.v1` | Resource usages refresh events | Inbound |
| `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` | Sub-resource validation responses | Outbound |
| `ai.flowx.application-version.resources-usages.operations.bulk.v1` | Bulk resource usage operations | Outbound |

> [!NOTE]
>
> These topics are automatically created if your Kafka cluster has auto-topic creation enabled. For production environments, it is recommended to create them manually with appropriate partition counts and replication factors.

***

### New environment variables

#### Platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

#### Document-plugin variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) | document-plugin |

> [!NOTE]
>
> This setting affects all file uploads handled by the document-plugin. Configure alongside the existing Spring multipart settings (`SPRING_SERVLET_MULTIPART_MAXFILESIZE`, `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`) for consistent upload limits. See [Documents Plugin Setup](/5.1/setup-guides/documents-plugin-setup#multipart-upload-configuration).

#### Authorization-system variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client. Required for new deployments. | ` ` (empty) | authorization-system |

> [!WARNING]
>
> **New deployments only**: If this variable is not set, the `flowx-platform-authenticate` Keycloak client will have no redirect URIs and OAuth2 login will fail. Set this to your Designer and app URLs (e.g., `https://designer.yourcompany.com/*,https://app.yourcompany.com/*`).
>
> Existing deployments upgrading to 5.5.0 are not affected — the Liquibase migration that uses this variable has already run.

> [card] [Authorization System Setup](/5.1/setup-guides/authorization-setup-guide#keycloak-redirect-uris)
>
> See the full redirect URI configuration details

#### Email-gateway variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` | email-gateway |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` | email-gateway |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL` | TTL for cached MS Graph client instances | `1d` | email-gateway |

> [!NOTE]
>
> For complete email-gateway configuration including database, Redis, and Kafka settings, see the [Email Gateway Setup](/5.9/setup-guides/email-gateway-setup) guide.

***

### Compatibility

* **Authentication**: Default `SECURITY_TYPE` changed to `jwt-public-key` — deployments using opaque-token introspection require migration (see [breaking changes](#authentication-mechanism-change))
* **Renderer Updates**: Web and mobile SDKs include new Chat component features and UI Flows enhancements
* **Database**: No schema changes required for this upgrade
* **Mobile Support**: Chat component now available on iOS and Android renderers
* **New Service**: Organization Manager requires PostgreSQL, Redis, Kafka, and Keycloak infrastructure

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/migration-overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!WARNING]
>
> FlowX.AI v5.5.0 introduces a **critical breaking change** to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

## What's changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (`oauth2`) to JWT-based authentication (`jwt-public-key`). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — **Organization Manager** — has been introduced for organization and tenant management.

## Who is affected

> [!WARNING]
>
> **All deployments** are affected by the authentication mechanism change. The default `SECURITY_TYPE` value has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services.
>
> If you explicitly set `SECURITY_TYPE=oauth2` or rely on opaque-token introspection, you **must** update your configuration before upgrading.

## Migration process

**1. Back up your configuration**

Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.

**2. Update Keycloak service accounts**

Update your Keycloak service account client IDs to follow the new `flowx-{service-name}-sa` naming pattern. See [Update Keycloak service accounts](#update-keycloak-service-accounts) for the full mapping.

**3. Update environment variables**

Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.

**4. Deploy Organization Manager**

If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.

**5. Deploy and verify**

Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

***

## Authentication mechanism change

### Overview

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. Opaque-token introspection has been **removed entirely**.

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

### Changed default values

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

***

## Update Keycloak service accounts

Service account client IDs now follow the `flowx-{service-name}-sa` pattern. Update your Keycloak configuration to match:

| Service | New Client ID |
| - | - |
| Admin | `flowx-admin-sa` |
| Process Engine | `flowx-process-engine-sa` |
| Integration Designer | `flowx-integration-designer-sa` |
| Authorization System | `flowx-authorization-system-sa` |
| Runtime Manager | `flowx-runtime-manager-sa` |
| Scheduler Core | `flowx-scheduler-core-sa` |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager | `flowx-organization-manager-sa` |
| License | `flowx-license-sa` |
| Email Gateway | `flowx-email-gateway-sa` |

> [!WARNING]
>
> Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

***

## New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the **Organization Manager** microservice for organization and tenant management, user registration, and platform component health monitoring.

**Infrastructure requirements:**

* PostgreSQL
* Redis
* Kafka
* Keycloak/IAM
* SpiceDB

For full setup instructions, see the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility** for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

## Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your `SECURITY_TYPE` and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

> [!NOTE]
>
> Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

***

## Additional resources

> [card] [Update Environment Variables](./update-environment-variables-5.5)
>
> Per-service environment variable changes for v5.5.0

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions and deployment instructions

> [card] [IAM Configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution)
>
> Keycloak setup and service account configuration

> [card] [Release Notes v5.5.0](../v5.5.0-february-2026)
>
> Full release notes for v5.5.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/update-environment-variables-5.5

Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!NOTE]
>
> This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"dark"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

> [tab] Before (v5.4)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "oauth2"
>
> # Service account client ID (example for admin service)
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"
>
> # Token URI using main realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
> ```

> [tab] After (v5.5)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "jwt-public-key"
>
> # Service account client ID follows flowx-{service-name}-sa pattern
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"
>
> # Token URI now uses separate sa-realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
> ```

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

***

## Document plugin

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

> [!NOTE]
>
> **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` |

***

## Additional resources

> [card] [Migration Overview](./migration-overview)
>
> Full migration guide with Keycloak and service account changes

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions, Kafka topics, and infrastructure requirements


# FlowX.AI 5.5.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/v5.5.0-february-2026

Enhanced Chat component, UI Flows improvements, Microsoft Outlook integration, container app authentication, and platform management updates.

> [!NOTE]
>
> FlowX.AI 5.5.0 introduces significant enhancements to the Chat component, UI Flows capabilities, email integrations, and platform management features including Knowledge Base v2, user management improvements, and new document processing capabilities.

![Data Source types in FlowX 5.5.0](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_type_selector_all.png)

**What's new?**

> [tab] AI Platform
>
> AI-powered features and document processing enhancements.
>
> 📄 [**Extract Data from File**](#extract-data-from-file) - Configurable document and image extraction with LLM, OCR, and text parsing strategies\
> 📚 [**Knowledge Base v2**](#knowledge-base-v2) - Updated Knowledge Base with audit, resource management, and improved UI
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 renames "Extract Text from Document" to **Extract Data from File** and adds configurable extraction strategies, image input support, and signature detection. Choose between LLM, OCR, or text parsing strategies based on your document types, accuracy requirements, and cost constraints.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Extraction strategies
> > > >
> > > > Choose between LLM Model, OCR Engine, or Text Parsing for optimal accuracy/cost balance
> > >
> > > > [card] Image support
> > > >
> > > > Process images (JPG, PNG, TIFF) in addition to documents — automatic PDF conversion
> > >
> > > > [card] Image extraction options
> > > >
> > > > Extract data from embedded images or generate image descriptions
> > >
> > > > [card] Signature detection
> > > >
> > > > Detect and locate signatures within documents (LLM and OCR modes)
> >
> > > [tab] Configuration
> > >
> > > **Extraction strategies:**
> > >
> > > | Strategy | Best for | Speed | Cost | Accuracy |
> > > | - | - | - | - | - |
> > > | LLM Model | Complex layouts, handwritten text | Slow | High | High |
> > > | OCR Engine | Scanned documents | Medium | Medium | Medium |
> > > | Text Parsing | Clean digital PDFs | Fast | Free | Low–Medium |
> > >
> > > **Image extraction options (LLM and OCR only):**
> > >
> > > | Option | Description |
> > > | - | - |
> > > | Image Description | Generates text descriptions of images |
> > > | Image Content | Extracts text and data from images |
> > >
> > > > [!TIP]
> > > >
> > > > A new [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) covers backend service configuration, deployment sizing, and cost optimization.
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Knowledge Base v2**
>
> > [card] [Knowledge Base v2](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 updates the Knowledge Base with a refreshed UI, audit capabilities, and improved resource management. Knowledge Base entries now support versioning and provide better traceability for AI-powered features.
> >
> > > [tab] Key Features
> > >
> > > > [card] Updated UI
> > > >
> > > > Refreshed Knowledge Base interface with improved navigation and search
> > >
> > > > [card] Audit trail
> > > >
> > > > Track changes to Knowledge Base entries with full audit history
> > >
> > > > [card] Resource management
> > > >
> > > > Improved management of Knowledge Base resources and documents
> > >
> > > > [card] Version tracking
> > > >
> > > > Version-aware Knowledge Base entries tied to app versions
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] UI Flows
>
> Enhanced UI Flows with new components, actions, and chat improvements.
>
> 💬 [**Chat Component Enhancements**](#chat-component-enhancements) - New subcomponents, display modes, and mobile support\
> 🧭 [**UI Flows Breadcrumbs**](#ui-flows-breadcrumbs) - Navigation breadcrumbs for UI Flows\
> 📄 [**Process Renderer Component**](#process-renderer-component) - Embed process renderers within UI Flows\
> 🚀 [**Start Workflow Action**](#start-workflow-action) - Start workflows directly from UI Flows\
> ⚡ [**On Load UI Event**](#on-load-ui-event) - Execute actions when UI Flows load
>
> ### **Chat component enhancements**
>
> > [card] [Chat component enhancements](/5.9/ai-platform/chat-component)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 significantly enhances the Chat component with new subcomponents for reasoning, error handling, and suggestions. The component now supports multiple display modes and is available on mobile platforms.
> >
> > > [tab] New Subcomponents
> > >
> > > > [card] Reasoning display
> > > >
> > > > Show AI reasoning and thought process to users for transparency
> > >
> > > > [card] Error handling
> > > >
> > > > Graceful error display with retry options and helpful messages
> > >
> > > > [card] Suggestions
> > > >
> > > > Display suggested responses or actions to guide user interactions
> >
> > > [tab] Display Modes
> > >
> > > **Available display modes:**
> > >
> > > | Mode | Description |
> > > | - | - |
> > > | **Full screen** | Chat occupies the entire screen (available since v5.4.0) |
> > > | **Sidebar** | Chat appears as a collapsible sidebar |
> > > | **Floating** | Chat appears as a floating widget |
> > > | **Embedded** | Chat embedded within a container component |
> >
> > > [tab] Mobile Support
> > >
> > > The Chat component is now fully supported on mobile platforms:
> > >
> > > > [card] iOS
> > > >
> > > > Native iOS renderer support with optimized touch interactions
> > >
> > > > [card] Android
> > > >
> > > > Native Android renderer support with material design integration
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **UI Flows breadcrumbs**
>
> > [card] [UI Flows breadcrumbs](/5.9/docs/building-blocks/ui-flows#breadcrumbs)
> >
> > FlowX.AI 5.5.0 enhances the breadcrumbs navigation component for UI Flows, providing users with clear context of their current location and enabling quick navigation to parent screens.
> >
> > > [card] Navigation path
> > >
> > > Display the full navigation path within UI Flows
> >
> > > [card] Click navigation
> > >
> > > Navigate to any parent screen by clicking breadcrumb items
> >
> > > [card] Theme configuration
> > >
> > > Customize breadcrumb appearance through Admin theme settings
> >
> > > [card] Responsive design
> > >
> > > Breadcrumbs adapt to different screen sizes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process renderer component**
>
> > [card] [Process renderer component](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > > [tab] Overview
> > >
> > > Embed process renderers directly within UI Flows using the new Process Renderer component. This enables hybrid applications that combine UI Flow navigation with traditional process-based screens.
> >
> > > [tab] Key Features
> > >
> > > > [card] Process embedding
> > > >
> > > > Embed any process renderer within a UI Flow screen
> > >
> > > > [card] Data passing
> > > >
> > > > Pass data between UI Flows and embedded processes
> > >
> > > > [card] Event handling
> > > >
> > > > Handle process events within the UI Flow context
> > >
> > > > [card] Consistent styling
> > > >
> > > > Maintain consistent styling and navigation across UI Flows and processes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Start workflow action**
>
> > [card] [Start workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action)
> >
> > > [tab] Overview
> > >
> > > Start integration workflows directly from UI Flows using the new Start Workflow action. This enables UI Flows to trigger backend workflows without requiring a full process instance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow selection
> > > >
> > > > Select from available integration workflows
> > >
> > > > [card] Input mapping
> > > >
> > > > Map UI Flow data to workflow input parameters
> > >
> > > > [card] Response handling
> > > >
> > > > Handle workflow responses and update UI state
> > >
> > > > [card] Error handling
> > > >
> > > > Configure error handling for failed workflow executions
> >
> > UI EnhancementAll Deployments
>
> ### **On load UI event**
>
> > [card] [On load UI event](/5.9/docs/building-blocks/ui-designer/event-handlers#triggers)
> >
> > > [tab] Overview
> > >
> > > Execute actions automatically when UI Flow screens load using the new On Load UI Event. This enables initialization logic, data fetching, and setup operations when users navigate to a screen.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic execution
> > > >
> > > > Actions execute automatically when the screen loads
> > >
> > > > [card] Data initialization
> > > >
> > > > Fetch and initialize data when entering a screen
> > >
> > > > [card] Conditional logic
> > > >
> > > > Execute different actions based on conditions
> > >
> > > > [card] Loading states
> > > >
> > > > Manage loading states during initialization
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Integrations
>
> Email integrations, document processing, and Integration Designer updates.
>
> 📬 [**Microsoft Outlook Data Source**](#microsoft-outlook-data-source) - Native MS Graph integration for reading and sending Outlook emails\
> 📧 [**Send Notification Action**](#send-notification-action) - Send emails and reply to received emails directly from processes\
> 🔌 [**Integration Designer Improvements**](#integration-designer-improvements) - Query parameter encoding, config param autocomplete\
> 🔑 [**Security Details in Workflows**](#security-details-in-workflows) - Access user security details in workflow scripts\
> 🔐 [**File Encrypt and Decrypt**](#file-encrypt-and-decrypt) - Encrypt and decrypt files in the Documents Plugin
>
> ### **Microsoft Outlook data source**
>
> > [card] Microsoft Outlook data source
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces a new **Microsoft Outlook** data source type that connects to Outlook mailboxes via the Microsoft Graph API. Unlike Email Trigger (IMAP) and Email Sender (SMTP), this provides a unified data source for both reading and sending emails through native Outlook integration with Azure AD authentication.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> > > >
> > > > See the complete Microsoft Outlook data source documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified read & send
> > > >
> > > > Single data source supports Read Emails, Send Emails, or Read & Send Emails scopes
> > >
> > > > [card] Azure AD authentication
> > > >
> > > > Service account authentication with Tenant ID, Client ID, and Client Secret
> > >
> > > > [card] Email monitoring
> > > >
> > > > Monitor Outlook mailboxes and trigger processes automatically when emails arrive
> > >
> > > > [card] Send & reply
> > > >
> > > > Send new emails or reply to received emails with conversation thread support
> > >
> > > > [card] Attachment validations
> > > >
> > > > Configure allowed file types, max file size, and max file count for incoming emails
> > >
> > > > [card] Test connection
> > > >
> > > > Validate Azure AD credentials and MS Graph permissions before saving
> >
> > > [tab] Configuration
> > >
> > > **Azure AD Authentication:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Tenant ID | Azure AD tenant ID |
> > > | Client ID | Azure AD application (client) ID |
> > > | Client Secret | Azure AD client secret |
> > >
> > > **Scope Options:**
> > >
> > > | Scope | MS Graph Permissions Required |
> > > | - | - |
> > > | Read Emails | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
> > > | Send Emails | `Mail.Send` or `Mail.ReadWrite` |
> > > | Read & Send Emails | One read + one send permission |
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Send Notification action**
>
> > [card] Send Notification action
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces the Send Notification action — a new action type that sends emails directly from process nodes through SMTP, without routing through Kafka. Combined with the new Email Sender data source type, it enables processes to send new emails or reply to emails that triggered the process via Email Trigger.
> > >
> > > > [!NOTE]
> > > >
> > > > Existing notification templates configured for Kafka-based sending continue to work without modification.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> > > >
> > > > See the complete Send Notification action documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Email Sender data source
> > > >
> > > > New SMTP data source type in Integration Designer with SSL/TLS smart port defaults
> > >
> > > > [card] Reply to emails
> > > >
> > > > Reply to emails that triggered the process, maintaining conversation threads
> > >
> > > > [card] Send new emails
> > > >
> > > > Send new outbound emails to specified recipients with CC/BCC support
> > >
> > > > [card] Notification template updates
> > > >
> > > > New Email Server and Email Sender fields for direct SMTP delivery
> > >
> > > > [card] Attachments
> > > >
> > > > Attach files using static paths or process variable keys
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing Kafka-based notification templates continue to work unchanged
> >
> > > [tab] Configuration
> > >
> > > **Email Sender Data Source (new):**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | SMTP (only option) |
> > > | Server Host | SMTP server hostname |
> > > | SSL/TLS | Enable secure connection (default: on) |
> > > | Port | `587` (SSL/TLS on) or `465` (SSL/TLS off) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > >
> > > **Send Notification Action:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Notification Template | Select a template with Predefined Email Connection |
> > > | Reply to received emails | Toggle on to reply to the email that triggered the process |
> > > | Reply to Email Header | Process variable with original email headers (reply mode) |
> > > | Receivers | Recipient email addresses or process variables |
> > > | CC/BCC Receivers | Optional CC and BCC recipients |
> > > | Language | Process variable key for template language |
> > > | Attachments | File path or process variable key |
> > > | Template Data | JSON key-value pairs for dynamic template content |
> > >
> > > > [!TIP]
> > > >
> > > > Available on Send Message Task, Task, and User Task nodes.
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Integration Designer improvements**
>
> > [card] Integration Designer improvements
> >
> > FlowX.AI 5.5.0 adds URL encoding options for REST endpoint query parameters, improved error handling for invalid REST responses, and configuration parameter autocomplete in data source forms.
> >
> > > [card] Query parameter encoding
> > >
> > > Configure whether query parameter values are URL-encoded automatically or sent as-is (for pre-encoded values)
> >
> > > [card] REST Content-Type handling
> > >
> > > Improved error handling when REST endpoints return responses with unexpected Content-Type headers
> >
> > > [card] Config param autocomplete
> > >
> > > Type `$` in data source configuration fields to autocomplete configuration parameters or create new ones inline
> >
> > > [!NOTE]
> > >
> > > See [Integration Designer - Query parameters](/5.1/docs/platform-deep-dive/integrations/integration-designer#query-parameters) for details.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Security details in workflows**
>
> > [card] Security details in workflows
> >
> > Workflow scripts can now access `additionalData.securityDetails` to retrieve the current user's identity. This works when a workflow is started from a **Chat component**, a **UI Flow**, or a **manual run**. Sub-workflows inherit security details from their parent.
> >
> > Unlike processes, where security details are grouped by swimlane and role, workflows use a simplified flat structure:
> >
> > ```json theme={"dark"}
> > {
> >   "securityDetails": {
> >     "username": "user@email.com",
> >     "identifier": "keycloak-subject-id",
> >     "details": {
> >       "firstName": "John",
> >       "lastName": "Snow",
> >       "email": "user@email.com"
> >     }
> >   }
> > }
> > ```
> >
> > > [!NOTE]
> > >
> > > See [Extracting additional data in business rules](/5.1/docs/building-blocks/actions/business-rule-action/extracting-additional-data) for full details and code examples for both processes and workflows.
> >
> > New FeatureAll Deployments
>
> ***
>
> ### **File encrypt and decrypt**
>
> > [card] [File encrypt and decrypt](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files)
> >
> > FlowX.AI 5.5.0 adds new file encryption and decryption actions to the Documents Plugin, enabling processes to encrypt files before storage and decrypt them for authorized access.
> >
> > > [card] File encryption
> > >
> > > Encrypt files using configurable encryption algorithms before storage
> >
> > > [card] File decryption
> > >
> > > Decrypt files for authorized access within process flows
> >
> > InfrastructureAll Deployments
>
> ***

> [tab] Platform & Management
>
> User management, workspace configuration, rendering, and platform improvements.
>
> 🔐 [**Container App Authentication**](#container-app-authentication) - Authentication flow and landing page improvements\
> 🔑 [**Password Policy Updates**](#password-policy-updates) - Updated password complexity requirements\
> 🚫 [**User status DISABLED**](#user-status-disabled) - New DISABLED status for user accounts\
> 📧 [**Resend User Invitation**](#resend-user-invitation) - Resend invitations for pending users\
> 🏷️ [**Workspace Environment Type**](#workspace-environment-type) - Sandbox, Staging, and Production labels for workspaces\
> 🏢 [**Organization ID Propagation**](#organization-id-propagation) - Enhanced multi-tenant isolation\
> ⚡ [**Rendering Runtime UX**](#rendering-runtime-ux) - Runtime UX improvements for rendering\
> 🔍 [**Process Variables Compare**](#process-variables-compare) - Monaco diff editor for process variable values\
> 📧 [**Failed Email Trigger Details Page**](#failed-email-trigger-details-page) - Dedicated details page for failed email triggers\
> 📐 [**Data Model Sidepanel**](#data-model-sidepanel) - Redesigned attribute settings, inline add, and path copy
>
> ### **Container app authentication**
>
> > [card] [Container app authentication](/5.9/docs/saas/container-app-authentication)
> >
> > > [tab] Overview
> > >
> > > Enhanced authentication flow and landing page for generic container applications. Configure authentication providers, customize login pages, and manage user sessions with improved security and user experience.
> >
> > > [tab] Key Features
> > >
> > > > [card] Authentication providers
> > > >
> > > > Support for multiple authentication providers
> > >
> > > > [card] Custom landing page
> > > >
> > > > Customize the landing page for unauthenticated users
> > >
> > > > [card] Session management
> > > >
> > > > Improved session handling and token refresh
> > >
> > > > [card] SSO integration
> > > >
> > > > Seamless single sign-on integration
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Password policy updates**
>
> > [card] [Password policy updates](/5.1/setup-guides/access-management/configuring-an-iam-solution#password-policy)
> >
> > FlowX.AI 5.5.0 updates the password policy with stricter complexity requirements for improved security.
> >
> > **New requirements:**
> >
> > | Rule | Value |
> > | - | - |
> > | Minimum length | 8 characters |
> > | Maximum length | 64 characters |
> > | Complexity | Must include uppercase, lowercase, number, and special character |
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **User status DISABLED**
>
> > [card] [User status DISABLED](/5.9/docs/saas/inviting-users#user-statuses)
> >
> > FlowX.AI 5.5.0 introduces a new **DISABLED** user status. Administrators can now enable or disable user accounts through the **Enable** and **Disable** actions in the user management menu, providing better control over user access without deleting accounts.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Resend user invitation**
>
> > [card] [Resend user invitation](/5.9/docs/saas/inviting-users#resending-invitations)
> >
> > FlowX.AI 5.5.0 adds the ability to resend invitations for users with a **Pending** status, ensuring users who missed or lost their initial invitation can still complete onboarding.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Workspace environment type**
>
> > [card] [Workspace environment type](/5.1/docs/projects/workspaces#workspace-environment-type)
> >
> > FlowX.AI 5.5.0 adds an **Environment Type** dropdown to workspace configuration, allowing administrators to label workspaces as **Sandbox**, **Staging**, or **Production**. This provides clearer context when working across multiple environments.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Organization ID propagation**
>
> > [card] Organization ID Propagation
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 enhances multi-tenant isolation by propagating organization ID across more runtime contexts. This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
> >
> > > [tab] Key Changes
> > >
> > > > [card] Scheduler execution
> > > >
> > > > Organization ID added to scheduled job context
> > >
> > > > [card] Event listeners
> > > >
> > > > Organization ID propagated to event handlers
> > >
> > > > [card] Process instances
> > > >
> > > > Organization ID captured from initiator
> > >
> > > > [card] Audit trail
> > > >
> > > > Enhanced audit logging with organization context
> >
> > InfrastructureSaaS
>
> ***
>
> ### **Rendering runtime UX**
>
> > [card] Rendering runtime UX
> >
> > FlowX.AI 5.5.0 includes various rendering runtime UX improvements for better performance and user experience.
> >
> > > [card] Loading states
> > >
> > > Improved loading state indicators and skeleton screens
> >
> > > [card] Transition animations
> > >
> > > Smoother transitions between screens and states
> >
> > > [card] Error boundaries
> > >
> > > Better error handling with graceful degradation
> >
> > > [card] Performance
> > >
> > > Optimized rendering performance for complex UIs
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process variables compare**
>
> > [card] [Process variables compare](/5.9/docs/projects/runtime/active-process/update-process-variables#compare-view)
> >
> > FlowX.AI 5.5.0 introduces a Monaco diff editor for comparing process variable values, making it easier to identify changes between versions or states.
> >
> > > [card] Diff editor
> > >
> > > Side-by-side comparison of process variable values using Monaco diff editor
> >
> > > [card] Version comparison
> > >
> > > Compare variable values across different process versions
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Failed email trigger details page**
>
> > [card] [Failed email trigger details page](/5.9/docs/platform-deep-dive/integrations/email-trigger#failed-trigger-details-page)
> >
> > FlowX.AI 5.5.0 adds a dedicated details page for failed email triggers, providing better visibility into email processing failures and enabling faster troubleshooting.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Data Model sidepanel**
>
> > [card] Data Model sidepanel
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 redesigns the Data Model editing experience with a new attribute settings side panel, inline add-attribute buttons, and attribute path display. These improvements make it faster to create, configure, and reference data model attributes without switching between menus.
> > >
> > > > [card] [Process Data Model](/5.1/docs/building-blocks/process/data-model#data-model-interface)
> > > >
> > > > See the updated Process Data Model documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Attribute settings side panel
> > > >
> > > > Select any attribute to open a settings panel with type, validations, sensitive data, and reporting options
> > >
> > > > [card] Inline add attribute
> > > >
> > > > Add attributes directly on each data type — button shows on hover after the first attribute
> > >
> > > > [card] Attribute path copy
> > > >
> > > > View and copy the full key path for any attribute for use in business rules and UI bindings
> > >
> > > > [card] Selection highlights
> > > >
> > > > Selecting a data type or connector highlights its location on the canvas
> > >
> > > > [card] Default minimized panel
> > > >
> > > > The Data Types panel starts minimized by default for a cleaner canvas view
> > >
> > > > [card] Confirmation toasts
> > > >
> > > > Success notifications when adding new data types
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### Additional improvements
>
> * **Workflow logs milliseconds** — Workflow execution logs now display timestamps with millisecond precision
> * **Single select in table edit** — SDK enhancement for single-select dropdowns within editable table cells. See [Table component](/5.1/docs/building-blocks/ui-designer/ui-component-types/table#editable-rows)
> * **UI Flows action name optional** — Action names in UI Flows are now optional, reducing configuration overhead
> * **Data mappers editable JSON testing** — Improved JSON testing experience in data mappers with editable input fields
> * **Solutions page load optimization** — Solutions page now loads only projects, improving performance for container apps
> * **Security patches** — General security improvements across platform services

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.5.0](./deployment-guidelines-v5.5).
>
> ### Compatibility
>
> > [!WARNING]
> >
> > **Breaking change:** The default `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 services. Opaque-token introspection has been removed. See the [Deployment Guidelines](./deployment-guidelines-v5.5#breaking-changes) for migration steps.
>
> > [card] Upgrade path
> >
> > Upgrade from v5.4.0 — requires authentication mechanism migration (`SECURITY_TYPE` change)
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.5


# Deployment guidelines v5.6.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/deployment-guidelines-v5.6

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.77.0** | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 |
| **admin** | **10.66.0** | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 |
| **designer** | **10.127.3** | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **cms-core** | **10.43.0** | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 |
| **scheduler-core** | **10.31.0** | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 |
| **events-gateway** | **10.33.1** | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 |
| **notification-plugin** | **10.42.1** | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 |
| **document-plugin** | **10.46.0** | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 |
| **task-management-plugin** | **10.41.1** | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 |
| **data-search** | **10.30.1** | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 |
| **audit-core** | **10.40.0** | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 |
| **advancing-controller** | **10.33.1** | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 |
| **integration-designer** | **10.84.0** | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 |
| **application-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **runtime-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **data-sync** | **10.38.0** | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 |
| **authorization-system** | **10.51.0** | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 |
| **nosql-db-runner** | **10.34.0** | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 |
| **email-gateway** | **10.32.1** | 10.24.0 | 10.9.0 | - | - | - |
| **organization-manager** | **10.26.1** | 10.19.2 | - | - | - | - |
| **webhook-gateway** | **10.1.1** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **iOS renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 |
| **Android renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 |

### Plugins

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.2.3** | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 |
| **di-platform** | **10.3.0** | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 |
| **ai-platform-ai-developer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-connected-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-knowledge-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agents** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-conversations** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-models** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-tenants** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-planner** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-analyst** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-designer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agent-builder** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-binaries** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **knowledgebase** | **10.6.0** | TBD | - | - | - | - |
| **knowledgebase-rag** | **10.6.0** | 10.2.0 | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.0** | 10.2.0 | - | - | - | - |
| **mcp** | **10.6.0** | 10.2.0 | - | - | - | - |
| **doc-converter** | **10.2.2** | - | - | - | - | - |
| **doc-parser** | **10.5.1** | - | - | - | - | - |

> [!NOTE]
>
> **New in 5.6.0:** `webhook-gateway` is a new microservice for processing incoming webhooks. It handles webhook event ingestion and routing to process instances.

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.6.0 | Keycloak | 26+ |
| 5.6.0 | Kafka | 3.8 - 3.9 |
| 5.6.0 | PostgreSQL | 16 - 17 |
| 5.6.0 | Oracle Database | 21c, 23ai |
| 5.6.0 | MongoDB | 7 - 8 |
| 5.6.0 | Redis | 7.4 - 8.0 |
| 5.6.0 | Angular (Web SDK) | 20 |
| 5.6.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.6.0

### Key features and updates

> [card] Chat Driven Workflows
>
> Multi-turn AI conversations with session memory and intent classification

> [card] Incoming Webhooks
>
> Trigger processes from external HTTP POST requests via the new webhook-gateway service

> [card] Web Page Extractor
>
> Collect readable content from web page URLs with crawling and link following

> [card] Proxy Server Connections
>
> Route integration traffic through HTTP/HTTPS proxy servers

> [card] UI Flow Route Management
>
> Query parameters, route maps, and breadcrumb navigation for UI Flows

> [card] MCP Authentication
>
> BEARER and BASIC auth for MCP server connections

## Upgrading from v5.5.0

### Breaking changes

#### WorkspaceCreatedEvent ownership change

> [!WARNING]
>
> The `WorkspaceCreatedEvent` Kafka topic ownership has moved from `authorization-system` to `organization-manager`.

**What changed:**

* `organization-manager` now produces `WorkspaceCreatedEvent` messages
* `authorization-system` no longer produces these events
* Update your Kafka topic ACLs if you manage topic-level permissions

***

#### gRPC thread pool configuration

> [!WARNING]
>
> The default gRPC client thread pool sizes in AI Platform have been updated. Review your deployment configuration if you have custom thread pool settings.

***

### New environment variables

#### Integration Designer

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_WEBHOOKS_BASE_URL` | Base URL for webhook-gateway service communication | `http://webhook-gateway:80` | integration-designer |
| `FLOWX_WEB_CRAWLER_BASE_URL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80` | integration-designer |

#### NoSQL DB Runner

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100` | nosql-db-runner |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL` | Time-to-live for cached external MongoDB connections | `1d` | nosql-db-runner |

#### Process Engine

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts for failed operations | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Base delay between retries (ms) | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum delay between retries (ms) | `200` | process-engine |

#### Authorization System

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD` | Initial password for default realm admin user | *(none)* | authorization-system |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY` | Force password change on first login | `true` | authorization-system |

#### Application Manager

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_RESOURCE_ID_FIELD` | Resource ID field for proxy connection merge | `resourceId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_ID_FIELDS` | Flatten map ID fields for proxy connection merge | `resourceId, name` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection flatten map | `authorization.configuration` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_COMPARE_REMOVED_JSON_PATHS` | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_CONFLICT_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection conflict detection | `resourceId, resourceDefinitionId` | application-manager |

#### Data Search

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | data-search |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | data-search |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | data-search |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | data-search |

#### Email Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | email-gateway |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | email-gateway |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | email-gateway |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | email-gateway |

> [!NOTE]
>
> The SpiceDB and CAS client variables for `data-search` and `email-gateway` are required for authorization integration. These services now use the same SpiceDB-based authorization as other platform services.

#### Webhook Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for webhook registrations database | `jdbc:postgresql://postgresql:5432/webhook_gateway` | webhook-gateway |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` | webhook-gateway |
| `SPRING_DATASOURCE_PASSWORD` | Database password | *(required)* | webhook-gateway |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | OAuth2/OIDC server base URL | — | webhook-gateway |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | — | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account client ID | `flowx-webhook-gateway-sa` | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account client secret | *(required)* | webhook-gateway |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Kafka topic for process start events | `ai.flowx.core.trigger.start-for-event.process.v1` | webhook-gateway |

> [!NOTE]
>
> `webhook-gateway` is a **new microservice** in 5.6.0. It requires its own PostgreSQL database (`webhook_gateway`), Kafka access, Keycloak service account (`flowx-webhook-gateway-sa`), and SpiceDB connectivity.

***

### New Kafka topics

#### Document Plugin

New topic for UI Flow session document persistence.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway | Inbound |
| `ai.flowx.eventsgateway.receive.document.v1` | Document events sent to events-gateway for SSE delivery | Outbound |

#### Webhook Gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Triggers process starts from incoming webhook events | Outbound |

> [!NOTE]
>
> The Webhook Gateway is a **producer-only** service — it receives HTTP webhook requests and publishes process start events to Kafka. It does not consume from any Kafka topics.

#### UI flow session variable updates

New topic for propagating document upload results and workflow completion results to the process-engine, which updates UI flow session variables.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | UI flow session variable updates after document upload or workflow completion | Inbound (process-engine) / Outbound (document-plugin, integration-designer) |

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | process-engine |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Consumer group ID for UI flow updates | `ui-flow-update` | process-engine |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of consumer threads for UI flow updates | `6` | process-engine |

***

### Compatibility

* **SpiceDB**: Now required for `data-search` and `email-gateway` in addition to existing services
* **Renderer Updates**: Web and mobile SDKs include route management, start parameters, enum label display, and chat enhancements
* **Database**: The `start_params` column on `ui_flow_session` table has been renamed to `variables` (auto-migrated via Liquibase). The column now stores all session variables, including start parameters and updates from document uploads and workflow completions

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026

Conversational AI with memory and intent routing, incoming webhooks, proxy connections, unmanaged MongoDB, UI Flow session variables, chat history, and 28 bug fixes.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html)

FlowX.AI 5.6.0 brings **conversational AI** to your apps. Build multi-turn chat experiences where agents remember context, classify user intent, and navigate users to the right screen — all within a single workflow. On the integration side, **incoming webhooks** let external systems start processes via HTTP, **proxy connections** route traffic through intermediary servers, and **unmanaged MongoDB** connects FlowX to your existing database infrastructure. The UI layer gains **session variables**, **route management**, **chat history**, and **suggested prompts** for richer end-user experiences.

> [card] [For AI builders](#conversational-workflows)
>
> Chat Driven workflows, session memory, intent routing, and context retrieval

> [card] [For integrators](#incoming-webhooks)
>
> Incoming webhooks, proxy connections, unmanaged MongoDB, and base64 certificates

> [card] [For UI developers](#ui-flow-session-variables)
>
> Session variables, route management, chat history, suggested prompts, and new UI events

### What changed since 5.5.0

| 5.5.0 | 5.6.0 |
| - | - |
| Output Focused workflows only | + **Chat Driven** workflows with multi-turn memory |
| No event-driven process starts from external systems | **Incoming webhooks** with API key auth |
| FlowX-managed MongoDB only | + **Unmanaged MongoDB** — bring your own database |
| No conversation persistence | **Chat History** — browse and resume past sessions |
| Static chat empty state | **Suggested Prompts** — guide users with one-click starters |
| Certificate file paths only | **Base64 certificates** — paste content directly, no file mounts |
| No cross-page data in UI Flows | **Session variables** — persist data across pages and workflows |

***

**What's new?**

> [tab] AI Platform
>
> Build complete conversational AI pipelines — from understanding what the user wants, to retrieving the right context, to navigating them to the right screen.
>
> 💬 [**Conversational Workflows**](#conversational-workflows) - New Chat Driven workflow type for multi-turn conversations\
> 🧠 [**Memory Capabilities**](#memory-capabilities) - Automatic session memory with summarization across turns\
> 🎯 [**Intent Classification node**](#intent-classification-node) - Classify user messages and route to the right branch in one step\
> 🧭 [**Navigate in UI Flow**](#navigate-in-ui-flow) - Let the AI open forms and screens with contextual data\
> 🔍 [**Context Retrieval node**](#context-retrieval-node) - RAG search against Knowledge Bases without calling an LLM\
> 📄 [**Extract Data from File**](#extract-data-from-file) - Three extraction methods, image support, and signature detection\
> 🌐 [**Web Page Extractor**](#web-page-extractor) - Crawl web pages and extract readable content for AI processing
>
> See also: [Chat History](#chat-history), [Suggested Prompts](#chat-suggested-prompts), and [Markdown in chat](#markdown-in-chat-messages) in the **UI & Designer** tab.
>
> ### **Conversational Workflows**
>
> > [card] Conversational Workflows
> >
> > > [tab] Overview
> > >
> > > Chat Driven workflows are a specialized workflow type for multi-turn chat interactions. Unlike Output Focused workflows that process structured input/output, Chat Driven workflows manage ongoing dialogue — handling message exchange, session memory, and response routing through a dedicated Start node layout (Chat Session ID + User Message) and Custom Agent nodes with direct chat reply capability.
> > >
> > > ![Conversational workflow with Custom Agent configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_config.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> > > >
> > > > See the complete Conversational Workflows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multi-turn conversations
> > > >
> > > > Support for back-and-forth conversations with persistent context
> > >
> > > > [card] Intent routing
> > > >
> > > > Automatically classify user messages and route to appropriate workflow branches
> > >
> > > > [card] Session memory
> > > >
> > > > Built-in session memory with automatic summarization across conversation turns
> > >
> > > > [card] Chat UI components
> > > >
> > > > Dedicated chat component with error handling and shared state management
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Memory Capabilities**
>
> > [card] Memory Capabilities
> >
> > > [tab] Overview
> > >
> > > Conversational workflows include built-in session memory that automatically persists and retrieves conversation history. On each message, the system retrieves the last 3 turns of raw messages plus a summary of earlier exchanges, injecting them into the AI node's system prompt for context-aware responses.
> > >
> > > ![Memory tab showing conversation summary and history](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> > > >
> > > > See the complete Memory Capabilities documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic retrieval
> > > >
> > > > Last 3 turns + summary of earlier exchanges retrieved on each message via sessionId
> > >
> > > > [card] Smart summarization
> > > >
> > > > Older conversation history is automatically summarized to fit within context limits
> > >
> > > > [card] Per-node control
> > > >
> > > > Turn on memory per Custom Agent node with the **Use memory** toggle
> > >
> > > > [card] Memory tab in console
> > > >
> > > > View retrieved memory (raw turns + summary) in the workflow console log
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Intent Classification node**
>
> > [card] Intent Classification Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that combines AI-powered message classification with workflow branching in a single step. Define up to 10 intents with natural language descriptions, and the node classifies user messages and routes to the matching branch automatically — replacing the previous TEXT\_UNDERSTANDING + Condition two-node pattern.
> > >
> > > ![Intent Classification node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intent_classification_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> > > >
> > > > See the complete Intent Classification documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] AI + routing in one node
> > > >
> > > > Combines LLM classification and conditional branching — no separate Condition node needed
> > >
> > > > [card] Natural language conditions
> > > >
> > > > Define intents as plain-text descriptions instead of code expressions
> > >
> > > > [card] Conversation memory
> > > >
> > > > Optionally use past conversation context for more accurate classification
> > >
> > > > [card] Built-in fallback
> > > >
> > > > Automatic "If No Intent Matches" branch handles unrecognized inputs
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Navigate in UI Flow**
>
> > [card] Navigate in UI Flow
> >
> > > [tab] Overview
> > >
> > > A new workflow node exclusive to **Chat Driven** (conversational) workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — for example, the AI says *"Let me open your account details"* and the user sees a pre-filled form with data from the conversation.
> > >
> > > ![Navigate in UI Flow node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node)
> > > >
> > > > See the Navigate in UI Flow section in Conversational Workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Conversational context
> > > >
> > > > Navigate users to UI screens directly from a Chat Driven workflow conversation
> > >
> > > > [card] Dynamic parameters
> > > >
> > > > Pass workflow data to the destination screen using `${expression}` syntax
> > >
> > > > [card] Destination picker
> > > >
> > > > Select from the UI Flow's navigation tree with auto-populated query parameters
> > >
> > > > [card] Chat Driven only
> > > >
> > > > Available exclusively in the Actions category of conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval node**
>
> > [card] Context Retrieval Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that performs RAG (Retrieval-Augmented Generation) searches against Knowledge Bases without calling an LLM. Returns raw chunks with relevance scores and metadata, giving you full control over downstream processing. Supports hybrid, semantic, and keyword search with configurable re-ranking and metadata filters.
> > >
> > > Use Context Retrieval when you need to inspect, filter, or transform chunks before passing them to an LLM — for example, checking relevance scores before generating a response. For all-in-one RAG, use a Custom Agent node with a Knowledge Base attached instead.
> > >
> > > ![Context Retrieval node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the complete Context Retrieval documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] No LLM required
> > > >
> > > > Retrieves chunks directly — no AI generation step, lower latency and cost
> > >
> > > > [card] Multiple search types
> > > >
> > > > Hybrid, semantic, or keyword search with configurable relevance thresholds
> > >
> > > > [card] Metadata filters
> > > >
> > > > Filter chunks by user-defined metadata for scoped retrieval
> > >
> > > > [card] Re-ranking
> > > >
> > > > Optional re-ranking for improved result ordering
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > The workflow node formerly known as "Extract Text from Document" has been renamed to **Extract Data from File** and gained three new configurable settings: **Extraction Method** (LLM Model, OCR Engine, or Text Parsing), **Image Extraction** (Image Description or Image Contents), and **Detect Signatures**. The node now also accepts image files (JPG, PNG, TIFF) in addition to documents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Three extraction methods
> > > >
> > > > Choose between LLM Model (AI vision), OCR Engine (scanned docs), or Text Parsing (digital PDFs) per use case
> > >
> > > > [card] Image support
> > > >
> > > > Process JPG, PNG, and TIFF files alongside PDF, DOCX, XLSX, and PPTX
> > >
> > > > [card] Signature detection
> > > >
> > > > Identify signature areas within documents when using LLM or OCR extraction
> > >
> > > > [card] Moved to Tools category
> > > >
> > > > The node is now in the **Tools** category in the workflow node palette
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor**
>
> > [card] Web Page Extractor
> >
> > > [tab] Overview
> > >
> > > A new workflow node in the **Tools** category that collects readable content from web page URLs. Crawl documentation sites to build a Knowledge Base, scrape product pages for competitive analysis, or extract terms and conditions for compliance review. Supports static URL lists or dynamic URL generation, configurable crawling depth with link following, PDF extraction from linked documents, and adjustable scrape speed presets.
> > >
> > > ![Web Page Extractor node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> > > >
> > > > See the complete Web Page Extractor documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Static or dynamic URLs
> > > >
> > > > Provide a fixed list of up to 20 URLs or generate them dynamically from workflow data
> > >
> > > > [card] Link following
> > > >
> > > > Follow links on pages up to a configurable depth (0–10 levels)
> > >
> > > > [card] PDF processing
> > > >
> > > > Extract content from PDF files linked on crawled pages
> > >
> > > > [card] Speed presets
> > > >
> > > > Choose Slow, Moderate, Fast, or Custom with manual rate limit and concurrency
> >
> > All Deployments

> [tab] Integrations
>
> Connect FlowX to more systems — trigger processes from external events, route traffic through proxies, and query your own MongoDB databases.
>
> 🔗 [**Incoming Webhooks**](#incoming-webhooks) - Trigger processes from external HTTP POST requests\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Route integration traffic through proxy servers\
> 🗄️ [**Unmanaged MongoDB Datasource**](#unmanaged-mongodb-datasource) - Connect to externally managed MongoDB instances\
> 📧 [**Email Trigger Enhancements**](#email-trigger-enhancements) - Resource management, reply-to, and mock email testing\
> 🔐 [**MCP Authentication**](#mcp-authentication) - BEARER and BASIC auth support for MCP server connections\
> 📜 [**Base64 Certificate Support**](#base64-certificate-support) - Provide certificates as base64-encoded strings instead of file paths\
> 📊 [**CSV/Excel to JSON Conversion**](#csv/excel-to-json-conversion) - Download CSV and Excel files as structured JSON on the fly
>
> ### **Incoming Webhooks**
>
> > [card] Incoming Webhooks
> >
> > > [tab] Overview
> > >
> > > A new data source type and microservice (`webhook-gateway`) that allows external systems to trigger FlowX processes via HTTP POST requests. Create a Webhook data source in Integration Designer, connect it to a Message Start Event in your process, and FlowX generates a unique URL with API key authentication. When external systems POST to this URL, a process instance starts automatically with the webhook payload and headers.
> > >
> > > ![Active webhook trigger in Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)
> > >
> > > > [!NOTE]
> > > >
> > > > Requires deploying the new `webhook-gateway` microservice. See [Deployment Guidelines](./deployment-guidelines-v5.6) for configuration.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> > > >
> > > > See the complete Incoming Webhooks documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] API key authentication
> > > >
> > > > Each webhook gets a unique, cryptographically secure API key for authentication
> > >
> > > > [card] JSON payload forwarding
> > > >
> > > > Webhook body and headers are forwarded to the process instance as variables
> > >
> > > > [card] Manage Triggers integration
> > > >
> > > > Activate, deactivate, and monitor webhooks from the Manage Triggers UI
> > >
> > > > [card] API key regeneration
> > > >
> > > > Regenerate API keys without recreating the webhook configuration
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Proxy Server Connections**
>
> > [card] Proxy Server Connections
> >
> > > [tab] Overview
> > >
> > > Create reusable proxy connections in Integration Designer and attach them to RESTful System data sources. Route outbound API traffic through HTTP or HTTPS proxy servers for environments that require intermediary routing for security or compliance.
> > >
> > > ![Proxy Connection configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> > > >
> > > > See the complete Proxy Connections documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] HTTP and HTTPS proxies
> > > >
> > > > Configure HTTP or HTTPS proxy servers with optional basic authentication
> > >
> > > > [card] Reusable connections
> > > >
> > > > Create a proxy once and attach it to multiple RESTful System data sources
> > >
> > > > [card] Test connectivity
> > > >
> > > > Validate proxy configuration before saving with the built-in test function
> > >
> > > > [card] Config parameter support
> > > >
> > > > Use `${param}` syntax in host and port fields for environment-specific values
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Unmanaged MongoDB Datasource**
>
> > [card] Unmanaged MongoDB Datasource
> >
> > > [tab] Overview
> > >
> > > Connect to externally managed MongoDB instances as a data source in FlowX. Unlike the built-in FlowX Database (which provisions and manages MongoDB collections automatically), Unmanaged MongoDB connects to databases and collections you control — with the same CRUD operations, connection discovery, and configurable connection pooling. Requires MongoDB 6.0 or later.
> > >
> > > ![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> > > >
> > > > See the complete Unmanaged MongoDB documentation.
> >
> > All Deployments
>
> ***
>
> ### **Email Trigger Enhancements**
>
> > [card] Email Trigger Enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.6.0 enhances the Email Trigger with resource management capabilities, reply-to-email support, process instance tracking for email-triggered processes, and mock email testing for development.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Resource management
> > > >
> > > > Manage email trigger resources with proper lifecycle controls
> > >
> > > > [card] Reply-to-email
> > > >
> > > > Support for reply-to patterns in email-triggered workflows
> > >
> > > > [card] Process instances
> > > >
> > > > View and track process instances created from email triggers
> > >
> > > > [card] Mock email testing
> > > >
> > > > Test email-triggered processes with mock email content during development
> >
> > All Deployments
>
> ***
>
> ### **MCP Authentication**
>
> > [card] MCP Authentication
> >
> > > [tab] Overview
> > >
> > > MCP server connections now support **BEARER** and **BASIC** authentication methods. Configure auth credentials when adding an MCP data source to connect to secured MCP servers.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source)
> > > >
> > > > See the Adding MCP Data Source documentation.
> >
> > All Deployments
>
> ***
>
> ### **Base64 Certificate Support**
>
> > [card] Base64 Certificate Support
> >
> > > [tab] Overview
> > >
> > > RESTful system data sources now support providing keystore and truststore content as **base64-encoded strings** instead of file paths. A new "Certificate type" selector lets you choose between Base64 (default for new configurations) and Path (existing behavior). Additionally, keystore and truststore passwords now support `${configParam}` placeholder syntax for dynamic per-environment resolution.
> > >
> > > ![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#certificates)
> > > >
> > > > See the Integration Designer certificates documentation.
> >
> > All Deployments
>
> ***
>
> ### **CSV/Excel to JSON Conversion**
>
> > [card] CSV/Excel to JSON Conversion
> >
> > > [tab] Overview
> > >
> > > Download CSV, XLS, or XLSX files as structured JSON directly from the file download endpoints. The conversion happens on the fly using the `Accept: application/json` header — no new files are created in storage. Supports two output formats: an array of objects (one per row) or a columnar structure.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats#csv/excel-to-json-conversion)
> > > >
> > > > See the Document Conversion documentation.
> >
> > All Deployments

> [tab] UI & Designer
>
> Richer end-user experiences with session state, chat history, and navigation — plus Designer productivity improvements.
>
> 🗺️ [**UI Flow Route Management**](#ui-flow-route-management) - Configure routes, query parameters, and navigation in UI Flows\
> ▶️ [**UI Flow Start Parameters**](#ui-flow-start-parameters) - Pass parameters when starting UI Flows\
> 💾 [**UI Flow Session Variables**](#ui-flow-session-variables) - Persist data across pages from workflows and file uploads\
> 📋 [**Chat History**](#chat-history) - Browse and resume past chat conversations\
> 💡 [**Chat Suggested Prompts**](#chat-suggested-prompts) - Pre-configured prompt suggestions in chat empty state\
> 🖱️ [**onClick UI events**](#onclick-ui-events) - Client-side data updates on Button and Collection Prototype clicks\
> ✨ [**Monaco Editor Autocomplete**](#monaco-editor-autocomplete) - Autocomplete from config params in code editors\
> 📊 [**KB query results in workflow console**](#kb-query-results-in-workflow-console) - View retrieved chunks and relevance scores during workflow runs\
> 📎 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Upload multiple files simultaneously\
> ❌ [**DISMISS UI action**](#dismiss-ui-action) - Dismiss modals automatically after Start Workflow completes\
> 🎨 [**Process Variables UX**](#process-variables-ux-improvements) - UI/UX improvements for updating process variables\
> 🏷️ [**Enum label display**](#enum-label-display) - Show enum labels instead of codes in text components\
> 📬 [**Notification template usages**](#notification-template-usages) - See where notification templates are used\
> 📐 [**Side Panel in Data Model**](#side-panel-in-data-model) - Improved data model navigation with side panel\
> 👁️ [**On Display UI event**](#on-display-ui-event) - Re-trigger actions every time a screen becomes visible\
> 🪟 [**On Load event on Modal**](#on-load-event-on-modal) - Modal components now support On Load events\
> 🏗️ [**KB user-defined metadata**](#kb-user-defined-metadata) - Define custom metadata keys on Knowledge Base content sources\
> ⚙️ [**Config params in workflow conditions**](#config-params-in-workflow-conditions) - Use config params and user details in workflow Fork node expressions\
> 🎨 [**Branding settings grouping**](#branding-settings-grouping) - Reorganized branding settings page\
> ✍️ [**Markdown in chat messages**](#markdown-in-chat-messages) - Render formatted text, links, and lists in chat responses\
> 🔗 [**External Action dynamic URL**](#external-action-dynamic-url) - Use expressions in External Action URLs for dynamic navigation\
> 📬 [**Notification history**](#notification-history) - View sent notification details and search by process instance
>
> ### **UI Flow Route Management**
>
> > [card] UI Flow Route Management
> >
> > > [tab] Overview
> > >
> > > Define query parameters on root views (Pages, Modals), pass data between screens via URL query strings, and get automatic breadcrumb generation from the navigation graph. Navigate To actions support destination parameter mapping with `${expression}` syntax for dynamic values.
> > >
> > > ![Route parameters modal with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#route-management)
> > > >
> > > > See the Route Management section in UI Flows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Route parameters
> > > >
> > > > Define named query parameters on root views with default values and required flags
> > >
> > > > [card] Parameter passing
> > > >
> > > > Map data from process store to destination query parameters using JSON expressions
> > >
> > > > [card] Auto breadcrumbs
> > > >
> > > > Breadcrumbs auto-generate from the navigation graph with proper parameter handling
> > >
> > > > [card] Modal URL state
> > > >
> > > > Modals add `modalId` to URL — survives page reload and supports deep linking
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Start Parameters**
>
> > [card] UI Flow Start Parameters
> >
> > > [tab] Overview
> > >
> > > Pass initial data when launching a UI Flow. Define start parameters as a JSON object in the Designer's Run dialog, extract them from URL query strings in SaaS container apps, or send them in the API request body. Parameters are persisted on the session and available throughout the UI Flow lifecycle.
> > >
> > > ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#start-parameters)
> > > >
> > > > See the Start Parameters section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Session Variables**
>
> > [card] UI Flow Session Variables
> >
> > > [tab] Overview
> > >
> > > UI Flow sessions can now persist variables across all pages sharing the same session ID. Data from start parameters, workflow outputs, and file upload responses is automatically collected and merged into session variables. Reference them in component configurations using `${}` syntax. A new **Variables** tab in the Designer session console shows current values for debugging.
> > >
> > > ![Variables tab in UI Flow session console](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#session-variables)
> > > >
> > > > See the Session Variables section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **Chat History**
>
> > [card] Chat History
> >
> > > [tab] Overview
> > >
> > > Users can now browse and resume past chat conversations. Chat History displays a list of previous sessions grouped by time (Today, Yesterday, Previous 7 Days, Previous 30 Days, Older), with the ability to open any conversation and continue where they left off. Conversations are per-user with access control enforced.
> > >
> > > ![Chat History panel with conversation list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#chat-history)
> > > >
> > > > See the Chat History section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Chat Suggested Prompts**
>
> > [card] Chat Suggested Prompts
> >
> > > [tab] Overview
> > >
> > > The Chat component now supports pre-configured **Suggested Prompts** — pill buttons displayed below the welcome message in the chat empty state. Configure a title and up to 5 prompt options in the Designer. When a user clicks a suggestion, it is submitted as their message, starting the conversation immediately.
> > >
> > > ![Suggested Prompts in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#suggested-prompts)
> > > >
> > > > See the Suggested Prompts section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Monaco Editor Autocomplete**
>
> > [card] Monaco Editor Autocomplete
> >
> > > [tab] Overview
> > >
> > > Code editors in the Designer now provide autocomplete suggestions from your project's configuration parameters. This speeds up writing business rules and expressions that reference config params.
> > >
> > > > [card] [Documentation](/5.1/docs/projects/runtime/configuration-parameters-overrides)
> > > >
> > > > See the Configuration Parameters documentation.
> >
> > All Deployments
>
> ***
>
> ### **Process Variables UX improvements**
>
> > [card] Process Variables UX
> >
> > > [tab] Overview
> > >
> > > UI/UX improvements to the Update Process Variables experience, making it easier to view and edit runtime process data.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > > >
> > > > See the Update Process Variables documentation.
> >
> > All Deployments
>
> ***
>
> ### **onClick UI events**
>
> > [card] onClick UI events
> >
> > > [tab] Overview
> > >
> > > Buttons and Collection Prototypes now support **onClick** UI events — client-side JavaScript expressions that execute immediately when clicked, *before* any configured UI actions fire. Use them for instant local data updates without server roundtrips.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-events)
> > > >
> > > > See the UI Events documentation.
> >
> > All Deployments
>
> ***
>
> ### **KB query results in workflow console**
>
> > [card] KB Query Results
> >
> > > [tab] Overview
> > >
> > > The workflow run console now includes a **Knowledge Base** tab that displays retrieved chunks, relevance scores, content sources, and metadata when Custom Agent nodes query a knowledge base. This makes it easier to debug and tune RAG-powered workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows)
> > > >
> > > > See Using Knowledge Base in Workflows.
> >
> > All Deployments
>
> ***
>
> ### **Multi-file bulk upload**
>
> > [card] Multi-file Bulk Upload
> >
> > > [tab] Overview
> > >
> > > Upload multiple files simultaneously at runtime using the new [Multiple File Upload](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload) component. Supports drag-and-drop, batch selection, per-file validation, and progress tracking. Available in both process screens and UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **DISMISS UI action**
>
> > [card] DISMISS Action
> >
> > > [tab] Overview
> > >
> > > The Start Workflow UI action now includes a **Dismiss modal** checkbox. When enabled, the modal closes automatically after the workflow completes — removing the need for a separate close action.
> >
> > All Deployments
>
> ***
>
> ### **Enum label display**
>
> > [card] Enum Label Display
> >
> > > [tab] Overview
> > >
> > > Text components can now display the human-readable **label** of an enumeration value instead of the raw code. When a data key references an enumeration, the renderer resolves the selected code to its label at display time. Enumeration values are also prefetched from the data model before action resolution for improved performance.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations#displaying-enum-labels-in-text-components)
> > > >
> > > > See the Enumerations documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification template usages**
>
> > [card] Notification Template Usages
> >
> > > [tab] Overview
> > >
> > > Notification templates now show a **usages** modal that lists all processes and workflows referencing the template. This helps you understand the impact of changes before editing or deleting a template.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > > >
> > > > See the Managing Notification Templates documentation.
> >
> > All Deployments
>
> ***
>
> ### **Side Panel in Data Model**
>
> > [card] Side Panel in Data Model
> >
> > > [tab] Overview
> > >
> > > The Data Model editor now includes a side panel for easier navigation and editing of data model attributes, improving the workflow when working with large data models.
> >
> > All Deployments
>
> ***
>
> ### **On Display UI event**
>
> > [card] On Display UI event
> >
> > > [tab] Overview
> > >
> > > A new `onDisplay` event type that triggers every time a screen becomes visible — on initial load, when navigating back, or when a modal is dismissed. Unlike On Load (which fires once), On Display re-triggers on every view, making it ideal for refreshing data.
> > >
> > > Supported on Page, Zone, and Tab Bar components in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **On Load event on Modal**
>
> > [card] On Load event on Modal
> >
> > > [tab] Overview
> > >
> > > Modal components in UI Flows now support the On Load event and Start Workflow action. This enables data fetching when a modal opens, allowing you to load context-specific data for modal content.
> >
> > All Deployments
>
> ***
>
> ### **KB user-defined metadata**
>
> > [card] KB user-defined metadata
> >
> > > [tab] Overview
> > >
> > > Define custom metadata keys on Knowledge Bases and assign values to content sources. User-defined metadata enables filtering and scoping when searching chunks — for example, by department, document version, or region. Metadata values are propagated to the vector database and can be used as filters in the Context Retrieval workflow node.
> >
> > All Deployments
>
> ***
>
> ### **Config params in workflow conditions**
>
> > [card] Config params in workflow conditions
> >
> > > [tab] Overview
> > >
> > > Workflow Fork (condition) nodes can now access configuration parameters via `additionalData.applicationConfiguration` and authenticated user details via `additionalData.securityDetails` in their expressions. This enables environment-aware routing and user-based branching in integration workflows.
> >
> > All Deployments
>
> ***
>
> ### **Branding settings grouping**
>
> > [card] Branding settings grouping
> >
> > > [tab] Overview
> > >
> > > The branding settings page has been reorganized with improved grouping and layout, making it easier to find and configure branding options.
> >
> > All Deployments
>
> ***
>
> ### **Markdown in chat messages**
>
> > [card] Markdown in Chat Messages
> >
> > > [tab] Overview
> > >
> > > Chat message components in web renderers now support Markdown rendering. AI-generated responses can include formatted text, headings, links, code blocks, and lists — displayed with proper styling in the chat interface.
> >
> > All Deployments
>
> ***
>
> ### **External Action dynamic URL**
>
> > [card] External Action Dynamic URL
> >
> > > [tab] Overview
> > >
> > > External Action URLs now support `${expression}` syntax for dynamic values. Build destination URLs using process data, config params, or computed values — enabling context-aware external navigation from UI Flows.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-actions#external-ui-actions)
> > > >
> > > > See the UI Actions documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification history**
>
> > [card] Notification History
> >
> > > [tab] Overview
> > >
> > > New REST API endpoints on the notification plugin let you retrieve sent notification history. Query a paginated summary list filtered by app and optionally by process instance, or fetch full notification details by ID — including recipients, subject, body, and the source process/action that triggered it.
> > >
> > > * `GET /api/notification/summary` — paginated summary list with filtering and sorting
> > > * `GET /api/notification/{id}` — full notification details including body and recipients
> >
> > > [tab] Key Features
> > >
> > > > [card] Summary and detail views
> > > >
> > > > Paginated summary list for browsing, with full detail drill-down by notification ID
> > >
> > > > [card] Source tracking
> > > >
> > > > Each notification records which process, node, and action triggered it for full traceability
> >
> > All Deployments

> [tab] SaaS
>
> User management and branding improvements for SaaS deployments.
>
> 👤 [**Runtime User Invitations**](#runtime-user-invitations) - Invite runtime users directly to test projects\
> 🏢 [**Workspace Type Display**](#workspace-type-display) - See workspace type within Designer\
> 🎨 [**Container App Branding**](#container-app-branding) - Customize branding for SaaS container apps\
> 👥 [**Designer User Invitations**](#designer-user-invitations) - Updated invite modal for designer users
>
> ### **Runtime User Invitations**
>
> > [card] Runtime User Invitations
> >
> > > [tab] Overview
> > >
> > > Invite runtime users directly to test projects from within the Designer. Simplifies the process of granting test access without requiring full workspace-level permissions.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS
>
> ***
>
> ### **Workspace Type Display**
>
> > [card] Workspace Type Display
> >
> > > [tab] Overview
> > >
> > > The Designer now displays the workspace type (development, staging, production) directly within the workspace view, making it easier to identify your current environment.
> >
> > SaaS
>
> ***
>
> ### **Container App Branding**
>
> > [card] Container App Branding
> >
> > > [tab] Overview
> > >
> > > Customize your SaaS container app branding at the organization level — upload a custom logo, set primary and secondary colors, toggle the header, and configure the solutions page background.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/container-app-branding)
> > > >
> > > > See the Container App Branding documentation.
> >
> > SaaS
>
> ***
>
> ### **Designer User Invitations**
>
> > [card] Designer User Invitations
> >
> > > [tab] Overview
> > >
> > > The invite modal for designer users has been redesigned with clearer role selection, group assignment, and a streamlined layout for inviting multiple users.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS

> [tab] Bug Fixes
>
> ## Bug fixes
>
> ### Core Platform
>
> * **Authorization-system Oracle DB startup** — Fixed an issue where the authorization-system service failed to start when using Oracle as the configured database.
> * **Process definition merge timing** — Fixed a race condition where the process definition was updated before the merge was finalized.
> * **Theme import with builds** — Fixed an issue where themes were not included when importing builds.
> * **Library import permissions** — Fixed an issue where importing a library into a workspace redirected to a 403 error page.
> * **App version reimport** — Fixed an error that occurred when reimporting an app version (project or library).
> * **Email resend after URL expiry** — Fixed an issue where the resend email endpoint returned 200 OK but no email was sent after the URL expired.
> * **Platform status discovery** — Fixed an authorization error when trying to force discover platform status.
> * **Runtime roles in permissions** — Fixed inconsistent runtime roles display in the permissions dropdown.
>
> ### AI Platform & Workflows
>
> * **gRPC thread pool sizing** — Fixed under-provisioned gRPC client thread pools that caused socket timeouts and dropped requests in production.
> * **API error trace IDs** — API errors now include a reference to the active traceID for easier debugging.
> * **Cross-project resource copy** — Fixed an issue where copying a workflow resource to another project did not include LDM objects.
> * **Multi-instance mappings** — Fixed a 400 error when saving multi-instance mappings in data mappers.
> * **Email trigger mock testing** — Fixed errors when starting a process from a build with mock email content.
> * **Multiple start nodes with email trigger** — Fixed an issue where only one start option was displayed when a process contained multiple start nodes with email triggers.
>
> ### Renderers & UI
>
> * **Angular input field crash** — Fixed an issue where pressing Enter in an input field caused the Angular UI to crash.
> * **Floating Chat interaction blocking** — Fixed an issue where the floating chat component blocked all interaction with page content while open.
> * **S3 internal bucket error** — Fixed an error when the integration-designer downloads files from document-plugin via downloadPath.
> * **File upload second attempt** — Fixed an issue where upload requests were not made when uploading a second file.
> * **UI Flow analytics** — Fixed issues where analytics events were not visible and not saved for Navigate-to action types.
> * **Task management column selection** — Fixed an issue where the Last Updated column remained selected in task management.
> * **Task Manager theming and UX** — Multiple fixes for Task Manager theming, dropdown display, comment field styling, and user assignment behavior.
> * **Toggle/checkbox label alignment** — Fixed an issue where the switch toggle/checkbox or label shifted position when in an error state.&#x20;
> * **Query parameters lost after refresh** — Fixed an issue where URL query parameters were lost after page refresh in UI Flows.&#x20;
> * **SSE connection management** — Fixed multiple issues where SSE connections were opened twice or not closed properly after messages were received.&#x20;
> * **Modal layering** — Fixed incorrect layering when a loader modal was displayed on top of another modal.&#x20;
> * **Card theming overrides** — Fixed an issue where card theming overrides were not applied when the card was collapsed.&#x20;
> * **On Display workflow triggering** — Fixed an issue where past On Display workflows were not re-triggered on page refresh.&#x20;
>
> ### Knowledge Base
>
> * **KB metadata handling** — Fixed multiple issues with Knowledge Base user-defined metadata: empty properties on content source creation, metadata not available for content sources added through apps, and incorrect cleanup when deleting metadata keys.&#x20;

> [tab] Info
>
> ## Additional information
>
> ### At a glance
>
> This release includes **30+ new features and enhancements** across AI Platform, Integrations, UI & Designer, and SaaS — plus **28 bug fixes** spanning Core Platform, AI/Workflows, Renderers, and Knowledge Base.
>
> ***
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6).
>
> For new environment variables and Kafka topics, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6#new-environment-variables).
>
> ### Changes to be aware of
>
> > [!NOTE]
> >
> > FlowX.AI 5.6.0 is a SaaS-managed release — deployment-level changes (infrastructure, Kafka topics, service configuration) are handled automatically by FlowX. The items below are listed for transparency and for future reference when on-prem support ships in 5.7+.
>
> #### API change (action required if you use this endpoint)
>
> > [!WARNING]
> >
> > **Process definition start metadata endpoint renamed** — `GET /api/process-definition/{uuid}/get-input-json` has been renamed to `GET /api/process-definition/{uuid}/get-start-metadata`. Update any API clients or custom integrations that call this endpoint directly.
> >
> > The response now includes an additional `hasEmailTriggerStart` boolean field.
>
> #### Infrastructure changes (managed by FlowX on SaaS)
>
> * **gRPC thread pool configuration** — Default gRPC client thread pool sizes have been updated for better production throughput.
> * **WorkspaceCreatedEvent ownership** — Kafka topic ownership moved from `authorization-system` to `organization-manager`.
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.5.0 — if you call `get-input-json` directly, update to `get-start-metadata`. All other changes are managed automatically on SaaS.
>
> > [card] [Component versions](./deployment-guidelines-v5.6#component-versions)
> >
> > See the Deployment Guidelines for the full component version matrix


# Deployment guidelines v5.7.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7

Component versions, environment variables, and configuration changes for FlowX.AI 5.7.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.96.0** | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 |
| **admin** | **10.83.0** | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 |
| **designer** | **10.164.0** | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **cms-core** | **10.58.0** | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 |
| **scheduler-core** | **10.45.0** | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 |
| **events-gateway** | **10.47.0** | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 |
| **notification-plugin** | **10.56.0** | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 |
| **document-plugin** | **10.64.0** | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 |
| **task-management-plugin** | **10.57.0** | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 |
| **data-search** | **10.44.0** | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 |
| **audit-core** | **10.54.0** | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 |
| **advancing-controller** | **10.45.0** | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 |
| **integration-designer** | **10.113.0** | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 |
| **application-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **runtime-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **data-sync** | **10.50.0** | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 |
| **authorization-system** | **10.68.0** | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 |
| **nosql-db-runner** | **10.48.0** | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 |
| **email-gateway** | **10.47.0** | 10.32.1 | 10.24.0 | 10.9.0 | - | - |
| **organization-manager** | **10.44.0** | 10.26.1 | 10.19.2 | - | - | - |
| **webhook-gateway** | **10.15.0** | 10.1.1 | - | - | - | - |
| **license** | **10.36.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |

### Plugins

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 |
| **ai-platform-ai-assistant** | **10.6.2** | - | - | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 |
| **ai-platform-ai-developer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-connected-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-knowledge-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agents** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-conversations** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-tenants** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-planner** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-analyst** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-designer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agent-builder** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-binaries** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **embedder** | **10.6.2** | - | - | - | - | - |
| **knowledgebase-rag** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **mcp** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **doc-converter** | **10.2.3** | 10.2.2 | - | - | - | - |
| **doc-parser** | **10.6.2** | 10.5.1 | - | - | - | - |
| **web-crawler** | **10.3.2** | - | - | - | - | - |
| **data-privacy** | **10.0.8** | - | - | - | - | - |
| **speech-to-text** | **10.3.3** | - | - | - | - | - |
| **modpod** | **10.0.7** | - | - | - | - | - |

> [!NOTE]
>
> **Note:** The `ai-platform-models` service has been removed in 5.7.0. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers) within the Organization Manager.

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.7.0 | Keycloak | 26+ |
| 5.7.0 | Kafka | 3.8 - 3.9 |
| 5.7.0 | PostgreSQL | 16 - 17 |
| 5.7.0 | Oracle Database | 21c, 23ai |
| 5.7.0 | MongoDB | 7 - 8 |
| 5.7.0 | Redis | 7.4 - 8.0 |
| 5.7.0 | Elasticsearch | 8 |
| 5.7.0 | Angular (Web SDK) | 20 |
| 5.7.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> The following versions of third-party dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

***

## Self-hosted deployment changes

> [!WARNING]
>
> **First on-premises release since 5.4.0.** This section covers critical configuration changes for self-hosted (on-premises) deployments.

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **Fresh install** | Supported | Guided setup flow on first launch. See [Organization Manager setup](/5.1/setup-guides/organization-manager-setup). |
| **5.1.x LTS** | Supported | Requires Organization ID on all 19 services. Liquibase migrates active process instances and realm data. Inactive instances require separate handling by FlowX. See details below. |
| **5.2 - 5.4** | FlowX-assisted only | These versions may have partial realm or organization changes. Contact your FlowX representative for a custom migration plan. Do **not** follow the 5.1.x upgrade path. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

### Organization ID (mandatory for upgrades)

The Organization ID is how FlowX identifies your installation. How it is obtained depends on your deployment path:

* **Fresh install:** The Organization ID is created automatically during the guided setup flow (Designer first-launch screen). No manual configuration needed.
* **Upgrade from 5.1.x:** FlowX registers your organization in the SaaS licensing infrastructure and provides an Organization ID (UUID). Set `ORGANIZATION_ID` on **all 19 services** before deploying 5.7.0 images — Liquibase migrations use it to replace the default organization.

```yaml theme={"dark"}
# Example — set on every service
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

**Affected services (all 19):** process-engine, admin, audit-core, authorization-system, advancing-controller, events-gateway, cms-core, scheduler-core, data-search, document-plugin, nosql-db-runner, notification-plugin, task-management-plugin, integration-designer, organization-manager, email-gateway, application-manager, runtime-manager, license.

> [!WARNING]
>
> Do **not** deploy 5.7.0 images without setting `ORGANIZATION_ID` on upgrade scenarios. Services will fail to start if Liquibase migrations cannot find the organization ID.

> [!NOTE]
>
> **Active vs inactive instances.** Liquibase migrations automatically update the Organization ID on **active process instances** only. Inactive or archived instances require separate migration handled by the FlowX team during guided deployment. Contact your FlowX representative for details.

### License service (new)

Self-hosted deployments must configure the License service to connect to FlowX SaaS for license validation and usage reporting. See the [License service setup guide](/5.9/setup-guides/license-engine-setup) for complete configuration.

### IAM / Keycloak changes

FlowX.AI now uses a **two-realm architecture** in Keycloak and **JWT public key validation** (replacing opaque-token introspection). These changes were introduced in 5.5.0 (SaaS) and are now relevant for self-hosted deployments.

* **Token validation**: `security.type` switches from `oauth2` to `jwt-public-key` on all services
* **Service accounts realm**: A dedicated realm (`00000002-0002-4002-8002-000000000002`) holds all service account clients, separate from the user realm
* **Organization manager**: Now a required dependency for all services (provides realm resolution)
* **`flowx-platform-authorize` client**: No longer needed — remove from Keycloak
* **Master realm credentials**: The authorization-system service needs Keycloak admin access for realm migrations. If you cannot provide admin credentials, see [Manual Keycloak configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).
* **SMTP**: Must be configured in Keycloak for password reset and user invitations

For complete IAM setup instructions, see the [Configuring an IAM solution](/5.1/setup-guides/access-management/configuring-an-iam-solution) guide.

***

## Environment info deprecation

The **Configure Environment Info** feature (`PATCH /api/platform/environment`) is deprecated and removed. Environment name is now set during organization registration. The following are no longer used:

* `FLOWX_CLIENT_NAME` environment variable
* `FLOWX_ENVIRONMENT_NAME` environment variable
* `environmentDetails` section in the `/api/init` response

***

## Kafka integration changes

### Fx-Organization-Id header (mandatory)

All FlowX Kafka consumers now validate the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected with a non-retryable `MissingKafkaHeaderException`.

> [!WARNING]
>
> **Action required for custom Kafka integrations.** If you have custom Kafka producers that publish directly to FlowX topics (starting processes, sending task events, responding to engine requests), you must add the `Fx-Organization-Id` header to every message. Set it to the Organization UUID (`ORGANIZATION_ID` value).
>
> ```java theme={"dark"}
> producerRecord.headers().add("Fx-Organization-Id",
>     organizationId.getBytes(StandardCharsets.UTF_8));
> ```
>
> See the [Creating a Kafka producer](/5.1/docs/platform-deep-dive/integrations/creating-a-kafka-producer#important-headers) guide for details.

### New Kafka topics

| Topic | Environment Variable | Producer | Consumer | Description |
| - | - | - | - | - |
| `ai.flowx.llm.config.changed.v1` | `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | organization-manager | integration-designer, AI Python services | Broadcast when LLM provider or model configuration changes at the organization level |

***

## Environment variables

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `ORGANIZATION_ID` | Organization UUID provided by FlowX. Required on all services for upgrades. Fresh installs get this automatically via the setup flow. | - | all services |
| `FLOWX_LICENSE_KEY` | License key for FlowX SaaS connection | - | license |
| `FLOWX_LICENSE_AUTHSERVERURL` | FlowX SaaS auth URL | - | license |
| `FLOWX_LICENSE_SERVERURL` | FlowX SaaS license API URL | - | license |
| `FLOWX_ORG_MANAGER_URL` | Organization Manager service URL for LLM provider configuration. Required on all Python AI services. | - | planner, ai-developer, ai-analyst, ai-designer, agent-builder, knowledgebase-rag, embedder, knowledgebase |
| `SECURITY_MASTERREALM_CLIENTID` | Master realm admin client ID for Keycloak management | `admin-cli` | authorization-system |
| `SECURITY_MASTERREALM_NAME` | Keycloak master realm name | `master` | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username for realm migrations | - | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password for realm migrations | - | authorization-system |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` | all services |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL for security lib | `http://organization-manager:80` | all services |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `60` | organization-manager |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `30` | organization-manager |
| `FLOWX_SPEECH_TO_TEXT_BASE_URL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` | integration-designer |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Topic for LLM config change notifications | `ai.flowx.llm.config.changed.v1` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys at rest. **Change from default in production.** | `default-dev-key-change-in-prod` | organization-manager |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required on on-prem deployments. | - | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required on on-prem deployments when the FlowX generic container app is deployed. | - | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If empty, derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` | organization-manager |
| `DEFAULT_ORGANIZATION_NAME` | Fallback organization code used by the Designer web app during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present. Required on on-prem — set to the organization code registered with FlowX. | - | designer |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for Oracle Database schema discovery responses cached for the SQL editor. | `24h` | integration-designer |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools used by Oracle Database data sources. | `100` | nosql-db-runner |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached JDBC connection pools. | `1d` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per Oracle Database data source. | `5` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout for Oracle Database data sources. | `10` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses for Oracle Database operations. | `1000` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout for Oracle Database operations. | `30` | nosql-db-runner |

### Removed environment variables

> [!WARNING]
>
> **For upgrades:** Remove these variables only **after** the Liquibase migrations have completed successfully. If you remove them before starting services for the first time on 5.7.0, the migrations may fail. The recommended sequence is: (1) add new variables, (2) deploy 5.7.0 images, (3) let migrations run, (4) verify services are healthy, (5) remove old variables in a follow-up deployment.

| Environment Variable | Reason | Component |
| - | - | - |
| `FLOWX_CLIENT_NAME` | Replaced by org code from registration | process-engine |
| `FLOWX_ENVIRONMENT_NAME` | Replaced by env name from registration | process-engine |
| `AI_SERVICE_MODELS_ENDPOINT` | The Models microservice (port 9104) has been removed. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers). Remove this service from your deployment. | ai-platform (all Python services) |
| `SECURITY_OAUTH2_REALM` | Replaced by per-organization realm resolution. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | Opaque-token introspection client no longer needed. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | Opaque-token introspection client secret no longer needed. | all services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_*` | Entire opaque-token introspection config removed. | all services |


# FlowX.AI 5.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/v5.7.0-april-2026

Single-org on-premises deployment, custom React components, AI providers self-service, chat-based UI Flows, voice input, end-user access management, and advanced query builder.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

FlowX.AI 5.7.0 makes on-premises deployment a first-class experience. **Single-org deployment** is now the default mode — configure your organization once, connect to FlowX licensing, and you're running. For builders, **Custom Components** let you write React code directly in the Designer, **AI Providers** configuration gives organizations self-service control over their LLM setup, and **Chat-based UI Flows** simplify conversational experiences. For organization admins, **End-user access management** separates runtime users, roles, and groups from Designer users.

> [card] [For platform teams](#single-org-deployment)
>
> Single-org deployment, license service, organization setup flow

> [card] [For builders](#custom-components)
>
> Custom React components, AI provider config, chat-based UI Flows, voice input

> [card] [For admins](#end-user-access-management)
>
> End-user access management, runtime roles, and groups

### What changed since 5.6.0

| 5.6.0 | 5.7.0 |
| - | - |
| SaaS-focused deployment | + **Single-org on-premises** as the default mode |
| Built-in UI components only | + **Custom React Components** with code editor and dependencies |
| AI models configured by FlowX | + **AI Providers self-service**: OpenAI (FlowX Managed or BYOK), custom URL, Defaults & Fallbacks per workspace type |
| Chat workflow set per component | + **Chat-based UI Flows**: set one workflow for the entire UI Flow |
| Text-only chat input | + **Voice input** for chat conversations |
| No audio processing in workflows | + **Speech to Text** node for transcription and text-to-speech |
| Runtime users mixed with Designer users | + **End-user access management**: separate org-level lists for end-users, roles, and groups, with CSV bulk invite |
| Basic query filters | + **Advanced Query Builder** for database operations |
| MongoDB-only database data sources | + **Oracle Database** as a new data source type with schema-aware SQL editor |
| Fixed search strategy for KB retrieval | + **Context Retrieval**: configurable search type (Hybrid/Semantic/Keyword) and re-ranking |
| Equality-only metadata filters, AND logic | + **Knowledge Base filter builder** with typed operators and AND/OR grouping; **Content Sources** tab renamed to **Stores** |
| Basic merge modal | + **Merge conflicts UX**: redesigned modal, diff viewer theme, keyboard support |

***

**What's new?**

> [tab] Platform
>
> FlowX 5.7.0 introduces single-org deployment as the default mode for on-premises installations, with self-service licensing, organization management, and runtime access controls.
>
> 🏢 [**Single-org deployment**](#single-org-deployment) - On-premises deployment with automatic organization setup\
> 🔑 [**License service**](#license-service) - Connect to FlowX SaaS for license validation and usage reporting\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level end-users, roles, and groups, separate from Designer users
>
> ### **Single-org deployment**
>
> > [card] Single-org deployment
> >
> > > [tab] Overview
> > >
> > > Self-hosted deployments now run as single-organization systems by default. FlowX registers your organization in the SaaS licensing infrastructure, provides an Organization ID, and your deployment connects to FlowX for license validation and usage reporting. The Designer guides you through a setup flow on first launch: enter a token, name your environment, and create your admin user.
> > >
> > > > [card] [Documentation](/5.1/setup-guides/organization-manager-setup#organization-id-configuration)
> > > >
> > > > See the Organization Manager setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Guided setup flow
> > > >
> > > > Designer walks you through organization registration on first launch
> > >
> > > > [card] Organization ID
> > > >
> > > > Mandatory on all services for Liquibase migrations on upgrades
> > >
> > > > [card] License connectivity
> > > >
> > > > On-premises license service connects to FlowX SaaS for validation and usage
> > >
> > > > [card] Multi-org features hidden
> > > >
> > > > Registration, org selection, and org switching are not available on-prem
> > >
> > > > [card] Explicit web app URLs
> > > >
> > > > Designer and Runtime URLs are configured via dedicated on-prem env vars on organization-manager, replacing hard-coded org-code lookup
> >
> > Major FeatureSelf-Hosted
>
> ***
>
> ### **License service**
>
> > [card] License service
> >
> > > [tab] Overview
> > >
> > > The License service is the bridge between your self-hosted deployment and FlowX SaaS. It validates your platform license, reports usage data, and ensures your subscription is active. Configure it with the license key and server URLs provided by FlowX during organization registration.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> > > >
> > > > See the License service setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] License validation
> > > >
> > > > Continuous license sync with FlowX SaaS
> > >
> > > > [card] Usage reporting
> > > >
> > > > AI node execution consumption reported to FlowX
> > >
> > > > [card] Organization events
> > > >
> > > > Listens to organization lifecycle events via Kafka
> > >
> > > > [card] Setup guide
> > > >
> > > > Complete setup guide with PostgreSQL, Kafka, Redis, and SpiceDB configuration
> >
> > Self-Hosted
>
> ***
>
> ### **End-user access management**
>
> > [card] End-user access management
> >
> > > [tab] Overview
> > >
> > > Organization admins can now manage the people who use published solutions separately from Designer users. A new **Access Management** section at the organization level holds three lists — **End-Users**, **End-Users Roles**, and **End-Users Groups** — each with its own permissions. Invite end users individually or import many at once from a CSV template, define roles that describe runtime access, and organize users into groups with custom attributes for filtering.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> > > >
> > > > See the End-user access management setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Separate end-user list
> > > >
> > > > End-Users are kept distinct from Designer users, with their own read/write permissions
> > >
> > > > [card] End-user roles
> > > >
> > > > Define named roles that describe runtime access at the organization level
> > >
> > > > [card] End-user groups
> > > >
> > > > Group users by department, region, or any attribute, and assign roles to the whole group
> > >
> > > > [card] Bulk invite
> > > >
> > > > Invite many users at once from a CSV template with names and attributes
> >
> > All Deployments
>
> ***

> [tab] AI & Chat
>
> Self-service AI provider configuration, chat-based UI Flows, AI Triggers, and voice input for conversational experiences.
>
> 🤖 [**AI Providers**](#ai-providers) - Organization-level LLM provider and model configuration\
> 💬 [**Chat-based UI Flows**](#chat-based-ui-flows) - Set a conversational workflow for the entire UI Flow\
> 🎤 [**Voice input**](#voice-input) - Speech-to-text input in chat conversations\
> ⏹️ [**Stop agent response**](#stop-agent-response) - Cancel an in-progress agent reply from the chat input\
> 🗣️ [**Speech to Text node**](#speech-to-text-node) - Transcription and text-to-speech workflow node\
> ⚡ [**AI Triggers**](#ai-triggers) - Named message templates for launching conversational workflows with context\
> 🧩 [**UI Flow Context**](#ui-flow-context) - Pass UI state from a Page to a conversational workflow\
> 🎯 [**Recommended prompts**](#recommended-prompts) - AI-generated follow-up suggestions in chat conversations\
> 🔎 [**Context Retrieval enhancements**](#context-retrieval-enhancements) - Configurable search type and re-ranking\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - Stores rename, typed metadata filters, AND/OR grouping\
> 🌐 [**Web Page Extractor enhancements**](#web-page-extractor-enhancements) - URL filtering, crawl depth, and file downloads
>
> ### **AI Providers**
>
> > [card] AI Providers
> >
> > > [tab] Overview
> > >
> > > Organizations can now configure their own AI providers and assign models at the organization level. Configure **OpenAI** (Bring Your Own Key or FlowX Managed) or **Azure OpenAI** for deployment-based access to GPT models, enable specific models, and assign default and fallback models per AI capability and workspace type (Sandbox, Staging, Production). **Defaults & Fallbacks** now includes an **Audio Capabilities** row used by the Speech to Text node, with `whisper-1` available in the OpenAI model catalog.
> > >
> > > ![Model Providers page with OpenAI and Azure OpenAI configured at the organization level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_view_org.png)
> > >
> > > ![Provider Details modal showing OpenAI and Azure OpenAI as provider options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_model_Provider.png)
> > >
> > > ![Defaults and Fallbacks page with capability rows including Audio Capabilities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/defaults_and_fallbacks.png)
> > >
> > > ![Model selection and configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ai_models_selection.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/ai-providers)
> > > >
> > > > See the AI providers and model configuration documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Organization-level providers
> > > >
> > > > Add and manage AI providers with API keys and connection settings
> > >
> > > > [card] Azure OpenAI
> > > >
> > > > Connect to Azure-hosted OpenAI deployments with a base URL and API version
> > >
> > > > [card] Custom model entry
> > > >
> > > > Add models manually for providers that use deployment names (Azure) or non-public catalogs
> > >
> > > > [card] Audio Capabilities
> > > >
> > > > New row in Defaults & Fallbacks for transcription and speech synthesis, used by the Speech to Text node
> > >
> > > > [card] Defaults & Fallbacks
> > > >
> > > > Assign default and fallback models per AI capability and workspace type
> > >
> > > > [card] Fallback strategy
> > > >
> > > > Set fallback models on different providers for resilience
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat-based UI Flows**
>
> > [card] Chat-based UI Flows
> >
> > > [tab] Overview
> > >
> > > UI Flows now support two experience types: **Flow-Based** (traditional) and **Chat-Based** (conversational). Chat-Based UI Flows connect to a conversational workflow at the UI Flow level, so all Chat components in the flow use the same workflow by default. A new Settings page with a Chat Options tab lets you configure or change the workflow after creation.
> > >
> > > ![Chat-based UI Flow configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_based_ui_flow.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> > > >
> > > > See the UI Flows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Experience types
> > > >
> > > > Choose Flow-Based or Chat-Based when creating a UI Flow
> > >
> > > > [card] UI Flow Settings
> > > >
> > > > New Settings page with Chat Options tab for workflow configuration
> > >
> > > > [card] Workflow filtering
> > > >
> > > > Chat components only show conversational workflows in the selector
> > >
> > > > [card] Navigate in UI Flow
> > > >
> > > > AI can open specific screens with parameters from a conversation
> >
> > All Deployments
>
> ***
>
> ### **Chat improvements**
>
> > [card] Chat improvements
> >
> > Configure which parts of the chat header are visible on a per-component basis. The Chat component (when display type is **Fill**) gains a **Show Header** toggle in its Properties panel, and the Chat Header component gets a new **Available Actions** accordion with toggles for **New Conversation** and **History**. Conversation history now loads in pages, with a **Load more** action, and conversations are sorted by creation date with the most recent first.
> >
> > All Deployments
>
> ***
>
> ### **Voice input**
>
> > [card] Voice input
> >
> > > [tab] Overview
> > >
> > > Chat components now support voice input, allowing users to record audio messages directly in the chat. Users can record, preview with an audio player, and send voice messages within conversations.
> > >
> > > > [!NOTE]
> > > >
> > > > Voice input captures and sends audio recordings. When paired with the [Speech to Text](/5.9/ai-platform/agent-builder/speech-to-text) workflow node, voice messages are automatically transcribed and processed as text in conversational workflows.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audio recording
> > > >
> > > > Record voice messages directly in the chat input
> > >
> > > > [card] Audio preview
> > > >
> > > > Preview recordings with a built-in audio player before sending
> >
> > All Deployments
>
> ***
>
> ### **Stop agent response**
>
> > [card] Stop agent response
> >
> > > [tab] Overview
> > >
> > > The chat input now shows a **Stop** button in place of Send while an agent reply is streaming. Pressing Stop cancels the conversational workflow instance: any in-flight AI call is aborted, partial output is discarded, and the user prompt is persisted with a `cancelled` flag so the chat history reflects what happened.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Cross-platform
> > > >
> > > > Available on Web (Standard, Floating, Full Screen), iOS, and Android
> > >
> > > > [card] Themeable
> > > >
> > > > New `stopResponseIcon` slot in `chatInputArea` themes; preloaded by cms-core
> > >
> > > > [card] Localized
> > > >
> > > > New system substitution tags for Stop and Send labels with a11y variants
> >
> > All Deployments
>
> ***
>
> ### **Speech to Text node**
>
> > [card] Speech to Text
> >
> > > [tab] Overview
> > >
> > > A new workflow node that converts between audio and text. **Transcribe** converts audio files (MP3, WAV, M4A, AAC, OGG) into text with language detection and confidence scores. **Text to Speech** generates audio files from text with configurable voice, speed, and format. In conversational workflows, the node processes voice messages from the chat UI automatically.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> > > >
> > > > See the Speech to Text node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Transcription
> > > >
> > > > Convert audio to text with language detection and confidence scores
> > >
> > > > [card] Text to Speech
> > > >
> > > > Generate audio from text with configurable voice, model, speed, and format
> > >
> > > > [card] Chat voice integration
> > > >
> > > > Automatically transcribes voice messages in conversational workflows
> > >
> > > > [card] Multiple file sources
> > > >
> > > > Read from Document Plugin, S3, or chat input
> >
> > > [!NOTE]
> > >
> > > The transcription model is resolved from the organization's **Audio** capability default, configured in **AI Settings** under [Defaults & Fallbacks](/5.9/ai-platform/ai-providers).
> >
> > All Deployments
>
> ***
>
> ### **AI Triggers**
>
> > [card] AI Triggers
> >
> > > [tab] Overview
> > >
> > > Define named message templates with parameters on conversational workflows, so different UI Flow pages can launch the same workflow with different starting contexts. Triggers are configured in a dedicated side nav tab and selected on the Start node or sent from the Chat component at runtime.
> > >
> > > ![Reply Triggers list in a conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_reply_trigger.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Parameterized messages
> > > >
> > > > Message templates with `${paramName}` placeholders resolved at runtime
> > >
> > > > [card] Multi-page reuse
> > > >
> > > > Different pages launch the same workflow with different context
> > >
> > > > [card] Start node integration
> > > >
> > > > Toggle between Text and AI Trigger modes on the Start node
> > >
> > > > [card] Memory aware
> > > >
> > > > Trigger messages saved to conversation memory but hidden from chat history
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Context**
>
> > [card] UI Flow Context
> >
> > > [tab] Overview
> > >
> > > Conversational workflows can now receive a JSON context alongside the user message. A new **Conversation Context** property on UI Flow Pages lets you define the Parameters payload (with `${expression}` resolution), and the Start node exposes it as a collapsible **UI Flow Context** editor — also available in the Run Workflow test modal for manual runs.
> > >
> > > ![Start node UI Flow Context and UI Flow Conversation Context property](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#setting-context-from-a-ui-flow)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] UI-driven context
> > > >
> > > > Pages attach a JSON payload to conversational runs without hard-coding it in the workflow
> > >
> > > > [card] Expression resolution
> > > >
> > > > Parameters support `${expression}` syntax to bind live UI Flow data at runtime
> > >
> > > > [card] Start node field
> > > >
> > > > Collapsible UI Flow Context editor on the Start node for both runtime and manual testing
> > >
> > > > [card] JSON validation
> > > >
> > > > Invalid JSON is rejected before the run starts, surfacing a clear error
> >
> > All Deployments
>
> ***
>
> ### **Recommended prompts**
>
> > [card] Recommended prompts
> >
> > > [tab] Overview
> > >
> > > Custom Agent nodes can now generate follow-up prompt suggestions alongside their chat replies. When enabled via the new **Prompt Suggestions** satellite panel on a Custom Agent node, the agent includes recommended next questions or actions in its response. These appear as clickable suggestions in the chat UI, guiding users toward relevant follow-up interactions.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions)
> > > >
> > > > See the Custom Agent node documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Satellite panel
> > > >
> > > > Configure prompt suggestions directly on Custom Agent nodes in the workflow editor
> > >
> > > > [card] AI-generated suggestions
> > > >
> > > > Agent generates contextual follow-up prompts based on the conversation
> > >
> > > > [card] Clickable in chat
> > > >
> > > > Suggestions render as tappable chips in the chat UI
> > >
> > > > [card] Conversational workflows
> > > >
> > > > Works with send-as-reply mode in conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval enhancements**
>
> > [card] Context Retrieval enhancements
> >
> > > [tab] Overview
> > >
> > > **Custom Agent** and **Context Retrieval** nodes now support configurable **search type** and **re-ranking** for Knowledge Base retrieval. Choose between Hybrid (default), Semantic, or Keyword search strategies depending on your use case. Turn on re-ranking to apply a secondary relevance model that reorders retrieved chunks for higher-quality results.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the Context Retrieval node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Search type
> > > >
> > > > Choose Hybrid, Semantic, or Keywords search for Knowledge Base retrieval on Custom Agent and Context Retrieval nodes
> > >
> > > > [card] Re-ranking
> > > >
> > > > Apply a re-ranking model to reorder results by relevance to the query — available on both Custom Agent and Context Retrieval nodes
> >
> > All Deployments
>
> ***
>
> ### **Knowledge Base enhancements**
>
> > [card] Knowledge Base enhancements
> >
> > > [tab] Overview
> > >
> > > The Knowledge Base data source gets a refreshed workspace and a more powerful metadata filter builder. The **Content Sources** tab is now called **Stores**, and the Chunks tab gains a structured query builder for metadata filters with typed operators, AND/OR logic, and grouping — replacing the previous equality-only filters.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > > >
> > > > See the Knowledge Base content management guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Stores tab
> > > >
> > > > The Content Sources tab is renamed to Stores. Same concept, clearer label.
> > >
> > > > [card] Typed filter operators
> > > >
> > > > Operators per metadata type: equals, not equals, contains, in, not in, before, after, exists, size equals, and more
> > >
> > > > [card] AND/OR grouping
> > > >
> > > > Combine conditions with AND or OR and nest them in groups for non-trivial logic
> > >
> > > > [card] Query builder on Chunks tab
> > > >
> > > > Test retrieval with Search Type (Hybrid/Semantic/Keywords), Use Re-rank, and the new filter builder
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor enhancements**
>
> > [card] Web Page Extractor enhancements
> >
> > > [tab] Overview
> > >
> > > The Web Page Extractor node now supports **URL filtering** to include or exclude specific URL patterns during crawling, **configurable crawl depth** for more control over how deep the crawler follows links, and **file downloads** to retrieve attached files from crawled pages.
> >
> > > [tab] Key Features
> > >
> > > > [card] URL filtering
> > > >
> > > > Include or exclude URLs matching specific patterns during crawling
> > >
> > > > [card] Crawl depth
> > > >
> > > > Configure how many levels deep the crawler follows links
> > >
> > > > [card] File downloads
> > > >
> > > > Download attached files from crawled web pages
> > >
> > > > [card] Bulk document type
> > > >
> > > > When file downloads are enabled, the document type auto-sets to **Bulk** so a single crawl can return multiple documents
> >
> > All Deployments
>
> ***

> [tab] UI & Components
>
> Custom React components, advanced query builder, and merge conflict improvements.
>
> 🧩 [**Custom Components**](#custom-components) - Write React code in Designer and use in UI Flows\
> 🔍 [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder for database operations\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor\
> 🔀 [**Merge conflicts UX**](#merge-conflicts-ux) - Improved merge modal and conflict resolution experience
>
> ### **Custom Components**
>
> > [card] Custom Components
> >
> > > [tab] Overview
> > >
> > > Create custom React components directly in FlowX Designer. Write JSX, CSS, and use pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Components receive process data through input keys and can trigger process actions. Define once in Reusable Resources, use across multiple User Tasks.
> > >
> > > ![Custom Components code editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> > > >
> > > > See the Custom Components documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Code editor
> > > >
> > > > Write React JSX and CSS with a built-in code editor and file tree
> > >
> > > > [card] Pre-defined packages
> > > >
> > > > React, Emotion, Lodash, Axios, and date-fns available out of the box
> > >
> > > > [card] Process integration
> > > >
> > > > Receive process data via input keys and trigger process actions
> > >
> > > > [card] Import/Export
> > > >
> > > > Export as ZIP and import into other projects
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Advanced Query Builder**
>
> > [card] Advanced Query Builder
> >
> > > [tab] Overview
> > >
> > > A visual query builder for database operations and metadata filters, replacing manual JSON query writing with a structured interface. Build complex queries with conditions, grouping, and sorting without writing raw queries. The operator set has expanded with NULL checks (`exists`, `is null`), set membership (`not in`), string matching (`contains`, `starts with`, `ends with`), boolean tests (`is true`, `is false`), and date comparators (`before`, `after`). The `between` operator has been removed from the UI.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> > > >
> > > > See the FlowX Database documentation for the full query builder reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] Visual conditions
> > > >
> > > > Build query conditions with a structured UI instead of raw JSON
> > >
> > > > [card] Grouping and sorting
> > > >
> > > > Combine conditions with AND/OR grouping and configure result sorting
> > >
> > > > [card] Schema awareness
> > > >
> > > > Fields auto-populated from your collection schema with type-aware operators
> > >
> > > > [card] Visual/Script toggle
> > > >
> > > > Switch between visual builder and raw code editor at any time
> >
> > All Deployments
>
> ***
>
> ### **Oracle Database integration**
>
> > [card] Oracle Database integration
> >
> > > [tab] Overview
> > >
> > > Connect FlowX workflows to externally managed Oracle databases. Configure a connection (Oracle 19c, 21c, or 23ai), save parameterized SQL queries against the schema, and call them from the existing Database Operation node alongside other data sources.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> > > >
> > > > See the Oracle Database integration guide for the full reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] SERVICE\_NAME or SID
> > > >
> > > > Connect via Service Name or SID, with an optional SSL toggle
> > >
> > > > [card] Schema-aware SQL editor
> > > >
> > > > Monaco editor with syntax highlighting, autocomplete, and a side panel for tables, columns, primary keys, and foreign keys
> > >
> > > > [card] Test queries inline
> > > >
> > > > Run SQL with sample parameters: table view for SELECT, affected-row count for INSERT, UPDATE, and DELETE
> > >
> > > > [card] Workflow integration
> > > >
> > > > Pick the Oracle data source and query from the Database Operation node, with no new node type required
> >
> > All Deployments
>
> ***
>
> ### **Datasource Experience**
>
> > [card] Datasource Experience
> >
> > The **Add Data Source** dialog now groups data source types into four categories (**AI Capabilities**, **APIs**, **Databases**, and **Connectors**) with a search box for finding a specific type. REST endpoint authoring also suggests common HTTP headers and values to speed up integration setup.
> >
> > ![New Add Data Source dialog with categorized data source types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_new_data_source.png)
> >
> > All Deployments
>
> ***
>
> ### **MongoDB-aware code editor**
>
> > [card] MongoDB-aware code editor
> >
> > Operation editors on MongoDB data sources now use a Monaco language provider tuned for MongoDB. The editor highlights MongoDB operators (Comparison, Logical, Element, Evaluation, Array, Update, Aggregation, Conditional) and `${param}` interpolations, including inside string literals. Three autocomplete flows speed up authoring: typing `$` lists MongoDB operators, opening a quote in a field-name position lists the schema field paths from the linked Project Data Type, and typing inside `${...}` lists the operation's parameter keys.
> >
> > All Deployments
>
> ***
>
> ### **Project Data Model authoring**
>
> > [card] Project Data Model authoring
> >
> > Three improvements make Project Data Model authoring easier and less error-prone.
> >
> > > [card] Go to source
> > >
> > > A new **Go to source** button on data-model usages and Data Model nodes jumps directly to the source definition without manual navigation.
> >
> > > [card] Type-aware example values
> > >
> > > The example-value input on each attribute now matches its declared type: number inputs for NUMBER, a date picker for DATE, a true/false dropdown for BOOLEAN, single-select for enums, multi-select chips for enum arrays, and so on. CURRENCY values use the currency code rather than the symbol.
> >
> > > [card] Type-aware test data
> > >
> > > The same type-aware inputs apply when running or testing a workflow node and when filling input parameters for a reusable function, replacing the previous generic text inputs.
> >
> > All Deployments
>
> ***
>
> ### **Stop Run for workflows**
>
> > [card] Stop Run for workflows
> >
> > You can now cancel a running workflow instance directly from the workflow editor. While a workflow is running, the **Run Workflow** button switches to **Stop Run** — clicking it cancels the instance and marks all in-progress and scheduled nodes as cancelled. Cancelled instances show a new **Cancelled** status alongside Started, Finished, and Failed.
> >
> > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#running-and-stopping-workflows)
> > >
> > > See Running and stopping workflows in the Integration Designer reference.
> >
> > All Deployments
>
> ***
>
> ### **Merge conflicts UX**
>
> > [card] Merge conflicts UX
> >
> > The merge branches experience has been improved with a redesigned merge modal, better form validation with detailed error messages, and keyboard support (submit with Enter). The conflict resolution diff viewer now uses a new CodeMirror theme that matches the Monaco editor styling for a consistent visual experience.
> >
> > All Deployments
>
> ***

> [tab] Bug fixes
>
> ## Bug fixes
>
> ### AI Platform
>
> | Issue | Description |
> | - | - |
> | Custom Agent WebSocket stability | Fixed WebSocket 1006 abnormal closure for Custom Agent nodes with large payloads by upgrading AI SDK to handle Spring Framework 7's 64KB frame aggregation limit |
> | Azure OpenAI structured output | Fixed silent hang on Azure OpenAI for Custom Agents, Intent Classification, and Recommended Prompts when the response JSON schema lacked title and description fields |
> | Custom Agent node stuck | Fixed Custom Agent node getting stuck in running state |
> | MCP tool updates not working | Fixed an issue where updating tools on an existing MCP Server did not persist changes |
> | KB append performance | Fixed slow execution of the Append Knowledge Base node |
> | KB chunking on append | Fixed an issue where appended content via JSON in the Update Knowledge Base node was not chunked |
> | REST node with base64 certificate | Fixed error when running a workflow with a REST node using a REST system with a base64 certificate |
> | Workflow dependencies copy | Fixed dependencies not being copied for already-copied workflows |
>
> ### Core Platform
>
> | Issue | Description |
> | - | - |
> | Import pipeline issues | Fixed API issues in the import pipeline |
> | Enum CSV import losing changes | Fixed an issue where importing enumerations via CSV on committed resources did not update the resource modified date, causing changes to appear lost |
> | Data model duplicate key on import | Fixed a MongoDB duplicate key error when importing data model slices with duplicate entries |
> | Config params page not loading | Fixed GET config params endpoint not being called when accessing the Configuration Parameters page |
> | Enum default values dropdown | Fixed only first-level enum objects being displayed in the default values dropdown |
> | Data model loading state | Fixed user getting stuck in loading state after an error on data model keep operation |
>
> ### UI & Renderers
>
> | Issue | Description |
> | - | - |
> | Select component clear icon | Fixed misaligned clear icon on Select components in both Angular and React renderers |

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > **Self-hosted deployments:** FlowX 5.7.0 introduces the Organization ID as a mandatory configuration on all services. See the [deployment guidelines](./deployment-guidelines-v5.7) for complete upgrade instructions.
>
> ### Compatibility
>
> > [card] [Upgrade path](./deployment-guidelines-v5.7#supported-upgrade-paths)
> >
> > See the deployment guidelines for supported upgrade paths from 5.1.x LTS, 5.2–5.4, and 5.5–5.6.
>
> > [card] [Component versions](./deployment-guidelines-v5.7#component-versions)
> >
> > See the deployment guidelines for the full component version matrix and third-party dependency support.


# Deployment guidelines v5.8.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/deployment-guidelines-v5.8

Component versions, environment variables, and configuration changes for FlowX.AI 5.8.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.106.0** | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 |
| **admin** | **10.93.0** | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 |
| **designer** | **10.181.0** | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 |
| **cms-core** | **10.67.0** | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 |
| **scheduler-core** | **10.53.0** | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 |
| **events-gateway** | **10.55.0** | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 |
| **notification-plugin** | **10.64.0** | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 |
| **document-plugin** | **10.75.0** | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 |
| **task-management-plugin** | **10.66.0** | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 |
| **data-search** | **10.52.0** | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 |
| **audit-core** | **10.63.0** | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 |
| **advancing-controller** | **10.55.0** | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 |
| **integration-designer** | **10.128.0** | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 |
| **application-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **runtime-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **data-sync** | **10.58.0** | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 |
| **authorization-system** | **10.77.0** | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 |
| **nosql-db-runner** | **10.56.0** | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 |
| **email-gateway** | **10.56.0** | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 | - |
| **organization-manager** | **10.53.0** | 10.44.0 | 10.26.1 | 10.19.2 | - | - |
| **webhook-gateway** | **10.25.0** | 10.15.0 | 10.1.1 | - | - | - |
| **license** | **10.46.0** | 10.36.0 | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |

### Plugins

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 |
| **ai-platform-ai-assistant** | **10.7.0** | 10.6.2 | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **ai-platform-ai-developer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-connected-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-knowledge-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agents** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-conversations** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-tenants** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-analyst** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-designer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agent-builder** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-binaries** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **embedder** | **10.7.0** | 10.6.2 | - | - | - |
| **knowledgebase-rag** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **knowledgebase-indexer-v2** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **mcp** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **doc-parser** | **10.7.0** | 10.6.2 | 10.5.1 | - | - |
| **web-crawler** | **10.3.5** | 10.3.2 | - | - | - |
| **data-privacy** | **10.1.0** | 10.0.8 | - | - | - |
| **speech-to-text** | 10.3.3 | 10.3.3 | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | - | - | - |

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.8.0 | Keycloak | 26+ |
| 5.8.0 | Kafka | 3.8 - 3.9 |
| 5.8.0 | PostgreSQL | 16 - 17 |
| 5.8.0 | Oracle Database | 21c, 23ai |
| 5.8.0 | MongoDB | 7 - 8 |
| 5.8.0 | Redis | 7.4 - 8.0 |
| 5.8.0 | Elasticsearch | 8 |
| 5.8.0 | Angular (Web SDK) | 20 |
| 5.8.0 | React (Web SDK) | 18.x |

***

## Self-hosted deployment changes

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **5.7.0** | Supported | Standard upgrade. |
| **5.1.x LTS** | Supported | Direct upgrade from 5.1.x to 5.8.0 is supported. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

***

## Kafka integration changes

### New Kafka topics

| Topic | Producer | Producer env var | Consumer | Consumer env var |
| - | - | - | - | - |
| `ai.flowx.license.events.v1` | organization-manager | `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | license | `KAFKA_TOPIC_LICENSE_IN_EVENTS` |
| `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | admin | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` | knowledgebase-indexer-v2 | n/a (Python constant) | embedder | n/a (Python constant) |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` | embedder | n/a (Python constant) | knowledgebase-indexer-v2 | n/a (Python constant) |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | (no env var; resolved from `kafka.topic.naming.*`) | document-plugin | `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` |

**License lifecycle events** are delivered from FlowX SaaS to the on-prem license service.

**Custom-component correction requests** complement the existing process / business-rule / reusable-template / ui-flow correction topics that the admin orchestrator already consumed.

**UI Flow multi-file upload** sends a single bulk command to document-plugin in place of the per-file pattern. The plugin persists each file in the session, emits one SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) at the end of the batch via events-gateway, and forwards per-file results to the existing `ai.flowx.core.trigger.ui-flow.update.v1` topic.

**KB embedding-request / embedding-response** replace the previous gRPC `EmbedderService` path (`BulkGenerateEmbeddings` / `GenerateEmbeddings`); the indexer now publishes one embedding job per chunk and the embedder writes points to Qdrant directly, emitting `KbStoreEntryStateChanged` once all chunks for an entry are persisted.

> [!NOTE]
>
> The two `core-services` topic names (`license.events`, `application-version.correction-after-app-operation.custom-component.request`) resolve from the standard `${kafka.topic.naming.prefix}` / `${kafka.topic.naming.suffix}` machinery: default prefix `ai.flowx.` (empty environment segment), default suffix `.v1`. Operators that want an environment-prefixed topic name (e.g., `ai.flowx.dev.license.events.v1`) set `kafka.topic.naming.environment` globally rather than overriding individual topics. The two AI Platform topics are hard-coded constants in the indexer and embedder and do not participate in the prefix machinery.

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX. Initialized with the `notset` sentinel; replace it with the value FlowX provides before the license service starts. Type changed from UUID to String in 5.8.0. | `notset` | license |
| `KAFKA_CONSUMER_GROUPID_LICENSE_EVENTS` | Kafka consumer group used by the license service to receive license events. | `license-events` | license |
| `KAFKA_CONSUMER_THREADS_LICENSE_EVENTS` | Listener container concurrency for the license-events consumer. | `1` | license |
| `KAFKA_TOPIC_LICENSE_IN_EVENTS` | License events topic consumed by the license service. | `ai.flowx.license.events.v1` | license |
| `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | Same topic, producer-side binding on organization-manager. | `ai.flowx.license.events.v1` | organization-manager |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | Custom-component correction-request topic, producer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` | Same topic, consumer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | admin |
| `MANAGEMENT_HEALTH_REDIS_TIMEOUT` | Spring Boot Actuator timeout for the Redis health indicator (in ms). | `5000` | all services using Redis |
| `SPRING_CACHE_REDIS_PERSISTENCEKEYPREFIX` | Prefix applied to Redis keys for the advancing-controller cache. | `flowx:core:cache:advancing-controller:` | advancing-controller |
| `REDIS_COMMAND_TIMEOUT` | Redis command timeout in ms. Fail-fast during master failover. Bound via `${REDIS_COMMAND_TIMEOUT:5000}` placeholder on `spring.data.redis.timeout`. | `5000` | all services using Redis |
| `REDIS_CONNECT_TIMEOUT` | Redis connection establishment timeout in ms. Bound via `${REDIS_CONNECT_TIMEOUT:5000}`. | `5000` | all services using Redis |
| `REDIS_POOL_MAX_ACTIVE` | Maximum number of active Redis connections in the pool. | `10` | all services using Redis |
| `REDIS_POOL_MAX_IDLE` | Maximum number of idle Redis connections retained in the pool. | `5` | all services using Redis |
| `REDIS_POOL_MIN_IDLE` | Minimum number of idle Redis connections kept warm in the pool. | `1` | all services using Redis |
| `REDIS_POOL_MAX_WAIT` | Maximum time to wait for an available connection from the pool, in ms. | `2000` | all services using Redis |
| `FLOWX_METRICS_STUCKCHECKINTERVALMS` | Interval at which the stuck-events metric scheduler runs (ms). Bound from the inline `@Value("${flowx.metrics.stuck-check-interval-ms:60000}")` default; not in `application.yml`. | `60000` | advancing-controller |
| `FLOWX_METRICS_STUCKTHRESHOLDMINUTES` | Age threshold (in minutes) above which an advancing event is considered stuck. Bound from `@Value("${flowx.metrics.stuck-threshold-minutes:5}")`. | `5` | advancing-controller |
| `FLOWX_DATAPRIVACY_BASEURL` | Base URL for the new Data Privacy service. Required when any AI workflow node enables the Personal Information Guard. | `http://data-privacy:80` | integration-designer |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60` | integration-designer |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. Producer-side is the matching `kafka.topic.session.upload.bulk.out` on process-engine, which resolves from the standard naming machinery. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | document-plugin |

### Removed environment variables

| Environment Variable | Replaced by | Component |
| - | - | - |
| `FLOWX_SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Removed with the move to single-pod scheduler execution (plat-1549, `commons-scheduler-lib`). No replacement; only one scheduler pod runs now. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_ENABLED` | Same. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_PROVIDER` | Same. | application-manager, license |
| `SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Same. | integration-designer, process-engine |

***


# FlowX.AI 5.8.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/v5.8.0-may-2026

Runtime authorization overhaul, UI Flow permissions, Custom Components in Processes, new theme components, Angular bulk file upload, and webhook provider adapters.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

Sharing a FlowX solution used to mean handing out admin keys. **5.8.0 changes that.** The AI Developer now ships the React component you wished you'd had time to build, PII never reaches your LLM by accident, and you can finally invite a reviewer without giving them the platform.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html)

### What changed since 5.7.0

| 5.7.0 | 5.8.0 |
| - | - |
| End-user access management with org-level roles and groups | + **Runtime authorization** with project-version-scoped roles, groups, and attribute-based assignment |
| UI Flows accessible to any runtime user | + **UI Flow permissions**: assign roles per UI Flow, evaluated at runtime |
| Custom Components in UI Flows only (Phase 1, React) | + **Custom Components in Processes** with shared data model, input/output mappings, and AI Developer generation |
| Built-in UI components | + **Tooltip, Markdown, Progress Bar, Separator** as new theme components |
| React-only multi-file upload | + **Angular SDK bulk file upload** |
| Generic webhook gateway | + **Webhook provider adapters** (Slack, with HMAC signing-secret validation) |
| Oracle Database (basic SQL editor) | + **Richer SQL autocomplete** in the Monaco editor: operators, schema-aware tables/columns, and `:paramName` interpolations |
| No personal-information guardrails on AI workflow nodes | + **PII Guard** with input/output scans, sensitivity presets, and an entity catalog |

***

**What's new?**

> [tab] Platform
>
> 🔐 [**Runtime authorization**](#runtime-authorization) - Project-scoped roles, end-user groups in FlowX, and Solutions → Share flow\
> 📋 [**UI Flow permissions**](#ui-flow-permissions) - Role-based UI Flow visibility with runtime enforcement

> [tab] Builders
>
> 🧩 [**Custom Components in Processes**](#custom-components-in-processes) - Bundled CCs in Process User Tasks with shared data model\
> 🎨 [**New UI components**](#new-ui-components) - Tooltip, Markdown, Progress Bar, Separator\
> 📥 [**Angular bulk file upload**](#angular-bulk-file-upload) - Multi-file upload component for the Angular SDK\
> 📦 [**UI Flow multi-file upload backend**](#ui-flow-multi-file-upload-backend) - Single bulk endpoint and one completion SSE event for batch uploads\
> 🪝 [**Webhook provider adapters**](#webhook-provider-adapters) - Slack inbound webhook support with HMAC signing\
> 🗄️ [**Richer SQL autocomplete**](#richer-sql-autocomplete) - Monaco editor enhancements for the Oracle data source SQL editor\
> 🧱 [**Data source UX redesign**](#data-source-ux-redesign) - Tile-based creation, type filters, unified settings, save with incomplete config\
> ➕ [**Context menu adds UI components in Processes**](#context-menu-adds-ui-components-in-processes) - Right-click Add UI component in Process User Tasks and Reusable UI Templates\
> 👆 [**Pointer cursor on actionable elements**](#pointer-cursor-on-actionable-elements) - Web renderers show pointer on action-bound components

> [tab] AI Platform
>
> 🛡️ [**PII Guard**](#pii-guard) - Personal information identification on AI inputs\
> 🤖 [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent now drafts Custom Component code\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - System metadata keys, Kafka indexer→embedder, Qdrant export/delete, error handling\
> 🌐 [**Web Crawler multi-URL filters**](#web-crawler-multi-url-filters) - Multiple URL filters per crawler config

### **Runtime authorization**

> [card] Runtime authorization overhaul
>
> > [tab] Overview
> >
> > **Before 5.8.0:** a role on a user matched every project that role appeared in. **Now:** roles live at the project version, sharing is explicit, and Designer users still bypass runtime so they can demo without standing up test accounts.
> >
> > Runtime access is reorganized around the project. Roles live at the **project version**, each org has a managed catalog of **end-user groups**, and access flows through a **Solutions → Share** modal. FlowX retains authentication and external-IDP federation in Keycloak; runtime roles, end-user groups, and project-scoped sharing live in FlowX itself, evaluated by a custom runtime authorization service tuned for the volume of runtime permission checks. SpiceDB remains the design-time permission engine for Designer access.
> >
> > > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> > >
> > > See Setup guides → Access management → Runtime authorization.
>
> > [tab] Key Features
> >
> > > [card] Project-scoped roles
> > >
> > > Each project version declares the runtime roles required to operate it. Roles are org-level entities, defined once and reusable across projects and libraries.
> >
> > > [card] Default `user` role on creation
> > >
> > > New projects spawn with a default `user` role so a fresh project is reachable on day one without extra wiring.
> >
> > > [card] Sharing from Solutions
> > >
> > > The Solutions page gains a **Share** modal. Pick a user or end-user group, assign a role, and the user can launch the solution at runtime.
> >
> > > [card] End-user groups in FlowX
> > >
> > > Groups previously managed in Keycloak now live in FlowX. Recommended pattern: an "All End Users" group per single-role solution; one group per role for multi-role solutions.
> >
> > > [card] Process swimlane roles
> > >
> > > BPMN swimlanes assign view, execute, and self-assign permissions per role.
> >
> > > [card] Designer-user bypass
> > >
> > > Designer users can run any project they have designer access to without holding a runtime role; they auto-receive view, execute, and self-assign on every swimlane.
> >
> > > [card] Active Policy gate
> > >
> > > The Share modal lists only roles defined in the build set as **Active Policy** for the project. Roles defined in a non-active build do not appear until promoted.
>
> > [tab] Architecture
> >
> > The 5.8.0 release introduces a clear split between authentication and runtime authorization:
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Authentication, sessions, MFA | Keycloak | Unchanged |
> > | External IDP federation | Keycloak | Configured per organization |
> > | User attributes (business filters) | Keycloak | Source of truth for token claims |
> > | Runtime roles | FlowX (custom CAS) | Defined per project version, evaluated at runtime |
> > | End-user groups | FlowX (custom CAS) | Replaces Keycloak group management |
> > | Project-scoped sharing | FlowX (custom CAS) | Solutions → Share modal |
> > | Design-time permissions | FlowX SpiceDB | Designer UI access; unchanged from prior releases |
> >
> > A `designer-user` Keycloak attribute is auto-managed on each user (`true` for designer users, `false` for end-users), with a mapper on the `flowx-platform-authenticate` client so the engine can check it cheaply on the access token.
>
> > [tab] Migration
> >
> > > [!WARNING]
> > >
> > > **Sharing settings do not export between environments or workspaces.** Configure sharing per environment as a deliberate step when promoting a project to a higher environment.
> >
> > Sharing data does not travel with the project export, so promoting a build from one environment to another (for example, dev to staging) requires a sharing pass in the target environment. Treat it as an explicit step in your deployment checklist.
> >
> > Existing FlowX organizations migrate as follows:
> >
> > * Roles previously assigned directly to users continue to work for backward compatibility while you rebuild assignments under the project-scoped model.
> > * End-user groups configured in Keycloak are migrated into FlowX and become the authoritative source going forward.
> > * Existing UI Flows receive the project-level **User** role automatically as their default allowed role on upgrade. See the [UI Flow permissions](#ui-flow-permissions) section for next steps.
>
> All Deployments

### **UI Flow permissions**

> [card] UI Flow permissions
>
> > [tab] Overview
> >
> > **Before 5.8.0:** every UI Flow was reachable by anyone with runtime access. **Now:** each UI Flow carries its own allow-list and components inside it can be hidden or disabled per role.
> >
> > Each UI Flow now carries a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API. Inside a UI Flow session, individual components can be hidden or disabled by permission-based rules evaluated at runtime against the user's permission set.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> > >
> > > See UI Flows → UI Flow permissions.
>
> > [tab] Key Features
> >
> > > [card] Permissions page
> > >
> > > A new **Settings → Permissions** page in the UI Flow editor lets you assign one or more runtime roles to each UI Flow.
> >
> > > [card] Default role on creation
> > >
> > > New UI Flows receive the project-level **User** role by default so they are reachable on day one; tighten the list before deploying.
> >
> > > [card] Per-component hide/disable
> > >
> > > Components can be hidden or made readonly based on the user's runtime permissions, using the same hide/disable rule machinery as JavaScript expressions.
> >
> > > [card] Permission toast
> > >
> > > Users without the required role see a permission toast in the Designer-hosted runtime preview; the deployed app returns 403 from the start endpoint.
> >
> > > [card] Input-parameter validation
> > >
> > > Input parameters are validated against the UI Flow's input schema before the session is created.
> >
> > > [card] Travels with import/export
> > >
> > > Allowed roles are saved on the UI Flow resource and travel with project export/import.
>
> > [tab] Migration
> >
> > UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.
>
> All Deployments

### **Custom Components in Processes**

> [card] Custom Components in Processes
>
> > [tab] Overview
> >
> > **Before 5.8.0:** Custom Components only ran in UI Flows. **Now:** drag one onto a Process User Task and the React SDK applies the input/output mappings at runtime.
> >
> > Bundled Custom Components, previously only usable in UI Flows, now render in **Process User Tasks**. Each Custom Component carries its own **data model** with explicit input and output slices, and you map process data into and out of the component at each use site. Renderer support ships in the React SDK.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components#using-custom-components-in-process-user-tasks)
> > >
> > > See Custom Components → Using Custom Components in Process User Tasks.
>
> > [tab] Key Features
> >
> > > [card] Process User Task host
> > >
> > > Drag a Custom Component onto a Process User Task layout the same way you do in UI Flows.
> >
> > > [card] Custom Component data model
> > >
> > > Each Custom Component declares its own data model. The Designer keeps input and output slices isolated so the component contract is clear at every use site.
> >
> > > [card] INPUT mappings
> > >
> > > Map process data attributes onto the Custom Component's input slice at runtime, so the component receives only the data it declared.
> >
> > > [card] OUTPUT mappings
> > >
> > > When the component triggers an action, the React SDK applies the configured OUTPUT mappings before piping `saveData` back to process variables.
> >
> > > [card] Test with sample inputs
> > >
> > > The Custom Component editor lets you fill input params with sample data for in-Designer preview, mirroring the UI Flow test flow.
> >
> > > [card] Import and export
> > >
> > > Custom Components export and import alongside the data model and mappings so a component travels intact between projects.
>
> > [tab] Limitations
> >
> > Phase 1 limitations from 5.7.0 still apply: React SDK only (no Angular renderer), pre-defined dependency set (React, Emotion, Lodash, Axios, date-fns), browser-side bundling, and client-side rendering only. See the [Custom Components limitations](/5.9/docs/building-blocks/reusable-resources/custom-components#limitations-phase-1) section.
>
> All Deployments

### **New UI components**

> [card] New UI components
>
> Four new theme components ship with renderer parity across React, Angular, and Android SDKs.
>
> > [card] [Tooltip](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Contextual hint anchored to any UI element. Configurable text (static, local variable, or computed expression), position handling, and an optional icon.
>
> > [card] [Markdown](/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown)
> >
> > Render Markdown content from a static string or computed expression, with localization formatting for numbers, dates, and currency. Six heading levels and link styling are theme-driven.
>
> > [card] [Progress Bar](/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar)
> >
> > Visual progress indicator. Set a value between `0` and `1` from a static value, local variable, or computed expression.
>
> > [card] [Separator](/5.9/docs/building-blocks/ui-designer/ui-component-types/separator)
> >
> > Visual divider with theme-driven color. Adjustable height for layout spacing.
>
> All four are exposed in the **Theme Admin** sidebar so theme overrides cascade through templates.
>
> All Deployments

### **Angular bulk file upload**

> [card] Angular bulk file upload
>
> > [tab] Overview
> >
> > The **Multiple File Upload** component (`BULK_FILE_UPLOAD`), previously available only in the React SDK, now ships in the Angular SDK with the same drag-and-drop area and theming. Existing UI Flows that use the component render across React and Angular containers without configuration changes.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> > >
> > > See the Multiple File Upload component reference.
>
> > [tab] Key Features
> >
> > > [card] Renderer parity
> > >
> > > Same component, same configuration, same theming across React and Angular containers.
> >
> > > [card] Drag-and-drop area
> > >
> > > Drop zone with click-to-browse fallback in both renderers.
> >
> > > [card] Theme-driven
> > >
> > > The component picks up theme overrides for typography, colors, and spacing the same way as built-in components.
> >
> > > [card] No flow changes needed
> > >
> > > UI Flows authored before 5.8.0 render in the Angular SDK without edits.
>
> All Deployments

### **UI Flow multi-file upload backend**

> [card] UI Flow multi-file upload backend
>
> > [tab] Overview
> >
> > Multi-file uploads from UI Flows now use a dedicated bulk endpoint and a single completion event in place of the per-file pattern. The upload action accepts a list of temp-file IDs in one request and the SDK receives a single SSE frame when the batch is persisted.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload#ui-flow-upload-flow)
> > >
> > > See Multiple file upload → UI Flow upload flow.
>
> > [tab] Key Features
> >
> > > [card] Single bulk endpoint
> > >
> > > `POST /ui-flow/{uiFlowSessionId}/upload-multiple` accepts a list of temp-file IDs and returns a server-generated `uploadBatchId`.
> >
> > > [card] Single completion event
> > >
> > > One SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) delivers per-file results once the batch is persisted.
> >
> > > [card] New Kafka topic
> > >
> > > `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` carries the bulk command from process-engine to document-plugin.
> >
> > > [card] Session variable mapping
> > >
> > > Per-file results are stored as a list under the upload action's `responseKey` in the UI Flow session.
>
> All Deployments

### **Webhook provider adapters**

> [card] Webhook provider adapters
>
> > [tab] Overview
> >
> > Inbound webhook registrations now select a **provider**: `GENERIC` or `SLACK`. The Slack adapter performs HMAC-SHA256 signature validation against the Slack signing secret on every request, including the `X-Slack-Request-Timestamp` skew check (5 minutes). Provider-segmented URLs (`/webhooks/incoming/slack/...`) keep generic and provider-specific registrations isolated. Future providers plug in behind the same `InboundProviderAdapter` interface without changing the URL contract.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#provider-adapters)
> > >
> > > See Incoming webhooks → Provider adapters.
>
> > [tab] Key Features
> >
> > > [card] Slack signature validation
> > >
> > > HMAC-SHA256 on `X-Slack-Signature`, with timestamp skew enforced
> >
> > > [card] Slack URL-verification handshake
> > >
> > > The gateway answers Slack's `url_verification` challenge automatically
> >
> > > [card] Provider-segmented URLs
> > >
> > > `/webhooks/incoming/{provider}/...` keeps providers isolated; mismatch returns 400
> >
> > > [card] Independent secret rotation
> > >
> > > Rotate the provider signing secret without touching the FlowX API key
> >
> > > [card] Settings tab
> > >
> > > Provider + signing secret moved to a dedicated Settings tab on the webhook system
> >
> > > [card] Pluggable
> > >
> > > New providers add an adapter and an enum value; no URL or registration schema changes
>
> All Deployments

### **Richer SQL autocomplete**

> [card] Richer SQL autocomplete
>
> > [tab] Overview
> >
> > The Monaco editor on the Oracle Database data source now ships with a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `:paramName` interpolations resolved from the parameters panel.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database#sql-editor)
> > >
> > > See the Oracle Database SQL editor documentation.
>
> > [tab] Key Features
> >
> > > [card] Keywords and operators
> > >
> > > Full SQL language definition powers keyword highlighting and completion.
> >
> > > [card] Schema-aware suggestions
> > >
> > > Tables and columns parsed from the saved schema context appear in completion lists.
> >
> > > [card] Parameter interpolation
> > >
> > > `:paramName` placeholders resolve against the parameters panel for inline preview.
> >
> > > [card] Editor consistency
> > >
> > > Matches the editor experience used by other code surfaces in the Designer.
>
> All Deployments

### **Data source UX redesign**

> [card] Data source UX redesign
>
> > [tab] Overview
> >
> > The Data Sources resource page is rebuilt around a tile-based creation flow and a unified details view. Each data source type has its own icon and a dedicated tile in the **New Data Source** modal, with a search box that filters tiles as you type. The list view shows the type next to each entry and adds a type filter so you can scope the list by connector. Settings panels for every data source type are normalized to the same card-based layout.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer reference for data source configuration.
>
> > [tab] Key Features
> >
> > > [card] Tile-based creation modal
> > >
> > > The **New Data Source** modal lists every connector type as a searchable tile, replacing the previous type dropdown.
> >
> > > [card] Type icons in the list
> > >
> > > Each entry in the data sources list shows the connector's icon and type, so a long list is easier to scan.
> >
> > > [card] Filter by type
> > >
> > > Filter the list to a specific connector type (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.) without scrolling.
> >
> > > [card] Unified settings layout
> > >
> > > Every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
> >
> > > [card] Save with incomplete config
> > >
> > > Create and save a data source even when some fields (credentials, endpoints) are not yet available. You can reference the data source in workflows and processes immediately and finish the configuration later — the data source will only operate at runtime once required fields are filled in.
>
> All Deployments

### **PII Guard**

> [card] Personal Information Guard
>
> > [tab] Overview
> >
> > **Before 5.8.0:** data-sensitive customers couldn't enable AI workflow nodes at all. **Now:** every AI node carries a per-node guardrail with sensitivity presets, scan directions, and a fail-closed contract.
> >
> > AI workflow nodes gain a per-node guardrail that detects and replaces personal information before it reaches the LLM and, optionally, scans LLM output before it flows downstream. The guard runs against the new **Data Privacy** service, configured per node with sensitivity presets, scan directions, and an entity catalog organized into Universal, Regional EN, and Regional RO scopes. Iteration 1 covers Custom Agent, Intent Classification, Extract Data from File, and all AI Text, Document, Image, and Data Operations, including Document Generation.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See Personal Information Guard.
>
> > [tab] Key Features
> >
> > > [card] Per-node toggle
> > >
> > > Enable on any AI node. Choose a sensitivity preset (Strict / Balanced / Relaxed) or set a custom threshold.
> >
> > > [card] Input and output scans
> > >
> > > Redacts inputs and `systemPrompt` before the LLM call; optionally scans LLM output before it leaves the node.
> >
> > > [card] File redaction
> > >
> > > Document and image nodes get a redacted source artifact uploaded back to the same storage; the file binding is swapped automatically.
> >
> > > [card] Entity catalog
> > >
> > > 24 entity types (email, phone, IBAN, etc.) grouped under Universal, Regional EN, and Regional RO. Modal supports search and section-level Select All.
> >
> > > [card] System-prompt appender
> > >
> > > Custom Agent nodes get a non-editable system-prompt segment teaching the LLM how to handle `<PII type=.../>` placeholders.
> >
> > > [card] Fail-closed
> > >
> > > Any error from the Data Privacy service stops node execution and surfaces on the run log; no partially-redacted prompts reach the LLM.
> >
> > > [card] Run-log visibility
> > >
> > > Each scan reports status, per-entity detection counts, and (for file scans) original and redacted storage paths.
> >
> > > [card] New Data Privacy service
> > >
> > > Backed by Presidio. Configured via `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` on integration-designer.
>
> All Deployments

### **Knowledge Base enhancements**

> [card] Knowledge Base
>
> > [tab] Overview
> >
> > Knowledge Bases gain richer metadata and a more resilient indexing path. Stores and chunks expose system metadata fields you can filter on in the Test KB modal and the Custom Agent node, the indexer and embedder communicate over Kafka instead of synchronous calls, and the Update Knowledge Base node can ingest files by path from inside a workflow.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See Knowledge Base → Overview.
>
> > [tab] Key Features
> >
> > > [card] System metadata on stores
> > >
> > > Filter entries by `Source` (Manual or Workflow), `Uploaded`, `Doc name`, `Doc type`, `Doc pages`, and `Store origin`
> >
> > > [card] System metadata on chunks
> > >
> > > Filter chunks by `Chunk counter`, `Chunk type`, `Chunk section`, `Chunk page start`, and `Chunk entry`
> >
> > > [card] Kafka between indexer and embedder
> > >
> > > Replaces the previous synchronous gRPC path; per-chunk embedding requests flow through `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1`
> >
> > > [card] Delete chunks from Qdrant
> > >
> > > Indexer forwards a delete job to the embedder, which removes matching points from Qdrant when an entry is deleted
> >
> > > [card] File path mode in Update KB node
> > >
> > > The Update Knowledge Base node accepts `contentType: FILE_PATH` so workflows can ingest content uploaded earlier in the run
> >
> > > [card] Doc pages in agent stream
> > >
> > > Custom Agent streaming responses include `doc_pages` and chunk metadata (counter, type, section, page start) for richer trace and debug
>
> All Deployments

### **Web Crawler multi-URL filters**

> [card] Web Crawler multi-URL filters
>
> > [tab] Overview
> >
> > The Web Crawler node now accepts up to 20 URL filter patterns per crawler configuration. Open the **URL Filters** modal on the Web Crawler node, add one row per pattern, and the crawler restricts its breadth-first traversal to URLs that match any of the configured filters.
> >
> > > [card] [Documentation](/5.9/setup-guides/web-crawler-setup)
> > >
> > > See the Web Crawler setup guide.
>
> > [tab] Key Features
> >
> > > [card] Up to 20 patterns per crawler
> > >
> > > Add one row per pattern in the URL Filters modal; deep crawls match any pattern.
> >
> > > [card] Replaces single-string filter
> > >
> > > The previous single-string filter is superseded by the new multi-pattern array. Existing crawlers are migrated automatically.
> >
> > > [card] Breadth-first scoping
> > >
> > > Filters apply to the crawler's breadth-first traversal so deep crawls stay within the intended scope.
> >
> > > [card] Per-pattern tuning
> > >
> > > Combine narrow and broad patterns in one configuration to handle multi-section sites without spawning multiple crawlers.
>
> All Deployments

### **AI Developer generates Custom Components**

> [card] AI Developer generates Custom Components
>
> > [tab] Overview
> >
> > **Before 5.8.0:** the AI Developer wrote business rules and JS expressions. **Now:** it ships entire React Custom Components — JSX, CSS, `package.json`, and sample input data — in one prompt.
> >
> > The AI Developer pre-built agent gains a **Generate Custom Component** action and an **Edit Custom Component** action. From the Designer's AI command center, describe the component you want, and the agent returns a complete React bundle (JSX, CSS, `package.json`, and sample input data) that you can preview, accept, or iterate on. The same conversation can edit existing components.
> >
> > > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> > >
> > > See AI Developer → Pre-built agents.
>
> > [tab] Key Features
> >
> > > [card] Generate from natural language
> > >
> > > Describe a component in plain language; receive JSX, CSS, `package.json`, and sample input data in one response.
> >
> > > [card] Sample input field
> > >
> > > A dedicated input field lets you provide preview data so the generated component renders meaningfully on first run.
> >
> > > [card] Edit existing components
> > >
> > > Iterate on a generated or hand-authored component through the same conversation. The agent keeps the component context.
> >
> > > [card] Inline preview
> > >
> > > The Designer's Preview area renders the generated bundle next to the conversation so you can validate before saving.
> >
> > > [card] Dependency summary
> > >
> > > A new dependency summary panel surfaces the npm packages the agent included in `package.json`.
> >
> > > [card] Keep / Discard
> > >
> > > Accept the generated bundle into the workspace or discard it without leaving the conversation.
>
> > [tab] Limitations
> >
> > The first iteration generates the component code, styles, and input parameters. Wiring component actions to host-side handlers (Process or UI Flow actions) is not yet inferred — connect actions manually after accepting the generated bundle.
>
> All Deployments

### **iframe logout postMessage contract**

> [card] iframe logout postMessage
>
> The runtime SaaS app now notifies an iframe parent when a user logs out. When the parent passes a `parentOrigin` query parameter on the `/{orgCode}/logout` URL, the runtime posts `{ type: 'logout-success' }` to `window.parent` immediately before the sign-out redirect. Host applications that embed the FlowX runtime in an iframe can listen for this message and react (clear local state, navigate, surface a UI cue) without polling the iframe URL.
>
> All Deployments

### **Context menu adds UI components in Processes**

> [card] Right-click Add UI component in Processes and Reusable UI Templates
>
> The right-click contextual menu for adding a UI component, previously available only in UI Flows, now works in **Process User Tasks** and **Reusable UI Templates** as well. Right-click a node in the components hierarchy panel to insert any allowed child component without dragging from the palette. Copy and paste styles are also exposed from the same menu.
>
> All Deployments

### **Pointer cursor on actionable elements**

> [card] Pointer cursor on actionable elements
>
> Web renderers now switch the cursor to a pointer when hovering over any UI component bound to an action, matching standard web affordances. No configuration change is required — the new behavior applies automatically to elements that already declare an action role.
>
> All Deployments

### **"Process Data" → "Local Variables" rename**

> [card] Process Data renamed to Local Variables
>
> In the UI Designer, the **Process Data** label is now displayed as **Local Variables** when you are editing a UI Flow or a Reusable UI Template. Process editing is unchanged and continues to use **Process Data**. The data source key and binding behavior are identical; only the user-visible label changed, so existing flows continue to work without any update.
>
> All Deployments

### **License billing guards**

> [card] License billing guards
>
> The license service no longer creates billing plans for periods past an organization's subscription end date. This prevents stale plan rows from accumulating after a subscription expires and aligns the on-prem billing trail with the SaaS-side license lifecycle.
>
> Self-Hosted

### **Speech-to-text and Web Crawler in AI consumption**

> [card] Speech-to-text and Web Crawler in AI consumption
>
> AI consumption tracking now includes Speech-to-text and Web Crawler workflow nodes alongside the existing AI Text, Document, Image, and Data Operations. Organizations on AI consumption-based plans see usage and billing reflected for these nodes from 5.8.0 onward.
>
> All Deployments

***

## Shipped by

This release is the work of the FlowX engineering team — backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.8.0](./deployment-guidelines-v5.8).


# Deployment guidelines v5.9.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9

Component versions, environment variables, and configuration changes for FlowX.AI 5.9.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

> [!NOTE]
>
> **Upgrading from 5.1.x LTS?** This page describes the steady-state 5.9.0 deployment. For the architecture delta, deprecation list, and upgrade steps, see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Deployment packaging.** 5.9.x is the last LTS release distributed as a multi-chart deployment, where each FlowX service is installed from its own Helm chart.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

The following tables list component versions per FlowX.AI release. Verify your installed versions against the 5.9.0 column in **FlowX.AI Designer → Platform Status**.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **process-engine** | 10.135.0 | 10.106.0 | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 |
| **admin** | 10.116.0 | 10.93.0 | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 |
| **designer** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 |
| **cms-core** | 10.86.0 | 10.67.0 | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 |
| **scheduler-core** | 10.70.0 | 10.53.0 | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 |
| **events-gateway** | 10.72.0 | 10.55.0 | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 |
| **notification-plugin** | 10.83.0 | 10.64.0 | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 |
| **document-plugin** | 10.94.0 | 10.75.0 | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 |
| **task-management-plugin** | 10.84.0 | 10.66.0 | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |
| **data-search** | 10.69.0 | 10.52.0 | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 |
| **audit-core** | 10.79.0 | 10.63.0 | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 |
| **advancing-controller** | 10.73.0 | 10.55.0 | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 |
| **integration-designer** | 10.162.0 | 10.128.0 | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 |
| **application-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **runtime-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **data-sync** | 10.81.0 | 10.58.0 | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 |
| **authorization-system** | 10.96.1 | 10.77.0 | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 |
| **nosql-db-runner** | 10.75.0 | 10.56.0 | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 |
| **email-gateway** | 10.74.0 | 10.56.0 | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 |
| **organization-manager** | 10.71.0 | 10.53.0 | 10.44.0 | 10.26.1 | 10.19.2 | - |
| **webhook-gateway** | 10.44.0 | 10.25.0 | 10.15.0 | 10.1.1 | - | - |
| **file-gateway** | 10.8.0 | - | - | - | - | - |
| **license** | 10.63.0 | 10.46.0 | 10.36.0 | - | - | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB**
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-native-sdk** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-theme** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-ui-toolkit** | 10.230.2 | - | - | - | - | - |
| **@flowx/core-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/core-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **react-saas** | 10.230.2 | - | - | - | - | - |
| **iOS renderer** | 10.4.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |
| **Android renderer** | 10.5.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |

The **react-saas** container app tracks the designer version.

### Plugins

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-knowledgebase-rag** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-embedder** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **doc-parser** | 10.9.0 | 10.7.0 | 10.6.2 | 10.5.1 | - | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-agent-builder** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **data-privacy** | 10.1.0 | 10.1.0 | 10.0.8 | - | - | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **evals-judge** | 10.1.1 | - | - | - | - | - |
| **speech-to-text** | 10.3.4 | 10.3.3 | 10.3.3 | - | - | - |
| **web-crawler** | 10.3.5 | 10.3.5 | 10.3.2 | - | - | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-gateway** | 10.7.0 | - | - | - | - | - |
| **ai-platform-ai-analyst** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-assistant** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **ai-platform-ai-designer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-developer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **di-platform** | 10.3.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **flowx-docs** | 5.9.0 | - | - | - | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - | - | - |
| **ai-observatory** | 10.3.2 | - | - | - | - | - |

***

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

***

## Kafka topics

### Document-plugin archive and extract listeners

5.9.0 exposes four Kafka topics for the document-plugin **archive** and **extract** operations. Both follow the encrypt/decrypt trigger and reply pattern: document-plugin consumes the `trigger.*.file` topic and process-engine consumes the matching `engine.receive.*.file.results` reply.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.archive.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.extract.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` | document-plugin | process-engine |

The four topic names are exposed as env vars on the document-plugin side (`KAFKA_TOPIC_FILE_ARCHIVE_IN`, `KAFKA_TOPIC_FILE_ARCHIVE_OUT`, `KAFKA_TOPIC_FILE_EXTRACT_IN`, `KAFKA_TOPIC_FILE_EXTRACT_OUT`). See [Documents plugin setup → File archive / File extract](/5.9/setup-guides/documents-plugin-setup#file-archive). Two new thread-pool entries are added: `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN` and `..._FILEEXTRACTIN`, both defaulting to `5`.

### Document-plugin encrypt and decrypt listeners

The **encrypt** and **decrypt** operations follow the same trigger-and-reply pattern: process-engine produces the `trigger.*.file` topic and document-plugin replies on the matching `engine.receive.*.file.results` topic.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | document-plugin | process-engine |

The topic names are exposed as env vars on the document-plugin side: `KAFKA_TOPIC_FILE_ENCRYPT_IN`, `KAFKA_TOPIC_FILE_ENCRYPT_OUT`, `KAFKA_TOPIC_FILE_DECRYPT_IN`, `KAFKA_TOPIC_FILE_DECRYPT_OUT`.

### Document-plugin session-upload listeners

Multi-file upload for UI flows routes uploaded files to the document-plugin for persistence. process-engine produces the trigger topic and document-plugin consumes it — `session` for a single upload session and `session.bulk` for batched multi-file uploads.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | process-engine | document-plugin |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | document-plugin |

The topic names are exposed on process-engine as `KAFKA_TOPIC_SESSION_UPLOAD_OUT` and `KAFKA_TOPIC_SESSION_UPLOAD_BULK_OUT`, and on document-plugin as `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN` and `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN`.

### AI Platform job topics

`integration-designer` dispatches asynchronous jobs to the standalone AI services over Kafka, using a request/response pair per service. Provision these topics when you deploy the corresponding AI service (see [AI components](#ai-components) above).

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.ai-platform.doc-parser.job.request.v1` | integration-designer | doc-parser |
| `ai.flowx.ai-platform.doc-parser.job.response.v1` | doc-parser | integration-designer |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | integration-designer | evals-judge |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | evals-judge | integration-designer |
| `ai.flowx.ai-platform.speech-to-text.job.request.v1` | integration-designer | speech-to-text |
| `ai.flowx.ai-platform.speech-to-text.job.response.v1` | speech-to-text | integration-designer |

On `integration-designer` the topic names are set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_REQUEST_OUT` and `..._RESPONSE_IN` (for example `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`). Each service also has a dead-letter topic — `ai.flowx.ai-platform.<service>.job.dlq.v1`, set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_DLQ_IN` — that integration-designer consumes for failed jobs.

### UI Flow runtime triggers

process-engine consumes two trigger topics that back the UI Flow runtime cache and expiration features. `update` invalidates a cached UI Flow when its definition changes; `expire` removes expired UI Flow runtime data.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer | process-engine |
| `ai.flowx.core.trigger.expire.ui-flow.v1` | scheduler-core | process-engine |

On process-engine these are set via `KAFKA_TOPIC_UIFLOW_UPDATE_IN` and `KAFKA_TOPIC_UIFLOW_EXPIRE_IN`; the producers expose `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`. The expire trigger uses the platform scheduler: when a UI Flow session is created, process-engine registers a delayed message with scheduler-core, which publishes it back to this topic at the expiry time. It is consumed by a dedicated consumer group (`KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE`, default `ui-flow-expire`).

### File and webhook process triggers

Two trigger topics let the file-gateway and webhook-gateway start or resume processes in process-engine. The **start-for-event** topic starts a process when a watched file arrives (file-gateway) or an incoming webhook fires (webhook-gateway); the **message event** topic resumes a running process that is waiting on an intermediate message catch event.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | file-gateway, webhook-gateway | process-engine |
| `ai.flowx.core.message.event.process.v1` | webhook-gateway | process-engine |

On the producers, the start-for-event topic is set via `KAFKA_TOPIC_TRIGGER_STARTFOREVENT_PROCESS_OUT` (file-gateway) and `KAFKA_TOPIC_PROCESS_START_OUT` (webhook-gateway); process-engine consumes it via `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`. The message event topic uses `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` on both webhook-gateway and process-engine. Like every service, file-gateway and webhook-gateway also publish to the shared audit topic `ai.flowx.core.trigger.save.audit.v1` via `KAFKA_TOPIC_AUDIT_OUT` (consumed by audit-core).

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Data-sync: Keycloak admin credentials

The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak on first run, using the Keycloak admin API. Configure the following on the data-sync job:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak` (the only supported provider). | `keycloak` | data-sync |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` | data-sync |
| `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` | data-sync |
| `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` | data-sync |
| `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Typically `admin-cli` for standard Keycloak deployments. Must be set explicitly. There is no default. | `-` | data-sync |

For full data-sync configuration, see [Data-sync job setup](/5.9/setup-guides/data-sync#openid-provider-configuration).

### Anonymous service account: shared client secret

5.9.x introduces a single shared service-account client, `flowx-anonymous-sa`, used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows. One client secret is reused across all consumers — it must be provided in two places.

**On `authorization-system`** — passed to Liquibase so the client is provisioned with the correct secret when FlowX manages Keycloak:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXANONYMOUSSA` | Client secret used by Liquibase to create the `flowx-anonymous-sa` client in the service-accounts realm at first boot. Required when `SECURITY_KEYCLOAKADMINENABLED=true`. | `-` | `authorization-system` |

**On every consuming service** — the Spring Security OAuth2 client registration for the `anonymousidentity` alias resolves the same secret at runtime:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Client secret for the `anonymousidentity` registration. **Must be the same value across every service** — it is a single shared service account. | `-` | `admin`, `application-manager`, `authorization-system`, `document-plugin`, `email-gateway`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `mock-server`, `nosql-db-runner`, `organization-manager`, `process-engine`, `scheduler-core`, `task-management-plugin`, `webhook-gateway` |

> [!WARNING]
>
> This is a secret. Store it in your secrets management solution (e.g., Kubernetes Secret, Vault) and reference it from there. Never commit it to version control.

For the Keycloak-side context (`flowx-anonymous-sa` client, `SA_FLOWX_ANONYMOUS` realm role, manual-configuration recipe for deployments without Keycloak admin access), see [Manual Keycloak configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).

### Knowledgebase-rag: Qdrant search tuning

Two env vars control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Defaults are tunable per environment.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. | `100` | knowledgebase-rag |
| `QDRANT_FUSION_LIMIT` | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker input. | `80` | knowledgebase-rag |

Raise both when recall is insufficient on very large or long-tailed Knowledge Bases. Lower them when Qdrant pods report memory pressure or filter-heavy queries time out.

### CORS handling: `APPLICATION_CORS_ALLOWORIGIN`

CORS is enforced at the application layer. Each backend service exposed via admin or public URLs reads its allowed-origin list from a single environment variable. Allowed methods, allowed headers, exposed headers, and credential handling are baked into each service's `application.yaml` with safe defaults. The 5.9.x default allow-headers set is `Accept, Content-Type, Authorization, Fx-Workspace-Id, Fx-Client-Host, Referer, User-Agent, Flowx-Platform, X-Fx-Anonymous-Session-Id, Fx-BuildId, Fx-AppId`, and `X-Fx-Anonymous-Session-Id` is exposed to the browser for anonymous runtime sessions. Only `APPLICATION_CORS_ALLOWORIGIN` is deployment-specific.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains (`https://*.yourcompany.com`). Must include every Designer, runtime renderer, and integration domain that calls FlowX APIs. | `-` | `admin`, `ai-gateway`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway` |
| `APPLICATION_CORS_EXPOSEDHEADERS` | Response headers exposed to browser JavaScript. The default carries the anonymous-session header; override only if you need to expose additional custom headers. | `X-Fx-Anonymous-Session-Id` | all services (shared security library) |

For migration guidance and the full list of removed NGINX CORS annotations, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

### Process-engine and integration-designer: native script engine

The default script engine for JavaScript and Python execution is a **native subprocess pool**. Scripts run in isolated Node.js and Python worker processes.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider | `native` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size | `16` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary | `/usr/bin/node` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS script execution timeout (ms) | `5000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a JS worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max JS input payload size (bytes) | `1048576` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size | `8` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary | `/usr/bin/python3` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python script execution timeout (ms) | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a Python worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max Python input payload size (bytes) | `1048576` | process-engine, integration-designer |

To use GraalVM instead of the native engine, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services.


# FlowX.AI 5.9.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026

First LTS in the 5.9.x family. Brings conversational AI, UI Flows and Custom Components, AI Platform, runtime authorization, new React Native and iOS UI Flow SDKs, and a wide set of integration and process-ops improvements.

[FlowX.AI 5.9.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-5.9.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted deployments
> * All Deployments Features available in both self-hosted and SaaS

### What 5.9.0 includes

* **Closes the runtime authorization rewrite**. Per-environment sharing, project-version-scoped roles, data-sync Keycloak provisioning.
* **Brings the full set of changes accumulated since the 5.1.x LTS line**. Conversational AI, UI Flows, Custom Components, AI Platform, runtime authorization.
* **Ships a new React Native SDK** and rounds out iOS UI Flow support.

> [!NOTE]
>
> **5.9.0 is the first LTS in the 5.9.x family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Self-hosted customers upgrading from 5.1.x LTS go directly to 5.9.0. See the [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview) guide for the consolidated upgrade path.

***

**What's in this LTS release?**

> [tab] Runtime authorization and sharing
>
> 🔐 [**Runtime authorization completion**](#runtime-authorization-completion) - Per-environment sharing checklist, project-level end-user roles, data-sync provisioning of Keycloak groups and roles.\
> 🌐 [**Anonymous runtime access**](#anonymous-runtime-access) - Built-in Anonymous role + Share modal "Everyone with the link" for unauthenticated end users; session-bound, SDK auth-skip mode.\
> 🛡️ [**Runtime authorization overhaul**](#runtime-authorization-overhaul) - Project-version-scoped roles, end-user groups moved from Keycloak into FlowX, Solutions → Share modal flow, Active Policy gate, designer-user bypass.\
> 🔒 [**UI Flow permissions**](#ui-flow-permissions) - Per-UI-Flow role allow-list with runtime 403 enforcement; assignments travel with import/export.\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.\
> 🎯 [**Active policy: group overrides**](#active-policy-group-overrides) - Override a project's active build per runtime group; legacy role overrides are excluded from runtime resolution and only kept for deletion.\
> 🧩 [**Roles carried across project-version merges**](#roles-carried-across-project-version-merges) - Application-version roles cloned onto the merged version automatically, no manual re-binding after merge.\
> 🏷️ [**Operations-editor role**](#operations-editor-role) - **Workspace operations editor** role and `wks_process_instance_variables_edit` permission for ops teams.\
> 🗂️ [**Cross-workspace projects**](#cross-workspace-projects) - Import the same project into multiple workspaces in the same environment.\
> 🔁 [**Cross-LTS import/export**](#cross-lts-import/export) - Move project versions and builds between the 5.1.x and 5.9.x LTS lines, in both directions.\
> 🚪 [**Log-in page redesign**](#log-in-page-redesign) - IdP provider button replaces the fallback link; refreshed labels across the log-in flow.

> [tab] Conversational AI
>
> 💬 [**Chat component**](#chat-component) - Standalone chat tab; Inline / Floating / FullScreen modes; iOS and Android support; Chat History; Suggested Prompts; Markdown.\
> 🌀 [**Conversational Workflows**](#conversational-workflows) - Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node.\
> 🎙️ [**Voice input + Speech-to-Text**](#voice-input-+-speech-to-text) - Audio recording in chat; Speech-to-Text node for transcription.\
> 🧠 [**Memory capabilities**](#memory-capabilities) - Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full; Use conversation memory toggle on the AI / Custom Agent node.\
> 🧭 [**Intent Classification node**](#intent-classification-node) - LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.\
> 💭 [**Chat-based UI Flows**](#chat-based-ui-flows) - Flow-Based vs Chat-Based experience type set at the UI Flow level.\
> ⚡ [**AI Triggers**](#ai-triggers) - Named parameterized message templates to launch conversational workflows with context.\
> 🏷️ [**Chat title generation and conversation search**](#chat-title-generation-and-conversation-search) - Auto-generated session titles + cross-conversation search on the chat history.\
> 🛑 [**Stop agent response**](#stop-agent-response) - Stop button while streaming; cancels the underlying workflow.

> [tab] AI Agents and Knowledge
>
> 📊 [**Evaluations (Evals)**](#evaluations) - LLM-as-judge, RAG-quality, and code evaluators score AI node outputs; datasets, experiments, per-org judge model via new `EVAL` capability.\
> 🤖 [**Custom Agent nodes**](#custom-agent-nodes) - AI agents that use MCP tools to act autonomously in workflows.\
> 🔎 [**Web Search tool for Custom Agents**](#web-search-tool-for-custom-agents) - Built-in web search so Custom Agents can look up up-to-date public-web information during a run.\
> 🔌 [**MCP integration**](#mcp-integration) - MCP servers as data sources; tools in Custom Agent nodes; OAuth 2.0, BEARER, BASIC auth.\
> 📖 [**Knowledge Bases**](#knowledge-bases) - PDF upload, workflow ingestion, semantic search, Custom Agent integration; Stores rename + typed filter builder; system metadata; Kafka indexer/embedder.\
> 🧰 [**AI Providers self-service**](#ai-providers-self-service) - Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability.\
> 🛡️ [**PII Guard: per-entity detections on documents and images**](#pii-guard-per-entity-detections-on-documents-and-images) - Document and image scans return the same per-entity detection list as text scans, with bounding regions.\
> 📝 [**Operational prompt split**](#operational-prompt-split) - System prompt split into operational guardrails and user-instruction layers, versioned independently.\
> 📄 [**Extract Data from File**](#extract-data-from-file) - LLM / OCR / Text Parsing strategies; image input; signature detection.\
> 🌐 [**Web Page Extractor / Web Crawler**](#web-page-extractor-/-web-crawler) - Static or dynamic URLs, link-following depth, PDF extraction, URL filtering, file downloads, multi-URL filters.\
> 📚 [**Manage Knowledge Base content from Runtime**](#manage-knowledge-base-content-from-runtime) - End users can add and update KB content at runtime without going back to the Designer.\
> ✨ [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent drafts React Custom Components from a brief.

> [tab] UI Flows and Custom Components
>
> 🪟 [**UI Flows**](#ui-flows) - Reusable multi-platform UI as project resources; Sessions monitoring; Process Renderer; Route Management; Start Parameters; Session Variables; onClick / On Display / On Load events.\
> ⏳ [**UI Flow session expiry**](#ui-flow-session-expiry) - Expire a UI Flow after a duration or on a schedule; expired sessions become read-only.\
> 🖼️ [**Configurable modal component**](#configurable-modal-component) - Title, subtitle, dismiss behavior, alignment and sizing on modals; theme-level shadow and dismiss icon.\
> 💻 [**Custom Components**](#custom-components) - React JSX / CSS in the Designer; Custom Components in Processes with INPUT/OUTPUT mappings.\
> 🎬 [**Event Handlers**](#event-handlers) - Typed Event Handlers section in the UI component config panel; UI events and AI triggers unified under one model.\
> ♿ [**Accessibility (WCAG 2.1 AA)**](#accessibility-wcag-2-1-aa) - Cross-platform accessibility model surfaced in the UI Designer.\
> 🧱 [**New theme components**](#new-theme-components) - Tooltip, Markdown, Progress Bar, Separator across React / Angular / Android.\
> 📤 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Multiple File Upload on process screens and UI Flows; Angular and React SDK support.\
> 🎨 [**Theming and Designer polish**](#theming-and-designer-polish) - Scoped variants and padding for form labels/errors/helpers, mandatory-label style.

> [tab] Integration and Data Platform
>
> 📨 [**Email Trigger**](#email-trigger) - IMAP-triggered processes; attachments to the `document-plugin`; validation rules.\
> 📧 [**Microsoft Outlook data source**](#microsoft-outlook-data-source) - Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes.\
> 🪝 [**Incoming Webhooks**](#incoming-webhooks) - New `webhook-gateway` microservice; trigger processes via HTTP POST; Slack provider adapter.\
> 🗄️ [**Oracle Database integration**](#oracle-database-integration) - Oracle 21c / 23ai data source; schema-aware Monaco editor.\
> 🍃 [**Unmanaged MongoDB data source**](#unmanaged-mongodb-data-source) - Connect to externally managed MongoDB 6.0+ instances.\
> 📁 [**File Storage data source**](#file-storage-data-source) - Move files in and out of external FTP / SFTP / S3 / Azure Blob storage from workflows.\
> 📨 [**Meta webhook provider**](#meta-webhook-provider) - WhatsApp / Messenger / Instagram / Threads webhook support with verify-token handshake and X-Hub-Signature-256 verification.\
> 📂 [**Documents in process instances**](#documents-in-process-instances) - Dedicated Documents section on each process instance.\
> 📤 [**Send Notification action + Email Sender**](#send-notification-action-+-email-sender) - SMTP data source; new action sends or replies email directly without Kafka.\
> 🎛️ [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder replacing manual JSON, with new operators.\
> 🧬 [**Parallel branches in workflows**](#parallel-branches-in-workflows) - Start / End Parallel nodes for concurrent execution.\
> ⚡ [**REST endpoint caching + workflow partitioning**](#rest-endpoint-caching-+-workflow-partitioning) - TTL-based REST GET caching; time-based workflow partitions with retention.\
> 🔗 [**Data mappers + workflow data models**](#data-mappers-+-workflow-data-models) - Workflow data models with input/output; process ↔ workflow mapping; CRUD endpoints.\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Reusable HTTP/HTTPS proxies attached to REST data sources.\
> ✉️ [**Two-stage attachment filtering for Email triggers**](#two-stage-attachment-filtering-for-email-triggers) - Choose which emails trigger the process and which attachments are forwarded into it.\
> ⏸️ [**Resume a process from an incoming webhook**](#resume-a-process-from-an-incoming-webhook) - Webhooks now drive Message Catch Intermediate Events with a Process Correlation Key.\
> 🌐 [**REST endpoints: content-type-aware responses**](#rest-endpoints-content-type-aware-responses) - Accept-driven JSON / text / XML parsing with XXE-safe XML; responses over 5 MiB are returned raw.\
> 📝 [**Raw endpoint payload type**](#raw-endpoint-payload-type) - Send request body as-is with the user's Content-Type preserved; XML / SOAP / form-urlencoded / plain text without MULTIPART wrapping.

> [tab] Process operations
>
> ✏️ [**Update Process Variables**](#update-process-variables) - JSON editor for variables on active instances; snapshot history; Compare diff.\
> 🛑 [**Stop workflow instances in runtime**](#stop-workflow-instances-in-runtime) - Authorized end users can stop running workflow instances from runtime.\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor.\
> 🔔 [**Notification history + template usages**](#notification-history-+-template-usages) - `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all references.\
> 📋 [**Token view improvements**](#token-view-improvements) - Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, color-coded status.\
> 🔧 **Fixed: names with square brackets** - Processes and UI flows whose names contain square brackets now start correctly again.

> [tab] Platform, deployment and infrastructure
>
> 🏢 [**Single-org self-hosted deployment**](#single-org-self-hosted-deployment) - Self-hosted default mode; guided setup wizard.\
> 🔑 [**License service**](#license-service) - Centralized license validation and usage reporting for self-hosted deployments.\
> 🔐 [**Authentication: opaque-token → JWT**](#authentication-opaque-token-→-jwt) - Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key`; dedicated service-accounts realm.\
> 🆕 [**New services to deploy**](#new-services-to-deploy) - `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. None existed in a 5.1.x deployment.\
> 🐍 [**Native script engine for JavaScript and Python**](#native-script-engine-for-javascript-and-python) - Default JS/Python execution moves from GraalVM to a Node.js + CPython subprocess pool; GraalVM available as opt-in.\
> 🌐 [**Ingress routing and CORS handling**](#ingress-routing-and-cors-handling) - NGINX ingress controller deprecated as the FlowX-shipped default; CORS moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on every backend service.\
> 📡 [**Kafka configuration alignment**](#kafka-configuration-alignment) - Standardized `KAFKA_*` env vars; mandatory `Fx-Organization-Id` header.\
> 📊 [**OpenTelemetry + SpiceDB DR**](#opentelemetry-+-spicedb-dr) - OpenTelemetry / Prometheus Helm charts published; SpiceDB backup and disaster-recovery procedures.\
> 🛡️ [**Durable message-processing**](#durable-message-processing) - Parked integration responses are persisted durably so in-flight responses survive runtime restarts, reducing stuck process tokens.\
> 🌍 [**Task management localization**](#task-management-localization) - 51 substitution tags + automatic table grid localization across 30 languages.

> [tab] Mobile & Renderers
>
> 📱 [**React Native SDK**](#react-native-sdk) - New SDK for React Native apps with process renderer, forms, navigation, and CMS integration. Demo app included.\
> 🍎 [**iOS UI Flows support**](#ios-ui-flows-support) - Full UI Flows renderer on iOS; sessions, document plugin subtypes, dismiss action, start parameters, new native components.\
> 📲 [**Mobile chat support**](#conversational-ai) - Chat component available on iOS and Android.\
> ⚛️ [**React 19 upgrade**](#react-19-upgrade) - React SDK upgraded to React 19; host apps must upgrade in lockstep.

> [tab] Info
>
> ℹ️ [**Deployment guidelines**](./deployment-guidelines-v5.9) - Component versions, environment variables, Kafka topics\
> 🗺️ [**Migrating from 5.1 LTS**](/5.9/migrating-from-5.1-lts/overview) - Consolidated upgrade path from 5.1.x LTS to 5.9.x LTS

> [card]
>
> ### **Runtime authorization completion**
>
> 5.9.0 completes the project-version-scoped runtime authorization model:
>
> * **Sharing checklist for environment promotion.** Sharing assignments do not export with builds. Each environment must be reconfigured when a project is promoted. The deployment checklist for this is now part of the setup guide.
> * **Project-level end-user roles.** Roles can be assigned at the project level from creation, so a fresh project is reachable without a separate share pass.
> * **Data-sync provisioning.** The data-sync job calls the Keycloak admin API on first run to provision FlowX-managed end-user groups and runtime roles. Five new `FLOWX_OPENID_*` env vars expose the admin credentials.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > See Setup guides → Access management → Runtime authorization for the day-to-day model.
>
> > [accordion] Key Features
> >
> > * **Per-environment sharing checklist.** When you promote a project from dev to uat to prod, the Share modal assignments do not travel with the build. The setup guide now documents the explicit per-environment reconfiguration step.
> > * **Project-level end-user roles.** Assign end-user roles at the project level so a freshly created project is reachable on day one. No separate Share-modal pass required for the default access pattern.
> > * **Data-sync Keycloak provisioning.** The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak the first time it runs against a 5.9.0 environment. Configure admin credentials with the new `FLOWX_OPENID_*` env vars on the data-sync job.
> > * **Deployment checklist included.** The runtime authorization setup guide now ships a deployment prerequisites section so the data-sync OpenID config and per-environment sharing reset are part of the standard promotion runbook.
>
> > [accordion] Configuration
> >
> > Required on the data-sync job from 5.9.0 onward:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak`. | `keycloak` |
> > | `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` |
> > | `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` |
> > | `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` |
> > | `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Set to `admin-cli` for standard Keycloak deployments. | `-` |
> >
> > See [Data-sync job setup → OpenID provider configuration](/5.9/setup-guides/data-sync#openid-provider-configuration) for the full setup.

> [card]
>
> ### **Anonymous runtime access**
>
> 5.9.0 introduces unauthenticated runtime access: an app can be made publicly reachable, and processes or UI flows inside it can be opened to anonymous end users via a new built-in role.
>
> * **Two independent gates.** The app must be set to **Everyone with the link** in the Share modal AND the process or UI flow must have the **Anonymous** role assigned. If either gate is closed, the runtime returns `403 Forbidden` (`Anonymous access not enabled for this application` / `Anonymous access not enabled for this build`).
> * **System-level Anonymous role.** Auto-seeded on every new app version, cannot be deleted or edited; allowed operations are `VIEW`, `EXECUTE`, and an auto-populated `SELF_ASSIGN`.
> * **Session-bound traffic.** Anonymous requests carry an `X-Fx-Anonymous-Session-Id` header. The backend issues a new session ID on first contact; instances are bound to that session and cannot be read by another.
> * **SDK auth-skip.** The renderer decides authenticated vs anonymous from the `authToken` parameter at initialization. Token-in-storage on the same browser silently bypasses anonymous mode — container apps must scrub the `Authorization` header on public routes.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access)
> >
> > See Platform deep-dive → User roles management → Anonymous runtime access for the full feature reference.
>
> > [accordion] Key Features
> >
> > * **Share modal public-access option.** A new **General access** section in the Share modal switches between **Everyone with the link** and **Only invited users and groups**. Default remains invited-only.
> > * **Anonymous role on processes, UI flows, and reusable UI templates.** Selectable in the Permissions tab once the role is on the version; additive to other roles.
> > * **Component hide / disable rules.** UI Designer supports an Anonymous condition in role-based hide/disable rules at the component level.
> > * **Public-build asset rule.** When a build has the Anonymous role and the app is shared publicly, all assets inside (enumerations, substitution tags, media files, themes, fonts) become reachable anonymously — except UI flows and processes that don't carry the Anonymous role.

> [card]
>
> ### **Runtime authorization overhaul**
>
> Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > Open the **Runtime authorization overhaul** documentation.

> [card]
>
> ### **UI Flow permissions**
>
> Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> >
> > Open the **UI Flow permissions** documentation.

> [card]
>
> ### **End-user access management**
>
> Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> >
> > Open the **End-user access management** documentation.

> [card]
>
> ### **Operations-editor role**
>
> New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix)
> >
> > Open the **Operations-editor role** documentation.

> [card]
>
> ### **Cross-workspace projects**
>
> Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/workspaces#cross-workspace-project-import)
> >
> > Open the **Cross-workspace projects** documentation.

> [card]
>
> ### **Cross-LTS import/export**
>
> Move project versions and builds between the **5.1.x** and **5.9.x** LTS lines, in both directions. A newer platform version imports exports produced by an older one, and exports produced on a newer version can target an older one — useful for shipping a hotfix to an environment that hasn't been upgraded yet. Compatibility is patch-agnostic: any 5.9.x patch works with any 5.1.x patch.
>
> When exporting to an older version, resources whose type doesn't exist there are excluded automatically and listed in a `manifest_excluded.json` file in the archive, so the import still succeeds. The lowest version in the export/import path defines the usable functionality.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import)
> >
> > Open the **Cross-version export and import** documentation.

> [card]
>
> ### **Active policy: group overrides**
>
> Active policy overrides can now target **runtime groups** instead of runtime roles. The override resolves the active build for every member of the group at runtime, with a priority field deciding which group wins when a user belongs to several.
>
> Role-based overrides are deprecated in the same change. The **Role** override type is gone from the Add / Edit modal, and any role overrides carried over from a 5.1.x upgrade are kept in the table for visibility only — they are flagged **DEPRECATED**, excluded from runtime resolution, and can only be deleted.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-policy)
> >
> > See Projects → Runtime → Active policy for the full configuration model.
>
> > [accordion] Key Features
> >
> > * **Group override type.** Add / Edit Policy Override now exposes **Username** and **Group**. The group picker lists runtime groups that have a runtime role configured for the current project.
> > * **Priority is mandatory and unique per project for group overrides.** Lower numbers win when several groups match the same user. Username overrides ignore priority and always take precedence.
> > * **Resolution order.** Username override → Group override (lowest priority wins) → Global policy.
> > * **Role overrides deprecated.** Removed from the Add / Edit modal. Existing role rows are rendered muted with a **DEPRECATED** marker and a red banner; only the delete action remains. Deprecated role overrides are excluded from runtime resolution.
> > * **Test panel.** The effective-policy test panel simulates resolution for a given user.
> > * **Audit log.** Group override create / update / delete / enable / disable events are recorded.
>
> > [accordion] Upgrade impact
> >
> > Upgrading from 5.1.x carries existing role overrides into the new table as deprecated entries. They no longer affect runtime behavior. Recreate the intended access using group overrides and delete the role rows. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.

> [card]
>
> ### **Roles carried across project-version merges**
>
> Application-level role definitions are now carried into the merged project version automatically. Before 5.9.0, merging two project versions could leave the role table in a partial state. Bindings defined on one side were not consistently propagated to the merged version. 5.9.0 clones the roles from the destination latest version onto the merged version atomically as part of the merge transaction, so merges with role changes complete without follow-up manual cleanup.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Roles propagated as part of the merge.** When a project version is merged, application-version roles from the destination latest version are cloned onto the merged version in the same transaction.
> > * **No manual role re-binding after merge.** Operators no longer need to re-apply role bindings on the merged version. The merge completes in a single commit; the merged version is immediately usable.

> [card]
>
> ### **Log-in page redesign**
>
> The Designer log-in page is refreshed to align with the platform's design system. When an organization has an external IdP configured, the previous fine-print fallback link is replaced with a primary button labeled with the IdP configuration's **Display name**. Field labels and call-to-action copy across the log-in flow are aligned with the rest of the UI.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **IdP provider button.** When the organization has an IdP configured, the log-in screen surfaces a primary button labeled with the IdP's **Display name**, instead of a fine-print link below the form.
> > * **Refreshed copy.** Updated labels across the flow: **Log In** replaces *Sign In*, **Reset Password** replaces *Forgot password?*, and the page title becomes **Log In**.

> [card]
>
> ### **Chat component**
>
> Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component)
> >
> > Open the **Chat component** documentation.

> [card]
>
> ### **Conversational Workflows**
>
> Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> >
> > Open the **Conversational Workflows** documentation.

> [card]
>
> ### **Voice input + Speech-to-Text**
>
> Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> >
> > Open the **Voice input + Speech-to-Text** documentation.

> [card]
>
> ### **Memory capabilities**
>
> Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> >
> > Open the **Memory capabilities** documentation.

> [card]
>
> ### **Intent Classification node**
>
> Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> >
> > Open the **Intent Classification node** documentation.

> [card]
>
> ### **Chat-based UI Flows**
>
> UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> >
> > Open the **Chat-based UI Flows** documentation.

> [card]
>
> ### **AI Triggers**
>
> Named parameterized message templates to launch conversational workflows with context.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> >
> > Open the **AI Triggers** documentation.

> [card]
>
> ### **Stop agent response**
>
> Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> >
> > Open the **Stop agent response** documentation.

> [card]
>
> ### **Chat title generation and conversation search**
>
> Chat sessions now get a meaningful title generated automatically from the user's first message. No more "untitled chat" entries in the history. End users can also search across all their conversations with a single query that scans both message bodies and session titles.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Auto-generated session title.** The first user message seeds a provisional title (first 7 words). A one-shot LLM call then refines it into a concise descriptive title; the chat list updates live via an SSE event.
> > * **Conversation search.** `/api/conversations` accepts a `q` query parameter (2–200 characters). Matches against both session titles and message bodies. Each result carries a `snippet` field showing the matched excerpt.
> > * **Title update event.** When the LLM title is generated, the gateway emits a `chatSessionRenamed` event on the chat session channel; the chat list shows the refined title on the next load.
> > * **Single-shot generation.** Title generation runs exactly once per session, on first persist. The provisional 7-word title remains in place if the LLM call fails. No error surfaces to the end user.

> [card]
>
> ### **Evaluations**
>
> 5.9.0 introduces Evaluations: score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Attach datasets to AI nodes, launch experiments, and read per-evaluator aggregate scores plus per-test-case details.
>
> * **10 built-in evaluators across three categories.** LLM-as-judge (Correctness, Conciseness, Hallucination, Answer relevance), RAG (Groundedness, Helpfulness, Retrieval relevance), and Code (Exact match, Levenshtein, JSON match). Numeric evaluators ship with default thresholds; binary evaluators return pass/fail.
> * **Datasets attached to AI nodes.** Test cases sourced manually or captured from real node executions. The dataset persists a schema snapshot so older runs remain reproducible if the workflow changes underneath.
> * **Async judge pipeline.** A new Python `evals-judge` event-driven worker consumes `ai.flowx.ai-platform.evals-judge.job.request.v1`, scores each (test case × evaluator) pair via the configured judge LLM, and publishes back on the response topic. Unscored jobs land on a DLQ for manual review.
> * **Per-org judge model.** A new `EVAL` capability is registered in the org-manager LLM catalogue. Platform default is `gpt-5.4-mini`, backfilled per org on upgrade so evals work out-of-the-box.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/evaluations)
> >
> > See AI Platform → Evaluations for the user workflow, evaluator catalogue, REST API surface, and operator setup.
>
> > [accordion] Key Features
> >
> > * **Designer workflow.** Add a dataset on an AI node, add test cases (manually or captured from a node execution), pick evaluators, launch an experiment, read aggregate + per-test-case reports.
> > * **LLM-as-judge scoring.** A judge LLM reads the model output (and optional expected output) and scores it on a single rubric, returning a numeric score plus its reasoning.
> > * **RAG-quality scoring.** Judges the retrieval side of a RAG workflow — is the retrieved context grounded, helpful, and relevant?
> > * **Deterministic code evaluators.** No LLM call. Exact match, normalized Levenshtein, and JSON-shape match against the dataset's output contract.

> [card]
>
> ### **PII Guard: per-entity detections on documents and images**
>
> PII Guard scans on document and image AI nodes now surface the same per-entity detection list already shown for text scans. The run console reports each match with its entity type, confidence, original value, and replacement, making it easy to verify what was redacted on file-based AI inputs.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Same shape as text scans.** Document and image scans now return a `detections` list with `entityKey`, `confidence`, `originalValue`, `replacement`, and `direction`, matching the existing text-scan output.
> > * **Bounding regions for document and image hits.** Each detection on a `DOCUMENT` or `IMAGE` source includes `regions` (`x`, `y`, `width`, `height`) so the run console can highlight where the entity was matched.
> > * **Source-type tagging.** Detections carry a `sourceType` of `TEXT`, `DOCUMENT`, or `IMAGE`, mirroring the wrapper's `sourceType` field so audit consumers can attribute matches to the right payload.
> > * **Backward-compatible upgrade.** On older data-privacy versions that don't yet return the analyzer pass for object endpoints, `detections` stays empty and the redacted artifacts continue to be produced and downloadable.

> [card]
>
> ### **Custom Agent nodes**
>
> AI agents that use MCP tools to act autonomously inside workflows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> >
> > Open the **Custom Agent nodes** documentation.

> [card]
>
> ### **Web Search tool for Custom Agents**
>
> Custom Agent nodes can call a built-in web search tool to look up up-to-date information from the public web during a run. Turn it on with a single toggle — the agent decides when to search based on its instructions and the user's request.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Single toggle.** Enable **Tools → Built-in tools → Use Web Search Tool** on a Custom Agent node. Off by default; no extra configuration.
> > * **Agent-driven.** The agent calls web search on its own when the task needs current information, and folds the results into its response.

> [card]
>
> ### **MCP integration**
>
> MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> >
> > Open the **MCP integration** documentation.

> [card]
>
> ### **Knowledge Bases**
>
> Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > Open the **Knowledge Bases** documentation.

> [card]
>
> ### **AI Providers self-service**
>
> Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/ai-providers)
> >
> > Open the **AI Providers self-service** documentation.

> [card]
>
> ### **Extract Data from File**
>
> LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> >
> > Open the **Extract Data from File** documentation.

> [card]
>
> ### **Web Page Extractor / Web Crawler**
>
> Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> >
> > Open the **Web Page Extractor / Web Crawler** documentation.

> [card]
>
> ### **Context Retrieval**
>
> RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> >
> > Open the **Context Retrieval** documentation.

> [card]
>
> ### **AI Developer generates Custom Components**
>
> Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> >
> > Open the **AI Developer generates Custom Components** documentation.

> [card]
>
> ### **Operational prompt split**
>
> The single Operation Prompt field on AI nodes is split into two inputs so the static portion of the prompt can be cached by the LLM provider while dynamic values are passed separately. **Instructions** holds the agent's role, tasks, and expected I/O, sent as the System message and cached between executions, so `${}` dynamic values are not allowed. The **Context** field, inside the **Background** section, takes the dynamic per-execution prompt text and supports `${}` references, sent as the User message and not cached.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Instructions: cached System message.** Mandatory. Holds the agent's role, tasks, and expected input/output. Sent as the System message and cached by the LLM between executions. `${}` references are rejected to keep the cache key stable.
> > * **Background section: dynamic User message.** Wraps the Knowledge Base selector, the **Context** textarea (free text with `${}` support), the **Use only referenced values as input** toggle, and, in Chat Driven workflows, the **Use conversation memory** toggle. Sent as the User message on every execution; not cached.
> > * **Lower LLM cost and latency.** The static portion of the prompt is sent once per cache window instead of on every execution, so each call pays only for the dynamic Background section. The longer the Instructions, the bigger the per-call saving.
> > * **Applies to every AI node subtype.** The split UI is now shared by all AI node subtypes that previously used the single Operation Prompt field.

> [card]
>
> ### **Manage Knowledge Base content from Runtime**
>
> A new **Test KB** option on the build is available in runtime, giving operators visibility into Knowledge Base content that was previously opaque after deployment. Authorized users can inspect chunks, add or replace sources, edit metadata, and query the KB without going back to the Designer. Useful for debugging retrieval issues and keeping KBs current as business knowledge evolves.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Six runtime operations.** Create store, Append content, Replace content, Delete store, Edit metadata, and Query. All from the Test KB option inside the running app.
> > * **Files and payloads.** Both file uploads and inline payloads can be added to the KB through this feature.
> > * **Permission-gated.** KB management at runtime is controlled by runtime authorization, so only users with the right role see the Test KB controls.
> > * **Visibility into chunking.** Inspect how documents were chunked and what metadata was captured, useful when debugging retrieval quality on client-uploaded content.

> [card]
>
> ### **UI Flows**
>
> 5.9.0 closes the UI Flows feature: reusable, multi-platform UI (web, iOS, Android) as first-class project resources with their own lifecycle and runtime sessions. UI Flows now reach feature parity with processes for end-user-facing apps that don't need a BPMN process underneath.
>
> * **Multi-platform.** Author once in the Designer; UI Flows render on web (React), iOS, and Android via the platform-specific renderers. Layouts and component bindings travel together as a single resource.
> * **Sessions and runtime monitoring.** Each UI Flow run is a `UiFlowSession` with its own state, navigation history, and SSE event stream. Operators can monitor and inspect sessions from the runtime.
> * **Process integration.** UI Flows can start processes (Start Process action), navigate to other UI Flows (Navigate UI action), and embed a Process Renderer to show a running process inside a UI Flow. Workflows can also be invoked from a UI Flow with a Start Workflow action.
> * **Per-UI-Flow permissions.** A dedicated Permissions tab on each UI Flow controls which roles can run it. Runtime enforces with `403`; assignments travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows)
> >
> > See Building blocks → UI Flows for the full feature reference, including Navigation Areas, session variables, route management, and the component reference.
>
> > [accordion] Key Features
> >
> > * **Navigation Areas.** Group UI components into named areas for layout, scroll, and per-area transitions.
> > * **Start Parameters and Session Variables.** Pass typed inputs into a UI Flow at start; persist state across nodes via Session Variables.
> > * **Route management.** Each UI Flow exposes a stable runtime route; nested navigation preserves browser history and back/forward behaviour.
> > * **Task Manager component.** Drop the Task Manager surface inside a UI Flow to drive process tasks from the same UI shell.
> > * **onClick and On Display events, plus a new On Load event.** Component-level events trigger workflows or UI actions, with the new On Load event firing when the UI Flow first opens.
> > * **Breadcrumbs.** Built-in breadcrumbs reflect the Navigation Area hierarchy and follow the active theme.
> > * **Process Renderer + Start Workflow action.** Embed a running process inside a UI Flow; trigger an integration workflow from a button or event without leaving the flow.

> [card]
>
> ### **UI Flow session expiry**
>
> A UI Flow session can be set to expire automatically after a fixed duration or on a schedule. Once expired, the session becomes read-only — the user keeps the data already loaded but cannot take further action.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Flexible expiry.** Set the **Expiry time** in **Settings → General** as an ISO-8601 duration (for example `PT3M22S`) or a cron expression (for example `0 0 9-17 * * MON-FRI`). Empty means no expiry.
> > * **Read-only on expiry.** Expired sessions block all actions; loaded data stays visible and nothing is wiped.
> > * **Server-enforced.** The platform marks sessions `EXPIRED` server-side, so it applies the same way in the deployed app and the Designer preview.

> [card]
>
> ### **Configurable modal component**
>
> Modals on process screens and UI Flows gain configurable content and layout. Set a title and subtitle, control dismiss behavior, and align and size the modal from the Designer.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Content.** Set the modal **Title** and **Subtitle** from the Settings panel.
> > * **Dismiss behavior.** Toggle **Dismissible**, allow **Backdrop click**, and optionally show a **Confirmation alert** with custom title, message, and button labels.
> > * **Layout.** Align content **Left**, **Center**, or **Right**, and set **Width**/**Height** to **Fixed** or **Auto**.
> > * **Theme-level styling.** The modal **shadow** and **dismiss icon** are defined once in the theme's Modal section.

> [card]
>
> ### **Custom Components**
>
> Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> >
> > Open the **Custom Components** documentation.

> [card]
>
> ### **Process Renderer in UI Flows**
>
> Embed process renderers inside UI Flows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > Open the **Process Renderer in UI Flows** documentation.

> [card]
>
> ### **UI Flow sessions monitoring**
>
> Runtime view with session list, audit log, process tracking, workflow debugging.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> >
> > Open the **UI Flow sessions monitoring** documentation.

> [card]
>
> ### **Accessibility (WCAG 2.1 AA)**
>
> Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> All Deployments

> [card]
>
> ### **New theme components**
>
> Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Open the **New theme components** documentation.

> [card]
>
> ### **Multi-file bulk upload**
>
> Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> >
> > Open the **Multi-file bulk upload** documentation.

> [card]
>
> ### **Card default collapse + Tables in Collections**
>
> Cards configurable to load collapsed; Table UI components inside Collection prototypes.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> >
> > Open the **Card default collapse + Tables in Collections** documentation.

> [card]
>
> ### **Event Handlers**
>
> The UI component configuration panel introduces a dedicated **Event Handlers** section. The legacy `flowx_props` bag is replaced by a typed, per-handler form covering action type, optional analytics, custom body, destination, and collection save-key fields. Container components (Page, Zone, Modal, Tab Bar in UI Flows; Tab on process screens) and inline components resolve their actions through the same model.
>
> Existing UI events and AI triggers are migrated automatically. A Liquibase migration runs on the first 5.9.0 boot and moves the data into the new `ui_action` model. No project re-export or re-import is required.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Typed Event Handlers.** Each handler is a named, typed entity instead of a free-form prop, making configuration easier to validate and audit.
> > * **Action type selector.** Pick the action type from a dropdown that knows which fields are required for that type.
> > * **Analytics, body, destination, save-key.** Per-handler sub-forms cover analytics events, custom request bodies, destination resolution, and collection save-key fields.
> > * **Unified for inline and container components.** Page, Zone, Modal, and Tab Bar containers in UI Flows use the same Event Handlers model as inline components; on process screens, Tab containers use it.

> [card]
>
> ### **Theming and Designer polish**
>
> > [accordion] Theming
> >
> > Form field labels, error messages, and helper text gain padding controls and scoped style variants in the theme model. Theme Admin exposes the new padding properties on segmented buttons, sliders, and input selections; the React and Angular SDKs apply the values in the renderers; the Designer preview reflects them in place. Form fields also pick up a consistent **mandatory label** style applied automatically when a field is required.
> >
> > * **Scoped variants for labels, errors, helpers.** Theme configs can override label, error, and helper styles per component without affecting other parts of the form.
> > * **Padding for segmented buttons, sliders, input selections.** Theme Admin adds label, error, and helper padding controls for these components; values flow through to all renderers.
> > * **Mandatory label style.** A consistent style for mandatory-field labels, applied automatically when a form field is required.
> > * **Designer preview parity.** Theme overrides and paddings are visible in the Designer preview without round-tripping through a runtime app.
> >
> > All Deployments
>
> > [accordion] Designer polish
> >
> > The command center floating action button is now hidden on the running-instance screens of Processes, UI Flows, and UI Templates, where it overlapped with the instance view; it reappears when the instance data panel is open. The command center remains reachable through the standard keyboard shortcut and from screens where it does not interfere.
> >
> > All Deployments

> [card]
>
> ### **Email Trigger**
>
> New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> >
> > Open the **Email Trigger** documentation.

> [card]
>
> ### **Microsoft Outlook data source**
>
> Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> >
> > Open the **Microsoft Outlook data source** documentation.

> [card]
>
> ### **Incoming Webhooks**
>
> New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> >
> > Open the **Incoming Webhooks** documentation.

> [card]
>
> ### **Oracle Database integration**
>
> Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL. Beyond tables and `SELECT`, queries can also target views, functions, and stored procedures, with output parameters returned to the workflow.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> >
> > Open the **Oracle Database integration** documentation.

> [card]
>
> ### **Unmanaged MongoDB data source**
>
> Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> >
> > Open the **Unmanaged MongoDB data source** documentation.

> [card]
>
> ### **File Storage data source**
>
> A new data source connecting workflows to external file storage — FTP, SFTP, S3 / S3-compatible, or Azure Blob Storage. Define named List, Download, Upload, Delete, and Move operations scoped to a root path, browse and test them in Designer, and call them from a Data Source node. Operations run in the new `file-gateway` service, exchanging files with the `document-plugin`.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/file-storage)
> >
> > Open the **File Storage data source** documentation.

> [card]
>
> ### **Send Notification action + Email Sender**
>
> SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> >
> > Open the **Send Notification action + Email Sender** documentation.

> [card]
>
> ### **Advanced Query Builder**
>
> Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> >
> > Open the **Advanced Query Builder** documentation.

> [card]
>
> ### **Parallel branches in workflows**
>
> Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> All Deployments

> [card]
>
> ### **REST endpoint caching + workflow partitioning**
>
> TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> All Deployments

> [card]
>
> ### **Data mappers + workflow data models**
>
> Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> >
> > Open the **Data mappers + workflow data models** documentation.

> [card]
>
> ### **Proxy Server Connections**
>
> Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> >
> > Open the **Proxy Server Connections** documentation.

> [card]
>
> ### **Faster authoring loop**
>
> 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.
>
> All Deployments

> [card]
>
> ### **Meta webhook provider**
>
> Incoming Webhooks add **Meta** as a built-in provider alongside Generic and Slack, covering WhatsApp, Messenger, Instagram, and Threads. The webhook-gateway handles the Meta-specific subscription handshake and signature verification natively. No custom adapter code required to wire a Meta-platform integration into a FlowX process.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Subscription handshake.** The gateway answers Meta's GET URL-verification request by validating `hub.mode=subscribe` and the provided `hub.verify_token` against the configured verify token, then echoes `hub.challenge` back. Constant-time token comparison.
> > * **X-Hub-Signature-256 verification.** Every POST is authenticated with the `X-Hub-Signature-256` HMAC-SHA256 signature using the configured app secret. Requests with missing or invalid signatures are rejected before reaching the process engine.
> > * **Two secrets per webhook.** When you create a Meta webhook in Integration Designer, two masked inputs appear in the configuration panel: **Verify token** (used during the handshake) and **App secret** (used for signature verification). Both are required.
> > * **Multi-product support.** A single Meta webhook can receive events from WhatsApp, Messenger, Instagram, and Threads. The provider is configured at the webhook level; the channel is part of the payload.
>
> > [accordion] Configuration
> >
> > Select **Meta** in the provider dropdown when creating the webhook data source. Both secret fields are required:
> >
> > | Field | Description |
> > | - | - |
> > | **Verify token** | The token Meta sends back during the GET URL-verification handshake. Choose any string; configure the same value on the Meta App developer console. |
> > | **App secret** | The App secret from the Meta App configuration; used to verify the `X-Hub-Signature-256` HMAC on every POST. |
> >
> > Both values are stored as a JSON-packed pair on the existing webhook secret field. No schema migration is required.
> >
> > See [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#meta-provider) for the full setup walk-through.

> [card]
>
> ### **Documents in process instances**
>
> Each process instance now exposes a dedicated **Documents** tab. A single source of truth for every document handled during the process, regardless of how it entered the instance. Operations teams can review tracking metadata, preview, and download attached files from one place rather than walking through the process timeline.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **All document sources in one place.** End-user uploads via the file-upload component, attachments from email triggers, files generated from HTML templates, OCR output, and files produced by AI workflow nodes, all listed under one tab.
> > * **Tracking metadata and preview.** Each row shows source, timestamp, and uploader, with inline preview for supported file types.
> > * **Direct download.** Download any attached document directly from the Documents tab.
> > * **Faster operations review.** No more clicking through the process timeline to reconstruct which file came in at which step.

> [card]
>
> ### **Two-stage attachment filtering for Email triggers**
>
> Email triggers (IMAP and Microsoft Outlook) now expose a two-stage filter on each trigger: choose which incoming emails create a process instance, then choose which attachments are forwarded into the process. The previous single on/off validations toggle is replaced with explicit, per-trigger control over inbound mail.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start Process for.** Trigger the process for all emails, only emails with attachments, or only emails carrying selected file types (PDF, DOCUMENT, IMAGE, EXCEL, ZIP).
> > * **Save email attachments on process.** Forward all attachments, none (metadata-only), or only specific file types into the process instance.
> > * **Trigger-level rejection.** Emails that fail the trigger condition or exceed **Maximum File Count** are rejected with explicit Failed Triggers causes. **No attachments**, **No matching file types**, **File count exceeded**.
> > * **Backward-compatible upgrade.** Existing triggers are migrated to **All incoming emails** + **All attachments** with no manual intervention. Reopen each trigger to reapply file-type filtering if you previously relied on the validations toggle.

> [card]
>
> ### **Resume a process from an incoming webhook**
>
> Incoming Webhooks can now drive a **Message Catch Intermediate Event**, not just a Message Start Event. When a process is paused on an intermediate catch event, an external system can POST to the webhook to resume that specific instance. Useful for callbacks from third-party services, asynchronous job completions, or operator actions delivered over HTTP.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start or resume from one webhook model.** The same webhook data source can start new processes (on a Message Start Event) or resume waiting ones (on a Message Catch Intermediate Event). The trigger type is set automatically based on where the webhook is attached.
> > * **Process Correlation Key.** Each intermediate catch event declares a Process Correlation Key (a business variable like `applicationId`). The webhook-gateway matches this value against the incoming payload to route the resume to the right process instance. The Webhook Correlation Key now accepts array indices in square brackets (`entry[0].changes[0].value.messages[0].text.body`), so the canonical Meta WhatsApp resume path works without flattening upstream.
> > * **Validation at design time.** Process Correlation Key and Process Key are required on intermediate webhook catch events and are validated when the message event is created or updated.
> > * **Backward-compatible upgrade.** Existing webhooks are migrated to `triggerType=START_PROCESS` with no manual intervention. New webhooks attached to an intermediate catch event are flagged `RESUME_PROCESS` automatically.

> [card]
>
> ### **REST endpoints: content-type-aware responses**
>
> REST endpoint responses in Integration Designer are now parsed by content type rather than assumed to be JSON. The endpoint's `Accept` header drives parsing: JSON, plain text, and XML responses are each handled with the right parser, and the original XML string is preserved alongside the parsed map so downstream nodes can read either form. Existing JSON-returning endpoints continue to work without configuration changes.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Accept-driven response parsing.** The endpoint's `Accept` header decides how the response is parsed. JSON variants (`application/json`, `application/hal+json`, `application/problem+json`, any `+json` suffix) are parsed as JSON; `text/*` is returned as a string; XML variants (`application/xml`, `text/xml`, `application/soap+xml`, any `+xml` suffix) are parsed into a JSON-shaped map. When `Accept` is missing, the endpoint falls back to `Content-Type`, then to **AUTO** best-effort.
> >
> > * **XML responses parsed into JSON-shaped objects.** XML response bodies are auto-converted to maps so existing path expressions (`response.body.someField`) work without code changes. The original XML string is preserved on `sourceBody` for callers that need it raw.
> >
> > * **Loud failures on declared mismatches.** When an endpoint declares JSON or XML and the upstream returns a different category, or returns a body that fails to parse, the node fails with a precise error message (for example, `Expected response content type "application/json" but received "text/plain"`). The original body is preserved on `rawBody`.
> >
> > * **Tolerant under AUTO and wildcards.** Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) and inferred categories (no `Accept` declared) fall back to the raw string instead of failing. Flaky or mislabelled upstreams don't break the node.
> >
> > * **XXE-safe XML parser.** XML parsing has DTD processing and external-entity resolution disabled by construction. External-entity attack payloads are neutralized; billion-laughs / entity-expansion attacks cannot fire.
> >
> > * **File downloads bypass Content-Type checks.** File-download endpoints (BINARY or BASE64) deliver the platform's own JSON payload regardless of upstream `Content-Type`, so legacy PDF, octet-stream, and image downloads work unchanged.
> >
> > * **Large XML returned raw.** XML response bodies larger than 5 MiB are returned as the raw string instead of a parsed map, so very large payloads don't block the node.
> >
> > > [!WARNING]
> > >
> > > **Mixed-content XML responses expose a new `value` key.** An XML element with both attributes and inner text (`<leaf attr="v">text</leaf>`) is now parsed to `{attr: "v", value: "text"}`. The inner text used to be silently dropped. Downstream nodes that iterate response keys or assert the exact key set on mixed-content elements may see an additional `value` entry. Path expressions that addressed attributes or child elements directly are unaffected.

> [card]
>
> ### **Raw endpoint payload type**
>
> REST endpoint configuration adds a **Raw** content type alongside JSON, Multipart, and Binary. Raw bodies are sent to the upstream system as-is. Useful for XML, SOAP envelopes, form-urlencoded payloads, or any plain-text body where you need to set the `Content-Type` header yourself.
>
> Before 5.9.0, the only way to send a non-JSON textual body was to use Multipart, which wrapped the payload in `multipart/form-data` and overrode the `Content-Type` header. Raw removes that wrapping.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Body sent as-is.** The body field is sent verbatim. The dispatcher does not transform, wrap, or pretty-print it.
> > * **Caller controls Content-Type.** Set the `Content-Type` header on the endpoint to whatever the upstream expects (`text/xml`, `application/soap+xml`, `application/x-www-form-urlencoded`, `text/plain`). The dispatcher does not override it.
> > * **Monaco plain-text mode.** The endpoint editor switches Monaco to plain text when Raw is selected. XML and SOAP indentation are preserved on paste and edit instead of being reformatted as JSON.
> > * **Shares the JSON body slot.** Raw and JSON payloads use the same storage field on the endpoint definition, so no schema migration is required. Existing endpoints continue to work without changes.

> [card]
>
> ### **Update Process Variables**
>
> JSON editor for variables on active instances with snapshot history; Compare diff.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> >
> > Open the **Update Process Variables** documentation.

> [card]
>
> ### **Stop Run for workflows**
>
> Cancel a running workflow instance from the editor.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-workflows#running-and-stopping-workflows)
> >
> > Open the **Stop Run for workflows** documentation.

> [card]
>
> ### **Notification history + template usages**
>
> `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> >
> > Open the **Notification history + template usages** documentation.

> [card]
>
> ### **Token view improvements**
>
> Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/token)
> >
> > Open the **Token view improvements** documentation.

> [card]
>
> ### **Stop workflow instances in runtime**
>
> Authorized end users can now stop running workflow instances directly from runtime. Previously, stopping a workflow required Designer access or a direct API call. The new control surfaces the action inside the runtime application alongside other workflow-instance management options.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **One-click stop.** Stop a running workflow instance from the runtime instance list.
> > * **Permission-gated.** The stop control is governed by runtime authorization.
> > * **Audited.** Stop actions are recorded on the workflow-instance audit log with the actor and timestamp.

> [card]
>
> ### **Native script engine for JavaScript and Python**
>
> The default script engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a **native subprocess pool**. Scripts run in long-running Node.js and Python worker processes managed by `process-engine` and `integration-designer`. Existing scripts that read from `input` and write to `output` keep working, including `output.put(...)`, `output.get(...)`, and bracket assignment.
>
> The change is opt-out: set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services to keep the previous engine.
>
> Self-HostedAll Deployments
>
> > [accordion] Key Features
> >
> > * **Node.js workers for JavaScript.** JavaScript runs in isolated Node.js worker processes. Each script executes in a fresh V8 context with an explicit globals allowlist and a V8-level execution timeout.
> > * **CPython workers for Python.** Python 3 runs in isolated worker processes with a curated sandbox. Common standard-library modules (`random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64`) are available without `import`. Process, OS, and network modules are blocked.
> > * **Worker pools with recycling.** Worker pools default to 16 Node.js workers and 8 Python workers, sized per service. Workers are recycled after a configurable number of executions to prevent state leakage.
> > * **HashMap method compatibility.** The familiar `output.put(key, value)`, `output.get(key)`, and `output.containsKey(key)` methods continue to work on both JavaScript and Python. The same scripts that ran under GraalVM polyglot context keep working without rewrites.
> > * **GraalVM still available as opt-in.** Set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine, useful if a script depends on GraalVM-specific polyglot features.
> > * **Hardened execution sandbox.** Per-execution fresh scope, environment variables cleared at worker startup, dangerous Python module references scrubbed before user code runs, no `require` / `process` / `global` access in JavaScript.
>
> > [accordion] Configuration
> >
> > The native engine is the default on `process-engine` and `integration-designer`. Tune worker pools and timeouts as needed:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider. `native` or `graalvm`. | `native` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size. | `16` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS execution timeout per script (ms). | `5000` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size. | `8` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python execution timeout per script (ms). | `10000` |
> >
> > See [Process engine setup → Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration) and [Integration Designer setup → Script engine configuration](/5.9/setup-guides/integration-designer-setup#script-engine-configuration) for the full set including payload size and worker recycling.
>
> > [accordion] Migration impact
> >
> > For most existing scripts the change is transparent. The `input`, `output`, `additionalData`, and `instanceMetadata` bindings behave the same, and HashMap-style access on `output` is preserved.
> >
> > Scripts that need attention:
> >
> > * **Python scripts that `import` modules outside the curated allowlist.** Narrow the script to use only the pre-loaded modules, or stay on GraalVM via the opt-out env var.
> > * **JavaScript scripts that reach for `require(...)`, `process`, or `global`.** Those references were never part of the supported surface area but may have worked under GraalVM. Rewrite to use only the bindings provided, or stay on GraalVM via the opt-out env var.
> > * **Scripts that depended on GraalVM-specific polyglot APIs** (calling Java classes from JavaScript / Python). Stay on GraalVM via the opt-out env var.
> >
> > See [Script runtime change for JavaScript and Python business rules](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit checklist.

> [card]
>
> ### **Single-org self-hosted deployment**
>
> Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/organization-deployment)
> >
> > Open the **Single-org self-hosted deployment** documentation.

> [card]
>
> ### **License service**
>
> Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> >
> > Open the **License service** documentation.

> [card]
>
> ### **Authentication: opaque-token → JWT**
>
> Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/authentication-iam)
> >
> > Open the **Authentication: opaque-token → JWT** documentation.

> [card]
>
> ### **New services to deploy**
>
> `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/prerequisites#new-services-to-deploy)
> >
> > Open the **New services to deploy** documentation.

> [card]
>
> ### **Ingress routing and CORS handling**
>
> The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/ingress-routing)
> >
> > Open the **Ingress routing and CORS handling** documentation.

> [card]
>
> ### **Kafka configuration alignment**
>
> Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/kafka)
> >
> > Open the **Kafka configuration alignment** documentation.

> [card]
>
> ### **OpenTelemetry + SpiceDB DR**
>
> OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> All Deployments

> [card]
>
> ### **Durable message-processing**
>
> The process engine now persists parked integration and external-message responses durably, so a response that arrives before its process is ready to consume it survives a runtime restart instead of being lost. This removes a class of stuck process-token failures and improves message-processing robustness at runtime.
>
> All Deployments

> [card]
>
> ### **Task management localization**
>
> 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Open the **Task management localization** documentation.

> [card]
>
> ### **React Native SDK**
>
> FlowX 5.9.0 ships a brand-new **React Native SDK**, bringing the same process renderer model that has powered the React, Angular, iOS, and Android SDKs to React Native apps. Teams building cross-platform mobile or embedded React Native experiences can now host FlowX processes natively, with forms, navigation, and CMS integration handled by the SDK.
>
> A companion demo app is included as a reference integration, covering authentication, the showcase page, and the wiring needed to start a process from inside a container app.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Process renderer.** Render FlowX processes inside any React Native screen with the same component model as the other SDKs.
> > * **Forms and basic components.** Page, Button, Text, Container, Card, and form components ship out of the box.
> > * **CMS integration.** Static content and theming load from the FlowX CMS, including dynamic display values.
> > * **Navigation.** Basic process navigation between screens follows the same patterns as the iOS and Android SDKs.
> > * **Demo app included.** A demo app with authentication and a showcase page is shipped alongside the SDK as a reference integration.

> [card]
>
> ### **iOS UI Flows support**
>
> The iOS renderer reaches feature parity with the React and Angular renderers on UI Flows. iOS apps can now start UI Flows from container apps, manage UI Flow sessions, dismiss modals, handle UI actions, and render document-plugin subtypes (images and document previews).
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start UI Flow from container app.** Container apps can launch a UI Flow with start parameters and handle the response.
> > * **UI Flow session management.** The renderer manages a UI Flow session lifecycle on iOS the same way it does on web.
> > * **onLoad UI Event for Page.** Pages emit an `onLoad` UI Event that iOS handlers can listen to, matching the cross-platform event model.
> > * **Dismiss action and dismiss-on-completion.** A `dismiss` action type cleanly closes modals; `dismiss on completion` on `START_WORKFLOW` actions auto-closes the launching modal when the workflow finishes.
> > * **UI Flow start params.** Pass typed start parameters into a UI Flow at launch.
> > * **Upload File support.** UI Flows on iOS support file upload, including image and document-preview document-plugin subtypes.
> > * **Updated start-process endpoint.** The iOS renderer uses the latest start-process endpoint and `data` property on Start UI Flow, aligned with the web SDKs.
> > * **New native components.** Tooltip, Separator, Progress View, and Markdown components are now rendered natively on iOS, bringing the iOS component set closer to parity with the React and Angular renderers.
> > * **Accessibility properties from UI Designer.** Accessibility properties configured in the UI Designer flow through to the iOS renderer, so screen reader labels and traits are honored on native screens.

> [card]
>
> ### **React 19 upgrade**
>
> The React SDK upgrades to **React 19**, picking up the runtime improvements and APIs that ship with that release. Surrounding `@flowx/*` packages are upgraded in lockstep so the renderer continues to work as a single coherent bundle.
>
> Host apps embedding the React renderer should plan a React 19 upgrade on their side and run the standard React migration checks before adopting 5.9.0.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **React 19 runtime.** Adopts the React 19 reconciler and the APIs that ship with that release.
> > * **Packages upgraded in lockstep.** All `@flowx/*` web SDK packages move to the same baseline so the renderer ships as one coherent bundle.
>
> > [accordion] Host app impact
> >
> > Host apps that embed the React renderer must be on React 19 themselves. Run the React 19 codemods and verify any third-party React libraries you depend on are compatible before upgrading FlowX.

> [card]
>
> ### **Runtime authorization and sharing**
>
> This is the biggest governance change in the 5.1 → 5.9 upgrade. End-user identities, runtime roles, and sharing assignments move out of Keycloak into FlowX-managed records, with project-version-scoped roles and a dedicated Share modal flow on Solutions.
>
> > [card] [Runtime authorization completion](#runtime-authorization-completion)
> >
> > Closes the rewrite: per-environment sharing checklist, project-level end-user roles, data-sync Keycloak provisioning. See the 5.9.0 card above.
>
> > [card] [Anonymous runtime access](#anonymous-runtime-access)
> >
> > Built-in `Anonymous` role + Share modal "Everyone with the link" option for unauthenticated end users. Session-bound (`X-Fx-Anonymous-Session-Id`), fire-and-forget; per-component hide/disable rules; SDK auth-skip mode.
>
> > [card] [Runtime authorization overhaul](#runtime-authorization-overhaul)
> >
> > Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> > [card] [UI Flow permissions](#ui-flow-permissions)
> >
> > Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> > [card] [End-user access management](#end-user-access-management)
> >
> > Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> > [card] [Operations-editor role](#operations-editor-role)
> >
> > New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> > [card] [Cross-workspace projects](#cross-workspace-projects)
> >
> > Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.

> [card]
>
> ### **Conversational AI**
>
> 5.9 takes FlowX from no chat to production conversational AI: the Chat component, conversational workflows with memory and intent classification, voice and speech-to-text, chat-based UI Flows, and runtime controls.
>
> > [card] [Chat component](#chat-component)
> >
> > Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> > [card] [Conversational Workflows](#conversational-workflows)
> >
> > Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> > [card] [Voice input + Speech-to-Text](#voice-input-+-speech-to-text)
> >
> > Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> > [card] [Memory capabilities](#memory-capabilities)
> >
> > Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> > [card] [Intent Classification node](#intent-classification-node)
> >
> > Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> > [card] [Chat-based UI Flows](#chat-based-ui-flows)
> >
> > UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> > [card] [AI Triggers](#ai-triggers)
> >
> > Named parameterized message templates to launch conversational workflows with context.
>
> > [card] [Stop agent response](#stop-agent-response)
> >
> > Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.

> [card]
>
> ### **AI Agents and Knowledge**
>
> The agent-builder story: Custom Agents, MCP integration, Knowledge Bases for RAG, document and web extraction, AI Providers self-service, and PII Guard.
>
> > [card] [Evaluations (Evals)](#evaluations)
> >
> > Score AI node outputs against test cases with 10 built-in evaluators (LLM-as-judge: correctness, conciseness, hallucination, answer-relevance; RAG: groundedness, helpfulness, retrieval-relevance; code: exact-match, Levenshtein, JSON-match). Datasets attached to AI nodes, async judge pipeline via the new `evals-judge` service + 3 Kafka topics, per-org judge model via the new `EVAL` capability (default `gpt-5.4-mini`).
>
> > [card] [Custom Agent nodes](#custom-agent-nodes)
> >
> > AI agents that use MCP tools to act autonomously inside workflows.
>
> > [card] [MCP integration](#mcp-integration)
> >
> > MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> > [card] [Knowledge Bases](#knowledge-bases)
> >
> > Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> > [card] [AI Providers self-service](#ai-providers-self-service)
> >
> > Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> > [card] [PII Guard](#pii-guard-per-entity-detections-on-documents-and-images)
> >
> > Per-AI-node guardrail with Strict / Balanced / Relaxed presets, input/output scans, file redaction. 5.9.0 adds per-entity detections on documents and images. See the 5.9.0 card above.
>
> > [card] [Extract Data from File](#extract-data-from-file)
> >
> > LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> > [card] [Web Page Extractor / Web Crawler](#web-page-extractor-/-web-crawler)
> >
> > Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> > [card] [Context Retrieval](#context-retrieval)
> >
> > RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> > [card] [AI Developer generates Custom Components](#ai-developer-generates-custom-components)
> >
> > Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.

> [card]
>
> ### **UI Flows and Custom Components**
>
> Build user-facing apps without a process. UI Flows reach feature parity with processes; Custom Components let teams ship React code inside the Designer.
>
> > [card] [UI Flows](#ui-flows)
> >
> > Reusable multi-platform UI (web / iOS / Android) as project resources. Navigation Areas, Start Process / Navigate UI actions, Task Manager component. Breadcrumbs + Sessions monitoring. Process Renderer + Start Workflow action + On Load event. Route management + Start Parameters + Session Variables + onClick / On Display events. UI Flow permissions.
>
> > [card] [Custom Components](#custom-components)
> >
> > Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> > [card] [Process Renderer in UI Flows](#process-renderer-in-ui-flows)
> >
> > Embed process renderers inside UI Flows.
>
> > [card] [UI Flow sessions monitoring](#ui-flow-sessions-monitoring)
> >
> > Runtime view with session list, audit log, process tracking, workflow debugging.
>
> > [card] [Accessibility (WCAG 2.1 AA)](#accessibility-wcag-2-1-aa)
> >
> > Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> > [card] [New theme components](#new-theme-components)
> >
> > Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> > [card] [Multi-file bulk upload](#multi-file-bulk-upload)
> >
> > Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> > [card] [Card default collapse + Tables in Collections](#card-default-collapse-+-tables-in-collections)
> >
> > Cards configurable to load collapsed; Table UI components inside Collection prototypes.

> [card]
>
> ### **Integration and Data Platform**
>
> For builders connecting FlowX to enterprise systems, 5.9 adds new data sources, new triggers, parallel workflow execution, REST resilience, and visual query authoring.
>
> > [card] [Email Trigger](#email-trigger)
> >
> > New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> > [card] [Microsoft Outlook data source](#microsoft-outlook-data-source)
> >
> > Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> > [card] [Incoming Webhooks](#incoming-webhooks)
> >
> > New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> > [card] [Oracle Database integration](#oracle-database-integration)
> >
> > Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL.
>
> > [card] [Unmanaged MongoDB data source](#unmanaged-mongodb-data-source)
> >
> > Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> > [card] [Send Notification action + Email Sender](#send-notification-action-+-email-sender)
> >
> > SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> > [card] [Advanced Query Builder](#advanced-query-builder)
> >
> > Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> > [card] [Parallel branches in workflows](#parallel-branches-in-workflows)
> >
> > Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> > [card] [REST endpoint caching + workflow partitioning](#rest-endpoint-caching-+-workflow-partitioning)
> >
> > TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> > [card] [Data mappers + workflow data models](#data-mappers-+-workflow-data-models)
> >
> > Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> > [card] [Proxy Server Connections](#proxy-server-connections)
> >
> > Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> > [card] [Faster authoring loop](#faster-authoring-loop)
> >
> > 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.

> [card]
>
> ### **Process operations**
>
> Day-2 operations for runtime teams: edit live process state, inspect tokens with more context, audit notifications, and operate on workflow instances.
>
> > [card] [Update Process Variables](#update-process-variables)
> >
> > JSON editor for variables on active instances with snapshot history; Compare diff.
>
> > [card] [Stop Run for workflows](#stop-run-for-workflows)
> >
> > Cancel a running workflow instance from the editor.
>
> > [card] [Notification history + template usages](#notification-history-+-template-usages)
> >
> > `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> > [card] [Token view improvements](#token-view-improvements)
> >
> > Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> 5.9.0 adds **Stop workflow instances in runtime** and **Documents in process instances**. See the 5.9.0 cards above.

> [card]
>
> ### **Platform, deployment and infrastructure**
>
> Read this first if you operate a self-hosted deployment. 5.9 adds new microservices, a new deployment mode, and the auth architecture transition.
>
> > [card] [Single-org self-hosted deployment](#single-org-self-hosted-deployment)
> >
> > Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> > [card] [License service](#license-service)
> >
> > Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> > [card] [Authentication: opaque-token → JWT](#authentication-opaque-token-→-jwt)
> >
> > Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> > [card] [New services to deploy](#new-services-to-deploy)
> >
> > `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> > [card] [Native script engine for JavaScript and Python](#native-script-engine-for-javascript-and-python)
> >
> > JavaScript and Python business rules and workflow scripts run on a Node.js + CPython subprocess pool by default. HashMap-style access on `output` is preserved; GraalVM remains available via `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`. See the 5.9.0 card above and the migration audit checklist.
>
> > [card] [Ingress routing and CORS handling](#ingress-routing-and-cors-handling)
> >
> > The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> > [card] [Kafka configuration alignment](#kafka-configuration-alignment)
> >
> > Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> > [card] [OpenTelemetry + SpiceDB DR](#opentelemetry-+-spicedb-dr)
> >
> > OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> > [card] [Task management localization](#task-management-localization)
> >
> > 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.

***

## Deployment notes

> [card] [Deployment guidelines v5.9.0](./deployment-guidelines-v5.9)
>
> Component versions, environment variables, Kafka topics, and self-hosted upgrade guidance.

> [card] [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview)
>
> Consolidated 5.1 LTS → 5.9 LTS migration guide. Direct upgrade to 5.9.0.


# Deployment guidelines v5.9.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1

Component versions, configuration, and deployment notes for FlowX.AI 5.9.1 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.1 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.0 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.0 → 5.9.1**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

## Component versions

### Core components

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **process-engine** | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.3 |
| **admin** | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.3 |
| **designer** | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.4 |
| **cms-core** | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.2 |
| **scheduler-core** | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.2 |
| **events-gateway** | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.2 |
| **notification-plugin** | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.2 |
| **document-plugin** | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.2 |
| **task-management-plugin** | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.2 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |
| **data-search** | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.2 |
| **audit-core** | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.2 |
| **advancing-controller** | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.2 |
| **integration-designer** | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.3 |
| **application-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **runtime-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **data-sync** | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.2 |
| **authorization-system** | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.2 |
| **nosql-db-runner** | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.2 |
| **email-gateway** | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-native-sdk** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/core-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **react-saas** | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.20 |
| **Android renderer** | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.24 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-knowledgebase-rag** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-embedder** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-agent-builder** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-gateway** | 10.17.0 | 10.7.0 | - | - |
| **ai-platform-ai-analyst** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-assistant** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-ai-designer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-developer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-planner** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-kb-enrichment** | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.1 adds two Kafka topics. Both are **auto-provisioned by the Helm chart** — no manual creation is required for standard deployments. The names and env vars are listed here for environments that provision topics or ACLs manually.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | application-manager | process-engine | Runtime config-param change events; invalidates the build cache |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine | integration-designer | Notifies that a runtime instance has been terminated |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin | process-engine | Resource cache eviction triggered when a process version changes |
| `ai.flowx.evals.suggestions.job.request.v1` | integration-designer | AI Platform | Evaluation improvement-suggestion job requests |
| `ai.flowx.evals.suggestions.job.response.v1` | AI Platform | integration-designer | Evaluation improvement-suggestion job responses |

Topic env vars and consumer groups:

| Topic | Producer var (OUT) | Consumer var (IN) | Consumer group |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | `config-params` |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_OUT` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_IN` | `integration-designer-runtime-instance-terminated-group` |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT_IN` | `resource-cache-evict` |
| `ai.flowx.evals.suggestions.job.request.v1` | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT` | — (consumed by AI Platform) | — |
| `ai.flowx.evals.suggestions.job.response.v1` | — (produced by AI Platform) | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN` | `integration-designer-evals-suggestions-response-group` |

For the config-param cache-invalidation behavior, see [Engine setup → Topics related to runtime config params](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-runtime-config-params). For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.1 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including split AI permissions, the legacy script flag, and File Storage and document-preview fixes.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.0 → 5.9.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.1** is a maintenance release for the 5.9.x LTS with bug fixes, security patches, and a few targeted improvements:
>
> * **Import/export:** stability and cross-version compatibility fixes
> * **Split AI permissions:** separate governance for AI runtime usage and AI build-time tooling
> * **Legacy script flag:** per-rule Native / GraalVM script runtime selection
> * **File Storage and document-preview improvements**
> * Wide set of Designer, Renderer, and platform bug fixes
> * No breaking changes; fully compatible upgrade from 5.9.0

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Split AI permissions**](#split-ai-permissions) - Independent governance for AI usage and AI build tooling.\
> 📝 [**Legacy script flag**](#legacy-script-flag) - Per-rule Native / GraalVM script runtime selection.\
> 🗂️ [**File Storage improvements**](#file-storage-improvements) - FTP connection and preview fixes.\
> 📄 [**File Preview scroll events**](#file-preview-scroll-events) - Scroll-trigger event handlers for the File Preview component.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, Workflows, and backend bug fixes plus security patches.
>
> ***
>
> ### **Split AI permissions**
>
> > [card] Separate governance for AI usage and AI build tooling
> >
> > > [tab] Overview
> > >
> > > AI permissions are now split into two independent controls, so administrators can govern **AI runtime usage** separately from **AI build-time tooling** (AI Designer, agent building, code generation).
> >
> > > [tab] Behavior
> > >
> > > * When AI is turned off, AI-related icons and entry points are hidden rather than shown in a disabled state.
> > > * AI nodes in workflows behave consistently with the gateway's availability.
> > > * Build-time AI helpers (code generation, "Add comment") follow the dev-agent permission rather than the runtime AI permission.
> >
> > All Deployments
>
> ***
>
> ### **Legacy script flag**
>
> > [card] Per-rule Native / GraalVM script runtime
> >
> > Business rules, reusable functions, and node rules can now choose their script engine individually: the current **native** engine (the 5.9 default) or the legacy **GraalVM** engine. Rules created before the switch to native keep running on GraalVM until you migrate them, while new rules default to native, so teams can move scripts across at their own pace. The per-rule selector only appears for rules that support GraalVM; new rules run on native.
> > All Deployments
>
> ***
>
> ### **File Storage improvements**
>
> > [card] FTP connection and preview fixes
> >
> > * FTP **test connection** now resolves configuration-parameter placeholders before connecting.
> > * **File operations** also resolve configuration-parameter placeholders at runtime.
> > * FTP **file preview** works when the root path has no leading slash.
> >   All Deployments
>
> ***
>
> ### **File Preview scroll events**
>
> > [card] Scroll-trigger event handlers for File Preview
> >
> > The **File Preview** component now supports **scroll-trigger event handlers** (including a "document end" trigger), configurable in the Designer and handled by the web, iOS, and Android renderers. They let a flow detect when a user scrolls through a document or reaches its end.
> >
> > This is built for consent and disclosure use cases such as banking flows that must prove, per local regulation, that the user actually read an agreement. You can keep an action such as a **Submit** or **Accept** button hidden or disabled until the document-end event handler fires; that handler can be a simple local script that sets a flag to enable the button.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Forms to validate:** fixed scrolling through the full component hierarchy, placeholder updates, and incorrect selection of chat and tab-bar components.
> > > > * **Process instances:** fixed a browser crash when loading instances with very large execution graphs.
> > > > * **Theme admin:** fixed theme content being lost when using "copy to".
> > > > * **UI Flow:** fixed images not displaying in preview after refresh, and a missing theme UUID when returning from an expired UI Flow.
> > > > * **Actions:** stopped GET actions firing with undefined parameters.
> > > > * **Modals:** fixed dropdown flicker and layout issues with long key names.
> > >
> > > > [accordion] Renderer fixes (Web / React / React Native)
> > > >
> > > > * **Web:** fixed missing button shadow, modal content padding, and rendering when a media-file storage path is null.
> > > > * **File Preview:** fixed preview not rendering correctly, events not firing inside collections, fixed height not applied at runtime, and CORS errors when accessing preview resources.
> > > > * **React Native:** fixed date-picker shifting to a previous day and input/textarea retaining focus after moving to another component.
> > > > * **Task management:** fixed header theming (React/Angular) and the filter window disappearing after applying criteria.
> > > > * **File upload:** the upload button now supports a configurable icon, set in the Designer and rendered on web, iOS, and Android.
> >
> > > [tab] Workflows & AI
> > >
> > > > [accordion] Workflow fixes
> > > >
> > > > * Fixed END PARALLEL output including data from before the parallel branches started.
> > > > * Optimized storage of running steps for workflows.
> > > > * Fixed a crash in NoSQL node run logs when a node failed before building its options.
> > > > * Workflows and processes launched from a UI Flow now inherit the build from the parent UI Flow.
> > > > * AI node failures now surface the error details and model reasoning in the workflow run logs, making failed AI steps easier to diagnose.
> > >
> > > > [accordion] AI improvements & fixes
> > > >
> > > > * **AI Designer** generates more reliable UI from a flat template format (replacing the previous 3-level nesting), supports additional component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates by applying changes incrementally instead of regenerating from scratch, and can now generate **reusable UI templates**.
> > > > * Fixed agent responses reappearing in chat after stop and refresh.
> > > > * Fixed duplicated messages in the builder-agent chat.
> > > > * **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
> > > > * **Platform Status** now reports AI Platform components and their databases alongside the core services.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * Fixed a null value being wrongly cached when looking up the "All end-users" group, which could block logins until data-sync completed.
> > > > * Fixed copying a process or workflow to another project: the copy now succeeds, and copied workflows appear in the target project.
> > > > * Fixed an invited Designer user added as an Organization owner not being assigned to a workspace.
> > > > * Improved merge-conflict handling for custom components and UI Flows, with clearer resource identification.
> > > > * Hide/disable conditions on UI templates, processes, and UI Flows are now applied at runtime for Designer users without workspace access.
> > > > * Fixed a 500 (duplicate key) error when activating a start timer event after a new build regenerated the process resource ID.
> > > > * Fixed a 500 error when opening a Usage Overview.
> > > > * Organization settings navigation and design improvements.
> > > > * **Runtime config params:** changes to runtime configuration parameters now propagate to the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
> > > > * **Microsoft Outlook connections** now support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.1 is fully compatible with 5.9.0. No breaking changes; standard deployment procedures apply.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.0 → 5.9.1 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.1 are tracked in the [5.9.1 deployment guidelines](./deployment-guidelines-v5.9.1).&#x20;
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2

Component versions, configuration, and deployment notes for FlowX.AI 5.9.2 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.2 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.1 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.1 → 5.9.2**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and converts your data. If you did not apply that workaround, no action is needed.

> [!WARNING]
>
> **Manually marked Liquibase changesets.** If any Liquibase changesets were manually marked as executed (MARK\_RAN) to work around failures during earlier 5.9.x upgrade attempts, those records must be removed after upgrading to 5.9.2 so the corrected changesets can run. Contact FlowX support for the exact list of affected changesets before removing anything. If you did not mark any changesets manually, no action is needed.

## Component versions

### Core components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.162.1 | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.7 |
| **admin** | 10.141.1 | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.7 |
| **designer** | 10.260.7 | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.10 |
| **cms-core** | 10.102.3 | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.3 |
| **scheduler-core** | 10.85.1 | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.3 |
| **events-gateway** | 10.90.1 | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.4 |
| **notification-plugin** | 10.100.2 | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.3 |
| **document-plugin** | 10.113.2 | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.3 |
| **task-management-plugin** | 10.102.1 | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.3 |
| **reporting-plugin**\* | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.7 |
| **data-search** | 10.83.1 | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.3 |
| **audit-core** | 10.93.1 | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.3 |
| **advancing-controller** | 10.89.1 | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.3 |
| **integration-designer** | 10.189.2 | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.4 |
| **application-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **runtime-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **data-sync** | 10.98.0 | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.4 |
| **authorization-system** | 10.112.1 | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.5 |
| **nosql-db-runner** | 10.92.1 | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.3 |
| **email-gateway** | 10.91.1 | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.88.1 | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.60.1 | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.23.1 | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.78.1 | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-native-sdk** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/core-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **react-saas** | 10.260.7 | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.6 | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.25 |
| **Android renderer** | 10.5.6 | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.31 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.0 | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.0 | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.0 | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.0 | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.0 | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.0 | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.25.0 | 10.17.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.0 | - | - | - | - |
| **ai-assistant** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.0 | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.2 | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.2 introduces no new Kafka topics over 5.9.1. For the topics added in 5.9.1, see the [5.9.1 deployment guidelines](../v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics); for the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.2 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

* **Kafka reconnect backoff:** platform services now default to a gentler broker-reconnect backoff — `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MS` `1000` / `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MAX_MS` `10000` (and the consumer equivalents) — and repetitive Kafka NetworkClient connection errors log at a quieter level, tunable via `LOGGING_LEVEL_KAFKA_NETWORK_CLIENT` (default `ERROR`). No action needed unless you previously tuned these.&#x20;
* **Resource-server security type:** the default for `idp.resourceServer.securityType` on the AI services changes to `jwt`. If you previously set the security type to `jwt` explicitly as a workaround, that override is no longer needed and can be removed.&#x20;

#### Data partitioning and archiving

5.9.2 adds configuration for the archiving lifecycle on the process-engine and Integration Designer. All new settings default to off, so no action is required on upgrade.&#x20;

* **Stuck-instance termination:** an optional sweep (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`, default `false`) terminates instances that would otherwise block archiving. Enable it, plus its cron and batch-size, if archiving stalls on unfinished data.
* **Legacy backfill:** one-shot backfills of `partition_id` (`FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED`) and `organization_id` (`FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED`), both default `false`, populate legacy rows when you first turn partitioning on. The organization-ID backfill is optional on self-hosted and can remain `false`.

> [!WARNING]
>
> **Partitions that still contain unfinished instances are not archived.** Starting with 5.9.2, the archiving job detaches a partition only when every process instance in it has reached a finished state (`FINISHED`, `FINISHED_WITH_ERROR`, `FAILED`, `EXPIRED`, `ABORTED`, `DISMISSED`, or `TERMINATED`). A single instance still in `CREATED`, `STARTED`, or `ON_HOLD` blocks the entire partition; it is retried on the next archiving run. The same rule applies to workflow instances on the Integration Designer, where a `STARTED` workflow instance blocks its partition. If partitions accumulate unarchived, terminate the blocking instances — set process expiry, or turn on the stuck-instance termination sweep above.

For the full property tables and defaults, see [Partitioning & archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) (process-engine) and [Integration Designer setup → Workflow partitioning](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration).

#### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them as part of this upgrade. The bundled Qdrant subchart is renamed the same way, so any explicit references to its service host must be updated too.

> [!WARNING]
>
> Core platform services resolve AI Platform components by these new names. Upgrade the AI Platform chart and the core platform services to 5.9.2 together — running a 5.9.1 AI Platform chart against 5.9.2 core services (or the reverse) breaks AI features.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including expanded audit logging, copy-with-roles, and the app-manager organization-ID migration fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.1 → 5.9.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.2** is a maintenance release for the 5.9.x LTS. It pairs a broad bug-fix pass with a few targeted improvements:
>
> * **Expanded audit logging:** coverage for sharing, invitations, user and group management, and process-instance and UI-flow actions
> * **Copy with roles:** copying a resource now also copies its associated roles
> * **Self-hosted upgrade fixes:** smoother installation and upgrade from 5.1.x on self-hosted environments
> * **Key fixes:** active-policy override user list, project-version merge, reusable UI templates in nested containers, and audit-log user filtering&#x20;
> * Wide set of Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.9.2 brings bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions.\
> 👥 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, and backend bug fixes plus security patches.
>
> ***
>
> ### **Expanded audit logging**
>
> > [card] Broader audit coverage for access and lifecycle actions
> >
> > Audit logging now records a wider set of actions, including **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> > All Deployments
>
> ***
>
> ### **Copy with roles**
>
> > [card] Roles travel with copied resources
> >
> > Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Reusable UI templates:** fixed actions missing at runtime when a template is nested in multiple levels of containers.&#x20;
> > > > * **Use in reporting:** the reporting toggle is now available on UI flows and workflows, matching the existing process setting.
> > > > * **UI action keys:** keys to save for collection items and bundled custom-component inputs are now computed automatically, and mapped object keys for collections and custom components are available in runtime data.&#x20;
> > > > * **SQL data sources:** queries on SQL data sources can now be tested from the builds list, mirroring the existing NoSQL runtime test flow.&#x20;
> > > > * **Event handlers:** the Event Handlers section now appears higher in the component configuration panel.&#x20;
> > > > * **Audit logs:** filtering audit entries by user now works when the username differs from the email address.&#x20;
> > > > * **AI agents and data models:** AI Designer and AI Developer now use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it. &#x20;
> > >
> > > > [accordion] Renderer fixes
> > > >
> > > > * **Chat:** the floating chat position is now calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.&#x20;
> > > >
> > > > This release also includes stability fixes across the web, React, React Native, Android, and iOS renderers.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * **Active policy:** fixed the user list appearing empty on the override active-policy form.&#x20;
> > > > * **Project version merge:** fixed a 500 error that could occur during project-version merge.&#x20;
> > > > * **CMS enumerations:** cascading-enum value lookups now resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.&#x20;
> > > > * **Build export with media files:** exporting a build with media file content included now produces an archive that actually contains the binaries.&#x20;
> > > > * **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.&#x20;
> > > > * **Redis Cluster:** UI-template cache keys are now hash-tagged so related keys map to the same cluster slot, preventing cross-slot errors on Redis Cluster deployments.&#x20;
> > > > * **Workflow data:** Mongo partition archiving now batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine was fixed. See [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) for the partitioning and archiving settings.&#x20;
> > > > * **Data sync with private CA certificates:** the data-sync job now runs the same certificate-initialization step as the other platform services, so data-sync migrations that call HTTPS endpoints (such as Keycloak) no longer fail certificate validation in environments using an internal certificate authority.&#x20;
> > > > * **Self-hosted installation and upgrade:** fixed Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding on self-hosted environments. As part of this, the migration-created default end-user group is renamed from `User` to `Users Group`; check the upgrade warning under Additional information if you map IDP groups into FlowX.&#x20;
> > > > * **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.&#x20;
> > > > * **AI workflow nodes:** JSON schema fields now support `${}` placeholders.&#x20;
> > > > * **Multi-KB retrieval:** retrieval can span multiple knowledge bases in a workflow.&#x20;
> > > > * **AI structured output:** responses from AI nodes with a response schema are now validated against it, with automatic repair retries, and node logs include richer run diagnostics such as the failure reason and rejected output.&#x20;
> > > > * **Document Parser:** a new LiteParse engine parses PDFs and images fully locally without GPU or AI calls, and OCR language support expands to English, Romanian, Hungarian, and Bulgarian.&#x20;
> > > > * **Knowledge bases:** a Custom Agent node can now select multiple knowledge bases, each exposed to the agent as its own retrieval tool, replacing the parallel-nodes workaround.&#x20;
> > > > * **Chat file uploads:** end users can attach multiple files in a chat-driven app; uploads are indexed into a knowledge base scoped to the chat session so AI nodes answer grounded in that content.&#x20;
> > > > * **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.&#x20;
> > > >
> > > > This release also includes a broad set of additional fixes and stability improvements across Designer and backend services.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.2 is fully compatible with 5.9.1; standard deployment procedures apply. One migration renames a default end-user group, which needs attention only if group membership is mapped from Keycloak or an external IDP (see the warning below).
>
> > [!WARNING]
> >
> > **Default end-user group renamed from `User` to `Users Group`.** The group that the 5.1.x upgrade migration creates for users who held the `FLOWX_ROLE` realm role is renamed from `User` to `Users Group` when you upgrade to 5.9.2 or any later release. Runtime group matching is by exact name: if a Keycloak **Group Membership** mapper or an external IDP claim emits the old name `User` into `attributes.runtimeGroups`, those values no longer match any FlowX group and affected users **lose solution access on their next sign-in, with no error logged**. Update the mapper or source group name to `Users Group` as part of the upgrade. Groups your admins created themselves, including any you named `User`, are not renamed. See the [runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) setup for where this value is configured.
>
> > [!WARNING]
> >
> > **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration so it converts existing data correctly. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and actually converts your data. If you did not apply that workaround, no action is needed.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.1 → 5.9.2 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.2 are tracked in the [5.9.2 deployment guidelines](./deployment-guidelines-v5.9.2).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3

Component versions, configuration, and deployment notes for FlowX.AI 5.9.3 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.3 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.2 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.2 → 5.9.3**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.0 or 5.9.1 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.165.0 | 10.162.1 | 10.135.0 | 10.106.0 | 9.76.3 |
| **admin** | 10.144.0 | 10.141.1 | 10.116.0 | 10.93.0 | 9.76.3 |
| **designer** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **cms-core** | 10.105.0 | 10.102.3 | 10.86.0 | 10.67.0 | 9.47.3 |
| **scheduler-core** | 10.87.0 | 10.85.1 | 10.70.0 | 10.53.0 | 9.36.3 |
| **events-gateway** | 10.93.0 | 10.90.1 | 10.72.0 | 10.55.0 | 9.37.3 |
| **notification-plugin** | 10.103.0 | 10.100.2 | 10.83.0 | 10.64.0 | 9.40.3 |
| **document-plugin** | 10.116.0 | 10.113.2 | 10.94.0 | 10.75.0 | 9.45.3 |
| **task-management-plugin** | 10.105.0 | 10.102.1 | 10.84.0 | 10.66.0 | 9.44.4 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.85.0 | 10.83.1 | 10.69.0 | 10.52.0 | 9.33.3 |
| **audit-core** | 10.95.0 | 10.93.1 | 10.79.0 | 10.63.0 | 9.41.3 |
| **advancing-controller** | 10.91.0 | 10.89.1 | 10.73.0 | 10.55.0 | 9.36.3 |
| **integration-designer** | 10.192.0 | 10.189.2 | 10.162.0 | 10.128.0 | 9.60.3 |
| **application-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **runtime-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **data-sync** | 10.100.0 | 10.98.0 | 10.81.0 | 10.58.0 | 9.34.2 |
| **authorization-system** | 10.115.0 | 10.112.1 | 10.96.1 | 10.77.0 | 9.44.4 |
| **nosql-db-runner** | 10.94.0 | 10.92.1 | 10.75.0 | 10.56.0 | 9.32.3 |
| **email-gateway** | 10.93.0 | 10.91.1 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.90.0 | 10.88.1 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.62.0 | 10.60.1 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.25.0 | 10.23.1 | 10.8.0 | - | - |
| **license** | 10.80.0 | 10.78.1 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-native-sdk** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/core-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **react-saas** | 10.265.6 | 10.260.7 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.11 | 10.5.6 | 10.4.1 | 10.3.0 | 9.0.27 |
| **Android renderer** | 10.6.6 | 10.5.6 | 10.5.0 | 10.3.0 | 9.0.37 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](../v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.1 | 10.9.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.1 | 10.9.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.1 | 10.9.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.1 | 10.9.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.1 | 10.9.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.1 | 10.9.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.27.0 | 10.25.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.1 | 10.9.0 | - | - | - |
| **ai-assistant** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.1 | 10.9.0 | - | - | - |
| **flowx-docs** | 5.9.3 | 5.9.2 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.3 introduces no new Kafka topics over 5.9.2. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.3 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Events Gateway — Redis connection pool for blocking mode

The Events Gateway's blocking read path is rebuilt on a dedicated Redis connection pool, fixing a connection leak that could previously require periodic Events Gateway restarts under sustained load. The new settings ship with working defaults — no action is required on upgrade.

| Environment variable | Default | Change in 5.9.3 |
| - | - | - |
| `EVENTS_REDIS_POOL_ENABLED` | `true` | New — dedicated connection pool for blocking reads |
| `EVENTS_REDIS_POOL_MAXTOTAL` | `50` | New — maximum pooled connections |
| `EVENTS_REDIS_POOL_MAXIDLE` | `50` | New — maximum idle pooled connections |
| `EVENTS_REDIS_POOL_MINIDLE` | `5` | New — minimum idle pooled connections |
| `EVENTS_REDIS_POOL_MAXWAITMILLIS` | `5000` | New — wait time for a pooled connection before failing |
| `EVENTS_REDIS_SSE_BUFFERSIZE` | `256` | New — per-subscriber SSE backpressure buffer |
| `EVENTS_REDIS_BLOCKDURATIONSECONDS` | `1` | Default lowered from `5` — shortens the blocking-read reissue interval |

If you previously set `EVENTS_REDIS_BLOCKDURATIONSECONDS` explicitly, review whether the new default suits your setup. See the [Events Gateway setup guide](/5.9/setup-guides/events-gateway-setup#events) for the full configuration reference.

#### Integration Designer — workflow topic partitions

`FLOWX_WORKFLOW_TOPICPARTITIONS` (default `1`) sets the number of partitions for auto-created workflow Kafka topics (used with `FLOWX_WORKFLOW_CREATETOPICS`). Existing topics are not modified; the setting applies to newly created topics only.&#x20;

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including the Events Gateway Redis connection-leak fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.2 → 5.9.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.3** is a maintenance release for the 5.9.x LTS:
>
> * **Real-time event delivery:** fixes a Redis connection leak in the Events Gateway that could previously require periodic restarts under sustained load
> * **Key fixes:** build import race during multi-dependency imports, task-management allocation rules, project re-creation error handling
> * **New configuration:** Events Gateway connection-pool tuning and workflow Kafka topic partitions
> * Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.2

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform improvements**](#platform-improvements) - Events Gateway stability, Designer and backend bug fixes, security patches.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Real-time event delivery:** fixed a Redis connection leak in the Events Gateway. Blocking reads now run on a dedicated connection pool with Redis Cluster support, eliminating the gradual connection buildup that could previously require periodic Events Gateway restarts. New tuning options are available — see the [deployment guidelines](./deployment-guidelines-v5.9.3#configuration-changes).
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it, and duplicate rules are no longer created when Save is clicked twice. Task views also no longer reset when the same view is open from different workspaces.&#x20;
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **Designer stability:** fixed a freeze when opening Runtime after expanding a component's Permissions section, and a pending AI UI-generation draft no longer locks the process diagram read-only.&#x20;
> > > > * **Date Picker:** the calendar now anchors correctly to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.&#x20;
> > > > * **Workflows:** fixed a silent workflow freeze that could occur after a step exhausted its retries.&#x20;
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior. UI Flows on iOS also gain support for the `additionalData` object.
> > > >   &#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Media Library:** PDF assets in the list can now be opened in a new tab directly from the Media Library.
> > > > * **Process start loading:** web renderers now keep the loading indicator visible until the first user task renders, matching the mobile SDK behavior.&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.3 is fully compatible with 5.9.2. No configuration changes are required on upgrade; new tuning options ship with working defaults.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.2 → 5.9.3 with no breaking changes
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps are required for this maintenance release. Upgrading directly from 5.9.0 or 5.9.1? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.3](./deployment-guidelines-v5.9.3).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4

Component versions, configuration, and deployment notes for FlowX.AI 5.9.4 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.4 is a maintenance release for the 5.9.x LTS line. The platform upgrade from 5.9.3 is non-breaking, but this release changes how the Helm charts express the container image location, so review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.3 → 5.9.4**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Helm values change.** The charts now express the image location as `image.registry` plus `image.repository` instead of one combined path. Deployments that set `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move it out before upgrading — see [Helm charts: image registry split](#helm-charts-image-registry-split).

> [!NOTE]
>
> **Upgrading from 5.9.0, 5.9.1, or 5.9.2 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.171.3 | 10.165.0 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.149.3 | 10.144.0 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.110.4 | 10.105.0 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.91.2 | 10.87.0 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.97.2 | 10.93.0 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.107.4 | 10.103.0 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.121.3 | 10.116.0 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.109.3 | 10.105.0 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.89.2 | 10.85.0 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.99.2 | 10.95.0 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.95.2 | 10.91.0 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.197.5 | 10.192.0 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.104.3 | 10.100.0 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.119.3 | 10.115.0 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.98.2 | 10.94.0 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.98.2 | 10.93.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.95.2 | 10.90.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.66.2 | 10.62.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.30.2 | 10.25.0 | 10.8.0 | - | - |
| **license** | 10.84.2 | 10.80.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.275.0 | 10.265.6 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.0 | 10.5.11 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.8.0 | 10.6.6 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.2 | 10.9.1 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.10.2 | 10.9.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.10.2 | 10.9.1 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.10.2 | 10.9.1 | 10.1.1 | - | - |
| **speech-to-text** | 10.10.2 | 10.9.1 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.10.2 | 10.9.1 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.32.2 | 10.27.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.10.2 | 10.9.1 | - | - | - |
| **ai-assistant** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.10.2 | 10.9.1 | - | - | - |
| **flowx-docs** | 5.9.4 | 5.9.3 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.4 introduces no new Kafka topics over 5.9.3. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Apply the Helm values change described in [Configuration changes](#configuration-changes), if it affects your setup.
2. Update container images to the 5.9.4 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Helm charts: image registry split

Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.

```yaml theme={"dark"}
# Before
image:
  repository: <registry>/<image-name>

# After
image:
  registry: <registry>
  repository: <image-name>
```

The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.

**Upgrade notes**

* **If you set `global.imageRegistry` to point the charts at your own registry** (the standard, documented approach): no action is required. Your override continues to work, and it now applies cleanly to the default bare repository names.
* **If you embedded the registry inside `image.repository`** (for example `image.repository: harbor.mycorp.internal/flowx/<image-name>`): move the registry portion out. Set it through `global.imageRegistry`, or the chart's `image.registry`, and let `image.repository` fall back to its default bare image name. Leaving the registry in `image.repository` alongside the now-populated `image.registry` prepends the registry twice.

  This applies to deployments configured from the FlowX setup guides before 5.9.4, which showed the combined form. If your values files were built from those examples, check them before upgrading.

#### Events Gateway service account

Events Gateway now authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`, in the service-accounts realm. It needs this identity to resolve and authorize a subscription before admitting the stream.

Two new configuration values are involved, and both take the **same secret**:

| Service | Environment Variable | Purpose |
| - | - | - |
| authorization-system | `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXEVENTSGATEWAYSA` | Secret the migration assigns to the client it creates |
| events-gateway | `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Secret Events Gateway authenticates with |

**Upgrade notes**

* **If you deploy with the FlowX Helm charts and authorization-system runs its migrations with Keycloak admin access**: no action is required. The chart already maps both values to the `KEYCLOAK_EVENTS_GATEWAY_CLIENT_SECRET` key of the `keycloak-flowx-realm-clients` secret, and the authorization-system migration creates the client and grants it the `SA_FLOWX` role.
* **If you manage Keycloak clients outside the chart** (external IdP, or authorization-system cannot provision clients): create `flowx-events-gateway-sa` in the service-accounts realm as a confidential client with service accounts enabled and only the client-credentials grant, then supply its secret to both values above.

> [!WARNING]
>
> If `flowx-events-gateway-sa` already exists, the migration leaves its secret untouched by design. A pre-existing client whose secret does not match the one given to Events Gateway will not be corrected on upgrade, and Events Gateway will fail to authorize subscriptions. Make the two match manually in that case.

#### Liquibase migration lock moves to database session locks

The lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so a stale `databasechangeloglock` row no longer needs clearing by hand. On any other database, Liquibase falls back to its standard row-based lock.

The previous mechanism verified the lock-holder pod through the Kubernetes API. That dependency is gone:

* Service accounts no longer need the `get pods/status` permission, and the FlowX Helm charts no longer create the corresponding Role and RoleBinding. If you maintain that RBAC outside the charts, you can remove the grant.
* The lock keeps working on Kubernetes 1.33 and newer, where the previous mechanism silently deactivated itself.

**Oracle deployments** must grant each FlowX service's database user the following before upgrading. A service whose grants are missing stops at startup with an error naming the missing grant:

```sql theme={"dark"}
GRANT EXECUTE ON SYS.DBMS_LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$SESSION TO <app_user>;
```

PostgreSQL deployments need no action: advisory locks require no additional grant.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, the Angular 21 renderer upgrade, and a Helm chart image-registry change.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. The platform upgrade from **5.9.3 → 5.9.4** requires no data migration, but it does change how the Helm charts express the container image location. Review the [deployment guidelines](./deployment-guidelines-v5.9.4#configuration-changes) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.4** is a maintenance release for the 5.9.x LTS:
>
> * **Helm charts:** the container image reference splits into `image.registry` and `image.repository`, making `global.imageRegistry` a single chart-wide override
> * **Angular 21:** the Angular renderer and the web SDKs move to Angular 21
> * **Key fixes:** branch merges no longer getting stuck, build export retry after a dependency timeout, deleting actions that call functions, gateway expression failures surfaced as incidents, library resource overview
> * **Cross-version import:** an imported theme is completed from the destination's system theme, so nothing is missing after importing an older export
> * Designer, renderer, and backend stability fixes plus security patches
> * No data migration; the only upgrade action is the Helm values change, and only for one override pattern

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, plus a Helm chart change that affects some self-hosted deployments.
>
> 📦 [**Helm chart image registry**](#helm-chart-image-registry) - `image.repository` splits into `image.registry` + `image.repository`\
> 🅰️ [**Angular 21**](#angular-21) - The Angular renderer and web SDKs move to Angular 21\
> 🔧 [**Platform improvements**](#platform-improvements) - Bug fixes and security patches
>
> ***
>
> ### **Helm chart image registry**
>
> > [card] image.repository splits into image.registry + image.repository
> >
> > Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.
> >
> > ```yaml theme={"dark"}
> > # Before
> > image:
> >   repository: <registry>/<image-name>
> >
> > # After
> > image:
> >   registry: <registry>
> >   repository: <image-name>
> > ```
> >
> > The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.
> >
> > > [!WARNING]
> > >
> > > **Check your values files before upgrading.** If you set `global.imageRegistry`, no action is needed. If you embedded the registry inside `image.repository`, move it out first, or the registry is prepended twice. This includes values files built from the FlowX setup guides before 5.9.4, which showed the combined form. Full before-and-after in the [deployment guidelines](./deployment-guidelines-v5.9.4#helm-charts-image-registry-split).
> >
> > All Deployments
>
> ***
>
> ### **Angular 21**
>
> > [card] Angular renderer and web SDKs on Angular 21
> >
> > The Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps embedding the Angular SDK should be on Angular 21 before taking 5.9.4.
> >
> > Angular does not support skipping a major in a single update, so step through the official update guide one major at a time. The **npm** and **node** requirements are unchanged from 5.9.3.
> >
> > See the [Angular SDK requirements](/5.9/sdks/angular-renderer#angular-project-requirements) for the current version floor, and the [Angular migration guide](/5.9/migrating-from-5.1-lts/angular#framework-upgrade-angular-19-→-21) for the upgrade path.
> >
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build export:** retrying a build export now re-attempts a dependency library whose own export ended in a timeout, instead of failing again immediately. Previously the retry skipped the timed-out dependency, so the parent build could never finish; the workaround was to export that dependency directly first.&#x20;
> > > > * **Actions:** deleting an action whose business rule calls a function now works instead of returning a server error. This affected any action at any nesting level, in both projects and libraries; the workaround was to delete the rule from the action first.&#x20;
> > > > * **Gateways:** an expression that fails to evaluate on an exclusive gateway now surfaces as an incident on the process instance. Previously the failure appeared only in the service logs, with no feedback in the platform.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection. Changing the page size no longer opens the wrong process from the list. &#x20;
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives while a background synchronization is still running, and merging versions no longer fails with a navigation-areas error.&#x20;
> > > > * **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds. The page index was previously lost on back-navigation.&#x20;
> > > > * **Reusable UI templates:** static input mappings configured on a reusable template are now applied at runtime.&#x20;
> > > > * **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.&#x20;
> > > > * **Entry points:** the entry-point picker in version settings now lists only processes and UI flows from the current project. Resources from dependency libraries were previously offered and could be selected.&#x20;
> > > > * **Themes and CMS resources:** exporting a theme no longer includes duplicate non-system copies of system icons, so repeated imports stop multiplying them, and importing no longer leaves system substitution tags missing.&#x20;
> > > > * **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output built from trailing empty cells and rows.&#x20;
> > > > * **Generated documents:** a document whose storage write fails now returns an error instead of being recorded as successful with a download path that cannot be opened. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.&#x20;
> > > > * **Renderers:** the document preview shows its subtitle again, and the file-upload error message picks up the configured theme.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Cross-version import:** importing a project build or version exported from an older platform line now completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten, so customizations survive.&#x20;
> > > > * **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.&#x20;
> > > > * **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.&#x20;
> > > > * **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.&#x20;
> > > > * **Integration Designer performance:** service startup no longer scans the full token-instance collection to warm up, and the run-list summary queries are indexed and gated.&#x20;
> > > > * **Database migrations:** the lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so there is no stale `databasechangeloglock` row to clear by hand. The previous mechanism recovered a stuck lock through the Kubernetes API, which required the `pods/status` permission on every service account and silently deactivated on Kubernetes 1.33 and newer. Oracle deployments need new database grants before upgrading: see the [deployment guidelines](./deployment-guidelines-v5.9.4#liquibase-migration-lock-moves-to-database-session-locks).&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade compatibility:** FlowX.AI 5.9.4 is compatible with 5.9.3. No data migration is required. One deployment-level change applies: the Helm charts split the image reference into `image.registry` and `image.repository`. Oracle deployments also need new database grants for the Liquibase migration session lock.
>
> > [!WARNING]
> >
> > **Helm values migration.** Deployments that redirect images through `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move the registry portion out before upgrading. See [Configuration changes](./deployment-guidelines-v5.9.4#configuration-changes).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Direct upgrade from 5.9.3 → 5.9.4. No data migration; review the Helm values change first.
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. The Angular SDK moves to Angular 21.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.4](./deployment-guidelines-v5.9.4).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5

Component versions, configuration, and deployment notes for FlowX.AI 5.9.5 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.5 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.4 is non-breaking and requires no data migration. The headline addition, native PostgreSQL partitioning, is opt-in: deployments that never enabled data partitioning are not affected. Review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.4 → 5.9.5**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.3 or earlier directly?** Review the [5.9.4 deployment guidelines](../v5.9.4-august-2026/deployment-guidelines-v5.9.4) first: the Helm image registry split applies when you skip 5.9.4. Upgrading from 5.9.0, 5.9.1, or 5.9.2, also review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) for the organization-ID migration fix and manually marked Liquibase changesets.

## Component versions

### Core components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.10 | 10.171.3 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.7 | 10.149.3 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.7 | 10.110.4 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.6 | 10.91.2 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.100.7 | 10.97.2 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.110.7 | 10.107.4 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.7 | 10.121.3 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.6 | 10.109.3 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.6 | 10.89.2 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.6 | 10.99.2 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.7 | 10.95.2 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.200.9 | 10.197.5 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.7 | 10.104.3 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.7 | 10.119.3 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.6 | 10.98.2 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.101.6 | 10.98.2 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.6 | 10.95.2 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.6 | 10.66.2 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.7 | 10.30.2 | 10.8.0 | - | - |
| **license** | 10.87.6 | 10.84.2 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB**: see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.282.5 | 10.275.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.2 | 10.6.0 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.9.3 | 10.8.0 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.0 | 10.10.2 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.0 | 10.10.2 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.0 | 10.10.2 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.0 | 10.10.2 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.0 | 10.10.2 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.0 | 10.10.2 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.6 | 10.32.2 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.0 | 10.10.2 | - | - | - |
| **ai-assistant** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.0 | 10.10.2 | - | - | - |
| **flowx-docs** | 5.9.5 | 5.9.4 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.5 introduces no new Kafka topics over 5.9.4. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Review [Configuration changes](#configuration-changes): everything new in this release is opt-in or ships with a safe default, so no values change is required for a standard upgrade.
2. Update container images to the 5.9.5 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Native PostgreSQL partitioning (opt-in)

Process-instance archiving on PostgreSQL can now use native declarative partitions instead of the legacy copy-based mechanism. Data partitioning itself remains **off by default** (`FLOWX_DATA_PARTITIONING_ENABLED` is `false`), so deployments that never enabled it are not affected.

New process-engine variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Use native PostgreSQL partitions for archiving when partitioning is enabled. PostgreSQL only; other databases keep the existing mechanism. | `true` |
| `FLOWX_DATA_PARTITIONING_PREMAKECRONEXPRESSION` | Schedule for the job that creates upcoming partitions in advance. | `0 0 23 * * ?` |
| `FLOWX_DATA_PARTITIONING_PREMAKEPARTITIONSAHEAD` | How many future partitions the job keeps created ahead of the current one. | `2` |

> [!WARNING]
>
> Enabling native partitioning converts the process-instance tables to partitioned tables, and the conversion is one way: there is no supported path back to unpartitioned tables. Review the [partitioning and archiving setup guide](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning) before turning it on.

#### Document plugin: processing size limits

The document plugin now enforces size limits on archive, encryption, and extraction operations. Input over the limit is rejected instead of processed. The defaults are generous; override them only if your documents legitimately exceed them.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOCUMENT_ARCHIVE_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for archive operations. | `209715200` (200 MB) |
| `DOCUMENT_ENCRYPTION_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for encryption. | `104857600` (100 MB) |
| `DOCUMENT_EXTRACT_MAX_UNCOMPRESSED_SIZE` | Maximum total uncompressed size, in bytes, an archive may expand to during extraction. | `209715200` (200 MB) |

#### Integration Designer: workflow output size guard

Workflow output published to Kafka is now size-checked before sending. A root workflow output that exceeds the limit fails the workflow run with the failure type `outputTooLargeForKafka` instead of being silently dropped by the broker's message-size limit. The check applies to root workflow outputs on automatic and default-path completion; subworkflow outputs are not checked.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_KAFKA_PAYLOAD_SIZE_LIMIT` | Maximum serialized size, in bytes, of a root workflow output published to Kafka. | `786432` |

> [!TIP]
>
> Keep this limit below your broker's `max.message.bytes`. The default, 768 KB, sits safely under the common 1 MB broker default.

#### Advancing datasource metrics

The process engine and Integration Designer now register their advancing datasource under a named connection pool (`advancing`), so its metrics are distinguishable from the main datasource pool in Prometheus. No configuration action is required.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026

Maintenance release for the 5.9.x LTS line. Native PostgreSQL partitioning for process data, bug fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. It also brings native PostgreSQL partitioning to process data. Review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.5** is a maintenance release for the 5.9.x LTS:
>
> * **Native PostgreSQL partitioning:** process data tables are partitioned by the database itself, so removing old data becomes a partition drop instead of a bulk delete
> * **Key fixes:** audit entries no longer missing or attributed to the wrong application, merge conflicts raised for changes inside embedded subprocesses, self-hosted Keycloak issuer derived from configuration
> * **Integrations:** an SFTP private key can be stored as a multi-line PEM
> * Backend, Designer, and renderer stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.5 is compatible with 5.9.4, and the upgrade requires no data migration. Native PostgreSQL partitioning is opt-in: if you had already enabled data partitioning, review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade, because the conversion to native partitions runs automatically for you and is one way.

**Before you upgrade, check these:**

* **AI job queues:** each AI service now consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group, and the new groups read only jobs published after they start. Wait until the `ai-services` group has no lag on the job topics before you upgrade, so no queued job is skipped. If your cluster restricts consumer groups with ACLs, allow the new groups first.
* **Relational data sources:** Oracle data sources connect only to hosts that resolve to a public address. Add private database hosts to the allowlist, as described in [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Service-account secrets:** confirm every service-account client secret is set on `authorization-system`, or the service stops at startup. The secrets are listed in the [Authorization setup guide](/5.9/setup-guides/authorization-setup-guide).
* **Dashboards and alerts:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total`.
* **Runtime log levels:** the `loggers` actuator endpoint is no longer exposed by default. Add it back as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Data partitioning:** if you had already turned on data partitioning, the conversion to native partitions runs automatically on upgrade and is one way. See the [deployment guidelines](./deployment-guidelines-v5.9.5).

**Upgrade path:** direct upgrade from 5.9.4. Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. Component versions are listed in the [5.9.5 deployment guidelines](./deployment-guidelines-v5.9.5).

***

## Native PostgreSQL partitioning

The process engine stores process data in tables that PostgreSQL itself partitions by time. Retention then
works by dropping whole partitions rather than deleting rows one at a time, which keeps the cost of
removing old data flat as the tables grow.

This is the same partitioning model described for the 5.12 line, delivered into the 5.9.x LTS.

For how partitioning interacts with archiving and retention, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving).

***

## Full changelog

### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.&#x20;
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](#native-postgresql-partitioning).&#x20;

### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.&#x20;
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.&#x20;
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.&#x20;
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.&#x20;
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.&#x20;
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.&#x20;
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.&#x20;
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](./deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).&#x20;
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](./deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).&#x20;
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).&#x20;
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).&#x20;
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.&#x20;
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.&#x20;

### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.&#x20;
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.&#x20;
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.&#x20;
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.&#x20;
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.&#x20;
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.&#x20;
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.&#x20;
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.&#x20;
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.&#x20;
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.&#x20;
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# Deployment guidelines v5.9.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6

Component versions, configuration, and deployment notes for FlowX.AI 5.9.6 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.6 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.5 adds one Kafka topic, a database table, and a MongoDB index. The table and the index are created automatically when the services start. Review [Kafka topics](#kafka-topics), [Configuration changes](#configuration-changes), and the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes) before you deploy.

> [card] Upgrade Path
>
> **5.9.5 → 5.9.6**: Direct upgrade. No manual data migration is required.
>
> **5.9.6 → 6.0.0**: See [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.4 or earlier directly?** Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first, then the earlier pages they point to.

## Component versions

### Core components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.17 | 10.174.10 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.14 | 10.152.7 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.13 | 10.113.7 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.11 | 10.94.6 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.101.1 | 10.100.7 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.111.1 | 10.110.7 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.13 | 10.124.7 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.12 | 10.112.6 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.8 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.11 | 10.92.6 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.11 | 10.102.6 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.12 | 10.98.7 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.201.2 | 10.200.9 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.13 | 10.107.7 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.13 | 10.122.7 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.13 | 10.101.6 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.102.1 | 10.101.6 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.12 | 10.98.6 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.12 | 10.69.6 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.14 | 10.33.7 | 10.8.0 | - | - |
| **license** | 10.87.12 | 10.87.6 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** 1.52.0, deployed and upgraded by the **SpiceDB operator** 1.25.1.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **solution-portal** (renamed from react-saas) | 10.285.4 | 10.282.5 | 10.230.2 | - | - |
| **iOS renderer** | 10.9.2 | 10.6.2 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.10.2 | 10.9.3 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.2 | 10.11.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.2 | 10.11.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.2 | 10.11.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.2 | 10.11.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.2 | 10.11.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.2 | 10.11.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.13 | 10.35.6 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.2 | 10.11.0 | - | - | - |
| **ai-assistant** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.2 | 10.11.0 | - | - | - |
| **flowx-docs** | 5.9.6 | 5.9.5 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.6 adds one Kafka topic. If your cluster does not create topics automatically, create it before you deploy, and allow both services in your ACLs.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.build.deployment-failed.v1` | runtime-manager | application-manager | Reports a build deployment that failed, so application-manager can queue it for a retry. |

The topic is included in the FlowX Kafka topics chart from version 10.2.0. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Create the `ai.flowx.build.deployment-failed.v1` Kafka topic if your cluster does not create topics automatically. See [Kafka topics](#kafka-topics).
2. Review [Configuration changes](#configuration-changes). No values change is required for a standard upgrade.
3. The `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes).
4. Update container images to the 5.9.6 versions listed in the tables above.
5. Deploy services using your standard deployment process.
6. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Build redeployment retries

When a build deployment fails, application-manager queues it for a retry. The queue is now stored in the application-manager database, in the new `failed_deployment` table, instead of in Redis. The table is created automatically on startup. runtime-manager reports each failure on the `ai.flowx.build.deployment-failed.v1` topic, and application-manager consumes it.

New application-manager variables (the defaults fit a standard deployment):

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_BUILD_DEPLOYMENTFAILED` | Topic that carries failed build deployments. | `ai.flowx.build.deployment-failed.v1` |
| `KAFKA_CONSUMER_GROUPID_BUILD_DEPLOYMENTFAILED` | Consumer group that reads the topic. | `build-deployment-failed-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_DEPLOYMENTFAILED` | Number of consumer threads for the topic. | `1` |

> [!WARNING]
>
> Retries that are still queued in Redis when you upgrade are not moved to the new table. Re-publish any build whose deployment failed shortly before the upgrade. The old entries stay in the Redis hash `build:failed-deployments:v3`, under the persistence key prefix configured for application-manager. Nothing reads them after the upgrade, so you can delete the hash.

#### MongoDB setting names

Services that use MongoDB now read their connection settings from new names. The previous `SPRING_DATA_MONGODB_*` variables still feed the new settings, so existing deployments need no change. Use the new names in new configuration.

| Previous variable | New variable |
| - | - |
| `SPRING_DATA_MONGODB_URI` | `SPRING_MONGODB_URI` |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | `SPRING_MONGODB_REPRESENTATION_UUID` |
| `SPRING_DATA_MONGODB_STORAGE` | `FLOWX_DATASOURCE_MONGO_STORAGE` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | `FLOWX_DATASOURCE_APPRUNTIME_ENABLED` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | `FLOWX_DATASOURCE_APPRUNTIME_URI` |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | `FLOWX_DATASOURCE_APPRUNTIME_REPRESENTATION_UUID` |

`SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION` no longer has any effect: indexes on the runtime database are never created automatically.

#### Document parser models

The document parser image now contains its layout, table, and OCR models, so the parser downloads nothing at startup or on the first parse. It runs without internet access and on a read-only filesystem. `USE_DOCLING` no longer has any effect on the document parser and can be removed from its configuration.

#### Integration Designer: document download timeout

A REST node JSON body can include `"@@base64File(<path>)"` to send a Document Plugin file as base64. Downloading the file from the Document Plugin is cancelled after this timeout. See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

New integration-designer variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` | Longest time a Document Plugin file download for a REST node JSON body may take before it is cancelled. | `PT5M` |

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026

Maintenance release for the 5.9.x LTS line. Durable build redeployment retries, project version merge fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Review the [deployment guidelines](./deployment-guidelines-v5.9.6) before you upgrade: this release adds one Kafka topic.

> [card] Release Highlight
>
> **FlowX.AI 5.9.6** is a maintenance release for the 5.9.x LTS:
>
> * **Durable build redeployments:** a build deployment that failed and waits for a retry is stored in the database, so a Redis flush or restart no longer drops it
> * **Key fixes:** project version merges no longer lose navigation areas, Resources Changed no longer flags unchanged resources, and Number attributes keep the selected subtype
> * Backend, Designer, and AI stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.6 is compatible with 5.9.5. The upgrade adds a database table and a MongoDB index, both created automatically when the services start.

**Before you upgrade, check these:**

* **AI Platform Helm chart:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime.&#x20;
* **Kafka topics:** create the `ai.flowx.build.deployment-failed.v1` topic if your cluster does not create topics automatically, and allow it in your ACLs. `runtime-manager` produces it and `application-manager` consumes it. See [Kafka topics](./deployment-guidelines-v5.9.6#kafka-topics).
* **Pending build redeployments:** retries that are still queued in Redis when you upgrade are not carried over. Re-publish any build whose deployment failed shortly before the upgrade. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Workflow node retries:** retry waits now grow exponentially and the max interval caps each wait instead of the whole retry window. Review the retry settings of nodes that rely on the previous timing.
* **Connection tests:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources. Grant these to custom roles that run connection tests.
* **Integration Designer startup:** the first start after the upgrade builds a new index on the `workflow_instances` MongoDB collection. On a large collection, allow extra time before the readiness check passes.
* **React Native SDK hosts:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` and keeps showing the current process, like the Android and iOS SDKs. Update your app to dispose the current process handle and continue the new process. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).

**Upgrade path:** direct upgrade from 5.9.5. Upgrading from 5.9.4 or earlier? Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/React Native/iOS/Android) and Designer 5.9.x. Component versions are listed in the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6).

***

## Full changelog

### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json) and [Integration Designer: document download timeout](./deployment-guidelines-v5.9.6#integration-designer-document-download-timeout).&#x20;

### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.&#x20;
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).&#x20;
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.&#x20;
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect. See [Document parser models](./deployment-guidelines-v5.9.6#document-parser-models).&#x20;
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.&#x20;
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.&#x20;
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](./deployment-guidelines-v5.9.6#mongodb-setting-names).&#x20;
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.&#x20;
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.&#x20;
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6) for its version.&#x20;

### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.&#x20;
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.&#x20;
* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.&#x20;
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.&#x20;
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.&#x20;
* **React Native SDK:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` instead of replacing the shown process itself, like the Android and iOS SDKs. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).&#x20;
* **React Native SDK:** a custom component keeps receiving data after the app returns from the background, for example from the Android document picker, so a document upload waiting for its link completes.&#x20;
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# Android SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/android

Migrate the FlowX Android renderer SDK from 5.9.x to 6.0.0.

## Android SDK migration guide

FlowX.AI 6.0 moves the Android SDK to `compileSdk` 37, Android Gradle plugin 9 and Kotlin 2.4, and aligns the SDK's names with the iOS and web SDKs. Update your build setup first, then the renamed SDK APIs.

### System requirements

* **minSdk = 26** (unchanged)
* **compileSdk = 37**

The SDK library was built using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 9.5.0**
* **[Gradle](https://gradle.org/releases/) 9.8.2**
* **[Kotlin](https://kotlinlang.org/) 2.4.21**

Your container app must build with at least:

* **Android Gradle Plugin 9.1.0**
* **Gradle 9.3.1** (the minimum depends on your Android Gradle Plugin version)
* **Kotlin 2.4**
* **JDK 17**

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Android Core KTX](https://developer.android.com/kotlin/ktx#core) | 1.16.0 | **1.19.1** |
| [Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) | 1.10.1 | **1.13.0** |
| [Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) | 2025.09.01 | **2026.09.00** |
| [Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) | 2.9.1 | **2.10.2** |
| [Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) | 2.9.1 | **2.11.0** |
| [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | 1.10.2 | **1.11.0** |
| [Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) | 1.1.7 | **1.3.0** |
| [Android Security](https://developer.android.com/jetpack/androidx/releases/security) | 1.1.0-beta01 | **1.1.0** |
| [OkHttp BOM](https://square.github.io/okhttp/) | 4.12.0 | **5.5.1** |
| [Retrofit](https://square.github.io/retrofit/) | 2.12.0 | **3.0.0** |
| [Coil BOM](https://coil-kt.github.io/coil/) | 3.4.0 | **3.6.3** |
| [Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) | 4.31.1 | **4.36.2** |
| [Mozilla Rhino](https://github.com/mozilla/rhino) | 1.8.0 | **1.9.2** |
| [Accompanist Permissions](https://google.github.io/accompanist/permissions/) | 0.37.3 | 0.37.3 |
| [Moshi](https://github.com/square/moshi) | 1.15.2 | 1.15.2 |
| [Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) | 2.1.5 | 2.1.5 |

> [!WARNING]
>
> The SDK now depends on **OkHttp 5** and **Retrofit 3**. Gradle resolves your app to these versions even if you declare OkHttp 4 or Retrofit 2, so update any code in your app that uses APIs removed in these major versions. Align your app's versions of these libraries with the SDK's versions to avoid compatibility issues.

### Migration steps

To build and run your container app with the 6.0 SDK, follow these steps in order:

**1. Update the SDK version**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
implementation("ai.flowx.android:sdk:<5.9.x version>") // [!code --]
implementation("ai.flowx.android:sdk:<6.0 version>") // [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Increase the `compileSdk` version to `37`**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileSdk = 35 // [!code --]
    compileSdk = 37 // [!code ++]
}
```

> [!NOTE]
>
> The SDK and its AndroidX, OkHttp and Coil dependencies require `compileSdk` 37. Raising `targetSdk` is not required.

**3. Update the `Android Gradle plugin` version to at least `9.1.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "8.10.0" apply false // [!code --]
    id("com.android.application") version "9.5.0" apply false // [!code ++]
}
```

> [!TIP]
>
> Android Gradle plugin 9 is a major release with breaking build changes. Consult the [Android Gradle plugin 9.0 release notes](https://developer.android.com/build/releases/agp-9-0-0-release-notes).

**4. Update the `Gradle` version**

```properties [rootProject]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.2-bin.zip # [!code ++]
```

> [!NOTE]
>
> Android Gradle plugin 9.1 requires at least Gradle 9.3.1, and 9.5 requires at least Gradle 9.6.0. Check the minimum for your version in the [Android Gradle plugin release notes](https://developer.android.com/build/releases/gradle-plugin).

**5. Remove the `Kotlin Android` plugin**

Android Gradle plugin 9 compiles Kotlin by itself (built-in Kotlin), so the `org.jetbrains.kotlin.android` plugin must be removed:

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code --]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") // [!code --]
}
```

> [!TIP]
>
> Consult the [Migrate to built-in Kotlin](https://developer.android.com/build/migrate-to-built-in-kotlin) guide.

**6. Update the `Kotlin` version to at least `2.4`**

With built-in Kotlin, your app compiles with the version of the Kotlin Gradle plugins you declare, such as the Compose Compiler plugin. The Kotlin version that Android Gradle plugin uses by default is too old to read the SDK's classes. Use the same version for every Kotlin Gradle plugin your project declares, such as Parcelize or Serialization.

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code --]
    id("org.jetbrains.kotlin.plugin.compose") version "2.4.21" apply false // [!code ++]
}
```

> [!WARNING]
>
> With an older Kotlin version, the build fails with an error like: `The binary version of its metadata is 2.4.0, expected version is 2.2.0`.

**7. Make sure core library desugaring is enabled**

The SDK requires core library desugaring. If your app does not enable it yet, add:

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**8. Rename the `imageBaseUrl` and `customHeaders` properties of the `Config` interface**

`imageBaseUrl` is now `assetsBaseUrl`, and `customHeaders` is now `additionalHttpHeaders`:

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
Flowx.getInstance().init(
    context = applicationContext,
    config = object : Config {
        ...
        override val imageBaseUrl = "URL to FlowX CMS Media Library" // [!code --]
        override val assetsBaseUrl = "URL to FlowX CMS Media Library" // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code --]
        override val additionalHttpHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code ++]
        ...
    },
    ...
)
```

> [!NOTE]
>
> The default value of the `locale` property changed from `Locale.getDefault()` to `Locale.forLanguageTag("en-US")`. If your app relies on the device locale for date, number and currency formatting, set it explicitly:
>
> ```kotlin theme={"dark"}
> override val locale: Locale = Locale.getDefault()
> ```

**9. Stop passing `null` to the `setAccessToken` method**

The `setAccessToken` method no longer accepts `null`:

```kotlin theme={"dark"}
fun setAccessToken(accessToken: String?) // [!code --]
fun setAccessToken(accessToken: String) // [!code ++]
```

Remove the calls that clear the token (for example, on logout or after a failed login):

```kotlin theme={"dark"}
Flowx.getInstance().setAccessToken(null) // [!code --]
```

A token can't be cleared once set. When another user logs in, set that user's token. If no token is ever set, the SDK runs in anonymous mode. For details, see the [Authentication](/6.x/sdks/android-renderer#authentication) section of the Android SDK reference.
\[!WARNING] Passing an empty string (`""`) no longer clears the token. The SDK sends it as is and the backend rejects the requests.

**10. Rename the `closeModalFunc` parameter to `onDismissRequested`**

The parameter of the `startProcess` and `continueProcess` methods was renamed. Its lambda now runs in the `ProjectScope` context:

```kotlin theme={"dark"}
Flowx.getInstance().startProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)

Flowx.getInstance().continueProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)
```

> [!TIP]
>
> Replace the deprecated `CloseModalProcessScope` type with `ProjectScope`, as described in the [Replace deprecated APIs](#replace-deprecated-apis) section.

**11. Rename the `imageBaseUrl` parameter of the `changeEnvironment` method (if used)**

```kotlin theme={"dark"}
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code --]
fun changeEnvironment(baseUrl: String, assetsBaseUrl: String, enginePath: String) // [!code ++]
```

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. The parameters are unchanged:

| Deprecated (5.9) | Replacement (6.0) | Available on |
| - | - | - |
| `CloseModalProcessScope` | `ProjectScope` | The `onDismissRequested` lambda of `startProcess` and `continueProcess` |
| `replaceSubstitutionTag` | `getSubstitutionTagContent` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getMediaResourceUrl` | `getMediaItemUrl` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getEnumeration` | `getEnumerationItems` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `executeAction` | `runAction` | `CustomComponentScope` |
| `executeUploadAction` | `runUploadAction` | `CustomComponentScope` |
| `configureUpdateState` | `setUpdateStateEnabled` | `Flowx` |

> [!TIP]
>
> Android Studio offers a **Replace with** quick fix on every deprecated call.

These changes are reflected in an actual implementation as shown below:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope // [!code --]
import ai.flowx.android.sdk.api.ProjectScope // [!code ++]

// close process confirmation alert
@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code --]
private fun ProjectScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code ++]
    ...
    Text(replaceSubstitutionTag("@@close_message")) // [!code --]
    Text(getSubstitutionTagContent("@@close_message")) // [!code ++]
}

// custom component
flowxScope.executeAction(action = it, params = JSONObject()) // [!code --]
flowxScope.runAction(action = it, params = JSONObject()) // [!code ++]

// custom loader
flowxScope.replaceSubstitutionTag(text) // [!code --]
flowxScope.getSubstitutionTagContent(text) // [!code ++]
flowxScope.getMediaResourceUrl(key) // [!code --]
flowxScope.getMediaItemUrl(key) // [!code ++]
```

## Related resources

> [card] [Android SDK reference](/6.x/sdks/android-renderer)
>
> Android renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Angular SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/angular

Migrate the FlowX Angular renderer SDK from 5.9.x to 6.0.0.

## Angular SDK migration guide

6.0 moves the Angular renderer to Angular 22 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new input and function names. The framework upgrade, the custom component input, and the removed `logSink` and `logCategories` inputs need code changes.

### Framework upgrade: Angular 21 → 22

Upgrade your host app **before** you bump the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide) from `21.0` to `22.0`.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Angular CLI and `@angular/*` | \~21 | **\~22** |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |
| TypeScript | ≥ 5.9, \< 6.1 | **≥ 6.0, \< 6.1** |

The FlowX Angular packages declare `@angular/*` ≥ 22.0.0 as peer dependencies, so `npm install` fails on an Angular 21 app.

### FlowX SDK changes

#### Renamed inputs and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` input | `baseUrl` |
| `processApiPath` input | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` input | `assetsBaseUrl` |
| `authToken` input | `accessToken` |
| `withConfig({ customLoader })` | `customLoaderProvider` (same shape) |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers.

```diff theme={"dark"}
 <flx-process-renderer
-  [apiUrl]="baseUrl"
-  [processApiPath]="'onboarding'"
-  [staticAssetsPath]="mediaLibraryUrl"
-  [authToken]="token"
+  [baseUrl]="baseUrl"
+  [enginePath]="'onboarding'"
+  [assetsBaseUrl]="mediaLibraryUrl"
+  [accessToken]="token"
   ...
 />
```

#### Custom components: `data$` → `input` signal

Custom components receive their data through an `input` signal input instead of the `data$` Observable. The process data moves under `input().data`, and actions run through `runAction` and the new `runUploadAction`. Both return an Observable.

| 5.9 | 6.0 |
| - | - |
| `data$` input (Observable) | `input` signal input |
| Data fields read from the top level (`data.<field>`) | `input().data.<field>` |
| `data.actionsFn.<name>(params)` | `input().runAction(name, params?)` |
| None | `input().runUploadAction(name, file, params?)` |

```typescript theme={"dark"}
import { Component, computed, input } from '@angular/core';
import { FlxCustomComponentData } from '@flowx/angular-sdk';

@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
})
export class CustomComponentComponent {
  input = input<FlxCustomComponentData>()
  client = computed(() => this.input()?.data.client)

  submit(file: Blob) {
    this.input()?.runAction('action_one', { amount: 3 }).subscribe();
    this.input()?.runUploadAction('upload_document', file, { side: 'front' }).subscribe();
  }
}
```

#### `logSink` and `logCategories` inputs removed

The `[logSink]` and `[logCategories]` inputs on `<flx-process-renderer>` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- [logSink]="formattedLogger"
- [logCategories]="['rest', 'sse']"
```

```typescript theme={"dark"}
import { formattedLogger, logSink } from '@flowx/core-sdk';

const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] });
```

`@flowx/angular-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Inputs removed or deprecated without replacement

| Input | Status in 6.0 |
| - | - |
| `legacyHttpVersion` | Deprecated, no replacement. Still honored. |
| `debugLogs` | Removed. It never had any effect. Use `logSink()` from `@flowx/core-sdk`. |

#### Behavior changes

* `baseUrl` is required on the process, UI Flow, chat and task management renderers, and `assetsBaseUrl` on the process, UI Flow and chat renderers. Without them, the renderer throws ``[FlowX] `baseUrl` is required.`` (or `` `assetsBaseUrl` ``) at start. The template compiler doesn't report a missing value.
* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [Angular SDK reference](/6.x/sdks/angular-renderer)
>
> Angular renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Helm chart
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart

Upgrade a FlowX.AI installation on the flowx-ai Helm chart from 5.9.x to 6.0.0.

> [!NOTE]
>
> FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

This page covers the Helm side of an upgrade from FlowX.AI 5.9.x to 6.0.0 for an installation that already runs on the `flowx-ai` Helm chart. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list every change in detail. This page puts the ones that need action in the order you do them.

> [!NOTE]
>
> If you still run the per-service charts or the `ai-platform` umbrella chart, move to the `flowx-ai` chart on 5.9.x first, as described in [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart). That migration recreates every workload. Doing it separately keeps the 6.0.0 upgrade a single `helm upgrade` of one release.

## Before you begin

* Read the [FlowX.AI 6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) and [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0).
* Get pull access to the `flowx-ai` chart at the chart version for 6.0.0. The chart version is the platform release.
* Take a backup of PostgreSQL, MongoDB, the object store, and the Qdrant collections right before the upgrade.
* If you run a container app with a FlowX renderer SDK, plan its upgrade with the [renderer SDK guides](./migration-overview#renderer-sdk-migration).

The commands on this page read the namespace from `NS`:

```bash theme={"dark"}
export NS={your-flowx-namespace}
```

## Update your values

**1. Set every group flag explicitly**

Don't rely on the chart's group defaults. Set all four group flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

`base` is the AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and Qdrant. The `devtime` and `runtime` services call it, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

For example, to install the core, base, and runtime services:

```yaml theme={"dark"}
groups:
  core:
    enabled: true
  base:
    enabled: true
  devtime:
    enabled: false
  runtime:
    enabled: true
```

See [AI service groups in the Helm chart](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#ai-service-groups-in-the-helm-chart) for the services in each group, and [How do the switches combine?](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#how-do-the-switches-combine) for how group and service flags combine.

**2. Provision databases and secrets for the services you turn on**

In 6.0.0, these services need their own database users and secrets: agent-builder, dynamic-classifier, and harness in PostgreSQL, and designer-user in MongoDB. Create them before the upgrade for every service your group flags turn on. designer-user is in the `core` group, so it always needs its database.

The `keycloak-flowx-realm-clients` secret needs four new client secret keys, whatever your group flags. authorization-system reads all four at startup and, when it has Keycloak admin access (the default), creates the matching service-account clients with those secrets. If a key is missing, its database migration fails and authorization-system doesn't start. Without Keycloak admin access, create the four clients in Keycloak yourself.

See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the user, secret, key, and client names.

**3. Grant process-engine read access to the integration-designer bucket**

process-engine now reads Kafka payloads that integration-designer stores in its bucket. Give the process-engine credentials `s3:GetObject` on that bucket. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the secret names.

**4. Set a bucket name for dynamic-classifier**

If you turn on dynamic-classifier, set its bucket under `services.dynamic-classifier.component.s3.applicationFileStorage.bucketName`. The chart sets no bucket names, as described in [Migrate S3 buckets](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#migrate-s3-buckets). dynamic-classifier also stores data on a 20Gi `ReadWriteOnce` volume, so your cluster needs a storage class that can provide one.

Unlike the Qdrant volumes, this claim is part of the Helm release. `helm uninstall`, or deleting the Argo CD Application with cascading deletion, deletes it, and with a `Delete` reclaim policy its data too.

**5. Move callers off the removed admin Ingress routes**

If you route with Kubernetes Ingress, the chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier, and the upgrade deletes the existing ones. ai-gateway keeps its own. Platform services and frontends don't use these routes. If anything outside the cluster calls one of these paths on the admin host, such as `/speech-to-text`, move it to the service's in-cluster address before you upgrade.

Installations that use the Gateway API aren't affected.

**6. Allow private MongoDB hosts**

nosql-db-runner now applies its host restriction to external MongoDB connections. Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS` on nosql-db-runner. See [nosql-db-runner host restrictions](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).

**7. Trust your IMAP servers' certificates**

email-gateway now verifies the certificate of every IMAPS server it connects to. Email triggers that read from a server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`. See [IMAPS certificate verification](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway).

**8. Keep the management port private**

Upgrading from 5.9.5 or earlier? Since 5.9.6, advancing-controller no longer reads `MANAGEMENT_SECURITY_ENABLED`, and the actuator endpoints on its management port, `8081`, including Prometheus, answer without authentication. Check that no public Ingress or Gateway route exposes that port. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).

**9. Set the personal-data encryption key**

In 6.0.0, integration-designer needs `FLOWX_PII_ENCRYPTION_MASTER_KEY` for the Mask Personal Data and Restore Personal Data nodes. The variable has no default and the chart doesn't set it, so without it those nodes fail when a workflow runs them. Store a strong random value in a secret under the key `FLOWX_PII_ENCRYPTION_MASTER_KEY`, and load the secret into integration-designer:

```yaml theme={"dark"}
services:
  integration-designer:
    extraEnvVarsSecret: {your-pii-secret-name}
```

Keep the value identical on every pod and stable over time: changing it invalidates every in-flight placeholder map. See [Personal-data encryption master key](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-required-secret-personal-data-encryption-master-key).

**10. Choose how Elasticsearch replicates new indices**

In 6.0.0, process-engine and audit-core create new indices with the Elasticsearch `auto_expand_replicas` setting `0-1`, which overrides `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS`. On a cluster with two or more data nodes, the replica roughly doubles the disk space these indices use. To keep a fixed replica count instead, turn auto-expansion off on both services:

```yaml theme={"dark"}
services:
  process-engine:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
  audit-core:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
```

See [Elasticsearch replica auto-expansion](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-elasticsearch-replica-auto-expansion).

**11. Create the new Kafka topics**

New capabilities since 5.9.x depend on new Kafka topics. Create them before you upgrade. The 6.0.0 [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics) list every topic added since 5.9.6. Upgrading from 5.9.5 or earlier? Also create `ai.flowx.build.deployment-failed.v1`, added in 5.9.6. If your cluster uses ACLs, also give the new clients of three existing topics access, as listed in the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics).

If the chart creates your topics, add the new names to the list under `global.flowx.kafka.topics.topics`. The chart creates topics only when `global.flowx.kafka.topics.enabled` is `true`, as Strimzi `KafkaTopic` resources with 3 partitions and 3 replicas unless you set other values under `global.flowx.kafka.topics.defaults`:

```yaml theme={"dark"}
global:
  flowx:
    kafka:
      topics:
        enabled: true
        topics:
          - ai.flowx.build.deployment-failed.v1
```

## Render and compare

Render the 6.0.0 chart with your updated values before you upgrade, and compare it with what runs today:

```bash theme={"dark"}
helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml
```

Check that the rendered Deployments are the services you expect. A missing AI base service, or an AI runtime service you didn't plan for, means a group flag isn't set. The render fails if your values still contain top-level `devtime` or `runtime` keys, or service keys outside `services`. See [Render and compare](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#render-and-compare) for commands that compare environment variables per Deployment.

Using a mirrored or air-gapped registry? List the images the render references, mirror them, and point the chart at your registry with `global.imageRegistry`, as described in [Container images and registry](/6.x/setup-guides/setup-guides-overview#container-images-and-registry):

```bash theme={"dark"}
grep -E '^\s+image:' rendered.yaml | sort -u
```

## Upgrade

Run `helm upgrade` on your `flowx-ai` release with the 6.0.0 chart version and your updated values:

```bash theme={"dark"}
helm upgrade {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml
```

dynamic-classifier uses the `Recreate` deployment strategy, so its old pod stops before the new one starts.

## After the upgrade

* **Upgrading from 5.9.5 or earlier: re-publish builds that were waiting for a retry.** The retry queue for failed build deployments moves from Redis to PostgreSQL, and deployments waiting in Redis are not moved. 5.9.6 already uses the PostgreSQL queue. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).
* **Check component versions.** In FlowX.AI Designer, go to **Platform Status** and compare the versions with the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#component-versions).
* **Check files from before the upgrade.** Open a process attachment, a media library asset, and a knowledge base document, and confirm they load. A bucket-not-found error in the logs points at a bucket name that didn't carry over.
* **Update name placeholders.** data-privacy now masks names with gendered placeholders, such as `<NAME_F_1>`. Update prompts or scripts that match the old form. See [Name placeholders in data-privacy](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy).
* **Expect a new workspace role name.** Users and groups with the Workspace operations editor role now have the Workspace corrective actions editor role, and keep access to process instance migration and move token. See [Workspace operations editor role replaced](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-workspace-operations-editor-role-replaced).

## Related resources

> [card] [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)
>
> Component versions and every deployment-level change in 6.0.0

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single chart


# iOS SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/ios

Migrate the FlowX iOS renderer SDK from 5.9.x to 6.0.0.

## iOS SDK migration guide

FlowX.AI 6.0 aligns the names of five iOS SDK APIs with the Android and web SDKs. The build requirements and library dependencies are unchanged, and the 5.9 names still compile, so your app builds with the 6.0 SDK after you update the pod version. Replace the deprecated names afterwards.

### System requirements

| Requirement | 5.9.x | 6.0 |
| - | - | - |
| Minimum iOS | iOS 15 | iOS 15 |
| Swift | 5.9 | 5.9 |

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Alamofire](https://github.com/Alamofire/Alamofire) | `~> 5.9.0` | `~> 5.9.0` |
| [SDWebImageSwiftUI](https://github.com/SDWebImage/SDWebImageSwiftUI) | 3.0.3 | 3.0.3 |
| [SDWebImageSVGCoder](https://github.com/SDWebImage/SDWebImageSVGCoder) | `~> 1.7.0` | `~> 1.7.0` |

### Migration steps

**1. Update the SDK version**

```ruby Podfile theme={"dark"}
pod 'FlowXRenderer', '<5.9.x version>' # [!code --]
pod 'FlowXRenderer', '<6.0 version>' # [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Replace the deprecated APIs**

Replace the 5.9 names with the 6.0 names listed in the [Replace deprecated APIs](#replace-deprecated-apis) section. The parameters, types and behavior are unchanged.

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. `imageBaseURL` is a property of `FXConfig`; the others are methods of `FlowX.sharedInstance`:

| Deprecated (5.9) | Replacement (6.0) |
| - | - |
| `imageBaseURL` | `assetsBaseURL` |
| `updateAuthorization(token:)` | `setAccessToken(token:)` |
| `getTag(withKey:)` | `getSubstitutionTagContent(key:)` |
| `getEnumeration(name:parentName:)` | `getEnumerationItems(name:parentName:)`, async and completion versions |
| `continueExistingProcess(uuid:name:…)` | `continueProcess(uuid:name:…)`, all three versions |

> [!TIP]
>
> Xcode shows a deprecation warning on every deprecated call, with a **Fix-it** that replaces it with the new name.

These changes are reflected in an actual implementation as shown below:

```swift theme={"dark"}
// configuration
FXConfig.sharedInstance.configure { config in
    config.imageBaseURL = myImageBaseURL // [!code --]
    config.assetsBaseURL = myAssetsBaseURL // [!code ++]
}

// authorization token changes
FlowX.sharedInstance.updateAuthorization(token: accessToken) // [!code --]
FlowX.sharedInstance.setAccessToken(token: accessToken) // [!code ++]

// substitution tags
FlowX.sharedInstance.getTag(withKey: "@@close_message") // [!code --]
FlowX.sharedInstance.getSubstitutionTagContent(key: "@@close_message") // [!code ++]

// enumerations
let items = await FlowX.sharedInstance.getEnumeration(name: "cities", parentName: "countries") // [!code --]
let items = await FlowX.sharedInstance.getEnumerationItems(name: "cities", parentName: "countries") // [!code ++]

// resuming a process
FlowX.sharedInstance.continueExistingProcess(uuid: uuid, // [!code --]
FlowX.sharedInstance.continueProcess(uuid: uuid, // [!code ++]
                                     name: processName,
                                     navigationController: processNavigationController,
                                     isModal: true)
```

## Related resources

> [card] [iOS SDK reference](/6.x/sdks/ios-renderer)
>
> iOS renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Overview
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview

Migration guide for upgrading container apps and the flowx-ai Helm chart from FlowX.AI 5.9.x to 6.0.0

FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

> [!WARNING]
>
> A FlowX.AI 6.0.0 renderer SDK can need a newer framework version in your container app. Check the guide for your SDK, and upgrade the host app before you bump the FlowX SDK.

## Who is affected

Teams that run a container app with a FlowX renderer SDK (Angular, React, iOS, Android, or React Native) and move it to FlowX.AI 6.0.0. See [Renderer SDK migration](#renderer-sdk-migration).

Teams that run FlowX.AI on the `flowx-ai` Helm chart and upgrade it from 5.9.x to 6.0.0. See [Helm chart upgrade](#helm-chart-upgrade).

Teams with business rules, reusable functions, or workflow scripts that still run on the GraalVM script engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

## What's changing

An upgrade to 6.0.0 touches up to three areas, depending on what you run:

* **Helm chart:** set every AI service group flag explicitly, and create databases and secrets for the new services that need them. See [Helm chart upgrade](#helm-chart-upgrade).
* **GraalVM script engine:** deprecated. Scripts on GraalVM keep running after this upgrade, now with the same time limit as the native engine, and 6.1.x is the last release family that supports the engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).
* **Renderer SDKs:** container apps upgrade the FlowX renderer SDK, and the host framework where the SDK needs it. See [Renderer SDK migration](#renderer-sdk-migration).

## Migration process

Follow these steps in order, and skip the ones for areas you don't run.

**1. Check your starting point**

Upgrade to 6.0.0 from FlowX.AI 5.9.x on the `flowx-ai` Helm chart. If you still run the per-service charts or the `ai-platform` umbrella chart, first [migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart) on 5.9.x, as a separate change.

**2. Read the release notes and deployment guidelines**

The [release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) list what changes in 6.0.0. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list the component versions, environment variables, and other configuration changes. The [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog) lists every feature change since 5.9.x, including the 5.10 to 5.13 feature releases.

**3. Prepare the infrastructure**

Create what the 6.0.0 services need before the upgrade window: new PostgreSQL and MongoDB database users and their secrets, four new keys in the `keycloak-flowx-realm-clients` secret, read access for process-engine to the integration-designer bucket, and storage for a 20Gi `ReadWriteOnce` volume if you turn on dynamic-classifier. Create the new Kafka topics, or list them for the chart to create. Also set the personal-data encryption key for integration-designer, choose how Elasticsearch replicates new indices, and allow the private MongoDB hosts and IMAP servers that existing connections use. [Before you upgrade a self-hosted installation](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#before-you-upgrade-a-self-hosted-installation) is the full checklist, and [Update your values](./helm-chart#update-your-values) walks through each item.

**4. Check GraalVM scripts and plan the move off GraalVM**

Scripts on GraalVM keep running, but from 6.0.0 they stop at the same time limit as the native engine. Before the upgrade, check the scripts that can run longer than the limit, or raise it. Then plan their move to the native engine, as described in [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

**5. Back up**

Take the backups listed in [Before you begin](./helm-chart#before-you-begin) right before the upgrade.

**6. Upgrade the Helm release**

Update your values and upgrade the release, as described in [Helm chart](./helm-chart).

**7. Upgrade your container apps**

For each container app, upgrade the host framework first if the SDK needs it, then the FlowX renderer SDK. See [Renderer SDK migration](#renderer-sdk-migration). Container apps on a 5.9.x renderer SDK keep running against a 6.0.0 backend, but screens can render incorrectly wherever 6.0.0 changed behavior. Release the upgraded apps in the same window as the Helm upgrade. For iOS and Android apps, end users who don't install the app update stay on the 5.9.x SDK, so plan how you move them to the new version.

## Helm chart upgrade

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single `flowx-ai` chart

> [card] [Helm chart](./helm-chart)
>
> Upgrade an installation on the `flowx-ai` Helm chart from 5.9.x to 6.0.0

## Move scripts off the GraalVM engine

The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine for JavaScript and Python. Scripts that run on GraalVM keep running after the upgrade to 6.0.0, but they now stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0, a GraalVM script had no time limit. Before you upgrade, check the GraalVM scripts that can run longer than these limits, or raise the limits, as described in [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits). Then plan the move to the native engine.

**1. Find the scripts that run on GraalVM**

Business rules and reusable functions created before the move to the native engine run on GraalVM unless you switched them. The engine selector in each rule's script editor shows the engine it runs on. Workflow scripts run on GraalVM only if `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`.

**2. Test each script on the native engine**

The two engines don't always write the same output. Follow the step-by-step list in [Port a script from GraalVM to native](/6.x/docs/building-blocks/supported-scripts#port-a-script-from-graalvm-to-native), check the [common pitfalls](/6.x/docs/building-blocks/supported-scripts#common-pitfalls), and search scripts for Python imports the native engine blocks, such as `os` and `subprocess`, JavaScript `require(...)`, `process`, or `global`, and calls into Java classes such as `Java.type(...)`. The native engine supports none of these.

**3. Switch to the native engine**

Switch business rules [per rule](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule). Move a reusable function and the rules that call it together: a function written for GraalVM fails when a rule on the native engine calls it. For workflow scripts, remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer`. The default is `native`.

## Renderer SDK migration

> [card] [Angular SDK](./angular)
>
> Migrate the Angular renderer SDK to 6.0.0

> [card] [React SDK](./react)
>
> Migrate the React renderer SDK to 6.0.0

> [card] [iOS SDK](./ios)
>
> Migrate the iOS renderer SDK to 6.0.0

> [card] [Android SDK](./android)
>
> Migrate the Android renderer SDK to 6.0.0

> [card] [React Native SDK](./react-native)
>
> Migrate the React Native renderer SDK to 6.0.0


# React SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react

Migrate the FlowX React renderer SDK from 5.9.x to 6.0.0.

## React SDK migration guide

6.0 moves the React renderer to Node 26 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new prop and function names. The `logSink` and `logCategories` renderer props are removed and need a code change.

### Framework requirements

React stays on 19. Upgrade Node in your build and CI environments.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| React | 19 | 19 |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |

### FlowX SDK changes

#### Renamed props and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` prop | `baseUrl` |
| `processApiPath` prop | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` prop | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customLoader` prop | `customLoaderProvider` (same shape) |
| UI Flow `appInfo.selectedProcessResourceId` | `resourceId` |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `useEnumeration(name, parentName?)` | `useEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers. `customLoaderProvider` applies to the process and UI Flow renderers.

```diff theme={"dark"}
 <FlxProcessRenderer
-  apiUrl={baseUrl}
-  processApiPath="onboarding"
-  staticAssetsPath={mediaLibraryUrl}
-  authToken={token}
+  baseUrl={baseUrl}
+  enginePath="onboarding"
+  assetsBaseUrl={mediaLibraryUrl}
+  accessToken={token}
   ...
 />
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, file, params?)` to upload a file through an upload action. `params` are sent as extra form fields beside the file.

```typescript theme={"dark"}
input.runAction('action_one', { amount: 3 })
input.runUploadAction('upload_document', file, { side: 'front' })
```

`FlxCustomComponentData` is now generic (`FlxCustomComponentData<TFile = Blob>`) and requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### `logSink` and `logCategories` props removed

The `logSink` and `logCategories` props on `FlxProcessRenderer` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- <FlxProcessRenderer logSink={formattedLogger} logCategories={['rest', 'sse']} ... />
+ import { formattedLogger, logSink } from '@flowx/core-sdk'
+
+ const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] })
```

`@flowx/react-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Props removed or deprecated without replacement

| Prop | Status in 6.0 |
| - | - |
| `legacyHttpVersion` on the process renderer | Deprecated, no replacement. Still honored. |
| `legacyHttpVersion` on the UI Flow renderer | Removed. It never had any effect. |
| `customHeaders` | Removed. It never had any effect. |
| `updateStateEnabled` | Removed. It never had any effect. |
| `isAnonymousMode` | Removed. It never had any effect. |
| `fw` | Removed. It never had any effect. |

Delete the removed props from your process and UI Flow renderer props.

#### Behavior changes

* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [React SDK reference](/6.x/sdks/react-renderer)
>
> React renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# React Native SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react-native

Migrate the FlowX React Native renderer SDK from 5.9.x to 6.0.0.

## React Native SDK migration guide

6.0 moves the validated React Native target to Expo SDK 57 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new configuration and prop names. The Android Material 3 date picker opt-in is removed.

### Prerequisites and version range

The peer dependency floors are unchanged: `react-native` ≥ 0.83.0 and `react` ≥ 19.2.0. The validated target moves up one Expo SDK.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Validated target | Expo SDK 56, React Native 0.85.3 | **Expo SDK 57, React Native 0.86.3** |
| React | 19.2.3 (Expo SDK 56 pin) | 19.2.3 (Expo SDK 57 pin) |
| `react-native-blob-util` | ^0.24.9 | **^0.25.1** |
| `@react-native-community/datetimepicker` | Required peer | **No longer used** |

For an Expo project, align the project to Expo SDK 57, then reinstall the FlowX packages with `npx expo install`:

```bash theme={"dark"}
npx expo install expo@^57.0.0 --fix
```

For the full install command and the Expo SDK 57 reference versions, see the [React Native SDK reference](/6.x/sdks/react-native-renderer).

### FlowX SDK changes

#### Renamed configuration options and props

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `FlxConfig.baseURL`, `apiUrl` prop | `baseUrl` |
| `processApiPath` | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customHeaders` | `additionalHttpHeaders` |
| `customLoader` | `customLoaderProvider` (same shape) |
| `customStepperHeader` | `customStepperHeaderProvider` (same component) |
| `configure({ locale, language })` | `FlowX.changeLocaleSettings(locale?, language?)` |
| `configure({ updateStateEnabled })` | `FlowX.setUpdateStateEnabled(enabled)` |
| `setAccessToken(token: string)` | `setAccessToken(token?: string \| null)`: `null`, `undefined` or `''` switches to anonymous access |
| `processUuid` prop | `processInstanceUuid` |
| `onClose(name?)` | `onDismissRequested(name?)` (same argument) |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl`, `enginePath` and `assetsBaseUrl` apply to `FlowX.configure` and to the process, UI Flow and chat renderers. `onDismissRequested` applies to `startProcess`, `continueProcess`, `startUiFlow` and the process and UI Flow renderers.

In 5.9 the content helpers came only from `@flowx/core-sdk/rn`. `@flowx/react-native-sdk` now exports them too, under their new names only (`getEnumerationItems`, `getMediaItemUrl`, `getSubstitutionTagContent`).

```diff theme={"dark"}
 FlowX.configure({
-  baseURL: 'https://api.example.com',
-  processApiPath: 'onboarding',
-  staticAssetsPath: 'https://media.example.com',
-  customHeaders: { 'x-tenant': 'acme' },
-  language: 'en',
-  locale: 'en-US',
+  baseUrl: 'https://api.example.com',
+  enginePath: 'onboarding',
+  assetsBaseUrl: 'https://media.example.com',
+  additionalHttpHeaders: { 'x-tenant': 'acme' },
   organizationId,
 })
+FlowX.changeLocaleSettings('en-US', 'en')
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, { uri, name, type }, params?)` to upload a file through an upload action.

`FlxCustomComponentData` requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### Android Material 3 date picker removed

The opt-in Material 3 date picker for `FlxDatePicker` on Android is removed, along with the `@react-native-community/datetimepicker` peer dependency.

* Remove `material3` from any `configureFlxUiToolkit` call.
* The `@react-native-community/datetimepicker` package is no longer needed by FlowX. Uninstall it if nothing else in your app uses it.
* Keep the `@flowx/react-native-ui-toolkit` Expo config plugin registered. It no longer changes `AppTheme` or sets `extra.flxUiToolkit.material3`. It now adds `fontScale` to the main activity's `android:configChanges` and declares the microphone permissions used by chat voice input. Run `npx expo prebuild` again after the upgrade.

#### Behavior changes

* A session with no usable access token now starts as anonymous instead of failing. In 5.9, a token that was `null`, `undefined` (never set) or an empty string (`''`) made the start throw `Call FlowX.setAccessToken(...) before starting a process.` In 6.0 all three values start an anonymous session, and a backend that requires a token answers `401`. If your token fetch can return `null`, `undefined` or `''`, check the value before you start a process; otherwise the failure only shows up later as a `401`.
* Error and warning messages name `baseUrl` and `assetsBaseUrl` instead of `baseURL` and `staticAssetsPath`. Update any host code that matches on their text.

## Related resources

> [card] [React Native SDK reference](/6.x/sdks/react-native-renderer)
>
> React Native renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Deployment guidelines v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/deployment-guidelines-v4.6.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.0 FlowX.AI release, you cannot import old process definitions or resources into the new platform from older versions .

## Component versions

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.0.2** | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.3** | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.1.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.0** | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.0.3** | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.0.3** | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | **4.1.3** | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | **7.0.3** | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.0** | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.0** | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.1.12** | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.0** | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.1** | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.0.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.3** | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.9** | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.10** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.9** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.3** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.24** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.5.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.0 | Keycloak | 22.x |
| 4.6.0 | Kafka | 3.2.x |
| 4.6.0 | PostgreSQL | 16.2.x |
| 4.6.0 | MongoDB | 7.0.x |
| 4.6.0 | Redis | 7.2.x |
| 4.6.0 | Elasticsearch | 7.17.x |
| 4.6.0 | Oracle Database | 21C/ 21-XE |
| 4.6.0 | Angular (Web SDK) | 19.x |
| 4.6.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

## New microservices - setup guides

> [card] [Application-manager](/4.7.x/setup-guides/application-manager)

> [card] [Runtime-manager](/4.7.x/setup-guides/runtime-manager)

> [card] [Integration Designer](/4.7.x/setup-guides/integration-designer-setup)

> [card] [Data-sync job](/4.7.x/setup-guides/data-sync)

## New access rights and roles

> [card] [Integration Designer access rights](/4.7.x/setup-guides/access-management/configuring-access-rights-for-integration-designer)

> [card] [Application Manager access rights](/4.7.x/setup-guides/access-management/app-manager-access-rights)

## Updated access rights and roles

> [card] [Task Manager access rights](/4.7.x/setup-guides/plugins-access-rights/configuring-access-rights-for-task-management)
>
> Added new roles for **manage-views**.

## New service accounts

> [card] [Runtime manager service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#runtime-manager-service-account)

> [card] [Integration Designer service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#integration-designer-service-account)


# Deployment changes for v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x

This document outlines the configuration and infrastructure changes introduced from v4.1.x to v4.6.0 for deploying the FlowX.AI platform.

## CMS Setup

### MongoDB configuration

In version 4.6.0, the CMS setup includes a more comprehensive MongoDB configuration, especially for runtime data handling:

* **Runtime MongoDB Instance**: A dedicated MongoDB instance for managing runtime data.
  * **New Environment Variables**:
    * `RUNTIME_DB_USERNAME`: Username for runtime MongoDB access.
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: Connection URI for the runtime MongoDB instance.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`). Default is `mongodb`.
  * **Transaction Settings for Mongock Library**:
    * `MONGOCK_TRANSACTIONENABLED`: Controls MongoDB transaction support with Mongock, defaulting to `false` due to compatibility concerns with MongoDB 5.

### Private storage configuration

Private CMS to securely store uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints. This CMS will support AI services and workflows while maintaining strict access controls.

> [!NOTE]
>
> Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from project builds as they aren't needed at runtime.

* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL`: This environment variable specifies the URL of the S3 server used for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME`: This environment variable specifies the name of the S3 bucket dedicated to private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET`: This environment variable indicates whether the private S3 bucket should be created if it does not already exist. It can be set to true or false.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY`: This environment variable holds the access key used to authenticate to the S3 server for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY`: This environment variable holds the secret key used to authenticate to the S3 server for private file storage.

> [card] [CMS setup guide](/4.7.x/setup-guides/cms-setup)

***

## Admin setup

### MongoDB configuration

Version 4.6.0 introduces a new MongoDB setup in the Admin service for managing data model information:

* **New MongoDB Data Model Configuration**:
  * **Environment Variables**:
    * `SPRING_DATA_MONGODB_URI`: URI for connecting to the MongoDB data model instance.
    * `DB_USERNAME`: Set to `data-model` for data model access.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`).

***

## Engine setup

### MongoDB configuration

The Engine configuration now includes additional setup for a runtime MongoDB instance to manage runtime builds:

* **Runtime MongoDB for Engine**:
  * **New Environment Variables**:
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: URI for connecting to the runtime MongoDB.
    * `DB_USERNAME`: Set to `app-runtime` for runtime data access.


# Configuration and migration guide
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/process-configuration

This guide outlines changes in process and UI configuration from v4.1.x to 4.6.0 version.

## Projects

The **Projects** feature in FlowX AI v4.6.0 is a new structure that organizes all dependencies and resources required for a project into a single deployable view. This enhancement simplifies configuration, deployment, and maintenance by layering projects on top of processes, offering a centralized workspace that encapsulates everything needed for project execution.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)

Several key configuration changes impact how resources and dependencies are managed, deployed, and maintained. This guide provides a breakdown of the configuration changes, automatic migration processes, and manual steps required to ensure a smooth transition.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)

***

### Consolidated resource management

* **Change**: All resources that were previously managed individually within processes are now grouped within Projects. This includes content management elements, integrations, themes, task configurations, and permissions.
* **Impact**: Resources like **enumerations**, **substitution tags**, and **generic parameters** are now managed within Projects, allowing centralized configuration and version control.
* **Migration**: All process-related resources will be migrated automatically into a **default project**, ensuring continuity of functionality in the new framework. After migration, you should verify that all critical resources are correctly configured within this default project.

> [card] [What are resources?](/4.7.x/docs/projects/resources)

### Enhanced version control and dependency management

* **Impact**: Projects support **dependency management** through **Libraries** and enforce version-controlled resources. Setting up a project now requires careful dependency management and versioning to prevent unintended updates.
* **Benefit**: Allows for modular, reusable resources and stable deployments across projects, reducing resource duplication and enhancing project compatibility.

### Migration checklist

To ensure a smooth transition, complete the following steps:

1. **Verify Process Migration**: Confirm that all existing process definitions have been correctly migrated into the default project.
2. **Set Configuration Parameter Overrides**: Post-deployment, adjust environment-specific Configuration Parameters in the default project.
3. **Update Task Views**: Replace the global "All Tasks" feature with project-specific Views in each project.
4. **Transfer Processes and Dependencies Manually**: If moving a process from the default project to another project, manually transfer associated resources and re-check dependencies.

***

## Generic parameters migration

* **Overview**: In version 4.6.0, global generic parameters (from versions prior to 4.6.0) have been migrated to project-level as Configuration Parameters, consolidating parameter management within specific projects for improved organization and control.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/Screenshot%202024-11-06%20at%2019.04.49.png)

* **Migration**: All generic parameters will be automatically migrated to Configuration Parameters section under a default project.
* **Business Rules Unaffected**: There is no impact on existing business rules; they will continue to function as before without requiring updates.
* **Process Export Considerations**: If you export a process from one project to another, ensure that you also transfer the associated configuration parameters. This step is crucial to maintain process functionality and consistency across projects.
* **Important Note**: Only values of generic parameters associated with the specific environment, or where `env = null` (displayed as "all" in the interface in versions prior to 4.6.0), will be migrated. You must ensure that you have correctly set the values for generic parameters, paying attention to environment values (which are case-sensitive), and export these generic parameters before migration to avoid any potential data loss.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.39.29.png)

* **Post-Deployment Step**: After the first deployment to an upper environment, you will need to create configuration parameter overrides with the specific values required for that environment. This ensures that all environment-specific configurations are accurately maintained and applied across different deployment stages.

> [!TIP]
>
> To set configuration parameter overrides, navigate to **Your App -> Runtime -> Configuration Parameters Overrides**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.42.06.png)

***

## Source systems migration

* **Change**: Source systems have not been migrated automatically and need to be manually recreated.
* **New Location**: In v4.6.0, source systems have been moved under Integration Designer.
* Manual Migration Required:
  1. Navigate to Integration Designer.
  2. Recreate each source system manually with the same code as in the original configuration.
  3. Ensure the "Enable enumeration value mapping" checkbox is enabled.
* **Impact**: Failure to manually migrate source systems may result in broken integrations and missing data mappings.

**v4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2009.53.30.png)

**\< v.4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2010.09.12.png)

## Task management

* "All Tasks" as a View: The global "All Tasks" feature is no longer standalone and will now function as a View in a project.

**v4.6.0:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

**v4.1.x:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/all_tasks.png)

***

## General

Before starting the migration, complete the following steps:

1. **Merge All Feature Branches**: Ensure all feature branches for processes are merged into the latest version on the main branch.
2. **Remove Unnecessary Resources**: Delete any test processes or resources that are no longer needed.
3. **Export Generic Parameters**: Export generic parameters as a backup to ensure they migrate accurately to project-specific Configuration Parameters.

### Migration steps

During migration, resources will be transferred into a single **default project** with one committed version.

* **Process Definitions**: Only the last committed process version on the main branch will migrate. If no committed version exists, the latest WIP version will be used.
* **Enumerations, Substitution Tags, and Task Manager**: These resources will be migrated to the default project.
* **Generic Parameters**: Migrated as **Configuration Parameters** within the default project, covering only values where `env = null` or that match the platform’s environment setting.
* **Languages**: Language settings (available languages and default) will be moved to project settings. Languages remain globally available.

### Resources excluded from migration

Some resources will remain globally available or are deprecated:

* **Themes**
* **Fonts**
* **Global Media Library** (for media used in themes)
* **Out of Office (Task Manager)**
* **Integration Management** (will not be available in v4.6.0)

***

## Datepicker Migration

In version 4.6.0, significant updates have been introduced to the **Datepicker** component to ensure compatibility with ISO 8601 date formats and enhanced handling of date attributes within the **Data Model**. This migration affects both newly created and existing processes.

### Key changes

1. **Introduction of Date Types**:
   * **Standard Date**: Stores and displays date values in ISO 8601 format, respecting the project's locale and timezone settings.
   * **Legacy Date**: Retains previous formatting to ensure compatibility with existing business rules and processes.

2. **Properties Updates**:
   * The **Datepicker** now supports dependent properties such as `minDate`, `maxDate`, and `defaultValue`. These properties:
     * Follow the formatting rules of the selected date type (Standard or Legacy).
     * Ensure that dynamic date values pulled from the **Data Model** are displayed correctly.

3. **Backward Compatibility**:
   * **Existing Processes**: All migrated processes with legacy Datepicker components will default to `Legacy Date` type. This preserves the original formatting and ensures no disruption in business rules or workflows.
   * **New Processes**: Newly created processes will default to `Standard Date` type, saving values in ISO 8601 format.

***

### Migration process

1. **Legacy Datepickers**:

   * Automatically flagged during migration.
   * Continue to work with existing business rules.
   * Require manual review for future updates to transition to the **Standard Date** format.

2. **Business Rules Updates**:
   * Legacy Datepickers may require manual adjustments if associated business rules reference hardcoded date formats.
   * Ensure that any dynamic dates used in business rules are compatible with the ISO 8601 standard.

3. **Standard Datepickers**:
   * All new Datepicker components save date values directly in ISO 8601 format.
   * Fully compatible with updated **Data Model** attributes, allowing seamless integration with external systems, adaptors, and reporting plugins.

### Considerations

* **Default Values**:
  * For **Standard Datepickers**, the `defaultValue` must be in ISO 8601 format.
  * Dynamic defaults can also be set using **Data Model** attributes or process data.
* **Data Model Integration**:
  * All external and internal date attributes, including those used by adaptors or business rules, must be explicitly defined in the **Data Model**.
* **UI Designer Overrides**:
  * Overrides can be applied to display dates differently for specific UI elements, ensuring flexibility for localized formatting.

### Recommendations for transition

* **Existing Processes**:
  * Leave Datepicker components in `Legacy` mode unless business rules and workflows are updated to support ISO 8601.
* **New Processes**:
  * Use `Standard Date` to ensure future compatibility and alignment with ISO 8601 formatting.
* **Documentation**:
  * Review and update all timer expressions, adaptors, and external data feeds to use ISO 8601 format for consistency.

***

## Updates to expression evaluation

**What Changed:**

* A fix was implemented in the web expression evaluator regarding how string values are handled during process value replacement.
* Previously, when evaluating dynamic and computed expressions, string variables required manual insertion of double quotes (`""`) because the system did not automatically add them.
* With the recent fix, the system now **automatically adds the necessary quotes** for string replacements.

**Impact:**

* **Existing Expressions:** If your current dynamic or computed expressions include manually added quotes around string values, these might now result in redundant quotes or incorrect string formatting.
* **Behavioral Shift:** The automatic quote addition alters how string values are processed, which might affect outputs if the expressions were structured with the expectation of manual quotes.

**Action Required:**

1. **Review Your Expressions:** Check any dynamic and computed expressions in your processes that currently include manual double quotes around string values.
2. **Modify as Needed:** Remove unnecessary double quotes where the system now handles them automatically to prevent duplicate quoting or formatting issues.

***

## Export/import enumerations (CSV)

In the transition from version 4.1.x to 4.6.0, the following columns have been removed from the enum CSV export format:

* description.application
* description.draft
* contentValue.childContentDescription.application
* contentValue.childContentDescription.draft
* contentValue.childContentDescription.type

Existing CSV export/import processes should be updated to remove references to these columns to ensure compatibility with the 4.6.0 release.

***

## Post-migration recommendations

For complex projects with multiple use cases, **do not use the default project for ongoing development or production builds**. Instead:

1. **Create Branches within the Default Project**: Organize and streamline resources by creating branches. This enables a lightweight build focused on production.
2. **Split the Default Project into Smaller Projects**: Use the import/export feature to separate the default project into individual projects by use case.
   * **Note**: When importing processes into a new project, resource references may need to be manually reconfigured.

***


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/renderers

This guide assists in migrating from FlowX v4.1.x to v4.6.0.

## Android SDK migration guide

### Initialization config changes

A new configuration parameter named `locale` was added to improve formatting the dates, numbers and currencies.

When the SDK initialization happens through the `FlowxSdkApi.getInstance().init(...)` method, the argument must be included inside the `config: SdkConfig` parameter value:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().init(
    ...
    config = SdkConfig(
        baseUrl = "URL to FlowX backend",
        imageBaseUrl = "URL to FlowX CMS Media Library",
        enginePath = "some_path",
        language = "en",
        locale = Locale.getDefault(), // e.g. Locale("en", "US"), Locale("fr", "CA")
        validators = mapOf("exact_25_in_length" to { it.length == 25 }),
        enableLog = false,
    ),
    ...
)
```

### Changes when starting a Flowx process

Two new parameters were added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The id of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun startProcess(
    projectId: String,
    processName: String,
    params: JSONObject = JSONObject(),
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes when resuming a Flowx process

One new parameter was added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the continued process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes regarding the implementation of Custom Components

The support for classical **[Android View](https://developer.android.com/reference/android/view/View)** system has been dropped.\

A Custom Component can now be implemented only by using the **[Compose](https://developer.android.com/compose)** UI system.

This means that the `CustomViewComponent` is now ignored in the internals of the SDK and has been marked as `@Deprecated` and will be completely removed in the next release.

> [!NOTE]
>
> There is no immediate need to update any of the existing components.

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```kotlin theme={"dark"}
fun changeLocaleSettings(locale: Locale, language: String)
```

### Library dependencies updates

* **[Kotlin](https://kotlinlang.org/)**: 1.9.22 **↗** **1.9.24**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping)**: 2024.02.00 **↗** **2024.06.00**
* **[Compose Compiler](https://developer.android.com/jetpack/androidx/releases/compose-compiler)**: 1.5.9 **↗** **1.5.14**
* **[Gson](https://github.com/google/gson)**: 2.10.1 **↗** **2.11.0**

***

## iOS SDK migration guide

### Initialization config changes

A new configuration parameter, named `locale` was added to improve formatting the dates, numbers and currencies.

The locale needs to be set on the `FXConfig.sharedInstance.configure` method

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    config.locale = "en-US"
    ...
}
```

### Changes when starting a process

Two new parameters were added on the 3 available start process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The uuid string of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func startProcess(projectId: String, 
                  name: String, 
                  params: [String : Any]?, 
                  isModal: Bool = false, 
                  showLoader: Bool = false, 
                  completion: ((UIViewController?) -> Void)?, 
                  onProcessEnded: (() -> Void)? = nil)
```

### Changes when resuming a Flowx process

One new parameter was added on the 3 available continue process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func continueExistingProcess(uuid: String, 
                             name: String, 
                             isModal: Bool = false, 
                             completion: ((UIViewController?) -> Void)? = nil, 
                             onProcessEnded: (() -> Void)? = nil)
```

### Updated FXDataSource protocol

A new method has been added to the `FXDataSource` protocol. Update conformance to protocol by adding the implementation of the new func.

```swift theme={"dark"}
func newProcessStarted(processInstanceUuid: String) {
    
}
```

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```swift theme={"dark"}
func changeLocaleSettings(locale: String?, language: String?)
```

***

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated and will use the latest versions Angular (version 19), thus all container apps that want to use the new SDKs should first update the Angular version of the container apps.

In the following we cover the migration guide for a container app from Angular v17 to v19 and the new SDKs.

**1. Remove old packages and their explicit dependencies (required dependency packages for new sdks are bundled in the libraries so we don't need)**

* remove `material-moment-adapter` unless it is used in custom components (usually together with material datepicker) and also the `moment` package (unless used elsewhere in the project )

```bash theme={"dark"}
npm uninstall @angular/material-moment-adapter
npm uninstall moment
```

* remove old FlowX SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/ui-sdk @flowx/ui-theme @flowx/ui-toolkit 
```

* in `angular.json` remove references to old stylesheets:

```bash theme={"dark"}
"./node_modules/@flowx/ui-sdk/src/assets/scss/style.scss"
"./node_modules/paperflow-web-components/src/assets/scss"
"./node_modules/@flowx/ui-sdk/src/assets/scss"
```

* remove old FlowX SDKs explicit dependencies. Please check before removing that packages are not used in the container app or custom components.

```bash theme={"dark"}
npm uninstall date-fns event-source-polyfill inputmask ng2-pdfjs-viewer vanillajs-datepicker @ngneat/input-mask deepmerge-ts marked-mangle
```

* remove deprecated `Angular Flex` library (the new sdks don't use it anymore and the package has been deprecated by the Angular team) unless it is not used in container app or custom components

```bash theme={"dark"}
npm uninstall @angular/flex-layout
```

**2. Update container app to Angular 18**

* Make sure to have the Angular CLI installed at version 18 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@18
```

* Run the Angular update for version 18

```bash theme={"dark"}
ng update @angular/core@18 @angular/cli@18
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@18
```

or, if the container app uses Angular Material, run:

```bash theme={"dark"}
ng update @angular/material@18
```

* Optionally, if your project uses other angular packages (ex. `NgRx`) please run migrations to v18 for each of them before proceeding. You can find details on the libraries documentation pages.

* Angular has changed the default build path in the `dist` folder, it now uses a `browser` folder for the build output. To place the output of the build command directly in the `dist/[APP_NAME]` folder, add the following change in `angular.json`:

```json theme={"dark"}
{
  ...
  "architect": {
    ...
    "build": {
      ...
      "options": {
        ...
        "outputPath": {
          "base": "dist/flowx-demo-app",
          "browser": "" <-- add this line
        },
      }
    }
  }
}

```

**3. Update container app to Angular 19**

* Make sure to have the Angular CLI installed at version 19 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Run the Angular update for version 19

```bash theme={"dark"}
ng update @angular/core@19 @angular/cli@19
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@19
```

or, if the container app uses Angular material, run:

```bash theme={"dark"}
ng update @angular/material@19
```

* Optionally, if your project uses other Angular packages (ex. `NgRx`) please run migrations to v19 for each of them before proceeding. You can find details on the libraries documentation pages.

* Also, it is recommended that you update the `target` and `module` settings in the `tsconfig.json` file to the new version, although be advised that this might require additional changes in the codebase due to new compilation errors that might arise.

```json theme={"dark"}
{
  ...
  "compilerOptions": {
      ...
      "target": "ES2022",
      "module": "ES2022"
  }
}
```

**4. Install the new FlowX SDK packages**

**Adding overrides for libraries that have a dependency on Angular version \< 19**

For some libraries, the required angular version might not be up to date or compatible with the new Angular version. In this case, you can add an override in the `package.json` file to force the library to use the new Angular version.

* For example, the `ng2-pdfjs-viewer` library has a dependency on Angular version 18 and will not work with the installed Angular version 19. To force the library to use the new Angular version, add the following override in the `package.json` file:

```json theme={"dark"}
{
  ...
  "overrides": {
    "ng2-pdfjs-viewer": {
      "@angular/common": "^19.0.0",
      "@angular/core": "^19.0.0",
      "ng-packagr": "^19.0.0"
    }
  }
}
```

**Install new packages**:

> [!WARNING]
>
> **ACTION REQUIRED**: Update to the latest version 4.6 to ensure optimal performance and compatibility.

```bash theme={"dark"}
npm install @flowx/core-sdk@5.63.0 @flowx/core-theme@5.63.0 @flowx/angular-sdk@5.63.0 @flowx/angular-theme@5.63.0 @flowx/angular-ui-toolkit@5.62.1 
```

* Install a type dependency for the SSE library:

```bash theme={"dark"}
npm install --save-dev @types/event-source-polyfill
```

* run through all the migration steps in the [New SDK Api changes](#new-sdk-api-changes) section below.

> [!NOTE]
>
> Each migration requires a 'clean' repository state. Make sure to commit all changes before starting the next migration step.

> [!TIP]
>
> After each Angular update it is recommended you restart your editor or TS Server, to use the new TS version since some import errors might appear.

### New SDK API changes

#### Renderer SDK component usage

In the Angular SDK, the `<flx-process-renderer>` component has two new parameters have been introduced: `projectInfo` and `locale`. These additions help support localization and project-specific configurations.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectInfo` | Object containing an `projectId` key, which identifies the project of the process to be started | `{projectId: string}` | Mandatory |
| `locale` | Provides region-specific settings for localization. | `string` | Mandatory |

Add the definitions for these properties in the class file of the component that uses the process renderer component:

```typescript theme={"dark"}
projectInfo = { projectId: 'your-project-id' },
locale = 'en-US',
```

Use these parameters in the template as inputs for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  ...
  [projectInfo]="projectInfo"
  [locale]="locale"
/>
```

#### API changes

Process Renderer:

| Category | Old Approach | New Approach |
| - | - | - |
| **Process Renderer** | `FlxProcessModule.forRoot({...})` | `FlxProcessModule.withConfig({...})` |

#### Import path updates

| Category | Old Approach | New Approach |
| - | - | - |
| **Import Paths** | `@flowx/ui-sdk` | `@flowx/angular-sdk` (or, in some cases `@flowx/core-sdk`) |
| | `@flowx/ui-theme` | `@flowx/angular-theme` |
| | `@flowx/ui-toolkit` | `@flowx/angular-ui-toolkit` |
| **Process Module** | `import {FlxProcessModule} from '@flowx/ui-sdk';` | `import {FlxProcessModule} from @flowx/angular-sdk` |
| **Localization Module** | `import {FlxLocalizationModule} from '@flowx/ui-sdk';`  Include in module imports | `import {FlxLocalizePipe} from '@flowx/angular-sdk';` Remove from module imports |
| **Task Management** | `import {FlxTaskManagementModule} from '@flowx/ui-sdk';` | `import {FlxTasksManagementComponent} from '@flowx/angular-sdk';` |
| **Client Store Interface** | `import {ClientStoreInterface} from '@flowx/ui-sdk';` | `import {ClientStoreInterface} from '@flowx/core-sdk';` |

> [!NOTE]
>
> You can also remove the `FlxLocalizationModule` from any `imports` arrays in modules, and import the `FlxLocalizePipe` instead

### Icon module update

The `withExtraIconSet` method has been replaced with `provideExtraIconSet`, which should now be used in the providers array.

```typescript theme={"dark"}
@NgModule({
  imports: [
    IconModule,  // Import the IconModule
  ],
  providers: [
    // Use provideExtraIconSet to add your custom icon set
    provideExtraIconSet({
      customIcon1: 'path/to/custom-icon1.svg',
      customIcon2: 'path/to/custom-icon2.svg',
      // Add more icons as needed
    })
  ]
})
export class AppModule {}
```

### Custom Interceptors

The new FlowX SDKs do not depend on Angular's `HttpClient` to make API calls, so existing interceptors must be adapted to a new format, for Request Interceptors (eg. custom headers) and Response Interceptors (eg. error handling)

For an overview of implementation details, please refer to the respective sections of the renderer documentation for the new API changes.

> [card] [Custom Interceptors](/4.7.x/sdks/angular-renderer#custom-interceptors)


# FlowX.AI 4.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025

Welcome, FlowX fam! The 4.6.0 update is here, and it’s packed with features designed to save you time, boost efficiency, and maybe even make you chuckle. Let’s dive into the details, feature by glorious feature. 🎉

## **What's new?** 🆕

### Projects: Order out of chaos

The new Project concept introduces a streamlined approach to managing and deploying complex projects within FlowX. By grouping all related resources—such as processes, enumerations, integrations, and assets—into a single, organized workspace, projects provide a cohesive view for efficient development and deployment.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

💼 **Key Benefits**:

* **Unified Workspace**: Group related processes, integrations, assets, and configurations into one tidy space.
* **Version Control**: Manage multiple builds and versions effortlessly. Rollbacks? No sweat.
* **Resource Sharing**: Reuse processes and configurations across projects like a boss.

> [!TIP]
>
> **Why you’ll love it**: It’s like going from a messy desk to an organized digital office.

🎥 **Quick Demo**: (Who needs text when you have visuals?)

<video />

> [card] [Projects](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

#### 🛠 Config vs Build Mode

**Config Mode**: Tinker, tweak, and perfect.

* Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's the workspace where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

**Build Mode**: Lock it, load it, deploy it.

* Build mode is the stage where the configurations you've set up are packaged into a deployable form. This is the runtime-ready version of your project, containing everything needed for it to function in a production environment. A build includes a snapshot of the project’s state at a given point, ensuring stability and predictability when deployed.

<video />

> [card] [Configuration](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

> [card] [Runtime](/4.7.x/docs/projects/runtime/builds)
>
> For more details, check out this section

***

### Integration Designer: Connect like a pro

It’s like a dating app for your systems: drag, drop, connect, and let the workflows flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)

API integration just got easier! Integration Designer simplifies connecting FlowX with external systems using REST APIs.

✨ **The magic of it**:

* **Drag-and-Drop Interface**: Map data, define workflows, and configure endpoints like a breeze.
* **Flexible Authorization**: Use Service Tokens, Bearer tokens, or go authentication-free.
* **Error Management**: Built-in tools ensure your integrations don’t ghost you.

> [!TIP]
>
> **Fun Fact**: Integration Designer doesn’t just test APIs (we love you, [Postman](https://www.postman.com/)❤️). It automates workflows, saving you tons of time.

> [card] [Integration Designer](/4.7.x/docs/platform-deep-dive/integrations/integration-designer)
>
> For more details, check out this section

***

### Merge Conflicts 2.0: Merge without the drama

Merging branches? We've overhauled the process to make it faster, smarter, and far less painful.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)

🧩 **What’s New**:

* **Advanced Conflict Detection**: Pinpoint issues by resource type (Processes, Enumerations, Media, etc.).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)

* **Resource-Level Resolution**: Resolve conflicts directly in the UI with:
  * JSON comparisons (color-coded for clarity!).
  * Navigation tools to jump between differences.
  * Progress tracking for reviewed items.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

> [!TIP]
>
> **Pro Tip**: Use the “Merge Anyway” option if you need to override unresolved conflicts (but use it wisely!).

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)

> [card] [Merge conflicts](/4.7.x/docs/projects/managing-applications/versioning#managing-conflicts)

***

### AI Agents: Smart, adaptable, always ready to help

FlowX AI Agents bring automation to your fingertips, powered by a flexible, LLM-agnostic core.

🤖 **Why It’s Cool**:

* Works with both open-source and private language models.
* Secure, on-premise deployments available.
* Automates business processes and interactions.

🎥 Check out a quick demo:

<video />

Stay tuned for more.

***

### Localization and Internationalization

FlowX is now more global-friendly with enhanced localization features.

> [card] Flexible Date, Time, Number, and Unit Formatting
>
> Enhanced formatting options for dates, times, numbers, and currencies with support for various international standards including short, medium, long, full, and custom formats.

> [card] Currency Customization
>
> Support for currency formatting with options to display values using ISO codes or symbols, adapting to user-selected locales and regional preferences.

> [card] Locale-Based Configurations
>
> Comprehensive settings for pluralization, capitalization, alignment, and sorting that adapt to regional requirements, helping cater to a diverse global user base.

> [card] Enhanced UI Component Formatting
>
> New options in the UI Designer to override general settings for text, messages, links, and form elements based on locale and region.

> [card] Document Localization
>
> Static and dynamically generated legal documents can now be customized based on regional and locale settings, improving compliance and communication with local audiences.

> [card] [Localization and internationalization](/4.7.x/docs/building-blocks/ui-designer/localization-and-i18n)
>
> For more details, check out this section

***

### Data Model 2.0: Data handling, but make it fashion

In this release, we've introduced Data Model 2.0, a major upgrade designed to simplify and enhance data handling. Key improvements include the introduction of reusable objects, a visual representation of complex data structures, and dynamic data binding, all aimed at creating a more reliable and intuitive experience. The new model ensures references are automatically updated when changes are made, streamlining data management across the platform.

**Highlights**:

* **New Root Element**: Provides a structural basis without impacting business logic, ensuring a clear and organized data structure.
* **Enhanced Data Binding**: Expanded to more areas, with dynamic updates based on changes in the data model.
* **Localization**: Added handling mechanism for locale-specific formatting, ensuring accurate data representation.

<video />

> [card] [Data model](/4.7.x/docs/building-blocks/process/data-model)
>
> For more details, check out this section

***

### Task management 2.0

We've enhanced Task Management capabilities, making it easier to create, track, and manage tasks efficiently. The updated Task Management features include customizable views and advanced filtering and sorting options for task data. Additionally, users can now implement both low-code and full-code solutions for a tailored Task Management experience, ensuring maximum flexibility for different business needs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

> [card] [Task Management](/4.7.x/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> For more details, check out this section

***

### UI Designer

#### Grid layout

We are excited to introduce the Grid Layout feature in this release, enhancing the flexibility and usability of the UI Designer for creating structured and responsive layouts. With the new Grid Layout, users can organize form elements, tables, and other components using a multi-column and row system, allowing for more complex, bidirectional designs compared to the previous flex-based layout.

<video />

> [accordion] This might happen after using it for the first time:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid-layout-first-time.jpg)

#### Table

The Table component is a simple and flexible way to display data in web applications. It lets you customize columns, add pagination, sort and filter data, and apply your own styling. You can resize columns, scroll through data, and even add actions like editing or deleting rows directly in the table. It’s easy to set up, with default columns and rows generated automatically based on your data.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)

> [card] [Table](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/table)
>
> For more details, check out this section

#### FlowX.AI UI Designer new navigator

We are thrilled to introduce the new and improved **UI Designer Navigator**, a major update designed to streamline your UI design process.

> [card] Enhanced UI Layer Panel Design and Functionality
>
> The UI layer panel has been redesigned for a more intuitive experience, making it easier to manage and navigate through your design elements.

> [card] Improved Drag and Drop Experience
>
> Dragging and dropping components in the preview is now smoother and more precise, allowing for faster and easier creation of UIs.

> [card] Flexible Root Component Management
>
> You can now change the root component from a form group to a container or vice versa, offering greater flexibility when copying nodes or resolving configuration problems.

> [card] Clearer Component Hierarchy
>
> It is now simpler to identify where you are placing a component within the hierarchy, thanks to the enhanced drag/reorder functionality in the right panel.

<video />

#### Conditional formatting for UI elements

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)

> [!NOTE]
>
> Conditional styling is available for **text**, **link**, and **container** UI elements based on specific conditions.

#### Hide expressions enhancements

Expanded hide expressions functionality to include:

* Cards
* Collection prototypes and children
* Table cell children (e.g., texts, images, buttons, links)

#### UI actions

* Added a new UI action **Start new project instance**
* Removed the **Start Process Inherit** UI action type.

#### UI action form updates

* Introduced **Functional** and **UX sections** for all action types, with a checkbox for **Add Analytics Name** in the UX section.
* Simplified custom and exclude key management.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2015.20.01.png)

***

### Start new project instance action

We’ve introduced the Start New Project Instance node action, enabling users to initiate a completely new process from within an ongoing one. This functionality is perfect for scenarios where isolated use cases are managed across different projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)

> [card] [Start new project instance action](/4.7.x/docs/building-blocks/actions/start-new-project-instance)

***

### Custom components validation

You are able to validate and retrieve data from a generated screen, including data from a custom form section. Additionally, you’ll have the ability to trigger and manage data directly within that section. This will be a major benefit for clients who have chosen to create custom components for the entire screen (for example, a form that isn’t supported natively by the platform).

> [card] [Validating elements](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/root-components/card#validating-elements)

***

### Autocomputed data to send

In previous platform versions, when creating your UI screens and working with data, you had to ensure that all the data stored in your process keys was saved in the process instance. This required adding an extra parameter called "Data to send" to the "Save Data" node action.

**Older versions** vs **v4.6.0**:

![older versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.x-aut.png)

![v.4.6](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.2-aut.png)

Now, with the autocompute feature, this step is no longer necessary, as the data is automatically saved and sent on your process instance.

> [!TIP]
>
> You no longer need to add "Save Data" node actions, but make sure to include "Forms to Validate" on the UI Actions. This helps ensure that data is submitted correctly and automatically activates any added validators where they exist.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/forms_to_validate.png)

However, you still have the option to customize which keys are included or excluded as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/include_exclude_keys.png)

***

### **Scripting UX Improvements**: *Write code like a wizard*

* **Autocomplete**: Get tailored suggestions based on your data model.
* **New Editors**: JSON and hide/disable expressions editors now include examples, syntax help, and better visual feedback.

<video />

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide%3Adisable%20editor.png)

***

### React & Angular SDKs

Dev friends, we heard you. FlowX now integrates smoothly into your React and Angular apps. It’s like peanut butter and jelly, but make it code.

#### React SDK

With the 4.6.0 release, we're excited to announce the launch of the FlowX React SDK! This new SDK empowers developers to seamlessly integrate FlowX.AI capabilities into React applications, making it easier than ever to build highly interactive, responsive, and dynamic user experiences.

To get started, simply install the FlowX React SDK via npm and check our documentation for examples and best practices!

> [card] [React SDK](/4.7.x/sdks/react-renderer)

#### New Angular SDK

We're excited to announce new releases for FlowX packages to support web applications:

* `@flowx/core-sdk`
* `@flowx/angular-sdk`
* `@flowx/angular-theme`
* `@flowx/angular-ui-toolkit`
* `@flowx/core-theme`

> [!WARNING]
>
> We recommend upgrading to the **latest** versions of all @flowx packages to take full advantage of these new features and improvements. Check the deployment guidelines for version details.

> [card] [Angular SDK migration guide](migrating-from-v4.1.x-to-v4.6.0/renderers#angular-sdk-migration-guide)

***

### Analytics integration for Container Apps

Container apps now support tracking "Screen Displayed" and "Action Executed" events, configurable in the UI Designer to improve insights into user interactions.

**UI Designer updates**

* **Analytics Screen Name:** Configurable under Root UI components (Cards and Containers) to enable tracking in analytics platforms like Google Analytics.

> [!TIP]
>
> "Screen Displayed" events support user task-based reporting, such as when a user task screen is shown.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.01.58.png)

> [!NOTE]
>
> The configured values are stored in `flowxProps.analytics`, making them accessible for integration with analytics tools.

* **Action Analytics:** Tracks user actions (e.g., button clicks) with tags set directly in the UI Action Form.

> [!NOTE]
>
> Added analytics configuration in the **UX Section** for all UI action types.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.20.53.png)

> [!NOTE]
>
> Values are saved in `params.analytics` via the PATCH `/actions` request.

**Renderers updates**

Renderers now expose a public API for triggering analytics events:

* **Screen Events:** Triggered on user task display, using `flowxProps.analytics`.
* **Action Events:** Triggered on action execution, using `params.analytics`.

Dynamic values such as process store keys and replace tags are supported for more contextual tracking.

***

### Plugin updates

**Notifications** and **Documents** plugins have been integrated as **project resources**.

***

### Scheduled Processes: Timer management reimagined

We've completely redesigned how you manage timer-triggered processes. Before 4.6.0, timer activation was managed through a quick actions menu in process definition headers; now it's handled via dedicated UI section in the Runtime tab under Scheduled Processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

🕒 Key Improvements:

* **Centralized Timer Management:** All process timers are now visible and manageable in one dedicated location
* **Persistent Settings:** Timer configurations persist across build exports/imports
* **Environment Control:** Activate or deactivate timers without redeploying your application

For more details, check out this section

> [card] [Scheduled Processes](/4.7.x/docs/projects/runtime/scheduled-processes)

## Bug fixes 🐞

### Rendering

* **Default Value Initialization for UI Elements**: Resolved an issue where certain UI elements were initialized with incorrect default values.

* **Improved Security for Hidden Fields**: Fixed a vulnerability where hidden fields could be accessed through browser developer tools.

* **Form Validation Reset on UI Dismissal**: Addressed an issue where form validation errors persisted after the UI was closed.

* **Keybinding Issues on Windows**: Fixed a bug where pressing specific keys triggered unintended operations in the designer.

* **Input Field Validation for Number Type**: Corrected the validation logic for number input fields to ensure consistent behavior.

* **Improved Datepicker Popup Positioning**: Resolved an issue where the datepicker popup overlapped the associated input field.

* **Manual Date Entry in Datepicker**: Fixed an issue where manually entering a date after selecting one from the datepicker caused errors.

* **Enhanced Update Mechanism for Custom Components**: Improved the reliability of updates for custom components to reflect changes consistently.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **New substitution tags with the same name on different branches aren’t flagged**: Merging branches that include new substitution tags with identical names on different branches does not trigger a conflict. Instead, both tags are retained, resulting in duplicate substitution tags with the same name but different values. This issue bypasses expected conflict detection and can lead to inconsistencies in substitution tag usage.
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] Notification and document templates
>
> * Branches with notification and document templates fail to merge into the main branch

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Changes 🔧

* **Web Renderer Caching:** Improved resource caching with browser mechanisms keyed to build IDs.
* **Process Designer:** Enhanced drag-and-drop functionality for node placement.

***

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.0](./deployment-guidelines-v4.6.0)

Migrating from v4.1.x:

> [card] [Migrating from v4.1.x to v4.6.0](./migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x)

> [card] [Changes in process configuration](./migrating-from-v4.1.x-to-v4.6.0/process-configuration)

> [card] [Renderer SDKs](./migrating-from-v4.1.x-to-v4.6.0/renderers)


# Deployment guidelines v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/deployment-guidelines-v4.6.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.

## Component versions

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.1.1** | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.6** | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.2** | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | 4.1.3 | 4.1.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.4** | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.25** | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.4** | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.11** | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

> [!NOTE]
>
> Note: The same container image and Helm chart are used for **Application Manager** and **Runtime Manager**.

## AI Agents

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.16** | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.15** | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.6** | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.27** | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.6.5** | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.1 | Keycloak | 22.x |
| 4.6.1 | Kafka | 3.2.x |
| 4.6.1 | PostgreSQL | 16.2.x |
| 4.6.1 | MongoDB | 7.0.x |
| 4.6.1 | Redis | 7.2.x |
| 4.6.1 | Elasticsearch | 7.17.x |
| 4.6.1 | Oracle Database | 21C/ 21-XE |
| 4.6.1 | Angular (Web SDK) | 19.x |
| 4.6.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.


# Migrating from previous versions to v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/migrating-from-v4.1.x-to-v4.6.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.0 version, make sure to first review the migration guide for v4.6.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

If you're moving from v4.1.x to v4.6.1, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.6.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025

FlowX.AI 4.6.1 is here with important fixes and improvements to keep things running smoothly. No new features this time—just focused updates to improve stability, fix bugs, and enhance overall performance. Simple, clean, and efficient.

## **What's new?** 🆕

### Rendering

**Form Elements** improvements:

* **Default Value Handling**: Defaults are applied only when no existing value is found, and set upon first display (with specific exceptions).
* **Data Consistency**: Form elements now save data in standardized formats based on type for improved reliability.
* **Smart Defaults**: Clear fallback behaviors for elements like switches, sliders, and checkboxes when no value is present.
* **Synchronized Inputs**: Linked form elements (e.g., input + slider) stay in sync with automatic value adjustments within set limits.
* **Dynamic Dependencies**: Form elements can dynamically adjust based on related components’ values for greater flexibility.

### Merge conflicts

* Improvement: merged version is now selected after a successful merge in versioning modal.

## Bug fixes 🐞

### Merge conflicts

* Fixed an issue that caused conflicts involving notification and document templates to fail.
* Fixed an issue where merges failed when a deleted configuration parameter was updated on a branch.
* Fixed an issue that resulted in duplicate substitution tag keys appearing in the merged version.
* Fixed an issue where merges failed due to the same dependency being added to both the source and target branches.
* Fixed issues related to workflow conflicts.

### Rendering

* Fixed an issue where documents from the media library were not loading correctly when added as a file preview in a user task.

### Integration Designer

* Fixed issue causing a 400 error when adding an enum mapper to the body tab due to incorrect data validation.
* Fixed issue where the last attribute in the objects table was not visible at higher zoom levels due to UI rendering constraints.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.1](./deployment-guidelines-v4.6.1)

Migrating from v4.6.0:

> [card] [Migrating from previous versions](./migrating-from-v4.1.x-to-v4.6.1)


# Deployment guidelines v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/deployment-guidelines-v4.7.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.0 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.
>
> In version 4.7, the import-export functionality for application-version is no longer backward compatible.
>
> * Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
>
> * Similarly, zip files from earlier versions cannot be imported into 4.7.
>
> Note: Zip files for builds and specific resources remain unaffected.

## Component versions

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.3.1** | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.5.1** | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.11** | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.2** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.5** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.0** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.1** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.2** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.4** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.4** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.3** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.2** | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.1.0** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.5** | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.12** | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.21** | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.7.2** | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.13** | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.31** | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.0** | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.0 | Keycloak | 22.x, 26.x |
| 4.7.0 | Kafka | 3.2.x |
| 4.7.0 | PostgreSQL | 16.2.x |
| 4.7.0 | Oracle Database | 21c, 23ai |
| 4.7.0 | MongoDB | 7.0.x |
| 4.7.0 | Redis | 7.2.x |
| 4.7.0 | Elasticsearch | 7.17.x |
| 4.7.0 | Angular (Web SDK) | 19.x |
| 4.7.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/migrating-from-v4.1.x-to-v4.7.0

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025

FlowX.AI 4.7.0 is here to keep your projects vibing, your merges drama-free, and your configs under control—because struggling with your platform is *so* last season. 😎🔥

## What's new? 🆕

✅ Copy resources across projects\
✅ Duplicate resources (in the same project/library)\
✅ Resources usage tracking\
✅ Smarter merge conflict detection & resolution\
✅ Libraries can now define configuration parameters\
✅ Dynamic Kafka topics using configuration parameters

## Projects

### Copy resources across projects

Moving resources between projects is now **fast and seamless**. The new **Copy to Another Project** feature ensures all dependencies stay intact, eliminating the hassle of manual adjustments.

<video />

> [tab] How it works
>
> 1️⃣ **Select a destination** – Choose the target project or library.\
> 2️⃣ **Pick a branch (if applicable)** – For WIP versions, select the target branch.\
> 3️⃣ **Review dependencies** – The system displays referenced resources and validates dependencies.\
> 4️⃣ **Resolve identifier conflicts** – If an identifier already exists in the destination, you'll be prompted to either:
>
> * **Keep both** (create a duplicate)
> * **Replace** (overwrite the existing resource)
> * **Use destination** (retain the existing resource without copying)

> [tab] Why it’s better
>
> * **No broken references** – Everything stays connected.
> * **Auto-add missing dependencies** – No manual setup required.
> * **Works with WIP & committed versions (only from committed to WIP)** – Flexibility for your workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.48.33.png)

> [card] [Copy resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Duplicate resources

> [tab] What you can duplicate
>
> The **Duplicate Resource** feature lets users create a copy of an existing resource within the same project or library version, streamlining workflows and ensuring quick reusability.
>
> <video />
>
> You can duplicate the following resources:
>
> * **Processes**
> * **Enumerations**
> * **Media files (including Global media library files)**
> * **Notification templates**
> * **Document templates**
> * **Views**

> [tab] How it works
>
> * **Duplicate options** are available from each resource’s three-dot menu (table row & secondary navigation).
> * When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).
> * **Cancel** to discard changes or **Duplicate** to create an exact copy in the same project/library version.
> * **Success confirmation:** The system navigates to the newly created resource and displays a success message.
> * **Error handling:** If a resource with the same name/key exists, users will be prompted to rename it before proceeding.

> [tab] Why it’s useful
>
> 💡 **Use cases:**
>
> * Quickly iterate on existing resources.
> * Reduce redundant manual setup.
> * Maintain consistency within projects.
> * Easily clone complex configurations for testing and modifications.

> [card] [Duplicate resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Track where your resources are used

Monitoring your resources has never been simpler and more efficient. Stay on top of where and how they’re being used.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

> [card] [Process Usage](../../4.7.x/docs/projects/resources#process-usage)
>
> Track where a process is referenced, with a clear **Usage Overview modal** that dynamically updates when references change.

> [card] [Enumeration Usage](../../4.7.x/docs/projects/resources#enumeration-usage)
>
> See where enumerations are used across **UI, Data Models, Systems, and Workflows** before making changes.

> [card] [Media Library Usage](../../4.7.x/docs/projects/resources#media-library-usage)
>
> Identify **which UI elements reference media assets** so you don’t accidentally break designs.

📌 **Before deleting a resource, a confirmation modal lists all affected references. No more surprises!**

***

### Configuration parameters overrides

🔹 **Libraries can now define configuration parameters** to help test processes or workflows that use those parameters.

🔹 However, **libraries do not support overrides**.

* **Overrides for library config parameters must be done within a project** where the library is added as a dependency.
* **Overrides cannot be added in libraries directly.**

<video />

💡 **What this means:**

* Libraries provide **default values** for configuration parameters.
* Projects using those libraries **can override these values** as needed.
* This ensures **clear separation between library defaults and project-specific configurations** while maintaining flexibility.

> [!TIP]
>
> ✨ **Overrides take precedence** over library values—so you stay in control.

***

### Merge conflict enhancements

Merge conflicts are never fun, but at least now they’re **easier to handle**.

> [card] Better Conflict Detection
>
> 🚨 Prevents merging if identical resource identifiers exist in both branches (e.g., same name, key, or code).

> [card] Resizable Merge Conflict Tree
>
> 🖥️ Resize the merge conflict tree for better visibility and navigation.

> [card] New Conflict Type
>
> 📢 A new conflict detection system for parent changes/deletions in both branches.

***

## SDK changes

### Expose Enumerations API in Angular SDK

Developers can now dynamically retrieve enumerations via the Angular SDK, making it easier to use enums in custom components like dropdowns.

> [!TIP]
>
> How it Works?
>
> A new method in the Angular SDK allows direct access to enumerations, reducing manual imports and improving flexibility.

**Usage**

The `getEnumeration()` function returns key-value pairs that can be used in components that need enumeration data:

```typescript theme={"dark"}
getEnumeration(enumName: string): { value: string; label: string }[]
```

* `enumName` (string) – The name of the enumeration to retrieve (e.g., 'UserRoles', 'cities')
* Returns: An array of objects containing value-label pairs representing the requested enumeration

> [accordion] Example usage
>
> The enumeration service works seamlessly with Angular's resource API for reactive state management:
>
> ```typescript theme={"dark"}
> import { Component, effect, model, resource } from '@angular/core';
> import { getEnumeration } from '@flowx/angular-sdk';
>
> @Component({
>   selector: 'app-dynamic-enum-select',
>   template: `
>     <select>
>       @for (option of options.value(); track option.value) {
>         <option [value]="option.value">{{ option.label }}</option>
>       }
>     </select>
>
>     <button (click)="enumName.set('cities')">Load Cities</button>
>     <button (click)="enumName.set('countries')">Load Countries</button>
>   `
> })
> export class DynamicEnumSelectComponent {
>   // Create a signal to track the currently selected enum
>   enumName = model<string>('UserRoles');
>
>   // Use resource API to reactively load enumerations when enumName changes
>   options = resource({
>     request: this.enumName,
>     loader: ({ request: enumName }) => getEnumeration(enumName),
>   });
>
>   constructor() {
>     effect(() => {
>       if (this.options.isLoading()) {
>         console.log(`Loading enumeration: ${this.enumName()}`);
>       } else {
>         console.log(`Loaded enumeration: ${this.enumName()}`, this.options.value());
>       }
>     });
>   }
> }
> ```

***

## **Bug fixes** 🐞

✔️ Improved **merge conflict detection and resolution**\
✔️ Fixed **UI rendering issues**

***

## Changes

### Dynamic Kafka topics

FlowX 4.7.0 introduces **Dynamic Kafka Topics**, enabling more flexible and configurable messaging across processes.

🔹 **What’s new?**

* Use **Configuration Parameters** to dynamically assign Kafka topics in **Kafka Send** and **Kafka Receive** actions.
* Concatenate predefined parameters with process variables for **on-the-fly topic selection**.
* Reduce hardcoded values and **simplify environment-specific configurations**.

💡 **Why it matters:**

* Makes **Kafka integrations more scalable** across different deployments.
* Supports **multi-topic messaging** for different use cases without manual updates.
* Ensures better **reusability and maintainability** in process configurations.

📌 Check the [Kafka Send Action](../../4.7.x/docs/building-blocks/actions/kafka-send-action#dynamic-kafka-topics) section for setup details.

***

### Export/import compatibility

In version 4.7, the import-export functionality for application-version is no longer backward compatible.

* Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
* Similarly, zip files from earlier versions cannot be imported into 4.7.

> [!NOTE]
>
> Zip files for builds and specific resources remain unaffected.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.0](./deployment-guidelines-v4.7.0)\
📌 [Migration Guide (from v4.6.0)](./migrating-from-v4.1.x-to-v4.7.0)


# Deployment guidelines v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/deployment-guidelines-v4.7.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.1.

## Component versions

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.5.1** | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.7.6** | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.3.3** | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.4** | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.7** | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.3** | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.4** | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.6** | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.6** | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.6** | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.5** | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.9** | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.2** | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.7** | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.13** | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.27** | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.2** | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.17** | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.35** | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.4** | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.1 | Keycloak | 22.x, 26.x |
| 4.7.1 | Kafka | 3.2.x |
| 4.7.1 | PostgreSQL | 16.2.x |
| 4.7.1 | Oracle Database | 21c, 23ai |
| 4.7.1 | MongoDB | 7.0.x |
| 4.7.1 | Redis | 7.2.x |
| 4.7.1 | Elasticsearch | 7.17.x |
| 4.7.1 | Angular (Web SDK) | 19.x |
| 4.7.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/migrating-from-v4.1.x-to-v4.7.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025

FlowX.AI 4.7.1 brings enhanced resource navigation, better error detection, and workflow improvements to make your development journey even smoother! 🚀

## What's new? 🆕

✅ Enhanced resource usage tracking with direct navigation\
✅ Upgraded JavaScript support to ECMAScript 15 (2024) in Business Rules\
✅ Added Python 3 support with 3x performance improvement\
✅ Major performance enhancements for both design time and runtime\
✅ Security enhancements for runtime endpoints

## Projects

### Enhanced resource usage navigation

We've significantly improved how you navigate between resources and their references with direct navigation capabilities. Now you can easily jump from the usage tracking panel to the exact location where a resource is referenced.

<video />

> [tab] How it works
>
> 1️⃣ **Access resource usage** – View where a resource is being used through the usage panel.\
> 2️⃣ **One-click navigation** – Use the new redirect button to jump directly to the referenced location.\
> 3️⃣ **Missing resource detection** – Easily identify and fix missing resource references with clear indicators.

> [tab] Why it's better
>
> * **Faster troubleshooting** – Directly navigate to problem areas without manual searching.
> * **Improved productivity** – Less time spent hunting down references means more time building.
> * **Better error prevention** – Quickly spot and fix missing resources before they cause issues.

***

## Enhanced scripting capabilities

### ECMAScript 15 (2024) support for Business Rules

FlowX.AI 4.7.1 brings the latest JavaScript features to your business rules with an upgrade to ECMAScript 15 (2024).

> [tab] What's included
>
> * Access to the latest JavaScript language features
> * Modern syntax for cleaner, more maintainable rules
> * Enhanced tooling and IDE support

> [tab] Benefits
>
> * Write more concise and expressive business rules
> * Leverage modern JavaScript patterns and best practices
> * Improved developer experience with better IDE integration

> [!NOTE]
>
> **Important Configuration Note:** Nashorn engine remains the default runtime. To enable GraalJS support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Nashorn will be used.

### Python 3 support for Business Rules

We've upgraded our Python scripting capabilities to Python 3, delivering significant performance improvements while maintaining compatibility.

> [card] 3x Faster Execution
>
> Python scripts now run at least 3 times faster than with Python 2.7.

> [card] Modern Python Features
>
> Take advantage of Python 3's improved syntax, libraries, and security features.

> [!NOTE]
>
> **Important Configuration Note:** Python 2.7 remains the default runtime. To enable Python 3 support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Python 2.7 will be used.

More details about the scripting capabilities can be found in the [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts) section.

***

## Performance improvements 🚀

We've made significant performance enhancements throughout the platform to make your development and runtime experience smoother and faster.

### Design time improvements

For large processes, you'll notice dramatic improvements:

| Operation | Improvement |
| - | - |
| Cloning a process | **5x faster** |
| Opening a process | **70x faster** |

### Runtime enhancements

Platform average response time has been **reduced by 20%** in our comprehensive benchmark\*.

> [!NOTE]
>
> \*The benchmark simulates a typical business process with a combination of user and service tasks. It includes rules that automate decision-making, as well as events for time-sensitive actions and communication. The process also covers various system functions, ensuring the platform can efficiently manage complex workflows with both individual and parallel tasks.

***

## Security enhancements 🔒

We've significantly improved platform security by implementing proper endpoint access controls and separation between internal and public-facing APIs.

> [card] Enhanced API Security
>
> Runtime execution proxy vulnerability addressed with comprehensive endpoint updates.

> [card] Access Control Improvements
>
> Better separation between design-time and runtime endpoints with proper access controls.

### Endpoint security updates

We've implemented a comprehensive security update for runtime endpoints to prevent potential proxy vulnerabilities:

* Redesigned API structure to separate internal (`runtime-internal`) from external-facing (`runtime`) endpoints
* Migrated design-time operations to use `runtime-internal` endpoints for enhanced security
* Moved specific management operations to dedicated `build-mgmt` endpoints
* Updated all API clients to use the new secure endpoints

> [!NOTE]
>
> **Important:** Make sure to update to the corresponding  version of the [**`flowx-admin`**](./deployment-guidelines-v4.7.1#component-versions) to benefit from these security enhancements.

### Enhanced resource caching in Angular SDK

The Angular SDK now includes an improved caching mechanism for CMS resources, optimizing loading times and performance. The cache parameter on the `flx-process-renderer` component allows developers to control caching behavior in different environments.

> [card] [Read about caching in Angular SDK](../../4.7.x/sdks/angular-renderer#caching)
>
> Find details on controlling CMS resource caching during development and production.

## **Bug fixes** 🐞

* Fixed various minor issues to improve overall stability
* Resolved some UI inconsistencies
* Addresses performance optimizations
* Fixed general usability issues

***

## **Additional information**

📌 [Deployment Guidelines v4.7.1](./deployment-guidelines-v4.7.1)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.1)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/deployment-guidelines-v4.7.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.2 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.2.

## Component versions

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.9.0** | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.5** | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.8** | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.10** | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.16** | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.12** | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.13** | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.14** | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.13** | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.14** | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.2.0** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.12** | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.16** | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.9** | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.35** | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.9** | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.24** | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.1** | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.9** | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.2 | Keycloak | 22.x, 26.x |
| 4.7.2 | Kafka | 3.2.x |
| 4.7.2 | PostgreSQL | 16.2.x |
| 4.7.2 | Oracle Database | 21c, 23ai |
| 4.7.2 | MongoDB | 7.0.x |
| 4.7.2 | Redis | 7.2.x |
| 4.7.2 | Elasticsearch | 7.17.x |
| 4.7.2 | Angular (Web SDK) | 19.x |
| 4.7.2 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## Additional configuration

Added new environment variable on Process Engine:

### Message routing configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

> [!NOTE]
>
> When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.


# Migrating from previous versions to v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/migrating-from-v4.1.x-to-v4.7.2

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 and v4.7.1 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.2 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025

FlowX.AI 4.7.2 delivers improved merge conflict handling with retry capabilities, deprecates DMN business rules, and fixes issues with subprocess handling, media file imports, and OCR functionality to enhance your development workflow! 🚀

## **What's new? 🆕**

✅ Improved merge conflict handling with retry functionality\
✅ Enhanced error messages during failed merges\
✅ Streamlined workflow for resolving merge conflicts

## Merge conflicts

### Improved error messages when merge fails

We've enhanced the merge conflict resolution experience with more informative error messages and a new retry functionality:

* When a merge fails, users can now see a "Retry merge" button on the Merge failed modal
* Clicking this button allows users to attempt the merge again without losing previous work

The system now handles two distinct scenarios:

**1. When conflicts exist:**

* The system opens the Merge conflicts panel with the previous state of the merge before the failed attempt
* This preserves all your conflict resolution work so you can fix the specific issues that caused the failure

![Merge failed with conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20conflicts.png)

**2. When no conflicts exist:**

* The system automatically retries the merge operation
* This streamlines the workflow when the merge failure was due to temporary issues rather than actual conflicts

![Merge failed without conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20no%20conflicts.png)

## Process engine

### Deprecated DMN rules

In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.

**What's changing:**

* DMN is no longer available as a language option when configuring business rule actions

**What's next:**
For guidance on using alternative business rule languages, please refer to our [supported scripting languages](../../../../4.7.x/docs/building-blocks/supported-scripts) documentation.

## **Bug fixes** 🐞

* Resolved export/import issues with media library files, particularly for applications migrated from earlier versions
* Fixed an issue where parallel multi-instance Call Activity would incorrectly trigger a subprocess when using an empty array list as a variable
* Fixed a display issue where not all subprocesses were visible in the subprocess list on smaller screens
* Fixed a bug where message events couldn't be caught when placed directly after an uninterrupting timer event
* Resolved "Unsupported Media Type" errors when importing application versions with media file binaries
* Fixed an issue where color palette changes in Theme settings couldn't be saved at 100% browser resolution on smaller screens
* Fixed a issue where OCR plugin failed due to missing correlation headers

***

## **Additional information**

📌 [Deployment Guidelines v4.7.2](./deployment-guidelines-v4.7.2)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.2)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/deployment-guidelines-v4.7.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.3 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.3.

## Component versions

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.13.0** | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.13** | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.12** | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.11** | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.17** | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.13** | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.16** | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.15** | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.14** | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.15** | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.14** | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.6.0** | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.11** | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.14** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.15** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.37** | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.12** | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.26** | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.3** | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.11** | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.3 | Keycloak | 22.x, 26.x |
| 4.7.3 | Kafka | 3.2.x |
| 4.7.3 | PostgreSQL | 16.2.x |
| 4.7.3 | Oracle Database | 21c, 23ai |
| 4.7.3 | MongoDB | 7.0.x |
| 4.7.3 | Redis | 7.2.x |
| 4.7.3 | Elasticsearch | 7.17.x |
| 4.7.3 | Angular (Web SDK) | 19.x |
| 4.7.3 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/migrating-from-v4.1.x-to-v4.7.3

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.3 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025

FlowX.AI 4.7.3 enhances workflow conflict resolution, adds configurable enumeration ordering, and fixes data streams, UI templates, and application export/import issues to improve your development experience! 🚀

## **What's new? 🆕**

✅ Enhanced workflow conflict resolution with improved visibility\
✅ Added ability to configure order attributes on enumerations\
✅ Upgraded conflict management interface for better user experience

## Merge conflicts - workflow improvements

### Enhanced workflow conflict resolution

We've significantly improved how [**workflow**](../../4.7.x/docs/platform-deep-dive/integrations/integration-designer#workflows) conflicts are handled in this release:

* Upgraded to a new version (v2) of the workflow conflict resolution interface
* Now only showing workflow entities that have actual conflicts, making it easier to identify and address issues
* Streamlined the conflict resolution process for a more efficient workflow

![Workflow conflict resolution](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/workflow_conflicts.png)

> [!NOTE]
>
> **Important note about sequence conflicts:**
>
> When resolving conflicts related to sequences, if you select one of the conflicting sequences, nodes that are no longer connected may remain "orphaned" on the canvas in the merged version. This design decision was made to prevent accidental node deletion. If these orphaned nodes are no longer needed, they can be manually removed in subsequent versions.

## Configurable enumeration ordering

You can now configure the **Order** attribute on enumerations, giving you greater control over how enumeration values are displayed in dropdown lists:

* Set specific order values for each enumeration entry
* Control the presentation sequence in UI components
* Improve user experience by arranging options in logical or prioritized order

![Enum order](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/enum_order.png)

> [!NOTE]
>
> **Limitation:** When changing the order value for an enumeration entry, the system does not automatically update the order values of other entries. You'll need to manually adjust the order values of other entries in the interface.

## **Bug fixes** 🐞

* Fixed an issue where workflow nodes could have two output sequences
* Resolved a problem with enumerations displaying in the wrong order in dropdown lists
* Fixed an authentication issue where users would receive 401 unauthorized errors when executing actions after token refresh
* Fixed a UI behavior issue where slider actions configured with "onChange" were incorrectly triggered when entering a screen instead of only when modified
* Fixed an issue with identical advancing IDs occurring in multi-pod deployments due to missing hostname command in GraalVM docker images
* Resolved an issue preventing media library migration from default application
* Fixed the "Go to reference" functionality from data model attributes that was not correctly redirecting to referenced elements
* Fixed an error during application export/import where "There already exists a tagged build for this project version" was preventing successful imports
* Restored support for multiple topics in Data Stream Topics feature, which was previously only listening to the first topic in the list
* Fixed a 500 error that occurred when attempting to create child actions on certain nodes
* Fixed a critical issue where UI templates would disappear when creating a new version of an application after performing undo operations on pasted templates
* Fixed a bug where updates to the subprocess in a Start subprocess action weren't being saved properly
* Fixed an issue with the "Send email" button remaining disabled in the Test notification template feature after correcting validation errors
* Fixed an error that occurred when trying to export document templates containing null values in templateMap
* Fixed a display issue where Tokens, Workflows, and Subprocesses information wasn't showing in process instances after migration from 4.7.1 to 4.7.2
* Fixed a UI issue where business rule code wasn't displayed when testing business rules in committed versions

***

## **Additional information**

📌 [Deployment Guidelines v4.7.3](./deployment-guidelines-v4.7.3)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.3)


# Deployment guidelines v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/deployment-guidelines-v4.7.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.4 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.4.

## Component versions

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.15.2** | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.9.2** | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.16** | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.13** | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.19** | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.15** | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.18** | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.17** | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.16** | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.17** | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.16** | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.7.2** | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.3.2** | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.19** | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.23** | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.39** | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.17** | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.28** | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.5** | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.13** | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.4 | Keycloak | 22.x, 26.x |
| 4.7.4 | Kafka | 3.2.x |
| 4.7.4 | PostgreSQL | 16.2.x |
| 4.7.4 | Oracle Database | 21c, 23ai |
| 4.7.4 | MongoDB | 7.0.x |
| 4.7.4 | Redis | 7.2.x |
| 4.7.4 | Elasticsearch | 7.17.x |
| 4.7.4 | Angular (Web SDK) | 19.x |
| 4.7.4 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## **Additional information**

* Added new environment variable `OPTIMISTIC_LOCKING_RETRIES` to control the number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

Elasticsearch indexing configuration:

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)


# Migrating from previous versions to v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/migrating-from-v4.1.x-to-v4.7.4

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.4 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025

FlowX.AI 4.7.4 enhances system stability with Spring Boot updates and resolves critical issues across build exports, reporting, SDK functionality, and cross-platform consistency to deliver a more reliable development experience! 🚀

## **What's new? 🆕**

✅ Platform enhancements\
✅ Added retry mechanism for ES indexing to handle key‑identifier errors\
✅ Fixed critical build export timeout issues\
✅ Improved reporting data representation\
✅ Enhanced cross-platform consistency

### Platform Enhancements ⚙️

* Enhanced system stability
* Latest security patches
* Improved performance

### Elasticsearch indexing - configurable retry mechanism

* `OPTIMISTIC_LOCKING_RETRIES`: Number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)

### Data-sync run status monitoring

* Added the ability to view the run status of data-sync jobs directly in the platform interface
* Monitor the execution status of all data-sync jobs from the Jobs dashboard
* Quickly identify failed jobs for faster troubleshooting

![Data-sync run status monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-20%20at%2010.55.19.png)

## **Bug fixes** 🐞

* **Build export timeouts**: Resolved intermittent timeout failures on projects with dependency libraries; exports now consistently complete or retry correctly.
* **Build creation on merge without conflicts**: Fixed an issue where merging one branch into another without conflicts—and switching the active policy—did not trigger a new build, forcing users to manually create a version; now, merges automatically update build resources and create the new version so merged changes appear at runtime.
* **Project version import stashing conflict**: Resolved an error where importing a branched project version across environments would inadvertently stash other versions—restoring successful import, fixing the GET history API response, and ensuring the Project versions history modal renders correctly.
* **CosmosDB workflows**: Fixed an issue preventing the workflow instances list from loading in the Integration Designer when using CosmosDB.
* **Reporting arrays**: Corrected array formatting in the `reporting_data` table (process-engine schema).
* **CMS permissions**: Restored backward compatibility for FlowX SDK v4.7+ by removing the unintended `media_library_read` requirement for processes containing images (behavior now matches v4.1).
* **onChange action behavior**: Standardized onChange/onBlur across web, Android, and iOS so users cannot continue typing after token advancement unless explicitly allowed.
* **React SDK ternary expressions**: Fixed an “Invalid Expression” error in SDK v5.86.1—ternary expressions in computed values (e.g. `return ${var1} ? "Onboarded" : (${var2} ? "Non-eligible" : "Ready for Onboarding");`) now parse correctly as they did in v5.62.1.
* **Elasticsearch indexing**: Fixed an issue where the engine was not retrying to index process instances when it encountered concurrent-update errors on key identifiers.
* **iOS SSE token refresh**: Fixed an issue in iOS SDK where Server-Sent Events connections would occasionally use expired JWT tokens instead of refreshed ones, causing 401 errors and process hangs in production environments.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.4](./deployment-guidelines-v4.7.4)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.4)


# Deployment guidelines v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/deployment-guidelines-v4.7.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.5 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.5.

## Component versions

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.17.0** | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.12.2** | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.5.1** | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.1.1** | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.1.1** | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.2.1** | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.4.1** | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.3.1** | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.1.1** | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.9.0** | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.4.1** | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.21** | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.24** | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.18** | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.5 | Keycloak | 22, 26+ |
| 4.7.5 | Kafka | 3.2 - 3.9 |
| 4.7.5 | PostgreSQL | 16 - 17 |
| 4.7.5 | Oracle Database | 21c, 23ai |
| 4.7.5 | MongoDB | 7 - 8 |
| 4.7.5 | Redis | 7.2 - 8.0 |
| 4.7.5 | Elasticsearch | 7 - 8 |
| 4.7.5 | Angular (Web SDK) | 19.x |
| 4.7.5 | React (Web SDK) | 18.x |

> [!NOTE]
>
> **New in 4.7.5: Support for more 3rd Party Dependencies**
>
> FlowX.AI 4.7.5 introduces support for more versions of third-party dependencies:
>
> * All versions are officially supported throughout the entire LTS lifetime
> * Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major release
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/migrating-from-v4.1.x-to-v4.7.5

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.5 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.5 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025

FlowX.AI 4.7.5 enhances system stability with introducing support for more 3rd party dependency and introduces High Availability improvements with Redis Sentinel mode support to deliver a more reliable and scalable development experience! 🚀

## **What's new? 🆕**

✅ **Platform enhancements**\
✅ **Analytics enhancements**

### Platform enhancements ⚙️

**Extended Third-Party Dependency Support** - Introducing support for more versions of third-party dependencies:

* All versions are officially supported throughout the entire LTS lifetime
* Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major releases for critical infrastructure components, ensuring all supported versions are officially maintained throughout the entire LTS lifetime. This enables organizations to perform gradual dependency upgrades during the LTS period, preparing infrastructure to meet the minimum requirements for the next FlowX.AI major release while maintaining full platform support and stability.

### Analytics enhancements ⚙️

* Improved analytics events with enriched metadata for action events across all platforms (Web, iOS, Android). Action events now include screen context, component type identification, and component labels, providing deeper insights into user interactions and enabling more granular analytics tracking for better user experience optimization.

More details:

> [card] [Angular Renderer](../../../../4.7.x/sdks/angular-renderer#analytics)

> [card] [React Renderer](../../../../4.7.x/sdks/react-renderer#analytics)

> [card] [iOS Renderer](../../../../4.7.x/sdks/ios-renderer#collecting-analytics-events)

> [card] [Android Renderer](../../../../4.7.x/sdks/android-renderer#collecting-analytics-events)

### Runtime Manager deployment changes

> [!NOTE]
>
> **Prior to 4.7.5:** Runtime Manager was deployed using `application-manager` chart/image with manual `SPRING_APPLICATION_NAME`: "runtime-manager" configuration.
> Starting with 4.7.5: Runtime Manager has its own dedicated chart and image with proper defaults.

> [!TIP]
>
> Migration Required

* Switch to new chart: Use runtime-manager chart instead of application-manager
* Verify image: Ensure image name is runtime-manager (default in new chart)
* Remove override: `SPRING_APPLICATION_NAME`: "runtime-manager" can be removed (optional)

> [!WARNING]
>
> You may need to delete the existing runtime-manager deployment before upgrading due to Kubernetes label changes that cause `kubectl apply` to fail.

## **Bug fixes** 🐞

* **Fixed Task Manager loading issue with data type changes** - Resolved critical issue where Task Manager would fail to load and throw `NullPointerException`   when process variables were changed from date to string data types, even after updating the data model and clearing cache
* **Fixed All Tasks view missing on build import** - Resolved issue where importing builds from one environment to another would fail to create the All Tasks view, when accessing the Task Manager area
* **Fixed unassign operation causing runtime errors** - Resolved 500 Internal Server Error when accessing process data after performing unassign operations via Kafka messages, where null ownerDetails would cause `NullPointerException` during JSON serialization
* **Fixed CMS-Core export failures with AWS S3 buckets** - Resolved issue where CMS-Core would add double slashes in S3 object paths when creating exports, causing 404 NoSuchKey errors with AWS S3 (while working correctly with MinIO). Fixed path construction to ensure compatibility with both AWS S3 and MinIO storage backends
* **Fixed active policy version resolution** - Resolved issue where importing application versions to environments with existing WIP versions would incorrectly activate the stashed WIP version instead of the imported committed version, causing graph display failures and incorrect active policy settings

***

## **Additional information**

📌 [Deployment Guidelines v4.7.5](./deployment-guidelines-v4.7.5)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.5)


# Deployment guidelines v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/deployment-guidelines-v4.7.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.6 will permanently prevent you from importing process definitions and resources created in versions 4.7.5 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

> [!WARNING]
>
> **Audit data retention change**
>
> Starting with FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. In 4.7.5 and earlier, the service created this policy only once, on the first installation.
>
> The policy it writes has a single hot phase that rolls the audit data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. The default is `30` days; in 4.7.5 and earlier, the rollover period was a fixed 1 day.
>
> Any phase you added to this policy directly in Elasticsearch, such as a delete phase, is removed the next time the Audit service starts. Without a delete phase, old audit indices are never deleted and audit storage keeps growing.
>
> To keep the previous daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1` on the Audit service.

## Component versions

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.21.1** | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.15.2** | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.8.2** | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.4.0** | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.4.0** | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.5.0** | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.7.0** | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.6.0** | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.5.0** | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.13.0** | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.7.1** | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.29** | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.19** | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.6 | Keycloak | 22, 26+ |
| 4.7.6 | Kafka | 3.2 - 3.9 |
| 4.7.6 | PostgreSQL | 16 - 17 |
| 4.7.6 | OracleDB | 21c, 23ai |
| 4.7.6 | MongoDB | 7 - 8 |
| 4.7.6 | Redis | 7.2 - 8.0 |
| 4.7.6 | Elasticsearch | 7 - 8 |
| 4.7.6 | Angular (Web SDK) | 19.x |
| 4.7.6 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8

## Configuration Parameters

Starting with FlowX.AI 4.7.6, Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment.

> [card] [Integration Designer setup](/4.7.x/setup-guides/integration-designer-setup#configuration-parameters)

> [card] [Process Engine setup](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters)

> [card] [Application Manager setup](/4.7.x/setup-guides/application-manager)


# Migrating from previous versions to v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/migrating-from-v4.1.x-to-v4.7.6

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.6 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.6](../v4.7.6-july-2025/deployment-guidelines-v4.7.6)

> [card] [Deployment guidelines v4.7.5](../v4.7.5-july-2025/deployment-guidelines-v4.7.5)

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1/)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.6 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025

This release includes significant improvements to logging configuration and resolves some issues across the Designer, Process Engine, and Integration Designer components.

> [!WARNING]
>
> Upgrading to 4.7.6 changes how the Audit service manages its Elasticsearch lifecycle policy: the policy is rewritten on every startup and the default rollover period changes from 1 day to 30 days. See the [Deployment guidelines](./deployment-guidelines-v4.7.6) before upgrading.

## **What's new? 🆕**

> [card] Improved default logging configuration
>
> Changed logging verbosity to reduce clutter & log sizes, increasing visibility for more relevant log messages.

> [card] Improved the ability to use deployment specific variables as Configuration Parameters (at process runtime)
>
> Now Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment. Check the [**Deployment Guidelines**](./deployment-guidelines-v4.7.6#configuration-parameters) for more details.

> [card] Improved runtime performance
>
> Improved runtime performance by better distributing the execution of nodes across all components.

> [card] Improved the speed of listing process instances
>
> Improved the speed of listing process instances by 4-6x on environments with a lot of process executions.

> [card] Added the ability to change logging levels at runtime
>
> This feature allows you to dynamically adjust logging levels without requiring a service restart, providing more flexibility in managing log output.

> [card] Reduced config deployment complexity
>
> The previously used `CONFIG_PROFILE` environment variable is no longer required as the default configs have been aligned with the recommended profiles.

## **Bug fixes** 🐞

> [accordion] \[Designer] Task view display issue
>
> Fixed task view list row content display issue where table rows were overlapping and text was not vertically centered in the latest Chrome browser version (138). The task view now properly displays centered content without text cutoff.

> [accordion] \[Integration Designer] JSON parsing error
>
> Fixed JSON parsing error when sending JSON result to REST body. Resolved issue where JSON objects generated in script tasks were causing "Unexpected character" errors when used in REST endpoint body parameters with \$ syntax.

> [accordion] \[Branch Merge] Media file export errors
>
> Fixed media file export errors during branch merges. Resolved issue where merging multiple branches created from the same main version would fail with "400 Bad Request" errors for media files after the first successful merge, even when no merge conflicts were present.

> [accordion] \[Process Designer] Rollback issue
>
> Fixed rollback issue during version submission errors. Resolved problem where processes were incorrectly marked as deleted in the database when submit version operations failed with 500 errors, preventing proper rollback and causing subsequent 404 "Process not found" errors.

> [accordion] \[Process Designer] Missing resources during copy operation
>
> Fixed missing resources during copy to another project/library operation. Resolved issue where forms with validation in UserTask nodes were not being copied when copying processes between projects or libraries.

> [accordion] \[Process Designer] Branch with missing resources and 404 errors
>
> Fixed issue where specific branches derived from main version would experience resource corruption, including missing process definitions (404 errors), missing Integration Designer resources, and commit failures.

> [accordion] \[Process Designer] Parallel multi-instance visual bug
>
> Fixed parallel multi-instance designer visual bug and database errors. Resolved issue where call activity nodes with parallel multi-instance enabled created duplicate "inputKey" and "outputKey" entries, causing visual bugs (missing collection key fields) and database update errors during node modifications.

> [accordion] \[Process Engine] Kafka message distribution
>
> Fixed Kafka message distribution across partitions. Resolved issue where Kafka messages were distributed as batches across partitions, causing increased usage of a limited number of partitions, instead of following the round-robin distribution per message strategy.

***

## **Additional information**

> [card] [Deployment Guidelines v4.7.6](./deployment-guidelines-v4.7.6)
>
> Step-by-step deployment instructions and configuration details for this release.

> [card] [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.6)
>
> Complete guide for migrating from version 4.1.x to 4.7.6 with breaking changes and migration steps.


# Deployment guidelines v4.7.7
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/deployment-guidelines-v4.7.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.7 will permanently prevent you from importing process definitions and resources created in versions 4.7.6 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.22.3** | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.16.3** | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.97.1** | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.9.2** | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.6.2** | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.8.2** | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.7.2** | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.6.2** | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.14.2** | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.8.1** | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.40** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.21** | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.29** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.14** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.7 | Keycloak | 22, 26+ |
| 4.7.7 | Kafka | 3.2 - 3.9 |
| 4.7.7 | PostgreSQL | 16 - 17 |
| 4.7.7 | OracleDB | 19c, 21c, 23ai |
| 4.7.7 | MongoDB | 7 - 8 |
| 4.7.7 | Redis | 7.2 - 8.0 |
| 4.7.7 | Elasticsearch | 7 - 8 |
| 4.7.7 | Angular (Web SDK) | 19.x |
| 4.7.7 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.7 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Improved robustness on auto-scaling process-engine and on Kafka node failures\
✅ Improvements on how configuration parameters can now be retrieved from Kubernetes secrets and ConfigMaps\
✅ Vulnerability fixes

## Configuration parameters

Improved configuration parameters retrieval from Kubernetes secrets and ConfigMaps. More details here:

> [card] [FlowX Engine](../../4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#dynamic-configuration-parameters-retrieval)

> [card] [Integration Designer](../../4.7.x/setup-guides/integration-designer-setup#dynamic-configuration-parameters-retrieval)

## Bug fixes

> [accordion] \[Designer] JSON size limit on input data
>
> Fixed JSON payload size limit issue causing "403 payload too large" errors when starting processes. More details [**here**](../../4.7.x/docs/flowx-designer/managing-a-project-flow/starting-a-process#starting-a-process-via-user-interface).

> [accordion] Improved robustness on Kafka node failures
>
> If one Kafka node fails, platform health check fails. This is now fixed.

> [accordion] \[UI Designer] Theming on accordion card
>
> Fixed theming issue where Card component styling was not properly applied when switched to accordion mode.

> [accordion] \[Angular SDK] Loader does not stop on subprocess end
>
> Fixed loader persistence issue where loaders initiated by "show loader" actions in subprocess UserTasks would continue displaying after subprocess completion.

> [accordion] \[Process Designer] Merge error with duplicate embed node keys
>
> Fixed merge conflict error occurring when copying and pasting embed nodes in processes.

> [accordion] \[Process Engine] Process execution stalls on REST-triggered flows when engine replica fails
>
> Fixed process execution recovery issue where REST API-triggered service tasks would hang indefinitely if the handling engine replica failed mid-execution.

> [accordion] \[Process Designer] Merge fails with duplicate key error after creating child branch to jump over broken WIP
>
> Fixed merge conflict error occurring when creating child branches from working commits to bypass broken WIP versions.


# Deployment guidelines v4.7.8
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/deployment-guidelines-v4.7.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.8 will permanently prevent you from importing process definitions and resources created in versions 4.7.7 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.23.2** | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.17.3** | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.10.3** | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.7.2** | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.9.2** | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.8.2** | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.7.2** | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.15.3** | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.9.2** | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.22** | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.8 | Keycloak | 22, 26+ |
| 4.7.8 | Kafka | 3.2 - 3.9 |
| 4.7.8 | PostgreSQL | 16 - 17 |
| 4.7.8 | OracleDB | 19c, 21c, 23ai |
| 4.7.8 | MongoDB | 7 - 8 |
| 4.7.8 | Redis | 7.2 - 8.0 |
| 4.7.8 | Elasticsearch | 7 - 8 |
| 4.7.8 | Angular (Web SDK) | 19.x |
| 4.7.8 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.8 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes\
✅ Support for [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title

### Support for Substitution Tags in Table column title

Now you can use [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title.

## Bug fixes

> [accordion] \[UI Designer] Card expansion state not calculated correctly
>
> Resolved an issue where, in certain situations, the expanded state of cards was not calculated correctly. This prevented users from expanding cards as expected.

> [accordion] \[UI Designer] Document preview component texts not translated
>
> Fixed localization issue where document preview component texts remained in English regardless of the selected language setting.

> [accordion] \[Designer] Groups tab fails to load with Keycloak 26.3
>
> Fixed compatibility issue with Keycloak 26.3 where the Groups tab would remain in loading state indefinitely due to new "description" field in group representations.

> [accordion] \[CMS] Import fails for PDF files with null thumbnail path
>
> Fixed import failure when PDF media files were exported with null `thumbnailStoragePath` values, preventing successful deployment of build or app versions to fresh environments.

> [accordion] \[Runtime Manager] Improved error logging for proxy failures
>
> Enhanced error logging detail when Runtime Manager proxy requests fail, providing better root cause information for debugging infrastructure issues like DNS problems or service unavailability.

> [accordion] \[Integration Designer] Slow performance on first workflow execution after pod restart
>
> Fixed performance issue where workflow IF node processing time increased from 3-5 seconds to 15-20 seconds on the first execution after Integration Designer pod restart.

> [accordion] \[Process Engine] Active step was incorrectly computed when the token is reset
>
> Fixed issue where the active step was incorrectly computed when the token is reset.


# Release Notes
Source: https://docs.flowx.ai/release-notes/overview

What shipped in every FlowX.AI release - new features, bug fixes, deployment guidelines, and migration steps for the 5.9.x and 5.1.x LTS lines and monthly feature releases.

Release notes · FlowX.AI

What shipped.
Every release, every line.

What shipped in every FlowX.AI release: new features, bug fixes, deployment guidelines, and migration steps. Pick your line below, or jump straight to the latest LTS patch and feature release.

[Latest LTS: 5.9.6](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[Feature release: 6.0.0](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

> [!NOTE]
>
> **Long Term Support (LTS) Versions:** LTS versions receive extended support with security updates and critical bug fixes. **5.9.x** is the current FlowX.AI LTS line, recommended for production environments requiring stability and long-term support. Support for the **5.1.x** line ended with 5.1.14, its final maintenance release. To keep receiving fixes, move to 5.9.x: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview). Release notes for older lines, including 5.1.x and 4.7.x, remain published for reference.
>
> **Feature Releases:** Versions released between LTS lines (such as 5.10.0) introduce new capabilities and are deployed to FlowX.AI SaaS environments as they ship. Self-hosted deployments receive these features consolidated into the next LTS release.

01 · Latest

## Latest releases

[LTS
v5.9.6
Maintenance release for the 5.9.x LTS line. Released on October 20th, 2026.](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)

[FEATURE
v6.0.0
Feature release, live on FlowX.AI SaaS. Released on October 30th, 2026.](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[LTS
v5.1.14
Final maintenance release for the 5.1.x LTS line. Released on October 30th, 2026.](./v5.x/v5.1.x-lts/v5.1.14-october-2026)

> [!TIP]
>
> **New cookbook:** [reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation), from email intake to exception review. More end-to-end builds are in the [cookbooks](/5.9/cookbooks/overview).

***

02 · All releases

## All releases

Planning a 5.9.x upgrade? The [5.9.x LTS changelog](./v5.x/5.9-lts-changelog) lists every change in each 5.9.x maintenance release on one page, with an RSS feed.

Moving from 5.9.x to 6.0.0? The [5.9.x to 6.0.0 changelog](./v6.x/5.9-to-6.0-changelog) lists every change from the 5.10 to 5.13 feature releases and 6.0.0 on one page, with an RSS feed.

versionlinereleased

[v6.0.0FRfeature releaseOctober 30th, 2026→](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[v5.1.14LTSmaintenance · 5.1.x LTS lineOctober 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.14-october-2026)
[v5.9.6LTSmaintenance · 5.9.x LTS lineOctober 20th, 2026→](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[v5.13.0FRfeature releaseSeptember 28th, 2026→](./v5.x/v5.13.0-september-2026/v5.13.0-september-2026)
[v5.9.5LTSmaintenance · 5.9.x LTS lineSeptember 23rd, 2026→](./v5.x/v5.9.5-september-2026/v5.9.5-september-2026)
[v5.1.13LTSmaintenance · 5.1.x LTS lineSeptember 18th, 2026→](./v5.x/v5.1.x-lts/v5.1.13-september-2026)
[v5.12.0FRfeature releaseSeptember 3rd, 2026→](./v5.x/v5.12.0-september-2026/v5.12.0-september-2026)
[v5.9.4LTSmaintenance · 5.9.x LTS lineAugust 27th, 2026→](./v5.x/v5.9.4-august-2026/v5.9.4-august-2026)
[v5.1.12LTSmaintenance · 5.1.x LTS lineAugust 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.12-august-2026)
[v5.11.0FRfeature releaseAugust 11th, 2026→](./v5.x/v5.11.0-august-2026/v5.11.0-august-2026)
[v5.9.3LTSmaintenance · 5.9.x LTS lineJuly 30th, 2026→](./v5.x/v5.9.3-july-2026/v5.9.3-july-2026)
[v5.1.11LTSmaintenance · 5.1.x LTS lineJuly 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.11-july-2026)
[v5.9.2LTSmaintenance · 5.9.x LTS lineJuly 10th, 2026→](./v5.x/v5.9.2-july-2026/v5.9.2-july-2026)
[v5.10.0FRfeature releaseJuly 7th, 2026→](./v5.x/v5.10.0-july-2026/v5.10.0-july-2026)
[v5.1.10LTSmaintenance · 5.1.x LTS lineJune 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.10-june-2026)
[v5.9.1LTSmaintenance · 5.9.x LTS lineJune 15th, 2026→](./v5.x/v5.9.1-june-2026/v5.9.1-june-2026)
[v5.9.0LTSfirst release of the 5.9.x LTS lineJune 2nd, 2026→](./v5.x/v5.9.0-june-2026/v5.9.0-june-2026)
[v5.1.9LTSLTS maintenance releaseMay 29th, 2026→](./v5.x/v5.1.x-lts/v5.1.9-may-2026)
[v5.8.0FRfeature releaseMay 10th, 2026→](./v5.x/v5.8.0-may-2026/v5.8.0-may-2026)
[v5.1.8LTSLTS maintenance releaseApril 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.8-april-2026)
[v5.7.0FRfeature releaseApril 28th, 2026→](./v5.x/v5.7.0-april-2026/v5.7.0-april-2026)
[v5.6.0FRfeature releaseMarch 25th, 2026→](./v5.x/v5.6.0-march-2026/v5.6.0-march-2026)
[v5.1.7LTSLTS maintenance releaseMarch 26th, 2026→](./v5.x/v5.1.x-lts/v5.1.7-march-2026)
[v5.1.6LTSLTS maintenance releaseMarch 16th, 2026→](./v5.x/v5.1.x-lts/v5.1.6-march-2026)
[v5.5.0FRfeature releaseFebruary 27th, 2026→](./v5.x/v5.5.0-february-2026/v5.5.0-february-2026)
[v5.1.5LTSLTS maintenance releaseFebruary 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.5-february-2026)
[v5.1.4LTSLTS maintenance releaseFebruary 9th, 2026→](./v5.x/v5.1.x-lts/v5.1.4-february-2026)
[v5.4.0FRfeature releaseJanuary 30th, 2026→](./v5.x/v5.4.0-january-2026/v5.4.0-january-2026)
[v5.1.3LTSLTS maintenance releaseJanuary 15th, 2026→](./v5.x/v5.1.x-lts/v5.1.3-january-2026)
[v5.3.0FRfeature releaseDecember 24th, 2025→](./v5.x/v5.3.0-december-2025/v5.3.0-december-2025)
[v5.1.2LTSLTS maintenance releaseDecember 3rd, 2025→](./v5.x/v5.1.x-lts/v5.1.2-december-2025)
[v5.2.0FRfeature releaseNovember 10th, 2025→](./v5.x/v5.2.0-november-2025/v5.2.0-november-2025)
[v5.1.1LTSLTS maintenance releaseNovember 10th, 2025→](./v5.x/v5.1.x-lts/v5.1.1-november-2025)
[v4.7.11LTSLTS maintenance releaseDecember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025)
[v4.7.10LTSLTS maintenance releaseNovember 17th, 2025→](./v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025)
[v4.7.9LTSLTS maintenance releaseOctober 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025)
[v5.1.0LTSLTS maintenance releaseOctober 2nd, 2025→](./v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025)
[v4.7.8LTSLTS maintenance releaseSeptember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025)
[v4.7.7LTSLTS maintenance releaseAugust 20th, 2025→](./v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025)
[v5.0.0FRfeature releaseJuly 31st, 2025→](./v5.x/v5.0.0-july-2025/v5.0.0-july-2025)
[v4.7.6LTSLTS maintenance releaseJuly 18th, 2025→](./v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025)
[v4.7.5LTSLTS maintenance releaseJune 19th, 2025→](./v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025)
[v4.7.4LTSLTS maintenance releaseMay 15th, 2025→](./v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025)
[v4.7.3LTSLTS maintenance releaseApril 14th, 2025→](./v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025)
[v4.7.2LTSLTS maintenance releaseMarch 26th, 2025→](./v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025)
[v4.7.1LTSLTS maintenance releaseMarch 7th, 2025→](./v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025)
[v4.7.0LTSLTS maintenance releaseFebruary 24th, 2025→](./v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025)
[v4.6.1FRfeature releaseFebruary 7th, 2025→](./v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025)
[v4.6.0FRfeature releaseJanuary 23rd, 2025→](./v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025)
[v4.1.5LTSLTS maintenance releaseSeptember 23rd, 2024→](./v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024)
[v4.1.4LTSLTS maintenance releaseSeptember 6th, 2024→](./v4.x/v4.1.x/v4.1.4-september-2024/v4.1.4-september-2024)
[v4.1.3LTSLTS maintenance releaseAugust 12th, 2024→](./v4.x/v4.1.x/v4.1.3-august-2024/v4.1.3-august-2024)
[v4.1.2LTSLTS maintenance releaseJune 8th, 2024→](./v4.x/v4.1.x/v4.1.2-june-2024/v4.1.2-june-2024)
[v4.1.1LTSLTS maintenance releaseJune 17th, 2024→](./v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024)
[v4.1.0LTSLTS maintenance releaseMay 30th, 2024→](./v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024)
[v4.0.0FRfeature releaseApril 18th, 2024→](./v4.x/v4.0.0-april-2024/v4.0.0-april-2024)

> [!NOTE]
>
> Releases from the **4.5.x (tech preview)** and **4.2.x** lines are not listed above. You can find them in the sidebar under **Release Notes** → **v4.x**.

***

> [accordion] Version 3.x.x
>
> > [card] [v3.4.8 - June 2024](/release-notes/v3.x.x/v3.4.8-june-2024/v3.4.8-june-2024)
> >
> > Explore the latest enhancements and fixes introduced in June 2024.
>
> > [card] [v3.4.7 - January 2024](/release-notes/v3.x.x/v3.4.7-january-2024/v3.4.7-january-2024)
> >
> > Explore the latest enhancements and fixes introduced in January 2024.
>
> > [card] [v3.4.6 - December 2023](/release-notes/v3.x.x/v3.4.6-december-2023/v3.4.6-december-2023)
> >
> > Explore the latest enhancements and fixes introduced in December 2023.
>
> > [card] [v3.4.5 - November 2023](/release-notes/v3.x.x/v3.4.5-november-2023/v3.4.5-november-2023)
> >
> > Explore the latest enhancements and fixes introduced in November 2023.
>
> > [card] [v3.4.4 - November 2023](/release-notes/v3.x.x/v3.4.4-november-2023/v3.4.4-november-2023)
> >
> > Discover the significant changes and improvements made in November 2023.
>
> > [card] [v3.4.3 - October 2023](/release-notes/v3.x.x/v3.4.3-october-2023/v3.4.3-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.2 - October 2023](/release-notes/v3.x.x/v3.4.2-october-2023/v3.4.2-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.1 - September 2023](/release-notes/v3.x.x/v3.4.1-september-2023/v3.4.1-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.4.0 - September 2023](/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.3.0 - July 2023](/release-notes/v3.x.x/v3.3.0-july-2023/v3.3.0-july-2023)
> >
> > Discover the significant changes and improvements made in July 2023.
>
> > [card] [v3.2.0 - April 2023](/release-notes/v3.x.x/v3.2.0-april-2023/v3.2.0-april-2023)
> >
> > Discover the significant changes and improvements made in April 2023.
>
> > [card] [v3.1.0 - March 2023](/release-notes/v3.x.x/v3.1.0-march-2023/v3.1.0-march-2023)
> >
> > Discover the significant changes and improvements made in March 2023.
>
> > [card] [v3.0.0 - February 2023](/release-notes/v3.x.x/v3.0.0-february-2023/v3.0.0-february-2023)
> >
> > Discover the significant changes and improvements made in February 2023.


# FlowX.AI 5.9.x LTS changelog
Source: https://docs.flowx.ai/release-notes/v5.x/5.9-lts-changelog

Every change in each FlowX.AI 5.9.x LTS maintenance release, grouped by type and component, with an RSS feed for upgrade planning.

This page lists every change in each 5.9.x LTS maintenance release, newest first. Use the RSS button at the top of the page to subscribe and get each new patch as it ships. Mobile renderers and the React Native SDK are covered in their own release notes. Moving to 6.0.0? See the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog).

**5.9.6**

October 2026

**Upgrade actions:** migrate to the `flowx-ai` Helm chart if you installed the `ai-platform` chart, create the `ai.flowx.build.deployment-failed.v1` Kafka topic and allow it in your ACLs, re-publish any build whose deployment failed shortly before the upgrade, review workflow node retry settings, grant the connection-test permissions to custom roles, and allow extra Integration Designer startup time on a large `workflow_instances` collection. Details are in the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).

#### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

#### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect.
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#mongodb-setting-names).
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6) for its version.

#### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.6 release notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026) · [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6)

**5.9.5**

September 2026

**Upgrade actions:** let the `ai-services` consumer group reach zero lag and allow the new AI consumer groups in Kafka ACLs, add private database hosts to the NoSQL DB runner allowlist, set every service-account client secret on `authorization-system`, rename `cache_error_total` in dashboards and alerts, re-expose `loggers` if you change log levels at runtime, and review the deployment guidelines if you had already turned on data partitioning, because the conversion to native partitions is one way. Details are in the [5.9.5 upgrade notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#upgrade-notes).

#### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#native-postgresql-partitioning).

#### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.

#### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.5 release notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026) · [5.9.5 deployment guidelines](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5)

**5.9.4**

August 2026

**Upgrade actions:** move the registry out of `image.repository` if you embedded it there (no action if you set `global.imageRegistry`), grant the Liquibase lock permissions to each service's database user on Oracle, create the `flowx-events-gateway-sa` client yourself if you manage Keycloak clients outside the Helm charts, and move host apps that embed the Angular SDK to Angular 21. Details are in the [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4#configuration-changes).

#### Changed

* **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.
* **Angular SDK:** the Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps that embed the Angular SDK must be on Angular 21. The npm and node requirements are unchanged.
* **Cross-version import:** importing a project build or version exported from an older platform line completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten.
* **Database migrations:** the lock that guards Liquibase schema migrations at service startup is a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration releases its lock when the database closes the session. Service accounts no longer need the `pods/status` permission. Oracle deployments need new database grants.
* **Events Gateway:** authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`. Helm chart deployments where `authorization-system` runs its migrations with Keycloak admin access need no action.
* **Helm charts:** the container image reference is split into `image.registry` and `image.repository`. The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. The default image location is unchanged.
* **Integration Designer:** service startup no longer scans the full token-instance collection, and the run-list summary queries are indexed.
* **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.
* **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.

#### Fixed

* **Actions:** deleting an action whose business rule calls a function works instead of returning a server error.
* **Build export:** retrying a build export re-attempts a dependency library whose own export timed out, so the parent build can finish.
* **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output from trailing empty cells and rows.
* **Entry points:** the entry-point picker in version settings lists only processes and UI flows from the current project.
* **Gateways:** an expression that fails to evaluate on an exclusive gateway surfaces as an incident on the process instance instead of only in the service logs.
* **Generated documents:** a document whose storage write fails returns an error instead of being recorded as successful. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.
* **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is listed once instead of once per consuming project version.
* **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives during a background synchronization, and merging versions no longer fails with a navigation-areas error.
* **Renderers:** the document preview shows its subtitle, and the file-upload error message follows the configured theme.
* **Reusable UI templates:** static input mappings configured on a reusable template are applied at runtime.
* **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.
* **Task management:** the row-selection checkbox column no longer carries an invisible sort control that re-sorted the view and cleared the selection, and changing the page size no longer opens the wrong process from the list.
* **Themes and CMS resources:** exporting a theme no longer includes duplicate copies of system icons, and importing no longer leaves system substitution tags missing.
* **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.4 release notes](/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026) · [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4)

**5.9.3**

July 2026

**Upgrade actions:** none. The new Events Gateway and Integration Designer settings ship with working defaults. Details are in the [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3#configuration-changes).

#### Changed

* **Events Gateway:** new settings tune the dedicated Redis connection pool for blocking reads, and the default blocking-read duration is lowered from 5 seconds to 1 second. If you set the blocking-read duration explicitly, review it against the new default.
* **Integration Designer:** a new setting sets the number of partitions for auto-created workflow Kafka topics. Existing topics are not modified.
* **Media Library:** PDF assets in the list can be opened in a new tab.
* **Process start:** web renderers keep the loading indicator visible until the first user task renders.

#### Fixed

* **Build import:** a transient database write conflict during a multi-dependency import no longer drops a dependency's build, which caused runtime errors on substitution tags and enumerations. Large imports may take slightly longer.
* **Date Picker:** the calendar anchors to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.
* **Designer:** opening Runtime after expanding a component's Permissions section no longer freezes the Designer, and a pending AI UI-generation draft no longer locks the process diagram read-only.
* **Projects:** creating a project with the same name as a deleted project returns a validation error instead of an internal server error.
* **Real-time event delivery:** the Events Gateway no longer leaks Redis connections. Blocking reads run on a dedicated connection pool with Redis Cluster support, so the gateway no longer needs periodic restarts under sustained load.
* **Task management:** deleting a swimlane allocation rule removes only that rule, clicking Save twice no longer creates duplicate rules, and task views no longer reset when the same view is open from different workspaces.
* **Workflows:** a workflow no longer freezes silently after a step exhausts its retries.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.3 release notes](/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026) · [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3)

**5.9.2**

July 2026

**Upgrade actions:** update any Keycloak group mapper or external IdP claim that emits the end-user group `User` to `Users Group`, remove records of the organization-ID migration or other Liquibase changesets you marked as executed by hand on an earlier 5.9.x (contact FlowX support for the list first), upgrade the AI Platform chart and the core services together, and update dashboards, alerts, and log queries that match the `ai-platform-` service name prefix. Details are in the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#upgrade-overview).

#### New

* **AI agents and data models:** AI Designer and AI Developer use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it.
* **AI workflow nodes:** JSON schema fields support `${}` placeholders.
* **Chat file uploads:** end users can attach multiple files in a chat-driven app. Uploads are indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content.
* **Document Parser:** a new LiteParse engine parses PDFs and images locally without GPU or AI calls, and OCR supports English, Romanian, Hungarian, and Bulgarian.
* **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.
* **Knowledge bases:** a Custom Agent node can select multiple knowledge bases, each exposed to the agent as its own retrieval tool, and retrieval can span multiple knowledge bases in a workflow.
* **SQL data sources:** queries on SQL data sources can be tested from the builds list.
* **Use in reporting:** the reporting toggle is available on UI flows and workflows.

#### Changed

* **AI node structured output:** responses from AI nodes with a response schema are validated against it, with automatic repair retries, and node logs include the failure reason and rejected output.
* **AI Platform services:** services are deployed under their plain names, without the `ai-platform-` prefix on pod, service, and image names, and the bundled Qdrant subchart is renamed the same way. Core services resolve AI components by the new names.
* **Audit log:** records sharing, user invitations, designer-user, end-user, and group management, actions on process instances and UI flows, adding a dependency, and terminating process, workflow, or UI flow instances.
* **Copy to project:** copying a process or UI flow to another project also copies its roles.
* **Data archiving:** archiving detaches a partition only when every process or workflow instance in it has finished. New settings for terminating stuck instances and backfilling legacy rows are off by default.
* **Default end-user group:** the group that the 5.1.x upgrade migration creates is renamed from `User` to `Users Group`. Groups your admins created are not renamed.
* **Designer:** the Event Handlers section appears higher in the component configuration panel, and the keys to save for collection items and bundled custom-component inputs are computed automatically.
* **Kafka reconnects:** platform services use a gentler broker-reconnect backoff by default, and repeated Kafka connection errors log at a quieter level.

#### Fixed

* **Active policy:** the user list on the override active-policy form is no longer empty.
* **Application manager:** the runtime-application organization-ID migration converts existing data correctly.
* **Audit logs:** filtering audit entries by user works when the username differs from the email address.
* **Build export with media files:** exporting a build with media file content produces an archive that contains the binaries.
* **Chat:** the floating chat position is calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.
* **CMS enumerations:** cascading-enum value lookups resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.
* **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.
* **Data sync with private CA certificates:** data-sync migrations that call HTTPS endpoints, such as Keycloak, no longer fail certificate validation in environments that use an internal certificate authority.
* **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.
* **Project version merge:** a merge no longer fails with a 500 error.
* **Redis Cluster:** UI template cache keys map to the same cluster slot, which prevents cross-slot errors.
* **Reusable UI templates:** actions are no longer missing at runtime when a template is nested in multiple levels of containers.
* **Self-hosted installation and upgrade:** Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding work on self-hosted environments.
* **Workflow data:** archiving batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine is fixed.
* Stability fixes across the Designer, the renderers, and the backend services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.2 release notes](/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026) · [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2)

**5.9.1**

June 2026

**Upgrade actions:** none for deployments where the Helm chart provisions Kafka topics. If you provision Kafka topics or ACLs manually, create the topics added in 5.9.1. Details are in the [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics).

#### New

* **AI permissions:** AI runtime usage and AI build-time tooling (AI Designer, agent building, code generation) are governed by two separate permissions. When AI is turned off, AI icons and entry points are hidden instead of shown disabled, and build-time helpers such as code generation and "Add comment" follow the dev-agent permission.
* **File Preview:** scroll-trigger event handlers, including a "document end" trigger, let a flow detect when a user scrolls through a document or reaches its end, for example to enable an **Accept** button only after the user reaches the end of an agreement.
* **File upload:** the upload button supports a configurable icon, set in the Designer.
* **Microsoft Outlook:** connections support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
* **Script engine:** business rules, reusable functions, and node rules can each run on the native engine (the 5.9 default) or the legacy GraalVM engine. Rules created before the switch to native keep running on GraalVM until you migrate them, and new rules default to native.

#### Changed

* **AI Designer:** generates UI from a flat template format instead of 3-level nesting, supports more component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates incrementally instead of regenerating them, and can generate reusable UI templates.
* **Kafka topics:** new topics carry runtime config-param change events, runtime instance terminations, resource cache evictions, and evaluation improvement suggestions. The Helm chart provisions them.
* **Merge conflicts:** merge-conflict handling for custom components and UI Flows identifies resources more clearly.
* **Organization settings:** navigation and design improvements.
* **Platform Status:** reports AI Platform components and their databases alongside the core services.
* **Runtime config params:** changes reach the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
* **Workflows:** storage of running steps is optimized, workflows and processes launched from a UI Flow inherit the build of the parent UI Flow, and AI node failures show the error details and model reasoning in the workflow run logs.

#### Fixed

* **Actions:** GET actions no longer fire with undefined parameters.
* **AI chat:** agent responses no longer reappear in chat after stop and refresh, and the builder-agent chat no longer duplicates messages.
* **Copy to project:** copying a process or workflow to another project succeeds, and copied workflows appear in the target project.
* **End-user login:** a null value is no longer cached when looking up the "All end-users" group, which could block logins until data sync completed.
* **File Preview:** previews render correctly, events fire inside collections, a fixed height applies at runtime, and preview resources no longer fail with CORS errors.
* **File Storage:** FTP test connection and file operations resolve configuration-parameter placeholders, and FTP file preview works when the root path has no leading slash.
* **Forms to validate:** scrolling covers the full component hierarchy, placeholders update, and chat and tab-bar components are selected correctly.
* **Hide and disable conditions:** conditions on UI templates, processes, and UI Flows apply at runtime for Designer users without workspace access.
* **Invitations:** an invited Designer user added as an Organization owner is assigned to a workspace.
* **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
* **Modals:** dropdowns no longer flicker, and long key names no longer break the layout.
* **Process instances:** loading an instance with a very large execution graph no longer crashes the browser.
* **Task management:** headers follow the theme in React and Angular, and the filter window no longer disappears after applying criteria.
* **Theme admin:** "copy to" no longer loses theme content.
* **Timer events:** activating a start timer event after a new build regenerated the process resource ID no longer fails with a 500 (duplicate key) error.
* **UI Flow:** images display in preview after refresh, and returning from an expired UI Flow no longer loses the theme UUID.
* **Usage Overview:** opening a usage overview no longer fails with a 500 error.
* **Web renderer:** the button shadow and modal content padding are restored, and components render when a media-file storage path is null.
* **Workflows:** END PARALLEL output no longer includes data from before the parallel branches started, and NoSQL node run logs no longer crash when a node fails before building its options.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.1 release notes](/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026) · [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1)


# Deployment guidelines v5.1.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.10 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.9 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.9 → 5.1.10**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **process-engine** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **admin** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **designer** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **cms-core** | 9.46.3 | 9.46.2 | 9.45.4 | 9.44.2 |
| **scheduler-core** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **events-gateway** | 9.36.4 | 9.36.2 | 9.35.4 | 9.34.1 |
| **notification-plugin** | 9.39.3 | 9.39.2 | 9.38.4 | 9.37.1 |
| **document-plugin** | 9.44.3 | 9.44.2 | 9.43.4 | 9.42.2 |
| **task-management-plugin** | 9.43.3 | 9.43.2 | 9.42.4 | 9.41.1 |
| **data-search** | 9.32.3 | 9.32.2 | 9.31.4 | 9.30.1 |
| **audit-core** | 9.40.3 | 9.40.2 | 9.39.4 | 9.38.1 |
| **advancing-controller** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **integration-designer** | 9.59.4 | 9.59.3 | 9.58.5 | 9.57.1 |
| **application-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **runtime-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **data-sync** | 9.33.4 | 9.33.2 | 9.32.3 | 9.31.1 |
| **authorization-system** | 9.43.5 | 9.43.2 | 9.42.4 | 9.41.1 |
| **nosql-db-runner** | 9.31.3 | 9.31.2 | 9.30.4 | 9.29.1 |

### Renderers

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **iOS renderer** | 9.0.25 | 9.0.20 | 9.0.19 | 9.0.12 |
| **Android renderer** | 9.0.31 | 9.0.24 | 9.0.19 | 9.0.13 |

### Plugins

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.7 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.10 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** starting with 5.1.10 the default Redis read mode is `polling` (`EVENTS_REDIS_MODE`). This is applied automatically on upgrade; no action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.9 processes and configurations

### What's included in 5.1.10

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.10 Release Notes](./v5.1.10-june-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.10 | Keycloak | 26+ |
| 5.1.10 | Kafka | 3.8 - 3.9 |
| 5.1.10 | PostgreSQL | 16 - 17 |
| 5.1.10 | Oracle Database | 21c, 23ai |
| 5.1.10 | MongoDB | 7 - 8 |
| 5.1.10 | Redis | 7.4 - 8.0 |
| 5.1.10 | Elasticsearch | 8 - 9 |
| 5.1.10 | Angular (Web SDK) | 19.2 |
| 5.1.10 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.11 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.10 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.10 → 5.1.11**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **process-engine** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **admin** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **designer** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **cms-core** | 9.47.3 | 9.46.3 | 9.46.2 | 9.45.4 |
| **scheduler-core** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **events-gateway** | 9.37.3 | 9.36.4 | 9.36.2 | 9.35.4 |
| **notification-plugin** | 9.40.3 | 9.39.3 | 9.39.2 | 9.38.4 |
| **document-plugin** | 9.45.3 | 9.44.3 | 9.44.2 | 9.43.4 |
| **task-management-plugin** | 9.44.4 | 9.43.3 | 9.43.2 | 9.42.4 |
| **data-search** | 9.33.3 | 9.32.3 | 9.32.2 | 9.31.4 |
| **audit-core** | 9.41.3 | 9.40.3 | 9.40.2 | 9.39.4 |
| **advancing-controller** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **integration-designer** | 9.60.3 | 9.59.4 | 9.59.3 | 9.58.5 |
| **application-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **runtime-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **data-sync** | 9.34.2 | 9.33.4 | 9.33.2 | 9.32.3 |
| **authorization-system** | 9.44.4 | 9.43.5 | 9.43.2 | 9.42.4 |
| **nosql-db-runner** | 9.32.3 | 9.31.3 | 9.31.2 | 9.30.4 |

### Renderers

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **iOS renderer** | 9.0.27 | 9.0.25 | 9.0.20 | 9.0.19 |
| **Android renderer** | 9.0.37 | 9.0.31 | 9.0.24 | 9.0.19 |

### Plugins

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.7 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.11 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.10 processes and configurations

### What's included in 5.1.11

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.11 Release Notes](./v5.1.11-july-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.11 | Keycloak | 26+ |
| 5.1.11 | Kafka | 3.8, 3.9 |
| 5.1.11 | PostgreSQL | 16, 17 |
| 5.1.11 | Oracle Database | 21c, 23ai |
| 5.1.11 | MongoDB | 7, 8 |
| 5.1.11 | Redis | 7, 8 |
| 5.1.11 | Elasticsearch | 8 |
| 5.1.11 | Angular (Web SDK) | 19.2 |
| 5.1.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.12

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.12 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.11 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.11 → 5.1.12**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **process-engine** | 9.76.7 | 9.76.3 | 9.75.7 | 9.75.3 |
| **admin** | 9.76.6 | 9.76.3 | 9.75.7 | 9.75.3 |
| **designer** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **cms-core** | 9.47.5 | 9.47.3 | 9.46.3 | 9.46.2 |
| **scheduler-core** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **events-gateway** | 9.37.4 | 9.37.3 | 9.36.4 | 9.36.2 |
| **notification-plugin** | 9.40.4 | 9.40.3 | 9.39.3 | 9.39.2 |
| **document-plugin** | 9.45.4 | 9.45.3 | 9.44.3 | 9.44.2 |
| **task-management-plugin** | 9.44.6 | 9.44.4 | 9.43.3 | 9.43.2 |
| **data-search** | 9.33.4 | 9.33.3 | 9.32.3 | 9.32.2 |
| **audit-core** | 9.41.4 | 9.41.3 | 9.40.3 | 9.40.2 |
| **advancing-controller** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **integration-designer** | 9.60.5 | 9.60.3 | 9.59.4 | 9.59.3 |
| **application-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **runtime-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **data-sync** | 9.34.3 | 9.34.2 | 9.33.4 | 9.33.2 |
| **authorization-system** | 9.44.5 | 9.44.4 | 9.43.5 | 9.43.2 |
| **nosql-db-runner** | 9.32.4 | 9.32.3 | 9.31.3 | 9.31.2 |

### Renderers

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **iOS renderer** | 9.0.29 | 9.0.27 | 9.0.25 | 9.0.20 |
| **Android renderer** | 9.0.39 | 9.0.37 | 9.0.31 | 9.0.24 |

### Plugins

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.7 | 0.2.6 |

### AI Platform

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.12 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.11 processes and configurations

### What's included in 5.1.12

This maintenance release includes:

* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.12 Release Notes](./v5.1.12-august-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.12 | Keycloak | 26+ |
| 5.1.12 | Kafka | 3.8, 3.9 |
| 5.1.12 | PostgreSQL | 16, 17 |
| 5.1.12 | Oracle Database | 21c, 23ai |
| 5.1.12 | MongoDB | 7, 8 |
| 5.1.12 | Redis | 7, 8 |
| 5.1.12 | Elasticsearch | 8 |
| 5.1.12 | Angular (Web SDK) | 19.2 |
| 5.1.12 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.13
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.13

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.13 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.12 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.12 → 5.1.13**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **process-engine** | 9.76.10 | 9.76.7 | 9.76.3 | 9.75.7 |
| **admin** | 9.76.8 | 9.76.6 | 9.76.3 | 9.75.7 |
| **designer** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **cms-core** | 9.47.6 | 9.47.5 | 9.47.3 | 9.46.3 |
| **scheduler-core** | 9.36.5 | 9.36.4 | 9.36.3 | 9.35.3 |
| **events-gateway** | 9.37.5 | 9.37.4 | 9.37.3 | 9.36.4 |
| **notification-plugin** | 9.40.5 | 9.40.4 | 9.40.3 | 9.39.3 |
| **document-plugin** | 9.45.5 | 9.45.4 | 9.45.3 | 9.44.3 |
| **task-management-plugin** | 9.44.7 | 9.44.6 | 9.44.4 | 9.43.3 |
| **data-search** | 9.33.5 | 9.33.4 | 9.33.3 | 9.32.3 |
| **audit-core** | 9.41.5 | 9.41.4 | 9.41.3 | 9.40.3 |
| **advancing-controller** | 9.36.6 | 9.36.4 | 9.36.3 | 9.35.3 |
| **integration-designer** | 9.60.7 | 9.60.5 | 9.60.3 | 9.59.4 |
| **application-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **runtime-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **data-sync** | 9.34.4 | 9.34.3 | 9.34.2 | 9.33.4 |
| **authorization-system** | 9.44.6 | 9.44.5 | 9.44.4 | 9.43.5 |
| **nosql-db-runner** | 9.32.5 | 9.32.4 | 9.32.3 | 9.31.3 |

### Renderers

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **iOS renderer** | 9.0.32 | 9.0.29 | 9.0.27 | 9.0.25 |
| **Android renderer** | 9.0.44 | 9.0.39 | 9.0.37 | 9.0.31 |

### Plugins

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.7 |

### AI Platform

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.13 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.12 processes and configurations

### What's included in 5.1.13

This maintenance release includes:

* **Reliability fixes** for process advancing under load
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.13 Release Notes](./v5.1.13-september-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.13 | Keycloak | 26+ |
| 5.1.13 | Kafka | 3.8, 3.9 |
| 5.1.13 | PostgreSQL | 16, 17 |
| 5.1.13 | Oracle Database | 21c, 23ai |
| 5.1.13 | MongoDB | 7, 8 |
| 5.1.13 | Redis | 7, 8 |
| 5.1.13 | Elasticsearch | 8 |
| 5.1.13 | Angular (Web SDK) | 19.2 |
| 5.1.13 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.14
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.14

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.14 is the final planned maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.13 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.13 → 5.1.14**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **process-engine** | 9.76.12 | 9.76.10 | 9.76.7 | 9.76.3 |
| **admin** | 9.76.10 | 9.76.8 | 9.76.6 | 9.76.3 |
| **designer** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **cms-core** | 9.47.8 | 9.47.6 | 9.47.5 | 9.47.3 |
| **scheduler-core** | 9.36.7 | 9.36.5 | 9.36.4 | 9.36.3 |
| **events-gateway** | 9.37.7 | 9.37.5 | 9.37.4 | 9.37.3 |
| **notification-plugin** | 9.40.7 | 9.40.5 | 9.40.4 | 9.40.3 |
| **document-plugin** | 9.45.7 | 9.45.5 | 9.45.4 | 9.45.3 |
| **task-management-plugin** | 9.44.9 | 9.44.7 | 9.44.6 | 9.44.4 |
| **data-search** | 9.33.7 | 9.33.5 | 9.33.4 | 9.33.3 |
| **audit-core** | 9.41.8 | 9.41.5 | 9.41.4 | 9.41.3 |
| **advancing-controller** | 9.36.8 | 9.36.6 | 9.36.4 | 9.36.3 |
| **integration-designer** | 9.60.9 | 9.60.7 | 9.60.5 | 9.60.3 |
| **application-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **runtime-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **data-sync** | 9.34.6 | 9.34.4 | 9.34.3 | 9.34.2 |
| **authorization-system** | 9.44.8 | 9.44.6 | 9.44.5 | 9.44.4 |
| **nosql-db-runner** | 9.32.7 | 9.32.5 | 9.32.4 | 9.32.3 |

### Renderers

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **iOS renderer** | 9.0.38 | 9.0.32 | 9.0.29 | 9.0.27 |
| **Android renderer** | 9.0.48 | 9.0.44 | 9.0.39 | 9.0.37 |

### Plugins

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.8 |

### AI Platform

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Version | Description |
| - | - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | 1.52.0 | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | 1.25.1 | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | 25.0.0-preview6 | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.14 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release. The audit index retention settings below are optional.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted | audit-core |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only | audit-core |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch).

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.13 processes and configurations

### What's included in 5.1.14

This maintenance release includes:

* **Android renderer fix** for the action loader on modal screens
* **Optional audit index retention** and shard-size rollover settings
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.14 Release Notes](./v5.1.14-october-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.14 | Keycloak | 26+ |
| 5.1.14 | Kafka | 3.8, 3.9 |
| 5.1.14 | PostgreSQL | 16, 17 |
| 5.1.14 | Oracle Database | 21c, 23ai |
| 5.1.14 | MongoDB | 7, 8 |
| 5.1.14 | Redis | 7, 8 |
| 5.1.14 | Elasticsearch | 8 |
| 5.1.14 | Angular (Web SDK) | 19.2 |
| 5.1.14 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.4 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.3 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.3 → 5.1.4**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **process-engine** | **9.72.2** | 9.70.1 | 9.67.0 | 9.64.3 |
| **admin** | **9.72.0** | 9.70.2 | 9.68.1 | 9.66.5 |
| **designer** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **cms-core** | **9.43.1** | 9.41.1 | 9.39.0 | 9.36.3 |
| **scheduler-core** | **9.32.0** | 9.30.1 | 9.28.1 | 9.26.1 |
| **events-gateway** | **9.33.0** | 9.31.2 | 9.29.0 | 9.26.1 |
| **notification-plugin** | **9.36.0** | 9.34.1 | 9.32.0 | 9.29.1 |
| **document-plugin** | **9.41.1** | 9.39.1 | 9.37.1 | 9.35.1 |
| **task-management-plugin** | **9.40.0** | 9.38.2 | 9.36.1 | 9.34.2 |
| **data-search** | **9.29.0** | 9.27.1 | 9.25.1 | 9.23.1 |
| **audit-core** | **9.37.0** | 9.35.1 | 9.33.0 | 9.30.1 |
| **advancing-controller** | **9.32.0** | 9.30.2 | 9.28.0 | 9.25.1 |
| **integration-designer** | **9.56.0** | 9.54.1 | 9.52.1 | 9.50.0 |
| **application-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **runtime-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **data-sync** | **9.30.1** | 9.28.1 | 9.26.0 | 9.22.1 |
| **authorization-system** | **9.40.1** | 9.38.1 | 9.36.1 | 9.34.2 |
| **nosql-db-runner** | **9.28.0** | 9.26.1 | 9.24.1 | 9.22.1 |

### Renderers

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **iOS renderer** | **9.0.9** | 9.0.8 | 9.0.7 | 9.0.5 |
| **Android renderer** | **9.0.7** | 9.0.6 | 9.0.5 | 9.0.3 |

### Plugins

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.8** | 9.2.7 | 9.2.6 | 9.2.5 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.4 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.3 processes and configurations

#### New environment variables (optional)

The following optional environment variables have been added for the **process-engine** to configure config params caching:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120` | process-engine |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache | `500` | process-engine |

> [!NOTE]
>
> These variables are optional. If not configured, the default values will be used. Adjust these values based on how frequently your configuration changes and your memory constraints.
>
> For more details, see [Engine Setup - Config params cache](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).

### What's included in 5.1.4

This maintenance release includes:

* **Security patches** addressing identified vulnerabilities
* **Bug fixes** addressing customer-reported issues
* **Platform improvements** including cache improvements, Kafka environment variable alignment, SSE metrics enhancements, and infrastructure updates

For detailed information on all changes, see the [FlowX.AI 5.1.4 Release Notes](./v5.1.4-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.4 | Keycloak | 26+ |
| 5.1.4 | Kafka | 3.8 - 3.9 |
| 5.1.4 | PostgreSQL | 16 - 17 |
| 5.1.4 | Oracle Database | 21c, 23ai |
| 5.1.4 | MongoDB | 7 - 8 |
| 5.1.4 | Redis | 7.4 - 8.0 |
| 5.1.4 | Elasticsearch | 8 |
| 5.1.4 | Angular (Web SDK) | 19.2 |
| 5.1.4 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.5 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.4 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.4 → 5.1.5**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **process-engine** | **9.72.5** | 9.72.2 | 9.70.1 | 9.67.0 |
| **admin** | **9.72.2** | 9.72.0 | 9.70.2 | 9.68.1 |
| **designer** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **cms-core** | **9.43.3** | 9.43.1 | 9.41.1 | 9.39.0 |
| **scheduler-core** | **9.32.2** | 9.32.0 | 9.30.1 | 9.28.1 |
| **events-gateway** | **9.33.2** | 9.33.0 | 9.31.2 | 9.29.0 |
| **notification-plugin** | **9.36.2** | 9.36.0 | 9.34.1 | 9.32.0 |
| **document-plugin** | **9.41.3** | 9.41.1 | 9.39.1 | 9.37.1 |
| **task-management-plugin** | **9.40.2** | 9.40.0 | 9.38.2 | 9.36.1 |
| **data-search** | **9.29.2** | 9.29.0 | 9.27.1 | 9.25.1 |
| **audit-core** | **9.37.2** | 9.37.0 | 9.35.1 | 9.33.0 |
| **advancing-controller** | **9.32.1** | 9.32.0 | 9.30.2 | 9.28.0 |
| **integration-designer** | **9.56.2** | 9.56.0 | 9.54.1 | 9.52.1 |
| **application-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **runtime-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **data-sync** | **9.30.2** | 9.30.1 | 9.28.1 | 9.26.0 |
| **authorization-system** | **9.40.2** | 9.40.1 | 9.38.1 | 9.36.1 |
| **nosql-db-runner** | **9.28.2** | 9.28.0 | 9.26.1 | 9.24.1 |

### Renderers

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **iOS renderer** | **9.0.10** | 9.0.9 | 9.0.8 | 9.0.7 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.6 | 9.0.5 |

### Plugins

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.9** | 9.2.8 | 9.2.7 | 9.2.6 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.5 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No new environment variables
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.4 processes and configurations

### What's included in 5.1.5

This maintenance release includes:

* **Bug fixes** for process loop rendering issues in the Angular renderer
* **Bug fixes** for subprocess output data not being returned from embedded processes

For detailed information on all changes, see the [FlowX.AI 5.1.5 Release Notes](./v5.1.5-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.5 | Keycloak | 26+ |
| 5.1.5 | Kafka | 3.8 - 3.9 |
| 5.1.5 | PostgreSQL | 16 - 17 |
| 5.1.5 | Oracle Database | 21c, 23ai |
| 5.1.5 | MongoDB | 7 - 8 |
| 5.1.5 | Redis | 7.4 - 8.0 |
| 5.1.5 | Elasticsearch | 8 |
| 5.1.5 | Angular (Web SDK) | 19.2 |
| 5.1.5 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.6 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.5 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.5 → 5.1.6**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **process-engine** | **9.72.7** | 9.72.5 | 9.72.2 | 9.70.1 |
| **admin** | **9.72.4** | 9.72.2 | 9.72.0 | 9.70.2 |
| **designer** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **cms-core** | **9.43.5** | 9.43.3 | 9.43.1 | 9.41.1 |
| **scheduler-core** | **9.32.4** | 9.32.2 | 9.32.0 | 9.30.1 |
| **events-gateway** | **9.33.4** | 9.33.2 | 9.33.0 | 9.31.2 |
| **notification-plugin** | **9.36.4** | 9.36.2 | 9.36.0 | 9.34.1 |
| **document-plugin** | **9.41.5** | 9.41.3 | 9.41.1 | 9.39.1 |
| **task-management-plugin** | **9.40.4** | 9.40.2 | 9.40.0 | 9.38.2 |
| **data-search** | **9.29.4** | 9.29.2 | 9.29.0 | 9.27.1 |
| **audit-core** | **9.37.4** | 9.37.2 | 9.37.0 | 9.35.1 |
| **advancing-controller** | **9.32.3** | 9.32.1 | 9.32.0 | 9.30.2 |
| **integration-designer** | **9.56.3** | 9.56.2 | 9.56.0 | 9.54.1 |
| **application-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **runtime-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **data-sync** | **9.30.4** | 9.30.2 | 9.30.1 | 9.28.1 |
| **authorization-system** | **9.40.3** | 9.40.2 | 9.40.1 | 9.38.1 |
| **nosql-db-runner** | **9.28.4** | 9.28.2 | 9.28.0 | 9.26.1 |

### Renderers

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **iOS renderer** | **9.0.11** | 9.0.10 | 9.0.9 | 9.0.8 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.7 | 9.0.6 |

### Plugins

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.8 | 9.2.7 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.6 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> This release introduces optional environment variables for the process engine retry mechanism. These are not required — defaults work for most deployments.

#### Process engine — retry configuration (optional)

The following optional environment variables configure the exponential backoff with Equal Jitter strategy used for optimistic locking retries:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` | process-engine |

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.5 processes and configurations

### What's included in 5.1.6

This maintenance release includes:

* **Bug fixes** for React renderer: modals, sliders, datepicker, selectors, disabled state, and accessibility
* **Bug fixes** for Angular + React renderer: card accordion height, focus outlines, button icon layout
* **Bug fix** for process engine advancing getting stuck on pod crash
* **Bug fix** for connection leak in application-manager export/import
* **Improvement** for configurable retry mechanism with exponential backoff
* **Security patches** across all platform components

For detailed information on all changes, see the [FlowX.AI 5.1.6 Release Notes](./v5.1.6-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.6 | Keycloak | 26+ |
| 5.1.6 | Kafka | 3.8 - 3.9 |
| 5.1.6 | PostgreSQL | 16 - 17 |
| 5.1.6 | Oracle Database | 21c, 23ai |
| 5.1.6 | MongoDB | 7 - 8 |
| 5.1.6 | Redis | 7.4 - 8.0 |
| 5.1.6 | Elasticsearch | 8 |
| 5.1.6 | Angular (Web SDK) | 19.2 |
| 5.1.6 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.7
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.7 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.6 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.6 → 5.1.7**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **process-engine** | **9.73.1** | 9.72.7 | 9.72.5 | 9.72.2 |
| **admin** | **9.73.1** | 9.72.4 | 9.72.2 | 9.72.0 |
| **designer** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **cms-core** | **9.44.2** | 9.43.5 | 9.43.3 | 9.43.1 |
| **scheduler-core** | **9.33.1** | 9.32.4 | 9.32.2 | 9.32.0 |
| **events-gateway** | **9.34.1** | 9.33.4 | 9.33.2 | 9.33.0 |
| **notification-plugin** | **9.37.1** | 9.36.4 | 9.36.2 | 9.36.0 |
| **document-plugin** | **9.42.2** | 9.41.5 | 9.41.3 | 9.41.1 |
| **task-management-plugin** | **9.41.1** | 9.40.4 | 9.40.2 | 9.40.0 |
| **data-search** | **9.30.1** | 9.29.4 | 9.29.2 | 9.29.0 |
| **audit-core** | **9.38.1** | 9.37.4 | 9.37.2 | 9.37.0 |
| **advancing-controller** | **9.33.1** | 9.32.3 | 9.32.1 | 9.32.0 |
| **integration-designer** | **9.57.1** | 9.56.3 | 9.56.2 | 9.56.0 |
| **application-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **runtime-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **data-sync** | **9.31.1** | 9.30.4 | 9.30.2 | 9.30.1 |
| **authorization-system** | **9.41.1** | 9.40.3 | 9.40.2 | 9.40.1 |
| **nosql-db-runner** | **9.29.1** | 9.28.4 | 9.28.2 | 9.28.0 |

### Renderers

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **iOS renderer** | **9.0.12** | 9.0.11 | 9.0.10 | 9.0.9 |
| **Android renderer** | **9.0.13** | 9.0.7 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI Platform

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.8 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.7 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.6 processes and configurations

### What's included in 5.1.7

This maintenance release includes:

* **Bug fix** for build reimport failures with manifest issues
* **Security patches** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.7 Release Notes](./v5.1.7-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.7 | Keycloak | 26+ |
| 5.1.7 | Kafka | 3.8 - 3.9 |
| 5.1.7 | PostgreSQL | 16 - 17 |
| 5.1.7 | Oracle Database | 21c, 23ai |
| 5.1.7 | MongoDB | 7 - 8 |
| 5.1.7 | Redis | 7.4 - 8.0 |
| 5.1.7 | Elasticsearch | 8 |
| 5.1.7 | Angular (Web SDK) | 19.2 |
| 5.1.7 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.8
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.8 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.7 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.7 → 5.1.8**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **process-engine** | **9.74.4** | 9.73.1 | 9.72.7 | 9.72.5 |
| **admin** | **9.74.4** | 9.73.1 | 9.72.4 | 9.72.2 |
| **designer** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **cms-core** | **9.45.4** | 9.44.2 | 9.43.5 | 9.43.3 |
| **scheduler-core** | **9.34.4** | 9.33.1 | 9.32.4 | 9.32.2 |
| **events-gateway** | **9.35.4** | 9.34.1 | 9.33.4 | 9.33.2 |
| **notification-plugin** | **9.38.4** | 9.37.1 | 9.36.4 | 9.36.2 |
| **document-plugin** | **9.43.4** | 9.42.2 | 9.41.5 | 9.41.3 |
| **task-management-plugin** | **9.42.4** | 9.41.1 | 9.40.4 | 9.40.2 |
| **data-search** | **9.31.4** | 9.30.1 | 9.29.4 | 9.29.2 |
| **audit-core** | **9.39.4** | 9.38.1 | 9.37.4 | 9.37.2 |
| **advancing-controller** | **9.34.4** | 9.33.1 | 9.32.3 | 9.32.1 |
| **integration-designer** | **9.58.5** | 9.57.1 | 9.56.3 | 9.56.2 |
| **application-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **runtime-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **data-sync** | **9.32.3** | 9.31.1 | 9.30.4 | 9.30.2 |
| **authorization-system** | **9.42.4** | 9.41.1 | 9.40.3 | 9.40.2 |
| **nosql-db-runner** | **9.30.4** | 9.29.1 | 9.28.4 | 9.28.2 |

### Renderers

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **iOS renderer** | **9.0.19** | 9.0.12 | 9.0.11 | 9.0.10 |
| **Android renderer** | **9.0.19** | 9.0.13 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.8 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.7 processes and configurations

### What's included in 5.1.8

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.8 Release Notes](./v5.1.8-april-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.8 | Keycloak | 26+ |
| 5.1.8 | Kafka | 3.8 - 3.9 |
| 5.1.8 | PostgreSQL | 16 - 17 |
| 5.1.8 | Oracle Database | 21c, 23ai |
| 5.1.8 | MongoDB | 7 - 8 |
| 5.1.8 | Redis | 7.4 - 8.0 |
| 5.1.8 | Elasticsearch | 8 |
| 5.1.8 | Angular (Web SDK) | 19.2 |
| 5.1.8 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.9
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.9 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.8 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.8 → 5.1.9**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **process-engine** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.7 |
| **admin** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.4 |
| **designer** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **cms-core** | **9.46.2** | 9.45.4 | 9.44.2 | 9.43.5 |
| **scheduler-core** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.4 |
| **events-gateway** | **9.36.2** | 9.35.4 | 9.34.1 | 9.33.4 |
| **notification-plugin** | **9.39.2** | 9.38.4 | 9.37.1 | 9.36.4 |
| **document-plugin** | **9.44.2** | 9.43.4 | 9.42.2 | 9.41.5 |
| **task-management-plugin** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.4 |
| **data-search** | **9.32.2** | 9.31.4 | 9.30.1 | 9.29.4 |
| **audit-core** | **9.40.2** | 9.39.4 | 9.38.1 | 9.37.4 |
| **advancing-controller** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.3 |
| **integration-designer** | **9.59.3** | 9.58.5 | 9.57.1 | 9.56.3 |
| **application-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **runtime-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **data-sync** | **9.33.2** | 9.32.3 | 9.31.1 | 9.30.4 |
| **authorization-system** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.3 |
| **nosql-db-runner** | **9.31.2** | 9.30.4 | 9.29.1 | 9.28.4 |

### Renderers

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **iOS renderer** | **9.0.20** | 9.0.19 | 9.0.12 | 9.0.11 |
| **Android renderer** | **9.0.24** | 9.0.19 | 9.0.13 | 9.0.7 |

### Plugins

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.9 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.8 processes and configurations

### What's included in 5.1.9

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.9 Release Notes](./v5.1.9-may-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.9 | Keycloak | 26+ |
| 5.1.9 | Kafka | 3.8 - 3.9 |
| 5.1.9 | PostgreSQL | 16 - 17 |
| 5.1.9 | Oracle Database | 21c, 23ai |
| 5.1.9 | MongoDB | 7 - 8 |
| 5.1.9 | Redis | 7.4 - 8.0 |
| 5.1.9 | Elasticsearch | 8 - 9 |
| 5.1.9 | Angular (Web SDK) | 19.2 |
| 5.1.9 | React (Web SDK) | 18.x |


# FlowX.AI 5.1.10 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.10-june-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.9 → 5.1.10** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.10 includes bug fixes and security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Active policy and iOS renderer fixes
> * Real-time event delivery stability improvement (Events Gateway)
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.9

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Reusable UI templates:** fixed several issues affecting reusable UI templates: actions remaining mapped after changing dependency versions, undo/redo leaving an action without a name or unable to save, data-slice and mapping requests returning 400 after a data-model key was renamed, duplicate entries returned for available templates, the "open in new tab" flag not being saved on UI action mappings, actions going missing when the same template is nested at multiple container levels, and conditional styling and validators being applied incorrectly when the same template is used more than once in a single user task.
> > > >
> > > > * **Active policy:** fixed an issue where the user list could appear empty on the override active-policy form.
> > > >
> > > > * **Project version merge:** fixed a 500 error that could occur when merging app versions.&#x20;
> > > >
> > > > * **Organization settings:** fixed the runtime users list failing to load.&#x20;
> > > >
> > > > - **Real-time event delivery:** improved Redis connection stability under sustained load. The Events Gateway now uses polling as the default mode for reading real-time events from Redis, preventing the gradual connection buildup that could previously require periodic Events Gateway restarts. The change applies automatically on upgrade; no configuration is required.
> > > > - **Renderer:** accordion card height and custom styles now follow the component's opened state, and gap spacing is applied correctly to collections.
> > > > - **Process instances:** fixed duplicate API calls and rendering errors when navigating between process instances.
> > > > - **iOS renderer:** broad VoiceOver and accessibility improvements across components (form fields, file preview, sliders, date picker, validation messages), and fixed form view-model lookup for forms nested in collections.
> > > > - **Android renderer:** component sizing now includes padding on text, link, markdown, and image components; fixed a TopAppBar crash in some configurations, tooltip icon overrides, slider step rounding, document preview caching, and resilience to process death.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.10 is fully compatible with 5.1.9. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.9 → 5.1.10 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.10](./deployment-guidelines-v5.1.10).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.11 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.11-july-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.10 → 5.1.11** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.11 includes bug fixes and security patches:
>
> * Audit log and task management fixes
> * Project creation error-handling fix
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.10

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Audit log:** filtering by user now returns results when a user's username differs from their email address.
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it.
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.11 is fully compatible with 5.1.10. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.10 → 5.1.11 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.11](./deployment-guidelines-v5.1.11).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.12 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.12-august-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.11 → 5.1.12** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.12 includes bug fixes for library resources and task management:
>
> * Library process resource overview fixes
> * Task management sort control fix
> * No breaking changes; fully compatible upgrade from 5.1.11

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes for library resource overview and task management
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.12 is fully compatible with 5.1.11. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.11 → 5.1.12 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.12](./deployment-guidelines-v5.1.12).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.13 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.13-september-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **security patches**. Upgrades from **5.1.12 → 5.1.13** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.13 includes reliability fixes for process advancing, a process designer fix, and security patches:
>
> * Process advancing fixes that prevent lost or stalled process advances under load
> * Action deletion fix for business rules that call reusable functions
> * Security patches and dependency upgrades across platform components
> * No breaking changes; fully compatible upgrade from 5.1.12

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and security patches across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Process advancing reliability fixes, a process designer fix, and security patches
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Process advancing:** the partition cleanup job no longer deletes advance events that are accepted while cleanup is running. Event insertion and cleanup now coordinate through database row locks, on both PostgreSQL and Oracle, so a process advance can no longer be lost to a concurrent cleanup.&#x20;
> > > > * **Process advancing:** advancing workers no longer pause for cooldown while work is still queued, and event completion is retried after a database deadlock instead of leaving an already-processed event marked as in progress.&#x20;
> > > > * **Process designer:** deleting an action no longer fails with a server error when one of its business rules calls a reusable function.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components. The Java runtime base images move to Eclipse Temurin 21.0.12 with a refreshed OS package layer.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.13 is fully compatible with 5.1.12. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.12 → 5.1.13 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.13](./deployment-guidelines-v5.1.13).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.14 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.14-october-2026

Final maintenance release for the FlowX.AI 5.1.x LTS line. Audit index retention settings, an Android SDK loader fix, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.1.x** line, focused on **bug fixes** and **security patches**. Upgrades from **5.1.13 → 5.1.14** are non-breaking and fully compatible. FlowX.AI 5.1.14 is the final planned maintenance release of the 5.1.x line. To keep receiving fixes, plan your move to the 5.9.x LTS line: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [card] Release Highlight
>
> **FlowX.AI 5.1.14** is a maintenance release for the 5.1.x LTS:
>
> * **Audit index retention:** optional settings to delete old audit data and roll audit indices over by shard size
> * **Key fixes:** the Android SDK loader shows on modal screens and no longer stays stuck after repeated taps
> * Security patches and dependency upgrades. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.1.14 is fully compatible with 5.1.13. No breaking changes, no database migrations, and no required configuration changes; standard deployment procedures apply.

**Upgrade path:** direct upgrade from 5.1.13.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x. Component versions are listed in the [5.1.14 deployment guidelines](./deployment-guidelines-v5.1.14).

***

## Full changelog

### New

* **Audit:** set how long audit data is kept, and roll audit indices over when a primary shard reaches a set size, with two new environment variables. Both are off by default, so the Audit service deletes nothing until you set a retention period. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch) and the [deployment guidelines](./deployment-guidelines-v5.1.14#new-environment-variables-audit-index-retention).&#x20;

### Fixed

* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.1.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.3-january-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.2 → 5.1.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.3 delivers security patches and significant performance improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.2

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.3 delivers comprehensive security, performance, and stability improvements across the platform.
>
> ♿ [**iOS Accessibility**](#improvements-and-enhancements) — VoiceOver accessibility support for iOS renderer\
> ✨ [**Improvements and enhancements**](#improvements-and-enhancements) — AI Platform improvements and enhancements for Data Model generation\
> ⚡ [**Performance Improvements**](#performance-improvements) — Performance improvements and optimizations across platform components and services\
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Improvements and enhancements**
>
> > [card] Improvements and enhancements
> >
> > > [tab] Renderers
> > >
> > > > [card] iOS Accessibility
> > > >
> > > > VoiceOver accessibility support for the iOS renderer. Accessibility properties configured in the UI Designer (labels, hints, traits, decorative flags) are now applied to iOS components including form elements, text, images, and links.
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation for Tables
> > > >
> > > > Generate Data Model mappings for table components from AI Designer. AI automatically creates array of objects DM keys for tables with type validation and visual feedback.
> > >
> > > > [card] Data Model Generation for Table Columns
> > > >
> > > > Extended DM generation for text and link elements within table columns, with automatic attribute mapping and support for partial matching.
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.3 delivers significant performance improvements to the process engine
> > >
> > > > [card] Optimized Writes
> > > >
> > > > Smart change detection skips unnecessary database writes when param\_values unchanged
> > >
> > > > [card] Reduced DB Calls
> > > >
> > > > N+1 query fixes and batch loading significantly reduce database round trips
> > >
> > > > [card] Request Caching
> > > >
> > > > Request-scoped caching for frequently accessed runtime configuration
> >
> > > [tab] Key optimizations
> > >
> > > > [accordion] ProcessInstance param\_values Optimization
> > > >
> > > > Optimized handling of large `param_values` to reduce network overhead and prevent optimistic locking conflicts:
> > > >
> > > > * **Change Detection**: Skip database writes when param\_values unchanged
> > > > * **Lightweight Queries**: Exclude param\_values from SELECT when not needed
> > >
> > > > [accordion] Runtime Improvements - Reduced DB Calls
> > > >
> > > > **Optimizations Implemented:**
> > > >
> > > > * Improved batch loading and caching to reduce redundant queries
> > > > * Streamlined process initiation
> > > > * Enhanced batching for database writes
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Task Manager View Not Updating
> > > >
> > > > **Problem:**\
> > > > When using a view with dataset config where assignee is set to blank, after assigning a task (or self-assigning), the view appeared unchanged. Similarly, when assignee is set to not blank and you unassign a task, the view did not update.
> > > >
> > > > **Resolution:**\
> > > > Fixed view refresh behavior after assign/unassign operations to properly reflect the updated task state and provide visual feedback to users.
> > >
> > > > [accordion] Forms in Collections - Backend Keys Calculation
> > > >
> > > > **Problem:**\
> > > > When saving data from outside a collection with forms to submit, the backend calculated keys for UUID entries in formsToSubmit. These keys were only partial (relative to the collection array) and could overwrite existing process values.
> > > >
> > > > **Resolution:**\
> > > > Added a flag on PATCH /actions requests to notify the backend to exclude backend keys calculation for forms in collections UUIDs from formsToSubmit.
> > >
> > > > [accordion] Variables Reset on Config Update
> > > >
> > > > **Problem:**\
> > > > Updating parameters in the config page caused existing parameters to be replaced with new ones, generating new flowxUuids. This caused variables in database nodes to no longer match, losing all references.
> > > >
> > > > **Resolution:**\
> > > > Fixed to always send id and flowxUuid for existing params when saving the operation, preserving variable references.
> > >
> > > > [accordion] Build Export Timeout
> > > >
> > > > **Problem:**\
> > > > When exporting builds with multiple resources, some resources remained in EXPORTING status, others got EXPORT\_TIMEOUT without the build export receiving the status, and others had EXPORTED status. This was caused by Kafka messages being processed before the MongoDB transaction was committed.
> > > >
> > > > **Resolution:**\
> > > > Fixed the export function to ensure proper sequencing of database transactions and Kafka messages during build export operations.
> >
> > > [tab] Designer fixes
> > >
> > > > [accordion] Table Row Deletable with Backspace in RUT
> > > >
> > > > **Problem:**\
> > > > In Reusable UI Templates, selecting a table row and pressing backspace would delete the row, even though table rows should not be deletable.
> > > >
> > > > **Resolution:**\
> > > > Fixed keyboard handling to prevent accidental table row deletion via backspace key.
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Android Upload Action Payload Missing
> > > >
> > > > **Problem:**\
> > > > Upload action payload data (except uploadFileTempFileId) was missing on execution in the Android renderer.
> > > >
> > > > **Resolution:**\
> > > > Fixed payload handling to include all required data in upload action execution.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Connector Topic Pattern
> > > >
> > > > Added dedicated KAFKA\_TOPIC\_CONNECTOR\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [tab] AI Platform
> > >
> > > > [card] Streaming Client Library
> > > >
> > > > Implemented client library for invoking the run AI node with streaming support for conversational API

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.3 is fully compatible with 5.1.2. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.2 → 5.1.3 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### New configuration options
>
> > [!NOTE]
> >
> > **Optional**: New environment variable available for process-engine
>
> | Variable | Description | Default |
> | - | - | - |
> | `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from other platform components | Falls back to `KAFKA_TOPIC_PATTERN` if not set |
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.3](./deployment-guidelines-v5.1.3).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.3 → 5.1.4** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.4 delivers security patches and stability improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.3

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.4 delivers comprehensive security, performance, and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components and stability improvements\
> ⚡ [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Form validators do not work inside collection prototypes
> > > >
> > > > **Summary:**
> > > >
> > > > Validators applied to forms within collection prototypes are not triggered as expected.
> > >
> > > > [accordion] Project editor could modify access permissions
> > > >
> > > > **Summary:**
> > > >
> > > > Project editors were incorrectly able to modify project access permissions and delete projects. This has been fixed: `project_editor` can no longer modify access management or delete projects/libraries. Only `project_owner` and `workspace_admin` can change project ownership, add/remove users and groups from projects/libraries, and delete projects/libraries.
> > >
> > > > [accordion] Subprocess UI still shown after subprocess is finished
> > > >
> > > > **Summary:**
> > > >
> > > > In processes with multiple subprocesses that have UI, the first subprocess UI remained visible after completion until the next user task details were received. The UI now correctly clears when a subprocess finishes.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Kafka environment variables alignment
> > > >
> > > > Kafka environment variables are now consistent across all services with backwards compatibility support for existing configurations.
> > >
> > > > [card] Config params cache improvements
> > > >
> > > > New environment variables for tuning config params cache: `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` and `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`. See [Engine Setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
> > >
> > > > [card] Project editor permissions update
> > > >
> > > > `project_editor` can no longer delete projects or modify access permissions. `projects_admin` permission now grants full project management capabilities. See [Roles Permissions Matrix](/5.1/setup-guides/access-management/roles-permissions-matrix).
> > >
> > > > [card] Advancing partition counter fix
> > > >
> > > > Fixed an issue where the advancing partition counter could go negative, causing event processing failures. Improves reliability in integration-designer and process-engine.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.4 is fully compatible with 5.1.3. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.3 → 5.1.4 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.4](./deployment-guidelines-v5.1.4).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.5-february-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.4 → 5.1.5** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.5 delivers bug fixes and stability improvements:
>
> * Fixes for process loop rendering issues in the Angular renderer
> * Fix for subprocess output data not being returned from embedded processes
> * No breaking changes — fully compatible upgrade from 5.1.4

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.5 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer and process engine fixes for process loop scenarios
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes
> > >
> > > Issues resolved in the Angular renderer:
> > >
> > > > [accordion] Validation shown without user interaction on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task for the second time, form validation errors were displayed immediately without any user interaction. Validation now correctly waits for user input before showing errors.
> > >
> > > > [accordion] Action executed continuously on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task that had a UI action configured on a form element, the action was executed continuously in a loop. Actions are now correctly triggered only on user interaction.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Subprocess not returning output from embedded process
> > > >
> > > > **Summary:**
> > > >
> > > > When a subprocess (call activity) was started from an embedded process, the output data was not passed back to the parent process instance after completion. Data mapping from subprocess to parent now works correctly in embedded process scenarios.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.5 is fully compatible with 5.1.4. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.4 → 5.1.5 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.5](./deployment-guidelines-v5.1.5).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026

Bug fixes, stability improvements, and platform enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.5 → 5.1.6** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.6 delivers bug fixes and stability improvements:
>
> * Multiple React and Angular renderer fixes for modals, sliders, buttons, and accessibility
> * Data mappers autocomplete fix for values not loading
> * Process engine fix for advancing getting stuck on pod crash with multiple partition events
> * Kafka health check fix for reporting UP despite consumer DNS failure
> * New health indicator for runtime MongoDB connection
> * Connection leak fix in application-manager export/import operations
> * Improved retry mechanism with configurable exponential backoff
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.5

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.6 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer, process engine, and application manager fixes
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Retry mechanism enhancements and security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes (React)
> > >
> > > Issues resolved in the React renderer:
> > >
> > > > [accordion] Clear icon present and clickable on disabled input/textarea
> > > >
> > > > **Summary:**
> > > >
> > > > When an input or textarea component was disabled, the clear icon was still visible and clickable. The clear icon is now hidden and non-interactive on disabled components.
> > >
> > > > [accordion] Options list not shown when selectors are inside modal
> > > >
> > > > **Summary:**
> > > >
> > > > When select or multiselect components were placed inside a modal, the options list was not displayed when opened. Selector dropdowns now render correctly within modal contexts.
> > >
> > > > [accordion] Datepicker calendar shown behind modal
> > > >
> > > > **Summary:**
> > > >
> > > > When a datepicker was placed inside a modal, the calendar popup appeared behind the modal overlay. The datepicker calendar now renders above the modal with correct z-index stacking.
> > >
> > > > [accordion] Slider min/max value not set when loading a screen
> > > >
> > > > **Summary:**
> > > >
> > > > When a slider shared a process data key with an input, or when slider min/max values depended on computed values from another slider, the min/max values were not set on load. Slider initialization now correctly applies min/max values and computed dependencies.
> > >
> > > > [accordion] Slider default value not set with multiple sliders on same page
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple sliders were present on the same page, some sliders did not receive their default values, especially when no explicit null value was set in the data store. Default value initialization now works correctly for all sliders on a page.
> > >
> > > > [accordion] Task management assignee clear icon clickable when disabled
> > > >
> > > > **Summary:**
> > > >
> > > > In the task management view, the assignee field's clear icon was visible and clickable even when the field was disabled (non-editable). The clear icon is now hidden when the assignee field cannot be edited.
> > >
> > > > [accordion] Input, select, datepicker, textarea, and table filters have incorrect inner outline
> > > >
> > > > **Summary:**
> > > >
> > > > Multiple form components displayed an incorrect inner outline styling. The outline now only appears during keyboard navigation, following proper accessibility patterns.
> > >
> > > > [accordion] Data mappers autocomplete values not loading
> > > >
> > > > **Summary:**
> > > >
> > > > Data mapper autocomplete suggestions were not loading values in certain configurations. Autocomplete now correctly fetches and displays available values.
> >
> > > [tab] Renderer fixes (Angular + React)
> > >
> > > Issues resolved in both Angular and React renderers:
> > >
> > > > [accordion] Card height does not update when accordion is collapsed
> > > >
> > > > **Summary:**
> > > >
> > > > When a card component with fixed height contained an accordion, the card height did not update when the accordion was collapsed. Card height now correctly recalculates when accordion state changes.
> > >
> > > > [accordion] Focus outline appears when interacting with card/file preview accordion
> > > >
> > > > **Summary:**
> > > >
> > > > When interacting with a card or file preview component that included an accordion, an unwanted focus outline appeared. The focus outline is now only displayed during keyboard navigation.
> > >
> > > > [accordion] Button icon not correctly rendered
> > > >
> > > > **Summary:**
> > > >
> > > > When a button was configured with a right-aligned icon, fill width, and right-aligned typography, the icon was not aligned with the text, the gap was missing, and text and icon were center-aligned instead of right-aligned. Button icon layout now respects all configured alignment and spacing settings.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Advancing gets stuck when multiple events are available for one partition and pod crashes
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple events were available for the same partition and a pod crashed, only the first event was picked up and the rest remained stuck. Event processing now correctly handles all pending events after a pod recovery.
> > >
> > > > [accordion] Kafka health check reported UP despite consumer DNS failure
> > > >
> > > > **Summary:**
> > > >
> > > > The Kafka health check indicator could report UP even when consumers had DNS resolution failures, masking connectivity issues. Health indicators now correctly reflect the actual state of Kafka consumer connections.
> > >
> > > > [accordion] Health indicator for runtime MongoDB connection
> > > >
> > > > **Summary:**
> > > >
> > > > A new health indicator has been added to monitor the runtime MongoDB connection. This improves observability and allows operators to detect MongoDB connectivity issues through the standard health endpoint.
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Theme not imported during build import
> > > >
> > > > **Summary:**
> > > >
> > > > When importing a build that included theme resources, the theme was not correctly imported. Build import now includes theme resources as expected.
> > >
> > > > [accordion] Connection leak in export/import services
> > > >
> > > > **Summary:**
> > > >
> > > > During import/export operations, database connections were held for the entire duration of long-running operations (MinIO file transfers, REST calls, Kafka messaging), which could exhaust the connection pool. Transaction boundaries have been refined so that database connections are only held during actual database operations.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Process engine
> > >
> > > > [accordion] Configurable retry mechanism with exponential backoff
> > > >
> > > > **Summary:**
> > > >
> > > > The retry mechanism for optimistic locking in the process engine now uses an Equal Jitter strategy and supports runtime configuration via environment variables. Previously, the jitter was nullified by the max delay cap, causing retrying threads to collide at the same millisecond.
> > > >
> > > > New environment variables for the `process-engine`:
> > > >
> > > > | Environment Variable | Description | Default Value |
> > > > | - | - | - |
> > > > | `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` |
> > > > | `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` |
> > > > | `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` |
> > > >
> > > > > [!TIP]
> > > > >
> > > > > Default settings give a total retry window of \~1.2 seconds, which covers most transient optimistic lock conflicts. Increase `FLOWX_RETRY_MAX_RETRIES` or `FLOWX_RETRY_MAX_DELAY_MS` if you see retry exhaustion under high contention.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Removed deprecated access rights endpoint
> > > >
> > > > **Summary:**
> > > >
> > > > A deprecated endpoint and its associated test for access rights have been removed from the codebase as they are no longer needed.
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across all platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.6 is fully compatible with 5.1.5. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.5 → 5.1.6 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.6](./deployment-guidelines-v5.1.6).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.7 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.7-march-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.6 → 5.1.7** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.7 delivers bug fixes and stability improvements:
>
> * Fix for build import issues with manifest (reimport failures)
> * Security patches
> * No breaking changes, fully compatible upgrade from 5.1.6

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.7 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Build import fix
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Build reimport failures with manifest issues
> > > >
> > > > **Summary:**
> > > >
> > > > When reimporting a build, the import could fail due to manifest validation issues, either stopping mid-import or reporting that the build was already being imported. Build reimport now correctly handles manifest validation and prevents duplicate import conflicts.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.7 is fully compatible with 5.1.6. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.6 → 5.1.7 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.7](./deployment-guidelines-v5.1.7).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.8 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.8-april-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.7 → 5.1.8** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.8 delivers security patches and dependency upgrades:
>
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.7

***

**What's new? 🆕**

> [tab] Highlights
>
> Security patches and dependency upgrades across platform components.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.8 is fully compatible with 5.1.7. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.7 → 5.1.8 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.8](./deployment-guidelines-v5.1.8).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.9 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.9-may-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.8 → 5.1.9** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.9 delivers notable bug fixes alongside security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Android renderer fixes
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.8

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Advancing workers** — Improved connection management so advancing workers no longer accumulate database connections across cooldown and rampup cycles, preventing connection growth on long-running runtime deployments.
> > > > * **Reusable UI templates** — Fixed an issue where input and output mappings on reusable UI templates could be silently lost when a referenced library version was updated.
> > > > * **Designer** — Fixed server errors when bulk-editing UI templates and when patching UI actions inside reusable UI templates.
> > > > * **Android renderer** — Fixed sticky container behavior across nested hierarchy levels, and deferred the custom loader display until CMS resources are available.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.9 is fully compatible with 5.1.8. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.8 → 5.1.9 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.9](./deployment-guidelines-v5.1.9).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10

Component versions and deployment notes for FlowX.AI 5.10 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.10 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.10.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.10.0 |
| - | - |
| **admin** | 11.18.0 |
| **advancing-controller** | 11.12.0 |
| **application-manager** | 11.18.0 |
| **audit-core** | 11.11.0 |
| **authorization-system** | 11.14.0 |
| **cms-core** | 11.14.0 |
| **data-search** | 11.11.0 |
| **data-sync** | 11.9.0 |
| **designer** | 11.36.1 |
| **document-plugin** | 11.19.0 |
| **email-gateway** | 11.15.0 |
| **events-gateway** | 11.14.0 |
| **file-gateway** | 11.14.0 |
| **integration-designer** | 11.24.2 |
| **license** | 11.13.0 |
| **nosql-db-runner** | 11.14.0 |
| **notification-plugin** | 11.14.0 |
| **organization-manager** | 11.14.0 |
| **process-engine** | 11.19.3 |
| **runtime-manager** | 11.18.0 |
| **scheduler-core** | 11.11.0 |
| **task-management-plugin** | 11.15.0 |
| **webhook-gateway** | 11.13.0 |

### AI base components

| Component | 5.10.0 |
| - | - |
| **embedder** | 11.2.0 |
| **knowledgebase-indexer-v2** | 11.2.0 |
| **knowledgebase-rag** | 11.2.0 |
| **doc-parser** | 11.2.0 |

### AI dev-time components

| Component | 5.10.0 |
| - | - |
| **ai-gateway** | 11.15.1 |
| **ai-analyst** | 11.2.0 |
| **ai-assistant** | 11.2.0 |
| **ai-designer** | 11.2.0 |
| **ai-developer** | 11.2.0 |
| **kb-enrichment** | 11.2.0 |
| **planner** | 11.2.0 |

### AI runtime components

| Component | 5.10.0 |
| - | - |
| **agent-builder** | 11.2.0 |
| **data-privacy** | 11.2.0 |
| **doc-converter** | 11.2.0 |
| **dynamic-classifier** | 11.2.0 |
| **evals-judge** | 11.2.0 |
| **speech-to-text** | 11.2.0 |
| **web-crawler** | 11.2.0 |

### AI extensions

| Component | 5.10.0 |
| - | - |
| **modpod** | 11.2.0 |
| **observatory-api** | 11.0.2 |
| **observatory-platform** | 11.0.2 |
| **observatory-web** | 11.0.2 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments receive them, re-verified, with the next LTS release.

### New Kafka topics

| Topic | Producer → Consumer | Purpose |
| - | - | - |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin → process-engine | Resource cache eviction |
| `ai.flowx.config.params.events.v1` | application-manager → process-engine | Config-param change notifications |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine → integration-designer | Runtime-instance termination |
| `ai.flowx.evals.suggestions.job.request.v1` / `.response.v1` | integration-designer | Evals suggestions job requests and responses |

### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them when your environment moves to 5.10.

This release also adds a new AI Platform component, **dynamic-classifier** (listed under AI runtime components above), which backs document classification.

In `admin`, the single `FLOWX_FEATUREAVAILABILITY_AISERVICENAME` setting is replaced by two, reflecting the split between AI dev-time and AI runtime services: `FLOWX_FEATUREAVAILABILITY_AIDEVTIMESERVICENAME` (default `ai-gateway-mngt`) and `FLOWX_FEATUREAVAILABILITY_AIRUNTIMESERVICENAME` (default `agent-builder-mngt`).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.10.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026

What's new in FlowX.AI 5.10: PostgreSQL and SOAP data sources, AI Developer script-node code generation, file uploads in chat-driven apps, and AI and document-intelligence improvements.

[FlowX.AI 5.10 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.10.0.html)

> [!NOTE]
>
> **FlowX.AI 5.10 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments receive them with the next LTS release.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release adds PostgreSQL and SOAP data sources, multi-file upload in chat-driven apps, and a set of AI and document-intelligence capabilities, alongside broader audit coverage, roles that travel with copied resources, and workflow data-partitioning improvements.

***

**What's new?**

> [tab] Core & Platform
>
> 🗂️ [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions\
> 📑 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources\
> ⚡ [**Platform performance and fixes**](#platform-performance-and-fixes) - Task-manager user fetch, project versioning, export/merge

> [tab] Designer & Renderer
>
> 💬 [**Chat file upload**](#chat-file-upload) - Attach multiple files in conversational apps\
> ⬇️ [**File download component**](#file-download-component) - Download files from a rendered app (web and Android)\
> 🔀 [**Conditional event-handler triggers**](#conditional-event-handler-triggers) - Fire event handlers based on a condition\
> 🎨 [**Image color property**](#image-color-property) - Color control on the IMAGE component\
> 💾 [**Save local variable**](#save-local-variable-action) - Capture a collection row into local data on click\
> 🪟 [**Global header and footer**](#global-header-and-footer) - Consistent header and footer across a UI Flow\
> 🧩 [**Reusable UI templates**](#reusable-ui-templates) - Action mapping, undo/redo, and dependency-version fixes

> [tab] Integrations & Data
>
> 🐘 [**PostgreSQL data source**](#postgresql-data-source) - Connect workflows directly to PostgreSQL and run SQL queries\
> 🧼 [**SOAP integration**](#soap-integration) - Import a WSDL and call SOAP operations from workflows\
> 🧮 [**FlowX Database aggregation**](#flowx-database-aggregation) - MongoDB aggregation pipelines\
> 🗄️ [**Documents tab in database testing**](#documents-tab-in-database-testing) - Inspect data while testing DB operations

> [tab] AI & Documents
>
> 📊 [**Tabular data extraction node**](#tabular-data-extraction-node) - Read spreadsheets and CSV into workflow data\
> 🔁 [**Knowledge Base error handling**](#knowledge-base-error-handling-and-retry) - Retry failed KB ingestion\
> ✨ [**AI Developer: script-node code**](#ai-developer-generate-script-node-code) - Generate node code from a prompt\
> 🧪 [**AI evaluation experiments**](#ai-evaluation-experiments) - Multiple datasets and improvement suggestions\
> 🛡️ [**AI node output reliability**](#ai-node-output-reliability) - Schema validation with auto-repair and clearer run errors\
> 📝 [**Template Filling node**](#template-filling-node) - Generate documents from templates in workflows\
> 🗂️ [**File manipulation nodes**](#file-manipulation-nodes) - Combine and split files in workflows\
> 📄 [**DOCX document generation**](#docx-document-generation) - Generate documents as DOCX in addition to PDF\
> 🏷️ [**Document Tag**](#document-tag-renamed-from-document-type) - "Document Type" renamed\
> 🔑 [**Mistral model provider**](#mistral-model-provider) - Bring your own Mistral API key

### **Expanded audit logging**

> [card] Broader audit coverage for access and lifecycle actions
>
> Audit logging now records a wider set of actions: **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> All Deployments

### **Copy with roles**

> [card] Roles travel with copied resources
>
> Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> All Deployments

### **Platform performance and fixes**

> [card] Platform performance and fixes
>
> > [tab] Performance
> >
> > The task manager fetches users through the authorization-system instead of calling Keycloak directly, cutting per-request identity lookups.&#x20;
> >
> > MongoDB partition archiving scales for large datasets, with partition-ID backfill for legacy data and archiving fixes on PostgreSQL and Oracle.&#x20;
>
> > [tab] Bug fixes
> >
> > > [accordion] Core platform fixes
> > >
> > > * **Project selector:** projects without a work-in-progress branch are correctly shown as unavailable.&#x20;
> > > * **Start Solution:** no longer fails with "no entry point set" until the page is refreshed.&#x20;
> > > * **Export and merge:** fixed errors when exporting a project build with imported libraries and when merging project versions, including a 500 during merge.&#x20;
> > > * **Merge-conflict checks:** no longer fail on processes that contain conflicts.&#x20;
> > > * **Allocation roles:** candidate-user search works for users without runtime permissions on the asset.&#x20;
> > > * **Version switching:** the selected resource opens when changing app versions, and reusable-function code refreshes on version switch.&#x20;
> > > * **Process engine:** resolved an incident-save deadlock.&#x20;
> > > * **FlowX Database:** inserting a document with a reserved `_id` key is now rejected with a clear error instead of breaking later reads.&#x20;
>
> All Deployments

### **PostgreSQL data source**

> [card] Connect to PostgreSQL databases from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds **PostgreSQL** as a data source type, alongside Oracle. Connect a workflow directly to a PostgreSQL database and run SQL queries against it as a workflow node, without a custom REST wrapper. See the [PostgreSQL Database](/5.9/docs/platform-deep-dive/integrations/postgresql-database) documentation.
>
> > [tab] Key Features
> >
> > > [card] Direct connection
> > >
> > > Configure host, port, database, schema, and credentials, with an optional SSL connection and a **Test connection** check before saving.
> >
> > > [card] SQL query operations
> > >
> > > Define SQL query operations on the data source and call them from workflow nodes.
> >
> > > [card] Connection pool tuning
> > >
> > > Advanced settings cover pool size, connection and query timeouts, keep-alive, and a validation query.
> >
> > > [card] Familiar experience
> > >
> > > Shares the same configuration and operations experience as the existing Oracle data source.
>
> SaaS

### **SOAP integration**

> [card] Call SOAP web services from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds a **SOAP System** data source. Import the service's **WSDL** — from a URL or an uploaded file — and FlowX discovers the operations with their input, output, and fault schemas, composes the SOAP envelope at runtime, and lets you call each operation from workflows through a **SOAP Operation** node. See the [SOAP System](/5.9/docs/platform-deep-dive/integrations/soap-system) documentation.
>
> > [tab] Key Features
> >
> > > [card] WSDL import
> > >
> > > Preview and select the operations to import; re-import refreshes schemas while preserving your edits
> >
> > > [card] Typed variables
> > >
> > > Envelope variables extracted from the input XSD, referenced as workflow parameters
> >
> > > [card] SOAP 1.1 and 1.2
> > >
> > > Version derived from the WSDL, with standard headers set automatically
> >
> > > [card] Testing built in
> > >
> > > Test operations with value overrides, a curl preview, and full request/response envelopes in run logs
>
> SaaS

### **Reusable UI templates**

> [card] Reusable UI template fixes
>
> Reusable UI templates get more reliable action mapping, undo/redo, and dependency-version handling.
>
> All Deployments

### **Chat file upload**

> [card] Attach multiple files in conversational apps
>
> End users can attach multiple files at once in chat-driven apps, and conversational workflows can receive those files as input. Uploaded files are extracted and indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content. Configurable in the Designer and themable, with runtime support on the web renderer.
>
> Session knowledge bases are isolated per conversation and per tenant, and are excluded from app export.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **File download component**

> [card] Download files from a rendered app
>
> A new File Download component lets end users download files directly from a rendered app. Configured in the Designer, with runtime support on web and Android.
>
> For more information, see the [File download](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download) documentation.
> SaaS

### **Conditional event-handler triggers**

> [card] Fire event handlers based on a condition
>
> Event handlers can now fire conditionally, configured in the Designer and honored by the web and Android renderers.
>
> For more information, see the [event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers) documentation.
> SaaS

### **Image color property**

> [card] Color control on the IMAGE component
>
> The IMAGE component now honors a color property, configured in the Designer and rendered on web and Android.
>
> See the [Image component](/5.9/docs/building-blocks/ui-designer/ui-component-types/image) documentation.
> SaaS

### **Save local variable action**

> [card] Capture a collection row into local data
>
> Event handlers gain a **Save Local Variable** action type: on a component inside a collection, it saves the clicked row's item into local data under a configurable key, entirely client-side with no backend roundtrip — useful for capturing the selected row before a follow-up action fires. Not available inside Reusable UI Templates.
>
> See the [Save Local Variable](/5.9/docs/building-blocks/ui-designer/event-handlers#save-local-variable) documentation.
> SaaS

### **Global header and footer**

> [card] Consistent header and footer across a UI Flow
>
> UI Flows can now define a **global header and footer** that display consistently across every page of the flow. Each holds content components — containers, forms, buttons, links, custom components — with fixed or static positioning (header fixed by default), so you can build persistent navigation or action bars in one place instead of per page.
>
> See the [Global Header and Footer](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer) documentation.
> SaaS

### **Tabular data extraction node**

> [card] Extract spreadsheet and CSV data into workflows
>
> A new workflow node reads a spreadsheet or CSV file and returns its contents as structured JSON in the node's response key, so the data can drive conditions and data operations downstream. Each row is returned as an object keyed by the file's header row, and for Excel files you can select which sheet to read.
>
> For more information, see the [Tabular Data Extraction node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node) documentation.
> SaaS

### **Knowledge Base error handling and retry**

> [card] Recover from failed Knowledge Base ingestion
>
> When Knowledge Base ingestion fails, the Knowledge Base page now shows a clear failure status and reason, and a **Retry** button re-runs the last operation after cleaning up partial content so the store is not left inconsistent. The **Update Knowledge Base** workflow node gains a **FAIL** exit handle with per-operation rollback.
>
> Learn more about [Knowledge Bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview).
> SaaS

### **AI Developer: generate script-node code**

> [card] Generate script-node code with AI Developer
>
> In the workflow designer, a script node can call **AI Developer** to generate or refactor its code from a natural-language prompt. Output streams into the test area for a **Keep** or **Discard** review, with edits shown as a diff. Supports JavaScript and Python, and respects existing AI Developer permissions.
>
> Learn more about [AI Developer](/5.9/ai-platform/pre-built-agents/ai-developer).
> SaaS

### **FlowX Database aggregation**

> [card] Aggregation pipelines in FlowX Database
>
> The FlowX Database data source adds MongoDB **aggregation pipeline** support, so configurators can group, join, reshape, and compute across documents beyond what a single query allows.
>
> Learn more about the [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) data source.
> SaaS

### **AI evaluation experiments**

> [card] Richer AI evaluation experiments
>
> > [tab] Multiple datasets
> >
> > An evaluation experiment can run against **multiple datasets** at once (datasets sharing the same AI node), with overall metrics aggregated across them and a dataset column added to the report.
>
> > [tab] Improvement suggestions
> >
> > Experiment reports now show **AI-generated suggestions** for improving the node's prompt, grouped per LLM-as-judge evaluator, beneath the score cards.
>
> Learn more about [AI evaluations](/5.9/ai-platform/evaluations).
> SaaS

### **AI node output reliability**

> [card] Schema validation with auto-repair and clearer run errors
>
> > [tab] Validation and repair
> >
> > When an AI node has a **Response Schema**, the response is validated against it and automatically retried with a repair prompt on mismatch. Nodes that still fail return a **categorized error** instead of passing malformed output downstream, and the node's **Logs** show the failure reason, rejected output, the model's reasoning summary, and the retry count.
>
> > [tab] Schema placeholders
> >
> > Response schemas now support `${variable}` placeholders resolved at runtime against workflow data, with substituted values coerced to the schema-declared types — consistent with how other AI-node fields resolve placeholders.
>
> See [AI node types](/5.9/ai-platform/agent-builder/node-types#structured-output-validation-and-run-diagnostics) for details.
> SaaS

### **Template Filling node**

> [card] Generate documents from templates in workflows
>
> Integration workflows gain a **Template Filling** node, under **Tools** in the node palette, that generates a document from a document template populated with workflow data. Select a template and language, fill the template's variables from workflow data, and choose **PDF** or **DOCX** output. The generated file's ID and download path are returned on the node's response key.
>
> See the [Template Filling node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) documentation.
> SaaS

### **File manipulation nodes**

> [card] Combine and split files in workflows
>
> Integration workflows add two document nodes, under **Tools** in the node palette: **Combine Files** merges multiple PDFs into one in a given order, and **Split File** breaks a PDF into multiple files by page ranges or one file per page. Both bring document handling that was previously process-only into workflows.
>
> See the [Combine Files](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) documentation.
> SaaS

### **DOCX document generation**

> [card] Generate documents as DOCX
>
> Template-based document generation can now produce **DOCX** files in addition to PDF. Set `outputFormat` (`PDF` or `DOCX`; defaults to `PDF`) on the generation request, or pick the format from the new **Output format** dropdown when testing a template in the Designer. Generated DOCX files preserve the template's styles, data, and images. Barcodes apply to PDF output only.
>
> Learn more in the [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output) documentation.
> SaaS

### **Document Tag (renamed from Document Type)**

> [card] Document Type is now Document Tag
>
> The **Document Type** field is renamed **Document Tag** across the surfaces where a document is tagged for storage (Upload File action, Document-Plugin REST responses, AI Document Generation, and the Web Page Extractor). This is a label change; behavior is unchanged.
> SaaS

### **Documents tab in database testing**

> [card] Inspect data while testing database operations
>
> The Database Query testing modals gain a **Documents** tab, so you can inspect the database right after running an operation. Multi-record operations report an affected-record count.
> SaaS

### **Mistral model provider**

> [card] Bring your own Mistral API key
>
> **Mistral** joins the model provider catalog as a bring-your-own-key provider. Add it with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability: chat, image understanding, embeddings, and document OCR. The seeded catalog covers the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed model lines.
>
> Learn more about [AI providers](/5.9/ai-platform/ai-providers).
> SaaS

***

## Deployment guidelines

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.10 deployment guidelines](./deployment-guidelines-v5.10).&#x20;


# Deployment guidelines v5.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11

Component versions and deployment notes for FlowX.AI 5.11 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.11 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.11.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.11.0 |
| - | - |
| **admin** | 11.53.0 |
| **advancing-controller** | 11.31.0 |
| **application-manager** | 11.46.0 |
| **audit-core** | 11.30.0 |
| **authorization-system** | 11.38.0 |
| **cms-core** | 11.43.0 |
| **data-search** | 11.30.0 |
| **data-sync** | 11.27.0 |
| **designer** | 11.89.1 |
| **document-plugin** | 11.47.0 |
| **email-gateway** | 11.39.0 |
| **events-gateway** | 11.34.0 |
| **file-gateway** | 11.38.0 |
| **integration-designer** | 11.62.1 |
| **license** | 11.34.0 |
| **nosql-db-runner** | 11.35.0 |
| **notification-plugin** | 11.41.0 |
| **organization-manager** | 11.38.0 |
| **process-engine** | 11.53.1 |
| **runtime-manager** | 11.46.0 |
| **scheduler-core** | 11.30.0 |
| **task-management-plugin** | 11.42.0 |
| **webhook-gateway** | 11.37.0 |

### AI base components

| Component | 5.11.0 |
| - | - |
| **embedder** | 11.3.1 |
| **knowledgebase-indexer-v2** | 11.3.1 |
| **knowledgebase-rag** | 11.3.1 |
| **doc-parser** | 11.3.1 |

### AI dev-time components

| Component | 5.11.0 |
| - | - |
| **ai-gateway** | 11.39.0 |
| **ai-analyst** | 11.3.1 |
| **ai-assistant** | 11.3.1 |
| **ai-designer** | 11.3.1 |
| **ai-developer** | 11.3.1 |
| **kb-enrichment** | 11.3.1 |
| **planner** | 11.3.1 |

### AI runtime components

| Component | 5.11.0 |
| - | - |
| **agent-builder** | 11.3.1 |
| **ai-architect** | 11.3.1 |
| **data-privacy** | 11.3.1 |
| **doc-converter** | 11.3.1 |
| **dynamic-classifier** | 11.3.1 |
| **evals-judge** | 11.3.1 |
| **speech-to-text** | 11.3.1 |
| **web-crawler** | 11.3.1 |

### AI extensions

| Component | 5.11.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.89.1` for FlowX.AI 5.11.0). The native iOS and Android renderers version independently.

| Component | 5.11.0 |
| - | - |
| **@flowx/angular-sdk** | 11.89.1 |
| **@flowx/angular-theme** | 11.89.1 |
| **@flowx/angular-ui-toolkit** | 11.89.1 |
| **@flowx/react-sdk** | 11.89.1 |
| **@flowx/react-theme** | 11.89.1 |
| **@flowx/react-ui-toolkit** | 11.89.1 |
| **@flowx/react-native-sdk** | 11.89.1 |
| **@flowx/react-native-theme** | 11.89.1 |
| **@flowx/react-native-ui-toolkit** | 11.89.1 |
| **@flowx/core-sdk** | 11.89.1 |
| **@flowx/core-theme** | 11.89.1 |
| **react-saas** | 11.89.1 |
| **iOS renderer** | 11.1.0 |
| **Android renderer** | 11.7.1 |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.11 capabilities. On SaaS they are created and managed automatically.

**Structured template data model** (document and notification templates move to the structured data model):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.sync.out.v1` | document-plugin, notification-plugin → application-manager |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | document-plugin, notification-plugin → application-manager |

**Runtime content import/export** (Knowledge Base and database content):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → ai-platform |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | ai-platform → integration-designer |

**Document classification and ML extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | ai-platform → integration-designer |

### AI Platform packaging

FlowX.AI 5.11 consolidates the AI Platform services into a single **`ai-platform` umbrella chart** (version `11.3.1`). Services that were previously deployed as standalone releases, including `doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, and `evals-judge`, now ship as subcharts of that chart and continue to run under their plain service names. On SaaS this change is applied automatically. The [component versions](#component-versions) section lists each service at its effective `11.3.1` version.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.11.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026

What's new in FlowX.AI 5.11: workflow tools and agentic RAG on Custom Agents, per-Knowledge-Base embedding models, document classification, extended response caching, subworkflow data mapping, structured template data models, and chat and UI Flow renderer improvements.

[FlowX.AI 5.11 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.11.0.html)

> [!NOTE]
>
> **FlowX.AI 5.11 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.11** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release turns Custom Agents into orchestrators that call FlowX workflows as tools and search knowledge bases agentically, adds per-Knowledge-Base embedding models with local embedders for personal-information content, and introduces document classification. It also extends response caching and subworkflow data mapping in the Integration Designer, moves document and notification templates onto the structured data model, and adds chat notifications, session ownership, and richer runtime audit to the renderers.

### What changed since 5.10.0

| 5.10.0 | 5.11.0 |
| - | - |
| Custom Agents call MCP servers, built-in tools, web search, and Knowledge Bases | + **FlowX workflows as callable tools** on a Custom Agent, with per-tool usage hints and tool-calling caps |
| Knowledge Base retrieval is a plain vector search on the org default embedding model | + **Agentic knowledge base search** and **per-KB embedding models**, including keyless local embedders for personal-information content |
| REST caching covers GET; SQL operations are cacheable | + **POST** REST responses, **file-storage** reads, and **Mongo** reads are cacheable too |
| Subworkflow input/output is raw JSON | + **Input and output mappers** on the Subworkflow node, with per-mapping test and import/export |
| Document and notification templates use a free-form key/value Data model tab | + Templates use the **structured data model** with typed attributes, validators, and Input Parameters |

***

**What's new?**

> [tab] AI & Agents
>
> 🧰 [**Workflow tools on Custom Agents**](#workflow-tools-on-custom-agents) - Attach FlowX workflows as callable agent tools, with usage hints and tool-calling caps\
> 🔎 [**Agentic knowledge base search and Show Reasoning**](#agentic-knowledge-base-search-and-show-reasoning) - Query decomposition, relevance grading, and a reasoning summary in the run log\
> 🧠 [**Per-knowledge-base embedding models**](#per-knowledge-base-embedding-models) - Pick an embedding model per KB and keep personal-information content on a local embedder\
> 🗂️ [**Knowledge Base content lifecycle**](#knowledge-base-content-lifecycle) - Delete entries by metadata filter, structured failure handling, per-chunk timestamps\
> 🏷️ [**Document classification**](#document-classification) - Train or import a classifier and route document pages in a workflow\
> 💬 [**Conversational chat reply requirement**](#conversational-chat-reply-requirement) - A conversational run that never replies to chat now fails with a clear error\
> ✍️ [**Custom Agent instruction limit**](#custom-agent-instruction-limit) - The Instructions field is capped at 10,000 characters

> [tab] Integrations & Data
>
> 🔁 [**Reusable functions in Integration Designer**](#reusable-functions-in-integration-designer) - Call reusable functions from Script and Condition (Fork) nodes\
> ⚡ [**Extended response caching**](#extended-response-caching) - Cache POST REST, file-storage reads, and Mongo reads alongside GET and SQL\
> 🔗 [**Subworkflow data mapping**](#subworkflow-data-mapping) - Map data in and out of a subworkflow with input and output mappers\
> 📎 [**Email attachment filtering by extension**](#email-attachment-filtering-by-extension) - Filter attachments by individual file extension instead of broad categories

> [tab] Platform
>
> 🧱 [**Structured data model for templates**](#structured-data-model-for-templates) - Document and notification templates use typed attributes and Input Parameters\
> ✅ [**Data model attribute validators**](#data-model-attribute-validators) - Required, min/max, length, pattern, email, items, and currency rules on attributes\
> 🧾 [**UI Flow runtime audit**](#ui-flow-runtime-audit) - Audit workflow-instance runs, chat messages, conversation reads, and process renders\
> 📤 [**Cross-version export adaptation**](#cross-version-export-adaptation) - Exports adapt UI templates for older LTS targets by removing unsupported handlers\
> 🔐 [**Platform and runtime improvements**](#platform-and-runtime-improvements) - Runtime access-control hardening

> [tab] Renderers & UI Flows
>
> 🔔 [**Chat notifications and conversation search**](#chat-notifications-and-conversation-search) - Unread-message badge on the chat button and search across conversation history\
> 🚫 [**Disable chat input on a condition**](#disable-chat-input-on-a-condition) - A business condition can make the chat input read-only\
> 🧭 [**Navigate To form validation**](#navigate-to-form-validation) - Require form validation before a Navigate To action, on web, iOS, and Android\
> ⌛ [**Expired UI Flow sessions**](#expired-ui-flow-sessions) - Expired sessions show a session-expired screen with a start-fresh option\
> 👤 [**UI Flow session owner**](#ui-flow-session-owner) - Restrict a running session to a single user\
> 🏁 [**Process Renderer process-end handling**](#process-renderer-process-end-handling) - Run a configurable action when an embedded process ends\
> 🎛️ [**Renderer improvements**](#renderer-improvements) - Batched enumeration fetch and process-start loader alignment

### **Workflow tools on Custom Agents**

> [card] Attach FlowX workflows as callable tools on a Custom Agent
>
> > [tab] Overview
> >
> > **Before 5.11:** a Custom Agent's tools were MCP servers, built-in tools, web search, and Knowledge Base retrieval. **Now:** you can also attach FlowX workflows as callable tools.
> >
> > In the Custom Agent node's **Tools** section, add a workflow as a tool and fill the per-tool **When should the agent use this workflow?** hint that tells the agent when to call it. The agent calls the workflow like any other tool, passing arguments that match the workflow's Start-node input parameters. A workflow with no input parameters cannot be attached. Each tool call starts a fresh workflow run whose output returns to the agent, and the child run is linked in the console log.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Workflows as tools
> > >
> > > Attach up to ten workflows as tools on one Custom Agent, each with a usage hint the agent reads when deciding to call it.
> >
> > > [card] Typed arguments
> > >
> > > The agent passes arguments that match the workflow's Start-node input parameters; workflows without input parameters are not eligible.
> >
> > > [card] Tool-calling limits
> > >
> > > An agent is limited in how many tool calls it can make per run, and workflow-tool call chains are depth-limited so recursion cannot run away.
> >
> > > [card] Linked runs
> > >
> > > Each workflow tool call is a fresh run whose output returns to the agent and is linked in the console log.
>
> SaaS

### **Agentic knowledge base search and Show Reasoning**

> [card] Agentic knowledge base search and reasoning summaries
>
> > [tab] Overview
> >
> > The Custom Agent node gains **agentic knowledge base search** and a **Show Reasoning** toggle.
> >
> > With agentic search on, the agent breaks a question into sub-queries, retrieves and grades results for relevance, and retries with reworded queries if the first pass finds nothing. It is better on complex questions and uses more model calls; a single pass with three sub-queries is the default. Agentic search never returns worse results than plain retrieval. **Show Reasoning** captures the model's reasoning summary in the run and console log; the structured response and the chat reply shown to the user are unchanged.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Agentic search
> > >
> > > Turn on **Enable agentic knowledge base search**, then set **Max attempts** and **Subqueries per attempt** under Settings.
> >
> > > [card] Relevance grading
> > >
> > > Retrieved candidates are graded against the original question, with corrective retries until a relevant result is found or the attempt budget is spent.
> >
> > > [card] Show Reasoning
> > >
> > > Surface the model's reasoning in the run log without changing the answer returned to the user.
> >
> > > [card] Fail-open
> > >
> > > Agentic mode returns the same chunk metadata as plain retrieval, so citations and telemetry are unchanged.
>
> SaaS

### **Per-knowledge-base embedding models**

> [card] Per-KB embedding models and local embedders for personal information
>
> > [tab] Overview
> >
> > Knowledge Bases can now use a **per-KB embedding model**, and a KB that holds personal information can keep its content on a local embedder.
> >
> > Turn on **Containing Personal Information** on a Knowledge Base to enable a local embedding model, then pick one from the **Embedding model** list. Local embedders (for example a text-embedding-inference or Ollama endpoint, or any OpenAI-compatible endpoint) are configured as a single **CUSTOM** provider in the organization AI settings, with a free-form base URL and no API key. The embedding model is set before the first store and cannot be changed afterward. Non-personal-information Knowledge Bases use the organization's default embedding model.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See the Knowledge Base documentation.
>
> > [tab] Key Features
> >
> > > [card] Per-KB model
> > >
> > > Each Knowledge Base carries its own embedding-model reference; a new Settings tab shows the current model.
> >
> > > [card] Local embedders
> > >
> > > Keep personal-information content on-box using a keyless local embedder fronted by a CUSTOM AI provider.
> >
> > > [card] Model travels with export
> > >
> > > Project version export preserves the KB's embedding-model reference, so a re-import keeps the same model.
> >
> > > [card] Set once per KB
> > >
> > > A Knowledge Base's embedding model is chosen before its first store and cannot be changed afterward.
>
> SaaS

### **Knowledge Base content lifecycle**

> [card] Delete entries by filter, structured failure handling, and per-chunk timestamps
>
> > [tab] Overview
> >
> > The **Update Knowledge Base** node gains a **Delete entries** operation and structured failure handling, and retrieval results now carry per-chunk metadata.
> >
> > **Delete entries** soft-deletes chunks whose entry-level metadata matches a filter, in one store or across the Knowledge Base; an empty or match-all filter is rejected so a misconfigured node cannot wipe a store. When an update operation fails, the node's **FAIL** branch returns a structured output with the operation, store, failure reason, and how many chunks were rolled back, and any partial changes are reversed. Retrieval results now include a per-chunk identifier and an ingestion timestamp.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > >
> > > See the Managing Knowledge Base content documentation.
>
> > [tab] Key Features
> >
> > > [card] Filtered deletion
> > >
> > > Delete entries by metadata filter from a workflow, with an empty or match-all filter rejected as a safety guard.
> >
> > > [card] Failure output with rollback
> > >
> > > The FAIL branch reports the operation, store, reason, and rolled-back chunk count; partial changes are reversed.
> >
> > > [card] Per-chunk timestamps
> > >
> > > RAG results carry a chunk identifier and an ingestion timestamp (empty for chunks indexed before this shipped).
> >
> > > [card] Clear retry signal
> > >
> > > Retryable failures such as extraction or chunking errors are distinguished from non-retryable ones such as size or timeout.
>
> SaaS

### **Document classification**

> [card] Classify document pages with a trainable ML model
>
> > [tab] Overview
> >
> > FlowX.AI adds **Document Classifiers**: deterministic ML models that sort document pages into categories. Define classes, upload training data, and train or import a model, then route each page in a workflow with the new **Document Classification** node.
> >
> > The node runs the active model over a document, returns a predicted label and probability per page with a configurable confidence threshold, and flags low-confidence pages. A page-level failure does not fail the node.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer documentation.
>
> > [tab] Key Features
> >
> > > [card] Train or import
> > >
> > > Build classes and training data in the Designer, then train a model or import a pre-trained one.
> >
> > > [card] Per-page classification
> > >
> > > The Document Classification node returns a label and probability for each page, with a confidence threshold and low-confidence flags.
> >
> > > [card] Deterministic routing
> > >
> > > Combine the node with a condition to route pages by their predicted category.
> >
> > > [card] Resilient runs
> > >
> > > A page that cannot be classified is reported per page without failing the whole node.
>
> SaaS

### **Conversational chat reply requirement**

> [card] Conversational runs must reply to chat
>
> A conversational (chat-driven) workflow must send at least one chat reply, either from a Custom Agent node with **Send as Chat Reply** on or from a Navigate in UI Flow node that completes the turn. A run that reaches the end without replying now fails with a clear error instead of ending silently.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **Custom Agent instruction limit**

> [card] Instructions field capped at 10,000 characters
>
> The Custom Agent **Instructions** field is now limited to 10,000 characters.
> SaaS

### **Reusable functions in Integration Designer**

> [card] Call reusable functions from Script and Condition (Fork) nodes
>
> Reusable functions can now be called from **Script** nodes and **Condition (Fork)** nodes in the Integration Designer, not just from Business Rule actions in processes. Functions are referenced in the node's JavaScript or Python and resolved at runtime from the app version's function copies, including functions that call other functions and cross-app references. A Fork node resolves the references used across all of its branch conditions.
>
> For more information, see the [reusable functions](/5.9/docs/building-blocks/reusable-resources/reusable-functions) documentation.
> SaaS

### **Extended response caching**

> [card] Cache POST REST, file-storage reads, and Mongo reads
>
> > [tab] Overview
> >
> > Response caching in the Integration Designer now covers more operation types. **POST** REST endpoints are cacheable alongside GET, with the request body forming part of the cache key so different bodies cache separately. Read **file-storage** operations (LIST and DOWNLOAD) and read **Mongo** operations (FIND, FIND\_ONE, AGGREGATE) are cacheable alongside SQL. Mutating operations are never cached.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] POST caching
> > >
> > > Cache POST responses, keyed on the request body so distinct requests stay separate.
> >
> > > [card] File-storage reads
> > >
> > > LIST and DOWNLOAD operations are cacheable; UPLOAD, DELETE, and MOVE are not.
> >
> > > [card] Mongo reads
> > >
> > > FIND, FIND\_ONE, and AGGREGATE are cacheable alongside SQL; mutating Mongo operations are not.
> >
> > > [card] Shared policy
> > >
> > > All cacheable surfaces reuse the same time-based expiry and per-operation clear-cache action.
>
> SaaS

### **Subworkflow data mapping**

> [card] Map data in and out of a subworkflow with input and output mappers
>
> > [tab] Overview
> >
> > The **Subworkflow** node adds data mapping as an alternative to raw JSON. Turn on **Enable data mapping** to define an **Input mapping** per subworkflow start node and an **Output mapping** per end node, mapping individual data slices instead of hand-editing JSON. Output mapping does not apply to asynchronous subworkflows. Each mapping opens a mapper with a test action, and mappings travel with import, export, and clone.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] Input and output mappers
> > >
> > > Map data into the subworkflow per start node and out of it per end node, without editing raw JSON.
> >
> > > [card] Per-mapping test
> > >
> > > Test a mapping with source and target slices and apply values from a past instance.
> >
> > > [card] Travels with the project
> > >
> > > Mappings are preserved on import, export, and clone.
> >
> > > [card] Async-aware
> > >
> > > Output mapping is hidden for asynchronous subworkflows, which do not return data to the caller.
>
> SaaS

### **Email attachment filtering by extension**

> [card] Filter email attachments by individual file extension
>
> Email Trigger and Microsoft Outlook data sources now filter attachments by **individual file extension** instead of the five broad file-type categories. Choose the exact extensions to accept and to forward into a process. Existing category selections are migrated to their individual extensions automatically on upgrade, so current triggers keep working.
>
> For more information, see the [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger) documentation.
> SaaS

### **Structured data model for templates**

> [card] Document and notification templates use the structured data model
>
> > [tab] Overview
> >
> > **Before 5.11:** document and notification templates declared parameters in a free-form key/value Data model tab. **Now:** templates use the same structured data model as the rest of the platform.
> >
> > On the **Data Model** tab you define typed attributes with validations, sensitive-data and reporting flags, and references to project or library data types. On the **Input Parameters** tab you select which attributes the template expects. Values sent in the request are substituted for those attributes at generation time.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > >
> > > See the notification templates documentation.
>
> > [tab] Key Features
> >
> > > [card] Typed attributes
> > >
> > > Define string, number, boolean, enum, date, currency, object, and array attributes with validations.
> >
> > > [card] Input Parameters
> > >
> > > Pick the attributes the template expects on a dedicated Input Parameters tab.
> >
> > > [card] Reference shared types
> > >
> > > Reference project and library data types like other resources.
> >
> > > [card] OTP unchanged
> > >
> > > The OTP flow contract is unchanged; the reserved `otpValue` and request `data` object work as before.
>
> SaaS

### **Data model attribute validators**

> [card] Validators on data model attributes
>
> Data model attributes now support validators. Available rules depend on the attribute type and include **Required**, **Min/Max Value**, **Min/Max Length**, **Pattern**, **Email Format**, and **Min/Max Items**, plus currency-specific amount and code rules. Validators are stored on the attribute and apply wherever that data model is used, including project, process, template, and reusable UI template data models.
>
> For more information, see the [project data model](/5.9/docs/building-blocks/project-data-model) documentation.
> SaaS

### **UI Flow runtime audit**

> [card] Audit UI Flow runtime activity
>
> UI Flow runtime sessions are now audited in more detail. The audit log records **workflow-instance** runs, chat **message sends**, conversation **list** and **history** reads, and whether the Process Renderer performed a **render** or a start. Entries name the app and the workflow instance.
>
> For more information, see the [audit](/5.9/docs/platform-deep-dive/core-extensions/audit) documentation.
> SaaS

### **Cross-version export adaptation**

> [card] Exports adapt UI templates for older LTS targets
>
> When you export a project to an older platform version, UI-template features the target version cannot understand are removed during down-adaptation, so the export imports cleanly. This currently covers Process Renderer process-end event handlers and the Navigate To **forms to validate** setting.
>
> For more information, see [Cross-version export and import](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
> All Deployments

### **Platform and runtime improvements**

> [card] Runtime access-control hardening
>
> Runtime API requests are now authorized against the roles defined in the running build across start-process, start-workflow, task views, conversation history, and the public runtime API. Requests without a matching build role are denied, and enforcement is on by default.
> All Deployments

> [card] Theme import no longer duplicates system icons
>
> Exporting a theme no longer includes duplicate copies of built-in system icons, and importing a theme no longer creates new ones. Duplicate icon copies that accumulated in earlier versions are cleaned up automatically on upgrade — no action is required.
> All Deployments

### **Chat notifications and conversation search**

> [card] Unread-message badge and conversation search in chat
>
> > [tab] Overview
> >
> > The chat floating action button gains an **unread-message notification badge**, with a themeable **Notification Dot** you can position in the chat style panel. The chat panel also adds **search across conversation history**, which filters conversations by a text query, highlights matches, and shows an empty state when nothing matches.
> >
> > For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
>
> > [tab] Key Features
> >
> > > [card] Unread badge
> > >
> > > The chat button shows a badge with the unread agent-message count; it is hidden while the chat is open in full screen.
> >
> > > [card] Notification Dot
> > >
> > > Position and size the notification dot from the chat style panel, with theme support.
> >
> > > [card] Conversation search
> > >
> > > Search conversation history from the chat panel, with highlighted matches and an empty state.
>
> SaaS

### **Disable chat input on a condition**

> [card] Make the chat input read-only with a business condition
>
> The chat **Input** component can be disabled by a business-condition expression. When the condition evaluates true, the input becomes read-only with an explanatory tooltip, and any pending attachments and voice input are cleared.
>
> For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
> SaaS

### **Navigate To form validation**

> [card] Require form validation before a Navigate To action
>
> A **Navigate To** action can now require selected forms to pass validation before navigating, matching how Start Process and Start Workflow actions gate on validation. This is available on web, iOS, and Android.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Expired UI Flow sessions**

> [card] A session-expired screen with a start-fresh option
>
> Expired UI Flow sessions now show a **session-expired** screen with a start-fresh option instead of leaving the previous data visible in read-only form. Expired and unauthorized access is written to the audit log.
> SaaS

### **UI Flow session owner**

> [card] Restrict a running session to a single user
>
> A UI Flow can restrict a running session to a single owner. When **Allow multiple editors** is off, other users who try to open the session are shown an access-denied screen, and unauthorized access is audited. Newly created flows default to single-owner; imported and existing flows keep the previous shared behavior. A session-owner value type is available for permission-based hide and disable rules.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Process Renderer process-end handling**

> [card] Run a configurable action when an embedded process ends
>
> The Process Renderer can now run a configurable action when its embedded process ends, using a new process-end trigger on event handlers. Configure what happens at that point instead of leaving the renderer idle when the process completes.
>
> For more information, see [Process end handling](/5.9/docs/building-blocks/ui-flows#process-end-handling).
> SaaS

### **Renderer improvements**

> [card] Renderer performance and behavior
>
> * **Batched enumeration fetch:** renderers batch enumeration lookups into a single bulk request, cutting the number of calls when rendering enum-backed fields. Applies to web and mobile renderers.
> * **Process-start loader alignment:** the web renderer keeps the process-start loader visible until the first user task, matching the mobile SDKs.
>   SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

FlowX.AI 5.11 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.11 deployment guidelines](./deployment-guidelines-v5.11).


# Deployment guidelines v5.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12

Component versions and deployment notes for FlowX.AI 5.12 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.12 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.12.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.12.0 |
| - | - |
| **admin** | 11.69.2 |
| **advancing-controller** | 11.46.0 |
| **application-manager** | 11.68.3 |
| **audit-core** | 11.44.1 |
| **authorization-system** | 11.53.2 |
| **cms-core** | 11.61.1 |
| **data-search** | 11.44.1 |
| **data-sync** | 11.43.1 |
| **designer** | 11.126.1 |
| **document-plugin** | 11.68.1 |
| **email-gateway** | 11.58.1 |
| **events-gateway** | 11.49.2 |
| **file-gateway** | 11.55.1 |
| **integration-designer** | 11.90.2 |
| **license** | 11.48.1 |
| **nosql-db-runner** | 11.49.1 |
| **notification-plugin** | 11.61.2 |
| **organization-manager** | 11.53.1 |
| **process-engine** | 11.76.1 |
| **runtime-manager** | 11.68.3 |
| **scheduler-core** | 11.45.1 |
| **task-management-plugin** | 11.59.2 |
| **webhook-gateway** | 11.54.1 |

### AI base components

| Component | 5.12.0 |
| - | - |
| **embedder** | 11.5.0 |
| **knowledgebase-indexer-v2** | 11.5.0 |
| **knowledgebase-rag** | 11.5.0 |
| **doc-parser** | 11.5.0 |

### AI dev-time components

| Component | 5.12.0 |
| - | - |
| **ai-gateway** | 11.53.1 |
| **ai-analyst** | 11.5.0 |
| **ai-assistant** | 11.5.0 |
| **ai-designer** | 11.5.0 |
| **ai-developer** | 11.5.0 |
| **kb-enrichment** | 11.5.0 |
| **planner** | 11.5.0 |

### AI runtime components

| Component | 5.12.0 |
| - | - |
| **agent-builder** | 11.5.0 |
| **ai-architect** | 11.5.0 |
| **data-privacy** | 11.5.0 |
| **doc-converter** | 11.5.0 |
| **dynamic-classifier** | 11.5.0 |
| **evals-judge** | 11.5.0 |
| **speech-to-text** | 11.5.0 |
| **web-crawler** | 11.5.0 |

### AI extensions

| Component | 5.12.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.126.1` for FlowX.AI 5.12.0). The native iOS and Android renderers version independently.

| Component | 5.12.0 |
| - | - |
| **@flowx/angular-sdk** | 11.126.1 |
| **@flowx/angular-theme** | 11.126.1 |
| **@flowx/angular-ui-toolkit** | 11.126.1 |
| **@flowx/react-sdk** | 11.126.1 |
| **@flowx/react-theme** | 11.126.1 |
| **@flowx/react-ui-toolkit** | 11.126.1 |
| **@flowx/react-native-sdk** | 11.126.1 |
| **@flowx/react-native-theme** | 11.126.1 |
| **@flowx/react-native-ui-toolkit** | 11.126.1 |
| **@flowx/core-sdk** | 11.126.1 |
| **@flowx/core-theme** | 11.126.1 |
| **react-saas** | 11.126.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.12 capabilities. On SaaS they are created and managed automatically.

**Event-triggered workflows** (email and webhook triggers can start an integration workflow):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Deep Research node** (the node hands research jobs to the AI Platform over Kafka):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | dead-letter queue for failed research jobs |

**Bulk process-instance migration:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |

**Notifications:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.eventsgateway.user.notifications.v1` | application-manager, process-engine → events-gateway |

**Document classification:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → dead-letter sink (not consumed) |

### New service dependency: webhook-gateway and MongoDB

The webhook gateway now reads the runtime registry that backs event-triggered workflows, so it depends on the runtime MongoDB database in addition to its existing relational database. On SaaS this connection is provisioned and managed by FlowX.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map. | none (required) | integration-designer |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today. | `k1` | integration-designer |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index. | `PT24H` | integration-designer |

### Native PostgreSQL partitioning for the engine

On PostgreSQL, the engine converts its runtime tables to native `RANGE(partition_id)` partitioning the first time it starts on the new version, and archiving then detaches a partition instead of copying rows out of it. Deployments that never enabled partitioning are skipped entirely, and Oracle deployments are unaffected.

Unlike most 5.12 changes, this one also reaches self-hosted 5.9.x in the 5.9.5 patch rather than waiting for the next LTS release family.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Whether archiving detaches partitions with `DETACH CONCURRENTLY` on natively partitioned tables. Setting it to `false` returns archiving to the previous batched insert-and-delete, but does not undo the conversion: the tables stay natively partitioned. | `true` | process-engine |

For the conversion cost, table locking and the one-way caveat, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.12.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026

What's new in FlowX.AI 5.12: parallel multi-instance subworkflow fan-out, event-triggered integration workflows, bulk process-instance migration, personal-data mask and restore nodes, and a Db2 data source.

[FlowX.AI 5.12 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.12.0.html)

> [!NOTE]
>
> **FlowX.AI 5.12 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.12** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release lets an integration workflow fan out over a collection without a subprocess, starts workflows directly from email and webhook events, and migrates process instances to a new build in bulk. It also adds personal-data mask and restore nodes to the Integration Designer and a Db2 relational data source.

### What changed since 5.11.0

| 5.11.0 | 5.12.0 |
| - | - |
| A workflow ran once per call; fanning out over a collection needed a BPMN Call Activity and a subprocess | + **Multi-instance subworkflow node** fans a workflow over a collection directly in the Integration Designer |
| An email or webhook trigger could start a process | + **Event-triggered workflows** start an integration workflow from the same triggers |
| Process instances migrated to a new build one at a time | + **Bulk migration** moves a filtered set of instances in one operation |
| Personal-data handling was configured on the agent | + **Mask and restore nodes** place it as explicit workflow steps, with details in the run log |

***

**What's new?**

> [tab] Integrations & Data
>
> 🔀 [**Multi-instance subworkflow node**](#multi-instance-subworkflow-node) - Fan a workflow out over a collection\
> ⚡ [**Event-triggered workflows**](#event-triggered-workflows) - Start a workflow from an email or webhook\
> 🗄️ [**Db2 relational data source**](#db2-relational-data-source) - Connect to Db2 for i or Db2 LUW\
> 🔻 [**Subworkflow failure exit**](#subworkflow-failure-exit) - Send a failed mapping down its own branch\
> 🔓 [**Skip TLS verification on a REST data source**](#skip-tls-verification-on-a-rest-data-source) - Reach a trusted internal host with an untrusted certificate\
> 🔔 [**Send Notification node**](#send-notification-node) - Send a templated notification straight from a workflow

> [tab] AI Platform
>
> 🛡️ [**Personal-data mask and restore nodes**](#personal-data-mask-and-restore-nodes) - Explicit workflow steps with run-log detail\
> 🧩 [**Reusable functions as agent tools**](#reusable-functions-as-agent-tools) - Give an agent a deterministic function to call\
> 👍 [**Chat response feedback**](#chat-response-feedback) - Let users rate an agent's answer, and theme how it looks\
> 📏 [**Custom evaluators**](#custom-evaluators) - Score an agent against a rubric you write yourself\
> 🔍 [**Deep Research node**](#deep-research-node) - Research a question across the open web and file a cited report\
> 🛠️ [**Built-in agent tools by category**](#built-in-agent-tools-by-category) - Twenty ready-made tools an agent can use, picked by category\
> 🪄 [**AI Designer builds UI Flows**](#ai-designer-builds-ui-flows) - Generate and edit multi-page UI Flows from a description

> [tab] Platform
>
> 📦 [**Bulk process-instance migration**](#bulk-process-instance-migration) - Move a filtered set of instances to a new build\
> 🔎 [**Runtime list filters and a Workflow Instances page**](#runtime-list-filters-and-a-workflow-instances-page) - Find the failed run without scanning the list\
> 🎨 [**Process canvas editing**](#process-canvas-editing) - Connect, reshape and resize more directly on the BPMN canvas\
> ⚠️ [**Check a version for issues**](#check-a-version-for-issues) - Validate every workflow in the version from one panel\
> 🧱 [**Reusable UI Templates in UI Flows**](#reusable-ui-templates-in-ui-flows) - Reuse a template on UI Flow pages, not just User Tasks\
> 🌿 [**Branch management**](#branch-management) - Merge to any branch, archive or delete the ones you are done with

### **Multi-instance subworkflow node**

> [card] Multi-instance subworkflow node
>
> > [tab] Overview
> >
> > **Before 5.12.0:** running an integration workflow once per item in a collection meant leaving the Integration Designer, wrapping the workflow in a BPMN process and fanning out with a multi-instance Call Activity. **Now:** the Subworkflow node fans out over an array on its own, in parallel.
> >
> > Turn on **Parallel Multi-Instance** under **Execution** on a Subworkflow node, pick the **Input Array** to iterate, and pick the **Output Array** that collects each run's result. The node starts one subworkflow instance per element of the input array and gathers the results into the output array on the parent workflow.
>
> > [tab] Key Features
> >
> > > [card] Input Array
> > >
> > > The array of objects to iterate. One subworkflow instance starts per element. Required.
> >
> > > [card] Output Array
> > >
> > > The array each instance result is collected into. Required.
> >
> > > [card] Correlation attribute
> > >
> > > Optional. Decides which output array element each result updates. Results matching no element, or all results when no attribute is set, are appended.
> >
> > > [card] Runs in parallel
> > >
> > > Instances run in parallel, and fan-out stays inside the Integration Designer instead of requiring a BPMN Call Activity.
>
> For the full configuration reference, see [Parallel multi-instance](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) on the Subworkflow node.
> SaaS

### **Event-triggered workflows**

> [card] Event-triggered workflows
>
> > [tab] Overview
> >
> > **Before 5.12.0:** an incoming email or webhook could start a process. **Now:** the same triggers can start an integration workflow directly.
> >
> > A workflow declares the trigger it listens for, and the platform keeps a subscription registry so a change to that trigger takes effect without rebuilding the whole app. Incoming email and webhook events are routed to the workflow that subscribes to them.
>
> > [tab] Key Features
> >
> > > [card] Email and webhook triggers
> > >
> > > Both trigger types can start a workflow, not only a process.
> >
> > > [card] Subscription registry
> > >
> > > Trigger changes update the affected data source without a full build recompute.
>
> > [tab] Architecture
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Trigger subscription changes | admin, integration-designer, application-manager | Design-time changes update the runtime subscription registry |
> > | Event delivery | email-gateway, webhook-gateway, integration-designer | Events are routed to the subscribing workflow |
> > | Webhook state | webhook-gateway | The webhook gateway now also reads the runtime registry, adding a MongoDB dependency it did not previously have |
> >
> > On SaaS these changes are applied automatically. See [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12) for the topic and dependency detail.
>
> For the full configuration reference, see [External triggers](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers) on the Start node.
> SaaS

### **Bulk process-instance migration**

> [card] Bulk process-instance migration
>
> > [tab] Overview
> >
> > **Before 5.12.0:** moving running process instances onto a new build was a one-at-a-time operation. **Now:** a filtered set of instances migrates in a single run.
> >
> > Select the target build, filter the instances to move, check the migration for problems before committing to it, and then run it. Progress and per-instance outcomes are available while it runs, and terminated instances are handled explicitly rather than failing the batch.
> >
> > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > See migrating process instances.
>
> > [tab] Key Features
> >
> > > [card] Filter then migrate
> > >
> > > Move specific instance UUIDs, the instances matching a process, node and status filter, or every eligible instance.
> >
> > > [card] Pre-flight check
> > >
> > > Validate a migration before running it.
> >
> > > [card] Per-instance outcomes
> > >
> > > Inspect details and results for the instances in a batch.
> >
> > > [card] Audit trail
> > >
> > > Migrations are recorded against the instances they touch.
>
> For the full configuration reference, see the [Migrate process instances](/5.9/docs/projects/runtime/active-process/migrate-process-instances) documentation.
> SaaS

### **Runtime list filters and a Workflow Instances page**

> [card] Runtime list filters and a Workflow Instances page
>
> Finding a failed run no longer means scanning an unfiltered list. The **Process Instances** and **UI Flow Sessions** lists gain a multi-select **Status** filter and a start-date filter on their columns, so "every failed instance since last night" is two clicks.
>
> Workflow runs get more: a new **Workflow Instances** page under **Runtime** lists every run in the project, filterable by **Status**, by date, and by **Origin**: whether a run was started by a process, a UI Flow, a webhook, or an email trigger. Until now, a workflow's runs were only visible from inside that workflow in the Integration Designer.
>
> For details, see the [Workflow Instances](/5.9/docs/projects/runtime/workflow-instances) documentation.
> SaaS

***

### **Personal-data mask and restore nodes**

> [card] Personal-data mask and restore nodes
>
> > [tab] Overview
> >
> > **Before 5.12.0:** personal-information handling was configured on the agent rather than placed in the flow. **Now:** masking and restoring personal data are workflow nodes you position explicitly, and you choose which key from the node input they apply to.
> >
> > Put a mask node before the step that must not see the raw values and a restore node after it. The workflow run log shows what each node did, so a run can be inspected without exposing the underlying data.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See the Personal Information Guard documentation.
>
> > [tab] Key Features
> >
> > > [card] Mask and restore as nodes
> > >
> > > Personal-data handling becomes an explicit step in the workflow.
> >
> > > [card] Selectable input key
> > >
> > > Choose which key from the node input the node applies to.
> >
> > > [card] Run-log detail
> > >
> > > A restore reports whether it completed, partially completed or failed, and how many of the issued placeholders it put back.
>
> For the full configuration reference, see [Masking and restoring across several nodes](/5.9/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
> SaaS

### **Db2 relational data source**

> [card] Db2 relational data source
>
> IBM Db2 joins the relational database data sources available in the Integration Designer. Because Db2 products use different drivers, ports and catalogs, the connection starts with a **Db2 Product** choice and the rest of the form follows from it. **Db2 for i (IBM i)** is the default and **Db2 LUW** is also supported. **Db2 for z/OS** appears in the list but is not implemented in this release, and selecting it fails with an explicit error rather than falling back to another driver.
>
> The port is prefilled from the product and whether SSL is on. Db2 for i adds a naming convention, an optional library and library list, and a switch for returning character data that the host reports as binary. On Db2 for i, connections also open **read-only by default**, so turn that off if your queries need to write, and the transaction isolation level defaults to none, because a table without a journal cannot take part in a transaction. Isolation is validated when the data source is saved rather than when a query first runs.
>
> For the full configuration reference, see the [Db2 Database](/5.9/docs/platform-deep-dive/integrations/db2-database) documentation.
> SaaS

***

### **Subworkflow failure exit**

> [card] Subworkflow failure exit
>
> A Subworkflow node now has a second exit. Connect the red one and a failure takes its own branch instead of stopping the parent workflow. It is opt-in per node, so a node without that branch fails and blocks exactly as before and nothing changes for existing workflows.
>
> Only a mapping failure routes, which is the kind a workflow can be built to handle: the input mapper failing, the input not satisfying what the subworkflow expects, or the output mapper failing on merge-back. An unset subworkflow, a missing response key, no mapping at all, and the node and depth limits all still stop the run. The branch reads a fixed `subWorkflowError` key that says which mapping failed and, when a child did start, which run it was.
>
> For the full configuration reference, see [Routing a subworkflow failure](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
> SaaS

***

### **Skip TLS verification on a REST data source**

> [card] Skip TLS verification on a REST data source
>
> A REST data source can now be told to stop checking the certificate of the host it calls, for the cases where an internal endpoint presents a self-signed or mismatched certificate and the alternative is an infrastructure workaround. It is off by default and set per data source, so turning it on for one connector leaves every other call verified.
>
> The Designer warns while it is on, because the call can no longer tell the intended host from anything intercepting it. One consequence is worth knowing before you use it: a truststore configured under Certificates is ignored while verification is skipped, since skipping replaces it rather than adding to it.
>
> For the full configuration reference, see [TLS verification](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#tls-verification) on a REST data source.
> SaaS

***

### **Send Notification node**

> [card] Send Notification node
>
> Workflows can now send notifications themselves. A **Send Notification** node, under **Tools** in the workflow node palette, takes one of your project's notification templates, fills its variables from workflow data, and sends it, without routing through a process just to reach the Notifications plugin.
>
> Address it with **To**, **Cc** and **Bcc**, as fixed addresses or `${}` keys. Email options are all overridable per node: subject, sender name and email, attachments by file path or `${}` key, and custom headers. The node reports the outcome under its response key, including recipient counts and the error when sending fails, so the workflow can branch on it.
>
> For the full configuration reference, see the [Send Notification node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node) documentation.
> SaaS

***

### **Reusable functions as agent tools**

> [card] Reusable functions as agent tools
>
> An AI node's tools can now include a **Function**, alongside built-in web search, an MCP server, and a workflow. Point an agent at a reusable function when the work is deterministic and you would rather it call your code than reason its way there.
>
> A function has to be typed to qualify: it needs both an input and an output slice, and functions without them do not appear in the picker. Give it a description as well, since that is what tells the agent when to reach for it.
>
> For the full configuration reference, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **Chat response feedback**

> [card] Chat response feedback
>
> Users can rate an agent's answer in the chat component, and follow the rating with a reason. The ratings are recorded in audit, so the quality of a deployed agent becomes something you can look at rather than guess at.
>
> The feedback controls and the reason chips are themable, with their own selected and hover states, so they can be styled to match the rest of the interface. The SDKs expose the same feedback state to custom front ends.
>
> For the full configuration reference, see [Rating an answer](/5.9/ai-platform/chat-component#rating-an-answer) on the chat component.
> SaaS

***

### **Custom evaluators**

> [card] Custom evaluators
>
> The evaluator catalogue is no longer fixed. When none of the built-in rubrics measures what you care about, you can write your own evaluator, give it the scoring instructions the judge LLM should follow, and it appears in the catalogue under a **Custom** group alongside the built-in ones.
>
> Choose **Numeric** scoring for a score between 0 and 1 with a pass threshold, or **Binary** for a straight pass or fail. You can start from an existing evaluator to adapt a built-in rubric rather than writing a prompt from scratch. Custom evaluators belong to the workflow you create them in, and unlike the built-in ones they can be edited and deleted.
>
> For the full configuration reference, see the [Evaluations](/5.9/ai-platform/evaluations#custom) documentation.
> SaaS

***

### **Deep Research node**

> [card] Deep Research node
>
> A new AI node researches a question across the open web and files a cited report into a Knowledge Base. It plans the work, sends sub-researchers out to search and read pages, grades what they bring back, and keeps going until its budget is spent or it has enough to report.
>
> Unlike a Custom Agent, you do not write the method: the research prompt is built into the node, so you describe the subject and bind workflow data into it. Depth is a **Quick**, **Standard** or **Deep** preset, or **Custom** if you want to set the number of passes and tool calls yourself. You can restrict which domains the research may read, with an allow list, a deny list, or both.
>
> The result always lands in a Knowledge Base as text, so retrieval nodes and other agents can reach it later. Rendering it as a document is optional.
>
> For the full configuration reference, see the [Deep Research node](/5.9/docs/platform-deep-dive/integrations/deep-research-node) documentation.
> SaaS

***

### **Built-in agent tools by category**

> [card] Built-in agent tools by category
>
> A Custom Agent's built-in tools are now a catalog you pick from by category: **Math tools**, **List tools**, **Date tools**, **Text tools**, and **Web search**. Each category row shows exactly which tools it turns on, and the agent runs deterministic code for that work instead of estimating it in the model.
>
> The catalog holds twenty tools, fifteen of them new: a full date family (business days, date arithmetic, formatting, parsing, timezone conversion), text helpers (regex match and extract, fuzzy match), unit conversion, and list aggregation, joining the original calculator, compare, sort, and filter. Web search is part of the same catalog rather than a separate toggle.
>
> Selection stays opt-in and per node. Agents saved with the old toggles keep working without an edit.
>
> For details, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **AI Designer builds UI Flows**

> [card] AI Designer builds UI Flows
>
> The AI Designer now works at the level of a whole UI Flow. Describe the journey and it generates a multi-page flow: structure first, pages filled in parallel, navigation wired between them. Ask for a change and it edits the affected pages instead of regenerating everything.
>
> Proposals appear on the UI Flow canvas as a draft for you to review, the editor stays locked while one is pending, and any data-model changes the flow needs are presented for approval on every turn, the same way single-screen generation already works.
>
> For details, see the [AI Designer](/5.9/ai-platform/pre-built-agents/ai-designer#ui-flow-generation-and-editing) documentation.
> SaaS

***

### **Check a version for issues**

> [card] Check a version for issues
>
> The Designer can now validate the resources in a project version and collect what it finds in one **Issues** panel at the bottom of the screen. Findings are marked where they occur, on resource lists, page titles and workflow canvas nodes, and selecting a marker opens the panel on that finding.
>
> Checks run when you ask for one, and the panel says when it last ran so a stale result is obvious. You can scope the list to the whole version, the resource you are in, or the node you have selected, filter it by severity or text, and group it by resource or severity. Opening **Commit Changes to Version** runs a check on its own and shows each changed resource's state beside it, as a review step rather than a gate. Integration workflows are the resource type validated in this first iteration.
>
> For the full configuration reference, see the [Checking a version for issues](/5.9/docs/projects/managing-applications/checking-for-issues) documentation.
> SaaS

***

### **Branch management**

> [card] Branch management
>
> Project branches gained a management layer. The merge modal now offers every branch you can merge into, not just the current branch's parents, so a fix made anywhere can land anywhere it is needed.
>
> Branches you are done with no longer linger: **Archive Branch** retires one (with a required reason, shown later in its info panel), **Unarchive Branch** brings it back, and **Delete Branch** removes one permanently, guarded so it refuses while child branches, an uncommitted draft, or a running merge depend on it, and asks you to type the branch name when unmerged work would be lost. Deleting has its own permission.
>
> Branch and version info panels round it out: a version merged from another branch says where it came from, including whether that branch has since been archived.
>
> For details, see [Managing branches](/5.9/docs/projects/managing-applications/versioning#managing-branches).
> SaaS

***

### **Process canvas editing**

> [card] Process canvas editing
>
> The BPMN canvas gains a set of direct editing improvements. A **New Node** panel and
> drop-anywhere connecting make it quicker to add a node and wire it up, connecting to a nearby
> node no longer means aiming precisely at a handle, and sequence flows can be reshaped by
> dragging their control points. Swimlanes now resize from any of their four edges. The
> process-instance viewer picks up the same canvas.
>
> The canvas is deliberately unchanged to look at, so existing diagrams, habits and screenshots
> still hold.
>
> For the full configuration reference, see [Faster ways to build](/5.9/docs/building-blocks/process/process#faster-ways-to-build) on the Process Designer canvas.
> SaaS

***

### **Reusable UI Templates in UI Flows**

> [card] Reusable UI Templates in UI Flows
>
> A Reusable UI Template can now be built for **UI Flow** pages as well as for the User Tasks in a process. Each template declares where it is used when you create it, and the UI Flow editor can drop templates onto a page the same way the Process editor always could.
>
> The host type also decides which actions a template's event handlers offer, so a template built for UI Flows gets navigation and workflow actions while one built for processes gets node actions. Because of that the choice is fixed once the template exists, and templates you created before this release count as Process templates, so nothing you already built changes.
>
> For the full configuration reference, see [Where a template can be used](/5.9/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used) in the Reusable UI Templates documentation.
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12).


# Deployment guidelines v5.13.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13

Component versions and deployment-level changes for FlowX.AI 5.13.0.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.13 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency. Self-hosted deployments receive these capabilities with the next LTS release family.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.13.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.13.0 |
| - | - |
| **admin** | 11.97.0 |
| **advancing-controller** | 11.67.0 |
| **application-manager** | 11.101.0 |
| **audit-core** | 11.69.0 |
| **authorization-system** | 11.78.0 |
| **cms-core** | 11.88.0 |
| **data-search** | 11.67.0 |
| **data-sync** | 11.68.0 |
| **designer** | 11.168.1 |
| **designer-user** | 11.8.0 |
| **document-plugin** | 11.95.0 |
| **email-gateway** | 11.83.0 |
| **events-gateway** | 11.72.0 |
| **file-gateway** | 11.79.0 |
| **integration-designer** | 11.119.1 |
| **license** | 11.72.0 |
| **nosql-db-runner** | 11.73.0 |
| **notification-plugin** | 11.88.0 |
| **organization-manager** | 11.77.0 |
| **process-engine** | 11.104.0 |
| **runtime-manager** | 11.101.0 |
| **scheduler-core** | 11.69.0 |
| **task-management-plugin** | 11.84.0 |
| **webhook-gateway** | 11.78.0 |

**designer-user** is new in 5.13. It backs the Designer notification center.

### AI base components

| Component | 5.13.0 |
| - | - |
| **embedder** | 11.6.0 |
| **knowledgebase-indexer-v2** | 11.6.0 |
| **knowledgebase-rag** | 11.6.0 |
| **doc-parser** | 11.6.0 |

### AI dev-time components

| Component | 5.13.0 |
| - | - |
| **ai-gateway** | 11.85.0 |
| **ai-analyst** | 11.6.0 |
| **ai-architect** | 11.6.0 |
| **ai-assistant** | 11.6.0 |
| **ai-designer** | 11.6.0 |
| **ai-developer** | 11.6.0 |
| **harness** | 11.6.0 |
| **ai-render-host** | 11.168.1 |
| **kb-enrichment** | 11.6.0 |
| **planner** | 11.6.0 |

**harness** and **ai-render-host** are new in 5.13. Together they run the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness): harness is the agent service, and ai-render-host renders UI flows headlessly for the agent. ai-render-host ships at the designer version.

### AI runtime components

| Component | 5.13.0 |
| - | - |
| **agent-builder** | 11.6.0 |
| **cee-pii** | 11.6.0 |
| **data-privacy** | 11.6.0 |
| **doc-converter** | 11.6.0 |
| **dynamic-classifier** | 11.6.0 |
| **evals-judge** | 11.6.0 |
| **speech-to-text** | 11.6.0 |
| **web-crawler** | 11.6.0 |

### AI extensions

| Component | 5.13.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.10.2 |
| **observatory-platform** | 11.10.2 |
| **observatory-web** | 11.10.2 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.168.1` for FlowX.AI 5.13.0). The native iOS and Android renderers version independently.

| Component | 5.13.0 |
| - | - |
| **@flowx/angular-sdk** | 11.168.1 |
| **@flowx/angular-theme** | 11.168.1 |
| **@flowx/angular-ui-toolkit** | 11.168.1 |
| **@flowx/react-sdk** | 11.168.1 |
| **@flowx/react-theme** | 11.168.1 |
| **@flowx/react-ui-toolkit** | 11.168.1 |
| **@flowx/react-native-sdk** | 11.168.1 |
| **@flowx/react-native-theme** | 11.168.1 |
| **@flowx/react-native-ui-toolkit** | 11.168.1 |
| **@flowx/core-sdk** | 11.168.1 |
| **@flowx/core-theme** | 11.168.1 |
| **react-saas** | 11.168.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

***

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.13 capabilities. On SaaS they are created and managed automatically.

**Notification center:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |

Notifications now pass through designer-user, which stores them and forwards them to events-gateway on the existing `ai.flowx.eventsgateway.user.notifications.v1` topic for delivery to the Designer.

**Move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

### New services

The Developer Agentic Harness adds the **harness** and **ai-render-host** services to the AI dev-time group, with a dedicated PostgreSQL database for harness sessions. The notification center adds the **designer-user** core service, which uses MongoDB, Redis, and Kafka. On SaaS these services and their databases are provisioned and managed by FlowX.

### New service dependency: process-engine and object storage

Oversized workflow responses and UI flow updates are now offloaded to object storage instead of travelling inline on Kafka. The process engine reads these offloaded payloads, so it now depends on object storage in addition to its existing databases. On SaaS this connection is provisioned and managed by FlowX.

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` | process-engine, audit-core |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Self-hosted deployments receive this change with the next LTS release family. A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.13.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026

What's new in FlowX.AI 5.13: a user notification center in Designer, UI component copy and paste across contexts, commit descriptions on app versions, and move token on process instances.

[FlowX.AI 5.13 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.13.0.html)

> [!NOTE]
>
> **FlowX.AI 5.13 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.13** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. The headline: the FlowX Developer Agentic Harness, an AI agent in the Designer that builds and changes apps from a description, with you confirming the plan and every operation before it runs. The release also adds a notification center to the Designer, lets builders copy and paste UI components across apps with a review of what could not be placed, records a description on every app version commit, forwards runtime events to Mixpanel and GA4, and moves stuck tokens on running process instances.

### What changed since 5.12.0

| 5.12.0 | 5.13.0 |
| - | - |
| Apps were assembled by hand in the Designer | + **Developer Agentic Harness**: describe the change, confirm the plan, review the result on its own branch |
| Long-running operations surfaced as passing toasts | + **Notification center** keeps a searchable 30-day history with read state |
| UI components copied within one context | + **Copy and paste across contexts**, with a paste review and unique naming |
| App version commits had a name only | + **Commit descriptions** and a commit details view record why a version exists |
| A stuck process instance needed support intervention | + **Move token** relocates the token, guarded by a dedicated corrective-actions role |

***

**What's new?**

> [tab] Builders
>
> 🔔 [**User notification center**](#user-notification-center) - Bell, searchable history, read state in Designer\
> 📋 [**UI component copy and paste**](#ui-component-copy-and-paste) - Cross-context paste with review and unique naming\
> 📝 [**Commit descriptions and details**](#commit-descriptions-and-details) - Optional description on version commits plus a details view\
> 📦 [**Version export alignment**](#version-export-alignment) - Version exports bundle dependencies like build exports

> [tab] Platform
>
> 🚑 [**Move token and corrective actions**](#move-token-and-corrective-actions) - Relocate a token, gated by a dedicated role

> [tab] AI Platform
>
> 🪄 [**Developer Agentic Harness**](#developer-agentic-harness) - Describe a change, the agent plans and builds it on a branch\
> 🧠 [**ML corpus import and export**](#ml-corpus-import-and-export) - Move a document classifier corpus between environments\
> ⚖️ [**Fair scheduling for embedding jobs**](#fair-scheduling-for-embedding-jobs) - Knowledge Base ingestion no longer starves small jobs\
> 🧩 [**Data Parse node**](#data-parse-node) - Tabular Data Extraction generalized, now parses XML and JSON\
> 🔐 [**File Encryption node**](#file-encryption-node) - Encrypt and decrypt files inside a workflow

> [tab] Rendering & SDKs
>
> 💬 [**React Native chat component**](#react-native-chat-component) - Floating chat sheet with voice input on mobile\
> ▶️ [**Conditional start workflow trigger**](#conditional-start-workflow-trigger) - Start a workflow from the UI only when a condition holds

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > **Before 5.13.0:** every process, screen, and data type was assembled by hand in the Designer. **Now:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys your app first, so changes use your real resources and names, then drafts a plan for you to confirm.
> >
> > You hold every gate: the agent runs only after you confirm the plan and review each operation, the change lands on a dedicated branch that never touches your main line, and merging plus serving a new version stay human decisions. See the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness) page for the full flow.
> >
> > <video>
> >   <track label="English" />
> > </video>
>
> > [tab] Key Features
> >
> > > [card] Works on your real app
> > >
> > > Surveys existing resources first, so changes use your actual processes, data types, and names.
> >
> > > [card] Plan, confirm, then run
> > >
> > > You confirm the plan and review every operation; the change runs on a dedicated branch that only you can merge or serve.
> >
> > > [card] Broad resource coverage
> > >
> > > Creates and edits processes, UI flows, workflows, and project data types.
> >
> > > [card] Guarded operations
> > >
> > > Destructive changes are gated, and runtime data such as process instances is never touched.
>
> SaaS

### **User notification center**

> [card] User notification center
>
> > [tab] Overview
> >
> > **Before 5.13.0:** long-running operations such as app imports or instance migrations announced themselves once and were gone. **Now:** a bell in the Designer opens a notification center with a 30-day history.
> >
> > Notifications carry read state, search, and filters by unread status and workspace type. First producers: app version export and process instance migration results.
>
> > [tab] Key Features
> >
> > > [card] 30-day history
> > >
> > > Notifications persist for 30 days instead of disappearing with the toast.
> >
> > > [card] Read state and search
> > >
> > > Mark notifications read, search them, and filter by unread status or workspace type.
> >
> > > [card] Export and migration results
> > >
> > > Get notified when an app version export finishes, fails, or times out, and when a process instance migration completes.
> >
> > > [card] Live updates
> > >
> > > The center updates over a live stream, including read state changes from other sessions.
>
> SaaS

### **UI component copy and paste**

> [card] UI component copy and paste
>
> > [tab] Overview
> >
> > **Before 5.13.0:** copying UI components was limited to the context you were in. **Now:** builders copy components and paste them into another UI Flow, app, or context.
> >
> > Pasting responds with a review of what could not be placed instead of failing silently, and pasted components receive unique names automatically. The clipboard holds one consistent version of the copied structure.
>
> > [tab] Key Features
> >
> > > [card] Cross-context paste
> > >
> > > Paste a copied component into a different UI Flow or app through a dedicated modal.
> >
> > > [card] Paste review
> > >
> > > The paste result names anything it could not place, so nothing drops without a trace.
>
> SaaS

### **Commit descriptions and details**

> [card] Commit descriptions and details
>
> Committing or merging an app version now takes an optional description of up to 2000 characters, and a commit details view shows what a version contains and why it exists. Version history stops being a list of names.
> SaaS

### **Version export alignment**

> [card] Version export alignment
>
> Project version exports now bundle dependencies the same way build exports do, so a version export is self-contained. The export dialog pre-selects the target platform version, and the exported filename carries the target version and whether media is included.
> SaaS

### **Move token and corrective actions**

> [card] Move token and corrective actions
>
> > [tab] Overview
> >
> > **Before 5.13.0:** a process instance stuck on the wrong node needed support intervention. **Now:** an operator with the corrective-actions role moves the token to the right node from Runtime.
> >
> > Corrective actions, covering bulk instance migration and move token, are gated by a dedicated workspace-level role, so admins grant this power without handing out full admin rights.
> >
> > The **Workspace corrective actions editor** role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically. See [Move tokens](/5.9/docs/projects/runtime/active-process/move-token) and the [Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
>
> > [tab] Key Features
> >
> > > [card] Move token
> > >
> > > Relocate the token of a running instance to another node in the process definition.
> >
> > > [card] Dedicated role
> > >
> > > A workspace-level corrective-actions role scopes who can migrate instances and move tokens.
>
> SaaS

### **ML corpus import and export**

> [card] ML corpus import and export
>
> A document classifier corpus now moves between environments: export the corpus with the model, import it into a runtime classifier, and inspect it in a read-only view in the Data tab. Training data stops being trapped in the environment where labeling happened.
> SaaS

### **Fair scheduling for embedding jobs**

> [card] Fair scheduling for embedding jobs
>
> Knowledge Base embedding jobs are scheduled fairly by default, so a large ingestion no longer starves small jobs queued behind it. Uploads to one Knowledge Base stop delaying every other one on the environment.
> SaaS

### **Data Parse node**

> [card] Data Parse node
>
> The Tabular Data Extraction node is generalized into a **Data Parse** node: it still reads CSV and Excel files into workflow data, and now also parses **XML** and **JSON**. A file fetched by a File Storage Operation can be read into the workflow regardless of its structured format.
> SaaS

### **File Encryption node**

> [card] File Encryption node
>
> A new **File Encryption** workflow node encrypts or decrypts a file with a password directly in the workflow, so protecting a generated document or opening a protected upload no longer needs a custom integration. The file path and password take expressions, letting the password come from workflow data.
> SaaS

### **React Native chat component**

> [card] React Native chat component
>
> The React Native renderer gains the chat experience mobile apps were missing: a floating chat sheet with voice input, suggested prompts, and conversation history. Renderer updates in the same release cover form validation on navigation actions, action context on execute-URL, and bulk enum fetching on eager load.
> SaaS

### **Conditional start workflow trigger**

> [card] Conditional start workflow trigger
>
> A start workflow trigger in the UI now takes a condition, so the workflow starts only when the expression holds. Available in the web SDK and on iOS.
> SaaS

### **Smaller improvements**

> [card] Smaller improvements
>
> **Process details modal:** the process name moves from Settings into a Details modal.
>
> **Document and image sources:** Document and Image UI components share one source configuration. In process user tasks, the new **Document Plugin Path** source takes a Documents plugin `downloadPath` directly, so you no longer need a business rule to build the file URL. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13) for File Preview and the [Download component](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download#file-sources-in-flowx-ai-5-13).
>
> **Sign-up link to solution:** a sign-up link lands new users directly in the right solution.
>
> **Bulk invite:** inviting many users at once gets a reworked flow.
>
> **Task list search on translated labels:** the task list searches, filters, and sorts on the labels it displays, in the viewer's language, for status, enumeration, and substitution-tag columns. See [Search and sort on translated labels](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).&#x20;
>
> **Reserved substitution-tag prefix:** custom substitution tags can no longer start with `sys_`; the prefix is reserved for system tags.&#x20;
> **Intersects operator for array fields:** FlowX Database queries can match documents whose array field shares at least one value with a given list. See [Intersects on array fields](/5.9/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).&#x20;
>
> **Request after PII anonymization in the run log:** AI nodes with the input scan enabled log the request exactly as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/5.9/ai-platform/personal-information-guard#request-after-pii-anonymization).&#x20;
>
> **Elasticsearch replica auto-expansion:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Changed default: Elasticsearch replica auto-expansion](./deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).&#x20;
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.13.0](./deployment-guidelines-v5.13).


# Deployment guidelines v5.2.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/deployment-guidelines-v5.2

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.12.0** | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **10.12.0** | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **10.7.0** | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **10.7.0** | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **10.6.0** | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **10.4.1** | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **10.6.0** | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **10.4.1** | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **10.8.0** | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **10.3.1** | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **10.4.1** | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **10.0.0** | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **10.0.0** | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.0.1** | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | **10.2.0** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.2.0 | Keycloak | 26+ |
| 5.2.0 | Kafka | 3.8 - 3.9 |
| 5.2.0 | PostgreSQL | 16 - 17 |
| 5.2.0 | Oracle Database | 21c, 23ai |
| 5.2.0 | MongoDB | 7 - 8 |
| 5.2.0 | Redis | 7.4 - 8.0 |
| 5.2.0 | Elasticsearch | 8 - 9 |
| 5.2.0 | Angular (Web SDK) | 19.2 |
| 5.2.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.2.0

### Key infrastructure updates

> [card] SpiceDB Upgrade
>
> Upgraded to SpiceDB v1.38.0+ and spice-db-operator for improved permission management and stability

> [card] Security Enhancements
>
> Updated Java libraries and base images to Oracle 10-slim, resolving HIGH and CRITICAL vulnerabilities

> [card] Accessibility Support
>
> Enhanced renderer components with comprehensive WCAG 2.1 compliance features

> [card] Python IDE Features
>
> Added autocomplete and IntelliSense support in business rules editors

> [card] Parallel Workflow Branches
>
> Support for concurrent execution paths in Integration Designer workflows

> [card] Workflow Partitioning & Archiving
>
> Time-based partitioning and automatic archiving for Integration Designer workflow instances

## Upgrading from v5.1.0

### Key changes

* **Accessibility Features**: No breaking changes, but new accessibility properties available in UI Designer
* **Database Security**: FlowX Database now supports sensitive data masking (requires Project Data Model configuration)
* **IDE Enhancements**: Python autocomplete is automatically available in business rules editors
* **Infrastructure**: SpiceDB upgrade requires cache clearing after migration

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.

### Compatibility

* **Backward Compatible**: v5.2.0 maintains backward compatibility with v5.1.0 configurations
* **Renderer Updates**: Web SDKs include accessibility enhancements without breaking changes
* **Mobile Renderers**: iOS and Android renderers include accessibility improvements

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/update-environment-variables-5.2

Update environment variables for all existing FlowX.AI services

## Integration Designer

### Workflow partitioning and archiving

> [!NOTE]
>
> Integration Designer now supports workflow instance partitioning and automatic archiving for efficient data management in high-volume deployments.

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Enable or disable workflow instance partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Time interval for creating partitions (`DAY`, `WEEK`, `MONTH`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Enable or disable automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Cron expression for archiving schedule (default: daily at 1:00 AM) |

> [!NOTE]
>
> **Workflow partitioning configuration:**
>
> * **Partitioning**: When enabled, workflow instances are stored in time-based partitions according to the specified interval
> * **Retention**: Determines how many intervals to keep active. Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> * **Archiving schedule**: The cron expression controls when the archiving process runs
> * **Best practice**: Enable partitioning first without archiving, verify it works correctly, then enable archiving

> [!WARNING]
>
> Enable partitioning and archiving only after careful planning and testing. Ensure your database has sufficient storage for partition management operations. It's recommended to start with archiving disabled and enable it only after verifying that partitioning works correctly for your use case.

### Advancing controller improvements

> [!NOTE]
>
> Integration Designer now uses the new ADVANCING controller with separate picking and processing operations for improved performance and resource management.

#### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

#### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.


# FlowX.AI 5.2.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025

Accessibility improvements, new side panel navigation, FlowX Database sensitive data handling, REST API response caching, and Python IDE enhancements for business rules development.

**What's new?**

> [tab] Accessibility & UX
>
> Making FlowX applications more inclusive and user-friendly with comprehensive accessibility improvements and enhanced navigation.
>
> ♿ [**Accessibility Enhancements**](#accessibility-enhancements) - Comprehensive [WCAG](https://www.w3.org/TR/WCAG21/) (Web Content Accessibility Guidelines) compliance features across all UI components\
> 🎨 [**New Workflow Side Panel**](#new-workflow-side-panel) - Enhanced navigation experience with improved drag-and-drop functionality
>
> ### **Accessibility enhancements**
>
> > [card] Accessibility enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds accessibility features across all UI components, enabling you to build [WCAG 2.1 Level AA compliant](https://www.w3.org/TR/WCAG21/) applications. These features support users with assistive technologies such as screen readers and keyboard-only navigation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs1.png)
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs2.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Accessibility Configuration Panel
> > > >
> > > > Configure labels, descriptions, and ARIA attributes in a dedicated accessibility section within UI Designer
> > >
> > > > [card] Auto-bindable Tags
> > > >
> > > > Bind accessibility tags automatically to buttons, inputs, selects, modals, and other UI components
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Navigate using keyboard shortcuts with proper focus management and tab order in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > Use screen readers with ARIA labels, descriptions, and live regions on all components
> >
> > > [tab] Supported Components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio buttons, Slider, and File upload components with labels and descriptions
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card components with keyboard navigation and focus management
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with alt text support and semantic HTML structure
> > >
> > > **4. Cross-Platform Support**
> > >
> > > Web (Angular/React), iOS, and Android platforms
> >
> > > [tab] Benefits
> > >
> > > > [card] WCAG Compliance
> > > >
> > > > Build applications that meet WCAG 2.1 Level AA standards for web accessibility
> > >
> > > > [card] Inclusive Design
> > > >
> > > > Make your applications usable for people with diverse abilities and assistive technology users
> > >
> > > > [card] Improved User Experience
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those using assistive technologies
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Meet accessibility requirements for government, healthcare, financial services, and other regulated industries
> >
> > Major Enhancement
>
> ***
>
> ### **New workflow side panel**
>
> > [card] New workflow side panel
> >
> > > [tab] Overview
> > >
> > > The new Workflow Side Panel provides an enhanced navigation experience in Integration Designer workflows. It includes improved organization, better drag-and-drop functionality, and intuitive access to design components and resources.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_side_panel.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Drag & Drop
> > > >
> > > > Add and organize workflow nodes with drag-and-drop functionality
> > >
> > > > [card] Improved Organization
> > > >
> > > > Group nodes logically with expandable/collapsible sections
> > >
> > > > [card] Search & Filter
> > > >
> > > > Find nodes instantly with quick search functionality
> >
> > UI/UX Enhancement
>
> ***

> [tab] Data & Security
>
> Enhanced data management and security features for FlowX Database and business rules.
>
> 🔒 [**FlowX Database Sensitive Data**](#flowx-database-sensitive-data) - GDPR-compliant sensitive data handling for FlowX Database\
> 🚀 [**Performance Improvements**](#performance-improvements) - Caching optimizations for better system performance
>
> ### **FlowX database sensitive data**
>
> > [card] FlowX database sensitive data
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds sensitive data handling for FlowX Database to ensure GDPR compliance. Attributes marked as sensitive in your Project Data Model are automatically protected across all FlowX Database operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic Data Masking
> > > >
> > > > Hide sensitive attributes automatically in logs, console outputs, and testing interfaces
> > >
> > > > [card] Project Data Model Integration
> > > >
> > > > Mark attributes as sensitive in Project Data Model to apply protection across all FlowX Database operations
> > >
> > > > [card] Developer-Friendly
> > > >
> > > > Access full data at runtime while maintaining security in design-time interfaces
> > >
> > > > [card] Audit Trail Protection
> > > >
> > > > Mask sensitive data in workflow output logs and operational documents
> >
> > > [tab] Protected Areas
> > >
> > > **1. Documents Page**
> > >
> > > Sensitive attributes are masked when viewing FlowX Database documents in the designer
> > >
> > > **2. Test Operations Pages**
> > >
> > > Database operation testing interfaces automatically hide sensitive data
> > >
> > > **3. Workflow Console**
> > >
> > > Console logs and output panels mask sensitive information from FlowX Database responses
> > >
> > > **4. Full Runtime Access**
> > >
> > > Applications have full access to sensitive data at runtime - protection is design-time only
> >
> > > [tab] Benefits
> > >
> > > > [card] GDPR Compliance
> > > >
> > > > Meet data protection requirements by preventing sensitive data exposure in design tools
> > >
> > > > [card] Security by Design
> > > >
> > > > Sensitive data protection is automatic once attributes are marked in Project Data Model
> > >
> > > > [card] Developer Productivity
> > > >
> > > > Test and develop without worrying about accidentally exposing sensitive information
> > >
> > > > [card] Audit-Ready
> > > >
> > > > Demonstrate proper data handling practices with masked logs and interfaces
> >
> > Security Enhancement
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Caching Enhancements
> > >
> > > FlowX.AI 5.2.0 adds intelligent caching mechanisms that improve system performance by reducing redundant processing when identical values are sent at process start.
> >
> > > [tab] Key Features
> > >
> > > > [card] Smart Caching
> > > >
> > > > Cache and reuse results automatically when identical input values are detected
> > >
> > > > [card] Reduced Latency
> > > >
> > > > Start processes faster when repeating operations with the same parameters
> > >
> > > > [card] Resource Optimization
> > > >
> > > > Reduce server load and improve resource utilization
> > >
> > > > [card] Automatic Management
> > > >
> > > > Manage cache automatically with no configuration required
> >
> > > [tab] Benefits
> > >
> > > **1. Response Times**
> > >
> > > Initialize processes faster in cached scenarios
> > >
> > > **2. Scalability**
> > >
> > > Handle more concurrent users with the same infrastructure
> > >
> > > **3. Cost Efficiency**
> > >
> > > Use fewer compute resources for high-volume scenarios
> >
> > Performance

> [tab] Developer Experience
>
> Enhanced tools and features for business rules development, testing, and workflow design.
>
> 🔀 [**Parallel Branches in Workflows**](#parallel-branches-in-workflows) - Design and execute parallel execution paths in Integration Designer workflows\
> 💾 [**REST API Response Caching**](#integration-designer-rest-api-response-caching) - Cache GET endpoint responses in Integration Designer with flexible TTL policies\
> 📊 [**Workflow Partitioning & Archiving**](#workflow-partitioning-&-archiving) - Manage Integration Designer workflow data efficiently with time-based partitions and automatic archiving\
> 🐍 [**Python IDE Enhancements**](#python-ide-enhancements) - Autocomplete and IntelliSense for Python business rules\
> 🧪 [**Business Rules Testing**](#functions-testing) - Save test parameters in reusable functions modal
>
> ### **Parallel branches in workflows**
>
> > [card] Parallel branches in workflows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds the ability to design and execute parallel branches in Integration Designer workflows. This enables concurrent execution of independent workflow paths and improves performance for complex integrations.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Start Parallel Node
> > > >
> > > > Split workflow execution into multiple concurrent branches with start parallel nodes
> > >
> > > > [card] End Parallel Node
> > > >
> > > > Merge parallel branches with end parallel nodes that wait for all branches to complete
> > >
> > > > [card] Path Visualization
> > > >
> > > > View which nodes belong to which parallel branch with visual path indexing in the workflow diagram
> > >
> > > > [card] Runtime Monitoring
> > > >
> > > > Track parallel path execution with timing information for each branch and merge point
> >
> > > [tab] How It Works
> > >
> > > **1. Design Parallel Paths**
> > >
> > > Add a Start Parallel node and create multiple sequences from it. Each sequence represents an independent execution path
> > >
> > > **2. Configure Branch Logic**
> > >
> > > Add workflow nodes to each parallel branch, such as API calls, transformations, or database operations
> > >
> > > **3. Merge Paths**
> > >
> > > Close parallel branches with an End Parallel node. This node waits for all branches to complete before continuing
> > >
> > > **4. Runtime Execution**
> > >
> > > All branches execute concurrently at runtime. The End Parallel node completes when the slowest branch finishes
> >
> > > [tab] Use Cases
> > >
> > > > [card] Multiple API Calls
> > > >
> > > > Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Fetch data from multiple sources in parallel for comprehensive data aggregation
> > >
> > > > [card] Notification Broadcasting
> > > >
> > > > Send notifications through multiple channels (email, SMS, push) simultaneously
> > >
> > > > [card] Document Processing
> > > >
> > > > Process different document types or sections in parallel for faster throughput
> >
> > > [tab] Runtime Behavior
> > >
> > > > [accordion] Path Timing
> > > >
> > > > * **Path Time**: Sum of all node execution times within that branch
> > > > * **End Parallel Time**: Node processing time + maximum time across all parallel paths
> > > > * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
> > >
> > > > [accordion] Console Logging
> > > >
> > > > * **Start Parallel Node**: Displays Input tab showing data split across branches
> > > > * **End Parallel Node**: Displays Output tab showing merged results from all branches
> > > > * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
> > >
> > > > [accordion] Error Handling
> > > >
> > > > * If any branch fails, the workflow handles it according to standard error handling rules
> > > > * End Parallel node waits for all non-failed branches before continuing
> > > > * Runtime validation ensures parallel branches are configured correctly
> >
> > > [tab] Limitations
> > >
> > > > [!WARNING]
> > > >
> > > > **First Iteration Constraints**: This is the initial implementation of parallel branches with the following considerations:
> > >
> > > * **Array Processing**: Arrays are not merged across parallel branches. When multiple branches modify the same array path, the last branch to complete determines the final array value. You cannot process individual objects from the same array in different parallel branches (for example, first element in branch 1, second element in branch 2). To preserve data from all branches, save to different keys and merge manually using a script before the end node
> > >
> > > * **Branch Closure**: All start parallel branches must be closed with end parallel nodes. Nodes following a start parallel node must merge into the same end parallel node, except for nodes that terminate with end workflow nodes
> > >
> > > > [!NOTE]
> > > >
> > > > Based on user feedback and raised exceptions during runtime execution, additional configuration constraints and validations are planned for future releases.
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Reduce workflow execution time by running independent operations concurrently instead of sequentially
> > >
> > > **2. Resource Utilization**
> > >
> > > Maximize throughput by executing multiple operations simultaneously
> > >
> > > **3. Design Clarity**
> > >
> > > Model concurrent operations explicitly in your workflow diagrams
> > >
> > > **4. Monitoring**
> > >
> > > Track execution time for each parallel path to identify bottlenecks
> >
> > Integration Designer
>
> ***
>
> ### **Integration Designer REST API response caching**
>
> > [card] Integration Designer REST API response caching
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces intelligent response caching for REST API GET endpoints in Integration Designer. Cache responses based on flexible Time-To-Live (TTL) policies to reduce redundant API calls, avoid rate limits, and lower operational costs while maintaining data freshness.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Endpoint_Get.png)
> > >
> > > > [!NOTE]
> > > >
> > > > When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Flexible TTL Policies
> > > >
> > > > Configure caching with "Expires after" (duration-based) or "Expires at" (time-based) policies
> > >
> > > > [card] Cache Management
> > > >
> > > > Clear cached responses from endpoint definitions or testing modals as needed
> > >
> > > > [card] Cache Status Visibility
> > > >
> > > > View cache status, keys, and TTL information in testing modals and workflow console logs
> > >
> > > > [card] Automatic Fallback
> > > >
> > > > System automatically calls the external API if cache retrieval fails, ensuring reliability
> >
> > > [tab] TTL Configuration
> > >
> > > > [accordion] Expires After (Duration-Based)
> > > >
> > > > Cache responses for a specific duration after the request is made.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **ISO Duration**: Use ISO 8601 duration format (e.g., `PT1H` for 1 hour, `P1D` for 1 day, `P1W` for 1 week)
> > > > * **Dynamic Duration**: Reference configuration parameters (e.g., `${myConfigParam}`)
> > > > * **Default**: `R/P1D` (1 day)
> > > >
> > > > **Example**: Cache for 10 minutes after each request
> > > >
> > > > ```
> > > > PT10M
> > > > ```
> > >
> > > > [accordion] Expires At (Time-Based)
> > > >
> > > > Cache responses until a specific time of day with recurring patterns.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **Expire Time**: Set specific time (e.g., `23:00` for midnight, `08:00` for 8 AM)
> > > > * **Recurrency**: Set how often the pattern repeats (integer > 0, default: 1)
> > > > * **Time Unit**: Choose Day, Week, or Month (default: Day)
> > > >
> > > > **Example**: Cache until midnight every day
> > > >
> > > > ```
> > > > Expire Time: 00:00
> > > > Recurrency: 1
> > > > Time Unit: Day
> > > > ```
> > > >
> > > > **Example**: Cache until 6 PM every Friday
> > > >
> > > > ```
> > > > Expire Time: 18:00
> > > > Recurrency: 1
> > > > Time Unit: Week
> > > > ```
> >
> > > [tab] Cache Visibility
> > >
> > > **1. Testing Modal**
> > >
> > > View cache status directly in the endpoint testing modal with:
> > >
> > > * **Cache Hit/Miss Status**: Whether results came from cache
> > > * **Cache Key**: The unique identifier for the cached response
> > > * **TTL Information**: When the cache expires (e.g., "Expires after PT10M" or "Expires at 23:00 on 2025-11-04")
> > >
> > > **2. Workflow Console**
> > >
> > > Monitor cache usage in workflow execution logs with the same detailed information
> > >
> > > **3. Clear Cache Action**
> > >
> > > Clear cached responses from the endpoint page or testing modal when cache is configured
> >
> > > [tab] How It Works
> > >
> > > **1. Configure Caching**
> > >
> > > In Integration Designer, open a REST System and navigate to a GET endpoint. Enable caching and select your TTL policy (Expires After or Expires At)
> > >
> > > **2. First Request**
> > >
> > > When the endpoint is called for the first time, the response is fetched from the external API and stored in cache with the configured TTL
> > >
> > > **3. Subsequent Requests**
> > >
> > > If the cache is still valid (within TTL), subsequent requests return the cached response immediately without calling the external API
> > >
> > > **4. Cache Expiration**
> > >
> > > Once TTL expires, the next request fetches fresh data from the external API and updates the cache
> > >
> > > **5. Cache Management**
> > >
> > > Use the "Clear Cache" action to manually invalidate cached responses when needed (e.g., after data updates)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Reference Data
> > > >
> > > > Cache country lists, product catalogs, or other reference data that rarely changes
> > >
> > > > [card] Rate Limit Avoidance
> > > >
> > > > Reduce API calls to third-party services with strict rate limits
> > >
> > > > [card] Cost Optimization
> > > >
> > > > Lower operational costs by reducing billable API calls to external services
> > >
> > > > [card] Performance
> > > >
> > > > Improve workflow execution speed by eliminating network latency for cached responses
> >
> > > [tab] Error Handling
> > >
> > > > [!WARNING]
> > > >
> > > > **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. This ensures your workflows always receive correct data.
> > >
> > > **Failure Scenarios**:
> > >
> > > * Cache service unavailable → Direct API call
> > > * Cache corruption or invalid data → Direct API call
> > > * Cache storage failure → Direct API call (with warning logged)
> > >
> > > Your workflows continue to function normally even if caching fails.
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced API Costs
> > > >
> > > > Minimize charges from external APIs by serving cached responses when data hasn't changed
> > >
> > > > [card] Improved Performance
> > > >
> > > > Return responses instantly from cache instead of waiting for external API calls
> > >
> > > > [card] Rate Limit Compliance
> > > >
> > > > Stay within API rate limits by reducing the number of requests to external services
> > >
> > > > [card] Better Scalability
> > > >
> > > > Handle higher workflow volumes without increasing external API calls
> >
> > Integration Designer
>
> > [card] [REST Endpoint Caching](../../../5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching)
> >
> > Learn how to configure caching policies, manage cache, and optimize your REST API integrations
>
> ***
>
> ### **Workflow partitioning & archiving**
>
> > [card] Workflow partitioning & archiving
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces workflow instance partitioning and archiving for Integration Designer. This feature enables efficient management of workflow data by organizing instances into time-based partitions and automatically archiving old data to maintain optimal database performance in large-scale deployments.
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow partitioning is particularly beneficial for high-volume Integration Designer workflows where instances accumulate over time, helping to maintain query performance and manage storage efficiently.
> >
> > > [tab] Key Features
> > >
> > > > [card] Time-Based Partitioning
> > > >
> > > > Organize workflow instances into partitions based on configurable time intervals (Day, Week, or Month)
> > >
> > > > [card] Automatic Archiving
> > > >
> > > > Automatically archive partitions older than the specified retention period to optimize active database size
> > >
> > > > [card] Flexible Retention Policies
> > > >
> > > > Configure how many time intervals to retain before archiving with granular control
> > >
> > > > [card] Scheduled Archiving
> > > >
> > > > Use cron expressions to schedule archiving operations at optimal times
> >
> > > [tab] Configuration
> > >
> > > Configure workflow partitioning using environment variables in Integration Designer:
> > >
> > > > [accordion] Partitioning Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ENABLED`**: Enable or disable workflow instance partitioning
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_INTERVAL`**: Time interval for creating partitions
> > > >   * Default: `MONTH`
> > > >   * Options: `DAY`, `WEEK`, `MONTH`
> > >
> > > > [accordion] Archiving Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`**: Enable or disable automatic archiving
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`**: Number of intervals to retain before archiving
> > > >   * Default: `3`
> > > >   * Options: Any positive integer
> > > >   * Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`**: Schedule for archiving operations
> > > >   * Default: `0 0 1 * * ?` (runs daily at 1:00 AM)
> > > >   * Options: Any valid cron expression
> >
> > > [tab] How It Works
> > >
> > > **1. Enable Partitioning**
> > >
> > > Set `FLOWX_DATA_PARTITIONING_ENABLED=true` to start organizing workflow instances into time-based partitions
> > >
> > > **2. Configure Partition Interval**
> > >
> > > Choose a partition interval (DAY, WEEK, or MONTH) based on your workflow volume and retention needs
> > >
> > > **3. Set Retention Policy**
> > >
> > > Define how many intervals to retain. For example, with MONTH interval and 3 retention intervals, data older than 3 months will be archived
> > >
> > > **4. Enable and Schedule Archiving**
> > >
> > > Turn on archiving and configure the cron expression to run archiving operations during low-traffic periods
> > >
> > > **5. Monitor Performance**
> > >
> > > Track database performance improvements as old partitions are archived and active data size is optimized
> >
> > > [tab] Use Cases
> > >
> > > > [card] High-Volume Workflows
> > > >
> > > > Maintain performance for Integration Designer workflows processing thousands of instances daily
> > >
> > > > [card] Compliance Requirements
> > > >
> > > > Archive historical workflow data while maintaining access to recent instances for operational needs
> > >
> > > > [card] Database Optimization
> > > >
> > > > Keep active database size manageable by automatically moving old data to archive partitions
> > >
> > > > [card] Long-Running Deployments
> > > >
> > > > Prevent database bloat in production environments running for extended periods
> >
> > > [tab] Best Practices
> > >
> > > > [!WARNING]
> > > >
> > > > **Planning and Testing Required**: Enable partitioning and archiving only after careful planning and testing. Once enabled:
> > > >
> > > > * Ensure sufficient database storage for partition management operations
> > > > * Start with archiving disabled to verify partitioning works correctly
> > > > * Test thoroughly in non-production environments before enabling in production
> > > > * Monitor database performance during initial archiving operations
> > > > * Choose partition intervals based on your workflow volume and retention requirements
> > >
> > > **Recommended Approach**:
> > >
> > > 1. Enable partitioning first without archiving
> > > 2. Monitor partition creation and database performance
> > > 3. After verifying stable operation, enable archiving
> > > 4. Schedule archiving during low-traffic periods (e.g., overnight)
> > > 5. Start with longer retention periods and adjust based on requirements
> >
> > > [tab] Benefits
> > >
> > > > [card] Improved Performance
> > > >
> > > > Maintain fast query performance as workflow instance count grows over time
> > >
> > > > [card] Efficient Storage
> > > >
> > > > Optimize database storage by archiving historical data while keeping recent data accessible
> > >
> > > > [card] Automatic Management
> > > >
> > > > Set retention policies once and let the system handle archiving automatically
> > >
> > > > [card] Scalability
> > > >
> > > > Support long-running production deployments with predictable database growth
> >
> > Integration Designer
>
> > [card] [Integration Designer Setup](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration)
> >
> > Learn how to configure workflow partitioning and archiving for Integration Designer
>
> ***
>
> ### **Python IDE enhancements**
>
> > [card] Python IDE enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds professional IDE features to Python business rules development, including autocomplete, IntelliSense, and enhanced code editing capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Autocomplete
> > > >
> > > > Get intelligent code suggestions as you type, including Python standard library and FlowX APIs
> > >
> > > > [card] IntelliSense
> > > >
> > > > Use context-aware code completion with parameter hints and documentation
> > >
> > > > [card] Syntax Highlighting
> > > >
> > > > Read code more easily with enhanced Python syntax highlighting
> > >
> > > > [card] Error Detection
> > > >
> > > > Detect syntax errors in real-time with helpful error messages
> >
> > > [tab] Benefits
> > >
> > > **1. Development Speed**
> > >
> > > Write business rules faster with intelligent code suggestions
> > >
> > > **2. Error Reduction**
> > >
> > > Catch syntax errors before deployment with real-time validation
> > >
> > > **3. API Discovery**
> > >
> > > Discover available APIs and methods through IntelliSense
> > >
> > > **4. Professional Experience**
> > >
> > > Use IDE-quality editing features directly in FlowX Designer
> >
> > Developer Tools
>
> ***
>
> ### **Functions testing**
>
> > [card] Functions testing
> >
> > > [tab] Overview
> > >
> > > Test Reusable Functions more efficiently by saving test parameters directly from the testing modal. This enables faster iteration and better test coverage.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Save Test Parameters
> > > >
> > > > Save test inputs directly from the testing modal and reuse them in future test runs
> > >
> > > > [card] Test History
> > > >
> > > > Access previously saved test parameters for regression testing
> > >
> > > > [card] Faster Iteration
> > > >
> > > > Re-test functions quickly with saved parameter sets
> > >
> > > > [card] Test Coverage
> > > >
> > > > Build a library of test cases for comprehensive function validation
> >
> > > [tab] Benefits
> > >
> > > **1. Quality**
> > >
> > > Test functions more thoroughly to improve quality
> > >
> > > **2. Time Savings**
> > >
> > > Avoid re-entering test data for each test iteration
> > >
> > > **3. Documentation**
> > >
> > > Use saved test cases as examples of how to use the function
> >
> > Testing Enhancement

> [tab] Additional Improvements
>
> Platform improvements, security updates, and bug fixes.
>
> 🌍 [**Task Management Localization**](#task-management-localization) - Comprehensive localization support with automatic table grid localization and 51 substitution tags\
> 🔧 [**Platform Enhancements**](#platform-enhancements) - Infrastructure upgrades and security improvements\
> 🐛 [**Bug Fixes**](#bug-fixes) - Resolved issues and stability improvements
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds comprehensive localization support for Task Management, enabling you to customize all user-facing text elements including table columns, filters, and actions. This allows you to deliver Task Management experiences in multiple languages:
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> >
> > > [tab] Key Features
> > >
> > > > [card] Table Grid Localization (Automatic)
> > > >
> > > > Data table components (filters, menus, pagination, data types) are automatically localized based on container app language
> > >
> > > > [card] Substitution Tags (Manual)
> > > >
> > > > Configure 51 system substitution tags in CMS to localize table columns, task actions, and UI elements
> > >
> > > > [card] Multi-language Support
> > > >
> > > > Support for 34 languages including Arabic, Chinese, Japanese, Korean, and European languages
> > >
> > > > [card] Task Action Localization
> > > >
> > > > Localize all task actions, statuses, and workflow-related text elements
> >
> > > [tab] Localization components
> > >
> > > > [accordion] Table Grid Locale Keys
> > > >
> > > > FlowX Task Management uses a comprehensive table grid localization system. These keys are **automatically applied** by FlowX.AI based on your container app language and cover all table functionality:
> > > >
> > > > * **Filters**: Set filters, text filters, number filters, date filters with all operators (equals, contains, starts with, etc.)
> > > >
> > > > * **Menus**: Column menus, context menus, aggregation functions, sorting options
> > > >
> > > > * **Pagination**: Page navigation, page size selectors, row counts
> > > >
> > > > * **Data Types**: Boolean values, dates, numbers with proper formatting
> > > >
> > > > * **Advanced Features**: Pivot mode, charting, column grouping, and row operations
> > > >
> > > > * **ARIA Labels**: Accessibility labels for screen readers and assistive technologies
> > > >
> > > > > [!NOTE]
> > > > >
> > > > > **Automatic Localization**: Table grid locale keys are automatically translated by FlowX.AI based on your container app language. No manual configuration or setup required.
> > >
> > > > [accordion] FlowX substitution tags (51 keys)
> > > >
> > > > Use these substitution tags in CMS to localize custom Task Management interface elements. All tags include English default values:
> > > >
> > > > **Search & Navigation**
> > > >
> > > > * `sys_tm_search` - "Search"
> > > >
> > > > **Table Columns**
> > > >
> > > > * `sys_tm_title` - "Title"
> > > > * `sys_tm_stage` - "Stage"
> > > > * `sys_tm_assignee` - "Assignee"
> > > > * `sys_tm_status` - "Status"
> > > > * `sys_tm_priority` - "Priority"
> > > > * `sys_tm_last_updated` - "Last updated"
> > > >
> > > > **Process States (Status Values)**
> > > >
> > > > * `sys_tm_created` - "Created"
> > > > * `sys_tm_started` - "Started"
> > > > * `sys_tm_finished` - "Finished"
> > > > * `sys_tm_finished_with_error` - "Finished with error"
> > > > * `sys_tm_failed` - "Failed"
> > > > * `sys_tm_expired` - "Expired"
> > > > * `sys_tm_aborted` - "Aborted"
> > > > * `sys_tm_terminated` - "Terminated"
> > > > * `sys_tm_dismissed` - "Dismissed"
> > > > * `sys_tm_on_hold` - "On hold"
> > > >
> > > > **Bulk Actions**
> > > >
> > > > * `sys_tm_assign_to` - "Assign to…"
> > > > * `sys_tm_unassign_all` - "Unassign All"
> > > > * `sys_tm_assign_all_to_me` - "Assign All to me"
> > > > * `sys_tm_hold_all` - "Hold All"
> > > > * `sys_tm_unhold_all` - "Unhold All"
> > > >
> > > > **Task Actions**
> > > >
> > > > * `sys_tm_view_application` - "View Application"
> > > > * `sys_tm_unassign` - "Unassign"
> > > > * `sys_tm_assign_to_myself` - "Assign to myself"
> > > > * `sys_tm_unhold` - "Unhold"
> > > > * `sys_tm_hold` - "Hold"
> > > > * `sys_tm_assign` - "Assign"
> > > > * `sys_tm_execute` - "Execute"
> > > > * `sys_tm_start` - "Start"
> > > >
> > > > **Task Details Sections**
> > > >
> > > > * `sys_tm_assignee_deactivated` - "(Deactivated)"
> > > > * `sys_tm_comments` - "Comments"
> > > > * `sys_tm_write_a_comment` - "Write a comment…"
> > > > * `sys_tm_history` - "History"
> > > >
> > > > **History Events**
> > > >
> > > > * `sys_tm_task_created` - "Task created"
> > > > * `sys_tm_user_created_this_task` - "`${user}` created this task"
> > > > * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
> > > > * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
> > > > * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
> > > > * `sys_tm_task_moved_to` - "Task moved to"
> > > > * `sys_tm_task_status_changed_to` - "Task status changed to"
> > > > * `sys_tm_task_assigned_to` - "Task assigned to"
> > > > * `sys_tm_task_owner_removed` - "Task owner removed"
> > > >
> > > > **User Selection & Search**
> > > >
> > > > * `sys_tm_select_person` - "Select person..."
> > > > * `sys_tm_search_person` - "Search users"
> > > > * `sys_tm_search_term_validation` - "Type at least 4 characters..."
> > > >
> > > > **UI States**
> > > >
> > > > * `sys_tm_loading` - "Loading..."
> > > > * `sys_tm_nothing_found` - "Nothing Found"
> > > >
> > > > **Data Display**
> > > >
> > > > * `sys_tm_in` - "In" (custom filter operator)
> > > >
> > > > * `sys_tm_yes` - "Yes" (boolean value)
> > > >
> > > > * `sys_tm_no` - "No" (boolean value)
> > > >
> > > > > [!WARNING]
> > > > >
> > > > > **\*\*Manual Configuration Required**: These 51 FlowX substitution tags must be configured manually in CMS for each language. They control custom Task Management UI elements outside of the data table.
> >
> > > [tab] Implementation
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization (300+ keys for filters, menus, pagination, data types) based on this setting
> > >
> > > **2. Configure FlowX Substitution Tags in CMS**
> > >
> > > Add translations for all 51 FlowX substitution tags (sys\_tm\_\*) in CMS for each supported language. These control custom Task Management UI elements (task actions, bulk operations, history events, comments)
> > >
> > > **3. Configure Custom Column Names (Optional)**
> > >
> > > If you need custom columns beyond the defaults, use substitution tags for column display names in your Task Management configuration
> > >
> > > **4. Test Localization**
> > >
> > > Verify complete localization:
> > >
> > > * **Table grid elements** (automatic): filters, sorting, pagination, menus should display in container app language
> > >
> > > * **FlowX custom elements** (CMS): task actions, bulk operations, history events, comments should use your CMS translations
> > >
> > > > [!NOTE]
> > > >
> > > > **Simple Setup**: Configure only the 51 FlowX substitution tags in CMS. Table grid localization (300+ keys) is handled automatically by the platform.
> >
> > > [tab] Benefits
> > >
> > > > [card] Global Reach
> > > >
> > > > Deploy Task Management to users worldwide with native language support
> > >
> > > > [card] Consistent Experience
> > > >
> > > > Provide a fully localized experience across all Task Management components
> > >
> > > > [card] Easy Maintenance
> > > >
> > > > Manage translations centrally through CMS substitution tags
> > >
> > > > [card] Professional Quality
> > > >
> > > > Leverage professional translations for data grid components with automatic localization
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> > [card] [Task Management Overview](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
> >
> > Learn about Task Management features and configuration
>
> > [card] [Process Settings](../../../5.1/docs/building-blocks/process/process-definition#integrate-with-task-manager)
> >
> > Configure Task Management integration in process settings
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform Enhancements
> >
> > FlowX.AI 5.2.0 includes platform improvements focused on security, stability, and infrastructure.
> >
> > ## Security & Infrastructure Updates
> >
> > > [card] Vulnerability Fixes
> > >
> > > Update Java libraries and base images to address security vulnerabilities
> >
> > > [card] SpiceDB Upgrade
> > >
> > > Upgrade SpiceDB with new operator version
> >
> > > [card] Dependency Updates
> > >
> > > Update platform dependencies to latest secure versions
> >
> > ## Additional improvements
> >
> > > [card] Permission-based UI
> > >
> > > Add permission-based UI functionality in Reusable UI Templates
> >
> > > [card] Database Query Improvements
> > >
> > > Improve FlowX Database query handling and error messages
> >
> > > [card] System Substitution Tags
> > >
> > > Use system substitution tags in task management texts in CMS
> >
> > > [card] SSE Disconnect Handling
> > >
> > > Handle Server-Sent Events disconnections better to reduce log noise
> >
> > > [card] [Integration Designer Environment Variables](./update-environment-variables-5.2)
> > >
> > > Update environment variables for improved advancing controller with separate picking and processing operations, see details [here](./update-environment-variables-5.2)
> >
> > Platform Updates
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes & stability improvements
> >
> > FlowX.AI 5.2.0 includes bug fixes and stability improvements to improve the overall user experience.
> >
> > ## Notable fixes
> >
> > > [accordion] Fixes
> > >
> > > * **Process Instances Page**: Fix error when opening Runtime process instances page
> > > * **Resource Import**: Fix import requests that use incorrect content type
> > > * **Elasticsearch Updates**: Fix engine errors when updating documents in older indexes
> > > * **Navigation Tree**: Fix navigation tree response for overridden processes
> > > * **Dependency Management**: Fix errors when updating library dependency versions
> >
> > > [accordion] UI/UX fixes
> > >
> > > * **Accessibility**: Fix missing accessibility sections on various components
> > > * **Theme Configuration**: Fix element selection issues in segmented button panel
> > > * **Modal Behavior**: Improve modal focus management and keyboard navigation
> > > * **Select Components**: Fix highlighting and navigation issues in select/multiselect
> > > * **Task Manager**: Fix browser freeze when opening table configuration
> >
> > > [accordion] Renderer fixes
> > >
> > > * **Angular SDK**: Fix keyboard navigation issues with select components and shift+tab behavior
> > > * **React SDK**: Fix option highlighting and keyboard navigation in various components
> > > * **Workflow Display**: Fix rendering issues in Integration Designer workflows
> > > * **Collection Components**: Fix card expansion issues with accordions in navigation areas
> >
> > > [accordion] Backend fixes
> > >
> > > * **Events Gateway**: Improve SSE disconnect handling to reduce error log flooding
> > > * **Database Operations**: Improve error handling and validation for FlowX Database queries
> > > * **Process Navigation**: Fix back button redirects from process definitions
> > > * **Warning Management**: Clean up warnings properly when deleting parent actions

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.2.0](./deployment-guidelines-v5.2).
>
> ### Environment variables updates
>
> > [!NOTE]
> >
> > For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
>
> ### Coming soon
>
> Additional features currently in development for future releases:
>
> * Extended accessibility support for iOS and Android platforms
> * Additional Python IDE capabilities
> * Enhanced FlowX Database query preview and optimization tools


# Deployment guidelines v5.3.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/deployment-guidelines-v5.3

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.29.0** | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 |
| **admin** | **10.26.1** | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 |
| **designer** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **cms-core** | **10.16.0** | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 |
| **scheduler-core** | **10.11.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **events-gateway** | **10.12.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **notification-plugin** | **10.17.0** | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **document-plugin** | **10.16.0** | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 |
| **task-management-plugin** | **10.18.0** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 |
| **data-search** | **10.10.1** | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 |
| **audit-core** | **10.15.1** | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **advancing-controller** | **10.11.0** | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 |
| **integration-designer** | **10.24.0** | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 |
| **application-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **runtime-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **data-sync** | **10.14.1** | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 |
| **authorization-system** | **10.18.1** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - |
| **nosql-db-runner** | **10.10.1** | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **iOS renderer** | **10.1.0** | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 |
| **Android renderer** | **10.1.0** | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 |

### Plugins

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.1** | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 |
| **di-platform** | **10.2.5** | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 |
| **ai-platform-ai-developer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-connected-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agents** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-conversations** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-models** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-tenants** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-planner** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-analyst** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-designer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agent-builder** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-binaries** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.3.0 | Keycloak | 26+ |
| 5.3.0 | Kafka | 3.8 - 3.9 |
| 5.3.0 | PostgreSQL | 16 - 17 |
| 5.3.0 | Oracle Database | 21c, 23ai |
| 5.3.0 | MongoDB | 7 - 8 |
| 5.3.0 | Redis | 7.4 - 8.0 |
| 5.3.0 | Elasticsearch | 8 |
| 5.3.0 | Angular (Web SDK) | 19.2 |
| 5.3.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.3.0

### Key features and updates

> [card] UI Flows
>
> Build multi-platform applications with reusable UI components across web, iOS, and Android

> [card] UI Events
>
> Real-time user interaction handling with event-driven UI components

> [card] Workflow Data Models
>
> Workflow-level data models with input/output parameters and process-to-workflow data mapping

> [card] Mobile Accessibility
>
> WCAG 2.1 accessibility compliance extended to iOS and Android platforms

> [card] Custom Component Enhancements
>
> Standardized custom component integration across all platforms

> [card] SaaS Capabilities
>
> Multi-tenant SaaS capabilities with organization management

## Upgrading from v5.2.0

### Breaking changes

> [!WARNING]
>
> **FlowX Engine Configuration Changes**: The partitioning and archiving configuration structure has been reorganized. If you have enabled data partitioning, you **must** update your configuration files before or immediately after upgrading.

> [card] [Complete migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
>
> See the detailed migration guide with step-by-step instructions, configuration examples, and troubleshooting

### Key changes

* **UI Flows**: New feature for building multi-platform reusable UI components
* **Workflow Data Models**: Enhanced integration between processes and workflows with structured data models
* **Mobile Accessibility**: iOS and Android renderers now support WCAG 2.1 accessibility standards
* **Configuration Structure**: Breaking change in FlowX Engine partitioning/archiving configuration (see preceding section)

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.

### Compatibility

* **Breaking Changes**: FlowX Engine partitioning/archiving configuration structure has changed (action required if using partitioning)
* **Feature Additions**: UI Flows, UI Events, and Workflow Data Models are new features with no breaking changes
* **Renderer Updates**: Web and mobile SDKs include new features with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/migration-overview

Migration guide for upgrading from FlowX.AI v5.2.0 to v5.3.0

> [!NOTE]
>
> FlowX.AI v5.3.0 is an incremental update from v5.2.0 with one breaking change related to FlowX Engine configuration structure.

## What's changing

FlowX.AI v5.3.0 introduces a breaking change to the FlowX Engine partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings have been reorganized under `partitioning.archiving`.

## Who is affected

> [!WARNING]
>
> This breaking change **only affects** deployments that have:
>
> * Enabled data partitioning in FlowX Engine (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings (`SCHEDULER_DATAPARTITIONING_ENABLED=true`)
>
> If you have not enabled these features, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

## Migration process

**1. Review configuration changes**

Understand the new configuration structure and identify which settings need to be updated in your deployment

**2. Update configuration files**

Update your FlowX Engine configuration files (YAML or environment variables) following the migration steps

**3. Deploy and verify**

Deploy the updated configuration and verify that partitioning and archiving continue to work correctly

## Key changes summary

### Configuration structure

**What's removed:**

* `scheduler.dataPartitioning` section with `enabled` and `cronExpression` settings

**What's added:**

* `partitioning.archiving` subsection containing all archiving-related settings

**What's moved:**

* `retention-intervals` moved from `partitioning` to `partitioning.archiving`
* `detached-partition-compression` moved to `partitioning.archiving`
* `moved-data-batch-size` moved to `partitioning.archiving`
* `cronExpression` moved from `scheduler.dataPartitioning` to `partitioning.archiving`

### Environment variables

5 environment variables have been renamed to reflect the new structure:

| Old Variable | New Variable |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` |

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility**: The old configuration structure is not supported in v5.3.0 and causes FlowX Engine startup errors.
>
> You must update your configuration before or immediately after upgrading to v5.3.0.

## Rollback support

If you need to rollback from v5.3.0 to v5.2.x:

1. Revert your configuration files to the previous structure
2. Restore environment variables to their previous names
3. Downgrade the FlowX Engine container/pod to the previous version

> [!NOTE]
>
> Database schema changes are forward-compatible. Ensure you have database backups before any upgrade.

> [!NOTE]
>
> This is a configuration-only change. No code changes, data migration, or schema updates are required.

## Next steps

## Additional resources

> [card] [Partitioning & Archiving Setup](/5.1/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving)
>
> Complete guide to FlowX Engine partitioning and archiving

> [card] [Deployment Guidelines v5.3.0](../deployment-guidelines-v5.3)
>
> Component versions and deployment instructions

> [card] [Release Notes v5.3.0](../v5.3.0-december-2025)
>
> Full release notes for v5.3.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/update-environment-variables-5.3

Update environment variables for all existing FlowX.AI services

## FlowX Engine

### Partitioning and archiving configuration restructure

> [!NOTE]
>
> FlowX.AI v5.3.0 reorganizes the partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings are now under `partitioning.archiving`.

#### Variables to remove

If you are using environment variables to override FlowX Engine configuration, remove these variables:

| Remove This Variable | Reason |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |

#### Variables to replace

| Old Variable Name | New Variable Name | Default Value | Description |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of partition intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression level for archived partitions (Oracle only): `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for moving data during archiving (PostgreSQL only) |

#### New variables structure

The archiving configuration is now nested under `partitioning.archiving`:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Turn on or off data partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Partition interval: `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Turn on or off automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Schedule expression for archiving operations (default: daily at 1:00 AM) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression for archived partitions (Oracle only) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for data movement (PostgreSQL only) |

> [!NOTE]
>
> **Configuration structure changes:**
>
> * **Removed**: `scheduler.dataPartitioning` section
> * **Added**: `partitioning.archiving` subsection with all archiving-related settings
> * **Unchanged**: Core partitioning settings (`enabled`, `interval`) remain at `partitioning` level
> * **Moved**: Archiving-specific settings (`retention-intervals`, `cronExpression`, `detached-partition-compression`, `moved-data-batch-size`) are now under `partitioning.archiving`

> [!WARNING]
>
> **Action required if using partitioning:**
>
> If you have enabled data partitioning in FlowX Engine, you **must** update your configuration:
>
> 1. **YAML configuration**: Update your `application.yml` to follow the new structure (see [Deployment Guidelines](../deployment-guidelines-v5.3#breaking-changes))
> 2. **Environment variables**: Update variable names as shown in the tables above
> 3. **Deployment order**: Update configuration before or immediately after upgrading to v5.3.0

#### Configuration examples

> [tab] Environment Variables (Before)
>
> ```bash theme={"dark"}
> # Old structure (v5.2 and earlier)
> SCHEDULER_DATAPARTITIONING_ENABLED=true
> SCHEDULER_DATAPARTITIONING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS=3
> FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [tab] Environment Variables (After)
>
> ```bash theme={"dark"}
> # New structure (v5.3.0)
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true
> FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS=3
> FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [!NOTE]
>
> **Impact assessment:**
>
> This change only affects deployments that have:
>
> * Enabled data partitioning (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings
>
> If partitioning is disabled, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

### New optional variables

| Variable | Default Value | Description |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Falls back to `KAFKA_TOPIC_PATTERN` if not set | Dedicated topic pattern for FlowX connectors, separate from other platform components like document-plugin, data-search, and cms-core |

> [!NOTE]
>
> The `KAFKA_TOPIC_CONNECTOR_PATTERN` variable allows you to configure a custom Kafka topic pattern specifically for FlowX connectors without affecting other platform components.

> [card] [Complete migration guide](migration-overview)
>
> See the Deployment Guidelines for complete configuration examples, step-by-step migration instructions, and troubleshooting guidance.


# FlowX.AI 5.3.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025

UI Flows for multi-platform app building, UI Events for real-time interactions, enhanced custom component integration, and mobile accessibility improvements.

**What's new?**

> [tab] App builder & reusability
>
> Build multi-platform applications faster with UI Flows, enhance real-time interactions with UI Events, and integrate custom components across all platforms.
>
> 📱 [**UI Flows**](#ui-flows) - Build multi-platform applications with reusable UI components across web, iOS, and Android\
> ⚡  [**UI Events**](#ui-events) - Real-time user interaction handling with event-driven UI components\
> 🧩 [**Custom Component Enhancements**](#custom-component-enhancements) - Enhanced integration for custom components with standardized data mapping\
> 📤 [**File Upload Improvements**](#file-upload-improvements) - Enhanced file upload experience with better loading states and user feedback\
> ♿ [**Mobile Accessibility**](#mobile-accessibility) - WCAG 2.1 accessibility compliance for iOS and Android platforms\
> 🏢 [**Cross Workspace Projects**](#cross-workspace-projects) - Share projects across multiple workspaces for flexible environment testing\
> 🎯 [**Collection & Table Actions**](#collection-and-table-actions) - Execute actions from collections and tables in UI Flows
>
> ### **UI flows**
>
> > [card] UI flows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Flows, a powerful new capability that enables you to build reusable, multi-platform user interfaces that work across web (Angular/React), iOS, and Android applications. UI Flows separate UI definitions from process logic, enabling better reusability and faster application development without the overhead of full BPMN processes.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flows revolutionize how you build applications by allowing you to create a UI once and deploy it across all platforms, dramatically reducing development time and ensuring consistent user experiences.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Unnecessary process complexity
> > > >
> > > > Some use cases do not need a mapping of the business case in BPMN and the complexity and overhead that a FlowX process entails
> > >
> > > > [card] Subprocess overhead
> > > >
> > > > Unnecessary subprocess layers inside processes added complexity for simple UI scenarios
> > >
> > > > [card] Tight UI-process coupling
> > > >
> > > > UI definitions were tightly coupled to process logic, reducing reusability and increasing maintenance
> > >
> > > > [card] Platform-specific development
> > > >
> > > > Building the same UI for multiple platforms required separate implementations for each platform
> >
> > > [tab] Key Features
> > >
> > > > [card] UI Flows as project resources
> > > >
> > > > UI Flows are managed as independent project resources, separate from process definitions
> > >
> > > > [card] Navigation areas management
> > > >
> > > > Manage Navigation Areas inside UI Flows Designer for structured navigation and layout
> > >
> > > > [card] Start process UI action
> > > >
> > > > Launch FlowX processes directly from UI Flows, bridging UI and process execution
> > >
> > > > [card] Navigate to UI action
> > > >
> > > > Setup navigation to Nav areas or Container elements through scroll for seamless UX
> > >
> > > > [card] Task Manager component
> > > >
> > > > Embed Task Manager as a UI Component in UI Flows for task management capabilities
> > >
> > > > [card] Multi-platform support
> > > >
> > > > Create UI once and deploy to web (Angular/React), iOS, and Android with platform-specific configurations
> > >
> > > > [card] Import/export
> > > >
> > > > Export UI Flows as portable packages and import them across environments and applications
> > >
> > > > [card] Platform selection
> > > >
> > > > Configure platform-specific behaviors and overrides for web, iOS, and Android in the UI Flows designer
> > >
> > > > [card] Home page support
> > > >
> > > > Create UI Flows with dedicated home pages and home navigation icons for better UX
> >
> > > [tab] How It Works
> > >
> > > **1. Create UI flow**
> > >
> > > Create a UI Flow as a project resource in FlowX Designer, separate from process definitions
> > >
> > > **2. Design navigation**
> > >
> > > Manage Navigation Areas inside UI Flows Designer, defining pages and navigation structure
> > >
> > > **3. Add components**
> > >
> > > Add UI components including Task Manager, forms, custom components, and other UI elements
> > >
> > > **4. Configure actions**
> > >
> > > Setup UI Actions like Start Process (to launch processes) and Navigate To (for Nav areas or container scrolling)
> > >
> > > **5. Configure platforms**
> > >
> > > Set platform-specific configurations using the platform selection subheader (Web, iOS, Android)
> > >
> > > **6. Set home page**
> > >
> > > Designate a page as the home page with automatic home icon navigation support
> > >
> > > **7. Export & reuse**
> > >
> > > Export your UI Flow and import it into other applications or environments for maximum reusability
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced complexity
> > > >
> > > > Build UIs without the overhead of BPMN processes for use cases that don't require business process mapping
> > >
> > > > [card] Faster development
> > > >
> > > > Build UI once instead of creating separate interfaces for each platform
> > >
> > > > [card] Flexible architecture
> > > >
> > > > Eliminate unnecessary subprocess layers - use UI Flows for simple scenarios and processes for complex business logic
> > >
> > > > [card] Consistent UX
> > > >
> > > > Ensure identical user experiences across web, iOS, and Android applications
> > >
> > > > [card] Reusability
> > > >
> > > > Share UI Flows across multiple applications and projects
> > >
> > > > [card] Process integration
> > > >
> > > > Launch processes from UI Flows when needed, maintaining clean separation of concerns
> > >
> > > > [card] Maintainability
> > > >
> > > > Update UI in one place and propagate changes across all platforms
> > >
> > > > [card] Enhanced navigation
> > > >
> > > > Rich navigation capabilities with Nav areas, container scrolling, and Task Manager integration
> >
> > > [tab] Use Cases
> > >
> > > **When to Use UI Flows vs Processes:**
> > >
> > > **Use UI Flows for:**
> > >
> > > * **Information Display**: Dashboards, reports, and static content that doesn't require process orchestration
> > > * **Task Management**: Task lists and task management interfaces with embedded Task Manager component
> > > * **Navigation Shells**: Application navigation structures and home pages
> > > * **Form Collections**: Data entry forms that start processes but don't need their own process context
> > > * **Multi-Platform Apps**: Applications that need consistent UI across web and mobile platforms
> > >
> > > **Use Processes for:**
> > >
> > > * **Business Logic**: Complex workflows with business rules, approvals, and integrations
> > > * **State Management**: Applications requiring process state tracking and persistence
> > > * **Orchestration**: Multi-step operations with decision points and parallel execution
> > >
> > > **Combine Both:**
> > >
> > > Create UI Flows as the main application shell and use Start Process UI Actions to launch business processes when needed, keeping your architecture clean and maintainable.
> >
> > > [card] [UI Flows Documentation](/5.9/docs/building-blocks/ui-flows)
> > >
> > > Complete guide to creating and configuring UI Flows, including navigation management, UI actions, and platform considerations.
> >
> > Major Feature
>
> ***
>
> ### **UI events**
>
> > [card] UI events
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Events, enabling real-time interaction handling directly within Reusable UI Templates. UI Events allow you to capture user interactions like button clicks, form changes, or custom events and respond immediately without process execution, providing responsive and dynamic user experiences.
> >
> > > [tab] Key Features
> > >
> > > > [card] Event configuration
> > > >
> > > > Configure UI Events in UI Designer with custom event types and handling logic
> > >
> > > > [card] Cross-platform support
> > > >
> > > > UI Events work consistently across Angular, React, iOS, and Android renderers
> > >
> > > > [card] Runtime mapping
> > > >
> > > > UI Event results are mapped automatically in Reusable UI Template instances at runtime
> > >
> > > > [card] Design-time testing
> > > >
> > > > Test UI Events directly in UI Designer before deploying to runtime
> >
> > > [tab] Use Cases
> > >
> > > > [card] Form validation
> > > >
> > > > Validate form inputs in real-time as users type, providing immediate feedback
> > >
> > > > [card] Dynamic UI updates
> > > >
> > > > Show/hide fields, update options, or change UI state based on user interactions
> > >
> > > > [card] Client-side logic
> > > >
> > > > Execute lightweight client-side logic without triggering backend processes
> > >
> > > > [card] Responsive interactions
> > > >
> > > > Create highly responsive UI behaviors like autocomplete, live search, or conditional displays
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Handle UI interactions instantly without waiting for backend process execution
> > >
> > > **2. User experience**
> > >
> > > Provide immediate visual feedback and responsive interactions
> > >
> > > **3. Reduced complexity**
> > >
> > > Simplify process logic by handling UI-specific interactions at the component level
> >
> > UX Enhancement
>
> ***
>
> ### **Custom component enhancements**
>
> > [card] Custom component enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 standardizes custom component integration across all platforms (Angular, React, iOS, Android) with unified data mapping for input keys, data binding, save operations, and action handling. This provides a consistent developer experience when building custom components.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified data mapping
> > > >
> > > > Standard data, saveData, and action body mapping across all platforms
> > >
> > > > [card] Input key mapping
> > > >
> > > > Consistent input key handling for passing configuration and data to custom components
> > >
> > > > [card] Platform parity
> > > >
> > > > Identical custom component APIs across Angular, React, iOS, and Android
> > >
> > > > [card] Action integration
> > > >
> > > > Integration with FlowX actions for triggering backend operations
> >
> > > [tab] Benefits
> > >
> > > **1. Developer productivity**
> > >
> > > Build custom components once with knowledge that applies across all platforms
> > >
> > > **2. Code reusability**
> > >
> > > Share component logic and patterns across web and mobile implementations
> > >
> > > **3. Consistency**
> > >
> > > Ensure consistent behavior and data handling across all platforms
> >
> > Developer Experience
>
> ***
>
> ### **File upload improvements**
>
> > [card] File upload improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the file upload experience across all platforms with improved loading states, better user feedback, and more flexible configuration options. These improvements provide clearer status communication during file upload operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Enhanced loading behavior
> > > >
> > > > Configure loading behavior with optional overlay loader and custom loading messages
> > >
> > > > [card] Toast notifications
> > > >
> > > > Success and error messages displayed as toasts with customizable messages
> > >
> > > > [card] Dynamic messages
> > > >
> > > > Display dynamic key values in toast and loading messages for context-aware feedback
> > >
> > > > [card] Generic loader design
> > > >
> > > > Updated loader designs across Angular, React, iOS, and Android for consistent theming
> >
> > > [tab] Configuration
> > >
> > > **Loading Behavior Options:**
> > >
> > > * **NONE**: No loading overlay displayed during upload
> > > * **OVERLAY**: Full-screen overlay with spinner and optional loading message
> > >
> > > **Toast Notifications:**
> > >
> > > * **Success Toast**: Toggle to show success message when upload completes (auto-dismiss after 3-5 seconds)
> > > * **Error Toast**: Toggle to show error message when upload fails (auto-dismiss after 3-5 seconds)
> > > * **Custom Messages**: Configure success and error messages with dynamic substitutions
> > >
> > > **Theming Support:**
> > >
> > > * Apply custom themes to loaders and toast messages
> > > * Configure colors, sizes, and styling to match your brand
> > > * Consistent visual language across platforms
> >
> > UX Enhancement
>
> ***
>
> ### **Mobile accessibility**
>
> > [card] Mobile accessibility
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 extends WCAG 2.1 accessibility compliance to iOS and Android platforms, allowing you to configure accessibility properties directly from UI Designer and ensuring your mobile applications are accessible to all users.
> >
> > > [tab] Key Features
> > >
> > > > [card] iOS accessibility
> > > >
> > > > Configure labels, hints, traits, and accessibility properties for iOS components
> > >
> > > > [card] Android accessibility
> > > >
> > > > Set content descriptions and accessibility properties for Android components
> > >
> > > > [card] Designer integration
> > > >
> > > > Configure all accessibility properties from UI Designer without code changes
> > >
> > > > [card] Platform-specific options
> > > >
> > > > Set platform-specific accessibility configurations for optimal native experience
> >
> > > [tab] Benefits
> > >
> > > > [card] Inclusive mobile apps
> > > >
> > > > Make your mobile applications accessible to users with disabilities
> > >
> > > > [card] Regulatory compliance
> > > >
> > > > Meet mobile accessibility requirements for government, healthcare, and financial sectors
> > >
> > > > [card] Better UX
> > > >
> > > > Accessibility improvements benefit all users, not just those using assistive technologies
> > >
> > > > [card] Unified configuration
> > > >
> > > > Configure accessibility for all platforms from a single Designer interface
> >
> > Accessibility
>
> ***
>
> ### **Cross workspace projects**
>
> > [card] Cross workspace projects
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 removes the restriction that prevented importing the same project into multiple workspaces within the same environment. This enables organizations to use workspaces to represent different upper environments (UAT, Staging) for testing and development.
> > >
> > > > [!NOTE]
> > > >
> > > > A single project (identified by its UUID) can now exist independently across workspaces, each with its own lifecycle: separate active policies, configurations, and access controls.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Environment testing restrictions
> > > >
> > > > Organizations could not use workspaces on the same FlowX deployment to represent different upper environments for testing (e.g. UAT, Staging)
> > >
> > > > [card] Operational costs
> > > >
> > > > This feature is intended to allow organizations to use workspace functionality to emulate different environments and reduce operational costs.
> >
> > > [tab] Solution
> > >
> > > **What Changed:**
> > >
> > > **1. Restriction removed**
> > >
> > > The system now allows importing the same project (identified by UUID) into multiple workspaces within the same environment
> > >
> > > **2. Independent lifecycles**
> > >
> > > Each project instance in different workspaces maintains its own independent lifecycle with separate active policies, configurations, and access controls
> > >
> > > **3. Workspace isolation**
> > >
> > > Changes in one workspace do not affect the same project in other workspaces, ensuring proper isolation
> >
> > > [tab] How It Works
> > >
> > > **Import Behavior:**
> > >
> > > | Aspect | Behavior |
> > > | - | - |
> > > | **Import** | Import a project build (and optionally a version) into a different workspace on the same environment |
> > > | **Active Policy** | The imported build is automatically set as the active policy, regardless of what was active in the original workspace |
> > > | **User Access** | Workspace users must be granted appropriate project rights (e.g., project viewer) to interact with the imported project |
> > > | **Process Instances** | Workspace-specific; imported projects start with no instances until processes run in the new workspace |
> > > | **Database** | Projects across workspaces on the same environment share the same database |
> > > | **No Impact on Original** | Import does not affect the original project's settings, policies, information, or process instances |
> > >
> > > > [!WARNING]
> > > >
> > > > Only the build itself is transferred during cross-workspace import. Configuration and access controls are defined separately in each workspace.
> >
> > > [tab] Benefits
> > >
> > > > [card] Flexible testing environments
> > > >
> > > > Use workspaces to represent UAT, Staging, and other test environments on the same deployment
> > >
> > > > [card] Reduced costs
> > > >
> > > > Eliminate the need for additional deployments and DevOps resources for environment management
> > >
> > > > [card] Better organization
> > > >
> > > > Organize projects and environments more efficiently with workspace-based separation
> > >
> > > > [card] Independent control
> > > >
> > > > Maintain separate policies and configurations for each workspace while using the same project
> > >
> > > > [card] Simplified operations
> > > >
> > > > Streamline deployment and environment management workflows
> > >
> > > > [card] Faster environment setup
> > > >
> > > > Quickly create new test environments by importing existing projects into new workspaces
> >
> > > [tab] Use Cases
> > >
> > > **Example Scenarios:**
> > >
> > > 1. **Multi-Environment Testing**: Import the same project into UAT and Staging workspaces, each with different test data and configurations
> > >
> > > 2. **Development Lifecycle**: Maintain development, integration, and pre-production environments as separate workspaces with the same project
> > >
> > > 3. **Parallel Testing**: Run multiple test scenarios simultaneously by creating separate workspaces for each testing team
> > >
> > > 4. **Isolated Training Environments**: Create dedicated workspaces for training and demos while keeping production separate
> >
> > > [card] [Workspaces Documentation](/5.1/docs/projects/workspaces#cross-workspace-project-import)
> > >
> > > Complete guide to cross-workspace project import, including import behavior and best practices.
> >
> > Reusability Enhancement
>
> ***
>
> ### **Collection and table actions**
>
> > [card] Collection and table actions
> >
> > FlowX.AI 5.3 enables executing actions directly from collection and table rows within UI Flows across Angular and React platforms, providing contextual user interactions within data-driven UI Flow components.
> >
> > > [card] Row-level actions
> > >
> > > Configure and trigger actions with row context for edit, delete, or start process operations in UI Flows
> >
> > > [card] Cross-platform support
> > >
> > > Works in both Angular and React web renderers for UI Flows
> >
> > UI Flows
>
> ***

> [tab] Integration & data
>
> Enhanced workflow integration, data model management, and backend performance improvements.
>
> 🔄 [**Data mappers for workflow integration**](#data-mappers-for-workflow-integration) - Data mappers for workflow integration\
> 🗄️ [**Workflow data model**](#workflow-data-model) - New CRUD endpoints and runtime data model access\
> 🤖 [**MCP Integration**](#mcp-integration) - Connect AI agents with external tools and services through Model Context Protocol servers\
> 🤖 [**Custom Agent Nodes**](#custom-agent-nodes) - Custom Agent nodes for AI agents to use external tools and services
> 📚 [**Knowledge Base**](#knowledge-base) - Create and manage Knowledge Bases for AI agents with document ingestion and semantic search\
> 🔧 [**Update process variables**](#update-process-variables) - Operations teams can modify process variables on active instances to resolve production issues\
> 🔍 [**Token view improvements**](#token-view-improvements) - Enhanced token hierarchy visibility with horizontal scrolling, frozen columns, and context-aware columns\
> 🛡️ [**Access management enhancements**](#access-management-enhancements) - New operations editor role and granular workspace permissions\
> ⚡ [**Performance & stability**](#performance-and-stability) - Backend optimizations, caching improvements, and infrastructure updates\
> 🔀 [**Exclusive Gateways**](#exclusive-gateways) - Expression testing and validation improvements
>
> ### **Data mappers for workflow integration**
>
> > [card] Data mappers for workflow integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces data mappers that enable integration between processes and Integration Designer workflows. Similar to Process Definitions, you can now define structured data models at the workflow level with input and output parameters, ensuring consistent data lineage across your integration architecture.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
> > >
> > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process-workflow.png)
> > >
> > > Map data bidirectionally between processes and workflows using data mappers
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow Data Models provide the same structured data management capabilities as Process Data Models, enabling declarative data mapping between workflows and processes with full type safety and validation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow data model
> > > >
> > > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > > [card] Input parameter management
> > > >
> > > > Input parameters automatically pre-fill Start Nodes with structured data from the workflow data model
> > >
> > > > [card] Data parameters
> > > >
> > > > Use data parameters to define input and output data subsets for workflow operations
> > >
> > > > [card] Process ↔ workflow mapping
> > > >
> > > > Create data mappers on nodes to receive outputs from workflows and map data bidirectionally
> > >
> > > > [card] Generic CRUD endpoints
> > > >
> > > > Manage data models, entities, attributes, and data parameters programmatically via REST APIs
> > >
> > > > [card] Unique node validation
> > > >
> > > > Automatic node name uniqueness validation within workflow definitions to ensure clear data lineage
> >
> > > [tab] How It Works
> > >
> > > **1. Define workflow data model**
> > >
> > > Create a data model for your workflow with entities and attributes, similar to Process Data Models. Define which parameters are inputs and outputs
> > >
> > > **2. Configure input parameters**
> > >
> > > Input parameters automatically pre-fill the Start Node when you open the workflow diagram or test at runtime. No manual JSON editing required
> > >
> > > **3. Map process to workflow**
> > >
> > > When invoking a workflow from a process, create data mappers to map process data to workflow input parameters
> > >
> > > **4. Map workflow to process**
> > >
> > > Configure output mappings on nodes to receive workflow results and map them back to process data
> >
> > > [tab] Data Model Management
> > >
> > > **New API Capabilities:**
> > >
> > > * **Data Model CRUD**: Create, read, update, and delete workflow data models
> > > * **Entity Management**: Add, modify, and remove entities within data models
> > > * **Attribute Management**: Define and manage attributes with types and validation rules
> > > * **Data Parameters Operations**: Create input and output data parameters for workflows
> > > * **Usage Tracking**: Query references and usages for attributes and entities
> > > * **Import/Export**: Export and import complete data models across environments
> > >
> > > **Technical Implementation:**
> > >
> > > * Centralized data model library for common classes and interfaces
> > > * Generic endpoints for data model and data parameters manipulation
> > > * Integration Designer communicates with Admin service for data model operations
> > > * Automatic input body computation based on data model input parameters
> > > * Runtime workflow start data endpoint for testing and execution
> >
> > > [tab] Limitations & Compatibility
> > >
> > > **Current Limitations:**
> > >
> > > * **Start Subworkflow Node**: Works as-is without data model integration in this release
> > > * **Endpoint Schemas**: Imported Swagger schemas are not yet integrated with workflow data models (planned for future release)
> > > * **Database Schemas**: Database operation schemas are not mapped to workflow variables yet (planned for future release)
> > >
> > > **Backwards Compatibility:**
> > >
> > > * Existing workflows continue to work without changes
> > > * End nodes from existing workflows can be renamed manually to align with output parameters
> > > * No breaking changes to current workflow execution
> > >
> > > **Node Naming:**
> > >
> > > * Node names must be unique within a workflow definition
> > > * System automatically validates uniqueness when renaming nodes
> > > * If duplicate names exist, an index is incremented (e.g., "Transform", "Transform\_2")
> >
> > > [tab] Benefits
> > >
> > > > [card] Consistent data lineage
> > > >
> > > > Ensure data consistency across processes and workflows with structured data models
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Input parameters automatically pre-fill Start Nodes - no manual JSON editing
> > >
> > > > [card] Type safety
> > > >
> > > > Define data types and validation rules at the workflow level for runtime safety
> > >
> > > > [card] Reusability
> > > >
> > > > Create reusable workflows with clear input/output contracts that can be invoked from multiple processes
> > >
> > > > [card] Better testing
> > > >
> > > > Test workflows with structured input data based on the data model
> > >
> > > > [card] Clear interfaces
> > > >
> > > > Workflow data models document the expected inputs and outputs for each workflow
> >
> > > [card] [Workflow Data Models Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> > >
> > > Complete guide to creating workflow data models, input/output parameters, process integration, and API reference.
> >
> > Integration Designer
>
> ***
>
> ### **Workflow data model**
>
> > [card] Workflow data model
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 adds comprehensive workflow data model management capabilities with new CRUD endpoints and runtime access to data model paths. This enables dynamic data model operations and better runtime introspection.
> >
> > > [tab] Key Features
> > >
> > > > [card] CRUD endpoints
> > > >
> > > > Create, read, update, and delete workflow data models programmatically via REST APIs
> > >
> > > > [card] Data model paths
> > > >
> > > > Runtime endpoint for retrieving workflow data model paths and structure information
> > >
> > > > [card] RUT instance mappings
> > > >
> > > > Enhanced /status and /details endpoints with mappings per workflow instance
> > >
> > > > [card] Runtime caching
> > > >
> > > > Improved caching for reusable templates to reduce latency and improve performance
> >
> > > [tab] Use Cases
> > >
> > > > [card] Dynamic forms
> > > >
> > > > Build dynamic forms based on data model structure at runtime
> > >
> > > > [card] Data migration
> > > >
> > > > Automate data model synchronization across environments
> > >
> > > > [card] Documentation
> > > >
> > > > Generate data model documentation automatically from API responses
> > >
> > > > [card] Validation
> > > >
> > > > Implement runtime validation based on data model definitions
> >
> > API Enhancement
>
> ***
>
> ### **MCP integration**
>
> > [card] MCP integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Model Context Protocol (MCP) integration, enabling AI agents to connect with external MCP servers and use their tools within Custom Agent nodes. MCP provides a standardized protocol for AI agents to access external tools, databases, APIs, and services.
> > >
> > > > [!NOTE]
> > > >
> > > > MCP integration extends AI agent capabilities by providing access to external tools through a standardized protocol. Configure MCP servers as data sources in Integration Designer and use their tools in workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] MCP data sources
> > > >
> > > > Add MCP servers as data sources in Integration Designer with base URL and authentication configuration
> > >
> > > > [card] Tool management
> > > >
> > > > View, enable, and turn off specific tools exposed by MCP servers directly from Integration Designer
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Select MCP servers in Custom Agent nodes to make their tools available to AI agents during workflow execution
> > >
> > > > [card] Authentication support
> > > >
> > > > Support for no authentication and OAuth 2.0 service account authentication methods
> > >
> > > > [card] Tool discovery
> > > >
> > > > Automatic tool discovery from MCP servers with schema information for inputs and outputs
> > >
> > > > [card] Execution monitoring
> > > >
> > > > Track tool usage and execution details in console logs for debugging and monitoring
> >
> > > [tab] How It Works
> > >
> > > **1. Add MCP server**
> > >
> > > Configure an MCP server as a data source in Integration Designer with base URL and authentication details
> > >
> > > **2. Authenticate connection**
> > >
> > > Set up authentication using no authentication (for development) or OAuth 2.0 service account (for production)
> > >
> > > **3. Discover tools**
> > >
> > > View available tools exposed by the MCP server with their input/output schemas
> > >
> > > **4. Enable tools**
> > >
> > > Enable or turn off specific tools based on your workflow requirements
> > >
> > > **5. Configure custom agent**
> > >
> > > Add a Custom Agent node to your workflow and select which MCP servers the agent can access
> > >
> > > **6. Execute workflow**
> > >
> > > AI agents can now use MCP tools during workflow execution to interact with external systems
> > >
> > > **7. Monitor execution**
> > >
> > > View tool usage and execution details in console logs for debugging and performance tracking
> >
> > > [tab] Authentication
> > >
> > > **Supported Authentication Methods:**
> > >
> > > **None**
> > >
> > > * No authentication required
> > > * Use for public MCP servers or development environments
> > > * Quick setup for testing and prototyping
> > >
> > > **Service Account (OAuth 2.0)**
> > >
> > > * OAuth 2.0 service account authentication
> > > * Required configuration:
> > >   * **Client ID**: OAuth client identifier
> > >   * **Client Secret**: OAuth client secret
> > >   * **Identity Provider URL**: Authorization server endpoint
> > > * Use for production environments
> > > * Secure access to MCP servers
> >
> > > [tab] Use Cases
> > >
> > > > [card] External API integration
> > > >
> > > > Connect AI agents to external APIs and services for data retrieval and action execution
> > >
> > > > [card] Database operations
> > > >
> > > > Query databases and perform data operations through MCP tools within AI workflows
> > >
> > > > [card] Custom business logic
> > > >
> > > > Expose custom business logic as MCP tools for AI agents to execute
> > >
> > > > [card] Multi-system orchestration
> > > >
> > > > Use multiple MCP servers in a single Custom Agent node to orchestrate operations across systems
> >
> > > [tab] Benefits
> > >
> > > > [card] Standardized integration
> > > >
> > > > Use a standardized protocol for AI agent tool integration across different systems
> > >
> > > > [card] Extended capabilities
> > > >
> > > > Extend AI agent capabilities with external tools without custom code
> > >
> > > > [card] Flexible tool management
> > > >
> > > > Enable or turn off specific tools per MCP server based on workflow needs
> > >
> > > > [card] Secure connections
> > > >
> > > > Support for OAuth 2.0 authentication ensures secure access to external services
> > >
> > > > [card] Tool reusability
> > > >
> > > > Configure MCP servers once and use their tools across multiple workflows and Custom Agent nodes
> > >
> > > > [card] Monitoring & debugging
> > > >
> > > > Console logs provide visibility into tool execution for troubleshooting and optimization
> >
> > > [card] [MCP Integration Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> > >
> > > Complete guide to MCP integration including data source configuration, tool management, and Custom Agent node usage.
> >
> > AI Integration
>
> ***
>
> ### **Custom Agent nodes**
>
> > [card] Custom Agent nodes
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Custom Agent nodes, enabling you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
> >
> > > [card] [Custom Agent Node Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > Complete guide to Custom Agent nodes, including configuration, usage, and best practices.
> >
> > AI Integration
>
> ***
>
> ### **Knowledge base**
>
> > [card] Knowledge base
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Knowledge Base integration, enabling you to create and manage centralized repositories of information that AI agents can query when preparing responses. Upload static documents or ingest dynamic data from workflows into Knowledge Bases that use vector embeddings and semantic search for intelligent information retrieval.
> > >
> > > > [!NOTE]
> > > >
> > > > Knowledge Bases enable AI agents to provide contextual, accurate responses based on your organization's documentation, policies, and dynamic data.
> >
> > > [tab] Key Features
> > >
> > > > [card] Document upload
> > > >
> > > > Upload PDF documents directly into Knowledge Bases for AI agent access
> > >
> > > > [card] Workflow ingestion
> > > >
> > > > Ingest data dynamically from workflows using Knowledge Base operations (Append, Replace, Delete)
> > >
> > > > [card] Semantic search
> > > >
> > > > AI agents find relevant information using natural language queries with vector embeddings
> > >
> > > > [card] Content sources
> > > >
> > > > Organize content across multiple sources within a Knowledge Base for better management
> > >
> > > > [card] Relevance scoring
> > > >
> > > > Configure minimum relevance thresholds (0-100%) to control response quality
> > >
> > > > [card] Testing capabilities
> > > >
> > > > Test queries and operations in isolation before adding them to production workflows
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Enable Knowledge Base queries in Custom Agent nodes with configurable parameters
> > >
> > > > [card] Content versioning
> > > >
> > > > Append, replace, or delete content sources with full traceability and state management
> >
> > > [tab] How It Works
> > >
> > > **1. Create Knowledge Base**
> > >
> > > Add a new Knowledge Base data source in Integration Designer
> > >
> > > **2. Ingest content**
> > >
> > > Upload PDF documents or ingest data from workflows into content sources
> > >
> > > **3. Automatic chunking**
> > >
> > > Content is automatically split into chunks and indexed in the vector database
> > >
> > > **4. Configure Custom Agent**
> > >
> > > Enable Knowledge Base in Custom Agent nodes and configure query parameters
> > >
> > > **5. Query execution**
> > >
> > > AI agents query the Knowledge Base using semantic search and receive relevant chunks
> > >
> > > **6. Response generation**
> > >
> > > Agents use retrieved chunks as context to generate accurate, informed responses
> >
> > > [tab] Workflow Operations
> > >
> > > **Knowledge Base operations available in workflows:**
> > >
> > > | Operation | Description |
> > > | - | - |
> > > | **Append** | Add new content to an existing content source without removing existing data |
> > > | **Replace** | Delete all existing content and replace with new content |
> > > | **Delete** | Remove all content from a content source |
> > >
> > > **Configuration Options:**
> > >
> > > * **Knowledge Base**: Select from local project libraries or dependencies
> > > * **Content Source**: Use existing sources, create new ones, or use workflow variables
> > > * **Content**: Static text, workflow variables, or configuration parameters
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product documentation assistant
> > > >
> > > > Create Knowledge Bases with product documentation for AI agents to answer customer questions
> > >
> > > > [card] Policy compliance
> > > >
> > > > Upload company policies so AI agents can reference them when processing requests
> > >
> > > > [card] Dynamic knowledge updates
> > > >
> > > > Ingest data from external systems through workflows to keep AI knowledge current
> > >
> > > > [card] Multi-source synthesis
> > > >
> > > > Organize information across sources and let AI agents synthesize comprehensive answers
> >
> > > [tab] Benefits
> > >
> > > > [card] Contextual AI responses
> > > >
> > > > AI agents provide accurate responses based on your organization's actual documentation
> > >
> > > > [card] Dynamic updates
> > > >
> > > > Keep AI knowledge current by ingesting data from workflows automatically
> > >
> > > > [card] Quality control
> > > >
> > > > Relevance scoring ensures only high-quality, relevant information is used
> > >
> > > > [card] Centralized management
> > > >
> > > > Manage all AI knowledge sources from a single location in Integration Designer
> > >
> > > > [card] No code integration
> > > >
> > > > Configure Knowledge Base queries directly in Custom Agent nodes without code
> > >
> > > > [card] Testable
> > > >
> > > > Test queries and see relevance scores before deploying to production
> >
> > > [tab] Limitations
> > >
> > > **Current Limitations:**
> > >
> > > > [!WARNING]
> > > >
> > > > * Only PDF documents are supported for manual upload (images, PPT, DOC, XLS support coming in future releases)
> > > > * Custom metadata cannot be defined (only system metadata is available)
> > > > * AI agents can only use one Knowledge Base per Custom Agent node
> > > > * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
> >
> > > [card] [Knowledge Base Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > Complete guide to creating Knowledge Bases, ingesting content, and using them in Custom Agent workflows.
> >
> > AI Integration
>
> ***
>
> ### **Update process variables**
>
> > [card] Update process variables
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces the ability for operations teams to modify process variables on active (Started or On Hold) process instances, providing critical tools to resolve production issues without process restarts. Edit, add, or delete attributes and objects directly using an editor with JSON validation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Formatting%20_%20Custom%20Date%20Format.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Tokens%20table.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > > [!NOTE]
> > > >
> > > > Updated values automatically sync to Task Manager and Elasticsearch, ensuring consistency across all systems. Previous values are saved in a snapshot table, and all modifications are tracked in the audit log for complete traceability.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Limited correction tools
> > > >
> > > > Operations teams had minimal tools to correct production issues at the process-instance level
> > >
> > > > [card] Blocked instances
> > > >
> > > > No way to unblock stuck process instances without backend intervention or process restarts
> > >
> > > > [card] Data correction challenges
> > > >
> > > > Incorrect process data required complex workarounds or manual database modifications
> > >
> > > > [card] Operational delays
> > > >
> > > > Production issues required developer intervention, increasing resolution time
> >
> > > [tab] Key Features
> > >
> > > > [card] Editor
> > > >
> > > > Edit process variables in a JSON editor with syntax validation and formatting
> > >
> > > > [card] Multiple entry points
> > > >
> > > > Access from Process Instances page contextual menu or Process Instance page secondary navigation
> > >
> > > > [card] Dual view modes
> > > >
> > > > Switch between Tree View (existing) and JSON View for variable visualization and editing
> > >
> > > > [card] Full CRUD operations
> > > >
> > > > Edit existing attribute values, add new attributes/objects, or delete existing attributes/objects
> > >
> > > > [card] JSON validation
> > > >
> > > > Automatic JSON format validation before saving to ensure data integrity
> > >
> > > > [card] Snapshot history
> > > >
> > > > Previous process variables are saved in a new snapshot table before changes are applied
> > >
> > > > [card] Auto-sync to Task Manager
> > > >
> > > > Updated variables automatically sync to Task Manager using existing mechanism
> > >
> > > > [card] Elasticsearch integration
> > > >
> > > > Process variables configured for data search are automatically updated in Elasticsearch
> > >
> > > > [card] Permission-based access
> > > >
> > > > Role-based access control with process\_variables\_edit permission ensures only authorized users can modify variables
> > >
> > > > [card] Export functionality
> > > >
> > > > Export button available near the view dropdown for downloading process variables
> > >
> > > **Iteration 2 - Enhanced Review:**
> > >
> > > > [card] Compare feature
> > > >
> > > > Ability to review updated process variables through a compare feature, showing before/after values for better visibility and validation
> >
> > > [tab] How It Works
> > >
> > > **Accessing the Feature:**
> > >
> > > You can access the edit functionality from two entry points:
> > >
> > > 1. **Process Instances Page**: Use contextual menu on a process instance row → navigates to Process Instance page and opens Variables tab in edit mode
> > > 2. **Process Instance Page**: Use contextual menu in secondary navigation → opens Variables tab in edit mode
> > >
> > > **Editing Process Variables:**
> > >
> > > **1. Select active instance**
> > >
> > > Choose an active process instance (Started or On Hold status) that requires variable modification
> > >
> > > **2. Switch to JSON view**
> > >
> > > In the Variables tab, switch from Tree View to JSON View using the view dropdown
> > >
> > > **3. Click edit**
> > >
> > > Click the Edit button (visible only if you have process\_variables\_edit permission)
> > >
> > > **4. Modify in editor**
> > >
> > > Edit process variables in the JSON editor - you can edit existing values, add new attributes/objects, or delete existing ones
> > >
> > > **5. Validate JSON**
> > >
> > > Ensure your JSON format is valid before saving - the editor will highlight syntax errors
> > >
> > > **6. Save changes**
> > >
> > > Click Save to apply changes - a snapshot of previous values is automatically created
> > >
> > > **7. Auto-sync**
> > >
> > > System automatically syncs updated variables to Task Manager and Elasticsearch (for variables configured for data search)
> > >
> > > **8. Review audit log**
> > >
> > > Check the Audit Log tab to confirm the modification was recorded with all details
> >
> > > [tab] Permissions & Security
> > >
> > > **Permission Requirements:**
> > >
> > > * **New Permission**: `process_variables_edit` available at workspace level
> > > * **Default Roles**: Added to `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, and `workspace_operations_editor` roles
> > > * **New Role**: `workspace_operations_editor` - A dedicated workspace role for operations management including process variable editing and operations (migration & move token)
> > >
> > > **Access Control:**
> > >
> > > * Edit option in UI is only visible to users with `process_variables_edit` permission
> > > * Save functionality is restricted to users with the required permission
> > > * Unauthorized users can view process variables but cannot modify them
> > >
> > > **Audit Logging:**
> > >
> > > Every process variable modification creates an audit log entry with:
> > >
> > > * Workspace ID
> > > * Feature: Process variables
> > > * Section: Process Instance
> > > * Application UUID and name
> > > * Subject: Process variables
> > > * Event: Edit
> > > * Subject Identifier: Process instance UUID
> > > * Body: JSON with new version of process parameters
> > >
> > > Audit logs are displayed in the Audit Log tab within the process instance for easy tracking.
> >
> > > [tab] Data Synchronization
> > >
> > > **What Gets Updated:**
> > >
> > > > [card] Task Manager
> > > >
> > > > Variables are automatically updated in Task Manager using existing mechanisms - ensures task keywords and data remain consistent
> > >
> > > > [card] Elasticsearch
> > > >
> > > > Variables configured for data search are automatically updated in Elasticsearch - maintains search accuracy
> > >
> > > > [card] Process instance params
> > > >
> > > > Primary process instance parameters are updated immediately in the database
> > >
> > > > [card] Snapshot table
> > > >
> > > > Previous values are saved in a new snapshot table before changes are applied
> > >
> > > **What Does NOT Get Updated:**
> > >
> > > > [card] Process snapshots
> > > >
> > > > Process instance snapshots (used for back navigation/reset) are not updated - maintains historical integrity
> > >
> > > > [card] Debug table
> > > >
> > > > Process instance debug records remain unchanged - preserves execution history
> > >
> > > > [card] Existing audit logs
> > > >
> > > > Previously recorded audit logs (manual actions, integrations) are not modified - maintains compliance trail
> > >
> > > > [card] Subprocess variables
> > > >
> > > > Child subprocess variables are not automatically updated - parent changes don't cascade to children
> >
> > > [tab] Important Considerations
> > >
> > > **Limitations & Best Practices:**
> > >
> > > > [!WARNING]
> > > >
> > > > **Subprocess Impact**: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.
> > >
> > > > [!WARNING]
> > > >
> > > > **Back Navigation**: 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.
> > >
> > > > [!WARNING]
> > > >
> > > > **Integration Messages**: 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.
> > >
> > > **Best Practices:**
> > >
> > > * **Verify JSON Format**: Always ensure valid JSON before saving to prevent data corruption
> > > * **Document Changes**: Use audit logs to track all modifications and maintain operational documentation
> > > * **Test in Lower Environments**: When possible, test variable modifications in staging before production
> > > * **Understand Dependencies**: Review process flow and subprocess relationships before modifying variables
> > > * **Consider Timing**: Best used for stuck processes or data corrections, not for regular operational changes
> > > * **Check Search Data**: If variables are used in data search, verify Elasticsearch sync completed successfully
> >
> > > [tab] Benefits
> > >
> > > > [card] Faster issue resolution
> > > >
> > > > Operations teams can resolve production issues immediately without developer intervention
> > >
> > > > [card] Reduced downtime
> > > >
> > > > Unblock stuck instances quickly, minimizing impact on end users and business processes
> > >
> > > > [card] Operational independence
> > > >
> > > > Empower ops teams with self-service tools for process-instance management
> > >
> > > > [card] Data consistency
> > > >
> > > > Automatic sync ensures Task Manager and Elasticsearch reflect updated values
> > >
> > > > [card] Full traceability
> > > >
> > > > Snapshots and audit logs provide complete history of all modifications for compliance
> > >
> > > > [card] Reduced risk
> > > >
> > > > Permission-based access and comprehensive audit trail reduce risk of unauthorized changes
> > >
> > > > [card] Flexible editing
> > > >
> > > > The JSON editor provides powerful JSON editing capabilities with validation
> > >
> > > > [card] Historical preservation
> > > >
> > > > Original values preserved in snapshot table for rollback scenarios
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Correct User Input Errors**
> > >
> > > * Customer submitted incorrect data in a loan application (wrong income, invalid address)
> > > * Operations team edits the variables to correct the information
> > > * Process continues without requiring customer to restart the application
> > >
> > > **2. Unblock Stuck Process Instances**
> > >
> > > * Process is waiting for external data that will never arrive (integration timeout, external system down)
> > > * Ops team updates the variable to provide expected data or skip the condition
> > > * Instance is unblocked and continues execution
> > >
> > > **3. Fix Integration Data Issues**
> > >
> > > * External system returned incorrect or incomplete data
> > > * Operations team corrects process variables to match expected values
> > > * Process continues with accurate data without re-calling the integration
> > >
> > > **4. Emergency Data Updates**
> > >
> > > * Critical business information changed after process started (regulatory update, pricing change)
> > > * Ops team modifies variables to reflect current information
> > > * Process continues with updated data without restart
> > >
> > > **5. Add Missing Attributes**
> > >
> > > * Process needs additional data that wasn't collected at start
> > > * Operations team adds new attributes or objects to process variables
> > > * Process can now access the required information
> > >
> > > **6. Remove Invalid Data**
> > >
> > > * Process contains incorrect or test data that shouldn't be there
> > > * Ops team deletes the problematic attributes or objects
> > > * Process continues with clean, valid data only
> > >
> > > **7. Update Task Manager Keywords**
> > >
> > > * Task search keywords need updating based on corrected data
> > > * Variables are modified and automatically synced to Task Manager
> > > * Tasks become searchable with correct keywords
> > >
> > > **8. Fix Elasticsearch Search Data**
> > >
> > > * Process data indexed for search contains errors
> > >
> > > * Operations team corrects variables configured for data search
> > >
> > > * Elasticsearch automatically updates, ensuring accurate search results
> > >
> > > > [!NOTE]
> > > >
> > > > This capability, combined with the upcoming Move Token feature, provides comprehensive process-instance management tools for operations teams.
> >
> > > [card] [Update Process Variables Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > >
> > > Complete guide including step-by-step instructions, permissions, data synchronization, best practices, and troubleshooting.
> >
> > Operations Enhancement
>
> ***
>
> ### **Token view improvements**
>
> > [card] Token view improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the **Tokens tab** in the **Process Instance View** with improved visibility and comprehension of token hierarchy and context. The enhanced token view introduces horizontal scrolling, frozen columns, hierarchical nesting, and new context-related columns to provide better insights into process execution.
> > >
> > > > [!NOTE]
> > > >
> > > > These improvements make it easier to understand complex process flows with parallel gateways, embedded subprocesses, and boundary events by clearly displaying token relationships and execution context.
> >
> > > [tab] Key Features
> > >
> > > > [card] Horizontal scrolling
> > > >
> > > > The table supports horizontal scrolling to accommodate all columns, ensuring all token information remains accessible
> > >
> > > > [card] Frozen columns
> > > >
> > > > Token UUID and Actions columns remain fixed during horizontal scroll for constant visibility of key identifiers and actions
> > >
> > > > [card] Hierarchical nesting
> > > >
> > > > Tokens display in a tree structure with nested child tokens under parent tokens, showing clear parent-child relationships
> > >
> > > > [card] Auto-expanded rows
> > > >
> > > > All token rows are expanded by default, providing immediate visibility into the complete token hierarchy
> > >
> > > > [card] Dynamic indentation
> > > >
> > > > Indentation dynamically adjusts based on nesting depth, visually representing token relationships
> > >
> > > > [card] Context column
> > > >
> > > > New Context column displays subprocess names for tokens running within embedded subprocesses, or main process name for main process tokens
> > >
> > > > [card] Initiator node column
> > > >
> > > > New Initiator Node column shows the node name that generated the token (e.g., Parallel Gateway, Non-interrupting boundary event)
> > >
> > > > [card] First executed node column
> > > >
> > > > New First Executed Node column displays the first node executed after token generation
> > >
> > > > [card] UUID copy functionality
> > > >
> > > > Token UUID displays first 6 characters with a copy icon; clicking copies the full UUID to clipboard with success notification
> > >
> > > > [card] Color-coded status tags
> > > >
> > > > Token Status column uses color-coded tags for quick visual identification of token lifecycle states
> > >
> > > > [card] Tooltip support
> > > >
> > > > Long node names are truncated with tooltips showing full text on hover for better readability
> > >
> > > > [card] Timezone-aware timestamps
> > > >
> > > > Last Updated column displays full datetime in browser timezone for accurate local time representation
> >
> > > [tab] Table Columns
> > >
> > > The enhanced token view includes the following columns:
> > >
> > > | Column | Description | Special Behavior |
> > > | - | - | - |
> > > | **Token UUID** | Unique identifier of the token | Only first 6 characters displayed. Copy icon appears beside UUID. Clicking copies full UUID to clipboard with success toast: "Full Token UUID copied to clipboard." **Frozen column** (stays visible during horizontal scroll) |
> > > | **Context** | Displays contextual data for token | Shows main process name for tokens in main process. Shows embedded subprocess name for tokens in embedded subprocesses (any nesting level) |
> > > | **Initiator Node** | Shows the node name that generated the token | Applies to child tokens only. For parent tokens, displays "-". Examples: Parallel Gateway name, Non-interrupting boundary event name |
> > > | **First Executed Node** | Displays the first node executed after token generation | For parallel gateway tokens: first executed node on that parallel branch. For boundary event tokens: first executed node on branch started from boundary node. If first node is embedded subprocess, displays embedded subprocess name |
> > > | **Current Node** | Displays the last node executed within the token branch | For parallel gateway tokens: last node on branch. For boundary event tokens: last node executed on branch triggered by boundary. For tokens in embedded subprocess: displays current node from subprocess |
> > > | **Current Node Status** | Shows the current execution status | Examples: WAITING\_TIMER\_EVENT, ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL. Sortable column |
> > > | **Token Status** | Indicates lifecycle state | Values: ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, TERMINATED. **Color-coded tags** for visual identification |
> > > | **Last Updated** | Timestamp of latest token state change | Displays full datetime in browser timezone |
> > > | **Actions** | Available actions for the token | Includes Retry token and View (eye icon) actions. **Frozen column** (stays visible during horizontal scroll). Retry button only visible for ACTIVE tokens |
> >
> > > [tab] Nesting Behavior
> > >
> > > **Token Hierarchy Display:**
> > >
> > > **1. Parent-child relationships**
> > >
> > > Tokens created by parallel gateways or embedded subprocesses are displayed as nested child tokens under their parent tokens
> > >
> > > **2. Default expansion**
> > >
> > > All token rows are expanded by default, showing the complete token hierarchy immediately
> > >
> > > **3. Dynamic indentation**
> > >
> > > Indentation adjusts automatically based on nesting depth, with columns expanding accordingly to maintain alignment
> > >
> > > **4. Visual hierarchy**
> > >
> > > The tree structure makes it easy to identify which tokens belong to which parallel branch or subprocess
> > >
> > > **Initiator Node Logic:**
> > >
> > > * **Parent tokens**: Display "-" in Initiator Node column
> > > * **Child tokens from parallel gateway**: Display the parallel gateway node name
> > > * **Child tokens from boundary event**: Display the boundary event node name
> > > * **Child tokens from back in steps**: Display appropriate initiator information
> >
> > > [tab] Benefits
> > >
> > > > [card] Better visibility
> > > >
> > > > Horizontal scrolling and frozen columns ensure all token information remains accessible regardless of table width
> > >
> > > > [card] Clear hierarchy
> > > >
> > > > Hierarchical nesting with dynamic indentation makes parent-child token relationships immediately clear
> > >
> > > > [card] Context awareness
> > > >
> > > > Context column provides immediate visibility into which subprocess a token is executing within
> > >
> > > > [card] Execution tracking
> > > >
> > > > Initiator Node and First Executed Node columns help track token origin and execution path
> > >
> > > > [card] Quick actions
> > > >
> > > > Frozen Actions column ensures retry and view actions are always accessible without scrolling
> > >
> > > > [card] Easy UUID access
> > > >
> > > > Quick copy functionality for full UUIDs without needing to view token details
> > >
> > > > [card] Visual status identification
> > > >
> > > > Color-coded status tags enable quick identification of token states at a glance
> > >
> > > > [card] Improved readability
> > > >
> > > > Tooltips for truncated names and timezone-aware timestamps improve overall readability
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Parallel Gateway Debugging**
> > >
> > > * View all parallel branches simultaneously with clear parent-child relationships
> > > * Identify which branch each token belongs to through hierarchical nesting
> > > * Track execution progress across multiple parallel paths
> > >
> > > **2. Embedded Subprocess Analysis**
> > >
> > > * Context column immediately shows which subprocess tokens are executing within
> > > * Understand nested subprocess relationships through indentation
> > > * Track token flow across multiple subprocess levels
> > >
> > > **3. Boundary Event Monitoring**
> > >
> > > * Initiator Node column shows which boundary event triggered each token
> > > * First Executed Node shows the execution path started by boundary events
> > > * Monitor non-interrupting boundary event token execution
> > >
> > > **4. Process Instance Troubleshooting**
> > >
> > > * Frozen UUID column ensures token identification is always visible
> > > * Copy UUID functionality enables quick token reference in support tickets
> > > * Color-coded status tags help identify problematic tokens quickly
> > >
> > > **5. Multi-Level Process Analysis**
> > >
> > > * Hierarchical view supports complex processes with multiple nesting levels
> > > * Dynamic indentation adapts to any nesting depth
> > > * All tokens visible by default without manual expansion
> >
> > > [card] [Token Documentation](/5.1/docs/building-blocks/token)
> > >
> > > Complete guide to tokens, including token status values, current node status, and detailed token status view.
> >
> > UX Enhancement
>
> ***
>
> ### **Access management enhancements**
>
> > [card] Access management enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces new workspace-level permissions and a dedicated operations editor role, providing more granular control over process instance management and operations.
> > >
> > > > [!NOTE]
> > > >
> > > > These enhancements enable organizations to delegate operational tasks to dedicated teams without granting full runtime or admin access.
> >
> > > [tab] New Role
> > >
> > > **workspace\_operations\_editor**
> > >
> > > A new predefined workspace role designed for operations teams who need to manage process instances without requiring full runtime or admin capabilities.
> > >
> > > > [card] Operations management
> > > >
> > > > Full CRUD access for process instance operations including migration and move token functionality
> > >
> > > > [card] Process variables
> > > >
> > > > Edit permission for process variables on active instances across the workspace
> > >
> > > > [card] Process instances
> > > >
> > > > Read and edit access to all process instances in the workspace
> > >
> > > > [card] Workspace user inheritance
> > > >
> > > > Inherits all base permissions from workspace\_user role including project creation
> > >
> > > **Role Constraints:**
> > >
> > > * Cannot be edited or deleted (predefined role)
> > > * Extends workspace\_user with operations-specific permissions
> > > * Does not include broader runtime capabilities (builds, policies, scheduled processes)
> > >
> > > **Use Cases:**
> > >
> > > * Support engineers managing process migrations
> > > * Operations teams handling token movements
> > > * Technical support staff editing process variables
> >
> > > [tab] New Permissions
> > >
> > > **Workspace-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **Operations** (Read/Edit/Create/Delete) | Manage process instance operations including migration and move token | `org_admin`, `workspace_admin`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Operations** (Read/Create only) | Create operations and view all operations | `workspace_user` |
> > > | **Process Variables** (Edit) | Edit process variables on active instances | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Process Instances** (Edit) | Edit process instance data | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > >
> > > **Project-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **UI Flows** (Read/Edit/Create/Delete) | Full access to create and manage UI Flows | `project_owner`, `project_editor` |
> > > | **UI Flows** (Read only) | View UI Flows definitions | `project_viewer` |
> >
> > > [tab] Benefits
> > >
> > > > [card] Principle of least privilege
> > > >
> > > > Grant only the permissions needed for specific operational tasks
> > >
> > > > [card] Dedicated operations teams
> > > >
> > > > Enable operations teams to work independently without full admin access
> > >
> > > > [card] Clear separation of concerns
> > > >
> > > > Distinguish between runtime management (builds, policies) and operations management (migrations, variables)
> > >
> > > > [card] Flexible role combinations
> > > >
> > > > Combine with other workspace roles for customized access patterns
> >
> > > [card] [Access Management Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix)
> > >
> > > Complete permissions matrix and role specifications for all FlowX roles.
> >
> > Access Management
>
> ***
>
> ### **Performance and stability**
>
> > [card] Performance and stability
> >
> > FlowX.AI 5.3 includes platform improvements focused on performance, reliability, and operational excellence.
> >
> > ## Backend optimizations
> >
> > > [card] Optimistic lock improvements
> > >
> > > Replace retry pattern with capped exponential backoff and infinite retries for better concurrency handling
> >
> > > [card] Events gateway optimization
> > >
> > > Update Redis read mode to XREAD BLOCK for more efficient event streaming
> >
> > > [card] Database performance
> > >
> > > Remove unnecessary index on token\_instance.current\_node\_id to improve update performance
> >
> > > [card] Template caching
> > >
> > > Enhanced caching for reusable templates at runtime reduces latency and improves throughput
> >
> > ## Infrastructure updates
> >
> > > [card] Connector Topic Pattern
> > >
> > > Added dedicated KAFKA\_CONNECTORS\_TOPIC\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [card] SpiceDB backup
> > >
> > > Documented backup and restore procedures for SpiceDB for disaster recovery
> >
> > > [card] Observability
> > >
> > > Publish Prometheus and OpenTelemetry Helm charts and container images to Harbor
> >
> > > [card] Security updates
> > >
> > > Fix HIGH vulnerabilities in Designer 5.1.x and main branch
> >
> > > [card] Renderer improvements
> > >
> > > Enhanced Angular renderer with action form submit functionality and substitution tag support
> >
> > Platform Updates
>
> ***
>
> ### **Exclusive gateways**
>
> > [card] Exclusive gateways
> >
> > FlowX.AI 5.3 enhances Exclusive Gateway configuration with expression testing capabilities and improved validation.
> >
> > > [card] Expression testing
> > >
> > > Test gateway expressions directly from the configuration panel with real-time validation
> >
> > > [card] Committed version testing
> > >
> > > Test business rules and gateway expressions in committed versions
> >
> > > [card] Code editor integration
> > >
> > > Enhanced code editor with syntax highlighting for complex expressions
> >
> > > [card] Payload synchronization
> > >
> > > Test payloads automatically update when rules are saved
> >
> > Process Logic
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes and stability improvements across Designer, renderers, backend services, and data management.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI Designer and Integration Designer stability improvements\
> 🖥️ [**Renderer Fixes**](#renderer-fixes) - Cross-platform renderer bug fixes for web, iOS, and Android\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements\
> 🗄️ [**Data & Integration Fixes**](#data-and-integration-fixes) - Data mapper and workflow integration fixes
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.3 resolves numerous Designer issues to improve stability and user experience.
> >
> > ## UI designer improvements
> >
> > > [accordion] Configuration & styling
> > >
> > > * **Fixed styles not applied after undo/redo** in Reusable UI Template config panel
> > > * **Fixed UI blocking** when slider min value exceeds max value
> > > * **Fixed warning icon display** in config panel
> > > * **Fixed expression test modal styles** when opened in resized screen
> > > * **Fixed UI action section refresh** when selecting different UI template
> > > * **Fixed UI action section rendering** after clicking 'Add new ui action'
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed loading spinner toggle** not available for Overlay loading behavior
> > > * **Fixed incomplete loading behavior dropdown**
> > > * **Fixed default messages** not displayed after undo
> > > * **Fixed forms in collections handling** for patch actions requests
> >
> > > [accordion] UI Flows designer
> > >
> > > * **Fixed task management error state** when view is selected
> > > * **Fixed tab content preview** showing content from 2 tabs when adding new tab
> >
> > > [accordion] Output parameters
> > >
> > > * **Fixed currency key management** - can now add/remove currency key in output params
> >
> > > [accordion] Exclusive Gateways
> > >
> > > * **Fixed gateway decisions** can now be modified after initial save
> > > * **Fixed test payload** updates when rules are saved
> > > * **Fixed expression propagation** to test modal
> >
> > ## Frontend runtime fixes
> >
> > > [accordion] Process management
> > >
> > > * **Fixed context column** showing empty value for tokens in embedded subprocesses
> > > * **Fixed process params update** from running process instance modal
> > > * **Fixed long node names** overlapping adjacent columns in Tokens table
> > > * **Fixed workspace redirect** on page refresh
> >
> > > [accordion] Audit & logging
> > >
> > > * **Fixed audit log subject value** not displayed for process params updates
> > > * **Fixed toast error messages** to use text from backend request
> > > * **Added documentation link** to Modify Variables modal info text
> >
> > Designer Stability
>
> ***
>
> ### **Renderer fixes**
>
> > [card] Renderer fixes
> >
> > FlowX.AI 5.3 includes comprehensive renderer fixes across all platforms.
> >
> > ## Web renderers (Angular & React)
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed theming** not applied to general loader
> > > * **Fixed theming** not applied to toast messages
> > > * **Fixed dynamic key values** not displayed in toast/loading messages
> > > * **Fixed success toast** displayed when flag is false
> >
> > > [accordion] Card & navigation
> > >
> > > * **Fixed card not expandable** after finishing subprocess started from it (Angular & React)
> > > * **Fixed card collapse** when next nav area is modal (Angular & React)
> > > * **Fixed subprocess navigation** closing parent process navigation with multiple hierarchies
> >
> > > [accordion] UI events
> > >
> > > * **Fixed UI event triggering** without user interaction (Angular)
> >
> > > [accordion] Call activity
> > >
> > > * **Fixed call activity UT rendering** when started from embedded process
> >
> > > [accordion] Collections & forms
> > >
> > > * **Fixed button with forms to submit** no longer disabled until template edited (Angular & React)
> > > * **Fixed multi-select search** filtering (React)
> > > * **Fixed JSON generation** with special characters in CollectionsV2
> >
> > ## Mobile renderers
> >
> > > [accordion] Android
> > >
> > > * **Fixed SSE Event & UI Event** - UI event value displayed instead of SSE value
> >
> > Renderer Stability
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process management
> >
> > > [accordion] Process & build issues
> > >
> > > * **Fixed processes not displayed** in container app list for imported builds
> > > * **Fixed token state** changing from Aborted to Active during back navigation
> > > * **Fixed audit logs** for override operations after merge
> >
> > > [accordion] Performance
> > >
> > > * **Fixed /details endpoint** returning cache error for processes with many components
> >
> > > [accordion] Process engine
> > >
> > > * **Fixed token stuck** in receive node when message received after advancing
> > > * **Fixed action params** copied correctly for child actions when copying node
> > > * **Fixed metadata preservation** when importing process
> >
> > ## Security & configuration
> >
> > > [accordion] Authentication
> > >
> > > * **Fixed service account client secret** configuration parameter in Authorization service
> >
> > ## Data management
> >
> > > [accordion] Runtime issues
> > >
> > > * **Fixed FlowxProps.events** mapping at runtime for array of objects
> >
> > ## Infrastructure
> >
> > > [accordion] Database & events
> > >
> > > * **Fixed advancing errors** in partition event table
> > > * **Fixed Liquibase logging** when crashing due to lock
> >
> > Backend Stability
>
> ***
>
> ### **Data and integration fixes**
>
> > [card] Data and integration fixes
> >
> > Fixes for data mappers and workflow integration features.
> >
> > ## Data mapper issues
> >
> > > [accordion] Mapping operations
> > >
> > > * **Fixed 400 error** when saving mappings
> > > * **Fixed error** when saving mapping with empty parameters
> > > * **Fixed unsaved mapping modal** displayed when saving action
> > > * **Fixed array mapping** - arrays in mapper functions now work correctly
> > > * **Fixed slice deletion** when updating PDM objects
> >
> > > [accordion] Data streams & workflows
> > >
> > > * **Fixed data stream availability** for older exports during import
> > > * **Fixed workflow data stream** data appending issue
> > > * **Fixed legacy mapping** toggle now triggers correctly for call activity
> >
> > > [accordion] UI updates
> > >
> > > * **Fixed start node** not updated in UI after parameters update until refresh
> > > * **Fixed manifest resource** not found after switching versions
> >
> > > [!NOTE]
> > >
> > > Data mapper fixes ensure reliable workflow integration and process-to-workflow data synchronization.
> >
> > Integration Stability
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.3.0](./deployment-guidelines-v5.3).
>
> ### Environment variable updates
>
> > [!NOTE]
> >
> > For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.
>
> ### Breaking changes
>
> > [!WARNING]
> >
> > **FlowX Engine Configuration**: v5.3.0 includes a breaking change to the partitioning and archiving configuration structure. If you have enabled data partitioning, you must update your configuration files.
>
> > [card] [Migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
> >
> > Complete migration guide with step-by-step instructions, configuration examples, and troubleshooting
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.2.0 requires configuration changes for FlowX Engine partitioning/archiving
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.3


# Deployment guidelines v5.4.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/deployment-guidelines-v5.4

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.38.0** | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **10.38.0** | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **10.22.0** | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **10.15.0** | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **10.17.0** | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **10.22.0** | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **10.23.0** | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **10.25.0** | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **10.14.0** | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **10.21.0** | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **10.16.0** | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **10.38.0** | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **10.20.1** | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **10.28.0** | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **10.17.0** | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **email-gateway** | **10.9.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 |

### AI Platform

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.4.0 | Keycloak | 26+ |
| 5.4.0 | Kafka | 3.8 - 3.9 |
| 5.4.0 | PostgreSQL | 16 - 17 |
| 5.4.0 | Oracle Database | 21c, 23ai |
| 5.4.0 | MongoDB | 7 - 8 |
| 5.4.0 | Redis | 7.4 - 8.0 |
| 5.4.0 | Elasticsearch | 8 |
| 5.4.0 | Angular (Web SDK) | 20 |
| 5.4.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.4.0

### Key features and updates

> [card] Email Trigger
>
> Start processes automatically from incoming emails with configurable validation rules

> [card] MCP Server Improvements
>
> Enhanced audit logging, resource management, and tool refresh capabilities

> [card] Email Gateway
>
> New microservice for handling email communication workflows

## Upgrading from v5.3.0

### Breaking changes

> [!NOTE]
>
> FlowX.AI 5.4.0 does not introduce breaking changes for standard deployments. Upgrades from v5.3.0 should be straightforward.

### New environment variables

The following new environment variables have been introduced:

| Variable | Service | Description |
| - | - | - |
| `KAFKA_CONNECTORS_TOPIC_PATTERN` | process-engine | Dedicated Kafka topic pattern for connectors (optional, falls back to `KAFKA_TOPIC_PATTERN` if not set) |
| `KAFKA_BOOTSTRAP_SERVERS` | All services | Standardized Kafka bootstrap servers property (preferred over `SPRING_KAFKA_BOOTSTRAPSERVERS`, backwards compatible) |
| `KAFKA_SECURITY_PROTOCOL` | All services | Standardized Kafka security protocol property (preferred over `SPRING_KAFKA_SECURITY_PROTOCOL`, backwards compatible) |

### Key changes

* **Email Trigger**: New capability to start processes from email events
* **Connector Topics**: New dedicated topic pattern variable for connectors
* **Kafka Configuration**: Standardized Kafka property names (`KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_SECURITY_PROTOCOL`) aligned across all services with backwards compatibility
* **Email Gateway**: New microservice for email communication workflows

### New microservice: Email Gateway

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces a new optional microservice: **Email Gateway**. This service handles email communication workflows within the platform.

The Email Gateway requires the following infrastructure:

| Component | Requirement |
| - | - |
| PostgreSQL | Dedicated database named `email_gateway` |
| MongoDB | Connection to existing `app-runtime` database |
| Kafka | Access to the FlowX Kafka cluster |
| Redis | Shared Redis instance |
| Keycloak | Service account for authentication |

> [!NOTE]
>
> The Email Gateway operates as an internal service and does not require ingress configuration.

> [card] [Email Gateway Setup Guide](/5.9/setup-guides/email-gateway-setup)
>
> Complete setup instructions including Helm values, environment variables, and troubleshooting.

### Compatibility

* **No Breaking Changes**: Standard deployments can upgrade without configuration changes
* **Feature Additions**: SaaS features require additional infrastructure configuration for production use
* **Renderer Updates**: Web and mobile SDKs include bug fixes with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.4.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026

SaaS multi-tenant platform capabilities, database tenant isolation, email-triggered processes, MCP server enhancements, and backend performance improvements.

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces foundational support for a multi-tenant platform, enabling organization management and improved tenant isolation in the SaaS deployment model.

> [!NOTE]
>
> **Deployment models** - Starting with v5.4.0, FlowX.AI is available in two deployment models:
>
> * **Self-Managed** (On-Premises / Customer Cloud)
> * **FlowX SaaS** (FlowX-hosted)
>
> **Feature availability badges:**
>
> * SaaS Features exclusive to FlowX SaaS deployments
> * Self-Managed Features specific to self-managed deployments
> * All Deployments Features available in both deployment models

**What's new?**

> [tab] SaaS & multi-tenancy
>
> > [!NOTE]
> >
> > The features described in this section apply to **FlowX SaaS deployments**.\
> > Self-managed deployments are not affected unless explicitly stated.
>
> FlowX.AI 5.4.0 introduces initial SaaS capabilities enabling multi-tenant deployments with organization management and tenant isolation.
>
> 🏢 [**SaaS Multi-Tenancy**](#saas-multi-tenancy) - Multi-tenant platform with organization isolation and provisioning
>
> ### **SaaS multi-tenancy**
>
> > [card] SaaS multi-tenancy
> >
> > Multi-tenant SaaS capabilities enable multiple organizations to operate independently on shared infrastructure. Each organization receives dedicated resources while maintaining complete isolation from other tenants.
> >
> > > [card] Multi-tenant architecture
> > >
> > > Multiple organizations operate on shared infrastructure with complete isolation
> >
> > > [card] Tenant isolation
> > >
> > > Complete data and authentication isolation between organizations
> >
> > > [card] Organization provisioning
> > >
> > > Automatic provisioning of dedicated resources for each organization
> >
> > > [card] Resource management
> > >
> > > Each organization receives dedicated resources and project spaces
> >
> > > [card] [Documentation](/5.9/docs/saas/saas-overview)
> > >
> > > See the complete FlowX SaaS documentation for guides and best practices.
> >
> > Major FeatureSaaS
>
> ***

> [tab] AI & Integration
>
> Enhanced MCP server management.
>
> 📧 [**Email Trigger**](#email-trigger) - Start processes from external email events with configurable validation rules\
> 💬 [**Chat Component**](#chat-component) - Standalone chat tab for AI-powered conversational interfaces\
> 🔧 [**MCP Server Improvements**](#mcp-server-improvements) - Enhanced audit logging, resource management, and tool updates
>
> ### **Email trigger**
>
> > [card] Email trigger
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces Email Trigger as a new Data Source type in Integration Designer, enabling processes to be started automatically when emails are received. Connect to IMAP mail servers, monitor specific mailboxes, and create process instances with the email data.
> > >
> > > > [!NOTE]
> > > >
> > > > Email Triggers bridge external communication channels with FlowX.AI process automation, enabling organizations to automatically route and process incoming emails through defined business workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation for configuration guides and examples.
> >
> > > [tab] Key Features
> > >
> > > > [card] IMAP Connection
> > > >
> > > > Connect to any IMAP-compatible email server with SSL/TLS support
> > >
> > > > [card] Message Start Event
> > > >
> > > > New trigger type option in Message Start Event nodes to use Email Triggers
> > >
> > > > [card] Attachment handling
> > > >
> > > > Automatic upload of email attachments to Document Plugin with file validation
> > >
> > > > [card] Validation rules
> > > >
> > > > Configure allowed file types, maximum file size, and attachment count limits
> > >
> > > > [card] Manage triggers
> > > >
> > > > Central Runtime page to activate, deactivate, and monitor email triggers
> > >
> > > > [card] Failed triggers
> > > >
> > > > Dedicated page to view and troubleshoot failed email processing attempts
> >
> > > [tab] Configuration
> > >
> > > **Data Source Settings:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | IMAP (currently supported) |
> > > | Server Host | IMAP server hostname |
> > > | Port | Connection port (993 for SSL/TLS) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > > | SSL/TLS | Enable secure connection |
> > >
> > > **Filtering Criteria:**
> > >
> > > * **Email Address**: Monitored email address (read-only, based on authentication)
> > > * **Mailbox Folder**: Folder to monitor (default: Inbox)
> > >
> > > **Validation Options:**
> > >
> > > * **Allowed File Types**: PDF, DOCUMENT, IMAGE, EXCEL, ZIP
> > >
> > > * **Maximum File Size**: Up to 25 MB per attachment
> > >
> > > * **Maximum File Count**: Limit attachments per email
> > >
> > > > [!TIP]
> > > >
> > > > All fields accept configuration parameters using `${configParam}` syntax for environment-specific values.
> >
> > > [tab] Email Data Schema
> > >
> > > When an email triggers a process, the following data structure is available:
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "emailMessage": {
> > >     "subject": "Support Request #12345",
> > >     "dateTime": "2026-01-15T10:30:00Z",
> > >     "sender": "customer@example.com",
> > >     "body": "Email body content...",
> > >     "fileAttachments": [{
> > >       "filePath": "email-attachments/proc-123/file.pdf",
> > >       "downloadPath": "/api/internal/files/uuid/download"
> > >     }],
> > >     "headerParams": {
> > >       "Message-ID": "<abc123@example.com>"
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Use Cases
> > >
> > > > [card] Customer support automation
> > > >
> > > > Automatically create support tickets from incoming customer emails
> > >
> > > > [card] Document processing
> > > >
> > > > Process attached documents through automated workflows
> > >
> > > > [card] Request handling
> > > >
> > > > Route requests to appropriate departments based on email content
> > >
> > > > [card] Notification processing
> > > >
> > > > Process automated notifications from external systems
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat component**
>
> > [card] Chat component
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a standalone Chat tab in web container applications, enabling AI-powered conversational interfaces within your applications. The Chat component provides a dedicated space for users to interact with AI agents through a familiar messaging interface.
> > >
> > > > [!NOTE]
> > > >
> > > > The Chat component integrates with FlowX.AI's AI platform to enable intelligent conversational experiences powered by your configured AI agents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the complete Chat Component documentation for configuration guides and best practices.
> >
> > > [tab] Key Features
> > >
> > > > [card] Standalone chat tab
> > > >
> > > > Dedicated chat interface available as a standalone tab in web container apps
> > >
> > > > [card] Message history
> > > >
> > > > Persistent chat history with automatic scrolling to the latest messages
> > >
> > > > [card] AI agent integration
> > > >
> > > > Connect to workflows powered by AI agents
> > >
> > > > [card] Session management
> > > >
> > > > Automatic session handling with persistence across page refreshes
> > >
> > > > [card] Customizable UI
> > > >
> > > > Themeable components with comprehensive style configuration through Theme Admin
> >
> > > [tab] Configuration
> > >
> > > **Component setup:**
> > >
> > > * Add Chat component from UI Designer to your UI Flow
> > > * Select a workflow to handle chat interactions
> > > * Configure header, messages, and input properties
> > > * Apply custom styling through Theme Admin
> > >
> > > **Display modes:**
> > >
> > > * Full screen (v5.4.0)
> > > * Additional modes planned for v5.5
> >
> > > [tab] Improvements
> > >
> > > **Session handling:**
> > >
> > > * Chat session ID is now generated when the first message is sent (not when opening the chat)
> > > * Improved session tracking
> > >
> > > **Message display:**
> > >
> > > * Latest messages are automatically scrolled into view after loading chat history
> > > * User input formatting (JSON, multiline text) is now preserved in displayed messages
> > >
> > > **Platform support:**
> > >
> > > * Available in both Angular and React web renderers
> > > * Mobile support planned for v5.5
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **MCP server improvements**
>
> > [card] MCP server improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 enhances MCP (Model Context Protocol) server integration with improved audit logging, exception handling, and resource management capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audit logging
> > > >
> > > > Complete audit trail for MCP server operations including creation, updates, and tool execution
> > >
> > > > [card] Tool refresh
> > > >
> > > > Update MCP servers to fetch new tools without recreating the data source
> > >
> > > > [card] Resource tracking
> > > >
> > > > Track MCP server usage across workflows with proper resource management
> > >
> > > > [card] Copy support
> > > >
> > > > Properly preserve MCP server selections when copying or duplicating workflows
> > >
> > > > [card] SSE streaming
> > > >
> > > > Fixed SSE event streaming to deliver events individually as they complete
> > >
> > > > [card] Exception handling
> > > >
> > > > Improved error handling and reporting for MCP server operations
> >
> > > [tab] Bug Fixes
> > >
> > > * **Tool updates**: Updating MCP servers now correctly fetches new tools
> > > * **Workflow copy**: MCP server selections are preserved when copying workflows
> > > * **Resource usages**: Fixed resource usage tracking when copying workflows to other projects
> > > * **SSE events**: Events are now streamed individually instead of all at once
> > > * **Audit entries**: Fixed missing event and subject in audit log entries
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] Rendering
>
> UI component enhancements and navigation improvements for web applications.
>
> 🎴 [**Card Default Collapse State**](#card-default-collapse-state) - Configure cards to load in collapsed state by default\
> 🧭 [**UI Flow Breadcrumbs**](#ui-flow-breadcrumbs) - Navigation breadcrumbs ui component for UI Flows with theme configuration\
> 📊 [**UI Flow Sessions**](#ui-flow-sessions) - Monitor and manage UI Flow sessions with audit logs and process tracking\
> 📋 [**Tables in Collections**](#tables-in-collections) - Add support for Table UI components within Collection UI elements
>
> ### **Card default collapse state**
>
> > [card] Card default collapse state
> >
> > FlowX.AI 5.4.0 introduces a new **Default collapse state** property for Card components with accordion functionality, allowing you to configure cards that are collapsed when first loaded.
> >
> > > [tab] Overview
> > >
> > > When using Card components with the accordion feature enabled, you can now specify whether the card should be expanded or collapsed by default when the screen loads. This provides better control over the initial presentation of content and helps manage screen real estate.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> > > >
> > > > See the complete Card component documentation for configuration details.
> >
> > > [tab] Configuration
> > >
> > > **Default collapse state options:**
> > >
> > > | State | Description |
> > > | - | - |
> > > | **Expanded** | The card content is visible when the screen loads (default behavior) |
> > > | **Collapsed** | The card content is hidden when the screen loads; users click to expand |
> > >
> > > > [!NOTE]
> > > >
> > > > This property is only available when the **Has accordion** setting is enabled on the Card component.
> >
> > > [tab] Use Cases
> > >
> > > > [card] Progressive disclosure
> > > >
> > > > Start with collapsed sections to reduce initial visual complexity
> > >
> > > > [card] Optional content
> > > >
> > > > Hide less important information by default while keeping it accessible
> > >
> > > > [card] Long forms
> > > >
> > > > Break up lengthy forms into collapsible sections for better navigation
> > >
> > > > [card] FAQ sections
> > > >
> > > > Display questions collapsed with answers revealed on click
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Breadcrumbs**
>
> > [card] UI Flow Breadcrumbs
> >
> > > [tab] Overview
> > >
> > > Navigation breadcrumbs UI component for UI Flows provide users with clear context of their current location within the application hierarchy. Breadcrumbs display the navigation path and enable quick navigation to parent screens.
> > >
> > > > [!NOTE]
> > > >
> > > > Breadcrumbs enhance user experience by providing visual navigation context and allowing users to understand their position in the application structure.
> >
> > > [tab] Key Features
> > >
> > > > [card] Navigation breadcrumbs UI component
> > > >
> > > > Display breadcrumbs UI component for UI Flows showing the current navigation path
> > >
> > > > [card] Admin theme configuration
> > > >
> > > > Configure breadcrumb appearance and styling through Admin theme settings
> >
> > > [tab] Configuration
> > >
> > > **Theme Configuration:**
> > >
> > > * Configure breadcrumb styling through Admin theme settings
> > > * Customize colors, fonts, and spacing to match your application design
> > > * Apply consistent styling across all UI Flows
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Sessions**
>
> > [card] UI Flow Sessions
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces UI Flow Sessions monitoring in the Runtime view, providing comprehensive visibility into active user sessions with UI Flows. Monitor session activity, view audit logs, track associated processes, and debug UI Flow interactions in real-time.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flow Sessions enable administrators and developers to track user interactions, troubleshoot issues, and monitor the health of UI Flow-based applications.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> > > >
> > > > See the complete UI Flow Sessions documentation for detailed usage and troubleshooting guides.
> >
> > > [tab] Key Features
> > >
> > > > [card] Session monitoring
> > > >
> > > > View all active and historical UI Flow sessions with status, start date, and session IDs
> > >
> > > > [card] Audit log
> > > >
> > > > Comprehensive audit trail showing all events and actions within each session
> > >
> > > > [card] Process tracking
> > > >
> > > > Monitor process instances started from UI Flows with execution status and timing
> > >
> > > > [card] Workflow debugging
> > > >
> > > > View workflow execution details, node timing, and data transformations for troubleshooting
> > >
> > > > [card] Filtering and search
> > > >
> > > > Filter sessions by UI Flow definition and search by session ID for quick access
> > >
> > > > [card] Real-time status
> > > >
> > > > Track session status updates in real-time (STARTED, ACTIVE, FINISHED, FAILED)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Session monitoring
> > > >
> > > > Monitor active sessions to understand user engagement and identify sessions needing attention
> > >
> > > > [card] Audit and compliance
> > > >
> > > > Track all user interactions and actions for audit purposes and compliance requirements
> > >
> > > > [card] Debugging
> > > >
> > > > Investigate issues by reviewing audit logs, process instances, and workflow executions
> > >
> > > > [card] Performance analysis
> > > >
> > > > Analyze session duration, process start times, and workflow execution performance
> >
> > Runtime ManagementAll Deployments
>
> ***
>
> ### **Tables in Collections**
>
> > [card] Tables in Collections
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces support for Table UI components within Collection UI elements, enabling you to display structured tabular data as items within dynamic collections. This enhancement provides greater flexibility for presenting complex data structures in a consistent, organized format.
> > >
> > > > [!NOTE]
> > > >
> > > > You can now embed Table components inside Collection prototypes, allowing each collection item to display data in a structured table format with columns, rows, and table-specific features.
> > >
> > > > [card] [Table Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/table)
> > > >
> > > > See the complete Table component documentation for configuration details and usage examples.
> > >
> > > > [card] [Collection Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/collection/collection)
> > > >
> > > > Learn about Collection components and how to configure collection prototypes.
> >
> > > [tab] Key Features
> > >
> > > > [card] Table in collection items
> > > >
> > > > Embed Table components within Collection prototypes to display structured data for each collection item
> > >
> > > > [card] Structured data display
> > > >
> > > > Present complex data structures with columns, rows, and table-specific formatting within collections
> > >
> > > > [card] Table features
> > > >
> > > > Leverage full Table component capabilities including sorting, filtering, pagination, and row actions
> > >
> > > > [card] Dynamic content
> > > >
> > > > Combine Collection's dynamic data handling with Table's structured presentation for flexible layouts
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product catalogs
> > > >
> > > > Display product information in table format within a collection of products
> > >
> > > > [card] Data dashboards
> > > >
> > > > Create dashboard views with multiple tables showing different data sets in collection items
> > >
> > > > [card] Report listings
> > > >
> > > > Show report summaries in table format within a collection of reports
> > >
> > > > [card] Comparison views
> > > >
> > > > Compare multiple entities side-by-side using tables within collection items
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Platform & infrastructure
>
> Backend optimizations, connector improvements, and platform stability enhancements.
>
> 🔌 [**Connector Topic Pattern**](#connector-topic-pattern) - Dedicated Kafka topic pattern for connectors\
> ⚙️ [**Kafka Configuration Alignment**](#kafka-configuration-alignment) - Unified Kafka property names across all services with backwards compatibility\
> ⚡ [**Advancing Performance**](#advancing-performance) - Fixed advancing partition issues and improved concurrency handling
>
> ### **Connector topic pattern**
>
> > [card] Connector topic pattern
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a dedicated Kafka topic pattern variable (`KAFKA_CONNECTORS_TOPIC_PATTERN`) for connectors, allowing custom topic patterns without affecting other platform components like document-plugin, data-search, and cms-core.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Shared topic pattern
> > > >
> > > > Connectors used the same `KAFKA_TOPIC_PATTERN` as other components, limiting customization
> > >
> > > > [card] Security concerns
> > > >
> > > > Connectors could write to all topics with the pattern `ai.flowx.engine.receive.*`
> >
> > > [tab] Solution
> > >
> > > **New Configuration:**
> > >
> > > ```yaml theme={"dark"}
> > > # Old configuration (shared with all components)
> > > KAFKA_TOPIC_PATTERN: ai.flowx.engine.receive.*
> > >
> > > # New configuration (dedicated for connectors)
> > > KAFKA_CONNECTORS_TOPIC_PATTERN: ro.uniflow.*
> > > ```
> > >
> > > **Benefits:**
> > >
> > > * Connectors can use custom topic patterns
> > > * Other components continue using the standard pattern
> > > * Improved security through topic isolation
> >
> > InfrastructureSelf-Managed
>
> ***
>
> ### **Kafka configuration alignment**
>
> > [card] Kafka configuration alignment
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 aligns Kafka configuration properties across all services (core-services and AI platform services) by introducing standardized property names while maintaining full backwards compatibility with existing configurations.
> >
> > > [tab] New Properties
> > >
> > > **Standardized Kafka Properties:**
> > >
> > > The following new environment variables are now available across all services:
> > >
> > > | Environment Variable | Description | Fallback Property |
> > > | - | - | - |
> > > | `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers | `SPRING_KAFKA_BOOTSTRAP_SERVERS` |
> > > | `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka communication | `SPRING_KAFKA_SECURITY_PROTOCOL` |
> > >
> > > > [!NOTE]
> > > >
> > > > The new properties take precedence over the legacy `SPRING_KAFKA_*` properties. If the new properties are not set, the system automatically falls back to the legacy properties, ensuring backwards compatibility.
> >
> > > [tab] Benefits
> > >
> > > > [card] Property alignment
> > > >
> > > > Consistent property names across core-services and AI platform services
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing configurations using `SPRING_KAFKA_*` properties continue to work without changes
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Unified configuration approach across all FlowX.AI services
> > >
> > > > [card] Migration flexibility
> > > >
> > > > Migrate to new properties at your own pace without breaking existing deployments
> > >
> > > > [!NOTE]
> > > >
> > > > This change was implemented in core-services and automatically applies to all services that use the shared Kafka configuration. No action is required for existing deployments, but you can optionally migrate to the new property names for consistency.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Advancing performance**
>
> > [card] Advancing performance
> >
> > FlowX.AI 5.4.0 includes significant fixes and improvements to the advancing mechanism, resolving issues with stalled events and improving concurrency handling.
> >
> > > [accordion] Stalled events fix
> > >
> > > Fixed issue where NEW entries in `advancing_partition` and `advancing_partition_event` tables would become stalled and never processed. This occurred when multiple events were generated for the same partition during parallel processing.
> >
> > > [accordion] Numeric overflow fix
> > >
> > > Fixed numeric overflow error when `advancing_partition_event_seq` sequence exceeded `Integer.MAX_VALUE`. Now correctly uses `getLong()` instead of `getInt()` for sequence values.
> >
> > > [accordion] Concurrency improvements
> > >
> > > * Fixed issue with multiple events to the same partition causing negative `count_queued_events`
> > > * Replaced trigger-based solution with SQL transactions for atomic updates
> > > * Improved handling of embedded subprocess completion under concurrent load
> >
> > > [accordion] Automated test stability
> > >
> > > Resolved data inconsistencies and business exceptions that were causing automated tests to fail consistently.
> >
> > PerformanceAll Deployments
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes across SaaS features, Designer, and backend services.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI and navigation fixes for Designer\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.4.0 resolves Designer issues to improve stability and user experience.
> >
> > ## Navigation & routing
> >
> > > [accordion] Navigation fixes
> > >
> > > * **Fixed sidebar display** - sidebar menu now shows when accessing pages via URL
> > > * **Fixed subprocess navigation** - resolved 403 when navigating to subprocesses
> > > * **Fixed back navigation** - resolved 403 when going back from UI Flows page
> > > * **Fixed audit log access** - resolved errors when viewing process instance audit logs
> > > * **Fixed version history** - "Open version in new tab" now works correctly
> >
> > > [accordion] UI improvements
> > >
> > > * **Fixed default locale display** - locale now correctly shown in Version settings
> > > * **Fixed substitution calls** - resolved errors when starting processes or accessing UI Flows
> >
> > Designer StabilityAll Deployments
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process engine
> >
> > > [accordion] Advancing & concurrency
> > >
> > > * **Fixed stalled advancing events** - NEW entries no longer get stuck in advancing tables
> > > * **Fixed numeric overflow** - resolved overflow when sequence exceeds Integer.MAX\_VALUE
> > > * **Fixed concurrent updates** - resolved stale data errors for embedded subprocess completion
> > > * **Fixed negative counter** - resolved issue with `count_queued_events` going negative
> >
> > ## AI platform
> >
> > > [accordion] AI integration fixes
> > >
> > > * **Fixed multi-agent streaming** - streaming now works correctly for multi-agent chat
> > > * **Fixed SSE event delivery** - events are delivered individually as they complete
> >
> > ## Integration Designer
> >
> > > [accordion] Workflow & data model
> > >
> > > * **Fixed file upload multipart** - only file name is sent in multipart body, not full path
> > > * **Fixed data model duplicates** - resolved duplicate entries in mongo properties\_paths
> >
> > Backend StabilityAll Deployments
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.4.0](./deployment-guidelines-v5.4).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.3.0 - no breaking changes for standard deployments
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.4
>
> ### SaaS features
>
> > [!NOTE]
> >
> > The SaaS multi-tenant features introduced in this release require additional infrastructure configuration for production deployments. Contact your FlowX.AI representative for guidance on enabling SaaS capabilities.


# Deployment guidelines v5.5.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/deployment-guidelines-v5.5

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.60.0** | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 |
| **admin** | **10.53.0** | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 |
| **designer** | **10.91.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **cms-core** | **10.35.0** | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **10.25.0** | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **10.27.0** | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **10.35.0** | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **10.35.0** | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **10.35.0** | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 |
| **data-search** | **10.25.0** | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **10.31.0** | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **10.27.0** | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 |
| **integration-designer** | **10.63.0** | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 |
| **application-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **data-sync** | **10.31.1** | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 |
| **authorization-system** | **10.42.1** | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **10.27.0** | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 |
| **email-gateway** | **10.24.0** | 10.9.0 | - | - | - | - |
| **organization-manager** | **10.19.2** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 |
| **Android renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 |
| **di-platform** | **10.2.6** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **knowledgebase** | **TBD** | - | - | - | - | - |
| **knowledgebase-rag** | **10.2.0** | - | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.2.0** | - | - | - | - | - |
| **mcp** | **10.2.0** | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.5.0 | Keycloak | 26+ |
| 5.5.0 | Kafka | 3.8 - 3.9 |
| 5.5.0 | PostgreSQL | 16 - 17 |
| 5.5.0 | Oracle Database | 21c, 23ai |
| 5.5.0 | MongoDB | 7 - 8 |
| 5.5.0 | Redis | 7.4 - 8.0 |
| 5.5.0 | Elasticsearch | 8 - 9 |
| 5.5.0 | Angular (Web SDK) | 20 |
| 5.5.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.5.0

### Key features and updates

> [card] Chat Component Enhancements
>
> New subcomponents (reasoning, error, suggestions), display modes, and mobile support

> [card] UI Flows Improvements
>
> Process renderer component, start workflow action, and on load events

> [card] Microsoft Outlook Integration
>
> Native MS Graph data source for reading and sending Outlook emails

> [card] Send Notification Action
>
> Send emails and reply to received emails directly from processes via SMTP

> [card] Knowledge Base v2
>
> Updated Knowledge Base with audit, resource management, and improved UI

> [card] User Management Updates
>
> Password policy, DISABLED status, resend invitations, workspace environment types

## Upgrading from v5.4.0

### Breaking changes

> [!WARNING]
>
> FlowX.AI 5.5.0 introduces a **breaking change** to the default authentication mechanism across most platform services. If you rely on the default `SECURITY_TYPE` value or opaque-token introspection, action is required before upgrading.

#### Authentication mechanism change

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. This reflects a shift from opaque-token introspection to JWT-based authentication as the default security mechanism.

**Removed environment variables:**

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

**Changed default values:**

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

**Migration steps:**

**1. Update SECURITY\_TYPE if explicitly set**

If you explicitly set `SECURITY_TYPE=oauth2` in your deployment configuration, update it to `jwt-public-key` or remove it to use the new default.

**2. Remove deprecated opaque-token variables**

Remove all `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_*` variables from your Helm values, environment configs, or deployment manifests.

**3. Update service account client IDs**

Service account client IDs now follow the `flowx-{service-name}-sa` pattern (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Update your Keycloak service account configurations accordingly.

**4. Configure the service account realm**

Add the `security.oauth2.sa-realm` property to your configuration if your service account realm differs from the default.

**5. Remove legacy OAuth2 client variables**

Remove `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENT_ID`, `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`, and `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_*` variables from your configuration.

***

### Key changes

* **Authentication**: Default `SECURITY_TYPE` changed from `oauth2` to `jwt-public-key` (breaking change — see above)
* **Organization Manager**: New microservice for organization and tenant management
* **Chat Component**: Enhanced with new subcomponents (reasoning, error, suggestions), display modes, and mobile support
* **UI Flows**: New process renderer component, start workflow action, and on load UI event
* **Microsoft Outlook**: New MS Graph data source for Outlook email integration
* **Send Notification**: New action type for sending/replying to emails via SMTP
* **Knowledge Base v2**: Updated UI, audit trail, and resource management
* **Container Apps**: Enhanced authentication flow and landing page
* **File Upload**: Improved progress indicators, drag and drop, and large file support
* **File Encrypt/Decrypt**: New document plugin actions for file encryption and decryption
* **User Management**: Password policy updates, DISABLED status, resend invitations, workspace environment type
* **Process Variables Compare**: Monaco diff editor for comparing variable values
* **New Kafka topics**: Multiple new topics added across document-plugin, integration-designer, admin, application-manager, email-gateway, authorization-system, and notification-plugin

***

### New microservice: Organization Manager

> [!NOTE]
>
> **Available starting with FlowX.AI 5.5.0**
>
> The Organization Manager is a new microservice responsible for organization and tenant management, including user registration, organization lifecycle, and platform component health monitoring.

**Infrastructure requirements:**

| Dependency | Details |
| - | - |
| PostgreSQL | Dedicated database for organization data |
| Redis | Caching and session management |
| Kafka | Event publishing (organization events topic) |
| Keycloak/IAM | Authentication and realm management |
| SpiceDB | Authorization via CAS lib |

> [card] [Organization Manager Setup](/5.1/setup-guides/organization-manager-setup)
>
> Complete setup and configuration guide for the Organization Manager microservice

***

### New Kafka topics

FlowX.AI 5.5.0 introduces new Kafka topics across multiple services.

#### Document-plugin Kafka topics

New topics for file encryption, decryption, bulk document persistence, and UI Flow session document persistence operations.

**Input topics (document-plugin consumes from these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Triggers file decryption operations |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Triggers file encryption operations |
| `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Triggers bulk document persistence operations |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway |

**Output topics (document-plugin publishes to these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Results from file decryption operations |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Results from file encryption operations |
| `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Results from bulk document persistence |
| `ai.flowx.eventsgateway.receive.document.v1` | Document upload progress notifications sent to events-gateway for SSE delivery |

#### Integration-designer Kafka topics

New topics for integration-designer in 5.5.0. Integration-designer now participates in the application sync mechanism for system and workflow resources.

> [!NOTE]
>
> The `sync.out.v1` and `correction-after-app-operation.response.v1` topics already exist since 5.1.x (used by admin). In 5.5.0, integration-designer becomes an additional producer on these shared response topics.

**New topics:**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync requests | Inbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System resource correction requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow resource correction requests | Inbound |
| `ai.flowx.build.runtime-data.v1` | Build runtime data | Outbound |
| `ai.flowx.license.usage.v1` | License usage tracking | Outbound |

**Existing topics (new producer in 5.5.0):**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.out.v1` | Sync operation responses | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | Correction operation responses | Outbound |

#### Admin Kafka topics

New topics for UI flow synchronization and correction operations in 5.5.0.

> [!NOTE]
>
> The `sync.process.in.v1`, `sync.business-rule.in.v1`, `sync.reusable-template.in.v1`, `sync.out.v1`, and `correction-after-app-operation` topics for process, business-rule, and reusable-template already exist since 5.1.x. Only the UI flow topics below are new in 5.5.0.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Inbound |

#### Application-manager Kafka topics

New outbound topics for resource synchronization and correction of system, workflow, and UI flow resources in 5.5.0.

> [!NOTE]
>
> Application-manager already produces sync and correction topics for process, business-rule, and reusable-template since 5.1.x. The topics below extend the same mechanism to system, workflow, and UI flow resources.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync | Outbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync | Outbound |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow resource sync | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Outbound |

#### Email-gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.save.audit.v1` | Audit event logging | Outbound |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Trigger process start from email events | Outbound |

#### Authorization-system Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.organization.events.v1` | Organization lifecycle events | Outbound |

#### Notification-plugin Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.resources-usages.refresh.v1` | Resource usages refresh events | Inbound |
| `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` | Sub-resource validation responses | Outbound |
| `ai.flowx.application-version.resources-usages.operations.bulk.v1` | Bulk resource usage operations | Outbound |

> [!NOTE]
>
> These topics are automatically created if your Kafka cluster has auto-topic creation enabled. For production environments, it is recommended to create them manually with appropriate partition counts and replication factors.

***

### New environment variables

#### Platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

#### Document-plugin variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) | document-plugin |

> [!NOTE]
>
> This setting affects all file uploads handled by the document-plugin. Configure alongside the existing Spring multipart settings (`SPRING_SERVLET_MULTIPART_MAXFILESIZE`, `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`) for consistent upload limits. See [Documents Plugin Setup](/5.1/setup-guides/documents-plugin-setup#multipart-upload-configuration).

#### Authorization-system variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client. Required for new deployments. | ` ` (empty) | authorization-system |

> [!WARNING]
>
> **New deployments only**: If this variable is not set, the `flowx-platform-authenticate` Keycloak client will have no redirect URIs and OAuth2 login will fail. Set this to your Designer and app URLs (e.g., `https://designer.yourcompany.com/*,https://app.yourcompany.com/*`).
>
> Existing deployments upgrading to 5.5.0 are not affected — the Liquibase migration that uses this variable has already run.

> [card] [Authorization System Setup](/5.1/setup-guides/authorization-setup-guide#keycloak-redirect-uris)
>
> See the full redirect URI configuration details

#### Email-gateway variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` | email-gateway |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` | email-gateway |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL` | TTL for cached MS Graph client instances | `1d` | email-gateway |

> [!NOTE]
>
> For complete email-gateway configuration including database, Redis, and Kafka settings, see the [Email Gateway Setup](/5.9/setup-guides/email-gateway-setup) guide.

***

### Compatibility

* **Authentication**: Default `SECURITY_TYPE` changed to `jwt-public-key` — deployments using opaque-token introspection require migration (see [breaking changes](#authentication-mechanism-change))
* **Renderer Updates**: Web and mobile SDKs include new Chat component features and UI Flows enhancements
* **Database**: No schema changes required for this upgrade
* **Mobile Support**: Chat component now available on iOS and Android renderers
* **New Service**: Organization Manager requires PostgreSQL, Redis, Kafka, and Keycloak infrastructure

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/migration-overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!WARNING]
>
> FlowX.AI v5.5.0 introduces a **critical breaking change** to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

## What's changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (`oauth2`) to JWT-based authentication (`jwt-public-key`). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — **Organization Manager** — has been introduced for organization and tenant management.

## Who is affected

> [!WARNING]
>
> **All deployments** are affected by the authentication mechanism change. The default `SECURITY_TYPE` value has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services.
>
> If you explicitly set `SECURITY_TYPE=oauth2` or rely on opaque-token introspection, you **must** update your configuration before upgrading.

## Migration process

**1. Back up your configuration**

Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.

**2. Update Keycloak service accounts**

Update your Keycloak service account client IDs to follow the new `flowx-{service-name}-sa` naming pattern. See [Update Keycloak service accounts](#update-keycloak-service-accounts) for the full mapping.

**3. Update environment variables**

Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.

**4. Deploy Organization Manager**

If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.

**5. Deploy and verify**

Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

***

## Authentication mechanism change

### Overview

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. Opaque-token introspection has been **removed entirely**.

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

### Changed default values

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

***

## Update Keycloak service accounts

Service account client IDs now follow the `flowx-{service-name}-sa` pattern. Update your Keycloak configuration to match:

| Service | New Client ID |
| - | - |
| Admin | `flowx-admin-sa` |
| Process Engine | `flowx-process-engine-sa` |
| Integration Designer | `flowx-integration-designer-sa` |
| Authorization System | `flowx-authorization-system-sa` |
| Runtime Manager | `flowx-runtime-manager-sa` |
| Scheduler Core | `flowx-scheduler-core-sa` |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager | `flowx-organization-manager-sa` |
| License | `flowx-license-sa` |
| Email Gateway | `flowx-email-gateway-sa` |

> [!WARNING]
>
> Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

***

## New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the **Organization Manager** microservice for organization and tenant management, user registration, and platform component health monitoring.

**Infrastructure requirements:**

* PostgreSQL
* Redis
* Kafka
* Keycloak/IAM
* SpiceDB

For full setup instructions, see the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility** for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

## Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your `SECURITY_TYPE` and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

> [!NOTE]
>
> Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

***

## Additional resources

> [card] [Update Environment Variables](./update-environment-variables-5.5)
>
> Per-service environment variable changes for v5.5.0

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions and deployment instructions

> [card] [IAM Configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution)
>
> Keycloak setup and service account configuration

> [card] [Release Notes v5.5.0](../v5.5.0-february-2026)
>
> Full release notes for v5.5.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/update-environment-variables-5.5

Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!NOTE]
>
> This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"dark"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

> [tab] Before (v5.4)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "oauth2"
>
> # Service account client ID (example for admin service)
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"
>
> # Token URI using main realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
> ```

> [tab] After (v5.5)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "jwt-public-key"
>
> # Service account client ID follows flowx-{service-name}-sa pattern
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"
>
> # Token URI now uses separate sa-realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
> ```

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

***

## Document plugin

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

> [!NOTE]
>
> **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` |

***

## Additional resources

> [card] [Migration Overview](./migration-overview)
>
> Full migration guide with Keycloak and service account changes

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions, Kafka topics, and infrastructure requirements


# FlowX.AI 5.5.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/v5.5.0-february-2026

Enhanced Chat component, UI Flows improvements, Microsoft Outlook integration, container app authentication, and platform management updates.

> [!NOTE]
>
> FlowX.AI 5.5.0 introduces significant enhancements to the Chat component, UI Flows capabilities, email integrations, and platform management features including Knowledge Base v2, user management improvements, and new document processing capabilities.

![Data Source types in FlowX 5.5.0](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_type_selector_all.png)

**What's new?**

> [tab] AI Platform
>
> AI-powered features and document processing enhancements.
>
> 📄 [**Extract Data from File**](#extract-data-from-file) - Configurable document and image extraction with LLM, OCR, and text parsing strategies\
> 📚 [**Knowledge Base v2**](#knowledge-base-v2) - Updated Knowledge Base with audit, resource management, and improved UI
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 renames "Extract Text from Document" to **Extract Data from File** and adds configurable extraction strategies, image input support, and signature detection. Choose between LLM, OCR, or text parsing strategies based on your document types, accuracy requirements, and cost constraints.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Extraction strategies
> > > >
> > > > Choose between LLM Model, OCR Engine, or Text Parsing for optimal accuracy/cost balance
> > >
> > > > [card] Image support
> > > >
> > > > Process images (JPG, PNG, TIFF) in addition to documents — automatic PDF conversion
> > >
> > > > [card] Image extraction options
> > > >
> > > > Extract data from embedded images or generate image descriptions
> > >
> > > > [card] Signature detection
> > > >
> > > > Detect and locate signatures within documents (LLM and OCR modes)
> >
> > > [tab] Configuration
> > >
> > > **Extraction strategies:**
> > >
> > > | Strategy | Best for | Speed | Cost | Accuracy |
> > > | - | - | - | - | - |
> > > | LLM Model | Complex layouts, handwritten text | Slow | High | High |
> > > | OCR Engine | Scanned documents | Medium | Medium | Medium |
> > > | Text Parsing | Clean digital PDFs | Fast | Free | Low–Medium |
> > >
> > > **Image extraction options (LLM and OCR only):**
> > >
> > > | Option | Description |
> > > | - | - |
> > > | Image Description | Generates text descriptions of images |
> > > | Image Content | Extracts text and data from images |
> > >
> > > > [!TIP]
> > > >
> > > > A new [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) covers backend service configuration, deployment sizing, and cost optimization.
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Knowledge Base v2**
>
> > [card] [Knowledge Base v2](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 updates the Knowledge Base with a refreshed UI, audit capabilities, and improved resource management. Knowledge Base entries now support versioning and provide better traceability for AI-powered features.
> >
> > > [tab] Key Features
> > >
> > > > [card] Updated UI
> > > >
> > > > Refreshed Knowledge Base interface with improved navigation and search
> > >
> > > > [card] Audit trail
> > > >
> > > > Track changes to Knowledge Base entries with full audit history
> > >
> > > > [card] Resource management
> > > >
> > > > Improved management of Knowledge Base resources and documents
> > >
> > > > [card] Version tracking
> > > >
> > > > Version-aware Knowledge Base entries tied to app versions
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] UI Flows
>
> Enhanced UI Flows with new components, actions, and chat improvements.
>
> 💬 [**Chat Component Enhancements**](#chat-component-enhancements) - New subcomponents, display modes, and mobile support\
> 🧭 [**UI Flows Breadcrumbs**](#ui-flows-breadcrumbs) - Navigation breadcrumbs for UI Flows\
> 📄 [**Process Renderer Component**](#process-renderer-component) - Embed process renderers within UI Flows\
> 🚀 [**Start Workflow Action**](#start-workflow-action) - Start workflows directly from UI Flows\
> ⚡ [**On Load UI Event**](#on-load-ui-event) - Execute actions when UI Flows load
>
> ### **Chat component enhancements**
>
> > [card] [Chat component enhancements](/5.9/ai-platform/chat-component)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 significantly enhances the Chat component with new subcomponents for reasoning, error handling, and suggestions. The component now supports multiple display modes and is available on mobile platforms.
> >
> > > [tab] New Subcomponents
> > >
> > > > [card] Reasoning display
> > > >
> > > > Show AI reasoning and thought process to users for transparency
> > >
> > > > [card] Error handling
> > > >
> > > > Graceful error display with retry options and helpful messages
> > >
> > > > [card] Suggestions
> > > >
> > > > Display suggested responses or actions to guide user interactions
> >
> > > [tab] Display Modes
> > >
> > > **Available display modes:**
> > >
> > > | Mode | Description |
> > > | - | - |
> > > | **Full screen** | Chat occupies the entire screen (available since v5.4.0) |
> > > | **Sidebar** | Chat appears as a collapsible sidebar |
> > > | **Floating** | Chat appears as a floating widget |
> > > | **Embedded** | Chat embedded within a container component |
> >
> > > [tab] Mobile Support
> > >
> > > The Chat component is now fully supported on mobile platforms:
> > >
> > > > [card] iOS
> > > >
> > > > Native iOS renderer support with optimized touch interactions
> > >
> > > > [card] Android
> > > >
> > > > Native Android renderer support with material design integration
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **UI Flows breadcrumbs**
>
> > [card] [UI Flows breadcrumbs](/5.9/docs/building-blocks/ui-flows#breadcrumbs)
> >
> > FlowX.AI 5.5.0 enhances the breadcrumbs navigation component for UI Flows, providing users with clear context of their current location and enabling quick navigation to parent screens.
> >
> > > [card] Navigation path
> > >
> > > Display the full navigation path within UI Flows
> >
> > > [card] Click navigation
> > >
> > > Navigate to any parent screen by clicking breadcrumb items
> >
> > > [card] Theme configuration
> > >
> > > Customize breadcrumb appearance through Admin theme settings
> >
> > > [card] Responsive design
> > >
> > > Breadcrumbs adapt to different screen sizes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process renderer component**
>
> > [card] [Process renderer component](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > > [tab] Overview
> > >
> > > Embed process renderers directly within UI Flows using the new Process Renderer component. This enables hybrid applications that combine UI Flow navigation with traditional process-based screens.
> >
> > > [tab] Key Features
> > >
> > > > [card] Process embedding
> > > >
> > > > Embed any process renderer within a UI Flow screen
> > >
> > > > [card] Data passing
> > > >
> > > > Pass data between UI Flows and embedded processes
> > >
> > > > [card] Event handling
> > > >
> > > > Handle process events within the UI Flow context
> > >
> > > > [card] Consistent styling
> > > >
> > > > Maintain consistent styling and navigation across UI Flows and processes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Start workflow action**
>
> > [card] [Start workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action)
> >
> > > [tab] Overview
> > >
> > > Start integration workflows directly from UI Flows using the new Start Workflow action. This enables UI Flows to trigger backend workflows without requiring a full process instance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow selection
> > > >
> > > > Select from available integration workflows
> > >
> > > > [card] Input mapping
> > > >
> > > > Map UI Flow data to workflow input parameters
> > >
> > > > [card] Response handling
> > > >
> > > > Handle workflow responses and update UI state
> > >
> > > > [card] Error handling
> > > >
> > > > Configure error handling for failed workflow executions
> >
> > UI EnhancementAll Deployments
>
> ### **On load UI event**
>
> > [card] [On load UI event](/5.9/docs/building-blocks/ui-designer/event-handlers#triggers)
> >
> > > [tab] Overview
> > >
> > > Execute actions automatically when UI Flow screens load using the new On Load UI Event. This enables initialization logic, data fetching, and setup operations when users navigate to a screen.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic execution
> > > >
> > > > Actions execute automatically when the screen loads
> > >
> > > > [card] Data initialization
> > > >
> > > > Fetch and initialize data when entering a screen
> > >
> > > > [card] Conditional logic
> > > >
> > > > Execute different actions based on conditions
> > >
> > > > [card] Loading states
> > > >
> > > > Manage loading states during initialization
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Integrations
>
> Email integrations, document processing, and Integration Designer updates.
>
> 📬 [**Microsoft Outlook Data Source**](#microsoft-outlook-data-source) - Native MS Graph integration for reading and sending Outlook emails\
> 📧 [**Send Notification Action**](#send-notification-action) - Send emails and reply to received emails directly from processes\
> 🔌 [**Integration Designer Improvements**](#integration-designer-improvements) - Query parameter encoding, config param autocomplete\
> 🔑 [**Security Details in Workflows**](#security-details-in-workflows) - Access user security details in workflow scripts\
> 🔐 [**File Encrypt and Decrypt**](#file-encrypt-and-decrypt) - Encrypt and decrypt files in the Documents Plugin
>
> ### **Microsoft Outlook data source**
>
> > [card] Microsoft Outlook data source
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces a new **Microsoft Outlook** data source type that connects to Outlook mailboxes via the Microsoft Graph API. Unlike Email Trigger (IMAP) and Email Sender (SMTP), this provides a unified data source for both reading and sending emails through native Outlook integration with Azure AD authentication.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> > > >
> > > > See the complete Microsoft Outlook data source documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified read & send
> > > >
> > > > Single data source supports Read Emails, Send Emails, or Read & Send Emails scopes
> > >
> > > > [card] Azure AD authentication
> > > >
> > > > Service account authentication with Tenant ID, Client ID, and Client Secret
> > >
> > > > [card] Email monitoring
> > > >
> > > > Monitor Outlook mailboxes and trigger processes automatically when emails arrive
> > >
> > > > [card] Send & reply
> > > >
> > > > Send new emails or reply to received emails with conversation thread support
> > >
> > > > [card] Attachment validations
> > > >
> > > > Configure allowed file types, max file size, and max file count for incoming emails
> > >
> > > > [card] Test connection
> > > >
> > > > Validate Azure AD credentials and MS Graph permissions before saving
> >
> > > [tab] Configuration
> > >
> > > **Azure AD Authentication:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Tenant ID | Azure AD tenant ID |
> > > | Client ID | Azure AD application (client) ID |
> > > | Client Secret | Azure AD client secret |
> > >
> > > **Scope Options:**
> > >
> > > | Scope | MS Graph Permissions Required |
> > > | - | - |
> > > | Read Emails | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
> > > | Send Emails | `Mail.Send` or `Mail.ReadWrite` |
> > > | Read & Send Emails | One read + one send permission |
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Send Notification action**
>
> > [card] Send Notification action
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces the Send Notification action — a new action type that sends emails directly from process nodes through SMTP, without routing through Kafka. Combined with the new Email Sender data source type, it enables processes to send new emails or reply to emails that triggered the process via Email Trigger.
> > >
> > > > [!NOTE]
> > > >
> > > > Existing notification templates configured for Kafka-based sending continue to work without modification.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> > > >
> > > > See the complete Send Notification action documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Email Sender data source
> > > >
> > > > New SMTP data source type in Integration Designer with SSL/TLS smart port defaults
> > >
> > > > [card] Reply to emails
> > > >
> > > > Reply to emails that triggered the process, maintaining conversation threads
> > >
> > > > [card] Send new emails
> > > >
> > > > Send new outbound emails to specified recipients with CC/BCC support
> > >
> > > > [card] Notification template updates
> > > >
> > > > New Email Server and Email Sender fields for direct SMTP delivery
> > >
> > > > [card] Attachments
> > > >
> > > > Attach files using static paths or process variable keys
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing Kafka-based notification templates continue to work unchanged
> >
> > > [tab] Configuration
> > >
> > > **Email Sender Data Source (new):**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | SMTP (only option) |
> > > | Server Host | SMTP server hostname |
> > > | SSL/TLS | Enable secure connection (default: on) |
> > > | Port | `587` (SSL/TLS on) or `465` (SSL/TLS off) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > >
> > > **Send Notification Action:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Notification Template | Select a template with Predefined Email Connection |
> > > | Reply to received emails | Toggle on to reply to the email that triggered the process |
> > > | Reply to Email Header | Process variable with original email headers (reply mode) |
> > > | Receivers | Recipient email addresses or process variables |
> > > | CC/BCC Receivers | Optional CC and BCC recipients |
> > > | Language | Process variable key for template language |
> > > | Attachments | File path or process variable key |
> > > | Template Data | JSON key-value pairs for dynamic template content |
> > >
> > > > [!TIP]
> > > >
> > > > Available on Send Message Task, Task, and User Task nodes.
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Integration Designer improvements**
>
> > [card] Integration Designer improvements
> >
> > FlowX.AI 5.5.0 adds URL encoding options for REST endpoint query parameters, improved error handling for invalid REST responses, and configuration parameter autocomplete in data source forms.
> >
> > > [card] Query parameter encoding
> > >
> > > Configure whether query parameter values are URL-encoded automatically or sent as-is (for pre-encoded values)
> >
> > > [card] REST Content-Type handling
> > >
> > > Improved error handling when REST endpoints return responses with unexpected Content-Type headers
> >
> > > [card] Config param autocomplete
> > >
> > > Type `$` in data source configuration fields to autocomplete configuration parameters or create new ones inline
> >
> > > [!NOTE]
> > >
> > > See [Integration Designer - Query parameters](/5.1/docs/platform-deep-dive/integrations/integration-designer#query-parameters) for details.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Security details in workflows**
>
> > [card] Security details in workflows
> >
> > Workflow scripts can now access `additionalData.securityDetails` to retrieve the current user's identity. This works when a workflow is started from a **Chat component**, a **UI Flow**, or a **manual run**. Sub-workflows inherit security details from their parent.
> >
> > Unlike processes, where security details are grouped by swimlane and role, workflows use a simplified flat structure:
> >
> > ```json theme={"dark"}
> > {
> >   "securityDetails": {
> >     "username": "user@email.com",
> >     "identifier": "keycloak-subject-id",
> >     "details": {
> >       "firstName": "John",
> >       "lastName": "Snow",
> >       "email": "user@email.com"
> >     }
> >   }
> > }
> > ```
> >
> > > [!NOTE]
> > >
> > > See [Extracting additional data in business rules](/5.1/docs/building-blocks/actions/business-rule-action/extracting-additional-data) for full details and code examples for both processes and workflows.
> >
> > New FeatureAll Deployments
>
> ***
>
> ### **File encrypt and decrypt**
>
> > [card] [File encrypt and decrypt](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files)
> >
> > FlowX.AI 5.5.0 adds new file encryption and decryption actions to the Documents Plugin, enabling processes to encrypt files before storage and decrypt them for authorized access.
> >
> > > [card] File encryption
> > >
> > > Encrypt files using configurable encryption algorithms before storage
> >
> > > [card] File decryption
> > >
> > > Decrypt files for authorized access within process flows
> >
> > InfrastructureAll Deployments
>
> ***

> [tab] Platform & Management
>
> User management, workspace configuration, rendering, and platform improvements.
>
> 🔐 [**Container App Authentication**](#container-app-authentication) - Authentication flow and landing page improvements\
> 🔑 [**Password Policy Updates**](#password-policy-updates) - Updated password complexity requirements\
> 🚫 [**User status DISABLED**](#user-status-disabled) - New DISABLED status for user accounts\
> 📧 [**Resend User Invitation**](#resend-user-invitation) - Resend invitations for pending users\
> 🏷️ [**Workspace Environment Type**](#workspace-environment-type) - Sandbox, Staging, and Production labels for workspaces\
> 🏢 [**Organization ID Propagation**](#organization-id-propagation) - Enhanced multi-tenant isolation\
> ⚡ [**Rendering Runtime UX**](#rendering-runtime-ux) - Runtime UX improvements for rendering\
> 🔍 [**Process Variables Compare**](#process-variables-compare) - Monaco diff editor for process variable values\
> 📧 [**Failed Email Trigger Details Page**](#failed-email-trigger-details-page) - Dedicated details page for failed email triggers\
> 📐 [**Data Model Sidepanel**](#data-model-sidepanel) - Redesigned attribute settings, inline add, and path copy
>
> ### **Container app authentication**
>
> > [card] [Container app authentication](/5.9/docs/saas/container-app-authentication)
> >
> > > [tab] Overview
> > >
> > > Enhanced authentication flow and landing page for generic container applications. Configure authentication providers, customize login pages, and manage user sessions with improved security and user experience.
> >
> > > [tab] Key Features
> > >
> > > > [card] Authentication providers
> > > >
> > > > Support for multiple authentication providers
> > >
> > > > [card] Custom landing page
> > > >
> > > > Customize the landing page for unauthenticated users
> > >
> > > > [card] Session management
> > > >
> > > > Improved session handling and token refresh
> > >
> > > > [card] SSO integration
> > > >
> > > > Seamless single sign-on integration
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Password policy updates**
>
> > [card] [Password policy updates](/5.1/setup-guides/access-management/configuring-an-iam-solution#password-policy)
> >
> > FlowX.AI 5.5.0 updates the password policy with stricter complexity requirements for improved security.
> >
> > **New requirements:**
> >
> > | Rule | Value |
> > | - | - |
> > | Minimum length | 8 characters |
> > | Maximum length | 64 characters |
> > | Complexity | Must include uppercase, lowercase, number, and special character |
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **User status DISABLED**
>
> > [card] [User status DISABLED](/5.9/docs/saas/inviting-users#user-statuses)
> >
> > FlowX.AI 5.5.0 introduces a new **DISABLED** user status. Administrators can now enable or disable user accounts through the **Enable** and **Disable** actions in the user management menu, providing better control over user access without deleting accounts.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Resend user invitation**
>
> > [card] [Resend user invitation](/5.9/docs/saas/inviting-users#resending-invitations)
> >
> > FlowX.AI 5.5.0 adds the ability to resend invitations for users with a **Pending** status, ensuring users who missed or lost their initial invitation can still complete onboarding.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Workspace environment type**
>
> > [card] [Workspace environment type](/5.1/docs/projects/workspaces#workspace-environment-type)
> >
> > FlowX.AI 5.5.0 adds an **Environment Type** dropdown to workspace configuration, allowing administrators to label workspaces as **Sandbox**, **Staging**, or **Production**. This provides clearer context when working across multiple environments.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Organization ID propagation**
>
> > [card] Organization ID Propagation
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 enhances multi-tenant isolation by propagating organization ID across more runtime contexts. This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
> >
> > > [tab] Key Changes
> > >
> > > > [card] Scheduler execution
> > > >
> > > > Organization ID added to scheduled job context
> > >
> > > > [card] Event listeners
> > > >
> > > > Organization ID propagated to event handlers
> > >
> > > > [card] Process instances
> > > >
> > > > Organization ID captured from initiator
> > >
> > > > [card] Audit trail
> > > >
> > > > Enhanced audit logging with organization context
> >
> > InfrastructureSaaS
>
> ***
>
> ### **Rendering runtime UX**
>
> > [card] Rendering runtime UX
> >
> > FlowX.AI 5.5.0 includes various rendering runtime UX improvements for better performance and user experience.
> >
> > > [card] Loading states
> > >
> > > Improved loading state indicators and skeleton screens
> >
> > > [card] Transition animations
> > >
> > > Smoother transitions between screens and states
> >
> > > [card] Error boundaries
> > >
> > > Better error handling with graceful degradation
> >
> > > [card] Performance
> > >
> > > Optimized rendering performance for complex UIs
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process variables compare**
>
> > [card] [Process variables compare](/5.9/docs/projects/runtime/active-process/update-process-variables#compare-view)
> >
> > FlowX.AI 5.5.0 introduces a Monaco diff editor for comparing process variable values, making it easier to identify changes between versions or states.
> >
> > > [card] Diff editor
> > >
> > > Side-by-side comparison of process variable values using Monaco diff editor
> >
> > > [card] Version comparison
> > >
> > > Compare variable values across different process versions
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Failed email trigger details page**
>
> > [card] [Failed email trigger details page](/5.9/docs/platform-deep-dive/integrations/email-trigger#failed-trigger-details-page)
> >
> > FlowX.AI 5.5.0 adds a dedicated details page for failed email triggers, providing better visibility into email processing failures and enabling faster troubleshooting.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Data Model sidepanel**
>
> > [card] Data Model sidepanel
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 redesigns the Data Model editing experience with a new attribute settings side panel, inline add-attribute buttons, and attribute path display. These improvements make it faster to create, configure, and reference data model attributes without switching between menus.
> > >
> > > > [card] [Process Data Model](/5.1/docs/building-blocks/process/data-model#data-model-interface)
> > > >
> > > > See the updated Process Data Model documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Attribute settings side panel
> > > >
> > > > Select any attribute to open a settings panel with type, validations, sensitive data, and reporting options
> > >
> > > > [card] Inline add attribute
> > > >
> > > > Add attributes directly on each data type — button shows on hover after the first attribute
> > >
> > > > [card] Attribute path copy
> > > >
> > > > View and copy the full key path for any attribute for use in business rules and UI bindings
> > >
> > > > [card] Selection highlights
> > > >
> > > > Selecting a data type or connector highlights its location on the canvas
> > >
> > > > [card] Default minimized panel
> > > >
> > > > The Data Types panel starts minimized by default for a cleaner canvas view
> > >
> > > > [card] Confirmation toasts
> > > >
> > > > Success notifications when adding new data types
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### Additional improvements
>
> * **Workflow logs milliseconds** — Workflow execution logs now display timestamps with millisecond precision
> * **Single select in table edit** — SDK enhancement for single-select dropdowns within editable table cells. See [Table component](/5.1/docs/building-blocks/ui-designer/ui-component-types/table#editable-rows)
> * **UI Flows action name optional** — Action names in UI Flows are now optional, reducing configuration overhead
> * **Data mappers editable JSON testing** — Improved JSON testing experience in data mappers with editable input fields
> * **Solutions page load optimization** — Solutions page now loads only projects, improving performance for container apps
> * **Security patches** — General security improvements across platform services

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.5.0](./deployment-guidelines-v5.5).
>
> ### Compatibility
>
> > [!WARNING]
> >
> > **Breaking change:** The default `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 services. Opaque-token introspection has been removed. See the [Deployment Guidelines](./deployment-guidelines-v5.5#breaking-changes) for migration steps.
>
> > [card] Upgrade path
> >
> > Upgrade from v5.4.0 — requires authentication mechanism migration (`SECURITY_TYPE` change)
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.5


# Deployment guidelines v5.6.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/deployment-guidelines-v5.6

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.77.0** | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 |
| **admin** | **10.66.0** | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 |
| **designer** | **10.127.3** | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **cms-core** | **10.43.0** | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 |
| **scheduler-core** | **10.31.0** | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 |
| **events-gateway** | **10.33.1** | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 |
| **notification-plugin** | **10.42.1** | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 |
| **document-plugin** | **10.46.0** | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 |
| **task-management-plugin** | **10.41.1** | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 |
| **data-search** | **10.30.1** | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 |
| **audit-core** | **10.40.0** | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 |
| **advancing-controller** | **10.33.1** | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 |
| **integration-designer** | **10.84.0** | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 |
| **application-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **runtime-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **data-sync** | **10.38.0** | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 |
| **authorization-system** | **10.51.0** | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 |
| **nosql-db-runner** | **10.34.0** | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 |
| **email-gateway** | **10.32.1** | 10.24.0 | 10.9.0 | - | - | - |
| **organization-manager** | **10.26.1** | 10.19.2 | - | - | - | - |
| **webhook-gateway** | **10.1.1** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **iOS renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 |
| **Android renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 |

### Plugins

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.2.3** | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 |
| **di-platform** | **10.3.0** | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 |
| **ai-platform-ai-developer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-connected-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-knowledge-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agents** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-conversations** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-models** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-tenants** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-planner** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-analyst** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-designer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agent-builder** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-binaries** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **knowledgebase** | **10.6.0** | TBD | - | - | - | - |
| **knowledgebase-rag** | **10.6.0** | 10.2.0 | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.0** | 10.2.0 | - | - | - | - |
| **mcp** | **10.6.0** | 10.2.0 | - | - | - | - |
| **doc-converter** | **10.2.2** | - | - | - | - | - |
| **doc-parser** | **10.5.1** | - | - | - | - | - |

> [!NOTE]
>
> **New in 5.6.0:** `webhook-gateway` is a new microservice for processing incoming webhooks. It handles webhook event ingestion and routing to process instances.

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.6.0 | Keycloak | 26+ |
| 5.6.0 | Kafka | 3.8 - 3.9 |
| 5.6.0 | PostgreSQL | 16 - 17 |
| 5.6.0 | Oracle Database | 21c, 23ai |
| 5.6.0 | MongoDB | 7 - 8 |
| 5.6.0 | Redis | 7.4 - 8.0 |
| 5.6.0 | Angular (Web SDK) | 20 |
| 5.6.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.6.0

### Key features and updates

> [card] Chat Driven Workflows
>
> Multi-turn AI conversations with session memory and intent classification

> [card] Incoming Webhooks
>
> Trigger processes from external HTTP POST requests via the new webhook-gateway service

> [card] Web Page Extractor
>
> Collect readable content from web page URLs with crawling and link following

> [card] Proxy Server Connections
>
> Route integration traffic through HTTP/HTTPS proxy servers

> [card] UI Flow Route Management
>
> Query parameters, route maps, and breadcrumb navigation for UI Flows

> [card] MCP Authentication
>
> BEARER and BASIC auth for MCP server connections

## Upgrading from v5.5.0

### Breaking changes

#### WorkspaceCreatedEvent ownership change

> [!WARNING]
>
> The `WorkspaceCreatedEvent` Kafka topic ownership has moved from `authorization-system` to `organization-manager`.

**What changed:**

* `organization-manager` now produces `WorkspaceCreatedEvent` messages
* `authorization-system` no longer produces these events
* Update your Kafka topic ACLs if you manage topic-level permissions

***

#### gRPC thread pool configuration

> [!WARNING]
>
> The default gRPC client thread pool sizes in AI Platform have been updated. Review your deployment configuration if you have custom thread pool settings.

***

### New environment variables

#### Integration Designer

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_WEBHOOKS_BASE_URL` | Base URL for webhook-gateway service communication | `http://webhook-gateway:80` | integration-designer |
| `FLOWX_WEB_CRAWLER_BASE_URL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80` | integration-designer |

#### NoSQL DB Runner

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100` | nosql-db-runner |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL` | Time-to-live for cached external MongoDB connections | `1d` | nosql-db-runner |

#### Process Engine

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts for failed operations | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Base delay between retries (ms) | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum delay between retries (ms) | `200` | process-engine |

#### Authorization System

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD` | Initial password for default realm admin user | *(none)* | authorization-system |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY` | Force password change on first login | `true` | authorization-system |

#### Application Manager

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_RESOURCE_ID_FIELD` | Resource ID field for proxy connection merge | `resourceId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_ID_FIELDS` | Flatten map ID fields for proxy connection merge | `resourceId, name` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection flatten map | `authorization.configuration` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_COMPARE_REMOVED_JSON_PATHS` | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_CONFLICT_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection conflict detection | `resourceId, resourceDefinitionId` | application-manager |

#### Data Search

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | data-search |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | data-search |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | data-search |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | data-search |

#### Email Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | email-gateway |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | email-gateway |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | email-gateway |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | email-gateway |

> [!NOTE]
>
> The SpiceDB and CAS client variables for `data-search` and `email-gateway` are required for authorization integration. These services now use the same SpiceDB-based authorization as other platform services.

#### Webhook Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for webhook registrations database | `jdbc:postgresql://postgresql:5432/webhook_gateway` | webhook-gateway |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` | webhook-gateway |
| `SPRING_DATASOURCE_PASSWORD` | Database password | *(required)* | webhook-gateway |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | OAuth2/OIDC server base URL | — | webhook-gateway |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | — | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account client ID | `flowx-webhook-gateway-sa` | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account client secret | *(required)* | webhook-gateway |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Kafka topic for process start events | `ai.flowx.core.trigger.start-for-event.process.v1` | webhook-gateway |

> [!NOTE]
>
> `webhook-gateway` is a **new microservice** in 5.6.0. It requires its own PostgreSQL database (`webhook_gateway`), Kafka access, Keycloak service account (`flowx-webhook-gateway-sa`), and SpiceDB connectivity.

***

### New Kafka topics

#### Document Plugin

New topic for UI Flow session document persistence.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway | Inbound |
| `ai.flowx.eventsgateway.receive.document.v1` | Document events sent to events-gateway for SSE delivery | Outbound |

#### Webhook Gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Triggers process starts from incoming webhook events | Outbound |

> [!NOTE]
>
> The Webhook Gateway is a **producer-only** service — it receives HTTP webhook requests and publishes process start events to Kafka. It does not consume from any Kafka topics.

#### UI flow session variable updates

New topic for propagating document upload results and workflow completion results to the process-engine, which updates UI flow session variables.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | UI flow session variable updates after document upload or workflow completion | Inbound (process-engine) / Outbound (document-plugin, integration-designer) |

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | process-engine |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Consumer group ID for UI flow updates | `ui-flow-update` | process-engine |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of consumer threads for UI flow updates | `6` | process-engine |

***

### Compatibility

* **SpiceDB**: Now required for `data-search` and `email-gateway` in addition to existing services
* **Renderer Updates**: Web and mobile SDKs include route management, start parameters, enum label display, and chat enhancements
* **Database**: The `start_params` column on `ui_flow_session` table has been renamed to `variables` (auto-migrated via Liquibase). The column now stores all session variables, including start parameters and updates from document uploads and workflow completions

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026

Conversational AI with memory and intent routing, incoming webhooks, proxy connections, unmanaged MongoDB, UI Flow session variables, chat history, and 28 bug fixes.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html)

FlowX.AI 5.6.0 brings **conversational AI** to your apps. Build multi-turn chat experiences where agents remember context, classify user intent, and navigate users to the right screen — all within a single workflow. On the integration side, **incoming webhooks** let external systems start processes via HTTP, **proxy connections** route traffic through intermediary servers, and **unmanaged MongoDB** connects FlowX to your existing database infrastructure. The UI layer gains **session variables**, **route management**, **chat history**, and **suggested prompts** for richer end-user experiences.

> [card] [For AI builders](#conversational-workflows)
>
> Chat Driven workflows, session memory, intent routing, and context retrieval

> [card] [For integrators](#incoming-webhooks)
>
> Incoming webhooks, proxy connections, unmanaged MongoDB, and base64 certificates

> [card] [For UI developers](#ui-flow-session-variables)
>
> Session variables, route management, chat history, suggested prompts, and new UI events

### What changed since 5.5.0

| 5.5.0 | 5.6.0 |
| - | - |
| Output Focused workflows only | + **Chat Driven** workflows with multi-turn memory |
| No event-driven process starts from external systems | **Incoming webhooks** with API key auth |
| FlowX-managed MongoDB only | + **Unmanaged MongoDB** — bring your own database |
| No conversation persistence | **Chat History** — browse and resume past sessions |
| Static chat empty state | **Suggested Prompts** — guide users with one-click starters |
| Certificate file paths only | **Base64 certificates** — paste content directly, no file mounts |
| No cross-page data in UI Flows | **Session variables** — persist data across pages and workflows |

***

**What's new?**

> [tab] AI Platform
>
> Build complete conversational AI pipelines — from understanding what the user wants, to retrieving the right context, to navigating them to the right screen.
>
> 💬 [**Conversational Workflows**](#conversational-workflows) - New Chat Driven workflow type for multi-turn conversations\
> 🧠 [**Memory Capabilities**](#memory-capabilities) - Automatic session memory with summarization across turns\
> 🎯 [**Intent Classification node**](#intent-classification-node) - Classify user messages and route to the right branch in one step\
> 🧭 [**Navigate in UI Flow**](#navigate-in-ui-flow) - Let the AI open forms and screens with contextual data\
> 🔍 [**Context Retrieval node**](#context-retrieval-node) - RAG search against Knowledge Bases without calling an LLM\
> 📄 [**Extract Data from File**](#extract-data-from-file) - Three extraction methods, image support, and signature detection\
> 🌐 [**Web Page Extractor**](#web-page-extractor) - Crawl web pages and extract readable content for AI processing
>
> See also: [Chat History](#chat-history), [Suggested Prompts](#chat-suggested-prompts), and [Markdown in chat](#markdown-in-chat-messages) in the **UI & Designer** tab.
>
> ### **Conversational Workflows**
>
> > [card] Conversational Workflows
> >
> > > [tab] Overview
> > >
> > > Chat Driven workflows are a specialized workflow type for multi-turn chat interactions. Unlike Output Focused workflows that process structured input/output, Chat Driven workflows manage ongoing dialogue — handling message exchange, session memory, and response routing through a dedicated Start node layout (Chat Session ID + User Message) and Custom Agent nodes with direct chat reply capability.
> > >
> > > ![Conversational workflow with Custom Agent configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_config.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> > > >
> > > > See the complete Conversational Workflows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multi-turn conversations
> > > >
> > > > Support for back-and-forth conversations with persistent context
> > >
> > > > [card] Intent routing
> > > >
> > > > Automatically classify user messages and route to appropriate workflow branches
> > >
> > > > [card] Session memory
> > > >
> > > > Built-in session memory with automatic summarization across conversation turns
> > >
> > > > [card] Chat UI components
> > > >
> > > > Dedicated chat component with error handling and shared state management
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Memory Capabilities**
>
> > [card] Memory Capabilities
> >
> > > [tab] Overview
> > >
> > > Conversational workflows include built-in session memory that automatically persists and retrieves conversation history. On each message, the system retrieves the last 3 turns of raw messages plus a summary of earlier exchanges, injecting them into the AI node's system prompt for context-aware responses.
> > >
> > > ![Memory tab showing conversation summary and history](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> > > >
> > > > See the complete Memory Capabilities documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic retrieval
> > > >
> > > > Last 3 turns + summary of earlier exchanges retrieved on each message via sessionId
> > >
> > > > [card] Smart summarization
> > > >
> > > > Older conversation history is automatically summarized to fit within context limits
> > >
> > > > [card] Per-node control
> > > >
> > > > Turn on memory per Custom Agent node with the **Use memory** toggle
> > >
> > > > [card] Memory tab in console
> > > >
> > > > View retrieved memory (raw turns + summary) in the workflow console log
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Intent Classification node**
>
> > [card] Intent Classification Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that combines AI-powered message classification with workflow branching in a single step. Define up to 10 intents with natural language descriptions, and the node classifies user messages and routes to the matching branch automatically — replacing the previous TEXT\_UNDERSTANDING + Condition two-node pattern.
> > >
> > > ![Intent Classification node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intent_classification_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> > > >
> > > > See the complete Intent Classification documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] AI + routing in one node
> > > >
> > > > Combines LLM classification and conditional branching — no separate Condition node needed
> > >
> > > > [card] Natural language conditions
> > > >
> > > > Define intents as plain-text descriptions instead of code expressions
> > >
> > > > [card] Conversation memory
> > > >
> > > > Optionally use past conversation context for more accurate classification
> > >
> > > > [card] Built-in fallback
> > > >
> > > > Automatic "If No Intent Matches" branch handles unrecognized inputs
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Navigate in UI Flow**
>
> > [card] Navigate in UI Flow
> >
> > > [tab] Overview
> > >
> > > A new workflow node exclusive to **Chat Driven** (conversational) workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — for example, the AI says *"Let me open your account details"* and the user sees a pre-filled form with data from the conversation.
> > >
> > > ![Navigate in UI Flow node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node)
> > > >
> > > > See the Navigate in UI Flow section in Conversational Workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Conversational context
> > > >
> > > > Navigate users to UI screens directly from a Chat Driven workflow conversation
> > >
> > > > [card] Dynamic parameters
> > > >
> > > > Pass workflow data to the destination screen using `${expression}` syntax
> > >
> > > > [card] Destination picker
> > > >
> > > > Select from the UI Flow's navigation tree with auto-populated query parameters
> > >
> > > > [card] Chat Driven only
> > > >
> > > > Available exclusively in the Actions category of conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval node**
>
> > [card] Context Retrieval Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that performs RAG (Retrieval-Augmented Generation) searches against Knowledge Bases without calling an LLM. Returns raw chunks with relevance scores and metadata, giving you full control over downstream processing. Supports hybrid, semantic, and keyword search with configurable re-ranking and metadata filters.
> > >
> > > Use Context Retrieval when you need to inspect, filter, or transform chunks before passing them to an LLM — for example, checking relevance scores before generating a response. For all-in-one RAG, use a Custom Agent node with a Knowledge Base attached instead.
> > >
> > > ![Context Retrieval node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the complete Context Retrieval documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] No LLM required
> > > >
> > > > Retrieves chunks directly — no AI generation step, lower latency and cost
> > >
> > > > [card] Multiple search types
> > > >
> > > > Hybrid, semantic, or keyword search with configurable relevance thresholds
> > >
> > > > [card] Metadata filters
> > > >
> > > > Filter chunks by user-defined metadata for scoped retrieval
> > >
> > > > [card] Re-ranking
> > > >
> > > > Optional re-ranking for improved result ordering
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > The workflow node formerly known as "Extract Text from Document" has been renamed to **Extract Data from File** and gained three new configurable settings: **Extraction Method** (LLM Model, OCR Engine, or Text Parsing), **Image Extraction** (Image Description or Image Contents), and **Detect Signatures**. The node now also accepts image files (JPG, PNG, TIFF) in addition to documents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Three extraction methods
> > > >
> > > > Choose between LLM Model (AI vision), OCR Engine (scanned docs), or Text Parsing (digital PDFs) per use case
> > >
> > > > [card] Image support
> > > >
> > > > Process JPG, PNG, and TIFF files alongside PDF, DOCX, XLSX, and PPTX
> > >
> > > > [card] Signature detection
> > > >
> > > > Identify signature areas within documents when using LLM or OCR extraction
> > >
> > > > [card] Moved to Tools category
> > > >
> > > > The node is now in the **Tools** category in the workflow node palette
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor**
>
> > [card] Web Page Extractor
> >
> > > [tab] Overview
> > >
> > > A new workflow node in the **Tools** category that collects readable content from web page URLs. Crawl documentation sites to build a Knowledge Base, scrape product pages for competitive analysis, or extract terms and conditions for compliance review. Supports static URL lists or dynamic URL generation, configurable crawling depth with link following, PDF extraction from linked documents, and adjustable scrape speed presets.
> > >
> > > ![Web Page Extractor node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> > > >
> > > > See the complete Web Page Extractor documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Static or dynamic URLs
> > > >
> > > > Provide a fixed list of up to 20 URLs or generate them dynamically from workflow data
> > >
> > > > [card] Link following
> > > >
> > > > Follow links on pages up to a configurable depth (0–10 levels)
> > >
> > > > [card] PDF processing
> > > >
> > > > Extract content from PDF files linked on crawled pages
> > >
> > > > [card] Speed presets
> > > >
> > > > Choose Slow, Moderate, Fast, or Custom with manual rate limit and concurrency
> >
> > All Deployments

> [tab] Integrations
>
> Connect FlowX to more systems — trigger processes from external events, route traffic through proxies, and query your own MongoDB databases.
>
> 🔗 [**Incoming Webhooks**](#incoming-webhooks) - Trigger processes from external HTTP POST requests\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Route integration traffic through proxy servers\
> 🗄️ [**Unmanaged MongoDB Datasource**](#unmanaged-mongodb-datasource) - Connect to externally managed MongoDB instances\
> 📧 [**Email Trigger Enhancements**](#email-trigger-enhancements) - Resource management, reply-to, and mock email testing\
> 🔐 [**MCP Authentication**](#mcp-authentication) - BEARER and BASIC auth support for MCP server connections\
> 📜 [**Base64 Certificate Support**](#base64-certificate-support) - Provide certificates as base64-encoded strings instead of file paths\
> 📊 [**CSV/Excel to JSON Conversion**](#csv/excel-to-json-conversion) - Download CSV and Excel files as structured JSON on the fly
>
> ### **Incoming Webhooks**
>
> > [card] Incoming Webhooks
> >
> > > [tab] Overview
> > >
> > > A new data source type and microservice (`webhook-gateway`) that allows external systems to trigger FlowX processes via HTTP POST requests. Create a Webhook data source in Integration Designer, connect it to a Message Start Event in your process, and FlowX generates a unique URL with API key authentication. When external systems POST to this URL, a process instance starts automatically with the webhook payload and headers.
> > >
> > > ![Active webhook trigger in Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)
> > >
> > > > [!NOTE]
> > > >
> > > > Requires deploying the new `webhook-gateway` microservice. See [Deployment Guidelines](./deployment-guidelines-v5.6) for configuration.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> > > >
> > > > See the complete Incoming Webhooks documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] API key authentication
> > > >
> > > > Each webhook gets a unique, cryptographically secure API key for authentication
> > >
> > > > [card] JSON payload forwarding
> > > >
> > > > Webhook body and headers are forwarded to the process instance as variables
> > >
> > > > [card] Manage Triggers integration
> > > >
> > > > Activate, deactivate, and monitor webhooks from the Manage Triggers UI
> > >
> > > > [card] API key regeneration
> > > >
> > > > Regenerate API keys without recreating the webhook configuration
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Proxy Server Connections**
>
> > [card] Proxy Server Connections
> >
> > > [tab] Overview
> > >
> > > Create reusable proxy connections in Integration Designer and attach them to RESTful System data sources. Route outbound API traffic through HTTP or HTTPS proxy servers for environments that require intermediary routing for security or compliance.
> > >
> > > ![Proxy Connection configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> > > >
> > > > See the complete Proxy Connections documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] HTTP and HTTPS proxies
> > > >
> > > > Configure HTTP or HTTPS proxy servers with optional basic authentication
> > >
> > > > [card] Reusable connections
> > > >
> > > > Create a proxy once and attach it to multiple RESTful System data sources
> > >
> > > > [card] Test connectivity
> > > >
> > > > Validate proxy configuration before saving with the built-in test function
> > >
> > > > [card] Config parameter support
> > > >
> > > > Use `${param}` syntax in host and port fields for environment-specific values
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Unmanaged MongoDB Datasource**
>
> > [card] Unmanaged MongoDB Datasource
> >
> > > [tab] Overview
> > >
> > > Connect to externally managed MongoDB instances as a data source in FlowX. Unlike the built-in FlowX Database (which provisions and manages MongoDB collections automatically), Unmanaged MongoDB connects to databases and collections you control — with the same CRUD operations, connection discovery, and configurable connection pooling. Requires MongoDB 6.0 or later.
> > >
> > > ![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> > > >
> > > > See the complete Unmanaged MongoDB documentation.
> >
> > All Deployments
>
> ***
>
> ### **Email Trigger Enhancements**
>
> > [card] Email Trigger Enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.6.0 enhances the Email Trigger with resource management capabilities, reply-to-email support, process instance tracking for email-triggered processes, and mock email testing for development.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Resource management
> > > >
> > > > Manage email trigger resources with proper lifecycle controls
> > >
> > > > [card] Reply-to-email
> > > >
> > > > Support for reply-to patterns in email-triggered workflows
> > >
> > > > [card] Process instances
> > > >
> > > > View and track process instances created from email triggers
> > >
> > > > [card] Mock email testing
> > > >
> > > > Test email-triggered processes with mock email content during development
> >
> > All Deployments
>
> ***
>
> ### **MCP Authentication**
>
> > [card] MCP Authentication
> >
> > > [tab] Overview
> > >
> > > MCP server connections now support **BEARER** and **BASIC** authentication methods. Configure auth credentials when adding an MCP data source to connect to secured MCP servers.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source)
> > > >
> > > > See the Adding MCP Data Source documentation.
> >
> > All Deployments
>
> ***
>
> ### **Base64 Certificate Support**
>
> > [card] Base64 Certificate Support
> >
> > > [tab] Overview
> > >
> > > RESTful system data sources now support providing keystore and truststore content as **base64-encoded strings** instead of file paths. A new "Certificate type" selector lets you choose between Base64 (default for new configurations) and Path (existing behavior). Additionally, keystore and truststore passwords now support `${configParam}` placeholder syntax for dynamic per-environment resolution.
> > >
> > > ![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#certificates)
> > > >
> > > > See the Integration Designer certificates documentation.
> >
> > All Deployments
>
> ***
>
> ### **CSV/Excel to JSON Conversion**
>
> > [card] CSV/Excel to JSON Conversion
> >
> > > [tab] Overview
> > >
> > > Download CSV, XLS, or XLSX files as structured JSON directly from the file download endpoints. The conversion happens on the fly using the `Accept: application/json` header — no new files are created in storage. Supports two output formats: an array of objects (one per row) or a columnar structure.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats#csv/excel-to-json-conversion)
> > > >
> > > > See the Document Conversion documentation.
> >
> > All Deployments

> [tab] UI & Designer
>
> Richer end-user experiences with session state, chat history, and navigation — plus Designer productivity improvements.
>
> 🗺️ [**UI Flow Route Management**](#ui-flow-route-management) - Configure routes, query parameters, and navigation in UI Flows\
> ▶️ [**UI Flow Start Parameters**](#ui-flow-start-parameters) - Pass parameters when starting UI Flows\
> 💾 [**UI Flow Session Variables**](#ui-flow-session-variables) - Persist data across pages from workflows and file uploads\
> 📋 [**Chat History**](#chat-history) - Browse and resume past chat conversations\
> 💡 [**Chat Suggested Prompts**](#chat-suggested-prompts) - Pre-configured prompt suggestions in chat empty state\
> 🖱️ [**onClick UI events**](#onclick-ui-events) - Client-side data updates on Button and Collection Prototype clicks\
> ✨ [**Monaco Editor Autocomplete**](#monaco-editor-autocomplete) - Autocomplete from config params in code editors\
> 📊 [**KB query results in workflow console**](#kb-query-results-in-workflow-console) - View retrieved chunks and relevance scores during workflow runs\
> 📎 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Upload multiple files simultaneously\
> ❌ [**DISMISS UI action**](#dismiss-ui-action) - Dismiss modals automatically after Start Workflow completes\
> 🎨 [**Process Variables UX**](#process-variables-ux-improvements) - UI/UX improvements for updating process variables\
> 🏷️ [**Enum label display**](#enum-label-display) - Show enum labels instead of codes in text components\
> 📬 [**Notification template usages**](#notification-template-usages) - See where notification templates are used\
> 📐 [**Side Panel in Data Model**](#side-panel-in-data-model) - Improved data model navigation with side panel\
> 👁️ [**On Display UI event**](#on-display-ui-event) - Re-trigger actions every time a screen becomes visible\
> 🪟 [**On Load event on Modal**](#on-load-event-on-modal) - Modal components now support On Load events\
> 🏗️ [**KB user-defined metadata**](#kb-user-defined-metadata) - Define custom metadata keys on Knowledge Base content sources\
> ⚙️ [**Config params in workflow conditions**](#config-params-in-workflow-conditions) - Use config params and user details in workflow Fork node expressions\
> 🎨 [**Branding settings grouping**](#branding-settings-grouping) - Reorganized branding settings page\
> ✍️ [**Markdown in chat messages**](#markdown-in-chat-messages) - Render formatted text, links, and lists in chat responses\
> 🔗 [**External Action dynamic URL**](#external-action-dynamic-url) - Use expressions in External Action URLs for dynamic navigation\
> 📬 [**Notification history**](#notification-history) - View sent notification details and search by process instance
>
> ### **UI Flow Route Management**
>
> > [card] UI Flow Route Management
> >
> > > [tab] Overview
> > >
> > > Define query parameters on root views (Pages, Modals), pass data between screens via URL query strings, and get automatic breadcrumb generation from the navigation graph. Navigate To actions support destination parameter mapping with `${expression}` syntax for dynamic values.
> > >
> > > ![Route parameters modal with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#route-management)
> > > >
> > > > See the Route Management section in UI Flows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Route parameters
> > > >
> > > > Define named query parameters on root views with default values and required flags
> > >
> > > > [card] Parameter passing
> > > >
> > > > Map data from process store to destination query parameters using JSON expressions
> > >
> > > > [card] Auto breadcrumbs
> > > >
> > > > Breadcrumbs auto-generate from the navigation graph with proper parameter handling
> > >
> > > > [card] Modal URL state
> > > >
> > > > Modals add `modalId` to URL — survives page reload and supports deep linking
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Start Parameters**
>
> > [card] UI Flow Start Parameters
> >
> > > [tab] Overview
> > >
> > > Pass initial data when launching a UI Flow. Define start parameters as a JSON object in the Designer's Run dialog, extract them from URL query strings in SaaS container apps, or send them in the API request body. Parameters are persisted on the session and available throughout the UI Flow lifecycle.
> > >
> > > ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#start-parameters)
> > > >
> > > > See the Start Parameters section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Session Variables**
>
> > [card] UI Flow Session Variables
> >
> > > [tab] Overview
> > >
> > > UI Flow sessions can now persist variables across all pages sharing the same session ID. Data from start parameters, workflow outputs, and file upload responses is automatically collected and merged into session variables. Reference them in component configurations using `${}` syntax. A new **Variables** tab in the Designer session console shows current values for debugging.
> > >
> > > ![Variables tab in UI Flow session console](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#session-variables)
> > > >
> > > > See the Session Variables section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **Chat History**
>
> > [card] Chat History
> >
> > > [tab] Overview
> > >
> > > Users can now browse and resume past chat conversations. Chat History displays a list of previous sessions grouped by time (Today, Yesterday, Previous 7 Days, Previous 30 Days, Older), with the ability to open any conversation and continue where they left off. Conversations are per-user with access control enforced.
> > >
> > > ![Chat History panel with conversation list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#chat-history)
> > > >
> > > > See the Chat History section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Chat Suggested Prompts**
>
> > [card] Chat Suggested Prompts
> >
> > > [tab] Overview
> > >
> > > The Chat component now supports pre-configured **Suggested Prompts** — pill buttons displayed below the welcome message in the chat empty state. Configure a title and up to 5 prompt options in the Designer. When a user clicks a suggestion, it is submitted as their message, starting the conversation immediately.
> > >
> > > ![Suggested Prompts in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#suggested-prompts)
> > > >
> > > > See the Suggested Prompts section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Monaco Editor Autocomplete**
>
> > [card] Monaco Editor Autocomplete
> >
> > > [tab] Overview
> > >
> > > Code editors in the Designer now provide autocomplete suggestions from your project's configuration parameters. This speeds up writing business rules and expressions that reference config params.
> > >
> > > > [card] [Documentation](/5.1/docs/projects/runtime/configuration-parameters-overrides)
> > > >
> > > > See the Configuration Parameters documentation.
> >
> > All Deployments
>
> ***
>
> ### **Process Variables UX improvements**
>
> > [card] Process Variables UX
> >
> > > [tab] Overview
> > >
> > > UI/UX improvements to the Update Process Variables experience, making it easier to view and edit runtime process data.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > > >
> > > > See the Update Process Variables documentation.
> >
> > All Deployments
>
> ***
>
> ### **onClick UI events**
>
> > [card] onClick UI events
> >
> > > [tab] Overview
> > >
> > > Buttons and Collection Prototypes now support **onClick** UI events — client-side JavaScript expressions that execute immediately when clicked, *before* any configured UI actions fire. Use them for instant local data updates without server roundtrips.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-events)
> > > >
> > > > See the UI Events documentation.
> >
> > All Deployments
>
> ***
>
> ### **KB query results in workflow console**
>
> > [card] KB Query Results
> >
> > > [tab] Overview
> > >
> > > The workflow run console now includes a **Knowledge Base** tab that displays retrieved chunks, relevance scores, content sources, and metadata when Custom Agent nodes query a knowledge base. This makes it easier to debug and tune RAG-powered workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows)
> > > >
> > > > See Using Knowledge Base in Workflows.
> >
> > All Deployments
>
> ***
>
> ### **Multi-file bulk upload**
>
> > [card] Multi-file Bulk Upload
> >
> > > [tab] Overview
> > >
> > > Upload multiple files simultaneously at runtime using the new [Multiple File Upload](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload) component. Supports drag-and-drop, batch selection, per-file validation, and progress tracking. Available in both process screens and UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **DISMISS UI action**
>
> > [card] DISMISS Action
> >
> > > [tab] Overview
> > >
> > > The Start Workflow UI action now includes a **Dismiss modal** checkbox. When enabled, the modal closes automatically after the workflow completes — removing the need for a separate close action.
> >
> > All Deployments
>
> ***
>
> ### **Enum label display**
>
> > [card] Enum Label Display
> >
> > > [tab] Overview
> > >
> > > Text components can now display the human-readable **label** of an enumeration value instead of the raw code. When a data key references an enumeration, the renderer resolves the selected code to its label at display time. Enumeration values are also prefetched from the data model before action resolution for improved performance.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations#displaying-enum-labels-in-text-components)
> > > >
> > > > See the Enumerations documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification template usages**
>
> > [card] Notification Template Usages
> >
> > > [tab] Overview
> > >
> > > Notification templates now show a **usages** modal that lists all processes and workflows referencing the template. This helps you understand the impact of changes before editing or deleting a template.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > > >
> > > > See the Managing Notification Templates documentation.
> >
> > All Deployments
>
> ***
>
> ### **Side Panel in Data Model**
>
> > [card] Side Panel in Data Model
> >
> > > [tab] Overview
> > >
> > > The Data Model editor now includes a side panel for easier navigation and editing of data model attributes, improving the workflow when working with large data models.
> >
> > All Deployments
>
> ***
>
> ### **On Display UI event**
>
> > [card] On Display UI event
> >
> > > [tab] Overview
> > >
> > > A new `onDisplay` event type that triggers every time a screen becomes visible — on initial load, when navigating back, or when a modal is dismissed. Unlike On Load (which fires once), On Display re-triggers on every view, making it ideal for refreshing data.
> > >
> > > Supported on Page, Zone, and Tab Bar components in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **On Load event on Modal**
>
> > [card] On Load event on Modal
> >
> > > [tab] Overview
> > >
> > > Modal components in UI Flows now support the On Load event and Start Workflow action. This enables data fetching when a modal opens, allowing you to load context-specific data for modal content.
> >
> > All Deployments
>
> ***
>
> ### **KB user-defined metadata**
>
> > [card] KB user-defined metadata
> >
> > > [tab] Overview
> > >
> > > Define custom metadata keys on Knowledge Bases and assign values to content sources. User-defined metadata enables filtering and scoping when searching chunks — for example, by department, document version, or region. Metadata values are propagated to the vector database and can be used as filters in the Context Retrieval workflow node.
> >
> > All Deployments
>
> ***
>
> ### **Config params in workflow conditions**
>
> > [card] Config params in workflow conditions
> >
> > > [tab] Overview
> > >
> > > Workflow Fork (condition) nodes can now access configuration parameters via `additionalData.applicationConfiguration` and authenticated user details via `additionalData.securityDetails` in their expressions. This enables environment-aware routing and user-based branching in integration workflows.
> >
> > All Deployments
>
> ***
>
> ### **Branding settings grouping**
>
> > [card] Branding settings grouping
> >
> > > [tab] Overview
> > >
> > > The branding settings page has been reorganized with improved grouping and layout, making it easier to find and configure branding options.
> >
> > All Deployments
>
> ***
>
> ### **Markdown in chat messages**
>
> > [card] Markdown in Chat Messages
> >
> > > [tab] Overview
> > >
> > > Chat message components in web renderers now support Markdown rendering. AI-generated responses can include formatted text, headings, links, code blocks, and lists — displayed with proper styling in the chat interface.
> >
> > All Deployments
>
> ***
>
> ### **External Action dynamic URL**
>
> > [card] External Action Dynamic URL
> >
> > > [tab] Overview
> > >
> > > External Action URLs now support `${expression}` syntax for dynamic values. Build destination URLs using process data, config params, or computed values — enabling context-aware external navigation from UI Flows.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-actions#external-ui-actions)
> > > >
> > > > See the UI Actions documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification history**
>
> > [card] Notification History
> >
> > > [tab] Overview
> > >
> > > New REST API endpoints on the notification plugin let you retrieve sent notification history. Query a paginated summary list filtered by app and optionally by process instance, or fetch full notification details by ID — including recipients, subject, body, and the source process/action that triggered it.
> > >
> > > * `GET /api/notification/summary` — paginated summary list with filtering and sorting
> > > * `GET /api/notification/{id}` — full notification details including body and recipients
> >
> > > [tab] Key Features
> > >
> > > > [card] Summary and detail views
> > > >
> > > > Paginated summary list for browsing, with full detail drill-down by notification ID
> > >
> > > > [card] Source tracking
> > > >
> > > > Each notification records which process, node, and action triggered it for full traceability
> >
> > All Deployments

> [tab] SaaS
>
> User management and branding improvements for SaaS deployments.
>
> 👤 [**Runtime User Invitations**](#runtime-user-invitations) - Invite runtime users directly to test projects\
> 🏢 [**Workspace Type Display**](#workspace-type-display) - See workspace type within Designer\
> 🎨 [**Container App Branding**](#container-app-branding) - Customize branding for SaaS container apps\
> 👥 [**Designer User Invitations**](#designer-user-invitations) - Updated invite modal for designer users
>
> ### **Runtime User Invitations**
>
> > [card] Runtime User Invitations
> >
> > > [tab] Overview
> > >
> > > Invite runtime users directly to test projects from within the Designer. Simplifies the process of granting test access without requiring full workspace-level permissions.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS
>
> ***
>
> ### **Workspace Type Display**
>
> > [card] Workspace Type Display
> >
> > > [tab] Overview
> > >
> > > The Designer now displays the workspace type (development, staging, production) directly within the workspace view, making it easier to identify your current environment.
> >
> > SaaS
>
> ***
>
> ### **Container App Branding**
>
> > [card] Container App Branding
> >
> > > [tab] Overview
> > >
> > > Customize your SaaS container app branding at the organization level — upload a custom logo, set primary and secondary colors, toggle the header, and configure the solutions page background.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/container-app-branding)
> > > >
> > > > See the Container App Branding documentation.
> >
> > SaaS
>
> ***
>
> ### **Designer User Invitations**
>
> > [card] Designer User Invitations
> >
> > > [tab] Overview
> > >
> > > The invite modal for designer users has been redesigned with clearer role selection, group assignment, and a streamlined layout for inviting multiple users.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS

> [tab] Bug Fixes
>
> ## Bug fixes
>
> ### Core Platform
>
> * **Authorization-system Oracle DB startup** — Fixed an issue where the authorization-system service failed to start when using Oracle as the configured database.
> * **Process definition merge timing** — Fixed a race condition where the process definition was updated before the merge was finalized.
> * **Theme import with builds** — Fixed an issue where themes were not included when importing builds.
> * **Library import permissions** — Fixed an issue where importing a library into a workspace redirected to a 403 error page.
> * **App version reimport** — Fixed an error that occurred when reimporting an app version (project or library).
> * **Email resend after URL expiry** — Fixed an issue where the resend email endpoint returned 200 OK but no email was sent after the URL expired.
> * **Platform status discovery** — Fixed an authorization error when trying to force discover platform status.
> * **Runtime roles in permissions** — Fixed inconsistent runtime roles display in the permissions dropdown.
>
> ### AI Platform & Workflows
>
> * **gRPC thread pool sizing** — Fixed under-provisioned gRPC client thread pools that caused socket timeouts and dropped requests in production.
> * **API error trace IDs** — API errors now include a reference to the active traceID for easier debugging.
> * **Cross-project resource copy** — Fixed an issue where copying a workflow resource to another project did not include LDM objects.
> * **Multi-instance mappings** — Fixed a 400 error when saving multi-instance mappings in data mappers.
> * **Email trigger mock testing** — Fixed errors when starting a process from a build with mock email content.
> * **Multiple start nodes with email trigger** — Fixed an issue where only one start option was displayed when a process contained multiple start nodes with email triggers.
>
> ### Renderers & UI
>
> * **Angular input field crash** — Fixed an issue where pressing Enter in an input field caused the Angular UI to crash.
> * **Floating Chat interaction blocking** — Fixed an issue where the floating chat component blocked all interaction with page content while open.
> * **S3 internal bucket error** — Fixed an error when the integration-designer downloads files from document-plugin via downloadPath.
> * **File upload second attempt** — Fixed an issue where upload requests were not made when uploading a second file.
> * **UI Flow analytics** — Fixed issues where analytics events were not visible and not saved for Navigate-to action types.
> * **Task management column selection** — Fixed an issue where the Last Updated column remained selected in task management.
> * **Task Manager theming and UX** — Multiple fixes for Task Manager theming, dropdown display, comment field styling, and user assignment behavior.
> * **Toggle/checkbox label alignment** — Fixed an issue where the switch toggle/checkbox or label shifted position when in an error state.&#x20;
> * **Query parameters lost after refresh** — Fixed an issue where URL query parameters were lost after page refresh in UI Flows.&#x20;
> * **SSE connection management** — Fixed multiple issues where SSE connections were opened twice or not closed properly after messages were received.&#x20;
> * **Modal layering** — Fixed incorrect layering when a loader modal was displayed on top of another modal.&#x20;
> * **Card theming overrides** — Fixed an issue where card theming overrides were not applied when the card was collapsed.&#x20;
> * **On Display workflow triggering** — Fixed an issue where past On Display workflows were not re-triggered on page refresh.&#x20;
>
> ### Knowledge Base
>
> * **KB metadata handling** — Fixed multiple issues with Knowledge Base user-defined metadata: empty properties on content source creation, metadata not available for content sources added through apps, and incorrect cleanup when deleting metadata keys.&#x20;

> [tab] Info
>
> ## Additional information
>
> ### At a glance
>
> This release includes **30+ new features and enhancements** across AI Platform, Integrations, UI & Designer, and SaaS — plus **28 bug fixes** spanning Core Platform, AI/Workflows, Renderers, and Knowledge Base.
>
> ***
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6).
>
> For new environment variables and Kafka topics, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6#new-environment-variables).
>
> ### Changes to be aware of
>
> > [!NOTE]
> >
> > FlowX.AI 5.6.0 is a SaaS-managed release — deployment-level changes (infrastructure, Kafka topics, service configuration) are handled automatically by FlowX. The items below are listed for transparency and for future reference when on-prem support ships in 5.7+.
>
> #### API change (action required if you use this endpoint)
>
> > [!WARNING]
> >
> > **Process definition start metadata endpoint renamed** — `GET /api/process-definition/{uuid}/get-input-json` has been renamed to `GET /api/process-definition/{uuid}/get-start-metadata`. Update any API clients or custom integrations that call this endpoint directly.
> >
> > The response now includes an additional `hasEmailTriggerStart` boolean field.
>
> #### Infrastructure changes (managed by FlowX on SaaS)
>
> * **gRPC thread pool configuration** — Default gRPC client thread pool sizes have been updated for better production throughput.
> * **WorkspaceCreatedEvent ownership** — Kafka topic ownership moved from `authorization-system` to `organization-manager`.
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.5.0 — if you call `get-input-json` directly, update to `get-start-metadata`. All other changes are managed automatically on SaaS.
>
> > [card] [Component versions](./deployment-guidelines-v5.6#component-versions)
> >
> > See the Deployment Guidelines for the full component version matrix


# Deployment guidelines v5.7.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7

Component versions, environment variables, and configuration changes for FlowX.AI 5.7.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.96.0** | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 |
| **admin** | **10.83.0** | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 |
| **designer** | **10.164.0** | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **cms-core** | **10.58.0** | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 |
| **scheduler-core** | **10.45.0** | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 |
| **events-gateway** | **10.47.0** | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 |
| **notification-plugin** | **10.56.0** | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 |
| **document-plugin** | **10.64.0** | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 |
| **task-management-plugin** | **10.57.0** | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 |
| **data-search** | **10.44.0** | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 |
| **audit-core** | **10.54.0** | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 |
| **advancing-controller** | **10.45.0** | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 |
| **integration-designer** | **10.113.0** | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 |
| **application-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **runtime-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **data-sync** | **10.50.0** | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 |
| **authorization-system** | **10.68.0** | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 |
| **nosql-db-runner** | **10.48.0** | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 |
| **email-gateway** | **10.47.0** | 10.32.1 | 10.24.0 | 10.9.0 | - | - |
| **organization-manager** | **10.44.0** | 10.26.1 | 10.19.2 | - | - | - |
| **webhook-gateway** | **10.15.0** | 10.1.1 | - | - | - | - |
| **license** | **10.36.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |

### Plugins

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 |
| **ai-platform-ai-assistant** | **10.6.2** | - | - | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 |
| **ai-platform-ai-developer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-connected-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-knowledge-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agents** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-conversations** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-tenants** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-planner** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-analyst** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-designer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agent-builder** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-binaries** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **embedder** | **10.6.2** | - | - | - | - | - |
| **knowledgebase-rag** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **mcp** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **doc-converter** | **10.2.3** | 10.2.2 | - | - | - | - |
| **doc-parser** | **10.6.2** | 10.5.1 | - | - | - | - |
| **web-crawler** | **10.3.2** | - | - | - | - | - |
| **data-privacy** | **10.0.8** | - | - | - | - | - |
| **speech-to-text** | **10.3.3** | - | - | - | - | - |
| **modpod** | **10.0.7** | - | - | - | - | - |

> [!NOTE]
>
> **Note:** The `ai-platform-models` service has been removed in 5.7.0. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers) within the Organization Manager.

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.7.0 | Keycloak | 26+ |
| 5.7.0 | Kafka | 3.8 - 3.9 |
| 5.7.0 | PostgreSQL | 16 - 17 |
| 5.7.0 | Oracle Database | 21c, 23ai |
| 5.7.0 | MongoDB | 7 - 8 |
| 5.7.0 | Redis | 7.4 - 8.0 |
| 5.7.0 | Elasticsearch | 8 |
| 5.7.0 | Angular (Web SDK) | 20 |
| 5.7.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> The following versions of third-party dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

***

## Self-hosted deployment changes

> [!WARNING]
>
> **First on-premises release since 5.4.0.** This section covers critical configuration changes for self-hosted (on-premises) deployments.

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **Fresh install** | Supported | Guided setup flow on first launch. See [Organization Manager setup](/5.1/setup-guides/organization-manager-setup). |
| **5.1.x LTS** | Supported | Requires Organization ID on all 19 services. Liquibase migrates active process instances and realm data. Inactive instances require separate handling by FlowX. See details below. |
| **5.2 - 5.4** | FlowX-assisted only | These versions may have partial realm or organization changes. Contact your FlowX representative for a custom migration plan. Do **not** follow the 5.1.x upgrade path. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

### Organization ID (mandatory for upgrades)

The Organization ID is how FlowX identifies your installation. How it is obtained depends on your deployment path:

* **Fresh install:** The Organization ID is created automatically during the guided setup flow (Designer first-launch screen). No manual configuration needed.
* **Upgrade from 5.1.x:** FlowX registers your organization in the SaaS licensing infrastructure and provides an Organization ID (UUID). Set `ORGANIZATION_ID` on **all 19 services** before deploying 5.7.0 images — Liquibase migrations use it to replace the default organization.

```yaml theme={"dark"}
# Example — set on every service
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

**Affected services (all 19):** process-engine, admin, audit-core, authorization-system, advancing-controller, events-gateway, cms-core, scheduler-core, data-search, document-plugin, nosql-db-runner, notification-plugin, task-management-plugin, integration-designer, organization-manager, email-gateway, application-manager, runtime-manager, license.

> [!WARNING]
>
> Do **not** deploy 5.7.0 images without setting `ORGANIZATION_ID` on upgrade scenarios. Services will fail to start if Liquibase migrations cannot find the organization ID.

> [!NOTE]
>
> **Active vs inactive instances.** Liquibase migrations automatically update the Organization ID on **active process instances** only. Inactive or archived instances require separate migration handled by the FlowX team during guided deployment. Contact your FlowX representative for details.

### License service (new)

Self-hosted deployments must configure the License service to connect to FlowX SaaS for license validation and usage reporting. See the [License service setup guide](/5.9/setup-guides/license-engine-setup) for complete configuration.

### IAM / Keycloak changes

FlowX.AI now uses a **two-realm architecture** in Keycloak and **JWT public key validation** (replacing opaque-token introspection). These changes were introduced in 5.5.0 (SaaS) and are now relevant for self-hosted deployments.

* **Token validation**: `security.type` switches from `oauth2` to `jwt-public-key` on all services
* **Service accounts realm**: A dedicated realm (`00000002-0002-4002-8002-000000000002`) holds all service account clients, separate from the user realm
* **Organization manager**: Now a required dependency for all services (provides realm resolution)
* **`flowx-platform-authorize` client**: No longer needed — remove from Keycloak
* **Master realm credentials**: The authorization-system service needs Keycloak admin access for realm migrations. If you cannot provide admin credentials, see [Manual Keycloak configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).
* **SMTP**: Must be configured in Keycloak for password reset and user invitations

For complete IAM setup instructions, see the [Configuring an IAM solution](/5.1/setup-guides/access-management/configuring-an-iam-solution) guide.

***

## Environment info deprecation

The **Configure Environment Info** feature (`PATCH /api/platform/environment`) is deprecated and removed. Environment name is now set during organization registration. The following are no longer used:

* `FLOWX_CLIENT_NAME` environment variable
* `FLOWX_ENVIRONMENT_NAME` environment variable
* `environmentDetails` section in the `/api/init` response

***

## Kafka integration changes

### Fx-Organization-Id header (mandatory)

All FlowX Kafka consumers now validate the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected with a non-retryable `MissingKafkaHeaderException`.

> [!WARNING]
>
> **Action required for custom Kafka integrations.** If you have custom Kafka producers that publish directly to FlowX topics (starting processes, sending task events, responding to engine requests), you must add the `Fx-Organization-Id` header to every message. Set it to the Organization UUID (`ORGANIZATION_ID` value).
>
> ```java theme={"dark"}
> producerRecord.headers().add("Fx-Organization-Id",
>     organizationId.getBytes(StandardCharsets.UTF_8));
> ```
>
> See the [Creating a Kafka producer](/5.1/docs/platform-deep-dive/integrations/creating-a-kafka-producer#important-headers) guide for details.

### New Kafka topics

| Topic | Environment Variable | Producer | Consumer | Description |
| - | - | - | - | - |
| `ai.flowx.llm.config.changed.v1` | `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | organization-manager | integration-designer, AI Python services | Broadcast when LLM provider or model configuration changes at the organization level |

***

## Environment variables

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `ORGANIZATION_ID` | Organization UUID provided by FlowX. Required on all services for upgrades. Fresh installs get this automatically via the setup flow. | - | all services |
| `FLOWX_LICENSE_KEY` | License key for FlowX SaaS connection | - | license |
| `FLOWX_LICENSE_AUTHSERVERURL` | FlowX SaaS auth URL | - | license |
| `FLOWX_LICENSE_SERVERURL` | FlowX SaaS license API URL | - | license |
| `FLOWX_ORG_MANAGER_URL` | Organization Manager service URL for LLM provider configuration. Required on all Python AI services. | - | planner, ai-developer, ai-analyst, ai-designer, agent-builder, knowledgebase-rag, embedder, knowledgebase |
| `SECURITY_MASTERREALM_CLIENTID` | Master realm admin client ID for Keycloak management | `admin-cli` | authorization-system |
| `SECURITY_MASTERREALM_NAME` | Keycloak master realm name | `master` | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username for realm migrations | - | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password for realm migrations | - | authorization-system |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` | all services |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL for security lib | `http://organization-manager:80` | all services |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `60` | organization-manager |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `30` | organization-manager |
| `FLOWX_SPEECH_TO_TEXT_BASE_URL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` | integration-designer |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Topic for LLM config change notifications | `ai.flowx.llm.config.changed.v1` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys at rest. **Change from default in production.** | `default-dev-key-change-in-prod` | organization-manager |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required on on-prem deployments. | - | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required on on-prem deployments when the FlowX generic container app is deployed. | - | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If empty, derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` | organization-manager |
| `DEFAULT_ORGANIZATION_NAME` | Fallback organization code used by the Designer web app during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present. Required on on-prem — set to the organization code registered with FlowX. | - | designer |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for Oracle Database schema discovery responses cached for the SQL editor. | `24h` | integration-designer |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools used by Oracle Database data sources. | `100` | nosql-db-runner |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached JDBC connection pools. | `1d` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per Oracle Database data source. | `5` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout for Oracle Database data sources. | `10` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses for Oracle Database operations. | `1000` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout for Oracle Database operations. | `30` | nosql-db-runner |

### Removed environment variables

> [!WARNING]
>
> **For upgrades:** Remove these variables only **after** the Liquibase migrations have completed successfully. If you remove them before starting services for the first time on 5.7.0, the migrations may fail. The recommended sequence is: (1) add new variables, (2) deploy 5.7.0 images, (3) let migrations run, (4) verify services are healthy, (5) remove old variables in a follow-up deployment.

| Environment Variable | Reason | Component |
| - | - | - |
| `FLOWX_CLIENT_NAME` | Replaced by org code from registration | process-engine |
| `FLOWX_ENVIRONMENT_NAME` | Replaced by env name from registration | process-engine |
| `AI_SERVICE_MODELS_ENDPOINT` | The Models microservice (port 9104) has been removed. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers). Remove this service from your deployment. | ai-platform (all Python services) |
| `SECURITY_OAUTH2_REALM` | Replaced by per-organization realm resolution. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | Opaque-token introspection client no longer needed. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | Opaque-token introspection client secret no longer needed. | all services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_*` | Entire opaque-token introspection config removed. | all services |


# FlowX.AI 5.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/v5.7.0-april-2026

Single-org on-premises deployment, custom React components, AI providers self-service, chat-based UI Flows, voice input, end-user access management, and advanced query builder.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

FlowX.AI 5.7.0 makes on-premises deployment a first-class experience. **Single-org deployment** is now the default mode — configure your organization once, connect to FlowX licensing, and you're running. For builders, **Custom Components** let you write React code directly in the Designer, **AI Providers** configuration gives organizations self-service control over their LLM setup, and **Chat-based UI Flows** simplify conversational experiences. For organization admins, **End-user access management** separates runtime users, roles, and groups from Designer users.

> [card] [For platform teams](#single-org-deployment)
>
> Single-org deployment, license service, organization setup flow

> [card] [For builders](#custom-components)
>
> Custom React components, AI provider config, chat-based UI Flows, voice input

> [card] [For admins](#end-user-access-management)
>
> End-user access management, runtime roles, and groups

### What changed since 5.6.0

| 5.6.0 | 5.7.0 |
| - | - |
| SaaS-focused deployment | + **Single-org on-premises** as the default mode |
| Built-in UI components only | + **Custom React Components** with code editor and dependencies |
| AI models configured by FlowX | + **AI Providers self-service**: OpenAI (FlowX Managed or BYOK), custom URL, Defaults & Fallbacks per workspace type |
| Chat workflow set per component | + **Chat-based UI Flows**: set one workflow for the entire UI Flow |
| Text-only chat input | + **Voice input** for chat conversations |
| No audio processing in workflows | + **Speech to Text** node for transcription and text-to-speech |
| Runtime users mixed with Designer users | + **End-user access management**: separate org-level lists for end-users, roles, and groups, with CSV bulk invite |
| Basic query filters | + **Advanced Query Builder** for database operations |
| MongoDB-only database data sources | + **Oracle Database** as a new data source type with schema-aware SQL editor |
| Fixed search strategy for KB retrieval | + **Context Retrieval**: configurable search type (Hybrid/Semantic/Keyword) and re-ranking |
| Equality-only metadata filters, AND logic | + **Knowledge Base filter builder** with typed operators and AND/OR grouping; **Content Sources** tab renamed to **Stores** |
| Basic merge modal | + **Merge conflicts UX**: redesigned modal, diff viewer theme, keyboard support |

***

**What's new?**

> [tab] Platform
>
> FlowX 5.7.0 introduces single-org deployment as the default mode for on-premises installations, with self-service licensing, organization management, and runtime access controls.
>
> 🏢 [**Single-org deployment**](#single-org-deployment) - On-premises deployment with automatic organization setup\
> 🔑 [**License service**](#license-service) - Connect to FlowX SaaS for license validation and usage reporting\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level end-users, roles, and groups, separate from Designer users
>
> ### **Single-org deployment**
>
> > [card] Single-org deployment
> >
> > > [tab] Overview
> > >
> > > Self-hosted deployments now run as single-organization systems by default. FlowX registers your organization in the SaaS licensing infrastructure, provides an Organization ID, and your deployment connects to FlowX for license validation and usage reporting. The Designer guides you through a setup flow on first launch: enter a token, name your environment, and create your admin user.
> > >
> > > > [card] [Documentation](/5.1/setup-guides/organization-manager-setup#organization-id-configuration)
> > > >
> > > > See the Organization Manager setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Guided setup flow
> > > >
> > > > Designer walks you through organization registration on first launch
> > >
> > > > [card] Organization ID
> > > >
> > > > Mandatory on all services for Liquibase migrations on upgrades
> > >
> > > > [card] License connectivity
> > > >
> > > > On-premises license service connects to FlowX SaaS for validation and usage
> > >
> > > > [card] Multi-org features hidden
> > > >
> > > > Registration, org selection, and org switching are not available on-prem
> > >
> > > > [card] Explicit web app URLs
> > > >
> > > > Designer and Runtime URLs are configured via dedicated on-prem env vars on organization-manager, replacing hard-coded org-code lookup
> >
> > Major FeatureSelf-Hosted
>
> ***
>
> ### **License service**
>
> > [card] License service
> >
> > > [tab] Overview
> > >
> > > The License service is the bridge between your self-hosted deployment and FlowX SaaS. It validates your platform license, reports usage data, and ensures your subscription is active. Configure it with the license key and server URLs provided by FlowX during organization registration.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> > > >
> > > > See the License service setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] License validation
> > > >
> > > > Continuous license sync with FlowX SaaS
> > >
> > > > [card] Usage reporting
> > > >
> > > > AI node execution consumption reported to FlowX
> > >
> > > > [card] Organization events
> > > >
> > > > Listens to organization lifecycle events via Kafka
> > >
> > > > [card] Setup guide
> > > >
> > > > Complete setup guide with PostgreSQL, Kafka, Redis, and SpiceDB configuration
> >
> > Self-Hosted
>
> ***
>
> ### **End-user access management**
>
> > [card] End-user access management
> >
> > > [tab] Overview
> > >
> > > Organization admins can now manage the people who use published solutions separately from Designer users. A new **Access Management** section at the organization level holds three lists — **End-Users**, **End-Users Roles**, and **End-Users Groups** — each with its own permissions. Invite end users individually or import many at once from a CSV template, define roles that describe runtime access, and organize users into groups with custom attributes for filtering.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> > > >
> > > > See the End-user access management setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Separate end-user list
> > > >
> > > > End-Users are kept distinct from Designer users, with their own read/write permissions
> > >
> > > > [card] End-user roles
> > > >
> > > > Define named roles that describe runtime access at the organization level
> > >
> > > > [card] End-user groups
> > > >
> > > > Group users by department, region, or any attribute, and assign roles to the whole group
> > >
> > > > [card] Bulk invite
> > > >
> > > > Invite many users at once from a CSV template with names and attributes
> >
> > All Deployments
>
> ***

> [tab] AI & Chat
>
> Self-service AI provider configuration, chat-based UI Flows, AI Triggers, and voice input for conversational experiences.
>
> 🤖 [**AI Providers**](#ai-providers) - Organization-level LLM provider and model configuration\
> 💬 [**Chat-based UI Flows**](#chat-based-ui-flows) - Set a conversational workflow for the entire UI Flow\
> 🎤 [**Voice input**](#voice-input) - Speech-to-text input in chat conversations\
> ⏹️ [**Stop agent response**](#stop-agent-response) - Cancel an in-progress agent reply from the chat input\
> 🗣️ [**Speech to Text node**](#speech-to-text-node) - Transcription and text-to-speech workflow node\
> ⚡ [**AI Triggers**](#ai-triggers) - Named message templates for launching conversational workflows with context\
> 🧩 [**UI Flow Context**](#ui-flow-context) - Pass UI state from a Page to a conversational workflow\
> 🎯 [**Recommended prompts**](#recommended-prompts) - AI-generated follow-up suggestions in chat conversations\
> 🔎 [**Context Retrieval enhancements**](#context-retrieval-enhancements) - Configurable search type and re-ranking\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - Stores rename, typed metadata filters, AND/OR grouping\
> 🌐 [**Web Page Extractor enhancements**](#web-page-extractor-enhancements) - URL filtering, crawl depth, and file downloads
>
> ### **AI Providers**
>
> > [card] AI Providers
> >
> > > [tab] Overview
> > >
> > > Organizations can now configure their own AI providers and assign models at the organization level. Configure **OpenAI** (Bring Your Own Key or FlowX Managed) or **Azure OpenAI** for deployment-based access to GPT models, enable specific models, and assign default and fallback models per AI capability and workspace type (Sandbox, Staging, Production). **Defaults & Fallbacks** now includes an **Audio Capabilities** row used by the Speech to Text node, with `whisper-1` available in the OpenAI model catalog.
> > >
> > > ![Model Providers page with OpenAI and Azure OpenAI configured at the organization level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_view_org.png)
> > >
> > > ![Provider Details modal showing OpenAI and Azure OpenAI as provider options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_model_Provider.png)
> > >
> > > ![Defaults and Fallbacks page with capability rows including Audio Capabilities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/defaults_and_fallbacks.png)
> > >
> > > ![Model selection and configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ai_models_selection.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/ai-providers)
> > > >
> > > > See the AI providers and model configuration documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Organization-level providers
> > > >
> > > > Add and manage AI providers with API keys and connection settings
> > >
> > > > [card] Azure OpenAI
> > > >
> > > > Connect to Azure-hosted OpenAI deployments with a base URL and API version
> > >
> > > > [card] Custom model entry
> > > >
> > > > Add models manually for providers that use deployment names (Azure) or non-public catalogs
> > >
> > > > [card] Audio Capabilities
> > > >
> > > > New row in Defaults & Fallbacks for transcription and speech synthesis, used by the Speech to Text node
> > >
> > > > [card] Defaults & Fallbacks
> > > >
> > > > Assign default and fallback models per AI capability and workspace type
> > >
> > > > [card] Fallback strategy
> > > >
> > > > Set fallback models on different providers for resilience
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat-based UI Flows**
>
> > [card] Chat-based UI Flows
> >
> > > [tab] Overview
> > >
> > > UI Flows now support two experience types: **Flow-Based** (traditional) and **Chat-Based** (conversational). Chat-Based UI Flows connect to a conversational workflow at the UI Flow level, so all Chat components in the flow use the same workflow by default. A new Settings page with a Chat Options tab lets you configure or change the workflow after creation.
> > >
> > > ![Chat-based UI Flow configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_based_ui_flow.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> > > >
> > > > See the UI Flows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Experience types
> > > >
> > > > Choose Flow-Based or Chat-Based when creating a UI Flow
> > >
> > > > [card] UI Flow Settings
> > > >
> > > > New Settings page with Chat Options tab for workflow configuration
> > >
> > > > [card] Workflow filtering
> > > >
> > > > Chat components only show conversational workflows in the selector
> > >
> > > > [card] Navigate in UI Flow
> > > >
> > > > AI can open specific screens with parameters from a conversation
> >
> > All Deployments
>
> ***
>
> ### **Chat improvements**
>
> > [card] Chat improvements
> >
> > Configure which parts of the chat header are visible on a per-component basis. The Chat component (when display type is **Fill**) gains a **Show Header** toggle in its Properties panel, and the Chat Header component gets a new **Available Actions** accordion with toggles for **New Conversation** and **History**. Conversation history now loads in pages, with a **Load more** action, and conversations are sorted by creation date with the most recent first.
> >
> > All Deployments
>
> ***
>
> ### **Voice input**
>
> > [card] Voice input
> >
> > > [tab] Overview
> > >
> > > Chat components now support voice input, allowing users to record audio messages directly in the chat. Users can record, preview with an audio player, and send voice messages within conversations.
> > >
> > > > [!NOTE]
> > > >
> > > > Voice input captures and sends audio recordings. When paired with the [Speech to Text](/5.9/ai-platform/agent-builder/speech-to-text) workflow node, voice messages are automatically transcribed and processed as text in conversational workflows.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audio recording
> > > >
> > > > Record voice messages directly in the chat input
> > >
> > > > [card] Audio preview
> > > >
> > > > Preview recordings with a built-in audio player before sending
> >
> > All Deployments
>
> ***
>
> ### **Stop agent response**
>
> > [card] Stop agent response
> >
> > > [tab] Overview
> > >
> > > The chat input now shows a **Stop** button in place of Send while an agent reply is streaming. Pressing Stop cancels the conversational workflow instance: any in-flight AI call is aborted, partial output is discarded, and the user prompt is persisted with a `cancelled` flag so the chat history reflects what happened.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Cross-platform
> > > >
> > > > Available on Web (Standard, Floating, Full Screen), iOS, and Android
> > >
> > > > [card] Themeable
> > > >
> > > > New `stopResponseIcon` slot in `chatInputArea` themes; preloaded by cms-core
> > >
> > > > [card] Localized
> > > >
> > > > New system substitution tags for Stop and Send labels with a11y variants
> >
> > All Deployments
>
> ***
>
> ### **Speech to Text node**
>
> > [card] Speech to Text
> >
> > > [tab] Overview
> > >
> > > A new workflow node that converts between audio and text. **Transcribe** converts audio files (MP3, WAV, M4A, AAC, OGG) into text with language detection and confidence scores. **Text to Speech** generates audio files from text with configurable voice, speed, and format. In conversational workflows, the node processes voice messages from the chat UI automatically.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> > > >
> > > > See the Speech to Text node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Transcription
> > > >
> > > > Convert audio to text with language detection and confidence scores
> > >
> > > > [card] Text to Speech
> > > >
> > > > Generate audio from text with configurable voice, model, speed, and format
> > >
> > > > [card] Chat voice integration
> > > >
> > > > Automatically transcribes voice messages in conversational workflows
> > >
> > > > [card] Multiple file sources
> > > >
> > > > Read from Document Plugin, S3, or chat input
> >
> > > [!NOTE]
> > >
> > > The transcription model is resolved from the organization's **Audio** capability default, configured in **AI Settings** under [Defaults & Fallbacks](/5.9/ai-platform/ai-providers).
> >
> > All Deployments
>
> ***
>
> ### **AI Triggers**
>
> > [card] AI Triggers
> >
> > > [tab] Overview
> > >
> > > Define named message templates with parameters on conversational workflows, so different UI Flow pages can launch the same workflow with different starting contexts. Triggers are configured in a dedicated side nav tab and selected on the Start node or sent from the Chat component at runtime.
> > >
> > > ![Reply Triggers list in a conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_reply_trigger.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Parameterized messages
> > > >
> > > > Message templates with `${paramName}` placeholders resolved at runtime
> > >
> > > > [card] Multi-page reuse
> > > >
> > > > Different pages launch the same workflow with different context
> > >
> > > > [card] Start node integration
> > > >
> > > > Toggle between Text and AI Trigger modes on the Start node
> > >
> > > > [card] Memory aware
> > > >
> > > > Trigger messages saved to conversation memory but hidden from chat history
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Context**
>
> > [card] UI Flow Context
> >
> > > [tab] Overview
> > >
> > > Conversational workflows can now receive a JSON context alongside the user message. A new **Conversation Context** property on UI Flow Pages lets you define the Parameters payload (with `${expression}` resolution), and the Start node exposes it as a collapsible **UI Flow Context** editor — also available in the Run Workflow test modal for manual runs.
> > >
> > > ![Start node UI Flow Context and UI Flow Conversation Context property](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#setting-context-from-a-ui-flow)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] UI-driven context
> > > >
> > > > Pages attach a JSON payload to conversational runs without hard-coding it in the workflow
> > >
> > > > [card] Expression resolution
> > > >
> > > > Parameters support `${expression}` syntax to bind live UI Flow data at runtime
> > >
> > > > [card] Start node field
> > > >
> > > > Collapsible UI Flow Context editor on the Start node for both runtime and manual testing
> > >
> > > > [card] JSON validation
> > > >
> > > > Invalid JSON is rejected before the run starts, surfacing a clear error
> >
> > All Deployments
>
> ***
>
> ### **Recommended prompts**
>
> > [card] Recommended prompts
> >
> > > [tab] Overview
> > >
> > > Custom Agent nodes can now generate follow-up prompt suggestions alongside their chat replies. When enabled via the new **Prompt Suggestions** satellite panel on a Custom Agent node, the agent includes recommended next questions or actions in its response. These appear as clickable suggestions in the chat UI, guiding users toward relevant follow-up interactions.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions)
> > > >
> > > > See the Custom Agent node documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Satellite panel
> > > >
> > > > Configure prompt suggestions directly on Custom Agent nodes in the workflow editor
> > >
> > > > [card] AI-generated suggestions
> > > >
> > > > Agent generates contextual follow-up prompts based on the conversation
> > >
> > > > [card] Clickable in chat
> > > >
> > > > Suggestions render as tappable chips in the chat UI
> > >
> > > > [card] Conversational workflows
> > > >
> > > > Works with send-as-reply mode in conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval enhancements**
>
> > [card] Context Retrieval enhancements
> >
> > > [tab] Overview
> > >
> > > **Custom Agent** and **Context Retrieval** nodes now support configurable **search type** and **re-ranking** for Knowledge Base retrieval. Choose between Hybrid (default), Semantic, or Keyword search strategies depending on your use case. Turn on re-ranking to apply a secondary relevance model that reorders retrieved chunks for higher-quality results.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the Context Retrieval node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Search type
> > > >
> > > > Choose Hybrid, Semantic, or Keywords search for Knowledge Base retrieval on Custom Agent and Context Retrieval nodes
> > >
> > > > [card] Re-ranking
> > > >
> > > > Apply a re-ranking model to reorder results by relevance to the query — available on both Custom Agent and Context Retrieval nodes
> >
> > All Deployments
>
> ***
>
> ### **Knowledge Base enhancements**
>
> > [card] Knowledge Base enhancements
> >
> > > [tab] Overview
> > >
> > > The Knowledge Base data source gets a refreshed workspace and a more powerful metadata filter builder. The **Content Sources** tab is now called **Stores**, and the Chunks tab gains a structured query builder for metadata filters with typed operators, AND/OR logic, and grouping — replacing the previous equality-only filters.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > > >
> > > > See the Knowledge Base content management guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Stores tab
> > > >
> > > > The Content Sources tab is renamed to Stores. Same concept, clearer label.
> > >
> > > > [card] Typed filter operators
> > > >
> > > > Operators per metadata type: equals, not equals, contains, in, not in, before, after, exists, size equals, and more
> > >
> > > > [card] AND/OR grouping
> > > >
> > > > Combine conditions with AND or OR and nest them in groups for non-trivial logic
> > >
> > > > [card] Query builder on Chunks tab
> > > >
> > > > Test retrieval with Search Type (Hybrid/Semantic/Keywords), Use Re-rank, and the new filter builder
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor enhancements**
>
> > [card] Web Page Extractor enhancements
> >
> > > [tab] Overview
> > >
> > > The Web Page Extractor node now supports **URL filtering** to include or exclude specific URL patterns during crawling, **configurable crawl depth** for more control over how deep the crawler follows links, and **file downloads** to retrieve attached files from crawled pages.
> >
> > > [tab] Key Features
> > >
> > > > [card] URL filtering
> > > >
> > > > Include or exclude URLs matching specific patterns during crawling
> > >
> > > > [card] Crawl depth
> > > >
> > > > Configure how many levels deep the crawler follows links
> > >
> > > > [card] File downloads
> > > >
> > > > Download attached files from crawled web pages
> > >
> > > > [card] Bulk document type
> > > >
> > > > When file downloads are enabled, the document type auto-sets to **Bulk** so a single crawl can return multiple documents
> >
> > All Deployments
>
> ***

> [tab] UI & Components
>
> Custom React components, advanced query builder, and merge conflict improvements.
>
> 🧩 [**Custom Components**](#custom-components) - Write React code in Designer and use in UI Flows\
> 🔍 [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder for database operations\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor\
> 🔀 [**Merge conflicts UX**](#merge-conflicts-ux) - Improved merge modal and conflict resolution experience
>
> ### **Custom Components**
>
> > [card] Custom Components
> >
> > > [tab] Overview
> > >
> > > Create custom React components directly in FlowX Designer. Write JSX, CSS, and use pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Components receive process data through input keys and can trigger process actions. Define once in Reusable Resources, use across multiple User Tasks.
> > >
> > > ![Custom Components code editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> > > >
> > > > See the Custom Components documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Code editor
> > > >
> > > > Write React JSX and CSS with a built-in code editor and file tree
> > >
> > > > [card] Pre-defined packages
> > > >
> > > > React, Emotion, Lodash, Axios, and date-fns available out of the box
> > >
> > > > [card] Process integration
> > > >
> > > > Receive process data via input keys and trigger process actions
> > >
> > > > [card] Import/Export
> > > >
> > > > Export as ZIP and import into other projects
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Advanced Query Builder**
>
> > [card] Advanced Query Builder
> >
> > > [tab] Overview
> > >
> > > A visual query builder for database operations and metadata filters, replacing manual JSON query writing with a structured interface. Build complex queries with conditions, grouping, and sorting without writing raw queries. The operator set has expanded with NULL checks (`exists`, `is null`), set membership (`not in`), string matching (`contains`, `starts with`, `ends with`), boolean tests (`is true`, `is false`), and date comparators (`before`, `after`). The `between` operator has been removed from the UI.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> > > >
> > > > See the FlowX Database documentation for the full query builder reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] Visual conditions
> > > >
> > > > Build query conditions with a structured UI instead of raw JSON
> > >
> > > > [card] Grouping and sorting
> > > >
> > > > Combine conditions with AND/OR grouping and configure result sorting
> > >
> > > > [card] Schema awareness
> > > >
> > > > Fields auto-populated from your collection schema with type-aware operators
> > >
> > > > [card] Visual/Script toggle
> > > >
> > > > Switch between visual builder and raw code editor at any time
> >
> > All Deployments
>
> ***
>
> ### **Oracle Database integration**
>
> > [card] Oracle Database integration
> >
> > > [tab] Overview
> > >
> > > Connect FlowX workflows to externally managed Oracle databases. Configure a connection (Oracle 19c, 21c, or 23ai), save parameterized SQL queries against the schema, and call them from the existing Database Operation node alongside other data sources.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> > > >
> > > > See the Oracle Database integration guide for the full reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] SERVICE\_NAME or SID
> > > >
> > > > Connect via Service Name or SID, with an optional SSL toggle
> > >
> > > > [card] Schema-aware SQL editor
> > > >
> > > > Monaco editor with syntax highlighting, autocomplete, and a side panel for tables, columns, primary keys, and foreign keys
> > >
> > > > [card] Test queries inline
> > > >
> > > > Run SQL with sample parameters: table view for SELECT, affected-row count for INSERT, UPDATE, and DELETE
> > >
> > > > [card] Workflow integration
> > > >
> > > > Pick the Oracle data source and query from the Database Operation node, with no new node type required
> >
> > All Deployments
>
> ***
>
> ### **Datasource Experience**
>
> > [card] Datasource Experience
> >
> > The **Add Data Source** dialog now groups data source types into four categories (**AI Capabilities**, **APIs**, **Databases**, and **Connectors**) with a search box for finding a specific type. REST endpoint authoring also suggests common HTTP headers and values to speed up integration setup.
> >
> > ![New Add Data Source dialog with categorized data source types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_new_data_source.png)
> >
> > All Deployments
>
> ***
>
> ### **MongoDB-aware code editor**
>
> > [card] MongoDB-aware code editor
> >
> > Operation editors on MongoDB data sources now use a Monaco language provider tuned for MongoDB. The editor highlights MongoDB operators (Comparison, Logical, Element, Evaluation, Array, Update, Aggregation, Conditional) and `${param}` interpolations, including inside string literals. Three autocomplete flows speed up authoring: typing `$` lists MongoDB operators, opening a quote in a field-name position lists the schema field paths from the linked Project Data Type, and typing inside `${...}` lists the operation's parameter keys.
> >
> > All Deployments
>
> ***
>
> ### **Project Data Model authoring**
>
> > [card] Project Data Model authoring
> >
> > Three improvements make Project Data Model authoring easier and less error-prone.
> >
> > > [card] Go to source
> > >
> > > A new **Go to source** button on data-model usages and Data Model nodes jumps directly to the source definition without manual navigation.
> >
> > > [card] Type-aware example values
> > >
> > > The example-value input on each attribute now matches its declared type: number inputs for NUMBER, a date picker for DATE, a true/false dropdown for BOOLEAN, single-select for enums, multi-select chips for enum arrays, and so on. CURRENCY values use the currency code rather than the symbol.
> >
> > > [card] Type-aware test data
> > >
> > > The same type-aware inputs apply when running or testing a workflow node and when filling input parameters for a reusable function, replacing the previous generic text inputs.
> >
> > All Deployments
>
> ***
>
> ### **Stop Run for workflows**
>
> > [card] Stop Run for workflows
> >
> > You can now cancel a running workflow instance directly from the workflow editor. While a workflow is running, the **Run Workflow** button switches to **Stop Run** — clicking it cancels the instance and marks all in-progress and scheduled nodes as cancelled. Cancelled instances show a new **Cancelled** status alongside Started, Finished, and Failed.
> >
> > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#running-and-stopping-workflows)
> > >
> > > See Running and stopping workflows in the Integration Designer reference.
> >
> > All Deployments
>
> ***
>
> ### **Merge conflicts UX**
>
> > [card] Merge conflicts UX
> >
> > The merge branches experience has been improved with a redesigned merge modal, better form validation with detailed error messages, and keyboard support (submit with Enter). The conflict resolution diff viewer now uses a new CodeMirror theme that matches the Monaco editor styling for a consistent visual experience.
> >
> > All Deployments
>
> ***

> [tab] Bug fixes
>
> ## Bug fixes
>
> ### AI Platform
>
> | Issue | Description |
> | - | - |
> | Custom Agent WebSocket stability | Fixed WebSocket 1006 abnormal closure for Custom Agent nodes with large payloads by upgrading AI SDK to handle Spring Framework 7's 64KB frame aggregation limit |
> | Azure OpenAI structured output | Fixed silent hang on Azure OpenAI for Custom Agents, Intent Classification, and Recommended Prompts when the response JSON schema lacked title and description fields |
> | Custom Agent node stuck | Fixed Custom Agent node getting stuck in running state |
> | MCP tool updates not working | Fixed an issue where updating tools on an existing MCP Server did not persist changes |
> | KB append performance | Fixed slow execution of the Append Knowledge Base node |
> | KB chunking on append | Fixed an issue where appended content via JSON in the Update Knowledge Base node was not chunked |
> | REST node with base64 certificate | Fixed error when running a workflow with a REST node using a REST system with a base64 certificate |
> | Workflow dependencies copy | Fixed dependencies not being copied for already-copied workflows |
>
> ### Core Platform
>
> | Issue | Description |
> | - | - |
> | Import pipeline issues | Fixed API issues in the import pipeline |
> | Enum CSV import losing changes | Fixed an issue where importing enumerations via CSV on committed resources did not update the resource modified date, causing changes to appear lost |
> | Data model duplicate key on import | Fixed a MongoDB duplicate key error when importing data model slices with duplicate entries |
> | Config params page not loading | Fixed GET config params endpoint not being called when accessing the Configuration Parameters page |
> | Enum default values dropdown | Fixed only first-level enum objects being displayed in the default values dropdown |
> | Data model loading state | Fixed user getting stuck in loading state after an error on data model keep operation |
>
> ### UI & Renderers
>
> | Issue | Description |
> | - | - |
> | Select component clear icon | Fixed misaligned clear icon on Select components in both Angular and React renderers |

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > **Self-hosted deployments:** FlowX 5.7.0 introduces the Organization ID as a mandatory configuration on all services. See the [deployment guidelines](./deployment-guidelines-v5.7) for complete upgrade instructions.
>
> ### Compatibility
>
> > [card] [Upgrade path](./deployment-guidelines-v5.7#supported-upgrade-paths)
> >
> > See the deployment guidelines for supported upgrade paths from 5.1.x LTS, 5.2–5.4, and 5.5–5.6.
>
> > [card] [Component versions](./deployment-guidelines-v5.7#component-versions)
> >
> > See the deployment guidelines for the full component version matrix and third-party dependency support.


# Deployment guidelines v5.8.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/deployment-guidelines-v5.8

Component versions, environment variables, and configuration changes for FlowX.AI 5.8.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.106.0** | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 |
| **admin** | **10.93.0** | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 |
| **designer** | **10.181.0** | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 |
| **cms-core** | **10.67.0** | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 |
| **scheduler-core** | **10.53.0** | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 |
| **events-gateway** | **10.55.0** | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 |
| **notification-plugin** | **10.64.0** | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 |
| **document-plugin** | **10.75.0** | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 |
| **task-management-plugin** | **10.66.0** | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 |
| **data-search** | **10.52.0** | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 |
| **audit-core** | **10.63.0** | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 |
| **advancing-controller** | **10.55.0** | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 |
| **integration-designer** | **10.128.0** | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 |
| **application-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **runtime-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **data-sync** | **10.58.0** | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 |
| **authorization-system** | **10.77.0** | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 |
| **nosql-db-runner** | **10.56.0** | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 |
| **email-gateway** | **10.56.0** | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 | - |
| **organization-manager** | **10.53.0** | 10.44.0 | 10.26.1 | 10.19.2 | - | - |
| **webhook-gateway** | **10.25.0** | 10.15.0 | 10.1.1 | - | - | - |
| **license** | **10.46.0** | 10.36.0 | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |

### Plugins

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 |
| **ai-platform-ai-assistant** | **10.7.0** | 10.6.2 | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **ai-platform-ai-developer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-connected-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-knowledge-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agents** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-conversations** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-tenants** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-analyst** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-designer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agent-builder** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-binaries** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **embedder** | **10.7.0** | 10.6.2 | - | - | - |
| **knowledgebase-rag** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **knowledgebase-indexer-v2** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **mcp** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **doc-parser** | **10.7.0** | 10.6.2 | 10.5.1 | - | - |
| **web-crawler** | **10.3.5** | 10.3.2 | - | - | - |
| **data-privacy** | **10.1.0** | 10.0.8 | - | - | - |
| **speech-to-text** | 10.3.3 | 10.3.3 | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | - | - | - |

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.8.0 | Keycloak | 26+ |
| 5.8.0 | Kafka | 3.8 - 3.9 |
| 5.8.0 | PostgreSQL | 16 - 17 |
| 5.8.0 | Oracle Database | 21c, 23ai |
| 5.8.0 | MongoDB | 7 - 8 |
| 5.8.0 | Redis | 7.4 - 8.0 |
| 5.8.0 | Elasticsearch | 8 |
| 5.8.0 | Angular (Web SDK) | 20 |
| 5.8.0 | React (Web SDK) | 18.x |

***

## Self-hosted deployment changes

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **5.7.0** | Supported | Standard upgrade. |
| **5.1.x LTS** | Supported | Direct upgrade from 5.1.x to 5.8.0 is supported. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

***

## Kafka integration changes

### New Kafka topics

| Topic | Producer | Producer env var | Consumer | Consumer env var |
| - | - | - | - | - |
| `ai.flowx.license.events.v1` | organization-manager | `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | license | `KAFKA_TOPIC_LICENSE_IN_EVENTS` |
| `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | admin | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` | knowledgebase-indexer-v2 | n/a (Python constant) | embedder | n/a (Python constant) |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` | embedder | n/a (Python constant) | knowledgebase-indexer-v2 | n/a (Python constant) |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | (no env var; resolved from `kafka.topic.naming.*`) | document-plugin | `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` |

**License lifecycle events** are delivered from FlowX SaaS to the on-prem license service.

**Custom-component correction requests** complement the existing process / business-rule / reusable-template / ui-flow correction topics that the admin orchestrator already consumed.

**UI Flow multi-file upload** sends a single bulk command to document-plugin in place of the per-file pattern. The plugin persists each file in the session, emits one SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) at the end of the batch via events-gateway, and forwards per-file results to the existing `ai.flowx.core.trigger.ui-flow.update.v1` topic.

**KB embedding-request / embedding-response** replace the previous gRPC `EmbedderService` path (`BulkGenerateEmbeddings` / `GenerateEmbeddings`); the indexer now publishes one embedding job per chunk and the embedder writes points to Qdrant directly, emitting `KbStoreEntryStateChanged` once all chunks for an entry are persisted.

> [!NOTE]
>
> The two `core-services` topic names (`license.events`, `application-version.correction-after-app-operation.custom-component.request`) resolve from the standard `${kafka.topic.naming.prefix}` / `${kafka.topic.naming.suffix}` machinery: default prefix `ai.flowx.` (empty environment segment), default suffix `.v1`. Operators that want an environment-prefixed topic name (e.g., `ai.flowx.dev.license.events.v1`) set `kafka.topic.naming.environment` globally rather than overriding individual topics. The two AI Platform topics are hard-coded constants in the indexer and embedder and do not participate in the prefix machinery.

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX. Initialized with the `notset` sentinel; replace it with the value FlowX provides before the license service starts. Type changed from UUID to String in 5.8.0. | `notset` | license |
| `KAFKA_CONSUMER_GROUPID_LICENSE_EVENTS` | Kafka consumer group used by the license service to receive license events. | `license-events` | license |
| `KAFKA_CONSUMER_THREADS_LICENSE_EVENTS` | Listener container concurrency for the license-events consumer. | `1` | license |
| `KAFKA_TOPIC_LICENSE_IN_EVENTS` | License events topic consumed by the license service. | `ai.flowx.license.events.v1` | license |
| `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | Same topic, producer-side binding on organization-manager. | `ai.flowx.license.events.v1` | organization-manager |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | Custom-component correction-request topic, producer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` | Same topic, consumer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | admin |
| `MANAGEMENT_HEALTH_REDIS_TIMEOUT` | Spring Boot Actuator timeout for the Redis health indicator (in ms). | `5000` | all services using Redis |
| `SPRING_CACHE_REDIS_PERSISTENCEKEYPREFIX` | Prefix applied to Redis keys for the advancing-controller cache. | `flowx:core:cache:advancing-controller:` | advancing-controller |
| `REDIS_COMMAND_TIMEOUT` | Redis command timeout in ms. Fail-fast during master failover. Bound via `${REDIS_COMMAND_TIMEOUT:5000}` placeholder on `spring.data.redis.timeout`. | `5000` | all services using Redis |
| `REDIS_CONNECT_TIMEOUT` | Redis connection establishment timeout in ms. Bound via `${REDIS_CONNECT_TIMEOUT:5000}`. | `5000` | all services using Redis |
| `REDIS_POOL_MAX_ACTIVE` | Maximum number of active Redis connections in the pool. | `10` | all services using Redis |
| `REDIS_POOL_MAX_IDLE` | Maximum number of idle Redis connections retained in the pool. | `5` | all services using Redis |
| `REDIS_POOL_MIN_IDLE` | Minimum number of idle Redis connections kept warm in the pool. | `1` | all services using Redis |
| `REDIS_POOL_MAX_WAIT` | Maximum time to wait for an available connection from the pool, in ms. | `2000` | all services using Redis |
| `FLOWX_METRICS_STUCKCHECKINTERVALMS` | Interval at which the stuck-events metric scheduler runs (ms). Bound from the inline `@Value("${flowx.metrics.stuck-check-interval-ms:60000}")` default; not in `application.yml`. | `60000` | advancing-controller |
| `FLOWX_METRICS_STUCKTHRESHOLDMINUTES` | Age threshold (in minutes) above which an advancing event is considered stuck. Bound from `@Value("${flowx.metrics.stuck-threshold-minutes:5}")`. | `5` | advancing-controller |
| `FLOWX_DATAPRIVACY_BASEURL` | Base URL for the new Data Privacy service. Required when any AI workflow node enables the Personal Information Guard. | `http://data-privacy:80` | integration-designer |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60` | integration-designer |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. Producer-side is the matching `kafka.topic.session.upload.bulk.out` on process-engine, which resolves from the standard naming machinery. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | document-plugin |

### Removed environment variables

| Environment Variable | Replaced by | Component |
| - | - | - |
| `FLOWX_SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Removed with the move to single-pod scheduler execution (plat-1549, `commons-scheduler-lib`). No replacement; only one scheduler pod runs now. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_ENABLED` | Same. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_PROVIDER` | Same. | application-manager, license |
| `SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Same. | integration-designer, process-engine |

***


# FlowX.AI 5.8.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/v5.8.0-may-2026

Runtime authorization overhaul, UI Flow permissions, Custom Components in Processes, new theme components, Angular bulk file upload, and webhook provider adapters.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

Sharing a FlowX solution used to mean handing out admin keys. **5.8.0 changes that.** The AI Developer now ships the React component you wished you'd had time to build, PII never reaches your LLM by accident, and you can finally invite a reviewer without giving them the platform.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html)

### What changed since 5.7.0

| 5.7.0 | 5.8.0 |
| - | - |
| End-user access management with org-level roles and groups | + **Runtime authorization** with project-version-scoped roles, groups, and attribute-based assignment |
| UI Flows accessible to any runtime user | + **UI Flow permissions**: assign roles per UI Flow, evaluated at runtime |
| Custom Components in UI Flows only (Phase 1, React) | + **Custom Components in Processes** with shared data model, input/output mappings, and AI Developer generation |
| Built-in UI components | + **Tooltip, Markdown, Progress Bar, Separator** as new theme components |
| React-only multi-file upload | + **Angular SDK bulk file upload** |
| Generic webhook gateway | + **Webhook provider adapters** (Slack, with HMAC signing-secret validation) |
| Oracle Database (basic SQL editor) | + **Richer SQL autocomplete** in the Monaco editor: operators, schema-aware tables/columns, and `:paramName` interpolations |
| No personal-information guardrails on AI workflow nodes | + **PII Guard** with input/output scans, sensitivity presets, and an entity catalog |

***

**What's new?**

> [tab] Platform
>
> 🔐 [**Runtime authorization**](#runtime-authorization) - Project-scoped roles, end-user groups in FlowX, and Solutions → Share flow\
> 📋 [**UI Flow permissions**](#ui-flow-permissions) - Role-based UI Flow visibility with runtime enforcement

> [tab] Builders
>
> 🧩 [**Custom Components in Processes**](#custom-components-in-processes) - Bundled CCs in Process User Tasks with shared data model\
> 🎨 [**New UI components**](#new-ui-components) - Tooltip, Markdown, Progress Bar, Separator\
> 📥 [**Angular bulk file upload**](#angular-bulk-file-upload) - Multi-file upload component for the Angular SDK\
> 📦 [**UI Flow multi-file upload backend**](#ui-flow-multi-file-upload-backend) - Single bulk endpoint and one completion SSE event for batch uploads\
> 🪝 [**Webhook provider adapters**](#webhook-provider-adapters) - Slack inbound webhook support with HMAC signing\
> 🗄️ [**Richer SQL autocomplete**](#richer-sql-autocomplete) - Monaco editor enhancements for the Oracle data source SQL editor\
> 🧱 [**Data source UX redesign**](#data-source-ux-redesign) - Tile-based creation, type filters, unified settings, save with incomplete config\
> ➕ [**Context menu adds UI components in Processes**](#context-menu-adds-ui-components-in-processes) - Right-click Add UI component in Process User Tasks and Reusable UI Templates\
> 👆 [**Pointer cursor on actionable elements**](#pointer-cursor-on-actionable-elements) - Web renderers show pointer on action-bound components

> [tab] AI Platform
>
> 🛡️ [**PII Guard**](#pii-guard) - Personal information identification on AI inputs\
> 🤖 [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent now drafts Custom Component code\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - System metadata keys, Kafka indexer→embedder, Qdrant export/delete, error handling\
> 🌐 [**Web Crawler multi-URL filters**](#web-crawler-multi-url-filters) - Multiple URL filters per crawler config

### **Runtime authorization**

> [card] Runtime authorization overhaul
>
> > [tab] Overview
> >
> > **Before 5.8.0:** a role on a user matched every project that role appeared in. **Now:** roles live at the project version, sharing is explicit, and Designer users still bypass runtime so they can demo without standing up test accounts.
> >
> > Runtime access is reorganized around the project. Roles live at the **project version**, each org has a managed catalog of **end-user groups**, and access flows through a **Solutions → Share** modal. FlowX retains authentication and external-IDP federation in Keycloak; runtime roles, end-user groups, and project-scoped sharing live in FlowX itself, evaluated by a custom runtime authorization service tuned for the volume of runtime permission checks. SpiceDB remains the design-time permission engine for Designer access.
> >
> > > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> > >
> > > See Setup guides → Access management → Runtime authorization.
>
> > [tab] Key Features
> >
> > > [card] Project-scoped roles
> > >
> > > Each project version declares the runtime roles required to operate it. Roles are org-level entities, defined once and reusable across projects and libraries.
> >
> > > [card] Default `user` role on creation
> > >
> > > New projects spawn with a default `user` role so a fresh project is reachable on day one without extra wiring.
> >
> > > [card] Sharing from Solutions
> > >
> > > The Solutions page gains a **Share** modal. Pick a user or end-user group, assign a role, and the user can launch the solution at runtime.
> >
> > > [card] End-user groups in FlowX
> > >
> > > Groups previously managed in Keycloak now live in FlowX. Recommended pattern: an "All End Users" group per single-role solution; one group per role for multi-role solutions.
> >
> > > [card] Process swimlane roles
> > >
> > > BPMN swimlanes assign view, execute, and self-assign permissions per role.
> >
> > > [card] Designer-user bypass
> > >
> > > Designer users can run any project they have designer access to without holding a runtime role; they auto-receive view, execute, and self-assign on every swimlane.
> >
> > > [card] Active Policy gate
> > >
> > > The Share modal lists only roles defined in the build set as **Active Policy** for the project. Roles defined in a non-active build do not appear until promoted.
>
> > [tab] Architecture
> >
> > The 5.8.0 release introduces a clear split between authentication and runtime authorization:
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Authentication, sessions, MFA | Keycloak | Unchanged |
> > | External IDP federation | Keycloak | Configured per organization |
> > | User attributes (business filters) | Keycloak | Source of truth for token claims |
> > | Runtime roles | FlowX (custom CAS) | Defined per project version, evaluated at runtime |
> > | End-user groups | FlowX (custom CAS) | Replaces Keycloak group management |
> > | Project-scoped sharing | FlowX (custom CAS) | Solutions → Share modal |
> > | Design-time permissions | FlowX SpiceDB | Designer UI access; unchanged from prior releases |
> >
> > A `designer-user` Keycloak attribute is auto-managed on each user (`true` for designer users, `false` for end-users), with a mapper on the `flowx-platform-authenticate` client so the engine can check it cheaply on the access token.
>
> > [tab] Migration
> >
> > > [!WARNING]
> > >
> > > **Sharing settings do not export between environments or workspaces.** Configure sharing per environment as a deliberate step when promoting a project to a higher environment.
> >
> > Sharing data does not travel with the project export, so promoting a build from one environment to another (for example, dev to staging) requires a sharing pass in the target environment. Treat it as an explicit step in your deployment checklist.
> >
> > Existing FlowX organizations migrate as follows:
> >
> > * Roles previously assigned directly to users continue to work for backward compatibility while you rebuild assignments under the project-scoped model.
> > * End-user groups configured in Keycloak are migrated into FlowX and become the authoritative source going forward.
> > * Existing UI Flows receive the project-level **User** role automatically as their default allowed role on upgrade. See the [UI Flow permissions](#ui-flow-permissions) section for next steps.
>
> All Deployments

### **UI Flow permissions**

> [card] UI Flow permissions
>
> > [tab] Overview
> >
> > **Before 5.8.0:** every UI Flow was reachable by anyone with runtime access. **Now:** each UI Flow carries its own allow-list and components inside it can be hidden or disabled per role.
> >
> > Each UI Flow now carries a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API. Inside a UI Flow session, individual components can be hidden or disabled by permission-based rules evaluated at runtime against the user's permission set.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> > >
> > > See UI Flows → UI Flow permissions.
>
> > [tab] Key Features
> >
> > > [card] Permissions page
> > >
> > > A new **Settings → Permissions** page in the UI Flow editor lets you assign one or more runtime roles to each UI Flow.
> >
> > > [card] Default role on creation
> > >
> > > New UI Flows receive the project-level **User** role by default so they are reachable on day one; tighten the list before deploying.
> >
> > > [card] Per-component hide/disable
> > >
> > > Components can be hidden or made readonly based on the user's runtime permissions, using the same hide/disable rule machinery as JavaScript expressions.
> >
> > > [card] Permission toast
> > >
> > > Users without the required role see a permission toast in the Designer-hosted runtime preview; the deployed app returns 403 from the start endpoint.
> >
> > > [card] Input-parameter validation
> > >
> > > Input parameters are validated against the UI Flow's input schema before the session is created.
> >
> > > [card] Travels with import/export
> > >
> > > Allowed roles are saved on the UI Flow resource and travel with project export/import.
>
> > [tab] Migration
> >
> > UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.
>
> All Deployments

### **Custom Components in Processes**

> [card] Custom Components in Processes
>
> > [tab] Overview
> >
> > **Before 5.8.0:** Custom Components only ran in UI Flows. **Now:** drag one onto a Process User Task and the React SDK applies the input/output mappings at runtime.
> >
> > Bundled Custom Components, previously only usable in UI Flows, now render in **Process User Tasks**. Each Custom Component carries its own **data model** with explicit input and output slices, and you map process data into and out of the component at each use site. Renderer support ships in the React SDK.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components#using-custom-components-in-process-user-tasks)
> > >
> > > See Custom Components → Using Custom Components in Process User Tasks.
>
> > [tab] Key Features
> >
> > > [card] Process User Task host
> > >
> > > Drag a Custom Component onto a Process User Task layout the same way you do in UI Flows.
> >
> > > [card] Custom Component data model
> > >
> > > Each Custom Component declares its own data model. The Designer keeps input and output slices isolated so the component contract is clear at every use site.
> >
> > > [card] INPUT mappings
> > >
> > > Map process data attributes onto the Custom Component's input slice at runtime, so the component receives only the data it declared.
> >
> > > [card] OUTPUT mappings
> > >
> > > When the component triggers an action, the React SDK applies the configured OUTPUT mappings before piping `saveData` back to process variables.
> >
> > > [card] Test with sample inputs
> > >
> > > The Custom Component editor lets you fill input params with sample data for in-Designer preview, mirroring the UI Flow test flow.
> >
> > > [card] Import and export
> > >
> > > Custom Components export and import alongside the data model and mappings so a component travels intact between projects.
>
> > [tab] Limitations
> >
> > Phase 1 limitations from 5.7.0 still apply: React SDK only (no Angular renderer), pre-defined dependency set (React, Emotion, Lodash, Axios, date-fns), browser-side bundling, and client-side rendering only. See the [Custom Components limitations](/5.9/docs/building-blocks/reusable-resources/custom-components#limitations-phase-1) section.
>
> All Deployments

### **New UI components**

> [card] New UI components
>
> Four new theme components ship with renderer parity across React, Angular, and Android SDKs.
>
> > [card] [Tooltip](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Contextual hint anchored to any UI element. Configurable text (static, local variable, or computed expression), position handling, and an optional icon.
>
> > [card] [Markdown](/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown)
> >
> > Render Markdown content from a static string or computed expression, with localization formatting for numbers, dates, and currency. Six heading levels and link styling are theme-driven.
>
> > [card] [Progress Bar](/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar)
> >
> > Visual progress indicator. Set a value between `0` and `1` from a static value, local variable, or computed expression.
>
> > [card] [Separator](/5.9/docs/building-blocks/ui-designer/ui-component-types/separator)
> >
> > Visual divider with theme-driven color. Adjustable height for layout spacing.
>
> All four are exposed in the **Theme Admin** sidebar so theme overrides cascade through templates.
>
> All Deployments

### **Angular bulk file upload**

> [card] Angular bulk file upload
>
> > [tab] Overview
> >
> > The **Multiple File Upload** component (`BULK_FILE_UPLOAD`), previously available only in the React SDK, now ships in the Angular SDK with the same drag-and-drop area and theming. Existing UI Flows that use the component render across React and Angular containers without configuration changes.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> > >
> > > See the Multiple File Upload component reference.
>
> > [tab] Key Features
> >
> > > [card] Renderer parity
> > >
> > > Same component, same configuration, same theming across React and Angular containers.
> >
> > > [card] Drag-and-drop area
> > >
> > > Drop zone with click-to-browse fallback in both renderers.
> >
> > > [card] Theme-driven
> > >
> > > The component picks up theme overrides for typography, colors, and spacing the same way as built-in components.
> >
> > > [card] No flow changes needed
> > >
> > > UI Flows authored before 5.8.0 render in the Angular SDK without edits.
>
> All Deployments

### **UI Flow multi-file upload backend**

> [card] UI Flow multi-file upload backend
>
> > [tab] Overview
> >
> > Multi-file uploads from UI Flows now use a dedicated bulk endpoint and a single completion event in place of the per-file pattern. The upload action accepts a list of temp-file IDs in one request and the SDK receives a single SSE frame when the batch is persisted.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload#ui-flow-upload-flow)
> > >
> > > See Multiple file upload → UI Flow upload flow.
>
> > [tab] Key Features
> >
> > > [card] Single bulk endpoint
> > >
> > > `POST /ui-flow/{uiFlowSessionId}/upload-multiple` accepts a list of temp-file IDs and returns a server-generated `uploadBatchId`.
> >
> > > [card] Single completion event
> > >
> > > One SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) delivers per-file results once the batch is persisted.
> >
> > > [card] New Kafka topic
> > >
> > > `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` carries the bulk command from process-engine to document-plugin.
> >
> > > [card] Session variable mapping
> > >
> > > Per-file results are stored as a list under the upload action's `responseKey` in the UI Flow session.
>
> All Deployments

### **Webhook provider adapters**

> [card] Webhook provider adapters
>
> > [tab] Overview
> >
> > Inbound webhook registrations now select a **provider**: `GENERIC` or `SLACK`. The Slack adapter performs HMAC-SHA256 signature validation against the Slack signing secret on every request, including the `X-Slack-Request-Timestamp` skew check (5 minutes). Provider-segmented URLs (`/webhooks/incoming/slack/...`) keep generic and provider-specific registrations isolated. Future providers plug in behind the same `InboundProviderAdapter` interface without changing the URL contract.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#provider-adapters)
> > >
> > > See Incoming webhooks → Provider adapters.
>
> > [tab] Key Features
> >
> > > [card] Slack signature validation
> > >
> > > HMAC-SHA256 on `X-Slack-Signature`, with timestamp skew enforced
> >
> > > [card] Slack URL-verification handshake
> > >
> > > The gateway answers Slack's `url_verification` challenge automatically
> >
> > > [card] Provider-segmented URLs
> > >
> > > `/webhooks/incoming/{provider}/...` keeps providers isolated; mismatch returns 400
> >
> > > [card] Independent secret rotation
> > >
> > > Rotate the provider signing secret without touching the FlowX API key
> >
> > > [card] Settings tab
> > >
> > > Provider + signing secret moved to a dedicated Settings tab on the webhook system
> >
> > > [card] Pluggable
> > >
> > > New providers add an adapter and an enum value; no URL or registration schema changes
>
> All Deployments

### **Richer SQL autocomplete**

> [card] Richer SQL autocomplete
>
> > [tab] Overview
> >
> > The Monaco editor on the Oracle Database data source now ships with a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `:paramName` interpolations resolved from the parameters panel.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database#sql-editor)
> > >
> > > See the Oracle Database SQL editor documentation.
>
> > [tab] Key Features
> >
> > > [card] Keywords and operators
> > >
> > > Full SQL language definition powers keyword highlighting and completion.
> >
> > > [card] Schema-aware suggestions
> > >
> > > Tables and columns parsed from the saved schema context appear in completion lists.
> >
> > > [card] Parameter interpolation
> > >
> > > `:paramName` placeholders resolve against the parameters panel for inline preview.
> >
> > > [card] Editor consistency
> > >
> > > Matches the editor experience used by other code surfaces in the Designer.
>
> All Deployments

### **Data source UX redesign**

> [card] Data source UX redesign
>
> > [tab] Overview
> >
> > The Data Sources resource page is rebuilt around a tile-based creation flow and a unified details view. Each data source type has its own icon and a dedicated tile in the **New Data Source** modal, with a search box that filters tiles as you type. The list view shows the type next to each entry and adds a type filter so you can scope the list by connector. Settings panels for every data source type are normalized to the same card-based layout.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer reference for data source configuration.
>
> > [tab] Key Features
> >
> > > [card] Tile-based creation modal
> > >
> > > The **New Data Source** modal lists every connector type as a searchable tile, replacing the previous type dropdown.
> >
> > > [card] Type icons in the list
> > >
> > > Each entry in the data sources list shows the connector's icon and type, so a long list is easier to scan.
> >
> > > [card] Filter by type
> > >
> > > Filter the list to a specific connector type (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.) without scrolling.
> >
> > > [card] Unified settings layout
> > >
> > > Every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
> >
> > > [card] Save with incomplete config
> > >
> > > Create and save a data source even when some fields (credentials, endpoints) are not yet available. You can reference the data source in workflows and processes immediately and finish the configuration later — the data source will only operate at runtime once required fields are filled in.
>
> All Deployments

### **PII Guard**

> [card] Personal Information Guard
>
> > [tab] Overview
> >
> > **Before 5.8.0:** data-sensitive customers couldn't enable AI workflow nodes at all. **Now:** every AI node carries a per-node guardrail with sensitivity presets, scan directions, and a fail-closed contract.
> >
> > AI workflow nodes gain a per-node guardrail that detects and replaces personal information before it reaches the LLM and, optionally, scans LLM output before it flows downstream. The guard runs against the new **Data Privacy** service, configured per node with sensitivity presets, scan directions, and an entity catalog organized into Universal, Regional EN, and Regional RO scopes. Iteration 1 covers Custom Agent, Intent Classification, Extract Data from File, and all AI Text, Document, Image, and Data Operations, including Document Generation.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See Personal Information Guard.
>
> > [tab] Key Features
> >
> > > [card] Per-node toggle
> > >
> > > Enable on any AI node. Choose a sensitivity preset (Strict / Balanced / Relaxed) or set a custom threshold.
> >
> > > [card] Input and output scans
> > >
> > > Redacts inputs and `systemPrompt` before the LLM call; optionally scans LLM output before it leaves the node.
> >
> > > [card] File redaction
> > >
> > > Document and image nodes get a redacted source artifact uploaded back to the same storage; the file binding is swapped automatically.
> >
> > > [card] Entity catalog
> > >
> > > 24 entity types (email, phone, IBAN, etc.) grouped under Universal, Regional EN, and Regional RO. Modal supports search and section-level Select All.
> >
> > > [card] System-prompt appender
> > >
> > > Custom Agent nodes get a non-editable system-prompt segment teaching the LLM how to handle `<PII type=.../>` placeholders.
> >
> > > [card] Fail-closed
> > >
> > > Any error from the Data Privacy service stops node execution and surfaces on the run log; no partially-redacted prompts reach the LLM.
> >
> > > [card] Run-log visibility
> > >
> > > Each scan reports status, per-entity detection counts, and (for file scans) original and redacted storage paths.
> >
> > > [card] New Data Privacy service
> > >
> > > Backed by Presidio. Configured via `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` on integration-designer.
>
> All Deployments

### **Knowledge Base enhancements**

> [card] Knowledge Base
>
> > [tab] Overview
> >
> > Knowledge Bases gain richer metadata and a more resilient indexing path. Stores and chunks expose system metadata fields you can filter on in the Test KB modal and the Custom Agent node, the indexer and embedder communicate over Kafka instead of synchronous calls, and the Update Knowledge Base node can ingest files by path from inside a workflow.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See Knowledge Base → Overview.
>
> > [tab] Key Features
> >
> > > [card] System metadata on stores
> > >
> > > Filter entries by `Source` (Manual or Workflow), `Uploaded`, `Doc name`, `Doc type`, `Doc pages`, and `Store origin`
> >
> > > [card] System metadata on chunks
> > >
> > > Filter chunks by `Chunk counter`, `Chunk type`, `Chunk section`, `Chunk page start`, and `Chunk entry`
> >
> > > [card] Kafka between indexer and embedder
> > >
> > > Replaces the previous synchronous gRPC path; per-chunk embedding requests flow through `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1`
> >
> > > [card] Delete chunks from Qdrant
> > >
> > > Indexer forwards a delete job to the embedder, which removes matching points from Qdrant when an entry is deleted
> >
> > > [card] File path mode in Update KB node
> > >
> > > The Update Knowledge Base node accepts `contentType: FILE_PATH` so workflows can ingest content uploaded earlier in the run
> >
> > > [card] Doc pages in agent stream
> > >
> > > Custom Agent streaming responses include `doc_pages` and chunk metadata (counter, type, section, page start) for richer trace and debug
>
> All Deployments

### **Web Crawler multi-URL filters**

> [card] Web Crawler multi-URL filters
>
> > [tab] Overview
> >
> > The Web Crawler node now accepts up to 20 URL filter patterns per crawler configuration. Open the **URL Filters** modal on the Web Crawler node, add one row per pattern, and the crawler restricts its breadth-first traversal to URLs that match any of the configured filters.
> >
> > > [card] [Documentation](/5.9/setup-guides/web-crawler-setup)
> > >
> > > See the Web Crawler setup guide.
>
> > [tab] Key Features
> >
> > > [card] Up to 20 patterns per crawler
> > >
> > > Add one row per pattern in the URL Filters modal; deep crawls match any pattern.
> >
> > > [card] Replaces single-string filter
> > >
> > > The previous single-string filter is superseded by the new multi-pattern array. Existing crawlers are migrated automatically.
> >
> > > [card] Breadth-first scoping
> > >
> > > Filters apply to the crawler's breadth-first traversal so deep crawls stay within the intended scope.
> >
> > > [card] Per-pattern tuning
> > >
> > > Combine narrow and broad patterns in one configuration to handle multi-section sites without spawning multiple crawlers.
>
> All Deployments

### **AI Developer generates Custom Components**

> [card] AI Developer generates Custom Components
>
> > [tab] Overview
> >
> > **Before 5.8.0:** the AI Developer wrote business rules and JS expressions. **Now:** it ships entire React Custom Components — JSX, CSS, `package.json`, and sample input data — in one prompt.
> >
> > The AI Developer pre-built agent gains a **Generate Custom Component** action and an **Edit Custom Component** action. From the Designer's AI command center, describe the component you want, and the agent returns a complete React bundle (JSX, CSS, `package.json`, and sample input data) that you can preview, accept, or iterate on. The same conversation can edit existing components.
> >
> > > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> > >
> > > See AI Developer → Pre-built agents.
>
> > [tab] Key Features
> >
> > > [card] Generate from natural language
> > >
> > > Describe a component in plain language; receive JSX, CSS, `package.json`, and sample input data in one response.
> >
> > > [card] Sample input field
> > >
> > > A dedicated input field lets you provide preview data so the generated component renders meaningfully on first run.
> >
> > > [card] Edit existing components
> > >
> > > Iterate on a generated or hand-authored component through the same conversation. The agent keeps the component context.
> >
> > > [card] Inline preview
> > >
> > > The Designer's Preview area renders the generated bundle next to the conversation so you can validate before saving.
> >
> > > [card] Dependency summary
> > >
> > > A new dependency summary panel surfaces the npm packages the agent included in `package.json`.
> >
> > > [card] Keep / Discard
> > >
> > > Accept the generated bundle into the workspace or discard it without leaving the conversation.
>
> > [tab] Limitations
> >
> > The first iteration generates the component code, styles, and input parameters. Wiring component actions to host-side handlers (Process or UI Flow actions) is not yet inferred — connect actions manually after accepting the generated bundle.
>
> All Deployments

### **iframe logout postMessage contract**

> [card] iframe logout postMessage
>
> The runtime SaaS app now notifies an iframe parent when a user logs out. When the parent passes a `parentOrigin` query parameter on the `/{orgCode}/logout` URL, the runtime posts `{ type: 'logout-success' }` to `window.parent` immediately before the sign-out redirect. Host applications that embed the FlowX runtime in an iframe can listen for this message and react (clear local state, navigate, surface a UI cue) without polling the iframe URL.
>
> All Deployments

### **Context menu adds UI components in Processes**

> [card] Right-click Add UI component in Processes and Reusable UI Templates
>
> The right-click contextual menu for adding a UI component, previously available only in UI Flows, now works in **Process User Tasks** and **Reusable UI Templates** as well. Right-click a node in the components hierarchy panel to insert any allowed child component without dragging from the palette. Copy and paste styles are also exposed from the same menu.
>
> All Deployments

### **Pointer cursor on actionable elements**

> [card] Pointer cursor on actionable elements
>
> Web renderers now switch the cursor to a pointer when hovering over any UI component bound to an action, matching standard web affordances. No configuration change is required — the new behavior applies automatically to elements that already declare an action role.
>
> All Deployments

### **"Process Data" → "Local Variables" rename**

> [card] Process Data renamed to Local Variables
>
> In the UI Designer, the **Process Data** label is now displayed as **Local Variables** when you are editing a UI Flow or a Reusable UI Template. Process editing is unchanged and continues to use **Process Data**. The data source key and binding behavior are identical; only the user-visible label changed, so existing flows continue to work without any update.
>
> All Deployments

### **License billing guards**

> [card] License billing guards
>
> The license service no longer creates billing plans for periods past an organization's subscription end date. This prevents stale plan rows from accumulating after a subscription expires and aligns the on-prem billing trail with the SaaS-side license lifecycle.
>
> Self-Hosted

### **Speech-to-text and Web Crawler in AI consumption**

> [card] Speech-to-text and Web Crawler in AI consumption
>
> AI consumption tracking now includes Speech-to-text and Web Crawler workflow nodes alongside the existing AI Text, Document, Image, and Data Operations. Organizations on AI consumption-based plans see usage and billing reflected for these nodes from 5.8.0 onward.
>
> All Deployments

***

## Shipped by

This release is the work of the FlowX engineering team — backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.8.0](./deployment-guidelines-v5.8).


# Deployment guidelines v5.9.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9

Component versions, environment variables, and configuration changes for FlowX.AI 5.9.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

> [!NOTE]
>
> **Upgrading from 5.1.x LTS?** This page describes the steady-state 5.9.0 deployment. For the architecture delta, deprecation list, and upgrade steps, see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Deployment packaging.** 5.9.x is the last LTS release distributed as a multi-chart deployment, where each FlowX service is installed from its own Helm chart.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

The following tables list component versions per FlowX.AI release. Verify your installed versions against the 5.9.0 column in **FlowX.AI Designer → Platform Status**.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **process-engine** | 10.135.0 | 10.106.0 | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 |
| **admin** | 10.116.0 | 10.93.0 | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 |
| **designer** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 |
| **cms-core** | 10.86.0 | 10.67.0 | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 |
| **scheduler-core** | 10.70.0 | 10.53.0 | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 |
| **events-gateway** | 10.72.0 | 10.55.0 | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 |
| **notification-plugin** | 10.83.0 | 10.64.0 | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 |
| **document-plugin** | 10.94.0 | 10.75.0 | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 |
| **task-management-plugin** | 10.84.0 | 10.66.0 | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |
| **data-search** | 10.69.0 | 10.52.0 | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 |
| **audit-core** | 10.79.0 | 10.63.0 | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 |
| **advancing-controller** | 10.73.0 | 10.55.0 | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 |
| **integration-designer** | 10.162.0 | 10.128.0 | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 |
| **application-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **runtime-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **data-sync** | 10.81.0 | 10.58.0 | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 |
| **authorization-system** | 10.96.1 | 10.77.0 | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 |
| **nosql-db-runner** | 10.75.0 | 10.56.0 | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 |
| **email-gateway** | 10.74.0 | 10.56.0 | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 |
| **organization-manager** | 10.71.0 | 10.53.0 | 10.44.0 | 10.26.1 | 10.19.2 | - |
| **webhook-gateway** | 10.44.0 | 10.25.0 | 10.15.0 | 10.1.1 | - | - |
| **file-gateway** | 10.8.0 | - | - | - | - | - |
| **license** | 10.63.0 | 10.46.0 | 10.36.0 | - | - | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB**
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-native-sdk** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-theme** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-ui-toolkit** | 10.230.2 | - | - | - | - | - |
| **@flowx/core-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/core-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **react-saas** | 10.230.2 | - | - | - | - | - |
| **iOS renderer** | 10.4.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |
| **Android renderer** | 10.5.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |

The **react-saas** container app tracks the designer version.

### Plugins

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-knowledgebase-rag** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-embedder** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **doc-parser** | 10.9.0 | 10.7.0 | 10.6.2 | 10.5.1 | - | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-agent-builder** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **data-privacy** | 10.1.0 | 10.1.0 | 10.0.8 | - | - | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **evals-judge** | 10.1.1 | - | - | - | - | - |
| **speech-to-text** | 10.3.4 | 10.3.3 | 10.3.3 | - | - | - |
| **web-crawler** | 10.3.5 | 10.3.5 | 10.3.2 | - | - | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-gateway** | 10.7.0 | - | - | - | - | - |
| **ai-platform-ai-analyst** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-assistant** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **ai-platform-ai-designer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-developer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **di-platform** | 10.3.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **flowx-docs** | 5.9.0 | - | - | - | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - | - | - |
| **ai-observatory** | 10.3.2 | - | - | - | - | - |

***

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

***

## Kafka topics

### Document-plugin archive and extract listeners

5.9.0 exposes four Kafka topics for the document-plugin **archive** and **extract** operations. Both follow the encrypt/decrypt trigger and reply pattern: document-plugin consumes the `trigger.*.file` topic and process-engine consumes the matching `engine.receive.*.file.results` reply.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.archive.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.extract.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` | document-plugin | process-engine |

The four topic names are exposed as env vars on the document-plugin side (`KAFKA_TOPIC_FILE_ARCHIVE_IN`, `KAFKA_TOPIC_FILE_ARCHIVE_OUT`, `KAFKA_TOPIC_FILE_EXTRACT_IN`, `KAFKA_TOPIC_FILE_EXTRACT_OUT`). See [Documents plugin setup → File archive / File extract](/5.9/setup-guides/documents-plugin-setup#file-archive). Two new thread-pool entries are added: `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN` and `..._FILEEXTRACTIN`, both defaulting to `5`.

### Document-plugin encrypt and decrypt listeners

The **encrypt** and **decrypt** operations follow the same trigger-and-reply pattern: process-engine produces the `trigger.*.file` topic and document-plugin replies on the matching `engine.receive.*.file.results` topic.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | document-plugin | process-engine |

The topic names are exposed as env vars on the document-plugin side: `KAFKA_TOPIC_FILE_ENCRYPT_IN`, `KAFKA_TOPIC_FILE_ENCRYPT_OUT`, `KAFKA_TOPIC_FILE_DECRYPT_IN`, `KAFKA_TOPIC_FILE_DECRYPT_OUT`.

### Document-plugin session-upload listeners

Multi-file upload for UI flows routes uploaded files to the document-plugin for persistence. process-engine produces the trigger topic and document-plugin consumes it — `session` for a single upload session and `session.bulk` for batched multi-file uploads.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | process-engine | document-plugin |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | document-plugin |

The topic names are exposed on process-engine as `KAFKA_TOPIC_SESSION_UPLOAD_OUT` and `KAFKA_TOPIC_SESSION_UPLOAD_BULK_OUT`, and on document-plugin as `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN` and `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN`.

### AI Platform job topics

`integration-designer` dispatches asynchronous jobs to the standalone AI services over Kafka, using a request/response pair per service. Provision these topics when you deploy the corresponding AI service (see [AI components](#ai-components) above).

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.ai-platform.doc-parser.job.request.v1` | integration-designer | doc-parser |
| `ai.flowx.ai-platform.doc-parser.job.response.v1` | doc-parser | integration-designer |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | integration-designer | evals-judge |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | evals-judge | integration-designer |
| `ai.flowx.ai-platform.speech-to-text.job.request.v1` | integration-designer | speech-to-text |
| `ai.flowx.ai-platform.speech-to-text.job.response.v1` | speech-to-text | integration-designer |

On `integration-designer` the topic names are set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_REQUEST_OUT` and `..._RESPONSE_IN` (for example `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`). Each service also has a dead-letter topic — `ai.flowx.ai-platform.<service>.job.dlq.v1`, set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_DLQ_IN` — that integration-designer consumes for failed jobs.

### UI Flow runtime triggers

process-engine consumes two trigger topics that back the UI Flow runtime cache and expiration features. `update` invalidates a cached UI Flow when its definition changes; `expire` removes expired UI Flow runtime data.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer | process-engine |
| `ai.flowx.core.trigger.expire.ui-flow.v1` | scheduler-core | process-engine |

On process-engine these are set via `KAFKA_TOPIC_UIFLOW_UPDATE_IN` and `KAFKA_TOPIC_UIFLOW_EXPIRE_IN`; the producers expose `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`. The expire trigger uses the platform scheduler: when a UI Flow session is created, process-engine registers a delayed message with scheduler-core, which publishes it back to this topic at the expiry time. It is consumed by a dedicated consumer group (`KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE`, default `ui-flow-expire`).

### File and webhook process triggers

Two trigger topics let the file-gateway and webhook-gateway start or resume processes in process-engine. The **start-for-event** topic starts a process when a watched file arrives (file-gateway) or an incoming webhook fires (webhook-gateway); the **message event** topic resumes a running process that is waiting on an intermediate message catch event.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | file-gateway, webhook-gateway | process-engine |
| `ai.flowx.core.message.event.process.v1` | webhook-gateway | process-engine |

On the producers, the start-for-event topic is set via `KAFKA_TOPIC_TRIGGER_STARTFOREVENT_PROCESS_OUT` (file-gateway) and `KAFKA_TOPIC_PROCESS_START_OUT` (webhook-gateway); process-engine consumes it via `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`. The message event topic uses `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` on both webhook-gateway and process-engine. Like every service, file-gateway and webhook-gateway also publish to the shared audit topic `ai.flowx.core.trigger.save.audit.v1` via `KAFKA_TOPIC_AUDIT_OUT` (consumed by audit-core).

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Data-sync: Keycloak admin credentials

The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak on first run, using the Keycloak admin API. Configure the following on the data-sync job:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak` (the only supported provider). | `keycloak` | data-sync |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` | data-sync |
| `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` | data-sync |
| `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` | data-sync |
| `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Typically `admin-cli` for standard Keycloak deployments. Must be set explicitly. There is no default. | `-` | data-sync |

For full data-sync configuration, see [Data-sync job setup](/5.9/setup-guides/data-sync#openid-provider-configuration).

### Anonymous service account: shared client secret

5.9.x introduces a single shared service-account client, `flowx-anonymous-sa`, used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows. One client secret is reused across all consumers — it must be provided in two places.

**On `authorization-system`** — passed to Liquibase so the client is provisioned with the correct secret when FlowX manages Keycloak:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXANONYMOUSSA` | Client secret used by Liquibase to create the `flowx-anonymous-sa` client in the service-accounts realm at first boot. Required when `SECURITY_KEYCLOAKADMINENABLED=true`. | `-` | `authorization-system` |

**On every consuming service** — the Spring Security OAuth2 client registration for the `anonymousidentity` alias resolves the same secret at runtime:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Client secret for the `anonymousidentity` registration. **Must be the same value across every service** — it is a single shared service account. | `-` | `admin`, `application-manager`, `authorization-system`, `document-plugin`, `email-gateway`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `mock-server`, `nosql-db-runner`, `organization-manager`, `process-engine`, `scheduler-core`, `task-management-plugin`, `webhook-gateway` |

> [!WARNING]
>
> This is a secret. Store it in your secrets management solution (e.g., Kubernetes Secret, Vault) and reference it from there. Never commit it to version control.

For the Keycloak-side context (`flowx-anonymous-sa` client, `SA_FLOWX_ANONYMOUS` realm role, manual-configuration recipe for deployments without Keycloak admin access), see [Manual Keycloak configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).

### Knowledgebase-rag: Qdrant search tuning

Two env vars control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Defaults are tunable per environment.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. | `100` | knowledgebase-rag |
| `QDRANT_FUSION_LIMIT` | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker input. | `80` | knowledgebase-rag |

Raise both when recall is insufficient on very large or long-tailed Knowledge Bases. Lower them when Qdrant pods report memory pressure or filter-heavy queries time out.

### CORS handling: `APPLICATION_CORS_ALLOWORIGIN`

CORS is enforced at the application layer. Each backend service exposed via admin or public URLs reads its allowed-origin list from a single environment variable. Allowed methods, allowed headers, exposed headers, and credential handling are baked into each service's `application.yaml` with safe defaults. The 5.9.x default allow-headers set is `Accept, Content-Type, Authorization, Fx-Workspace-Id, Fx-Client-Host, Referer, User-Agent, Flowx-Platform, X-Fx-Anonymous-Session-Id, Fx-BuildId, Fx-AppId`, and `X-Fx-Anonymous-Session-Id` is exposed to the browser for anonymous runtime sessions. Only `APPLICATION_CORS_ALLOWORIGIN` is deployment-specific.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains (`https://*.yourcompany.com`). Must include every Designer, runtime renderer, and integration domain that calls FlowX APIs. | `-` | `admin`, `ai-gateway`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway` |
| `APPLICATION_CORS_EXPOSEDHEADERS` | Response headers exposed to browser JavaScript. The default carries the anonymous-session header; override only if you need to expose additional custom headers. | `X-Fx-Anonymous-Session-Id` | all services (shared security library) |

For migration guidance and the full list of removed NGINX CORS annotations, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

### Process-engine and integration-designer: native script engine

The default script engine for JavaScript and Python execution is a **native subprocess pool**. Scripts run in isolated Node.js and Python worker processes.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider | `native` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size | `16` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary | `/usr/bin/node` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS script execution timeout (ms) | `5000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a JS worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max JS input payload size (bytes) | `1048576` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size | `8` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary | `/usr/bin/python3` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python script execution timeout (ms) | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a Python worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max Python input payload size (bytes) | `1048576` | process-engine, integration-designer |

To use GraalVM instead of the native engine, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services.


# FlowX.AI 5.9.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026

First LTS in the 5.9.x family. Brings conversational AI, UI Flows and Custom Components, AI Platform, runtime authorization, new React Native and iOS UI Flow SDKs, and a wide set of integration and process-ops improvements.

[FlowX.AI 5.9.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-5.9.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted deployments
> * All Deployments Features available in both self-hosted and SaaS

### What 5.9.0 includes

* **Closes the runtime authorization rewrite**. Per-environment sharing, project-version-scoped roles, data-sync Keycloak provisioning.
* **Brings the full set of changes accumulated since the 5.1.x LTS line**. Conversational AI, UI Flows, Custom Components, AI Platform, runtime authorization.
* **Ships a new React Native SDK** and rounds out iOS UI Flow support.

> [!NOTE]
>
> **5.9.0 is the first LTS in the 5.9.x family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Self-hosted customers upgrading from 5.1.x LTS go directly to 5.9.0. See the [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview) guide for the consolidated upgrade path.

***

**What's in this LTS release?**

> [tab] Runtime authorization and sharing
>
> 🔐 [**Runtime authorization completion**](#runtime-authorization-completion) - Per-environment sharing checklist, project-level end-user roles, data-sync provisioning of Keycloak groups and roles.\
> 🌐 [**Anonymous runtime access**](#anonymous-runtime-access) - Built-in Anonymous role + Share modal "Everyone with the link" for unauthenticated end users; session-bound, SDK auth-skip mode.\
> 🛡️ [**Runtime authorization overhaul**](#runtime-authorization-overhaul) - Project-version-scoped roles, end-user groups moved from Keycloak into FlowX, Solutions → Share modal flow, Active Policy gate, designer-user bypass.\
> 🔒 [**UI Flow permissions**](#ui-flow-permissions) - Per-UI-Flow role allow-list with runtime 403 enforcement; assignments travel with import/export.\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.\
> 🎯 [**Active policy: group overrides**](#active-policy-group-overrides) - Override a project's active build per runtime group; legacy role overrides are excluded from runtime resolution and only kept for deletion.\
> 🧩 [**Roles carried across project-version merges**](#roles-carried-across-project-version-merges) - Application-version roles cloned onto the merged version automatically, no manual re-binding after merge.\
> 🏷️ [**Operations-editor role**](#operations-editor-role) - **Workspace operations editor** role and `wks_process_instance_variables_edit` permission for ops teams.\
> 🗂️ [**Cross-workspace projects**](#cross-workspace-projects) - Import the same project into multiple workspaces in the same environment.\
> 🔁 [**Cross-LTS import/export**](#cross-lts-import/export) - Move project versions and builds between the 5.1.x and 5.9.x LTS lines, in both directions.\
> 🚪 [**Log-in page redesign**](#log-in-page-redesign) - IdP provider button replaces the fallback link; refreshed labels across the log-in flow.

> [tab] Conversational AI
>
> 💬 [**Chat component**](#chat-component) - Standalone chat tab; Inline / Floating / FullScreen modes; iOS and Android support; Chat History; Suggested Prompts; Markdown.\
> 🌀 [**Conversational Workflows**](#conversational-workflows) - Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node.\
> 🎙️ [**Voice input + Speech-to-Text**](#voice-input-+-speech-to-text) - Audio recording in chat; Speech-to-Text node for transcription.\
> 🧠 [**Memory capabilities**](#memory-capabilities) - Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full; Use conversation memory toggle on the AI / Custom Agent node.\
> 🧭 [**Intent Classification node**](#intent-classification-node) - LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.\
> 💭 [**Chat-based UI Flows**](#chat-based-ui-flows) - Flow-Based vs Chat-Based experience type set at the UI Flow level.\
> ⚡ [**AI Triggers**](#ai-triggers) - Named parameterized message templates to launch conversational workflows with context.\
> 🏷️ [**Chat title generation and conversation search**](#chat-title-generation-and-conversation-search) - Auto-generated session titles + cross-conversation search on the chat history.\
> 🛑 [**Stop agent response**](#stop-agent-response) - Stop button while streaming; cancels the underlying workflow.

> [tab] AI Agents and Knowledge
>
> 📊 [**Evaluations (Evals)**](#evaluations) - LLM-as-judge, RAG-quality, and code evaluators score AI node outputs; datasets, experiments, per-org judge model via new `EVAL` capability.\
> 🤖 [**Custom Agent nodes**](#custom-agent-nodes) - AI agents that use MCP tools to act autonomously in workflows.\
> 🔎 [**Web Search tool for Custom Agents**](#web-search-tool-for-custom-agents) - Built-in web search so Custom Agents can look up up-to-date public-web information during a run.\
> 🔌 [**MCP integration**](#mcp-integration) - MCP servers as data sources; tools in Custom Agent nodes; OAuth 2.0, BEARER, BASIC auth.\
> 📖 [**Knowledge Bases**](#knowledge-bases) - PDF upload, workflow ingestion, semantic search, Custom Agent integration; Stores rename + typed filter builder; system metadata; Kafka indexer/embedder.\
> 🧰 [**AI Providers self-service**](#ai-providers-self-service) - Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability.\
> 🛡️ [**PII Guard: per-entity detections on documents and images**](#pii-guard-per-entity-detections-on-documents-and-images) - Document and image scans return the same per-entity detection list as text scans, with bounding regions.\
> 📝 [**Operational prompt split**](#operational-prompt-split) - System prompt split into operational guardrails and user-instruction layers, versioned independently.\
> 📄 [**Extract Data from File**](#extract-data-from-file) - LLM / OCR / Text Parsing strategies; image input; signature detection.\
> 🌐 [**Web Page Extractor / Web Crawler**](#web-page-extractor-/-web-crawler) - Static or dynamic URLs, link-following depth, PDF extraction, URL filtering, file downloads, multi-URL filters.\
> 📚 [**Manage Knowledge Base content from Runtime**](#manage-knowledge-base-content-from-runtime) - End users can add and update KB content at runtime without going back to the Designer.\
> ✨ [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent drafts React Custom Components from a brief.

> [tab] UI Flows and Custom Components
>
> 🪟 [**UI Flows**](#ui-flows) - Reusable multi-platform UI as project resources; Sessions monitoring; Process Renderer; Route Management; Start Parameters; Session Variables; onClick / On Display / On Load events.\
> ⏳ [**UI Flow session expiry**](#ui-flow-session-expiry) - Expire a UI Flow after a duration or on a schedule; expired sessions become read-only.\
> 🖼️ [**Configurable modal component**](#configurable-modal-component) - Title, subtitle, dismiss behavior, alignment and sizing on modals; theme-level shadow and dismiss icon.\
> 💻 [**Custom Components**](#custom-components) - React JSX / CSS in the Designer; Custom Components in Processes with INPUT/OUTPUT mappings.\
> 🎬 [**Event Handlers**](#event-handlers) - Typed Event Handlers section in the UI component config panel; UI events and AI triggers unified under one model.\
> ♿ [**Accessibility (WCAG 2.1 AA)**](#accessibility-wcag-2-1-aa) - Cross-platform accessibility model surfaced in the UI Designer.\
> 🧱 [**New theme components**](#new-theme-components) - Tooltip, Markdown, Progress Bar, Separator across React / Angular / Android.\
> 📤 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Multiple File Upload on process screens and UI Flows; Angular and React SDK support.\
> 🎨 [**Theming and Designer polish**](#theming-and-designer-polish) - Scoped variants and padding for form labels/errors/helpers, mandatory-label style.

> [tab] Integration and Data Platform
>
> 📨 [**Email Trigger**](#email-trigger) - IMAP-triggered processes; attachments to the `document-plugin`; validation rules.\
> 📧 [**Microsoft Outlook data source**](#microsoft-outlook-data-source) - Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes.\
> 🪝 [**Incoming Webhooks**](#incoming-webhooks) - New `webhook-gateway` microservice; trigger processes via HTTP POST; Slack provider adapter.\
> 🗄️ [**Oracle Database integration**](#oracle-database-integration) - Oracle 21c / 23ai data source; schema-aware Monaco editor.\
> 🍃 [**Unmanaged MongoDB data source**](#unmanaged-mongodb-data-source) - Connect to externally managed MongoDB 6.0+ instances.\
> 📁 [**File Storage data source**](#file-storage-data-source) - Move files in and out of external FTP / SFTP / S3 / Azure Blob storage from workflows.\
> 📨 [**Meta webhook provider**](#meta-webhook-provider) - WhatsApp / Messenger / Instagram / Threads webhook support with verify-token handshake and X-Hub-Signature-256 verification.\
> 📂 [**Documents in process instances**](#documents-in-process-instances) - Dedicated Documents section on each process instance.\
> 📤 [**Send Notification action + Email Sender**](#send-notification-action-+-email-sender) - SMTP data source; new action sends or replies email directly without Kafka.\
> 🎛️ [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder replacing manual JSON, with new operators.\
> 🧬 [**Parallel branches in workflows**](#parallel-branches-in-workflows) - Start / End Parallel nodes for concurrent execution.\
> ⚡ [**REST endpoint caching + workflow partitioning**](#rest-endpoint-caching-+-workflow-partitioning) - TTL-based REST GET caching; time-based workflow partitions with retention.\
> 🔗 [**Data mappers + workflow data models**](#data-mappers-+-workflow-data-models) - Workflow data models with input/output; process ↔ workflow mapping; CRUD endpoints.\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Reusable HTTP/HTTPS proxies attached to REST data sources.\
> ✉️ [**Two-stage attachment filtering for Email triggers**](#two-stage-attachment-filtering-for-email-triggers) - Choose which emails trigger the process and which attachments are forwarded into it.\
> ⏸️ [**Resume a process from an incoming webhook**](#resume-a-process-from-an-incoming-webhook) - Webhooks now drive Message Catch Intermediate Events with a Process Correlation Key.\
> 🌐 [**REST endpoints: content-type-aware responses**](#rest-endpoints-content-type-aware-responses) - Accept-driven JSON / text / XML parsing with XXE-safe XML; responses over 5 MiB are returned raw.\
> 📝 [**Raw endpoint payload type**](#raw-endpoint-payload-type) - Send request body as-is with the user's Content-Type preserved; XML / SOAP / form-urlencoded / plain text without MULTIPART wrapping.

> [tab] Process operations
>
> ✏️ [**Update Process Variables**](#update-process-variables) - JSON editor for variables on active instances; snapshot history; Compare diff.\
> 🛑 [**Stop workflow instances in runtime**](#stop-workflow-instances-in-runtime) - Authorized end users can stop running workflow instances from runtime.\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor.\
> 🔔 [**Notification history + template usages**](#notification-history-+-template-usages) - `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all references.\
> 📋 [**Token view improvements**](#token-view-improvements) - Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, color-coded status.\
> 🔧 **Fixed: names with square brackets** - Processes and UI flows whose names contain square brackets now start correctly again.

> [tab] Platform, deployment and infrastructure
>
> 🏢 [**Single-org self-hosted deployment**](#single-org-self-hosted-deployment) - Self-hosted default mode; guided setup wizard.\
> 🔑 [**License service**](#license-service) - Centralized license validation and usage reporting for self-hosted deployments.\
> 🔐 [**Authentication: opaque-token → JWT**](#authentication-opaque-token-→-jwt) - Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key`; dedicated service-accounts realm.\
> 🆕 [**New services to deploy**](#new-services-to-deploy) - `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. None existed in a 5.1.x deployment.\
> 🐍 [**Native script engine for JavaScript and Python**](#native-script-engine-for-javascript-and-python) - Default JS/Python execution moves from GraalVM to a Node.js + CPython subprocess pool; GraalVM available as opt-in.\
> 🌐 [**Ingress routing and CORS handling**](#ingress-routing-and-cors-handling) - NGINX ingress controller deprecated as the FlowX-shipped default; CORS moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on every backend service.\
> 📡 [**Kafka configuration alignment**](#kafka-configuration-alignment) - Standardized `KAFKA_*` env vars; mandatory `Fx-Organization-Id` header.\
> 📊 [**OpenTelemetry + SpiceDB DR**](#opentelemetry-+-spicedb-dr) - OpenTelemetry / Prometheus Helm charts published; SpiceDB backup and disaster-recovery procedures.\
> 🛡️ [**Durable message-processing**](#durable-message-processing) - Parked integration responses are persisted durably so in-flight responses survive runtime restarts, reducing stuck process tokens.\
> 🌍 [**Task management localization**](#task-management-localization) - 51 substitution tags + automatic table grid localization across 30 languages.

> [tab] Mobile & Renderers
>
> 📱 [**React Native SDK**](#react-native-sdk) - New SDK for React Native apps with process renderer, forms, navigation, and CMS integration. Demo app included.\
> 🍎 [**iOS UI Flows support**](#ios-ui-flows-support) - Full UI Flows renderer on iOS; sessions, document plugin subtypes, dismiss action, start parameters, new native components.\
> 📲 [**Mobile chat support**](#conversational-ai) - Chat component available on iOS and Android.\
> ⚛️ [**React 19 upgrade**](#react-19-upgrade) - React SDK upgraded to React 19; host apps must upgrade in lockstep.

> [tab] Info
>
> ℹ️ [**Deployment guidelines**](./deployment-guidelines-v5.9) - Component versions, environment variables, Kafka topics\
> 🗺️ [**Migrating from 5.1 LTS**](/5.9/migrating-from-5.1-lts/overview) - Consolidated upgrade path from 5.1.x LTS to 5.9.x LTS

> [card]
>
> ### **Runtime authorization completion**
>
> 5.9.0 completes the project-version-scoped runtime authorization model:
>
> * **Sharing checklist for environment promotion.** Sharing assignments do not export with builds. Each environment must be reconfigured when a project is promoted. The deployment checklist for this is now part of the setup guide.
> * **Project-level end-user roles.** Roles can be assigned at the project level from creation, so a fresh project is reachable without a separate share pass.
> * **Data-sync provisioning.** The data-sync job calls the Keycloak admin API on first run to provision FlowX-managed end-user groups and runtime roles. Five new `FLOWX_OPENID_*` env vars expose the admin credentials.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > See Setup guides → Access management → Runtime authorization for the day-to-day model.
>
> > [accordion] Key Features
> >
> > * **Per-environment sharing checklist.** When you promote a project from dev to uat to prod, the Share modal assignments do not travel with the build. The setup guide now documents the explicit per-environment reconfiguration step.
> > * **Project-level end-user roles.** Assign end-user roles at the project level so a freshly created project is reachable on day one. No separate Share-modal pass required for the default access pattern.
> > * **Data-sync Keycloak provisioning.** The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak the first time it runs against a 5.9.0 environment. Configure admin credentials with the new `FLOWX_OPENID_*` env vars on the data-sync job.
> > * **Deployment checklist included.** The runtime authorization setup guide now ships a deployment prerequisites section so the data-sync OpenID config and per-environment sharing reset are part of the standard promotion runbook.
>
> > [accordion] Configuration
> >
> > Required on the data-sync job from 5.9.0 onward:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak`. | `keycloak` |
> > | `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` |
> > | `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` |
> > | `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` |
> > | `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Set to `admin-cli` for standard Keycloak deployments. | `-` |
> >
> > See [Data-sync job setup → OpenID provider configuration](/5.9/setup-guides/data-sync#openid-provider-configuration) for the full setup.

> [card]
>
> ### **Anonymous runtime access**
>
> 5.9.0 introduces unauthenticated runtime access: an app can be made publicly reachable, and processes or UI flows inside it can be opened to anonymous end users via a new built-in role.
>
> * **Two independent gates.** The app must be set to **Everyone with the link** in the Share modal AND the process or UI flow must have the **Anonymous** role assigned. If either gate is closed, the runtime returns `403 Forbidden` (`Anonymous access not enabled for this application` / `Anonymous access not enabled for this build`).
> * **System-level Anonymous role.** Auto-seeded on every new app version, cannot be deleted or edited; allowed operations are `VIEW`, `EXECUTE`, and an auto-populated `SELF_ASSIGN`.
> * **Session-bound traffic.** Anonymous requests carry an `X-Fx-Anonymous-Session-Id` header. The backend issues a new session ID on first contact; instances are bound to that session and cannot be read by another.
> * **SDK auth-skip.** The renderer decides authenticated vs anonymous from the `authToken` parameter at initialization. Token-in-storage on the same browser silently bypasses anonymous mode — container apps must scrub the `Authorization` header on public routes.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access)
> >
> > See Platform deep-dive → User roles management → Anonymous runtime access for the full feature reference.
>
> > [accordion] Key Features
> >
> > * **Share modal public-access option.** A new **General access** section in the Share modal switches between **Everyone with the link** and **Only invited users and groups**. Default remains invited-only.
> > * **Anonymous role on processes, UI flows, and reusable UI templates.** Selectable in the Permissions tab once the role is on the version; additive to other roles.
> > * **Component hide / disable rules.** UI Designer supports an Anonymous condition in role-based hide/disable rules at the component level.
> > * **Public-build asset rule.** When a build has the Anonymous role and the app is shared publicly, all assets inside (enumerations, substitution tags, media files, themes, fonts) become reachable anonymously — except UI flows and processes that don't carry the Anonymous role.

> [card]
>
> ### **Runtime authorization overhaul**
>
> Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > Open the **Runtime authorization overhaul** documentation.

> [card]
>
> ### **UI Flow permissions**
>
> Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> >
> > Open the **UI Flow permissions** documentation.

> [card]
>
> ### **End-user access management**
>
> Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> >
> > Open the **End-user access management** documentation.

> [card]
>
> ### **Operations-editor role**
>
> New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix)
> >
> > Open the **Operations-editor role** documentation.

> [card]
>
> ### **Cross-workspace projects**
>
> Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/workspaces#cross-workspace-project-import)
> >
> > Open the **Cross-workspace projects** documentation.

> [card]
>
> ### **Cross-LTS import/export**
>
> Move project versions and builds between the **5.1.x** and **5.9.x** LTS lines, in both directions. A newer platform version imports exports produced by an older one, and exports produced on a newer version can target an older one — useful for shipping a hotfix to an environment that hasn't been upgraded yet. Compatibility is patch-agnostic: any 5.9.x patch works with any 5.1.x patch.
>
> When exporting to an older version, resources whose type doesn't exist there are excluded automatically and listed in a `manifest_excluded.json` file in the archive, so the import still succeeds. The lowest version in the export/import path defines the usable functionality.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import)
> >
> > Open the **Cross-version export and import** documentation.

> [card]
>
> ### **Active policy: group overrides**
>
> Active policy overrides can now target **runtime groups** instead of runtime roles. The override resolves the active build for every member of the group at runtime, with a priority field deciding which group wins when a user belongs to several.
>
> Role-based overrides are deprecated in the same change. The **Role** override type is gone from the Add / Edit modal, and any role overrides carried over from a 5.1.x upgrade are kept in the table for visibility only — they are flagged **DEPRECATED**, excluded from runtime resolution, and can only be deleted.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-policy)
> >
> > See Projects → Runtime → Active policy for the full configuration model.
>
> > [accordion] Key Features
> >
> > * **Group override type.** Add / Edit Policy Override now exposes **Username** and **Group**. The group picker lists runtime groups that have a runtime role configured for the current project.
> > * **Priority is mandatory and unique per project for group overrides.** Lower numbers win when several groups match the same user. Username overrides ignore priority and always take precedence.
> > * **Resolution order.** Username override → Group override (lowest priority wins) → Global policy.
> > * **Role overrides deprecated.** Removed from the Add / Edit modal. Existing role rows are rendered muted with a **DEPRECATED** marker and a red banner; only the delete action remains. Deprecated role overrides are excluded from runtime resolution.
> > * **Test panel.** The effective-policy test panel simulates resolution for a given user.
> > * **Audit log.** Group override create / update / delete / enable / disable events are recorded.
>
> > [accordion] Upgrade impact
> >
> > Upgrading from 5.1.x carries existing role overrides into the new table as deprecated entries. They no longer affect runtime behavior. Recreate the intended access using group overrides and delete the role rows. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.

> [card]
>
> ### **Roles carried across project-version merges**
>
> Application-level role definitions are now carried into the merged project version automatically. Before 5.9.0, merging two project versions could leave the role table in a partial state. Bindings defined on one side were not consistently propagated to the merged version. 5.9.0 clones the roles from the destination latest version onto the merged version atomically as part of the merge transaction, so merges with role changes complete without follow-up manual cleanup.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Roles propagated as part of the merge.** When a project version is merged, application-version roles from the destination latest version are cloned onto the merged version in the same transaction.
> > * **No manual role re-binding after merge.** Operators no longer need to re-apply role bindings on the merged version. The merge completes in a single commit; the merged version is immediately usable.

> [card]
>
> ### **Log-in page redesign**
>
> The Designer log-in page is refreshed to align with the platform's design system. When an organization has an external IdP configured, the previous fine-print fallback link is replaced with a primary button labeled with the IdP configuration's **Display name**. Field labels and call-to-action copy across the log-in flow are aligned with the rest of the UI.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **IdP provider button.** When the organization has an IdP configured, the log-in screen surfaces a primary button labeled with the IdP's **Display name**, instead of a fine-print link below the form.
> > * **Refreshed copy.** Updated labels across the flow: **Log In** replaces *Sign In*, **Reset Password** replaces *Forgot password?*, and the page title becomes **Log In**.

> [card]
>
> ### **Chat component**
>
> Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component)
> >
> > Open the **Chat component** documentation.

> [card]
>
> ### **Conversational Workflows**
>
> Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> >
> > Open the **Conversational Workflows** documentation.

> [card]
>
> ### **Voice input + Speech-to-Text**
>
> Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> >
> > Open the **Voice input + Speech-to-Text** documentation.

> [card]
>
> ### **Memory capabilities**
>
> Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> >
> > Open the **Memory capabilities** documentation.

> [card]
>
> ### **Intent Classification node**
>
> Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> >
> > Open the **Intent Classification node** documentation.

> [card]
>
> ### **Chat-based UI Flows**
>
> UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> >
> > Open the **Chat-based UI Flows** documentation.

> [card]
>
> ### **AI Triggers**
>
> Named parameterized message templates to launch conversational workflows with context.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> >
> > Open the **AI Triggers** documentation.

> [card]
>
> ### **Stop agent response**
>
> Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> >
> > Open the **Stop agent response** documentation.

> [card]
>
> ### **Chat title generation and conversation search**
>
> Chat sessions now get a meaningful title generated automatically from the user's first message. No more "untitled chat" entries in the history. End users can also search across all their conversations with a single query that scans both message bodies and session titles.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Auto-generated session title.** The first user message seeds a provisional title (first 7 words). A one-shot LLM call then refines it into a concise descriptive title; the chat list updates live via an SSE event.
> > * **Conversation search.** `/api/conversations` accepts a `q` query parameter (2–200 characters). Matches against both session titles and message bodies. Each result carries a `snippet` field showing the matched excerpt.
> > * **Title update event.** When the LLM title is generated, the gateway emits a `chatSessionRenamed` event on the chat session channel; the chat list shows the refined title on the next load.
> > * **Single-shot generation.** Title generation runs exactly once per session, on first persist. The provisional 7-word title remains in place if the LLM call fails. No error surfaces to the end user.

> [card]
>
> ### **Evaluations**
>
> 5.9.0 introduces Evaluations: score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Attach datasets to AI nodes, launch experiments, and read per-evaluator aggregate scores plus per-test-case details.
>
> * **10 built-in evaluators across three categories.** LLM-as-judge (Correctness, Conciseness, Hallucination, Answer relevance), RAG (Groundedness, Helpfulness, Retrieval relevance), and Code (Exact match, Levenshtein, JSON match). Numeric evaluators ship with default thresholds; binary evaluators return pass/fail.
> * **Datasets attached to AI nodes.** Test cases sourced manually or captured from real node executions. The dataset persists a schema snapshot so older runs remain reproducible if the workflow changes underneath.
> * **Async judge pipeline.** A new Python `evals-judge` event-driven worker consumes `ai.flowx.ai-platform.evals-judge.job.request.v1`, scores each (test case × evaluator) pair via the configured judge LLM, and publishes back on the response topic. Unscored jobs land on a DLQ for manual review.
> * **Per-org judge model.** A new `EVAL` capability is registered in the org-manager LLM catalogue. Platform default is `gpt-5.4-mini`, backfilled per org on upgrade so evals work out-of-the-box.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/evaluations)
> >
> > See AI Platform → Evaluations for the user workflow, evaluator catalogue, REST API surface, and operator setup.
>
> > [accordion] Key Features
> >
> > * **Designer workflow.** Add a dataset on an AI node, add test cases (manually or captured from a node execution), pick evaluators, launch an experiment, read aggregate + per-test-case reports.
> > * **LLM-as-judge scoring.** A judge LLM reads the model output (and optional expected output) and scores it on a single rubric, returning a numeric score plus its reasoning.
> > * **RAG-quality scoring.** Judges the retrieval side of a RAG workflow — is the retrieved context grounded, helpful, and relevant?
> > * **Deterministic code evaluators.** No LLM call. Exact match, normalized Levenshtein, and JSON-shape match against the dataset's output contract.

> [card]
>
> ### **PII Guard: per-entity detections on documents and images**
>
> PII Guard scans on document and image AI nodes now surface the same per-entity detection list already shown for text scans. The run console reports each match with its entity type, confidence, original value, and replacement, making it easy to verify what was redacted on file-based AI inputs.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Same shape as text scans.** Document and image scans now return a `detections` list with `entityKey`, `confidence`, `originalValue`, `replacement`, and `direction`, matching the existing text-scan output.
> > * **Bounding regions for document and image hits.** Each detection on a `DOCUMENT` or `IMAGE` source includes `regions` (`x`, `y`, `width`, `height`) so the run console can highlight where the entity was matched.
> > * **Source-type tagging.** Detections carry a `sourceType` of `TEXT`, `DOCUMENT`, or `IMAGE`, mirroring the wrapper's `sourceType` field so audit consumers can attribute matches to the right payload.
> > * **Backward-compatible upgrade.** On older data-privacy versions that don't yet return the analyzer pass for object endpoints, `detections` stays empty and the redacted artifacts continue to be produced and downloadable.

> [card]
>
> ### **Custom Agent nodes**
>
> AI agents that use MCP tools to act autonomously inside workflows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> >
> > Open the **Custom Agent nodes** documentation.

> [card]
>
> ### **Web Search tool for Custom Agents**
>
> Custom Agent nodes can call a built-in web search tool to look up up-to-date information from the public web during a run. Turn it on with a single toggle — the agent decides when to search based on its instructions and the user's request.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Single toggle.** Enable **Tools → Built-in tools → Use Web Search Tool** on a Custom Agent node. Off by default; no extra configuration.
> > * **Agent-driven.** The agent calls web search on its own when the task needs current information, and folds the results into its response.

> [card]
>
> ### **MCP integration**
>
> MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> >
> > Open the **MCP integration** documentation.

> [card]
>
> ### **Knowledge Bases**
>
> Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > Open the **Knowledge Bases** documentation.

> [card]
>
> ### **AI Providers self-service**
>
> Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/ai-providers)
> >
> > Open the **AI Providers self-service** documentation.

> [card]
>
> ### **Extract Data from File**
>
> LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> >
> > Open the **Extract Data from File** documentation.

> [card]
>
> ### **Web Page Extractor / Web Crawler**
>
> Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> >
> > Open the **Web Page Extractor / Web Crawler** documentation.

> [card]
>
> ### **Context Retrieval**
>
> RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> >
> > Open the **Context Retrieval** documentation.

> [card]
>
> ### **AI Developer generates Custom Components**
>
> Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> >
> > Open the **AI Developer generates Custom Components** documentation.

> [card]
>
> ### **Operational prompt split**
>
> The single Operation Prompt field on AI nodes is split into two inputs so the static portion of the prompt can be cached by the LLM provider while dynamic values are passed separately. **Instructions** holds the agent's role, tasks, and expected I/O, sent as the System message and cached between executions, so `${}` dynamic values are not allowed. The **Context** field, inside the **Background** section, takes the dynamic per-execution prompt text and supports `${}` references, sent as the User message and not cached.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Instructions: cached System message.** Mandatory. Holds the agent's role, tasks, and expected input/output. Sent as the System message and cached by the LLM between executions. `${}` references are rejected to keep the cache key stable.
> > * **Background section: dynamic User message.** Wraps the Knowledge Base selector, the **Context** textarea (free text with `${}` support), the **Use only referenced values as input** toggle, and, in Chat Driven workflows, the **Use conversation memory** toggle. Sent as the User message on every execution; not cached.
> > * **Lower LLM cost and latency.** The static portion of the prompt is sent once per cache window instead of on every execution, so each call pays only for the dynamic Background section. The longer the Instructions, the bigger the per-call saving.
> > * **Applies to every AI node subtype.** The split UI is now shared by all AI node subtypes that previously used the single Operation Prompt field.

> [card]
>
> ### **Manage Knowledge Base content from Runtime**
>
> A new **Test KB** option on the build is available in runtime, giving operators visibility into Knowledge Base content that was previously opaque after deployment. Authorized users can inspect chunks, add or replace sources, edit metadata, and query the KB without going back to the Designer. Useful for debugging retrieval issues and keeping KBs current as business knowledge evolves.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Six runtime operations.** Create store, Append content, Replace content, Delete store, Edit metadata, and Query. All from the Test KB option inside the running app.
> > * **Files and payloads.** Both file uploads and inline payloads can be added to the KB through this feature.
> > * **Permission-gated.** KB management at runtime is controlled by runtime authorization, so only users with the right role see the Test KB controls.
> > * **Visibility into chunking.** Inspect how documents were chunked and what metadata was captured, useful when debugging retrieval quality on client-uploaded content.

> [card]
>
> ### **UI Flows**
>
> 5.9.0 closes the UI Flows feature: reusable, multi-platform UI (web, iOS, Android) as first-class project resources with their own lifecycle and runtime sessions. UI Flows now reach feature parity with processes for end-user-facing apps that don't need a BPMN process underneath.
>
> * **Multi-platform.** Author once in the Designer; UI Flows render on web (React), iOS, and Android via the platform-specific renderers. Layouts and component bindings travel together as a single resource.
> * **Sessions and runtime monitoring.** Each UI Flow run is a `UiFlowSession` with its own state, navigation history, and SSE event stream. Operators can monitor and inspect sessions from the runtime.
> * **Process integration.** UI Flows can start processes (Start Process action), navigate to other UI Flows (Navigate UI action), and embed a Process Renderer to show a running process inside a UI Flow. Workflows can also be invoked from a UI Flow with a Start Workflow action.
> * **Per-UI-Flow permissions.** A dedicated Permissions tab on each UI Flow controls which roles can run it. Runtime enforces with `403`; assignments travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows)
> >
> > See Building blocks → UI Flows for the full feature reference, including Navigation Areas, session variables, route management, and the component reference.
>
> > [accordion] Key Features
> >
> > * **Navigation Areas.** Group UI components into named areas for layout, scroll, and per-area transitions.
> > * **Start Parameters and Session Variables.** Pass typed inputs into a UI Flow at start; persist state across nodes via Session Variables.
> > * **Route management.** Each UI Flow exposes a stable runtime route; nested navigation preserves browser history and back/forward behaviour.
> > * **Task Manager component.** Drop the Task Manager surface inside a UI Flow to drive process tasks from the same UI shell.
> > * **onClick and On Display events, plus a new On Load event.** Component-level events trigger workflows or UI actions, with the new On Load event firing when the UI Flow first opens.
> > * **Breadcrumbs.** Built-in breadcrumbs reflect the Navigation Area hierarchy and follow the active theme.
> > * **Process Renderer + Start Workflow action.** Embed a running process inside a UI Flow; trigger an integration workflow from a button or event without leaving the flow.

> [card]
>
> ### **UI Flow session expiry**
>
> A UI Flow session can be set to expire automatically after a fixed duration or on a schedule. Once expired, the session becomes read-only — the user keeps the data already loaded but cannot take further action.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Flexible expiry.** Set the **Expiry time** in **Settings → General** as an ISO-8601 duration (for example `PT3M22S`) or a cron expression (for example `0 0 9-17 * * MON-FRI`). Empty means no expiry.
> > * **Read-only on expiry.** Expired sessions block all actions; loaded data stays visible and nothing is wiped.
> > * **Server-enforced.** The platform marks sessions `EXPIRED` server-side, so it applies the same way in the deployed app and the Designer preview.

> [card]
>
> ### **Configurable modal component**
>
> Modals on process screens and UI Flows gain configurable content and layout. Set a title and subtitle, control dismiss behavior, and align and size the modal from the Designer.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Content.** Set the modal **Title** and **Subtitle** from the Settings panel.
> > * **Dismiss behavior.** Toggle **Dismissible**, allow **Backdrop click**, and optionally show a **Confirmation alert** with custom title, message, and button labels.
> > * **Layout.** Align content **Left**, **Center**, or **Right**, and set **Width**/**Height** to **Fixed** or **Auto**.
> > * **Theme-level styling.** The modal **shadow** and **dismiss icon** are defined once in the theme's Modal section.

> [card]
>
> ### **Custom Components**
>
> Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> >
> > Open the **Custom Components** documentation.

> [card]
>
> ### **Process Renderer in UI Flows**
>
> Embed process renderers inside UI Flows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > Open the **Process Renderer in UI Flows** documentation.

> [card]
>
> ### **UI Flow sessions monitoring**
>
> Runtime view with session list, audit log, process tracking, workflow debugging.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> >
> > Open the **UI Flow sessions monitoring** documentation.

> [card]
>
> ### **Accessibility (WCAG 2.1 AA)**
>
> Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> All Deployments

> [card]
>
> ### **New theme components**
>
> Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Open the **New theme components** documentation.

> [card]
>
> ### **Multi-file bulk upload**
>
> Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> >
> > Open the **Multi-file bulk upload** documentation.

> [card]
>
> ### **Card default collapse + Tables in Collections**
>
> Cards configurable to load collapsed; Table UI components inside Collection prototypes.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> >
> > Open the **Card default collapse + Tables in Collections** documentation.

> [card]
>
> ### **Event Handlers**
>
> The UI component configuration panel introduces a dedicated **Event Handlers** section. The legacy `flowx_props` bag is replaced by a typed, per-handler form covering action type, optional analytics, custom body, destination, and collection save-key fields. Container components (Page, Zone, Modal, Tab Bar in UI Flows; Tab on process screens) and inline components resolve their actions through the same model.
>
> Existing UI events and AI triggers are migrated automatically. A Liquibase migration runs on the first 5.9.0 boot and moves the data into the new `ui_action` model. No project re-export or re-import is required.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Typed Event Handlers.** Each handler is a named, typed entity instead of a free-form prop, making configuration easier to validate and audit.
> > * **Action type selector.** Pick the action type from a dropdown that knows which fields are required for that type.
> > * **Analytics, body, destination, save-key.** Per-handler sub-forms cover analytics events, custom request bodies, destination resolution, and collection save-key fields.
> > * **Unified for inline and container components.** Page, Zone, Modal, and Tab Bar containers in UI Flows use the same Event Handlers model as inline components; on process screens, Tab containers use it.

> [card]
>
> ### **Theming and Designer polish**
>
> > [accordion] Theming
> >
> > Form field labels, error messages, and helper text gain padding controls and scoped style variants in the theme model. Theme Admin exposes the new padding properties on segmented buttons, sliders, and input selections; the React and Angular SDKs apply the values in the renderers; the Designer preview reflects them in place. Form fields also pick up a consistent **mandatory label** style applied automatically when a field is required.
> >
> > * **Scoped variants for labels, errors, helpers.** Theme configs can override label, error, and helper styles per component without affecting other parts of the form.
> > * **Padding for segmented buttons, sliders, input selections.** Theme Admin adds label, error, and helper padding controls for these components; values flow through to all renderers.
> > * **Mandatory label style.** A consistent style for mandatory-field labels, applied automatically when a form field is required.
> > * **Designer preview parity.** Theme overrides and paddings are visible in the Designer preview without round-tripping through a runtime app.
> >
> > All Deployments
>
> > [accordion] Designer polish
> >
> > The command center floating action button is now hidden on the running-instance screens of Processes, UI Flows, and UI Templates, where it overlapped with the instance view; it reappears when the instance data panel is open. The command center remains reachable through the standard keyboard shortcut and from screens where it does not interfere.
> >
> > All Deployments

> [card]
>
> ### **Email Trigger**
>
> New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> >
> > Open the **Email Trigger** documentation.

> [card]
>
> ### **Microsoft Outlook data source**
>
> Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> >
> > Open the **Microsoft Outlook data source** documentation.

> [card]
>
> ### **Incoming Webhooks**
>
> New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> >
> > Open the **Incoming Webhooks** documentation.

> [card]
>
> ### **Oracle Database integration**
>
> Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL. Beyond tables and `SELECT`, queries can also target views, functions, and stored procedures, with output parameters returned to the workflow.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> >
> > Open the **Oracle Database integration** documentation.

> [card]
>
> ### **Unmanaged MongoDB data source**
>
> Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> >
> > Open the **Unmanaged MongoDB data source** documentation.

> [card]
>
> ### **File Storage data source**
>
> A new data source connecting workflows to external file storage — FTP, SFTP, S3 / S3-compatible, or Azure Blob Storage. Define named List, Download, Upload, Delete, and Move operations scoped to a root path, browse and test them in Designer, and call them from a Data Source node. Operations run in the new `file-gateway` service, exchanging files with the `document-plugin`.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/file-storage)
> >
> > Open the **File Storage data source** documentation.

> [card]
>
> ### **Send Notification action + Email Sender**
>
> SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> >
> > Open the **Send Notification action + Email Sender** documentation.

> [card]
>
> ### **Advanced Query Builder**
>
> Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> >
> > Open the **Advanced Query Builder** documentation.

> [card]
>
> ### **Parallel branches in workflows**
>
> Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> All Deployments

> [card]
>
> ### **REST endpoint caching + workflow partitioning**
>
> TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> All Deployments

> [card]
>
> ### **Data mappers + workflow data models**
>
> Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> >
> > Open the **Data mappers + workflow data models** documentation.

> [card]
>
> ### **Proxy Server Connections**
>
> Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> >
> > Open the **Proxy Server Connections** documentation.

> [card]
>
> ### **Faster authoring loop**
>
> 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.
>
> All Deployments

> [card]
>
> ### **Meta webhook provider**
>
> Incoming Webhooks add **Meta** as a built-in provider alongside Generic and Slack, covering WhatsApp, Messenger, Instagram, and Threads. The webhook-gateway handles the Meta-specific subscription handshake and signature verification natively. No custom adapter code required to wire a Meta-platform integration into a FlowX process.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Subscription handshake.** The gateway answers Meta's GET URL-verification request by validating `hub.mode=subscribe` and the provided `hub.verify_token` against the configured verify token, then echoes `hub.challenge` back. Constant-time token comparison.
> > * **X-Hub-Signature-256 verification.** Every POST is authenticated with the `X-Hub-Signature-256` HMAC-SHA256 signature using the configured app secret. Requests with missing or invalid signatures are rejected before reaching the process engine.
> > * **Two secrets per webhook.** When you create a Meta webhook in Integration Designer, two masked inputs appear in the configuration panel: **Verify token** (used during the handshake) and **App secret** (used for signature verification). Both are required.
> > * **Multi-product support.** A single Meta webhook can receive events from WhatsApp, Messenger, Instagram, and Threads. The provider is configured at the webhook level; the channel is part of the payload.
>
> > [accordion] Configuration
> >
> > Select **Meta** in the provider dropdown when creating the webhook data source. Both secret fields are required:
> >
> > | Field | Description |
> > | - | - |
> > | **Verify token** | The token Meta sends back during the GET URL-verification handshake. Choose any string; configure the same value on the Meta App developer console. |
> > | **App secret** | The App secret from the Meta App configuration; used to verify the `X-Hub-Signature-256` HMAC on every POST. |
> >
> > Both values are stored as a JSON-packed pair on the existing webhook secret field. No schema migration is required.
> >
> > See [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#meta-provider) for the full setup walk-through.

> [card]
>
> ### **Documents in process instances**
>
> Each process instance now exposes a dedicated **Documents** tab. A single source of truth for every document handled during the process, regardless of how it entered the instance. Operations teams can review tracking metadata, preview, and download attached files from one place rather than walking through the process timeline.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **All document sources in one place.** End-user uploads via the file-upload component, attachments from email triggers, files generated from HTML templates, OCR output, and files produced by AI workflow nodes, all listed under one tab.
> > * **Tracking metadata and preview.** Each row shows source, timestamp, and uploader, with inline preview for supported file types.
> > * **Direct download.** Download any attached document directly from the Documents tab.
> > * **Faster operations review.** No more clicking through the process timeline to reconstruct which file came in at which step.

> [card]
>
> ### **Two-stage attachment filtering for Email triggers**
>
> Email triggers (IMAP and Microsoft Outlook) now expose a two-stage filter on each trigger: choose which incoming emails create a process instance, then choose which attachments are forwarded into the process. The previous single on/off validations toggle is replaced with explicit, per-trigger control over inbound mail.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start Process for.** Trigger the process for all emails, only emails with attachments, or only emails carrying selected file types (PDF, DOCUMENT, IMAGE, EXCEL, ZIP).
> > * **Save email attachments on process.** Forward all attachments, none (metadata-only), or only specific file types into the process instance.
> > * **Trigger-level rejection.** Emails that fail the trigger condition or exceed **Maximum File Count** are rejected with explicit Failed Triggers causes. **No attachments**, **No matching file types**, **File count exceeded**.
> > * **Backward-compatible upgrade.** Existing triggers are migrated to **All incoming emails** + **All attachments** with no manual intervention. Reopen each trigger to reapply file-type filtering if you previously relied on the validations toggle.

> [card]
>
> ### **Resume a process from an incoming webhook**
>
> Incoming Webhooks can now drive a **Message Catch Intermediate Event**, not just a Message Start Event. When a process is paused on an intermediate catch event, an external system can POST to the webhook to resume that specific instance. Useful for callbacks from third-party services, asynchronous job completions, or operator actions delivered over HTTP.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start or resume from one webhook model.** The same webhook data source can start new processes (on a Message Start Event) or resume waiting ones (on a Message Catch Intermediate Event). The trigger type is set automatically based on where the webhook is attached.
> > * **Process Correlation Key.** Each intermediate catch event declares a Process Correlation Key (a business variable like `applicationId`). The webhook-gateway matches this value against the incoming payload to route the resume to the right process instance. The Webhook Correlation Key now accepts array indices in square brackets (`entry[0].changes[0].value.messages[0].text.body`), so the canonical Meta WhatsApp resume path works without flattening upstream.
> > * **Validation at design time.** Process Correlation Key and Process Key are required on intermediate webhook catch events and are validated when the message event is created or updated.
> > * **Backward-compatible upgrade.** Existing webhooks are migrated to `triggerType=START_PROCESS` with no manual intervention. New webhooks attached to an intermediate catch event are flagged `RESUME_PROCESS` automatically.

> [card]
>
> ### **REST endpoints: content-type-aware responses**
>
> REST endpoint responses in Integration Designer are now parsed by content type rather than assumed to be JSON. The endpoint's `Accept` header drives parsing: JSON, plain text, and XML responses are each handled with the right parser, and the original XML string is preserved alongside the parsed map so downstream nodes can read either form. Existing JSON-returning endpoints continue to work without configuration changes.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Accept-driven response parsing.** The endpoint's `Accept` header decides how the response is parsed. JSON variants (`application/json`, `application/hal+json`, `application/problem+json`, any `+json` suffix) are parsed as JSON; `text/*` is returned as a string; XML variants (`application/xml`, `text/xml`, `application/soap+xml`, any `+xml` suffix) are parsed into a JSON-shaped map. When `Accept` is missing, the endpoint falls back to `Content-Type`, then to **AUTO** best-effort.
> >
> > * **XML responses parsed into JSON-shaped objects.** XML response bodies are auto-converted to maps so existing path expressions (`response.body.someField`) work without code changes. The original XML string is preserved on `sourceBody` for callers that need it raw.
> >
> > * **Loud failures on declared mismatches.** When an endpoint declares JSON or XML and the upstream returns a different category, or returns a body that fails to parse, the node fails with a precise error message (for example, `Expected response content type "application/json" but received "text/plain"`). The original body is preserved on `rawBody`.
> >
> > * **Tolerant under AUTO and wildcards.** Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) and inferred categories (no `Accept` declared) fall back to the raw string instead of failing. Flaky or mislabelled upstreams don't break the node.
> >
> > * **XXE-safe XML parser.** XML parsing has DTD processing and external-entity resolution disabled by construction. External-entity attack payloads are neutralized; billion-laughs / entity-expansion attacks cannot fire.
> >
> > * **File downloads bypass Content-Type checks.** File-download endpoints (BINARY or BASE64) deliver the platform's own JSON payload regardless of upstream `Content-Type`, so legacy PDF, octet-stream, and image downloads work unchanged.
> >
> > * **Large XML returned raw.** XML response bodies larger than 5 MiB are returned as the raw string instead of a parsed map, so very large payloads don't block the node.
> >
> > > [!WARNING]
> > >
> > > **Mixed-content XML responses expose a new `value` key.** An XML element with both attributes and inner text (`<leaf attr="v">text</leaf>`) is now parsed to `{attr: "v", value: "text"}`. The inner text used to be silently dropped. Downstream nodes that iterate response keys or assert the exact key set on mixed-content elements may see an additional `value` entry. Path expressions that addressed attributes or child elements directly are unaffected.

> [card]
>
> ### **Raw endpoint payload type**
>
> REST endpoint configuration adds a **Raw** content type alongside JSON, Multipart, and Binary. Raw bodies are sent to the upstream system as-is. Useful for XML, SOAP envelopes, form-urlencoded payloads, or any plain-text body where you need to set the `Content-Type` header yourself.
>
> Before 5.9.0, the only way to send a non-JSON textual body was to use Multipart, which wrapped the payload in `multipart/form-data` and overrode the `Content-Type` header. Raw removes that wrapping.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Body sent as-is.** The body field is sent verbatim. The dispatcher does not transform, wrap, or pretty-print it.
> > * **Caller controls Content-Type.** Set the `Content-Type` header on the endpoint to whatever the upstream expects (`text/xml`, `application/soap+xml`, `application/x-www-form-urlencoded`, `text/plain`). The dispatcher does not override it.
> > * **Monaco plain-text mode.** The endpoint editor switches Monaco to plain text when Raw is selected. XML and SOAP indentation are preserved on paste and edit instead of being reformatted as JSON.
> > * **Shares the JSON body slot.** Raw and JSON payloads use the same storage field on the endpoint definition, so no schema migration is required. Existing endpoints continue to work without changes.

> [card]
>
> ### **Update Process Variables**
>
> JSON editor for variables on active instances with snapshot history; Compare diff.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> >
> > Open the **Update Process Variables** documentation.

> [card]
>
> ### **Stop Run for workflows**
>
> Cancel a running workflow instance from the editor.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-workflows#running-and-stopping-workflows)
> >
> > Open the **Stop Run for workflows** documentation.

> [card]
>
> ### **Notification history + template usages**
>
> `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> >
> > Open the **Notification history + template usages** documentation.

> [card]
>
> ### **Token view improvements**
>
> Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/token)
> >
> > Open the **Token view improvements** documentation.

> [card]
>
> ### **Stop workflow instances in runtime**
>
> Authorized end users can now stop running workflow instances directly from runtime. Previously, stopping a workflow required Designer access or a direct API call. The new control surfaces the action inside the runtime application alongside other workflow-instance management options.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **One-click stop.** Stop a running workflow instance from the runtime instance list.
> > * **Permission-gated.** The stop control is governed by runtime authorization.
> > * **Audited.** Stop actions are recorded on the workflow-instance audit log with the actor and timestamp.

> [card]
>
> ### **Native script engine for JavaScript and Python**
>
> The default script engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a **native subprocess pool**. Scripts run in long-running Node.js and Python worker processes managed by `process-engine` and `integration-designer`. Existing scripts that read from `input` and write to `output` keep working, including `output.put(...)`, `output.get(...)`, and bracket assignment.
>
> The change is opt-out: set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services to keep the previous engine.
>
> Self-HostedAll Deployments
>
> > [accordion] Key Features
> >
> > * **Node.js workers for JavaScript.** JavaScript runs in isolated Node.js worker processes. Each script executes in a fresh V8 context with an explicit globals allowlist and a V8-level execution timeout.
> > * **CPython workers for Python.** Python 3 runs in isolated worker processes with a curated sandbox. Common standard-library modules (`random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64`) are available without `import`. Process, OS, and network modules are blocked.
> > * **Worker pools with recycling.** Worker pools default to 16 Node.js workers and 8 Python workers, sized per service. Workers are recycled after a configurable number of executions to prevent state leakage.
> > * **HashMap method compatibility.** The familiar `output.put(key, value)`, `output.get(key)`, and `output.containsKey(key)` methods continue to work on both JavaScript and Python. The same scripts that ran under GraalVM polyglot context keep working without rewrites.
> > * **GraalVM still available as opt-in.** Set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine, useful if a script depends on GraalVM-specific polyglot features.
> > * **Hardened execution sandbox.** Per-execution fresh scope, environment variables cleared at worker startup, dangerous Python module references scrubbed before user code runs, no `require` / `process` / `global` access in JavaScript.
>
> > [accordion] Configuration
> >
> > The native engine is the default on `process-engine` and `integration-designer`. Tune worker pools and timeouts as needed:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider. `native` or `graalvm`. | `native` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size. | `16` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS execution timeout per script (ms). | `5000` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size. | `8` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python execution timeout per script (ms). | `10000` |
> >
> > See [Process engine setup → Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration) and [Integration Designer setup → Script engine configuration](/5.9/setup-guides/integration-designer-setup#script-engine-configuration) for the full set including payload size and worker recycling.
>
> > [accordion] Migration impact
> >
> > For most existing scripts the change is transparent. The `input`, `output`, `additionalData`, and `instanceMetadata` bindings behave the same, and HashMap-style access on `output` is preserved.
> >
> > Scripts that need attention:
> >
> > * **Python scripts that `import` modules outside the curated allowlist.** Narrow the script to use only the pre-loaded modules, or stay on GraalVM via the opt-out env var.
> > * **JavaScript scripts that reach for `require(...)`, `process`, or `global`.** Those references were never part of the supported surface area but may have worked under GraalVM. Rewrite to use only the bindings provided, or stay on GraalVM via the opt-out env var.
> > * **Scripts that depended on GraalVM-specific polyglot APIs** (calling Java classes from JavaScript / Python). Stay on GraalVM via the opt-out env var.
> >
> > See [Script runtime change for JavaScript and Python business rules](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit checklist.

> [card]
>
> ### **Single-org self-hosted deployment**
>
> Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/organization-deployment)
> >
> > Open the **Single-org self-hosted deployment** documentation.

> [card]
>
> ### **License service**
>
> Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> >
> > Open the **License service** documentation.

> [card]
>
> ### **Authentication: opaque-token → JWT**
>
> Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/authentication-iam)
> >
> > Open the **Authentication: opaque-token → JWT** documentation.

> [card]
>
> ### **New services to deploy**
>
> `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/prerequisites#new-services-to-deploy)
> >
> > Open the **New services to deploy** documentation.

> [card]
>
> ### **Ingress routing and CORS handling**
>
> The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/ingress-routing)
> >
> > Open the **Ingress routing and CORS handling** documentation.

> [card]
>
> ### **Kafka configuration alignment**
>
> Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/kafka)
> >
> > Open the **Kafka configuration alignment** documentation.

> [card]
>
> ### **OpenTelemetry + SpiceDB DR**
>
> OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> All Deployments

> [card]
>
> ### **Durable message-processing**
>
> The process engine now persists parked integration and external-message responses durably, so a response that arrives before its process is ready to consume it survives a runtime restart instead of being lost. This removes a class of stuck process-token failures and improves message-processing robustness at runtime.
>
> All Deployments

> [card]
>
> ### **Task management localization**
>
> 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Open the **Task management localization** documentation.

> [card]
>
> ### **React Native SDK**
>
> FlowX 5.9.0 ships a brand-new **React Native SDK**, bringing the same process renderer model that has powered the React, Angular, iOS, and Android SDKs to React Native apps. Teams building cross-platform mobile or embedded React Native experiences can now host FlowX processes natively, with forms, navigation, and CMS integration handled by the SDK.
>
> A companion demo app is included as a reference integration, covering authentication, the showcase page, and the wiring needed to start a process from inside a container app.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Process renderer.** Render FlowX processes inside any React Native screen with the same component model as the other SDKs.
> > * **Forms and basic components.** Page, Button, Text, Container, Card, and form components ship out of the box.
> > * **CMS integration.** Static content and theming load from the FlowX CMS, including dynamic display values.
> > * **Navigation.** Basic process navigation between screens follows the same patterns as the iOS and Android SDKs.
> > * **Demo app included.** A demo app with authentication and a showcase page is shipped alongside the SDK as a reference integration.

> [card]
>
> ### **iOS UI Flows support**
>
> The iOS renderer reaches feature parity with the React and Angular renderers on UI Flows. iOS apps can now start UI Flows from container apps, manage UI Flow sessions, dismiss modals, handle UI actions, and render document-plugin subtypes (images and document previews).
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start UI Flow from container app.** Container apps can launch a UI Flow with start parameters and handle the response.
> > * **UI Flow session management.** The renderer manages a UI Flow session lifecycle on iOS the same way it does on web.
> > * **onLoad UI Event for Page.** Pages emit an `onLoad` UI Event that iOS handlers can listen to, matching the cross-platform event model.
> > * **Dismiss action and dismiss-on-completion.** A `dismiss` action type cleanly closes modals; `dismiss on completion` on `START_WORKFLOW` actions auto-closes the launching modal when the workflow finishes.
> > * **UI Flow start params.** Pass typed start parameters into a UI Flow at launch.
> > * **Upload File support.** UI Flows on iOS support file upload, including image and document-preview document-plugin subtypes.
> > * **Updated start-process endpoint.** The iOS renderer uses the latest start-process endpoint and `data` property on Start UI Flow, aligned with the web SDKs.
> > * **New native components.** Tooltip, Separator, Progress View, and Markdown components are now rendered natively on iOS, bringing the iOS component set closer to parity with the React and Angular renderers.
> > * **Accessibility properties from UI Designer.** Accessibility properties configured in the UI Designer flow through to the iOS renderer, so screen reader labels and traits are honored on native screens.

> [card]
>
> ### **React 19 upgrade**
>
> The React SDK upgrades to **React 19**, picking up the runtime improvements and APIs that ship with that release. Surrounding `@flowx/*` packages are upgraded in lockstep so the renderer continues to work as a single coherent bundle.
>
> Host apps embedding the React renderer should plan a React 19 upgrade on their side and run the standard React migration checks before adopting 5.9.0.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **React 19 runtime.** Adopts the React 19 reconciler and the APIs that ship with that release.
> > * **Packages upgraded in lockstep.** All `@flowx/*` web SDK packages move to the same baseline so the renderer ships as one coherent bundle.
>
> > [accordion] Host app impact
> >
> > Host apps that embed the React renderer must be on React 19 themselves. Run the React 19 codemods and verify any third-party React libraries you depend on are compatible before upgrading FlowX.

> [card]
>
> ### **Runtime authorization and sharing**
>
> This is the biggest governance change in the 5.1 → 5.9 upgrade. End-user identities, runtime roles, and sharing assignments move out of Keycloak into FlowX-managed records, with project-version-scoped roles and a dedicated Share modal flow on Solutions.
>
> > [card] [Runtime authorization completion](#runtime-authorization-completion)
> >
> > Closes the rewrite: per-environment sharing checklist, project-level end-user roles, data-sync Keycloak provisioning. See the 5.9.0 card above.
>
> > [card] [Anonymous runtime access](#anonymous-runtime-access)
> >
> > Built-in `Anonymous` role + Share modal "Everyone with the link" option for unauthenticated end users. Session-bound (`X-Fx-Anonymous-Session-Id`), fire-and-forget; per-component hide/disable rules; SDK auth-skip mode.
>
> > [card] [Runtime authorization overhaul](#runtime-authorization-overhaul)
> >
> > Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> > [card] [UI Flow permissions](#ui-flow-permissions)
> >
> > Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> > [card] [End-user access management](#end-user-access-management)
> >
> > Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> > [card] [Operations-editor role](#operations-editor-role)
> >
> > New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> > [card] [Cross-workspace projects](#cross-workspace-projects)
> >
> > Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.

> [card]
>
> ### **Conversational AI**
>
> 5.9 takes FlowX from no chat to production conversational AI: the Chat component, conversational workflows with memory and intent classification, voice and speech-to-text, chat-based UI Flows, and runtime controls.
>
> > [card] [Chat component](#chat-component)
> >
> > Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> > [card] [Conversational Workflows](#conversational-workflows)
> >
> > Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> > [card] [Voice input + Speech-to-Text](#voice-input-+-speech-to-text)
> >
> > Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> > [card] [Memory capabilities](#memory-capabilities)
> >
> > Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> > [card] [Intent Classification node](#intent-classification-node)
> >
> > Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> > [card] [Chat-based UI Flows](#chat-based-ui-flows)
> >
> > UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> > [card] [AI Triggers](#ai-triggers)
> >
> > Named parameterized message templates to launch conversational workflows with context.
>
> > [card] [Stop agent response](#stop-agent-response)
> >
> > Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.

> [card]
>
> ### **AI Agents and Knowledge**
>
> The agent-builder story: Custom Agents, MCP integration, Knowledge Bases for RAG, document and web extraction, AI Providers self-service, and PII Guard.
>
> > [card] [Evaluations (Evals)](#evaluations)
> >
> > Score AI node outputs against test cases with 10 built-in evaluators (LLM-as-judge: correctness, conciseness, hallucination, answer-relevance; RAG: groundedness, helpfulness, retrieval-relevance; code: exact-match, Levenshtein, JSON-match). Datasets attached to AI nodes, async judge pipeline via the new `evals-judge` service + 3 Kafka topics, per-org judge model via the new `EVAL` capability (default `gpt-5.4-mini`).
>
> > [card] [Custom Agent nodes](#custom-agent-nodes)
> >
> > AI agents that use MCP tools to act autonomously inside workflows.
>
> > [card] [MCP integration](#mcp-integration)
> >
> > MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> > [card] [Knowledge Bases](#knowledge-bases)
> >
> > Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> > [card] [AI Providers self-service](#ai-providers-self-service)
> >
> > Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> > [card] [PII Guard](#pii-guard-per-entity-detections-on-documents-and-images)
> >
> > Per-AI-node guardrail with Strict / Balanced / Relaxed presets, input/output scans, file redaction. 5.9.0 adds per-entity detections on documents and images. See the 5.9.0 card above.
>
> > [card] [Extract Data from File](#extract-data-from-file)
> >
> > LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> > [card] [Web Page Extractor / Web Crawler](#web-page-extractor-/-web-crawler)
> >
> > Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> > [card] [Context Retrieval](#context-retrieval)
> >
> > RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> > [card] [AI Developer generates Custom Components](#ai-developer-generates-custom-components)
> >
> > Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.

> [card]
>
> ### **UI Flows and Custom Components**
>
> Build user-facing apps without a process. UI Flows reach feature parity with processes; Custom Components let teams ship React code inside the Designer.
>
> > [card] [UI Flows](#ui-flows)
> >
> > Reusable multi-platform UI (web / iOS / Android) as project resources. Navigation Areas, Start Process / Navigate UI actions, Task Manager component. Breadcrumbs + Sessions monitoring. Process Renderer + Start Workflow action + On Load event. Route management + Start Parameters + Session Variables + onClick / On Display events. UI Flow permissions.
>
> > [card] [Custom Components](#custom-components)
> >
> > Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> > [card] [Process Renderer in UI Flows](#process-renderer-in-ui-flows)
> >
> > Embed process renderers inside UI Flows.
>
> > [card] [UI Flow sessions monitoring](#ui-flow-sessions-monitoring)
> >
> > Runtime view with session list, audit log, process tracking, workflow debugging.
>
> > [card] [Accessibility (WCAG 2.1 AA)](#accessibility-wcag-2-1-aa)
> >
> > Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> > [card] [New theme components](#new-theme-components)
> >
> > Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> > [card] [Multi-file bulk upload](#multi-file-bulk-upload)
> >
> > Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> > [card] [Card default collapse + Tables in Collections](#card-default-collapse-+-tables-in-collections)
> >
> > Cards configurable to load collapsed; Table UI components inside Collection prototypes.

> [card]
>
> ### **Integration and Data Platform**
>
> For builders connecting FlowX to enterprise systems, 5.9 adds new data sources, new triggers, parallel workflow execution, REST resilience, and visual query authoring.
>
> > [card] [Email Trigger](#email-trigger)
> >
> > New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> > [card] [Microsoft Outlook data source](#microsoft-outlook-data-source)
> >
> > Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> > [card] [Incoming Webhooks](#incoming-webhooks)
> >
> > New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> > [card] [Oracle Database integration](#oracle-database-integration)
> >
> > Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL.
>
> > [card] [Unmanaged MongoDB data source](#unmanaged-mongodb-data-source)
> >
> > Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> > [card] [Send Notification action + Email Sender](#send-notification-action-+-email-sender)
> >
> > SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> > [card] [Advanced Query Builder](#advanced-query-builder)
> >
> > Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> > [card] [Parallel branches in workflows](#parallel-branches-in-workflows)
> >
> > Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> > [card] [REST endpoint caching + workflow partitioning](#rest-endpoint-caching-+-workflow-partitioning)
> >
> > TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> > [card] [Data mappers + workflow data models](#data-mappers-+-workflow-data-models)
> >
> > Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> > [card] [Proxy Server Connections](#proxy-server-connections)
> >
> > Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> > [card] [Faster authoring loop](#faster-authoring-loop)
> >
> > 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.

> [card]
>
> ### **Process operations**
>
> Day-2 operations for runtime teams: edit live process state, inspect tokens with more context, audit notifications, and operate on workflow instances.
>
> > [card] [Update Process Variables](#update-process-variables)
> >
> > JSON editor for variables on active instances with snapshot history; Compare diff.
>
> > [card] [Stop Run for workflows](#stop-run-for-workflows)
> >
> > Cancel a running workflow instance from the editor.
>
> > [card] [Notification history + template usages](#notification-history-+-template-usages)
> >
> > `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> > [card] [Token view improvements](#token-view-improvements)
> >
> > Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> 5.9.0 adds **Stop workflow instances in runtime** and **Documents in process instances**. See the 5.9.0 cards above.

> [card]
>
> ### **Platform, deployment and infrastructure**
>
> Read this first if you operate a self-hosted deployment. 5.9 adds new microservices, a new deployment mode, and the auth architecture transition.
>
> > [card] [Single-org self-hosted deployment](#single-org-self-hosted-deployment)
> >
> > Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> > [card] [License service](#license-service)
> >
> > Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> > [card] [Authentication: opaque-token → JWT](#authentication-opaque-token-→-jwt)
> >
> > Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> > [card] [New services to deploy](#new-services-to-deploy)
> >
> > `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> > [card] [Native script engine for JavaScript and Python](#native-script-engine-for-javascript-and-python)
> >
> > JavaScript and Python business rules and workflow scripts run on a Node.js + CPython subprocess pool by default. HashMap-style access on `output` is preserved; GraalVM remains available via `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`. See the 5.9.0 card above and the migration audit checklist.
>
> > [card] [Ingress routing and CORS handling](#ingress-routing-and-cors-handling)
> >
> > The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> > [card] [Kafka configuration alignment](#kafka-configuration-alignment)
> >
> > Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> > [card] [OpenTelemetry + SpiceDB DR](#opentelemetry-+-spicedb-dr)
> >
> > OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> > [card] [Task management localization](#task-management-localization)
> >
> > 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.

***

## Deployment notes

> [card] [Deployment guidelines v5.9.0](./deployment-guidelines-v5.9)
>
> Component versions, environment variables, Kafka topics, and self-hosted upgrade guidance.

> [card] [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview)
>
> Consolidated 5.1 LTS → 5.9 LTS migration guide. Direct upgrade to 5.9.0.


# Deployment guidelines v5.9.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1

Component versions, configuration, and deployment notes for FlowX.AI 5.9.1 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.1 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.0 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.0 → 5.9.1**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

## Component versions

### Core components

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **process-engine** | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.3 |
| **admin** | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.3 |
| **designer** | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.4 |
| **cms-core** | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.2 |
| **scheduler-core** | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.2 |
| **events-gateway** | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.2 |
| **notification-plugin** | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.2 |
| **document-plugin** | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.2 |
| **task-management-plugin** | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.2 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |
| **data-search** | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.2 |
| **audit-core** | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.2 |
| **advancing-controller** | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.2 |
| **integration-designer** | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.3 |
| **application-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **runtime-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **data-sync** | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.2 |
| **authorization-system** | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.2 |
| **nosql-db-runner** | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.2 |
| **email-gateway** | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-native-sdk** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/core-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **react-saas** | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.20 |
| **Android renderer** | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.24 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-knowledgebase-rag** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-embedder** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-agent-builder** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-gateway** | 10.17.0 | 10.7.0 | - | - |
| **ai-platform-ai-analyst** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-assistant** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-ai-designer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-developer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-planner** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-kb-enrichment** | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.1 adds two Kafka topics. Both are **auto-provisioned by the Helm chart** — no manual creation is required for standard deployments. The names and env vars are listed here for environments that provision topics or ACLs manually.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | application-manager | process-engine | Runtime config-param change events; invalidates the build cache |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine | integration-designer | Notifies that a runtime instance has been terminated |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin | process-engine | Resource cache eviction triggered when a process version changes |
| `ai.flowx.evals.suggestions.job.request.v1` | integration-designer | AI Platform | Evaluation improvement-suggestion job requests |
| `ai.flowx.evals.suggestions.job.response.v1` | AI Platform | integration-designer | Evaluation improvement-suggestion job responses |

Topic env vars and consumer groups:

| Topic | Producer var (OUT) | Consumer var (IN) | Consumer group |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | `config-params` |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_OUT` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_IN` | `integration-designer-runtime-instance-terminated-group` |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT_IN` | `resource-cache-evict` |
| `ai.flowx.evals.suggestions.job.request.v1` | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT` | — (consumed by AI Platform) | — |
| `ai.flowx.evals.suggestions.job.response.v1` | — (produced by AI Platform) | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN` | `integration-designer-evals-suggestions-response-group` |

For the config-param cache-invalidation behavior, see [Engine setup → Topics related to runtime config params](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-runtime-config-params). For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.1 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including split AI permissions, the legacy script flag, and File Storage and document-preview fixes.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.0 → 5.9.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.1** is a maintenance release for the 5.9.x LTS with bug fixes, security patches, and a few targeted improvements:
>
> * **Import/export:** stability and cross-version compatibility fixes
> * **Split AI permissions:** separate governance for AI runtime usage and AI build-time tooling
> * **Legacy script flag:** per-rule Native / GraalVM script runtime selection
> * **File Storage and document-preview improvements**
> * Wide set of Designer, Renderer, and platform bug fixes
> * No breaking changes; fully compatible upgrade from 5.9.0

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Split AI permissions**](#split-ai-permissions) - Independent governance for AI usage and AI build tooling.\
> 📝 [**Legacy script flag**](#legacy-script-flag) - Per-rule Native / GraalVM script runtime selection.\
> 🗂️ [**File Storage improvements**](#file-storage-improvements) - FTP connection and preview fixes.\
> 📄 [**File Preview scroll events**](#file-preview-scroll-events) - Scroll-trigger event handlers for the File Preview component.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, Workflows, and backend bug fixes plus security patches.
>
> ***
>
> ### **Split AI permissions**
>
> > [card] Separate governance for AI usage and AI build tooling
> >
> > > [tab] Overview
> > >
> > > AI permissions are now split into two independent controls, so administrators can govern **AI runtime usage** separately from **AI build-time tooling** (AI Designer, agent building, code generation).
> >
> > > [tab] Behavior
> > >
> > > * When AI is turned off, AI-related icons and entry points are hidden rather than shown in a disabled state.
> > > * AI nodes in workflows behave consistently with the gateway's availability.
> > > * Build-time AI helpers (code generation, "Add comment") follow the dev-agent permission rather than the runtime AI permission.
> >
> > All Deployments
>
> ***
>
> ### **Legacy script flag**
>
> > [card] Per-rule Native / GraalVM script runtime
> >
> > Business rules, reusable functions, and node rules can now choose their script engine individually: the current **native** engine (the 5.9 default) or the legacy **GraalVM** engine. Rules created before the switch to native keep running on GraalVM until you migrate them, while new rules default to native, so teams can move scripts across at their own pace. The per-rule selector only appears for rules that support GraalVM; new rules run on native.
> > All Deployments
>
> ***
>
> ### **File Storage improvements**
>
> > [card] FTP connection and preview fixes
> >
> > * FTP **test connection** now resolves configuration-parameter placeholders before connecting.
> > * **File operations** also resolve configuration-parameter placeholders at runtime.
> > * FTP **file preview** works when the root path has no leading slash.
> >   All Deployments
>
> ***
>
> ### **File Preview scroll events**
>
> > [card] Scroll-trigger event handlers for File Preview
> >
> > The **File Preview** component now supports **scroll-trigger event handlers** (including a "document end" trigger), configurable in the Designer and handled by the web, iOS, and Android renderers. They let a flow detect when a user scrolls through a document or reaches its end.
> >
> > This is built for consent and disclosure use cases such as banking flows that must prove, per local regulation, that the user actually read an agreement. You can keep an action such as a **Submit** or **Accept** button hidden or disabled until the document-end event handler fires; that handler can be a simple local script that sets a flag to enable the button.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Forms to validate:** fixed scrolling through the full component hierarchy, placeholder updates, and incorrect selection of chat and tab-bar components.
> > > > * **Process instances:** fixed a browser crash when loading instances with very large execution graphs.
> > > > * **Theme admin:** fixed theme content being lost when using "copy to".
> > > > * **UI Flow:** fixed images not displaying in preview after refresh, and a missing theme UUID when returning from an expired UI Flow.
> > > > * **Actions:** stopped GET actions firing with undefined parameters.
> > > > * **Modals:** fixed dropdown flicker and layout issues with long key names.
> > >
> > > > [accordion] Renderer fixes (Web / React / React Native)
> > > >
> > > > * **Web:** fixed missing button shadow, modal content padding, and rendering when a media-file storage path is null.
> > > > * **File Preview:** fixed preview not rendering correctly, events not firing inside collections, fixed height not applied at runtime, and CORS errors when accessing preview resources.
> > > > * **React Native:** fixed date-picker shifting to a previous day and input/textarea retaining focus after moving to another component.
> > > > * **Task management:** fixed header theming (React/Angular) and the filter window disappearing after applying criteria.
> > > > * **File upload:** the upload button now supports a configurable icon, set in the Designer and rendered on web, iOS, and Android.
> >
> > > [tab] Workflows & AI
> > >
> > > > [accordion] Workflow fixes
> > > >
> > > > * Fixed END PARALLEL output including data from before the parallel branches started.
> > > > * Optimized storage of running steps for workflows.
> > > > * Fixed a crash in NoSQL node run logs when a node failed before building its options.
> > > > * Workflows and processes launched from a UI Flow now inherit the build from the parent UI Flow.
> > > > * AI node failures now surface the error details and model reasoning in the workflow run logs, making failed AI steps easier to diagnose.
> > >
> > > > [accordion] AI improvements & fixes
> > > >
> > > > * **AI Designer** generates more reliable UI from a flat template format (replacing the previous 3-level nesting), supports additional component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates by applying changes incrementally instead of regenerating from scratch, and can now generate **reusable UI templates**.
> > > > * Fixed agent responses reappearing in chat after stop and refresh.
> > > > * Fixed duplicated messages in the builder-agent chat.
> > > > * **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
> > > > * **Platform Status** now reports AI Platform components and their databases alongside the core services.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * Fixed a null value being wrongly cached when looking up the "All end-users" group, which could block logins until data-sync completed.
> > > > * Fixed copying a process or workflow to another project: the copy now succeeds, and copied workflows appear in the target project.
> > > > * Fixed an invited Designer user added as an Organization owner not being assigned to a workspace.
> > > > * Improved merge-conflict handling for custom components and UI Flows, with clearer resource identification.
> > > > * Hide/disable conditions on UI templates, processes, and UI Flows are now applied at runtime for Designer users without workspace access.
> > > > * Fixed a 500 (duplicate key) error when activating a start timer event after a new build regenerated the process resource ID.
> > > > * Fixed a 500 error when opening a Usage Overview.
> > > > * Organization settings navigation and design improvements.
> > > > * **Runtime config params:** changes to runtime configuration parameters now propagate to the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
> > > > * **Microsoft Outlook connections** now support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.1 is fully compatible with 5.9.0. No breaking changes; standard deployment procedures apply.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.0 → 5.9.1 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.1 are tracked in the [5.9.1 deployment guidelines](./deployment-guidelines-v5.9.1).&#x20;
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2

Component versions, configuration, and deployment notes for FlowX.AI 5.9.2 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.2 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.1 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.1 → 5.9.2**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and converts your data. If you did not apply that workaround, no action is needed.

> [!WARNING]
>
> **Manually marked Liquibase changesets.** If any Liquibase changesets were manually marked as executed (MARK\_RAN) to work around failures during earlier 5.9.x upgrade attempts, those records must be removed after upgrading to 5.9.2 so the corrected changesets can run. Contact FlowX support for the exact list of affected changesets before removing anything. If you did not mark any changesets manually, no action is needed.

## Component versions

### Core components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.162.1 | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.7 |
| **admin** | 10.141.1 | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.7 |
| **designer** | 10.260.7 | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.10 |
| **cms-core** | 10.102.3 | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.3 |
| **scheduler-core** | 10.85.1 | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.3 |
| **events-gateway** | 10.90.1 | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.4 |
| **notification-plugin** | 10.100.2 | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.3 |
| **document-plugin** | 10.113.2 | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.3 |
| **task-management-plugin** | 10.102.1 | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.3 |
| **reporting-plugin**\* | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.7 |
| **data-search** | 10.83.1 | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.3 |
| **audit-core** | 10.93.1 | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.3 |
| **advancing-controller** | 10.89.1 | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.3 |
| **integration-designer** | 10.189.2 | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.4 |
| **application-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **runtime-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **data-sync** | 10.98.0 | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.4 |
| **authorization-system** | 10.112.1 | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.5 |
| **nosql-db-runner** | 10.92.1 | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.3 |
| **email-gateway** | 10.91.1 | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.88.1 | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.60.1 | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.23.1 | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.78.1 | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-native-sdk** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/core-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **react-saas** | 10.260.7 | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.6 | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.25 |
| **Android renderer** | 10.5.6 | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.31 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.0 | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.0 | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.0 | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.0 | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.0 | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.0 | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.25.0 | 10.17.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.0 | - | - | - | - |
| **ai-assistant** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.0 | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.2 | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.2 introduces no new Kafka topics over 5.9.1. For the topics added in 5.9.1, see the [5.9.1 deployment guidelines](../v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics); for the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.2 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

* **Kafka reconnect backoff:** platform services now default to a gentler broker-reconnect backoff — `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MS` `1000` / `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MAX_MS` `10000` (and the consumer equivalents) — and repetitive Kafka NetworkClient connection errors log at a quieter level, tunable via `LOGGING_LEVEL_KAFKA_NETWORK_CLIENT` (default `ERROR`). No action needed unless you previously tuned these.&#x20;
* **Resource-server security type:** the default for `idp.resourceServer.securityType` on the AI services changes to `jwt`. If you previously set the security type to `jwt` explicitly as a workaround, that override is no longer needed and can be removed.&#x20;

#### Data partitioning and archiving

5.9.2 adds configuration for the archiving lifecycle on the process-engine and Integration Designer. All new settings default to off, so no action is required on upgrade.&#x20;

* **Stuck-instance termination:** an optional sweep (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`, default `false`) terminates instances that would otherwise block archiving. Enable it, plus its cron and batch-size, if archiving stalls on unfinished data.
* **Legacy backfill:** one-shot backfills of `partition_id` (`FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED`) and `organization_id` (`FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED`), both default `false`, populate legacy rows when you first turn partitioning on. The organization-ID backfill is optional on self-hosted and can remain `false`.

> [!WARNING]
>
> **Partitions that still contain unfinished instances are not archived.** Starting with 5.9.2, the archiving job detaches a partition only when every process instance in it has reached a finished state (`FINISHED`, `FINISHED_WITH_ERROR`, `FAILED`, `EXPIRED`, `ABORTED`, `DISMISSED`, or `TERMINATED`). A single instance still in `CREATED`, `STARTED`, or `ON_HOLD` blocks the entire partition; it is retried on the next archiving run. The same rule applies to workflow instances on the Integration Designer, where a `STARTED` workflow instance blocks its partition. If partitions accumulate unarchived, terminate the blocking instances — set process expiry, or turn on the stuck-instance termination sweep above.

For the full property tables and defaults, see [Partitioning & archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) (process-engine) and [Integration Designer setup → Workflow partitioning](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration).

#### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them as part of this upgrade. The bundled Qdrant subchart is renamed the same way, so any explicit references to its service host must be updated too.

> [!WARNING]
>
> Core platform services resolve AI Platform components by these new names. Upgrade the AI Platform chart and the core platform services to 5.9.2 together — running a 5.9.1 AI Platform chart against 5.9.2 core services (or the reverse) breaks AI features.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including expanded audit logging, copy-with-roles, and the app-manager organization-ID migration fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.1 → 5.9.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.2** is a maintenance release for the 5.9.x LTS. It pairs a broad bug-fix pass with a few targeted improvements:
>
> * **Expanded audit logging:** coverage for sharing, invitations, user and group management, and process-instance and UI-flow actions
> * **Copy with roles:** copying a resource now also copies its associated roles
> * **Self-hosted upgrade fixes:** smoother installation and upgrade from 5.1.x on self-hosted environments
> * **Key fixes:** active-policy override user list, project-version merge, reusable UI templates in nested containers, and audit-log user filtering&#x20;
> * Wide set of Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.9.2 brings bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions.\
> 👥 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, and backend bug fixes plus security patches.
>
> ***
>
> ### **Expanded audit logging**
>
> > [card] Broader audit coverage for access and lifecycle actions
> >
> > Audit logging now records a wider set of actions, including **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> > All Deployments
>
> ***
>
> ### **Copy with roles**
>
> > [card] Roles travel with copied resources
> >
> > Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Reusable UI templates:** fixed actions missing at runtime when a template is nested in multiple levels of containers.&#x20;
> > > > * **Use in reporting:** the reporting toggle is now available on UI flows and workflows, matching the existing process setting.
> > > > * **UI action keys:** keys to save for collection items and bundled custom-component inputs are now computed automatically, and mapped object keys for collections and custom components are available in runtime data.&#x20;
> > > > * **SQL data sources:** queries on SQL data sources can now be tested from the builds list, mirroring the existing NoSQL runtime test flow.&#x20;
> > > > * **Event handlers:** the Event Handlers section now appears higher in the component configuration panel.&#x20;
> > > > * **Audit logs:** filtering audit entries by user now works when the username differs from the email address.&#x20;
> > > > * **AI agents and data models:** AI Designer and AI Developer now use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it. &#x20;
> > >
> > > > [accordion] Renderer fixes
> > > >
> > > > * **Chat:** the floating chat position is now calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.&#x20;
> > > >
> > > > This release also includes stability fixes across the web, React, React Native, Android, and iOS renderers.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * **Active policy:** fixed the user list appearing empty on the override active-policy form.&#x20;
> > > > * **Project version merge:** fixed a 500 error that could occur during project-version merge.&#x20;
> > > > * **CMS enumerations:** cascading-enum value lookups now resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.&#x20;
> > > > * **Build export with media files:** exporting a build with media file content included now produces an archive that actually contains the binaries.&#x20;
> > > > * **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.&#x20;
> > > > * **Redis Cluster:** UI-template cache keys are now hash-tagged so related keys map to the same cluster slot, preventing cross-slot errors on Redis Cluster deployments.&#x20;
> > > > * **Workflow data:** Mongo partition archiving now batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine was fixed. See [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) for the partitioning and archiving settings.&#x20;
> > > > * **Data sync with private CA certificates:** the data-sync job now runs the same certificate-initialization step as the other platform services, so data-sync migrations that call HTTPS endpoints (such as Keycloak) no longer fail certificate validation in environments using an internal certificate authority.&#x20;
> > > > * **Self-hosted installation and upgrade:** fixed Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding on self-hosted environments. As part of this, the migration-created default end-user group is renamed from `User` to `Users Group`; check the upgrade warning under Additional information if you map IDP groups into FlowX.&#x20;
> > > > * **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.&#x20;
> > > > * **AI workflow nodes:** JSON schema fields now support `${}` placeholders.&#x20;
> > > > * **Multi-KB retrieval:** retrieval can span multiple knowledge bases in a workflow.&#x20;
> > > > * **AI structured output:** responses from AI nodes with a response schema are now validated against it, with automatic repair retries, and node logs include richer run diagnostics such as the failure reason and rejected output.&#x20;
> > > > * **Document Parser:** a new LiteParse engine parses PDFs and images fully locally without GPU or AI calls, and OCR language support expands to English, Romanian, Hungarian, and Bulgarian.&#x20;
> > > > * **Knowledge bases:** a Custom Agent node can now select multiple knowledge bases, each exposed to the agent as its own retrieval tool, replacing the parallel-nodes workaround.&#x20;
> > > > * **Chat file uploads:** end users can attach multiple files in a chat-driven app; uploads are indexed into a knowledge base scoped to the chat session so AI nodes answer grounded in that content.&#x20;
> > > > * **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.&#x20;
> > > >
> > > > This release also includes a broad set of additional fixes and stability improvements across Designer and backend services.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.2 is fully compatible with 5.9.1; standard deployment procedures apply. One migration renames a default end-user group, which needs attention only if group membership is mapped from Keycloak or an external IDP (see the warning below).
>
> > [!WARNING]
> >
> > **Default end-user group renamed from `User` to `Users Group`.** The group that the 5.1.x upgrade migration creates for users who held the `FLOWX_ROLE` realm role is renamed from `User` to `Users Group` when you upgrade to 5.9.2 or any later release. Runtime group matching is by exact name: if a Keycloak **Group Membership** mapper or an external IDP claim emits the old name `User` into `attributes.runtimeGroups`, those values no longer match any FlowX group and affected users **lose solution access on their next sign-in, with no error logged**. Update the mapper or source group name to `Users Group` as part of the upgrade. Groups your admins created themselves, including any you named `User`, are not renamed. See the [runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) setup for where this value is configured.
>
> > [!WARNING]
> >
> > **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration so it converts existing data correctly. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and actually converts your data. If you did not apply that workaround, no action is needed.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.1 → 5.9.2 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.2 are tracked in the [5.9.2 deployment guidelines](./deployment-guidelines-v5.9.2).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3

Component versions, configuration, and deployment notes for FlowX.AI 5.9.3 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.3 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.2 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.2 → 5.9.3**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.0 or 5.9.1 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.165.0 | 10.162.1 | 10.135.0 | 10.106.0 | 9.76.3 |
| **admin** | 10.144.0 | 10.141.1 | 10.116.0 | 10.93.0 | 9.76.3 |
| **designer** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **cms-core** | 10.105.0 | 10.102.3 | 10.86.0 | 10.67.0 | 9.47.3 |
| **scheduler-core** | 10.87.0 | 10.85.1 | 10.70.0 | 10.53.0 | 9.36.3 |
| **events-gateway** | 10.93.0 | 10.90.1 | 10.72.0 | 10.55.0 | 9.37.3 |
| **notification-plugin** | 10.103.0 | 10.100.2 | 10.83.0 | 10.64.0 | 9.40.3 |
| **document-plugin** | 10.116.0 | 10.113.2 | 10.94.0 | 10.75.0 | 9.45.3 |
| **task-management-plugin** | 10.105.0 | 10.102.1 | 10.84.0 | 10.66.0 | 9.44.4 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.85.0 | 10.83.1 | 10.69.0 | 10.52.0 | 9.33.3 |
| **audit-core** | 10.95.0 | 10.93.1 | 10.79.0 | 10.63.0 | 9.41.3 |
| **advancing-controller** | 10.91.0 | 10.89.1 | 10.73.0 | 10.55.0 | 9.36.3 |
| **integration-designer** | 10.192.0 | 10.189.2 | 10.162.0 | 10.128.0 | 9.60.3 |
| **application-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **runtime-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **data-sync** | 10.100.0 | 10.98.0 | 10.81.0 | 10.58.0 | 9.34.2 |
| **authorization-system** | 10.115.0 | 10.112.1 | 10.96.1 | 10.77.0 | 9.44.4 |
| **nosql-db-runner** | 10.94.0 | 10.92.1 | 10.75.0 | 10.56.0 | 9.32.3 |
| **email-gateway** | 10.93.0 | 10.91.1 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.90.0 | 10.88.1 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.62.0 | 10.60.1 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.25.0 | 10.23.1 | 10.8.0 | - | - |
| **license** | 10.80.0 | 10.78.1 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-native-sdk** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/core-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **react-saas** | 10.265.6 | 10.260.7 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.11 | 10.5.6 | 10.4.1 | 10.3.0 | 9.0.27 |
| **Android renderer** | 10.6.6 | 10.5.6 | 10.5.0 | 10.3.0 | 9.0.37 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](../v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.1 | 10.9.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.1 | 10.9.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.1 | 10.9.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.1 | 10.9.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.1 | 10.9.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.1 | 10.9.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.27.0 | 10.25.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.1 | 10.9.0 | - | - | - |
| **ai-assistant** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.1 | 10.9.0 | - | - | - |
| **flowx-docs** | 5.9.3 | 5.9.2 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.3 introduces no new Kafka topics over 5.9.2. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.3 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Events Gateway — Redis connection pool for blocking mode

The Events Gateway's blocking read path is rebuilt on a dedicated Redis connection pool, fixing a connection leak that could previously require periodic Events Gateway restarts under sustained load. The new settings ship with working defaults — no action is required on upgrade.

| Environment variable | Default | Change in 5.9.3 |
| - | - | - |
| `EVENTS_REDIS_POOL_ENABLED` | `true` | New — dedicated connection pool for blocking reads |
| `EVENTS_REDIS_POOL_MAXTOTAL` | `50` | New — maximum pooled connections |
| `EVENTS_REDIS_POOL_MAXIDLE` | `50` | New — maximum idle pooled connections |
| `EVENTS_REDIS_POOL_MINIDLE` | `5` | New — minimum idle pooled connections |
| `EVENTS_REDIS_POOL_MAXWAITMILLIS` | `5000` | New — wait time for a pooled connection before failing |
| `EVENTS_REDIS_SSE_BUFFERSIZE` | `256` | New — per-subscriber SSE backpressure buffer |
| `EVENTS_REDIS_BLOCKDURATIONSECONDS` | `1` | Default lowered from `5` — shortens the blocking-read reissue interval |

If you previously set `EVENTS_REDIS_BLOCKDURATIONSECONDS` explicitly, review whether the new default suits your setup. See the [Events Gateway setup guide](/5.9/setup-guides/events-gateway-setup#events) for the full configuration reference.

#### Integration Designer — workflow topic partitions

`FLOWX_WORKFLOW_TOPICPARTITIONS` (default `1`) sets the number of partitions for auto-created workflow Kafka topics (used with `FLOWX_WORKFLOW_CREATETOPICS`). Existing topics are not modified; the setting applies to newly created topics only.&#x20;

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including the Events Gateway Redis connection-leak fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.2 → 5.9.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.3** is a maintenance release for the 5.9.x LTS:
>
> * **Real-time event delivery:** fixes a Redis connection leak in the Events Gateway that could previously require periodic restarts under sustained load
> * **Key fixes:** build import race during multi-dependency imports, task-management allocation rules, project re-creation error handling
> * **New configuration:** Events Gateway connection-pool tuning and workflow Kafka topic partitions
> * Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.2

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform improvements**](#platform-improvements) - Events Gateway stability, Designer and backend bug fixes, security patches.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Real-time event delivery:** fixed a Redis connection leak in the Events Gateway. Blocking reads now run on a dedicated connection pool with Redis Cluster support, eliminating the gradual connection buildup that could previously require periodic Events Gateway restarts. New tuning options are available — see the [deployment guidelines](./deployment-guidelines-v5.9.3#configuration-changes).
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it, and duplicate rules are no longer created when Save is clicked twice. Task views also no longer reset when the same view is open from different workspaces.&#x20;
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **Designer stability:** fixed a freeze when opening Runtime after expanding a component's Permissions section, and a pending AI UI-generation draft no longer locks the process diagram read-only.&#x20;
> > > > * **Date Picker:** the calendar now anchors correctly to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.&#x20;
> > > > * **Workflows:** fixed a silent workflow freeze that could occur after a step exhausted its retries.&#x20;
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior. UI Flows on iOS also gain support for the `additionalData` object.
> > > >   &#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Media Library:** PDF assets in the list can now be opened in a new tab directly from the Media Library.
> > > > * **Process start loading:** web renderers now keep the loading indicator visible until the first user task renders, matching the mobile SDK behavior.&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.3 is fully compatible with 5.9.2. No configuration changes are required on upgrade; new tuning options ship with working defaults.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.2 → 5.9.3 with no breaking changes
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps are required for this maintenance release. Upgrading directly from 5.9.0 or 5.9.1? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.3](./deployment-guidelines-v5.9.3).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4

Component versions, configuration, and deployment notes for FlowX.AI 5.9.4 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.4 is a maintenance release for the 5.9.x LTS line. The platform upgrade from 5.9.3 is non-breaking, but this release changes how the Helm charts express the container image location, so review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.3 → 5.9.4**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Helm values change.** The charts now express the image location as `image.registry` plus `image.repository` instead of one combined path. Deployments that set `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move it out before upgrading — see [Helm charts: image registry split](#helm-charts-image-registry-split).

> [!NOTE]
>
> **Upgrading from 5.9.0, 5.9.1, or 5.9.2 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.171.3 | 10.165.0 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.149.3 | 10.144.0 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.110.4 | 10.105.0 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.91.2 | 10.87.0 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.97.2 | 10.93.0 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.107.4 | 10.103.0 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.121.3 | 10.116.0 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.109.3 | 10.105.0 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.89.2 | 10.85.0 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.99.2 | 10.95.0 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.95.2 | 10.91.0 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.197.5 | 10.192.0 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.104.3 | 10.100.0 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.119.3 | 10.115.0 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.98.2 | 10.94.0 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.98.2 | 10.93.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.95.2 | 10.90.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.66.2 | 10.62.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.30.2 | 10.25.0 | 10.8.0 | - | - |
| **license** | 10.84.2 | 10.80.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.275.0 | 10.265.6 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.0 | 10.5.11 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.8.0 | 10.6.6 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.2 | 10.9.1 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.10.2 | 10.9.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.10.2 | 10.9.1 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.10.2 | 10.9.1 | 10.1.1 | - | - |
| **speech-to-text** | 10.10.2 | 10.9.1 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.10.2 | 10.9.1 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.32.2 | 10.27.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.10.2 | 10.9.1 | - | - | - |
| **ai-assistant** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.10.2 | 10.9.1 | - | - | - |
| **flowx-docs** | 5.9.4 | 5.9.3 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.4 introduces no new Kafka topics over 5.9.3. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Apply the Helm values change described in [Configuration changes](#configuration-changes), if it affects your setup.
2. Update container images to the 5.9.4 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Helm charts: image registry split

Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.

```yaml theme={"dark"}
# Before
image:
  repository: <registry>/<image-name>

# After
image:
  registry: <registry>
  repository: <image-name>
```

The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.

**Upgrade notes**

* **If you set `global.imageRegistry` to point the charts at your own registry** (the standard, documented approach): no action is required. Your override continues to work, and it now applies cleanly to the default bare repository names.
* **If you embedded the registry inside `image.repository`** (for example `image.repository: harbor.mycorp.internal/flowx/<image-name>`): move the registry portion out. Set it through `global.imageRegistry`, or the chart's `image.registry`, and let `image.repository` fall back to its default bare image name. Leaving the registry in `image.repository` alongside the now-populated `image.registry` prepends the registry twice.

  This applies to deployments configured from the FlowX setup guides before 5.9.4, which showed the combined form. If your values files were built from those examples, check them before upgrading.

#### Events Gateway service account

Events Gateway now authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`, in the service-accounts realm. It needs this identity to resolve and authorize a subscription before admitting the stream.

Two new configuration values are involved, and both take the **same secret**:

| Service | Environment Variable | Purpose |
| - | - | - |
| authorization-system | `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXEVENTSGATEWAYSA` | Secret the migration assigns to the client it creates |
| events-gateway | `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Secret Events Gateway authenticates with |

**Upgrade notes**

* **If you deploy with the FlowX Helm charts and authorization-system runs its migrations with Keycloak admin access**: no action is required. The chart already maps both values to the `KEYCLOAK_EVENTS_GATEWAY_CLIENT_SECRET` key of the `keycloak-flowx-realm-clients` secret, and the authorization-system migration creates the client and grants it the `SA_FLOWX` role.
* **If you manage Keycloak clients outside the chart** (external IdP, or authorization-system cannot provision clients): create `flowx-events-gateway-sa` in the service-accounts realm as a confidential client with service accounts enabled and only the client-credentials grant, then supply its secret to both values above.

> [!WARNING]
>
> If `flowx-events-gateway-sa` already exists, the migration leaves its secret untouched by design. A pre-existing client whose secret does not match the one given to Events Gateway will not be corrected on upgrade, and Events Gateway will fail to authorize subscriptions. Make the two match manually in that case.

#### Liquibase migration lock moves to database session locks

The lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so a stale `databasechangeloglock` row no longer needs clearing by hand. On any other database, Liquibase falls back to its standard row-based lock.

The previous mechanism verified the lock-holder pod through the Kubernetes API. That dependency is gone:

* Service accounts no longer need the `get pods/status` permission, and the FlowX Helm charts no longer create the corresponding Role and RoleBinding. If you maintain that RBAC outside the charts, you can remove the grant.
* The lock keeps working on Kubernetes 1.33 and newer, where the previous mechanism silently deactivated itself.

**Oracle deployments** must grant each FlowX service's database user the following before upgrading. A service whose grants are missing stops at startup with an error naming the missing grant:

```sql theme={"dark"}
GRANT EXECUTE ON SYS.DBMS_LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$SESSION TO <app_user>;
```

PostgreSQL deployments need no action: advisory locks require no additional grant.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, the Angular 21 renderer upgrade, and a Helm chart image-registry change.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. The platform upgrade from **5.9.3 → 5.9.4** requires no data migration, but it does change how the Helm charts express the container image location. Review the [deployment guidelines](./deployment-guidelines-v5.9.4#configuration-changes) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.4** is a maintenance release for the 5.9.x LTS:
>
> * **Helm charts:** the container image reference splits into `image.registry` and `image.repository`, making `global.imageRegistry` a single chart-wide override
> * **Angular 21:** the Angular renderer and the web SDKs move to Angular 21
> * **Key fixes:** branch merges no longer getting stuck, build export retry after a dependency timeout, deleting actions that call functions, gateway expression failures surfaced as incidents, library resource overview
> * **Cross-version import:** an imported theme is completed from the destination's system theme, so nothing is missing after importing an older export
> * Designer, renderer, and backend stability fixes plus security patches
> * No data migration; the only upgrade action is the Helm values change, and only for one override pattern

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, plus a Helm chart change that affects some self-hosted deployments.
>
> 📦 [**Helm chart image registry**](#helm-chart-image-registry) - `image.repository` splits into `image.registry` + `image.repository`\
> 🅰️ [**Angular 21**](#angular-21) - The Angular renderer and web SDKs move to Angular 21\
> 🔧 [**Platform improvements**](#platform-improvements) - Bug fixes and security patches
>
> ***
>
> ### **Helm chart image registry**
>
> > [card] image.repository splits into image.registry + image.repository
> >
> > Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.
> >
> > ```yaml theme={"dark"}
> > # Before
> > image:
> >   repository: <registry>/<image-name>
> >
> > # After
> > image:
> >   registry: <registry>
> >   repository: <image-name>
> > ```
> >
> > The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.
> >
> > > [!WARNING]
> > >
> > > **Check your values files before upgrading.** If you set `global.imageRegistry`, no action is needed. If you embedded the registry inside `image.repository`, move it out first, or the registry is prepended twice. This includes values files built from the FlowX setup guides before 5.9.4, which showed the combined form. Full before-and-after in the [deployment guidelines](./deployment-guidelines-v5.9.4#helm-charts-image-registry-split).
> >
> > All Deployments
>
> ***
>
> ### **Angular 21**
>
> > [card] Angular renderer and web SDKs on Angular 21
> >
> > The Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps embedding the Angular SDK should be on Angular 21 before taking 5.9.4.
> >
> > Angular does not support skipping a major in a single update, so step through the official update guide one major at a time. The **npm** and **node** requirements are unchanged from 5.9.3.
> >
> > See the [Angular SDK requirements](/5.9/sdks/angular-renderer#angular-project-requirements) for the current version floor, and the [Angular migration guide](/5.9/migrating-from-5.1-lts/angular#framework-upgrade-angular-19-→-21) for the upgrade path.
> >
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build export:** retrying a build export now re-attempts a dependency library whose own export ended in a timeout, instead of failing again immediately. Previously the retry skipped the timed-out dependency, so the parent build could never finish; the workaround was to export that dependency directly first.&#x20;
> > > > * **Actions:** deleting an action whose business rule calls a function now works instead of returning a server error. This affected any action at any nesting level, in both projects and libraries; the workaround was to delete the rule from the action first.&#x20;
> > > > * **Gateways:** an expression that fails to evaluate on an exclusive gateway now surfaces as an incident on the process instance. Previously the failure appeared only in the service logs, with no feedback in the platform.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection. Changing the page size no longer opens the wrong process from the list. &#x20;
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives while a background synchronization is still running, and merging versions no longer fails with a navigation-areas error.&#x20;
> > > > * **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds. The page index was previously lost on back-navigation.&#x20;
> > > > * **Reusable UI templates:** static input mappings configured on a reusable template are now applied at runtime.&#x20;
> > > > * **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.&#x20;
> > > > * **Entry points:** the entry-point picker in version settings now lists only processes and UI flows from the current project. Resources from dependency libraries were previously offered and could be selected.&#x20;
> > > > * **Themes and CMS resources:** exporting a theme no longer includes duplicate non-system copies of system icons, so repeated imports stop multiplying them, and importing no longer leaves system substitution tags missing.&#x20;
> > > > * **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output built from trailing empty cells and rows.&#x20;
> > > > * **Generated documents:** a document whose storage write fails now returns an error instead of being recorded as successful with a download path that cannot be opened. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.&#x20;
> > > > * **Renderers:** the document preview shows its subtitle again, and the file-upload error message picks up the configured theme.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Cross-version import:** importing a project build or version exported from an older platform line now completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten, so customizations survive.&#x20;
> > > > * **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.&#x20;
> > > > * **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.&#x20;
> > > > * **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.&#x20;
> > > > * **Integration Designer performance:** service startup no longer scans the full token-instance collection to warm up, and the run-list summary queries are indexed and gated.&#x20;
> > > > * **Database migrations:** the lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so there is no stale `databasechangeloglock` row to clear by hand. The previous mechanism recovered a stuck lock through the Kubernetes API, which required the `pods/status` permission on every service account and silently deactivated on Kubernetes 1.33 and newer. Oracle deployments need new database grants before upgrading: see the [deployment guidelines](./deployment-guidelines-v5.9.4#liquibase-migration-lock-moves-to-database-session-locks).&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade compatibility:** FlowX.AI 5.9.4 is compatible with 5.9.3. No data migration is required. One deployment-level change applies: the Helm charts split the image reference into `image.registry` and `image.repository`. Oracle deployments also need new database grants for the Liquibase migration session lock.
>
> > [!WARNING]
> >
> > **Helm values migration.** Deployments that redirect images through `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move the registry portion out before upgrading. See [Configuration changes](./deployment-guidelines-v5.9.4#configuration-changes).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Direct upgrade from 5.9.3 → 5.9.4. No data migration; review the Helm values change first.
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. The Angular SDK moves to Angular 21.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.4](./deployment-guidelines-v5.9.4).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5

Component versions, configuration, and deployment notes for FlowX.AI 5.9.5 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.5 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.4 is non-breaking and requires no data migration. The headline addition, native PostgreSQL partitioning, is opt-in: deployments that never enabled data partitioning are not affected. Review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.4 → 5.9.5**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.3 or earlier directly?** Review the [5.9.4 deployment guidelines](../v5.9.4-august-2026/deployment-guidelines-v5.9.4) first: the Helm image registry split applies when you skip 5.9.4. Upgrading from 5.9.0, 5.9.1, or 5.9.2, also review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) for the organization-ID migration fix and manually marked Liquibase changesets.

## Component versions

### Core components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.10 | 10.171.3 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.7 | 10.149.3 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.7 | 10.110.4 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.6 | 10.91.2 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.100.7 | 10.97.2 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.110.7 | 10.107.4 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.7 | 10.121.3 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.6 | 10.109.3 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.6 | 10.89.2 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.6 | 10.99.2 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.7 | 10.95.2 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.200.9 | 10.197.5 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.7 | 10.104.3 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.7 | 10.119.3 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.6 | 10.98.2 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.101.6 | 10.98.2 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.6 | 10.95.2 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.6 | 10.66.2 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.7 | 10.30.2 | 10.8.0 | - | - |
| **license** | 10.87.6 | 10.84.2 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB**: see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.282.5 | 10.275.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.2 | 10.6.0 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.9.3 | 10.8.0 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.0 | 10.10.2 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.0 | 10.10.2 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.0 | 10.10.2 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.0 | 10.10.2 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.0 | 10.10.2 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.0 | 10.10.2 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.6 | 10.32.2 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.0 | 10.10.2 | - | - | - |
| **ai-assistant** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.0 | 10.10.2 | - | - | - |
| **flowx-docs** | 5.9.5 | 5.9.4 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.5 introduces no new Kafka topics over 5.9.4. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Review [Configuration changes](#configuration-changes): everything new in this release is opt-in or ships with a safe default, so no values change is required for a standard upgrade.
2. Update container images to the 5.9.5 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Native PostgreSQL partitioning (opt-in)

Process-instance archiving on PostgreSQL can now use native declarative partitions instead of the legacy copy-based mechanism. Data partitioning itself remains **off by default** (`FLOWX_DATA_PARTITIONING_ENABLED` is `false`), so deployments that never enabled it are not affected.

New process-engine variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Use native PostgreSQL partitions for archiving when partitioning is enabled. PostgreSQL only; other databases keep the existing mechanism. | `true` |
| `FLOWX_DATA_PARTITIONING_PREMAKECRONEXPRESSION` | Schedule for the job that creates upcoming partitions in advance. | `0 0 23 * * ?` |
| `FLOWX_DATA_PARTITIONING_PREMAKEPARTITIONSAHEAD` | How many future partitions the job keeps created ahead of the current one. | `2` |

> [!WARNING]
>
> Enabling native partitioning converts the process-instance tables to partitioned tables, and the conversion is one way: there is no supported path back to unpartitioned tables. Review the [partitioning and archiving setup guide](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning) before turning it on.

#### Document plugin: processing size limits

The document plugin now enforces size limits on archive, encryption, and extraction operations. Input over the limit is rejected instead of processed. The defaults are generous; override them only if your documents legitimately exceed them.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOCUMENT_ARCHIVE_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for archive operations. | `209715200` (200 MB) |
| `DOCUMENT_ENCRYPTION_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for encryption. | `104857600` (100 MB) |
| `DOCUMENT_EXTRACT_MAX_UNCOMPRESSED_SIZE` | Maximum total uncompressed size, in bytes, an archive may expand to during extraction. | `209715200` (200 MB) |

#### Integration Designer: workflow output size guard

Workflow output published to Kafka is now size-checked before sending. A root workflow output that exceeds the limit fails the workflow run with the failure type `outputTooLargeForKafka` instead of being silently dropped by the broker's message-size limit. The check applies to root workflow outputs on automatic and default-path completion; subworkflow outputs are not checked.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_KAFKA_PAYLOAD_SIZE_LIMIT` | Maximum serialized size, in bytes, of a root workflow output published to Kafka. | `786432` |

> [!TIP]
>
> Keep this limit below your broker's `max.message.bytes`. The default, 768 KB, sits safely under the common 1 MB broker default.

#### Advancing datasource metrics

The process engine and Integration Designer now register their advancing datasource under a named connection pool (`advancing`), so its metrics are distinguishable from the main datasource pool in Prometheus. No configuration action is required.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026

Maintenance release for the 5.9.x LTS line. Native PostgreSQL partitioning for process data, bug fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. It also brings native PostgreSQL partitioning to process data. Review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.5** is a maintenance release for the 5.9.x LTS:
>
> * **Native PostgreSQL partitioning:** process data tables are partitioned by the database itself, so removing old data becomes a partition drop instead of a bulk delete
> * **Key fixes:** audit entries no longer missing or attributed to the wrong application, merge conflicts raised for changes inside embedded subprocesses, self-hosted Keycloak issuer derived from configuration
> * **Integrations:** an SFTP private key can be stored as a multi-line PEM
> * Backend, Designer, and renderer stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.5 is compatible with 5.9.4, and the upgrade requires no data migration. Native PostgreSQL partitioning is opt-in: if you had already enabled data partitioning, review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade, because the conversion to native partitions runs automatically for you and is one way.

**Before you upgrade, check these:**

* **AI job queues:** each AI service now consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group, and the new groups read only jobs published after they start. Wait until the `ai-services` group has no lag on the job topics before you upgrade, so no queued job is skipped. If your cluster restricts consumer groups with ACLs, allow the new groups first.
* **Relational data sources:** Oracle data sources connect only to hosts that resolve to a public address. Add private database hosts to the allowlist, as described in [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Service-account secrets:** confirm every service-account client secret is set on `authorization-system`, or the service stops at startup. The secrets are listed in the [Authorization setup guide](/5.9/setup-guides/authorization-setup-guide).
* **Dashboards and alerts:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total`.
* **Runtime log levels:** the `loggers` actuator endpoint is no longer exposed by default. Add it back as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Data partitioning:** if you had already turned on data partitioning, the conversion to native partitions runs automatically on upgrade and is one way. See the [deployment guidelines](./deployment-guidelines-v5.9.5).

**Upgrade path:** direct upgrade from 5.9.4. Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. Component versions are listed in the [5.9.5 deployment guidelines](./deployment-guidelines-v5.9.5).

***

## Native PostgreSQL partitioning

The process engine stores process data in tables that PostgreSQL itself partitions by time. Retention then
works by dropping whole partitions rather than deleting rows one at a time, which keeps the cost of
removing old data flat as the tables grow.

This is the same partitioning model described for the 5.12 line, delivered into the 5.9.x LTS.

For how partitioning interacts with archiving and retention, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving).

***

## Full changelog

### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.&#x20;
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](#native-postgresql-partitioning).&#x20;

### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.&#x20;
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.&#x20;
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.&#x20;
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.&#x20;
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.&#x20;
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.&#x20;
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.&#x20;
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](./deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).&#x20;
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](./deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).&#x20;
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).&#x20;
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).&#x20;
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.&#x20;
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.&#x20;

### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.&#x20;
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.&#x20;
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.&#x20;
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.&#x20;
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.&#x20;
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.&#x20;
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.&#x20;
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.&#x20;
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.&#x20;
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.&#x20;
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# Deployment guidelines v5.9.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6

Component versions, configuration, and deployment notes for FlowX.AI 5.9.6 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.6 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.5 adds one Kafka topic, a database table, and a MongoDB index. The table and the index are created automatically when the services start. Review [Kafka topics](#kafka-topics), [Configuration changes](#configuration-changes), and the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes) before you deploy.

> [card] Upgrade Path
>
> **5.9.5 → 5.9.6**: Direct upgrade. No manual data migration is required.
>
> **5.9.6 → 6.0.0**: See [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.4 or earlier directly?** Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first, then the earlier pages they point to.

## Component versions

### Core components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.17 | 10.174.10 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.14 | 10.152.7 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.13 | 10.113.7 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.11 | 10.94.6 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.101.1 | 10.100.7 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.111.1 | 10.110.7 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.13 | 10.124.7 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.12 | 10.112.6 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.8 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.11 | 10.92.6 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.11 | 10.102.6 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.12 | 10.98.7 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.201.2 | 10.200.9 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.13 | 10.107.7 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.13 | 10.122.7 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.13 | 10.101.6 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.102.1 | 10.101.6 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.12 | 10.98.6 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.12 | 10.69.6 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.14 | 10.33.7 | 10.8.0 | - | - |
| **license** | 10.87.12 | 10.87.6 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** 1.52.0, deployed and upgraded by the **SpiceDB operator** 1.25.1.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **solution-portal** (renamed from react-saas) | 10.285.4 | 10.282.5 | 10.230.2 | - | - |
| **iOS renderer** | 10.9.2 | 10.6.2 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.10.2 | 10.9.3 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.2 | 10.11.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.2 | 10.11.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.2 | 10.11.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.2 | 10.11.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.2 | 10.11.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.2 | 10.11.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.13 | 10.35.6 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.2 | 10.11.0 | - | - | - |
| **ai-assistant** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.2 | 10.11.0 | - | - | - |
| **flowx-docs** | 5.9.6 | 5.9.5 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.6 adds one Kafka topic. If your cluster does not create topics automatically, create it before you deploy, and allow both services in your ACLs.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.build.deployment-failed.v1` | runtime-manager | application-manager | Reports a build deployment that failed, so application-manager can queue it for a retry. |

The topic is included in the FlowX Kafka topics chart from version 10.2.0. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Create the `ai.flowx.build.deployment-failed.v1` Kafka topic if your cluster does not create topics automatically. See [Kafka topics](#kafka-topics).
2. Review [Configuration changes](#configuration-changes). No values change is required for a standard upgrade.
3. The `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes).
4. Update container images to the 5.9.6 versions listed in the tables above.
5. Deploy services using your standard deployment process.
6. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Build redeployment retries

When a build deployment fails, application-manager queues it for a retry. The queue is now stored in the application-manager database, in the new `failed_deployment` table, instead of in Redis. The table is created automatically on startup. runtime-manager reports each failure on the `ai.flowx.build.deployment-failed.v1` topic, and application-manager consumes it.

New application-manager variables (the defaults fit a standard deployment):

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_BUILD_DEPLOYMENTFAILED` | Topic that carries failed build deployments. | `ai.flowx.build.deployment-failed.v1` |
| `KAFKA_CONSUMER_GROUPID_BUILD_DEPLOYMENTFAILED` | Consumer group that reads the topic. | `build-deployment-failed-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_DEPLOYMENTFAILED` | Number of consumer threads for the topic. | `1` |

> [!WARNING]
>
> Retries that are still queued in Redis when you upgrade are not moved to the new table. Re-publish any build whose deployment failed shortly before the upgrade. The old entries stay in the Redis hash `build:failed-deployments:v3`, under the persistence key prefix configured for application-manager. Nothing reads them after the upgrade, so you can delete the hash.

#### MongoDB setting names

Services that use MongoDB now read their connection settings from new names. The previous `SPRING_DATA_MONGODB_*` variables still feed the new settings, so existing deployments need no change. Use the new names in new configuration.

| Previous variable | New variable |
| - | - |
| `SPRING_DATA_MONGODB_URI` | `SPRING_MONGODB_URI` |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | `SPRING_MONGODB_REPRESENTATION_UUID` |
| `SPRING_DATA_MONGODB_STORAGE` | `FLOWX_DATASOURCE_MONGO_STORAGE` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | `FLOWX_DATASOURCE_APPRUNTIME_ENABLED` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | `FLOWX_DATASOURCE_APPRUNTIME_URI` |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | `FLOWX_DATASOURCE_APPRUNTIME_REPRESENTATION_UUID` |

`SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION` no longer has any effect: indexes on the runtime database are never created automatically.

#### Document parser models

The document parser image now contains its layout, table, and OCR models, so the parser downloads nothing at startup or on the first parse. It runs without internet access and on a read-only filesystem. `USE_DOCLING` no longer has any effect on the document parser and can be removed from its configuration.

#### Integration Designer: document download timeout

A REST node JSON body can include `"@@base64File(<path>)"` to send a Document Plugin file as base64. Downloading the file from the Document Plugin is cancelled after this timeout. See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

New integration-designer variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` | Longest time a Document Plugin file download for a REST node JSON body may take before it is cancelled. | `PT5M` |

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026

Maintenance release for the 5.9.x LTS line. Durable build redeployment retries, project version merge fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Review the [deployment guidelines](./deployment-guidelines-v5.9.6) before you upgrade: this release adds one Kafka topic.

> [card] Release Highlight
>
> **FlowX.AI 5.9.6** is a maintenance release for the 5.9.x LTS:
>
> * **Durable build redeployments:** a build deployment that failed and waits for a retry is stored in the database, so a Redis flush or restart no longer drops it
> * **Key fixes:** project version merges no longer lose navigation areas, Resources Changed no longer flags unchanged resources, and Number attributes keep the selected subtype
> * Backend, Designer, and AI stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.6 is compatible with 5.9.5. The upgrade adds a database table and a MongoDB index, both created automatically when the services start.

**Before you upgrade, check these:**

* **AI Platform Helm chart:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime.&#x20;
* **Kafka topics:** create the `ai.flowx.build.deployment-failed.v1` topic if your cluster does not create topics automatically, and allow it in your ACLs. `runtime-manager` produces it and `application-manager` consumes it. See [Kafka topics](./deployment-guidelines-v5.9.6#kafka-topics).
* **Pending build redeployments:** retries that are still queued in Redis when you upgrade are not carried over. Re-publish any build whose deployment failed shortly before the upgrade. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Workflow node retries:** retry waits now grow exponentially and the max interval caps each wait instead of the whole retry window. Review the retry settings of nodes that rely on the previous timing.
* **Connection tests:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources. Grant these to custom roles that run connection tests.
* **Integration Designer startup:** the first start after the upgrade builds a new index on the `workflow_instances` MongoDB collection. On a large collection, allow extra time before the readiness check passes.
* **React Native SDK hosts:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` and keeps showing the current process, like the Android and iOS SDKs. Update your app to dispose the current process handle and continue the new process. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).

**Upgrade path:** direct upgrade from 5.9.5. Upgrading from 5.9.4 or earlier? Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/React Native/iOS/Android) and Designer 5.9.x. Component versions are listed in the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6).

***

## Full changelog

### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json) and [Integration Designer: document download timeout](./deployment-guidelines-v5.9.6#integration-designer-document-download-timeout).&#x20;

### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.&#x20;
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).&#x20;
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.&#x20;
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect. See [Document parser models](./deployment-guidelines-v5.9.6#document-parser-models).&#x20;
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.&#x20;
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.&#x20;
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](./deployment-guidelines-v5.9.6#mongodb-setting-names).&#x20;
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.&#x20;
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.&#x20;
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6) for its version.&#x20;

### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.&#x20;
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.&#x20;
* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.&#x20;
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.&#x20;
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.&#x20;
* **React Native SDK:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` instead of replacing the shown process itself, like the Android and iOS SDKs. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).&#x20;
* **React Native SDK:** a custom component keeps receiving data after the app returns from the background, for example from the Android document picker, so a document upload waiting for its link completes.&#x20;
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.9.x to 6.0.0 changelog
Source: https://docs.flowx.ai/release-notes/v6.x/5.9-to-6.0-changelog

Every change a self-hosted FlowX.AI 5.9.x installation picks up when it moves to 6.0.0, grouped by release and type, with an RSS feed.

This page lists what changes for a self-hosted FlowX.AI 5.9.x installation that moves to 6.0.0, newest first. Releases 5.10 to 5.13 shipped to SaaS first, and self-hosted installations get their features with 6.0.0. Changes already delivered in a 5.9.x patch are in the [5.9.x LTS changelog](/release-notes/v5.x/5.9-lts-changelog) and are not repeated here. Mobile renderers and the React Native SDK are covered in their own release notes.

On FlowX.AI SaaS, apps moved from 5.13.0 to 6.0.0, so only the 6.0.0 entry applies to them, including its upgrade actions.

**6.0.0**

October 2026

**Upgrade actions:** check these in your existing apps.

* **AI node prompts:** the chat message is no longer appended. Reference `${userMessage}` in **Context**. [Details](/6.x/ai-platform/chat-driven-workflows#context)
* **AI node retries:** on by default, up to 10 times, 30 seconds apart. [Details](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service)
* **Substitution tags:** `@@key` is rewritten to `${tag:key}`, and a missing `sys_*` tag now renders empty. [Details](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#what-changes-in-existing-apps-when-you-upgrade)
* **FlowX Database and Unmanaged MongoDB writes:** `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter are rejected. To match every document, pass `{"_id": {"$exists": true}}`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb)
* **Masked names:** data-privacy placeholders now carry the gender, such as `<NAME_F_1>`. Update prompts or scripts that match `<NAME_1>`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy)
* **Email triggers over IMAPS:** the mail server's certificate is now verified, so a self-signed or mismatched certificate stops the trigger from connecting. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway)
* **Evaluations:** datasets become test cases with no checks, so an experiment skips them until you add an assert or evaluator. [Details](/6.x/ai-platform/evaluations#datasets-from-earlier-versions)
* **Exports from 5.1.x:** they no longer import, and 5.1.x is no longer an export target. Import a 5.1.x export into a 5.9.x environment and export it again from there. [Details](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x)
* **Scripts on GraalVM:** they now stop at the same per-language time limit as the native engine, 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0 they had no limit. [Details](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits)

Self-hosted installations also follow the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) and the [migration guide](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview) for the Helm chart and renderer SDKs.

#### New

* **Developer Agentic Harness:** a plan can split the work into stories, delivered one at a time, each with how to test it. Comment mode lets you select a component in the running app and ask for a change, and conversations follow you across the Designer. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Integration Designer:** add schedules to a workflow's Start node to run it once on a date or repeatedly on an ISO or cron cycle. A schedule fires only after you activate it in **Runtime** → **Runtime Settings** → **Schedules**. See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
* **Integration Designer:** the Generate Tabular File node turns an array of rows into a CSV or XLSX file. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
* **FlowX Database:** an index can enforce unique values on one attribute or a compound key, and existing duplicates are reported when you run **Apply Indexes**. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
* **Knowledge Base:** **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
* **Resources:** **Documentation** in a resource's menu holds a short description and longer Markdown documentation. Media Library assets get a description, used as the image's alt text. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
* **Substitution tags:** write `${tag:key}` anywhere in a component's text, next to static text and process data. The upgrade rewrites whole-value `@@key` references to `${tag:key}`, and `@@key` keeps working as a whole value. See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).

#### Changed

* **Designer header:** the header holds the project name, the **Config** / **Runtime** switch, the **Build with AI** and **Comment** toggles, and **Run project**. Branching, the current version, and **Commit Changes** move to a version block in the footer. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
* **AI nodes:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when its AI service or provider can't be reached. Turn on **Allow Retry** to set your own count, interval, and backoff. See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
* **Chat-driven workflows:** the chat message is no longer appended to an AI node's prompt. Reference `${userMessage}` in the node's **Context**. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
* **Evaluations:** each workflow has its own test cases, grouped by tags, with **equals** and **equals as JSON** asserts and LLM evaluators. The upgrade converts datasets to test cases with no checks, so add an assert or evaluator to each one before you run it. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
* **Certificates:** the **Certificates** panel on REST and File Storage data sources has two parts: **Trust** (System CAs, Custom CA, or None (insecure)) and **Identity** for mutual TLS. Existing settings are converted automatically. See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates).
* **Knowledge Base:** turning **Containing Personal Information** on or off re-embeds the existing content with the new model. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested).
* **Issues Console:** a check also covers the version itself: entry points, theme, library builds, and unused dependencies. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
* **Notification center:** covers version imports and build exports and imports, alongside version exports and process instance migrations. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
* **Configuration parameters:** after you save a sensitive value, the Designer shows `********` in its place. The real value is still used at runtime. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
* **Script engine:** scripts on GraalVM stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
* **Canvas:** **Auto-arrange** on the workflow canvas and **Arrange** on the process canvas show a layout preview before anything moves. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).
* **Timer events:** timer nodes use the schedule editor. Dates and times are picked in local time and saved in UTC. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).
* **Versioning:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).
* **Datepicker:** **Allow manual input** lets users type a date in the pattern of the project's default locale. Web only.
* **Data mapping:** typing a new attribute path, such as `client.address.street`, creates the data types it names when you save the mapping.

#### Removed

* **AI agents:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors are removed. Open the agent rail with ⌘K (Ctrl+K) or the sparkle toggle in the header. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Evaluations:** the Code evaluators are removed. Use **equals** in place of Exact match and **equals as JSON** in place of JSON match. Levenshtein has no replacement. See [Evaluations](/6.x/ai-platform/evaluations).
* **Export and import:** exports from 5.1.x no longer import, and 5.1.x is no longer an export target. See [Exports from 5.1.x](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x).

#### Deprecated

* **GraalVM script engine:** deprecated. FlowX.AI 6.1.x is the last release family that supports it. Scripts on GraalVM keep working in 6.0.0; move them to the native engine. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).

[6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) · [6.0.0 deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)

**5.13.0**

September 2026

#### New

* **Developer Agentic Harness:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys the app, drafts a plan for you to confirm, and runs the change on its own branch; merging and serving a new version stay with you. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Notification center:** a bell in the Designer opens a 30-day notification history with read state, search, and filters. See [Notification center](/6.x/docs/flowx-designer/notification-center).
* **UI Designer:** copy UI components and paste them into another UI Flow, app, or context. The paste names anything it could not place, and pasted components get unique names.
* **Versioning:** committing or merging a version takes an optional description of up to 2000 characters, and a commit details view shows what a version contains. See [Commit descriptions and details](/6.x/docs/projects/managing-applications/versioning#commit-descriptions-and-details).
* **Runtime:** an operator with the corrective-actions role moves the token of a running process instance to another node. See [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
* **Document classifiers:** a classifier's corpus can be exported and imported between environments, and viewed read-only in the **Data** tab. See [What travels between environments](/6.x/docs/platform-deep-dive/integrations/document-classifiers#what-travels-between-environments).
* **Integration Designer:** the File Encryption node encrypts or decrypts a file with a password inside a workflow. The file path and password take expressions.
* **UI Designer:** a start workflow trigger takes a condition, so the workflow starts only when the condition holds.&#x20;
* **FlowX Database:** the Intersects operator matches documents whose array field shares at least one value with a given list. See [Intersects on array fields](/6.x/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).
* **Personal Information Guard:** AI nodes with the input scan on log the request as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/6.x/ai-platform/personal-information-guard#request-after-pii-anonymization).

#### Changed

* **Access management:** the Workspace corrective actions editor role replaces the Workspace operations editor role. Users and groups with the old role move to the new one automatically. See [Workspace corrective actions editor permission matrix](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
* **Export and import:** version exports bundle dependencies the same way build exports do, and the export dialog preselects the target platform version. See [Version exports that bundle dependencies](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#version-exports-that-bundle-dependencies).
* **Integration Designer:** the Tabular Data Extraction node becomes the Data Parse node and also parses XML and JSON. See [Data Parse: XML and JSON support](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support).
* **Knowledge Base:** embedding jobs are scheduled fairly by default, so a large ingestion no longer delays small jobs queued behind it.
* **File sources:** Document and Image components share one source configuration. In process user tasks, the **Document Plugin Path** source takes a Documents plugin `downloadPath` directly. See [Selecting the file to download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download#selecting-the-file-to-download).
* **Task management:** the task list searches, filters, and sorts on the translated labels it displays. See [Search and sort on translated labels](/6.x/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).
* **Substitution tags:** custom tags can no longer start with `sys_`, which is reserved for system tags. See [Substitution tags](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags).
* **Elasticsearch:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Elasticsearch replica auto-expansion](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).
* **Processes:** the process name moves from **Settings** into a **Details** modal.
* **User management:** inviting many users at once has a reworked flow, and a sign-up link takes new users directly to the right solution.

[5.13.0 release notes](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) · [5.13.0 deployment guidelines](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13)

**5.12.0**

September 2026

**Upgrade actions:** the webhook gateway now reads the runtime registry, which adds a MongoDB dependency it did not have before. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets).

#### New

* **Integration Designer:** turn on **Parallel Multi-Instance** on a Subworkflow node to start one subworkflow per element of an input array and collect the results in an output array. See [Parallel multi-instance](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance).
* **Integration Designer:** email and webhook triggers can start an integration workflow, not only a process. See [External triggers](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).
* **Integration Designer:** a Subworkflow node can route a mapping failure to its own branch instead of stopping the parent workflow. It is opt-in per node. See [Routing a subworkflow failure](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
* **Integration Designer:** the Send Notification node fills a project notification template from workflow data and sends it. See [Send Notification node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node).
* **Db2 data source:** IBM Db2 joins the relational data sources, with Db2 for i as the default and Db2 LUW also supported. Db2 for z/OS is listed but not implemented, and selecting it fails with an error. See [Db2 database](/6.x/docs/platform-deep-dive/integrations/db2-database).
* **Runtime:** bulk migration moves a filtered set of process instances to a new build in one run, with a check before it runs. See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances).
* **Runtime:** a Workflow Instances page lists every workflow run in the project, filterable by status, date, and origin. The Process Instances and UI Flow Sessions lists gain status and start-date filters. See [Workflow instances](/6.x/docs/projects/runtime/workflow-instances).
* **Personal Information Guard:** mask and restore nodes place personal-data handling as explicit workflow steps. See [Masking and restoring across several nodes](/6.x/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
* **Deep Research node:** researches a question across the open web and files a cited report into a Knowledge Base. Depth is Quick, Standard, Deep, or Custom, and domains can be restricted with an allow or deny list. See [Deep Research node](/6.x/docs/platform-deep-dive/integrations/deep-research-node).
* **Custom Agent:** a reusable function with input and output slices can be an agent tool. Built-in tools are a catalog of twenty tools in five categories: Math, List, Date, Text, and Web search. See [Tools tab](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#tools-tab).
* **Chat component:** users rate an agent's answer and add a reason, and the ratings are recorded in audit. See [Rating an answer](/6.x/ai-platform/chat-component#rating-an-answer).
* **Evaluations:** custom evaluators score with Numeric or Binary rules and belong to the workflow you create them in. See [Custom evaluators](/6.x/ai-platform/evaluations#custom).
* **Issues panel:** the Designer validates the resources in a project version and collects the findings in one **Issues** panel. See [Checking for issues](/6.x/docs/projects/managing-applications/checking-for-issues).
* **Versioning:** merge into any branch you can merge into, and archive, unarchive, or delete branches. See [Managing branches](/6.x/docs/projects/managing-applications/versioning#managing-branches).
* **Process canvas:** a **New Node** panel, drop-anywhere connecting, draggable control points on sequence flows, and swimlanes that resize from all four edges. See [Faster ways to build](/6.x/docs/building-blocks/process/process#faster-ways-to-build).
* **Reusable UI templates:** a template can be built for UI Flow pages as well as process user tasks. Templates created earlier count as Process templates. See [Where a template can be used](/6.x/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used).

[5.12.0 release notes](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026) · [5.12.0 deployment guidelines](/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12)

**5.11.0**

August 2026

#### New

* **Custom Agent:** attach FlowX workflows as tools, each with a hint that tells the agent when to call it. See [How workflow tools run](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run).
* **Custom Agent:** agentic knowledge base search breaks a question into sub-queries and retries with reworded queries when the first pass finds nothing. **Show Reasoning** records the model's reasoning summary in the logs. See [Agentic knowledge base search](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#agentic-knowledge-base-search).
* **Knowledge Base:** a Knowledge Base with **Containing Personal Information** on can use a local embedding model, set up as a CUSTOM provider in the organization AI settings. See [Containing personal information](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).
* **Knowledge Base:** the Update Knowledge Base node can delete entries that match a metadata filter, and its FAIL branch reports what failed and how many chunks were rolled back. See [Delete entries](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#delete-entries).
* **Document classifiers:** define classes, upload training data, and train or import a model, then route each document page with the Document Classification node. See [Document classifiers](/6.x/docs/platform-deep-dive/integrations/document-classifiers).
* **Reusable functions:** Script and Condition (Fork) nodes in the Integration Designer can call reusable functions. See [Reusable functions](/6.x/docs/building-blocks/reusable-resources/reusable-functions).
* **Integration Designer:** the Subworkflow node can map input per start node and output per end node instead of raw JSON. See [Subworkflow node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#subworkflow-node).
* **Data model:** attributes support validators such as Required, Min/Max Value, Min/Max Length, Pattern, and Email Format, wherever the data model is used. See [Attribute validations](/6.x/docs/building-blocks/project-data-model#attribute-validations).
* **Templates:** document and notification templates use the structured data model, with typed attributes and an **Input Parameters** tab. See [Managing notification templates](/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates).
* **Chat component:** the chat button shows an unread-message badge, the panel searches conversation history, and the input can be disabled by a condition. See [Chat](/6.x/docs/building-blocks/ui-designer/ui-component-types/chat).
* **UI Flows:** a **Navigate To** action can require selected forms to pass validation before it navigates. See [Navigate To action](/6.x/docs/building-blocks/ui-flows#navigate-to-action).
* **UI Flows:** with **Allow multiple editors** off, a running session is restricted to its owner. New flows default to single-owner; existing and imported flows keep the shared behavior. See [Session owner](/6.x/docs/building-blocks/ui-flows#session-owner).
* **Process Renderer:** a process-end trigger runs a configured action when the embedded process ends. See [Process end handling](/6.x/docs/building-blocks/ui-flows#process-end-handling).

#### Changed

* **Chat-driven workflows:** a conversational workflow must send at least one chat reply, or the run fails with an error. See [Chat-driven workflows](/6.x/ai-platform/chat-driven-workflows).
* **Custom Agent:** the **Instructions** field is limited to 10,000 characters. See [Custom Agent node](/6.x/docs/platform-deep-dive/integrations/custom-agent-node).
* **Response caching:** POST REST endpoints, file-storage LIST and DOWNLOAD, and Mongo FIND, FIND\_ONE, and AGGREGATE operations are cacheable. Mutating operations are never cached. See [REST endpoint caching](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching).
* **Email triggers:** Email Trigger and Microsoft Outlook data sources filter attachments by file extension. Existing category selections are migrated automatically. See [Attachment handling](/6.x/docs/platform-deep-dive/integrations/email-trigger#attachment-handling).
* **Audit:** UI Flow runtime sessions are audited in more detail, including workflow runs, chat messages, and conversation reads. See [Audit](/6.x/docs/platform-deep-dive/core-extensions/audit).
* **Export and import:** exporting to an older platform version removes UI-template features the target cannot read. See [Cross-version export and import](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
* **UI Flows:** an expired session shows a session-expired screen with a start-fresh option.
* **Renderers:** enumeration lookups are batched into a single request.

[5.11.0 release notes](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026) · [5.11.0 deployment guidelines](/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11)

**5.10.0**

July 2026

#### New

* **PostgreSQL data source:** connect a workflow to a PostgreSQL database and run SQL query operations from workflow nodes. See [PostgreSQL database](/6.x/docs/platform-deep-dive/integrations/postgresql-database).
* **SOAP data source:** import a WSDL from a URL or file, and call each operation from workflows with a SOAP Operation node. See [SOAP System](/6.x/docs/platform-deep-dive/integrations/soap-system).
* **FlowX Database:** MongoDB aggregation pipelines group, join, and reshape documents beyond a single query. See [Aggregation pipelines](/6.x/docs/platform-deep-dive/integrations/flowx-database#aggregation-pipelines).
* **Integration Designer:** the Tabular Data Extraction node reads a spreadsheet or CSV file into structured JSON, one object per row. See [Tabular Data Extraction node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node).
* **Integration Designer:** the Template Filling node generates a PDF or DOCX document from a document template filled with workflow data. See [Template Filling node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node).
* **Integration Designer:** the Combine Files node merges PDFs in a given order, and the Split File node splits a PDF by page ranges or per page. See [Combine Files node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node).
* **Documents plugin:** template-based generation can produce DOCX as well as PDF, set with `outputFormat`. See [Generating DOCX output](/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output).
* **Knowledge Base:** a failed ingestion shows its status and reason, and **Retry** re-runs the last operation after cleaning up partial content. The Update Knowledge Base node gains a FAIL exit with per-operation rollback. See [Error handling and retry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#error-handling-and-retry).
* **File Download component:** end users download files directly from a rendered app. See [File download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download).
* **Global header and footer:** a UI Flow can define a header and footer shown on every page. See [Global header and footer](/6.x/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer).
* **Event handlers:** event handlers can fire on a condition. The **Save Local Variable** action saves the clicked collection row into local data under a key. See [Conditional triggers](/6.x/docs/building-blocks/ui-designer/event-handlers#conditional-triggers) and [Save Local Variable](/6.x/docs/building-blocks/ui-designer/event-handlers#save-local-variable).
* **Image component:** the Image component honors a color property. See [Image](/6.x/docs/building-blocks/ui-designer/ui-component-types/image).
* **Data source testing:** the database query testing modals have a **Documents** tab, and multi-record operations report an affected-record count. See [Testing data sources](/6.x/docs/platform-deep-dive/integrations/testing-data-sources).
* **Mistral provider:** add Mistral with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability. See [AI providers](/6.x/ai-platform/ai-providers).

#### Changed

* **Documents:** the **Document Type** field is renamed **Document Tag**. Behavior is unchanged.

[5.10.0 release notes](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026) · [5.10.0 deployment guidelines](/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10)


# Deployment guidelines v6.0.0
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0

Component versions, Kafka topics, environment variables, and Helm chart changes for FlowX.AI 6.0.0, with the steps a self-hosted upgrade needs.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 6.0 is a feature release. On SaaS, FlowX applies every change on this page. Self-hosted deployments usually follow LTS releases and receive these changes with the next LTS release family. If you upgrade a self-hosted installation to 6.0.0, apply the changes below in the order given in [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

### Before you upgrade a self-hosted installation

* Set every AI service group flag explicitly. See [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart).
* Deploy designer-user, the new `core` service. harness and ui-driver (`devtime`) and dynamic-classifier (`runtime`) deploy only if you turn their group on. See [New services](#new-services).
* Create the new database users and secrets for the services you deploy. Every installation needs the four new keys in `keycloak-flowx-realm-clients`. See [New databases and secrets](#new-databases-and-secrets).
* Give process-engine read access to the integration-designer bucket. See [New databases and secrets](#new-databases-and-secrets).
* If you turn on dynamic-classifier, set its bucket name and provide its 20Gi volume. See [Update your values](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart#update-your-values).
* If you route with Kubernetes Ingress, move callers off the admin Ingress routes that the chart no longer creates. See [New databases and secrets](#new-databases-and-secrets).
* Create the new Kafka topics. If your cluster uses ACLs, also give the new clients of three existing topics access. See [New Kafka topics](#new-kafka-topics).
* Let audit-core reach Redis. It now uses Redis only to choose which replica runs its nightly cleanup job, not as a cache, and the chart connects it to the same Redis server as the other services. If you restrict which services can reach Redis, add audit-core. See [Configuring Redis](/6.x/setup-guides/audit-setup-guide#configuring-redis).
* Set the personal-data encryption master key on integration-designer. See [Personal-data encryption master key](#new-required-secret-personal-data-encryption-master-key).
* Choose how Elasticsearch replicates new indices. See [Elasticsearch replica auto-expansion](#changed-default-elasticsearch-replica-auto-expansion).
* Add the MongoDB hosts on your private network that data sources use to `FLOWX_SSRFALLOWEDHOSTS`. See [nosql-db-runner host restrictions](#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).
* Trust the certificates of the IMAP servers your email triggers read from. See [IMAPS certificate verification](#changed-default-imaps-certificate-verification-in-email-gateway).

Upgrading from 5.9.5 or earlier? Two changes from 5.9.6 also apply. See [Upgrading from an older patch release](#upgrading-from-an-older-patch-release).

## Component versions

The versions below are the component versions that make up FlowX.AI 6.0.0, next to FlowX.AI 5.9.6, the latest 5.9.x release a self-hosted installation upgrades from. A dash marks a component that is new since 5.9.6. On SaaS, FlowX manages these versions.

### Core components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **admin** | 11.132.0 | 10.152.14 |
| **advancing-controller** | 11.86.0 | 10.98.12 |
| **application-manager** | 11.143.0 | 10.159.3 |
| **audit-core** | 11.92.0 | 10.102.11 |
| **authorization-system** | 11.102.0 | 10.122.13 |
| **cms-core** | 11.114.0 | 10.113.13 |
| **data-search** | 11.87.0 | 10.92.11 |
| **data-sync** | 11.94.0 | 10.107.13 |
| **designer** | 11.252.0 | 10.285.4 |
| **designer-user** | 11.31.0 | - |
| **document-plugin** | 11.122.0 | 10.124.13 |
| **email-gateway** | 11.110.0 | 10.102.1 |
| **events-gateway** | 11.93.0 | 10.101.1 |
| **file-gateway** | 11.105.0 | 10.33.14 |
| **integration-designer** | 11.158.0 | 10.201.2 |
| **license** | 11.94.0 | 10.87.12 |
| **nosql-db-runner** | 11.98.0 | 10.101.13 |
| **notification-plugin** | 11.113.0 | 10.111.1 |
| **organization-manager** | 11.101.0 | 10.98.12 |
| **process-engine** | 11.137.1 | 10.174.17 |
| **runtime-manager** | 11.143.0 | 10.159.3 |
| **scheduler-core** | 11.89.0 | 10.94.11 |
| **task-management-plugin** | 11.109.0 | 10.112.12 |
| **webhook-gateway** | 11.102.0 | 10.69.12 |

### AI base components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-gateway** | 11.118.1 | 10.35.13 |
| **embedder** | 11.7.0 | 10.11.2 |
| **knowledgebase-indexer-v2** | 11.7.0 | 10.11.2 |
| **knowledgebase-rag** | 11.7.0 | 10.11.2 |
| **doc-parser** | 11.7.0 | 10.11.2 |

### AI dev-time components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-analyst** | 11.7.0 | 10.11.2 |
| **ai-architect** | 11.7.0 | 10.11.2 |
| **ai-assistant** | 11.7.0 | 10.11.2 |
| **ai-designer** | 11.7.0 | 10.11.2 |
| **ai-developer** | 11.7.0 | 10.11.2 |
| **harness** | 11.7.0 | - |
| **kb-enrichment** | 11.7.0 | 10.11.2 |
| **planner** | 11.7.0 | 10.11.2 |
| **ui-driver** | 11.252.0 | - |

### AI runtime components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **agent-builder** | 11.7.0 | 10.11.2 |
| **cee-pii** | 11.7.0 | - |
| **data-privacy** | 11.7.0 | 10.11.2 |
| **doc-converter** | 11.7.0 | 10.11.2 |
| **dynamic-classifier** | 11.7.0 | - |
| **evals-judge** | 11.7.0 | 10.11.2 |
| **speech-to-text** | 11.7.0 | 10.11.2 |
| **web-crawler** | 11.7.0 | 10.11.2 |

### AI extensions

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **modpod** | 11.0.1 | 10.0.7 |
| **observatory-api** | 11.29.4 | 10.7.2 |
| **observatory-platform** | 11.29.4 | 10.7.2 |
| **observatory-web** | 11.29.4 | 10.7.2 |

In FlowX.AI 6.0, the Observatory components run on environments operated by FlowX. They aren't included in client deployments in this release.

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart and deployed with the AI base group (see [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart)). Its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/6.x/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.252.0` for FlowX.AI 6.0.0). The native iOS and Android renderers version independently.

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **@flowx/angular-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/angular-theme** | 11.252.0 | 10.285.4 |
| **@flowx/angular-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/core-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/core-theme** | 11.252.0 | 10.285.4 |
| **solution-portal** | 11.252.0 | 10.285.4 |
| **iOS renderer** | 11.6.0 | 10.9.2 |
| **Android renderer** | 11.18.0 | 10.10.2 |

The **solution-portal** container app tracks the designer version.

***

## Configuration changes

This section compares environment variables, Kafka topics, and the `flowx-ai` Helm chart with FlowX.AI 5.9.6. It includes the changes that reached SaaS in 5.10 to 5.13, so a self-hosted upgrade from 5.9.6 needs only this page.

### New Kafka topics

Compared with 5.9.6, create these 42 topics. Create all of them, whatever your group flags: topics for services you don't deploy stay unused. On SaaS they are created and managed automatically.

**AI nodes as durable jobs:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.agent-node.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.progress.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.cancel.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Deep research node:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Validation findings:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.application-version.validation-findings.request-admin.v1` | application-manager → admin |
| `ai.flowx.application-version.validation-findings.request-cms.v1` | application-manager → cms-core |
| `ai.flowx.application-version.validation-findings.request-document-plugin.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.validation-findings.request-integration.v1` | application-manager → integration-designer |
| `ai.flowx.application-version.validation-findings.request-notification-plugin.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.validation-findings.request-application-manager.v1` | application-manager → application-manager |
| `ai.flowx.application-version.validation-findings.response.v1` | admin, cms-core, document-plugin, integration-designer, notification-plugin → application-manager |
| `ai.flowx.application-version.validation-findings.job-completed.v1` | application-manager → harness |

**Structured template data model:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |

**Runtime content import and export:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → embedder |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | embedder → integration-designer |

**Document classification and extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → none (dead-letter topic) |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | doc-parser → integration-designer |

**Event-triggered workflows:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Workflow schedules:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.workflow-schedules.updates.in.v1` | integration-designer → runtime-manager |
| `ai.flowx.core.notify.timer-event-schedule.state.v1` | scheduler-core → runtime-manager |

**Bulk instance migration and move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

**Designer notifications and preferences:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |
| `ai.flowx.eventsgateway.user.notifications.v1` | designer-user → events-gateway |
| `ai.flowx.designer-user.user-preferences.v1` | designer-user → designer-user |

> [!NOTE]
>
> If your Kafka cluster uses ACLs, also give the new clients of these existing topics access:
>
> * `ai.flowx.application-version.sync.out.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.correction-after-app-operation.response.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1`: document-plugin

### New services

Compared with 5.9.6, the `flowx-ai` Helm chart adds four services. On SaaS they are provisioned and managed by FlowX.

| Service | Group | What it does | Dependencies |
| - | - | - | - |
| designer-user | `core` | Stores Designer user preferences, such as the last-used workspace, and delivers Designer notifications | MongoDB, Redis, Kafka |
| harness | `devtime` | Runs the Developer Agentic Harness | PostgreSQL, Redis, Kafka |
| ui-driver | `devtime` | Renders UI flows in the background for the Developer Agentic Harness | None |
| dynamic-classifier | `runtime` | Classifies documents with trained models | PostgreSQL, a persistent volume, Kafka |

The databases, secrets, and volume are in [New databases and secrets](#new-databases-and-secrets).

The harness reuses the platform's existing Redis, so nothing new is provisioned. It uses Redis to stream a running turn to every open Designer session and to cancel a turn from any harness pod. Without Redis, turns still run, but live progress and cancellation across pods don't work.

The harness also consumes the existing `ai.flowx.llm.config.changed.v1` topic, so a change to an organization's AI model settings reaches it right away. Without Kafka, it picks up the change when its cache expires.

### AI service groups in the Helm chart

The `flowx-ai` Helm chart groups the services into four groups. Each group has its own flag, `groups.<group>.enabled`:

| Group | Services |
| - | - |
| `core` | Core platform services |
| `base` | The AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and the bundled Qdrant |
| `devtime` | ai-analyst, ai-architect, ai-assistant, ai-designer, ai-developer, harness, kb-enrichment, planner, ui-driver |
| `runtime` | agent-builder, data-privacy, doc-converter, dynamic-classifier, evals-judge, speech-to-text, web-crawler. cee-pii is in this group but needs `services.cee-pii.enabled: true` as well |

The groups are the same as in 5.9.6. The 6.0.0 chart adds designer-user to `core`, harness and ui-driver to `devtime`, and cee-pii and dynamic-classifier to `runtime`. The `base` group is unchanged.

Set all four flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

> [!WARNING]
>
> **Set every group flag explicitly for self-hosted upgrades.** Don't rely on the chart's group defaults. The `devtime` and `runtime` services call the AI base services, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

### New databases and secrets

Compared with the `flowx-ai` Helm chart in 5.9.6, these services need new databases. Create a database only if its service's group is on. designer-user is in `core`, so every installation needs its database:

| Service | Group | Database user | Secret |
| - | - | - | - |
| agent-builder | `runtime` | PostgreSQL `agent_builder` | `flowx-postgres-agent-builder` |
| dynamic-classifier | `runtime` | PostgreSQL `dynamic_classifier` | `flowx-postgres-dynamic-classifier` |
| harness | `devtime` | PostgreSQL `harness` | `flowx-postgres-harness` |
| designer-user | `core` | MongoDB `designer-user` | `mongodb-designer-user-designer-user` |

Each database has the same name as its user. Each secret holds the user's password under the key `password`.

The webhook-gateway also connects to the existing `app-runtime` MongoDB database with the `app-runtime` user.

The `keycloak-flowx-realm-clients` secret needs four new keys, one for each new service account:

| Secret key | Keycloak client |
| - | - |
| `KEYCLOAK_DESIGNER_USER_CLIENT_SECRET` | `flowx-designer-user-sa` |
| `KEYCLOAK_AI_HARNESS_CLIENT_SECRET` | `flowx-ai-harness-sa` |
| `KEYCLOAK_NOTIFICATION_PLUGIN_CLIENT_SECRET` | `flowx-notification-plugin-sa` |
| `KEYCLOAK_DOCUMENT_PLUGIN_CLIENT_SECRET` | `flowx-document-plugin-sa` |

Other chart changes:

* **process-engine** needs read-only access (`s3:GetObject`) to the integration-designer bucket, to download the Kafka payloads that integration-designer stores there. The chart reads the access key ID from `global.flowx.s3.credentials.processEngine.accessKey` (default `flowx-process-engine-accesskey`) and the secret access key from the `flowx-process-engine-s3` secret, key `SecretAccessKey`.
* **dynamic-classifier** stores its data on a 20Gi `ReadWriteOnce` persistent volume claim, `dynamic-classifier-data`, and uses the `Recreate` deployment strategy, so an upgrade stops the old pod before the new one starts.
* **dynamic-classifier** reads an OpenAI API key for its LLM judge from the `dynamic-classifier-openai` secret, key `OPENAI_API_KEY`. The secret is optional: without it, the pod still starts and classification keeps working.
* The chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier. ai-gateway keeps its own.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map | none (required) |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today | `k1` |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index | `PT24H` |

### New object storage bucket: runtime content

Runtime content export and import stores its files in a new shared bucket, `runtime-content-bucket`. Application Manager creates the bucket on first use, Integration Designer writes export files and reads imports there, and the embedder reads and writes Knowledge Base vectors at the paths each request names. Grant all three services access to the bucket.

Browsers upload import files and download export files directly, through presigned URLs that Application Manager signs. By default it signs them with the internal storage endpoint, which only pods can reach, so set `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` to a storage endpoint that browsers can reach.

New variables on application-manager and integration-designer. Set the bucket on both, and the presign settings on application-manager only:

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_RUNTIMECONTENTBUCKET` | Bucket for runtime content export and import files | `runtime-content-bucket` |
| `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` | Storage endpoint used to sign the presigned upload and download URLs. Leave empty to sign with the internal storage endpoint | empty |
| `APPLICATION_FILESTORAGE_S3_PRESIGNREGION` | Region used to sign the presigned URLs | `us-east-1` |

For the full list of buckets, see [Data architecture](/6.x/docs/platform-overview/data-architecture#s3-compatible-object-storage-buckets).

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

New process-engine and audit-core variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

### Changed behavior: nosql-db-runner host restrictions cover MongoDB

The host restriction that relational data sources already had now applies to external MongoDB connections too. The nosql-db-runner checks every address a MongoDB host resolves to, including replica-set members and SRV targets, and rejects the connection if any of them is private. For FlowX Database and Unmanaged MongoDB data sources alike, it also rejects `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter. To match every document, pass `{"_id": {"$exists": true}}`.

nosql-db-runner variables (both already existed for relational data sources):

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SSRFALLOWEDHOSTS` | Hosts or CIDR blocks, separated by commas, that may connect even though they resolve to a private address. Addresses on the local machine or in a link-local range stay blocked | empty |
| `FLOWX_SSRFPROTECTIONENABLED` | Turns the host restriction on or off | `true` |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS`.

### Changed behavior: name placeholders in data-privacy

When data-privacy masks a person's name, the placeholder now carries the gender, for example `<NAME_F_1>` or `<NAME_M_1>`. When the name doesn't show the gender, the placeholder stays `<NAME_1>`. Prompts or scripts that match the old placeholder form need updating.

### Changed behavior: Workspace operations editor role replaced

The upgrade replaces the Workspace operations editor role with the [Workspace corrective actions editor](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix) role. Users and groups that had the old role get the new one automatically and keep access to process instance migration and move token. No action is needed.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

New audit-core variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/6.x/setup-guides/audit-setup-guide#configuring-elasticsearch).

### Changed default: IMAPS certificate verification in email-gateway

The email-gateway now verifies the certificate of every IMAPS server it connects to. A server must present a certificate signed by a trusted authority and matching its host name.

New email-gateway variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS` | Mail hosts that skip certificate verification, separated by spaces or commas. Use `*` to skip it for every host | empty |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Email triggers that read from an IMAP server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`.

### Changed default: AI node retry

AI nodes without retry settings of their own now retry when a dependency is temporarily unavailable, such as an LLM provider outage, a rate limit, or a lost connection. Permanent errors aren't retried, and deep research nodes never retry by default. A node's own retry settings replace the default.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_ENABLED` | Turns the default retry for AI nodes on or off | `true` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_MAXATTEMPTS` | Maximum retry attempts | `10` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_BACKOFFPERIOD` | Wait between attempts, as an ISO-8601 duration | `PT30S` |

### Upgrading from an older patch release

Upgrading from 5.9.5 or earlier? Apply the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries) as well. Two 5.9.6 changes affect the upgrade:

* **Build redeployment retries:** the queue of build deployments waiting for a retry moved from Redis to the application-manager PostgreSQL database, with a new topic, `ai.flowx.build.deployment-failed.v1`. Deployments waiting for a retry in Redis when you upgrade aren't moved to the new queue. Re-publish those builds after the upgrade.
* **advancing-controller management port:** `MANAGEMENT_SECURITY_ENABLED` is no longer read. Actuator endpoints on the management port, including Prometheus, answer without authentication.

> [!WARNING]
>
> Keep the advancing-controller management port, `8081`, off any public ingress.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](/release-notes/overview).


# Android SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/android

Migrate the FlowX Android renderer SDK from 5.9.x to 6.0.0.

## Android SDK migration guide

FlowX.AI 6.0 moves the Android SDK to `compileSdk` 37, Android Gradle plugin 9 and Kotlin 2.4, and aligns the SDK's names with the iOS and web SDKs. Update your build setup first, then the renamed SDK APIs.

### System requirements

* **minSdk = 26** (unchanged)
* **compileSdk = 37**

The SDK library was built using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 9.5.0**
* **[Gradle](https://gradle.org/releases/) 9.8.2**
* **[Kotlin](https://kotlinlang.org/) 2.4.21**

Your container app must build with at least:

* **Android Gradle Plugin 9.1.0**
* **Gradle 9.3.1** (the minimum depends on your Android Gradle Plugin version)
* **Kotlin 2.4**
* **JDK 17**

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Android Core KTX](https://developer.android.com/kotlin/ktx#core) | 1.16.0 | **1.19.1** |
| [Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) | 1.10.1 | **1.13.0** |
| [Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) | 2025.09.01 | **2026.09.00** |
| [Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) | 2.9.1 | **2.10.2** |
| [Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) | 2.9.1 | **2.11.0** |
| [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | 1.10.2 | **1.11.0** |
| [Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) | 1.1.7 | **1.3.0** |
| [Android Security](https://developer.android.com/jetpack/androidx/releases/security) | 1.1.0-beta01 | **1.1.0** |
| [OkHttp BOM](https://square.github.io/okhttp/) | 4.12.0 | **5.5.1** |
| [Retrofit](https://square.github.io/retrofit/) | 2.12.0 | **3.0.0** |
| [Coil BOM](https://coil-kt.github.io/coil/) | 3.4.0 | **3.6.3** |
| [Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) | 4.31.1 | **4.36.2** |
| [Mozilla Rhino](https://github.com/mozilla/rhino) | 1.8.0 | **1.9.2** |
| [Accompanist Permissions](https://google.github.io/accompanist/permissions/) | 0.37.3 | 0.37.3 |
| [Moshi](https://github.com/square/moshi) | 1.15.2 | 1.15.2 |
| [Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) | 2.1.5 | 2.1.5 |

> [!WARNING]
>
> The SDK now depends on **OkHttp 5** and **Retrofit 3**. Gradle resolves your app to these versions even if you declare OkHttp 4 or Retrofit 2, so update any code in your app that uses APIs removed in these major versions. Align your app's versions of these libraries with the SDK's versions to avoid compatibility issues.

### Migration steps

To build and run your container app with the 6.0 SDK, follow these steps in order:

**1. Update the SDK version**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
implementation("ai.flowx.android:sdk:<5.9.x version>") // [!code --]
implementation("ai.flowx.android:sdk:<6.0 version>") // [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Increase the `compileSdk` version to `37`**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileSdk = 35 // [!code --]
    compileSdk = 37 // [!code ++]
}
```

> [!NOTE]
>
> The SDK and its AndroidX, OkHttp and Coil dependencies require `compileSdk` 37. Raising `targetSdk` is not required.

**3. Update the `Android Gradle plugin` version to at least `9.1.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "8.10.0" apply false // [!code --]
    id("com.android.application") version "9.5.0" apply false // [!code ++]
}
```

> [!TIP]
>
> Android Gradle plugin 9 is a major release with breaking build changes. Consult the [Android Gradle plugin 9.0 release notes](https://developer.android.com/build/releases/agp-9-0-0-release-notes).

**4. Update the `Gradle` version**

```properties [rootProject]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.2-bin.zip # [!code ++]
```

> [!NOTE]
>
> Android Gradle plugin 9.1 requires at least Gradle 9.3.1, and 9.5 requires at least Gradle 9.6.0. Check the minimum for your version in the [Android Gradle plugin release notes](https://developer.android.com/build/releases/gradle-plugin).

**5. Remove the `Kotlin Android` plugin**

Android Gradle plugin 9 compiles Kotlin by itself (built-in Kotlin), so the `org.jetbrains.kotlin.android` plugin must be removed:

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code --]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") // [!code --]
}
```

> [!TIP]
>
> Consult the [Migrate to built-in Kotlin](https://developer.android.com/build/migrate-to-built-in-kotlin) guide.

**6. Update the `Kotlin` version to at least `2.4`**

With built-in Kotlin, your app compiles with the version of the Kotlin Gradle plugins you declare, such as the Compose Compiler plugin. The Kotlin version that Android Gradle plugin uses by default is too old to read the SDK's classes. Use the same version for every Kotlin Gradle plugin your project declares, such as Parcelize or Serialization.

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code --]
    id("org.jetbrains.kotlin.plugin.compose") version "2.4.21" apply false // [!code ++]
}
```

> [!WARNING]
>
> With an older Kotlin version, the build fails with an error like: `The binary version of its metadata is 2.4.0, expected version is 2.2.0`.

**7. Make sure core library desugaring is enabled**

The SDK requires core library desugaring. If your app does not enable it yet, add:

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**8. Rename the `imageBaseUrl` and `customHeaders` properties of the `Config` interface**

`imageBaseUrl` is now `assetsBaseUrl`, and `customHeaders` is now `additionalHttpHeaders`:

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
Flowx.getInstance().init(
    context = applicationContext,
    config = object : Config {
        ...
        override val imageBaseUrl = "URL to FlowX CMS Media Library" // [!code --]
        override val assetsBaseUrl = "URL to FlowX CMS Media Library" // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code --]
        override val additionalHttpHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code ++]
        ...
    },
    ...
)
```

> [!NOTE]
>
> The default value of the `locale` property changed from `Locale.getDefault()` to `Locale.forLanguageTag("en-US")`. If your app relies on the device locale for date, number and currency formatting, set it explicitly:
>
> ```kotlin theme={"dark"}
> override val locale: Locale = Locale.getDefault()
> ```

**9. Stop passing `null` to the `setAccessToken` method**

The `setAccessToken` method no longer accepts `null`:

```kotlin theme={"dark"}
fun setAccessToken(accessToken: String?) // [!code --]
fun setAccessToken(accessToken: String) // [!code ++]
```

Remove the calls that clear the token (for example, on logout or after a failed login):

```kotlin theme={"dark"}
Flowx.getInstance().setAccessToken(null) // [!code --]
```

A token can't be cleared once set. When another user logs in, set that user's token. If no token is ever set, the SDK runs in anonymous mode. For details, see the [Authentication](/6.x/sdks/android-renderer#authentication) section of the Android SDK reference.
\[!WARNING] Passing an empty string (`""`) no longer clears the token. The SDK sends it as is and the backend rejects the requests.

**10. Rename the `closeModalFunc` parameter to `onDismissRequested`**

The parameter of the `startProcess` and `continueProcess` methods was renamed. Its lambda now runs in the `ProjectScope` context:

```kotlin theme={"dark"}
Flowx.getInstance().startProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)

Flowx.getInstance().continueProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)
```

> [!TIP]
>
> Replace the deprecated `CloseModalProcessScope` type with `ProjectScope`, as described in the [Replace deprecated APIs](#replace-deprecated-apis) section.

**11. Rename the `imageBaseUrl` parameter of the `changeEnvironment` method (if used)**

```kotlin theme={"dark"}
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code --]
fun changeEnvironment(baseUrl: String, assetsBaseUrl: String, enginePath: String) // [!code ++]
```

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. The parameters are unchanged:

| Deprecated (5.9) | Replacement (6.0) | Available on |
| - | - | - |
| `CloseModalProcessScope` | `ProjectScope` | The `onDismissRequested` lambda of `startProcess` and `continueProcess` |
| `replaceSubstitutionTag` | `getSubstitutionTagContent` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getMediaResourceUrl` | `getMediaItemUrl` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getEnumeration` | `getEnumerationItems` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `executeAction` | `runAction` | `CustomComponentScope` |
| `executeUploadAction` | `runUploadAction` | `CustomComponentScope` |
| `configureUpdateState` | `setUpdateStateEnabled` | `Flowx` |

> [!TIP]
>
> Android Studio offers a **Replace with** quick fix on every deprecated call.

These changes are reflected in an actual implementation as shown below:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope // [!code --]
import ai.flowx.android.sdk.api.ProjectScope // [!code ++]

// close process confirmation alert
@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code --]
private fun ProjectScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code ++]
    ...
    Text(replaceSubstitutionTag("@@close_message")) // [!code --]
    Text(getSubstitutionTagContent("@@close_message")) // [!code ++]
}

// custom component
flowxScope.executeAction(action = it, params = JSONObject()) // [!code --]
flowxScope.runAction(action = it, params = JSONObject()) // [!code ++]

// custom loader
flowxScope.replaceSubstitutionTag(text) // [!code --]
flowxScope.getSubstitutionTagContent(text) // [!code ++]
flowxScope.getMediaResourceUrl(key) // [!code --]
flowxScope.getMediaItemUrl(key) // [!code ++]
```

## Related resources

> [card] [Android SDK reference](/6.x/sdks/android-renderer)
>
> Android renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Angular SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/angular

Migrate the FlowX Angular renderer SDK from 5.9.x to 6.0.0.

## Angular SDK migration guide

6.0 moves the Angular renderer to Angular 22 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new input and function names. The framework upgrade, the custom component input, and the removed `logSink` and `logCategories` inputs need code changes.

### Framework upgrade: Angular 21 → 22

Upgrade your host app **before** you bump the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide) from `21.0` to `22.0`.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Angular CLI and `@angular/*` | \~21 | **\~22** |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |
| TypeScript | ≥ 5.9, \< 6.1 | **≥ 6.0, \< 6.1** |

The FlowX Angular packages declare `@angular/*` ≥ 22.0.0 as peer dependencies, so `npm install` fails on an Angular 21 app.

### FlowX SDK changes

#### Renamed inputs and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` input | `baseUrl` |
| `processApiPath` input | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` input | `assetsBaseUrl` |
| `authToken` input | `accessToken` |
| `withConfig({ customLoader })` | `customLoaderProvider` (same shape) |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers.

```diff theme={"dark"}
 <flx-process-renderer
-  [apiUrl]="baseUrl"
-  [processApiPath]="'onboarding'"
-  [staticAssetsPath]="mediaLibraryUrl"
-  [authToken]="token"
+  [baseUrl]="baseUrl"
+  [enginePath]="'onboarding'"
+  [assetsBaseUrl]="mediaLibraryUrl"
+  [accessToken]="token"
   ...
 />
```

#### Custom components: `data$` → `input` signal

Custom components receive their data through an `input` signal input instead of the `data$` Observable. The process data moves under `input().data`, and actions run through `runAction` and the new `runUploadAction`. Both return an Observable.

| 5.9 | 6.0 |
| - | - |
| `data$` input (Observable) | `input` signal input |
| Data fields read from the top level (`data.<field>`) | `input().data.<field>` |
| `data.actionsFn.<name>(params)` | `input().runAction(name, params?)` |
| None | `input().runUploadAction(name, file, params?)` |

```typescript theme={"dark"}
import { Component, computed, input } from '@angular/core';
import { FlxCustomComponentData } from '@flowx/angular-sdk';

@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
})
export class CustomComponentComponent {
  input = input<FlxCustomComponentData>()
  client = computed(() => this.input()?.data.client)

  submit(file: Blob) {
    this.input()?.runAction('action_one', { amount: 3 }).subscribe();
    this.input()?.runUploadAction('upload_document', file, { side: 'front' }).subscribe();
  }
}
```

#### `logSink` and `logCategories` inputs removed

The `[logSink]` and `[logCategories]` inputs on `<flx-process-renderer>` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- [logSink]="formattedLogger"
- [logCategories]="['rest', 'sse']"
```

```typescript theme={"dark"}
import { formattedLogger, logSink } from '@flowx/core-sdk';

const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] });
```

`@flowx/angular-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Inputs removed or deprecated without replacement

| Input | Status in 6.0 |
| - | - |
| `legacyHttpVersion` | Deprecated, no replacement. Still honored. |
| `debugLogs` | Removed. It never had any effect. Use `logSink()` from `@flowx/core-sdk`. |

#### Behavior changes

* `baseUrl` is required on the process, UI Flow, chat and task management renderers, and `assetsBaseUrl` on the process, UI Flow and chat renderers. Without them, the renderer throws ``[FlowX] `baseUrl` is required.`` (or `` `assetsBaseUrl` ``) at start. The template compiler doesn't report a missing value.
* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [Angular SDK reference](/6.x/sdks/angular-renderer)
>
> Angular renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Helm chart
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart

Upgrade a FlowX.AI installation on the flowx-ai Helm chart from 5.9.x to 6.0.0.

> [!NOTE]
>
> FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

This page covers the Helm side of an upgrade from FlowX.AI 5.9.x to 6.0.0 for an installation that already runs on the `flowx-ai` Helm chart. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list every change in detail. This page puts the ones that need action in the order you do them.

> [!NOTE]
>
> If you still run the per-service charts or the `ai-platform` umbrella chart, move to the `flowx-ai` chart on 5.9.x first, as described in [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart). That migration recreates every workload. Doing it separately keeps the 6.0.0 upgrade a single `helm upgrade` of one release.

## Before you begin

* Read the [FlowX.AI 6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) and [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0).
* Get pull access to the `flowx-ai` chart at the chart version for 6.0.0. The chart version is the platform release.
* Take a backup of PostgreSQL, MongoDB, the object store, and the Qdrant collections right before the upgrade.
* If you run a container app with a FlowX renderer SDK, plan its upgrade with the [renderer SDK guides](./migration-overview#renderer-sdk-migration).

The commands on this page read the namespace from `NS`:

```bash theme={"dark"}
export NS={your-flowx-namespace}
```

## Update your values

**1. Set every group flag explicitly**

Don't rely on the chart's group defaults. Set all four group flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

`base` is the AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and Qdrant. The `devtime` and `runtime` services call it, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

For example, to install the core, base, and runtime services:

```yaml theme={"dark"}
groups:
  core:
    enabled: true
  base:
    enabled: true
  devtime:
    enabled: false
  runtime:
    enabled: true
```

See [AI service groups in the Helm chart](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#ai-service-groups-in-the-helm-chart) for the services in each group, and [How do the switches combine?](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#how-do-the-switches-combine) for how group and service flags combine.

**2. Provision databases and secrets for the services you turn on**

In 6.0.0, these services need their own database users and secrets: agent-builder, dynamic-classifier, and harness in PostgreSQL, and designer-user in MongoDB. Create them before the upgrade for every service your group flags turn on. designer-user is in the `core` group, so it always needs its database.

The `keycloak-flowx-realm-clients` secret needs four new client secret keys, whatever your group flags. authorization-system reads all four at startup and, when it has Keycloak admin access (the default), creates the matching service-account clients with those secrets. If a key is missing, its database migration fails and authorization-system doesn't start. Without Keycloak admin access, create the four clients in Keycloak yourself.

See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the user, secret, key, and client names.

**3. Grant process-engine read access to the integration-designer bucket**

process-engine now reads Kafka payloads that integration-designer stores in its bucket. Give the process-engine credentials `s3:GetObject` on that bucket. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the secret names.

**4. Set a bucket name for dynamic-classifier**

If you turn on dynamic-classifier, set its bucket under `services.dynamic-classifier.component.s3.applicationFileStorage.bucketName`. The chart sets no bucket names, as described in [Migrate S3 buckets](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#migrate-s3-buckets). dynamic-classifier also stores data on a 20Gi `ReadWriteOnce` volume, so your cluster needs a storage class that can provide one.

Unlike the Qdrant volumes, this claim is part of the Helm release. `helm uninstall`, or deleting the Argo CD Application with cascading deletion, deletes it, and with a `Delete` reclaim policy its data too.

**5. Move callers off the removed admin Ingress routes**

If you route with Kubernetes Ingress, the chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier, and the upgrade deletes the existing ones. ai-gateway keeps its own. Platform services and frontends don't use these routes. If anything outside the cluster calls one of these paths on the admin host, such as `/speech-to-text`, move it to the service's in-cluster address before you upgrade.

Installations that use the Gateway API aren't affected.

**6. Allow private MongoDB hosts**

nosql-db-runner now applies its host restriction to external MongoDB connections. Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS` on nosql-db-runner. See [nosql-db-runner host restrictions](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).

**7. Trust your IMAP servers' certificates**

email-gateway now verifies the certificate of every IMAPS server it connects to. Email triggers that read from a server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`. See [IMAPS certificate verification](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway).

**8. Keep the management port private**

Upgrading from 5.9.5 or earlier? Since 5.9.6, advancing-controller no longer reads `MANAGEMENT_SECURITY_ENABLED`, and the actuator endpoints on its management port, `8081`, including Prometheus, answer without authentication. Check that no public Ingress or Gateway route exposes that port. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).

**9. Set the personal-data encryption key**

In 6.0.0, integration-designer needs `FLOWX_PII_ENCRYPTION_MASTER_KEY` for the Mask Personal Data and Restore Personal Data nodes. The variable has no default and the chart doesn't set it, so without it those nodes fail when a workflow runs them. Store a strong random value in a secret under the key `FLOWX_PII_ENCRYPTION_MASTER_KEY`, and load the secret into integration-designer:

```yaml theme={"dark"}
services:
  integration-designer:
    extraEnvVarsSecret: {your-pii-secret-name}
```

Keep the value identical on every pod and stable over time: changing it invalidates every in-flight placeholder map. See [Personal-data encryption master key](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-required-secret-personal-data-encryption-master-key).

**10. Choose how Elasticsearch replicates new indices**

In 6.0.0, process-engine and audit-core create new indices with the Elasticsearch `auto_expand_replicas` setting `0-1`, which overrides `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS`. On a cluster with two or more data nodes, the replica roughly doubles the disk space these indices use. To keep a fixed replica count instead, turn auto-expansion off on both services:

```yaml theme={"dark"}
services:
  process-engine:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
  audit-core:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
```

See [Elasticsearch replica auto-expansion](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-elasticsearch-replica-auto-expansion).

**11. Create the new Kafka topics**

New capabilities since 5.9.x depend on new Kafka topics. Create them before you upgrade. The 6.0.0 [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics) list every topic added since 5.9.6. Upgrading from 5.9.5 or earlier? Also create `ai.flowx.build.deployment-failed.v1`, added in 5.9.6. If your cluster uses ACLs, also give the new clients of three existing topics access, as listed in the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics).

If the chart creates your topics, add the new names to the list under `global.flowx.kafka.topics.topics`. The chart creates topics only when `global.flowx.kafka.topics.enabled` is `true`, as Strimzi `KafkaTopic` resources with 3 partitions and 3 replicas unless you set other values under `global.flowx.kafka.topics.defaults`:

```yaml theme={"dark"}
global:
  flowx:
    kafka:
      topics:
        enabled: true
        topics:
          - ai.flowx.build.deployment-failed.v1
```

## Render and compare

Render the 6.0.0 chart with your updated values before you upgrade, and compare it with what runs today:

```bash theme={"dark"}
helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml
```

Check that the rendered Deployments are the services you expect. A missing AI base service, or an AI runtime service you didn't plan for, means a group flag isn't set. The render fails if your values still contain top-level `devtime` or `runtime` keys, or service keys outside `services`. See [Render and compare](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#render-and-compare) for commands that compare environment variables per Deployment.

Using a mirrored or air-gapped registry? List the images the render references, mirror them, and point the chart at your registry with `global.imageRegistry`, as described in [Container images and registry](/6.x/setup-guides/setup-guides-overview#container-images-and-registry):

```bash theme={"dark"}
grep -E '^\s+image:' rendered.yaml | sort -u
```

## Upgrade

Run `helm upgrade` on your `flowx-ai` release with the 6.0.0 chart version and your updated values:

```bash theme={"dark"}
helm upgrade {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml
```

dynamic-classifier uses the `Recreate` deployment strategy, so its old pod stops before the new one starts.

## After the upgrade

* **Upgrading from 5.9.5 or earlier: re-publish builds that were waiting for a retry.** The retry queue for failed build deployments moves from Redis to PostgreSQL, and deployments waiting in Redis are not moved. 5.9.6 already uses the PostgreSQL queue. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).
* **Check component versions.** In FlowX.AI Designer, go to **Platform Status** and compare the versions with the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#component-versions).
* **Check files from before the upgrade.** Open a process attachment, a media library asset, and a knowledge base document, and confirm they load. A bucket-not-found error in the logs points at a bucket name that didn't carry over.
* **Update name placeholders.** data-privacy now masks names with gendered placeholders, such as `<NAME_F_1>`. Update prompts or scripts that match the old form. See [Name placeholders in data-privacy](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy).
* **Expect a new workspace role name.** Users and groups with the Workspace operations editor role now have the Workspace corrective actions editor role, and keep access to process instance migration and move token. See [Workspace operations editor role replaced](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-workspace-operations-editor-role-replaced).

## Related resources

> [card] [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)
>
> Component versions and every deployment-level change in 6.0.0

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single chart


# iOS SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/ios

Migrate the FlowX iOS renderer SDK from 5.9.x to 6.0.0.

## iOS SDK migration guide

FlowX.AI 6.0 aligns the names of five iOS SDK APIs with the Android and web SDKs. The build requirements and library dependencies are unchanged, and the 5.9 names still compile, so your app builds with the 6.0 SDK after you update the pod version. Replace the deprecated names afterwards.

### System requirements

| Requirement | 5.9.x | 6.0 |
| - | - | - |
| Minimum iOS | iOS 15 | iOS 15 |
| Swift | 5.9 | 5.9 |

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Alamofire](https://github.com/Alamofire/Alamofire) | `~> 5.9.0` | `~> 5.9.0` |
| [SDWebImageSwiftUI](https://github.com/SDWebImage/SDWebImageSwiftUI) | 3.0.3 | 3.0.3 |
| [SDWebImageSVGCoder](https://github.com/SDWebImage/SDWebImageSVGCoder) | `~> 1.7.0` | `~> 1.7.0` |

### Migration steps

**1. Update the SDK version**

```ruby Podfile theme={"dark"}
pod 'FlowXRenderer', '<5.9.x version>' # [!code --]
pod 'FlowXRenderer', '<6.0 version>' # [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Replace the deprecated APIs**

Replace the 5.9 names with the 6.0 names listed in the [Replace deprecated APIs](#replace-deprecated-apis) section. The parameters, types and behavior are unchanged.

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. `imageBaseURL` is a property of `FXConfig`; the others are methods of `FlowX.sharedInstance`:

| Deprecated (5.9) | Replacement (6.0) |
| - | - |
| `imageBaseURL` | `assetsBaseURL` |
| `updateAuthorization(token:)` | `setAccessToken(token:)` |
| `getTag(withKey:)` | `getSubstitutionTagContent(key:)` |
| `getEnumeration(name:parentName:)` | `getEnumerationItems(name:parentName:)`, async and completion versions |
| `continueExistingProcess(uuid:name:…)` | `continueProcess(uuid:name:…)`, all three versions |

> [!TIP]
>
> Xcode shows a deprecation warning on every deprecated call, with a **Fix-it** that replaces it with the new name.

These changes are reflected in an actual implementation as shown below:

```swift theme={"dark"}
// configuration
FXConfig.sharedInstance.configure { config in
    config.imageBaseURL = myImageBaseURL // [!code --]
    config.assetsBaseURL = myAssetsBaseURL // [!code ++]
}

// authorization token changes
FlowX.sharedInstance.updateAuthorization(token: accessToken) // [!code --]
FlowX.sharedInstance.setAccessToken(token: accessToken) // [!code ++]

// substitution tags
FlowX.sharedInstance.getTag(withKey: "@@close_message") // [!code --]
FlowX.sharedInstance.getSubstitutionTagContent(key: "@@close_message") // [!code ++]

// enumerations
let items = await FlowX.sharedInstance.getEnumeration(name: "cities", parentName: "countries") // [!code --]
let items = await FlowX.sharedInstance.getEnumerationItems(name: "cities", parentName: "countries") // [!code ++]

// resuming a process
FlowX.sharedInstance.continueExistingProcess(uuid: uuid, // [!code --]
FlowX.sharedInstance.continueProcess(uuid: uuid, // [!code ++]
                                     name: processName,
                                     navigationController: processNavigationController,
                                     isModal: true)
```

## Related resources

> [card] [iOS SDK reference](/6.x/sdks/ios-renderer)
>
> iOS renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Overview
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview

Migration guide for upgrading container apps and the flowx-ai Helm chart from FlowX.AI 5.9.x to 6.0.0

FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

> [!WARNING]
>
> A FlowX.AI 6.0.0 renderer SDK can need a newer framework version in your container app. Check the guide for your SDK, and upgrade the host app before you bump the FlowX SDK.

## Who is affected

Teams that run a container app with a FlowX renderer SDK (Angular, React, iOS, Android, or React Native) and move it to FlowX.AI 6.0.0. See [Renderer SDK migration](#renderer-sdk-migration).

Teams that run FlowX.AI on the `flowx-ai` Helm chart and upgrade it from 5.9.x to 6.0.0. See [Helm chart upgrade](#helm-chart-upgrade).

Teams with business rules, reusable functions, or workflow scripts that still run on the GraalVM script engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

## What's changing

An upgrade to 6.0.0 touches up to three areas, depending on what you run:

* **Helm chart:** set every AI service group flag explicitly, and create databases and secrets for the new services that need them. See [Helm chart upgrade](#helm-chart-upgrade).
* **GraalVM script engine:** deprecated. Scripts on GraalVM keep running after this upgrade, now with the same time limit as the native engine, and 6.1.x is the last release family that supports the engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).
* **Renderer SDKs:** container apps upgrade the FlowX renderer SDK, and the host framework where the SDK needs it. See [Renderer SDK migration](#renderer-sdk-migration).

## Migration process

Follow these steps in order, and skip the ones for areas you don't run.

**1. Check your starting point**

Upgrade to 6.0.0 from FlowX.AI 5.9.x on the `flowx-ai` Helm chart. If you still run the per-service charts or the `ai-platform` umbrella chart, first [migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart) on 5.9.x, as a separate change.

**2. Read the release notes and deployment guidelines**

The [release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) list what changes in 6.0.0. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list the component versions, environment variables, and other configuration changes. The [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog) lists every feature change since 5.9.x, including the 5.10 to 5.13 feature releases.

**3. Prepare the infrastructure**

Create what the 6.0.0 services need before the upgrade window: new PostgreSQL and MongoDB database users and their secrets, four new keys in the `keycloak-flowx-realm-clients` secret, read access for process-engine to the integration-designer bucket, and storage for a 20Gi `ReadWriteOnce` volume if you turn on dynamic-classifier. Create the new Kafka topics, or list them for the chart to create. Also set the personal-data encryption key for integration-designer, choose how Elasticsearch replicates new indices, and allow the private MongoDB hosts and IMAP servers that existing connections use. [Before you upgrade a self-hosted installation](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#before-you-upgrade-a-self-hosted-installation) is the full checklist, and [Update your values](./helm-chart#update-your-values) walks through each item.

**4. Check GraalVM scripts and plan the move off GraalVM**

Scripts on GraalVM keep running, but from 6.0.0 they stop at the same time limit as the native engine. Before the upgrade, check the scripts that can run longer than the limit, or raise it. Then plan their move to the native engine, as described in [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

**5. Back up**

Take the backups listed in [Before you begin](./helm-chart#before-you-begin) right before the upgrade.

**6. Upgrade the Helm release**

Update your values and upgrade the release, as described in [Helm chart](./helm-chart).

**7. Upgrade your container apps**

For each container app, upgrade the host framework first if the SDK needs it, then the FlowX renderer SDK. See [Renderer SDK migration](#renderer-sdk-migration). Container apps on a 5.9.x renderer SDK keep running against a 6.0.0 backend, but screens can render incorrectly wherever 6.0.0 changed behavior. Release the upgraded apps in the same window as the Helm upgrade. For iOS and Android apps, end users who don't install the app update stay on the 5.9.x SDK, so plan how you move them to the new version.

## Helm chart upgrade

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single `flowx-ai` chart

> [card] [Helm chart](./helm-chart)
>
> Upgrade an installation on the `flowx-ai` Helm chart from 5.9.x to 6.0.0

## Move scripts off the GraalVM engine

The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine for JavaScript and Python. Scripts that run on GraalVM keep running after the upgrade to 6.0.0, but they now stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0, a GraalVM script had no time limit. Before you upgrade, check the GraalVM scripts that can run longer than these limits, or raise the limits, as described in [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits). Then plan the move to the native engine.

**1. Find the scripts that run on GraalVM**

Business rules and reusable functions created before the move to the native engine run on GraalVM unless you switched them. The engine selector in each rule's script editor shows the engine it runs on. Workflow scripts run on GraalVM only if `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`.

**2. Test each script on the native engine**

The two engines don't always write the same output. Follow the step-by-step list in [Port a script from GraalVM to native](/6.x/docs/building-blocks/supported-scripts#port-a-script-from-graalvm-to-native), check the [common pitfalls](/6.x/docs/building-blocks/supported-scripts#common-pitfalls), and search scripts for Python imports the native engine blocks, such as `os` and `subprocess`, JavaScript `require(...)`, `process`, or `global`, and calls into Java classes such as `Java.type(...)`. The native engine supports none of these.

**3. Switch to the native engine**

Switch business rules [per rule](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule). Move a reusable function and the rules that call it together: a function written for GraalVM fails when a rule on the native engine calls it. For workflow scripts, remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer`. The default is `native`.

## Renderer SDK migration

> [card] [Angular SDK](./angular)
>
> Migrate the Angular renderer SDK to 6.0.0

> [card] [React SDK](./react)
>
> Migrate the React renderer SDK to 6.0.0

> [card] [iOS SDK](./ios)
>
> Migrate the iOS renderer SDK to 6.0.0

> [card] [Android SDK](./android)
>
> Migrate the Android renderer SDK to 6.0.0

> [card] [React Native SDK](./react-native)
>
> Migrate the React Native renderer SDK to 6.0.0


# React SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react

Migrate the FlowX React renderer SDK from 5.9.x to 6.0.0.

## React SDK migration guide

6.0 moves the React renderer to Node 26 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new prop and function names. The `logSink` and `logCategories` renderer props are removed and need a code change.

### Framework requirements

React stays on 19. Upgrade Node in your build and CI environments.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| React | 19 | 19 |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |

### FlowX SDK changes

#### Renamed props and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` prop | `baseUrl` |
| `processApiPath` prop | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` prop | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customLoader` prop | `customLoaderProvider` (same shape) |
| UI Flow `appInfo.selectedProcessResourceId` | `resourceId` |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `useEnumeration(name, parentName?)` | `useEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers. `customLoaderProvider` applies to the process and UI Flow renderers.

```diff theme={"dark"}
 <FlxProcessRenderer
-  apiUrl={baseUrl}
-  processApiPath="onboarding"
-  staticAssetsPath={mediaLibraryUrl}
-  authToken={token}
+  baseUrl={baseUrl}
+  enginePath="onboarding"
+  assetsBaseUrl={mediaLibraryUrl}
+  accessToken={token}
   ...
 />
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, file, params?)` to upload a file through an upload action. `params` are sent as extra form fields beside the file.

```typescript theme={"dark"}
input.runAction('action_one', { amount: 3 })
input.runUploadAction('upload_document', file, { side: 'front' })
```

`FlxCustomComponentData` is now generic (`FlxCustomComponentData<TFile = Blob>`) and requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### `logSink` and `logCategories` props removed

The `logSink` and `logCategories` props on `FlxProcessRenderer` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- <FlxProcessRenderer logSink={formattedLogger} logCategories={['rest', 'sse']} ... />
+ import { formattedLogger, logSink } from '@flowx/core-sdk'
+
+ const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] })
```

`@flowx/react-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Props removed or deprecated without replacement

| Prop | Status in 6.0 |
| - | - |
| `legacyHttpVersion` on the process renderer | Deprecated, no replacement. Still honored. |
| `legacyHttpVersion` on the UI Flow renderer | Removed. It never had any effect. |
| `customHeaders` | Removed. It never had any effect. |
| `updateStateEnabled` | Removed. It never had any effect. |
| `isAnonymousMode` | Removed. It never had any effect. |
| `fw` | Removed. It never had any effect. |

Delete the removed props from your process and UI Flow renderer props.

#### Behavior changes

* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [React SDK reference](/6.x/sdks/react-renderer)
>
> React renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# React Native SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react-native

Migrate the FlowX React Native renderer SDK from 5.9.x to 6.0.0.

## React Native SDK migration guide

6.0 moves the validated React Native target to Expo SDK 57 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new configuration and prop names. The Android Material 3 date picker opt-in is removed.

### Prerequisites and version range

The peer dependency floors are unchanged: `react-native` ≥ 0.83.0 and `react` ≥ 19.2.0. The validated target moves up one Expo SDK.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Validated target | Expo SDK 56, React Native 0.85.3 | **Expo SDK 57, React Native 0.86.3** |
| React | 19.2.3 (Expo SDK 56 pin) | 19.2.3 (Expo SDK 57 pin) |
| `react-native-blob-util` | ^0.24.9 | **^0.25.1** |
| `@react-native-community/datetimepicker` | Required peer | **No longer used** |

For an Expo project, align the project to Expo SDK 57, then reinstall the FlowX packages with `npx expo install`:

```bash theme={"dark"}
npx expo install expo@^57.0.0 --fix
```

For the full install command and the Expo SDK 57 reference versions, see the [React Native SDK reference](/6.x/sdks/react-native-renderer).

### FlowX SDK changes

#### Renamed configuration options and props

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `FlxConfig.baseURL`, `apiUrl` prop | `baseUrl` |
| `processApiPath` | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customHeaders` | `additionalHttpHeaders` |
| `customLoader` | `customLoaderProvider` (same shape) |
| `customStepperHeader` | `customStepperHeaderProvider` (same component) |
| `configure({ locale, language })` | `FlowX.changeLocaleSettings(locale?, language?)` |
| `configure({ updateStateEnabled })` | `FlowX.setUpdateStateEnabled(enabled)` |
| `setAccessToken(token: string)` | `setAccessToken(token?: string \| null)`: `null`, `undefined` or `''` switches to anonymous access |
| `processUuid` prop | `processInstanceUuid` |
| `onClose(name?)` | `onDismissRequested(name?)` (same argument) |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl`, `enginePath` and `assetsBaseUrl` apply to `FlowX.configure` and to the process, UI Flow and chat renderers. `onDismissRequested` applies to `startProcess`, `continueProcess`, `startUiFlow` and the process and UI Flow renderers.

In 5.9 the content helpers came only from `@flowx/core-sdk/rn`. `@flowx/react-native-sdk` now exports them too, under their new names only (`getEnumerationItems`, `getMediaItemUrl`, `getSubstitutionTagContent`).

```diff theme={"dark"}
 FlowX.configure({
-  baseURL: 'https://api.example.com',
-  processApiPath: 'onboarding',
-  staticAssetsPath: 'https://media.example.com',
-  customHeaders: { 'x-tenant': 'acme' },
-  language: 'en',
-  locale: 'en-US',
+  baseUrl: 'https://api.example.com',
+  enginePath: 'onboarding',
+  assetsBaseUrl: 'https://media.example.com',
+  additionalHttpHeaders: { 'x-tenant': 'acme' },
   organizationId,
 })
+FlowX.changeLocaleSettings('en-US', 'en')
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, { uri, name, type }, params?)` to upload a file through an upload action.

`FlxCustomComponentData` requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### Android Material 3 date picker removed

The opt-in Material 3 date picker for `FlxDatePicker` on Android is removed, along with the `@react-native-community/datetimepicker` peer dependency.

* Remove `material3` from any `configureFlxUiToolkit` call.
* The `@react-native-community/datetimepicker` package is no longer needed by FlowX. Uninstall it if nothing else in your app uses it.
* Keep the `@flowx/react-native-ui-toolkit` Expo config plugin registered. It no longer changes `AppTheme` or sets `extra.flxUiToolkit.material3`. It now adds `fontScale` to the main activity's `android:configChanges` and declares the microphone permissions used by chat voice input. Run `npx expo prebuild` again after the upgrade.

#### Behavior changes

* A session with no usable access token now starts as anonymous instead of failing. In 5.9, a token that was `null`, `undefined` (never set) or an empty string (`''`) made the start throw `Call FlowX.setAccessToken(...) before starting a process.` In 6.0 all three values start an anonymous session, and a backend that requires a token answers `401`. If your token fetch can return `null`, `undefined` or `''`, check the value before you start a process; otherwise the failure only shows up later as a `401`.
* Error and warning messages name `baseUrl` and `assetsBaseUrl` instead of `baseURL` and `staticAssetsPath`. Update any host code that matches on their text.

## Related resources

> [card] [React Native SDK reference](/6.x/sdks/react-native-renderer)
>
> React Native renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# FlowX.AI 6.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026

What's new in FlowX.AI 6.0: the Developer Agentic Harness builds story by story, plus bulk process-instance migration, scheduled workflows, and certificates.

[FlowX.AI 6.0.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/hero-6.0.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 6.0 is a feature release, live on FlowX.AI SaaS. Self-hosted installations usually wait for the next LTS release family, and can also upgrade to 6.0.0 now: see [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

> [!WARNING]
>
> **Check your existing apps:** 6.0.0 changes how AI node prompts and retries, substitution tags, FlowX Database writes, masked names, IMAPS email triggers, evaluations, 5.1.x exports, and GraalVM scripts behave. See the [upgrade actions](/release-notes/v6.x/5.9-to-6.0-changelog) for what to check in each. Coming from 5.9.x? On the same page, also check the **Changed** entries for 5.10 to 5.13.

> [accordion] What changed since 5.13.0
>
> | 5.13.0 | 6.0.0 |
> | - | - |
> | The harness built the whole approved plan in one run | **Story-by-story delivery**: build one slice of the app, test it, then continue |
> | Changes to the app were described in words | **Comment mode**: select a component in the running app and say what should change |
> | The Command Center and the AI buttons in each editor opened standalone AI agents | **One agent rail**: **⌘K** or the header toggle opens the harness, which uses those agents internally |
> | A workflow started only when a process or caller started it | **Scheduled workflows**: date or cycle schedules on the Start node |
> | TLS was configured with keystores, truststores, and a skip switch | **Trust and Identity**: choose what the host is checked against, and whether to present a client certificate |
> | The Issues Console checked resources only | **Version checks**: entry points, theme, and library dependencies |
> | Only version exports sent notifications | **Import and export notifications**: version imports, build exports, and build imports notify you too |
> | A substitution tag had to be a property's whole value | **Tags inside any text**: `${tag:key}` next to static text and process data |
> | An AI node failed as soon as its AI service or provider couldn't be reached | **AI node retries**: on by default, up to 10 times, 30 seconds apart |
> | The chat message was appended to the end of an AI node's prompt | **Chat message in prompts**: reference `${userMessage}` in **Context** where the agent should answer it |
> | Evaluations grouped test cases into datasets and checked outputs with Code evaluators | **Test cases and asserts**: tagged test cases per workflow, checked with asserts and LLM evaluators |
> | The embedding model was locked once a Knowledge Base held content | **Re-embedding**: change **Containing Personal Information** later and the content is re-embedded |
> | Exporting rows to a file needed a Script node | **Generate Tabular File node**: a CSV or XLSX file from an array of rows |
> | A FlowX Database index couldn't reject duplicate values | **Unique indexes**: **Enforce unique values** on one attribute or a compound key |
> | A sensitive configuration value was shown in the Designer after saving | **Sensitive values stay hidden**: the Designer shows `********` in its place |
> | GraalVM was a supported script engine | **GraalVM deprecated**: 6.1.x is the last release family that supports it |

### **Coming from 5.9.x**

Releases 5.10 to 5.13 shipped to SaaS first. An installation that moves from 5.9.x to 6.0.0 gets their features too, including the [corrective actions](#corrective-actions-on-running-instances) below. The highlights:

> [card] New data sources
>
> [PostgreSQL](/6.x/docs/platform-deep-dive/integrations/postgresql-database) and [Db2](/6.x/docs/platform-deep-dive/integrations/db2-database) databases, and [SOAP services](/6.x/docs/platform-deep-dive/integrations/soap-system) imported from a WSDL.

> [card] Document nodes in workflows
>
> [Fill a template](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) into a PDF or DOCX, [combine](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) or [split](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) PDFs, and [parse](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support) spreadsheets, CSV, XML, and JSON.

> [card] Multi-instance and triggered workflows
>
> Run [one subworkflow per array element](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) in parallel, and start a workflow from an [email or webhook trigger](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).

> [card] Workflow Instances page
>
> [Every workflow run in the project](/6.x/docs/projects/runtime/workflow-instances), filterable by status, date, and origin.

> [card] Branches and the Issues panel
>
> [Merge into any branch](/6.x/docs/projects/managing-applications/versioning#managing-branches), archive or delete branches, and [see validation findings](/6.x/docs/projects/managing-applications/checking-for-issues) in one panel.

> [card] Workflows as agent tools
>
> A Custom Agent node [calls FlowX workflows as tools](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run), each with a hint for when to use it.

Full list: the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog), and the [5.10](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026), [5.11](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026), [5.12](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026), and [5.13](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) release notes.

***

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > The Developer Agentic Harness is the Designer's AI agent: it surveys your app, plans the change, and builds it on its own branch.
> >
> > **Before 6.0:** the harness ran an approved plan as a single run, and a conversation stayed tied to the app and branch where you started it. **Now:** a plan can split the work into stories, each a slice of the app you can try on its own, delivered one story at a time. You can point at a component in the running app to ask for a change. Your conversations follow you across the Designer.
> >
> > Each story says how to test it and what the agent needs from you, so you check one working slice before the next one starts. Comment mode turns the running UI flow or process into the brief: select a component, say what should change, and the comment lands in the conversation with the component attached. A conversation writes to the project and branch set by the first change you confirm, wherever you navigate after that, and the agent asks before it reads beyond that target.
> >
> > > [!NOTE]
> > >
> > > **Removed:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors, such as **Generate** on the data model and the sparkle buttons in business rules, reusable functions, and Script nodes. Open the agent rail instead: press **⌘K** (**Ctrl+K** on Windows and Linux) or select the sparkle toggle in the header. The harness still uses those agents internally for focused generation work. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness#what-the-agent-can-see-and-change).
> >
> > <video>
> >   <track label="English" />
> > </video>
> >
> > See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
>
> > [tab] Key Features
> >
> > > [card] [Story-by-story delivery](/6.x/ai-platform/developer-agentic-harness#how-does-a-plan-with-stories-run)
> > >
> > > Implement the next story, test it with the steps the story gives, then continue with one story or all that remain.
> >
> > > [card] [Comment on the running app](/6.x/ai-platform/developer-agentic-harness#how-do-i-comment-on-the-running-app)
> > >
> > > Select **Comment** in the header, pick a component in the running UI flow or process, and say what should change.
> >
> > > [card] [Conversations that follow you](/6.x/ai-platform/developer-agentic-harness#sessions)
> > >
> > > Every conversation you have in the organization, searchable. Each keeps writing to the project and branch of its first confirmed change, wherever you navigate.
> >
> > > [card] [Asks before reading more](/6.x/ai-platform/developer-agentic-harness#what-happens-when-the-agent-asks-to-read-another-project)
> > >
> > > Read-only access to another project needs **Allow for this conversation**, and you can revoke it from the rail.
> >
> > > [card] [Attach your material](/6.x/ai-platform/developer-agentic-harness#attach-files-to-a-conversation)
> > >
> > > Give the agent PDF and DOCX briefs, screenshots, or BPMN diagrams to plan and build from.
> >
> > > [card] [Delete with a plan export](/6.x/ai-platform/developer-agentic-harness#delete-a-conversation)
> > >
> > > Deleting a conversation keeps its commits on the branch and offers **Export plan** for what wasn't run.
> >
> > > [card] [Entry points, handovers, and repairs](/6.x/ai-platform/developer-agentic-harness#entry-points-handovers-timeouts-and-repairs)
> > >
> > > The agent suggests an entry point and asks again before serving, adds handover buttons, times out workflow waits, and proposes a repair when a step fails, a limited number of times per step.
>
> SaaS

### **Corrective actions on running instances**

> [card] Corrective actions on running instances
>
> > [tab] Overview
> >
> > Corrective actions shipped in the 5.12 and 5.13 feature releases. They fix running process instances in place, without restarting them, from **Runtime** → **Runtime Control** → **Corrective Actions**.
> >
> > **Bulk process-instance migration** moves a filtered set of running instances from one build to another in one run, so a fix made in a newer build reaches instances already in flight. **Move token** takes the active token off the node the instances are stuck on and places it on another node of the same process, and the instances stay on their build.
> >
> > The **Workspace corrective actions editor** role grants both. It replaces the Workspace operations editor role, and the upgrade moves users and groups that had the old role to the new one.
> >
> > See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances) and [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
>
> > [tab] Key Features
> >
> > > [card] [Build to build, in bulk](/6.x/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > Pick the source build, the target build, and the instances to move, then review the eligible count and map any node missing from the target build before you start.
> >
> > > [card] [Move token](/6.x/docs/projects/runtime/active-process/move-token)
> > >
> > > Resume stuck instances from another node of the same process, on one or many instances at once.
> >
> > > [card] [Dedicated role](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix)
> > >
> > > Grant corrective actions without handing out workspace admin rights.
> >
> > > [card] [Notified when done](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification)
> > >
> > > The notification center reports when a bulk migration finishes.
>
> SaaS

### **New Designer header**

> [card] New Designer header
>
> **Before 6.0:** the branch selector, the version state, and **Commit Changes** sat in the project's top bar. **Now:** the header holds the project name, the **Config** / **Runtime** switch (**Config** to edit a version, **Runtime** for builds and their settings), the **Build with AI** and **Comment** toggles, and **Run project**, which starts the version's entry point. Branching, the current version, and **Commit Changes** move to a version block at the start of the footer on Config pages.
>
> ![Designer project on a Config page: the header shows the project name, the Config and Runtime switch, the Build with AI toggle, and Run project; the footer starts with the version block showing the main branch, the version name, and Start New Version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/designer-header-6-0.png)
>
> The Designer also opens the workspace you used last, and **Organization settings** is in the avatar menu. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
>
> SaaS

### **AI node retries**

> [card] AI node retries
>
> **Before 6.0:** an AI node failed as soon as its AI service or LLM provider couldn't be reached. **Now:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when the service is unreachable, the provider is unavailable or rate-limits the request, or the connection fails. Timeouts aren't retried by default, because the node may already have called its tools.
>
> Toggle **Allow Retry** on in the node's **Settings** to set your own count, interval, and exponential backoff. After the last retry, the workflow continues down the node's failure exit if one is connected. With **Allow Retry** on, the workflow run logs show each attempt on its own line.  See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
>
> SaaS

### **Knowledge Base re-embedding and entry lifecycle**

> [card] Knowledge Base re-embedding and entry lifecycle
>
> **Before 6.0:** the embedding model was locked once a Knowledge Base held content. **Now:** turning **Containing Personal Information** on or off later re-embeds the existing content with the new model. Search keeps using the current embedding while it runs, and content changes are locked until it finishes. If some documents fail, the Knowledge Base stays on its previous model and the header says how many weren't re-embedded.
>
> Entries also have their own lifecycle: **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested) and [disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
>
> SaaS

### **Chat message in AI node prompts**

> [card] Chat message in AI node prompts
>
> > [!WARNING]
> >
> > **Behavior change.** The chat message is no longer appended to the end of an AI node's prompt automatically. In chat-driven workflows, reference `${userMessage}` in the node's **Context** wherever the agent should answer the user's message.
>
> The message still reaches the model inside the input data when **Use only referenced values as input** is off. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
>
> SaaS

### **Evaluations: test cases replace datasets**

> [card] Evaluations: test cases replace datasets
>
> **Before 6.0:** test cases lived in datasets, and the Code evaluators checked outputs for an exact, JSON, or Levenshtein match. **Now:** each workflow has its own test cases, grouped by tags. Each case carries its checks: asserts for **equals** and **equals as JSON**, and LLM evaluators with a pass threshold. An experiment runs the test cases you select. See [Evaluations](/6.x/ai-platform/evaluations).
>
> > [!WARNING]
> >
> > **Behavior change.** The upgrade converts each dataset's test cases and keeps the dataset name as a tag, but adds no checks. An experiment skips a case with no enabled check, so add an assert or evaluator to each converted case before you run it. The Code evaluators are removed: use the **equals** assert in place of **Exact match**, and **equals as JSON** in place of **JSON match**. **Levenshtein** has no replacement. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
>
> SaaS

### **Scheduled workflows**

> [card] Scheduled workflows
>
> > [tab] Overview
> >
> > **Before 6.0:** an integration workflow started only when a process, a UI flow, or another caller started it. **Now:** add schedules to the workflow's **Start** node and it starts by itself at each fire time.
> >
> > Schedules fire once on a date or repeatedly on an ISO or cron cycle, and the dialog previews the next fire times in your local time zone. Saving a schedule or publishing a build never turns it on: activate it in **Runtime** → **Runtime Settings** → **Schedules**.
> >
> > See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
>
> > [tab] Key Features
> >
> > > [card] Date or cycle
> > >
> > > Fire once at a date and time, or repeatedly with an ISO or cron expression built from guided fields.
> >
> > > [card] Up to 50 per workflow
> > >
> > > Each schedule has a name that is unique on its workflow. Schedules are available on Output Focused workflows, which process structured input and output.
> >
> > > [card] Explicit activation
> > >
> > > A schedule fires only after you activate it on the **Schedules** page, for a workflow in the project's active build.
> >
> > > [card] Next fire times
> > >
> > > Check the previewed fire times before you save.
>
> SaaS

### **Certificates: trust and identity**

> [card] Certificates: trust and identity
>
> > [tab] Overview
> >
> > **Before 6.0:** a REST data source combined keystore, truststore, and a skip-verification switch in one TLS setup. **Now:** the **Certificates** panel has two independent parts. **Trust** decides what the host's certificate is checked against: **System CAs** (the default), a **Custom CA**, or **None (insecure)**. **Identity** is the client certificate FlowX presents for mutual TLS, turned on with **Present a certificate**.
> >
> > The same panel is available on File Storage data sources. Existing certificate settings are converted to the new model automatically.
> >
> > See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates) for when to use each option.
>
> > [tab] Key Features
> >
> > > [card] Trust per data source
> > >
> > > Changing trust on one data source leaves every other call verified as before.
> >
> > > [card] Mutual TLS when asked
> > >
> > > Present a client certificate only to hosts that require one.
> >
> > > [card] [File Storage too](/6.x/docs/platform-deep-dive/integrations/file-storage#certificates)
> > >
> > > S3-compatible storage uses the same Trust and Identity settings.
> >
> > > [card] Insecure, by name
> > >
> > > **None (insecure)** is labeled as such and accepted only on REST and File Storage data sources.
>
> SaaS

### **Generate Tabular File node**

> [card] Generate Tabular File node
>
> A new node under **Tools** in the workflow palette turns a workflow variable that holds an array of rows into a CSV or XLSX file, stored as a document linked to the workflow run. A workflow can now produce an export without a Script node. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
>
> SaaS

### **FlowX Database unique indexes**

> [card] FlowX Database unique indexes
>
> Toggle **Enforce unique values** when you add an index to reject documents that repeat a value already stored, on one attribute or on a compound key, with an option to exempt documents that leave the key empty. Existing duplicates are reported when you run **Apply Indexes**, before the index is created. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
>
> SaaS

### **Issues Console version checks**

> [card] Issues Console version checks
>
> **Before 6.0:** an Issues Console check, which validates the resources in a project version, covered processes, UI flows, and integration workflows. **Now:** it also checks the version itself: missing, broken, or mismatched entry points, a theme that isn't in the workspace, library builds that are missing directly or transitively, and dependencies the version doesn't use. Selecting a finding opens the version settings or the **Dependencies** page, where you fix it. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
>
> SaaS

### **Import and export notifications**

> [card] Import and export notifications
>
> The notification center now covers version imports and build exports and imports, alongside version exports and process instance migrations. Each operation notifies you when it starts and replaces that entry with its result: ready to download, imported, needs review with a conflict or excluded-resource count, failed, or timed out. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
>
> SaaS

### **Resource documentation**

> [card] Resource documentation
>
> Open **Documentation** from a resource's menu to give it a short description and longer Markdown documentation, written and previewed in the same window. Media Library assets in a project library get a description too, used as the image's alt text in the asset preview. Knowledge base stores, navigation areas, and user tasks in the process navigation panel have **Documentation** in their menus too. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
>
> SaaS

### **Sensitive values stay hidden**

> [card] Sensitive values stay hidden
>
> After you save a `value` configuration parameter with **Sensitive** on, the Designer shows `********` in place of the value in the parameters list, overrides, build details and lists, and the merge view. The real value is still used at runtime, and editing other fields keeps it. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
>
> SaaS

### **Substitution tags inside any text**

> [card] Substitution tags inside any text
>
> > [tab] Overview
> >
> > **Before 6.0:** a substitution tag resolved only when it was the whole value of a property, so `@@greeting ${firstName}` rendered as empty text. **Now:** write `${tag:key}` anywhere in a component's text, next to static text and process data, and the renderer fills in every tag: `${tag:greeting}, ${firstName}!` renders as "Hello, John!".
> >
> > The upgrade rewrites whole-value `@@key` references to `${tag:key}` in processes, UI flows, and reusable templates, so existing screens render as before. `@@key` keeps working as a whole value.
> >
> > See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).
>
> > [tab] Key Features
> >
> > > [card] Tags, text, and data together
> > >
> > > Use several tags and process data placeholders in one label, placeholder, message, validator message, or option label.
> >
> > > [card] Existing references converted
> > >
> > > Whole-value `@@key` references become `${tag:key}`. Option values and the default of choice components stay `@@key`.
> >
> > > [card] Task Manager columns
> > >
> > > A column value of exactly `${tag:key}` shows, filters, and sorts like `@@key`.
> >
> > > [card] Import from and export for 5.9
> > >
> > > Importing from 5.9 converts `@@key` forward. Exporting for 5.9 converts whole-value tags back to `@@key`.
>
> SaaS

### **GraalVM script engine deprecated**

> [card] GraalVM script engine deprecated
>
> The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports it, for every JavaScript and Python script: business rules, reusable functions, workflow Script nodes, and the rest. Scripts that run on GraalVM keep working in 6.0.0. Move them to the native engine, the default since 5.9.0, before support ends. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).
>
> **Time limits on GraalVM too:** scripts that run on GraalVM now stop at the same per-language time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default, set on the process engine and Integration Designer with `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` and `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`. Before 6.0.0, a GraalVM script had no time limit. A script that runs past its limit is stopped and fails with an error saying it did not finish within its time limit. Before you upgrade, check GraalVM scripts that can run longer than these limits, or raise the limits. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
>
> All Deployments

### **Smaller improvements**

> [card] Smaller improvements
>
> **Auto-arrange on both canvases:** select **Auto-arrange** on the workflow canvas, or **Arrange** on the process canvas, to see a tidied layout in the **Layout preview** bar before anything moves. Compare it with the current layout, then **Apply** or **Cancel**. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).&#x20;
>
> **Timers in local time:** timer nodes now use the same editor as workflow schedules. Dates and times you pick are in your local time and saved in UTC, one control switches between **Guided**, **Expression**, and **Process variable** entry, and cycle timers preview their next fires. Timers saved with the earlier date pickers can look shifted by your UTC offset in the panel, but they still fire at their stored time. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).&#x20;
>
> **Longer branch names:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).&#x20;
>
> **Organization branding:** a **Branding** page under **Organization settings** > **Customization** sets one brand for the organization: name, logos, legal and social links, container app colors and header, and the sender, signature, and text of the invite, verify email, and reset password emails, with a preview of each. Login page and email branding are available on FlowX SaaS only. See [Organization branding](/6.x/docs/saas/organization-branding).&#x20;
>
> **Typed dates in the Datepicker:** turn on **Allow manual input** to let users type a date in the pattern of the project's default locale instead of picking it. Web only, and not available while **Legacy component** is on.&#x20;
>
> **Data mapping creates data types:** type a new attribute path such as `client.address.street`, and saving the mapping creates the data types it names. Until then, the mapper marks them as not yet added to the data model. Required rows show an asterisk, and mapping an object onto a primitive field shows an error.&#x20;
>
> **Removed fields stay removed:** when a node's output sets a field to `null`, the field is removed from the workflow data and later steps no longer restore it with a `null` value. If a condition checks for `null`, make it handle a missing field too.&#x20;
>
> **Keys with dots stay whole:** a data key that contains a dot, such as `cash|31.12.2025`, now stays one key when a workflow saves its data. Before, the key was split into nested objects and later nodes could not read it.&#x20;
>
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, and Kafka topics, see [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0). To upgrade the Helm chart or a renderer SDK, follow [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).


# Deployment guidelines v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/deployment-guidelines-v4.6.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.0 FlowX.AI release, you cannot import old process definitions or resources into the new platform from older versions .

## Component versions

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.0.2** | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.3** | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.1.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.0** | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.0.3** | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.0.3** | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | **4.1.3** | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | **7.0.3** | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.0** | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.0** | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.1.12** | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.0** | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.1** | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.0.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.3** | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.9** | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.10** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.9** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.3** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.24** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.5.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.0 | Keycloak | 22.x |
| 4.6.0 | Kafka | 3.2.x |
| 4.6.0 | PostgreSQL | 16.2.x |
| 4.6.0 | MongoDB | 7.0.x |
| 4.6.0 | Redis | 7.2.x |
| 4.6.0 | Elasticsearch | 7.17.x |
| 4.6.0 | Oracle Database | 21C/ 21-XE |
| 4.6.0 | Angular (Web SDK) | 19.x |
| 4.6.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

## New microservices - setup guides

> [card] [Application-manager](/4.7.x/setup-guides/application-manager)

> [card] [Runtime-manager](/4.7.x/setup-guides/runtime-manager)

> [card] [Integration Designer](/4.7.x/setup-guides/integration-designer-setup)

> [card] [Data-sync job](/4.7.x/setup-guides/data-sync)

## New access rights and roles

> [card] [Integration Designer access rights](/4.7.x/setup-guides/access-management/configuring-access-rights-for-integration-designer)

> [card] [Application Manager access rights](/4.7.x/setup-guides/access-management/app-manager-access-rights)

## Updated access rights and roles

> [card] [Task Manager access rights](/4.7.x/setup-guides/plugins-access-rights/configuring-access-rights-for-task-management)
>
> Added new roles for **manage-views**.

## New service accounts

> [card] [Runtime manager service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#runtime-manager-service-account)

> [card] [Integration Designer service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#integration-designer-service-account)


# Deployment changes for v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x

This document outlines the configuration and infrastructure changes introduced from v4.1.x to v4.6.0 for deploying the FlowX.AI platform.

## CMS Setup

### MongoDB configuration

In version 4.6.0, the CMS setup includes a more comprehensive MongoDB configuration, especially for runtime data handling:

* **Runtime MongoDB Instance**: A dedicated MongoDB instance for managing runtime data.
  * **New Environment Variables**:
    * `RUNTIME_DB_USERNAME`: Username for runtime MongoDB access.
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: Connection URI for the runtime MongoDB instance.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`). Default is `mongodb`.
  * **Transaction Settings for Mongock Library**:
    * `MONGOCK_TRANSACTIONENABLED`: Controls MongoDB transaction support with Mongock, defaulting to `false` due to compatibility concerns with MongoDB 5.

### Private storage configuration

Private CMS to securely store uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints. This CMS will support AI services and workflows while maintaining strict access controls.

> [!NOTE]
>
> Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from project builds as they aren't needed at runtime.

* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL`: This environment variable specifies the URL of the S3 server used for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME`: This environment variable specifies the name of the S3 bucket dedicated to private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET`: This environment variable indicates whether the private S3 bucket should be created if it does not already exist. It can be set to true or false.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY`: This environment variable holds the access key used to authenticate to the S3 server for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY`: This environment variable holds the secret key used to authenticate to the S3 server for private file storage.

> [card] [CMS setup guide](/4.7.x/setup-guides/cms-setup)

***

## Admin setup

### MongoDB configuration

Version 4.6.0 introduces a new MongoDB setup in the Admin service for managing data model information:

* **New MongoDB Data Model Configuration**:
  * **Environment Variables**:
    * `SPRING_DATA_MONGODB_URI`: URI for connecting to the MongoDB data model instance.
    * `DB_USERNAME`: Set to `data-model` for data model access.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`).

***

## Engine setup

### MongoDB configuration

The Engine configuration now includes additional setup for a runtime MongoDB instance to manage runtime builds:

* **Runtime MongoDB for Engine**:
  * **New Environment Variables**:
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: URI for connecting to the runtime MongoDB.
    * `DB_USERNAME`: Set to `app-runtime` for runtime data access.


# Configuration and migration guide
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/process-configuration

This guide outlines changes in process and UI configuration from v4.1.x to 4.6.0 version.

## Projects

The **Projects** feature in FlowX AI v4.6.0 is a new structure that organizes all dependencies and resources required for a project into a single deployable view. This enhancement simplifies configuration, deployment, and maintenance by layering projects on top of processes, offering a centralized workspace that encapsulates everything needed for project execution.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)

Several key configuration changes impact how resources and dependencies are managed, deployed, and maintained. This guide provides a breakdown of the configuration changes, automatic migration processes, and manual steps required to ensure a smooth transition.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)

***

### Consolidated resource management

* **Change**: All resources that were previously managed individually within processes are now grouped within Projects. This includes content management elements, integrations, themes, task configurations, and permissions.
* **Impact**: Resources like **enumerations**, **substitution tags**, and **generic parameters** are now managed within Projects, allowing centralized configuration and version control.
* **Migration**: All process-related resources will be migrated automatically into a **default project**, ensuring continuity of functionality in the new framework. After migration, you should verify that all critical resources are correctly configured within this default project.

> [card] [What are resources?](/4.7.x/docs/projects/resources)

### Enhanced version control and dependency management

* **Impact**: Projects support **dependency management** through **Libraries** and enforce version-controlled resources. Setting up a project now requires careful dependency management and versioning to prevent unintended updates.
* **Benefit**: Allows for modular, reusable resources and stable deployments across projects, reducing resource duplication and enhancing project compatibility.

### Migration checklist

To ensure a smooth transition, complete the following steps:

1. **Verify Process Migration**: Confirm that all existing process definitions have been correctly migrated into the default project.
2. **Set Configuration Parameter Overrides**: Post-deployment, adjust environment-specific Configuration Parameters in the default project.
3. **Update Task Views**: Replace the global "All Tasks" feature with project-specific Views in each project.
4. **Transfer Processes and Dependencies Manually**: If moving a process from the default project to another project, manually transfer associated resources and re-check dependencies.

***

## Generic parameters migration

* **Overview**: In version 4.6.0, global generic parameters (from versions prior to 4.6.0) have been migrated to project-level as Configuration Parameters, consolidating parameter management within specific projects for improved organization and control.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/Screenshot%202024-11-06%20at%2019.04.49.png)

* **Migration**: All generic parameters will be automatically migrated to Configuration Parameters section under a default project.
* **Business Rules Unaffected**: There is no impact on existing business rules; they will continue to function as before without requiring updates.
* **Process Export Considerations**: If you export a process from one project to another, ensure that you also transfer the associated configuration parameters. This step is crucial to maintain process functionality and consistency across projects.
* **Important Note**: Only values of generic parameters associated with the specific environment, or where `env = null` (displayed as "all" in the interface in versions prior to 4.6.0), will be migrated. You must ensure that you have correctly set the values for generic parameters, paying attention to environment values (which are case-sensitive), and export these generic parameters before migration to avoid any potential data loss.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.39.29.png)

* **Post-Deployment Step**: After the first deployment to an upper environment, you will need to create configuration parameter overrides with the specific values required for that environment. This ensures that all environment-specific configurations are accurately maintained and applied across different deployment stages.

> [!TIP]
>
> To set configuration parameter overrides, navigate to **Your App -> Runtime -> Configuration Parameters Overrides**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.42.06.png)

***

## Source systems migration

* **Change**: Source systems have not been migrated automatically and need to be manually recreated.
* **New Location**: In v4.6.0, source systems have been moved under Integration Designer.
* Manual Migration Required:
  1. Navigate to Integration Designer.
  2. Recreate each source system manually with the same code as in the original configuration.
  3. Ensure the "Enable enumeration value mapping" checkbox is enabled.
* **Impact**: Failure to manually migrate source systems may result in broken integrations and missing data mappings.

**v4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2009.53.30.png)

**\< v.4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2010.09.12.png)

## Task management

* "All Tasks" as a View: The global "All Tasks" feature is no longer standalone and will now function as a View in a project.

**v4.6.0:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

**v4.1.x:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/all_tasks.png)

***

## General

Before starting the migration, complete the following steps:

1. **Merge All Feature Branches**: Ensure all feature branches for processes are merged into the latest version on the main branch.
2. **Remove Unnecessary Resources**: Delete any test processes or resources that are no longer needed.
3. **Export Generic Parameters**: Export generic parameters as a backup to ensure they migrate accurately to project-specific Configuration Parameters.

### Migration steps

During migration, resources will be transferred into a single **default project** with one committed version.

* **Process Definitions**: Only the last committed process version on the main branch will migrate. If no committed version exists, the latest WIP version will be used.
* **Enumerations, Substitution Tags, and Task Manager**: These resources will be migrated to the default project.
* **Generic Parameters**: Migrated as **Configuration Parameters** within the default project, covering only values where `env = null` or that match the platform’s environment setting.
* **Languages**: Language settings (available languages and default) will be moved to project settings. Languages remain globally available.

### Resources excluded from migration

Some resources will remain globally available or are deprecated:

* **Themes**
* **Fonts**
* **Global Media Library** (for media used in themes)
* **Out of Office (Task Manager)**
* **Integration Management** (will not be available in v4.6.0)

***

## Datepicker Migration

In version 4.6.0, significant updates have been introduced to the **Datepicker** component to ensure compatibility with ISO 8601 date formats and enhanced handling of date attributes within the **Data Model**. This migration affects both newly created and existing processes.

### Key changes

1. **Introduction of Date Types**:
   * **Standard Date**: Stores and displays date values in ISO 8601 format, respecting the project's locale and timezone settings.
   * **Legacy Date**: Retains previous formatting to ensure compatibility with existing business rules and processes.

2. **Properties Updates**:
   * The **Datepicker** now supports dependent properties such as `minDate`, `maxDate`, and `defaultValue`. These properties:
     * Follow the formatting rules of the selected date type (Standard or Legacy).
     * Ensure that dynamic date values pulled from the **Data Model** are displayed correctly.

3. **Backward Compatibility**:
   * **Existing Processes**: All migrated processes with legacy Datepicker components will default to `Legacy Date` type. This preserves the original formatting and ensures no disruption in business rules or workflows.
   * **New Processes**: Newly created processes will default to `Standard Date` type, saving values in ISO 8601 format.

***

### Migration process

1. **Legacy Datepickers**:

   * Automatically flagged during migration.
   * Continue to work with existing business rules.
   * Require manual review for future updates to transition to the **Standard Date** format.

2. **Business Rules Updates**:
   * Legacy Datepickers may require manual adjustments if associated business rules reference hardcoded date formats.
   * Ensure that any dynamic dates used in business rules are compatible with the ISO 8601 standard.

3. **Standard Datepickers**:
   * All new Datepicker components save date values directly in ISO 8601 format.
   * Fully compatible with updated **Data Model** attributes, allowing seamless integration with external systems, adaptors, and reporting plugins.

### Considerations

* **Default Values**:
  * For **Standard Datepickers**, the `defaultValue` must be in ISO 8601 format.
  * Dynamic defaults can also be set using **Data Model** attributes or process data.
* **Data Model Integration**:
  * All external and internal date attributes, including those used by adaptors or business rules, must be explicitly defined in the **Data Model**.
* **UI Designer Overrides**:
  * Overrides can be applied to display dates differently for specific UI elements, ensuring flexibility for localized formatting.

### Recommendations for transition

* **Existing Processes**:
  * Leave Datepicker components in `Legacy` mode unless business rules and workflows are updated to support ISO 8601.
* **New Processes**:
  * Use `Standard Date` to ensure future compatibility and alignment with ISO 8601 formatting.
* **Documentation**:
  * Review and update all timer expressions, adaptors, and external data feeds to use ISO 8601 format for consistency.

***

## Updates to expression evaluation

**What Changed:**

* A fix was implemented in the web expression evaluator regarding how string values are handled during process value replacement.
* Previously, when evaluating dynamic and computed expressions, string variables required manual insertion of double quotes (`""`) because the system did not automatically add them.
* With the recent fix, the system now **automatically adds the necessary quotes** for string replacements.

**Impact:**

* **Existing Expressions:** If your current dynamic or computed expressions include manually added quotes around string values, these might now result in redundant quotes or incorrect string formatting.
* **Behavioral Shift:** The automatic quote addition alters how string values are processed, which might affect outputs if the expressions were structured with the expectation of manual quotes.

**Action Required:**

1. **Review Your Expressions:** Check any dynamic and computed expressions in your processes that currently include manual double quotes around string values.
2. **Modify as Needed:** Remove unnecessary double quotes where the system now handles them automatically to prevent duplicate quoting or formatting issues.

***

## Export/import enumerations (CSV)

In the transition from version 4.1.x to 4.6.0, the following columns have been removed from the enum CSV export format:

* description.application
* description.draft
* contentValue.childContentDescription.application
* contentValue.childContentDescription.draft
* contentValue.childContentDescription.type

Existing CSV export/import processes should be updated to remove references to these columns to ensure compatibility with the 4.6.0 release.

***

## Post-migration recommendations

For complex projects with multiple use cases, **do not use the default project for ongoing development or production builds**. Instead:

1. **Create Branches within the Default Project**: Organize and streamline resources by creating branches. This enables a lightweight build focused on production.
2. **Split the Default Project into Smaller Projects**: Use the import/export feature to separate the default project into individual projects by use case.
   * **Note**: When importing processes into a new project, resource references may need to be manually reconfigured.

***


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/renderers

This guide assists in migrating from FlowX v4.1.x to v4.6.0.

## Android SDK migration guide

### Initialization config changes

A new configuration parameter named `locale` was added to improve formatting the dates, numbers and currencies.

When the SDK initialization happens through the `FlowxSdkApi.getInstance().init(...)` method, the argument must be included inside the `config: SdkConfig` parameter value:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().init(
    ...
    config = SdkConfig(
        baseUrl = "URL to FlowX backend",
        imageBaseUrl = "URL to FlowX CMS Media Library",
        enginePath = "some_path",
        language = "en",
        locale = Locale.getDefault(), // e.g. Locale("en", "US"), Locale("fr", "CA")
        validators = mapOf("exact_25_in_length" to { it.length == 25 }),
        enableLog = false,
    ),
    ...
)
```

### Changes when starting a Flowx process

Two new parameters were added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The id of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun startProcess(
    projectId: String,
    processName: String,
    params: JSONObject = JSONObject(),
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes when resuming a Flowx process

One new parameter was added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the continued process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes regarding the implementation of Custom Components

The support for classical **[Android View](https://developer.android.com/reference/android/view/View)** system has been dropped.\

A Custom Component can now be implemented only by using the **[Compose](https://developer.android.com/compose)** UI system.

This means that the `CustomViewComponent` is now ignored in the internals of the SDK and has been marked as `@Deprecated` and will be completely removed in the next release.

> [!NOTE]
>
> There is no immediate need to update any of the existing components.

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```kotlin theme={"dark"}
fun changeLocaleSettings(locale: Locale, language: String)
```

### Library dependencies updates

* **[Kotlin](https://kotlinlang.org/)**: 1.9.22 **↗** **1.9.24**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping)**: 2024.02.00 **↗** **2024.06.00**
* **[Compose Compiler](https://developer.android.com/jetpack/androidx/releases/compose-compiler)**: 1.5.9 **↗** **1.5.14**
* **[Gson](https://github.com/google/gson)**: 2.10.1 **↗** **2.11.0**

***

## iOS SDK migration guide

### Initialization config changes

A new configuration parameter, named `locale` was added to improve formatting the dates, numbers and currencies.

The locale needs to be set on the `FXConfig.sharedInstance.configure` method

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    config.locale = "en-US"
    ...
}
```

### Changes when starting a process

Two new parameters were added on the 3 available start process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The uuid string of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func startProcess(projectId: String, 
                  name: String, 
                  params: [String : Any]?, 
                  isModal: Bool = false, 
                  showLoader: Bool = false, 
                  completion: ((UIViewController?) -> Void)?, 
                  onProcessEnded: (() -> Void)? = nil)
```

### Changes when resuming a Flowx process

One new parameter was added on the 3 available continue process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func continueExistingProcess(uuid: String, 
                             name: String, 
                             isModal: Bool = false, 
                             completion: ((UIViewController?) -> Void)? = nil, 
                             onProcessEnded: (() -> Void)? = nil)
```

### Updated FXDataSource protocol

A new method has been added to the `FXDataSource` protocol. Update conformance to protocol by adding the implementation of the new func.

```swift theme={"dark"}
func newProcessStarted(processInstanceUuid: String) {
    
}
```

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```swift theme={"dark"}
func changeLocaleSettings(locale: String?, language: String?)
```

***

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated and will use the latest versions Angular (version 19), thus all container apps that want to use the new SDKs should first update the Angular version of the container apps.

In the following we cover the migration guide for a container app from Angular v17 to v19 and the new SDKs.

**1. Remove old packages and their explicit dependencies (required dependency packages for new sdks are bundled in the libraries so we don't need)**

* remove `material-moment-adapter` unless it is used in custom components (usually together with material datepicker) and also the `moment` package (unless used elsewhere in the project )

```bash theme={"dark"}
npm uninstall @angular/material-moment-adapter
npm uninstall moment
```

* remove old FlowX SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/ui-sdk @flowx/ui-theme @flowx/ui-toolkit 
```

* in `angular.json` remove references to old stylesheets:

```bash theme={"dark"}
"./node_modules/@flowx/ui-sdk/src/assets/scss/style.scss"
"./node_modules/paperflow-web-components/src/assets/scss"
"./node_modules/@flowx/ui-sdk/src/assets/scss"
```

* remove old FlowX SDKs explicit dependencies. Please check before removing that packages are not used in the container app or custom components.

```bash theme={"dark"}
npm uninstall date-fns event-source-polyfill inputmask ng2-pdfjs-viewer vanillajs-datepicker @ngneat/input-mask deepmerge-ts marked-mangle
```

* remove deprecated `Angular Flex` library (the new sdks don't use it anymore and the package has been deprecated by the Angular team) unless it is not used in container app or custom components

```bash theme={"dark"}
npm uninstall @angular/flex-layout
```

**2. Update container app to Angular 18**

* Make sure to have the Angular CLI installed at version 18 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@18
```

* Run the Angular update for version 18

```bash theme={"dark"}
ng update @angular/core@18 @angular/cli@18
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@18
```

or, if the container app uses Angular Material, run:

```bash theme={"dark"}
ng update @angular/material@18
```

* Optionally, if your project uses other angular packages (ex. `NgRx`) please run migrations to v18 for each of them before proceeding. You can find details on the libraries documentation pages.

* Angular has changed the default build path in the `dist` folder, it now uses a `browser` folder for the build output. To place the output of the build command directly in the `dist/[APP_NAME]` folder, add the following change in `angular.json`:

```json theme={"dark"}
{
  ...
  "architect": {
    ...
    "build": {
      ...
      "options": {
        ...
        "outputPath": {
          "base": "dist/flowx-demo-app",
          "browser": "" <-- add this line
        },
      }
    }
  }
}

```

**3. Update container app to Angular 19**

* Make sure to have the Angular CLI installed at version 19 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Run the Angular update for version 19

```bash theme={"dark"}
ng update @angular/core@19 @angular/cli@19
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@19
```

or, if the container app uses Angular material, run:

```bash theme={"dark"}
ng update @angular/material@19
```

* Optionally, if your project uses other Angular packages (ex. `NgRx`) please run migrations to v19 for each of them before proceeding. You can find details on the libraries documentation pages.

* Also, it is recommended that you update the `target` and `module` settings in the `tsconfig.json` file to the new version, although be advised that this might require additional changes in the codebase due to new compilation errors that might arise.

```json theme={"dark"}
{
  ...
  "compilerOptions": {
      ...
      "target": "ES2022",
      "module": "ES2022"
  }
}
```

**4. Install the new FlowX SDK packages**

**Adding overrides for libraries that have a dependency on Angular version \< 19**

For some libraries, the required angular version might not be up to date or compatible with the new Angular version. In this case, you can add an override in the `package.json` file to force the library to use the new Angular version.

* For example, the `ng2-pdfjs-viewer` library has a dependency on Angular version 18 and will not work with the installed Angular version 19. To force the library to use the new Angular version, add the following override in the `package.json` file:

```json theme={"dark"}
{
  ...
  "overrides": {
    "ng2-pdfjs-viewer": {
      "@angular/common": "^19.0.0",
      "@angular/core": "^19.0.0",
      "ng-packagr": "^19.0.0"
    }
  }
}
```

**Install new packages**:

> [!WARNING]
>
> **ACTION REQUIRED**: Update to the latest version 4.6 to ensure optimal performance and compatibility.

```bash theme={"dark"}
npm install @flowx/core-sdk@5.63.0 @flowx/core-theme@5.63.0 @flowx/angular-sdk@5.63.0 @flowx/angular-theme@5.63.0 @flowx/angular-ui-toolkit@5.62.1 
```

* Install a type dependency for the SSE library:

```bash theme={"dark"}
npm install --save-dev @types/event-source-polyfill
```

* run through all the migration steps in the [New SDK Api changes](#new-sdk-api-changes) section below.

> [!NOTE]
>
> Each migration requires a 'clean' repository state. Make sure to commit all changes before starting the next migration step.

> [!TIP]
>
> After each Angular update it is recommended you restart your editor or TS Server, to use the new TS version since some import errors might appear.

### New SDK API changes

#### Renderer SDK component usage

In the Angular SDK, the `<flx-process-renderer>` component has two new parameters have been introduced: `projectInfo` and `locale`. These additions help support localization and project-specific configurations.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectInfo` | Object containing an `projectId` key, which identifies the project of the process to be started | `{projectId: string}` | Mandatory |
| `locale` | Provides region-specific settings for localization. | `string` | Mandatory |

Add the definitions for these properties in the class file of the component that uses the process renderer component:

```typescript theme={"dark"}
projectInfo = { projectId: 'your-project-id' },
locale = 'en-US',
```

Use these parameters in the template as inputs for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  ...
  [projectInfo]="projectInfo"
  [locale]="locale"
/>
```

#### API changes

Process Renderer:

| Category | Old Approach | New Approach |
| - | - | - |
| **Process Renderer** | `FlxProcessModule.forRoot({...})` | `FlxProcessModule.withConfig({...})` |

#### Import path updates

| Category | Old Approach | New Approach |
| - | - | - |
| **Import Paths** | `@flowx/ui-sdk` | `@flowx/angular-sdk` (or, in some cases `@flowx/core-sdk`) |
| | `@flowx/ui-theme` | `@flowx/angular-theme` |
| | `@flowx/ui-toolkit` | `@flowx/angular-ui-toolkit` |
| **Process Module** | `import {FlxProcessModule} from '@flowx/ui-sdk';` | `import {FlxProcessModule} from @flowx/angular-sdk` |
| **Localization Module** | `import {FlxLocalizationModule} from '@flowx/ui-sdk';`  Include in module imports | `import {FlxLocalizePipe} from '@flowx/angular-sdk';` Remove from module imports |
| **Task Management** | `import {FlxTaskManagementModule} from '@flowx/ui-sdk';` | `import {FlxTasksManagementComponent} from '@flowx/angular-sdk';` |
| **Client Store Interface** | `import {ClientStoreInterface} from '@flowx/ui-sdk';` | `import {ClientStoreInterface} from '@flowx/core-sdk';` |

> [!NOTE]
>
> You can also remove the `FlxLocalizationModule` from any `imports` arrays in modules, and import the `FlxLocalizePipe` instead

### Icon module update

The `withExtraIconSet` method has been replaced with `provideExtraIconSet`, which should now be used in the providers array.

```typescript theme={"dark"}
@NgModule({
  imports: [
    IconModule,  // Import the IconModule
  ],
  providers: [
    // Use provideExtraIconSet to add your custom icon set
    provideExtraIconSet({
      customIcon1: 'path/to/custom-icon1.svg',
      customIcon2: 'path/to/custom-icon2.svg',
      // Add more icons as needed
    })
  ]
})
export class AppModule {}
```

### Custom Interceptors

The new FlowX SDKs do not depend on Angular's `HttpClient` to make API calls, so existing interceptors must be adapted to a new format, for Request Interceptors (eg. custom headers) and Response Interceptors (eg. error handling)

For an overview of implementation details, please refer to the respective sections of the renderer documentation for the new API changes.

> [card] [Custom Interceptors](/4.7.x/sdks/angular-renderer#custom-interceptors)


# FlowX.AI 4.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025

Welcome, FlowX fam! The 4.6.0 update is here, and it’s packed with features designed to save you time, boost efficiency, and maybe even make you chuckle. Let’s dive into the details, feature by glorious feature. 🎉

## **What's new?** 🆕

### Projects: Order out of chaos

The new Project concept introduces a streamlined approach to managing and deploying complex projects within FlowX. By grouping all related resources—such as processes, enumerations, integrations, and assets—into a single, organized workspace, projects provide a cohesive view for efficient development and deployment.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

💼 **Key Benefits**:

* **Unified Workspace**: Group related processes, integrations, assets, and configurations into one tidy space.
* **Version Control**: Manage multiple builds and versions effortlessly. Rollbacks? No sweat.
* **Resource Sharing**: Reuse processes and configurations across projects like a boss.

> [!TIP]
>
> **Why you’ll love it**: It’s like going from a messy desk to an organized digital office.

🎥 **Quick Demo**: (Who needs text when you have visuals?)

<video />

> [card] [Projects](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

#### 🛠 Config vs Build Mode

**Config Mode**: Tinker, tweak, and perfect.

* Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's the workspace where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

**Build Mode**: Lock it, load it, deploy it.

* Build mode is the stage where the configurations you've set up are packaged into a deployable form. This is the runtime-ready version of your project, containing everything needed for it to function in a production environment. A build includes a snapshot of the project’s state at a given point, ensuring stability and predictability when deployed.

<video />

> [card] [Configuration](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

> [card] [Runtime](/4.7.x/docs/projects/runtime/builds)
>
> For more details, check out this section

***

### Integration Designer: Connect like a pro

It’s like a dating app for your systems: drag, drop, connect, and let the workflows flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)

API integration just got easier! Integration Designer simplifies connecting FlowX with external systems using REST APIs.

✨ **The magic of it**:

* **Drag-and-Drop Interface**: Map data, define workflows, and configure endpoints like a breeze.
* **Flexible Authorization**: Use Service Tokens, Bearer tokens, or go authentication-free.
* **Error Management**: Built-in tools ensure your integrations don’t ghost you.

> [!TIP]
>
> **Fun Fact**: Integration Designer doesn’t just test APIs (we love you, [Postman](https://www.postman.com/)❤️). It automates workflows, saving you tons of time.

> [card] [Integration Designer](/4.7.x/docs/platform-deep-dive/integrations/integration-designer)
>
> For more details, check out this section

***

### Merge Conflicts 2.0: Merge without the drama

Merging branches? We've overhauled the process to make it faster, smarter, and far less painful.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)

🧩 **What’s New**:

* **Advanced Conflict Detection**: Pinpoint issues by resource type (Processes, Enumerations, Media, etc.).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)

* **Resource-Level Resolution**: Resolve conflicts directly in the UI with:
  * JSON comparisons (color-coded for clarity!).
  * Navigation tools to jump between differences.
  * Progress tracking for reviewed items.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

> [!TIP]
>
> **Pro Tip**: Use the “Merge Anyway” option if you need to override unresolved conflicts (but use it wisely!).

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)

> [card] [Merge conflicts](/4.7.x/docs/projects/managing-applications/versioning#managing-conflicts)

***

### AI Agents: Smart, adaptable, always ready to help

FlowX AI Agents bring automation to your fingertips, powered by a flexible, LLM-agnostic core.

🤖 **Why It’s Cool**:

* Works with both open-source and private language models.
* Secure, on-premise deployments available.
* Automates business processes and interactions.

🎥 Check out a quick demo:

<video />

Stay tuned for more.

***

### Localization and Internationalization

FlowX is now more global-friendly with enhanced localization features.

> [card] Flexible Date, Time, Number, and Unit Formatting
>
> Enhanced formatting options for dates, times, numbers, and currencies with support for various international standards including short, medium, long, full, and custom formats.

> [card] Currency Customization
>
> Support for currency formatting with options to display values using ISO codes or symbols, adapting to user-selected locales and regional preferences.

> [card] Locale-Based Configurations
>
> Comprehensive settings for pluralization, capitalization, alignment, and sorting that adapt to regional requirements, helping cater to a diverse global user base.

> [card] Enhanced UI Component Formatting
>
> New options in the UI Designer to override general settings for text, messages, links, and form elements based on locale and region.

> [card] Document Localization
>
> Static and dynamically generated legal documents can now be customized based on regional and locale settings, improving compliance and communication with local audiences.

> [card] [Localization and internationalization](/4.7.x/docs/building-blocks/ui-designer/localization-and-i18n)
>
> For more details, check out this section

***

### Data Model 2.0: Data handling, but make it fashion

In this release, we've introduced Data Model 2.0, a major upgrade designed to simplify and enhance data handling. Key improvements include the introduction of reusable objects, a visual representation of complex data structures, and dynamic data binding, all aimed at creating a more reliable and intuitive experience. The new model ensures references are automatically updated when changes are made, streamlining data management across the platform.

**Highlights**:

* **New Root Element**: Provides a structural basis without impacting business logic, ensuring a clear and organized data structure.
* **Enhanced Data Binding**: Expanded to more areas, with dynamic updates based on changes in the data model.
* **Localization**: Added handling mechanism for locale-specific formatting, ensuring accurate data representation.

<video />

> [card] [Data model](/4.7.x/docs/building-blocks/process/data-model)
>
> For more details, check out this section

***

### Task management 2.0

We've enhanced Task Management capabilities, making it easier to create, track, and manage tasks efficiently. The updated Task Management features include customizable views and advanced filtering and sorting options for task data. Additionally, users can now implement both low-code and full-code solutions for a tailored Task Management experience, ensuring maximum flexibility for different business needs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

> [card] [Task Management](/4.7.x/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> For more details, check out this section

***

### UI Designer

#### Grid layout

We are excited to introduce the Grid Layout feature in this release, enhancing the flexibility and usability of the UI Designer for creating structured and responsive layouts. With the new Grid Layout, users can organize form elements, tables, and other components using a multi-column and row system, allowing for more complex, bidirectional designs compared to the previous flex-based layout.

<video />

> [accordion] This might happen after using it for the first time:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid-layout-first-time.jpg)

#### Table

The Table component is a simple and flexible way to display data in web applications. It lets you customize columns, add pagination, sort and filter data, and apply your own styling. You can resize columns, scroll through data, and even add actions like editing or deleting rows directly in the table. It’s easy to set up, with default columns and rows generated automatically based on your data.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)

> [card] [Table](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/table)
>
> For more details, check out this section

#### FlowX.AI UI Designer new navigator

We are thrilled to introduce the new and improved **UI Designer Navigator**, a major update designed to streamline your UI design process.

> [card] Enhanced UI Layer Panel Design and Functionality
>
> The UI layer panel has been redesigned for a more intuitive experience, making it easier to manage and navigate through your design elements.

> [card] Improved Drag and Drop Experience
>
> Dragging and dropping components in the preview is now smoother and more precise, allowing for faster and easier creation of UIs.

> [card] Flexible Root Component Management
>
> You can now change the root component from a form group to a container or vice versa, offering greater flexibility when copying nodes or resolving configuration problems.

> [card] Clearer Component Hierarchy
>
> It is now simpler to identify where you are placing a component within the hierarchy, thanks to the enhanced drag/reorder functionality in the right panel.

<video />

#### Conditional formatting for UI elements

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)

> [!NOTE]
>
> Conditional styling is available for **text**, **link**, and **container** UI elements based on specific conditions.

#### Hide expressions enhancements

Expanded hide expressions functionality to include:

* Cards
* Collection prototypes and children
* Table cell children (e.g., texts, images, buttons, links)

#### UI actions

* Added a new UI action **Start new project instance**
* Removed the **Start Process Inherit** UI action type.

#### UI action form updates

* Introduced **Functional** and **UX sections** for all action types, with a checkbox for **Add Analytics Name** in the UX section.
* Simplified custom and exclude key management.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2015.20.01.png)

***

### Start new project instance action

We’ve introduced the Start New Project Instance node action, enabling users to initiate a completely new process from within an ongoing one. This functionality is perfect for scenarios where isolated use cases are managed across different projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)

> [card] [Start new project instance action](/4.7.x/docs/building-blocks/actions/start-new-project-instance)

***

### Custom components validation

You are able to validate and retrieve data from a generated screen, including data from a custom form section. Additionally, you’ll have the ability to trigger and manage data directly within that section. This will be a major benefit for clients who have chosen to create custom components for the entire screen (for example, a form that isn’t supported natively by the platform).

> [card] [Validating elements](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/root-components/card#validating-elements)

***

### Autocomputed data to send

In previous platform versions, when creating your UI screens and working with data, you had to ensure that all the data stored in your process keys was saved in the process instance. This required adding an extra parameter called "Data to send" to the "Save Data" node action.

**Older versions** vs **v4.6.0**:

![older versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.x-aut.png)

![v.4.6](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.2-aut.png)

Now, with the autocompute feature, this step is no longer necessary, as the data is automatically saved and sent on your process instance.

> [!TIP]
>
> You no longer need to add "Save Data" node actions, but make sure to include "Forms to Validate" on the UI Actions. This helps ensure that data is submitted correctly and automatically activates any added validators where they exist.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/forms_to_validate.png)

However, you still have the option to customize which keys are included or excluded as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/include_exclude_keys.png)

***

### **Scripting UX Improvements**: *Write code like a wizard*

* **Autocomplete**: Get tailored suggestions based on your data model.
* **New Editors**: JSON and hide/disable expressions editors now include examples, syntax help, and better visual feedback.

<video />

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide%3Adisable%20editor.png)

***

### React & Angular SDKs

Dev friends, we heard you. FlowX now integrates smoothly into your React and Angular apps. It’s like peanut butter and jelly, but make it code.

#### React SDK

With the 4.6.0 release, we're excited to announce the launch of the FlowX React SDK! This new SDK empowers developers to seamlessly integrate FlowX.AI capabilities into React applications, making it easier than ever to build highly interactive, responsive, and dynamic user experiences.

To get started, simply install the FlowX React SDK via npm and check our documentation for examples and best practices!

> [card] [React SDK](/4.7.x/sdks/react-renderer)

#### New Angular SDK

We're excited to announce new releases for FlowX packages to support web applications:

* `@flowx/core-sdk`
* `@flowx/angular-sdk`
* `@flowx/angular-theme`
* `@flowx/angular-ui-toolkit`
* `@flowx/core-theme`

> [!WARNING]
>
> We recommend upgrading to the **latest** versions of all @flowx packages to take full advantage of these new features and improvements. Check the deployment guidelines for version details.

> [card] [Angular SDK migration guide](migrating-from-v4.1.x-to-v4.6.0/renderers#angular-sdk-migration-guide)

***

### Analytics integration for Container Apps

Container apps now support tracking "Screen Displayed" and "Action Executed" events, configurable in the UI Designer to improve insights into user interactions.

**UI Designer updates**

* **Analytics Screen Name:** Configurable under Root UI components (Cards and Containers) to enable tracking in analytics platforms like Google Analytics.

> [!TIP]
>
> "Screen Displayed" events support user task-based reporting, such as when a user task screen is shown.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.01.58.png)

> [!NOTE]
>
> The configured values are stored in `flowxProps.analytics`, making them accessible for integration with analytics tools.

* **Action Analytics:** Tracks user actions (e.g., button clicks) with tags set directly in the UI Action Form.

> [!NOTE]
>
> Added analytics configuration in the **UX Section** for all UI action types.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.20.53.png)

> [!NOTE]
>
> Values are saved in `params.analytics` via the PATCH `/actions` request.

**Renderers updates**

Renderers now expose a public API for triggering analytics events:

* **Screen Events:** Triggered on user task display, using `flowxProps.analytics`.
* **Action Events:** Triggered on action execution, using `params.analytics`.

Dynamic values such as process store keys and replace tags are supported for more contextual tracking.

***

### Plugin updates

**Notifications** and **Documents** plugins have been integrated as **project resources**.

***

### Scheduled Processes: Timer management reimagined

We've completely redesigned how you manage timer-triggered processes. Before 4.6.0, timer activation was managed through a quick actions menu in process definition headers; now it's handled via dedicated UI section in the Runtime tab under Scheduled Processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

🕒 Key Improvements:

* **Centralized Timer Management:** All process timers are now visible and manageable in one dedicated location
* **Persistent Settings:** Timer configurations persist across build exports/imports
* **Environment Control:** Activate or deactivate timers without redeploying your application

For more details, check out this section

> [card] [Scheduled Processes](/4.7.x/docs/projects/runtime/scheduled-processes)

## Bug fixes 🐞

### Rendering

* **Default Value Initialization for UI Elements**: Resolved an issue where certain UI elements were initialized with incorrect default values.

* **Improved Security for Hidden Fields**: Fixed a vulnerability where hidden fields could be accessed through browser developer tools.

* **Form Validation Reset on UI Dismissal**: Addressed an issue where form validation errors persisted after the UI was closed.

* **Keybinding Issues on Windows**: Fixed a bug where pressing specific keys triggered unintended operations in the designer.

* **Input Field Validation for Number Type**: Corrected the validation logic for number input fields to ensure consistent behavior.

* **Improved Datepicker Popup Positioning**: Resolved an issue where the datepicker popup overlapped the associated input field.

* **Manual Date Entry in Datepicker**: Fixed an issue where manually entering a date after selecting one from the datepicker caused errors.

* **Enhanced Update Mechanism for Custom Components**: Improved the reliability of updates for custom components to reflect changes consistently.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **New substitution tags with the same name on different branches aren’t flagged**: Merging branches that include new substitution tags with identical names on different branches does not trigger a conflict. Instead, both tags are retained, resulting in duplicate substitution tags with the same name but different values. This issue bypasses expected conflict detection and can lead to inconsistencies in substitution tag usage.
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] Notification and document templates
>
> * Branches with notification and document templates fail to merge into the main branch

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Changes 🔧

* **Web Renderer Caching:** Improved resource caching with browser mechanisms keyed to build IDs.
* **Process Designer:** Enhanced drag-and-drop functionality for node placement.

***

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.0](./deployment-guidelines-v4.6.0)

Migrating from v4.1.x:

> [card] [Migrating from v4.1.x to v4.6.0](./migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x)

> [card] [Changes in process configuration](./migrating-from-v4.1.x-to-v4.6.0/process-configuration)

> [card] [Renderer SDKs](./migrating-from-v4.1.x-to-v4.6.0/renderers)


# Deployment guidelines v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/deployment-guidelines-v4.6.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.

## Component versions

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.1.1** | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.6** | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.2** | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | 4.1.3 | 4.1.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.4** | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.25** | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.4** | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.11** | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

> [!NOTE]
>
> Note: The same container image and Helm chart are used for **Application Manager** and **Runtime Manager**.

## AI Agents

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.16** | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.15** | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.6** | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.27** | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.6.5** | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.1 | Keycloak | 22.x |
| 4.6.1 | Kafka | 3.2.x |
| 4.6.1 | PostgreSQL | 16.2.x |
| 4.6.1 | MongoDB | 7.0.x |
| 4.6.1 | Redis | 7.2.x |
| 4.6.1 | Elasticsearch | 7.17.x |
| 4.6.1 | Oracle Database | 21C/ 21-XE |
| 4.6.1 | Angular (Web SDK) | 19.x |
| 4.6.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.


# Migrating from previous versions to v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/migrating-from-v4.1.x-to-v4.6.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.0 version, make sure to first review the migration guide for v4.6.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

If you're moving from v4.1.x to v4.6.1, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.6.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025

FlowX.AI 4.6.1 is here with important fixes and improvements to keep things running smoothly. No new features this time—just focused updates to improve stability, fix bugs, and enhance overall performance. Simple, clean, and efficient.

## **What's new?** 🆕

### Rendering

**Form Elements** improvements:

* **Default Value Handling**: Defaults are applied only when no existing value is found, and set upon first display (with specific exceptions).
* **Data Consistency**: Form elements now save data in standardized formats based on type for improved reliability.
* **Smart Defaults**: Clear fallback behaviors for elements like switches, sliders, and checkboxes when no value is present.
* **Synchronized Inputs**: Linked form elements (e.g., input + slider) stay in sync with automatic value adjustments within set limits.
* **Dynamic Dependencies**: Form elements can dynamically adjust based on related components’ values for greater flexibility.

### Merge conflicts

* Improvement: merged version is now selected after a successful merge in versioning modal.

## Bug fixes 🐞

### Merge conflicts

* Fixed an issue that caused conflicts involving notification and document templates to fail.
* Fixed an issue where merges failed when a deleted configuration parameter was updated on a branch.
* Fixed an issue that resulted in duplicate substitution tag keys appearing in the merged version.
* Fixed an issue where merges failed due to the same dependency being added to both the source and target branches.
* Fixed issues related to workflow conflicts.

### Rendering

* Fixed an issue where documents from the media library were not loading correctly when added as a file preview in a user task.

### Integration Designer

* Fixed issue causing a 400 error when adding an enum mapper to the body tab due to incorrect data validation.
* Fixed issue where the last attribute in the objects table was not visible at higher zoom levels due to UI rendering constraints.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.1](./deployment-guidelines-v4.6.1)

Migrating from v4.6.0:

> [card] [Migrating from previous versions](./migrating-from-v4.1.x-to-v4.6.1)


# Deployment guidelines v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/deployment-guidelines-v4.7.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.0 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.
>
> In version 4.7, the import-export functionality for application-version is no longer backward compatible.
>
> * Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
>
> * Similarly, zip files from earlier versions cannot be imported into 4.7.
>
> Note: Zip files for builds and specific resources remain unaffected.

## Component versions

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.3.1** | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.5.1** | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.11** | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.2** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.5** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.0** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.1** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.2** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.4** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.4** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.3** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.2** | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.1.0** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.5** | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.12** | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.21** | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.7.2** | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.13** | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.31** | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.0** | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.0 | Keycloak | 22.x, 26.x |
| 4.7.0 | Kafka | 3.2.x |
| 4.7.0 | PostgreSQL | 16.2.x |
| 4.7.0 | Oracle Database | 21c, 23ai |
| 4.7.0 | MongoDB | 7.0.x |
| 4.7.0 | Redis | 7.2.x |
| 4.7.0 | Elasticsearch | 7.17.x |
| 4.7.0 | Angular (Web SDK) | 19.x |
| 4.7.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/migrating-from-v4.1.x-to-v4.7.0

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025

FlowX.AI 4.7.0 is here to keep your projects vibing, your merges drama-free, and your configs under control—because struggling with your platform is *so* last season. 😎🔥

## What's new? 🆕

✅ Copy resources across projects\
✅ Duplicate resources (in the same project/library)\
✅ Resources usage tracking\
✅ Smarter merge conflict detection & resolution\
✅ Libraries can now define configuration parameters\
✅ Dynamic Kafka topics using configuration parameters

## Projects

### Copy resources across projects

Moving resources between projects is now **fast and seamless**. The new **Copy to Another Project** feature ensures all dependencies stay intact, eliminating the hassle of manual adjustments.

<video />

> [tab] How it works
>
> 1️⃣ **Select a destination** – Choose the target project or library.\
> 2️⃣ **Pick a branch (if applicable)** – For WIP versions, select the target branch.\
> 3️⃣ **Review dependencies** – The system displays referenced resources and validates dependencies.\
> 4️⃣ **Resolve identifier conflicts** – If an identifier already exists in the destination, you'll be prompted to either:
>
> * **Keep both** (create a duplicate)
> * **Replace** (overwrite the existing resource)
> * **Use destination** (retain the existing resource without copying)

> [tab] Why it’s better
>
> * **No broken references** – Everything stays connected.
> * **Auto-add missing dependencies** – No manual setup required.
> * **Works with WIP & committed versions (only from committed to WIP)** – Flexibility for your workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.48.33.png)

> [card] [Copy resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Duplicate resources

> [tab] What you can duplicate
>
> The **Duplicate Resource** feature lets users create a copy of an existing resource within the same project or library version, streamlining workflows and ensuring quick reusability.
>
> <video />
>
> You can duplicate the following resources:
>
> * **Processes**
> * **Enumerations**
> * **Media files (including Global media library files)**
> * **Notification templates**
> * **Document templates**
> * **Views**

> [tab] How it works
>
> * **Duplicate options** are available from each resource’s three-dot menu (table row & secondary navigation).
> * When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).
> * **Cancel** to discard changes or **Duplicate** to create an exact copy in the same project/library version.
> * **Success confirmation:** The system navigates to the newly created resource and displays a success message.
> * **Error handling:** If a resource with the same name/key exists, users will be prompted to rename it before proceeding.

> [tab] Why it’s useful
>
> 💡 **Use cases:**
>
> * Quickly iterate on existing resources.
> * Reduce redundant manual setup.
> * Maintain consistency within projects.
> * Easily clone complex configurations for testing and modifications.

> [card] [Duplicate resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Track where your resources are used

Monitoring your resources has never been simpler and more efficient. Stay on top of where and how they’re being used.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

> [card] [Process Usage](../../4.7.x/docs/projects/resources#process-usage)
>
> Track where a process is referenced, with a clear **Usage Overview modal** that dynamically updates when references change.

> [card] [Enumeration Usage](../../4.7.x/docs/projects/resources#enumeration-usage)
>
> See where enumerations are used across **UI, Data Models, Systems, and Workflows** before making changes.

> [card] [Media Library Usage](../../4.7.x/docs/projects/resources#media-library-usage)
>
> Identify **which UI elements reference media assets** so you don’t accidentally break designs.

📌 **Before deleting a resource, a confirmation modal lists all affected references. No more surprises!**

***

### Configuration parameters overrides

🔹 **Libraries can now define configuration parameters** to help test processes or workflows that use those parameters.

🔹 However, **libraries do not support overrides**.

* **Overrides for library config parameters must be done within a project** where the library is added as a dependency.
* **Overrides cannot be added in libraries directly.**

<video />

💡 **What this means:**

* Libraries provide **default values** for configuration parameters.
* Projects using those libraries **can override these values** as needed.
* This ensures **clear separation between library defaults and project-specific configurations** while maintaining flexibility.

> [!TIP]
>
> ✨ **Overrides take precedence** over library values—so you stay in control.

***

### Merge conflict enhancements

Merge conflicts are never fun, but at least now they’re **easier to handle**.

> [card] Better Conflict Detection
>
> 🚨 Prevents merging if identical resource identifiers exist in both branches (e.g., same name, key, or code).

> [card] Resizable Merge Conflict Tree
>
> 🖥️ Resize the merge conflict tree for better visibility and navigation.

> [card] New Conflict Type
>
> 📢 A new conflict detection system for parent changes/deletions in both branches.

***

## SDK changes

### Expose Enumerations API in Angular SDK

Developers can now dynamically retrieve enumerations via the Angular SDK, making it easier to use enums in custom components like dropdowns.

> [!TIP]
>
> How it Works?
>
> A new method in the Angular SDK allows direct access to enumerations, reducing manual imports and improving flexibility.

**Usage**

The `getEnumeration()` function returns key-value pairs that can be used in components that need enumeration data:

```typescript theme={"dark"}
getEnumeration(enumName: string): { value: string; label: string }[]
```

* `enumName` (string) – The name of the enumeration to retrieve (e.g., 'UserRoles', 'cities')
* Returns: An array of objects containing value-label pairs representing the requested enumeration

> [accordion] Example usage
>
> The enumeration service works seamlessly with Angular's resource API for reactive state management:
>
> ```typescript theme={"dark"}
> import { Component, effect, model, resource } from '@angular/core';
> import { getEnumeration } from '@flowx/angular-sdk';
>
> @Component({
>   selector: 'app-dynamic-enum-select',
>   template: `
>     <select>
>       @for (option of options.value(); track option.value) {
>         <option [value]="option.value">{{ option.label }}</option>
>       }
>     </select>
>
>     <button (click)="enumName.set('cities')">Load Cities</button>
>     <button (click)="enumName.set('countries')">Load Countries</button>
>   `
> })
> export class DynamicEnumSelectComponent {
>   // Create a signal to track the currently selected enum
>   enumName = model<string>('UserRoles');
>
>   // Use resource API to reactively load enumerations when enumName changes
>   options = resource({
>     request: this.enumName,
>     loader: ({ request: enumName }) => getEnumeration(enumName),
>   });
>
>   constructor() {
>     effect(() => {
>       if (this.options.isLoading()) {
>         console.log(`Loading enumeration: ${this.enumName()}`);
>       } else {
>         console.log(`Loaded enumeration: ${this.enumName()}`, this.options.value());
>       }
>     });
>   }
> }
> ```

***

## **Bug fixes** 🐞

✔️ Improved **merge conflict detection and resolution**\
✔️ Fixed **UI rendering issues**

***

## Changes

### Dynamic Kafka topics

FlowX 4.7.0 introduces **Dynamic Kafka Topics**, enabling more flexible and configurable messaging across processes.

🔹 **What’s new?**

* Use **Configuration Parameters** to dynamically assign Kafka topics in **Kafka Send** and **Kafka Receive** actions.
* Concatenate predefined parameters with process variables for **on-the-fly topic selection**.
* Reduce hardcoded values and **simplify environment-specific configurations**.

💡 **Why it matters:**

* Makes **Kafka integrations more scalable** across different deployments.
* Supports **multi-topic messaging** for different use cases without manual updates.
* Ensures better **reusability and maintainability** in process configurations.

📌 Check the [Kafka Send Action](../../4.7.x/docs/building-blocks/actions/kafka-send-action#dynamic-kafka-topics) section for setup details.

***

### Export/import compatibility

In version 4.7, the import-export functionality for application-version is no longer backward compatible.

* Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
* Similarly, zip files from earlier versions cannot be imported into 4.7.

> [!NOTE]
>
> Zip files for builds and specific resources remain unaffected.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.0](./deployment-guidelines-v4.7.0)\
📌 [Migration Guide (from v4.6.0)](./migrating-from-v4.1.x-to-v4.7.0)


# Deployment guidelines v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/deployment-guidelines-v4.7.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.1.

## Component versions

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.5.1** | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.7.6** | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.3.3** | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.4** | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.7** | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.3** | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.4** | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.6** | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.6** | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.6** | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.5** | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.9** | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.2** | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.7** | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.13** | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.27** | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.2** | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.17** | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.35** | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.4** | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.1 | Keycloak | 22.x, 26.x |
| 4.7.1 | Kafka | 3.2.x |
| 4.7.1 | PostgreSQL | 16.2.x |
| 4.7.1 | Oracle Database | 21c, 23ai |
| 4.7.1 | MongoDB | 7.0.x |
| 4.7.1 | Redis | 7.2.x |
| 4.7.1 | Elasticsearch | 7.17.x |
| 4.7.1 | Angular (Web SDK) | 19.x |
| 4.7.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/migrating-from-v4.1.x-to-v4.7.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025

FlowX.AI 4.7.1 brings enhanced resource navigation, better error detection, and workflow improvements to make your development journey even smoother! 🚀

## What's new? 🆕

✅ Enhanced resource usage tracking with direct navigation\
✅ Upgraded JavaScript support to ECMAScript 15 (2024) in Business Rules\
✅ Added Python 3 support with 3x performance improvement\
✅ Major performance enhancements for both design time and runtime\
✅ Security enhancements for runtime endpoints

## Projects

### Enhanced resource usage navigation

We've significantly improved how you navigate between resources and their references with direct navigation capabilities. Now you can easily jump from the usage tracking panel to the exact location where a resource is referenced.

<video />

> [tab] How it works
>
> 1️⃣ **Access resource usage** – View where a resource is being used through the usage panel.\
> 2️⃣ **One-click navigation** – Use the new redirect button to jump directly to the referenced location.\
> 3️⃣ **Missing resource detection** – Easily identify and fix missing resource references with clear indicators.

> [tab] Why it's better
>
> * **Faster troubleshooting** – Directly navigate to problem areas without manual searching.
> * **Improved productivity** – Less time spent hunting down references means more time building.
> * **Better error prevention** – Quickly spot and fix missing resources before they cause issues.

***

## Enhanced scripting capabilities

### ECMAScript 15 (2024) support for Business Rules

FlowX.AI 4.7.1 brings the latest JavaScript features to your business rules with an upgrade to ECMAScript 15 (2024).

> [tab] What's included
>
> * Access to the latest JavaScript language features
> * Modern syntax for cleaner, more maintainable rules
> * Enhanced tooling and IDE support

> [tab] Benefits
>
> * Write more concise and expressive business rules
> * Leverage modern JavaScript patterns and best practices
> * Improved developer experience with better IDE integration

> [!NOTE]
>
> **Important Configuration Note:** Nashorn engine remains the default runtime. To enable GraalJS support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Nashorn will be used.

### Python 3 support for Business Rules

We've upgraded our Python scripting capabilities to Python 3, delivering significant performance improvements while maintaining compatibility.

> [card] 3x Faster Execution
>
> Python scripts now run at least 3 times faster than with Python 2.7.

> [card] Modern Python Features
>
> Take advantage of Python 3's improved syntax, libraries, and security features.

> [!NOTE]
>
> **Important Configuration Note:** Python 2.7 remains the default runtime. To enable Python 3 support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Python 2.7 will be used.

More details about the scripting capabilities can be found in the [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts) section.

***

## Performance improvements 🚀

We've made significant performance enhancements throughout the platform to make your development and runtime experience smoother and faster.

### Design time improvements

For large processes, you'll notice dramatic improvements:

| Operation | Improvement |
| - | - |
| Cloning a process | **5x faster** |
| Opening a process | **70x faster** |

### Runtime enhancements

Platform average response time has been **reduced by 20%** in our comprehensive benchmark\*.

> [!NOTE]
>
> \*The benchmark simulates a typical business process with a combination of user and service tasks. It includes rules that automate decision-making, as well as events for time-sensitive actions and communication. The process also covers various system functions, ensuring the platform can efficiently manage complex workflows with both individual and parallel tasks.

***

## Security enhancements 🔒

We've significantly improved platform security by implementing proper endpoint access controls and separation between internal and public-facing APIs.

> [card] Enhanced API Security
>
> Runtime execution proxy vulnerability addressed with comprehensive endpoint updates.

> [card] Access Control Improvements
>
> Better separation between design-time and runtime endpoints with proper access controls.

### Endpoint security updates

We've implemented a comprehensive security update for runtime endpoints to prevent potential proxy vulnerabilities:

* Redesigned API structure to separate internal (`runtime-internal`) from external-facing (`runtime`) endpoints
* Migrated design-time operations to use `runtime-internal` endpoints for enhanced security
* Moved specific management operations to dedicated `build-mgmt` endpoints
* Updated all API clients to use the new secure endpoints

> [!NOTE]
>
> **Important:** Make sure to update to the corresponding  version of the [**`flowx-admin`**](./deployment-guidelines-v4.7.1#component-versions) to benefit from these security enhancements.

### Enhanced resource caching in Angular SDK

The Angular SDK now includes an improved caching mechanism for CMS resources, optimizing loading times and performance. The cache parameter on the `flx-process-renderer` component allows developers to control caching behavior in different environments.

> [card] [Read about caching in Angular SDK](../../4.7.x/sdks/angular-renderer#caching)
>
> Find details on controlling CMS resource caching during development and production.

## **Bug fixes** 🐞

* Fixed various minor issues to improve overall stability
* Resolved some UI inconsistencies
* Addresses performance optimizations
* Fixed general usability issues

***

## **Additional information**

📌 [Deployment Guidelines v4.7.1](./deployment-guidelines-v4.7.1)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.1)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.10
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/deployment-guidelines-v4.7.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.3** | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.8** | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.6** | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.5** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.4** | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.6** | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.4** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.3** | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.6** | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.2** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.32** | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.24** | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.10 | Keycloak | 22, 26+ |
| 4.7.10 | Kafka | 3.2 - 3.9 |
| 4.7.10 | PostgreSQL | 16 - 17 |
| 4.7.10 | OracleDB | 19c, 21c, 23ai |
| 4.7.10 | MongoDB | 7 - 8 |
| 4.7.10 | Redis | 7.2 - 8.0 |
| 4.7.10 | Elasticsearch | 7 - 8 |
| 4.7.10 | Angular (Web SDK) | 19.x |
| 4.7.10 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.10 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Updated Spring Boot to the latest release for enhanced security and performance\
✅ Updated Java libraries to fix vulnerabilities across all images\
✅ Selectors support for substitution tags across all platforms (Web, iOS, Android)\
✅ System substitution tags on all task management texts\
✅ CMS - Added system substitution tags with migration script support

### Security and Platform Updates

This release includes critical security updates to ensure your FlowX.AI platform remains secure and up-to-date:

* **Spring Boot Update**: Updated to the latest release on the 4.7.x LTS branch
* **Java Libraries Update**: Updated Java libraries to fix vulnerabilities across all LTS 4.7.x images

### Selectors Support for Substitution Tags

You can now use selectors with substitution tags when the source type is process data across all platforms (Web, iOS, and Android). This enhancement provides more flexibility in displaying dynamic content from your process data in selector components.

**Available on:**

* Angular Web Renderer
* React Web Renderer
* iOS Renderer

### System Substitution Tags for Task Management

Task management now includes comprehensive system substitution tags support:

* **Backend CMS**: Added system substitution tags with a migration script to help you transition existing content
* **Web Renderers**: System substitution tags are now available on all task management texts across Angular and React renderers
* This allows for more dynamic and flexible task management configurations

## Bug fixes

> [accordion] \[Designer] Error when copying/pasting nodes with misconfiguration
>
> Fixed an issue where attempting to copy and paste nodes with misconfigurations, or importing an app version/build with misconfigured nodes, would result in an error. The system now handles misconfigured nodes gracefully during these operations.
>
> **Issue**: Error when trying to copy and paste nodes with misconfiguration or import an app version/build with nodes with misconfigurations

> [accordion] \[React] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the React renderer.
>
> **Issue**: \[React] Card not expandable after finishing subprocess started from it

> [accordion] \[Angular] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the Angular renderer.
>
> **Issue**: \[Angular] Card not expandable after finishing subprocess started from it

> [accordion] \[React] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the React renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[React] Card shouldn't collapse when next nav area is modal

> [accordion] \[Angular] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the Angular renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[Angular] Card shouldn't collapse when next nav area is modal

> [accordion] \[Backend] Task Manager - System substitution tags not displayed in column names
>
> Fixed an issue where system substitution tags were not being displayed in the `columns.displayName` property of the Task Manager backend.
>
> **Issue**: \[BE] Task manager | System substitutionTags are not displayed in columns.displayName

> [accordion] \[Web Renderers] Task Manager - Substitution tags value override
>
> Resolved an issue where system substitution tags values were incorrectly overriding custom substitution tags when the value was not null in both React and Angular renderers.
>
> **Issue**: \[React]\[Angular] Task manager | System subTags values override de custom subTags when value is not null

> [accordion] \[Task Manager] Missing localization for Russian and Uzbek in table view
>
> Fixed localization support in Task Manager table view for Russian and Uzbek languages, ensuring proper display of translated content.
>
> **Issue**: \[Task manager localisation] Table view - Missing localisation support for Russian and Uzbek

> [accordion] \[Task Manager] View search field placeholder not localized
>
> Resolved an issue where the view search field placeholder in Task Manager was not being localized for any language. The placeholder now properly supports all configured languages.
>
> **Issue**: \[Task manager localisation] View search field placeholder not localised for any language


# Deployment guidelines v4.7.11
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/deployment-guidelines-v4.7.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.6** | 8.24.3 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.12** | 7.18.8 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.9** | 5.11.6 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.8** | 6.8.5 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.7** | 6.10.4 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.9** | 7.9.6 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.7** | 6.8.4 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.6** | 2.16.3 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.9** | 2.10.6 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.103.6** | 5.101.2 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.32 | 4.0.32 | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.27** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.25** | 1.8.24 | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.11 | Keycloak | 22, 26+ |
| 4.7.11 | Kafka | 3.2 - 3.9 |
| 4.7.11 | PostgreSQL | 16 - 17 |
| 4.7.11 | OracleDB | 19c, 21c, 23ai |
| 4.7.11 | MongoDB | 7 - 8 |
| 4.7.11 | Redis | 7.2 - 8.0 |
| 4.7.11 | Elasticsearch | 7 - 8 |
| 4.7.11 | Angular (Web SDK) | 19.x |
| 4.7.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.11 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025

Security and maintenance updates for the 4.7.x LTS release

## What's new?

This is a **security and maintenance release** for the FlowX.AI 4.7.x LTS branch, focused on keeping your platform secure and up-to-date with the latest security patches.

✅ **Security Updates** - Updated core libraries and dependencies to address known vulnerabilities\
✅ **Platform Stability** - Improved overall platform security and stability

***

## Migration notes

> [!WARNING]
>
> As this is a **patch release** on the 4.7.x LTS branch, it is designed to be a **drop-in replacement** with no breaking changes.

***

## Component versions

All FlowX.AI components have been updated to version **4.7.11** with the security patches applied. Refer to the deployment guidelines for the complete list of component versions.


# Deployment guidelines v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/deployment-guidelines-v4.7.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.2 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.2.

## Component versions

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.9.0** | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.5** | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.8** | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.10** | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.16** | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.12** | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.13** | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.14** | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.13** | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.14** | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.2.0** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.12** | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.16** | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.9** | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.35** | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.9** | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.24** | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.1** | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.9** | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.2 | Keycloak | 22.x, 26.x |
| 4.7.2 | Kafka | 3.2.x |
| 4.7.2 | PostgreSQL | 16.2.x |
| 4.7.2 | Oracle Database | 21c, 23ai |
| 4.7.2 | MongoDB | 7.0.x |
| 4.7.2 | Redis | 7.2.x |
| 4.7.2 | Elasticsearch | 7.17.x |
| 4.7.2 | Angular (Web SDK) | 19.x |
| 4.7.2 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## Additional configuration

Added new environment variable on Process Engine:

### Message routing configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

> [!NOTE]
>
> When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.


# Migrating from previous versions to v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/migrating-from-v4.1.x-to-v4.7.2

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 and v4.7.1 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.2 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025

FlowX.AI 4.7.2 delivers improved merge conflict handling with retry capabilities, deprecates DMN business rules, and fixes issues with subprocess handling, media file imports, and OCR functionality to enhance your development workflow! 🚀

## **What's new? 🆕**

✅ Improved merge conflict handling with retry functionality\
✅ Enhanced error messages during failed merges\
✅ Streamlined workflow for resolving merge conflicts

## Merge conflicts

### Improved error messages when merge fails

We've enhanced the merge conflict resolution experience with more informative error messages and a new retry functionality:

* When a merge fails, users can now see a "Retry merge" button on the Merge failed modal
* Clicking this button allows users to attempt the merge again without losing previous work

The system now handles two distinct scenarios:

**1. When conflicts exist:**

* The system opens the Merge conflicts panel with the previous state of the merge before the failed attempt
* This preserves all your conflict resolution work so you can fix the specific issues that caused the failure

![Merge failed with conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20conflicts.png)

**2. When no conflicts exist:**

* The system automatically retries the merge operation
* This streamlines the workflow when the merge failure was due to temporary issues rather than actual conflicts

![Merge failed without conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20no%20conflicts.png)

## Process engine

### Deprecated DMN rules

In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.

**What's changing:**

* DMN is no longer available as a language option when configuring business rule actions

**What's next:**
For guidance on using alternative business rule languages, please refer to our [supported scripting languages](../../../../4.7.x/docs/building-blocks/supported-scripts) documentation.

## **Bug fixes** 🐞

* Resolved export/import issues with media library files, particularly for applications migrated from earlier versions
* Fixed an issue where parallel multi-instance Call Activity would incorrectly trigger a subprocess when using an empty array list as a variable
* Fixed a display issue where not all subprocesses were visible in the subprocess list on smaller screens
* Fixed a bug where message events couldn't be caught when placed directly after an uninterrupting timer event
* Resolved "Unsupported Media Type" errors when importing application versions with media file binaries
* Fixed an issue where color palette changes in Theme settings couldn't be saved at 100% browser resolution on smaller screens
* Fixed a issue where OCR plugin failed due to missing correlation headers

***

## **Additional information**

📌 [Deployment Guidelines v4.7.2](./deployment-guidelines-v4.7.2)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.2)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/deployment-guidelines-v4.7.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.3 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.3.

## Component versions

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.13.0** | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.13** | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.12** | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.11** | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.17** | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.13** | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.16** | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.15** | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.14** | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.15** | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.14** | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.6.0** | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.11** | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.14** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.15** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.37** | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.12** | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.26** | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.3** | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.11** | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.3 | Keycloak | 22.x, 26.x |
| 4.7.3 | Kafka | 3.2.x |
| 4.7.3 | PostgreSQL | 16.2.x |
| 4.7.3 | Oracle Database | 21c, 23ai |
| 4.7.3 | MongoDB | 7.0.x |
| 4.7.3 | Redis | 7.2.x |
| 4.7.3 | Elasticsearch | 7.17.x |
| 4.7.3 | Angular (Web SDK) | 19.x |
| 4.7.3 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/migrating-from-v4.1.x-to-v4.7.3

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.3 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025

FlowX.AI 4.7.3 enhances workflow conflict resolution, adds configurable enumeration ordering, and fixes data streams, UI templates, and application export/import issues to improve your development experience! 🚀

## **What's new? 🆕**

✅ Enhanced workflow conflict resolution with improved visibility\
✅ Added ability to configure order attributes on enumerations\
✅ Upgraded conflict management interface for better user experience

## Merge conflicts - workflow improvements

### Enhanced workflow conflict resolution

We've significantly improved how [**workflow**](../../4.7.x/docs/platform-deep-dive/integrations/integration-designer#workflows) conflicts are handled in this release:

* Upgraded to a new version (v2) of the workflow conflict resolution interface
* Now only showing workflow entities that have actual conflicts, making it easier to identify and address issues
* Streamlined the conflict resolution process for a more efficient workflow

![Workflow conflict resolution](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/workflow_conflicts.png)

> [!NOTE]
>
> **Important note about sequence conflicts:**
>
> When resolving conflicts related to sequences, if you select one of the conflicting sequences, nodes that are no longer connected may remain "orphaned" on the canvas in the merged version. This design decision was made to prevent accidental node deletion. If these orphaned nodes are no longer needed, they can be manually removed in subsequent versions.

## Configurable enumeration ordering

You can now configure the **Order** attribute on enumerations, giving you greater control over how enumeration values are displayed in dropdown lists:

* Set specific order values for each enumeration entry
* Control the presentation sequence in UI components
* Improve user experience by arranging options in logical or prioritized order

![Enum order](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/enum_order.png)

> [!NOTE]
>
> **Limitation:** When changing the order value for an enumeration entry, the system does not automatically update the order values of other entries. You'll need to manually adjust the order values of other entries in the interface.

## **Bug fixes** 🐞

* Fixed an issue where workflow nodes could have two output sequences
* Resolved a problem with enumerations displaying in the wrong order in dropdown lists
* Fixed an authentication issue where users would receive 401 unauthorized errors when executing actions after token refresh
* Fixed a UI behavior issue where slider actions configured with "onChange" were incorrectly triggered when entering a screen instead of only when modified
* Fixed an issue with identical advancing IDs occurring in multi-pod deployments due to missing hostname command in GraalVM docker images
* Resolved an issue preventing media library migration from default application
* Fixed the "Go to reference" functionality from data model attributes that was not correctly redirecting to referenced elements
* Fixed an error during application export/import where "There already exists a tagged build for this project version" was preventing successful imports
* Restored support for multiple topics in Data Stream Topics feature, which was previously only listening to the first topic in the list
* Fixed a 500 error that occurred when attempting to create child actions on certain nodes
* Fixed a critical issue where UI templates would disappear when creating a new version of an application after performing undo operations on pasted templates
* Fixed a bug where updates to the subprocess in a Start subprocess action weren't being saved properly
* Fixed an issue with the "Send email" button remaining disabled in the Test notification template feature after correcting validation errors
* Fixed an error that occurred when trying to export document templates containing null values in templateMap
* Fixed a display issue where Tokens, Workflows, and Subprocesses information wasn't showing in process instances after migration from 4.7.1 to 4.7.2
* Fixed a UI issue where business rule code wasn't displayed when testing business rules in committed versions

***

## **Additional information**

📌 [Deployment Guidelines v4.7.3](./deployment-guidelines-v4.7.3)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.3)


# Deployment guidelines v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/deployment-guidelines-v4.7.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.4 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.4.

## Component versions

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.15.2** | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.9.2** | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.16** | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.13** | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.19** | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.15** | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.18** | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.17** | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.16** | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.17** | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.16** | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.7.2** | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.3.2** | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.19** | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.23** | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.39** | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.17** | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.28** | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.5** | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.13** | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.4 | Keycloak | 22.x, 26.x |
| 4.7.4 | Kafka | 3.2.x |
| 4.7.4 | PostgreSQL | 16.2.x |
| 4.7.4 | Oracle Database | 21c, 23ai |
| 4.7.4 | MongoDB | 7.0.x |
| 4.7.4 | Redis | 7.2.x |
| 4.7.4 | Elasticsearch | 7.17.x |
| 4.7.4 | Angular (Web SDK) | 19.x |
| 4.7.4 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## **Additional information**

* Added new environment variable `OPTIMISTIC_LOCKING_RETRIES` to control the number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

Elasticsearch indexing configuration:

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)


# Migrating from previous versions to v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/migrating-from-v4.1.x-to-v4.7.4

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.4 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025

FlowX.AI 4.7.4 enhances system stability with Spring Boot updates and resolves critical issues across build exports, reporting, SDK functionality, and cross-platform consistency to deliver a more reliable development experience! 🚀

## **What's new? 🆕**

✅ Platform enhancements\
✅ Added retry mechanism for ES indexing to handle key‑identifier errors\
✅ Fixed critical build export timeout issues\
✅ Improved reporting data representation\
✅ Enhanced cross-platform consistency

### Platform Enhancements ⚙️

* Enhanced system stability
* Latest security patches
* Improved performance

### Elasticsearch indexing - configurable retry mechanism

* `OPTIMISTIC_LOCKING_RETRIES`: Number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)

### Data-sync run status monitoring

* Added the ability to view the run status of data-sync jobs directly in the platform interface
* Monitor the execution status of all data-sync jobs from the Jobs dashboard
* Quickly identify failed jobs for faster troubleshooting

![Data-sync run status monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-20%20at%2010.55.19.png)

## **Bug fixes** 🐞

* **Build export timeouts**: Resolved intermittent timeout failures on projects with dependency libraries; exports now consistently complete or retry correctly.
* **Build creation on merge without conflicts**: Fixed an issue where merging one branch into another without conflicts—and switching the active policy—did not trigger a new build, forcing users to manually create a version; now, merges automatically update build resources and create the new version so merged changes appear at runtime.
* **Project version import stashing conflict**: Resolved an error where importing a branched project version across environments would inadvertently stash other versions—restoring successful import, fixing the GET history API response, and ensuring the Project versions history modal renders correctly.
* **CosmosDB workflows**: Fixed an issue preventing the workflow instances list from loading in the Integration Designer when using CosmosDB.
* **Reporting arrays**: Corrected array formatting in the `reporting_data` table (process-engine schema).
* **CMS permissions**: Restored backward compatibility for FlowX SDK v4.7+ by removing the unintended `media_library_read` requirement for processes containing images (behavior now matches v4.1).
* **onChange action behavior**: Standardized onChange/onBlur across web, Android, and iOS so users cannot continue typing after token advancement unless explicitly allowed.
* **React SDK ternary expressions**: Fixed an “Invalid Expression” error in SDK v5.86.1—ternary expressions in computed values (e.g. `return ${var1} ? "Onboarded" : (${var2} ? "Non-eligible" : "Ready for Onboarding");`) now parse correctly as they did in v5.62.1.
* **Elasticsearch indexing**: Fixed an issue where the engine was not retrying to index process instances when it encountered concurrent-update errors on key identifiers.
* **iOS SSE token refresh**: Fixed an issue in iOS SDK where Server-Sent Events connections would occasionally use expired JWT tokens instead of refreshed ones, causing 401 errors and process hangs in production environments.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.4](./deployment-guidelines-v4.7.4)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.4)


# Deployment guidelines v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/deployment-guidelines-v4.7.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.5 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.5.

## Component versions

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.17.0** | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.12.2** | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.5.1** | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.1.1** | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.1.1** | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.2.1** | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.4.1** | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.3.1** | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.1.1** | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.9.0** | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.4.1** | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.21** | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.24** | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.18** | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.5 | Keycloak | 22, 26+ |
| 4.7.5 | Kafka | 3.2 - 3.9 |
| 4.7.5 | PostgreSQL | 16 - 17 |
| 4.7.5 | Oracle Database | 21c, 23ai |
| 4.7.5 | MongoDB | 7 - 8 |
| 4.7.5 | Redis | 7.2 - 8.0 |
| 4.7.5 | Elasticsearch | 7 - 8 |
| 4.7.5 | Angular (Web SDK) | 19.x |
| 4.7.5 | React (Web SDK) | 18.x |

> [!NOTE]
>
> **New in 4.7.5: Support for more 3rd Party Dependencies**
>
> FlowX.AI 4.7.5 introduces support for more versions of third-party dependencies:
>
> * All versions are officially supported throughout the entire LTS lifetime
> * Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major release
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/migrating-from-v4.1.x-to-v4.7.5

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.5 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.5 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025

FlowX.AI 4.7.5 enhances system stability with introducing support for more 3rd party dependency and introduces High Availability improvements with Redis Sentinel mode support to deliver a more reliable and scalable development experience! 🚀

## **What's new? 🆕**

✅ **Platform enhancements**\
✅ **Analytics enhancements**

### Platform enhancements ⚙️

**Extended Third-Party Dependency Support** - Introducing support for more versions of third-party dependencies:

* All versions are officially supported throughout the entire LTS lifetime
* Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major releases for critical infrastructure components, ensuring all supported versions are officially maintained throughout the entire LTS lifetime. This enables organizations to perform gradual dependency upgrades during the LTS period, preparing infrastructure to meet the minimum requirements for the next FlowX.AI major release while maintaining full platform support and stability.

### Analytics enhancements ⚙️

* Improved analytics events with enriched metadata for action events across all platforms (Web, iOS, Android). Action events now include screen context, component type identification, and component labels, providing deeper insights into user interactions and enabling more granular analytics tracking for better user experience optimization.

More details:

> [card] [Angular Renderer](../../../../4.7.x/sdks/angular-renderer#analytics)

> [card] [React Renderer](../../../../4.7.x/sdks/react-renderer#analytics)

> [card] [iOS Renderer](../../../../4.7.x/sdks/ios-renderer#collecting-analytics-events)

> [card] [Android Renderer](../../../../4.7.x/sdks/android-renderer#collecting-analytics-events)

### Runtime Manager deployment changes

> [!NOTE]
>
> **Prior to 4.7.5:** Runtime Manager was deployed using `application-manager` chart/image with manual `SPRING_APPLICATION_NAME`: "runtime-manager" configuration.
> Starting with 4.7.5: Runtime Manager has its own dedicated chart and image with proper defaults.

> [!TIP]
>
> Migration Required

* Switch to new chart: Use runtime-manager chart instead of application-manager
* Verify image: Ensure image name is runtime-manager (default in new chart)
* Remove override: `SPRING_APPLICATION_NAME`: "runtime-manager" can be removed (optional)

> [!WARNING]
>
> You may need to delete the existing runtime-manager deployment before upgrading due to Kubernetes label changes that cause `kubectl apply` to fail.

## **Bug fixes** 🐞

* **Fixed Task Manager loading issue with data type changes** - Resolved critical issue where Task Manager would fail to load and throw `NullPointerException`   when process variables were changed from date to string data types, even after updating the data model and clearing cache
* **Fixed All Tasks view missing on build import** - Resolved issue where importing builds from one environment to another would fail to create the All Tasks view, when accessing the Task Manager area
* **Fixed unassign operation causing runtime errors** - Resolved 500 Internal Server Error when accessing process data after performing unassign operations via Kafka messages, where null ownerDetails would cause `NullPointerException` during JSON serialization
* **Fixed CMS-Core export failures with AWS S3 buckets** - Resolved issue where CMS-Core would add double slashes in S3 object paths when creating exports, causing 404 NoSuchKey errors with AWS S3 (while working correctly with MinIO). Fixed path construction to ensure compatibility with both AWS S3 and MinIO storage backends
* **Fixed active policy version resolution** - Resolved issue where importing application versions to environments with existing WIP versions would incorrectly activate the stashed WIP version instead of the imported committed version, causing graph display failures and incorrect active policy settings

***

## **Additional information**

📌 [Deployment Guidelines v4.7.5](./deployment-guidelines-v4.7.5)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.5)


# Deployment guidelines v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/deployment-guidelines-v4.7.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.6 will permanently prevent you from importing process definitions and resources created in versions 4.7.5 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

> [!WARNING]
>
> **Audit data retention change**
>
> Starting with FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. In 4.7.5 and earlier, the service created this policy only once, on the first installation.
>
> The policy it writes has a single hot phase that rolls the audit data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. The default is `30` days; in 4.7.5 and earlier, the rollover period was a fixed 1 day.
>
> Any phase you added to this policy directly in Elasticsearch, such as a delete phase, is removed the next time the Audit service starts. Without a delete phase, old audit indices are never deleted and audit storage keeps growing.
>
> To keep the previous daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1` on the Audit service.

## Component versions

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.21.1** | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.15.2** | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.8.2** | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.4.0** | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.4.0** | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.5.0** | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.7.0** | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.6.0** | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.5.0** | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.13.0** | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.7.1** | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.29** | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.19** | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.6 | Keycloak | 22, 26+ |
| 4.7.6 | Kafka | 3.2 - 3.9 |
| 4.7.6 | PostgreSQL | 16 - 17 |
| 4.7.6 | OracleDB | 21c, 23ai |
| 4.7.6 | MongoDB | 7 - 8 |
| 4.7.6 | Redis | 7.2 - 8.0 |
| 4.7.6 | Elasticsearch | 7 - 8 |
| 4.7.6 | Angular (Web SDK) | 19.x |
| 4.7.6 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8

## Configuration Parameters

Starting with FlowX.AI 4.7.6, Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment.

> [card] [Integration Designer setup](/4.7.x/setup-guides/integration-designer-setup#configuration-parameters)

> [card] [Process Engine setup](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters)

> [card] [Application Manager setup](/4.7.x/setup-guides/application-manager)


# Migrating from previous versions to v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/migrating-from-v4.1.x-to-v4.7.6

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.6 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.6](../v4.7.6-july-2025/deployment-guidelines-v4.7.6)

> [card] [Deployment guidelines v4.7.5](../v4.7.5-july-2025/deployment-guidelines-v4.7.5)

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1/)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.6 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025

This release includes significant improvements to logging configuration and resolves some issues across the Designer, Process Engine, and Integration Designer components.

> [!WARNING]
>
> Upgrading to 4.7.6 changes how the Audit service manages its Elasticsearch lifecycle policy: the policy is rewritten on every startup and the default rollover period changes from 1 day to 30 days. See the [Deployment guidelines](./deployment-guidelines-v4.7.6) before upgrading.

## **What's new? 🆕**

> [card] Improved default logging configuration
>
> Changed logging verbosity to reduce clutter & log sizes, increasing visibility for more relevant log messages.

> [card] Improved the ability to use deployment specific variables as Configuration Parameters (at process runtime)
>
> Now Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment. Check the [**Deployment Guidelines**](./deployment-guidelines-v4.7.6#configuration-parameters) for more details.

> [card] Improved runtime performance
>
> Improved runtime performance by better distributing the execution of nodes across all components.

> [card] Improved the speed of listing process instances
>
> Improved the speed of listing process instances by 4-6x on environments with a lot of process executions.

> [card] Added the ability to change logging levels at runtime
>
> This feature allows you to dynamically adjust logging levels without requiring a service restart, providing more flexibility in managing log output.

> [card] Reduced config deployment complexity
>
> The previously used `CONFIG_PROFILE` environment variable is no longer required as the default configs have been aligned with the recommended profiles.

## **Bug fixes** 🐞

> [accordion] \[Designer] Task view display issue
>
> Fixed task view list row content display issue where table rows were overlapping and text was not vertically centered in the latest Chrome browser version (138). The task view now properly displays centered content without text cutoff.

> [accordion] \[Integration Designer] JSON parsing error
>
> Fixed JSON parsing error when sending JSON result to REST body. Resolved issue where JSON objects generated in script tasks were causing "Unexpected character" errors when used in REST endpoint body parameters with \$ syntax.

> [accordion] \[Branch Merge] Media file export errors
>
> Fixed media file export errors during branch merges. Resolved issue where merging multiple branches created from the same main version would fail with "400 Bad Request" errors for media files after the first successful merge, even when no merge conflicts were present.

> [accordion] \[Process Designer] Rollback issue
>
> Fixed rollback issue during version submission errors. Resolved problem where processes were incorrectly marked as deleted in the database when submit version operations failed with 500 errors, preventing proper rollback and causing subsequent 404 "Process not found" errors.

> [accordion] \[Process Designer] Missing resources during copy operation
>
> Fixed missing resources during copy to another project/library operation. Resolved issue where forms with validation in UserTask nodes were not being copied when copying processes between projects or libraries.

> [accordion] \[Process Designer] Branch with missing resources and 404 errors
>
> Fixed issue where specific branches derived from main version would experience resource corruption, including missing process definitions (404 errors), missing Integration Designer resources, and commit failures.

> [accordion] \[Process Designer] Parallel multi-instance visual bug
>
> Fixed parallel multi-instance designer visual bug and database errors. Resolved issue where call activity nodes with parallel multi-instance enabled created duplicate "inputKey" and "outputKey" entries, causing visual bugs (missing collection key fields) and database update errors during node modifications.

> [accordion] \[Process Engine] Kafka message distribution
>
> Fixed Kafka message distribution across partitions. Resolved issue where Kafka messages were distributed as batches across partitions, causing increased usage of a limited number of partitions, instead of following the round-robin distribution per message strategy.

***

## **Additional information**

> [card] [Deployment Guidelines v4.7.6](./deployment-guidelines-v4.7.6)
>
> Step-by-step deployment instructions and configuration details for this release.

> [card] [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.6)
>
> Complete guide for migrating from version 4.1.x to 4.7.6 with breaking changes and migration steps.


# Deployment guidelines v4.7.7
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/deployment-guidelines-v4.7.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.7 will permanently prevent you from importing process definitions and resources created in versions 4.7.6 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.22.3** | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.16.3** | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.97.1** | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.9.2** | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.6.2** | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.8.2** | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.7.2** | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.6.2** | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.14.2** | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.8.1** | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.40** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.21** | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.29** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.14** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.7 | Keycloak | 22, 26+ |
| 4.7.7 | Kafka | 3.2 - 3.9 |
| 4.7.7 | PostgreSQL | 16 - 17 |
| 4.7.7 | OracleDB | 19c, 21c, 23ai |
| 4.7.7 | MongoDB | 7 - 8 |
| 4.7.7 | Redis | 7.2 - 8.0 |
| 4.7.7 | Elasticsearch | 7 - 8 |
| 4.7.7 | Angular (Web SDK) | 19.x |
| 4.7.7 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.7 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Improved robustness on auto-scaling process-engine and on Kafka node failures\
✅ Improvements on how configuration parameters can now be retrieved from Kubernetes secrets and ConfigMaps\
✅ Vulnerability fixes

## Configuration parameters

Improved configuration parameters retrieval from Kubernetes secrets and ConfigMaps. More details here:

> [card] [FlowX Engine](../../4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#dynamic-configuration-parameters-retrieval)

> [card] [Integration Designer](../../4.7.x/setup-guides/integration-designer-setup#dynamic-configuration-parameters-retrieval)

## Bug fixes

> [accordion] \[Designer] JSON size limit on input data
>
> Fixed JSON payload size limit issue causing "403 payload too large" errors when starting processes. More details [**here**](../../4.7.x/docs/flowx-designer/managing-a-project-flow/starting-a-process#starting-a-process-via-user-interface).

> [accordion] Improved robustness on Kafka node failures
>
> If one Kafka node fails, platform health check fails. This is now fixed.

> [accordion] \[UI Designer] Theming on accordion card
>
> Fixed theming issue where Card component styling was not properly applied when switched to accordion mode.

> [accordion] \[Angular SDK] Loader does not stop on subprocess end
>
> Fixed loader persistence issue where loaders initiated by "show loader" actions in subprocess UserTasks would continue displaying after subprocess completion.

> [accordion] \[Process Designer] Merge error with duplicate embed node keys
>
> Fixed merge conflict error occurring when copying and pasting embed nodes in processes.

> [accordion] \[Process Engine] Process execution stalls on REST-triggered flows when engine replica fails
>
> Fixed process execution recovery issue where REST API-triggered service tasks would hang indefinitely if the handling engine replica failed mid-execution.

> [accordion] \[Process Designer] Merge fails with duplicate key error after creating child branch to jump over broken WIP
>
> Fixed merge conflict error occurring when creating child branches from working commits to bypass broken WIP versions.


# Deployment guidelines v4.7.8
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/deployment-guidelines-v4.7.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.8 will permanently prevent you from importing process definitions and resources created in versions 4.7.7 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.23.2** | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.17.3** | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.10.3** | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.7.2** | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.9.2** | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.8.2** | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.7.2** | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.15.3** | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.9.2** | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.22** | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.8 | Keycloak | 22, 26+ |
| 4.7.8 | Kafka | 3.2 - 3.9 |
| 4.7.8 | PostgreSQL | 16 - 17 |
| 4.7.8 | OracleDB | 19c, 21c, 23ai |
| 4.7.8 | MongoDB | 7 - 8 |
| 4.7.8 | Redis | 7.2 - 8.0 |
| 4.7.8 | Elasticsearch | 7 - 8 |
| 4.7.8 | Angular (Web SDK) | 19.x |
| 4.7.8 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.8 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes\
✅ Support for [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title

### Support for Substitution Tags in Table column title

Now you can use [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title.

## Bug fixes

> [accordion] \[UI Designer] Card expansion state not calculated correctly
>
> Resolved an issue where, in certain situations, the expanded state of cards was not calculated correctly. This prevented users from expanding cards as expected.

> [accordion] \[UI Designer] Document preview component texts not translated
>
> Fixed localization issue where document preview component texts remained in English regardless of the selected language setting.

> [accordion] \[Designer] Groups tab fails to load with Keycloak 26.3
>
> Fixed compatibility issue with Keycloak 26.3 where the Groups tab would remain in loading state indefinitely due to new "description" field in group representations.

> [accordion] \[CMS] Import fails for PDF files with null thumbnail path
>
> Fixed import failure when PDF media files were exported with null `thumbnailStoragePath` values, preventing successful deployment of build or app versions to fresh environments.

> [accordion] \[Runtime Manager] Improved error logging for proxy failures
>
> Enhanced error logging detail when Runtime Manager proxy requests fail, providing better root cause information for debugging infrastructure issues like DNS problems or service unavailability.

> [accordion] \[Integration Designer] Slow performance on first workflow execution after pod restart
>
> Fixed performance issue where workflow IF node processing time increased from 3-5 seconds to 15-20 seconds on the first execution after Integration Designer pod restart.

> [accordion] \[Process Engine] Active step was incorrectly computed when the token is reset
>
> Fixed issue where the active step was incorrectly computed when the token is reset.


# Deployment guidelines v4.7.9
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/deployment-guidelines-v4.7.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.1** | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.4** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.1** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.1** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.1** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.2** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.30** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.26** | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.23** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.9 | Keycloak | 22, 26+ |
| 4.7.9 | Kafka | 3.2 - 3.9 |
| 4.7.9 | PostgreSQL | 16 - 17 |
| 4.7.9 | OracleDB | 19c, 21c, 23ai |
| 4.7.9 | MongoDB | 7 - 8 |
| 4.7.9 | Redis | 7.2 - 8.0 |
| 4.7.9 | Elasticsearch | 7 - 8 |
| 4.7.9 | Angular (Web SDK) | 19.x |
| 4.7.9 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.9 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes and security improvements\
✅ Support for dynamic keys in [**Link component**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/typography#link) URL property across all platforms\
✅ Added property on View for enabling or disabling row selection in tasks table

### Support for dynamic keys in Link component URL property

You can now use dynamic keys in the Link component's URL property across all platforms (Web, iOS, and Android). This enhancement allows you to dynamically construct URLs using process data, enabling more flexible navigation patterns in your applications.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)

### Task Manager rowSelection property on view

A new "Enable row selection" property has been added to Task Manager views, enabling you to control row selection behavior in task tables.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enable_row_select.png)

## Bug fixes

> [accordion] \[Designer] Merge fails if one branch contains past merges
>
> Fixed an issue where merging branches that contain multiple past merge commits would fail with an error. The merge conflict resolution now properly handles complex merge histories when adding values to enumerations or making other configuration changes.

> [accordion] \[CMS] Enumerations retrieve content endpoint should return content from dependencies
>
> Resolved an issue where the CMS enumerations Kafka endpoint only returned content from the local project and not from library dependencies. The endpoint now correctly retrieves enumeration content from both the current project and all dependency libraries.

> [accordion] \[Task Manager] Table doesn't use the current language
>
> Fixed localization issue in Task Manager where table content wasn't respecting the current language setting. Task Manager tables now properly use the selected language for all displayed content.

> [accordion] \[UI Designer]\[Angular]\[React] Modal fixed height is not applied
>
> Resolved an issue where setting a modal's height to "fixed" would not apply correctly in Angular and React renderers. Fixed height configuration now works as expected for modal components.

> [accordion] \[UI Designer]\[Angular] Fixed container should use overflow-y auto instead of scroll
>
> Fixed styling issue where fixed-height containers incorrectly used `overflow-y: scroll` instead of `overflow-y: auto`. Containers now only show scrollbars when content exceeds the container height.


# Deployment guidelines v5.0.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/deployment-guidelines-v5.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.29.2** | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.25.2** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.21.2** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.14.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.17.2** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.14.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.12.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.15.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.11.0** | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.26.2** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.11.0** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.14.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.11.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | |

### Embedded components

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **SpiceDB** | **1.42.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **DGraph** | **25.0.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

### Renderers

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.3** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.0.12** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.0.0 | Keycloak | 26+ |
| 5.0.0 | Kafka | 3.8 - 3.9 |
| 5.0.0 | PostgreSQL | 16 - 17 |
| 5.0.0 | Oracle Database | 21c, 23ai |
| 5.0.0 | MongoDB | 7 - 8 |
| 5.0.0 | Redis | 7.4 - 8.0 |
| 5.0.0 | Elasticsearch | 8 - 9 |
| 5.0.0 | Angular (Web SDK) | 19.x |
| 5.0.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/configuration-and-migration

This section contains the steps in the order we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](../../../../5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The Authorization System will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

> [!NOTE]
>
> The admin user imported here is the same service account referenced in the migration prerequisites. If you followed the prerequisites page and set up the admin Keycloak user beforehand, the Authorization System will pick it up automatically during this step — no additional action is needed.

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from Application Manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.0.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | 🆕 Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Kafka Configuration

> [!NOTE]
>
> Consumer group naming standardized to kebab-case across all FlowX.AI services with new messaging features for enhanced functionality.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group naming changes

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
> | | |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Application Manager specific features

#### New environment variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | 🆕 Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | 🆕 Maximum HTTP request header size |

#### New Kafka features

> [card] Resource Update Propagation
>
> Consumer Group: `app-resource-update-propagation-group`\
> Threads: 3\
> Topic: `ai.flowx.{env}.application-version.resource.update.propagation.v1`

> [card] Build Runtime Data
>
> Consumer Group: `build-runtime-data-group`\
> Threads: 2\
> Topic: `ai.flowx.{env}.build.runtime-data.v1`

> [card] Business Rule Sync
>
> Topic: `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> Purpose: Business rule synchronization

> [card] Process Sync (Restructured)
>
> Topic: `ai.flowx.{env}.application-version.sync.process.in.v1`\
> Purpose: Enhanced process synchronization

> [card] Reusable Templates sync
>
> Topic: `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> Purpose: Reusable template synchronization

#### Kafka environment variables (optional overrides)

```bash New Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_RESOURCEUPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Business Rule Sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1

# Process Sync (restructured)
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1


# Reusable Templates sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1
```

```bash Consumer Groups theme={"dark"}
# New Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
```

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides.

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | 🆕 Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | 🆕 Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | 🆕 S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | 🆕 S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | 🆕 S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | 🆕 S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | 🆕 S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | 🆕 S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | 🆕 Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | 🆕 Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | 🆕 Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | 🆕 Redis host |
| `SPRING_REDIS_PORT` | `6379` | 🆕 Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | 🆕 Redis password |
| `SPRING_REDIS_TTL` | `5000000` | 🆕 Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | 🆕 Redis host |

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/install-services

Step-by-step installation guide for new FlowX.AI 5.0 services

FlowX.AI 5.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](/5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](/5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.6 (or newer) to 5.0.0. If you’re on an earlier version, upgrade to the latest LTS version first.

## Success factors

> [!WARNING]
>
> The following steps are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB** must be installed before any FlowX.AI services. **DGraph** is only required if you are using FlowX AI agents — if not, you can skip DGraph installation, but SpiceDB is still mandatory.
>
> > [!NOTE]
> >
> > Only DGraph can be skipped (and only if you are not using FlowX AI agents). SpiceDB is mandatory for all deployments.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices migration** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](/5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites

This section contains the steps in the order we recommend for migrating data from FlowX v4.7.x to v5.0.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.6 | FlowX.AI 5.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.0#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip installing DGraph. SpiceDB is still mandatory.

> [card] [SpiceDB setup guide](../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.0.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

Before upgrading to FlowX.AI 5.0, you must run two operations on all existing Elasticsearch indices:

1. **Update index mappings** to include the `workspaceId` field (schema change)
2. **Migrate existing documents** to assign them to the default workspace (data migration)

These operations are required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable; if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

> [!WARNING]
>
> If Elasticsearch migration is not completed correctly, some process instances may not appear in search results, data-search features might return incomplete results, and workspace-scoped queries will fail for unmigrated data. Existing resources will also not be visible or accessible within the new workspace structure.

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.0.0.

***

## Authorization System Prerequisites

Before deploying the `authorization-system` service, you must configure the organization admin user. This is a critical prerequisite for ensuring that the authentication and user management features function correctly post-upgrade.

### Steps to Configure the Organization Admin User

Follow these guides to correctly set up the organization admin user:

> [card] [Bootstrap Organization Admin](../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Organization Admin Roles & Workspace Access](../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

> [!TIP]
>
> Configuration of the organization admin user must be completed **before** deploying the authorization-system service (see the [Install Services](./install-services) section for service deployment steps).

### Pre-migration preparation

Required configuration for the authorization-system service:

* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE`= `true` (mandatory for migrations)
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME`= `<admin-username>` (recommended method, default: `admin@flowx.ai`)

The system will search for this username in Keycloak and automatically copy the user's subject ID to the authorization-system database.

**Fallback method:** If the username method fails or you prefer to specify the subject ID directly:

* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID`= `<subject-id-of-admin-user>`

> [!TIP]
>
> To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.

![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users"
    ]
  }
}
```


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.06.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.0") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.0 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.0 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.0 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.0 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.0 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# FlowX.AI 5.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025

Latest features, improvements, and bug fixes in our newest release

> [!WARNING]
>
> This release includes the following features in Tech Preview. We encourage you to try them out and share your feedback to help us improve them. Please note that Tech Preview features may change before final release.

> [tab] What's New
>
> **What's new? 🆕**
>
> 🆕 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture)\
> 🆕 [**Project Data Model (PDM)**](#project-data-model-pdm)\
> 🆕 [**FlowX.AI Database**](#flowx-ai-database)\
> 🆕 [**Multi Select UI Component**](#multi-select-ui-component)\
> 🆕 [**Library-to-Library Dependencies**](#library-to-library-dependencies)\
> 🆕 [**Data Mappers**](#data-mappers)\
> 🆕 [**Reusable Resources**](#reusable-resources)\
> 🆕 [**Files in Integration Designer**](#files-in-integration-designer)\
> 🆕 [**Rendering improvements**](#rendering-improvements)
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Major Infrastructure Changes**: Workspaces introduces SpiceDB integration and new database schemas for multi-tenant architecture.
> > >
> > > **Key Changes:**
> > >
> > > * **SpiceDB Integration**: New permission management system requiring deployment
> > >
> > > * **Database Migration**: Schema updates for workspace support
> > >
> > > * **User Storage**: Only information about FlowX.AI Designer users is stored in FlowX.AI. The stored user data is limited to: unique identifier, username, first name, last name, and email address.
> > >
> > > * **Default Workspace**: All the projects and libraries are migrated to default workspace
> > >
> > > > [!TIP]
> > > >
> > > > **Backward Compatibility**: All existing functionality preserved in default workspace
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Login Flow**: After authentication, select your workspace before accessing FlowX.AI Designer. Once inside a workspace, everything works as before.
> > >
> > > **What's New:**
> > >
> > > * **Workspace Selection**: Choose workspace after login
> > > * **Resource Isolation**: Projects, libraries, themes are workspace-specific
> > > * **Enhanced Permissions**: Fine-grained access control with user groups and ACLs
> > > * **Workspace Management**: Create and manage workspaces (admin users)
> > >
> > > **What Stays the Same:**
> > >
> > > * Process design and configuration
> > > * UI Designer capabilities
> > > * Integration patterns
> > > * All existing FlowX.AI Designer features
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Transformation**: Workspaces enables enterprise multi-tenant architecture with independent business unit governance while sharing platform capabilities.
> > >
> > > **Business Impact:**
> > >
> > > * **Faster time-to-market** for new business verticals
> > > * **Enhanced compliance** with workspace-specific controls
> > > * **Improved governance** with fine-grained access management
> > >
> > > **Enterprise Benefits:**
> > >
> > > * Business unit autonomy with shared platform
> > > * Regulatory compliance through data isolation
> > > * Centralized upgrades and maintenance
> > > * Cross-business unit resource sharing when appropriate
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Infrastructure Impact**: PDM has minimal infrastructure impact - it's a design-time feature that improves development efficiency without affecting runtime resources.
> > >
> > > > [!TIP]
> > > >
> > > > **No deployment changes required** - PDM is part of the design platform, not runtime
> > >
> > > > [!TIP]
> > > >
> > > > **Backward compatible** - Existing processes continue to work unchanged
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer**: Define data types once at project level, use everywhere. No more recreating Customer or Order objects in every process.
> > >
> > > **How to Use PDM:**
> > >
> > > 1. Navigate to Project → Config → Data Model
> > > 2. Define your business entities (Customer, Product, etc.)
> > > 3. Set governance rules (sensitive data, reporting)
> > > 4. Use these types in any process within the project
> > >
> > > **Best Practices:**
> > >
> > > * Start with core business entities
> > > * Use clear, consistent naming
> > > * Mark sensitive fields appropriately
> > > * Leverage library data types when available
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: PDM transforms how your organization manages business data definitions. Define business entities once and ensure consistency across all processes and teams.
> > >
> > > **Business Benefits:**
> > >
> > > * **Enhanced compliance** through centralized governance and data sensitivity controls
> > > * **Reduced errors** from consistent data definitions
> > >
> > > **ROI Indicators:**
> > >
> > > * Development Efficiency: Measure reduction in process creation time
> > > * Error Reduction: Track fewer data-related production issues
> > > * Maintenance Cost: Monitor time spent on data structure updates
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Infrastructure Planning Required**: FlowX.AI Database creates additional MongoDB collections and requires infrastructure planning for storage, monitoring, and backup procedures.
> > >
> > > > [!TIP]
> > > >
> > > > New microservice: NoSQL DB Runner. Check the [setup guide](/5.1/setup-guides/nosql-db-runner) for more details.
> > >
> > > **Key Considerations:**
> > >
> > > * **Storage Planning**: Monitor usage as processes adopt internal database (plan for 20-30% increase)
> > > * **Performance Monitoring**: Set up alerts for FlowX.AI Database query performance
> > > * **Backup Strategy**: Include FlowX.AI Database collections in backup procedures
> > > * **Connection Pooling**: Additional connection pools for database operations
> > > * **Memory**: Additional 256MB-512MB per FlowX.AI instance for database operations
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Integration Option**: FlowX.AI Database appears as a new Data Source type in Integration Designer, right alongside RESTful System.
> > >
> > > **When to Use FlowX.AI Database:**
> > >
> > > * Customer data lookup across processes
> > > * Shared configuration and reference data
> > > * Process-to-process communication
> > > * Caching frequently accessed data
> > > * Temporary operational data storage
> > >
> > > **How to Implement:**
> > >
> > > 1. Add Data Source node to your process
> > >
> > > 2. Select "FlowX.AI Database" as type
> > >
> > > 3. Configure collection and operations
> > >
> > > 4. Use familiar MongoDB syntax (find, insert, update)
> > >
> > > > [!WARNING]
> > > >
> > > > **When NOT to Use**: Don't replace your core business systems. FlowX.AI Database is perfect for operational data, caching, and inter-process communication - but your CRM, ERP, and other systems of record should remain your primary data sources.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: FlowX.AI Database enables new operational patterns that were previously complex or impossible. It's not about replacing your core systems, but about enabling new ways to orchestrate business processes.
> > >
> > > **New Business Capabilities:**
> > >
> > > * **Cross-process workflows**: Loan application → Credit check → Approval across different process instances
> > > * **Real-time dashboards**: Operational data for business monitoring without system integration
> > > * **Agile experimentation**: Test new business rules without impacting core systems
> > > * **Process orchestration**: Complex business flows spanning multiple departments
> > >
> > > **ROI Considerations:**
> > >
> > > * **Time to Market**: Faster implementation of new business processes
> > > * **Agility**: Rapid prototyping and testing of business ideas
> > >
> > > **Use FlowX.AI Database when:**
> > >
> > > * Data is operational and process-specific (not master data)
> > > * You need rapid implementation without IT system changes
> > > * Process instances need to communicate with each other
> > > * You're prototyping new business capabilities
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **No Infrastructure Impact**: Multi Select is a pure UI component with no backend requirements. It works with existing form handling and data storage mechanisms.
> > >
> > > > [!TIP]
> > > >
> > > > **Zero deployment overhead** - Component is part of the UI framework upgrade
> > >
> > > > [!TIP]
> > > >
> > > > **Existing data handling** - Uses standard array storage, no schema changes needed
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Easy Integration**: Multi Select works just like other form elements in UI Designer. Drag, drop, configure - no new learning curve required.
> > >
> > > **Common Use Cases:**
> > >
> > > 1. **Skills Selection**: Job applications, team member profiles, contractor skills
> > > 2. **Product Features**: Insurance coverage options, software licensing features
> > > 3. **Categories & Tags**: Document classification, customer segmentation
> > >
> > > **Key Configuration:**
> > >
> > > * **Max selections**: Control input limits
> > > * **Display format**: Chips, lists, custom
> > > * **Search**: Filter large option sets
> > > * **Clear all**: Easy reset functionality
> > > * **Validation**: Min/max rules
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **User Experience Impact**: Multi Select eliminates user frustration in scenarios where single selection doesn't match real-world needs. This improves data quality and user satisfaction.
> > >
> > > **Before vs After:**
> > >
> > > * ❌ **Before**: "I can only select one skill, but I have multiple certifications"
> > > * ✅ **After**: "Perfect! I can select all my relevant skills at once"
> > >
> > > **Business Process Examples:**
> > >
> > > * **Employee Onboarding**: Select multiple skills, certifications, department access
> > >
> > > * **Product Configuration**: Select multiple features, add-ons, support packages
> > >
> > > * **Customer Preferences**: Select multiple communication channels, product interests
> > >
> > > > [!TIP]
> > > >
> > > > **Analytics Benefit**: Multi-select data provides richer analytics. Instead of knowing a customer chose "Primary Interest: Technology," you know they selected "AI, Cloud Computing, Cybersecurity, Mobile Development" - much more actionable for business intelligence.
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backwards Compatibility**: FlowX.AI 5.0 maintains full backwards compatibility with existing project-to-library dependencies from FlowX.AI 4.x. All existing dependencies will continue to work without modification.
> > >
> > > **Upgrade Process:**
> > >
> > > 1. **Existing dependencies** will be automatically migrated
> > >
> > > 2. **New library dependency features** become available immediately
> > >
> > > 3. **No breaking changes** to existing functionality
> > >
> > > 4. **Enhanced validation** may catch previously undetected issues
> > >
> > > > [!WARNING]
> > > >
> > > > **Post-Migration Required**: After the lib2lib migration is executed, you must clear the cache. This is necessary because a new field is added to the build mongo document.
> > >
> > > **Cache Clearing Steps:**
> > >
> > > 1. Complete the lib2lib migration process
> > > 2. Clear the application cache to ensure the new build document fields are properly recognized
> > > 3. Verify that library-to-library dependencies are functioning correctly
> > >
> > > **Key Changes:**
> > >
> > > * **Build Export Changes**: Build exports now automatically include entire dependency trees (larger packages but self-contained)
> > > * **Dependency Validation**: Build process now checks for dependency conflicts (enhanced validation may catch previously undetected issues)
> > > * **Deployment Consistency**: Single-version constraint prevents runtime conflicts (more predictable deployments)
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Enhanced Organization**: You can now create more sophisticated library structures where specialized libraries build upon common foundations. This reduces duplication and improves consistency.
> > >
> > > **How It Works:**
> > >
> > > 1. Navigate to Library → Config → Dependencies
> > > 2. Add other libraries as dependencies
> > > 3. FlowX.AI validates for conflicts automatically
> > > 4. Resources from all dependency levels become available
> > >
> > > **Best Practices:**
> > >
> > > * Plan your library hierarchy before implementation
> > >
> > > * Keep dependencies focused and purposeful
> > >
> > > * Avoid circular dependencies
> > >
> > > * Use semantic versioning consistently
> > >
> > > * Document dependency relationships clearly
> > >
> > > > [!NOTE]
> > > >
> > > > **Example**: Create a "US Banking Library" that depends on "Global Banking Library" and "US Compliance Library". This way, US-specific processes get both global banking functionality and local compliance requirements automatically.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Enterprise Architecture**: Library-to-Library Dependencies enable sophisticated organizational structures where different teams can own specific business domains while building on shared foundations.
> > >
> > > **Enterprise Use Cases:**
> > >
> > > **Multi-Country Operations:**
> > > Global Insurance Company: US-specific library depends on Global Compliance library
> > >
> > > ```
> > > US Insurance Library → Global Compliance Library → Base Insurance Library
> > > ```
> > >
> > > **Product Line Specialization:**
> > > Bank: Mortgage processes use specialized libraries that extend common banking operations
> > >
> > > ```
> > > Mortgage Library → Lending Library → Core Banking Library
> > > ```
> > >
> > > **Business Impact:**
> > >
> > > * **Team Autonomy**: Teams work independently while leveraging shared assets
> > >
> > > * **Faster Innovation**: New products build on proven foundation components
> > >
> > > * **Risk Reduction**: Tested, validated components reduce implementation risk
> > >
> > > > [!WARNING]
> > > >
> > > > **Change Management**: This capability requires coordination between teams. Establish clear ownership models, communication protocols, and upgrade procedures before implementing complex dependency hierarchies.
>
> ***
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **Zero Infrastructure Impact**: Data Mappers is a design-time feature that enhances the FlowX.AI Designer interface without requiring additional infrastructure or deployment changes.
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backward Compatibility**: All existing data transfer mechanisms (like `append to parent process` or `output.[outputKey]`) continue to work unchanged. Teams can adopt Data Mappers at their own pace.
> > >
> > > **Key Points:**
> > >
> > > * **No new microservices** - Enhancement to existing designer interface
> > > * **No runtime changes** - Data mapping occurs at design time
> > > * **Existing configurations preserved** - Zero impact on current implementations
> > > * **Optional adoption** - Teams choose when and where to use new functionality
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer for Integration**: No more complex syntax for data transfers. Visual drag-and-drop interface makes component integration intuitive and error-free.
> > >
> > > **How to Use Data Mappers:**
> > >
> > > 1. **Define Parameters**: Set input/output parameters on Start/End nodes
> > > 2. **Choose Implementation**: Select "Data Mapper" or "Current" method
> > > 3. **Visual Mapping**: Drag source parameters to destination parameters
> > > 4. **Save Configuration**: Store mappings for reuse and maintenance
> > >
> > > **When to Use:**
> > >
> > > * **Call Activities**: Passing data between parent and child processes
> > >
> > > * **Integration Workflows**: Connecting with external systems
> > >
> > > * **Complex Data Flows**: When visual mapping improves clarity
> > >
> > > * **Team Collaboration**: When multiple people work on integration logic
> > >
> > > > [!WARNING]
> > > >
> > > > **Parameter Changes**: When you modify input/output parameters, existing mappings must be manually updated. Changes don't automatically propagate to avoid unintended data flow modifications.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: Data Mappers transforms technical integration tasks into visual, business-friendly workflows. Non-technical stakeholders can now understand and validate data flows between business processes.
> > >
> > > **Business Impact:**
> > >
> > > * **Reduced Errors**: Visual mapping prevents data integration mistakes that cause process failures
> > > * **Faster Development**: Intuitive interface accelerates process configuration and testing
> > > * **Better Documentation**: Visual data flows serve as living documentation of business logic
> > > * **Team Collaboration**: Business and technical teams can discuss data flows using the same visual interface
> > >
> > > **ROI Indicators:**
> > >
> > > * **Development Speed**: Measure reduction in integration configuration time
> > > * **Error Rate**: Track fewer data-related production issues
> > > * **Team Efficiency**: Monitor cross-functional collaboration improvements
> > > * **Process Quality**: Assess improvement in first-time-right deployments
> > >
> > > **Use Cases by Industry:**
> > >
> > > * **Banking**: Loan application data flowing from customer intake → credit check → approval process
> > > * **Insurance**: Claim data mapping from initial report → investigation → settlement
> > > * **Manufacturing**: Order data flowing from sales → production planning → fulfillment
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Minimal Infrastructure Impact**: Reusable Resources is primarily a design-time enhancement that leverages existing FlowX infrastructure with minimal additional overhead.
> > >
> > > **Infrastructure Considerations:**
> > >
> > > * **Execution Context**: Functions execute within existing process engine contexts - no additional runtime infrastructure required
> > >
> > > > [!TIP]
> > > >
> > > > **No New Microservices**: Features are integrated into existing FlowX.AI platform components
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Development Game Changer**: Access the new "Reusable Resources" section in FlowX.AI Designer - located alongside "Reusable Functions" - to eliminate 60-80% of repetitive development work.
> > >
> > > **Key Capabilities:**
> > >
> > > * **Data Model Support**: Full integration with Project Data Model (PDM)
> > > * **Action Scenarios**: Template-defined actions assigned during instantiation OR form-centric actions handled by User Task
> > > * **Omnichannel**: Templates work across web, mobile, and other channels
> > >
> > > **Best Practices:**
> > >
> > > * **Start with common patterns**: Identify frequently repeated business logic and UI components
> > > * **Test thoroughly**: Use interactive testing for functions and preview mode for templates
> > > * **Document usage**: Include clear descriptions and example use cases
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Revolutionary Business Impact**: Reusable Resources fundamentally changes how organizations approach process development, transforming from "build every time" to "build once, leverage everywhere."
> > >
> > > **Strategic Business Value:**
> > >
> > > * **Quality Assurance**: Dramatic reduction in defects through reusable, tested components
> > > * **Maintenance Efficiency**: Update business rules once to instantly affect all processes
> > > * **Team Productivity**: Developers focus on new business capabilities instead of repetitive development
> > > * **Consistency**: Ensure uniform business rules and user experience across all touchpoints
> > >
> > > **Industry Use Cases:**
> > >
> > > * **Functions**: KYC validation, credit scoring, fraud detection, regulatory compliance checks
> > >
> > > * **UI Templates**: Customer onboarding forms, document upload sections, account summary dashboards, loan application interfaces
> > >
> > > * **Functions**: Premium calculations, risk evaluation, claims processing, policy validation
> > >
> > > * **UI Templates**: Quote request forms, claims submission interfaces, policy comparison tables, agent dashboards
> > >
> > > * **Functions**: Patient eligibility checks, treatment authorization, billing calculations, compliance validation
> > >
> > > * **UI Templates**: Patient registration forms, appointment scheduling interfaces, medical history cards, provider dashboards
>
> ### **Files in Integration Designer**
>
> > [card] File Handling in Integration Designer
> >
> > FlowX.AI 5.0 introduces native file handling capabilities in Integration Designer, enabling seamless file uploads and downloads with external systems directly within your integration workflows.
> >
> > > [card] Download Files
> > >
> > > Call external APIs and receive files in the response. Integration Designer saves files to Document Plugin or S3 and returns paths for further processing.
> >
> > > [card] Upload Files
> > >
> > > Send files stored in Document Plugin or S3 to external APIs via multipart/form-data or single binary requests.
> >
> > > [card] Multiple Formats
> > >
> > > Support for JSON responses with Base64 encoded files and single binary responses with automatic file identification.
> >
> > > [card] Flexible Storage
> > >
> > > Configure file destinations to Document Plugin (process-linked) or S3 Protocol (custom buckets) based on your needs.
> >
> > [Learn more about File Handling in Integration Designer](../../../5.1/docs/platform-deep-dive/integrations/integration-designer#file-handling)
> >
> > New Feature
>
> ### **Rendering Improvements**
>
> > [card] UI/UX Enhancements
> >
> > > [tab] Grid & Layout Improvements
> > >
> > > > [card] Enhanced Grid Component
> > > >
> > > > Improved performance, responsiveness, and customization options for data display and form organization
> > >
> > > > [card] Navigation Areas Redesign
> > > >
> > > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> > >
> > > > [card] Multi Actions Support
> > > >
> > > > Batch operations support for UI components, enabling simultaneous actions on multiple elements
> > >
> > > > [card] Permission-Based UI Editing
> > > >
> > > > Granular control over UI element editing based on user permissions with partial editing capabilities
> >
> > > [tab] Enhanced Form Controls
> > >
> > > > [card] Input Type Code
> > > >
> > > > Specialized input component for code entry
> > >
> > > > [card] Formatting Options
> > > >
> > > > Advanced formatting capabilities for Input and Slider components
> > >
> > > > [card] Switch Variants
> > > >
> > > > Enhanced switch component supporting both toggle and checkbox variants
> > >
> > > > [card] Disabled Options on Selectors
> > > >
> > > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > > [tab] Advanced Features
> > >
> > > > [card] Custom Loader
> > > >
> > > > Configurable loading indicators for improved user experience during data operations
> > >
> > > > [card] Custom Validators
> > > >
> > > > Advanced validation logic using dynamic computed expressions
> > >
> > > > [card] File Upload Button Type
> > > >
> > > > New specialized button variant designed for file upload operations
> > >
> > > > [card] Copy Styles
> > > >
> > > > Efficiently replicate styling across multiple UI components
> >
> > > [tab] Analytics & Process
> > >
> > > > [card] Analytics Enhancements
> > > >
> > > > Custom payload support for detailed user interaction tracking and business intelligence
> > >
> > > > [card] Process End Handling
> > > >
> > > > Improved user experience when processes complete or terminate
> > >
> > > > [card] Forms in Collections
> > > >
> > > > Enhanced support for form elements within collection components
> > >
> > > > [card] Template Management
> > > >
> > > > Streamlined template organization by consolidating functionality in Reusable Resources

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.0](./deployment-guidelines-v5.0)
> >
> > Instructions for deploying FlowX.AI 5.0.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.0/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.0.0


# Deployment guidelines v5.1.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.1 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.0 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.0 → 5.1.1**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.64.3** | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **9.66.5** | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **9.36.3** | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **9.29.1** | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **9.35.1** | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **9.34.2** | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **9.23.1** | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **9.30.1** | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **9.25.1** | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **9.50.0** | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **9.22.1** | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **9.34.2** | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **9.22.1** | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Renderers

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **9.0.5** | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **9.0.3** | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.0 | 0.2.4 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.5** | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.1 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.0 processes and configurations

### What's included in 5.1.1

This maintenance release includes:

* **WCAG 2.1 Level AA compliance** across all web components (28 improvements)
* **3 customer-reported issue fixes** for production environments
* **62 proactive quality improvements** identified through internal testing
* **Platform enhancements** for SSE handling, CMS tags, and infrastructure

For detailed information on all changes, see the [FlowX.AI 5.1.1 Release Notes](./v5.1.1-november-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.1 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.1 | PostgreSQL | 16 - 17 |
| 5.1.1 | Oracle Database | 21c, 23ai |
| 5.1.1 | MongoDB | 7 - 8 |
| 5.1.1 | Redis | 7.4 - 8.0 |
| 5.1.1 | Elasticsearch | 8 |
| 5.1.1 | Angular (Web SDK) | 19.x |
| 5.1.1 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.2 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.1 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.1 → 5.1.2**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **process-engine** | **9.67.0** | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **9.68.1** | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **9.39.0** | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **9.28.1** | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **9.29.0** | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **9.32.0** | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **9.37.1** | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **9.25.1** | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **9.33.0** | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **9.28.0** | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **9.52.1** | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **9.26.0** | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **9.24.1** | 9.22.1 | 9.21.0 | 9.11.0 |

### Renderers

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **9.0.7** | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **9.0.5** | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.0 |

### AI Platform

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.6** | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.2 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.1 processes and configurations

### What's included in 5.1.2

This maintenance release includes:

* **Bug fixes** addressing customer-reported issues
* **Stability improvements** for platform reliability
* **Quality enhancements** identified through internal testing

For detailed information on all changes, see the [FlowX.AI 5.1.2 Release Notes](./v5.1.2-december-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.2 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.2 | PostgreSQL | 16 - 17 |
| 5.1.2 | Oracle Database | 21c, 23ai |
| 5.1.2 | MongoDB | 7 - 8 |
| 5.1.2 | Redis | 7.4 - 8.0 |
| 5.1.2 | Elasticsearch | 8 |
| 5.1.2 | Angular (Web SDK) | 19.x |
| 5.1.2 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.3 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.2 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.2 → 5.1.3**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **process-engine** | **9.70.1** | 9.67.0 | 9.64.3 | 9.63.0 |
| **admin** | **9.70.2** | 9.68.1 | 9.66.5 | 9.65.0 |
| **designer** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **cms-core** | **9.41.1** | 9.39.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **9.30.1** | 9.28.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **9.31.2** | 9.29.0 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **9.34.1** | 9.32.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **9.39.1** | 9.37.1 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **9.38.2** | 9.36.1 | 9.34.2 | 9.33.0 |
| **data-search** | **9.27.1** | 9.25.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **9.35.1** | 9.33.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **9.30.2** | 9.28.0 | 9.25.1 | 9.24.0 |
| **integration-designer** | **9.54.1** | 9.52.1 | 9.50.0 | 9.49.1 |
| **application-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **data-sync** | **9.28.1** | 9.26.0 | 9.22.1 | 9.21.0 |
| **authorization-system** | **9.38.1** | 9.36.1 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **9.26.1** | 9.24.1 | 9.22.1 | 9.21.0 |

### Renderers

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **9.0.8** | 9.0.7 | 9.0.5 | 9.0.4 |
| **Android renderer** | **9.0.6** | 9.0.5 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.7** | 9.2.6 | 9.2.5 | 9.2.4 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.3 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes required\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.2 processes and configurations

### Optional configuration

A new optional environment variable is available for process-engine:

| Variable | Description | Default |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from platform components | Falls back to `KAFKA_TOPIC_PATTERN` |

> [!NOTE]
>
> This allows connectors to use custom topic patterns without affecting other components like document-plugin, data-search, and cms-core that use `ai.flowx.engine.receive.*`.

### What's included in 5.1.3

This maintenance release includes:

* **Security fixes**
* **Bug fixes** addressing customer-reported issues

For detailed information on all changes, see the [FlowX.AI 5.1.3 Release Notes](./v5.1.3-january-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.3 | Keycloak | 26+ |
| 5.1.3 | Kafka | 3.8 - 3.9 |
| 5.1.3 | PostgreSQL | 16 - 17 |
| 5.1.3 | Oracle Database | 21c, 23ai |
| 5.1.3 | MongoDB | 7 - 8 |
| 5.1.3 | Redis | 7.4 - 8.0 |
| 5.1.3 | Elasticsearch | 8 |
| 5.1.3 | Angular (Web SDK) | 19.2 |
| 5.1.3 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/deployment-guidelines-v5.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.63.0** | 9.29.2 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.65.0** | 9.25.2 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.35.0** | 9.21.2 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.28.0** | 9.14.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.34.0** | 9.17.2 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.33.0** | 9.14.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.22.0** | 9.12.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.29.1** | 9.15.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.24.0** | 9.11.0 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.49.1** | 9.26.2 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.21.0** | 9.11.0 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.33.0** | 9.14.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.21.0** | 9.11.0 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.4** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.2** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | **0.2.4** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.4** | 9.2.3 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.3.1** | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.0 | Keycloak | 26+ |
| 5.1.0 | Kafka | 3.8 - 3.9 |
| 5.1.0 | PostgreSQL | 16 - 17 |
| 5.1.0 | Oracle Database | 21c, 23ai |
| 5.1.0 | MongoDB | 7 - 8 |
| 5.1.0 | Redis | 7.4 - 8.0 |
| 5.1.0 | Elasticsearch | 8 - 9 |
| 5.1.0 | Angular (Web SDK) | 19.x |
| 5.1.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/configuration-and-migration

This section contains the steps in order that we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](/5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.1.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.1.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.1.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The auth-system will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from app-manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Document plugin

> [!NOTE]
>
> New configuration option for test documents bucket customization.

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILE_STORAGE_TEST_FILES_BUCKET` | `-test-documents` | Overrides the default test documents bucket suffix. Use this to configure a custom bucket name for test files. |

> [!NOTE]
>
> This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed.

## Kafka configuration

> [!NOTE]
>
> Complete Kafka migration including consumer group standardization to kebab-case, comprehensive topic restructuring with new versioned naming patterns, and enhanced messaging features across all FlowX.AI services.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group migrations

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Kafka topic migrations

> [!NOTE]
>
> All Kafka topics migrate to versioned naming pattern `ai.flowx.{env}.{service}.{operation}.v1` for improved organization and future compatibility.

> [tab] Application Manager
>
> **Application resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
>
> **Sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS_IN` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE_IN` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE_IN` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN` | `ai.flowx.application-version.sync.out.v1` |
>
> **Resource update propagation:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | `ai.flowx.application-version.resource.update.propagation.v1` |
>
> **Build resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

> [tab] Admin
>
> **Consumer groups:**
>
> | Environment Variable | New Consumer Group | Threads |
> | - | - | - |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_SYNC` | `process-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC` | `business-rule-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC` | `reusable-template-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION` | `processCorrectionAfterAppOperationGroup` | `6` |
>
> **Application sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE` | `ai.flowx.application-version.sync.out.v1` |
> | `KAFKA_TOPIC_APPLICATION_PROCESS_SYNC` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
>
> **Application correction after app operation topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
>
> **Build topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

### New Kafka features

> [card] Resource Update Propagation
>
> **Consumer Group:** `app-resource-update-propagation-group`\
> **Threads:** 3\
> **Topic:** `ai.flowx.{env}.application-version.resource.update.propagation.v1`\
> **Purpose:** Real-time resource change propagation

> [card] Build Runtime Data
>
> **Consumer Group:** `build-runtime-data-group`\
> **Threads:** 2\
> **Topic:** `ai.flowx.{env}.build.runtime-data.v1`\
> **Purpose:** Build process data management

> [card] Business Rule Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> **Purpose:** Enhanced business rule synchronization\
> **Consumer Group:** `business-rule-sync-group`

> [card] Process Sync Enhanced
>
> **Topic:** `ai.flowx.{env}.application-version.sync.process.in.v1`\
> **Purpose:** Improved process synchronization\
> **Consumer Group:** `process-sync-group`

> [card] Reusable Template Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> **Purpose:** Template synchronization\
> **Consumer Group:** `reusable-template-sync-group`

> [card] Correction After App Operation
>
> **Multiple Topics:** Process, business rule, and template correction\
> **Purpose:** Post-deployment resource correction\
> **Consumer Group:** `processCorrectionAfterAppOperationGroup`

### Configure environment variables

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides. Only override when custom naming is required.

```bash Application Manager Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Sync Topics
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
```

```bash Admin Topics theme={"dark"}
# Application Sync
KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE=ai.flowx.dev.application-version.sync.out.v1
KAFKA_TOPIC_APPLICATION_PROCESS_SYNC=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT=ai.flowx.dev.application-version.correction-after-app-operation.response.v1
```

```bash Consumer Groups and Threads theme={"dark"}
# Application Manager Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Admin Consumer Groups  
KAFKA_CONSUMER_GROUPID_PROCESS_SYNC=process-sync-group
KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC=business-rule-sync-group
KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC=reusable-template-sync-group
KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION=processCorrectionAfterAppOperationGroup

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
KAFKA_CONSUMER_THREADS_PROCESS_SYNC=6
KAFKA_CONSUMER_THREADS_BUSINESS_RULE_SYNC=6
KAFKA_CONSUMER_THREADS_REUSABLE_TEMPLATE_SYNC=6
KAFKA_CONSUMER_THREADS_PROCESS_CORRECTIONAFTERAPPOPERATION=6
```

### Additional Application Manager variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | Maximum HTTP request header size |

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | Redis host |
| `SPRING_REDIS_PORT` | `6379` | Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | Redis password |
| `SPRING_REDIS_TTL` | `5000000` | Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | Redis host |

## FlowX Engine

> [!NOTE]
>
> The ADVANCING controller has been redesigned with separate picking and processing operations for improved performance and resource management.

### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.

### Elasticsearch indexing configuration

> [!NOTE]
>
> Elasticsearch indexing environment variables have been updated with new naming conventions for better consistency with FlowX naming standards.

#### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEXING_TYPE` | `FLOWX_INDEXING_TYPE` | `kafka` | `kafka` |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` | `process_instance` |
| `FLOWX_INDEXING_PROCESSINSTANCE_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `FLOWX_INDEXING_PROCESSINSTANCE_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

> [!NOTE]
>
> For complete Elasticsearch indexing setup including Kafka Connect configuration and time-based partitioning, see the [Configuring Elasticsearch indexing](/5.1/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing) guide.

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.

### Development environment exception

> [!NOTE]
>
> For development environments only, `CONFIG_PROFILE` migrates to the standard Spring configuration profile variable.

| Remove This Variable | Replace With | Environment |
| - | - | - |
| `CONFIG_PROFILE` | `SPRING_CONFIG_PROFILE` | devenv only |

## SpiceDB integration

> [!NOTE]
>
> FlowX.AI 5.1 introduces SpiceDB integration for enhanced authorization capabilities across all core services.

### Services affected

The following services require new SpiceDB configuration variables:

* Admin
* Application Manager
* Audit Core
* CMS Core
* Document Plugin
* Integration Designer
* Notification Plugin
* Process Engine
* Runtime Manager
* Task Management Plugin

### New variables to add

For every CAS configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_SPICEDB_TOKEN` | *(secret)* | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Data sync updates

### Data Sync additional variables

For every Data-Sync configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_URL` | - | Authentication system URL. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME` | - | Authentication system username. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` | - | Authentication system password. |
| `FLOWX_SPICEDB_TOKEN` | - | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Kafka topic naming

### Global configuration change

| Variable | Old Default | New Default | Description |
| - | - | - | - |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | (varies) | `""` | Moved to default empty environment |

> [!NOTE]
>
> This change standardizes topic naming across environments by defaulting to an empty environment identifier.

## CORS and ingress updates

> [!WARNING]
>
> All services with Kubernetes ingress configurations now require the `Fx-Workspace-Id` header for workspace identification in multi-tenant environments.

### Standard ingress pattern

FlowX.AI v5.1 introduces a standardized ingress configuration pattern for all services. The key change is adding the `Fx-Workspace-Id` header to the CORS configuration.

**Required annotation update:**

```yaml theme={"dark"}
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
```

### Services requiring updates

All FlowX.AI services that expose ingress endpoints require this update:

| Service | Fx-Workspace-Id Required | Reference |
| - | - | - |
| Admin | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Application Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Audit Core | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Authorization System | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Events Gateway | ❌ No (SSE) | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) |
| Integration Designer | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Process Engine | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Runtime Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Task Management | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |

> [card] [Complete Ingress Configuration Guide](../../../../../5.1/setup-guides/ingress-configuration)
>
> View the complete ingress configuration pattern including:
>
> * Standard template for all services
> * Service-specific paths and rewrite rules
> * Annotation explanations
> * Troubleshooting guide
> * Environment-specific customization

> [!NOTE]
>
> **Exception:** Events Gateway does not require the `Fx-Workspace-Id` header because it handles Server-Sent Events (SSE) with different security requirements. See the [Events Gateway exception](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) section for details.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/install-services

Step-by-step installation guide for new FlowX.AI 5.1.0 services

FlowX.AI 5.1.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](../../../../../5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](../../../../../5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.

> [!WARNING]
>
> **Continuing to 5.9.x?** If 5.1.x is only an intermediate stop on your path to 5.9.x, land on the **latest available 5.1.x patch**, not 5.1.0. Data migrations and their fixes accumulate across the patches of the family, and the latest patch is the level guaranteed to carry all of them. Before starting the next migration, confirm the environment is fully functional: every service up and healthy in **FlowX.AI Designer → Platform Status**, and the data-sync job completed successfully. See the [5.1 → 5.9 migration prerequisites](/5.9/migrating-from-5.1-lts/prerequisites).

## Success factors

> [!WARNING]
>
> Take care when following the steps below are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB and DGraph** must be installed before any FlowX.AI services
>
> > [!NOTE]
> >
> > DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices (data migration)** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration (Elasticsearch indices)

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation

> [card] [Troubleshooting](./troubleshooting)
>
> Common issues and solutions for post-upgrade problems


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/prerequisites

This section contains the steps in order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.8 | FlowX.AI 5.1.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.1#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.1.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip this step.

> [card] [SpiceDB setup guide](../../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.1.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

> [!WARNING]
>
> Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.1.0 to ensure workspace functionality works correctly.

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Prerequisites for migration

Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:

```json theme={"dark"}
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
```

This mapping update is required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable, if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

### Post-migration impact

**Without proper Elasticsearch migration, you will experience:**

* Some process instances may not appear in search results
* Data-search functionality may not return complete results
* Workspace-scoped queries will fail for unmigrated data
* **Existing resources will not be visible or accessible within the new workspace structure**

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.1.0.

***

## Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).

Details on how to configure the organization admin user:

> [card] [Authorization system](../../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Workspaces access rights](../../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

***

#### Pre-migration preparation

You must configure the authorization-system service before migration. There are two supported approaches:

> [tab] Recommended: Use admin email (simpler)
>
> Set the following authorization-system environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=<username-of-admin-user>`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.

> [tab] Alternative: Use admin subject ID
>
> Set the following environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
>
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=<subject-id-of-admin-user>`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).
>
> > [!TIP]
> >
> > To get the subject ID of the admin user, extract it from the JWT token of the admin user.
>
> ![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.1.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users",
      "manage-realm"
    ]
  }
}
```

***

## Process instances migration

All active process instances will be migrated under default workspace.

> [!WARNING]
>
> For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.1.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.2") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.2 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.2 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.2 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.2 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.2 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# Post-upgrade troubleshooting
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/troubleshooting

Common issues and solutions that may occur after upgrading from FlowX v4.7.x to v5.1.0.

This section covers common issues that may occur after completing the upgrade to FlowX.AI 5.1.0 and their solutions.

## Designer login issues

### DataIntegrityViolationException error

If you cannot login to FlowX Designer after the 5.x upgrade and encounter the following error in the authorization-system logs:

```
org.springframework.dao.DataIntegrityViolationException: could not execute statement [ERROR: duplicate key value violates unique constraint "cas_user_username_key"
  Detail: Key (username)=(admin@flowx.ai) already exists.] [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; SQL [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; constraint [cas_user_username_key]
```

**Root Cause**: This error occurs because the `sub` (subject ID) is missing from JWT tokens. Starting with Keycloak version 25, the `sub` claim is not added by default to lightweight access tokens.

**Solution**: Ensure the `basic` Client Scope is created in your Keycloak Realm and added to all FlowX clients.

> [!WARNING]
>
> Since Keycloak version 25, the `sub` claim is not added by default to JWT lightweight tokens. This is a breaking change that affects FlowX.AI authentication.

### How to verify if subject ID is missing

**1. Login attempt**

Try to login to FlowX Designer and note if the login fails.

**2. Capture the token**

1. Open your browser's Developer Tools
2. Navigate to the **Network** tab
3. Attempt to login again
4. Look for a call to: `https://<your-keycloak-address>/auth/realms/flowx/protocol/openid-connect/token`
5. Copy the access token from the response

**3. Decode the token**

1. Go to [https://jwt.io/](https://jwt.io/)
2. Paste the token in the **Encoded** section
3. Check the **Payload** section for the presence of the `sub` claim

> [!TIP]
>
> If the `sub` claim is present, the token should contain a field like: `"sub": "12345678-1234-1234-1234-123456789abc"`

**4. Verify Client Scope configuration**

If the `sub` claim is missing, you need to configure the Client Scope in Keycloak:

1. Login to your Keycloak Admin Console
2. Navigate to your FlowX realm
3. Go to **Client Scopes**
4. Ensure the `basic` client scope exists and includes the `sub` claim
5. Add this client scope to all FlowX clients (FlowX Designer, Admin, etc.)

### Additional resources

> [card] [Keycloak Release Notes](https://www.keycloak.org/docs/latest/release_notes/#lightweight-access-token-to-be-even-more-lightweight)
>
> Official Keycloak documentation about lightweight access token changes

***

## Other common issues

> [!NOTE]
>
> Additional troubleshooting sections will be added as common post-upgrade issues are identified. If you encounter issues not covered here, please consult the FlowX support team.


# FlowX.AI 5.1.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025

Introducing Workspaces, Project Data Model, Library-to-Library Dependencies, Data Mappers, Reusable Resources, and more for a more efficient and flexible development experience.

**What's new? 🆕**

> [tab] Reusability
>
> Build once, use everywhere. These features transform how you develop and maintain applications by eliminating duplication and enabling sophisticated modular architectures.
>
> 🔄 [**Project Data Model (PDM)**](#project-data-model-pdm) - Define reusable data types at the project level to ensure consistency across processes\
> 🔄 [**Library-to-Library Dependencies**](#library-to-library-dependencies) - Create complex dependency trees with multiple levels of library-to-library relationships\
> 🔄 [**Data Mappers**](#data-mappers) - Visual drag-and-drop data mapping with reusable parameter definitions\
> 🔄 [**Reusable Resources**](#reusable-resources) - Create and manage UI Templates and Business Functions across multiple processes\
> 🔄 [**Files in Integration Designer**](#files-in-integration-designer) - Enhanced file management and reusability in integration workflows\
> 🔄 [**Resources Overrides**](#resources-overrides) - Localization and customization of core applications across multiple regions with centralized management\
> 🔄 [**Active Policy Overrides**](#active-policy-overrides) - User-specific and role-specific deployment policies for independent testing and controlled rollouts
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.1.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.1.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> ***
>
> ### **Files in Integration Designer**
>
> > [card] Files in Integration Designer
> >
> > > [tab] Files Overview
> > >
> > > ![Integration Designer file workflows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh.png)
> > >
> > > FlowX.AI 5.1.0 introduces comprehensive file handling capabilities in Integration Designer, resolving previous limitations where sending or receiving documents, photos, or any files via Integration Designer was not supported. This powerful enhancement enables seamless file exchange with external systems through automated workflows.
> >
> > > [tab] Core File Scenarios
> > >
> > > > [card] File Downloads
> > > >
> > > > Process calls external API (GET/POST) and receives files in response. Integration Designer saves files to specified location and returns paths to workflow
> > >
> > > > [card] File Uploads
> > > >
> > > > Process sends files stored in Document Plugin or S3 Bucket to external API via POST request. Workflow transmits file path for seamless transfer
> > >
> > > > [card] Document Plugin Integration
> > > >
> > > > Seamless integration with FlowX.AI Document Plugin for process-specific file management and organization
> > >
> > > > [card] S3 Storage Support
> > > >
> > > > Custom S3 bucket storage for files not tied to specific process instances or when Document Plugin is unavailable
> >
> > > [tab] Enhanced Capabilities
> > >
> > > **1. Automated File Exchange**
> > >
> > > Enable seamless file transfer with external systems without manual handling or complex custom integrations
> > >
> > > **2. Flexible Storage Options**
> > >
> > > Choose between Document Plugin for process-specific files or S3 Protocol for independent file operations
> > >
> > > **3. Workflow Integration**
> > >
> > > Files are automatically integrated into workflow processes with proper path management and metadata handling
> > >
> > > **4. External Service Communication**
> > >
> > > Communicate effectively with document services, AI processing systems, report generators, and CMS platforms
> >
> > > [tab] Real-World Use Cases
> > >
> > > > [accordion] Contract Generation Workflows
> > > >
> > > > **Scenario**: Generate personalized contracts using external document services
> > > >
> > > > * **Process Flow**: Send customer data → External contract service → Receive generated PDF contract
> > > > * **Integration**: Customer information flows to document generation API, completed contracts return to process
> > > > * **Storage**: Generated contracts stored in Document Plugin for process tracking and audit trails
> > > > * **Business Value**: Automated contract creation with legal template compliance and version control
> > >
> > > > [accordion] Document Processing & OCR
> > > >
> > > > **Scenario**: Process uploaded documents through external AI/OCR services
> > > >
> > > > * **Process Flow**: Upload document → AI processing service → Receive extracted data and processed files
> > > > * **Integration**: Documents sent to AI services for text extraction, classification, or compliance validation
> > > > * **Storage**: Processed documents and extracted data stored for business logic processing
> > > > * **Business Value**: Automated document processing with intelligent data extraction capabilities
> > >
> > > > [accordion] Report Generation & Analytics
> > > >
> > > > **Scenario**: Generate business reports using external reporting services
> > > >
> > > > * **Process Flow**: Send business data → Reporting service → Receive formatted reports (PDF, Excel)
> > > > * **Integration**: Business metrics and KPIs sent to specialized reporting engines
> > > > * **Storage**: Generated reports available for download and distribution workflows
> > > > * **Business Value**: Professional report generation with advanced formatting and visualization capabilities
> > >
> > > > [accordion] CMS & Content Management
> > > >
> > > > **Scenario**: Integrate with content management systems for file organization
> > > >
> > > > * **Process Flow**: Upload files → CMS integration → Organize and categorize content
> > > > * **Integration**: Files uploaded to external CMS platforms with metadata and categorization
> > > > * **Storage**: S3 Protocol ideal for CMS integrations with unassociated documents
> > > > * **Business Value**: Centralized content management with automated workflow integration
> >
> > [Learn more about Integration Designer](../../../../5.1/docs/platform-deep-dive/integrations/integration-designer)
> >
> > Major Enhancement
>
> ***
>
> ### **Resources Overrides**
>
> > [card] Resources Overrides
> >
> > > [tab] Resources Overrides Overview
> > >
> > > ![Resources Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
> > >
> > > Resources Overrides enable localization and customization of core business applications across multiple regions while maintaining centralized updates from headquarters. This powerful feature allows organizations to adapt specific business logic, compliance requirements, or local regulations without losing connection to the master application.
> >
> > > [tab] Key Features
> > >
> > > > [card] Localization Control
> > > >
> > > > Customize processes, workflows, and enumerations for different countries or regions while maintaining core functionality
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all resource overrides through the Dependencies page with comprehensive override tracking and configuration
> > >
> > > > [card] Selective Overriding
> > > >
> > > > Override only specific resources that need localization while inheriting all other updates from the main library
> > >
> > > > [card] Export/Import Support
> > > >
> > > > Automatically include override configurations in project exports and imports for seamless environment management
> >
> > > [tab] Business Benefits
> > >
> > > **1. Accelerate Global Expansion**
> > >
> > > Deploy core applications to new regions quickly by overriding only country-specific elements instead of rebuilding from scratch
> > >
> > > **2. Maintain Compliance**
> > >
> > > Adapt business logic and data handling to meet local regulatory requirements while preserving global standards
> > >
> > > **3. Preserve Investment**
> > >
> > > Continue receiving updates and improvements from headquarters without losing local customizations
> > >
> > > **4. Reduce Maintenance Overhead**
> > >
> > > Manage regional variations centrally instead of maintaining completely separate application instances
> >
> > > [tab] Supported Resource Types
> > >
> > > > [card] Process Overrides
> > > >
> > > > Customize business process logic while maintaining input/output compatibility and core workflow structure
> > >
> > > > [card] Workflow Overrides
> > > >
> > > > Replace entire workflow implementations to adapt business rules for local requirements
> > >
> > > > [card] Enumeration Overrides
> > > >
> > > > Localize value lists, dropdown options, and classification systems for regional variations
> > >
> > > > [card] Runtime Resolution
> > > >
> > > > Overrides are resolved dynamically at runtime, ensuring the correct regional version is always used
> >
> > > [tab] Real-World Applications
> > >
> > > > [accordion] Multi-National Banking
> > > >
> > > > **Scenario**: Global bank with country-specific loan approval processes
> > > >
> > > > * **Global Library**: Common loan application workflow with standard validation steps
> > > > * **Country Overrides**: Local credit scoring algorithms, regulatory compliance checks, documentation requirements
> > > > * **Business Value**: Single platform maintenance with automated compliance for each country's banking regulations
> > >
> > > > [accordion] Insurance Operations
> > > >
> > > > **Scenario**: Insurance company operating across different regulatory environments
> > > >
> > > > * **Global Library**: Standard claims processing workflow and policy management
> > > > * **Regional Overrides**: Country-specific coverage types, claim validation rules, regulatory reporting
> > > > * **Business Value**: Consistent global operations with local market adaptation and compliance
> > >
> > > > [accordion] Manufacturing & Supply Chain
> > > >
> > > > **Scenario**: Manufacturing company with different operational requirements per region
> > > >
> > > > * **Global Library**: Core production planning and inventory management processes
> > > > * **Local Overrides**: Regional supplier networks, compliance standards, environmental regulations
> > > > * **Business Value**: Standardized operations with flexibility for local business practices and regulations
> >
> > [Learn more about Resources Overrides](../../../../5.1/docs/projects/resources#resources-overrides)
> >
> > Major Enhancement
>
> ***
>
> ### **Active Policy Overrides**
>
> > [card] Active Policy Overrides
> >
> > > [tab] Active Policy Overrides Overview
> > >
> > > ![Active Policy Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap2.png)
> > >
> > > Active Policy Overrides enable user-specific and role-specific deployment policies that allow independent testing of different builds or branches without affecting the global policy. This powerful feature provides granular control over which project versions different users access in runtime environments.
> >
> > > [tab] Key Features
> > >
> > > > [card] User-Specific Policies
> > > >
> > > > Create individual policy overrides for specific users to test different builds independently
> > >
> > > > [card] Role-Based Overrides
> > > >
> > > > Apply policy overrides to entire roles for team-based testing and deployment strategies
> > >
> > > > [card] Priority-Based Resolution
> > > >
> > > > Handle conflicts when multiple overrides apply using configurable priority systems
> > >
> > > > [card] Real-Time Switching
> > > >
> > > > Switch between different project versions instantly without deployment downtime
> >
> > > [tab] Business Benefits
> > >
> > > **1. Independent Testing**
> > >
> > > Enable QA teams and developers to test different builds simultaneously without interfering with production users
> > >
> > > **2. Controlled Rollouts**
> > >
> > > Gradually deploy new features to specific user groups before full production release
> > >
> > > **3. Emergency Rollback**
> > >
> > > Quickly revert specific users to stable versions during incidents without affecting the entire system
> > >
> > > **4. Branch-Specific Development**
> > >
> > > Allow different teams to work with different development branches in shared environments
> >
> > > [tab] Override Management
> > >
> > > > [card] Policy Types
> > > >
> > > > Support for both "Latest on Branch" and specific "Build" policies with flexible branch and version selection
> > >
> > > > [card] Search & Filter
> > > >
> > > > Real-time search functionality to quickly locate specific user or role overrides
> > >
> > > > [card] Activation Control
> > > >
> > > > Enable or disable overrides without deletion for temporary testing scenarios
> > >
> > > > [card] Conflict Resolution
> > > >
> > > > Clear hierarchy: User overrides > Role overrides > Global policy with priority-based resolution
> >
> > > [tab] Real-World Scenarios
> > >
> > > > [accordion] Development Team Testing
> > > >
> > > > **Scenario**: Frontend team needs to test with latest UI changes while backend team tests API updates
> > > >
> > > > * **Override Setup**: Create role-based overrides for "Frontend Developers" and "Backend Developers"
> > > > * **Policy Configuration**: Frontend role uses latest on `ui-redesign` branch, Backend role uses `api-v2` branch
> > > > * **Business Value**: Parallel development with isolated testing environments and no cross-team interference
> > >
> > > > [accordion] Gradual Feature Rollout
> > > >
> > > > **Scenario**: New premium features need testing with select customers before full release
> > > >
> > > > * **Override Setup**: Create user-specific overrides for beta customers and internal stakeholders
> > > > * **Policy Configuration**: Beta users get latest build with premium features, others remain on stable version
> > > > * **Business Value**: Risk mitigation through controlled exposure and real-world testing feedback
> > >
> > > > [accordion] Emergency Response
> > > >
> > > > **Scenario**: Critical bug discovered in production affecting specific user workflows
> > > >
> > > > * **Override Setup**: Create high-priority role override for affected user groups
> > > > * **Policy Configuration**: Temporarily revert affected users to last stable build while others continue normally
> > > > * **Business Value**: Immediate incident response with minimal user impact and service continuity
> >
> > [Learn more about Active Policy Overrides](../../../../5.1/docs/projects/runtime/active-policy)
> >
> > Major Enhancement

> [tab] Persistence
>
> Advanced data management and storage capabilities that enable new architectural patterns and improved data governance.
>
> 🔄 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture) - Logical separation of business contexts with shared infrastructure\
> 🔄 [**FlowX.AI Database**](#flowx-ai-database) - New persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.1.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature

> [tab] Rendering Improvements & UI/UX Enhancements
>
> Enhanced user experience through improved components, better performance, and streamlined interface design.
>
> 🎨 [**Rendering Improvements & UI/UX Enhancements**](#rendering-improvements-&-ui/ux-enhancements) - Enhanced grid components, navigation redesign, advanced form controls, and analytics capabilities\
> 📋 [**Forms in Collections**](#forms-in-collections) - Enhanced support for form elements within collection components, enabling complex data entry scenarios\
> 🔄 [**Multi Select UI Component**](#multi-select-ui-component) - Allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
>
> ### **Rendering Improvements & UI/UX Enhancements**
>
> > [card] Rendering Improvements & UI/UX Enhancements
> >
> > FlowX.AI 5.1.0 delivers comprehensive UI/UX improvements that enhance the user experience across all platform components, from streamlined navigation to advanced form controls and better workflow handling.
> >
> > ## Interface & Navigation Improvements
> >
> > > [card] Enhanced Grid Component
> > >
> > > Improved performance, responsiveness, and customization options for data display and form organization
> >
> > > [card] Navigation Areas Redesign
> > >
> > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> >
> > > [card] Multi Actions Support
> > >
> > > Batch operations support for UI components, enabling simultaneous actions on multiple elements, multi select, multi copy/paste, multi drag and drop, multi delete
> >
> > > [card] [Permission-Based UI Editing](../../../../5.1/docs/building-blocks/ui-designer/ui-designer#permission-based-expressions)
> > >
> > > Granular control over UI element editing based on user permissions with partial editing capabilities, allow multiple executors on swimlane level
> >
> > ## Enhanced Form Controls & Components
> >
> > > [card] [Input Type Code](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-types)
> > >
> > > Specialized input component for code entry
> >
> > > [card] Formatting Options
> > >
> > > Advanced formatting capabilities for Input and Slider components
> >
> > > [card] [Switch Variants](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field#switch-type)
> > >
> > > Enhanced switch component supporting both toggle and checkbox variants
> >
> > > [card] [Disabled Options on Selectors](/5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select#disabled-options)
> > >
> > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > ## User Experience Enhancements
> >
> > > [card] Custom Loader
> > >
> > > Configurable loading indicators for improved user experience during data operations
> >
> > > [card] [Custom Expression Validators](../../../../5.1/docs/building-blocks/ui-designer/validators#custom-validators)
> > >
> > > Advanced validation logic using dynamic computed expressions that can reference other process data values. Write JavaScript expressions that return boolean values for cross-field validation scenarios
> >
> > > [card] File Upload Button Type
> > >
> > > Introduces a specialized button variant for file upload operations, supporting **fill**, **ghost**, and **text** types for flexible UI styling.
> >
> > > [card] Copy Styles
> > >
> > > Efficiently replicate styling across multiple UI components
> >
> > ## Workflow & Analytics Improvements
> >
> > > [card] Analytics Enhancements
> > >
> > > Custom payload support for detailed user interaction tracking and business intelligence
> >
> > > [card] Process End Handling
> > >
> > > Improved user experience when processes complete or terminate
> >
> > > [card] Template Management
> > >
> > > Streamlined template organization by consolidating functionality in Reusable Resources
>
> ***
>
> ### **Forms in Collections**
>
> > [card] Forms in Collections
> >
> > A powerful new feature that enables dynamic, repeatable forms within collection prototypes, eliminating the need for custom development when building forms with repeatable sections like co-debtors, comments, or any list of similar items.
> >
> > <video />
> >
> > ## Key Capabilities
> >
> > > [card] No Custom Development
> > >
> > > Drag Form components directly into Collection Prototypes - they automatically repeat for each item in your data array
> >
> > > [card] Flexible Validation
> > >
> > > Choose between individual item validation or bulk validation across all collection items
> >
> > > [card] Two Saving Scenarios
> > >
> > > Individual save (one item at a time) or bulk save (entire collection) with different validation behaviors
> >
> > ## Common Use Cases Solved
> >
> > **1. Dynamic Forms**
> >
> > Build forms that show different elements based on conditions without custom development
> >
> > **2. Repeatable Sections**
> >
> > Create forms with sections like adding multiple co-debtors, comments, or family members
> >
> > **3. Complex Data Entry**
> >
> > Handle arrays of objects with proper validation and data management
> >
> > **4. Real-time vs Batch Processing**
> >
> > Choose individual saves for real-time editing or bulk saves for form completion workflows
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component

> [tab] AI Platform
>
> New AI capabilities in Integration Designer for processing text, documents, images, and data using AI-powered nodes.
>
> 🤖 [**AI Nodes in Integration Designer**](#ai-nodes-in-integration-designer) - Process text, documents, images, and data using AI-powered workflow nodes
>
> ### **AI Nodes in Integration Designer**
>
> > [card] AI Nodes in Integration Designer
> >
> > > [tab] AI Nodes Overview
> > >
> > > ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
> > >
> > > FlowX.AI 5.1.0 introduces AI-powered nodes in Integration Designer, enabling intelligent processing of text, documents, images, and data within your workflows. These nodes bring AI capabilities directly into your integration flows without requiring external AI services.
> >
> > > [tab] AI Text Operations
> > >
> > > > [card] Text Transformation
> > > >
> > > > Modify text tone, complexity or formatting for better clarity or style
> > >
> > > > [card] Text Understanding
> > > >
> > > > Analyze text to determine sentiment, topics, intent, language and named entities
> > >
> > > > [card] Text Generation
> > > >
> > > > Generate new text such as summaries, completions, translations or paraphrases
> > >
> > > > [card] Text Extraction
> > > >
> > > > Extract structured information, keywords or metadata from text
> >
> > > [tab] AI Document Operations
> > >
> > > > [card] Document Generation
> > > >
> > > > Automatically build reports or complete templates based on given inputs
> > >
> > > > [card] Document Extraction
> > > >
> > > > Identify and extract structured data, entities or metadata from documents
> > >
> > > > [card] Document Understanding
> > > >
> > > > Analyze documents to extract meaning, topics, sentiment, or important information
> > >
> > > > [card] Extract Text from Document
> > > >
> > > > Extract text content from documents (OCR, PDF text extraction)
> >
> > > [tab] AI Image & Data Operations
> > >
> > > **Image Operations:**
> > >
> > > > [card] Image Description
> > > >
> > > > Generate captions or extract detailed information from visual content
> > >
> > > > [card] Image Analysis
> > > >
> > > > Recognize objects, emotions and scenes in images for contextual understanding
> > >
> > > **Data Operations:**
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Add annotations, context or relationships to enhance raw data value
> > >
> > > > [card] Data Generation
> > > >
> > > > Produce synthetic or structured data using templates and logic-based rules
> > >
> > > > [card] Data Transformation
> > > >
> > > > Clean, normalize, aggregate, or restructure datasets into usable formats
> >
> > > [tab] Use Cases
> > >
> > > > [accordion] Intelligent Document Processing
> > > >
> > > > * Extract data from invoices, contracts, and forms
> > > > * Classify documents automatically
> > > > * Validate extracted information against business rules
> > >
> > > > [accordion] Customer Communication Analysis
> > > >
> > > > * Analyze customer feedback sentiment
> > > > * Extract key topics from support tickets
> > > > * Generate personalized responses
> > >
> > > > [accordion] Content Generation
> > > >
> > > > * Create summaries of long documents
> > > > * Translate content to multiple languages
> > > > * Generate reports from structured data
> > >
> > > > [accordion] Data Processing
> > > >
> > > > * Enrich customer data with AI-derived insights
> > > > * Transform unstructured data to structured formats
> > > > * Generate test data for development
> >
> > [Learn more about AI Node Types](../../../../5.1/docs/platform-deep-dive/integrations/ai-nodes)
> >
> > New Feature

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.1](./deployment-guidelines-v5.1)
> >
> > Instructions for deploying FlowX.AI 5.1.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.1/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.1.0


# FlowX.AI 5.1.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.1-november-2025

WCAG 2.1 Level AA compliance achieved, AI Platform enhancements, bug fixes, and quality improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **accessibility compliance**, **AI Platform enhancements**, **customer issue resolution**, and **proactive quality improvements**.
> Upgrades from **5.1.0 → 5.1.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Quality Achievement**: FlowX.AI 5.1.1 demonstrates our commitment to proactive quality improvement:
>
> * **[WCAG 2.1 Level AA compliance](https://www.w3.org/TR/WCAG21/)** achieved across all web components
> * **Proactive quality improvements** identified through internal QA before reaching customers
> * **Customer issues** resolved with full business context
> * **Zero breaking changes** - fully compatible upgrade from 5.1.0
>
> This release represents months of accessibility audits, automated testing, and quality assurance work to deliver exceptional software quality.

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.1 delivers comprehensive improvements across accessibility, stability, and platform reliability.
>
> ♿  [**WCAG 2.1 Compliance Achieved**](#wcag-2-1-compliance) - Full accessibility support across all web components\
> 🌍 [**Task Management Localization**](#task-management-localization) — Comprehensive multi-language support with 51 substitution tags\
> 🤖 [**AI Platform Enhancements**](#ai-platform-enhancements) — Multi-agent system improvements and AI workflow stability\
> 🎯 [**Customer Fixes**](#customer-fixes) — Critical issues resolved based on customer feedback\
> ✨ [**Proactive Improvements**](#proactive-quality-improvements) — Issues identified through internal QA before reaching customers\
> 🔧 [**Platform Enhancements**](#platform-enhancements) — SSE handling, audit logs, and infrastructure improvements
>
> ### **WCAG 2.1 compliance**
>
> > [card] WCAG 2.1 compliance
> >
> > > [tab] Overview
> > >
> > > **FlowX.AI is now WCAG 2.1 Level AA compliant**
> > >
> > > This release delivers full accessibility support through **28 comprehensive improvements** across Angular and React SDKs, making FlowX applications usable by everyone, including users with disabilities.
> > >
> > > ### Business value
> > >
> > > > [card] Government Compliance
> > > >
> > > > Meet accessibility requirements for government and public sector applications
> > >
> > > > [card] Healthcare Standards
> > > >
> > > > Comply with healthcare industry accessibility regulations and standards
> > >
> > > > [card] Financial Services
> > > >
> > > > Satisfy financial sector requirements for inclusive digital experiences
> > >
> > > > [card] Universal UX
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those with disabilities
> > >
> > > ### What changed
> > >
> > > * All components now fully keyboard-accessible
> > > * Complete screen reader support with ARIA labels
> > > * Proper focus management across all interactions
> > > * Accessible error announcements and validation
> > > * Semantic HTML structure throughout
> >
> > > [tab] Key features
> > >
> > > > [card] Auto-bindable ARIA Tags
> > > >
> > > > Automatically bind accessibility labels, descriptions, and ARIA attributes to all UI components from Designer configuration
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Full keyboard navigation support with proper focus management, tab order, and keyboard shortcuts in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > ARIA labels, descriptions, and live regions implemented across all form elements and interactive components
> > >
> > > > [card] UI Designer Integration
> > > >
> > > > Dedicated accessibility configuration section in UI Designer for managing labels and descriptions
> >
> > > [tab] Supported components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio/Segmented buttons, Slider, and File upload with labels, descriptions, and error announcements
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card with keyboard navigation, focus management, and state announcements
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with semantic HTML structure and proper labeling
> > >
> > > **4. Platform Support**
> > >
> > > Complete implementation for Angular and React SDKs (iOS and Android in future releases)
> >
> > > [tab] Implementation details
> > >
> > > **28 Improvements Delivered:**
> > >
> > > > [accordion] Angular SDK
> > > >
> > > > * Custom keyboard navigation implementation
> > > > * Focus management for Select/Multiselect components
> > > > * Modal focus trap and restoration
> > > > * Shift+Tab handling across form elements
> > > > * Listbox keyboard operations
> > > > * Table navigation improvements
> > > > * Switch and checkbox accessibility
> > > > * File preview focus indicators
> > > > * Button Space key activation
> > > > * Link focus outlines
> > > > * Disabled element keyboard behavior
> > >
> > > > [accordion] React SDK
> > > >
> > > > * BaseUI Combobox implementation for Select/Multiselect
> > > > * Keyboard navigation with clear buttons
> > > > * Focus restoration after interactions
> > > > * Outline theming for focus indicators
> > > > * Modal auto-focus on open
> > > > * Card accordion keyboard handling
> > > > * Table row navigation
> > > > * Option highlighting in dropdowns
> > >
> > > > [accordion] UI Designer
> > > >
> > > > * Accessibility configuration panel
> > > > * Auto-bindable tags for all components
> > > > * Label and description fields
> > > > * Alt text management for images
> > > > * ARIA attribute configuration
> > > > * Accessibility section styling
> > > > * Component-specific accessibility settings
> > >
> > > > [accordion] Technical tasks completed
> > > >
> > > > * Implemented BaseUI Combobox for Select/Multiselect
> > > > * Custom keyboard navigation for Angular
> > > > * React SDK keyboard navigation with clear button
> > > > * Auto-bindable accessibility tags for all components
> > > > * Accessibility configuration panel in UI Designer
> > > > * Removed conflicting title attribute tooltips
> > > > * Aligned Stepper accessibility between frameworks
> > > > * Bind labels and descriptions to form fields
> >
> > [Learn more about Accessibility Configuration](/5.1/docs/platform-deep-dive/accessibility)
> >
> > Major Achievement
>
> ***
>
> ### **Customer fixes**
>
> > [card] Customer fixes
> >
> > We prioritized and resolved **customer-reported issues** in this release, addressing critical functionality issues and workflow inefficiencies reported via Zendesk.
> >
> > > [accordion] Action parameters lost on copy/paste
> > >
> > > **Problem:**\
> > > When copying nodes with Kafka send actions, topic and message configurations were not preserved, forcing users to manually reconfigure all action parameters after paste operations.
> > >
> > > **Customer Impact:**
> > >
> > > * Development velocity significantly reduced
> > > * Risk of configuration errors during manual re-entry
> > > * Frustration with repetitive configuration work
> > >
> > > **Resolution:**\
> > > actionParamsMap now properly persists through copy/paste operations
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create send message node with Kafka action
> > > 2. Configure topic and message parameters
> > > 3. Copy and paste the node
> > > 4. All configurations now preserved correctly
> > >
> > > **Customer Benefit:**\
> > > Faster workflow development with reduced configuration errors and improved developer experience.
> >
> > > [accordion] Orphaned warnings block process deployments
> > >
> > > **Problem:**\
> > > When deleting parent actions that had child actions with warnings, the warnings remained in the system as orphans. These orphaned warnings prevented process export/import operations and blocked build deployments.
> > >
> > > **Customer Impact:**
> > >
> > > * Build pipelines blocked by stale warnings
> > > * Deployment delays requiring manual database cleanup
> > > * Process export/import operations failed
> > > * Development and testing workflows disrupted
> > >
> > > **Resolution:**\
> > > Warnings now cascade-delete automatically when parent actions are removed
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create action with subactions containing warnings
> > > 2. Delete the parent action
> > > 3. All child warnings now properly cleaned up
> > >
> > > **Customer Benefit:**\
> > > Clean deployments without manual intervention, faster development cycles, no more blocked pipelines.
> >
> > > [accordion] Default application cannot be removed
> > >
> > > **Problem:**\
> > > Auto-generated `default_application` in new environments existed only in app\_manager schema and could not be deleted through standard operations, returning validation errors.
> > >
> > > **Customer Impact:**
> > >
> > > * Environment cleanup difficulties
> > > * Testing complications with unwanted default projects
> > > * Confusion about application lifecycle management
> > >
> > > **Resolution:**\
> > > Added proper runtime validation for application deletion operations
> > >
> > > **Error (Fixed):**
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": 400,
> > >   "message": "error.validation.runtime.application.not_found",
> > >   "title": "Runtime project not found."
> > > }
> > > ```
> > >
> > > **Customer Benefit:**\
> > > Clean environment management with predictable application lifecycle operations.
>
> ***
>
> ### **Proactive quality improvements**
>
> > [card] Proactive quality improvements
> >
> > > [tab] Overview
> > >
> > > **Issues identified and resolved proactively**:
> > >
> > > ### Quality process
> > >
> > > > [card] Accessibility Audits
> > > >
> > > > WCAG 2.1 compliance testing identified keyboard navigation and focus management improvements
> > >
> > > > [card] Automated Testing
> > > >
> > > > Continuous integration pipelines caught component behavior issues and rendering problems
> > >
> > > > [card] Internal QA
> > > >
> > > > Manual testing uncovered edge cases in form interactions and modal behaviors
> > >
> > > > [card] Code Reviews
> > > >
> > > > Peer reviews identified potential stability issues in backend processing and dependency management
> > >
> > > ### Distribution by category
> > >
> > > * **Keyboard Navigation**: Fixes across Angular and React
> > > * **Focus Management**: Fixes for modals, forms, and interactive elements
> > > * **Component Behavior**: Fixes for proper state handling and rendering
> > > * **Backend Stability**: Fixes for processing and dependency management
> >
> > > [tab] Angular SDK
> > >
> > > > [accordion] Keyboard navigation improvements
> > > >
> > > > * Fixed listbox remaining open when pressing Shift+Tab
> > > > * Fixed Shift+Tab not working on Select with search
> > > > * Fixed Multiselect tab navigation moving to first element instead of next
> > > > * Fixed Select input focus not working properly
> > > > * Fixed Select list not scrolling during keyboard navigation
> > > > * Fixed up/down arrow scrolling screen alongside option list
> > > > * Fixed focus lost after loading new user task
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed Link in message focus missing outline
> > > > * Fixed modal close button not focused automatically
> > > > * Fixed file preview focus not highlighted and lost
> > > > * Fixed button inside modal not working with Space key
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Multiselect options list not opening
> > > > * Fixed MultiSelect and link focusable when disabled
> > > > * Fixed modal dismiss buttons not working with Space key
> > > > * Fixed modal without close button not easily focusable
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Space pressed on card with accordion scrolling page
> > > > * Fixed Switch with label position start focus issues
> >
> > > [tab] React SDK
> > >
> > > > [accordion] Keyboard Navigation Improvements
> > > >
> > > > * Fixed outline from theme not applied to modal close button and links
> > > > * Fixed Select selected option not highlighted in options list
> > > > * Fixed Select search not filtering after selection
> > > > * Fixed Input/textarea/select focus lost after using clear button
> > > > * Fixed Tab focus moving inside collapsed card
> > > > * Fixed table Tab navigation skipping rows
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed file preview retry focus not highlighted and lost
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Select and link focusable when disabled
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Datepicker clear icon focus not highlighted
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed doc preview modal not closable with Enter or Space
> > > > * Fixed button inside table focus not highlighted
> > > > * Fixed Slider decimal numbers not rendered correctly
> > > > * Fixed Substepper not rendered correctly
> > > > * Fixed doc preview display mode showing inline
> > > > * Fixed cards expandable before token reaches them
> >
> > > [tab] Designer & Backend
> > >
> > > > [accordion] UI Designer Improvements
> > > >
> > > > * Fixed missing accessibility section on Link component
> > > > * Fixed missing accessibility section on Image button
> > > > * Fixed missing space in accessibility label and info icon
> > > > * Fixed Alt text field disabled styling not applied
> > > > * Fixed console errors when changing pages from header
> > > > * Fixed Select/multiselect highlighted in preview and settings tabs
> > > > * Fixed outline theming in enumerations and inputs
> > > > * Fixed Workflows info points content not rendered correctly
> > > > * Fixed Workflows tabs content not showing properly
> > > > * Fixed padding missing on RUT UI Assets panel
> > >
> > > > [accordion] Backend Stability Improvements
> > > >
> > > > * Fixed wrong navigationTree response on overridden process
> > > > * Fixed incorrect navigationTree for resource override details
> > > > * Fixed error when trying to update dependency lib versions
> > > > * Fixed error returned when updating dependency with override
> > > > * Fixed no response on out topic for start process by name from Kafka
> > > > * Fixed checkbox "Allow back to this action" status not loaded
> > > > * Fixed empty screen when logging in without workspace access
> > > > * Fixed Elasticsearch scheduled task errors with failed documents
> > > > * Fixed services not logging when Liquibase crashing due to lock
> >
> > Proactive Quality
>
> ***
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 adds comprehensive localization support for Task Management, enabling multi-language task management interfaces through 51 system substitution tags. Table grid localization is automatic.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > >
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> > >
> > > > [!NOTE]
> > > >
> > > > This feature enables complete Task Management localization for global deployments, meeting requirements for government, healthcare, and financial services applications requiring multi-language support.
> >
> > > [tab] Key features
> > >
> > > > [card] FlowX Substitution Tags (51 Keys)
> > > >
> > > > Complete set of substitution tags for task actions, statuses, history events, and UI elements
> > >
> > > > [card] Table Grid Localization
> > > >
> > > > Table grid localizes automatically based on container app language; FlowX tags configured manually in CMS
> > >
> > > > [card] Web Renderer Integration
> > > >
> > > > Angular and React renderers use system substitution tags on all task management texts
> >
> > > [tab] What's localized
> > >
> > > **FlowX Substitution Tags (51 Keys):**
> > >
> > > * Table columns (title, stage, assignee, status, priority, last updated)
> > > * Process states (created, started, finished, failed, expired, etc.)
> > > * Task actions (assign, unassign, hold, unhold, execute, start)
> > > * Bulk operations (assign to, unassign all, hold all, etc.)
> > > * History events (task created, assigned, status changed, etc.)
> > > * User selection dialogs and UI states
> > >
> > > **Table Grid Localization**:
> > >
> > > * Filters (set, text, number, date with all operators)
> > > * Menus (column, context, aggregation, sorting)
> > > * Pagination (navigation, page size, row counts)
> > > * Data types (boolean, dates, numbers with formatting)
> > > * ARIA labels for accessibility
> >
> > > [tab] Implementation details
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization based on this setting
> > >
> > > **2. Configure CMS Tags**
> > >
> > > Add translations for all 51 sys\_tm\_\* tags in CMS for each supported language - this is the only manual configuration needed
> > >
> > > **3. Use in Renderers**
> > >
> > > Web renderers automatically apply system substitution tags to all task management UI elements
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> ***
>
> ### **AI Platform enhancements**
>
> > [card] AI Platform enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 delivers significant improvements to the AI Platform, enhancing multi-agent collaboration, conversation management, and AI workflow stability. These enhancements ensure more reliable AI-assisted development workflows and better user experience.
> > >
> > > > [card] Multi-Agent System
> > > >
> > > > Enhanced agent communication and thread management for improved collaborative AI workflows
> > >
> > > > [card] Conversation Stability
> > > >
> > > > Improved conversation handling with better error propagation and session management
> > >
> > > > [card] AI Developer Tools
> > > >
> > > > Enhanced AI Developer capabilities with proper data model integration and expression generation
> > >
> > > > [card] Document Intelligence
> > > >
> > > > Multi-page document generation support and improved content handling
> >
> > > [tab] Key improvements
> > >
> > > **Multi-Agent Conversation Management:**
> > >
> > > * Enhanced conversation thread handling with proper parent action status updates
> > > * Improved backend support for adding new messages on agent threads
> > > * Better session management with new session button in Command Center
> > > * Context switching prevention during execution plan generation
> > >
> > > **AI Developer Enhancements:**
> > >
> > > * Fixed data model integration for expressions and business rules generation
> > > * Improved action target saving and destination setting
> > > * Enhanced execution plan editing from user prompts
> > > * Better handling of empty execution plans
> > >
> > > **Error Handling & Stability:**
> > >
> > > * Graceful error propagation from internal AI agent operations
> > > * Improved CORS headers for document object downloads
> > > * Enhanced telemetry support for debugging and monitoring
> > > * Better handling of plan enhancement patches
> > >
> > > **Document & Content Features:**
> > >
> > > * Multi-page document generation support in AI nodes
> > > * Source selector component for image and document inputs
> > > * Improved messaging system for AI agents in command center
> > > * Enhanced UI feedback for AI-generated resources
> >
> > > [tab] Technical improvements
> > >
> > > **Backend Enhancements:**
> > >
> > > * Continuous patching support for action contexts during execution
> > > * Improved navigation tree responses for overridden processes
> > > * Enhanced dependency management for library overrides
> > > * Better error handling and logging across AI services
> > >
> > > **Frontend Improvements:**
> > >
> > > * Fixed target selector closing behavior in implementation threads
> > > * Improved preview mode handling after developer changes
> > > * Enhanced command center messaging and error display
> > > * Better UI state management for AI workflow interactions
> > >
> > > **Integration Updates:**
> > >
> > > * CORS headers properly configured for GraphQL object downloads
> > > * Process task destinations automatically set to current process
> > > * Improved integration between AI agents and execution plans
> > > * Enhanced audit logging for resource overrides
> >
> > AI Platform
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform enhancements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] SSE Disconnect Handling
> > > >
> > > > Improved Server-Sent Events disconnect handling to reduce error log flooding when clients disconnect
> > >
> > > > [card] Resource Overrides Audit
> > > >
> > > > Implemented audit logs for library resource overrides to track configuration changes
> > >
> > > > [card] Security Updates
> > > >
> > > > Fixed high vulnerabilities in Designer 5.1.x and main branch
> >
> > > [tab] Renderer Enhancements
> > >
> > > > [card] System Substitution Tags
> > > >
> > > > Web renderers now use system substitution tags on all task management texts
> > >
> > > > [card] Outline Theming
> > > >
> > > > Enhanced outline and select/multiselect option highlight theming for visual consistency
> >
> > > [tab] Technical Improvements
> > >
> > > **Code Quality:**
> > >
> > > * Eliminated deprecated code for Kafka start process
> > > * Improved error handling for Elasticsearch document updates
> > > * Enhanced dependency management for library overrides
> > > * Better logging and error reporting across services
> > >
> > > **Performance:**
> > >
> > > * Optimized SSE connection handling
> > > * Improved query performance for navigation tree
> > > * Better resource management in long-running processes
> >
> > Platform Updates

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.1 is fully compatible with 5.1.0. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.0 → 5.1.1 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Android and iOS accessibility properties implementation
> > * Additional Select component refinements
> > * UI Designer padding optimizations
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and critical bug fixes
> * Accessibility enhancements for mobile platforms
> * Performance optimizations
>
> Major new features are planned for future releases in the 5.x series. See the [5.2.0 release notes](../v5.2.0-november-2025/v5.2.0-november-2025) for upcoming capabilities.


# FlowX.AI 5.1.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.2-december-2025

Bug fixes, stability improvements, and quality enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes**, **stability improvements**, and **quality enhancements**.
> Upgrades from **5.1.1 → 5.1.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.2 provides continued quality, stability, and reliability for the platform:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * New features and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.2 delivers maintenance improvements focused on stability, reliability, and feature enhancements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — issues resolved including customer-reported and proactive fixes\
> ✨ [**New Features**](#new-features) — enhancements including new features and platform improvements\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure and stability enhancements
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Authorization service configuration
> > > >
> > > > **Problem:**\
> > > > Wrong service account client secret config parameter was used in Authorization service, causing authentication failures.
> > > >
> > > > **Resolution:**\
> > > > Fixed configu gration parameter mapping for service account client secret in Authorization service
> > >
> > > > [accordion] Token state changes on back navigation
> > > >
> > > > **Problem:**\
> > > > When performing back in steps actions, tokens incorrectly changed from Aborted to Active state when lazy actions finished.
> > > >
> > > > **Resolution:**\
> > > > Fixed token state management during back navigation to preserve correct state
> > >
> > > > [accordion] Action parameters not copied on node copy
> > > >
> > > > **Problem:**\
> > > > When copying nodes with child actions, action parameters (like Kafka topic and message configurations) were not preserved.
> > > >
> > > > **Resolution:**\
> > > > Fixed actionParamsMap persistence through copy/paste operations
> > >
> > > > [accordion] Permissions updated incorrectly during action execution
> > > >
> > > > **Problem:**\
> > > > hideRules and disableRules values were incorrectly updated in database when executing actions, causing permission issues.
> > > >
> > > > **Resolution:**\
> > > > Fixed permission rule handling during action execution
> > >
> > > > [accordion] Subprocess data mapping issues
> > > >
> > > > **Problem:**\
> > > > Starting subprocess with legacy mapping caused data to be incorrectly appended instead of replaced.
> > > >
> > > > **Resolution:**\
> > > > Fixed data mapping behavior for subprocess start actions
> > >
> > > > [accordion] Forms in collections - action not found
> > > >
> > > > **Problem:**\
> > > > When saving data from outside collection with forms to submit, actions were not found correctly.
> > > >
> > > > **Resolution:**\
> > > > Fixed action resolution for forms inside collections
> >
> > > [tab] AI Platform fixes
> > >
> > > > [accordion] AI Designer improvements
> > > >
> > > > * Fixed no feedback when uploading large documents in command center
> > > > * Fixed targets for business rules never being set by planner
> > > > * Fixed file upload limit lower than 3MB
> > > > * Fixed missing messages on Keep/Discard buttons for UI and BR
> > > > * Fixed Save & Close button not working in Data Model modal
> > > > * Fixed DM keys not created after keeping UI
> > > > * Fixed table key appearing as mapped when Data Model is empty
> > > > * Fixed pip window being clipped
> > > > * Fixed Submit prompt button color not indicating active state
> > > > * Fixed source not indicating uploaded document for some Plan actions
> > > > * Fixed UI outcome duplication until connected-graph keep method finishes
> > > > * Fixed missing scrollbar in Context Documents modal with multiple subprocesses
> > > > * Fixed command center not reopenable after closing in developer preview mode
> > > > * Fixed planner sample data import crashes
> > > > * Fixed business logic targets not correctly stored in execution plan
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Web renderer improvements
> > > >
> > > > * Fixed hide subprocess navigation closing parent navigation with multiple hierarchies
> > > > * Fixed card collapsing when next nav area is modal (Angular & React)
> > > > * Fixed card not expandable after finishing subprocess started from it (Angular & React)
> > > > * Fixed loader missing or not fully shown in React
> > > > * Fixed message icon and text rendered on different rows when width fill in React
> > > > * Fixed collection prototype shown when collection source array doesn't exist in React
> > > > * Fixed broken image rendered when missing url or base64 image in React
> > > > * Fixed switch component knob and container alignment in React
> > > > * Fixed multi select search not filtering available options in React SDK
> > > > * Fixed custom component keys duplicated in action body (React & Angular)
> > >
> > > > [accordion] Task Manager fixes
> > > >
> > > > * Fixed Task Manager theming not applied in Angular
> > > > * Fixed Task Manager header theming not applied in React
> > > > * Fixed assignee dropdown list and placeholder not displayed in React
> > >
> > > > [accordion] Reusable templates fixes
> > > >
> > > > * Fixed custom body being null at runtime for Reusable templates actions
> >
> > > [tab] Platform & Data fixes
> > >
> > > > [accordion] Data model and mappers
> > > >
> > > > * Fixed input/output parameters not deleted after updating parameters
> > > > * Fixed Go to reference button redirecting incorrectly
> > > > * Fixed parameters items deleted when updating Project Data Model object
> > >
> > > > [accordion] Process Designer
> > > >
> > > > * Fixed retry token button available for inactive tokens
> > > > * Fixed missing save action button when opening action config from UI designer
> > >
> > > > [accordion] Platform stability
> > > >
> > > > * Fixed advancing errors in partition event table
>
> ***
>
> ### **New features**
>
> > [card] New features
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation
> > > >
> > > > Generate Data Model for tables and table columns from AI Designer
> >
> > > [tab] Renderers
> > >
> > > > [card] Android Accessibility
> > > >
> > > > Accessibility properties from UI Designer now supported in Android renderer
> > >
> > > > [card] Substitution Tags in Selectors
> > > >
> > > > Selectors (checkbox, radio, select, multiselect) now support substitution tags when source type is process data across Angular, React, and iOS renderers
> > >
> > > > [card] Template Caching
> > > >
> > > > Improved caching for reusable templates at runtime
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Dgraph Upgrade
> > > >
> > > > Bring dgraph to flowx-release
> >
> > > [tab] Performance & Optimization
> > >
> > > > [card] Designer Static Assets
> > > >
> > > > Make designer nginx use compression & caching for static assets

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.2 is fully compatible with 5.1.1. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.1 → 5.1.2 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.2](./deployment-guidelines-v5.1.2).
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Task Manager theming issues in Angular and React
> > * Task Manager assignee dropdown display issues in React
> > * Custom component key duplication in action body
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# Release Notes
Source: https://docs.flowx.ai/release-notes/overview

What shipped in every FlowX.AI release - new features, bug fixes, deployment guidelines, and migration steps for the 5.9.x and 5.1.x LTS lines and monthly feature releases.

Release notes · FlowX.AI

What shipped.
Every release, every line.

What shipped in every FlowX.AI release: new features, bug fixes, deployment guidelines, and migration steps. Pick your line below, or jump straight to the latest LTS patch and feature release.

[Latest LTS: 5.9.6](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[Feature release: 6.0.0](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

> [!NOTE]
>
> **Long Term Support (LTS) Versions:** LTS versions receive extended support with security updates and critical bug fixes. **5.9.x** is the current FlowX.AI LTS line, recommended for production environments requiring stability and long-term support. Support for the **5.1.x** line ended with 5.1.14, its final maintenance release. To keep receiving fixes, move to 5.9.x: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview). Release notes for older lines, including 5.1.x and 4.7.x, remain published for reference.
>
> **Feature Releases:** Versions released between LTS lines (such as 5.10.0) introduce new capabilities and are deployed to FlowX.AI SaaS environments as they ship. Self-hosted deployments receive these features consolidated into the next LTS release.

01 · Latest

## Latest releases

[LTS
v5.9.6
Maintenance release for the 5.9.x LTS line. Released on October 20th, 2026.](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)

[FEATURE
v6.0.0
Feature release, live on FlowX.AI SaaS. Released on October 30th, 2026.](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[LTS
v5.1.14
Final maintenance release for the 5.1.x LTS line. Released on October 30th, 2026.](./v5.x/v5.1.x-lts/v5.1.14-october-2026)

> [!TIP]
>
> **New cookbook:** [reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation), from email intake to exception review. More end-to-end builds are in the [cookbooks](/5.9/cookbooks/overview).

***

02 · All releases

## All releases

Planning a 5.9.x upgrade? The [5.9.x LTS changelog](./v5.x/5.9-lts-changelog) lists every change in each 5.9.x maintenance release on one page, with an RSS feed.

Moving from 5.9.x to 6.0.0? The [5.9.x to 6.0.0 changelog](./v6.x/5.9-to-6.0-changelog) lists every change from the 5.10 to 5.13 feature releases and 6.0.0 on one page, with an RSS feed.

versionlinereleased

[v6.0.0FRfeature releaseOctober 30th, 2026→](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[v5.1.14LTSmaintenance · 5.1.x LTS lineOctober 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.14-october-2026)
[v5.9.6LTSmaintenance · 5.9.x LTS lineOctober 20th, 2026→](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[v5.13.0FRfeature releaseSeptember 28th, 2026→](./v5.x/v5.13.0-september-2026/v5.13.0-september-2026)
[v5.9.5LTSmaintenance · 5.9.x LTS lineSeptember 23rd, 2026→](./v5.x/v5.9.5-september-2026/v5.9.5-september-2026)
[v5.1.13LTSmaintenance · 5.1.x LTS lineSeptember 18th, 2026→](./v5.x/v5.1.x-lts/v5.1.13-september-2026)
[v5.12.0FRfeature releaseSeptember 3rd, 2026→](./v5.x/v5.12.0-september-2026/v5.12.0-september-2026)
[v5.9.4LTSmaintenance · 5.9.x LTS lineAugust 27th, 2026→](./v5.x/v5.9.4-august-2026/v5.9.4-august-2026)
[v5.1.12LTSmaintenance · 5.1.x LTS lineAugust 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.12-august-2026)
[v5.11.0FRfeature releaseAugust 11th, 2026→](./v5.x/v5.11.0-august-2026/v5.11.0-august-2026)
[v5.9.3LTSmaintenance · 5.9.x LTS lineJuly 30th, 2026→](./v5.x/v5.9.3-july-2026/v5.9.3-july-2026)
[v5.1.11LTSmaintenance · 5.1.x LTS lineJuly 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.11-july-2026)
[v5.9.2LTSmaintenance · 5.9.x LTS lineJuly 10th, 2026→](./v5.x/v5.9.2-july-2026/v5.9.2-july-2026)
[v5.10.0FRfeature releaseJuly 7th, 2026→](./v5.x/v5.10.0-july-2026/v5.10.0-july-2026)
[v5.1.10LTSmaintenance · 5.1.x LTS lineJune 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.10-june-2026)
[v5.9.1LTSmaintenance · 5.9.x LTS lineJune 15th, 2026→](./v5.x/v5.9.1-june-2026/v5.9.1-june-2026)
[v5.9.0LTSfirst release of the 5.9.x LTS lineJune 2nd, 2026→](./v5.x/v5.9.0-june-2026/v5.9.0-june-2026)
[v5.1.9LTSLTS maintenance releaseMay 29th, 2026→](./v5.x/v5.1.x-lts/v5.1.9-may-2026)
[v5.8.0FRfeature releaseMay 10th, 2026→](./v5.x/v5.8.0-may-2026/v5.8.0-may-2026)
[v5.1.8LTSLTS maintenance releaseApril 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.8-april-2026)
[v5.7.0FRfeature releaseApril 28th, 2026→](./v5.x/v5.7.0-april-2026/v5.7.0-april-2026)
[v5.6.0FRfeature releaseMarch 25th, 2026→](./v5.x/v5.6.0-march-2026/v5.6.0-march-2026)
[v5.1.7LTSLTS maintenance releaseMarch 26th, 2026→](./v5.x/v5.1.x-lts/v5.1.7-march-2026)
[v5.1.6LTSLTS maintenance releaseMarch 16th, 2026→](./v5.x/v5.1.x-lts/v5.1.6-march-2026)
[v5.5.0FRfeature releaseFebruary 27th, 2026→](./v5.x/v5.5.0-february-2026/v5.5.0-february-2026)
[v5.1.5LTSLTS maintenance releaseFebruary 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.5-february-2026)
[v5.1.4LTSLTS maintenance releaseFebruary 9th, 2026→](./v5.x/v5.1.x-lts/v5.1.4-february-2026)
[v5.4.0FRfeature releaseJanuary 30th, 2026→](./v5.x/v5.4.0-january-2026/v5.4.0-january-2026)
[v5.1.3LTSLTS maintenance releaseJanuary 15th, 2026→](./v5.x/v5.1.x-lts/v5.1.3-january-2026)
[v5.3.0FRfeature releaseDecember 24th, 2025→](./v5.x/v5.3.0-december-2025/v5.3.0-december-2025)
[v5.1.2LTSLTS maintenance releaseDecember 3rd, 2025→](./v5.x/v5.1.x-lts/v5.1.2-december-2025)
[v5.2.0FRfeature releaseNovember 10th, 2025→](./v5.x/v5.2.0-november-2025/v5.2.0-november-2025)
[v5.1.1LTSLTS maintenance releaseNovember 10th, 2025→](./v5.x/v5.1.x-lts/v5.1.1-november-2025)
[v4.7.11LTSLTS maintenance releaseDecember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025)
[v4.7.10LTSLTS maintenance releaseNovember 17th, 2025→](./v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025)
[v4.7.9LTSLTS maintenance releaseOctober 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025)
[v5.1.0LTSLTS maintenance releaseOctober 2nd, 2025→](./v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025)
[v4.7.8LTSLTS maintenance releaseSeptember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025)
[v4.7.7LTSLTS maintenance releaseAugust 20th, 2025→](./v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025)
[v5.0.0FRfeature releaseJuly 31st, 2025→](./v5.x/v5.0.0-july-2025/v5.0.0-july-2025)
[v4.7.6LTSLTS maintenance releaseJuly 18th, 2025→](./v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025)
[v4.7.5LTSLTS maintenance releaseJune 19th, 2025→](./v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025)
[v4.7.4LTSLTS maintenance releaseMay 15th, 2025→](./v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025)
[v4.7.3LTSLTS maintenance releaseApril 14th, 2025→](./v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025)
[v4.7.2LTSLTS maintenance releaseMarch 26th, 2025→](./v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025)
[v4.7.1LTSLTS maintenance releaseMarch 7th, 2025→](./v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025)
[v4.7.0LTSLTS maintenance releaseFebruary 24th, 2025→](./v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025)
[v4.6.1FRfeature releaseFebruary 7th, 2025→](./v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025)
[v4.6.0FRfeature releaseJanuary 23rd, 2025→](./v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025)
[v4.1.5LTSLTS maintenance releaseSeptember 23rd, 2024→](./v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024)
[v4.1.4LTSLTS maintenance releaseSeptember 6th, 2024→](./v4.x/v4.1.x/v4.1.4-september-2024/v4.1.4-september-2024)
[v4.1.3LTSLTS maintenance releaseAugust 12th, 2024→](./v4.x/v4.1.x/v4.1.3-august-2024/v4.1.3-august-2024)
[v4.1.2LTSLTS maintenance releaseJune 8th, 2024→](./v4.x/v4.1.x/v4.1.2-june-2024/v4.1.2-june-2024)
[v4.1.1LTSLTS maintenance releaseJune 17th, 2024→](./v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024)
[v4.1.0LTSLTS maintenance releaseMay 30th, 2024→](./v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024)
[v4.0.0FRfeature releaseApril 18th, 2024→](./v4.x/v4.0.0-april-2024/v4.0.0-april-2024)

> [!NOTE]
>
> Releases from the **4.5.x (tech preview)** and **4.2.x** lines are not listed above. You can find them in the sidebar under **Release Notes** → **v4.x**.

***

> [accordion] Version 3.x.x
>
> > [card] [v3.4.8 - June 2024](/release-notes/v3.x.x/v3.4.8-june-2024/v3.4.8-june-2024)
> >
> > Explore the latest enhancements and fixes introduced in June 2024.
>
> > [card] [v3.4.7 - January 2024](/release-notes/v3.x.x/v3.4.7-january-2024/v3.4.7-january-2024)
> >
> > Explore the latest enhancements and fixes introduced in January 2024.
>
> > [card] [v3.4.6 - December 2023](/release-notes/v3.x.x/v3.4.6-december-2023/v3.4.6-december-2023)
> >
> > Explore the latest enhancements and fixes introduced in December 2023.
>
> > [card] [v3.4.5 - November 2023](/release-notes/v3.x.x/v3.4.5-november-2023/v3.4.5-november-2023)
> >
> > Explore the latest enhancements and fixes introduced in November 2023.
>
> > [card] [v3.4.4 - November 2023](/release-notes/v3.x.x/v3.4.4-november-2023/v3.4.4-november-2023)
> >
> > Discover the significant changes and improvements made in November 2023.
>
> > [card] [v3.4.3 - October 2023](/release-notes/v3.x.x/v3.4.3-october-2023/v3.4.3-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.2 - October 2023](/release-notes/v3.x.x/v3.4.2-october-2023/v3.4.2-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.1 - September 2023](/release-notes/v3.x.x/v3.4.1-september-2023/v3.4.1-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.4.0 - September 2023](/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.3.0 - July 2023](/release-notes/v3.x.x/v3.3.0-july-2023/v3.3.0-july-2023)
> >
> > Discover the significant changes and improvements made in July 2023.
>
> > [card] [v3.2.0 - April 2023](/release-notes/v3.x.x/v3.2.0-april-2023/v3.2.0-april-2023)
> >
> > Discover the significant changes and improvements made in April 2023.
>
> > [card] [v3.1.0 - March 2023](/release-notes/v3.x.x/v3.1.0-march-2023/v3.1.0-march-2023)
> >
> > Discover the significant changes and improvements made in March 2023.
>
> > [card] [v3.0.0 - February 2023](/release-notes/v3.x.x/v3.0.0-february-2023/v3.0.0-february-2023)
> >
> > Discover the significant changes and improvements made in February 2023.


# FlowX.AI 5.9.x LTS changelog
Source: https://docs.flowx.ai/release-notes/v5.x/5.9-lts-changelog

Every change in each FlowX.AI 5.9.x LTS maintenance release, grouped by type and component, with an RSS feed for upgrade planning.

This page lists every change in each 5.9.x LTS maintenance release, newest first. Use the RSS button at the top of the page to subscribe and get each new patch as it ships. Mobile renderers and the React Native SDK are covered in their own release notes. Moving to 6.0.0? See the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog).

**5.9.6**

October 2026

**Upgrade actions:** migrate to the `flowx-ai` Helm chart if you installed the `ai-platform` chart, create the `ai.flowx.build.deployment-failed.v1` Kafka topic and allow it in your ACLs, re-publish any build whose deployment failed shortly before the upgrade, review workflow node retry settings, grant the connection-test permissions to custom roles, and allow extra Integration Designer startup time on a large `workflow_instances` collection. Details are in the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).

#### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

#### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect.
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#mongodb-setting-names).
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6) for its version.

#### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.6 release notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026) · [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6)

**5.9.5**

September 2026

**Upgrade actions:** let the `ai-services` consumer group reach zero lag and allow the new AI consumer groups in Kafka ACLs, add private database hosts to the NoSQL DB runner allowlist, set every service-account client secret on `authorization-system`, rename `cache_error_total` in dashboards and alerts, re-expose `loggers` if you change log levels at runtime, and review the deployment guidelines if you had already turned on data partitioning, because the conversion to native partitions is one way. Details are in the [5.9.5 upgrade notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#upgrade-notes).

#### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#native-postgresql-partitioning).

#### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.

#### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.5 release notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026) · [5.9.5 deployment guidelines](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5)

**5.9.4**

August 2026

**Upgrade actions:** move the registry out of `image.repository` if you embedded it there (no action if you set `global.imageRegistry`), grant the Liquibase lock permissions to each service's database user on Oracle, create the `flowx-events-gateway-sa` client yourself if you manage Keycloak clients outside the Helm charts, and move host apps that embed the Angular SDK to Angular 21. Details are in the [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4#configuration-changes).

#### Changed

* **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.
* **Angular SDK:** the Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps that embed the Angular SDK must be on Angular 21. The npm and node requirements are unchanged.
* **Cross-version import:** importing a project build or version exported from an older platform line completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten.
* **Database migrations:** the lock that guards Liquibase schema migrations at service startup is a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration releases its lock when the database closes the session. Service accounts no longer need the `pods/status` permission. Oracle deployments need new database grants.
* **Events Gateway:** authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`. Helm chart deployments where `authorization-system` runs its migrations with Keycloak admin access need no action.
* **Helm charts:** the container image reference is split into `image.registry` and `image.repository`. The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. The default image location is unchanged.
* **Integration Designer:** service startup no longer scans the full token-instance collection, and the run-list summary queries are indexed.
* **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.
* **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.

#### Fixed

* **Actions:** deleting an action whose business rule calls a function works instead of returning a server error.
* **Build export:** retrying a build export re-attempts a dependency library whose own export timed out, so the parent build can finish.
* **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output from trailing empty cells and rows.
* **Entry points:** the entry-point picker in version settings lists only processes and UI flows from the current project.
* **Gateways:** an expression that fails to evaluate on an exclusive gateway surfaces as an incident on the process instance instead of only in the service logs.
* **Generated documents:** a document whose storage write fails returns an error instead of being recorded as successful. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.
* **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is listed once instead of once per consuming project version.
* **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives during a background synchronization, and merging versions no longer fails with a navigation-areas error.
* **Renderers:** the document preview shows its subtitle, and the file-upload error message follows the configured theme.
* **Reusable UI templates:** static input mappings configured on a reusable template are applied at runtime.
* **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.
* **Task management:** the row-selection checkbox column no longer carries an invisible sort control that re-sorted the view and cleared the selection, and changing the page size no longer opens the wrong process from the list.
* **Themes and CMS resources:** exporting a theme no longer includes duplicate copies of system icons, and importing no longer leaves system substitution tags missing.
* **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.4 release notes](/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026) · [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4)

**5.9.3**

July 2026

**Upgrade actions:** none. The new Events Gateway and Integration Designer settings ship with working defaults. Details are in the [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3#configuration-changes).

#### Changed

* **Events Gateway:** new settings tune the dedicated Redis connection pool for blocking reads, and the default blocking-read duration is lowered from 5 seconds to 1 second. If you set the blocking-read duration explicitly, review it against the new default.
* **Integration Designer:** a new setting sets the number of partitions for auto-created workflow Kafka topics. Existing topics are not modified.
* **Media Library:** PDF assets in the list can be opened in a new tab.
* **Process start:** web renderers keep the loading indicator visible until the first user task renders.

#### Fixed

* **Build import:** a transient database write conflict during a multi-dependency import no longer drops a dependency's build, which caused runtime errors on substitution tags and enumerations. Large imports may take slightly longer.
* **Date Picker:** the calendar anchors to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.
* **Designer:** opening Runtime after expanding a component's Permissions section no longer freezes the Designer, and a pending AI UI-generation draft no longer locks the process diagram read-only.
* **Projects:** creating a project with the same name as a deleted project returns a validation error instead of an internal server error.
* **Real-time event delivery:** the Events Gateway no longer leaks Redis connections. Blocking reads run on a dedicated connection pool with Redis Cluster support, so the gateway no longer needs periodic restarts under sustained load.
* **Task management:** deleting a swimlane allocation rule removes only that rule, clicking Save twice no longer creates duplicate rules, and task views no longer reset when the same view is open from different workspaces.
* **Workflows:** a workflow no longer freezes silently after a step exhausts its retries.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.3 release notes](/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026) · [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3)

**5.9.2**

July 2026

**Upgrade actions:** update any Keycloak group mapper or external IdP claim that emits the end-user group `User` to `Users Group`, remove records of the organization-ID migration or other Liquibase changesets you marked as executed by hand on an earlier 5.9.x (contact FlowX support for the list first), upgrade the AI Platform chart and the core services together, and update dashboards, alerts, and log queries that match the `ai-platform-` service name prefix. Details are in the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#upgrade-overview).

#### New

* **AI agents and data models:** AI Designer and AI Developer use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it.
* **AI workflow nodes:** JSON schema fields support `${}` placeholders.
* **Chat file uploads:** end users can attach multiple files in a chat-driven app. Uploads are indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content.
* **Document Parser:** a new LiteParse engine parses PDFs and images locally without GPU or AI calls, and OCR supports English, Romanian, Hungarian, and Bulgarian.
* **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.
* **Knowledge bases:** a Custom Agent node can select multiple knowledge bases, each exposed to the agent as its own retrieval tool, and retrieval can span multiple knowledge bases in a workflow.
* **SQL data sources:** queries on SQL data sources can be tested from the builds list.
* **Use in reporting:** the reporting toggle is available on UI flows and workflows.

#### Changed

* **AI node structured output:** responses from AI nodes with a response schema are validated against it, with automatic repair retries, and node logs include the failure reason and rejected output.
* **AI Platform services:** services are deployed under their plain names, without the `ai-platform-` prefix on pod, service, and image names, and the bundled Qdrant subchart is renamed the same way. Core services resolve AI components by the new names.
* **Audit log:** records sharing, user invitations, designer-user, end-user, and group management, actions on process instances and UI flows, adding a dependency, and terminating process, workflow, or UI flow instances.
* **Copy to project:** copying a process or UI flow to another project also copies its roles.
* **Data archiving:** archiving detaches a partition only when every process or workflow instance in it has finished. New settings for terminating stuck instances and backfilling legacy rows are off by default.
* **Default end-user group:** the group that the 5.1.x upgrade migration creates is renamed from `User` to `Users Group`. Groups your admins created are not renamed.
* **Designer:** the Event Handlers section appears higher in the component configuration panel, and the keys to save for collection items and bundled custom-component inputs are computed automatically.
* **Kafka reconnects:** platform services use a gentler broker-reconnect backoff by default, and repeated Kafka connection errors log at a quieter level.

#### Fixed

* **Active policy:** the user list on the override active-policy form is no longer empty.
* **Application manager:** the runtime-application organization-ID migration converts existing data correctly.
* **Audit logs:** filtering audit entries by user works when the username differs from the email address.
* **Build export with media files:** exporting a build with media file content produces an archive that contains the binaries.
* **Chat:** the floating chat position is calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.
* **CMS enumerations:** cascading-enum value lookups resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.
* **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.
* **Data sync with private CA certificates:** data-sync migrations that call HTTPS endpoints, such as Keycloak, no longer fail certificate validation in environments that use an internal certificate authority.
* **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.
* **Project version merge:** a merge no longer fails with a 500 error.
* **Redis Cluster:** UI template cache keys map to the same cluster slot, which prevents cross-slot errors.
* **Reusable UI templates:** actions are no longer missing at runtime when a template is nested in multiple levels of containers.
* **Self-hosted installation and upgrade:** Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding work on self-hosted environments.
* **Workflow data:** archiving batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine is fixed.
* Stability fixes across the Designer, the renderers, and the backend services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.2 release notes](/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026) · [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2)

**5.9.1**

June 2026

**Upgrade actions:** none for deployments where the Helm chart provisions Kafka topics. If you provision Kafka topics or ACLs manually, create the topics added in 5.9.1. Details are in the [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics).

#### New

* **AI permissions:** AI runtime usage and AI build-time tooling (AI Designer, agent building, code generation) are governed by two separate permissions. When AI is turned off, AI icons and entry points are hidden instead of shown disabled, and build-time helpers such as code generation and "Add comment" follow the dev-agent permission.
* **File Preview:** scroll-trigger event handlers, including a "document end" trigger, let a flow detect when a user scrolls through a document or reaches its end, for example to enable an **Accept** button only after the user reaches the end of an agreement.
* **File upload:** the upload button supports a configurable icon, set in the Designer.
* **Microsoft Outlook:** connections support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
* **Script engine:** business rules, reusable functions, and node rules can each run on the native engine (the 5.9 default) or the legacy GraalVM engine. Rules created before the switch to native keep running on GraalVM until you migrate them, and new rules default to native.

#### Changed

* **AI Designer:** generates UI from a flat template format instead of 3-level nesting, supports more component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates incrementally instead of regenerating them, and can generate reusable UI templates.
* **Kafka topics:** new topics carry runtime config-param change events, runtime instance terminations, resource cache evictions, and evaluation improvement suggestions. The Helm chart provisions them.
* **Merge conflicts:** merge-conflict handling for custom components and UI Flows identifies resources more clearly.
* **Organization settings:** navigation and design improvements.
* **Platform Status:** reports AI Platform components and their databases alongside the core services.
* **Runtime config params:** changes reach the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
* **Workflows:** storage of running steps is optimized, workflows and processes launched from a UI Flow inherit the build of the parent UI Flow, and AI node failures show the error details and model reasoning in the workflow run logs.

#### Fixed

* **Actions:** GET actions no longer fire with undefined parameters.
* **AI chat:** agent responses no longer reappear in chat after stop and refresh, and the builder-agent chat no longer duplicates messages.
* **Copy to project:** copying a process or workflow to another project succeeds, and copied workflows appear in the target project.
* **End-user login:** a null value is no longer cached when looking up the "All end-users" group, which could block logins until data sync completed.
* **File Preview:** previews render correctly, events fire inside collections, a fixed height applies at runtime, and preview resources no longer fail with CORS errors.
* **File Storage:** FTP test connection and file operations resolve configuration-parameter placeholders, and FTP file preview works when the root path has no leading slash.
* **Forms to validate:** scrolling covers the full component hierarchy, placeholders update, and chat and tab-bar components are selected correctly.
* **Hide and disable conditions:** conditions on UI templates, processes, and UI Flows apply at runtime for Designer users without workspace access.
* **Invitations:** an invited Designer user added as an Organization owner is assigned to a workspace.
* **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
* **Modals:** dropdowns no longer flicker, and long key names no longer break the layout.
* **Process instances:** loading an instance with a very large execution graph no longer crashes the browser.
* **Task management:** headers follow the theme in React and Angular, and the filter window no longer disappears after applying criteria.
* **Theme admin:** "copy to" no longer loses theme content.
* **Timer events:** activating a start timer event after a new build regenerated the process resource ID no longer fails with a 500 (duplicate key) error.
* **UI Flow:** images display in preview after refresh, and returning from an expired UI Flow no longer loses the theme UUID.
* **Usage Overview:** opening a usage overview no longer fails with a 500 error.
* **Web renderer:** the button shadow and modal content padding are restored, and components render when a media-file storage path is null.
* **Workflows:** END PARALLEL output no longer includes data from before the parallel branches started, and NoSQL node run logs no longer crash when a node fails before building its options.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.1 release notes](/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026) · [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1)


# Deployment guidelines v5.1.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.10 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.9 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.9 → 5.1.10**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **process-engine** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **admin** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **designer** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **cms-core** | 9.46.3 | 9.46.2 | 9.45.4 | 9.44.2 |
| **scheduler-core** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **events-gateway** | 9.36.4 | 9.36.2 | 9.35.4 | 9.34.1 |
| **notification-plugin** | 9.39.3 | 9.39.2 | 9.38.4 | 9.37.1 |
| **document-plugin** | 9.44.3 | 9.44.2 | 9.43.4 | 9.42.2 |
| **task-management-plugin** | 9.43.3 | 9.43.2 | 9.42.4 | 9.41.1 |
| **data-search** | 9.32.3 | 9.32.2 | 9.31.4 | 9.30.1 |
| **audit-core** | 9.40.3 | 9.40.2 | 9.39.4 | 9.38.1 |
| **advancing-controller** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **integration-designer** | 9.59.4 | 9.59.3 | 9.58.5 | 9.57.1 |
| **application-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **runtime-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **data-sync** | 9.33.4 | 9.33.2 | 9.32.3 | 9.31.1 |
| **authorization-system** | 9.43.5 | 9.43.2 | 9.42.4 | 9.41.1 |
| **nosql-db-runner** | 9.31.3 | 9.31.2 | 9.30.4 | 9.29.1 |

### Renderers

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **iOS renderer** | 9.0.25 | 9.0.20 | 9.0.19 | 9.0.12 |
| **Android renderer** | 9.0.31 | 9.0.24 | 9.0.19 | 9.0.13 |

### Plugins

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.7 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.10 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** starting with 5.1.10 the default Redis read mode is `polling` (`EVENTS_REDIS_MODE`). This is applied automatically on upgrade; no action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.9 processes and configurations

### What's included in 5.1.10

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.10 Release Notes](./v5.1.10-june-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.10 | Keycloak | 26+ |
| 5.1.10 | Kafka | 3.8 - 3.9 |
| 5.1.10 | PostgreSQL | 16 - 17 |
| 5.1.10 | Oracle Database | 21c, 23ai |
| 5.1.10 | MongoDB | 7 - 8 |
| 5.1.10 | Redis | 7.4 - 8.0 |
| 5.1.10 | Elasticsearch | 8 - 9 |
| 5.1.10 | Angular (Web SDK) | 19.2 |
| 5.1.10 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.11 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.10 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.10 → 5.1.11**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **process-engine** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **admin** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **designer** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **cms-core** | 9.47.3 | 9.46.3 | 9.46.2 | 9.45.4 |
| **scheduler-core** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **events-gateway** | 9.37.3 | 9.36.4 | 9.36.2 | 9.35.4 |
| **notification-plugin** | 9.40.3 | 9.39.3 | 9.39.2 | 9.38.4 |
| **document-plugin** | 9.45.3 | 9.44.3 | 9.44.2 | 9.43.4 |
| **task-management-plugin** | 9.44.4 | 9.43.3 | 9.43.2 | 9.42.4 |
| **data-search** | 9.33.3 | 9.32.3 | 9.32.2 | 9.31.4 |
| **audit-core** | 9.41.3 | 9.40.3 | 9.40.2 | 9.39.4 |
| **advancing-controller** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **integration-designer** | 9.60.3 | 9.59.4 | 9.59.3 | 9.58.5 |
| **application-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **runtime-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **data-sync** | 9.34.2 | 9.33.4 | 9.33.2 | 9.32.3 |
| **authorization-system** | 9.44.4 | 9.43.5 | 9.43.2 | 9.42.4 |
| **nosql-db-runner** | 9.32.3 | 9.31.3 | 9.31.2 | 9.30.4 |

### Renderers

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **iOS renderer** | 9.0.27 | 9.0.25 | 9.0.20 | 9.0.19 |
| **Android renderer** | 9.0.37 | 9.0.31 | 9.0.24 | 9.0.19 |

### Plugins

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.7 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.11 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.10 processes and configurations

### What's included in 5.1.11

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.11 Release Notes](./v5.1.11-july-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.11 | Keycloak | 26+ |
| 5.1.11 | Kafka | 3.8, 3.9 |
| 5.1.11 | PostgreSQL | 16, 17 |
| 5.1.11 | Oracle Database | 21c, 23ai |
| 5.1.11 | MongoDB | 7, 8 |
| 5.1.11 | Redis | 7, 8 |
| 5.1.11 | Elasticsearch | 8 |
| 5.1.11 | Angular (Web SDK) | 19.2 |
| 5.1.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.12

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.12 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.11 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.11 → 5.1.12**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **process-engine** | 9.76.7 | 9.76.3 | 9.75.7 | 9.75.3 |
| **admin** | 9.76.6 | 9.76.3 | 9.75.7 | 9.75.3 |
| **designer** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **cms-core** | 9.47.5 | 9.47.3 | 9.46.3 | 9.46.2 |
| **scheduler-core** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **events-gateway** | 9.37.4 | 9.37.3 | 9.36.4 | 9.36.2 |
| **notification-plugin** | 9.40.4 | 9.40.3 | 9.39.3 | 9.39.2 |
| **document-plugin** | 9.45.4 | 9.45.3 | 9.44.3 | 9.44.2 |
| **task-management-plugin** | 9.44.6 | 9.44.4 | 9.43.3 | 9.43.2 |
| **data-search** | 9.33.4 | 9.33.3 | 9.32.3 | 9.32.2 |
| **audit-core** | 9.41.4 | 9.41.3 | 9.40.3 | 9.40.2 |
| **advancing-controller** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **integration-designer** | 9.60.5 | 9.60.3 | 9.59.4 | 9.59.3 |
| **application-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **runtime-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **data-sync** | 9.34.3 | 9.34.2 | 9.33.4 | 9.33.2 |
| **authorization-system** | 9.44.5 | 9.44.4 | 9.43.5 | 9.43.2 |
| **nosql-db-runner** | 9.32.4 | 9.32.3 | 9.31.3 | 9.31.2 |

### Renderers

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **iOS renderer** | 9.0.29 | 9.0.27 | 9.0.25 | 9.0.20 |
| **Android renderer** | 9.0.39 | 9.0.37 | 9.0.31 | 9.0.24 |

### Plugins

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.7 | 0.2.6 |

### AI Platform

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.12 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.11 processes and configurations

### What's included in 5.1.12

This maintenance release includes:

* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.12 Release Notes](./v5.1.12-august-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.12 | Keycloak | 26+ |
| 5.1.12 | Kafka | 3.8, 3.9 |
| 5.1.12 | PostgreSQL | 16, 17 |
| 5.1.12 | Oracle Database | 21c, 23ai |
| 5.1.12 | MongoDB | 7, 8 |
| 5.1.12 | Redis | 7, 8 |
| 5.1.12 | Elasticsearch | 8 |
| 5.1.12 | Angular (Web SDK) | 19.2 |
| 5.1.12 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.13
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.13

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.13 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.12 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.12 → 5.1.13**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **process-engine** | 9.76.10 | 9.76.7 | 9.76.3 | 9.75.7 |
| **admin** | 9.76.8 | 9.76.6 | 9.76.3 | 9.75.7 |
| **designer** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **cms-core** | 9.47.6 | 9.47.5 | 9.47.3 | 9.46.3 |
| **scheduler-core** | 9.36.5 | 9.36.4 | 9.36.3 | 9.35.3 |
| **events-gateway** | 9.37.5 | 9.37.4 | 9.37.3 | 9.36.4 |
| **notification-plugin** | 9.40.5 | 9.40.4 | 9.40.3 | 9.39.3 |
| **document-plugin** | 9.45.5 | 9.45.4 | 9.45.3 | 9.44.3 |
| **task-management-plugin** | 9.44.7 | 9.44.6 | 9.44.4 | 9.43.3 |
| **data-search** | 9.33.5 | 9.33.4 | 9.33.3 | 9.32.3 |
| **audit-core** | 9.41.5 | 9.41.4 | 9.41.3 | 9.40.3 |
| **advancing-controller** | 9.36.6 | 9.36.4 | 9.36.3 | 9.35.3 |
| **integration-designer** | 9.60.7 | 9.60.5 | 9.60.3 | 9.59.4 |
| **application-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **runtime-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **data-sync** | 9.34.4 | 9.34.3 | 9.34.2 | 9.33.4 |
| **authorization-system** | 9.44.6 | 9.44.5 | 9.44.4 | 9.43.5 |
| **nosql-db-runner** | 9.32.5 | 9.32.4 | 9.32.3 | 9.31.3 |

### Renderers

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **iOS renderer** | 9.0.32 | 9.0.29 | 9.0.27 | 9.0.25 |
| **Android renderer** | 9.0.44 | 9.0.39 | 9.0.37 | 9.0.31 |

### Plugins

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.7 |

### AI Platform

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.13 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.12 processes and configurations

### What's included in 5.1.13

This maintenance release includes:

* **Reliability fixes** for process advancing under load
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.13 Release Notes](./v5.1.13-september-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.13 | Keycloak | 26+ |
| 5.1.13 | Kafka | 3.8, 3.9 |
| 5.1.13 | PostgreSQL | 16, 17 |
| 5.1.13 | Oracle Database | 21c, 23ai |
| 5.1.13 | MongoDB | 7, 8 |
| 5.1.13 | Redis | 7, 8 |
| 5.1.13 | Elasticsearch | 8 |
| 5.1.13 | Angular (Web SDK) | 19.2 |
| 5.1.13 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.14
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.14

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.14 is the final planned maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.13 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.13 → 5.1.14**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **process-engine** | 9.76.12 | 9.76.10 | 9.76.7 | 9.76.3 |
| **admin** | 9.76.10 | 9.76.8 | 9.76.6 | 9.76.3 |
| **designer** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **cms-core** | 9.47.8 | 9.47.6 | 9.47.5 | 9.47.3 |
| **scheduler-core** | 9.36.7 | 9.36.5 | 9.36.4 | 9.36.3 |
| **events-gateway** | 9.37.7 | 9.37.5 | 9.37.4 | 9.37.3 |
| **notification-plugin** | 9.40.7 | 9.40.5 | 9.40.4 | 9.40.3 |
| **document-plugin** | 9.45.7 | 9.45.5 | 9.45.4 | 9.45.3 |
| **task-management-plugin** | 9.44.9 | 9.44.7 | 9.44.6 | 9.44.4 |
| **data-search** | 9.33.7 | 9.33.5 | 9.33.4 | 9.33.3 |
| **audit-core** | 9.41.8 | 9.41.5 | 9.41.4 | 9.41.3 |
| **advancing-controller** | 9.36.8 | 9.36.6 | 9.36.4 | 9.36.3 |
| **integration-designer** | 9.60.9 | 9.60.7 | 9.60.5 | 9.60.3 |
| **application-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **runtime-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **data-sync** | 9.34.6 | 9.34.4 | 9.34.3 | 9.34.2 |
| **authorization-system** | 9.44.8 | 9.44.6 | 9.44.5 | 9.44.4 |
| **nosql-db-runner** | 9.32.7 | 9.32.5 | 9.32.4 | 9.32.3 |

### Renderers

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **iOS renderer** | 9.0.38 | 9.0.32 | 9.0.29 | 9.0.27 |
| **Android renderer** | 9.0.48 | 9.0.44 | 9.0.39 | 9.0.37 |

### Plugins

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.8 |

### AI Platform

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Version | Description |
| - | - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | 1.52.0 | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | 1.25.1 | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | 25.0.0-preview6 | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.14 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release. The audit index retention settings below are optional.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted | audit-core |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only | audit-core |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch).

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.13 processes and configurations

### What's included in 5.1.14

This maintenance release includes:

* **Android renderer fix** for the action loader on modal screens
* **Optional audit index retention** and shard-size rollover settings
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.14 Release Notes](./v5.1.14-october-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.14 | Keycloak | 26+ |
| 5.1.14 | Kafka | 3.8, 3.9 |
| 5.1.14 | PostgreSQL | 16, 17 |
| 5.1.14 | Oracle Database | 21c, 23ai |
| 5.1.14 | MongoDB | 7, 8 |
| 5.1.14 | Redis | 7, 8 |
| 5.1.14 | Elasticsearch | 8 |
| 5.1.14 | Angular (Web SDK) | 19.2 |
| 5.1.14 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.9
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.9 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.8 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.8 → 5.1.9**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **process-engine** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.7 |
| **admin** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.4 |
| **designer** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **cms-core** | **9.46.2** | 9.45.4 | 9.44.2 | 9.43.5 |
| **scheduler-core** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.4 |
| **events-gateway** | **9.36.2** | 9.35.4 | 9.34.1 | 9.33.4 |
| **notification-plugin** | **9.39.2** | 9.38.4 | 9.37.1 | 9.36.4 |
| **document-plugin** | **9.44.2** | 9.43.4 | 9.42.2 | 9.41.5 |
| **task-management-plugin** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.4 |
| **data-search** | **9.32.2** | 9.31.4 | 9.30.1 | 9.29.4 |
| **audit-core** | **9.40.2** | 9.39.4 | 9.38.1 | 9.37.4 |
| **advancing-controller** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.3 |
| **integration-designer** | **9.59.3** | 9.58.5 | 9.57.1 | 9.56.3 |
| **application-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **runtime-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **data-sync** | **9.33.2** | 9.32.3 | 9.31.1 | 9.30.4 |
| **authorization-system** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.3 |
| **nosql-db-runner** | **9.31.2** | 9.30.4 | 9.29.1 | 9.28.4 |

### Renderers

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **iOS renderer** | **9.0.20** | 9.0.19 | 9.0.12 | 9.0.11 |
| **Android renderer** | **9.0.24** | 9.0.19 | 9.0.13 | 9.0.7 |

### Plugins

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.9 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.8 processes and configurations

### What's included in 5.1.9

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.9 Release Notes](./v5.1.9-may-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.9 | Keycloak | 26+ |
| 5.1.9 | Kafka | 3.8 - 3.9 |
| 5.1.9 | PostgreSQL | 16 - 17 |
| 5.1.9 | Oracle Database | 21c, 23ai |
| 5.1.9 | MongoDB | 7 - 8 |
| 5.1.9 | Redis | 7.4 - 8.0 |
| 5.1.9 | Elasticsearch | 8 - 9 |
| 5.1.9 | Angular (Web SDK) | 19.2 |
| 5.1.9 | React (Web SDK) | 18.x |


# FlowX.AI 5.1.10 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.10-june-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.9 → 5.1.10** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.10 includes bug fixes and security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Active policy and iOS renderer fixes
> * Real-time event delivery stability improvement (Events Gateway)
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.9

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Reusable UI templates:** fixed several issues affecting reusable UI templates: actions remaining mapped after changing dependency versions, undo/redo leaving an action without a name or unable to save, data-slice and mapping requests returning 400 after a data-model key was renamed, duplicate entries returned for available templates, the "open in new tab" flag not being saved on UI action mappings, actions going missing when the same template is nested at multiple container levels, and conditional styling and validators being applied incorrectly when the same template is used more than once in a single user task.
> > > >
> > > > * **Active policy:** fixed an issue where the user list could appear empty on the override active-policy form.
> > > >
> > > > * **Project version merge:** fixed a 500 error that could occur when merging app versions.&#x20;
> > > >
> > > > * **Organization settings:** fixed the runtime users list failing to load.&#x20;
> > > >
> > > > - **Real-time event delivery:** improved Redis connection stability under sustained load. The Events Gateway now uses polling as the default mode for reading real-time events from Redis, preventing the gradual connection buildup that could previously require periodic Events Gateway restarts. The change applies automatically on upgrade; no configuration is required.
> > > > - **Renderer:** accordion card height and custom styles now follow the component's opened state, and gap spacing is applied correctly to collections.
> > > > - **Process instances:** fixed duplicate API calls and rendering errors when navigating between process instances.
> > > > - **iOS renderer:** broad VoiceOver and accessibility improvements across components (form fields, file preview, sliders, date picker, validation messages), and fixed form view-model lookup for forms nested in collections.
> > > > - **Android renderer:** component sizing now includes padding on text, link, markdown, and image components; fixed a TopAppBar crash in some configurations, tooltip icon overrides, slider step rounding, document preview caching, and resilience to process death.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.10 is fully compatible with 5.1.9. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.9 → 5.1.10 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.10](./deployment-guidelines-v5.1.10).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.11 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.11-july-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.10 → 5.1.11** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.11 includes bug fixes and security patches:
>
> * Audit log and task management fixes
> * Project creation error-handling fix
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.10

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Audit log:** filtering by user now returns results when a user's username differs from their email address.
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it.
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.11 is fully compatible with 5.1.10. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.10 → 5.1.11 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.11](./deployment-guidelines-v5.1.11).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.12 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.12-august-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.11 → 5.1.12** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.12 includes bug fixes for library resources and task management:
>
> * Library process resource overview fixes
> * Task management sort control fix
> * No breaking changes; fully compatible upgrade from 5.1.11

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes for library resource overview and task management
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.12 is fully compatible with 5.1.11. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.11 → 5.1.12 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.12](./deployment-guidelines-v5.1.12).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.13 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.13-september-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **security patches**. Upgrades from **5.1.12 → 5.1.13** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.13 includes reliability fixes for process advancing, a process designer fix, and security patches:
>
> * Process advancing fixes that prevent lost or stalled process advances under load
> * Action deletion fix for business rules that call reusable functions
> * Security patches and dependency upgrades across platform components
> * No breaking changes; fully compatible upgrade from 5.1.12

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and security patches across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Process advancing reliability fixes, a process designer fix, and security patches
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Process advancing:** the partition cleanup job no longer deletes advance events that are accepted while cleanup is running. Event insertion and cleanup now coordinate through database row locks, on both PostgreSQL and Oracle, so a process advance can no longer be lost to a concurrent cleanup.&#x20;
> > > > * **Process advancing:** advancing workers no longer pause for cooldown while work is still queued, and event completion is retried after a database deadlock instead of leaving an already-processed event marked as in progress.&#x20;
> > > > * **Process designer:** deleting an action no longer fails with a server error when one of its business rules calls a reusable function.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components. The Java runtime base images move to Eclipse Temurin 21.0.12 with a refreshed OS package layer.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.13 is fully compatible with 5.1.12. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.12 → 5.1.13 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.13](./deployment-guidelines-v5.1.13).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.14 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.14-october-2026

Final maintenance release for the FlowX.AI 5.1.x LTS line. Audit index retention settings, an Android SDK loader fix, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.1.x** line, focused on **bug fixes** and **security patches**. Upgrades from **5.1.13 → 5.1.14** are non-breaking and fully compatible. FlowX.AI 5.1.14 is the final planned maintenance release of the 5.1.x line. To keep receiving fixes, plan your move to the 5.9.x LTS line: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [card] Release Highlight
>
> **FlowX.AI 5.1.14** is a maintenance release for the 5.1.x LTS:
>
> * **Audit index retention:** optional settings to delete old audit data and roll audit indices over by shard size
> * **Key fixes:** the Android SDK loader shows on modal screens and no longer stays stuck after repeated taps
> * Security patches and dependency upgrades. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.1.14 is fully compatible with 5.1.13. No breaking changes, no database migrations, and no required configuration changes; standard deployment procedures apply.

**Upgrade path:** direct upgrade from 5.1.13.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x. Component versions are listed in the [5.1.14 deployment guidelines](./deployment-guidelines-v5.1.14).

***

## Full changelog

### New

* **Audit:** set how long audit data is kept, and roll audit indices over when a primary shard reaches a set size, with two new environment variables. Both are off by default, so the Audit service deletes nothing until you set a retention period. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch) and the [deployment guidelines](./deployment-guidelines-v5.1.14#new-environment-variables-audit-index-retention).&#x20;

### Fixed

* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.1.8 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.8-april-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.7 → 5.1.8** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.8 delivers security patches and dependency upgrades:
>
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.7

***

**What's new? 🆕**

> [tab] Highlights
>
> Security patches and dependency upgrades across platform components.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.8 is fully compatible with 5.1.7. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.7 → 5.1.8 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.8](./deployment-guidelines-v5.1.8).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.9 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.9-may-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.8 → 5.1.9** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.9 delivers notable bug fixes alongside security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Android renderer fixes
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.8

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Advancing workers** — Improved connection management so advancing workers no longer accumulate database connections across cooldown and rampup cycles, preventing connection growth on long-running runtime deployments.
> > > > * **Reusable UI templates** — Fixed an issue where input and output mappings on reusable UI templates could be silently lost when a referenced library version was updated.
> > > > * **Designer** — Fixed server errors when bulk-editing UI templates and when patching UI actions inside reusable UI templates.
> > > > * **Android renderer** — Fixed sticky container behavior across nested hierarchy levels, and deferred the custom loader display until CMS resources are available.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.9 is fully compatible with 5.1.8. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.8 → 5.1.9 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.9](./deployment-guidelines-v5.1.9).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10

Component versions and deployment notes for FlowX.AI 5.10 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.10 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.10.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.10.0 |
| - | - |
| **admin** | 11.18.0 |
| **advancing-controller** | 11.12.0 |
| **application-manager** | 11.18.0 |
| **audit-core** | 11.11.0 |
| **authorization-system** | 11.14.0 |
| **cms-core** | 11.14.0 |
| **data-search** | 11.11.0 |
| **data-sync** | 11.9.0 |
| **designer** | 11.36.1 |
| **document-plugin** | 11.19.0 |
| **email-gateway** | 11.15.0 |
| **events-gateway** | 11.14.0 |
| **file-gateway** | 11.14.0 |
| **integration-designer** | 11.24.2 |
| **license** | 11.13.0 |
| **nosql-db-runner** | 11.14.0 |
| **notification-plugin** | 11.14.0 |
| **organization-manager** | 11.14.0 |
| **process-engine** | 11.19.3 |
| **runtime-manager** | 11.18.0 |
| **scheduler-core** | 11.11.0 |
| **task-management-plugin** | 11.15.0 |
| **webhook-gateway** | 11.13.0 |

### AI base components

| Component | 5.10.0 |
| - | - |
| **embedder** | 11.2.0 |
| **knowledgebase-indexer-v2** | 11.2.0 |
| **knowledgebase-rag** | 11.2.0 |
| **doc-parser** | 11.2.0 |

### AI dev-time components

| Component | 5.10.0 |
| - | - |
| **ai-gateway** | 11.15.1 |
| **ai-analyst** | 11.2.0 |
| **ai-assistant** | 11.2.0 |
| **ai-designer** | 11.2.0 |
| **ai-developer** | 11.2.0 |
| **kb-enrichment** | 11.2.0 |
| **planner** | 11.2.0 |

### AI runtime components

| Component | 5.10.0 |
| - | - |
| **agent-builder** | 11.2.0 |
| **data-privacy** | 11.2.0 |
| **doc-converter** | 11.2.0 |
| **dynamic-classifier** | 11.2.0 |
| **evals-judge** | 11.2.0 |
| **speech-to-text** | 11.2.0 |
| **web-crawler** | 11.2.0 |

### AI extensions

| Component | 5.10.0 |
| - | - |
| **modpod** | 11.2.0 |
| **observatory-api** | 11.0.2 |
| **observatory-platform** | 11.0.2 |
| **observatory-web** | 11.0.2 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments receive them, re-verified, with the next LTS release.

### New Kafka topics

| Topic | Producer → Consumer | Purpose |
| - | - | - |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin → process-engine | Resource cache eviction |
| `ai.flowx.config.params.events.v1` | application-manager → process-engine | Config-param change notifications |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine → integration-designer | Runtime-instance termination |
| `ai.flowx.evals.suggestions.job.request.v1` / `.response.v1` | integration-designer | Evals suggestions job requests and responses |

### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them when your environment moves to 5.10.

This release also adds a new AI Platform component, **dynamic-classifier** (listed under AI runtime components above), which backs document classification.

In `admin`, the single `FLOWX_FEATUREAVAILABILITY_AISERVICENAME` setting is replaced by two, reflecting the split between AI dev-time and AI runtime services: `FLOWX_FEATUREAVAILABILITY_AIDEVTIMESERVICENAME` (default `ai-gateway-mngt`) and `FLOWX_FEATUREAVAILABILITY_AIRUNTIMESERVICENAME` (default `agent-builder-mngt`).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.10.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026

What's new in FlowX.AI 5.10: PostgreSQL and SOAP data sources, AI Developer script-node code generation, file uploads in chat-driven apps, and AI and document-intelligence improvements.

[FlowX.AI 5.10 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.10.0.html)

> [!NOTE]
>
> **FlowX.AI 5.10 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments receive them with the next LTS release.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release adds PostgreSQL and SOAP data sources, multi-file upload in chat-driven apps, and a set of AI and document-intelligence capabilities, alongside broader audit coverage, roles that travel with copied resources, and workflow data-partitioning improvements.

***

**What's new?**

> [tab] Core & Platform
>
> 🗂️ [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions\
> 📑 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources\
> ⚡ [**Platform performance and fixes**](#platform-performance-and-fixes) - Task-manager user fetch, project versioning, export/merge

> [tab] Designer & Renderer
>
> 💬 [**Chat file upload**](#chat-file-upload) - Attach multiple files in conversational apps\
> ⬇️ [**File download component**](#file-download-component) - Download files from a rendered app (web and Android)\
> 🔀 [**Conditional event-handler triggers**](#conditional-event-handler-triggers) - Fire event handlers based on a condition\
> 🎨 [**Image color property**](#image-color-property) - Color control on the IMAGE component\
> 💾 [**Save local variable**](#save-local-variable-action) - Capture a collection row into local data on click\
> 🪟 [**Global header and footer**](#global-header-and-footer) - Consistent header and footer across a UI Flow\
> 🧩 [**Reusable UI templates**](#reusable-ui-templates) - Action mapping, undo/redo, and dependency-version fixes

> [tab] Integrations & Data
>
> 🐘 [**PostgreSQL data source**](#postgresql-data-source) - Connect workflows directly to PostgreSQL and run SQL queries\
> 🧼 [**SOAP integration**](#soap-integration) - Import a WSDL and call SOAP operations from workflows\
> 🧮 [**FlowX Database aggregation**](#flowx-database-aggregation) - MongoDB aggregation pipelines\
> 🗄️ [**Documents tab in database testing**](#documents-tab-in-database-testing) - Inspect data while testing DB operations

> [tab] AI & Documents
>
> 📊 [**Tabular data extraction node**](#tabular-data-extraction-node) - Read spreadsheets and CSV into workflow data\
> 🔁 [**Knowledge Base error handling**](#knowledge-base-error-handling-and-retry) - Retry failed KB ingestion\
> ✨ [**AI Developer: script-node code**](#ai-developer-generate-script-node-code) - Generate node code from a prompt\
> 🧪 [**AI evaluation experiments**](#ai-evaluation-experiments) - Multiple datasets and improvement suggestions\
> 🛡️ [**AI node output reliability**](#ai-node-output-reliability) - Schema validation with auto-repair and clearer run errors\
> 📝 [**Template Filling node**](#template-filling-node) - Generate documents from templates in workflows\
> 🗂️ [**File manipulation nodes**](#file-manipulation-nodes) - Combine and split files in workflows\
> 📄 [**DOCX document generation**](#docx-document-generation) - Generate documents as DOCX in addition to PDF\
> 🏷️ [**Document Tag**](#document-tag-renamed-from-document-type) - "Document Type" renamed\
> 🔑 [**Mistral model provider**](#mistral-model-provider) - Bring your own Mistral API key

### **Expanded audit logging**

> [card] Broader audit coverage for access and lifecycle actions
>
> Audit logging now records a wider set of actions: **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> All Deployments

### **Copy with roles**

> [card] Roles travel with copied resources
>
> Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> All Deployments

### **Platform performance and fixes**

> [card] Platform performance and fixes
>
> > [tab] Performance
> >
> > The task manager fetches users through the authorization-system instead of calling Keycloak directly, cutting per-request identity lookups.&#x20;
> >
> > MongoDB partition archiving scales for large datasets, with partition-ID backfill for legacy data and archiving fixes on PostgreSQL and Oracle.&#x20;
>
> > [tab] Bug fixes
> >
> > > [accordion] Core platform fixes
> > >
> > > * **Project selector:** projects without a work-in-progress branch are correctly shown as unavailable.&#x20;
> > > * **Start Solution:** no longer fails with "no entry point set" until the page is refreshed.&#x20;
> > > * **Export and merge:** fixed errors when exporting a project build with imported libraries and when merging project versions, including a 500 during merge.&#x20;
> > > * **Merge-conflict checks:** no longer fail on processes that contain conflicts.&#x20;
> > > * **Allocation roles:** candidate-user search works for users without runtime permissions on the asset.&#x20;
> > > * **Version switching:** the selected resource opens when changing app versions, and reusable-function code refreshes on version switch.&#x20;
> > > * **Process engine:** resolved an incident-save deadlock.&#x20;
> > > * **FlowX Database:** inserting a document with a reserved `_id` key is now rejected with a clear error instead of breaking later reads.&#x20;
>
> All Deployments

### **PostgreSQL data source**

> [card] Connect to PostgreSQL databases from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds **PostgreSQL** as a data source type, alongside Oracle. Connect a workflow directly to a PostgreSQL database and run SQL queries against it as a workflow node, without a custom REST wrapper. See the [PostgreSQL Database](/5.9/docs/platform-deep-dive/integrations/postgresql-database) documentation.
>
> > [tab] Key Features
> >
> > > [card] Direct connection
> > >
> > > Configure host, port, database, schema, and credentials, with an optional SSL connection and a **Test connection** check before saving.
> >
> > > [card] SQL query operations
> > >
> > > Define SQL query operations on the data source and call them from workflow nodes.
> >
> > > [card] Connection pool tuning
> > >
> > > Advanced settings cover pool size, connection and query timeouts, keep-alive, and a validation query.
> >
> > > [card] Familiar experience
> > >
> > > Shares the same configuration and operations experience as the existing Oracle data source.
>
> SaaS

### **SOAP integration**

> [card] Call SOAP web services from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds a **SOAP System** data source. Import the service's **WSDL** — from a URL or an uploaded file — and FlowX discovers the operations with their input, output, and fault schemas, composes the SOAP envelope at runtime, and lets you call each operation from workflows through a **SOAP Operation** node. See the [SOAP System](/5.9/docs/platform-deep-dive/integrations/soap-system) documentation.
>
> > [tab] Key Features
> >
> > > [card] WSDL import
> > >
> > > Preview and select the operations to import; re-import refreshes schemas while preserving your edits
> >
> > > [card] Typed variables
> > >
> > > Envelope variables extracted from the input XSD, referenced as workflow parameters
> >
> > > [card] SOAP 1.1 and 1.2
> > >
> > > Version derived from the WSDL, with standard headers set automatically
> >
> > > [card] Testing built in
> > >
> > > Test operations with value overrides, a curl preview, and full request/response envelopes in run logs
>
> SaaS

### **Reusable UI templates**

> [card] Reusable UI template fixes
>
> Reusable UI templates get more reliable action mapping, undo/redo, and dependency-version handling.
>
> All Deployments

### **Chat file upload**

> [card] Attach multiple files in conversational apps
>
> End users can attach multiple files at once in chat-driven apps, and conversational workflows can receive those files as input. Uploaded files are extracted and indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content. Configurable in the Designer and themable, with runtime support on the web renderer.
>
> Session knowledge bases are isolated per conversation and per tenant, and are excluded from app export.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **File download component**

> [card] Download files from a rendered app
>
> A new File Download component lets end users download files directly from a rendered app. Configured in the Designer, with runtime support on web and Android.
>
> For more information, see the [File download](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download) documentation.
> SaaS

### **Conditional event-handler triggers**

> [card] Fire event handlers based on a condition
>
> Event handlers can now fire conditionally, configured in the Designer and honored by the web and Android renderers.
>
> For more information, see the [event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers) documentation.
> SaaS

### **Image color property**

> [card] Color control on the IMAGE component
>
> The IMAGE component now honors a color property, configured in the Designer and rendered on web and Android.
>
> See the [Image component](/5.9/docs/building-blocks/ui-designer/ui-component-types/image) documentation.
> SaaS

### **Save local variable action**

> [card] Capture a collection row into local data
>
> Event handlers gain a **Save Local Variable** action type: on a component inside a collection, it saves the clicked row's item into local data under a configurable key, entirely client-side with no backend roundtrip — useful for capturing the selected row before a follow-up action fires. Not available inside Reusable UI Templates.
>
> See the [Save Local Variable](/5.9/docs/building-blocks/ui-designer/event-handlers#save-local-variable) documentation.
> SaaS

### **Global header and footer**

> [card] Consistent header and footer across a UI Flow
>
> UI Flows can now define a **global header and footer** that display consistently across every page of the flow. Each holds content components — containers, forms, buttons, links, custom components — with fixed or static positioning (header fixed by default), so you can build persistent navigation or action bars in one place instead of per page.
>
> See the [Global Header and Footer](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer) documentation.
> SaaS

### **Tabular data extraction node**

> [card] Extract spreadsheet and CSV data into workflows
>
> A new workflow node reads a spreadsheet or CSV file and returns its contents as structured JSON in the node's response key, so the data can drive conditions and data operations downstream. Each row is returned as an object keyed by the file's header row, and for Excel files you can select which sheet to read.
>
> For more information, see the [Tabular Data Extraction node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node) documentation.
> SaaS

### **Knowledge Base error handling and retry**

> [card] Recover from failed Knowledge Base ingestion
>
> When Knowledge Base ingestion fails, the Knowledge Base page now shows a clear failure status and reason, and a **Retry** button re-runs the last operation after cleaning up partial content so the store is not left inconsistent. The **Update Knowledge Base** workflow node gains a **FAIL** exit handle with per-operation rollback.
>
> Learn more about [Knowledge Bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview).
> SaaS

### **AI Developer: generate script-node code**

> [card] Generate script-node code with AI Developer
>
> In the workflow designer, a script node can call **AI Developer** to generate or refactor its code from a natural-language prompt. Output streams into the test area for a **Keep** or **Discard** review, with edits shown as a diff. Supports JavaScript and Python, and respects existing AI Developer permissions.
>
> Learn more about [AI Developer](/5.9/ai-platform/pre-built-agents/ai-developer).
> SaaS

### **FlowX Database aggregation**

> [card] Aggregation pipelines in FlowX Database
>
> The FlowX Database data source adds MongoDB **aggregation pipeline** support, so configurators can group, join, reshape, and compute across documents beyond what a single query allows.
>
> Learn more about the [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) data source.
> SaaS

### **AI evaluation experiments**

> [card] Richer AI evaluation experiments
>
> > [tab] Multiple datasets
> >
> > An evaluation experiment can run against **multiple datasets** at once (datasets sharing the same AI node), with overall metrics aggregated across them and a dataset column added to the report.
>
> > [tab] Improvement suggestions
> >
> > Experiment reports now show **AI-generated suggestions** for improving the node's prompt, grouped per LLM-as-judge evaluator, beneath the score cards.
>
> Learn more about [AI evaluations](/5.9/ai-platform/evaluations).
> SaaS

### **AI node output reliability**

> [card] Schema validation with auto-repair and clearer run errors
>
> > [tab] Validation and repair
> >
> > When an AI node has a **Response Schema**, the response is validated against it and automatically retried with a repair prompt on mismatch. Nodes that still fail return a **categorized error** instead of passing malformed output downstream, and the node's **Logs** show the failure reason, rejected output, the model's reasoning summary, and the retry count.
>
> > [tab] Schema placeholders
> >
> > Response schemas now support `${variable}` placeholders resolved at runtime against workflow data, with substituted values coerced to the schema-declared types — consistent with how other AI-node fields resolve placeholders.
>
> See [AI node types](/5.9/ai-platform/agent-builder/node-types#structured-output-validation-and-run-diagnostics) for details.
> SaaS

### **Template Filling node**

> [card] Generate documents from templates in workflows
>
> Integration workflows gain a **Template Filling** node, under **Tools** in the node palette, that generates a document from a document template populated with workflow data. Select a template and language, fill the template's variables from workflow data, and choose **PDF** or **DOCX** output. The generated file's ID and download path are returned on the node's response key.
>
> See the [Template Filling node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) documentation.
> SaaS

### **File manipulation nodes**

> [card] Combine and split files in workflows
>
> Integration workflows add two document nodes, under **Tools** in the node palette: **Combine Files** merges multiple PDFs into one in a given order, and **Split File** breaks a PDF into multiple files by page ranges or one file per page. Both bring document handling that was previously process-only into workflows.
>
> See the [Combine Files](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) documentation.
> SaaS

### **DOCX document generation**

> [card] Generate documents as DOCX
>
> Template-based document generation can now produce **DOCX** files in addition to PDF. Set `outputFormat` (`PDF` or `DOCX`; defaults to `PDF`) on the generation request, or pick the format from the new **Output format** dropdown when testing a template in the Designer. Generated DOCX files preserve the template's styles, data, and images. Barcodes apply to PDF output only.
>
> Learn more in the [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output) documentation.
> SaaS

### **Document Tag (renamed from Document Type)**

> [card] Document Type is now Document Tag
>
> The **Document Type** field is renamed **Document Tag** across the surfaces where a document is tagged for storage (Upload File action, Document-Plugin REST responses, AI Document Generation, and the Web Page Extractor). This is a label change; behavior is unchanged.
> SaaS

### **Documents tab in database testing**

> [card] Inspect data while testing database operations
>
> The Database Query testing modals gain a **Documents** tab, so you can inspect the database right after running an operation. Multi-record operations report an affected-record count.
> SaaS

### **Mistral model provider**

> [card] Bring your own Mistral API key
>
> **Mistral** joins the model provider catalog as a bring-your-own-key provider. Add it with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability: chat, image understanding, embeddings, and document OCR. The seeded catalog covers the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed model lines.
>
> Learn more about [AI providers](/5.9/ai-platform/ai-providers).
> SaaS

***

## Deployment guidelines

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.10 deployment guidelines](./deployment-guidelines-v5.10).&#x20;


# Deployment guidelines v5.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11

Component versions and deployment notes for FlowX.AI 5.11 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.11 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.11.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.11.0 |
| - | - |
| **admin** | 11.53.0 |
| **advancing-controller** | 11.31.0 |
| **application-manager** | 11.46.0 |
| **audit-core** | 11.30.0 |
| **authorization-system** | 11.38.0 |
| **cms-core** | 11.43.0 |
| **data-search** | 11.30.0 |
| **data-sync** | 11.27.0 |
| **designer** | 11.89.1 |
| **document-plugin** | 11.47.0 |
| **email-gateway** | 11.39.0 |
| **events-gateway** | 11.34.0 |
| **file-gateway** | 11.38.0 |
| **integration-designer** | 11.62.1 |
| **license** | 11.34.0 |
| **nosql-db-runner** | 11.35.0 |
| **notification-plugin** | 11.41.0 |
| **organization-manager** | 11.38.0 |
| **process-engine** | 11.53.1 |
| **runtime-manager** | 11.46.0 |
| **scheduler-core** | 11.30.0 |
| **task-management-plugin** | 11.42.0 |
| **webhook-gateway** | 11.37.0 |

### AI base components

| Component | 5.11.0 |
| - | - |
| **embedder** | 11.3.1 |
| **knowledgebase-indexer-v2** | 11.3.1 |
| **knowledgebase-rag** | 11.3.1 |
| **doc-parser** | 11.3.1 |

### AI dev-time components

| Component | 5.11.0 |
| - | - |
| **ai-gateway** | 11.39.0 |
| **ai-analyst** | 11.3.1 |
| **ai-assistant** | 11.3.1 |
| **ai-designer** | 11.3.1 |
| **ai-developer** | 11.3.1 |
| **kb-enrichment** | 11.3.1 |
| **planner** | 11.3.1 |

### AI runtime components

| Component | 5.11.0 |
| - | - |
| **agent-builder** | 11.3.1 |
| **ai-architect** | 11.3.1 |
| **data-privacy** | 11.3.1 |
| **doc-converter** | 11.3.1 |
| **dynamic-classifier** | 11.3.1 |
| **evals-judge** | 11.3.1 |
| **speech-to-text** | 11.3.1 |
| **web-crawler** | 11.3.1 |

### AI extensions

| Component | 5.11.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.89.1` for FlowX.AI 5.11.0). The native iOS and Android renderers version independently.

| Component | 5.11.0 |
| - | - |
| **@flowx/angular-sdk** | 11.89.1 |
| **@flowx/angular-theme** | 11.89.1 |
| **@flowx/angular-ui-toolkit** | 11.89.1 |
| **@flowx/react-sdk** | 11.89.1 |
| **@flowx/react-theme** | 11.89.1 |
| **@flowx/react-ui-toolkit** | 11.89.1 |
| **@flowx/react-native-sdk** | 11.89.1 |
| **@flowx/react-native-theme** | 11.89.1 |
| **@flowx/react-native-ui-toolkit** | 11.89.1 |
| **@flowx/core-sdk** | 11.89.1 |
| **@flowx/core-theme** | 11.89.1 |
| **react-saas** | 11.89.1 |
| **iOS renderer** | 11.1.0 |
| **Android renderer** | 11.7.1 |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.11 capabilities. On SaaS they are created and managed automatically.

**Structured template data model** (document and notification templates move to the structured data model):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.sync.out.v1` | document-plugin, notification-plugin → application-manager |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | document-plugin, notification-plugin → application-manager |

**Runtime content import/export** (Knowledge Base and database content):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → ai-platform |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | ai-platform → integration-designer |

**Document classification and ML extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | ai-platform → integration-designer |

### AI Platform packaging

FlowX.AI 5.11 consolidates the AI Platform services into a single **`ai-platform` umbrella chart** (version `11.3.1`). Services that were previously deployed as standalone releases, including `doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, and `evals-judge`, now ship as subcharts of that chart and continue to run under their plain service names. On SaaS this change is applied automatically. The [component versions](#component-versions) section lists each service at its effective `11.3.1` version.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.11.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026

What's new in FlowX.AI 5.11: workflow tools and agentic RAG on Custom Agents, per-Knowledge-Base embedding models, document classification, extended response caching, subworkflow data mapping, structured template data models, and chat and UI Flow renderer improvements.

[FlowX.AI 5.11 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.11.0.html)

> [!NOTE]
>
> **FlowX.AI 5.11 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.11** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release turns Custom Agents into orchestrators that call FlowX workflows as tools and search knowledge bases agentically, adds per-Knowledge-Base embedding models with local embedders for personal-information content, and introduces document classification. It also extends response caching and subworkflow data mapping in the Integration Designer, moves document and notification templates onto the structured data model, and adds chat notifications, session ownership, and richer runtime audit to the renderers.

### What changed since 5.10.0

| 5.10.0 | 5.11.0 |
| - | - |
| Custom Agents call MCP servers, built-in tools, web search, and Knowledge Bases | + **FlowX workflows as callable tools** on a Custom Agent, with per-tool usage hints and tool-calling caps |
| Knowledge Base retrieval is a plain vector search on the org default embedding model | + **Agentic knowledge base search** and **per-KB embedding models**, including keyless local embedders for personal-information content |
| REST caching covers GET; SQL operations are cacheable | + **POST** REST responses, **file-storage** reads, and **Mongo** reads are cacheable too |
| Subworkflow input/output is raw JSON | + **Input and output mappers** on the Subworkflow node, with per-mapping test and import/export |
| Document and notification templates use a free-form key/value Data model tab | + Templates use the **structured data model** with typed attributes, validators, and Input Parameters |

***

**What's new?**

> [tab] AI & Agents
>
> 🧰 [**Workflow tools on Custom Agents**](#workflow-tools-on-custom-agents) - Attach FlowX workflows as callable agent tools, with usage hints and tool-calling caps\
> 🔎 [**Agentic knowledge base search and Show Reasoning**](#agentic-knowledge-base-search-and-show-reasoning) - Query decomposition, relevance grading, and a reasoning summary in the run log\
> 🧠 [**Per-knowledge-base embedding models**](#per-knowledge-base-embedding-models) - Pick an embedding model per KB and keep personal-information content on a local embedder\
> 🗂️ [**Knowledge Base content lifecycle**](#knowledge-base-content-lifecycle) - Delete entries by metadata filter, structured failure handling, per-chunk timestamps\
> 🏷️ [**Document classification**](#document-classification) - Train or import a classifier and route document pages in a workflow\
> 💬 [**Conversational chat reply requirement**](#conversational-chat-reply-requirement) - A conversational run that never replies to chat now fails with a clear error\
> ✍️ [**Custom Agent instruction limit**](#custom-agent-instruction-limit) - The Instructions field is capped at 10,000 characters

> [tab] Integrations & Data
>
> 🔁 [**Reusable functions in Integration Designer**](#reusable-functions-in-integration-designer) - Call reusable functions from Script and Condition (Fork) nodes\
> ⚡ [**Extended response caching**](#extended-response-caching) - Cache POST REST, file-storage reads, and Mongo reads alongside GET and SQL\
> 🔗 [**Subworkflow data mapping**](#subworkflow-data-mapping) - Map data in and out of a subworkflow with input and output mappers\
> 📎 [**Email attachment filtering by extension**](#email-attachment-filtering-by-extension) - Filter attachments by individual file extension instead of broad categories

> [tab] Platform
>
> 🧱 [**Structured data model for templates**](#structured-data-model-for-templates) - Document and notification templates use typed attributes and Input Parameters\
> ✅ [**Data model attribute validators**](#data-model-attribute-validators) - Required, min/max, length, pattern, email, items, and currency rules on attributes\
> 🧾 [**UI Flow runtime audit**](#ui-flow-runtime-audit) - Audit workflow-instance runs, chat messages, conversation reads, and process renders\
> 📤 [**Cross-version export adaptation**](#cross-version-export-adaptation) - Exports adapt UI templates for older LTS targets by removing unsupported handlers\
> 🔐 [**Platform and runtime improvements**](#platform-and-runtime-improvements) - Runtime access-control hardening

> [tab] Renderers & UI Flows
>
> 🔔 [**Chat notifications and conversation search**](#chat-notifications-and-conversation-search) - Unread-message badge on the chat button and search across conversation history\
> 🚫 [**Disable chat input on a condition**](#disable-chat-input-on-a-condition) - A business condition can make the chat input read-only\
> 🧭 [**Navigate To form validation**](#navigate-to-form-validation) - Require form validation before a Navigate To action, on web, iOS, and Android\
> ⌛ [**Expired UI Flow sessions**](#expired-ui-flow-sessions) - Expired sessions show a session-expired screen with a start-fresh option\
> 👤 [**UI Flow session owner**](#ui-flow-session-owner) - Restrict a running session to a single user\
> 🏁 [**Process Renderer process-end handling**](#process-renderer-process-end-handling) - Run a configurable action when an embedded process ends\
> 🎛️ [**Renderer improvements**](#renderer-improvements) - Batched enumeration fetch and process-start loader alignment

### **Workflow tools on Custom Agents**

> [card] Attach FlowX workflows as callable tools on a Custom Agent
>
> > [tab] Overview
> >
> > **Before 5.11:** a Custom Agent's tools were MCP servers, built-in tools, web search, and Knowledge Base retrieval. **Now:** you can also attach FlowX workflows as callable tools.
> >
> > In the Custom Agent node's **Tools** section, add a workflow as a tool and fill the per-tool **When should the agent use this workflow?** hint that tells the agent when to call it. The agent calls the workflow like any other tool, passing arguments that match the workflow's Start-node input parameters. A workflow with no input parameters cannot be attached. Each tool call starts a fresh workflow run whose output returns to the agent, and the child run is linked in the console log.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Workflows as tools
> > >
> > > Attach up to ten workflows as tools on one Custom Agent, each with a usage hint the agent reads when deciding to call it.
> >
> > > [card] Typed arguments
> > >
> > > The agent passes arguments that match the workflow's Start-node input parameters; workflows without input parameters are not eligible.
> >
> > > [card] Tool-calling limits
> > >
> > > An agent is limited in how many tool calls it can make per run, and workflow-tool call chains are depth-limited so recursion cannot run away.
> >
> > > [card] Linked runs
> > >
> > > Each workflow tool call is a fresh run whose output returns to the agent and is linked in the console log.
>
> SaaS

### **Agentic knowledge base search and Show Reasoning**

> [card] Agentic knowledge base search and reasoning summaries
>
> > [tab] Overview
> >
> > The Custom Agent node gains **agentic knowledge base search** and a **Show Reasoning** toggle.
> >
> > With agentic search on, the agent breaks a question into sub-queries, retrieves and grades results for relevance, and retries with reworded queries if the first pass finds nothing. It is better on complex questions and uses more model calls; a single pass with three sub-queries is the default. Agentic search never returns worse results than plain retrieval. **Show Reasoning** captures the model's reasoning summary in the run and console log; the structured response and the chat reply shown to the user are unchanged.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Agentic search
> > >
> > > Turn on **Enable agentic knowledge base search**, then set **Max attempts** and **Subqueries per attempt** under Settings.
> >
> > > [card] Relevance grading
> > >
> > > Retrieved candidates are graded against the original question, with corrective retries until a relevant result is found or the attempt budget is spent.
> >
> > > [card] Show Reasoning
> > >
> > > Surface the model's reasoning in the run log without changing the answer returned to the user.
> >
> > > [card] Fail-open
> > >
> > > Agentic mode returns the same chunk metadata as plain retrieval, so citations and telemetry are unchanged.
>
> SaaS

### **Per-knowledge-base embedding models**

> [card] Per-KB embedding models and local embedders for personal information
>
> > [tab] Overview
> >
> > Knowledge Bases can now use a **per-KB embedding model**, and a KB that holds personal information can keep its content on a local embedder.
> >
> > Turn on **Containing Personal Information** on a Knowledge Base to enable a local embedding model, then pick one from the **Embedding model** list. Local embedders (for example a text-embedding-inference or Ollama endpoint, or any OpenAI-compatible endpoint) are configured as a single **CUSTOM** provider in the organization AI settings, with a free-form base URL and no API key. The embedding model is set before the first store and cannot be changed afterward. Non-personal-information Knowledge Bases use the organization's default embedding model.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See the Knowledge Base documentation.
>
> > [tab] Key Features
> >
> > > [card] Per-KB model
> > >
> > > Each Knowledge Base carries its own embedding-model reference; a new Settings tab shows the current model.
> >
> > > [card] Local embedders
> > >
> > > Keep personal-information content on-box using a keyless local embedder fronted by a CUSTOM AI provider.
> >
> > > [card] Model travels with export
> > >
> > > Project version export preserves the KB's embedding-model reference, so a re-import keeps the same model.
> >
> > > [card] Set once per KB
> > >
> > > A Knowledge Base's embedding model is chosen before its first store and cannot be changed afterward.
>
> SaaS

### **Knowledge Base content lifecycle**

> [card] Delete entries by filter, structured failure handling, and per-chunk timestamps
>
> > [tab] Overview
> >
> > The **Update Knowledge Base** node gains a **Delete entries** operation and structured failure handling, and retrieval results now carry per-chunk metadata.
> >
> > **Delete entries** soft-deletes chunks whose entry-level metadata matches a filter, in one store or across the Knowledge Base; an empty or match-all filter is rejected so a misconfigured node cannot wipe a store. When an update operation fails, the node's **FAIL** branch returns a structured output with the operation, store, failure reason, and how many chunks were rolled back, and any partial changes are reversed. Retrieval results now include a per-chunk identifier and an ingestion timestamp.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > >
> > > See the Managing Knowledge Base content documentation.
>
> > [tab] Key Features
> >
> > > [card] Filtered deletion
> > >
> > > Delete entries by metadata filter from a workflow, with an empty or match-all filter rejected as a safety guard.
> >
> > > [card] Failure output with rollback
> > >
> > > The FAIL branch reports the operation, store, reason, and rolled-back chunk count; partial changes are reversed.
> >
> > > [card] Per-chunk timestamps
> > >
> > > RAG results carry a chunk identifier and an ingestion timestamp (empty for chunks indexed before this shipped).
> >
> > > [card] Clear retry signal
> > >
> > > Retryable failures such as extraction or chunking errors are distinguished from non-retryable ones such as size or timeout.
>
> SaaS

### **Document classification**

> [card] Classify document pages with a trainable ML model
>
> > [tab] Overview
> >
> > FlowX.AI adds **Document Classifiers**: deterministic ML models that sort document pages into categories. Define classes, upload training data, and train or import a model, then route each page in a workflow with the new **Document Classification** node.
> >
> > The node runs the active model over a document, returns a predicted label and probability per page with a configurable confidence threshold, and flags low-confidence pages. A page-level failure does not fail the node.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer documentation.
>
> > [tab] Key Features
> >
> > > [card] Train or import
> > >
> > > Build classes and training data in the Designer, then train a model or import a pre-trained one.
> >
> > > [card] Per-page classification
> > >
> > > The Document Classification node returns a label and probability for each page, with a confidence threshold and low-confidence flags.
> >
> > > [card] Deterministic routing
> > >
> > > Combine the node with a condition to route pages by their predicted category.
> >
> > > [card] Resilient runs
> > >
> > > A page that cannot be classified is reported per page without failing the whole node.
>
> SaaS

### **Conversational chat reply requirement**

> [card] Conversational runs must reply to chat
>
> A conversational (chat-driven) workflow must send at least one chat reply, either from a Custom Agent node with **Send as Chat Reply** on or from a Navigate in UI Flow node that completes the turn. A run that reaches the end without replying now fails with a clear error instead of ending silently.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **Custom Agent instruction limit**

> [card] Instructions field capped at 10,000 characters
>
> The Custom Agent **Instructions** field is now limited to 10,000 characters.
> SaaS

### **Reusable functions in Integration Designer**

> [card] Call reusable functions from Script and Condition (Fork) nodes
>
> Reusable functions can now be called from **Script** nodes and **Condition (Fork)** nodes in the Integration Designer, not just from Business Rule actions in processes. Functions are referenced in the node's JavaScript or Python and resolved at runtime from the app version's function copies, including functions that call other functions and cross-app references. A Fork node resolves the references used across all of its branch conditions.
>
> For more information, see the [reusable functions](/5.9/docs/building-blocks/reusable-resources/reusable-functions) documentation.
> SaaS

### **Extended response caching**

> [card] Cache POST REST, file-storage reads, and Mongo reads
>
> > [tab] Overview
> >
> > Response caching in the Integration Designer now covers more operation types. **POST** REST endpoints are cacheable alongside GET, with the request body forming part of the cache key so different bodies cache separately. Read **file-storage** operations (LIST and DOWNLOAD) and read **Mongo** operations (FIND, FIND\_ONE, AGGREGATE) are cacheable alongside SQL. Mutating operations are never cached.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] POST caching
> > >
> > > Cache POST responses, keyed on the request body so distinct requests stay separate.
> >
> > > [card] File-storage reads
> > >
> > > LIST and DOWNLOAD operations are cacheable; UPLOAD, DELETE, and MOVE are not.
> >
> > > [card] Mongo reads
> > >
> > > FIND, FIND\_ONE, and AGGREGATE are cacheable alongside SQL; mutating Mongo operations are not.
> >
> > > [card] Shared policy
> > >
> > > All cacheable surfaces reuse the same time-based expiry and per-operation clear-cache action.
>
> SaaS

### **Subworkflow data mapping**

> [card] Map data in and out of a subworkflow with input and output mappers
>
> > [tab] Overview
> >
> > The **Subworkflow** node adds data mapping as an alternative to raw JSON. Turn on **Enable data mapping** to define an **Input mapping** per subworkflow start node and an **Output mapping** per end node, mapping individual data slices instead of hand-editing JSON. Output mapping does not apply to asynchronous subworkflows. Each mapping opens a mapper with a test action, and mappings travel with import, export, and clone.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] Input and output mappers
> > >
> > > Map data into the subworkflow per start node and out of it per end node, without editing raw JSON.
> >
> > > [card] Per-mapping test
> > >
> > > Test a mapping with source and target slices and apply values from a past instance.
> >
> > > [card] Travels with the project
> > >
> > > Mappings are preserved on import, export, and clone.
> >
> > > [card] Async-aware
> > >
> > > Output mapping is hidden for asynchronous subworkflows, which do not return data to the caller.
>
> SaaS

### **Email attachment filtering by extension**

> [card] Filter email attachments by individual file extension
>
> Email Trigger and Microsoft Outlook data sources now filter attachments by **individual file extension** instead of the five broad file-type categories. Choose the exact extensions to accept and to forward into a process. Existing category selections are migrated to their individual extensions automatically on upgrade, so current triggers keep working.
>
> For more information, see the [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger) documentation.
> SaaS

### **Structured data model for templates**

> [card] Document and notification templates use the structured data model
>
> > [tab] Overview
> >
> > **Before 5.11:** document and notification templates declared parameters in a free-form key/value Data model tab. **Now:** templates use the same structured data model as the rest of the platform.
> >
> > On the **Data Model** tab you define typed attributes with validations, sensitive-data and reporting flags, and references to project or library data types. On the **Input Parameters** tab you select which attributes the template expects. Values sent in the request are substituted for those attributes at generation time.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > >
> > > See the notification templates documentation.
>
> > [tab] Key Features
> >
> > > [card] Typed attributes
> > >
> > > Define string, number, boolean, enum, date, currency, object, and array attributes with validations.
> >
> > > [card] Input Parameters
> > >
> > > Pick the attributes the template expects on a dedicated Input Parameters tab.
> >
> > > [card] Reference shared types
> > >
> > > Reference project and library data types like other resources.
> >
> > > [card] OTP unchanged
> > >
> > > The OTP flow contract is unchanged; the reserved `otpValue` and request `data` object work as before.
>
> SaaS

### **Data model attribute validators**

> [card] Validators on data model attributes
>
> Data model attributes now support validators. Available rules depend on the attribute type and include **Required**, **Min/Max Value**, **Min/Max Length**, **Pattern**, **Email Format**, and **Min/Max Items**, plus currency-specific amount and code rules. Validators are stored on the attribute and apply wherever that data model is used, including project, process, template, and reusable UI template data models.
>
> For more information, see the [project data model](/5.9/docs/building-blocks/project-data-model) documentation.
> SaaS

### **UI Flow runtime audit**

> [card] Audit UI Flow runtime activity
>
> UI Flow runtime sessions are now audited in more detail. The audit log records **workflow-instance** runs, chat **message sends**, conversation **list** and **history** reads, and whether the Process Renderer performed a **render** or a start. Entries name the app and the workflow instance.
>
> For more information, see the [audit](/5.9/docs/platform-deep-dive/core-extensions/audit) documentation.
> SaaS

### **Cross-version export adaptation**

> [card] Exports adapt UI templates for older LTS targets
>
> When you export a project to an older platform version, UI-template features the target version cannot understand are removed during down-adaptation, so the export imports cleanly. This currently covers Process Renderer process-end event handlers and the Navigate To **forms to validate** setting.
>
> For more information, see [Cross-version export and import](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
> All Deployments

### **Platform and runtime improvements**

> [card] Runtime access-control hardening
>
> Runtime API requests are now authorized against the roles defined in the running build across start-process, start-workflow, task views, conversation history, and the public runtime API. Requests without a matching build role are denied, and enforcement is on by default.
> All Deployments

> [card] Theme import no longer duplicates system icons
>
> Exporting a theme no longer includes duplicate copies of built-in system icons, and importing a theme no longer creates new ones. Duplicate icon copies that accumulated in earlier versions are cleaned up automatically on upgrade — no action is required.
> All Deployments

### **Chat notifications and conversation search**

> [card] Unread-message badge and conversation search in chat
>
> > [tab] Overview
> >
> > The chat floating action button gains an **unread-message notification badge**, with a themeable **Notification Dot** you can position in the chat style panel. The chat panel also adds **search across conversation history**, which filters conversations by a text query, highlights matches, and shows an empty state when nothing matches.
> >
> > For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
>
> > [tab] Key Features
> >
> > > [card] Unread badge
> > >
> > > The chat button shows a badge with the unread agent-message count; it is hidden while the chat is open in full screen.
> >
> > > [card] Notification Dot
> > >
> > > Position and size the notification dot from the chat style panel, with theme support.
> >
> > > [card] Conversation search
> > >
> > > Search conversation history from the chat panel, with highlighted matches and an empty state.
>
> SaaS

### **Disable chat input on a condition**

> [card] Make the chat input read-only with a business condition
>
> The chat **Input** component can be disabled by a business-condition expression. When the condition evaluates true, the input becomes read-only with an explanatory tooltip, and any pending attachments and voice input are cleared.
>
> For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
> SaaS

### **Navigate To form validation**

> [card] Require form validation before a Navigate To action
>
> A **Navigate To** action can now require selected forms to pass validation before navigating, matching how Start Process and Start Workflow actions gate on validation. This is available on web, iOS, and Android.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Expired UI Flow sessions**

> [card] A session-expired screen with a start-fresh option
>
> Expired UI Flow sessions now show a **session-expired** screen with a start-fresh option instead of leaving the previous data visible in read-only form. Expired and unauthorized access is written to the audit log.
> SaaS

### **UI Flow session owner**

> [card] Restrict a running session to a single user
>
> A UI Flow can restrict a running session to a single owner. When **Allow multiple editors** is off, other users who try to open the session are shown an access-denied screen, and unauthorized access is audited. Newly created flows default to single-owner; imported and existing flows keep the previous shared behavior. A session-owner value type is available for permission-based hide and disable rules.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Process Renderer process-end handling**

> [card] Run a configurable action when an embedded process ends
>
> The Process Renderer can now run a configurable action when its embedded process ends, using a new process-end trigger on event handlers. Configure what happens at that point instead of leaving the renderer idle when the process completes.
>
> For more information, see [Process end handling](/5.9/docs/building-blocks/ui-flows#process-end-handling).
> SaaS

### **Renderer improvements**

> [card] Renderer performance and behavior
>
> * **Batched enumeration fetch:** renderers batch enumeration lookups into a single bulk request, cutting the number of calls when rendering enum-backed fields. Applies to web and mobile renderers.
> * **Process-start loader alignment:** the web renderer keeps the process-start loader visible until the first user task, matching the mobile SDKs.
>   SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

FlowX.AI 5.11 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.11 deployment guidelines](./deployment-guidelines-v5.11).


# Deployment guidelines v5.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12

Component versions and deployment notes for FlowX.AI 5.12 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.12 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.12.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.12.0 |
| - | - |
| **admin** | 11.69.2 |
| **advancing-controller** | 11.46.0 |
| **application-manager** | 11.68.3 |
| **audit-core** | 11.44.1 |
| **authorization-system** | 11.53.2 |
| **cms-core** | 11.61.1 |
| **data-search** | 11.44.1 |
| **data-sync** | 11.43.1 |
| **designer** | 11.126.1 |
| **document-plugin** | 11.68.1 |
| **email-gateway** | 11.58.1 |
| **events-gateway** | 11.49.2 |
| **file-gateway** | 11.55.1 |
| **integration-designer** | 11.90.2 |
| **license** | 11.48.1 |
| **nosql-db-runner** | 11.49.1 |
| **notification-plugin** | 11.61.2 |
| **organization-manager** | 11.53.1 |
| **process-engine** | 11.76.1 |
| **runtime-manager** | 11.68.3 |
| **scheduler-core** | 11.45.1 |
| **task-management-plugin** | 11.59.2 |
| **webhook-gateway** | 11.54.1 |

### AI base components

| Component | 5.12.0 |
| - | - |
| **embedder** | 11.5.0 |
| **knowledgebase-indexer-v2** | 11.5.0 |
| **knowledgebase-rag** | 11.5.0 |
| **doc-parser** | 11.5.0 |

### AI dev-time components

| Component | 5.12.0 |
| - | - |
| **ai-gateway** | 11.53.1 |
| **ai-analyst** | 11.5.0 |
| **ai-assistant** | 11.5.0 |
| **ai-designer** | 11.5.0 |
| **ai-developer** | 11.5.0 |
| **kb-enrichment** | 11.5.0 |
| **planner** | 11.5.0 |

### AI runtime components

| Component | 5.12.0 |
| - | - |
| **agent-builder** | 11.5.0 |
| **ai-architect** | 11.5.0 |
| **data-privacy** | 11.5.0 |
| **doc-converter** | 11.5.0 |
| **dynamic-classifier** | 11.5.0 |
| **evals-judge** | 11.5.0 |
| **speech-to-text** | 11.5.0 |
| **web-crawler** | 11.5.0 |

### AI extensions

| Component | 5.12.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.126.1` for FlowX.AI 5.12.0). The native iOS and Android renderers version independently.

| Component | 5.12.0 |
| - | - |
| **@flowx/angular-sdk** | 11.126.1 |
| **@flowx/angular-theme** | 11.126.1 |
| **@flowx/angular-ui-toolkit** | 11.126.1 |
| **@flowx/react-sdk** | 11.126.1 |
| **@flowx/react-theme** | 11.126.1 |
| **@flowx/react-ui-toolkit** | 11.126.1 |
| **@flowx/react-native-sdk** | 11.126.1 |
| **@flowx/react-native-theme** | 11.126.1 |
| **@flowx/react-native-ui-toolkit** | 11.126.1 |
| **@flowx/core-sdk** | 11.126.1 |
| **@flowx/core-theme** | 11.126.1 |
| **react-saas** | 11.126.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.12 capabilities. On SaaS they are created and managed automatically.

**Event-triggered workflows** (email and webhook triggers can start an integration workflow):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Deep Research node** (the node hands research jobs to the AI Platform over Kafka):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | dead-letter queue for failed research jobs |

**Bulk process-instance migration:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |

**Notifications:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.eventsgateway.user.notifications.v1` | application-manager, process-engine → events-gateway |

**Document classification:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → dead-letter sink (not consumed) |

### New service dependency: webhook-gateway and MongoDB

The webhook gateway now reads the runtime registry that backs event-triggered workflows, so it depends on the runtime MongoDB database in addition to its existing relational database. On SaaS this connection is provisioned and managed by FlowX.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map. | none (required) | integration-designer |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today. | `k1` | integration-designer |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index. | `PT24H` | integration-designer |

### Native PostgreSQL partitioning for the engine

On PostgreSQL, the engine converts its runtime tables to native `RANGE(partition_id)` partitioning the first time it starts on the new version, and archiving then detaches a partition instead of copying rows out of it. Deployments that never enabled partitioning are skipped entirely, and Oracle deployments are unaffected.

Unlike most 5.12 changes, this one also reaches self-hosted 5.9.x in the 5.9.5 patch rather than waiting for the next LTS release family.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Whether archiving detaches partitions with `DETACH CONCURRENTLY` on natively partitioned tables. Setting it to `false` returns archiving to the previous batched insert-and-delete, but does not undo the conversion: the tables stay natively partitioned. | `true` | process-engine |

For the conversion cost, table locking and the one-way caveat, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.12.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026

What's new in FlowX.AI 5.12: parallel multi-instance subworkflow fan-out, event-triggered integration workflows, bulk process-instance migration, personal-data mask and restore nodes, and a Db2 data source.

[FlowX.AI 5.12 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.12.0.html)

> [!NOTE]
>
> **FlowX.AI 5.12 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.12** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release lets an integration workflow fan out over a collection without a subprocess, starts workflows directly from email and webhook events, and migrates process instances to a new build in bulk. It also adds personal-data mask and restore nodes to the Integration Designer and a Db2 relational data source.

### What changed since 5.11.0

| 5.11.0 | 5.12.0 |
| - | - |
| A workflow ran once per call; fanning out over a collection needed a BPMN Call Activity and a subprocess | + **Multi-instance subworkflow node** fans a workflow over a collection directly in the Integration Designer |
| An email or webhook trigger could start a process | + **Event-triggered workflows** start an integration workflow from the same triggers |
| Process instances migrated to a new build one at a time | + **Bulk migration** moves a filtered set of instances in one operation |
| Personal-data handling was configured on the agent | + **Mask and restore nodes** place it as explicit workflow steps, with details in the run log |

***

**What's new?**

> [tab] Integrations & Data
>
> 🔀 [**Multi-instance subworkflow node**](#multi-instance-subworkflow-node) - Fan a workflow out over a collection\
> ⚡ [**Event-triggered workflows**](#event-triggered-workflows) - Start a workflow from an email or webhook\
> 🗄️ [**Db2 relational data source**](#db2-relational-data-source) - Connect to Db2 for i or Db2 LUW\
> 🔻 [**Subworkflow failure exit**](#subworkflow-failure-exit) - Send a failed mapping down its own branch\
> 🔓 [**Skip TLS verification on a REST data source**](#skip-tls-verification-on-a-rest-data-source) - Reach a trusted internal host with an untrusted certificate\
> 🔔 [**Send Notification node**](#send-notification-node) - Send a templated notification straight from a workflow

> [tab] AI Platform
>
> 🛡️ [**Personal-data mask and restore nodes**](#personal-data-mask-and-restore-nodes) - Explicit workflow steps with run-log detail\
> 🧩 [**Reusable functions as agent tools**](#reusable-functions-as-agent-tools) - Give an agent a deterministic function to call\
> 👍 [**Chat response feedback**](#chat-response-feedback) - Let users rate an agent's answer, and theme how it looks\
> 📏 [**Custom evaluators**](#custom-evaluators) - Score an agent against a rubric you write yourself\
> 🔍 [**Deep Research node**](#deep-research-node) - Research a question across the open web and file a cited report\
> 🛠️ [**Built-in agent tools by category**](#built-in-agent-tools-by-category) - Twenty ready-made tools an agent can use, picked by category\
> 🪄 [**AI Designer builds UI Flows**](#ai-designer-builds-ui-flows) - Generate and edit multi-page UI Flows from a description

> [tab] Platform
>
> 📦 [**Bulk process-instance migration**](#bulk-process-instance-migration) - Move a filtered set of instances to a new build\
> 🔎 [**Runtime list filters and a Workflow Instances page**](#runtime-list-filters-and-a-workflow-instances-page) - Find the failed run without scanning the list\
> 🎨 [**Process canvas editing**](#process-canvas-editing) - Connect, reshape and resize more directly on the BPMN canvas\
> ⚠️ [**Check a version for issues**](#check-a-version-for-issues) - Validate every workflow in the version from one panel\
> 🧱 [**Reusable UI Templates in UI Flows**](#reusable-ui-templates-in-ui-flows) - Reuse a template on UI Flow pages, not just User Tasks\
> 🌿 [**Branch management**](#branch-management) - Merge to any branch, archive or delete the ones you are done with

### **Multi-instance subworkflow node**

> [card] Multi-instance subworkflow node
>
> > [tab] Overview
> >
> > **Before 5.12.0:** running an integration workflow once per item in a collection meant leaving the Integration Designer, wrapping the workflow in a BPMN process and fanning out with a multi-instance Call Activity. **Now:** the Subworkflow node fans out over an array on its own, in parallel.
> >
> > Turn on **Parallel Multi-Instance** under **Execution** on a Subworkflow node, pick the **Input Array** to iterate, and pick the **Output Array** that collects each run's result. The node starts one subworkflow instance per element of the input array and gathers the results into the output array on the parent workflow.
>
> > [tab] Key Features
> >
> > > [card] Input Array
> > >
> > > The array of objects to iterate. One subworkflow instance starts per element. Required.
> >
> > > [card] Output Array
> > >
> > > The array each instance result is collected into. Required.
> >
> > > [card] Correlation attribute
> > >
> > > Optional. Decides which output array element each result updates. Results matching no element, or all results when no attribute is set, are appended.
> >
> > > [card] Runs in parallel
> > >
> > > Instances run in parallel, and fan-out stays inside the Integration Designer instead of requiring a BPMN Call Activity.
>
> For the full configuration reference, see [Parallel multi-instance](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) on the Subworkflow node.
> SaaS

### **Event-triggered workflows**

> [card] Event-triggered workflows
>
> > [tab] Overview
> >
> > **Before 5.12.0:** an incoming email or webhook could start a process. **Now:** the same triggers can start an integration workflow directly.
> >
> > A workflow declares the trigger it listens for, and the platform keeps a subscription registry so a change to that trigger takes effect without rebuilding the whole app. Incoming email and webhook events are routed to the workflow that subscribes to them.
>
> > [tab] Key Features
> >
> > > [card] Email and webhook triggers
> > >
> > > Both trigger types can start a workflow, not only a process.
> >
> > > [card] Subscription registry
> > >
> > > Trigger changes update the affected data source without a full build recompute.
>
> > [tab] Architecture
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Trigger subscription changes | admin, integration-designer, application-manager | Design-time changes update the runtime subscription registry |
> > | Event delivery | email-gateway, webhook-gateway, integration-designer | Events are routed to the subscribing workflow |
> > | Webhook state | webhook-gateway | The webhook gateway now also reads the runtime registry, adding a MongoDB dependency it did not previously have |
> >
> > On SaaS these changes are applied automatically. See [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12) for the topic and dependency detail.
>
> For the full configuration reference, see [External triggers](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers) on the Start node.
> SaaS

### **Bulk process-instance migration**

> [card] Bulk process-instance migration
>
> > [tab] Overview
> >
> > **Before 5.12.0:** moving running process instances onto a new build was a one-at-a-time operation. **Now:** a filtered set of instances migrates in a single run.
> >
> > Select the target build, filter the instances to move, check the migration for problems before committing to it, and then run it. Progress and per-instance outcomes are available while it runs, and terminated instances are handled explicitly rather than failing the batch.
> >
> > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > See migrating process instances.
>
> > [tab] Key Features
> >
> > > [card] Filter then migrate
> > >
> > > Move specific instance UUIDs, the instances matching a process, node and status filter, or every eligible instance.
> >
> > > [card] Pre-flight check
> > >
> > > Validate a migration before running it.
> >
> > > [card] Per-instance outcomes
> > >
> > > Inspect details and results for the instances in a batch.
> >
> > > [card] Audit trail
> > >
> > > Migrations are recorded against the instances they touch.
>
> For the full configuration reference, see the [Migrate process instances](/5.9/docs/projects/runtime/active-process/migrate-process-instances) documentation.
> SaaS

### **Runtime list filters and a Workflow Instances page**

> [card] Runtime list filters and a Workflow Instances page
>
> Finding a failed run no longer means scanning an unfiltered list. The **Process Instances** and **UI Flow Sessions** lists gain a multi-select **Status** filter and a start-date filter on their columns, so "every failed instance since last night" is two clicks.
>
> Workflow runs get more: a new **Workflow Instances** page under **Runtime** lists every run in the project, filterable by **Status**, by date, and by **Origin**: whether a run was started by a process, a UI Flow, a webhook, or an email trigger. Until now, a workflow's runs were only visible from inside that workflow in the Integration Designer.
>
> For details, see the [Workflow Instances](/5.9/docs/projects/runtime/workflow-instances) documentation.
> SaaS

***

### **Personal-data mask and restore nodes**

> [card] Personal-data mask and restore nodes
>
> > [tab] Overview
> >
> > **Before 5.12.0:** personal-information handling was configured on the agent rather than placed in the flow. **Now:** masking and restoring personal data are workflow nodes you position explicitly, and you choose which key from the node input they apply to.
> >
> > Put a mask node before the step that must not see the raw values and a restore node after it. The workflow run log shows what each node did, so a run can be inspected without exposing the underlying data.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See the Personal Information Guard documentation.
>
> > [tab] Key Features
> >
> > > [card] Mask and restore as nodes
> > >
> > > Personal-data handling becomes an explicit step in the workflow.
> >
> > > [card] Selectable input key
> > >
> > > Choose which key from the node input the node applies to.
> >
> > > [card] Run-log detail
> > >
> > > A restore reports whether it completed, partially completed or failed, and how many of the issued placeholders it put back.
>
> For the full configuration reference, see [Masking and restoring across several nodes](/5.9/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
> SaaS

### **Db2 relational data source**

> [card] Db2 relational data source
>
> IBM Db2 joins the relational database data sources available in the Integration Designer. Because Db2 products use different drivers, ports and catalogs, the connection starts with a **Db2 Product** choice and the rest of the form follows from it. **Db2 for i (IBM i)** is the default and **Db2 LUW** is also supported. **Db2 for z/OS** appears in the list but is not implemented in this release, and selecting it fails with an explicit error rather than falling back to another driver.
>
> The port is prefilled from the product and whether SSL is on. Db2 for i adds a naming convention, an optional library and library list, and a switch for returning character data that the host reports as binary. On Db2 for i, connections also open **read-only by default**, so turn that off if your queries need to write, and the transaction isolation level defaults to none, because a table without a journal cannot take part in a transaction. Isolation is validated when the data source is saved rather than when a query first runs.
>
> For the full configuration reference, see the [Db2 Database](/5.9/docs/platform-deep-dive/integrations/db2-database) documentation.
> SaaS

***

### **Subworkflow failure exit**

> [card] Subworkflow failure exit
>
> A Subworkflow node now has a second exit. Connect the red one and a failure takes its own branch instead of stopping the parent workflow. It is opt-in per node, so a node without that branch fails and blocks exactly as before and nothing changes for existing workflows.
>
> Only a mapping failure routes, which is the kind a workflow can be built to handle: the input mapper failing, the input not satisfying what the subworkflow expects, or the output mapper failing on merge-back. An unset subworkflow, a missing response key, no mapping at all, and the node and depth limits all still stop the run. The branch reads a fixed `subWorkflowError` key that says which mapping failed and, when a child did start, which run it was.
>
> For the full configuration reference, see [Routing a subworkflow failure](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
> SaaS

***

### **Skip TLS verification on a REST data source**

> [card] Skip TLS verification on a REST data source
>
> A REST data source can now be told to stop checking the certificate of the host it calls, for the cases where an internal endpoint presents a self-signed or mismatched certificate and the alternative is an infrastructure workaround. It is off by default and set per data source, so turning it on for one connector leaves every other call verified.
>
> The Designer warns while it is on, because the call can no longer tell the intended host from anything intercepting it. One consequence is worth knowing before you use it: a truststore configured under Certificates is ignored while verification is skipped, since skipping replaces it rather than adding to it.
>
> For the full configuration reference, see [TLS verification](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#tls-verification) on a REST data source.
> SaaS

***

### **Send Notification node**

> [card] Send Notification node
>
> Workflows can now send notifications themselves. A **Send Notification** node, under **Tools** in the workflow node palette, takes one of your project's notification templates, fills its variables from workflow data, and sends it, without routing through a process just to reach the Notifications plugin.
>
> Address it with **To**, **Cc** and **Bcc**, as fixed addresses or `${}` keys. Email options are all overridable per node: subject, sender name and email, attachments by file path or `${}` key, and custom headers. The node reports the outcome under its response key, including recipient counts and the error when sending fails, so the workflow can branch on it.
>
> For the full configuration reference, see the [Send Notification node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node) documentation.
> SaaS

***

### **Reusable functions as agent tools**

> [card] Reusable functions as agent tools
>
> An AI node's tools can now include a **Function**, alongside built-in web search, an MCP server, and a workflow. Point an agent at a reusable function when the work is deterministic and you would rather it call your code than reason its way there.
>
> A function has to be typed to qualify: it needs both an input and an output slice, and functions without them do not appear in the picker. Give it a description as well, since that is what tells the agent when to reach for it.
>
> For the full configuration reference, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **Chat response feedback**

> [card] Chat response feedback
>
> Users can rate an agent's answer in the chat component, and follow the rating with a reason. The ratings are recorded in audit, so the quality of a deployed agent becomes something you can look at rather than guess at.
>
> The feedback controls and the reason chips are themable, with their own selected and hover states, so they can be styled to match the rest of the interface. The SDKs expose the same feedback state to custom front ends.
>
> For the full configuration reference, see [Rating an answer](/5.9/ai-platform/chat-component#rating-an-answer) on the chat component.
> SaaS

***

### **Custom evaluators**

> [card] Custom evaluators
>
> The evaluator catalogue is no longer fixed. When none of the built-in rubrics measures what you care about, you can write your own evaluator, give it the scoring instructions the judge LLM should follow, and it appears in the catalogue under a **Custom** group alongside the built-in ones.
>
> Choose **Numeric** scoring for a score between 0 and 1 with a pass threshold, or **Binary** for a straight pass or fail. You can start from an existing evaluator to adapt a built-in rubric rather than writing a prompt from scratch. Custom evaluators belong to the workflow you create them in, and unlike the built-in ones they can be edited and deleted.
>
> For the full configuration reference, see the [Evaluations](/5.9/ai-platform/evaluations#custom) documentation.
> SaaS

***

### **Deep Research node**

> [card] Deep Research node
>
> A new AI node researches a question across the open web and files a cited report into a Knowledge Base. It plans the work, sends sub-researchers out to search and read pages, grades what they bring back, and keeps going until its budget is spent or it has enough to report.
>
> Unlike a Custom Agent, you do not write the method: the research prompt is built into the node, so you describe the subject and bind workflow data into it. Depth is a **Quick**, **Standard** or **Deep** preset, or **Custom** if you want to set the number of passes and tool calls yourself. You can restrict which domains the research may read, with an allow list, a deny list, or both.
>
> The result always lands in a Knowledge Base as text, so retrieval nodes and other agents can reach it later. Rendering it as a document is optional.
>
> For the full configuration reference, see the [Deep Research node](/5.9/docs/platform-deep-dive/integrations/deep-research-node) documentation.
> SaaS

***

### **Built-in agent tools by category**

> [card] Built-in agent tools by category
>
> A Custom Agent's built-in tools are now a catalog you pick from by category: **Math tools**, **List tools**, **Date tools**, **Text tools**, and **Web search**. Each category row shows exactly which tools it turns on, and the agent runs deterministic code for that work instead of estimating it in the model.
>
> The catalog holds twenty tools, fifteen of them new: a full date family (business days, date arithmetic, formatting, parsing, timezone conversion), text helpers (regex match and extract, fuzzy match), unit conversion, and list aggregation, joining the original calculator, compare, sort, and filter. Web search is part of the same catalog rather than a separate toggle.
>
> Selection stays opt-in and per node. Agents saved with the old toggles keep working without an edit.
>
> For details, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **AI Designer builds UI Flows**

> [card] AI Designer builds UI Flows
>
> The AI Designer now works at the level of a whole UI Flow. Describe the journey and it generates a multi-page flow: structure first, pages filled in parallel, navigation wired between them. Ask for a change and it edits the affected pages instead of regenerating everything.
>
> Proposals appear on the UI Flow canvas as a draft for you to review, the editor stays locked while one is pending, and any data-model changes the flow needs are presented for approval on every turn, the same way single-screen generation already works.
>
> For details, see the [AI Designer](/5.9/ai-platform/pre-built-agents/ai-designer#ui-flow-generation-and-editing) documentation.
> SaaS

***

### **Check a version for issues**

> [card] Check a version for issues
>
> The Designer can now validate the resources in a project version and collect what it finds in one **Issues** panel at the bottom of the screen. Findings are marked where they occur, on resource lists, page titles and workflow canvas nodes, and selecting a marker opens the panel on that finding.
>
> Checks run when you ask for one, and the panel says when it last ran so a stale result is obvious. You can scope the list to the whole version, the resource you are in, or the node you have selected, filter it by severity or text, and group it by resource or severity. Opening **Commit Changes to Version** runs a check on its own and shows each changed resource's state beside it, as a review step rather than a gate. Integration workflows are the resource type validated in this first iteration.
>
> For the full configuration reference, see the [Checking a version for issues](/5.9/docs/projects/managing-applications/checking-for-issues) documentation.
> SaaS

***

### **Branch management**

> [card] Branch management
>
> Project branches gained a management layer. The merge modal now offers every branch you can merge into, not just the current branch's parents, so a fix made anywhere can land anywhere it is needed.
>
> Branches you are done with no longer linger: **Archive Branch** retires one (with a required reason, shown later in its info panel), **Unarchive Branch** brings it back, and **Delete Branch** removes one permanently, guarded so it refuses while child branches, an uncommitted draft, or a running merge depend on it, and asks you to type the branch name when unmerged work would be lost. Deleting has its own permission.
>
> Branch and version info panels round it out: a version merged from another branch says where it came from, including whether that branch has since been archived.
>
> For details, see [Managing branches](/5.9/docs/projects/managing-applications/versioning#managing-branches).
> SaaS

***

### **Process canvas editing**

> [card] Process canvas editing
>
> The BPMN canvas gains a set of direct editing improvements. A **New Node** panel and
> drop-anywhere connecting make it quicker to add a node and wire it up, connecting to a nearby
> node no longer means aiming precisely at a handle, and sequence flows can be reshaped by
> dragging their control points. Swimlanes now resize from any of their four edges. The
> process-instance viewer picks up the same canvas.
>
> The canvas is deliberately unchanged to look at, so existing diagrams, habits and screenshots
> still hold.
>
> For the full configuration reference, see [Faster ways to build](/5.9/docs/building-blocks/process/process#faster-ways-to-build) on the Process Designer canvas.
> SaaS

***

### **Reusable UI Templates in UI Flows**

> [card] Reusable UI Templates in UI Flows
>
> A Reusable UI Template can now be built for **UI Flow** pages as well as for the User Tasks in a process. Each template declares where it is used when you create it, and the UI Flow editor can drop templates onto a page the same way the Process editor always could.
>
> The host type also decides which actions a template's event handlers offer, so a template built for UI Flows gets navigation and workflow actions while one built for processes gets node actions. Because of that the choice is fixed once the template exists, and templates you created before this release count as Process templates, so nothing you already built changes.
>
> For the full configuration reference, see [Where a template can be used](/5.9/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used) in the Reusable UI Templates documentation.
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12).


# Deployment guidelines v5.13.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13

Component versions and deployment-level changes for FlowX.AI 5.13.0.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.13 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency. Self-hosted deployments receive these capabilities with the next LTS release family.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.13.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.13.0 |
| - | - |
| **admin** | 11.97.0 |
| **advancing-controller** | 11.67.0 |
| **application-manager** | 11.101.0 |
| **audit-core** | 11.69.0 |
| **authorization-system** | 11.78.0 |
| **cms-core** | 11.88.0 |
| **data-search** | 11.67.0 |
| **data-sync** | 11.68.0 |
| **designer** | 11.168.1 |
| **designer-user** | 11.8.0 |
| **document-plugin** | 11.95.0 |
| **email-gateway** | 11.83.0 |
| **events-gateway** | 11.72.0 |
| **file-gateway** | 11.79.0 |
| **integration-designer** | 11.119.1 |
| **license** | 11.72.0 |
| **nosql-db-runner** | 11.73.0 |
| **notification-plugin** | 11.88.0 |
| **organization-manager** | 11.77.0 |
| **process-engine** | 11.104.0 |
| **runtime-manager** | 11.101.0 |
| **scheduler-core** | 11.69.0 |
| **task-management-plugin** | 11.84.0 |
| **webhook-gateway** | 11.78.0 |

**designer-user** is new in 5.13. It backs the Designer notification center.

### AI base components

| Component | 5.13.0 |
| - | - |
| **embedder** | 11.6.0 |
| **knowledgebase-indexer-v2** | 11.6.0 |
| **knowledgebase-rag** | 11.6.0 |
| **doc-parser** | 11.6.0 |

### AI dev-time components

| Component | 5.13.0 |
| - | - |
| **ai-gateway** | 11.85.0 |
| **ai-analyst** | 11.6.0 |
| **ai-architect** | 11.6.0 |
| **ai-assistant** | 11.6.0 |
| **ai-designer** | 11.6.0 |
| **ai-developer** | 11.6.0 |
| **harness** | 11.6.0 |
| **ai-render-host** | 11.168.1 |
| **kb-enrichment** | 11.6.0 |
| **planner** | 11.6.0 |

**harness** and **ai-render-host** are new in 5.13. Together they run the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness): harness is the agent service, and ai-render-host renders UI flows headlessly for the agent. ai-render-host ships at the designer version.

### AI runtime components

| Component | 5.13.0 |
| - | - |
| **agent-builder** | 11.6.0 |
| **cee-pii** | 11.6.0 |
| **data-privacy** | 11.6.0 |
| **doc-converter** | 11.6.0 |
| **dynamic-classifier** | 11.6.0 |
| **evals-judge** | 11.6.0 |
| **speech-to-text** | 11.6.0 |
| **web-crawler** | 11.6.0 |

### AI extensions

| Component | 5.13.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.10.2 |
| **observatory-platform** | 11.10.2 |
| **observatory-web** | 11.10.2 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.168.1` for FlowX.AI 5.13.0). The native iOS and Android renderers version independently.

| Component | 5.13.0 |
| - | - |
| **@flowx/angular-sdk** | 11.168.1 |
| **@flowx/angular-theme** | 11.168.1 |
| **@flowx/angular-ui-toolkit** | 11.168.1 |
| **@flowx/react-sdk** | 11.168.1 |
| **@flowx/react-theme** | 11.168.1 |
| **@flowx/react-ui-toolkit** | 11.168.1 |
| **@flowx/react-native-sdk** | 11.168.1 |
| **@flowx/react-native-theme** | 11.168.1 |
| **@flowx/react-native-ui-toolkit** | 11.168.1 |
| **@flowx/core-sdk** | 11.168.1 |
| **@flowx/core-theme** | 11.168.1 |
| **react-saas** | 11.168.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

***

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.13 capabilities. On SaaS they are created and managed automatically.

**Notification center:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |

Notifications now pass through designer-user, which stores them and forwards them to events-gateway on the existing `ai.flowx.eventsgateway.user.notifications.v1` topic for delivery to the Designer.

**Move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

### New services

The Developer Agentic Harness adds the **harness** and **ai-render-host** services to the AI dev-time group, with a dedicated PostgreSQL database for harness sessions. The notification center adds the **designer-user** core service, which uses MongoDB, Redis, and Kafka. On SaaS these services and their databases are provisioned and managed by FlowX.

### New service dependency: process-engine and object storage

Oversized workflow responses and UI flow updates are now offloaded to object storage instead of travelling inline on Kafka. The process engine reads these offloaded payloads, so it now depends on object storage in addition to its existing databases. On SaaS this connection is provisioned and managed by FlowX.

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` | process-engine, audit-core |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Self-hosted deployments receive this change with the next LTS release family. A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.13.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026

What's new in FlowX.AI 5.13: a user notification center in Designer, UI component copy and paste across contexts, commit descriptions on app versions, and move token on process instances.

[FlowX.AI 5.13 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.13.0.html)

> [!NOTE]
>
> **FlowX.AI 5.13 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.13** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. The headline: the FlowX Developer Agentic Harness, an AI agent in the Designer that builds and changes apps from a description, with you confirming the plan and every operation before it runs. The release also adds a notification center to the Designer, lets builders copy and paste UI components across apps with a review of what could not be placed, records a description on every app version commit, forwards runtime events to Mixpanel and GA4, and moves stuck tokens on running process instances.

### What changed since 5.12.0

| 5.12.0 | 5.13.0 |
| - | - |
| Apps were assembled by hand in the Designer | + **Developer Agentic Harness**: describe the change, confirm the plan, review the result on its own branch |
| Long-running operations surfaced as passing toasts | + **Notification center** keeps a searchable 30-day history with read state |
| UI components copied within one context | + **Copy and paste across contexts**, with a paste review and unique naming |
| App version commits had a name only | + **Commit descriptions** and a commit details view record why a version exists |
| A stuck process instance needed support intervention | + **Move token** relocates the token, guarded by a dedicated corrective-actions role |

***

**What's new?**

> [tab] Builders
>
> 🔔 [**User notification center**](#user-notification-center) - Bell, searchable history, read state in Designer\
> 📋 [**UI component copy and paste**](#ui-component-copy-and-paste) - Cross-context paste with review and unique naming\
> 📝 [**Commit descriptions and details**](#commit-descriptions-and-details) - Optional description on version commits plus a details view\
> 📦 [**Version export alignment**](#version-export-alignment) - Version exports bundle dependencies like build exports

> [tab] Platform
>
> 🚑 [**Move token and corrective actions**](#move-token-and-corrective-actions) - Relocate a token, gated by a dedicated role

> [tab] AI Platform
>
> 🪄 [**Developer Agentic Harness**](#developer-agentic-harness) - Describe a change, the agent plans and builds it on a branch\
> 🧠 [**ML corpus import and export**](#ml-corpus-import-and-export) - Move a document classifier corpus between environments\
> ⚖️ [**Fair scheduling for embedding jobs**](#fair-scheduling-for-embedding-jobs) - Knowledge Base ingestion no longer starves small jobs\
> 🧩 [**Data Parse node**](#data-parse-node) - Tabular Data Extraction generalized, now parses XML and JSON\
> 🔐 [**File Encryption node**](#file-encryption-node) - Encrypt and decrypt files inside a workflow

> [tab] Rendering & SDKs
>
> 💬 [**React Native chat component**](#react-native-chat-component) - Floating chat sheet with voice input on mobile\
> ▶️ [**Conditional start workflow trigger**](#conditional-start-workflow-trigger) - Start a workflow from the UI only when a condition holds

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > **Before 5.13.0:** every process, screen, and data type was assembled by hand in the Designer. **Now:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys your app first, so changes use your real resources and names, then drafts a plan for you to confirm.
> >
> > You hold every gate: the agent runs only after you confirm the plan and review each operation, the change lands on a dedicated branch that never touches your main line, and merging plus serving a new version stay human decisions. See the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness) page for the full flow.
> >
> > <video>
> >   <track label="English" />
> > </video>
>
> > [tab] Key Features
> >
> > > [card] Works on your real app
> > >
> > > Surveys existing resources first, so changes use your actual processes, data types, and names.
> >
> > > [card] Plan, confirm, then run
> > >
> > > You confirm the plan and review every operation; the change runs on a dedicated branch that only you can merge or serve.
> >
> > > [card] Broad resource coverage
> > >
> > > Creates and edits processes, UI flows, workflows, and project data types.
> >
> > > [card] Guarded operations
> > >
> > > Destructive changes are gated, and runtime data such as process instances is never touched.
>
> SaaS

### **User notification center**

> [card] User notification center
>
> > [tab] Overview
> >
> > **Before 5.13.0:** long-running operations such as app imports or instance migrations announced themselves once and were gone. **Now:** a bell in the Designer opens a notification center with a 30-day history.
> >
> > Notifications carry read state, search, and filters by unread status and workspace type. First producers: app version export and process instance migration results.
>
> > [tab] Key Features
> >
> > > [card] 30-day history
> > >
> > > Notifications persist for 30 days instead of disappearing with the toast.
> >
> > > [card] Read state and search
> > >
> > > Mark notifications read, search them, and filter by unread status or workspace type.
> >
> > > [card] Export and migration results
> > >
> > > Get notified when an app version export finishes, fails, or times out, and when a process instance migration completes.
> >
> > > [card] Live updates
> > >
> > > The center updates over a live stream, including read state changes from other sessions.
>
> SaaS

### **UI component copy and paste**

> [card] UI component copy and paste
>
> > [tab] Overview
> >
> > **Before 5.13.0:** copying UI components was limited to the context you were in. **Now:** builders copy components and paste them into another UI Flow, app, or context.
> >
> > Pasting responds with a review of what could not be placed instead of failing silently, and pasted components receive unique names automatically. The clipboard holds one consistent version of the copied structure.
>
> > [tab] Key Features
> >
> > > [card] Cross-context paste
> > >
> > > Paste a copied component into a different UI Flow or app through a dedicated modal.
> >
> > > [card] Paste review
> > >
> > > The paste result names anything it could not place, so nothing drops without a trace.
>
> SaaS

### **Commit descriptions and details**

> [card] Commit descriptions and details
>
> Committing or merging an app version now takes an optional description of up to 2000 characters, and a commit details view shows what a version contains and why it exists. Version history stops being a list of names.
> SaaS

### **Version export alignment**

> [card] Version export alignment
>
> Project version exports now bundle dependencies the same way build exports do, so a version export is self-contained. The export dialog pre-selects the target platform version, and the exported filename carries the target version and whether media is included.
> SaaS

### **Move token and corrective actions**

> [card] Move token and corrective actions
>
> > [tab] Overview
> >
> > **Before 5.13.0:** a process instance stuck on the wrong node needed support intervention. **Now:** an operator with the corrective-actions role moves the token to the right node from Runtime.
> >
> > Corrective actions, covering bulk instance migration and move token, are gated by a dedicated workspace-level role, so admins grant this power without handing out full admin rights.
> >
> > The **Workspace corrective actions editor** role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically. See [Move tokens](/5.9/docs/projects/runtime/active-process/move-token) and the [Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
>
> > [tab] Key Features
> >
> > > [card] Move token
> > >
> > > Relocate the token of a running instance to another node in the process definition.
> >
> > > [card] Dedicated role
> > >
> > > A workspace-level corrective-actions role scopes who can migrate instances and move tokens.
>
> SaaS

### **ML corpus import and export**

> [card] ML corpus import and export
>
> A document classifier corpus now moves between environments: export the corpus with the model, import it into a runtime classifier, and inspect it in a read-only view in the Data tab. Training data stops being trapped in the environment where labeling happened.
> SaaS

### **Fair scheduling for embedding jobs**

> [card] Fair scheduling for embedding jobs
>
> Knowledge Base embedding jobs are scheduled fairly by default, so a large ingestion no longer starves small jobs queued behind it. Uploads to one Knowledge Base stop delaying every other one on the environment.
> SaaS

### **Data Parse node**

> [card] Data Parse node
>
> The Tabular Data Extraction node is generalized into a **Data Parse** node: it still reads CSV and Excel files into workflow data, and now also parses **XML** and **JSON**. A file fetched by a File Storage Operation can be read into the workflow regardless of its structured format.
> SaaS

### **File Encryption node**

> [card] File Encryption node
>
> A new **File Encryption** workflow node encrypts or decrypts a file with a password directly in the workflow, so protecting a generated document or opening a protected upload no longer needs a custom integration. The file path and password take expressions, letting the password come from workflow data.
> SaaS

### **React Native chat component**

> [card] React Native chat component
>
> The React Native renderer gains the chat experience mobile apps were missing: a floating chat sheet with voice input, suggested prompts, and conversation history. Renderer updates in the same release cover form validation on navigation actions, action context on execute-URL, and bulk enum fetching on eager load.
> SaaS

### **Conditional start workflow trigger**

> [card] Conditional start workflow trigger
>
> A start workflow trigger in the UI now takes a condition, so the workflow starts only when the expression holds. Available in the web SDK and on iOS.
> SaaS

### **Smaller improvements**

> [card] Smaller improvements
>
> **Process details modal:** the process name moves from Settings into a Details modal.
>
> **Document and image sources:** Document and Image UI components share one source configuration. In process user tasks, the new **Document Plugin Path** source takes a Documents plugin `downloadPath` directly, so you no longer need a business rule to build the file URL. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13) for File Preview and the [Download component](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download#file-sources-in-flowx-ai-5-13).
>
> **Sign-up link to solution:** a sign-up link lands new users directly in the right solution.
>
> **Bulk invite:** inviting many users at once gets a reworked flow.
>
> **Task list search on translated labels:** the task list searches, filters, and sorts on the labels it displays, in the viewer's language, for status, enumeration, and substitution-tag columns. See [Search and sort on translated labels](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).&#x20;
>
> **Reserved substitution-tag prefix:** custom substitution tags can no longer start with `sys_`; the prefix is reserved for system tags.&#x20;
> **Intersects operator for array fields:** FlowX Database queries can match documents whose array field shares at least one value with a given list. See [Intersects on array fields](/5.9/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).&#x20;
>
> **Request after PII anonymization in the run log:** AI nodes with the input scan enabled log the request exactly as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/5.9/ai-platform/personal-information-guard#request-after-pii-anonymization).&#x20;
>
> **Elasticsearch replica auto-expansion:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Changed default: Elasticsearch replica auto-expansion](./deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).&#x20;
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.13.0](./deployment-guidelines-v5.13).


# Deployment guidelines v5.2.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/deployment-guidelines-v5.2

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.12.0** | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **10.12.0** | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **10.7.0** | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **10.7.0** | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **10.6.0** | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **10.4.1** | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **10.6.0** | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **10.4.1** | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **10.8.0** | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **10.3.1** | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **10.4.1** | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **10.0.0** | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **10.0.0** | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.0.1** | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | **10.2.0** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.2.0 | Keycloak | 26+ |
| 5.2.0 | Kafka | 3.8 - 3.9 |
| 5.2.0 | PostgreSQL | 16 - 17 |
| 5.2.0 | Oracle Database | 21c, 23ai |
| 5.2.0 | MongoDB | 7 - 8 |
| 5.2.0 | Redis | 7.4 - 8.0 |
| 5.2.0 | Elasticsearch | 8 - 9 |
| 5.2.0 | Angular (Web SDK) | 19.2 |
| 5.2.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.2.0

### Key infrastructure updates

> [card] SpiceDB Upgrade
>
> Upgraded to SpiceDB v1.38.0+ and spice-db-operator for improved permission management and stability

> [card] Security Enhancements
>
> Updated Java libraries and base images to Oracle 10-slim, resolving HIGH and CRITICAL vulnerabilities

> [card] Accessibility Support
>
> Enhanced renderer components with comprehensive WCAG 2.1 compliance features

> [card] Python IDE Features
>
> Added autocomplete and IntelliSense support in business rules editors

> [card] Parallel Workflow Branches
>
> Support for concurrent execution paths in Integration Designer workflows

> [card] Workflow Partitioning & Archiving
>
> Time-based partitioning and automatic archiving for Integration Designer workflow instances

## Upgrading from v5.1.0

### Key changes

* **Accessibility Features**: No breaking changes, but new accessibility properties available in UI Designer
* **Database Security**: FlowX Database now supports sensitive data masking (requires Project Data Model configuration)
* **IDE Enhancements**: Python autocomplete is automatically available in business rules editors
* **Infrastructure**: SpiceDB upgrade requires cache clearing after migration

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.

### Compatibility

* **Backward Compatible**: v5.2.0 maintains backward compatibility with v5.1.0 configurations
* **Renderer Updates**: Web SDKs include accessibility enhancements without breaking changes
* **Mobile Renderers**: iOS and Android renderers include accessibility improvements

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/update-environment-variables-5.2

Update environment variables for all existing FlowX.AI services

## Integration Designer

### Workflow partitioning and archiving

> [!NOTE]
>
> Integration Designer now supports workflow instance partitioning and automatic archiving for efficient data management in high-volume deployments.

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Enable or disable workflow instance partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Time interval for creating partitions (`DAY`, `WEEK`, `MONTH`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Enable or disable automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Cron expression for archiving schedule (default: daily at 1:00 AM) |

> [!NOTE]
>
> **Workflow partitioning configuration:**
>
> * **Partitioning**: When enabled, workflow instances are stored in time-based partitions according to the specified interval
> * **Retention**: Determines how many intervals to keep active. Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> * **Archiving schedule**: The cron expression controls when the archiving process runs
> * **Best practice**: Enable partitioning first without archiving, verify it works correctly, then enable archiving

> [!WARNING]
>
> Enable partitioning and archiving only after careful planning and testing. Ensure your database has sufficient storage for partition management operations. It's recommended to start with archiving disabled and enable it only after verifying that partitioning works correctly for your use case.

### Advancing controller improvements

> [!NOTE]
>
> Integration Designer now uses the new ADVANCING controller with separate picking and processing operations for improved performance and resource management.

#### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

#### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.


# FlowX.AI 5.2.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025

Accessibility improvements, new side panel navigation, FlowX Database sensitive data handling, REST API response caching, and Python IDE enhancements for business rules development.

**What's new?**

> [tab] Accessibility & UX
>
> Making FlowX applications more inclusive and user-friendly with comprehensive accessibility improvements and enhanced navigation.
>
> ♿ [**Accessibility Enhancements**](#accessibility-enhancements) - Comprehensive [WCAG](https://www.w3.org/TR/WCAG21/) (Web Content Accessibility Guidelines) compliance features across all UI components\
> 🎨 [**New Workflow Side Panel**](#new-workflow-side-panel) - Enhanced navigation experience with improved drag-and-drop functionality
>
> ### **Accessibility enhancements**
>
> > [card] Accessibility enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds accessibility features across all UI components, enabling you to build [WCAG 2.1 Level AA compliant](https://www.w3.org/TR/WCAG21/) applications. These features support users with assistive technologies such as screen readers and keyboard-only navigation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs1.png)
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs2.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Accessibility Configuration Panel
> > > >
> > > > Configure labels, descriptions, and ARIA attributes in a dedicated accessibility section within UI Designer
> > >
> > > > [card] Auto-bindable Tags
> > > >
> > > > Bind accessibility tags automatically to buttons, inputs, selects, modals, and other UI components
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Navigate using keyboard shortcuts with proper focus management and tab order in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > Use screen readers with ARIA labels, descriptions, and live regions on all components
> >
> > > [tab] Supported Components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio buttons, Slider, and File upload components with labels and descriptions
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card components with keyboard navigation and focus management
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with alt text support and semantic HTML structure
> > >
> > > **4. Cross-Platform Support**
> > >
> > > Web (Angular/React), iOS, and Android platforms
> >
> > > [tab] Benefits
> > >
> > > > [card] WCAG Compliance
> > > >
> > > > Build applications that meet WCAG 2.1 Level AA standards for web accessibility
> > >
> > > > [card] Inclusive Design
> > > >
> > > > Make your applications usable for people with diverse abilities and assistive technology users
> > >
> > > > [card] Improved User Experience
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those using assistive technologies
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Meet accessibility requirements for government, healthcare, financial services, and other regulated industries
> >
> > Major Enhancement
>
> ***
>
> ### **New workflow side panel**
>
> > [card] New workflow side panel
> >
> > > [tab] Overview
> > >
> > > The new Workflow Side Panel provides an enhanced navigation experience in Integration Designer workflows. It includes improved organization, better drag-and-drop functionality, and intuitive access to design components and resources.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_side_panel.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Drag & Drop
> > > >
> > > > Add and organize workflow nodes with drag-and-drop functionality
> > >
> > > > [card] Improved Organization
> > > >
> > > > Group nodes logically with expandable/collapsible sections
> > >
> > > > [card] Search & Filter
> > > >
> > > > Find nodes instantly with quick search functionality
> >
> > UI/UX Enhancement
>
> ***

> [tab] Data & Security
>
> Enhanced data management and security features for FlowX Database and business rules.
>
> 🔒 [**FlowX Database Sensitive Data**](#flowx-database-sensitive-data) - GDPR-compliant sensitive data handling for FlowX Database\
> 🚀 [**Performance Improvements**](#performance-improvements) - Caching optimizations for better system performance
>
> ### **FlowX database sensitive data**
>
> > [card] FlowX database sensitive data
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds sensitive data handling for FlowX Database to ensure GDPR compliance. Attributes marked as sensitive in your Project Data Model are automatically protected across all FlowX Database operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic Data Masking
> > > >
> > > > Hide sensitive attributes automatically in logs, console outputs, and testing interfaces
> > >
> > > > [card] Project Data Model Integration
> > > >
> > > > Mark attributes as sensitive in Project Data Model to apply protection across all FlowX Database operations
> > >
> > > > [card] Developer-Friendly
> > > >
> > > > Access full data at runtime while maintaining security in design-time interfaces
> > >
> > > > [card] Audit Trail Protection
> > > >
> > > > Mask sensitive data in workflow output logs and operational documents
> >
> > > [tab] Protected Areas
> > >
> > > **1. Documents Page**
> > >
> > > Sensitive attributes are masked when viewing FlowX Database documents in the designer
> > >
> > > **2. Test Operations Pages**
> > >
> > > Database operation testing interfaces automatically hide sensitive data
> > >
> > > **3. Workflow Console**
> > >
> > > Console logs and output panels mask sensitive information from FlowX Database responses
> > >
> > > **4. Full Runtime Access**
> > >
> > > Applications have full access to sensitive data at runtime - protection is design-time only
> >
> > > [tab] Benefits
> > >
> > > > [card] GDPR Compliance
> > > >
> > > > Meet data protection requirements by preventing sensitive data exposure in design tools
> > >
> > > > [card] Security by Design
> > > >
> > > > Sensitive data protection is automatic once attributes are marked in Project Data Model
> > >
> > > > [card] Developer Productivity
> > > >
> > > > Test and develop without worrying about accidentally exposing sensitive information
> > >
> > > > [card] Audit-Ready
> > > >
> > > > Demonstrate proper data handling practices with masked logs and interfaces
> >
> > Security Enhancement
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Caching Enhancements
> > >
> > > FlowX.AI 5.2.0 adds intelligent caching mechanisms that improve system performance by reducing redundant processing when identical values are sent at process start.
> >
> > > [tab] Key Features
> > >
> > > > [card] Smart Caching
> > > >
> > > > Cache and reuse results automatically when identical input values are detected
> > >
> > > > [card] Reduced Latency
> > > >
> > > > Start processes faster when repeating operations with the same parameters
> > >
> > > > [card] Resource Optimization
> > > >
> > > > Reduce server load and improve resource utilization
> > >
> > > > [card] Automatic Management
> > > >
> > > > Manage cache automatically with no configuration required
> >
> > > [tab] Benefits
> > >
> > > **1. Response Times**
> > >
> > > Initialize processes faster in cached scenarios
> > >
> > > **2. Scalability**
> > >
> > > Handle more concurrent users with the same infrastructure
> > >
> > > **3. Cost Efficiency**
> > >
> > > Use fewer compute resources for high-volume scenarios
> >
> > Performance

> [tab] Developer Experience
>
> Enhanced tools and features for business rules development, testing, and workflow design.
>
> 🔀 [**Parallel Branches in Workflows**](#parallel-branches-in-workflows) - Design and execute parallel execution paths in Integration Designer workflows\
> 💾 [**REST API Response Caching**](#integration-designer-rest-api-response-caching) - Cache GET endpoint responses in Integration Designer with flexible TTL policies\
> 📊 [**Workflow Partitioning & Archiving**](#workflow-partitioning-&-archiving) - Manage Integration Designer workflow data efficiently with time-based partitions and automatic archiving\
> 🐍 [**Python IDE Enhancements**](#python-ide-enhancements) - Autocomplete and IntelliSense for Python business rules\
> 🧪 [**Business Rules Testing**](#functions-testing) - Save test parameters in reusable functions modal
>
> ### **Parallel branches in workflows**
>
> > [card] Parallel branches in workflows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds the ability to design and execute parallel branches in Integration Designer workflows. This enables concurrent execution of independent workflow paths and improves performance for complex integrations.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Start Parallel Node
> > > >
> > > > Split workflow execution into multiple concurrent branches with start parallel nodes
> > >
> > > > [card] End Parallel Node
> > > >
> > > > Merge parallel branches with end parallel nodes that wait for all branches to complete
> > >
> > > > [card] Path Visualization
> > > >
> > > > View which nodes belong to which parallel branch with visual path indexing in the workflow diagram
> > >
> > > > [card] Runtime Monitoring
> > > >
> > > > Track parallel path execution with timing information for each branch and merge point
> >
> > > [tab] How It Works
> > >
> > > **1. Design Parallel Paths**
> > >
> > > Add a Start Parallel node and create multiple sequences from it. Each sequence represents an independent execution path
> > >
> > > **2. Configure Branch Logic**
> > >
> > > Add workflow nodes to each parallel branch, such as API calls, transformations, or database operations
> > >
> > > **3. Merge Paths**
> > >
> > > Close parallel branches with an End Parallel node. This node waits for all branches to complete before continuing
> > >
> > > **4. Runtime Execution**
> > >
> > > All branches execute concurrently at runtime. The End Parallel node completes when the slowest branch finishes
> >
> > > [tab] Use Cases
> > >
> > > > [card] Multiple API Calls
> > > >
> > > > Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Fetch data from multiple sources in parallel for comprehensive data aggregation
> > >
> > > > [card] Notification Broadcasting
> > > >
> > > > Send notifications through multiple channels (email, SMS, push) simultaneously
> > >
> > > > [card] Document Processing
> > > >
> > > > Process different document types or sections in parallel for faster throughput
> >
> > > [tab] Runtime Behavior
> > >
> > > > [accordion] Path Timing
> > > >
> > > > * **Path Time**: Sum of all node execution times within that branch
> > > > * **End Parallel Time**: Node processing time + maximum time across all parallel paths
> > > > * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
> > >
> > > > [accordion] Console Logging
> > > >
> > > > * **Start Parallel Node**: Displays Input tab showing data split across branches
> > > > * **End Parallel Node**: Displays Output tab showing merged results from all branches
> > > > * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
> > >
> > > > [accordion] Error Handling
> > > >
> > > > * If any branch fails, the workflow handles it according to standard error handling rules
> > > > * End Parallel node waits for all non-failed branches before continuing
> > > > * Runtime validation ensures parallel branches are configured correctly
> >
> > > [tab] Limitations
> > >
> > > > [!WARNING]
> > > >
> > > > **First Iteration Constraints**: This is the initial implementation of parallel branches with the following considerations:
> > >
> > > * **Array Processing**: Arrays are not merged across parallel branches. When multiple branches modify the same array path, the last branch to complete determines the final array value. You cannot process individual objects from the same array in different parallel branches (for example, first element in branch 1, second element in branch 2). To preserve data from all branches, save to different keys and merge manually using a script before the end node
> > >
> > > * **Branch Closure**: All start parallel branches must be closed with end parallel nodes. Nodes following a start parallel node must merge into the same end parallel node, except for nodes that terminate with end workflow nodes
> > >
> > > > [!NOTE]
> > > >
> > > > Based on user feedback and raised exceptions during runtime execution, additional configuration constraints and validations are planned for future releases.
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Reduce workflow execution time by running independent operations concurrently instead of sequentially
> > >
> > > **2. Resource Utilization**
> > >
> > > Maximize throughput by executing multiple operations simultaneously
> > >
> > > **3. Design Clarity**
> > >
> > > Model concurrent operations explicitly in your workflow diagrams
> > >
> > > **4. Monitoring**
> > >
> > > Track execution time for each parallel path to identify bottlenecks
> >
> > Integration Designer
>
> ***
>
> ### **Integration Designer REST API response caching**
>
> > [card] Integration Designer REST API response caching
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces intelligent response caching for REST API GET endpoints in Integration Designer. Cache responses based on flexible Time-To-Live (TTL) policies to reduce redundant API calls, avoid rate limits, and lower operational costs while maintaining data freshness.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Endpoint_Get.png)
> > >
> > > > [!NOTE]
> > > >
> > > > When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Flexible TTL Policies
> > > >
> > > > Configure caching with "Expires after" (duration-based) or "Expires at" (time-based) policies
> > >
> > > > [card] Cache Management
> > > >
> > > > Clear cached responses from endpoint definitions or testing modals as needed
> > >
> > > > [card] Cache Status Visibility
> > > >
> > > > View cache status, keys, and TTL information in testing modals and workflow console logs
> > >
> > > > [card] Automatic Fallback
> > > >
> > > > System automatically calls the external API if cache retrieval fails, ensuring reliability
> >
> > > [tab] TTL Configuration
> > >
> > > > [accordion] Expires After (Duration-Based)
> > > >
> > > > Cache responses for a specific duration after the request is made.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **ISO Duration**: Use ISO 8601 duration format (e.g., `PT1H` for 1 hour, `P1D` for 1 day, `P1W` for 1 week)
> > > > * **Dynamic Duration**: Reference configuration parameters (e.g., `${myConfigParam}`)
> > > > * **Default**: `R/P1D` (1 day)
> > > >
> > > > **Example**: Cache for 10 minutes after each request
> > > >
> > > > ```
> > > > PT10M
> > > > ```
> > >
> > > > [accordion] Expires At (Time-Based)
> > > >
> > > > Cache responses until a specific time of day with recurring patterns.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **Expire Time**: Set specific time (e.g., `23:00` for midnight, `08:00` for 8 AM)
> > > > * **Recurrency**: Set how often the pattern repeats (integer > 0, default: 1)
> > > > * **Time Unit**: Choose Day, Week, or Month (default: Day)
> > > >
> > > > **Example**: Cache until midnight every day
> > > >
> > > > ```
> > > > Expire Time: 00:00
> > > > Recurrency: 1
> > > > Time Unit: Day
> > > > ```
> > > >
> > > > **Example**: Cache until 6 PM every Friday
> > > >
> > > > ```
> > > > Expire Time: 18:00
> > > > Recurrency: 1
> > > > Time Unit: Week
> > > > ```
> >
> > > [tab] Cache Visibility
> > >
> > > **1. Testing Modal**
> > >
> > > View cache status directly in the endpoint testing modal with:
> > >
> > > * **Cache Hit/Miss Status**: Whether results came from cache
> > > * **Cache Key**: The unique identifier for the cached response
> > > * **TTL Information**: When the cache expires (e.g., "Expires after PT10M" or "Expires at 23:00 on 2025-11-04")
> > >
> > > **2. Workflow Console**
> > >
> > > Monitor cache usage in workflow execution logs with the same detailed information
> > >
> > > **3. Clear Cache Action**
> > >
> > > Clear cached responses from the endpoint page or testing modal when cache is configured
> >
> > > [tab] How It Works
> > >
> > > **1. Configure Caching**
> > >
> > > In Integration Designer, open a REST System and navigate to a GET endpoint. Enable caching and select your TTL policy (Expires After or Expires At)
> > >
> > > **2. First Request**
> > >
> > > When the endpoint is called for the first time, the response is fetched from the external API and stored in cache with the configured TTL
> > >
> > > **3. Subsequent Requests**
> > >
> > > If the cache is still valid (within TTL), subsequent requests return the cached response immediately without calling the external API
> > >
> > > **4. Cache Expiration**
> > >
> > > Once TTL expires, the next request fetches fresh data from the external API and updates the cache
> > >
> > > **5. Cache Management**
> > >
> > > Use the "Clear Cache" action to manually invalidate cached responses when needed (e.g., after data updates)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Reference Data
> > > >
> > > > Cache country lists, product catalogs, or other reference data that rarely changes
> > >
> > > > [card] Rate Limit Avoidance
> > > >
> > > > Reduce API calls to third-party services with strict rate limits
> > >
> > > > [card] Cost Optimization
> > > >
> > > > Lower operational costs by reducing billable API calls to external services
> > >
> > > > [card] Performance
> > > >
> > > > Improve workflow execution speed by eliminating network latency for cached responses
> >
> > > [tab] Error Handling
> > >
> > > > [!WARNING]
> > > >
> > > > **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. This ensures your workflows always receive correct data.
> > >
> > > **Failure Scenarios**:
> > >
> > > * Cache service unavailable → Direct API call
> > > * Cache corruption or invalid data → Direct API call
> > > * Cache storage failure → Direct API call (with warning logged)
> > >
> > > Your workflows continue to function normally even if caching fails.
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced API Costs
> > > >
> > > > Minimize charges from external APIs by serving cached responses when data hasn't changed
> > >
> > > > [card] Improved Performance
> > > >
> > > > Return responses instantly from cache instead of waiting for external API calls
> > >
> > > > [card] Rate Limit Compliance
> > > >
> > > > Stay within API rate limits by reducing the number of requests to external services
> > >
> > > > [card] Better Scalability
> > > >
> > > > Handle higher workflow volumes without increasing external API calls
> >
> > Integration Designer
>
> > [card] [REST Endpoint Caching](../../../5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching)
> >
> > Learn how to configure caching policies, manage cache, and optimize your REST API integrations
>
> ***
>
> ### **Workflow partitioning & archiving**
>
> > [card] Workflow partitioning & archiving
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces workflow instance partitioning and archiving for Integration Designer. This feature enables efficient management of workflow data by organizing instances into time-based partitions and automatically archiving old data to maintain optimal database performance in large-scale deployments.
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow partitioning is particularly beneficial for high-volume Integration Designer workflows where instances accumulate over time, helping to maintain query performance and manage storage efficiently.
> >
> > > [tab] Key Features
> > >
> > > > [card] Time-Based Partitioning
> > > >
> > > > Organize workflow instances into partitions based on configurable time intervals (Day, Week, or Month)
> > >
> > > > [card] Automatic Archiving
> > > >
> > > > Automatically archive partitions older than the specified retention period to optimize active database size
> > >
> > > > [card] Flexible Retention Policies
> > > >
> > > > Configure how many time intervals to retain before archiving with granular control
> > >
> > > > [card] Scheduled Archiving
> > > >
> > > > Use cron expressions to schedule archiving operations at optimal times
> >
> > > [tab] Configuration
> > >
> > > Configure workflow partitioning using environment variables in Integration Designer:
> > >
> > > > [accordion] Partitioning Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ENABLED`**: Enable or disable workflow instance partitioning
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_INTERVAL`**: Time interval for creating partitions
> > > >   * Default: `MONTH`
> > > >   * Options: `DAY`, `WEEK`, `MONTH`
> > >
> > > > [accordion] Archiving Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`**: Enable or disable automatic archiving
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`**: Number of intervals to retain before archiving
> > > >   * Default: `3`
> > > >   * Options: Any positive integer
> > > >   * Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`**: Schedule for archiving operations
> > > >   * Default: `0 0 1 * * ?` (runs daily at 1:00 AM)
> > > >   * Options: Any valid cron expression
> >
> > > [tab] How It Works
> > >
> > > **1. Enable Partitioning**
> > >
> > > Set `FLOWX_DATA_PARTITIONING_ENABLED=true` to start organizing workflow instances into time-based partitions
> > >
> > > **2. Configure Partition Interval**
> > >
> > > Choose a partition interval (DAY, WEEK, or MONTH) based on your workflow volume and retention needs
> > >
> > > **3. Set Retention Policy**
> > >
> > > Define how many intervals to retain. For example, with MONTH interval and 3 retention intervals, data older than 3 months will be archived
> > >
> > > **4. Enable and Schedule Archiving**
> > >
> > > Turn on archiving and configure the cron expression to run archiving operations during low-traffic periods
> > >
> > > **5. Monitor Performance**
> > >
> > > Track database performance improvements as old partitions are archived and active data size is optimized
> >
> > > [tab] Use Cases
> > >
> > > > [card] High-Volume Workflows
> > > >
> > > > Maintain performance for Integration Designer workflows processing thousands of instances daily
> > >
> > > > [card] Compliance Requirements
> > > >
> > > > Archive historical workflow data while maintaining access to recent instances for operational needs
> > >
> > > > [card] Database Optimization
> > > >
> > > > Keep active database size manageable by automatically moving old data to archive partitions
> > >
> > > > [card] Long-Running Deployments
> > > >
> > > > Prevent database bloat in production environments running for extended periods
> >
> > > [tab] Best Practices
> > >
> > > > [!WARNING]
> > > >
> > > > **Planning and Testing Required**: Enable partitioning and archiving only after careful planning and testing. Once enabled:
> > > >
> > > > * Ensure sufficient database storage for partition management operations
> > > > * Start with archiving disabled to verify partitioning works correctly
> > > > * Test thoroughly in non-production environments before enabling in production
> > > > * Monitor database performance during initial archiving operations
> > > > * Choose partition intervals based on your workflow volume and retention requirements
> > >
> > > **Recommended Approach**:
> > >
> > > 1. Enable partitioning first without archiving
> > > 2. Monitor partition creation and database performance
> > > 3. After verifying stable operation, enable archiving
> > > 4. Schedule archiving during low-traffic periods (e.g., overnight)
> > > 5. Start with longer retention periods and adjust based on requirements
> >
> > > [tab] Benefits
> > >
> > > > [card] Improved Performance
> > > >
> > > > Maintain fast query performance as workflow instance count grows over time
> > >
> > > > [card] Efficient Storage
> > > >
> > > > Optimize database storage by archiving historical data while keeping recent data accessible
> > >
> > > > [card] Automatic Management
> > > >
> > > > Set retention policies once and let the system handle archiving automatically
> > >
> > > > [card] Scalability
> > > >
> > > > Support long-running production deployments with predictable database growth
> >
> > Integration Designer
>
> > [card] [Integration Designer Setup](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration)
> >
> > Learn how to configure workflow partitioning and archiving for Integration Designer
>
> ***
>
> ### **Python IDE enhancements**
>
> > [card] Python IDE enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds professional IDE features to Python business rules development, including autocomplete, IntelliSense, and enhanced code editing capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Autocomplete
> > > >
> > > > Get intelligent code suggestions as you type, including Python standard library and FlowX APIs
> > >
> > > > [card] IntelliSense
> > > >
> > > > Use context-aware code completion with parameter hints and documentation
> > >
> > > > [card] Syntax Highlighting
> > > >
> > > > Read code more easily with enhanced Python syntax highlighting
> > >
> > > > [card] Error Detection
> > > >
> > > > Detect syntax errors in real-time with helpful error messages
> >
> > > [tab] Benefits
> > >
> > > **1. Development Speed**
> > >
> > > Write business rules faster with intelligent code suggestions
> > >
> > > **2. Error Reduction**
> > >
> > > Catch syntax errors before deployment with real-time validation
> > >
> > > **3. API Discovery**
> > >
> > > Discover available APIs and methods through IntelliSense
> > >
> > > **4. Professional Experience**
> > >
> > > Use IDE-quality editing features directly in FlowX Designer
> >
> > Developer Tools
>
> ***
>
> ### **Functions testing**
>
> > [card] Functions testing
> >
> > > [tab] Overview
> > >
> > > Test Reusable Functions more efficiently by saving test parameters directly from the testing modal. This enables faster iteration and better test coverage.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Save Test Parameters
> > > >
> > > > Save test inputs directly from the testing modal and reuse them in future test runs
> > >
> > > > [card] Test History
> > > >
> > > > Access previously saved test parameters for regression testing
> > >
> > > > [card] Faster Iteration
> > > >
> > > > Re-test functions quickly with saved parameter sets
> > >
> > > > [card] Test Coverage
> > > >
> > > > Build a library of test cases for comprehensive function validation
> >
> > > [tab] Benefits
> > >
> > > **1. Quality**
> > >
> > > Test functions more thoroughly to improve quality
> > >
> > > **2. Time Savings**
> > >
> > > Avoid re-entering test data for each test iteration
> > >
> > > **3. Documentation**
> > >
> > > Use saved test cases as examples of how to use the function
> >
> > Testing Enhancement

> [tab] Additional Improvements
>
> Platform improvements, security updates, and bug fixes.
>
> 🌍 [**Task Management Localization**](#task-management-localization) - Comprehensive localization support with automatic table grid localization and 51 substitution tags\
> 🔧 [**Platform Enhancements**](#platform-enhancements) - Infrastructure upgrades and security improvements\
> 🐛 [**Bug Fixes**](#bug-fixes) - Resolved issues and stability improvements
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds comprehensive localization support for Task Management, enabling you to customize all user-facing text elements including table columns, filters, and actions. This allows you to deliver Task Management experiences in multiple languages:
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> >
> > > [tab] Key Features
> > >
> > > > [card] Table Grid Localization (Automatic)
> > > >
> > > > Data table components (filters, menus, pagination, data types) are automatically localized based on container app language
> > >
> > > > [card] Substitution Tags (Manual)
> > > >
> > > > Configure 51 system substitution tags in CMS to localize table columns, task actions, and UI elements
> > >
> > > > [card] Multi-language Support
> > > >
> > > > Support for 34 languages including Arabic, Chinese, Japanese, Korean, and European languages
> > >
> > > > [card] Task Action Localization
> > > >
> > > > Localize all task actions, statuses, and workflow-related text elements
> >
> > > [tab] Localization components
> > >
> > > > [accordion] Table Grid Locale Keys
> > > >
> > > > FlowX Task Management uses a comprehensive table grid localization system. These keys are **automatically applied** by FlowX.AI based on your container app language and cover all table functionality:
> > > >
> > > > * **Filters**: Set filters, text filters, number filters, date filters with all operators (equals, contains, starts with, etc.)
> > > >
> > > > * **Menus**: Column menus, context menus, aggregation functions, sorting options
> > > >
> > > > * **Pagination**: Page navigation, page size selectors, row counts
> > > >
> > > > * **Data Types**: Boolean values, dates, numbers with proper formatting
> > > >
> > > > * **Advanced Features**: Pivot mode, charting, column grouping, and row operations
> > > >
> > > > * **ARIA Labels**: Accessibility labels for screen readers and assistive technologies
> > > >
> > > > > [!NOTE]
> > > > >
> > > > > **Automatic Localization**: Table grid locale keys are automatically translated by FlowX.AI based on your container app language. No manual configuration or setup required.
> > >
> > > > [accordion] FlowX substitution tags (51 keys)
> > > >
> > > > Use these substitution tags in CMS to localize custom Task Management interface elements. All tags include English default values:
> > > >
> > > > **Search & Navigation**
> > > >
> > > > * `sys_tm_search` - "Search"
> > > >
> > > > **Table Columns**
> > > >
> > > > * `sys_tm_title` - "Title"
> > > > * `sys_tm_stage` - "Stage"
> > > > * `sys_tm_assignee` - "Assignee"
> > > > * `sys_tm_status` - "Status"
> > > > * `sys_tm_priority` - "Priority"
> > > > * `sys_tm_last_updated` - "Last updated"
> > > >
> > > > **Process States (Status Values)**
> > > >
> > > > * `sys_tm_created` - "Created"
> > > > * `sys_tm_started` - "Started"
> > > > * `sys_tm_finished` - "Finished"
> > > > * `sys_tm_finished_with_error` - "Finished with error"
> > > > * `sys_tm_failed` - "Failed"
> > > > * `sys_tm_expired` - "Expired"
> > > > * `sys_tm_aborted` - "Aborted"
> > > > * `sys_tm_terminated` - "Terminated"
> > > > * `sys_tm_dismissed` - "Dismissed"
> > > > * `sys_tm_on_hold` - "On hold"
> > > >
> > > > **Bulk Actions**
> > > >
> > > > * `sys_tm_assign_to` - "Assign to…"
> > > > * `sys_tm_unassign_all` - "Unassign All"
> > > > * `sys_tm_assign_all_to_me` - "Assign All to me"
> > > > * `sys_tm_hold_all` - "Hold All"
> > > > * `sys_tm_unhold_all` - "Unhold All"
> > > >
> > > > **Task Actions**
> > > >
> > > > * `sys_tm_view_application` - "View Application"
> > > > * `sys_tm_unassign` - "Unassign"
> > > > * `sys_tm_assign_to_myself` - "Assign to myself"
> > > > * `sys_tm_unhold` - "Unhold"
> > > > * `sys_tm_hold` - "Hold"
> > > > * `sys_tm_assign` - "Assign"
> > > > * `sys_tm_execute` - "Execute"
> > > > * `sys_tm_start` - "Start"
> > > >
> > > > **Task Details Sections**
> > > >
> > > > * `sys_tm_assignee_deactivated` - "(Deactivated)"
> > > > * `sys_tm_comments` - "Comments"
> > > > * `sys_tm_write_a_comment` - "Write a comment…"
> > > > * `sys_tm_history` - "History"
> > > >
> > > > **History Events**
> > > >
> > > > * `sys_tm_task_created` - "Task created"
> > > > * `sys_tm_user_created_this_task` - "`${user}` created this task"
> > > > * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
> > > > * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
> > > > * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
> > > > * `sys_tm_task_moved_to` - "Task moved to"
> > > > * `sys_tm_task_status_changed_to` - "Task status changed to"
> > > > * `sys_tm_task_assigned_to` - "Task assigned to"
> > > > * `sys_tm_task_owner_removed` - "Task owner removed"
> > > >
> > > > **User Selection & Search**
> > > >
> > > > * `sys_tm_select_person` - "Select person..."
> > > > * `sys_tm_search_person` - "Search users"
> > > > * `sys_tm_search_term_validation` - "Type at least 4 characters..."
> > > >
> > > > **UI States**
> > > >
> > > > * `sys_tm_loading` - "Loading..."
> > > > * `sys_tm_nothing_found` - "Nothing Found"
> > > >
> > > > **Data Display**
> > > >
> > > > * `sys_tm_in` - "In" (custom filter operator)
> > > >
> > > > * `sys_tm_yes` - "Yes" (boolean value)
> > > >
> > > > * `sys_tm_no` - "No" (boolean value)
> > > >
> > > > > [!WARNING]
> > > > >
> > > > > **\*\*Manual Configuration Required**: These 51 FlowX substitution tags must be configured manually in CMS for each language. They control custom Task Management UI elements outside of the data table.
> >
> > > [tab] Implementation
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization (300+ keys for filters, menus, pagination, data types) based on this setting
> > >
> > > **2. Configure FlowX Substitution Tags in CMS**
> > >
> > > Add translations for all 51 FlowX substitution tags (sys\_tm\_\*) in CMS for each supported language. These control custom Task Management UI elements (task actions, bulk operations, history events, comments)
> > >
> > > **3. Configure Custom Column Names (Optional)**
> > >
> > > If you need custom columns beyond the defaults, use substitution tags for column display names in your Task Management configuration
> > >
> > > **4. Test Localization**
> > >
> > > Verify complete localization:
> > >
> > > * **Table grid elements** (automatic): filters, sorting, pagination, menus should display in container app language
> > >
> > > * **FlowX custom elements** (CMS): task actions, bulk operations, history events, comments should use your CMS translations
> > >
> > > > [!NOTE]
> > > >
> > > > **Simple Setup**: Configure only the 51 FlowX substitution tags in CMS. Table grid localization (300+ keys) is handled automatically by the platform.
> >
> > > [tab] Benefits
> > >
> > > > [card] Global Reach
> > > >
> > > > Deploy Task Management to users worldwide with native language support
> > >
> > > > [card] Consistent Experience
> > > >
> > > > Provide a fully localized experience across all Task Management components
> > >
> > > > [card] Easy Maintenance
> > > >
> > > > Manage translations centrally through CMS substitution tags
> > >
> > > > [card] Professional Quality
> > > >
> > > > Leverage professional translations for data grid components with automatic localization
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> > [card] [Task Management Overview](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
> >
> > Learn about Task Management features and configuration
>
> > [card] [Process Settings](../../../5.1/docs/building-blocks/process/process-definition#integrate-with-task-manager)
> >
> > Configure Task Management integration in process settings
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform Enhancements
> >
> > FlowX.AI 5.2.0 includes platform improvements focused on security, stability, and infrastructure.
> >
> > ## Security & Infrastructure Updates
> >
> > > [card] Vulnerability Fixes
> > >
> > > Update Java libraries and base images to address security vulnerabilities
> >
> > > [card] SpiceDB Upgrade
> > >
> > > Upgrade SpiceDB with new operator version
> >
> > > [card] Dependency Updates
> > >
> > > Update platform dependencies to latest secure versions
> >
> > ## Additional improvements
> >
> > > [card] Permission-based UI
> > >
> > > Add permission-based UI functionality in Reusable UI Templates
> >
> > > [card] Database Query Improvements
> > >
> > > Improve FlowX Database query handling and error messages
> >
> > > [card] System Substitution Tags
> > >
> > > Use system substitution tags in task management texts in CMS
> >
> > > [card] SSE Disconnect Handling
> > >
> > > Handle Server-Sent Events disconnections better to reduce log noise
> >
> > > [card] [Integration Designer Environment Variables](./update-environment-variables-5.2)
> > >
> > > Update environment variables for improved advancing controller with separate picking and processing operations, see details [here](./update-environment-variables-5.2)
> >
> > Platform Updates
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes & stability improvements
> >
> > FlowX.AI 5.2.0 includes bug fixes and stability improvements to improve the overall user experience.
> >
> > ## Notable fixes
> >
> > > [accordion] Fixes
> > >
> > > * **Process Instances Page**: Fix error when opening Runtime process instances page
> > > * **Resource Import**: Fix import requests that use incorrect content type
> > > * **Elasticsearch Updates**: Fix engine errors when updating documents in older indexes
> > > * **Navigation Tree**: Fix navigation tree response for overridden processes
> > > * **Dependency Management**: Fix errors when updating library dependency versions
> >
> > > [accordion] UI/UX fixes
> > >
> > > * **Accessibility**: Fix missing accessibility sections on various components
> > > * **Theme Configuration**: Fix element selection issues in segmented button panel
> > > * **Modal Behavior**: Improve modal focus management and keyboard navigation
> > > * **Select Components**: Fix highlighting and navigation issues in select/multiselect
> > > * **Task Manager**: Fix browser freeze when opening table configuration
> >
> > > [accordion] Renderer fixes
> > >
> > > * **Angular SDK**: Fix keyboard navigation issues with select components and shift+tab behavior
> > > * **React SDK**: Fix option highlighting and keyboard navigation in various components
> > > * **Workflow Display**: Fix rendering issues in Integration Designer workflows
> > > * **Collection Components**: Fix card expansion issues with accordions in navigation areas
> >
> > > [accordion] Backend fixes
> > >
> > > * **Events Gateway**: Improve SSE disconnect handling to reduce error log flooding
> > > * **Database Operations**: Improve error handling and validation for FlowX Database queries
> > > * **Process Navigation**: Fix back button redirects from process definitions
> > > * **Warning Management**: Clean up warnings properly when deleting parent actions

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.2.0](./deployment-guidelines-v5.2).
>
> ### Environment variables updates
>
> > [!NOTE]
> >
> > For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
>
> ### Coming soon
>
> Additional features currently in development for future releases:
>
> * Extended accessibility support for iOS and Android platforms
> * Additional Python IDE capabilities
> * Enhanced FlowX Database query preview and optimization tools


# Deployment guidelines v5.3.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/deployment-guidelines-v5.3

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.29.0** | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 |
| **admin** | **10.26.1** | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 |
| **designer** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **cms-core** | **10.16.0** | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 |
| **scheduler-core** | **10.11.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **events-gateway** | **10.12.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **notification-plugin** | **10.17.0** | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **document-plugin** | **10.16.0** | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 |
| **task-management-plugin** | **10.18.0** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 |
| **data-search** | **10.10.1** | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 |
| **audit-core** | **10.15.1** | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **advancing-controller** | **10.11.0** | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 |
| **integration-designer** | **10.24.0** | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 |
| **application-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **runtime-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **data-sync** | **10.14.1** | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 |
| **authorization-system** | **10.18.1** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - |
| **nosql-db-runner** | **10.10.1** | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **iOS renderer** | **10.1.0** | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 |
| **Android renderer** | **10.1.0** | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 |

### Plugins

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.1** | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 |
| **di-platform** | **10.2.5** | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 |
| **ai-platform-ai-developer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-connected-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agents** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-conversations** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-models** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-tenants** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-planner** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-analyst** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-designer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agent-builder** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-binaries** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.3.0 | Keycloak | 26+ |
| 5.3.0 | Kafka | 3.8 - 3.9 |
| 5.3.0 | PostgreSQL | 16 - 17 |
| 5.3.0 | Oracle Database | 21c, 23ai |
| 5.3.0 | MongoDB | 7 - 8 |
| 5.3.0 | Redis | 7.4 - 8.0 |
| 5.3.0 | Elasticsearch | 8 |
| 5.3.0 | Angular (Web SDK) | 19.2 |
| 5.3.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.3.0

### Key features and updates

> [card] UI Flows
>
> Build multi-platform applications with reusable UI components across web, iOS, and Android

> [card] UI Events
>
> Real-time user interaction handling with event-driven UI components

> [card] Workflow Data Models
>
> Workflow-level data models with input/output parameters and process-to-workflow data mapping

> [card] Mobile Accessibility
>
> WCAG 2.1 accessibility compliance extended to iOS and Android platforms

> [card] Custom Component Enhancements
>
> Standardized custom component integration across all platforms

> [card] SaaS Capabilities
>
> Multi-tenant SaaS capabilities with organization management

## Upgrading from v5.2.0

### Breaking changes

> [!WARNING]
>
> **FlowX Engine Configuration Changes**: The partitioning and archiving configuration structure has been reorganized. If you have enabled data partitioning, you **must** update your configuration files before or immediately after upgrading.

> [card] [Complete migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
>
> See the detailed migration guide with step-by-step instructions, configuration examples, and troubleshooting

### Key changes

* **UI Flows**: New feature for building multi-platform reusable UI components
* **Workflow Data Models**: Enhanced integration between processes and workflows with structured data models
* **Mobile Accessibility**: iOS and Android renderers now support WCAG 2.1 accessibility standards
* **Configuration Structure**: Breaking change in FlowX Engine partitioning/archiving configuration (see preceding section)

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.

### Compatibility

* **Breaking Changes**: FlowX Engine partitioning/archiving configuration structure has changed (action required if using partitioning)
* **Feature Additions**: UI Flows, UI Events, and Workflow Data Models are new features with no breaking changes
* **Renderer Updates**: Web and mobile SDKs include new features with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/migration-overview

Migration guide for upgrading from FlowX.AI v5.2.0 to v5.3.0

> [!NOTE]
>
> FlowX.AI v5.3.0 is an incremental update from v5.2.0 with one breaking change related to FlowX Engine configuration structure.

## What's changing

FlowX.AI v5.3.0 introduces a breaking change to the FlowX Engine partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings have been reorganized under `partitioning.archiving`.

## Who is affected

> [!WARNING]
>
> This breaking change **only affects** deployments that have:
>
> * Enabled data partitioning in FlowX Engine (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings (`SCHEDULER_DATAPARTITIONING_ENABLED=true`)
>
> If you have not enabled these features, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

## Migration process

**1. Review configuration changes**

Understand the new configuration structure and identify which settings need to be updated in your deployment

**2. Update configuration files**

Update your FlowX Engine configuration files (YAML or environment variables) following the migration steps

**3. Deploy and verify**

Deploy the updated configuration and verify that partitioning and archiving continue to work correctly

## Key changes summary

### Configuration structure

**What's removed:**

* `scheduler.dataPartitioning` section with `enabled` and `cronExpression` settings

**What's added:**

* `partitioning.archiving` subsection containing all archiving-related settings

**What's moved:**

* `retention-intervals` moved from `partitioning` to `partitioning.archiving`
* `detached-partition-compression` moved to `partitioning.archiving`
* `moved-data-batch-size` moved to `partitioning.archiving`
* `cronExpression` moved from `scheduler.dataPartitioning` to `partitioning.archiving`

### Environment variables

5 environment variables have been renamed to reflect the new structure:

| Old Variable | New Variable |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` |

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility**: The old configuration structure is not supported in v5.3.0 and causes FlowX Engine startup errors.
>
> You must update your configuration before or immediately after upgrading to v5.3.0.

## Rollback support

If you need to rollback from v5.3.0 to v5.2.x:

1. Revert your configuration files to the previous structure
2. Restore environment variables to their previous names
3. Downgrade the FlowX Engine container/pod to the previous version

> [!NOTE]
>
> Database schema changes are forward-compatible. Ensure you have database backups before any upgrade.

> [!NOTE]
>
> This is a configuration-only change. No code changes, data migration, or schema updates are required.

## Next steps

## Additional resources

> [card] [Partitioning & Archiving Setup](/5.1/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving)
>
> Complete guide to FlowX Engine partitioning and archiving

> [card] [Deployment Guidelines v5.3.0](../deployment-guidelines-v5.3)
>
> Component versions and deployment instructions

> [card] [Release Notes v5.3.0](../v5.3.0-december-2025)
>
> Full release notes for v5.3.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/update-environment-variables-5.3

Update environment variables for all existing FlowX.AI services

## FlowX Engine

### Partitioning and archiving configuration restructure

> [!NOTE]
>
> FlowX.AI v5.3.0 reorganizes the partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings are now under `partitioning.archiving`.

#### Variables to remove

If you are using environment variables to override FlowX Engine configuration, remove these variables:

| Remove This Variable | Reason |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |

#### Variables to replace

| Old Variable Name | New Variable Name | Default Value | Description |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of partition intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression level for archived partitions (Oracle only): `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for moving data during archiving (PostgreSQL only) |

#### New variables structure

The archiving configuration is now nested under `partitioning.archiving`:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Turn on or off data partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Partition interval: `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Turn on or off automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Schedule expression for archiving operations (default: daily at 1:00 AM) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression for archived partitions (Oracle only) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for data movement (PostgreSQL only) |

> [!NOTE]
>
> **Configuration structure changes:**
>
> * **Removed**: `scheduler.dataPartitioning` section
> * **Added**: `partitioning.archiving` subsection with all archiving-related settings
> * **Unchanged**: Core partitioning settings (`enabled`, `interval`) remain at `partitioning` level
> * **Moved**: Archiving-specific settings (`retention-intervals`, `cronExpression`, `detached-partition-compression`, `moved-data-batch-size`) are now under `partitioning.archiving`

> [!WARNING]
>
> **Action required if using partitioning:**
>
> If you have enabled data partitioning in FlowX Engine, you **must** update your configuration:
>
> 1. **YAML configuration**: Update your `application.yml` to follow the new structure (see [Deployment Guidelines](../deployment-guidelines-v5.3#breaking-changes))
> 2. **Environment variables**: Update variable names as shown in the tables above
> 3. **Deployment order**: Update configuration before or immediately after upgrading to v5.3.0

#### Configuration examples

> [tab] Environment Variables (Before)
>
> ```bash theme={"dark"}
> # Old structure (v5.2 and earlier)
> SCHEDULER_DATAPARTITIONING_ENABLED=true
> SCHEDULER_DATAPARTITIONING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS=3
> FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [tab] Environment Variables (After)
>
> ```bash theme={"dark"}
> # New structure (v5.3.0)
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true
> FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS=3
> FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [!NOTE]
>
> **Impact assessment:**
>
> This change only affects deployments that have:
>
> * Enabled data partitioning (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings
>
> If partitioning is disabled, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

### New optional variables

| Variable | Default Value | Description |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Falls back to `KAFKA_TOPIC_PATTERN` if not set | Dedicated topic pattern for FlowX connectors, separate from other platform components like document-plugin, data-search, and cms-core |

> [!NOTE]
>
> The `KAFKA_TOPIC_CONNECTOR_PATTERN` variable allows you to configure a custom Kafka topic pattern specifically for FlowX connectors without affecting other platform components.

> [card] [Complete migration guide](migration-overview)
>
> See the Deployment Guidelines for complete configuration examples, step-by-step migration instructions, and troubleshooting guidance.


# FlowX.AI 5.3.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025

UI Flows for multi-platform app building, UI Events for real-time interactions, enhanced custom component integration, and mobile accessibility improvements.

**What's new?**

> [tab] App builder & reusability
>
> Build multi-platform applications faster with UI Flows, enhance real-time interactions with UI Events, and integrate custom components across all platforms.
>
> 📱 [**UI Flows**](#ui-flows) - Build multi-platform applications with reusable UI components across web, iOS, and Android\
> ⚡  [**UI Events**](#ui-events) - Real-time user interaction handling with event-driven UI components\
> 🧩 [**Custom Component Enhancements**](#custom-component-enhancements) - Enhanced integration for custom components with standardized data mapping\
> 📤 [**File Upload Improvements**](#file-upload-improvements) - Enhanced file upload experience with better loading states and user feedback\
> ♿ [**Mobile Accessibility**](#mobile-accessibility) - WCAG 2.1 accessibility compliance for iOS and Android platforms\
> 🏢 [**Cross Workspace Projects**](#cross-workspace-projects) - Share projects across multiple workspaces for flexible environment testing\
> 🎯 [**Collection & Table Actions**](#collection-and-table-actions) - Execute actions from collections and tables in UI Flows
>
> ### **UI flows**
>
> > [card] UI flows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Flows, a powerful new capability that enables you to build reusable, multi-platform user interfaces that work across web (Angular/React), iOS, and Android applications. UI Flows separate UI definitions from process logic, enabling better reusability and faster application development without the overhead of full BPMN processes.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flows revolutionize how you build applications by allowing you to create a UI once and deploy it across all platforms, dramatically reducing development time and ensuring consistent user experiences.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Unnecessary process complexity
> > > >
> > > > Some use cases do not need a mapping of the business case in BPMN and the complexity and overhead that a FlowX process entails
> > >
> > > > [card] Subprocess overhead
> > > >
> > > > Unnecessary subprocess layers inside processes added complexity for simple UI scenarios
> > >
> > > > [card] Tight UI-process coupling
> > > >
> > > > UI definitions were tightly coupled to process logic, reducing reusability and increasing maintenance
> > >
> > > > [card] Platform-specific development
> > > >
> > > > Building the same UI for multiple platforms required separate implementations for each platform
> >
> > > [tab] Key Features
> > >
> > > > [card] UI Flows as project resources
> > > >
> > > > UI Flows are managed as independent project resources, separate from process definitions
> > >
> > > > [card] Navigation areas management
> > > >
> > > > Manage Navigation Areas inside UI Flows Designer for structured navigation and layout
> > >
> > > > [card] Start process UI action
> > > >
> > > > Launch FlowX processes directly from UI Flows, bridging UI and process execution
> > >
> > > > [card] Navigate to UI action
> > > >
> > > > Setup navigation to Nav areas or Container elements through scroll for seamless UX
> > >
> > > > [card] Task Manager component
> > > >
> > > > Embed Task Manager as a UI Component in UI Flows for task management capabilities
> > >
> > > > [card] Multi-platform support
> > > >
> > > > Create UI once and deploy to web (Angular/React), iOS, and Android with platform-specific configurations
> > >
> > > > [card] Import/export
> > > >
> > > > Export UI Flows as portable packages and import them across environments and applications
> > >
> > > > [card] Platform selection
> > > >
> > > > Configure platform-specific behaviors and overrides for web, iOS, and Android in the UI Flows designer
> > >
> > > > [card] Home page support
> > > >
> > > > Create UI Flows with dedicated home pages and home navigation icons for better UX
> >
> > > [tab] How It Works
> > >
> > > **1. Create UI flow**
> > >
> > > Create a UI Flow as a project resource in FlowX Designer, separate from process definitions
> > >
> > > **2. Design navigation**
> > >
> > > Manage Navigation Areas inside UI Flows Designer, defining pages and navigation structure
> > >
> > > **3. Add components**
> > >
> > > Add UI components including Task Manager, forms, custom components, and other UI elements
> > >
> > > **4. Configure actions**
> > >
> > > Setup UI Actions like Start Process (to launch processes) and Navigate To (for Nav areas or container scrolling)
> > >
> > > **5. Configure platforms**
> > >
> > > Set platform-specific configurations using the platform selection subheader (Web, iOS, Android)
> > >
> > > **6. Set home page**
> > >
> > > Designate a page as the home page with automatic home icon navigation support
> > >
> > > **7. Export & reuse**
> > >
> > > Export your UI Flow and import it into other applications or environments for maximum reusability
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced complexity
> > > >
> > > > Build UIs without the overhead of BPMN processes for use cases that don't require business process mapping
> > >
> > > > [card] Faster development
> > > >
> > > > Build UI once instead of creating separate interfaces for each platform
> > >
> > > > [card] Flexible architecture
> > > >
> > > > Eliminate unnecessary subprocess layers - use UI Flows for simple scenarios and processes for complex business logic
> > >
> > > > [card] Consistent UX
> > > >
> > > > Ensure identical user experiences across web, iOS, and Android applications
> > >
> > > > [card] Reusability
> > > >
> > > > Share UI Flows across multiple applications and projects
> > >
> > > > [card] Process integration
> > > >
> > > > Launch processes from UI Flows when needed, maintaining clean separation of concerns
> > >
> > > > [card] Maintainability
> > > >
> > > > Update UI in one place and propagate changes across all platforms
> > >
> > > > [card] Enhanced navigation
> > > >
> > > > Rich navigation capabilities with Nav areas, container scrolling, and Task Manager integration
> >
> > > [tab] Use Cases
> > >
> > > **When to Use UI Flows vs Processes:**
> > >
> > > **Use UI Flows for:**
> > >
> > > * **Information Display**: Dashboards, reports, and static content that doesn't require process orchestration
> > > * **Task Management**: Task lists and task management interfaces with embedded Task Manager component
> > > * **Navigation Shells**: Application navigation structures and home pages
> > > * **Form Collections**: Data entry forms that start processes but don't need their own process context
> > > * **Multi-Platform Apps**: Applications that need consistent UI across web and mobile platforms
> > >
> > > **Use Processes for:**
> > >
> > > * **Business Logic**: Complex workflows with business rules, approvals, and integrations
> > > * **State Management**: Applications requiring process state tracking and persistence
> > > * **Orchestration**: Multi-step operations with decision points and parallel execution
> > >
> > > **Combine Both:**
> > >
> > > Create UI Flows as the main application shell and use Start Process UI Actions to launch business processes when needed, keeping your architecture clean and maintainable.
> >
> > > [card] [UI Flows Documentation](/5.9/docs/building-blocks/ui-flows)
> > >
> > > Complete guide to creating and configuring UI Flows, including navigation management, UI actions, and platform considerations.
> >
> > Major Feature
>
> ***
>
> ### **UI events**
>
> > [card] UI events
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Events, enabling real-time interaction handling directly within Reusable UI Templates. UI Events allow you to capture user interactions like button clicks, form changes, or custom events and respond immediately without process execution, providing responsive and dynamic user experiences.
> >
> > > [tab] Key Features
> > >
> > > > [card] Event configuration
> > > >
> > > > Configure UI Events in UI Designer with custom event types and handling logic
> > >
> > > > [card] Cross-platform support
> > > >
> > > > UI Events work consistently across Angular, React, iOS, and Android renderers
> > >
> > > > [card] Runtime mapping
> > > >
> > > > UI Event results are mapped automatically in Reusable UI Template instances at runtime
> > >
> > > > [card] Design-time testing
> > > >
> > > > Test UI Events directly in UI Designer before deploying to runtime
> >
> > > [tab] Use Cases
> > >
> > > > [card] Form validation
> > > >
> > > > Validate form inputs in real-time as users type, providing immediate feedback
> > >
> > > > [card] Dynamic UI updates
> > > >
> > > > Show/hide fields, update options, or change UI state based on user interactions
> > >
> > > > [card] Client-side logic
> > > >
> > > > Execute lightweight client-side logic without triggering backend processes
> > >
> > > > [card] Responsive interactions
> > > >
> > > > Create highly responsive UI behaviors like autocomplete, live search, or conditional displays
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Handle UI interactions instantly without waiting for backend process execution
> > >
> > > **2. User experience**
> > >
> > > Provide immediate visual feedback and responsive interactions
> > >
> > > **3. Reduced complexity**
> > >
> > > Simplify process logic by handling UI-specific interactions at the component level
> >
> > UX Enhancement
>
> ***
>
> ### **Custom component enhancements**
>
> > [card] Custom component enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 standardizes custom component integration across all platforms (Angular, React, iOS, Android) with unified data mapping for input keys, data binding, save operations, and action handling. This provides a consistent developer experience when building custom components.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified data mapping
> > > >
> > > > Standard data, saveData, and action body mapping across all platforms
> > >
> > > > [card] Input key mapping
> > > >
> > > > Consistent input key handling for passing configuration and data to custom components
> > >
> > > > [card] Platform parity
> > > >
> > > > Identical custom component APIs across Angular, React, iOS, and Android
> > >
> > > > [card] Action integration
> > > >
> > > > Integration with FlowX actions for triggering backend operations
> >
> > > [tab] Benefits
> > >
> > > **1. Developer productivity**
> > >
> > > Build custom components once with knowledge that applies across all platforms
> > >
> > > **2. Code reusability**
> > >
> > > Share component logic and patterns across web and mobile implementations
> > >
> > > **3. Consistency**
> > >
> > > Ensure consistent behavior and data handling across all platforms
> >
> > Developer Experience
>
> ***
>
> ### **File upload improvements**
>
> > [card] File upload improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the file upload experience across all platforms with improved loading states, better user feedback, and more flexible configuration options. These improvements provide clearer status communication during file upload operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Enhanced loading behavior
> > > >
> > > > Configure loading behavior with optional overlay loader and custom loading messages
> > >
> > > > [card] Toast notifications
> > > >
> > > > Success and error messages displayed as toasts with customizable messages
> > >
> > > > [card] Dynamic messages
> > > >
> > > > Display dynamic key values in toast and loading messages for context-aware feedback
> > >
> > > > [card] Generic loader design
> > > >
> > > > Updated loader designs across Angular, React, iOS, and Android for consistent theming
> >
> > > [tab] Configuration
> > >
> > > **Loading Behavior Options:**
> > >
> > > * **NONE**: No loading overlay displayed during upload
> > > * **OVERLAY**: Full-screen overlay with spinner and optional loading message
> > >
> > > **Toast Notifications:**
> > >
> > > * **Success Toast**: Toggle to show success message when upload completes (auto-dismiss after 3-5 seconds)
> > > * **Error Toast**: Toggle to show error message when upload fails (auto-dismiss after 3-5 seconds)
> > > * **Custom Messages**: Configure success and error messages with dynamic substitutions
> > >
> > > **Theming Support:**
> > >
> > > * Apply custom themes to loaders and toast messages
> > > * Configure colors, sizes, and styling to match your brand
> > > * Consistent visual language across platforms
> >
> > UX Enhancement
>
> ***
>
> ### **Mobile accessibility**
>
> > [card] Mobile accessibility
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 extends WCAG 2.1 accessibility compliance to iOS and Android platforms, allowing you to configure accessibility properties directly from UI Designer and ensuring your mobile applications are accessible to all users.
> >
> > > [tab] Key Features
> > >
> > > > [card] iOS accessibility
> > > >
> > > > Configure labels, hints, traits, and accessibility properties for iOS components
> > >
> > > > [card] Android accessibility
> > > >
> > > > Set content descriptions and accessibility properties for Android components
> > >
> > > > [card] Designer integration
> > > >
> > > > Configure all accessibility properties from UI Designer without code changes
> > >
> > > > [card] Platform-specific options
> > > >
> > > > Set platform-specific accessibility configurations for optimal native experience
> >
> > > [tab] Benefits
> > >
> > > > [card] Inclusive mobile apps
> > > >
> > > > Make your mobile applications accessible to users with disabilities
> > >
> > > > [card] Regulatory compliance
> > > >
> > > > Meet mobile accessibility requirements for government, healthcare, and financial sectors
> > >
> > > > [card] Better UX
> > > >
> > > > Accessibility improvements benefit all users, not just those using assistive technologies
> > >
> > > > [card] Unified configuration
> > > >
> > > > Configure accessibility for all platforms from a single Designer interface
> >
> > Accessibility
>
> ***
>
> ### **Cross workspace projects**
>
> > [card] Cross workspace projects
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 removes the restriction that prevented importing the same project into multiple workspaces within the same environment. This enables organizations to use workspaces to represent different upper environments (UAT, Staging) for testing and development.
> > >
> > > > [!NOTE]
> > > >
> > > > A single project (identified by its UUID) can now exist independently across workspaces, each with its own lifecycle: separate active policies, configurations, and access controls.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Environment testing restrictions
> > > >
> > > > Organizations could not use workspaces on the same FlowX deployment to represent different upper environments for testing (e.g. UAT, Staging)
> > >
> > > > [card] Operational costs
> > > >
> > > > This feature is intended to allow organizations to use workspace functionality to emulate different environments and reduce operational costs.
> >
> > > [tab] Solution
> > >
> > > **What Changed:**
> > >
> > > **1. Restriction removed**
> > >
> > > The system now allows importing the same project (identified by UUID) into multiple workspaces within the same environment
> > >
> > > **2. Independent lifecycles**
> > >
> > > Each project instance in different workspaces maintains its own independent lifecycle with separate active policies, configurations, and access controls
> > >
> > > **3. Workspace isolation**
> > >
> > > Changes in one workspace do not affect the same project in other workspaces, ensuring proper isolation
> >
> > > [tab] How It Works
> > >
> > > **Import Behavior:**
> > >
> > > | Aspect | Behavior |
> > > | - | - |
> > > | **Import** | Import a project build (and optionally a version) into a different workspace on the same environment |
> > > | **Active Policy** | The imported build is automatically set as the active policy, regardless of what was active in the original workspace |
> > > | **User Access** | Workspace users must be granted appropriate project rights (e.g., project viewer) to interact with the imported project |
> > > | **Process Instances** | Workspace-specific; imported projects start with no instances until processes run in the new workspace |
> > > | **Database** | Projects across workspaces on the same environment share the same database |
> > > | **No Impact on Original** | Import does not affect the original project's settings, policies, information, or process instances |
> > >
> > > > [!WARNING]
> > > >
> > > > Only the build itself is transferred during cross-workspace import. Configuration and access controls are defined separately in each workspace.
> >
> > > [tab] Benefits
> > >
> > > > [card] Flexible testing environments
> > > >
> > > > Use workspaces to represent UAT, Staging, and other test environments on the same deployment
> > >
> > > > [card] Reduced costs
> > > >
> > > > Eliminate the need for additional deployments and DevOps resources for environment management
> > >
> > > > [card] Better organization
> > > >
> > > > Organize projects and environments more efficiently with workspace-based separation
> > >
> > > > [card] Independent control
> > > >
> > > > Maintain separate policies and configurations for each workspace while using the same project
> > >
> > > > [card] Simplified operations
> > > >
> > > > Streamline deployment and environment management workflows
> > >
> > > > [card] Faster environment setup
> > > >
> > > > Quickly create new test environments by importing existing projects into new workspaces
> >
> > > [tab] Use Cases
> > >
> > > **Example Scenarios:**
> > >
> > > 1. **Multi-Environment Testing**: Import the same project into UAT and Staging workspaces, each with different test data and configurations
> > >
> > > 2. **Development Lifecycle**: Maintain development, integration, and pre-production environments as separate workspaces with the same project
> > >
> > > 3. **Parallel Testing**: Run multiple test scenarios simultaneously by creating separate workspaces for each testing team
> > >
> > > 4. **Isolated Training Environments**: Create dedicated workspaces for training and demos while keeping production separate
> >
> > > [card] [Workspaces Documentation](/5.1/docs/projects/workspaces#cross-workspace-project-import)
> > >
> > > Complete guide to cross-workspace project import, including import behavior and best practices.
> >
> > Reusability Enhancement
>
> ***
>
> ### **Collection and table actions**
>
> > [card] Collection and table actions
> >
> > FlowX.AI 5.3 enables executing actions directly from collection and table rows within UI Flows across Angular and React platforms, providing contextual user interactions within data-driven UI Flow components.
> >
> > > [card] Row-level actions
> > >
> > > Configure and trigger actions with row context for edit, delete, or start process operations in UI Flows
> >
> > > [card] Cross-platform support
> > >
> > > Works in both Angular and React web renderers for UI Flows
> >
> > UI Flows
>
> ***

> [tab] Integration & data
>
> Enhanced workflow integration, data model management, and backend performance improvements.
>
> 🔄 [**Data mappers for workflow integration**](#data-mappers-for-workflow-integration) - Data mappers for workflow integration\
> 🗄️ [**Workflow data model**](#workflow-data-model) - New CRUD endpoints and runtime data model access\
> 🤖 [**MCP Integration**](#mcp-integration) - Connect AI agents with external tools and services through Model Context Protocol servers\
> 🤖 [**Custom Agent Nodes**](#custom-agent-nodes) - Custom Agent nodes for AI agents to use external tools and services
> 📚 [**Knowledge Base**](#knowledge-base) - Create and manage Knowledge Bases for AI agents with document ingestion and semantic search\
> 🔧 [**Update process variables**](#update-process-variables) - Operations teams can modify process variables on active instances to resolve production issues\
> 🔍 [**Token view improvements**](#token-view-improvements) - Enhanced token hierarchy visibility with horizontal scrolling, frozen columns, and context-aware columns\
> 🛡️ [**Access management enhancements**](#access-management-enhancements) - New operations editor role and granular workspace permissions\
> ⚡ [**Performance & stability**](#performance-and-stability) - Backend optimizations, caching improvements, and infrastructure updates\
> 🔀 [**Exclusive Gateways**](#exclusive-gateways) - Expression testing and validation improvements
>
> ### **Data mappers for workflow integration**
>
> > [card] Data mappers for workflow integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces data mappers that enable integration between processes and Integration Designer workflows. Similar to Process Definitions, you can now define structured data models at the workflow level with input and output parameters, ensuring consistent data lineage across your integration architecture.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
> > >
> > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process-workflow.png)
> > >
> > > Map data bidirectionally between processes and workflows using data mappers
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow Data Models provide the same structured data management capabilities as Process Data Models, enabling declarative data mapping between workflows and processes with full type safety and validation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow data model
> > > >
> > > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > > [card] Input parameter management
> > > >
> > > > Input parameters automatically pre-fill Start Nodes with structured data from the workflow data model
> > >
> > > > [card] Data parameters
> > > >
> > > > Use data parameters to define input and output data subsets for workflow operations
> > >
> > > > [card] Process ↔ workflow mapping
> > > >
> > > > Create data mappers on nodes to receive outputs from workflows and map data bidirectionally
> > >
> > > > [card] Generic CRUD endpoints
> > > >
> > > > Manage data models, entities, attributes, and data parameters programmatically via REST APIs
> > >
> > > > [card] Unique node validation
> > > >
> > > > Automatic node name uniqueness validation within workflow definitions to ensure clear data lineage
> >
> > > [tab] How It Works
> > >
> > > **1. Define workflow data model**
> > >
> > > Create a data model for your workflow with entities and attributes, similar to Process Data Models. Define which parameters are inputs and outputs
> > >
> > > **2. Configure input parameters**
> > >
> > > Input parameters automatically pre-fill the Start Node when you open the workflow diagram or test at runtime. No manual JSON editing required
> > >
> > > **3. Map process to workflow**
> > >
> > > When invoking a workflow from a process, create data mappers to map process data to workflow input parameters
> > >
> > > **4. Map workflow to process**
> > >
> > > Configure output mappings on nodes to receive workflow results and map them back to process data
> >
> > > [tab] Data Model Management
> > >
> > > **New API Capabilities:**
> > >
> > > * **Data Model CRUD**: Create, read, update, and delete workflow data models
> > > * **Entity Management**: Add, modify, and remove entities within data models
> > > * **Attribute Management**: Define and manage attributes with types and validation rules
> > > * **Data Parameters Operations**: Create input and output data parameters for workflows
> > > * **Usage Tracking**: Query references and usages for attributes and entities
> > > * **Import/Export**: Export and import complete data models across environments
> > >
> > > **Technical Implementation:**
> > >
> > > * Centralized data model library for common classes and interfaces
> > > * Generic endpoints for data model and data parameters manipulation
> > > * Integration Designer communicates with Admin service for data model operations
> > > * Automatic input body computation based on data model input parameters
> > > * Runtime workflow start data endpoint for testing and execution
> >
> > > [tab] Limitations & Compatibility
> > >
> > > **Current Limitations:**
> > >
> > > * **Start Subworkflow Node**: Works as-is without data model integration in this release
> > > * **Endpoint Schemas**: Imported Swagger schemas are not yet integrated with workflow data models (planned for future release)
> > > * **Database Schemas**: Database operation schemas are not mapped to workflow variables yet (planned for future release)
> > >
> > > **Backwards Compatibility:**
> > >
> > > * Existing workflows continue to work without changes
> > > * End nodes from existing workflows can be renamed manually to align with output parameters
> > > * No breaking changes to current workflow execution
> > >
> > > **Node Naming:**
> > >
> > > * Node names must be unique within a workflow definition
> > > * System automatically validates uniqueness when renaming nodes
> > > * If duplicate names exist, an index is incremented (e.g., "Transform", "Transform\_2")
> >
> > > [tab] Benefits
> > >
> > > > [card] Consistent data lineage
> > > >
> > > > Ensure data consistency across processes and workflows with structured data models
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Input parameters automatically pre-fill Start Nodes - no manual JSON editing
> > >
> > > > [card] Type safety
> > > >
> > > > Define data types and validation rules at the workflow level for runtime safety
> > >
> > > > [card] Reusability
> > > >
> > > > Create reusable workflows with clear input/output contracts that can be invoked from multiple processes
> > >
> > > > [card] Better testing
> > > >
> > > > Test workflows with structured input data based on the data model
> > >
> > > > [card] Clear interfaces
> > > >
> > > > Workflow data models document the expected inputs and outputs for each workflow
> >
> > > [card] [Workflow Data Models Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> > >
> > > Complete guide to creating workflow data models, input/output parameters, process integration, and API reference.
> >
> > Integration Designer
>
> ***
>
> ### **Workflow data model**
>
> > [card] Workflow data model
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 adds comprehensive workflow data model management capabilities with new CRUD endpoints and runtime access to data model paths. This enables dynamic data model operations and better runtime introspection.
> >
> > > [tab] Key Features
> > >
> > > > [card] CRUD endpoints
> > > >
> > > > Create, read, update, and delete workflow data models programmatically via REST APIs
> > >
> > > > [card] Data model paths
> > > >
> > > > Runtime endpoint for retrieving workflow data model paths and structure information
> > >
> > > > [card] RUT instance mappings
> > > >
> > > > Enhanced /status and /details endpoints with mappings per workflow instance
> > >
> > > > [card] Runtime caching
> > > >
> > > > Improved caching for reusable templates to reduce latency and improve performance
> >
> > > [tab] Use Cases
> > >
> > > > [card] Dynamic forms
> > > >
> > > > Build dynamic forms based on data model structure at runtime
> > >
> > > > [card] Data migration
> > > >
> > > > Automate data model synchronization across environments
> > >
> > > > [card] Documentation
> > > >
> > > > Generate data model documentation automatically from API responses
> > >
> > > > [card] Validation
> > > >
> > > > Implement runtime validation based on data model definitions
> >
> > API Enhancement
>
> ***
>
> ### **MCP integration**
>
> > [card] MCP integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Model Context Protocol (MCP) integration, enabling AI agents to connect with external MCP servers and use their tools within Custom Agent nodes. MCP provides a standardized protocol for AI agents to access external tools, databases, APIs, and services.
> > >
> > > > [!NOTE]
> > > >
> > > > MCP integration extends AI agent capabilities by providing access to external tools through a standardized protocol. Configure MCP servers as data sources in Integration Designer and use their tools in workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] MCP data sources
> > > >
> > > > Add MCP servers as data sources in Integration Designer with base URL and authentication configuration
> > >
> > > > [card] Tool management
> > > >
> > > > View, enable, and turn off specific tools exposed by MCP servers directly from Integration Designer
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Select MCP servers in Custom Agent nodes to make their tools available to AI agents during workflow execution
> > >
> > > > [card] Authentication support
> > > >
> > > > Support for no authentication and OAuth 2.0 service account authentication methods
> > >
> > > > [card] Tool discovery
> > > >
> > > > Automatic tool discovery from MCP servers with schema information for inputs and outputs
> > >
> > > > [card] Execution monitoring
> > > >
> > > > Track tool usage and execution details in console logs for debugging and monitoring
> >
> > > [tab] How It Works
> > >
> > > **1. Add MCP server**
> > >
> > > Configure an MCP server as a data source in Integration Designer with base URL and authentication details
> > >
> > > **2. Authenticate connection**
> > >
> > > Set up authentication using no authentication (for development) or OAuth 2.0 service account (for production)
> > >
> > > **3. Discover tools**
> > >
> > > View available tools exposed by the MCP server with their input/output schemas
> > >
> > > **4. Enable tools**
> > >
> > > Enable or turn off specific tools based on your workflow requirements
> > >
> > > **5. Configure custom agent**
> > >
> > > Add a Custom Agent node to your workflow and select which MCP servers the agent can access
> > >
> > > **6. Execute workflow**
> > >
> > > AI agents can now use MCP tools during workflow execution to interact with external systems
> > >
> > > **7. Monitor execution**
> > >
> > > View tool usage and execution details in console logs for debugging and performance tracking
> >
> > > [tab] Authentication
> > >
> > > **Supported Authentication Methods:**
> > >
> > > **None**
> > >
> > > * No authentication required
> > > * Use for public MCP servers or development environments
> > > * Quick setup for testing and prototyping
> > >
> > > **Service Account (OAuth 2.0)**
> > >
> > > * OAuth 2.0 service account authentication
> > > * Required configuration:
> > >   * **Client ID**: OAuth client identifier
> > >   * **Client Secret**: OAuth client secret
> > >   * **Identity Provider URL**: Authorization server endpoint
> > > * Use for production environments
> > > * Secure access to MCP servers
> >
> > > [tab] Use Cases
> > >
> > > > [card] External API integration
> > > >
> > > > Connect AI agents to external APIs and services for data retrieval and action execution
> > >
> > > > [card] Database operations
> > > >
> > > > Query databases and perform data operations through MCP tools within AI workflows
> > >
> > > > [card] Custom business logic
> > > >
> > > > Expose custom business logic as MCP tools for AI agents to execute
> > >
> > > > [card] Multi-system orchestration
> > > >
> > > > Use multiple MCP servers in a single Custom Agent node to orchestrate operations across systems
> >
> > > [tab] Benefits
> > >
> > > > [card] Standardized integration
> > > >
> > > > Use a standardized protocol for AI agent tool integration across different systems
> > >
> > > > [card] Extended capabilities
> > > >
> > > > Extend AI agent capabilities with external tools without custom code
> > >
> > > > [card] Flexible tool management
> > > >
> > > > Enable or turn off specific tools per MCP server based on workflow needs
> > >
> > > > [card] Secure connections
> > > >
> > > > Support for OAuth 2.0 authentication ensures secure access to external services
> > >
> > > > [card] Tool reusability
> > > >
> > > > Configure MCP servers once and use their tools across multiple workflows and Custom Agent nodes
> > >
> > > > [card] Monitoring & debugging
> > > >
> > > > Console logs provide visibility into tool execution for troubleshooting and optimization
> >
> > > [card] [MCP Integration Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> > >
> > > Complete guide to MCP integration including data source configuration, tool management, and Custom Agent node usage.
> >
> > AI Integration
>
> ***
>
> ### **Custom Agent nodes**
>
> > [card] Custom Agent nodes
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Custom Agent nodes, enabling you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
> >
> > > [card] [Custom Agent Node Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > Complete guide to Custom Agent nodes, including configuration, usage, and best practices.
> >
> > AI Integration
>
> ***
>
> ### **Knowledge base**
>
> > [card] Knowledge base
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Knowledge Base integration, enabling you to create and manage centralized repositories of information that AI agents can query when preparing responses. Upload static documents or ingest dynamic data from workflows into Knowledge Bases that use vector embeddings and semantic search for intelligent information retrieval.
> > >
> > > > [!NOTE]
> > > >
> > > > Knowledge Bases enable AI agents to provide contextual, accurate responses based on your organization's documentation, policies, and dynamic data.
> >
> > > [tab] Key Features
> > >
> > > > [card] Document upload
> > > >
> > > > Upload PDF documents directly into Knowledge Bases for AI agent access
> > >
> > > > [card] Workflow ingestion
> > > >
> > > > Ingest data dynamically from workflows using Knowledge Base operations (Append, Replace, Delete)
> > >
> > > > [card] Semantic search
> > > >
> > > > AI agents find relevant information using natural language queries with vector embeddings
> > >
> > > > [card] Content sources
> > > >
> > > > Organize content across multiple sources within a Knowledge Base for better management
> > >
> > > > [card] Relevance scoring
> > > >
> > > > Configure minimum relevance thresholds (0-100%) to control response quality
> > >
> > > > [card] Testing capabilities
> > > >
> > > > Test queries and operations in isolation before adding them to production workflows
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Enable Knowledge Base queries in Custom Agent nodes with configurable parameters
> > >
> > > > [card] Content versioning
> > > >
> > > > Append, replace, or delete content sources with full traceability and state management
> >
> > > [tab] How It Works
> > >
> > > **1. Create Knowledge Base**
> > >
> > > Add a new Knowledge Base data source in Integration Designer
> > >
> > > **2. Ingest content**
> > >
> > > Upload PDF documents or ingest data from workflows into content sources
> > >
> > > **3. Automatic chunking**
> > >
> > > Content is automatically split into chunks and indexed in the vector database
> > >
> > > **4. Configure Custom Agent**
> > >
> > > Enable Knowledge Base in Custom Agent nodes and configure query parameters
> > >
> > > **5. Query execution**
> > >
> > > AI agents query the Knowledge Base using semantic search and receive relevant chunks
> > >
> > > **6. Response generation**
> > >
> > > Agents use retrieved chunks as context to generate accurate, informed responses
> >
> > > [tab] Workflow Operations
> > >
> > > **Knowledge Base operations available in workflows:**
> > >
> > > | Operation | Description |
> > > | - | - |
> > > | **Append** | Add new content to an existing content source without removing existing data |
> > > | **Replace** | Delete all existing content and replace with new content |
> > > | **Delete** | Remove all content from a content source |
> > >
> > > **Configuration Options:**
> > >
> > > * **Knowledge Base**: Select from local project libraries or dependencies
> > > * **Content Source**: Use existing sources, create new ones, or use workflow variables
> > > * **Content**: Static text, workflow variables, or configuration parameters
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product documentation assistant
> > > >
> > > > Create Knowledge Bases with product documentation for AI agents to answer customer questions
> > >
> > > > [card] Policy compliance
> > > >
> > > > Upload company policies so AI agents can reference them when processing requests
> > >
> > > > [card] Dynamic knowledge updates
> > > >
> > > > Ingest data from external systems through workflows to keep AI knowledge current
> > >
> > > > [card] Multi-source synthesis
> > > >
> > > > Organize information across sources and let AI agents synthesize comprehensive answers
> >
> > > [tab] Benefits
> > >
> > > > [card] Contextual AI responses
> > > >
> > > > AI agents provide accurate responses based on your organization's actual documentation
> > >
> > > > [card] Dynamic updates
> > > >
> > > > Keep AI knowledge current by ingesting data from workflows automatically
> > >
> > > > [card] Quality control
> > > >
> > > > Relevance scoring ensures only high-quality, relevant information is used
> > >
> > > > [card] Centralized management
> > > >
> > > > Manage all AI knowledge sources from a single location in Integration Designer
> > >
> > > > [card] No code integration
> > > >
> > > > Configure Knowledge Base queries directly in Custom Agent nodes without code
> > >
> > > > [card] Testable
> > > >
> > > > Test queries and see relevance scores before deploying to production
> >
> > > [tab] Limitations
> > >
> > > **Current Limitations:**
> > >
> > > > [!WARNING]
> > > >
> > > > * Only PDF documents are supported for manual upload (images, PPT, DOC, XLS support coming in future releases)
> > > > * Custom metadata cannot be defined (only system metadata is available)
> > > > * AI agents can only use one Knowledge Base per Custom Agent node
> > > > * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
> >
> > > [card] [Knowledge Base Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > Complete guide to creating Knowledge Bases, ingesting content, and using them in Custom Agent workflows.
> >
> > AI Integration
>
> ***
>
> ### **Update process variables**
>
> > [card] Update process variables
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces the ability for operations teams to modify process variables on active (Started or On Hold) process instances, providing critical tools to resolve production issues without process restarts. Edit, add, or delete attributes and objects directly using an editor with JSON validation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Formatting%20_%20Custom%20Date%20Format.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Tokens%20table.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > > [!NOTE]
> > > >
> > > > Updated values automatically sync to Task Manager and Elasticsearch, ensuring consistency across all systems. Previous values are saved in a snapshot table, and all modifications are tracked in the audit log for complete traceability.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Limited correction tools
> > > >
> > > > Operations teams had minimal tools to correct production issues at the process-instance level
> > >
> > > > [card] Blocked instances
> > > >
> > > > No way to unblock stuck process instances without backend intervention or process restarts
> > >
> > > > [card] Data correction challenges
> > > >
> > > > Incorrect process data required complex workarounds or manual database modifications
> > >
> > > > [card] Operational delays
> > > >
> > > > Production issues required developer intervention, increasing resolution time
> >
> > > [tab] Key Features
> > >
> > > > [card] Editor
> > > >
> > > > Edit process variables in a JSON editor with syntax validation and formatting
> > >
> > > > [card] Multiple entry points
> > > >
> > > > Access from Process Instances page contextual menu or Process Instance page secondary navigation
> > >
> > > > [card] Dual view modes
> > > >
> > > > Switch between Tree View (existing) and JSON View for variable visualization and editing
> > >
> > > > [card] Full CRUD operations
> > > >
> > > > Edit existing attribute values, add new attributes/objects, or delete existing attributes/objects
> > >
> > > > [card] JSON validation
> > > >
> > > > Automatic JSON format validation before saving to ensure data integrity
> > >
> > > > [card] Snapshot history
> > > >
> > > > Previous process variables are saved in a new snapshot table before changes are applied
> > >
> > > > [card] Auto-sync to Task Manager
> > > >
> > > > Updated variables automatically sync to Task Manager using existing mechanism
> > >
> > > > [card] Elasticsearch integration
> > > >
> > > > Process variables configured for data search are automatically updated in Elasticsearch
> > >
> > > > [card] Permission-based access
> > > >
> > > > Role-based access control with process\_variables\_edit permission ensures only authorized users can modify variables
> > >
> > > > [card] Export functionality
> > > >
> > > > Export button available near the view dropdown for downloading process variables
> > >
> > > **Iteration 2 - Enhanced Review:**
> > >
> > > > [card] Compare feature
> > > >
> > > > Ability to review updated process variables through a compare feature, showing before/after values for better visibility and validation
> >
> > > [tab] How It Works
> > >
> > > **Accessing the Feature:**
> > >
> > > You can access the edit functionality from two entry points:
> > >
> > > 1. **Process Instances Page**: Use contextual menu on a process instance row → navigates to Process Instance page and opens Variables tab in edit mode
> > > 2. **Process Instance Page**: Use contextual menu in secondary navigation → opens Variables tab in edit mode
> > >
> > > **Editing Process Variables:**
> > >
> > > **1. Select active instance**
> > >
> > > Choose an active process instance (Started or On Hold status) that requires variable modification
> > >
> > > **2. Switch to JSON view**
> > >
> > > In the Variables tab, switch from Tree View to JSON View using the view dropdown
> > >
> > > **3. Click edit**
> > >
> > > Click the Edit button (visible only if you have process\_variables\_edit permission)
> > >
> > > **4. Modify in editor**
> > >
> > > Edit process variables in the JSON editor - you can edit existing values, add new attributes/objects, or delete existing ones
> > >
> > > **5. Validate JSON**
> > >
> > > Ensure your JSON format is valid before saving - the editor will highlight syntax errors
> > >
> > > **6. Save changes**
> > >
> > > Click Save to apply changes - a snapshot of previous values is automatically created
> > >
> > > **7. Auto-sync**
> > >
> > > System automatically syncs updated variables to Task Manager and Elasticsearch (for variables configured for data search)
> > >
> > > **8. Review audit log**
> > >
> > > Check the Audit Log tab to confirm the modification was recorded with all details
> >
> > > [tab] Permissions & Security
> > >
> > > **Permission Requirements:**
> > >
> > > * **New Permission**: `process_variables_edit` available at workspace level
> > > * **Default Roles**: Added to `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, and `workspace_operations_editor` roles
> > > * **New Role**: `workspace_operations_editor` - A dedicated workspace role for operations management including process variable editing and operations (migration & move token)
> > >
> > > **Access Control:**
> > >
> > > * Edit option in UI is only visible to users with `process_variables_edit` permission
> > > * Save functionality is restricted to users with the required permission
> > > * Unauthorized users can view process variables but cannot modify them
> > >
> > > **Audit Logging:**
> > >
> > > Every process variable modification creates an audit log entry with:
> > >
> > > * Workspace ID
> > > * Feature: Process variables
> > > * Section: Process Instance
> > > * Application UUID and name
> > > * Subject: Process variables
> > > * Event: Edit
> > > * Subject Identifier: Process instance UUID
> > > * Body: JSON with new version of process parameters
> > >
> > > Audit logs are displayed in the Audit Log tab within the process instance for easy tracking.
> >
> > > [tab] Data Synchronization
> > >
> > > **What Gets Updated:**
> > >
> > > > [card] Task Manager
> > > >
> > > > Variables are automatically updated in Task Manager using existing mechanisms - ensures task keywords and data remain consistent
> > >
> > > > [card] Elasticsearch
> > > >
> > > > Variables configured for data search are automatically updated in Elasticsearch - maintains search accuracy
> > >
> > > > [card] Process instance params
> > > >
> > > > Primary process instance parameters are updated immediately in the database
> > >
> > > > [card] Snapshot table
> > > >
> > > > Previous values are saved in a new snapshot table before changes are applied
> > >
> > > **What Does NOT Get Updated:**
> > >
> > > > [card] Process snapshots
> > > >
> > > > Process instance snapshots (used for back navigation/reset) are not updated - maintains historical integrity
> > >
> > > > [card] Debug table
> > > >
> > > > Process instance debug records remain unchanged - preserves execution history
> > >
> > > > [card] Existing audit logs
> > > >
> > > > Previously recorded audit logs (manual actions, integrations) are not modified - maintains compliance trail
> > >
> > > > [card] Subprocess variables
> > > >
> > > > Child subprocess variables are not automatically updated - parent changes don't cascade to children
> >
> > > [tab] Important Considerations
> > >
> > > **Limitations & Best Practices:**
> > >
> > > > [!WARNING]
> > > >
> > > > **Subprocess Impact**: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.
> > >
> > > > [!WARNING]
> > > >
> > > > **Back Navigation**: 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.
> > >
> > > > [!WARNING]
> > > >
> > > > **Integration Messages**: 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.
> > >
> > > **Best Practices:**
> > >
> > > * **Verify JSON Format**: Always ensure valid JSON before saving to prevent data corruption
> > > * **Document Changes**: Use audit logs to track all modifications and maintain operational documentation
> > > * **Test in Lower Environments**: When possible, test variable modifications in staging before production
> > > * **Understand Dependencies**: Review process flow and subprocess relationships before modifying variables
> > > * **Consider Timing**: Best used for stuck processes or data corrections, not for regular operational changes
> > > * **Check Search Data**: If variables are used in data search, verify Elasticsearch sync completed successfully
> >
> > > [tab] Benefits
> > >
> > > > [card] Faster issue resolution
> > > >
> > > > Operations teams can resolve production issues immediately without developer intervention
> > >
> > > > [card] Reduced downtime
> > > >
> > > > Unblock stuck instances quickly, minimizing impact on end users and business processes
> > >
> > > > [card] Operational independence
> > > >
> > > > Empower ops teams with self-service tools for process-instance management
> > >
> > > > [card] Data consistency
> > > >
> > > > Automatic sync ensures Task Manager and Elasticsearch reflect updated values
> > >
> > > > [card] Full traceability
> > > >
> > > > Snapshots and audit logs provide complete history of all modifications for compliance
> > >
> > > > [card] Reduced risk
> > > >
> > > > Permission-based access and comprehensive audit trail reduce risk of unauthorized changes
> > >
> > > > [card] Flexible editing
> > > >
> > > > The JSON editor provides powerful JSON editing capabilities with validation
> > >
> > > > [card] Historical preservation
> > > >
> > > > Original values preserved in snapshot table for rollback scenarios
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Correct User Input Errors**
> > >
> > > * Customer submitted incorrect data in a loan application (wrong income, invalid address)
> > > * Operations team edits the variables to correct the information
> > > * Process continues without requiring customer to restart the application
> > >
> > > **2. Unblock Stuck Process Instances**
> > >
> > > * Process is waiting for external data that will never arrive (integration timeout, external system down)
> > > * Ops team updates the variable to provide expected data or skip the condition
> > > * Instance is unblocked and continues execution
> > >
> > > **3. Fix Integration Data Issues**
> > >
> > > * External system returned incorrect or incomplete data
> > > * Operations team corrects process variables to match expected values
> > > * Process continues with accurate data without re-calling the integration
> > >
> > > **4. Emergency Data Updates**
> > >
> > > * Critical business information changed after process started (regulatory update, pricing change)
> > > * Ops team modifies variables to reflect current information
> > > * Process continues with updated data without restart
> > >
> > > **5. Add Missing Attributes**
> > >
> > > * Process needs additional data that wasn't collected at start
> > > * Operations team adds new attributes or objects to process variables
> > > * Process can now access the required information
> > >
> > > **6. Remove Invalid Data**
> > >
> > > * Process contains incorrect or test data that shouldn't be there
> > > * Ops team deletes the problematic attributes or objects
> > > * Process continues with clean, valid data only
> > >
> > > **7. Update Task Manager Keywords**
> > >
> > > * Task search keywords need updating based on corrected data
> > > * Variables are modified and automatically synced to Task Manager
> > > * Tasks become searchable with correct keywords
> > >
> > > **8. Fix Elasticsearch Search Data**
> > >
> > > * Process data indexed for search contains errors
> > >
> > > * Operations team corrects variables configured for data search
> > >
> > > * Elasticsearch automatically updates, ensuring accurate search results
> > >
> > > > [!NOTE]
> > > >
> > > > This capability, combined with the upcoming Move Token feature, provides comprehensive process-instance management tools for operations teams.
> >
> > > [card] [Update Process Variables Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > >
> > > Complete guide including step-by-step instructions, permissions, data synchronization, best practices, and troubleshooting.
> >
> > Operations Enhancement
>
> ***
>
> ### **Token view improvements**
>
> > [card] Token view improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the **Tokens tab** in the **Process Instance View** with improved visibility and comprehension of token hierarchy and context. The enhanced token view introduces horizontal scrolling, frozen columns, hierarchical nesting, and new context-related columns to provide better insights into process execution.
> > >
> > > > [!NOTE]
> > > >
> > > > These improvements make it easier to understand complex process flows with parallel gateways, embedded subprocesses, and boundary events by clearly displaying token relationships and execution context.
> >
> > > [tab] Key Features
> > >
> > > > [card] Horizontal scrolling
> > > >
> > > > The table supports horizontal scrolling to accommodate all columns, ensuring all token information remains accessible
> > >
> > > > [card] Frozen columns
> > > >
> > > > Token UUID and Actions columns remain fixed during horizontal scroll for constant visibility of key identifiers and actions
> > >
> > > > [card] Hierarchical nesting
> > > >
> > > > Tokens display in a tree structure with nested child tokens under parent tokens, showing clear parent-child relationships
> > >
> > > > [card] Auto-expanded rows
> > > >
> > > > All token rows are expanded by default, providing immediate visibility into the complete token hierarchy
> > >
> > > > [card] Dynamic indentation
> > > >
> > > > Indentation dynamically adjusts based on nesting depth, visually representing token relationships
> > >
> > > > [card] Context column
> > > >
> > > > New Context column displays subprocess names for tokens running within embedded subprocesses, or main process name for main process tokens
> > >
> > > > [card] Initiator node column
> > > >
> > > > New Initiator Node column shows the node name that generated the token (e.g., Parallel Gateway, Non-interrupting boundary event)
> > >
> > > > [card] First executed node column
> > > >
> > > > New First Executed Node column displays the first node executed after token generation
> > >
> > > > [card] UUID copy functionality
> > > >
> > > > Token UUID displays first 6 characters with a copy icon; clicking copies the full UUID to clipboard with success notification
> > >
> > > > [card] Color-coded status tags
> > > >
> > > > Token Status column uses color-coded tags for quick visual identification of token lifecycle states
> > >
> > > > [card] Tooltip support
> > > >
> > > > Long node names are truncated with tooltips showing full text on hover for better readability
> > >
> > > > [card] Timezone-aware timestamps
> > > >
> > > > Last Updated column displays full datetime in browser timezone for accurate local time representation
> >
> > > [tab] Table Columns
> > >
> > > The enhanced token view includes the following columns:
> > >
> > > | Column | Description | Special Behavior |
> > > | - | - | - |
> > > | **Token UUID** | Unique identifier of the token | Only first 6 characters displayed. Copy icon appears beside UUID. Clicking copies full UUID to clipboard with success toast: "Full Token UUID copied to clipboard." **Frozen column** (stays visible during horizontal scroll) |
> > > | **Context** | Displays contextual data for token | Shows main process name for tokens in main process. Shows embedded subprocess name for tokens in embedded subprocesses (any nesting level) |
> > > | **Initiator Node** | Shows the node name that generated the token | Applies to child tokens only. For parent tokens, displays "-". Examples: Parallel Gateway name, Non-interrupting boundary event name |
> > > | **First Executed Node** | Displays the first node executed after token generation | For parallel gateway tokens: first executed node on that parallel branch. For boundary event tokens: first executed node on branch started from boundary node. If first node is embedded subprocess, displays embedded subprocess name |
> > > | **Current Node** | Displays the last node executed within the token branch | For parallel gateway tokens: last node on branch. For boundary event tokens: last node executed on branch triggered by boundary. For tokens in embedded subprocess: displays current node from subprocess |
> > > | **Current Node Status** | Shows the current execution status | Examples: WAITING\_TIMER\_EVENT, ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL. Sortable column |
> > > | **Token Status** | Indicates lifecycle state | Values: ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, TERMINATED. **Color-coded tags** for visual identification |
> > > | **Last Updated** | Timestamp of latest token state change | Displays full datetime in browser timezone |
> > > | **Actions** | Available actions for the token | Includes Retry token and View (eye icon) actions. **Frozen column** (stays visible during horizontal scroll). Retry button only visible for ACTIVE tokens |
> >
> > > [tab] Nesting Behavior
> > >
> > > **Token Hierarchy Display:**
> > >
> > > **1. Parent-child relationships**
> > >
> > > Tokens created by parallel gateways or embedded subprocesses are displayed as nested child tokens under their parent tokens
> > >
> > > **2. Default expansion**
> > >
> > > All token rows are expanded by default, showing the complete token hierarchy immediately
> > >
> > > **3. Dynamic indentation**
> > >
> > > Indentation adjusts automatically based on nesting depth, with columns expanding accordingly to maintain alignment
> > >
> > > **4. Visual hierarchy**
> > >
> > > The tree structure makes it easy to identify which tokens belong to which parallel branch or subprocess
> > >
> > > **Initiator Node Logic:**
> > >
> > > * **Parent tokens**: Display "-" in Initiator Node column
> > > * **Child tokens from parallel gateway**: Display the parallel gateway node name
> > > * **Child tokens from boundary event**: Display the boundary event node name
> > > * **Child tokens from back in steps**: Display appropriate initiator information
> >
> > > [tab] Benefits
> > >
> > > > [card] Better visibility
> > > >
> > > > Horizontal scrolling and frozen columns ensure all token information remains accessible regardless of table width
> > >
> > > > [card] Clear hierarchy
> > > >
> > > > Hierarchical nesting with dynamic indentation makes parent-child token relationships immediately clear
> > >
> > > > [card] Context awareness
> > > >
> > > > Context column provides immediate visibility into which subprocess a token is executing within
> > >
> > > > [card] Execution tracking
> > > >
> > > > Initiator Node and First Executed Node columns help track token origin and execution path
> > >
> > > > [card] Quick actions
> > > >
> > > > Frozen Actions column ensures retry and view actions are always accessible without scrolling
> > >
> > > > [card] Easy UUID access
> > > >
> > > > Quick copy functionality for full UUIDs without needing to view token details
> > >
> > > > [card] Visual status identification
> > > >
> > > > Color-coded status tags enable quick identification of token states at a glance
> > >
> > > > [card] Improved readability
> > > >
> > > > Tooltips for truncated names and timezone-aware timestamps improve overall readability
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Parallel Gateway Debugging**
> > >
> > > * View all parallel branches simultaneously with clear parent-child relationships
> > > * Identify which branch each token belongs to through hierarchical nesting
> > > * Track execution progress across multiple parallel paths
> > >
> > > **2. Embedded Subprocess Analysis**
> > >
> > > * Context column immediately shows which subprocess tokens are executing within
> > > * Understand nested subprocess relationships through indentation
> > > * Track token flow across multiple subprocess levels
> > >
> > > **3. Boundary Event Monitoring**
> > >
> > > * Initiator Node column shows which boundary event triggered each token
> > > * First Executed Node shows the execution path started by boundary events
> > > * Monitor non-interrupting boundary event token execution
> > >
> > > **4. Process Instance Troubleshooting**
> > >
> > > * Frozen UUID column ensures token identification is always visible
> > > * Copy UUID functionality enables quick token reference in support tickets
> > > * Color-coded status tags help identify problematic tokens quickly
> > >
> > > **5. Multi-Level Process Analysis**
> > >
> > > * Hierarchical view supports complex processes with multiple nesting levels
> > > * Dynamic indentation adapts to any nesting depth
> > > * All tokens visible by default without manual expansion
> >
> > > [card] [Token Documentation](/5.1/docs/building-blocks/token)
> > >
> > > Complete guide to tokens, including token status values, current node status, and detailed token status view.
> >
> > UX Enhancement
>
> ***
>
> ### **Access management enhancements**
>
> > [card] Access management enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces new workspace-level permissions and a dedicated operations editor role, providing more granular control over process instance management and operations.
> > >
> > > > [!NOTE]
> > > >
> > > > These enhancements enable organizations to delegate operational tasks to dedicated teams without granting full runtime or admin access.
> >
> > > [tab] New Role
> > >
> > > **workspace\_operations\_editor**
> > >
> > > A new predefined workspace role designed for operations teams who need to manage process instances without requiring full runtime or admin capabilities.
> > >
> > > > [card] Operations management
> > > >
> > > > Full CRUD access for process instance operations including migration and move token functionality
> > >
> > > > [card] Process variables
> > > >
> > > > Edit permission for process variables on active instances across the workspace
> > >
> > > > [card] Process instances
> > > >
> > > > Read and edit access to all process instances in the workspace
> > >
> > > > [card] Workspace user inheritance
> > > >
> > > > Inherits all base permissions from workspace\_user role including project creation
> > >
> > > **Role Constraints:**
> > >
> > > * Cannot be edited or deleted (predefined role)
> > > * Extends workspace\_user with operations-specific permissions
> > > * Does not include broader runtime capabilities (builds, policies, scheduled processes)
> > >
> > > **Use Cases:**
> > >
> > > * Support engineers managing process migrations
> > > * Operations teams handling token movements
> > > * Technical support staff editing process variables
> >
> > > [tab] New Permissions
> > >
> > > **Workspace-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **Operations** (Read/Edit/Create/Delete) | Manage process instance operations including migration and move token | `org_admin`, `workspace_admin`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Operations** (Read/Create only) | Create operations and view all operations | `workspace_user` |
> > > | **Process Variables** (Edit) | Edit process variables on active instances | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Process Instances** (Edit) | Edit process instance data | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > >
> > > **Project-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **UI Flows** (Read/Edit/Create/Delete) | Full access to create and manage UI Flows | `project_owner`, `project_editor` |
> > > | **UI Flows** (Read only) | View UI Flows definitions | `project_viewer` |
> >
> > > [tab] Benefits
> > >
> > > > [card] Principle of least privilege
> > > >
> > > > Grant only the permissions needed for specific operational tasks
> > >
> > > > [card] Dedicated operations teams
> > > >
> > > > Enable operations teams to work independently without full admin access
> > >
> > > > [card] Clear separation of concerns
> > > >
> > > > Distinguish between runtime management (builds, policies) and operations management (migrations, variables)
> > >
> > > > [card] Flexible role combinations
> > > >
> > > > Combine with other workspace roles for customized access patterns
> >
> > > [card] [Access Management Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix)
> > >
> > > Complete permissions matrix and role specifications for all FlowX roles.
> >
> > Access Management
>
> ***
>
> ### **Performance and stability**
>
> > [card] Performance and stability
> >
> > FlowX.AI 5.3 includes platform improvements focused on performance, reliability, and operational excellence.
> >
> > ## Backend optimizations
> >
> > > [card] Optimistic lock improvements
> > >
> > > Replace retry pattern with capped exponential backoff and infinite retries for better concurrency handling
> >
> > > [card] Events gateway optimization
> > >
> > > Update Redis read mode to XREAD BLOCK for more efficient event streaming
> >
> > > [card] Database performance
> > >
> > > Remove unnecessary index on token\_instance.current\_node\_id to improve update performance
> >
> > > [card] Template caching
> > >
> > > Enhanced caching for reusable templates at runtime reduces latency and improves throughput
> >
> > ## Infrastructure updates
> >
> > > [card] Connector Topic Pattern
> > >
> > > Added dedicated KAFKA\_CONNECTORS\_TOPIC\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [card] SpiceDB backup
> > >
> > > Documented backup and restore procedures for SpiceDB for disaster recovery
> >
> > > [card] Observability
> > >
> > > Publish Prometheus and OpenTelemetry Helm charts and container images to Harbor
> >
> > > [card] Security updates
> > >
> > > Fix HIGH vulnerabilities in Designer 5.1.x and main branch
> >
> > > [card] Renderer improvements
> > >
> > > Enhanced Angular renderer with action form submit functionality and substitution tag support
> >
> > Platform Updates
>
> ***
>
> ### **Exclusive gateways**
>
> > [card] Exclusive gateways
> >
> > FlowX.AI 5.3 enhances Exclusive Gateway configuration with expression testing capabilities and improved validation.
> >
> > > [card] Expression testing
> > >
> > > Test gateway expressions directly from the configuration panel with real-time validation
> >
> > > [card] Committed version testing
> > >
> > > Test business rules and gateway expressions in committed versions
> >
> > > [card] Code editor integration
> > >
> > > Enhanced code editor with syntax highlighting for complex expressions
> >
> > > [card] Payload synchronization
> > >
> > > Test payloads automatically update when rules are saved
> >
> > Process Logic
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes and stability improvements across Designer, renderers, backend services, and data management.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI Designer and Integration Designer stability improvements\
> 🖥️ [**Renderer Fixes**](#renderer-fixes) - Cross-platform renderer bug fixes for web, iOS, and Android\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements\
> 🗄️ [**Data & Integration Fixes**](#data-and-integration-fixes) - Data mapper and workflow integration fixes
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.3 resolves numerous Designer issues to improve stability and user experience.
> >
> > ## UI designer improvements
> >
> > > [accordion] Configuration & styling
> > >
> > > * **Fixed styles not applied after undo/redo** in Reusable UI Template config panel
> > > * **Fixed UI blocking** when slider min value exceeds max value
> > > * **Fixed warning icon display** in config panel
> > > * **Fixed expression test modal styles** when opened in resized screen
> > > * **Fixed UI action section refresh** when selecting different UI template
> > > * **Fixed UI action section rendering** after clicking 'Add new ui action'
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed loading spinner toggle** not available for Overlay loading behavior
> > > * **Fixed incomplete loading behavior dropdown**
> > > * **Fixed default messages** not displayed after undo
> > > * **Fixed forms in collections handling** for patch actions requests
> >
> > > [accordion] UI Flows designer
> > >
> > > * **Fixed task management error state** when view is selected
> > > * **Fixed tab content preview** showing content from 2 tabs when adding new tab
> >
> > > [accordion] Output parameters
> > >
> > > * **Fixed currency key management** - can now add/remove currency key in output params
> >
> > > [accordion] Exclusive Gateways
> > >
> > > * **Fixed gateway decisions** can now be modified after initial save
> > > * **Fixed test payload** updates when rules are saved
> > > * **Fixed expression propagation** to test modal
> >
> > ## Frontend runtime fixes
> >
> > > [accordion] Process management
> > >
> > > * **Fixed context column** showing empty value for tokens in embedded subprocesses
> > > * **Fixed process params update** from running process instance modal
> > > * **Fixed long node names** overlapping adjacent columns in Tokens table
> > > * **Fixed workspace redirect** on page refresh
> >
> > > [accordion] Audit & logging
> > >
> > > * **Fixed audit log subject value** not displayed for process params updates
> > > * **Fixed toast error messages** to use text from backend request
> > > * **Added documentation link** to Modify Variables modal info text
> >
> > Designer Stability
>
> ***
>
> ### **Renderer fixes**
>
> > [card] Renderer fixes
> >
> > FlowX.AI 5.3 includes comprehensive renderer fixes across all platforms.
> >
> > ## Web renderers (Angular & React)
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed theming** not applied to general loader
> > > * **Fixed theming** not applied to toast messages
> > > * **Fixed dynamic key values** not displayed in toast/loading messages
> > > * **Fixed success toast** displayed when flag is false
> >
> > > [accordion] Card & navigation
> > >
> > > * **Fixed card not expandable** after finishing subprocess started from it (Angular & React)
> > > * **Fixed card collapse** when next nav area is modal (Angular & React)
> > > * **Fixed subprocess navigation** closing parent process navigation with multiple hierarchies
> >
> > > [accordion] UI events
> > >
> > > * **Fixed UI event triggering** without user interaction (Angular)
> >
> > > [accordion] Call activity
> > >
> > > * **Fixed call activity UT rendering** when started from embedded process
> >
> > > [accordion] Collections & forms
> > >
> > > * **Fixed button with forms to submit** no longer disabled until template edited (Angular & React)
> > > * **Fixed multi-select search** filtering (React)
> > > * **Fixed JSON generation** with special characters in CollectionsV2
> >
> > ## Mobile renderers
> >
> > > [accordion] Android
> > >
> > > * **Fixed SSE Event & UI Event** - UI event value displayed instead of SSE value
> >
> > Renderer Stability
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process management
> >
> > > [accordion] Process & build issues
> > >
> > > * **Fixed processes not displayed** in container app list for imported builds
> > > * **Fixed token state** changing from Aborted to Active during back navigation
> > > * **Fixed audit logs** for override operations after merge
> >
> > > [accordion] Performance
> > >
> > > * **Fixed /details endpoint** returning cache error for processes with many components
> >
> > > [accordion] Process engine
> > >
> > > * **Fixed token stuck** in receive node when message received after advancing
> > > * **Fixed action params** copied correctly for child actions when copying node
> > > * **Fixed metadata preservation** when importing process
> >
> > ## Security & configuration
> >
> > > [accordion] Authentication
> > >
> > > * **Fixed service account client secret** configuration parameter in Authorization service
> >
> > ## Data management
> >
> > > [accordion] Runtime issues
> > >
> > > * **Fixed FlowxProps.events** mapping at runtime for array of objects
> >
> > ## Infrastructure
> >
> > > [accordion] Database & events
> > >
> > > * **Fixed advancing errors** in partition event table
> > > * **Fixed Liquibase logging** when crashing due to lock
> >
> > Backend Stability
>
> ***
>
> ### **Data and integration fixes**
>
> > [card] Data and integration fixes
> >
> > Fixes for data mappers and workflow integration features.
> >
> > ## Data mapper issues
> >
> > > [accordion] Mapping operations
> > >
> > > * **Fixed 400 error** when saving mappings
> > > * **Fixed error** when saving mapping with empty parameters
> > > * **Fixed unsaved mapping modal** displayed when saving action
> > > * **Fixed array mapping** - arrays in mapper functions now work correctly
> > > * **Fixed slice deletion** when updating PDM objects
> >
> > > [accordion] Data streams & workflows
> > >
> > > * **Fixed data stream availability** for older exports during import
> > > * **Fixed workflow data stream** data appending issue
> > > * **Fixed legacy mapping** toggle now triggers correctly for call activity
> >
> > > [accordion] UI updates
> > >
> > > * **Fixed start node** not updated in UI after parameters update until refresh
> > > * **Fixed manifest resource** not found after switching versions
> >
> > > [!NOTE]
> > >
> > > Data mapper fixes ensure reliable workflow integration and process-to-workflow data synchronization.
> >
> > Integration Stability
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.3.0](./deployment-guidelines-v5.3).
>
> ### Environment variable updates
>
> > [!NOTE]
> >
> > For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.
>
> ### Breaking changes
>
> > [!WARNING]
> >
> > **FlowX Engine Configuration**: v5.3.0 includes a breaking change to the partitioning and archiving configuration structure. If you have enabled data partitioning, you must update your configuration files.
>
> > [card] [Migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
> >
> > Complete migration guide with step-by-step instructions, configuration examples, and troubleshooting
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.2.0 requires configuration changes for FlowX Engine partitioning/archiving
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.3


# Deployment guidelines v5.4.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/deployment-guidelines-v5.4

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.38.0** | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **10.38.0** | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **10.22.0** | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **10.15.0** | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **10.17.0** | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **10.22.0** | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **10.23.0** | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **10.25.0** | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **10.14.0** | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **10.21.0** | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **10.16.0** | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **10.38.0** | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **10.20.1** | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **10.28.0** | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **10.17.0** | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **email-gateway** | **10.9.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 |

### AI Platform

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.4.0 | Keycloak | 26+ |
| 5.4.0 | Kafka | 3.8 - 3.9 |
| 5.4.0 | PostgreSQL | 16 - 17 |
| 5.4.0 | Oracle Database | 21c, 23ai |
| 5.4.0 | MongoDB | 7 - 8 |
| 5.4.0 | Redis | 7.4 - 8.0 |
| 5.4.0 | Elasticsearch | 8 |
| 5.4.0 | Angular (Web SDK) | 20 |
| 5.4.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.4.0

### Key features and updates

> [card] Email Trigger
>
> Start processes automatically from incoming emails with configurable validation rules

> [card] MCP Server Improvements
>
> Enhanced audit logging, resource management, and tool refresh capabilities

> [card] Email Gateway
>
> New microservice for handling email communication workflows

## Upgrading from v5.3.0

### Breaking changes

> [!NOTE]
>
> FlowX.AI 5.4.0 does not introduce breaking changes for standard deployments. Upgrades from v5.3.0 should be straightforward.

### New environment variables

The following new environment variables have been introduced:

| Variable | Service | Description |
| - | - | - |
| `KAFKA_CONNECTORS_TOPIC_PATTERN` | process-engine | Dedicated Kafka topic pattern for connectors (optional, falls back to `KAFKA_TOPIC_PATTERN` if not set) |
| `KAFKA_BOOTSTRAP_SERVERS` | All services | Standardized Kafka bootstrap servers property (preferred over `SPRING_KAFKA_BOOTSTRAPSERVERS`, backwards compatible) |
| `KAFKA_SECURITY_PROTOCOL` | All services | Standardized Kafka security protocol property (preferred over `SPRING_KAFKA_SECURITY_PROTOCOL`, backwards compatible) |

### Key changes

* **Email Trigger**: New capability to start processes from email events
* **Connector Topics**: New dedicated topic pattern variable for connectors
* **Kafka Configuration**: Standardized Kafka property names (`KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_SECURITY_PROTOCOL`) aligned across all services with backwards compatibility
* **Email Gateway**: New microservice for email communication workflows

### New microservice: Email Gateway

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces a new optional microservice: **Email Gateway**. This service handles email communication workflows within the platform.

The Email Gateway requires the following infrastructure:

| Component | Requirement |
| - | - |
| PostgreSQL | Dedicated database named `email_gateway` |
| MongoDB | Connection to existing `app-runtime` database |
| Kafka | Access to the FlowX Kafka cluster |
| Redis | Shared Redis instance |
| Keycloak | Service account for authentication |

> [!NOTE]
>
> The Email Gateway operates as an internal service and does not require ingress configuration.

> [card] [Email Gateway Setup Guide](/5.9/setup-guides/email-gateway-setup)
>
> Complete setup instructions including Helm values, environment variables, and troubleshooting.

### Compatibility

* **No Breaking Changes**: Standard deployments can upgrade without configuration changes
* **Feature Additions**: SaaS features require additional infrastructure configuration for production use
* **Renderer Updates**: Web and mobile SDKs include bug fixes with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.4.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026

SaaS multi-tenant platform capabilities, database tenant isolation, email-triggered processes, MCP server enhancements, and backend performance improvements.

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces foundational support for a multi-tenant platform, enabling organization management and improved tenant isolation in the SaaS deployment model.

> [!NOTE]
>
> **Deployment models** - Starting with v5.4.0, FlowX.AI is available in two deployment models:
>
> * **Self-Managed** (On-Premises / Customer Cloud)
> * **FlowX SaaS** (FlowX-hosted)
>
> **Feature availability badges:**
>
> * SaaS Features exclusive to FlowX SaaS deployments
> * Self-Managed Features specific to self-managed deployments
> * All Deployments Features available in both deployment models

**What's new?**

> [tab] SaaS & multi-tenancy
>
> > [!NOTE]
> >
> > The features described in this section apply to **FlowX SaaS deployments**.\
> > Self-managed deployments are not affected unless explicitly stated.
>
> FlowX.AI 5.4.0 introduces initial SaaS capabilities enabling multi-tenant deployments with organization management and tenant isolation.
>
> 🏢 [**SaaS Multi-Tenancy**](#saas-multi-tenancy) - Multi-tenant platform with organization isolation and provisioning
>
> ### **SaaS multi-tenancy**
>
> > [card] SaaS multi-tenancy
> >
> > Multi-tenant SaaS capabilities enable multiple organizations to operate independently on shared infrastructure. Each organization receives dedicated resources while maintaining complete isolation from other tenants.
> >
> > > [card] Multi-tenant architecture
> > >
> > > Multiple organizations operate on shared infrastructure with complete isolation
> >
> > > [card] Tenant isolation
> > >
> > > Complete data and authentication isolation between organizations
> >
> > > [card] Organization provisioning
> > >
> > > Automatic provisioning of dedicated resources for each organization
> >
> > > [card] Resource management
> > >
> > > Each organization receives dedicated resources and project spaces
> >
> > > [card] [Documentation](/5.9/docs/saas/saas-overview)
> > >
> > > See the complete FlowX SaaS documentation for guides and best practices.
> >
> > Major FeatureSaaS
>
> ***

> [tab] AI & Integration
>
> Enhanced MCP server management.
>
> 📧 [**Email Trigger**](#email-trigger) - Start processes from external email events with configurable validation rules\
> 💬 [**Chat Component**](#chat-component) - Standalone chat tab for AI-powered conversational interfaces\
> 🔧 [**MCP Server Improvements**](#mcp-server-improvements) - Enhanced audit logging, resource management, and tool updates
>
> ### **Email trigger**
>
> > [card] Email trigger
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces Email Trigger as a new Data Source type in Integration Designer, enabling processes to be started automatically when emails are received. Connect to IMAP mail servers, monitor specific mailboxes, and create process instances with the email data.
> > >
> > > > [!NOTE]
> > > >
> > > > Email Triggers bridge external communication channels with FlowX.AI process automation, enabling organizations to automatically route and process incoming emails through defined business workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation for configuration guides and examples.
> >
> > > [tab] Key Features
> > >
> > > > [card] IMAP Connection
> > > >
> > > > Connect to any IMAP-compatible email server with SSL/TLS support
> > >
> > > > [card] Message Start Event
> > > >
> > > > New trigger type option in Message Start Event nodes to use Email Triggers
> > >
> > > > [card] Attachment handling
> > > >
> > > > Automatic upload of email attachments to Document Plugin with file validation
> > >
> > > > [card] Validation rules
> > > >
> > > > Configure allowed file types, maximum file size, and attachment count limits
> > >
> > > > [card] Manage triggers
> > > >
> > > > Central Runtime page to activate, deactivate, and monitor email triggers
> > >
> > > > [card] Failed triggers
> > > >
> > > > Dedicated page to view and troubleshoot failed email processing attempts
> >
> > > [tab] Configuration
> > >
> > > **Data Source Settings:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | IMAP (currently supported) |
> > > | Server Host | IMAP server hostname |
> > > | Port | Connection port (993 for SSL/TLS) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > > | SSL/TLS | Enable secure connection |
> > >
> > > **Filtering Criteria:**
> > >
> > > * **Email Address**: Monitored email address (read-only, based on authentication)
> > > * **Mailbox Folder**: Folder to monitor (default: Inbox)
> > >
> > > **Validation Options:**
> > >
> > > * **Allowed File Types**: PDF, DOCUMENT, IMAGE, EXCEL, ZIP
> > >
> > > * **Maximum File Size**: Up to 25 MB per attachment
> > >
> > > * **Maximum File Count**: Limit attachments per email
> > >
> > > > [!TIP]
> > > >
> > > > All fields accept configuration parameters using `${configParam}` syntax for environment-specific values.
> >
> > > [tab] Email Data Schema
> > >
> > > When an email triggers a process, the following data structure is available:
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "emailMessage": {
> > >     "subject": "Support Request #12345",
> > >     "dateTime": "2026-01-15T10:30:00Z",
> > >     "sender": "customer@example.com",
> > >     "body": "Email body content...",
> > >     "fileAttachments": [{
> > >       "filePath": "email-attachments/proc-123/file.pdf",
> > >       "downloadPath": "/api/internal/files/uuid/download"
> > >     }],
> > >     "headerParams": {
> > >       "Message-ID": "<abc123@example.com>"
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Use Cases
> > >
> > > > [card] Customer support automation
> > > >
> > > > Automatically create support tickets from incoming customer emails
> > >
> > > > [card] Document processing
> > > >
> > > > Process attached documents through automated workflows
> > >
> > > > [card] Request handling
> > > >
> > > > Route requests to appropriate departments based on email content
> > >
> > > > [card] Notification processing
> > > >
> > > > Process automated notifications from external systems
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat component**
>
> > [card] Chat component
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a standalone Chat tab in web container applications, enabling AI-powered conversational interfaces within your applications. The Chat component provides a dedicated space for users to interact with AI agents through a familiar messaging interface.
> > >
> > > > [!NOTE]
> > > >
> > > > The Chat component integrates with FlowX.AI's AI platform to enable intelligent conversational experiences powered by your configured AI agents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the complete Chat Component documentation for configuration guides and best practices.
> >
> > > [tab] Key Features
> > >
> > > > [card] Standalone chat tab
> > > >
> > > > Dedicated chat interface available as a standalone tab in web container apps
> > >
> > > > [card] Message history
> > > >
> > > > Persistent chat history with automatic scrolling to the latest messages
> > >
> > > > [card] AI agent integration
> > > >
> > > > Connect to workflows powered by AI agents
> > >
> > > > [card] Session management
> > > >
> > > > Automatic session handling with persistence across page refreshes
> > >
> > > > [card] Customizable UI
> > > >
> > > > Themeable components with comprehensive style configuration through Theme Admin
> >
> > > [tab] Configuration
> > >
> > > **Component setup:**
> > >
> > > * Add Chat component from UI Designer to your UI Flow
> > > * Select a workflow to handle chat interactions
> > > * Configure header, messages, and input properties
> > > * Apply custom styling through Theme Admin
> > >
> > > **Display modes:**
> > >
> > > * Full screen (v5.4.0)
> > > * Additional modes planned for v5.5
> >
> > > [tab] Improvements
> > >
> > > **Session handling:**
> > >
> > > * Chat session ID is now generated when the first message is sent (not when opening the chat)
> > > * Improved session tracking
> > >
> > > **Message display:**
> > >
> > > * Latest messages are automatically scrolled into view after loading chat history
> > > * User input formatting (JSON, multiline text) is now preserved in displayed messages
> > >
> > > **Platform support:**
> > >
> > > * Available in both Angular and React web renderers
> > > * Mobile support planned for v5.5
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **MCP server improvements**
>
> > [card] MCP server improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 enhances MCP (Model Context Protocol) server integration with improved audit logging, exception handling, and resource management capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audit logging
> > > >
> > > > Complete audit trail for MCP server operations including creation, updates, and tool execution
> > >
> > > > [card] Tool refresh
> > > >
> > > > Update MCP servers to fetch new tools without recreating the data source
> > >
> > > > [card] Resource tracking
> > > >
> > > > Track MCP server usage across workflows with proper resource management
> > >
> > > > [card] Copy support
> > > >
> > > > Properly preserve MCP server selections when copying or duplicating workflows
> > >
> > > > [card] SSE streaming
> > > >
> > > > Fixed SSE event streaming to deliver events individually as they complete
> > >
> > > > [card] Exception handling
> > > >
> > > > Improved error handling and reporting for MCP server operations
> >
> > > [tab] Bug Fixes
> > >
> > > * **Tool updates**: Updating MCP servers now correctly fetches new tools
> > > * **Workflow copy**: MCP server selections are preserved when copying workflows
> > > * **Resource usages**: Fixed resource usage tracking when copying workflows to other projects
> > > * **SSE events**: Events are now streamed individually instead of all at once
> > > * **Audit entries**: Fixed missing event and subject in audit log entries
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] Rendering
>
> UI component enhancements and navigation improvements for web applications.
>
> 🎴 [**Card Default Collapse State**](#card-default-collapse-state) - Configure cards to load in collapsed state by default\
> 🧭 [**UI Flow Breadcrumbs**](#ui-flow-breadcrumbs) - Navigation breadcrumbs ui component for UI Flows with theme configuration\
> 📊 [**UI Flow Sessions**](#ui-flow-sessions) - Monitor and manage UI Flow sessions with audit logs and process tracking\
> 📋 [**Tables in Collections**](#tables-in-collections) - Add support for Table UI components within Collection UI elements
>
> ### **Card default collapse state**
>
> > [card] Card default collapse state
> >
> > FlowX.AI 5.4.0 introduces a new **Default collapse state** property for Card components with accordion functionality, allowing you to configure cards that are collapsed when first loaded.
> >
> > > [tab] Overview
> > >
> > > When using Card components with the accordion feature enabled, you can now specify whether the card should be expanded or collapsed by default when the screen loads. This provides better control over the initial presentation of content and helps manage screen real estate.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> > > >
> > > > See the complete Card component documentation for configuration details.
> >
> > > [tab] Configuration
> > >
> > > **Default collapse state options:**
> > >
> > > | State | Description |
> > > | - | - |
> > > | **Expanded** | The card content is visible when the screen loads (default behavior) |
> > > | **Collapsed** | The card content is hidden when the screen loads; users click to expand |
> > >
> > > > [!NOTE]
> > > >
> > > > This property is only available when the **Has accordion** setting is enabled on the Card component.
> >
> > > [tab] Use Cases
> > >
> > > > [card] Progressive disclosure
> > > >
> > > > Start with collapsed sections to reduce initial visual complexity
> > >
> > > > [card] Optional content
> > > >
> > > > Hide less important information by default while keeping it accessible
> > >
> > > > [card] Long forms
> > > >
> > > > Break up lengthy forms into collapsible sections for better navigation
> > >
> > > > [card] FAQ sections
> > > >
> > > > Display questions collapsed with answers revealed on click
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Breadcrumbs**
>
> > [card] UI Flow Breadcrumbs
> >
> > > [tab] Overview
> > >
> > > Navigation breadcrumbs UI component for UI Flows provide users with clear context of their current location within the application hierarchy. Breadcrumbs display the navigation path and enable quick navigation to parent screens.
> > >
> > > > [!NOTE]
> > > >
> > > > Breadcrumbs enhance user experience by providing visual navigation context and allowing users to understand their position in the application structure.
> >
> > > [tab] Key Features
> > >
> > > > [card] Navigation breadcrumbs UI component
> > > >
> > > > Display breadcrumbs UI component for UI Flows showing the current navigation path
> > >
> > > > [card] Admin theme configuration
> > > >
> > > > Configure breadcrumb appearance and styling through Admin theme settings
> >
> > > [tab] Configuration
> > >
> > > **Theme Configuration:**
> > >
> > > * Configure breadcrumb styling through Admin theme settings
> > > * Customize colors, fonts, and spacing to match your application design
> > > * Apply consistent styling across all UI Flows
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Sessions**
>
> > [card] UI Flow Sessions
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces UI Flow Sessions monitoring in the Runtime view, providing comprehensive visibility into active user sessions with UI Flows. Monitor session activity, view audit logs, track associated processes, and debug UI Flow interactions in real-time.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flow Sessions enable administrators and developers to track user interactions, troubleshoot issues, and monitor the health of UI Flow-based applications.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> > > >
> > > > See the complete UI Flow Sessions documentation for detailed usage and troubleshooting guides.
> >
> > > [tab] Key Features
> > >
> > > > [card] Session monitoring
> > > >
> > > > View all active and historical UI Flow sessions with status, start date, and session IDs
> > >
> > > > [card] Audit log
> > > >
> > > > Comprehensive audit trail showing all events and actions within each session
> > >
> > > > [card] Process tracking
> > > >
> > > > Monitor process instances started from UI Flows with execution status and timing
> > >
> > > > [card] Workflow debugging
> > > >
> > > > View workflow execution details, node timing, and data transformations for troubleshooting
> > >
> > > > [card] Filtering and search
> > > >
> > > > Filter sessions by UI Flow definition and search by session ID for quick access
> > >
> > > > [card] Real-time status
> > > >
> > > > Track session status updates in real-time (STARTED, ACTIVE, FINISHED, FAILED)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Session monitoring
> > > >
> > > > Monitor active sessions to understand user engagement and identify sessions needing attention
> > >
> > > > [card] Audit and compliance
> > > >
> > > > Track all user interactions and actions for audit purposes and compliance requirements
> > >
> > > > [card] Debugging
> > > >
> > > > Investigate issues by reviewing audit logs, process instances, and workflow executions
> > >
> > > > [card] Performance analysis
> > > >
> > > > Analyze session duration, process start times, and workflow execution performance
> >
> > Runtime ManagementAll Deployments
>
> ***
>
> ### **Tables in Collections**
>
> > [card] Tables in Collections
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces support for Table UI components within Collection UI elements, enabling you to display structured tabular data as items within dynamic collections. This enhancement provides greater flexibility for presenting complex data structures in a consistent, organized format.
> > >
> > > > [!NOTE]
> > > >
> > > > You can now embed Table components inside Collection prototypes, allowing each collection item to display data in a structured table format with columns, rows, and table-specific features.
> > >
> > > > [card] [Table Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/table)
> > > >
> > > > See the complete Table component documentation for configuration details and usage examples.
> > >
> > > > [card] [Collection Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/collection/collection)
> > > >
> > > > Learn about Collection components and how to configure collection prototypes.
> >
> > > [tab] Key Features
> > >
> > > > [card] Table in collection items
> > > >
> > > > Embed Table components within Collection prototypes to display structured data for each collection item
> > >
> > > > [card] Structured data display
> > > >
> > > > Present complex data structures with columns, rows, and table-specific formatting within collections
> > >
> > > > [card] Table features
> > > >
> > > > Leverage full Table component capabilities including sorting, filtering, pagination, and row actions
> > >
> > > > [card] Dynamic content
> > > >
> > > > Combine Collection's dynamic data handling with Table's structured presentation for flexible layouts
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product catalogs
> > > >
> > > > Display product information in table format within a collection of products
> > >
> > > > [card] Data dashboards
> > > >
> > > > Create dashboard views with multiple tables showing different data sets in collection items
> > >
> > > > [card] Report listings
> > > >
> > > > Show report summaries in table format within a collection of reports
> > >
> > > > [card] Comparison views
> > > >
> > > > Compare multiple entities side-by-side using tables within collection items
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Platform & infrastructure
>
> Backend optimizations, connector improvements, and platform stability enhancements.
>
> 🔌 [**Connector Topic Pattern**](#connector-topic-pattern) - Dedicated Kafka topic pattern for connectors\
> ⚙️ [**Kafka Configuration Alignment**](#kafka-configuration-alignment) - Unified Kafka property names across all services with backwards compatibility\
> ⚡ [**Advancing Performance**](#advancing-performance) - Fixed advancing partition issues and improved concurrency handling
>
> ### **Connector topic pattern**
>
> > [card] Connector topic pattern
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a dedicated Kafka topic pattern variable (`KAFKA_CONNECTORS_TOPIC_PATTERN`) for connectors, allowing custom topic patterns without affecting other platform components like document-plugin, data-search, and cms-core.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Shared topic pattern
> > > >
> > > > Connectors used the same `KAFKA_TOPIC_PATTERN` as other components, limiting customization
> > >
> > > > [card] Security concerns
> > > >
> > > > Connectors could write to all topics with the pattern `ai.flowx.engine.receive.*`
> >
> > > [tab] Solution
> > >
> > > **New Configuration:**
> > >
> > > ```yaml theme={"dark"}
> > > # Old configuration (shared with all components)
> > > KAFKA_TOPIC_PATTERN: ai.flowx.engine.receive.*
> > >
> > > # New configuration (dedicated for connectors)
> > > KAFKA_CONNECTORS_TOPIC_PATTERN: ro.uniflow.*
> > > ```
> > >
> > > **Benefits:**
> > >
> > > * Connectors can use custom topic patterns
> > > * Other components continue using the standard pattern
> > > * Improved security through topic isolation
> >
> > InfrastructureSelf-Managed
>
> ***
>
> ### **Kafka configuration alignment**
>
> > [card] Kafka configuration alignment
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 aligns Kafka configuration properties across all services (core-services and AI platform services) by introducing standardized property names while maintaining full backwards compatibility with existing configurations.
> >
> > > [tab] New Properties
> > >
> > > **Standardized Kafka Properties:**
> > >
> > > The following new environment variables are now available across all services:
> > >
> > > | Environment Variable | Description | Fallback Property |
> > > | - | - | - |
> > > | `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers | `SPRING_KAFKA_BOOTSTRAP_SERVERS` |
> > > | `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka communication | `SPRING_KAFKA_SECURITY_PROTOCOL` |
> > >
> > > > [!NOTE]
> > > >
> > > > The new properties take precedence over the legacy `SPRING_KAFKA_*` properties. If the new properties are not set, the system automatically falls back to the legacy properties, ensuring backwards compatibility.
> >
> > > [tab] Benefits
> > >
> > > > [card] Property alignment
> > > >
> > > > Consistent property names across core-services and AI platform services
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing configurations using `SPRING_KAFKA_*` properties continue to work without changes
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Unified configuration approach across all FlowX.AI services
> > >
> > > > [card] Migration flexibility
> > > >
> > > > Migrate to new properties at your own pace without breaking existing deployments
> > >
> > > > [!NOTE]
> > > >
> > > > This change was implemented in core-services and automatically applies to all services that use the shared Kafka configuration. No action is required for existing deployments, but you can optionally migrate to the new property names for consistency.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Advancing performance**
>
> > [card] Advancing performance
> >
> > FlowX.AI 5.4.0 includes significant fixes and improvements to the advancing mechanism, resolving issues with stalled events and improving concurrency handling.
> >
> > > [accordion] Stalled events fix
> > >
> > > Fixed issue where NEW entries in `advancing_partition` and `advancing_partition_event` tables would become stalled and never processed. This occurred when multiple events were generated for the same partition during parallel processing.
> >
> > > [accordion] Numeric overflow fix
> > >
> > > Fixed numeric overflow error when `advancing_partition_event_seq` sequence exceeded `Integer.MAX_VALUE`. Now correctly uses `getLong()` instead of `getInt()` for sequence values.
> >
> > > [accordion] Concurrency improvements
> > >
> > > * Fixed issue with multiple events to the same partition causing negative `count_queued_events`
> > > * Replaced trigger-based solution with SQL transactions for atomic updates
> > > * Improved handling of embedded subprocess completion under concurrent load
> >
> > > [accordion] Automated test stability
> > >
> > > Resolved data inconsistencies and business exceptions that were causing automated tests to fail consistently.
> >
> > PerformanceAll Deployments
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes across SaaS features, Designer, and backend services.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI and navigation fixes for Designer\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.4.0 resolves Designer issues to improve stability and user experience.
> >
> > ## Navigation & routing
> >
> > > [accordion] Navigation fixes
> > >
> > > * **Fixed sidebar display** - sidebar menu now shows when accessing pages via URL
> > > * **Fixed subprocess navigation** - resolved 403 when navigating to subprocesses
> > > * **Fixed back navigation** - resolved 403 when going back from UI Flows page
> > > * **Fixed audit log access** - resolved errors when viewing process instance audit logs
> > > * **Fixed version history** - "Open version in new tab" now works correctly
> >
> > > [accordion] UI improvements
> > >
> > > * **Fixed default locale display** - locale now correctly shown in Version settings
> > > * **Fixed substitution calls** - resolved errors when starting processes or accessing UI Flows
> >
> > Designer StabilityAll Deployments
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process engine
> >
> > > [accordion] Advancing & concurrency
> > >
> > > * **Fixed stalled advancing events** - NEW entries no longer get stuck in advancing tables
> > > * **Fixed numeric overflow** - resolved overflow when sequence exceeds Integer.MAX\_VALUE
> > > * **Fixed concurrent updates** - resolved stale data errors for embedded subprocess completion
> > > * **Fixed negative counter** - resolved issue with `count_queued_events` going negative
> >
> > ## AI platform
> >
> > > [accordion] AI integration fixes
> > >
> > > * **Fixed multi-agent streaming** - streaming now works correctly for multi-agent chat
> > > * **Fixed SSE event delivery** - events are delivered individually as they complete
> >
> > ## Integration Designer
> >
> > > [accordion] Workflow & data model
> > >
> > > * **Fixed file upload multipart** - only file name is sent in multipart body, not full path
> > > * **Fixed data model duplicates** - resolved duplicate entries in mongo properties\_paths
> >
> > Backend StabilityAll Deployments
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.4.0](./deployment-guidelines-v5.4).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.3.0 - no breaking changes for standard deployments
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.4
>
> ### SaaS features
>
> > [!NOTE]
> >
> > The SaaS multi-tenant features introduced in this release require additional infrastructure configuration for production deployments. Contact your FlowX.AI representative for guidance on enabling SaaS capabilities.


# Deployment guidelines v5.5.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/deployment-guidelines-v5.5

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.60.0** | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 |
| **admin** | **10.53.0** | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 |
| **designer** | **10.91.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **cms-core** | **10.35.0** | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **10.25.0** | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **10.27.0** | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **10.35.0** | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **10.35.0** | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **10.35.0** | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 |
| **data-search** | **10.25.0** | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **10.31.0** | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **10.27.0** | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 |
| **integration-designer** | **10.63.0** | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 |
| **application-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **data-sync** | **10.31.1** | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 |
| **authorization-system** | **10.42.1** | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **10.27.0** | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 |
| **email-gateway** | **10.24.0** | 10.9.0 | - | - | - | - |
| **organization-manager** | **10.19.2** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 |
| **Android renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 |
| **di-platform** | **10.2.6** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **knowledgebase** | **TBD** | - | - | - | - | - |
| **knowledgebase-rag** | **10.2.0** | - | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.2.0** | - | - | - | - | - |
| **mcp** | **10.2.0** | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.5.0 | Keycloak | 26+ |
| 5.5.0 | Kafka | 3.8 - 3.9 |
| 5.5.0 | PostgreSQL | 16 - 17 |
| 5.5.0 | Oracle Database | 21c, 23ai |
| 5.5.0 | MongoDB | 7 - 8 |
| 5.5.0 | Redis | 7.4 - 8.0 |
| 5.5.0 | Elasticsearch | 8 - 9 |
| 5.5.0 | Angular (Web SDK) | 20 |
| 5.5.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.5.0

### Key features and updates

> [card] Chat Component Enhancements
>
> New subcomponents (reasoning, error, suggestions), display modes, and mobile support

> [card] UI Flows Improvements
>
> Process renderer component, start workflow action, and on load events

> [card] Microsoft Outlook Integration
>
> Native MS Graph data source for reading and sending Outlook emails

> [card] Send Notification Action
>
> Send emails and reply to received emails directly from processes via SMTP

> [card] Knowledge Base v2
>
> Updated Knowledge Base with audit, resource management, and improved UI

> [card] User Management Updates
>
> Password policy, DISABLED status, resend invitations, workspace environment types

## Upgrading from v5.4.0

### Breaking changes

> [!WARNING]
>
> FlowX.AI 5.5.0 introduces a **breaking change** to the default authentication mechanism across most platform services. If you rely on the default `SECURITY_TYPE` value or opaque-token introspection, action is required before upgrading.

#### Authentication mechanism change

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. This reflects a shift from opaque-token introspection to JWT-based authentication as the default security mechanism.

**Removed environment variables:**

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

**Changed default values:**

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

**Migration steps:**

**1. Update SECURITY\_TYPE if explicitly set**

If you explicitly set `SECURITY_TYPE=oauth2` in your deployment configuration, update it to `jwt-public-key` or remove it to use the new default.

**2. Remove deprecated opaque-token variables**

Remove all `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_*` variables from your Helm values, environment configs, or deployment manifests.

**3. Update service account client IDs**

Service account client IDs now follow the `flowx-{service-name}-sa` pattern (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Update your Keycloak service account configurations accordingly.

**4. Configure the service account realm**

Add the `security.oauth2.sa-realm` property to your configuration if your service account realm differs from the default.

**5. Remove legacy OAuth2 client variables**

Remove `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENT_ID`, `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`, and `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_*` variables from your configuration.

***

### Key changes

* **Authentication**: Default `SECURITY_TYPE` changed from `oauth2` to `jwt-public-key` (breaking change — see above)
* **Organization Manager**: New microservice for organization and tenant management
* **Chat Component**: Enhanced with new subcomponents (reasoning, error, suggestions), display modes, and mobile support
* **UI Flows**: New process renderer component, start workflow action, and on load UI event
* **Microsoft Outlook**: New MS Graph data source for Outlook email integration
* **Send Notification**: New action type for sending/replying to emails via SMTP
* **Knowledge Base v2**: Updated UI, audit trail, and resource management
* **Container Apps**: Enhanced authentication flow and landing page
* **File Upload**: Improved progress indicators, drag and drop, and large file support
* **File Encrypt/Decrypt**: New document plugin actions for file encryption and decryption
* **User Management**: Password policy updates, DISABLED status, resend invitations, workspace environment type
* **Process Variables Compare**: Monaco diff editor for comparing variable values
* **New Kafka topics**: Multiple new topics added across document-plugin, integration-designer, admin, application-manager, email-gateway, authorization-system, and notification-plugin

***

### New microservice: Organization Manager

> [!NOTE]
>
> **Available starting with FlowX.AI 5.5.0**
>
> The Organization Manager is a new microservice responsible for organization and tenant management, including user registration, organization lifecycle, and platform component health monitoring.

**Infrastructure requirements:**

| Dependency | Details |
| - | - |
| PostgreSQL | Dedicated database for organization data |
| Redis | Caching and session management |
| Kafka | Event publishing (organization events topic) |
| Keycloak/IAM | Authentication and realm management |
| SpiceDB | Authorization via CAS lib |

> [card] [Organization Manager Setup](/5.1/setup-guides/organization-manager-setup)
>
> Complete setup and configuration guide for the Organization Manager microservice

***

### New Kafka topics

FlowX.AI 5.5.0 introduces new Kafka topics across multiple services.

#### Document-plugin Kafka topics

New topics for file encryption, decryption, bulk document persistence, and UI Flow session document persistence operations.

**Input topics (document-plugin consumes from these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Triggers file decryption operations |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Triggers file encryption operations |
| `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Triggers bulk document persistence operations |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway |

**Output topics (document-plugin publishes to these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Results from file decryption operations |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Results from file encryption operations |
| `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Results from bulk document persistence |
| `ai.flowx.eventsgateway.receive.document.v1` | Document upload progress notifications sent to events-gateway for SSE delivery |

#### Integration-designer Kafka topics

New topics for integration-designer in 5.5.0. Integration-designer now participates in the application sync mechanism for system and workflow resources.

> [!NOTE]
>
> The `sync.out.v1` and `correction-after-app-operation.response.v1` topics already exist since 5.1.x (used by admin). In 5.5.0, integration-designer becomes an additional producer on these shared response topics.

**New topics:**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync requests | Inbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System resource correction requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow resource correction requests | Inbound |
| `ai.flowx.build.runtime-data.v1` | Build runtime data | Outbound |
| `ai.flowx.license.usage.v1` | License usage tracking | Outbound |

**Existing topics (new producer in 5.5.0):**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.out.v1` | Sync operation responses | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | Correction operation responses | Outbound |

#### Admin Kafka topics

New topics for UI flow synchronization and correction operations in 5.5.0.

> [!NOTE]
>
> The `sync.process.in.v1`, `sync.business-rule.in.v1`, `sync.reusable-template.in.v1`, `sync.out.v1`, and `correction-after-app-operation` topics for process, business-rule, and reusable-template already exist since 5.1.x. Only the UI flow topics below are new in 5.5.0.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Inbound |

#### Application-manager Kafka topics

New outbound topics for resource synchronization and correction of system, workflow, and UI flow resources in 5.5.0.

> [!NOTE]
>
> Application-manager already produces sync and correction topics for process, business-rule, and reusable-template since 5.1.x. The topics below extend the same mechanism to system, workflow, and UI flow resources.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync | Outbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync | Outbound |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow resource sync | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Outbound |

#### Email-gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.save.audit.v1` | Audit event logging | Outbound |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Trigger process start from email events | Outbound |

#### Authorization-system Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.organization.events.v1` | Organization lifecycle events | Outbound |

#### Notification-plugin Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.resources-usages.refresh.v1` | Resource usages refresh events | Inbound |
| `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` | Sub-resource validation responses | Outbound |
| `ai.flowx.application-version.resources-usages.operations.bulk.v1` | Bulk resource usage operations | Outbound |

> [!NOTE]
>
> These topics are automatically created if your Kafka cluster has auto-topic creation enabled. For production environments, it is recommended to create them manually with appropriate partition counts and replication factors.

***

### New environment variables

#### Platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

#### Document-plugin variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) | document-plugin |

> [!NOTE]
>
> This setting affects all file uploads handled by the document-plugin. Configure alongside the existing Spring multipart settings (`SPRING_SERVLET_MULTIPART_MAXFILESIZE`, `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`) for consistent upload limits. See [Documents Plugin Setup](/5.1/setup-guides/documents-plugin-setup#multipart-upload-configuration).

#### Authorization-system variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client. Required for new deployments. | ` ` (empty) | authorization-system |

> [!WARNING]
>
> **New deployments only**: If this variable is not set, the `flowx-platform-authenticate` Keycloak client will have no redirect URIs and OAuth2 login will fail. Set this to your Designer and app URLs (e.g., `https://designer.yourcompany.com/*,https://app.yourcompany.com/*`).
>
> Existing deployments upgrading to 5.5.0 are not affected — the Liquibase migration that uses this variable has already run.

> [card] [Authorization System Setup](/5.1/setup-guides/authorization-setup-guide#keycloak-redirect-uris)
>
> See the full redirect URI configuration details

#### Email-gateway variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` | email-gateway |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` | email-gateway |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL` | TTL for cached MS Graph client instances | `1d` | email-gateway |

> [!NOTE]
>
> For complete email-gateway configuration including database, Redis, and Kafka settings, see the [Email Gateway Setup](/5.9/setup-guides/email-gateway-setup) guide.

***

### Compatibility

* **Authentication**: Default `SECURITY_TYPE` changed to `jwt-public-key` — deployments using opaque-token introspection require migration (see [breaking changes](#authentication-mechanism-change))
* **Renderer Updates**: Web and mobile SDKs include new Chat component features and UI Flows enhancements
* **Database**: No schema changes required for this upgrade
* **Mobile Support**: Chat component now available on iOS and Android renderers
* **New Service**: Organization Manager requires PostgreSQL, Redis, Kafka, and Keycloak infrastructure

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/migration-overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!WARNING]
>
> FlowX.AI v5.5.0 introduces a **critical breaking change** to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

## What's changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (`oauth2`) to JWT-based authentication (`jwt-public-key`). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — **Organization Manager** — has been introduced for organization and tenant management.

## Who is affected

> [!WARNING]
>
> **All deployments** are affected by the authentication mechanism change. The default `SECURITY_TYPE` value has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services.
>
> If you explicitly set `SECURITY_TYPE=oauth2` or rely on opaque-token introspection, you **must** update your configuration before upgrading.

## Migration process

**1. Back up your configuration**

Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.

**2. Update Keycloak service accounts**

Update your Keycloak service account client IDs to follow the new `flowx-{service-name}-sa` naming pattern. See [Update Keycloak service accounts](#update-keycloak-service-accounts) for the full mapping.

**3. Update environment variables**

Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.

**4. Deploy Organization Manager**

If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.

**5. Deploy and verify**

Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

***

## Authentication mechanism change

### Overview

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. Opaque-token introspection has been **removed entirely**.

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

### Changed default values

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

***

## Update Keycloak service accounts

Service account client IDs now follow the `flowx-{service-name}-sa` pattern. Update your Keycloak configuration to match:

| Service | New Client ID |
| - | - |
| Admin | `flowx-admin-sa` |
| Process Engine | `flowx-process-engine-sa` |
| Integration Designer | `flowx-integration-designer-sa` |
| Authorization System | `flowx-authorization-system-sa` |
| Runtime Manager | `flowx-runtime-manager-sa` |
| Scheduler Core | `flowx-scheduler-core-sa` |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager | `flowx-organization-manager-sa` |
| License | `flowx-license-sa` |
| Email Gateway | `flowx-email-gateway-sa` |

> [!WARNING]
>
> Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

***

## New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the **Organization Manager** microservice for organization and tenant management, user registration, and platform component health monitoring.

**Infrastructure requirements:**

* PostgreSQL
* Redis
* Kafka
* Keycloak/IAM
* SpiceDB

For full setup instructions, see the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility** for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

## Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your `SECURITY_TYPE` and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

> [!NOTE]
>
> Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

***

## Additional resources

> [card] [Update Environment Variables](./update-environment-variables-5.5)
>
> Per-service environment variable changes for v5.5.0

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions and deployment instructions

> [card] [IAM Configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution)
>
> Keycloak setup and service account configuration

> [card] [Release Notes v5.5.0](../v5.5.0-february-2026)
>
> Full release notes for v5.5.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/update-environment-variables-5.5

Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!NOTE]
>
> This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"dark"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

> [tab] Before (v5.4)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "oauth2"
>
> # Service account client ID (example for admin service)
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"
>
> # Token URI using main realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
> ```

> [tab] After (v5.5)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "jwt-public-key"
>
> # Service account client ID follows flowx-{service-name}-sa pattern
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"
>
> # Token URI now uses separate sa-realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
> ```

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

***

## Document plugin

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

> [!NOTE]
>
> **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` |

***

## Additional resources

> [card] [Migration Overview](./migration-overview)
>
> Full migration guide with Keycloak and service account changes

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions, Kafka topics, and infrastructure requirements


# FlowX.AI 5.5.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/v5.5.0-february-2026

Enhanced Chat component, UI Flows improvements, Microsoft Outlook integration, container app authentication, and platform management updates.

> [!NOTE]
>
> FlowX.AI 5.5.0 introduces significant enhancements to the Chat component, UI Flows capabilities, email integrations, and platform management features including Knowledge Base v2, user management improvements, and new document processing capabilities.

![Data Source types in FlowX 5.5.0](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_type_selector_all.png)

**What's new?**

> [tab] AI Platform
>
> AI-powered features and document processing enhancements.
>
> 📄 [**Extract Data from File**](#extract-data-from-file) - Configurable document and image extraction with LLM, OCR, and text parsing strategies\
> 📚 [**Knowledge Base v2**](#knowledge-base-v2) - Updated Knowledge Base with audit, resource management, and improved UI
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 renames "Extract Text from Document" to **Extract Data from File** and adds configurable extraction strategies, image input support, and signature detection. Choose between LLM, OCR, or text parsing strategies based on your document types, accuracy requirements, and cost constraints.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Extraction strategies
> > > >
> > > > Choose between LLM Model, OCR Engine, or Text Parsing for optimal accuracy/cost balance
> > >
> > > > [card] Image support
> > > >
> > > > Process images (JPG, PNG, TIFF) in addition to documents — automatic PDF conversion
> > >
> > > > [card] Image extraction options
> > > >
> > > > Extract data from embedded images or generate image descriptions
> > >
> > > > [card] Signature detection
> > > >
> > > > Detect and locate signatures within documents (LLM and OCR modes)
> >
> > > [tab] Configuration
> > >
> > > **Extraction strategies:**
> > >
> > > | Strategy | Best for | Speed | Cost | Accuracy |
> > > | - | - | - | - | - |
> > > | LLM Model | Complex layouts, handwritten text | Slow | High | High |
> > > | OCR Engine | Scanned documents | Medium | Medium | Medium |
> > > | Text Parsing | Clean digital PDFs | Fast | Free | Low–Medium |
> > >
> > > **Image extraction options (LLM and OCR only):**
> > >
> > > | Option | Description |
> > > | - | - |
> > > | Image Description | Generates text descriptions of images |
> > > | Image Content | Extracts text and data from images |
> > >
> > > > [!TIP]
> > > >
> > > > A new [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) covers backend service configuration, deployment sizing, and cost optimization.
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Knowledge Base v2**
>
> > [card] [Knowledge Base v2](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 updates the Knowledge Base with a refreshed UI, audit capabilities, and improved resource management. Knowledge Base entries now support versioning and provide better traceability for AI-powered features.
> >
> > > [tab] Key Features
> > >
> > > > [card] Updated UI
> > > >
> > > > Refreshed Knowledge Base interface with improved navigation and search
> > >
> > > > [card] Audit trail
> > > >
> > > > Track changes to Knowledge Base entries with full audit history
> > >
> > > > [card] Resource management
> > > >
> > > > Improved management of Knowledge Base resources and documents
> > >
> > > > [card] Version tracking
> > > >
> > > > Version-aware Knowledge Base entries tied to app versions
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] UI Flows
>
> Enhanced UI Flows with new components, actions, and chat improvements.
>
> 💬 [**Chat Component Enhancements**](#chat-component-enhancements) - New subcomponents, display modes, and mobile support\
> 🧭 [**UI Flows Breadcrumbs**](#ui-flows-breadcrumbs) - Navigation breadcrumbs for UI Flows\
> 📄 [**Process Renderer Component**](#process-renderer-component) - Embed process renderers within UI Flows\
> 🚀 [**Start Workflow Action**](#start-workflow-action) - Start workflows directly from UI Flows\
> ⚡ [**On Load UI Event**](#on-load-ui-event) - Execute actions when UI Flows load
>
> ### **Chat component enhancements**
>
> > [card] [Chat component enhancements](/5.9/ai-platform/chat-component)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 significantly enhances the Chat component with new subcomponents for reasoning, error handling, and suggestions. The component now supports multiple display modes and is available on mobile platforms.
> >
> > > [tab] New Subcomponents
> > >
> > > > [card] Reasoning display
> > > >
> > > > Show AI reasoning and thought process to users for transparency
> > >
> > > > [card] Error handling
> > > >
> > > > Graceful error display with retry options and helpful messages
> > >
> > > > [card] Suggestions
> > > >
> > > > Display suggested responses or actions to guide user interactions
> >
> > > [tab] Display Modes
> > >
> > > **Available display modes:**
> > >
> > > | Mode | Description |
> > > | - | - |
> > > | **Full screen** | Chat occupies the entire screen (available since v5.4.0) |
> > > | **Sidebar** | Chat appears as a collapsible sidebar |
> > > | **Floating** | Chat appears as a floating widget |
> > > | **Embedded** | Chat embedded within a container component |
> >
> > > [tab] Mobile Support
> > >
> > > The Chat component is now fully supported on mobile platforms:
> > >
> > > > [card] iOS
> > > >
> > > > Native iOS renderer support with optimized touch interactions
> > >
> > > > [card] Android
> > > >
> > > > Native Android renderer support with material design integration
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **UI Flows breadcrumbs**
>
> > [card] [UI Flows breadcrumbs](/5.9/docs/building-blocks/ui-flows#breadcrumbs)
> >
> > FlowX.AI 5.5.0 enhances the breadcrumbs navigation component for UI Flows, providing users with clear context of their current location and enabling quick navigation to parent screens.
> >
> > > [card] Navigation path
> > >
> > > Display the full navigation path within UI Flows
> >
> > > [card] Click navigation
> > >
> > > Navigate to any parent screen by clicking breadcrumb items
> >
> > > [card] Theme configuration
> > >
> > > Customize breadcrumb appearance through Admin theme settings
> >
> > > [card] Responsive design
> > >
> > > Breadcrumbs adapt to different screen sizes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process renderer component**
>
> > [card] [Process renderer component](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > > [tab] Overview
> > >
> > > Embed process renderers directly within UI Flows using the new Process Renderer component. This enables hybrid applications that combine UI Flow navigation with traditional process-based screens.
> >
> > > [tab] Key Features
> > >
> > > > [card] Process embedding
> > > >
> > > > Embed any process renderer within a UI Flow screen
> > >
> > > > [card] Data passing
> > > >
> > > > Pass data between UI Flows and embedded processes
> > >
> > > > [card] Event handling
> > > >
> > > > Handle process events within the UI Flow context
> > >
> > > > [card] Consistent styling
> > > >
> > > > Maintain consistent styling and navigation across UI Flows and processes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Start workflow action**
>
> > [card] [Start workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action)
> >
> > > [tab] Overview
> > >
> > > Start integration workflows directly from UI Flows using the new Start Workflow action. This enables UI Flows to trigger backend workflows without requiring a full process instance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow selection
> > > >
> > > > Select from available integration workflows
> > >
> > > > [card] Input mapping
> > > >
> > > > Map UI Flow data to workflow input parameters
> > >
> > > > [card] Response handling
> > > >
> > > > Handle workflow responses and update UI state
> > >
> > > > [card] Error handling
> > > >
> > > > Configure error handling for failed workflow executions
> >
> > UI EnhancementAll Deployments
>
> ### **On load UI event**
>
> > [card] [On load UI event](/5.9/docs/building-blocks/ui-designer/event-handlers#triggers)
> >
> > > [tab] Overview
> > >
> > > Execute actions automatically when UI Flow screens load using the new On Load UI Event. This enables initialization logic, data fetching, and setup operations when users navigate to a screen.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic execution
> > > >
> > > > Actions execute automatically when the screen loads
> > >
> > > > [card] Data initialization
> > > >
> > > > Fetch and initialize data when entering a screen
> > >
> > > > [card] Conditional logic
> > > >
> > > > Execute different actions based on conditions
> > >
> > > > [card] Loading states
> > > >
> > > > Manage loading states during initialization
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Integrations
>
> Email integrations, document processing, and Integration Designer updates.
>
> 📬 [**Microsoft Outlook Data Source**](#microsoft-outlook-data-source) - Native MS Graph integration for reading and sending Outlook emails\
> 📧 [**Send Notification Action**](#send-notification-action) - Send emails and reply to received emails directly from processes\
> 🔌 [**Integration Designer Improvements**](#integration-designer-improvements) - Query parameter encoding, config param autocomplete\
> 🔑 [**Security Details in Workflows**](#security-details-in-workflows) - Access user security details in workflow scripts\
> 🔐 [**File Encrypt and Decrypt**](#file-encrypt-and-decrypt) - Encrypt and decrypt files in the Documents Plugin
>
> ### **Microsoft Outlook data source**
>
> > [card] Microsoft Outlook data source
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces a new **Microsoft Outlook** data source type that connects to Outlook mailboxes via the Microsoft Graph API. Unlike Email Trigger (IMAP) and Email Sender (SMTP), this provides a unified data source for both reading and sending emails through native Outlook integration with Azure AD authentication.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> > > >
> > > > See the complete Microsoft Outlook data source documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified read & send
> > > >
> > > > Single data source supports Read Emails, Send Emails, or Read & Send Emails scopes
> > >
> > > > [card] Azure AD authentication
> > > >
> > > > Service account authentication with Tenant ID, Client ID, and Client Secret
> > >
> > > > [card] Email monitoring
> > > >
> > > > Monitor Outlook mailboxes and trigger processes automatically when emails arrive
> > >
> > > > [card] Send & reply
> > > >
> > > > Send new emails or reply to received emails with conversation thread support
> > >
> > > > [card] Attachment validations
> > > >
> > > > Configure allowed file types, max file size, and max file count for incoming emails
> > >
> > > > [card] Test connection
> > > >
> > > > Validate Azure AD credentials and MS Graph permissions before saving
> >
> > > [tab] Configuration
> > >
> > > **Azure AD Authentication:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Tenant ID | Azure AD tenant ID |
> > > | Client ID | Azure AD application (client) ID |
> > > | Client Secret | Azure AD client secret |
> > >
> > > **Scope Options:**
> > >
> > > | Scope | MS Graph Permissions Required |
> > > | - | - |
> > > | Read Emails | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
> > > | Send Emails | `Mail.Send` or `Mail.ReadWrite` |
> > > | Read & Send Emails | One read + one send permission |
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Send Notification action**
>
> > [card] Send Notification action
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces the Send Notification action — a new action type that sends emails directly from process nodes through SMTP, without routing through Kafka. Combined with the new Email Sender data source type, it enables processes to send new emails or reply to emails that triggered the process via Email Trigger.
> > >
> > > > [!NOTE]
> > > >
> > > > Existing notification templates configured for Kafka-based sending continue to work without modification.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> > > >
> > > > See the complete Send Notification action documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Email Sender data source
> > > >
> > > > New SMTP data source type in Integration Designer with SSL/TLS smart port defaults
> > >
> > > > [card] Reply to emails
> > > >
> > > > Reply to emails that triggered the process, maintaining conversation threads
> > >
> > > > [card] Send new emails
> > > >
> > > > Send new outbound emails to specified recipients with CC/BCC support
> > >
> > > > [card] Notification template updates
> > > >
> > > > New Email Server and Email Sender fields for direct SMTP delivery
> > >
> > > > [card] Attachments
> > > >
> > > > Attach files using static paths or process variable keys
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing Kafka-based notification templates continue to work unchanged
> >
> > > [tab] Configuration
> > >
> > > **Email Sender Data Source (new):**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | SMTP (only option) |
> > > | Server Host | SMTP server hostname |
> > > | SSL/TLS | Enable secure connection (default: on) |
> > > | Port | `587` (SSL/TLS on) or `465` (SSL/TLS off) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > >
> > > **Send Notification Action:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Notification Template | Select a template with Predefined Email Connection |
> > > | Reply to received emails | Toggle on to reply to the email that triggered the process |
> > > | Reply to Email Header | Process variable with original email headers (reply mode) |
> > > | Receivers | Recipient email addresses or process variables |
> > > | CC/BCC Receivers | Optional CC and BCC recipients |
> > > | Language | Process variable key for template language |
> > > | Attachments | File path or process variable key |
> > > | Template Data | JSON key-value pairs for dynamic template content |
> > >
> > > > [!TIP]
> > > >
> > > > Available on Send Message Task, Task, and User Task nodes.
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Integration Designer improvements**
>
> > [card] Integration Designer improvements
> >
> > FlowX.AI 5.5.0 adds URL encoding options for REST endpoint query parameters, improved error handling for invalid REST responses, and configuration parameter autocomplete in data source forms.
> >
> > > [card] Query parameter encoding
> > >
> > > Configure whether query parameter values are URL-encoded automatically or sent as-is (for pre-encoded values)
> >
> > > [card] REST Content-Type handling
> > >
> > > Improved error handling when REST endpoints return responses with unexpected Content-Type headers
> >
> > > [card] Config param autocomplete
> > >
> > > Type `$` in data source configuration fields to autocomplete configuration parameters or create new ones inline
> >
> > > [!NOTE]
> > >
> > > See [Integration Designer - Query parameters](/5.1/docs/platform-deep-dive/integrations/integration-designer#query-parameters) for details.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Security details in workflows**
>
> > [card] Security details in workflows
> >
> > Workflow scripts can now access `additionalData.securityDetails` to retrieve the current user's identity. This works when a workflow is started from a **Chat component**, a **UI Flow**, or a **manual run**. Sub-workflows inherit security details from their parent.
> >
> > Unlike processes, where security details are grouped by swimlane and role, workflows use a simplified flat structure:
> >
> > ```json theme={"dark"}
> > {
> >   "securityDetails": {
> >     "username": "user@email.com",
> >     "identifier": "keycloak-subject-id",
> >     "details": {
> >       "firstName": "John",
> >       "lastName": "Snow",
> >       "email": "user@email.com"
> >     }
> >   }
> > }
> > ```
> >
> > > [!NOTE]
> > >
> > > See [Extracting additional data in business rules](/5.1/docs/building-blocks/actions/business-rule-action/extracting-additional-data) for full details and code examples for both processes and workflows.
> >
> > New FeatureAll Deployments
>
> ***
>
> ### **File encrypt and decrypt**
>
> > [card] [File encrypt and decrypt](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files)
> >
> > FlowX.AI 5.5.0 adds new file encryption and decryption actions to the Documents Plugin, enabling processes to encrypt files before storage and decrypt them for authorized access.
> >
> > > [card] File encryption
> > >
> > > Encrypt files using configurable encryption algorithms before storage
> >
> > > [card] File decryption
> > >
> > > Decrypt files for authorized access within process flows
> >
> > InfrastructureAll Deployments
>
> ***

> [tab] Platform & Management
>
> User management, workspace configuration, rendering, and platform improvements.
>
> 🔐 [**Container App Authentication**](#container-app-authentication) - Authentication flow and landing page improvements\
> 🔑 [**Password Policy Updates**](#password-policy-updates) - Updated password complexity requirements\
> 🚫 [**User status DISABLED**](#user-status-disabled) - New DISABLED status for user accounts\
> 📧 [**Resend User Invitation**](#resend-user-invitation) - Resend invitations for pending users\
> 🏷️ [**Workspace Environment Type**](#workspace-environment-type) - Sandbox, Staging, and Production labels for workspaces\
> 🏢 [**Organization ID Propagation**](#organization-id-propagation) - Enhanced multi-tenant isolation\
> ⚡ [**Rendering Runtime UX**](#rendering-runtime-ux) - Runtime UX improvements for rendering\
> 🔍 [**Process Variables Compare**](#process-variables-compare) - Monaco diff editor for process variable values\
> 📧 [**Failed Email Trigger Details Page**](#failed-email-trigger-details-page) - Dedicated details page for failed email triggers\
> 📐 [**Data Model Sidepanel**](#data-model-sidepanel) - Redesigned attribute settings, inline add, and path copy
>
> ### **Container app authentication**
>
> > [card] [Container app authentication](/5.9/docs/saas/container-app-authentication)
> >
> > > [tab] Overview
> > >
> > > Enhanced authentication flow and landing page for generic container applications. Configure authentication providers, customize login pages, and manage user sessions with improved security and user experience.
> >
> > > [tab] Key Features
> > >
> > > > [card] Authentication providers
> > > >
> > > > Support for multiple authentication providers
> > >
> > > > [card] Custom landing page
> > > >
> > > > Customize the landing page for unauthenticated users
> > >
> > > > [card] Session management
> > > >
> > > > Improved session handling and token refresh
> > >
> > > > [card] SSO integration
> > > >
> > > > Seamless single sign-on integration
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Password policy updates**
>
> > [card] [Password policy updates](/5.1/setup-guides/access-management/configuring-an-iam-solution#password-policy)
> >
> > FlowX.AI 5.5.0 updates the password policy with stricter complexity requirements for improved security.
> >
> > **New requirements:**
> >
> > | Rule | Value |
> > | - | - |
> > | Minimum length | 8 characters |
> > | Maximum length | 64 characters |
> > | Complexity | Must include uppercase, lowercase, number, and special character |
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **User status DISABLED**
>
> > [card] [User status DISABLED](/5.9/docs/saas/inviting-users#user-statuses)
> >
> > FlowX.AI 5.5.0 introduces a new **DISABLED** user status. Administrators can now enable or disable user accounts through the **Enable** and **Disable** actions in the user management menu, providing better control over user access without deleting accounts.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Resend user invitation**
>
> > [card] [Resend user invitation](/5.9/docs/saas/inviting-users#resending-invitations)
> >
> > FlowX.AI 5.5.0 adds the ability to resend invitations for users with a **Pending** status, ensuring users who missed or lost their initial invitation can still complete onboarding.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Workspace environment type**
>
> > [card] [Workspace environment type](/5.1/docs/projects/workspaces#workspace-environment-type)
> >
> > FlowX.AI 5.5.0 adds an **Environment Type** dropdown to workspace configuration, allowing administrators to label workspaces as **Sandbox**, **Staging**, or **Production**. This provides clearer context when working across multiple environments.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Organization ID propagation**
>
> > [card] Organization ID Propagation
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 enhances multi-tenant isolation by propagating organization ID across more runtime contexts. This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
> >
> > > [tab] Key Changes
> > >
> > > > [card] Scheduler execution
> > > >
> > > > Organization ID added to scheduled job context
> > >
> > > > [card] Event listeners
> > > >
> > > > Organization ID propagated to event handlers
> > >
> > > > [card] Process instances
> > > >
> > > > Organization ID captured from initiator
> > >
> > > > [card] Audit trail
> > > >
> > > > Enhanced audit logging with organization context
> >
> > InfrastructureSaaS
>
> ***
>
> ### **Rendering runtime UX**
>
> > [card] Rendering runtime UX
> >
> > FlowX.AI 5.5.0 includes various rendering runtime UX improvements for better performance and user experience.
> >
> > > [card] Loading states
> > >
> > > Improved loading state indicators and skeleton screens
> >
> > > [card] Transition animations
> > >
> > > Smoother transitions between screens and states
> >
> > > [card] Error boundaries
> > >
> > > Better error handling with graceful degradation
> >
> > > [card] Performance
> > >
> > > Optimized rendering performance for complex UIs
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process variables compare**
>
> > [card] [Process variables compare](/5.9/docs/projects/runtime/active-process/update-process-variables#compare-view)
> >
> > FlowX.AI 5.5.0 introduces a Monaco diff editor for comparing process variable values, making it easier to identify changes between versions or states.
> >
> > > [card] Diff editor
> > >
> > > Side-by-side comparison of process variable values using Monaco diff editor
> >
> > > [card] Version comparison
> > >
> > > Compare variable values across different process versions
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Failed email trigger details page**
>
> > [card] [Failed email trigger details page](/5.9/docs/platform-deep-dive/integrations/email-trigger#failed-trigger-details-page)
> >
> > FlowX.AI 5.5.0 adds a dedicated details page for failed email triggers, providing better visibility into email processing failures and enabling faster troubleshooting.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Data Model sidepanel**
>
> > [card] Data Model sidepanel
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 redesigns the Data Model editing experience with a new attribute settings side panel, inline add-attribute buttons, and attribute path display. These improvements make it faster to create, configure, and reference data model attributes without switching between menus.
> > >
> > > > [card] [Process Data Model](/5.1/docs/building-blocks/process/data-model#data-model-interface)
> > > >
> > > > See the updated Process Data Model documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Attribute settings side panel
> > > >
> > > > Select any attribute to open a settings panel with type, validations, sensitive data, and reporting options
> > >
> > > > [card] Inline add attribute
> > > >
> > > > Add attributes directly on each data type — button shows on hover after the first attribute
> > >
> > > > [card] Attribute path copy
> > > >
> > > > View and copy the full key path for any attribute for use in business rules and UI bindings
> > >
> > > > [card] Selection highlights
> > > >
> > > > Selecting a data type or connector highlights its location on the canvas
> > >
> > > > [card] Default minimized panel
> > > >
> > > > The Data Types panel starts minimized by default for a cleaner canvas view
> > >
> > > > [card] Confirmation toasts
> > > >
> > > > Success notifications when adding new data types
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### Additional improvements
>
> * **Workflow logs milliseconds** — Workflow execution logs now display timestamps with millisecond precision
> * **Single select in table edit** — SDK enhancement for single-select dropdowns within editable table cells. See [Table component](/5.1/docs/building-blocks/ui-designer/ui-component-types/table#editable-rows)
> * **UI Flows action name optional** — Action names in UI Flows are now optional, reducing configuration overhead
> * **Data mappers editable JSON testing** — Improved JSON testing experience in data mappers with editable input fields
> * **Solutions page load optimization** — Solutions page now loads only projects, improving performance for container apps
> * **Security patches** — General security improvements across platform services

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.5.0](./deployment-guidelines-v5.5).
>
> ### Compatibility
>
> > [!WARNING]
> >
> > **Breaking change:** The default `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 services. Opaque-token introspection has been removed. See the [Deployment Guidelines](./deployment-guidelines-v5.5#breaking-changes) for migration steps.
>
> > [card] Upgrade path
> >
> > Upgrade from v5.4.0 — requires authentication mechanism migration (`SECURITY_TYPE` change)
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.5


# Deployment guidelines v5.6.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/deployment-guidelines-v5.6

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.77.0** | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 |
| **admin** | **10.66.0** | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 |
| **designer** | **10.127.3** | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **cms-core** | **10.43.0** | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 |
| **scheduler-core** | **10.31.0** | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 |
| **events-gateway** | **10.33.1** | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 |
| **notification-plugin** | **10.42.1** | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 |
| **document-plugin** | **10.46.0** | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 |
| **task-management-plugin** | **10.41.1** | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 |
| **data-search** | **10.30.1** | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 |
| **audit-core** | **10.40.0** | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 |
| **advancing-controller** | **10.33.1** | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 |
| **integration-designer** | **10.84.0** | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 |
| **application-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **runtime-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **data-sync** | **10.38.0** | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 |
| **authorization-system** | **10.51.0** | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 |
| **nosql-db-runner** | **10.34.0** | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 |
| **email-gateway** | **10.32.1** | 10.24.0 | 10.9.0 | - | - | - |
| **organization-manager** | **10.26.1** | 10.19.2 | - | - | - | - |
| **webhook-gateway** | **10.1.1** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **iOS renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 |
| **Android renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 |

### Plugins

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.2.3** | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 |
| **di-platform** | **10.3.0** | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 |
| **ai-platform-ai-developer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-connected-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-knowledge-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agents** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-conversations** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-models** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-tenants** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-planner** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-analyst** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-designer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agent-builder** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-binaries** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **knowledgebase** | **10.6.0** | TBD | - | - | - | - |
| **knowledgebase-rag** | **10.6.0** | 10.2.0 | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.0** | 10.2.0 | - | - | - | - |
| **mcp** | **10.6.0** | 10.2.0 | - | - | - | - |
| **doc-converter** | **10.2.2** | - | - | - | - | - |
| **doc-parser** | **10.5.1** | - | - | - | - | - |

> [!NOTE]
>
> **New in 5.6.0:** `webhook-gateway` is a new microservice for processing incoming webhooks. It handles webhook event ingestion and routing to process instances.

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.6.0 | Keycloak | 26+ |
| 5.6.0 | Kafka | 3.8 - 3.9 |
| 5.6.0 | PostgreSQL | 16 - 17 |
| 5.6.0 | Oracle Database | 21c, 23ai |
| 5.6.0 | MongoDB | 7 - 8 |
| 5.6.0 | Redis | 7.4 - 8.0 |
| 5.6.0 | Angular (Web SDK) | 20 |
| 5.6.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.6.0

### Key features and updates

> [card] Chat Driven Workflows
>
> Multi-turn AI conversations with session memory and intent classification

> [card] Incoming Webhooks
>
> Trigger processes from external HTTP POST requests via the new webhook-gateway service

> [card] Web Page Extractor
>
> Collect readable content from web page URLs with crawling and link following

> [card] Proxy Server Connections
>
> Route integration traffic through HTTP/HTTPS proxy servers

> [card] UI Flow Route Management
>
> Query parameters, route maps, and breadcrumb navigation for UI Flows

> [card] MCP Authentication
>
> BEARER and BASIC auth for MCP server connections

## Upgrading from v5.5.0

### Breaking changes

#### WorkspaceCreatedEvent ownership change

> [!WARNING]
>
> The `WorkspaceCreatedEvent` Kafka topic ownership has moved from `authorization-system` to `organization-manager`.

**What changed:**

* `organization-manager` now produces `WorkspaceCreatedEvent` messages
* `authorization-system` no longer produces these events
* Update your Kafka topic ACLs if you manage topic-level permissions

***

#### gRPC thread pool configuration

> [!WARNING]
>
> The default gRPC client thread pool sizes in AI Platform have been updated. Review your deployment configuration if you have custom thread pool settings.

***

### New environment variables

#### Integration Designer

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_WEBHOOKS_BASE_URL` | Base URL for webhook-gateway service communication | `http://webhook-gateway:80` | integration-designer |
| `FLOWX_WEB_CRAWLER_BASE_URL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80` | integration-designer |

#### NoSQL DB Runner

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100` | nosql-db-runner |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL` | Time-to-live for cached external MongoDB connections | `1d` | nosql-db-runner |

#### Process Engine

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts for failed operations | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Base delay between retries (ms) | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum delay between retries (ms) | `200` | process-engine |

#### Authorization System

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD` | Initial password for default realm admin user | *(none)* | authorization-system |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY` | Force password change on first login | `true` | authorization-system |

#### Application Manager

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_RESOURCE_ID_FIELD` | Resource ID field for proxy connection merge | `resourceId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_ID_FIELDS` | Flatten map ID fields for proxy connection merge | `resourceId, name` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection flatten map | `authorization.configuration` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_COMPARE_REMOVED_JSON_PATHS` | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_CONFLICT_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection conflict detection | `resourceId, resourceDefinitionId` | application-manager |

#### Data Search

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | data-search |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | data-search |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | data-search |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | data-search |

#### Email Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | email-gateway |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | email-gateway |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | email-gateway |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | email-gateway |

> [!NOTE]
>
> The SpiceDB and CAS client variables for `data-search` and `email-gateway` are required for authorization integration. These services now use the same SpiceDB-based authorization as other platform services.

#### Webhook Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for webhook registrations database | `jdbc:postgresql://postgresql:5432/webhook_gateway` | webhook-gateway |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` | webhook-gateway |
| `SPRING_DATASOURCE_PASSWORD` | Database password | *(required)* | webhook-gateway |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | OAuth2/OIDC server base URL | — | webhook-gateway |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | — | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account client ID | `flowx-webhook-gateway-sa` | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account client secret | *(required)* | webhook-gateway |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Kafka topic for process start events | `ai.flowx.core.trigger.start-for-event.process.v1` | webhook-gateway |

> [!NOTE]
>
> `webhook-gateway` is a **new microservice** in 5.6.0. It requires its own PostgreSQL database (`webhook_gateway`), Kafka access, Keycloak service account (`flowx-webhook-gateway-sa`), and SpiceDB connectivity.

***

### New Kafka topics

#### Document Plugin

New topic for UI Flow session document persistence.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway | Inbound |
| `ai.flowx.eventsgateway.receive.document.v1` | Document events sent to events-gateway for SSE delivery | Outbound |

#### Webhook Gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Triggers process starts from incoming webhook events | Outbound |

> [!NOTE]
>
> The Webhook Gateway is a **producer-only** service — it receives HTTP webhook requests and publishes process start events to Kafka. It does not consume from any Kafka topics.

#### UI flow session variable updates

New topic for propagating document upload results and workflow completion results to the process-engine, which updates UI flow session variables.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | UI flow session variable updates after document upload or workflow completion | Inbound (process-engine) / Outbound (document-plugin, integration-designer) |

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | process-engine |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Consumer group ID for UI flow updates | `ui-flow-update` | process-engine |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of consumer threads for UI flow updates | `6` | process-engine |

***

### Compatibility

* **SpiceDB**: Now required for `data-search` and `email-gateway` in addition to existing services
* **Renderer Updates**: Web and mobile SDKs include route management, start parameters, enum label display, and chat enhancements
* **Database**: The `start_params` column on `ui_flow_session` table has been renamed to `variables` (auto-migrated via Liquibase). The column now stores all session variables, including start parameters and updates from document uploads and workflow completions

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026

Conversational AI with memory and intent routing, incoming webhooks, proxy connections, unmanaged MongoDB, UI Flow session variables, chat history, and 28 bug fixes.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html)

FlowX.AI 5.6.0 brings **conversational AI** to your apps. Build multi-turn chat experiences where agents remember context, classify user intent, and navigate users to the right screen — all within a single workflow. On the integration side, **incoming webhooks** let external systems start processes via HTTP, **proxy connections** route traffic through intermediary servers, and **unmanaged MongoDB** connects FlowX to your existing database infrastructure. The UI layer gains **session variables**, **route management**, **chat history**, and **suggested prompts** for richer end-user experiences.

> [card] [For AI builders](#conversational-workflows)
>
> Chat Driven workflows, session memory, intent routing, and context retrieval

> [card] [For integrators](#incoming-webhooks)
>
> Incoming webhooks, proxy connections, unmanaged MongoDB, and base64 certificates

> [card] [For UI developers](#ui-flow-session-variables)
>
> Session variables, route management, chat history, suggested prompts, and new UI events

### What changed since 5.5.0

| 5.5.0 | 5.6.0 |
| - | - |
| Output Focused workflows only | + **Chat Driven** workflows with multi-turn memory |
| No event-driven process starts from external systems | **Incoming webhooks** with API key auth |
| FlowX-managed MongoDB only | + **Unmanaged MongoDB** — bring your own database |
| No conversation persistence | **Chat History** — browse and resume past sessions |
| Static chat empty state | **Suggested Prompts** — guide users with one-click starters |
| Certificate file paths only | **Base64 certificates** — paste content directly, no file mounts |
| No cross-page data in UI Flows | **Session variables** — persist data across pages and workflows |

***

**What's new?**

> [tab] AI Platform
>
> Build complete conversational AI pipelines — from understanding what the user wants, to retrieving the right context, to navigating them to the right screen.
>
> 💬 [**Conversational Workflows**](#conversational-workflows) - New Chat Driven workflow type for multi-turn conversations\
> 🧠 [**Memory Capabilities**](#memory-capabilities) - Automatic session memory with summarization across turns\
> 🎯 [**Intent Classification node**](#intent-classification-node) - Classify user messages and route to the right branch in one step\
> 🧭 [**Navigate in UI Flow**](#navigate-in-ui-flow) - Let the AI open forms and screens with contextual data\
> 🔍 [**Context Retrieval node**](#context-retrieval-node) - RAG search against Knowledge Bases without calling an LLM\
> 📄 [**Extract Data from File**](#extract-data-from-file) - Three extraction methods, image support, and signature detection\
> 🌐 [**Web Page Extractor**](#web-page-extractor) - Crawl web pages and extract readable content for AI processing
>
> See also: [Chat History](#chat-history), [Suggested Prompts](#chat-suggested-prompts), and [Markdown in chat](#markdown-in-chat-messages) in the **UI & Designer** tab.
>
> ### **Conversational Workflows**
>
> > [card] Conversational Workflows
> >
> > > [tab] Overview
> > >
> > > Chat Driven workflows are a specialized workflow type for multi-turn chat interactions. Unlike Output Focused workflows that process structured input/output, Chat Driven workflows manage ongoing dialogue — handling message exchange, session memory, and response routing through a dedicated Start node layout (Chat Session ID + User Message) and Custom Agent nodes with direct chat reply capability.
> > >
> > > ![Conversational workflow with Custom Agent configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_config.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> > > >
> > > > See the complete Conversational Workflows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multi-turn conversations
> > > >
> > > > Support for back-and-forth conversations with persistent context
> > >
> > > > [card] Intent routing
> > > >
> > > > Automatically classify user messages and route to appropriate workflow branches
> > >
> > > > [card] Session memory
> > > >
> > > > Built-in session memory with automatic summarization across conversation turns
> > >
> > > > [card] Chat UI components
> > > >
> > > > Dedicated chat component with error handling and shared state management
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Memory Capabilities**
>
> > [card] Memory Capabilities
> >
> > > [tab] Overview
> > >
> > > Conversational workflows include built-in session memory that automatically persists and retrieves conversation history. On each message, the system retrieves the last 3 turns of raw messages plus a summary of earlier exchanges, injecting them into the AI node's system prompt for context-aware responses.
> > >
> > > ![Memory tab showing conversation summary and history](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> > > >
> > > > See the complete Memory Capabilities documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic retrieval
> > > >
> > > > Last 3 turns + summary of earlier exchanges retrieved on each message via sessionId
> > >
> > > > [card] Smart summarization
> > > >
> > > > Older conversation history is automatically summarized to fit within context limits
> > >
> > > > [card] Per-node control
> > > >
> > > > Turn on memory per Custom Agent node with the **Use memory** toggle
> > >
> > > > [card] Memory tab in console
> > > >
> > > > View retrieved memory (raw turns + summary) in the workflow console log
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Intent Classification node**
>
> > [card] Intent Classification Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that combines AI-powered message classification with workflow branching in a single step. Define up to 10 intents with natural language descriptions, and the node classifies user messages and routes to the matching branch automatically — replacing the previous TEXT\_UNDERSTANDING + Condition two-node pattern.
> > >
> > > ![Intent Classification node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intent_classification_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> > > >
> > > > See the complete Intent Classification documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] AI + routing in one node
> > > >
> > > > Combines LLM classification and conditional branching — no separate Condition node needed
> > >
> > > > [card] Natural language conditions
> > > >
> > > > Define intents as plain-text descriptions instead of code expressions
> > >
> > > > [card] Conversation memory
> > > >
> > > > Optionally use past conversation context for more accurate classification
> > >
> > > > [card] Built-in fallback
> > > >
> > > > Automatic "If No Intent Matches" branch handles unrecognized inputs
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Navigate in UI Flow**
>
> > [card] Navigate in UI Flow
> >
> > > [tab] Overview
> > >
> > > A new workflow node exclusive to **Chat Driven** (conversational) workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — for example, the AI says *"Let me open your account details"* and the user sees a pre-filled form with data from the conversation.
> > >
> > > ![Navigate in UI Flow node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node)
> > > >
> > > > See the Navigate in UI Flow section in Conversational Workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Conversational context
> > > >
> > > > Navigate users to UI screens directly from a Chat Driven workflow conversation
> > >
> > > > [card] Dynamic parameters
> > > >
> > > > Pass workflow data to the destination screen using `${expression}` syntax
> > >
> > > > [card] Destination picker
> > > >
> > > > Select from the UI Flow's navigation tree with auto-populated query parameters
> > >
> > > > [card] Chat Driven only
> > > >
> > > > Available exclusively in the Actions category of conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval node**
>
> > [card] Context Retrieval Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that performs RAG (Retrieval-Augmented Generation) searches against Knowledge Bases without calling an LLM. Returns raw chunks with relevance scores and metadata, giving you full control over downstream processing. Supports hybrid, semantic, and keyword search with configurable re-ranking and metadata filters.
> > >
> > > Use Context Retrieval when you need to inspect, filter, or transform chunks before passing them to an LLM — for example, checking relevance scores before generating a response. For all-in-one RAG, use a Custom Agent node with a Knowledge Base attached instead.
> > >
> > > ![Context Retrieval node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the complete Context Retrieval documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] No LLM required
> > > >
> > > > Retrieves chunks directly — no AI generation step, lower latency and cost
> > >
> > > > [card] Multiple search types
> > > >
> > > > Hybrid, semantic, or keyword search with configurable relevance thresholds
> > >
> > > > [card] Metadata filters
> > > >
> > > > Filter chunks by user-defined metadata for scoped retrieval
> > >
> > > > [card] Re-ranking
> > > >
> > > > Optional re-ranking for improved result ordering
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > The workflow node formerly known as "Extract Text from Document" has been renamed to **Extract Data from File** and gained three new configurable settings: **Extraction Method** (LLM Model, OCR Engine, or Text Parsing), **Image Extraction** (Image Description or Image Contents), and **Detect Signatures**. The node now also accepts image files (JPG, PNG, TIFF) in addition to documents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Three extraction methods
> > > >
> > > > Choose between LLM Model (AI vision), OCR Engine (scanned docs), or Text Parsing (digital PDFs) per use case
> > >
> > > > [card] Image support
> > > >
> > > > Process JPG, PNG, and TIFF files alongside PDF, DOCX, XLSX, and PPTX
> > >
> > > > [card] Signature detection
> > > >
> > > > Identify signature areas within documents when using LLM or OCR extraction
> > >
> > > > [card] Moved to Tools category
> > > >
> > > > The node is now in the **Tools** category in the workflow node palette
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor**
>
> > [card] Web Page Extractor
> >
> > > [tab] Overview
> > >
> > > A new workflow node in the **Tools** category that collects readable content from web page URLs. Crawl documentation sites to build a Knowledge Base, scrape product pages for competitive analysis, or extract terms and conditions for compliance review. Supports static URL lists or dynamic URL generation, configurable crawling depth with link following, PDF extraction from linked documents, and adjustable scrape speed presets.
> > >
> > > ![Web Page Extractor node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> > > >
> > > > See the complete Web Page Extractor documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Static or dynamic URLs
> > > >
> > > > Provide a fixed list of up to 20 URLs or generate them dynamically from workflow data
> > >
> > > > [card] Link following
> > > >
> > > > Follow links on pages up to a configurable depth (0–10 levels)
> > >
> > > > [card] PDF processing
> > > >
> > > > Extract content from PDF files linked on crawled pages
> > >
> > > > [card] Speed presets
> > > >
> > > > Choose Slow, Moderate, Fast, or Custom with manual rate limit and concurrency
> >
> > All Deployments

> [tab] Integrations
>
> Connect FlowX to more systems — trigger processes from external events, route traffic through proxies, and query your own MongoDB databases.
>
> 🔗 [**Incoming Webhooks**](#incoming-webhooks) - Trigger processes from external HTTP POST requests\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Route integration traffic through proxy servers\
> 🗄️ [**Unmanaged MongoDB Datasource**](#unmanaged-mongodb-datasource) - Connect to externally managed MongoDB instances\
> 📧 [**Email Trigger Enhancements**](#email-trigger-enhancements) - Resource management, reply-to, and mock email testing\
> 🔐 [**MCP Authentication**](#mcp-authentication) - BEARER and BASIC auth support for MCP server connections\
> 📜 [**Base64 Certificate Support**](#base64-certificate-support) - Provide certificates as base64-encoded strings instead of file paths\
> 📊 [**CSV/Excel to JSON Conversion**](#csv/excel-to-json-conversion) - Download CSV and Excel files as structured JSON on the fly
>
> ### **Incoming Webhooks**
>
> > [card] Incoming Webhooks
> >
> > > [tab] Overview
> > >
> > > A new data source type and microservice (`webhook-gateway`) that allows external systems to trigger FlowX processes via HTTP POST requests. Create a Webhook data source in Integration Designer, connect it to a Message Start Event in your process, and FlowX generates a unique URL with API key authentication. When external systems POST to this URL, a process instance starts automatically with the webhook payload and headers.
> > >
> > > ![Active webhook trigger in Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)
> > >
> > > > [!NOTE]
> > > >
> > > > Requires deploying the new `webhook-gateway` microservice. See [Deployment Guidelines](./deployment-guidelines-v5.6) for configuration.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> > > >
> > > > See the complete Incoming Webhooks documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] API key authentication
> > > >
> > > > Each webhook gets a unique, cryptographically secure API key for authentication
> > >
> > > > [card] JSON payload forwarding
> > > >
> > > > Webhook body and headers are forwarded to the process instance as variables
> > >
> > > > [card] Manage Triggers integration
> > > >
> > > > Activate, deactivate, and monitor webhooks from the Manage Triggers UI
> > >
> > > > [card] API key regeneration
> > > >
> > > > Regenerate API keys without recreating the webhook configuration
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Proxy Server Connections**
>
> > [card] Proxy Server Connections
> >
> > > [tab] Overview
> > >
> > > Create reusable proxy connections in Integration Designer and attach them to RESTful System data sources. Route outbound API traffic through HTTP or HTTPS proxy servers for environments that require intermediary routing for security or compliance.
> > >
> > > ![Proxy Connection configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> > > >
> > > > See the complete Proxy Connections documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] HTTP and HTTPS proxies
> > > >
> > > > Configure HTTP or HTTPS proxy servers with optional basic authentication
> > >
> > > > [card] Reusable connections
> > > >
> > > > Create a proxy once and attach it to multiple RESTful System data sources
> > >
> > > > [card] Test connectivity
> > > >
> > > > Validate proxy configuration before saving with the built-in test function
> > >
> > > > [card] Config parameter support
> > > >
> > > > Use `${param}` syntax in host and port fields for environment-specific values
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Unmanaged MongoDB Datasource**
>
> > [card] Unmanaged MongoDB Datasource
> >
> > > [tab] Overview
> > >
> > > Connect to externally managed MongoDB instances as a data source in FlowX. Unlike the built-in FlowX Database (which provisions and manages MongoDB collections automatically), Unmanaged MongoDB connects to databases and collections you control — with the same CRUD operations, connection discovery, and configurable connection pooling. Requires MongoDB 6.0 or later.
> > >
> > > ![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> > > >
> > > > See the complete Unmanaged MongoDB documentation.
> >
> > All Deployments
>
> ***
>
> ### **Email Trigger Enhancements**
>
> > [card] Email Trigger Enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.6.0 enhances the Email Trigger with resource management capabilities, reply-to-email support, process instance tracking for email-triggered processes, and mock email testing for development.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Resource management
> > > >
> > > > Manage email trigger resources with proper lifecycle controls
> > >
> > > > [card] Reply-to-email
> > > >
> > > > Support for reply-to patterns in email-triggered workflows
> > >
> > > > [card] Process instances
> > > >
> > > > View and track process instances created from email triggers
> > >
> > > > [card] Mock email testing
> > > >
> > > > Test email-triggered processes with mock email content during development
> >
> > All Deployments
>
> ***
>
> ### **MCP Authentication**
>
> > [card] MCP Authentication
> >
> > > [tab] Overview
> > >
> > > MCP server connections now support **BEARER** and **BASIC** authentication methods. Configure auth credentials when adding an MCP data source to connect to secured MCP servers.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source)
> > > >
> > > > See the Adding MCP Data Source documentation.
> >
> > All Deployments
>
> ***
>
> ### **Base64 Certificate Support**
>
> > [card] Base64 Certificate Support
> >
> > > [tab] Overview
> > >
> > > RESTful system data sources now support providing keystore and truststore content as **base64-encoded strings** instead of file paths. A new "Certificate type" selector lets you choose between Base64 (default for new configurations) and Path (existing behavior). Additionally, keystore and truststore passwords now support `${configParam}` placeholder syntax for dynamic per-environment resolution.
> > >
> > > ![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#certificates)
> > > >
> > > > See the Integration Designer certificates documentation.
> >
> > All Deployments
>
> ***
>
> ### **CSV/Excel to JSON Conversion**
>
> > [card] CSV/Excel to JSON Conversion
> >
> > > [tab] Overview
> > >
> > > Download CSV, XLS, or XLSX files as structured JSON directly from the file download endpoints. The conversion happens on the fly using the `Accept: application/json` header — no new files are created in storage. Supports two output formats: an array of objects (one per row) or a columnar structure.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats#csv/excel-to-json-conversion)
> > > >
> > > > See the Document Conversion documentation.
> >
> > All Deployments

> [tab] UI & Designer
>
> Richer end-user experiences with session state, chat history, and navigation — plus Designer productivity improvements.
>
> 🗺️ [**UI Flow Route Management**](#ui-flow-route-management) - Configure routes, query parameters, and navigation in UI Flows\
> ▶️ [**UI Flow Start Parameters**](#ui-flow-start-parameters) - Pass parameters when starting UI Flows\
> 💾 [**UI Flow Session Variables**](#ui-flow-session-variables) - Persist data across pages from workflows and file uploads\
> 📋 [**Chat History**](#chat-history) - Browse and resume past chat conversations\
> 💡 [**Chat Suggested Prompts**](#chat-suggested-prompts) - Pre-configured prompt suggestions in chat empty state\
> 🖱️ [**onClick UI events**](#onclick-ui-events) - Client-side data updates on Button and Collection Prototype clicks\
> ✨ [**Monaco Editor Autocomplete**](#monaco-editor-autocomplete) - Autocomplete from config params in code editors\
> 📊 [**KB query results in workflow console**](#kb-query-results-in-workflow-console) - View retrieved chunks and relevance scores during workflow runs\
> 📎 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Upload multiple files simultaneously\
> ❌ [**DISMISS UI action**](#dismiss-ui-action) - Dismiss modals automatically after Start Workflow completes\
> 🎨 [**Process Variables UX**](#process-variables-ux-improvements) - UI/UX improvements for updating process variables\
> 🏷️ [**Enum label display**](#enum-label-display) - Show enum labels instead of codes in text components\
> 📬 [**Notification template usages**](#notification-template-usages) - See where notification templates are used\
> 📐 [**Side Panel in Data Model**](#side-panel-in-data-model) - Improved data model navigation with side panel\
> 👁️ [**On Display UI event**](#on-display-ui-event) - Re-trigger actions every time a screen becomes visible\
> 🪟 [**On Load event on Modal**](#on-load-event-on-modal) - Modal components now support On Load events\
> 🏗️ [**KB user-defined metadata**](#kb-user-defined-metadata) - Define custom metadata keys on Knowledge Base content sources\
> ⚙️ [**Config params in workflow conditions**](#config-params-in-workflow-conditions) - Use config params and user details in workflow Fork node expressions\
> 🎨 [**Branding settings grouping**](#branding-settings-grouping) - Reorganized branding settings page\
> ✍️ [**Markdown in chat messages**](#markdown-in-chat-messages) - Render formatted text, links, and lists in chat responses\
> 🔗 [**External Action dynamic URL**](#external-action-dynamic-url) - Use expressions in External Action URLs for dynamic navigation\
> 📬 [**Notification history**](#notification-history) - View sent notification details and search by process instance
>
> ### **UI Flow Route Management**
>
> > [card] UI Flow Route Management
> >
> > > [tab] Overview
> > >
> > > Define query parameters on root views (Pages, Modals), pass data between screens via URL query strings, and get automatic breadcrumb generation from the navigation graph. Navigate To actions support destination parameter mapping with `${expression}` syntax for dynamic values.
> > >
> > > ![Route parameters modal with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#route-management)
> > > >
> > > > See the Route Management section in UI Flows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Route parameters
> > > >
> > > > Define named query parameters on root views with default values and required flags
> > >
> > > > [card] Parameter passing
> > > >
> > > > Map data from process store to destination query parameters using JSON expressions
> > >
> > > > [card] Auto breadcrumbs
> > > >
> > > > Breadcrumbs auto-generate from the navigation graph with proper parameter handling
> > >
> > > > [card] Modal URL state
> > > >
> > > > Modals add `modalId` to URL — survives page reload and supports deep linking
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Start Parameters**
>
> > [card] UI Flow Start Parameters
> >
> > > [tab] Overview
> > >
> > > Pass initial data when launching a UI Flow. Define start parameters as a JSON object in the Designer's Run dialog, extract them from URL query strings in SaaS container apps, or send them in the API request body. Parameters are persisted on the session and available throughout the UI Flow lifecycle.
> > >
> > > ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#start-parameters)
> > > >
> > > > See the Start Parameters section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Session Variables**
>
> > [card] UI Flow Session Variables
> >
> > > [tab] Overview
> > >
> > > UI Flow sessions can now persist variables across all pages sharing the same session ID. Data from start parameters, workflow outputs, and file upload responses is automatically collected and merged into session variables. Reference them in component configurations using `${}` syntax. A new **Variables** tab in the Designer session console shows current values for debugging.
> > >
> > > ![Variables tab in UI Flow session console](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#session-variables)
> > > >
> > > > See the Session Variables section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **Chat History**
>
> > [card] Chat History
> >
> > > [tab] Overview
> > >
> > > Users can now browse and resume past chat conversations. Chat History displays a list of previous sessions grouped by time (Today, Yesterday, Previous 7 Days, Previous 30 Days, Older), with the ability to open any conversation and continue where they left off. Conversations are per-user with access control enforced.
> > >
> > > ![Chat History panel with conversation list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#chat-history)
> > > >
> > > > See the Chat History section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Chat Suggested Prompts**
>
> > [card] Chat Suggested Prompts
> >
> > > [tab] Overview
> > >
> > > The Chat component now supports pre-configured **Suggested Prompts** — pill buttons displayed below the welcome message in the chat empty state. Configure a title and up to 5 prompt options in the Designer. When a user clicks a suggestion, it is submitted as their message, starting the conversation immediately.
> > >
> > > ![Suggested Prompts in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#suggested-prompts)
> > > >
> > > > See the Suggested Prompts section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Monaco Editor Autocomplete**
>
> > [card] Monaco Editor Autocomplete
> >
> > > [tab] Overview
> > >
> > > Code editors in the Designer now provide autocomplete suggestions from your project's configuration parameters. This speeds up writing business rules and expressions that reference config params.
> > >
> > > > [card] [Documentation](/5.1/docs/projects/runtime/configuration-parameters-overrides)
> > > >
> > > > See the Configuration Parameters documentation.
> >
> > All Deployments
>
> ***
>
> ### **Process Variables UX improvements**
>
> > [card] Process Variables UX
> >
> > > [tab] Overview
> > >
> > > UI/UX improvements to the Update Process Variables experience, making it easier to view and edit runtime process data.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > > >
> > > > See the Update Process Variables documentation.
> >
> > All Deployments
>
> ***
>
> ### **onClick UI events**
>
> > [card] onClick UI events
> >
> > > [tab] Overview
> > >
> > > Buttons and Collection Prototypes now support **onClick** UI events — client-side JavaScript expressions that execute immediately when clicked, *before* any configured UI actions fire. Use them for instant local data updates without server roundtrips.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-events)
> > > >
> > > > See the UI Events documentation.
> >
> > All Deployments
>
> ***
>
> ### **KB query results in workflow console**
>
> > [card] KB Query Results
> >
> > > [tab] Overview
> > >
> > > The workflow run console now includes a **Knowledge Base** tab that displays retrieved chunks, relevance scores, content sources, and metadata when Custom Agent nodes query a knowledge base. This makes it easier to debug and tune RAG-powered workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows)
> > > >
> > > > See Using Knowledge Base in Workflows.
> >
> > All Deployments
>
> ***
>
> ### **Multi-file bulk upload**
>
> > [card] Multi-file Bulk Upload
> >
> > > [tab] Overview
> > >
> > > Upload multiple files simultaneously at runtime using the new [Multiple File Upload](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload) component. Supports drag-and-drop, batch selection, per-file validation, and progress tracking. Available in both process screens and UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **DISMISS UI action**
>
> > [card] DISMISS Action
> >
> > > [tab] Overview
> > >
> > > The Start Workflow UI action now includes a **Dismiss modal** checkbox. When enabled, the modal closes automatically after the workflow completes — removing the need for a separate close action.
> >
> > All Deployments
>
> ***
>
> ### **Enum label display**
>
> > [card] Enum Label Display
> >
> > > [tab] Overview
> > >
> > > Text components can now display the human-readable **label** of an enumeration value instead of the raw code. When a data key references an enumeration, the renderer resolves the selected code to its label at display time. Enumeration values are also prefetched from the data model before action resolution for improved performance.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations#displaying-enum-labels-in-text-components)
> > > >
> > > > See the Enumerations documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification template usages**
>
> > [card] Notification Template Usages
> >
> > > [tab] Overview
> > >
> > > Notification templates now show a **usages** modal that lists all processes and workflows referencing the template. This helps you understand the impact of changes before editing or deleting a template.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > > >
> > > > See the Managing Notification Templates documentation.
> >
> > All Deployments
>
> ***
>
> ### **Side Panel in Data Model**
>
> > [card] Side Panel in Data Model
> >
> > > [tab] Overview
> > >
> > > The Data Model editor now includes a side panel for easier navigation and editing of data model attributes, improving the workflow when working with large data models.
> >
> > All Deployments
>
> ***
>
> ### **On Display UI event**
>
> > [card] On Display UI event
> >
> > > [tab] Overview
> > >
> > > A new `onDisplay` event type that triggers every time a screen becomes visible — on initial load, when navigating back, or when a modal is dismissed. Unlike On Load (which fires once), On Display re-triggers on every view, making it ideal for refreshing data.
> > >
> > > Supported on Page, Zone, and Tab Bar components in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **On Load event on Modal**
>
> > [card] On Load event on Modal
> >
> > > [tab] Overview
> > >
> > > Modal components in UI Flows now support the On Load event and Start Workflow action. This enables data fetching when a modal opens, allowing you to load context-specific data for modal content.
> >
> > All Deployments
>
> ***
>
> ### **KB user-defined metadata**
>
> > [card] KB user-defined metadata
> >
> > > [tab] Overview
> > >
> > > Define custom metadata keys on Knowledge Bases and assign values to content sources. User-defined metadata enables filtering and scoping when searching chunks — for example, by department, document version, or region. Metadata values are propagated to the vector database and can be used as filters in the Context Retrieval workflow node.
> >
> > All Deployments
>
> ***
>
> ### **Config params in workflow conditions**
>
> > [card] Config params in workflow conditions
> >
> > > [tab] Overview
> > >
> > > Workflow Fork (condition) nodes can now access configuration parameters via `additionalData.applicationConfiguration` and authenticated user details via `additionalData.securityDetails` in their expressions. This enables environment-aware routing and user-based branching in integration workflows.
> >
> > All Deployments
>
> ***
>
> ### **Branding settings grouping**
>
> > [card] Branding settings grouping
> >
> > > [tab] Overview
> > >
> > > The branding settings page has been reorganized with improved grouping and layout, making it easier to find and configure branding options.
> >
> > All Deployments
>
> ***
>
> ### **Markdown in chat messages**
>
> > [card] Markdown in Chat Messages
> >
> > > [tab] Overview
> > >
> > > Chat message components in web renderers now support Markdown rendering. AI-generated responses can include formatted text, headings, links, code blocks, and lists — displayed with proper styling in the chat interface.
> >
> > All Deployments
>
> ***
>
> ### **External Action dynamic URL**
>
> > [card] External Action Dynamic URL
> >
> > > [tab] Overview
> > >
> > > External Action URLs now support `${expression}` syntax for dynamic values. Build destination URLs using process data, config params, or computed values — enabling context-aware external navigation from UI Flows.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-actions#external-ui-actions)
> > > >
> > > > See the UI Actions documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification history**
>
> > [card] Notification History
> >
> > > [tab] Overview
> > >
> > > New REST API endpoints on the notification plugin let you retrieve sent notification history. Query a paginated summary list filtered by app and optionally by process instance, or fetch full notification details by ID — including recipients, subject, body, and the source process/action that triggered it.
> > >
> > > * `GET /api/notification/summary` — paginated summary list with filtering and sorting
> > > * `GET /api/notification/{id}` — full notification details including body and recipients
> >
> > > [tab] Key Features
> > >
> > > > [card] Summary and detail views
> > > >
> > > > Paginated summary list for browsing, with full detail drill-down by notification ID
> > >
> > > > [card] Source tracking
> > > >
> > > > Each notification records which process, node, and action triggered it for full traceability
> >
> > All Deployments

> [tab] SaaS
>
> User management and branding improvements for SaaS deployments.
>
> 👤 [**Runtime User Invitations**](#runtime-user-invitations) - Invite runtime users directly to test projects\
> 🏢 [**Workspace Type Display**](#workspace-type-display) - See workspace type within Designer\
> 🎨 [**Container App Branding**](#container-app-branding) - Customize branding for SaaS container apps\
> 👥 [**Designer User Invitations**](#designer-user-invitations) - Updated invite modal for designer users
>
> ### **Runtime User Invitations**
>
> > [card] Runtime User Invitations
> >
> > > [tab] Overview
> > >
> > > Invite runtime users directly to test projects from within the Designer. Simplifies the process of granting test access without requiring full workspace-level permissions.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS
>
> ***
>
> ### **Workspace Type Display**
>
> > [card] Workspace Type Display
> >
> > > [tab] Overview
> > >
> > > The Designer now displays the workspace type (development, staging, production) directly within the workspace view, making it easier to identify your current environment.
> >
> > SaaS
>
> ***
>
> ### **Container App Branding**
>
> > [card] Container App Branding
> >
> > > [tab] Overview
> > >
> > > Customize your SaaS container app branding at the organization level — upload a custom logo, set primary and secondary colors, toggle the header, and configure the solutions page background.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/container-app-branding)
> > > >
> > > > See the Container App Branding documentation.
> >
> > SaaS
>
> ***
>
> ### **Designer User Invitations**
>
> > [card] Designer User Invitations
> >
> > > [tab] Overview
> > >
> > > The invite modal for designer users has been redesigned with clearer role selection, group assignment, and a streamlined layout for inviting multiple users.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS

> [tab] Bug Fixes
>
> ## Bug fixes
>
> ### Core Platform
>
> * **Authorization-system Oracle DB startup** — Fixed an issue where the authorization-system service failed to start when using Oracle as the configured database.
> * **Process definition merge timing** — Fixed a race condition where the process definition was updated before the merge was finalized.
> * **Theme import with builds** — Fixed an issue where themes were not included when importing builds.
> * **Library import permissions** — Fixed an issue where importing a library into a workspace redirected to a 403 error page.
> * **App version reimport** — Fixed an error that occurred when reimporting an app version (project or library).
> * **Email resend after URL expiry** — Fixed an issue where the resend email endpoint returned 200 OK but no email was sent after the URL expired.
> * **Platform status discovery** — Fixed an authorization error when trying to force discover platform status.
> * **Runtime roles in permissions** — Fixed inconsistent runtime roles display in the permissions dropdown.
>
> ### AI Platform & Workflows
>
> * **gRPC thread pool sizing** — Fixed under-provisioned gRPC client thread pools that caused socket timeouts and dropped requests in production.
> * **API error trace IDs** — API errors now include a reference to the active traceID for easier debugging.
> * **Cross-project resource copy** — Fixed an issue where copying a workflow resource to another project did not include LDM objects.
> * **Multi-instance mappings** — Fixed a 400 error when saving multi-instance mappings in data mappers.
> * **Email trigger mock testing** — Fixed errors when starting a process from a build with mock email content.
> * **Multiple start nodes with email trigger** — Fixed an issue where only one start option was displayed when a process contained multiple start nodes with email triggers.
>
> ### Renderers & UI
>
> * **Angular input field crash** — Fixed an issue where pressing Enter in an input field caused the Angular UI to crash.
> * **Floating Chat interaction blocking** — Fixed an issue where the floating chat component blocked all interaction with page content while open.
> * **S3 internal bucket error** — Fixed an error when the integration-designer downloads files from document-plugin via downloadPath.
> * **File upload second attempt** — Fixed an issue where upload requests were not made when uploading a second file.
> * **UI Flow analytics** — Fixed issues where analytics events were not visible and not saved for Navigate-to action types.
> * **Task management column selection** — Fixed an issue where the Last Updated column remained selected in task management.
> * **Task Manager theming and UX** — Multiple fixes for Task Manager theming, dropdown display, comment field styling, and user assignment behavior.
> * **Toggle/checkbox label alignment** — Fixed an issue where the switch toggle/checkbox or label shifted position when in an error state.&#x20;
> * **Query parameters lost after refresh** — Fixed an issue where URL query parameters were lost after page refresh in UI Flows.&#x20;
> * **SSE connection management** — Fixed multiple issues where SSE connections were opened twice or not closed properly after messages were received.&#x20;
> * **Modal layering** — Fixed incorrect layering when a loader modal was displayed on top of another modal.&#x20;
> * **Card theming overrides** — Fixed an issue where card theming overrides were not applied when the card was collapsed.&#x20;
> * **On Display workflow triggering** — Fixed an issue where past On Display workflows were not re-triggered on page refresh.&#x20;
>
> ### Knowledge Base
>
> * **KB metadata handling** — Fixed multiple issues with Knowledge Base user-defined metadata: empty properties on content source creation, metadata not available for content sources added through apps, and incorrect cleanup when deleting metadata keys.&#x20;

> [tab] Info
>
> ## Additional information
>
> ### At a glance
>
> This release includes **30+ new features and enhancements** across AI Platform, Integrations, UI & Designer, and SaaS — plus **28 bug fixes** spanning Core Platform, AI/Workflows, Renderers, and Knowledge Base.
>
> ***
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6).
>
> For new environment variables and Kafka topics, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6#new-environment-variables).
>
> ### Changes to be aware of
>
> > [!NOTE]
> >
> > FlowX.AI 5.6.0 is a SaaS-managed release — deployment-level changes (infrastructure, Kafka topics, service configuration) are handled automatically by FlowX. The items below are listed for transparency and for future reference when on-prem support ships in 5.7+.
>
> #### API change (action required if you use this endpoint)
>
> > [!WARNING]
> >
> > **Process definition start metadata endpoint renamed** — `GET /api/process-definition/{uuid}/get-input-json` has been renamed to `GET /api/process-definition/{uuid}/get-start-metadata`. Update any API clients or custom integrations that call this endpoint directly.
> >
> > The response now includes an additional `hasEmailTriggerStart` boolean field.
>
> #### Infrastructure changes (managed by FlowX on SaaS)
>
> * **gRPC thread pool configuration** — Default gRPC client thread pool sizes have been updated for better production throughput.
> * **WorkspaceCreatedEvent ownership** — Kafka topic ownership moved from `authorization-system` to `organization-manager`.
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.5.0 — if you call `get-input-json` directly, update to `get-start-metadata`. All other changes are managed automatically on SaaS.
>
> > [card] [Component versions](./deployment-guidelines-v5.6#component-versions)
> >
> > See the Deployment Guidelines for the full component version matrix


# Deployment guidelines v5.7.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7

Component versions, environment variables, and configuration changes for FlowX.AI 5.7.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.96.0** | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 |
| **admin** | **10.83.0** | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 |
| **designer** | **10.164.0** | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **cms-core** | **10.58.0** | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 |
| **scheduler-core** | **10.45.0** | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 |
| **events-gateway** | **10.47.0** | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 |
| **notification-plugin** | **10.56.0** | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 |
| **document-plugin** | **10.64.0** | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 |
| **task-management-plugin** | **10.57.0** | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 |
| **data-search** | **10.44.0** | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 |
| **audit-core** | **10.54.0** | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 |
| **advancing-controller** | **10.45.0** | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 |
| **integration-designer** | **10.113.0** | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 |
| **application-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **runtime-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **data-sync** | **10.50.0** | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 |
| **authorization-system** | **10.68.0** | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 |
| **nosql-db-runner** | **10.48.0** | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 |
| **email-gateway** | **10.47.0** | 10.32.1 | 10.24.0 | 10.9.0 | - | - |
| **organization-manager** | **10.44.0** | 10.26.1 | 10.19.2 | - | - | - |
| **webhook-gateway** | **10.15.0** | 10.1.1 | - | - | - | - |
| **license** | **10.36.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |

### Plugins

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 |
| **ai-platform-ai-assistant** | **10.6.2** | - | - | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 |
| **ai-platform-ai-developer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-connected-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-knowledge-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agents** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-conversations** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-tenants** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-planner** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-analyst** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-designer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agent-builder** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-binaries** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **embedder** | **10.6.2** | - | - | - | - | - |
| **knowledgebase-rag** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **mcp** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **doc-converter** | **10.2.3** | 10.2.2 | - | - | - | - |
| **doc-parser** | **10.6.2** | 10.5.1 | - | - | - | - |
| **web-crawler** | **10.3.2** | - | - | - | - | - |
| **data-privacy** | **10.0.8** | - | - | - | - | - |
| **speech-to-text** | **10.3.3** | - | - | - | - | - |
| **modpod** | **10.0.7** | - | - | - | - | - |

> [!NOTE]
>
> **Note:** The `ai-platform-models` service has been removed in 5.7.0. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers) within the Organization Manager.

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.7.0 | Keycloak | 26+ |
| 5.7.0 | Kafka | 3.8 - 3.9 |
| 5.7.0 | PostgreSQL | 16 - 17 |
| 5.7.0 | Oracle Database | 21c, 23ai |
| 5.7.0 | MongoDB | 7 - 8 |
| 5.7.0 | Redis | 7.4 - 8.0 |
| 5.7.0 | Elasticsearch | 8 |
| 5.7.0 | Angular (Web SDK) | 20 |
| 5.7.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> The following versions of third-party dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

***

## Self-hosted deployment changes

> [!WARNING]
>
> **First on-premises release since 5.4.0.** This section covers critical configuration changes for self-hosted (on-premises) deployments.

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **Fresh install** | Supported | Guided setup flow on first launch. See [Organization Manager setup](/5.1/setup-guides/organization-manager-setup). |
| **5.1.x LTS** | Supported | Requires Organization ID on all 19 services. Liquibase migrates active process instances and realm data. Inactive instances require separate handling by FlowX. See details below. |
| **5.2 - 5.4** | FlowX-assisted only | These versions may have partial realm or organization changes. Contact your FlowX representative for a custom migration plan. Do **not** follow the 5.1.x upgrade path. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

### Organization ID (mandatory for upgrades)

The Organization ID is how FlowX identifies your installation. How it is obtained depends on your deployment path:

* **Fresh install:** The Organization ID is created automatically during the guided setup flow (Designer first-launch screen). No manual configuration needed.
* **Upgrade from 5.1.x:** FlowX registers your organization in the SaaS licensing infrastructure and provides an Organization ID (UUID). Set `ORGANIZATION_ID` on **all 19 services** before deploying 5.7.0 images — Liquibase migrations use it to replace the default organization.

```yaml theme={"dark"}
# Example — set on every service
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

**Affected services (all 19):** process-engine, admin, audit-core, authorization-system, advancing-controller, events-gateway, cms-core, scheduler-core, data-search, document-plugin, nosql-db-runner, notification-plugin, task-management-plugin, integration-designer, organization-manager, email-gateway, application-manager, runtime-manager, license.

> [!WARNING]
>
> Do **not** deploy 5.7.0 images without setting `ORGANIZATION_ID` on upgrade scenarios. Services will fail to start if Liquibase migrations cannot find the organization ID.

> [!NOTE]
>
> **Active vs inactive instances.** Liquibase migrations automatically update the Organization ID on **active process instances** only. Inactive or archived instances require separate migration handled by the FlowX team during guided deployment. Contact your FlowX representative for details.

### License service (new)

Self-hosted deployments must configure the License service to connect to FlowX SaaS for license validation and usage reporting. See the [License service setup guide](/5.9/setup-guides/license-engine-setup) for complete configuration.

### IAM / Keycloak changes

FlowX.AI now uses a **two-realm architecture** in Keycloak and **JWT public key validation** (replacing opaque-token introspection). These changes were introduced in 5.5.0 (SaaS) and are now relevant for self-hosted deployments.

* **Token validation**: `security.type` switches from `oauth2` to `jwt-public-key` on all services
* **Service accounts realm**: A dedicated realm (`00000002-0002-4002-8002-000000000002`) holds all service account clients, separate from the user realm
* **Organization manager**: Now a required dependency for all services (provides realm resolution)
* **`flowx-platform-authorize` client**: No longer needed — remove from Keycloak
* **Master realm credentials**: The authorization-system service needs Keycloak admin access for realm migrations. If you cannot provide admin credentials, see [Manual Keycloak configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).
* **SMTP**: Must be configured in Keycloak for password reset and user invitations

For complete IAM setup instructions, see the [Configuring an IAM solution](/5.1/setup-guides/access-management/configuring-an-iam-solution) guide.

***

## Environment info deprecation

The **Configure Environment Info** feature (`PATCH /api/platform/environment`) is deprecated and removed. Environment name is now set during organization registration. The following are no longer used:

* `FLOWX_CLIENT_NAME` environment variable
* `FLOWX_ENVIRONMENT_NAME` environment variable
* `environmentDetails` section in the `/api/init` response

***

## Kafka integration changes

### Fx-Organization-Id header (mandatory)

All FlowX Kafka consumers now validate the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected with a non-retryable `MissingKafkaHeaderException`.

> [!WARNING]
>
> **Action required for custom Kafka integrations.** If you have custom Kafka producers that publish directly to FlowX topics (starting processes, sending task events, responding to engine requests), you must add the `Fx-Organization-Id` header to every message. Set it to the Organization UUID (`ORGANIZATION_ID` value).
>
> ```java theme={"dark"}
> producerRecord.headers().add("Fx-Organization-Id",
>     organizationId.getBytes(StandardCharsets.UTF_8));
> ```
>
> See the [Creating a Kafka producer](/5.1/docs/platform-deep-dive/integrations/creating-a-kafka-producer#important-headers) guide for details.

### New Kafka topics

| Topic | Environment Variable | Producer | Consumer | Description |
| - | - | - | - | - |
| `ai.flowx.llm.config.changed.v1` | `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | organization-manager | integration-designer, AI Python services | Broadcast when LLM provider or model configuration changes at the organization level |

***

## Environment variables

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `ORGANIZATION_ID` | Organization UUID provided by FlowX. Required on all services for upgrades. Fresh installs get this automatically via the setup flow. | - | all services |
| `FLOWX_LICENSE_KEY` | License key for FlowX SaaS connection | - | license |
| `FLOWX_LICENSE_AUTHSERVERURL` | FlowX SaaS auth URL | - | license |
| `FLOWX_LICENSE_SERVERURL` | FlowX SaaS license API URL | - | license |
| `FLOWX_ORG_MANAGER_URL` | Organization Manager service URL for LLM provider configuration. Required on all Python AI services. | - | planner, ai-developer, ai-analyst, ai-designer, agent-builder, knowledgebase-rag, embedder, knowledgebase |
| `SECURITY_MASTERREALM_CLIENTID` | Master realm admin client ID for Keycloak management | `admin-cli` | authorization-system |
| `SECURITY_MASTERREALM_NAME` | Keycloak master realm name | `master` | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username for realm migrations | - | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password for realm migrations | - | authorization-system |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` | all services |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL for security lib | `http://organization-manager:80` | all services |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `60` | organization-manager |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `30` | organization-manager |
| `FLOWX_SPEECH_TO_TEXT_BASE_URL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` | integration-designer |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Topic for LLM config change notifications | `ai.flowx.llm.config.changed.v1` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys at rest. **Change from default in production.** | `default-dev-key-change-in-prod` | organization-manager |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required on on-prem deployments. | - | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required on on-prem deployments when the FlowX generic container app is deployed. | - | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If empty, derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` | organization-manager |
| `DEFAULT_ORGANIZATION_NAME` | Fallback organization code used by the Designer web app during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present. Required on on-prem — set to the organization code registered with FlowX. | - | designer |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for Oracle Database schema discovery responses cached for the SQL editor. | `24h` | integration-designer |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools used by Oracle Database data sources. | `100` | nosql-db-runner |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached JDBC connection pools. | `1d` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per Oracle Database data source. | `5` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout for Oracle Database data sources. | `10` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses for Oracle Database operations. | `1000` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout for Oracle Database operations. | `30` | nosql-db-runner |

### Removed environment variables

> [!WARNING]
>
> **For upgrades:** Remove these variables only **after** the Liquibase migrations have completed successfully. If you remove them before starting services for the first time on 5.7.0, the migrations may fail. The recommended sequence is: (1) add new variables, (2) deploy 5.7.0 images, (3) let migrations run, (4) verify services are healthy, (5) remove old variables in a follow-up deployment.

| Environment Variable | Reason | Component |
| - | - | - |
| `FLOWX_CLIENT_NAME` | Replaced by org code from registration | process-engine |
| `FLOWX_ENVIRONMENT_NAME` | Replaced by env name from registration | process-engine |
| `AI_SERVICE_MODELS_ENDPOINT` | The Models microservice (port 9104) has been removed. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers). Remove this service from your deployment. | ai-platform (all Python services) |
| `SECURITY_OAUTH2_REALM` | Replaced by per-organization realm resolution. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | Opaque-token introspection client no longer needed. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | Opaque-token introspection client secret no longer needed. | all services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_*` | Entire opaque-token introspection config removed. | all services |


# FlowX.AI 5.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/v5.7.0-april-2026

Single-org on-premises deployment, custom React components, AI providers self-service, chat-based UI Flows, voice input, end-user access management, and advanced query builder.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

FlowX.AI 5.7.0 makes on-premises deployment a first-class experience. **Single-org deployment** is now the default mode — configure your organization once, connect to FlowX licensing, and you're running. For builders, **Custom Components** let you write React code directly in the Designer, **AI Providers** configuration gives organizations self-service control over their LLM setup, and **Chat-based UI Flows** simplify conversational experiences. For organization admins, **End-user access management** separates runtime users, roles, and groups from Designer users.

> [card] [For platform teams](#single-org-deployment)
>
> Single-org deployment, license service, organization setup flow

> [card] [For builders](#custom-components)
>
> Custom React components, AI provider config, chat-based UI Flows, voice input

> [card] [For admins](#end-user-access-management)
>
> End-user access management, runtime roles, and groups

### What changed since 5.6.0

| 5.6.0 | 5.7.0 |
| - | - |
| SaaS-focused deployment | + **Single-org on-premises** as the default mode |
| Built-in UI components only | + **Custom React Components** with code editor and dependencies |
| AI models configured by FlowX | + **AI Providers self-service**: OpenAI (FlowX Managed or BYOK), custom URL, Defaults & Fallbacks per workspace type |
| Chat workflow set per component | + **Chat-based UI Flows**: set one workflow for the entire UI Flow |
| Text-only chat input | + **Voice input** for chat conversations |
| No audio processing in workflows | + **Speech to Text** node for transcription and text-to-speech |
| Runtime users mixed with Designer users | + **End-user access management**: separate org-level lists for end-users, roles, and groups, with CSV bulk invite |
| Basic query filters | + **Advanced Query Builder** for database operations |
| MongoDB-only database data sources | + **Oracle Database** as a new data source type with schema-aware SQL editor |
| Fixed search strategy for KB retrieval | + **Context Retrieval**: configurable search type (Hybrid/Semantic/Keyword) and re-ranking |
| Equality-only metadata filters, AND logic | + **Knowledge Base filter builder** with typed operators and AND/OR grouping; **Content Sources** tab renamed to **Stores** |
| Basic merge modal | + **Merge conflicts UX**: redesigned modal, diff viewer theme, keyboard support |

***

**What's new?**

> [tab] Platform
>
> FlowX 5.7.0 introduces single-org deployment as the default mode for on-premises installations, with self-service licensing, organization management, and runtime access controls.
>
> 🏢 [**Single-org deployment**](#single-org-deployment) - On-premises deployment with automatic organization setup\
> 🔑 [**License service**](#license-service) - Connect to FlowX SaaS for license validation and usage reporting\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level end-users, roles, and groups, separate from Designer users
>
> ### **Single-org deployment**
>
> > [card] Single-org deployment
> >
> > > [tab] Overview
> > >
> > > Self-hosted deployments now run as single-organization systems by default. FlowX registers your organization in the SaaS licensing infrastructure, provides an Organization ID, and your deployment connects to FlowX for license validation and usage reporting. The Designer guides you through a setup flow on first launch: enter a token, name your environment, and create your admin user.
> > >
> > > > [card] [Documentation](/5.1/setup-guides/organization-manager-setup#organization-id-configuration)
> > > >
> > > > See the Organization Manager setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Guided setup flow
> > > >
> > > > Designer walks you through organization registration on first launch
> > >
> > > > [card] Organization ID
> > > >
> > > > Mandatory on all services for Liquibase migrations on upgrades
> > >
> > > > [card] License connectivity
> > > >
> > > > On-premises license service connects to FlowX SaaS for validation and usage
> > >
> > > > [card] Multi-org features hidden
> > > >
> > > > Registration, org selection, and org switching are not available on-prem
> > >
> > > > [card] Explicit web app URLs
> > > >
> > > > Designer and Runtime URLs are configured via dedicated on-prem env vars on organization-manager, replacing hard-coded org-code lookup
> >
> > Major FeatureSelf-Hosted
>
> ***
>
> ### **License service**
>
> > [card] License service
> >
> > > [tab] Overview
> > >
> > > The License service is the bridge between your self-hosted deployment and FlowX SaaS. It validates your platform license, reports usage data, and ensures your subscription is active. Configure it with the license key and server URLs provided by FlowX during organization registration.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> > > >
> > > > See the License service setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] License validation
> > > >
> > > > Continuous license sync with FlowX SaaS
> > >
> > > > [card] Usage reporting
> > > >
> > > > AI node execution consumption reported to FlowX
> > >
> > > > [card] Organization events
> > > >
> > > > Listens to organization lifecycle events via Kafka
> > >
> > > > [card] Setup guide
> > > >
> > > > Complete setup guide with PostgreSQL, Kafka, Redis, and SpiceDB configuration
> >
> > Self-Hosted
>
> ***
>
> ### **End-user access management**
>
> > [card] End-user access management
> >
> > > [tab] Overview
> > >
> > > Organization admins can now manage the people who use published solutions separately from Designer users. A new **Access Management** section at the organization level holds three lists — **End-Users**, **End-Users Roles**, and **End-Users Groups** — each with its own permissions. Invite end users individually or import many at once from a CSV template, define roles that describe runtime access, and organize users into groups with custom attributes for filtering.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> > > >
> > > > See the End-user access management setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Separate end-user list
> > > >
> > > > End-Users are kept distinct from Designer users, with their own read/write permissions
> > >
> > > > [card] End-user roles
> > > >
> > > > Define named roles that describe runtime access at the organization level
> > >
> > > > [card] End-user groups
> > > >
> > > > Group users by department, region, or any attribute, and assign roles to the whole group
> > >
> > > > [card] Bulk invite
> > > >
> > > > Invite many users at once from a CSV template with names and attributes
> >
> > All Deployments
>
> ***

> [tab] AI & Chat
>
> Self-service AI provider configuration, chat-based UI Flows, AI Triggers, and voice input for conversational experiences.
>
> 🤖 [**AI Providers**](#ai-providers) - Organization-level LLM provider and model configuration\
> 💬 [**Chat-based UI Flows**](#chat-based-ui-flows) - Set a conversational workflow for the entire UI Flow\
> 🎤 [**Voice input**](#voice-input) - Speech-to-text input in chat conversations\
> ⏹️ [**Stop agent response**](#stop-agent-response) - Cancel an in-progress agent reply from the chat input\
> 🗣️ [**Speech to Text node**](#speech-to-text-node) - Transcription and text-to-speech workflow node\
> ⚡ [**AI Triggers**](#ai-triggers) - Named message templates for launching conversational workflows with context\
> 🧩 [**UI Flow Context**](#ui-flow-context) - Pass UI state from a Page to a conversational workflow\
> 🎯 [**Recommended prompts**](#recommended-prompts) - AI-generated follow-up suggestions in chat conversations\
> 🔎 [**Context Retrieval enhancements**](#context-retrieval-enhancements) - Configurable search type and re-ranking\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - Stores rename, typed metadata filters, AND/OR grouping\
> 🌐 [**Web Page Extractor enhancements**](#web-page-extractor-enhancements) - URL filtering, crawl depth, and file downloads
>
> ### **AI Providers**
>
> > [card] AI Providers
> >
> > > [tab] Overview
> > >
> > > Organizations can now configure their own AI providers and assign models at the organization level. Configure **OpenAI** (Bring Your Own Key or FlowX Managed) or **Azure OpenAI** for deployment-based access to GPT models, enable specific models, and assign default and fallback models per AI capability and workspace type (Sandbox, Staging, Production). **Defaults & Fallbacks** now includes an **Audio Capabilities** row used by the Speech to Text node, with `whisper-1` available in the OpenAI model catalog.
> > >
> > > ![Model Providers page with OpenAI and Azure OpenAI configured at the organization level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_view_org.png)
> > >
> > > ![Provider Details modal showing OpenAI and Azure OpenAI as provider options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_model_Provider.png)
> > >
> > > ![Defaults and Fallbacks page with capability rows including Audio Capabilities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/defaults_and_fallbacks.png)
> > >
> > > ![Model selection and configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ai_models_selection.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/ai-providers)
> > > >
> > > > See the AI providers and model configuration documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Organization-level providers
> > > >
> > > > Add and manage AI providers with API keys and connection settings
> > >
> > > > [card] Azure OpenAI
> > > >
> > > > Connect to Azure-hosted OpenAI deployments with a base URL and API version
> > >
> > > > [card] Custom model entry
> > > >
> > > > Add models manually for providers that use deployment names (Azure) or non-public catalogs
> > >
> > > > [card] Audio Capabilities
> > > >
> > > > New row in Defaults & Fallbacks for transcription and speech synthesis, used by the Speech to Text node
> > >
> > > > [card] Defaults & Fallbacks
> > > >
> > > > Assign default and fallback models per AI capability and workspace type
> > >
> > > > [card] Fallback strategy
> > > >
> > > > Set fallback models on different providers for resilience
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat-based UI Flows**
>
> > [card] Chat-based UI Flows
> >
> > > [tab] Overview
> > >
> > > UI Flows now support two experience types: **Flow-Based** (traditional) and **Chat-Based** (conversational). Chat-Based UI Flows connect to a conversational workflow at the UI Flow level, so all Chat components in the flow use the same workflow by default. A new Settings page with a Chat Options tab lets you configure or change the workflow after creation.
> > >
> > > ![Chat-based UI Flow configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_based_ui_flow.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> > > >
> > > > See the UI Flows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Experience types
> > > >
> > > > Choose Flow-Based or Chat-Based when creating a UI Flow
> > >
> > > > [card] UI Flow Settings
> > > >
> > > > New Settings page with Chat Options tab for workflow configuration
> > >
> > > > [card] Workflow filtering
> > > >
> > > > Chat components only show conversational workflows in the selector
> > >
> > > > [card] Navigate in UI Flow
> > > >
> > > > AI can open specific screens with parameters from a conversation
> >
> > All Deployments
>
> ***
>
> ### **Chat improvements**
>
> > [card] Chat improvements
> >
> > Configure which parts of the chat header are visible on a per-component basis. The Chat component (when display type is **Fill**) gains a **Show Header** toggle in its Properties panel, and the Chat Header component gets a new **Available Actions** accordion with toggles for **New Conversation** and **History**. Conversation history now loads in pages, with a **Load more** action, and conversations are sorted by creation date with the most recent first.
> >
> > All Deployments
>
> ***
>
> ### **Voice input**
>
> > [card] Voice input
> >
> > > [tab] Overview
> > >
> > > Chat components now support voice input, allowing users to record audio messages directly in the chat. Users can record, preview with an audio player, and send voice messages within conversations.
> > >
> > > > [!NOTE]
> > > >
> > > > Voice input captures and sends audio recordings. When paired with the [Speech to Text](/5.9/ai-platform/agent-builder/speech-to-text) workflow node, voice messages are automatically transcribed and processed as text in conversational workflows.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audio recording
> > > >
> > > > Record voice messages directly in the chat input
> > >
> > > > [card] Audio preview
> > > >
> > > > Preview recordings with a built-in audio player before sending
> >
> > All Deployments
>
> ***
>
> ### **Stop agent response**
>
> > [card] Stop agent response
> >
> > > [tab] Overview
> > >
> > > The chat input now shows a **Stop** button in place of Send while an agent reply is streaming. Pressing Stop cancels the conversational workflow instance: any in-flight AI call is aborted, partial output is discarded, and the user prompt is persisted with a `cancelled` flag so the chat history reflects what happened.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Cross-platform
> > > >
> > > > Available on Web (Standard, Floating, Full Screen), iOS, and Android
> > >
> > > > [card] Themeable
> > > >
> > > > New `stopResponseIcon` slot in `chatInputArea` themes; preloaded by cms-core
> > >
> > > > [card] Localized
> > > >
> > > > New system substitution tags for Stop and Send labels with a11y variants
> >
> > All Deployments
>
> ***
>
> ### **Speech to Text node**
>
> > [card] Speech to Text
> >
> > > [tab] Overview
> > >
> > > A new workflow node that converts between audio and text. **Transcribe** converts audio files (MP3, WAV, M4A, AAC, OGG) into text with language detection and confidence scores. **Text to Speech** generates audio files from text with configurable voice, speed, and format. In conversational workflows, the node processes voice messages from the chat UI automatically.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> > > >
> > > > See the Speech to Text node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Transcription
> > > >
> > > > Convert audio to text with language detection and confidence scores
> > >
> > > > [card] Text to Speech
> > > >
> > > > Generate audio from text with configurable voice, model, speed, and format
> > >
> > > > [card] Chat voice integration
> > > >
> > > > Automatically transcribes voice messages in conversational workflows
> > >
> > > > [card] Multiple file sources
> > > >
> > > > Read from Document Plugin, S3, or chat input
> >
> > > [!NOTE]
> > >
> > > The transcription model is resolved from the organization's **Audio** capability default, configured in **AI Settings** under [Defaults & Fallbacks](/5.9/ai-platform/ai-providers).
> >
> > All Deployments
>
> ***
>
> ### **AI Triggers**
>
> > [card] AI Triggers
> >
> > > [tab] Overview
> > >
> > > Define named message templates with parameters on conversational workflows, so different UI Flow pages can launch the same workflow with different starting contexts. Triggers are configured in a dedicated side nav tab and selected on the Start node or sent from the Chat component at runtime.
> > >
> > > ![Reply Triggers list in a conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_reply_trigger.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Parameterized messages
> > > >
> > > > Message templates with `${paramName}` placeholders resolved at runtime
> > >
> > > > [card] Multi-page reuse
> > > >
> > > > Different pages launch the same workflow with different context
> > >
> > > > [card] Start node integration
> > > >
> > > > Toggle between Text and AI Trigger modes on the Start node
> > >
> > > > [card] Memory aware
> > > >
> > > > Trigger messages saved to conversation memory but hidden from chat history
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Context**
>
> > [card] UI Flow Context
> >
> > > [tab] Overview
> > >
> > > Conversational workflows can now receive a JSON context alongside the user message. A new **Conversation Context** property on UI Flow Pages lets you define the Parameters payload (with `${expression}` resolution), and the Start node exposes it as a collapsible **UI Flow Context** editor — also available in the Run Workflow test modal for manual runs.
> > >
> > > ![Start node UI Flow Context and UI Flow Conversation Context property](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#setting-context-from-a-ui-flow)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] UI-driven context
> > > >
> > > > Pages attach a JSON payload to conversational runs without hard-coding it in the workflow
> > >
> > > > [card] Expression resolution
> > > >
> > > > Parameters support `${expression}` syntax to bind live UI Flow data at runtime
> > >
> > > > [card] Start node field
> > > >
> > > > Collapsible UI Flow Context editor on the Start node for both runtime and manual testing
> > >
> > > > [card] JSON validation
> > > >
> > > > Invalid JSON is rejected before the run starts, surfacing a clear error
> >
> > All Deployments
>
> ***
>
> ### **Recommended prompts**
>
> > [card] Recommended prompts
> >
> > > [tab] Overview
> > >
> > > Custom Agent nodes can now generate follow-up prompt suggestions alongside their chat replies. When enabled via the new **Prompt Suggestions** satellite panel on a Custom Agent node, the agent includes recommended next questions or actions in its response. These appear as clickable suggestions in the chat UI, guiding users toward relevant follow-up interactions.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions)
> > > >
> > > > See the Custom Agent node documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Satellite panel
> > > >
> > > > Configure prompt suggestions directly on Custom Agent nodes in the workflow editor
> > >
> > > > [card] AI-generated suggestions
> > > >
> > > > Agent generates contextual follow-up prompts based on the conversation
> > >
> > > > [card] Clickable in chat
> > > >
> > > > Suggestions render as tappable chips in the chat UI
> > >
> > > > [card] Conversational workflows
> > > >
> > > > Works with send-as-reply mode in conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval enhancements**
>
> > [card] Context Retrieval enhancements
> >
> > > [tab] Overview
> > >
> > > **Custom Agent** and **Context Retrieval** nodes now support configurable **search type** and **re-ranking** for Knowledge Base retrieval. Choose between Hybrid (default), Semantic, or Keyword search strategies depending on your use case. Turn on re-ranking to apply a secondary relevance model that reorders retrieved chunks for higher-quality results.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the Context Retrieval node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Search type
> > > >
> > > > Choose Hybrid, Semantic, or Keywords search for Knowledge Base retrieval on Custom Agent and Context Retrieval nodes
> > >
> > > > [card] Re-ranking
> > > >
> > > > Apply a re-ranking model to reorder results by relevance to the query — available on both Custom Agent and Context Retrieval nodes
> >
> > All Deployments
>
> ***
>
> ### **Knowledge Base enhancements**
>
> > [card] Knowledge Base enhancements
> >
> > > [tab] Overview
> > >
> > > The Knowledge Base data source gets a refreshed workspace and a more powerful metadata filter builder. The **Content Sources** tab is now called **Stores**, and the Chunks tab gains a structured query builder for metadata filters with typed operators, AND/OR logic, and grouping — replacing the previous equality-only filters.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > > >
> > > > See the Knowledge Base content management guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Stores tab
> > > >
> > > > The Content Sources tab is renamed to Stores. Same concept, clearer label.
> > >
> > > > [card] Typed filter operators
> > > >
> > > > Operators per metadata type: equals, not equals, contains, in, not in, before, after, exists, size equals, and more
> > >
> > > > [card] AND/OR grouping
> > > >
> > > > Combine conditions with AND or OR and nest them in groups for non-trivial logic
> > >
> > > > [card] Query builder on Chunks tab
> > > >
> > > > Test retrieval with Search Type (Hybrid/Semantic/Keywords), Use Re-rank, and the new filter builder
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor enhancements**
>
> > [card] Web Page Extractor enhancements
> >
> > > [tab] Overview
> > >
> > > The Web Page Extractor node now supports **URL filtering** to include or exclude specific URL patterns during crawling, **configurable crawl depth** for more control over how deep the crawler follows links, and **file downloads** to retrieve attached files from crawled pages.
> >
> > > [tab] Key Features
> > >
> > > > [card] URL filtering
> > > >
> > > > Include or exclude URLs matching specific patterns during crawling
> > >
> > > > [card] Crawl depth
> > > >
> > > > Configure how many levels deep the crawler follows links
> > >
> > > > [card] File downloads
> > > >
> > > > Download attached files from crawled web pages
> > >
> > > > [card] Bulk document type
> > > >
> > > > When file downloads are enabled, the document type auto-sets to **Bulk** so a single crawl can return multiple documents
> >
> > All Deployments
>
> ***

> [tab] UI & Components
>
> Custom React components, advanced query builder, and merge conflict improvements.
>
> 🧩 [**Custom Components**](#custom-components) - Write React code in Designer and use in UI Flows\
> 🔍 [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder for database operations\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor\
> 🔀 [**Merge conflicts UX**](#merge-conflicts-ux) - Improved merge modal and conflict resolution experience
>
> ### **Custom Components**
>
> > [card] Custom Components
> >
> > > [tab] Overview
> > >
> > > Create custom React components directly in FlowX Designer. Write JSX, CSS, and use pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Components receive process data through input keys and can trigger process actions. Define once in Reusable Resources, use across multiple User Tasks.
> > >
> > > ![Custom Components code editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> > > >
> > > > See the Custom Components documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Code editor
> > > >
> > > > Write React JSX and CSS with a built-in code editor and file tree
> > >
> > > > [card] Pre-defined packages
> > > >
> > > > React, Emotion, Lodash, Axios, and date-fns available out of the box
> > >
> > > > [card] Process integration
> > > >
> > > > Receive process data via input keys and trigger process actions
> > >
> > > > [card] Import/Export
> > > >
> > > > Export as ZIP and import into other projects
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Advanced Query Builder**
>
> > [card] Advanced Query Builder
> >
> > > [tab] Overview
> > >
> > > A visual query builder for database operations and metadata filters, replacing manual JSON query writing with a structured interface. Build complex queries with conditions, grouping, and sorting without writing raw queries. The operator set has expanded with NULL checks (`exists`, `is null`), set membership (`not in`), string matching (`contains`, `starts with`, `ends with`), boolean tests (`is true`, `is false`), and date comparators (`before`, `after`). The `between` operator has been removed from the UI.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> > > >
> > > > See the FlowX Database documentation for the full query builder reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] Visual conditions
> > > >
> > > > Build query conditions with a structured UI instead of raw JSON
> > >
> > > > [card] Grouping and sorting
> > > >
> > > > Combine conditions with AND/OR grouping and configure result sorting
> > >
> > > > [card] Schema awareness
> > > >
> > > > Fields auto-populated from your collection schema with type-aware operators
> > >
> > > > [card] Visual/Script toggle
> > > >
> > > > Switch between visual builder and raw code editor at any time
> >
> > All Deployments
>
> ***
>
> ### **Oracle Database integration**
>
> > [card] Oracle Database integration
> >
> > > [tab] Overview
> > >
> > > Connect FlowX workflows to externally managed Oracle databases. Configure a connection (Oracle 19c, 21c, or 23ai), save parameterized SQL queries against the schema, and call them from the existing Database Operation node alongside other data sources.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> > > >
> > > > See the Oracle Database integration guide for the full reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] SERVICE\_NAME or SID
> > > >
> > > > Connect via Service Name or SID, with an optional SSL toggle
> > >
> > > > [card] Schema-aware SQL editor
> > > >
> > > > Monaco editor with syntax highlighting, autocomplete, and a side panel for tables, columns, primary keys, and foreign keys
> > >
> > > > [card] Test queries inline
> > > >
> > > > Run SQL with sample parameters: table view for SELECT, affected-row count for INSERT, UPDATE, and DELETE
> > >
> > > > [card] Workflow integration
> > > >
> > > > Pick the Oracle data source and query from the Database Operation node, with no new node type required
> >
> > All Deployments
>
> ***
>
> ### **Datasource Experience**
>
> > [card] Datasource Experience
> >
> > The **Add Data Source** dialog now groups data source types into four categories (**AI Capabilities**, **APIs**, **Databases**, and **Connectors**) with a search box for finding a specific type. REST endpoint authoring also suggests common HTTP headers and values to speed up integration setup.
> >
> > ![New Add Data Source dialog with categorized data source types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_new_data_source.png)
> >
> > All Deployments
>
> ***
>
> ### **MongoDB-aware code editor**
>
> > [card] MongoDB-aware code editor
> >
> > Operation editors on MongoDB data sources now use a Monaco language provider tuned for MongoDB. The editor highlights MongoDB operators (Comparison, Logical, Element, Evaluation, Array, Update, Aggregation, Conditional) and `${param}` interpolations, including inside string literals. Three autocomplete flows speed up authoring: typing `$` lists MongoDB operators, opening a quote in a field-name position lists the schema field paths from the linked Project Data Type, and typing inside `${...}` lists the operation's parameter keys.
> >
> > All Deployments
>
> ***
>
> ### **Project Data Model authoring**
>
> > [card] Project Data Model authoring
> >
> > Three improvements make Project Data Model authoring easier and less error-prone.
> >
> > > [card] Go to source
> > >
> > > A new **Go to source** button on data-model usages and Data Model nodes jumps directly to the source definition without manual navigation.
> >
> > > [card] Type-aware example values
> > >
> > > The example-value input on each attribute now matches its declared type: number inputs for NUMBER, a date picker for DATE, a true/false dropdown for BOOLEAN, single-select for enums, multi-select chips for enum arrays, and so on. CURRENCY values use the currency code rather than the symbol.
> >
> > > [card] Type-aware test data
> > >
> > > The same type-aware inputs apply when running or testing a workflow node and when filling input parameters for a reusable function, replacing the previous generic text inputs.
> >
> > All Deployments
>
> ***
>
> ### **Stop Run for workflows**
>
> > [card] Stop Run for workflows
> >
> > You can now cancel a running workflow instance directly from the workflow editor. While a workflow is running, the **Run Workflow** button switches to **Stop Run** — clicking it cancels the instance and marks all in-progress and scheduled nodes as cancelled. Cancelled instances show a new **Cancelled** status alongside Started, Finished, and Failed.
> >
> > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#running-and-stopping-workflows)
> > >
> > > See Running and stopping workflows in the Integration Designer reference.
> >
> > All Deployments
>
> ***
>
> ### **Merge conflicts UX**
>
> > [card] Merge conflicts UX
> >
> > The merge branches experience has been improved with a redesigned merge modal, better form validation with detailed error messages, and keyboard support (submit with Enter). The conflict resolution diff viewer now uses a new CodeMirror theme that matches the Monaco editor styling for a consistent visual experience.
> >
> > All Deployments
>
> ***

> [tab] Bug fixes
>
> ## Bug fixes
>
> ### AI Platform
>
> | Issue | Description |
> | - | - |
> | Custom Agent WebSocket stability | Fixed WebSocket 1006 abnormal closure for Custom Agent nodes with large payloads by upgrading AI SDK to handle Spring Framework 7's 64KB frame aggregation limit |
> | Azure OpenAI structured output | Fixed silent hang on Azure OpenAI for Custom Agents, Intent Classification, and Recommended Prompts when the response JSON schema lacked title and description fields |
> | Custom Agent node stuck | Fixed Custom Agent node getting stuck in running state |
> | MCP tool updates not working | Fixed an issue where updating tools on an existing MCP Server did not persist changes |
> | KB append performance | Fixed slow execution of the Append Knowledge Base node |
> | KB chunking on append | Fixed an issue where appended content via JSON in the Update Knowledge Base node was not chunked |
> | REST node with base64 certificate | Fixed error when running a workflow with a REST node using a REST system with a base64 certificate |
> | Workflow dependencies copy | Fixed dependencies not being copied for already-copied workflows |
>
> ### Core Platform
>
> | Issue | Description |
> | - | - |
> | Import pipeline issues | Fixed API issues in the import pipeline |
> | Enum CSV import losing changes | Fixed an issue where importing enumerations via CSV on committed resources did not update the resource modified date, causing changes to appear lost |
> | Data model duplicate key on import | Fixed a MongoDB duplicate key error when importing data model slices with duplicate entries |
> | Config params page not loading | Fixed GET config params endpoint not being called when accessing the Configuration Parameters page |
> | Enum default values dropdown | Fixed only first-level enum objects being displayed in the default values dropdown |
> | Data model loading state | Fixed user getting stuck in loading state after an error on data model keep operation |
>
> ### UI & Renderers
>
> | Issue | Description |
> | - | - |
> | Select component clear icon | Fixed misaligned clear icon on Select components in both Angular and React renderers |

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > **Self-hosted deployments:** FlowX 5.7.0 introduces the Organization ID as a mandatory configuration on all services. See the [deployment guidelines](./deployment-guidelines-v5.7) for complete upgrade instructions.
>
> ### Compatibility
>
> > [card] [Upgrade path](./deployment-guidelines-v5.7#supported-upgrade-paths)
> >
> > See the deployment guidelines for supported upgrade paths from 5.1.x LTS, 5.2–5.4, and 5.5–5.6.
>
> > [card] [Component versions](./deployment-guidelines-v5.7#component-versions)
> >
> > See the deployment guidelines for the full component version matrix and third-party dependency support.


# Deployment guidelines v5.8.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/deployment-guidelines-v5.8

Component versions, environment variables, and configuration changes for FlowX.AI 5.8.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.106.0** | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 |
| **admin** | **10.93.0** | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 |
| **designer** | **10.181.0** | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 |
| **cms-core** | **10.67.0** | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 |
| **scheduler-core** | **10.53.0** | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 |
| **events-gateway** | **10.55.0** | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 |
| **notification-plugin** | **10.64.0** | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 |
| **document-plugin** | **10.75.0** | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 |
| **task-management-plugin** | **10.66.0** | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 |
| **data-search** | **10.52.0** | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 |
| **audit-core** | **10.63.0** | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 |
| **advancing-controller** | **10.55.0** | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 |
| **integration-designer** | **10.128.0** | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 |
| **application-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **runtime-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **data-sync** | **10.58.0** | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 |
| **authorization-system** | **10.77.0** | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 |
| **nosql-db-runner** | **10.56.0** | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 |
| **email-gateway** | **10.56.0** | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 | - |
| **organization-manager** | **10.53.0** | 10.44.0 | 10.26.1 | 10.19.2 | - | - |
| **webhook-gateway** | **10.25.0** | 10.15.0 | 10.1.1 | - | - | - |
| **license** | **10.46.0** | 10.36.0 | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |

### Plugins

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 |
| **ai-platform-ai-assistant** | **10.7.0** | 10.6.2 | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **ai-platform-ai-developer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-connected-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-knowledge-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agents** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-conversations** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-tenants** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-analyst** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-designer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agent-builder** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-binaries** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **embedder** | **10.7.0** | 10.6.2 | - | - | - |
| **knowledgebase-rag** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **knowledgebase-indexer-v2** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **mcp** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **doc-parser** | **10.7.0** | 10.6.2 | 10.5.1 | - | - |
| **web-crawler** | **10.3.5** | 10.3.2 | - | - | - |
| **data-privacy** | **10.1.0** | 10.0.8 | - | - | - |
| **speech-to-text** | 10.3.3 | 10.3.3 | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | - | - | - |

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.8.0 | Keycloak | 26+ |
| 5.8.0 | Kafka | 3.8 - 3.9 |
| 5.8.0 | PostgreSQL | 16 - 17 |
| 5.8.0 | Oracle Database | 21c, 23ai |
| 5.8.0 | MongoDB | 7 - 8 |
| 5.8.0 | Redis | 7.4 - 8.0 |
| 5.8.0 | Elasticsearch | 8 |
| 5.8.0 | Angular (Web SDK) | 20 |
| 5.8.0 | React (Web SDK) | 18.x |

***

## Self-hosted deployment changes

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **5.7.0** | Supported | Standard upgrade. |
| **5.1.x LTS** | Supported | Direct upgrade from 5.1.x to 5.8.0 is supported. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

***

## Kafka integration changes

### New Kafka topics

| Topic | Producer | Producer env var | Consumer | Consumer env var |
| - | - | - | - | - |
| `ai.flowx.license.events.v1` | organization-manager | `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | license | `KAFKA_TOPIC_LICENSE_IN_EVENTS` |
| `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | admin | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` | knowledgebase-indexer-v2 | n/a (Python constant) | embedder | n/a (Python constant) |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` | embedder | n/a (Python constant) | knowledgebase-indexer-v2 | n/a (Python constant) |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | (no env var; resolved from `kafka.topic.naming.*`) | document-plugin | `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` |

**License lifecycle events** are delivered from FlowX SaaS to the on-prem license service.

**Custom-component correction requests** complement the existing process / business-rule / reusable-template / ui-flow correction topics that the admin orchestrator already consumed.

**UI Flow multi-file upload** sends a single bulk command to document-plugin in place of the per-file pattern. The plugin persists each file in the session, emits one SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) at the end of the batch via events-gateway, and forwards per-file results to the existing `ai.flowx.core.trigger.ui-flow.update.v1` topic.

**KB embedding-request / embedding-response** replace the previous gRPC `EmbedderService` path (`BulkGenerateEmbeddings` / `GenerateEmbeddings`); the indexer now publishes one embedding job per chunk and the embedder writes points to Qdrant directly, emitting `KbStoreEntryStateChanged` once all chunks for an entry are persisted.

> [!NOTE]
>
> The two `core-services` topic names (`license.events`, `application-version.correction-after-app-operation.custom-component.request`) resolve from the standard `${kafka.topic.naming.prefix}` / `${kafka.topic.naming.suffix}` machinery: default prefix `ai.flowx.` (empty environment segment), default suffix `.v1`. Operators that want an environment-prefixed topic name (e.g., `ai.flowx.dev.license.events.v1`) set `kafka.topic.naming.environment` globally rather than overriding individual topics. The two AI Platform topics are hard-coded constants in the indexer and embedder and do not participate in the prefix machinery.

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX. Initialized with the `notset` sentinel; replace it with the value FlowX provides before the license service starts. Type changed from UUID to String in 5.8.0. | `notset` | license |
| `KAFKA_CONSUMER_GROUPID_LICENSE_EVENTS` | Kafka consumer group used by the license service to receive license events. | `license-events` | license |
| `KAFKA_CONSUMER_THREADS_LICENSE_EVENTS` | Listener container concurrency for the license-events consumer. | `1` | license |
| `KAFKA_TOPIC_LICENSE_IN_EVENTS` | License events topic consumed by the license service. | `ai.flowx.license.events.v1` | license |
| `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | Same topic, producer-side binding on organization-manager. | `ai.flowx.license.events.v1` | organization-manager |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | Custom-component correction-request topic, producer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` | Same topic, consumer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | admin |
| `MANAGEMENT_HEALTH_REDIS_TIMEOUT` | Spring Boot Actuator timeout for the Redis health indicator (in ms). | `5000` | all services using Redis |
| `SPRING_CACHE_REDIS_PERSISTENCEKEYPREFIX` | Prefix applied to Redis keys for the advancing-controller cache. | `flowx:core:cache:advancing-controller:` | advancing-controller |
| `REDIS_COMMAND_TIMEOUT` | Redis command timeout in ms. Fail-fast during master failover. Bound via `${REDIS_COMMAND_TIMEOUT:5000}` placeholder on `spring.data.redis.timeout`. | `5000` | all services using Redis |
| `REDIS_CONNECT_TIMEOUT` | Redis connection establishment timeout in ms. Bound via `${REDIS_CONNECT_TIMEOUT:5000}`. | `5000` | all services using Redis |
| `REDIS_POOL_MAX_ACTIVE` | Maximum number of active Redis connections in the pool. | `10` | all services using Redis |
| `REDIS_POOL_MAX_IDLE` | Maximum number of idle Redis connections retained in the pool. | `5` | all services using Redis |
| `REDIS_POOL_MIN_IDLE` | Minimum number of idle Redis connections kept warm in the pool. | `1` | all services using Redis |
| `REDIS_POOL_MAX_WAIT` | Maximum time to wait for an available connection from the pool, in ms. | `2000` | all services using Redis |
| `FLOWX_METRICS_STUCKCHECKINTERVALMS` | Interval at which the stuck-events metric scheduler runs (ms). Bound from the inline `@Value("${flowx.metrics.stuck-check-interval-ms:60000}")` default; not in `application.yml`. | `60000` | advancing-controller |
| `FLOWX_METRICS_STUCKTHRESHOLDMINUTES` | Age threshold (in minutes) above which an advancing event is considered stuck. Bound from `@Value("${flowx.metrics.stuck-threshold-minutes:5}")`. | `5` | advancing-controller |
| `FLOWX_DATAPRIVACY_BASEURL` | Base URL for the new Data Privacy service. Required when any AI workflow node enables the Personal Information Guard. | `http://data-privacy:80` | integration-designer |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60` | integration-designer |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. Producer-side is the matching `kafka.topic.session.upload.bulk.out` on process-engine, which resolves from the standard naming machinery. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | document-plugin |

### Removed environment variables

| Environment Variable | Replaced by | Component |
| - | - | - |
| `FLOWX_SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Removed with the move to single-pod scheduler execution (plat-1549, `commons-scheduler-lib`). No replacement; only one scheduler pod runs now. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_ENABLED` | Same. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_PROVIDER` | Same. | application-manager, license |
| `SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Same. | integration-designer, process-engine |

***


# FlowX.AI 5.8.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/v5.8.0-may-2026

Runtime authorization overhaul, UI Flow permissions, Custom Components in Processes, new theme components, Angular bulk file upload, and webhook provider adapters.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

Sharing a FlowX solution used to mean handing out admin keys. **5.8.0 changes that.** The AI Developer now ships the React component you wished you'd had time to build, PII never reaches your LLM by accident, and you can finally invite a reviewer without giving them the platform.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html)

### What changed since 5.7.0

| 5.7.0 | 5.8.0 |
| - | - |
| End-user access management with org-level roles and groups | + **Runtime authorization** with project-version-scoped roles, groups, and attribute-based assignment |
| UI Flows accessible to any runtime user | + **UI Flow permissions**: assign roles per UI Flow, evaluated at runtime |
| Custom Components in UI Flows only (Phase 1, React) | + **Custom Components in Processes** with shared data model, input/output mappings, and AI Developer generation |
| Built-in UI components | + **Tooltip, Markdown, Progress Bar, Separator** as new theme components |
| React-only multi-file upload | + **Angular SDK bulk file upload** |
| Generic webhook gateway | + **Webhook provider adapters** (Slack, with HMAC signing-secret validation) |
| Oracle Database (basic SQL editor) | + **Richer SQL autocomplete** in the Monaco editor: operators, schema-aware tables/columns, and `:paramName` interpolations |
| No personal-information guardrails on AI workflow nodes | + **PII Guard** with input/output scans, sensitivity presets, and an entity catalog |

***

**What's new?**

> [tab] Platform
>
> 🔐 [**Runtime authorization**](#runtime-authorization) - Project-scoped roles, end-user groups in FlowX, and Solutions → Share flow\
> 📋 [**UI Flow permissions**](#ui-flow-permissions) - Role-based UI Flow visibility with runtime enforcement

> [tab] Builders
>
> 🧩 [**Custom Components in Processes**](#custom-components-in-processes) - Bundled CCs in Process User Tasks with shared data model\
> 🎨 [**New UI components**](#new-ui-components) - Tooltip, Markdown, Progress Bar, Separator\
> 📥 [**Angular bulk file upload**](#angular-bulk-file-upload) - Multi-file upload component for the Angular SDK\
> 📦 [**UI Flow multi-file upload backend**](#ui-flow-multi-file-upload-backend) - Single bulk endpoint and one completion SSE event for batch uploads\
> 🪝 [**Webhook provider adapters**](#webhook-provider-adapters) - Slack inbound webhook support with HMAC signing\
> 🗄️ [**Richer SQL autocomplete**](#richer-sql-autocomplete) - Monaco editor enhancements for the Oracle data source SQL editor\
> 🧱 [**Data source UX redesign**](#data-source-ux-redesign) - Tile-based creation, type filters, unified settings, save with incomplete config\
> ➕ [**Context menu adds UI components in Processes**](#context-menu-adds-ui-components-in-processes) - Right-click Add UI component in Process User Tasks and Reusable UI Templates\
> 👆 [**Pointer cursor on actionable elements**](#pointer-cursor-on-actionable-elements) - Web renderers show pointer on action-bound components

> [tab] AI Platform
>
> 🛡️ [**PII Guard**](#pii-guard) - Personal information identification on AI inputs\
> 🤖 [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent now drafts Custom Component code\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - System metadata keys, Kafka indexer→embedder, Qdrant export/delete, error handling\
> 🌐 [**Web Crawler multi-URL filters**](#web-crawler-multi-url-filters) - Multiple URL filters per crawler config

### **Runtime authorization**

> [card] Runtime authorization overhaul
>
> > [tab] Overview
> >
> > **Before 5.8.0:** a role on a user matched every project that role appeared in. **Now:** roles live at the project version, sharing is explicit, and Designer users still bypass runtime so they can demo without standing up test accounts.
> >
> > Runtime access is reorganized around the project. Roles live at the **project version**, each org has a managed catalog of **end-user groups**, and access flows through a **Solutions → Share** modal. FlowX retains authentication and external-IDP federation in Keycloak; runtime roles, end-user groups, and project-scoped sharing live in FlowX itself, evaluated by a custom runtime authorization service tuned for the volume of runtime permission checks. SpiceDB remains the design-time permission engine for Designer access.
> >
> > > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> > >
> > > See Setup guides → Access management → Runtime authorization.
>
> > [tab] Key Features
> >
> > > [card] Project-scoped roles
> > >
> > > Each project version declares the runtime roles required to operate it. Roles are org-level entities, defined once and reusable across projects and libraries.
> >
> > > [card] Default `user` role on creation
> > >
> > > New projects spawn with a default `user` role so a fresh project is reachable on day one without extra wiring.
> >
> > > [card] Sharing from Solutions
> > >
> > > The Solutions page gains a **Share** modal. Pick a user or end-user group, assign a role, and the user can launch the solution at runtime.
> >
> > > [card] End-user groups in FlowX
> > >
> > > Groups previously managed in Keycloak now live in FlowX. Recommended pattern: an "All End Users" group per single-role solution; one group per role for multi-role solutions.
> >
> > > [card] Process swimlane roles
> > >
> > > BPMN swimlanes assign view, execute, and self-assign permissions per role.
> >
> > > [card] Designer-user bypass
> > >
> > > Designer users can run any project they have designer access to without holding a runtime role; they auto-receive view, execute, and self-assign on every swimlane.
> >
> > > [card] Active Policy gate
> > >
> > > The Share modal lists only roles defined in the build set as **Active Policy** for the project. Roles defined in a non-active build do not appear until promoted.
>
> > [tab] Architecture
> >
> > The 5.8.0 release introduces a clear split between authentication and runtime authorization:
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Authentication, sessions, MFA | Keycloak | Unchanged |
> > | External IDP federation | Keycloak | Configured per organization |
> > | User attributes (business filters) | Keycloak | Source of truth for token claims |
> > | Runtime roles | FlowX (custom CAS) | Defined per project version, evaluated at runtime |
> > | End-user groups | FlowX (custom CAS) | Replaces Keycloak group management |
> > | Project-scoped sharing | FlowX (custom CAS) | Solutions → Share modal |
> > | Design-time permissions | FlowX SpiceDB | Designer UI access; unchanged from prior releases |
> >
> > A `designer-user` Keycloak attribute is auto-managed on each user (`true` for designer users, `false` for end-users), with a mapper on the `flowx-platform-authenticate` client so the engine can check it cheaply on the access token.
>
> > [tab] Migration
> >
> > > [!WARNING]
> > >
> > > **Sharing settings do not export between environments or workspaces.** Configure sharing per environment as a deliberate step when promoting a project to a higher environment.
> >
> > Sharing data does not travel with the project export, so promoting a build from one environment to another (for example, dev to staging) requires a sharing pass in the target environment. Treat it as an explicit step in your deployment checklist.
> >
> > Existing FlowX organizations migrate as follows:
> >
> > * Roles previously assigned directly to users continue to work for backward compatibility while you rebuild assignments under the project-scoped model.
> > * End-user groups configured in Keycloak are migrated into FlowX and become the authoritative source going forward.
> > * Existing UI Flows receive the project-level **User** role automatically as their default allowed role on upgrade. See the [UI Flow permissions](#ui-flow-permissions) section for next steps.
>
> All Deployments

### **UI Flow permissions**

> [card] UI Flow permissions
>
> > [tab] Overview
> >
> > **Before 5.8.0:** every UI Flow was reachable by anyone with runtime access. **Now:** each UI Flow carries its own allow-list and components inside it can be hidden or disabled per role.
> >
> > Each UI Flow now carries a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API. Inside a UI Flow session, individual components can be hidden or disabled by permission-based rules evaluated at runtime against the user's permission set.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> > >
> > > See UI Flows → UI Flow permissions.
>
> > [tab] Key Features
> >
> > > [card] Permissions page
> > >
> > > A new **Settings → Permissions** page in the UI Flow editor lets you assign one or more runtime roles to each UI Flow.
> >
> > > [card] Default role on creation
> > >
> > > New UI Flows receive the project-level **User** role by default so they are reachable on day one; tighten the list before deploying.
> >
> > > [card] Per-component hide/disable
> > >
> > > Components can be hidden or made readonly based on the user's runtime permissions, using the same hide/disable rule machinery as JavaScript expressions.
> >
> > > [card] Permission toast
> > >
> > > Users without the required role see a permission toast in the Designer-hosted runtime preview; the deployed app returns 403 from the start endpoint.
> >
> > > [card] Input-parameter validation
> > >
> > > Input parameters are validated against the UI Flow's input schema before the session is created.
> >
> > > [card] Travels with import/export
> > >
> > > Allowed roles are saved on the UI Flow resource and travel with project export/import.
>
> > [tab] Migration
> >
> > UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.
>
> All Deployments

### **Custom Components in Processes**

> [card] Custom Components in Processes
>
> > [tab] Overview
> >
> > **Before 5.8.0:** Custom Components only ran in UI Flows. **Now:** drag one onto a Process User Task and the React SDK applies the input/output mappings at runtime.
> >
> > Bundled Custom Components, previously only usable in UI Flows, now render in **Process User Tasks**. Each Custom Component carries its own **data model** with explicit input and output slices, and you map process data into and out of the component at each use site. Renderer support ships in the React SDK.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components#using-custom-components-in-process-user-tasks)
> > >
> > > See Custom Components → Using Custom Components in Process User Tasks.
>
> > [tab] Key Features
> >
> > > [card] Process User Task host
> > >
> > > Drag a Custom Component onto a Process User Task layout the same way you do in UI Flows.
> >
> > > [card] Custom Component data model
> > >
> > > Each Custom Component declares its own data model. The Designer keeps input and output slices isolated so the component contract is clear at every use site.
> >
> > > [card] INPUT mappings
> > >
> > > Map process data attributes onto the Custom Component's input slice at runtime, so the component receives only the data it declared.
> >
> > > [card] OUTPUT mappings
> > >
> > > When the component triggers an action, the React SDK applies the configured OUTPUT mappings before piping `saveData` back to process variables.
> >
> > > [card] Test with sample inputs
> > >
> > > The Custom Component editor lets you fill input params with sample data for in-Designer preview, mirroring the UI Flow test flow.
> >
> > > [card] Import and export
> > >
> > > Custom Components export and import alongside the data model and mappings so a component travels intact between projects.
>
> > [tab] Limitations
> >
> > Phase 1 limitations from 5.7.0 still apply: React SDK only (no Angular renderer), pre-defined dependency set (React, Emotion, Lodash, Axios, date-fns), browser-side bundling, and client-side rendering only. See the [Custom Components limitations](/5.9/docs/building-blocks/reusable-resources/custom-components#limitations-phase-1) section.
>
> All Deployments

### **New UI components**

> [card] New UI components
>
> Four new theme components ship with renderer parity across React, Angular, and Android SDKs.
>
> > [card] [Tooltip](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Contextual hint anchored to any UI element. Configurable text (static, local variable, or computed expression), position handling, and an optional icon.
>
> > [card] [Markdown](/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown)
> >
> > Render Markdown content from a static string or computed expression, with localization formatting for numbers, dates, and currency. Six heading levels and link styling are theme-driven.
>
> > [card] [Progress Bar](/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar)
> >
> > Visual progress indicator. Set a value between `0` and `1` from a static value, local variable, or computed expression.
>
> > [card] [Separator](/5.9/docs/building-blocks/ui-designer/ui-component-types/separator)
> >
> > Visual divider with theme-driven color. Adjustable height for layout spacing.
>
> All four are exposed in the **Theme Admin** sidebar so theme overrides cascade through templates.
>
> All Deployments

### **Angular bulk file upload**

> [card] Angular bulk file upload
>
> > [tab] Overview
> >
> > The **Multiple File Upload** component (`BULK_FILE_UPLOAD`), previously available only in the React SDK, now ships in the Angular SDK with the same drag-and-drop area and theming. Existing UI Flows that use the component render across React and Angular containers without configuration changes.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> > >
> > > See the Multiple File Upload component reference.
>
> > [tab] Key Features
> >
> > > [card] Renderer parity
> > >
> > > Same component, same configuration, same theming across React and Angular containers.
> >
> > > [card] Drag-and-drop area
> > >
> > > Drop zone with click-to-browse fallback in both renderers.
> >
> > > [card] Theme-driven
> > >
> > > The component picks up theme overrides for typography, colors, and spacing the same way as built-in components.
> >
> > > [card] No flow changes needed
> > >
> > > UI Flows authored before 5.8.0 render in the Angular SDK without edits.
>
> All Deployments

### **UI Flow multi-file upload backend**

> [card] UI Flow multi-file upload backend
>
> > [tab] Overview
> >
> > Multi-file uploads from UI Flows now use a dedicated bulk endpoint and a single completion event in place of the per-file pattern. The upload action accepts a list of temp-file IDs in one request and the SDK receives a single SSE frame when the batch is persisted.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload#ui-flow-upload-flow)
> > >
> > > See Multiple file upload → UI Flow upload flow.
>
> > [tab] Key Features
> >
> > > [card] Single bulk endpoint
> > >
> > > `POST /ui-flow/{uiFlowSessionId}/upload-multiple` accepts a list of temp-file IDs and returns a server-generated `uploadBatchId`.
> >
> > > [card] Single completion event
> > >
> > > One SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) delivers per-file results once the batch is persisted.
> >
> > > [card] New Kafka topic
> > >
> > > `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` carries the bulk command from process-engine to document-plugin.
> >
> > > [card] Session variable mapping
> > >
> > > Per-file results are stored as a list under the upload action's `responseKey` in the UI Flow session.
>
> All Deployments

### **Webhook provider adapters**

> [card] Webhook provider adapters
>
> > [tab] Overview
> >
> > Inbound webhook registrations now select a **provider**: `GENERIC` or `SLACK`. The Slack adapter performs HMAC-SHA256 signature validation against the Slack signing secret on every request, including the `X-Slack-Request-Timestamp` skew check (5 minutes). Provider-segmented URLs (`/webhooks/incoming/slack/...`) keep generic and provider-specific registrations isolated. Future providers plug in behind the same `InboundProviderAdapter` interface without changing the URL contract.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#provider-adapters)
> > >
> > > See Incoming webhooks → Provider adapters.
>
> > [tab] Key Features
> >
> > > [card] Slack signature validation
> > >
> > > HMAC-SHA256 on `X-Slack-Signature`, with timestamp skew enforced
> >
> > > [card] Slack URL-verification handshake
> > >
> > > The gateway answers Slack's `url_verification` challenge automatically
> >
> > > [card] Provider-segmented URLs
> > >
> > > `/webhooks/incoming/{provider}/...` keeps providers isolated; mismatch returns 400
> >
> > > [card] Independent secret rotation
> > >
> > > Rotate the provider signing secret without touching the FlowX API key
> >
> > > [card] Settings tab
> > >
> > > Provider + signing secret moved to a dedicated Settings tab on the webhook system
> >
> > > [card] Pluggable
> > >
> > > New providers add an adapter and an enum value; no URL or registration schema changes
>
> All Deployments

### **Richer SQL autocomplete**

> [card] Richer SQL autocomplete
>
> > [tab] Overview
> >
> > The Monaco editor on the Oracle Database data source now ships with a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `:paramName` interpolations resolved from the parameters panel.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database#sql-editor)
> > >
> > > See the Oracle Database SQL editor documentation.
>
> > [tab] Key Features
> >
> > > [card] Keywords and operators
> > >
> > > Full SQL language definition powers keyword highlighting and completion.
> >
> > > [card] Schema-aware suggestions
> > >
> > > Tables and columns parsed from the saved schema context appear in completion lists.
> >
> > > [card] Parameter interpolation
> > >
> > > `:paramName` placeholders resolve against the parameters panel for inline preview.
> >
> > > [card] Editor consistency
> > >
> > > Matches the editor experience used by other code surfaces in the Designer.
>
> All Deployments

### **Data source UX redesign**

> [card] Data source UX redesign
>
> > [tab] Overview
> >
> > The Data Sources resource page is rebuilt around a tile-based creation flow and a unified details view. Each data source type has its own icon and a dedicated tile in the **New Data Source** modal, with a search box that filters tiles as you type. The list view shows the type next to each entry and adds a type filter so you can scope the list by connector. Settings panels for every data source type are normalized to the same card-based layout.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer reference for data source configuration.
>
> > [tab] Key Features
> >
> > > [card] Tile-based creation modal
> > >
> > > The **New Data Source** modal lists every connector type as a searchable tile, replacing the previous type dropdown.
> >
> > > [card] Type icons in the list
> > >
> > > Each entry in the data sources list shows the connector's icon and type, so a long list is easier to scan.
> >
> > > [card] Filter by type
> > >
> > > Filter the list to a specific connector type (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.) without scrolling.
> >
> > > [card] Unified settings layout
> > >
> > > Every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
> >
> > > [card] Save with incomplete config
> > >
> > > Create and save a data source even when some fields (credentials, endpoints) are not yet available. You can reference the data source in workflows and processes immediately and finish the configuration later — the data source will only operate at runtime once required fields are filled in.
>
> All Deployments

### **PII Guard**

> [card] Personal Information Guard
>
> > [tab] Overview
> >
> > **Before 5.8.0:** data-sensitive customers couldn't enable AI workflow nodes at all. **Now:** every AI node carries a per-node guardrail with sensitivity presets, scan directions, and a fail-closed contract.
> >
> > AI workflow nodes gain a per-node guardrail that detects and replaces personal information before it reaches the LLM and, optionally, scans LLM output before it flows downstream. The guard runs against the new **Data Privacy** service, configured per node with sensitivity presets, scan directions, and an entity catalog organized into Universal, Regional EN, and Regional RO scopes. Iteration 1 covers Custom Agent, Intent Classification, Extract Data from File, and all AI Text, Document, Image, and Data Operations, including Document Generation.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See Personal Information Guard.
>
> > [tab] Key Features
> >
> > > [card] Per-node toggle
> > >
> > > Enable on any AI node. Choose a sensitivity preset (Strict / Balanced / Relaxed) or set a custom threshold.
> >
> > > [card] Input and output scans
> > >
> > > Redacts inputs and `systemPrompt` before the LLM call; optionally scans LLM output before it leaves the node.
> >
> > > [card] File redaction
> > >
> > > Document and image nodes get a redacted source artifact uploaded back to the same storage; the file binding is swapped automatically.
> >
> > > [card] Entity catalog
> > >
> > > 24 entity types (email, phone, IBAN, etc.) grouped under Universal, Regional EN, and Regional RO. Modal supports search and section-level Select All.
> >
> > > [card] System-prompt appender
> > >
> > > Custom Agent nodes get a non-editable system-prompt segment teaching the LLM how to handle `<PII type=.../>` placeholders.
> >
> > > [card] Fail-closed
> > >
> > > Any error from the Data Privacy service stops node execution and surfaces on the run log; no partially-redacted prompts reach the LLM.
> >
> > > [card] Run-log visibility
> > >
> > > Each scan reports status, per-entity detection counts, and (for file scans) original and redacted storage paths.
> >
> > > [card] New Data Privacy service
> > >
> > > Backed by Presidio. Configured via `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` on integration-designer.
>
> All Deployments

### **Knowledge Base enhancements**

> [card] Knowledge Base
>
> > [tab] Overview
> >
> > Knowledge Bases gain richer metadata and a more resilient indexing path. Stores and chunks expose system metadata fields you can filter on in the Test KB modal and the Custom Agent node, the indexer and embedder communicate over Kafka instead of synchronous calls, and the Update Knowledge Base node can ingest files by path from inside a workflow.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See Knowledge Base → Overview.
>
> > [tab] Key Features
> >
> > > [card] System metadata on stores
> > >
> > > Filter entries by `Source` (Manual or Workflow), `Uploaded`, `Doc name`, `Doc type`, `Doc pages`, and `Store origin`
> >
> > > [card] System metadata on chunks
> > >
> > > Filter chunks by `Chunk counter`, `Chunk type`, `Chunk section`, `Chunk page start`, and `Chunk entry`
> >
> > > [card] Kafka between indexer and embedder
> > >
> > > Replaces the previous synchronous gRPC path; per-chunk embedding requests flow through `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1`
> >
> > > [card] Delete chunks from Qdrant
> > >
> > > Indexer forwards a delete job to the embedder, which removes matching points from Qdrant when an entry is deleted
> >
> > > [card] File path mode in Update KB node
> > >
> > > The Update Knowledge Base node accepts `contentType: FILE_PATH` so workflows can ingest content uploaded earlier in the run
> >
> > > [card] Doc pages in agent stream
> > >
> > > Custom Agent streaming responses include `doc_pages` and chunk metadata (counter, type, section, page start) for richer trace and debug
>
> All Deployments

### **Web Crawler multi-URL filters**

> [card] Web Crawler multi-URL filters
>
> > [tab] Overview
> >
> > The Web Crawler node now accepts up to 20 URL filter patterns per crawler configuration. Open the **URL Filters** modal on the Web Crawler node, add one row per pattern, and the crawler restricts its breadth-first traversal to URLs that match any of the configured filters.
> >
> > > [card] [Documentation](/5.9/setup-guides/web-crawler-setup)
> > >
> > > See the Web Crawler setup guide.
>
> > [tab] Key Features
> >
> > > [card] Up to 20 patterns per crawler
> > >
> > > Add one row per pattern in the URL Filters modal; deep crawls match any pattern.
> >
> > > [card] Replaces single-string filter
> > >
> > > The previous single-string filter is superseded by the new multi-pattern array. Existing crawlers are migrated automatically.
> >
> > > [card] Breadth-first scoping
> > >
> > > Filters apply to the crawler's breadth-first traversal so deep crawls stay within the intended scope.
> >
> > > [card] Per-pattern tuning
> > >
> > > Combine narrow and broad patterns in one configuration to handle multi-section sites without spawning multiple crawlers.
>
> All Deployments

### **AI Developer generates Custom Components**

> [card] AI Developer generates Custom Components
>
> > [tab] Overview
> >
> > **Before 5.8.0:** the AI Developer wrote business rules and JS expressions. **Now:** it ships entire React Custom Components — JSX, CSS, `package.json`, and sample input data — in one prompt.
> >
> > The AI Developer pre-built agent gains a **Generate Custom Component** action and an **Edit Custom Component** action. From the Designer's AI command center, describe the component you want, and the agent returns a complete React bundle (JSX, CSS, `package.json`, and sample input data) that you can preview, accept, or iterate on. The same conversation can edit existing components.
> >
> > > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> > >
> > > See AI Developer → Pre-built agents.
>
> > [tab] Key Features
> >
> > > [card] Generate from natural language
> > >
> > > Describe a component in plain language; receive JSX, CSS, `package.json`, and sample input data in one response.
> >
> > > [card] Sample input field
> > >
> > > A dedicated input field lets you provide preview data so the generated component renders meaningfully on first run.
> >
> > > [card] Edit existing components
> > >
> > > Iterate on a generated or hand-authored component through the same conversation. The agent keeps the component context.
> >
> > > [card] Inline preview
> > >
> > > The Designer's Preview area renders the generated bundle next to the conversation so you can validate before saving.
> >
> > > [card] Dependency summary
> > >
> > > A new dependency summary panel surfaces the npm packages the agent included in `package.json`.
> >
> > > [card] Keep / Discard
> > >
> > > Accept the generated bundle into the workspace or discard it without leaving the conversation.
>
> > [tab] Limitations
> >
> > The first iteration generates the component code, styles, and input parameters. Wiring component actions to host-side handlers (Process or UI Flow actions) is not yet inferred — connect actions manually after accepting the generated bundle.
>
> All Deployments

### **iframe logout postMessage contract**

> [card] iframe logout postMessage
>
> The runtime SaaS app now notifies an iframe parent when a user logs out. When the parent passes a `parentOrigin` query parameter on the `/{orgCode}/logout` URL, the runtime posts `{ type: 'logout-success' }` to `window.parent` immediately before the sign-out redirect. Host applications that embed the FlowX runtime in an iframe can listen for this message and react (clear local state, navigate, surface a UI cue) without polling the iframe URL.
>
> All Deployments

### **Context menu adds UI components in Processes**

> [card] Right-click Add UI component in Processes and Reusable UI Templates
>
> The right-click contextual menu for adding a UI component, previously available only in UI Flows, now works in **Process User Tasks** and **Reusable UI Templates** as well. Right-click a node in the components hierarchy panel to insert any allowed child component without dragging from the palette. Copy and paste styles are also exposed from the same menu.
>
> All Deployments

### **Pointer cursor on actionable elements**

> [card] Pointer cursor on actionable elements
>
> Web renderers now switch the cursor to a pointer when hovering over any UI component bound to an action, matching standard web affordances. No configuration change is required — the new behavior applies automatically to elements that already declare an action role.
>
> All Deployments

### **"Process Data" → "Local Variables" rename**

> [card] Process Data renamed to Local Variables
>
> In the UI Designer, the **Process Data** label is now displayed as **Local Variables** when you are editing a UI Flow or a Reusable UI Template. Process editing is unchanged and continues to use **Process Data**. The data source key and binding behavior are identical; only the user-visible label changed, so existing flows continue to work without any update.
>
> All Deployments

### **License billing guards**

> [card] License billing guards
>
> The license service no longer creates billing plans for periods past an organization's subscription end date. This prevents stale plan rows from accumulating after a subscription expires and aligns the on-prem billing trail with the SaaS-side license lifecycle.
>
> Self-Hosted

### **Speech-to-text and Web Crawler in AI consumption**

> [card] Speech-to-text and Web Crawler in AI consumption
>
> AI consumption tracking now includes Speech-to-text and Web Crawler workflow nodes alongside the existing AI Text, Document, Image, and Data Operations. Organizations on AI consumption-based plans see usage and billing reflected for these nodes from 5.8.0 onward.
>
> All Deployments

***

## Shipped by

This release is the work of the FlowX engineering team — backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.8.0](./deployment-guidelines-v5.8).


# Deployment guidelines v5.9.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9

Component versions, environment variables, and configuration changes for FlowX.AI 5.9.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

> [!NOTE]
>
> **Upgrading from 5.1.x LTS?** This page describes the steady-state 5.9.0 deployment. For the architecture delta, deprecation list, and upgrade steps, see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Deployment packaging.** 5.9.x is the last LTS release distributed as a multi-chart deployment, where each FlowX service is installed from its own Helm chart.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

The following tables list component versions per FlowX.AI release. Verify your installed versions against the 5.9.0 column in **FlowX.AI Designer → Platform Status**.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **process-engine** | 10.135.0 | 10.106.0 | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 |
| **admin** | 10.116.0 | 10.93.0 | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 |
| **designer** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 |
| **cms-core** | 10.86.0 | 10.67.0 | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 |
| **scheduler-core** | 10.70.0 | 10.53.0 | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 |
| **events-gateway** | 10.72.0 | 10.55.0 | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 |
| **notification-plugin** | 10.83.0 | 10.64.0 | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 |
| **document-plugin** | 10.94.0 | 10.75.0 | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 |
| **task-management-plugin** | 10.84.0 | 10.66.0 | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |
| **data-search** | 10.69.0 | 10.52.0 | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 |
| **audit-core** | 10.79.0 | 10.63.0 | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 |
| **advancing-controller** | 10.73.0 | 10.55.0 | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 |
| **integration-designer** | 10.162.0 | 10.128.0 | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 |
| **application-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **runtime-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **data-sync** | 10.81.0 | 10.58.0 | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 |
| **authorization-system** | 10.96.1 | 10.77.0 | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 |
| **nosql-db-runner** | 10.75.0 | 10.56.0 | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 |
| **email-gateway** | 10.74.0 | 10.56.0 | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 |
| **organization-manager** | 10.71.0 | 10.53.0 | 10.44.0 | 10.26.1 | 10.19.2 | - |
| **webhook-gateway** | 10.44.0 | 10.25.0 | 10.15.0 | 10.1.1 | - | - |
| **file-gateway** | 10.8.0 | - | - | - | - | - |
| **license** | 10.63.0 | 10.46.0 | 10.36.0 | - | - | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB**
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-native-sdk** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-theme** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-ui-toolkit** | 10.230.2 | - | - | - | - | - |
| **@flowx/core-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/core-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **react-saas** | 10.230.2 | - | - | - | - | - |
| **iOS renderer** | 10.4.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |
| **Android renderer** | 10.5.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |

The **react-saas** container app tracks the designer version.

### Plugins

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-knowledgebase-rag** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-embedder** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **doc-parser** | 10.9.0 | 10.7.0 | 10.6.2 | 10.5.1 | - | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-agent-builder** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **data-privacy** | 10.1.0 | 10.1.0 | 10.0.8 | - | - | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **evals-judge** | 10.1.1 | - | - | - | - | - |
| **speech-to-text** | 10.3.4 | 10.3.3 | 10.3.3 | - | - | - |
| **web-crawler** | 10.3.5 | 10.3.5 | 10.3.2 | - | - | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-gateway** | 10.7.0 | - | - | - | - | - |
| **ai-platform-ai-analyst** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-assistant** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **ai-platform-ai-designer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-developer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **di-platform** | 10.3.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **flowx-docs** | 5.9.0 | - | - | - | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - | - | - |
| **ai-observatory** | 10.3.2 | - | - | - | - | - |

***

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

***

## Kafka topics

### Document-plugin archive and extract listeners

5.9.0 exposes four Kafka topics for the document-plugin **archive** and **extract** operations. Both follow the encrypt/decrypt trigger and reply pattern: document-plugin consumes the `trigger.*.file` topic and process-engine consumes the matching `engine.receive.*.file.results` reply.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.archive.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.extract.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` | document-plugin | process-engine |

The four topic names are exposed as env vars on the document-plugin side (`KAFKA_TOPIC_FILE_ARCHIVE_IN`, `KAFKA_TOPIC_FILE_ARCHIVE_OUT`, `KAFKA_TOPIC_FILE_EXTRACT_IN`, `KAFKA_TOPIC_FILE_EXTRACT_OUT`). See [Documents plugin setup → File archive / File extract](/5.9/setup-guides/documents-plugin-setup#file-archive). Two new thread-pool entries are added: `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN` and `..._FILEEXTRACTIN`, both defaulting to `5`.

### Document-plugin encrypt and decrypt listeners

The **encrypt** and **decrypt** operations follow the same trigger-and-reply pattern: process-engine produces the `trigger.*.file` topic and document-plugin replies on the matching `engine.receive.*.file.results` topic.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | document-plugin | process-engine |

The topic names are exposed as env vars on the document-plugin side: `KAFKA_TOPIC_FILE_ENCRYPT_IN`, `KAFKA_TOPIC_FILE_ENCRYPT_OUT`, `KAFKA_TOPIC_FILE_DECRYPT_IN`, `KAFKA_TOPIC_FILE_DECRYPT_OUT`.

### Document-plugin session-upload listeners

Multi-file upload for UI flows routes uploaded files to the document-plugin for persistence. process-engine produces the trigger topic and document-plugin consumes it — `session` for a single upload session and `session.bulk` for batched multi-file uploads.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | process-engine | document-plugin |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | document-plugin |

The topic names are exposed on process-engine as `KAFKA_TOPIC_SESSION_UPLOAD_OUT` and `KAFKA_TOPIC_SESSION_UPLOAD_BULK_OUT`, and on document-plugin as `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN` and `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN`.

### AI Platform job topics

`integration-designer` dispatches asynchronous jobs to the standalone AI services over Kafka, using a request/response pair per service. Provision these topics when you deploy the corresponding AI service (see [AI components](#ai-components) above).

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.ai-platform.doc-parser.job.request.v1` | integration-designer | doc-parser |
| `ai.flowx.ai-platform.doc-parser.job.response.v1` | doc-parser | integration-designer |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | integration-designer | evals-judge |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | evals-judge | integration-designer |
| `ai.flowx.ai-platform.speech-to-text.job.request.v1` | integration-designer | speech-to-text |
| `ai.flowx.ai-platform.speech-to-text.job.response.v1` | speech-to-text | integration-designer |

On `integration-designer` the topic names are set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_REQUEST_OUT` and `..._RESPONSE_IN` (for example `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`). Each service also has a dead-letter topic — `ai.flowx.ai-platform.<service>.job.dlq.v1`, set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_DLQ_IN` — that integration-designer consumes for failed jobs.

### UI Flow runtime triggers

process-engine consumes two trigger topics that back the UI Flow runtime cache and expiration features. `update` invalidates a cached UI Flow when its definition changes; `expire` removes expired UI Flow runtime data.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer | process-engine |
| `ai.flowx.core.trigger.expire.ui-flow.v1` | scheduler-core | process-engine |

On process-engine these are set via `KAFKA_TOPIC_UIFLOW_UPDATE_IN` and `KAFKA_TOPIC_UIFLOW_EXPIRE_IN`; the producers expose `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`. The expire trigger uses the platform scheduler: when a UI Flow session is created, process-engine registers a delayed message with scheduler-core, which publishes it back to this topic at the expiry time. It is consumed by a dedicated consumer group (`KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE`, default `ui-flow-expire`).

### File and webhook process triggers

Two trigger topics let the file-gateway and webhook-gateway start or resume processes in process-engine. The **start-for-event** topic starts a process when a watched file arrives (file-gateway) or an incoming webhook fires (webhook-gateway); the **message event** topic resumes a running process that is waiting on an intermediate message catch event.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | file-gateway, webhook-gateway | process-engine |
| `ai.flowx.core.message.event.process.v1` | webhook-gateway | process-engine |

On the producers, the start-for-event topic is set via `KAFKA_TOPIC_TRIGGER_STARTFOREVENT_PROCESS_OUT` (file-gateway) and `KAFKA_TOPIC_PROCESS_START_OUT` (webhook-gateway); process-engine consumes it via `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`. The message event topic uses `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` on both webhook-gateway and process-engine. Like every service, file-gateway and webhook-gateway also publish to the shared audit topic `ai.flowx.core.trigger.save.audit.v1` via `KAFKA_TOPIC_AUDIT_OUT` (consumed by audit-core).

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Data-sync: Keycloak admin credentials

The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak on first run, using the Keycloak admin API. Configure the following on the data-sync job:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak` (the only supported provider). | `keycloak` | data-sync |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` | data-sync |
| `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` | data-sync |
| `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` | data-sync |
| `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Typically `admin-cli` for standard Keycloak deployments. Must be set explicitly. There is no default. | `-` | data-sync |

For full data-sync configuration, see [Data-sync job setup](/5.9/setup-guides/data-sync#openid-provider-configuration).

### Anonymous service account: shared client secret

5.9.x introduces a single shared service-account client, `flowx-anonymous-sa`, used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows. One client secret is reused across all consumers — it must be provided in two places.

**On `authorization-system`** — passed to Liquibase so the client is provisioned with the correct secret when FlowX manages Keycloak:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXANONYMOUSSA` | Client secret used by Liquibase to create the `flowx-anonymous-sa` client in the service-accounts realm at first boot. Required when `SECURITY_KEYCLOAKADMINENABLED=true`. | `-` | `authorization-system` |

**On every consuming service** — the Spring Security OAuth2 client registration for the `anonymousidentity` alias resolves the same secret at runtime:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Client secret for the `anonymousidentity` registration. **Must be the same value across every service** — it is a single shared service account. | `-` | `admin`, `application-manager`, `authorization-system`, `document-plugin`, `email-gateway`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `mock-server`, `nosql-db-runner`, `organization-manager`, `process-engine`, `scheduler-core`, `task-management-plugin`, `webhook-gateway` |

> [!WARNING]
>
> This is a secret. Store it in your secrets management solution (e.g., Kubernetes Secret, Vault) and reference it from there. Never commit it to version control.

For the Keycloak-side context (`flowx-anonymous-sa` client, `SA_FLOWX_ANONYMOUS` realm role, manual-configuration recipe for deployments without Keycloak admin access), see [Manual Keycloak configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).

### Knowledgebase-rag: Qdrant search tuning

Two env vars control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Defaults are tunable per environment.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. | `100` | knowledgebase-rag |
| `QDRANT_FUSION_LIMIT` | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker input. | `80` | knowledgebase-rag |

Raise both when recall is insufficient on very large or long-tailed Knowledge Bases. Lower them when Qdrant pods report memory pressure or filter-heavy queries time out.

### CORS handling: `APPLICATION_CORS_ALLOWORIGIN`

CORS is enforced at the application layer. Each backend service exposed via admin or public URLs reads its allowed-origin list from a single environment variable. Allowed methods, allowed headers, exposed headers, and credential handling are baked into each service's `application.yaml` with safe defaults. The 5.9.x default allow-headers set is `Accept, Content-Type, Authorization, Fx-Workspace-Id, Fx-Client-Host, Referer, User-Agent, Flowx-Platform, X-Fx-Anonymous-Session-Id, Fx-BuildId, Fx-AppId`, and `X-Fx-Anonymous-Session-Id` is exposed to the browser for anonymous runtime sessions. Only `APPLICATION_CORS_ALLOWORIGIN` is deployment-specific.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains (`https://*.yourcompany.com`). Must include every Designer, runtime renderer, and integration domain that calls FlowX APIs. | `-` | `admin`, `ai-gateway`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway` |
| `APPLICATION_CORS_EXPOSEDHEADERS` | Response headers exposed to browser JavaScript. The default carries the anonymous-session header; override only if you need to expose additional custom headers. | `X-Fx-Anonymous-Session-Id` | all services (shared security library) |

For migration guidance and the full list of removed NGINX CORS annotations, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

### Process-engine and integration-designer: native script engine

The default script engine for JavaScript and Python execution is a **native subprocess pool**. Scripts run in isolated Node.js and Python worker processes.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider | `native` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size | `16` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary | `/usr/bin/node` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS script execution timeout (ms) | `5000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a JS worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max JS input payload size (bytes) | `1048576` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size | `8` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary | `/usr/bin/python3` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python script execution timeout (ms) | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a Python worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max Python input payload size (bytes) | `1048576` | process-engine, integration-designer |

To use GraalVM instead of the native engine, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services.


# FlowX.AI 5.9.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026

First LTS in the 5.9.x family. Brings conversational AI, UI Flows and Custom Components, AI Platform, runtime authorization, new React Native and iOS UI Flow SDKs, and a wide set of integration and process-ops improvements.

[FlowX.AI 5.9.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-5.9.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted deployments
> * All Deployments Features available in both self-hosted and SaaS

### What 5.9.0 includes

* **Closes the runtime authorization rewrite**. Per-environment sharing, project-version-scoped roles, data-sync Keycloak provisioning.
* **Brings the full set of changes accumulated since the 5.1.x LTS line**. Conversational AI, UI Flows, Custom Components, AI Platform, runtime authorization.
* **Ships a new React Native SDK** and rounds out iOS UI Flow support.

> [!NOTE]
>
> **5.9.0 is the first LTS in the 5.9.x family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Self-hosted customers upgrading from 5.1.x LTS go directly to 5.9.0. See the [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview) guide for the consolidated upgrade path.

***

**What's in this LTS release?**

> [tab] Runtime authorization and sharing
>
> 🔐 [**Runtime authorization completion**](#runtime-authorization-completion) - Per-environment sharing checklist, project-level end-user roles, data-sync provisioning of Keycloak groups and roles.\
> 🌐 [**Anonymous runtime access**](#anonymous-runtime-access) - Built-in Anonymous role + Share modal "Everyone with the link" for unauthenticated end users; session-bound, SDK auth-skip mode.\
> 🛡️ [**Runtime authorization overhaul**](#runtime-authorization-overhaul) - Project-version-scoped roles, end-user groups moved from Keycloak into FlowX, Solutions → Share modal flow, Active Policy gate, designer-user bypass.\
> 🔒 [**UI Flow permissions**](#ui-flow-permissions) - Per-UI-Flow role allow-list with runtime 403 enforcement; assignments travel with import/export.\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.\
> 🎯 [**Active policy: group overrides**](#active-policy-group-overrides) - Override a project's active build per runtime group; legacy role overrides are excluded from runtime resolution and only kept for deletion.\
> 🧩 [**Roles carried across project-version merges**](#roles-carried-across-project-version-merges) - Application-version roles cloned onto the merged version automatically, no manual re-binding after merge.\
> 🏷️ [**Operations-editor role**](#operations-editor-role) - **Workspace operations editor** role and `wks_process_instance_variables_edit` permission for ops teams.\
> 🗂️ [**Cross-workspace projects**](#cross-workspace-projects) - Import the same project into multiple workspaces in the same environment.\
> 🔁 [**Cross-LTS import/export**](#cross-lts-import/export) - Move project versions and builds between the 5.1.x and 5.9.x LTS lines, in both directions.\
> 🚪 [**Log-in page redesign**](#log-in-page-redesign) - IdP provider button replaces the fallback link; refreshed labels across the log-in flow.

> [tab] Conversational AI
>
> 💬 [**Chat component**](#chat-component) - Standalone chat tab; Inline / Floating / FullScreen modes; iOS and Android support; Chat History; Suggested Prompts; Markdown.\
> 🌀 [**Conversational Workflows**](#conversational-workflows) - Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node.\
> 🎙️ [**Voice input + Speech-to-Text**](#voice-input-+-speech-to-text) - Audio recording in chat; Speech-to-Text node for transcription.\
> 🧠 [**Memory capabilities**](#memory-capabilities) - Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full; Use conversation memory toggle on the AI / Custom Agent node.\
> 🧭 [**Intent Classification node**](#intent-classification-node) - LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.\
> 💭 [**Chat-based UI Flows**](#chat-based-ui-flows) - Flow-Based vs Chat-Based experience type set at the UI Flow level.\
> ⚡ [**AI Triggers**](#ai-triggers) - Named parameterized message templates to launch conversational workflows with context.\
> 🏷️ [**Chat title generation and conversation search**](#chat-title-generation-and-conversation-search) - Auto-generated session titles + cross-conversation search on the chat history.\
> 🛑 [**Stop agent response**](#stop-agent-response) - Stop button while streaming; cancels the underlying workflow.

> [tab] AI Agents and Knowledge
>
> 📊 [**Evaluations (Evals)**](#evaluations) - LLM-as-judge, RAG-quality, and code evaluators score AI node outputs; datasets, experiments, per-org judge model via new `EVAL` capability.\
> 🤖 [**Custom Agent nodes**](#custom-agent-nodes) - AI agents that use MCP tools to act autonomously in workflows.\
> 🔎 [**Web Search tool for Custom Agents**](#web-search-tool-for-custom-agents) - Built-in web search so Custom Agents can look up up-to-date public-web information during a run.\
> 🔌 [**MCP integration**](#mcp-integration) - MCP servers as data sources; tools in Custom Agent nodes; OAuth 2.0, BEARER, BASIC auth.\
> 📖 [**Knowledge Bases**](#knowledge-bases) - PDF upload, workflow ingestion, semantic search, Custom Agent integration; Stores rename + typed filter builder; system metadata; Kafka indexer/embedder.\
> 🧰 [**AI Providers self-service**](#ai-providers-self-service) - Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability.\
> 🛡️ [**PII Guard: per-entity detections on documents and images**](#pii-guard-per-entity-detections-on-documents-and-images) - Document and image scans return the same per-entity detection list as text scans, with bounding regions.\
> 📝 [**Operational prompt split**](#operational-prompt-split) - System prompt split into operational guardrails and user-instruction layers, versioned independently.\
> 📄 [**Extract Data from File**](#extract-data-from-file) - LLM / OCR / Text Parsing strategies; image input; signature detection.\
> 🌐 [**Web Page Extractor / Web Crawler**](#web-page-extractor-/-web-crawler) - Static or dynamic URLs, link-following depth, PDF extraction, URL filtering, file downloads, multi-URL filters.\
> 📚 [**Manage Knowledge Base content from Runtime**](#manage-knowledge-base-content-from-runtime) - End users can add and update KB content at runtime without going back to the Designer.\
> ✨ [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent drafts React Custom Components from a brief.

> [tab] UI Flows and Custom Components
>
> 🪟 [**UI Flows**](#ui-flows) - Reusable multi-platform UI as project resources; Sessions monitoring; Process Renderer; Route Management; Start Parameters; Session Variables; onClick / On Display / On Load events.\
> ⏳ [**UI Flow session expiry**](#ui-flow-session-expiry) - Expire a UI Flow after a duration or on a schedule; expired sessions become read-only.\
> 🖼️ [**Configurable modal component**](#configurable-modal-component) - Title, subtitle, dismiss behavior, alignment and sizing on modals; theme-level shadow and dismiss icon.\
> 💻 [**Custom Components**](#custom-components) - React JSX / CSS in the Designer; Custom Components in Processes with INPUT/OUTPUT mappings.\
> 🎬 [**Event Handlers**](#event-handlers) - Typed Event Handlers section in the UI component config panel; UI events and AI triggers unified under one model.\
> ♿ [**Accessibility (WCAG 2.1 AA)**](#accessibility-wcag-2-1-aa) - Cross-platform accessibility model surfaced in the UI Designer.\
> 🧱 [**New theme components**](#new-theme-components) - Tooltip, Markdown, Progress Bar, Separator across React / Angular / Android.\
> 📤 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Multiple File Upload on process screens and UI Flows; Angular and React SDK support.\
> 🎨 [**Theming and Designer polish**](#theming-and-designer-polish) - Scoped variants and padding for form labels/errors/helpers, mandatory-label style.

> [tab] Integration and Data Platform
>
> 📨 [**Email Trigger**](#email-trigger) - IMAP-triggered processes; attachments to the `document-plugin`; validation rules.\
> 📧 [**Microsoft Outlook data source**](#microsoft-outlook-data-source) - Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes.\
> 🪝 [**Incoming Webhooks**](#incoming-webhooks) - New `webhook-gateway` microservice; trigger processes via HTTP POST; Slack provider adapter.\
> 🗄️ [**Oracle Database integration**](#oracle-database-integration) - Oracle 21c / 23ai data source; schema-aware Monaco editor.\
> 🍃 [**Unmanaged MongoDB data source**](#unmanaged-mongodb-data-source) - Connect to externally managed MongoDB 6.0+ instances.\
> 📁 [**File Storage data source**](#file-storage-data-source) - Move files in and out of external FTP / SFTP / S3 / Azure Blob storage from workflows.\
> 📨 [**Meta webhook provider**](#meta-webhook-provider) - WhatsApp / Messenger / Instagram / Threads webhook support with verify-token handshake and X-Hub-Signature-256 verification.\
> 📂 [**Documents in process instances**](#documents-in-process-instances) - Dedicated Documents section on each process instance.\
> 📤 [**Send Notification action + Email Sender**](#send-notification-action-+-email-sender) - SMTP data source; new action sends or replies email directly without Kafka.\
> 🎛️ [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder replacing manual JSON, with new operators.\
> 🧬 [**Parallel branches in workflows**](#parallel-branches-in-workflows) - Start / End Parallel nodes for concurrent execution.\
> ⚡ [**REST endpoint caching + workflow partitioning**](#rest-endpoint-caching-+-workflow-partitioning) - TTL-based REST GET caching; time-based workflow partitions with retention.\
> 🔗 [**Data mappers + workflow data models**](#data-mappers-+-workflow-data-models) - Workflow data models with input/output; process ↔ workflow mapping; CRUD endpoints.\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Reusable HTTP/HTTPS proxies attached to REST data sources.\
> ✉️ [**Two-stage attachment filtering for Email triggers**](#two-stage-attachment-filtering-for-email-triggers) - Choose which emails trigger the process and which attachments are forwarded into it.\
> ⏸️ [**Resume a process from an incoming webhook**](#resume-a-process-from-an-incoming-webhook) - Webhooks now drive Message Catch Intermediate Events with a Process Correlation Key.\
> 🌐 [**REST endpoints: content-type-aware responses**](#rest-endpoints-content-type-aware-responses) - Accept-driven JSON / text / XML parsing with XXE-safe XML; responses over 5 MiB are returned raw.\
> 📝 [**Raw endpoint payload type**](#raw-endpoint-payload-type) - Send request body as-is with the user's Content-Type preserved; XML / SOAP / form-urlencoded / plain text without MULTIPART wrapping.

> [tab] Process operations
>
> ✏️ [**Update Process Variables**](#update-process-variables) - JSON editor for variables on active instances; snapshot history; Compare diff.\
> 🛑 [**Stop workflow instances in runtime**](#stop-workflow-instances-in-runtime) - Authorized end users can stop running workflow instances from runtime.\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor.\
> 🔔 [**Notification history + template usages**](#notification-history-+-template-usages) - `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all references.\
> 📋 [**Token view improvements**](#token-view-improvements) - Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, color-coded status.\
> 🔧 **Fixed: names with square brackets** - Processes and UI flows whose names contain square brackets now start correctly again.

> [tab] Platform, deployment and infrastructure
>
> 🏢 [**Single-org self-hosted deployment**](#single-org-self-hosted-deployment) - Self-hosted default mode; guided setup wizard.\
> 🔑 [**License service**](#license-service) - Centralized license validation and usage reporting for self-hosted deployments.\
> 🔐 [**Authentication: opaque-token → JWT**](#authentication-opaque-token-→-jwt) - Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key`; dedicated service-accounts realm.\
> 🆕 [**New services to deploy**](#new-services-to-deploy) - `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. None existed in a 5.1.x deployment.\
> 🐍 [**Native script engine for JavaScript and Python**](#native-script-engine-for-javascript-and-python) - Default JS/Python execution moves from GraalVM to a Node.js + CPython subprocess pool; GraalVM available as opt-in.\
> 🌐 [**Ingress routing and CORS handling**](#ingress-routing-and-cors-handling) - NGINX ingress controller deprecated as the FlowX-shipped default; CORS moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on every backend service.\
> 📡 [**Kafka configuration alignment**](#kafka-configuration-alignment) - Standardized `KAFKA_*` env vars; mandatory `Fx-Organization-Id` header.\
> 📊 [**OpenTelemetry + SpiceDB DR**](#opentelemetry-+-spicedb-dr) - OpenTelemetry / Prometheus Helm charts published; SpiceDB backup and disaster-recovery procedures.\
> 🛡️ [**Durable message-processing**](#durable-message-processing) - Parked integration responses are persisted durably so in-flight responses survive runtime restarts, reducing stuck process tokens.\
> 🌍 [**Task management localization**](#task-management-localization) - 51 substitution tags + automatic table grid localization across 30 languages.

> [tab] Mobile & Renderers
>
> 📱 [**React Native SDK**](#react-native-sdk) - New SDK for React Native apps with process renderer, forms, navigation, and CMS integration. Demo app included.\
> 🍎 [**iOS UI Flows support**](#ios-ui-flows-support) - Full UI Flows renderer on iOS; sessions, document plugin subtypes, dismiss action, start parameters, new native components.\
> 📲 [**Mobile chat support**](#conversational-ai) - Chat component available on iOS and Android.\
> ⚛️ [**React 19 upgrade**](#react-19-upgrade) - React SDK upgraded to React 19; host apps must upgrade in lockstep.

> [tab] Info
>
> ℹ️ [**Deployment guidelines**](./deployment-guidelines-v5.9) - Component versions, environment variables, Kafka topics\
> 🗺️ [**Migrating from 5.1 LTS**](/5.9/migrating-from-5.1-lts/overview) - Consolidated upgrade path from 5.1.x LTS to 5.9.x LTS

> [card]
>
> ### **Runtime authorization completion**
>
> 5.9.0 completes the project-version-scoped runtime authorization model:
>
> * **Sharing checklist for environment promotion.** Sharing assignments do not export with builds. Each environment must be reconfigured when a project is promoted. The deployment checklist for this is now part of the setup guide.
> * **Project-level end-user roles.** Roles can be assigned at the project level from creation, so a fresh project is reachable without a separate share pass.
> * **Data-sync provisioning.** The data-sync job calls the Keycloak admin API on first run to provision FlowX-managed end-user groups and runtime roles. Five new `FLOWX_OPENID_*` env vars expose the admin credentials.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > See Setup guides → Access management → Runtime authorization for the day-to-day model.
>
> > [accordion] Key Features
> >
> > * **Per-environment sharing checklist.** When you promote a project from dev to uat to prod, the Share modal assignments do not travel with the build. The setup guide now documents the explicit per-environment reconfiguration step.
> > * **Project-level end-user roles.** Assign end-user roles at the project level so a freshly created project is reachable on day one. No separate Share-modal pass required for the default access pattern.
> > * **Data-sync Keycloak provisioning.** The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak the first time it runs against a 5.9.0 environment. Configure admin credentials with the new `FLOWX_OPENID_*` env vars on the data-sync job.
> > * **Deployment checklist included.** The runtime authorization setup guide now ships a deployment prerequisites section so the data-sync OpenID config and per-environment sharing reset are part of the standard promotion runbook.
>
> > [accordion] Configuration
> >
> > Required on the data-sync job from 5.9.0 onward:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak`. | `keycloak` |
> > | `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` |
> > | `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` |
> > | `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` |
> > | `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Set to `admin-cli` for standard Keycloak deployments. | `-` |
> >
> > See [Data-sync job setup → OpenID provider configuration](/5.9/setup-guides/data-sync#openid-provider-configuration) for the full setup.

> [card]
>
> ### **Anonymous runtime access**
>
> 5.9.0 introduces unauthenticated runtime access: an app can be made publicly reachable, and processes or UI flows inside it can be opened to anonymous end users via a new built-in role.
>
> * **Two independent gates.** The app must be set to **Everyone with the link** in the Share modal AND the process or UI flow must have the **Anonymous** role assigned. If either gate is closed, the runtime returns `403 Forbidden` (`Anonymous access not enabled for this application` / `Anonymous access not enabled for this build`).
> * **System-level Anonymous role.** Auto-seeded on every new app version, cannot be deleted or edited; allowed operations are `VIEW`, `EXECUTE`, and an auto-populated `SELF_ASSIGN`.
> * **Session-bound traffic.** Anonymous requests carry an `X-Fx-Anonymous-Session-Id` header. The backend issues a new session ID on first contact; instances are bound to that session and cannot be read by another.
> * **SDK auth-skip.** The renderer decides authenticated vs anonymous from the `authToken` parameter at initialization. Token-in-storage on the same browser silently bypasses anonymous mode — container apps must scrub the `Authorization` header on public routes.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access)
> >
> > See Platform deep-dive → User roles management → Anonymous runtime access for the full feature reference.
>
> > [accordion] Key Features
> >
> > * **Share modal public-access option.** A new **General access** section in the Share modal switches between **Everyone with the link** and **Only invited users and groups**. Default remains invited-only.
> > * **Anonymous role on processes, UI flows, and reusable UI templates.** Selectable in the Permissions tab once the role is on the version; additive to other roles.
> > * **Component hide / disable rules.** UI Designer supports an Anonymous condition in role-based hide/disable rules at the component level.
> > * **Public-build asset rule.** When a build has the Anonymous role and the app is shared publicly, all assets inside (enumerations, substitution tags, media files, themes, fonts) become reachable anonymously — except UI flows and processes that don't carry the Anonymous role.

> [card]
>
> ### **Runtime authorization overhaul**
>
> Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > Open the **Runtime authorization overhaul** documentation.

> [card]
>
> ### **UI Flow permissions**
>
> Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> >
> > Open the **UI Flow permissions** documentation.

> [card]
>
> ### **End-user access management**
>
> Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> >
> > Open the **End-user access management** documentation.

> [card]
>
> ### **Operations-editor role**
>
> New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix)
> >
> > Open the **Operations-editor role** documentation.

> [card]
>
> ### **Cross-workspace projects**
>
> Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/workspaces#cross-workspace-project-import)
> >
> > Open the **Cross-workspace projects** documentation.

> [card]
>
> ### **Cross-LTS import/export**
>
> Move project versions and builds between the **5.1.x** and **5.9.x** LTS lines, in both directions. A newer platform version imports exports produced by an older one, and exports produced on a newer version can target an older one — useful for shipping a hotfix to an environment that hasn't been upgraded yet. Compatibility is patch-agnostic: any 5.9.x patch works with any 5.1.x patch.
>
> When exporting to an older version, resources whose type doesn't exist there are excluded automatically and listed in a `manifest_excluded.json` file in the archive, so the import still succeeds. The lowest version in the export/import path defines the usable functionality.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import)
> >
> > Open the **Cross-version export and import** documentation.

> [card]
>
> ### **Active policy: group overrides**
>
> Active policy overrides can now target **runtime groups** instead of runtime roles. The override resolves the active build for every member of the group at runtime, with a priority field deciding which group wins when a user belongs to several.
>
> Role-based overrides are deprecated in the same change. The **Role** override type is gone from the Add / Edit modal, and any role overrides carried over from a 5.1.x upgrade are kept in the table for visibility only — they are flagged **DEPRECATED**, excluded from runtime resolution, and can only be deleted.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-policy)
> >
> > See Projects → Runtime → Active policy for the full configuration model.
>
> > [accordion] Key Features
> >
> > * **Group override type.** Add / Edit Policy Override now exposes **Username** and **Group**. The group picker lists runtime groups that have a runtime role configured for the current project.
> > * **Priority is mandatory and unique per project for group overrides.** Lower numbers win when several groups match the same user. Username overrides ignore priority and always take precedence.
> > * **Resolution order.** Username override → Group override (lowest priority wins) → Global policy.
> > * **Role overrides deprecated.** Removed from the Add / Edit modal. Existing role rows are rendered muted with a **DEPRECATED** marker and a red banner; only the delete action remains. Deprecated role overrides are excluded from runtime resolution.
> > * **Test panel.** The effective-policy test panel simulates resolution for a given user.
> > * **Audit log.** Group override create / update / delete / enable / disable events are recorded.
>
> > [accordion] Upgrade impact
> >
> > Upgrading from 5.1.x carries existing role overrides into the new table as deprecated entries. They no longer affect runtime behavior. Recreate the intended access using group overrides and delete the role rows. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.

> [card]
>
> ### **Roles carried across project-version merges**
>
> Application-level role definitions are now carried into the merged project version automatically. Before 5.9.0, merging two project versions could leave the role table in a partial state. Bindings defined on one side were not consistently propagated to the merged version. 5.9.0 clones the roles from the destination latest version onto the merged version atomically as part of the merge transaction, so merges with role changes complete without follow-up manual cleanup.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Roles propagated as part of the merge.** When a project version is merged, application-version roles from the destination latest version are cloned onto the merged version in the same transaction.
> > * **No manual role re-binding after merge.** Operators no longer need to re-apply role bindings on the merged version. The merge completes in a single commit; the merged version is immediately usable.

> [card]
>
> ### **Log-in page redesign**
>
> The Designer log-in page is refreshed to align with the platform's design system. When an organization has an external IdP configured, the previous fine-print fallback link is replaced with a primary button labeled with the IdP configuration's **Display name**. Field labels and call-to-action copy across the log-in flow are aligned with the rest of the UI.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **IdP provider button.** When the organization has an IdP configured, the log-in screen surfaces a primary button labeled with the IdP's **Display name**, instead of a fine-print link below the form.
> > * **Refreshed copy.** Updated labels across the flow: **Log In** replaces *Sign In*, **Reset Password** replaces *Forgot password?*, and the page title becomes **Log In**.

> [card]
>
> ### **Chat component**
>
> Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component)
> >
> > Open the **Chat component** documentation.

> [card]
>
> ### **Conversational Workflows**
>
> Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> >
> > Open the **Conversational Workflows** documentation.

> [card]
>
> ### **Voice input + Speech-to-Text**
>
> Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> >
> > Open the **Voice input + Speech-to-Text** documentation.

> [card]
>
> ### **Memory capabilities**
>
> Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> >
> > Open the **Memory capabilities** documentation.

> [card]
>
> ### **Intent Classification node**
>
> Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> >
> > Open the **Intent Classification node** documentation.

> [card]
>
> ### **Chat-based UI Flows**
>
> UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> >
> > Open the **Chat-based UI Flows** documentation.

> [card]
>
> ### **AI Triggers**
>
> Named parameterized message templates to launch conversational workflows with context.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> >
> > Open the **AI Triggers** documentation.

> [card]
>
> ### **Stop agent response**
>
> Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> >
> > Open the **Stop agent response** documentation.

> [card]
>
> ### **Chat title generation and conversation search**
>
> Chat sessions now get a meaningful title generated automatically from the user's first message. No more "untitled chat" entries in the history. End users can also search across all their conversations with a single query that scans both message bodies and session titles.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Auto-generated session title.** The first user message seeds a provisional title (first 7 words). A one-shot LLM call then refines it into a concise descriptive title; the chat list updates live via an SSE event.
> > * **Conversation search.** `/api/conversations` accepts a `q` query parameter (2–200 characters). Matches against both session titles and message bodies. Each result carries a `snippet` field showing the matched excerpt.
> > * **Title update event.** When the LLM title is generated, the gateway emits a `chatSessionRenamed` event on the chat session channel; the chat list shows the refined title on the next load.
> > * **Single-shot generation.** Title generation runs exactly once per session, on first persist. The provisional 7-word title remains in place if the LLM call fails. No error surfaces to the end user.

> [card]
>
> ### **Evaluations**
>
> 5.9.0 introduces Evaluations: score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Attach datasets to AI nodes, launch experiments, and read per-evaluator aggregate scores plus per-test-case details.
>
> * **10 built-in evaluators across three categories.** LLM-as-judge (Correctness, Conciseness, Hallucination, Answer relevance), RAG (Groundedness, Helpfulness, Retrieval relevance), and Code (Exact match, Levenshtein, JSON match). Numeric evaluators ship with default thresholds; binary evaluators return pass/fail.
> * **Datasets attached to AI nodes.** Test cases sourced manually or captured from real node executions. The dataset persists a schema snapshot so older runs remain reproducible if the workflow changes underneath.
> * **Async judge pipeline.** A new Python `evals-judge` event-driven worker consumes `ai.flowx.ai-platform.evals-judge.job.request.v1`, scores each (test case × evaluator) pair via the configured judge LLM, and publishes back on the response topic. Unscored jobs land on a DLQ for manual review.
> * **Per-org judge model.** A new `EVAL` capability is registered in the org-manager LLM catalogue. Platform default is `gpt-5.4-mini`, backfilled per org on upgrade so evals work out-of-the-box.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/evaluations)
> >
> > See AI Platform → Evaluations for the user workflow, evaluator catalogue, REST API surface, and operator setup.
>
> > [accordion] Key Features
> >
> > * **Designer workflow.** Add a dataset on an AI node, add test cases (manually or captured from a node execution), pick evaluators, launch an experiment, read aggregate + per-test-case reports.
> > * **LLM-as-judge scoring.** A judge LLM reads the model output (and optional expected output) and scores it on a single rubric, returning a numeric score plus its reasoning.
> > * **RAG-quality scoring.** Judges the retrieval side of a RAG workflow — is the retrieved context grounded, helpful, and relevant?
> > * **Deterministic code evaluators.** No LLM call. Exact match, normalized Levenshtein, and JSON-shape match against the dataset's output contract.

> [card]
>
> ### **PII Guard: per-entity detections on documents and images**
>
> PII Guard scans on document and image AI nodes now surface the same per-entity detection list already shown for text scans. The run console reports each match with its entity type, confidence, original value, and replacement, making it easy to verify what was redacted on file-based AI inputs.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Same shape as text scans.** Document and image scans now return a `detections` list with `entityKey`, `confidence`, `originalValue`, `replacement`, and `direction`, matching the existing text-scan output.
> > * **Bounding regions for document and image hits.** Each detection on a `DOCUMENT` or `IMAGE` source includes `regions` (`x`, `y`, `width`, `height`) so the run console can highlight where the entity was matched.
> > * **Source-type tagging.** Detections carry a `sourceType` of `TEXT`, `DOCUMENT`, or `IMAGE`, mirroring the wrapper's `sourceType` field so audit consumers can attribute matches to the right payload.
> > * **Backward-compatible upgrade.** On older data-privacy versions that don't yet return the analyzer pass for object endpoints, `detections` stays empty and the redacted artifacts continue to be produced and downloadable.

> [card]
>
> ### **Custom Agent nodes**
>
> AI agents that use MCP tools to act autonomously inside workflows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> >
> > Open the **Custom Agent nodes** documentation.

> [card]
>
> ### **Web Search tool for Custom Agents**
>
> Custom Agent nodes can call a built-in web search tool to look up up-to-date information from the public web during a run. Turn it on with a single toggle — the agent decides when to search based on its instructions and the user's request.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Single toggle.** Enable **Tools → Built-in tools → Use Web Search Tool** on a Custom Agent node. Off by default; no extra configuration.
> > * **Agent-driven.** The agent calls web search on its own when the task needs current information, and folds the results into its response.

> [card]
>
> ### **MCP integration**
>
> MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> >
> > Open the **MCP integration** documentation.

> [card]
>
> ### **Knowledge Bases**
>
> Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > Open the **Knowledge Bases** documentation.

> [card]
>
> ### **AI Providers self-service**
>
> Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/ai-providers)
> >
> > Open the **AI Providers self-service** documentation.

> [card]
>
> ### **Extract Data from File**
>
> LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> >
> > Open the **Extract Data from File** documentation.

> [card]
>
> ### **Web Page Extractor / Web Crawler**
>
> Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> >
> > Open the **Web Page Extractor / Web Crawler** documentation.

> [card]
>
> ### **Context Retrieval**
>
> RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> >
> > Open the **Context Retrieval** documentation.

> [card]
>
> ### **AI Developer generates Custom Components**
>
> Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> >
> > Open the **AI Developer generates Custom Components** documentation.

> [card]
>
> ### **Operational prompt split**
>
> The single Operation Prompt field on AI nodes is split into two inputs so the static portion of the prompt can be cached by the LLM provider while dynamic values are passed separately. **Instructions** holds the agent's role, tasks, and expected I/O, sent as the System message and cached between executions, so `${}` dynamic values are not allowed. The **Context** field, inside the **Background** section, takes the dynamic per-execution prompt text and supports `${}` references, sent as the User message and not cached.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Instructions: cached System message.** Mandatory. Holds the agent's role, tasks, and expected input/output. Sent as the System message and cached by the LLM between executions. `${}` references are rejected to keep the cache key stable.
> > * **Background section: dynamic User message.** Wraps the Knowledge Base selector, the **Context** textarea (free text with `${}` support), the **Use only referenced values as input** toggle, and, in Chat Driven workflows, the **Use conversation memory** toggle. Sent as the User message on every execution; not cached.
> > * **Lower LLM cost and latency.** The static portion of the prompt is sent once per cache window instead of on every execution, so each call pays only for the dynamic Background section. The longer the Instructions, the bigger the per-call saving.
> > * **Applies to every AI node subtype.** The split UI is now shared by all AI node subtypes that previously used the single Operation Prompt field.

> [card]
>
> ### **Manage Knowledge Base content from Runtime**
>
> A new **Test KB** option on the build is available in runtime, giving operators visibility into Knowledge Base content that was previously opaque after deployment. Authorized users can inspect chunks, add or replace sources, edit metadata, and query the KB without going back to the Designer. Useful for debugging retrieval issues and keeping KBs current as business knowledge evolves.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Six runtime operations.** Create store, Append content, Replace content, Delete store, Edit metadata, and Query. All from the Test KB option inside the running app.
> > * **Files and payloads.** Both file uploads and inline payloads can be added to the KB through this feature.
> > * **Permission-gated.** KB management at runtime is controlled by runtime authorization, so only users with the right role see the Test KB controls.
> > * **Visibility into chunking.** Inspect how documents were chunked and what metadata was captured, useful when debugging retrieval quality on client-uploaded content.

> [card]
>
> ### **UI Flows**
>
> 5.9.0 closes the UI Flows feature: reusable, multi-platform UI (web, iOS, Android) as first-class project resources with their own lifecycle and runtime sessions. UI Flows now reach feature parity with processes for end-user-facing apps that don't need a BPMN process underneath.
>
> * **Multi-platform.** Author once in the Designer; UI Flows render on web (React), iOS, and Android via the platform-specific renderers. Layouts and component bindings travel together as a single resource.
> * **Sessions and runtime monitoring.** Each UI Flow run is a `UiFlowSession` with its own state, navigation history, and SSE event stream. Operators can monitor and inspect sessions from the runtime.
> * **Process integration.** UI Flows can start processes (Start Process action), navigate to other UI Flows (Navigate UI action), and embed a Process Renderer to show a running process inside a UI Flow. Workflows can also be invoked from a UI Flow with a Start Workflow action.
> * **Per-UI-Flow permissions.** A dedicated Permissions tab on each UI Flow controls which roles can run it. Runtime enforces with `403`; assignments travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows)
> >
> > See Building blocks → UI Flows for the full feature reference, including Navigation Areas, session variables, route management, and the component reference.
>
> > [accordion] Key Features
> >
> > * **Navigation Areas.** Group UI components into named areas for layout, scroll, and per-area transitions.
> > * **Start Parameters and Session Variables.** Pass typed inputs into a UI Flow at start; persist state across nodes via Session Variables.
> > * **Route management.** Each UI Flow exposes a stable runtime route; nested navigation preserves browser history and back/forward behaviour.
> > * **Task Manager component.** Drop the Task Manager surface inside a UI Flow to drive process tasks from the same UI shell.
> > * **onClick and On Display events, plus a new On Load event.** Component-level events trigger workflows or UI actions, with the new On Load event firing when the UI Flow first opens.
> > * **Breadcrumbs.** Built-in breadcrumbs reflect the Navigation Area hierarchy and follow the active theme.
> > * **Process Renderer + Start Workflow action.** Embed a running process inside a UI Flow; trigger an integration workflow from a button or event without leaving the flow.

> [card]
>
> ### **UI Flow session expiry**
>
> A UI Flow session can be set to expire automatically after a fixed duration or on a schedule. Once expired, the session becomes read-only — the user keeps the data already loaded but cannot take further action.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Flexible expiry.** Set the **Expiry time** in **Settings → General** as an ISO-8601 duration (for example `PT3M22S`) or a cron expression (for example `0 0 9-17 * * MON-FRI`). Empty means no expiry.
> > * **Read-only on expiry.** Expired sessions block all actions; loaded data stays visible and nothing is wiped.
> > * **Server-enforced.** The platform marks sessions `EXPIRED` server-side, so it applies the same way in the deployed app and the Designer preview.

> [card]
>
> ### **Configurable modal component**
>
> Modals on process screens and UI Flows gain configurable content and layout. Set a title and subtitle, control dismiss behavior, and align and size the modal from the Designer.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Content.** Set the modal **Title** and **Subtitle** from the Settings panel.
> > * **Dismiss behavior.** Toggle **Dismissible**, allow **Backdrop click**, and optionally show a **Confirmation alert** with custom title, message, and button labels.
> > * **Layout.** Align content **Left**, **Center**, or **Right**, and set **Width**/**Height** to **Fixed** or **Auto**.
> > * **Theme-level styling.** The modal **shadow** and **dismiss icon** are defined once in the theme's Modal section.

> [card]
>
> ### **Custom Components**
>
> Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> >
> > Open the **Custom Components** documentation.

> [card]
>
> ### **Process Renderer in UI Flows**
>
> Embed process renderers inside UI Flows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > Open the **Process Renderer in UI Flows** documentation.

> [card]
>
> ### **UI Flow sessions monitoring**
>
> Runtime view with session list, audit log, process tracking, workflow debugging.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> >
> > Open the **UI Flow sessions monitoring** documentation.

> [card]
>
> ### **Accessibility (WCAG 2.1 AA)**
>
> Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> All Deployments

> [card]
>
> ### **New theme components**
>
> Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Open the **New theme components** documentation.

> [card]
>
> ### **Multi-file bulk upload**
>
> Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> >
> > Open the **Multi-file bulk upload** documentation.

> [card]
>
> ### **Card default collapse + Tables in Collections**
>
> Cards configurable to load collapsed; Table UI components inside Collection prototypes.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> >
> > Open the **Card default collapse + Tables in Collections** documentation.

> [card]
>
> ### **Event Handlers**
>
> The UI component configuration panel introduces a dedicated **Event Handlers** section. The legacy `flowx_props` bag is replaced by a typed, per-handler form covering action type, optional analytics, custom body, destination, and collection save-key fields. Container components (Page, Zone, Modal, Tab Bar in UI Flows; Tab on process screens) and inline components resolve their actions through the same model.
>
> Existing UI events and AI triggers are migrated automatically. A Liquibase migration runs on the first 5.9.0 boot and moves the data into the new `ui_action` model. No project re-export or re-import is required.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Typed Event Handlers.** Each handler is a named, typed entity instead of a free-form prop, making configuration easier to validate and audit.
> > * **Action type selector.** Pick the action type from a dropdown that knows which fields are required for that type.
> > * **Analytics, body, destination, save-key.** Per-handler sub-forms cover analytics events, custom request bodies, destination resolution, and collection save-key fields.
> > * **Unified for inline and container components.** Page, Zone, Modal, and Tab Bar containers in UI Flows use the same Event Handlers model as inline components; on process screens, Tab containers use it.

> [card]
>
> ### **Theming and Designer polish**
>
> > [accordion] Theming
> >
> > Form field labels, error messages, and helper text gain padding controls and scoped style variants in the theme model. Theme Admin exposes the new padding properties on segmented buttons, sliders, and input selections; the React and Angular SDKs apply the values in the renderers; the Designer preview reflects them in place. Form fields also pick up a consistent **mandatory label** style applied automatically when a field is required.
> >
> > * **Scoped variants for labels, errors, helpers.** Theme configs can override label, error, and helper styles per component without affecting other parts of the form.
> > * **Padding for segmented buttons, sliders, input selections.** Theme Admin adds label, error, and helper padding controls for these components; values flow through to all renderers.
> > * **Mandatory label style.** A consistent style for mandatory-field labels, applied automatically when a form field is required.
> > * **Designer preview parity.** Theme overrides and paddings are visible in the Designer preview without round-tripping through a runtime app.
> >
> > All Deployments
>
> > [accordion] Designer polish
> >
> > The command center floating action button is now hidden on the running-instance screens of Processes, UI Flows, and UI Templates, where it overlapped with the instance view; it reappears when the instance data panel is open. The command center remains reachable through the standard keyboard shortcut and from screens where it does not interfere.
> >
> > All Deployments

> [card]
>
> ### **Email Trigger**
>
> New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> >
> > Open the **Email Trigger** documentation.

> [card]
>
> ### **Microsoft Outlook data source**
>
> Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> >
> > Open the **Microsoft Outlook data source** documentation.

> [card]
>
> ### **Incoming Webhooks**
>
> New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> >
> > Open the **Incoming Webhooks** documentation.

> [card]
>
> ### **Oracle Database integration**
>
> Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL. Beyond tables and `SELECT`, queries can also target views, functions, and stored procedures, with output parameters returned to the workflow.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> >
> > Open the **Oracle Database integration** documentation.

> [card]
>
> ### **Unmanaged MongoDB data source**
>
> Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> >
> > Open the **Unmanaged MongoDB data source** documentation.

> [card]
>
> ### **File Storage data source**
>
> A new data source connecting workflows to external file storage — FTP, SFTP, S3 / S3-compatible, or Azure Blob Storage. Define named List, Download, Upload, Delete, and Move operations scoped to a root path, browse and test them in Designer, and call them from a Data Source node. Operations run in the new `file-gateway` service, exchanging files with the `document-plugin`.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/file-storage)
> >
> > Open the **File Storage data source** documentation.

> [card]
>
> ### **Send Notification action + Email Sender**
>
> SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> >
> > Open the **Send Notification action + Email Sender** documentation.

> [card]
>
> ### **Advanced Query Builder**
>
> Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> >
> > Open the **Advanced Query Builder** documentation.

> [card]
>
> ### **Parallel branches in workflows**
>
> Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> All Deployments

> [card]
>
> ### **REST endpoint caching + workflow partitioning**
>
> TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> All Deployments

> [card]
>
> ### **Data mappers + workflow data models**
>
> Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> >
> > Open the **Data mappers + workflow data models** documentation.

> [card]
>
> ### **Proxy Server Connections**
>
> Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> >
> > Open the **Proxy Server Connections** documentation.

> [card]
>
> ### **Faster authoring loop**
>
> 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.
>
> All Deployments

> [card]
>
> ### **Meta webhook provider**
>
> Incoming Webhooks add **Meta** as a built-in provider alongside Generic and Slack, covering WhatsApp, Messenger, Instagram, and Threads. The webhook-gateway handles the Meta-specific subscription handshake and signature verification natively. No custom adapter code required to wire a Meta-platform integration into a FlowX process.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Subscription handshake.** The gateway answers Meta's GET URL-verification request by validating `hub.mode=subscribe` and the provided `hub.verify_token` against the configured verify token, then echoes `hub.challenge` back. Constant-time token comparison.
> > * **X-Hub-Signature-256 verification.** Every POST is authenticated with the `X-Hub-Signature-256` HMAC-SHA256 signature using the configured app secret. Requests with missing or invalid signatures are rejected before reaching the process engine.
> > * **Two secrets per webhook.** When you create a Meta webhook in Integration Designer, two masked inputs appear in the configuration panel: **Verify token** (used during the handshake) and **App secret** (used for signature verification). Both are required.
> > * **Multi-product support.** A single Meta webhook can receive events from WhatsApp, Messenger, Instagram, and Threads. The provider is configured at the webhook level; the channel is part of the payload.
>
> > [accordion] Configuration
> >
> > Select **Meta** in the provider dropdown when creating the webhook data source. Both secret fields are required:
> >
> > | Field | Description |
> > | - | - |
> > | **Verify token** | The token Meta sends back during the GET URL-verification handshake. Choose any string; configure the same value on the Meta App developer console. |
> > | **App secret** | The App secret from the Meta App configuration; used to verify the `X-Hub-Signature-256` HMAC on every POST. |
> >
> > Both values are stored as a JSON-packed pair on the existing webhook secret field. No schema migration is required.
> >
> > See [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#meta-provider) for the full setup walk-through.

> [card]
>
> ### **Documents in process instances**
>
> Each process instance now exposes a dedicated **Documents** tab. A single source of truth for every document handled during the process, regardless of how it entered the instance. Operations teams can review tracking metadata, preview, and download attached files from one place rather than walking through the process timeline.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **All document sources in one place.** End-user uploads via the file-upload component, attachments from email triggers, files generated from HTML templates, OCR output, and files produced by AI workflow nodes, all listed under one tab.
> > * **Tracking metadata and preview.** Each row shows source, timestamp, and uploader, with inline preview for supported file types.
> > * **Direct download.** Download any attached document directly from the Documents tab.
> > * **Faster operations review.** No more clicking through the process timeline to reconstruct which file came in at which step.

> [card]
>
> ### **Two-stage attachment filtering for Email triggers**
>
> Email triggers (IMAP and Microsoft Outlook) now expose a two-stage filter on each trigger: choose which incoming emails create a process instance, then choose which attachments are forwarded into the process. The previous single on/off validations toggle is replaced with explicit, per-trigger control over inbound mail.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start Process for.** Trigger the process for all emails, only emails with attachments, or only emails carrying selected file types (PDF, DOCUMENT, IMAGE, EXCEL, ZIP).
> > * **Save email attachments on process.** Forward all attachments, none (metadata-only), or only specific file types into the process instance.
> > * **Trigger-level rejection.** Emails that fail the trigger condition or exceed **Maximum File Count** are rejected with explicit Failed Triggers causes. **No attachments**, **No matching file types**, **File count exceeded**.
> > * **Backward-compatible upgrade.** Existing triggers are migrated to **All incoming emails** + **All attachments** with no manual intervention. Reopen each trigger to reapply file-type filtering if you previously relied on the validations toggle.

> [card]
>
> ### **Resume a process from an incoming webhook**
>
> Incoming Webhooks can now drive a **Message Catch Intermediate Event**, not just a Message Start Event. When a process is paused on an intermediate catch event, an external system can POST to the webhook to resume that specific instance. Useful for callbacks from third-party services, asynchronous job completions, or operator actions delivered over HTTP.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start or resume from one webhook model.** The same webhook data source can start new processes (on a Message Start Event) or resume waiting ones (on a Message Catch Intermediate Event). The trigger type is set automatically based on where the webhook is attached.
> > * **Process Correlation Key.** Each intermediate catch event declares a Process Correlation Key (a business variable like `applicationId`). The webhook-gateway matches this value against the incoming payload to route the resume to the right process instance. The Webhook Correlation Key now accepts array indices in square brackets (`entry[0].changes[0].value.messages[0].text.body`), so the canonical Meta WhatsApp resume path works without flattening upstream.
> > * **Validation at design time.** Process Correlation Key and Process Key are required on intermediate webhook catch events and are validated when the message event is created or updated.
> > * **Backward-compatible upgrade.** Existing webhooks are migrated to `triggerType=START_PROCESS` with no manual intervention. New webhooks attached to an intermediate catch event are flagged `RESUME_PROCESS` automatically.

> [card]
>
> ### **REST endpoints: content-type-aware responses**
>
> REST endpoint responses in Integration Designer are now parsed by content type rather than assumed to be JSON. The endpoint's `Accept` header drives parsing: JSON, plain text, and XML responses are each handled with the right parser, and the original XML string is preserved alongside the parsed map so downstream nodes can read either form. Existing JSON-returning endpoints continue to work without configuration changes.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Accept-driven response parsing.** The endpoint's `Accept` header decides how the response is parsed. JSON variants (`application/json`, `application/hal+json`, `application/problem+json`, any `+json` suffix) are parsed as JSON; `text/*` is returned as a string; XML variants (`application/xml`, `text/xml`, `application/soap+xml`, any `+xml` suffix) are parsed into a JSON-shaped map. When `Accept` is missing, the endpoint falls back to `Content-Type`, then to **AUTO** best-effort.
> >
> > * **XML responses parsed into JSON-shaped objects.** XML response bodies are auto-converted to maps so existing path expressions (`response.body.someField`) work without code changes. The original XML string is preserved on `sourceBody` for callers that need it raw.
> >
> > * **Loud failures on declared mismatches.** When an endpoint declares JSON or XML and the upstream returns a different category, or returns a body that fails to parse, the node fails with a precise error message (for example, `Expected response content type "application/json" but received "text/plain"`). The original body is preserved on `rawBody`.
> >
> > * **Tolerant under AUTO and wildcards.** Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) and inferred categories (no `Accept` declared) fall back to the raw string instead of failing. Flaky or mislabelled upstreams don't break the node.
> >
> > * **XXE-safe XML parser.** XML parsing has DTD processing and external-entity resolution disabled by construction. External-entity attack payloads are neutralized; billion-laughs / entity-expansion attacks cannot fire.
> >
> > * **File downloads bypass Content-Type checks.** File-download endpoints (BINARY or BASE64) deliver the platform's own JSON payload regardless of upstream `Content-Type`, so legacy PDF, octet-stream, and image downloads work unchanged.
> >
> > * **Large XML returned raw.** XML response bodies larger than 5 MiB are returned as the raw string instead of a parsed map, so very large payloads don't block the node.
> >
> > > [!WARNING]
> > >
> > > **Mixed-content XML responses expose a new `value` key.** An XML element with both attributes and inner text (`<leaf attr="v">text</leaf>`) is now parsed to `{attr: "v", value: "text"}`. The inner text used to be silently dropped. Downstream nodes that iterate response keys or assert the exact key set on mixed-content elements may see an additional `value` entry. Path expressions that addressed attributes or child elements directly are unaffected.

> [card]
>
> ### **Raw endpoint payload type**
>
> REST endpoint configuration adds a **Raw** content type alongside JSON, Multipart, and Binary. Raw bodies are sent to the upstream system as-is. Useful for XML, SOAP envelopes, form-urlencoded payloads, or any plain-text body where you need to set the `Content-Type` header yourself.
>
> Before 5.9.0, the only way to send a non-JSON textual body was to use Multipart, which wrapped the payload in `multipart/form-data` and overrode the `Content-Type` header. Raw removes that wrapping.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Body sent as-is.** The body field is sent verbatim. The dispatcher does not transform, wrap, or pretty-print it.
> > * **Caller controls Content-Type.** Set the `Content-Type` header on the endpoint to whatever the upstream expects (`text/xml`, `application/soap+xml`, `application/x-www-form-urlencoded`, `text/plain`). The dispatcher does not override it.
> > * **Monaco plain-text mode.** The endpoint editor switches Monaco to plain text when Raw is selected. XML and SOAP indentation are preserved on paste and edit instead of being reformatted as JSON.
> > * **Shares the JSON body slot.** Raw and JSON payloads use the same storage field on the endpoint definition, so no schema migration is required. Existing endpoints continue to work without changes.

> [card]
>
> ### **Update Process Variables**
>
> JSON editor for variables on active instances with snapshot history; Compare diff.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> >
> > Open the **Update Process Variables** documentation.

> [card]
>
> ### **Stop Run for workflows**
>
> Cancel a running workflow instance from the editor.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-workflows#running-and-stopping-workflows)
> >
> > Open the **Stop Run for workflows** documentation.

> [card]
>
> ### **Notification history + template usages**
>
> `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> >
> > Open the **Notification history + template usages** documentation.

> [card]
>
> ### **Token view improvements**
>
> Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/token)
> >
> > Open the **Token view improvements** documentation.

> [card]
>
> ### **Stop workflow instances in runtime**
>
> Authorized end users can now stop running workflow instances directly from runtime. Previously, stopping a workflow required Designer access or a direct API call. The new control surfaces the action inside the runtime application alongside other workflow-instance management options.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **One-click stop.** Stop a running workflow instance from the runtime instance list.
> > * **Permission-gated.** The stop control is governed by runtime authorization.
> > * **Audited.** Stop actions are recorded on the workflow-instance audit log with the actor and timestamp.

> [card]
>
> ### **Native script engine for JavaScript and Python**
>
> The default script engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a **native subprocess pool**. Scripts run in long-running Node.js and Python worker processes managed by `process-engine` and `integration-designer`. Existing scripts that read from `input` and write to `output` keep working, including `output.put(...)`, `output.get(...)`, and bracket assignment.
>
> The change is opt-out: set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services to keep the previous engine.
>
> Self-HostedAll Deployments
>
> > [accordion] Key Features
> >
> > * **Node.js workers for JavaScript.** JavaScript runs in isolated Node.js worker processes. Each script executes in a fresh V8 context with an explicit globals allowlist and a V8-level execution timeout.
> > * **CPython workers for Python.** Python 3 runs in isolated worker processes with a curated sandbox. Common standard-library modules (`random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64`) are available without `import`. Process, OS, and network modules are blocked.
> > * **Worker pools with recycling.** Worker pools default to 16 Node.js workers and 8 Python workers, sized per service. Workers are recycled after a configurable number of executions to prevent state leakage.
> > * **HashMap method compatibility.** The familiar `output.put(key, value)`, `output.get(key)`, and `output.containsKey(key)` methods continue to work on both JavaScript and Python. The same scripts that ran under GraalVM polyglot context keep working without rewrites.
> > * **GraalVM still available as opt-in.** Set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine, useful if a script depends on GraalVM-specific polyglot features.
> > * **Hardened execution sandbox.** Per-execution fresh scope, environment variables cleared at worker startup, dangerous Python module references scrubbed before user code runs, no `require` / `process` / `global` access in JavaScript.
>
> > [accordion] Configuration
> >
> > The native engine is the default on `process-engine` and `integration-designer`. Tune worker pools and timeouts as needed:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider. `native` or `graalvm`. | `native` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size. | `16` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS execution timeout per script (ms). | `5000` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size. | `8` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python execution timeout per script (ms). | `10000` |
> >
> > See [Process engine setup → Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration) and [Integration Designer setup → Script engine configuration](/5.9/setup-guides/integration-designer-setup#script-engine-configuration) for the full set including payload size and worker recycling.
>
> > [accordion] Migration impact
> >
> > For most existing scripts the change is transparent. The `input`, `output`, `additionalData`, and `instanceMetadata` bindings behave the same, and HashMap-style access on `output` is preserved.
> >
> > Scripts that need attention:
> >
> > * **Python scripts that `import` modules outside the curated allowlist.** Narrow the script to use only the pre-loaded modules, or stay on GraalVM via the opt-out env var.
> > * **JavaScript scripts that reach for `require(...)`, `process`, or `global`.** Those references were never part of the supported surface area but may have worked under GraalVM. Rewrite to use only the bindings provided, or stay on GraalVM via the opt-out env var.
> > * **Scripts that depended on GraalVM-specific polyglot APIs** (calling Java classes from JavaScript / Python). Stay on GraalVM via the opt-out env var.
> >
> > See [Script runtime change for JavaScript and Python business rules](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit checklist.

> [card]
>
> ### **Single-org self-hosted deployment**
>
> Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/organization-deployment)
> >
> > Open the **Single-org self-hosted deployment** documentation.

> [card]
>
> ### **License service**
>
> Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> >
> > Open the **License service** documentation.

> [card]
>
> ### **Authentication: opaque-token → JWT**
>
> Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/authentication-iam)
> >
> > Open the **Authentication: opaque-token → JWT** documentation.

> [card]
>
> ### **New services to deploy**
>
> `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/prerequisites#new-services-to-deploy)
> >
> > Open the **New services to deploy** documentation.

> [card]
>
> ### **Ingress routing and CORS handling**
>
> The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/ingress-routing)
> >
> > Open the **Ingress routing and CORS handling** documentation.

> [card]
>
> ### **Kafka configuration alignment**
>
> Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/kafka)
> >
> > Open the **Kafka configuration alignment** documentation.

> [card]
>
> ### **OpenTelemetry + SpiceDB DR**
>
> OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> All Deployments

> [card]
>
> ### **Durable message-processing**
>
> The process engine now persists parked integration and external-message responses durably, so a response that arrives before its process is ready to consume it survives a runtime restart instead of being lost. This removes a class of stuck process-token failures and improves message-processing robustness at runtime.
>
> All Deployments

> [card]
>
> ### **Task management localization**
>
> 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Open the **Task management localization** documentation.

> [card]
>
> ### **React Native SDK**
>
> FlowX 5.9.0 ships a brand-new **React Native SDK**, bringing the same process renderer model that has powered the React, Angular, iOS, and Android SDKs to React Native apps. Teams building cross-platform mobile or embedded React Native experiences can now host FlowX processes natively, with forms, navigation, and CMS integration handled by the SDK.
>
> A companion demo app is included as a reference integration, covering authentication, the showcase page, and the wiring needed to start a process from inside a container app.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Process renderer.** Render FlowX processes inside any React Native screen with the same component model as the other SDKs.
> > * **Forms and basic components.** Page, Button, Text, Container, Card, and form components ship out of the box.
> > * **CMS integration.** Static content and theming load from the FlowX CMS, including dynamic display values.
> > * **Navigation.** Basic process navigation between screens follows the same patterns as the iOS and Android SDKs.
> > * **Demo app included.** A demo app with authentication and a showcase page is shipped alongside the SDK as a reference integration.

> [card]
>
> ### **iOS UI Flows support**
>
> The iOS renderer reaches feature parity with the React and Angular renderers on UI Flows. iOS apps can now start UI Flows from container apps, manage UI Flow sessions, dismiss modals, handle UI actions, and render document-plugin subtypes (images and document previews).
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start UI Flow from container app.** Container apps can launch a UI Flow with start parameters and handle the response.
> > * **UI Flow session management.** The renderer manages a UI Flow session lifecycle on iOS the same way it does on web.
> > * **onLoad UI Event for Page.** Pages emit an `onLoad` UI Event that iOS handlers can listen to, matching the cross-platform event model.
> > * **Dismiss action and dismiss-on-completion.** A `dismiss` action type cleanly closes modals; `dismiss on completion` on `START_WORKFLOW` actions auto-closes the launching modal when the workflow finishes.
> > * **UI Flow start params.** Pass typed start parameters into a UI Flow at launch.
> > * **Upload File support.** UI Flows on iOS support file upload, including image and document-preview document-plugin subtypes.
> > * **Updated start-process endpoint.** The iOS renderer uses the latest start-process endpoint and `data` property on Start UI Flow, aligned with the web SDKs.
> > * **New native components.** Tooltip, Separator, Progress View, and Markdown components are now rendered natively on iOS, bringing the iOS component set closer to parity with the React and Angular renderers.
> > * **Accessibility properties from UI Designer.** Accessibility properties configured in the UI Designer flow through to the iOS renderer, so screen reader labels and traits are honored on native screens.

> [card]
>
> ### **React 19 upgrade**
>
> The React SDK upgrades to **React 19**, picking up the runtime improvements and APIs that ship with that release. Surrounding `@flowx/*` packages are upgraded in lockstep so the renderer continues to work as a single coherent bundle.
>
> Host apps embedding the React renderer should plan a React 19 upgrade on their side and run the standard React migration checks before adopting 5.9.0.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **React 19 runtime.** Adopts the React 19 reconciler and the APIs that ship with that release.
> > * **Packages upgraded in lockstep.** All `@flowx/*` web SDK packages move to the same baseline so the renderer ships as one coherent bundle.
>
> > [accordion] Host app impact
> >
> > Host apps that embed the React renderer must be on React 19 themselves. Run the React 19 codemods and verify any third-party React libraries you depend on are compatible before upgrading FlowX.

> [card]
>
> ### **Runtime authorization and sharing**
>
> This is the biggest governance change in the 5.1 → 5.9 upgrade. End-user identities, runtime roles, and sharing assignments move out of Keycloak into FlowX-managed records, with project-version-scoped roles and a dedicated Share modal flow on Solutions.
>
> > [card] [Runtime authorization completion](#runtime-authorization-completion)
> >
> > Closes the rewrite: per-environment sharing checklist, project-level end-user roles, data-sync Keycloak provisioning. See the 5.9.0 card above.
>
> > [card] [Anonymous runtime access](#anonymous-runtime-access)
> >
> > Built-in `Anonymous` role + Share modal "Everyone with the link" option for unauthenticated end users. Session-bound (`X-Fx-Anonymous-Session-Id`), fire-and-forget; per-component hide/disable rules; SDK auth-skip mode.
>
> > [card] [Runtime authorization overhaul](#runtime-authorization-overhaul)
> >
> > Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> > [card] [UI Flow permissions](#ui-flow-permissions)
> >
> > Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> > [card] [End-user access management](#end-user-access-management)
> >
> > Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> > [card] [Operations-editor role](#operations-editor-role)
> >
> > New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> > [card] [Cross-workspace projects](#cross-workspace-projects)
> >
> > Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.

> [card]
>
> ### **Conversational AI**
>
> 5.9 takes FlowX from no chat to production conversational AI: the Chat component, conversational workflows with memory and intent classification, voice and speech-to-text, chat-based UI Flows, and runtime controls.
>
> > [card] [Chat component](#chat-component)
> >
> > Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> > [card] [Conversational Workflows](#conversational-workflows)
> >
> > Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> > [card] [Voice input + Speech-to-Text](#voice-input-+-speech-to-text)
> >
> > Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> > [card] [Memory capabilities](#memory-capabilities)
> >
> > Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> > [card] [Intent Classification node](#intent-classification-node)
> >
> > Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> > [card] [Chat-based UI Flows](#chat-based-ui-flows)
> >
> > UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> > [card] [AI Triggers](#ai-triggers)
> >
> > Named parameterized message templates to launch conversational workflows with context.
>
> > [card] [Stop agent response](#stop-agent-response)
> >
> > Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.

> [card]
>
> ### **AI Agents and Knowledge**
>
> The agent-builder story: Custom Agents, MCP integration, Knowledge Bases for RAG, document and web extraction, AI Providers self-service, and PII Guard.
>
> > [card] [Evaluations (Evals)](#evaluations)
> >
> > Score AI node outputs against test cases with 10 built-in evaluators (LLM-as-judge: correctness, conciseness, hallucination, answer-relevance; RAG: groundedness, helpfulness, retrieval-relevance; code: exact-match, Levenshtein, JSON-match). Datasets attached to AI nodes, async judge pipeline via the new `evals-judge` service + 3 Kafka topics, per-org judge model via the new `EVAL` capability (default `gpt-5.4-mini`).
>
> > [card] [Custom Agent nodes](#custom-agent-nodes)
> >
> > AI agents that use MCP tools to act autonomously inside workflows.
>
> > [card] [MCP integration](#mcp-integration)
> >
> > MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> > [card] [Knowledge Bases](#knowledge-bases)
> >
> > Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> > [card] [AI Providers self-service](#ai-providers-self-service)
> >
> > Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> > [card] [PII Guard](#pii-guard-per-entity-detections-on-documents-and-images)
> >
> > Per-AI-node guardrail with Strict / Balanced / Relaxed presets, input/output scans, file redaction. 5.9.0 adds per-entity detections on documents and images. See the 5.9.0 card above.
>
> > [card] [Extract Data from File](#extract-data-from-file)
> >
> > LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> > [card] [Web Page Extractor / Web Crawler](#web-page-extractor-/-web-crawler)
> >
> > Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> > [card] [Context Retrieval](#context-retrieval)
> >
> > RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> > [card] [AI Developer generates Custom Components](#ai-developer-generates-custom-components)
> >
> > Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.

> [card]
>
> ### **UI Flows and Custom Components**
>
> Build user-facing apps without a process. UI Flows reach feature parity with processes; Custom Components let teams ship React code inside the Designer.
>
> > [card] [UI Flows](#ui-flows)
> >
> > Reusable multi-platform UI (web / iOS / Android) as project resources. Navigation Areas, Start Process / Navigate UI actions, Task Manager component. Breadcrumbs + Sessions monitoring. Process Renderer + Start Workflow action + On Load event. Route management + Start Parameters + Session Variables + onClick / On Display events. UI Flow permissions.
>
> > [card] [Custom Components](#custom-components)
> >
> > Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> > [card] [Process Renderer in UI Flows](#process-renderer-in-ui-flows)
> >
> > Embed process renderers inside UI Flows.
>
> > [card] [UI Flow sessions monitoring](#ui-flow-sessions-monitoring)
> >
> > Runtime view with session list, audit log, process tracking, workflow debugging.
>
> > [card] [Accessibility (WCAG 2.1 AA)](#accessibility-wcag-2-1-aa)
> >
> > Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> > [card] [New theme components](#new-theme-components)
> >
> > Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> > [card] [Multi-file bulk upload](#multi-file-bulk-upload)
> >
> > Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> > [card] [Card default collapse + Tables in Collections](#card-default-collapse-+-tables-in-collections)
> >
> > Cards configurable to load collapsed; Table UI components inside Collection prototypes.

> [card]
>
> ### **Integration and Data Platform**
>
> For builders connecting FlowX to enterprise systems, 5.9 adds new data sources, new triggers, parallel workflow execution, REST resilience, and visual query authoring.
>
> > [card] [Email Trigger](#email-trigger)
> >
> > New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> > [card] [Microsoft Outlook data source](#microsoft-outlook-data-source)
> >
> > Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> > [card] [Incoming Webhooks](#incoming-webhooks)
> >
> > New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> > [card] [Oracle Database integration](#oracle-database-integration)
> >
> > Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL.
>
> > [card] [Unmanaged MongoDB data source](#unmanaged-mongodb-data-source)
> >
> > Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> > [card] [Send Notification action + Email Sender](#send-notification-action-+-email-sender)
> >
> > SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> > [card] [Advanced Query Builder](#advanced-query-builder)
> >
> > Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> > [card] [Parallel branches in workflows](#parallel-branches-in-workflows)
> >
> > Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> > [card] [REST endpoint caching + workflow partitioning](#rest-endpoint-caching-+-workflow-partitioning)
> >
> > TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> > [card] [Data mappers + workflow data models](#data-mappers-+-workflow-data-models)
> >
> > Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> > [card] [Proxy Server Connections](#proxy-server-connections)
> >
> > Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> > [card] [Faster authoring loop](#faster-authoring-loop)
> >
> > 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.

> [card]
>
> ### **Process operations**
>
> Day-2 operations for runtime teams: edit live process state, inspect tokens with more context, audit notifications, and operate on workflow instances.
>
> > [card] [Update Process Variables](#update-process-variables)
> >
> > JSON editor for variables on active instances with snapshot history; Compare diff.
>
> > [card] [Stop Run for workflows](#stop-run-for-workflows)
> >
> > Cancel a running workflow instance from the editor.
>
> > [card] [Notification history + template usages](#notification-history-+-template-usages)
> >
> > `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> > [card] [Token view improvements](#token-view-improvements)
> >
> > Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> 5.9.0 adds **Stop workflow instances in runtime** and **Documents in process instances**. See the 5.9.0 cards above.

> [card]
>
> ### **Platform, deployment and infrastructure**
>
> Read this first if you operate a self-hosted deployment. 5.9 adds new microservices, a new deployment mode, and the auth architecture transition.
>
> > [card] [Single-org self-hosted deployment](#single-org-self-hosted-deployment)
> >
> > Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> > [card] [License service](#license-service)
> >
> > Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> > [card] [Authentication: opaque-token → JWT](#authentication-opaque-token-→-jwt)
> >
> > Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> > [card] [New services to deploy](#new-services-to-deploy)
> >
> > `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> > [card] [Native script engine for JavaScript and Python](#native-script-engine-for-javascript-and-python)
> >
> > JavaScript and Python business rules and workflow scripts run on a Node.js + CPython subprocess pool by default. HashMap-style access on `output` is preserved; GraalVM remains available via `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`. See the 5.9.0 card above and the migration audit checklist.
>
> > [card] [Ingress routing and CORS handling](#ingress-routing-and-cors-handling)
> >
> > The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> > [card] [Kafka configuration alignment](#kafka-configuration-alignment)
> >
> > Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> > [card] [OpenTelemetry + SpiceDB DR](#opentelemetry-+-spicedb-dr)
> >
> > OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> > [card] [Task management localization](#task-management-localization)
> >
> > 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.

***

## Deployment notes

> [card] [Deployment guidelines v5.9.0](./deployment-guidelines-v5.9)
>
> Component versions, environment variables, Kafka topics, and self-hosted upgrade guidance.

> [card] [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview)
>
> Consolidated 5.1 LTS → 5.9 LTS migration guide. Direct upgrade to 5.9.0.


# Deployment guidelines v5.9.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1

Component versions, configuration, and deployment notes for FlowX.AI 5.9.1 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.1 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.0 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.0 → 5.9.1**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

## Component versions

### Core components

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **process-engine** | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.3 |
| **admin** | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.3 |
| **designer** | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.4 |
| **cms-core** | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.2 |
| **scheduler-core** | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.2 |
| **events-gateway** | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.2 |
| **notification-plugin** | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.2 |
| **document-plugin** | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.2 |
| **task-management-plugin** | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.2 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |
| **data-search** | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.2 |
| **audit-core** | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.2 |
| **advancing-controller** | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.2 |
| **integration-designer** | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.3 |
| **application-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **runtime-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **data-sync** | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.2 |
| **authorization-system** | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.2 |
| **nosql-db-runner** | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.2 |
| **email-gateway** | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-native-sdk** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/core-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **react-saas** | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.20 |
| **Android renderer** | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.24 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-knowledgebase-rag** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-embedder** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-agent-builder** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-gateway** | 10.17.0 | 10.7.0 | - | - |
| **ai-platform-ai-analyst** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-assistant** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-ai-designer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-developer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-planner** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-kb-enrichment** | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.1 adds two Kafka topics. Both are **auto-provisioned by the Helm chart** — no manual creation is required for standard deployments. The names and env vars are listed here for environments that provision topics or ACLs manually.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | application-manager | process-engine | Runtime config-param change events; invalidates the build cache |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine | integration-designer | Notifies that a runtime instance has been terminated |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin | process-engine | Resource cache eviction triggered when a process version changes |
| `ai.flowx.evals.suggestions.job.request.v1` | integration-designer | AI Platform | Evaluation improvement-suggestion job requests |
| `ai.flowx.evals.suggestions.job.response.v1` | AI Platform | integration-designer | Evaluation improvement-suggestion job responses |

Topic env vars and consumer groups:

| Topic | Producer var (OUT) | Consumer var (IN) | Consumer group |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | `config-params` |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_OUT` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_IN` | `integration-designer-runtime-instance-terminated-group` |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT_IN` | `resource-cache-evict` |
| `ai.flowx.evals.suggestions.job.request.v1` | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT` | — (consumed by AI Platform) | — |
| `ai.flowx.evals.suggestions.job.response.v1` | — (produced by AI Platform) | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN` | `integration-designer-evals-suggestions-response-group` |

For the config-param cache-invalidation behavior, see [Engine setup → Topics related to runtime config params](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-runtime-config-params). For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.1 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including split AI permissions, the legacy script flag, and File Storage and document-preview fixes.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.0 → 5.9.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.1** is a maintenance release for the 5.9.x LTS with bug fixes, security patches, and a few targeted improvements:
>
> * **Import/export:** stability and cross-version compatibility fixes
> * **Split AI permissions:** separate governance for AI runtime usage and AI build-time tooling
> * **Legacy script flag:** per-rule Native / GraalVM script runtime selection
> * **File Storage and document-preview improvements**
> * Wide set of Designer, Renderer, and platform bug fixes
> * No breaking changes; fully compatible upgrade from 5.9.0

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Split AI permissions**](#split-ai-permissions) - Independent governance for AI usage and AI build tooling.\
> 📝 [**Legacy script flag**](#legacy-script-flag) - Per-rule Native / GraalVM script runtime selection.\
> 🗂️ [**File Storage improvements**](#file-storage-improvements) - FTP connection and preview fixes.\
> 📄 [**File Preview scroll events**](#file-preview-scroll-events) - Scroll-trigger event handlers for the File Preview component.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, Workflows, and backend bug fixes plus security patches.
>
> ***
>
> ### **Split AI permissions**
>
> > [card] Separate governance for AI usage and AI build tooling
> >
> > > [tab] Overview
> > >
> > > AI permissions are now split into two independent controls, so administrators can govern **AI runtime usage** separately from **AI build-time tooling** (AI Designer, agent building, code generation).
> >
> > > [tab] Behavior
> > >
> > > * When AI is turned off, AI-related icons and entry points are hidden rather than shown in a disabled state.
> > > * AI nodes in workflows behave consistently with the gateway's availability.
> > > * Build-time AI helpers (code generation, "Add comment") follow the dev-agent permission rather than the runtime AI permission.
> >
> > All Deployments
>
> ***
>
> ### **Legacy script flag**
>
> > [card] Per-rule Native / GraalVM script runtime
> >
> > Business rules, reusable functions, and node rules can now choose their script engine individually: the current **native** engine (the 5.9 default) or the legacy **GraalVM** engine. Rules created before the switch to native keep running on GraalVM until you migrate them, while new rules default to native, so teams can move scripts across at their own pace. The per-rule selector only appears for rules that support GraalVM; new rules run on native.
> > All Deployments
>
> ***
>
> ### **File Storage improvements**
>
> > [card] FTP connection and preview fixes
> >
> > * FTP **test connection** now resolves configuration-parameter placeholders before connecting.
> > * **File operations** also resolve configuration-parameter placeholders at runtime.
> > * FTP **file preview** works when the root path has no leading slash.
> >   All Deployments
>
> ***
>
> ### **File Preview scroll events**
>
> > [card] Scroll-trigger event handlers for File Preview
> >
> > The **File Preview** component now supports **scroll-trigger event handlers** (including a "document end" trigger), configurable in the Designer and handled by the web, iOS, and Android renderers. They let a flow detect when a user scrolls through a document or reaches its end.
> >
> > This is built for consent and disclosure use cases such as banking flows that must prove, per local regulation, that the user actually read an agreement. You can keep an action such as a **Submit** or **Accept** button hidden or disabled until the document-end event handler fires; that handler can be a simple local script that sets a flag to enable the button.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Forms to validate:** fixed scrolling through the full component hierarchy, placeholder updates, and incorrect selection of chat and tab-bar components.
> > > > * **Process instances:** fixed a browser crash when loading instances with very large execution graphs.
> > > > * **Theme admin:** fixed theme content being lost when using "copy to".
> > > > * **UI Flow:** fixed images not displaying in preview after refresh, and a missing theme UUID when returning from an expired UI Flow.
> > > > * **Actions:** stopped GET actions firing with undefined parameters.
> > > > * **Modals:** fixed dropdown flicker and layout issues with long key names.
> > >
> > > > [accordion] Renderer fixes (Web / React / React Native)
> > > >
> > > > * **Web:** fixed missing button shadow, modal content padding, and rendering when a media-file storage path is null.
> > > > * **File Preview:** fixed preview not rendering correctly, events not firing inside collections, fixed height not applied at runtime, and CORS errors when accessing preview resources.
> > > > * **React Native:** fixed date-picker shifting to a previous day and input/textarea retaining focus after moving to another component.
> > > > * **Task management:** fixed header theming (React/Angular) and the filter window disappearing after applying criteria.
> > > > * **File upload:** the upload button now supports a configurable icon, set in the Designer and rendered on web, iOS, and Android.
> >
> > > [tab] Workflows & AI
> > >
> > > > [accordion] Workflow fixes
> > > >
> > > > * Fixed END PARALLEL output including data from before the parallel branches started.
> > > > * Optimized storage of running steps for workflows.
> > > > * Fixed a crash in NoSQL node run logs when a node failed before building its options.
> > > > * Workflows and processes launched from a UI Flow now inherit the build from the parent UI Flow.
> > > > * AI node failures now surface the error details and model reasoning in the workflow run logs, making failed AI steps easier to diagnose.
> > >
> > > > [accordion] AI improvements & fixes
> > > >
> > > > * **AI Designer** generates more reliable UI from a flat template format (replacing the previous 3-level nesting), supports additional component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates by applying changes incrementally instead of regenerating from scratch, and can now generate **reusable UI templates**.
> > > > * Fixed agent responses reappearing in chat after stop and refresh.
> > > > * Fixed duplicated messages in the builder-agent chat.
> > > > * **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
> > > > * **Platform Status** now reports AI Platform components and their databases alongside the core services.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * Fixed a null value being wrongly cached when looking up the "All end-users" group, which could block logins until data-sync completed.
> > > > * Fixed copying a process or workflow to another project: the copy now succeeds, and copied workflows appear in the target project.
> > > > * Fixed an invited Designer user added as an Organization owner not being assigned to a workspace.
> > > > * Improved merge-conflict handling for custom components and UI Flows, with clearer resource identification.
> > > > * Hide/disable conditions on UI templates, processes, and UI Flows are now applied at runtime for Designer users without workspace access.
> > > > * Fixed a 500 (duplicate key) error when activating a start timer event after a new build regenerated the process resource ID.
> > > > * Fixed a 500 error when opening a Usage Overview.
> > > > * Organization settings navigation and design improvements.
> > > > * **Runtime config params:** changes to runtime configuration parameters now propagate to the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
> > > > * **Microsoft Outlook connections** now support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.1 is fully compatible with 5.9.0. No breaking changes; standard deployment procedures apply.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.0 → 5.9.1 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.1 are tracked in the [5.9.1 deployment guidelines](./deployment-guidelines-v5.9.1).&#x20;
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2

Component versions, configuration, and deployment notes for FlowX.AI 5.9.2 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.2 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.1 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.1 → 5.9.2**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and converts your data. If you did not apply that workaround, no action is needed.

> [!WARNING]
>
> **Manually marked Liquibase changesets.** If any Liquibase changesets were manually marked as executed (MARK\_RAN) to work around failures during earlier 5.9.x upgrade attempts, those records must be removed after upgrading to 5.9.2 so the corrected changesets can run. Contact FlowX support for the exact list of affected changesets before removing anything. If you did not mark any changesets manually, no action is needed.

## Component versions

### Core components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.162.1 | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.7 |
| **admin** | 10.141.1 | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.7 |
| **designer** | 10.260.7 | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.10 |
| **cms-core** | 10.102.3 | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.3 |
| **scheduler-core** | 10.85.1 | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.3 |
| **events-gateway** | 10.90.1 | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.4 |
| **notification-plugin** | 10.100.2 | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.3 |
| **document-plugin** | 10.113.2 | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.3 |
| **task-management-plugin** | 10.102.1 | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.3 |
| **reporting-plugin**\* | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.7 |
| **data-search** | 10.83.1 | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.3 |
| **audit-core** | 10.93.1 | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.3 |
| **advancing-controller** | 10.89.1 | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.3 |
| **integration-designer** | 10.189.2 | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.4 |
| **application-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **runtime-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **data-sync** | 10.98.0 | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.4 |
| **authorization-system** | 10.112.1 | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.5 |
| **nosql-db-runner** | 10.92.1 | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.3 |
| **email-gateway** | 10.91.1 | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.88.1 | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.60.1 | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.23.1 | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.78.1 | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-native-sdk** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/core-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **react-saas** | 10.260.7 | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.6 | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.25 |
| **Android renderer** | 10.5.6 | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.31 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.0 | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.0 | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.0 | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.0 | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.0 | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.0 | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.25.0 | 10.17.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.0 | - | - | - | - |
| **ai-assistant** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.0 | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.2 | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.2 introduces no new Kafka topics over 5.9.1. For the topics added in 5.9.1, see the [5.9.1 deployment guidelines](../v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics); for the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.2 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

* **Kafka reconnect backoff:** platform services now default to a gentler broker-reconnect backoff — `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MS` `1000` / `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MAX_MS` `10000` (and the consumer equivalents) — and repetitive Kafka NetworkClient connection errors log at a quieter level, tunable via `LOGGING_LEVEL_KAFKA_NETWORK_CLIENT` (default `ERROR`). No action needed unless you previously tuned these.&#x20;
* **Resource-server security type:** the default for `idp.resourceServer.securityType` on the AI services changes to `jwt`. If you previously set the security type to `jwt` explicitly as a workaround, that override is no longer needed and can be removed.&#x20;

#### Data partitioning and archiving

5.9.2 adds configuration for the archiving lifecycle on the process-engine and Integration Designer. All new settings default to off, so no action is required on upgrade.&#x20;

* **Stuck-instance termination:** an optional sweep (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`, default `false`) terminates instances that would otherwise block archiving. Enable it, plus its cron and batch-size, if archiving stalls on unfinished data.
* **Legacy backfill:** one-shot backfills of `partition_id` (`FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED`) and `organization_id` (`FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED`), both default `false`, populate legacy rows when you first turn partitioning on. The organization-ID backfill is optional on self-hosted and can remain `false`.

> [!WARNING]
>
> **Partitions that still contain unfinished instances are not archived.** Starting with 5.9.2, the archiving job detaches a partition only when every process instance in it has reached a finished state (`FINISHED`, `FINISHED_WITH_ERROR`, `FAILED`, `EXPIRED`, `ABORTED`, `DISMISSED`, or `TERMINATED`). A single instance still in `CREATED`, `STARTED`, or `ON_HOLD` blocks the entire partition; it is retried on the next archiving run. The same rule applies to workflow instances on the Integration Designer, where a `STARTED` workflow instance blocks its partition. If partitions accumulate unarchived, terminate the blocking instances — set process expiry, or turn on the stuck-instance termination sweep above.

For the full property tables and defaults, see [Partitioning & archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) (process-engine) and [Integration Designer setup → Workflow partitioning](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration).

#### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them as part of this upgrade. The bundled Qdrant subchart is renamed the same way, so any explicit references to its service host must be updated too.

> [!WARNING]
>
> Core platform services resolve AI Platform components by these new names. Upgrade the AI Platform chart and the core platform services to 5.9.2 together — running a 5.9.1 AI Platform chart against 5.9.2 core services (or the reverse) breaks AI features.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including expanded audit logging, copy-with-roles, and the app-manager organization-ID migration fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.1 → 5.9.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.2** is a maintenance release for the 5.9.x LTS. It pairs a broad bug-fix pass with a few targeted improvements:
>
> * **Expanded audit logging:** coverage for sharing, invitations, user and group management, and process-instance and UI-flow actions
> * **Copy with roles:** copying a resource now also copies its associated roles
> * **Self-hosted upgrade fixes:** smoother installation and upgrade from 5.1.x on self-hosted environments
> * **Key fixes:** active-policy override user list, project-version merge, reusable UI templates in nested containers, and audit-log user filtering&#x20;
> * Wide set of Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.9.2 brings bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions.\
> 👥 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, and backend bug fixes plus security patches.
>
> ***
>
> ### **Expanded audit logging**
>
> > [card] Broader audit coverage for access and lifecycle actions
> >
> > Audit logging now records a wider set of actions, including **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> > All Deployments
>
> ***
>
> ### **Copy with roles**
>
> > [card] Roles travel with copied resources
> >
> > Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Reusable UI templates:** fixed actions missing at runtime when a template is nested in multiple levels of containers.&#x20;
> > > > * **Use in reporting:** the reporting toggle is now available on UI flows and workflows, matching the existing process setting.
> > > > * **UI action keys:** keys to save for collection items and bundled custom-component inputs are now computed automatically, and mapped object keys for collections and custom components are available in runtime data.&#x20;
> > > > * **SQL data sources:** queries on SQL data sources can now be tested from the builds list, mirroring the existing NoSQL runtime test flow.&#x20;
> > > > * **Event handlers:** the Event Handlers section now appears higher in the component configuration panel.&#x20;
> > > > * **Audit logs:** filtering audit entries by user now works when the username differs from the email address.&#x20;
> > > > * **AI agents and data models:** AI Designer and AI Developer now use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it. &#x20;
> > >
> > > > [accordion] Renderer fixes
> > > >
> > > > * **Chat:** the floating chat position is now calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.&#x20;
> > > >
> > > > This release also includes stability fixes across the web, React, React Native, Android, and iOS renderers.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * **Active policy:** fixed the user list appearing empty on the override active-policy form.&#x20;
> > > > * **Project version merge:** fixed a 500 error that could occur during project-version merge.&#x20;
> > > > * **CMS enumerations:** cascading-enum value lookups now resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.&#x20;
> > > > * **Build export with media files:** exporting a build with media file content included now produces an archive that actually contains the binaries.&#x20;
> > > > * **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.&#x20;
> > > > * **Redis Cluster:** UI-template cache keys are now hash-tagged so related keys map to the same cluster slot, preventing cross-slot errors on Redis Cluster deployments.&#x20;
> > > > * **Workflow data:** Mongo partition archiving now batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine was fixed. See [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) for the partitioning and archiving settings.&#x20;
> > > > * **Data sync with private CA certificates:** the data-sync job now runs the same certificate-initialization step as the other platform services, so data-sync migrations that call HTTPS endpoints (such as Keycloak) no longer fail certificate validation in environments using an internal certificate authority.&#x20;
> > > > * **Self-hosted installation and upgrade:** fixed Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding on self-hosted environments. As part of this, the migration-created default end-user group is renamed from `User` to `Users Group`; check the upgrade warning under Additional information if you map IDP groups into FlowX.&#x20;
> > > > * **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.&#x20;
> > > > * **AI workflow nodes:** JSON schema fields now support `${}` placeholders.&#x20;
> > > > * **Multi-KB retrieval:** retrieval can span multiple knowledge bases in a workflow.&#x20;
> > > > * **AI structured output:** responses from AI nodes with a response schema are now validated against it, with automatic repair retries, and node logs include richer run diagnostics such as the failure reason and rejected output.&#x20;
> > > > * **Document Parser:** a new LiteParse engine parses PDFs and images fully locally without GPU or AI calls, and OCR language support expands to English, Romanian, Hungarian, and Bulgarian.&#x20;
> > > > * **Knowledge bases:** a Custom Agent node can now select multiple knowledge bases, each exposed to the agent as its own retrieval tool, replacing the parallel-nodes workaround.&#x20;
> > > > * **Chat file uploads:** end users can attach multiple files in a chat-driven app; uploads are indexed into a knowledge base scoped to the chat session so AI nodes answer grounded in that content.&#x20;
> > > > * **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.&#x20;
> > > >
> > > > This release also includes a broad set of additional fixes and stability improvements across Designer and backend services.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.2 is fully compatible with 5.9.1; standard deployment procedures apply. One migration renames a default end-user group, which needs attention only if group membership is mapped from Keycloak or an external IDP (see the warning below).
>
> > [!WARNING]
> >
> > **Default end-user group renamed from `User` to `Users Group`.** The group that the 5.1.x upgrade migration creates for users who held the `FLOWX_ROLE` realm role is renamed from `User` to `Users Group` when you upgrade to 5.9.2 or any later release. Runtime group matching is by exact name: if a Keycloak **Group Membership** mapper or an external IDP claim emits the old name `User` into `attributes.runtimeGroups`, those values no longer match any FlowX group and affected users **lose solution access on their next sign-in, with no error logged**. Update the mapper or source group name to `Users Group` as part of the upgrade. Groups your admins created themselves, including any you named `User`, are not renamed. See the [runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) setup for where this value is configured.
>
> > [!WARNING]
> >
> > **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration so it converts existing data correctly. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and actually converts your data. If you did not apply that workaround, no action is needed.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.1 → 5.9.2 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.2 are tracked in the [5.9.2 deployment guidelines](./deployment-guidelines-v5.9.2).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3

Component versions, configuration, and deployment notes for FlowX.AI 5.9.3 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.3 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.2 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.2 → 5.9.3**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.0 or 5.9.1 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.165.0 | 10.162.1 | 10.135.0 | 10.106.0 | 9.76.3 |
| **admin** | 10.144.0 | 10.141.1 | 10.116.0 | 10.93.0 | 9.76.3 |
| **designer** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **cms-core** | 10.105.0 | 10.102.3 | 10.86.0 | 10.67.0 | 9.47.3 |
| **scheduler-core** | 10.87.0 | 10.85.1 | 10.70.0 | 10.53.0 | 9.36.3 |
| **events-gateway** | 10.93.0 | 10.90.1 | 10.72.0 | 10.55.0 | 9.37.3 |
| **notification-plugin** | 10.103.0 | 10.100.2 | 10.83.0 | 10.64.0 | 9.40.3 |
| **document-plugin** | 10.116.0 | 10.113.2 | 10.94.0 | 10.75.0 | 9.45.3 |
| **task-management-plugin** | 10.105.0 | 10.102.1 | 10.84.0 | 10.66.0 | 9.44.4 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.85.0 | 10.83.1 | 10.69.0 | 10.52.0 | 9.33.3 |
| **audit-core** | 10.95.0 | 10.93.1 | 10.79.0 | 10.63.0 | 9.41.3 |
| **advancing-controller** | 10.91.0 | 10.89.1 | 10.73.0 | 10.55.0 | 9.36.3 |
| **integration-designer** | 10.192.0 | 10.189.2 | 10.162.0 | 10.128.0 | 9.60.3 |
| **application-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **runtime-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **data-sync** | 10.100.0 | 10.98.0 | 10.81.0 | 10.58.0 | 9.34.2 |
| **authorization-system** | 10.115.0 | 10.112.1 | 10.96.1 | 10.77.0 | 9.44.4 |
| **nosql-db-runner** | 10.94.0 | 10.92.1 | 10.75.0 | 10.56.0 | 9.32.3 |
| **email-gateway** | 10.93.0 | 10.91.1 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.90.0 | 10.88.1 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.62.0 | 10.60.1 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.25.0 | 10.23.1 | 10.8.0 | - | - |
| **license** | 10.80.0 | 10.78.1 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-native-sdk** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/core-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **react-saas** | 10.265.6 | 10.260.7 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.11 | 10.5.6 | 10.4.1 | 10.3.0 | 9.0.27 |
| **Android renderer** | 10.6.6 | 10.5.6 | 10.5.0 | 10.3.0 | 9.0.37 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](../v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.1 | 10.9.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.1 | 10.9.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.1 | 10.9.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.1 | 10.9.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.1 | 10.9.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.1 | 10.9.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.27.0 | 10.25.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.1 | 10.9.0 | - | - | - |
| **ai-assistant** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.1 | 10.9.0 | - | - | - |
| **flowx-docs** | 5.9.3 | 5.9.2 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.3 introduces no new Kafka topics over 5.9.2. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.3 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Events Gateway — Redis connection pool for blocking mode

The Events Gateway's blocking read path is rebuilt on a dedicated Redis connection pool, fixing a connection leak that could previously require periodic Events Gateway restarts under sustained load. The new settings ship with working defaults — no action is required on upgrade.

| Environment variable | Default | Change in 5.9.3 |
| - | - | - |
| `EVENTS_REDIS_POOL_ENABLED` | `true` | New — dedicated connection pool for blocking reads |
| `EVENTS_REDIS_POOL_MAXTOTAL` | `50` | New — maximum pooled connections |
| `EVENTS_REDIS_POOL_MAXIDLE` | `50` | New — maximum idle pooled connections |
| `EVENTS_REDIS_POOL_MINIDLE` | `5` | New — minimum idle pooled connections |
| `EVENTS_REDIS_POOL_MAXWAITMILLIS` | `5000` | New — wait time for a pooled connection before failing |
| `EVENTS_REDIS_SSE_BUFFERSIZE` | `256` | New — per-subscriber SSE backpressure buffer |
| `EVENTS_REDIS_BLOCKDURATIONSECONDS` | `1` | Default lowered from `5` — shortens the blocking-read reissue interval |

If you previously set `EVENTS_REDIS_BLOCKDURATIONSECONDS` explicitly, review whether the new default suits your setup. See the [Events Gateway setup guide](/5.9/setup-guides/events-gateway-setup#events) for the full configuration reference.

#### Integration Designer — workflow topic partitions

`FLOWX_WORKFLOW_TOPICPARTITIONS` (default `1`) sets the number of partitions for auto-created workflow Kafka topics (used with `FLOWX_WORKFLOW_CREATETOPICS`). Existing topics are not modified; the setting applies to newly created topics only.&#x20;

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including the Events Gateway Redis connection-leak fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.2 → 5.9.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.3** is a maintenance release for the 5.9.x LTS:
>
> * **Real-time event delivery:** fixes a Redis connection leak in the Events Gateway that could previously require periodic restarts under sustained load
> * **Key fixes:** build import race during multi-dependency imports, task-management allocation rules, project re-creation error handling
> * **New configuration:** Events Gateway connection-pool tuning and workflow Kafka topic partitions
> * Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.2

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform improvements**](#platform-improvements) - Events Gateway stability, Designer and backend bug fixes, security patches.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Real-time event delivery:** fixed a Redis connection leak in the Events Gateway. Blocking reads now run on a dedicated connection pool with Redis Cluster support, eliminating the gradual connection buildup that could previously require periodic Events Gateway restarts. New tuning options are available — see the [deployment guidelines](./deployment-guidelines-v5.9.3#configuration-changes).
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it, and duplicate rules are no longer created when Save is clicked twice. Task views also no longer reset when the same view is open from different workspaces.&#x20;
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **Designer stability:** fixed a freeze when opening Runtime after expanding a component's Permissions section, and a pending AI UI-generation draft no longer locks the process diagram read-only.&#x20;
> > > > * **Date Picker:** the calendar now anchors correctly to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.&#x20;
> > > > * **Workflows:** fixed a silent workflow freeze that could occur after a step exhausted its retries.&#x20;
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior. UI Flows on iOS also gain support for the `additionalData` object.
> > > >   &#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Media Library:** PDF assets in the list can now be opened in a new tab directly from the Media Library.
> > > > * **Process start loading:** web renderers now keep the loading indicator visible until the first user task renders, matching the mobile SDK behavior.&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.3 is fully compatible with 5.9.2. No configuration changes are required on upgrade; new tuning options ship with working defaults.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.2 → 5.9.3 with no breaking changes
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps are required for this maintenance release. Upgrading directly from 5.9.0 or 5.9.1? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.3](./deployment-guidelines-v5.9.3).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4

Component versions, configuration, and deployment notes for FlowX.AI 5.9.4 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.4 is a maintenance release for the 5.9.x LTS line. The platform upgrade from 5.9.3 is non-breaking, but this release changes how the Helm charts express the container image location, so review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.3 → 5.9.4**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Helm values change.** The charts now express the image location as `image.registry` plus `image.repository` instead of one combined path. Deployments that set `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move it out before upgrading — see [Helm charts: image registry split](#helm-charts-image-registry-split).

> [!NOTE]
>
> **Upgrading from 5.9.0, 5.9.1, or 5.9.2 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.171.3 | 10.165.0 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.149.3 | 10.144.0 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.110.4 | 10.105.0 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.91.2 | 10.87.0 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.97.2 | 10.93.0 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.107.4 | 10.103.0 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.121.3 | 10.116.0 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.109.3 | 10.105.0 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.89.2 | 10.85.0 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.99.2 | 10.95.0 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.95.2 | 10.91.0 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.197.5 | 10.192.0 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.104.3 | 10.100.0 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.119.3 | 10.115.0 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.98.2 | 10.94.0 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.98.2 | 10.93.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.95.2 | 10.90.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.66.2 | 10.62.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.30.2 | 10.25.0 | 10.8.0 | - | - |
| **license** | 10.84.2 | 10.80.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.275.0 | 10.265.6 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.0 | 10.5.11 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.8.0 | 10.6.6 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.2 | 10.9.1 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.10.2 | 10.9.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.10.2 | 10.9.1 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.10.2 | 10.9.1 | 10.1.1 | - | - |
| **speech-to-text** | 10.10.2 | 10.9.1 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.10.2 | 10.9.1 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.32.2 | 10.27.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.10.2 | 10.9.1 | - | - | - |
| **ai-assistant** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.10.2 | 10.9.1 | - | - | - |
| **flowx-docs** | 5.9.4 | 5.9.3 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.4 introduces no new Kafka topics over 5.9.3. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Apply the Helm values change described in [Configuration changes](#configuration-changes), if it affects your setup.
2. Update container images to the 5.9.4 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Helm charts: image registry split

Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.

```yaml theme={"dark"}
# Before
image:
  repository: <registry>/<image-name>

# After
image:
  registry: <registry>
  repository: <image-name>
```

The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.

**Upgrade notes**

* **If you set `global.imageRegistry` to point the charts at your own registry** (the standard, documented approach): no action is required. Your override continues to work, and it now applies cleanly to the default bare repository names.
* **If you embedded the registry inside `image.repository`** (for example `image.repository: harbor.mycorp.internal/flowx/<image-name>`): move the registry portion out. Set it through `global.imageRegistry`, or the chart's `image.registry`, and let `image.repository` fall back to its default bare image name. Leaving the registry in `image.repository` alongside the now-populated `image.registry` prepends the registry twice.

  This applies to deployments configured from the FlowX setup guides before 5.9.4, which showed the combined form. If your values files were built from those examples, check them before upgrading.

#### Events Gateway service account

Events Gateway now authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`, in the service-accounts realm. It needs this identity to resolve and authorize a subscription before admitting the stream.

Two new configuration values are involved, and both take the **same secret**:

| Service | Environment Variable | Purpose |
| - | - | - |
| authorization-system | `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXEVENTSGATEWAYSA` | Secret the migration assigns to the client it creates |
| events-gateway | `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Secret Events Gateway authenticates with |

**Upgrade notes**

* **If you deploy with the FlowX Helm charts and authorization-system runs its migrations with Keycloak admin access**: no action is required. The chart already maps both values to the `KEYCLOAK_EVENTS_GATEWAY_CLIENT_SECRET` key of the `keycloak-flowx-realm-clients` secret, and the authorization-system migration creates the client and grants it the `SA_FLOWX` role.
* **If you manage Keycloak clients outside the chart** (external IdP, or authorization-system cannot provision clients): create `flowx-events-gateway-sa` in the service-accounts realm as a confidential client with service accounts enabled and only the client-credentials grant, then supply its secret to both values above.

> [!WARNING]
>
> If `flowx-events-gateway-sa` already exists, the migration leaves its secret untouched by design. A pre-existing client whose secret does not match the one given to Events Gateway will not be corrected on upgrade, and Events Gateway will fail to authorize subscriptions. Make the two match manually in that case.

#### Liquibase migration lock moves to database session locks

The lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so a stale `databasechangeloglock` row no longer needs clearing by hand. On any other database, Liquibase falls back to its standard row-based lock.

The previous mechanism verified the lock-holder pod through the Kubernetes API. That dependency is gone:

* Service accounts no longer need the `get pods/status` permission, and the FlowX Helm charts no longer create the corresponding Role and RoleBinding. If you maintain that RBAC outside the charts, you can remove the grant.
* The lock keeps working on Kubernetes 1.33 and newer, where the previous mechanism silently deactivated itself.

**Oracle deployments** must grant each FlowX service's database user the following before upgrading. A service whose grants are missing stops at startup with an error naming the missing grant:

```sql theme={"dark"}
GRANT EXECUTE ON SYS.DBMS_LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$SESSION TO <app_user>;
```

PostgreSQL deployments need no action: advisory locks require no additional grant.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, the Angular 21 renderer upgrade, and a Helm chart image-registry change.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. The platform upgrade from **5.9.3 → 5.9.4** requires no data migration, but it does change how the Helm charts express the container image location. Review the [deployment guidelines](./deployment-guidelines-v5.9.4#configuration-changes) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.4** is a maintenance release for the 5.9.x LTS:
>
> * **Helm charts:** the container image reference splits into `image.registry` and `image.repository`, making `global.imageRegistry` a single chart-wide override
> * **Angular 21:** the Angular renderer and the web SDKs move to Angular 21
> * **Key fixes:** branch merges no longer getting stuck, build export retry after a dependency timeout, deleting actions that call functions, gateway expression failures surfaced as incidents, library resource overview
> * **Cross-version import:** an imported theme is completed from the destination's system theme, so nothing is missing after importing an older export
> * Designer, renderer, and backend stability fixes plus security patches
> * No data migration; the only upgrade action is the Helm values change, and only for one override pattern

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, plus a Helm chart change that affects some self-hosted deployments.
>
> 📦 [**Helm chart image registry**](#helm-chart-image-registry) - `image.repository` splits into `image.registry` + `image.repository`\
> 🅰️ [**Angular 21**](#angular-21) - The Angular renderer and web SDKs move to Angular 21\
> 🔧 [**Platform improvements**](#platform-improvements) - Bug fixes and security patches
>
> ***
>
> ### **Helm chart image registry**
>
> > [card] image.repository splits into image.registry + image.repository
> >
> > Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.
> >
> > ```yaml theme={"dark"}
> > # Before
> > image:
> >   repository: <registry>/<image-name>
> >
> > # After
> > image:
> >   registry: <registry>
> >   repository: <image-name>
> > ```
> >
> > The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.
> >
> > > [!WARNING]
> > >
> > > **Check your values files before upgrading.** If you set `global.imageRegistry`, no action is needed. If you embedded the registry inside `image.repository`, move it out first, or the registry is prepended twice. This includes values files built from the FlowX setup guides before 5.9.4, which showed the combined form. Full before-and-after in the [deployment guidelines](./deployment-guidelines-v5.9.4#helm-charts-image-registry-split).
> >
> > All Deployments
>
> ***
>
> ### **Angular 21**
>
> > [card] Angular renderer and web SDKs on Angular 21
> >
> > The Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps embedding the Angular SDK should be on Angular 21 before taking 5.9.4.
> >
> > Angular does not support skipping a major in a single update, so step through the official update guide one major at a time. The **npm** and **node** requirements are unchanged from 5.9.3.
> >
> > See the [Angular SDK requirements](/5.9/sdks/angular-renderer#angular-project-requirements) for the current version floor, and the [Angular migration guide](/5.9/migrating-from-5.1-lts/angular#framework-upgrade-angular-19-→-21) for the upgrade path.
> >
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build export:** retrying a build export now re-attempts a dependency library whose own export ended in a timeout, instead of failing again immediately. Previously the retry skipped the timed-out dependency, so the parent build could never finish; the workaround was to export that dependency directly first.&#x20;
> > > > * **Actions:** deleting an action whose business rule calls a function now works instead of returning a server error. This affected any action at any nesting level, in both projects and libraries; the workaround was to delete the rule from the action first.&#x20;
> > > > * **Gateways:** an expression that fails to evaluate on an exclusive gateway now surfaces as an incident on the process instance. Previously the failure appeared only in the service logs, with no feedback in the platform.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection. Changing the page size no longer opens the wrong process from the list. &#x20;
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives while a background synchronization is still running, and merging versions no longer fails with a navigation-areas error.&#x20;
> > > > * **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds. The page index was previously lost on back-navigation.&#x20;
> > > > * **Reusable UI templates:** static input mappings configured on a reusable template are now applied at runtime.&#x20;
> > > > * **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.&#x20;
> > > > * **Entry points:** the entry-point picker in version settings now lists only processes and UI flows from the current project. Resources from dependency libraries were previously offered and could be selected.&#x20;
> > > > * **Themes and CMS resources:** exporting a theme no longer includes duplicate non-system copies of system icons, so repeated imports stop multiplying them, and importing no longer leaves system substitution tags missing.&#x20;
> > > > * **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output built from trailing empty cells and rows.&#x20;
> > > > * **Generated documents:** a document whose storage write fails now returns an error instead of being recorded as successful with a download path that cannot be opened. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.&#x20;
> > > > * **Renderers:** the document preview shows its subtitle again, and the file-upload error message picks up the configured theme.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Cross-version import:** importing a project build or version exported from an older platform line now completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten, so customizations survive.&#x20;
> > > > * **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.&#x20;
> > > > * **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.&#x20;
> > > > * **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.&#x20;
> > > > * **Integration Designer performance:** service startup no longer scans the full token-instance collection to warm up, and the run-list summary queries are indexed and gated.&#x20;
> > > > * **Database migrations:** the lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so there is no stale `databasechangeloglock` row to clear by hand. The previous mechanism recovered a stuck lock through the Kubernetes API, which required the `pods/status` permission on every service account and silently deactivated on Kubernetes 1.33 and newer. Oracle deployments need new database grants before upgrading: see the [deployment guidelines](./deployment-guidelines-v5.9.4#liquibase-migration-lock-moves-to-database-session-locks).&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade compatibility:** FlowX.AI 5.9.4 is compatible with 5.9.3. No data migration is required. One deployment-level change applies: the Helm charts split the image reference into `image.registry` and `image.repository`. Oracle deployments also need new database grants for the Liquibase migration session lock.
>
> > [!WARNING]
> >
> > **Helm values migration.** Deployments that redirect images through `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move the registry portion out before upgrading. See [Configuration changes](./deployment-guidelines-v5.9.4#configuration-changes).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Direct upgrade from 5.9.3 → 5.9.4. No data migration; review the Helm values change first.
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. The Angular SDK moves to Angular 21.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.4](./deployment-guidelines-v5.9.4).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5

Component versions, configuration, and deployment notes for FlowX.AI 5.9.5 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.5 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.4 is non-breaking and requires no data migration. The headline addition, native PostgreSQL partitioning, is opt-in: deployments that never enabled data partitioning are not affected. Review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.4 → 5.9.5**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.3 or earlier directly?** Review the [5.9.4 deployment guidelines](../v5.9.4-august-2026/deployment-guidelines-v5.9.4) first: the Helm image registry split applies when you skip 5.9.4. Upgrading from 5.9.0, 5.9.1, or 5.9.2, also review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) for the organization-ID migration fix and manually marked Liquibase changesets.

## Component versions

### Core components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.10 | 10.171.3 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.7 | 10.149.3 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.7 | 10.110.4 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.6 | 10.91.2 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.100.7 | 10.97.2 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.110.7 | 10.107.4 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.7 | 10.121.3 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.6 | 10.109.3 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.6 | 10.89.2 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.6 | 10.99.2 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.7 | 10.95.2 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.200.9 | 10.197.5 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.7 | 10.104.3 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.7 | 10.119.3 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.6 | 10.98.2 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.101.6 | 10.98.2 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.6 | 10.95.2 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.6 | 10.66.2 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.7 | 10.30.2 | 10.8.0 | - | - |
| **license** | 10.87.6 | 10.84.2 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB**: see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.282.5 | 10.275.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.2 | 10.6.0 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.9.3 | 10.8.0 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.0 | 10.10.2 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.0 | 10.10.2 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.0 | 10.10.2 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.0 | 10.10.2 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.0 | 10.10.2 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.0 | 10.10.2 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.6 | 10.32.2 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.0 | 10.10.2 | - | - | - |
| **ai-assistant** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.0 | 10.10.2 | - | - | - |
| **flowx-docs** | 5.9.5 | 5.9.4 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.5 introduces no new Kafka topics over 5.9.4. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Review [Configuration changes](#configuration-changes): everything new in this release is opt-in or ships with a safe default, so no values change is required for a standard upgrade.
2. Update container images to the 5.9.5 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Native PostgreSQL partitioning (opt-in)

Process-instance archiving on PostgreSQL can now use native declarative partitions instead of the legacy copy-based mechanism. Data partitioning itself remains **off by default** (`FLOWX_DATA_PARTITIONING_ENABLED` is `false`), so deployments that never enabled it are not affected.

New process-engine variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Use native PostgreSQL partitions for archiving when partitioning is enabled. PostgreSQL only; other databases keep the existing mechanism. | `true` |
| `FLOWX_DATA_PARTITIONING_PREMAKECRONEXPRESSION` | Schedule for the job that creates upcoming partitions in advance. | `0 0 23 * * ?` |
| `FLOWX_DATA_PARTITIONING_PREMAKEPARTITIONSAHEAD` | How many future partitions the job keeps created ahead of the current one. | `2` |

> [!WARNING]
>
> Enabling native partitioning converts the process-instance tables to partitioned tables, and the conversion is one way: there is no supported path back to unpartitioned tables. Review the [partitioning and archiving setup guide](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning) before turning it on.

#### Document plugin: processing size limits

The document plugin now enforces size limits on archive, encryption, and extraction operations. Input over the limit is rejected instead of processed. The defaults are generous; override them only if your documents legitimately exceed them.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOCUMENT_ARCHIVE_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for archive operations. | `209715200` (200 MB) |
| `DOCUMENT_ENCRYPTION_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for encryption. | `104857600` (100 MB) |
| `DOCUMENT_EXTRACT_MAX_UNCOMPRESSED_SIZE` | Maximum total uncompressed size, in bytes, an archive may expand to during extraction. | `209715200` (200 MB) |

#### Integration Designer: workflow output size guard

Workflow output published to Kafka is now size-checked before sending. A root workflow output that exceeds the limit fails the workflow run with the failure type `outputTooLargeForKafka` instead of being silently dropped by the broker's message-size limit. The check applies to root workflow outputs on automatic and default-path completion; subworkflow outputs are not checked.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_KAFKA_PAYLOAD_SIZE_LIMIT` | Maximum serialized size, in bytes, of a root workflow output published to Kafka. | `786432` |

> [!TIP]
>
> Keep this limit below your broker's `max.message.bytes`. The default, 768 KB, sits safely under the common 1 MB broker default.

#### Advancing datasource metrics

The process engine and Integration Designer now register their advancing datasource under a named connection pool (`advancing`), so its metrics are distinguishable from the main datasource pool in Prometheus. No configuration action is required.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026

Maintenance release for the 5.9.x LTS line. Native PostgreSQL partitioning for process data, bug fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. It also brings native PostgreSQL partitioning to process data. Review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.5** is a maintenance release for the 5.9.x LTS:
>
> * **Native PostgreSQL partitioning:** process data tables are partitioned by the database itself, so removing old data becomes a partition drop instead of a bulk delete
> * **Key fixes:** audit entries no longer missing or attributed to the wrong application, merge conflicts raised for changes inside embedded subprocesses, self-hosted Keycloak issuer derived from configuration
> * **Integrations:** an SFTP private key can be stored as a multi-line PEM
> * Backend, Designer, and renderer stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.5 is compatible with 5.9.4, and the upgrade requires no data migration. Native PostgreSQL partitioning is opt-in: if you had already enabled data partitioning, review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade, because the conversion to native partitions runs automatically for you and is one way.

**Before you upgrade, check these:**

* **AI job queues:** each AI service now consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group, and the new groups read only jobs published after they start. Wait until the `ai-services` group has no lag on the job topics before you upgrade, so no queued job is skipped. If your cluster restricts consumer groups with ACLs, allow the new groups first.
* **Relational data sources:** Oracle data sources connect only to hosts that resolve to a public address. Add private database hosts to the allowlist, as described in [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Service-account secrets:** confirm every service-account client secret is set on `authorization-system`, or the service stops at startup. The secrets are listed in the [Authorization setup guide](/5.9/setup-guides/authorization-setup-guide).
* **Dashboards and alerts:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total`.
* **Runtime log levels:** the `loggers` actuator endpoint is no longer exposed by default. Add it back as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Data partitioning:** if you had already turned on data partitioning, the conversion to native partitions runs automatically on upgrade and is one way. See the [deployment guidelines](./deployment-guidelines-v5.9.5).

**Upgrade path:** direct upgrade from 5.9.4. Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. Component versions are listed in the [5.9.5 deployment guidelines](./deployment-guidelines-v5.9.5).

***

## Native PostgreSQL partitioning

The process engine stores process data in tables that PostgreSQL itself partitions by time. Retention then
works by dropping whole partitions rather than deleting rows one at a time, which keeps the cost of
removing old data flat as the tables grow.

This is the same partitioning model described for the 5.12 line, delivered into the 5.9.x LTS.

For how partitioning interacts with archiving and retention, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving).

***

## Full changelog

### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.&#x20;
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](#native-postgresql-partitioning).&#x20;

### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.&#x20;
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.&#x20;
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.&#x20;
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.&#x20;
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.&#x20;
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.&#x20;
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.&#x20;
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](./deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).&#x20;
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](./deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).&#x20;
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).&#x20;
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).&#x20;
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.&#x20;
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.&#x20;

### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.&#x20;
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.&#x20;
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.&#x20;
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.&#x20;
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.&#x20;
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.&#x20;
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.&#x20;
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.&#x20;
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.&#x20;
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.&#x20;
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# Deployment guidelines v5.9.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6

Component versions, configuration, and deployment notes for FlowX.AI 5.9.6 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.6 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.5 adds one Kafka topic, a database table, and a MongoDB index. The table and the index are created automatically when the services start. Review [Kafka topics](#kafka-topics), [Configuration changes](#configuration-changes), and the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes) before you deploy.

> [card] Upgrade Path
>
> **5.9.5 → 5.9.6**: Direct upgrade. No manual data migration is required.
>
> **5.9.6 → 6.0.0**: See [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.4 or earlier directly?** Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first, then the earlier pages they point to.

## Component versions

### Core components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.17 | 10.174.10 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.14 | 10.152.7 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.13 | 10.113.7 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.11 | 10.94.6 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.101.1 | 10.100.7 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.111.1 | 10.110.7 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.13 | 10.124.7 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.12 | 10.112.6 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.8 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.11 | 10.92.6 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.11 | 10.102.6 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.12 | 10.98.7 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.201.2 | 10.200.9 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.13 | 10.107.7 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.13 | 10.122.7 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.13 | 10.101.6 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.102.1 | 10.101.6 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.12 | 10.98.6 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.12 | 10.69.6 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.14 | 10.33.7 | 10.8.0 | - | - |
| **license** | 10.87.12 | 10.87.6 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** 1.52.0, deployed and upgraded by the **SpiceDB operator** 1.25.1.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **solution-portal** (renamed from react-saas) | 10.285.4 | 10.282.5 | 10.230.2 | - | - |
| **iOS renderer** | 10.9.2 | 10.6.2 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.10.2 | 10.9.3 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.2 | 10.11.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.2 | 10.11.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.2 | 10.11.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.2 | 10.11.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.2 | 10.11.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.2 | 10.11.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.13 | 10.35.6 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.2 | 10.11.0 | - | - | - |
| **ai-assistant** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.2 | 10.11.0 | - | - | - |
| **flowx-docs** | 5.9.6 | 5.9.5 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.6 adds one Kafka topic. If your cluster does not create topics automatically, create it before you deploy, and allow both services in your ACLs.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.build.deployment-failed.v1` | runtime-manager | application-manager | Reports a build deployment that failed, so application-manager can queue it for a retry. |

The topic is included in the FlowX Kafka topics chart from version 10.2.0. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Create the `ai.flowx.build.deployment-failed.v1` Kafka topic if your cluster does not create topics automatically. See [Kafka topics](#kafka-topics).
2. Review [Configuration changes](#configuration-changes). No values change is required for a standard upgrade.
3. The `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes).
4. Update container images to the 5.9.6 versions listed in the tables above.
5. Deploy services using your standard deployment process.
6. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Build redeployment retries

When a build deployment fails, application-manager queues it for a retry. The queue is now stored in the application-manager database, in the new `failed_deployment` table, instead of in Redis. The table is created automatically on startup. runtime-manager reports each failure on the `ai.flowx.build.deployment-failed.v1` topic, and application-manager consumes it.

New application-manager variables (the defaults fit a standard deployment):

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_BUILD_DEPLOYMENTFAILED` | Topic that carries failed build deployments. | `ai.flowx.build.deployment-failed.v1` |
| `KAFKA_CONSUMER_GROUPID_BUILD_DEPLOYMENTFAILED` | Consumer group that reads the topic. | `build-deployment-failed-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_DEPLOYMENTFAILED` | Number of consumer threads for the topic. | `1` |

> [!WARNING]
>
> Retries that are still queued in Redis when you upgrade are not moved to the new table. Re-publish any build whose deployment failed shortly before the upgrade. The old entries stay in the Redis hash `build:failed-deployments:v3`, under the persistence key prefix configured for application-manager. Nothing reads them after the upgrade, so you can delete the hash.

#### MongoDB setting names

Services that use MongoDB now read their connection settings from new names. The previous `SPRING_DATA_MONGODB_*` variables still feed the new settings, so existing deployments need no change. Use the new names in new configuration.

| Previous variable | New variable |
| - | - |
| `SPRING_DATA_MONGODB_URI` | `SPRING_MONGODB_URI` |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | `SPRING_MONGODB_REPRESENTATION_UUID` |
| `SPRING_DATA_MONGODB_STORAGE` | `FLOWX_DATASOURCE_MONGO_STORAGE` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | `FLOWX_DATASOURCE_APPRUNTIME_ENABLED` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | `FLOWX_DATASOURCE_APPRUNTIME_URI` |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | `FLOWX_DATASOURCE_APPRUNTIME_REPRESENTATION_UUID` |

`SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION` no longer has any effect: indexes on the runtime database are never created automatically.

#### Document parser models

The document parser image now contains its layout, table, and OCR models, so the parser downloads nothing at startup or on the first parse. It runs without internet access and on a read-only filesystem. `USE_DOCLING` no longer has any effect on the document parser and can be removed from its configuration.

#### Integration Designer: document download timeout

A REST node JSON body can include `"@@base64File(<path>)"` to send a Document Plugin file as base64. Downloading the file from the Document Plugin is cancelled after this timeout. See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

New integration-designer variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` | Longest time a Document Plugin file download for a REST node JSON body may take before it is cancelled. | `PT5M` |

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026

Maintenance release for the 5.9.x LTS line. Durable build redeployment retries, project version merge fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Review the [deployment guidelines](./deployment-guidelines-v5.9.6) before you upgrade: this release adds one Kafka topic.

> [card] Release Highlight
>
> **FlowX.AI 5.9.6** is a maintenance release for the 5.9.x LTS:
>
> * **Durable build redeployments:** a build deployment that failed and waits for a retry is stored in the database, so a Redis flush or restart no longer drops it
> * **Key fixes:** project version merges no longer lose navigation areas, Resources Changed no longer flags unchanged resources, and Number attributes keep the selected subtype
> * Backend, Designer, and AI stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.6 is compatible with 5.9.5. The upgrade adds a database table and a MongoDB index, both created automatically when the services start.

**Before you upgrade, check these:**

* **AI Platform Helm chart:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime.&#x20;
* **Kafka topics:** create the `ai.flowx.build.deployment-failed.v1` topic if your cluster does not create topics automatically, and allow it in your ACLs. `runtime-manager` produces it and `application-manager` consumes it. See [Kafka topics](./deployment-guidelines-v5.9.6#kafka-topics).
* **Pending build redeployments:** retries that are still queued in Redis when you upgrade are not carried over. Re-publish any build whose deployment failed shortly before the upgrade. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Workflow node retries:** retry waits now grow exponentially and the max interval caps each wait instead of the whole retry window. Review the retry settings of nodes that rely on the previous timing.
* **Connection tests:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources. Grant these to custom roles that run connection tests.
* **Integration Designer startup:** the first start after the upgrade builds a new index on the `workflow_instances` MongoDB collection. On a large collection, allow extra time before the readiness check passes.
* **React Native SDK hosts:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` and keeps showing the current process, like the Android and iOS SDKs. Update your app to dispose the current process handle and continue the new process. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).

**Upgrade path:** direct upgrade from 5.9.5. Upgrading from 5.9.4 or earlier? Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/React Native/iOS/Android) and Designer 5.9.x. Component versions are listed in the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6).

***

## Full changelog

### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json) and [Integration Designer: document download timeout](./deployment-guidelines-v5.9.6#integration-designer-document-download-timeout).&#x20;

### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.&#x20;
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).&#x20;
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.&#x20;
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect. See [Document parser models](./deployment-guidelines-v5.9.6#document-parser-models).&#x20;
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.&#x20;
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.&#x20;
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](./deployment-guidelines-v5.9.6#mongodb-setting-names).&#x20;
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.&#x20;
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.&#x20;
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6) for its version.&#x20;

### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.&#x20;
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.&#x20;
* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.&#x20;
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.&#x20;
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.&#x20;
* **React Native SDK:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` instead of replacing the shown process itself, like the Android and iOS SDKs. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).&#x20;
* **React Native SDK:** a custom component keeps receiving data after the app returns from the background, for example from the Android document picker, so a document upload waiting for its link completes.&#x20;
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.9.x to 6.0.0 changelog
Source: https://docs.flowx.ai/release-notes/v6.x/5.9-to-6.0-changelog

Every change a self-hosted FlowX.AI 5.9.x installation picks up when it moves to 6.0.0, grouped by release and type, with an RSS feed.

This page lists what changes for a self-hosted FlowX.AI 5.9.x installation that moves to 6.0.0, newest first. Releases 5.10 to 5.13 shipped to SaaS first, and self-hosted installations get their features with 6.0.0. Changes already delivered in a 5.9.x patch are in the [5.9.x LTS changelog](/release-notes/v5.x/5.9-lts-changelog) and are not repeated here. Mobile renderers and the React Native SDK are covered in their own release notes.

On FlowX.AI SaaS, apps moved from 5.13.0 to 6.0.0, so only the 6.0.0 entry applies to them, including its upgrade actions.

**6.0.0**

October 2026

**Upgrade actions:** check these in your existing apps.

* **AI node prompts:** the chat message is no longer appended. Reference `${userMessage}` in **Context**. [Details](/6.x/ai-platform/chat-driven-workflows#context)
* **AI node retries:** on by default, up to 10 times, 30 seconds apart. [Details](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service)
* **Substitution tags:** `@@key` is rewritten to `${tag:key}`, and a missing `sys_*` tag now renders empty. [Details](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#what-changes-in-existing-apps-when-you-upgrade)
* **FlowX Database and Unmanaged MongoDB writes:** `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter are rejected. To match every document, pass `{"_id": {"$exists": true}}`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb)
* **Masked names:** data-privacy placeholders now carry the gender, such as `<NAME_F_1>`. Update prompts or scripts that match `<NAME_1>`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy)
* **Email triggers over IMAPS:** the mail server's certificate is now verified, so a self-signed or mismatched certificate stops the trigger from connecting. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway)
* **Evaluations:** datasets become test cases with no checks, so an experiment skips them until you add an assert or evaluator. [Details](/6.x/ai-platform/evaluations#datasets-from-earlier-versions)
* **Exports from 5.1.x:** they no longer import, and 5.1.x is no longer an export target. Import a 5.1.x export into a 5.9.x environment and export it again from there. [Details](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x)
* **Scripts on GraalVM:** they now stop at the same per-language time limit as the native engine, 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0 they had no limit. [Details](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits)

Self-hosted installations also follow the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) and the [migration guide](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview) for the Helm chart and renderer SDKs.

#### New

* **Developer Agentic Harness:** a plan can split the work into stories, delivered one at a time, each with how to test it. Comment mode lets you select a component in the running app and ask for a change, and conversations follow you across the Designer. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Integration Designer:** add schedules to a workflow's Start node to run it once on a date or repeatedly on an ISO or cron cycle. A schedule fires only after you activate it in **Runtime** → **Runtime Settings** → **Schedules**. See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
* **Integration Designer:** the Generate Tabular File node turns an array of rows into a CSV or XLSX file. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
* **FlowX Database:** an index can enforce unique values on one attribute or a compound key, and existing duplicates are reported when you run **Apply Indexes**. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
* **Knowledge Base:** **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
* **Resources:** **Documentation** in a resource's menu holds a short description and longer Markdown documentation. Media Library assets get a description, used as the image's alt text. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
* **Substitution tags:** write `${tag:key}` anywhere in a component's text, next to static text and process data. The upgrade rewrites whole-value `@@key` references to `${tag:key}`, and `@@key` keeps working as a whole value. See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).

#### Changed

* **Designer header:** the header holds the project name, the **Config** / **Runtime** switch, the **Build with AI** and **Comment** toggles, and **Run project**. Branching, the current version, and **Commit Changes** move to a version block in the footer. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
* **AI nodes:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when its AI service or provider can't be reached. Turn on **Allow Retry** to set your own count, interval, and backoff. See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
* **Chat-driven workflows:** the chat message is no longer appended to an AI node's prompt. Reference `${userMessage}` in the node's **Context**. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
* **Evaluations:** each workflow has its own test cases, grouped by tags, with **equals** and **equals as JSON** asserts and LLM evaluators. The upgrade converts datasets to test cases with no checks, so add an assert or evaluator to each one before you run it. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
* **Certificates:** the **Certificates** panel on REST and File Storage data sources has two parts: **Trust** (System CAs, Custom CA, or None (insecure)) and **Identity** for mutual TLS. Existing settings are converted automatically. See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates).
* **Knowledge Base:** turning **Containing Personal Information** on or off re-embeds the existing content with the new model. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested).
* **Issues Console:** a check also covers the version itself: entry points, theme, library builds, and unused dependencies. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
* **Notification center:** covers version imports and build exports and imports, alongside version exports and process instance migrations. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
* **Configuration parameters:** after you save a sensitive value, the Designer shows `********` in its place. The real value is still used at runtime. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
* **Script engine:** scripts on GraalVM stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
* **Canvas:** **Auto-arrange** on the workflow canvas and **Arrange** on the process canvas show a layout preview before anything moves. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).
* **Timer events:** timer nodes use the schedule editor. Dates and times are picked in local time and saved in UTC. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).
* **Versioning:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).
* **Datepicker:** **Allow manual input** lets users type a date in the pattern of the project's default locale. Web only.
* **Data mapping:** typing a new attribute path, such as `client.address.street`, creates the data types it names when you save the mapping.

#### Removed

* **AI agents:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors are removed. Open the agent rail with ⌘K (Ctrl+K) or the sparkle toggle in the header. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Evaluations:** the Code evaluators are removed. Use **equals** in place of Exact match and **equals as JSON** in place of JSON match. Levenshtein has no replacement. See [Evaluations](/6.x/ai-platform/evaluations).
* **Export and import:** exports from 5.1.x no longer import, and 5.1.x is no longer an export target. See [Exports from 5.1.x](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x).

#### Deprecated

* **GraalVM script engine:** deprecated. FlowX.AI 6.1.x is the last release family that supports it. Scripts on GraalVM keep working in 6.0.0; move them to the native engine. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).

[6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) · [6.0.0 deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)

**5.13.0**

September 2026

#### New

* **Developer Agentic Harness:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys the app, drafts a plan for you to confirm, and runs the change on its own branch; merging and serving a new version stay with you. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Notification center:** a bell in the Designer opens a 30-day notification history with read state, search, and filters. See [Notification center](/6.x/docs/flowx-designer/notification-center).
* **UI Designer:** copy UI components and paste them into another UI Flow, app, or context. The paste names anything it could not place, and pasted components get unique names.
* **Versioning:** committing or merging a version takes an optional description of up to 2000 characters, and a commit details view shows what a version contains. See [Commit descriptions and details](/6.x/docs/projects/managing-applications/versioning#commit-descriptions-and-details).
* **Runtime:** an operator with the corrective-actions role moves the token of a running process instance to another node. See [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
* **Document classifiers:** a classifier's corpus can be exported and imported between environments, and viewed read-only in the **Data** tab. See [What travels between environments](/6.x/docs/platform-deep-dive/integrations/document-classifiers#what-travels-between-environments).
* **Integration Designer:** the File Encryption node encrypts or decrypts a file with a password inside a workflow. The file path and password take expressions.
* **UI Designer:** a start workflow trigger takes a condition, so the workflow starts only when the condition holds.&#x20;
* **FlowX Database:** the Intersects operator matches documents whose array field shares at least one value with a given list. See [Intersects on array fields](/6.x/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).
* **Personal Information Guard:** AI nodes with the input scan on log the request as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/6.x/ai-platform/personal-information-guard#request-after-pii-anonymization).

#### Changed

* **Access management:** the Workspace corrective actions editor role replaces the Workspace operations editor role. Users and groups with the old role move to the new one automatically. See [Workspace corrective actions editor permission matrix](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
* **Export and import:** version exports bundle dependencies the same way build exports do, and the export dialog preselects the target platform version. See [Version exports that bundle dependencies](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#version-exports-that-bundle-dependencies).
* **Integration Designer:** the Tabular Data Extraction node becomes the Data Parse node and also parses XML and JSON. See [Data Parse: XML and JSON support](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support).
* **Knowledge Base:** embedding jobs are scheduled fairly by default, so a large ingestion no longer delays small jobs queued behind it.
* **File sources:** Document and Image components share one source configuration. In process user tasks, the **Document Plugin Path** source takes a Documents plugin `downloadPath` directly. See [Selecting the file to download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download#selecting-the-file-to-download).
* **Task management:** the task list searches, filters, and sorts on the translated labels it displays. See [Search and sort on translated labels](/6.x/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).
* **Substitution tags:** custom tags can no longer start with `sys_`, which is reserved for system tags. See [Substitution tags](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags).
* **Elasticsearch:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Elasticsearch replica auto-expansion](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).
* **Processes:** the process name moves from **Settings** into a **Details** modal.
* **User management:** inviting many users at once has a reworked flow, and a sign-up link takes new users directly to the right solution.

[5.13.0 release notes](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) · [5.13.0 deployment guidelines](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13)

**5.12.0**

September 2026

**Upgrade actions:** the webhook gateway now reads the runtime registry, which adds a MongoDB dependency it did not have before. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets).

#### New

* **Integration Designer:** turn on **Parallel Multi-Instance** on a Subworkflow node to start one subworkflow per element of an input array and collect the results in an output array. See [Parallel multi-instance](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance).
* **Integration Designer:** email and webhook triggers can start an integration workflow, not only a process. See [External triggers](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).
* **Integration Designer:** a Subworkflow node can route a mapping failure to its own branch instead of stopping the parent workflow. It is opt-in per node. See [Routing a subworkflow failure](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
* **Integration Designer:** the Send Notification node fills a project notification template from workflow data and sends it. See [Send Notification node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node).
* **Db2 data source:** IBM Db2 joins the relational data sources, with Db2 for i as the default and Db2 LUW also supported. Db2 for z/OS is listed but not implemented, and selecting it fails with an error. See [Db2 database](/6.x/docs/platform-deep-dive/integrations/db2-database).
* **Runtime:** bulk migration moves a filtered set of process instances to a new build in one run, with a check before it runs. See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances).
* **Runtime:** a Workflow Instances page lists every workflow run in the project, filterable by status, date, and origin. The Process Instances and UI Flow Sessions lists gain status and start-date filters. See [Workflow instances](/6.x/docs/projects/runtime/workflow-instances).
* **Personal Information Guard:** mask and restore nodes place personal-data handling as explicit workflow steps. See [Masking and restoring across several nodes](/6.x/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
* **Deep Research node:** researches a question across the open web and files a cited report into a Knowledge Base. Depth is Quick, Standard, Deep, or Custom, and domains can be restricted with an allow or deny list. See [Deep Research node](/6.x/docs/platform-deep-dive/integrations/deep-research-node).
* **Custom Agent:** a reusable function with input and output slices can be an agent tool. Built-in tools are a catalog of twenty tools in five categories: Math, List, Date, Text, and Web search. See [Tools tab](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#tools-tab).
* **Chat component:** users rate an agent's answer and add a reason, and the ratings are recorded in audit. See [Rating an answer](/6.x/ai-platform/chat-component#rating-an-answer).
* **Evaluations:** custom evaluators score with Numeric or Binary rules and belong to the workflow you create them in. See [Custom evaluators](/6.x/ai-platform/evaluations#custom).
* **Issues panel:** the Designer validates the resources in a project version and collects the findings in one **Issues** panel. See [Checking for issues](/6.x/docs/projects/managing-applications/checking-for-issues).
* **Versioning:** merge into any branch you can merge into, and archive, unarchive, or delete branches. See [Managing branches](/6.x/docs/projects/managing-applications/versioning#managing-branches).
* **Process canvas:** a **New Node** panel, drop-anywhere connecting, draggable control points on sequence flows, and swimlanes that resize from all four edges. See [Faster ways to build](/6.x/docs/building-blocks/process/process#faster-ways-to-build).
* **Reusable UI templates:** a template can be built for UI Flow pages as well as process user tasks. Templates created earlier count as Process templates. See [Where a template can be used](/6.x/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used).

[5.12.0 release notes](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026) · [5.12.0 deployment guidelines](/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12)

**5.11.0**

August 2026

#### New

* **Custom Agent:** attach FlowX workflows as tools, each with a hint that tells the agent when to call it. See [How workflow tools run](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run).
* **Custom Agent:** agentic knowledge base search breaks a question into sub-queries and retries with reworded queries when the first pass finds nothing. **Show Reasoning** records the model's reasoning summary in the logs. See [Agentic knowledge base search](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#agentic-knowledge-base-search).
* **Knowledge Base:** a Knowledge Base with **Containing Personal Information** on can use a local embedding model, set up as a CUSTOM provider in the organization AI settings. See [Containing personal information](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).
* **Knowledge Base:** the Update Knowledge Base node can delete entries that match a metadata filter, and its FAIL branch reports what failed and how many chunks were rolled back. See [Delete entries](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#delete-entries).
* **Document classifiers:** define classes, upload training data, and train or import a model, then route each document page with the Document Classification node. See [Document classifiers](/6.x/docs/platform-deep-dive/integrations/document-classifiers).
* **Reusable functions:** Script and Condition (Fork) nodes in the Integration Designer can call reusable functions. See [Reusable functions](/6.x/docs/building-blocks/reusable-resources/reusable-functions).
* **Integration Designer:** the Subworkflow node can map input per start node and output per end node instead of raw JSON. See [Subworkflow node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#subworkflow-node).
* **Data model:** attributes support validators such as Required, Min/Max Value, Min/Max Length, Pattern, and Email Format, wherever the data model is used. See [Attribute validations](/6.x/docs/building-blocks/project-data-model#attribute-validations).
* **Templates:** document and notification templates use the structured data model, with typed attributes and an **Input Parameters** tab. See [Managing notification templates](/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates).
* **Chat component:** the chat button shows an unread-message badge, the panel searches conversation history, and the input can be disabled by a condition. See [Chat](/6.x/docs/building-blocks/ui-designer/ui-component-types/chat).
* **UI Flows:** a **Navigate To** action can require selected forms to pass validation before it navigates. See [Navigate To action](/6.x/docs/building-blocks/ui-flows#navigate-to-action).
* **UI Flows:** with **Allow multiple editors** off, a running session is restricted to its owner. New flows default to single-owner; existing and imported flows keep the shared behavior. See [Session owner](/6.x/docs/building-blocks/ui-flows#session-owner).
* **Process Renderer:** a process-end trigger runs a configured action when the embedded process ends. See [Process end handling](/6.x/docs/building-blocks/ui-flows#process-end-handling).

#### Changed

* **Chat-driven workflows:** a conversational workflow must send at least one chat reply, or the run fails with an error. See [Chat-driven workflows](/6.x/ai-platform/chat-driven-workflows).
* **Custom Agent:** the **Instructions** field is limited to 10,000 characters. See [Custom Agent node](/6.x/docs/platform-deep-dive/integrations/custom-agent-node).
* **Response caching:** POST REST endpoints, file-storage LIST and DOWNLOAD, and Mongo FIND, FIND\_ONE, and AGGREGATE operations are cacheable. Mutating operations are never cached. See [REST endpoint caching](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching).
* **Email triggers:** Email Trigger and Microsoft Outlook data sources filter attachments by file extension. Existing category selections are migrated automatically. See [Attachment handling](/6.x/docs/platform-deep-dive/integrations/email-trigger#attachment-handling).
* **Audit:** UI Flow runtime sessions are audited in more detail, including workflow runs, chat messages, and conversation reads. See [Audit](/6.x/docs/platform-deep-dive/core-extensions/audit).
* **Export and import:** exporting to an older platform version removes UI-template features the target cannot read. See [Cross-version export and import](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
* **UI Flows:** an expired session shows a session-expired screen with a start-fresh option.
* **Renderers:** enumeration lookups are batched into a single request.

[5.11.0 release notes](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026) · [5.11.0 deployment guidelines](/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11)

**5.10.0**

July 2026

#### New

* **PostgreSQL data source:** connect a workflow to a PostgreSQL database and run SQL query operations from workflow nodes. See [PostgreSQL database](/6.x/docs/platform-deep-dive/integrations/postgresql-database).
* **SOAP data source:** import a WSDL from a URL or file, and call each operation from workflows with a SOAP Operation node. See [SOAP System](/6.x/docs/platform-deep-dive/integrations/soap-system).
* **FlowX Database:** MongoDB aggregation pipelines group, join, and reshape documents beyond a single query. See [Aggregation pipelines](/6.x/docs/platform-deep-dive/integrations/flowx-database#aggregation-pipelines).
* **Integration Designer:** the Tabular Data Extraction node reads a spreadsheet or CSV file into structured JSON, one object per row. See [Tabular Data Extraction node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node).
* **Integration Designer:** the Template Filling node generates a PDF or DOCX document from a document template filled with workflow data. See [Template Filling node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node).
* **Integration Designer:** the Combine Files node merges PDFs in a given order, and the Split File node splits a PDF by page ranges or per page. See [Combine Files node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node).
* **Documents plugin:** template-based generation can produce DOCX as well as PDF, set with `outputFormat`. See [Generating DOCX output](/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output).
* **Knowledge Base:** a failed ingestion shows its status and reason, and **Retry** re-runs the last operation after cleaning up partial content. The Update Knowledge Base node gains a FAIL exit with per-operation rollback. See [Error handling and retry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#error-handling-and-retry).
* **File Download component:** end users download files directly from a rendered app. See [File download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download).
* **Global header and footer:** a UI Flow can define a header and footer shown on every page. See [Global header and footer](/6.x/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer).
* **Event handlers:** event handlers can fire on a condition. The **Save Local Variable** action saves the clicked collection row into local data under a key. See [Conditional triggers](/6.x/docs/building-blocks/ui-designer/event-handlers#conditional-triggers) and [Save Local Variable](/6.x/docs/building-blocks/ui-designer/event-handlers#save-local-variable).
* **Image component:** the Image component honors a color property. See [Image](/6.x/docs/building-blocks/ui-designer/ui-component-types/image).
* **Data source testing:** the database query testing modals have a **Documents** tab, and multi-record operations report an affected-record count. See [Testing data sources](/6.x/docs/platform-deep-dive/integrations/testing-data-sources).
* **Mistral provider:** add Mistral with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability. See [AI providers](/6.x/ai-platform/ai-providers).

#### Changed

* **Documents:** the **Document Type** field is renamed **Document Tag**. Behavior is unchanged.

[5.10.0 release notes](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026) · [5.10.0 deployment guidelines](/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10)


# Deployment guidelines v6.0.0
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0

Component versions, Kafka topics, environment variables, and Helm chart changes for FlowX.AI 6.0.0, with the steps a self-hosted upgrade needs.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 6.0 is a feature release. On SaaS, FlowX applies every change on this page. Self-hosted deployments usually follow LTS releases and receive these changes with the next LTS release family. If you upgrade a self-hosted installation to 6.0.0, apply the changes below in the order given in [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

### Before you upgrade a self-hosted installation

* Set every AI service group flag explicitly. See [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart).
* Deploy designer-user, the new `core` service. harness and ui-driver (`devtime`) and dynamic-classifier (`runtime`) deploy only if you turn their group on. See [New services](#new-services).
* Create the new database users and secrets for the services you deploy. Every installation needs the four new keys in `keycloak-flowx-realm-clients`. See [New databases and secrets](#new-databases-and-secrets).
* Give process-engine read access to the integration-designer bucket. See [New databases and secrets](#new-databases-and-secrets).
* If you turn on dynamic-classifier, set its bucket name and provide its 20Gi volume. See [Update your values](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart#update-your-values).
* If you route with Kubernetes Ingress, move callers off the admin Ingress routes that the chart no longer creates. See [New databases and secrets](#new-databases-and-secrets).
* Create the new Kafka topics. If your cluster uses ACLs, also give the new clients of three existing topics access. See [New Kafka topics](#new-kafka-topics).
* Let audit-core reach Redis. It now uses Redis only to choose which replica runs its nightly cleanup job, not as a cache, and the chart connects it to the same Redis server as the other services. If you restrict which services can reach Redis, add audit-core. See [Configuring Redis](/6.x/setup-guides/audit-setup-guide#configuring-redis).
* Set the personal-data encryption master key on integration-designer. See [Personal-data encryption master key](#new-required-secret-personal-data-encryption-master-key).
* Choose how Elasticsearch replicates new indices. See [Elasticsearch replica auto-expansion](#changed-default-elasticsearch-replica-auto-expansion).
* Add the MongoDB hosts on your private network that data sources use to `FLOWX_SSRFALLOWEDHOSTS`. See [nosql-db-runner host restrictions](#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).
* Trust the certificates of the IMAP servers your email triggers read from. See [IMAPS certificate verification](#changed-default-imaps-certificate-verification-in-email-gateway).

Upgrading from 5.9.5 or earlier? Two changes from 5.9.6 also apply. See [Upgrading from an older patch release](#upgrading-from-an-older-patch-release).

## Component versions

The versions below are the component versions that make up FlowX.AI 6.0.0, next to FlowX.AI 5.9.6, the latest 5.9.x release a self-hosted installation upgrades from. A dash marks a component that is new since 5.9.6. On SaaS, FlowX manages these versions.

### Core components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **admin** | 11.132.0 | 10.152.14 |
| **advancing-controller** | 11.86.0 | 10.98.12 |
| **application-manager** | 11.143.0 | 10.159.3 |
| **audit-core** | 11.92.0 | 10.102.11 |
| **authorization-system** | 11.102.0 | 10.122.13 |
| **cms-core** | 11.114.0 | 10.113.13 |
| **data-search** | 11.87.0 | 10.92.11 |
| **data-sync** | 11.94.0 | 10.107.13 |
| **designer** | 11.252.0 | 10.285.4 |
| **designer-user** | 11.31.0 | - |
| **document-plugin** | 11.122.0 | 10.124.13 |
| **email-gateway** | 11.110.0 | 10.102.1 |
| **events-gateway** | 11.93.0 | 10.101.1 |
| **file-gateway** | 11.105.0 | 10.33.14 |
| **integration-designer** | 11.158.0 | 10.201.2 |
| **license** | 11.94.0 | 10.87.12 |
| **nosql-db-runner** | 11.98.0 | 10.101.13 |
| **notification-plugin** | 11.113.0 | 10.111.1 |
| **organization-manager** | 11.101.0 | 10.98.12 |
| **process-engine** | 11.137.1 | 10.174.17 |
| **runtime-manager** | 11.143.0 | 10.159.3 |
| **scheduler-core** | 11.89.0 | 10.94.11 |
| **task-management-plugin** | 11.109.0 | 10.112.12 |
| **webhook-gateway** | 11.102.0 | 10.69.12 |

### AI base components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-gateway** | 11.118.1 | 10.35.13 |
| **embedder** | 11.7.0 | 10.11.2 |
| **knowledgebase-indexer-v2** | 11.7.0 | 10.11.2 |
| **knowledgebase-rag** | 11.7.0 | 10.11.2 |
| **doc-parser** | 11.7.0 | 10.11.2 |

### AI dev-time components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-analyst** | 11.7.0 | 10.11.2 |
| **ai-architect** | 11.7.0 | 10.11.2 |
| **ai-assistant** | 11.7.0 | 10.11.2 |
| **ai-designer** | 11.7.0 | 10.11.2 |
| **ai-developer** | 11.7.0 | 10.11.2 |
| **harness** | 11.7.0 | - |
| **kb-enrichment** | 11.7.0 | 10.11.2 |
| **planner** | 11.7.0 | 10.11.2 |
| **ui-driver** | 11.252.0 | - |

### AI runtime components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **agent-builder** | 11.7.0 | 10.11.2 |
| **cee-pii** | 11.7.0 | - |
| **data-privacy** | 11.7.0 | 10.11.2 |
| **doc-converter** | 11.7.0 | 10.11.2 |
| **dynamic-classifier** | 11.7.0 | - |
| **evals-judge** | 11.7.0 | 10.11.2 |
| **speech-to-text** | 11.7.0 | 10.11.2 |
| **web-crawler** | 11.7.0 | 10.11.2 |

### AI extensions

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **modpod** | 11.0.1 | 10.0.7 |
| **observatory-api** | 11.29.4 | 10.7.2 |
| **observatory-platform** | 11.29.4 | 10.7.2 |
| **observatory-web** | 11.29.4 | 10.7.2 |

In FlowX.AI 6.0, the Observatory components run on environments operated by FlowX. They aren't included in client deployments in this release.

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart and deployed with the AI base group (see [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart)). Its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/6.x/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.252.0` for FlowX.AI 6.0.0). The native iOS and Android renderers version independently.

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **@flowx/angular-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/angular-theme** | 11.252.0 | 10.285.4 |
| **@flowx/angular-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/core-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/core-theme** | 11.252.0 | 10.285.4 |
| **solution-portal** | 11.252.0 | 10.285.4 |
| **iOS renderer** | 11.6.0 | 10.9.2 |
| **Android renderer** | 11.18.0 | 10.10.2 |

The **solution-portal** container app tracks the designer version.

***

## Configuration changes

This section compares environment variables, Kafka topics, and the `flowx-ai` Helm chart with FlowX.AI 5.9.6. It includes the changes that reached SaaS in 5.10 to 5.13, so a self-hosted upgrade from 5.9.6 needs only this page.

### New Kafka topics

Compared with 5.9.6, create these 42 topics. Create all of them, whatever your group flags: topics for services you don't deploy stay unused. On SaaS they are created and managed automatically.

**AI nodes as durable jobs:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.agent-node.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.progress.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.cancel.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Deep research node:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Validation findings:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.application-version.validation-findings.request-admin.v1` | application-manager → admin |
| `ai.flowx.application-version.validation-findings.request-cms.v1` | application-manager → cms-core |
| `ai.flowx.application-version.validation-findings.request-document-plugin.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.validation-findings.request-integration.v1` | application-manager → integration-designer |
| `ai.flowx.application-version.validation-findings.request-notification-plugin.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.validation-findings.request-application-manager.v1` | application-manager → application-manager |
| `ai.flowx.application-version.validation-findings.response.v1` | admin, cms-core, document-plugin, integration-designer, notification-plugin → application-manager |
| `ai.flowx.application-version.validation-findings.job-completed.v1` | application-manager → harness |

**Structured template data model:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |

**Runtime content import and export:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → embedder |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | embedder → integration-designer |

**Document classification and extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → none (dead-letter topic) |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | doc-parser → integration-designer |

**Event-triggered workflows:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Workflow schedules:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.workflow-schedules.updates.in.v1` | integration-designer → runtime-manager |
| `ai.flowx.core.notify.timer-event-schedule.state.v1` | scheduler-core → runtime-manager |

**Bulk instance migration and move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

**Designer notifications and preferences:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |
| `ai.flowx.eventsgateway.user.notifications.v1` | designer-user → events-gateway |
| `ai.flowx.designer-user.user-preferences.v1` | designer-user → designer-user |

> [!NOTE]
>
> If your Kafka cluster uses ACLs, also give the new clients of these existing topics access:
>
> * `ai.flowx.application-version.sync.out.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.correction-after-app-operation.response.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1`: document-plugin

### New services

Compared with 5.9.6, the `flowx-ai` Helm chart adds four services. On SaaS they are provisioned and managed by FlowX.

| Service | Group | What it does | Dependencies |
| - | - | - | - |
| designer-user | `core` | Stores Designer user preferences, such as the last-used workspace, and delivers Designer notifications | MongoDB, Redis, Kafka |
| harness | `devtime` | Runs the Developer Agentic Harness | PostgreSQL, Redis, Kafka |
| ui-driver | `devtime` | Renders UI flows in the background for the Developer Agentic Harness | None |
| dynamic-classifier | `runtime` | Classifies documents with trained models | PostgreSQL, a persistent volume, Kafka |

The databases, secrets, and volume are in [New databases and secrets](#new-databases-and-secrets).

The harness reuses the platform's existing Redis, so nothing new is provisioned. It uses Redis to stream a running turn to every open Designer session and to cancel a turn from any harness pod. Without Redis, turns still run, but live progress and cancellation across pods don't work.

The harness also consumes the existing `ai.flowx.llm.config.changed.v1` topic, so a change to an organization's AI model settings reaches it right away. Without Kafka, it picks up the change when its cache expires.

### AI service groups in the Helm chart

The `flowx-ai` Helm chart groups the services into four groups. Each group has its own flag, `groups.<group>.enabled`:

| Group | Services |
| - | - |
| `core` | Core platform services |
| `base` | The AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and the bundled Qdrant |
| `devtime` | ai-analyst, ai-architect, ai-assistant, ai-designer, ai-developer, harness, kb-enrichment, planner, ui-driver |
| `runtime` | agent-builder, data-privacy, doc-converter, dynamic-classifier, evals-judge, speech-to-text, web-crawler. cee-pii is in this group but needs `services.cee-pii.enabled: true` as well |

The groups are the same as in 5.9.6. The 6.0.0 chart adds designer-user to `core`, harness and ui-driver to `devtime`, and cee-pii and dynamic-classifier to `runtime`. The `base` group is unchanged.

Set all four flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

> [!WARNING]
>
> **Set every group flag explicitly for self-hosted upgrades.** Don't rely on the chart's group defaults. The `devtime` and `runtime` services call the AI base services, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

### New databases and secrets

Compared with the `flowx-ai` Helm chart in 5.9.6, these services need new databases. Create a database only if its service's group is on. designer-user is in `core`, so every installation needs its database:

| Service | Group | Database user | Secret |
| - | - | - | - |
| agent-builder | `runtime` | PostgreSQL `agent_builder` | `flowx-postgres-agent-builder` |
| dynamic-classifier | `runtime` | PostgreSQL `dynamic_classifier` | `flowx-postgres-dynamic-classifier` |
| harness | `devtime` | PostgreSQL `harness` | `flowx-postgres-harness` |
| designer-user | `core` | MongoDB `designer-user` | `mongodb-designer-user-designer-user` |

Each database has the same name as its user. Each secret holds the user's password under the key `password`.

The webhook-gateway also connects to the existing `app-runtime` MongoDB database with the `app-runtime` user.

The `keycloak-flowx-realm-clients` secret needs four new keys, one for each new service account:

| Secret key | Keycloak client |
| - | - |
| `KEYCLOAK_DESIGNER_USER_CLIENT_SECRET` | `flowx-designer-user-sa` |
| `KEYCLOAK_AI_HARNESS_CLIENT_SECRET` | `flowx-ai-harness-sa` |
| `KEYCLOAK_NOTIFICATION_PLUGIN_CLIENT_SECRET` | `flowx-notification-plugin-sa` |
| `KEYCLOAK_DOCUMENT_PLUGIN_CLIENT_SECRET` | `flowx-document-plugin-sa` |

Other chart changes:

* **process-engine** needs read-only access (`s3:GetObject`) to the integration-designer bucket, to download the Kafka payloads that integration-designer stores there. The chart reads the access key ID from `global.flowx.s3.credentials.processEngine.accessKey` (default `flowx-process-engine-accesskey`) and the secret access key from the `flowx-process-engine-s3` secret, key `SecretAccessKey`.
* **dynamic-classifier** stores its data on a 20Gi `ReadWriteOnce` persistent volume claim, `dynamic-classifier-data`, and uses the `Recreate` deployment strategy, so an upgrade stops the old pod before the new one starts.
* **dynamic-classifier** reads an OpenAI API key for its LLM judge from the `dynamic-classifier-openai` secret, key `OPENAI_API_KEY`. The secret is optional: without it, the pod still starts and classification keeps working.
* The chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier. ai-gateway keeps its own.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map | none (required) |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today | `k1` |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index | `PT24H` |

### New object storage bucket: runtime content

Runtime content export and import stores its files in a new shared bucket, `runtime-content-bucket`. Application Manager creates the bucket on first use, Integration Designer writes export files and reads imports there, and the embedder reads and writes Knowledge Base vectors at the paths each request names. Grant all three services access to the bucket.

Browsers upload import files and download export files directly, through presigned URLs that Application Manager signs. By default it signs them with the internal storage endpoint, which only pods can reach, so set `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` to a storage endpoint that browsers can reach.

New variables on application-manager and integration-designer. Set the bucket on both, and the presign settings on application-manager only:

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_RUNTIMECONTENTBUCKET` | Bucket for runtime content export and import files | `runtime-content-bucket` |
| `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` | Storage endpoint used to sign the presigned upload and download URLs. Leave empty to sign with the internal storage endpoint | empty |
| `APPLICATION_FILESTORAGE_S3_PRESIGNREGION` | Region used to sign the presigned URLs | `us-east-1` |

For the full list of buckets, see [Data architecture](/6.x/docs/platform-overview/data-architecture#s3-compatible-object-storage-buckets).

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

New process-engine and audit-core variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

### Changed behavior: nosql-db-runner host restrictions cover MongoDB

The host restriction that relational data sources already had now applies to external MongoDB connections too. The nosql-db-runner checks every address a MongoDB host resolves to, including replica-set members and SRV targets, and rejects the connection if any of them is private. For FlowX Database and Unmanaged MongoDB data sources alike, it also rejects `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter. To match every document, pass `{"_id": {"$exists": true}}`.

nosql-db-runner variables (both already existed for relational data sources):

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SSRFALLOWEDHOSTS` | Hosts or CIDR blocks, separated by commas, that may connect even though they resolve to a private address. Addresses on the local machine or in a link-local range stay blocked | empty |
| `FLOWX_SSRFPROTECTIONENABLED` | Turns the host restriction on or off | `true` |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS`.

### Changed behavior: name placeholders in data-privacy

When data-privacy masks a person's name, the placeholder now carries the gender, for example `<NAME_F_1>` or `<NAME_M_1>`. When the name doesn't show the gender, the placeholder stays `<NAME_1>`. Prompts or scripts that match the old placeholder form need updating.

### Changed behavior: Workspace operations editor role replaced

The upgrade replaces the Workspace operations editor role with the [Workspace corrective actions editor](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix) role. Users and groups that had the old role get the new one automatically and keep access to process instance migration and move token. No action is needed.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

New audit-core variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/6.x/setup-guides/audit-setup-guide#configuring-elasticsearch).

### Changed default: IMAPS certificate verification in email-gateway

The email-gateway now verifies the certificate of every IMAPS server it connects to. A server must present a certificate signed by a trusted authority and matching its host name.

New email-gateway variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS` | Mail hosts that skip certificate verification, separated by spaces or commas. Use `*` to skip it for every host | empty |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Email triggers that read from an IMAP server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`.

### Changed default: AI node retry

AI nodes without retry settings of their own now retry when a dependency is temporarily unavailable, such as an LLM provider outage, a rate limit, or a lost connection. Permanent errors aren't retried, and deep research nodes never retry by default. A node's own retry settings replace the default.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_ENABLED` | Turns the default retry for AI nodes on or off | `true` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_MAXATTEMPTS` | Maximum retry attempts | `10` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_BACKOFFPERIOD` | Wait between attempts, as an ISO-8601 duration | `PT30S` |

### Upgrading from an older patch release

Upgrading from 5.9.5 or earlier? Apply the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries) as well. Two 5.9.6 changes affect the upgrade:

* **Build redeployment retries:** the queue of build deployments waiting for a retry moved from Redis to the application-manager PostgreSQL database, with a new topic, `ai.flowx.build.deployment-failed.v1`. Deployments waiting for a retry in Redis when you upgrade aren't moved to the new queue. Re-publish those builds after the upgrade.
* **advancing-controller management port:** `MANAGEMENT_SECURITY_ENABLED` is no longer read. Actuator endpoints on the management port, including Prometheus, answer without authentication.

> [!WARNING]
>
> Keep the advancing-controller management port, `8081`, off any public ingress.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](/release-notes/overview).


# Android SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/android

Migrate the FlowX Android renderer SDK from 5.9.x to 6.0.0.

## Android SDK migration guide

FlowX.AI 6.0 moves the Android SDK to `compileSdk` 37, Android Gradle plugin 9 and Kotlin 2.4, and aligns the SDK's names with the iOS and web SDKs. Update your build setup first, then the renamed SDK APIs.

### System requirements

* **minSdk = 26** (unchanged)
* **compileSdk = 37**

The SDK library was built using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 9.5.0**
* **[Gradle](https://gradle.org/releases/) 9.8.2**
* **[Kotlin](https://kotlinlang.org/) 2.4.21**

Your container app must build with at least:

* **Android Gradle Plugin 9.1.0**
* **Gradle 9.3.1** (the minimum depends on your Android Gradle Plugin version)
* **Kotlin 2.4**
* **JDK 17**

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Android Core KTX](https://developer.android.com/kotlin/ktx#core) | 1.16.0 | **1.19.1** |
| [Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) | 1.10.1 | **1.13.0** |
| [Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) | 2025.09.01 | **2026.09.00** |
| [Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) | 2.9.1 | **2.10.2** |
| [Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) | 2.9.1 | **2.11.0** |
| [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | 1.10.2 | **1.11.0** |
| [Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) | 1.1.7 | **1.3.0** |
| [Android Security](https://developer.android.com/jetpack/androidx/releases/security) | 1.1.0-beta01 | **1.1.0** |
| [OkHttp BOM](https://square.github.io/okhttp/) | 4.12.0 | **5.5.1** |
| [Retrofit](https://square.github.io/retrofit/) | 2.12.0 | **3.0.0** |
| [Coil BOM](https://coil-kt.github.io/coil/) | 3.4.0 | **3.6.3** |
| [Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) | 4.31.1 | **4.36.2** |
| [Mozilla Rhino](https://github.com/mozilla/rhino) | 1.8.0 | **1.9.2** |
| [Accompanist Permissions](https://google.github.io/accompanist/permissions/) | 0.37.3 | 0.37.3 |
| [Moshi](https://github.com/square/moshi) | 1.15.2 | 1.15.2 |
| [Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) | 2.1.5 | 2.1.5 |

> [!WARNING]
>
> The SDK now depends on **OkHttp 5** and **Retrofit 3**. Gradle resolves your app to these versions even if you declare OkHttp 4 or Retrofit 2, so update any code in your app that uses APIs removed in these major versions. Align your app's versions of these libraries with the SDK's versions to avoid compatibility issues.

### Migration steps

To build and run your container app with the 6.0 SDK, follow these steps in order:

**1. Update the SDK version**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
implementation("ai.flowx.android:sdk:<5.9.x version>") // [!code --]
implementation("ai.flowx.android:sdk:<6.0 version>") // [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Increase the `compileSdk` version to `37`**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileSdk = 35 // [!code --]
    compileSdk = 37 // [!code ++]
}
```

> [!NOTE]
>
> The SDK and its AndroidX, OkHttp and Coil dependencies require `compileSdk` 37. Raising `targetSdk` is not required.

**3. Update the `Android Gradle plugin` version to at least `9.1.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "8.10.0" apply false // [!code --]
    id("com.android.application") version "9.5.0" apply false // [!code ++]
}
```

> [!TIP]
>
> Android Gradle plugin 9 is a major release with breaking build changes. Consult the [Android Gradle plugin 9.0 release notes](https://developer.android.com/build/releases/agp-9-0-0-release-notes).

**4. Update the `Gradle` version**

```properties [rootProject]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.2-bin.zip # [!code ++]
```

> [!NOTE]
>
> Android Gradle plugin 9.1 requires at least Gradle 9.3.1, and 9.5 requires at least Gradle 9.6.0. Check the minimum for your version in the [Android Gradle plugin release notes](https://developer.android.com/build/releases/gradle-plugin).

**5. Remove the `Kotlin Android` plugin**

Android Gradle plugin 9 compiles Kotlin by itself (built-in Kotlin), so the `org.jetbrains.kotlin.android` plugin must be removed:

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code --]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") // [!code --]
}
```

> [!TIP]
>
> Consult the [Migrate to built-in Kotlin](https://developer.android.com/build/migrate-to-built-in-kotlin) guide.

**6. Update the `Kotlin` version to at least `2.4`**

With built-in Kotlin, your app compiles with the version of the Kotlin Gradle plugins you declare, such as the Compose Compiler plugin. The Kotlin version that Android Gradle plugin uses by default is too old to read the SDK's classes. Use the same version for every Kotlin Gradle plugin your project declares, such as Parcelize or Serialization.

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code --]
    id("org.jetbrains.kotlin.plugin.compose") version "2.4.21" apply false // [!code ++]
}
```

> [!WARNING]
>
> With an older Kotlin version, the build fails with an error like: `The binary version of its metadata is 2.4.0, expected version is 2.2.0`.

**7. Make sure core library desugaring is enabled**

The SDK requires core library desugaring. If your app does not enable it yet, add:

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**8. Rename the `imageBaseUrl` and `customHeaders` properties of the `Config` interface**

`imageBaseUrl` is now `assetsBaseUrl`, and `customHeaders` is now `additionalHttpHeaders`:

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
Flowx.getInstance().init(
    context = applicationContext,
    config = object : Config {
        ...
        override val imageBaseUrl = "URL to FlowX CMS Media Library" // [!code --]
        override val assetsBaseUrl = "URL to FlowX CMS Media Library" // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code --]
        override val additionalHttpHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code ++]
        ...
    },
    ...
)
```

> [!NOTE]
>
> The default value of the `locale` property changed from `Locale.getDefault()` to `Locale.forLanguageTag("en-US")`. If your app relies on the device locale for date, number and currency formatting, set it explicitly:
>
> ```kotlin theme={"dark"}
> override val locale: Locale = Locale.getDefault()
> ```

**9. Stop passing `null` to the `setAccessToken` method**

The `setAccessToken` method no longer accepts `null`:

```kotlin theme={"dark"}
fun setAccessToken(accessToken: String?) // [!code --]
fun setAccessToken(accessToken: String) // [!code ++]
```

Remove the calls that clear the token (for example, on logout or after a failed login):

```kotlin theme={"dark"}
Flowx.getInstance().setAccessToken(null) // [!code --]
```

A token can't be cleared once set. When another user logs in, set that user's token. If no token is ever set, the SDK runs in anonymous mode. For details, see the [Authentication](/6.x/sdks/android-renderer#authentication) section of the Android SDK reference.
\[!WARNING] Passing an empty string (`""`) no longer clears the token. The SDK sends it as is and the backend rejects the requests.

**10. Rename the `closeModalFunc` parameter to `onDismissRequested`**

The parameter of the `startProcess` and `continueProcess` methods was renamed. Its lambda now runs in the `ProjectScope` context:

```kotlin theme={"dark"}
Flowx.getInstance().startProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)

Flowx.getInstance().continueProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)
```

> [!TIP]
>
> Replace the deprecated `CloseModalProcessScope` type with `ProjectScope`, as described in the [Replace deprecated APIs](#replace-deprecated-apis) section.

**11. Rename the `imageBaseUrl` parameter of the `changeEnvironment` method (if used)**

```kotlin theme={"dark"}
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code --]
fun changeEnvironment(baseUrl: String, assetsBaseUrl: String, enginePath: String) // [!code ++]
```

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. The parameters are unchanged:

| Deprecated (5.9) | Replacement (6.0) | Available on |
| - | - | - |
| `CloseModalProcessScope` | `ProjectScope` | The `onDismissRequested` lambda of `startProcess` and `continueProcess` |
| `replaceSubstitutionTag` | `getSubstitutionTagContent` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getMediaResourceUrl` | `getMediaItemUrl` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getEnumeration` | `getEnumerationItems` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `executeAction` | `runAction` | `CustomComponentScope` |
| `executeUploadAction` | `runUploadAction` | `CustomComponentScope` |
| `configureUpdateState` | `setUpdateStateEnabled` | `Flowx` |

> [!TIP]
>
> Android Studio offers a **Replace with** quick fix on every deprecated call.

These changes are reflected in an actual implementation as shown below:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope // [!code --]
import ai.flowx.android.sdk.api.ProjectScope // [!code ++]

// close process confirmation alert
@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code --]
private fun ProjectScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code ++]
    ...
    Text(replaceSubstitutionTag("@@close_message")) // [!code --]
    Text(getSubstitutionTagContent("@@close_message")) // [!code ++]
}

// custom component
flowxScope.executeAction(action = it, params = JSONObject()) // [!code --]
flowxScope.runAction(action = it, params = JSONObject()) // [!code ++]

// custom loader
flowxScope.replaceSubstitutionTag(text) // [!code --]
flowxScope.getSubstitutionTagContent(text) // [!code ++]
flowxScope.getMediaResourceUrl(key) // [!code --]
flowxScope.getMediaItemUrl(key) // [!code ++]
```

## Related resources

> [card] [Android SDK reference](/6.x/sdks/android-renderer)
>
> Android renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Angular SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/angular

Migrate the FlowX Angular renderer SDK from 5.9.x to 6.0.0.

## Angular SDK migration guide

6.0 moves the Angular renderer to Angular 22 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new input and function names. The framework upgrade, the custom component input, and the removed `logSink` and `logCategories` inputs need code changes.

### Framework upgrade: Angular 21 → 22

Upgrade your host app **before** you bump the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide) from `21.0` to `22.0`.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Angular CLI and `@angular/*` | \~21 | **\~22** |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |
| TypeScript | ≥ 5.9, \< 6.1 | **≥ 6.0, \< 6.1** |

The FlowX Angular packages declare `@angular/*` ≥ 22.0.0 as peer dependencies, so `npm install` fails on an Angular 21 app.

### FlowX SDK changes

#### Renamed inputs and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` input | `baseUrl` |
| `processApiPath` input | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` input | `assetsBaseUrl` |
| `authToken` input | `accessToken` |
| `withConfig({ customLoader })` | `customLoaderProvider` (same shape) |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers.

```diff theme={"dark"}
 <flx-process-renderer
-  [apiUrl]="baseUrl"
-  [processApiPath]="'onboarding'"
-  [staticAssetsPath]="mediaLibraryUrl"
-  [authToken]="token"
+  [baseUrl]="baseUrl"
+  [enginePath]="'onboarding'"
+  [assetsBaseUrl]="mediaLibraryUrl"
+  [accessToken]="token"
   ...
 />
```

#### Custom components: `data$` → `input` signal

Custom components receive their data through an `input` signal input instead of the `data$` Observable. The process data moves under `input().data`, and actions run through `runAction` and the new `runUploadAction`. Both return an Observable.

| 5.9 | 6.0 |
| - | - |
| `data$` input (Observable) | `input` signal input |
| Data fields read from the top level (`data.<field>`) | `input().data.<field>` |
| `data.actionsFn.<name>(params)` | `input().runAction(name, params?)` |
| None | `input().runUploadAction(name, file, params?)` |

```typescript theme={"dark"}
import { Component, computed, input } from '@angular/core';
import { FlxCustomComponentData } from '@flowx/angular-sdk';

@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
})
export class CustomComponentComponent {
  input = input<FlxCustomComponentData>()
  client = computed(() => this.input()?.data.client)

  submit(file: Blob) {
    this.input()?.runAction('action_one', { amount: 3 }).subscribe();
    this.input()?.runUploadAction('upload_document', file, { side: 'front' }).subscribe();
  }
}
```

#### `logSink` and `logCategories` inputs removed

The `[logSink]` and `[logCategories]` inputs on `<flx-process-renderer>` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- [logSink]="formattedLogger"
- [logCategories]="['rest', 'sse']"
```

```typescript theme={"dark"}
import { formattedLogger, logSink } from '@flowx/core-sdk';

const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] });
```

`@flowx/angular-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Inputs removed or deprecated without replacement

| Input | Status in 6.0 |
| - | - |
| `legacyHttpVersion` | Deprecated, no replacement. Still honored. |
| `debugLogs` | Removed. It never had any effect. Use `logSink()` from `@flowx/core-sdk`. |

#### Behavior changes

* `baseUrl` is required on the process, UI Flow, chat and task management renderers, and `assetsBaseUrl` on the process, UI Flow and chat renderers. Without them, the renderer throws ``[FlowX] `baseUrl` is required.`` (or `` `assetsBaseUrl` ``) at start. The template compiler doesn't report a missing value.
* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [Angular SDK reference](/6.x/sdks/angular-renderer)
>
> Angular renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Helm chart
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart

Upgrade a FlowX.AI installation on the flowx-ai Helm chart from 5.9.x to 6.0.0.

> [!NOTE]
>
> FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

This page covers the Helm side of an upgrade from FlowX.AI 5.9.x to 6.0.0 for an installation that already runs on the `flowx-ai` Helm chart. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list every change in detail. This page puts the ones that need action in the order you do them.

> [!NOTE]
>
> If you still run the per-service charts or the `ai-platform` umbrella chart, move to the `flowx-ai` chart on 5.9.x first, as described in [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart). That migration recreates every workload. Doing it separately keeps the 6.0.0 upgrade a single `helm upgrade` of one release.

## Before you begin

* Read the [FlowX.AI 6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) and [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0).
* Get pull access to the `flowx-ai` chart at the chart version for 6.0.0. The chart version is the platform release.
* Take a backup of PostgreSQL, MongoDB, the object store, and the Qdrant collections right before the upgrade.
* If you run a container app with a FlowX renderer SDK, plan its upgrade with the [renderer SDK guides](./migration-overview#renderer-sdk-migration).

The commands on this page read the namespace from `NS`:

```bash theme={"dark"}
export NS={your-flowx-namespace}
```

## Update your values

**1. Set every group flag explicitly**

Don't rely on the chart's group defaults. Set all four group flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

`base` is the AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and Qdrant. The `devtime` and `runtime` services call it, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

For example, to install the core, base, and runtime services:

```yaml theme={"dark"}
groups:
  core:
    enabled: true
  base:
    enabled: true
  devtime:
    enabled: false
  runtime:
    enabled: true
```

See [AI service groups in the Helm chart](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#ai-service-groups-in-the-helm-chart) for the services in each group, and [How do the switches combine?](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#how-do-the-switches-combine) for how group and service flags combine.

**2. Provision databases and secrets for the services you turn on**

In 6.0.0, these services need their own database users and secrets: agent-builder, dynamic-classifier, and harness in PostgreSQL, and designer-user in MongoDB. Create them before the upgrade for every service your group flags turn on. designer-user is in the `core` group, so it always needs its database.

The `keycloak-flowx-realm-clients` secret needs four new client secret keys, whatever your group flags. authorization-system reads all four at startup and, when it has Keycloak admin access (the default), creates the matching service-account clients with those secrets. If a key is missing, its database migration fails and authorization-system doesn't start. Without Keycloak admin access, create the four clients in Keycloak yourself.

See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the user, secret, key, and client names.

**3. Grant process-engine read access to the integration-designer bucket**

process-engine now reads Kafka payloads that integration-designer stores in its bucket. Give the process-engine credentials `s3:GetObject` on that bucket. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the secret names.

**4. Set a bucket name for dynamic-classifier**

If you turn on dynamic-classifier, set its bucket under `services.dynamic-classifier.component.s3.applicationFileStorage.bucketName`. The chart sets no bucket names, as described in [Migrate S3 buckets](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#migrate-s3-buckets). dynamic-classifier also stores data on a 20Gi `ReadWriteOnce` volume, so your cluster needs a storage class that can provide one.

Unlike the Qdrant volumes, this claim is part of the Helm release. `helm uninstall`, or deleting the Argo CD Application with cascading deletion, deletes it, and with a `Delete` reclaim policy its data too.

**5. Move callers off the removed admin Ingress routes**

If you route with Kubernetes Ingress, the chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier, and the upgrade deletes the existing ones. ai-gateway keeps its own. Platform services and frontends don't use these routes. If anything outside the cluster calls one of these paths on the admin host, such as `/speech-to-text`, move it to the service's in-cluster address before you upgrade.

Installations that use the Gateway API aren't affected.

**6. Allow private MongoDB hosts**

nosql-db-runner now applies its host restriction to external MongoDB connections. Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS` on nosql-db-runner. See [nosql-db-runner host restrictions](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).

**7. Trust your IMAP servers' certificates**

email-gateway now verifies the certificate of every IMAPS server it connects to. Email triggers that read from a server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`. See [IMAPS certificate verification](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway).

**8. Keep the management port private**

Upgrading from 5.9.5 or earlier? Since 5.9.6, advancing-controller no longer reads `MANAGEMENT_SECURITY_ENABLED`, and the actuator endpoints on its management port, `8081`, including Prometheus, answer without authentication. Check that no public Ingress or Gateway route exposes that port. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).

**9. Set the personal-data encryption key**

In 6.0.0, integration-designer needs `FLOWX_PII_ENCRYPTION_MASTER_KEY` for the Mask Personal Data and Restore Personal Data nodes. The variable has no default and the chart doesn't set it, so without it those nodes fail when a workflow runs them. Store a strong random value in a secret under the key `FLOWX_PII_ENCRYPTION_MASTER_KEY`, and load the secret into integration-designer:

```yaml theme={"dark"}
services:
  integration-designer:
    extraEnvVarsSecret: {your-pii-secret-name}
```

Keep the value identical on every pod and stable over time: changing it invalidates every in-flight placeholder map. See [Personal-data encryption master key](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-required-secret-personal-data-encryption-master-key).

**10. Choose how Elasticsearch replicates new indices**

In 6.0.0, process-engine and audit-core create new indices with the Elasticsearch `auto_expand_replicas` setting `0-1`, which overrides `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS`. On a cluster with two or more data nodes, the replica roughly doubles the disk space these indices use. To keep a fixed replica count instead, turn auto-expansion off on both services:

```yaml theme={"dark"}
services:
  process-engine:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
  audit-core:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
```

See [Elasticsearch replica auto-expansion](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-elasticsearch-replica-auto-expansion).

**11. Create the new Kafka topics**

New capabilities since 5.9.x depend on new Kafka topics. Create them before you upgrade. The 6.0.0 [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics) list every topic added since 5.9.6. Upgrading from 5.9.5 or earlier? Also create `ai.flowx.build.deployment-failed.v1`, added in 5.9.6. If your cluster uses ACLs, also give the new clients of three existing topics access, as listed in the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics).

If the chart creates your topics, add the new names to the list under `global.flowx.kafka.topics.topics`. The chart creates topics only when `global.flowx.kafka.topics.enabled` is `true`, as Strimzi `KafkaTopic` resources with 3 partitions and 3 replicas unless you set other values under `global.flowx.kafka.topics.defaults`:

```yaml theme={"dark"}
global:
  flowx:
    kafka:
      topics:
        enabled: true
        topics:
          - ai.flowx.build.deployment-failed.v1
```

## Render and compare

Render the 6.0.0 chart with your updated values before you upgrade, and compare it with what runs today:

```bash theme={"dark"}
helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml
```

Check that the rendered Deployments are the services you expect. A missing AI base service, or an AI runtime service you didn't plan for, means a group flag isn't set. The render fails if your values still contain top-level `devtime` or `runtime` keys, or service keys outside `services`. See [Render and compare](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#render-and-compare) for commands that compare environment variables per Deployment.

Using a mirrored or air-gapped registry? List the images the render references, mirror them, and point the chart at your registry with `global.imageRegistry`, as described in [Container images and registry](/6.x/setup-guides/setup-guides-overview#container-images-and-registry):

```bash theme={"dark"}
grep -E '^\s+image:' rendered.yaml | sort -u
```

## Upgrade

Run `helm upgrade` on your `flowx-ai` release with the 6.0.0 chart version and your updated values:

```bash theme={"dark"}
helm upgrade {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml
```

dynamic-classifier uses the `Recreate` deployment strategy, so its old pod stops before the new one starts.

## After the upgrade

* **Upgrading from 5.9.5 or earlier: re-publish builds that were waiting for a retry.** The retry queue for failed build deployments moves from Redis to PostgreSQL, and deployments waiting in Redis are not moved. 5.9.6 already uses the PostgreSQL queue. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).
* **Check component versions.** In FlowX.AI Designer, go to **Platform Status** and compare the versions with the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#component-versions).
* **Check files from before the upgrade.** Open a process attachment, a media library asset, and a knowledge base document, and confirm they load. A bucket-not-found error in the logs points at a bucket name that didn't carry over.
* **Update name placeholders.** data-privacy now masks names with gendered placeholders, such as `<NAME_F_1>`. Update prompts or scripts that match the old form. See [Name placeholders in data-privacy](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy).
* **Expect a new workspace role name.** Users and groups with the Workspace operations editor role now have the Workspace corrective actions editor role, and keep access to process instance migration and move token. See [Workspace operations editor role replaced](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-workspace-operations-editor-role-replaced).

## Related resources

> [card] [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)
>
> Component versions and every deployment-level change in 6.0.0

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single chart


# iOS SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/ios

Migrate the FlowX iOS renderer SDK from 5.9.x to 6.0.0.

## iOS SDK migration guide

FlowX.AI 6.0 aligns the names of five iOS SDK APIs with the Android and web SDKs. The build requirements and library dependencies are unchanged, and the 5.9 names still compile, so your app builds with the 6.0 SDK after you update the pod version. Replace the deprecated names afterwards.

### System requirements

| Requirement | 5.9.x | 6.0 |
| - | - | - |
| Minimum iOS | iOS 15 | iOS 15 |
| Swift | 5.9 | 5.9 |

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Alamofire](https://github.com/Alamofire/Alamofire) | `~> 5.9.0` | `~> 5.9.0` |
| [SDWebImageSwiftUI](https://github.com/SDWebImage/SDWebImageSwiftUI) | 3.0.3 | 3.0.3 |
| [SDWebImageSVGCoder](https://github.com/SDWebImage/SDWebImageSVGCoder) | `~> 1.7.0` | `~> 1.7.0` |

### Migration steps

**1. Update the SDK version**

```ruby Podfile theme={"dark"}
pod 'FlowXRenderer', '<5.9.x version>' # [!code --]
pod 'FlowXRenderer', '<6.0 version>' # [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Replace the deprecated APIs**

Replace the 5.9 names with the 6.0 names listed in the [Replace deprecated APIs](#replace-deprecated-apis) section. The parameters, types and behavior are unchanged.

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. `imageBaseURL` is a property of `FXConfig`; the others are methods of `FlowX.sharedInstance`:

| Deprecated (5.9) | Replacement (6.0) |
| - | - |
| `imageBaseURL` | `assetsBaseURL` |
| `updateAuthorization(token:)` | `setAccessToken(token:)` |
| `getTag(withKey:)` | `getSubstitutionTagContent(key:)` |
| `getEnumeration(name:parentName:)` | `getEnumerationItems(name:parentName:)`, async and completion versions |
| `continueExistingProcess(uuid:name:…)` | `continueProcess(uuid:name:…)`, all three versions |

> [!TIP]
>
> Xcode shows a deprecation warning on every deprecated call, with a **Fix-it** that replaces it with the new name.

These changes are reflected in an actual implementation as shown below:

```swift theme={"dark"}
// configuration
FXConfig.sharedInstance.configure { config in
    config.imageBaseURL = myImageBaseURL // [!code --]
    config.assetsBaseURL = myAssetsBaseURL // [!code ++]
}

// authorization token changes
FlowX.sharedInstance.updateAuthorization(token: accessToken) // [!code --]
FlowX.sharedInstance.setAccessToken(token: accessToken) // [!code ++]

// substitution tags
FlowX.sharedInstance.getTag(withKey: "@@close_message") // [!code --]
FlowX.sharedInstance.getSubstitutionTagContent(key: "@@close_message") // [!code ++]

// enumerations
let items = await FlowX.sharedInstance.getEnumeration(name: "cities", parentName: "countries") // [!code --]
let items = await FlowX.sharedInstance.getEnumerationItems(name: "cities", parentName: "countries") // [!code ++]

// resuming a process
FlowX.sharedInstance.continueExistingProcess(uuid: uuid, // [!code --]
FlowX.sharedInstance.continueProcess(uuid: uuid, // [!code ++]
                                     name: processName,
                                     navigationController: processNavigationController,
                                     isModal: true)
```

## Related resources

> [card] [iOS SDK reference](/6.x/sdks/ios-renderer)
>
> iOS renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Overview
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview

Migration guide for upgrading container apps and the flowx-ai Helm chart from FlowX.AI 5.9.x to 6.0.0

FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

> [!WARNING]
>
> A FlowX.AI 6.0.0 renderer SDK can need a newer framework version in your container app. Check the guide for your SDK, and upgrade the host app before you bump the FlowX SDK.

## Who is affected

Teams that run a container app with a FlowX renderer SDK (Angular, React, iOS, Android, or React Native) and move it to FlowX.AI 6.0.0. See [Renderer SDK migration](#renderer-sdk-migration).

Teams that run FlowX.AI on the `flowx-ai` Helm chart and upgrade it from 5.9.x to 6.0.0. See [Helm chart upgrade](#helm-chart-upgrade).

Teams with business rules, reusable functions, or workflow scripts that still run on the GraalVM script engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

## What's changing

An upgrade to 6.0.0 touches up to three areas, depending on what you run:

* **Helm chart:** set every AI service group flag explicitly, and create databases and secrets for the new services that need them. See [Helm chart upgrade](#helm-chart-upgrade).
* **GraalVM script engine:** deprecated. Scripts on GraalVM keep running after this upgrade, now with the same time limit as the native engine, and 6.1.x is the last release family that supports the engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).
* **Renderer SDKs:** container apps upgrade the FlowX renderer SDK, and the host framework where the SDK needs it. See [Renderer SDK migration](#renderer-sdk-migration).

## Migration process

Follow these steps in order, and skip the ones for areas you don't run.

**1. Check your starting point**

Upgrade to 6.0.0 from FlowX.AI 5.9.x on the `flowx-ai` Helm chart. If you still run the per-service charts or the `ai-platform` umbrella chart, first [migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart) on 5.9.x, as a separate change.

**2. Read the release notes and deployment guidelines**

The [release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) list what changes in 6.0.0. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list the component versions, environment variables, and other configuration changes. The [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog) lists every feature change since 5.9.x, including the 5.10 to 5.13 feature releases.

**3. Prepare the infrastructure**

Create what the 6.0.0 services need before the upgrade window: new PostgreSQL and MongoDB database users and their secrets, four new keys in the `keycloak-flowx-realm-clients` secret, read access for process-engine to the integration-designer bucket, and storage for a 20Gi `ReadWriteOnce` volume if you turn on dynamic-classifier. Create the new Kafka topics, or list them for the chart to create. Also set the personal-data encryption key for integration-designer, choose how Elasticsearch replicates new indices, and allow the private MongoDB hosts and IMAP servers that existing connections use. [Before you upgrade a self-hosted installation](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#before-you-upgrade-a-self-hosted-installation) is the full checklist, and [Update your values](./helm-chart#update-your-values) walks through each item.

**4. Check GraalVM scripts and plan the move off GraalVM**

Scripts on GraalVM keep running, but from 6.0.0 they stop at the same time limit as the native engine. Before the upgrade, check the scripts that can run longer than the limit, or raise it. Then plan their move to the native engine, as described in [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

**5. Back up**

Take the backups listed in [Before you begin](./helm-chart#before-you-begin) right before the upgrade.

**6. Upgrade the Helm release**

Update your values and upgrade the release, as described in [Helm chart](./helm-chart).

**7. Upgrade your container apps**

For each container app, upgrade the host framework first if the SDK needs it, then the FlowX renderer SDK. See [Renderer SDK migration](#renderer-sdk-migration). Container apps on a 5.9.x renderer SDK keep running against a 6.0.0 backend, but screens can render incorrectly wherever 6.0.0 changed behavior. Release the upgraded apps in the same window as the Helm upgrade. For iOS and Android apps, end users who don't install the app update stay on the 5.9.x SDK, so plan how you move them to the new version.

## Helm chart upgrade

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single `flowx-ai` chart

> [card] [Helm chart](./helm-chart)
>
> Upgrade an installation on the `flowx-ai` Helm chart from 5.9.x to 6.0.0

## Move scripts off the GraalVM engine

The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine for JavaScript and Python. Scripts that run on GraalVM keep running after the upgrade to 6.0.0, but they now stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0, a GraalVM script had no time limit. Before you upgrade, check the GraalVM scripts that can run longer than these limits, or raise the limits, as described in [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits). Then plan the move to the native engine.

**1. Find the scripts that run on GraalVM**

Business rules and reusable functions created before the move to the native engine run on GraalVM unless you switched them. The engine selector in each rule's script editor shows the engine it runs on. Workflow scripts run on GraalVM only if `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`.

**2. Test each script on the native engine**

The two engines don't always write the same output. Follow the step-by-step list in [Port a script from GraalVM to native](/6.x/docs/building-blocks/supported-scripts#port-a-script-from-graalvm-to-native), check the [common pitfalls](/6.x/docs/building-blocks/supported-scripts#common-pitfalls), and search scripts for Python imports the native engine blocks, such as `os` and `subprocess`, JavaScript `require(...)`, `process`, or `global`, and calls into Java classes such as `Java.type(...)`. The native engine supports none of these.

**3. Switch to the native engine**

Switch business rules [per rule](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule). Move a reusable function and the rules that call it together: a function written for GraalVM fails when a rule on the native engine calls it. For workflow scripts, remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer`. The default is `native`.

## Renderer SDK migration

> [card] [Angular SDK](./angular)
>
> Migrate the Angular renderer SDK to 6.0.0

> [card] [React SDK](./react)
>
> Migrate the React renderer SDK to 6.0.0

> [card] [iOS SDK](./ios)
>
> Migrate the iOS renderer SDK to 6.0.0

> [card] [Android SDK](./android)
>
> Migrate the Android renderer SDK to 6.0.0

> [card] [React Native SDK](./react-native)
>
> Migrate the React Native renderer SDK to 6.0.0


# React SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react

Migrate the FlowX React renderer SDK from 5.9.x to 6.0.0.

## React SDK migration guide

6.0 moves the React renderer to Node 26 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new prop and function names. The `logSink` and `logCategories` renderer props are removed and need a code change.

### Framework requirements

React stays on 19. Upgrade Node in your build and CI environments.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| React | 19 | 19 |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |

### FlowX SDK changes

#### Renamed props and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` prop | `baseUrl` |
| `processApiPath` prop | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` prop | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customLoader` prop | `customLoaderProvider` (same shape) |
| UI Flow `appInfo.selectedProcessResourceId` | `resourceId` |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `useEnumeration(name, parentName?)` | `useEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers. `customLoaderProvider` applies to the process and UI Flow renderers.

```diff theme={"dark"}
 <FlxProcessRenderer
-  apiUrl={baseUrl}
-  processApiPath="onboarding"
-  staticAssetsPath={mediaLibraryUrl}
-  authToken={token}
+  baseUrl={baseUrl}
+  enginePath="onboarding"
+  assetsBaseUrl={mediaLibraryUrl}
+  accessToken={token}
   ...
 />
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, file, params?)` to upload a file through an upload action. `params` are sent as extra form fields beside the file.

```typescript theme={"dark"}
input.runAction('action_one', { amount: 3 })
input.runUploadAction('upload_document', file, { side: 'front' })
```

`FlxCustomComponentData` is now generic (`FlxCustomComponentData<TFile = Blob>`) and requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### `logSink` and `logCategories` props removed

The `logSink` and `logCategories` props on `FlxProcessRenderer` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- <FlxProcessRenderer logSink={formattedLogger} logCategories={['rest', 'sse']} ... />
+ import { formattedLogger, logSink } from '@flowx/core-sdk'
+
+ const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] })
```

`@flowx/react-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Props removed or deprecated without replacement

| Prop | Status in 6.0 |
| - | - |
| `legacyHttpVersion` on the process renderer | Deprecated, no replacement. Still honored. |
| `legacyHttpVersion` on the UI Flow renderer | Removed. It never had any effect. |
| `customHeaders` | Removed. It never had any effect. |
| `updateStateEnabled` | Removed. It never had any effect. |
| `isAnonymousMode` | Removed. It never had any effect. |
| `fw` | Removed. It never had any effect. |

Delete the removed props from your process and UI Flow renderer props.

#### Behavior changes

* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [React SDK reference](/6.x/sdks/react-renderer)
>
> React renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# React Native SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react-native

Migrate the FlowX React Native renderer SDK from 5.9.x to 6.0.0.

## React Native SDK migration guide

6.0 moves the validated React Native target to Expo SDK 57 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new configuration and prop names. The Android Material 3 date picker opt-in is removed.

### Prerequisites and version range

The peer dependency floors are unchanged: `react-native` ≥ 0.83.0 and `react` ≥ 19.2.0. The validated target moves up one Expo SDK.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Validated target | Expo SDK 56, React Native 0.85.3 | **Expo SDK 57, React Native 0.86.3** |
| React | 19.2.3 (Expo SDK 56 pin) | 19.2.3 (Expo SDK 57 pin) |
| `react-native-blob-util` | ^0.24.9 | **^0.25.1** |
| `@react-native-community/datetimepicker` | Required peer | **No longer used** |

For an Expo project, align the project to Expo SDK 57, then reinstall the FlowX packages with `npx expo install`:

```bash theme={"dark"}
npx expo install expo@^57.0.0 --fix
```

For the full install command and the Expo SDK 57 reference versions, see the [React Native SDK reference](/6.x/sdks/react-native-renderer).

### FlowX SDK changes

#### Renamed configuration options and props

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `FlxConfig.baseURL`, `apiUrl` prop | `baseUrl` |
| `processApiPath` | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customHeaders` | `additionalHttpHeaders` |
| `customLoader` | `customLoaderProvider` (same shape) |
| `customStepperHeader` | `customStepperHeaderProvider` (same component) |
| `configure({ locale, language })` | `FlowX.changeLocaleSettings(locale?, language?)` |
| `configure({ updateStateEnabled })` | `FlowX.setUpdateStateEnabled(enabled)` |
| `setAccessToken(token: string)` | `setAccessToken(token?: string \| null)`: `null`, `undefined` or `''` switches to anonymous access |
| `processUuid` prop | `processInstanceUuid` |
| `onClose(name?)` | `onDismissRequested(name?)` (same argument) |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl`, `enginePath` and `assetsBaseUrl` apply to `FlowX.configure` and to the process, UI Flow and chat renderers. `onDismissRequested` applies to `startProcess`, `continueProcess`, `startUiFlow` and the process and UI Flow renderers.

In 5.9 the content helpers came only from `@flowx/core-sdk/rn`. `@flowx/react-native-sdk` now exports them too, under their new names only (`getEnumerationItems`, `getMediaItemUrl`, `getSubstitutionTagContent`).

```diff theme={"dark"}
 FlowX.configure({
-  baseURL: 'https://api.example.com',
-  processApiPath: 'onboarding',
-  staticAssetsPath: 'https://media.example.com',
-  customHeaders: { 'x-tenant': 'acme' },
-  language: 'en',
-  locale: 'en-US',
+  baseUrl: 'https://api.example.com',
+  enginePath: 'onboarding',
+  assetsBaseUrl: 'https://media.example.com',
+  additionalHttpHeaders: { 'x-tenant': 'acme' },
   organizationId,
 })
+FlowX.changeLocaleSettings('en-US', 'en')
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, { uri, name, type }, params?)` to upload a file through an upload action.

`FlxCustomComponentData` requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### Android Material 3 date picker removed

The opt-in Material 3 date picker for `FlxDatePicker` on Android is removed, along with the `@react-native-community/datetimepicker` peer dependency.

* Remove `material3` from any `configureFlxUiToolkit` call.
* The `@react-native-community/datetimepicker` package is no longer needed by FlowX. Uninstall it if nothing else in your app uses it.
* Keep the `@flowx/react-native-ui-toolkit` Expo config plugin registered. It no longer changes `AppTheme` or sets `extra.flxUiToolkit.material3`. It now adds `fontScale` to the main activity's `android:configChanges` and declares the microphone permissions used by chat voice input. Run `npx expo prebuild` again after the upgrade.

#### Behavior changes

* A session with no usable access token now starts as anonymous instead of failing. In 5.9, a token that was `null`, `undefined` (never set) or an empty string (`''`) made the start throw `Call FlowX.setAccessToken(...) before starting a process.` In 6.0 all three values start an anonymous session, and a backend that requires a token answers `401`. If your token fetch can return `null`, `undefined` or `''`, check the value before you start a process; otherwise the failure only shows up later as a `401`.
* Error and warning messages name `baseUrl` and `assetsBaseUrl` instead of `baseURL` and `staticAssetsPath`. Update any host code that matches on their text.

## Related resources

> [card] [React Native SDK reference](/6.x/sdks/react-native-renderer)
>
> React Native renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# FlowX.AI 6.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026

What's new in FlowX.AI 6.0: the Developer Agentic Harness builds story by story, plus bulk process-instance migration, scheduled workflows, and certificates.

[FlowX.AI 6.0.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/hero-6.0.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 6.0 is a feature release, live on FlowX.AI SaaS. Self-hosted installations usually wait for the next LTS release family, and can also upgrade to 6.0.0 now: see [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

> [!WARNING]
>
> **Check your existing apps:** 6.0.0 changes how AI node prompts and retries, substitution tags, FlowX Database writes, masked names, IMAPS email triggers, evaluations, 5.1.x exports, and GraalVM scripts behave. See the [upgrade actions](/release-notes/v6.x/5.9-to-6.0-changelog) for what to check in each. Coming from 5.9.x? On the same page, also check the **Changed** entries for 5.10 to 5.13.

> [accordion] What changed since 5.13.0
>
> | 5.13.0 | 6.0.0 |
> | - | - |
> | The harness built the whole approved plan in one run | **Story-by-story delivery**: build one slice of the app, test it, then continue |
> | Changes to the app were described in words | **Comment mode**: select a component in the running app and say what should change |
> | The Command Center and the AI buttons in each editor opened standalone AI agents | **One agent rail**: **⌘K** or the header toggle opens the harness, which uses those agents internally |
> | A workflow started only when a process or caller started it | **Scheduled workflows**: date or cycle schedules on the Start node |
> | TLS was configured with keystores, truststores, and a skip switch | **Trust and Identity**: choose what the host is checked against, and whether to present a client certificate |
> | The Issues Console checked resources only | **Version checks**: entry points, theme, and library dependencies |
> | Only version exports sent notifications | **Import and export notifications**: version imports, build exports, and build imports notify you too |
> | A substitution tag had to be a property's whole value | **Tags inside any text**: `${tag:key}` next to static text and process data |
> | An AI node failed as soon as its AI service or provider couldn't be reached | **AI node retries**: on by default, up to 10 times, 30 seconds apart |
> | The chat message was appended to the end of an AI node's prompt | **Chat message in prompts**: reference `${userMessage}` in **Context** where the agent should answer it |
> | Evaluations grouped test cases into datasets and checked outputs with Code evaluators | **Test cases and asserts**: tagged test cases per workflow, checked with asserts and LLM evaluators |
> | The embedding model was locked once a Knowledge Base held content | **Re-embedding**: change **Containing Personal Information** later and the content is re-embedded |
> | Exporting rows to a file needed a Script node | **Generate Tabular File node**: a CSV or XLSX file from an array of rows |
> | A FlowX Database index couldn't reject duplicate values | **Unique indexes**: **Enforce unique values** on one attribute or a compound key |
> | A sensitive configuration value was shown in the Designer after saving | **Sensitive values stay hidden**: the Designer shows `********` in its place |
> | GraalVM was a supported script engine | **GraalVM deprecated**: 6.1.x is the last release family that supports it |

### **Coming from 5.9.x**

Releases 5.10 to 5.13 shipped to SaaS first. An installation that moves from 5.9.x to 6.0.0 gets their features too, including the [corrective actions](#corrective-actions-on-running-instances) below. The highlights:

> [card] New data sources
>
> [PostgreSQL](/6.x/docs/platform-deep-dive/integrations/postgresql-database) and [Db2](/6.x/docs/platform-deep-dive/integrations/db2-database) databases, and [SOAP services](/6.x/docs/platform-deep-dive/integrations/soap-system) imported from a WSDL.

> [card] Document nodes in workflows
>
> [Fill a template](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) into a PDF or DOCX, [combine](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) or [split](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) PDFs, and [parse](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support) spreadsheets, CSV, XML, and JSON.

> [card] Multi-instance and triggered workflows
>
> Run [one subworkflow per array element](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) in parallel, and start a workflow from an [email or webhook trigger](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).

> [card] Workflow Instances page
>
> [Every workflow run in the project](/6.x/docs/projects/runtime/workflow-instances), filterable by status, date, and origin.

> [card] Branches and the Issues panel
>
> [Merge into any branch](/6.x/docs/projects/managing-applications/versioning#managing-branches), archive or delete branches, and [see validation findings](/6.x/docs/projects/managing-applications/checking-for-issues) in one panel.

> [card] Workflows as agent tools
>
> A Custom Agent node [calls FlowX workflows as tools](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run), each with a hint for when to use it.

Full list: the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog), and the [5.10](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026), [5.11](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026), [5.12](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026), and [5.13](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) release notes.

***

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > The Developer Agentic Harness is the Designer's AI agent: it surveys your app, plans the change, and builds it on its own branch.
> >
> > **Before 6.0:** the harness ran an approved plan as a single run, and a conversation stayed tied to the app and branch where you started it. **Now:** a plan can split the work into stories, each a slice of the app you can try on its own, delivered one story at a time. You can point at a component in the running app to ask for a change. Your conversations follow you across the Designer.
> >
> > Each story says how to test it and what the agent needs from you, so you check one working slice before the next one starts. Comment mode turns the running UI flow or process into the brief: select a component, say what should change, and the comment lands in the conversation with the component attached. A conversation writes to the project and branch set by the first change you confirm, wherever you navigate after that, and the agent asks before it reads beyond that target.
> >
> > > [!NOTE]
> > >
> > > **Removed:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors, such as **Generate** on the data model and the sparkle buttons in business rules, reusable functions, and Script nodes. Open the agent rail instead: press **⌘K** (**Ctrl+K** on Windows and Linux) or select the sparkle toggle in the header. The harness still uses those agents internally for focused generation work. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness#what-the-agent-can-see-and-change).
> >
> > <video>
> >   <track label="English" />
> > </video>
> >
> > See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
>
> > [tab] Key Features
> >
> > > [card] [Story-by-story delivery](/6.x/ai-platform/developer-agentic-harness#how-does-a-plan-with-stories-run)
> > >
> > > Implement the next story, test it with the steps the story gives, then continue with one story or all that remain.
> >
> > > [card] [Comment on the running app](/6.x/ai-platform/developer-agentic-harness#how-do-i-comment-on-the-running-app)
> > >
> > > Select **Comment** in the header, pick a component in the running UI flow or process, and say what should change.
> >
> > > [card] [Conversations that follow you](/6.x/ai-platform/developer-agentic-harness#sessions)
> > >
> > > Every conversation you have in the organization, searchable. Each keeps writing to the project and branch of its first confirmed change, wherever you navigate.
> >
> > > [card] [Asks before reading more](/6.x/ai-platform/developer-agentic-harness#what-happens-when-the-agent-asks-to-read-another-project)
> > >
> > > Read-only access to another project needs **Allow for this conversation**, and you can revoke it from the rail.
> >
> > > [card] [Attach your material](/6.x/ai-platform/developer-agentic-harness#attach-files-to-a-conversation)
> > >
> > > Give the agent PDF and DOCX briefs, screenshots, or BPMN diagrams to plan and build from.
> >
> > > [card] [Delete with a plan export](/6.x/ai-platform/developer-agentic-harness#delete-a-conversation)
> > >
> > > Deleting a conversation keeps its commits on the branch and offers **Export plan** for what wasn't run.
> >
> > > [card] [Entry points, handovers, and repairs](/6.x/ai-platform/developer-agentic-harness#entry-points-handovers-timeouts-and-repairs)
> > >
> > > The agent suggests an entry point and asks again before serving, adds handover buttons, times out workflow waits, and proposes a repair when a step fails, a limited number of times per step.
>
> SaaS

### **Corrective actions on running instances**

> [card] Corrective actions on running instances
>
> > [tab] Overview
> >
> > Corrective actions shipped in the 5.12 and 5.13 feature releases. They fix running process instances in place, without restarting them, from **Runtime** → **Runtime Control** → **Corrective Actions**.
> >
> > **Bulk process-instance migration** moves a filtered set of running instances from one build to another in one run, so a fix made in a newer build reaches instances already in flight. **Move token** takes the active token off the node the instances are stuck on and places it on another node of the same process, and the instances stay on their build.
> >
> > The **Workspace corrective actions editor** role grants both. It replaces the Workspace operations editor role, and the upgrade moves users and groups that had the old role to the new one.
> >
> > See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances) and [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
>
> > [tab] Key Features
> >
> > > [card] [Build to build, in bulk](/6.x/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > Pick the source build, the target build, and the instances to move, then review the eligible count and map any node missing from the target build before you start.
> >
> > > [card] [Move token](/6.x/docs/projects/runtime/active-process/move-token)
> > >
> > > Resume stuck instances from another node of the same process, on one or many instances at once.
> >
> > > [card] [Dedicated role](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix)
> > >
> > > Grant corrective actions without handing out workspace admin rights.
> >
> > > [card] [Notified when done](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification)
> > >
> > > The notification center reports when a bulk migration finishes.
>
> SaaS

### **New Designer header**

> [card] New Designer header
>
> **Before 6.0:** the branch selector, the version state, and **Commit Changes** sat in the project's top bar. **Now:** the header holds the project name, the **Config** / **Runtime** switch (**Config** to edit a version, **Runtime** for builds and their settings), the **Build with AI** and **Comment** toggles, and **Run project**, which starts the version's entry point. Branching, the current version, and **Commit Changes** move to a version block at the start of the footer on Config pages.
>
> ![Designer project on a Config page: the header shows the project name, the Config and Runtime switch, the Build with AI toggle, and Run project; the footer starts with the version block showing the main branch, the version name, and Start New Version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/designer-header-6-0.png)
>
> The Designer also opens the workspace you used last, and **Organization settings** is in the avatar menu. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
>
> SaaS

### **AI node retries**

> [card] AI node retries
>
> **Before 6.0:** an AI node failed as soon as its AI service or LLM provider couldn't be reached. **Now:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when the service is unreachable, the provider is unavailable or rate-limits the request, or the connection fails. Timeouts aren't retried by default, because the node may already have called its tools.
>
> Toggle **Allow Retry** on in the node's **Settings** to set your own count, interval, and exponential backoff. After the last retry, the workflow continues down the node's failure exit if one is connected. With **Allow Retry** on, the workflow run logs show each attempt on its own line.  See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
>
> SaaS

### **Knowledge Base re-embedding and entry lifecycle**

> [card] Knowledge Base re-embedding and entry lifecycle
>
> **Before 6.0:** the embedding model was locked once a Knowledge Base held content. **Now:** turning **Containing Personal Information** on or off later re-embeds the existing content with the new model. Search keeps using the current embedding while it runs, and content changes are locked until it finishes. If some documents fail, the Knowledge Base stays on its previous model and the header says how many weren't re-embedded.
>
> Entries also have their own lifecycle: **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested) and [disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
>
> SaaS

### **Chat message in AI node prompts**

> [card] Chat message in AI node prompts
>
> > [!WARNING]
> >
> > **Behavior change.** The chat message is no longer appended to the end of an AI node's prompt automatically. In chat-driven workflows, reference `${userMessage}` in the node's **Context** wherever the agent should answer the user's message.
>
> The message still reaches the model inside the input data when **Use only referenced values as input** is off. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
>
> SaaS

### **Evaluations: test cases replace datasets**

> [card] Evaluations: test cases replace datasets
>
> **Before 6.0:** test cases lived in datasets, and the Code evaluators checked outputs for an exact, JSON, or Levenshtein match. **Now:** each workflow has its own test cases, grouped by tags. Each case carries its checks: asserts for **equals** and **equals as JSON**, and LLM evaluators with a pass threshold. An experiment runs the test cases you select. See [Evaluations](/6.x/ai-platform/evaluations).
>
> > [!WARNING]
> >
> > **Behavior change.** The upgrade converts each dataset's test cases and keeps the dataset name as a tag, but adds no checks. An experiment skips a case with no enabled check, so add an assert or evaluator to each converted case before you run it. The Code evaluators are removed: use the **equals** assert in place of **Exact match**, and **equals as JSON** in place of **JSON match**. **Levenshtein** has no replacement. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
>
> SaaS

### **Scheduled workflows**

> [card] Scheduled workflows
>
> > [tab] Overview
> >
> > **Before 6.0:** an integration workflow started only when a process, a UI flow, or another caller started it. **Now:** add schedules to the workflow's **Start** node and it starts by itself at each fire time.
> >
> > Schedules fire once on a date or repeatedly on an ISO or cron cycle, and the dialog previews the next fire times in your local time zone. Saving a schedule or publishing a build never turns it on: activate it in **Runtime** → **Runtime Settings** → **Schedules**.
> >
> > See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
>
> > [tab] Key Features
> >
> > > [card] Date or cycle
> > >
> > > Fire once at a date and time, or repeatedly with an ISO or cron expression built from guided fields.
> >
> > > [card] Up to 50 per workflow
> > >
> > > Each schedule has a name that is unique on its workflow. Schedules are available on Output Focused workflows, which process structured input and output.
> >
> > > [card] Explicit activation
> > >
> > > A schedule fires only after you activate it on the **Schedules** page, for a workflow in the project's active build.
> >
> > > [card] Next fire times
> > >
> > > Check the previewed fire times before you save.
>
> SaaS

### **Certificates: trust and identity**

> [card] Certificates: trust and identity
>
> > [tab] Overview
> >
> > **Before 6.0:** a REST data source combined keystore, truststore, and a skip-verification switch in one TLS setup. **Now:** the **Certificates** panel has two independent parts. **Trust** decides what the host's certificate is checked against: **System CAs** (the default), a **Custom CA**, or **None (insecure)**. **Identity** is the client certificate FlowX presents for mutual TLS, turned on with **Present a certificate**.
> >
> > The same panel is available on File Storage data sources. Existing certificate settings are converted to the new model automatically.
> >
> > See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates) for when to use each option.
>
> > [tab] Key Features
> >
> > > [card] Trust per data source
> > >
> > > Changing trust on one data source leaves every other call verified as before.
> >
> > > [card] Mutual TLS when asked
> > >
> > > Present a client certificate only to hosts that require one.
> >
> > > [card] [File Storage too](/6.x/docs/platform-deep-dive/integrations/file-storage#certificates)
> > >
> > > S3-compatible storage uses the same Trust and Identity settings.
> >
> > > [card] Insecure, by name
> > >
> > > **None (insecure)** is labeled as such and accepted only on REST and File Storage data sources.
>
> SaaS

### **Generate Tabular File node**

> [card] Generate Tabular File node
>
> A new node under **Tools** in the workflow palette turns a workflow variable that holds an array of rows into a CSV or XLSX file, stored as a document linked to the workflow run. A workflow can now produce an export without a Script node. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
>
> SaaS

### **FlowX Database unique indexes**

> [card] FlowX Database unique indexes
>
> Toggle **Enforce unique values** when you add an index to reject documents that repeat a value already stored, on one attribute or on a compound key, with an option to exempt documents that leave the key empty. Existing duplicates are reported when you run **Apply Indexes**, before the index is created. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
>
> SaaS

### **Issues Console version checks**

> [card] Issues Console version checks
>
> **Before 6.0:** an Issues Console check, which validates the resources in a project version, covered processes, UI flows, and integration workflows. **Now:** it also checks the version itself: missing, broken, or mismatched entry points, a theme that isn't in the workspace, library builds that are missing directly or transitively, and dependencies the version doesn't use. Selecting a finding opens the version settings or the **Dependencies** page, where you fix it. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
>
> SaaS

### **Import and export notifications**

> [card] Import and export notifications
>
> The notification center now covers version imports and build exports and imports, alongside version exports and process instance migrations. Each operation notifies you when it starts and replaces that entry with its result: ready to download, imported, needs review with a conflict or excluded-resource count, failed, or timed out. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
>
> SaaS

### **Resource documentation**

> [card] Resource documentation
>
> Open **Documentation** from a resource's menu to give it a short description and longer Markdown documentation, written and previewed in the same window. Media Library assets in a project library get a description too, used as the image's alt text in the asset preview. Knowledge base stores, navigation areas, and user tasks in the process navigation panel have **Documentation** in their menus too. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
>
> SaaS

### **Sensitive values stay hidden**

> [card] Sensitive values stay hidden
>
> After you save a `value` configuration parameter with **Sensitive** on, the Designer shows `********` in place of the value in the parameters list, overrides, build details and lists, and the merge view. The real value is still used at runtime, and editing other fields keeps it. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
>
> SaaS

### **Substitution tags inside any text**

> [card] Substitution tags inside any text
>
> > [tab] Overview
> >
> > **Before 6.0:** a substitution tag resolved only when it was the whole value of a property, so `@@greeting ${firstName}` rendered as empty text. **Now:** write `${tag:key}` anywhere in a component's text, next to static text and process data, and the renderer fills in every tag: `${tag:greeting}, ${firstName}!` renders as "Hello, John!".
> >
> > The upgrade rewrites whole-value `@@key` references to `${tag:key}` in processes, UI flows, and reusable templates, so existing screens render as before. `@@key` keeps working as a whole value.
> >
> > See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).
>
> > [tab] Key Features
> >
> > > [card] Tags, text, and data together
> > >
> > > Use several tags and process data placeholders in one label, placeholder, message, validator message, or option label.
> >
> > > [card] Existing references converted
> > >
> > > Whole-value `@@key` references become `${tag:key}`. Option values and the default of choice components stay `@@key`.
> >
> > > [card] Task Manager columns
> > >
> > > A column value of exactly `${tag:key}` shows, filters, and sorts like `@@key`.
> >
> > > [card] Import from and export for 5.9
> > >
> > > Importing from 5.9 converts `@@key` forward. Exporting for 5.9 converts whole-value tags back to `@@key`.
>
> SaaS

### **GraalVM script engine deprecated**

> [card] GraalVM script engine deprecated
>
> The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports it, for every JavaScript and Python script: business rules, reusable functions, workflow Script nodes, and the rest. Scripts that run on GraalVM keep working in 6.0.0. Move them to the native engine, the default since 5.9.0, before support ends. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).
>
> **Time limits on GraalVM too:** scripts that run on GraalVM now stop at the same per-language time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default, set on the process engine and Integration Designer with `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` and `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`. Before 6.0.0, a GraalVM script had no time limit. A script that runs past its limit is stopped and fails with an error saying it did not finish within its time limit. Before you upgrade, check GraalVM scripts that can run longer than these limits, or raise the limits. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
>
> All Deployments

### **Smaller improvements**

> [card] Smaller improvements
>
> **Auto-arrange on both canvases:** select **Auto-arrange** on the workflow canvas, or **Arrange** on the process canvas, to see a tidied layout in the **Layout preview** bar before anything moves. Compare it with the current layout, then **Apply** or **Cancel**. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).&#x20;
>
> **Timers in local time:** timer nodes now use the same editor as workflow schedules. Dates and times you pick are in your local time and saved in UTC, one control switches between **Guided**, **Expression**, and **Process variable** entry, and cycle timers preview their next fires. Timers saved with the earlier date pickers can look shifted by your UTC offset in the panel, but they still fire at their stored time. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).&#x20;
>
> **Longer branch names:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).&#x20;
>
> **Organization branding:** a **Branding** page under **Organization settings** > **Customization** sets one brand for the organization: name, logos, legal and social links, container app colors and header, and the sender, signature, and text of the invite, verify email, and reset password emails, with a preview of each. Login page and email branding are available on FlowX SaaS only. See [Organization branding](/6.x/docs/saas/organization-branding).&#x20;
>
> **Typed dates in the Datepicker:** turn on **Allow manual input** to let users type a date in the pattern of the project's default locale instead of picking it. Web only, and not available while **Legacy component** is on.&#x20;
>
> **Data mapping creates data types:** type a new attribute path such as `client.address.street`, and saving the mapping creates the data types it names. Until then, the mapper marks them as not yet added to the data model. Required rows show an asterisk, and mapping an object onto a primitive field shows an error.&#x20;
>
> **Removed fields stay removed:** when a node's output sets a field to `null`, the field is removed from the workflow data and later steps no longer restore it with a `null` value. If a condition checks for `null`, make it handle a missing field too.&#x20;
>
> **Keys with dots stay whole:** a data key that contains a dot, such as `cash|31.12.2025`, now stays one key when a workflow saves its data. Before, the key was split into nested objects and later nodes could not read it.&#x20;
>
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, and Kafka topics, see [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0). To upgrade the Helm chart or a renderer SDK, follow [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).


# Deployment guidelines v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/deployment-guidelines-v4.6.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.0 FlowX.AI release, you cannot import old process definitions or resources into the new platform from older versions .

## Component versions

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.0.2** | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.3** | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.1.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.0** | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.0.3** | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.0.3** | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | **4.1.3** | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | **7.0.3** | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.0** | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.0** | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.1.12** | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.0** | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.1** | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.0.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.3** | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.9** | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.10** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.9** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.3** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.24** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.5.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.0 | Keycloak | 22.x |
| 4.6.0 | Kafka | 3.2.x |
| 4.6.0 | PostgreSQL | 16.2.x |
| 4.6.0 | MongoDB | 7.0.x |
| 4.6.0 | Redis | 7.2.x |
| 4.6.0 | Elasticsearch | 7.17.x |
| 4.6.0 | Oracle Database | 21C/ 21-XE |
| 4.6.0 | Angular (Web SDK) | 19.x |
| 4.6.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

## New microservices - setup guides

> [card] [Application-manager](/4.7.x/setup-guides/application-manager)

> [card] [Runtime-manager](/4.7.x/setup-guides/runtime-manager)

> [card] [Integration Designer](/4.7.x/setup-guides/integration-designer-setup)

> [card] [Data-sync job](/4.7.x/setup-guides/data-sync)

## New access rights and roles

> [card] [Integration Designer access rights](/4.7.x/setup-guides/access-management/configuring-access-rights-for-integration-designer)

> [card] [Application Manager access rights](/4.7.x/setup-guides/access-management/app-manager-access-rights)

## Updated access rights and roles

> [card] [Task Manager access rights](/4.7.x/setup-guides/plugins-access-rights/configuring-access-rights-for-task-management)
>
> Added new roles for **manage-views**.

## New service accounts

> [card] [Runtime manager service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#runtime-manager-service-account)

> [card] [Integration Designer service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#integration-designer-service-account)


# Deployment changes for v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x

This document outlines the configuration and infrastructure changes introduced from v4.1.x to v4.6.0 for deploying the FlowX.AI platform.

## CMS Setup

### MongoDB configuration

In version 4.6.0, the CMS setup includes a more comprehensive MongoDB configuration, especially for runtime data handling:

* **Runtime MongoDB Instance**: A dedicated MongoDB instance for managing runtime data.
  * **New Environment Variables**:
    * `RUNTIME_DB_USERNAME`: Username for runtime MongoDB access.
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: Connection URI for the runtime MongoDB instance.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`). Default is `mongodb`.
  * **Transaction Settings for Mongock Library**:
    * `MONGOCK_TRANSACTIONENABLED`: Controls MongoDB transaction support with Mongock, defaulting to `false` due to compatibility concerns with MongoDB 5.

### Private storage configuration

Private CMS to securely store uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints. This CMS will support AI services and workflows while maintaining strict access controls.

> [!NOTE]
>
> Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from project builds as they aren't needed at runtime.

* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL`: This environment variable specifies the URL of the S3 server used for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME`: This environment variable specifies the name of the S3 bucket dedicated to private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET`: This environment variable indicates whether the private S3 bucket should be created if it does not already exist. It can be set to true or false.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY`: This environment variable holds the access key used to authenticate to the S3 server for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY`: This environment variable holds the secret key used to authenticate to the S3 server for private file storage.

> [card] [CMS setup guide](/4.7.x/setup-guides/cms-setup)

***

## Admin setup

### MongoDB configuration

Version 4.6.0 introduces a new MongoDB setup in the Admin service for managing data model information:

* **New MongoDB Data Model Configuration**:
  * **Environment Variables**:
    * `SPRING_DATA_MONGODB_URI`: URI for connecting to the MongoDB data model instance.
    * `DB_USERNAME`: Set to `data-model` for data model access.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`).

***

## Engine setup

### MongoDB configuration

The Engine configuration now includes additional setup for a runtime MongoDB instance to manage runtime builds:

* **Runtime MongoDB for Engine**:
  * **New Environment Variables**:
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: URI for connecting to the runtime MongoDB.
    * `DB_USERNAME`: Set to `app-runtime` for runtime data access.


# Configuration and migration guide
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/process-configuration

This guide outlines changes in process and UI configuration from v4.1.x to 4.6.0 version.

## Projects

The **Projects** feature in FlowX AI v4.6.0 is a new structure that organizes all dependencies and resources required for a project into a single deployable view. This enhancement simplifies configuration, deployment, and maintenance by layering projects on top of processes, offering a centralized workspace that encapsulates everything needed for project execution.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)

Several key configuration changes impact how resources and dependencies are managed, deployed, and maintained. This guide provides a breakdown of the configuration changes, automatic migration processes, and manual steps required to ensure a smooth transition.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)

***

### Consolidated resource management

* **Change**: All resources that were previously managed individually within processes are now grouped within Projects. This includes content management elements, integrations, themes, task configurations, and permissions.
* **Impact**: Resources like **enumerations**, **substitution tags**, and **generic parameters** are now managed within Projects, allowing centralized configuration and version control.
* **Migration**: All process-related resources will be migrated automatically into a **default project**, ensuring continuity of functionality in the new framework. After migration, you should verify that all critical resources are correctly configured within this default project.

> [card] [What are resources?](/4.7.x/docs/projects/resources)

### Enhanced version control and dependency management

* **Impact**: Projects support **dependency management** through **Libraries** and enforce version-controlled resources. Setting up a project now requires careful dependency management and versioning to prevent unintended updates.
* **Benefit**: Allows for modular, reusable resources and stable deployments across projects, reducing resource duplication and enhancing project compatibility.

### Migration checklist

To ensure a smooth transition, complete the following steps:

1. **Verify Process Migration**: Confirm that all existing process definitions have been correctly migrated into the default project.
2. **Set Configuration Parameter Overrides**: Post-deployment, adjust environment-specific Configuration Parameters in the default project.
3. **Update Task Views**: Replace the global "All Tasks" feature with project-specific Views in each project.
4. **Transfer Processes and Dependencies Manually**: If moving a process from the default project to another project, manually transfer associated resources and re-check dependencies.

***

## Generic parameters migration

* **Overview**: In version 4.6.0, global generic parameters (from versions prior to 4.6.0) have been migrated to project-level as Configuration Parameters, consolidating parameter management within specific projects for improved organization and control.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/Screenshot%202024-11-06%20at%2019.04.49.png)

* **Migration**: All generic parameters will be automatically migrated to Configuration Parameters section under a default project.
* **Business Rules Unaffected**: There is no impact on existing business rules; they will continue to function as before without requiring updates.
* **Process Export Considerations**: If you export a process from one project to another, ensure that you also transfer the associated configuration parameters. This step is crucial to maintain process functionality and consistency across projects.
* **Important Note**: Only values of generic parameters associated with the specific environment, or where `env = null` (displayed as "all" in the interface in versions prior to 4.6.0), will be migrated. You must ensure that you have correctly set the values for generic parameters, paying attention to environment values (which are case-sensitive), and export these generic parameters before migration to avoid any potential data loss.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.39.29.png)

* **Post-Deployment Step**: After the first deployment to an upper environment, you will need to create configuration parameter overrides with the specific values required for that environment. This ensures that all environment-specific configurations are accurately maintained and applied across different deployment stages.

> [!TIP]
>
> To set configuration parameter overrides, navigate to **Your App -> Runtime -> Configuration Parameters Overrides**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.42.06.png)

***

## Source systems migration

* **Change**: Source systems have not been migrated automatically and need to be manually recreated.
* **New Location**: In v4.6.0, source systems have been moved under Integration Designer.
* Manual Migration Required:
  1. Navigate to Integration Designer.
  2. Recreate each source system manually with the same code as in the original configuration.
  3. Ensure the "Enable enumeration value mapping" checkbox is enabled.
* **Impact**: Failure to manually migrate source systems may result in broken integrations and missing data mappings.

**v4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2009.53.30.png)

**\< v.4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2010.09.12.png)

## Task management

* "All Tasks" as a View: The global "All Tasks" feature is no longer standalone and will now function as a View in a project.

**v4.6.0:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

**v4.1.x:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/all_tasks.png)

***

## General

Before starting the migration, complete the following steps:

1. **Merge All Feature Branches**: Ensure all feature branches for processes are merged into the latest version on the main branch.
2. **Remove Unnecessary Resources**: Delete any test processes or resources that are no longer needed.
3. **Export Generic Parameters**: Export generic parameters as a backup to ensure they migrate accurately to project-specific Configuration Parameters.

### Migration steps

During migration, resources will be transferred into a single **default project** with one committed version.

* **Process Definitions**: Only the last committed process version on the main branch will migrate. If no committed version exists, the latest WIP version will be used.
* **Enumerations, Substitution Tags, and Task Manager**: These resources will be migrated to the default project.
* **Generic Parameters**: Migrated as **Configuration Parameters** within the default project, covering only values where `env = null` or that match the platform’s environment setting.
* **Languages**: Language settings (available languages and default) will be moved to project settings. Languages remain globally available.

### Resources excluded from migration

Some resources will remain globally available or are deprecated:

* **Themes**
* **Fonts**
* **Global Media Library** (for media used in themes)
* **Out of Office (Task Manager)**
* **Integration Management** (will not be available in v4.6.0)

***

## Datepicker Migration

In version 4.6.0, significant updates have been introduced to the **Datepicker** component to ensure compatibility with ISO 8601 date formats and enhanced handling of date attributes within the **Data Model**. This migration affects both newly created and existing processes.

### Key changes

1. **Introduction of Date Types**:
   * **Standard Date**: Stores and displays date values in ISO 8601 format, respecting the project's locale and timezone settings.
   * **Legacy Date**: Retains previous formatting to ensure compatibility with existing business rules and processes.

2. **Properties Updates**:
   * The **Datepicker** now supports dependent properties such as `minDate`, `maxDate`, and `defaultValue`. These properties:
     * Follow the formatting rules of the selected date type (Standard or Legacy).
     * Ensure that dynamic date values pulled from the **Data Model** are displayed correctly.

3. **Backward Compatibility**:
   * **Existing Processes**: All migrated processes with legacy Datepicker components will default to `Legacy Date` type. This preserves the original formatting and ensures no disruption in business rules or workflows.
   * **New Processes**: Newly created processes will default to `Standard Date` type, saving values in ISO 8601 format.

***

### Migration process

1. **Legacy Datepickers**:

   * Automatically flagged during migration.
   * Continue to work with existing business rules.
   * Require manual review for future updates to transition to the **Standard Date** format.

2. **Business Rules Updates**:
   * Legacy Datepickers may require manual adjustments if associated business rules reference hardcoded date formats.
   * Ensure that any dynamic dates used in business rules are compatible with the ISO 8601 standard.

3. **Standard Datepickers**:
   * All new Datepicker components save date values directly in ISO 8601 format.
   * Fully compatible with updated **Data Model** attributes, allowing seamless integration with external systems, adaptors, and reporting plugins.

### Considerations

* **Default Values**:
  * For **Standard Datepickers**, the `defaultValue` must be in ISO 8601 format.
  * Dynamic defaults can also be set using **Data Model** attributes or process data.
* **Data Model Integration**:
  * All external and internal date attributes, including those used by adaptors or business rules, must be explicitly defined in the **Data Model**.
* **UI Designer Overrides**:
  * Overrides can be applied to display dates differently for specific UI elements, ensuring flexibility for localized formatting.

### Recommendations for transition

* **Existing Processes**:
  * Leave Datepicker components in `Legacy` mode unless business rules and workflows are updated to support ISO 8601.
* **New Processes**:
  * Use `Standard Date` to ensure future compatibility and alignment with ISO 8601 formatting.
* **Documentation**:
  * Review and update all timer expressions, adaptors, and external data feeds to use ISO 8601 format for consistency.

***

## Updates to expression evaluation

**What Changed:**

* A fix was implemented in the web expression evaluator regarding how string values are handled during process value replacement.
* Previously, when evaluating dynamic and computed expressions, string variables required manual insertion of double quotes (`""`) because the system did not automatically add them.
* With the recent fix, the system now **automatically adds the necessary quotes** for string replacements.

**Impact:**

* **Existing Expressions:** If your current dynamic or computed expressions include manually added quotes around string values, these might now result in redundant quotes or incorrect string formatting.
* **Behavioral Shift:** The automatic quote addition alters how string values are processed, which might affect outputs if the expressions were structured with the expectation of manual quotes.

**Action Required:**

1. **Review Your Expressions:** Check any dynamic and computed expressions in your processes that currently include manual double quotes around string values.
2. **Modify as Needed:** Remove unnecessary double quotes where the system now handles them automatically to prevent duplicate quoting or formatting issues.

***

## Export/import enumerations (CSV)

In the transition from version 4.1.x to 4.6.0, the following columns have been removed from the enum CSV export format:

* description.application
* description.draft
* contentValue.childContentDescription.application
* contentValue.childContentDescription.draft
* contentValue.childContentDescription.type

Existing CSV export/import processes should be updated to remove references to these columns to ensure compatibility with the 4.6.0 release.

***

## Post-migration recommendations

For complex projects with multiple use cases, **do not use the default project for ongoing development or production builds**. Instead:

1. **Create Branches within the Default Project**: Organize and streamline resources by creating branches. This enables a lightweight build focused on production.
2. **Split the Default Project into Smaller Projects**: Use the import/export feature to separate the default project into individual projects by use case.
   * **Note**: When importing processes into a new project, resource references may need to be manually reconfigured.

***


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/renderers

This guide assists in migrating from FlowX v4.1.x to v4.6.0.

## Android SDK migration guide

### Initialization config changes

A new configuration parameter named `locale` was added to improve formatting the dates, numbers and currencies.

When the SDK initialization happens through the `FlowxSdkApi.getInstance().init(...)` method, the argument must be included inside the `config: SdkConfig` parameter value:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().init(
    ...
    config = SdkConfig(
        baseUrl = "URL to FlowX backend",
        imageBaseUrl = "URL to FlowX CMS Media Library",
        enginePath = "some_path",
        language = "en",
        locale = Locale.getDefault(), // e.g. Locale("en", "US"), Locale("fr", "CA")
        validators = mapOf("exact_25_in_length" to { it.length == 25 }),
        enableLog = false,
    ),
    ...
)
```

### Changes when starting a Flowx process

Two new parameters were added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The id of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun startProcess(
    projectId: String,
    processName: String,
    params: JSONObject = JSONObject(),
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes when resuming a Flowx process

One new parameter was added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the continued process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes regarding the implementation of Custom Components

The support for classical **[Android View](https://developer.android.com/reference/android/view/View)** system has been dropped.\

A Custom Component can now be implemented only by using the **[Compose](https://developer.android.com/compose)** UI system.

This means that the `CustomViewComponent` is now ignored in the internals of the SDK and has been marked as `@Deprecated` and will be completely removed in the next release.

> [!NOTE]
>
> There is no immediate need to update any of the existing components.

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```kotlin theme={"dark"}
fun changeLocaleSettings(locale: Locale, language: String)
```

### Library dependencies updates

* **[Kotlin](https://kotlinlang.org/)**: 1.9.22 **↗** **1.9.24**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping)**: 2024.02.00 **↗** **2024.06.00**
* **[Compose Compiler](https://developer.android.com/jetpack/androidx/releases/compose-compiler)**: 1.5.9 **↗** **1.5.14**
* **[Gson](https://github.com/google/gson)**: 2.10.1 **↗** **2.11.0**

***

## iOS SDK migration guide

### Initialization config changes

A new configuration parameter, named `locale` was added to improve formatting the dates, numbers and currencies.

The locale needs to be set on the `FXConfig.sharedInstance.configure` method

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    config.locale = "en-US"
    ...
}
```

### Changes when starting a process

Two new parameters were added on the 3 available start process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The uuid string of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func startProcess(projectId: String, 
                  name: String, 
                  params: [String : Any]?, 
                  isModal: Bool = false, 
                  showLoader: Bool = false, 
                  completion: ((UIViewController?) -> Void)?, 
                  onProcessEnded: (() -> Void)? = nil)
```

### Changes when resuming a Flowx process

One new parameter was added on the 3 available continue process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func continueExistingProcess(uuid: String, 
                             name: String, 
                             isModal: Bool = false, 
                             completion: ((UIViewController?) -> Void)? = nil, 
                             onProcessEnded: (() -> Void)? = nil)
```

### Updated FXDataSource protocol

A new method has been added to the `FXDataSource` protocol. Update conformance to protocol by adding the implementation of the new func.

```swift theme={"dark"}
func newProcessStarted(processInstanceUuid: String) {
    
}
```

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```swift theme={"dark"}
func changeLocaleSettings(locale: String?, language: String?)
```

***

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated and will use the latest versions Angular (version 19), thus all container apps that want to use the new SDKs should first update the Angular version of the container apps.

In the following we cover the migration guide for a container app from Angular v17 to v19 and the new SDKs.

**1. Remove old packages and their explicit dependencies (required dependency packages for new sdks are bundled in the libraries so we don't need)**

* remove `material-moment-adapter` unless it is used in custom components (usually together with material datepicker) and also the `moment` package (unless used elsewhere in the project )

```bash theme={"dark"}
npm uninstall @angular/material-moment-adapter
npm uninstall moment
```

* remove old FlowX SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/ui-sdk @flowx/ui-theme @flowx/ui-toolkit 
```

* in `angular.json` remove references to old stylesheets:

```bash theme={"dark"}
"./node_modules/@flowx/ui-sdk/src/assets/scss/style.scss"
"./node_modules/paperflow-web-components/src/assets/scss"
"./node_modules/@flowx/ui-sdk/src/assets/scss"
```

* remove old FlowX SDKs explicit dependencies. Please check before removing that packages are not used in the container app or custom components.

```bash theme={"dark"}
npm uninstall date-fns event-source-polyfill inputmask ng2-pdfjs-viewer vanillajs-datepicker @ngneat/input-mask deepmerge-ts marked-mangle
```

* remove deprecated `Angular Flex` library (the new sdks don't use it anymore and the package has been deprecated by the Angular team) unless it is not used in container app or custom components

```bash theme={"dark"}
npm uninstall @angular/flex-layout
```

**2. Update container app to Angular 18**

* Make sure to have the Angular CLI installed at version 18 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@18
```

* Run the Angular update for version 18

```bash theme={"dark"}
ng update @angular/core@18 @angular/cli@18
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@18
```

or, if the container app uses Angular Material, run:

```bash theme={"dark"}
ng update @angular/material@18
```

* Optionally, if your project uses other angular packages (ex. `NgRx`) please run migrations to v18 for each of them before proceeding. You can find details on the libraries documentation pages.

* Angular has changed the default build path in the `dist` folder, it now uses a `browser` folder for the build output. To place the output of the build command directly in the `dist/[APP_NAME]` folder, add the following change in `angular.json`:

```json theme={"dark"}
{
  ...
  "architect": {
    ...
    "build": {
      ...
      "options": {
        ...
        "outputPath": {
          "base": "dist/flowx-demo-app",
          "browser": "" <-- add this line
        },
      }
    }
  }
}

```

**3. Update container app to Angular 19**

* Make sure to have the Angular CLI installed at version 19 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Run the Angular update for version 19

```bash theme={"dark"}
ng update @angular/core@19 @angular/cli@19
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@19
```

or, if the container app uses Angular material, run:

```bash theme={"dark"}
ng update @angular/material@19
```

* Optionally, if your project uses other Angular packages (ex. `NgRx`) please run migrations to v19 for each of them before proceeding. You can find details on the libraries documentation pages.

* Also, it is recommended that you update the `target` and `module` settings in the `tsconfig.json` file to the new version, although be advised that this might require additional changes in the codebase due to new compilation errors that might arise.

```json theme={"dark"}
{
  ...
  "compilerOptions": {
      ...
      "target": "ES2022",
      "module": "ES2022"
  }
}
```

**4. Install the new FlowX SDK packages**

**Adding overrides for libraries that have a dependency on Angular version \< 19**

For some libraries, the required angular version might not be up to date or compatible with the new Angular version. In this case, you can add an override in the `package.json` file to force the library to use the new Angular version.

* For example, the `ng2-pdfjs-viewer` library has a dependency on Angular version 18 and will not work with the installed Angular version 19. To force the library to use the new Angular version, add the following override in the `package.json` file:

```json theme={"dark"}
{
  ...
  "overrides": {
    "ng2-pdfjs-viewer": {
      "@angular/common": "^19.0.0",
      "@angular/core": "^19.0.0",
      "ng-packagr": "^19.0.0"
    }
  }
}
```

**Install new packages**:

> [!WARNING]
>
> **ACTION REQUIRED**: Update to the latest version 4.6 to ensure optimal performance and compatibility.

```bash theme={"dark"}
npm install @flowx/core-sdk@5.63.0 @flowx/core-theme@5.63.0 @flowx/angular-sdk@5.63.0 @flowx/angular-theme@5.63.0 @flowx/angular-ui-toolkit@5.62.1 
```

* Install a type dependency for the SSE library:

```bash theme={"dark"}
npm install --save-dev @types/event-source-polyfill
```

* run through all the migration steps in the [New SDK Api changes](#new-sdk-api-changes) section below.

> [!NOTE]
>
> Each migration requires a 'clean' repository state. Make sure to commit all changes before starting the next migration step.

> [!TIP]
>
> After each Angular update it is recommended you restart your editor or TS Server, to use the new TS version since some import errors might appear.

### New SDK API changes

#### Renderer SDK component usage

In the Angular SDK, the `<flx-process-renderer>` component has two new parameters have been introduced: `projectInfo` and `locale`. These additions help support localization and project-specific configurations.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectInfo` | Object containing an `projectId` key, which identifies the project of the process to be started | `{projectId: string}` | Mandatory |
| `locale` | Provides region-specific settings for localization. | `string` | Mandatory |

Add the definitions for these properties in the class file of the component that uses the process renderer component:

```typescript theme={"dark"}
projectInfo = { projectId: 'your-project-id' },
locale = 'en-US',
```

Use these parameters in the template as inputs for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  ...
  [projectInfo]="projectInfo"
  [locale]="locale"
/>
```

#### API changes

Process Renderer:

| Category | Old Approach | New Approach |
| - | - | - |
| **Process Renderer** | `FlxProcessModule.forRoot({...})` | `FlxProcessModule.withConfig({...})` |

#### Import path updates

| Category | Old Approach | New Approach |
| - | - | - |
| **Import Paths** | `@flowx/ui-sdk` | `@flowx/angular-sdk` (or, in some cases `@flowx/core-sdk`) |
| | `@flowx/ui-theme` | `@flowx/angular-theme` |
| | `@flowx/ui-toolkit` | `@flowx/angular-ui-toolkit` |
| **Process Module** | `import {FlxProcessModule} from '@flowx/ui-sdk';` | `import {FlxProcessModule} from @flowx/angular-sdk` |
| **Localization Module** | `import {FlxLocalizationModule} from '@flowx/ui-sdk';`  Include in module imports | `import {FlxLocalizePipe} from '@flowx/angular-sdk';` Remove from module imports |
| **Task Management** | `import {FlxTaskManagementModule} from '@flowx/ui-sdk';` | `import {FlxTasksManagementComponent} from '@flowx/angular-sdk';` |
| **Client Store Interface** | `import {ClientStoreInterface} from '@flowx/ui-sdk';` | `import {ClientStoreInterface} from '@flowx/core-sdk';` |

> [!NOTE]
>
> You can also remove the `FlxLocalizationModule` from any `imports` arrays in modules, and import the `FlxLocalizePipe` instead

### Icon module update

The `withExtraIconSet` method has been replaced with `provideExtraIconSet`, which should now be used in the providers array.

```typescript theme={"dark"}
@NgModule({
  imports: [
    IconModule,  // Import the IconModule
  ],
  providers: [
    // Use provideExtraIconSet to add your custom icon set
    provideExtraIconSet({
      customIcon1: 'path/to/custom-icon1.svg',
      customIcon2: 'path/to/custom-icon2.svg',
      // Add more icons as needed
    })
  ]
})
export class AppModule {}
```

### Custom Interceptors

The new FlowX SDKs do not depend on Angular's `HttpClient` to make API calls, so existing interceptors must be adapted to a new format, for Request Interceptors (eg. custom headers) and Response Interceptors (eg. error handling)

For an overview of implementation details, please refer to the respective sections of the renderer documentation for the new API changes.

> [card] [Custom Interceptors](/4.7.x/sdks/angular-renderer#custom-interceptors)


# FlowX.AI 4.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025

Welcome, FlowX fam! The 4.6.0 update is here, and it’s packed with features designed to save you time, boost efficiency, and maybe even make you chuckle. Let’s dive into the details, feature by glorious feature. 🎉

## **What's new?** 🆕

### Projects: Order out of chaos

The new Project concept introduces a streamlined approach to managing and deploying complex projects within FlowX. By grouping all related resources—such as processes, enumerations, integrations, and assets—into a single, organized workspace, projects provide a cohesive view for efficient development and deployment.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

💼 **Key Benefits**:

* **Unified Workspace**: Group related processes, integrations, assets, and configurations into one tidy space.
* **Version Control**: Manage multiple builds and versions effortlessly. Rollbacks? No sweat.
* **Resource Sharing**: Reuse processes and configurations across projects like a boss.

> [!TIP]
>
> **Why you’ll love it**: It’s like going from a messy desk to an organized digital office.

🎥 **Quick Demo**: (Who needs text when you have visuals?)

<video />

> [card] [Projects](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

#### 🛠 Config vs Build Mode

**Config Mode**: Tinker, tweak, and perfect.

* Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's the workspace where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

**Build Mode**: Lock it, load it, deploy it.

* Build mode is the stage where the configurations you've set up are packaged into a deployable form. This is the runtime-ready version of your project, containing everything needed for it to function in a production environment. A build includes a snapshot of the project’s state at a given point, ensuring stability and predictability when deployed.

<video />

> [card] [Configuration](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

> [card] [Runtime](/4.7.x/docs/projects/runtime/builds)
>
> For more details, check out this section

***

### Integration Designer: Connect like a pro

It’s like a dating app for your systems: drag, drop, connect, and let the workflows flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)

API integration just got easier! Integration Designer simplifies connecting FlowX with external systems using REST APIs.

✨ **The magic of it**:

* **Drag-and-Drop Interface**: Map data, define workflows, and configure endpoints like a breeze.
* **Flexible Authorization**: Use Service Tokens, Bearer tokens, or go authentication-free.
* **Error Management**: Built-in tools ensure your integrations don’t ghost you.

> [!TIP]
>
> **Fun Fact**: Integration Designer doesn’t just test APIs (we love you, [Postman](https://www.postman.com/)❤️). It automates workflows, saving you tons of time.

> [card] [Integration Designer](/4.7.x/docs/platform-deep-dive/integrations/integration-designer)
>
> For more details, check out this section

***

### Merge Conflicts 2.0: Merge without the drama

Merging branches? We've overhauled the process to make it faster, smarter, and far less painful.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)

🧩 **What’s New**:

* **Advanced Conflict Detection**: Pinpoint issues by resource type (Processes, Enumerations, Media, etc.).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)

* **Resource-Level Resolution**: Resolve conflicts directly in the UI with:
  * JSON comparisons (color-coded for clarity!).
  * Navigation tools to jump between differences.
  * Progress tracking for reviewed items.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

> [!TIP]
>
> **Pro Tip**: Use the “Merge Anyway” option if you need to override unresolved conflicts (but use it wisely!).

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)

> [card] [Merge conflicts](/4.7.x/docs/projects/managing-applications/versioning#managing-conflicts)

***

### AI Agents: Smart, adaptable, always ready to help

FlowX AI Agents bring automation to your fingertips, powered by a flexible, LLM-agnostic core.

🤖 **Why It’s Cool**:

* Works with both open-source and private language models.
* Secure, on-premise deployments available.
* Automates business processes and interactions.

🎥 Check out a quick demo:

<video />

Stay tuned for more.

***

### Localization and Internationalization

FlowX is now more global-friendly with enhanced localization features.

> [card] Flexible Date, Time, Number, and Unit Formatting
>
> Enhanced formatting options for dates, times, numbers, and currencies with support for various international standards including short, medium, long, full, and custom formats.

> [card] Currency Customization
>
> Support for currency formatting with options to display values using ISO codes or symbols, adapting to user-selected locales and regional preferences.

> [card] Locale-Based Configurations
>
> Comprehensive settings for pluralization, capitalization, alignment, and sorting that adapt to regional requirements, helping cater to a diverse global user base.

> [card] Enhanced UI Component Formatting
>
> New options in the UI Designer to override general settings for text, messages, links, and form elements based on locale and region.

> [card] Document Localization
>
> Static and dynamically generated legal documents can now be customized based on regional and locale settings, improving compliance and communication with local audiences.

> [card] [Localization and internationalization](/4.7.x/docs/building-blocks/ui-designer/localization-and-i18n)
>
> For more details, check out this section

***

### Data Model 2.0: Data handling, but make it fashion

In this release, we've introduced Data Model 2.0, a major upgrade designed to simplify and enhance data handling. Key improvements include the introduction of reusable objects, a visual representation of complex data structures, and dynamic data binding, all aimed at creating a more reliable and intuitive experience. The new model ensures references are automatically updated when changes are made, streamlining data management across the platform.

**Highlights**:

* **New Root Element**: Provides a structural basis without impacting business logic, ensuring a clear and organized data structure.
* **Enhanced Data Binding**: Expanded to more areas, with dynamic updates based on changes in the data model.
* **Localization**: Added handling mechanism for locale-specific formatting, ensuring accurate data representation.

<video />

> [card] [Data model](/4.7.x/docs/building-blocks/process/data-model)
>
> For more details, check out this section

***

### Task management 2.0

We've enhanced Task Management capabilities, making it easier to create, track, and manage tasks efficiently. The updated Task Management features include customizable views and advanced filtering and sorting options for task data. Additionally, users can now implement both low-code and full-code solutions for a tailored Task Management experience, ensuring maximum flexibility for different business needs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

> [card] [Task Management](/4.7.x/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> For more details, check out this section

***

### UI Designer

#### Grid layout

We are excited to introduce the Grid Layout feature in this release, enhancing the flexibility and usability of the UI Designer for creating structured and responsive layouts. With the new Grid Layout, users can organize form elements, tables, and other components using a multi-column and row system, allowing for more complex, bidirectional designs compared to the previous flex-based layout.

<video />

> [accordion] This might happen after using it for the first time:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid-layout-first-time.jpg)

#### Table

The Table component is a simple and flexible way to display data in web applications. It lets you customize columns, add pagination, sort and filter data, and apply your own styling. You can resize columns, scroll through data, and even add actions like editing or deleting rows directly in the table. It’s easy to set up, with default columns and rows generated automatically based on your data.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)

> [card] [Table](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/table)
>
> For more details, check out this section

#### FlowX.AI UI Designer new navigator

We are thrilled to introduce the new and improved **UI Designer Navigator**, a major update designed to streamline your UI design process.

> [card] Enhanced UI Layer Panel Design and Functionality
>
> The UI layer panel has been redesigned for a more intuitive experience, making it easier to manage and navigate through your design elements.

> [card] Improved Drag and Drop Experience
>
> Dragging and dropping components in the preview is now smoother and more precise, allowing for faster and easier creation of UIs.

> [card] Flexible Root Component Management
>
> You can now change the root component from a form group to a container or vice versa, offering greater flexibility when copying nodes or resolving configuration problems.

> [card] Clearer Component Hierarchy
>
> It is now simpler to identify where you are placing a component within the hierarchy, thanks to the enhanced drag/reorder functionality in the right panel.

<video />

#### Conditional formatting for UI elements

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)

> [!NOTE]
>
> Conditional styling is available for **text**, **link**, and **container** UI elements based on specific conditions.

#### Hide expressions enhancements

Expanded hide expressions functionality to include:

* Cards
* Collection prototypes and children
* Table cell children (e.g., texts, images, buttons, links)

#### UI actions

* Added a new UI action **Start new project instance**
* Removed the **Start Process Inherit** UI action type.

#### UI action form updates

* Introduced **Functional** and **UX sections** for all action types, with a checkbox for **Add Analytics Name** in the UX section.
* Simplified custom and exclude key management.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2015.20.01.png)

***

### Start new project instance action

We’ve introduced the Start New Project Instance node action, enabling users to initiate a completely new process from within an ongoing one. This functionality is perfect for scenarios where isolated use cases are managed across different projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)

> [card] [Start new project instance action](/4.7.x/docs/building-blocks/actions/start-new-project-instance)

***

### Custom components validation

You are able to validate and retrieve data from a generated screen, including data from a custom form section. Additionally, you’ll have the ability to trigger and manage data directly within that section. This will be a major benefit for clients who have chosen to create custom components for the entire screen (for example, a form that isn’t supported natively by the platform).

> [card] [Validating elements](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/root-components/card#validating-elements)

***

### Autocomputed data to send

In previous platform versions, when creating your UI screens and working with data, you had to ensure that all the data stored in your process keys was saved in the process instance. This required adding an extra parameter called "Data to send" to the "Save Data" node action.

**Older versions** vs **v4.6.0**:

![older versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.x-aut.png)

![v.4.6](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.2-aut.png)

Now, with the autocompute feature, this step is no longer necessary, as the data is automatically saved and sent on your process instance.

> [!TIP]
>
> You no longer need to add "Save Data" node actions, but make sure to include "Forms to Validate" on the UI Actions. This helps ensure that data is submitted correctly and automatically activates any added validators where they exist.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/forms_to_validate.png)

However, you still have the option to customize which keys are included or excluded as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/include_exclude_keys.png)

***

### **Scripting UX Improvements**: *Write code like a wizard*

* **Autocomplete**: Get tailored suggestions based on your data model.
* **New Editors**: JSON and hide/disable expressions editors now include examples, syntax help, and better visual feedback.

<video />

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide%3Adisable%20editor.png)

***

### React & Angular SDKs

Dev friends, we heard you. FlowX now integrates smoothly into your React and Angular apps. It’s like peanut butter and jelly, but make it code.

#### React SDK

With the 4.6.0 release, we're excited to announce the launch of the FlowX React SDK! This new SDK empowers developers to seamlessly integrate FlowX.AI capabilities into React applications, making it easier than ever to build highly interactive, responsive, and dynamic user experiences.

To get started, simply install the FlowX React SDK via npm and check our documentation for examples and best practices!

> [card] [React SDK](/4.7.x/sdks/react-renderer)

#### New Angular SDK

We're excited to announce new releases for FlowX packages to support web applications:

* `@flowx/core-sdk`
* `@flowx/angular-sdk`
* `@flowx/angular-theme`
* `@flowx/angular-ui-toolkit`
* `@flowx/core-theme`

> [!WARNING]
>
> We recommend upgrading to the **latest** versions of all @flowx packages to take full advantage of these new features and improvements. Check the deployment guidelines for version details.

> [card] [Angular SDK migration guide](migrating-from-v4.1.x-to-v4.6.0/renderers#angular-sdk-migration-guide)

***

### Analytics integration for Container Apps

Container apps now support tracking "Screen Displayed" and "Action Executed" events, configurable in the UI Designer to improve insights into user interactions.

**UI Designer updates**

* **Analytics Screen Name:** Configurable under Root UI components (Cards and Containers) to enable tracking in analytics platforms like Google Analytics.

> [!TIP]
>
> "Screen Displayed" events support user task-based reporting, such as when a user task screen is shown.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.01.58.png)

> [!NOTE]
>
> The configured values are stored in `flowxProps.analytics`, making them accessible for integration with analytics tools.

* **Action Analytics:** Tracks user actions (e.g., button clicks) with tags set directly in the UI Action Form.

> [!NOTE]
>
> Added analytics configuration in the **UX Section** for all UI action types.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.20.53.png)

> [!NOTE]
>
> Values are saved in `params.analytics` via the PATCH `/actions` request.

**Renderers updates**

Renderers now expose a public API for triggering analytics events:

* **Screen Events:** Triggered on user task display, using `flowxProps.analytics`.
* **Action Events:** Triggered on action execution, using `params.analytics`.

Dynamic values such as process store keys and replace tags are supported for more contextual tracking.

***

### Plugin updates

**Notifications** and **Documents** plugins have been integrated as **project resources**.

***

### Scheduled Processes: Timer management reimagined

We've completely redesigned how you manage timer-triggered processes. Before 4.6.0, timer activation was managed through a quick actions menu in process definition headers; now it's handled via dedicated UI section in the Runtime tab under Scheduled Processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

🕒 Key Improvements:

* **Centralized Timer Management:** All process timers are now visible and manageable in one dedicated location
* **Persistent Settings:** Timer configurations persist across build exports/imports
* **Environment Control:** Activate or deactivate timers without redeploying your application

For more details, check out this section

> [card] [Scheduled Processes](/4.7.x/docs/projects/runtime/scheduled-processes)

## Bug fixes 🐞

### Rendering

* **Default Value Initialization for UI Elements**: Resolved an issue where certain UI elements were initialized with incorrect default values.

* **Improved Security for Hidden Fields**: Fixed a vulnerability where hidden fields could be accessed through browser developer tools.

* **Form Validation Reset on UI Dismissal**: Addressed an issue where form validation errors persisted after the UI was closed.

* **Keybinding Issues on Windows**: Fixed a bug where pressing specific keys triggered unintended operations in the designer.

* **Input Field Validation for Number Type**: Corrected the validation logic for number input fields to ensure consistent behavior.

* **Improved Datepicker Popup Positioning**: Resolved an issue where the datepicker popup overlapped the associated input field.

* **Manual Date Entry in Datepicker**: Fixed an issue where manually entering a date after selecting one from the datepicker caused errors.

* **Enhanced Update Mechanism for Custom Components**: Improved the reliability of updates for custom components to reflect changes consistently.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **New substitution tags with the same name on different branches aren’t flagged**: Merging branches that include new substitution tags with identical names on different branches does not trigger a conflict. Instead, both tags are retained, resulting in duplicate substitution tags with the same name but different values. This issue bypasses expected conflict detection and can lead to inconsistencies in substitution tag usage.
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] Notification and document templates
>
> * Branches with notification and document templates fail to merge into the main branch

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Changes 🔧

* **Web Renderer Caching:** Improved resource caching with browser mechanisms keyed to build IDs.
* **Process Designer:** Enhanced drag-and-drop functionality for node placement.

***

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.0](./deployment-guidelines-v4.6.0)

Migrating from v4.1.x:

> [card] [Migrating from v4.1.x to v4.6.0](./migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x)

> [card] [Changes in process configuration](./migrating-from-v4.1.x-to-v4.6.0/process-configuration)

> [card] [Renderer SDKs](./migrating-from-v4.1.x-to-v4.6.0/renderers)


# Deployment guidelines v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/deployment-guidelines-v4.6.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.

## Component versions

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.1.1** | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.6** | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.2** | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | 4.1.3 | 4.1.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.4** | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.25** | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.4** | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.11** | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

> [!NOTE]
>
> Note: The same container image and Helm chart are used for **Application Manager** and **Runtime Manager**.

## AI Agents

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.16** | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.15** | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.6** | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.27** | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.6.5** | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.1 | Keycloak | 22.x |
| 4.6.1 | Kafka | 3.2.x |
| 4.6.1 | PostgreSQL | 16.2.x |
| 4.6.1 | MongoDB | 7.0.x |
| 4.6.1 | Redis | 7.2.x |
| 4.6.1 | Elasticsearch | 7.17.x |
| 4.6.1 | Oracle Database | 21C/ 21-XE |
| 4.6.1 | Angular (Web SDK) | 19.x |
| 4.6.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.


# Migrating from previous versions to v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/migrating-from-v4.1.x-to-v4.6.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.0 version, make sure to first review the migration guide for v4.6.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

If you're moving from v4.1.x to v4.6.1, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.6.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025

FlowX.AI 4.6.1 is here with important fixes and improvements to keep things running smoothly. No new features this time—just focused updates to improve stability, fix bugs, and enhance overall performance. Simple, clean, and efficient.

## **What's new?** 🆕

### Rendering

**Form Elements** improvements:

* **Default Value Handling**: Defaults are applied only when no existing value is found, and set upon first display (with specific exceptions).
* **Data Consistency**: Form elements now save data in standardized formats based on type for improved reliability.
* **Smart Defaults**: Clear fallback behaviors for elements like switches, sliders, and checkboxes when no value is present.
* **Synchronized Inputs**: Linked form elements (e.g., input + slider) stay in sync with automatic value adjustments within set limits.
* **Dynamic Dependencies**: Form elements can dynamically adjust based on related components’ values for greater flexibility.

### Merge conflicts

* Improvement: merged version is now selected after a successful merge in versioning modal.

## Bug fixes 🐞

### Merge conflicts

* Fixed an issue that caused conflicts involving notification and document templates to fail.
* Fixed an issue where merges failed when a deleted configuration parameter was updated on a branch.
* Fixed an issue that resulted in duplicate substitution tag keys appearing in the merged version.
* Fixed an issue where merges failed due to the same dependency being added to both the source and target branches.
* Fixed issues related to workflow conflicts.

### Rendering

* Fixed an issue where documents from the media library were not loading correctly when added as a file preview in a user task.

### Integration Designer

* Fixed issue causing a 400 error when adding an enum mapper to the body tab due to incorrect data validation.
* Fixed issue where the last attribute in the objects table was not visible at higher zoom levels due to UI rendering constraints.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.1](./deployment-guidelines-v4.6.1)

Migrating from v4.6.0:

> [card] [Migrating from previous versions](./migrating-from-v4.1.x-to-v4.6.1)


# Deployment guidelines v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/deployment-guidelines-v4.7.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.0 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.
>
> In version 4.7, the import-export functionality for application-version is no longer backward compatible.
>
> * Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
>
> * Similarly, zip files from earlier versions cannot be imported into 4.7.
>
> Note: Zip files for builds and specific resources remain unaffected.

## Component versions

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.3.1** | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.5.1** | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.11** | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.2** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.5** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.0** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.1** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.2** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.4** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.4** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.3** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.2** | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.1.0** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.5** | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.12** | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.21** | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.7.2** | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.13** | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.31** | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.0** | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.0 | Keycloak | 22.x, 26.x |
| 4.7.0 | Kafka | 3.2.x |
| 4.7.0 | PostgreSQL | 16.2.x |
| 4.7.0 | Oracle Database | 21c, 23ai |
| 4.7.0 | MongoDB | 7.0.x |
| 4.7.0 | Redis | 7.2.x |
| 4.7.0 | Elasticsearch | 7.17.x |
| 4.7.0 | Angular (Web SDK) | 19.x |
| 4.7.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/migrating-from-v4.1.x-to-v4.7.0

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025

FlowX.AI 4.7.0 is here to keep your projects vibing, your merges drama-free, and your configs under control—because struggling with your platform is *so* last season. 😎🔥

## What's new? 🆕

✅ Copy resources across projects\
✅ Duplicate resources (in the same project/library)\
✅ Resources usage tracking\
✅ Smarter merge conflict detection & resolution\
✅ Libraries can now define configuration parameters\
✅ Dynamic Kafka topics using configuration parameters

## Projects

### Copy resources across projects

Moving resources between projects is now **fast and seamless**. The new **Copy to Another Project** feature ensures all dependencies stay intact, eliminating the hassle of manual adjustments.

<video />

> [tab] How it works
>
> 1️⃣ **Select a destination** – Choose the target project or library.\
> 2️⃣ **Pick a branch (if applicable)** – For WIP versions, select the target branch.\
> 3️⃣ **Review dependencies** – The system displays referenced resources and validates dependencies.\
> 4️⃣ **Resolve identifier conflicts** – If an identifier already exists in the destination, you'll be prompted to either:
>
> * **Keep both** (create a duplicate)
> * **Replace** (overwrite the existing resource)
> * **Use destination** (retain the existing resource without copying)

> [tab] Why it’s better
>
> * **No broken references** – Everything stays connected.
> * **Auto-add missing dependencies** – No manual setup required.
> * **Works with WIP & committed versions (only from committed to WIP)** – Flexibility for your workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.48.33.png)

> [card] [Copy resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Duplicate resources

> [tab] What you can duplicate
>
> The **Duplicate Resource** feature lets users create a copy of an existing resource within the same project or library version, streamlining workflows and ensuring quick reusability.
>
> <video />
>
> You can duplicate the following resources:
>
> * **Processes**
> * **Enumerations**
> * **Media files (including Global media library files)**
> * **Notification templates**
> * **Document templates**
> * **Views**

> [tab] How it works
>
> * **Duplicate options** are available from each resource’s three-dot menu (table row & secondary navigation).
> * When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).
> * **Cancel** to discard changes or **Duplicate** to create an exact copy in the same project/library version.
> * **Success confirmation:** The system navigates to the newly created resource and displays a success message.
> * **Error handling:** If a resource with the same name/key exists, users will be prompted to rename it before proceeding.

> [tab] Why it’s useful
>
> 💡 **Use cases:**
>
> * Quickly iterate on existing resources.
> * Reduce redundant manual setup.
> * Maintain consistency within projects.
> * Easily clone complex configurations for testing and modifications.

> [card] [Duplicate resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Track where your resources are used

Monitoring your resources has never been simpler and more efficient. Stay on top of where and how they’re being used.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

> [card] [Process Usage](../../4.7.x/docs/projects/resources#process-usage)
>
> Track where a process is referenced, with a clear **Usage Overview modal** that dynamically updates when references change.

> [card] [Enumeration Usage](../../4.7.x/docs/projects/resources#enumeration-usage)
>
> See where enumerations are used across **UI, Data Models, Systems, and Workflows** before making changes.

> [card] [Media Library Usage](../../4.7.x/docs/projects/resources#media-library-usage)
>
> Identify **which UI elements reference media assets** so you don’t accidentally break designs.

📌 **Before deleting a resource, a confirmation modal lists all affected references. No more surprises!**

***

### Configuration parameters overrides

🔹 **Libraries can now define configuration parameters** to help test processes or workflows that use those parameters.

🔹 However, **libraries do not support overrides**.

* **Overrides for library config parameters must be done within a project** where the library is added as a dependency.
* **Overrides cannot be added in libraries directly.**

<video />

💡 **What this means:**

* Libraries provide **default values** for configuration parameters.
* Projects using those libraries **can override these values** as needed.
* This ensures **clear separation between library defaults and project-specific configurations** while maintaining flexibility.

> [!TIP]
>
> ✨ **Overrides take precedence** over library values—so you stay in control.

***

### Merge conflict enhancements

Merge conflicts are never fun, but at least now they’re **easier to handle**.

> [card] Better Conflict Detection
>
> 🚨 Prevents merging if identical resource identifiers exist in both branches (e.g., same name, key, or code).

> [card] Resizable Merge Conflict Tree
>
> 🖥️ Resize the merge conflict tree for better visibility and navigation.

> [card] New Conflict Type
>
> 📢 A new conflict detection system for parent changes/deletions in both branches.

***

## SDK changes

### Expose Enumerations API in Angular SDK

Developers can now dynamically retrieve enumerations via the Angular SDK, making it easier to use enums in custom components like dropdowns.

> [!TIP]
>
> How it Works?
>
> A new method in the Angular SDK allows direct access to enumerations, reducing manual imports and improving flexibility.

**Usage**

The `getEnumeration()` function returns key-value pairs that can be used in components that need enumeration data:

```typescript theme={"dark"}
getEnumeration(enumName: string): { value: string; label: string }[]
```

* `enumName` (string) – The name of the enumeration to retrieve (e.g., 'UserRoles', 'cities')
* Returns: An array of objects containing value-label pairs representing the requested enumeration

> [accordion] Example usage
>
> The enumeration service works seamlessly with Angular's resource API for reactive state management:
>
> ```typescript theme={"dark"}
> import { Component, effect, model, resource } from '@angular/core';
> import { getEnumeration } from '@flowx/angular-sdk';
>
> @Component({
>   selector: 'app-dynamic-enum-select',
>   template: `
>     <select>
>       @for (option of options.value(); track option.value) {
>         <option [value]="option.value">{{ option.label }}</option>
>       }
>     </select>
>
>     <button (click)="enumName.set('cities')">Load Cities</button>
>     <button (click)="enumName.set('countries')">Load Countries</button>
>   `
> })
> export class DynamicEnumSelectComponent {
>   // Create a signal to track the currently selected enum
>   enumName = model<string>('UserRoles');
>
>   // Use resource API to reactively load enumerations when enumName changes
>   options = resource({
>     request: this.enumName,
>     loader: ({ request: enumName }) => getEnumeration(enumName),
>   });
>
>   constructor() {
>     effect(() => {
>       if (this.options.isLoading()) {
>         console.log(`Loading enumeration: ${this.enumName()}`);
>       } else {
>         console.log(`Loaded enumeration: ${this.enumName()}`, this.options.value());
>       }
>     });
>   }
> }
> ```

***

## **Bug fixes** 🐞

✔️ Improved **merge conflict detection and resolution**\
✔️ Fixed **UI rendering issues**

***

## Changes

### Dynamic Kafka topics

FlowX 4.7.0 introduces **Dynamic Kafka Topics**, enabling more flexible and configurable messaging across processes.

🔹 **What’s new?**

* Use **Configuration Parameters** to dynamically assign Kafka topics in **Kafka Send** and **Kafka Receive** actions.
* Concatenate predefined parameters with process variables for **on-the-fly topic selection**.
* Reduce hardcoded values and **simplify environment-specific configurations**.

💡 **Why it matters:**

* Makes **Kafka integrations more scalable** across different deployments.
* Supports **multi-topic messaging** for different use cases without manual updates.
* Ensures better **reusability and maintainability** in process configurations.

📌 Check the [Kafka Send Action](../../4.7.x/docs/building-blocks/actions/kafka-send-action#dynamic-kafka-topics) section for setup details.

***

### Export/import compatibility

In version 4.7, the import-export functionality for application-version is no longer backward compatible.

* Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
* Similarly, zip files from earlier versions cannot be imported into 4.7.

> [!NOTE]
>
> Zip files for builds and specific resources remain unaffected.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.0](./deployment-guidelines-v4.7.0)\
📌 [Migration Guide (from v4.6.0)](./migrating-from-v4.1.x-to-v4.7.0)


# Deployment guidelines v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/deployment-guidelines-v4.7.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.1.

## Component versions

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.5.1** | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.7.6** | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.3.3** | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.4** | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.7** | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.3** | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.4** | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.6** | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.6** | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.6** | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.5** | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.9** | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.2** | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.7** | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.13** | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.27** | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.2** | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.17** | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.35** | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.4** | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.1 | Keycloak | 22.x, 26.x |
| 4.7.1 | Kafka | 3.2.x |
| 4.7.1 | PostgreSQL | 16.2.x |
| 4.7.1 | Oracle Database | 21c, 23ai |
| 4.7.1 | MongoDB | 7.0.x |
| 4.7.1 | Redis | 7.2.x |
| 4.7.1 | Elasticsearch | 7.17.x |
| 4.7.1 | Angular (Web SDK) | 19.x |
| 4.7.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/migrating-from-v4.1.x-to-v4.7.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025

FlowX.AI 4.7.1 brings enhanced resource navigation, better error detection, and workflow improvements to make your development journey even smoother! 🚀

## What's new? 🆕

✅ Enhanced resource usage tracking with direct navigation\
✅ Upgraded JavaScript support to ECMAScript 15 (2024) in Business Rules\
✅ Added Python 3 support with 3x performance improvement\
✅ Major performance enhancements for both design time and runtime\
✅ Security enhancements for runtime endpoints

## Projects

### Enhanced resource usage navigation

We've significantly improved how you navigate between resources and their references with direct navigation capabilities. Now you can easily jump from the usage tracking panel to the exact location where a resource is referenced.

<video />

> [tab] How it works
>
> 1️⃣ **Access resource usage** – View where a resource is being used through the usage panel.\
> 2️⃣ **One-click navigation** – Use the new redirect button to jump directly to the referenced location.\
> 3️⃣ **Missing resource detection** – Easily identify and fix missing resource references with clear indicators.

> [tab] Why it's better
>
> * **Faster troubleshooting** – Directly navigate to problem areas without manual searching.
> * **Improved productivity** – Less time spent hunting down references means more time building.
> * **Better error prevention** – Quickly spot and fix missing resources before they cause issues.

***

## Enhanced scripting capabilities

### ECMAScript 15 (2024) support for Business Rules

FlowX.AI 4.7.1 brings the latest JavaScript features to your business rules with an upgrade to ECMAScript 15 (2024).

> [tab] What's included
>
> * Access to the latest JavaScript language features
> * Modern syntax for cleaner, more maintainable rules
> * Enhanced tooling and IDE support

> [tab] Benefits
>
> * Write more concise and expressive business rules
> * Leverage modern JavaScript patterns and best practices
> * Improved developer experience with better IDE integration

> [!NOTE]
>
> **Important Configuration Note:** Nashorn engine remains the default runtime. To enable GraalJS support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Nashorn will be used.

### Python 3 support for Business Rules

We've upgraded our Python scripting capabilities to Python 3, delivering significant performance improvements while maintaining compatibility.

> [card] 3x Faster Execution
>
> Python scripts now run at least 3 times faster than with Python 2.7.

> [card] Modern Python Features
>
> Take advantage of Python 3's improved syntax, libraries, and security features.

> [!NOTE]
>
> **Important Configuration Note:** Python 2.7 remains the default runtime. To enable Python 3 support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Python 2.7 will be used.

More details about the scripting capabilities can be found in the [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts) section.

***

## Performance improvements 🚀

We've made significant performance enhancements throughout the platform to make your development and runtime experience smoother and faster.

### Design time improvements

For large processes, you'll notice dramatic improvements:

| Operation | Improvement |
| - | - |
| Cloning a process | **5x faster** |
| Opening a process | **70x faster** |

### Runtime enhancements

Platform average response time has been **reduced by 20%** in our comprehensive benchmark\*.

> [!NOTE]
>
> \*The benchmark simulates a typical business process with a combination of user and service tasks. It includes rules that automate decision-making, as well as events for time-sensitive actions and communication. The process also covers various system functions, ensuring the platform can efficiently manage complex workflows with both individual and parallel tasks.

***

## Security enhancements 🔒

We've significantly improved platform security by implementing proper endpoint access controls and separation between internal and public-facing APIs.

> [card] Enhanced API Security
>
> Runtime execution proxy vulnerability addressed with comprehensive endpoint updates.

> [card] Access Control Improvements
>
> Better separation between design-time and runtime endpoints with proper access controls.

### Endpoint security updates

We've implemented a comprehensive security update for runtime endpoints to prevent potential proxy vulnerabilities:

* Redesigned API structure to separate internal (`runtime-internal`) from external-facing (`runtime`) endpoints
* Migrated design-time operations to use `runtime-internal` endpoints for enhanced security
* Moved specific management operations to dedicated `build-mgmt` endpoints
* Updated all API clients to use the new secure endpoints

> [!NOTE]
>
> **Important:** Make sure to update to the corresponding  version of the [**`flowx-admin`**](./deployment-guidelines-v4.7.1#component-versions) to benefit from these security enhancements.

### Enhanced resource caching in Angular SDK

The Angular SDK now includes an improved caching mechanism for CMS resources, optimizing loading times and performance. The cache parameter on the `flx-process-renderer` component allows developers to control caching behavior in different environments.

> [card] [Read about caching in Angular SDK](../../4.7.x/sdks/angular-renderer#caching)
>
> Find details on controlling CMS resource caching during development and production.

## **Bug fixes** 🐞

* Fixed various minor issues to improve overall stability
* Resolved some UI inconsistencies
* Addresses performance optimizations
* Fixed general usability issues

***

## **Additional information**

📌 [Deployment Guidelines v4.7.1](./deployment-guidelines-v4.7.1)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.1)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.10
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/deployment-guidelines-v4.7.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.3** | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.8** | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.6** | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.5** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.4** | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.6** | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.4** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.3** | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.6** | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.2** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.32** | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.24** | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.10 | Keycloak | 22, 26+ |
| 4.7.10 | Kafka | 3.2 - 3.9 |
| 4.7.10 | PostgreSQL | 16 - 17 |
| 4.7.10 | OracleDB | 19c, 21c, 23ai |
| 4.7.10 | MongoDB | 7 - 8 |
| 4.7.10 | Redis | 7.2 - 8.0 |
| 4.7.10 | Elasticsearch | 7 - 8 |
| 4.7.10 | Angular (Web SDK) | 19.x |
| 4.7.10 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.10 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Updated Spring Boot to the latest release for enhanced security and performance\
✅ Updated Java libraries to fix vulnerabilities across all images\
✅ Selectors support for substitution tags across all platforms (Web, iOS, Android)\
✅ System substitution tags on all task management texts\
✅ CMS - Added system substitution tags with migration script support

### Security and Platform Updates

This release includes critical security updates to ensure your FlowX.AI platform remains secure and up-to-date:

* **Spring Boot Update**: Updated to the latest release on the 4.7.x LTS branch
* **Java Libraries Update**: Updated Java libraries to fix vulnerabilities across all LTS 4.7.x images

### Selectors Support for Substitution Tags

You can now use selectors with substitution tags when the source type is process data across all platforms (Web, iOS, and Android). This enhancement provides more flexibility in displaying dynamic content from your process data in selector components.

**Available on:**

* Angular Web Renderer
* React Web Renderer
* iOS Renderer

### System Substitution Tags for Task Management

Task management now includes comprehensive system substitution tags support:

* **Backend CMS**: Added system substitution tags with a migration script to help you transition existing content
* **Web Renderers**: System substitution tags are now available on all task management texts across Angular and React renderers
* This allows for more dynamic and flexible task management configurations

## Bug fixes

> [accordion] \[Designer] Error when copying/pasting nodes with misconfiguration
>
> Fixed an issue where attempting to copy and paste nodes with misconfigurations, or importing an app version/build with misconfigured nodes, would result in an error. The system now handles misconfigured nodes gracefully during these operations.
>
> **Issue**: Error when trying to copy and paste nodes with misconfiguration or import an app version/build with nodes with misconfigurations

> [accordion] \[React] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the React renderer.
>
> **Issue**: \[React] Card not expandable after finishing subprocess started from it

> [accordion] \[Angular] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the Angular renderer.
>
> **Issue**: \[Angular] Card not expandable after finishing subprocess started from it

> [accordion] \[React] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the React renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[React] Card shouldn't collapse when next nav area is modal

> [accordion] \[Angular] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the Angular renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[Angular] Card shouldn't collapse when next nav area is modal

> [accordion] \[Backend] Task Manager - System substitution tags not displayed in column names
>
> Fixed an issue where system substitution tags were not being displayed in the `columns.displayName` property of the Task Manager backend.
>
> **Issue**: \[BE] Task manager | System substitutionTags are not displayed in columns.displayName

> [accordion] \[Web Renderers] Task Manager - Substitution tags value override
>
> Resolved an issue where system substitution tags values were incorrectly overriding custom substitution tags when the value was not null in both React and Angular renderers.
>
> **Issue**: \[React]\[Angular] Task manager | System subTags values override de custom subTags when value is not null

> [accordion] \[Task Manager] Missing localization for Russian and Uzbek in table view
>
> Fixed localization support in Task Manager table view for Russian and Uzbek languages, ensuring proper display of translated content.
>
> **Issue**: \[Task manager localisation] Table view - Missing localisation support for Russian and Uzbek

> [accordion] \[Task Manager] View search field placeholder not localized
>
> Resolved an issue where the view search field placeholder in Task Manager was not being localized for any language. The placeholder now properly supports all configured languages.
>
> **Issue**: \[Task manager localisation] View search field placeholder not localised for any language


# Deployment guidelines v4.7.11
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/deployment-guidelines-v4.7.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.6** | 8.24.3 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.12** | 7.18.8 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.9** | 5.11.6 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.8** | 6.8.5 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.7** | 6.10.4 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.9** | 7.9.6 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.7** | 6.8.4 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.6** | 2.16.3 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.9** | 2.10.6 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.103.6** | 5.101.2 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.32 | 4.0.32 | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.27** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.25** | 1.8.24 | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.11 | Keycloak | 22, 26+ |
| 4.7.11 | Kafka | 3.2 - 3.9 |
| 4.7.11 | PostgreSQL | 16 - 17 |
| 4.7.11 | OracleDB | 19c, 21c, 23ai |
| 4.7.11 | MongoDB | 7 - 8 |
| 4.7.11 | Redis | 7.2 - 8.0 |
| 4.7.11 | Elasticsearch | 7 - 8 |
| 4.7.11 | Angular (Web SDK) | 19.x |
| 4.7.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.11 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025

Security and maintenance updates for the 4.7.x LTS release

## What's new?

This is a **security and maintenance release** for the FlowX.AI 4.7.x LTS branch, focused on keeping your platform secure and up-to-date with the latest security patches.

✅ **Security Updates** - Updated core libraries and dependencies to address known vulnerabilities\
✅ **Platform Stability** - Improved overall platform security and stability

***

## Migration notes

> [!WARNING]
>
> As this is a **patch release** on the 4.7.x LTS branch, it is designed to be a **drop-in replacement** with no breaking changes.

***

## Component versions

All FlowX.AI components have been updated to version **4.7.11** with the security patches applied. Refer to the deployment guidelines for the complete list of component versions.


# Deployment guidelines v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/deployment-guidelines-v4.7.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.2 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.2.

## Component versions

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.9.0** | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.5** | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.8** | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.10** | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.16** | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.12** | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.13** | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.14** | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.13** | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.14** | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.2.0** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.12** | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.16** | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.9** | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.35** | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.9** | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.24** | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.1** | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.9** | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.2 | Keycloak | 22.x, 26.x |
| 4.7.2 | Kafka | 3.2.x |
| 4.7.2 | PostgreSQL | 16.2.x |
| 4.7.2 | Oracle Database | 21c, 23ai |
| 4.7.2 | MongoDB | 7.0.x |
| 4.7.2 | Redis | 7.2.x |
| 4.7.2 | Elasticsearch | 7.17.x |
| 4.7.2 | Angular (Web SDK) | 19.x |
| 4.7.2 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## Additional configuration

Added new environment variable on Process Engine:

### Message routing configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

> [!NOTE]
>
> When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.


# Migrating from previous versions to v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/migrating-from-v4.1.x-to-v4.7.2

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 and v4.7.1 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.2 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025

FlowX.AI 4.7.2 delivers improved merge conflict handling with retry capabilities, deprecates DMN business rules, and fixes issues with subprocess handling, media file imports, and OCR functionality to enhance your development workflow! 🚀

## **What's new? 🆕**

✅ Improved merge conflict handling with retry functionality\
✅ Enhanced error messages during failed merges\
✅ Streamlined workflow for resolving merge conflicts

## Merge conflicts

### Improved error messages when merge fails

We've enhanced the merge conflict resolution experience with more informative error messages and a new retry functionality:

* When a merge fails, users can now see a "Retry merge" button on the Merge failed modal
* Clicking this button allows users to attempt the merge again without losing previous work

The system now handles two distinct scenarios:

**1. When conflicts exist:**

* The system opens the Merge conflicts panel with the previous state of the merge before the failed attempt
* This preserves all your conflict resolution work so you can fix the specific issues that caused the failure

![Merge failed with conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20conflicts.png)

**2. When no conflicts exist:**

* The system automatically retries the merge operation
* This streamlines the workflow when the merge failure was due to temporary issues rather than actual conflicts

![Merge failed without conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20no%20conflicts.png)

## Process engine

### Deprecated DMN rules

In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.

**What's changing:**

* DMN is no longer available as a language option when configuring business rule actions

**What's next:**
For guidance on using alternative business rule languages, please refer to our [supported scripting languages](../../../../4.7.x/docs/building-blocks/supported-scripts) documentation.

## **Bug fixes** 🐞

* Resolved export/import issues with media library files, particularly for applications migrated from earlier versions
* Fixed an issue where parallel multi-instance Call Activity would incorrectly trigger a subprocess when using an empty array list as a variable
* Fixed a display issue where not all subprocesses were visible in the subprocess list on smaller screens
* Fixed a bug where message events couldn't be caught when placed directly after an uninterrupting timer event
* Resolved "Unsupported Media Type" errors when importing application versions with media file binaries
* Fixed an issue where color palette changes in Theme settings couldn't be saved at 100% browser resolution on smaller screens
* Fixed a issue where OCR plugin failed due to missing correlation headers

***

## **Additional information**

📌 [Deployment Guidelines v4.7.2](./deployment-guidelines-v4.7.2)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.2)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/deployment-guidelines-v4.7.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.3 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.3.

## Component versions

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.13.0** | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.13** | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.12** | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.11** | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.17** | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.13** | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.16** | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.15** | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.14** | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.15** | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.14** | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.6.0** | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.11** | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.14** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.15** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.37** | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.12** | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.26** | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.3** | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.11** | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.3 | Keycloak | 22.x, 26.x |
| 4.7.3 | Kafka | 3.2.x |
| 4.7.3 | PostgreSQL | 16.2.x |
| 4.7.3 | Oracle Database | 21c, 23ai |
| 4.7.3 | MongoDB | 7.0.x |
| 4.7.3 | Redis | 7.2.x |
| 4.7.3 | Elasticsearch | 7.17.x |
| 4.7.3 | Angular (Web SDK) | 19.x |
| 4.7.3 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/migrating-from-v4.1.x-to-v4.7.3

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.3 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025

FlowX.AI 4.7.3 enhances workflow conflict resolution, adds configurable enumeration ordering, and fixes data streams, UI templates, and application export/import issues to improve your development experience! 🚀

## **What's new? 🆕**

✅ Enhanced workflow conflict resolution with improved visibility\
✅ Added ability to configure order attributes on enumerations\
✅ Upgraded conflict management interface for better user experience

## Merge conflicts - workflow improvements

### Enhanced workflow conflict resolution

We've significantly improved how [**workflow**](../../4.7.x/docs/platform-deep-dive/integrations/integration-designer#workflows) conflicts are handled in this release:

* Upgraded to a new version (v2) of the workflow conflict resolution interface
* Now only showing workflow entities that have actual conflicts, making it easier to identify and address issues
* Streamlined the conflict resolution process for a more efficient workflow

![Workflow conflict resolution](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/workflow_conflicts.png)

> [!NOTE]
>
> **Important note about sequence conflicts:**
>
> When resolving conflicts related to sequences, if you select one of the conflicting sequences, nodes that are no longer connected may remain "orphaned" on the canvas in the merged version. This design decision was made to prevent accidental node deletion. If these orphaned nodes are no longer needed, they can be manually removed in subsequent versions.

## Configurable enumeration ordering

You can now configure the **Order** attribute on enumerations, giving you greater control over how enumeration values are displayed in dropdown lists:

* Set specific order values for each enumeration entry
* Control the presentation sequence in UI components
* Improve user experience by arranging options in logical or prioritized order

![Enum order](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/enum_order.png)

> [!NOTE]
>
> **Limitation:** When changing the order value for an enumeration entry, the system does not automatically update the order values of other entries. You'll need to manually adjust the order values of other entries in the interface.

## **Bug fixes** 🐞

* Fixed an issue where workflow nodes could have two output sequences
* Resolved a problem with enumerations displaying in the wrong order in dropdown lists
* Fixed an authentication issue where users would receive 401 unauthorized errors when executing actions after token refresh
* Fixed a UI behavior issue where slider actions configured with "onChange" were incorrectly triggered when entering a screen instead of only when modified
* Fixed an issue with identical advancing IDs occurring in multi-pod deployments due to missing hostname command in GraalVM docker images
* Resolved an issue preventing media library migration from default application
* Fixed the "Go to reference" functionality from data model attributes that was not correctly redirecting to referenced elements
* Fixed an error during application export/import where "There already exists a tagged build for this project version" was preventing successful imports
* Restored support for multiple topics in Data Stream Topics feature, which was previously only listening to the first topic in the list
* Fixed a 500 error that occurred when attempting to create child actions on certain nodes
* Fixed a critical issue where UI templates would disappear when creating a new version of an application after performing undo operations on pasted templates
* Fixed a bug where updates to the subprocess in a Start subprocess action weren't being saved properly
* Fixed an issue with the "Send email" button remaining disabled in the Test notification template feature after correcting validation errors
* Fixed an error that occurred when trying to export document templates containing null values in templateMap
* Fixed a display issue where Tokens, Workflows, and Subprocesses information wasn't showing in process instances after migration from 4.7.1 to 4.7.2
* Fixed a UI issue where business rule code wasn't displayed when testing business rules in committed versions

***

## **Additional information**

📌 [Deployment Guidelines v4.7.3](./deployment-guidelines-v4.7.3)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.3)


# Deployment guidelines v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/deployment-guidelines-v4.7.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.4 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.4.

## Component versions

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.15.2** | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.9.2** | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.16** | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.13** | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.19** | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.15** | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.18** | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.17** | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.16** | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.17** | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.16** | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.7.2** | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.3.2** | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.19** | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.23** | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.39** | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.17** | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.28** | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.5** | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.13** | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.4 | Keycloak | 22.x, 26.x |
| 4.7.4 | Kafka | 3.2.x |
| 4.7.4 | PostgreSQL | 16.2.x |
| 4.7.4 | Oracle Database | 21c, 23ai |
| 4.7.4 | MongoDB | 7.0.x |
| 4.7.4 | Redis | 7.2.x |
| 4.7.4 | Elasticsearch | 7.17.x |
| 4.7.4 | Angular (Web SDK) | 19.x |
| 4.7.4 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## **Additional information**

* Added new environment variable `OPTIMISTIC_LOCKING_RETRIES` to control the number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

Elasticsearch indexing configuration:

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)


# Migrating from previous versions to v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/migrating-from-v4.1.x-to-v4.7.4

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.4 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025

FlowX.AI 4.7.4 enhances system stability with Spring Boot updates and resolves critical issues across build exports, reporting, SDK functionality, and cross-platform consistency to deliver a more reliable development experience! 🚀

## **What's new? 🆕**

✅ Platform enhancements\
✅ Added retry mechanism for ES indexing to handle key‑identifier errors\
✅ Fixed critical build export timeout issues\
✅ Improved reporting data representation\
✅ Enhanced cross-platform consistency

### Platform Enhancements ⚙️

* Enhanced system stability
* Latest security patches
* Improved performance

### Elasticsearch indexing - configurable retry mechanism

* `OPTIMISTIC_LOCKING_RETRIES`: Number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)

### Data-sync run status monitoring

* Added the ability to view the run status of data-sync jobs directly in the platform interface
* Monitor the execution status of all data-sync jobs from the Jobs dashboard
* Quickly identify failed jobs for faster troubleshooting

![Data-sync run status monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-20%20at%2010.55.19.png)

## **Bug fixes** 🐞

* **Build export timeouts**: Resolved intermittent timeout failures on projects with dependency libraries; exports now consistently complete or retry correctly.
* **Build creation on merge without conflicts**: Fixed an issue where merging one branch into another without conflicts—and switching the active policy—did not trigger a new build, forcing users to manually create a version; now, merges automatically update build resources and create the new version so merged changes appear at runtime.
* **Project version import stashing conflict**: Resolved an error where importing a branched project version across environments would inadvertently stash other versions—restoring successful import, fixing the GET history API response, and ensuring the Project versions history modal renders correctly.
* **CosmosDB workflows**: Fixed an issue preventing the workflow instances list from loading in the Integration Designer when using CosmosDB.
* **Reporting arrays**: Corrected array formatting in the `reporting_data` table (process-engine schema).
* **CMS permissions**: Restored backward compatibility for FlowX SDK v4.7+ by removing the unintended `media_library_read` requirement for processes containing images (behavior now matches v4.1).
* **onChange action behavior**: Standardized onChange/onBlur across web, Android, and iOS so users cannot continue typing after token advancement unless explicitly allowed.
* **React SDK ternary expressions**: Fixed an “Invalid Expression” error in SDK v5.86.1—ternary expressions in computed values (e.g. `return ${var1} ? "Onboarded" : (${var2} ? "Non-eligible" : "Ready for Onboarding");`) now parse correctly as they did in v5.62.1.
* **Elasticsearch indexing**: Fixed an issue where the engine was not retrying to index process instances when it encountered concurrent-update errors on key identifiers.
* **iOS SSE token refresh**: Fixed an issue in iOS SDK where Server-Sent Events connections would occasionally use expired JWT tokens instead of refreshed ones, causing 401 errors and process hangs in production environments.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.4](./deployment-guidelines-v4.7.4)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.4)


# Deployment guidelines v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/deployment-guidelines-v4.7.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.5 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.5.

## Component versions

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.17.0** | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.12.2** | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.5.1** | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.1.1** | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.1.1** | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.2.1** | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.4.1** | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.3.1** | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.1.1** | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.9.0** | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.4.1** | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.21** | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.24** | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.18** | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.5 | Keycloak | 22, 26+ |
| 4.7.5 | Kafka | 3.2 - 3.9 |
| 4.7.5 | PostgreSQL | 16 - 17 |
| 4.7.5 | Oracle Database | 21c, 23ai |
| 4.7.5 | MongoDB | 7 - 8 |
| 4.7.5 | Redis | 7.2 - 8.0 |
| 4.7.5 | Elasticsearch | 7 - 8 |
| 4.7.5 | Angular (Web SDK) | 19.x |
| 4.7.5 | React (Web SDK) | 18.x |

> [!NOTE]
>
> **New in 4.7.5: Support for more 3rd Party Dependencies**
>
> FlowX.AI 4.7.5 introduces support for more versions of third-party dependencies:
>
> * All versions are officially supported throughout the entire LTS lifetime
> * Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major release
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/migrating-from-v4.1.x-to-v4.7.5

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.5 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.5 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025

FlowX.AI 4.7.5 enhances system stability with introducing support for more 3rd party dependency and introduces High Availability improvements with Redis Sentinel mode support to deliver a more reliable and scalable development experience! 🚀

## **What's new? 🆕**

✅ **Platform enhancements**\
✅ **Analytics enhancements**

### Platform enhancements ⚙️

**Extended Third-Party Dependency Support** - Introducing support for more versions of third-party dependencies:

* All versions are officially supported throughout the entire LTS lifetime
* Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major releases for critical infrastructure components, ensuring all supported versions are officially maintained throughout the entire LTS lifetime. This enables organizations to perform gradual dependency upgrades during the LTS period, preparing infrastructure to meet the minimum requirements for the next FlowX.AI major release while maintaining full platform support and stability.

### Analytics enhancements ⚙️

* Improved analytics events with enriched metadata for action events across all platforms (Web, iOS, Android). Action events now include screen context, component type identification, and component labels, providing deeper insights into user interactions and enabling more granular analytics tracking for better user experience optimization.

More details:

> [card] [Angular Renderer](../../../../4.7.x/sdks/angular-renderer#analytics)

> [card] [React Renderer](../../../../4.7.x/sdks/react-renderer#analytics)

> [card] [iOS Renderer](../../../../4.7.x/sdks/ios-renderer#collecting-analytics-events)

> [card] [Android Renderer](../../../../4.7.x/sdks/android-renderer#collecting-analytics-events)

### Runtime Manager deployment changes

> [!NOTE]
>
> **Prior to 4.7.5:** Runtime Manager was deployed using `application-manager` chart/image with manual `SPRING_APPLICATION_NAME`: "runtime-manager" configuration.
> Starting with 4.7.5: Runtime Manager has its own dedicated chart and image with proper defaults.

> [!TIP]
>
> Migration Required

* Switch to new chart: Use runtime-manager chart instead of application-manager
* Verify image: Ensure image name is runtime-manager (default in new chart)
* Remove override: `SPRING_APPLICATION_NAME`: "runtime-manager" can be removed (optional)

> [!WARNING]
>
> You may need to delete the existing runtime-manager deployment before upgrading due to Kubernetes label changes that cause `kubectl apply` to fail.

## **Bug fixes** 🐞

* **Fixed Task Manager loading issue with data type changes** - Resolved critical issue where Task Manager would fail to load and throw `NullPointerException`   when process variables were changed from date to string data types, even after updating the data model and clearing cache
* **Fixed All Tasks view missing on build import** - Resolved issue where importing builds from one environment to another would fail to create the All Tasks view, when accessing the Task Manager area
* **Fixed unassign operation causing runtime errors** - Resolved 500 Internal Server Error when accessing process data after performing unassign operations via Kafka messages, where null ownerDetails would cause `NullPointerException` during JSON serialization
* **Fixed CMS-Core export failures with AWS S3 buckets** - Resolved issue where CMS-Core would add double slashes in S3 object paths when creating exports, causing 404 NoSuchKey errors with AWS S3 (while working correctly with MinIO). Fixed path construction to ensure compatibility with both AWS S3 and MinIO storage backends
* **Fixed active policy version resolution** - Resolved issue where importing application versions to environments with existing WIP versions would incorrectly activate the stashed WIP version instead of the imported committed version, causing graph display failures and incorrect active policy settings

***

## **Additional information**

📌 [Deployment Guidelines v4.7.5](./deployment-guidelines-v4.7.5)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.5)


# Deployment guidelines v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/deployment-guidelines-v4.7.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.6 will permanently prevent you from importing process definitions and resources created in versions 4.7.5 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

> [!WARNING]
>
> **Audit data retention change**
>
> Starting with FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. In 4.7.5 and earlier, the service created this policy only once, on the first installation.
>
> The policy it writes has a single hot phase that rolls the audit data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. The default is `30` days; in 4.7.5 and earlier, the rollover period was a fixed 1 day.
>
> Any phase you added to this policy directly in Elasticsearch, such as a delete phase, is removed the next time the Audit service starts. Without a delete phase, old audit indices are never deleted and audit storage keeps growing.
>
> To keep the previous daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1` on the Audit service.

## Component versions

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.21.1** | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.15.2** | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.8.2** | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.4.0** | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.4.0** | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.5.0** | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.7.0** | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.6.0** | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.5.0** | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.13.0** | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.7.1** | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.29** | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.19** | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.6 | Keycloak | 22, 26+ |
| 4.7.6 | Kafka | 3.2 - 3.9 |
| 4.7.6 | PostgreSQL | 16 - 17 |
| 4.7.6 | OracleDB | 21c, 23ai |
| 4.7.6 | MongoDB | 7 - 8 |
| 4.7.6 | Redis | 7.2 - 8.0 |
| 4.7.6 | Elasticsearch | 7 - 8 |
| 4.7.6 | Angular (Web SDK) | 19.x |
| 4.7.6 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8

## Configuration Parameters

Starting with FlowX.AI 4.7.6, Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment.

> [card] [Integration Designer setup](/4.7.x/setup-guides/integration-designer-setup#configuration-parameters)

> [card] [Process Engine setup](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters)

> [card] [Application Manager setup](/4.7.x/setup-guides/application-manager)


# Migrating from previous versions to v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/migrating-from-v4.1.x-to-v4.7.6

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.6 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.6](../v4.7.6-july-2025/deployment-guidelines-v4.7.6)

> [card] [Deployment guidelines v4.7.5](../v4.7.5-july-2025/deployment-guidelines-v4.7.5)

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1/)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.6 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025

This release includes significant improvements to logging configuration and resolves some issues across the Designer, Process Engine, and Integration Designer components.

> [!WARNING]
>
> Upgrading to 4.7.6 changes how the Audit service manages its Elasticsearch lifecycle policy: the policy is rewritten on every startup and the default rollover period changes from 1 day to 30 days. See the [Deployment guidelines](./deployment-guidelines-v4.7.6) before upgrading.

## **What's new? 🆕**

> [card] Improved default logging configuration
>
> Changed logging verbosity to reduce clutter & log sizes, increasing visibility for more relevant log messages.

> [card] Improved the ability to use deployment specific variables as Configuration Parameters (at process runtime)
>
> Now Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment. Check the [**Deployment Guidelines**](./deployment-guidelines-v4.7.6#configuration-parameters) for more details.

> [card] Improved runtime performance
>
> Improved runtime performance by better distributing the execution of nodes across all components.

> [card] Improved the speed of listing process instances
>
> Improved the speed of listing process instances by 4-6x on environments with a lot of process executions.

> [card] Added the ability to change logging levels at runtime
>
> This feature allows you to dynamically adjust logging levels without requiring a service restart, providing more flexibility in managing log output.

> [card] Reduced config deployment complexity
>
> The previously used `CONFIG_PROFILE` environment variable is no longer required as the default configs have been aligned with the recommended profiles.

## **Bug fixes** 🐞

> [accordion] \[Designer] Task view display issue
>
> Fixed task view list row content display issue where table rows were overlapping and text was not vertically centered in the latest Chrome browser version (138). The task view now properly displays centered content without text cutoff.

> [accordion] \[Integration Designer] JSON parsing error
>
> Fixed JSON parsing error when sending JSON result to REST body. Resolved issue where JSON objects generated in script tasks were causing "Unexpected character" errors when used in REST endpoint body parameters with \$ syntax.

> [accordion] \[Branch Merge] Media file export errors
>
> Fixed media file export errors during branch merges. Resolved issue where merging multiple branches created from the same main version would fail with "400 Bad Request" errors for media files after the first successful merge, even when no merge conflicts were present.

> [accordion] \[Process Designer] Rollback issue
>
> Fixed rollback issue during version submission errors. Resolved problem where processes were incorrectly marked as deleted in the database when submit version operations failed with 500 errors, preventing proper rollback and causing subsequent 404 "Process not found" errors.

> [accordion] \[Process Designer] Missing resources during copy operation
>
> Fixed missing resources during copy to another project/library operation. Resolved issue where forms with validation in UserTask nodes were not being copied when copying processes between projects or libraries.

> [accordion] \[Process Designer] Branch with missing resources and 404 errors
>
> Fixed issue where specific branches derived from main version would experience resource corruption, including missing process definitions (404 errors), missing Integration Designer resources, and commit failures.

> [accordion] \[Process Designer] Parallel multi-instance visual bug
>
> Fixed parallel multi-instance designer visual bug and database errors. Resolved issue where call activity nodes with parallel multi-instance enabled created duplicate "inputKey" and "outputKey" entries, causing visual bugs (missing collection key fields) and database update errors during node modifications.

> [accordion] \[Process Engine] Kafka message distribution
>
> Fixed Kafka message distribution across partitions. Resolved issue where Kafka messages were distributed as batches across partitions, causing increased usage of a limited number of partitions, instead of following the round-robin distribution per message strategy.

***

## **Additional information**

> [card] [Deployment Guidelines v4.7.6](./deployment-guidelines-v4.7.6)
>
> Step-by-step deployment instructions and configuration details for this release.

> [card] [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.6)
>
> Complete guide for migrating from version 4.1.x to 4.7.6 with breaking changes and migration steps.


# Deployment guidelines v4.7.7
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/deployment-guidelines-v4.7.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.7 will permanently prevent you from importing process definitions and resources created in versions 4.7.6 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.22.3** | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.16.3** | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.97.1** | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.9.2** | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.6.2** | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.8.2** | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.7.2** | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.6.2** | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.14.2** | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.8.1** | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.40** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.21** | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.29** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.14** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.7 | Keycloak | 22, 26+ |
| 4.7.7 | Kafka | 3.2 - 3.9 |
| 4.7.7 | PostgreSQL | 16 - 17 |
| 4.7.7 | OracleDB | 19c, 21c, 23ai |
| 4.7.7 | MongoDB | 7 - 8 |
| 4.7.7 | Redis | 7.2 - 8.0 |
| 4.7.7 | Elasticsearch | 7 - 8 |
| 4.7.7 | Angular (Web SDK) | 19.x |
| 4.7.7 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.7 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Improved robustness on auto-scaling process-engine and on Kafka node failures\
✅ Improvements on how configuration parameters can now be retrieved from Kubernetes secrets and ConfigMaps\
✅ Vulnerability fixes

## Configuration parameters

Improved configuration parameters retrieval from Kubernetes secrets and ConfigMaps. More details here:

> [card] [FlowX Engine](../../4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#dynamic-configuration-parameters-retrieval)

> [card] [Integration Designer](../../4.7.x/setup-guides/integration-designer-setup#dynamic-configuration-parameters-retrieval)

## Bug fixes

> [accordion] \[Designer] JSON size limit on input data
>
> Fixed JSON payload size limit issue causing "403 payload too large" errors when starting processes. More details [**here**](../../4.7.x/docs/flowx-designer/managing-a-project-flow/starting-a-process#starting-a-process-via-user-interface).

> [accordion] Improved robustness on Kafka node failures
>
> If one Kafka node fails, platform health check fails. This is now fixed.

> [accordion] \[UI Designer] Theming on accordion card
>
> Fixed theming issue where Card component styling was not properly applied when switched to accordion mode.

> [accordion] \[Angular SDK] Loader does not stop on subprocess end
>
> Fixed loader persistence issue where loaders initiated by "show loader" actions in subprocess UserTasks would continue displaying after subprocess completion.

> [accordion] \[Process Designer] Merge error with duplicate embed node keys
>
> Fixed merge conflict error occurring when copying and pasting embed nodes in processes.

> [accordion] \[Process Engine] Process execution stalls on REST-triggered flows when engine replica fails
>
> Fixed process execution recovery issue where REST API-triggered service tasks would hang indefinitely if the handling engine replica failed mid-execution.

> [accordion] \[Process Designer] Merge fails with duplicate key error after creating child branch to jump over broken WIP
>
> Fixed merge conflict error occurring when creating child branches from working commits to bypass broken WIP versions.


# Deployment guidelines v4.7.8
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/deployment-guidelines-v4.7.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.8 will permanently prevent you from importing process definitions and resources created in versions 4.7.7 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.23.2** | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.17.3** | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.10.3** | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.7.2** | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.9.2** | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.8.2** | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.7.2** | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.15.3** | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.9.2** | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.22** | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.8 | Keycloak | 22, 26+ |
| 4.7.8 | Kafka | 3.2 - 3.9 |
| 4.7.8 | PostgreSQL | 16 - 17 |
| 4.7.8 | OracleDB | 19c, 21c, 23ai |
| 4.7.8 | MongoDB | 7 - 8 |
| 4.7.8 | Redis | 7.2 - 8.0 |
| 4.7.8 | Elasticsearch | 7 - 8 |
| 4.7.8 | Angular (Web SDK) | 19.x |
| 4.7.8 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.8 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes\
✅ Support for [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title

### Support for Substitution Tags in Table column title

Now you can use [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title.

## Bug fixes

> [accordion] \[UI Designer] Card expansion state not calculated correctly
>
> Resolved an issue where, in certain situations, the expanded state of cards was not calculated correctly. This prevented users from expanding cards as expected.

> [accordion] \[UI Designer] Document preview component texts not translated
>
> Fixed localization issue where document preview component texts remained in English regardless of the selected language setting.

> [accordion] \[Designer] Groups tab fails to load with Keycloak 26.3
>
> Fixed compatibility issue with Keycloak 26.3 where the Groups tab would remain in loading state indefinitely due to new "description" field in group representations.

> [accordion] \[CMS] Import fails for PDF files with null thumbnail path
>
> Fixed import failure when PDF media files were exported with null `thumbnailStoragePath` values, preventing successful deployment of build or app versions to fresh environments.

> [accordion] \[Runtime Manager] Improved error logging for proxy failures
>
> Enhanced error logging detail when Runtime Manager proxy requests fail, providing better root cause information for debugging infrastructure issues like DNS problems or service unavailability.

> [accordion] \[Integration Designer] Slow performance on first workflow execution after pod restart
>
> Fixed performance issue where workflow IF node processing time increased from 3-5 seconds to 15-20 seconds on the first execution after Integration Designer pod restart.

> [accordion] \[Process Engine] Active step was incorrectly computed when the token is reset
>
> Fixed issue where the active step was incorrectly computed when the token is reset.


# Deployment guidelines v4.7.9
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/deployment-guidelines-v4.7.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.1** | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.4** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.1** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.1** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.1** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.2** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.30** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.26** | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.23** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.9 | Keycloak | 22, 26+ |
| 4.7.9 | Kafka | 3.2 - 3.9 |
| 4.7.9 | PostgreSQL | 16 - 17 |
| 4.7.9 | OracleDB | 19c, 21c, 23ai |
| 4.7.9 | MongoDB | 7 - 8 |
| 4.7.9 | Redis | 7.2 - 8.0 |
| 4.7.9 | Elasticsearch | 7 - 8 |
| 4.7.9 | Angular (Web SDK) | 19.x |
| 4.7.9 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.9 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes and security improvements\
✅ Support for dynamic keys in [**Link component**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/typography#link) URL property across all platforms\
✅ Added property on View for enabling or disabling row selection in tasks table

### Support for dynamic keys in Link component URL property

You can now use dynamic keys in the Link component's URL property across all platforms (Web, iOS, and Android). This enhancement allows you to dynamically construct URLs using process data, enabling more flexible navigation patterns in your applications.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)

### Task Manager rowSelection property on view

A new "Enable row selection" property has been added to Task Manager views, enabling you to control row selection behavior in task tables.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enable_row_select.png)

## Bug fixes

> [accordion] \[Designer] Merge fails if one branch contains past merges
>
> Fixed an issue where merging branches that contain multiple past merge commits would fail with an error. The merge conflict resolution now properly handles complex merge histories when adding values to enumerations or making other configuration changes.

> [accordion] \[CMS] Enumerations retrieve content endpoint should return content from dependencies
>
> Resolved an issue where the CMS enumerations Kafka endpoint only returned content from the local project and not from library dependencies. The endpoint now correctly retrieves enumeration content from both the current project and all dependency libraries.

> [accordion] \[Task Manager] Table doesn't use the current language
>
> Fixed localization issue in Task Manager where table content wasn't respecting the current language setting. Task Manager tables now properly use the selected language for all displayed content.

> [accordion] \[UI Designer]\[Angular]\[React] Modal fixed height is not applied
>
> Resolved an issue where setting a modal's height to "fixed" would not apply correctly in Angular and React renderers. Fixed height configuration now works as expected for modal components.

> [accordion] \[UI Designer]\[Angular] Fixed container should use overflow-y auto instead of scroll
>
> Fixed styling issue where fixed-height containers incorrectly used `overflow-y: scroll` instead of `overflow-y: auto`. Containers now only show scrollbars when content exceeds the container height.


# Deployment guidelines v5.0.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/deployment-guidelines-v5.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.29.2** | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.25.2** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.21.2** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.14.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.17.2** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.14.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.12.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.15.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.11.0** | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.26.2** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.11.0** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.14.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.11.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | |

### Embedded components

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **SpiceDB** | **1.42.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **DGraph** | **25.0.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

### Renderers

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.3** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.0.12** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.0.0 | Keycloak | 26+ |
| 5.0.0 | Kafka | 3.8 - 3.9 |
| 5.0.0 | PostgreSQL | 16 - 17 |
| 5.0.0 | Oracle Database | 21c, 23ai |
| 5.0.0 | MongoDB | 7 - 8 |
| 5.0.0 | Redis | 7.4 - 8.0 |
| 5.0.0 | Elasticsearch | 8 - 9 |
| 5.0.0 | Angular (Web SDK) | 19.x |
| 5.0.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/configuration-and-migration

This section contains the steps in the order we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](../../../../5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The Authorization System will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

> [!NOTE]
>
> The admin user imported here is the same service account referenced in the migration prerequisites. If you followed the prerequisites page and set up the admin Keycloak user beforehand, the Authorization System will pick it up automatically during this step — no additional action is needed.

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from Application Manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.0.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | 🆕 Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Kafka Configuration

> [!NOTE]
>
> Consumer group naming standardized to kebab-case across all FlowX.AI services with new messaging features for enhanced functionality.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group naming changes

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
> | | |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Application Manager specific features

#### New environment variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | 🆕 Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | 🆕 Maximum HTTP request header size |

#### New Kafka features

> [card] Resource Update Propagation
>
> Consumer Group: `app-resource-update-propagation-group`\
> Threads: 3\
> Topic: `ai.flowx.{env}.application-version.resource.update.propagation.v1`

> [card] Build Runtime Data
>
> Consumer Group: `build-runtime-data-group`\
> Threads: 2\
> Topic: `ai.flowx.{env}.build.runtime-data.v1`

> [card] Business Rule Sync
>
> Topic: `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> Purpose: Business rule synchronization

> [card] Process Sync (Restructured)
>
> Topic: `ai.flowx.{env}.application-version.sync.process.in.v1`\
> Purpose: Enhanced process synchronization

> [card] Reusable Templates sync
>
> Topic: `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> Purpose: Reusable template synchronization

#### Kafka environment variables (optional overrides)

```bash New Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_RESOURCEUPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Business Rule Sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1

# Process Sync (restructured)
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1


# Reusable Templates sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1
```

```bash Consumer Groups theme={"dark"}
# New Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
```

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides.

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | 🆕 Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | 🆕 Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | 🆕 S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | 🆕 S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | 🆕 S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | 🆕 S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | 🆕 S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | 🆕 S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | 🆕 Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | 🆕 Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | 🆕 Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | 🆕 Redis host |
| `SPRING_REDIS_PORT` | `6379` | 🆕 Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | 🆕 Redis password |
| `SPRING_REDIS_TTL` | `5000000` | 🆕 Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | 🆕 Redis host |

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/install-services

Step-by-step installation guide for new FlowX.AI 5.0 services

FlowX.AI 5.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](/5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](/5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.6 (or newer) to 5.0.0. If you’re on an earlier version, upgrade to the latest LTS version first.

## Success factors

> [!WARNING]
>
> The following steps are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB** must be installed before any FlowX.AI services. **DGraph** is only required if you are using FlowX AI agents — if not, you can skip DGraph installation, but SpiceDB is still mandatory.
>
> > [!NOTE]
> >
> > Only DGraph can be skipped (and only if you are not using FlowX AI agents). SpiceDB is mandatory for all deployments.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices migration** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](/5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites

This section contains the steps in the order we recommend for migrating data from FlowX v4.7.x to v5.0.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.6 | FlowX.AI 5.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.0#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip installing DGraph. SpiceDB is still mandatory.

> [card] [SpiceDB setup guide](../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.0.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

Before upgrading to FlowX.AI 5.0, you must run two operations on all existing Elasticsearch indices:

1. **Update index mappings** to include the `workspaceId` field (schema change)
2. **Migrate existing documents** to assign them to the default workspace (data migration)

These operations are required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable; if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

> [!WARNING]
>
> If Elasticsearch migration is not completed correctly, some process instances may not appear in search results, data-search features might return incomplete results, and workspace-scoped queries will fail for unmigrated data. Existing resources will also not be visible or accessible within the new workspace structure.

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.0.0.

***

## Authorization System Prerequisites

Before deploying the `authorization-system` service, you must configure the organization admin user. This is a critical prerequisite for ensuring that the authentication and user management features function correctly post-upgrade.

### Steps to Configure the Organization Admin User

Follow these guides to correctly set up the organization admin user:

> [card] [Bootstrap Organization Admin](../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Organization Admin Roles & Workspace Access](../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

> [!TIP]
>
> Configuration of the organization admin user must be completed **before** deploying the authorization-system service (see the [Install Services](./install-services) section for service deployment steps).

### Pre-migration preparation

Required configuration for the authorization-system service:

* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE`= `true` (mandatory for migrations)
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME`= `<admin-username>` (recommended method, default: `admin@flowx.ai`)

The system will search for this username in Keycloak and automatically copy the user's subject ID to the authorization-system database.

**Fallback method:** If the username method fails or you prefer to specify the subject ID directly:

* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID`= `<subject-id-of-admin-user>`

> [!TIP]
>
> To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.

![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users"
    ]
  }
}
```


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.06.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.0") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.0 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.0 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.0 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.0 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.0 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# FlowX.AI 5.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025

Latest features, improvements, and bug fixes in our newest release

> [!WARNING]
>
> This release includes the following features in Tech Preview. We encourage you to try them out and share your feedback to help us improve them. Please note that Tech Preview features may change before final release.

> [tab] What's New
>
> **What's new? 🆕**
>
> 🆕 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture)\
> 🆕 [**Project Data Model (PDM)**](#project-data-model-pdm)\
> 🆕 [**FlowX.AI Database**](#flowx-ai-database)\
> 🆕 [**Multi Select UI Component**](#multi-select-ui-component)\
> 🆕 [**Library-to-Library Dependencies**](#library-to-library-dependencies)\
> 🆕 [**Data Mappers**](#data-mappers)\
> 🆕 [**Reusable Resources**](#reusable-resources)\
> 🆕 [**Files in Integration Designer**](#files-in-integration-designer)\
> 🆕 [**Rendering improvements**](#rendering-improvements)
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Major Infrastructure Changes**: Workspaces introduces SpiceDB integration and new database schemas for multi-tenant architecture.
> > >
> > > **Key Changes:**
> > >
> > > * **SpiceDB Integration**: New permission management system requiring deployment
> > >
> > > * **Database Migration**: Schema updates for workspace support
> > >
> > > * **User Storage**: Only information about FlowX.AI Designer users is stored in FlowX.AI. The stored user data is limited to: unique identifier, username, first name, last name, and email address.
> > >
> > > * **Default Workspace**: All the projects and libraries are migrated to default workspace
> > >
> > > > [!TIP]
> > > >
> > > > **Backward Compatibility**: All existing functionality preserved in default workspace
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Login Flow**: After authentication, select your workspace before accessing FlowX.AI Designer. Once inside a workspace, everything works as before.
> > >
> > > **What's New:**
> > >
> > > * **Workspace Selection**: Choose workspace after login
> > > * **Resource Isolation**: Projects, libraries, themes are workspace-specific
> > > * **Enhanced Permissions**: Fine-grained access control with user groups and ACLs
> > > * **Workspace Management**: Create and manage workspaces (admin users)
> > >
> > > **What Stays the Same:**
> > >
> > > * Process design and configuration
> > > * UI Designer capabilities
> > > * Integration patterns
> > > * All existing FlowX.AI Designer features
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Transformation**: Workspaces enables enterprise multi-tenant architecture with independent business unit governance while sharing platform capabilities.
> > >
> > > **Business Impact:**
> > >
> > > * **Faster time-to-market** for new business verticals
> > > * **Enhanced compliance** with workspace-specific controls
> > > * **Improved governance** with fine-grained access management
> > >
> > > **Enterprise Benefits:**
> > >
> > > * Business unit autonomy with shared platform
> > > * Regulatory compliance through data isolation
> > > * Centralized upgrades and maintenance
> > > * Cross-business unit resource sharing when appropriate
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Infrastructure Impact**: PDM has minimal infrastructure impact - it's a design-time feature that improves development efficiency without affecting runtime resources.
> > >
> > > > [!TIP]
> > > >
> > > > **No deployment changes required** - PDM is part of the design platform, not runtime
> > >
> > > > [!TIP]
> > > >
> > > > **Backward compatible** - Existing processes continue to work unchanged
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer**: Define data types once at project level, use everywhere. No more recreating Customer or Order objects in every process.
> > >
> > > **How to Use PDM:**
> > >
> > > 1. Navigate to Project → Config → Data Model
> > > 2. Define your business entities (Customer, Product, etc.)
> > > 3. Set governance rules (sensitive data, reporting)
> > > 4. Use these types in any process within the project
> > >
> > > **Best Practices:**
> > >
> > > * Start with core business entities
> > > * Use clear, consistent naming
> > > * Mark sensitive fields appropriately
> > > * Leverage library data types when available
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: PDM transforms how your organization manages business data definitions. Define business entities once and ensure consistency across all processes and teams.
> > >
> > > **Business Benefits:**
> > >
> > > * **Enhanced compliance** through centralized governance and data sensitivity controls
> > > * **Reduced errors** from consistent data definitions
> > >
> > > **ROI Indicators:**
> > >
> > > * Development Efficiency: Measure reduction in process creation time
> > > * Error Reduction: Track fewer data-related production issues
> > > * Maintenance Cost: Monitor time spent on data structure updates
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Infrastructure Planning Required**: FlowX.AI Database creates additional MongoDB collections and requires infrastructure planning for storage, monitoring, and backup procedures.
> > >
> > > > [!TIP]
> > > >
> > > > New microservice: NoSQL DB Runner. Check the [setup guide](/5.1/setup-guides/nosql-db-runner) for more details.
> > >
> > > **Key Considerations:**
> > >
> > > * **Storage Planning**: Monitor usage as processes adopt internal database (plan for 20-30% increase)
> > > * **Performance Monitoring**: Set up alerts for FlowX.AI Database query performance
> > > * **Backup Strategy**: Include FlowX.AI Database collections in backup procedures
> > > * **Connection Pooling**: Additional connection pools for database operations
> > > * **Memory**: Additional 256MB-512MB per FlowX.AI instance for database operations
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Integration Option**: FlowX.AI Database appears as a new Data Source type in Integration Designer, right alongside RESTful System.
> > >
> > > **When to Use FlowX.AI Database:**
> > >
> > > * Customer data lookup across processes
> > > * Shared configuration and reference data
> > > * Process-to-process communication
> > > * Caching frequently accessed data
> > > * Temporary operational data storage
> > >
> > > **How to Implement:**
> > >
> > > 1. Add Data Source node to your process
> > >
> > > 2. Select "FlowX.AI Database" as type
> > >
> > > 3. Configure collection and operations
> > >
> > > 4. Use familiar MongoDB syntax (find, insert, update)
> > >
> > > > [!WARNING]
> > > >
> > > > **When NOT to Use**: Don't replace your core business systems. FlowX.AI Database is perfect for operational data, caching, and inter-process communication - but your CRM, ERP, and other systems of record should remain your primary data sources.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: FlowX.AI Database enables new operational patterns that were previously complex or impossible. It's not about replacing your core systems, but about enabling new ways to orchestrate business processes.
> > >
> > > **New Business Capabilities:**
> > >
> > > * **Cross-process workflows**: Loan application → Credit check → Approval across different process instances
> > > * **Real-time dashboards**: Operational data for business monitoring without system integration
> > > * **Agile experimentation**: Test new business rules without impacting core systems
> > > * **Process orchestration**: Complex business flows spanning multiple departments
> > >
> > > **ROI Considerations:**
> > >
> > > * **Time to Market**: Faster implementation of new business processes
> > > * **Agility**: Rapid prototyping and testing of business ideas
> > >
> > > **Use FlowX.AI Database when:**
> > >
> > > * Data is operational and process-specific (not master data)
> > > * You need rapid implementation without IT system changes
> > > * Process instances need to communicate with each other
> > > * You're prototyping new business capabilities
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **No Infrastructure Impact**: Multi Select is a pure UI component with no backend requirements. It works with existing form handling and data storage mechanisms.
> > >
> > > > [!TIP]
> > > >
> > > > **Zero deployment overhead** - Component is part of the UI framework upgrade
> > >
> > > > [!TIP]
> > > >
> > > > **Existing data handling** - Uses standard array storage, no schema changes needed
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Easy Integration**: Multi Select works just like other form elements in UI Designer. Drag, drop, configure - no new learning curve required.
> > >
> > > **Common Use Cases:**
> > >
> > > 1. **Skills Selection**: Job applications, team member profiles, contractor skills
> > > 2. **Product Features**: Insurance coverage options, software licensing features
> > > 3. **Categories & Tags**: Document classification, customer segmentation
> > >
> > > **Key Configuration:**
> > >
> > > * **Max selections**: Control input limits
> > > * **Display format**: Chips, lists, custom
> > > * **Search**: Filter large option sets
> > > * **Clear all**: Easy reset functionality
> > > * **Validation**: Min/max rules
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **User Experience Impact**: Multi Select eliminates user frustration in scenarios where single selection doesn't match real-world needs. This improves data quality and user satisfaction.
> > >
> > > **Before vs After:**
> > >
> > > * ❌ **Before**: "I can only select one skill, but I have multiple certifications"
> > > * ✅ **After**: "Perfect! I can select all my relevant skills at once"
> > >
> > > **Business Process Examples:**
> > >
> > > * **Employee Onboarding**: Select multiple skills, certifications, department access
> > >
> > > * **Product Configuration**: Select multiple features, add-ons, support packages
> > >
> > > * **Customer Preferences**: Select multiple communication channels, product interests
> > >
> > > > [!TIP]
> > > >
> > > > **Analytics Benefit**: Multi-select data provides richer analytics. Instead of knowing a customer chose "Primary Interest: Technology," you know they selected "AI, Cloud Computing, Cybersecurity, Mobile Development" - much more actionable for business intelligence.
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backwards Compatibility**: FlowX.AI 5.0 maintains full backwards compatibility with existing project-to-library dependencies from FlowX.AI 4.x. All existing dependencies will continue to work without modification.
> > >
> > > **Upgrade Process:**
> > >
> > > 1. **Existing dependencies** will be automatically migrated
> > >
> > > 2. **New library dependency features** become available immediately
> > >
> > > 3. **No breaking changes** to existing functionality
> > >
> > > 4. **Enhanced validation** may catch previously undetected issues
> > >
> > > > [!WARNING]
> > > >
> > > > **Post-Migration Required**: After the lib2lib migration is executed, you must clear the cache. This is necessary because a new field is added to the build mongo document.
> > >
> > > **Cache Clearing Steps:**
> > >
> > > 1. Complete the lib2lib migration process
> > > 2. Clear the application cache to ensure the new build document fields are properly recognized
> > > 3. Verify that library-to-library dependencies are functioning correctly
> > >
> > > **Key Changes:**
> > >
> > > * **Build Export Changes**: Build exports now automatically include entire dependency trees (larger packages but self-contained)
> > > * **Dependency Validation**: Build process now checks for dependency conflicts (enhanced validation may catch previously undetected issues)
> > > * **Deployment Consistency**: Single-version constraint prevents runtime conflicts (more predictable deployments)
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Enhanced Organization**: You can now create more sophisticated library structures where specialized libraries build upon common foundations. This reduces duplication and improves consistency.
> > >
> > > **How It Works:**
> > >
> > > 1. Navigate to Library → Config → Dependencies
> > > 2. Add other libraries as dependencies
> > > 3. FlowX.AI validates for conflicts automatically
> > > 4. Resources from all dependency levels become available
> > >
> > > **Best Practices:**
> > >
> > > * Plan your library hierarchy before implementation
> > >
> > > * Keep dependencies focused and purposeful
> > >
> > > * Avoid circular dependencies
> > >
> > > * Use semantic versioning consistently
> > >
> > > * Document dependency relationships clearly
> > >
> > > > [!NOTE]
> > > >
> > > > **Example**: Create a "US Banking Library" that depends on "Global Banking Library" and "US Compliance Library". This way, US-specific processes get both global banking functionality and local compliance requirements automatically.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Enterprise Architecture**: Library-to-Library Dependencies enable sophisticated organizational structures where different teams can own specific business domains while building on shared foundations.
> > >
> > > **Enterprise Use Cases:**
> > >
> > > **Multi-Country Operations:**
> > > Global Insurance Company: US-specific library depends on Global Compliance library
> > >
> > > ```
> > > US Insurance Library → Global Compliance Library → Base Insurance Library
> > > ```
> > >
> > > **Product Line Specialization:**
> > > Bank: Mortgage processes use specialized libraries that extend common banking operations
> > >
> > > ```
> > > Mortgage Library → Lending Library → Core Banking Library
> > > ```
> > >
> > > **Business Impact:**
> > >
> > > * **Team Autonomy**: Teams work independently while leveraging shared assets
> > >
> > > * **Faster Innovation**: New products build on proven foundation components
> > >
> > > * **Risk Reduction**: Tested, validated components reduce implementation risk
> > >
> > > > [!WARNING]
> > > >
> > > > **Change Management**: This capability requires coordination between teams. Establish clear ownership models, communication protocols, and upgrade procedures before implementing complex dependency hierarchies.
>
> ***
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **Zero Infrastructure Impact**: Data Mappers is a design-time feature that enhances the FlowX.AI Designer interface without requiring additional infrastructure or deployment changes.
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backward Compatibility**: All existing data transfer mechanisms (like `append to parent process` or `output.[outputKey]`) continue to work unchanged. Teams can adopt Data Mappers at their own pace.
> > >
> > > **Key Points:**
> > >
> > > * **No new microservices** - Enhancement to existing designer interface
> > > * **No runtime changes** - Data mapping occurs at design time
> > > * **Existing configurations preserved** - Zero impact on current implementations
> > > * **Optional adoption** - Teams choose when and where to use new functionality
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer for Integration**: No more complex syntax for data transfers. Visual drag-and-drop interface makes component integration intuitive and error-free.
> > >
> > > **How to Use Data Mappers:**
> > >
> > > 1. **Define Parameters**: Set input/output parameters on Start/End nodes
> > > 2. **Choose Implementation**: Select "Data Mapper" or "Current" method
> > > 3. **Visual Mapping**: Drag source parameters to destination parameters
> > > 4. **Save Configuration**: Store mappings for reuse and maintenance
> > >
> > > **When to Use:**
> > >
> > > * **Call Activities**: Passing data between parent and child processes
> > >
> > > * **Integration Workflows**: Connecting with external systems
> > >
> > > * **Complex Data Flows**: When visual mapping improves clarity
> > >
> > > * **Team Collaboration**: When multiple people work on integration logic
> > >
> > > > [!WARNING]
> > > >
> > > > **Parameter Changes**: When you modify input/output parameters, existing mappings must be manually updated. Changes don't automatically propagate to avoid unintended data flow modifications.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: Data Mappers transforms technical integration tasks into visual, business-friendly workflows. Non-technical stakeholders can now understand and validate data flows between business processes.
> > >
> > > **Business Impact:**
> > >
> > > * **Reduced Errors**: Visual mapping prevents data integration mistakes that cause process failures
> > > * **Faster Development**: Intuitive interface accelerates process configuration and testing
> > > * **Better Documentation**: Visual data flows serve as living documentation of business logic
> > > * **Team Collaboration**: Business and technical teams can discuss data flows using the same visual interface
> > >
> > > **ROI Indicators:**
> > >
> > > * **Development Speed**: Measure reduction in integration configuration time
> > > * **Error Rate**: Track fewer data-related production issues
> > > * **Team Efficiency**: Monitor cross-functional collaboration improvements
> > > * **Process Quality**: Assess improvement in first-time-right deployments
> > >
> > > **Use Cases by Industry:**
> > >
> > > * **Banking**: Loan application data flowing from customer intake → credit check → approval process
> > > * **Insurance**: Claim data mapping from initial report → investigation → settlement
> > > * **Manufacturing**: Order data flowing from sales → production planning → fulfillment
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Minimal Infrastructure Impact**: Reusable Resources is primarily a design-time enhancement that leverages existing FlowX infrastructure with minimal additional overhead.
> > >
> > > **Infrastructure Considerations:**
> > >
> > > * **Execution Context**: Functions execute within existing process engine contexts - no additional runtime infrastructure required
> > >
> > > > [!TIP]
> > > >
> > > > **No New Microservices**: Features are integrated into existing FlowX.AI platform components
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Development Game Changer**: Access the new "Reusable Resources" section in FlowX.AI Designer - located alongside "Reusable Functions" - to eliminate 60-80% of repetitive development work.
> > >
> > > **Key Capabilities:**
> > >
> > > * **Data Model Support**: Full integration with Project Data Model (PDM)
> > > * **Action Scenarios**: Template-defined actions assigned during instantiation OR form-centric actions handled by User Task
> > > * **Omnichannel**: Templates work across web, mobile, and other channels
> > >
> > > **Best Practices:**
> > >
> > > * **Start with common patterns**: Identify frequently repeated business logic and UI components
> > > * **Test thoroughly**: Use interactive testing for functions and preview mode for templates
> > > * **Document usage**: Include clear descriptions and example use cases
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Revolutionary Business Impact**: Reusable Resources fundamentally changes how organizations approach process development, transforming from "build every time" to "build once, leverage everywhere."
> > >
> > > **Strategic Business Value:**
> > >
> > > * **Quality Assurance**: Dramatic reduction in defects through reusable, tested components
> > > * **Maintenance Efficiency**: Update business rules once to instantly affect all processes
> > > * **Team Productivity**: Developers focus on new business capabilities instead of repetitive development
> > > * **Consistency**: Ensure uniform business rules and user experience across all touchpoints
> > >
> > > **Industry Use Cases:**
> > >
> > > * **Functions**: KYC validation, credit scoring, fraud detection, regulatory compliance checks
> > >
> > > * **UI Templates**: Customer onboarding forms, document upload sections, account summary dashboards, loan application interfaces
> > >
> > > * **Functions**: Premium calculations, risk evaluation, claims processing, policy validation
> > >
> > > * **UI Templates**: Quote request forms, claims submission interfaces, policy comparison tables, agent dashboards
> > >
> > > * **Functions**: Patient eligibility checks, treatment authorization, billing calculations, compliance validation
> > >
> > > * **UI Templates**: Patient registration forms, appointment scheduling interfaces, medical history cards, provider dashboards
>
> ### **Files in Integration Designer**
>
> > [card] File Handling in Integration Designer
> >
> > FlowX.AI 5.0 introduces native file handling capabilities in Integration Designer, enabling seamless file uploads and downloads with external systems directly within your integration workflows.
> >
> > > [card] Download Files
> > >
> > > Call external APIs and receive files in the response. Integration Designer saves files to Document Plugin or S3 and returns paths for further processing.
> >
> > > [card] Upload Files
> > >
> > > Send files stored in Document Plugin or S3 to external APIs via multipart/form-data or single binary requests.
> >
> > > [card] Multiple Formats
> > >
> > > Support for JSON responses with Base64 encoded files and single binary responses with automatic file identification.
> >
> > > [card] Flexible Storage
> > >
> > > Configure file destinations to Document Plugin (process-linked) or S3 Protocol (custom buckets) based on your needs.
> >
> > [Learn more about File Handling in Integration Designer](../../../5.1/docs/platform-deep-dive/integrations/integration-designer#file-handling)
> >
> > New Feature
>
> ### **Rendering Improvements**
>
> > [card] UI/UX Enhancements
> >
> > > [tab] Grid & Layout Improvements
> > >
> > > > [card] Enhanced Grid Component
> > > >
> > > > Improved performance, responsiveness, and customization options for data display and form organization
> > >
> > > > [card] Navigation Areas Redesign
> > > >
> > > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> > >
> > > > [card] Multi Actions Support
> > > >
> > > > Batch operations support for UI components, enabling simultaneous actions on multiple elements
> > >
> > > > [card] Permission-Based UI Editing
> > > >
> > > > Granular control over UI element editing based on user permissions with partial editing capabilities
> >
> > > [tab] Enhanced Form Controls
> > >
> > > > [card] Input Type Code
> > > >
> > > > Specialized input component for code entry
> > >
> > > > [card] Formatting Options
> > > >
> > > > Advanced formatting capabilities for Input and Slider components
> > >
> > > > [card] Switch Variants
> > > >
> > > > Enhanced switch component supporting both toggle and checkbox variants
> > >
> > > > [card] Disabled Options on Selectors
> > > >
> > > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > > [tab] Advanced Features
> > >
> > > > [card] Custom Loader
> > > >
> > > > Configurable loading indicators for improved user experience during data operations
> > >
> > > > [card] Custom Validators
> > > >
> > > > Advanced validation logic using dynamic computed expressions
> > >
> > > > [card] File Upload Button Type
> > > >
> > > > New specialized button variant designed for file upload operations
> > >
> > > > [card] Copy Styles
> > > >
> > > > Efficiently replicate styling across multiple UI components
> >
> > > [tab] Analytics & Process
> > >
> > > > [card] Analytics Enhancements
> > > >
> > > > Custom payload support for detailed user interaction tracking and business intelligence
> > >
> > > > [card] Process End Handling
> > > >
> > > > Improved user experience when processes complete or terminate
> > >
> > > > [card] Forms in Collections
> > > >
> > > > Enhanced support for form elements within collection components
> > >
> > > > [card] Template Management
> > > >
> > > > Streamlined template organization by consolidating functionality in Reusable Resources

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.0](./deployment-guidelines-v5.0)
> >
> > Instructions for deploying FlowX.AI 5.0.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.0/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.0.0


# Deployment guidelines v5.1.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.1 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.0 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.0 → 5.1.1**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.64.3** | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **9.66.5** | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **9.36.3** | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **9.29.1** | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **9.35.1** | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **9.34.2** | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **9.23.1** | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **9.30.1** | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **9.25.1** | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **9.50.0** | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **9.22.1** | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **9.34.2** | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **9.22.1** | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Renderers

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **9.0.5** | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **9.0.3** | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.0 | 0.2.4 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.5** | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.1 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.0 processes and configurations

### What's included in 5.1.1

This maintenance release includes:

* **WCAG 2.1 Level AA compliance** across all web components (28 improvements)
* **3 customer-reported issue fixes** for production environments
* **62 proactive quality improvements** identified through internal testing
* **Platform enhancements** for SSE handling, CMS tags, and infrastructure

For detailed information on all changes, see the [FlowX.AI 5.1.1 Release Notes](./v5.1.1-november-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.1 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.1 | PostgreSQL | 16 - 17 |
| 5.1.1 | Oracle Database | 21c, 23ai |
| 5.1.1 | MongoDB | 7 - 8 |
| 5.1.1 | Redis | 7.4 - 8.0 |
| 5.1.1 | Elasticsearch | 8 |
| 5.1.1 | Angular (Web SDK) | 19.x |
| 5.1.1 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.2 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.1 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.1 → 5.1.2**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **process-engine** | **9.67.0** | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **9.68.1** | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **9.39.0** | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **9.28.1** | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **9.29.0** | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **9.32.0** | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **9.37.1** | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **9.25.1** | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **9.33.0** | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **9.28.0** | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **9.52.1** | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **9.26.0** | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **9.24.1** | 9.22.1 | 9.21.0 | 9.11.0 |

### Renderers

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **9.0.7** | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **9.0.5** | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.0 |

### AI Platform

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.6** | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.2 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.1 processes and configurations

### What's included in 5.1.2

This maintenance release includes:

* **Bug fixes** addressing customer-reported issues
* **Stability improvements** for platform reliability
* **Quality enhancements** identified through internal testing

For detailed information on all changes, see the [FlowX.AI 5.1.2 Release Notes](./v5.1.2-december-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.2 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.2 | PostgreSQL | 16 - 17 |
| 5.1.2 | Oracle Database | 21c, 23ai |
| 5.1.2 | MongoDB | 7 - 8 |
| 5.1.2 | Redis | 7.4 - 8.0 |
| 5.1.2 | Elasticsearch | 8 |
| 5.1.2 | Angular (Web SDK) | 19.x |
| 5.1.2 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.3 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.2 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.2 → 5.1.3**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **process-engine** | **9.70.1** | 9.67.0 | 9.64.3 | 9.63.0 |
| **admin** | **9.70.2** | 9.68.1 | 9.66.5 | 9.65.0 |
| **designer** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **cms-core** | **9.41.1** | 9.39.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **9.30.1** | 9.28.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **9.31.2** | 9.29.0 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **9.34.1** | 9.32.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **9.39.1** | 9.37.1 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **9.38.2** | 9.36.1 | 9.34.2 | 9.33.0 |
| **data-search** | **9.27.1** | 9.25.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **9.35.1** | 9.33.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **9.30.2** | 9.28.0 | 9.25.1 | 9.24.0 |
| **integration-designer** | **9.54.1** | 9.52.1 | 9.50.0 | 9.49.1 |
| **application-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **data-sync** | **9.28.1** | 9.26.0 | 9.22.1 | 9.21.0 |
| **authorization-system** | **9.38.1** | 9.36.1 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **9.26.1** | 9.24.1 | 9.22.1 | 9.21.0 |

### Renderers

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **9.0.8** | 9.0.7 | 9.0.5 | 9.0.4 |
| **Android renderer** | **9.0.6** | 9.0.5 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.7** | 9.2.6 | 9.2.5 | 9.2.4 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.3 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes required\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.2 processes and configurations

### Optional configuration

A new optional environment variable is available for process-engine:

| Variable | Description | Default |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from platform components | Falls back to `KAFKA_TOPIC_PATTERN` |

> [!NOTE]
>
> This allows connectors to use custom topic patterns without affecting other components like document-plugin, data-search, and cms-core that use `ai.flowx.engine.receive.*`.

### What's included in 5.1.3

This maintenance release includes:

* **Security fixes**
* **Bug fixes** addressing customer-reported issues

For detailed information on all changes, see the [FlowX.AI 5.1.3 Release Notes](./v5.1.3-january-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.3 | Keycloak | 26+ |
| 5.1.3 | Kafka | 3.8 - 3.9 |
| 5.1.3 | PostgreSQL | 16 - 17 |
| 5.1.3 | Oracle Database | 21c, 23ai |
| 5.1.3 | MongoDB | 7 - 8 |
| 5.1.3 | Redis | 7.4 - 8.0 |
| 5.1.3 | Elasticsearch | 8 |
| 5.1.3 | Angular (Web SDK) | 19.2 |
| 5.1.3 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.4 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.3 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.3 → 5.1.4**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **process-engine** | **9.72.2** | 9.70.1 | 9.67.0 | 9.64.3 |
| **admin** | **9.72.0** | 9.70.2 | 9.68.1 | 9.66.5 |
| **designer** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **cms-core** | **9.43.1** | 9.41.1 | 9.39.0 | 9.36.3 |
| **scheduler-core** | **9.32.0** | 9.30.1 | 9.28.1 | 9.26.1 |
| **events-gateway** | **9.33.0** | 9.31.2 | 9.29.0 | 9.26.1 |
| **notification-plugin** | **9.36.0** | 9.34.1 | 9.32.0 | 9.29.1 |
| **document-plugin** | **9.41.1** | 9.39.1 | 9.37.1 | 9.35.1 |
| **task-management-plugin** | **9.40.0** | 9.38.2 | 9.36.1 | 9.34.2 |
| **data-search** | **9.29.0** | 9.27.1 | 9.25.1 | 9.23.1 |
| **audit-core** | **9.37.0** | 9.35.1 | 9.33.0 | 9.30.1 |
| **advancing-controller** | **9.32.0** | 9.30.2 | 9.28.0 | 9.25.1 |
| **integration-designer** | **9.56.0** | 9.54.1 | 9.52.1 | 9.50.0 |
| **application-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **runtime-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **data-sync** | **9.30.1** | 9.28.1 | 9.26.0 | 9.22.1 |
| **authorization-system** | **9.40.1** | 9.38.1 | 9.36.1 | 9.34.2 |
| **nosql-db-runner** | **9.28.0** | 9.26.1 | 9.24.1 | 9.22.1 |

### Renderers

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **iOS renderer** | **9.0.9** | 9.0.8 | 9.0.7 | 9.0.5 |
| **Android renderer** | **9.0.7** | 9.0.6 | 9.0.5 | 9.0.3 |

### Plugins

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.8** | 9.2.7 | 9.2.6 | 9.2.5 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.4 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.3 processes and configurations

#### New environment variables (optional)

The following optional environment variables have been added for the **process-engine** to configure config params caching:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120` | process-engine |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache | `500` | process-engine |

> [!NOTE]
>
> These variables are optional. If not configured, the default values will be used. Adjust these values based on how frequently your configuration changes and your memory constraints.
>
> For more details, see [Engine Setup - Config params cache](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).

### What's included in 5.1.4

This maintenance release includes:

* **Security patches** addressing identified vulnerabilities
* **Bug fixes** addressing customer-reported issues
* **Platform improvements** including cache improvements, Kafka environment variable alignment, SSE metrics enhancements, and infrastructure updates

For detailed information on all changes, see the [FlowX.AI 5.1.4 Release Notes](./v5.1.4-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.4 | Keycloak | 26+ |
| 5.1.4 | Kafka | 3.8 - 3.9 |
| 5.1.4 | PostgreSQL | 16 - 17 |
| 5.1.4 | Oracle Database | 21c, 23ai |
| 5.1.4 | MongoDB | 7 - 8 |
| 5.1.4 | Redis | 7.4 - 8.0 |
| 5.1.4 | Elasticsearch | 8 |
| 5.1.4 | Angular (Web SDK) | 19.2 |
| 5.1.4 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.5 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.4 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.4 → 5.1.5**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **process-engine** | **9.72.5** | 9.72.2 | 9.70.1 | 9.67.0 |
| **admin** | **9.72.2** | 9.72.0 | 9.70.2 | 9.68.1 |
| **designer** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **cms-core** | **9.43.3** | 9.43.1 | 9.41.1 | 9.39.0 |
| **scheduler-core** | **9.32.2** | 9.32.0 | 9.30.1 | 9.28.1 |
| **events-gateway** | **9.33.2** | 9.33.0 | 9.31.2 | 9.29.0 |
| **notification-plugin** | **9.36.2** | 9.36.0 | 9.34.1 | 9.32.0 |
| **document-plugin** | **9.41.3** | 9.41.1 | 9.39.1 | 9.37.1 |
| **task-management-plugin** | **9.40.2** | 9.40.0 | 9.38.2 | 9.36.1 |
| **data-search** | **9.29.2** | 9.29.0 | 9.27.1 | 9.25.1 |
| **audit-core** | **9.37.2** | 9.37.0 | 9.35.1 | 9.33.0 |
| **advancing-controller** | **9.32.1** | 9.32.0 | 9.30.2 | 9.28.0 |
| **integration-designer** | **9.56.2** | 9.56.0 | 9.54.1 | 9.52.1 |
| **application-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **runtime-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **data-sync** | **9.30.2** | 9.30.1 | 9.28.1 | 9.26.0 |
| **authorization-system** | **9.40.2** | 9.40.1 | 9.38.1 | 9.36.1 |
| **nosql-db-runner** | **9.28.2** | 9.28.0 | 9.26.1 | 9.24.1 |

### Renderers

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **iOS renderer** | **9.0.10** | 9.0.9 | 9.0.8 | 9.0.7 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.6 | 9.0.5 |

### Plugins

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.9** | 9.2.8 | 9.2.7 | 9.2.6 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.5 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No new environment variables
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.4 processes and configurations

### What's included in 5.1.5

This maintenance release includes:

* **Bug fixes** for process loop rendering issues in the Angular renderer
* **Bug fixes** for subprocess output data not being returned from embedded processes

For detailed information on all changes, see the [FlowX.AI 5.1.5 Release Notes](./v5.1.5-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.5 | Keycloak | 26+ |
| 5.1.5 | Kafka | 3.8 - 3.9 |
| 5.1.5 | PostgreSQL | 16 - 17 |
| 5.1.5 | Oracle Database | 21c, 23ai |
| 5.1.5 | MongoDB | 7 - 8 |
| 5.1.5 | Redis | 7.4 - 8.0 |
| 5.1.5 | Elasticsearch | 8 |
| 5.1.5 | Angular (Web SDK) | 19.2 |
| 5.1.5 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.6 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.5 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.5 → 5.1.6**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **process-engine** | **9.72.7** | 9.72.5 | 9.72.2 | 9.70.1 |
| **admin** | **9.72.4** | 9.72.2 | 9.72.0 | 9.70.2 |
| **designer** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **cms-core** | **9.43.5** | 9.43.3 | 9.43.1 | 9.41.1 |
| **scheduler-core** | **9.32.4** | 9.32.2 | 9.32.0 | 9.30.1 |
| **events-gateway** | **9.33.4** | 9.33.2 | 9.33.0 | 9.31.2 |
| **notification-plugin** | **9.36.4** | 9.36.2 | 9.36.0 | 9.34.1 |
| **document-plugin** | **9.41.5** | 9.41.3 | 9.41.1 | 9.39.1 |
| **task-management-plugin** | **9.40.4** | 9.40.2 | 9.40.0 | 9.38.2 |
| **data-search** | **9.29.4** | 9.29.2 | 9.29.0 | 9.27.1 |
| **audit-core** | **9.37.4** | 9.37.2 | 9.37.0 | 9.35.1 |
| **advancing-controller** | **9.32.3** | 9.32.1 | 9.32.0 | 9.30.2 |
| **integration-designer** | **9.56.3** | 9.56.2 | 9.56.0 | 9.54.1 |
| **application-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **runtime-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **data-sync** | **9.30.4** | 9.30.2 | 9.30.1 | 9.28.1 |
| **authorization-system** | **9.40.3** | 9.40.2 | 9.40.1 | 9.38.1 |
| **nosql-db-runner** | **9.28.4** | 9.28.2 | 9.28.0 | 9.26.1 |

### Renderers

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **iOS renderer** | **9.0.11** | 9.0.10 | 9.0.9 | 9.0.8 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.7 | 9.0.6 |

### Plugins

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.8 | 9.2.7 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.6 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> This release introduces optional environment variables for the process engine retry mechanism. These are not required — defaults work for most deployments.

#### Process engine — retry configuration (optional)

The following optional environment variables configure the exponential backoff with Equal Jitter strategy used for optimistic locking retries:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` | process-engine |

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.5 processes and configurations

### What's included in 5.1.6

This maintenance release includes:

* **Bug fixes** for React renderer: modals, sliders, datepicker, selectors, disabled state, and accessibility
* **Bug fixes** for Angular + React renderer: card accordion height, focus outlines, button icon layout
* **Bug fix** for process engine advancing getting stuck on pod crash
* **Bug fix** for connection leak in application-manager export/import
* **Improvement** for configurable retry mechanism with exponential backoff
* **Security patches** across all platform components

For detailed information on all changes, see the [FlowX.AI 5.1.6 Release Notes](./v5.1.6-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.6 | Keycloak | 26+ |
| 5.1.6 | Kafka | 3.8 - 3.9 |
| 5.1.6 | PostgreSQL | 16 - 17 |
| 5.1.6 | Oracle Database | 21c, 23ai |
| 5.1.6 | MongoDB | 7 - 8 |
| 5.1.6 | Redis | 7.4 - 8.0 |
| 5.1.6 | Elasticsearch | 8 |
| 5.1.6 | Angular (Web SDK) | 19.2 |
| 5.1.6 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.7
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.7 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.6 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.6 → 5.1.7**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **process-engine** | **9.73.1** | 9.72.7 | 9.72.5 | 9.72.2 |
| **admin** | **9.73.1** | 9.72.4 | 9.72.2 | 9.72.0 |
| **designer** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **cms-core** | **9.44.2** | 9.43.5 | 9.43.3 | 9.43.1 |
| **scheduler-core** | **9.33.1** | 9.32.4 | 9.32.2 | 9.32.0 |
| **events-gateway** | **9.34.1** | 9.33.4 | 9.33.2 | 9.33.0 |
| **notification-plugin** | **9.37.1** | 9.36.4 | 9.36.2 | 9.36.0 |
| **document-plugin** | **9.42.2** | 9.41.5 | 9.41.3 | 9.41.1 |
| **task-management-plugin** | **9.41.1** | 9.40.4 | 9.40.2 | 9.40.0 |
| **data-search** | **9.30.1** | 9.29.4 | 9.29.2 | 9.29.0 |
| **audit-core** | **9.38.1** | 9.37.4 | 9.37.2 | 9.37.0 |
| **advancing-controller** | **9.33.1** | 9.32.3 | 9.32.1 | 9.32.0 |
| **integration-designer** | **9.57.1** | 9.56.3 | 9.56.2 | 9.56.0 |
| **application-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **runtime-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **data-sync** | **9.31.1** | 9.30.4 | 9.30.2 | 9.30.1 |
| **authorization-system** | **9.41.1** | 9.40.3 | 9.40.2 | 9.40.1 |
| **nosql-db-runner** | **9.29.1** | 9.28.4 | 9.28.2 | 9.28.0 |

### Renderers

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **iOS renderer** | **9.0.12** | 9.0.11 | 9.0.10 | 9.0.9 |
| **Android renderer** | **9.0.13** | 9.0.7 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI Platform

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.8 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.7 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.6 processes and configurations

### What's included in 5.1.7

This maintenance release includes:

* **Bug fix** for build reimport failures with manifest issues
* **Security patches** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.7 Release Notes](./v5.1.7-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.7 | Keycloak | 26+ |
| 5.1.7 | Kafka | 3.8 - 3.9 |
| 5.1.7 | PostgreSQL | 16 - 17 |
| 5.1.7 | Oracle Database | 21c, 23ai |
| 5.1.7 | MongoDB | 7 - 8 |
| 5.1.7 | Redis | 7.4 - 8.0 |
| 5.1.7 | Elasticsearch | 8 |
| 5.1.7 | Angular (Web SDK) | 19.2 |
| 5.1.7 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.8
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.8 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.7 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.7 → 5.1.8**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **process-engine** | **9.74.4** | 9.73.1 | 9.72.7 | 9.72.5 |
| **admin** | **9.74.4** | 9.73.1 | 9.72.4 | 9.72.2 |
| **designer** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **cms-core** | **9.45.4** | 9.44.2 | 9.43.5 | 9.43.3 |
| **scheduler-core** | **9.34.4** | 9.33.1 | 9.32.4 | 9.32.2 |
| **events-gateway** | **9.35.4** | 9.34.1 | 9.33.4 | 9.33.2 |
| **notification-plugin** | **9.38.4** | 9.37.1 | 9.36.4 | 9.36.2 |
| **document-plugin** | **9.43.4** | 9.42.2 | 9.41.5 | 9.41.3 |
| **task-management-plugin** | **9.42.4** | 9.41.1 | 9.40.4 | 9.40.2 |
| **data-search** | **9.31.4** | 9.30.1 | 9.29.4 | 9.29.2 |
| **audit-core** | **9.39.4** | 9.38.1 | 9.37.4 | 9.37.2 |
| **advancing-controller** | **9.34.4** | 9.33.1 | 9.32.3 | 9.32.1 |
| **integration-designer** | **9.58.5** | 9.57.1 | 9.56.3 | 9.56.2 |
| **application-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **runtime-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **data-sync** | **9.32.3** | 9.31.1 | 9.30.4 | 9.30.2 |
| **authorization-system** | **9.42.4** | 9.41.1 | 9.40.3 | 9.40.2 |
| **nosql-db-runner** | **9.30.4** | 9.29.1 | 9.28.4 | 9.28.2 |

### Renderers

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **iOS renderer** | **9.0.19** | 9.0.12 | 9.0.11 | 9.0.10 |
| **Android renderer** | **9.0.19** | 9.0.13 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.8 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.7 processes and configurations

### What's included in 5.1.8

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.8 Release Notes](./v5.1.8-april-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.8 | Keycloak | 26+ |
| 5.1.8 | Kafka | 3.8 - 3.9 |
| 5.1.8 | PostgreSQL | 16 - 17 |
| 5.1.8 | Oracle Database | 21c, 23ai |
| 5.1.8 | MongoDB | 7 - 8 |
| 5.1.8 | Redis | 7.4 - 8.0 |
| 5.1.8 | Elasticsearch | 8 |
| 5.1.8 | Angular (Web SDK) | 19.2 |
| 5.1.8 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/deployment-guidelines-v5.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.63.0** | 9.29.2 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.65.0** | 9.25.2 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.35.0** | 9.21.2 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.28.0** | 9.14.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.34.0** | 9.17.2 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.33.0** | 9.14.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.22.0** | 9.12.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.29.1** | 9.15.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.24.0** | 9.11.0 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.49.1** | 9.26.2 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.21.0** | 9.11.0 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.33.0** | 9.14.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.21.0** | 9.11.0 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.4** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.2** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | **0.2.4** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.4** | 9.2.3 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.3.1** | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.0 | Keycloak | 26+ |
| 5.1.0 | Kafka | 3.8 - 3.9 |
| 5.1.0 | PostgreSQL | 16 - 17 |
| 5.1.0 | Oracle Database | 21c, 23ai |
| 5.1.0 | MongoDB | 7 - 8 |
| 5.1.0 | Redis | 7.4 - 8.0 |
| 5.1.0 | Elasticsearch | 8 - 9 |
| 5.1.0 | Angular (Web SDK) | 19.x |
| 5.1.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/configuration-and-migration

This section contains the steps in order that we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](/5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.1.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.1.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.1.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The auth-system will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from app-manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Document plugin

> [!NOTE]
>
> New configuration option for test documents bucket customization.

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILE_STORAGE_TEST_FILES_BUCKET` | `-test-documents` | Overrides the default test documents bucket suffix. Use this to configure a custom bucket name for test files. |

> [!NOTE]
>
> This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed.

## Kafka configuration

> [!NOTE]
>
> Complete Kafka migration including consumer group standardization to kebab-case, comprehensive topic restructuring with new versioned naming patterns, and enhanced messaging features across all FlowX.AI services.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group migrations

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Kafka topic migrations

> [!NOTE]
>
> All Kafka topics migrate to versioned naming pattern `ai.flowx.{env}.{service}.{operation}.v1` for improved organization and future compatibility.

> [tab] Application Manager
>
> **Application resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
>
> **Sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS_IN` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE_IN` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE_IN` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN` | `ai.flowx.application-version.sync.out.v1` |
>
> **Resource update propagation:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | `ai.flowx.application-version.resource.update.propagation.v1` |
>
> **Build resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

> [tab] Admin
>
> **Consumer groups:**
>
> | Environment Variable | New Consumer Group | Threads |
> | - | - | - |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_SYNC` | `process-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC` | `business-rule-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC` | `reusable-template-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION` | `processCorrectionAfterAppOperationGroup` | `6` |
>
> **Application sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE` | `ai.flowx.application-version.sync.out.v1` |
> | `KAFKA_TOPIC_APPLICATION_PROCESS_SYNC` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
>
> **Application correction after app operation topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
>
> **Build topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

### New Kafka features

> [card] Resource Update Propagation
>
> **Consumer Group:** `app-resource-update-propagation-group`\
> **Threads:** 3\
> **Topic:** `ai.flowx.{env}.application-version.resource.update.propagation.v1`\
> **Purpose:** Real-time resource change propagation

> [card] Build Runtime Data
>
> **Consumer Group:** `build-runtime-data-group`\
> **Threads:** 2\
> **Topic:** `ai.flowx.{env}.build.runtime-data.v1`\
> **Purpose:** Build process data management

> [card] Business Rule Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> **Purpose:** Enhanced business rule synchronization\
> **Consumer Group:** `business-rule-sync-group`

> [card] Process Sync Enhanced
>
> **Topic:** `ai.flowx.{env}.application-version.sync.process.in.v1`\
> **Purpose:** Improved process synchronization\
> **Consumer Group:** `process-sync-group`

> [card] Reusable Template Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> **Purpose:** Template synchronization\
> **Consumer Group:** `reusable-template-sync-group`

> [card] Correction After App Operation
>
> **Multiple Topics:** Process, business rule, and template correction\
> **Purpose:** Post-deployment resource correction\
> **Consumer Group:** `processCorrectionAfterAppOperationGroup`

### Configure environment variables

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides. Only override when custom naming is required.

```bash Application Manager Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Sync Topics
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
```

```bash Admin Topics theme={"dark"}
# Application Sync
KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE=ai.flowx.dev.application-version.sync.out.v1
KAFKA_TOPIC_APPLICATION_PROCESS_SYNC=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT=ai.flowx.dev.application-version.correction-after-app-operation.response.v1
```

```bash Consumer Groups and Threads theme={"dark"}
# Application Manager Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Admin Consumer Groups  
KAFKA_CONSUMER_GROUPID_PROCESS_SYNC=process-sync-group
KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC=business-rule-sync-group
KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC=reusable-template-sync-group
KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION=processCorrectionAfterAppOperationGroup

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
KAFKA_CONSUMER_THREADS_PROCESS_SYNC=6
KAFKA_CONSUMER_THREADS_BUSINESS_RULE_SYNC=6
KAFKA_CONSUMER_THREADS_REUSABLE_TEMPLATE_SYNC=6
KAFKA_CONSUMER_THREADS_PROCESS_CORRECTIONAFTERAPPOPERATION=6
```

### Additional Application Manager variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | Maximum HTTP request header size |

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | Redis host |
| `SPRING_REDIS_PORT` | `6379` | Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | Redis password |
| `SPRING_REDIS_TTL` | `5000000` | Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | Redis host |

## FlowX Engine

> [!NOTE]
>
> The ADVANCING controller has been redesigned with separate picking and processing operations for improved performance and resource management.

### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.

### Elasticsearch indexing configuration

> [!NOTE]
>
> Elasticsearch indexing environment variables have been updated with new naming conventions for better consistency with FlowX naming standards.

#### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEXING_TYPE` | `FLOWX_INDEXING_TYPE` | `kafka` | `kafka` |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` | `process_instance` |
| `FLOWX_INDEXING_PROCESSINSTANCE_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `FLOWX_INDEXING_PROCESSINSTANCE_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

> [!NOTE]
>
> For complete Elasticsearch indexing setup including Kafka Connect configuration and time-based partitioning, see the [Configuring Elasticsearch indexing](/5.1/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing) guide.

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.

### Development environment exception

> [!NOTE]
>
> For development environments only, `CONFIG_PROFILE` migrates to the standard Spring configuration profile variable.

| Remove This Variable | Replace With | Environment |
| - | - | - |
| `CONFIG_PROFILE` | `SPRING_CONFIG_PROFILE` | devenv only |

## SpiceDB integration

> [!NOTE]
>
> FlowX.AI 5.1 introduces SpiceDB integration for enhanced authorization capabilities across all core services.

### Services affected

The following services require new SpiceDB configuration variables:

* Admin
* Application Manager
* Audit Core
* CMS Core
* Document Plugin
* Integration Designer
* Notification Plugin
* Process Engine
* Runtime Manager
* Task Management Plugin

### New variables to add

For every CAS configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_SPICEDB_TOKEN` | *(secret)* | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Data sync updates

### Data Sync additional variables

For every Data-Sync configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_URL` | - | Authentication system URL. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME` | - | Authentication system username. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` | - | Authentication system password. |
| `FLOWX_SPICEDB_TOKEN` | - | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Kafka topic naming

### Global configuration change

| Variable | Old Default | New Default | Description |
| - | - | - | - |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | (varies) | `""` | Moved to default empty environment |

> [!NOTE]
>
> This change standardizes topic naming across environments by defaulting to an empty environment identifier.

## CORS and ingress updates

> [!WARNING]
>
> All services with Kubernetes ingress configurations now require the `Fx-Workspace-Id` header for workspace identification in multi-tenant environments.

### Standard ingress pattern

FlowX.AI v5.1 introduces a standardized ingress configuration pattern for all services. The key change is adding the `Fx-Workspace-Id` header to the CORS configuration.

**Required annotation update:**

```yaml theme={"dark"}
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
```

### Services requiring updates

All FlowX.AI services that expose ingress endpoints require this update:

| Service | Fx-Workspace-Id Required | Reference |
| - | - | - |
| Admin | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Application Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Audit Core | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Authorization System | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Events Gateway | ❌ No (SSE) | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) |
| Integration Designer | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Process Engine | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Runtime Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Task Management | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |

> [card] [Complete Ingress Configuration Guide](../../../../../5.1/setup-guides/ingress-configuration)
>
> View the complete ingress configuration pattern including:
>
> * Standard template for all services
> * Service-specific paths and rewrite rules
> * Annotation explanations
> * Troubleshooting guide
> * Environment-specific customization

> [!NOTE]
>
> **Exception:** Events Gateway does not require the `Fx-Workspace-Id` header because it handles Server-Sent Events (SSE) with different security requirements. See the [Events Gateway exception](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) section for details.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/install-services

Step-by-step installation guide for new FlowX.AI 5.1.0 services

FlowX.AI 5.1.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](../../../../../5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](../../../../../5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.

> [!WARNING]
>
> **Continuing to 5.9.x?** If 5.1.x is only an intermediate stop on your path to 5.9.x, land on the **latest available 5.1.x patch**, not 5.1.0. Data migrations and their fixes accumulate across the patches of the family, and the latest patch is the level guaranteed to carry all of them. Before starting the next migration, confirm the environment is fully functional: every service up and healthy in **FlowX.AI Designer → Platform Status**, and the data-sync job completed successfully. See the [5.1 → 5.9 migration prerequisites](/5.9/migrating-from-5.1-lts/prerequisites).

## Success factors

> [!WARNING]
>
> Take care when following the steps below are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB and DGraph** must be installed before any FlowX.AI services
>
> > [!NOTE]
> >
> > DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices (data migration)** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration (Elasticsearch indices)

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation

> [card] [Troubleshooting](./troubleshooting)
>
> Common issues and solutions for post-upgrade problems


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/prerequisites

This section contains the steps in order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.8 | FlowX.AI 5.1.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.1#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.1.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip this step.

> [card] [SpiceDB setup guide](../../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.1.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

> [!WARNING]
>
> Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.1.0 to ensure workspace functionality works correctly.

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Prerequisites for migration

Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:

```json theme={"dark"}
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
```

This mapping update is required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable, if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

### Post-migration impact

**Without proper Elasticsearch migration, you will experience:**

* Some process instances may not appear in search results
* Data-search functionality may not return complete results
* Workspace-scoped queries will fail for unmigrated data
* **Existing resources will not be visible or accessible within the new workspace structure**

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.1.0.

***

## Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).

Details on how to configure the organization admin user:

> [card] [Authorization system](../../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Workspaces access rights](../../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

***

#### Pre-migration preparation

You must configure the authorization-system service before migration. There are two supported approaches:

> [tab] Recommended: Use admin email (simpler)
>
> Set the following authorization-system environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=<username-of-admin-user>`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.

> [tab] Alternative: Use admin subject ID
>
> Set the following environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
>
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=<subject-id-of-admin-user>`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).
>
> > [!TIP]
> >
> > To get the subject ID of the admin user, extract it from the JWT token of the admin user.
>
> ![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.1.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users",
      "manage-realm"
    ]
  }
}
```

***

## Process instances migration

All active process instances will be migrated under default workspace.

> [!WARNING]
>
> For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.1.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.2") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.2 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.2 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.2 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.2 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.2 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# Post-upgrade troubleshooting
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/troubleshooting

Common issues and solutions that may occur after upgrading from FlowX v4.7.x to v5.1.0.

This section covers common issues that may occur after completing the upgrade to FlowX.AI 5.1.0 and their solutions.

## Designer login issues

### DataIntegrityViolationException error

If you cannot login to FlowX Designer after the 5.x upgrade and encounter the following error in the authorization-system logs:

```
org.springframework.dao.DataIntegrityViolationException: could not execute statement [ERROR: duplicate key value violates unique constraint "cas_user_username_key"
  Detail: Key (username)=(admin@flowx.ai) already exists.] [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; SQL [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; constraint [cas_user_username_key]
```

**Root Cause**: This error occurs because the `sub` (subject ID) is missing from JWT tokens. Starting with Keycloak version 25, the `sub` claim is not added by default to lightweight access tokens.

**Solution**: Ensure the `basic` Client Scope is created in your Keycloak Realm and added to all FlowX clients.

> [!WARNING]
>
> Since Keycloak version 25, the `sub` claim is not added by default to JWT lightweight tokens. This is a breaking change that affects FlowX.AI authentication.

### How to verify if subject ID is missing

**1. Login attempt**

Try to login to FlowX Designer and note if the login fails.

**2. Capture the token**

1. Open your browser's Developer Tools
2. Navigate to the **Network** tab
3. Attempt to login again
4. Look for a call to: `https://<your-keycloak-address>/auth/realms/flowx/protocol/openid-connect/token`
5. Copy the access token from the response

**3. Decode the token**

1. Go to [https://jwt.io/](https://jwt.io/)
2. Paste the token in the **Encoded** section
3. Check the **Payload** section for the presence of the `sub` claim

> [!TIP]
>
> If the `sub` claim is present, the token should contain a field like: `"sub": "12345678-1234-1234-1234-123456789abc"`

**4. Verify Client Scope configuration**

If the `sub` claim is missing, you need to configure the Client Scope in Keycloak:

1. Login to your Keycloak Admin Console
2. Navigate to your FlowX realm
3. Go to **Client Scopes**
4. Ensure the `basic` client scope exists and includes the `sub` claim
5. Add this client scope to all FlowX clients (FlowX Designer, Admin, etc.)

### Additional resources

> [card] [Keycloak Release Notes](https://www.keycloak.org/docs/latest/release_notes/#lightweight-access-token-to-be-even-more-lightweight)
>
> Official Keycloak documentation about lightweight access token changes

***

## Other common issues

> [!NOTE]
>
> Additional troubleshooting sections will be added as common post-upgrade issues are identified. If you encounter issues not covered here, please consult the FlowX support team.


# FlowX.AI 5.1.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025

Introducing Workspaces, Project Data Model, Library-to-Library Dependencies, Data Mappers, Reusable Resources, and more for a more efficient and flexible development experience.

**What's new? 🆕**

> [tab] Reusability
>
> Build once, use everywhere. These features transform how you develop and maintain applications by eliminating duplication and enabling sophisticated modular architectures.
>
> 🔄 [**Project Data Model (PDM)**](#project-data-model-pdm) - Define reusable data types at the project level to ensure consistency across processes\
> 🔄 [**Library-to-Library Dependencies**](#library-to-library-dependencies) - Create complex dependency trees with multiple levels of library-to-library relationships\
> 🔄 [**Data Mappers**](#data-mappers) - Visual drag-and-drop data mapping with reusable parameter definitions\
> 🔄 [**Reusable Resources**](#reusable-resources) - Create and manage UI Templates and Business Functions across multiple processes\
> 🔄 [**Files in Integration Designer**](#files-in-integration-designer) - Enhanced file management and reusability in integration workflows\
> 🔄 [**Resources Overrides**](#resources-overrides) - Localization and customization of core applications across multiple regions with centralized management\
> 🔄 [**Active Policy Overrides**](#active-policy-overrides) - User-specific and role-specific deployment policies for independent testing and controlled rollouts
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.1.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.1.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> ***
>
> ### **Files in Integration Designer**
>
> > [card] Files in Integration Designer
> >
> > > [tab] Files Overview
> > >
> > > ![Integration Designer file workflows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh.png)
> > >
> > > FlowX.AI 5.1.0 introduces comprehensive file handling capabilities in Integration Designer, resolving previous limitations where sending or receiving documents, photos, or any files via Integration Designer was not supported. This powerful enhancement enables seamless file exchange with external systems through automated workflows.
> >
> > > [tab] Core File Scenarios
> > >
> > > > [card] File Downloads
> > > >
> > > > Process calls external API (GET/POST) and receives files in response. Integration Designer saves files to specified location and returns paths to workflow
> > >
> > > > [card] File Uploads
> > > >
> > > > Process sends files stored in Document Plugin or S3 Bucket to external API via POST request. Workflow transmits file path for seamless transfer
> > >
> > > > [card] Document Plugin Integration
> > > >
> > > > Seamless integration with FlowX.AI Document Plugin for process-specific file management and organization
> > >
> > > > [card] S3 Storage Support
> > > >
> > > > Custom S3 bucket storage for files not tied to specific process instances or when Document Plugin is unavailable
> >
> > > [tab] Enhanced Capabilities
> > >
> > > **1. Automated File Exchange**
> > >
> > > Enable seamless file transfer with external systems without manual handling or complex custom integrations
> > >
> > > **2. Flexible Storage Options**
> > >
> > > Choose between Document Plugin for process-specific files or S3 Protocol for independent file operations
> > >
> > > **3. Workflow Integration**
> > >
> > > Files are automatically integrated into workflow processes with proper path management and metadata handling
> > >
> > > **4. External Service Communication**
> > >
> > > Communicate effectively with document services, AI processing systems, report generators, and CMS platforms
> >
> > > [tab] Real-World Use Cases
> > >
> > > > [accordion] Contract Generation Workflows
> > > >
> > > > **Scenario**: Generate personalized contracts using external document services
> > > >
> > > > * **Process Flow**: Send customer data → External contract service → Receive generated PDF contract
> > > > * **Integration**: Customer information flows to document generation API, completed contracts return to process
> > > > * **Storage**: Generated contracts stored in Document Plugin for process tracking and audit trails
> > > > * **Business Value**: Automated contract creation with legal template compliance and version control
> > >
> > > > [accordion] Document Processing & OCR
> > > >
> > > > **Scenario**: Process uploaded documents through external AI/OCR services
> > > >
> > > > * **Process Flow**: Upload document → AI processing service → Receive extracted data and processed files
> > > > * **Integration**: Documents sent to AI services for text extraction, classification, or compliance validation
> > > > * **Storage**: Processed documents and extracted data stored for business logic processing
> > > > * **Business Value**: Automated document processing with intelligent data extraction capabilities
> > >
> > > > [accordion] Report Generation & Analytics
> > > >
> > > > **Scenario**: Generate business reports using external reporting services
> > > >
> > > > * **Process Flow**: Send business data → Reporting service → Receive formatted reports (PDF, Excel)
> > > > * **Integration**: Business metrics and KPIs sent to specialized reporting engines
> > > > * **Storage**: Generated reports available for download and distribution workflows
> > > > * **Business Value**: Professional report generation with advanced formatting and visualization capabilities
> > >
> > > > [accordion] CMS & Content Management
> > > >
> > > > **Scenario**: Integrate with content management systems for file organization
> > > >
> > > > * **Process Flow**: Upload files → CMS integration → Organize and categorize content
> > > > * **Integration**: Files uploaded to external CMS platforms with metadata and categorization
> > > > * **Storage**: S3 Protocol ideal for CMS integrations with unassociated documents
> > > > * **Business Value**: Centralized content management with automated workflow integration
> >
> > [Learn more about Integration Designer](../../../../5.1/docs/platform-deep-dive/integrations/integration-designer)
> >
> > Major Enhancement
>
> ***
>
> ### **Resources Overrides**
>
> > [card] Resources Overrides
> >
> > > [tab] Resources Overrides Overview
> > >
> > > ![Resources Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
> > >
> > > Resources Overrides enable localization and customization of core business applications across multiple regions while maintaining centralized updates from headquarters. This powerful feature allows organizations to adapt specific business logic, compliance requirements, or local regulations without losing connection to the master application.
> >
> > > [tab] Key Features
> > >
> > > > [card] Localization Control
> > > >
> > > > Customize processes, workflows, and enumerations for different countries or regions while maintaining core functionality
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all resource overrides through the Dependencies page with comprehensive override tracking and configuration
> > >
> > > > [card] Selective Overriding
> > > >
> > > > Override only specific resources that need localization while inheriting all other updates from the main library
> > >
> > > > [card] Export/Import Support
> > > >
> > > > Automatically include override configurations in project exports and imports for seamless environment management
> >
> > > [tab] Business Benefits
> > >
> > > **1. Accelerate Global Expansion**
> > >
> > > Deploy core applications to new regions quickly by overriding only country-specific elements instead of rebuilding from scratch
> > >
> > > **2. Maintain Compliance**
> > >
> > > Adapt business logic and data handling to meet local regulatory requirements while preserving global standards
> > >
> > > **3. Preserve Investment**
> > >
> > > Continue receiving updates and improvements from headquarters without losing local customizations
> > >
> > > **4. Reduce Maintenance Overhead**
> > >
> > > Manage regional variations centrally instead of maintaining completely separate application instances
> >
> > > [tab] Supported Resource Types
> > >
> > > > [card] Process Overrides
> > > >
> > > > Customize business process logic while maintaining input/output compatibility and core workflow structure
> > >
> > > > [card] Workflow Overrides
> > > >
> > > > Replace entire workflow implementations to adapt business rules for local requirements
> > >
> > > > [card] Enumeration Overrides
> > > >
> > > > Localize value lists, dropdown options, and classification systems for regional variations
> > >
> > > > [card] Runtime Resolution
> > > >
> > > > Overrides are resolved dynamically at runtime, ensuring the correct regional version is always used
> >
> > > [tab] Real-World Applications
> > >
> > > > [accordion] Multi-National Banking
> > > >
> > > > **Scenario**: Global bank with country-specific loan approval processes
> > > >
> > > > * **Global Library**: Common loan application workflow with standard validation steps
> > > > * **Country Overrides**: Local credit scoring algorithms, regulatory compliance checks, documentation requirements
> > > > * **Business Value**: Single platform maintenance with automated compliance for each country's banking regulations
> > >
> > > > [accordion] Insurance Operations
> > > >
> > > > **Scenario**: Insurance company operating across different regulatory environments
> > > >
> > > > * **Global Library**: Standard claims processing workflow and policy management
> > > > * **Regional Overrides**: Country-specific coverage types, claim validation rules, regulatory reporting
> > > > * **Business Value**: Consistent global operations with local market adaptation and compliance
> > >
> > > > [accordion] Manufacturing & Supply Chain
> > > >
> > > > **Scenario**: Manufacturing company with different operational requirements per region
> > > >
> > > > * **Global Library**: Core production planning and inventory management processes
> > > > * **Local Overrides**: Regional supplier networks, compliance standards, environmental regulations
> > > > * **Business Value**: Standardized operations with flexibility for local business practices and regulations
> >
> > [Learn more about Resources Overrides](../../../../5.1/docs/projects/resources#resources-overrides)
> >
> > Major Enhancement
>
> ***
>
> ### **Active Policy Overrides**
>
> > [card] Active Policy Overrides
> >
> > > [tab] Active Policy Overrides Overview
> > >
> > > ![Active Policy Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap2.png)
> > >
> > > Active Policy Overrides enable user-specific and role-specific deployment policies that allow independent testing of different builds or branches without affecting the global policy. This powerful feature provides granular control over which project versions different users access in runtime environments.
> >
> > > [tab] Key Features
> > >
> > > > [card] User-Specific Policies
> > > >
> > > > Create individual policy overrides for specific users to test different builds independently
> > >
> > > > [card] Role-Based Overrides
> > > >
> > > > Apply policy overrides to entire roles for team-based testing and deployment strategies
> > >
> > > > [card] Priority-Based Resolution
> > > >
> > > > Handle conflicts when multiple overrides apply using configurable priority systems
> > >
> > > > [card] Real-Time Switching
> > > >
> > > > Switch between different project versions instantly without deployment downtime
> >
> > > [tab] Business Benefits
> > >
> > > **1. Independent Testing**
> > >
> > > Enable QA teams and developers to test different builds simultaneously without interfering with production users
> > >
> > > **2. Controlled Rollouts**
> > >
> > > Gradually deploy new features to specific user groups before full production release
> > >
> > > **3. Emergency Rollback**
> > >
> > > Quickly revert specific users to stable versions during incidents without affecting the entire system
> > >
> > > **4. Branch-Specific Development**
> > >
> > > Allow different teams to work with different development branches in shared environments
> >
> > > [tab] Override Management
> > >
> > > > [card] Policy Types
> > > >
> > > > Support for both "Latest on Branch" and specific "Build" policies with flexible branch and version selection
> > >
> > > > [card] Search & Filter
> > > >
> > > > Real-time search functionality to quickly locate specific user or role overrides
> > >
> > > > [card] Activation Control
> > > >
> > > > Enable or disable overrides without deletion for temporary testing scenarios
> > >
> > > > [card] Conflict Resolution
> > > >
> > > > Clear hierarchy: User overrides > Role overrides > Global policy with priority-based resolution
> >
> > > [tab] Real-World Scenarios
> > >
> > > > [accordion] Development Team Testing
> > > >
> > > > **Scenario**: Frontend team needs to test with latest UI changes while backend team tests API updates
> > > >
> > > > * **Override Setup**: Create role-based overrides for "Frontend Developers" and "Backend Developers"
> > > > * **Policy Configuration**: Frontend role uses latest on `ui-redesign` branch, Backend role uses `api-v2` branch
> > > > * **Business Value**: Parallel development with isolated testing environments and no cross-team interference
> > >
> > > > [accordion] Gradual Feature Rollout
> > > >
> > > > **Scenario**: New premium features need testing with select customers before full release
> > > >
> > > > * **Override Setup**: Create user-specific overrides for beta customers and internal stakeholders
> > > > * **Policy Configuration**: Beta users get latest build with premium features, others remain on stable version
> > > > * **Business Value**: Risk mitigation through controlled exposure and real-world testing feedback
> > >
> > > > [accordion] Emergency Response
> > > >
> > > > **Scenario**: Critical bug discovered in production affecting specific user workflows
> > > >
> > > > * **Override Setup**: Create high-priority role override for affected user groups
> > > > * **Policy Configuration**: Temporarily revert affected users to last stable build while others continue normally
> > > > * **Business Value**: Immediate incident response with minimal user impact and service continuity
> >
> > [Learn more about Active Policy Overrides](../../../../5.1/docs/projects/runtime/active-policy)
> >
> > Major Enhancement

> [tab] Persistence
>
> Advanced data management and storage capabilities that enable new architectural patterns and improved data governance.
>
> 🔄 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture) - Logical separation of business contexts with shared infrastructure\
> 🔄 [**FlowX.AI Database**](#flowx-ai-database) - New persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.1.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature

> [tab] Rendering Improvements & UI/UX Enhancements
>
> Enhanced user experience through improved components, better performance, and streamlined interface design.
>
> 🎨 [**Rendering Improvements & UI/UX Enhancements**](#rendering-improvements-&-ui/ux-enhancements) - Enhanced grid components, navigation redesign, advanced form controls, and analytics capabilities\
> 📋 [**Forms in Collections**](#forms-in-collections) - Enhanced support for form elements within collection components, enabling complex data entry scenarios\
> 🔄 [**Multi Select UI Component**](#multi-select-ui-component) - Allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
>
> ### **Rendering Improvements & UI/UX Enhancements**
>
> > [card] Rendering Improvements & UI/UX Enhancements
> >
> > FlowX.AI 5.1.0 delivers comprehensive UI/UX improvements that enhance the user experience across all platform components, from streamlined navigation to advanced form controls and better workflow handling.
> >
> > ## Interface & Navigation Improvements
> >
> > > [card] Enhanced Grid Component
> > >
> > > Improved performance, responsiveness, and customization options for data display and form organization
> >
> > > [card] Navigation Areas Redesign
> > >
> > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> >
> > > [card] Multi Actions Support
> > >
> > > Batch operations support for UI components, enabling simultaneous actions on multiple elements, multi select, multi copy/paste, multi drag and drop, multi delete
> >
> > > [card] [Permission-Based UI Editing](../../../../5.1/docs/building-blocks/ui-designer/ui-designer#permission-based-expressions)
> > >
> > > Granular control over UI element editing based on user permissions with partial editing capabilities, allow multiple executors on swimlane level
> >
> > ## Enhanced Form Controls & Components
> >
> > > [card] [Input Type Code](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-types)
> > >
> > > Specialized input component for code entry
> >
> > > [card] Formatting Options
> > >
> > > Advanced formatting capabilities for Input and Slider components
> >
> > > [card] [Switch Variants](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field#switch-type)
> > >
> > > Enhanced switch component supporting both toggle and checkbox variants
> >
> > > [card] [Disabled Options on Selectors](/5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select#disabled-options)
> > >
> > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > ## User Experience Enhancements
> >
> > > [card] Custom Loader
> > >
> > > Configurable loading indicators for improved user experience during data operations
> >
> > > [card] [Custom Expression Validators](../../../../5.1/docs/building-blocks/ui-designer/validators#custom-validators)
> > >
> > > Advanced validation logic using dynamic computed expressions that can reference other process data values. Write JavaScript expressions that return boolean values for cross-field validation scenarios
> >
> > > [card] File Upload Button Type
> > >
> > > Introduces a specialized button variant for file upload operations, supporting **fill**, **ghost**, and **text** types for flexible UI styling.
> >
> > > [card] Copy Styles
> > >
> > > Efficiently replicate styling across multiple UI components
> >
> > ## Workflow & Analytics Improvements
> >
> > > [card] Analytics Enhancements
> > >
> > > Custom payload support for detailed user interaction tracking and business intelligence
> >
> > > [card] Process End Handling
> > >
> > > Improved user experience when processes complete or terminate
> >
> > > [card] Template Management
> > >
> > > Streamlined template organization by consolidating functionality in Reusable Resources
>
> ***
>
> ### **Forms in Collections**
>
> > [card] Forms in Collections
> >
> > A powerful new feature that enables dynamic, repeatable forms within collection prototypes, eliminating the need for custom development when building forms with repeatable sections like co-debtors, comments, or any list of similar items.
> >
> > <video />
> >
> > ## Key Capabilities
> >
> > > [card] No Custom Development
> > >
> > > Drag Form components directly into Collection Prototypes - they automatically repeat for each item in your data array
> >
> > > [card] Flexible Validation
> > >
> > > Choose between individual item validation or bulk validation across all collection items
> >
> > > [card] Two Saving Scenarios
> > >
> > > Individual save (one item at a time) or bulk save (entire collection) with different validation behaviors
> >
> > ## Common Use Cases Solved
> >
> > **1. Dynamic Forms**
> >
> > Build forms that show different elements based on conditions without custom development
> >
> > **2. Repeatable Sections**
> >
> > Create forms with sections like adding multiple co-debtors, comments, or family members
> >
> > **3. Complex Data Entry**
> >
> > Handle arrays of objects with proper validation and data management
> >
> > **4. Real-time vs Batch Processing**
> >
> > Choose individual saves for real-time editing or bulk saves for form completion workflows
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component

> [tab] AI Platform
>
> New AI capabilities in Integration Designer for processing text, documents, images, and data using AI-powered nodes.
>
> 🤖 [**AI Nodes in Integration Designer**](#ai-nodes-in-integration-designer) - Process text, documents, images, and data using AI-powered workflow nodes
>
> ### **AI Nodes in Integration Designer**
>
> > [card] AI Nodes in Integration Designer
> >
> > > [tab] AI Nodes Overview
> > >
> > > ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
> > >
> > > FlowX.AI 5.1.0 introduces AI-powered nodes in Integration Designer, enabling intelligent processing of text, documents, images, and data within your workflows. These nodes bring AI capabilities directly into your integration flows without requiring external AI services.
> >
> > > [tab] AI Text Operations
> > >
> > > > [card] Text Transformation
> > > >
> > > > Modify text tone, complexity or formatting for better clarity or style
> > >
> > > > [card] Text Understanding
> > > >
> > > > Analyze text to determine sentiment, topics, intent, language and named entities
> > >
> > > > [card] Text Generation
> > > >
> > > > Generate new text such as summaries, completions, translations or paraphrases
> > >
> > > > [card] Text Extraction
> > > >
> > > > Extract structured information, keywords or metadata from text
> >
> > > [tab] AI Document Operations
> > >
> > > > [card] Document Generation
> > > >
> > > > Automatically build reports or complete templates based on given inputs
> > >
> > > > [card] Document Extraction
> > > >
> > > > Identify and extract structured data, entities or metadata from documents
> > >
> > > > [card] Document Understanding
> > > >
> > > > Analyze documents to extract meaning, topics, sentiment, or important information
> > >
> > > > [card] Extract Text from Document
> > > >
> > > > Extract text content from documents (OCR, PDF text extraction)
> >
> > > [tab] AI Image & Data Operations
> > >
> > > **Image Operations:**
> > >
> > > > [card] Image Description
> > > >
> > > > Generate captions or extract detailed information from visual content
> > >
> > > > [card] Image Analysis
> > > >
> > > > Recognize objects, emotions and scenes in images for contextual understanding
> > >
> > > **Data Operations:**
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Add annotations, context or relationships to enhance raw data value
> > >
> > > > [card] Data Generation
> > > >
> > > > Produce synthetic or structured data using templates and logic-based rules
> > >
> > > > [card] Data Transformation
> > > >
> > > > Clean, normalize, aggregate, or restructure datasets into usable formats
> >
> > > [tab] Use Cases
> > >
> > > > [accordion] Intelligent Document Processing
> > > >
> > > > * Extract data from invoices, contracts, and forms
> > > > * Classify documents automatically
> > > > * Validate extracted information against business rules
> > >
> > > > [accordion] Customer Communication Analysis
> > > >
> > > > * Analyze customer feedback sentiment
> > > > * Extract key topics from support tickets
> > > > * Generate personalized responses
> > >
> > > > [accordion] Content Generation
> > > >
> > > > * Create summaries of long documents
> > > > * Translate content to multiple languages
> > > > * Generate reports from structured data
> > >
> > > > [accordion] Data Processing
> > > >
> > > > * Enrich customer data with AI-derived insights
> > > > * Transform unstructured data to structured formats
> > > > * Generate test data for development
> >
> > [Learn more about AI Node Types](../../../../5.1/docs/platform-deep-dive/integrations/ai-nodes)
> >
> > New Feature

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.1](./deployment-guidelines-v5.1)
> >
> > Instructions for deploying FlowX.AI 5.1.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.1/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.1.0


# FlowX.AI 5.1.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.1-november-2025

WCAG 2.1 Level AA compliance achieved, AI Platform enhancements, bug fixes, and quality improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **accessibility compliance**, **AI Platform enhancements**, **customer issue resolution**, and **proactive quality improvements**.
> Upgrades from **5.1.0 → 5.1.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Quality Achievement**: FlowX.AI 5.1.1 demonstrates our commitment to proactive quality improvement:
>
> * **[WCAG 2.1 Level AA compliance](https://www.w3.org/TR/WCAG21/)** achieved across all web components
> * **Proactive quality improvements** identified through internal QA before reaching customers
> * **Customer issues** resolved with full business context
> * **Zero breaking changes** - fully compatible upgrade from 5.1.0
>
> This release represents months of accessibility audits, automated testing, and quality assurance work to deliver exceptional software quality.

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.1 delivers comprehensive improvements across accessibility, stability, and platform reliability.
>
> ♿  [**WCAG 2.1 Compliance Achieved**](#wcag-2-1-compliance) - Full accessibility support across all web components\
> 🌍 [**Task Management Localization**](#task-management-localization) — Comprehensive multi-language support with 51 substitution tags\
> 🤖 [**AI Platform Enhancements**](#ai-platform-enhancements) — Multi-agent system improvements and AI workflow stability\
> 🎯 [**Customer Fixes**](#customer-fixes) — Critical issues resolved based on customer feedback\
> ✨ [**Proactive Improvements**](#proactive-quality-improvements) — Issues identified through internal QA before reaching customers\
> 🔧 [**Platform Enhancements**](#platform-enhancements) — SSE handling, audit logs, and infrastructure improvements
>
> ### **WCAG 2.1 compliance**
>
> > [card] WCAG 2.1 compliance
> >
> > > [tab] Overview
> > >
> > > **FlowX.AI is now WCAG 2.1 Level AA compliant**
> > >
> > > This release delivers full accessibility support through **28 comprehensive improvements** across Angular and React SDKs, making FlowX applications usable by everyone, including users with disabilities.
> > >
> > > ### Business value
> > >
> > > > [card] Government Compliance
> > > >
> > > > Meet accessibility requirements for government and public sector applications
> > >
> > > > [card] Healthcare Standards
> > > >
> > > > Comply with healthcare industry accessibility regulations and standards
> > >
> > > > [card] Financial Services
> > > >
> > > > Satisfy financial sector requirements for inclusive digital experiences
> > >
> > > > [card] Universal UX
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those with disabilities
> > >
> > > ### What changed
> > >
> > > * All components now fully keyboard-accessible
> > > * Complete screen reader support with ARIA labels
> > > * Proper focus management across all interactions
> > > * Accessible error announcements and validation
> > > * Semantic HTML structure throughout
> >
> > > [tab] Key features
> > >
> > > > [card] Auto-bindable ARIA Tags
> > > >
> > > > Automatically bind accessibility labels, descriptions, and ARIA attributes to all UI components from Designer configuration
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Full keyboard navigation support with proper focus management, tab order, and keyboard shortcuts in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > ARIA labels, descriptions, and live regions implemented across all form elements and interactive components
> > >
> > > > [card] UI Designer Integration
> > > >
> > > > Dedicated accessibility configuration section in UI Designer for managing labels and descriptions
> >
> > > [tab] Supported components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio/Segmented buttons, Slider, and File upload with labels, descriptions, and error announcements
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card with keyboard navigation, focus management, and state announcements
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with semantic HTML structure and proper labeling
> > >
> > > **4. Platform Support**
> > >
> > > Complete implementation for Angular and React SDKs (iOS and Android in future releases)
> >
> > > [tab] Implementation details
> > >
> > > **28 Improvements Delivered:**
> > >
> > > > [accordion] Angular SDK
> > > >
> > > > * Custom keyboard navigation implementation
> > > > * Focus management for Select/Multiselect components
> > > > * Modal focus trap and restoration
> > > > * Shift+Tab handling across form elements
> > > > * Listbox keyboard operations
> > > > * Table navigation improvements
> > > > * Switch and checkbox accessibility
> > > > * File preview focus indicators
> > > > * Button Space key activation
> > > > * Link focus outlines
> > > > * Disabled element keyboard behavior
> > >
> > > > [accordion] React SDK
> > > >
> > > > * BaseUI Combobox implementation for Select/Multiselect
> > > > * Keyboard navigation with clear buttons
> > > > * Focus restoration after interactions
> > > > * Outline theming for focus indicators
> > > > * Modal auto-focus on open
> > > > * Card accordion keyboard handling
> > > > * Table row navigation
> > > > * Option highlighting in dropdowns
> > >
> > > > [accordion] UI Designer
> > > >
> > > > * Accessibility configuration panel
> > > > * Auto-bindable tags for all components
> > > > * Label and description fields
> > > > * Alt text management for images
> > > > * ARIA attribute configuration
> > > > * Accessibility section styling
> > > > * Component-specific accessibility settings
> > >
> > > > [accordion] Technical tasks completed
> > > >
> > > > * Implemented BaseUI Combobox for Select/Multiselect
> > > > * Custom keyboard navigation for Angular
> > > > * React SDK keyboard navigation with clear button
> > > > * Auto-bindable accessibility tags for all components
> > > > * Accessibility configuration panel in UI Designer
> > > > * Removed conflicting title attribute tooltips
> > > > * Aligned Stepper accessibility between frameworks
> > > > * Bind labels and descriptions to form fields
> >
> > [Learn more about Accessibility Configuration](/5.1/docs/platform-deep-dive/accessibility)
> >
> > Major Achievement
>
> ***
>
> ### **Customer fixes**
>
> > [card] Customer fixes
> >
> > We prioritized and resolved **customer-reported issues** in this release, addressing critical functionality issues and workflow inefficiencies reported via Zendesk.
> >
> > > [accordion] Action parameters lost on copy/paste
> > >
> > > **Problem:**\
> > > When copying nodes with Kafka send actions, topic and message configurations were not preserved, forcing users to manually reconfigure all action parameters after paste operations.
> > >
> > > **Customer Impact:**
> > >
> > > * Development velocity significantly reduced
> > > * Risk of configuration errors during manual re-entry
> > > * Frustration with repetitive configuration work
> > >
> > > **Resolution:**\
> > > actionParamsMap now properly persists through copy/paste operations
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create send message node with Kafka action
> > > 2. Configure topic and message parameters
> > > 3. Copy and paste the node
> > > 4. All configurations now preserved correctly
> > >
> > > **Customer Benefit:**\
> > > Faster workflow development with reduced configuration errors and improved developer experience.
> >
> > > [accordion] Orphaned warnings block process deployments
> > >
> > > **Problem:**\
> > > When deleting parent actions that had child actions with warnings, the warnings remained in the system as orphans. These orphaned warnings prevented process export/import operations and blocked build deployments.
> > >
> > > **Customer Impact:**
> > >
> > > * Build pipelines blocked by stale warnings
> > > * Deployment delays requiring manual database cleanup
> > > * Process export/import operations failed
> > > * Development and testing workflows disrupted
> > >
> > > **Resolution:**\
> > > Warnings now cascade-delete automatically when parent actions are removed
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create action with subactions containing warnings
> > > 2. Delete the parent action
> > > 3. All child warnings now properly cleaned up
> > >
> > > **Customer Benefit:**\
> > > Clean deployments without manual intervention, faster development cycles, no more blocked pipelines.
> >
> > > [accordion] Default application cannot be removed
> > >
> > > **Problem:**\
> > > Auto-generated `default_application` in new environments existed only in app\_manager schema and could not be deleted through standard operations, returning validation errors.
> > >
> > > **Customer Impact:**
> > >
> > > * Environment cleanup difficulties
> > > * Testing complications with unwanted default projects
> > > * Confusion about application lifecycle management
> > >
> > > **Resolution:**\
> > > Added proper runtime validation for application deletion operations
> > >
> > > **Error (Fixed):**
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": 400,
> > >   "message": "error.validation.runtime.application.not_found",
> > >   "title": "Runtime project not found."
> > > }
> > > ```
> > >
> > > **Customer Benefit:**\
> > > Clean environment management with predictable application lifecycle operations.
>
> ***
>
> ### **Proactive quality improvements**
>
> > [card] Proactive quality improvements
> >
> > > [tab] Overview
> > >
> > > **Issues identified and resolved proactively**:
> > >
> > > ### Quality process
> > >
> > > > [card] Accessibility Audits
> > > >
> > > > WCAG 2.1 compliance testing identified keyboard navigation and focus management improvements
> > >
> > > > [card] Automated Testing
> > > >
> > > > Continuous integration pipelines caught component behavior issues and rendering problems
> > >
> > > > [card] Internal QA
> > > >
> > > > Manual testing uncovered edge cases in form interactions and modal behaviors
> > >
> > > > [card] Code Reviews
> > > >
> > > > Peer reviews identified potential stability issues in backend processing and dependency management
> > >
> > > ### Distribution by category
> > >
> > > * **Keyboard Navigation**: Fixes across Angular and React
> > > * **Focus Management**: Fixes for modals, forms, and interactive elements
> > > * **Component Behavior**: Fixes for proper state handling and rendering
> > > * **Backend Stability**: Fixes for processing and dependency management
> >
> > > [tab] Angular SDK
> > >
> > > > [accordion] Keyboard navigation improvements
> > > >
> > > > * Fixed listbox remaining open when pressing Shift+Tab
> > > > * Fixed Shift+Tab not working on Select with search
> > > > * Fixed Multiselect tab navigation moving to first element instead of next
> > > > * Fixed Select input focus not working properly
> > > > * Fixed Select list not scrolling during keyboard navigation
> > > > * Fixed up/down arrow scrolling screen alongside option list
> > > > * Fixed focus lost after loading new user task
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed Link in message focus missing outline
> > > > * Fixed modal close button not focused automatically
> > > > * Fixed file preview focus not highlighted and lost
> > > > * Fixed button inside modal not working with Space key
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Multiselect options list not opening
> > > > * Fixed MultiSelect and link focusable when disabled
> > > > * Fixed modal dismiss buttons not working with Space key
> > > > * Fixed modal without close button not easily focusable
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Space pressed on card with accordion scrolling page
> > > > * Fixed Switch with label position start focus issues
> >
> > > [tab] React SDK
> > >
> > > > [accordion] Keyboard Navigation Improvements
> > > >
> > > > * Fixed outline from theme not applied to modal close button and links
> > > > * Fixed Select selected option not highlighted in options list
> > > > * Fixed Select search not filtering after selection
> > > > * Fixed Input/textarea/select focus lost after using clear button
> > > > * Fixed Tab focus moving inside collapsed card
> > > > * Fixed table Tab navigation skipping rows
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed file preview retry focus not highlighted and lost
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Select and link focusable when disabled
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Datepicker clear icon focus not highlighted
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed doc preview modal not closable with Enter or Space
> > > > * Fixed button inside table focus not highlighted
> > > > * Fixed Slider decimal numbers not rendered correctly
> > > > * Fixed Substepper not rendered correctly
> > > > * Fixed doc preview display mode showing inline
> > > > * Fixed cards expandable before token reaches them
> >
> > > [tab] Designer & Backend
> > >
> > > > [accordion] UI Designer Improvements
> > > >
> > > > * Fixed missing accessibility section on Link component
> > > > * Fixed missing accessibility section on Image button
> > > > * Fixed missing space in accessibility label and info icon
> > > > * Fixed Alt text field disabled styling not applied
> > > > * Fixed console errors when changing pages from header
> > > > * Fixed Select/multiselect highlighted in preview and settings tabs
> > > > * Fixed outline theming in enumerations and inputs
> > > > * Fixed Workflows info points content not rendered correctly
> > > > * Fixed Workflows tabs content not showing properly
> > > > * Fixed padding missing on RUT UI Assets panel
> > >
> > > > [accordion] Backend Stability Improvements
> > > >
> > > > * Fixed wrong navigationTree response on overridden process
> > > > * Fixed incorrect navigationTree for resource override details
> > > > * Fixed error when trying to update dependency lib versions
> > > > * Fixed error returned when updating dependency with override
> > > > * Fixed no response on out topic for start process by name from Kafka
> > > > * Fixed checkbox "Allow back to this action" status not loaded
> > > > * Fixed empty screen when logging in without workspace access
> > > > * Fixed Elasticsearch scheduled task errors with failed documents
> > > > * Fixed services not logging when Liquibase crashing due to lock
> >
> > Proactive Quality
>
> ***
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 adds comprehensive localization support for Task Management, enabling multi-language task management interfaces through 51 system substitution tags. Table grid localization is automatic.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > >
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> > >
> > > > [!NOTE]
> > > >
> > > > This feature enables complete Task Management localization for global deployments, meeting requirements for government, healthcare, and financial services applications requiring multi-language support.
> >
> > > [tab] Key features
> > >
> > > > [card] FlowX Substitution Tags (51 Keys)
> > > >
> > > > Complete set of substitution tags for task actions, statuses, history events, and UI elements
> > >
> > > > [card] Table Grid Localization
> > > >
> > > > Table grid localizes automatically based on container app language; FlowX tags configured manually in CMS
> > >
> > > > [card] Web Renderer Integration
> > > >
> > > > Angular and React renderers use system substitution tags on all task management texts
> >
> > > [tab] What's localized
> > >
> > > **FlowX Substitution Tags (51 Keys):**
> > >
> > > * Table columns (title, stage, assignee, status, priority, last updated)
> > > * Process states (created, started, finished, failed, expired, etc.)
> > > * Task actions (assign, unassign, hold, unhold, execute, start)
> > > * Bulk operations (assign to, unassign all, hold all, etc.)
> > > * History events (task created, assigned, status changed, etc.)
> > > * User selection dialogs and UI states
> > >
> > > **Table Grid Localization**:
> > >
> > > * Filters (set, text, number, date with all operators)
> > > * Menus (column, context, aggregation, sorting)
> > > * Pagination (navigation, page size, row counts)
> > > * Data types (boolean, dates, numbers with formatting)
> > > * ARIA labels for accessibility
> >
> > > [tab] Implementation details
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization based on this setting
> > >
> > > **2. Configure CMS Tags**
> > >
> > > Add translations for all 51 sys\_tm\_\* tags in CMS for each supported language - this is the only manual configuration needed
> > >
> > > **3. Use in Renderers**
> > >
> > > Web renderers automatically apply system substitution tags to all task management UI elements
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> ***
>
> ### **AI Platform enhancements**
>
> > [card] AI Platform enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 delivers significant improvements to the AI Platform, enhancing multi-agent collaboration, conversation management, and AI workflow stability. These enhancements ensure more reliable AI-assisted development workflows and better user experience.
> > >
> > > > [card] Multi-Agent System
> > > >
> > > > Enhanced agent communication and thread management for improved collaborative AI workflows
> > >
> > > > [card] Conversation Stability
> > > >
> > > > Improved conversation handling with better error propagation and session management
> > >
> > > > [card] AI Developer Tools
> > > >
> > > > Enhanced AI Developer capabilities with proper data model integration and expression generation
> > >
> > > > [card] Document Intelligence
> > > >
> > > > Multi-page document generation support and improved content handling
> >
> > > [tab] Key improvements
> > >
> > > **Multi-Agent Conversation Management:**
> > >
> > > * Enhanced conversation thread handling with proper parent action status updates
> > > * Improved backend support for adding new messages on agent threads
> > > * Better session management with new session button in Command Center
> > > * Context switching prevention during execution plan generation
> > >
> > > **AI Developer Enhancements:**
> > >
> > > * Fixed data model integration for expressions and business rules generation
> > > * Improved action target saving and destination setting
> > > * Enhanced execution plan editing from user prompts
> > > * Better handling of empty execution plans
> > >
> > > **Error Handling & Stability:**
> > >
> > > * Graceful error propagation from internal AI agent operations
> > > * Improved CORS headers for document object downloads
> > > * Enhanced telemetry support for debugging and monitoring
> > > * Better handling of plan enhancement patches
> > >
> > > **Document & Content Features:**
> > >
> > > * Multi-page document generation support in AI nodes
> > > * Source selector component for image and document inputs
> > > * Improved messaging system for AI agents in command center
> > > * Enhanced UI feedback for AI-generated resources
> >
> > > [tab] Technical improvements
> > >
> > > **Backend Enhancements:**
> > >
> > > * Continuous patching support for action contexts during execution
> > > * Improved navigation tree responses for overridden processes
> > > * Enhanced dependency management for library overrides
> > > * Better error handling and logging across AI services
> > >
> > > **Frontend Improvements:**
> > >
> > > * Fixed target selector closing behavior in implementation threads
> > > * Improved preview mode handling after developer changes
> > > * Enhanced command center messaging and error display
> > > * Better UI state management for AI workflow interactions
> > >
> > > **Integration Updates:**
> > >
> > > * CORS headers properly configured for GraphQL object downloads
> > > * Process task destinations automatically set to current process
> > > * Improved integration between AI agents and execution plans
> > > * Enhanced audit logging for resource overrides
> >
> > AI Platform
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform enhancements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] SSE Disconnect Handling
> > > >
> > > > Improved Server-Sent Events disconnect handling to reduce error log flooding when clients disconnect
> > >
> > > > [card] Resource Overrides Audit
> > > >
> > > > Implemented audit logs for library resource overrides to track configuration changes
> > >
> > > > [card] Security Updates
> > > >
> > > > Fixed high vulnerabilities in Designer 5.1.x and main branch
> >
> > > [tab] Renderer Enhancements
> > >
> > > > [card] System Substitution Tags
> > > >
> > > > Web renderers now use system substitution tags on all task management texts
> > >
> > > > [card] Outline Theming
> > > >
> > > > Enhanced outline and select/multiselect option highlight theming for visual consistency
> >
> > > [tab] Technical Improvements
> > >
> > > **Code Quality:**
> > >
> > > * Eliminated deprecated code for Kafka start process
> > > * Improved error handling for Elasticsearch document updates
> > > * Enhanced dependency management for library overrides
> > > * Better logging and error reporting across services
> > >
> > > **Performance:**
> > >
> > > * Optimized SSE connection handling
> > > * Improved query performance for navigation tree
> > > * Better resource management in long-running processes
> >
> > Platform Updates

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.1 is fully compatible with 5.1.0. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.0 → 5.1.1 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Android and iOS accessibility properties implementation
> > * Additional Select component refinements
> > * UI Designer padding optimizations
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and critical bug fixes
> * Accessibility enhancements for mobile platforms
> * Performance optimizations
>
> Major new features are planned for future releases in the 5.x series. See the [5.2.0 release notes](../v5.2.0-november-2025/v5.2.0-november-2025) for upcoming capabilities.


# FlowX.AI 5.1.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.2-december-2025

Bug fixes, stability improvements, and quality enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes**, **stability improvements**, and **quality enhancements**.
> Upgrades from **5.1.1 → 5.1.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.2 provides continued quality, stability, and reliability for the platform:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * New features and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.2 delivers maintenance improvements focused on stability, reliability, and feature enhancements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — issues resolved including customer-reported and proactive fixes\
> ✨ [**New Features**](#new-features) — enhancements including new features and platform improvements\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure and stability enhancements
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Authorization service configuration
> > > >
> > > > **Problem:**\
> > > > Wrong service account client secret config parameter was used in Authorization service, causing authentication failures.
> > > >
> > > > **Resolution:**\
> > > > Fixed configu gration parameter mapping for service account client secret in Authorization service
> > >
> > > > [accordion] Token state changes on back navigation
> > > >
> > > > **Problem:**\
> > > > When performing back in steps actions, tokens incorrectly changed from Aborted to Active state when lazy actions finished.
> > > >
> > > > **Resolution:**\
> > > > Fixed token state management during back navigation to preserve correct state
> > >
> > > > [accordion] Action parameters not copied on node copy
> > > >
> > > > **Problem:**\
> > > > When copying nodes with child actions, action parameters (like Kafka topic and message configurations) were not preserved.
> > > >
> > > > **Resolution:**\
> > > > Fixed actionParamsMap persistence through copy/paste operations
> > >
> > > > [accordion] Permissions updated incorrectly during action execution
> > > >
> > > > **Problem:**\
> > > > hideRules and disableRules values were incorrectly updated in database when executing actions, causing permission issues.
> > > >
> > > > **Resolution:**\
> > > > Fixed permission rule handling during action execution
> > >
> > > > [accordion] Subprocess data mapping issues
> > > >
> > > > **Problem:**\
> > > > Starting subprocess with legacy mapping caused data to be incorrectly appended instead of replaced.
> > > >
> > > > **Resolution:**\
> > > > Fixed data mapping behavior for subprocess start actions
> > >
> > > > [accordion] Forms in collections - action not found
> > > >
> > > > **Problem:**\
> > > > When saving data from outside collection with forms to submit, actions were not found correctly.
> > > >
> > > > **Resolution:**\
> > > > Fixed action resolution for forms inside collections
> >
> > > [tab] AI Platform fixes
> > >
> > > > [accordion] AI Designer improvements
> > > >
> > > > * Fixed no feedback when uploading large documents in command center
> > > > * Fixed targets for business rules never being set by planner
> > > > * Fixed file upload limit lower than 3MB
> > > > * Fixed missing messages on Keep/Discard buttons for UI and BR
> > > > * Fixed Save & Close button not working in Data Model modal
> > > > * Fixed DM keys not created after keeping UI
> > > > * Fixed table key appearing as mapped when Data Model is empty
> > > > * Fixed pip window being clipped
> > > > * Fixed Submit prompt button color not indicating active state
> > > > * Fixed source not indicating uploaded document for some Plan actions
> > > > * Fixed UI outcome duplication until connected-graph keep method finishes
> > > > * Fixed missing scrollbar in Context Documents modal with multiple subprocesses
> > > > * Fixed command center not reopenable after closing in developer preview mode
> > > > * Fixed planner sample data import crashes
> > > > * Fixed business logic targets not correctly stored in execution plan
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Web renderer improvements
> > > >
> > > > * Fixed hide subprocess navigation closing parent navigation with multiple hierarchies
> > > > * Fixed card collapsing when next nav area is modal (Angular & React)
> > > > * Fixed card not expandable after finishing subprocess started from it (Angular & React)
> > > > * Fixed loader missing or not fully shown in React
> > > > * Fixed message icon and text rendered on different rows when width fill in React
> > > > * Fixed collection prototype shown when collection source array doesn't exist in React
> > > > * Fixed broken image rendered when missing url or base64 image in React
> > > > * Fixed switch component knob and container alignment in React
> > > > * Fixed multi select search not filtering available options in React SDK
> > > > * Fixed custom component keys duplicated in action body (React & Angular)
> > >
> > > > [accordion] Task Manager fixes
> > > >
> > > > * Fixed Task Manager theming not applied in Angular
> > > > * Fixed Task Manager header theming not applied in React
> > > > * Fixed assignee dropdown list and placeholder not displayed in React
> > >
> > > > [accordion] Reusable templates fixes
> > > >
> > > > * Fixed custom body being null at runtime for Reusable templates actions
> >
> > > [tab] Platform & Data fixes
> > >
> > > > [accordion] Data model and mappers
> > > >
> > > > * Fixed input/output parameters not deleted after updating parameters
> > > > * Fixed Go to reference button redirecting incorrectly
> > > > * Fixed parameters items deleted when updating Project Data Model object
> > >
> > > > [accordion] Process Designer
> > > >
> > > > * Fixed retry token button available for inactive tokens
> > > > * Fixed missing save action button when opening action config from UI designer
> > >
> > > > [accordion] Platform stability
> > > >
> > > > * Fixed advancing errors in partition event table
>
> ***
>
> ### **New features**
>
> > [card] New features
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation
> > > >
> > > > Generate Data Model for tables and table columns from AI Designer
> >
> > > [tab] Renderers
> > >
> > > > [card] Android Accessibility
> > > >
> > > > Accessibility properties from UI Designer now supported in Android renderer
> > >
> > > > [card] Substitution Tags in Selectors
> > > >
> > > > Selectors (checkbox, radio, select, multiselect) now support substitution tags when source type is process data across Angular, React, and iOS renderers
> > >
> > > > [card] Template Caching
> > > >
> > > > Improved caching for reusable templates at runtime
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Dgraph Upgrade
> > > >
> > > > Bring dgraph to flowx-release
> >
> > > [tab] Performance & Optimization
> > >
> > > > [card] Designer Static Assets
> > > >
> > > > Make designer nginx use compression & caching for static assets

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.2 is fully compatible with 5.1.1. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.1 → 5.1.2 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.2](./deployment-guidelines-v5.1.2).
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Task Manager theming issues in Angular and React
> > * Task Manager assignee dropdown display issues in React
> > * Custom component key duplication in action body
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.3-january-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.2 → 5.1.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.3 delivers security patches and significant performance improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.2

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.3 delivers comprehensive security, performance, and stability improvements across the platform.
>
> ♿ [**iOS Accessibility**](#improvements-and-enhancements) — VoiceOver accessibility support for iOS renderer\
> ✨ [**Improvements and enhancements**](#improvements-and-enhancements) — AI Platform improvements and enhancements for Data Model generation\
> ⚡ [**Performance Improvements**](#performance-improvements) — Performance improvements and optimizations across platform components and services\
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Improvements and enhancements**
>
> > [card] Improvements and enhancements
> >
> > > [tab] Renderers
> > >
> > > > [card] iOS Accessibility
> > > >
> > > > VoiceOver accessibility support for the iOS renderer. Accessibility properties configured in the UI Designer (labels, hints, traits, decorative flags) are now applied to iOS components including form elements, text, images, and links.
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation for Tables
> > > >
> > > > Generate Data Model mappings for table components from AI Designer. AI automatically creates array of objects DM keys for tables with type validation and visual feedback.
> > >
> > > > [card] Data Model Generation for Table Columns
> > > >
> > > > Extended DM generation for text and link elements within table columns, with automatic attribute mapping and support for partial matching.
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.3 delivers significant performance improvements to the process engine
> > >
> > > > [card] Optimized Writes
> > > >
> > > > Smart change detection skips unnecessary database writes when param\_values unchanged
> > >
> > > > [card] Reduced DB Calls
> > > >
> > > > N+1 query fixes and batch loading significantly reduce database round trips
> > >
> > > > [card] Request Caching
> > > >
> > > > Request-scoped caching for frequently accessed runtime configuration
> >
> > > [tab] Key optimizations
> > >
> > > > [accordion] ProcessInstance param\_values Optimization
> > > >
> > > > Optimized handling of large `param_values` to reduce network overhead and prevent optimistic locking conflicts:
> > > >
> > > > * **Change Detection**: Skip database writes when param\_values unchanged
> > > > * **Lightweight Queries**: Exclude param\_values from SELECT when not needed
> > >
> > > > [accordion] Runtime Improvements - Reduced DB Calls
> > > >
> > > > **Optimizations Implemented:**
> > > >
> > > > * Improved batch loading and caching to reduce redundant queries
> > > > * Streamlined process initiation
> > > > * Enhanced batching for database writes
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Task Manager View Not Updating
> > > >
> > > > **Problem:**\
> > > > When using a view with dataset config where assignee is set to blank, after assigning a task (or self-assigning), the view appeared unchanged. Similarly, when assignee is set to not blank and you unassign a task, the view did not update.
> > > >
> > > > **Resolution:**\
> > > > Fixed view refresh behavior after assign/unassign operations to properly reflect the updated task state and provide visual feedback to users.
> > >
> > > > [accordion] Forms in Collections - Backend Keys Calculation
> > > >
> > > > **Problem:**\
> > > > When saving data from outside a collection with forms to submit, the backend calculated keys for UUID entries in formsToSubmit. These keys were only partial (relative to the collection array) and could overwrite existing process values.
> > > >
> > > > **Resolution:**\
> > > > Added a flag on PATCH /actions requests to notify the backend to exclude backend keys calculation for forms in collections UUIDs from formsToSubmit.
> > >
> > > > [accordion] Variables Reset on Config Update
> > > >
> > > > **Problem:**\
> > > > Updating parameters in the config page caused existing parameters to be replaced with new ones, generating new flowxUuids. This caused variables in database nodes to no longer match, losing all references.
> > > >
> > > > **Resolution:**\
> > > > Fixed to always send id and flowxUuid for existing params when saving the operation, preserving variable references.
> > >
> > > > [accordion] Build Export Timeout
> > > >
> > > > **Problem:**\
> > > > When exporting builds with multiple resources, some resources remained in EXPORTING status, others got EXPORT\_TIMEOUT without the build export receiving the status, and others had EXPORTED status. This was caused by Kafka messages being processed before the MongoDB transaction was committed.
> > > >
> > > > **Resolution:**\
> > > > Fixed the export function to ensure proper sequencing of database transactions and Kafka messages during build export operations.
> >
> > > [tab] Designer fixes
> > >
> > > > [accordion] Table Row Deletable with Backspace in RUT
> > > >
> > > > **Problem:**\
> > > > In Reusable UI Templates, selecting a table row and pressing backspace would delete the row, even though table rows should not be deletable.
> > > >
> > > > **Resolution:**\
> > > > Fixed keyboard handling to prevent accidental table row deletion via backspace key.
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Android Upload Action Payload Missing
> > > >
> > > > **Problem:**\
> > > > Upload action payload data (except uploadFileTempFileId) was missing on execution in the Android renderer.
> > > >
> > > > **Resolution:**\
> > > > Fixed payload handling to include all required data in upload action execution.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Connector Topic Pattern
> > > >
> > > > Added dedicated KAFKA\_TOPIC\_CONNECTOR\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [tab] AI Platform
> > >
> > > > [card] Streaming Client Library
> > > >
> > > > Implemented client library for invoking the run AI node with streaming support for conversational API

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.3 is fully compatible with 5.1.2. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.2 → 5.1.3 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### New configuration options
>
> > [!NOTE]
> >
> > **Optional**: New environment variable available for process-engine
>
> | Variable | Description | Default |
> | - | - | - |
> | `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from other platform components | Falls back to `KAFKA_TOPIC_PATTERN` if not set |
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.3](./deployment-guidelines-v5.1.3).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.3 → 5.1.4** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.4 delivers security patches and stability improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.3

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.4 delivers comprehensive security, performance, and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components and stability improvements\
> ⚡ [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Form validators do not work inside collection prototypes
> > > >
> > > > **Summary:**
> > > >
> > > > Validators applied to forms within collection prototypes are not triggered as expected.
> > >
> > > > [accordion] Project editor could modify access permissions
> > > >
> > > > **Summary:**
> > > >
> > > > Project editors were incorrectly able to modify project access permissions and delete projects. This has been fixed: `project_editor` can no longer modify access management or delete projects/libraries. Only `project_owner` and `workspace_admin` can change project ownership, add/remove users and groups from projects/libraries, and delete projects/libraries.
> > >
> > > > [accordion] Subprocess UI still shown after subprocess is finished
> > > >
> > > > **Summary:**
> > > >
> > > > In processes with multiple subprocesses that have UI, the first subprocess UI remained visible after completion until the next user task details were received. The UI now correctly clears when a subprocess finishes.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Kafka environment variables alignment
> > > >
> > > > Kafka environment variables are now consistent across all services with backwards compatibility support for existing configurations.
> > >
> > > > [card] Config params cache improvements
> > > >
> > > > New environment variables for tuning config params cache: `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` and `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`. See [Engine Setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
> > >
> > > > [card] Project editor permissions update
> > > >
> > > > `project_editor` can no longer delete projects or modify access permissions. `projects_admin` permission now grants full project management capabilities. See [Roles Permissions Matrix](/5.1/setup-guides/access-management/roles-permissions-matrix).
> > >
> > > > [card] Advancing partition counter fix
> > > >
> > > > Fixed an issue where the advancing partition counter could go negative, causing event processing failures. Improves reliability in integration-designer and process-engine.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.4 is fully compatible with 5.1.3. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.3 → 5.1.4 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.4](./deployment-guidelines-v5.1.4).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.5-february-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.4 → 5.1.5** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.5 delivers bug fixes and stability improvements:
>
> * Fixes for process loop rendering issues in the Angular renderer
> * Fix for subprocess output data not being returned from embedded processes
> * No breaking changes — fully compatible upgrade from 5.1.4

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.5 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer and process engine fixes for process loop scenarios
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes
> > >
> > > Issues resolved in the Angular renderer:
> > >
> > > > [accordion] Validation shown without user interaction on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task for the second time, form validation errors were displayed immediately without any user interaction. Validation now correctly waits for user input before showing errors.
> > >
> > > > [accordion] Action executed continuously on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task that had a UI action configured on a form element, the action was executed continuously in a loop. Actions are now correctly triggered only on user interaction.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Subprocess not returning output from embedded process
> > > >
> > > > **Summary:**
> > > >
> > > > When a subprocess (call activity) was started from an embedded process, the output data was not passed back to the parent process instance after completion. Data mapping from subprocess to parent now works correctly in embedded process scenarios.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.5 is fully compatible with 5.1.4. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.4 → 5.1.5 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.5](./deployment-guidelines-v5.1.5).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026

Bug fixes, stability improvements, and platform enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.5 → 5.1.6** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.6 delivers bug fixes and stability improvements:
>
> * Multiple React and Angular renderer fixes for modals, sliders, buttons, and accessibility
> * Data mappers autocomplete fix for values not loading
> * Process engine fix for advancing getting stuck on pod crash with multiple partition events
> * Kafka health check fix for reporting UP despite consumer DNS failure
> * New health indicator for runtime MongoDB connection
> * Connection leak fix in application-manager export/import operations
> * Improved retry mechanism with configurable exponential backoff
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.5

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.6 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer, process engine, and application manager fixes
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Retry mechanism enhancements and security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes (React)
> > >
> > > Issues resolved in the React renderer:
> > >
> > > > [accordion] Clear icon present and clickable on disabled input/textarea
> > > >
> > > > **Summary:**
> > > >
> > > > When an input or textarea component was disabled, the clear icon was still visible and clickable. The clear icon is now hidden and non-interactive on disabled components.
> > >
> > > > [accordion] Options list not shown when selectors are inside modal
> > > >
> > > > **Summary:**
> > > >
> > > > When select or multiselect components were placed inside a modal, the options list was not displayed when opened. Selector dropdowns now render correctly within modal contexts.
> > >
> > > > [accordion] Datepicker calendar shown behind modal
> > > >
> > > > **Summary:**
> > > >
> > > > When a datepicker was placed inside a modal, the calendar popup appeared behind the modal overlay. The datepicker calendar now renders above the modal with correct z-index stacking.
> > >
> > > > [accordion] Slider min/max value not set when loading a screen
> > > >
> > > > **Summary:**
> > > >
> > > > When a slider shared a process data key with an input, or when slider min/max values depended on computed values from another slider, the min/max values were not set on load. Slider initialization now correctly applies min/max values and computed dependencies.
> > >
> > > > [accordion] Slider default value not set with multiple sliders on same page
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple sliders were present on the same page, some sliders did not receive their default values, especially when no explicit null value was set in the data store. Default value initialization now works correctly for all sliders on a page.
> > >
> > > > [accordion] Task management assignee clear icon clickable when disabled
> > > >
> > > > **Summary:**
> > > >
> > > > In the task management view, the assignee field's clear icon was visible and clickable even when the field was disabled (non-editable). The clear icon is now hidden when the assignee field cannot be edited.
> > >
> > > > [accordion] Input, select, datepicker, textarea, and table filters have incorrect inner outline
> > > >
> > > > **Summary:**
> > > >
> > > > Multiple form components displayed an incorrect inner outline styling. The outline now only appears during keyboard navigation, following proper accessibility patterns.
> > >
> > > > [accordion] Data mappers autocomplete values not loading
> > > >
> > > > **Summary:**
> > > >
> > > > Data mapper autocomplete suggestions were not loading values in certain configurations. Autocomplete now correctly fetches and displays available values.
> >
> > > [tab] Renderer fixes (Angular + React)
> > >
> > > Issues resolved in both Angular and React renderers:
> > >
> > > > [accordion] Card height does not update when accordion is collapsed
> > > >
> > > > **Summary:**
> > > >
> > > > When a card component with fixed height contained an accordion, the card height did not update when the accordion was collapsed. Card height now correctly recalculates when accordion state changes.
> > >
> > > > [accordion] Focus outline appears when interacting with card/file preview accordion
> > > >
> > > > **Summary:**
> > > >
> > > > When interacting with a card or file preview component that included an accordion, an unwanted focus outline appeared. The focus outline is now only displayed during keyboard navigation.
> > >
> > > > [accordion] Button icon not correctly rendered
> > > >
> > > > **Summary:**
> > > >
> > > > When a button was configured with a right-aligned icon, fill width, and right-aligned typography, the icon was not aligned with the text, the gap was missing, and text and icon were center-aligned instead of right-aligned. Button icon layout now respects all configured alignment and spacing settings.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Advancing gets stuck when multiple events are available for one partition and pod crashes
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple events were available for the same partition and a pod crashed, only the first event was picked up and the rest remained stuck. Event processing now correctly handles all pending events after a pod recovery.
> > >
> > > > [accordion] Kafka health check reported UP despite consumer DNS failure
> > > >
> > > > **Summary:**
> > > >
> > > > The Kafka health check indicator could report UP even when consumers had DNS resolution failures, masking connectivity issues. Health indicators now correctly reflect the actual state of Kafka consumer connections.
> > >
> > > > [accordion] Health indicator for runtime MongoDB connection
> > > >
> > > > **Summary:**
> > > >
> > > > A new health indicator has been added to monitor the runtime MongoDB connection. This improves observability and allows operators to detect MongoDB connectivity issues through the standard health endpoint.
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Theme not imported during build import
> > > >
> > > > **Summary:**
> > > >
> > > > When importing a build that included theme resources, the theme was not correctly imported. Build import now includes theme resources as expected.
> > >
> > > > [accordion] Connection leak in export/import services
> > > >
> > > > **Summary:**
> > > >
> > > > During import/export operations, database connections were held for the entire duration of long-running operations (MinIO file transfers, REST calls, Kafka messaging), which could exhaust the connection pool. Transaction boundaries have been refined so that database connections are only held during actual database operations.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Process engine
> > >
> > > > [accordion] Configurable retry mechanism with exponential backoff
> > > >
> > > > **Summary:**
> > > >
> > > > The retry mechanism for optimistic locking in the process engine now uses an Equal Jitter strategy and supports runtime configuration via environment variables. Previously, the jitter was nullified by the max delay cap, causing retrying threads to collide at the same millisecond.
> > > >
> > > > New environment variables for the `process-engine`:
> > > >
> > > > | Environment Variable | Description | Default Value |
> > > > | - | - | - |
> > > > | `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` |
> > > > | `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` |
> > > > | `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` |
> > > >
> > > > > [!TIP]
> > > > >
> > > > > Default settings give a total retry window of \~1.2 seconds, which covers most transient optimistic lock conflicts. Increase `FLOWX_RETRY_MAX_RETRIES` or `FLOWX_RETRY_MAX_DELAY_MS` if you see retry exhaustion under high contention.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Removed deprecated access rights endpoint
> > > >
> > > > **Summary:**
> > > >
> > > > A deprecated endpoint and its associated test for access rights have been removed from the codebase as they are no longer needed.
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across all platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.6 is fully compatible with 5.1.5. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.5 → 5.1.6 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.6](./deployment-guidelines-v5.1.6).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.7 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.7-march-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.6 → 5.1.7** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.7 delivers bug fixes and stability improvements:
>
> * Fix for build import issues with manifest (reimport failures)
> * Security patches
> * No breaking changes, fully compatible upgrade from 5.1.6

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.7 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Build import fix
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Build reimport failures with manifest issues
> > > >
> > > > **Summary:**
> > > >
> > > > When reimporting a build, the import could fail due to manifest validation issues, either stopping mid-import or reporting that the build was already being imported. Build reimport now correctly handles manifest validation and prevents duplicate import conflicts.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.7 is fully compatible with 5.1.6. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.6 → 5.1.7 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.7](./deployment-guidelines-v5.1.7).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Release Notes
Source: https://docs.flowx.ai/release-notes/overview

What shipped in every FlowX.AI release - new features, bug fixes, deployment guidelines, and migration steps for the 5.9.x and 5.1.x LTS lines and monthly feature releases.

Release notes · FlowX.AI

What shipped.
Every release, every line.

What shipped in every FlowX.AI release: new features, bug fixes, deployment guidelines, and migration steps. Pick your line below, or jump straight to the latest LTS patch and feature release.

[Latest LTS: 5.9.6](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[Feature release: 6.0.0](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

> [!NOTE]
>
> **Long Term Support (LTS) Versions:** LTS versions receive extended support with security updates and critical bug fixes. **5.9.x** is the current FlowX.AI LTS line, recommended for production environments requiring stability and long-term support. Support for the **5.1.x** line ended with 5.1.14, its final maintenance release. To keep receiving fixes, move to 5.9.x: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview). Release notes for older lines, including 5.1.x and 4.7.x, remain published for reference.
>
> **Feature Releases:** Versions released between LTS lines (such as 5.10.0) introduce new capabilities and are deployed to FlowX.AI SaaS environments as they ship. Self-hosted deployments receive these features consolidated into the next LTS release.

01 · Latest

## Latest releases

[LTS
v5.9.6
Maintenance release for the 5.9.x LTS line. Released on October 20th, 2026.](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)

[FEATURE
v6.0.0
Feature release, live on FlowX.AI SaaS. Released on October 30th, 2026.](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[LTS
v5.1.14
Final maintenance release for the 5.1.x LTS line. Released on October 30th, 2026.](./v5.x/v5.1.x-lts/v5.1.14-october-2026)

> [!TIP]
>
> **New cookbook:** [reconcile supplier invoices against purchase orders](/5.9/cookbooks/invoice-reconciliation), from email intake to exception review. More end-to-end builds are in the [cookbooks](/5.9/cookbooks/overview).

***

02 · All releases

## All releases

Planning a 5.9.x upgrade? The [5.9.x LTS changelog](./v5.x/5.9-lts-changelog) lists every change in each 5.9.x maintenance release on one page, with an RSS feed.

Moving from 5.9.x to 6.0.0? The [5.9.x to 6.0.0 changelog](./v6.x/5.9-to-6.0-changelog) lists every change from the 5.10 to 5.13 feature releases and 6.0.0 on one page, with an RSS feed.

versionlinereleased

[v6.0.0FRfeature releaseOctober 30th, 2026→](./v6.x/v6.0.0-october-2026/v6.0.0-october-2026)

[v5.1.14LTSmaintenance · 5.1.x LTS lineOctober 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.14-october-2026)
[v5.9.6LTSmaintenance · 5.9.x LTS lineOctober 20th, 2026→](./v5.x/v5.9.6-october-2026/v5.9.6-october-2026)
[v5.13.0FRfeature releaseSeptember 28th, 2026→](./v5.x/v5.13.0-september-2026/v5.13.0-september-2026)
[v5.9.5LTSmaintenance · 5.9.x LTS lineSeptember 23rd, 2026→](./v5.x/v5.9.5-september-2026/v5.9.5-september-2026)
[v5.1.13LTSmaintenance · 5.1.x LTS lineSeptember 18th, 2026→](./v5.x/v5.1.x-lts/v5.1.13-september-2026)
[v5.12.0FRfeature releaseSeptember 3rd, 2026→](./v5.x/v5.12.0-september-2026/v5.12.0-september-2026)
[v5.9.4LTSmaintenance · 5.9.x LTS lineAugust 27th, 2026→](./v5.x/v5.9.4-august-2026/v5.9.4-august-2026)
[v5.1.12LTSmaintenance · 5.1.x LTS lineAugust 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.12-august-2026)
[v5.11.0FRfeature releaseAugust 11th, 2026→](./v5.x/v5.11.0-august-2026/v5.11.0-august-2026)
[v5.9.3LTSmaintenance · 5.9.x LTS lineJuly 30th, 2026→](./v5.x/v5.9.3-july-2026/v5.9.3-july-2026)
[v5.1.11LTSmaintenance · 5.1.x LTS lineJuly 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.11-july-2026)
[v5.9.2LTSmaintenance · 5.9.x LTS lineJuly 10th, 2026→](./v5.x/v5.9.2-july-2026/v5.9.2-july-2026)
[v5.10.0FRfeature releaseJuly 7th, 2026→](./v5.x/v5.10.0-july-2026/v5.10.0-july-2026)
[v5.1.10LTSmaintenance · 5.1.x LTS lineJune 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.10-june-2026)
[v5.9.1LTSmaintenance · 5.9.x LTS lineJune 15th, 2026→](./v5.x/v5.9.1-june-2026/v5.9.1-june-2026)
[v5.9.0LTSfirst release of the 5.9.x LTS lineJune 2nd, 2026→](./v5.x/v5.9.0-june-2026/v5.9.0-june-2026)
[v5.1.9LTSLTS maintenance releaseMay 29th, 2026→](./v5.x/v5.1.x-lts/v5.1.9-may-2026)
[v5.8.0FRfeature releaseMay 10th, 2026→](./v5.x/v5.8.0-may-2026/v5.8.0-may-2026)
[v5.1.8LTSLTS maintenance releaseApril 30th, 2026→](./v5.x/v5.1.x-lts/v5.1.8-april-2026)
[v5.7.0FRfeature releaseApril 28th, 2026→](./v5.x/v5.7.0-april-2026/v5.7.0-april-2026)
[v5.6.0FRfeature releaseMarch 25th, 2026→](./v5.x/v5.6.0-march-2026/v5.6.0-march-2026)
[v5.1.7LTSLTS maintenance releaseMarch 26th, 2026→](./v5.x/v5.1.x-lts/v5.1.7-march-2026)
[v5.1.6LTSLTS maintenance releaseMarch 16th, 2026→](./v5.x/v5.1.x-lts/v5.1.6-march-2026)
[v5.5.0FRfeature releaseFebruary 27th, 2026→](./v5.x/v5.5.0-february-2026/v5.5.0-february-2026)
[v5.1.5LTSLTS maintenance releaseFebruary 27th, 2026→](./v5.x/v5.1.x-lts/v5.1.5-february-2026)
[v5.1.4LTSLTS maintenance releaseFebruary 9th, 2026→](./v5.x/v5.1.x-lts/v5.1.4-february-2026)
[v5.4.0FRfeature releaseJanuary 30th, 2026→](./v5.x/v5.4.0-january-2026/v5.4.0-january-2026)
[v5.1.3LTSLTS maintenance releaseJanuary 15th, 2026→](./v5.x/v5.1.x-lts/v5.1.3-january-2026)
[v5.3.0FRfeature releaseDecember 24th, 2025→](./v5.x/v5.3.0-december-2025/v5.3.0-december-2025)
[v5.1.2LTSLTS maintenance releaseDecember 3rd, 2025→](./v5.x/v5.1.x-lts/v5.1.2-december-2025)
[v5.2.0FRfeature releaseNovember 10th, 2025→](./v5.x/v5.2.0-november-2025/v5.2.0-november-2025)
[v5.1.1LTSLTS maintenance releaseNovember 10th, 2025→](./v5.x/v5.1.x-lts/v5.1.1-november-2025)
[v4.7.11LTSLTS maintenance releaseDecember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025)
[v4.7.10LTSLTS maintenance releaseNovember 17th, 2025→](./v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025)
[v4.7.9LTSLTS maintenance releaseOctober 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025)
[v5.1.0LTSLTS maintenance releaseOctober 2nd, 2025→](./v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025)
[v4.7.8LTSLTS maintenance releaseSeptember 16th, 2025→](./v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025)
[v4.7.7LTSLTS maintenance releaseAugust 20th, 2025→](./v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025)
[v5.0.0FRfeature releaseJuly 31st, 2025→](./v5.x/v5.0.0-july-2025/v5.0.0-july-2025)
[v4.7.6LTSLTS maintenance releaseJuly 18th, 2025→](./v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025)
[v4.7.5LTSLTS maintenance releaseJune 19th, 2025→](./v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025)
[v4.7.4LTSLTS maintenance releaseMay 15th, 2025→](./v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025)
[v4.7.3LTSLTS maintenance releaseApril 14th, 2025→](./v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025)
[v4.7.2LTSLTS maintenance releaseMarch 26th, 2025→](./v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025)
[v4.7.1LTSLTS maintenance releaseMarch 7th, 2025→](./v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025)
[v4.7.0LTSLTS maintenance releaseFebruary 24th, 2025→](./v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025)
[v4.6.1FRfeature releaseFebruary 7th, 2025→](./v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025)
[v4.6.0FRfeature releaseJanuary 23rd, 2025→](./v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025)
[v4.1.5LTSLTS maintenance releaseSeptember 23rd, 2024→](./v4.x/v4.1.x/v4.1.5-september-2024/v4.1.5-september-2024)
[v4.1.4LTSLTS maintenance releaseSeptember 6th, 2024→](./v4.x/v4.1.x/v4.1.4-september-2024/v4.1.4-september-2024)
[v4.1.3LTSLTS maintenance releaseAugust 12th, 2024→](./v4.x/v4.1.x/v4.1.3-august-2024/v4.1.3-august-2024)
[v4.1.2LTSLTS maintenance releaseJune 8th, 2024→](./v4.x/v4.1.x/v4.1.2-june-2024/v4.1.2-june-2024)
[v4.1.1LTSLTS maintenance releaseJune 17th, 2024→](./v4.x/v4.1.x/v4.1.1-june-2024/v4.1.1-june-2024)
[v4.1.0LTSLTS maintenance releaseMay 30th, 2024→](./v4.x/v4.1.x/v4.1.0-may-2024/v4.1.0-may-2024)
[v4.0.0FRfeature releaseApril 18th, 2024→](./v4.x/v4.0.0-april-2024/v4.0.0-april-2024)

> [!NOTE]
>
> Releases from the **4.5.x (tech preview)** and **4.2.x** lines are not listed above. You can find them in the sidebar under **Release Notes** → **v4.x**.

***

> [accordion] Version 3.x.x
>
> > [card] [v3.4.8 - June 2024](/release-notes/v3.x.x/v3.4.8-june-2024/v3.4.8-june-2024)
> >
> > Explore the latest enhancements and fixes introduced in June 2024.
>
> > [card] [v3.4.7 - January 2024](/release-notes/v3.x.x/v3.4.7-january-2024/v3.4.7-january-2024)
> >
> > Explore the latest enhancements and fixes introduced in January 2024.
>
> > [card] [v3.4.6 - December 2023](/release-notes/v3.x.x/v3.4.6-december-2023/v3.4.6-december-2023)
> >
> > Explore the latest enhancements and fixes introduced in December 2023.
>
> > [card] [v3.4.5 - November 2023](/release-notes/v3.x.x/v3.4.5-november-2023/v3.4.5-november-2023)
> >
> > Explore the latest enhancements and fixes introduced in November 2023.
>
> > [card] [v3.4.4 - November 2023](/release-notes/v3.x.x/v3.4.4-november-2023/v3.4.4-november-2023)
> >
> > Discover the significant changes and improvements made in November 2023.
>
> > [card] [v3.4.3 - October 2023](/release-notes/v3.x.x/v3.4.3-october-2023/v3.4.3-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.2 - October 2023](/release-notes/v3.x.x/v3.4.2-october-2023/v3.4.2-october-2023)
> >
> > Discover the significant changes and improvements made in October 2023.
>
> > [card] [v3.4.1 - September 2023](/release-notes/v3.x.x/v3.4.1-september-2023/v3.4.1-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.4.0 - September 2023](/release-notes/v3.x.x/v3.4.0-september-2023/v3.4.0-september-2023)
> >
> > Discover the significant changes and improvements made in September 2023.
>
> > [card] [v3.3.0 - July 2023](/release-notes/v3.x.x/v3.3.0-july-2023/v3.3.0-july-2023)
> >
> > Discover the significant changes and improvements made in July 2023.
>
> > [card] [v3.2.0 - April 2023](/release-notes/v3.x.x/v3.2.0-april-2023/v3.2.0-april-2023)
> >
> > Discover the significant changes and improvements made in April 2023.
>
> > [card] [v3.1.0 - March 2023](/release-notes/v3.x.x/v3.1.0-march-2023/v3.1.0-march-2023)
> >
> > Discover the significant changes and improvements made in March 2023.
>
> > [card] [v3.0.0 - February 2023](/release-notes/v3.x.x/v3.0.0-february-2023/v3.0.0-february-2023)
> >
> > Discover the significant changes and improvements made in February 2023.


# FlowX.AI 5.9.x LTS changelog
Source: https://docs.flowx.ai/release-notes/v5.x/5.9-lts-changelog

Every change in each FlowX.AI 5.9.x LTS maintenance release, grouped by type and component, with an RSS feed for upgrade planning.

This page lists every change in each 5.9.x LTS maintenance release, newest first. Use the RSS button at the top of the page to subscribe and get each new patch as it ships. Mobile renderers and the React Native SDK are covered in their own release notes. Moving to 6.0.0? See the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog).

**5.9.6**

October 2026

**Upgrade actions:** migrate to the `flowx-ai` Helm chart if you installed the `ai-platform` chart, create the `ai.flowx.build.deployment-failed.v1` Kafka topic and allow it in your ACLs, re-publish any build whose deployment failed shortly before the upgrade, review workflow node retry settings, grant the connection-test permissions to custom roles, and allow extra Integration Designer startup time on a large `workflow_instances` collection. Details are in the [5.9.6 upgrade notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026#upgrade-notes).

#### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

#### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect.
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#mongodb-setting-names).
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6) for its version.

#### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.6 release notes](/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026) · [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6)

**5.9.5**

September 2026

**Upgrade actions:** let the `ai-services` consumer group reach zero lag and allow the new AI consumer groups in Kafka ACLs, add private database hosts to the NoSQL DB runner allowlist, set every service-account client secret on `authorization-system`, rename `cache_error_total` in dashboards and alerts, re-expose `loggers` if you change log levels at runtime, and review the deployment guidelines if you had already turned on data partitioning, because the conversion to native partitions is one way. Details are in the [5.9.5 upgrade notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#upgrade-notes).

#### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026#native-postgresql-partitioning).

#### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.

#### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.5 release notes](/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026) · [5.9.5 deployment guidelines](/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5)

**5.9.4**

August 2026

**Upgrade actions:** move the registry out of `image.repository` if you embedded it there (no action if you set `global.imageRegistry`), grant the Liquibase lock permissions to each service's database user on Oracle, create the `flowx-events-gateway-sa` client yourself if you manage Keycloak clients outside the Helm charts, and move host apps that embed the Angular SDK to Angular 21. Details are in the [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4#configuration-changes).

#### Changed

* **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.
* **Angular SDK:** the Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps that embed the Angular SDK must be on Angular 21. The npm and node requirements are unchanged.
* **Cross-version import:** importing a project build or version exported from an older platform line completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten.
* **Database migrations:** the lock that guards Liquibase schema migrations at service startup is a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration releases its lock when the database closes the session. Service accounts no longer need the `pods/status` permission. Oracle deployments need new database grants.
* **Events Gateway:** authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`. Helm chart deployments where `authorization-system` runs its migrations with Keycloak admin access need no action.
* **Helm charts:** the container image reference is split into `image.registry` and `image.repository`. The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. The default image location is unchanged.
* **Integration Designer:** service startup no longer scans the full token-instance collection, and the run-list summary queries are indexed.
* **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.
* **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.

#### Fixed

* **Actions:** deleting an action whose business rule calls a function works instead of returning a server error.
* **Build export:** retrying a build export re-attempts a dependency library whose own export timed out, so the parent build can finish.
* **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output from trailing empty cells and rows.
* **Entry points:** the entry-point picker in version settings lists only processes and UI flows from the current project.
* **Gateways:** an expression that fails to evaluate on an exclusive gateway surfaces as an incident on the process instance instead of only in the service logs.
* **Generated documents:** a document whose storage write fails returns an error instead of being recorded as successful. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.
* **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is listed once instead of once per consuming project version.
* **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives during a background synchronization, and merging versions no longer fails with a navigation-areas error.
* **Renderers:** the document preview shows its subtitle, and the file-upload error message follows the configured theme.
* **Reusable UI templates:** static input mappings configured on a reusable template are applied at runtime.
* **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.
* **Task management:** the row-selection checkbox column no longer carries an invisible sort control that re-sorted the view and cleared the selection, and changing the page size no longer opens the wrong process from the list.
* **Themes and CMS resources:** exporting a theme no longer includes duplicate copies of system icons, and importing no longer leaves system substitution tags missing.
* **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.4 release notes](/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026) · [5.9.4 deployment guidelines](/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4)

**5.9.3**

July 2026

**Upgrade actions:** none. The new Events Gateway and Integration Designer settings ship with working defaults. Details are in the [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3#configuration-changes).

#### Changed

* **Events Gateway:** new settings tune the dedicated Redis connection pool for blocking reads, and the default blocking-read duration is lowered from 5 seconds to 1 second. If you set the blocking-read duration explicitly, review it against the new default.
* **Integration Designer:** a new setting sets the number of partitions for auto-created workflow Kafka topics. Existing topics are not modified.
* **Media Library:** PDF assets in the list can be opened in a new tab.
* **Process start:** web renderers keep the loading indicator visible until the first user task renders.

#### Fixed

* **Build import:** a transient database write conflict during a multi-dependency import no longer drops a dependency's build, which caused runtime errors on substitution tags and enumerations. Large imports may take slightly longer.
* **Date Picker:** the calendar anchors to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.
* **Designer:** opening Runtime after expanding a component's Permissions section no longer freezes the Designer, and a pending AI UI-generation draft no longer locks the process diagram read-only.
* **Projects:** creating a project with the same name as a deleted project returns a validation error instead of an internal server error.
* **Real-time event delivery:** the Events Gateway no longer leaks Redis connections. Blocking reads run on a dedicated connection pool with Redis Cluster support, so the gateway no longer needs periodic restarts under sustained load.
* **Task management:** deleting a swimlane allocation rule removes only that rule, clicking Save twice no longer creates duplicate rules, and task views no longer reset when the same view is open from different workspaces.
* **Workflows:** a workflow no longer freezes silently after a step exhausts its retries.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.3 release notes](/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026) · [5.9.3 deployment guidelines](/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3)

**5.9.2**

July 2026

**Upgrade actions:** update any Keycloak group mapper or external IdP claim that emits the end-user group `User` to `Users Group`, remove records of the organization-ID migration or other Liquibase changesets you marked as executed by hand on an earlier 5.9.x (contact FlowX support for the list first), upgrade the AI Platform chart and the core services together, and update dashboards, alerts, and log queries that match the `ai-platform-` service name prefix. Details are in the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#upgrade-overview).

#### New

* **AI agents and data models:** AI Designer and AI Developer use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it.
* **AI workflow nodes:** JSON schema fields support `${}` placeholders.
* **Chat file uploads:** end users can attach multiple files in a chat-driven app. Uploads are indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content.
* **Document Parser:** a new LiteParse engine parses PDFs and images locally without GPU or AI calls, and OCR supports English, Romanian, Hungarian, and Bulgarian.
* **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.
* **Knowledge bases:** a Custom Agent node can select multiple knowledge bases, each exposed to the agent as its own retrieval tool, and retrieval can span multiple knowledge bases in a workflow.
* **SQL data sources:** queries on SQL data sources can be tested from the builds list.
* **Use in reporting:** the reporting toggle is available on UI flows and workflows.

#### Changed

* **AI node structured output:** responses from AI nodes with a response schema are validated against it, with automatic repair retries, and node logs include the failure reason and rejected output.
* **AI Platform services:** services are deployed under their plain names, without the `ai-platform-` prefix on pod, service, and image names, and the bundled Qdrant subchart is renamed the same way. Core services resolve AI components by the new names.
* **Audit log:** records sharing, user invitations, designer-user, end-user, and group management, actions on process instances and UI flows, adding a dependency, and terminating process, workflow, or UI flow instances.
* **Copy to project:** copying a process or UI flow to another project also copies its roles.
* **Data archiving:** archiving detaches a partition only when every process or workflow instance in it has finished. New settings for terminating stuck instances and backfilling legacy rows are off by default.
* **Default end-user group:** the group that the 5.1.x upgrade migration creates is renamed from `User` to `Users Group`. Groups your admins created are not renamed.
* **Designer:** the Event Handlers section appears higher in the component configuration panel, and the keys to save for collection items and bundled custom-component inputs are computed automatically.
* **Kafka reconnects:** platform services use a gentler broker-reconnect backoff by default, and repeated Kafka connection errors log at a quieter level.

#### Fixed

* **Active policy:** the user list on the override active-policy form is no longer empty.
* **Application manager:** the runtime-application organization-ID migration converts existing data correctly.
* **Audit logs:** filtering audit entries by user works when the username differs from the email address.
* **Build export with media files:** exporting a build with media file content produces an archive that contains the binaries.
* **Chat:** the floating chat position is calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.
* **CMS enumerations:** cascading-enum value lookups resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.
* **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.
* **Data sync with private CA certificates:** data-sync migrations that call HTTPS endpoints, such as Keycloak, no longer fail certificate validation in environments that use an internal certificate authority.
* **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.
* **Project version merge:** a merge no longer fails with a 500 error.
* **Redis Cluster:** UI template cache keys map to the same cluster slot, which prevents cross-slot errors.
* **Reusable UI templates:** actions are no longer missing at runtime when a template is nested in multiple levels of containers.
* **Self-hosted installation and upgrade:** Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding work on self-hosted environments.
* **Workflow data:** archiving batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine is fixed.
* Stability fixes across the Designer, the renderers, and the backend services.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.2 release notes](/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026) · [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2)

**5.9.1**

June 2026

**Upgrade actions:** none for deployments where the Helm chart provisions Kafka topics. If you provision Kafka topics or ACLs manually, create the topics added in 5.9.1. Details are in the [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics).

#### New

* **AI permissions:** AI runtime usage and AI build-time tooling (AI Designer, agent building, code generation) are governed by two separate permissions. When AI is turned off, AI icons and entry points are hidden instead of shown disabled, and build-time helpers such as code generation and "Add comment" follow the dev-agent permission.
* **File Preview:** scroll-trigger event handlers, including a "document end" trigger, let a flow detect when a user scrolls through a document or reaches its end, for example to enable an **Accept** button only after the user reaches the end of an agreement.
* **File upload:** the upload button supports a configurable icon, set in the Designer.
* **Microsoft Outlook:** connections support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
* **Script engine:** business rules, reusable functions, and node rules can each run on the native engine (the 5.9 default) or the legacy GraalVM engine. Rules created before the switch to native keep running on GraalVM until you migrate them, and new rules default to native.

#### Changed

* **AI Designer:** generates UI from a flat template format instead of 3-level nesting, supports more component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates incrementally instead of regenerating them, and can generate reusable UI templates.
* **Kafka topics:** new topics carry runtime config-param change events, runtime instance terminations, resource cache evictions, and evaluation improvement suggestions. The Helm chart provisions them.
* **Merge conflicts:** merge-conflict handling for custom components and UI Flows identifies resources more clearly.
* **Organization settings:** navigation and design improvements.
* **Platform Status:** reports AI Platform components and their databases alongside the core services.
* **Runtime config params:** changes reach the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
* **Workflows:** storage of running steps is optimized, workflows and processes launched from a UI Flow inherit the build of the parent UI Flow, and AI node failures show the error details and model reasoning in the workflow run logs.

#### Fixed

* **Actions:** GET actions no longer fire with undefined parameters.
* **AI chat:** agent responses no longer reappear in chat after stop and refresh, and the builder-agent chat no longer duplicates messages.
* **Copy to project:** copying a process or workflow to another project succeeds, and copied workflows appear in the target project.
* **End-user login:** a null value is no longer cached when looking up the "All end-users" group, which could block logins until data sync completed.
* **File Preview:** previews render correctly, events fire inside collections, a fixed height applies at runtime, and preview resources no longer fail with CORS errors.
* **File Storage:** FTP test connection and file operations resolve configuration-parameter placeholders, and FTP file preview works when the root path has no leading slash.
* **Forms to validate:** scrolling covers the full component hierarchy, placeholders update, and chat and tab-bar components are selected correctly.
* **Hide and disable conditions:** conditions on UI templates, processes, and UI Flows apply at runtime for Designer users without workspace access.
* **Invitations:** an invited Designer user added as an Organization owner is assigned to a workspace.
* **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
* **Modals:** dropdowns no longer flicker, and long key names no longer break the layout.
* **Process instances:** loading an instance with a very large execution graph no longer crashes the browser.
* **Task management:** headers follow the theme in React and Angular, and the filter window no longer disappears after applying criteria.
* **Theme admin:** "copy to" no longer loses theme content.
* **Timer events:** activating a start timer event after a new build regenerated the process resource ID no longer fails with a 500 (duplicate key) error.
* **UI Flow:** images display in preview after refresh, and returning from an expired UI Flow no longer loses the theme UUID.
* **Usage Overview:** opening a usage overview no longer fails with a 500 error.
* **Web renderer:** the button shadow and modal content padding are restored, and components render when a media-file storage path is null.
* **Workflows:** END PARALLEL output no longer includes data from before the parallel branches started, and NoSQL node run logs no longer crash when a node fails before building its options.

#### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.

[5.9.1 release notes](/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026) · [5.9.1 deployment guidelines](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1)


# Deployment guidelines v5.1.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.10 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.9 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.9 → 5.1.10**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **process-engine** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **admin** | 9.75.7 | 9.75.3 | 9.74.4 | 9.73.1 |
| **designer** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **cms-core** | 9.46.3 | 9.46.2 | 9.45.4 | 9.44.2 |
| **scheduler-core** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **events-gateway** | 9.36.4 | 9.36.2 | 9.35.4 | 9.34.1 |
| **notification-plugin** | 9.39.3 | 9.39.2 | 9.38.4 | 9.37.1 |
| **document-plugin** | 9.44.3 | 9.44.2 | 9.43.4 | 9.42.2 |
| **task-management-plugin** | 9.43.3 | 9.43.2 | 9.42.4 | 9.41.1 |
| **data-search** | 9.32.3 | 9.32.2 | 9.31.4 | 9.30.1 |
| **audit-core** | 9.40.3 | 9.40.2 | 9.39.4 | 9.38.1 |
| **advancing-controller** | 9.35.3 | 9.35.2 | 9.34.4 | 9.33.1 |
| **integration-designer** | 9.59.4 | 9.59.3 | 9.58.5 | 9.57.1 |
| **application-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **runtime-manager** | 9.82.5 | 9.82.2 | 9.81.4 | 9.80.2 |
| **data-sync** | 9.33.4 | 9.33.2 | 9.32.3 | 9.31.1 |
| **authorization-system** | 9.43.5 | 9.43.2 | 9.42.4 | 9.41.1 |
| **nosql-db-runner** | 9.31.3 | 9.31.2 | 9.30.4 | 9.29.1 |

### Renderers

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | 9.164.10 | 9.164.4 | 9.164.2 | 9.164.2 |
| **iOS renderer** | 9.0.25 | 9.0.20 | 9.0.19 | 9.0.12 |
| **Android renderer** | 9.0.31 | 9.0.24 | 9.0.19 | 9.0.13 |

### Plugins

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.7 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.10 | 5.1.9 | 5.1.8 | 5.1.7 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.10 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** starting with 5.1.10 the default Redis read mode is `polling` (`EVENTS_REDIS_MODE`). This is applied automatically on upgrade; no action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.9 processes and configurations

### What's included in 5.1.10

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.10 Release Notes](./v5.1.10-june-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.10 | Keycloak | 26+ |
| 5.1.10 | Kafka | 3.8 - 3.9 |
| 5.1.10 | PostgreSQL | 16 - 17 |
| 5.1.10 | Oracle Database | 21c, 23ai |
| 5.1.10 | MongoDB | 7 - 8 |
| 5.1.10 | Redis | 7.4 - 8.0 |
| 5.1.10 | Elasticsearch | 8 - 9 |
| 5.1.10 | Angular (Web SDK) | 19.2 |
| 5.1.10 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.11 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.10 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.10 → 5.1.11**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **process-engine** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **admin** | 9.76.3 | 9.75.7 | 9.75.3 | 9.74.4 |
| **designer** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **cms-core** | 9.47.3 | 9.46.3 | 9.46.2 | 9.45.4 |
| **scheduler-core** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **events-gateway** | 9.37.3 | 9.36.4 | 9.36.2 | 9.35.4 |
| **notification-plugin** | 9.40.3 | 9.39.3 | 9.39.2 | 9.38.4 |
| **document-plugin** | 9.45.3 | 9.44.3 | 9.44.2 | 9.43.4 |
| **task-management-plugin** | 9.44.4 | 9.43.3 | 9.43.2 | 9.42.4 |
| **data-search** | 9.33.3 | 9.32.3 | 9.32.2 | 9.31.4 |
| **audit-core** | 9.41.3 | 9.40.3 | 9.40.2 | 9.39.4 |
| **advancing-controller** | 9.36.3 | 9.35.3 | 9.35.2 | 9.34.4 |
| **integration-designer** | 9.60.3 | 9.59.4 | 9.59.3 | 9.58.5 |
| **application-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **runtime-manager** | 9.83.5 | 9.82.5 | 9.82.2 | 9.81.4 |
| **data-sync** | 9.34.2 | 9.33.4 | 9.33.2 | 9.32.3 |
| **authorization-system** | 9.44.4 | 9.43.5 | 9.43.2 | 9.42.4 |
| **nosql-db-runner** | 9.32.3 | 9.31.3 | 9.31.2 | 9.30.4 |

### Renderers

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/react-ui-toolkit** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-sdk** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **@flowx/core-theme** | 9.164.15 | 9.164.10 | 9.164.4 | 9.164.2 |
| **iOS renderer** | 9.0.27 | 9.0.25 | 9.0.20 | 9.0.19 |
| **Android renderer** | 9.0.37 | 9.0.31 | 9.0.24 | 9.0.19 |

### Plugins

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.7 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.11 | 5.1.10 | 5.1.9 | 5.1.8 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.11 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway — real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.10 processes and configurations

### What's included in 5.1.11

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.11 Release Notes](./v5.1.11-july-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.11 | Keycloak | 26+ |
| 5.1.11 | Kafka | 3.8, 3.9 |
| 5.1.11 | PostgreSQL | 16, 17 |
| 5.1.11 | Oracle Database | 21c, 23ai |
| 5.1.11 | MongoDB | 7, 8 |
| 5.1.11 | Redis | 7, 8 |
| 5.1.11 | Elasticsearch | 8 |
| 5.1.11 | Angular (Web SDK) | 19.2 |
| 5.1.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.12

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.12 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.11 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.11 → 5.1.12**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **process-engine** | 9.76.7 | 9.76.3 | 9.75.7 | 9.75.3 |
| **admin** | 9.76.6 | 9.76.3 | 9.75.7 | 9.75.3 |
| **designer** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **cms-core** | 9.47.5 | 9.47.3 | 9.46.3 | 9.46.2 |
| **scheduler-core** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **events-gateway** | 9.37.4 | 9.37.3 | 9.36.4 | 9.36.2 |
| **notification-plugin** | 9.40.4 | 9.40.3 | 9.39.3 | 9.39.2 |
| **document-plugin** | 9.45.4 | 9.45.3 | 9.44.3 | 9.44.2 |
| **task-management-plugin** | 9.44.6 | 9.44.4 | 9.43.3 | 9.43.2 |
| **data-search** | 9.33.4 | 9.33.3 | 9.32.3 | 9.32.2 |
| **audit-core** | 9.41.4 | 9.41.3 | 9.40.3 | 9.40.2 |
| **advancing-controller** | 9.36.4 | 9.36.3 | 9.35.3 | 9.35.2 |
| **integration-designer** | 9.60.5 | 9.60.3 | 9.59.4 | 9.59.3 |
| **application-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **runtime-manager** | 9.83.7 | 9.83.5 | 9.82.5 | 9.82.2 |
| **data-sync** | 9.34.3 | 9.34.2 | 9.33.4 | 9.33.2 |
| **authorization-system** | 9.44.5 | 9.44.4 | 9.43.5 | 9.43.2 |
| **nosql-db-runner** | 9.32.4 | 9.32.3 | 9.31.3 | 9.31.2 |

### Renderers

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-sdk** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **@flowx/core-theme** | 9.165.2 | 9.164.15 | 9.164.10 | 9.164.4 |
| **iOS renderer** | 9.0.29 | 9.0.27 | 9.0.25 | 9.0.20 |
| **Android renderer** | 9.0.39 | 9.0.37 | 9.0.31 | 9.0.24 |

### Plugins

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.7 | 0.2.6 |

### AI Platform

| Component | 5.1.12 | 5.1.11 | 5.1.10 | 5.1.9 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.12 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.11 processes and configurations

### What's included in 5.1.12

This maintenance release includes:

* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.12 Release Notes](./v5.1.12-august-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.12 | Keycloak | 26+ |
| 5.1.12 | Kafka | 3.8, 3.9 |
| 5.1.12 | PostgreSQL | 16, 17 |
| 5.1.12 | Oracle Database | 21c, 23ai |
| 5.1.12 | MongoDB | 7, 8 |
| 5.1.12 | Redis | 7, 8 |
| 5.1.12 | Elasticsearch | 8 |
| 5.1.12 | Angular (Web SDK) | 19.2 |
| 5.1.12 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.13
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.13

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.13 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.12 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.12 → 5.1.13**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **process-engine** | 9.76.10 | 9.76.7 | 9.76.3 | 9.75.7 |
| **admin** | 9.76.8 | 9.76.6 | 9.76.3 | 9.75.7 |
| **designer** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **cms-core** | 9.47.6 | 9.47.5 | 9.47.3 | 9.46.3 |
| **scheduler-core** | 9.36.5 | 9.36.4 | 9.36.3 | 9.35.3 |
| **events-gateway** | 9.37.5 | 9.37.4 | 9.37.3 | 9.36.4 |
| **notification-plugin** | 9.40.5 | 9.40.4 | 9.40.3 | 9.39.3 |
| **document-plugin** | 9.45.5 | 9.45.4 | 9.45.3 | 9.44.3 |
| **task-management-plugin** | 9.44.7 | 9.44.6 | 9.44.4 | 9.43.3 |
| **data-search** | 9.33.5 | 9.33.4 | 9.33.3 | 9.32.3 |
| **audit-core** | 9.41.5 | 9.41.4 | 9.41.3 | 9.40.3 |
| **advancing-controller** | 9.36.6 | 9.36.4 | 9.36.3 | 9.35.3 |
| **integration-designer** | 9.60.7 | 9.60.5 | 9.60.3 | 9.59.4 |
| **application-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **runtime-manager** | 9.83.8 | 9.83.7 | 9.83.5 | 9.82.5 |
| **data-sync** | 9.34.4 | 9.34.3 | 9.34.2 | 9.33.4 |
| **authorization-system** | 9.44.6 | 9.44.5 | 9.44.4 | 9.43.5 |
| **nosql-db-runner** | 9.32.5 | 9.32.4 | 9.32.3 | 9.31.3 |

### Renderers

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-sdk** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **@flowx/core-theme** | 9.165.3 | 9.165.2 | 9.164.15 | 9.164.10 |
| **iOS renderer** | 9.0.32 | 9.0.29 | 9.0.27 | 9.0.25 |
| **Android renderer** | 9.0.44 | 9.0.39 | 9.0.37 | 9.0.31 |

### Plugins

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.7 |

### AI Platform

| Component | 5.1.13 | 5.1.12 | 5.1.11 | 5.1.10 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.13 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.12 processes and configurations

### What's included in 5.1.13

This maintenance release includes:

* **Reliability fixes** for process advancing under load
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.13 Release Notes](./v5.1.13-september-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.13 | Keycloak | 26+ |
| 5.1.13 | Kafka | 3.8, 3.9 |
| 5.1.13 | PostgreSQL | 16, 17 |
| 5.1.13 | Oracle Database | 21c, 23ai |
| 5.1.13 | MongoDB | 7, 8 |
| 5.1.13 | Redis | 7, 8 |
| 5.1.13 | Elasticsearch | 8 |
| 5.1.13 | Angular (Web SDK) | 19.2 |
| 5.1.13 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# Deployment guidelines v5.1.14
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.14

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.14 is the final planned maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.13 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.13 → 5.1.14**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **process-engine** | 9.76.12 | 9.76.10 | 9.76.7 | 9.76.3 |
| **admin** | 9.76.10 | 9.76.8 | 9.76.6 | 9.76.3 |
| **designer** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **cms-core** | 9.47.8 | 9.47.6 | 9.47.5 | 9.47.3 |
| **scheduler-core** | 9.36.7 | 9.36.5 | 9.36.4 | 9.36.3 |
| **events-gateway** | 9.37.7 | 9.37.5 | 9.37.4 | 9.37.3 |
| **notification-plugin** | 9.40.7 | 9.40.5 | 9.40.4 | 9.40.3 |
| **document-plugin** | 9.45.7 | 9.45.5 | 9.45.4 | 9.45.3 |
| **task-management-plugin** | 9.44.9 | 9.44.7 | 9.44.6 | 9.44.4 |
| **data-search** | 9.33.7 | 9.33.5 | 9.33.4 | 9.33.3 |
| **audit-core** | 9.41.8 | 9.41.5 | 9.41.4 | 9.41.3 |
| **advancing-controller** | 9.36.8 | 9.36.6 | 9.36.4 | 9.36.3 |
| **integration-designer** | 9.60.9 | 9.60.7 | 9.60.5 | 9.60.3 |
| **application-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **runtime-manager** | 9.83.10 | 9.83.8 | 9.83.7 | 9.83.5 |
| **data-sync** | 9.34.6 | 9.34.4 | 9.34.3 | 9.34.2 |
| **authorization-system** | 9.44.8 | 9.44.6 | 9.44.5 | 9.44.4 |
| **nosql-db-runner** | 9.32.7 | 9.32.5 | 9.32.4 | 9.32.3 |

### Renderers

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-sdk** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **@flowx/core-theme** | 9.165.4 | 9.165.3 | 9.165.2 | 9.164.15 |
| **iOS renderer** | 9.0.38 | 9.0.32 | 9.0.29 | 9.0.27 |
| **Android renderer** | 9.0.48 | 9.0.44 | 9.0.39 | 9.0.37 |

### Plugins

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 |
| **reporting-plugin** | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.8 |

### AI Platform

| Component | 5.1.14 | 5.1.13 | 5.1.12 | 5.1.11 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agents** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-conversations** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-models** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-tenants** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-planner** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |
| **ai-platform-binaries** | 9.4.8 | 9.4.8 | 9.4.8 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Version | Description |
| - | - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | 1.52.0 | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | 1.25.1 | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It handles operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | 25.0.0-preview6 | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.14 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release. The audit index retention settings below are optional.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted | audit-core |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only | audit-core |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch).

> [!NOTE]
>
> **Events Gateway, real-time event delivery:** the default Redis read mode on the 5.1.x line remains `polling` (`EVENTS_REDIS_MODE`), introduced in 5.1.10. No action is required. If you previously set `EVENTS_REDIS_MODE=blocking` explicitly, switch it to `polling`.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.13 processes and configurations

### What's included in 5.1.14

This maintenance release includes:

* **Android renderer fix** for the action loader on modal screens
* **Optional audit index retention** and shard-size rollover settings
* **Security patches and dependency upgrades** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.14 Release Notes](./v5.1.14-october-2026).

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.14 | Keycloak | 26+ |
| 5.1.14 | Kafka | 3.8, 3.9 |
| 5.1.14 | PostgreSQL | 16, 17 |
| 5.1.14 | Oracle Database | 21c, 23ai |
| 5.1.14 | MongoDB | 7, 8 |
| 5.1.14 | Redis | 7, 8 |
| 5.1.14 | Elasticsearch | 8 |
| 5.1.14 | Angular (Web SDK) | 19.2 |
| 5.1.14 | React (Web SDK) | 18.x |

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.


# FlowX.AI 5.1.10 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.10-june-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.9 → 5.1.10** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.10 includes bug fixes and security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Active policy and iOS renderer fixes
> * Real-time event delivery stability improvement (Events Gateway)
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.9

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Reusable UI templates:** fixed several issues affecting reusable UI templates: actions remaining mapped after changing dependency versions, undo/redo leaving an action without a name or unable to save, data-slice and mapping requests returning 400 after a data-model key was renamed, duplicate entries returned for available templates, the "open in new tab" flag not being saved on UI action mappings, actions going missing when the same template is nested at multiple container levels, and conditional styling and validators being applied incorrectly when the same template is used more than once in a single user task.
> > > >
> > > > * **Active policy:** fixed an issue where the user list could appear empty on the override active-policy form.
> > > >
> > > > * **Project version merge:** fixed a 500 error that could occur when merging app versions.&#x20;
> > > >
> > > > * **Organization settings:** fixed the runtime users list failing to load.&#x20;
> > > >
> > > > - **Real-time event delivery:** improved Redis connection stability under sustained load. The Events Gateway now uses polling as the default mode for reading real-time events from Redis, preventing the gradual connection buildup that could previously require periodic Events Gateway restarts. The change applies automatically on upgrade; no configuration is required.
> > > > - **Renderer:** accordion card height and custom styles now follow the component's opened state, and gap spacing is applied correctly to collections.
> > > > - **Process instances:** fixed duplicate API calls and rendering errors when navigating between process instances.
> > > > - **iOS renderer:** broad VoiceOver and accessibility improvements across components (form fields, file preview, sliders, date picker, validation messages), and fixed form view-model lookup for forms nested in collections.
> > > > - **Android renderer:** component sizing now includes padding on text, link, markdown, and image components; fixed a TopAppBar crash in some configurations, tooltip icon overrides, slider step rounding, document preview caching, and resilience to process death.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.10 is fully compatible with 5.1.9. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.9 → 5.1.10 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.10](./deployment-guidelines-v5.1.10).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.11 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.11-july-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.10 → 5.1.11** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.11 includes bug fixes and security patches:
>
> * Audit log and task management fixes
> * Project creation error-handling fix
> * Security patches and dependency upgrades
> * No breaking changes; fully compatible upgrade from 5.1.10

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Audit log:** filtering by user now returns results when a user's username differs from their email address.
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it.
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.11 is fully compatible with 5.1.10. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.10 → 5.1.11 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.11](./deployment-guidelines-v5.1.11).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.12 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.12-august-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.11 → 5.1.12** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.12 includes bug fixes for library resources and task management:
>
> * Library process resource overview fixes
> * Task management sort control fix
> * No breaking changes; fully compatible upgrade from 5.1.11

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Bug fixes for library resource overview and task management
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.12 is fully compatible with 5.1.11. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.11 → 5.1.12 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.12](./deployment-guidelines-v5.1.12).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.13 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.13-september-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **security patches**. Upgrades from **5.1.12 → 5.1.13** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance release.** FlowX.AI 5.1.13 includes reliability fixes for process advancing, a process designer fix, and security patches:
>
> * Process advancing fixes that prevent lost or stalled process advances under load
> * Action deletion fix for business rules that call reusable functions
> * Security patches and dependency upgrades across platform components
> * No breaking changes; fully compatible upgrade from 5.1.12

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and security patches across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) - Process advancing reliability fixes, a process designer fix, and security patches
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Process advancing:** the partition cleanup job no longer deletes advance events that are accepted while cleanup is running. Event insertion and cleanup now coordinate through database row locks, on both PostgreSQL and Oracle, so a process advance can no longer be lost to a concurrent cleanup.&#x20;
> > > > * **Process advancing:** advancing workers no longer pause for cooldown while work is still queued, and event completion is retried after a database deadlock instead of leaving an already-processed event marked as in progress.&#x20;
> > > > * **Process designer:** deleting an action no longer fails with a server error when one of its business rules calls a reusable function.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components. The Java runtime base images move to Eclipse Temurin 21.0.12 with a refreshed OS package layer.&#x20;
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.13 is fully compatible with 5.1.12. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.12 → 5.1.13 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.13](./deployment-guidelines-v5.1.13).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.14 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.14-october-2026

Final maintenance release for the FlowX.AI 5.1.x LTS line. Audit index retention settings, an Android SDK loader fix, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.1.x** line, focused on **bug fixes** and **security patches**. Upgrades from **5.1.13 → 5.1.14** are non-breaking and fully compatible. FlowX.AI 5.1.14 is the final planned maintenance release of the 5.1.x line. To keep receiving fixes, plan your move to the 5.9.x LTS line: see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [card] Release Highlight
>
> **FlowX.AI 5.1.14** is a maintenance release for the 5.1.x LTS:
>
> * **Audit index retention:** optional settings to delete old audit data and roll audit indices over by shard size
> * **Key fixes:** the Android SDK loader shows on modal screens and no longer stays stuck after repeated taps
> * Security patches and dependency upgrades. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.1.14 is fully compatible with 5.1.13. No breaking changes, no database migrations, and no required configuration changes; standard deployment procedures apply.

**Upgrade path:** direct upgrade from 5.1.13.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x. Component versions are listed in the [5.1.14 deployment guidelines](./deployment-guidelines-v5.1.14).

***

## Full changelog

### New

* **Audit:** set how long audit data is kept, and roll audit indices over when a primary shard reaches a set size, with two new environment variables. Both are off by default, so the Audit service deletes nothing until you set a retention period. See [Configuring Elasticsearch](/5.1/setup-guides/audit-setup-guide#configuring-elasticsearch) and the [deployment guidelines](./deployment-guidelines-v5.1.14#new-environment-variables-audit-index-retention).&#x20;

### Fixed

* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.1.9 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.9-may-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.8 → 5.1.9** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.9 delivers notable bug fixes alongside security patches:
>
> * Reusable UI template mapping and Designer fixes
> * Android renderer fixes
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.8

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Bug fixes, security patches, and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Advancing workers** — Improved connection management so advancing workers no longer accumulate database connections across cooldown and rampup cycles, preventing connection growth on long-running runtime deployments.
> > > > * **Reusable UI templates** — Fixed an issue where input and output mappings on reusable UI templates could be silently lost when a referenced library version was updated.
> > > > * **Designer** — Fixed server errors when bulk-editing UI templates and when patching UI actions inside reusable UI templates.
> > > > * **Android renderer** — Fixed sticky container behavior across nested hierarchy levels, and deferred the custom loader display until CMS resources are available.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.9 is fully compatible with 5.1.8. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.8 → 5.1.9 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.9](./deployment-guidelines-v5.1.9).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.10
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10

Component versions and deployment notes for FlowX.AI 5.10 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.10 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.10.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.10.0 |
| - | - |
| **admin** | 11.18.0 |
| **advancing-controller** | 11.12.0 |
| **application-manager** | 11.18.0 |
| **audit-core** | 11.11.0 |
| **authorization-system** | 11.14.0 |
| **cms-core** | 11.14.0 |
| **data-search** | 11.11.0 |
| **data-sync** | 11.9.0 |
| **designer** | 11.36.1 |
| **document-plugin** | 11.19.0 |
| **email-gateway** | 11.15.0 |
| **events-gateway** | 11.14.0 |
| **file-gateway** | 11.14.0 |
| **integration-designer** | 11.24.2 |
| **license** | 11.13.0 |
| **nosql-db-runner** | 11.14.0 |
| **notification-plugin** | 11.14.0 |
| **organization-manager** | 11.14.0 |
| **process-engine** | 11.19.3 |
| **runtime-manager** | 11.18.0 |
| **scheduler-core** | 11.11.0 |
| **task-management-plugin** | 11.15.0 |
| **webhook-gateway** | 11.13.0 |

### AI base components

| Component | 5.10.0 |
| - | - |
| **embedder** | 11.2.0 |
| **knowledgebase-indexer-v2** | 11.2.0 |
| **knowledgebase-rag** | 11.2.0 |
| **doc-parser** | 11.2.0 |

### AI dev-time components

| Component | 5.10.0 |
| - | - |
| **ai-gateway** | 11.15.1 |
| **ai-analyst** | 11.2.0 |
| **ai-assistant** | 11.2.0 |
| **ai-designer** | 11.2.0 |
| **ai-developer** | 11.2.0 |
| **kb-enrichment** | 11.2.0 |
| **planner** | 11.2.0 |

### AI runtime components

| Component | 5.10.0 |
| - | - |
| **agent-builder** | 11.2.0 |
| **data-privacy** | 11.2.0 |
| **doc-converter** | 11.2.0 |
| **dynamic-classifier** | 11.2.0 |
| **evals-judge** | 11.2.0 |
| **speech-to-text** | 11.2.0 |
| **web-crawler** | 11.2.0 |

### AI extensions

| Component | 5.10.0 |
| - | - |
| **modpod** | 11.2.0 |
| **observatory-api** | 11.0.2 |
| **observatory-platform** | 11.0.2 |
| **observatory-web** | 11.0.2 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments receive them, re-verified, with the next LTS release.

### New Kafka topics

| Topic | Producer → Consumer | Purpose |
| - | - | - |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin → process-engine | Resource cache eviction |
| `ai.flowx.config.params.events.v1` | application-manager → process-engine | Config-param change notifications |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine → integration-designer | Runtime-instance termination |
| `ai.flowx.evals.suggestions.job.request.v1` / `.response.v1` | integration-designer | Evals suggestions job requests and responses |

### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them when your environment moves to 5.10.

This release also adds a new AI Platform component, **dynamic-classifier** (listed under AI runtime components above), which backs document classification.

In `admin`, the single `FLOWX_FEATUREAVAILABILITY_AISERVICENAME` setting is replaced by two, reflecting the split between AI dev-time and AI runtime services: `FLOWX_FEATUREAVAILABILITY_AIDEVTIMESERVICENAME` (default `ai-gateway-mngt`) and `FLOWX_FEATUREAVAILABILITY_AIRUNTIMESERVICENAME` (default `agent-builder-mngt`).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.10.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026

What's new in FlowX.AI 5.10: PostgreSQL and SOAP data sources, AI Developer script-node code generation, file uploads in chat-driven apps, and AI and document-intelligence improvements.

[FlowX.AI 5.10 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.10.0.html)

> [!NOTE]
>
> **FlowX.AI 5.10 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments receive them with the next LTS release.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release adds PostgreSQL and SOAP data sources, multi-file upload in chat-driven apps, and a set of AI and document-intelligence capabilities, alongside broader audit coverage, roles that travel with copied resources, and workflow data-partitioning improvements.

***

**What's new?**

> [tab] Core & Platform
>
> 🗂️ [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions\
> 📑 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources\
> ⚡ [**Platform performance and fixes**](#platform-performance-and-fixes) - Task-manager user fetch, project versioning, export/merge

> [tab] Designer & Renderer
>
> 💬 [**Chat file upload**](#chat-file-upload) - Attach multiple files in conversational apps\
> ⬇️ [**File download component**](#file-download-component) - Download files from a rendered app (web and Android)\
> 🔀 [**Conditional event-handler triggers**](#conditional-event-handler-triggers) - Fire event handlers based on a condition\
> 🎨 [**Image color property**](#image-color-property) - Color control on the IMAGE component\
> 💾 [**Save local variable**](#save-local-variable-action) - Capture a collection row into local data on click\
> 🪟 [**Global header and footer**](#global-header-and-footer) - Consistent header and footer across a UI Flow\
> 🧩 [**Reusable UI templates**](#reusable-ui-templates) - Action mapping, undo/redo, and dependency-version fixes

> [tab] Integrations & Data
>
> 🐘 [**PostgreSQL data source**](#postgresql-data-source) - Connect workflows directly to PostgreSQL and run SQL queries\
> 🧼 [**SOAP integration**](#soap-integration) - Import a WSDL and call SOAP operations from workflows\
> 🧮 [**FlowX Database aggregation**](#flowx-database-aggregation) - MongoDB aggregation pipelines\
> 🗄️ [**Documents tab in database testing**](#documents-tab-in-database-testing) - Inspect data while testing DB operations

> [tab] AI & Documents
>
> 📊 [**Tabular data extraction node**](#tabular-data-extraction-node) - Read spreadsheets and CSV into workflow data\
> 🔁 [**Knowledge Base error handling**](#knowledge-base-error-handling-and-retry) - Retry failed KB ingestion\
> ✨ [**AI Developer: script-node code**](#ai-developer-generate-script-node-code) - Generate node code from a prompt\
> 🧪 [**AI evaluation experiments**](#ai-evaluation-experiments) - Multiple datasets and improvement suggestions\
> 🛡️ [**AI node output reliability**](#ai-node-output-reliability) - Schema validation with auto-repair and clearer run errors\
> 📝 [**Template Filling node**](#template-filling-node) - Generate documents from templates in workflows\
> 🗂️ [**File manipulation nodes**](#file-manipulation-nodes) - Combine and split files in workflows\
> 📄 [**DOCX document generation**](#docx-document-generation) - Generate documents as DOCX in addition to PDF\
> 🏷️ [**Document Tag**](#document-tag-renamed-from-document-type) - "Document Type" renamed\
> 🔑 [**Mistral model provider**](#mistral-model-provider) - Bring your own Mistral API key

### **Expanded audit logging**

> [card] Broader audit coverage for access and lifecycle actions
>
> Audit logging now records a wider set of actions: **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> All Deployments

### **Copy with roles**

> [card] Roles travel with copied resources
>
> Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> All Deployments

### **Platform performance and fixes**

> [card] Platform performance and fixes
>
> > [tab] Performance
> >
> > The task manager fetches users through the authorization-system instead of calling Keycloak directly, cutting per-request identity lookups.&#x20;
> >
> > MongoDB partition archiving scales for large datasets, with partition-ID backfill for legacy data and archiving fixes on PostgreSQL and Oracle.&#x20;
>
> > [tab] Bug fixes
> >
> > > [accordion] Core platform fixes
> > >
> > > * **Project selector:** projects without a work-in-progress branch are correctly shown as unavailable.&#x20;
> > > * **Start Solution:** no longer fails with "no entry point set" until the page is refreshed.&#x20;
> > > * **Export and merge:** fixed errors when exporting a project build with imported libraries and when merging project versions, including a 500 during merge.&#x20;
> > > * **Merge-conflict checks:** no longer fail on processes that contain conflicts.&#x20;
> > > * **Allocation roles:** candidate-user search works for users without runtime permissions on the asset.&#x20;
> > > * **Version switching:** the selected resource opens when changing app versions, and reusable-function code refreshes on version switch.&#x20;
> > > * **Process engine:** resolved an incident-save deadlock.&#x20;
> > > * **FlowX Database:** inserting a document with a reserved `_id` key is now rejected with a clear error instead of breaking later reads.&#x20;
>
> All Deployments

### **PostgreSQL data source**

> [card] Connect to PostgreSQL databases from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds **PostgreSQL** as a data source type, alongside Oracle. Connect a workflow directly to a PostgreSQL database and run SQL queries against it as a workflow node, without a custom REST wrapper. See the [PostgreSQL Database](/5.9/docs/platform-deep-dive/integrations/postgresql-database) documentation.
>
> > [tab] Key Features
> >
> > > [card] Direct connection
> > >
> > > Configure host, port, database, schema, and credentials, with an optional SSL connection and a **Test connection** check before saving.
> >
> > > [card] SQL query operations
> > >
> > > Define SQL query operations on the data source and call them from workflow nodes.
> >
> > > [card] Connection pool tuning
> > >
> > > Advanced settings cover pool size, connection and query timeouts, keep-alive, and a validation query.
> >
> > > [card] Familiar experience
> > >
> > > Shares the same configuration and operations experience as the existing Oracle data source.
>
> SaaS

### **SOAP integration**

> [card] Call SOAP web services from workflows
>
> > [tab] Overview
> >
> > Integration Designer adds a **SOAP System** data source. Import the service's **WSDL** — from a URL or an uploaded file — and FlowX discovers the operations with their input, output, and fault schemas, composes the SOAP envelope at runtime, and lets you call each operation from workflows through a **SOAP Operation** node. See the [SOAP System](/5.9/docs/platform-deep-dive/integrations/soap-system) documentation.
>
> > [tab] Key Features
> >
> > > [card] WSDL import
> > >
> > > Preview and select the operations to import; re-import refreshes schemas while preserving your edits
> >
> > > [card] Typed variables
> > >
> > > Envelope variables extracted from the input XSD, referenced as workflow parameters
> >
> > > [card] SOAP 1.1 and 1.2
> > >
> > > Version derived from the WSDL, with standard headers set automatically
> >
> > > [card] Testing built in
> > >
> > > Test operations with value overrides, a curl preview, and full request/response envelopes in run logs
>
> SaaS

### **Reusable UI templates**

> [card] Reusable UI template fixes
>
> Reusable UI templates get more reliable action mapping, undo/redo, and dependency-version handling.
>
> All Deployments

### **Chat file upload**

> [card] Attach multiple files in conversational apps
>
> End users can attach multiple files at once in chat-driven apps, and conversational workflows can receive those files as input. Uploaded files are extracted and indexed into a knowledge base scoped to the chat session, so AI nodes answer grounded in that content. Configurable in the Designer and themable, with runtime support on the web renderer.
>
> Session knowledge bases are isolated per conversation and per tenant, and are excluded from app export.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **File download component**

> [card] Download files from a rendered app
>
> A new File Download component lets end users download files directly from a rendered app. Configured in the Designer, with runtime support on web and Android.
>
> For more information, see the [File download](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download) documentation.
> SaaS

### **Conditional event-handler triggers**

> [card] Fire event handlers based on a condition
>
> Event handlers can now fire conditionally, configured in the Designer and honored by the web and Android renderers.
>
> For more information, see the [event handlers](/5.9/docs/building-blocks/ui-designer/event-handlers) documentation.
> SaaS

### **Image color property**

> [card] Color control on the IMAGE component
>
> The IMAGE component now honors a color property, configured in the Designer and rendered on web and Android.
>
> See the [Image component](/5.9/docs/building-blocks/ui-designer/ui-component-types/image) documentation.
> SaaS

### **Save local variable action**

> [card] Capture a collection row into local data
>
> Event handlers gain a **Save Local Variable** action type: on a component inside a collection, it saves the clicked row's item into local data under a configurable key, entirely client-side with no backend roundtrip — useful for capturing the selected row before a follow-up action fires. Not available inside Reusable UI Templates.
>
> See the [Save Local Variable](/5.9/docs/building-blocks/ui-designer/event-handlers#save-local-variable) documentation.
> SaaS

### **Global header and footer**

> [card] Consistent header and footer across a UI Flow
>
> UI Flows can now define a **global header and footer** that display consistently across every page of the flow. Each holds content components — containers, forms, buttons, links, custom components — with fixed or static positioning (header fixed by default), so you can build persistent navigation or action bars in one place instead of per page.
>
> See the [Global Header and Footer](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer) documentation.
> SaaS

### **Tabular data extraction node**

> [card] Extract spreadsheet and CSV data into workflows
>
> A new workflow node reads a spreadsheet or CSV file and returns its contents as structured JSON in the node's response key, so the data can drive conditions and data operations downstream. Each row is returned as an object keyed by the file's header row, and for Excel files you can select which sheet to read.
>
> For more information, see the [Tabular Data Extraction node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node) documentation.
> SaaS

### **Knowledge Base error handling and retry**

> [card] Recover from failed Knowledge Base ingestion
>
> When Knowledge Base ingestion fails, the Knowledge Base page now shows a clear failure status and reason, and a **Retry** button re-runs the last operation after cleaning up partial content so the store is not left inconsistent. The **Update Knowledge Base** workflow node gains a **FAIL** exit handle with per-operation rollback.
>
> Learn more about [Knowledge Bases](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview).
> SaaS

### **AI Developer: generate script-node code**

> [card] Generate script-node code with AI Developer
>
> In the workflow designer, a script node can call **AI Developer** to generate or refactor its code from a natural-language prompt. Output streams into the test area for a **Keep** or **Discard** review, with edits shown as a diff. Supports JavaScript and Python, and respects existing AI Developer permissions.
>
> Learn more about [AI Developer](/5.9/ai-platform/pre-built-agents/ai-developer).
> SaaS

### **FlowX Database aggregation**

> [card] Aggregation pipelines in FlowX Database
>
> The FlowX Database data source adds MongoDB **aggregation pipeline** support, so configurators can group, join, reshape, and compute across documents beyond what a single query allows.
>
> Learn more about the [FlowX Database](/5.9/docs/platform-deep-dive/integrations/flowx-database) data source.
> SaaS

### **AI evaluation experiments**

> [card] Richer AI evaluation experiments
>
> > [tab] Multiple datasets
> >
> > An evaluation experiment can run against **multiple datasets** at once (datasets sharing the same AI node), with overall metrics aggregated across them and a dataset column added to the report.
>
> > [tab] Improvement suggestions
> >
> > Experiment reports now show **AI-generated suggestions** for improving the node's prompt, grouped per LLM-as-judge evaluator, beneath the score cards.
>
> Learn more about [AI evaluations](/5.9/ai-platform/evaluations).
> SaaS

### **AI node output reliability**

> [card] Schema validation with auto-repair and clearer run errors
>
> > [tab] Validation and repair
> >
> > When an AI node has a **Response Schema**, the response is validated against it and automatically retried with a repair prompt on mismatch. Nodes that still fail return a **categorized error** instead of passing malformed output downstream, and the node's **Logs** show the failure reason, rejected output, the model's reasoning summary, and the retry count.
>
> > [tab] Schema placeholders
> >
> > Response schemas now support `${variable}` placeholders resolved at runtime against workflow data, with substituted values coerced to the schema-declared types — consistent with how other AI-node fields resolve placeholders.
>
> See [AI node types](/5.9/ai-platform/agent-builder/node-types#structured-output-validation-and-run-diagnostics) for details.
> SaaS

### **Template Filling node**

> [card] Generate documents from templates in workflows
>
> Integration workflows gain a **Template Filling** node, under **Tools** in the node palette, that generates a document from a document template populated with workflow data. Select a template and language, fill the template's variables from workflow data, and choose **PDF** or **DOCX** output. The generated file's ID and download path are returned on the node's response key.
>
> See the [Template Filling node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) documentation.
> SaaS

### **File manipulation nodes**

> [card] Combine and split files in workflows
>
> Integration workflows add two document nodes, under **Tools** in the node palette: **Combine Files** merges multiple PDFs into one in a given order, and **Split File** breaks a PDF into multiple files by page ranges or one file per page. Both bring document handling that was previously process-only into workflows.
>
> See the [Combine Files](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) documentation.
> SaaS

### **DOCX document generation**

> [card] Generate documents as DOCX
>
> Template-based document generation can now produce **DOCX** files in addition to PDF. Set `outputFormat` (`PDF` or `DOCX`; defaults to `PDF`) on the generation request, or pick the format from the new **Output format** dropdown when testing a template in the Designer. Generated DOCX files preserve the template's styles, data, and images. Barcodes apply to PDF output only.
>
> Learn more in the [Generating documents](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output) documentation.
> SaaS

### **Document Tag (renamed from Document Type)**

> [card] Document Type is now Document Tag
>
> The **Document Type** field is renamed **Document Tag** across the surfaces where a document is tagged for storage (Upload File action, Document-Plugin REST responses, AI Document Generation, and the Web Page Extractor). This is a label change; behavior is unchanged.
> SaaS

### **Documents tab in database testing**

> [card] Inspect data while testing database operations
>
> The Database Query testing modals gain a **Documents** tab, so you can inspect the database right after running an operation. Multi-record operations report an affected-record count.
> SaaS

### **Mistral model provider**

> [card] Bring your own Mistral API key
>
> **Mistral** joins the model provider catalog as a bring-your-own-key provider. Add it with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability: chat, image understanding, embeddings, and document OCR. The seeded catalog covers the Mistral Large, Medium, Small, Magistral, Codestral, Pixtral, OCR, and Embed model lines.
>
> Learn more about [AI providers](/5.9/ai-platform/ai-providers).
> SaaS

***

## Deployment guidelines

FlowX.AI 5.10 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.10 deployment guidelines](./deployment-guidelines-v5.10).&#x20;


# Deployment guidelines v5.11
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11

Component versions and deployment notes for FlowX.AI 5.11 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.11 is a **SaaS-managed release**. Deployment-level changes — infrastructure, Kafka topics, and service configuration — are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.11.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.11.0 |
| - | - |
| **admin** | 11.53.0 |
| **advancing-controller** | 11.31.0 |
| **application-manager** | 11.46.0 |
| **audit-core** | 11.30.0 |
| **authorization-system** | 11.38.0 |
| **cms-core** | 11.43.0 |
| **data-search** | 11.30.0 |
| **data-sync** | 11.27.0 |
| **designer** | 11.89.1 |
| **document-plugin** | 11.47.0 |
| **email-gateway** | 11.39.0 |
| **events-gateway** | 11.34.0 |
| **file-gateway** | 11.38.0 |
| **integration-designer** | 11.62.1 |
| **license** | 11.34.0 |
| **nosql-db-runner** | 11.35.0 |
| **notification-plugin** | 11.41.0 |
| **organization-manager** | 11.38.0 |
| **process-engine** | 11.53.1 |
| **runtime-manager** | 11.46.0 |
| **scheduler-core** | 11.30.0 |
| **task-management-plugin** | 11.42.0 |
| **webhook-gateway** | 11.37.0 |

### AI base components

| Component | 5.11.0 |
| - | - |
| **embedder** | 11.3.1 |
| **knowledgebase-indexer-v2** | 11.3.1 |
| **knowledgebase-rag** | 11.3.1 |
| **doc-parser** | 11.3.1 |

### AI dev-time components

| Component | 5.11.0 |
| - | - |
| **ai-gateway** | 11.39.0 |
| **ai-analyst** | 11.3.1 |
| **ai-assistant** | 11.3.1 |
| **ai-designer** | 11.3.1 |
| **ai-developer** | 11.3.1 |
| **kb-enrichment** | 11.3.1 |
| **planner** | 11.3.1 |

### AI runtime components

| Component | 5.11.0 |
| - | - |
| **agent-builder** | 11.3.1 |
| **ai-architect** | 11.3.1 |
| **data-privacy** | 11.3.1 |
| **doc-converter** | 11.3.1 |
| **dynamic-classifier** | 11.3.1 |
| **evals-judge** | 11.3.1 |
| **speech-to-text** | 11.3.1 |
| **web-crawler** | 11.3.1 |

### AI extensions

| Component | 5.11.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.89.1` for FlowX.AI 5.11.0). The native iOS and Android renderers version independently.

| Component | 5.11.0 |
| - | - |
| **@flowx/angular-sdk** | 11.89.1 |
| **@flowx/angular-theme** | 11.89.1 |
| **@flowx/angular-ui-toolkit** | 11.89.1 |
| **@flowx/react-sdk** | 11.89.1 |
| **@flowx/react-theme** | 11.89.1 |
| **@flowx/react-ui-toolkit** | 11.89.1 |
| **@flowx/react-native-sdk** | 11.89.1 |
| **@flowx/react-native-theme** | 11.89.1 |
| **@flowx/react-native-ui-toolkit** | 11.89.1 |
| **@flowx/core-sdk** | 11.89.1 |
| **@flowx/core-theme** | 11.89.1 |
| **react-saas** | 11.89.1 |
| **iOS renderer** | 11.1.0 |
| **Android renderer** | 11.7.1 |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.11 capabilities. On SaaS they are created and managed automatically.

**Structured template data model** (document and notification templates move to the structured data model):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.sync.out.v1` | document-plugin, notification-plugin → application-manager |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | document-plugin, notification-plugin → application-manager |

**Runtime content import/export** (Knowledge Base and database content):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → ai-platform |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | ai-platform → integration-designer |

**Document classification and ML extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | ai-platform → integration-designer |

### AI Platform packaging

FlowX.AI 5.11 consolidates the AI Platform services into a single **`ai-platform` umbrella chart** (version `11.3.1`). Services that were previously deployed as standalone releases, including `doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, and `evals-judge`, now ship as subcharts of that chart and continue to run under their plain service names. On SaaS this change is applied automatically. The [component versions](#component-versions) section lists each service at its effective `11.3.1` version.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.11.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026

What's new in FlowX.AI 5.11: workflow tools and agentic RAG on Custom Agents, per-Knowledge-Base embedding models, document classification, extended response caching, subworkflow data mapping, structured template data models, and chat and UI Flow renderer improvements.

[FlowX.AI 5.11 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.11.0.html)

> [!NOTE]
>
> **FlowX.AI 5.11 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.11** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release turns Custom Agents into orchestrators that call FlowX workflows as tools and search knowledge bases agentically, adds per-Knowledge-Base embedding models with local embedders for personal-information content, and introduces document classification. It also extends response caching and subworkflow data mapping in the Integration Designer, moves document and notification templates onto the structured data model, and adds chat notifications, session ownership, and richer runtime audit to the renderers.

### What changed since 5.10.0

| 5.10.0 | 5.11.0 |
| - | - |
| Custom Agents call MCP servers, built-in tools, web search, and Knowledge Bases | + **FlowX workflows as callable tools** on a Custom Agent, with per-tool usage hints and tool-calling caps |
| Knowledge Base retrieval is a plain vector search on the org default embedding model | + **Agentic knowledge base search** and **per-KB embedding models**, including keyless local embedders for personal-information content |
| REST caching covers GET; SQL operations are cacheable | + **POST** REST responses, **file-storage** reads, and **Mongo** reads are cacheable too |
| Subworkflow input/output is raw JSON | + **Input and output mappers** on the Subworkflow node, with per-mapping test and import/export |
| Document and notification templates use a free-form key/value Data model tab | + Templates use the **structured data model** with typed attributes, validators, and Input Parameters |

***

**What's new?**

> [tab] AI & Agents
>
> 🧰 [**Workflow tools on Custom Agents**](#workflow-tools-on-custom-agents) - Attach FlowX workflows as callable agent tools, with usage hints and tool-calling caps\
> 🔎 [**Agentic knowledge base search and Show Reasoning**](#agentic-knowledge-base-search-and-show-reasoning) - Query decomposition, relevance grading, and a reasoning summary in the run log\
> 🧠 [**Per-knowledge-base embedding models**](#per-knowledge-base-embedding-models) - Pick an embedding model per KB and keep personal-information content on a local embedder\
> 🗂️ [**Knowledge Base content lifecycle**](#knowledge-base-content-lifecycle) - Delete entries by metadata filter, structured failure handling, per-chunk timestamps\
> 🏷️ [**Document classification**](#document-classification) - Train or import a classifier and route document pages in a workflow\
> 💬 [**Conversational chat reply requirement**](#conversational-chat-reply-requirement) - A conversational run that never replies to chat now fails with a clear error\
> ✍️ [**Custom Agent instruction limit**](#custom-agent-instruction-limit) - The Instructions field is capped at 10,000 characters

> [tab] Integrations & Data
>
> 🔁 [**Reusable functions in Integration Designer**](#reusable-functions-in-integration-designer) - Call reusable functions from Script and Condition (Fork) nodes\
> ⚡ [**Extended response caching**](#extended-response-caching) - Cache POST REST, file-storage reads, and Mongo reads alongside GET and SQL\
> 🔗 [**Subworkflow data mapping**](#subworkflow-data-mapping) - Map data in and out of a subworkflow with input and output mappers\
> 📎 [**Email attachment filtering by extension**](#email-attachment-filtering-by-extension) - Filter attachments by individual file extension instead of broad categories

> [tab] Platform
>
> 🧱 [**Structured data model for templates**](#structured-data-model-for-templates) - Document and notification templates use typed attributes and Input Parameters\
> ✅ [**Data model attribute validators**](#data-model-attribute-validators) - Required, min/max, length, pattern, email, items, and currency rules on attributes\
> 🧾 [**UI Flow runtime audit**](#ui-flow-runtime-audit) - Audit workflow-instance runs, chat messages, conversation reads, and process renders\
> 📤 [**Cross-version export adaptation**](#cross-version-export-adaptation) - Exports adapt UI templates for older LTS targets by removing unsupported handlers\
> 🔐 [**Platform and runtime improvements**](#platform-and-runtime-improvements) - Runtime access-control hardening

> [tab] Renderers & UI Flows
>
> 🔔 [**Chat notifications and conversation search**](#chat-notifications-and-conversation-search) - Unread-message badge on the chat button and search across conversation history\
> 🚫 [**Disable chat input on a condition**](#disable-chat-input-on-a-condition) - A business condition can make the chat input read-only\
> 🧭 [**Navigate To form validation**](#navigate-to-form-validation) - Require form validation before a Navigate To action, on web, iOS, and Android\
> ⌛ [**Expired UI Flow sessions**](#expired-ui-flow-sessions) - Expired sessions show a session-expired screen with a start-fresh option\
> 👤 [**UI Flow session owner**](#ui-flow-session-owner) - Restrict a running session to a single user\
> 🏁 [**Process Renderer process-end handling**](#process-renderer-process-end-handling) - Run a configurable action when an embedded process ends\
> 🎛️ [**Renderer improvements**](#renderer-improvements) - Batched enumeration fetch and process-start loader alignment

### **Workflow tools on Custom Agents**

> [card] Attach FlowX workflows as callable tools on a Custom Agent
>
> > [tab] Overview
> >
> > **Before 5.11:** a Custom Agent's tools were MCP servers, built-in tools, web search, and Knowledge Base retrieval. **Now:** you can also attach FlowX workflows as callable tools.
> >
> > In the Custom Agent node's **Tools** section, add a workflow as a tool and fill the per-tool **When should the agent use this workflow?** hint that tells the agent when to call it. The agent calls the workflow like any other tool, passing arguments that match the workflow's Start-node input parameters. A workflow with no input parameters cannot be attached. Each tool call starts a fresh workflow run whose output returns to the agent, and the child run is linked in the console log.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Workflows as tools
> > >
> > > Attach up to ten workflows as tools on one Custom Agent, each with a usage hint the agent reads when deciding to call it.
> >
> > > [card] Typed arguments
> > >
> > > The agent passes arguments that match the workflow's Start-node input parameters; workflows without input parameters are not eligible.
> >
> > > [card] Tool-calling limits
> > >
> > > An agent is limited in how many tool calls it can make per run, and workflow-tool call chains are depth-limited so recursion cannot run away.
> >
> > > [card] Linked runs
> > >
> > > Each workflow tool call is a fresh run whose output returns to the agent and is linked in the console log.
>
> SaaS

### **Agentic knowledge base search and Show Reasoning**

> [card] Agentic knowledge base search and reasoning summaries
>
> > [tab] Overview
> >
> > The Custom Agent node gains **agentic knowledge base search** and a **Show Reasoning** toggle.
> >
> > With agentic search on, the agent breaks a question into sub-queries, retrieves and grades results for relevance, and retries with reworded queries if the first pass finds nothing. It is better on complex questions and uses more model calls; a single pass with three sub-queries is the default. Agentic search never returns worse results than plain retrieval. **Show Reasoning** captures the model's reasoning summary in the run and console log; the structured response and the chat reply shown to the user are unchanged.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > See the Custom Agent node documentation.
>
> > [tab] Key Features
> >
> > > [card] Agentic search
> > >
> > > Turn on **Enable agentic knowledge base search**, then set **Max attempts** and **Subqueries per attempt** under Settings.
> >
> > > [card] Relevance grading
> > >
> > > Retrieved candidates are graded against the original question, with corrective retries until a relevant result is found or the attempt budget is spent.
> >
> > > [card] Show Reasoning
> > >
> > > Surface the model's reasoning in the run log without changing the answer returned to the user.
> >
> > > [card] Fail-open
> > >
> > > Agentic mode returns the same chunk metadata as plain retrieval, so citations and telemetry are unchanged.
>
> SaaS

### **Per-knowledge-base embedding models**

> [card] Per-KB embedding models and local embedders for personal information
>
> > [tab] Overview
> >
> > Knowledge Bases can now use a **per-KB embedding model**, and a KB that holds personal information can keep its content on a local embedder.
> >
> > Turn on **Containing Personal Information** on a Knowledge Base to enable a local embedding model, then pick one from the **Embedding model** list. Local embedders (for example a text-embedding-inference or Ollama endpoint, or any OpenAI-compatible endpoint) are configured as a single **CUSTOM** provider in the organization AI settings, with a free-form base URL and no API key. The embedding model is set before the first store and cannot be changed afterward. Non-personal-information Knowledge Bases use the organization's default embedding model.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See the Knowledge Base documentation.
>
> > [tab] Key Features
> >
> > > [card] Per-KB model
> > >
> > > Each Knowledge Base carries its own embedding-model reference; a new Settings tab shows the current model.
> >
> > > [card] Local embedders
> > >
> > > Keep personal-information content on-box using a keyless local embedder fronted by a CUSTOM AI provider.
> >
> > > [card] Model travels with export
> > >
> > > Project version export preserves the KB's embedding-model reference, so a re-import keeps the same model.
> >
> > > [card] Set once per KB
> > >
> > > A Knowledge Base's embedding model is chosen before its first store and cannot be changed afterward.
>
> SaaS

### **Knowledge Base content lifecycle**

> [card] Delete entries by filter, structured failure handling, and per-chunk timestamps
>
> > [tab] Overview
> >
> > The **Update Knowledge Base** node gains a **Delete entries** operation and structured failure handling, and retrieval results now carry per-chunk metadata.
> >
> > **Delete entries** soft-deletes chunks whose entry-level metadata matches a filter, in one store or across the Knowledge Base; an empty or match-all filter is rejected so a misconfigured node cannot wipe a store. When an update operation fails, the node's **FAIL** branch returns a structured output with the operation, store, failure reason, and how many chunks were rolled back, and any partial changes are reversed. Retrieval results now include a per-chunk identifier and an ingestion timestamp.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > >
> > > See the Managing Knowledge Base content documentation.
>
> > [tab] Key Features
> >
> > > [card] Filtered deletion
> > >
> > > Delete entries by metadata filter from a workflow, with an empty or match-all filter rejected as a safety guard.
> >
> > > [card] Failure output with rollback
> > >
> > > The FAIL branch reports the operation, store, reason, and rolled-back chunk count; partial changes are reversed.
> >
> > > [card] Per-chunk timestamps
> > >
> > > RAG results carry a chunk identifier and an ingestion timestamp (empty for chunks indexed before this shipped).
> >
> > > [card] Clear retry signal
> > >
> > > Retryable failures such as extraction or chunking errors are distinguished from non-retryable ones such as size or timeout.
>
> SaaS

### **Document classification**

> [card] Classify document pages with a trainable ML model
>
> > [tab] Overview
> >
> > FlowX.AI adds **Document Classifiers**: deterministic ML models that sort document pages into categories. Define classes, upload training data, and train or import a model, then route each page in a workflow with the new **Document Classification** node.
> >
> > The node runs the active model over a document, returns a predicted label and probability per page with a configurable confidence threshold, and flags low-confidence pages. A page-level failure does not fail the node.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer documentation.
>
> > [tab] Key Features
> >
> > > [card] Train or import
> > >
> > > Build classes and training data in the Designer, then train a model or import a pre-trained one.
> >
> > > [card] Per-page classification
> > >
> > > The Document Classification node returns a label and probability for each page, with a confidence threshold and low-confidence flags.
> >
> > > [card] Deterministic routing
> > >
> > > Combine the node with a condition to route pages by their predicted category.
> >
> > > [card] Resilient runs
> > >
> > > A page that cannot be classified is reported per page without failing the whole node.
>
> SaaS

### **Conversational chat reply requirement**

> [card] Conversational runs must reply to chat
>
> A conversational (chat-driven) workflow must send at least one chat reply, either from a Custom Agent node with **Send as Chat Reply** on or from a Navigate in UI Flow node that completes the turn. A run that reaches the end without replying now fails with a clear error instead of ending silently.
>
> Learn more about [chat-driven workflows](/5.9/ai-platform/chat-driven-workflows).
> SaaS

### **Custom Agent instruction limit**

> [card] Instructions field capped at 10,000 characters
>
> The Custom Agent **Instructions** field is now limited to 10,000 characters.
> SaaS

### **Reusable functions in Integration Designer**

> [card] Call reusable functions from Script and Condition (Fork) nodes
>
> Reusable functions can now be called from **Script** nodes and **Condition (Fork)** nodes in the Integration Designer, not just from Business Rule actions in processes. Functions are referenced in the node's JavaScript or Python and resolved at runtime from the app version's function copies, including functions that call other functions and cross-app references. A Fork node resolves the references used across all of its branch conditions.
>
> For more information, see the [reusable functions](/5.9/docs/building-blocks/reusable-resources/reusable-functions) documentation.
> SaaS

### **Extended response caching**

> [card] Cache POST REST, file-storage reads, and Mongo reads
>
> > [tab] Overview
> >
> > Response caching in the Integration Designer now covers more operation types. **POST** REST endpoints are cacheable alongside GET, with the request body forming part of the cache key so different bodies cache separately. Read **file-storage** operations (LIST and DOWNLOAD) and read **Mongo** operations (FIND, FIND\_ONE, AGGREGATE) are cacheable alongside SQL. Mutating operations are never cached.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] POST caching
> > >
> > > Cache POST responses, keyed on the request body so distinct requests stay separate.
> >
> > > [card] File-storage reads
> > >
> > > LIST and DOWNLOAD operations are cacheable; UPLOAD, DELETE, and MOVE are not.
> >
> > > [card] Mongo reads
> > >
> > > FIND, FIND\_ONE, and AGGREGATE are cacheable alongside SQL; mutating Mongo operations are not.
> >
> > > [card] Shared policy
> > >
> > > All cacheable surfaces reuse the same time-based expiry and per-operation clear-cache action.
>
> SaaS

### **Subworkflow data mapping**

> [card] Map data in and out of a subworkflow with input and output mappers
>
> > [tab] Overview
> >
> > The **Subworkflow** node adds data mapping as an alternative to raw JSON. Turn on **Enable data mapping** to define an **Input mapping** per subworkflow start node and an **Output mapping** per end node, mapping individual data slices instead of hand-editing JSON. Output mapping does not apply to asynchronous subworkflows. Each mapping opens a mapper with a test action, and mappings travel with import, export, and clone.
> >
> > For more information, see the [Integration Designer](/5.9/docs/platform-deep-dive/integrations/integration-designer) documentation.
>
> > [tab] Key Features
> >
> > > [card] Input and output mappers
> > >
> > > Map data into the subworkflow per start node and out of it per end node, without editing raw JSON.
> >
> > > [card] Per-mapping test
> > >
> > > Test a mapping with source and target slices and apply values from a past instance.
> >
> > > [card] Travels with the project
> > >
> > > Mappings are preserved on import, export, and clone.
> >
> > > [card] Async-aware
> > >
> > > Output mapping is hidden for asynchronous subworkflows, which do not return data to the caller.
>
> SaaS

### **Email attachment filtering by extension**

> [card] Filter email attachments by individual file extension
>
> Email Trigger and Microsoft Outlook data sources now filter attachments by **individual file extension** instead of the five broad file-type categories. Choose the exact extensions to accept and to forward into a process. Existing category selections are migrated to their individual extensions automatically on upgrade, so current triggers keep working.
>
> For more information, see the [Email Trigger](/5.9/docs/platform-deep-dive/integrations/email-trigger) documentation.
> SaaS

### **Structured data model for templates**

> [card] Document and notification templates use the structured data model
>
> > [tab] Overview
> >
> > **Before 5.11:** document and notification templates declared parameters in a free-form key/value Data model tab. **Now:** templates use the same structured data model as the rest of the platform.
> >
> > On the **Data Model** tab you define typed attributes with validations, sensitive-data and reporting flags, and references to project or library data types. On the **Input Parameters** tab you select which attributes the template expects. Values sent in the request are substituted for those attributes at generation time.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > >
> > > See the notification templates documentation.
>
> > [tab] Key Features
> >
> > > [card] Typed attributes
> > >
> > > Define string, number, boolean, enum, date, currency, object, and array attributes with validations.
> >
> > > [card] Input Parameters
> > >
> > > Pick the attributes the template expects on a dedicated Input Parameters tab.
> >
> > > [card] Reference shared types
> > >
> > > Reference project and library data types like other resources.
> >
> > > [card] OTP unchanged
> > >
> > > The OTP flow contract is unchanged; the reserved `otpValue` and request `data` object work as before.
>
> SaaS

### **Data model attribute validators**

> [card] Validators on data model attributes
>
> Data model attributes now support validators. Available rules depend on the attribute type and include **Required**, **Min/Max Value**, **Min/Max Length**, **Pattern**, **Email Format**, and **Min/Max Items**, plus currency-specific amount and code rules. Validators are stored on the attribute and apply wherever that data model is used, including project, process, template, and reusable UI template data models.
>
> For more information, see the [project data model](/5.9/docs/building-blocks/project-data-model) documentation.
> SaaS

### **UI Flow runtime audit**

> [card] Audit UI Flow runtime activity
>
> UI Flow runtime sessions are now audited in more detail. The audit log records **workflow-instance** runs, chat **message sends**, conversation **list** and **history** reads, and whether the Process Renderer performed a **render** or a start. Entries name the app and the workflow instance.
>
> For more information, see the [audit](/5.9/docs/platform-deep-dive/core-extensions/audit) documentation.
> SaaS

### **Cross-version export adaptation**

> [card] Exports adapt UI templates for older LTS targets
>
> When you export a project to an older platform version, UI-template features the target version cannot understand are removed during down-adaptation, so the export imports cleanly. This currently covers Process Renderer process-end event handlers and the Navigate To **forms to validate** setting.
>
> For more information, see [Cross-version export and import](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
> All Deployments

### **Platform and runtime improvements**

> [card] Runtime access-control hardening
>
> Runtime API requests are now authorized against the roles defined in the running build across start-process, start-workflow, task views, conversation history, and the public runtime API. Requests without a matching build role are denied, and enforcement is on by default.
> All Deployments

> [card] Theme import no longer duplicates system icons
>
> Exporting a theme no longer includes duplicate copies of built-in system icons, and importing a theme no longer creates new ones. Duplicate icon copies that accumulated in earlier versions are cleaned up automatically on upgrade — no action is required.
> All Deployments

### **Chat notifications and conversation search**

> [card] Unread-message badge and conversation search in chat
>
> > [tab] Overview
> >
> > The chat floating action button gains an **unread-message notification badge**, with a themeable **Notification Dot** you can position in the chat style panel. The chat panel also adds **search across conversation history**, which filters conversations by a text query, highlights matches, and shows an empty state when nothing matches.
> >
> > For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
>
> > [tab] Key Features
> >
> > > [card] Unread badge
> > >
> > > The chat button shows a badge with the unread agent-message count; it is hidden while the chat is open in full screen.
> >
> > > [card] Notification Dot
> > >
> > > Position and size the notification dot from the chat style panel, with theme support.
> >
> > > [card] Conversation search
> > >
> > > Search conversation history from the chat panel, with highlighted matches and an empty state.
>
> SaaS

### **Disable chat input on a condition**

> [card] Make the chat input read-only with a business condition
>
> The chat **Input** component can be disabled by a business-condition expression. When the condition evaluates true, the input becomes read-only with an explanatory tooltip, and any pending attachments and voice input are cleared.
>
> For more information, see the [Chat component](/5.9/docs/building-blocks/ui-designer/ui-component-types/chat) documentation.
> SaaS

### **Navigate To form validation**

> [card] Require form validation before a Navigate To action
>
> A **Navigate To** action can now require selected forms to pass validation before navigating, matching how Start Process and Start Workflow actions gate on validation. This is available on web, iOS, and Android.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Expired UI Flow sessions**

> [card] A session-expired screen with a start-fresh option
>
> Expired UI Flow sessions now show a **session-expired** screen with a start-fresh option instead of leaving the previous data visible in read-only form. Expired and unauthorized access is written to the audit log.
> SaaS

### **UI Flow session owner**

> [card] Restrict a running session to a single user
>
> A UI Flow can restrict a running session to a single owner. When **Allow multiple editors** is off, other users who try to open the session are shown an access-denied screen, and unauthorized access is audited. Newly created flows default to single-owner; imported and existing flows keep the previous shared behavior. A session-owner value type is available for permission-based hide and disable rules.
>
> For more information, see the [UI Flows](/5.9/docs/building-blocks/ui-flows) documentation.
> SaaS

### **Process Renderer process-end handling**

> [card] Run a configurable action when an embedded process ends
>
> The Process Renderer can now run a configurable action when its embedded process ends, using a new process-end trigger on event handlers. Configure what happens at that point instead of leaving the renderer idle when the process completes.
>
> For more information, see [Process end handling](/5.9/docs/building-blocks/ui-flows#process-end-handling).
> SaaS

### **Renderer improvements**

> [card] Renderer performance and behavior
>
> * **Batched enumeration fetch:** renderers batch enumeration lookups into a single bulk request, cutting the number of calls when rendering enum-backed fields. Applies to web and mobile renderers.
> * **Process-start loader alignment:** the web renderer keeps the process-start loader visible until the first user task, matching the mobile SDKs.
>   SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

FlowX.AI 5.11 is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. For component versions and infrastructure notes, see the [5.11 deployment guidelines](./deployment-guidelines-v5.11).


# Deployment guidelines v5.12
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12

Component versions and deployment notes for FlowX.AI 5.12 (SaaS release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.12 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.12.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.12.0 |
| - | - |
| **admin** | 11.69.2 |
| **advancing-controller** | 11.46.0 |
| **application-manager** | 11.68.3 |
| **audit-core** | 11.44.1 |
| **authorization-system** | 11.53.2 |
| **cms-core** | 11.61.1 |
| **data-search** | 11.44.1 |
| **data-sync** | 11.43.1 |
| **designer** | 11.126.1 |
| **document-plugin** | 11.68.1 |
| **email-gateway** | 11.58.1 |
| **events-gateway** | 11.49.2 |
| **file-gateway** | 11.55.1 |
| **integration-designer** | 11.90.2 |
| **license** | 11.48.1 |
| **nosql-db-runner** | 11.49.1 |
| **notification-plugin** | 11.61.2 |
| **organization-manager** | 11.53.1 |
| **process-engine** | 11.76.1 |
| **runtime-manager** | 11.68.3 |
| **scheduler-core** | 11.45.1 |
| **task-management-plugin** | 11.59.2 |
| **webhook-gateway** | 11.54.1 |

### AI base components

| Component | 5.12.0 |
| - | - |
| **embedder** | 11.5.0 |
| **knowledgebase-indexer-v2** | 11.5.0 |
| **knowledgebase-rag** | 11.5.0 |
| **doc-parser** | 11.5.0 |

### AI dev-time components

| Component | 5.12.0 |
| - | - |
| **ai-gateway** | 11.53.1 |
| **ai-analyst** | 11.5.0 |
| **ai-assistant** | 11.5.0 |
| **ai-designer** | 11.5.0 |
| **ai-developer** | 11.5.0 |
| **kb-enrichment** | 11.5.0 |
| **planner** | 11.5.0 |

### AI runtime components

| Component | 5.12.0 |
| - | - |
| **agent-builder** | 11.5.0 |
| **ai-architect** | 11.5.0 |
| **data-privacy** | 11.5.0 |
| **doc-converter** | 11.5.0 |
| **dynamic-classifier** | 11.5.0 |
| **evals-judge** | 11.5.0 |
| **speech-to-text** | 11.5.0 |
| **web-crawler** | 11.5.0 |

### AI extensions

| Component | 5.12.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.3.0 |
| **observatory-platform** | 11.3.0 |
| **observatory-web** | 11.3.0 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.126.1` for FlowX.AI 5.12.0). The native iOS and Android renderers version independently.

| Component | 5.12.0 |
| - | - |
| **@flowx/angular-sdk** | 11.126.1 |
| **@flowx/angular-theme** | 11.126.1 |
| **@flowx/angular-ui-toolkit** | 11.126.1 |
| **@flowx/react-sdk** | 11.126.1 |
| **@flowx/react-theme** | 11.126.1 |
| **@flowx/react-ui-toolkit** | 11.126.1 |
| **@flowx/react-native-sdk** | 11.126.1 |
| **@flowx/react-native-theme** | 11.126.1 |
| **@flowx/react-native-ui-toolkit** | 11.126.1 |
| **@flowx/core-sdk** | 11.126.1 |
| **@flowx/core-theme** | 11.126.1 |
| **react-saas** | 11.126.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.12 capabilities. On SaaS they are created and managed automatically.

**Event-triggered workflows** (email and webhook triggers can start an integration workflow):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Deep Research node** (the node hands research jobs to the AI Platform over Kafka):

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | dead-letter queue for failed research jobs |

**Bulk process-instance migration:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |

**Notifications:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.eventsgateway.user.notifications.v1` | application-manager, process-engine → events-gateway |

**Document classification:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → dead-letter sink (not consumed) |

### New service dependency: webhook-gateway and MongoDB

The webhook gateway now reads the runtime registry that backs event-triggered workflows, so it depends on the runtime MongoDB database in addition to its existing relational database. On SaaS this connection is provisioned and managed by FlowX.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map. | none (required) | integration-designer |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today. | `k1` | integration-designer |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index. | `PT24H` | integration-designer |

### Native PostgreSQL partitioning for the engine

On PostgreSQL, the engine converts its runtime tables to native `RANGE(partition_id)` partitioning the first time it starts on the new version, and archiving then detaches a partition instead of copying rows out of it. Deployments that never enabled partitioning are skipped entirely, and Oracle deployments are unaffected.

Unlike most 5.12 changes, this one also reaches self-hosted 5.9.x in the 5.9.5 patch rather than waiting for the next LTS release family.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Whether archiving detaches partitions with `DETACH CONCURRENTLY` on natively partitioned tables. Setting it to `false` returns archiving to the previous batched insert-and-delete, but does not undo the conversion: the tables stay natively partitioned. | `true` | process-engine |

For the conversion cost, table locking and the one-way caveat, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning).

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.12.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026

What's new in FlowX.AI 5.12: parallel multi-instance subworkflow fan-out, event-triggered integration workflows, bulk process-instance migration, personal-data mask and restore nodes, and a Db2 data source.

[FlowX.AI 5.12 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.12.0.html)

> [!NOTE]
>
> **FlowX.AI 5.12 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.12** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. This release lets an integration workflow fan out over a collection without a subprocess, starts workflows directly from email and webhook events, and migrates process instances to a new build in bulk. It also adds personal-data mask and restore nodes to the Integration Designer and a Db2 relational data source.

### What changed since 5.11.0

| 5.11.0 | 5.12.0 |
| - | - |
| A workflow ran once per call; fanning out over a collection needed a BPMN Call Activity and a subprocess | + **Multi-instance subworkflow node** fans a workflow over a collection directly in the Integration Designer |
| An email or webhook trigger could start a process | + **Event-triggered workflows** start an integration workflow from the same triggers |
| Process instances migrated to a new build one at a time | + **Bulk migration** moves a filtered set of instances in one operation |
| Personal-data handling was configured on the agent | + **Mask and restore nodes** place it as explicit workflow steps, with details in the run log |

***

**What's new?**

> [tab] Integrations & Data
>
> 🔀 [**Multi-instance subworkflow node**](#multi-instance-subworkflow-node) - Fan a workflow out over a collection\
> ⚡ [**Event-triggered workflows**](#event-triggered-workflows) - Start a workflow from an email or webhook\
> 🗄️ [**Db2 relational data source**](#db2-relational-data-source) - Connect to Db2 for i or Db2 LUW\
> 🔻 [**Subworkflow failure exit**](#subworkflow-failure-exit) - Send a failed mapping down its own branch\
> 🔓 [**Skip TLS verification on a REST data source**](#skip-tls-verification-on-a-rest-data-source) - Reach a trusted internal host with an untrusted certificate\
> 🔔 [**Send Notification node**](#send-notification-node) - Send a templated notification straight from a workflow

> [tab] AI Platform
>
> 🛡️ [**Personal-data mask and restore nodes**](#personal-data-mask-and-restore-nodes) - Explicit workflow steps with run-log detail\
> 🧩 [**Reusable functions as agent tools**](#reusable-functions-as-agent-tools) - Give an agent a deterministic function to call\
> 👍 [**Chat response feedback**](#chat-response-feedback) - Let users rate an agent's answer, and theme how it looks\
> 📏 [**Custom evaluators**](#custom-evaluators) - Score an agent against a rubric you write yourself\
> 🔍 [**Deep Research node**](#deep-research-node) - Research a question across the open web and file a cited report\
> 🛠️ [**Built-in agent tools by category**](#built-in-agent-tools-by-category) - Twenty ready-made tools an agent can use, picked by category\
> 🪄 [**AI Designer builds UI Flows**](#ai-designer-builds-ui-flows) - Generate and edit multi-page UI Flows from a description

> [tab] Platform
>
> 📦 [**Bulk process-instance migration**](#bulk-process-instance-migration) - Move a filtered set of instances to a new build\
> 🔎 [**Runtime list filters and a Workflow Instances page**](#runtime-list-filters-and-a-workflow-instances-page) - Find the failed run without scanning the list\
> 🎨 [**Process canvas editing**](#process-canvas-editing) - Connect, reshape and resize more directly on the BPMN canvas\
> ⚠️ [**Check a version for issues**](#check-a-version-for-issues) - Validate every workflow in the version from one panel\
> 🧱 [**Reusable UI Templates in UI Flows**](#reusable-ui-templates-in-ui-flows) - Reuse a template on UI Flow pages, not just User Tasks\
> 🌿 [**Branch management**](#branch-management) - Merge to any branch, archive or delete the ones you are done with

### **Multi-instance subworkflow node**

> [card] Multi-instance subworkflow node
>
> > [tab] Overview
> >
> > **Before 5.12.0:** running an integration workflow once per item in a collection meant leaving the Integration Designer, wrapping the workflow in a BPMN process and fanning out with a multi-instance Call Activity. **Now:** the Subworkflow node fans out over an array on its own, in parallel.
> >
> > Turn on **Parallel Multi-Instance** under **Execution** on a Subworkflow node, pick the **Input Array** to iterate, and pick the **Output Array** that collects each run's result. The node starts one subworkflow instance per element of the input array and gathers the results into the output array on the parent workflow.
>
> > [tab] Key Features
> >
> > > [card] Input Array
> > >
> > > The array of objects to iterate. One subworkflow instance starts per element. Required.
> >
> > > [card] Output Array
> > >
> > > The array each instance result is collected into. Required.
> >
> > > [card] Correlation attribute
> > >
> > > Optional. Decides which output array element each result updates. Results matching no element, or all results when no attribute is set, are appended.
> >
> > > [card] Runs in parallel
> > >
> > > Instances run in parallel, and fan-out stays inside the Integration Designer instead of requiring a BPMN Call Activity.
>
> For the full configuration reference, see [Parallel multi-instance](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) on the Subworkflow node.
> SaaS

### **Event-triggered workflows**

> [card] Event-triggered workflows
>
> > [tab] Overview
> >
> > **Before 5.12.0:** an incoming email or webhook could start a process. **Now:** the same triggers can start an integration workflow directly.
> >
> > A workflow declares the trigger it listens for, and the platform keeps a subscription registry so a change to that trigger takes effect without rebuilding the whole app. Incoming email and webhook events are routed to the workflow that subscribes to them.
>
> > [tab] Key Features
> >
> > > [card] Email and webhook triggers
> > >
> > > Both trigger types can start a workflow, not only a process.
> >
> > > [card] Subscription registry
> > >
> > > Trigger changes update the affected data source without a full build recompute.
>
> > [tab] Architecture
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Trigger subscription changes | admin, integration-designer, application-manager | Design-time changes update the runtime subscription registry |
> > | Event delivery | email-gateway, webhook-gateway, integration-designer | Events are routed to the subscribing workflow |
> > | Webhook state | webhook-gateway | The webhook gateway now also reads the runtime registry, adding a MongoDB dependency it did not previously have |
> >
> > On SaaS these changes are applied automatically. See [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12) for the topic and dependency detail.
>
> For the full configuration reference, see [External triggers](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers) on the Start node.
> SaaS

### **Bulk process-instance migration**

> [card] Bulk process-instance migration
>
> > [tab] Overview
> >
> > **Before 5.12.0:** moving running process instances onto a new build was a one-at-a-time operation. **Now:** a filtered set of instances migrates in a single run.
> >
> > Select the target build, filter the instances to move, check the migration for problems before committing to it, and then run it. Progress and per-instance outcomes are available while it runs, and terminated instances are handled explicitly rather than failing the batch.
> >
> > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > See migrating process instances.
>
> > [tab] Key Features
> >
> > > [card] Filter then migrate
> > >
> > > Move specific instance UUIDs, the instances matching a process, node and status filter, or every eligible instance.
> >
> > > [card] Pre-flight check
> > >
> > > Validate a migration before running it.
> >
> > > [card] Per-instance outcomes
> > >
> > > Inspect details and results for the instances in a batch.
> >
> > > [card] Audit trail
> > >
> > > Migrations are recorded against the instances they touch.
>
> For the full configuration reference, see the [Migrate process instances](/5.9/docs/projects/runtime/active-process/migrate-process-instances) documentation.
> SaaS

### **Runtime list filters and a Workflow Instances page**

> [card] Runtime list filters and a Workflow Instances page
>
> Finding a failed run no longer means scanning an unfiltered list. The **Process Instances** and **UI Flow Sessions** lists gain a multi-select **Status** filter and a start-date filter on their columns, so "every failed instance since last night" is two clicks.
>
> Workflow runs get more: a new **Workflow Instances** page under **Runtime** lists every run in the project, filterable by **Status**, by date, and by **Origin**: whether a run was started by a process, a UI Flow, a webhook, or an email trigger. Until now, a workflow's runs were only visible from inside that workflow in the Integration Designer.
>
> For details, see the [Workflow Instances](/5.9/docs/projects/runtime/workflow-instances) documentation.
> SaaS

***

### **Personal-data mask and restore nodes**

> [card] Personal-data mask and restore nodes
>
> > [tab] Overview
> >
> > **Before 5.12.0:** personal-information handling was configured on the agent rather than placed in the flow. **Now:** masking and restoring personal data are workflow nodes you position explicitly, and you choose which key from the node input they apply to.
> >
> > Put a mask node before the step that must not see the raw values and a restore node after it. The workflow run log shows what each node did, so a run can be inspected without exposing the underlying data.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See the Personal Information Guard documentation.
>
> > [tab] Key Features
> >
> > > [card] Mask and restore as nodes
> > >
> > > Personal-data handling becomes an explicit step in the workflow.
> >
> > > [card] Selectable input key
> > >
> > > Choose which key from the node input the node applies to.
> >
> > > [card] Run-log detail
> > >
> > > A restore reports whether it completed, partially completed or failed, and how many of the issued placeholders it put back.
>
> For the full configuration reference, see [Masking and restoring across several nodes](/5.9/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
> SaaS

### **Db2 relational data source**

> [card] Db2 relational data source
>
> IBM Db2 joins the relational database data sources available in the Integration Designer. Because Db2 products use different drivers, ports and catalogs, the connection starts with a **Db2 Product** choice and the rest of the form follows from it. **Db2 for i (IBM i)** is the default and **Db2 LUW** is also supported. **Db2 for z/OS** appears in the list but is not implemented in this release, and selecting it fails with an explicit error rather than falling back to another driver.
>
> The port is prefilled from the product and whether SSL is on. Db2 for i adds a naming convention, an optional library and library list, and a switch for returning character data that the host reports as binary. On Db2 for i, connections also open **read-only by default**, so turn that off if your queries need to write, and the transaction isolation level defaults to none, because a table without a journal cannot take part in a transaction. Isolation is validated when the data source is saved rather than when a query first runs.
>
> For the full configuration reference, see the [Db2 Database](/5.9/docs/platform-deep-dive/integrations/db2-database) documentation.
> SaaS

***

### **Subworkflow failure exit**

> [card] Subworkflow failure exit
>
> A Subworkflow node now has a second exit. Connect the red one and a failure takes its own branch instead of stopping the parent workflow. It is opt-in per node, so a node without that branch fails and blocks exactly as before and nothing changes for existing workflows.
>
> Only a mapping failure routes, which is the kind a workflow can be built to handle: the input mapper failing, the input not satisfying what the subworkflow expects, or the output mapper failing on merge-back. An unset subworkflow, a missing response key, no mapping at all, and the node and depth limits all still stop the run. The branch reads a fixed `subWorkflowError` key that says which mapping failed and, when a child did start, which run it was.
>
> For the full configuration reference, see [Routing a subworkflow failure](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
> SaaS

***

### **Skip TLS verification on a REST data source**

> [card] Skip TLS verification on a REST data source
>
> A REST data source can now be told to stop checking the certificate of the host it calls, for the cases where an internal endpoint presents a self-signed or mismatched certificate and the alternative is an infrastructure workaround. It is off by default and set per data source, so turning it on for one connector leaves every other call verified.
>
> The Designer warns while it is on, because the call can no longer tell the intended host from anything intercepting it. One consequence is worth knowing before you use it: a truststore configured under Certificates is ignored while verification is skipped, since skipping replaces it rather than adding to it.
>
> For the full configuration reference, see [TLS verification](/5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#tls-verification) on a REST data source.
> SaaS

***

### **Send Notification node**

> [card] Send Notification node
>
> Workflows can now send notifications themselves. A **Send Notification** node, under **Tools** in the workflow node palette, takes one of your project's notification templates, fills its variables from workflow data, and sends it, without routing through a process just to reach the Notifications plugin.
>
> Address it with **To**, **Cc** and **Bcc**, as fixed addresses or `${}` keys. Email options are all overridable per node: subject, sender name and email, attachments by file path or `${}` key, and custom headers. The node reports the outcome under its response key, including recipient counts and the error when sending fails, so the workflow can branch on it.
>
> For the full configuration reference, see the [Send Notification node](/5.9/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node) documentation.
> SaaS

***

### **Reusable functions as agent tools**

> [card] Reusable functions as agent tools
>
> An AI node's tools can now include a **Function**, alongside built-in web search, an MCP server, and a workflow. Point an agent at a reusable function when the work is deterministic and you would rather it call your code than reason its way there.
>
> A function has to be typed to qualify: it needs both an input and an output slice, and functions without them do not appear in the picker. Give it a description as well, since that is what tells the agent when to reach for it.
>
> For the full configuration reference, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **Chat response feedback**

> [card] Chat response feedback
>
> Users can rate an agent's answer in the chat component, and follow the rating with a reason. The ratings are recorded in audit, so the quality of a deployed agent becomes something you can look at rather than guess at.
>
> The feedback controls and the reason chips are themable, with their own selected and hover states, so they can be styled to match the rest of the interface. The SDKs expose the same feedback state to custom front ends.
>
> For the full configuration reference, see [Rating an answer](/5.9/ai-platform/chat-component#rating-an-answer) on the chat component.
> SaaS

***

### **Custom evaluators**

> [card] Custom evaluators
>
> The evaluator catalogue is no longer fixed. When none of the built-in rubrics measures what you care about, you can write your own evaluator, give it the scoring instructions the judge LLM should follow, and it appears in the catalogue under a **Custom** group alongside the built-in ones.
>
> Choose **Numeric** scoring for a score between 0 and 1 with a pass threshold, or **Binary** for a straight pass or fail. You can start from an existing evaluator to adapt a built-in rubric rather than writing a prompt from scratch. Custom evaluators belong to the workflow you create them in, and unlike the built-in ones they can be edited and deleted.
>
> For the full configuration reference, see the [Evaluations](/5.9/ai-platform/evaluations#custom) documentation.
> SaaS

***

### **Deep Research node**

> [card] Deep Research node
>
> A new AI node researches a question across the open web and files a cited report into a Knowledge Base. It plans the work, sends sub-researchers out to search and read pages, grades what they bring back, and keeps going until its budget is spent or it has enough to report.
>
> Unlike a Custom Agent, you do not write the method: the research prompt is built into the node, so you describe the subject and bind workflow data into it. Depth is a **Quick**, **Standard** or **Deep** preset, or **Custom** if you want to set the number of passes and tool calls yourself. You can restrict which domains the research may read, with an allow list, a deny list, or both.
>
> The result always lands in a Knowledge Base as text, so retrieval nodes and other agents can reach it later. Rendering it as a document is optional.
>
> For the full configuration reference, see the [Deep Research node](/5.9/docs/platform-deep-dive/integrations/deep-research-node) documentation.
> SaaS

***

### **Built-in agent tools by category**

> [card] Built-in agent tools by category
>
> A Custom Agent's built-in tools are now a catalog you pick from by category: **Math tools**, **List tools**, **Date tools**, **Text tools**, and **Web search**. Each category row shows exactly which tools it turns on, and the agent runs deterministic code for that work instead of estimating it in the model.
>
> The catalog holds twenty tools, fifteen of them new: a full date family (business days, date arithmetic, formatting, parsing, timezone conversion), text helpers (regex match and extract, fuzzy match), unit conversion, and list aggregation, joining the original calculator, compare, sort, and filter. Web search is part of the same catalog rather than a separate toggle.
>
> Selection stays opt-in and per node. Agents saved with the old toggles keep working without an edit.
>
> For details, see the [Custom Agent node](/5.9/docs/platform-deep-dive/integrations/custom-agent-node) documentation.
> SaaS

***

### **AI Designer builds UI Flows**

> [card] AI Designer builds UI Flows
>
> The AI Designer now works at the level of a whole UI Flow. Describe the journey and it generates a multi-page flow: structure first, pages filled in parallel, navigation wired between them. Ask for a change and it edits the affected pages instead of regenerating everything.
>
> Proposals appear on the UI Flow canvas as a draft for you to review, the editor stays locked while one is pending, and any data-model changes the flow needs are presented for approval on every turn, the same way single-screen generation already works.
>
> For details, see the [AI Designer](/5.9/ai-platform/pre-built-agents/ai-designer#ui-flow-generation-and-editing) documentation.
> SaaS

***

### **Check a version for issues**

> [card] Check a version for issues
>
> The Designer can now validate the resources in a project version and collect what it finds in one **Issues** panel at the bottom of the screen. Findings are marked where they occur, on resource lists, page titles and workflow canvas nodes, and selecting a marker opens the panel on that finding.
>
> Checks run when you ask for one, and the panel says when it last ran so a stale result is obvious. You can scope the list to the whole version, the resource you are in, or the node you have selected, filter it by severity or text, and group it by resource or severity. Opening **Commit Changes to Version** runs a check on its own and shows each changed resource's state beside it, as a review step rather than a gate. Integration workflows are the resource type validated in this first iteration.
>
> For the full configuration reference, see the [Checking a version for issues](/5.9/docs/projects/managing-applications/checking-for-issues) documentation.
> SaaS

***

### **Branch management**

> [card] Branch management
>
> Project branches gained a management layer. The merge modal now offers every branch you can merge into, not just the current branch's parents, so a fix made anywhere can land anywhere it is needed.
>
> Branches you are done with no longer linger: **Archive Branch** retires one (with a required reason, shown later in its info panel), **Unarchive Branch** brings it back, and **Delete Branch** removes one permanently, guarded so it refuses while child branches, an uncommitted draft, or a running merge depend on it, and asks you to type the branch name when unmerged work would be lost. Deleting has its own permission.
>
> Branch and version info panels round it out: a version merged from another branch says where it came from, including whether that branch has since been archived.
>
> For details, see [Managing branches](/5.9/docs/projects/managing-applications/versioning#managing-branches).
> SaaS

***

### **Process canvas editing**

> [card] Process canvas editing
>
> The BPMN canvas gains a set of direct editing improvements. A **New Node** panel and
> drop-anywhere connecting make it quicker to add a node and wire it up, connecting to a nearby
> node no longer means aiming precisely at a handle, and sequence flows can be reshaped by
> dragging their control points. Swimlanes now resize from any of their four edges. The
> process-instance viewer picks up the same canvas.
>
> The canvas is deliberately unchanged to look at, so existing diagrams, habits and screenshots
> still hold.
>
> For the full configuration reference, see [Faster ways to build](/5.9/docs/building-blocks/process/process#faster-ways-to-build) on the Process Designer canvas.
> SaaS

***

### **Reusable UI Templates in UI Flows**

> [card] Reusable UI Templates in UI Flows
>
> A Reusable UI Template can now be built for **UI Flow** pages as well as for the User Tasks in a process. Each template declares where it is used when you create it, and the UI Flow editor can drop templates onto a page the same way the Process editor always could.
>
> The host type also decides which actions a template's event handlers offer, so a template built for UI Flows gets navigation and workflow actions while one built for processes gets node actions. Because of that the choice is fixed once the template exists, and templates you created before this release count as Process templates, so nothing you already built changes.
>
> For the full configuration reference, see [Where a template can be used](/5.9/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used) in the Reusable UI Templates documentation.
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.12.0](./deployment-guidelines-v5.12).


# Deployment guidelines v5.13.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13

Component versions and deployment-level changes for FlowX.AI 5.13.0.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.13 is a **SaaS-managed release**. Deployment-level changes, including infrastructure, Kafka topics, and service configuration, are handled automatically by FlowX. The information below is provided for transparency. Self-hosted deployments receive these capabilities with the next LTS release family.

## Component versions

The versions below are the component versions that make up FlowX.AI 5.13.0. On SaaS these are managed by FlowX; the list is provided for transparency.

### Core components

| Component | 5.13.0 |
| - | - |
| **admin** | 11.97.0 |
| **advancing-controller** | 11.67.0 |
| **application-manager** | 11.101.0 |
| **audit-core** | 11.69.0 |
| **authorization-system** | 11.78.0 |
| **cms-core** | 11.88.0 |
| **data-search** | 11.67.0 |
| **data-sync** | 11.68.0 |
| **designer** | 11.168.1 |
| **designer-user** | 11.8.0 |
| **document-plugin** | 11.95.0 |
| **email-gateway** | 11.83.0 |
| **events-gateway** | 11.72.0 |
| **file-gateway** | 11.79.0 |
| **integration-designer** | 11.119.1 |
| **license** | 11.72.0 |
| **nosql-db-runner** | 11.73.0 |
| **notification-plugin** | 11.88.0 |
| **organization-manager** | 11.77.0 |
| **process-engine** | 11.104.0 |
| **runtime-manager** | 11.101.0 |
| **scheduler-core** | 11.69.0 |
| **task-management-plugin** | 11.84.0 |
| **webhook-gateway** | 11.78.0 |

**designer-user** is new in 5.13. It backs the Designer notification center.

### AI base components

| Component | 5.13.0 |
| - | - |
| **embedder** | 11.6.0 |
| **knowledgebase-indexer-v2** | 11.6.0 |
| **knowledgebase-rag** | 11.6.0 |
| **doc-parser** | 11.6.0 |

### AI dev-time components

| Component | 5.13.0 |
| - | - |
| **ai-gateway** | 11.85.0 |
| **ai-analyst** | 11.6.0 |
| **ai-architect** | 11.6.0 |
| **ai-assistant** | 11.6.0 |
| **ai-designer** | 11.6.0 |
| **ai-developer** | 11.6.0 |
| **harness** | 11.6.0 |
| **ai-render-host** | 11.168.1 |
| **kb-enrichment** | 11.6.0 |
| **planner** | 11.6.0 |

**harness** and **ai-render-host** are new in 5.13. Together they run the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness): harness is the agent service, and ai-render-host renders UI flows headlessly for the agent. ai-render-host ships at the designer version.

### AI runtime components

| Component | 5.13.0 |
| - | - |
| **agent-builder** | 11.6.0 |
| **cee-pii** | 11.6.0 |
| **data-privacy** | 11.6.0 |
| **doc-converter** | 11.6.0 |
| **dynamic-classifier** | 11.6.0 |
| **evals-judge** | 11.6.0 |
| **speech-to-text** | 11.6.0 |
| **web-crawler** | 11.6.0 |

### AI extensions

| Component | 5.13.0 |
| - | - |
| **modpod** | 11.0.1 |
| **observatory-api** | 11.10.2 |
| **observatory-platform** | 11.10.2 |
| **observatory-web** | 11.10.2 |

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.168.1` for FlowX.AI 5.13.0). The native iOS and Android renderers version independently.

| Component | 5.13.0 |
| - | - |
| **@flowx/angular-sdk** | 11.168.1 |
| **@flowx/angular-theme** | 11.168.1 |
| **@flowx/angular-ui-toolkit** | 11.168.1 |
| **@flowx/react-sdk** | 11.168.1 |
| **@flowx/react-theme** | 11.168.1 |
| **@flowx/react-ui-toolkit** | 11.168.1 |
| **@flowx/react-native-sdk** | 11.168.1 |
| **@flowx/react-native-theme** | 11.168.1 |
| **@flowx/react-native-ui-toolkit** | 11.168.1 |
| **@flowx/core-sdk** | 11.168.1 |
| **@flowx/core-theme** | 11.168.1 |
| **react-saas** | 11.168.1 |
| **iOS renderer** | TBD |
| **Android renderer** | TBD |

The **react-saas** container app tracks the designer version.

***

## Configuration changes

> [!NOTE]
>
> On SaaS, required configuration changes are applied automatically by FlowX. The changes below are listed for transparency. Self-hosted deployments will receive them, re-verified, with the next LTS release family.

### New Kafka topics

These topics back new 5.13 capabilities. On SaaS they are created and managed automatically.

**Notification center:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |

Notifications now pass through designer-user, which stores them and forwards them to events-gateway on the existing `ai.flowx.eventsgateway.user.notifications.v1` topic for delivery to the Designer.

**Move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

### New services

The Developer Agentic Harness adds the **harness** and **ai-render-host** services to the AI dev-time group, with a dedicated PostgreSQL database for harness sessions. The notification center adds the **designer-user** core service, which uses MongoDB, Redis, and Kafka. On SaaS these services and their databases are provisioned and managed by FlowX.

### New service dependency: process-engine and object storage

Oversized workflow responses and UI flow updates are now offloaded to object storage instead of travelling inline on Kafka. The process engine reads these offloaded payloads, so it now depends on object storage in addition to its existing databases. On SaaS this connection is provisioned and managed by FlowX.

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` | process-engine, audit-core |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Self-hosted deployments receive this change with the next LTS release family. A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.13.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026

What's new in FlowX.AI 5.13: a user notification center in Designer, UI component copy and paste across contexts, commit descriptions on app versions, and move token on process instances.

[FlowX.AI 5.13 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/hero-5.13.0.html)

> [!NOTE]
>
> **FlowX.AI 5.13 is a SaaS release.** New capabilities are available on managed (SaaS) deployments; self-hosted deployments will receive them with the next LTS release family.

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI **5.13** is a SaaS-managed release: FlowX handles deployment-level changes such as infrastructure, Kafka topics, and service configuration. The headline: the FlowX Developer Agentic Harness, an AI agent in the Designer that builds and changes apps from a description, with you confirming the plan and every operation before it runs. The release also adds a notification center to the Designer, lets builders copy and paste UI components across apps with a review of what could not be placed, records a description on every app version commit, forwards runtime events to Mixpanel and GA4, and moves stuck tokens on running process instances.

### What changed since 5.12.0

| 5.12.0 | 5.13.0 |
| - | - |
| Apps were assembled by hand in the Designer | + **Developer Agentic Harness**: describe the change, confirm the plan, review the result on its own branch |
| Long-running operations surfaced as passing toasts | + **Notification center** keeps a searchable 30-day history with read state |
| UI components copied within one context | + **Copy and paste across contexts**, with a paste review and unique naming |
| App version commits had a name only | + **Commit descriptions** and a commit details view record why a version exists |
| A stuck process instance needed support intervention | + **Move token** relocates the token, guarded by a dedicated corrective-actions role |

***

**What's new?**

> [tab] Builders
>
> 🔔 [**User notification center**](#user-notification-center) - Bell, searchable history, read state in Designer\
> 📋 [**UI component copy and paste**](#ui-component-copy-and-paste) - Cross-context paste with review and unique naming\
> 📝 [**Commit descriptions and details**](#commit-descriptions-and-details) - Optional description on version commits plus a details view\
> 📦 [**Version export alignment**](#version-export-alignment) - Version exports bundle dependencies like build exports

> [tab] Platform
>
> 🚑 [**Move token and corrective actions**](#move-token-and-corrective-actions) - Relocate a token, gated by a dedicated role

> [tab] AI Platform
>
> 🪄 [**Developer Agentic Harness**](#developer-agentic-harness) - Describe a change, the agent plans and builds it on a branch\
> 🧠 [**ML corpus import and export**](#ml-corpus-import-and-export) - Move a document classifier corpus between environments\
> ⚖️ [**Fair scheduling for embedding jobs**](#fair-scheduling-for-embedding-jobs) - Knowledge Base ingestion no longer starves small jobs\
> 🧩 [**Data Parse node**](#data-parse-node) - Tabular Data Extraction generalized, now parses XML and JSON\
> 🔐 [**File Encryption node**](#file-encryption-node) - Encrypt and decrypt files inside a workflow

> [tab] Rendering & SDKs
>
> 💬 [**React Native chat component**](#react-native-chat-component) - Floating chat sheet with voice input on mobile\
> ▶️ [**Conditional start workflow trigger**](#conditional-start-workflow-trigger) - Start a workflow from the UI only when a condition holds

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > **Before 5.13.0:** every process, screen, and data type was assembled by hand in the Designer. **Now:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys your app first, so changes use your real resources and names, then drafts a plan for you to confirm.
> >
> > You hold every gate: the agent runs only after you confirm the plan and review each operation, the change lands on a dedicated branch that never touches your main line, and merging plus serving a new version stay human decisions. See the [Developer Agentic Harness](/5.9/ai-platform/developer-agentic-harness) page for the full flow.
> >
> > <video>
> >   <track label="English" />
> > </video>
>
> > [tab] Key Features
> >
> > > [card] Works on your real app
> > >
> > > Surveys existing resources first, so changes use your actual processes, data types, and names.
> >
> > > [card] Plan, confirm, then run
> > >
> > > You confirm the plan and review every operation; the change runs on a dedicated branch that only you can merge or serve.
> >
> > > [card] Broad resource coverage
> > >
> > > Creates and edits processes, UI flows, workflows, and project data types.
> >
> > > [card] Guarded operations
> > >
> > > Destructive changes are gated, and runtime data such as process instances is never touched.
>
> SaaS

### **User notification center**

> [card] User notification center
>
> > [tab] Overview
> >
> > **Before 5.13.0:** long-running operations such as app imports or instance migrations announced themselves once and were gone. **Now:** a bell in the Designer opens a notification center with a 30-day history.
> >
> > Notifications carry read state, search, and filters by unread status and workspace type. First producers: app version export and process instance migration results.
>
> > [tab] Key Features
> >
> > > [card] 30-day history
> > >
> > > Notifications persist for 30 days instead of disappearing with the toast.
> >
> > > [card] Read state and search
> > >
> > > Mark notifications read, search them, and filter by unread status or workspace type.
> >
> > > [card] Export and migration results
> > >
> > > Get notified when an app version export finishes, fails, or times out, and when a process instance migration completes.
> >
> > > [card] Live updates
> > >
> > > The center updates over a live stream, including read state changes from other sessions.
>
> SaaS

### **UI component copy and paste**

> [card] UI component copy and paste
>
> > [tab] Overview
> >
> > **Before 5.13.0:** copying UI components was limited to the context you were in. **Now:** builders copy components and paste them into another UI Flow, app, or context.
> >
> > Pasting responds with a review of what could not be placed instead of failing silently, and pasted components receive unique names automatically. The clipboard holds one consistent version of the copied structure.
>
> > [tab] Key Features
> >
> > > [card] Cross-context paste
> > >
> > > Paste a copied component into a different UI Flow or app through a dedicated modal.
> >
> > > [card] Paste review
> > >
> > > The paste result names anything it could not place, so nothing drops without a trace.
>
> SaaS

### **Commit descriptions and details**

> [card] Commit descriptions and details
>
> Committing or merging an app version now takes an optional description of up to 2000 characters, and a commit details view shows what a version contains and why it exists. Version history stops being a list of names.
> SaaS

### **Version export alignment**

> [card] Version export alignment
>
> Project version exports now bundle dependencies the same way build exports do, so a version export is self-contained. The export dialog pre-selects the target platform version, and the exported filename carries the target version and whether media is included.
> SaaS

### **Move token and corrective actions**

> [card] Move token and corrective actions
>
> > [tab] Overview
> >
> > **Before 5.13.0:** a process instance stuck on the wrong node needed support intervention. **Now:** an operator with the corrective-actions role moves the token to the right node from Runtime.
> >
> > Corrective actions, covering bulk instance migration and move token, are gated by a dedicated workspace-level role, so admins grant this power without handing out full admin rights.
> >
> > The **Workspace corrective actions editor** role replaces the Workspace operations editor role. Users and groups that had the old role are moved to the new one automatically. See [Move tokens](/5.9/docs/projects/runtime/active-process/move-token) and the [Workspace corrective actions editor permission matrix](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
>
> > [tab] Key Features
> >
> > > [card] Move token
> > >
> > > Relocate the token of a running instance to another node in the process definition.
> >
> > > [card] Dedicated role
> > >
> > > A workspace-level corrective-actions role scopes who can migrate instances and move tokens.
>
> SaaS

### **ML corpus import and export**

> [card] ML corpus import and export
>
> A document classifier corpus now moves between environments: export the corpus with the model, import it into a runtime classifier, and inspect it in a read-only view in the Data tab. Training data stops being trapped in the environment where labeling happened.
> SaaS

### **Fair scheduling for embedding jobs**

> [card] Fair scheduling for embedding jobs
>
> Knowledge Base embedding jobs are scheduled fairly by default, so a large ingestion no longer starves small jobs queued behind it. Uploads to one Knowledge Base stop delaying every other one on the environment.
> SaaS

### **Data Parse node**

> [card] Data Parse node
>
> The Tabular Data Extraction node is generalized into a **Data Parse** node: it still reads CSV and Excel files into workflow data, and now also parses **XML** and **JSON**. A file fetched by a File Storage Operation can be read into the workflow regardless of its structured format.
> SaaS

### **File Encryption node**

> [card] File Encryption node
>
> A new **File Encryption** workflow node encrypts or decrypts a file with a password directly in the workflow, so protecting a generated document or opening a protected upload no longer needs a custom integration. The file path and password take expressions, letting the password come from workflow data.
> SaaS

### **React Native chat component**

> [card] React Native chat component
>
> The React Native renderer gains the chat experience mobile apps were missing: a floating chat sheet with voice input, suggested prompts, and conversation history. Renderer updates in the same release cover form validation on navigation actions, action context on execute-URL, and bulk enum fetching on eager load.
> SaaS

### **Conditional start workflow trigger**

> [card] Conditional start workflow trigger
>
> A start workflow trigger in the UI now takes a condition, so the workflow starts only when the expression holds. Available in the web SDK and on iOS.
> SaaS

### **Smaller improvements**

> [card] Smaller improvements
>
> **Process details modal:** the process name moves from Settings into a Details modal.
>
> **Document and image sources:** Document and Image UI components share one source configuration. In process user tasks, the new **Document Plugin Path** source takes a Documents plugin `downloadPath` directly, so you no longer need a business rule to build the file URL. See [File sources in FlowX.AI 5.13](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-preview#file-sources-in-flowx-ai-5-13) for File Preview and the [Download component](/5.9/docs/building-blocks/ui-designer/ui-component-types/file-download#file-sources-in-flowx-ai-5-13).
>
> **Sign-up link to solution:** a sign-up link lands new users directly in the right solution.
>
> **Bulk invite:** inviting many users at once gets a reworked flow.
>
> **Task list search on translated labels:** the task list searches, filters, and sorts on the labels it displays, in the viewer's language, for status, enumeration, and substitution-tag columns. See [Search and sort on translated labels](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).&#x20;
>
> **Reserved substitution-tag prefix:** custom substitution tags can no longer start with `sys_`; the prefix is reserved for system tags.&#x20;
> **Intersects operator for array fields:** FlowX Database queries can match documents whose array field shares at least one value with a given list. See [Intersects on array fields](/5.9/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).&#x20;
>
> **Request after PII anonymization in the run log:** AI nodes with the input scan enabled log the request exactly as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/5.9/ai-platform/personal-information-guard#request-after-pii-anonymization).&#x20;
>
> **Elasticsearch replica auto-expansion:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Changed default: Elasticsearch replica auto-expansion](./deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).&#x20;
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.13.0](./deployment-guidelines-v5.13).


# Deployment guidelines v5.2.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/deployment-guidelines-v5.2

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.12.0** | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **10.12.0** | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **10.7.0** | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **10.4.1** | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **10.7.0** | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **10.6.0** | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **10.4.1** | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **10.6.0** | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **10.4.1** | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **10.8.0** | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **10.11.0** | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **10.3.1** | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **10.7.0** | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **10.4.1** | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **10.12.1** | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **10.0.0** | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **10.0.0** | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.0.1** | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | **10.2.0** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **10.0.1** | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.2.0 | Keycloak | 26+ |
| 5.2.0 | Kafka | 3.8 - 3.9 |
| 5.2.0 | PostgreSQL | 16 - 17 |
| 5.2.0 | Oracle Database | 21c, 23ai |
| 5.2.0 | MongoDB | 7 - 8 |
| 5.2.0 | Redis | 7.4 - 8.0 |
| 5.2.0 | Elasticsearch | 8 - 9 |
| 5.2.0 | Angular (Web SDK) | 19.2 |
| 5.2.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.2.0

### Key infrastructure updates

> [card] SpiceDB Upgrade
>
> Upgraded to SpiceDB v1.38.0+ and spice-db-operator for improved permission management and stability

> [card] Security Enhancements
>
> Updated Java libraries and base images to Oracle 10-slim, resolving HIGH and CRITICAL vulnerabilities

> [card] Accessibility Support
>
> Enhanced renderer components with comprehensive WCAG 2.1 compliance features

> [card] Python IDE Features
>
> Added autocomplete and IntelliSense support in business rules editors

> [card] Parallel Workflow Branches
>
> Support for concurrent execution paths in Integration Designer workflows

> [card] Workflow Partitioning & Archiving
>
> Time-based partitioning and automatic archiving for Integration Designer workflow instances

## Upgrading from v5.1.0

### Key changes

* **Accessibility Features**: No breaking changes, but new accessibility properties available in UI Designer
* **Database Security**: FlowX Database now supports sensitive data masking (requires Project Data Model configuration)
* **IDE Enhancements**: Python autocomplete is automatically available in business rules editors
* **Infrastructure**: SpiceDB upgrade requires cache clearing after migration

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.

### Compatibility

* **Backward Compatible**: v5.2.0 maintains backward compatibility with v5.1.0 configurations
* **Renderer Updates**: Web SDKs include accessibility enhancements without breaking changes
* **Mobile Renderers**: iOS and Android renderers include accessibility improvements

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/update-environment-variables-5.2

Update environment variables for all existing FlowX.AI services

## Integration Designer

### Workflow partitioning and archiving

> [!NOTE]
>
> Integration Designer now supports workflow instance partitioning and automatic archiving for efficient data management in high-volume deployments.

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Enable or disable workflow instance partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Time interval for creating partitions (`DAY`, `WEEK`, `MONTH`) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Enable or disable automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Cron expression for archiving schedule (default: daily at 1:00 AM) |

> [!NOTE]
>
> **Workflow partitioning configuration:**
>
> * **Partitioning**: When enabled, workflow instances are stored in time-based partitions according to the specified interval
> * **Retention**: Determines how many intervals to keep active. Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> * **Archiving schedule**: The cron expression controls when the archiving process runs
> * **Best practice**: Enable partitioning first without archiving, verify it works correctly, then enable archiving

> [!WARNING]
>
> Enable partitioning and archiving only after careful planning and testing. Ensure your database has sufficient storage for partition management operations. It's recommended to start with archiving disabled and enable it only after verifying that partitioning works correctly for your use case.

### Advancing controller improvements

> [!NOTE]
>
> Integration Designer now uses the new ADVANCING controller with separate picking and processing operations for improved performance and resource management.

#### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

#### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

#### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.


# FlowX.AI 5.2.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.2.0-november-2025/v5.2.0-november-2025

Accessibility improvements, new side panel navigation, FlowX Database sensitive data handling, REST API response caching, and Python IDE enhancements for business rules development.

**What's new?**

> [tab] Accessibility & UX
>
> Making FlowX applications more inclusive and user-friendly with comprehensive accessibility improvements and enhanced navigation.
>
> ♿ [**Accessibility Enhancements**](#accessibility-enhancements) - Comprehensive [WCAG](https://www.w3.org/TR/WCAG21/) (Web Content Accessibility Guidelines) compliance features across all UI components\
> 🎨 [**New Workflow Side Panel**](#new-workflow-side-panel) - Enhanced navigation experience with improved drag-and-drop functionality
>
> ### **Accessibility enhancements**
>
> > [card] Accessibility enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds accessibility features across all UI components, enabling you to build [WCAG 2.1 Level AA compliant](https://www.w3.org/TR/WCAG21/) applications. These features support users with assistive technologies such as screen readers and keyboard-only navigation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs1.png)
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/accs2.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Accessibility Configuration Panel
> > > >
> > > > Configure labels, descriptions, and ARIA attributes in a dedicated accessibility section within UI Designer
> > >
> > > > [card] Auto-bindable Tags
> > > >
> > > > Bind accessibility tags automatically to buttons, inputs, selects, modals, and other UI components
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Navigate using keyboard shortcuts with proper focus management and tab order in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > Use screen readers with ARIA labels, descriptions, and live regions on all components
> >
> > > [tab] Supported Components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio buttons, Slider, and File upload components with labels and descriptions
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card components with keyboard navigation and focus management
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with alt text support and semantic HTML structure
> > >
> > > **4. Cross-Platform Support**
> > >
> > > Web (Angular/React), iOS, and Android platforms
> >
> > > [tab] Benefits
> > >
> > > > [card] WCAG Compliance
> > > >
> > > > Build applications that meet WCAG 2.1 Level AA standards for web accessibility
> > >
> > > > [card] Inclusive Design
> > > >
> > > > Make your applications usable for people with diverse abilities and assistive technology users
> > >
> > > > [card] Improved User Experience
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those using assistive technologies
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Meet accessibility requirements for government, healthcare, financial services, and other regulated industries
> >
> > Major Enhancement
>
> ***
>
> ### **New workflow side panel**
>
> > [card] New workflow side panel
> >
> > > [tab] Overview
> > >
> > > The new Workflow Side Panel provides an enhanced navigation experience in Integration Designer workflows. It includes improved organization, better drag-and-drop functionality, and intuitive access to design components and resources.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/wf_side_panel.png)
> >
> > > [tab] Key Features
> > >
> > > > [card] Drag & Drop
> > > >
> > > > Add and organize workflow nodes with drag-and-drop functionality
> > >
> > > > [card] Improved Organization
> > > >
> > > > Group nodes logically with expandable/collapsible sections
> > >
> > > > [card] Search & Filter
> > > >
> > > > Find nodes instantly with quick search functionality
> >
> > UI/UX Enhancement
>
> ***

> [tab] Data & Security
>
> Enhanced data management and security features for FlowX Database and business rules.
>
> 🔒 [**FlowX Database Sensitive Data**](#flowx-database-sensitive-data) - GDPR-compliant sensitive data handling for FlowX Database\
> 🚀 [**Performance Improvements**](#performance-improvements) - Caching optimizations for better system performance
>
> ### **FlowX database sensitive data**
>
> > [card] FlowX database sensitive data
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds sensitive data handling for FlowX Database to ensure GDPR compliance. Attributes marked as sensitive in your Project Data Model are automatically protected across all FlowX Database operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic Data Masking
> > > >
> > > > Hide sensitive attributes automatically in logs, console outputs, and testing interfaces
> > >
> > > > [card] Project Data Model Integration
> > > >
> > > > Mark attributes as sensitive in Project Data Model to apply protection across all FlowX Database operations
> > >
> > > > [card] Developer-Friendly
> > > >
> > > > Access full data at runtime while maintaining security in design-time interfaces
> > >
> > > > [card] Audit Trail Protection
> > > >
> > > > Mask sensitive data in workflow output logs and operational documents
> >
> > > [tab] Protected Areas
> > >
> > > **1. Documents Page**
> > >
> > > Sensitive attributes are masked when viewing FlowX Database documents in the designer
> > >
> > > **2. Test Operations Pages**
> > >
> > > Database operation testing interfaces automatically hide sensitive data
> > >
> > > **3. Workflow Console**
> > >
> > > Console logs and output panels mask sensitive information from FlowX Database responses
> > >
> > > **4. Full Runtime Access**
> > >
> > > Applications have full access to sensitive data at runtime - protection is design-time only
> >
> > > [tab] Benefits
> > >
> > > > [card] GDPR Compliance
> > > >
> > > > Meet data protection requirements by preventing sensitive data exposure in design tools
> > >
> > > > [card] Security by Design
> > > >
> > > > Sensitive data protection is automatic once attributes are marked in Project Data Model
> > >
> > > > [card] Developer Productivity
> > > >
> > > > Test and develop without worrying about accidentally exposing sensitive information
> > >
> > > > [card] Audit-Ready
> > > >
> > > > Demonstrate proper data handling practices with masked logs and interfaces
> >
> > Security Enhancement
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Caching Enhancements
> > >
> > > FlowX.AI 5.2.0 adds intelligent caching mechanisms that improve system performance by reducing redundant processing when identical values are sent at process start.
> >
> > > [tab] Key Features
> > >
> > > > [card] Smart Caching
> > > >
> > > > Cache and reuse results automatically when identical input values are detected
> > >
> > > > [card] Reduced Latency
> > > >
> > > > Start processes faster when repeating operations with the same parameters
> > >
> > > > [card] Resource Optimization
> > > >
> > > > Reduce server load and improve resource utilization
> > >
> > > > [card] Automatic Management
> > > >
> > > > Manage cache automatically with no configuration required
> >
> > > [tab] Benefits
> > >
> > > **1. Response Times**
> > >
> > > Initialize processes faster in cached scenarios
> > >
> > > **2. Scalability**
> > >
> > > Handle more concurrent users with the same infrastructure
> > >
> > > **3. Cost Efficiency**
> > >
> > > Use fewer compute resources for high-volume scenarios
> >
> > Performance

> [tab] Developer Experience
>
> Enhanced tools and features for business rules development, testing, and workflow design.
>
> 🔀 [**Parallel Branches in Workflows**](#parallel-branches-in-workflows) - Design and execute parallel execution paths in Integration Designer workflows\
> 💾 [**REST API Response Caching**](#integration-designer-rest-api-response-caching) - Cache GET endpoint responses in Integration Designer with flexible TTL policies\
> 📊 [**Workflow Partitioning & Archiving**](#workflow-partitioning-&-archiving) - Manage Integration Designer workflow data efficiently with time-based partitions and automatic archiving\
> 🐍 [**Python IDE Enhancements**](#python-ide-enhancements) - Autocomplete and IntelliSense for Python business rules\
> 🧪 [**Business Rules Testing**](#functions-testing) - Save test parameters in reusable functions modal
>
> ### **Parallel branches in workflows**
>
> > [card] Parallel branches in workflows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds the ability to design and execute parallel branches in Integration Designer workflows. This enables concurrent execution of independent workflow paths and improves performance for complex integrations.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Start Parallel Node
> > > >
> > > > Split workflow execution into multiple concurrent branches with start parallel nodes
> > >
> > > > [card] End Parallel Node
> > > >
> > > > Merge parallel branches with end parallel nodes that wait for all branches to complete
> > >
> > > > [card] Path Visualization
> > > >
> > > > View which nodes belong to which parallel branch with visual path indexing in the workflow diagram
> > >
> > > > [card] Runtime Monitoring
> > > >
> > > > Track parallel path execution with timing information for each branch and merge point
> >
> > > [tab] How It Works
> > >
> > > **1. Design Parallel Paths**
> > >
> > > Add a Start Parallel node and create multiple sequences from it. Each sequence represents an independent execution path
> > >
> > > **2. Configure Branch Logic**
> > >
> > > Add workflow nodes to each parallel branch, such as API calls, transformations, or database operations
> > >
> > > **3. Merge Paths**
> > >
> > > Close parallel branches with an End Parallel node. This node waits for all branches to complete before continuing
> > >
> > > **4. Runtime Execution**
> > >
> > > All branches execute concurrently at runtime. The End Parallel node completes when the slowest branch finishes
> >
> > > [tab] Use Cases
> > >
> > > > [card] Multiple API Calls
> > > >
> > > > Call multiple independent APIs concurrently instead of sequentially, reducing total execution time
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Fetch data from multiple sources in parallel for comprehensive data aggregation
> > >
> > > > [card] Notification Broadcasting
> > > >
> > > > Send notifications through multiple channels (email, SMS, push) simultaneously
> > >
> > > > [card] Document Processing
> > > >
> > > > Process different document types or sections in parallel for faster throughput
> >
> > > [tab] Runtime Behavior
> > >
> > > > [accordion] Path Timing
> > > >
> > > > * **Path Time**: Sum of all node execution times within that branch
> > > > * **End Parallel Time**: Node processing time + maximum time across all parallel paths
> > > > * **Example**: If Branch A takes 2s and Branch B takes 5s, the End Parallel node completes after 5s (plus its own processing time)
> > >
> > > > [accordion] Console Logging
> > > >
> > > > * **Start Parallel Node**: Displays Input tab showing data split across branches
> > > > * **End Parallel Node**: Displays Output tab showing merged results from all branches
> > > > * **Path Grouping**: Nodes within each parallel path are grouped for easy monitoring
> > >
> > > > [accordion] Error Handling
> > > >
> > > > * If any branch fails, the workflow handles it according to standard error handling rules
> > > > * End Parallel node waits for all non-failed branches before continuing
> > > > * Runtime validation ensures parallel branches are configured correctly
> >
> > > [tab] Limitations
> > >
> > > > [!WARNING]
> > > >
> > > > **First Iteration Constraints**: This is the initial implementation of parallel branches with the following considerations:
> > >
> > > * **Array Processing**: Arrays are not merged across parallel branches. When multiple branches modify the same array path, the last branch to complete determines the final array value. You cannot process individual objects from the same array in different parallel branches (for example, first element in branch 1, second element in branch 2). To preserve data from all branches, save to different keys and merge manually using a script before the end node
> > >
> > > * **Branch Closure**: All start parallel branches must be closed with end parallel nodes. Nodes following a start parallel node must merge into the same end parallel node, except for nodes that terminate with end workflow nodes
> > >
> > > > [!NOTE]
> > > >
> > > > Based on user feedback and raised exceptions during runtime execution, additional configuration constraints and validations are planned for future releases.
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Reduce workflow execution time by running independent operations concurrently instead of sequentially
> > >
> > > **2. Resource Utilization**
> > >
> > > Maximize throughput by executing multiple operations simultaneously
> > >
> > > **3. Design Clarity**
> > >
> > > Model concurrent operations explicitly in your workflow diagrams
> > >
> > > **4. Monitoring**
> > >
> > > Track execution time for each parallel path to identify bottlenecks
> >
> > Integration Designer
>
> ***
>
> ### **Integration Designer REST API response caching**
>
> > [card] Integration Designer REST API response caching
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces intelligent response caching for REST API GET endpoints in Integration Designer. Cache responses based on flexible Time-To-Live (TTL) policies to reduce redundant API calls, avoid rate limits, and lower operational costs while maintaining data freshness.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Endpoint_Get.png)
> > >
> > > > [!NOTE]
> > > >
> > > > When data is stable for a defined period, caching eliminates unnecessary external API calls and improves workflow performance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Flexible TTL Policies
> > > >
> > > > Configure caching with "Expires after" (duration-based) or "Expires at" (time-based) policies
> > >
> > > > [card] Cache Management
> > > >
> > > > Clear cached responses from endpoint definitions or testing modals as needed
> > >
> > > > [card] Cache Status Visibility
> > > >
> > > > View cache status, keys, and TTL information in testing modals and workflow console logs
> > >
> > > > [card] Automatic Fallback
> > > >
> > > > System automatically calls the external API if cache retrieval fails, ensuring reliability
> >
> > > [tab] TTL Configuration
> > >
> > > > [accordion] Expires After (Duration-Based)
> > > >
> > > > Cache responses for a specific duration after the request is made.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **ISO Duration**: Use ISO 8601 duration format (e.g., `PT1H` for 1 hour, `P1D` for 1 day, `P1W` for 1 week)
> > > > * **Dynamic Duration**: Reference configuration parameters (e.g., `${myConfigParam}`)
> > > > * **Default**: `R/P1D` (1 day)
> > > >
> > > > **Example**: Cache for 10 minutes after each request
> > > >
> > > > ```
> > > > PT10M
> > > > ```
> > >
> > > > [accordion] Expires At (Time-Based)
> > > >
> > > > Cache responses until a specific time of day with recurring patterns.
> > > >
> > > > **Configuration Options**:
> > > >
> > > > * **Expire Time**: Set specific time (e.g., `23:00` for midnight, `08:00` for 8 AM)
> > > > * **Recurrency**: Set how often the pattern repeats (integer > 0, default: 1)
> > > > * **Time Unit**: Choose Day, Week, or Month (default: Day)
> > > >
> > > > **Example**: Cache until midnight every day
> > > >
> > > > ```
> > > > Expire Time: 00:00
> > > > Recurrency: 1
> > > > Time Unit: Day
> > > > ```
> > > >
> > > > **Example**: Cache until 6 PM every Friday
> > > >
> > > > ```
> > > > Expire Time: 18:00
> > > > Recurrency: 1
> > > > Time Unit: Week
> > > > ```
> >
> > > [tab] Cache Visibility
> > >
> > > **1. Testing Modal**
> > >
> > > View cache status directly in the endpoint testing modal with:
> > >
> > > * **Cache Hit/Miss Status**: Whether results came from cache
> > > * **Cache Key**: The unique identifier for the cached response
> > > * **TTL Information**: When the cache expires (e.g., "Expires after PT10M" or "Expires at 23:00 on 2025-11-04")
> > >
> > > **2. Workflow Console**
> > >
> > > Monitor cache usage in workflow execution logs with the same detailed information
> > >
> > > **3. Clear Cache Action**
> > >
> > > Clear cached responses from the endpoint page or testing modal when cache is configured
> >
> > > [tab] How It Works
> > >
> > > **1. Configure Caching**
> > >
> > > In Integration Designer, open a REST System and navigate to a GET endpoint. Enable caching and select your TTL policy (Expires After or Expires At)
> > >
> > > **2. First Request**
> > >
> > > When the endpoint is called for the first time, the response is fetched from the external API and stored in cache with the configured TTL
> > >
> > > **3. Subsequent Requests**
> > >
> > > If the cache is still valid (within TTL), subsequent requests return the cached response immediately without calling the external API
> > >
> > > **4. Cache Expiration**
> > >
> > > Once TTL expires, the next request fetches fresh data from the external API and updates the cache
> > >
> > > **5. Cache Management**
> > >
> > > Use the "Clear Cache" action to manually invalidate cached responses when needed (e.g., after data updates)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Reference Data
> > > >
> > > > Cache country lists, product catalogs, or other reference data that rarely changes
> > >
> > > > [card] Rate Limit Avoidance
> > > >
> > > > Reduce API calls to third-party services with strict rate limits
> > >
> > > > [card] Cost Optimization
> > > >
> > > > Lower operational costs by reducing billable API calls to external services
> > >
> > > > [card] Performance
> > > >
> > > > Improve workflow execution speed by eliminating network latency for cached responses
> >
> > > [tab] Error Handling
> > >
> > > > [!WARNING]
> > > >
> > > > **Reliability First**: If any issue occurs with cache retrieval or storage, FlowX.AI automatically falls back to calling the external API directly. This ensures your workflows always receive correct data.
> > >
> > > **Failure Scenarios**:
> > >
> > > * Cache service unavailable → Direct API call
> > > * Cache corruption or invalid data → Direct API call
> > > * Cache storage failure → Direct API call (with warning logged)
> > >
> > > Your workflows continue to function normally even if caching fails.
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced API Costs
> > > >
> > > > Minimize charges from external APIs by serving cached responses when data hasn't changed
> > >
> > > > [card] Improved Performance
> > > >
> > > > Return responses instantly from cache instead of waiting for external API calls
> > >
> > > > [card] Rate Limit Compliance
> > > >
> > > > Stay within API rate limits by reducing the number of requests to external services
> > >
> > > > [card] Better Scalability
> > > >
> > > > Handle higher workflow volumes without increasing external API calls
> >
> > Integration Designer
>
> > [card] [REST Endpoint Caching](../../../5.9/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching)
> >
> > Learn how to configure caching policies, manage cache, and optimize your REST API integrations
>
> ***
>
> ### **Workflow partitioning & archiving**
>
> > [card] Workflow partitioning & archiving
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 introduces workflow instance partitioning and archiving for Integration Designer. This feature enables efficient management of workflow data by organizing instances into time-based partitions and automatically archiving old data to maintain optimal database performance in large-scale deployments.
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow partitioning is particularly beneficial for high-volume Integration Designer workflows where instances accumulate over time, helping to maintain query performance and manage storage efficiently.
> >
> > > [tab] Key Features
> > >
> > > > [card] Time-Based Partitioning
> > > >
> > > > Organize workflow instances into partitions based on configurable time intervals (Day, Week, or Month)
> > >
> > > > [card] Automatic Archiving
> > > >
> > > > Automatically archive partitions older than the specified retention period to optimize active database size
> > >
> > > > [card] Flexible Retention Policies
> > > >
> > > > Configure how many time intervals to retain before archiving with granular control
> > >
> > > > [card] Scheduled Archiving
> > > >
> > > > Use cron expressions to schedule archiving operations at optimal times
> >
> > > [tab] Configuration
> > >
> > > Configure workflow partitioning using environment variables in Integration Designer:
> > >
> > > > [accordion] Partitioning Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ENABLED`**: Enable or disable workflow instance partitioning
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_INTERVAL`**: Time interval for creating partitions
> > > >   * Default: `MONTH`
> > > >   * Options: `DAY`, `WEEK`, `MONTH`
> > >
> > > > [accordion] Archiving Settings
> > > >
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED`**: Enable or disable automatic archiving
> > > >   * Default: `false`
> > > >   * Options: `true`, `false`
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS`**: Number of intervals to retain before archiving
> > > >   * Default: `3`
> > > >   * Options: Any positive integer
> > > >   * Example: With `MONTH` interval and `3` retention intervals, partitions older than 3 months are archived
> > > > * **`FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION`**: Schedule for archiving operations
> > > >   * Default: `0 0 1 * * ?` (runs daily at 1:00 AM)
> > > >   * Options: Any valid cron expression
> >
> > > [tab] How It Works
> > >
> > > **1. Enable Partitioning**
> > >
> > > Set `FLOWX_DATA_PARTITIONING_ENABLED=true` to start organizing workflow instances into time-based partitions
> > >
> > > **2. Configure Partition Interval**
> > >
> > > Choose a partition interval (DAY, WEEK, or MONTH) based on your workflow volume and retention needs
> > >
> > > **3. Set Retention Policy**
> > >
> > > Define how many intervals to retain. For example, with MONTH interval and 3 retention intervals, data older than 3 months will be archived
> > >
> > > **4. Enable and Schedule Archiving**
> > >
> > > Turn on archiving and configure the cron expression to run archiving operations during low-traffic periods
> > >
> > > **5. Monitor Performance**
> > >
> > > Track database performance improvements as old partitions are archived and active data size is optimized
> >
> > > [tab] Use Cases
> > >
> > > > [card] High-Volume Workflows
> > > >
> > > > Maintain performance for Integration Designer workflows processing thousands of instances daily
> > >
> > > > [card] Compliance Requirements
> > > >
> > > > Archive historical workflow data while maintaining access to recent instances for operational needs
> > >
> > > > [card] Database Optimization
> > > >
> > > > Keep active database size manageable by automatically moving old data to archive partitions
> > >
> > > > [card] Long-Running Deployments
> > > >
> > > > Prevent database bloat in production environments running for extended periods
> >
> > > [tab] Best Practices
> > >
> > > > [!WARNING]
> > > >
> > > > **Planning and Testing Required**: Enable partitioning and archiving only after careful planning and testing. Once enabled:
> > > >
> > > > * Ensure sufficient database storage for partition management operations
> > > > * Start with archiving disabled to verify partitioning works correctly
> > > > * Test thoroughly in non-production environments before enabling in production
> > > > * Monitor database performance during initial archiving operations
> > > > * Choose partition intervals based on your workflow volume and retention requirements
> > >
> > > **Recommended Approach**:
> > >
> > > 1. Enable partitioning first without archiving
> > > 2. Monitor partition creation and database performance
> > > 3. After verifying stable operation, enable archiving
> > > 4. Schedule archiving during low-traffic periods (e.g., overnight)
> > > 5. Start with longer retention periods and adjust based on requirements
> >
> > > [tab] Benefits
> > >
> > > > [card] Improved Performance
> > > >
> > > > Maintain fast query performance as workflow instance count grows over time
> > >
> > > > [card] Efficient Storage
> > > >
> > > > Optimize database storage by archiving historical data while keeping recent data accessible
> > >
> > > > [card] Automatic Management
> > > >
> > > > Set retention policies once and let the system handle archiving automatically
> > >
> > > > [card] Scalability
> > > >
> > > > Support long-running production deployments with predictable database growth
> >
> > Integration Designer
>
> > [card] [Integration Designer Setup](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration)
> >
> > Learn how to configure workflow partitioning and archiving for Integration Designer
>
> ***
>
> ### **Python IDE enhancements**
>
> > [card] Python IDE enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds professional IDE features to Python business rules development, including autocomplete, IntelliSense, and enhanced code editing capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Autocomplete
> > > >
> > > > Get intelligent code suggestions as you type, including Python standard library and FlowX APIs
> > >
> > > > [card] IntelliSense
> > > >
> > > > Use context-aware code completion with parameter hints and documentation
> > >
> > > > [card] Syntax Highlighting
> > > >
> > > > Read code more easily with enhanced Python syntax highlighting
> > >
> > > > [card] Error Detection
> > > >
> > > > Detect syntax errors in real-time with helpful error messages
> >
> > > [tab] Benefits
> > >
> > > **1. Development Speed**
> > >
> > > Write business rules faster with intelligent code suggestions
> > >
> > > **2. Error Reduction**
> > >
> > > Catch syntax errors before deployment with real-time validation
> > >
> > > **3. API Discovery**
> > >
> > > Discover available APIs and methods through IntelliSense
> > >
> > > **4. Professional Experience**
> > >
> > > Use IDE-quality editing features directly in FlowX Designer
> >
> > Developer Tools
>
> ***
>
> ### **Functions testing**
>
> > [card] Functions testing
> >
> > > [tab] Overview
> > >
> > > Test Reusable Functions more efficiently by saving test parameters directly from the testing modal. This enables faster iteration and better test coverage.
> > >
> > > <video />
> >
> > > [tab] Key Features
> > >
> > > > [card] Save Test Parameters
> > > >
> > > > Save test inputs directly from the testing modal and reuse them in future test runs
> > >
> > > > [card] Test History
> > > >
> > > > Access previously saved test parameters for regression testing
> > >
> > > > [card] Faster Iteration
> > > >
> > > > Re-test functions quickly with saved parameter sets
> > >
> > > > [card] Test Coverage
> > > >
> > > > Build a library of test cases for comprehensive function validation
> >
> > > [tab] Benefits
> > >
> > > **1. Quality**
> > >
> > > Test functions more thoroughly to improve quality
> > >
> > > **2. Time Savings**
> > >
> > > Avoid re-entering test data for each test iteration
> > >
> > > **3. Documentation**
> > >
> > > Use saved test cases as examples of how to use the function
> >
> > Testing Enhancement

> [tab] Additional Improvements
>
> Platform improvements, security updates, and bug fixes.
>
> 🌍 [**Task Management Localization**](#task-management-localization) - Comprehensive localization support with automatic table grid localization and 51 substitution tags\
> 🔧 [**Platform Enhancements**](#platform-enhancements) - Infrastructure upgrades and security improvements\
> 🐛 [**Bug Fixes**](#bug-fixes) - Resolved issues and stability improvements
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.2.0 adds comprehensive localization support for Task Management, enabling you to customize all user-facing text elements including table columns, filters, and actions. This allows you to deliver Task Management experiences in multiple languages:
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> >
> > > [tab] Key Features
> > >
> > > > [card] Table Grid Localization (Automatic)
> > > >
> > > > Data table components (filters, menus, pagination, data types) are automatically localized based on container app language
> > >
> > > > [card] Substitution Tags (Manual)
> > > >
> > > > Configure 51 system substitution tags in CMS to localize table columns, task actions, and UI elements
> > >
> > > > [card] Multi-language Support
> > > >
> > > > Support for 34 languages including Arabic, Chinese, Japanese, Korean, and European languages
> > >
> > > > [card] Task Action Localization
> > > >
> > > > Localize all task actions, statuses, and workflow-related text elements
> >
> > > [tab] Localization components
> > >
> > > > [accordion] Table Grid Locale Keys
> > > >
> > > > FlowX Task Management uses a comprehensive table grid localization system. These keys are **automatically applied** by FlowX.AI based on your container app language and cover all table functionality:
> > > >
> > > > * **Filters**: Set filters, text filters, number filters, date filters with all operators (equals, contains, starts with, etc.)
> > > >
> > > > * **Menus**: Column menus, context menus, aggregation functions, sorting options
> > > >
> > > > * **Pagination**: Page navigation, page size selectors, row counts
> > > >
> > > > * **Data Types**: Boolean values, dates, numbers with proper formatting
> > > >
> > > > * **Advanced Features**: Pivot mode, charting, column grouping, and row operations
> > > >
> > > > * **ARIA Labels**: Accessibility labels for screen readers and assistive technologies
> > > >
> > > > > [!NOTE]
> > > > >
> > > > > **Automatic Localization**: Table grid locale keys are automatically translated by FlowX.AI based on your container app language. No manual configuration or setup required.
> > >
> > > > [accordion] FlowX substitution tags (51 keys)
> > > >
> > > > Use these substitution tags in CMS to localize custom Task Management interface elements. All tags include English default values:
> > > >
> > > > **Search & Navigation**
> > > >
> > > > * `sys_tm_search` - "Search"
> > > >
> > > > **Table Columns**
> > > >
> > > > * `sys_tm_title` - "Title"
> > > > * `sys_tm_stage` - "Stage"
> > > > * `sys_tm_assignee` - "Assignee"
> > > > * `sys_tm_status` - "Status"
> > > > * `sys_tm_priority` - "Priority"
> > > > * `sys_tm_last_updated` - "Last updated"
> > > >
> > > > **Process States (Status Values)**
> > > >
> > > > * `sys_tm_created` - "Created"
> > > > * `sys_tm_started` - "Started"
> > > > * `sys_tm_finished` - "Finished"
> > > > * `sys_tm_finished_with_error` - "Finished with error"
> > > > * `sys_tm_failed` - "Failed"
> > > > * `sys_tm_expired` - "Expired"
> > > > * `sys_tm_aborted` - "Aborted"
> > > > * `sys_tm_terminated` - "Terminated"
> > > > * `sys_tm_dismissed` - "Dismissed"
> > > > * `sys_tm_on_hold` - "On hold"
> > > >
> > > > **Bulk Actions**
> > > >
> > > > * `sys_tm_assign_to` - "Assign to…"
> > > > * `sys_tm_unassign_all` - "Unassign All"
> > > > * `sys_tm_assign_all_to_me` - "Assign All to me"
> > > > * `sys_tm_hold_all` - "Hold All"
> > > > * `sys_tm_unhold_all` - "Unhold All"
> > > >
> > > > **Task Actions**
> > > >
> > > > * `sys_tm_view_application` - "View Application"
> > > > * `sys_tm_unassign` - "Unassign"
> > > > * `sys_tm_assign_to_myself` - "Assign to myself"
> > > > * `sys_tm_unhold` - "Unhold"
> > > > * `sys_tm_hold` - "Hold"
> > > > * `sys_tm_assign` - "Assign"
> > > > * `sys_tm_execute` - "Execute"
> > > > * `sys_tm_start` - "Start"
> > > >
> > > > **Task Details Sections**
> > > >
> > > > * `sys_tm_assignee_deactivated` - "(Deactivated)"
> > > > * `sys_tm_comments` - "Comments"
> > > > * `sys_tm_write_a_comment` - "Write a comment…"
> > > > * `sys_tm_history` - "History"
> > > >
> > > > **History Events**
> > > >
> > > > * `sys_tm_task_created` - "Task created"
> > > > * `sys_tm_user_created_this_task` - "`${user}` created this task"
> > > > * `sys_tm_started_process_instance_with_id` - "Started Process Instance with ID"
> > > > * `sys_tm_started_process_instance_on_build` - "Started Process Instance on build"
> > > > * `sys_tm_task_ownership_changed_to` - "Task ownership changed to"
> > > > * `sys_tm_task_moved_to` - "Task moved to"
> > > > * `sys_tm_task_status_changed_to` - "Task status changed to"
> > > > * `sys_tm_task_assigned_to` - "Task assigned to"
> > > > * `sys_tm_task_owner_removed` - "Task owner removed"
> > > >
> > > > **User Selection & Search**
> > > >
> > > > * `sys_tm_select_person` - "Select person..."
> > > > * `sys_tm_search_person` - "Search users"
> > > > * `sys_tm_search_term_validation` - "Type at least 4 characters..."
> > > >
> > > > **UI States**
> > > >
> > > > * `sys_tm_loading` - "Loading..."
> > > > * `sys_tm_nothing_found` - "Nothing Found"
> > > >
> > > > **Data Display**
> > > >
> > > > * `sys_tm_in` - "In" (custom filter operator)
> > > >
> > > > * `sys_tm_yes` - "Yes" (boolean value)
> > > >
> > > > * `sys_tm_no` - "No" (boolean value)
> > > >
> > > > > [!WARNING]
> > > > >
> > > > > **\*\*Manual Configuration Required**: These 51 FlowX substitution tags must be configured manually in CMS for each language. They control custom Task Management UI elements outside of the data table.
> >
> > > [tab] Implementation
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization (300+ keys for filters, menus, pagination, data types) based on this setting
> > >
> > > **2. Configure FlowX Substitution Tags in CMS**
> > >
> > > Add translations for all 51 FlowX substitution tags (sys\_tm\_\*) in CMS for each supported language. These control custom Task Management UI elements (task actions, bulk operations, history events, comments)
> > >
> > > **3. Configure Custom Column Names (Optional)**
> > >
> > > If you need custom columns beyond the defaults, use substitution tags for column display names in your Task Management configuration
> > >
> > > **4. Test Localization**
> > >
> > > Verify complete localization:
> > >
> > > * **Table grid elements** (automatic): filters, sorting, pagination, menus should display in container app language
> > >
> > > * **FlowX custom elements** (CMS): task actions, bulk operations, history events, comments should use your CMS translations
> > >
> > > > [!NOTE]
> > > >
> > > > **Simple Setup**: Configure only the 51 FlowX substitution tags in CMS. Table grid localization (300+ keys) is handled automatically by the platform.
> >
> > > [tab] Benefits
> > >
> > > > [card] Global Reach
> > > >
> > > > Deploy Task Management to users worldwide with native language support
> > >
> > > > [card] Consistent Experience
> > > >
> > > > Provide a fully localized experience across all Task Management components
> > >
> > > > [card] Easy Maintenance
> > > >
> > > > Manage translations centrally through CMS substitution tags
> > >
> > > > [card] Professional Quality
> > > >
> > > > Leverage professional translations for data grid components with automatic localization
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> > [card] [Task Management Overview](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
> >
> > Learn about Task Management features and configuration
>
> > [card] [Process Settings](../../../5.1/docs/building-blocks/process/process-definition#integrate-with-task-manager)
> >
> > Configure Task Management integration in process settings
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform Enhancements
> >
> > FlowX.AI 5.2.0 includes platform improvements focused on security, stability, and infrastructure.
> >
> > ## Security & Infrastructure Updates
> >
> > > [card] Vulnerability Fixes
> > >
> > > Update Java libraries and base images to address security vulnerabilities
> >
> > > [card] SpiceDB Upgrade
> > >
> > > Upgrade SpiceDB with new operator version
> >
> > > [card] Dependency Updates
> > >
> > > Update platform dependencies to latest secure versions
> >
> > ## Additional improvements
> >
> > > [card] Permission-based UI
> > >
> > > Add permission-based UI functionality in Reusable UI Templates
> >
> > > [card] Database Query Improvements
> > >
> > > Improve FlowX Database query handling and error messages
> >
> > > [card] System Substitution Tags
> > >
> > > Use system substitution tags in task management texts in CMS
> >
> > > [card] SSE Disconnect Handling
> > >
> > > Handle Server-Sent Events disconnections better to reduce log noise
> >
> > > [card] [Integration Designer Environment Variables](./update-environment-variables-5.2)
> > >
> > > Update environment variables for improved advancing controller with separate picking and processing operations, see details [here](./update-environment-variables-5.2)
> >
> > Platform Updates
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes & stability improvements
> >
> > FlowX.AI 5.2.0 includes bug fixes and stability improvements to improve the overall user experience.
> >
> > ## Notable fixes
> >
> > > [accordion] Fixes
> > >
> > > * **Process Instances Page**: Fix error when opening Runtime process instances page
> > > * **Resource Import**: Fix import requests that use incorrect content type
> > > * **Elasticsearch Updates**: Fix engine errors when updating documents in older indexes
> > > * **Navigation Tree**: Fix navigation tree response for overridden processes
> > > * **Dependency Management**: Fix errors when updating library dependency versions
> >
> > > [accordion] UI/UX fixes
> > >
> > > * **Accessibility**: Fix missing accessibility sections on various components
> > > * **Theme Configuration**: Fix element selection issues in segmented button panel
> > > * **Modal Behavior**: Improve modal focus management and keyboard navigation
> > > * **Select Components**: Fix highlighting and navigation issues in select/multiselect
> > > * **Task Manager**: Fix browser freeze when opening table configuration
> >
> > > [accordion] Renderer fixes
> > >
> > > * **Angular SDK**: Fix keyboard navigation issues with select components and shift+tab behavior
> > > * **React SDK**: Fix option highlighting and keyboard navigation in various components
> > > * **Workflow Display**: Fix rendering issues in Integration Designer workflows
> > > * **Collection Components**: Fix card expansion issues with accordions in navigation areas
> >
> > > [accordion] Backend fixes
> > >
> > > * **Events Gateway**: Improve SSE disconnect handling to reduce error log flooding
> > > * **Database Operations**: Improve error handling and validation for FlowX Database queries
> > > * **Process Navigation**: Fix back button redirects from process definitions
> > > * **Warning Management**: Clean up warnings properly when deleting parent actions

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.2.0](./deployment-guidelines-v5.2).
>
> ### Environment variables updates
>
> > [!NOTE]
> >
> > For detailed information on environment variables, see the [Update environment variables](./update-environment-variables-5.2) section.
>
> ### Coming soon
>
> Additional features currently in development for future releases:
>
> * Extended accessibility support for iOS and Android platforms
> * Additional Python IDE capabilities
> * Enhanced FlowX Database query preview and optimization tools


# Deployment guidelines v5.3.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/deployment-guidelines-v5.3

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **10.29.0** | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 |
| **admin** | **10.26.1** | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 |
| **designer** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **cms-core** | **10.16.0** | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 |
| **scheduler-core** | **10.11.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **events-gateway** | **10.12.1** | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 |
| **notification-plugin** | **10.17.0** | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **document-plugin** | **10.16.0** | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 |
| **task-management-plugin** | **10.18.0** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 |
| **data-search** | **10.10.1** | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 |
| **audit-core** | **10.15.1** | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 |
| **advancing-controller** | **10.11.0** | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 |
| **integration-designer** | **10.24.0** | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 |
| **application-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **runtime-manager** | **10.24.0** | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 |
| **data-sync** | **10.14.1** | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 |
| **authorization-system** | **10.18.1** | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 | - | - | - |
| **nosql-db-runner** | **10.10.1** | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/angular-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/react-ui-toolkit** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-sdk** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **@flowx/core-theme** | **10.32.4** | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 |
| **iOS renderer** | **10.1.0** | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 |
| **Android renderer** | **10.1.0** | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 |

### Plugins

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.1** | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 |
| **di-platform** | **10.2.5** | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 |
| **ai-platform-ai-developer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-connected-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agents** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-conversations** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-models** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-tenants** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-planner** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-analyst** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-ai-designer** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-agent-builder** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |
| **ai-platform-binaries** | **10.1.3** | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.3.0 | Keycloak | 26+ |
| 5.3.0 | Kafka | 3.8 - 3.9 |
| 5.3.0 | PostgreSQL | 16 - 17 |
| 5.3.0 | Oracle Database | 21c, 23ai |
| 5.3.0 | MongoDB | 7 - 8 |
| 5.3.0 | Redis | 7.4 - 8.0 |
| 5.3.0 | Elasticsearch | 8 |
| 5.3.0 | Angular (Web SDK) | 19.2 |
| 5.3.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.3.0

### Key features and updates

> [card] UI Flows
>
> Build multi-platform applications with reusable UI components across web, iOS, and Android

> [card] UI Events
>
> Real-time user interaction handling with event-driven UI components

> [card] Workflow Data Models
>
> Workflow-level data models with input/output parameters and process-to-workflow data mapping

> [card] Mobile Accessibility
>
> WCAG 2.1 accessibility compliance extended to iOS and Android platforms

> [card] Custom Component Enhancements
>
> Standardized custom component integration across all platforms

> [card] SaaS Capabilities
>
> Multi-tenant SaaS capabilities with organization management

## Upgrading from v5.2.0

### Breaking changes

> [!WARNING]
>
> **FlowX Engine Configuration Changes**: The partitioning and archiving configuration structure has been reorganized. If you have enabled data partitioning, you **must** update your configuration files before or immediately after upgrading.

> [card] [Complete migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
>
> See the detailed migration guide with step-by-step instructions, configuration examples, and troubleshooting

### Key changes

* **UI Flows**: New feature for building multi-platform reusable UI components
* **Workflow Data Models**: Enhanced integration between processes and workflows with structured data models
* **Mobile Accessibility**: iOS and Android renderers now support WCAG 2.1 accessibility standards
* **Configuration Structure**: Breaking change in FlowX Engine partitioning/archiving configuration (see preceding section)

### Environment variables updates

> [!NOTE]
>
> For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.

### Compatibility

* **Breaking Changes**: FlowX Engine partitioning/archiving configuration structure has changed (action required if using partitioning)
* **Feature Additions**: UI Flows, UI Events, and Workflow Data Models are new features with no breaking changes
* **Renderer Updates**: Web and mobile SDKs include new features with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/migration-overview

Migration guide for upgrading from FlowX.AI v5.2.0 to v5.3.0

> [!NOTE]
>
> FlowX.AI v5.3.0 is an incremental update from v5.2.0 with one breaking change related to FlowX Engine configuration structure.

## What's changing

FlowX.AI v5.3.0 introduces a breaking change to the FlowX Engine partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings have been reorganized under `partitioning.archiving`.

## Who is affected

> [!WARNING]
>
> This breaking change **only affects** deployments that have:
>
> * Enabled data partitioning in FlowX Engine (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings (`SCHEDULER_DATAPARTITIONING_ENABLED=true`)
>
> If you have not enabled these features, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

## Migration process

**1. Review configuration changes**

Understand the new configuration structure and identify which settings need to be updated in your deployment

**2. Update configuration files**

Update your FlowX Engine configuration files (YAML or environment variables) following the migration steps

**3. Deploy and verify**

Deploy the updated configuration and verify that partitioning and archiving continue to work correctly

## Key changes summary

### Configuration structure

**What's removed:**

* `scheduler.dataPartitioning` section with `enabled` and `cronExpression` settings

**What's added:**

* `partitioning.archiving` subsection containing all archiving-related settings

**What's moved:**

* `retention-intervals` moved from `partitioning` to `partitioning.archiving`
* `detached-partition-compression` moved to `partitioning.archiving`
* `moved-data-batch-size` moved to `partitioning.archiving`
* `cronExpression` moved from `scheduler.dataPartitioning` to `partitioning.archiving`

### Environment variables

5 environment variables have been renamed to reflect the new structure:

| Old Variable | New Variable |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` |

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility**: The old configuration structure is not supported in v5.3.0 and causes FlowX Engine startup errors.
>
> You must update your configuration before or immediately after upgrading to v5.3.0.

## Rollback support

If you need to rollback from v5.3.0 to v5.2.x:

1. Revert your configuration files to the previous structure
2. Restore environment variables to their previous names
3. Downgrade the FlowX Engine container/pod to the previous version

> [!NOTE]
>
> Database schema changes are forward-compatible. Ensure you have database backups before any upgrade.

> [!NOTE]
>
> This is a configuration-only change. No code changes, data migration, or schema updates are required.

## Next steps

## Additional resources

> [card] [Partitioning & Archiving Setup](/5.1/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving)
>
> Complete guide to FlowX Engine partitioning and archiving

> [card] [Deployment Guidelines v5.3.0](../deployment-guidelines-v5.3)
>
> Component versions and deployment instructions

> [card] [Release Notes v5.3.0](../v5.3.0-december-2025)
>
> Full release notes for v5.3.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/migrating-from-v5.2-to-v5.3/update-environment-variables-5.3

Update environment variables for all existing FlowX.AI services

## FlowX Engine

### Partitioning and archiving configuration restructure

> [!NOTE]
>
> FlowX.AI v5.3.0 reorganizes the partitioning and archiving configuration structure. The `scheduler.dataPartitioning` section has been removed, and archiving settings are now under `partitioning.archiving`.

#### Variables to remove

If you are using environment variables to override FlowX Engine configuration, remove these variables:

| Remove This Variable | Reason |
| - | - |
| `SCHEDULER_DATAPARTITIONING_ENABLED` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` |
| `SCHEDULER_DATAPARTITIONING_CRONEXPRESSION` | Replaced by `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` |

#### Variables to replace

| Old Variable Name | New Variable Name | Default Value | Description |
| - | - | - | - |
| `FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS` | `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of partition intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION` | `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression level for archived partitions (Oracle only): `OFF`, `BASIC`, `ADVANCED` |
| `FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE` | `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for moving data during archiving (PostgreSQL only) |

#### New variables structure

The archiving configuration is now nested under `partitioning.archiving`:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ENABLED` | `false` | Turn on or off data partitioning |
| `FLOWX_DATA_PARTITIONING_INTERVAL` | `MONTH` | Partition interval: `DAY`, `WEEK`, `MONTH` |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED` | `false` | Turn on or off automatic archiving of old partitions |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS` | `3` | Number of intervals to retain before archiving |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION` | `0 0 1 * * ?` | Schedule expression for archiving operations (default: daily at 1:00 AM) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION` | `OFF` | Compression for archived partitions (Oracle only) |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE` | `5000` | Batch size for data movement (PostgreSQL only) |

> [!NOTE]
>
> **Configuration structure changes:**
>
> * **Removed**: `scheduler.dataPartitioning` section
> * **Added**: `partitioning.archiving` subsection with all archiving-related settings
> * **Unchanged**: Core partitioning settings (`enabled`, `interval`) remain at `partitioning` level
> * **Moved**: Archiving-specific settings (`retention-intervals`, `cronExpression`, `detached-partition-compression`, `moved-data-batch-size`) are now under `partitioning.archiving`

> [!WARNING]
>
> **Action required if using partitioning:**
>
> If you have enabled data partitioning in FlowX Engine, you **must** update your configuration:
>
> 1. **YAML configuration**: Update your `application.yml` to follow the new structure (see [Deployment Guidelines](../deployment-guidelines-v5.3#breaking-changes))
> 2. **Environment variables**: Update variable names as shown in the tables above
> 3. **Deployment order**: Update configuration before or immediately after upgrading to v5.3.0

#### Configuration examples

> [tab] Environment Variables (Before)
>
> ```bash theme={"dark"}
> # Old structure (v5.2 and earlier)
> SCHEDULER_DATAPARTITIONING_ENABLED=true
> SCHEDULER_DATAPARTITIONING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_RETENTION_INTERVALS=3
> FLOWX_DATA_PARTITIONING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [tab] Environment Variables (After)
>
> ```bash theme={"dark"}
> # New structure (v5.3.0)
> FLOWX_DATA_PARTITIONING_ENABLED=true
> FLOWX_DATA_PARTITIONING_INTERVAL=MONTH
> FLOWX_DATA_PARTITIONING_ARCHIVING_ENABLED=true
> FLOWX_DATA_PARTITIONING_ARCHIVING_RETENTIONINTERVALS=3
> FLOWX_DATA_PARTITIONING_ARCHIVING_CRONEXPRESSION=0 0 1 * * ?
> FLOWX_DATA_PARTITIONING_ARCHIVING_DETACHED_PARTITION_COMPRESSION=OFF
> FLOWX_DATA_PARTITIONING_ARCHIVING_MOVED_DATA_BATCH_SIZE=5000
> ```

> [!NOTE]
>
> **Impact assessment:**
>
> This change only affects deployments that have:
>
> * Enabled data partitioning (`FLOWX_DATA_PARTITIONING_ENABLED=true`)
> * Configured archiving settings
>
> If partitioning is disabled, you should still update your configuration files for future compatibility, but there is no immediate operational impact.

### New optional variables

| Variable | Default Value | Description |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Falls back to `KAFKA_TOPIC_PATTERN` if not set | Dedicated topic pattern for FlowX connectors, separate from other platform components like document-plugin, data-search, and cms-core |

> [!NOTE]
>
> The `KAFKA_TOPIC_CONNECTOR_PATTERN` variable allows you to configure a custom Kafka topic pattern specifically for FlowX connectors without affecting other platform components.

> [card] [Complete migration guide](migration-overview)
>
> See the Deployment Guidelines for complete configuration examples, step-by-step migration instructions, and troubleshooting guidance.


# FlowX.AI 5.3.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.3.0-december-2025/v5.3.0-december-2025

UI Flows for multi-platform app building, UI Events for real-time interactions, enhanced custom component integration, and mobile accessibility improvements.

**What's new?**

> [tab] App builder & reusability
>
> Build multi-platform applications faster with UI Flows, enhance real-time interactions with UI Events, and integrate custom components across all platforms.
>
> 📱 [**UI Flows**](#ui-flows) - Build multi-platform applications with reusable UI components across web, iOS, and Android\
> ⚡  [**UI Events**](#ui-events) - Real-time user interaction handling with event-driven UI components\
> 🧩 [**Custom Component Enhancements**](#custom-component-enhancements) - Enhanced integration for custom components with standardized data mapping\
> 📤 [**File Upload Improvements**](#file-upload-improvements) - Enhanced file upload experience with better loading states and user feedback\
> ♿ [**Mobile Accessibility**](#mobile-accessibility) - WCAG 2.1 accessibility compliance for iOS and Android platforms\
> 🏢 [**Cross Workspace Projects**](#cross-workspace-projects) - Share projects across multiple workspaces for flexible environment testing\
> 🎯 [**Collection & Table Actions**](#collection-and-table-actions) - Execute actions from collections and tables in UI Flows
>
> ### **UI flows**
>
> > [card] UI flows
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Flows, a powerful new capability that enables you to build reusable, multi-platform user interfaces that work across web (Angular/React), iOS, and Android applications. UI Flows separate UI definitions from process logic, enabling better reusability and faster application development without the overhead of full BPMN processes.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flows revolutionize how you build applications by allowing you to create a UI once and deploy it across all platforms, dramatically reducing development time and ensuring consistent user experiences.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Unnecessary process complexity
> > > >
> > > > Some use cases do not need a mapping of the business case in BPMN and the complexity and overhead that a FlowX process entails
> > >
> > > > [card] Subprocess overhead
> > > >
> > > > Unnecessary subprocess layers inside processes added complexity for simple UI scenarios
> > >
> > > > [card] Tight UI-process coupling
> > > >
> > > > UI definitions were tightly coupled to process logic, reducing reusability and increasing maintenance
> > >
> > > > [card] Platform-specific development
> > > >
> > > > Building the same UI for multiple platforms required separate implementations for each platform
> >
> > > [tab] Key Features
> > >
> > > > [card] UI Flows as project resources
> > > >
> > > > UI Flows are managed as independent project resources, separate from process definitions
> > >
> > > > [card] Navigation areas management
> > > >
> > > > Manage Navigation Areas inside UI Flows Designer for structured navigation and layout
> > >
> > > > [card] Start process UI action
> > > >
> > > > Launch FlowX processes directly from UI Flows, bridging UI and process execution
> > >
> > > > [card] Navigate to UI action
> > > >
> > > > Setup navigation to Nav areas or Container elements through scroll for seamless UX
> > >
> > > > [card] Task Manager component
> > > >
> > > > Embed Task Manager as a UI Component in UI Flows for task management capabilities
> > >
> > > > [card] Multi-platform support
> > > >
> > > > Create UI once and deploy to web (Angular/React), iOS, and Android with platform-specific configurations
> > >
> > > > [card] Import/export
> > > >
> > > > Export UI Flows as portable packages and import them across environments and applications
> > >
> > > > [card] Platform selection
> > > >
> > > > Configure platform-specific behaviors and overrides for web, iOS, and Android in the UI Flows designer
> > >
> > > > [card] Home page support
> > > >
> > > > Create UI Flows with dedicated home pages and home navigation icons for better UX
> >
> > > [tab] How It Works
> > >
> > > **1. Create UI flow**
> > >
> > > Create a UI Flow as a project resource in FlowX Designer, separate from process definitions
> > >
> > > **2. Design navigation**
> > >
> > > Manage Navigation Areas inside UI Flows Designer, defining pages and navigation structure
> > >
> > > **3. Add components**
> > >
> > > Add UI components including Task Manager, forms, custom components, and other UI elements
> > >
> > > **4. Configure actions**
> > >
> > > Setup UI Actions like Start Process (to launch processes) and Navigate To (for Nav areas or container scrolling)
> > >
> > > **5. Configure platforms**
> > >
> > > Set platform-specific configurations using the platform selection subheader (Web, iOS, Android)
> > >
> > > **6. Set home page**
> > >
> > > Designate a page as the home page with automatic home icon navigation support
> > >
> > > **7. Export & reuse**
> > >
> > > Export your UI Flow and import it into other applications or environments for maximum reusability
> >
> > > [tab] Benefits
> > >
> > > > [card] Reduced complexity
> > > >
> > > > Build UIs without the overhead of BPMN processes for use cases that don't require business process mapping
> > >
> > > > [card] Faster development
> > > >
> > > > Build UI once instead of creating separate interfaces for each platform
> > >
> > > > [card] Flexible architecture
> > > >
> > > > Eliminate unnecessary subprocess layers - use UI Flows for simple scenarios and processes for complex business logic
> > >
> > > > [card] Consistent UX
> > > >
> > > > Ensure identical user experiences across web, iOS, and Android applications
> > >
> > > > [card] Reusability
> > > >
> > > > Share UI Flows across multiple applications and projects
> > >
> > > > [card] Process integration
> > > >
> > > > Launch processes from UI Flows when needed, maintaining clean separation of concerns
> > >
> > > > [card] Maintainability
> > > >
> > > > Update UI in one place and propagate changes across all platforms
> > >
> > > > [card] Enhanced navigation
> > > >
> > > > Rich navigation capabilities with Nav areas, container scrolling, and Task Manager integration
> >
> > > [tab] Use Cases
> > >
> > > **When to Use UI Flows vs Processes:**
> > >
> > > **Use UI Flows for:**
> > >
> > > * **Information Display**: Dashboards, reports, and static content that doesn't require process orchestration
> > > * **Task Management**: Task lists and task management interfaces with embedded Task Manager component
> > > * **Navigation Shells**: Application navigation structures and home pages
> > > * **Form Collections**: Data entry forms that start processes but don't need their own process context
> > > * **Multi-Platform Apps**: Applications that need consistent UI across web and mobile platforms
> > >
> > > **Use Processes for:**
> > >
> > > * **Business Logic**: Complex workflows with business rules, approvals, and integrations
> > > * **State Management**: Applications requiring process state tracking and persistence
> > > * **Orchestration**: Multi-step operations with decision points and parallel execution
> > >
> > > **Combine Both:**
> > >
> > > Create UI Flows as the main application shell and use Start Process UI Actions to launch business processes when needed, keeping your architecture clean and maintainable.
> >
> > > [card] [UI Flows Documentation](/5.9/docs/building-blocks/ui-flows)
> > >
> > > Complete guide to creating and configuring UI Flows, including navigation management, UI actions, and platform considerations.
> >
> > Major Feature
>
> ***
>
> ### **UI events**
>
> > [card] UI events
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces UI Events, enabling real-time interaction handling directly within Reusable UI Templates. UI Events allow you to capture user interactions like button clicks, form changes, or custom events and respond immediately without process execution, providing responsive and dynamic user experiences.
> >
> > > [tab] Key Features
> > >
> > > > [card] Event configuration
> > > >
> > > > Configure UI Events in UI Designer with custom event types and handling logic
> > >
> > > > [card] Cross-platform support
> > > >
> > > > UI Events work consistently across Angular, React, iOS, and Android renderers
> > >
> > > > [card] Runtime mapping
> > > >
> > > > UI Event results are mapped automatically in Reusable UI Template instances at runtime
> > >
> > > > [card] Design-time testing
> > > >
> > > > Test UI Events directly in UI Designer before deploying to runtime
> >
> > > [tab] Use Cases
> > >
> > > > [card] Form validation
> > > >
> > > > Validate form inputs in real-time as users type, providing immediate feedback
> > >
> > > > [card] Dynamic UI updates
> > > >
> > > > Show/hide fields, update options, or change UI state based on user interactions
> > >
> > > > [card] Client-side logic
> > > >
> > > > Execute lightweight client-side logic without triggering backend processes
> > >
> > > > [card] Responsive interactions
> > > >
> > > > Create highly responsive UI behaviors like autocomplete, live search, or conditional displays
> >
> > > [tab] Benefits
> > >
> > > **1. Performance**
> > >
> > > Handle UI interactions instantly without waiting for backend process execution
> > >
> > > **2. User experience**
> > >
> > > Provide immediate visual feedback and responsive interactions
> > >
> > > **3. Reduced complexity**
> > >
> > > Simplify process logic by handling UI-specific interactions at the component level
> >
> > UX Enhancement
>
> ***
>
> ### **Custom component enhancements**
>
> > [card] Custom component enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 standardizes custom component integration across all platforms (Angular, React, iOS, Android) with unified data mapping for input keys, data binding, save operations, and action handling. This provides a consistent developer experience when building custom components.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified data mapping
> > > >
> > > > Standard data, saveData, and action body mapping across all platforms
> > >
> > > > [card] Input key mapping
> > > >
> > > > Consistent input key handling for passing configuration and data to custom components
> > >
> > > > [card] Platform parity
> > > >
> > > > Identical custom component APIs across Angular, React, iOS, and Android
> > >
> > > > [card] Action integration
> > > >
> > > > Integration with FlowX actions for triggering backend operations
> >
> > > [tab] Benefits
> > >
> > > **1. Developer productivity**
> > >
> > > Build custom components once with knowledge that applies across all platforms
> > >
> > > **2. Code reusability**
> > >
> > > Share component logic and patterns across web and mobile implementations
> > >
> > > **3. Consistency**
> > >
> > > Ensure consistent behavior and data handling across all platforms
> >
> > Developer Experience
>
> ***
>
> ### **File upload improvements**
>
> > [card] File upload improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the file upload experience across all platforms with improved loading states, better user feedback, and more flexible configuration options. These improvements provide clearer status communication during file upload operations.
> >
> > > [tab] Key Features
> > >
> > > > [card] Enhanced loading behavior
> > > >
> > > > Configure loading behavior with optional overlay loader and custom loading messages
> > >
> > > > [card] Toast notifications
> > > >
> > > > Success and error messages displayed as toasts with customizable messages
> > >
> > > > [card] Dynamic messages
> > > >
> > > > Display dynamic key values in toast and loading messages for context-aware feedback
> > >
> > > > [card] Generic loader design
> > > >
> > > > Updated loader designs across Angular, React, iOS, and Android for consistent theming
> >
> > > [tab] Configuration
> > >
> > > **Loading Behavior Options:**
> > >
> > > * **NONE**: No loading overlay displayed during upload
> > > * **OVERLAY**: Full-screen overlay with spinner and optional loading message
> > >
> > > **Toast Notifications:**
> > >
> > > * **Success Toast**: Toggle to show success message when upload completes (auto-dismiss after 3-5 seconds)
> > > * **Error Toast**: Toggle to show error message when upload fails (auto-dismiss after 3-5 seconds)
> > > * **Custom Messages**: Configure success and error messages with dynamic substitutions
> > >
> > > **Theming Support:**
> > >
> > > * Apply custom themes to loaders and toast messages
> > > * Configure colors, sizes, and styling to match your brand
> > > * Consistent visual language across platforms
> >
> > UX Enhancement
>
> ***
>
> ### **Mobile accessibility**
>
> > [card] Mobile accessibility
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 extends WCAG 2.1 accessibility compliance to iOS and Android platforms, allowing you to configure accessibility properties directly from UI Designer and ensuring your mobile applications are accessible to all users.
> >
> > > [tab] Key Features
> > >
> > > > [card] iOS accessibility
> > > >
> > > > Configure labels, hints, traits, and accessibility properties for iOS components
> > >
> > > > [card] Android accessibility
> > > >
> > > > Set content descriptions and accessibility properties for Android components
> > >
> > > > [card] Designer integration
> > > >
> > > > Configure all accessibility properties from UI Designer without code changes
> > >
> > > > [card] Platform-specific options
> > > >
> > > > Set platform-specific accessibility configurations for optimal native experience
> >
> > > [tab] Benefits
> > >
> > > > [card] Inclusive mobile apps
> > > >
> > > > Make your mobile applications accessible to users with disabilities
> > >
> > > > [card] Regulatory compliance
> > > >
> > > > Meet mobile accessibility requirements for government, healthcare, and financial sectors
> > >
> > > > [card] Better UX
> > > >
> > > > Accessibility improvements benefit all users, not just those using assistive technologies
> > >
> > > > [card] Unified configuration
> > > >
> > > > Configure accessibility for all platforms from a single Designer interface
> >
> > Accessibility
>
> ***
>
> ### **Cross workspace projects**
>
> > [card] Cross workspace projects
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 removes the restriction that prevented importing the same project into multiple workspaces within the same environment. This enables organizations to use workspaces to represent different upper environments (UAT, Staging) for testing and development.
> > >
> > > > [!NOTE]
> > > >
> > > > A single project (identified by its UUID) can now exist independently across workspaces, each with its own lifecycle: separate active policies, configurations, and access controls.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Environment testing restrictions
> > > >
> > > > Organizations could not use workspaces on the same FlowX deployment to represent different upper environments for testing (e.g. UAT, Staging)
> > >
> > > > [card] Operational costs
> > > >
> > > > This feature is intended to allow organizations to use workspace functionality to emulate different environments and reduce operational costs.
> >
> > > [tab] Solution
> > >
> > > **What Changed:**
> > >
> > > **1. Restriction removed**
> > >
> > > The system now allows importing the same project (identified by UUID) into multiple workspaces within the same environment
> > >
> > > **2. Independent lifecycles**
> > >
> > > Each project instance in different workspaces maintains its own independent lifecycle with separate active policies, configurations, and access controls
> > >
> > > **3. Workspace isolation**
> > >
> > > Changes in one workspace do not affect the same project in other workspaces, ensuring proper isolation
> >
> > > [tab] How It Works
> > >
> > > **Import Behavior:**
> > >
> > > | Aspect | Behavior |
> > > | - | - |
> > > | **Import** | Import a project build (and optionally a version) into a different workspace on the same environment |
> > > | **Active Policy** | The imported build is automatically set as the active policy, regardless of what was active in the original workspace |
> > > | **User Access** | Workspace users must be granted appropriate project rights (e.g., project viewer) to interact with the imported project |
> > > | **Process Instances** | Workspace-specific; imported projects start with no instances until processes run in the new workspace |
> > > | **Database** | Projects across workspaces on the same environment share the same database |
> > > | **No Impact on Original** | Import does not affect the original project's settings, policies, information, or process instances |
> > >
> > > > [!WARNING]
> > > >
> > > > Only the build itself is transferred during cross-workspace import. Configuration and access controls are defined separately in each workspace.
> >
> > > [tab] Benefits
> > >
> > > > [card] Flexible testing environments
> > > >
> > > > Use workspaces to represent UAT, Staging, and other test environments on the same deployment
> > >
> > > > [card] Reduced costs
> > > >
> > > > Eliminate the need for additional deployments and DevOps resources for environment management
> > >
> > > > [card] Better organization
> > > >
> > > > Organize projects and environments more efficiently with workspace-based separation
> > >
> > > > [card] Independent control
> > > >
> > > > Maintain separate policies and configurations for each workspace while using the same project
> > >
> > > > [card] Simplified operations
> > > >
> > > > Streamline deployment and environment management workflows
> > >
> > > > [card] Faster environment setup
> > > >
> > > > Quickly create new test environments by importing existing projects into new workspaces
> >
> > > [tab] Use Cases
> > >
> > > **Example Scenarios:**
> > >
> > > 1. **Multi-Environment Testing**: Import the same project into UAT and Staging workspaces, each with different test data and configurations
> > >
> > > 2. **Development Lifecycle**: Maintain development, integration, and pre-production environments as separate workspaces with the same project
> > >
> > > 3. **Parallel Testing**: Run multiple test scenarios simultaneously by creating separate workspaces for each testing team
> > >
> > > 4. **Isolated Training Environments**: Create dedicated workspaces for training and demos while keeping production separate
> >
> > > [card] [Workspaces Documentation](/5.1/docs/projects/workspaces#cross-workspace-project-import)
> > >
> > > Complete guide to cross-workspace project import, including import behavior and best practices.
> >
> > Reusability Enhancement
>
> ***
>
> ### **Collection and table actions**
>
> > [card] Collection and table actions
> >
> > FlowX.AI 5.3 enables executing actions directly from collection and table rows within UI Flows across Angular and React platforms, providing contextual user interactions within data-driven UI Flow components.
> >
> > > [card] Row-level actions
> > >
> > > Configure and trigger actions with row context for edit, delete, or start process operations in UI Flows
> >
> > > [card] Cross-platform support
> > >
> > > Works in both Angular and React web renderers for UI Flows
> >
> > UI Flows
>
> ***

> [tab] Integration & data
>
> Enhanced workflow integration, data model management, and backend performance improvements.
>
> 🔄 [**Data mappers for workflow integration**](#data-mappers-for-workflow-integration) - Data mappers for workflow integration\
> 🗄️ [**Workflow data model**](#workflow-data-model) - New CRUD endpoints and runtime data model access\
> 🤖 [**MCP Integration**](#mcp-integration) - Connect AI agents with external tools and services through Model Context Protocol servers\
> 🤖 [**Custom Agent Nodes**](#custom-agent-nodes) - Custom Agent nodes for AI agents to use external tools and services
> 📚 [**Knowledge Base**](#knowledge-base) - Create and manage Knowledge Bases for AI agents with document ingestion and semantic search\
> 🔧 [**Update process variables**](#update-process-variables) - Operations teams can modify process variables on active instances to resolve production issues\
> 🔍 [**Token view improvements**](#token-view-improvements) - Enhanced token hierarchy visibility with horizontal scrolling, frozen columns, and context-aware columns\
> 🛡️ [**Access management enhancements**](#access-management-enhancements) - New operations editor role and granular workspace permissions\
> ⚡ [**Performance & stability**](#performance-and-stability) - Backend optimizations, caching improvements, and infrastructure updates\
> 🔀 [**Exclusive Gateways**](#exclusive-gateways) - Expression testing and validation improvements
>
> ### **Data mappers for workflow integration**
>
> > [card] Data mappers for workflow integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces data mappers that enable integration between processes and Integration Designer workflows. Similar to Process Definitions, you can now define structured data models at the workflow level with input and output parameters, ensuring consistent data lineage across your integration architecture.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Workflow%20-%20Data%20Model.png)
> > >
> > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/process-workflow.png)
> > >
> > > Map data bidirectionally between processes and workflows using data mappers
> > >
> > > > [!NOTE]
> > > >
> > > > Workflow Data Models provide the same structured data management capabilities as Process Data Models, enabling declarative data mapping between workflows and processes with full type safety and validation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow data model
> > > >
> > > > Define data models at the workflow level with input and output parameters, similar to Process Definitions
> > >
> > > > [card] Input parameter management
> > > >
> > > > Input parameters automatically pre-fill Start Nodes with structured data from the workflow data model
> > >
> > > > [card] Data parameters
> > > >
> > > > Use data parameters to define input and output data subsets for workflow operations
> > >
> > > > [card] Process ↔ workflow mapping
> > > >
> > > > Create data mappers on nodes to receive outputs from workflows and map data bidirectionally
> > >
> > > > [card] Generic CRUD endpoints
> > > >
> > > > Manage data models, entities, attributes, and data parameters programmatically via REST APIs
> > >
> > > > [card] Unique node validation
> > > >
> > > > Automatic node name uniqueness validation within workflow definitions to ensure clear data lineage
> >
> > > [tab] How It Works
> > >
> > > **1. Define workflow data model**
> > >
> > > Create a data model for your workflow with entities and attributes, similar to Process Data Models. Define which parameters are inputs and outputs
> > >
> > > **2. Configure input parameters**
> > >
> > > Input parameters automatically pre-fill the Start Node when you open the workflow diagram or test at runtime. No manual JSON editing required
> > >
> > > **3. Map process to workflow**
> > >
> > > When invoking a workflow from a process, create data mappers to map process data to workflow input parameters
> > >
> > > **4. Map workflow to process**
> > >
> > > Configure output mappings on nodes to receive workflow results and map them back to process data
> >
> > > [tab] Data Model Management
> > >
> > > **New API Capabilities:**
> > >
> > > * **Data Model CRUD**: Create, read, update, and delete workflow data models
> > > * **Entity Management**: Add, modify, and remove entities within data models
> > > * **Attribute Management**: Define and manage attributes with types and validation rules
> > > * **Data Parameters Operations**: Create input and output data parameters for workflows
> > > * **Usage Tracking**: Query references and usages for attributes and entities
> > > * **Import/Export**: Export and import complete data models across environments
> > >
> > > **Technical Implementation:**
> > >
> > > * Centralized data model library for common classes and interfaces
> > > * Generic endpoints for data model and data parameters manipulation
> > > * Integration Designer communicates with Admin service for data model operations
> > > * Automatic input body computation based on data model input parameters
> > > * Runtime workflow start data endpoint for testing and execution
> >
> > > [tab] Limitations & Compatibility
> > >
> > > **Current Limitations:**
> > >
> > > * **Start Subworkflow Node**: Works as-is without data model integration in this release
> > > * **Endpoint Schemas**: Imported Swagger schemas are not yet integrated with workflow data models (planned for future release)
> > > * **Database Schemas**: Database operation schemas are not mapped to workflow variables yet (planned for future release)
> > >
> > > **Backwards Compatibility:**
> > >
> > > * Existing workflows continue to work without changes
> > > * End nodes from existing workflows can be renamed manually to align with output parameters
> > > * No breaking changes to current workflow execution
> > >
> > > **Node Naming:**
> > >
> > > * Node names must be unique within a workflow definition
> > > * System automatically validates uniqueness when renaming nodes
> > > * If duplicate names exist, an index is incremented (e.g., "Transform", "Transform\_2")
> >
> > > [tab] Benefits
> > >
> > > > [card] Consistent data lineage
> > > >
> > > > Ensure data consistency across processes and workflows with structured data models
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Input parameters automatically pre-fill Start Nodes - no manual JSON editing
> > >
> > > > [card] Type safety
> > > >
> > > > Define data types and validation rules at the workflow level for runtime safety
> > >
> > > > [card] Reusability
> > > >
> > > > Create reusable workflows with clear input/output contracts that can be invoked from multiple processes
> > >
> > > > [card] Better testing
> > > >
> > > > Test workflows with structured input data based on the data model
> > >
> > > > [card] Clear interfaces
> > > >
> > > > Workflow data models document the expected inputs and outputs for each workflow
> >
> > > [card] [Workflow Data Models Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> > >
> > > Complete guide to creating workflow data models, input/output parameters, process integration, and API reference.
> >
> > Integration Designer
>
> ***
>
> ### **Workflow data model**
>
> > [card] Workflow data model
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 adds comprehensive workflow data model management capabilities with new CRUD endpoints and runtime access to data model paths. This enables dynamic data model operations and better runtime introspection.
> >
> > > [tab] Key Features
> > >
> > > > [card] CRUD endpoints
> > > >
> > > > Create, read, update, and delete workflow data models programmatically via REST APIs
> > >
> > > > [card] Data model paths
> > > >
> > > > Runtime endpoint for retrieving workflow data model paths and structure information
> > >
> > > > [card] RUT instance mappings
> > > >
> > > > Enhanced /status and /details endpoints with mappings per workflow instance
> > >
> > > > [card] Runtime caching
> > > >
> > > > Improved caching for reusable templates to reduce latency and improve performance
> >
> > > [tab] Use Cases
> > >
> > > > [card] Dynamic forms
> > > >
> > > > Build dynamic forms based on data model structure at runtime
> > >
> > > > [card] Data migration
> > > >
> > > > Automate data model synchronization across environments
> > >
> > > > [card] Documentation
> > > >
> > > > Generate data model documentation automatically from API responses
> > >
> > > > [card] Validation
> > > >
> > > > Implement runtime validation based on data model definitions
> >
> > API Enhancement
>
> ***
>
> ### **MCP integration**
>
> > [card] MCP integration
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Model Context Protocol (MCP) integration, enabling AI agents to connect with external MCP servers and use their tools within Custom Agent nodes. MCP provides a standardized protocol for AI agents to access external tools, databases, APIs, and services.
> > >
> > > > [!NOTE]
> > > >
> > > > MCP integration extends AI agent capabilities by providing access to external tools through a standardized protocol. Configure MCP servers as data sources in Integration Designer and use their tools in workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] MCP data sources
> > > >
> > > > Add MCP servers as data sources in Integration Designer with base URL and authentication configuration
> > >
> > > > [card] Tool management
> > > >
> > > > View, enable, and turn off specific tools exposed by MCP servers directly from Integration Designer
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Select MCP servers in Custom Agent nodes to make their tools available to AI agents during workflow execution
> > >
> > > > [card] Authentication support
> > > >
> > > > Support for no authentication and OAuth 2.0 service account authentication methods
> > >
> > > > [card] Tool discovery
> > > >
> > > > Automatic tool discovery from MCP servers with schema information for inputs and outputs
> > >
> > > > [card] Execution monitoring
> > > >
> > > > Track tool usage and execution details in console logs for debugging and monitoring
> >
> > > [tab] How It Works
> > >
> > > **1. Add MCP server**
> > >
> > > Configure an MCP server as a data source in Integration Designer with base URL and authentication details
> > >
> > > **2. Authenticate connection**
> > >
> > > Set up authentication using no authentication (for development) or OAuth 2.0 service account (for production)
> > >
> > > **3. Discover tools**
> > >
> > > View available tools exposed by the MCP server with their input/output schemas
> > >
> > > **4. Enable tools**
> > >
> > > Enable or turn off specific tools based on your workflow requirements
> > >
> > > **5. Configure custom agent**
> > >
> > > Add a Custom Agent node to your workflow and select which MCP servers the agent can access
> > >
> > > **6. Execute workflow**
> > >
> > > AI agents can now use MCP tools during workflow execution to interact with external systems
> > >
> > > **7. Monitor execution**
> > >
> > > View tool usage and execution details in console logs for debugging and performance tracking
> >
> > > [tab] Authentication
> > >
> > > **Supported Authentication Methods:**
> > >
> > > **None**
> > >
> > > * No authentication required
> > > * Use for public MCP servers or development environments
> > > * Quick setup for testing and prototyping
> > >
> > > **Service Account (OAuth 2.0)**
> > >
> > > * OAuth 2.0 service account authentication
> > > * Required configuration:
> > >   * **Client ID**: OAuth client identifier
> > >   * **Client Secret**: OAuth client secret
> > >   * **Identity Provider URL**: Authorization server endpoint
> > > * Use for production environments
> > > * Secure access to MCP servers
> >
> > > [tab] Use Cases
> > >
> > > > [card] External API integration
> > > >
> > > > Connect AI agents to external APIs and services for data retrieval and action execution
> > >
> > > > [card] Database operations
> > > >
> > > > Query databases and perform data operations through MCP tools within AI workflows
> > >
> > > > [card] Custom business logic
> > > >
> > > > Expose custom business logic as MCP tools for AI agents to execute
> > >
> > > > [card] Multi-system orchestration
> > > >
> > > > Use multiple MCP servers in a single Custom Agent node to orchestrate operations across systems
> >
> > > [tab] Benefits
> > >
> > > > [card] Standardized integration
> > > >
> > > > Use a standardized protocol for AI agent tool integration across different systems
> > >
> > > > [card] Extended capabilities
> > > >
> > > > Extend AI agent capabilities with external tools without custom code
> > >
> > > > [card] Flexible tool management
> > > >
> > > > Enable or turn off specific tools per MCP server based on workflow needs
> > >
> > > > [card] Secure connections
> > > >
> > > > Support for OAuth 2.0 authentication ensures secure access to external services
> > >
> > > > [card] Tool reusability
> > > >
> > > > Configure MCP servers once and use their tools across multiple workflows and Custom Agent nodes
> > >
> > > > [card] Monitoring & debugging
> > > >
> > > > Console logs provide visibility into tool execution for troubleshooting and optimization
> >
> > > [card] [MCP Integration Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> > >
> > > Complete guide to MCP integration including data source configuration, tool management, and Custom Agent node usage.
> >
> > AI Integration
>
> ***
>
> ### **Custom Agent nodes**
>
> > [card] Custom Agent nodes
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Custom Agent nodes, enabling you to create AI agents with custom capabilities powered by Model Context Protocol (MCP) tools. Custom Agent nodes can interact with external systems, databases, and services through MCP servers, allowing them to perform complex, multi-step operations autonomously within your integration workflows.
> >
> > > [card] [Custom Agent Node Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> > >
> > > Complete guide to Custom Agent nodes, including configuration, usage, and best practices.
> >
> > AI Integration
>
> ***
>
> ### **Knowledge base**
>
> > [card] Knowledge base
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces Knowledge Base integration, enabling you to create and manage centralized repositories of information that AI agents can query when preparing responses. Upload static documents or ingest dynamic data from workflows into Knowledge Bases that use vector embeddings and semantic search for intelligent information retrieval.
> > >
> > > > [!NOTE]
> > > >
> > > > Knowledge Bases enable AI agents to provide contextual, accurate responses based on your organization's documentation, policies, and dynamic data.
> >
> > > [tab] Key Features
> > >
> > > > [card] Document upload
> > > >
> > > > Upload PDF documents directly into Knowledge Bases for AI agent access
> > >
> > > > [card] Workflow ingestion
> > > >
> > > > Ingest data dynamically from workflows using Knowledge Base operations (Append, Replace, Delete)
> > >
> > > > [card] Semantic search
> > > >
> > > > AI agents find relevant information using natural language queries with vector embeddings
> > >
> > > > [card] Content sources
> > > >
> > > > Organize content across multiple sources within a Knowledge Base for better management
> > >
> > > > [card] Relevance scoring
> > > >
> > > > Configure minimum relevance thresholds (0-100%) to control response quality
> > >
> > > > [card] Testing capabilities
> > > >
> > > > Test queries and operations in isolation before adding them to production workflows
> > >
> > > > [card] Custom agent integration
> > > >
> > > > Enable Knowledge Base queries in Custom Agent nodes with configurable parameters
> > >
> > > > [card] Content versioning
> > > >
> > > > Append, replace, or delete content sources with full traceability and state management
> >
> > > [tab] How It Works
> > >
> > > **1. Create Knowledge Base**
> > >
> > > Add a new Knowledge Base data source in Integration Designer
> > >
> > > **2. Ingest content**
> > >
> > > Upload PDF documents or ingest data from workflows into content sources
> > >
> > > **3. Automatic chunking**
> > >
> > > Content is automatically split into chunks and indexed in the vector database
> > >
> > > **4. Configure Custom Agent**
> > >
> > > Enable Knowledge Base in Custom Agent nodes and configure query parameters
> > >
> > > **5. Query execution**
> > >
> > > AI agents query the Knowledge Base using semantic search and receive relevant chunks
> > >
> > > **6. Response generation**
> > >
> > > Agents use retrieved chunks as context to generate accurate, informed responses
> >
> > > [tab] Workflow Operations
> > >
> > > **Knowledge Base operations available in workflows:**
> > >
> > > | Operation | Description |
> > > | - | - |
> > > | **Append** | Add new content to an existing content source without removing existing data |
> > > | **Replace** | Delete all existing content and replace with new content |
> > > | **Delete** | Remove all content from a content source |
> > >
> > > **Configuration Options:**
> > >
> > > * **Knowledge Base**: Select from local project libraries or dependencies
> > > * **Content Source**: Use existing sources, create new ones, or use workflow variables
> > > * **Content**: Static text, workflow variables, or configuration parameters
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product documentation assistant
> > > >
> > > > Create Knowledge Bases with product documentation for AI agents to answer customer questions
> > >
> > > > [card] Policy compliance
> > > >
> > > > Upload company policies so AI agents can reference them when processing requests
> > >
> > > > [card] Dynamic knowledge updates
> > > >
> > > > Ingest data from external systems through workflows to keep AI knowledge current
> > >
> > > > [card] Multi-source synthesis
> > > >
> > > > Organize information across sources and let AI agents synthesize comprehensive answers
> >
> > > [tab] Benefits
> > >
> > > > [card] Contextual AI responses
> > > >
> > > > AI agents provide accurate responses based on your organization's actual documentation
> > >
> > > > [card] Dynamic updates
> > > >
> > > > Keep AI knowledge current by ingesting data from workflows automatically
> > >
> > > > [card] Quality control
> > > >
> > > > Relevance scoring ensures only high-quality, relevant information is used
> > >
> > > > [card] Centralized management
> > > >
> > > > Manage all AI knowledge sources from a single location in Integration Designer
> > >
> > > > [card] No code integration
> > > >
> > > > Configure Knowledge Base queries directly in Custom Agent nodes without code
> > >
> > > > [card] Testable
> > > >
> > > > Test queries and see relevance scores before deploying to production
> >
> > > [tab] Limitations
> > >
> > > **Current Limitations:**
> > >
> > > > [!WARNING]
> > > >
> > > > * Only PDF documents are supported for manual upload (images, PPT, DOC, XLS support coming in future releases)
> > > > * Custom metadata cannot be defined (only system metadata is available)
> > > > * AI agents can only use one Knowledge Base per Custom Agent node
> > > > * Documents received from integrations cannot be directly ingested (Document Plugin links are treated as strings)
> >
> > > [card] [Knowledge Base Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > Complete guide to creating Knowledge Bases, ingesting content, and using them in Custom Agent workflows.
> >
> > AI Integration
>
> ***
>
> ### **Update process variables**
>
> > [card] Update process variables
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces the ability for operations teams to modify process variables on active (Started or On Hold) process instances, providing critical tools to resolve production issues without process restarts. Edit, add, or delete attributes and objects directly using an editor with JSON validation.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Formatting%20_%20Custom%20Date%20Format.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Tokens%20table.png)
> > >
> > > Edit, add, or delete attributes and objects directly using an editor with JSON validation
> > >
> > > > [!NOTE]
> > > >
> > > > Updated values automatically sync to Task Manager and Elasticsearch, ensuring consistency across all systems. Previous values are saved in a snapshot table, and all modifications are tracked in the audit log for complete traceability.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Limited correction tools
> > > >
> > > > Operations teams had minimal tools to correct production issues at the process-instance level
> > >
> > > > [card] Blocked instances
> > > >
> > > > No way to unblock stuck process instances without backend intervention or process restarts
> > >
> > > > [card] Data correction challenges
> > > >
> > > > Incorrect process data required complex workarounds or manual database modifications
> > >
> > > > [card] Operational delays
> > > >
> > > > Production issues required developer intervention, increasing resolution time
> >
> > > [tab] Key Features
> > >
> > > > [card] Editor
> > > >
> > > > Edit process variables in a JSON editor with syntax validation and formatting
> > >
> > > > [card] Multiple entry points
> > > >
> > > > Access from Process Instances page contextual menu or Process Instance page secondary navigation
> > >
> > > > [card] Dual view modes
> > > >
> > > > Switch between Tree View (existing) and JSON View for variable visualization and editing
> > >
> > > > [card] Full CRUD operations
> > > >
> > > > Edit existing attribute values, add new attributes/objects, or delete existing attributes/objects
> > >
> > > > [card] JSON validation
> > > >
> > > > Automatic JSON format validation before saving to ensure data integrity
> > >
> > > > [card] Snapshot history
> > > >
> > > > Previous process variables are saved in a new snapshot table before changes are applied
> > >
> > > > [card] Auto-sync to Task Manager
> > > >
> > > > Updated variables automatically sync to Task Manager using existing mechanism
> > >
> > > > [card] Elasticsearch integration
> > > >
> > > > Process variables configured for data search are automatically updated in Elasticsearch
> > >
> > > > [card] Permission-based access
> > > >
> > > > Role-based access control with process\_variables\_edit permission ensures only authorized users can modify variables
> > >
> > > > [card] Export functionality
> > > >
> > > > Export button available near the view dropdown for downloading process variables
> > >
> > > **Iteration 2 - Enhanced Review:**
> > >
> > > > [card] Compare feature
> > > >
> > > > Ability to review updated process variables through a compare feature, showing before/after values for better visibility and validation
> >
> > > [tab] How It Works
> > >
> > > **Accessing the Feature:**
> > >
> > > You can access the edit functionality from two entry points:
> > >
> > > 1. **Process Instances Page**: Use contextual menu on a process instance row → navigates to Process Instance page and opens Variables tab in edit mode
> > > 2. **Process Instance Page**: Use contextual menu in secondary navigation → opens Variables tab in edit mode
> > >
> > > **Editing Process Variables:**
> > >
> > > **1. Select active instance**
> > >
> > > Choose an active process instance (Started or On Hold status) that requires variable modification
> > >
> > > **2. Switch to JSON view**
> > >
> > > In the Variables tab, switch from Tree View to JSON View using the view dropdown
> > >
> > > **3. Click edit**
> > >
> > > Click the Edit button (visible only if you have process\_variables\_edit permission)
> > >
> > > **4. Modify in editor**
> > >
> > > Edit process variables in the JSON editor - you can edit existing values, add new attributes/objects, or delete existing ones
> > >
> > > **5. Validate JSON**
> > >
> > > Ensure your JSON format is valid before saving - the editor will highlight syntax errors
> > >
> > > **6. Save changes**
> > >
> > > Click Save to apply changes - a snapshot of previous values is automatically created
> > >
> > > **7. Auto-sync**
> > >
> > > System automatically syncs updated variables to Task Manager and Elasticsearch (for variables configured for data search)
> > >
> > > **8. Review audit log**
> > >
> > > Check the Audit Log tab to confirm the modification was recorded with all details
> >
> > > [tab] Permissions & Security
> > >
> > > **Permission Requirements:**
> > >
> > > * **New Permission**: `process_variables_edit` available at workspace level
> > > * **Default Roles**: Added to `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, and `workspace_operations_editor` roles
> > > * **New Role**: `workspace_operations_editor` - A dedicated workspace role for operations management including process variable editing and operations (migration & move token)
> > >
> > > **Access Control:**
> > >
> > > * Edit option in UI is only visible to users with `process_variables_edit` permission
> > > * Save functionality is restricted to users with the required permission
> > > * Unauthorized users can view process variables but cannot modify them
> > >
> > > **Audit Logging:**
> > >
> > > Every process variable modification creates an audit log entry with:
> > >
> > > * Workspace ID
> > > * Feature: Process variables
> > > * Section: Process Instance
> > > * Application UUID and name
> > > * Subject: Process variables
> > > * Event: Edit
> > > * Subject Identifier: Process instance UUID
> > > * Body: JSON with new version of process parameters
> > >
> > > Audit logs are displayed in the Audit Log tab within the process instance for easy tracking.
> >
> > > [tab] Data Synchronization
> > >
> > > **What Gets Updated:**
> > >
> > > > [card] Task Manager
> > > >
> > > > Variables are automatically updated in Task Manager using existing mechanisms - ensures task keywords and data remain consistent
> > >
> > > > [card] Elasticsearch
> > > >
> > > > Variables configured for data search are automatically updated in Elasticsearch - maintains search accuracy
> > >
> > > > [card] Process instance params
> > > >
> > > > Primary process instance parameters are updated immediately in the database
> > >
> > > > [card] Snapshot table
> > > >
> > > > Previous values are saved in a new snapshot table before changes are applied
> > >
> > > **What Does NOT Get Updated:**
> > >
> > > > [card] Process snapshots
> > > >
> > > > Process instance snapshots (used for back navigation/reset) are not updated - maintains historical integrity
> > >
> > > > [card] Debug table
> > > >
> > > > Process instance debug records remain unchanged - preserves execution history
> > >
> > > > [card] Existing audit logs
> > > >
> > > > Previously recorded audit logs (manual actions, integrations) are not modified - maintains compliance trail
> > >
> > > > [card] Subprocess variables
> > > >
> > > > Child subprocess variables are not automatically updated - parent changes don't cascade to children
> >
> > > [tab] Important Considerations
> > >
> > > **Limitations & Best Practices:**
> > >
> > > > [!WARNING]
> > > >
> > > > **Subprocess Impact**: When modifying parent process variables after subprocesses have started, child processes retain their original values. Variables are not propagated to existing subprocesses.
> > >
> > > > [!WARNING]
> > > >
> > > > **Back Navigation**: 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.
> > >
> > > > [!WARNING]
> > > >
> > > > **Integration Messages**: 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.
> > >
> > > **Best Practices:**
> > >
> > > * **Verify JSON Format**: Always ensure valid JSON before saving to prevent data corruption
> > > * **Document Changes**: Use audit logs to track all modifications and maintain operational documentation
> > > * **Test in Lower Environments**: When possible, test variable modifications in staging before production
> > > * **Understand Dependencies**: Review process flow and subprocess relationships before modifying variables
> > > * **Consider Timing**: Best used for stuck processes or data corrections, not for regular operational changes
> > > * **Check Search Data**: If variables are used in data search, verify Elasticsearch sync completed successfully
> >
> > > [tab] Benefits
> > >
> > > > [card] Faster issue resolution
> > > >
> > > > Operations teams can resolve production issues immediately without developer intervention
> > >
> > > > [card] Reduced downtime
> > > >
> > > > Unblock stuck instances quickly, minimizing impact on end users and business processes
> > >
> > > > [card] Operational independence
> > > >
> > > > Empower ops teams with self-service tools for process-instance management
> > >
> > > > [card] Data consistency
> > > >
> > > > Automatic sync ensures Task Manager and Elasticsearch reflect updated values
> > >
> > > > [card] Full traceability
> > > >
> > > > Snapshots and audit logs provide complete history of all modifications for compliance
> > >
> > > > [card] Reduced risk
> > > >
> > > > Permission-based access and comprehensive audit trail reduce risk of unauthorized changes
> > >
> > > > [card] Flexible editing
> > > >
> > > > The JSON editor provides powerful JSON editing capabilities with validation
> > >
> > > > [card] Historical preservation
> > > >
> > > > Original values preserved in snapshot table for rollback scenarios
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Correct User Input Errors**
> > >
> > > * Customer submitted incorrect data in a loan application (wrong income, invalid address)
> > > * Operations team edits the variables to correct the information
> > > * Process continues without requiring customer to restart the application
> > >
> > > **2. Unblock Stuck Process Instances**
> > >
> > > * Process is waiting for external data that will never arrive (integration timeout, external system down)
> > > * Ops team updates the variable to provide expected data or skip the condition
> > > * Instance is unblocked and continues execution
> > >
> > > **3. Fix Integration Data Issues**
> > >
> > > * External system returned incorrect or incomplete data
> > > * Operations team corrects process variables to match expected values
> > > * Process continues with accurate data without re-calling the integration
> > >
> > > **4. Emergency Data Updates**
> > >
> > > * Critical business information changed after process started (regulatory update, pricing change)
> > > * Ops team modifies variables to reflect current information
> > > * Process continues with updated data without restart
> > >
> > > **5. Add Missing Attributes**
> > >
> > > * Process needs additional data that wasn't collected at start
> > > * Operations team adds new attributes or objects to process variables
> > > * Process can now access the required information
> > >
> > > **6. Remove Invalid Data**
> > >
> > > * Process contains incorrect or test data that shouldn't be there
> > > * Ops team deletes the problematic attributes or objects
> > > * Process continues with clean, valid data only
> > >
> > > **7. Update Task Manager Keywords**
> > >
> > > * Task search keywords need updating based on corrected data
> > > * Variables are modified and automatically synced to Task Manager
> > > * Tasks become searchable with correct keywords
> > >
> > > **8. Fix Elasticsearch Search Data**
> > >
> > > * Process data indexed for search contains errors
> > >
> > > * Operations team corrects variables configured for data search
> > >
> > > * Elasticsearch automatically updates, ensuring accurate search results
> > >
> > > > [!NOTE]
> > > >
> > > > This capability, combined with the upcoming Move Token feature, provides comprehensive process-instance management tools for operations teams.
> >
> > > [card] [Update Process Variables Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > >
> > > Complete guide including step-by-step instructions, permissions, data synchronization, best practices, and troubleshooting.
> >
> > Operations Enhancement
>
> ***
>
> ### **Token view improvements**
>
> > [card] Token view improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 enhances the **Tokens tab** in the **Process Instance View** with improved visibility and comprehension of token hierarchy and context. The enhanced token view introduces horizontal scrolling, frozen columns, hierarchical nesting, and new context-related columns to provide better insights into process execution.
> > >
> > > > [!NOTE]
> > > >
> > > > These improvements make it easier to understand complex process flows with parallel gateways, embedded subprocesses, and boundary events by clearly displaying token relationships and execution context.
> >
> > > [tab] Key Features
> > >
> > > > [card] Horizontal scrolling
> > > >
> > > > The table supports horizontal scrolling to accommodate all columns, ensuring all token information remains accessible
> > >
> > > > [card] Frozen columns
> > > >
> > > > Token UUID and Actions columns remain fixed during horizontal scroll for constant visibility of key identifiers and actions
> > >
> > > > [card] Hierarchical nesting
> > > >
> > > > Tokens display in a tree structure with nested child tokens under parent tokens, showing clear parent-child relationships
> > >
> > > > [card] Auto-expanded rows
> > > >
> > > > All token rows are expanded by default, providing immediate visibility into the complete token hierarchy
> > >
> > > > [card] Dynamic indentation
> > > >
> > > > Indentation dynamically adjusts based on nesting depth, visually representing token relationships
> > >
> > > > [card] Context column
> > > >
> > > > New Context column displays subprocess names for tokens running within embedded subprocesses, or main process name for main process tokens
> > >
> > > > [card] Initiator node column
> > > >
> > > > New Initiator Node column shows the node name that generated the token (e.g., Parallel Gateway, Non-interrupting boundary event)
> > >
> > > > [card] First executed node column
> > > >
> > > > New First Executed Node column displays the first node executed after token generation
> > >
> > > > [card] UUID copy functionality
> > > >
> > > > Token UUID displays first 6 characters with a copy icon; clicking copies the full UUID to clipboard with success notification
> > >
> > > > [card] Color-coded status tags
> > > >
> > > > Token Status column uses color-coded tags for quick visual identification of token lifecycle states
> > >
> > > > [card] Tooltip support
> > > >
> > > > Long node names are truncated with tooltips showing full text on hover for better readability
> > >
> > > > [card] Timezone-aware timestamps
> > > >
> > > > Last Updated column displays full datetime in browser timezone for accurate local time representation
> >
> > > [tab] Table Columns
> > >
> > > The enhanced token view includes the following columns:
> > >
> > > | Column | Description | Special Behavior |
> > > | - | - | - |
> > > | **Token UUID** | Unique identifier of the token | Only first 6 characters displayed. Copy icon appears beside UUID. Clicking copies full UUID to clipboard with success toast: "Full Token UUID copied to clipboard." **Frozen column** (stays visible during horizontal scroll) |
> > > | **Context** | Displays contextual data for token | Shows main process name for tokens in main process. Shows embedded subprocess name for tokens in embedded subprocesses (any nesting level) |
> > > | **Initiator Node** | Shows the node name that generated the token | Applies to child tokens only. For parent tokens, displays "-". Examples: Parallel Gateway name, Non-interrupting boundary event name |
> > > | **First Executed Node** | Displays the first node executed after token generation | For parallel gateway tokens: first executed node on that parallel branch. For boundary event tokens: first executed node on branch started from boundary node. If first node is embedded subprocess, displays embedded subprocess name |
> > > | **Current Node** | Displays the last node executed within the token branch | For parallel gateway tokens: last node on branch. For boundary event tokens: last node executed on branch triggered by boundary. For tokens in embedded subprocess: displays current node from subprocess |
> > > | **Current Node Status** | Shows the current execution status | Examples: WAITING\_TIMER\_EVENT, ARRIVED, EXECUTING, EXECUTED\_COMPLETE, EXECUTED\_PARTIAL. Sortable column |
> > > | **Token Status** | Indicates lifecycle state | Values: ACTIVE, INACTIVE, ABORTED, ON HOLD, DISMISSED, EXPIRED, TERMINATED. **Color-coded tags** for visual identification |
> > > | **Last Updated** | Timestamp of latest token state change | Displays full datetime in browser timezone |
> > > | **Actions** | Available actions for the token | Includes Retry token and View (eye icon) actions. **Frozen column** (stays visible during horizontal scroll). Retry button only visible for ACTIVE tokens |
> >
> > > [tab] Nesting Behavior
> > >
> > > **Token Hierarchy Display:**
> > >
> > > **1. Parent-child relationships**
> > >
> > > Tokens created by parallel gateways or embedded subprocesses are displayed as nested child tokens under their parent tokens
> > >
> > > **2. Default expansion**
> > >
> > > All token rows are expanded by default, showing the complete token hierarchy immediately
> > >
> > > **3. Dynamic indentation**
> > >
> > > Indentation adjusts automatically based on nesting depth, with columns expanding accordingly to maintain alignment
> > >
> > > **4. Visual hierarchy**
> > >
> > > The tree structure makes it easy to identify which tokens belong to which parallel branch or subprocess
> > >
> > > **Initiator Node Logic:**
> > >
> > > * **Parent tokens**: Display "-" in Initiator Node column
> > > * **Child tokens from parallel gateway**: Display the parallel gateway node name
> > > * **Child tokens from boundary event**: Display the boundary event node name
> > > * **Child tokens from back in steps**: Display appropriate initiator information
> >
> > > [tab] Benefits
> > >
> > > > [card] Better visibility
> > > >
> > > > Horizontal scrolling and frozen columns ensure all token information remains accessible regardless of table width
> > >
> > > > [card] Clear hierarchy
> > > >
> > > > Hierarchical nesting with dynamic indentation makes parent-child token relationships immediately clear
> > >
> > > > [card] Context awareness
> > > >
> > > > Context column provides immediate visibility into which subprocess a token is executing within
> > >
> > > > [card] Execution tracking
> > > >
> > > > Initiator Node and First Executed Node columns help track token origin and execution path
> > >
> > > > [card] Quick actions
> > > >
> > > > Frozen Actions column ensures retry and view actions are always accessible without scrolling
> > >
> > > > [card] Easy UUID access
> > > >
> > > > Quick copy functionality for full UUIDs without needing to view token details
> > >
> > > > [card] Visual status identification
> > > >
> > > > Color-coded status tags enable quick identification of token states at a glance
> > >
> > > > [card] Improved readability
> > > >
> > > > Tooltips for truncated names and timezone-aware timestamps improve overall readability
> >
> > > [tab] Use Cases
> > >
> > > **Common Scenarios:**
> > >
> > > **1. Parallel Gateway Debugging**
> > >
> > > * View all parallel branches simultaneously with clear parent-child relationships
> > > * Identify which branch each token belongs to through hierarchical nesting
> > > * Track execution progress across multiple parallel paths
> > >
> > > **2. Embedded Subprocess Analysis**
> > >
> > > * Context column immediately shows which subprocess tokens are executing within
> > > * Understand nested subprocess relationships through indentation
> > > * Track token flow across multiple subprocess levels
> > >
> > > **3. Boundary Event Monitoring**
> > >
> > > * Initiator Node column shows which boundary event triggered each token
> > > * First Executed Node shows the execution path started by boundary events
> > > * Monitor non-interrupting boundary event token execution
> > >
> > > **4. Process Instance Troubleshooting**
> > >
> > > * Frozen UUID column ensures token identification is always visible
> > > * Copy UUID functionality enables quick token reference in support tickets
> > > * Color-coded status tags help identify problematic tokens quickly
> > >
> > > **5. Multi-Level Process Analysis**
> > >
> > > * Hierarchical view supports complex processes with multiple nesting levels
> > > * Dynamic indentation adapts to any nesting depth
> > > * All tokens visible by default without manual expansion
> >
> > > [card] [Token Documentation](/5.1/docs/building-blocks/token)
> > >
> > > Complete guide to tokens, including token status values, current node status, and detailed token status view.
> >
> > UX Enhancement
>
> ***
>
> ### **Access management enhancements**
>
> > [card] Access management enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.3 introduces new workspace-level permissions and a dedicated operations editor role, providing more granular control over process instance management and operations.
> > >
> > > > [!NOTE]
> > > >
> > > > These enhancements enable organizations to delegate operational tasks to dedicated teams without granting full runtime or admin access.
> >
> > > [tab] New Role
> > >
> > > **workspace\_operations\_editor**
> > >
> > > A new predefined workspace role designed for operations teams who need to manage process instances without requiring full runtime or admin capabilities.
> > >
> > > > [card] Operations management
> > > >
> > > > Full CRUD access for process instance operations including migration and move token functionality
> > >
> > > > [card] Process variables
> > > >
> > > > Edit permission for process variables on active instances across the workspace
> > >
> > > > [card] Process instances
> > > >
> > > > Read and edit access to all process instances in the workspace
> > >
> > > > [card] Workspace user inheritance
> > > >
> > > > Inherits all base permissions from workspace\_user role including project creation
> > >
> > > **Role Constraints:**
> > >
> > > * Cannot be edited or deleted (predefined role)
> > > * Extends workspace\_user with operations-specific permissions
> > > * Does not include broader runtime capabilities (builds, policies, scheduled processes)
> > >
> > > **Use Cases:**
> > >
> > > * Support engineers managing process migrations
> > > * Operations teams handling token movements
> > > * Technical support staff editing process variables
> >
> > > [tab] New Permissions
> > >
> > > **Workspace-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **Operations** (Read/Edit/Create/Delete) | Manage process instance operations including migration and move token | `org_admin`, `workspace_admin`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Operations** (Read/Create only) | Create operations and view all operations | `workspace_user` |
> > > | **Process Variables** (Edit) | Edit process variables on active instances | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > > | **Process Instances** (Edit) | Edit process instance data | `org_admin`, `workspace_admin`, `workspace_user`, `workspace_runtime_editor`, `workspace_operations_editor` |
> > >
> > > **Project-Level Permissions:**
> > >
> > > | Permission | Description | Roles with Access |
> > > | - | - | - |
> > > | **UI Flows** (Read/Edit/Create/Delete) | Full access to create and manage UI Flows | `project_owner`, `project_editor` |
> > > | **UI Flows** (Read only) | View UI Flows definitions | `project_viewer` |
> >
> > > [tab] Benefits
> > >
> > > > [card] Principle of least privilege
> > > >
> > > > Grant only the permissions needed for specific operational tasks
> > >
> > > > [card] Dedicated operations teams
> > > >
> > > > Enable operations teams to work independently without full admin access
> > >
> > > > [card] Clear separation of concerns
> > > >
> > > > Distinguish between runtime management (builds, policies) and operations management (migrations, variables)
> > >
> > > > [card] Flexible role combinations
> > > >
> > > > Combine with other workspace roles for customized access patterns
> >
> > > [card] [Access Management Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix#workspace-operations-editor-permission-matrix)
> > >
> > > Complete permissions matrix and role specifications for all FlowX roles.
> >
> > Access Management
>
> ***
>
> ### **Performance and stability**
>
> > [card] Performance and stability
> >
> > FlowX.AI 5.3 includes platform improvements focused on performance, reliability, and operational excellence.
> >
> > ## Backend optimizations
> >
> > > [card] Optimistic lock improvements
> > >
> > > Replace retry pattern with capped exponential backoff and infinite retries for better concurrency handling
> >
> > > [card] Events gateway optimization
> > >
> > > Update Redis read mode to XREAD BLOCK for more efficient event streaming
> >
> > > [card] Database performance
> > >
> > > Remove unnecessary index on token\_instance.current\_node\_id to improve update performance
> >
> > > [card] Template caching
> > >
> > > Enhanced caching for reusable templates at runtime reduces latency and improves throughput
> >
> > ## Infrastructure updates
> >
> > > [card] Connector Topic Pattern
> > >
> > > Added dedicated KAFKA\_CONNECTORS\_TOPIC\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [card] SpiceDB backup
> > >
> > > Documented backup and restore procedures for SpiceDB for disaster recovery
> >
> > > [card] Observability
> > >
> > > Publish Prometheus and OpenTelemetry Helm charts and container images to Harbor
> >
> > > [card] Security updates
> > >
> > > Fix HIGH vulnerabilities in Designer 5.1.x and main branch
> >
> > > [card] Renderer improvements
> > >
> > > Enhanced Angular renderer with action form submit functionality and substitution tag support
> >
> > Platform Updates
>
> ***
>
> ### **Exclusive gateways**
>
> > [card] Exclusive gateways
> >
> > FlowX.AI 5.3 enhances Exclusive Gateway configuration with expression testing capabilities and improved validation.
> >
> > > [card] Expression testing
> > >
> > > Test gateway expressions directly from the configuration panel with real-time validation
> >
> > > [card] Committed version testing
> > >
> > > Test business rules and gateway expressions in committed versions
> >
> > > [card] Code editor integration
> > >
> > > Enhanced code editor with syntax highlighting for complex expressions
> >
> > > [card] Payload synchronization
> > >
> > > Test payloads automatically update when rules are saved
> >
> > Process Logic
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes and stability improvements across Designer, renderers, backend services, and data management.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI Designer and Integration Designer stability improvements\
> 🖥️ [**Renderer Fixes**](#renderer-fixes) - Cross-platform renderer bug fixes for web, iOS, and Android\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements\
> 🗄️ [**Data & Integration Fixes**](#data-and-integration-fixes) - Data mapper and workflow integration fixes
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.3 resolves numerous Designer issues to improve stability and user experience.
> >
> > ## UI designer improvements
> >
> > > [accordion] Configuration & styling
> > >
> > > * **Fixed styles not applied after undo/redo** in Reusable UI Template config panel
> > > * **Fixed UI blocking** when slider min value exceeds max value
> > > * **Fixed warning icon display** in config panel
> > > * **Fixed expression test modal styles** when opened in resized screen
> > > * **Fixed UI action section refresh** when selecting different UI template
> > > * **Fixed UI action section rendering** after clicking 'Add new ui action'
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed loading spinner toggle** not available for Overlay loading behavior
> > > * **Fixed incomplete loading behavior dropdown**
> > > * **Fixed default messages** not displayed after undo
> > > * **Fixed forms in collections handling** for patch actions requests
> >
> > > [accordion] UI Flows designer
> > >
> > > * **Fixed task management error state** when view is selected
> > > * **Fixed tab content preview** showing content from 2 tabs when adding new tab
> >
> > > [accordion] Output parameters
> > >
> > > * **Fixed currency key management** - can now add/remove currency key in output params
> >
> > > [accordion] Exclusive Gateways
> > >
> > > * **Fixed gateway decisions** can now be modified after initial save
> > > * **Fixed test payload** updates when rules are saved
> > > * **Fixed expression propagation** to test modal
> >
> > ## Frontend runtime fixes
> >
> > > [accordion] Process management
> > >
> > > * **Fixed context column** showing empty value for tokens in embedded subprocesses
> > > * **Fixed process params update** from running process instance modal
> > > * **Fixed long node names** overlapping adjacent columns in Tokens table
> > > * **Fixed workspace redirect** on page refresh
> >
> > > [accordion] Audit & logging
> > >
> > > * **Fixed audit log subject value** not displayed for process params updates
> > > * **Fixed toast error messages** to use text from backend request
> > > * **Added documentation link** to Modify Variables modal info text
> >
> > Designer Stability
>
> ***
>
> ### **Renderer fixes**
>
> > [card] Renderer fixes
> >
> > FlowX.AI 5.3 includes comprehensive renderer fixes across all platforms.
> >
> > ## Web renderers (Angular & React)
> >
> > > [accordion] File upload component
> > >
> > > * **Fixed theming** not applied to general loader
> > > * **Fixed theming** not applied to toast messages
> > > * **Fixed dynamic key values** not displayed in toast/loading messages
> > > * **Fixed success toast** displayed when flag is false
> >
> > > [accordion] Card & navigation
> > >
> > > * **Fixed card not expandable** after finishing subprocess started from it (Angular & React)
> > > * **Fixed card collapse** when next nav area is modal (Angular & React)
> > > * **Fixed subprocess navigation** closing parent process navigation with multiple hierarchies
> >
> > > [accordion] UI events
> > >
> > > * **Fixed UI event triggering** without user interaction (Angular)
> >
> > > [accordion] Call activity
> > >
> > > * **Fixed call activity UT rendering** when started from embedded process
> >
> > > [accordion] Collections & forms
> > >
> > > * **Fixed button with forms to submit** no longer disabled until template edited (Angular & React)
> > > * **Fixed multi-select search** filtering (React)
> > > * **Fixed JSON generation** with special characters in CollectionsV2
> >
> > ## Mobile renderers
> >
> > > [accordion] Android
> > >
> > > * **Fixed SSE Event & UI Event** - UI event value displayed instead of SSE value
> >
> > Renderer Stability
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process management
> >
> > > [accordion] Process & build issues
> > >
> > > * **Fixed processes not displayed** in container app list for imported builds
> > > * **Fixed token state** changing from Aborted to Active during back navigation
> > > * **Fixed audit logs** for override operations after merge
> >
> > > [accordion] Performance
> > >
> > > * **Fixed /details endpoint** returning cache error for processes with many components
> >
> > > [accordion] Process engine
> > >
> > > * **Fixed token stuck** in receive node when message received after advancing
> > > * **Fixed action params** copied correctly for child actions when copying node
> > > * **Fixed metadata preservation** when importing process
> >
> > ## Security & configuration
> >
> > > [accordion] Authentication
> > >
> > > * **Fixed service account client secret** configuration parameter in Authorization service
> >
> > ## Data management
> >
> > > [accordion] Runtime issues
> > >
> > > * **Fixed FlowxProps.events** mapping at runtime for array of objects
> >
> > ## Infrastructure
> >
> > > [accordion] Database & events
> > >
> > > * **Fixed advancing errors** in partition event table
> > > * **Fixed Liquibase logging** when crashing due to lock
> >
> > Backend Stability
>
> ***
>
> ### **Data and integration fixes**
>
> > [card] Data and integration fixes
> >
> > Fixes for data mappers and workflow integration features.
> >
> > ## Data mapper issues
> >
> > > [accordion] Mapping operations
> > >
> > > * **Fixed 400 error** when saving mappings
> > > * **Fixed error** when saving mapping with empty parameters
> > > * **Fixed unsaved mapping modal** displayed when saving action
> > > * **Fixed array mapping** - arrays in mapper functions now work correctly
> > > * **Fixed slice deletion** when updating PDM objects
> >
> > > [accordion] Data streams & workflows
> > >
> > > * **Fixed data stream availability** for older exports during import
> > > * **Fixed workflow data stream** data appending issue
> > > * **Fixed legacy mapping** toggle now triggers correctly for call activity
> >
> > > [accordion] UI updates
> > >
> > > * **Fixed start node** not updated in UI after parameters update until refresh
> > > * **Fixed manifest resource** not found after switching versions
> >
> > > [!NOTE]
> > >
> > > Data mapper fixes ensure reliable workflow integration and process-to-workflow data synchronization.
> >
> > Integration Stability
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.3.0](./deployment-guidelines-v5.3).
>
> ### Environment variable updates
>
> > [!NOTE]
> >
> > For detailed information on environment variable changes, see the [Update environment variables](./migrating-from-v5.2-to-v5.3/update-environment-variables-5.3) section.
>
> ### Breaking changes
>
> > [!WARNING]
> >
> > **FlowX Engine Configuration**: v5.3.0 includes a breaking change to the partitioning and archiving configuration structure. If you have enabled data partitioning, you must update your configuration files.
>
> > [card] [Migration guide](./migrating-from-v5.2-to-v5.3/migration-overview)
> >
> > Complete migration guide with step-by-step instructions, configuration examples, and troubleshooting
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.2.0 requires configuration changes for FlowX Engine partitioning/archiving
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.3


# Deployment guidelines v5.4.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/deployment-guidelines-v5.4

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.38.0** | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **10.38.0** | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **10.22.0** | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **10.15.0** | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **10.17.0** | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **10.22.0** | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **10.23.0** | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **10.25.0** | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **10.14.0** | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **10.21.0** | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **10.16.0** | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **10.38.0** | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **10.37.0** | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **10.20.1** | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **10.28.0** | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **10.17.0** | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 | 9.11.0 |
| **email-gateway** | **10.9.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **10.59.1** | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **10.2.0** | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.0 |

### AI Platform

| Component | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | **10.1.3** | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 | 9.0.1 |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.4.0 | Keycloak | 26+ |
| 5.4.0 | Kafka | 3.8 - 3.9 |
| 5.4.0 | PostgreSQL | 16 - 17 |
| 5.4.0 | Oracle Database | 21c, 23ai |
| 5.4.0 | MongoDB | 7 - 8 |
| 5.4.0 | Redis | 7.4 - 8.0 |
| 5.4.0 | Elasticsearch | 8 |
| 5.4.0 | Angular (Web SDK) | 20 |
| 5.4.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.4.0

### Key features and updates

> [card] Email Trigger
>
> Start processes automatically from incoming emails with configurable validation rules

> [card] MCP Server Improvements
>
> Enhanced audit logging, resource management, and tool refresh capabilities

> [card] Email Gateway
>
> New microservice for handling email communication workflows

## Upgrading from v5.3.0

### Breaking changes

> [!NOTE]
>
> FlowX.AI 5.4.0 does not introduce breaking changes for standard deployments. Upgrades from v5.3.0 should be straightforward.

### New environment variables

The following new environment variables have been introduced:

| Variable | Service | Description |
| - | - | - |
| `KAFKA_CONNECTORS_TOPIC_PATTERN` | process-engine | Dedicated Kafka topic pattern for connectors (optional, falls back to `KAFKA_TOPIC_PATTERN` if not set) |
| `KAFKA_BOOTSTRAP_SERVERS` | All services | Standardized Kafka bootstrap servers property (preferred over `SPRING_KAFKA_BOOTSTRAPSERVERS`, backwards compatible) |
| `KAFKA_SECURITY_PROTOCOL` | All services | Standardized Kafka security protocol property (preferred over `SPRING_KAFKA_SECURITY_PROTOCOL`, backwards compatible) |

### Key changes

* **Email Trigger**: New capability to start processes from email events
* **Connector Topics**: New dedicated topic pattern variable for connectors
* **Kafka Configuration**: Standardized Kafka property names (`KAFKA_BOOTSTRAP_SERVERS`, `KAFKA_SECURITY_PROTOCOL`) aligned across all services with backwards compatibility
* **Email Gateway**: New microservice for email communication workflows

### New microservice: Email Gateway

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces a new optional microservice: **Email Gateway**. This service handles email communication workflows within the platform.

The Email Gateway requires the following infrastructure:

| Component | Requirement |
| - | - |
| PostgreSQL | Dedicated database named `email_gateway` |
| MongoDB | Connection to existing `app-runtime` database |
| Kafka | Access to the FlowX Kafka cluster |
| Redis | Shared Redis instance |
| Keycloak | Service account for authentication |

> [!NOTE]
>
> The Email Gateway operates as an internal service and does not require ingress configuration.

> [card] [Email Gateway Setup Guide](/5.9/setup-guides/email-gateway-setup)
>
> Complete setup instructions including Helm values, environment variables, and troubleshooting.

### Compatibility

* **No Breaking Changes**: Standard deployments can upgrade without configuration changes
* **Feature Additions**: SaaS features require additional infrastructure configuration for production use
* **Renderer Updates**: Web and mobile SDKs include bug fixes with backward compatibility
* **Database**: No schema changes required for this upgrade

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.4.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.4.0-january-2026/v5.4.0-january-2026

SaaS multi-tenant platform capabilities, database tenant isolation, email-triggered processes, MCP server enhancements, and backend performance improvements.

> [!NOTE]
>
> FlowX.AI 5.4.0 introduces foundational support for a multi-tenant platform, enabling organization management and improved tenant isolation in the SaaS deployment model.

> [!NOTE]
>
> **Deployment models** - Starting with v5.4.0, FlowX.AI is available in two deployment models:
>
> * **Self-Managed** (On-Premises / Customer Cloud)
> * **FlowX SaaS** (FlowX-hosted)
>
> **Feature availability badges:**
>
> * SaaS Features exclusive to FlowX SaaS deployments
> * Self-Managed Features specific to self-managed deployments
> * All Deployments Features available in both deployment models

**What's new?**

> [tab] SaaS & multi-tenancy
>
> > [!NOTE]
> >
> > The features described in this section apply to **FlowX SaaS deployments**.\
> > Self-managed deployments are not affected unless explicitly stated.
>
> FlowX.AI 5.4.0 introduces initial SaaS capabilities enabling multi-tenant deployments with organization management and tenant isolation.
>
> 🏢 [**SaaS Multi-Tenancy**](#saas-multi-tenancy) - Multi-tenant platform with organization isolation and provisioning
>
> ### **SaaS multi-tenancy**
>
> > [card] SaaS multi-tenancy
> >
> > Multi-tenant SaaS capabilities enable multiple organizations to operate independently on shared infrastructure. Each organization receives dedicated resources while maintaining complete isolation from other tenants.
> >
> > > [card] Multi-tenant architecture
> > >
> > > Multiple organizations operate on shared infrastructure with complete isolation
> >
> > > [card] Tenant isolation
> > >
> > > Complete data and authentication isolation between organizations
> >
> > > [card] Organization provisioning
> > >
> > > Automatic provisioning of dedicated resources for each organization
> >
> > > [card] Resource management
> > >
> > > Each organization receives dedicated resources and project spaces
> >
> > > [card] [Documentation](/5.9/docs/saas/saas-overview)
> > >
> > > See the complete FlowX SaaS documentation for guides and best practices.
> >
> > Major FeatureSaaS
>
> ***

> [tab] AI & Integration
>
> Enhanced MCP server management.
>
> 📧 [**Email Trigger**](#email-trigger) - Start processes from external email events with configurable validation rules\
> 💬 [**Chat Component**](#chat-component) - Standalone chat tab for AI-powered conversational interfaces\
> 🔧 [**MCP Server Improvements**](#mcp-server-improvements) - Enhanced audit logging, resource management, and tool updates
>
> ### **Email trigger**
>
> > [card] Email trigger
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces Email Trigger as a new Data Source type in Integration Designer, enabling processes to be started automatically when emails are received. Connect to IMAP mail servers, monitor specific mailboxes, and create process instances with the email data.
> > >
> > > > [!NOTE]
> > > >
> > > > Email Triggers bridge external communication channels with FlowX.AI process automation, enabling organizations to automatically route and process incoming emails through defined business workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation for configuration guides and examples.
> >
> > > [tab] Key Features
> > >
> > > > [card] IMAP Connection
> > > >
> > > > Connect to any IMAP-compatible email server with SSL/TLS support
> > >
> > > > [card] Message Start Event
> > > >
> > > > New trigger type option in Message Start Event nodes to use Email Triggers
> > >
> > > > [card] Attachment handling
> > > >
> > > > Automatic upload of email attachments to Document Plugin with file validation
> > >
> > > > [card] Validation rules
> > > >
> > > > Configure allowed file types, maximum file size, and attachment count limits
> > >
> > > > [card] Manage triggers
> > > >
> > > > Central Runtime page to activate, deactivate, and monitor email triggers
> > >
> > > > [card] Failed triggers
> > > >
> > > > Dedicated page to view and troubleshoot failed email processing attempts
> >
> > > [tab] Configuration
> > >
> > > **Data Source Settings:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | IMAP (currently supported) |
> > > | Server Host | IMAP server hostname |
> > > | Port | Connection port (993 for SSL/TLS) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > > | SSL/TLS | Enable secure connection |
> > >
> > > **Filtering Criteria:**
> > >
> > > * **Email Address**: Monitored email address (read-only, based on authentication)
> > > * **Mailbox Folder**: Folder to monitor (default: Inbox)
> > >
> > > **Validation Options:**
> > >
> > > * **Allowed File Types**: PDF, DOCUMENT, IMAGE, EXCEL, ZIP
> > >
> > > * **Maximum File Size**: Up to 25 MB per attachment
> > >
> > > * **Maximum File Count**: Limit attachments per email
> > >
> > > > [!TIP]
> > > >
> > > > All fields accept configuration parameters using `${configParam}` syntax for environment-specific values.
> >
> > > [tab] Email Data Schema
> > >
> > > When an email triggers a process, the following data structure is available:
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "emailMessage": {
> > >     "subject": "Support Request #12345",
> > >     "dateTime": "2026-01-15T10:30:00Z",
> > >     "sender": "customer@example.com",
> > >     "body": "Email body content...",
> > >     "fileAttachments": [{
> > >       "filePath": "email-attachments/proc-123/file.pdf",
> > >       "downloadPath": "/api/internal/files/uuid/download"
> > >     }],
> > >     "headerParams": {
> > >       "Message-ID": "<abc123@example.com>"
> > >     }
> > >   }
> > > }
> > > ```
> >
> > > [tab] Use Cases
> > >
> > > > [card] Customer support automation
> > > >
> > > > Automatically create support tickets from incoming customer emails
> > >
> > > > [card] Document processing
> > > >
> > > > Process attached documents through automated workflows
> > >
> > > > [card] Request handling
> > > >
> > > > Route requests to appropriate departments based on email content
> > >
> > > > [card] Notification processing
> > > >
> > > > Process automated notifications from external systems
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat component**
>
> > [card] Chat component
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a standalone Chat tab in web container applications, enabling AI-powered conversational interfaces within your applications. The Chat component provides a dedicated space for users to interact with AI agents through a familiar messaging interface.
> > >
> > > > [!NOTE]
> > > >
> > > > The Chat component integrates with FlowX.AI's AI platform to enable intelligent conversational experiences powered by your configured AI agents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the complete Chat Component documentation for configuration guides and best practices.
> >
> > > [tab] Key Features
> > >
> > > > [card] Standalone chat tab
> > > >
> > > > Dedicated chat interface available as a standalone tab in web container apps
> > >
> > > > [card] Message history
> > > >
> > > > Persistent chat history with automatic scrolling to the latest messages
> > >
> > > > [card] AI agent integration
> > > >
> > > > Connect to workflows powered by AI agents
> > >
> > > > [card] Session management
> > > >
> > > > Automatic session handling with persistence across page refreshes
> > >
> > > > [card] Customizable UI
> > > >
> > > > Themeable components with comprehensive style configuration through Theme Admin
> >
> > > [tab] Configuration
> > >
> > > **Component setup:**
> > >
> > > * Add Chat component from UI Designer to your UI Flow
> > > * Select a workflow to handle chat interactions
> > > * Configure header, messages, and input properties
> > > * Apply custom styling through Theme Admin
> > >
> > > **Display modes:**
> > >
> > > * Full screen (v5.4.0)
> > > * Additional modes planned for v5.5
> >
> > > [tab] Improvements
> > >
> > > **Session handling:**
> > >
> > > * Chat session ID is now generated when the first message is sent (not when opening the chat)
> > > * Improved session tracking
> > >
> > > **Message display:**
> > >
> > > * Latest messages are automatically scrolled into view after loading chat history
> > > * User input formatting (JSON, multiline text) is now preserved in displayed messages
> > >
> > > **Platform support:**
> > >
> > > * Available in both Angular and React web renderers
> > > * Mobile support planned for v5.5
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **MCP server improvements**
>
> > [card] MCP server improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 enhances MCP (Model Context Protocol) server integration with improved audit logging, exception handling, and resource management capabilities.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audit logging
> > > >
> > > > Complete audit trail for MCP server operations including creation, updates, and tool execution
> > >
> > > > [card] Tool refresh
> > > >
> > > > Update MCP servers to fetch new tools without recreating the data source
> > >
> > > > [card] Resource tracking
> > > >
> > > > Track MCP server usage across workflows with proper resource management
> > >
> > > > [card] Copy support
> > > >
> > > > Properly preserve MCP server selections when copying or duplicating workflows
> > >
> > > > [card] SSE streaming
> > > >
> > > > Fixed SSE event streaming to deliver events individually as they complete
> > >
> > > > [card] Exception handling
> > > >
> > > > Improved error handling and reporting for MCP server operations
> >
> > > [tab] Bug Fixes
> > >
> > > * **Tool updates**: Updating MCP servers now correctly fetches new tools
> > > * **Workflow copy**: MCP server selections are preserved when copying workflows
> > > * **Resource usages**: Fixed resource usage tracking when copying workflows to other projects
> > > * **SSE events**: Events are now streamed individually instead of all at once
> > > * **Audit entries**: Fixed missing event and subject in audit log entries
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] Rendering
>
> UI component enhancements and navigation improvements for web applications.
>
> 🎴 [**Card Default Collapse State**](#card-default-collapse-state) - Configure cards to load in collapsed state by default\
> 🧭 [**UI Flow Breadcrumbs**](#ui-flow-breadcrumbs) - Navigation breadcrumbs ui component for UI Flows with theme configuration\
> 📊 [**UI Flow Sessions**](#ui-flow-sessions) - Monitor and manage UI Flow sessions with audit logs and process tracking\
> 📋 [**Tables in Collections**](#tables-in-collections) - Add support for Table UI components within Collection UI elements
>
> ### **Card default collapse state**
>
> > [card] Card default collapse state
> >
> > FlowX.AI 5.4.0 introduces a new **Default collapse state** property for Card components with accordion functionality, allowing you to configure cards that are collapsed when first loaded.
> >
> > > [tab] Overview
> > >
> > > When using Card components with the accordion feature enabled, you can now specify whether the card should be expanded or collapsed by default when the screen loads. This provides better control over the initial presentation of content and helps manage screen real estate.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> > > >
> > > > See the complete Card component documentation for configuration details.
> >
> > > [tab] Configuration
> > >
> > > **Default collapse state options:**
> > >
> > > | State | Description |
> > > | - | - |
> > > | **Expanded** | The card content is visible when the screen loads (default behavior) |
> > > | **Collapsed** | The card content is hidden when the screen loads; users click to expand |
> > >
> > > > [!NOTE]
> > > >
> > > > This property is only available when the **Has accordion** setting is enabled on the Card component.
> >
> > > [tab] Use Cases
> > >
> > > > [card] Progressive disclosure
> > > >
> > > > Start with collapsed sections to reduce initial visual complexity
> > >
> > > > [card] Optional content
> > > >
> > > > Hide less important information by default while keeping it accessible
> > >
> > > > [card] Long forms
> > > >
> > > > Break up lengthy forms into collapsible sections for better navigation
> > >
> > > > [card] FAQ sections
> > > >
> > > > Display questions collapsed with answers revealed on click
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Breadcrumbs**
>
> > [card] UI Flow Breadcrumbs
> >
> > > [tab] Overview
> > >
> > > Navigation breadcrumbs UI component for UI Flows provide users with clear context of their current location within the application hierarchy. Breadcrumbs display the navigation path and enable quick navigation to parent screens.
> > >
> > > > [!NOTE]
> > > >
> > > > Breadcrumbs enhance user experience by providing visual navigation context and allowing users to understand their position in the application structure.
> >
> > > [tab] Key Features
> > >
> > > > [card] Navigation breadcrumbs UI component
> > > >
> > > > Display breadcrumbs UI component for UI Flows showing the current navigation path
> > >
> > > > [card] Admin theme configuration
> > > >
> > > > Configure breadcrumb appearance and styling through Admin theme settings
> >
> > > [tab] Configuration
> > >
> > > **Theme Configuration:**
> > >
> > > * Configure breadcrumb styling through Admin theme settings
> > > * Customize colors, fonts, and spacing to match your application design
> > > * Apply consistent styling across all UI Flows
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **UI Flow Sessions**
>
> > [card] UI Flow Sessions
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces UI Flow Sessions monitoring in the Runtime view, providing comprehensive visibility into active user sessions with UI Flows. Monitor session activity, view audit logs, track associated processes, and debug UI Flow interactions in real-time.
> > >
> > > > [!NOTE]
> > > >
> > > > UI Flow Sessions enable administrators and developers to track user interactions, troubleshoot issues, and monitor the health of UI Flow-based applications.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> > > >
> > > > See the complete UI Flow Sessions documentation for detailed usage and troubleshooting guides.
> >
> > > [tab] Key Features
> > >
> > > > [card] Session monitoring
> > > >
> > > > View all active and historical UI Flow sessions with status, start date, and session IDs
> > >
> > > > [card] Audit log
> > > >
> > > > Comprehensive audit trail showing all events and actions within each session
> > >
> > > > [card] Process tracking
> > > >
> > > > Monitor process instances started from UI Flows with execution status and timing
> > >
> > > > [card] Workflow debugging
> > > >
> > > > View workflow execution details, node timing, and data transformations for troubleshooting
> > >
> > > > [card] Filtering and search
> > > >
> > > > Filter sessions by UI Flow definition and search by session ID for quick access
> > >
> > > > [card] Real-time status
> > > >
> > > > Track session status updates in real-time (STARTED, ACTIVE, FINISHED, FAILED)
> >
> > > [tab] Use Cases
> > >
> > > > [card] Session monitoring
> > > >
> > > > Monitor active sessions to understand user engagement and identify sessions needing attention
> > >
> > > > [card] Audit and compliance
> > > >
> > > > Track all user interactions and actions for audit purposes and compliance requirements
> > >
> > > > [card] Debugging
> > > >
> > > > Investigate issues by reviewing audit logs, process instances, and workflow executions
> > >
> > > > [card] Performance analysis
> > > >
> > > > Analyze session duration, process start times, and workflow execution performance
> >
> > Runtime ManagementAll Deployments
>
> ***
>
> ### **Tables in Collections**
>
> > [card] Tables in Collections
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces support for Table UI components within Collection UI elements, enabling you to display structured tabular data as items within dynamic collections. This enhancement provides greater flexibility for presenting complex data structures in a consistent, organized format.
> > >
> > > > [!NOTE]
> > > >
> > > > You can now embed Table components inside Collection prototypes, allowing each collection item to display data in a structured table format with columns, rows, and table-specific features.
> > >
> > > > [card] [Table Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/table)
> > > >
> > > > See the complete Table component documentation for configuration details and usage examples.
> > >
> > > > [card] [Collection Documentation](/5.1/docs/building-blocks/ui-designer/ui-component-types/collection/collection)
> > > >
> > > > Learn about Collection components and how to configure collection prototypes.
> >
> > > [tab] Key Features
> > >
> > > > [card] Table in collection items
> > > >
> > > > Embed Table components within Collection prototypes to display structured data for each collection item
> > >
> > > > [card] Structured data display
> > > >
> > > > Present complex data structures with columns, rows, and table-specific formatting within collections
> > >
> > > > [card] Table features
> > > >
> > > > Leverage full Table component capabilities including sorting, filtering, pagination, and row actions
> > >
> > > > [card] Dynamic content
> > > >
> > > > Combine Collection's dynamic data handling with Table's structured presentation for flexible layouts
> >
> > > [tab] Use Cases
> > >
> > > > [card] Product catalogs
> > > >
> > > > Display product information in table format within a collection of products
> > >
> > > > [card] Data dashboards
> > > >
> > > > Create dashboard views with multiple tables showing different data sets in collection items
> > >
> > > > [card] Report listings
> > > >
> > > > Show report summaries in table format within a collection of reports
> > >
> > > > [card] Comparison views
> > > >
> > > > Compare multiple entities side-by-side using tables within collection items
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Platform & infrastructure
>
> Backend optimizations, connector improvements, and platform stability enhancements.
>
> 🔌 [**Connector Topic Pattern**](#connector-topic-pattern) - Dedicated Kafka topic pattern for connectors\
> ⚙️ [**Kafka Configuration Alignment**](#kafka-configuration-alignment) - Unified Kafka property names across all services with backwards compatibility\
> ⚡ [**Advancing Performance**](#advancing-performance) - Fixed advancing partition issues and improved concurrency handling
>
> ### **Connector topic pattern**
>
> > [card] Connector topic pattern
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 introduces a dedicated Kafka topic pattern variable (`KAFKA_CONNECTORS_TOPIC_PATTERN`) for connectors, allowing custom topic patterns without affecting other platform components like document-plugin, data-search, and cms-core.
> >
> > > [tab] Problem Solved
> > >
> > > **Previous Limitations:**
> > >
> > > > [card] Shared topic pattern
> > > >
> > > > Connectors used the same `KAFKA_TOPIC_PATTERN` as other components, limiting customization
> > >
> > > > [card] Security concerns
> > > >
> > > > Connectors could write to all topics with the pattern `ai.flowx.engine.receive.*`
> >
> > > [tab] Solution
> > >
> > > **New Configuration:**
> > >
> > > ```yaml theme={"dark"}
> > > # Old configuration (shared with all components)
> > > KAFKA_TOPIC_PATTERN: ai.flowx.engine.receive.*
> > >
> > > # New configuration (dedicated for connectors)
> > > KAFKA_CONNECTORS_TOPIC_PATTERN: ro.uniflow.*
> > > ```
> > >
> > > **Benefits:**
> > >
> > > * Connectors can use custom topic patterns
> > > * Other components continue using the standard pattern
> > > * Improved security through topic isolation
> >
> > InfrastructureSelf-Managed
>
> ***
>
> ### **Kafka configuration alignment**
>
> > [card] Kafka configuration alignment
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.4.0 aligns Kafka configuration properties across all services (core-services and AI platform services) by introducing standardized property names while maintaining full backwards compatibility with existing configurations.
> >
> > > [tab] New Properties
> > >
> > > **Standardized Kafka Properties:**
> > >
> > > The following new environment variables are now available across all services:
> > >
> > > | Environment Variable | Description | Fallback Property |
> > > | - | - | - |
> > > | `KAFKA_BOOTSTRAP_SERVERS` | Comma-separated list of Kafka brokers | `SPRING_KAFKA_BOOTSTRAP_SERVERS` |
> > > | `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka communication | `SPRING_KAFKA_SECURITY_PROTOCOL` |
> > >
> > > > [!NOTE]
> > > >
> > > > The new properties take precedence over the legacy `SPRING_KAFKA_*` properties. If the new properties are not set, the system automatically falls back to the legacy properties, ensuring backwards compatibility.
> >
> > > [tab] Benefits
> > >
> > > > [card] Property alignment
> > > >
> > > > Consistent property names across core-services and AI platform services
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing configurations using `SPRING_KAFKA_*` properties continue to work without changes
> > >
> > > > [card] Simplified configuration
> > > >
> > > > Unified configuration approach across all FlowX.AI services
> > >
> > > > [card] Migration flexibility
> > > >
> > > > Migrate to new properties at your own pace without breaking existing deployments
> > >
> > > > [!NOTE]
> > > >
> > > > This change was implemented in core-services and automatically applies to all services that use the shared Kafka configuration. No action is required for existing deployments, but you can optionally migrate to the new property names for consistency.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Advancing performance**
>
> > [card] Advancing performance
> >
> > FlowX.AI 5.4.0 includes significant fixes and improvements to the advancing mechanism, resolving issues with stalled events and improving concurrency handling.
> >
> > > [accordion] Stalled events fix
> > >
> > > Fixed issue where NEW entries in `advancing_partition` and `advancing_partition_event` tables would become stalled and never processed. This occurred when multiple events were generated for the same partition during parallel processing.
> >
> > > [accordion] Numeric overflow fix
> > >
> > > Fixed numeric overflow error when `advancing_partition_event_seq` sequence exceeded `Integer.MAX_VALUE`. Now correctly uses `getLong()` instead of `getInt()` for sequence values.
> >
> > > [accordion] Concurrency improvements
> > >
> > > * Fixed issue with multiple events to the same partition causing negative `count_queued_events`
> > > * Replaced trigger-based solution with SQL transactions for atomic updates
> > > * Improved handling of embedded subprocess completion under concurrent load
> >
> > > [accordion] Automated test stability
> > >
> > > Resolved data inconsistencies and business exceptions that were causing automated tests to fail consistently.
> >
> > PerformanceAll Deployments
>
> ***

> [tab] Bug fixes & stability
>
> Comprehensive bug fixes across SaaS features, Designer, and backend services.
>
> 🎨 [**Designer Fixes**](#designer-fixes) - UI and navigation fixes for Designer\
> ⚙️ [**Backend Fixes**](#backend-fixes) - Backend stability and performance improvements
>
> ### **Designer fixes**
>
> > [card] Designer fixes
> >
> > FlowX.AI 5.4.0 resolves Designer issues to improve stability and user experience.
> >
> > ## Navigation & routing
> >
> > > [accordion] Navigation fixes
> > >
> > > * **Fixed sidebar display** - sidebar menu now shows when accessing pages via URL
> > > * **Fixed subprocess navigation** - resolved 403 when navigating to subprocesses
> > > * **Fixed back navigation** - resolved 403 when going back from UI Flows page
> > > * **Fixed audit log access** - resolved errors when viewing process instance audit logs
> > > * **Fixed version history** - "Open version in new tab" now works correctly
> >
> > > [accordion] UI improvements
> > >
> > > * **Fixed default locale display** - locale now correctly shown in Version settings
> > > * **Fixed substitution calls** - resolved errors when starting processes or accessing UI Flows
> >
> > Designer StabilityAll Deployments
>
> ***
>
> ### **Backend fixes**
>
> > [card] Backend fixes
> >
> > Backend stability and performance improvements across core services.
> >
> > ## Process engine
> >
> > > [accordion] Advancing & concurrency
> > >
> > > * **Fixed stalled advancing events** - NEW entries no longer get stuck in advancing tables
> > > * **Fixed numeric overflow** - resolved overflow when sequence exceeds Integer.MAX\_VALUE
> > > * **Fixed concurrent updates** - resolved stale data errors for embedded subprocess completion
> > > * **Fixed negative counter** - resolved issue with `count_queued_events` going negative
> >
> > ## AI platform
> >
> > > [accordion] AI integration fixes
> > >
> > > * **Fixed multi-agent streaming** - streaming now works correctly for multi-agent chat
> > > * **Fixed SSE event delivery** - events are delivered individually as they complete
> >
> > ## Integration Designer
> >
> > > [accordion] Workflow & data model
> > >
> > > * **Fixed file upload multipart** - only file name is sent in multipart body, not full path
> > > * **Fixed data model duplicates** - resolved duplicate entries in mongo properties\_paths
> >
> > Backend StabilityAll Deployments
>
> ***

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.4.0](./deployment-guidelines-v5.4).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.3.0 - no breaking changes for standard deployments
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.4
>
> ### SaaS features
>
> > [!NOTE]
> >
> > The SaaS multi-tenant features introduced in this release require additional infrastructure configuration for production deployments. Contact your FlowX.AI representative for guidance on enabling SaaS capabilities.


# Deployment guidelines v5.5.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/deployment-guidelines-v5.5

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.60.0** | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 | 9.63.0 |
| **admin** | **10.53.0** | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 | 9.65.0 |
| **designer** | **10.91.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **cms-core** | **10.35.0** | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **10.25.0** | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **10.27.0** | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **10.35.0** | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **10.35.0** | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **10.35.0** | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 | 9.33.0 |
| **data-search** | **10.25.0** | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **10.31.0** | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **10.27.0** | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 | 9.24.0 |
| **integration-designer** | **10.63.0** | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 | 9.49.1 |
| **application-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **10.53.0** | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 | 9.72.0 |
| **data-sync** | **10.31.1** | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 | 9.21.0 |
| **authorization-system** | **10.42.1** | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **10.27.0** | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 | 9.21.0 |
| **email-gateway** | **10.24.0** | 10.9.0 | - | - | - | - |
| **organization-manager** | **10.19.2** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **10.68.0** | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 | 9.0.4 |
| **Android renderer** | **10.3.0** | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 | 5.1.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.1.2** | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 | 9.2.4 |
| **di-platform** | **10.2.6** | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | **TBD** | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 | 9.3.0 |
| **knowledgebase** | **TBD** | - | - | - | - | - |
| **knowledgebase-rag** | **10.2.0** | - | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.2.0** | - | - | - | - | - |
| **mcp** | **10.2.0** | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.5.0 | Keycloak | 26+ |
| 5.5.0 | Kafka | 3.8 - 3.9 |
| 5.5.0 | PostgreSQL | 16 - 17 |
| 5.5.0 | Oracle Database | 21c, 23ai |
| 5.5.0 | MongoDB | 7 - 8 |
| 5.5.0 | Redis | 7.4 - 8.0 |
| 5.5.0 | Elasticsearch | 8 - 9 |
| 5.5.0 | Angular (Web SDK) | 20 |
| 5.5.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.5.0

### Key features and updates

> [card] Chat Component Enhancements
>
> New subcomponents (reasoning, error, suggestions), display modes, and mobile support

> [card] UI Flows Improvements
>
> Process renderer component, start workflow action, and on load events

> [card] Microsoft Outlook Integration
>
> Native MS Graph data source for reading and sending Outlook emails

> [card] Send Notification Action
>
> Send emails and reply to received emails directly from processes via SMTP

> [card] Knowledge Base v2
>
> Updated Knowledge Base with audit, resource management, and improved UI

> [card] User Management Updates
>
> Password policy, DISABLED status, resend invitations, workspace environment types

## Upgrading from v5.4.0

### Breaking changes

> [!WARNING]
>
> FlowX.AI 5.5.0 introduces a **breaking change** to the default authentication mechanism across most platform services. If you rely on the default `SECURITY_TYPE` value or opaque-token introspection, action is required before upgrading.

#### Authentication mechanism change

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. This reflects a shift from opaque-token introspection to JWT-based authentication as the default security mechanism.

**Removed environment variables:**

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

**Changed default values:**

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

**Migration steps:**

**1. Update SECURITY\_TYPE if explicitly set**

If you explicitly set `SECURITY_TYPE=oauth2` in your deployment configuration, update it to `jwt-public-key` or remove it to use the new default.

**2. Remove deprecated opaque-token variables**

Remove all `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_*` variables from your Helm values, environment configs, or deployment manifests.

**3. Update service account client IDs**

Service account client IDs now follow the `flowx-{service-name}-sa` pattern (e.g., `flowx-admin-sa`, `flowx-process-engine-sa`). Update your Keycloak service account configurations accordingly.

**4. Configure the service account realm**

Add the `security.oauth2.sa-realm` property to your configuration if your service account realm differs from the default.

**5. Remove legacy OAuth2 client variables**

Remove `SECURITY_OAUTH2_REALM`, `SECURITY_OAUTH2_CLIENT_CLIENT_ID`, `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET`, and `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_*` variables from your configuration.

***

### Key changes

* **Authentication**: Default `SECURITY_TYPE` changed from `oauth2` to `jwt-public-key` (breaking change — see above)
* **Organization Manager**: New microservice for organization and tenant management
* **Chat Component**: Enhanced with new subcomponents (reasoning, error, suggestions), display modes, and mobile support
* **UI Flows**: New process renderer component, start workflow action, and on load UI event
* **Microsoft Outlook**: New MS Graph data source for Outlook email integration
* **Send Notification**: New action type for sending/replying to emails via SMTP
* **Knowledge Base v2**: Updated UI, audit trail, and resource management
* **Container Apps**: Enhanced authentication flow and landing page
* **File Upload**: Improved progress indicators, drag and drop, and large file support
* **File Encrypt/Decrypt**: New document plugin actions for file encryption and decryption
* **User Management**: Password policy updates, DISABLED status, resend invitations, workspace environment type
* **Process Variables Compare**: Monaco diff editor for comparing variable values
* **New Kafka topics**: Multiple new topics added across document-plugin, integration-designer, admin, application-manager, email-gateway, authorization-system, and notification-plugin

***

### New microservice: Organization Manager

> [!NOTE]
>
> **Available starting with FlowX.AI 5.5.0**
>
> The Organization Manager is a new microservice responsible for organization and tenant management, including user registration, organization lifecycle, and platform component health monitoring.

**Infrastructure requirements:**

| Dependency | Details |
| - | - |
| PostgreSQL | Dedicated database for organization data |
| Redis | Caching and session management |
| Kafka | Event publishing (organization events topic) |
| Keycloak/IAM | Authentication and realm management |
| SpiceDB | Authorization via CAS lib |

> [card] [Organization Manager Setup](/5.1/setup-guides/organization-manager-setup)
>
> Complete setup and configuration guide for the Organization Manager microservice

***

### New Kafka topics

FlowX.AI 5.5.0 introduces new Kafka topics across multiple services.

#### Document-plugin Kafka topics

New topics for file encryption, decryption, bulk document persistence, and UI Flow session document persistence operations.

**Input topics (document-plugin consumes from these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Triggers file decryption operations |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Triggers file encryption operations |
| `ai.flowx.plugin.document.trigger.persist.document.bulk.v1` | Triggers bulk document persistence operations |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway |

**Output topics (document-plugin publishes to these topics):**

| Topic Name | Description |
| - | - |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Results from file decryption operations |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Results from file encryption operations |
| `ai.flowx.engine.receive.plugin.document.persist.document.bulk.results.v1` | Results from bulk document persistence |
| `ai.flowx.eventsgateway.receive.document.v1` | Document upload progress notifications sent to events-gateway for SSE delivery |

#### Integration-designer Kafka topics

New topics for integration-designer in 5.5.0. Integration-designer now participates in the application sync mechanism for system and workflow resources.

> [!NOTE]
>
> The `sync.out.v1` and `correction-after-app-operation.response.v1` topics already exist since 5.1.x (used by admin). In 5.5.0, integration-designer becomes an additional producer on these shared response topics.

**New topics:**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync requests | Inbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System resource correction requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow resource correction requests | Inbound |
| `ai.flowx.build.runtime-data.v1` | Build runtime data | Outbound |
| `ai.flowx.license.usage.v1` | License usage tracking | Outbound |

**Existing topics (new producer in 5.5.0):**

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.out.v1` | Sync operation responses | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.response.v1` | Correction operation responses | Outbound |

#### Admin Kafka topics

New topics for UI flow synchronization and correction operations in 5.5.0.

> [!NOTE]
>
> The `sync.process.in.v1`, `sync.business-rule.in.v1`, `sync.reusable-template.in.v1`, `sync.out.v1`, and `correction-after-app-operation` topics for process, business-rule, and reusable-template already exist since 5.1.x. Only the UI flow topics below are new in 5.5.0.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow sync requests | Inbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Inbound |

#### Application-manager Kafka topics

New outbound topics for resource synchronization and correction of system, workflow, and UI flow resources in 5.5.0.

> [!NOTE]
>
> Application-manager already produces sync and correction topics for process, business-rule, and reusable-template since 5.1.x. The topics below extend the same mechanism to system, workflow, and UI flow resources.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.sync.system.in.v1` | System resource sync | Outbound |
| `ai.flowx.application-version.sync.workflow.in.v1` | Workflow resource sync | Outbound |
| `ai.flowx.application-version.sync.ui-flow.in.v1` | UI flow resource sync | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.system.request.v1` | System correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.workflow.request.v1` | Workflow correction requests | Outbound |
| `ai.flowx.application-version.correction-after-app-operation.ui-flow.request.v1` | UI flow correction requests | Outbound |

#### Email-gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.save.audit.v1` | Audit event logging | Outbound |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Trigger process start from email events | Outbound |

#### Authorization-system Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.organization.events.v1` | Organization lifecycle events | Outbound |

#### Notification-plugin Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.application-version.resources-usages.refresh.v1` | Resource usages refresh events | Inbound |
| `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1` | Sub-resource validation responses | Outbound |
| `ai.flowx.application-version.resources-usages.operations.bulk.v1` | Bulk resource usage operations | Outbound |

> [!NOTE]
>
> These topics are automatically created if your Kafka cluster has auto-topic creation enabled. For production environments, it is recommended to create them manually with appropriate partition counts and replication factors.

***

### New environment variables

#### Platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

#### Document-plugin variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) | document-plugin |

> [!NOTE]
>
> This setting affects all file uploads handled by the document-plugin. Configure alongside the existing Spring multipart settings (`SPRING_SERVLET_MULTIPART_MAXFILESIZE`, `SPRING_SERVLET_MULTIPART_MAXREQUESTSIZE`) for consistent upload limits. See [Documents Plugin Setup](/5.1/setup-guides/documents-plugin-setup#multipart-upload-configuration).

#### Authorization-system variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_ALLOWED_REDIRECT_URIS` | Comma-separated list of valid redirect URI patterns for the `flowx-platform-authenticate` Keycloak client. Required for new deployments. | ` ` (empty) | authorization-system |

> [!WARNING]
>
> **New deployments only**: If this variable is not set, the `flowx-platform-authenticate` Keycloak client will have no redirect URIs and OAuth2 login will fail. Set this to your Designer and app URLs (e.g., `https://designer.yourcompany.com/*,https://app.yourcompany.com/*`).
>
> Existing deployments upgrading to 5.5.0 are not affected — the Liquibase migration that uses this variable has already run.

> [card] [Authorization System Setup](/5.1/setup-guides/authorization-setup-guide#keycloak-redirect-uris)
>
> See the full redirect URI configuration details

#### Email-gateway variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` | email-gateway |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` | email-gateway |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` | email-gateway |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` | email-gateway |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per MS Graph polling cycle | `50` | email-gateway |
| `EMAIL_GATEWAY_MS_GRAPH_CLIENT_CACHE_TTL` | TTL for cached MS Graph client instances | `1d` | email-gateway |

> [!NOTE]
>
> For complete email-gateway configuration including database, Redis, and Kafka settings, see the [Email Gateway Setup](/5.9/setup-guides/email-gateway-setup) guide.

***

### Compatibility

* **Authentication**: Default `SECURITY_TYPE` changed to `jwt-public-key` — deployments using opaque-token introspection require migration (see [breaking changes](#authentication-mechanism-change))
* **Renderer Updates**: Web and mobile SDKs include new Chat component features and UI Flows enhancements
* **Database**: No schema changes required for this upgrade
* **Mobile Support**: Chat component now available on iOS and Android renderers
* **New Service**: Organization Manager requires PostgreSQL, Redis, Kafka, and Keycloak infrastructure

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/migration-overview

Migration guide for upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!WARNING]
>
> FlowX.AI v5.5.0 introduces a **critical breaking change** to the default authentication mechanism across 14 of 19 platform services. Action is required before upgrading.

## What's changing

FlowX.AI v5.5.0 changes the default authentication mechanism from opaque-token introspection (`oauth2`) to JWT-based authentication (`jwt-public-key`). This affects service-to-service communication, service account configuration in Keycloak, and multiple environment variables across the platform.

Additionally, a new microservice — **Organization Manager** — has been introduced for organization and tenant management.

## Who is affected

> [!WARNING]
>
> **All deployments** are affected by the authentication mechanism change. The default `SECURITY_TYPE` value has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services.
>
> If you explicitly set `SECURITY_TYPE=oauth2` or rely on opaque-token introspection, you **must** update your configuration before upgrading.

## Migration process

**1. Back up your configuration**

Create backups of your current Helm values, environment configurations, and Keycloak settings before making any changes.

**2. Update Keycloak service accounts**

Update your Keycloak service account client IDs to follow the new `flowx-{service-name}-sa` naming pattern. See [Update Keycloak service accounts](#update-keycloak-service-accounts) for the full mapping.

**3. Update environment variables**

Remove deprecated variables and update changed defaults. See [Update environment variables](./update-environment-variables-5.5) for a per-service breakdown.

**4. Deploy Organization Manager**

If applicable, deploy the new Organization Manager microservice. See the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup) for infrastructure requirements.

**5. Deploy and verify**

Deploy the updated configuration and verify that all services start correctly and inter-service communication works as expected.

***

## Authentication mechanism change

### Overview

The default value of `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 of 19 platform services. Opaque-token introspection has been **removed entirely**.

> [!NOTE]
>
> A new `security.oauth2.sa-realm` property has been introduced to separate the service account realm from the main authentication realm. This property is used by the token URI for inter-service communication across 11 services.

### Removed environment variables

The following environment variables have been removed and are no longer supported:

| Environment Variable | Description | Previously Used By |
| - | - | - |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI` | Opaque-token introspection endpoint | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID` | Client ID for opaque-token introspection | 14 services |
| `SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET` | Client secret for opaque-token introspection | 14 services |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_ID` | OAuth2 client ID | 13 services |
| `SECURITY_OAUTH2_CLIENT_CLIENT_SECRET` | OAuth2 client secret | 13 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account admin client ID | 8 services |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account admin client secret | 8 services |

### Changed default values

| Environment Variable | Old Default | New Default | Affected Services |
| - | - | - | - |
| `SECURITY_TYPE` | `oauth2` | `jwt-public-key` | 14/19 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID` | `${security.oauth2.service-account.admin.client-id}` | `flowx-${spring.application.name}-sa` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET` | `${security.oauth2.service-account.admin.client-secret}` | `-` | 8 services |
| `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI` | Uses `${security.oauth2.realm}` | Uses `${security.oauth2.sa-realm}` | 8 services |

***

## Update Keycloak service accounts

Service account client IDs now follow the `flowx-{service-name}-sa` pattern. Update your Keycloak configuration to match:

| Service | New Client ID |
| - | - |
| Admin | `flowx-admin-sa` |
| Process Engine | `flowx-process-engine-sa` |
| Integration Designer | `flowx-integration-designer-sa` |
| Authorization System | `flowx-authorization-system-sa` |
| Runtime Manager | `flowx-runtime-manager-sa` |
| Scheduler Core | `flowx-scheduler-core-sa` |
| Task Management Plugin | `flowx-task-management-plugin-sa` |
| Organization Manager | `flowx-organization-manager-sa` |
| License | `flowx-license-sa` |
| Email Gateway | `flowx-email-gateway-sa` |

> [!WARNING]
>
> Ensure you update both the Keycloak client IDs **and** the corresponding environment variables in your deployment configuration. Mismatches will cause service startup failures.

***

## New microservice: Organization Manager

FlowX.AI 5.5.0 introduces the **Organization Manager** microservice for organization and tenant management, user registration, and platform component health monitoring.

**Infrastructure requirements:**

* PostgreSQL
* Redis
* Kafka
* Keycloak/IAM
* SpiceDB

For full setup instructions, see the [Organization Manager Setup Guide](/5.1/setup-guides/organization-manager-setup).

***

## Backward compatibility

> [!WARNING]
>
> **No backward compatibility** for the authentication mechanism change. The opaque-token introspection mechanism has been removed entirely. You must update your configuration before or immediately after upgrading to v5.5.0.

## Rollback support

If you need to rollback from v5.5.0 to v5.4.x:

1. Revert your `SECURITY_TYPE` and environment variables to the previous configuration
2. Restore the previous Keycloak service account client IDs
3. Re-add the removed opaque-token variables if they were in use
4. Downgrade all platform service containers to their v5.4.x versions

> [!NOTE]
>
> Ensure you have database backups before any upgrade. Schema changes introduced by Organization Manager are not automatically reversed on rollback.

***

## Additional resources

> [card] [Update Environment Variables](./update-environment-variables-5.5)
>
> Per-service environment variable changes for v5.5.0

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions and deployment instructions

> [card] [IAM Configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution)
>
> Keycloak setup and service account configuration

> [card] [Release Notes v5.5.0](../v5.5.0-february-2026)
>
> Full release notes for v5.5.0

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or migration questions, contact your FlowX.AI support representative.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/migrating-from-v5.4-to-v5.5/update-environment-variables-5.5

Environment variable changes when upgrading from FlowX.AI v5.4.0 to v5.5.0

> [!NOTE]
>
> This page details environment variable changes required for the v5.4.0 to v5.5.0 upgrade. For the full migration context, see the [Migration Overview](./migration-overview).

## Authentication variables (all affected services)

The following changes apply to **14 of 19 platform services** as part of the authentication mechanism change from `oauth2` to `jwt-public-key`.

### Variables to remove

Remove these variables from your Helm values, environment configs, or deployment manifests:

```yaml theme={"dark"}
# Opaque-token introspection (removed entirely)
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_INTROSPECTION_URI:  # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_ID:          # REMOVE
SPRING_SECURITY_OAUTH2_RESOURCE_SERVER_OPAQUE_TOKEN_CLIENT_SECRET:      # REMOVE

# Legacy OAuth2 client variables
SECURITY_OAUTH2_REALM:                                                   # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_ID:                                        # REMOVE
SECURITY_OAUTH2_CLIENT_CLIENT_SECRET:                                    # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID:                         # REMOVE
SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET:                     # REMOVE
```

### Variables to update

> [tab] Before (v5.4)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "oauth2"
>
> # Service account client ID (example for admin service)
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "${security.oauth2.service-account.admin.client-id}"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "${security.oauth2.service-account.admin.client-secret}"
>
> # Token URI using main realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token"
> ```

> [tab] After (v5.5)
>
> ```yaml theme={"dark"}
> SECURITY_TYPE: "jwt-public-key"
>
> # Service account client ID follows flowx-{service-name}-sa pattern
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_ID: "flowx-admin-sa"
> SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENT_SECRET: "{your-client-secret}"
>
> # Token URI now uses separate sa-realm
> SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_MAINAUTHPROVIDER_TOKEN_URI: "${security.oauth2.base-server-url}/realms/${security.oauth2.sa-realm}/protocol/openid-connect/token"
> ```

***

## New platform-wide variables

The following new environment variables are available across multiple services:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum Kafka producer message size in bytes | `52428800` (50 MB) | process-engine, admin, application-manager, integration-designer, events-gateway, email-gateway, notification-plugin, document-plugin |
| `REDIS_TTL` | Redis cache time-to-live in milliseconds | `5000000` | admin, application-manager, cms-core, integration-designer, task-management-plugin, notification-plugin |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID for Kafka SASL authentication | `kafka` | events-gateway, email-gateway, notification-plugin, document-plugin |
| `LOGGING_LEVEL_APP` | Application-specific logging level | `INFO` | Most services (12/19) |
| `LOGGING_LEVEL_OAUTH2_EXC` | OAuth2 autoconfiguration exception logging level | `OFF` | Most services (12/19) |
| `LOGGG_LEVEL_MONGO_DRIVER` | MongoDB driver logging level | `INFO` | admin, application-manager, cms-core |

***

## Document plugin

| Environment Variable | Description | Default Value |
| - | - | - |
| `MULTIPART_MAX_ENTITY_SIZE` | Maximum size for multipart uploads at server level | `52428800` (50 MB) |

***

## Email gateway

> [!NOTE]
>
> **New in 5.5.0** — The email gateway service supports IMAP polling for email triggers. The following variables control polling behavior and load balancing.

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAIL_GATEWAY_IMAP_CONNECTION_TIMEOUT` | IMAP server connection timeout in milliseconds | `10000` |
| `EMAIL_GATEWAY_IMAP_MAX_CONCURRENT_POLLS` | Maximum number of concurrent IMAP polling operations | `30` |
| `EMAIL_GATEWAY_IMAP_MAX_MESSAGES_PER_POLL` | Maximum messages to fetch per polling cycle | `50` |
| `EMAIL_GATEWAY_IMAP_POLLING_INTERVAL` | Interval between IMAP polling cycles in seconds | `30` |
| `EMAIL_GATEWAY_IMAP_READ_TIMEOUT` | IMAP read timeout in milliseconds | `30000` |
| `EMAIL_GATEWAY_MASTER_ELECTION_CRON` | Cron expression for master election checks | `*/5 * * * * *` |
| `EMAIL_GATEWAY_MASTER_ELECTION_TTL` | Master election TTL in seconds | `15` |
| `EMAIL_GATEWAY_MAX_EMAILS_PER_INSTANCE` | Maximum email accounts per service instance for load balancing | `100` |
| `EMAIL_GATEWAY_REBALANCING_CRON` | Cron expression for email account rebalancing | `*/30 * * * * *` |
| `EMAIL_GATEWAY_STALE_TIMEOUT_SECONDS` | Timeout in seconds before marking an instance as stale | `90` |

***

## Additional resources

> [card] [Migration Overview](./migration-overview)
>
> Full migration guide with Keycloak and service account changes

> [card] [Deployment Guidelines v5.5.0](../deployment-guidelines-v5.5)
>
> Component versions, Kafka topics, and infrastructure requirements


# FlowX.AI 5.5.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.5.0-february-2026/v5.5.0-february-2026

Enhanced Chat component, UI Flows improvements, Microsoft Outlook integration, container app authentication, and platform management updates.

> [!NOTE]
>
> FlowX.AI 5.5.0 introduces significant enhancements to the Chat component, UI Flows capabilities, email integrations, and platform management features including Knowledge Base v2, user management improvements, and new document processing capabilities.

![Data Source types in FlowX 5.5.0](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.5/ds_type_selector_all.png)

**What's new?**

> [tab] AI Platform
>
> AI-powered features and document processing enhancements.
>
> 📄 [**Extract Data from File**](#extract-data-from-file) - Configurable document and image extraction with LLM, OCR, and text parsing strategies\
> 📚 [**Knowledge Base v2**](#knowledge-base-v2) - Updated Knowledge Base with audit, resource management, and improved UI
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 renames "Extract Text from Document" to **Extract Data from File** and adds configurable extraction strategies, image input support, and signature detection. Choose between LLM, OCR, or text parsing strategies based on your document types, accuracy requirements, and cost constraints.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Extraction strategies
> > > >
> > > > Choose between LLM Model, OCR Engine, or Text Parsing for optimal accuracy/cost balance
> > >
> > > > [card] Image support
> > > >
> > > > Process images (JPG, PNG, TIFF) in addition to documents — automatic PDF conversion
> > >
> > > > [card] Image extraction options
> > > >
> > > > Extract data from embedded images or generate image descriptions
> > >
> > > > [card] Signature detection
> > > >
> > > > Detect and locate signatures within documents (LLM and OCR modes)
> >
> > > [tab] Configuration
> > >
> > > **Extraction strategies:**
> > >
> > > | Strategy | Best for | Speed | Cost | Accuracy |
> > > | - | - | - | - | - |
> > > | LLM Model | Complex layouts, handwritten text | Slow | High | High |
> > > | OCR Engine | Scanned documents | Medium | Medium | Medium |
> > > | Text Parsing | Clean digital PDFs | Fast | Free | Low–Medium |
> > >
> > > **Image extraction options (LLM and OCR only):**
> > >
> > > | Option | Description |
> > > | - | - |
> > > | Image Description | Generates text descriptions of images |
> > > | Image Content | Extracts text and data from images |
> > >
> > > > [!TIP]
> > > >
> > > > A new [Document Parser setup guide](/5.9/setup-guides/document-parser-setup) covers backend service configuration, deployment sizing, and cost optimization.
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Knowledge Base v2**
>
> > [card] [Knowledge Base v2](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 updates the Knowledge Base with a refreshed UI, audit capabilities, and improved resource management. Knowledge Base entries now support versioning and provide better traceability for AI-powered features.
> >
> > > [tab] Key Features
> > >
> > > > [card] Updated UI
> > > >
> > > > Refreshed Knowledge Base interface with improved navigation and search
> > >
> > > > [card] Audit trail
> > > >
> > > > Track changes to Knowledge Base entries with full audit history
> > >
> > > > [card] Resource management
> > > >
> > > > Improved management of Knowledge Base resources and documents
> > >
> > > > [card] Version tracking
> > > >
> > > > Version-aware Knowledge Base entries tied to app versions
> >
> > AI IntegrationAll Deployments
>
> ***

> [tab] UI Flows
>
> Enhanced UI Flows with new components, actions, and chat improvements.
>
> 💬 [**Chat Component Enhancements**](#chat-component-enhancements) - New subcomponents, display modes, and mobile support\
> 🧭 [**UI Flows Breadcrumbs**](#ui-flows-breadcrumbs) - Navigation breadcrumbs for UI Flows\
> 📄 [**Process Renderer Component**](#process-renderer-component) - Embed process renderers within UI Flows\
> 🚀 [**Start Workflow Action**](#start-workflow-action) - Start workflows directly from UI Flows\
> ⚡ [**On Load UI Event**](#on-load-ui-event) - Execute actions when UI Flows load
>
> ### **Chat component enhancements**
>
> > [card] [Chat component enhancements](/5.9/ai-platform/chat-component)
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 significantly enhances the Chat component with new subcomponents for reasoning, error handling, and suggestions. The component now supports multiple display modes and is available on mobile platforms.
> >
> > > [tab] New Subcomponents
> > >
> > > > [card] Reasoning display
> > > >
> > > > Show AI reasoning and thought process to users for transparency
> > >
> > > > [card] Error handling
> > > >
> > > > Graceful error display with retry options and helpful messages
> > >
> > > > [card] Suggestions
> > > >
> > > > Display suggested responses or actions to guide user interactions
> >
> > > [tab] Display Modes
> > >
> > > **Available display modes:**
> > >
> > > | Mode | Description |
> > > | - | - |
> > > | **Full screen** | Chat occupies the entire screen (available since v5.4.0) |
> > > | **Sidebar** | Chat appears as a collapsible sidebar |
> > > | **Floating** | Chat appears as a floating widget |
> > > | **Embedded** | Chat embedded within a container component |
> >
> > > [tab] Mobile Support
> > >
> > > The Chat component is now fully supported on mobile platforms:
> > >
> > > > [card] iOS
> > > >
> > > > Native iOS renderer support with optimized touch interactions
> > >
> > > > [card] Android
> > > >
> > > > Native Android renderer support with material design integration
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **UI Flows breadcrumbs**
>
> > [card] [UI Flows breadcrumbs](/5.9/docs/building-blocks/ui-flows#breadcrumbs)
> >
> > FlowX.AI 5.5.0 enhances the breadcrumbs navigation component for UI Flows, providing users with clear context of their current location and enabling quick navigation to parent screens.
> >
> > > [card] Navigation path
> > >
> > > Display the full navigation path within UI Flows
> >
> > > [card] Click navigation
> > >
> > > Navigate to any parent screen by clicking breadcrumb items
> >
> > > [card] Theme configuration
> > >
> > > Customize breadcrumb appearance through Admin theme settings
> >
> > > [card] Responsive design
> > >
> > > Breadcrumbs adapt to different screen sizes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process renderer component**
>
> > [card] [Process renderer component](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > > [tab] Overview
> > >
> > > Embed process renderers directly within UI Flows using the new Process Renderer component. This enables hybrid applications that combine UI Flow navigation with traditional process-based screens.
> >
> > > [tab] Key Features
> > >
> > > > [card] Process embedding
> > > >
> > > > Embed any process renderer within a UI Flow screen
> > >
> > > > [card] Data passing
> > > >
> > > > Pass data between UI Flows and embedded processes
> > >
> > > > [card] Event handling
> > > >
> > > > Handle process events within the UI Flow context
> > >
> > > > [card] Consistent styling
> > > >
> > > > Maintain consistent styling and navigation across UI Flows and processes
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Start workflow action**
>
> > [card] [Start workflow action](/5.9/docs/building-blocks/ui-flows#configuring-the-start-workflow-action)
> >
> > > [tab] Overview
> > >
> > > Start integration workflows directly from UI Flows using the new Start Workflow action. This enables UI Flows to trigger backend workflows without requiring a full process instance.
> >
> > > [tab] Key Features
> > >
> > > > [card] Workflow selection
> > > >
> > > > Select from available integration workflows
> > >
> > > > [card] Input mapping
> > > >
> > > > Map UI Flow data to workflow input parameters
> > >
> > > > [card] Response handling
> > > >
> > > > Handle workflow responses and update UI state
> > >
> > > > [card] Error handling
> > > >
> > > > Configure error handling for failed workflow executions
> >
> > UI EnhancementAll Deployments
>
> ### **On load UI event**
>
> > [card] [On load UI event](/5.9/docs/building-blocks/ui-designer/event-handlers#triggers)
> >
> > > [tab] Overview
> > >
> > > Execute actions automatically when UI Flow screens load using the new On Load UI Event. This enables initialization logic, data fetching, and setup operations when users navigate to a screen.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic execution
> > > >
> > > > Actions execute automatically when the screen loads
> > >
> > > > [card] Data initialization
> > > >
> > > > Fetch and initialize data when entering a screen
> > >
> > > > [card] Conditional logic
> > > >
> > > > Execute different actions based on conditions
> > >
> > > > [card] Loading states
> > > >
> > > > Manage loading states during initialization
> >
> > UI EnhancementAll Deployments
>
> ***

> [tab] Integrations
>
> Email integrations, document processing, and Integration Designer updates.
>
> 📬 [**Microsoft Outlook Data Source**](#microsoft-outlook-data-source) - Native MS Graph integration for reading and sending Outlook emails\
> 📧 [**Send Notification Action**](#send-notification-action) - Send emails and reply to received emails directly from processes\
> 🔌 [**Integration Designer Improvements**](#integration-designer-improvements) - Query parameter encoding, config param autocomplete\
> 🔑 [**Security Details in Workflows**](#security-details-in-workflows) - Access user security details in workflow scripts\
> 🔐 [**File Encrypt and Decrypt**](#file-encrypt-and-decrypt) - Encrypt and decrypt files in the Documents Plugin
>
> ### **Microsoft Outlook data source**
>
> > [card] Microsoft Outlook data source
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces a new **Microsoft Outlook** data source type that connects to Outlook mailboxes via the Microsoft Graph API. Unlike Email Trigger (IMAP) and Email Sender (SMTP), this provides a unified data source for both reading and sending emails through native Outlook integration with Azure AD authentication.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> > > >
> > > > See the complete Microsoft Outlook data source documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Unified read & send
> > > >
> > > > Single data source supports Read Emails, Send Emails, or Read & Send Emails scopes
> > >
> > > > [card] Azure AD authentication
> > > >
> > > > Service account authentication with Tenant ID, Client ID, and Client Secret
> > >
> > > > [card] Email monitoring
> > > >
> > > > Monitor Outlook mailboxes and trigger processes automatically when emails arrive
> > >
> > > > [card] Send & reply
> > > >
> > > > Send new emails or reply to received emails with conversation thread support
> > >
> > > > [card] Attachment validations
> > > >
> > > > Configure allowed file types, max file size, and max file count for incoming emails
> > >
> > > > [card] Test connection
> > > >
> > > > Validate Azure AD credentials and MS Graph permissions before saving
> >
> > > [tab] Configuration
> > >
> > > **Azure AD Authentication:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Tenant ID | Azure AD tenant ID |
> > > | Client ID | Azure AD application (client) ID |
> > > | Client Secret | Azure AD client secret |
> > >
> > > **Scope Options:**
> > >
> > > | Scope | MS Graph Permissions Required |
> > > | - | - |
> > > | Read Emails | `Mail.Read`, `Mail.ReadBasic`, or `Mail.ReadWrite` |
> > > | Send Emails | `Mail.Send` or `Mail.ReadWrite` |
> > > | Read & Send Emails | One read + one send permission |
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Send Notification action**
>
> > [card] Send Notification action
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 introduces the Send Notification action — a new action type that sends emails directly from process nodes through SMTP, without routing through Kafka. Combined with the new Email Sender data source type, it enables processes to send new emails or reply to emails that triggered the process via Email Trigger.
> > >
> > > > [!NOTE]
> > > >
> > > > Existing notification templates configured for Kafka-based sending continue to work without modification.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> > > >
> > > > See the complete Send Notification action documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Email Sender data source
> > > >
> > > > New SMTP data source type in Integration Designer with SSL/TLS smart port defaults
> > >
> > > > [card] Reply to emails
> > > >
> > > > Reply to emails that triggered the process, maintaining conversation threads
> > >
> > > > [card] Send new emails
> > > >
> > > > Send new outbound emails to specified recipients with CC/BCC support
> > >
> > > > [card] Notification template updates
> > > >
> > > > New Email Server and Email Sender fields for direct SMTP delivery
> > >
> > > > [card] Attachments
> > > >
> > > > Attach files using static paths or process variable keys
> > >
> > > > [card] Backwards compatible
> > > >
> > > > Existing Kafka-based notification templates continue to work unchanged
> >
> > > [tab] Configuration
> > >
> > > **Email Sender Data Source (new):**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Protocol | SMTP (only option) |
> > > | Server Host | SMTP server hostname |
> > > | SSL/TLS | Enable secure connection (default: on) |
> > > | Port | `587` (SSL/TLS on) or `465` (SSL/TLS off) |
> > > | Username | Email account username |
> > > | Password | Email account password |
> > >
> > > **Send Notification Action:**
> > >
> > > | Field | Description |
> > > | - | - |
> > > | Notification Template | Select a template with Predefined Email Connection |
> > > | Reply to received emails | Toggle on to reply to the email that triggered the process |
> > > | Reply to Email Header | Process variable with original email headers (reply mode) |
> > > | Receivers | Recipient email addresses or process variables |
> > > | CC/BCC Receivers | Optional CC and BCC recipients |
> > > | Language | Process variable key for template language |
> > > | Attachments | File path or process variable key |
> > > | Template Data | JSON key-value pairs for dynamic template content |
> > >
> > > > [!TIP]
> > > >
> > > > Available on Send Message Task, Task, and User Task nodes.
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Integration Designer improvements**
>
> > [card] Integration Designer improvements
> >
> > FlowX.AI 5.5.0 adds URL encoding options for REST endpoint query parameters, improved error handling for invalid REST responses, and configuration parameter autocomplete in data source forms.
> >
> > > [card] Query parameter encoding
> > >
> > > Configure whether query parameter values are URL-encoded automatically or sent as-is (for pre-encoded values)
> >
> > > [card] REST Content-Type handling
> > >
> > > Improved error handling when REST endpoints return responses with unexpected Content-Type headers
> >
> > > [card] Config param autocomplete
> > >
> > > Type `$` in data source configuration fields to autocomplete configuration parameters or create new ones inline
> >
> > > [!NOTE]
> > >
> > > See [Integration Designer - Query parameters](/5.1/docs/platform-deep-dive/integrations/integration-designer#query-parameters) for details.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Security details in workflows**
>
> > [card] Security details in workflows
> >
> > Workflow scripts can now access `additionalData.securityDetails` to retrieve the current user's identity. This works when a workflow is started from a **Chat component**, a **UI Flow**, or a **manual run**. Sub-workflows inherit security details from their parent.
> >
> > Unlike processes, where security details are grouped by swimlane and role, workflows use a simplified flat structure:
> >
> > ```json theme={"dark"}
> > {
> >   "securityDetails": {
> >     "username": "user@email.com",
> >     "identifier": "keycloak-subject-id",
> >     "details": {
> >       "firstName": "John",
> >       "lastName": "Snow",
> >       "email": "user@email.com"
> >     }
> >   }
> > }
> > ```
> >
> > > [!NOTE]
> > >
> > > See [Extracting additional data in business rules](/5.1/docs/building-blocks/actions/business-rule-action/extracting-additional-data) for full details and code examples for both processes and workflows.
> >
> > New FeatureAll Deployments
>
> ***
>
> ### **File encrypt and decrypt**
>
> > [card] [File encrypt and decrypt](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/encrypting-decrypting-files)
> >
> > FlowX.AI 5.5.0 adds new file encryption and decryption actions to the Documents Plugin, enabling processes to encrypt files before storage and decrypt them for authorized access.
> >
> > > [card] File encryption
> > >
> > > Encrypt files using configurable encryption algorithms before storage
> >
> > > [card] File decryption
> > >
> > > Decrypt files for authorized access within process flows
> >
> > InfrastructureAll Deployments
>
> ***

> [tab] Platform & Management
>
> User management, workspace configuration, rendering, and platform improvements.
>
> 🔐 [**Container App Authentication**](#container-app-authentication) - Authentication flow and landing page improvements\
> 🔑 [**Password Policy Updates**](#password-policy-updates) - Updated password complexity requirements\
> 🚫 [**User status DISABLED**](#user-status-disabled) - New DISABLED status for user accounts\
> 📧 [**Resend User Invitation**](#resend-user-invitation) - Resend invitations for pending users\
> 🏷️ [**Workspace Environment Type**](#workspace-environment-type) - Sandbox, Staging, and Production labels for workspaces\
> 🏢 [**Organization ID Propagation**](#organization-id-propagation) - Enhanced multi-tenant isolation\
> ⚡ [**Rendering Runtime UX**](#rendering-runtime-ux) - Runtime UX improvements for rendering\
> 🔍 [**Process Variables Compare**](#process-variables-compare) - Monaco diff editor for process variable values\
> 📧 [**Failed Email Trigger Details Page**](#failed-email-trigger-details-page) - Dedicated details page for failed email triggers\
> 📐 [**Data Model Sidepanel**](#data-model-sidepanel) - Redesigned attribute settings, inline add, and path copy
>
> ### **Container app authentication**
>
> > [card] [Container app authentication](/5.9/docs/saas/container-app-authentication)
> >
> > > [tab] Overview
> > >
> > > Enhanced authentication flow and landing page for generic container applications. Configure authentication providers, customize login pages, and manage user sessions with improved security and user experience.
> >
> > > [tab] Key Features
> > >
> > > > [card] Authentication providers
> > > >
> > > > Support for multiple authentication providers
> > >
> > > > [card] Custom landing page
> > > >
> > > > Customize the landing page for unauthenticated users
> > >
> > > > [card] Session management
> > > >
> > > > Improved session handling and token refresh
> > >
> > > > [card] SSO integration
> > > >
> > > > Seamless single sign-on integration
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Password policy updates**
>
> > [card] [Password policy updates](/5.1/setup-guides/access-management/configuring-an-iam-solution#password-policy)
> >
> > FlowX.AI 5.5.0 updates the password policy with stricter complexity requirements for improved security.
> >
> > **New requirements:**
> >
> > | Rule | Value |
> > | - | - |
> > | Minimum length | 8 characters |
> > | Maximum length | 64 characters |
> > | Complexity | Must include uppercase, lowercase, number, and special character |
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **User status DISABLED**
>
> > [card] [User status DISABLED](/5.9/docs/saas/inviting-users#user-statuses)
> >
> > FlowX.AI 5.5.0 introduces a new **DISABLED** user status. Administrators can now enable or disable user accounts through the **Enable** and **Disable** actions in the user management menu, providing better control over user access without deleting accounts.
> >
> > InfrastructureAll Deployments
>
> ***
>
> ### **Resend user invitation**
>
> > [card] [Resend user invitation](/5.9/docs/saas/inviting-users#resending-invitations)
> >
> > FlowX.AI 5.5.0 adds the ability to resend invitations for users with a **Pending** status, ensuring users who missed or lost their initial invitation can still complete onboarding.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Workspace environment type**
>
> > [card] [Workspace environment type](/5.1/docs/projects/workspaces#workspace-environment-type)
> >
> > FlowX.AI 5.5.0 adds an **Environment Type** dropdown to workspace configuration, allowing administrators to label workspaces as **Sandbox**, **Staging**, or **Production**. This provides clearer context when working across multiple environments.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Organization ID propagation**
>
> > [card] Organization ID Propagation
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 enhances multi-tenant isolation by propagating organization ID across more runtime contexts. This improves audit trails and ensures proper resource scoping per organization in SaaS deployments.
> >
> > > [tab] Key Changes
> > >
> > > > [card] Scheduler execution
> > > >
> > > > Organization ID added to scheduled job context
> > >
> > > > [card] Event listeners
> > > >
> > > > Organization ID propagated to event handlers
> > >
> > > > [card] Process instances
> > > >
> > > > Organization ID captured from initiator
> > >
> > > > [card] Audit trail
> > > >
> > > > Enhanced audit logging with organization context
> >
> > InfrastructureSaaS
>
> ***
>
> ### **Rendering runtime UX**
>
> > [card] Rendering runtime UX
> >
> > FlowX.AI 5.5.0 includes various rendering runtime UX improvements for better performance and user experience.
> >
> > > [card] Loading states
> > >
> > > Improved loading state indicators and skeleton screens
> >
> > > [card] Transition animations
> > >
> > > Smoother transitions between screens and states
> >
> > > [card] Error boundaries
> > >
> > > Better error handling with graceful degradation
> >
> > > [card] Performance
> > >
> > > Optimized rendering performance for complex UIs
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Process variables compare**
>
> > [card] [Process variables compare](/5.9/docs/projects/runtime/active-process/update-process-variables#compare-view)
> >
> > FlowX.AI 5.5.0 introduces a Monaco diff editor for comparing process variable values, making it easier to identify changes between versions or states.
> >
> > > [card] Diff editor
> > >
> > > Side-by-side comparison of process variable values using Monaco diff editor
> >
> > > [card] Version comparison
> > >
> > > Compare variable values across different process versions
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Failed email trigger details page**
>
> > [card] [Failed email trigger details page](/5.9/docs/platform-deep-dive/integrations/email-trigger#failed-trigger-details-page)
> >
> > FlowX.AI 5.5.0 adds a dedicated details page for failed email triggers, providing better visibility into email processing failures and enabling faster troubleshooting.
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### **Data Model sidepanel**
>
> > [card] Data Model sidepanel
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.5.0 redesigns the Data Model editing experience with a new attribute settings side panel, inline add-attribute buttons, and attribute path display. These improvements make it faster to create, configure, and reference data model attributes without switching between menus.
> > >
> > > > [card] [Process Data Model](/5.1/docs/building-blocks/process/data-model#data-model-interface)
> > > >
> > > > See the updated Process Data Model documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Attribute settings side panel
> > > >
> > > > Select any attribute to open a settings panel with type, validations, sensitive data, and reporting options
> > >
> > > > [card] Inline add attribute
> > > >
> > > > Add attributes directly on each data type — button shows on hover after the first attribute
> > >
> > > > [card] Attribute path copy
> > > >
> > > > View and copy the full key path for any attribute for use in business rules and UI bindings
> > >
> > > > [card] Selection highlights
> > > >
> > > > Selecting a data type or connector highlights its location on the canvas
> > >
> > > > [card] Default minimized panel
> > > >
> > > > The Data Types panel starts minimized by default for a cleaner canvas view
> > >
> > > > [card] Confirmation toasts
> > > >
> > > > Success notifications when adding new data types
> >
> > UI EnhancementAll Deployments
>
> ***
>
> ### Additional improvements
>
> * **Workflow logs milliseconds** — Workflow execution logs now display timestamps with millisecond precision
> * **Single select in table edit** — SDK enhancement for single-select dropdowns within editable table cells. See [Table component](/5.1/docs/building-blocks/ui-designer/ui-component-types/table#editable-rows)
> * **UI Flows action name optional** — Action names in UI Flows are now optional, reducing configuration overhead
> * **Data mappers editable JSON testing** — Improved JSON testing experience in data mappers with editable input fields
> * **Solutions page load optimization** — Solutions page now loads only projects, improving performance for container apps
> * **Security patches** — General security improvements across platform services

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, component versions, and upgrade instructions, see the [Deployment Guidelines v5.5.0](./deployment-guidelines-v5.5).
>
> ### Compatibility
>
> > [!WARNING]
> >
> > **Breaking change:** The default `SECURITY_TYPE` has changed from `oauth2` to `jwt-public-key` across 14 services. Opaque-token introspection has been removed. See the [Deployment Guidelines](./deployment-guidelines-v5.5#breaking-changes) for migration steps.
>
> > [card] Upgrade path
> >
> > Upgrade from v5.4.0 — requires authentication mechanism migration (`SECURITY_TYPE` change)
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.5


# Deployment guidelines v5.6.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/deployment-guidelines-v5.6

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.77.0** | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 | 9.64.3 |
| **admin** | **10.66.0** | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 | 9.66.5 |
| **designer** | **10.127.3** | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **cms-core** | **10.43.0** | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 | 9.36.3 |
| **scheduler-core** | **10.31.0** | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 | 9.26.1 |
| **events-gateway** | **10.33.1** | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 | 9.26.1 |
| **notification-plugin** | **10.42.1** | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 | 9.29.1 |
| **document-plugin** | **10.46.0** | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 | 9.35.1 |
| **task-management-plugin** | **10.41.1** | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 | 9.34.2 |
| **data-search** | **10.30.1** | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 | 9.23.1 |
| **audit-core** | **10.40.0** | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 | 9.30.1 |
| **advancing-controller** | **10.33.1** | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 | 9.25.1 |
| **integration-designer** | **10.84.0** | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 | 9.50.0 |
| **application-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **runtime-manager** | **10.69.1** | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 | 9.73.6 |
| **data-sync** | **10.38.0** | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 | 9.22.1 |
| **authorization-system** | **10.51.0** | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 | 9.34.2 |
| **nosql-db-runner** | **10.34.0** | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 | 9.22.1 |
| **email-gateway** | **10.32.1** | 10.24.0 | 10.9.0 | - | - | - |
| **organization-manager** | **10.26.1** | 10.19.2 | - | - | - | - |
| **webhook-gateway** | **10.1.1** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-sdk** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **@flowx/core-theme** | **10.127.3** | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 | 9.159.5 |
| **iOS renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.5 |
| **Android renderer** | **10.3.0** | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 | 9.0.3 |

### Plugins

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 | 5.1.1 |
| - | - | - | - | - | - | - |
| **ai-assistant** | **10.2.3** | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 | 9.2.5 |
| **di-platform** | **10.3.0** | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 | 9.3.1 |
| **ai-platform-ai-developer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-connected-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-knowledge-graph** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agents** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-conversations** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-models** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-tenants** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-planner** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-analyst** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-ai-designer** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-agent-builder** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **ai-platform-binaries** | **10.6.0** | TBD | 10.1.3 | 10.1.3 | 10.0.1 | 9.4.2 |
| **knowledgebase** | **10.6.0** | TBD | - | - | - | - |
| **knowledgebase-rag** | **10.6.0** | 10.2.0 | - | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.0** | 10.2.0 | - | - | - | - |
| **mcp** | **10.6.0** | 10.2.0 | - | - | - | - |
| **doc-converter** | **10.2.2** | - | - | - | - | - |
| **doc-parser** | **10.5.1** | - | - | - | - | - |

> [!NOTE]
>
> **New in 5.6.0:** `webhook-gateway` is a new microservice for processing incoming webhooks. It handles webhook event ingestion and routing to process instances.

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.6.0 | Keycloak | 26+ |
| 5.6.0 | Kafka | 3.8 - 3.9 |
| 5.6.0 | PostgreSQL | 16 - 17 |
| 5.6.0 | Oracle Database | 21c, 23ai |
| 5.6.0 | MongoDB | 7 - 8 |
| 5.6.0 | Redis | 7.4 - 8.0 |
| 5.6.0 | Angular (Web SDK) | 20 |
| 5.6.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

## New in v5.6.0

### Key features and updates

> [card] Chat Driven Workflows
>
> Multi-turn AI conversations with session memory and intent classification

> [card] Incoming Webhooks
>
> Trigger processes from external HTTP POST requests via the new webhook-gateway service

> [card] Web Page Extractor
>
> Collect readable content from web page URLs with crawling and link following

> [card] Proxy Server Connections
>
> Route integration traffic through HTTP/HTTPS proxy servers

> [card] UI Flow Route Management
>
> Query parameters, route maps, and breadcrumb navigation for UI Flows

> [card] MCP Authentication
>
> BEARER and BASIC auth for MCP server connections

## Upgrading from v5.5.0

### Breaking changes

#### WorkspaceCreatedEvent ownership change

> [!WARNING]
>
> The `WorkspaceCreatedEvent` Kafka topic ownership has moved from `authorization-system` to `organization-manager`.

**What changed:**

* `organization-manager` now produces `WorkspaceCreatedEvent` messages
* `authorization-system` no longer produces these events
* Update your Kafka topic ACLs if you manage topic-level permissions

***

#### gRPC thread pool configuration

> [!WARNING]
>
> The default gRPC client thread pool sizes in AI Platform have been updated. Review your deployment configuration if you have custom thread pool settings.

***

### New environment variables

#### Integration Designer

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_WEBHOOKS_BASE_URL` | Base URL for webhook-gateway service communication | `http://webhook-gateway:80` | integration-designer |
| `FLOWX_WEB_CRAWLER_BASE_URL` | Base URL for the web-crawler service (Web Page Extractor node) | `http://web-crawler:80` | integration-designer |

#### NoSQL DB Runner

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_MONGO_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum number of cached external MongoDB connections | `100` | nosql-db-runner |
| `FLOWX_MONGO_CONNECTIONS_CACHE_TTL` | Time-to-live for cached external MongoDB connections | `1d` | nosql-db-runner |

#### Process Engine

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts for failed operations | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Base delay between retries (ms) | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum delay between retries (ms) | `200` | process-engine |

#### Authorization System

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD` | Initial password for default realm admin user | *(none)* | authorization-system |
| `SPRING_LIQUIBASE_PARAMETERS_DEFAULT_REALM_ADMIN_INITIAL_PASSWORD_IS_TEMPORARY` | Force password change on first login | `true` | authorization-system |

#### Application Manager

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_RESOURCE_ID_FIELD` | Resource ID field for proxy connection merge | `resourceId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_ID_FIELDS` | Flatten map ID fields for proxy connection merge | `resourceId, name` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_FLATTENMAP_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection flatten map | `authorization.configuration` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_COMPARE_REMOVED_JSON_PATHS` | Excluded JSON paths when comparing removed proxy connections | `resourceId, resourceDefinitionId` | application-manager |
| `FLOWX_APPLICATION_MERGE_RESOURCES_PROXY_CONNECTION_CONFLICT_EXCLUDED_JSON_PATHS` | Excluded JSON paths for proxy connection conflict detection | `resourceId, resourceDefinitionId` | application-manager |

#### Data Search

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | data-search |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | data-search |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | data-search |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | data-search |

#### Email Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` | email-gateway |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` | email-gateway |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | - (required) | email-gateway |
| `FLOWX_LIB_CAS_CLIENT_SERVICES_AUTHORIZATION_SYSTEM_BASE_URL` | Authorization system base URL for CAS client | `http://authorization-system:80` | email-gateway |

> [!NOTE]
>
> The SpiceDB and CAS client variables for `data-search` and `email-gateway` are required for authorization integration. These services now use the same SpiceDB-based authorization as other platform services.

#### Webhook Gateway

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_DATASOURCE_URL` | JDBC connection URL for webhook registrations database | `jdbc:postgresql://postgresql:5432/webhook_gateway` | webhook-gateway |
| `SPRING_DATASOURCE_USERNAME` | Database username | `flowx` | webhook-gateway |
| `SPRING_DATASOURCE_PASSWORD` | Database password | *(required)* | webhook-gateway |
| `SECURITY_OAUTH2_BASE_SERVER_URL` | OAuth2/OIDC server base URL | — | webhook-gateway |
| `SECURITY_OAUTH2_REALM` | OAuth2 realm name | — | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_ID` | Service account client ID | `flowx-webhook-gateway-sa` | webhook-gateway |
| `SECURITY_OAUTH2_SERVICE_ACCOUNT_ADMIN_CLIENT_SECRET` | Service account client secret | *(required)* | webhook-gateway |
| `KAFKA_TOPIC_PROCESS_START_OUT` | Kafka topic for process start events | `ai.flowx.core.trigger.start-for-event.process.v1` | webhook-gateway |

> [!NOTE]
>
> `webhook-gateway` is a **new microservice** in 5.6.0. It requires its own PostgreSQL database (`webhook_gateway`), Kafka access, Keycloak service account (`flowx-webhook-gateway-sa`), and SpiceDB connectivity.

***

### New Kafka topics

#### Document Plugin

New topic for UI Flow session document persistence.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | Triggers UI Flow session document persistence; result delivered via SSE through events-gateway | Inbound |
| `ai.flowx.eventsgateway.receive.document.v1` | Document events sent to events-gateway for SSE delivery | Outbound |

#### Webhook Gateway Kafka topics

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | Triggers process starts from incoming webhook events | Outbound |

> [!NOTE]
>
> The Webhook Gateway is a **producer-only** service — it receives HTTP webhook requests and publishes process start events to Kafka. It does not consume from any Kafka topics.

#### UI flow session variable updates

New topic for propagating document upload results and workflow completion results to the process-engine, which updates UI flow session variables.

| Topic Name | Description | Direction |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | UI flow session variable updates after document upload or workflow completion | Inbound (process-engine) / Outbound (document-plugin, integration-designer) |

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `KAFKA_TOPIC_UIFLOW_UPDATE_IN` | Topic for receiving UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | process-engine |
| `KAFKA_TOPIC_UIFLOW_UPDATE_OUT` | Topic for sending UI flow session variable updates | `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer |
| `KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWUPDATE` | Consumer group ID for UI flow updates | `ui-flow-update` | process-engine |
| `KAFKA_CONSUMER_THREADS_PROCESS_UIFLOWUPDATE` | Number of consumer threads for UI flow updates | `6` | process-engine |

***

### Compatibility

* **SpiceDB**: Now required for `data-search` and `email-gateway` in addition to existing services
* **Renderer Updates**: Web and mobile SDKs include route management, start parameters, enum label display, and chat enhancements
* **Database**: The `start_params` column on `ui_flow_session` table has been renamed to `variables` (auto-migrated via Liquibase). The column now stores all session variables, including start parameters and updates from document uploads and workflow completions

## Support

> [!NOTE]
>
> For technical support, deployment assistance, or feature questions, please contact your FlowX.AI support representative.

### Support channels

* **Technical issues**: Contact your FlowX.AI support representative
* **Feature questions**: Reach out through your designated support channel
* **Documentation**: Report documentation issues or suggestions


# FlowX.AI 5.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.6.0-march-2026/v5.6.0-march-2026

Conversational AI with memory and intent routing, incoming webhooks, proxy connections, unmanaged MongoDB, UI Flow session variables, chat history, and 28 bug fixes.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.6.0.html)

FlowX.AI 5.6.0 brings **conversational AI** to your apps. Build multi-turn chat experiences where agents remember context, classify user intent, and navigate users to the right screen — all within a single workflow. On the integration side, **incoming webhooks** let external systems start processes via HTTP, **proxy connections** route traffic through intermediary servers, and **unmanaged MongoDB** connects FlowX to your existing database infrastructure. The UI layer gains **session variables**, **route management**, **chat history**, and **suggested prompts** for richer end-user experiences.

> [card] [For AI builders](#conversational-workflows)
>
> Chat Driven workflows, session memory, intent routing, and context retrieval

> [card] [For integrators](#incoming-webhooks)
>
> Incoming webhooks, proxy connections, unmanaged MongoDB, and base64 certificates

> [card] [For UI developers](#ui-flow-session-variables)
>
> Session variables, route management, chat history, suggested prompts, and new UI events

### What changed since 5.5.0

| 5.5.0 | 5.6.0 |
| - | - |
| Output Focused workflows only | + **Chat Driven** workflows with multi-turn memory |
| No event-driven process starts from external systems | **Incoming webhooks** with API key auth |
| FlowX-managed MongoDB only | + **Unmanaged MongoDB** — bring your own database |
| No conversation persistence | **Chat History** — browse and resume past sessions |
| Static chat empty state | **Suggested Prompts** — guide users with one-click starters |
| Certificate file paths only | **Base64 certificates** — paste content directly, no file mounts |
| No cross-page data in UI Flows | **Session variables** — persist data across pages and workflows |

***

**What's new?**

> [tab] AI Platform
>
> Build complete conversational AI pipelines — from understanding what the user wants, to retrieving the right context, to navigating them to the right screen.
>
> 💬 [**Conversational Workflows**](#conversational-workflows) - New Chat Driven workflow type for multi-turn conversations\
> 🧠 [**Memory Capabilities**](#memory-capabilities) - Automatic session memory with summarization across turns\
> 🎯 [**Intent Classification node**](#intent-classification-node) - Classify user messages and route to the right branch in one step\
> 🧭 [**Navigate in UI Flow**](#navigate-in-ui-flow) - Let the AI open forms and screens with contextual data\
> 🔍 [**Context Retrieval node**](#context-retrieval-node) - RAG search against Knowledge Bases without calling an LLM\
> 📄 [**Extract Data from File**](#extract-data-from-file) - Three extraction methods, image support, and signature detection\
> 🌐 [**Web Page Extractor**](#web-page-extractor) - Crawl web pages and extract readable content for AI processing
>
> See also: [Chat History](#chat-history), [Suggested Prompts](#chat-suggested-prompts), and [Markdown in chat](#markdown-in-chat-messages) in the **UI & Designer** tab.
>
> ### **Conversational Workflows**
>
> > [card] Conversational Workflows
> >
> > > [tab] Overview
> > >
> > > Chat Driven workflows are a specialized workflow type for multi-turn chat interactions. Unlike Output Focused workflows that process structured input/output, Chat Driven workflows manage ongoing dialogue — handling message exchange, session memory, and response routing through a dedicated Start node layout (Chat Session ID + User Message) and Custom Agent nodes with direct chat reply capability.
> > >
> > > ![Conversational workflow with Custom Agent configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/conversational_workflow_config.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> > > >
> > > > See the complete Conversational Workflows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multi-turn conversations
> > > >
> > > > Support for back-and-forth conversations with persistent context
> > >
> > > > [card] Intent routing
> > > >
> > > > Automatically classify user messages and route to appropriate workflow branches
> > >
> > > > [card] Session memory
> > > >
> > > > Built-in session memory with automatic summarization across conversation turns
> > >
> > > > [card] Chat UI components
> > > >
> > > > Dedicated chat component with error handling and shared state management
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Memory Capabilities**
>
> > [card] Memory Capabilities
> >
> > > [tab] Overview
> > >
> > > Conversational workflows include built-in session memory that automatically persists and retrieves conversation history. On each message, the system retrieves the last 3 turns of raw messages plus a summary of earlier exchanges, injecting them into the AI node's system prompt for context-aware responses.
> > >
> > > ![Memory tab showing conversation summary and history](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/memory_tab_workflow_console.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> > > >
> > > > See the complete Memory Capabilities documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Automatic retrieval
> > > >
> > > > Last 3 turns + summary of earlier exchanges retrieved on each message via sessionId
> > >
> > > > [card] Smart summarization
> > > >
> > > > Older conversation history is automatically summarized to fit within context limits
> > >
> > > > [card] Per-node control
> > > >
> > > > Turn on memory per Custom Agent node with the **Use memory** toggle
> > >
> > > > [card] Memory tab in console
> > > >
> > > > View retrieved memory (raw turns + summary) in the workflow console log
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Intent Classification node**
>
> > [card] Intent Classification Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that combines AI-powered message classification with workflow branching in a single step. Define up to 10 intents with natural language descriptions, and the node classifies user messages and routes to the matching branch automatically — replacing the previous TEXT\_UNDERSTANDING + Condition two-node pattern.
> > >
> > > ![Intent Classification node](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/intent_classification_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> > > >
> > > > See the complete Intent Classification documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] AI + routing in one node
> > > >
> > > > Combines LLM classification and conditional branching — no separate Condition node needed
> > >
> > > > [card] Natural language conditions
> > > >
> > > > Define intents as plain-text descriptions instead of code expressions
> > >
> > > > [card] Conversation memory
> > > >
> > > > Optionally use past conversation context for more accurate classification
> > >
> > > > [card] Built-in fallback
> > > >
> > > > Automatic "If No Intent Matches" branch handles unrecognized inputs
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Navigate in UI Flow**
>
> > [card] Navigate in UI Flow
> >
> > > [tab] Overview
> > >
> > > A new workflow node exclusive to **Chat Driven** (conversational) workflows. It navigates the user to a specific screen in a UI Flow, passing dynamic parameters — for example, the AI says *"Let me open your account details"* and the user sees a pre-filled form with data from the conversation.
> > >
> > > ![Navigate in UI Flow node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/navigate_ui_flow_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#navigate-in-ui-flow-node)
> > > >
> > > > See the Navigate in UI Flow section in Conversational Workflows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Conversational context
> > > >
> > > > Navigate users to UI screens directly from a Chat Driven workflow conversation
> > >
> > > > [card] Dynamic parameters
> > > >
> > > > Pass workflow data to the destination screen using `${expression}` syntax
> > >
> > > > [card] Destination picker
> > > >
> > > > Select from the UI Flow's navigation tree with auto-populated query parameters
> > >
> > > > [card] Chat Driven only
> > > >
> > > > Available exclusively in the Actions category of conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval node**
>
> > [card] Context Retrieval Node
> >
> > > [tab] Overview
> > >
> > > A dedicated workflow node that performs RAG (Retrieval-Augmented Generation) searches against Knowledge Bases without calling an LLM. Returns raw chunks with relevance scores and metadata, giving you full control over downstream processing. Supports hybrid, semantic, and keyword search with configurable re-ranking and metadata filters.
> > >
> > > Use Context Retrieval when you need to inspect, filter, or transform chunks before passing them to an LLM — for example, checking relevance scores before generating a response. For all-in-one RAG, use a Custom Agent node with a Knowledge Base attached instead.
> > >
> > > ![Context Retrieval node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/context_retrieval_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the complete Context Retrieval documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] No LLM required
> > > >
> > > > Retrieves chunks directly — no AI generation step, lower latency and cost
> > >
> > > > [card] Multiple search types
> > > >
> > > > Hybrid, semantic, or keyword search with configurable relevance thresholds
> > >
> > > > [card] Metadata filters
> > > >
> > > > Filter chunks by user-defined metadata for scoped retrieval
> > >
> > > > [card] Re-ranking
> > > >
> > > > Optional re-ranking for improved result ordering
> >
> > AI IntegrationAll Deployments
>
> ***
>
> ### **Extract Data from File**
>
> > [card] Extract Data from File
> >
> > > [tab] Overview
> > >
> > > The workflow node formerly known as "Extract Text from Document" has been renamed to **Extract Data from File** and gained three new configurable settings: **Extraction Method** (LLM Model, OCR Engine, or Text Parsing), **Image Extraction** (Image Description or Image Contents), and **Detect Signatures**. The node now also accepts image files (JPG, PNG, TIFF) in addition to documents.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> > > >
> > > > See the complete Extract Data from File documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Three extraction methods
> > > >
> > > > Choose between LLM Model (AI vision), OCR Engine (scanned docs), or Text Parsing (digital PDFs) per use case
> > >
> > > > [card] Image support
> > > >
> > > > Process JPG, PNG, and TIFF files alongside PDF, DOCX, XLSX, and PPTX
> > >
> > > > [card] Signature detection
> > > >
> > > > Identify signature areas within documents when using LLM or OCR extraction
> > >
> > > > [card] Moved to Tools category
> > > >
> > > > The node is now in the **Tools** category in the workflow node palette
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor**
>
> > [card] Web Page Extractor
> >
> > > [tab] Overview
> > >
> > > A new workflow node in the **Tools** category that collects readable content from web page URLs. Crawl documentation sites to build a Knowledge Base, scrape product pages for competitive analysis, or extract terms and conditions for compliance review. Supports static URL lists or dynamic URL generation, configurable crawling depth with link following, PDF extraction from linked documents, and adjustable scrape speed presets.
> > >
> > > ![Web Page Extractor node configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/web_page_extractor_node.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> > > >
> > > > See the complete Web Page Extractor documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Static or dynamic URLs
> > > >
> > > > Provide a fixed list of up to 20 URLs or generate them dynamically from workflow data
> > >
> > > > [card] Link following
> > > >
> > > > Follow links on pages up to a configurable depth (0–10 levels)
> > >
> > > > [card] PDF processing
> > > >
> > > > Extract content from PDF files linked on crawled pages
> > >
> > > > [card] Speed presets
> > > >
> > > > Choose Slow, Moderate, Fast, or Custom with manual rate limit and concurrency
> >
> > All Deployments

> [tab] Integrations
>
> Connect FlowX to more systems — trigger processes from external events, route traffic through proxies, and query your own MongoDB databases.
>
> 🔗 [**Incoming Webhooks**](#incoming-webhooks) - Trigger processes from external HTTP POST requests\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Route integration traffic through proxy servers\
> 🗄️ [**Unmanaged MongoDB Datasource**](#unmanaged-mongodb-datasource) - Connect to externally managed MongoDB instances\
> 📧 [**Email Trigger Enhancements**](#email-trigger-enhancements) - Resource management, reply-to, and mock email testing\
> 🔐 [**MCP Authentication**](#mcp-authentication) - BEARER and BASIC auth support for MCP server connections\
> 📜 [**Base64 Certificate Support**](#base64-certificate-support) - Provide certificates as base64-encoded strings instead of file paths\
> 📊 [**CSV/Excel to JSON Conversion**](#csv/excel-to-json-conversion) - Download CSV and Excel files as structured JSON on the fly
>
> ### **Incoming Webhooks**
>
> > [card] Incoming Webhooks
> >
> > > [tab] Overview
> > >
> > > A new data source type and microservice (`webhook-gateway`) that allows external systems to trigger FlowX processes via HTTP POST requests. Create a Webhook data source in Integration Designer, connect it to a Message Start Event in your process, and FlowX generates a unique URL with API key authentication. When external systems POST to this URL, a process instance starts automatically with the webhook payload and headers.
> > >
> > > ![Active webhook trigger in Manage Triggers](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/webhook_trigger_active.png)
> > >
> > > > [!NOTE]
> > > >
> > > > Requires deploying the new `webhook-gateway` microservice. See [Deployment Guidelines](./deployment-guidelines-v5.6) for configuration.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> > > >
> > > > See the complete Incoming Webhooks documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] API key authentication
> > > >
> > > > Each webhook gets a unique, cryptographically secure API key for authentication
> > >
> > > > [card] JSON payload forwarding
> > > >
> > > > Webhook body and headers are forwarded to the process instance as variables
> > >
> > > > [card] Manage Triggers integration
> > > >
> > > > Activate, deactivate, and monitor webhooks from the Manage Triggers UI
> > >
> > > > [card] API key regeneration
> > > >
> > > > Regenerate API keys without recreating the webhook configuration
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Proxy Server Connections**
>
> > [card] Proxy Server Connections
> >
> > > [tab] Overview
> > >
> > > Create reusable proxy connections in Integration Designer and attach them to RESTful System data sources. Route outbound API traffic through HTTP or HTTPS proxy servers for environments that require intermediary routing for security or compliance.
> > >
> > > ![Proxy Connection configuration example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/proxy_connections_example.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> > > >
> > > > See the complete Proxy Connections documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] HTTP and HTTPS proxies
> > > >
> > > > Configure HTTP or HTTPS proxy servers with optional basic authentication
> > >
> > > > [card] Reusable connections
> > > >
> > > > Create a proxy once and attach it to multiple RESTful System data sources
> > >
> > > > [card] Test connectivity
> > > >
> > > > Validate proxy configuration before saving with the built-in test function
> > >
> > > > [card] Config parameter support
> > > >
> > > > Use `${param}` syntax in host and port fields for environment-specific values
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Unmanaged MongoDB Datasource**
>
> > [card] Unmanaged MongoDB Datasource
> >
> > > [tab] Overview
> > >
> > > Connect to externally managed MongoDB instances as a data source in FlowX. Unlike the built-in FlowX Database (which provisions and manages MongoDB collections automatically), Unmanaged MongoDB connects to databases and collections you control — with the same CRUD operations, connection discovery, and configurable connection pooling. Requires MongoDB 6.0 or later.
> > >
> > > ![Unmanaged MongoDB data source configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/unmanaged_mongo.png)
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> > > >
> > > > See the complete Unmanaged MongoDB documentation.
> >
> > All Deployments
>
> ***
>
> ### **Email Trigger Enhancements**
>
> > [card] Email Trigger Enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.6.0 enhances the Email Trigger with resource management capabilities, reply-to-email support, process instance tracking for email-triggered processes, and mock email testing for development.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> > > >
> > > > See the complete Email Trigger documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Resource management
> > > >
> > > > Manage email trigger resources with proper lifecycle controls
> > >
> > > > [card] Reply-to-email
> > > >
> > > > Support for reply-to patterns in email-triggered workflows
> > >
> > > > [card] Process instances
> > > >
> > > > View and track process instances created from email triggers
> > >
> > > > [card] Mock email testing
> > > >
> > > > Test email-triggered processes with mock email content during development
> >
> > All Deployments
>
> ***
>
> ### **MCP Authentication**
>
> > [card] MCP Authentication
> >
> > > [tab] Overview
> > >
> > > MCP server connections now support **BEARER** and **BASIC** authentication methods. Configure auth credentials when adding an MCP data source to connect to secured MCP servers.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/adding-mcp-data-source)
> > > >
> > > > See the Adding MCP Data Source documentation.
> >
> > All Deployments
>
> ***
>
> ### **Base64 Certificate Support**
>
> > [card] Base64 Certificate Support
> >
> > > [tab] Overview
> > >
> > > RESTful system data sources now support providing keystore and truststore content as **base64-encoded strings** instead of file paths. A new "Certificate type" selector lets you choose between Base64 (default for new configurations) and Path (existing behavior). Additionally, keystore and truststore passwords now support `${configParam}` placeholder syntax for dynamic per-environment resolution.
> > >
> > > ![Certificate type selector with Base64 and Path options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/certificate_type_selector.png)
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#certificates)
> > > >
> > > > See the Integration Designer certificates documentation.
> >
> > All Deployments
>
> ***
>
> ### **CSV/Excel to JSON Conversion**
>
> > [card] CSV/Excel to JSON Conversion
> >
> > > [tab] Overview
> > >
> > > Download CSV, XLS, or XLSX files as structured JSON directly from the file download endpoints. The conversion happens on the fly using the `Accept: application/json` header — no new files are created in storage. Supports two output formats: an array of objects (one per row) or a columnar structure.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/converting-documents-to-different-formats#csv/excel-to-json-conversion)
> > > >
> > > > See the Document Conversion documentation.
> >
> > All Deployments

> [tab] UI & Designer
>
> Richer end-user experiences with session state, chat history, and navigation — plus Designer productivity improvements.
>
> 🗺️ [**UI Flow Route Management**](#ui-flow-route-management) - Configure routes, query parameters, and navigation in UI Flows\
> ▶️ [**UI Flow Start Parameters**](#ui-flow-start-parameters) - Pass parameters when starting UI Flows\
> 💾 [**UI Flow Session Variables**](#ui-flow-session-variables) - Persist data across pages from workflows and file uploads\
> 📋 [**Chat History**](#chat-history) - Browse and resume past chat conversations\
> 💡 [**Chat Suggested Prompts**](#chat-suggested-prompts) - Pre-configured prompt suggestions in chat empty state\
> 🖱️ [**onClick UI events**](#onclick-ui-events) - Client-side data updates on Button and Collection Prototype clicks\
> ✨ [**Monaco Editor Autocomplete**](#monaco-editor-autocomplete) - Autocomplete from config params in code editors\
> 📊 [**KB query results in workflow console**](#kb-query-results-in-workflow-console) - View retrieved chunks and relevance scores during workflow runs\
> 📎 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Upload multiple files simultaneously\
> ❌ [**DISMISS UI action**](#dismiss-ui-action) - Dismiss modals automatically after Start Workflow completes\
> 🎨 [**Process Variables UX**](#process-variables-ux-improvements) - UI/UX improvements for updating process variables\
> 🏷️ [**Enum label display**](#enum-label-display) - Show enum labels instead of codes in text components\
> 📬 [**Notification template usages**](#notification-template-usages) - See where notification templates are used\
> 📐 [**Side Panel in Data Model**](#side-panel-in-data-model) - Improved data model navigation with side panel\
> 👁️ [**On Display UI event**](#on-display-ui-event) - Re-trigger actions every time a screen becomes visible\
> 🪟 [**On Load event on Modal**](#on-load-event-on-modal) - Modal components now support On Load events\
> 🏗️ [**KB user-defined metadata**](#kb-user-defined-metadata) - Define custom metadata keys on Knowledge Base content sources\
> ⚙️ [**Config params in workflow conditions**](#config-params-in-workflow-conditions) - Use config params and user details in workflow Fork node expressions\
> 🎨 [**Branding settings grouping**](#branding-settings-grouping) - Reorganized branding settings page\
> ✍️ [**Markdown in chat messages**](#markdown-in-chat-messages) - Render formatted text, links, and lists in chat responses\
> 🔗 [**External Action dynamic URL**](#external-action-dynamic-url) - Use expressions in External Action URLs for dynamic navigation\
> 📬 [**Notification history**](#notification-history) - View sent notification details and search by process instance
>
> ### **UI Flow Route Management**
>
> > [card] UI Flow Route Management
> >
> > > [tab] Overview
> > >
> > > Define query parameters on root views (Pages, Modals), pass data between screens via URL query strings, and get automatic breadcrumb generation from the navigation graph. Navigate To actions support destination parameter mapping with `${expression}` syntax for dynamic values.
> > >
> > > ![Route parameters modal with URL path preview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/route_parameters_modal.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#route-management)
> > > >
> > > > See the Route Management section in UI Flows.
> >
> > > [tab] Key Features
> > >
> > > > [card] Route parameters
> > > >
> > > > Define named query parameters on root views with default values and required flags
> > >
> > > > [card] Parameter passing
> > > >
> > > > Map data from process store to destination query parameters using JSON expressions
> > >
> > > > [card] Auto breadcrumbs
> > > >
> > > > Breadcrumbs auto-generate from the navigation graph with proper parameter handling
> > >
> > > > [card] Modal URL state
> > > >
> > > > Modals add `modalId` to URL — survives page reload and supports deep linking
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Start Parameters**
>
> > [card] UI Flow Start Parameters
> >
> > > [tab] Overview
> > >
> > > Pass initial data when launching a UI Flow. Define start parameters as a JSON object in the Designer's Run dialog, extract them from URL query strings in SaaS container apps, or send them in the API request body. Parameters are persisted on the session and available throughout the UI Flow lifecycle.
> > >
> > > ![Run UI Flow dialog with Start params JSON editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_start_params.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#start-parameters)
> > > >
> > > > See the Start Parameters section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Session Variables**
>
> > [card] UI Flow Session Variables
> >
> > > [tab] Overview
> > >
> > > UI Flow sessions can now persist variables across all pages sharing the same session ID. Data from start parameters, workflow outputs, and file upload responses is automatically collected and merged into session variables. Reference them in component configurations using `${}` syntax. A new **Variables** tab in the Designer session console shows current values for debugging.
> > >
> > > ![Variables tab in UI Flow session console](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_session_variables.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#session-variables)
> > > >
> > > > See the Session Variables section in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **Chat History**
>
> > [card] Chat History
> >
> > > [tab] Overview
> > >
> > > Users can now browse and resume past chat conversations. Chat History displays a list of previous sessions grouped by time (Today, Yesterday, Previous 7 Days, Previous 30 Days, Older), with the ability to open any conversation and continue where they left off. Conversations are per-user with access control enforced.
> > >
> > > ![Chat History panel with conversation list](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_history.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#chat-history)
> > > >
> > > > See the Chat History section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Chat Suggested Prompts**
>
> > [card] Chat Suggested Prompts
> >
> > > [tab] Overview
> > >
> > > The Chat component now supports pre-configured **Suggested Prompts** — pill buttons displayed below the welcome message in the chat empty state. Configure a title and up to 5 prompt options in the Designer. When a user clicks a suggestion, it is submitted as their message, starting the conversation immediately.
> > >
> > > ![Suggested Prompts in chat empty state](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_suggested_prompts.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#suggested-prompts)
> > > >
> > > > See the Suggested Prompts section in Chat component.
> >
> > All Deployments
>
> ***
>
> ### **Monaco Editor Autocomplete**
>
> > [card] Monaco Editor Autocomplete
> >
> > > [tab] Overview
> > >
> > > Code editors in the Designer now provide autocomplete suggestions from your project's configuration parameters. This speeds up writing business rules and expressions that reference config params.
> > >
> > > > [card] [Documentation](/5.1/docs/projects/runtime/configuration-parameters-overrides)
> > > >
> > > > See the Configuration Parameters documentation.
> >
> > All Deployments
>
> ***
>
> ### **Process Variables UX improvements**
>
> > [card] Process Variables UX
> >
> > > [tab] Overview
> > >
> > > UI/UX improvements to the Update Process Variables experience, making it easier to view and edit runtime process data.
> > >
> > > > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> > > >
> > > > See the Update Process Variables documentation.
> >
> > All Deployments
>
> ***
>
> ### **onClick UI events**
>
> > [card] onClick UI events
> >
> > > [tab] Overview
> > >
> > > Buttons and Collection Prototypes now support **onClick** UI events — client-side JavaScript expressions that execute immediately when clicked, *before* any configured UI actions fire. Use them for instant local data updates without server roundtrips.
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-events)
> > > >
> > > > See the UI Events documentation.
> >
> > All Deployments
>
> ***
>
> ### **KB query results in workflow console**
>
> > [card] KB Query Results
> >
> > > [tab] Overview
> > >
> > > The workflow run console now includes a **Knowledge Base** tab that displays retrieved chunks, relevance scores, content sources, and metadata when Custom Agent nodes query a knowledge base. This makes it easier to debug and tune RAG-powered workflows.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows)
> > > >
> > > > See Using Knowledge Base in Workflows.
> >
> > All Deployments
>
> ***
>
> ### **Multi-file bulk upload**
>
> > [card] Multi-file Bulk Upload
> >
> > > [tab] Overview
> > >
> > > Upload multiple files simultaneously at runtime using the new [Multiple File Upload](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload) component. Supports drag-and-drop, batch selection, per-file validation, and progress tracking. Available in both process screens and UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **DISMISS UI action**
>
> > [card] DISMISS Action
> >
> > > [tab] Overview
> > >
> > > The Start Workflow UI action now includes a **Dismiss modal** checkbox. When enabled, the modal closes automatically after the workflow completes — removing the need for a separate close action.
> >
> > All Deployments
>
> ***
>
> ### **Enum label display**
>
> > [card] Enum Label Display
> >
> > > [tab] Overview
> > >
> > > Text components can now display the human-readable **label** of an enumeration value instead of the raw code. When a data key references an enumeration, the renderer resolves the selected code to its label at display time. Enumeration values are also prefetched from the data model before action resolution for improved performance.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/enumerations#displaying-enum-labels-in-text-components)
> > > >
> > > > See the Enumerations documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification template usages**
>
> > [card] Notification Template Usages
> >
> > > [tab] Overview
> > >
> > > Notification templates now show a **usages** modal that lists all processes and workflows referencing the template. This helps you understand the impact of changes before editing or deleting a template.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> > > >
> > > > See the Managing Notification Templates documentation.
> >
> > All Deployments
>
> ***
>
> ### **Side Panel in Data Model**
>
> > [card] Side Panel in Data Model
> >
> > > [tab] Overview
> > >
> > > The Data Model editor now includes a side panel for easier navigation and editing of data model attributes, improving the workflow when working with large data models.
> >
> > All Deployments
>
> ***
>
> ### **On Display UI event**
>
> > [card] On Display UI event
> >
> > > [tab] Overview
> > >
> > > A new `onDisplay` event type that triggers every time a screen becomes visible — on initial load, when navigating back, or when a modal is dismissed. Unlike On Load (which fires once), On Display re-triggers on every view, making it ideal for refreshing data.
> > >
> > > Supported on Page, Zone, and Tab Bar components in UI Flows.
> >
> > All Deployments
>
> ***
>
> ### **On Load event on Modal**
>
> > [card] On Load event on Modal
> >
> > > [tab] Overview
> > >
> > > Modal components in UI Flows now support the On Load event and Start Workflow action. This enables data fetching when a modal opens, allowing you to load context-specific data for modal content.
> >
> > All Deployments
>
> ***
>
> ### **KB user-defined metadata**
>
> > [card] KB user-defined metadata
> >
> > > [tab] Overview
> > >
> > > Define custom metadata keys on Knowledge Bases and assign values to content sources. User-defined metadata enables filtering and scoping when searching chunks — for example, by department, document version, or region. Metadata values are propagated to the vector database and can be used as filters in the Context Retrieval workflow node.
> >
> > All Deployments
>
> ***
>
> ### **Config params in workflow conditions**
>
> > [card] Config params in workflow conditions
> >
> > > [tab] Overview
> > >
> > > Workflow Fork (condition) nodes can now access configuration parameters via `additionalData.applicationConfiguration` and authenticated user details via `additionalData.securityDetails` in their expressions. This enables environment-aware routing and user-based branching in integration workflows.
> >
> > All Deployments
>
> ***
>
> ### **Branding settings grouping**
>
> > [card] Branding settings grouping
> >
> > > [tab] Overview
> > >
> > > The branding settings page has been reorganized with improved grouping and layout, making it easier to find and configure branding options.
> >
> > All Deployments
>
> ***
>
> ### **Markdown in chat messages**
>
> > [card] Markdown in Chat Messages
> >
> > > [tab] Overview
> > >
> > > Chat message components in web renderers now support Markdown rendering. AI-generated responses can include formatted text, headings, links, code blocks, and lists — displayed with proper styling in the chat interface.
> >
> > All Deployments
>
> ***
>
> ### **External Action dynamic URL**
>
> > [card] External Action Dynamic URL
> >
> > > [tab] Overview
> > >
> > > External Action URLs now support `${expression}` syntax for dynamic values. Build destination URLs using process data, config params, or computed values — enabling context-aware external navigation from UI Flows.
> > >
> > > > [card] [Documentation](/5.1/docs/building-blocks/ui-designer/ui-actions#external-ui-actions)
> > > >
> > > > See the UI Actions documentation.
> >
> > All Deployments
>
> ***
>
> ### **Notification history**
>
> > [card] Notification History
> >
> > > [tab] Overview
> > >
> > > New REST API endpoints on the notification plugin let you retrieve sent notification history. Query a paginated summary list filtered by app and optionally by process instance, or fetch full notification details by ID — including recipients, subject, body, and the source process/action that triggered it.
> > >
> > > * `GET /api/notification/summary` — paginated summary list with filtering and sorting
> > > * `GET /api/notification/{id}` — full notification details including body and recipients
> >
> > > [tab] Key Features
> > >
> > > > [card] Summary and detail views
> > > >
> > > > Paginated summary list for browsing, with full detail drill-down by notification ID
> > >
> > > > [card] Source tracking
> > > >
> > > > Each notification records which process, node, and action triggered it for full traceability
> >
> > All Deployments

> [tab] SaaS
>
> User management and branding improvements for SaaS deployments.
>
> 👤 [**Runtime User Invitations**](#runtime-user-invitations) - Invite runtime users directly to test projects\
> 🏢 [**Workspace Type Display**](#workspace-type-display) - See workspace type within Designer\
> 🎨 [**Container App Branding**](#container-app-branding) - Customize branding for SaaS container apps\
> 👥 [**Designer User Invitations**](#designer-user-invitations) - Updated invite modal for designer users
>
> ### **Runtime User Invitations**
>
> > [card] Runtime User Invitations
> >
> > > [tab] Overview
> > >
> > > Invite runtime users directly to test projects from within the Designer. Simplifies the process of granting test access without requiring full workspace-level permissions.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS
>
> ***
>
> ### **Workspace Type Display**
>
> > [card] Workspace Type Display
> >
> > > [tab] Overview
> > >
> > > The Designer now displays the workspace type (development, staging, production) directly within the workspace view, making it easier to identify your current environment.
> >
> > SaaS
>
> ***
>
> ### **Container App Branding**
>
> > [card] Container App Branding
> >
> > > [tab] Overview
> > >
> > > Customize your SaaS container app branding at the organization level — upload a custom logo, set primary and secondary colors, toggle the header, and configure the solutions page background.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/container-app-branding)
> > > >
> > > > See the Container App Branding documentation.
> >
> > SaaS
>
> ***
>
> ### **Designer User Invitations**
>
> > [card] Designer User Invitations
> >
> > > [tab] Overview
> > >
> > > The invite modal for designer users has been redesigned with clearer role selection, group assignment, and a streamlined layout for inviting multiple users.
> > >
> > > > [card] [Documentation](/5.9/docs/saas/inviting-users)
> > > >
> > > > See the Inviting Users documentation.
> >
> > SaaS

> [tab] Bug Fixes
>
> ## Bug fixes
>
> ### Core Platform
>
> * **Authorization-system Oracle DB startup** — Fixed an issue where the authorization-system service failed to start when using Oracle as the configured database.
> * **Process definition merge timing** — Fixed a race condition where the process definition was updated before the merge was finalized.
> * **Theme import with builds** — Fixed an issue where themes were not included when importing builds.
> * **Library import permissions** — Fixed an issue where importing a library into a workspace redirected to a 403 error page.
> * **App version reimport** — Fixed an error that occurred when reimporting an app version (project or library).
> * **Email resend after URL expiry** — Fixed an issue where the resend email endpoint returned 200 OK but no email was sent after the URL expired.
> * **Platform status discovery** — Fixed an authorization error when trying to force discover platform status.
> * **Runtime roles in permissions** — Fixed inconsistent runtime roles display in the permissions dropdown.
>
> ### AI Platform & Workflows
>
> * **gRPC thread pool sizing** — Fixed under-provisioned gRPC client thread pools that caused socket timeouts and dropped requests in production.
> * **API error trace IDs** — API errors now include a reference to the active traceID for easier debugging.
> * **Cross-project resource copy** — Fixed an issue where copying a workflow resource to another project did not include LDM objects.
> * **Multi-instance mappings** — Fixed a 400 error when saving multi-instance mappings in data mappers.
> * **Email trigger mock testing** — Fixed errors when starting a process from a build with mock email content.
> * **Multiple start nodes with email trigger** — Fixed an issue where only one start option was displayed when a process contained multiple start nodes with email triggers.
>
> ### Renderers & UI
>
> * **Angular input field crash** — Fixed an issue where pressing Enter in an input field caused the Angular UI to crash.
> * **Floating Chat interaction blocking** — Fixed an issue where the floating chat component blocked all interaction with page content while open.
> * **S3 internal bucket error** — Fixed an error when the integration-designer downloads files from document-plugin via downloadPath.
> * **File upload second attempt** — Fixed an issue where upload requests were not made when uploading a second file.
> * **UI Flow analytics** — Fixed issues where analytics events were not visible and not saved for Navigate-to action types.
> * **Task management column selection** — Fixed an issue where the Last Updated column remained selected in task management.
> * **Task Manager theming and UX** — Multiple fixes for Task Manager theming, dropdown display, comment field styling, and user assignment behavior.
> * **Toggle/checkbox label alignment** — Fixed an issue where the switch toggle/checkbox or label shifted position when in an error state.&#x20;
> * **Query parameters lost after refresh** — Fixed an issue where URL query parameters were lost after page refresh in UI Flows.&#x20;
> * **SSE connection management** — Fixed multiple issues where SSE connections were opened twice or not closed properly after messages were received.&#x20;
> * **Modal layering** — Fixed incorrect layering when a loader modal was displayed on top of another modal.&#x20;
> * **Card theming overrides** — Fixed an issue where card theming overrides were not applied when the card was collapsed.&#x20;
> * **On Display workflow triggering** — Fixed an issue where past On Display workflows were not re-triggered on page refresh.&#x20;
>
> ### Knowledge Base
>
> * **KB metadata handling** — Fixed multiple issues with Knowledge Base user-defined metadata: empty properties on content source creation, metadata not available for content sources added through apps, and incorrect cleanup when deleting metadata keys.&#x20;

> [tab] Info
>
> ## Additional information
>
> ### At a glance
>
> This release includes **30+ new features and enhancements** across AI Platform, Integrations, UI & Designer, and SaaS — plus **28 bug fixes** spanning Core Platform, AI/Workflows, Renderers, and Knowledge Base.
>
> ***
>
> ### Deployment information
>
> > [!NOTE]
> >
> > For detailed deployment guidelines, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6).
>
> For new environment variables and Kafka topics, see the [Deployment Guidelines v5.6.0](./deployment-guidelines-v5.6#new-environment-variables).
>
> ### Changes to be aware of
>
> > [!NOTE]
> >
> > FlowX.AI 5.6.0 is a SaaS-managed release — deployment-level changes (infrastructure, Kafka topics, service configuration) are handled automatically by FlowX. The items below are listed for transparency and for future reference when on-prem support ships in 5.7+.
>
> #### API change (action required if you use this endpoint)
>
> > [!WARNING]
> >
> > **Process definition start metadata endpoint renamed** — `GET /api/process-definition/{uuid}/get-input-json` has been renamed to `GET /api/process-definition/{uuid}/get-start-metadata`. Update any API clients or custom integrations that call this endpoint directly.
> >
> > The response now includes an additional `hasEmailTriggerStart` boolean field.
>
> #### Infrastructure changes (managed by FlowX on SaaS)
>
> * **gRPC thread pool configuration** — Default gRPC client thread pool sizes have been updated for better production throughput.
> * **WorkspaceCreatedEvent ownership** — Kafka topic ownership moved from `authorization-system` to `organization-manager`.
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Upgrade from v5.5.0 — if you call `get-input-json` directly, update to `get-start-metadata`. All other changes are managed automatically on SaaS.
>
> > [card] [Component versions](./deployment-guidelines-v5.6#component-versions)
> >
> > See the Deployment Guidelines for the full component version matrix


# Deployment guidelines v5.7.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7

Component versions, environment variables, and configuration changes for FlowX.AI 5.7.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.96.0** | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 | 10.12.0 |
| **admin** | **10.83.0** | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 | 10.12.0 |
| **designer** | **10.164.0** | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **cms-core** | **10.58.0** | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 | 10.7.0 |
| **scheduler-core** | **10.45.0** | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 | 10.4.1 |
| **events-gateway** | **10.47.0** | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 | 10.4.1 |
| **notification-plugin** | **10.56.0** | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 | 10.7.0 |
| **document-plugin** | **10.64.0** | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 | 10.6.0 |
| **task-management-plugin** | **10.57.0** | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 | 10.7.0 |
| **data-search** | **10.44.0** | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 | 10.4.1 |
| **audit-core** | **10.54.0** | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 | 10.6.0 |
| **advancing-controller** | **10.45.0** | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 | 10.4.1 |
| **integration-designer** | **10.113.0** | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 | 10.8.0 |
| **application-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **runtime-manager** | **10.88.0** | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 | 10.11.0 |
| **data-sync** | **10.50.0** | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 | 10.3.1 |
| **authorization-system** | **10.68.0** | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 | 10.7.0 |
| **nosql-db-runner** | **10.48.0** | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 | 10.4.1 |
| **email-gateway** | **10.47.0** | 10.32.1 | 10.24.0 | 10.9.0 | - | - |
| **organization-manager** | **10.44.0** | 10.26.1 | 10.19.2 | - | - | - |
| **webhook-gateway** | **10.15.0** | 10.1.1 | - | - | - | - |
| **license** | **10.36.0** | - | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/angular-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/react-ui-toolkit** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-sdk** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **@flowx/core-theme** | **10.164.0** | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 | 10.12.1 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 | 10.0.0 |

### Plugins

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 | 5.2.0 |
| - | - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 | 10.1.1 | 10.0.1 |
| **ai-platform-ai-assistant** | **10.6.2** | - | - | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 | 10.2.5 | 10.2.0 |
| **ai-platform-ai-developer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-connected-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-knowledge-graph** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agents** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-conversations** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-tenants** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-planner** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-analyst** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-ai-designer** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-agent-builder** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **ai-platform-binaries** | **10.6.2** | 10.6.0 | 10.4.0 | 10.1.3 | 10.1.3 | 10.0.1 |
| **embedder** | **10.6.2** | - | - | - | - | - |
| **knowledgebase-rag** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **knowledgebase-indexer-v2** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **mcp** | **10.6.2** | 10.6.0 | 10.2.0 | - | - | - |
| **doc-converter** | **10.2.3** | 10.2.2 | - | - | - | - |
| **doc-parser** | **10.6.2** | 10.5.1 | - | - | - | - |
| **web-crawler** | **10.3.2** | - | - | - | - | - |
| **data-privacy** | **10.0.8** | - | - | - | - | - |
| **speech-to-text** | **10.3.3** | - | - | - | - | - |
| **modpod** | **10.0.7** | - | - | - | - | - |

> [!NOTE]
>
> **Note:** The `ai-platform-models` service has been removed in 5.7.0. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers) within the Organization Manager.

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.7.0 | Keycloak | 26+ |
| 5.7.0 | Kafka | 3.8 - 3.9 |
| 5.7.0 | PostgreSQL | 16 - 17 |
| 5.7.0 | Oracle Database | 21c, 23ai |
| 5.7.0 | MongoDB | 7 - 8 |
| 5.7.0 | Redis | 7.4 - 8.0 |
| 5.7.0 | Elasticsearch | 8 |
| 5.7.0 | Angular (Web SDK) | 20 |
| 5.7.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> The following versions of third-party dependencies are no longer supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4

***

## Self-hosted deployment changes

> [!WARNING]
>
> **First on-premises release since 5.4.0.** This section covers critical configuration changes for self-hosted (on-premises) deployments.

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **Fresh install** | Supported | Guided setup flow on first launch. See [Organization Manager setup](/5.1/setup-guides/organization-manager-setup). |
| **5.1.x LTS** | Supported | Requires Organization ID on all 19 services. Liquibase migrates active process instances and realm data. Inactive instances require separate handling by FlowX. See details below. |
| **5.2 - 5.4** | FlowX-assisted only | These versions may have partial realm or organization changes. Contact your FlowX representative for a custom migration plan. Do **not** follow the 5.1.x upgrade path. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

### Organization ID (mandatory for upgrades)

The Organization ID is how FlowX identifies your installation. How it is obtained depends on your deployment path:

* **Fresh install:** The Organization ID is created automatically during the guided setup flow (Designer first-launch screen). No manual configuration needed.
* **Upgrade from 5.1.x:** FlowX registers your organization in the SaaS licensing infrastructure and provides an Organization ID (UUID). Set `ORGANIZATION_ID` on **all 19 services** before deploying 5.7.0 images — Liquibase migrations use it to replace the default organization.

```yaml theme={"dark"}
# Example — set on every service
ORGANIZATION_ID: "26ef7b5f-b463-4375-88c8-xxxxxxxxxxxx"  # UUID provided by FlowX
```

**Affected services (all 19):** process-engine, admin, audit-core, authorization-system, advancing-controller, events-gateway, cms-core, scheduler-core, data-search, document-plugin, nosql-db-runner, notification-plugin, task-management-plugin, integration-designer, organization-manager, email-gateway, application-manager, runtime-manager, license.

> [!WARNING]
>
> Do **not** deploy 5.7.0 images without setting `ORGANIZATION_ID` on upgrade scenarios. Services will fail to start if Liquibase migrations cannot find the organization ID.

> [!NOTE]
>
> **Active vs inactive instances.** Liquibase migrations automatically update the Organization ID on **active process instances** only. Inactive or archived instances require separate migration handled by the FlowX team during guided deployment. Contact your FlowX representative for details.

### License service (new)

Self-hosted deployments must configure the License service to connect to FlowX SaaS for license validation and usage reporting. See the [License service setup guide](/5.9/setup-guides/license-engine-setup) for complete configuration.

### IAM / Keycloak changes

FlowX.AI now uses a **two-realm architecture** in Keycloak and **JWT public key validation** (replacing opaque-token introspection). These changes were introduced in 5.5.0 (SaaS) and are now relevant for self-hosted deployments.

* **Token validation**: `security.type` switches from `oauth2` to `jwt-public-key` on all services
* **Service accounts realm**: A dedicated realm (`00000002-0002-4002-8002-000000000002`) holds all service account clients, separate from the user realm
* **Organization manager**: Now a required dependency for all services (provides realm resolution)
* **`flowx-platform-authorize` client**: No longer needed — remove from Keycloak
* **Master realm credentials**: The authorization-system service needs Keycloak admin access for realm migrations. If you cannot provide admin credentials, see [Manual Keycloak configuration](/5.1/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).
* **SMTP**: Must be configured in Keycloak for password reset and user invitations

For complete IAM setup instructions, see the [Configuring an IAM solution](/5.1/setup-guides/access-management/configuring-an-iam-solution) guide.

***

## Environment info deprecation

The **Configure Environment Info** feature (`PATCH /api/platform/environment`) is deprecated and removed. Environment name is now set during organization registration. The following are no longer used:

* `FLOWX_CLIENT_NAME` environment variable
* `FLOWX_ENVIRONMENT_NAME` environment variable
* `environmentDetails` section in the `/api/init` response

***

## Kafka integration changes

### Fx-Organization-Id header (mandatory)

All FlowX Kafka consumers now validate the `Fx-Organization-Id` header on every incoming message. Messages without this header are rejected with a non-retryable `MissingKafkaHeaderException`.

> [!WARNING]
>
> **Action required for custom Kafka integrations.** If you have custom Kafka producers that publish directly to FlowX topics (starting processes, sending task events, responding to engine requests), you must add the `Fx-Organization-Id` header to every message. Set it to the Organization UUID (`ORGANIZATION_ID` value).
>
> ```java theme={"dark"}
> producerRecord.headers().add("Fx-Organization-Id",
>     organizationId.getBytes(StandardCharsets.UTF_8));
> ```
>
> See the [Creating a Kafka producer](/5.1/docs/platform-deep-dive/integrations/creating-a-kafka-producer#important-headers) guide for details.

### New Kafka topics

| Topic | Environment Variable | Producer | Consumer | Description |
| - | - | - | - | - |
| `ai.flowx.llm.config.changed.v1` | `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | organization-manager | integration-designer, AI Python services | Broadcast when LLM provider or model configuration changes at the organization level |

***

## Environment variables

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `ORGANIZATION_ID` | Organization UUID provided by FlowX. Required on all services for upgrades. Fresh installs get this automatically via the setup flow. | - | all services |
| `FLOWX_LICENSE_KEY` | License key for FlowX SaaS connection | - | license |
| `FLOWX_LICENSE_AUTHSERVERURL` | FlowX SaaS auth URL | - | license |
| `FLOWX_LICENSE_SERVERURL` | FlowX SaaS license API URL | - | license |
| `FLOWX_ORG_MANAGER_URL` | Organization Manager service URL for LLM provider configuration. Required on all Python AI services. | - | planner, ai-developer, ai-analyst, ai-designer, agent-builder, knowledgebase-rag, embedder, knowledgebase |
| `SECURITY_MASTERREALM_CLIENTID` | Master realm admin client ID for Keycloak management | `admin-cli` | authorization-system |
| `SECURITY_MASTERREALM_NAME` | Keycloak master realm name | `master` | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_USERNAME` | Keycloak admin username for realm migrations | - | authorization-system |
| `SECURITY_MASTERREALM_ADMIN_PASSWORD` | Keycloak admin password for realm migrations | - | authorization-system |
| `SECURITY_OAUTH2_SAREALM` | Service accounts realm ID | `00000002-0002-4002-8002-000000000002` | all services |
| `FLOWX_LIB_SECURITY_SERVICES_ORGANIZATIONMANAGER_BASEURL` | Organization manager URL for security lib | `http://organization-manager:80` | all services |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_RESPONSETIMEOUT` | Response timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `60` | organization-manager |
| `FLOWX_SERVICES_AUTHORIZATIONSYSTEM_WEBCLIENT_ORGPROVISIONINGCAS_CONNECTIONTIMEOUT` | Connection timeout (in seconds) for HTTP calls from organization-manager to authorization-system during organization provisioning | `30` | organization-manager |
| `FLOWX_SPEECH_TO_TEXT_BASE_URL` | Base URL for the Speech-to-Text service | `http://speech-to-text:80` | integration-designer |
| `KAFKA_TOPIC_LLM_CONFIG_CHANGED` | Topic for LLM config change notifications | `ai.flowx.llm.config.changed.v1` | organization-manager |
| `LLM_ENCRYPTION_MASTER_KEY` | Encryption key for LLM provider API keys at rest. **Change from default in production.** | `default-dev-key-change-in-prod` | organization-manager |
| `FLOWX_DEFAULT_DESIGNER_HOME_URI` | Base URL of the Designer web app. Required on on-prem deployments. | - | organization-manager |
| `FLOWX_DEFAULT_RUNTIME_HOME_URI` | Base URL of the Runtime (generic container) web app. Required on on-prem deployments when the FlowX generic container app is deployed. | - | organization-manager |
| `FLOWX_DEFAULT_SECURITY_REALM_ALLOWED_REDIRECT_URIS` | Comma-separated list of additional Keycloak redirect URIs. If empty, derived automatically from `FLOWX_DEFAULT_DESIGNER_HOME_URI` and `FLOWX_DEFAULT_RUNTIME_HOME_URI` with a `/*` suffix. Override only to allow access from another app, or when using Keycloak login inside a client-owned container app that uses the FlowX SDK. | `[]` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_ACCOUNT_VERIFICATION` | Lifespan of the account verification link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_USER_INVITE` | Lifespan of the user invite link sent by email, in seconds. | `172800` | organization-manager |
| `FLOWX_DEFAULT_EMAIL_LIFESPAN_FORGOT_PASSWORD` | Lifespan of the forgot-password link sent by email, in seconds. | `3600` | organization-manager |
| `DEFAULT_ORGANIZATION_NAME` | Fallback organization code used by the Designer web app during Keycloak authentication when no `organizationCode` URL query parameter or subdomain is present. Required on on-prem — set to the organization code registered with FlowX. | - | designer |
| `FLOWX_SQL_DISCOVERY_CACHE_TTL` | Time-to-live for Oracle Database schema discovery responses cached for the SQL editor. | `24h` | integration-designer |
| `FLOWX_JDBC_CONNECTIONS_CACHE_MAX_ENTRIES` | Maximum cached JDBC connection pools used by Oracle Database data sources. | `100` | nosql-db-runner |
| `FLOWX_JDBC_CONNECTIONS_CACHE_TTL` | Time-to-live for cached JDBC connection pools. | `1d` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_MAX_POOL_SIZE` | Maximum HikariCP pool size per Oracle Database data source. | `5` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_CONNECTION_TIMEOUT_SECONDS` | JDBC connection timeout for Oracle Database data sources. | `10` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_ROW_LIMIT` | Default row cap on `SELECT` responses for Oracle Database operations. | `1000` | nosql-db-runner |
| `FLOWX_SQL_DEFAULTS_QUERY_TIMEOUT_SECONDS` | Query execution timeout for Oracle Database operations. | `30` | nosql-db-runner |

### Removed environment variables

> [!WARNING]
>
> **For upgrades:** Remove these variables only **after** the Liquibase migrations have completed successfully. If you remove them before starting services for the first time on 5.7.0, the migrations may fail. The recommended sequence is: (1) add new variables, (2) deploy 5.7.0 images, (3) let migrations run, (4) verify services are healthy, (5) remove old variables in a follow-up deployment.

| Environment Variable | Reason | Component |
| - | - | - |
| `FLOWX_CLIENT_NAME` | Replaced by org code from registration | process-engine |
| `FLOWX_ENVIRONMENT_NAME` | Replaced by env name from registration | process-engine |
| `AI_SERVICE_MODELS_ENDPOINT` | The Models microservice (port 9104) has been removed. LLM provider and model configuration has moved to the [AI Providers UI](/5.9/ai-platform/ai-providers). Remove this service from your deployment. | ai-platform (all Python services) |
| `SECURITY_OAUTH2_REALM` | Replaced by per-organization realm resolution. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTID` | Opaque-token introspection client no longer needed. | all services |
| `SECURITY_OAUTH2_CLIENT_CLIENTSECRET` | Opaque-token introspection client secret no longer needed. | all services |
| `SPRING_SECURITY_OAUTH2_RESOURCESERVER_OPAQUETOKEN_*` | Entire opaque-token introspection config removed. | all services |


# FlowX.AI 5.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.7.0-april-2026/v5.7.0-april-2026

Single-org on-premises deployment, custom React components, AI providers self-service, chat-based UI Flows, voice input, end-user access management, and advanced query builder.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.7.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

FlowX.AI 5.7.0 makes on-premises deployment a first-class experience. **Single-org deployment** is now the default mode — configure your organization once, connect to FlowX licensing, and you're running. For builders, **Custom Components** let you write React code directly in the Designer, **AI Providers** configuration gives organizations self-service control over their LLM setup, and **Chat-based UI Flows** simplify conversational experiences. For organization admins, **End-user access management** separates runtime users, roles, and groups from Designer users.

> [card] [For platform teams](#single-org-deployment)
>
> Single-org deployment, license service, organization setup flow

> [card] [For builders](#custom-components)
>
> Custom React components, AI provider config, chat-based UI Flows, voice input

> [card] [For admins](#end-user-access-management)
>
> End-user access management, runtime roles, and groups

### What changed since 5.6.0

| 5.6.0 | 5.7.0 |
| - | - |
| SaaS-focused deployment | + **Single-org on-premises** as the default mode |
| Built-in UI components only | + **Custom React Components** with code editor and dependencies |
| AI models configured by FlowX | + **AI Providers self-service**: OpenAI (FlowX Managed or BYOK), custom URL, Defaults & Fallbacks per workspace type |
| Chat workflow set per component | + **Chat-based UI Flows**: set one workflow for the entire UI Flow |
| Text-only chat input | + **Voice input** for chat conversations |
| No audio processing in workflows | + **Speech to Text** node for transcription and text-to-speech |
| Runtime users mixed with Designer users | + **End-user access management**: separate org-level lists for end-users, roles, and groups, with CSV bulk invite |
| Basic query filters | + **Advanced Query Builder** for database operations |
| MongoDB-only database data sources | + **Oracle Database** as a new data source type with schema-aware SQL editor |
| Fixed search strategy for KB retrieval | + **Context Retrieval**: configurable search type (Hybrid/Semantic/Keyword) and re-ranking |
| Equality-only metadata filters, AND logic | + **Knowledge Base filter builder** with typed operators and AND/OR grouping; **Content Sources** tab renamed to **Stores** |
| Basic merge modal | + **Merge conflicts UX**: redesigned modal, diff viewer theme, keyboard support |

***

**What's new?**

> [tab] Platform
>
> FlowX 5.7.0 introduces single-org deployment as the default mode for on-premises installations, with self-service licensing, organization management, and runtime access controls.
>
> 🏢 [**Single-org deployment**](#single-org-deployment) - On-premises deployment with automatic organization setup\
> 🔑 [**License service**](#license-service) - Connect to FlowX SaaS for license validation and usage reporting\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level end-users, roles, and groups, separate from Designer users
>
> ### **Single-org deployment**
>
> > [card] Single-org deployment
> >
> > > [tab] Overview
> > >
> > > Self-hosted deployments now run as single-organization systems by default. FlowX registers your organization in the SaaS licensing infrastructure, provides an Organization ID, and your deployment connects to FlowX for license validation and usage reporting. The Designer guides you through a setup flow on first launch: enter a token, name your environment, and create your admin user.
> > >
> > > > [card] [Documentation](/5.1/setup-guides/organization-manager-setup#organization-id-configuration)
> > > >
> > > > See the Organization Manager setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Guided setup flow
> > > >
> > > > Designer walks you through organization registration on first launch
> > >
> > > > [card] Organization ID
> > > >
> > > > Mandatory on all services for Liquibase migrations on upgrades
> > >
> > > > [card] License connectivity
> > > >
> > > > On-premises license service connects to FlowX SaaS for validation and usage
> > >
> > > > [card] Multi-org features hidden
> > > >
> > > > Registration, org selection, and org switching are not available on-prem
> > >
> > > > [card] Explicit web app URLs
> > > >
> > > > Designer and Runtime URLs are configured via dedicated on-prem env vars on organization-manager, replacing hard-coded org-code lookup
> >
> > Major FeatureSelf-Hosted
>
> ***
>
> ### **License service**
>
> > [card] License service
> >
> > > [tab] Overview
> > >
> > > The License service is the bridge between your self-hosted deployment and FlowX SaaS. It validates your platform license, reports usage data, and ensures your subscription is active. Configure it with the license key and server URLs provided by FlowX during organization registration.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> > > >
> > > > See the License service setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] License validation
> > > >
> > > > Continuous license sync with FlowX SaaS
> > >
> > > > [card] Usage reporting
> > > >
> > > > AI node execution consumption reported to FlowX
> > >
> > > > [card] Organization events
> > > >
> > > > Listens to organization lifecycle events via Kafka
> > >
> > > > [card] Setup guide
> > > >
> > > > Complete setup guide with PostgreSQL, Kafka, Redis, and SpiceDB configuration
> >
> > Self-Hosted
>
> ***
>
> ### **End-user access management**
>
> > [card] End-user access management
> >
> > > [tab] Overview
> > >
> > > Organization admins can now manage the people who use published solutions separately from Designer users. A new **Access Management** section at the organization level holds three lists — **End-Users**, **End-Users Roles**, and **End-Users Groups** — each with its own permissions. Invite end users individually or import many at once from a CSV template, define roles that describe runtime access, and organize users into groups with custom attributes for filtering.
> > >
> > > > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> > > >
> > > > See the End-user access management setup guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Separate end-user list
> > > >
> > > > End-Users are kept distinct from Designer users, with their own read/write permissions
> > >
> > > > [card] End-user roles
> > > >
> > > > Define named roles that describe runtime access at the organization level
> > >
> > > > [card] End-user groups
> > > >
> > > > Group users by department, region, or any attribute, and assign roles to the whole group
> > >
> > > > [card] Bulk invite
> > > >
> > > > Invite many users at once from a CSV template with names and attributes
> >
> > All Deployments
>
> ***

> [tab] AI & Chat
>
> Self-service AI provider configuration, chat-based UI Flows, AI Triggers, and voice input for conversational experiences.
>
> 🤖 [**AI Providers**](#ai-providers) - Organization-level LLM provider and model configuration\
> 💬 [**Chat-based UI Flows**](#chat-based-ui-flows) - Set a conversational workflow for the entire UI Flow\
> 🎤 [**Voice input**](#voice-input) - Speech-to-text input in chat conversations\
> ⏹️ [**Stop agent response**](#stop-agent-response) - Cancel an in-progress agent reply from the chat input\
> 🗣️ [**Speech to Text node**](#speech-to-text-node) - Transcription and text-to-speech workflow node\
> ⚡ [**AI Triggers**](#ai-triggers) - Named message templates for launching conversational workflows with context\
> 🧩 [**UI Flow Context**](#ui-flow-context) - Pass UI state from a Page to a conversational workflow\
> 🎯 [**Recommended prompts**](#recommended-prompts) - AI-generated follow-up suggestions in chat conversations\
> 🔎 [**Context Retrieval enhancements**](#context-retrieval-enhancements) - Configurable search type and re-ranking\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - Stores rename, typed metadata filters, AND/OR grouping\
> 🌐 [**Web Page Extractor enhancements**](#web-page-extractor-enhancements) - URL filtering, crawl depth, and file downloads
>
> ### **AI Providers**
>
> > [card] AI Providers
> >
> > > [tab] Overview
> > >
> > > Organizations can now configure their own AI providers and assign models at the organization level. Configure **OpenAI** (Bring Your Own Key or FlowX Managed) or **Azure OpenAI** for deployment-based access to GPT models, enable specific models, and assign default and fallback models per AI capability and workspace type (Sandbox, Staging, Production). **Defaults & Fallbacks** now includes an **Audio Capabilities** row used by the Speech to Text node, with `whisper-1` available in the OpenAI model catalog.
> > >
> > > ![Model Providers page with OpenAI and Azure OpenAI configured at the organization level](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/model_providers_view_org.png)
> > >
> > > ![Provider Details modal showing OpenAI and Azure OpenAI as provider options](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_model_Provider.png)
> > >
> > > ![Defaults and Fallbacks page with capability rows including Audio Capabilities](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/defaults_and_fallbacks.png)
> > >
> > > ![Model selection and configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ai_models_selection.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/ai-providers)
> > > >
> > > > See the AI providers and model configuration documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Organization-level providers
> > > >
> > > > Add and manage AI providers with API keys and connection settings
> > >
> > > > [card] Azure OpenAI
> > > >
> > > > Connect to Azure-hosted OpenAI deployments with a base URL and API version
> > >
> > > > [card] Custom model entry
> > > >
> > > > Add models manually for providers that use deployment names (Azure) or non-public catalogs
> > >
> > > > [card] Audio Capabilities
> > > >
> > > > New row in Defaults & Fallbacks for transcription and speech synthesis, used by the Speech to Text node
> > >
> > > > [card] Defaults & Fallbacks
> > > >
> > > > Assign default and fallback models per AI capability and workspace type
> > >
> > > > [card] Fallback strategy
> > > >
> > > > Set fallback models on different providers for resilience
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Chat-based UI Flows**
>
> > [card] Chat-based UI Flows
> >
> > > [tab] Overview
> > >
> > > UI Flows now support two experience types: **Flow-Based** (traditional) and **Chat-Based** (conversational). Chat-Based UI Flows connect to a conversational workflow at the UI Flow level, so all Chat components in the flow use the same workflow by default. A new Settings page with a Chat Options tab lets you configure or change the workflow after creation.
> > >
> > > ![Chat-based UI Flow configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/chat_based_ui_flow.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> > > >
> > > > See the UI Flows documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Experience types
> > > >
> > > > Choose Flow-Based or Chat-Based when creating a UI Flow
> > >
> > > > [card] UI Flow Settings
> > > >
> > > > New Settings page with Chat Options tab for workflow configuration
> > >
> > > > [card] Workflow filtering
> > > >
> > > > Chat components only show conversational workflows in the selector
> > >
> > > > [card] Navigate in UI Flow
> > > >
> > > > AI can open specific screens with parameters from a conversation
> >
> > All Deployments
>
> ***
>
> ### **Chat improvements**
>
> > [card] Chat improvements
> >
> > Configure which parts of the chat header are visible on a per-component basis. The Chat component (when display type is **Fill**) gains a **Show Header** toggle in its Properties panel, and the Chat Header component gets a new **Available Actions** accordion with toggles for **New Conversation** and **History**. Conversation history now loads in pages, with a **Load more** action, and conversations are sorted by creation date with the most recent first.
> >
> > All Deployments
>
> ***
>
> ### **Voice input**
>
> > [card] Voice input
> >
> > > [tab] Overview
> > >
> > > Chat components now support voice input, allowing users to record audio messages directly in the chat. Users can record, preview with an audio player, and send voice messages within conversations.
> > >
> > > > [!NOTE]
> > > >
> > > > Voice input captures and sends audio recordings. When paired with the [Speech to Text](/5.9/ai-platform/agent-builder/speech-to-text) workflow node, voice messages are automatically transcribed and processed as text in conversational workflows.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Audio recording
> > > >
> > > > Record voice messages directly in the chat input
> > >
> > > > [card] Audio preview
> > > >
> > > > Preview recordings with a built-in audio player before sending
> >
> > All Deployments
>
> ***
>
> ### **Stop agent response**
>
> > [card] Stop agent response
> >
> > > [tab] Overview
> > >
> > > The chat input now shows a **Stop** button in place of Send while an agent reply is streaming. Pressing Stop cancels the conversational workflow instance: any in-flight AI call is aborted, partial output is discarded, and the user prompt is persisted with a `cancelled` flag so the chat history reflects what happened.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> > > >
> > > > See the Chat component documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Cross-platform
> > > >
> > > > Available on Web (Standard, Floating, Full Screen), iOS, and Android
> > >
> > > > [card] Themeable
> > > >
> > > > New `stopResponseIcon` slot in `chatInputArea` themes; preloaded by cms-core
> > >
> > > > [card] Localized
> > > >
> > > > New system substitution tags for Stop and Send labels with a11y variants
> >
> > All Deployments
>
> ***
>
> ### **Speech to Text node**
>
> > [card] Speech to Text
> >
> > > [tab] Overview
> > >
> > > A new workflow node that converts between audio and text. **Transcribe** converts audio files (MP3, WAV, M4A, AAC, OGG) into text with language detection and confidence scores. **Text to Speech** generates audio files from text with configurable voice, speed, and format. In conversational workflows, the node processes voice messages from the chat UI automatically.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> > > >
> > > > See the Speech to Text node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Transcription
> > > >
> > > > Convert audio to text with language detection and confidence scores
> > >
> > > > [card] Text to Speech
> > > >
> > > > Generate audio from text with configurable voice, model, speed, and format
> > >
> > > > [card] Chat voice integration
> > > >
> > > > Automatically transcribes voice messages in conversational workflows
> > >
> > > > [card] Multiple file sources
> > > >
> > > > Read from Document Plugin, S3, or chat input
> >
> > > [!NOTE]
> > >
> > > The transcription model is resolved from the organization's **Audio** capability default, configured in **AI Settings** under [Defaults & Fallbacks](/5.9/ai-platform/ai-providers).
> >
> > All Deployments
>
> ***
>
> ### **AI Triggers**
>
> > [card] AI Triggers
> >
> > > [tab] Overview
> > >
> > > Define named message templates with parameters on conversational workflows, so different UI Flow pages can launch the same workflow with different starting contexts. Triggers are configured in a dedicated side nav tab and selected on the Start node or sent from the Chat component at runtime.
> > >
> > > ![Reply Triggers list in a conversational workflow](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/example_reply_trigger.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Parameterized messages
> > > >
> > > > Message templates with `${paramName}` placeholders resolved at runtime
> > >
> > > > [card] Multi-page reuse
> > > >
> > > > Different pages launch the same workflow with different context
> > >
> > > > [card] Start node integration
> > > >
> > > > Toggle between Text and AI Trigger modes on the Start node
> > >
> > > > [card] Memory aware
> > > >
> > > > Trigger messages saved to conversation memory but hidden from chat history
> >
> > All Deployments
>
> ***
>
> ### **UI Flow Context**
>
> > [card] UI Flow Context
> >
> > > [tab] Overview
> > >
> > > Conversational workflows can now receive a JSON context alongside the user message. A new **Conversation Context** property on UI Flow Pages lets you define the Parameters payload (with `${expression}` resolution), and the Start node exposes it as a collapsible **UI Flow Context** editor — also available in the Run Workflow test modal for manual runs.
> > >
> > > ![Start node UI Flow Context and UI Flow Conversation Context property](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/ui_flow_context.png)
> > >
> > > > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#setting-context-from-a-ui-flow)
> > > >
> > > > See the Conversational workflows documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] UI-driven context
> > > >
> > > > Pages attach a JSON payload to conversational runs without hard-coding it in the workflow
> > >
> > > > [card] Expression resolution
> > > >
> > > > Parameters support `${expression}` syntax to bind live UI Flow data at runtime
> > >
> > > > [card] Start node field
> > > >
> > > > Collapsible UI Flow Context editor on the Start node for both runtime and manual testing
> > >
> > > > [card] JSON validation
> > > >
> > > > Invalid JSON is rejected before the run starts, surfacing a clear error
> >
> > All Deployments
>
> ***
>
> ### **Recommended prompts**
>
> > [card] Recommended prompts
> >
> > > [tab] Overview
> > >
> > > Custom Agent nodes can now generate follow-up prompt suggestions alongside their chat replies. When enabled via the new **Prompt Suggestions** satellite panel on a Custom Agent node, the agent includes recommended next questions or actions in its response. These appear as clickable suggestions in the chat UI, guiding users toward relevant follow-up interactions.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node#prompt-suggestions)
> > > >
> > > > See the Custom Agent node documentation for configuration details.
> >
> > > [tab] Key Features
> > >
> > > > [card] Satellite panel
> > > >
> > > > Configure prompt suggestions directly on Custom Agent nodes in the workflow editor
> > >
> > > > [card] AI-generated suggestions
> > > >
> > > > Agent generates contextual follow-up prompts based on the conversation
> > >
> > > > [card] Clickable in chat
> > > >
> > > > Suggestions render as tappable chips in the chat UI
> > >
> > > > [card] Conversational workflows
> > > >
> > > > Works with send-as-reply mode in conversational workflows
> >
> > All Deployments
>
> ***
>
> ### **Context Retrieval enhancements**
>
> > [card] Context Retrieval enhancements
> >
> > > [tab] Overview
> > >
> > > **Custom Agent** and **Context Retrieval** nodes now support configurable **search type** and **re-ranking** for Knowledge Base retrieval. Choose between Hybrid (default), Semantic, or Keyword search strategies depending on your use case. Turn on re-ranking to apply a secondary relevance model that reorders retrieved chunks for higher-quality results.
> > >
> > > > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> > > >
> > > > See the Context Retrieval node documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Search type
> > > >
> > > > Choose Hybrid, Semantic, or Keywords search for Knowledge Base retrieval on Custom Agent and Context Retrieval nodes
> > >
> > > > [card] Re-ranking
> > > >
> > > > Apply a re-ranking model to reorder results by relevance to the query — available on both Custom Agent and Context Retrieval nodes
> >
> > All Deployments
>
> ***
>
> ### **Knowledge Base enhancements**
>
> > [card] Knowledge Base enhancements
> >
> > > [tab] Overview
> > >
> > > The Knowledge Base data source gets a refreshed workspace and a more powerful metadata filter builder. The **Content Sources** tab is now called **Stores**, and the Chunks tab gains a structured query builder for metadata filters with typed operators, AND/OR logic, and grouping — replacing the previous equality-only filters.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content)
> > > >
> > > > See the Knowledge Base content management guide.
> >
> > > [tab] Key Features
> > >
> > > > [card] Stores tab
> > > >
> > > > The Content Sources tab is renamed to Stores. Same concept, clearer label.
> > >
> > > > [card] Typed filter operators
> > > >
> > > > Operators per metadata type: equals, not equals, contains, in, not in, before, after, exists, size equals, and more
> > >
> > > > [card] AND/OR grouping
> > > >
> > > > Combine conditions with AND or OR and nest them in groups for non-trivial logic
> > >
> > > > [card] Query builder on Chunks tab
> > > >
> > > > Test retrieval with Search Type (Hybrid/Semantic/Keywords), Use Re-rank, and the new filter builder
> >
> > All Deployments
>
> ***
>
> ### **Web Page Extractor enhancements**
>
> > [card] Web Page Extractor enhancements
> >
> > > [tab] Overview
> > >
> > > The Web Page Extractor node now supports **URL filtering** to include or exclude specific URL patterns during crawling, **configurable crawl depth** for more control over how deep the crawler follows links, and **file downloads** to retrieve attached files from crawled pages.
> >
> > > [tab] Key Features
> > >
> > > > [card] URL filtering
> > > >
> > > > Include or exclude URLs matching specific patterns during crawling
> > >
> > > > [card] Crawl depth
> > > >
> > > > Configure how many levels deep the crawler follows links
> > >
> > > > [card] File downloads
> > > >
> > > > Download attached files from crawled web pages
> > >
> > > > [card] Bulk document type
> > > >
> > > > When file downloads are enabled, the document type auto-sets to **Bulk** so a single crawl can return multiple documents
> >
> > All Deployments
>
> ***

> [tab] UI & Components
>
> Custom React components, advanced query builder, and merge conflict improvements.
>
> 🧩 [**Custom Components**](#custom-components) - Write React code in Designer and use in UI Flows\
> 🔍 [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder for database operations\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor\
> 🔀 [**Merge conflicts UX**](#merge-conflicts-ux) - Improved merge modal and conflict resolution experience
>
> ### **Custom Components**
>
> > [card] Custom Components
> >
> > > [tab] Overview
> > >
> > > Create custom React components directly in FlowX Designer. Write JSX, CSS, and use pre-defined packages (React, Emotion, Lodash, Axios, date-fns). Components receive process data through input keys and can trigger process actions. Define once in Reusable Resources, use across multiple User Tasks.
> > >
> > > ![Custom Components code editor](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/custom_components.png)
> > >
> > > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> > > >
> > > > See the Custom Components documentation.
> >
> > > [tab] Key Features
> > >
> > > > [card] Code editor
> > > >
> > > > Write React JSX and CSS with a built-in code editor and file tree
> > >
> > > > [card] Pre-defined packages
> > > >
> > > > React, Emotion, Lodash, Axios, and date-fns available out of the box
> > >
> > > > [card] Process integration
> > > >
> > > > Receive process data via input keys and trigger process actions
> > >
> > > > [card] Import/Export
> > > >
> > > > Export as ZIP and import into other projects
> >
> > Major FeatureAll Deployments
>
> ***
>
> ### **Advanced Query Builder**
>
> > [card] Advanced Query Builder
> >
> > > [tab] Overview
> > >
> > > A visual query builder for database operations and metadata filters, replacing manual JSON query writing with a structured interface. Build complex queries with conditions, grouping, and sorting without writing raw queries. The operator set has expanded with NULL checks (`exists`, `is null`), set membership (`not in`), string matching (`contains`, `starts with`, `ends with`), boolean tests (`is true`, `is false`), and date comparators (`before`, `after`). The `between` operator has been removed from the UI.
> > >
> > > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> > > >
> > > > See the FlowX Database documentation for the full query builder reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] Visual conditions
> > > >
> > > > Build query conditions with a structured UI instead of raw JSON
> > >
> > > > [card] Grouping and sorting
> > > >
> > > > Combine conditions with AND/OR grouping and configure result sorting
> > >
> > > > [card] Schema awareness
> > > >
> > > > Fields auto-populated from your collection schema with type-aware operators
> > >
> > > > [card] Visual/Script toggle
> > > >
> > > > Switch between visual builder and raw code editor at any time
> >
> > All Deployments
>
> ***
>
> ### **Oracle Database integration**
>
> > [card] Oracle Database integration
> >
> > > [tab] Overview
> > >
> > > Connect FlowX workflows to externally managed Oracle databases. Configure a connection (Oracle 19c, 21c, or 23ai), save parameterized SQL queries against the schema, and call them from the existing Database Operation node alongside other data sources.
> > >
> > > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> > > >
> > > > See the Oracle Database integration guide for the full reference.
> >
> > > [tab] Key Features
> > >
> > > > [card] SERVICE\_NAME or SID
> > > >
> > > > Connect via Service Name or SID, with an optional SSL toggle
> > >
> > > > [card] Schema-aware SQL editor
> > > >
> > > > Monaco editor with syntax highlighting, autocomplete, and a side panel for tables, columns, primary keys, and foreign keys
> > >
> > > > [card] Test queries inline
> > > >
> > > > Run SQL with sample parameters: table view for SELECT, affected-row count for INSERT, UPDATE, and DELETE
> > >
> > > > [card] Workflow integration
> > > >
> > > > Pick the Oracle data source and query from the Database Operation node, with no new node type required
> >
> > All Deployments
>
> ***
>
> ### **Datasource Experience**
>
> > [card] Datasource Experience
> >
> > The **Add Data Source** dialog now groups data source types into four categories (**AI Capabilities**, **APIs**, **Databases**, and **Connectors**) with a search box for finding a specific type. REST endpoint authoring also suggests common HTTP headers and values to speed up integration setup.
> >
> > ![New Add Data Source dialog with categorized data source types](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/add_new_data_source.png)
> >
> > All Deployments
>
> ***
>
> ### **MongoDB-aware code editor**
>
> > [card] MongoDB-aware code editor
> >
> > Operation editors on MongoDB data sources now use a Monaco language provider tuned for MongoDB. The editor highlights MongoDB operators (Comparison, Logical, Element, Evaluation, Array, Update, Aggregation, Conditional) and `${param}` interpolations, including inside string literals. Three autocomplete flows speed up authoring: typing `$` lists MongoDB operators, opening a quote in a field-name position lists the schema field paths from the linked Project Data Type, and typing inside `${...}` lists the operation's parameter keys.
> >
> > All Deployments
>
> ***
>
> ### **Project Data Model authoring**
>
> > [card] Project Data Model authoring
> >
> > Three improvements make Project Data Model authoring easier and less error-prone.
> >
> > > [card] Go to source
> > >
> > > A new **Go to source** button on data-model usages and Data Model nodes jumps directly to the source definition without manual navigation.
> >
> > > [card] Type-aware example values
> > >
> > > The example-value input on each attribute now matches its declared type: number inputs for NUMBER, a date picker for DATE, a true/false dropdown for BOOLEAN, single-select for enums, multi-select chips for enum arrays, and so on. CURRENCY values use the currency code rather than the symbol.
> >
> > > [card] Type-aware test data
> > >
> > > The same type-aware inputs apply when running or testing a workflow node and when filling input parameters for a reusable function, replacing the previous generic text inputs.
> >
> > All Deployments
>
> ***
>
> ### **Stop Run for workflows**
>
> > [card] Stop Run for workflows
> >
> > You can now cancel a running workflow instance directly from the workflow editor. While a workflow is running, the **Run Workflow** button switches to **Stop Run** — clicking it cancels the instance and marks all in-progress and scheduled nodes as cancelled. Cancelled instances show a new **Cancelled** status alongside Started, Finished, and Failed.
> >
> > > [card] [Documentation](/5.1/docs/platform-deep-dive/integrations/integration-designer#running-and-stopping-workflows)
> > >
> > > See Running and stopping workflows in the Integration Designer reference.
> >
> > All Deployments
>
> ***
>
> ### **Merge conflicts UX**
>
> > [card] Merge conflicts UX
> >
> > The merge branches experience has been improved with a redesigned merge modal, better form validation with detailed error messages, and keyboard support (submit with Enter). The conflict resolution diff viewer now uses a new CodeMirror theme that matches the Monaco editor styling for a consistent visual experience.
> >
> > All Deployments
>
> ***

> [tab] Bug fixes
>
> ## Bug fixes
>
> ### AI Platform
>
> | Issue | Description |
> | - | - |
> | Custom Agent WebSocket stability | Fixed WebSocket 1006 abnormal closure for Custom Agent nodes with large payloads by upgrading AI SDK to handle Spring Framework 7's 64KB frame aggregation limit |
> | Azure OpenAI structured output | Fixed silent hang on Azure OpenAI for Custom Agents, Intent Classification, and Recommended Prompts when the response JSON schema lacked title and description fields |
> | Custom Agent node stuck | Fixed Custom Agent node getting stuck in running state |
> | MCP tool updates not working | Fixed an issue where updating tools on an existing MCP Server did not persist changes |
> | KB append performance | Fixed slow execution of the Append Knowledge Base node |
> | KB chunking on append | Fixed an issue where appended content via JSON in the Update Knowledge Base node was not chunked |
> | REST node with base64 certificate | Fixed error when running a workflow with a REST node using a REST system with a base64 certificate |
> | Workflow dependencies copy | Fixed dependencies not being copied for already-copied workflows |
>
> ### Core Platform
>
> | Issue | Description |
> | - | - |
> | Import pipeline issues | Fixed API issues in the import pipeline |
> | Enum CSV import losing changes | Fixed an issue where importing enumerations via CSV on committed resources did not update the resource modified date, causing changes to appear lost |
> | Data model duplicate key on import | Fixed a MongoDB duplicate key error when importing data model slices with duplicate entries |
> | Config params page not loading | Fixed GET config params endpoint not being called when accessing the Configuration Parameters page |
> | Enum default values dropdown | Fixed only first-level enum objects being displayed in the default values dropdown |
> | Data model loading state | Fixed user getting stuck in loading state after an error on data model keep operation |
>
> ### UI & Renderers
>
> | Issue | Description |
> | - | - |
> | Select component clear icon | Fixed misaligned clear icon on Select components in both Angular and React renderers |

> [tab] Info
>
> ## Additional information
>
> ### Deployment information
>
> > [!NOTE]
> >
> > **Self-hosted deployments:** FlowX 5.7.0 introduces the Organization ID as a mandatory configuration on all services. See the [deployment guidelines](./deployment-guidelines-v5.7) for complete upgrade instructions.
>
> ### Compatibility
>
> > [card] [Upgrade path](./deployment-guidelines-v5.7#supported-upgrade-paths)
> >
> > See the deployment guidelines for supported upgrade paths from 5.1.x LTS, 5.2–5.4, and 5.5–5.6.
>
> > [card] [Component versions](./deployment-guidelines-v5.7#component-versions)
> >
> > See the deployment guidelines for the full component version matrix and third-party dependency support.


# Deployment guidelines v5.8.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/deployment-guidelines-v5.8

Component versions, environment variables, and configuration changes for FlowX.AI 5.8.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **process-engine** | **10.106.0** | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 | 10.29.0 |
| **admin** | **10.93.0** | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 | 10.26.1 |
| **designer** | **10.181.0** | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 | 10.32.4 |
| **cms-core** | **10.67.0** | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 | 10.16.0 |
| **scheduler-core** | **10.53.0** | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 | 10.11.1 |
| **events-gateway** | **10.55.0** | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 | 10.12.1 |
| **notification-plugin** | **10.64.0** | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 | 10.17.0 |
| **document-plugin** | **10.75.0** | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 | 10.16.0 |
| **task-management-plugin** | **10.66.0** | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 | 10.18.0 |
| **data-search** | **10.52.0** | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 | 10.10.1 |
| **audit-core** | **10.63.0** | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 | 10.15.1 |
| **advancing-controller** | **10.55.0** | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 | 10.11.0 |
| **integration-designer** | **10.128.0** | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 | 10.24.0 |
| **application-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **runtime-manager** | **10.97.0** | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 | 10.24.0 |
| **data-sync** | **10.58.0** | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 | 10.14.1 |
| **authorization-system** | **10.77.0** | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 | 10.18.1 |
| **nosql-db-runner** | **10.56.0** | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 | 10.10.1 |
| **email-gateway** | **10.56.0** | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 | - |
| **organization-manager** | **10.53.0** | 10.44.0 | 10.26.1 | 10.19.2 | - | - |
| **webhook-gateway** | **10.25.0** | 10.15.0 | 10.1.1 | - | - | - |
| **license** | **10.46.0** | 10.36.0 | - | - | - | - |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/angular-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/react-ui-toolkit** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-sdk** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **@flowx/core-theme** | **10.181.0** | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 | 10.32.4 |
| **iOS renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |
| **Android renderer** | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 | 10.1.0 |

### Plugins

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 | 5.3.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 | 0.2.3 |

### AI Platform

| Component | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - |
| **ai-assistant** | 10.2.3 | 10.2.3 | 10.2.3 | 10.1.2 | 10.1.2 |
| **ai-platform-ai-assistant** | **10.7.0** | 10.6.2 | - | - | - |
| **di-platform** | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **ai-platform-ai-developer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-connected-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-knowledge-graph** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agents** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-conversations** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-tenants** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-analyst** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-designer** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-agent-builder** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-binaries** | **10.7.0** | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **embedder** | **10.7.0** | 10.6.2 | - | - | - |
| **knowledgebase-rag** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **knowledgebase-indexer-v2** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **mcp** | **10.7.0** | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **doc-parser** | **10.7.0** | 10.6.2 | 10.5.1 | - | - |
| **web-crawler** | **10.3.5** | 10.3.2 | - | - | - |
| **data-privacy** | **10.1.0** | 10.0.8 | - | - | - |
| **speech-to-text** | 10.3.3 | 10.3.3 | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | - | - | - |

***

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.8.0 | Keycloak | 26+ |
| 5.8.0 | Kafka | 3.8 - 3.9 |
| 5.8.0 | PostgreSQL | 16 - 17 |
| 5.8.0 | Oracle Database | 21c, 23ai |
| 5.8.0 | MongoDB | 7 - 8 |
| 5.8.0 | Redis | 7.4 - 8.0 |
| 5.8.0 | Elasticsearch | 8 |
| 5.8.0 | Angular (Web SDK) | 20 |
| 5.8.0 | React (Web SDK) | 18.x |

***

## Self-hosted deployment changes

### Supported upgrade paths

| Source version | Path | Notes |
| - | - | - |
| **5.7.0** | Supported | Standard upgrade. |
| **5.1.x LTS** | Supported | Direct upgrade from 5.1.x to 5.8.0 is supported. |
| **5.5 - 5.6** | SaaS only | These were SaaS-only releases with no on-premises deployment. |

***

## Kafka integration changes

### New Kafka topics

| Topic | Producer | Producer env var | Consumer | Consumer env var |
| - | - | - | - | - |
| `ai.flowx.license.events.v1` | organization-manager | `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | license | `KAFKA_TOPIC_LICENSE_IN_EVENTS` |
| `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | admin | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1` | knowledgebase-indexer-v2 | n/a (Python constant) | embedder | n/a (Python constant) |
| `ai.flowx.ai-platform.knowledgebase.internal.embedding-response.v1` | embedder | n/a (Python constant) | knowledgebase-indexer-v2 | n/a (Python constant) |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | (no env var; resolved from `kafka.topic.naming.*`) | document-plugin | `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` |

**License lifecycle events** are delivered from FlowX SaaS to the on-prem license service.

**Custom-component correction requests** complement the existing process / business-rule / reusable-template / ui-flow correction topics that the admin orchestrator already consumed.

**UI Flow multi-file upload** sends a single bulk command to document-plugin in place of the per-file pattern. The plugin persists each file in the session, emits one SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) at the end of the batch via events-gateway, and forwards per-file results to the existing `ai.flowx.core.trigger.ui-flow.update.v1` topic.

**KB embedding-request / embedding-response** replace the previous gRPC `EmbedderService` path (`BulkGenerateEmbeddings` / `GenerateEmbeddings`); the indexer now publishes one embedding job per chunk and the embedder writes points to Qdrant directly, emitting `KbStoreEntryStateChanged` once all chunks for an entry are persisted.

> [!NOTE]
>
> The two `core-services` topic names (`license.events`, `application-version.correction-after-app-operation.custom-component.request`) resolve from the standard `${kafka.topic.naming.prefix}` / `${kafka.topic.naming.suffix}` machinery: default prefix `ai.flowx.` (empty environment segment), default suffix `.v1`. Operators that want an environment-prefixed topic name (e.g., `ai.flowx.dev.license.events.v1`) set `kafka.topic.naming.environment` globally rather than overriding individual topics. The two AI Platform topics are hard-coded constants in the indexer and embedder and do not participate in the prefix machinery.

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

> [!NOTE]
>
> Environment variable names follow Spring relaxed binding conventions. For example, the YAML property `security.oauth2.sa-realm` maps to the environment variable `SECURITY_OAUTH2_SAREALM` (dots become underscores, hyphens are removed, all uppercase).

### New environment variables

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_LICENSE_ORGANIZATIONID` | Organization ID provided by FlowX. Initialized with the `notset` sentinel; replace it with the value FlowX provides before the license service starts. Type changed from UUID to String in 5.8.0. | `notset` | license |
| `KAFKA_CONSUMER_GROUPID_LICENSE_EVENTS` | Kafka consumer group used by the license service to receive license events. | `license-events` | license |
| `KAFKA_CONSUMER_THREADS_LICENSE_EVENTS` | Listener container concurrency for the license-events consumer. | `1` | license |
| `KAFKA_TOPIC_LICENSE_IN_EVENTS` | License events topic consumed by the license service. | `ai.flowx.license.events.v1` | license |
| `KAFKA_TOPIC_LICENSE_EVENTS_OUT` | Same topic, producer-side binding on organization-manager. | `ai.flowx.license.events.v1` | organization-manager |
| `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_CUSTOMCOMPONENT` | Custom-component correction-request topic, producer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | application-manager |
| `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_CUSTOMCOMPONENT` | Same topic, consumer-side. | `ai.flowx.application-version.correction-after-app-operation.custom-component.request.v1` | admin |
| `MANAGEMENT_HEALTH_REDIS_TIMEOUT` | Spring Boot Actuator timeout for the Redis health indicator (in ms). | `5000` | all services using Redis |
| `SPRING_CACHE_REDIS_PERSISTENCEKEYPREFIX` | Prefix applied to Redis keys for the advancing-controller cache. | `flowx:core:cache:advancing-controller:` | advancing-controller |
| `REDIS_COMMAND_TIMEOUT` | Redis command timeout in ms. Fail-fast during master failover. Bound via `${REDIS_COMMAND_TIMEOUT:5000}` placeholder on `spring.data.redis.timeout`. | `5000` | all services using Redis |
| `REDIS_CONNECT_TIMEOUT` | Redis connection establishment timeout in ms. Bound via `${REDIS_CONNECT_TIMEOUT:5000}`. | `5000` | all services using Redis |
| `REDIS_POOL_MAX_ACTIVE` | Maximum number of active Redis connections in the pool. | `10` | all services using Redis |
| `REDIS_POOL_MAX_IDLE` | Maximum number of idle Redis connections retained in the pool. | `5` | all services using Redis |
| `REDIS_POOL_MIN_IDLE` | Minimum number of idle Redis connections kept warm in the pool. | `1` | all services using Redis |
| `REDIS_POOL_MAX_WAIT` | Maximum time to wait for an available connection from the pool, in ms. | `2000` | all services using Redis |
| `FLOWX_METRICS_STUCKCHECKINTERVALMS` | Interval at which the stuck-events metric scheduler runs (ms). Bound from the inline `@Value("${flowx.metrics.stuck-check-interval-ms:60000}")` default; not in `application.yml`. | `60000` | advancing-controller |
| `FLOWX_METRICS_STUCKTHRESHOLDMINUTES` | Age threshold (in minutes) above which an advancing event is considered stuck. Bound from `@Value("${flowx.metrics.stuck-threshold-minutes:5}")`. | `5` | advancing-controller |
| `FLOWX_DATAPRIVACY_BASEURL` | Base URL for the new Data Privacy service. Required when any AI workflow node enables the Personal Information Guard. | `http://data-privacy:80` | integration-designer |
| `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` | Request timeout (seconds) for Data Privacy WebClient calls. Sized to accommodate cold-start of the Presidio model on the data-privacy worker. | `60` | integration-designer |
| `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN` | Topic consumed by document-plugin to persist a list of UI Flow temp-files in a single batch. Producer-side is the matching `kafka.topic.session.upload.bulk.out` on process-engine, which resolves from the standard naming machinery. | `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | document-plugin |

### Removed environment variables

| Environment Variable | Replaced by | Component |
| - | - | - |
| `FLOWX_SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Removed with the move to single-pod scheduler execution (plat-1549, `commons-scheduler-lib`). No replacement; only one scheduler pod runs now. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_ENABLED` | Same. | application-manager, license |
| `FLOWX_SCHEDULER_MASTERELECTION_PROVIDER` | Same. | application-manager, license |
| `SCHEDULER_MASTERELECTION_CRONEXPRESSION` | Same. | integration-designer, process-engine |

***


# FlowX.AI 5.8.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.8.0-may-2026/v5.8.0-may-2026

Runtime authorization overhaul, UI Flow permissions, Custom Components in Processes, new theme components, Angular bulk file upload, and webhook provider adapters.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/hero-5.8.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted (on-premises) deployments
> * All Deployments Features available in both self-hosted and SaaS

Sharing a FlowX solution used to mean handing out admin keys. **5.8.0 changes that.** The AI Developer now ships the React component you wished you'd had time to build, PII never reaches your LLM by accident, and you can finally invite a reviewer without giving them the platform.

[https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-maya-5.8.0.html)

### What changed since 5.7.0

| 5.7.0 | 5.8.0 |
| - | - |
| End-user access management with org-level roles and groups | + **Runtime authorization** with project-version-scoped roles, groups, and attribute-based assignment |
| UI Flows accessible to any runtime user | + **UI Flow permissions**: assign roles per UI Flow, evaluated at runtime |
| Custom Components in UI Flows only (Phase 1, React) | + **Custom Components in Processes** with shared data model, input/output mappings, and AI Developer generation |
| Built-in UI components | + **Tooltip, Markdown, Progress Bar, Separator** as new theme components |
| React-only multi-file upload | + **Angular SDK bulk file upload** |
| Generic webhook gateway | + **Webhook provider adapters** (Slack, with HMAC signing-secret validation) |
| Oracle Database (basic SQL editor) | + **Richer SQL autocomplete** in the Monaco editor: operators, schema-aware tables/columns, and `:paramName` interpolations |
| No personal-information guardrails on AI workflow nodes | + **PII Guard** with input/output scans, sensitivity presets, and an entity catalog |

***

**What's new?**

> [tab] Platform
>
> 🔐 [**Runtime authorization**](#runtime-authorization) - Project-scoped roles, end-user groups in FlowX, and Solutions → Share flow\
> 📋 [**UI Flow permissions**](#ui-flow-permissions) - Role-based UI Flow visibility with runtime enforcement

> [tab] Builders
>
> 🧩 [**Custom Components in Processes**](#custom-components-in-processes) - Bundled CCs in Process User Tasks with shared data model\
> 🎨 [**New UI components**](#new-ui-components) - Tooltip, Markdown, Progress Bar, Separator\
> 📥 [**Angular bulk file upload**](#angular-bulk-file-upload) - Multi-file upload component for the Angular SDK\
> 📦 [**UI Flow multi-file upload backend**](#ui-flow-multi-file-upload-backend) - Single bulk endpoint and one completion SSE event for batch uploads\
> 🪝 [**Webhook provider adapters**](#webhook-provider-adapters) - Slack inbound webhook support with HMAC signing\
> 🗄️ [**Richer SQL autocomplete**](#richer-sql-autocomplete) - Monaco editor enhancements for the Oracle data source SQL editor\
> 🧱 [**Data source UX redesign**](#data-source-ux-redesign) - Tile-based creation, type filters, unified settings, save with incomplete config\
> ➕ [**Context menu adds UI components in Processes**](#context-menu-adds-ui-components-in-processes) - Right-click Add UI component in Process User Tasks and Reusable UI Templates\
> 👆 [**Pointer cursor on actionable elements**](#pointer-cursor-on-actionable-elements) - Web renderers show pointer on action-bound components

> [tab] AI Platform
>
> 🛡️ [**PII Guard**](#pii-guard) - Personal information identification on AI inputs\
> 🤖 [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent now drafts Custom Component code\
> 📚 [**Knowledge Base enhancements**](#knowledge-base-enhancements) - System metadata keys, Kafka indexer→embedder, Qdrant export/delete, error handling\
> 🌐 [**Web Crawler multi-URL filters**](#web-crawler-multi-url-filters) - Multiple URL filters per crawler config

### **Runtime authorization**

> [card] Runtime authorization overhaul
>
> > [tab] Overview
> >
> > **Before 5.8.0:** a role on a user matched every project that role appeared in. **Now:** roles live at the project version, sharing is explicit, and Designer users still bypass runtime so they can demo without standing up test accounts.
> >
> > Runtime access is reorganized around the project. Roles live at the **project version**, each org has a managed catalog of **end-user groups**, and access flows through a **Solutions → Share** modal. FlowX retains authentication and external-IDP federation in Keycloak; runtime roles, end-user groups, and project-scoped sharing live in FlowX itself, evaluated by a custom runtime authorization service tuned for the volume of runtime permission checks. SpiceDB remains the design-time permission engine for Designer access.
> >
> > > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> > >
> > > See Setup guides → Access management → Runtime authorization.
>
> > [tab] Key Features
> >
> > > [card] Project-scoped roles
> > >
> > > Each project version declares the runtime roles required to operate it. Roles are org-level entities, defined once and reusable across projects and libraries.
> >
> > > [card] Default `user` role on creation
> > >
> > > New projects spawn with a default `user` role so a fresh project is reachable on day one without extra wiring.
> >
> > > [card] Sharing from Solutions
> > >
> > > The Solutions page gains a **Share** modal. Pick a user or end-user group, assign a role, and the user can launch the solution at runtime.
> >
> > > [card] End-user groups in FlowX
> > >
> > > Groups previously managed in Keycloak now live in FlowX. Recommended pattern: an "All End Users" group per single-role solution; one group per role for multi-role solutions.
> >
> > > [card] Process swimlane roles
> > >
> > > BPMN swimlanes assign view, execute, and self-assign permissions per role.
> >
> > > [card] Designer-user bypass
> > >
> > > Designer users can run any project they have designer access to without holding a runtime role; they auto-receive view, execute, and self-assign on every swimlane.
> >
> > > [card] Active Policy gate
> > >
> > > The Share modal lists only roles defined in the build set as **Active Policy** for the project. Roles defined in a non-active build do not appear until promoted.
>
> > [tab] Architecture
> >
> > The 5.8.0 release introduces a clear split between authentication and runtime authorization:
> >
> > | Concern | System | Notes |
> > | - | - | - |
> > | Authentication, sessions, MFA | Keycloak | Unchanged |
> > | External IDP federation | Keycloak | Configured per organization |
> > | User attributes (business filters) | Keycloak | Source of truth for token claims |
> > | Runtime roles | FlowX (custom CAS) | Defined per project version, evaluated at runtime |
> > | End-user groups | FlowX (custom CAS) | Replaces Keycloak group management |
> > | Project-scoped sharing | FlowX (custom CAS) | Solutions → Share modal |
> > | Design-time permissions | FlowX SpiceDB | Designer UI access; unchanged from prior releases |
> >
> > A `designer-user` Keycloak attribute is auto-managed on each user (`true` for designer users, `false` for end-users), with a mapper on the `flowx-platform-authenticate` client so the engine can check it cheaply on the access token.
>
> > [tab] Migration
> >
> > > [!WARNING]
> > >
> > > **Sharing settings do not export between environments or workspaces.** Configure sharing per environment as a deliberate step when promoting a project to a higher environment.
> >
> > Sharing data does not travel with the project export, so promoting a build from one environment to another (for example, dev to staging) requires a sharing pass in the target environment. Treat it as an explicit step in your deployment checklist.
> >
> > Existing FlowX organizations migrate as follows:
> >
> > * Roles previously assigned directly to users continue to work for backward compatibility while you rebuild assignments under the project-scoped model.
> > * End-user groups configured in Keycloak are migrated into FlowX and become the authoritative source going forward.
> > * Existing UI Flows receive the project-level **User** role automatically as their default allowed role on upgrade. See the [UI Flow permissions](#ui-flow-permissions) section for next steps.
>
> All Deployments

### **UI Flow permissions**

> [card] UI Flow permissions
>
> > [tab] Overview
> >
> > **Before 5.8.0:** every UI Flow was reachable by anyone with runtime access. **Now:** each UI Flow carries its own allow-list and components inside it can be hidden or disabled per role.
> >
> > Each UI Flow now carries a list of allowed runtime roles. Users without one of those roles cannot start the UI Flow at runtime, and the UI Flow does not appear in the solutions list returned by the runtime API. Inside a UI Flow session, individual components can be hidden or disabled by permission-based rules evaluated at runtime against the user's permission set.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> > >
> > > See UI Flows → UI Flow permissions.
>
> > [tab] Key Features
> >
> > > [card] Permissions page
> > >
> > > A new **Settings → Permissions** page in the UI Flow editor lets you assign one or more runtime roles to each UI Flow.
> >
> > > [card] Default role on creation
> > >
> > > New UI Flows receive the project-level **User** role by default so they are reachable on day one; tighten the list before deploying.
> >
> > > [card] Per-component hide/disable
> > >
> > > Components can be hidden or made readonly based on the user's runtime permissions, using the same hide/disable rule machinery as JavaScript expressions.
> >
> > > [card] Permission toast
> > >
> > > Users without the required role see a permission toast in the Designer-hosted runtime preview; the deployed app returns 403 from the start endpoint.
> >
> > > [card] Input-parameter validation
> > >
> > > Input parameters are validated against the UI Flow's input schema before the session is created.
> >
> > > [card] Travels with import/export
> > >
> > > Allowed roles are saved on the UI Flow resource and travel with project export/import.
>
> > [tab] Migration
> >
> > UI Flows created before 5.8.0 receive the project-level **User** role automatically as their default allowed role on upgrade. Review and tighten the role list per UI Flow as part of the 5.8.0 deployment checklist.
>
> All Deployments

### **Custom Components in Processes**

> [card] Custom Components in Processes
>
> > [tab] Overview
> >
> > **Before 5.8.0:** Custom Components only ran in UI Flows. **Now:** drag one onto a Process User Task and the React SDK applies the input/output mappings at runtime.
> >
> > Bundled Custom Components, previously only usable in UI Flows, now render in **Process User Tasks**. Each Custom Component carries its own **data model** with explicit input and output slices, and you map process data into and out of the component at each use site. Renderer support ships in the React SDK.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components#using-custom-components-in-process-user-tasks)
> > >
> > > See Custom Components → Using Custom Components in Process User Tasks.
>
> > [tab] Key Features
> >
> > > [card] Process User Task host
> > >
> > > Drag a Custom Component onto a Process User Task layout the same way you do in UI Flows.
> >
> > > [card] Custom Component data model
> > >
> > > Each Custom Component declares its own data model. The Designer keeps input and output slices isolated so the component contract is clear at every use site.
> >
> > > [card] INPUT mappings
> > >
> > > Map process data attributes onto the Custom Component's input slice at runtime, so the component receives only the data it declared.
> >
> > > [card] OUTPUT mappings
> > >
> > > When the component triggers an action, the React SDK applies the configured OUTPUT mappings before piping `saveData` back to process variables.
> >
> > > [card] Test with sample inputs
> > >
> > > The Custom Component editor lets you fill input params with sample data for in-Designer preview, mirroring the UI Flow test flow.
> >
> > > [card] Import and export
> > >
> > > Custom Components export and import alongside the data model and mappings so a component travels intact between projects.
>
> > [tab] Limitations
> >
> > Phase 1 limitations from 5.7.0 still apply: React SDK only (no Angular renderer), pre-defined dependency set (React, Emotion, Lodash, Axios, date-fns), browser-side bundling, and client-side rendering only. See the [Custom Components limitations](/5.9/docs/building-blocks/reusable-resources/custom-components#limitations-phase-1) section.
>
> All Deployments

### **New UI components**

> [card] New UI components
>
> Four new theme components ship with renderer parity across React, Angular, and Android SDKs.
>
> > [card] [Tooltip](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Contextual hint anchored to any UI element. Configurable text (static, local variable, or computed expression), position handling, and an optional icon.
>
> > [card] [Markdown](/5.9/docs/building-blocks/ui-designer/ui-component-types/markdown)
> >
> > Render Markdown content from a static string or computed expression, with localization formatting for numbers, dates, and currency. Six heading levels and link styling are theme-driven.
>
> > [card] [Progress Bar](/5.9/docs/building-blocks/ui-designer/ui-component-types/progress-bar)
> >
> > Visual progress indicator. Set a value between `0` and `1` from a static value, local variable, or computed expression.
>
> > [card] [Separator](/5.9/docs/building-blocks/ui-designer/ui-component-types/separator)
> >
> > Visual divider with theme-driven color. Adjustable height for layout spacing.
>
> All four are exposed in the **Theme Admin** sidebar so theme overrides cascade through templates.
>
> All Deployments

### **Angular bulk file upload**

> [card] Angular bulk file upload
>
> > [tab] Overview
> >
> > The **Multiple File Upload** component (`BULK_FILE_UPLOAD`), previously available only in the React SDK, now ships in the Angular SDK with the same drag-and-drop area and theming. Existing UI Flows that use the component render across React and Angular containers without configuration changes.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> > >
> > > See the Multiple File Upload component reference.
>
> > [tab] Key Features
> >
> > > [card] Renderer parity
> > >
> > > Same component, same configuration, same theming across React and Angular containers.
> >
> > > [card] Drag-and-drop area
> > >
> > > Drop zone with click-to-browse fallback in both renderers.
> >
> > > [card] Theme-driven
> > >
> > > The component picks up theme overrides for typography, colors, and spacing the same way as built-in components.
> >
> > > [card] No flow changes needed
> > >
> > > UI Flows authored before 5.8.0 render in the Angular SDK without edits.
>
> All Deployments

### **UI Flow multi-file upload backend**

> [card] UI Flow multi-file upload backend
>
> > [tab] Overview
> >
> > Multi-file uploads from UI Flows now use a dedicated bulk endpoint and a single completion event in place of the per-file pattern. The upload action accepts a list of temp-file IDs in one request and the SDK receives a single SSE frame when the batch is persisted.
> >
> > > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload#ui-flow-upload-flow)
> > >
> > > See Multiple file upload → UI Flow upload flow.
>
> > [tab] Key Features
> >
> > > [card] Single bulk endpoint
> > >
> > > `POST /ui-flow/{uiFlowSessionId}/upload-multiple` accepts a list of temp-file IDs and returns a server-generated `uploadBatchId`.
> >
> > > [card] Single completion event
> > >
> > > One SSE frame (`UI_FLOW_FILE_UPLOAD_MULTIPLE`, namespace = `uploadBatchId`) delivers per-file results once the batch is persisted.
> >
> > > [card] New Kafka topic
> > >
> > > `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` carries the bulk command from process-engine to document-plugin.
> >
> > > [card] Session variable mapping
> > >
> > > Per-file results are stored as a list under the upload action's `responseKey` in the UI Flow session.
>
> All Deployments

### **Webhook provider adapters**

> [card] Webhook provider adapters
>
> > [tab] Overview
> >
> > Inbound webhook registrations now select a **provider**: `GENERIC` or `SLACK`. The Slack adapter performs HMAC-SHA256 signature validation against the Slack signing secret on every request, including the `X-Slack-Request-Timestamp` skew check (5 minutes). Provider-segmented URLs (`/webhooks/incoming/slack/...`) keep generic and provider-specific registrations isolated. Future providers plug in behind the same `InboundProviderAdapter` interface without changing the URL contract.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#provider-adapters)
> > >
> > > See Incoming webhooks → Provider adapters.
>
> > [tab] Key Features
> >
> > > [card] Slack signature validation
> > >
> > > HMAC-SHA256 on `X-Slack-Signature`, with timestamp skew enforced
> >
> > > [card] Slack URL-verification handshake
> > >
> > > The gateway answers Slack's `url_verification` challenge automatically
> >
> > > [card] Provider-segmented URLs
> > >
> > > `/webhooks/incoming/{provider}/...` keeps providers isolated; mismatch returns 400
> >
> > > [card] Independent secret rotation
> > >
> > > Rotate the provider signing secret without touching the FlowX API key
> >
> > > [card] Settings tab
> > >
> > > Provider + signing secret moved to a dedicated Settings tab on the webhook system
> >
> > > [card] Pluggable
> > >
> > > New providers add an adapter and an enum value; no URL or registration schema changes
>
> All Deployments

### **Richer SQL autocomplete**

> [card] Richer SQL autocomplete
>
> > [tab] Overview
> >
> > The Monaco editor on the Oracle Database data source now ships with a full SQL language definition. Autocomplete suggestions cover SQL keywords and operators, table and column names parsed from the saved schema context, and `:paramName` interpolations resolved from the parameters panel.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database#sql-editor)
> > >
> > > See the Oracle Database SQL editor documentation.
>
> > [tab] Key Features
> >
> > > [card] Keywords and operators
> > >
> > > Full SQL language definition powers keyword highlighting and completion.
> >
> > > [card] Schema-aware suggestions
> > >
> > > Tables and columns parsed from the saved schema context appear in completion lists.
> >
> > > [card] Parameter interpolation
> > >
> > > `:paramName` placeholders resolve against the parameters panel for inline preview.
> >
> > > [card] Editor consistency
> > >
> > > Matches the editor experience used by other code surfaces in the Designer.
>
> All Deployments

### **Data source UX redesign**

> [card] Data source UX redesign
>
> > [tab] Overview
> >
> > The Data Sources resource page is rebuilt around a tile-based creation flow and a unified details view. Each data source type has its own icon and a dedicated tile in the **New Data Source** modal, with a search box that filters tiles as you type. The list view shows the type next to each entry and adds a type filter so you can scope the list by connector. Settings panels for every data source type are normalized to the same card-based layout.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-designer)
> > >
> > > See the Integration Designer reference for data source configuration.
>
> > [tab] Key Features
> >
> > > [card] Tile-based creation modal
> > >
> > > The **New Data Source** modal lists every connector type as a searchable tile, replacing the previous type dropdown.
> >
> > > [card] Type icons in the list
> > >
> > > Each entry in the data sources list shows the connector's icon and type, so a long list is easier to scan.
> >
> > > [card] Filter by type
> > >
> > > Filter the list to a specific connector type (REST, FlowX Database, Email, MCP Server, Knowledge Base, etc.) without scrolling.
> >
> > > [card] Unified settings layout
> > >
> > > Every data source type now uses the same card-based settings layout, so the configuration experience is consistent across connectors.
> >
> > > [card] Save with incomplete config
> > >
> > > Create and save a data source even when some fields (credentials, endpoints) are not yet available. You can reference the data source in workflows and processes immediately and finish the configuration later — the data source will only operate at runtime once required fields are filled in.
>
> All Deployments

### **PII Guard**

> [card] Personal Information Guard
>
> > [tab] Overview
> >
> > **Before 5.8.0:** data-sensitive customers couldn't enable AI workflow nodes at all. **Now:** every AI node carries a per-node guardrail with sensitivity presets, scan directions, and a fail-closed contract.
> >
> > AI workflow nodes gain a per-node guardrail that detects and replaces personal information before it reaches the LLM and, optionally, scans LLM output before it flows downstream. The guard runs against the new **Data Privacy** service, configured per node with sensitivity presets, scan directions, and an entity catalog organized into Universal, Regional EN, and Regional RO scopes. Iteration 1 covers Custom Agent, Intent Classification, Extract Data from File, and all AI Text, Document, Image, and Data Operations, including Document Generation.
> >
> > > [card] [Documentation](/5.9/ai-platform/personal-information-guard)
> > >
> > > See Personal Information Guard.
>
> > [tab] Key Features
> >
> > > [card] Per-node toggle
> > >
> > > Enable on any AI node. Choose a sensitivity preset (Strict / Balanced / Relaxed) or set a custom threshold.
> >
> > > [card] Input and output scans
> > >
> > > Redacts inputs and `systemPrompt` before the LLM call; optionally scans LLM output before it leaves the node.
> >
> > > [card] File redaction
> > >
> > > Document and image nodes get a redacted source artifact uploaded back to the same storage; the file binding is swapped automatically.
> >
> > > [card] Entity catalog
> > >
> > > 24 entity types (email, phone, IBAN, etc.) grouped under Universal, Regional EN, and Regional RO. Modal supports search and section-level Select All.
> >
> > > [card] System-prompt appender
> > >
> > > Custom Agent nodes get a non-editable system-prompt segment teaching the LLM how to handle `<PII type=.../>` placeholders.
> >
> > > [card] Fail-closed
> > >
> > > Any error from the Data Privacy service stops node execution and surfaces on the run log; no partially-redacted prompts reach the LLM.
> >
> > > [card] Run-log visibility
> > >
> > > Each scan reports status, per-entity detection counts, and (for file scans) original and redacted storage paths.
> >
> > > [card] New Data Privacy service
> > >
> > > Backed by Presidio. Configured via `FLOWX_DATAPRIVACY_BASEURL` and `FLOWX_DATAPRIVACY_TIMEOUTSECONDS` on integration-designer.
>
> All Deployments

### **Knowledge Base enhancements**

> [card] Knowledge Base
>
> > [tab] Overview
> >
> > Knowledge Bases gain richer metadata and a more resilient indexing path. Stores and chunks expose system metadata fields you can filter on in the Test KB modal and the Custom Agent node, the indexer and embedder communicate over Kafka instead of synchronous calls, and the Update Knowledge Base node can ingest files by path from inside a workflow.
> >
> > > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> > >
> > > See Knowledge Base → Overview.
>
> > [tab] Key Features
> >
> > > [card] System metadata on stores
> > >
> > > Filter entries by `Source` (Manual or Workflow), `Uploaded`, `Doc name`, `Doc type`, `Doc pages`, and `Store origin`
> >
> > > [card] System metadata on chunks
> > >
> > > Filter chunks by `Chunk counter`, `Chunk type`, `Chunk section`, `Chunk page start`, and `Chunk entry`
> >
> > > [card] Kafka between indexer and embedder
> > >
> > > Replaces the previous synchronous gRPC path; per-chunk embedding requests flow through `ai.flowx.ai-platform.knowledgebase.internal.embedding-request.v1`
> >
> > > [card] Delete chunks from Qdrant
> > >
> > > Indexer forwards a delete job to the embedder, which removes matching points from Qdrant when an entry is deleted
> >
> > > [card] File path mode in Update KB node
> > >
> > > The Update Knowledge Base node accepts `contentType: FILE_PATH` so workflows can ingest content uploaded earlier in the run
> >
> > > [card] Doc pages in agent stream
> > >
> > > Custom Agent streaming responses include `doc_pages` and chunk metadata (counter, type, section, page start) for richer trace and debug
>
> All Deployments

### **Web Crawler multi-URL filters**

> [card] Web Crawler multi-URL filters
>
> > [tab] Overview
> >
> > The Web Crawler node now accepts up to 20 URL filter patterns per crawler configuration. Open the **URL Filters** modal on the Web Crawler node, add one row per pattern, and the crawler restricts its breadth-first traversal to URLs that match any of the configured filters.
> >
> > > [card] [Documentation](/5.9/setup-guides/web-crawler-setup)
> > >
> > > See the Web Crawler setup guide.
>
> > [tab] Key Features
> >
> > > [card] Up to 20 patterns per crawler
> > >
> > > Add one row per pattern in the URL Filters modal; deep crawls match any pattern.
> >
> > > [card] Replaces single-string filter
> > >
> > > The previous single-string filter is superseded by the new multi-pattern array. Existing crawlers are migrated automatically.
> >
> > > [card] Breadth-first scoping
> > >
> > > Filters apply to the crawler's breadth-first traversal so deep crawls stay within the intended scope.
> >
> > > [card] Per-pattern tuning
> > >
> > > Combine narrow and broad patterns in one configuration to handle multi-section sites without spawning multiple crawlers.
>
> All Deployments

### **AI Developer generates Custom Components**

> [card] AI Developer generates Custom Components
>
> > [tab] Overview
> >
> > **Before 5.8.0:** the AI Developer wrote business rules and JS expressions. **Now:** it ships entire React Custom Components — JSX, CSS, `package.json`, and sample input data — in one prompt.
> >
> > The AI Developer pre-built agent gains a **Generate Custom Component** action and an **Edit Custom Component** action. From the Designer's AI command center, describe the component you want, and the agent returns a complete React bundle (JSX, CSS, `package.json`, and sample input data) that you can preview, accept, or iterate on. The same conversation can edit existing components.
> >
> > > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> > >
> > > See AI Developer → Pre-built agents.
>
> > [tab] Key Features
> >
> > > [card] Generate from natural language
> > >
> > > Describe a component in plain language; receive JSX, CSS, `package.json`, and sample input data in one response.
> >
> > > [card] Sample input field
> > >
> > > A dedicated input field lets you provide preview data so the generated component renders meaningfully on first run.
> >
> > > [card] Edit existing components
> > >
> > > Iterate on a generated or hand-authored component through the same conversation. The agent keeps the component context.
> >
> > > [card] Inline preview
> > >
> > > The Designer's Preview area renders the generated bundle next to the conversation so you can validate before saving.
> >
> > > [card] Dependency summary
> > >
> > > A new dependency summary panel surfaces the npm packages the agent included in `package.json`.
> >
> > > [card] Keep / Discard
> > >
> > > Accept the generated bundle into the workspace or discard it without leaving the conversation.
>
> > [tab] Limitations
> >
> > The first iteration generates the component code, styles, and input parameters. Wiring component actions to host-side handlers (Process or UI Flow actions) is not yet inferred — connect actions manually after accepting the generated bundle.
>
> All Deployments

### **iframe logout postMessage contract**

> [card] iframe logout postMessage
>
> The runtime SaaS app now notifies an iframe parent when a user logs out. When the parent passes a `parentOrigin` query parameter on the `/{orgCode}/logout` URL, the runtime posts `{ type: 'logout-success' }` to `window.parent` immediately before the sign-out redirect. Host applications that embed the FlowX runtime in an iframe can listen for this message and react (clear local state, navigate, surface a UI cue) without polling the iframe URL.
>
> All Deployments

### **Context menu adds UI components in Processes**

> [card] Right-click Add UI component in Processes and Reusable UI Templates
>
> The right-click contextual menu for adding a UI component, previously available only in UI Flows, now works in **Process User Tasks** and **Reusable UI Templates** as well. Right-click a node in the components hierarchy panel to insert any allowed child component without dragging from the palette. Copy and paste styles are also exposed from the same menu.
>
> All Deployments

### **Pointer cursor on actionable elements**

> [card] Pointer cursor on actionable elements
>
> Web renderers now switch the cursor to a pointer when hovering over any UI component bound to an action, matching standard web affordances. No configuration change is required — the new behavior applies automatically to elements that already declare an action role.
>
> All Deployments

### **"Process Data" → "Local Variables" rename**

> [card] Process Data renamed to Local Variables
>
> In the UI Designer, the **Process Data** label is now displayed as **Local Variables** when you are editing a UI Flow or a Reusable UI Template. Process editing is unchanged and continues to use **Process Data**. The data source key and binding behavior are identical; only the user-visible label changed, so existing flows continue to work without any update.
>
> All Deployments

### **License billing guards**

> [card] License billing guards
>
> The license service no longer creates billing plans for periods past an organization's subscription end date. This prevents stale plan rows from accumulating after a subscription expires and aligns the on-prem billing trail with the SaaS-side license lifecycle.
>
> Self-Hosted

### **Speech-to-text and Web Crawler in AI consumption**

> [card] Speech-to-text and Web Crawler in AI consumption
>
> AI consumption tracking now includes Speech-to-text and Web Crawler workflow nodes alongside the existing AI Text, Document, Image, and Data Operations. Organizations on AI consumption-based plans see usage and billing reflected for these nodes from 5.8.0 onward.
>
> All Deployments

***

## Shipped by

This release is the work of the FlowX engineering team — backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, Kafka topics, and migration guidance, see [Deployment guidelines v5.8.0](./deployment-guidelines-v5.8).


# Deployment guidelines v5.9.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9

Component versions, environment variables, and configuration changes for FlowX.AI 5.9.0 deployments.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

> [!NOTE]
>
> **Upgrading from 5.1.x LTS?** This page describes the steady-state 5.9.0 deployment. For the architecture delta, deprecation list, and upgrade steps, see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Deployment packaging.** 5.9.x is the last LTS release distributed as a multi-chart deployment, where each FlowX service is installed from its own Helm chart.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

The following tables list component versions per FlowX.AI release. Verify your installed versions against the 5.9.0 column in **FlowX.AI Designer → Platform Status**.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **process-engine** | 10.135.0 | 10.106.0 | 10.96.0 | 10.77.0 | 10.60.0 | 10.38.0 |
| **admin** | 10.116.0 | 10.93.0 | 10.83.0 | 10.66.0 | 10.53.0 | 10.38.0 |
| **designer** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.91.0 | 10.59.1 |
| **cms-core** | 10.86.0 | 10.67.0 | 10.58.0 | 10.43.0 | 10.35.0 | 10.22.0 |
| **scheduler-core** | 10.70.0 | 10.53.0 | 10.45.0 | 10.31.0 | 10.25.0 | 10.15.0 |
| **events-gateway** | 10.72.0 | 10.55.0 | 10.47.0 | 10.33.1 | 10.27.0 | 10.17.0 |
| **notification-plugin** | 10.83.0 | 10.64.0 | 10.56.0 | 10.42.1 | 10.35.0 | 10.22.0 |
| **document-plugin** | 10.94.0 | 10.75.0 | 10.64.0 | 10.46.0 | 10.35.0 | 10.23.0 |
| **task-management-plugin** | 10.84.0 | 10.66.0 | 10.57.0 | 10.41.1 | 10.35.0 | 10.25.0 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |
| **data-search** | 10.69.0 | 10.52.0 | 10.44.0 | 10.30.1 | 10.25.0 | 10.14.0 |
| **audit-core** | 10.79.0 | 10.63.0 | 10.54.0 | 10.40.0 | 10.31.0 | 10.21.0 |
| **advancing-controller** | 10.73.0 | 10.55.0 | 10.45.0 | 10.33.1 | 10.27.0 | 10.16.0 |
| **integration-designer** | 10.162.0 | 10.128.0 | 10.113.0 | 10.84.0 | 10.63.0 | 10.38.0 |
| **application-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **runtime-manager** | 10.123.0 | 10.97.0 | 10.88.0 | 10.69.1 | 10.53.0 | 10.37.0 |
| **data-sync** | 10.81.0 | 10.58.0 | 10.50.0 | 10.38.0 | 10.31.1 | 10.20.1 |
| **authorization-system** | 10.96.1 | 10.77.0 | 10.68.0 | 10.51.0 | 10.42.1 | 10.28.0 |
| **nosql-db-runner** | 10.75.0 | 10.56.0 | 10.48.0 | 10.34.0 | 10.27.0 | 10.17.0 |
| **email-gateway** | 10.74.0 | 10.56.0 | 10.47.0 | 10.32.1 | 10.24.0 | 10.9.0 |
| **organization-manager** | 10.71.0 | 10.53.0 | 10.44.0 | 10.26.1 | 10.19.2 | - |
| **webhook-gateway** | 10.44.0 | 10.25.0 | 10.15.0 | 10.1.1 | - | - |
| **file-gateway** | 10.8.0 | - | - | - | - | - |
| **license** | 10.63.0 | 10.46.0 | 10.36.0 | - | - | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB**
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/angular-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-ui-toolkit** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/react-native-sdk** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-theme** | 10.230.2 | - | - | - | - | - |
| **@flowx/react-native-ui-toolkit** | 10.230.2 | - | - | - | - | - |
| **@flowx/core-sdk** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **@flowx/core-theme** | 10.230.2 | 10.181.0 | 10.164.0 | 10.127.3 | 10.68.0 | 10.59.1 |
| **react-saas** | 10.230.2 | - | - | - | - | - |
| **iOS renderer** | 10.4.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |
| **Android renderer** | 10.5.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.0 |

The **react-saas** container app tracks the designer version.

### Plugins

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-knowledgebase-rag** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.2.0 | - |
| **ai-platform-embedder** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **doc-parser** | 10.9.0 | 10.7.0 | 10.6.2 | 10.5.1 | - | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-platform-agent-builder** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **data-privacy** | 10.1.0 | 10.1.0 | 10.0.8 | - | - | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | 10.2.2 | - | - |
| **evals-judge** | 10.1.1 | - | - | - | - | - |
| **speech-to-text** | 10.3.4 | 10.3.3 | 10.3.3 | - | - | - |
| **web-crawler** | 10.3.5 | 10.3.5 | 10.3.2 | - | - | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **ai-gateway** | 10.7.0 | - | - | - | - | - |
| **ai-platform-ai-analyst** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-assistant** | 10.7.0 | 10.7.0 | 10.6.2 | - | - | - |
| **ai-platform-ai-designer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-ai-developer** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **ai-platform-planner** | 10.7.0 | 10.7.0 | 10.6.2 | 10.6.0 | 10.4.0 | 10.1.3 |
| **di-platform** | 10.3.1 | 10.3.0 | 10.3.0 | 10.3.0 | 10.2.6 | 10.2.5 |
| **flowx-docs** | 5.9.0 | - | - | - | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.0 | 5.8.0 | 5.7.0 | 5.6.0 | 5.5.0 | 5.4.0 |
| - | - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - | - | - |
| **ai-observatory** | 10.3.2 | - | - | - | - | - |

***

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

***

## Kafka topics

### Document-plugin archive and extract listeners

5.9.0 exposes four Kafka topics for the document-plugin **archive** and **extract** operations. Both follow the encrypt/decrypt trigger and reply pattern: document-plugin consumes the `trigger.*.file` topic and process-engine consumes the matching `engine.receive.*.file.results` reply.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.archive.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.archive.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.extract.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.extract.file.results.v1` | document-plugin | process-engine |

The four topic names are exposed as env vars on the document-plugin side (`KAFKA_TOPIC_FILE_ARCHIVE_IN`, `KAFKA_TOPIC_FILE_ARCHIVE_OUT`, `KAFKA_TOPIC_FILE_EXTRACT_IN`, `KAFKA_TOPIC_FILE_EXTRACT_OUT`). See [Documents plugin setup → File archive / File extract](/5.9/setup-guides/documents-plugin-setup#file-archive). Two new thread-pool entries are added: `KAFKA_CONSUMER_THREADPOOLS_THREADPOOLGENERIC_THREADCOUNTPERCONTAINER_FILEARCHIVEIN` and `..._FILEEXTRACTIN`, both defaulting to `5`.

### Document-plugin encrypt and decrypt listeners

The **encrypt** and **decrypt** operations follow the same trigger-and-reply pattern: process-engine produces the `trigger.*.file` topic and document-plugin replies on the matching `engine.receive.*.file.results` topic.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.encrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | document-plugin | process-engine |
| `ai.flowx.plugin.document.trigger.decrypt.file.v1` | process-engine | document-plugin |
| `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | document-plugin | process-engine |

The topic names are exposed as env vars on the document-plugin side: `KAFKA_TOPIC_FILE_ENCRYPT_IN`, `KAFKA_TOPIC_FILE_ENCRYPT_OUT`, `KAFKA_TOPIC_FILE_DECRYPT_IN`, `KAFKA_TOPIC_FILE_DECRYPT_OUT`.

### Document-plugin session-upload listeners

Multi-file upload for UI flows routes uploaded files to the document-plugin for persistence. process-engine produces the trigger topic and document-plugin consumes it — `session` for a single upload session and `session.bulk` for batched multi-file uploads.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.plugin.document.trigger.persist.document.session.v1` | process-engine | document-plugin |
| `ai.flowx.plugin.document.trigger.persist.document.session.bulk.v1` | process-engine | document-plugin |

The topic names are exposed on process-engine as `KAFKA_TOPIC_SESSION_UPLOAD_OUT` and `KAFKA_TOPIC_SESSION_UPLOAD_BULK_OUT`, and on document-plugin as `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_IN` and `KAFKA_TOPIC_DOCUMENT_PERSIST_SESSION_BULK_IN`.

### AI Platform job topics

`integration-designer` dispatches asynchronous jobs to the standalone AI services over Kafka, using a request/response pair per service. Provision these topics when you deploy the corresponding AI service (see [AI components](#ai-components) above).

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.ai-platform.doc-parser.job.request.v1` | integration-designer | doc-parser |
| `ai.flowx.ai-platform.doc-parser.job.response.v1` | doc-parser | integration-designer |
| `ai.flowx.ai-platform.evals-judge.job.request.v1` | integration-designer | evals-judge |
| `ai.flowx.ai-platform.evals-judge.job.response.v1` | evals-judge | integration-designer |
| `ai.flowx.ai-platform.speech-to-text.job.request.v1` | integration-designer | speech-to-text |
| `ai.flowx.ai-platform.speech-to-text.job.response.v1` | speech-to-text | integration-designer |

On `integration-designer` the topic names are set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_REQUEST_OUT` and `..._RESPONSE_IN` (for example `KAFKA_TOPIC_AI_EVALSJUDGE_JOB_REQUEST_OUT`). Each service also has a dead-letter topic — `ai.flowx.ai-platform.<service>.job.dlq.v1`, set via `KAFKA_TOPIC_AI_<SERVICE>_JOB_DLQ_IN` — that integration-designer consumes for failed jobs.

### UI Flow runtime triggers

process-engine consumes two trigger topics that back the UI Flow runtime cache and expiration features. `update` invalidates a cached UI Flow when its definition changes; `expire` removes expired UI Flow runtime data.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.ui-flow.update.v1` | document-plugin, integration-designer | process-engine |
| `ai.flowx.core.trigger.expire.ui-flow.v1` | scheduler-core | process-engine |

On process-engine these are set via `KAFKA_TOPIC_UIFLOW_UPDATE_IN` and `KAFKA_TOPIC_UIFLOW_EXPIRE_IN`; the producers expose `KAFKA_TOPIC_UIFLOW_UPDATE_OUT`. The expire trigger uses the platform scheduler: when a UI Flow session is created, process-engine registers a delayed message with scheduler-core, which publishes it back to this topic at the expiry time. It is consumed by a dedicated consumer group (`KAFKA_CONSUMER_GROUPID_PROCESS_UIFLOWEXPIRE`, default `ui-flow-expire`).

### File and webhook process triggers

Two trigger topics let the file-gateway and webhook-gateway start or resume processes in process-engine. The **start-for-event** topic starts a process when a watched file arrives (file-gateway) or an incoming webhook fires (webhook-gateway); the **message event** topic resumes a running process that is waiting on an intermediate message catch event.

| Topic | Producer | Consumer |
| - | - | - |
| `ai.flowx.core.trigger.start-for-event.process.v1` | file-gateway, webhook-gateway | process-engine |
| `ai.flowx.core.message.event.process.v1` | webhook-gateway | process-engine |

On the producers, the start-for-event topic is set via `KAFKA_TOPIC_TRIGGER_STARTFOREVENT_PROCESS_OUT` (file-gateway) and `KAFKA_TOPIC_PROCESS_START_OUT` (webhook-gateway); process-engine consumes it via `KAFKA_TOPIC_PROCESS_STARTFOREVENT_IN`. The message event topic uses `KAFKA_TOPIC_PROCESS_EVENT_MESSAGE` on both webhook-gateway and process-engine. Like every service, file-gateway and webhook-gateway also publish to the shared audit topic `ai.flowx.core.trigger.save.audit.v1` via `KAFKA_TOPIC_AUDIT_OUT` (consumed by audit-core).

***

## Environment variables

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Data-sync: Keycloak admin credentials

The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak on first run, using the Keycloak admin API. Configure the following on the data-sync job:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak` (the only supported provider). | `keycloak` | data-sync |
| `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` | data-sync |
| `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` | data-sync |
| `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` | data-sync |
| `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Typically `admin-cli` for standard Keycloak deployments. Must be set explicitly. There is no default. | `-` | data-sync |

For full data-sync configuration, see [Data-sync job setup](/5.9/setup-guides/data-sync#openid-provider-configuration).

### Anonymous service account: shared client secret

5.9.x introduces a single shared service-account client, `flowx-anonymous-sa`, used by FlowX backend services for inter-service calls on anonymous (unauthenticated) runtime flows. One client secret is reused across all consumers — it must be provided in two places.

**On `authorization-system`** — passed to Liquibase so the client is provisioned with the correct secret when FlowX manages Keycloak:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXANONYMOUSSA` | Client secret used by Liquibase to create the `flowx-anonymous-sa` client in the service-accounts realm at first boot. Required when `SECURITY_KEYCLOAKADMINENABLED=true`. | `-` | `authorization-system` |

**On every consuming service** — the Spring Security OAuth2 client registration for the `anonymousidentity` alias resolves the same secret at runtime:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_ANONYMOUSIDENTITY_CLIENTSECRET` | Client secret for the `anonymousidentity` registration. **Must be the same value across every service** — it is a single shared service account. | `-` | `admin`, `application-manager`, `authorization-system`, `document-plugin`, `email-gateway`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `mock-server`, `nosql-db-runner`, `organization-manager`, `process-engine`, `scheduler-core`, `task-management-plugin`, `webhook-gateway` |

> [!WARNING]
>
> This is a secret. Store it in your secrets management solution (e.g., Kubernetes Secret, Vault) and reference it from there. Never commit it to version control.

For the Keycloak-side context (`flowx-anonymous-sa` client, `SA_FLOWX_ANONYMOUS` realm role, manual-configuration recipe for deployments without Keycloak admin access), see [Manual Keycloak configuration](/5.9/setup-guides/access-management/configuring-an-iam-solution#manual-keycloak-configuration).

### Knowledgebase-rag: Qdrant search tuning

Two env vars control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Defaults are tunable per environment.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. | `100` | knowledgebase-rag |
| `QDRANT_FUSION_LIMIT` | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker input. | `80` | knowledgebase-rag |

Raise both when recall is insufficient on very large or long-tailed Knowledge Bases. Lower them when Qdrant pods report memory pressure or filter-heavy queries time out.

### CORS handling: `APPLICATION_CORS_ALLOWORIGIN`

CORS is enforced at the application layer. Each backend service exposed via admin or public URLs reads its allowed-origin list from a single environment variable. Allowed methods, allowed headers, exposed headers, and credential handling are baked into each service's `application.yaml` with safe defaults. The 5.9.x default allow-headers set is `Accept, Content-Type, Authorization, Fx-Workspace-Id, Fx-Client-Host, Referer, User-Agent, Flowx-Platform, X-Fx-Anonymous-Session-Id, Fx-BuildId, Fx-AppId`, and `X-Fx-Anonymous-Session-Id` is exposed to the browser for anonymous runtime sessions. Only `APPLICATION_CORS_ALLOWORIGIN` is deployment-specific.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains (`https://*.yourcompany.com`). Must include every Designer, runtime renderer, and integration domain that calls FlowX APIs. | `-` | `admin`, `ai-gateway`, `application-manager`, `audit-core`, `authorization-system`, `cms-core`, `document-plugin`, `events-gateway`, `file-gateway`, `integration-designer`, `license`, `notification-plugin`, `organization-manager`, `process-engine`, `runtime-manager`, `task-management-plugin`, `webhook-gateway` |
| `APPLICATION_CORS_EXPOSEDHEADERS` | Response headers exposed to browser JavaScript. The default carries the anonymous-session header; override only if you need to expose additional custom headers. | `X-Fx-Anonymous-Session-Id` | all services (shared security library) |

For migration guidance and the full list of removed NGINX CORS annotations, see [Ingress routing and CORS](/5.9/migrating-from-5.1-lts/ingress-routing).

### Process-engine and integration-designer: native script engine

The default script engine for JavaScript and Python execution is a **native subprocess pool**. Scripts run in isolated Node.js and Python worker processes.

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider | `native` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size | `16` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTABLE` | Path to the Node.js binary | `/usr/bin/node` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS script execution timeout (ms) | `5000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXEXECUTIONSPERWORKER` | Max executions before a JS worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_MAXPAYLOADSIZEBYTES` | Max JS input payload size (bytes) | `1048576` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size | `8` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTABLE` | Path to the Python 3 binary | `/usr/bin/python3` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python script execution timeout (ms) | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXEXECUTIONSPERWORKER` | Max executions before a Python worker is recycled | `10000` | process-engine, integration-designer |
| `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_MAXPAYLOADSIZEBYTES` | Max Python input payload size (bytes) | `1048576` | process-engine, integration-designer |

To use GraalVM instead of the native engine, set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services.


# FlowX.AI 5.9.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.0-june-2026/v5.9.0-june-2026

First LTS in the 5.9.x family. Brings conversational AI, UI Flows and Custom Components, AI Platform, runtime authorization, new React Native and iOS UI Flow SDKs, and a wide set of integration and process-ops improvements.

[FlowX.AI 5.9.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/hero-5.9.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * Self-Hosted Features for self-hosted deployments
> * All Deployments Features available in both self-hosted and SaaS

### What 5.9.0 includes

* **Closes the runtime authorization rewrite**. Per-environment sharing, project-version-scoped roles, data-sync Keycloak provisioning.
* **Brings the full set of changes accumulated since the 5.1.x LTS line**. Conversational AI, UI Flows, Custom Components, AI Platform, runtime authorization.
* **Ships a new React Native SDK** and rounds out iOS UI Flow support.

> [!NOTE]
>
> **5.9.0 is the first LTS in the 5.9.x family** (target 2026-06-02). Monthly LTS patches follow from July 2026. Self-hosted customers upgrading from 5.1.x LTS go directly to 5.9.0. See the [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview) guide for the consolidated upgrade path.

***

**What's in this LTS release?**

> [tab] Runtime authorization and sharing
>
> 🔐 [**Runtime authorization completion**](#runtime-authorization-completion) - Per-environment sharing checklist, project-level end-user roles, data-sync provisioning of Keycloak groups and roles.\
> 🌐 [**Anonymous runtime access**](#anonymous-runtime-access) - Built-in Anonymous role + Share modal "Everyone with the link" for unauthenticated end users; session-bound, SDK auth-skip mode.\
> 🛡️ [**Runtime authorization overhaul**](#runtime-authorization-overhaul) - Project-version-scoped roles, end-user groups moved from Keycloak into FlowX, Solutions → Share modal flow, Active Policy gate, designer-user bypass.\
> 🔒 [**UI Flow permissions**](#ui-flow-permissions) - Per-UI-Flow role allow-list with runtime 403 enforcement; assignments travel with import/export.\
> 👥 [**End-user access management**](#end-user-access-management) - Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.\
> 🎯 [**Active policy: group overrides**](#active-policy-group-overrides) - Override a project's active build per runtime group; legacy role overrides are excluded from runtime resolution and only kept for deletion.\
> 🧩 [**Roles carried across project-version merges**](#roles-carried-across-project-version-merges) - Application-version roles cloned onto the merged version automatically, no manual re-binding after merge.\
> 🏷️ [**Operations-editor role**](#operations-editor-role) - **Workspace operations editor** role and `wks_process_instance_variables_edit` permission for ops teams.\
> 🗂️ [**Cross-workspace projects**](#cross-workspace-projects) - Import the same project into multiple workspaces in the same environment.\
> 🔁 [**Cross-LTS import/export**](#cross-lts-import/export) - Move project versions and builds between the 5.1.x and 5.9.x LTS lines, in both directions.\
> 🚪 [**Log-in page redesign**](#log-in-page-redesign) - IdP provider button replaces the fallback link; refreshed labels across the log-in flow.

> [tab] Conversational AI
>
> 💬 [**Chat component**](#chat-component) - Standalone chat tab; Inline / Floating / FullScreen modes; iOS and Android support; Chat History; Suggested Prompts; Markdown.\
> 🌀 [**Conversational Workflows**](#conversational-workflows) - Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node.\
> 🎙️ [**Voice input + Speech-to-Text**](#voice-input-+-speech-to-text) - Audio recording in chat; Speech-to-Text node for transcription.\
> 🧠 [**Memory capabilities**](#memory-capabilities) - Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full; Use conversation memory toggle on the AI / Custom Agent node.\
> 🧭 [**Intent Classification node**](#intent-classification-node) - LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.\
> 💭 [**Chat-based UI Flows**](#chat-based-ui-flows) - Flow-Based vs Chat-Based experience type set at the UI Flow level.\
> ⚡ [**AI Triggers**](#ai-triggers) - Named parameterized message templates to launch conversational workflows with context.\
> 🏷️ [**Chat title generation and conversation search**](#chat-title-generation-and-conversation-search) - Auto-generated session titles + cross-conversation search on the chat history.\
> 🛑 [**Stop agent response**](#stop-agent-response) - Stop button while streaming; cancels the underlying workflow.

> [tab] AI Agents and Knowledge
>
> 📊 [**Evaluations (Evals)**](#evaluations) - LLM-as-judge, RAG-quality, and code evaluators score AI node outputs; datasets, experiments, per-org judge model via new `EVAL` capability.\
> 🤖 [**Custom Agent nodes**](#custom-agent-nodes) - AI agents that use MCP tools to act autonomously in workflows.\
> 🔎 [**Web Search tool for Custom Agents**](#web-search-tool-for-custom-agents) - Built-in web search so Custom Agents can look up up-to-date public-web information during a run.\
> 🔌 [**MCP integration**](#mcp-integration) - MCP servers as data sources; tools in Custom Agent nodes; OAuth 2.0, BEARER, BASIC auth.\
> 📖 [**Knowledge Bases**](#knowledge-bases) - PDF upload, workflow ingestion, semantic search, Custom Agent integration; Stores rename + typed filter builder; system metadata; Kafka indexer/embedder.\
> 🧰 [**AI Providers self-service**](#ai-providers-self-service) - Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability.\
> 🛡️ [**PII Guard: per-entity detections on documents and images**](#pii-guard-per-entity-detections-on-documents-and-images) - Document and image scans return the same per-entity detection list as text scans, with bounding regions.\
> 📝 [**Operational prompt split**](#operational-prompt-split) - System prompt split into operational guardrails and user-instruction layers, versioned independently.\
> 📄 [**Extract Data from File**](#extract-data-from-file) - LLM / OCR / Text Parsing strategies; image input; signature detection.\
> 🌐 [**Web Page Extractor / Web Crawler**](#web-page-extractor-/-web-crawler) - Static or dynamic URLs, link-following depth, PDF extraction, URL filtering, file downloads, multi-URL filters.\
> 📚 [**Manage Knowledge Base content from Runtime**](#manage-knowledge-base-content-from-runtime) - End users can add and update KB content at runtime without going back to the Designer.\
> ✨ [**AI Developer generates Custom Components**](#ai-developer-generates-custom-components) - Pre-built agent drafts React Custom Components from a brief.

> [tab] UI Flows and Custom Components
>
> 🪟 [**UI Flows**](#ui-flows) - Reusable multi-platform UI as project resources; Sessions monitoring; Process Renderer; Route Management; Start Parameters; Session Variables; onClick / On Display / On Load events.\
> ⏳ [**UI Flow session expiry**](#ui-flow-session-expiry) - Expire a UI Flow after a duration or on a schedule; expired sessions become read-only.\
> 🖼️ [**Configurable modal component**](#configurable-modal-component) - Title, subtitle, dismiss behavior, alignment and sizing on modals; theme-level shadow and dismiss icon.\
> 💻 [**Custom Components**](#custom-components) - React JSX / CSS in the Designer; Custom Components in Processes with INPUT/OUTPUT mappings.\
> 🎬 [**Event Handlers**](#event-handlers) - Typed Event Handlers section in the UI component config panel; UI events and AI triggers unified under one model.\
> ♿ [**Accessibility (WCAG 2.1 AA)**](#accessibility-wcag-2-1-aa) - Cross-platform accessibility model surfaced in the UI Designer.\
> 🧱 [**New theme components**](#new-theme-components) - Tooltip, Markdown, Progress Bar, Separator across React / Angular / Android.\
> 📤 [**Multi-file bulk upload**](#multi-file-bulk-upload) - Multiple File Upload on process screens and UI Flows; Angular and React SDK support.\
> 🎨 [**Theming and Designer polish**](#theming-and-designer-polish) - Scoped variants and padding for form labels/errors/helpers, mandatory-label style.

> [tab] Integration and Data Platform
>
> 📨 [**Email Trigger**](#email-trigger) - IMAP-triggered processes; attachments to the `document-plugin`; validation rules.\
> 📧 [**Microsoft Outlook data source**](#microsoft-outlook-data-source) - Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes.\
> 🪝 [**Incoming Webhooks**](#incoming-webhooks) - New `webhook-gateway` microservice; trigger processes via HTTP POST; Slack provider adapter.\
> 🗄️ [**Oracle Database integration**](#oracle-database-integration) - Oracle 21c / 23ai data source; schema-aware Monaco editor.\
> 🍃 [**Unmanaged MongoDB data source**](#unmanaged-mongodb-data-source) - Connect to externally managed MongoDB 6.0+ instances.\
> 📁 [**File Storage data source**](#file-storage-data-source) - Move files in and out of external FTP / SFTP / S3 / Azure Blob storage from workflows.\
> 📨 [**Meta webhook provider**](#meta-webhook-provider) - WhatsApp / Messenger / Instagram / Threads webhook support with verify-token handshake and X-Hub-Signature-256 verification.\
> 📂 [**Documents in process instances**](#documents-in-process-instances) - Dedicated Documents section on each process instance.\
> 📤 [**Send Notification action + Email Sender**](#send-notification-action-+-email-sender) - SMTP data source; new action sends or replies email directly without Kafka.\
> 🎛️ [**Advanced Query Builder**](#advanced-query-builder) - Visual query builder replacing manual JSON, with new operators.\
> 🧬 [**Parallel branches in workflows**](#parallel-branches-in-workflows) - Start / End Parallel nodes for concurrent execution.\
> ⚡ [**REST endpoint caching + workflow partitioning**](#rest-endpoint-caching-+-workflow-partitioning) - TTL-based REST GET caching; time-based workflow partitions with retention.\
> 🔗 [**Data mappers + workflow data models**](#data-mappers-+-workflow-data-models) - Workflow data models with input/output; process ↔ workflow mapping; CRUD endpoints.\
> 🛡️ [**Proxy Server Connections**](#proxy-server-connections) - Reusable HTTP/HTTPS proxies attached to REST data sources.\
> ✉️ [**Two-stage attachment filtering for Email triggers**](#two-stage-attachment-filtering-for-email-triggers) - Choose which emails trigger the process and which attachments are forwarded into it.\
> ⏸️ [**Resume a process from an incoming webhook**](#resume-a-process-from-an-incoming-webhook) - Webhooks now drive Message Catch Intermediate Events with a Process Correlation Key.\
> 🌐 [**REST endpoints: content-type-aware responses**](#rest-endpoints-content-type-aware-responses) - Accept-driven JSON / text / XML parsing with XXE-safe XML; responses over 5 MiB are returned raw.\
> 📝 [**Raw endpoint payload type**](#raw-endpoint-payload-type) - Send request body as-is with the user's Content-Type preserved; XML / SOAP / form-urlencoded / plain text without MULTIPART wrapping.

> [tab] Process operations
>
> ✏️ [**Update Process Variables**](#update-process-variables) - JSON editor for variables on active instances; snapshot history; Compare diff.\
> 🛑 [**Stop workflow instances in runtime**](#stop-workflow-instances-in-runtime) - Authorized end users can stop running workflow instances from runtime.\
> ⏹️ [**Stop Run for workflows**](#stop-run-for-workflows) - Cancel a running workflow instance from the editor.\
> 🔔 [**Notification history + template usages**](#notification-history-+-template-usages) - `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all references.\
> 📋 [**Token view improvements**](#token-view-improvements) - Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, color-coded status.\
> 🔧 **Fixed: names with square brackets** - Processes and UI flows whose names contain square brackets now start correctly again.

> [tab] Platform, deployment and infrastructure
>
> 🏢 [**Single-org self-hosted deployment**](#single-org-self-hosted-deployment) - Self-hosted default mode; guided setup wizard.\
> 🔑 [**License service**](#license-service) - Centralized license validation and usage reporting for self-hosted deployments.\
> 🔐 [**Authentication: opaque-token → JWT**](#authentication-opaque-token-→-jwt) - Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key`; dedicated service-accounts realm.\
> 🆕 [**New services to deploy**](#new-services-to-deploy) - `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. None existed in a 5.1.x deployment.\
> 🐍 [**Native script engine for JavaScript and Python**](#native-script-engine-for-javascript-and-python) - Default JS/Python execution moves from GraalVM to a Node.js + CPython subprocess pool; GraalVM available as opt-in.\
> 🌐 [**Ingress routing and CORS handling**](#ingress-routing-and-cors-handling) - NGINX ingress controller deprecated as the FlowX-shipped default; CORS moves to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on every backend service.\
> 📡 [**Kafka configuration alignment**](#kafka-configuration-alignment) - Standardized `KAFKA_*` env vars; mandatory `Fx-Organization-Id` header.\
> 📊 [**OpenTelemetry + SpiceDB DR**](#opentelemetry-+-spicedb-dr) - OpenTelemetry / Prometheus Helm charts published; SpiceDB backup and disaster-recovery procedures.\
> 🛡️ [**Durable message-processing**](#durable-message-processing) - Parked integration responses are persisted durably so in-flight responses survive runtime restarts, reducing stuck process tokens.\
> 🌍 [**Task management localization**](#task-management-localization) - 51 substitution tags + automatic table grid localization across 30 languages.

> [tab] Mobile & Renderers
>
> 📱 [**React Native SDK**](#react-native-sdk) - New SDK for React Native apps with process renderer, forms, navigation, and CMS integration. Demo app included.\
> 🍎 [**iOS UI Flows support**](#ios-ui-flows-support) - Full UI Flows renderer on iOS; sessions, document plugin subtypes, dismiss action, start parameters, new native components.\
> 📲 [**Mobile chat support**](#conversational-ai) - Chat component available on iOS and Android.\
> ⚛️ [**React 19 upgrade**](#react-19-upgrade) - React SDK upgraded to React 19; host apps must upgrade in lockstep.

> [tab] Info
>
> ℹ️ [**Deployment guidelines**](./deployment-guidelines-v5.9) - Component versions, environment variables, Kafka topics\
> 🗺️ [**Migrating from 5.1 LTS**](/5.9/migrating-from-5.1-lts/overview) - Consolidated upgrade path from 5.1.x LTS to 5.9.x LTS

> [card]
>
> ### **Runtime authorization completion**
>
> 5.9.0 completes the project-version-scoped runtime authorization model:
>
> * **Sharing checklist for environment promotion.** Sharing assignments do not export with builds. Each environment must be reconfigured when a project is promoted. The deployment checklist for this is now part of the setup guide.
> * **Project-level end-user roles.** Roles can be assigned at the project level from creation, so a fresh project is reachable without a separate share pass.
> * **Data-sync provisioning.** The data-sync job calls the Keycloak admin API on first run to provision FlowX-managed end-user groups and runtime roles. Five new `FLOWX_OPENID_*` env vars expose the admin credentials.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > See Setup guides → Access management → Runtime authorization for the day-to-day model.
>
> > [accordion] Key Features
> >
> > * **Per-environment sharing checklist.** When you promote a project from dev to uat to prod, the Share modal assignments do not travel with the build. The setup guide now documents the explicit per-environment reconfiguration step.
> > * **Project-level end-user roles.** Assign end-user roles at the project level so a freshly created project is reachable on day one. No separate Share-modal pass required for the default access pattern.
> > * **Data-sync Keycloak provisioning.** The data-sync job provisions FlowX-managed end-user groups and runtime roles in Keycloak the first time it runs against a 5.9.0 environment. Configure admin credentials with the new `FLOWX_OPENID_*` env vars on the data-sync job.
> > * **Deployment checklist included.** The runtime authorization setup guide now ships a deployment prerequisites section so the data-sync OpenID config and per-environment sharing reset are part of the standard promotion runbook.
>
> > [accordion] Configuration
> >
> > Required on the data-sync job from 5.9.0 onward:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `FLOWX_OPENID_PROVIDER` | OpenID provider type. Set to `keycloak`. | `keycloak` |
> > | `FLOWX_OPENID_SERVERURL` | Base URL of the Keycloak server, including the `/auth/` path. | `-` |
> > | `FLOWX_OPENID_USER` | Username of a Keycloak admin account that can manage groups and roles in the FlowX realm. | `-` |
> > | `FLOWX_OPENID_PASSWORD` | Password for the admin account above. Store in a Kubernetes Secret. | `-` |
> > | `FLOWX_OPENID_CLIENTID` | Keycloak admin client used to obtain the admin token. Set to `admin-cli` for standard Keycloak deployments. | `-` |
> >
> > See [Data-sync job setup → OpenID provider configuration](/5.9/setup-guides/data-sync#openid-provider-configuration) for the full setup.

> [card]
>
> ### **Anonymous runtime access**
>
> 5.9.0 introduces unauthenticated runtime access: an app can be made publicly reachable, and processes or UI flows inside it can be opened to anonymous end users via a new built-in role.
>
> * **Two independent gates.** The app must be set to **Everyone with the link** in the Share modal AND the process or UI flow must have the **Anonymous** role assigned. If either gate is closed, the runtime returns `403 Forbidden` (`Anonymous access not enabled for this application` / `Anonymous access not enabled for this build`).
> * **System-level Anonymous role.** Auto-seeded on every new app version, cannot be deleted or edited; allowed operations are `VIEW`, `EXECUTE`, and an auto-populated `SELF_ASSIGN`.
> * **Session-bound traffic.** Anonymous requests carry an `X-Fx-Anonymous-Session-Id` header. The backend issues a new session ID on first contact; instances are bound to that session and cannot be read by another.
> * **SDK auth-skip.** The renderer decides authenticated vs anonymous from the `authToken` parameter at initialization. Token-in-storage on the same browser silently bypasses anonymous mode — container apps must scrub the `Authorization` header on public routes.
>
> Self-HostedAll Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/user-roles-management/anonymous-runtime-access)
> >
> > See Platform deep-dive → User roles management → Anonymous runtime access for the full feature reference.
>
> > [accordion] Key Features
> >
> > * **Share modal public-access option.** A new **General access** section in the Share modal switches between **Everyone with the link** and **Only invited users and groups**. Default remains invited-only.
> > * **Anonymous role on processes, UI flows, and reusable UI templates.** Selectable in the Permissions tab once the role is on the version; additive to other roles.
> > * **Component hide / disable rules.** UI Designer supports an Anonymous condition in role-based hide/disable rules at the component level.
> > * **Public-build asset rule.** When a build has the Anonymous role and the app is shared publicly, all assets inside (enumerations, substitution tags, media files, themes, fonts) become reachable anonymously — except UI flows and processes that don't carry the Anonymous role.

> [card]
>
> ### **Runtime authorization overhaul**
>
> Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/runtime-authorization)
> >
> > Open the **Runtime authorization overhaul** documentation.

> [card]
>
> ### **UI Flow permissions**
>
> Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#ui-flow-permissions)
> >
> > Open the **UI Flow permissions** documentation.

> [card]
>
> ### **End-user access management**
>
> Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/end-user-access-management)
> >
> > Open the **End-user access management** documentation.

> [card]
>
> ### **Operations-editor role**
>
> New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> All Deployments
>
> > [card] [Documentation](/5.9/setup-guides/access-management/roles-permissions-matrix)
> >
> > Open the **Operations-editor role** documentation.

> [card]
>
> ### **Cross-workspace projects**
>
> Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/workspaces#cross-workspace-project-import)
> >
> > Open the **Cross-workspace projects** documentation.

> [card]
>
> ### **Cross-LTS import/export**
>
> Move project versions and builds between the **5.1.x** and **5.9.x** LTS lines, in both directions. A newer platform version imports exports produced by an older one, and exports produced on a newer version can target an older one — useful for shipping a hotfix to an environment that hasn't been upgraded yet. Compatibility is patch-agnostic: any 5.9.x patch works with any 5.1.x patch.
>
> When exporting to an older version, resources whose type doesn't exist there are excluded automatically and listed in a `manifest_excluded.json` file in the archive, so the import still succeeds. The lowest version in the export/import path defines the usable functionality.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import)
> >
> > Open the **Cross-version export and import** documentation.

> [card]
>
> ### **Active policy: group overrides**
>
> Active policy overrides can now target **runtime groups** instead of runtime roles. The override resolves the active build for every member of the group at runtime, with a priority field deciding which group wins when a user belongs to several.
>
> Role-based overrides are deprecated in the same change. The **Role** override type is gone from the Add / Edit modal, and any role overrides carried over from a 5.1.x upgrade are kept in the table for visibility only — they are flagged **DEPRECATED**, excluded from runtime resolution, and can only be deleted.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-policy)
> >
> > See Projects → Runtime → Active policy for the full configuration model.
>
> > [accordion] Key Features
> >
> > * **Group override type.** Add / Edit Policy Override now exposes **Username** and **Group**. The group picker lists runtime groups that have a runtime role configured for the current project.
> > * **Priority is mandatory and unique per project for group overrides.** Lower numbers win when several groups match the same user. Username overrides ignore priority and always take precedence.
> > * **Resolution order.** Username override → Group override (lowest priority wins) → Global policy.
> > * **Role overrides deprecated.** Removed from the Add / Edit modal. Existing role rows are rendered muted with a **DEPRECATED** marker and a red banner; only the delete action remains. Deprecated role overrides are excluded from runtime resolution.
> > * **Test panel.** The effective-policy test panel simulates resolution for a given user.
> > * **Audit log.** Group override create / update / delete / enable / disable events are recorded.
>
> > [accordion] Upgrade impact
> >
> > Upgrading from 5.1.x carries existing role overrides into the new table as deprecated entries. They no longer affect runtime behavior. Recreate the intended access using group overrides and delete the role rows. See [Migrating from 5.1 LTS → Runtime authorization](/5.9/migrating-from-5.1-lts/runtime-authorization) for the conversion steps.

> [card]
>
> ### **Roles carried across project-version merges**
>
> Application-level role definitions are now carried into the merged project version automatically. Before 5.9.0, merging two project versions could leave the role table in a partial state. Bindings defined on one side were not consistently propagated to the merged version. 5.9.0 clones the roles from the destination latest version onto the merged version atomically as part of the merge transaction, so merges with role changes complete without follow-up manual cleanup.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Roles propagated as part of the merge.** When a project version is merged, application-version roles from the destination latest version are cloned onto the merged version in the same transaction.
> > * **No manual role re-binding after merge.** Operators no longer need to re-apply role bindings on the merged version. The merge completes in a single commit; the merged version is immediately usable.

> [card]
>
> ### **Log-in page redesign**
>
> The Designer log-in page is refreshed to align with the platform's design system. When an organization has an external IdP configured, the previous fine-print fallback link is replaced with a primary button labeled with the IdP configuration's **Display name**. Field labels and call-to-action copy across the log-in flow are aligned with the rest of the UI.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **IdP provider button.** When the organization has an IdP configured, the log-in screen surfaces a primary button labeled with the IdP's **Display name**, instead of a fine-print link below the form.
> > * **Refreshed copy.** Updated labels across the flow: **Log In** replaces *Sign In*, **Reset Password** replaces *Forgot password?*, and the page title becomes **Log In**.

> [card]
>
> ### **Chat component**
>
> Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component)
> >
> > Open the **Chat component** documentation.

> [card]
>
> ### **Conversational Workflows**
>
> Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/conversational-workflows)
> >
> > Open the **Conversational Workflows** documentation.

> [card]
>
> ### **Voice input + Speech-to-Text**
>
> Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/speech-to-text)
> >
> > Open the **Voice input + Speech-to-Text** documentation.

> [card]
>
> ### **Memory capabilities**
>
> Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/memory-capabilities)
> >
> > Open the **Memory capabilities** documentation.

> [card]
>
> ### **Intent Classification node**
>
> Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/intent-classification)
> >
> > Open the **Intent Classification node** documentation.

> [card]
>
> ### **Chat-based UI Flows**
>
> UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#experience-types)
> >
> > Open the **Chat-based UI Flows** documentation.

> [card]
>
> ### **AI Triggers**
>
> Named parameterized message templates to launch conversational workflows with context.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-driven-workflows#ai-triggers)
> >
> > Open the **AI Triggers** documentation.

> [card]
>
> ### **Stop agent response**
>
> Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/chat-component#stop-agent-response)
> >
> > Open the **Stop agent response** documentation.

> [card]
>
> ### **Chat title generation and conversation search**
>
> Chat sessions now get a meaningful title generated automatically from the user's first message. No more "untitled chat" entries in the history. End users can also search across all their conversations with a single query that scans both message bodies and session titles.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Auto-generated session title.** The first user message seeds a provisional title (first 7 words). A one-shot LLM call then refines it into a concise descriptive title; the chat list updates live via an SSE event.
> > * **Conversation search.** `/api/conversations` accepts a `q` query parameter (2–200 characters). Matches against both session titles and message bodies. Each result carries a `snippet` field showing the matched excerpt.
> > * **Title update event.** When the LLM title is generated, the gateway emits a `chatSessionRenamed` event on the chat session channel; the chat list shows the refined title on the next load.
> > * **Single-shot generation.** Title generation runs exactly once per session, on first persist. The provisional 7-word title remains in place if the LLM call fails. No error surfaces to the end user.

> [card]
>
> ### **Evaluations**
>
> 5.9.0 introduces Evaluations: score AI node outputs against test cases using LLM-as-judge, RAG-quality, and code evaluators. Attach datasets to AI nodes, launch experiments, and read per-evaluator aggregate scores plus per-test-case details.
>
> * **10 built-in evaluators across three categories.** LLM-as-judge (Correctness, Conciseness, Hallucination, Answer relevance), RAG (Groundedness, Helpfulness, Retrieval relevance), and Code (Exact match, Levenshtein, JSON match). Numeric evaluators ship with default thresholds; binary evaluators return pass/fail.
> * **Datasets attached to AI nodes.** Test cases sourced manually or captured from real node executions. The dataset persists a schema snapshot so older runs remain reproducible if the workflow changes underneath.
> * **Async judge pipeline.** A new Python `evals-judge` event-driven worker consumes `ai.flowx.ai-platform.evals-judge.job.request.v1`, scores each (test case × evaluator) pair via the configured judge LLM, and publishes back on the response topic. Unscored jobs land on a DLQ for manual review.
> * **Per-org judge model.** A new `EVAL` capability is registered in the org-manager LLM catalogue. Platform default is `gpt-5.4-mini`, backfilled per org on upgrade so evals work out-of-the-box.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/evaluations)
> >
> > See AI Platform → Evaluations for the user workflow, evaluator catalogue, REST API surface, and operator setup.
>
> > [accordion] Key Features
> >
> > * **Designer workflow.** Add a dataset on an AI node, add test cases (manually or captured from a node execution), pick evaluators, launch an experiment, read aggregate + per-test-case reports.
> > * **LLM-as-judge scoring.** A judge LLM reads the model output (and optional expected output) and scores it on a single rubric, returning a numeric score plus its reasoning.
> > * **RAG-quality scoring.** Judges the retrieval side of a RAG workflow — is the retrieved context grounded, helpful, and relevant?
> > * **Deterministic code evaluators.** No LLM call. Exact match, normalized Levenshtein, and JSON-shape match against the dataset's output contract.

> [card]
>
> ### **PII Guard: per-entity detections on documents and images**
>
> PII Guard scans on document and image AI nodes now surface the same per-entity detection list already shown for text scans. The run console reports each match with its entity type, confidence, original value, and replacement, making it easy to verify what was redacted on file-based AI inputs.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Same shape as text scans.** Document and image scans now return a `detections` list with `entityKey`, `confidence`, `originalValue`, `replacement`, and `direction`, matching the existing text-scan output.
> > * **Bounding regions for document and image hits.** Each detection on a `DOCUMENT` or `IMAGE` source includes `regions` (`x`, `y`, `width`, `height`) so the run console can highlight where the entity was matched.
> > * **Source-type tagging.** Detections carry a `sourceType` of `TEXT`, `DOCUMENT`, or `IMAGE`, mirroring the wrapper's `sourceType` field so audit consumers can attribute matches to the right payload.
> > * **Backward-compatible upgrade.** On older data-privacy versions that don't yet return the analyzer pass for object endpoints, `detections` stays empty and the redacted artifacts continue to be produced and downloadable.

> [card]
>
> ### **Custom Agent nodes**
>
> AI agents that use MCP tools to act autonomously inside workflows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/custom-agent-node)
> >
> > Open the **Custom Agent nodes** documentation.

> [card]
>
> ### **Web Search tool for Custom Agents**
>
> Custom Agent nodes can call a built-in web search tool to look up up-to-date information from the public web during a run. Turn it on with a single toggle — the agent decides when to search based on its instructions and the user's request.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Single toggle.** Enable **Tools → Built-in tools → Use Web Search Tool** on a Custom Agent node. Off by default; no extra configuration.
> > * **Agent-driven.** The agent calls web search on its own when the task needs current information, and folds the results into its response.

> [card]
>
> ### **MCP integration**
>
> MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/mcp-integration/mcp-integration-overview)
> >
> > Open the **MCP integration** documentation.

> [card]
>
> ### **Knowledge Bases**
>
> Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview)
> >
> > Open the **Knowledge Bases** documentation.

> [card]
>
> ### **AI Providers self-service**
>
> Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/ai-providers)
> >
> > Open the **AI Providers self-service** documentation.

> [card]
>
> ### **Extract Data from File**
>
> LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/extract-data-from-file)
> >
> > Open the **Extract Data from File** documentation.

> [card]
>
> ### **Web Page Extractor / Web Crawler**
>
> Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/web-page-extractor)
> >
> > Open the **Web Page Extractor / Web Crawler** documentation.

> [card]
>
> ### **Context Retrieval**
>
> RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/agent-builder/context-retrieval)
> >
> > Open the **Context Retrieval** documentation.

> [card]
>
> ### **AI Developer generates Custom Components**
>
> Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.
>
> All Deployments
>
> > [card] [Documentation](/5.9/ai-platform/pre-built-agents/ai-developer)
> >
> > Open the **AI Developer generates Custom Components** documentation.

> [card]
>
> ### **Operational prompt split**
>
> The single Operation Prompt field on AI nodes is split into two inputs so the static portion of the prompt can be cached by the LLM provider while dynamic values are passed separately. **Instructions** holds the agent's role, tasks, and expected I/O, sent as the System message and cached between executions, so `${}` dynamic values are not allowed. The **Context** field, inside the **Background** section, takes the dynamic per-execution prompt text and supports `${}` references, sent as the User message and not cached.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Instructions: cached System message.** Mandatory. Holds the agent's role, tasks, and expected input/output. Sent as the System message and cached by the LLM between executions. `${}` references are rejected to keep the cache key stable.
> > * **Background section: dynamic User message.** Wraps the Knowledge Base selector, the **Context** textarea (free text with `${}` support), the **Use only referenced values as input** toggle, and, in Chat Driven workflows, the **Use conversation memory** toggle. Sent as the User message on every execution; not cached.
> > * **Lower LLM cost and latency.** The static portion of the prompt is sent once per cache window instead of on every execution, so each call pays only for the dynamic Background section. The longer the Instructions, the bigger the per-call saving.
> > * **Applies to every AI node subtype.** The split UI is now shared by all AI node subtypes that previously used the single Operation Prompt field.

> [card]
>
> ### **Manage Knowledge Base content from Runtime**
>
> A new **Test KB** option on the build is available in runtime, giving operators visibility into Knowledge Base content that was previously opaque after deployment. Authorized users can inspect chunks, add or replace sources, edit metadata, and query the KB without going back to the Designer. Useful for debugging retrieval issues and keeping KBs current as business knowledge evolves.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Six runtime operations.** Create store, Append content, Replace content, Delete store, Edit metadata, and Query. All from the Test KB option inside the running app.
> > * **Files and payloads.** Both file uploads and inline payloads can be added to the KB through this feature.
> > * **Permission-gated.** KB management at runtime is controlled by runtime authorization, so only users with the right role see the Test KB controls.
> > * **Visibility into chunking.** Inspect how documents were chunked and what metadata was captured, useful when debugging retrieval quality on client-uploaded content.

> [card]
>
> ### **UI Flows**
>
> 5.9.0 closes the UI Flows feature: reusable, multi-platform UI (web, iOS, Android) as first-class project resources with their own lifecycle and runtime sessions. UI Flows now reach feature parity with processes for end-user-facing apps that don't need a BPMN process underneath.
>
> * **Multi-platform.** Author once in the Designer; UI Flows render on web (React), iOS, and Android via the platform-specific renderers. Layouts and component bindings travel together as a single resource.
> * **Sessions and runtime monitoring.** Each UI Flow run is a `UiFlowSession` with its own state, navigation history, and SSE event stream. Operators can monitor and inspect sessions from the runtime.
> * **Process integration.** UI Flows can start processes (Start Process action), navigate to other UI Flows (Navigate UI action), and embed a Process Renderer to show a running process inside a UI Flow. Workflows can also be invoked from a UI Flow with a Start Workflow action.
> * **Per-UI-Flow permissions.** A dedicated Permissions tab on each UI Flow controls which roles can run it. Runtime enforces with `403`; assignments travel with import/export.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows)
> >
> > See Building blocks → UI Flows for the full feature reference, including Navigation Areas, session variables, route management, and the component reference.
>
> > [accordion] Key Features
> >
> > * **Navigation Areas.** Group UI components into named areas for layout, scroll, and per-area transitions.
> > * **Start Parameters and Session Variables.** Pass typed inputs into a UI Flow at start; persist state across nodes via Session Variables.
> > * **Route management.** Each UI Flow exposes a stable runtime route; nested navigation preserves browser history and back/forward behaviour.
> > * **Task Manager component.** Drop the Task Manager surface inside a UI Flow to drive process tasks from the same UI shell.
> > * **onClick and On Display events, plus a new On Load event.** Component-level events trigger workflows or UI actions, with the new On Load event firing when the UI Flow first opens.
> > * **Breadcrumbs.** Built-in breadcrumbs reflect the Navigation Area hierarchy and follow the active theme.
> > * **Process Renderer + Start Workflow action.** Embed a running process inside a UI Flow; trigger an integration workflow from a button or event without leaving the flow.

> [card]
>
> ### **UI Flow session expiry**
>
> A UI Flow session can be set to expire automatically after a fixed duration or on a schedule. Once expired, the session becomes read-only — the user keeps the data already loaded but cannot take further action.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Flexible expiry.** Set the **Expiry time** in **Settings → General** as an ISO-8601 duration (for example `PT3M22S`) or a cron expression (for example `0 0 9-17 * * MON-FRI`). Empty means no expiry.
> > * **Read-only on expiry.** Expired sessions block all actions; loaded data stays visible and nothing is wiped.
> > * **Server-enforced.** The platform marks sessions `EXPIRED` server-side, so it applies the same way in the deployed app and the Designer preview.

> [card]
>
> ### **Configurable modal component**
>
> Modals on process screens and UI Flows gain configurable content and layout. Set a title and subtitle, control dismiss behavior, and align and size the modal from the Designer.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Content.** Set the modal **Title** and **Subtitle** from the Settings panel.
> > * **Dismiss behavior.** Toggle **Dismissible**, allow **Backdrop click**, and optionally show a **Confirmation alert** with custom title, message, and button labels.
> > * **Layout.** Align content **Left**, **Center**, or **Right**, and set **Width**/**Height** to **Fixed** or **Auto**.
> > * **Theme-level styling.** The modal **shadow** and **dismiss icon** are defined once in the theme's Modal section.

> [card]
>
> ### **Custom Components**
>
> Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/reusable-resources/custom-components)
> >
> > Open the **Custom Components** documentation.

> [card]
>
> ### **Process Renderer in UI Flows**
>
> Embed process renderers inside UI Flows.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-flows#process-renderer-component)
> >
> > Open the **Process Renderer in UI Flows** documentation.

> [card]
>
> ### **UI Flow sessions monitoring**
>
> Runtime view with session list, audit log, process tracking, workflow debugging.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/ui-flow-sessions)
> >
> > Open the **UI Flow sessions monitoring** documentation.

> [card]
>
> ### **Accessibility (WCAG 2.1 AA)**
>
> Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> All Deployments

> [card]
>
> ### **New theme components**
>
> Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/tooltip)
> >
> > Open the **New theme components** documentation.

> [card]
>
> ### **Multi-file bulk upload**
>
> Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload)
> >
> > Open the **Multi-file bulk upload** documentation.

> [card]
>
> ### **Card default collapse + Tables in Collections**
>
> Cards configurable to load collapsed; Table UI components inside Collection prototypes.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/ui-designer/ui-component-types/root-components/card)
> >
> > Open the **Card default collapse + Tables in Collections** documentation.

> [card]
>
> ### **Event Handlers**
>
> The UI component configuration panel introduces a dedicated **Event Handlers** section. The legacy `flowx_props` bag is replaced by a typed, per-handler form covering action type, optional analytics, custom body, destination, and collection save-key fields. Container components (Page, Zone, Modal, Tab Bar in UI Flows; Tab on process screens) and inline components resolve their actions through the same model.
>
> Existing UI events and AI triggers are migrated automatically. A Liquibase migration runs on the first 5.9.0 boot and moves the data into the new `ui_action` model. No project re-export or re-import is required.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Typed Event Handlers.** Each handler is a named, typed entity instead of a free-form prop, making configuration easier to validate and audit.
> > * **Action type selector.** Pick the action type from a dropdown that knows which fields are required for that type.
> > * **Analytics, body, destination, save-key.** Per-handler sub-forms cover analytics events, custom request bodies, destination resolution, and collection save-key fields.
> > * **Unified for inline and container components.** Page, Zone, Modal, and Tab Bar containers in UI Flows use the same Event Handlers model as inline components; on process screens, Tab containers use it.

> [card]
>
> ### **Theming and Designer polish**
>
> > [accordion] Theming
> >
> > Form field labels, error messages, and helper text gain padding controls and scoped style variants in the theme model. Theme Admin exposes the new padding properties on segmented buttons, sliders, and input selections; the React and Angular SDKs apply the values in the renderers; the Designer preview reflects them in place. Form fields also pick up a consistent **mandatory label** style applied automatically when a field is required.
> >
> > * **Scoped variants for labels, errors, helpers.** Theme configs can override label, error, and helper styles per component without affecting other parts of the form.
> > * **Padding for segmented buttons, sliders, input selections.** Theme Admin adds label, error, and helper padding controls for these components; values flow through to all renderers.
> > * **Mandatory label style.** A consistent style for mandatory-field labels, applied automatically when a form field is required.
> > * **Designer preview parity.** Theme overrides and paddings are visible in the Designer preview without round-tripping through a runtime app.
> >
> > All Deployments
>
> > [accordion] Designer polish
> >
> > The command center floating action button is now hidden on the running-instance screens of Processes, UI Flows, and UI Templates, where it overlapped with the instance view; it reappears when the instance data panel is open. The command center remains reachable through the standard keyboard shortcut and from screens where it does not interfere.
> >
> > All Deployments

> [card]
>
> ### **Email Trigger**
>
> New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/email-trigger)
> >
> > Open the **Email Trigger** documentation.

> [card]
>
> ### **Microsoft Outlook data source**
>
> Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/microsoft-outlook-data-source)
> >
> > Open the **Microsoft Outlook data source** documentation.

> [card]
>
> ### **Incoming Webhooks**
>
> New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks)
> >
> > Open the **Incoming Webhooks** documentation.

> [card]
>
> ### **Oracle Database integration**
>
> Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL. Beyond tables and `SELECT`, queries can also target views, functions, and stored procedures, with output parameters returned to the workflow.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/oracle-database)
> >
> > Open the **Oracle Database integration** documentation.

> [card]
>
> ### **Unmanaged MongoDB data source**
>
> Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/unmanaged-mongodb)
> >
> > Open the **Unmanaged MongoDB data source** documentation.

> [card]
>
> ### **File Storage data source**
>
> A new data source connecting workflows to external file storage — FTP, SFTP, S3 / S3-compatible, or Azure Blob Storage. Define named List, Download, Upload, Delete, and Move operations scoped to a root path, browse and test them in Designer, and call them from a Data Source node. Operations run in the new `file-gateway` service, exchanging files with the `document-plugin`.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/file-storage)
> >
> > Open the **File Storage data source** documentation.

> [card]
>
> ### **Send Notification action + Email Sender**
>
> SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/actions/send-notification-action)
> >
> > Open the **Send Notification action + Email Sender** documentation.

> [card]
>
> ### **Advanced Query Builder**
>
> Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/flowx-database#visual-query-builder)
> >
> > Open the **Advanced Query Builder** documentation.

> [card]
>
> ### **Parallel branches in workflows**
>
> Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> All Deployments

> [card]
>
> ### **REST endpoint caching + workflow partitioning**
>
> TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> All Deployments

> [card]
>
> ### **Data mappers + workflow data models**
>
> Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/workflow-data-models)
> >
> > Open the **Data mappers + workflow data models** documentation.

> [card]
>
> ### **Proxy Server Connections**
>
> Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/proxy-connections)
> >
> > Open the **Proxy Server Connections** documentation.

> [card]
>
> ### **Faster authoring loop**
>
> 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.
>
> All Deployments

> [card]
>
> ### **Meta webhook provider**
>
> Incoming Webhooks add **Meta** as a built-in provider alongside Generic and Slack, covering WhatsApp, Messenger, Instagram, and Threads. The webhook-gateway handles the Meta-specific subscription handshake and signature verification natively. No custom adapter code required to wire a Meta-platform integration into a FlowX process.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Subscription handshake.** The gateway answers Meta's GET URL-verification request by validating `hub.mode=subscribe` and the provided `hub.verify_token` against the configured verify token, then echoes `hub.challenge` back. Constant-time token comparison.
> > * **X-Hub-Signature-256 verification.** Every POST is authenticated with the `X-Hub-Signature-256` HMAC-SHA256 signature using the configured app secret. Requests with missing or invalid signatures are rejected before reaching the process engine.
> > * **Two secrets per webhook.** When you create a Meta webhook in Integration Designer, two masked inputs appear in the configuration panel: **Verify token** (used during the handshake) and **App secret** (used for signature verification). Both are required.
> > * **Multi-product support.** A single Meta webhook can receive events from WhatsApp, Messenger, Instagram, and Threads. The provider is configured at the webhook level; the channel is part of the payload.
>
> > [accordion] Configuration
> >
> > Select **Meta** in the provider dropdown when creating the webhook data source. Both secret fields are required:
> >
> > | Field | Description |
> > | - | - |
> > | **Verify token** | The token Meta sends back during the GET URL-verification handshake. Choose any string; configure the same value on the Meta App developer console. |
> > | **App secret** | The App secret from the Meta App configuration; used to verify the `X-Hub-Signature-256` HMAC on every POST. |
> >
> > Both values are stored as a JSON-packed pair on the existing webhook secret field. No schema migration is required.
> >
> > See [Incoming Webhooks](/5.9/docs/platform-deep-dive/integrations/incoming-webhooks#meta-provider) for the full setup walk-through.

> [card]
>
> ### **Documents in process instances**
>
> Each process instance now exposes a dedicated **Documents** tab. A single source of truth for every document handled during the process, regardless of how it entered the instance. Operations teams can review tracking metadata, preview, and download attached files from one place rather than walking through the process timeline.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **All document sources in one place.** End-user uploads via the file-upload component, attachments from email triggers, files generated from HTML templates, OCR output, and files produced by AI workflow nodes, all listed under one tab.
> > * **Tracking metadata and preview.** Each row shows source, timestamp, and uploader, with inline preview for supported file types.
> > * **Direct download.** Download any attached document directly from the Documents tab.
> > * **Faster operations review.** No more clicking through the process timeline to reconstruct which file came in at which step.

> [card]
>
> ### **Two-stage attachment filtering for Email triggers**
>
> Email triggers (IMAP and Microsoft Outlook) now expose a two-stage filter on each trigger: choose which incoming emails create a process instance, then choose which attachments are forwarded into the process. The previous single on/off validations toggle is replaced with explicit, per-trigger control over inbound mail.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start Process for.** Trigger the process for all emails, only emails with attachments, or only emails carrying selected file types (PDF, DOCUMENT, IMAGE, EXCEL, ZIP).
> > * **Save email attachments on process.** Forward all attachments, none (metadata-only), or only specific file types into the process instance.
> > * **Trigger-level rejection.** Emails that fail the trigger condition or exceed **Maximum File Count** are rejected with explicit Failed Triggers causes. **No attachments**, **No matching file types**, **File count exceeded**.
> > * **Backward-compatible upgrade.** Existing triggers are migrated to **All incoming emails** + **All attachments** with no manual intervention. Reopen each trigger to reapply file-type filtering if you previously relied on the validations toggle.

> [card]
>
> ### **Resume a process from an incoming webhook**
>
> Incoming Webhooks can now drive a **Message Catch Intermediate Event**, not just a Message Start Event. When a process is paused on an intermediate catch event, an external system can POST to the webhook to resume that specific instance. Useful for callbacks from third-party services, asynchronous job completions, or operator actions delivered over HTTP.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start or resume from one webhook model.** The same webhook data source can start new processes (on a Message Start Event) or resume waiting ones (on a Message Catch Intermediate Event). The trigger type is set automatically based on where the webhook is attached.
> > * **Process Correlation Key.** Each intermediate catch event declares a Process Correlation Key (a business variable like `applicationId`). The webhook-gateway matches this value against the incoming payload to route the resume to the right process instance. The Webhook Correlation Key now accepts array indices in square brackets (`entry[0].changes[0].value.messages[0].text.body`), so the canonical Meta WhatsApp resume path works without flattening upstream.
> > * **Validation at design time.** Process Correlation Key and Process Key are required on intermediate webhook catch events and are validated when the message event is created or updated.
> > * **Backward-compatible upgrade.** Existing webhooks are migrated to `triggerType=START_PROCESS` with no manual intervention. New webhooks attached to an intermediate catch event are flagged `RESUME_PROCESS` automatically.

> [card]
>
> ### **REST endpoints: content-type-aware responses**
>
> REST endpoint responses in Integration Designer are now parsed by content type rather than assumed to be JSON. The endpoint's `Accept` header drives parsing: JSON, plain text, and XML responses are each handled with the right parser, and the original XML string is preserved alongside the parsed map so downstream nodes can read either form. Existing JSON-returning endpoints continue to work without configuration changes.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Accept-driven response parsing.** The endpoint's `Accept` header decides how the response is parsed. JSON variants (`application/json`, `application/hal+json`, `application/problem+json`, any `+json` suffix) are parsed as JSON; `text/*` is returned as a string; XML variants (`application/xml`, `text/xml`, `application/soap+xml`, any `+xml` suffix) are parsed into a JSON-shaped map. When `Accept` is missing, the endpoint falls back to `Content-Type`, then to **AUTO** best-effort.
> >
> > * **XML responses parsed into JSON-shaped objects.** XML response bodies are auto-converted to maps so existing path expressions (`response.body.someField`) work without code changes. The original XML string is preserved on `sourceBody` for callers that need it raw.
> >
> > * **Loud failures on declared mismatches.** When an endpoint declares JSON or XML and the upstream returns a different category, or returns a body that fails to parse, the node fails with a precise error message (for example, `Expected response content type "application/json" but received "text/plain"`). The original body is preserved on `rawBody`.
> >
> > * **Tolerant under AUTO and wildcards.** Wildcard `Accept` values (`*/*`, `application/*`, `text/*`) and inferred categories (no `Accept` declared) fall back to the raw string instead of failing. Flaky or mislabelled upstreams don't break the node.
> >
> > * **XXE-safe XML parser.** XML parsing has DTD processing and external-entity resolution disabled by construction. External-entity attack payloads are neutralized; billion-laughs / entity-expansion attacks cannot fire.
> >
> > * **File downloads bypass Content-Type checks.** File-download endpoints (BINARY or BASE64) deliver the platform's own JSON payload regardless of upstream `Content-Type`, so legacy PDF, octet-stream, and image downloads work unchanged.
> >
> > * **Large XML returned raw.** XML response bodies larger than 5 MiB are returned as the raw string instead of a parsed map, so very large payloads don't block the node.
> >
> > > [!WARNING]
> > >
> > > **Mixed-content XML responses expose a new `value` key.** An XML element with both attributes and inner text (`<leaf attr="v">text</leaf>`) is now parsed to `{attr: "v", value: "text"}`. The inner text used to be silently dropped. Downstream nodes that iterate response keys or assert the exact key set on mixed-content elements may see an additional `value` entry. Path expressions that addressed attributes or child elements directly are unaffected.

> [card]
>
> ### **Raw endpoint payload type**
>
> REST endpoint configuration adds a **Raw** content type alongside JSON, Multipart, and Binary. Raw bodies are sent to the upstream system as-is. Useful for XML, SOAP envelopes, form-urlencoded payloads, or any plain-text body where you need to set the `Content-Type` header yourself.
>
> Before 5.9.0, the only way to send a non-JSON textual body was to use Multipart, which wrapped the payload in `multipart/form-data` and overrode the `Content-Type` header. Raw removes that wrapping.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Body sent as-is.** The body field is sent verbatim. The dispatcher does not transform, wrap, or pretty-print it.
> > * **Caller controls Content-Type.** Set the `Content-Type` header on the endpoint to whatever the upstream expects (`text/xml`, `application/soap+xml`, `application/x-www-form-urlencoded`, `text/plain`). The dispatcher does not override it.
> > * **Monaco plain-text mode.** The endpoint editor switches Monaco to plain text when Raw is selected. XML and SOAP indentation are preserved on paste and edit instead of being reformatted as JSON.
> > * **Shares the JSON body slot.** Raw and JSON payloads use the same storage field on the endpoint definition, so no schema migration is required. Existing endpoints continue to work without changes.

> [card]
>
> ### **Update Process Variables**
>
> JSON editor for variables on active instances with snapshot history; Compare diff.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/projects/runtime/active-process/update-process-variables)
> >
> > Open the **Update Process Variables** documentation.

> [card]
>
> ### **Stop Run for workflows**
>
> Cancel a running workflow instance from the editor.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/integrations/integration-workflows#running-and-stopping-workflows)
> >
> > Open the **Stop Run for workflows** documentation.

> [card]
>
> ### **Notification history + template usages**
>
> `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates)
> >
> > Open the **Notification history + template usages** documentation.

> [card]
>
> ### **Token view improvements**
>
> Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/building-blocks/token)
> >
> > Open the **Token view improvements** documentation.

> [card]
>
> ### **Stop workflow instances in runtime**
>
> Authorized end users can now stop running workflow instances directly from runtime. Previously, stopping a workflow required Designer access or a direct API call. The new control surfaces the action inside the runtime application alongside other workflow-instance management options.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **One-click stop.** Stop a running workflow instance from the runtime instance list.
> > * **Permission-gated.** The stop control is governed by runtime authorization.
> > * **Audited.** Stop actions are recorded on the workflow-instance audit log with the actor and timestamp.

> [card]
>
> ### **Native script engine for JavaScript and Python**
>
> The default script engine for JavaScript and Python business rules and workflow scripts moves from GraalVM polyglot contexts to a **native subprocess pool**. Scripts run in long-running Node.js and Python worker processes managed by `process-engine` and `integration-designer`. Existing scripts that read from `input` and write to `output` keep working, including `output.put(...)`, `output.get(...)`, and bracket assignment.
>
> The change is opt-out: set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on both services to keep the previous engine.
>
> Self-HostedAll Deployments
>
> > [accordion] Key Features
> >
> > * **Node.js workers for JavaScript.** JavaScript runs in isolated Node.js worker processes. Each script executes in a fresh V8 context with an explicit globals allowlist and a V8-level execution timeout.
> > * **CPython workers for Python.** Python 3 runs in isolated worker processes with a curated sandbox. Common standard-library modules (`random`, `math`, `datetime`, `re`, `hashlib`, `decimal`, `copy`, `string`, `collections`, `itertools`, `functools`, `uuid`, `base64`) are available without `import`. Process, OS, and network modules are blocked.
> > * **Worker pools with recycling.** Worker pools default to 16 Node.js workers and 8 Python workers, sized per service. Workers are recycled after a configurable number of executions to prevent state leakage.
> > * **HashMap method compatibility.** The familiar `output.put(key, value)`, `output.get(key)`, and `output.containsKey(key)` methods continue to work on both JavaScript and Python. The same scripts that ran under GraalVM polyglot context keep working without rewrites.
> > * **GraalVM still available as opt-in.** Set `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` on `process-engine` and `integration-designer` to keep the GraalVM engine, useful if a script depends on GraalVM-specific polyglot features.
> > * **Hardened execution sandbox.** Per-execution fresh scope, environment variables cleared at worker startup, dangerous Python module references scrubbed before user code runs, no `require` / `process` / `global` access in JavaScript.
>
> > [accordion] Configuration
> >
> > The native engine is the default on `process-engine` and `integration-designer`. Tune worker pools and timeouts as needed:
> >
> > | Environment Variable | Description | Default |
> > | - | - | - |
> > | `APPLICATION_SCRIPTENGINE_PROVIDER` | Script engine provider. `native` or `graalvm`. | `native` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_POOLSIZE` | Node.js worker pool size. | `16` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` | JS execution timeout per script (ms). | `5000` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_POOLSIZE` | Python worker pool size. | `8` |
> > | `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS` | Python execution timeout per script (ms). | `10000` |
> >
> > See [Process engine setup → Script engine configuration](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#script-engine-configuration) and [Integration Designer setup → Script engine configuration](/5.9/setup-guides/integration-designer-setup#script-engine-configuration) for the full set including payload size and worker recycling.
>
> > [accordion] Migration impact
> >
> > For most existing scripts the change is transparent. The `input`, `output`, `additionalData`, and `instanceMetadata` bindings behave the same, and HashMap-style access on `output` is preserved.
> >
> > Scripts that need attention:
> >
> > * **Python scripts that `import` modules outside the curated allowlist.** Narrow the script to use only the pre-loaded modules, or stay on GraalVM via the opt-out env var.
> > * **JavaScript scripts that reach for `require(...)`, `process`, or `global`.** Those references were never part of the supported surface area but may have worked under GraalVM. Rewrite to use only the bindings provided, or stay on GraalVM via the opt-out env var.
> > * **Scripts that depended on GraalVM-specific polyglot APIs** (calling Java classes from JavaScript / Python). Stay on GraalVM via the opt-out env var.
> >
> > See [Script runtime change for JavaScript and Python business rules](/5.9/migrating-from-5.1-lts/api-breaking-changes#script-runtime-change-for-javascript-and-python-business-rules) in the 5.1 → 5.9 migration guide for the full audit checklist.

> [card]
>
> ### **Single-org self-hosted deployment**
>
> Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/organization-deployment)
> >
> > Open the **Single-org self-hosted deployment** documentation.

> [card]
>
> ### **License service**
>
> Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> Self-Hosted
>
> > [card] [Documentation](/5.9/setup-guides/license-engine-setup)
> >
> > Open the **License service** documentation.

> [card]
>
> ### **Authentication: opaque-token → JWT**
>
> Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/authentication-iam)
> >
> > Open the **Authentication: opaque-token → JWT** documentation.

> [card]
>
> ### **New services to deploy**
>
> `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/prerequisites#new-services-to-deploy)
> >
> > Open the **New services to deploy** documentation.

> [card]
>
> ### **Ingress routing and CORS handling**
>
> The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/ingress-routing)
> >
> > Open the **Ingress routing and CORS handling** documentation.

> [card]
>
> ### **Kafka configuration alignment**
>
> Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> All Deployments
>
> > [card] [Documentation](/5.9/migrating-from-5.1-lts/kafka)
> >
> > Open the **Kafka configuration alignment** documentation.

> [card]
>
> ### **OpenTelemetry + SpiceDB DR**
>
> OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> All Deployments

> [card]
>
> ### **Durable message-processing**
>
> The process engine now persists parked integration and external-message responses durably, so a response that arrives before its process is ready to consume it survives a runtime restart instead of being lost. This removes a class of stuck process-token failures and improves message-processing robustness at runtime.
>
> All Deployments

> [card]
>
> ### **Task management localization**
>
> 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.
>
> All Deployments
>
> > [card] [Documentation](/5.9/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Open the **Task management localization** documentation.

> [card]
>
> ### **React Native SDK**
>
> FlowX 5.9.0 ships a brand-new **React Native SDK**, bringing the same process renderer model that has powered the React, Angular, iOS, and Android SDKs to React Native apps. Teams building cross-platform mobile or embedded React Native experiences can now host FlowX processes natively, with forms, navigation, and CMS integration handled by the SDK.
>
> A companion demo app is included as a reference integration, covering authentication, the showcase page, and the wiring needed to start a process from inside a container app.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Process renderer.** Render FlowX processes inside any React Native screen with the same component model as the other SDKs.
> > * **Forms and basic components.** Page, Button, Text, Container, Card, and form components ship out of the box.
> > * **CMS integration.** Static content and theming load from the FlowX CMS, including dynamic display values.
> > * **Navigation.** Basic process navigation between screens follows the same patterns as the iOS and Android SDKs.
> > * **Demo app included.** A demo app with authentication and a showcase page is shipped alongside the SDK as a reference integration.

> [card]
>
> ### **iOS UI Flows support**
>
> The iOS renderer reaches feature parity with the React and Angular renderers on UI Flows. iOS apps can now start UI Flows from container apps, manage UI Flow sessions, dismiss modals, handle UI actions, and render document-plugin subtypes (images and document previews).
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **Start UI Flow from container app.** Container apps can launch a UI Flow with start parameters and handle the response.
> > * **UI Flow session management.** The renderer manages a UI Flow session lifecycle on iOS the same way it does on web.
> > * **onLoad UI Event for Page.** Pages emit an `onLoad` UI Event that iOS handlers can listen to, matching the cross-platform event model.
> > * **Dismiss action and dismiss-on-completion.** A `dismiss` action type cleanly closes modals; `dismiss on completion` on `START_WORKFLOW` actions auto-closes the launching modal when the workflow finishes.
> > * **UI Flow start params.** Pass typed start parameters into a UI Flow at launch.
> > * **Upload File support.** UI Flows on iOS support file upload, including image and document-preview document-plugin subtypes.
> > * **Updated start-process endpoint.** The iOS renderer uses the latest start-process endpoint and `data` property on Start UI Flow, aligned with the web SDKs.
> > * **New native components.** Tooltip, Separator, Progress View, and Markdown components are now rendered natively on iOS, bringing the iOS component set closer to parity with the React and Angular renderers.
> > * **Accessibility properties from UI Designer.** Accessibility properties configured in the UI Designer flow through to the iOS renderer, so screen reader labels and traits are honored on native screens.

> [card]
>
> ### **React 19 upgrade**
>
> The React SDK upgrades to **React 19**, picking up the runtime improvements and APIs that ship with that release. Surrounding `@flowx/*` packages are upgraded in lockstep so the renderer continues to work as a single coherent bundle.
>
> Host apps embedding the React renderer should plan a React 19 upgrade on their side and run the standard React migration checks before adopting 5.9.0.
>
> All Deployments
>
> > [accordion] Key Features
> >
> > * **React 19 runtime.** Adopts the React 19 reconciler and the APIs that ship with that release.
> > * **Packages upgraded in lockstep.** All `@flowx/*` web SDK packages move to the same baseline so the renderer ships as one coherent bundle.
>
> > [accordion] Host app impact
> >
> > Host apps that embed the React renderer must be on React 19 themselves. Run the React 19 codemods and verify any third-party React libraries you depend on are compatible before upgrading FlowX.

> [card]
>
> ### **Runtime authorization and sharing**
>
> This is the biggest governance change in the 5.1 → 5.9 upgrade. End-user identities, runtime roles, and sharing assignments move out of Keycloak into FlowX-managed records, with project-version-scoped roles and a dedicated Share modal flow on Solutions.
>
> > [card] [Runtime authorization completion](#runtime-authorization-completion)
> >
> > Closes the rewrite: per-environment sharing checklist, project-level end-user roles, data-sync Keycloak provisioning. See the 5.9.0 card above.
>
> > [card] [Anonymous runtime access](#anonymous-runtime-access)
> >
> > Built-in `Anonymous` role + Share modal "Everyone with the link" option for unauthenticated end users. Session-bound (`X-Fx-Anonymous-Session-Id`), fire-and-forget; per-component hide/disable rules; SDK auth-skip mode.
>
> > [card] [Runtime authorization overhaul](#runtime-authorization-overhaul)
> >
> > Project-version-scoped roles, end-user groups in FlowX (moved from Keycloak), Solutions → Share modal, Active Policy gate, designer-user bypass, swimlane roles.
>
> > [card] [UI Flow permissions](#ui-flow-permissions)
> >
> > Per-UI-Flow role allow-list with runtime 403 enforcement, per-component hide/disable, and assignments that travel with import/export.
>
> > [card] [End-user access management](#end-user-access-management)
> >
> > Org-level End-Users and End-Users Groups separate from Designer users; project-level End-User Roles; CSV bulk invite.
>
> > [card] [Operations-editor role](#operations-editor-role)
> >
> > New **Workspace operations editor** predefined role and `wks_process_instance_variables_edit` permission for ops teams to migrate tokens and edit variables.
>
> > [card] [Cross-workspace projects](#cross-workspace-projects)
> >
> > Import the same project (UUID) into multiple workspaces in the same environment for UAT / Staging emulation.

> [card]
>
> ### **Conversational AI**
>
> 5.9 takes FlowX from no chat to production conversational AI: the Chat component, conversational workflows with memory and intent classification, voice and speech-to-text, chat-based UI Flows, and runtime controls.
>
> > [card] [Chat component](#chat-component)
> >
> > Standalone chat tab in web container apps with AI agent integration and session persistence. Inline / Floating / FullScreen display modes + iOS and Android mobile support. Chat History and Suggested Prompts. Markdown rendering.
>
> > [card] [Conversational Workflows](#conversational-workflows)
> >
> > Chat Driven workflow type, multi-turn dialogue, Chat Session ID + User Message Start node, direct chat reply.
>
> > [card] [Voice input + Speech-to-Text](#voice-input-+-speech-to-text)
> >
> > Audio recording, preview, and send within chat; Speech-to-Text node for transcription.
>
> > [card] [Memory capabilities](#memory-capabilities)
> >
> > Built-in session memory: the recent conversation (last 30 turns) is sent to the model in full, with a Use conversation memory toggle on the AI / Custom Agent node.
>
> > [card] [Intent Classification node](#intent-classification-node)
> >
> > Dedicated node combining LLM classification + branching, up to 10 intents, If-No-Intent-Matches fallback.
>
> > [card] [Chat-based UI Flows](#chat-based-ui-flows)
> >
> > UI Flows expose a Flow-Based vs Chat-Based experience type set at the UI Flow level.
>
> > [card] [AI Triggers](#ai-triggers)
> >
> > Named parameterized message templates to launch conversational workflows with context.
>
> > [card] [Stop agent response](#stop-agent-response)
> >
> > Stop button replaces Send while streaming; cancels the underlying workflow and persists a cancelled flag.

> [card]
>
> ### **AI Agents and Knowledge**
>
> The agent-builder story: Custom Agents, MCP integration, Knowledge Bases for RAG, document and web extraction, AI Providers self-service, and PII Guard.
>
> > [card] [Evaluations (Evals)](#evaluations)
> >
> > Score AI node outputs against test cases with 10 built-in evaluators (LLM-as-judge: correctness, conciseness, hallucination, answer-relevance; RAG: groundedness, helpfulness, retrieval-relevance; code: exact-match, Levenshtein, JSON-match). Datasets attached to AI nodes, async judge pipeline via the new `evals-judge` service + 3 Kafka topics, per-org judge model via the new `EVAL` capability (default `gpt-5.4-mini`).
>
> > [card] [Custom Agent nodes](#custom-agent-nodes)
> >
> > AI agents that use MCP tools to act autonomously inside workflows.
>
> > [card] [MCP integration](#mcp-integration)
> >
> > MCP servers as data sources; tools available in Custom Agent nodes; OAuth 2.0 SA auth, with BEARER/BASIC. 5.9.0 adds runtime config-param references (`${yourParamName}`) inside MCP server configuration fields for environment portability.
>
> > [card] [Knowledge Bases](#knowledge-bases)
> >
> > Centralized KBs with PDF upload, workflow ingestion (Append / Replace / Delete), semantic search, and Custom Agent integration. Stores rename + typed filter builder; system metadata + Kafka indexer/embedder + Qdrant delete + FILE\_PATH ingestion. 5.9.0 adds tunable Qdrant prefetch and fusion limits for hybrid search — deployment-time settings, covered in the deployment guidelines.
>
> > [card] [AI Providers self-service](#ai-providers-self-service)
> >
> > Org-level OpenAI (BYOK / FlowX-Managed) and Azure OpenAI; Defaults & Fallbacks per capability + workspace type; Audio capability.
>
> > [card] [PII Guard](#pii-guard-per-entity-detections-on-documents-and-images)
> >
> > Per-AI-node guardrail with Strict / Balanced / Relaxed presets, input/output scans, file redaction. 5.9.0 adds per-entity detections on documents and images. See the 5.9.0 card above.
>
> > [card] [Extract Data from File](#extract-data-from-file)
> >
> > LLM / OCR / Text Parsing strategies; image input (JPG, PNG, TIFF); signature detection.
>
> > [card] [Web Page Extractor / Web Crawler](#web-page-extractor-/-web-crawler)
> >
> > Crawl web pages, static or dynamic URLs, link-following depth, PDF extraction. URL filtering and file downloads; multi-URL filters.
>
> > [card] [Context Retrieval](#context-retrieval)
> >
> > RAG search against KBs without an LLM; hybrid / semantic / keyword; metadata filters and re-ranking. 5.9.0 surfaces per-chunk relevance scores in the node output so downstream nodes can branch or filter on confidence.
>
> > [card] [AI Developer generates Custom Components](#ai-developer-generates-custom-components)
> >
> > Pre-built agent drafts React Custom Components (JSX, CSS, package.json, sample data) from a brief.

> [card]
>
> ### **UI Flows and Custom Components**
>
> Build user-facing apps without a process. UI Flows reach feature parity with processes; Custom Components let teams ship React code inside the Designer.
>
> > [card] [UI Flows](#ui-flows)
> >
> > Reusable multi-platform UI (web / iOS / Android) as project resources. Navigation Areas, Start Process / Navigate UI actions, Task Manager component. Breadcrumbs + Sessions monitoring. Process Renderer + Start Workflow action + On Load event. Route management + Start Parameters + Session Variables + onClick / On Display events. UI Flow permissions.
>
> > [card] [Custom Components](#custom-components)
> >
> > Write React JSX / CSS in the Designer. React, Emotion, Lodash, Axios, date-fns supported. Input keys + actions, import / export. Custom Components in Processes (with INPUT/OUTPUT mappings).
>
> > [card] [Process Renderer in UI Flows](#process-renderer-in-ui-flows)
> >
> > Embed process renderers inside UI Flows.
>
> > [card] [UI Flow sessions monitoring](#ui-flow-sessions-monitoring)
> >
> > Runtime view with session list, audit log, process tracking, workflow debugging.
>
> > [card] [Accessibility (WCAG 2.1 AA)](#accessibility-wcag-2-1-aa)
> >
> > Accessibility section in the UI Designer with ARIA, keyboard navigation, screen reader support across web / iOS / Android. Mobile accessibility expanded.
>
> > [card] [New theme components](#new-theme-components)
> >
> > Tooltip, Markdown, Progress Bar, Separator components across React / Angular / Android.
>
> > [card] [Multi-file bulk upload](#multi-file-bulk-upload)
> >
> > Multiple File Upload component on process screens and UI Flows. Angular and React SDK support; single bulk endpoint + one SSE completion event.
>
> > [card] [Card default collapse + Tables in Collections](#card-default-collapse-+-tables-in-collections)
> >
> > Cards configurable to load collapsed; Table UI components inside Collection prototypes.

> [card]
>
> ### **Integration and Data Platform**
>
> For builders connecting FlowX to enterprise systems, 5.9 adds new data sources, new triggers, parallel workflow execution, REST resilience, and visual query authoring.
>
> > [card] [Email Trigger](#email-trigger)
> >
> > New data source: IMAP-triggered processes, attachments routed to the `document-plugin`, validation rules, Manage Triggers UI. Resource management, reply-to, and mock-email testing.
>
> > [card] [Microsoft Outlook data source](#microsoft-outlook-data-source)
> >
> > Microsoft Graph integration via Azure AD; Read / Send / Read\&Send scopes; conversation threads.
>
> > [card] [Incoming Webhooks](#incoming-webhooks)
> >
> > New `webhook-gateway` microservice; trigger processes via HTTP POST with API key auth. Provider adapters for Slack (HMAC-SHA256 + timestamp skew) and Meta (verify-token handshake + `X-Hub-Signature-256`). 5.9.0 adds Resume Process from intermediate catch events and the Meta provider. See the 5.9.0 cards above.
>
> > [card] [Oracle Database integration](#oracle-database-integration)
> >
> > Oracle 21c / 23ai data source; schema-aware Monaco editor; SERVICE\_NAME or SID; SSL.
>
> > [card] [Unmanaged MongoDB data source](#unmanaged-mongodb-data-source)
> >
> > Connect to externally managed MongoDB 6.0+ instances with the same CRUD as the FlowX DB. 5.9.0 adds a visual query builder for Unmanaged Mongo (filter / projection / sort, generated-query preview, in-place result preview).
>
> > [card] [Send Notification action + Email Sender](#send-notification-action-+-email-sender)
> >
> > SMTP data source and a new action that sends or replies email directly without going through Kafka.
>
> > [card] [Advanced Query Builder](#advanced-query-builder)
> >
> > Visual query builder replacing manual JSON. New operators (`exists`, `contains`, `before`, `after`, etc.).
>
> > [card] [Parallel branches in workflows](#parallel-branches-in-workflows)
> >
> > Start / End Parallel nodes for concurrent execution in Integration Designer.
>
> > [card] [REST endpoint caching + workflow partitioning](#rest-endpoint-caching-+-workflow-partitioning)
> >
> > TTL-based caching for REST GETs (Expires After / Expires At); time-based workflow partitions (DAY / WEEK / MONTH) with retention.
>
> > [card] [Data mappers + workflow data models](#data-mappers-+-workflow-data-models)
> >
> > Workflow data models with input / output; process ↔ workflow mapping; CRUD endpoints.
>
> > [card] [Proxy Server Connections](#proxy-server-connections)
> >
> > Reusable HTTP/HTTPS proxies attached to REST data sources.
>
> > [card] [Faster authoring loop](#faster-authoring-loop)
> >
> > 5.9.0 adds inline test modals on Script nodes and per-subworkflow individual runs. Iterate on script code or run a single subworkflow node without leaving the canvas.

> [card]
>
> ### **Process operations**
>
> Day-2 operations for runtime teams: edit live process state, inspect tokens with more context, audit notifications, and operate on workflow instances.
>
> > [card] [Update Process Variables](#update-process-variables)
> >
> > JSON editor for variables on active instances with snapshot history; Compare diff.
>
> > [card] [Stop Run for workflows](#stop-run-for-workflows)
> >
> > Cancel a running workflow instance from the editor.
>
> > [card] [Notification history + template usages](#notification-history-+-template-usages)
> >
> > `/api/notification/summary` and `/api/notification/{id}` endpoints; Usages modal lists all processes/workflows referencing a template.
>
> > [card] [Token view improvements](#token-view-improvements)
> >
> > Horizontal scroll, frozen UUID and Status columns, hierarchical nesting, Context column, Initiator Node, color-coded status.
>
> 5.9.0 adds **Stop workflow instances in runtime** and **Documents in process instances**. See the 5.9.0 cards above.

> [card]
>
> ### **Platform, deployment and infrastructure**
>
> Read this first if you operate a self-hosted deployment. 5.9 adds new microservices, a new deployment mode, and the auth architecture transition.
>
> > [card] [Single-org self-hosted deployment](#single-org-self-hosted-deployment)
> >
> > Self-hosted default mode. Guided setup wizard; explicit Designer / Runtime URL env vars.
>
> > [card] [License service](#license-service)
> >
> > Centralized license validation and usage reporting for self-hosted deployments. License billing guards.
>
> > [card] [Authentication: opaque-token → JWT](#authentication-opaque-token-→-jwt)
> >
> > Breaking change: `SECURITY_TYPE` default moves to `jwt-public-key` across all backend services; opaque-token introspection removed. Dedicated service-accounts realm; standardized `flowx-{service}-sa` client naming.
>
> > [card] [New services to deploy](#new-services-to-deploy)
> >
> > `webhook-gateway`, `email-gateway`, `license`, `organization-manager`. Helm charts and infrastructure must be provisioned before upgrading.
>
> > [card] [Native script engine for JavaScript and Python](#native-script-engine-for-javascript-and-python)
> >
> > JavaScript and Python business rules and workflow scripts run on a Node.js + CPython subprocess pool by default. HashMap-style access on `output` is preserved; GraalVM remains available via `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm`. See the 5.9.0 card above and the migration audit checklist.
>
> > [card] [Ingress routing and CORS handling](#ingress-routing-and-cors-handling)
> >
> > The NGINX ingress controller is deprecated as the FlowX-shipped default; the chart now supports Gateway API HTTPRoutes alongside Kubernetes Ingress with any controller. CORS handling moves from ingress annotations to the `APPLICATION_CORS_ALLOWORIGIN` environment variable on each backend service.
>
> > [card] [Kafka configuration alignment](#kafka-configuration-alignment)
> >
> > Standardized `KAFKA_BOOTSTRAP_SERVERS` / `KAFKA_SECURITY_PROTOCOL` env vars with `SPRING_KAFKA_*` fallback. Mandatory `Fx-Organization-Id` header.
>
> > [card] [OpenTelemetry + SpiceDB DR](#opentelemetry-+-spicedb-dr)
> >
> > OpenTelemetry / Prometheus Helm charts published to Harbor; documented SpiceDB backup and disaster-recovery procedures.
>
> > [card] [Task management localization](#task-management-localization)
> >
> > 51 substitution tags + automatic table grid localization (300+ keys) across 30 languages.

***

## Deployment notes

> [card] [Deployment guidelines v5.9.0](./deployment-guidelines-v5.9)
>
> Component versions, environment variables, Kafka topics, and self-hosted upgrade guidance.

> [card] [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview)
>
> Consolidated 5.1 LTS → 5.9 LTS migration guide. Direct upgrade to 5.9.0.


# Deployment guidelines v5.9.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1

Component versions, configuration, and deployment notes for FlowX.AI 5.9.1 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.1 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.0 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.0 → 5.9.1**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

## Component versions

### Core components

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **process-engine** | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.3 |
| **admin** | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.3 |
| **designer** | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.4 |
| **cms-core** | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.2 |
| **scheduler-core** | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.2 |
| **events-gateway** | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.2 |
| **notification-plugin** | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.2 |
| **document-plugin** | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.2 |
| **task-management-plugin** | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.2 |
| **reporting-plugin**\* | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |
| **data-search** | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.2 |
| **audit-core** | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.2 |
| **advancing-controller** | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.2 |
| **integration-designer** | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.3 |
| **application-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **runtime-manager** | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.2 |
| **data-sync** | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.2 |
| **authorization-system** | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.2 |
| **nosql-db-runner** | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.2 |
| **email-gateway** | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/angular-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-ui-toolkit** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/react-native-sdk** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **@flowx/core-theme** | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.4 |
| **react-saas** | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.20 |
| **Android renderer** | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.24 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

Foundation services. Install these before any Runtime or Dev Time component.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-knowledgebase-indexer-v2** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-knowledgebase-rag** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-embedder** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

Requires AI Base. Services that execute AI workloads at runtime.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-platform-agent-builder** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

Requires AI Base. Services used at design time inside the Designer.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **ai-gateway** | 10.17.0 | 10.7.0 | - | - |
| **ai-platform-ai-analyst** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-assistant** | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-platform-ai-designer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-ai-developer** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-planner** | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-platform-kb-enrichment** | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

Optional add-ons layered on the AI Platform.

| Component | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.9 (LTS) |
| - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.1 adds two Kafka topics. Both are **auto-provisioned by the Helm chart** — no manual creation is required for standard deployments. The names and env vars are listed here for environments that provision topics or ACLs manually.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | application-manager | process-engine | Runtime config-param change events; invalidates the build cache |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | process-engine | integration-designer | Notifies that a runtime instance has been terminated |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | admin | process-engine | Resource cache eviction triggered when a process version changes |
| `ai.flowx.evals.suggestions.job.request.v1` | integration-designer | AI Platform | Evaluation improvement-suggestion job requests |
| `ai.flowx.evals.suggestions.job.response.v1` | AI Platform | integration-designer | Evaluation improvement-suggestion job responses |

Topic env vars and consumer groups:

| Topic | Producer var (OUT) | Consumer var (IN) | Consumer group |
| - | - | - | - |
| `ai.flowx.config.params.events.v1` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_OUT` | `KAFKA_TOPIC_CONFIGPARAMS_EVENTS_IN` | `config-params` |
| `ai.flowx.core.notify.terminated.runtime-instance.v1` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_OUT` | `KAFKA_TOPIC_RUNTIMEINSTANCE_TERMINATED_IN` | `integration-designer-runtime-instance-terminated-group` |
| `ai.flowx.core.trigger.resource.cache-evict.v1` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT` | `KAFKA_TOPIC_RESOURCE_CACHEEVICT_IN` | `resource-cache-evict` |
| `ai.flowx.evals.suggestions.job.request.v1` | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_REQUEST_OUT` | — (consumed by AI Platform) | — |
| `ai.flowx.evals.suggestions.job.response.v1` | — (produced by AI Platform) | `KAFKA_TOPIC_AI_EVALSSUGGESTIONS_JOB_RESPONSE_IN` | `integration-designer-evals-suggestions-response-group` |

For the config-param cache-invalidation behavior, see [Engine setup → Topics related to runtime config params](/5.9/setup-guides/flowx-engine-setup-guide/engine-setup#topics-related-to-runtime-config-params). For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.1 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.1-june-2026/v5.9.1-june-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including split AI permissions, the legacy script flag, and File Storage and document-preview fixes.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.0 → 5.9.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.1** is a maintenance release for the 5.9.x LTS with bug fixes, security patches, and a few targeted improvements:
>
> * **Import/export:** stability and cross-version compatibility fixes
> * **Split AI permissions:** separate governance for AI runtime usage and AI build-time tooling
> * **Legacy script flag:** per-rule Native / GraalVM script runtime selection
> * **File Storage and document-preview improvements**
> * Wide set of Designer, Renderer, and platform bug fixes
> * No breaking changes; fully compatible upgrade from 5.9.0

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Split AI permissions**](#split-ai-permissions) - Independent governance for AI usage and AI build tooling.\
> 📝 [**Legacy script flag**](#legacy-script-flag) - Per-rule Native / GraalVM script runtime selection.\
> 🗂️ [**File Storage improvements**](#file-storage-improvements) - FTP connection and preview fixes.\
> 📄 [**File Preview scroll events**](#file-preview-scroll-events) - Scroll-trigger event handlers for the File Preview component.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, Workflows, and backend bug fixes plus security patches.
>
> ***
>
> ### **Split AI permissions**
>
> > [card] Separate governance for AI usage and AI build tooling
> >
> > > [tab] Overview
> > >
> > > AI permissions are now split into two independent controls, so administrators can govern **AI runtime usage** separately from **AI build-time tooling** (AI Designer, agent building, code generation).
> >
> > > [tab] Behavior
> > >
> > > * When AI is turned off, AI-related icons and entry points are hidden rather than shown in a disabled state.
> > > * AI nodes in workflows behave consistently with the gateway's availability.
> > > * Build-time AI helpers (code generation, "Add comment") follow the dev-agent permission rather than the runtime AI permission.
> >
> > All Deployments
>
> ***
>
> ### **Legacy script flag**
>
> > [card] Per-rule Native / GraalVM script runtime
> >
> > Business rules, reusable functions, and node rules can now choose their script engine individually: the current **native** engine (the 5.9 default) or the legacy **GraalVM** engine. Rules created before the switch to native keep running on GraalVM until you migrate them, while new rules default to native, so teams can move scripts across at their own pace. The per-rule selector only appears for rules that support GraalVM; new rules run on native.
> > All Deployments
>
> ***
>
> ### **File Storage improvements**
>
> > [card] FTP connection and preview fixes
> >
> > * FTP **test connection** now resolves configuration-parameter placeholders before connecting.
> > * **File operations** also resolve configuration-parameter placeholders at runtime.
> > * FTP **file preview** works when the root path has no leading slash.
> >   All Deployments
>
> ***
>
> ### **File Preview scroll events**
>
> > [card] Scroll-trigger event handlers for File Preview
> >
> > The **File Preview** component now supports **scroll-trigger event handlers** (including a "document end" trigger), configurable in the Designer and handled by the web, iOS, and Android renderers. They let a flow detect when a user scrolls through a document or reaches its end.
> >
> > This is built for consent and disclosure use cases such as banking flows that must prove, per local regulation, that the user actually read an agreement. You can keep an action such as a **Submit** or **Accept** button hidden or disabled until the document-end event handler fires; that handler can be a simple local script that sets a flag to enable the button.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Forms to validate:** fixed scrolling through the full component hierarchy, placeholder updates, and incorrect selection of chat and tab-bar components.
> > > > * **Process instances:** fixed a browser crash when loading instances with very large execution graphs.
> > > > * **Theme admin:** fixed theme content being lost when using "copy to".
> > > > * **UI Flow:** fixed images not displaying in preview after refresh, and a missing theme UUID when returning from an expired UI Flow.
> > > > * **Actions:** stopped GET actions firing with undefined parameters.
> > > > * **Modals:** fixed dropdown flicker and layout issues with long key names.
> > >
> > > > [accordion] Renderer fixes (Web / React / React Native)
> > > >
> > > > * **Web:** fixed missing button shadow, modal content padding, and rendering when a media-file storage path is null.
> > > > * **File Preview:** fixed preview not rendering correctly, events not firing inside collections, fixed height not applied at runtime, and CORS errors when accessing preview resources.
> > > > * **React Native:** fixed date-picker shifting to a previous day and input/textarea retaining focus after moving to another component.
> > > > * **Task management:** fixed header theming (React/Angular) and the filter window disappearing after applying criteria.
> > > > * **File upload:** the upload button now supports a configurable icon, set in the Designer and rendered on web, iOS, and Android.
> >
> > > [tab] Workflows & AI
> > >
> > > > [accordion] Workflow fixes
> > > >
> > > > * Fixed END PARALLEL output including data from before the parallel branches started.
> > > > * Optimized storage of running steps for workflows.
> > > > * Fixed a crash in NoSQL node run logs when a node failed before building its options.
> > > > * Workflows and processes launched from a UI Flow now inherit the build from the parent UI Flow.
> > > > * AI node failures now surface the error details and model reasoning in the workflow run logs, making failed AI steps easier to diagnose.
> > >
> > > > [accordion] AI improvements & fixes
> > > >
> > > > * **AI Designer** generates more reliable UI from a flat template format (replacing the previous 3-level nesting), supports additional component types (including Multi-Select, Bulk File Upload, Table Cell, and Collection), edits existing templates by applying changes incrementally instead of regenerating from scratch, and can now generate **reusable UI templates**.
> > > > * Fixed agent responses reappearing in chat after stop and refresh.
> > > > * Fixed duplicated messages in the builder-agent chat.
> > > > * **Knowledge Base:** files that fail to upload because the content is too large no longer appear in the content source list.
> > > > * **Platform Status** now reports AI Platform components and their databases alongside the core services.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * Fixed a null value being wrongly cached when looking up the "All end-users" group, which could block logins until data-sync completed.
> > > > * Fixed copying a process or workflow to another project: the copy now succeeds, and copied workflows appear in the target project.
> > > > * Fixed an invited Designer user added as an Organization owner not being assigned to a workspace.
> > > > * Improved merge-conflict handling for custom components and UI Flows, with clearer resource identification.
> > > > * Hide/disable conditions on UI templates, processes, and UI Flows are now applied at runtime for Designer users without workspace access.
> > > > * Fixed a 500 (duplicate key) error when activating a start timer event after a new build regenerated the process resource ID.
> > > > * Fixed a 500 error when opening a Usage Overview.
> > > > * Organization settings navigation and design improvements.
> > > > * **Runtime config params:** changes to runtime configuration parameters now propagate to the process engine in near-real-time, so updated values take effect immediately instead of after a short cache delay.
> > > > * **Microsoft Outlook connections** now support certificate-based authentication for Microsoft Graph, as an alternative to client-secret credentials.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.1 is fully compatible with 5.9.0. No breaking changes; standard deployment procedures apply.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.0 → 5.9.1 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.1 are tracked in the [5.9.1 deployment guidelines](./deployment-guidelines-v5.9.1).&#x20;
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2

Component versions, configuration, and deployment notes for FlowX.AI 5.9.2 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.2 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.1 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.1 → 5.9.2**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and converts your data. If you did not apply that workaround, no action is needed.

> [!WARNING]
>
> **Manually marked Liquibase changesets.** If any Liquibase changesets were manually marked as executed (MARK\_RAN) to work around failures during earlier 5.9.x upgrade attempts, those records must be removed after upgrading to 5.9.2 so the corrected changesets can run. Contact FlowX support for the exact list of affected changesets before removing anything. If you did not mark any changesets manually, no action is needed.

## Component versions

### Core components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.162.1 | 10.147.1 | 10.135.0 | 10.106.0 | 9.75.7 |
| **admin** | 10.141.1 | 10.130.0 | 10.116.0 | 10.93.0 | 9.75.7 |
| **designer** | 10.260.7 | 10.250.0 | 10.230.2 | 10.181.0 | 9.164.10 |
| **cms-core** | 10.102.3 | 10.94.0 | 10.86.0 | 10.67.0 | 9.46.3 |
| **scheduler-core** | 10.85.1 | 10.78.0 | 10.70.0 | 10.53.0 | 9.35.3 |
| **events-gateway** | 10.90.1 | 10.81.0 | 10.72.0 | 10.55.0 | 9.36.4 |
| **notification-plugin** | 10.100.2 | 10.92.0 | 10.83.0 | 10.64.0 | 9.39.3 |
| **document-plugin** | 10.113.2 | 10.104.0 | 10.94.0 | 10.75.0 | 9.44.3 |
| **task-management-plugin** | 10.102.1 | 10.93.0 | 10.84.0 | 10.66.0 | 9.43.3 |
| **reporting-plugin**\* | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.7 |
| **data-search** | 10.83.1 | 10.76.0 | 10.69.0 | 10.52.0 | 9.32.3 |
| **audit-core** | 10.93.1 | 10.86.0 | 10.79.0 | 10.63.0 | 9.40.3 |
| **advancing-controller** | 10.89.1 | 10.81.0 | 10.73.0 | 10.55.0 | 9.35.3 |
| **integration-designer** | 10.189.2 | 10.177.0 | 10.162.0 | 10.128.0 | 9.59.4 |
| **application-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **runtime-manager** | 10.148.3 | 10.136.0 | 10.123.0 | 10.97.0 | 9.82.5 |
| **data-sync** | 10.98.0 | 10.89.0 | 10.81.0 | 10.58.0 | 9.33.4 |
| **authorization-system** | 10.112.1 | 10.103.0 | 10.96.1 | 10.77.0 | 9.43.5 |
| **nosql-db-runner** | 10.92.1 | 10.84.0 | 10.75.0 | 10.56.0 | 9.31.3 |
| **email-gateway** | 10.91.1 | 10.84.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.88.1 | 10.80.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.60.1 | 10.52.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.23.1 | 10.16.0 | 10.8.0 | - | - |
| **license** | 10.78.1 | 10.70.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/angular-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-ui-toolkit** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/react-native-sdk** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.262.0 | 10.255.1 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **@flowx/core-theme** | 10.260.7 | 10.250.2 | 10.230.2 | 10.181.0 | 9.164.10 |
| **react-saas** | 10.260.7 | 10.250.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.6 | 10.5.0 | 10.4.1 | 10.3.0 | 9.0.25 |
| **Android renderer** | 10.5.6 | 10.5.4 | 10.5.0 | 10.3.0 | 9.0.31 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.0 | 10.10.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.0 | 10.2.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.0 | 10.2.3 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.0 | 10.2.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.0 | 10.3.5 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.0 | 10.3.6 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.25.0 | 10.17.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.0 | - | - | - | - |
| **ai-assistant** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.0 | 10.8.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.0 | 10.8.0 | - | - | - |
| **flowx-docs** | 5.9.2 | 5.9.1 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.2 | 5.9.1 | 5.9.0 | 5.8.0 | 5.1.10 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.2 introduces no new Kafka topics over 5.9.1. For the topics added in 5.9.1, see the [5.9.1 deployment guidelines](../v5.9.1-june-2026/deployment-guidelines-v5.9.1#kafka-topics); for the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.2 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

* **Kafka reconnect backoff:** platform services now default to a gentler broker-reconnect backoff — `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MS` `1000` / `SPRING_KAFKA_PRODUCER_PROPERTIES_RECONNECT_BACKOFF_MAX_MS` `10000` (and the consumer equivalents) — and repetitive Kafka NetworkClient connection errors log at a quieter level, tunable via `LOGGING_LEVEL_KAFKA_NETWORK_CLIENT` (default `ERROR`). No action needed unless you previously tuned these.&#x20;
* **Resource-server security type:** the default for `idp.resourceServer.securityType` on the AI services changes to `jwt`. If you previously set the security type to `jwt` explicitly as a workaround, that override is no longer needed and can be removed.&#x20;

#### Data partitioning and archiving

5.9.2 adds configuration for the archiving lifecycle on the process-engine and Integration Designer. All new settings default to off, so no action is required on upgrade.&#x20;

* **Stuck-instance termination:** an optional sweep (`FLOWX_DATA_PARTITIONING_ARCHIVING_STUCKTERMINATE_ENABLED`, default `false`) terminates instances that would otherwise block archiving. Enable it, plus its cron and batch-size, if archiving stalls on unfinished data.
* **Legacy backfill:** one-shot backfills of `partition_id` (`FLOWX_DATA_PARTITIONING_BACKFILL_ENABLED`) and `organization_id` (`FLOWX_DATA_PARTITIONING_ORGIDBACKFILL_ENABLED`), both default `false`, populate legacy rows when you first turn partitioning on. The organization-ID backfill is optional on self-hosted and can remain `false`.

> [!WARNING]
>
> **Partitions that still contain unfinished instances are not archived.** Starting with 5.9.2, the archiving job detaches a partition only when every process instance in it has reached a finished state (`FINISHED`, `FINISHED_WITH_ERROR`, `FAILED`, `EXPIRED`, `ABORTED`, `DISMISSED`, or `TERMINATED`). A single instance still in `CREATED`, `STARTED`, or `ON_HOLD` blocks the entire partition; it is retried on the next archiving run. The same rule applies to workflow instances on the Integration Designer, where a `STARTED` workflow instance blocks its partition. If partitions accumulate unarchived, terminate the blocking instances — set process expiry, or turn on the stuck-instance termination sweep above.

For the full property tables and defaults, see [Partitioning & archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) (process-engine) and [Integration Designer setup → Workflow partitioning](/5.9/setup-guides/integration-designer-setup#workflow-partitioning-configuration).

#### AI Platform service naming

AI Platform services are now deployed under their plain names — the `ai-platform-` prefix is dropped from pod, service, and image names (for example, `ai-platform-agent-builder` becomes `agent-builder`). If you have monitoring dashboards, alerts, or log queries that match the prefixed names, update them as part of this upgrade. The bundled Qdrant subchart is renamed the same way, so any explicit references to its service host must be updated too.

> [!WARNING]
>
> Core platform services resolve AI Platform components by these new names. Upgrade the AI Platform chart and the core platform services to 5.9.2 together — running a 5.9.1 AI Platform chart against 5.9.2 core services (or the reverse) breaks AI features.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/v5.9.2-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including expanded audit logging, copy-with-roles, and the app-manager organization-ID migration fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.1 → 5.9.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.2** is a maintenance release for the 5.9.x LTS. It pairs a broad bug-fix pass with a few targeted improvements:
>
> * **Expanded audit logging:** coverage for sharing, invitations, user and group management, and process-instance and UI-flow actions
> * **Copy with roles:** copying a resource now also copies its associated roles
> * **Self-hosted upgrade fixes:** smoother installation and upgrade from 5.1.x on self-hosted environments
> * **Key fixes:** active-policy override user list, project-version merge, reusable UI templates in nested containers, and audit-log user filtering&#x20;
> * Wide set of Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.9.2 brings bug fixes and stability improvements across the platform, with a few targeted enhancements in the 5.9.x LTS line.
>
> 🔐 [**Expanded audit logging**](#expanded-audit-logging) - Broader coverage of access and lifecycle actions.\
> 👥 [**Copy with roles**](#copy-with-roles) - Roles travel with copied resources.\
> 🔧 [**Platform improvements**](#platform-improvements) - Designer, Renderer, and backend bug fixes plus security patches.
>
> ***
>
> ### **Expanded audit logging**
>
> > [card] Broader audit coverage for access and lifecycle actions
> >
> > Audit logging now records a wider set of actions, including **sharing**, **user invitations**, **designer-user, end-user, and group management**, and actions on **process instances** and **UI flows**. Adding a dependency is now audited, and terminating process, workflow, or UI-flow instances is captured as well.
> > All Deployments
>
> ***
>
> ### **Copy with roles**
>
> > [card] Roles travel with copied resources
> >
> > Copying a process or UI flow to another project now also copies the resource's associated **roles**, so access configuration no longer has to be recreated by hand after a copy.
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Designer & Renderer
> > >
> > > > [accordion] Designer fixes
> > > >
> > > > * **Reusable UI templates:** fixed actions missing at runtime when a template is nested in multiple levels of containers.&#x20;
> > > > * **Use in reporting:** the reporting toggle is now available on UI flows and workflows, matching the existing process setting.
> > > > * **UI action keys:** keys to save for collection items and bundled custom-component inputs are now computed automatically, and mapped object keys for collections and custom components are available in runtime data.&#x20;
> > > > * **SQL data sources:** queries on SQL data sources can now be tested from the builds list, mirroring the existing NoSQL runtime test flow.&#x20;
> > > > * **Event handlers:** the Event Handlers section now appears higher in the component configuration panel.&#x20;
> > > > * **Audit logs:** filtering audit entries by user now works when the username differs from the email address.&#x20;
> > > > * **AI agents and data models:** AI Designer and AI Developer now use the project data model when generating UIs and business rules, and AI Architect can generate a project data model with a preview before applying it. &#x20;
> > >
> > > > [accordion] Renderer fixes
> > > >
> > > > * **Chat:** the floating chat position is now calculated correctly, and the chat session is kept in the URL when the instance UI flow console is opened.&#x20;
> > > >
> > > > This release also includes stability fixes across the web, React, React Native, Android, and iOS renderers.
> >
> > > [tab] Platform & Backend
> > >
> > > > [accordion] Backend fixes
> > > >
> > > > * **Active policy:** fixed the user list appearing empty on the override active-policy form.&#x20;
> > > > * **Project version merge:** fixed a 500 error that could occur during project-version merge.&#x20;
> > > > * **CMS enumerations:** cascading-enum value lookups now resolve from live entries only, so options that were removed and re-added no longer cause errors or return deleted values.&#x20;
> > > > * **Build export with media files:** exporting a build with media file content included now produces an archive that actually contains the binaries.&#x20;
> > > > * **Data mappers:** adding a new output parameter no longer clears existing JavaScript functions.&#x20;
> > > > * **Redis Cluster:** UI-template cache keys are now hash-tagged so related keys map to the same cluster slot, preventing cross-slot errors on Redis Cluster deployments.&#x20;
> > > > * **Workflow data:** Mongo partition archiving now batches, checkpoints, and throttles for large datasets, with partition-ID backfill for legacy data. UI flow sessions are included in partitioning and archiving, and an incident-save deadlock in the process engine was fixed. See [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#configuring-partitioning-and-archiving) for the partitioning and archiving settings.&#x20;
> > > > * **Data sync with private CA certificates:** the data-sync job now runs the same certificate-initialization step as the other platform services, so data-sync migrations that call HTTPS endpoints (such as Keycloak) no longer fail certificate validation in environments using an internal certificate authority.&#x20;
> > > > * **Self-hosted installation and upgrade:** fixed Keycloak realm handling during upgrades from 5.1.x (including migration changesets on Oracle), service-account provisioning, and default end-user group seeding on self-hosted environments. As part of this, the migration-created default end-user group is renamed from `User` to `Users Group`; check the upgrade warning under Additional information if you map IDP groups into FlowX.&#x20;
> > > > * **PII Guard:** the input scan no longer corrupts workflow data or redacts example values from instructions, and anonymized values are restored after LLM calls, including in chat-driven workflows that use conversation memory.&#x20;
> > > > * **AI workflow nodes:** JSON schema fields now support `${}` placeholders.&#x20;
> > > > * **Multi-KB retrieval:** retrieval can span multiple knowledge bases in a workflow.&#x20;
> > > > * **AI structured output:** responses from AI nodes with a response schema are now validated against it, with automatic repair retries, and node logs include richer run diagnostics such as the failure reason and rejected output.&#x20;
> > > > * **Document Parser:** a new LiteParse engine parses PDFs and images fully locally without GPU or AI calls, and OCR language support expands to English, Romanian, Hungarian, and Bulgarian.&#x20;
> > > > * **Knowledge bases:** a Custom Agent node can now select multiple knowledge bases, each exposed to the agent as its own retrieval tool, replacing the parallel-nodes workaround.&#x20;
> > > > * **Chat file uploads:** end users can attach multiple files in a chat-driven app; uploads are indexed into a knowledge base scoped to the chat session so AI nodes answer grounded in that content.&#x20;
> > > > * **Evaluations:** an experiment can run against multiple datasets at once with per-dataset scores, and reports include AI-generated prompt-improvement suggestions per judge evaluator.&#x20;
> > > >
> > > > This release also includes a broad set of additional fixes and stability improvements across Designer and backend services.
> > >
> > > > [accordion] Security patches & dependency upgrades
> > > >
> > > > This release includes security patches and dependency upgrades across platform components.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.2 is fully compatible with 5.9.1; standard deployment procedures apply. One migration renames a default end-user group, which needs attention only if group membership is mapped from Keycloak or an external IDP (see the warning below).
>
> > [!WARNING]
> >
> > **Default end-user group renamed from `User` to `Users Group`.** The group that the 5.1.x upgrade migration creates for users who held the `FLOWX_ROLE` realm role is renamed from `User` to `Users Group` when you upgrade to 5.9.2 or any later release. Runtime group matching is by exact name: if a Keycloak **Group Membership** mapper or an external IDP claim emits the old name `User` into `attributes.runtimeGroups`, those values no longer match any FlowX group and affected users **lose solution access on their next sign-in, with no error logged**. Update the mapper or source group name to `Users Group` as part of the upgrade. Groups your admins created themselves, including any you named `User`, are not renamed. See the [runtime groups attribute mapper](/5.9/setup-guides/access-management/configuring-an-iam-solution#runtime-groups-attribute-mapper) setup for where this value is configured.
>
> > [!WARNING]
> >
> > **Organization-ID migration fix (application-manager).** 5.9.2 corrects the runtime-application organization-ID migration so it converts existing data correctly. If you worked around the original migration on 5.9.0 or 5.9.1 by manually marking it as executed, **remove that record after upgrading to 5.9.2** so the corrected migration runs and actually converts your data. If you did not apply that workaround, no action is needed.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.1 → 5.9.2 with no breaking changes. Self-hosted customers on 5.1.x LTS upgrade directly to the 5.9.x line; see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Component versions for 5.9.2 are tracked in the [5.9.2 deployment guidelines](./deployment-guidelines-v5.9.2).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive monthly maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes


# Deployment guidelines v5.9.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/deployment-guidelines-v5.9.3

Component versions, configuration, and deployment notes for FlowX.AI 5.9.3 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.3 is a maintenance release for the 5.9.x LTS line. It can be deployed as a direct upgrade from 5.9.2 with no breaking changes.

> [card] Upgrade Path
>
> **5.9.2 → 5.9.3**: Direct upgrade with no breaking changes.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.0 or 5.9.1 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.165.0 | 10.162.1 | 10.135.0 | 10.106.0 | 9.76.3 |
| **admin** | 10.144.0 | 10.141.1 | 10.116.0 | 10.93.0 | 9.76.3 |
| **designer** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **cms-core** | 10.105.0 | 10.102.3 | 10.86.0 | 10.67.0 | 9.47.3 |
| **scheduler-core** | 10.87.0 | 10.85.1 | 10.70.0 | 10.53.0 | 9.36.3 |
| **events-gateway** | 10.93.0 | 10.90.1 | 10.72.0 | 10.55.0 | 9.37.3 |
| **notification-plugin** | 10.103.0 | 10.100.2 | 10.83.0 | 10.64.0 | 9.40.3 |
| **document-plugin** | 10.116.0 | 10.113.2 | 10.94.0 | 10.75.0 | 9.45.3 |
| **task-management-plugin** | 10.105.0 | 10.102.1 | 10.84.0 | 10.66.0 | 9.44.4 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.85.0 | 10.83.1 | 10.69.0 | 10.52.0 | 9.33.3 |
| **audit-core** | 10.95.0 | 10.93.1 | 10.79.0 | 10.63.0 | 9.41.3 |
| **advancing-controller** | 10.91.0 | 10.89.1 | 10.73.0 | 10.55.0 | 9.36.3 |
| **integration-designer** | 10.192.0 | 10.189.2 | 10.162.0 | 10.128.0 | 9.60.3 |
| **application-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **runtime-manager** | 10.151.1 | 10.148.3 | 10.123.0 | 10.97.0 | 9.83.5 |
| **data-sync** | 10.100.0 | 10.98.0 | 10.81.0 | 10.58.0 | 9.34.2 |
| **authorization-system** | 10.115.0 | 10.112.1 | 10.96.1 | 10.77.0 | 9.44.4 |
| **nosql-db-runner** | 10.94.0 | 10.92.1 | 10.75.0 | 10.56.0 | 9.32.3 |
| **email-gateway** | 10.93.0 | 10.91.1 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.90.0 | 10.88.1 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.62.0 | 10.60.1 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.25.0 | 10.23.1 | 10.8.0 | - | - |
| **license** | 10.80.0 | 10.78.1 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/angular-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-ui-toolkit** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/react-native-sdk** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.266.0 | 10.262.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **@flowx/core-theme** | 10.265.6 | 10.260.7 | 10.230.2 | 10.181.0 | 9.164.15 |
| **react-saas** | 10.265.6 | 10.260.7 | 10.230.2 | - | - |
| **iOS renderer** | 10.5.11 | 10.5.6 | 10.4.1 | 10.3.0 | 9.0.27 |
| **Android renderer** | 10.6.6 | 10.5.6 | 10.5.0 | 10.3.0 | 9.0.37 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

> [!NOTE]
>
> **AI component versioning is unified in 5.9.2.** All AI Platform services now ship under a single AI Platform version (**10.9.0**), including services that previously carried their own version lines (`doc-parser`, `doc-converter`, `data-privacy`, `speech-to-text`, `web-crawler`, `evals-judge`). Their 5.9.2 version numbers are therefore not comparable with earlier columns — for example, `doc-parser` moves from 10.10.1 to 10.9.0 without losing anything. Component rows below use the plain service names introduced in 5.9.2 (the `ai-platform-` prefix is dropped — see [AI Platform service naming](../v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming)); earlier columns show the same component under its previous name.

#### AI Base components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.9.1 | 10.9.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **data-privacy** | 10.9.1 | 10.9.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.9.1 | 10.9.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.9.1 | 10.9.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.9.1 | 10.9.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.9.1 | 10.9.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.27.0 | 10.25.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-architect** | 10.9.1 | 10.9.0 | - | - | - |
| **ai-assistant** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **ai-developer** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **planner** | 10.9.1 | 10.9.0 | 10.7.0 | 10.7.0 | 9.4.2 |
| **kb-enrichment** | 10.9.1 | 10.9.0 | - | - | - |
| **flowx-docs** | 5.9.3 | 5.9.2 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.3 | 5.9.2 | 5.9.0 | 5.8.0 | 5.1.11 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.3 introduces no new Kafka topics over 5.9.2. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Update container images to the 5.9.3 versions listed in the table above.
2. Deploy services using your standard deployment process.
3. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Events Gateway — Redis connection pool for blocking mode

The Events Gateway's blocking read path is rebuilt on a dedicated Redis connection pool, fixing a connection leak that could previously require periodic Events Gateway restarts under sustained load. The new settings ship with working defaults — no action is required on upgrade.

| Environment variable | Default | Change in 5.9.3 |
| - | - | - |
| `EVENTS_REDIS_POOL_ENABLED` | `true` | New — dedicated connection pool for blocking reads |
| `EVENTS_REDIS_POOL_MAXTOTAL` | `50` | New — maximum pooled connections |
| `EVENTS_REDIS_POOL_MAXIDLE` | `50` | New — maximum idle pooled connections |
| `EVENTS_REDIS_POOL_MINIDLE` | `5` | New — minimum idle pooled connections |
| `EVENTS_REDIS_POOL_MAXWAITMILLIS` | `5000` | New — wait time for a pooled connection before failing |
| `EVENTS_REDIS_SSE_BUFFERSIZE` | `256` | New — per-subscriber SSE backpressure buffer |
| `EVENTS_REDIS_BLOCKDURATIONSECONDS` | `1` | Default lowered from `5` — shortens the blocking-read reissue interval |

If you previously set `EVENTS_REDIS_BLOCKDURATIONSECONDS` explicitly, review whether the new default suits your setup. See the [Events Gateway setup guide](/5.9/setup-guides/events-gateway-setup#events) for the full configuration reference.

#### Integration Designer — workflow topic partitions

`FLOWX_WORKFLOW_TOPICPARTITIONS` (default `1`) sets the number of partitions for auto-created workflow Kafka topics (used with `FLOWX_WORKFLOW_CREATETOPICS`). Existing topics are not modified; the setting applies to newly created topics only.&#x20;

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.3-july-2026/v5.9.3-july-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, and stability improvements, including the Events Gateway Redis connection-leak fix.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Upgrades from **5.9.2 → 5.9.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **FlowX.AI 5.9.3** is a maintenance release for the 5.9.x LTS:
>
> * **Real-time event delivery:** fixes a Redis connection leak in the Events Gateway that could previously require periodic restarts under sustained load
> * **Key fixes:** build import race during multi-dependency imports, task-management allocation rules, project re-creation error handling
> * **New configuration:** Events Gateway connection-pool tuning and workflow Kafka topic partitions
> * Designer, Renderer, and backend stability fixes plus security patches
> * No breaking changes; fully compatible upgrade from 5.9.2

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform.
>
> 🔧 [**Platform improvements**](#platform-improvements) - Events Gateway stability, Designer and backend bug fixes, security patches.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Real-time event delivery:** fixed a Redis connection leak in the Events Gateway. Blocking reads now run on a dedicated connection pool with Redis Cluster support, eliminating the gradual connection buildup that could previously require periodic Events Gateway restarts. New tuning options are available — see the [deployment guidelines](./deployment-guidelines-v5.9.3#configuration-changes).
> > > > * **Build import:** fixed a race during multi-dependency imports where a transient database write conflict could silently drop a dependency's build, causing runtime errors on substitution tags and enumerations for that build. Large imports may take slightly longer as a result.&#x20;
> > > > * **Task management:** deleting a swimlane allocation rule now removes only the targeted rule instead of clearing other rules along with it, and duplicate rules are no longer created when Save is clicked twice. Task views also no longer reset when the same view is open from different workspaces.&#x20;
> > > > * **Projects:** creating a project with the same name as a previously deleted project now returns a clear validation error instead of an internal server error.
> > > > * **Designer stability:** fixed a freeze when opening Runtime after expanding a component's Permissions section, and a pending AI UI-generation draft no longer locks the process diagram read-only.&#x20;
> > > > * **Date Picker:** the calendar now anchors correctly to its field above modals and while scrolling, and label, helper, and error text follow the themed padding.&#x20;
> > > > * **Workflows:** fixed a silent workflow freeze that could occur after a step exhausted its retries.&#x20;
> > > > * **iOS renderer:** the form background is now applied correctly on native iOS, matching the Android behavior. UI Flows on iOS also gain support for the `additionalData` object.
> > > >   &#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Media Library:** PDF assets in the list can now be opened in a new tab directly from the Media Library.
> > > > * **Process start loading:** web renderers now keep the loading indicator visible until the first user task renders, matching the mobile SDK behavior.&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.9.3 is fully compatible with 5.9.2. No configuration changes are required on upgrade; new tuning options ship with working defaults.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.9.2 → 5.9.3 with no breaking changes
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps are required for this maintenance release. Upgrading directly from 5.9.0 or 5.9.1? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.3](./deployment-guidelines-v5.9.3).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/deployment-guidelines-v5.9.4

Component versions, configuration, and deployment notes for FlowX.AI 5.9.4 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.4 is a maintenance release for the 5.9.x LTS line. The platform upgrade from 5.9.3 is non-breaking, but this release changes how the Helm charts express the container image location, so review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.3 → 5.9.4**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line — see [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!WARNING]
>
> **Helm values change.** The charts now express the image location as `image.registry` plus `image.repository` instead of one combined path. Deployments that set `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move it out before upgrading — see [Helm charts: image registry split](#helm-charts-image-registry-split).

> [!NOTE]
>
> **Upgrading from 5.9.0, 5.9.1, or 5.9.2 directly?** Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first — they include required steps for the organization-ID migration fix and manually marked Liquibase changesets that also apply when you skip 5.9.2.

## Component versions

### Core components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.171.3 | 10.165.0 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.149.3 | 10.144.0 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.110.4 | 10.105.0 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.91.2 | 10.87.0 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.97.2 | 10.93.0 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.107.4 | 10.103.0 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.121.3 | 10.116.0 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.109.3 | 10.105.0 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.89.2 | 10.85.0 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.99.2 | 10.95.0 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.95.2 | 10.91.0 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.197.5 | 10.192.0 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.155.5 | 10.151.1 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.104.3 | 10.100.0 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.119.3 | 10.115.0 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.98.2 | 10.94.0 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.98.2 | 10.93.0 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.95.2 | 10.90.0 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.66.2 | 10.62.0 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.30.2 | 10.25.0 | 10.8.0 | - | - |
| **license** | 10.84.2 | 10.80.0 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** — see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database) — bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.266.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.275.0 | 10.265.6 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.275.0 | 10.265.6 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.0 | 10.5.11 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.8.0 | 10.6.6 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.10.2 | 10.9.1 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.10.2 | 10.9.1 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.10.2 | 10.9.1 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.10.2 | 10.9.1 | 10.1.1 | - | - |
| **speech-to-text** | 10.10.2 | 10.9.1 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.10.2 | 10.9.1 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.32.2 | 10.27.0 | 10.7.0 | - | - |
| **ai-analyst** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.10.2 | 10.9.1 | - | - | - |
| **ai-assistant** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.10.2 | 10.9.1 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.10.2 | 10.9.1 | - | - | - |
| **flowx-docs** | 5.9.4 | 5.9.3 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.4 | 5.9.3 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.4 introduces no new Kafka topics over 5.9.3. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Apply the Helm values change described in [Configuration changes](#configuration-changes), if it affects your setup.
2. Update container images to the 5.9.4 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Helm charts: image registry split

Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.

```yaml theme={"dark"}
# Before
image:
  repository: <registry>/<image-name>

# After
image:
  registry: <registry>
  repository: <image-name>
```

The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.

**Upgrade notes**

* **If you set `global.imageRegistry` to point the charts at your own registry** (the standard, documented approach): no action is required. Your override continues to work, and it now applies cleanly to the default bare repository names.
* **If you embedded the registry inside `image.repository`** (for example `image.repository: harbor.mycorp.internal/flowx/<image-name>`): move the registry portion out. Set it through `global.imageRegistry`, or the chart's `image.registry`, and let `image.repository` fall back to its default bare image name. Leaving the registry in `image.repository` alongside the now-populated `image.registry` prepends the registry twice.

  This applies to deployments configured from the FlowX setup guides before 5.9.4, which showed the combined form. If your values files were built from those examples, check them before upgrading.

#### Events Gateway service account

Events Gateway now authenticates to the Runtime Manager with its own service account, `flowx-events-gateway-sa`, in the service-accounts realm. It needs this identity to resolve and authorize a subscription before admitting the stream.

Two new configuration values are involved, and both take the **same secret**:

| Service | Environment Variable | Purpose |
| - | - | - |
| authorization-system | `SPRING_LIQUIBASE_PARAMETERS_SECRETS_SERVICEACCOUNTS_FLOWXEVENTSGATEWAYSA` | Secret the migration assigns to the client it creates |
| events-gateway | `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_MAINIDENTITY_CLIENTSECRET` | Secret Events Gateway authenticates with |

**Upgrade notes**

* **If you deploy with the FlowX Helm charts and authorization-system runs its migrations with Keycloak admin access**: no action is required. The chart already maps both values to the `KEYCLOAK_EVENTS_GATEWAY_CLIENT_SECRET` key of the `keycloak-flowx-realm-clients` secret, and the authorization-system migration creates the client and grants it the `SA_FLOWX` role.
* **If you manage Keycloak clients outside the chart** (external IdP, or authorization-system cannot provision clients): create `flowx-events-gateway-sa` in the service-accounts realm as a confidential client with service accounts enabled and only the client-credentials grant, then supply its secret to both values above.

> [!WARNING]
>
> If `flowx-events-gateway-sa` already exists, the migration leaves its secret untouched by design. A pre-existing client whose secret does not match the one given to Events Gateway will not be corrected on upgrade, and Events Gateway will fail to authorize subscriptions. Make the two match manually in that case.

#### Liquibase migration lock moves to database session locks

The lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so a stale `databasechangeloglock` row no longer needs clearing by hand. On any other database, Liquibase falls back to its standard row-based lock.

The previous mechanism verified the lock-holder pod through the Kubernetes API. That dependency is gone:

* Service accounts no longer need the `get pods/status` permission, and the FlowX Helm charts no longer create the corresponding Role and RoleBinding. If you maintain that RBAC outside the charts, you can remove the grant.
* The lock keeps working on Kubernetes 1.33 and newer, where the previous mechanism silently deactivated itself.

**Oracle deployments** must grant each FlowX service's database user the following before upgrading. A service whose grants are missing stops at startup with an error naming the missing grant:

```sql theme={"dark"}
GRANT EXECUTE ON SYS.DBMS_LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$LOCK TO <app_user>;
GRANT SELECT ON SYS.GV_$SESSION TO <app_user>;
```

PostgreSQL deployments need no action: advisory locks require no additional grant.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.4-august-2026/v5.9.4-august-2026

Maintenance release for the 5.9.x LTS line. Bug fixes, security patches, the Angular 21 renderer upgrade, and a Helm chart image-registry change.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. The platform upgrade from **5.9.3 → 5.9.4** requires no data migration, but it does change how the Helm charts express the container image location. Review the [deployment guidelines](./deployment-guidelines-v5.9.4#configuration-changes) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.4** is a maintenance release for the 5.9.x LTS:
>
> * **Helm charts:** the container image reference splits into `image.registry` and `image.repository`, making `global.imageRegistry` a single chart-wide override
> * **Angular 21:** the Angular renderer and the web SDKs move to Angular 21
> * **Key fixes:** branch merges no longer getting stuck, build export retry after a dependency timeout, deleting actions that call functions, gateway expression failures surfaced as incidents, library resource overview
> * **Cross-version import:** an imported theme is completed from the destination's system theme, so nothing is missing after importing an older export
> * Designer, renderer, and backend stability fixes plus security patches
> * No data migration; the only upgrade action is the Helm values change, and only for one override pattern

***

**What's new? 🆕**

> [tab] Highlights
>
> Bug fixes and stability improvements across the platform, plus a Helm chart change that affects some self-hosted deployments.
>
> 📦 [**Helm chart image registry**](#helm-chart-image-registry) - `image.repository` splits into `image.registry` + `image.repository`\
> 🅰️ [**Angular 21**](#angular-21) - The Angular renderer and web SDKs move to Angular 21\
> 🔧 [**Platform improvements**](#platform-improvements) - Bug fixes and security patches
>
> ***
>
> ### **Helm chart image registry**
>
> > [card] image.repository splits into image.registry + image.repository
> >
> > Across the FlowX chart set, the container image reference is now expressed as two fields instead of one combined path. The default image location is unchanged: each chart still resolves to the same `registry/repository:tag`.
> >
> > ```yaml theme={"dark"}
> > # Before
> > image:
> >   repository: <registry>/<image-name>
> >
> > # After
> > image:
> >   registry: <registry>
> >   repository: <image-name>
> > ```
> >
> > The registry resolves to `global.imageRegistry` when that is set, and otherwise to the chart's own `image.registry`. This makes `global.imageRegistry` a single, chart-wide override that redirects the charts to your registry, while each chart ships the correct bare `image.repository` by default.
> >
> > > [!WARNING]
> > >
> > > **Check your values files before upgrading.** If you set `global.imageRegistry`, no action is needed. If you embedded the registry inside `image.repository`, move it out first, or the registry is prepended twice. This includes values files built from the FlowX setup guides before 5.9.4, which showed the combined form. Full before-and-after in the [deployment guidelines](./deployment-guidelines-v5.9.4#helm-charts-image-registry-split).
> >
> > All Deployments
>
> ***
>
> ### **Angular 21**
>
> > [card] Angular renderer and web SDKs on Angular 21
> >
> > The Angular renderer and the `@flowx/angular-*` web SDK packages are built on Angular 21. Host apps embedding the Angular SDK should be on Angular 21 before taking 5.9.4.
> >
> > Angular does not support skipping a major in a single update, so step through the official update guide one major at a time. The **npm** and **node** requirements are unchanged from 5.9.3.
> >
> > See the [Angular SDK requirements](/5.9/sdks/angular-renderer#angular-project-requirements) for the current version floor, and the [Angular migration guide](/5.9/migrating-from-5.1-lts/angular#framework-upgrade-angular-19-→-21) for the upgrade path.
> >
> > All Deployments
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Bug fixes
> > >
> > > > [accordion] Notable bug fixes
> > > >
> > > > * **Build export:** retrying a build export now re-attempts a dependency library whose own export ended in a timeout, instead of failing again immediately. Previously the retry skipped the timed-out dependency, so the parent build could never finish; the workaround was to export that dependency directly first.&#x20;
> > > > * **Actions:** deleting an action whose business rule calls a function now works instead of returning a server error. This affected any action at any nesting level, in both projects and libraries; the workaround was to delete the rule from the action first.&#x20;
> > > > * **Gateways:** an expression that fails to evaluate on an exclusive gateway now surfaces as an incident on the process instance. Previously the failure appeared only in the service logs, with no feedback in the platform.&#x20;
> > > > * **Task management:** the row-selection checkbox column no longer carries an invisible sort control. Clicking it by accident previously re-sorted the view and cleared the current selection. Changing the page size no longer opens the wrong process from the list. &#x20;
> > > > * **Library resource overview:** opening the resource overview for a library process no longer fails with a server error, and a process used from a library is no longer listed once per consuming project version.&#x20;
> > > > * **Project versions:** a branch merge no longer gets stuck awaiting correction when the final correction response arrives while a background synchronization is still running, and merging versions no longer fails with a navigation-areas error.&#x20;
> > > > * **UI Flows:** table filters, sorting, and the current page are kept when you navigate away and back, and across rebuilds. The page index was previously lost on back-navigation.&#x20;
> > > > * **Reusable UI templates:** static input mappings configured on a reusable template are now applied at runtime.&#x20;
> > > > * **Subprocesses:** dismissing a subprocess started from an embedded call activity no longer returns a 403.&#x20;
> > > > * **Entry points:** the entry-point picker in version settings now lists only processes and UI flows from the current project. Resources from dependency libraries were previously offered and could be selected.&#x20;
> > > > * **Themes and CMS resources:** exporting a theme no longer includes duplicate non-system copies of system icons, so repeated imports stop multiplying them, and importing no longer leaves system substitution tags missing.&#x20;
> > > > * **Documents:** CSV generation from spreadsheet-derived data no longer produces oversized output built from trailing empty cells and rows.&#x20;
> > > > * **Generated documents:** a document whose storage write fails now returns an error instead of being recorded as successful with a download path that cannot be opened. Transient storage write failures are retried first. The same guard covers the archive, encrypt, decrypt, convert, combine, split, and persist operations.&#x20;
> > > > * **Renderers:** the document preview shows its subtitle again, and the file-upload error message picks up the configured theme.&#x20;
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Improvements
> > > >
> > > > * **Cross-version import:** importing a project build or version exported from an older platform line now completes the imported theme from the destination's system theme, so components added since the export are no longer missing. Existing values in the exported file are never overwritten, so customizations survive.&#x20;
> > > > * **Access management:** the project share modal warns when an access entity references roles that are missing from the build, and an end-user role can be removed from a project version.&#x20;
> > > > * **Runtime authorization:** runtime-manager, process-engine, and events-gateway check each request from a signed-in end user against the roles defined in the running build, and reject it with a 403 when the user holds none of them. Service accounts aren't affected.&#x20;
> > > > * **Libraries:** the UI Flows entry is hidden from the library menu, where it did not apply.&#x20;
> > > > * **Integration Designer performance:** service startup no longer scans the full token-instance collection to warm up, and the run-list summary queries are indexed and gated.&#x20;
> > > > * **Database migrations:** the lock that guards Liquibase schema migrations at service startup is now a database session lock: `pg_advisory_lock` on PostgreSQL, `DBMS_LOCK` on Oracle. A pod that stops mid-migration has its lock released automatically when the database closes the session, so there is no stale `databasechangeloglock` row to clear by hand. The previous mechanism recovered a stuck lock through the Kubernetes API, which required the `pods/status` permission on every service account and silently deactivated on Kubernetes 1.33 and newer. Oracle deployments need new database grants before upgrading: see the [deployment guidelines](./deployment-guidelines-v5.9.4#liquibase-migration-lock-moves-to-database-session-locks).&#x20;
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade compatibility:** FlowX.AI 5.9.4 is compatible with 5.9.3. No data migration is required. One deployment-level change applies: the Helm charts split the image reference into `image.registry` and `image.repository`. Oracle deployments also need new database grants for the Liquibase migration session lock.
>
> > [!WARNING]
> >
> > **Helm values migration.** Deployments that redirect images through `global.imageRegistry` need no action. Deployments that embedded the registry inside `image.repository` must move the registry portion out before upgrading. See [Configuration changes](./deployment-guidelines-v5.9.4#configuration-changes).
>
> ### Compatibility
>
> > [card] Upgrade path
> >
> > Direct upgrade from 5.9.3 → 5.9.4. No data migration; review the Helm values change first.
>
> > [card] Component compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. The Angular SDK moves to Angular 21.
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.9.4](./deployment-guidelines-v5.9.4).
>
> ### What's next
>
> **FlowX.AI 5.9.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# Deployment guidelines v5.9.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/deployment-guidelines-v5.9.5

Component versions, configuration, and deployment notes for FlowX.AI 5.9.5 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.5 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.4 is non-breaking and requires no data migration. The headline addition, native PostgreSQL partitioning, is opt-in: deployments that never enabled data partitioning are not affected. Review [Configuration changes](#configuration-changes) before you deploy.

> [card] Upgrade Path
>
> **5.9.4 → 5.9.5**: Direct upgrade. No data migration is required.
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.3 or earlier directly?** Review the [5.9.4 deployment guidelines](../v5.9.4-august-2026/deployment-guidelines-v5.9.4) first: the Helm image registry split applies when you skip 5.9.4. Upgrading from 5.9.0, 5.9.1, or 5.9.2, also review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) for the organization-ID migration fix and manually marked Liquibase changesets.

## Component versions

### Core components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.10 | 10.171.3 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.7 | 10.149.3 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.7 | 10.110.4 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.6 | 10.91.2 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.100.7 | 10.97.2 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.110.7 | 10.107.4 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.7 | 10.121.3 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.6 | 10.109.3 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.6 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.6 | 10.89.2 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.6 | 10.99.2 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.7 | 10.95.2 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.200.9 | 10.197.5 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.158.7 | 10.155.5 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.7 | 10.104.3 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.7 | 10.119.3 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.6 | 10.98.2 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.101.6 | 10.98.2 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.6 | 10.95.2 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.6 | 10.66.2 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.7 | 10.30.2 | 10.8.0 | - | - |
| **license** | 10.87.6 | 10.84.2 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB**: see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the AI Platform Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.277.0 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.282.5 | 10.275.0 | 10.230.2 | 10.181.0 | 9.165.3 |
| **react-saas** | 10.282.5 | 10.275.0 | 10.230.2 | - | - |
| **iOS renderer** | 10.6.2 | 10.6.0 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.9.3 | 10.8.0 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.0 | 10.10.2 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.0 | 10.10.2 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.0 | 10.10.2 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.0 | 10.10.2 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.0 | 10.10.2 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.0 | 10.10.2 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.6 | 10.32.2 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.0 | 10.10.2 | - | - | - |
| **ai-assistant** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.0 | 10.10.2 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.0 | 10.10.2 | - | - | - |
| **flowx-docs** | 5.9.5 | 5.9.4 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.5 | 5.9.4 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

> [!NOTE]
>
> 5.9.5 introduces no new Kafka topics over 5.9.4. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Review [Configuration changes](#configuration-changes): everything new in this release is opt-in or ships with a safe default, so no values change is required for a standard upgrade.
2. Update container images to the 5.9.5 versions listed in the table above.
3. Deploy services using your standard deployment process.
4. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Native PostgreSQL partitioning (opt-in)

Process-instance archiving on PostgreSQL can now use native declarative partitions instead of the legacy copy-based mechanism. Data partitioning itself remains **off by default** (`FLOWX_DATA_PARTITIONING_ENABLED` is `false`), so deployments that never enabled it are not affected.

New process-engine variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DATA_PARTITIONING_ARCHIVING_POSTGRESNATIVE` | Use native PostgreSQL partitions for archiving when partitioning is enabled. PostgreSQL only; other databases keep the existing mechanism. | `true` |
| `FLOWX_DATA_PARTITIONING_PREMAKECRONEXPRESSION` | Schedule for the job that creates upcoming partitions in advance. | `0 0 23 * * ?` |
| `FLOWX_DATA_PARTITIONING_PREMAKEPARTITIONSAHEAD` | How many future partitions the job keeps created ahead of the current one. | `2` |

> [!WARNING]
>
> Enabling native partitioning converts the process-instance tables to partitioned tables, and the conversion is one way: there is no supported path back to unpartitioned tables. Review the [partitioning and archiving setup guide](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving#native-postgresql-partitioning) before turning it on.

#### Document plugin: processing size limits

The document plugin now enforces size limits on archive, encryption, and extraction operations. Input over the limit is rejected instead of processed. The defaults are generous; override them only if your documents legitimately exceed them.

| Environment Variable | Description | Default Value |
| - | - | - |
| `DOCUMENT_ARCHIVE_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for archive operations. | `209715200` (200 MB) |
| `DOCUMENT_ENCRYPTION_MAX_FILE_SIZE` | Maximum size, in bytes, of a file accepted for encryption. | `104857600` (100 MB) |
| `DOCUMENT_EXTRACT_MAX_UNCOMPRESSED_SIZE` | Maximum total uncompressed size, in bytes, an archive may expand to during extraction. | `209715200` (200 MB) |

#### Integration Designer: workflow output size guard

Workflow output published to Kafka is now size-checked before sending. A root workflow output that exceeds the limit fails the workflow run with the failure type `outputTooLargeForKafka` instead of being silently dropped by the broker's message-size limit. The check applies to root workflow outputs on automatic and default-path completion; subworkflow outputs are not checked.

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_KAFKA_PAYLOAD_SIZE_LIMIT` | Maximum serialized size, in bytes, of a root workflow output published to Kafka. | `786432` |

> [!TIP]
>
> Keep this limit below your broker's `max.message.bytes`. The default, 768 KB, sits safely under the common 1 MB broker default.

#### Advancing datasource metrics

The process engine and Integration Designer now register their advancing datasource under a named connection pool (`advancing`), so its metrics are distinguishable from the main datasource pool in Prometheus. No configuration action is required.

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.5-september-2026/v5.9.5-september-2026

Maintenance release for the 5.9.x LTS line. Native PostgreSQL partitioning for process data, bug fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. It also brings native PostgreSQL partitioning to process data. Review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade.

> [card] Release Highlight
>
> **FlowX.AI 5.9.5** is a maintenance release for the 5.9.x LTS:
>
> * **Native PostgreSQL partitioning:** process data tables are partitioned by the database itself, so removing old data becomes a partition drop instead of a bulk delete
> * **Key fixes:** audit entries no longer missing or attributed to the wrong application, merge conflicts raised for changes inside embedded subprocesses, self-hosted Keycloak issuer derived from configuration
> * **Integrations:** an SFTP private key can be stored as a multi-line PEM
> * Backend, Designer, and renderer stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.5 is compatible with 5.9.4, and the upgrade requires no data migration. Native PostgreSQL partitioning is opt-in: if you had already enabled data partitioning, review the [deployment guidelines](./deployment-guidelines-v5.9.5) before you upgrade, because the conversion to native partitions runs automatically for you and is one way.

**Before you upgrade, check these:**

* **AI job queues:** each AI service now consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group, and the new groups read only jobs published after they start. Wait until the `ai-services` group has no lag on the job topics before you upgrade, so no queued job is skipped. If your cluster restricts consumer groups with ACLs, allow the new groups first.
* **Relational data sources:** Oracle data sources connect only to hosts that resolve to a public address. Add private database hosts to the allowlist, as described in [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).
* **Service-account secrets:** confirm every service-account client secret is set on `authorization-system`, or the service stops at startup. The secrets are listed in the [Authorization setup guide](/5.9/setup-guides/authorization-setup-guide).
* **Dashboards and alerts:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total`.
* **Runtime log levels:** the `loggers` actuator endpoint is no longer exposed by default. Add it back as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).
* **Data partitioning:** if you had already turned on data partitioning, the conversion to native partitions runs automatically on upgrade and is one way. See the [deployment guidelines](./deployment-guidelines-v5.9.5).

**Upgrade path:** direct upgrade from 5.9.4. Upgrading directly from 5.9.0, 5.9.1, or 5.9.2? Review the [5.9.2 deployment guidelines](../v5.9.2-july-2026/deployment-guidelines-v5.9.2) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.9.x. Component versions are listed in the [5.9.5 deployment guidelines](./deployment-guidelines-v5.9.5).

***

## Native PostgreSQL partitioning

The process engine stores process data in tables that PostgreSQL itself partitions by time. Retention then
works by dropping whole partitions rather than deleting rows one at a time, which keeps the cost of
removing old data flat as the tables grow.

This is the same partitioning model described for the 5.12 line, delivered into the 5.9.x LTS.

For how partitioning interacts with archiving and retention, see [Process instance data archiving](/5.9/setup-guides/flowx-engine-setup-guide/process-instance-data-archiving).

***

## Full changelog

### New

* **Integrations:** an SFTP private key can be stored as a multi-line PEM, in both the Private Key field and in a configuration parameter, and is passed through to the connection.&#x20;
* **Process engine:** process data tables can use native PostgreSQL partitioning, so retention drops whole partitions instead of deleting rows. Opt-in. See [Native PostgreSQL partitioning](#native-postgresql-partitioning).&#x20;

### Changed

* **AI Gateway:** logs carry structured key-value fields and record the length of a user message instead of an excerpt of its text.&#x20;
* **AI platform services:** every AI service applies the platform's Kafka security setting the same way, including TLS, and accepts the same OAuth token endpoint setting as the core services. An unsupported Kafka security protocol now stops the service at startup.&#x20;
* **AI platform services:** each AI service consumes Kafka jobs in its own consumer group instead of the shared `ai-services` group. The new groups read only jobs published after they start, so let the `ai-services` group reach zero lag before you upgrade. If your Kafka cluster restricts consumer groups with ACLs, allow the new groups before you upgrade.&#x20;
* **AI platform services:** the LLM configuration cache listener keeps one stable Kafka consumer group per pod, so restarts no longer leave orphaned groups on the broker.&#x20;
* **Application manager:** loading app versions is faster on databases that hold many deleted apps. The upgrade creates two new database indexes.&#x20;
* **Authorization system:** a missing or blank service-account client secret now stops `authorization-system` at startup, and the log names each affected client and its setting.&#x20;
* **Builds:** exporting and importing a build resolves dependencies more consistently, and a parent build is reconciled when an import it depends on finishes.&#x20;
* **Document plugin:** archive, encryption, and extraction operations enforce size limits, and input over the limit is rejected. See [Document plugin: processing size limits](./deployment-guidelines-v5.9.5#document-plugin-processing-size-limits).&#x20;
* **Integration Designer:** a root workflow output larger than the Kafka payload limit fails the run with `outputTooLargeForKafka` instead of being dropped by the broker. See [Integration Designer: workflow output size guard](./deployment-guidelines-v5.9.5#integration-designer-workflow-output-size-guard).&#x20;
* **NoSQL DB runner:** Oracle data sources can connect only to hosts that resolve to a public address, unless the host is allowed explicitly. Databases on a private network need an allowlist entry. See [Relational database host restrictions](/5.9/setup-guides/nosql-db-runner#relational-database-host-restrictions).&#x20;
* **Observability:** the `loggers` actuator endpoint is no longer exposed by default. To keep changing log levels at runtime, add `loggers` to the exposure list, as described in [Changing log levels at runtime](/5.9/setup-guides/admin-setup-guide#changing-log-levels-at-runtime).&#x20;
* **Observability:** the advancing engine reports additional metrics for its processing, and the metric names follow the platform naming convention.&#x20;
* **Observability:** the Redis cache error counter is renamed from `cache_error_total` to `flowx_cache_error_total` and gains an `error_class` label. Update dashboards and alerts that use the old name.&#x20;

### Fixed

* **Audit:** audit entries are no longer missing, duplicated, or recorded against the wrong application.&#x20;
* **Authorization system:** service-account clients that were created without a secret receive the configured secret on upgrade. Clients that already have a secret keep it.&#x20;
* **Designer:** searching reusable functions is case-insensitive, in the Functions list and in the function picker of Script and Fork nodes.&#x20;
* **Document plugin:** archive, extract, encrypt, and decrypt operations stage files in temporary storage instead of holding them in memory, so a large archive no longer exhausts service memory.&#x20;
* **Events gateway:** real-time updates resume automatically within seconds after a Redis failover, instead of requiring a pod restart.&#x20;
* **Identity:** on self-hosted deployments the Keycloak issuer is derived from configuration and matched exactly, so tokens are no longer rejected when the configured base URL and the issuer in the token differ.&#x20;
* **Process execution:** fixed rare cases where a process or workflow token stopped advancing with no error logged, and a database deadlock during cleanup of finished advancing partitions.&#x20;
* **Project versions:** a change made inside an embedded subprocess is now taken into account when a merge computes conflicts. Previously such a change could pass through a merge without a conflict being raised.&#x20;
* **Redis connectivity:** platform services, including AI Gateway, reconnect automatically after a Redis Sentinel failover or a dropped connection, and start even when Redis is briefly unavailable, without a pod restart.&#x20;
* **Renderers:** text substitution no longer breaks when a substitution tag receives an empty value.&#x20;
* **Runtime:** the runtime app context is cached correctly, which removes recurring `Redis cache PUT error` warnings and a database lookup on each runtime request.&#x20;

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# Deployment guidelines v5.9.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6

Component versions, configuration, and deployment notes for FlowX.AI 5.9.6 (5.9.x LTS maintenance release).

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 5.9.6 is a maintenance release for the 5.9.x LTS line. The upgrade from 5.9.5 adds one Kafka topic, a database table, and a MongoDB index. The table and the index are created automatically when the services start. Review [Kafka topics](#kafka-topics), [Configuration changes](#configuration-changes), and the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes) before you deploy.

> [card] Upgrade Path
>
> **5.9.5 → 5.9.6**: Direct upgrade. No manual data migration is required.
>
> **5.9.6 → 6.0.0**: See [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).
>
> Self-hosted customers still on the 5.1.x LTS upgrade directly to the 5.9.x line. See [Migrating from 5.1 LTS](/5.9/migrating-from-5.1-lts/overview).

> [!NOTE]
>
> **Upgrading from 5.9.4 or earlier directly?** Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first, then the earlier pages they point to.

## Component versions

### Core components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **process-engine** | 10.174.17 | 10.174.10 | 10.135.0 | 10.106.0 | 9.76.10 |
| **admin** | 10.152.14 | 10.152.7 | 10.116.0 | 10.93.0 | 9.76.8 |
| **designer** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **cms-core** | 10.113.13 | 10.113.7 | 10.86.0 | 10.67.0 | 9.47.6 |
| **scheduler-core** | 10.94.11 | 10.94.6 | 10.70.0 | 10.53.0 | 9.36.5 |
| **events-gateway** | 10.101.1 | 10.100.7 | 10.72.0 | 10.55.0 | 9.37.5 |
| **notification-plugin** | 10.111.1 | 10.110.7 | 10.83.0 | 10.64.0 | 9.40.5 |
| **document-plugin** | 10.124.13 | 10.124.7 | 10.94.0 | 10.75.0 | 9.45.5 |
| **task-management-plugin** | 10.112.12 | 10.112.6 | 10.84.0 | 10.66.0 | 9.44.7 |
| **reporting-plugin**\* | 10.1.8 | 10.1.6 | 0.2.6 | 0.2.6 | 0.2.8 |
| **data-search** | 10.92.11 | 10.92.6 | 10.69.0 | 10.52.0 | 9.33.5 |
| **audit-core** | 10.102.11 | 10.102.6 | 10.79.0 | 10.63.0 | 9.41.5 |
| **advancing-controller** | 10.98.12 | 10.98.7 | 10.73.0 | 10.55.0 | 9.36.6 |
| **integration-designer** | 10.201.2 | 10.200.9 | 10.162.0 | 10.128.0 | 9.60.7 |
| **application-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **runtime-manager** | 10.159.3 | 10.158.7 | 10.123.0 | 10.97.0 | 9.83.8 |
| **data-sync** | 10.107.13 | 10.107.7 | 10.81.0 | 10.58.0 | 9.34.4 |
| **authorization-system** | 10.122.13 | 10.122.7 | 10.96.1 | 10.77.0 | 9.44.6 |
| **nosql-db-runner** | 10.101.13 | 10.101.6 | 10.75.0 | 10.56.0 | 9.32.5 |
| **email-gateway** | 10.102.1 | 10.101.6 | 10.74.0 | 10.56.0 | - |
| **organization-manager** | 10.98.12 | 10.98.6 | 10.71.0 | 10.53.0 | - |
| **webhook-gateway** | 10.69.12 | 10.69.6 | 10.44.0 | 10.25.0 | - |
| **file-gateway** | 10.33.14 | 10.33.7 | 10.8.0 | - | - |
| **license** | 10.87.12 | 10.87.6 | 10.63.0 | 10.46.0 | - |

\* The reporting plugin is an optional add-on and is versioned independently of the platform, so its numbering does not follow the other components. It moved from the `0.2.x` scheme to `10.x` after 5.9.0. Pin the version listed for your release.

### Embedded components

* **SpiceDB** 1.52.0, deployed and upgraded by the **SpiceDB operator** 1.25.1.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart; its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/5.9/setup-guides/qdrant) for deployment and configuration.

### Renderers

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **@flowx/angular-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/angular-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-ui-toolkit** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/react-native-sdk** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-theme** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/react-native-ui-toolkit** | 10.285.4 | 10.277.0 | 10.230.2 | - | - |
| **@flowx/core-sdk** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **@flowx/core-theme** | 10.285.4 | 10.282.5 | 10.230.2 | 10.181.0 | 9.165.3 |
| **solution-portal** (renamed from react-saas) | 10.285.4 | 10.282.5 | 10.230.2 | - | - |
| **iOS renderer** | 10.9.2 | 10.6.2 | 10.4.1 | 10.3.0 | 9.0.32 |
| **Android renderer** | 10.10.2 | 10.9.3 | 10.5.0 | 10.3.0 | 9.0.44 |

### AI components

FlowX.AI groups AI services into four tiers by deployment role. **AI Base** components are the foundation; **AI Runtime** and **AI Dev Time** components both require Base to be installed first; **AI Extensions** are optional add-ons layered on top.

#### AI Base components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **knowledgebase-indexer-v2** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **knowledgebase-rag** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **embedder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **doc-parser** | 10.11.2 | 10.11.0 | 10.9.0 | 10.7.0 | - |

#### AI Runtime components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **agent-builder** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **data-privacy** | 10.11.2 | 10.11.0 | 10.1.0 | 10.1.0 | - |
| **doc-converter** | 10.11.2 | 10.11.0 | 10.2.3 | 10.2.3 | - |
| **evals-judge** | 10.11.2 | 10.11.0 | 10.1.1 | - | - |
| **speech-to-text** | 10.11.2 | 10.11.0 | 10.3.4 | 10.3.3 | - |
| **web-crawler** | 10.11.2 | 10.11.0 | 10.3.5 | 10.3.5 | - |

#### AI Dev Time components

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **ai-gateway** | 10.35.13 | 10.35.6 | 10.7.0 | - | - |
| **ai-analyst** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-architect** | 10.11.2 | 10.11.0 | - | - | - |
| **ai-assistant** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | - |
| **ai-designer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **ai-developer** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **planner** | 10.11.2 | 10.11.0 | 10.7.0 | 10.7.0 | 9.4.8 |
| **kb-enrichment** | 10.11.2 | 10.11.0 | - | - | - |
| **flowx-docs** | 5.9.6 | 5.9.5 | 5.9.0 | - | - |

#### AI Extensions

| Component | 5.9.6 | 5.9.5 | 5.9.0 | 5.8.0 | 5.1.13 (LTS) |
| - | - | - | - | - | - |
| **modpod** | 10.0.7 | 10.0.7 | 10.0.7 | 10.0.7 | - |
| **ai-observatory** | 10.7.2 | 10.7.2 | 10.3.2 | - | - |

> [!NOTE]
>
> For the plugins matrix, refer to the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9).

## Kafka topics

5.9.6 adds one Kafka topic. If your cluster does not create topics automatically, create it before you deploy, and allow both services in your ACLs.

| Topic | Producer | Consumer | Purpose |
| - | - | - | - |
| `ai.flowx.build.deployment-failed.v1` | runtime-manager | application-manager | Reports a build deployment that failed, so application-manager can queue it for a retry. |

The topic is included in the FlowX Kafka topics chart from version 10.2.0. For the full multi-release topic matrix, see the [5.9.0 deployment guidelines](../v5.9.0-june-2026/deployment-guidelines-v5.9#kafka-topics).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures:

1. Create the `ai.flowx.build.deployment-failed.v1` Kafka topic if your cluster does not create topics automatically. See [Kafka topics](#kafka-topics).
2. Review [Configuration changes](#configuration-changes). No values change is required for a standard upgrade.
3. The `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](./v5.9.6-october-2026#upgrade-notes).
4. Update container images to the 5.9.6 versions listed in the tables above.
5. Deploy services using your standard deployment process.
6. Verify deployment via **FlowX.AI Designer → Platform Status**.

### Configuration changes

#### Build redeployment retries

When a build deployment fails, application-manager queues it for a retry. The queue is now stored in the application-manager database, in the new `failed_deployment` table, instead of in Redis. The table is created automatically on startup. runtime-manager reports each failure on the `ai.flowx.build.deployment-failed.v1` topic, and application-manager consumes it.

New application-manager variables (the defaults fit a standard deployment):

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_BUILD_DEPLOYMENTFAILED` | Topic that carries failed build deployments. | `ai.flowx.build.deployment-failed.v1` |
| `KAFKA_CONSUMER_GROUPID_BUILD_DEPLOYMENTFAILED` | Consumer group that reads the topic. | `build-deployment-failed-group` |
| `KAFKA_CONSUMER_THREADS_BUILD_DEPLOYMENTFAILED` | Number of consumer threads for the topic. | `1` |

> [!WARNING]
>
> Retries that are still queued in Redis when you upgrade are not moved to the new table. Re-publish any build whose deployment failed shortly before the upgrade. The old entries stay in the Redis hash `build:failed-deployments:v3`, under the persistence key prefix configured for application-manager. Nothing reads them after the upgrade, so you can delete the hash.

#### MongoDB setting names

Services that use MongoDB now read their connection settings from new names. The previous `SPRING_DATA_MONGODB_*` variables still feed the new settings, so existing deployments need no change. Use the new names in new configuration.

| Previous variable | New variable |
| - | - |
| `SPRING_DATA_MONGODB_URI` | `SPRING_MONGODB_URI` |
| `SPRING_DATA_MONGODB_REPRESENTATION_UUID` | `SPRING_MONGODB_REPRESENTATION_UUID` |
| `SPRING_DATA_MONGODB_STORAGE` | `FLOWX_DATASOURCE_MONGO_STORAGE` |
| `SPRING_DATA_MONGODB_RUNTIME_ENABLED` | `FLOWX_DATASOURCE_APPRUNTIME_ENABLED` |
| `SPRING_DATA_MONGODB_RUNTIME_URI` | `FLOWX_DATASOURCE_APPRUNTIME_URI` |
| `SPRING_DATA_MONGODB_RUNTIME_REPRESENTATION_UUID` | `FLOWX_DATASOURCE_APPRUNTIME_REPRESENTATION_UUID` |

`SPRING_DATA_MONGODB_RUNTIME_AUTOINDEXCREATION` no longer has any effect: indexes on the runtime database are never created automatically.

#### Document parser models

The document parser image now contains its layout, table, and OCR models, so the parser downloads nothing at startup or on the first parse. It runs without internet access and on a read-only filesystem. `USE_DOCLING` no longer has any effect on the document parser and can be removed from its configuration.

#### Integration Designer: document download timeout

A REST node JSON body can include `"@@base64File(<path>)"` to send a Document Plugin file as base64. Downloading the file from the Document Plugin is cancelled after this timeout. See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json).

New integration-designer variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT` | Longest time a Document Plugin file download for a REST node JSON body may take before it is cancelled. | `PT5M` |

> [!NOTE]
>
> Confirm any required configuration changes against the setup guides before upgrading.

## Third-party supported component versions

Within each version line listed below, versions that have reached upstream end of life are not supported, even though their major/minor is listed.

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.9.x | Keycloak | 26 |
| 5.9.x | Kafka | 3.9, 4.0, 4.1, 4.2 |
| 5.9.x | PostgreSQL | 16, 17, 18 |
| 5.9.x | Oracle Database | 21c, 23ai |
| 5.9.x | MongoDB | 7, 8 |
| 5.9.x | Redis | 7, 8 |
| 5.9.x | Elasticsearch | 8, 9 |
| 5.9.x | Elasticsearch Sink Connector (\*) | 15 |
| 5.9.x | Angular (Web SDK) | 20.3, 21.2 |
| 5.9.x | React (Web SDK) | 19 |

(\*) Required only if using indexing via Kafka. Multiple sink connector implementations also work, as long as they are compatible with both the deployed Kafka and Elasticsearch version.

> [!NOTE]
>
> The table lists version lines, not individual versions. A version is supported for as long as its vendor still supports it, so check the version you plan to deploy against that vendor's lifecycle page before committing to it. When a version reaches upstream end of life it is no longer supported; upgrade that component to keep your deployment on a supported configuration. Versions can also be added during the family's lifetime as FlowX validates them.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).


# FlowX.AI 5.9.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026

Maintenance release for the 5.9.x LTS line. Durable build redeployment retries, project version merge fixes, and security patches.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release in the **5.9.x** line, focused on **bug fixes**, **security patches**, and **stability improvements**. Review the [deployment guidelines](./deployment-guidelines-v5.9.6) before you upgrade: this release adds one Kafka topic.

> [card] Release Highlight
>
> **FlowX.AI 5.9.6** is a maintenance release for the 5.9.x LTS:
>
> * **Durable build redeployments:** a build deployment that failed and waits for a retry is stored in the database, so a Redis flush or restart no longer drops it
> * **Key fixes:** project version merges no longer lose navigation areas, Resources Changed no longer flags unchanged resources, and Number attributes keep the selected subtype
> * Backend, Designer, and AI stability fixes plus security patches. Every change is listed in the [full changelog](#full-changelog)

***

## Upgrade notes

> [!NOTE]
>
> **Upgrade compatibility:** FlowX.AI 5.9.6 is compatible with 5.9.5. The upgrade adds a database table and a MongoDB index, both created automatically when the services start.

**Before you upgrade, check these:**

* **AI Platform Helm chart:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart) as part of your upgrade to 5.9.6. The migration needs downtime.&#x20;
* **Kafka topics:** create the `ai.flowx.build.deployment-failed.v1` topic if your cluster does not create topics automatically, and allow it in your ACLs. `runtime-manager` produces it and `application-manager` consumes it. See [Kafka topics](./deployment-guidelines-v5.9.6#kafka-topics).
* **Pending build redeployments:** retries that are still queued in Redis when you upgrade are not carried over. Re-publish any build whose deployment failed shortly before the upgrade. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).
* **Workflow node retries:** retry waits now grow exponentially and the max interval caps each wait instead of the whole retry window. Review the retry settings of nodes that rely on the previous timing.
* **Connection tests:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources. Grant these to custom roles that run connection tests.
* **Integration Designer startup:** the first start after the upgrade builds a new index on the `workflow_instances` MongoDB collection. On a large collection, allow extra time before the readiness check passes.
* **React Native SDK hosts:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` and keeps showing the current process, like the Android and iOS SDKs. Update your app to dispose the current process handle and continue the new process. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).

**Upgrade path:** direct upgrade from 5.9.5. Upgrading from 5.9.4 or earlier? Review the [5.9.5 deployment guidelines](../v5.9.5-september-2026/deployment-guidelines-v5.9.5) first.

**Component compatibility:** compatible with FlowX.AI SDKs (Angular/React/React Native/iOS/Android) and Designer 5.9.x. Component versions are listed in the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6).

***

## Full changelog

### New

* **Integration Designer:** a REST node JSON body can include `"@@base64File(<path>)"`. When the request is sent, the marker is replaced with the base64-encoded content of the Document Plugin file at that path. The download from the Document Plugin times out after 5 minutes by default (`FLOWX_DOCUMENTPLUGIN_DOWNLOADTIMEOUT`). See [Content Type: JSON](/5.9/docs/platform-deep-dive/integrations/endpoint-file-handling#content-type-json) and [Integration Designer: document download timeout](./deployment-guidelines-v5.9.6#integration-designer-document-download-timeout).&#x20;

### Changed

* **AI Platform services:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. See [Migrate to the flowx-ai Helm chart](/5.9/setup-guides/migrate-to-flowx-ai-helm-chart).
* **All services:** every service image sets `MALLOC_ARENA_MAX=2`, which lowers native memory use. A value set in your deployment overrides it.&#x20;
* **Builds:** a build deployment that failed and waits for a retry is stored in the `application-manager` database instead of Redis, so a Redis flush or restart no longer drops it. The failure is reported on the new `ai.flowx.build.deployment-failed.v1` Kafka topic. Retries still queued in Redis at upgrade are not carried over. See [Build redeployment retries](./deployment-guidelines-v5.9.6#build-redeployment-retries).&#x20;
* **Designer:** a custom component, document template, or notification template that is still in use can be deleted. The delete confirmation first lists where it is used, because those references break when it is deleted.&#x20;
* **Document parser:** the layout, table, and OCR models are part of the image, so nothing is downloaded at startup or on the first parse, and the parser works without internet access or on a read-only filesystem. A request for the RapidOCR engine runs Tesseract instead. The `USE_DOCLING` setting has no effect. See [Document parser models](./deployment-guidelines-v5.9.6#document-parser-models).&#x20;
* **Integration Designer:** workflow node retry waits grow exponentially (the interval multiplied by the coefficient for each further attempt), and the max interval caps each wait instead of limiting the whole retry window. Each attempt keeps its own entry in the run history.&#x20;
* **Integration Designer:** a new index on the `workflow_instances` MongoDB collection speeds up lookups of child workflow runs. It is created when the service starts.&#x20;
* **MongoDB settings:** services read the MongoDB connection from new setting names, such as `SPRING_MONGODB_URI`. Existing `SPRING_DATA_MONGODB_*` values keep working, so no change is needed. See [MongoDB setting names](./deployment-guidelines-v5.9.6#mongodb-setting-names).&#x20;
* **Notifications and data sources:** testing an SMTP connection needs the permission to edit notification templates, and testing an IMAP or Microsoft Outlook connection needs the permission to edit data sources.&#x20;
* **Import:** the compatibility of an export file is now validated at the start of the import, so an incompatible file fails faster.&#x20;
* **Solution portal:** the `react-saas` web app is renamed `solution-portal`, and its container image is published under the new name. See the [5.9.6 deployment guidelines](./deployment-guidelines-v5.9.6) for its version.&#x20;

### Fixed

* **Advancing controller:** Prometheus can scrape the metrics endpoint, like the other services. Paths outside the actuator endpoints stay closed.&#x20;
* **AI services:** services start when `PYTHONPATH` is overridden in the pod spec, for example by an APM agent injector.&#x20;
* **Android SDK:** the loader shows while an action runs on a modal screen, and tapping an action button several times in a row no longer leaves the loader on screen with the next screen never shown.&#x20;
* **Data model:** switching an attribute from one Number subtype to another shows and saves the subtype you selected.&#x20;
* **Project versions:** **Resources Changed** no longer reports a resource as changed when only its misconfiguration warnings differ, so editing one business rule no longer flags the other business rules in the process.&#x20;
* **Project versions:** merging a branch keeps navigation area lists whole, so areas no longer disappear or fail with "Navigation area name already exists". Merging also removes UI templates whose parent container the merge deleted, instead of leaving them at the root of the UI flow.&#x20;
* **React Native SDK:** when the backend starts a new process, the SDK notifies your app through `FlowX.newProcessStarted` instead of replacing the shown process itself, like the Android and iOS SDKs. See [New process started](/5.9/sdks/react-native-renderer#new-process-started).&#x20;
* **React Native SDK:** a custom component keeps receiving data after the app returns from the background, for example from the Android document picker, so a document upload waiting for its link completes.&#x20;
* Stability fixes across project version merges, Integration Designer workflows, builds, the Designer, the renderers, and the AI services.

### Security

* **All components:** security patches and dependency upgrades to address known vulnerabilities.&#x20;


# FlowX.AI 5.9.x to 6.0.0 changelog
Source: https://docs.flowx.ai/release-notes/v6.x/5.9-to-6.0-changelog

Every change a self-hosted FlowX.AI 5.9.x installation picks up when it moves to 6.0.0, grouped by release and type, with an RSS feed.

This page lists what changes for a self-hosted FlowX.AI 5.9.x installation that moves to 6.0.0, newest first. Releases 5.10 to 5.13 shipped to SaaS first, and self-hosted installations get their features with 6.0.0. Changes already delivered in a 5.9.x patch are in the [5.9.x LTS changelog](/release-notes/v5.x/5.9-lts-changelog) and are not repeated here. Mobile renderers and the React Native SDK are covered in their own release notes.

On FlowX.AI SaaS, apps moved from 5.13.0 to 6.0.0, so only the 6.0.0 entry applies to them, including its upgrade actions.

**6.0.0**

October 2026

**Upgrade actions:** check these in your existing apps.

* **AI node prompts:** the chat message is no longer appended. Reference `${userMessage}` in **Context**. [Details](/6.x/ai-platform/chat-driven-workflows#context)
* **AI node retries:** on by default, up to 10 times, 30 seconds apart. [Details](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service)
* **Substitution tags:** `@@key` is rewritten to `${tag:key}`, and a missing `sys_*` tag now renders empty. [Details](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#what-changes-in-existing-apps-when-you-upgrade)
* **FlowX Database and Unmanaged MongoDB writes:** `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter are rejected. To match every document, pass `{"_id": {"$exists": true}}`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb)
* **Masked names:** data-privacy placeholders now carry the gender, such as `<NAME_F_1>`. Update prompts or scripts that match `<NAME_1>`. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy)
* **Email triggers over IMAPS:** the mail server's certificate is now verified, so a self-signed or mismatched certificate stops the trigger from connecting. [Details](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway)
* **Evaluations:** datasets become test cases with no checks, so an experiment skips them until you add an assert or evaluator. [Details](/6.x/ai-platform/evaluations#datasets-from-earlier-versions)
* **Exports from 5.1.x:** they no longer import, and 5.1.x is no longer an export target. Import a 5.1.x export into a 5.9.x environment and export it again from there. [Details](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x)
* **Scripts on GraalVM:** they now stop at the same per-language time limit as the native engine, 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0 they had no limit. [Details](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits)

Self-hosted installations also follow the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) and the [migration guide](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview) for the Helm chart and renderer SDKs.

#### New

* **Developer Agentic Harness:** a plan can split the work into stories, delivered one at a time, each with how to test it. Comment mode lets you select a component in the running app and ask for a change, and conversations follow you across the Designer. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Integration Designer:** add schedules to a workflow's Start node to run it once on a date or repeatedly on an ISO or cron cycle. A schedule fires only after you activate it in **Runtime** → **Runtime Settings** → **Schedules**. See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
* **Integration Designer:** the Generate Tabular File node turns an array of rows into a CSV or XLSX file. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
* **FlowX Database:** an index can enforce unique values on one attribute or a compound key, and existing duplicates are reported when you run **Apply Indexes**. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
* **Knowledge Base:** **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
* **Resources:** **Documentation** in a resource's menu holds a short description and longer Markdown documentation. Media Library assets get a description, used as the image's alt text. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
* **Substitution tags:** write `${tag:key}` anywhere in a component's text, next to static text and process data. The upgrade rewrites whole-value `@@key` references to `${tag:key}`, and `@@key` keeps working as a whole value. See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).

#### Changed

* **Designer header:** the header holds the project name, the **Config** / **Runtime** switch, the **Build with AI** and **Comment** toggles, and **Run project**. Branching, the current version, and **Commit Changes** move to a version block in the footer. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
* **AI nodes:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when its AI service or provider can't be reached. Turn on **Allow Retry** to set your own count, interval, and backoff. See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
* **Chat-driven workflows:** the chat message is no longer appended to an AI node's prompt. Reference `${userMessage}` in the node's **Context**. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
* **Evaluations:** each workflow has its own test cases, grouped by tags, with **equals** and **equals as JSON** asserts and LLM evaluators. The upgrade converts datasets to test cases with no checks, so add an assert or evaluator to each one before you run it. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
* **Certificates:** the **Certificates** panel on REST and File Storage data sources has two parts: **Trust** (System CAs, Custom CA, or None (insecure)) and **Identity** for mutual TLS. Existing settings are converted automatically. See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates).
* **Knowledge Base:** turning **Containing Personal Information** on or off re-embeds the existing content with the new model. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested).
* **Issues Console:** a check also covers the version itself: entry points, theme, library builds, and unused dependencies. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
* **Notification center:** covers version imports and build exports and imports, alongside version exports and process instance migrations. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
* **Configuration parameters:** after you save a sensitive value, the Designer shows `********` in its place. The real value is still used at runtime. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
* **Script engine:** scripts on GraalVM stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
* **Canvas:** **Auto-arrange** on the workflow canvas and **Arrange** on the process canvas show a layout preview before anything moves. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).
* **Timer events:** timer nodes use the schedule editor. Dates and times are picked in local time and saved in UTC. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).
* **Versioning:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).
* **Datepicker:** **Allow manual input** lets users type a date in the pattern of the project's default locale. Web only.
* **Data mapping:** typing a new attribute path, such as `client.address.street`, creates the data types it names when you save the mapping.

#### Removed

* **AI agents:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors are removed. Open the agent rail with ⌘K (Ctrl+K) or the sparkle toggle in the header. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Evaluations:** the Code evaluators are removed. Use **equals** in place of Exact match and **equals as JSON** in place of JSON match. Levenshtein has no replacement. See [Evaluations](/6.x/ai-platform/evaluations).
* **Export and import:** exports from 5.1.x no longer import, and 5.1.x is no longer an export target. See [Exports from 5.1.x](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#exports-from-5-1-x).

#### Deprecated

* **GraalVM script engine:** deprecated. FlowX.AI 6.1.x is the last release family that supports it. Scripts on GraalVM keep working in 6.0.0; move them to the native engine. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).

[6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) · [6.0.0 deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)

**5.13.0**

September 2026

#### New

* **Developer Agentic Harness:** an AI agent in the Designer builds and changes apps from a plain-language description. It surveys the app, drafts a plan for you to confirm, and runs the change on its own branch; merging and serving a new version stay with you. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
* **Notification center:** a bell in the Designer opens a 30-day notification history with read state, search, and filters. See [Notification center](/6.x/docs/flowx-designer/notification-center).
* **UI Designer:** copy UI components and paste them into another UI Flow, app, or context. The paste names anything it could not place, and pasted components get unique names.
* **Versioning:** committing or merging a version takes an optional description of up to 2000 characters, and a commit details view shows what a version contains. See [Commit descriptions and details](/6.x/docs/projects/managing-applications/versioning#commit-descriptions-and-details).
* **Runtime:** an operator with the corrective-actions role moves the token of a running process instance to another node. See [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
* **Document classifiers:** a classifier's corpus can be exported and imported between environments, and viewed read-only in the **Data** tab. See [What travels between environments](/6.x/docs/platform-deep-dive/integrations/document-classifiers#what-travels-between-environments).
* **Integration Designer:** the File Encryption node encrypts or decrypts a file with a password inside a workflow. The file path and password take expressions.
* **UI Designer:** a start workflow trigger takes a condition, so the workflow starts only when the condition holds.&#x20;
* **FlowX Database:** the Intersects operator matches documents whose array field shares at least one value with a given list. See [Intersects on array fields](/6.x/docs/platform-deep-dive/integrations/flowx-database#intersects-on-array-fields).
* **Personal Information Guard:** AI nodes with the input scan on log the request as the model received it, with placeholders in place of the detected values. See [Request after PII anonymization](/6.x/ai-platform/personal-information-guard#request-after-pii-anonymization).

#### Changed

* **Access management:** the Workspace corrective actions editor role replaces the Workspace operations editor role. Users and groups with the old role move to the new one automatically. See [Workspace corrective actions editor permission matrix](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix).
* **Export and import:** version exports bundle dependencies the same way build exports do, and the export dialog preselects the target platform version. See [Version exports that bundle dependencies](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#version-exports-that-bundle-dependencies).
* **Integration Designer:** the Tabular Data Extraction node becomes the Data Parse node and also parses XML and JSON. See [Data Parse: XML and JSON support](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support).
* **Knowledge Base:** embedding jobs are scheduled fairly by default, so a large ingestion no longer delays small jobs queued behind it.
* **File sources:** Document and Image components share one source configuration. In process user tasks, the **Document Plugin Path** source takes a Documents plugin `downloadPath` directly. See [Selecting the file to download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download#selecting-the-file-to-download).
* **Task management:** the task list searches, filters, and sorts on the translated labels it displays. See [Search and sort on translated labels](/6.x/docs/platform-deep-dive/core-extensions/task-management/task-management-localization#search-and-sort-on-translated-labels).
* **Substitution tags:** custom tags can no longer start with `sys_`, which is reserved for system tags. See [Substitution tags](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags).
* **Elasticsearch:** new process instance and audit log indices default to `auto_expand_replicas` `0-1`, which overrides a fixed replica count. See [Elasticsearch replica auto-expansion](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13#changed-default-elasticsearch-replica-auto-expansion).
* **Processes:** the process name moves from **Settings** into a **Details** modal.
* **User management:** inviting many users at once has a reworked flow, and a sign-up link takes new users directly to the right solution.

[5.13.0 release notes](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) · [5.13.0 deployment guidelines](/release-notes/v5.x/v5.13.0-september-2026/deployment-guidelines-v5.13)

**5.12.0**

September 2026

**Upgrade actions:** the webhook gateway now reads the runtime registry, which adds a MongoDB dependency it did not have before. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets).

#### New

* **Integration Designer:** turn on **Parallel Multi-Instance** on a Subworkflow node to start one subworkflow per element of an input array and collect the results in an output array. See [Parallel multi-instance](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance).
* **Integration Designer:** email and webhook triggers can start an integration workflow, not only a process. See [External triggers](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).
* **Integration Designer:** a Subworkflow node can route a mapping failure to its own branch instead of stopping the parent workflow. It is opt-in per node. See [Routing a subworkflow failure](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#routing-a-subworkflow-failure).
* **Integration Designer:** the Send Notification node fills a project notification template from workflow data and sends it. See [Send Notification node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#send-notification-node).
* **Db2 data source:** IBM Db2 joins the relational data sources, with Db2 for i as the default and Db2 LUW also supported. Db2 for z/OS is listed but not implemented, and selecting it fails with an error. See [Db2 database](/6.x/docs/platform-deep-dive/integrations/db2-database).
* **Runtime:** bulk migration moves a filtered set of process instances to a new build in one run, with a check before it runs. See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances).
* **Runtime:** a Workflow Instances page lists every workflow run in the project, filterable by status, date, and origin. The Process Instances and UI Flow Sessions lists gain status and start-date filters. See [Workflow instances](/6.x/docs/projects/runtime/workflow-instances).
* **Personal Information Guard:** mask and restore nodes place personal-data handling as explicit workflow steps. See [Masking and restoring across several nodes](/6.x/ai-platform/personal-information-guard#masking-and-restoring-across-several-nodes).
* **Deep Research node:** researches a question across the open web and files a cited report into a Knowledge Base. Depth is Quick, Standard, Deep, or Custom, and domains can be restricted with an allow or deny list. See [Deep Research node](/6.x/docs/platform-deep-dive/integrations/deep-research-node).
* **Custom Agent:** a reusable function with input and output slices can be an agent tool. Built-in tools are a catalog of twenty tools in five categories: Math, List, Date, Text, and Web search. See [Tools tab](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#tools-tab).
* **Chat component:** users rate an agent's answer and add a reason, and the ratings are recorded in audit. See [Rating an answer](/6.x/ai-platform/chat-component#rating-an-answer).
* **Evaluations:** custom evaluators score with Numeric or Binary rules and belong to the workflow you create them in. See [Custom evaluators](/6.x/ai-platform/evaluations#custom).
* **Issues panel:** the Designer validates the resources in a project version and collects the findings in one **Issues** panel. See [Checking for issues](/6.x/docs/projects/managing-applications/checking-for-issues).
* **Versioning:** merge into any branch you can merge into, and archive, unarchive, or delete branches. See [Managing branches](/6.x/docs/projects/managing-applications/versioning#managing-branches).
* **Process canvas:** a **New Node** panel, drop-anywhere connecting, draggable control points on sequence flows, and swimlanes that resize from all four edges. See [Faster ways to build](/6.x/docs/building-blocks/process/process#faster-ways-to-build).
* **Reusable UI templates:** a template can be built for UI Flow pages as well as process user tasks. Templates created earlier count as Process templates. See [Where a template can be used](/6.x/docs/building-blocks/reusable-resources/reusable-ui#where-a-template-can-be-used).

[5.12.0 release notes](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026) · [5.12.0 deployment guidelines](/release-notes/v5.x/v5.12.0-september-2026/deployment-guidelines-v5.12)

**5.11.0**

August 2026

#### New

* **Custom Agent:** attach FlowX workflows as tools, each with a hint that tells the agent when to call it. See [How workflow tools run](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run).
* **Custom Agent:** agentic knowledge base search breaks a question into sub-queries and retries with reworded queries when the first pass finds nothing. **Show Reasoning** records the model's reasoning summary in the logs. See [Agentic knowledge base search](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#agentic-knowledge-base-search).
* **Knowledge Base:** a Knowledge Base with **Containing Personal Information** on can use a local embedding model, set up as a CUSTOM provider in the organization AI settings. See [Containing personal information](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#containing-personal-information).
* **Knowledge Base:** the Update Knowledge Base node can delete entries that match a metadata filter, and its FAIL branch reports what failed and how many chunks were rolled back. See [Delete entries](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#delete-entries).
* **Document classifiers:** define classes, upload training data, and train or import a model, then route each document page with the Document Classification node. See [Document classifiers](/6.x/docs/platform-deep-dive/integrations/document-classifiers).
* **Reusable functions:** Script and Condition (Fork) nodes in the Integration Designer can call reusable functions. See [Reusable functions](/6.x/docs/building-blocks/reusable-resources/reusable-functions).
* **Integration Designer:** the Subworkflow node can map input per start node and output per end node instead of raw JSON. See [Subworkflow node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#subworkflow-node).
* **Data model:** attributes support validators such as Required, Min/Max Value, Min/Max Length, Pattern, and Email Format, wherever the data model is used. See [Attribute validations](/6.x/docs/building-blocks/project-data-model#attribute-validations).
* **Templates:** document and notification templates use the structured data model, with typed attributes and an **Input Parameters** tab. See [Managing notification templates](/6.x/docs/platform-deep-dive/core-extensions/content-management/notifications-plugin/managing-notification-templates).
* **Chat component:** the chat button shows an unread-message badge, the panel searches conversation history, and the input can be disabled by a condition. See [Chat](/6.x/docs/building-blocks/ui-designer/ui-component-types/chat).
* **UI Flows:** a **Navigate To** action can require selected forms to pass validation before it navigates. See [Navigate To action](/6.x/docs/building-blocks/ui-flows#navigate-to-action).
* **UI Flows:** with **Allow multiple editors** off, a running session is restricted to its owner. New flows default to single-owner; existing and imported flows keep the shared behavior. See [Session owner](/6.x/docs/building-blocks/ui-flows#session-owner).
* **Process Renderer:** a process-end trigger runs a configured action when the embedded process ends. See [Process end handling](/6.x/docs/building-blocks/ui-flows#process-end-handling).

#### Changed

* **Chat-driven workflows:** a conversational workflow must send at least one chat reply, or the run fails with an error. See [Chat-driven workflows](/6.x/ai-platform/chat-driven-workflows).
* **Custom Agent:** the **Instructions** field is limited to 10,000 characters. See [Custom Agent node](/6.x/docs/platform-deep-dive/integrations/custom-agent-node).
* **Response caching:** POST REST endpoints, file-storage LIST and DOWNLOAD, and Mongo FIND, FIND\_ONE, and AGGREGATE operations are cacheable. Mutating operations are never cached. See [REST endpoint caching](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#rest-endpoint-caching).
* **Email triggers:** Email Trigger and Microsoft Outlook data sources filter attachments by file extension. Existing category selections are migrated automatically. See [Attachment handling](/6.x/docs/platform-deep-dive/integrations/email-trigger#attachment-handling).
* **Audit:** UI Flow runtime sessions are audited in more detail, including workflow runs, chat messages, and conversation reads. See [Audit](/6.x/docs/platform-deep-dive/core-extensions/audit).
* **Export and import:** exporting to an older platform version removes UI-template features the target cannot read. See [Cross-version export and import](/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition#cross-version-export-and-import).
* **UI Flows:** an expired session shows a session-expired screen with a start-fresh option.
* **Renderers:** enumeration lookups are batched into a single request.

[5.11.0 release notes](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026) · [5.11.0 deployment guidelines](/release-notes/v5.x/v5.11.0-august-2026/deployment-guidelines-v5.11)

**5.10.0**

July 2026

#### New

* **PostgreSQL data source:** connect a workflow to a PostgreSQL database and run SQL query operations from workflow nodes. See [PostgreSQL database](/6.x/docs/platform-deep-dive/integrations/postgresql-database).
* **SOAP data source:** import a WSDL from a URL or file, and call each operation from workflows with a SOAP Operation node. See [SOAP System](/6.x/docs/platform-deep-dive/integrations/soap-system).
* **FlowX Database:** MongoDB aggregation pipelines group, join, and reshape documents beyond a single query. See [Aggregation pipelines](/6.x/docs/platform-deep-dive/integrations/flowx-database#aggregation-pipelines).
* **Integration Designer:** the Tabular Data Extraction node reads a spreadsheet or CSV file into structured JSON, one object per row. See [Tabular Data Extraction node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#tabular-data-extraction-node).
* **Integration Designer:** the Template Filling node generates a PDF or DOCX document from a document template filled with workflow data. See [Template Filling node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node).
* **Integration Designer:** the Combine Files node merges PDFs in a given order, and the Split File node splits a PDF by page ranges or per page. See [Combine Files node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) and [Split File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node).
* **Documents plugin:** template-based generation can produce DOCX as well as PDF, set with `outputFormat`. See [Generating DOCX output](/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/generating-from-html-templates#generating-docx-output).
* **Knowledge Base:** a failed ingestion shows its status and reason, and **Retry** re-runs the last operation after cleaning up partial content. The Update Knowledge Base node gains a FAIL exit with per-operation rollback. See [Error handling and retry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#error-handling-and-retry).
* **File Download component:** end users download files directly from a rendered app. See [File download](/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download).
* **Global header and footer:** a UI Flow can define a header and footer shown on every page. See [Global header and footer](/6.x/docs/building-blocks/ui-designer/ui-component-types/root-components/global-header-footer).
* **Event handlers:** event handlers can fire on a condition. The **Save Local Variable** action saves the clicked collection row into local data under a key. See [Conditional triggers](/6.x/docs/building-blocks/ui-designer/event-handlers#conditional-triggers) and [Save Local Variable](/6.x/docs/building-blocks/ui-designer/event-handlers#save-local-variable).
* **Image component:** the Image component honors a color property. See [Image](/6.x/docs/building-blocks/ui-designer/ui-component-types/image).
* **Data source testing:** the database query testing modals have a **Documents** tab, and multi-record operations report an affected-record count. See [Testing data sources](/6.x/docs/platform-deep-dive/integrations/testing-data-sources).
* **Mistral provider:** add Mistral with your own API key under **Organization Settings** → **AI Settings** → **Model Providers**, then assign its models per capability. See [AI providers](/6.x/ai-platform/ai-providers).

#### Changed

* **Documents:** the **Document Type** field is renamed **Document Tag**. Behavior is unchanged.

[5.10.0 release notes](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026) · [5.10.0 deployment guidelines](/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10)


# Deployment guidelines v6.0.0
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0

Component versions, Kafka topics, environment variables, and Helm chart changes for FlowX.AI 6.0.0, with the steps a self-hosted upgrade needs.

> [!NOTE]
>
> After upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer → Platform Status**.

## Upgrade overview

FlowX.AI 6.0 is a feature release. On SaaS, FlowX applies every change on this page. Self-hosted deployments usually follow LTS releases and receive these changes with the next LTS release family. If you upgrade a self-hosted installation to 6.0.0, apply the changes below in the order given in [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

### Before you upgrade a self-hosted installation

* Set every AI service group flag explicitly. See [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart).
* Deploy designer-user, the new `core` service. harness and ui-driver (`devtime`) and dynamic-classifier (`runtime`) deploy only if you turn their group on. See [New services](#new-services).
* Create the new database users and secrets for the services you deploy. Every installation needs the four new keys in `keycloak-flowx-realm-clients`. See [New databases and secrets](#new-databases-and-secrets).
* Give process-engine read access to the integration-designer bucket. See [New databases and secrets](#new-databases-and-secrets).
* If you turn on dynamic-classifier, set its bucket name and provide its 20Gi volume. See [Update your values](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart#update-your-values).
* If you route with Kubernetes Ingress, move callers off the admin Ingress routes that the chart no longer creates. See [New databases and secrets](#new-databases-and-secrets).
* Create the new Kafka topics. If your cluster uses ACLs, also give the new clients of three existing topics access. See [New Kafka topics](#new-kafka-topics).
* Let audit-core reach Redis. It now uses Redis only to choose which replica runs its nightly cleanup job, not as a cache, and the chart connects it to the same Redis server as the other services. If you restrict which services can reach Redis, add audit-core. See [Configuring Redis](/6.x/setup-guides/audit-setup-guide#configuring-redis).
* Set the personal-data encryption master key on integration-designer. See [Personal-data encryption master key](#new-required-secret-personal-data-encryption-master-key).
* Choose how Elasticsearch replicates new indices. See [Elasticsearch replica auto-expansion](#changed-default-elasticsearch-replica-auto-expansion).
* Add the MongoDB hosts on your private network that data sources use to `FLOWX_SSRFALLOWEDHOSTS`. See [nosql-db-runner host restrictions](#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).
* Trust the certificates of the IMAP servers your email triggers read from. See [IMAPS certificate verification](#changed-default-imaps-certificate-verification-in-email-gateway).

Upgrading from 5.9.5 or earlier? Two changes from 5.9.6 also apply. See [Upgrading from an older patch release](#upgrading-from-an-older-patch-release).

## Component versions

The versions below are the component versions that make up FlowX.AI 6.0.0, next to FlowX.AI 5.9.6, the latest 5.9.x release a self-hosted installation upgrades from. A dash marks a component that is new since 5.9.6. On SaaS, FlowX manages these versions.

### Core components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **admin** | 11.132.0 | 10.152.14 |
| **advancing-controller** | 11.86.0 | 10.98.12 |
| **application-manager** | 11.143.0 | 10.159.3 |
| **audit-core** | 11.92.0 | 10.102.11 |
| **authorization-system** | 11.102.0 | 10.122.13 |
| **cms-core** | 11.114.0 | 10.113.13 |
| **data-search** | 11.87.0 | 10.92.11 |
| **data-sync** | 11.94.0 | 10.107.13 |
| **designer** | 11.252.0 | 10.285.4 |
| **designer-user** | 11.31.0 | - |
| **document-plugin** | 11.122.0 | 10.124.13 |
| **email-gateway** | 11.110.0 | 10.102.1 |
| **events-gateway** | 11.93.0 | 10.101.1 |
| **file-gateway** | 11.105.0 | 10.33.14 |
| **integration-designer** | 11.158.0 | 10.201.2 |
| **license** | 11.94.0 | 10.87.12 |
| **nosql-db-runner** | 11.98.0 | 10.101.13 |
| **notification-plugin** | 11.113.0 | 10.111.1 |
| **organization-manager** | 11.101.0 | 10.98.12 |
| **process-engine** | 11.137.1 | 10.174.17 |
| **runtime-manager** | 11.143.0 | 10.159.3 |
| **scheduler-core** | 11.89.0 | 10.94.11 |
| **task-management-plugin** | 11.109.0 | 10.112.12 |
| **webhook-gateway** | 11.102.0 | 10.69.12 |

### AI base components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-gateway** | 11.118.1 | 10.35.13 |
| **embedder** | 11.7.0 | 10.11.2 |
| **knowledgebase-indexer-v2** | 11.7.0 | 10.11.2 |
| **knowledgebase-rag** | 11.7.0 | 10.11.2 |
| **doc-parser** | 11.7.0 | 10.11.2 |

### AI dev-time components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **ai-analyst** | 11.7.0 | 10.11.2 |
| **ai-architect** | 11.7.0 | 10.11.2 |
| **ai-assistant** | 11.7.0 | 10.11.2 |
| **ai-designer** | 11.7.0 | 10.11.2 |
| **ai-developer** | 11.7.0 | 10.11.2 |
| **harness** | 11.7.0 | - |
| **kb-enrichment** | 11.7.0 | 10.11.2 |
| **planner** | 11.7.0 | 10.11.2 |
| **ui-driver** | 11.252.0 | - |

### AI runtime components

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **agent-builder** | 11.7.0 | 10.11.2 |
| **cee-pii** | 11.7.0 | - |
| **data-privacy** | 11.7.0 | 10.11.2 |
| **doc-converter** | 11.7.0 | 10.11.2 |
| **dynamic-classifier** | 11.7.0 | - |
| **evals-judge** | 11.7.0 | 10.11.2 |
| **speech-to-text** | 11.7.0 | 10.11.2 |
| **web-crawler** | 11.7.0 | 10.11.2 |

### AI extensions

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **modpod** | 11.0.1 | 10.0.7 |
| **observatory-api** | 11.29.4 | 10.7.2 |
| **observatory-platform** | 11.29.4 | 10.7.2 |
| **observatory-web** | 11.29.4 | 10.7.2 |

In FlowX.AI 6.0, the Observatory components run on environments operated by FlowX. They aren't included in client deployments in this release.

### Embedded components

* **SpiceDB:** see the [5.9.0 deployment guidelines](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9) for details.
* **Qdrant** (vector database): bundled in the `flowx-ai` Helm chart and deployed with the AI base group (see [AI service groups in the Helm chart](#ai-service-groups-in-the-helm-chart)). Its version is managed by the chart and not pinned here. See the [Qdrant setup guide](/6.x/setup-guides/qdrant) for deployment and configuration.

### Renderers

The web SDKs ship at the **designer** version (`11.252.0` for FlowX.AI 6.0.0). The native iOS and Android renderers version independently.

| Component | 6.0.0 | 5.9.6 |
| - | - | - |
| **@flowx/angular-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/angular-theme** | 11.252.0 | 10.285.4 |
| **@flowx/angular-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-theme** | 11.252.0 | 10.285.4 |
| **@flowx/react-native-ui-toolkit** | 11.252.0 | 10.285.4 |
| **@flowx/core-sdk** | 11.252.0 | 10.285.4 |
| **@flowx/core-theme** | 11.252.0 | 10.285.4 |
| **solution-portal** | 11.252.0 | 10.285.4 |
| **iOS renderer** | 11.6.0 | 10.9.2 |
| **Android renderer** | 11.18.0 | 10.10.2 |

The **solution-portal** container app tracks the designer version.

***

## Configuration changes

This section compares environment variables, Kafka topics, and the `flowx-ai` Helm chart with FlowX.AI 5.9.6. It includes the changes that reached SaaS in 5.10 to 5.13, so a self-hosted upgrade from 5.9.6 needs only this page.

### New Kafka topics

Compared with 5.9.6, create these 42 topics. Create all of them, whatever your group flags: topics for services you don't deploy stay unused. On SaaS they are created and managed automatically.

**AI nodes as durable jobs:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.agent-node.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.progress.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.agent-node.job.cancel.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.agent-node.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Deep research node:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.ai-platform.deep-research.job.request.v1` | integration-designer → agent-builder |
| `ai.flowx.ai-platform.deep-research.job.response.v1` | agent-builder → integration-designer |
| `ai.flowx.ai-platform.deep-research.job.dlq.v1` | agent-builder → none (dead-letter topic) |

**Validation findings:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.application-version.validation-findings.request-admin.v1` | application-manager → admin |
| `ai.flowx.application-version.validation-findings.request-cms.v1` | application-manager → cms-core |
| `ai.flowx.application-version.validation-findings.request-document-plugin.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.validation-findings.request-integration.v1` | application-manager → integration-designer |
| `ai.flowx.application-version.validation-findings.request-notification-plugin.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.validation-findings.request-application-manager.v1` | application-manager → application-manager |
| `ai.flowx.application-version.validation-findings.response.v1` | admin, cms-core, document-plugin, integration-designer, notification-plugin → application-manager |
| `ai.flowx.application-version.validation-findings.job-completed.v1` | application-manager → harness |

**Structured template data model:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.plugin.template-data-model.migration.v1` | admin → document-plugin, notification-plugin |
| `ai.flowx.application-version.sync.document-template.in.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.sync.notification-template.in.v1` | application-manager → notification-plugin |
| `ai.flowx.application-version.correction-after-app-operation.document-template.request.v1` | application-manager → document-plugin |
| `ai.flowx.application-version.correction-after-app-operation.notification-template.request.v1` | application-manager → notification-plugin |

**Runtime content import and export:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.runtime-content.task.request.v1` | application-manager → integration-designer |
| `ai.flowx.runtime-content.task.response.v1` | integration-designer → application-manager |
| `ai.flowx.ai-platform.knowledgebase.job.request.v1` | integration-designer → embedder |
| `ai.flowx.ai-platform.knowledgebase.job.response.v1` | embedder → integration-designer |

**Document classification and extraction:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.dynamic-classifier.job.request.v1` | integration-designer → dynamic-classifier |
| `ai.flowx.dynamic-classifier.job.response.v1` | dynamic-classifier → integration-designer |
| `ai.flowx.dynamic-classifier.job.dlq.v1` | dynamic-classifier → none (dead-letter topic) |
| `ai.flowx.plugin.document.trigger.ml-archive-extract.v1` | integration-designer → document-plugin |
| `ai.flowx.plugin.document.ml-archive-extract.results.v1` | document-plugin → integration-designer |
| `ai.flowx.ai-platform.doc-parser.job.response.ml.v1` | doc-parser → integration-designer |

**Event-triggered workflows:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.trigger-subscription-change.in.v1` | admin, integration-designer → application-manager |
| `ai.flowx.core.trigger.start-for-event.workflow.v1` | email-gateway, webhook-gateway → integration-designer |

**Workflow schedules:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.build.workflow-schedules.updates.in.v1` | integration-designer → runtime-manager |
| `ai.flowx.core.notify.timer-event-schedule.state.v1` | scheduler-core → runtime-manager |

**Bulk instance migration and move token:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.trigger.instance-migration.batch.v1` | process-engine → process-engine |
| `ai.flowx.core.trigger.token-move.batch.v1` | process-engine → process-engine |

**Run auditing:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.core.run.segment.v1` | process-engine, integration-designer → audit-core |
| `ai.flowx.core.runtime.failure.v1` | process-engine, integration-designer → audit-core |

**Designer notifications and preferences:**

| Topic | Producer → Consumer |
| - | - |
| `ai.flowx.designer-user.notifications.v1` | application-manager, process-engine → designer-user |
| `ai.flowx.eventsgateway.user.notifications.v1` | designer-user → events-gateway |
| `ai.flowx.designer-user.user-preferences.v1` | designer-user → designer-user |

> [!NOTE]
>
> If your Kafka cluster uses ACLs, also give the new clients of these existing topics access:
>
> * `ai.flowx.application-version.sync.out.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.correction-after-app-operation.response.v1`: document-plugin and notification-plugin
> * `ai.flowx.application-version.resources-usages.sub-res-validation.response.v1`: document-plugin

### New services

Compared with 5.9.6, the `flowx-ai` Helm chart adds four services. On SaaS they are provisioned and managed by FlowX.

| Service | Group | What it does | Dependencies |
| - | - | - | - |
| designer-user | `core` | Stores Designer user preferences, such as the last-used workspace, and delivers Designer notifications | MongoDB, Redis, Kafka |
| harness | `devtime` | Runs the Developer Agentic Harness | PostgreSQL, Redis, Kafka |
| ui-driver | `devtime` | Renders UI flows in the background for the Developer Agentic Harness | None |
| dynamic-classifier | `runtime` | Classifies documents with trained models | PostgreSQL, a persistent volume, Kafka |

The databases, secrets, and volume are in [New databases and secrets](#new-databases-and-secrets).

The harness reuses the platform's existing Redis, so nothing new is provisioned. It uses Redis to stream a running turn to every open Designer session and to cancel a turn from any harness pod. Without Redis, turns still run, but live progress and cancellation across pods don't work.

The harness also consumes the existing `ai.flowx.llm.config.changed.v1` topic, so a change to an organization's AI model settings reaches it right away. Without Kafka, it picks up the change when its cache expires.

### AI service groups in the Helm chart

The `flowx-ai` Helm chart groups the services into four groups. Each group has its own flag, `groups.<group>.enabled`:

| Group | Services |
| - | - |
| `core` | Core platform services |
| `base` | The AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and the bundled Qdrant |
| `devtime` | ai-analyst, ai-architect, ai-assistant, ai-designer, ai-developer, harness, kb-enrichment, planner, ui-driver |
| `runtime` | agent-builder, data-privacy, doc-converter, dynamic-classifier, evals-judge, speech-to-text, web-crawler. cee-pii is in this group but needs `services.cee-pii.enabled: true` as well |

The groups are the same as in 5.9.6. The 6.0.0 chart adds designer-user to `core`, harness and ui-driver to `devtime`, and cee-pii and dynamic-classifier to `runtime`. The `base` group is unchanged.

Set all four flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

> [!WARNING]
>
> **Set every group flag explicitly for self-hosted upgrades.** Don't rely on the chart's group defaults. The `devtime` and `runtime` services call the AI base services, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

### New databases and secrets

Compared with the `flowx-ai` Helm chart in 5.9.6, these services need new databases. Create a database only if its service's group is on. designer-user is in `core`, so every installation needs its database:

| Service | Group | Database user | Secret |
| - | - | - | - |
| agent-builder | `runtime` | PostgreSQL `agent_builder` | `flowx-postgres-agent-builder` |
| dynamic-classifier | `runtime` | PostgreSQL `dynamic_classifier` | `flowx-postgres-dynamic-classifier` |
| harness | `devtime` | PostgreSQL `harness` | `flowx-postgres-harness` |
| designer-user | `core` | MongoDB `designer-user` | `mongodb-designer-user-designer-user` |

Each database has the same name as its user. Each secret holds the user's password under the key `password`.

The webhook-gateway also connects to the existing `app-runtime` MongoDB database with the `app-runtime` user.

The `keycloak-flowx-realm-clients` secret needs four new keys, one for each new service account:

| Secret key | Keycloak client |
| - | - |
| `KEYCLOAK_DESIGNER_USER_CLIENT_SECRET` | `flowx-designer-user-sa` |
| `KEYCLOAK_AI_HARNESS_CLIENT_SECRET` | `flowx-ai-harness-sa` |
| `KEYCLOAK_NOTIFICATION_PLUGIN_CLIENT_SECRET` | `flowx-notification-plugin-sa` |
| `KEYCLOAK_DOCUMENT_PLUGIN_CLIENT_SECRET` | `flowx-document-plugin-sa` |

Other chart changes:

* **process-engine** needs read-only access (`s3:GetObject`) to the integration-designer bucket, to download the Kafka payloads that integration-designer stores there. The chart reads the access key ID from `global.flowx.s3.credentials.processEngine.accessKey` (default `flowx-process-engine-accesskey`) and the secret access key from the `flowx-process-engine-s3` secret, key `SecretAccessKey`.
* **dynamic-classifier** stores its data on a 20Gi `ReadWriteOnce` persistent volume claim, `dynamic-classifier-data`, and uses the `Recreate` deployment strategy, so an upgrade stops the old pod before the new one starts.
* **dynamic-classifier** reads an OpenAI API key for its LLM judge from the `dynamic-classifier-openai` secret, key `OPENAI_API_KEY`. The secret is optional: without it, the pod still starts and classification keeps working.
* The chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier. ai-gateway keeps its own.

### New required secret: personal-data encryption master key

The Mask Personal Data and Restore Personal Data nodes encrypt the placeholder map they keep during a workflow run. The key material comes from a new integration-designer variable with **no default**: without it, the mask and restore nodes fail rather than encrypt personal data with a published value. On SaaS this secret is provisioned and managed by FlowX.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_PII_ENCRYPTION_MASTER_KEY` | Master secret the mask and restore nodes derive their encryption key from. Any non-empty string; use a strong random value and store it as a secret. Must be identical across all pods and stable over time: changing it invalidates every in-flight placeholder map | none (required) |
| `FLOWX_PII_ENCRYPTION_KEY_ID` | Label recorded on new placeholder-map entries so a future migration can support key rotation. Only the configured key is held today | `k1` |
| `FLOWX_PII_MAP_TTL` | How long a masked value stays restorable. Bounds exposure when a run ends without reaching the instance-end cleanup hooks; enforced by a MongoDB TTL index | `PT24H` |

### New object storage bucket: runtime content

Runtime content export and import stores its files in a new shared bucket, `runtime-content-bucket`. Application Manager creates the bucket on first use, Integration Designer writes export files and reads imports there, and the embedder reads and writes Knowledge Base vectors at the paths each request names. Grant all three services access to the bucket.

Browsers upload import files and download export files directly, through presigned URLs that Application Manager signs. By default it signs them with the internal storage endpoint, which only pods can reach, so set `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` to a storage endpoint that browsers can reach.

New variables on application-manager and integration-designer. Set the bucket on both, and the presign settings on application-manager only:

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_FILESTORAGE_S3_RUNTIMECONTENTBUCKET` | Bucket for runtime content export and import files | `runtime-content-bucket` |
| `APPLICATION_FILESTORAGE_S3_PRESIGNSERVERURL` | Storage endpoint used to sign the presigned upload and download URLs. Leave empty to sign with the internal storage endpoint | empty |
| `APPLICATION_FILESTORAGE_S3_PRESIGNREGION` | Region used to sign the presigned URLs | `us-east-1` |

For the full list of buckets, see [Data architecture](/6.x/docs/platform-overview/data-architecture#s3-compatible-object-storage-buckets).

### Changed default: Elasticsearch replica auto-expansion

New process instance indices and new audit log indices now use the Elasticsearch `auto_expand_replicas` setting, with a default of `0-1`. Elasticsearch keeps 0 replicas when the cluster has one data node and 1 replica when it has two or more, and adjusts the count as nodes join or leave. On SaaS, Elasticsearch is managed by FlowX.

New process-engine and audit-core variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS` | Replica range that Elasticsearch applies to new indices. Set to `false` to use the fixed `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` value instead | `0-1` |

* **Overrides the fixed replica count:** while auto-expansion is on, `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` has no effect on new indices.
* **New indices only:** the setting applies to the `process_instance` index and index template and to the audit logs data stream template. Existing indices keep their current settings.
* **Disk usage:** on clusters with two or more data nodes, the replica roughly doubles the disk space these indices use.

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** A deployment that pins a fixed replica count, for example `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS=3`, loses it on new indices unless it also sets `FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS=false`. On multi-node clusters, check free disk space before upgrading.

To apply auto-expansion to indices created before the upgrade, update their settings once:

```http theme={"dark"}
PUT process_instance*,.ds-audit-logs*/_settings
{"index": {"auto_expand_replicas": "0-1"}}
```

### Changed behavior: nosql-db-runner host restrictions cover MongoDB

The host restriction that relational data sources already had now applies to external MongoDB connections too. The nosql-db-runner checks every address a MongoDB host resolves to, including replica-set members and SRV targets, and rejects the connection if any of them is private. For FlowX Database and Unmanaged MongoDB data sources alike, it also rejects `UPDATE`, `UPDATE_MANY`, `DELETE`, and `DELETE_MANY` operations with a missing or empty filter. To match every document, pass `{"_id": {"$exists": true}}`.

nosql-db-runner variables (both already existed for relational data sources):

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SSRFALLOWEDHOSTS` | Hosts or CIDR blocks, separated by commas, that may connect even though they resolve to a private address. Addresses on the local machine or in a link-local range stay blocked | empty |
| `FLOWX_SSRFPROTECTIONENABLED` | Turns the host restriction on or off | `true` |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS`.

### Changed behavior: name placeholders in data-privacy

When data-privacy masks a person's name, the placeholder now carries the gender, for example `<NAME_F_1>` or `<NAME_M_1>`. When the name doesn't show the gender, the placeholder stays `<NAME_1>`. Prompts or scripts that match the old placeholder form need updating.

### Changed behavior: Workspace operations editor role replaced

The upgrade replaces the Workspace operations editor role with the [Workspace corrective actions editor](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix) role. Users and groups that had the old role get the new one automatically and keep access to process instance migration and move token. No action is needed.

### New environment variables: audit index retention

The Audit service can now delete old audit data and roll over by shard size. Both settings are off by default, so the Audit service doesn't delete data unless you set a retention period.

New audit-core variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, such as `50gb` | Not set: roll over by age only |

> [!WARNING]
>
> When you first set `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS`, the Audit service also deletes backing indices that rolled over more than that many days ago. See [Configuring Elasticsearch](/6.x/setup-guides/audit-setup-guide#configuring-elasticsearch).

### Changed default: IMAPS certificate verification in email-gateway

The email-gateway now verifies the certificate of every IMAPS server it connects to. A server must present a certificate signed by a trusted authority and matching its host name.

New email-gateway variable:

| Environment Variable | Description | Default Value |
| - | - | - |
| `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS` | Mail hosts that skip certificate verification, separated by spaces or commas. Use `*` to skip it for every host | empty |

> [!WARNING]
>
> **Breaking change for self-hosted upgrades.** Email triggers that read from an IMAP server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`.

### Changed default: AI node retry

AI nodes without retry settings of their own now retry when a dependency is temporarily unavailable, such as an LLM provider outage, a rate limit, or a lost connection. Permanent errors aren't retried, and deep research nodes never retry by default. A node's own retry settings replace the default.

New integration-designer variables:

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_ENABLED` | Turns the default retry for AI nodes on or off | `true` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_MAXATTEMPTS` | Maximum retry attempts | `10` |
| `FLOWX_WORKFLOW_AINODEDEFAULTRETRY_BACKOFFPERIOD` | Wait between attempts, as an ISO-8601 duration | `PT30S` |

### Upgrading from an older patch release

Upgrading from 5.9.5 or earlier? Apply the [5.9.6 deployment guidelines](/release-notes/v5.x/v5.9.6-october-2026/deployment-guidelines-v5.9.6#build-redeployment-retries) as well. Two 5.9.6 changes affect the upgrade:

* **Build redeployment retries:** the queue of build deployments waiting for a retry moved from Redis to the application-manager PostgreSQL database, with a new topic, `ai.flowx.build.deployment-failed.v1`. Deployments waiting for a retry in Redis when you upgrade aren't moved to the new queue. Re-publish those builds after the upgrade.
* **advancing-controller management port:** `MANAGEMENT_SECURITY_ENABLED` is no longer read. Actuator endpoints on the management port, including Prometheus, answer without authentication.

> [!WARNING]
>
> Keep the advancing-controller management port, `8081`, off any public ingress.

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](/release-notes/overview).


# Android SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/android

Migrate the FlowX Android renderer SDK from 5.9.x to 6.0.0.

## Android SDK migration guide

FlowX.AI 6.0 moves the Android SDK to `compileSdk` 37, Android Gradle plugin 9 and Kotlin 2.4, and aligns the SDK's names with the iOS and web SDKs. Update your build setup first, then the renamed SDK APIs.

### System requirements

* **minSdk = 26** (unchanged)
* **compileSdk = 37**

The SDK library was built using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 9.5.0**
* **[Gradle](https://gradle.org/releases/) 9.8.2**
* **[Kotlin](https://kotlinlang.org/) 2.4.21**

Your container app must build with at least:

* **Android Gradle Plugin 9.1.0**
* **Gradle 9.3.1** (the minimum depends on your Android Gradle Plugin version)
* **Kotlin 2.4**
* **JDK 17**

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Android Core KTX](https://developer.android.com/kotlin/ktx#core) | 1.16.0 | **1.19.1** |
| [Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) | 1.10.1 | **1.13.0** |
| [Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) | 2025.09.01 | **2026.09.00** |
| [Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) | 2.9.1 | **2.10.2** |
| [Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) | 2.9.1 | **2.11.0** |
| [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | 1.10.2 | **1.11.0** |
| [Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) | 1.1.7 | **1.3.0** |
| [Android Security](https://developer.android.com/jetpack/androidx/releases/security) | 1.1.0-beta01 | **1.1.0** |
| [OkHttp BOM](https://square.github.io/okhttp/) | 4.12.0 | **5.5.1** |
| [Retrofit](https://square.github.io/retrofit/) | 2.12.0 | **3.0.0** |
| [Coil BOM](https://coil-kt.github.io/coil/) | 3.4.0 | **3.6.3** |
| [Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) | 4.31.1 | **4.36.2** |
| [Mozilla Rhino](https://github.com/mozilla/rhino) | 1.8.0 | **1.9.2** |
| [Accompanist Permissions](https://google.github.io/accompanist/permissions/) | 0.37.3 | 0.37.3 |
| [Moshi](https://github.com/square/moshi) | 1.15.2 | 1.15.2 |
| [Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) | 2.1.5 | 2.1.5 |

> [!WARNING]
>
> The SDK now depends on **OkHttp 5** and **Retrofit 3**. Gradle resolves your app to these versions even if you declare OkHttp 4 or Retrofit 2, so update any code in your app that uses APIs removed in these major versions. Align your app's versions of these libraries with the SDK's versions to avoid compatibility issues.

### Migration steps

To build and run your container app with the 6.0 SDK, follow these steps in order:

**1. Update the SDK version**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
implementation("ai.flowx.android:sdk:<5.9.x version>") // [!code --]
implementation("ai.flowx.android:sdk:<6.0 version>") // [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Increase the `compileSdk` version to `37`**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileSdk = 35 // [!code --]
    compileSdk = 37 // [!code ++]
}
```

> [!NOTE]
>
> The SDK and its AndroidX, OkHttp and Coil dependencies require `compileSdk` 37. Raising `targetSdk` is not required.

**3. Update the `Android Gradle plugin` version to at least `9.1.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "8.10.0" apply false // [!code --]
    id("com.android.application") version "9.5.0" apply false // [!code ++]
}
```

> [!TIP]
>
> Android Gradle plugin 9 is a major release with breaking build changes. Consult the [Android Gradle plugin 9.0 release notes](https://developer.android.com/build/releases/agp-9-0-0-release-notes).

**4. Update the `Gradle` version**

```properties [rootProject]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.2-bin.zip # [!code ++]
```

> [!NOTE]
>
> Android Gradle plugin 9.1 requires at least Gradle 9.3.1, and 9.5 requires at least Gradle 9.6.0. Check the minimum for your version in the [Android Gradle plugin release notes](https://developer.android.com/build/releases/gradle-plugin).

**5. Remove the `Kotlin Android` plugin**

Android Gradle plugin 9 compiles Kotlin by itself (built-in Kotlin), so the `org.jetbrains.kotlin.android` plugin must be removed:

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code --]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") // [!code --]
}
```

> [!TIP]
>
> Consult the [Migrate to built-in Kotlin](https://developer.android.com/build/migrate-to-built-in-kotlin) guide.

**6. Update the `Kotlin` version to at least `2.4`**

With built-in Kotlin, your app compiles with the version of the Kotlin Gradle plugins you declare, such as the Compose Compiler plugin. The Kotlin version that Android Gradle plugin uses by default is too old to read the SDK's classes. Use the same version for every Kotlin Gradle plugin your project declares, such as Parcelize or Serialization.

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code --]
    id("org.jetbrains.kotlin.plugin.compose") version "2.4.21" apply false // [!code ++]
}
```

> [!WARNING]
>
> With an older Kotlin version, the build fails with an error like: `The binary version of its metadata is 2.4.0, expected version is 2.2.0`.

**7. Make sure core library desugaring is enabled**

The SDK requires core library desugaring. If your app does not enable it yet, add:

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**8. Rename the `imageBaseUrl` and `customHeaders` properties of the `Config` interface**

`imageBaseUrl` is now `assetsBaseUrl`, and `customHeaders` is now `additionalHttpHeaders`:

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
Flowx.getInstance().init(
    context = applicationContext,
    config = object : Config {
        ...
        override val imageBaseUrl = "URL to FlowX CMS Media Library" // [!code --]
        override val assetsBaseUrl = "URL to FlowX CMS Media Library" // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code --]
        override val additionalHttpHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // [!code ++]
        ...
    },
    ...
)
```

> [!NOTE]
>
> The default value of the `locale` property changed from `Locale.getDefault()` to `Locale.forLanguageTag("en-US")`. If your app relies on the device locale for date, number and currency formatting, set it explicitly:
>
> ```kotlin theme={"dark"}
> override val locale: Locale = Locale.getDefault()
> ```

**9. Stop passing `null` to the `setAccessToken` method**

The `setAccessToken` method no longer accepts `null`:

```kotlin theme={"dark"}
fun setAccessToken(accessToken: String?) // [!code --]
fun setAccessToken(accessToken: String) // [!code ++]
```

Remove the calls that clear the token (for example, on logout or after a failed login):

```kotlin theme={"dark"}
Flowx.getInstance().setAccessToken(null) // [!code --]
```

A token can't be cleared once set. When another user logs in, set that user's token. If no token is ever set, the SDK runs in anonymous mode. For details, see the [Authentication](/6.x/sdks/android-renderer#authentication) section of the Android SDK reference.
\[!WARNING] Passing an empty string (`""`) no longer clears the token. The SDK sends it as is and the backend rejects the requests.

**10. Rename the `closeModalFunc` parameter to `onDismissRequested`**

The parameter of the `startProcess` and `continueProcess` methods was renamed. Its lambda now runs in the `ProjectScope` context:

```kotlin theme={"dark"}
Flowx.getInstance().startProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)

Flowx.getInstance().continueProcess(
    ...
    closeModalFunc = { processName -> ... }, // [!code --]
    onDismissRequested = { processName -> ... }, // [!code ++]
)
```

> [!TIP]
>
> Replace the deprecated `CloseModalProcessScope` type with `ProjectScope`, as described in the [Replace deprecated APIs](#replace-deprecated-apis) section.

**11. Rename the `imageBaseUrl` parameter of the `changeEnvironment` method (if used)**

```kotlin theme={"dark"}
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code --]
fun changeEnvironment(baseUrl: String, assetsBaseUrl: String, enginePath: String) // [!code ++]
```

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. The parameters are unchanged:

| Deprecated (5.9) | Replacement (6.0) | Available on |
| - | - | - |
| `CloseModalProcessScope` | `ProjectScope` | The `onDismissRequested` lambda of `startProcess` and `continueProcess` |
| `replaceSubstitutionTag` | `getSubstitutionTagContent` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getMediaResourceUrl` | `getMediaItemUrl` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `getEnumeration` | `getEnumerationItems` | `ProjectScope`, `CustomComponentScope`, `CustomLoaderScope` |
| `executeAction` | `runAction` | `CustomComponentScope` |
| `executeUploadAction` | `runUploadAction` | `CustomComponentScope` |
| `configureUpdateState` | `setUpdateStateEnabled` | `Flowx` |

> [!TIP]
>
> Android Studio offers a **Replace with** quick fix on every deprecated call.

These changes are reflected in an actual implementation as shown below:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope // [!code --]
import ai.flowx.android.sdk.api.ProjectScope // [!code ++]

// close process confirmation alert
@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code --]
private fun ProjectScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) { // [!code ++]
    ...
    Text(replaceSubstitutionTag("@@close_message")) // [!code --]
    Text(getSubstitutionTagContent("@@close_message")) // [!code ++]
}

// custom component
flowxScope.executeAction(action = it, params = JSONObject()) // [!code --]
flowxScope.runAction(action = it, params = JSONObject()) // [!code ++]

// custom loader
flowxScope.replaceSubstitutionTag(text) // [!code --]
flowxScope.getSubstitutionTagContent(text) // [!code ++]
flowxScope.getMediaResourceUrl(key) // [!code --]
flowxScope.getMediaItemUrl(key) // [!code ++]
```

## Related resources

> [card] [Android SDK reference](/6.x/sdks/android-renderer)
>
> Android renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Angular SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/angular

Migrate the FlowX Angular renderer SDK from 5.9.x to 6.0.0.

## Angular SDK migration guide

6.0 moves the Angular renderer to Angular 22 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new input and function names. The framework upgrade, the custom component input, and the removed `logSink` and `logCategories` inputs need code changes.

### Framework upgrade: Angular 21 → 22

Upgrade your host app **before** you bump the FlowX SDK. Follow the official [Angular update guide](https://angular.dev/update-guide) from `21.0` to `22.0`.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Angular CLI and `@angular/*` | \~21 | **\~22** |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |
| TypeScript | ≥ 5.9, \< 6.1 | **≥ 6.0, \< 6.1** |

The FlowX Angular packages declare `@angular/*` ≥ 22.0.0 as peer dependencies, so `npm install` fails on an Angular 21 app.

### FlowX SDK changes

#### Renamed inputs and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` input | `baseUrl` |
| `processApiPath` input | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` input | `assetsBaseUrl` |
| `authToken` input | `accessToken` |
| `withConfig({ customLoader })` | `customLoaderProvider` (same shape) |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers.

```diff theme={"dark"}
 <flx-process-renderer
-  [apiUrl]="baseUrl"
-  [processApiPath]="'onboarding'"
-  [staticAssetsPath]="mediaLibraryUrl"
-  [authToken]="token"
+  [baseUrl]="baseUrl"
+  [enginePath]="'onboarding'"
+  [assetsBaseUrl]="mediaLibraryUrl"
+  [accessToken]="token"
   ...
 />
```

#### Custom components: `data$` → `input` signal

Custom components receive their data through an `input` signal input instead of the `data$` Observable. The process data moves under `input().data`, and actions run through `runAction` and the new `runUploadAction`. Both return an Observable.

| 5.9 | 6.0 |
| - | - |
| `data$` input (Observable) | `input` signal input |
| Data fields read from the top level (`data.<field>`) | `input().data.<field>` |
| `data.actionsFn.<name>(params)` | `input().runAction(name, params?)` |
| None | `input().runUploadAction(name, file, params?)` |

```typescript theme={"dark"}
import { Component, computed, input } from '@angular/core';
import { FlxCustomComponentData } from '@flowx/angular-sdk';

@Component({
  selector: 'my-custom-component',
  templateUrl: './custom-component.component.html',
})
export class CustomComponentComponent {
  input = input<FlxCustomComponentData>()
  client = computed(() => this.input()?.data.client)

  submit(file: Blob) {
    this.input()?.runAction('action_one', { amount: 3 }).subscribe();
    this.input()?.runUploadAction('upload_document', file, { side: 'front' }).subscribe();
  }
}
```

#### `logSink` and `logCategories` inputs removed

The `[logSink]` and `[logCategories]` inputs on `<flx-process-renderer>` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- [logSink]="formattedLogger"
- [logCategories]="['rest', 'sse']"
```

```typescript theme={"dark"}
import { formattedLogger, logSink } from '@flowx/core-sdk';

const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] });
```

`@flowx/angular-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Inputs removed or deprecated without replacement

| Input | Status in 6.0 |
| - | - |
| `legacyHttpVersion` | Deprecated, no replacement. Still honored. |
| `debugLogs` | Removed. It never had any effect. Use `logSink()` from `@flowx/core-sdk`. |

#### Behavior changes

* `baseUrl` is required on the process, UI Flow, chat and task management renderers, and `assetsBaseUrl` on the process, UI Flow and chat renderers. Without them, the renderer throws ``[FlowX] `baseUrl` is required.`` (or `` `assetsBaseUrl` ``) at start. The template compiler doesn't report a missing value.
* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [Angular SDK reference](/6.x/sdks/angular-renderer)
>
> Angular renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Helm chart
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/helm-chart

Upgrade a FlowX.AI installation on the flowx-ai Helm chart from 5.9.x to 6.0.0.

> [!NOTE]
>
> FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

This page covers the Helm side of an upgrade from FlowX.AI 5.9.x to 6.0.0 for an installation that already runs on the `flowx-ai` Helm chart. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list every change in detail. This page puts the ones that need action in the order you do them.

> [!NOTE]
>
> If you still run the per-service charts or the `ai-platform` umbrella chart, move to the `flowx-ai` chart on 5.9.x first, as described in [Migrate self-hosted FlowX.AI to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart). That migration recreates every workload. Doing it separately keeps the 6.0.0 upgrade a single `helm upgrade` of one release.

## Before you begin

* Read the [FlowX.AI 6.0.0 release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) and [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0).
* Get pull access to the `flowx-ai` chart at the chart version for 6.0.0. The chart version is the platform release.
* Take a backup of PostgreSQL, MongoDB, the object store, and the Qdrant collections right before the upgrade.
* If you run a container app with a FlowX renderer SDK, plan its upgrade with the [renderer SDK guides](./migration-overview#renderer-sdk-migration).

The commands on this page read the namespace from `NS`:

```bash theme={"dark"}
export NS={your-flowx-namespace}
```

## Update your values

**1. Set every group flag explicitly**

Don't rely on the chart's group defaults. Set all four group flags in your values. `core` is `true` in every combination:

| To install | `base` | `devtime` | `runtime` |
| - | - | - | - |
| Core services only | `false` | `false` | `false` |
| Core, base, and devtime services | `true` | `true` | `false` |
| Core, base, and runtime services | `true` | `false` | `true` |
| All services | `true` | `true` | `true` |

`base` is the AI base: ai-gateway, doc-parser, embedder, knowledgebase-indexer-v2, knowledgebase-rag, and Qdrant. The `devtime` and `runtime` services call it, so turn `base` on whenever either of them is on. The chart doesn't check this for you.

For example, to install the core, base, and runtime services:

```yaml theme={"dark"}
groups:
  core:
    enabled: true
  base:
    enabled: true
  devtime:
    enabled: false
  runtime:
    enabled: true
```

See [AI service groups in the Helm chart](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#ai-service-groups-in-the-helm-chart) for the services in each group, and [How do the switches combine?](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#how-do-the-switches-combine) for how group and service flags combine.

**2. Provision databases and secrets for the services you turn on**

In 6.0.0, these services need their own database users and secrets: agent-builder, dynamic-classifier, and harness in PostgreSQL, and designer-user in MongoDB. Create them before the upgrade for every service your group flags turn on. designer-user is in the `core` group, so it always needs its database.

The `keycloak-flowx-realm-clients` secret needs four new client secret keys, whatever your group flags. authorization-system reads all four at startup and, when it has Keycloak admin access (the default), creates the matching service-account clients with those secrets. If a key is missing, its database migration fails and authorization-system doesn't start. Without Keycloak admin access, create the four clients in Keycloak yourself.

See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the user, secret, key, and client names.

**3. Grant process-engine read access to the integration-designer bucket**

process-engine now reads Kafka payloads that integration-designer stores in its bucket. Give the process-engine credentials `s3:GetObject` on that bucket. See [New databases and secrets](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-databases-and-secrets) for the secret names.

**4. Set a bucket name for dynamic-classifier**

If you turn on dynamic-classifier, set its bucket under `services.dynamic-classifier.component.s3.applicationFileStorage.bucketName`. The chart sets no bucket names, as described in [Migrate S3 buckets](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#migrate-s3-buckets). dynamic-classifier also stores data on a 20Gi `ReadWriteOnce` volume, so your cluster needs a storage class that can provide one.

Unlike the Qdrant volumes, this claim is part of the Helm release. `helm uninstall`, or deleting the Argo CD Application with cascading deletion, deletes it, and with a `Delete` reclaim policy its data too.

**5. Move callers off the removed admin Ingress routes**

If you route with Kubernetes Ingress, the chart no longer creates an admin Ingress for doc-converter, data-privacy, speech-to-text, web-crawler, and dynamic-classifier, and the upgrade deletes the existing ones. ai-gateway keeps its own. Platform services and frontends don't use these routes. If anything outside the cluster calls one of these paths on the admin host, such as `/speech-to-text`, move it to the service's in-cluster address before you upgrade.

Installations that use the Gateway API aren't affected.

**6. Allow private MongoDB hosts**

nosql-db-runner now applies its host restriction to external MongoDB connections. Unmanaged MongoDB data sources that point to a host on a private network stop connecting after the upgrade. Add those hosts to `FLOWX_SSRFALLOWEDHOSTS` on nosql-db-runner. See [nosql-db-runner host restrictions](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-nosql-db-runner-host-restrictions-cover-mongodb).

**7. Trust your IMAP servers' certificates**

email-gateway now verifies the certificate of every IMAPS server it connects to. Email triggers that read from a server with a self-signed, private-CA, or mismatched certificate stop connecting after the upgrade. Add the server's CA to the email-gateway trust store, or list the host in `EMAILGATEWAY_IMAP_SSLTRUSTEDHOSTS`. See [IMAPS certificate verification](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-imaps-certificate-verification-in-email-gateway).

**8. Keep the management port private**

Upgrading from 5.9.5 or earlier? Since 5.9.6, advancing-controller no longer reads `MANAGEMENT_SECURITY_ENABLED`, and the actuator endpoints on its management port, `8081`, including Prometheus, answer without authentication. Check that no public Ingress or Gateway route exposes that port. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).

**9. Set the personal-data encryption key**

In 6.0.0, integration-designer needs `FLOWX_PII_ENCRYPTION_MASTER_KEY` for the Mask Personal Data and Restore Personal Data nodes. The variable has no default and the chart doesn't set it, so without it those nodes fail when a workflow runs them. Store a strong random value in a secret under the key `FLOWX_PII_ENCRYPTION_MASTER_KEY`, and load the secret into integration-designer:

```yaml theme={"dark"}
services:
  integration-designer:
    extraEnvVarsSecret: {your-pii-secret-name}
```

Keep the value identical on every pod and stable over time: changing it invalidates every in-flight placeholder map. See [Personal-data encryption master key](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-required-secret-personal-data-encryption-master-key).

**10. Choose how Elasticsearch replicates new indices**

In 6.0.0, process-engine and audit-core create new indices with the Elasticsearch `auto_expand_replicas` setting `0-1`, which overrides `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS`. On a cluster with two or more data nodes, the replica roughly doubles the disk space these indices use. To keep a fixed replica count instead, turn auto-expansion off on both services:

```yaml theme={"dark"}
services:
  process-engine:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
  audit-core:
    env:
      FLOWX_ELASTICSEARCH_INDEXSETTINGS_AUTOEXPANDREPLICAS: "false"
```

See [Elasticsearch replica auto-expansion](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-default-elasticsearch-replica-auto-expansion).

**11. Create the new Kafka topics**

New capabilities since 5.9.x depend on new Kafka topics. Create them before you upgrade. The 6.0.0 [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics) list every topic added since 5.9.6. Upgrading from 5.9.5 or earlier? Also create `ai.flowx.build.deployment-failed.v1`, added in 5.9.6. If your cluster uses ACLs, also give the new clients of three existing topics access, as listed in the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#new-kafka-topics).

If the chart creates your topics, add the new names to the list under `global.flowx.kafka.topics.topics`. The chart creates topics only when `global.flowx.kafka.topics.enabled` is `true`, as Strimzi `KafkaTopic` resources with 3 partitions and 3 replicas unless you set other values under `global.flowx.kafka.topics.defaults`:

```yaml theme={"dark"}
global:
  flowx:
    kafka:
      topics:
        enabled: true
        topics:
          - ai.flowx.build.deployment-failed.v1
```

## Render and compare

Render the 6.0.0 chart with your updated values before you upgrade, and compare it with what runs today:

```bash theme={"dark"}
helm template {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml > rendered.yaml
```

Check that the rendered Deployments are the services you expect. A missing AI base service, or an AI runtime service you didn't plan for, means a group flag isn't set. The render fails if your values still contain top-level `devtime` or `runtime` keys, or service keys outside `services`. See [Render and compare](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart#render-and-compare) for commands that compare environment variables per Deployment.

Using a mirrored or air-gapped registry? List the images the render references, mirror them, and point the chart at your registry with `global.imageRegistry`, as described in [Container images and registry](/6.x/setup-guides/setup-guides-overview#container-images-and-registry):

```bash theme={"dark"}
grep -E '^\s+image:' rendered.yaml | sort -u
```

## Upgrade

Run `helm upgrade` on your `flowx-ai` release with the 6.0.0 chart version and your updated values:

```bash theme={"dark"}
helm upgrade {your-release-name} {flowx-ai-chart-reference} --version {chart-version} \
  -n "$NS" -f values-flowx-ai.yaml
```

dynamic-classifier uses the `Recreate` deployment strategy, so its old pod stops before the new one starts.

## After the upgrade

* **Upgrading from 5.9.5 or earlier: re-publish builds that were waiting for a retry.** The retry queue for failed build deployments moves from Redis to PostgreSQL, and deployments waiting in Redis are not moved. 5.9.6 already uses the PostgreSQL queue. See [Upgrading from an older patch release](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#upgrading-from-an-older-patch-release).
* **Check component versions.** In FlowX.AI Designer, go to **Platform Status** and compare the versions with the [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#component-versions).
* **Check files from before the upgrade.** Open a process attachment, a media library asset, and a knowledge base document, and confirm they load. A bucket-not-found error in the logs points at a bucket name that didn't carry over.
* **Update name placeholders.** data-privacy now masks names with gendered placeholders, such as `<NAME_F_1>`. Update prompts or scripts that match the old form. See [Name placeholders in data-privacy](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-name-placeholders-in-data-privacy).
* **Expect a new workspace role name.** Users and groups with the Workspace operations editor role now have the Workspace corrective actions editor role, and keep access to process instance migration and move token. See [Workspace operations editor role replaced](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#changed-behavior-workspace-operations-editor-role-replaced).

## Related resources

> [card] [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0)
>
> Component versions and every deployment-level change in 6.0.0

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single chart


# iOS SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/ios

Migrate the FlowX iOS renderer SDK from 5.9.x to 6.0.0.

## iOS SDK migration guide

FlowX.AI 6.0 aligns the names of five iOS SDK APIs with the Android and web SDKs. The build requirements and library dependencies are unchanged, and the 5.9 names still compile, so your app builds with the 6.0 SDK after you update the pod version. Replace the deprecated names afterwards.

### System requirements

| Requirement | 5.9.x | 6.0 |
| - | - | - |
| Minimum iOS | iOS 15 | iOS 15 |
| Swift | 5.9 | 5.9 |

### Library dependencies

| Dependency | 5.9.x | 6.0 |
| - | - | - |
| [Alamofire](https://github.com/Alamofire/Alamofire) | `~> 5.9.0` | `~> 5.9.0` |
| [SDWebImageSwiftUI](https://github.com/SDWebImage/SDWebImageSwiftUI) | 3.0.3 | 3.0.3 |
| [SDWebImageSVGCoder](https://github.com/SDWebImage/SDWebImageSVGCoder) | `~> 1.7.0` | `~> 1.7.0` |

### Migration steps

**1. Update the SDK version**

```ruby Podfile theme={"dark"}
pod 'FlowXRenderer', '<5.9.x version>' # [!code --]
pod 'FlowXRenderer', '<6.0 version>' # [!code ++]
```

> [!NOTE]
>
> Find the SDK version that matches your platform version in **Release Notes → v6.0 → Deployment guidelines → Component versions**.

**2. Replace the deprecated APIs**

Replace the 5.9 names with the 6.0 names listed in the [Replace deprecated APIs](#replace-deprecated-apis) section. The parameters, types and behavior are unchanged.

### Replace deprecated APIs

The following 5.9 names still compile in 6.0, but they are deprecated and **will be removed in the next LTS release**. Replace them now. `imageBaseURL` is a property of `FXConfig`; the others are methods of `FlowX.sharedInstance`:

| Deprecated (5.9) | Replacement (6.0) |
| - | - |
| `imageBaseURL` | `assetsBaseURL` |
| `updateAuthorization(token:)` | `setAccessToken(token:)` |
| `getTag(withKey:)` | `getSubstitutionTagContent(key:)` |
| `getEnumeration(name:parentName:)` | `getEnumerationItems(name:parentName:)`, async and completion versions |
| `continueExistingProcess(uuid:name:…)` | `continueProcess(uuid:name:…)`, all three versions |

> [!TIP]
>
> Xcode shows a deprecation warning on every deprecated call, with a **Fix-it** that replaces it with the new name.

These changes are reflected in an actual implementation as shown below:

```swift theme={"dark"}
// configuration
FXConfig.sharedInstance.configure { config in
    config.imageBaseURL = myImageBaseURL // [!code --]
    config.assetsBaseURL = myAssetsBaseURL // [!code ++]
}

// authorization token changes
FlowX.sharedInstance.updateAuthorization(token: accessToken) // [!code --]
FlowX.sharedInstance.setAccessToken(token: accessToken) // [!code ++]

// substitution tags
FlowX.sharedInstance.getTag(withKey: "@@close_message") // [!code --]
FlowX.sharedInstance.getSubstitutionTagContent(key: "@@close_message") // [!code ++]

// enumerations
let items = await FlowX.sharedInstance.getEnumeration(name: "cities", parentName: "countries") // [!code --]
let items = await FlowX.sharedInstance.getEnumerationItems(name: "cities", parentName: "countries") // [!code ++]

// resuming a process
FlowX.sharedInstance.continueExistingProcess(uuid: uuid, // [!code --]
FlowX.sharedInstance.continueProcess(uuid: uuid, // [!code ++]
                                     name: processName,
                                     navigationController: processNavigationController,
                                     isModal: true)
```

## Related resources

> [card] [iOS SDK reference](/6.x/sdks/ios-renderer)
>
> iOS renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# Overview
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview

Migration guide for upgrading container apps and the flowx-ai Helm chart from FlowX.AI 5.9.x to 6.0.0

FlowX.AI 6.0.0 is a feature release. Self-hosted deployments usually follow LTS releases. Use this guide if you upgrade a self-hosted installation to 6.0.0.

> [!WARNING]
>
> A FlowX.AI 6.0.0 renderer SDK can need a newer framework version in your container app. Check the guide for your SDK, and upgrade the host app before you bump the FlowX SDK.

## Who is affected

Teams that run a container app with a FlowX renderer SDK (Angular, React, iOS, Android, or React Native) and move it to FlowX.AI 6.0.0. See [Renderer SDK migration](#renderer-sdk-migration).

Teams that run FlowX.AI on the `flowx-ai` Helm chart and upgrade it from 5.9.x to 6.0.0. See [Helm chart upgrade](#helm-chart-upgrade).

Teams with business rules, reusable functions, or workflow scripts that still run on the GraalVM script engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

## What's changing

An upgrade to 6.0.0 touches up to three areas, depending on what you run:

* **Helm chart:** set every AI service group flag explicitly, and create databases and secrets for the new services that need them. See [Helm chart upgrade](#helm-chart-upgrade).
* **GraalVM script engine:** deprecated. Scripts on GraalVM keep running after this upgrade, now with the same time limit as the native engine, and 6.1.x is the last release family that supports the engine. See [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).
* **Renderer SDKs:** container apps upgrade the FlowX renderer SDK, and the host framework where the SDK needs it. See [Renderer SDK migration](#renderer-sdk-migration).

## Migration process

Follow these steps in order, and skip the ones for areas you don't run.

**1. Check your starting point**

Upgrade to 6.0.0 from FlowX.AI 5.9.x on the `flowx-ai` Helm chart. If you still run the per-service charts or the `ai-platform` umbrella chart, first [migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart) on 5.9.x, as a separate change.

**2. Read the release notes and deployment guidelines**

The [release notes](/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026) list what changes in 6.0.0. The [deployment guidelines](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0) list the component versions, environment variables, and other configuration changes. The [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog) lists every feature change since 5.9.x, including the 5.10 to 5.13 feature releases.

**3. Prepare the infrastructure**

Create what the 6.0.0 services need before the upgrade window: new PostgreSQL and MongoDB database users and their secrets, four new keys in the `keycloak-flowx-realm-clients` secret, read access for process-engine to the integration-designer bucket, and storage for a 20Gi `ReadWriteOnce` volume if you turn on dynamic-classifier. Create the new Kafka topics, or list them for the chart to create. Also set the personal-data encryption key for integration-designer, choose how Elasticsearch replicates new indices, and allow the private MongoDB hosts and IMAP servers that existing connections use. [Before you upgrade a self-hosted installation](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0#before-you-upgrade-a-self-hosted-installation) is the full checklist, and [Update your values](./helm-chart#update-your-values) walks through each item.

**4. Check GraalVM scripts and plan the move off GraalVM**

Scripts on GraalVM keep running, but from 6.0.0 they stop at the same time limit as the native engine. Before the upgrade, check the scripts that can run longer than the limit, or raise it. Then plan their move to the native engine, as described in [Move scripts off the GraalVM engine](#move-scripts-off-the-graalvm-engine).

**5. Back up**

Take the backups listed in [Before you begin](./helm-chart#before-you-begin) right before the upgrade.

**6. Upgrade the Helm release**

Update your values and upgrade the release, as described in [Helm chart](./helm-chart).

**7. Upgrade your container apps**

For each container app, upgrade the host framework first if the SDK needs it, then the FlowX renderer SDK. See [Renderer SDK migration](#renderer-sdk-migration). Container apps on a 5.9.x renderer SDK keep running against a 6.0.0 backend, but screens can render incorrectly wherever 6.0.0 changed behavior. Release the upgraded apps in the same window as the Helm upgrade. For iOS and Android apps, end users who don't install the app update stay on the 5.9.x SDK, so plan how you move them to the new version.

## Helm chart upgrade

> [card] [Migrate to the flowx-ai Helm chart](/6.x/setup-guides/migrate-to-flowx-ai-helm-chart)
>
> Move from the per-service or ai-platform charts to the single `flowx-ai` chart

> [card] [Helm chart](./helm-chart)
>
> Upgrade an installation on the `flowx-ai` Helm chart from 5.9.x to 6.0.0

## Move scripts off the GraalVM engine

The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports GraalVM as a script engine for JavaScript and Python. Scripts that run on GraalVM keep running after the upgrade to 6.0.0, but they now stop at the same time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default. Before 6.0.0, a GraalVM script had no time limit. Before you upgrade, check the GraalVM scripts that can run longer than these limits, or raise the limits, as described in [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits). Then plan the move to the native engine.

**1. Find the scripts that run on GraalVM**

Business rules and reusable functions created before the move to the native engine run on GraalVM unless you switched them. The engine selector in each rule's script editor shows the engine it runs on. Workflow scripts run on GraalVM only if `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` is set on `integration-designer`.

**2. Test each script on the native engine**

The two engines don't always write the same output. Follow the step-by-step list in [Port a script from GraalVM to native](/6.x/docs/building-blocks/supported-scripts#port-a-script-from-graalvm-to-native), check the [common pitfalls](/6.x/docs/building-blocks/supported-scripts#common-pitfalls), and search scripts for Python imports the native engine blocks, such as `os` and `subprocess`, JavaScript `require(...)`, `process`, or `global`, and calls into Java classes such as `Java.type(...)`. The native engine supports none of these.

**3. Switch to the native engine**

Switch business rules [per rule](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-engine-per-rule). Move a reusable function and the rules that call it together: a function written for GraalVM fails when a rule on the native engine calls it. For workflow scripts, remove `APPLICATION_SCRIPTENGINE_PROVIDER=graalvm` from `integration-designer`. The default is `native`.

## Renderer SDK migration

> [card] [Angular SDK](./angular)
>
> Migrate the Angular renderer SDK to 6.0.0

> [card] [React SDK](./react)
>
> Migrate the React renderer SDK to 6.0.0

> [card] [iOS SDK](./ios)
>
> Migrate the iOS renderer SDK to 6.0.0

> [card] [Android SDK](./android)
>
> Migrate the Android renderer SDK to 6.0.0

> [card] [React Native SDK](./react-native)
>
> Migrate the React Native renderer SDK to 6.0.0


# React SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react

Migrate the FlowX React renderer SDK from 5.9.x to 6.0.0.

## React SDK migration guide

6.0 moves the React renderer to Node 26 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new prop and function names. The `logSink` and `logCategories` renderer props are removed and need a code change.

### Framework requirements

React stays on 19. Upgrade Node in your build and CI environments.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| React | 19 | 19 |
| Node | ≥ 24.0.0 | **≥ 26.0.0** |
| npm | ≥ 11.0.0 | ≥ 11.0.0 |

### FlowX SDK changes

#### Renamed props and functions

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `apiUrl` prop | `baseUrl` |
| `processApiPath` prop | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` prop | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customLoader` prop | `customLoaderProvider` (same shape) |
| UI Flow `appInfo.selectedProcessResourceId` | `resourceId` |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `useEnumeration(name, parentName?)` | `useEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl` and `assetsBaseUrl` apply to the process, UI Flow, chat and task management renderers. `enginePath` applies to the process, UI Flow and chat renderers. `customLoaderProvider` applies to the process and UI Flow renderers.

```diff theme={"dark"}
 <FlxProcessRenderer
-  apiUrl={baseUrl}
-  processApiPath="onboarding"
-  staticAssetsPath={mediaLibraryUrl}
-  authToken={token}
+  baseUrl={baseUrl}
+  enginePath="onboarding"
+  assetsBaseUrl={mediaLibraryUrl}
+  accessToken={token}
   ...
 />
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, file, params?)` to upload a file through an upload action. `params` are sent as extra form fields beside the file.

```typescript theme={"dark"}
input.runAction('action_one', { amount: 3 })
input.runUploadAction('upload_document', file, { side: 'front' })
```

`FlxCustomComponentData` is now generic (`FlxCustomComponentData<TFile = Blob>`) and requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### `logSink` and `logCategories` props removed

The `logSink` and `logCategories` props on `FlxProcessRenderer` and the UI Flow renderer are removed. Subscribe a log sink once at app start with `logSink()` from `@flowx/core-sdk` instead. It takes the same sinks and categories and returns a function that stops logging.

```diff theme={"dark"}
- <FlxProcessRenderer logSink={formattedLogger} logCategories={['rest', 'sse']} ... />
+ import { formattedLogger, logSink } from '@flowx/core-sdk'
+
+ const stopLogging = logSink(formattedLogger, { categories: ['rest', 'sse'] })
```

`@flowx/react-sdk` no longer re-exports `formattedLogger`, `createFormattedLogger` or the log types (`FlxLogCategory`, `FlxLogEvent`, `FlxLogSink`, `FlxLogSinkOptions`, `FormattedLoggerOptions`). Import them from `@flowx/core-sdk`.

#### Props removed or deprecated without replacement

| Prop | Status in 6.0 |
| - | - |
| `legacyHttpVersion` on the process renderer | Deprecated, no replacement. Still honored. |
| `legacyHttpVersion` on the UI Flow renderer | Removed. It never had any effect. |
| `customHeaders` | Removed. It never had any effect. |
| `updateStateEnabled` | Removed. It never had any effect. |
| `isAnonymousMode` | Removed. It never had any effect. |
| `fw` | Removed. It never had any effect. |

Delete the removed props from your process and UI Flow renderer props.

#### Behavior changes

* Links and URLs now carry only `?processInstanceUuid=`, including task management links. Links with `?processUuid=` still resume. An app on a 5.9 SDK reads only `?processUuid=`, so it can't resume from links a 6.0 app writes: upgrade every app that opens these links together.

## Related resources

> [card] [React SDK reference](/6.x/sdks/react-renderer)
>
> React renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# React Native SDK
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/react-native

Migrate the FlowX React Native renderer SDK from 5.9.x to 6.0.0.

## React Native SDK migration guide

6.0 moves the validated React Native target to Expo SDK 57 and aligns the SDK's names with the iOS and Android SDKs. Update your app to the new configuration and prop names. The Android Material 3 date picker opt-in is removed.

### Prerequisites and version range

The peer dependency floors are unchanged: `react-native` ≥ 0.83.0 and `react` ≥ 19.2.0. The validated target moves up one Expo SDK.

| Requirement | 5.9 | 6.0 |
| - | - | - |
| Validated target | Expo SDK 56, React Native 0.85.3 | **Expo SDK 57, React Native 0.86.3** |
| React | 19.2.3 (Expo SDK 56 pin) | 19.2.3 (Expo SDK 57 pin) |
| `react-native-blob-util` | ^0.24.9 | **^0.25.1** |
| `@react-native-community/datetimepicker` | Required peer | **No longer used** |

For an Expo project, align the project to Expo SDK 57, then reinstall the FlowX packages with `npx expo install`:

```bash theme={"dark"}
npx expo install expo@^57.0.0 --fix
```

For the full install command and the Expo SDK 57 reference versions, see the [React Native SDK reference](/6.x/sdks/react-native-renderer).

### FlowX SDK changes

#### Renamed configuration options and props

Replace each 5.9 name with its 6.0 name. The 5.9 names still work in 6.0, but they are deprecated.

| 5.9 | 6.0 |
| - | - |
| `FlxConfig.baseURL`, `apiUrl` prop | `baseUrl` |
| `processApiPath` | `enginePath` (the leading slash is optional) |
| `staticAssetsPath` | `assetsBaseUrl` |
| `authToken` prop | `accessToken` |
| `customHeaders` | `additionalHttpHeaders` |
| `customLoader` | `customLoaderProvider` (same shape) |
| `customStepperHeader` | `customStepperHeaderProvider` (same component) |
| `configure({ locale, language })` | `FlowX.changeLocaleSettings(locale?, language?)` |
| `configure({ updateStateEnabled })` | `FlowX.setUpdateStateEnabled(enabled)` |
| `setAccessToken(token: string)` | `setAccessToken(token?: string \| null)`: `null`, `undefined` or `''` switches to anonymous access |
| `processUuid` prop | `processInstanceUuid` |
| `onClose(name?)` | `onDismissRequested(name?)` (same argument) |
| Custom component `input.actionsFn.<name>(params)` | `input.runAction(name, params?)` |
| Custom component `registerValidation` prop | `validate` |
| `getEnumeration(name, parentName?)` | `getEnumerationItems(name, parentName?)` |
| `getStaticAsset(key)` | `getMediaItemUrl(key)` |
| `getMediaItemURL(mediaItemId)` (async) | `getMediaItemUrl(key)` (sync, once the process has loaded its media) |
| `getSubstitutionTag(code)` | `getSubstitutionTagContent(key)` |

`baseUrl`, `enginePath` and `assetsBaseUrl` apply to `FlowX.configure` and to the process, UI Flow and chat renderers. `onDismissRequested` applies to `startProcess`, `continueProcess`, `startUiFlow` and the process and UI Flow renderers.

In 5.9 the content helpers came only from `@flowx/core-sdk/rn`. `@flowx/react-native-sdk` now exports them too, under their new names only (`getEnumerationItems`, `getMediaItemUrl`, `getSubstitutionTagContent`).

```diff theme={"dark"}
 FlowX.configure({
-  baseURL: 'https://api.example.com',
-  processApiPath: 'onboarding',
-  staticAssetsPath: 'https://media.example.com',
-  customHeaders: { 'x-tenant': 'acme' },
-  language: 'en',
-  locale: 'en-US',
+  baseUrl: 'https://api.example.com',
+  enginePath: 'onboarding',
+  assetsBaseUrl: 'https://media.example.com',
+  additionalHttpHeaders: { 'x-tenant': 'acme' },
   organizationId,
 })
+FlowX.changeLocaleSettings('en-US', 'en')
```

#### New custom component action: `runUploadAction`

Custom components get `input.runUploadAction(name, { uri, name, type }, params?)` to upload a file through an upload action.

`FlxCustomComponentData` requires `runAction` and `runUploadAction`. If your tests build a mock of it by hand, add both.

#### Android Material 3 date picker removed

The opt-in Material 3 date picker for `FlxDatePicker` on Android is removed, along with the `@react-native-community/datetimepicker` peer dependency.

* Remove `material3` from any `configureFlxUiToolkit` call.
* The `@react-native-community/datetimepicker` package is no longer needed by FlowX. Uninstall it if nothing else in your app uses it.
* Keep the `@flowx/react-native-ui-toolkit` Expo config plugin registered. It no longer changes `AppTheme` or sets `extra.flxUiToolkit.material3`. It now adds `fontScale` to the main activity's `android:configChanges` and declares the microphone permissions used by chat voice input. Run `npx expo prebuild` again after the upgrade.

#### Behavior changes

* A session with no usable access token now starts as anonymous instead of failing. In 5.9, a token that was `null`, `undefined` (never set) or an empty string (`''`) made the start throw `Call FlowX.setAccessToken(...) before starting a process.` In 6.0 all three values start an anonymous session, and a backend that requires a token answers `401`. If your token fetch can return `null`, `undefined` or `''`, check the value before you start a process; otherwise the failure only shows up later as a `401`.
* Error and warning messages name `baseUrl` and `assetsBaseUrl` instead of `baseURL` and `staticAssetsPath`. Update any host code that matches on their text.

## Related resources

> [card] [React Native SDK reference](/6.x/sdks/react-native-renderer)
>
> React Native renderer SDK documentation

> [card] [Migration overview](./migration-overview)
>
> Full 5.9.x → 6.0.0 container app upgrade guide


# FlowX.AI 6.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/v6.0.0-october-2026

What's new in FlowX.AI 6.0: the Developer Agentic Harness builds story by story, plus bulk process-instance migration, scheduled workflows, and certificates.

[FlowX.AI 6.0.0 release hero](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/hero-6.0.0.html)

> [!NOTE]
>
> **Deployment models:**
>
> * SaaS Managed FlowX cloud deployments
> * All Deployments Available in both self-hosted and SaaS

FlowX.AI 6.0 is a feature release, live on FlowX.AI SaaS. Self-hosted installations usually wait for the next LTS release family, and can also upgrade to 6.0.0 now: see [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).

> [!WARNING]
>
> **Check your existing apps:** 6.0.0 changes how AI node prompts and retries, substitution tags, FlowX Database writes, masked names, IMAPS email triggers, evaluations, 5.1.x exports, and GraalVM scripts behave. See the [upgrade actions](/release-notes/v6.x/5.9-to-6.0-changelog) for what to check in each. Coming from 5.9.x? On the same page, also check the **Changed** entries for 5.10 to 5.13.

> [accordion] What changed since 5.13.0
>
> | 5.13.0 | 6.0.0 |
> | - | - |
> | The harness built the whole approved plan in one run | **Story-by-story delivery**: build one slice of the app, test it, then continue |
> | Changes to the app were described in words | **Comment mode**: select a component in the running app and say what should change |
> | The Command Center and the AI buttons in each editor opened standalone AI agents | **One agent rail**: **⌘K** or the header toggle opens the harness, which uses those agents internally |
> | A workflow started only when a process or caller started it | **Scheduled workflows**: date or cycle schedules on the Start node |
> | TLS was configured with keystores, truststores, and a skip switch | **Trust and Identity**: choose what the host is checked against, and whether to present a client certificate |
> | The Issues Console checked resources only | **Version checks**: entry points, theme, and library dependencies |
> | Only version exports sent notifications | **Import and export notifications**: version imports, build exports, and build imports notify you too |
> | A substitution tag had to be a property's whole value | **Tags inside any text**: `${tag:key}` next to static text and process data |
> | An AI node failed as soon as its AI service or provider couldn't be reached | **AI node retries**: on by default, up to 10 times, 30 seconds apart |
> | The chat message was appended to the end of an AI node's prompt | **Chat message in prompts**: reference `${userMessage}` in **Context** where the agent should answer it |
> | Evaluations grouped test cases into datasets and checked outputs with Code evaluators | **Test cases and asserts**: tagged test cases per workflow, checked with asserts and LLM evaluators |
> | The embedding model was locked once a Knowledge Base held content | **Re-embedding**: change **Containing Personal Information** later and the content is re-embedded |
> | Exporting rows to a file needed a Script node | **Generate Tabular File node**: a CSV or XLSX file from an array of rows |
> | A FlowX Database index couldn't reject duplicate values | **Unique indexes**: **Enforce unique values** on one attribute or a compound key |
> | A sensitive configuration value was shown in the Designer after saving | **Sensitive values stay hidden**: the Designer shows `********` in its place |
> | GraalVM was a supported script engine | **GraalVM deprecated**: 6.1.x is the last release family that supports it |

### **Coming from 5.9.x**

Releases 5.10 to 5.13 shipped to SaaS first. An installation that moves from 5.9.x to 6.0.0 gets their features too, including the [corrective actions](#corrective-actions-on-running-instances) below. The highlights:

> [card] New data sources
>
> [PostgreSQL](/6.x/docs/platform-deep-dive/integrations/postgresql-database) and [Db2](/6.x/docs/platform-deep-dive/integrations/db2-database) databases, and [SOAP services](/6.x/docs/platform-deep-dive/integrations/soap-system) imported from a WSDL.

> [card] Document nodes in workflows
>
> [Fill a template](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#template-filling-node) into a PDF or DOCX, [combine](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#combine-files-node) or [split](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#split-file-node) PDFs, and [parse](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#data-parse-xml-and-json-support) spreadsheets, CSV, XML, and JSON.

> [card] Multi-instance and triggered workflows
>
> Run [one subworkflow per array element](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#parallel-multi-instance) in parallel, and start a workflow from an [email or webhook trigger](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#external-triggers).

> [card] Workflow Instances page
>
> [Every workflow run in the project](/6.x/docs/projects/runtime/workflow-instances), filterable by status, date, and origin.

> [card] Branches and the Issues panel
>
> [Merge into any branch](/6.x/docs/projects/managing-applications/versioning#managing-branches), archive or delete branches, and [see validation findings](/6.x/docs/projects/managing-applications/checking-for-issues) in one panel.

> [card] Workflows as agent tools
>
> A Custom Agent node [calls FlowX workflows as tools](/6.x/docs/platform-deep-dive/integrations/custom-agent-node#how-workflow-tools-run), each with a hint for when to use it.

Full list: the [5.9.x to 6.0.0 changelog](/release-notes/v6.x/5.9-to-6.0-changelog), and the [5.10](/release-notes/v5.x/v5.10.0-july-2026/v5.10.0-july-2026), [5.11](/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026), [5.12](/release-notes/v5.x/v5.12.0-september-2026/v5.12.0-september-2026), and [5.13](/release-notes/v5.x/v5.13.0-september-2026/v5.13.0-september-2026) release notes.

***

### **Developer Agentic Harness**

> [card] Developer Agentic Harness
>
> > [tab] Overview
> >
> > The Developer Agentic Harness is the Designer's AI agent: it surveys your app, plans the change, and builds it on its own branch.
> >
> > **Before 6.0:** the harness ran an approved plan as a single run, and a conversation stayed tied to the app and branch where you started it. **Now:** a plan can split the work into stories, each a slice of the app you can try on its own, delivered one story at a time. You can point at a component in the running app to ask for a change. Your conversations follow you across the Designer.
> >
> > Each story says how to test it and what the agent needs from you, so you check one working slice before the next one starts. Comment mode turns the running UI flow or process into the brief: select a component, say what should change, and the comment lands in the conversation with the component attached. A conversation writes to the project and branch set by the first change you confirm, wherever you navigate after that, and the agent asks before it reads beyond that target.
> >
> > > [!NOTE]
> > >
> > > **Removed:** the Command Center, the standalone Analyst, Architect, Assistant, Designer, and Developer agents, and the AI buttons inside the editors, such as **Generate** on the data model and the sparkle buttons in business rules, reusable functions, and Script nodes. Open the agent rail instead: press **⌘K** (**Ctrl+K** on Windows and Linux) or select the sparkle toggle in the header. The harness still uses those agents internally for focused generation work. See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness#what-the-agent-can-see-and-change).
> >
> > <video>
> >   <track label="English" />
> > </video>
> >
> > See [Developer Agentic Harness](/6.x/ai-platform/developer-agentic-harness).
>
> > [tab] Key Features
> >
> > > [card] [Story-by-story delivery](/6.x/ai-platform/developer-agentic-harness#how-does-a-plan-with-stories-run)
> > >
> > > Implement the next story, test it with the steps the story gives, then continue with one story or all that remain.
> >
> > > [card] [Comment on the running app](/6.x/ai-platform/developer-agentic-harness#how-do-i-comment-on-the-running-app)
> > >
> > > Select **Comment** in the header, pick a component in the running UI flow or process, and say what should change.
> >
> > > [card] [Conversations that follow you](/6.x/ai-platform/developer-agentic-harness#sessions)
> > >
> > > Every conversation you have in the organization, searchable. Each keeps writing to the project and branch of its first confirmed change, wherever you navigate.
> >
> > > [card] [Asks before reading more](/6.x/ai-platform/developer-agentic-harness#what-happens-when-the-agent-asks-to-read-another-project)
> > >
> > > Read-only access to another project needs **Allow for this conversation**, and you can revoke it from the rail.
> >
> > > [card] [Attach your material](/6.x/ai-platform/developer-agentic-harness#attach-files-to-a-conversation)
> > >
> > > Give the agent PDF and DOCX briefs, screenshots, or BPMN diagrams to plan and build from.
> >
> > > [card] [Delete with a plan export](/6.x/ai-platform/developer-agentic-harness#delete-a-conversation)
> > >
> > > Deleting a conversation keeps its commits on the branch and offers **Export plan** for what wasn't run.
> >
> > > [card] [Entry points, handovers, and repairs](/6.x/ai-platform/developer-agentic-harness#entry-points-handovers-timeouts-and-repairs)
> > >
> > > The agent suggests an entry point and asks again before serving, adds handover buttons, times out workflow waits, and proposes a repair when a step fails, a limited number of times per step.
>
> SaaS

### **Corrective actions on running instances**

> [card] Corrective actions on running instances
>
> > [tab] Overview
> >
> > Corrective actions shipped in the 5.12 and 5.13 feature releases. They fix running process instances in place, without restarting them, from **Runtime** → **Runtime Control** → **Corrective Actions**.
> >
> > **Bulk process-instance migration** moves a filtered set of running instances from one build to another in one run, so a fix made in a newer build reaches instances already in flight. **Move token** takes the active token off the node the instances are stuck on and places it on another node of the same process, and the instances stay on their build.
> >
> > The **Workspace corrective actions editor** role grants both. It replaces the Workspace operations editor role, and the upgrade moves users and groups that had the old role to the new one.
> >
> > See [Migrate process instances](/6.x/docs/projects/runtime/active-process/migrate-process-instances) and [Move tokens](/6.x/docs/projects/runtime/active-process/move-token).
>
> > [tab] Key Features
> >
> > > [card] [Build to build, in bulk](/6.x/docs/projects/runtime/active-process/migrate-process-instances)
> > >
> > > Pick the source build, the target build, and the instances to move, then review the eligible count and map any node missing from the target build before you start.
> >
> > > [card] [Move token](/6.x/docs/projects/runtime/active-process/move-token)
> > >
> > > Resume stuck instances from another node of the same process, on one or many instances at once.
> >
> > > [card] [Dedicated role](/6.x/setup-guides/access-management/roles-permissions-matrix#workspace-corrective-actions-editor-permission-matrix)
> > >
> > > Grant corrective actions without handing out workspace admin rights.
> >
> > > [card] [Notified when done](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification)
> > >
> > > The notification center reports when a bulk migration finishes.
>
> SaaS

### **New Designer header**

> [card] New Designer header
>
> **Before 6.0:** the branch selector, the version state, and **Commit Changes** sat in the project's top bar. **Now:** the header holds the project name, the **Config** / **Runtime** switch (**Config** to edit a version, **Runtime** for builds and their settings), the **Build with AI** and **Comment** toggles, and **Run project**, which starts the version's entry point. Branching, the current version, and **Commit Changes** move to a version block at the start of the footer on Config pages.
>
> ![Designer project on a Config page: the header shows the project name, the Config and Runtime switch, the Build with AI toggle, and Run project; the footer starts with the version block showing the main branch, the version name, and Start New Version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/designer-header-6-0.png)
>
> The Designer also opens the workspace you used last, and **Organization settings** is in the avatar menu. See [Header and version block](/6.x/docs/projects/managing-applications/versioning#header-and-version-block).
>
> SaaS

### **AI node retries**

> [card] AI node retries
>
> **Before 6.0:** an AI node failed as soon as its AI service or LLM provider couldn't be reached. **Now:** every AI node except Deep Research retries up to 10 times, 30 seconds apart, when the service is unreachable, the provider is unavailable or rate-limits the request, or the connection fails. Timeouts aren't retried by default, because the node may already have called its tools.
>
> Toggle **Allow Retry** on in the node's **Settings** to set your own count, interval, and exponential backoff. After the last retry, the workflow continues down the node's failure exit if one is connected. With **Allow Retry** on, the workflow run logs show each attempt on its own line.  See [AI node retries](/6.x/ai-platform/agent-builder/node-types#what-happens-when-an-ai-node-can’t-reach-its-ai-service).
>
> SaaS

### **Knowledge Base re-embedding and entry lifecycle**

> [card] Knowledge Base re-embedding and entry lifecycle
>
> **Before 6.0:** the embedding model was locked once a Knowledge Base held content. **Now:** turning **Containing Personal Information** on or off later re-embeds the existing content with the new model. Search keeps using the current embedding while it runs, and content changes are locked until it finishes. If some documents fail, the Knowledge Base stays on its previous model and the header says how many weren't re-embedded.
>
> Entries also have their own lifecycle: **Disable Entry** takes an entry out of retrieval without removing it, **Activate Entry** puts it back, and an entry can be permanently deleted. See [Can I change personal information after content is ingested?](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview#can-i-change-personal-information-after-content-is-ingested) and [disable, re-activate, or permanently delete an entry](/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/managing-content#how-do-i-disable-re-activate-or-permanently-delete-an-entry).
>
> SaaS

### **Chat message in AI node prompts**

> [card] Chat message in AI node prompts
>
> > [!WARNING]
> >
> > **Behavior change.** The chat message is no longer appended to the end of an AI node's prompt automatically. In chat-driven workflows, reference `${userMessage}` in the node's **Context** wherever the agent should answer the user's message.
>
> The message still reaches the model inside the input data when **Use only referenced values as input** is off. See [Context](/6.x/ai-platform/chat-driven-workflows#context).
>
> SaaS

### **Evaluations: test cases replace datasets**

> [card] Evaluations: test cases replace datasets
>
> **Before 6.0:** test cases lived in datasets, and the Code evaluators checked outputs for an exact, JSON, or Levenshtein match. **Now:** each workflow has its own test cases, grouped by tags. Each case carries its checks: asserts for **equals** and **equals as JSON**, and LLM evaluators with a pass threshold. An experiment runs the test cases you select. See [Evaluations](/6.x/ai-platform/evaluations).
>
> > [!WARNING]
> >
> > **Behavior change.** The upgrade converts each dataset's test cases and keeps the dataset name as a tag, but adds no checks. An experiment skips a case with no enabled check, so add an assert or evaluator to each converted case before you run it. The Code evaluators are removed: use the **equals** assert in place of **Exact match**, and **equals as JSON** in place of **JSON match**. **Levenshtein** has no replacement. See [Datasets from earlier versions](/6.x/ai-platform/evaluations#datasets-from-earlier-versions).
>
> SaaS

### **Scheduled workflows**

> [card] Scheduled workflows
>
> > [tab] Overview
> >
> > **Before 6.0:** an integration workflow started only when a process, a UI flow, or another caller started it. **Now:** add schedules to the workflow's **Start** node and it starts by itself at each fire time.
> >
> > Schedules fire once on a date or repeatedly on an ISO or cron cycle, and the dialog previews the next fire times in your local time zone. Saving a schedule or publishing a build never turns it on: activate it in **Runtime** → **Runtime Settings** → **Schedules**.
> >
> > See [How do I run a workflow on a schedule?](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-control-flow#how-do-i-run-a-workflow-on-a-schedule).
>
> > [tab] Key Features
> >
> > > [card] Date or cycle
> > >
> > > Fire once at a date and time, or repeatedly with an ISO or cron expression built from guided fields.
> >
> > > [card] Up to 50 per workflow
> > >
> > > Each schedule has a name that is unique on its workflow. Schedules are available on Output Focused workflows, which process structured input and output.
> >
> > > [card] Explicit activation
> > >
> > > A schedule fires only after you activate it on the **Schedules** page, for a workflow in the project's active build.
> >
> > > [card] Next fire times
> > >
> > > Check the previewed fire times before you save.
>
> SaaS

### **Certificates: trust and identity**

> [card] Certificates: trust and identity
>
> > [tab] Overview
> >
> > **Before 6.0:** a REST data source combined keystore, truststore, and a skip-verification switch in one TLS setup. **Now:** the **Certificates** panel has two independent parts. **Trust** decides what the host's certificate is checked against: **System CAs** (the default), a **Custom CA**, or **None (insecure)**. **Identity** is the client certificate FlowX presents for mutual TLS, turned on with **Present a certificate**.
> >
> > The same panel is available on File Storage data sources. Existing certificate settings are converted to the new model automatically.
> >
> > See [Certificates](/6.x/docs/platform-deep-dive/integrations/data-sources-and-endpoints#certificates) for when to use each option.
>
> > [tab] Key Features
> >
> > > [card] Trust per data source
> > >
> > > Changing trust on one data source leaves every other call verified as before.
> >
> > > [card] Mutual TLS when asked
> > >
> > > Present a client certificate only to hosts that require one.
> >
> > > [card] [File Storage too](/6.x/docs/platform-deep-dive/integrations/file-storage#certificates)
> > >
> > > S3-compatible storage uses the same Trust and Identity settings.
> >
> > > [card] Insecure, by name
> > >
> > > **None (insecure)** is labeled as such and accepted only on REST and File Storage data sources.
>
> SaaS

### **Generate Tabular File node**

> [card] Generate Tabular File node
>
> A new node under **Tools** in the workflow palette turns a workflow variable that holds an array of rows into a CSV or XLSX file, stored as a document linked to the workflow run. A workflow can now produce an export without a Script node. See [Generate Tabular File node](/6.x/docs/platform-deep-dive/integrations/workflow-nodes-data-and-ai#generate-tabular-file-node).
>
> SaaS

### **FlowX Database unique indexes**

> [card] FlowX Database unique indexes
>
> Toggle **Enforce unique values** when you add an index to reject documents that repeat a value already stored, on one attribute or on a compound key, with an option to exempt documents that leave the key empty. Existing duplicates are reported when you run **Apply Indexes**, before the index is created. You can also delete a document from the collection view. See [How do I make an index unique?](/6.x/docs/platform-deep-dive/integrations/flowx-database#how-do-i-make-an-index-unique).
>
> SaaS

### **Issues Console version checks**

> [card] Issues Console version checks
>
> **Before 6.0:** an Issues Console check, which validates the resources in a project version, covered processes, UI flows, and integration workflows. **Now:** it also checks the version itself: missing, broken, or mismatched entry points, a theme that isn't in the workspace, library builds that are missing directly or transitively, and dependencies the version doesn't use. Selecting a finding opens the version settings or the **Dependencies** page, where you fix it. See [Which version settings does a check cover?](/6.x/docs/projects/managing-applications/checking-for-issues#which-version-settings-does-a-check-cover).
>
> SaaS

### **Import and export notifications**

> [card] Import and export notifications
>
> The notification center now covers version imports and build exports and imports, alongside version exports and process instance migrations. Each operation notifies you when it starts and replaces that entry with its result: ready to download, imported, needs review with a conflict or excluded-resource count, failed, or timed out. See [What sends a notification](/6.x/docs/flowx-designer/notification-center#what-sends-a-notification).
>
> SaaS

### **Resource documentation**

> [card] Resource documentation
>
> Open **Documentation** from a resource's menu to give it a short description and longer Markdown documentation, written and previewed in the same window. Media Library assets in a project library get a description too, used as the image's alt text in the asset preview. Knowledge base stores, navigation areas, and user tasks in the process navigation panel have **Documentation** in their menus too. See [How do I document a resource?](/6.x/docs/projects/resources#how-do-i-document-a-resource).
>
> SaaS

### **Sensitive values stay hidden**

> [card] Sensitive values stay hidden
>
> After you save a `value` configuration parameter with **Sensitive** on, the Designer shows `********` in place of the value in the parameters list, overrides, build details and lists, and the merge view. The real value is still used at runtime, and editing other fields keeps it. See [What happens after you save a sensitive value?](/6.x/docs/platform-deep-dive/core-extensions/configuration-parameters#what-happens-after-you-save-a-sensitive-value).
>
> SaaS

### **Substitution tags inside any text**

> [card] Substitution tags inside any text
>
> > [tab] Overview
> >
> > **Before 6.0:** a substitution tag resolved only when it was the whole value of a property, so `@@greeting ${firstName}` rendered as empty text. **Now:** write `${tag:key}` anywhere in a component's text, next to static text and process data, and the renderer fills in every tag: `${tag:greeting}, ${firstName}!` renders as "Hello, John!".
> >
> > The upgrade rewrites whole-value `@@key` references to `${tag:key}` in processes, UI flows, and reusable templates, so existing screens render as before. `@@key` keeps working as a whole value.
> >
> > See [How do I reference a substitution tag in UI content?](/6.x/docs/platform-deep-dive/core-extensions/content-management/substitution-tags#how-do-i-reference-a-substitution-tag-in-ui-content).
>
> > [tab] Key Features
> >
> > > [card] Tags, text, and data together
> > >
> > > Use several tags and process data placeholders in one label, placeholder, message, validator message, or option label.
> >
> > > [card] Existing references converted
> > >
> > > Whole-value `@@key` references become `${tag:key}`. Option values and the default of choice components stay `@@key`.
> >
> > > [card] Task Manager columns
> > >
> > > A column value of exactly `${tag:key}` shows, filters, and sorts like `@@key`.
> >
> > > [card] Import from and export for 5.9
> > >
> > > Importing from 5.9 converts `@@key` forward. Exporting for 5.9 converts whole-value tags back to `@@key`.
>
> SaaS

### **GraalVM script engine deprecated**

> [card] GraalVM script engine deprecated
>
> The GraalVM script engine is deprecated. FlowX.AI 6.1.x is the last release family that supports it, for every JavaScript and Python script: business rules, reusable functions, workflow Script nodes, and the rest. Scripts that run on GraalVM keep working in 6.0.0. Move them to the native engine, the default since 5.9.0, before support ends. See [Move scripts off the GraalVM engine](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview#move-scripts-off-the-graalvm-engine).
>
> **Time limits on GraalVM too:** scripts that run on GraalVM now stop at the same per-language time limit as the native engine: 5,000 ms for JavaScript and 10,000 ms for Python by default, set on the process engine and Integration Designer with `APPLICATION_SCRIPTENGINE_NATIVEENGINE_JS_EXECUTIONTIMEOUTMS` and `APPLICATION_SCRIPTENGINE_NATIVEENGINE_PYTHON_EXECUTIONTIMEOUTMS`. Before 6.0.0, a GraalVM script had no time limit. A script that runs past its limit is stopped and fails with an error saying it did not finish within its time limit. Before you upgrade, check GraalVM scripts that can run longer than these limits, or raise the limits. See [Script size and execution limits](/6.x/docs/building-blocks/actions/business-rule-action/business-rule-action#script-size-and-execution-limits).
>
> All Deployments

### **Smaller improvements**

> [card] Smaller improvements
>
> **Auto-arrange on both canvases:** select **Auto-arrange** on the workflow canvas, or **Arrange** on the process canvas, to see a tidied layout in the **Layout preview** bar before anything moves. Compare it with the current layout, then **Apply** or **Cancel**. See [How do I auto-arrange the workflow canvas?](/6.x/docs/platform-deep-dive/integrations/integration-workflows#how-do-i-auto-arrange-the-workflow-canvas).&#x20;
>
> **Timers in local time:** timer nodes now use the same editor as workflow schedules. Dates and times you pick are in your local time and saved in UTC, one control switches between **Guided**, **Expression**, and **Process variable** entry, and cycle timers preview their next fires. Timers saved with the earlier date pickers can look shifted by your UTC offset in the panel, but they still fire at their stored time. See [Which entry modes can I use?](/6.x/docs/building-blocks/node/timer-events/timer-events#which-entry-modes-can-i-use).&#x20;
>
> **Longer branch names:** branch names can be up to 40 characters, up from 16. See [Creating a new branch](/6.x/docs/projects/managing-applications/versioning#creating-a-new-branch).&#x20;
>
> **Organization branding:** a **Branding** page under **Organization settings** > **Customization** sets one brand for the organization: name, logos, legal and social links, container app colors and header, and the sender, signature, and text of the invite, verify email, and reset password emails, with a preview of each. Login page and email branding are available on FlowX SaaS only. See [Organization branding](/6.x/docs/saas/organization-branding).&#x20;
>
> **Typed dates in the Datepicker:** turn on **Allow manual input** to let users type a date in the pattern of the project's default locale instead of picking it. Web only, and not available while **Legacy component** is on.&#x20;
>
> **Data mapping creates data types:** type a new attribute path such as `client.address.street`, and saving the mapping creates the data types it names. Until then, the mapper marks them as not yet added to the data model. Required rows show an asterisk, and mapping an object onto a primitive field shows an error.&#x20;
>
> **Removed fields stay removed:** when a node's output sets a field to `null`, the field is removed from the workflow data and later steps no longer restore it with a `null` value. If a condition checks for `null`, make it handle a missing field too.&#x20;
>
> **Keys with dots stay whole:** a data key that contains a dot, such as `cash|31.12.2025`, now stays one key when a workflow saves its data. Before, the key was split into nested objects and later nodes could not read it.&#x20;
>
> SaaS

***

## Shipped by

This release is the work of the FlowX engineering team across backend, frontend, AI, infra, QA, and docs. It also belongs to the customers who told us what was broken last quarter. Thank you.

***

## Deployment guidelines

For component versions, environment variables, and Kafka topics, see [Deployment guidelines v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0). To upgrade the Helm chart or a renderer SDK, follow [Migrating from v5.9.x to v6.0.0](/release-notes/v6.x/v6.0.0-october-2026/migrating-from-v5.9-to-v6.0/migration-overview).


# Deployment guidelines v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/deployment-guidelines-v4.6.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.0 FlowX.AI release, you cannot import old process definitions or resources into the new platform from older versions .

## Component versions

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.0.2** | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.3** | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.64.5** | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.64.5** | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.64.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.1.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.0** | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.2** | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.0.3** | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.0.3** | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | **4.1.3** | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | **7.0.3** | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.0** | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.0** | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.1.12** | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.0** | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.1** | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.0.18** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.0.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.3** | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.9** | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.10** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.9** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.3** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.24** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.5.5** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.0 | Keycloak | 22.x |
| 4.6.0 | Kafka | 3.2.x |
| 4.6.0 | PostgreSQL | 16.2.x |
| 4.6.0 | MongoDB | 7.0.x |
| 4.6.0 | Redis | 7.2.x |
| 4.6.0 | Elasticsearch | 7.17.x |
| 4.6.0 | Oracle Database | 21C/ 21-XE |
| 4.6.0 | Angular (Web SDK) | 19.x |
| 4.6.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

## New microservices - setup guides

> [card] [Application-manager](/4.7.x/setup-guides/application-manager)

> [card] [Runtime-manager](/4.7.x/setup-guides/runtime-manager)

> [card] [Integration Designer](/4.7.x/setup-guides/integration-designer-setup)

> [card] [Data-sync job](/4.7.x/setup-guides/data-sync)

## New access rights and roles

> [card] [Integration Designer access rights](/4.7.x/setup-guides/access-management/configuring-access-rights-for-integration-designer)

> [card] [Application Manager access rights](/4.7.x/setup-guides/access-management/app-manager-access-rights)

## Updated access rights and roles

> [card] [Task Manager access rights](/4.7.x/setup-guides/plugins-access-rights/configuring-access-rights-for-task-management)
>
> Added new roles for **manage-views**.

## New service accounts

> [card] [Runtime manager service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#runtime-manager-service-account)

> [card] [Integration Designer service account](/4.7.x/setup-guides/access-management/configuring-an-iam-solution#integration-designer-service-account)


# Deployment changes for v4.6.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x

This document outlines the configuration and infrastructure changes introduced from v4.1.x to v4.6.0 for deploying the FlowX.AI platform.

## CMS Setup

### MongoDB configuration

In version 4.6.0, the CMS setup includes a more comprehensive MongoDB configuration, especially for runtime data handling:

* **Runtime MongoDB Instance**: A dedicated MongoDB instance for managing runtime data.
  * **New Environment Variables**:
    * `RUNTIME_DB_USERNAME`: Username for runtime MongoDB access.
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: Connection URI for the runtime MongoDB instance.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`). Default is `mongodb`.
  * **Transaction Settings for Mongock Library**:
    * `MONGOCK_TRANSACTIONENABLED`: Controls MongoDB transaction support with Mongock, defaulting to `false` due to compatibility concerns with MongoDB 5.

### Private storage configuration

Private CMS to securely store uploaded documents and AI-generated documents, ensuring they are accessible only via authenticated endpoints. This CMS will support AI services and workflows while maintaining strict access controls.

> [!NOTE]
>
> Private CMS ensures secure file storage by keeping documents hidden from the Media Library and accessible only through authenticated endpoints with access token permissions. Files can be retrieved using tags (e.g., ai\_document, ref:UUID\_doc) and are excluded from project builds as they aren't needed at runtime.

* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SERVER_URL`: This environment variable specifies the URL of the S3 server used for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_BUCKET_NAME`: This environment variable specifies the name of the S3 bucket dedicated to private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET`: This environment variable indicates whether the private S3 bucket should be created if it does not already exist. It can be set to true or false.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_ACCESS_KEY`: This environment variable holds the access key used to authenticate to the S3 server for private file storage.
* `APPLICATION_FILE_STORAGE_S3_PRIVATE_SECRET_KEY`: This environment variable holds the secret key used to authenticate to the S3 server for private file storage.

> [card] [CMS setup guide](/4.7.x/setup-guides/cms-setup)

***

## Admin setup

### MongoDB configuration

Version 4.6.0 introduces a new MongoDB setup in the Admin service for managing data model information:

* **New MongoDB Data Model Configuration**:
  * **Environment Variables**:
    * `SPRING_DATA_MONGODB_URI`: URI for connecting to the MongoDB data model instance.
    * `DB_USERNAME`: Set to `data-model` for data model access.
    * `SPRING_DATA_MONGODB_STORAGE`: Specifies storage type for Azure environments (`mongodb` or `cosmosdb`).

***

## Engine setup

### MongoDB configuration

The Engine configuration now includes additional setup for a runtime MongoDB instance to manage runtime builds:

* **Runtime MongoDB for Engine**:
  * **New Environment Variables**:
    * `SPRING_DATA_MONGODB_RUNTIME_URI`: URI for connecting to the runtime MongoDB.
    * `DB_USERNAME`: Set to `app-runtime` for runtime data access.


# Configuration and migration guide
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/process-configuration

This guide outlines changes in process and UI configuration from v4.1.x to 4.6.0 version.

## Projects

The **Projects** feature in FlowX AI v4.6.0 is a new structure that organizes all dependencies and resources required for a project into a single deployable view. This enhancement simplifies configuration, deployment, and maintenance by layering projects on top of processes, offering a centralized workspace that encapsulates everything needed for project execution.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/designer_new.png)

Several key configuration changes impact how resources and dependencies are managed, deployed, and maintained. This guide provides a breakdown of the configuration changes, automatic migration processes, and manual steps required to ensure a smooth transition.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/application/application_processes.png)

***

### Consolidated resource management

* **Change**: All resources that were previously managed individually within processes are now grouped within Projects. This includes content management elements, integrations, themes, task configurations, and permissions.
* **Impact**: Resources like **enumerations**, **substitution tags**, and **generic parameters** are now managed within Projects, allowing centralized configuration and version control.
* **Migration**: All process-related resources will be migrated automatically into a **default project**, ensuring continuity of functionality in the new framework. After migration, you should verify that all critical resources are correctly configured within this default project.

> [card] [What are resources?](/4.7.x/docs/projects/resources)

### Enhanced version control and dependency management

* **Impact**: Projects support **dependency management** through **Libraries** and enforce version-controlled resources. Setting up a project now requires careful dependency management and versioning to prevent unintended updates.
* **Benefit**: Allows for modular, reusable resources and stable deployments across projects, reducing resource duplication and enhancing project compatibility.

### Migration checklist

To ensure a smooth transition, complete the following steps:

1. **Verify Process Migration**: Confirm that all existing process definitions have been correctly migrated into the default project.
2. **Set Configuration Parameter Overrides**: Post-deployment, adjust environment-specific Configuration Parameters in the default project.
3. **Update Task Views**: Replace the global "All Tasks" feature with project-specific Views in each project.
4. **Transfer Processes and Dependencies Manually**: If moving a process from the default project to another project, manually transfer associated resources and re-check dependencies.

***

## Generic parameters migration

* **Overview**: In version 4.6.0, global generic parameters (from versions prior to 4.6.0) have been migrated to project-level as Configuration Parameters, consolidating parameter management within specific projects for improved organization and control.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/Screenshot%202024-11-06%20at%2019.04.49.png)

* **Migration**: All generic parameters will be automatically migrated to Configuration Parameters section under a default project.
* **Business Rules Unaffected**: There is no impact on existing business rules; they will continue to function as before without requiring updates.
* **Process Export Considerations**: If you export a process from one project to another, ensure that you also transfer the associated configuration parameters. This step is crucial to maintain process functionality and consistency across projects.
* **Important Note**: Only values of generic parameters associated with the specific environment, or where `env = null` (displayed as "all" in the interface in versions prior to 4.6.0), will be migrated. You must ensure that you have correctly set the values for generic parameters, paying attention to environment values (which are case-sensitive), and export these generic parameters before migration to avoid any potential data loss.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.39.29.png)

* **Post-Deployment Step**: After the first deployment to an upper environment, you will need to create configuration parameter overrides with the specific values required for that environment. This ensures that all environment-specific configurations are accurately maintained and applied across different deployment stages.

> [!TIP]
>
> To set configuration parameter overrides, navigate to **Your App -> Runtime -> Configuration Parameters Overrides**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-07%20at%2010.42.06.png)

***

## Source systems migration

* **Change**: Source systems have not been migrated automatically and need to be manually recreated.
* **New Location**: In v4.6.0, source systems have been moved under Integration Designer.
* Manual Migration Required:
  1. Navigate to Integration Designer.
  2. Recreate each source system manually with the same code as in the original configuration.
  3. Ensure the "Enable enumeration value mapping" checkbox is enabled.
* **Impact**: Failure to manually migrate source systems may result in broken integrations and missing data mappings.

**v4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2009.53.30.png)

**\< v.4.6.0**:

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2010.09.12.png)

## Task management

* "All Tasks" as a View: The global "All Tasks" feature is no longer standalone and will now function as a View in a project.

**v4.6.0:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

**v4.1.x:**

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/all_tasks.png)

***

## General

Before starting the migration, complete the following steps:

1. **Merge All Feature Branches**: Ensure all feature branches for processes are merged into the latest version on the main branch.
2. **Remove Unnecessary Resources**: Delete any test processes or resources that are no longer needed.
3. **Export Generic Parameters**: Export generic parameters as a backup to ensure they migrate accurately to project-specific Configuration Parameters.

### Migration steps

During migration, resources will be transferred into a single **default project** with one committed version.

* **Process Definitions**: Only the last committed process version on the main branch will migrate. If no committed version exists, the latest WIP version will be used.
* **Enumerations, Substitution Tags, and Task Manager**: These resources will be migrated to the default project.
* **Generic Parameters**: Migrated as **Configuration Parameters** within the default project, covering only values where `env = null` or that match the platform’s environment setting.
* **Languages**: Language settings (available languages and default) will be moved to project settings. Languages remain globally available.

### Resources excluded from migration

Some resources will remain globally available or are deprecated:

* **Themes**
* **Fonts**
* **Global Media Library** (for media used in themes)
* **Out of Office (Task Manager)**
* **Integration Management** (will not be available in v4.6.0)

***

## Datepicker Migration

In version 4.6.0, significant updates have been introduced to the **Datepicker** component to ensure compatibility with ISO 8601 date formats and enhanced handling of date attributes within the **Data Model**. This migration affects both newly created and existing processes.

### Key changes

1. **Introduction of Date Types**:
   * **Standard Date**: Stores and displays date values in ISO 8601 format, respecting the project's locale and timezone settings.
   * **Legacy Date**: Retains previous formatting to ensure compatibility with existing business rules and processes.

2. **Properties Updates**:
   * The **Datepicker** now supports dependent properties such as `minDate`, `maxDate`, and `defaultValue`. These properties:
     * Follow the formatting rules of the selected date type (Standard or Legacy).
     * Ensure that dynamic date values pulled from the **Data Model** are displayed correctly.

3. **Backward Compatibility**:
   * **Existing Processes**: All migrated processes with legacy Datepicker components will default to `Legacy Date` type. This preserves the original formatting and ensures no disruption in business rules or workflows.
   * **New Processes**: Newly created processes will default to `Standard Date` type, saving values in ISO 8601 format.

***

### Migration process

1. **Legacy Datepickers**:

   * Automatically flagged during migration.
   * Continue to work with existing business rules.
   * Require manual review for future updates to transition to the **Standard Date** format.

2. **Business Rules Updates**:
   * Legacy Datepickers may require manual adjustments if associated business rules reference hardcoded date formats.
   * Ensure that any dynamic dates used in business rules are compatible with the ISO 8601 standard.

3. **Standard Datepickers**:
   * All new Datepicker components save date values directly in ISO 8601 format.
   * Fully compatible with updated **Data Model** attributes, allowing seamless integration with external systems, adaptors, and reporting plugins.

### Considerations

* **Default Values**:
  * For **Standard Datepickers**, the `defaultValue` must be in ISO 8601 format.
  * Dynamic defaults can also be set using **Data Model** attributes or process data.
* **Data Model Integration**:
  * All external and internal date attributes, including those used by adaptors or business rules, must be explicitly defined in the **Data Model**.
* **UI Designer Overrides**:
  * Overrides can be applied to display dates differently for specific UI elements, ensuring flexibility for localized formatting.

### Recommendations for transition

* **Existing Processes**:
  * Leave Datepicker components in `Legacy` mode unless business rules and workflows are updated to support ISO 8601.
* **New Processes**:
  * Use `Standard Date` to ensure future compatibility and alignment with ISO 8601 formatting.
* **Documentation**:
  * Review and update all timer expressions, adaptors, and external data feeds to use ISO 8601 format for consistency.

***

## Updates to expression evaluation

**What Changed:**

* A fix was implemented in the web expression evaluator regarding how string values are handled during process value replacement.
* Previously, when evaluating dynamic and computed expressions, string variables required manual insertion of double quotes (`""`) because the system did not automatically add them.
* With the recent fix, the system now **automatically adds the necessary quotes** for string replacements.

**Impact:**

* **Existing Expressions:** If your current dynamic or computed expressions include manually added quotes around string values, these might now result in redundant quotes or incorrect string formatting.
* **Behavioral Shift:** The automatic quote addition alters how string values are processed, which might affect outputs if the expressions were structured with the expectation of manual quotes.

**Action Required:**

1. **Review Your Expressions:** Check any dynamic and computed expressions in your processes that currently include manual double quotes around string values.
2. **Modify as Needed:** Remove unnecessary double quotes where the system now handles them automatically to prevent duplicate quoting or formatting issues.

***

## Export/import enumerations (CSV)

In the transition from version 4.1.x to 4.6.0, the following columns have been removed from the enum CSV export format:

* description.application
* description.draft
* contentValue.childContentDescription.application
* contentValue.childContentDescription.draft
* contentValue.childContentDescription.type

Existing CSV export/import processes should be updated to remove references to these columns to ensure compatibility with the 4.6.0 release.

***

## Post-migration recommendations

For complex projects with multiple use cases, **do not use the default project for ongoing development or production builds**. Instead:

1. **Create Branches within the Default Project**: Organize and streamline resources by creating branches. This enables a lightweight build focused on production.
2. **Split the Default Project into Smaller Projects**: Use the import/export feature to separate the default project into individual projects by use case.
   * **Note**: When importing processes into a new project, resource references may need to be manually reconfigured.

***


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/renderers

This guide assists in migrating from FlowX v4.1.x to v4.6.0.

## Android SDK migration guide

### Initialization config changes

A new configuration parameter named `locale` was added to improve formatting the dates, numbers and currencies.

When the SDK initialization happens through the `FlowxSdkApi.getInstance().init(...)` method, the argument must be included inside the `config: SdkConfig` parameter value:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().init(
    ...
    config = SdkConfig(
        baseUrl = "URL to FlowX backend",
        imageBaseUrl = "URL to FlowX CMS Media Library",
        enginePath = "some_path",
        language = "en",
        locale = Locale.getDefault(), // e.g. Locale("en", "US"), Locale("fr", "CA")
        validators = mapOf("exact_25_in_length" to { it.length == 25 }),
        enableLog = false,
    ),
    ...
)
```

### Changes when starting a Flowx process

Two new parameters were added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The id of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun startProcess(
    projectId: String,
    processName: String,
    params: JSONObject = JSONObject(),
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes when resuming a Flowx process

One new parameter was added:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the continued process ends | `(() -> Unit)?` | Optional. It defaults to `null`. |

```kotlin theme={"dark"}
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: ((processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

### Changes regarding the implementation of Custom Components

The support for classical **[Android View](https://developer.android.com/reference/android/view/View)** system has been dropped.\

A Custom Component can now be implemented only by using the **[Compose](https://developer.android.com/compose)** UI system.

This means that the `CustomViewComponent` is now ignored in the internals of the SDK and has been marked as `@Deprecated` and will be completely removed in the next release.

> [!NOTE]
>
> There is no immediate need to update any of the existing components.

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```kotlin theme={"dark"}
fun changeLocaleSettings(locale: Locale, language: String)
```

### Library dependencies updates

* **[Kotlin](https://kotlinlang.org/)**: 1.9.22 **↗** **1.9.24**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping)**: 2024.02.00 **↗** **2024.06.00**
* **[Compose Compiler](https://developer.android.com/jetpack/androidx/releases/compose-compiler)**: 1.5.9 **↗** **1.5.14**
* **[Gson](https://github.com/google/gson)**: 2.10.1 **↗** **2.11.0**

***

## iOS SDK migration guide

### Initialization config changes

A new configuration parameter, named `locale` was added to improve formatting the dates, numbers and currencies.

The locale needs to be set on the `FXConfig.sharedInstance.configure` method

```swift theme={"dark"}
FXConfig.sharedInstance.configure { (config) in
    config.locale = "en-US"
    ...
}
```

### Changes when starting a process

Two new parameters were added on the 3 available start process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectId` | The uuid string of the project containing the process to be started | `String` | Mandatory |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func startProcess(projectId: String, 
                  name: String, 
                  params: [String : Any]?, 
                  isModal: Bool = false, 
                  showLoader: Bool = false, 
                  completion: ((UIViewController?) -> Void)?, 
                  onProcessEnded: (() -> Void)? = nil)
```

### Changes when resuming a Flowx process

One new parameter was added on the 3 available continue process methods:

| Name | Description | Type | Requirement |
| - | - | - | - |
| `onProcessEnded` | Callback function where you can do additional processing when the started process ends | `(() -> Void)?` | Optional. It defaults to `nil`. |

```swift theme={"dark"}
func continueExistingProcess(uuid: String, 
                             name: String, 
                             isModal: Bool = false, 
                             completion: ((UIViewController?) -> Void)? = nil, 
                             onProcessEnded: (() -> Void)? = nil)
```

### Updated FXDataSource protocol

A new method has been added to the `FXDataSource` protocol. Update conformance to protocol by adding the implementation of the new func.

```swift theme={"dark"}
func newProcessStarted(processInstanceUuid: String) {
    
}
```

### Public API changes

The `changeLanguage` method has been updated and renamed to `changeLocaleSettings` to accommodate the newly added `locale` config parameter:

```swift theme={"dark"}
func changeLocaleSettings(locale: String?, language: String?)
```

***

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated and will use the latest versions Angular (version 19), thus all container apps that want to use the new SDKs should first update the Angular version of the container apps.

In the following we cover the migration guide for a container app from Angular v17 to v19 and the new SDKs.

**1. Remove old packages and their explicit dependencies (required dependency packages for new sdks are bundled in the libraries so we don't need)**

* remove `material-moment-adapter` unless it is used in custom components (usually together with material datepicker) and also the `moment` package (unless used elsewhere in the project )

```bash theme={"dark"}
npm uninstall @angular/material-moment-adapter
npm uninstall moment
```

* remove old FlowX SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/ui-sdk @flowx/ui-theme @flowx/ui-toolkit 
```

* in `angular.json` remove references to old stylesheets:

```bash theme={"dark"}
"./node_modules/@flowx/ui-sdk/src/assets/scss/style.scss"
"./node_modules/paperflow-web-components/src/assets/scss"
"./node_modules/@flowx/ui-sdk/src/assets/scss"
```

* remove old FlowX SDKs explicit dependencies. Please check before removing that packages are not used in the container app or custom components.

```bash theme={"dark"}
npm uninstall date-fns event-source-polyfill inputmask ng2-pdfjs-viewer vanillajs-datepicker @ngneat/input-mask deepmerge-ts marked-mangle
```

* remove deprecated `Angular Flex` library (the new sdks don't use it anymore and the package has been deprecated by the Angular team) unless it is not used in container app or custom components

```bash theme={"dark"}
npm uninstall @angular/flex-layout
```

**2. Update container app to Angular 18**

* Make sure to have the Angular CLI installed at version 18 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@18
```

* Run the Angular update for version 18

```bash theme={"dark"}
ng update @angular/core@18 @angular/cli@18
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@18
```

or, if the container app uses Angular Material, run:

```bash theme={"dark"}
ng update @angular/material@18
```

* Optionally, if your project uses other angular packages (ex. `NgRx`) please run migrations to v18 for each of them before proceeding. You can find details on the libraries documentation pages.

* Angular has changed the default build path in the `dist` folder, it now uses a `browser` folder for the build output. To place the output of the build command directly in the `dist/[APP_NAME]` folder, add the following change in `angular.json`:

```json theme={"dark"}
{
  ...
  "architect": {
    ...
    "build": {
      ...
      "options": {
        ...
        "outputPath": {
          "base": "dist/flowx-demo-app",
          "browser": "" <-- add this line
        },
      }
    }
  }
}

```

**3. Update container app to Angular 19**

* Make sure to have the Angular CLI installed at version 19 (check with `ng --version`)

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Run the Angular update for version 19

```bash theme={"dark"}
ng update @angular/core@19 @angular/cli@19
```

* Update Angular CDK or Angular Material

```bash theme={"dark"}
ng update @angular/cdk@19
```

or, if the container app uses Angular material, run:

```bash theme={"dark"}
ng update @angular/material@19
```

* Optionally, if your project uses other Angular packages (ex. `NgRx`) please run migrations to v19 for each of them before proceeding. You can find details on the libraries documentation pages.

* Also, it is recommended that you update the `target` and `module` settings in the `tsconfig.json` file to the new version, although be advised that this might require additional changes in the codebase due to new compilation errors that might arise.

```json theme={"dark"}
{
  ...
  "compilerOptions": {
      ...
      "target": "ES2022",
      "module": "ES2022"
  }
}
```

**4. Install the new FlowX SDK packages**

**Adding overrides for libraries that have a dependency on Angular version \< 19**

For some libraries, the required angular version might not be up to date or compatible with the new Angular version. In this case, you can add an override in the `package.json` file to force the library to use the new Angular version.

* For example, the `ng2-pdfjs-viewer` library has a dependency on Angular version 18 and will not work with the installed Angular version 19. To force the library to use the new Angular version, add the following override in the `package.json` file:

```json theme={"dark"}
{
  ...
  "overrides": {
    "ng2-pdfjs-viewer": {
      "@angular/common": "^19.0.0",
      "@angular/core": "^19.0.0",
      "ng-packagr": "^19.0.0"
    }
  }
}
```

**Install new packages**:

> [!WARNING]
>
> **ACTION REQUIRED**: Update to the latest version 4.6 to ensure optimal performance and compatibility.

```bash theme={"dark"}
npm install @flowx/core-sdk@5.63.0 @flowx/core-theme@5.63.0 @flowx/angular-sdk@5.63.0 @flowx/angular-theme@5.63.0 @flowx/angular-ui-toolkit@5.62.1 
```

* Install a type dependency for the SSE library:

```bash theme={"dark"}
npm install --save-dev @types/event-source-polyfill
```

* run through all the migration steps in the [New SDK Api changes](#new-sdk-api-changes) section below.

> [!NOTE]
>
> Each migration requires a 'clean' repository state. Make sure to commit all changes before starting the next migration step.

> [!TIP]
>
> After each Angular update it is recommended you restart your editor or TS Server, to use the new TS version since some import errors might appear.

### New SDK API changes

#### Renderer SDK component usage

In the Angular SDK, the `<flx-process-renderer>` component has two new parameters have been introduced: `projectInfo` and `locale`. These additions help support localization and project-specific configurations.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `projectInfo` | Object containing an `projectId` key, which identifies the project of the process to be started | `{projectId: string}` | Mandatory |
| `locale` | Provides region-specific settings for localization. | `string` | Mandatory |

Add the definitions for these properties in the class file of the component that uses the process renderer component:

```typescript theme={"dark"}
projectInfo = { projectId: 'your-project-id' },
locale = 'en-US',
```

Use these parameters in the template as inputs for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  ...
  [projectInfo]="projectInfo"
  [locale]="locale"
/>
```

#### API changes

Process Renderer:

| Category | Old Approach | New Approach |
| - | - | - |
| **Process Renderer** | `FlxProcessModule.forRoot({...})` | `FlxProcessModule.withConfig({...})` |

#### Import path updates

| Category | Old Approach | New Approach |
| - | - | - |
| **Import Paths** | `@flowx/ui-sdk` | `@flowx/angular-sdk` (or, in some cases `@flowx/core-sdk`) |
| | `@flowx/ui-theme` | `@flowx/angular-theme` |
| | `@flowx/ui-toolkit` | `@flowx/angular-ui-toolkit` |
| **Process Module** | `import {FlxProcessModule} from '@flowx/ui-sdk';` | `import {FlxProcessModule} from @flowx/angular-sdk` |
| **Localization Module** | `import {FlxLocalizationModule} from '@flowx/ui-sdk';`  Include in module imports | `import {FlxLocalizePipe} from '@flowx/angular-sdk';` Remove from module imports |
| **Task Management** | `import {FlxTaskManagementModule} from '@flowx/ui-sdk';` | `import {FlxTasksManagementComponent} from '@flowx/angular-sdk';` |
| **Client Store Interface** | `import {ClientStoreInterface} from '@flowx/ui-sdk';` | `import {ClientStoreInterface} from '@flowx/core-sdk';` |

> [!NOTE]
>
> You can also remove the `FlxLocalizationModule` from any `imports` arrays in modules, and import the `FlxLocalizePipe` instead

### Icon module update

The `withExtraIconSet` method has been replaced with `provideExtraIconSet`, which should now be used in the providers array.

```typescript theme={"dark"}
@NgModule({
  imports: [
    IconModule,  // Import the IconModule
  ],
  providers: [
    // Use provideExtraIconSet to add your custom icon set
    provideExtraIconSet({
      customIcon1: 'path/to/custom-icon1.svg',
      customIcon2: 'path/to/custom-icon2.svg',
      // Add more icons as needed
    })
  ]
})
export class AppModule {}
```

### Custom Interceptors

The new FlowX SDKs do not depend on Angular's `HttpClient` to make API calls, so existing interceptors must be adapted to a new format, for Request Interceptors (eg. custom headers) and Response Interceptors (eg. error handling)

For an overview of implementation details, please refer to the respective sections of the renderer documentation for the new API changes.

> [card] [Custom Interceptors](/4.7.x/sdks/angular-renderer#custom-interceptors)


# FlowX.AI 4.6.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.0-january-2025/v4.6.0-january-2025

Welcome, FlowX fam! The 4.6.0 update is here, and it’s packed with features designed to save you time, boost efficiency, and maybe even make you chuckle. Let’s dive into the details, feature by glorious feature. 🎉

## **What's new?** 🆕

### Projects: Order out of chaos

The new Project concept introduces a streamlined approach to managing and deploying complex projects within FlowX. By grouping all related resources—such as processes, enumerations, integrations, and assets—into a single, organized workspace, projects provide a cohesive view for efficient development and deployment.

![FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-23%20at%2017.33.16.png)

💼 **Key Benefits**:

* **Unified Workspace**: Group related processes, integrations, assets, and configurations into one tidy space.
* **Version Control**: Manage multiple builds and versions effortlessly. Rollbacks? No sweat.
* **Resource Sharing**: Reuse processes and configurations across projects like a boss.

> [!TIP]
>
> **Why you’ll love it**: It’s like going from a messy desk to an organized digital office.

🎥 **Quick Demo**: (Who needs text when you have visuals?)

<video />

> [card] [Projects](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

#### 🛠 Config vs Build Mode

**Config Mode**: Tinker, tweak, and perfect.

* Config mode is the environment where you set up, adjust, and manage your project's resources, processes, and configurations. It's the workspace where you fine-tune every aspect of the project before it's ready for deployment. Think of it as the design phase, where the focus is on setup, organization, and preparation.

**Build Mode**: Lock it, load it, deploy it.

* Build mode is the stage where the configurations you've set up are packaged into a deployable form. This is the runtime-ready version of your project, containing everything needed for it to function in a production environment. A build includes a snapshot of the project’s state at a given point, ensuring stability and predictability when deployed.

<video />

> [card] [Configuration](/4.7.x/docs/projects/managing-applications/application)
>
> For more details, check out this section

> [card] [Runtime](/4.7.x/docs/projects/runtime/builds)
>
> For more details, check out this section

***

### Integration Designer: Connect like a pro

It’s like a dating app for your systems: drag, drop, connect, and let the workflows flow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/intg_designer.png)

API integration just got easier! Integration Designer simplifies connecting FlowX with external systems using REST APIs.

✨ **The magic of it**:

* **Drag-and-Drop Interface**: Map data, define workflows, and configure endpoints like a breeze.
* **Flexible Authorization**: Use Service Tokens, Bearer tokens, or go authentication-free.
* **Error Management**: Built-in tools ensure your integrations don’t ghost you.

> [!TIP]
>
> **Fun Fact**: Integration Designer doesn’t just test APIs (we love you, [Postman](https://www.postman.com/)❤️). It automates workflows, saving you tons of time.

> [card] [Integration Designer](/4.7.x/docs/platform-deep-dive/integrations/integration-designer)
>
> For more details, check out this section

***

### Merge Conflicts 2.0: Merge without the drama

Merging branches? We've overhauled the process to make it faster, smarter, and far less painful.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png)

🧩 **What’s New**:

* **Advanced Conflict Detection**: Pinpoint issues by resource type (Processes, Enumerations, Media, etc.).

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png)

* **Resource-Level Resolution**: Resolve conflicts directly in the UI with:
  * JSON comparisons (color-coded for clarity!).
  * Navigation tools to jump between differences.
  * Progress tracking for reviewed items.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png)

Handle unresolved conflicts with the **Merge Anyway** option, which provides flexibility while maintaining control over outcomes:

> [!TIP]
>
> **Pro Tip**: Use the “Merge Anyway” option if you need to override unresolved conflicts (but use it wisely!).

* A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
* Allows merging to continue even when some conflicts remain unresolved.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png)

> [card] [Merge conflicts](/4.7.x/docs/projects/managing-applications/versioning#managing-conflicts)

***

### AI Agents: Smart, adaptable, always ready to help

FlowX AI Agents bring automation to your fingertips, powered by a flexible, LLM-agnostic core.

🤖 **Why It’s Cool**:

* Works with both open-source and private language models.
* Secure, on-premise deployments available.
* Automates business processes and interactions.

🎥 Check out a quick demo:

<video />

Stay tuned for more.

***

### Localization and Internationalization

FlowX is now more global-friendly with enhanced localization features.

> [card] Flexible Date, Time, Number, and Unit Formatting
>
> Enhanced formatting options for dates, times, numbers, and currencies with support for various international standards including short, medium, long, full, and custom formats.

> [card] Currency Customization
>
> Support for currency formatting with options to display values using ISO codes or symbols, adapting to user-selected locales and regional preferences.

> [card] Locale-Based Configurations
>
> Comprehensive settings for pluralization, capitalization, alignment, and sorting that adapt to regional requirements, helping cater to a diverse global user base.

> [card] Enhanced UI Component Formatting
>
> New options in the UI Designer to override general settings for text, messages, links, and form elements based on locale and region.

> [card] Document Localization
>
> Static and dynamically generated legal documents can now be customized based on regional and locale settings, improving compliance and communication with local audiences.

> [card] [Localization and internationalization](/4.7.x/docs/building-blocks/ui-designer/localization-and-i18n)
>
> For more details, check out this section

***

### Data Model 2.0: Data handling, but make it fashion

In this release, we've introduced Data Model 2.0, a major upgrade designed to simplify and enhance data handling. Key improvements include the introduction of reusable objects, a visual representation of complex data structures, and dynamic data binding, all aimed at creating a more reliable and intuitive experience. The new model ensures references are automatically updated when changes are made, streamlining data management across the platform.

**Highlights**:

* **New Root Element**: Provides a structural basis without impacting business logic, ensuring a clear and organized data structure.
* **Enhanced Data Binding**: Expanded to more areas, with dynamic updates based on changes in the data model.
* **Localization**: Added handling mechanism for locale-specific formatting, ensuring accurate data representation.

<video />

> [card] [Data model](/4.7.x/docs/building-blocks/process/data-model)
>
> For more details, check out this section

***

### Task management 2.0

We've enhanced Task Management capabilities, making it easier to create, track, and manage tasks efficiently. The updated Task Management features include customizable views and advanced filtering and sorting options for task data. Additionally, users can now implement both low-code and full-code solutions for a tailored Task Management experience, ensuring maximum flexibility for different business needs.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/views_task_manager.png)

> [card] [Task Management](/4.7.x/docs/platform-deep-dive/core-extensions/task-management/task-management-overview)
>
> For more details, check out this section

***

### UI Designer

#### Grid layout

We are excited to introduce the Grid Layout feature in this release, enhancing the flexibility and usability of the UI Designer for creating structured and responsive layouts. With the new Grid Layout, users can organize form elements, tables, and other components using a multi-column and row system, allowing for more complex, bidirectional designs compared to the previous flex-based layout.

<video />

> [accordion] This might happen after using it for the first time:
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/grid-layout-first-time.jpg)

#### Table

The Table component is a simple and flexible way to display data in web applications. It lets you customize columns, add pagination, sort and filter data, and apply your own styling. You can resize columns, scroll through data, and even add actions like editing or deleting rows directly in the table. It’s easy to set up, with default columns and rows generated automatically based on your data.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2024-12-23%2017.10.38.gif)

> [card] [Table](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/table)
>
> For more details, check out this section

#### FlowX.AI UI Designer new navigator

We are thrilled to introduce the new and improved **UI Designer Navigator**, a major update designed to streamline your UI design process.

> [card] Enhanced UI Layer Panel Design and Functionality
>
> The UI layer panel has been redesigned for a more intuitive experience, making it easier to manage and navigate through your design elements.

> [card] Improved Drag and Drop Experience
>
> Dragging and dropping components in the preview is now smoother and more precise, allowing for faster and easier creation of UIs.

> [card] Flexible Root Component Management
>
> You can now change the root component from a form group to a container or vice versa, offering greater flexibility when copying nodes or resolving configuration problems.

> [card] Clearer Component Hierarchy
>
> It is now simpler to identify where you are placing a component within the hierarchy, thanks to the enhanced drag/reorder functionality in the right panel.

<video />

#### Conditional formatting for UI elements

Dynamically update styling and properties of UI elements based on conditions, reducing the need for multiple prototypes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/image%20%2812%29.png)

> [!NOTE]
>
> Conditional styling is available for **text**, **link**, and **container** UI elements based on specific conditions.

#### Hide expressions enhancements

Expanded hide expressions functionality to include:

* Cards
* Collection prototypes and children
* Table cell children (e.g., texts, images, buttons, links)

#### UI actions

* Added a new UI action **Start new project instance**
* Removed the **Start Process Inherit** UI action type.

#### UI action form updates

* Introduced **Functional** and **UX sections** for all action types, with a checkbox for **Add Analytics Name** in the UX section.
* Simplified custom and exclude key management.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2015.20.01.png)

***

### Start new project instance action

We’ve introduced the Start New Project Instance node action, enabling users to initiate a completely new process from within an ongoing one. This functionality is perfect for scenarios where isolated use cases are managed across different projects or environments.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/start_new_project_instance.png)

> [card] [Start new project instance action](/4.7.x/docs/building-blocks/actions/start-new-project-instance)

***

### Custom components validation

You are able to validate and retrieve data from a generated screen, including data from a custom form section. Additionally, you’ll have the ability to trigger and manage data directly within that section. This will be a major benefit for clients who have chosen to create custom components for the entire screen (for example, a form that isn’t supported natively by the platform).

> [card] [Validating elements](/4.7.x/docs/building-blocks/ui-designer/ui-component-types/root-components/card#validating-elements)

***

### Autocomputed data to send

In previous platform versions, when creating your UI screens and working with data, you had to ensure that all the data stored in your process keys was saved in the process instance. This required adding an extra parameter called "Data to send" to the "Save Data" node action.

**Older versions** vs **v4.6.0**:

![older versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.x-aut.png)

![v.4.6](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/4.2-aut.png)

Now, with the autocompute feature, this step is no longer necessary, as the data is automatically saved and sent on your process instance.

> [!TIP]
>
> You no longer need to add "Save Data" node actions, but make sure to include "Forms to Validate" on the UI Actions. This helps ensure that data is submitted correctly and automatically activates any added validators where they exist.
>
> ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/forms_to_validate.png)

However, you still have the option to customize which keys are included or excluded as needed.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/include_exclude_keys.png)

***

### **Scripting UX Improvements**: *Write code like a wizard*

* **Autocomplete**: Get tailored suggestions based on your data model.
* **New Editors**: JSON and hide/disable expressions editors now include examples, syntax help, and better visual feedback.

<video />

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/post41/hide%3Adisable%20editor.png)

***

### React & Angular SDKs

Dev friends, we heard you. FlowX now integrates smoothly into your React and Angular apps. It’s like peanut butter and jelly, but make it code.

#### React SDK

With the 4.6.0 release, we're excited to announce the launch of the FlowX React SDK! This new SDK empowers developers to seamlessly integrate FlowX.AI capabilities into React applications, making it easier than ever to build highly interactive, responsive, and dynamic user experiences.

To get started, simply install the FlowX React SDK via npm and check our documentation for examples and best practices!

> [card] [React SDK](/4.7.x/sdks/react-renderer)

#### New Angular SDK

We're excited to announce new releases for FlowX packages to support web applications:

* `@flowx/core-sdk`
* `@flowx/angular-sdk`
* `@flowx/angular-theme`
* `@flowx/angular-ui-toolkit`
* `@flowx/core-theme`

> [!WARNING]
>
> We recommend upgrading to the **latest** versions of all @flowx packages to take full advantage of these new features and improvements. Check the deployment guidelines for version details.

> [card] [Angular SDK migration guide](migrating-from-v4.1.x-to-v4.6.0/renderers#angular-sdk-migration-guide)

***

### Analytics integration for Container Apps

Container apps now support tracking "Screen Displayed" and "Action Executed" events, configurable in the UI Designer to improve insights into user interactions.

**UI Designer updates**

* **Analytics Screen Name:** Configurable under Root UI components (Cards and Containers) to enable tracking in analytics platforms like Google Analytics.

> [!TIP]
>
> "Screen Displayed" events support user task-based reporting, such as when a user task screen is shown.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.01.58.png)

> [!NOTE]
>
> The configured values are stored in `flowxProps.analytics`, making them accessible for integration with analytics tools.

* **Action Analytics:** Tracks user actions (e.g., button clicks) with tags set directly in the UI Action Form.

> [!NOTE]
>
> Added analytics configuration in the **UX Section** for all UI action types.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202024-12-11%20at%2016.20.53.png)

> [!NOTE]
>
> Values are saved in `params.analytics` via the PATCH `/actions` request.

**Renderers updates**

Renderers now expose a public API for triggering analytics events:

* **Screen Events:** Triggered on user task display, using `flowxProps.analytics`.
* **Action Events:** Triggered on action execution, using `params.analytics`.

Dynamic values such as process store keys and replace tags are supported for more contextual tracking.

***

### Plugin updates

**Notifications** and **Documents** plugins have been integrated as **project resources**.

***

### Scheduled Processes: Timer management reimagined

We've completely redesigned how you manage timer-triggered processes. Before 4.6.0, timer activation was managed through a quick actions menu in process definition headers; now it's handled via dedicated UI section in the Runtime tab under Scheduled Processes.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/scheduled_processes.png)

🕒 Key Improvements:

* **Centralized Timer Management:** All process timers are now visible and manageable in one dedicated location
* **Persistent Settings:** Timer configurations persist across build exports/imports
* **Environment Control:** Activate or deactivate timers without redeploying your application

For more details, check out this section

> [card] [Scheduled Processes](/4.7.x/docs/projects/runtime/scheduled-processes)

## Bug fixes 🐞

### Rendering

* **Default Value Initialization for UI Elements**: Resolved an issue where certain UI elements were initialized with incorrect default values.

* **Improved Security for Hidden Fields**: Fixed a vulnerability where hidden fields could be accessed through browser developer tools.

* **Form Validation Reset on UI Dismissal**: Addressed an issue where form validation errors persisted after the UI was closed.

* **Keybinding Issues on Windows**: Fixed a bug where pressing specific keys triggered unintended operations in the designer.

* **Input Field Validation for Number Type**: Corrected the validation logic for number input fields to ensure consistent behavior.

* **Improved Datepicker Popup Positioning**: Resolved an issue where the datepicker popup overlapped the associated input field.

* **Manual Date Entry in Datepicker**: Fixed an issue where manually entering a date after selecting one from the datepicker caused errors.

* **Enhanced Update Mechanism for Custom Components**: Improved the reliability of updates for custom components to reflect changes consistently.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **New substitution tags with the same name on different branches aren’t flagged**: Merging branches that include new substitution tags with identical names on different branches does not trigger a conflict. Instead, both tags are retained, resulting in duplicate substitution tags with the same name but different values. This issue bypasses expected conflict detection and can lead to inconsistencies in substitution tag usage.
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] Notification and document templates
>
> * Branches with notification and document templates fail to merge into the main branch

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Changes 🔧

* **Web Renderer Caching:** Improved resource caching with browser mechanisms keyed to build IDs.
* **Process Designer:** Enhanced drag-and-drop functionality for node placement.

***

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.0](./deployment-guidelines-v4.6.0)

Migrating from v4.1.x:

> [card] [Migrating from v4.1.x to v4.6.0](./migrating-from-v4.1.x-to-v4.6.0/migrating-from-v4.1.x)

> [card] [Changes in process configuration](./migrating-from-v4.1.x-to-v4.6.0/process-configuration)

> [card] [Renderer SDKs](./migrating-from-v4.1.x-to-v4.6.0/renderers)


# Deployment guidelines v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/deployment-guidelines-v4.6.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.6.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.

## Component versions

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.1.1** | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.2.6** | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.69.3** | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.69.3** | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.69.3** | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.2** | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **license-core** | 4.1.3 | 4.1.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.5 | 1.1.0 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.7 | 1.0.4 | 1.0.2 | 1.0.2 | 1.0.2 | 1.0.1 |
| **task-management-plugin** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.0.4** | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.0.25** | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.4** | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.11** | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

> [!NOTE]
>
> Note: The same container image and Helm chart are used for **Application Manager** and **Runtime Manager**.

## AI Agents

| Component | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.16** | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.6.15** | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.6** | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.27** | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.6.5** | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Third-party recommended component versions

| FlowX.AI Platform Version | Component Name | Recommended Versions |
| - | - | - |
| 4.6.1 | Keycloak | 22.x |
| 4.6.1 | Kafka | 3.2.x |
| 4.6.1 | PostgreSQL | 16.2.x |
| 4.6.1 | MongoDB | 7.0.x |
| 4.6.1 | Redis | 7.2.x |
| 4.6.1 | Elasticsearch | 7.17.x |
| 4.6.1 | Oracle Database | 21C/ 21-XE |
| 4.6.1 | Angular (Web SDK) | 19.x |
| 4.6.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.


# Migrating from previous versions to v4.6.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/migrating-from-v4.1.x-to-v4.6.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.0 version, make sure to first review the migration guide for v4.6.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

If you're moving from v4.1.x to v4.6.1, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.6.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.6.x/v4.6.1-february-2025/v4.6.1-february-2025

FlowX.AI 4.6.1 is here with important fixes and improvements to keep things running smoothly. No new features this time—just focused updates to improve stability, fix bugs, and enhance overall performance. Simple, clean, and efficient.

## **What's new?** 🆕

### Rendering

**Form Elements** improvements:

* **Default Value Handling**: Defaults are applied only when no existing value is found, and set upon first display (with specific exceptions).
* **Data Consistency**: Form elements now save data in standardized formats based on type for improved reliability.
* **Smart Defaults**: Clear fallback behaviors for elements like switches, sliders, and checkboxes when no value is present.
* **Synchronized Inputs**: Linked form elements (e.g., input + slider) stay in sync with automatic value adjustments within set limits.
* **Dynamic Dependencies**: Form elements can dynamically adjust based on related components’ values for greater flexibility.

### Merge conflicts

* Improvement: merged version is now selected after a successful merge in versioning modal.

## Bug fixes 🐞

### Merge conflicts

* Fixed an issue that caused conflicts involving notification and document templates to fail.
* Fixed an issue where merges failed when a deleted configuration parameter was updated on a branch.
* Fixed an issue that resulted in duplicate substitution tag keys appearing in the merged version.
* Fixed an issue where merges failed due to the same dependency being added to both the source and target branches.
* Fixed issues related to workflow conflicts.

### Rendering

* Fixed an issue where documents from the media library were not loading correctly when added as a file preview in a user task.

### Integration Designer

* Fixed issue causing a 400 error when adding an enum mapper to the body tab due to incorrect data validation.
* Fixed issue where the last attribute in the objects table was not visible at higher zoom levels due to UI rendering constraints.

## Known issues 😢

We’re aware of a few quirks during merge conflicts and are working to fix them. Here’s a quick rundown:

> [accordion] Processes
>
> * After a merge, sequences without a connection to an end node may appear on the canvas in cases of conflicts related to deleted nodes in one of the versions. This may occur because the merge mechanism does not detect that a sequence needs to be deleted if, in the final version, the node remains deleted.
> * Navigation areas – After a merge, inconsistencies in the navigation areas hierarchy calculated during merging may result in navigation areas being hidden in the final merged version.
> * No merge conflict detected if a user task node is deleted in the source branch and its UI is modified in the destination branch.
> * Nodes may end up having two different outgoing sequences in certain scenarios: When a node is not connected to another node, and both the source and target branches define different sequences to different nodes, the merged version may contain both sequences. In particular, this may cause inconsistencies for boundary nodes, which cannot have multiple outgoing sequences.
> * Gateway nodes may lose some of their configurations during merging when conflicts arise.
> * Conflicts arising from moving nodes to different swimlanes in both the source and target branches are not detected correctly and result in a merge error.

> [accordion] Enumerations
>
> * **Duplicate content values can be created during merging**: Merging branches with enumeration updates can result in duplicate content values or child enums with the same code. This occurs when identical names are added to the same enum in different branches, bypassing backend validation. Instead of flagging a conflict, the merge proceeds, creating duplicate entries. This issue disrupts the expected uniqueness constraint for enumeration values.
> * **Enum content values might not save correctly in some cases**: In specific scenarios involving transformations of content values into child enums across branches, content values added in one branch may not appear after merging. Despite accepting changes from the branch where the content value was added, the merged version omits it, leading to incomplete or inconsistent enumeration data.

> [accordion] Conflict Detection Gaps
>
> * **Adding values to deleted data model keys does not raise conflicts**: When values are added to a data model key in one branch and the same key is deleted in another, merging does not generate a conflict. Instead, the added values from the first branch are silently lost in the merged version. This issue bypasses expected conflict detection, leading to data loss and inconsistencies in the resulting data model.

> [accordion] Media Library
>
> * Branches with media library assets sometimes fail to merge into the main branch: Merging branches with media library assets can result in a 500 Internal Server Error when changes to the same asset occur across multiple branches. This issue typically arises when one branch is merged into another, and then the combined branch is merged into the main branch. The failure occurs due to null parameter handling during the merge process, preventing the merge from completing successfully.

> [accordion] UI/UX
>
> * After a successful merge, the merged version is not selected in the versioning modal.
> * Some entries in the merge conflicts tree may show numbers instead of specific identifiers (e.g. forms);
> * **Unnecessary scrollbars appear in the merge modal for single items**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.
> * **Fields like `originalCreationTimestamp` and `flowxUuid` are incorrectly flagged as conflicts**: The merge conflict modal displays unnecessary scrollbars when only a single item is present in the list. This occurs in scenarios where media library assets with long keys are involved, creating a layout issue that affects the user interface. While functionality is not impacted, this visual inconsistency can reduce the overall user experience during conflict resolution.

## Additional information

For deployment guidelines and further details, refer to:

> [card] [Deployment guidelines v4.6.1](./deployment-guidelines-v4.6.1)

Migrating from v4.6.0:

> [card] [Migrating from previous versions](./migrating-from-v4.1.x-to-v4.6.1)


# Deployment guidelines v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/deployment-guidelines-v4.7.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.0 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.6.0.
>
> In version 4.7, the import-export functionality for application-version is no longer backward compatible.
>
> * Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
>
> * Similarly, zip files from earlier versions cannot be imported into 4.7.
>
> Note: Zip files for builds and specific resources remain unaffected.

## Component versions

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.3.1** | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.5.1** | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.80.6** | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.2.11** | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.2** | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.5** | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.0** | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.1** | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.2** | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.4** | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.4** | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.3** | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.2** | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.6.0** | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.1.0** | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.5** | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.12** | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.21** | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.7.2** | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.13** | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.31** | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.0** | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.0 | Keycloak | 22.x, 26.x |
| 4.7.0 | Kafka | 3.2.x |
| 4.7.0 | PostgreSQL | 16.2.x |
| 4.7.0 | Oracle Database | 21c, 23ai |
| 4.7.0 | MongoDB | 7.0.x |
| 4.7.0 | Redis | 7.2.x |
| 4.7.0 | Elasticsearch | 7.17.x |
| 4.7.0 | Angular (Web SDK) | 19.x |
| 4.7.0 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.0
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/migrating-from-v4.1.x-to-v4.7.0

> [card] Upgrading from an older version?

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.0-february-2025/v4.7.0-february-2025

FlowX.AI 4.7.0 is here to keep your projects vibing, your merges drama-free, and your configs under control—because struggling with your platform is *so* last season. 😎🔥

## What's new? 🆕

✅ Copy resources across projects\
✅ Duplicate resources (in the same project/library)\
✅ Resources usage tracking\
✅ Smarter merge conflict detection & resolution\
✅ Libraries can now define configuration parameters\
✅ Dynamic Kafka topics using configuration parameters

## Projects

### Copy resources across projects

Moving resources between projects is now **fast and seamless**. The new **Copy to Another Project** feature ensures all dependencies stay intact, eliminating the hassle of manual adjustments.

<video />

> [tab] How it works
>
> 1️⃣ **Select a destination** – Choose the target project or library.\
> 2️⃣ **Pick a branch (if applicable)** – For WIP versions, select the target branch.\
> 3️⃣ **Review dependencies** – The system displays referenced resources and validates dependencies.\
> 4️⃣ **Resolve identifier conflicts** – If an identifier already exists in the destination, you'll be prompted to either:
>
> * **Keep both** (create a duplicate)
> * **Replace** (overwrite the existing resource)
> * **Use destination** (retain the existing resource without copying)

> [tab] Why it’s better
>
> * **No broken references** – Everything stays connected.
> * **Auto-add missing dependencies** – No manual setup required.
> * **Works with WIP & committed versions (only from committed to WIP)** – Flexibility for your workflow.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.48.33.png)

> [card] [Copy resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Duplicate resources

> [tab] What you can duplicate
>
> The **Duplicate Resource** feature lets users create a copy of an existing resource within the same project or library version, streamlining workflows and ensuring quick reusability.
>
> <video />
>
> You can duplicate the following resources:
>
> * **Processes**
> * **Enumerations**
> * **Media files (including Global media library files)**
> * **Notification templates**
> * **Document templates**
> * **Views**

> [tab] How it works
>
> * **Duplicate options** are available from each resource’s three-dot menu (table row & secondary navigation).
> * When selected, a **"Duplicate" modal** opens with a prefilled name: *Copy of \[Resource Name]* (which can be edited).
> * **Cancel** to discard changes or **Duplicate** to create an exact copy in the same project/library version.
> * **Success confirmation:** The system navigates to the newly created resource and displays a success message.
> * **Error handling:** If a resource with the same name/key exists, users will be prompted to rename it before proceeding.

> [tab] Why it’s useful
>
> 💡 **Use cases:**
>
> * Quickly iterate on existing resources.
> * Reduce redundant manual setup.
> * Maintain consistency within projects.
> * Easily clone complex configurations for testing and modifications.

> [card] [Duplicate resources](../../4.7.x/docs/projects/resources#copy--duplicate-resources)
>
> Check this section for more details.

***

### Track where your resources are used

Monitoring your resources has never been simpler and more efficient. Stay on top of where and how they’re being used.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-02-24%2011.47.16.gif)

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-02-24%20at%2011.42.52.png)

> [card] [Process Usage](../../4.7.x/docs/projects/resources#process-usage)
>
> Track where a process is referenced, with a clear **Usage Overview modal** that dynamically updates when references change.

> [card] [Enumeration Usage](../../4.7.x/docs/projects/resources#enumeration-usage)
>
> See where enumerations are used across **UI, Data Models, Systems, and Workflows** before making changes.

> [card] [Media Library Usage](../../4.7.x/docs/projects/resources#media-library-usage)
>
> Identify **which UI elements reference media assets** so you don’t accidentally break designs.

📌 **Before deleting a resource, a confirmation modal lists all affected references. No more surprises!**

***

### Configuration parameters overrides

🔹 **Libraries can now define configuration parameters** to help test processes or workflows that use those parameters.

🔹 However, **libraries do not support overrides**.

* **Overrides for library config parameters must be done within a project** where the library is added as a dependency.
* **Overrides cannot be added in libraries directly.**

<video />

💡 **What this means:**

* Libraries provide **default values** for configuration parameters.
* Projects using those libraries **can override these values** as needed.
* This ensures **clear separation between library defaults and project-specific configurations** while maintaining flexibility.

> [!TIP]
>
> ✨ **Overrides take precedence** over library values—so you stay in control.

***

### Merge conflict enhancements

Merge conflicts are never fun, but at least now they’re **easier to handle**.

> [card] Better Conflict Detection
>
> 🚨 Prevents merging if identical resource identifiers exist in both branches (e.g., same name, key, or code).

> [card] Resizable Merge Conflict Tree
>
> 🖥️ Resize the merge conflict tree for better visibility and navigation.

> [card] New Conflict Type
>
> 📢 A new conflict detection system for parent changes/deletions in both branches.

***

## SDK changes

### Expose Enumerations API in Angular SDK

Developers can now dynamically retrieve enumerations via the Angular SDK, making it easier to use enums in custom components like dropdowns.

> [!TIP]
>
> How it Works?
>
> A new method in the Angular SDK allows direct access to enumerations, reducing manual imports and improving flexibility.

**Usage**

The `getEnumeration()` function returns key-value pairs that can be used in components that need enumeration data:

```typescript theme={"dark"}
getEnumeration(enumName: string): { value: string; label: string }[]
```

* `enumName` (string) – The name of the enumeration to retrieve (e.g., 'UserRoles', 'cities')
* Returns: An array of objects containing value-label pairs representing the requested enumeration

> [accordion] Example usage
>
> The enumeration service works seamlessly with Angular's resource API for reactive state management:
>
> ```typescript theme={"dark"}
> import { Component, effect, model, resource } from '@angular/core';
> import { getEnumeration } from '@flowx/angular-sdk';
>
> @Component({
>   selector: 'app-dynamic-enum-select',
>   template: `
>     <select>
>       @for (option of options.value(); track option.value) {
>         <option [value]="option.value">{{ option.label }}</option>
>       }
>     </select>
>
>     <button (click)="enumName.set('cities')">Load Cities</button>
>     <button (click)="enumName.set('countries')">Load Countries</button>
>   `
> })
> export class DynamicEnumSelectComponent {
>   // Create a signal to track the currently selected enum
>   enumName = model<string>('UserRoles');
>
>   // Use resource API to reactively load enumerations when enumName changes
>   options = resource({
>     request: this.enumName,
>     loader: ({ request: enumName }) => getEnumeration(enumName),
>   });
>
>   constructor() {
>     effect(() => {
>       if (this.options.isLoading()) {
>         console.log(`Loading enumeration: ${this.enumName()}`);
>       } else {
>         console.log(`Loaded enumeration: ${this.enumName()}`, this.options.value());
>       }
>     });
>   }
> }
> ```

***

## **Bug fixes** 🐞

✔️ Improved **merge conflict detection and resolution**\
✔️ Fixed **UI rendering issues**

***

## Changes

### Dynamic Kafka topics

FlowX 4.7.0 introduces **Dynamic Kafka Topics**, enabling more flexible and configurable messaging across processes.

🔹 **What’s new?**

* Use **Configuration Parameters** to dynamically assign Kafka topics in **Kafka Send** and **Kafka Receive** actions.
* Concatenate predefined parameters with process variables for **on-the-fly topic selection**.
* Reduce hardcoded values and **simplify environment-specific configurations**.

💡 **Why it matters:**

* Makes **Kafka integrations more scalable** across different deployments.
* Supports **multi-topic messaging** for different use cases without manual updates.
* Ensures better **reusability and maintainability** in process configurations.

📌 Check the [Kafka Send Action](../../4.7.x/docs/building-blocks/actions/kafka-send-action#dynamic-kafka-topics) section for setup details.

***

### Export/import compatibility

In version 4.7, the import-export functionality for application-version is no longer backward compatible.

* Zip files exported from version 4.7 cannot be imported into earlier FlowX versions.
* Similarly, zip files from earlier versions cannot be imported into 4.7.

> [!NOTE]
>
> Zip files for builds and specific resources remain unaffected.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.0](./deployment-guidelines-v4.7.0)\
📌 [Migration Guide (from v4.6.0)](./migrating-from-v4.1.x-to-v4.7.0)


# Deployment guidelines v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/deployment-guidelines-v4.7.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.1 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.1.

## Component versions

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.5.1** | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.7.6** | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.83.8** | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.3.3** | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.4** | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.7** | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.3** | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.4** | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.6** | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.6** | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.6** | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.5** | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.9** | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.9.4** | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.2** | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.7** | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.13** | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.27** | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.2** | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.17** | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.2.35** | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.4** | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.1 | Keycloak | 22.x, 26.x |
| 4.7.1 | Kafka | 3.2.x |
| 4.7.1 | PostgreSQL | 16.2.x |
| 4.7.1 | Oracle Database | 21c, 23ai |
| 4.7.1 | MongoDB | 7.0.x |
| 4.7.1 | Redis | 7.2.x |
| 4.7.1 | Elasticsearch | 7.17.x |
| 4.7.1 | Angular (Web SDK) | 19.x |
| 4.7.1 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.1
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/migrating-from-v4.1.x-to-v4.7.1

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.1 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.1-march-2025/v4.7.1-march-2025

FlowX.AI 4.7.1 brings enhanced resource navigation, better error detection, and workflow improvements to make your development journey even smoother! 🚀

## What's new? 🆕

✅ Enhanced resource usage tracking with direct navigation\
✅ Upgraded JavaScript support to ECMAScript 15 (2024) in Business Rules\
✅ Added Python 3 support with 3x performance improvement\
✅ Major performance enhancements for both design time and runtime\
✅ Security enhancements for runtime endpoints

## Projects

### Enhanced resource usage navigation

We've significantly improved how you navigate between resources and their references with direct navigation capabilities. Now you can easily jump from the usage tracking panel to the exact location where a resource is referenced.

<video />

> [tab] How it works
>
> 1️⃣ **Access resource usage** – View where a resource is being used through the usage panel.\
> 2️⃣ **One-click navigation** – Use the new redirect button to jump directly to the referenced location.\
> 3️⃣ **Missing resource detection** – Easily identify and fix missing resource references with clear indicators.

> [tab] Why it's better
>
> * **Faster troubleshooting** – Directly navigate to problem areas without manual searching.
> * **Improved productivity** – Less time spent hunting down references means more time building.
> * **Better error prevention** – Quickly spot and fix missing resources before they cause issues.

***

## Enhanced scripting capabilities

### ECMAScript 15 (2024) support for Business Rules

FlowX.AI 4.7.1 brings the latest JavaScript features to your business rules with an upgrade to ECMAScript 15 (2024).

> [tab] What's included
>
> * Access to the latest JavaScript language features
> * Modern syntax for cleaner, more maintainable rules
> * Enhanced tooling and IDE support

> [tab] Benefits
>
> * Write more concise and expressive business rules
> * Leverage modern JavaScript patterns and best practices
> * Improved developer experience with better IDE integration

> [!NOTE]
>
> **Important Configuration Note:** Nashorn engine remains the default runtime. To enable GraalJS support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Nashorn will be used.

### Python 3 support for Business Rules

We've upgraded our Python scripting capabilities to Python 3, delivering significant performance improvements while maintaining compatibility.

> [card] 3x Faster Execution
>
> Python scripts now run at least 3 times faster than with Python 2.7.

> [card] Modern Python Features
>
> Take advantage of Python 3's improved syntax, libraries, and security features.

> [!NOTE]
>
> **Important Configuration Note:** Python 2.7 remains the default runtime. To enable Python 3 support with its performance improvements, you must set the feature toggle `FLOWX_SCRIPTENGINE_USEGRAALVM` to `true` in the [**Process Engine configuration**](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup) and in the **AI Developer** (if used) agent configuration. If this configuration variable is missing or set to `false`, Python 2.7 will be used.

More details about the scripting capabilities can be found in the [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts) section.

***

## Performance improvements 🚀

We've made significant performance enhancements throughout the platform to make your development and runtime experience smoother and faster.

### Design time improvements

For large processes, you'll notice dramatic improvements:

| Operation | Improvement |
| - | - |
| Cloning a process | **5x faster** |
| Opening a process | **70x faster** |

### Runtime enhancements

Platform average response time has been **reduced by 20%** in our comprehensive benchmark\*.

> [!NOTE]
>
> \*The benchmark simulates a typical business process with a combination of user and service tasks. It includes rules that automate decision-making, as well as events for time-sensitive actions and communication. The process also covers various system functions, ensuring the platform can efficiently manage complex workflows with both individual and parallel tasks.

***

## Security enhancements 🔒

We've significantly improved platform security by implementing proper endpoint access controls and separation between internal and public-facing APIs.

> [card] Enhanced API Security
>
> Runtime execution proxy vulnerability addressed with comprehensive endpoint updates.

> [card] Access Control Improvements
>
> Better separation between design-time and runtime endpoints with proper access controls.

### Endpoint security updates

We've implemented a comprehensive security update for runtime endpoints to prevent potential proxy vulnerabilities:

* Redesigned API structure to separate internal (`runtime-internal`) from external-facing (`runtime`) endpoints
* Migrated design-time operations to use `runtime-internal` endpoints for enhanced security
* Moved specific management operations to dedicated `build-mgmt` endpoints
* Updated all API clients to use the new secure endpoints

> [!NOTE]
>
> **Important:** Make sure to update to the corresponding  version of the [**`flowx-admin`**](./deployment-guidelines-v4.7.1#component-versions) to benefit from these security enhancements.

### Enhanced resource caching in Angular SDK

The Angular SDK now includes an improved caching mechanism for CMS resources, optimizing loading times and performance. The cache parameter on the `flx-process-renderer` component allows developers to control caching behavior in different environments.

> [card] [Read about caching in Angular SDK](../../4.7.x/sdks/angular-renderer#caching)
>
> Find details on controlling CMS resource caching during development and production.

## **Bug fixes** 🐞

* Fixed various minor issues to improve overall stability
* Resolved some UI inconsistencies
* Addresses performance optimizations
* Fixed general usability issues

***

## **Additional information**

📌 [Deployment Guidelines v4.7.1](./deployment-guidelines-v4.7.1)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.1)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.10
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/deployment-guidelines-v4.7.10

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.3** | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.8** | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.6** | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.4** | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.5** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.4** | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.6** | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.4** | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.4** | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.3** | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.4** | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.6** | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.2** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.5** | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.32** | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.24** | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.10 | Keycloak | 22, 26+ |
| 4.7.10 | Kafka | 3.2 - 3.9 |
| 4.7.10 | PostgreSQL | 16 - 17 |
| 4.7.10 | OracleDB | 19c, 21c, 23ai |
| 4.7.10 | MongoDB | 7 - 8 |
| 4.7.10 | Redis | 7.2 - 8.0 |
| 4.7.10 | Elasticsearch | 7 - 8 |
| 4.7.10 | Angular (Web SDK) | 19.x |
| 4.7.10 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.10 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.10-november-2025/v4.7.10-november-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Updated Spring Boot to the latest release for enhanced security and performance\
✅ Updated Java libraries to fix vulnerabilities across all images\
✅ Selectors support for substitution tags across all platforms (Web, iOS, Android)\
✅ System substitution tags on all task management texts\
✅ CMS - Added system substitution tags with migration script support

### Security and Platform Updates

This release includes critical security updates to ensure your FlowX.AI platform remains secure and up-to-date:

* **Spring Boot Update**: Updated to the latest release on the 4.7.x LTS branch
* **Java Libraries Update**: Updated Java libraries to fix vulnerabilities across all LTS 4.7.x images

### Selectors Support for Substitution Tags

You can now use selectors with substitution tags when the source type is process data across all platforms (Web, iOS, and Android). This enhancement provides more flexibility in displaying dynamic content from your process data in selector components.

**Available on:**

* Angular Web Renderer
* React Web Renderer
* iOS Renderer

### System Substitution Tags for Task Management

Task management now includes comprehensive system substitution tags support:

* **Backend CMS**: Added system substitution tags with a migration script to help you transition existing content
* **Web Renderers**: System substitution tags are now available on all task management texts across Angular and React renderers
* This allows for more dynamic and flexible task management configurations

## Bug fixes

> [accordion] \[Designer] Error when copying/pasting nodes with misconfiguration
>
> Fixed an issue where attempting to copy and paste nodes with misconfigurations, or importing an app version/build with misconfigured nodes, would result in an error. The system now handles misconfigured nodes gracefully during these operations.
>
> **Issue**: Error when trying to copy and paste nodes with misconfiguration or import an app version/build with nodes with misconfigurations

> [accordion] \[React] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the React renderer.
>
> **Issue**: \[React] Card not expandable after finishing subprocess started from it

> [accordion] \[Angular] Card not expandable after finishing subprocess
>
> Resolved an issue where cards would not be expandable after finishing a subprocess that was started from the card in the Angular renderer.
>
> **Issue**: \[Angular] Card not expandable after finishing subprocess started from it

> [accordion] \[React] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the React renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[React] Card shouldn't collapse when next nav area is modal

> [accordion] \[Angular] Card collapse behavior with modal navigation
>
> Fixed an issue where cards would collapse inappropriately when the next navigation area is a modal in the Angular renderer. Cards now maintain their expanded state correctly in these scenarios.
>
> **Issue**: \[Angular] Card shouldn't collapse when next nav area is modal

> [accordion] \[Backend] Task Manager - System substitution tags not displayed in column names
>
> Fixed an issue where system substitution tags were not being displayed in the `columns.displayName` property of the Task Manager backend.
>
> **Issue**: \[BE] Task manager | System substitutionTags are not displayed in columns.displayName

> [accordion] \[Web Renderers] Task Manager - Substitution tags value override
>
> Resolved an issue where system substitution tags values were incorrectly overriding custom substitution tags when the value was not null in both React and Angular renderers.
>
> **Issue**: \[React]\[Angular] Task manager | System subTags values override de custom subTags when value is not null

> [accordion] \[Task Manager] Missing localization for Russian and Uzbek in table view
>
> Fixed localization support in Task Manager table view for Russian and Uzbek languages, ensuring proper display of translated content.
>
> **Issue**: \[Task manager localisation] Table view - Missing localisation support for Russian and Uzbek

> [accordion] \[Task Manager] View search field placeholder not localized
>
> Resolved an issue where the view search field placeholder in Task Manager was not being localized for any language. The placeholder now properly supports all configured languages.
>
> **Issue**: \[Task manager localisation] View search field placeholder not localised for any language


# Deployment guidelines v4.7.11
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/deployment-guidelines-v4.7.11

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.6** | 8.24.3 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.12** | 7.18.8 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.9** | 5.11.6 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.7** | 5.7.4 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.8** | 6.8.5 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.7** | 6.10.4 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.9** | 7.9.6 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.7** | 6.8.4 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.7** | 4.7.4 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.6** | 2.16.3 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.7** | 2.23.4 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.9** | 2.10.6 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.103.6** | 5.101.2 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.103.6** | 5.103.5 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.32 | 4.0.32 | 4.0.30 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.27** | 4.0.26 | 4.0.26 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.11 | 4.7.10 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.25** | 1.8.24 | 1.8.23 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.11 | Keycloak | 22, 26+ |
| 4.7.11 | Kafka | 3.2 - 3.9 |
| 4.7.11 | PostgreSQL | 16 - 17 |
| 4.7.11 | OracleDB | 19c, 21c, 23ai |
| 4.7.11 | MongoDB | 7 - 8 |
| 4.7.11 | Redis | 7.2 - 8.0 |
| 4.7.11 | Elasticsearch | 7 - 8 |
| 4.7.11 | Angular (Web SDK) | 19.x |
| 4.7.11 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.11 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.11-december-2025/v4.7.11-december-2025

Security and maintenance updates for the 4.7.x LTS release

## What's new?

This is a **security and maintenance release** for the FlowX.AI 4.7.x LTS branch, focused on keeping your platform secure and up-to-date with the latest security patches.

✅ **Security Updates** - Updated core libraries and dependencies to address known vulnerabilities\
✅ **Platform Stability** - Improved overall platform security and stability

***

## Migration notes

> [!WARNING]
>
> As this is a **patch release** on the 4.7.x LTS branch, it is designed to be a **drop-in replacement** with no breaking changes.

***

## Component versions

All FlowX.AI components have been updated to version **4.7.11** with the security patches applied. Refer to the deployment guidelines for the complete list of component versions.


# Deployment guidelines v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/deployment-guidelines-v4.7.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.2 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.2.

## Component versions

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.9.0** | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.5** | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.84.5** | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.8** | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.10** | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.16** | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.12** | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.13** | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.14** | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.13** | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.14** | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | **0.2.0** | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.12** | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.3.16** | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.10.9** | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.9** | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.35** | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.9** | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.24** | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.1** | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.9** | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.2 | Keycloak | 22.x, 26.x |
| 4.7.2 | Kafka | 3.2.x |
| 4.7.2 | PostgreSQL | 16.2.x |
| 4.7.2 | Oracle Database | 21c, 23ai |
| 4.7.2 | MongoDB | 7.0.x |
| 4.7.2 | Redis | 7.2.x |
| 4.7.2 | Elasticsearch | 7.17.x |
| 4.7.2 | Angular (Web SDK) | 19.x |
| 4.7.2 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## Additional configuration

Added new environment variable on Process Engine:

### Message routing configuration

| Environment variable | Description | Default value |
| - | - | - |
| `KAFKA_DEFAULT_FX_CONTEXT` | Default context value for message routing when no context is provided | `""` (empty string) |

> [!NOTE]
>
> When `KAFKA_DEFAULT_FX_CONTEXT` is set and an event is received on Kafka without an fxContext header, the system will automatically apply the default context value to the message.


# Migrating from previous versions to v4.7.2
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/migrating-from-v4.1.x-to-v4.7.2

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.0 and v4.7.1 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.2 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.2-march-2025/v4.7.2-march-2025

FlowX.AI 4.7.2 delivers improved merge conflict handling with retry capabilities, deprecates DMN business rules, and fixes issues with subprocess handling, media file imports, and OCR functionality to enhance your development workflow! 🚀

## **What's new? 🆕**

✅ Improved merge conflict handling with retry functionality\
✅ Enhanced error messages during failed merges\
✅ Streamlined workflow for resolving merge conflicts

## Merge conflicts

### Improved error messages when merge fails

We've enhanced the merge conflict resolution experience with more informative error messages and a new retry functionality:

* When a merge fails, users can now see a "Retry merge" button on the Merge failed modal
* Clicking this button allows users to attempt the merge again without losing previous work

The system now handles two distinct scenarios:

**1. When conflicts exist:**

* The system opens the Merge conflicts panel with the previous state of the merge before the failed attempt
* This preserves all your conflict resolution work so you can fix the specific issues that caused the failure

![Merge failed with conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20conflicts.png)

**2. When no conflicts exist:**

* The system automatically retries the merge operation
* This streamlines the workflow when the merge failure was due to temporary issues rather than actual conflicts

![Merge failed without conflicts](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/If%20no%20conflicts.png)

## Process engine

### Deprecated DMN rules

In version 4.7.2, we've deprecated the **DMN (Decision Model and Notation)** business rule actions. This change affects how business rules are configured on task/user task nodes in business processes.

**What's changing:**

* DMN is no longer available as a language option when configuring business rule actions

**What's next:**
For guidance on using alternative business rule languages, please refer to our [supported scripting languages](../../../../4.7.x/docs/building-blocks/supported-scripts) documentation.

## **Bug fixes** 🐞

* Resolved export/import issues with media library files, particularly for applications migrated from earlier versions
* Fixed an issue where parallel multi-instance Call Activity would incorrectly trigger a subprocess when using an empty array list as a variable
* Fixed a display issue where not all subprocesses were visible in the subprocess list on smaller screens
* Fixed a bug where message events couldn't be caught when placed directly after an uninterrupting timer event
* Resolved "Unsupported Media Type" errors when importing application versions with media file binaries
* Fixed an issue where color palette changes in Theme settings couldn't be saved at 100% browser resolution on smaller screens
* Fixed a issue where OCR plugin failed due to missing correlation headers

***

## **Additional information**

📌 [Deployment Guidelines v4.7.2](./deployment-guidelines-v4.7.2)\
📌 [Migration Guide (from v4.7.0)](./migrating-from-v4.7.0-to-v4.7.2)\
📌 [Supported scripting languages](../../4.7.x/docs/building-blocks/supported-scripts)


# Deployment guidelines v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/deployment-guidelines-v4.7.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.3 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.3.

## Component versions

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.13.0** | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.8.13** | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.91.2** | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.12** | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.11** | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.17** | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.13** | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.16** | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.15** | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.14** | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.15** | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.14** | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.6.0** | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.14.0** | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.2.11** | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.14** | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.15** | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.37** | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.12** | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.26** | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.3** | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.11** | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.3 | Keycloak | 22.x, 26.x |
| 4.7.3 | Kafka | 3.2.x |
| 4.7.3 | PostgreSQL | 16.2.x |
| 4.7.3 | Oracle Database | 21c, 23ai |
| 4.7.3 | MongoDB | 7.0.x |
| 4.7.3 | Redis | 7.2.x |
| 4.7.3 | Elasticsearch | 7.17.x |
| 4.7.3 | Angular (Web SDK) | 19.x |
| 4.7.3 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.3
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/migrating-from-v4.1.x-to-v4.7.3

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.3 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.3-april-2025/v4.7.3-april-2025

FlowX.AI 4.7.3 enhances workflow conflict resolution, adds configurable enumeration ordering, and fixes data streams, UI templates, and application export/import issues to improve your development experience! 🚀

## **What's new? 🆕**

✅ Enhanced workflow conflict resolution with improved visibility\
✅ Added ability to configure order attributes on enumerations\
✅ Upgraded conflict management interface for better user experience

## Merge conflicts - workflow improvements

### Enhanced workflow conflict resolution

We've significantly improved how [**workflow**](../../4.7.x/docs/platform-deep-dive/integrations/integration-designer#workflows) conflicts are handled in this release:

* Upgraded to a new version (v2) of the workflow conflict resolution interface
* Now only showing workflow entities that have actual conflicts, making it easier to identify and address issues
* Streamlined the conflict resolution process for a more efficient workflow

![Workflow conflict resolution](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/workflow_conflicts.png)

> [!NOTE]
>
> **Important note about sequence conflicts:**
>
> When resolving conflicts related to sequences, if you select one of the conflicting sequences, nodes that are no longer connected may remain "orphaned" on the canvas in the merged version. This design decision was made to prevent accidental node deletion. If these orphaned nodes are no longer needed, they can be manually removed in subsequent versions.

## Configurable enumeration ordering

You can now configure the **Order** attribute on enumerations, giving you greater control over how enumeration values are displayed in dropdown lists:

* Set specific order values for each enumeration entry
* Control the presentation sequence in UI components
* Improve user experience by arranging options in logical or prioritized order

![Enum order](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/enum_order.png)

> [!NOTE]
>
> **Limitation:** When changing the order value for an enumeration entry, the system does not automatically update the order values of other entries. You'll need to manually adjust the order values of other entries in the interface.

## **Bug fixes** 🐞

* Fixed an issue where workflow nodes could have two output sequences
* Resolved a problem with enumerations displaying in the wrong order in dropdown lists
* Fixed an authentication issue where users would receive 401 unauthorized errors when executing actions after token refresh
* Fixed a UI behavior issue where slider actions configured with "onChange" were incorrectly triggered when entering a screen instead of only when modified
* Fixed an issue with identical advancing IDs occurring in multi-pod deployments due to missing hostname command in GraalVM docker images
* Resolved an issue preventing media library migration from default application
* Fixed the "Go to reference" functionality from data model attributes that was not correctly redirecting to referenced elements
* Fixed an error during application export/import where "There already exists a tagged build for this project version" was preventing successful imports
* Restored support for multiple topics in Data Stream Topics feature, which was previously only listening to the first topic in the list
* Fixed a 500 error that occurred when attempting to create child actions on certain nodes
* Fixed a critical issue where UI templates would disappear when creating a new version of an application after performing undo operations on pasted templates
* Fixed a bug where updates to the subprocess in a Start subprocess action weren't being saved properly
* Fixed an issue with the "Send email" button remaining disabled in the Test notification template feature after correcting validation errors
* Fixed an error that occurred when trying to export document templates containing null values in templateMap
* Fixed a display issue where Tokens, Workflows, and Subprocesses information wasn't showing in process instances after migration from 4.7.1 to 4.7.2
* Fixed a UI issue where business rule code wasn't displayed when testing business rules in committed versions

***

## **Additional information**

📌 [Deployment Guidelines v4.7.3](./deployment-guidelines-v4.7.3)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.3)


# Deployment guidelines v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/deployment-guidelines-v4.7.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.4 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.4.

## Component versions

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.15.2** | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.9.2** | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.93.1** | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.4.16** | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.0.13** | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.0.19** | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.1.15** | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.3.18** | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.2.17** | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.0.16** | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.0.17** | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.0.16** | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.7.2** | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.15.6** | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.3.2** | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.19** | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.23** | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.39** | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.17** | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.28** | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.5** | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.13** | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Recommended Supported Version |
| - | - | - |
| 4.7.4 | Keycloak | 22.x, 26.x |
| 4.7.4 | Kafka | 3.2.x |
| 4.7.4 | PostgreSQL | 16.2.x |
| 4.7.4 | Oracle Database | 21c, 23ai |
| 4.7.4 | MongoDB | 7.0.x |
| 4.7.4 | Redis | 7.2.x |
| 4.7.4 | Elasticsearch | 7.17.x |
| 4.7.4 | Angular (Web SDK) | 19.x |
| 4.7.4 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports the Recommended Versions of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest Recommended Versions. While exploring alternative versions that suit your company's specific requirements, we recommend referring to the table above for guidance.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

### Deprecation notice

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4

## **Additional information**

* Added new environment variable `OPTIMISTIC_LOCKING_RETRIES` to control the number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

Elasticsearch indexing configuration:

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)


# Migrating from previous versions to v4.7.4
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/migrating-from-v4.1.x-to-v4.7.4

> [card] Upgrading from an older version?

If you're upgrading from a v4.7.0 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.4 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.4-may-2025/v4.7.4-may-2025

FlowX.AI 4.7.4 enhances system stability with Spring Boot updates and resolves critical issues across build exports, reporting, SDK functionality, and cross-platform consistency to deliver a more reliable development experience! 🚀

## **What's new? 🆕**

✅ Platform enhancements\
✅ Added retry mechanism for ES indexing to handle key‑identifier errors\
✅ Fixed critical build export timeout issues\
✅ Improved reporting data representation\
✅ Enhanced cross-platform consistency

### Platform Enhancements ⚙️

* Enhanced system stability
* Latest security patches
* Improved performance

### Elasticsearch indexing - configurable retry mechanism

* `OPTIMISTIC_LOCKING_RETRIES`: Number of times the engine will retry indexing when it encounters concurrent-update errors specifically on key identifiers during their update after an action.

> [card] [Elasticsearch indexing configuration](../../4.7.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing#configuration)

### Data-sync run status monitoring

* Added the ability to view the run status of data-sync jobs directly in the platform interface
* Monitor the execution status of all data-sync jobs from the Jobs dashboard
* Quickly identify failed jobs for faster troubleshooting

![Data-sync run status monitoring](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/Screenshot%202025-05-20%20at%2010.55.19.png)

## **Bug fixes** 🐞

* **Build export timeouts**: Resolved intermittent timeout failures on projects with dependency libraries; exports now consistently complete or retry correctly.
* **Build creation on merge without conflicts**: Fixed an issue where merging one branch into another without conflicts—and switching the active policy—did not trigger a new build, forcing users to manually create a version; now, merges automatically update build resources and create the new version so merged changes appear at runtime.
* **Project version import stashing conflict**: Resolved an error where importing a branched project version across environments would inadvertently stash other versions—restoring successful import, fixing the GET history API response, and ensuring the Project versions history modal renders correctly.
* **CosmosDB workflows**: Fixed an issue preventing the workflow instances list from loading in the Integration Designer when using CosmosDB.
* **Reporting arrays**: Corrected array formatting in the `reporting_data` table (process-engine schema).
* **CMS permissions**: Restored backward compatibility for FlowX SDK v4.7+ by removing the unintended `media_library_read` requirement for processes containing images (behavior now matches v4.1).
* **onChange action behavior**: Standardized onChange/onBlur across web, Android, and iOS so users cannot continue typing after token advancement unless explicitly allowed.
* **React SDK ternary expressions**: Fixed an “Invalid Expression” error in SDK v5.86.1—ternary expressions in computed values (e.g. `return ${var1} ? "Onboarded" : (${var2} ? "Non-eligible" : "Ready for Onboarding");`) now parse correctly as they did in v5.62.1.
* **Elasticsearch indexing**: Fixed an issue where the engine was not retrying to index process instances when it encountered concurrent-update errors on key identifiers.
* **iOS SSE token refresh**: Fixed an issue in iOS SDK where Server-Sent Events connections would occasionally use expired JWT tokens instead of refreshed ones, causing 401 errors and process hangs in production environments.

***

## **Additional information**

📌 [Deployment Guidelines v4.7.4](./deployment-guidelines-v4.7.4)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.4)


# Deployment guidelines v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/deployment-guidelines-v4.7.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> After upgrading to the 4.7.5 FlowX.AI release, you cannot import old process definitions or resources from versions older than 4.7.5.

## Component versions

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.17.0** | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.12.2** | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.95.1** | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.5.1** | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.1.1** | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.1.1** | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.2.1** | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.4.1** | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.3.1** | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.1.1** | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.1.1** | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.9.0** | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.17.2** | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.4.1** | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.21** | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.24** | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.18** | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.5 | Keycloak | 22, 26+ |
| 4.7.5 | Kafka | 3.2 - 3.9 |
| 4.7.5 | PostgreSQL | 16 - 17 |
| 4.7.5 | Oracle Database | 21c, 23ai |
| 4.7.5 | MongoDB | 7 - 8 |
| 4.7.5 | Redis | 7.2 - 8.0 |
| 4.7.5 | Elasticsearch | 7 - 8 |
| 4.7.5 | Angular (Web SDK) | 19.x |
| 4.7.5 | React (Web SDK) | 18.x |

> [!NOTE]
>
> **New in 4.7.5: Support for more 3rd Party Dependencies**
>
> FlowX.AI 4.7.5 introduces support for more versions of third-party dependencies:
>
> * All versions are officially supported throughout the entire LTS lifetime
> * Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major release
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4


# Migrating from previous versions to v4.7.5
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/migrating-from-v4.1.x-to-v4.7.5

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.5 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.5 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.5-june-2025/v4.7.5-june-2025

FlowX.AI 4.7.5 enhances system stability with introducing support for more 3rd party dependency and introduces High Availability improvements with Redis Sentinel mode support to deliver a more reliable and scalable development experience! 🚀

## **What's new? 🆕**

✅ **Platform enhancements**\
✅ **Analytics enhancements**

### Platform enhancements ⚙️

**Extended Third-Party Dependency Support** - Introducing support for more versions of third-party dependencies:

* All versions are officially supported throughout the entire LTS lifetime
* Upgrades can be performed during the LTS lifetime to prepare for the minimum requirements of the next FlowX.AI major releases for critical infrastructure components, ensuring all supported versions are officially maintained throughout the entire LTS lifetime. This enables organizations to perform gradual dependency upgrades during the LTS period, preparing infrastructure to meet the minimum requirements for the next FlowX.AI major release while maintaining full platform support and stability.

### Analytics enhancements ⚙️

* Improved analytics events with enriched metadata for action events across all platforms (Web, iOS, Android). Action events now include screen context, component type identification, and component labels, providing deeper insights into user interactions and enabling more granular analytics tracking for better user experience optimization.

More details:

> [card] [Angular Renderer](../../../../4.7.x/sdks/angular-renderer#analytics)

> [card] [React Renderer](../../../../4.7.x/sdks/react-renderer#analytics)

> [card] [iOS Renderer](../../../../4.7.x/sdks/ios-renderer#collecting-analytics-events)

> [card] [Android Renderer](../../../../4.7.x/sdks/android-renderer#collecting-analytics-events)

### Runtime Manager deployment changes

> [!NOTE]
>
> **Prior to 4.7.5:** Runtime Manager was deployed using `application-manager` chart/image with manual `SPRING_APPLICATION_NAME`: "runtime-manager" configuration.
> Starting with 4.7.5: Runtime Manager has its own dedicated chart and image with proper defaults.

> [!TIP]
>
> Migration Required

* Switch to new chart: Use runtime-manager chart instead of application-manager
* Verify image: Ensure image name is runtime-manager (default in new chart)
* Remove override: `SPRING_APPLICATION_NAME`: "runtime-manager" can be removed (optional)

> [!WARNING]
>
> You may need to delete the existing runtime-manager deployment before upgrading due to Kubernetes label changes that cause `kubectl apply` to fail.

## **Bug fixes** 🐞

* **Fixed Task Manager loading issue with data type changes** - Resolved critical issue where Task Manager would fail to load and throw `NullPointerException`   when process variables were changed from date to string data types, even after updating the data model and clearing cache
* **Fixed All Tasks view missing on build import** - Resolved issue where importing builds from one environment to another would fail to create the All Tasks view, when accessing the Task Manager area
* **Fixed unassign operation causing runtime errors** - Resolved 500 Internal Server Error when accessing process data after performing unassign operations via Kafka messages, where null ownerDetails would cause `NullPointerException` during JSON serialization
* **Fixed CMS-Core export failures with AWS S3 buckets** - Resolved issue where CMS-Core would add double slashes in S3 object paths when creating exports, causing 404 NoSuchKey errors with AWS S3 (while working correctly with MinIO). Fixed path construction to ensure compatibility with both AWS S3 and MinIO storage backends
* **Fixed active policy version resolution** - Resolved issue where importing application versions to environments with existing WIP versions would incorrectly activate the stashed WIP version instead of the imported committed version, causing graph display failures and incorrect active policy settings

***

## **Additional information**

📌 [Deployment Guidelines v4.7.5](./deployment-guidelines-v4.7.5)\
📌 [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.5)


# Deployment guidelines v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/deployment-guidelines-v4.7.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.6 will permanently prevent you from importing process definitions and resources created in versions 4.7.5 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

> [!WARNING]
>
> **Audit data retention change**
>
> Starting with FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. In 4.7.5 and earlier, the service created this policy only once, on the first installation.
>
> The policy it writes has a single hot phase that rolls the audit data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. The default is `30` days; in 4.7.5 and earlier, the rollover period was a fixed 1 day.
>
> Any phase you added to this policy directly in Elasticsearch, such as a delete phase, is removed the next time the Audit service starts. Without a delete phase, old audit indices are never deleted and audit storage keeps growing.
>
> To keep the previous daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1` on the Audit service.

## Component versions

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.21.1** | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.15.2** | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/angular-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.96.1** | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.8.2** | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.4.0** | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.4.0** | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.5.0** | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.7.0** | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **task-management-plugin** | **7.6.0** | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.5.0** | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |
| **advancing-controller** | **4.4.0** | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.13.0** | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.20.2** | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.7.1** | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **iOS renderer** | **4.0.29** | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

## AI Agents

| Component | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.19** | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.6 | Keycloak | 22, 26+ |
| 4.7.6 | Kafka | 3.2 - 3.9 |
| 4.7.6 | PostgreSQL | 16 - 17 |
| 4.7.6 | OracleDB | 21c, 23ai |
| 4.7.6 | MongoDB | 7 - 8 |
| 4.7.6 | Redis | 7.2 - 8.0 |
| 4.7.6 | Elasticsearch | 7 - 8 |
| 4.7.6 | Angular (Web SDK) | 19.x |
| 4.7.6 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8

## Configuration Parameters

Starting with FlowX.AI 4.7.6, Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment.

> [card] [Integration Designer setup](/4.7.x/setup-guides/integration-designer-setup#configuration-parameters)

> [card] [Process Engine setup](/4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#configuration-parameters)

> [card] [Application Manager setup](/4.7.x/setup-guides/application-manager)


# Migrating from previous versions to v4.7.6
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/migrating-from-v4.1.x-to-v4.7.6

> [card] Upgrading from an older version?

If you're upgrading from a \< v4.7.6 version, make sure to first review the deployment guidelines for v4.7.x release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.7.6](../v4.7.6-july-2025/deployment-guidelines-v4.7.6)

> [card] [Deployment guidelines v4.7.5](../v4.7.5-july-2025/deployment-guidelines-v4.7.5)

> [card] [Deployment guidelines v4.7.4](../v4.7.4-may-2025/deployment-guidelines-v4.7.4)

> [card] [Deployment guidelines v4.7.3](../v4.7.3-april-2025/deployment-guidelines-v4.7.3)

> [card] [Deployment guidelines v4.7.2](../v4.7.2-march-2025/deployment-guidelines-v4.7.2)

> [card] [Deployment guidelines v4.7.1](../v4.7.1-february-2025/deployment-guidelines-v4.7.1)

> [card] [Deployment guidelines v4.7.0](../v4.7.0-february-2025/deployment-guidelines-v4.7.0)

If you're upgrading from a v4.6.x version, make sure to first review the migration guide for v4.6 release documentation to capture all the significant changes and also the deployment guidelines:

> [card] [Deployment guidelines v4.6.0](../v4.6.0-january-2025/deployment-guidelines-v4.6.0)

> [card] [Deployment guidelines v4.6.1](../v4.6.1-february-2025/deployment-guidelines-v4.6.1)

If you're moving from v4.1.x to v4.7.0, don’t forget to check the relevant migration guides for each version to ensure nothing is missed:

> [card] [Migrating from v4.1.x to v4.6.0](../v4.6.0-january-2025/migrating-from-v4.1.x-to-v4.6.0/)

> [card] [Migrating from v4.1 to v4.1.1](../v4.1.1-june-2024/migrating-from-previous-to-v4.1.1/)

Do not also forget to check all the deployment guidelines in between releases to do not miss important configurations or changes:

> [card] [Deployment guidelines v4.1.2](../v4.1.2-june-2024/deployment-guidelines-v4.1.2)

> [card] [Deployment guidelines v4.1.3](../v4.1.3-august-2024/deployment-guidelines-v4.1.3)

> [card] [Deployment guidelines v4.1.4](../v4.1.4-september-2024/deployment-guidelines-v4.1.4)

> [card] [Deployment guidelines v4.1.5](../v4.1.5-september-2024/deployment-guidelines-v4.1.5)


# FlowX.AI 4.7.6 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.6-july-2025/v4.7.6-july-2025

This release includes significant improvements to logging configuration and resolves some issues across the Designer, Process Engine, and Integration Designer components.

> [!WARNING]
>
> Upgrading to 4.7.6 changes how the Audit service manages its Elasticsearch lifecycle policy: the policy is rewritten on every startup and the default rollover period changes from 1 day to 30 days. See the [Deployment guidelines](./deployment-guidelines-v4.7.6) before upgrading.

## **What's new? 🆕**

> [card] Improved default logging configuration
>
> Changed logging verbosity to reduce clutter & log sizes, increasing visibility for more relevant log messages.

> [card] Improved the ability to use deployment specific variables as Configuration Parameters (at process runtime)
>
> Now Configuration Parameters can use values from Environment Variables, Kubernetes Config Maps, and Kubernetes Secrets, as configured in the deployment. Check the [**Deployment Guidelines**](./deployment-guidelines-v4.7.6#configuration-parameters) for more details.

> [card] Improved runtime performance
>
> Improved runtime performance by better distributing the execution of nodes across all components.

> [card] Improved the speed of listing process instances
>
> Improved the speed of listing process instances by 4-6x on environments with a lot of process executions.

> [card] Added the ability to change logging levels at runtime
>
> This feature allows you to dynamically adjust logging levels without requiring a service restart, providing more flexibility in managing log output.

> [card] Reduced config deployment complexity
>
> The previously used `CONFIG_PROFILE` environment variable is no longer required as the default configs have been aligned with the recommended profiles.

## **Bug fixes** 🐞

> [accordion] \[Designer] Task view display issue
>
> Fixed task view list row content display issue where table rows were overlapping and text was not vertically centered in the latest Chrome browser version (138). The task view now properly displays centered content without text cutoff.

> [accordion] \[Integration Designer] JSON parsing error
>
> Fixed JSON parsing error when sending JSON result to REST body. Resolved issue where JSON objects generated in script tasks were causing "Unexpected character" errors when used in REST endpoint body parameters with \$ syntax.

> [accordion] \[Branch Merge] Media file export errors
>
> Fixed media file export errors during branch merges. Resolved issue where merging multiple branches created from the same main version would fail with "400 Bad Request" errors for media files after the first successful merge, even when no merge conflicts were present.

> [accordion] \[Process Designer] Rollback issue
>
> Fixed rollback issue during version submission errors. Resolved problem where processes were incorrectly marked as deleted in the database when submit version operations failed with 500 errors, preventing proper rollback and causing subsequent 404 "Process not found" errors.

> [accordion] \[Process Designer] Missing resources during copy operation
>
> Fixed missing resources during copy to another project/library operation. Resolved issue where forms with validation in UserTask nodes were not being copied when copying processes between projects or libraries.

> [accordion] \[Process Designer] Branch with missing resources and 404 errors
>
> Fixed issue where specific branches derived from main version would experience resource corruption, including missing process definitions (404 errors), missing Integration Designer resources, and commit failures.

> [accordion] \[Process Designer] Parallel multi-instance visual bug
>
> Fixed parallel multi-instance designer visual bug and database errors. Resolved issue where call activity nodes with parallel multi-instance enabled created duplicate "inputKey" and "outputKey" entries, causing visual bugs (missing collection key fields) and database update errors during node modifications.

> [accordion] \[Process Engine] Kafka message distribution
>
> Fixed Kafka message distribution across partitions. Resolved issue where Kafka messages were distributed as batches across partitions, causing increased usage of a limited number of partitions, instead of following the round-robin distribution per message strategy.

***

## **Additional information**

> [card] [Deployment Guidelines v4.7.6](./deployment-guidelines-v4.7.6)
>
> Step-by-step deployment instructions and configuration details for this release.

> [card] [Migration Guide (from v4.1.x)](./migrating-from-v4.1.x-to-v4.7.6)
>
> Complete guide for migrating from version 4.1.x to 4.7.6 with breaking changes and migration steps.


# Deployment guidelines v4.7.7
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/deployment-guidelines-v4.7.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.7 will permanently prevent you from importing process definitions and resources created in versions 4.7.6 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.22.3** | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.16.3** | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.97.1** | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.9.2** | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.5.2** | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.6.2** | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.8.2** | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.7.2** | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.6.2** | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.5.2** | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.14.2** | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.21.2** | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.8.1** | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **1.9.40** | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.21** | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | **1.10.29** | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **1.7.14** | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **1.4.6** | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.7 | Keycloak | 22, 26+ |
| 4.7.7 | Kafka | 3.2 - 3.9 |
| 4.7.7 | PostgreSQL | 16 - 17 |
| 4.7.7 | OracleDB | 19c, 21c, 23ai |
| 4.7.7 | MongoDB | 7 - 8 |
| 4.7.7 | Redis | 7.2 - 8.0 |
| 4.7.7 | Elasticsearch | 7 - 8 |
| 4.7.7 | Angular (Web SDK) | 19.x |
| 4.7.7 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.7 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.7-august-2025/v4.7.7-august-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Improved robustness on auto-scaling process-engine and on Kafka node failures\
✅ Improvements on how configuration parameters can now be retrieved from Kubernetes secrets and ConfigMaps\
✅ Vulnerability fixes

## Configuration parameters

Improved configuration parameters retrieval from Kubernetes secrets and ConfigMaps. More details here:

> [card] [FlowX Engine](../../4.7.x/setup-guides/flowx-engine-setup-guide/engine-setup#dynamic-configuration-parameters-retrieval)

> [card] [Integration Designer](../../4.7.x/setup-guides/integration-designer-setup#dynamic-configuration-parameters-retrieval)

## Bug fixes

> [accordion] \[Designer] JSON size limit on input data
>
> Fixed JSON payload size limit issue causing "403 payload too large" errors when starting processes. More details [**here**](../../4.7.x/docs/flowx-designer/managing-a-project-flow/starting-a-process#starting-a-process-via-user-interface).

> [accordion] Improved robustness on Kafka node failures
>
> If one Kafka node fails, platform health check fails. This is now fixed.

> [accordion] \[UI Designer] Theming on accordion card
>
> Fixed theming issue where Card component styling was not properly applied when switched to accordion mode.

> [accordion] \[Angular SDK] Loader does not stop on subprocess end
>
> Fixed loader persistence issue where loaders initiated by "show loader" actions in subprocess UserTasks would continue displaying after subprocess completion.

> [accordion] \[Process Designer] Merge error with duplicate embed node keys
>
> Fixed merge conflict error occurring when copying and pasting embed nodes in processes.

> [accordion] \[Process Engine] Process execution stalls on REST-triggered flows when engine replica fails
>
> Fixed process execution recovery issue where REST API-triggered service tasks would hang indefinitely if the handling engine replica failed mid-execution.

> [accordion] \[Process Designer] Merge fails with duplicate key error after creating child branch to jump over broken WIP
>
> Fixed merge conflict error occurring when creating child branches from working commits to bypass broken WIP versions.


# Deployment guidelines v4.7.8
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/deployment-guidelines-v4.7.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

> [!WARNING]
>
> **Important Upgrade Notice**
> Upgrading to FlowX.AI 4.7.8 will permanently prevent you from importing process definitions and resources created in versions 4.7.7 and earlier. Ensure all necessary data is backed up and compatible before upgrading.

## Component versions

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.23.2** | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **7.17.3** | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.10.3** | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.6.2** | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.7.2** | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.9.2** | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.8.2** | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.7.2** | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.6.2** | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.15.3** | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.22.3** | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.9.2** | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.98.0** | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.22** | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.8 | Keycloak | 22, 26+ |
| 4.7.8 | Kafka | 3.2 - 3.9 |
| 4.7.8 | PostgreSQL | 16 - 17 |
| 4.7.8 | OracleDB | 19c, 21c, 23ai |
| 4.7.8 | MongoDB | 7 - 8 |
| 4.7.8 | Redis | 7.2 - 8.0 |
| 4.7.8 | Elasticsearch | 7 - 8 |
| 4.7.8 | Angular (Web SDK) | 19.x |
| 4.7.8 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.8 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.8-september-2025/v4.7.8-september-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes\
✅ Support for [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title

### Support for Substitution Tags in Table column title

Now you can use [**Substitution Tags**](../../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags) in [**Table**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/table) column title.

## Bug fixes

> [accordion] \[UI Designer] Card expansion state not calculated correctly
>
> Resolved an issue where, in certain situations, the expanded state of cards was not calculated correctly. This prevented users from expanding cards as expected.

> [accordion] \[UI Designer] Document preview component texts not translated
>
> Fixed localization issue where document preview component texts remained in English regardless of the selected language setting.

> [accordion] \[Designer] Groups tab fails to load with Keycloak 26.3
>
> Fixed compatibility issue with Keycloak 26.3 where the Groups tab would remain in loading state indefinitely due to new "description" field in group representations.

> [accordion] \[CMS] Import fails for PDF files with null thumbnail path
>
> Fixed import failure when PDF media files were exported with null `thumbnailStoragePath` values, preventing successful deployment of build or app versions to fresh environments.

> [accordion] \[Runtime Manager] Improved error logging for proxy failures
>
> Enhanced error logging detail when Runtime Manager proxy requests fail, providing better root cause information for debugging infrastructure issues like DNS problems or service unavailability.

> [accordion] \[Integration Designer] Slow performance on first workflow execution after pod restart
>
> Fixed performance issue where workflow IF node processing time increased from 3-5 seconds to 15-20 seconds on the first execution after Integration Designer pod restart.

> [accordion] \[Process Engine] Active step was incorrectly computed when the token is reset
>
> Fixed issue where the active step was incorrectly computed when the token is reset.


# Deployment guidelines v4.7.9
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/deployment-guidelines-v4.7.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **8.24.1** | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 |
| **admin** | **7.18.4** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **5.11.1** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **5.7.1** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **6.10.1** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **7.9.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **6.8.1** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **4.7.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **2.16.1** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **2.23.1** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **2.10.2** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Renderers

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **5.101.1** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **4.0.30** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **4.0.26** | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.25 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Agents

| Component | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | 1.9.40 | 1.9.40 | 1.9.40 | 1.9.39 | 1.9.39 | 1.9.39 | 1.9.37 | 1.9.35 | 1.9.27 | 1.9.21 | 1.9.16 | 1.9.10 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-assistant** | **1.8.23** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-analyst** | 1.10.29 | 1.10.29 | 1.10.29 | 1.10.28 | 1.10.28 | 1.10.28 | 1.10.26 | 1.10.24 | 1.10.17 | 1.10.13 | 1.10.6 | 1.10.3 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | 1.4.6 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | 1.7.14 | 1.7.14 | 1.7.14 | 1.7.13 | 1.7.13 | 1.7.13 | 1.7.11 | 1.7.9 | 1.7.4 | 1.7.0 | 1.6.5 | 1.5.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

## Third-party recommended component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 4.7.9 | Keycloak | 22, 26+ |
| 4.7.9 | Kafka | 3.2 - 3.9 |
| 4.7.9 | PostgreSQL | 16 - 17 |
| 4.7.9 | OracleDB | 19c, 21c, 23ai |
| 4.7.9 | MongoDB | 7 - 8 |
| 4.7.9 | Redis | 7.2 - 8.0 |
| 4.7.9 | Elasticsearch | 7 - 8 |
| 4.7.9 | Angular (Web SDK) | 19.x |
| 4.7.9 | React (Web SDK) | 18.x |

> [!NOTE]
>
> FlowX.AI supports all versions within the specified ranges of the prerequisite third-party components in the above table.
>
> For optimal performance and reliability, our internal QA process validates new FlowX.AI releases using the latest stable versions within each supported range.
>
> In the unlikely event that you encounter any compatibility issues with FlowX.AI, please open a support ticket [**here**](https://flowxai.zendesk.com/), and our dedicated team will address and resolve any identified bugs following our standard support process.

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.9
> * Redis versions older than 7.4
> * Elasticsearch older than 8


# FlowX.AI 4.7.9 Release Notes
Source: https://docs.flowx.ai/release-notes/v4.x/v4.7.x-lts/v4.7.9-october-2025/v4.7.9-october-2025

Latest features, improvements, and bug fixes in our newest release

## What's new?

✅ Vulnerability fixes and security improvements\
✅ Support for dynamic keys in [**Link component**](../../../../4.7.x/docs/building-blocks/ui-designer/ui-component-types/typography#link) URL property across all platforms\
✅ Added property on View for enabling or disabling row selection in tasks table

### Support for dynamic keys in Link component URL property

You can now use dynamic keys in the Link component's URL property across all platforms (Web, iOS, and Android). This enhancement allows you to dynamically construct URLs using process data, enabling more flexible navigation patterns in your applications.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/link_url.png)

### Task Manager rowSelection property on view

A new "Enable row selection" property has been added to Task Manager views, enabling you to control row selection behavior in task tables.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/enable_row_select.png)

## Bug fixes

> [accordion] \[Designer] Merge fails if one branch contains past merges
>
> Fixed an issue where merging branches that contain multiple past merge commits would fail with an error. The merge conflict resolution now properly handles complex merge histories when adding values to enumerations or making other configuration changes.

> [accordion] \[CMS] Enumerations retrieve content endpoint should return content from dependencies
>
> Resolved an issue where the CMS enumerations Kafka endpoint only returned content from the local project and not from library dependencies. The endpoint now correctly retrieves enumeration content from both the current project and all dependency libraries.

> [accordion] \[Task Manager] Table doesn't use the current language
>
> Fixed localization issue in Task Manager where table content wasn't respecting the current language setting. Task Manager tables now properly use the selected language for all displayed content.

> [accordion] \[UI Designer]\[Angular]\[React] Modal fixed height is not applied
>
> Resolved an issue where setting a modal's height to "fixed" would not apply correctly in Angular and React renderers. Fixed height configuration now works as expected for modal components.

> [accordion] \[UI Designer]\[Angular] Fixed container should use overflow-y auto instead of scroll
>
> Fixed styling issue where fixed-height containers incorrectly used `overflow-y: scroll` instead of `overflow-y: auto`. Containers now only show scrollbars when content exceeds the container height.


# Deployment guidelines v5.0.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/deployment-guidelines-v5.0

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.29.2** | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.25.2** | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.21.2** | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.12.0** | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.14.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.17.2** | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.14.2** | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.12.1** | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.15.2** | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.11.0** | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.26.2** | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.27.3** | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.11.0** | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.14.2** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.11.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | |

### Embedded components

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **SpiceDB** | **1.42.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **DGraph** | **25.0.0** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

### Renderers

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.69.0** | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.0** | 4.0.29 | 4.0.29 | 4.0.24 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.3** | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.0.12** | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.0.1** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.0.1** | - | | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.0.0 | Keycloak | 26+ |
| 5.0.0 | Kafka | 3.8 - 3.9 |
| 5.0.0 | PostgreSQL | 16 - 17 |
| 5.0.0 | Oracle Database | 21c, 23ai |
| 5.0.0 | MongoDB | 7 - 8 |
| 5.0.0 | Redis | 7.4 - 8.0 |
| 5.0.0 | Elasticsearch | 8 - 9 |
| 5.0.0 | Angular (Web SDK) | 19.x |
| 5.0.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies will no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/configuration-and-migration

This section contains the steps in the order we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](../../../../5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The Authorization System will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

> [!NOTE]
>
> The admin user imported here is the same service account referenced in the migration prerequisites. If you followed the prerequisites page and set up the admin Keycloak user beforehand, the Authorization System will pick it up automatically during this step — no additional action is needed.

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from Application Manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.0.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | 🆕 Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Kafka Configuration

> [!NOTE]
>
> Consumer group naming standardized to kebab-case across all FlowX.AI services with new messaging features for enhanced functionality.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group naming changes

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
> | | |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Application Manager specific features

#### New environment variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | 🆕 Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | 🆕 Maximum HTTP request header size |

#### New Kafka features

> [card] Resource Update Propagation
>
> Consumer Group: `app-resource-update-propagation-group`\
> Threads: 3\
> Topic: `ai.flowx.{env}.application-version.resource.update.propagation.v1`

> [card] Build Runtime Data
>
> Consumer Group: `build-runtime-data-group`\
> Threads: 2\
> Topic: `ai.flowx.{env}.build.runtime-data.v1`

> [card] Business Rule Sync
>
> Topic: `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> Purpose: Business rule synchronization

> [card] Process Sync (Restructured)
>
> Topic: `ai.flowx.{env}.application-version.sync.process.in.v1`\
> Purpose: Enhanced process synchronization

> [card] Reusable Templates sync
>
> Topic: `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> Purpose: Reusable template synchronization

#### Kafka environment variables (optional overrides)

```bash New Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_RESOURCEUPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Business Rule Sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1

# Process Sync (restructured)
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1


# Reusable Templates sync
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1
```

```bash Consumer Groups theme={"dark"}
# New Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
```

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides.

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | 🆕 Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | 🆕 Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | 🆕 Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | 🆕 S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | 🆕 S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | 🆕 S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | 🆕 S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | 🆕 S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | 🆕 S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | 🆕 Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | 🆕 Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | 🆕 Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | 🆕 Redis host |
| `SPRING_REDIS_PORT` | `6379` | 🆕 Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | 🆕 Redis password |
| `SPRING_REDIS_TTL` | `5000000` | 🆕 Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | 🆕 Redis host |

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/install-services

Step-by-step installation guide for new FlowX.AI 5.0 services

FlowX.AI 5.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](/5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](/5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.6 (or newer) to 5.0.0. If you’re on an earlier version, upgrade to the latest LTS version first.

## Success factors

> [!WARNING]
>
> The following steps are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB** must be installed before any FlowX.AI services. **DGraph** is only required if you are using FlowX AI agents — if not, you can skip DGraph installation, but SpiceDB is still mandatory.
>
> > [!NOTE]
> >
> > Only DGraph can be skipped (and only if you are not using FlowX AI agents). SpiceDB is mandatory for all deployments.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices migration** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](/5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/prerequisites

This section contains the steps in the order we recommend for migrating data from FlowX v4.7.x to v5.0.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.6 | FlowX.AI 5.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.0#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip installing DGraph. SpiceDB is still mandatory.

> [card] [SpiceDB setup guide](../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.0.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

Before upgrading to FlowX.AI 5.0, you must run two operations on all existing Elasticsearch indices:

1. **Update index mappings** to include the `workspaceId` field (schema change)
2. **Migrate existing documents** to assign them to the default workspace (data migration)

These operations are required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable; if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

> [!WARNING]
>
> If Elasticsearch migration is not completed correctly, some process instances may not appear in search results, data-search features might return incomplete results, and workspace-scoped queries will fail for unmigrated data. Existing resources will also not be visible or accessible within the new workspace structure.

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.0.0.

***

## Authorization System Prerequisites

Before deploying the `authorization-system` service, you must configure the organization admin user. This is a critical prerequisite for ensuring that the authentication and user management features function correctly post-upgrade.

### Steps to Configure the Organization Admin User

Follow these guides to correctly set up the organization admin user:

> [card] [Bootstrap Organization Admin](../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Organization Admin Roles & Workspace Access](../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

> [!TIP]
>
> Configuration of the organization admin user must be completed **before** deploying the authorization-system service (see the [Install Services](./install-services) section for service deployment steps).

### Pre-migration preparation

Required configuration for the authorization-system service:

* `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE`= `true` (mandatory for migrations)
* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME`= `<admin-username>` (recommended method, default: `admin@flowx.ai`)

The system will search for this username in Keycloak and automatically copy the user's subject ID to the authorization-system database.

**Fallback method:** If the username method fails or you prefer to specify the subject ID directly:

* `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID`= `<subject-id-of-admin-user>`

> [!TIP]
>
> To get the subject-id of the admin user, you can extract it from the JWT token of the admin user.

![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users"
    ]
  }
}
```


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/migrating-from-v4.7.x-to-5.0/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.0 platform version. Check: **Release Notes → v5.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.06.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.0") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.0 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.0 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.0 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.0 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.0 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.0 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.0 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# FlowX.AI 5.0.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.0.0-july-2025/v5.0.0-july-2025

Latest features, improvements, and bug fixes in our newest release

> [!WARNING]
>
> This release includes the following features in Tech Preview. We encourage you to try them out and share your feedback to help us improve them. Please note that Tech Preview features may change before final release.

> [tab] What's New
>
> **What's new? 🆕**
>
> 🆕 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture)\
> 🆕 [**Project Data Model (PDM)**](#project-data-model-pdm)\
> 🆕 [**FlowX.AI Database**](#flowx-ai-database)\
> 🆕 [**Multi Select UI Component**](#multi-select-ui-component)\
> 🆕 [**Library-to-Library Dependencies**](#library-to-library-dependencies)\
> 🆕 [**Data Mappers**](#data-mappers)\
> 🆕 [**Reusable Resources**](#reusable-resources)\
> 🆕 [**Files in Integration Designer**](#files-in-integration-designer)\
> 🆕 [**Rendering improvements**](#rendering-improvements)
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Major Infrastructure Changes**: Workspaces introduces SpiceDB integration and new database schemas for multi-tenant architecture.
> > >
> > > **Key Changes:**
> > >
> > > * **SpiceDB Integration**: New permission management system requiring deployment
> > >
> > > * **Database Migration**: Schema updates for workspace support
> > >
> > > * **User Storage**: Only information about FlowX.AI Designer users is stored in FlowX.AI. The stored user data is limited to: unique identifier, username, first name, last name, and email address.
> > >
> > > * **Default Workspace**: All the projects and libraries are migrated to default workspace
> > >
> > > > [!TIP]
> > > >
> > > > **Backward Compatibility**: All existing functionality preserved in default workspace
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Login Flow**: After authentication, select your workspace before accessing FlowX.AI Designer. Once inside a workspace, everything works as before.
> > >
> > > **What's New:**
> > >
> > > * **Workspace Selection**: Choose workspace after login
> > > * **Resource Isolation**: Projects, libraries, themes are workspace-specific
> > > * **Enhanced Permissions**: Fine-grained access control with user groups and ACLs
> > > * **Workspace Management**: Create and manage workspaces (admin users)
> > >
> > > **What Stays the Same:**
> > >
> > > * Process design and configuration
> > > * UI Designer capabilities
> > > * Integration patterns
> > > * All existing FlowX.AI Designer features
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Transformation**: Workspaces enables enterprise multi-tenant architecture with independent business unit governance while sharing platform capabilities.
> > >
> > > **Business Impact:**
> > >
> > > * **Faster time-to-market** for new business verticals
> > > * **Enhanced compliance** with workspace-specific controls
> > > * **Improved governance** with fine-grained access management
> > >
> > > **Enterprise Benefits:**
> > >
> > > * Business unit autonomy with shared platform
> > > * Regulatory compliance through data isolation
> > > * Centralized upgrades and maintenance
> > > * Cross-business unit resource sharing when appropriate
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Infrastructure Impact**: PDM has minimal infrastructure impact - it's a design-time feature that improves development efficiency without affecting runtime resources.
> > >
> > > > [!TIP]
> > > >
> > > > **No deployment changes required** - PDM is part of the design platform, not runtime
> > >
> > > > [!TIP]
> > > >
> > > > **Backward compatible** - Existing processes continue to work unchanged
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer**: Define data types once at project level, use everywhere. No more recreating Customer or Order objects in every process.
> > >
> > > **How to Use PDM:**
> > >
> > > 1. Navigate to Project → Config → Data Model
> > > 2. Define your business entities (Customer, Product, etc.)
> > > 3. Set governance rules (sensitive data, reporting)
> > > 4. Use these types in any process within the project
> > >
> > > **Best Practices:**
> > >
> > > * Start with core business entities
> > > * Use clear, consistent naming
> > > * Mark sensitive fields appropriately
> > > * Leverage library data types when available
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: PDM transforms how your organization manages business data definitions. Define business entities once and ensure consistency across all processes and teams.
> > >
> > > **Business Benefits:**
> > >
> > > * **Enhanced compliance** through centralized governance and data sensitivity controls
> > > * **Reduced errors** from consistent data definitions
> > >
> > > **ROI Indicators:**
> > >
> > > * Development Efficiency: Measure reduction in process creation time
> > > * Error Reduction: Track fewer data-related production issues
> > > * Maintenance Cost: Monitor time spent on data structure updates
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!WARNING]
> > > >
> > > > **Infrastructure Planning Required**: FlowX.AI Database creates additional MongoDB collections and requires infrastructure planning for storage, monitoring, and backup procedures.
> > >
> > > > [!TIP]
> > > >
> > > > New microservice: NoSQL DB Runner. Check the [setup guide](/5.1/setup-guides/nosql-db-runner) for more details.
> > >
> > > **Key Considerations:**
> > >
> > > * **Storage Planning**: Monitor usage as processes adopt internal database (plan for 20-30% increase)
> > > * **Performance Monitoring**: Set up alerts for FlowX.AI Database query performance
> > > * **Backup Strategy**: Include FlowX.AI Database collections in backup procedures
> > > * **Connection Pooling**: Additional connection pools for database operations
> > > * **Memory**: Additional 256MB-512MB per FlowX.AI instance for database operations
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **New Integration Option**: FlowX.AI Database appears as a new Data Source type in Integration Designer, right alongside RESTful System.
> > >
> > > **When to Use FlowX.AI Database:**
> > >
> > > * Customer data lookup across processes
> > > * Shared configuration and reference data
> > > * Process-to-process communication
> > > * Caching frequently accessed data
> > > * Temporary operational data storage
> > >
> > > **How to Implement:**
> > >
> > > 1. Add Data Source node to your process
> > >
> > > 2. Select "FlowX.AI Database" as type
> > >
> > > 3. Configure collection and operations
> > >
> > > 4. Use familiar MongoDB syntax (find, insert, update)
> > >
> > > > [!WARNING]
> > > >
> > > > **When NOT to Use**: Don't replace your core business systems. FlowX.AI Database is perfect for operational data, caching, and inter-process communication - but your CRM, ERP, and other systems of record should remain your primary data sources.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: FlowX.AI Database enables new operational patterns that were previously complex or impossible. It's not about replacing your core systems, but about enabling new ways to orchestrate business processes.
> > >
> > > **New Business Capabilities:**
> > >
> > > * **Cross-process workflows**: Loan application → Credit check → Approval across different process instances
> > > * **Real-time dashboards**: Operational data for business monitoring without system integration
> > > * **Agile experimentation**: Test new business rules without impacting core systems
> > > * **Process orchestration**: Complex business flows spanning multiple departments
> > >
> > > **ROI Considerations:**
> > >
> > > * **Time to Market**: Faster implementation of new business processes
> > > * **Agility**: Rapid prototyping and testing of business ideas
> > >
> > > **Use FlowX.AI Database when:**
> > >
> > > * Data is operational and process-specific (not master data)
> > > * You need rapid implementation without IT system changes
> > > * Process instances need to communicate with each other
> > > * You're prototyping new business capabilities
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **No Infrastructure Impact**: Multi Select is a pure UI component with no backend requirements. It works with existing form handling and data storage mechanisms.
> > >
> > > > [!TIP]
> > > >
> > > > **Zero deployment overhead** - Component is part of the UI framework upgrade
> > >
> > > > [!TIP]
> > > >
> > > > **Existing data handling** - Uses standard array storage, no schema changes needed
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Easy Integration**: Multi Select works just like other form elements in UI Designer. Drag, drop, configure - no new learning curve required.
> > >
> > > **Common Use Cases:**
> > >
> > > 1. **Skills Selection**: Job applications, team member profiles, contractor skills
> > > 2. **Product Features**: Insurance coverage options, software licensing features
> > > 3. **Categories & Tags**: Document classification, customer segmentation
> > >
> > > **Key Configuration:**
> > >
> > > * **Max selections**: Control input limits
> > > * **Display format**: Chips, lists, custom
> > > * **Search**: Filter large option sets
> > > * **Clear all**: Easy reset functionality
> > > * **Validation**: Min/max rules
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **User Experience Impact**: Multi Select eliminates user frustration in scenarios where single selection doesn't match real-world needs. This improves data quality and user satisfaction.
> > >
> > > **Before vs After:**
> > >
> > > * ❌ **Before**: "I can only select one skill, but I have multiple certifications"
> > > * ✅ **After**: "Perfect! I can select all my relevant skills at once"
> > >
> > > **Business Process Examples:**
> > >
> > > * **Employee Onboarding**: Select multiple skills, certifications, department access
> > >
> > > * **Product Configuration**: Select multiple features, add-ons, support packages
> > >
> > > * **Customer Preferences**: Select multiple communication channels, product interests
> > >
> > > > [!TIP]
> > > >
> > > > **Analytics Benefit**: Multi-select data provides richer analytics. Instead of knowing a customer chose "Primary Interest: Technology," you know they selected "AI, Cloud Computing, Cybersecurity, Mobile Development" - much more actionable for business intelligence.
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backwards Compatibility**: FlowX.AI 5.0 maintains full backwards compatibility with existing project-to-library dependencies from FlowX.AI 4.x. All existing dependencies will continue to work without modification.
> > >
> > > **Upgrade Process:**
> > >
> > > 1. **Existing dependencies** will be automatically migrated
> > >
> > > 2. **New library dependency features** become available immediately
> > >
> > > 3. **No breaking changes** to existing functionality
> > >
> > > 4. **Enhanced validation** may catch previously undetected issues
> > >
> > > > [!WARNING]
> > > >
> > > > **Post-Migration Required**: After the lib2lib migration is executed, you must clear the cache. This is necessary because a new field is added to the build mongo document.
> > >
> > > **Cache Clearing Steps:**
> > >
> > > 1. Complete the lib2lib migration process
> > > 2. Clear the application cache to ensure the new build document fields are properly recognized
> > > 3. Verify that library-to-library dependencies are functioning correctly
> > >
> > > **Key Changes:**
> > >
> > > * **Build Export Changes**: Build exports now automatically include entire dependency trees (larger packages but self-contained)
> > > * **Dependency Validation**: Build process now checks for dependency conflicts (enhanced validation may catch previously undetected issues)
> > > * **Deployment Consistency**: Single-version constraint prevents runtime conflicts (more predictable deployments)
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Enhanced Organization**: You can now create more sophisticated library structures where specialized libraries build upon common foundations. This reduces duplication and improves consistency.
> > >
> > > **How It Works:**
> > >
> > > 1. Navigate to Library → Config → Dependencies
> > > 2. Add other libraries as dependencies
> > > 3. FlowX.AI validates for conflicts automatically
> > > 4. Resources from all dependency levels become available
> > >
> > > **Best Practices:**
> > >
> > > * Plan your library hierarchy before implementation
> > >
> > > * Keep dependencies focused and purposeful
> > >
> > > * Avoid circular dependencies
> > >
> > > * Use semantic versioning consistently
> > >
> > > * Document dependency relationships clearly
> > >
> > > > [!NOTE]
> > > >
> > > > **Example**: Create a "US Banking Library" that depends on "Global Banking Library" and "US Compliance Library". This way, US-specific processes get both global banking functionality and local compliance requirements automatically.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Enterprise Architecture**: Library-to-Library Dependencies enable sophisticated organizational structures where different teams can own specific business domains while building on shared foundations.
> > >
> > > **Enterprise Use Cases:**
> > >
> > > **Multi-Country Operations:**
> > > Global Insurance Company: US-specific library depends on Global Compliance library
> > >
> > > ```
> > > US Insurance Library → Global Compliance Library → Base Insurance Library
> > > ```
> > >
> > > **Product Line Specialization:**
> > > Bank: Mortgage processes use specialized libraries that extend common banking operations
> > >
> > > ```
> > > Mortgage Library → Lending Library → Core Banking Library
> > > ```
> > >
> > > **Business Impact:**
> > >
> > > * **Team Autonomy**: Teams work independently while leveraging shared assets
> > >
> > > * **Faster Innovation**: New products build on proven foundation components
> > >
> > > * **Risk Reduction**: Tested, validated components reduce implementation risk
> > >
> > > > [!WARNING]
> > > >
> > > > **Change Management**: This capability requires coordination between teams. Establish clear ownership models, communication protocols, and upgrade procedures before implementing complex dependency hierarchies.
>
> ***
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!TIP]
> > > >
> > > > **Zero Infrastructure Impact**: Data Mappers is a design-time feature that enhances the FlowX.AI Designer interface without requiring additional infrastructure or deployment changes.
> > >
> > > > [!NOTE]
> > > >
> > > > **Full Backward Compatibility**: All existing data transfer mechanisms (like `append to parent process` or `output.[outputKey]`) continue to work unchanged. Teams can adopt Data Mappers at their own pace.
> > >
> > > **Key Points:**
> > >
> > > * **No new microservices** - Enhancement to existing designer interface
> > > * **No runtime changes** - Data mapping occurs at design time
> > > * **Existing configurations preserved** - Zero impact on current implementations
> > > * **Optional adoption** - Teams choose when and where to use new functionality
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Game Changer for Integration**: No more complex syntax for data transfers. Visual drag-and-drop interface makes component integration intuitive and error-free.
> > >
> > > **How to Use Data Mappers:**
> > >
> > > 1. **Define Parameters**: Set input/output parameters on Start/End nodes
> > > 2. **Choose Implementation**: Select "Data Mapper" or "Current" method
> > > 3. **Visual Mapping**: Drag source parameters to destination parameters
> > > 4. **Save Configuration**: Store mappings for reuse and maintenance
> > >
> > > **When to Use:**
> > >
> > > * **Call Activities**: Passing data between parent and child processes
> > >
> > > * **Integration Workflows**: Connecting with external systems
> > >
> > > * **Complex Data Flows**: When visual mapping improves clarity
> > >
> > > * **Team Collaboration**: When multiple people work on integration logic
> > >
> > > > [!WARNING]
> > > >
> > > > **Parameter Changes**: When you modify input/output parameters, existing mappings must be manually updated. Changes don't automatically propagate to avoid unintended data flow modifications.
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Strategic Value**: Data Mappers transforms technical integration tasks into visual, business-friendly workflows. Non-technical stakeholders can now understand and validate data flows between business processes.
> > >
> > > **Business Impact:**
> > >
> > > * **Reduced Errors**: Visual mapping prevents data integration mistakes that cause process failures
> > > * **Faster Development**: Intuitive interface accelerates process configuration and testing
> > > * **Better Documentation**: Visual data flows serve as living documentation of business logic
> > > * **Team Collaboration**: Business and technical teams can discuss data flows using the same visual interface
> > >
> > > **ROI Indicators:**
> > >
> > > * **Development Speed**: Measure reduction in integration configuration time
> > > * **Error Rate**: Track fewer data-related production issues
> > > * **Team Efficiency**: Monitor cross-functional collaboration improvements
> > > * **Process Quality**: Assess improvement in first-time-right deployments
> > >
> > > **Use Cases by Industry:**
> > >
> > > * **Banking**: Loan application data flowing from customer intake → credit check → approval process
> > > * **Insurance**: Claim data mapping from initial report → investigation → settlement
> > > * **Manufacturing**: Order data flowing from sales → production planning → fulfillment
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> > [accordion] 👥 What This Means for Your Role
> >
> > > [tab] DevOps Engineer
> > >
> > > > [!NOTE]
> > > >
> > > > **Minimal Infrastructure Impact**: Reusable Resources is primarily a design-time enhancement that leverages existing FlowX infrastructure with minimal additional overhead.
> > >
> > > **Infrastructure Considerations:**
> > >
> > > * **Execution Context**: Functions execute within existing process engine contexts - no additional runtime infrastructure required
> > >
> > > > [!TIP]
> > > >
> > > > **No New Microservices**: Features are integrated into existing FlowX.AI platform components
> >
> > > [tab] Process Configurator
> > >
> > > > [!TIP]
> > > >
> > > > **Development Game Changer**: Access the new "Reusable Resources" section in FlowX.AI Designer - located alongside "Reusable Functions" - to eliminate 60-80% of repetitive development work.
> > >
> > > **Key Capabilities:**
> > >
> > > * **Data Model Support**: Full integration with Project Data Model (PDM)
> > > * **Action Scenarios**: Template-defined actions assigned during instantiation OR form-centric actions handled by User Task
> > > * **Omnichannel**: Templates work across web, mobile, and other channels
> > >
> > > **Best Practices:**
> > >
> > > * **Start with common patterns**: Identify frequently repeated business logic and UI components
> > > * **Test thoroughly**: Use interactive testing for functions and preview mode for templates
> > > * **Document usage**: Include clear descriptions and example use cases
> >
> > > [tab] Business Analyst
> > >
> > > > [!NOTE]
> > > >
> > > > **Revolutionary Business Impact**: Reusable Resources fundamentally changes how organizations approach process development, transforming from "build every time" to "build once, leverage everywhere."
> > >
> > > **Strategic Business Value:**
> > >
> > > * **Quality Assurance**: Dramatic reduction in defects through reusable, tested components
> > > * **Maintenance Efficiency**: Update business rules once to instantly affect all processes
> > > * **Team Productivity**: Developers focus on new business capabilities instead of repetitive development
> > > * **Consistency**: Ensure uniform business rules and user experience across all touchpoints
> > >
> > > **Industry Use Cases:**
> > >
> > > * **Functions**: KYC validation, credit scoring, fraud detection, regulatory compliance checks
> > >
> > > * **UI Templates**: Customer onboarding forms, document upload sections, account summary dashboards, loan application interfaces
> > >
> > > * **Functions**: Premium calculations, risk evaluation, claims processing, policy validation
> > >
> > > * **UI Templates**: Quote request forms, claims submission interfaces, policy comparison tables, agent dashboards
> > >
> > > * **Functions**: Patient eligibility checks, treatment authorization, billing calculations, compliance validation
> > >
> > > * **UI Templates**: Patient registration forms, appointment scheduling interfaces, medical history cards, provider dashboards
>
> ### **Files in Integration Designer**
>
> > [card] File Handling in Integration Designer
> >
> > FlowX.AI 5.0 introduces native file handling capabilities in Integration Designer, enabling seamless file uploads and downloads with external systems directly within your integration workflows.
> >
> > > [card] Download Files
> > >
> > > Call external APIs and receive files in the response. Integration Designer saves files to Document Plugin or S3 and returns paths for further processing.
> >
> > > [card] Upload Files
> > >
> > > Send files stored in Document Plugin or S3 to external APIs via multipart/form-data or single binary requests.
> >
> > > [card] Multiple Formats
> > >
> > > Support for JSON responses with Base64 encoded files and single binary responses with automatic file identification.
> >
> > > [card] Flexible Storage
> > >
> > > Configure file destinations to Document Plugin (process-linked) or S3 Protocol (custom buckets) based on your needs.
> >
> > [Learn more about File Handling in Integration Designer](../../../5.1/docs/platform-deep-dive/integrations/integration-designer#file-handling)
> >
> > New Feature
>
> ### **Rendering Improvements**
>
> > [card] UI/UX Enhancements
> >
> > > [tab] Grid & Layout Improvements
> > >
> > > > [card] Enhanced Grid Component
> > > >
> > > > Improved performance, responsiveness, and customization options for data display and form organization
> > >
> > > > [card] Navigation Areas Redesign
> > > >
> > > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> > >
> > > > [card] Multi Actions Support
> > > >
> > > > Batch operations support for UI components, enabling simultaneous actions on multiple elements
> > >
> > > > [card] Permission-Based UI Editing
> > > >
> > > > Granular control over UI element editing based on user permissions with partial editing capabilities
> >
> > > [tab] Enhanced Form Controls
> > >
> > > > [card] Input Type Code
> > > >
> > > > Specialized input component for code entry
> > >
> > > > [card] Formatting Options
> > > >
> > > > Advanced formatting capabilities for Input and Slider components
> > >
> > > > [card] Switch Variants
> > > >
> > > > Enhanced switch component supporting both toggle and checkbox variants
> > >
> > > > [card] Disabled Options on Selectors
> > > >
> > > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > > [tab] Advanced Features
> > >
> > > > [card] Custom Loader
> > > >
> > > > Configurable loading indicators for improved user experience during data operations
> > >
> > > > [card] Custom Validators
> > > >
> > > > Advanced validation logic using dynamic computed expressions
> > >
> > > > [card] File Upload Button Type
> > > >
> > > > New specialized button variant designed for file upload operations
> > >
> > > > [card] Copy Styles
> > > >
> > > > Efficiently replicate styling across multiple UI components
> >
> > > [tab] Analytics & Process
> > >
> > > > [card] Analytics Enhancements
> > > >
> > > > Custom payload support for detailed user interaction tracking and business intelligence
> > >
> > > > [card] Process End Handling
> > > >
> > > > Improved user experience when processes complete or terminate
> > >
> > > > [card] Forms in Collections
> > > >
> > > > Enhanced support for form elements within collection components
> > >
> > > > [card] Template Management
> > > >
> > > > Streamlined template organization by consolidating functionality in Reusable Resources

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.0](./deployment-guidelines-v5.0)
> >
> > Instructions for deploying FlowX.AI 5.0.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.0/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.0.0


# Deployment guidelines v5.1.1
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.1 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.0 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.0 → 5.1.1**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.64.3** | 9.63.0 | 9.29.2 | 8.24.1 | 8.23.3 | 8.23.2 | 8.22.3 | 8.21.11 |
| **admin** | **9.66.5** | 9.65.0 | 9.25.2 | 7.18.4 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 |
| **designer** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **cms-core** | **9.36.3** | 9.35.0 | 9.21.2 | 5.11.1 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 |
| **scheduler-core** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **events-gateway** | **9.26.1** | 9.25.0 | 9.12.0 | 5.7.1 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 |
| **notification-plugin** | **9.29.1** | 9.28.0 | 9.14.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 |
| **document-plugin** | **9.35.1** | 9.34.0 | 9.17.2 | 6.10.1 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 |
| **task-management-plugin** | **9.34.2** | 9.33.0 | 9.14.2 | 7.9.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 |
| **data-search** | **9.23.1** | 9.22.0 | 9.12.1 | 4.7.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 |
| **audit-core** | **9.30.1** | 9.29.1 | 9.15.2 | 6.8.1 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 |
| **advancing-controller** | **9.25.1** | 9.24.0 | 9.11.0 | 4.7.1 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 |
| **integration-designer** | **9.50.0** | 9.49.1 | 9.26.2 | 2.16.1 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 |
| **application-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.2 | |
| **runtime-manager** | **9.73.6** | 9.72.0 | 9.27.3 | 2.23.1 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 |
| **data-sync** | **9.22.1** | 9.21.0 | 9.11.0 | 2.10.2 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 |
| **authorization-system** | **9.34.2** | 9.33.0 | 9.14.2 | - | - | - | - | - |
| **nosql-db-runner** | **9.22.1** | 9.21.0 | 9.11.0 | - | - | - | - | - |

### Renderers

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/angular-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/react-ui-toolkit** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-sdk** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **@flowx/core-theme** | **9.159.5** | 9.153.6 | 9.69.0 | 5.101.1 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 |
| **iOS renderer** | **9.0.5** | 9.0.4 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 |
| **Android renderer** | **9.0.3** | 9.0.2 | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 |

### Plugins

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.0 | 0.2.4 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 |

### AI Platform

| Component | 5.1.1 | 5.1.0 | 5.0.0 | 4.7.9 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 |
| - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.5** | 9.2.4 | 9.2.3 | 1.8.22 | 1.8.22 | 1.8.21 | 1.8.20 | 1.8.19 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.3 |
| **ai-platform-ai-developer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-connected-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-knowledge-graph** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agents** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-conversations** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-models** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-tenants** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-planner** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-analyst** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-ai-designer** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-agent-builder** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |
| **ai-platform-binaries** | **9.4.2** | 9.3.0 | 9.0.1 | - | - | - | - | - |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.1 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.0 processes and configurations

### What's included in 5.1.1

This maintenance release includes:

* **WCAG 2.1 Level AA compliance** across all web components (28 improvements)
* **3 customer-reported issue fixes** for production environments
* **62 proactive quality improvements** identified through internal testing
* **Platform enhancements** for SSE handling, CMS tags, and infrastructure

For detailed information on all changes, see the [FlowX.AI 5.1.1 Release Notes](./v5.1.1-november-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.1 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.1 | PostgreSQL | 16 - 17 |
| 5.1.1 | Oracle Database | 21c, 23ai |
| 5.1.1 | MongoDB | 7 - 8 |
| 5.1.1 | Redis | 7.4 - 8.0 |
| 5.1.1 | Elasticsearch | 8 |
| 5.1.1 | Angular (Web SDK) | 19.x |
| 5.1.1 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.2
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.2

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.2 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.1 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.1 → 5.1.2**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **process-engine** | **9.67.0** | 9.64.3 | 9.63.0 | 9.29.2 |
| **admin** | **9.68.1** | 9.66.5 | 9.65.0 | 9.25.2 |
| **designer** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **cms-core** | **9.39.0** | 9.36.3 | 9.35.0 | 9.21.2 |
| **scheduler-core** | **9.28.1** | 9.26.1 | 9.25.0 | 9.12.0 |
| **events-gateway** | **9.29.0** | 9.26.1 | 9.25.0 | 9.12.0 |
| **notification-plugin** | **9.32.0** | 9.29.1 | 9.28.0 | 9.14.2 |
| **document-plugin** | **9.37.1** | 9.35.1 | 9.34.0 | 9.17.2 |
| **task-management-plugin** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **data-search** | **9.25.1** | 9.23.1 | 9.22.0 | 9.12.1 |
| **audit-core** | **9.33.0** | 9.30.1 | 9.29.1 | 9.15.2 |
| **advancing-controller** | **9.28.0** | 9.25.1 | 9.24.0 | 9.11.0 |
| **integration-designer** | **9.52.1** | 9.50.0 | 9.49.1 | 9.26.2 |
| **application-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **runtime-manager** | **9.75.1** | 9.73.6 | 9.72.0 | 9.27.3 |
| **data-sync** | **9.26.0** | 9.22.1 | 9.21.0 | 9.11.0 |
| **authorization-system** | **9.36.1** | 9.34.2 | 9.33.0 | 9.14.2 |
| **nosql-db-runner** | **9.24.1** | 9.22.1 | 9.21.0 | 9.11.0 |

### Renderers

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/angular-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/react-ui-toolkit** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-sdk** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **@flowx/core-theme** | **9.161.3** | 9.159.5 | 9.153.6 | 9.69.0 |
| **iOS renderer** | **9.0.7** | 9.0.5 | 9.0.4 | 9.0.0 |
| **Android renderer** | **9.0.5** | 9.0.3 | 9.0.2 | 9.0.0 |

### Plugins

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.0 |

### AI Platform

| Component | 5.1.2 | 5.1.1 | 5.1.0 | 5.0.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.6** | 9.2.5 | 9.2.4 | 9.2.3 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.0.12 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.3.0 | 9.0.1 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.2 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.1 processes and configurations

### What's included in 5.1.2

This maintenance release includes:

* **Bug fixes** addressing customer-reported issues
* **Stability improvements** for platform reliability
* **Quality enhancements** identified through internal testing

For detailed information on all changes, see the [FlowX.AI 5.1.2 Release Notes](./v5.1.2-december-2025).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.2 | Keycloak | 26+ |
| 5.1.2 | Kafka | 3.8 - 3.9 |
| 5.1.2 | PostgreSQL | 16 - 17 |
| 5.1.2 | Oracle Database | 21c, 23ai |
| 5.1.2 | MongoDB | 7 - 8 |
| 5.1.2 | Redis | 7.4 - 8.0 |
| 5.1.2 | Elasticsearch | 8 |
| 5.1.2 | Angular (Web SDK) | 19.x |
| 5.1.2 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.3
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.3

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.3 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.2 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.2 → 5.1.3**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **process-engine** | **9.70.1** | 9.67.0 | 9.64.3 | 9.63.0 |
| **admin** | **9.70.2** | 9.68.1 | 9.66.5 | 9.65.0 |
| **designer** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **cms-core** | **9.41.1** | 9.39.0 | 9.36.3 | 9.35.0 |
| **scheduler-core** | **9.30.1** | 9.28.1 | 9.26.1 | 9.25.0 |
| **events-gateway** | **9.31.2** | 9.29.0 | 9.26.1 | 9.25.0 |
| **notification-plugin** | **9.34.1** | 9.32.0 | 9.29.1 | 9.28.0 |
| **document-plugin** | **9.39.1** | 9.37.1 | 9.35.1 | 9.34.0 |
| **task-management-plugin** | **9.38.2** | 9.36.1 | 9.34.2 | 9.33.0 |
| **data-search** | **9.27.1** | 9.25.1 | 9.23.1 | 9.22.0 |
| **audit-core** | **9.35.1** | 9.33.0 | 9.30.1 | 9.29.1 |
| **advancing-controller** | **9.30.2** | 9.28.0 | 9.25.1 | 9.24.0 |
| **integration-designer** | **9.54.1** | 9.52.1 | 9.50.0 | 9.49.1 |
| **application-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **runtime-manager** | **9.77.2** | 9.75.1 | 9.73.6 | 9.72.0 |
| **data-sync** | **9.28.1** | 9.26.0 | 9.22.1 | 9.21.0 |
| **authorization-system** | **9.38.1** | 9.36.1 | 9.34.2 | 9.33.0 |
| **nosql-db-runner** | **9.26.1** | 9.24.1 | 9.22.1 | 9.21.0 |

### Renderers

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/angular-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/react-ui-toolkit** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-sdk** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **@flowx/core-theme** | **9.163.0** | 9.161.3 | 9.159.5 | 9.153.6 |
| **iOS renderer** | **9.0.8** | 9.0.7 | 9.0.5 | 9.0.4 |
| **Android renderer** | **9.0.6** | 9.0.5 | 9.0.3 | 9.0.2 |

### Plugins

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.3 | 5.1.2 | 5.1.1 | 5.1.0 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.7** | 9.2.6 | 9.2.5 | 9.2.4 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.3.0 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.3 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### No configuration changes required

> [!TIP]
>
> No environment variable changes required\
> No database migrations\
> No breaking changes\
> Compatible with existing 5.1.2 processes and configurations

### Optional configuration

A new optional environment variable is available for process-engine:

| Variable | Description | Default |
| - | - | - |
| `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from platform components | Falls back to `KAFKA_TOPIC_PATTERN` |

> [!NOTE]
>
> This allows connectors to use custom topic patterns without affecting other components like document-plugin, data-search, and cms-core that use `ai.flowx.engine.receive.*`.

### What's included in 5.1.3

This maintenance release includes:

* **Security fixes**
* **Bug fixes** addressing customer-reported issues

For detailed information on all changes, see the [FlowX.AI 5.1.3 Release Notes](./v5.1.3-january-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.3 | Keycloak | 26+ |
| 5.1.3 | Kafka | 3.8 - 3.9 |
| 5.1.3 | PostgreSQL | 16 - 17 |
| 5.1.3 | Oracle Database | 21c, 23ai |
| 5.1.3 | MongoDB | 7 - 8 |
| 5.1.3 | Redis | 7.4 - 8.0 |
| 5.1.3 | Elasticsearch | 8 |
| 5.1.3 | Angular (Web SDK) | 19.2 |
| 5.1.3 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.4
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.4

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.4 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.3 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.3 → 5.1.4**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **process-engine** | **9.72.2** | 9.70.1 | 9.67.0 | 9.64.3 |
| **admin** | **9.72.0** | 9.70.2 | 9.68.1 | 9.66.5 |
| **designer** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **cms-core** | **9.43.1** | 9.41.1 | 9.39.0 | 9.36.3 |
| **scheduler-core** | **9.32.0** | 9.30.1 | 9.28.1 | 9.26.1 |
| **events-gateway** | **9.33.0** | 9.31.2 | 9.29.0 | 9.26.1 |
| **notification-plugin** | **9.36.0** | 9.34.1 | 9.32.0 | 9.29.1 |
| **document-plugin** | **9.41.1** | 9.39.1 | 9.37.1 | 9.35.1 |
| **task-management-plugin** | **9.40.0** | 9.38.2 | 9.36.1 | 9.34.2 |
| **data-search** | **9.29.0** | 9.27.1 | 9.25.1 | 9.23.1 |
| **audit-core** | **9.37.0** | 9.35.1 | 9.33.0 | 9.30.1 |
| **advancing-controller** | **9.32.0** | 9.30.2 | 9.28.0 | 9.25.1 |
| **integration-designer** | **9.56.0** | 9.54.1 | 9.52.1 | 9.50.0 |
| **application-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **runtime-manager** | **9.79.1** | 9.77.2 | 9.75.1 | 9.73.6 |
| **data-sync** | **9.30.1** | 9.28.1 | 9.26.0 | 9.22.1 |
| **authorization-system** | **9.40.1** | 9.38.1 | 9.36.1 | 9.34.2 |
| **nosql-db-runner** | **9.28.0** | 9.26.1 | 9.24.1 | 9.22.1 |

### Renderers

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/angular-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/react-ui-toolkit** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-sdk** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **@flowx/core-theme** | **9.163.6** | 9.163.0 | 9.161.3 | 9.159.5 |
| **iOS renderer** | **9.0.9** | 9.0.8 | 9.0.7 | 9.0.5 |
| **Android renderer** | **9.0.7** | 9.0.6 | 9.0.5 | 9.0.3 |

### Plugins

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.4 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.4 | 5.1.3 | 5.1.2 | 5.1.1 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.8** | 9.2.7 | 9.2.6 | 9.2.5 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.4 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.3 processes and configurations

#### New environment variables (optional)

The following optional environment variables have been added for the **process-engine** to configure config params caching:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` | Time-to-live in seconds for cached configuration params | `120` | process-engine |
| `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES` | Maximum number of entries in the config params cache | `500` | process-engine |

> [!NOTE]
>
> These variables are optional. If not configured, the default values will be used. Adjust these values based on how frequently your configuration changes and your memory constraints.
>
> For more details, see [Engine Setup - Config params cache](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).

### What's included in 5.1.4

This maintenance release includes:

* **Security patches** addressing identified vulnerabilities
* **Bug fixes** addressing customer-reported issues
* **Platform improvements** including cache improvements, Kafka environment variable alignment, SSE metrics enhancements, and infrastructure updates

For detailed information on all changes, see the [FlowX.AI 5.1.4 Release Notes](./v5.1.4-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.4 | Keycloak | 26+ |
| 5.1.4 | Kafka | 3.8 - 3.9 |
| 5.1.4 | PostgreSQL | 16 - 17 |
| 5.1.4 | Oracle Database | 21c, 23ai |
| 5.1.4 | MongoDB | 7 - 8 |
| 5.1.4 | Redis | 7.4 - 8.0 |
| 5.1.4 | Elasticsearch | 8 |
| 5.1.4 | Angular (Web SDK) | 19.2 |
| 5.1.4 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.5
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.5

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.5 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.4 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.4 → 5.1.5**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **process-engine** | **9.72.5** | 9.72.2 | 9.70.1 | 9.67.0 |
| **admin** | **9.72.2** | 9.72.0 | 9.70.2 | 9.68.1 |
| **designer** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **cms-core** | **9.43.3** | 9.43.1 | 9.41.1 | 9.39.0 |
| **scheduler-core** | **9.32.2** | 9.32.0 | 9.30.1 | 9.28.1 |
| **events-gateway** | **9.33.2** | 9.33.0 | 9.31.2 | 9.29.0 |
| **notification-plugin** | **9.36.2** | 9.36.0 | 9.34.1 | 9.32.0 |
| **document-plugin** | **9.41.3** | 9.41.1 | 9.39.1 | 9.37.1 |
| **task-management-plugin** | **9.40.2** | 9.40.0 | 9.38.2 | 9.36.1 |
| **data-search** | **9.29.2** | 9.29.0 | 9.27.1 | 9.25.1 |
| **audit-core** | **9.37.2** | 9.37.0 | 9.35.1 | 9.33.0 |
| **advancing-controller** | **9.32.1** | 9.32.0 | 9.30.2 | 9.28.0 |
| **integration-designer** | **9.56.2** | 9.56.0 | 9.54.1 | 9.52.1 |
| **application-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **runtime-manager** | **9.79.3** | 9.79.1 | 9.77.2 | 9.75.1 |
| **data-sync** | **9.30.2** | 9.30.1 | 9.28.1 | 9.26.0 |
| **authorization-system** | **9.40.2** | 9.40.1 | 9.38.1 | 9.36.1 |
| **nosql-db-runner** | **9.28.2** | 9.28.0 | 9.26.1 | 9.24.1 |

### Renderers

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/angular-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/react-ui-toolkit** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-sdk** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **@flowx/core-theme** | **9.163.12** | 9.163.6 | 9.163.0 | 9.161.3 |
| **iOS renderer** | **9.0.10** | 9.0.9 | 9.0.8 | 9.0.7 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.6 | 9.0.5 |

### Plugins

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.4 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.5 | 5.1.4 | 5.1.3 | 5.1.2 |
| - | - | - | - | - |
| **ai-assistant** | **9.2.9** | 9.2.8 | 9.2.7 | 9.2.6 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale. |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes. |
| **[Dgraph](https://docs.dgraph.io/)** | A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability. |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.5 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!TIP]
>
> No new environment variables
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.4 processes and configurations

### What's included in 5.1.5

This maintenance release includes:

* **Bug fixes** for process loop rendering issues in the Angular renderer
* **Bug fixes** for subprocess output data not being returned from embedded processes

For detailed information on all changes, see the [FlowX.AI 5.1.5 Release Notes](./v5.1.5-february-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.5 | Keycloak | 26+ |
| 5.1.5 | Kafka | 3.8 - 3.9 |
| 5.1.5 | PostgreSQL | 16 - 17 |
| 5.1.5 | Oracle Database | 21c, 23ai |
| 5.1.5 | MongoDB | 7 - 8 |
| 5.1.5 | Redis | 7.4 - 8.0 |
| 5.1.5 | Elasticsearch | 8 |
| 5.1.5 | Angular (Web SDK) | 19.2 |
| 5.1.5 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.6
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.6

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.6 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.5 with no breaking changes or configuration updates required.

> [card] Upgrade Path
>
> **5.1.5 → 5.1.6**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **process-engine** | **9.72.7** | 9.72.5 | 9.72.2 | 9.70.1 |
| **admin** | **9.72.4** | 9.72.2 | 9.72.0 | 9.70.2 |
| **designer** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **cms-core** | **9.43.5** | 9.43.3 | 9.43.1 | 9.41.1 |
| **scheduler-core** | **9.32.4** | 9.32.2 | 9.32.0 | 9.30.1 |
| **events-gateway** | **9.33.4** | 9.33.2 | 9.33.0 | 9.31.2 |
| **notification-plugin** | **9.36.4** | 9.36.2 | 9.36.0 | 9.34.1 |
| **document-plugin** | **9.41.5** | 9.41.3 | 9.41.1 | 9.39.1 |
| **task-management-plugin** | **9.40.4** | 9.40.2 | 9.40.0 | 9.38.2 |
| **data-search** | **9.29.4** | 9.29.2 | 9.29.0 | 9.27.1 |
| **audit-core** | **9.37.4** | 9.37.2 | 9.37.0 | 9.35.1 |
| **advancing-controller** | **9.32.3** | 9.32.1 | 9.32.0 | 9.30.2 |
| **integration-designer** | **9.56.3** | 9.56.2 | 9.56.0 | 9.54.1 |
| **application-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **runtime-manager** | **9.79.6** | 9.79.3 | 9.79.1 | 9.77.2 |
| **data-sync** | **9.30.4** | 9.30.2 | 9.30.1 | 9.28.1 |
| **authorization-system** | **9.40.3** | 9.40.2 | 9.40.1 | 9.38.1 |
| **nosql-db-runner** | **9.28.4** | 9.28.2 | 9.28.0 | 9.26.1 |

### Renderers

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/angular-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/react-ui-toolkit** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-sdk** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **@flowx/core-theme** | **9.164.2** | 9.163.12 | 9.163.6 | 9.163.0 |
| **iOS renderer** | **9.0.11** | 9.0.10 | 9.0.9 | 9.0.8 |
| **Android renderer** | 9.0.7 | 9.0.7 | 9.0.7 | 9.0.6 |

### Plugins

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.4 | 0.2.4 |

### AI Platform

| Component | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.8 | 9.2.7 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.6 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> This release introduces optional environment variables for the process engine retry mechanism. These are not required — defaults work for most deployments.

#### Process engine — retry configuration (optional)

The following optional environment variables configure the exponential backoff with Equal Jitter strategy used for optimistic locking retries:

| Environment Variable | Description | Default Value | Component |
| - | - | - | - |
| `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` | process-engine |
| `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` | process-engine |
| `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` | process-engine |

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.5 processes and configurations

### What's included in 5.1.6

This maintenance release includes:

* **Bug fixes** for React renderer: modals, sliders, datepicker, selectors, disabled state, and accessibility
* **Bug fixes** for Angular + React renderer: card accordion height, focus outlines, button icon layout
* **Bug fix** for process engine advancing getting stuck on pod crash
* **Bug fix** for connection leak in application-manager export/import
* **Improvement** for configurable retry mechanism with exponential backoff
* **Security patches** across all platform components

For detailed information on all changes, see the [FlowX.AI 5.1.6 Release Notes](./v5.1.6-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.6 | Keycloak | 26+ |
| 5.1.6 | Kafka | 3.8 - 3.9 |
| 5.1.6 | PostgreSQL | 16 - 17 |
| 5.1.6 | Oracle Database | 21c, 23ai |
| 5.1.6 | MongoDB | 7 - 8 |
| 5.1.6 | Redis | 7.4 - 8.0 |
| 5.1.6 | Elasticsearch | 8 |
| 5.1.6 | Angular (Web SDK) | 19.2 |
| 5.1.6 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.7
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.7

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.7 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.6 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.6 → 5.1.7**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **process-engine** | **9.73.1** | 9.72.7 | 9.72.5 | 9.72.2 |
| **admin** | **9.73.1** | 9.72.4 | 9.72.2 | 9.72.0 |
| **designer** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **cms-core** | **9.44.2** | 9.43.5 | 9.43.3 | 9.43.1 |
| **scheduler-core** | **9.33.1** | 9.32.4 | 9.32.2 | 9.32.0 |
| **events-gateway** | **9.34.1** | 9.33.4 | 9.33.2 | 9.33.0 |
| **notification-plugin** | **9.37.1** | 9.36.4 | 9.36.2 | 9.36.0 |
| **document-plugin** | **9.42.2** | 9.41.5 | 9.41.3 | 9.41.1 |
| **task-management-plugin** | **9.41.1** | 9.40.4 | 9.40.2 | 9.40.0 |
| **data-search** | **9.30.1** | 9.29.4 | 9.29.2 | 9.29.0 |
| **audit-core** | **9.38.1** | 9.37.4 | 9.37.2 | 9.37.0 |
| **advancing-controller** | **9.33.1** | 9.32.3 | 9.32.1 | 9.32.0 |
| **integration-designer** | **9.57.1** | 9.56.3 | 9.56.2 | 9.56.0 |
| **application-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **runtime-manager** | **9.80.2** | 9.79.6 | 9.79.3 | 9.79.1 |
| **data-sync** | **9.31.1** | 9.30.4 | 9.30.2 | 9.30.1 |
| **authorization-system** | **9.41.1** | 9.40.3 | 9.40.2 | 9.40.1 |
| **nosql-db-runner** | **9.29.1** | 9.28.4 | 9.28.2 | 9.28.0 |

### Renderers

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.163.12 | 9.163.6 |
| **iOS renderer** | **9.0.12** | 9.0.11 | 9.0.10 | 9.0.9 |
| **Android renderer** | **9.0.13** | 9.0.7 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.17 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.4 |

### AI Platform

| Component | 5.1.7 | 5.1.6 | 5.1.5 | 5.1.4 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.8 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.7 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.6 processes and configurations

### What's included in 5.1.7

This maintenance release includes:

* **Bug fix** for build reimport failures with manifest issues
* **Security patches** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.7 Release Notes](./v5.1.7-march-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.7 | Keycloak | 26+ |
| 5.1.7 | Kafka | 3.8 - 3.9 |
| 5.1.7 | PostgreSQL | 16 - 17 |
| 5.1.7 | Oracle Database | 21c, 23ai |
| 5.1.7 | MongoDB | 7 - 8 |
| 5.1.7 | Redis | 7.4 - 8.0 |
| 5.1.7 | Elasticsearch | 8 |
| 5.1.7 | Angular (Web SDK) | 19.2 |
| 5.1.7 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.8
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.8

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.8 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.7 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.7 → 5.1.8**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **process-engine** | **9.74.4** | 9.73.1 | 9.72.7 | 9.72.5 |
| **admin** | **9.74.4** | 9.73.1 | 9.72.4 | 9.72.2 |
| **designer** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **cms-core** | **9.45.4** | 9.44.2 | 9.43.5 | 9.43.3 |
| **scheduler-core** | **9.34.4** | 9.33.1 | 9.32.4 | 9.32.2 |
| **events-gateway** | **9.35.4** | 9.34.1 | 9.33.4 | 9.33.2 |
| **notification-plugin** | **9.38.4** | 9.37.1 | 9.36.4 | 9.36.2 |
| **document-plugin** | **9.43.4** | 9.42.2 | 9.41.5 | 9.41.3 |
| **task-management-plugin** | **9.42.4** | 9.41.1 | 9.40.4 | 9.40.2 |
| **data-search** | **9.31.4** | 9.30.1 | 9.29.4 | 9.29.2 |
| **audit-core** | **9.39.4** | 9.38.1 | 9.37.4 | 9.37.2 |
| **advancing-controller** | **9.34.4** | 9.33.1 | 9.32.3 | 9.32.1 |
| **integration-designer** | **9.58.5** | 9.57.1 | 9.56.3 | 9.56.2 |
| **application-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **runtime-manager** | **9.81.4** | 9.80.2 | 9.79.6 | 9.79.3 |
| **data-sync** | **9.32.3** | 9.31.1 | 9.30.4 | 9.30.2 |
| **authorization-system** | **9.42.4** | 9.41.1 | 9.40.3 | 9.40.2 |
| **nosql-db-runner** | **9.30.4** | 9.29.1 | 9.28.4 | 9.28.2 |

### Renderers

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/angular-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/react-ui-toolkit** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-sdk** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **@flowx/core-theme** | 9.164.2 | 9.164.2 | 9.164.2 | 9.163.12 |
| **iOS renderer** | **9.0.19** | 9.0.12 | 9.0.11 | 9.0.10 |
| **Android renderer** | **9.0.19** | 9.0.13 | 9.0.7 | 9.0.7 |

### Plugins

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.17 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.8 | 5.1.7 | 5.1.6 | 5.1.5 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

> [!WARNING]
>
> **A configuration that blocks startup is a required configuration.** If a service fails to start and its logs report a missing or empty configuration value, treat that value as required and provide it, even when it is not flagged as required here. These guides document the most common variables; they are not an exhaustive list of every value your deployment topology requires.

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.8 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.7 processes and configurations

### What's included in 5.1.8

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.8 Release Notes](./v5.1.8-april-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.8 | Keycloak | 26+ |
| 5.1.8 | Kafka | 3.8 - 3.9 |
| 5.1.8 | PostgreSQL | 16 - 17 |
| 5.1.8 | Oracle Database | 21c, 23ai |
| 5.1.8 | MongoDB | 7 - 8 |
| 5.1.8 | Redis | 7.4 - 8.0 |
| 5.1.8 | Elasticsearch | 8 |
| 5.1.8 | Angular (Web SDK) | 19.2 |
| 5.1.8 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.9
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/deployment-guidelines-v5.1.9

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Upgrade overview

FlowX.AI 5.1.9 is a maintenance release for the 5.1.x LTS line. This release can be deployed as a direct upgrade from 5.1.8 with no breaking changes.

> [card] Upgrade Path
>
> **5.1.8 → 5.1.9**: Direct upgrade with no breaking changes

## Component versions

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **process-engine** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.7 |
| **admin** | **9.75.3** | 9.74.4 | 9.73.1 | 9.72.4 |
| **designer** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **cms-core** | **9.46.2** | 9.45.4 | 9.44.2 | 9.43.5 |
| **scheduler-core** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.4 |
| **events-gateway** | **9.36.2** | 9.35.4 | 9.34.1 | 9.33.4 |
| **notification-plugin** | **9.39.2** | 9.38.4 | 9.37.1 | 9.36.4 |
| **document-plugin** | **9.44.2** | 9.43.4 | 9.42.2 | 9.41.5 |
| **task-management-plugin** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.4 |
| **data-search** | **9.32.2** | 9.31.4 | 9.30.1 | 9.29.4 |
| **audit-core** | **9.40.2** | 9.39.4 | 9.38.1 | 9.37.4 |
| **advancing-controller** | **9.35.2** | 9.34.4 | 9.33.1 | 9.32.3 |
| **integration-designer** | **9.59.3** | 9.58.5 | 9.57.1 | 9.56.3 |
| **application-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **runtime-manager** | **9.82.2** | 9.81.4 | 9.80.2 | 9.79.6 |
| **data-sync** | **9.33.2** | 9.32.3 | 9.31.1 | 9.30.4 |
| **authorization-system** | **9.43.2** | 9.42.4 | 9.41.1 | 9.40.3 |
| **nosql-db-runner** | **9.31.2** | 9.30.4 | 9.29.1 | 9.28.4 |

### Renderers

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **@flowx/angular-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/angular-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/react-ui-toolkit** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-sdk** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **@flowx/core-theme** | **9.164.4** | 9.164.2 | 9.164.2 | 9.164.2 |
| **iOS renderer** | **9.0.20** | 9.0.19 | 9.0.12 | 9.0.11 |
| **Android renderer** | **9.0.24** | 9.0.19 | 9.0.13 | 9.0.7 |

### Plugins

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ocr-plugin** | 1.0.19 | 1.0.19 | 1.0.19 | 1.0.17 |
| **reporting-plugin** | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 |

### AI Platform

| Component | 5.1.9 | 5.1.8 | 5.1.7 | 5.1.6 |
| - | - | - | - | - |
| **ai-assistant** | 9.2.9 | 9.2.9 | 9.2.9 | 9.2.9 |
| **di-platform** | 9.3.1 | 9.3.1 | 9.3.1 | 9.3.1 |
| **ai-platform-ai-developer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-connected-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-knowledge-graph** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agents** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-conversations** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-models** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-tenants** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-planner** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-analyst** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-ai-designer** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-agent-builder** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |
| **ai-platform-binaries** | 9.4.2 | 9.4.2 | 9.4.2 | 9.4.2 |

### Embedded components

Embedded components are third-party software packaged with the platform.

| Component | Description |
| - | - |
| **[SpiceDB](https://authzed.com/spicedb)** | **An open-source, database-backed system for managing fine-grained authorization. Provides a relationship-based access control model (ReBAC) and powers complex authorization at scale.** |
| **[SpiceDB Operator](https://github.com/authzed/spicedb-operator)** | **A Kubernetes operator that automates the deployment, configuration, and lifecycle management of SpiceDB instances. It streamlines operational tasks such as upgrades, scaling, and configuration changes.** |
| **[Dgraph](https://docs.dgraph.io/)** | **A distributed, open-source graph database designed for high-performance queries and real-time graph processing. Supports GraphQL natively and is optimized for horizontal scalability.** |

> [!NOTE]
>
> For previous FlowX.AI releases, please refer to the [Release Notes overview](../../overview).

## Deployment notes

### Standard deployment

This maintenance release follows standard FlowX.AI deployment procedures with no special considerations:

1. Update container images to 5.1.9 versions listed in the table
2. Deploy services using your standard deployment process
3. Verify deployment via **FlowX Designer > Platform Status**

### Configuration changes

> [!NOTE]
>
> No configuration changes are required for this release.

> [!TIP]
>
> No required configuration changes
> No database migrations
> No breaking changes
> Compatible with existing 5.1.8 processes and configurations

### What's included in 5.1.9

This maintenance release includes:

* **Security patches** and dependency upgrades across platform components
* **Stability fixes** across platform components

For detailed information on all changes, see the [FlowX.AI 5.1.9 Release Notes](./v5.1.9-may-2026).

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.9 | Keycloak | 26+ |
| 5.1.9 | Kafka | 3.8 - 3.9 |
| 5.1.9 | PostgreSQL | 16 - 17 |
| 5.1.9 | Oracle Database | 21c, 23ai |
| 5.1.9 | MongoDB | 7 - 8 |
| 5.1.9 | Redis | 7.4 - 8.0 |
| 5.1.9 | Elasticsearch | 8 - 9 |
| 5.1.9 | Angular (Web SDK) | 19.2 |
| 5.1.9 | React (Web SDK) | 18.x |


# Deployment guidelines v5.1.0
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/deployment-guidelines-v5.1

> [!NOTE]
>
> Do not forget, after upgrading to a new platform version, always ensure that your installed component versions match the versions specified in the release notes. To verify this, navigate to **FlowX.AI Designer > Platform Status**.

![Platform Status screen showing component versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/platform_status.png)

## Component versions

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **process-engine** | **9.63.0** | 9.29.2 | 8.23.2 | 8.22.3 | 8.21.1 | 8.17.0 | 8.15.2 | 8.13.0 | 8.9.0 | 8.5.1 | 8.3.1 | 8.1.1 | 8.0.2 | 6.1.4 | 6.1.3 | 6.1.2 | 6.0.3 | 5.10.3 | 4.3.5-2v11 | 4.3.5-2v6 | 4.3.5-2v2 | 4.3.5-2v1 | 4.3.5 | 4.3.2 | 4.3.1 | 4.1.0 | 3.6.0 | 2.2.1 | 2.1.2 | 2.0.7 | |
| **admin** | **9.65.0** | 9.25.2 | 7.17.3 | 7.16.3 | 7.15.2 | 7.12.2 | 7.9.2 | 7.8.13 | 7.8.5 | 7.7.6 | 7.5.1 | 7.2.6 | 7.2.3 | 5.1.6 | 5.1.5 | 5.1.4 | 5.1.3 | 5.0.9 | 4.6.10 | 3.3.19-6 | 3.3.19-4 | 3.3.19-3 | 3.3.19-1 | 3.3.19 | 3.3.10 | 3.3.7 | 3.1.1 | 2.5.2 | 2.2.2 | 2.1.3 | 2.0.8 |
| **designer** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **cms-core** | **9.35.0** | 9.21.2 | 5.10.3 | 5.9.2 | 5.8.2 | 5.5.1 | 5.4.16 | 5.4.12 | 5.4.8 | 5.3.3 | 5.2.11 | 5.2.2 | 5.1.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.1 | 2.2.5 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.9 | 1.3.6 | 1.3.0 | 1.2.0 | 1.0.3 | 1.0.2 |
| **scheduler-core** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.13 | 5.0.11 | 5.0.10 | 5.0.4 | 5.0.2 | 5.0.0 | 5.0.0 | 3.0.2 | 3.0.1 | 3.0.1 | 3.0.1 | 3.0.0 | 2.1.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.2.4 | 1.1.0 | 1.0.4 | 1.0.4 | 1.0.4 | 1.0.1 |
| **events-gateway** | **9.25.0** | 9.12.0 | 5.6.2 | 5.5.2 | 5.4.0 | 5.1.1 | 5.0.19 | 5.0.17 | 5.0.16 | 5.0.7 | 5.0.5 | 5.0.2 | 5.0.2 | 3.0.3 | 3.0.2 | 3.0.2 | 3.0.2 | 3.0.0 | 2.0.4 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.1.0 | 1.0.6 | 1.0.2 | - | - | - |
| **notification-plugin** | **9.28.0** | 9.14.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.2.1 | 6.1.15 | 6.1.13 | 6.1.12 | 6.1.3 | 6.1.0 | 6.0.3 | 6.0.3 | 4.0.4 | 4.0.3 | 4.0.3 | 4.0.3 | 4.0.1 | 3.0.6 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.9 | 2.0.8 | 2.0.8 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.3 | 2.0.1 |
| **document-plugin** | **9.34.0** | 9.17.2 | 6.9.2 | 6.8.2 | 6.7.0 | 6.4.1 | 6.3.18 | 6.3.16 | 6.3.13 | 6.3.4 | 6.3.1 | 6.0.3 | 6.0.3 | 4.0.3 | 4.0.2 | 4.0.2 | 4.0.2 | 4.0.0 | 3.0.6 | 2.0.10-1 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.10 | 2.0.8 | 2.0.8 | 2.0.6 | 2.0.4 | 2.0.3 | 2.0.3 | 2.0.2 |
| **task-management-plugin** | **9.33.0** | 9.14.2 | 7.8.2 | 7.7.2 | 7.6.0 | 7.3.1 | 7.2.17 | 7.2.15 | 7.2.14 | 7.2.6 | 7.2.2 | 7.0.3 | 7.0.3 | 5.0.5 | 5.0.4 | 5.0.4 | 5.0.4 | 5.0.2 | 4.0.5 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.3 | 3.0.0 | 2.1.2 | 1.0.4 | 1.0.4 | 1.0.1 |
| **data-search** | **9.22.0** | 9.12.1 | 4.6.2 | 4.5.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.13 | 4.0.6 | 4.0.4 | 4.0.0 | 4.0.0 | 2.0.5 | 2.0.4 | 2.0.4 | 2.0.4 | 2.0.3 | 1.0.6 | 0.2.8 | 0.2.8 | 0.2.8 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.6 | 0.2.3 | 0.2.0 | 0.1.4 | 0.1.4 | 0.1.3 |
| **audit-core** | **9.29.1** | 9.15.2 | 6.7.2 | 6.6.2 | 6.5.0 | 6.1.1 | 6.0.17 | 6.0.15 | 6.0.14 | 6.0.6 | 6.0.4 | 6.0.0 | 6.0.0 | 4.0.5 | 4.0.4 | 4.0.4 | 4.0.4 | 4.0.3 | 3.1.4 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.2.0 | 2.1.3 | 2.1.3 | 2.1.0 | 1.0.6 | 1.0.5 | 1.0.4 | 1.0.1 |
| **advancing-controller** | **9.24.0** | 9.11.0 | 4.6.2 | 4.6.2 | 4.4.0 | 4.1.1 | 4.0.16 | 4.0.14 | 4.0.12 | 4.0.5 | 4.0.3 | 4.0.0 | 4.0.0 | 2.0.3 | 2.0.2 | 2.0.2 | 2.0.2 | 2.0.0 | 1.1.4 | 0.3.5-1 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.5 | 0.3.2 | 0.3.0 | 0.1.4 | 0.1.4 | 0.1.2 |
| **integration-designer** | **9.49.1** | 9.26.2 | 2.15.3 | 2.14.2 | 2.13.0 | 2.9.0 | 2.7.2 | 2.6.0 | 2.3.16 | 2.3.9 | 2.3.2 | 2.0.4 | 2.0.1 | | | | | | | | | | | | | | | | | | |
| **application-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **runtime-manager** | **9.72.0** | 9.27.3 | 2.22.3 | 2.21.2 | 2.20.2 | 2.17.2 | 2.15.6 | 2.14.0 | 2.10.9 | 2.9.4 | 2.6.0 | 2.0.25 | 2.0.18 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **data-sync** | **9.21.0** | 9.11.0 | 2.9.2 | 2.8.1 | 2.7.1 | 2.4.1 | 2.3.2 | 2.2.11 | 2.2.9 | 2.2.2 | 2.1.0 | 2.0.2 | 2.0.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **authorization-system** | **9.33.0** | 9.14.2 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **nosql-db-runner** | **9.21.0** | 9.11.0 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |

### Embedded components

* **SpiceDB**
* **DGraph**

### Renderers

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **@flowx/angular-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | | | | | | | | | | | | | | | | |
| **@flowx/angular-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | 4.17.1-5 | 4.17.1-3 | 4.17.1-2 | 4.17.1 | 4.17.1 | 4.0.1 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **@flowx/react-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/react-ui-toolkit** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-sdk** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **@flowx/core-theme** | **9.153.6** | 9.69.0 | 5.98.0 | 5.97.1 | 5.96.1 | 5.95.1 | 5.93.1 | 5.91.2 | 5.84.5 | 5.83.8 | 5.80.6 | 5.69.3 | 5.64.5 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **paperflow-web-components** | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 3.35.18-5 | 3.35.18-5 | 3.35.18-3 | 3.35.18-2 | 3.35.18-1 | 3.35.18 | 3.35.9 | 3.35.6 | 3.33.2 | 3.28.11 | 3.21.1 | 3.15.1 | 3.2.1 |
| **iOS renderer** | **9.0.4** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.29 | 4.0.21 | 4.0.19 | 4.0.14 | 4.0.7 | 4.0.7 | 4.0.5 | 4.0.4 | 4.0.3 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.20 | 3.0.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.3.0 | 2.1.0 | 2.0.1 | 2.0.0 | 2.0.0 |
| **Android renderer** | **9.0.2** | 9.0.0 | 4.0.29 | 4.0.29 | 4.0.28 | 4.0.24 | 4.0.23 | 4.0.15 | 4.0.13 | 4.0.13 | 4.0.12 | 4.0.11 | 4.0.9 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.23 | 3.0.0 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.1.4 | 2.0.1 | 2.0.1 | 2.0.1 | 2.0.1 |

### Plugins

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ocr-plugin** | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.17 | 1.0.15 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.12 | 1.0.8 | 1.0.8 | 1.0.2 | 0.1.33 | 0.1.33 |
| **reporting-plugin** | **0.2.4** | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.2.0 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.12 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.6 | 0.1.5 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.1.2 | 0.0.40 | 0.0.40 | 0.0.40 | 0.0.39 |

## AI Platform

| Component | 5.1.0 | 5.0.0 | 4.7.8 | 4.7.7 | 4.7.6 | 4.7.5 | 4.7.4 | 4.7.3 | 4.7.2 | 4.7.1 | 4.7.0 | 4.6.1 | 4.6.0 | 4.1.4 | 4.1.3 | 4.1.2 | 4.1.1 | 4.1 | 4.0 | 3.4.7 | 3.4.6 | 3.4.5 | 3.4.4 | 3.4.3 | 3.4.2 | 3.4.1 | 3.4.0 | 3.3.0 | 3.2.0 | 3.1.0 | 3.0.0 |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-assistant** | **9.2.4** | 9.2.3 | 1.8.22 | 1.8.21 | 1.8.19 | 1.8.18 | 1.8.17 | 1.8.12 | 1.8.9 | 1.8.2 | 1.7.2 | 1.6.15 | 1.6.9 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **di-platform** | **9.3.1** | 9.0.12 | 1.4.6 | 1.4.6 | 1.4.5 | 1.4.5 | 1.4.5 | 1.4.3 | 1.4.1 | 1.2.35 | 1.2.31 | 1.2.27 | 1.2.24 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | |
| **ai-developer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **connected-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **knowledge-graph** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **agents** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **conversations** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **models** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **tenants** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **planner** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-designer** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| **ai-analyst** | **9.3.0** | 9.0.1 | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | - | - | - | - | - | - | - | - | - | - | - | - | - | - |

## Third-party supported component versions

| FlowX.AI Version | 3rd Party Dependency | Supported Versions |
| - | - | - |
| 5.1.0 | Keycloak | 26+ |
| 5.1.0 | Kafka | 3.8 - 3.9 |
| 5.1.0 | PostgreSQL | 16 - 17 |
| 5.1.0 | Oracle Database | 21c, 23ai |
| 5.1.0 | MongoDB | 7 - 8 |
| 5.1.0 | Redis | 7.4 - 8.0 |
| 5.1.0 | Elasticsearch | 8 - 9 |
| 5.1.0 | Angular (Web SDK) | 19.x |
| 5.1.0 | React (Web SDK) | 18.x |

> [!WARNING]
>
> Starting FlowX 5.0, the following versions of 3rd Party Dependencies are no longer be supported:
>
> * Keycloak versions older than 26
> * Kafka versions older than 3.8
> * Redis versions older than 7.4


# Post-deployment configuration
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/configuration-and-migration

This section contains the steps in order that we recommend for post-deployment configuration of FlowX.AI.

## Redis cache clearing

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Endpoint

`POST {{baseUrlAdmin}}/api/internal/cache/clear`

### Body:

```json theme={"dark"}
{
    "cacheNames": [
        "flowx:core:cache"
    ]
}
```

> [card] [Clear cache endpoint](/5.1/docs/api/clear-cache)

## Authentication & authorization

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [!NOTE]
>
> This step ensures business continuity by maintaining user access to existing FlowX.AI assets in the new workspace-based architecture.

### Role mapping guide

> [!WARNING]
>
> FlowX.AI 4.7.x roles stored in Keycloak are not automatically migrated. Manual role assignment is required.

> [card] Legacy Role Mapping
>
> **FlowX.AI 4.7.x** → **FlowX.AI 5.1.0**
>
> * `FLOWX_ADMIN` → `workspace_admin`
> * `FLOWX_CONFIGURATOR` → `workspace_user` or `project_editor`
> * `FLOWX_UI_DESIGNER` → `theme_editor`
> * `FLOWX_VIEWER` → `project_viewer`
> * Custom Keycloak roles → Manual review required

> [card] Migration Considerations
>
> **Important Changes**
>
> * Roles are now workspace-scoped
> * More granular permission structure
> * Database-stored instead of token-based
> * New role hierarchy requires review

### Migration process

**1. Inventory Current Roles**

Document all existing Keycloak roles and their assigned users before migration

**2. Map to New Structure**

Determine appropriate FlowX.AI 5.1.0 roles for each user based on their current access needs

**3. Plan Workspace Structure**

Decide how to organize users into workspaces based on business requirements

**4. Assign New Roles**

Use the FlowX.AI 5.1.0 interface to assign appropriate roles to users in their respective workspaces

**5. Validate Access**

Test user access to ensure proper permissions are granted and restrictions are enforced

### For existing customers

**1. Automatic Default Workspace Creation**

The auth-system will automatically:

* Create default organization and workspace
* Import the admin user from Keycloak
* Assign organization admin privileges
* Set up default roles and groups

**2. data-sync Migration Process**

The data-sync service will:

* Migrate existing projects from app-manager database to CAS database
* Assign all existing resources to the default workspace
* Preserve all existing functionality
* Require temporary write access to CAS database

**Note**: This is the only exception to the exclusive write access rule.

**3. Process Instance Migration**

Process instance migration occurs automatically when the platform starts:

* **Active process instances**: Automatically migrated to the default workspace during platform startup
* **Inactive process instances**: Require a separate migration script that runs post-migration

> [!WARNING]
>
> For clients who need inactive process instances migrated, a migration script will be provided to run post-migration.

***

## Header migration: Fx-BuildId to Fx-Build-App-Version-Id

### Background

The header `Fx-BuildId` has been renamed to `Fx-Build-App-Version-Id` to accurately reflect that it contains an application version identifier, not a build identifier.

### Migration strategy

During the transition period, both headers are supported:

* **New messages**: Include `Fx-Build-App-Version-Id` with the application version ID
* **Legacy support**: `Fx-BuildId` is still accepted for backward compatibility
* **Priority**: FlowX.AI platform reads `Fx-Build-App-Version-Id` first, then falls back to `Fx-BuildId` if not present

### Implementation guidelines

1. **New integrations**: Use `Fx-Build-App-Version-Id` header
2. **Existing integrations**: Will continue to work during migration period
3. **Client considerations**: Existing client instances may continue sending `Fx-BuildId` until they are updated

### Timeline considerations

Client applications with long-running instances may continue using the legacy `Fx-BuildId` header until those instances complete their processes and are updated to use the new header format.


# Update environment variables
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/environment-variables

Update environment variables for all existing FlowX.AI services

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

## Audit core

> [!NOTE]
>
> Elasticsearch configuration migrates from `SPRING_ELASTICSEARCH_*` to `FLOWX_ELASTICSEARCH_*` namespace with enhanced index management.

### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_DATASTREAM` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `audit-logs` | `audit-logs` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | `30` | Automatic index rollover policy |

> [!WARNING]
>
> Since FlowX.AI 4.7.6, the Audit service rewrites its Elasticsearch index lifecycle management (ILM) policy, `audit-logs_policy` by default, every time it starts. The policy has a single hot phase that rolls over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, and no delete phase. Any phase you added directly in Elasticsearch, such as a delete phase, is removed on the next startup, so old audit indices are never deleted and audit storage keeps growing.
>
> If you're upgrading from 4.7.5 or earlier, the rollover period also changes from a fixed 1 day to a default of 30 days. To keep daily rollover, set `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS=1`.

## Data Search

> [!NOTE]
>
> Simple migration with containerization support and namespace alignment.

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `SPRING_ELASTICSEARCH_REST_URIS` | `localhost:9200` | `elasticsearch:9200` | Containerization support |

### Variables to replace

| Remove This | Add This | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_INDEXSETTINGS_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` |

## Document plugin

> [!NOTE]
>
> New configuration option for test documents bucket customization.

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILE_STORAGE_TEST_FILES_BUCKET` | `-test-documents` | Overrides the default test documents bucket suffix. Use this to configure a custom bucket name for test files. |

> [!NOTE]
>
> This variable allows you to override the default `-test-documents` bucket suffix. You can configure a custom bucket name or use the same bucket as the main storage if needed.

## Kafka configuration

> [!NOTE]
>
> Complete Kafka migration including consumer group standardization to kebab-case, comprehensive topic restructuring with new versioned naming patterns, and enhanced messaging features across all FlowX.AI services.

> [!WARNING]
>
> **Do not modify default consumer group names.** We strongly recommend against changing the default consumer group names as this operation can lead to misconfigurations. The application is designed to work and scale with the consumer groups as they are defined by default.

### Consumer group migrations

> [accordion] View all 33 consumer group name changes across all FlowX.AI services
>
> **Admin (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `genericProcessingGroup` | `generic-processing-group` |
> | `processSyncGroup` | `process-sync-group` |
> | `adminResourcesUsagesRefreshGroup` | `admin-resources-usages-refresh-group` |
>
> **Application Manager (15 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `appResourceExportGroup` | `app-resource-export-group` |
> | `appResourceImportGroup` | `app-resource-import-group` |
> | `appResourceUsagesGroup` | `app-resource-usages-group` |
> | `appResElemUsageValidationResp` | `app-resource-elem-usage-validation-resp` |
> | `appResourceCopyGroup` | `app-resource-copy-group` |
> | `appResourceSyncGroup` | `app-resource-sync-group` |
> | `appResourceUpdatePropagationGroup` | `app-resource-update-propagation-group` |
> | `appMergeItemGroup` | `app-merge-item-group` |
> | `buildCreateGroup` | `build-create-group` |
> | `buildUpdateGroup` | `build-update-group` |
> | `buildResourceExportGroup` | `build-resource-export-group` |
> | `buildResourceImportGroup` | `build-resource-import-group` |
> | `buildRuntimeDataGroup` | `build-runtime-data-group` |
> | `buildStartTimerEventsUpdatesGroup` | `build-start-timer-events-updates-group` |
> | `processStartGroup` | `process-start-group` |
>
> **CMS Core (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `cms-consumer-preview` | `cms-consumer-group` |
>
> **Document Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `kafka-svc-document-consumer-local-test2` | `kafka-svc-document-consumer` |
>
> **Integration Designer (3 groups):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `integrDesignerResourcesUsagesRefreshGroup` | `integration-designer-resources-usages-refresh-group` |
> | `genericProcessingGroup` | `start-workflows-group` |
> | `resElemUsageValidation` | `integration-designer-res-elem-usage-validation-group` |
>
> **Notification Plugin (1 group):**
>
> | Old Group ID | New Group ID |
> | - | - |
> | `notif123-preview` | `notification-plugin-consumer` |
>
> **Process Engine (11 groups):**
>
> | Old Group ID (all were `notif123-preview`) | New Group ID |
> | - | - |
> | `notif123-preview` | `advance` |
> | `notif123-preview` | `notify-parent` |
> | `notif123-preview` | `adapters` |
> | `notif123-preview` | `scheduler-run-action` |
> | `notif123-preview` | `scheduler-advancing` |
> | `notif123-preview` | `message-events` |
> | `notif123-preview` | `process-start` |
> | `notif123-preview` | `process-start-for-event` |
> | `notif123-preview` | `process-expire` |
> | `notif123-preview` | `process-operations` |
> | `notif123-preview` | `process-batch-processing` |

### Kafka topic migrations

> [!NOTE]
>
> All Kafka topics migrate to versioned naming pattern `ai.flowx.{env}.{service}.{operation}.v1` for improved organization and future compatibility.

> [tab] Application Manager
>
> **Application resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_IN` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
>
> **Sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS_IN` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE_IN` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLETEMPLATE_IN` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_IN` | `ai.flowx.application-version.sync.out.v1` |
>
> **Resource update propagation:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION` | `ai.flowx.application-version.resource.update.propagation.v1` |
>
> **Build resource topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

> [tab] Admin
>
> **Consumer groups:**
>
> | Environment Variable | New Consumer Group | Threads |
> | - | - | - |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_SYNC` | `process-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC` | `business-rule-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC` | `reusable-template-sync-group` | `6` |
> | `KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION` | `processCorrectionAfterAppOperationGroup` | `6` |
>
> **Application sync topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE` | `ai.flowx.application-version.sync.out.v1` |
> | `KAFKA_TOPIC_APPLICATION_PROCESS_SYNC` | `ai.flowx.application-version.sync.process.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC` | `ai.flowx.application-version.sync.business-rule.in.v1` |
> | `KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC` | `ai.flowx.application-version.sync.reusable-template.in.v1` |
>
> **Application correction after app operation topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS` | `ai.flowx.application-version.correction-after-app-operation.process.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE` | `ai.flowx.application-version.correction-after-app-operation.business-rule.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE` | `ai.flowx.application-version.correction-after-app-operation.reusable-template.request.v1` |
> | `KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT` | `ai.flowx.application-version.correction-after-app-operation.response.v1` |
>
> **Build topics:**
>
> | Environment Variable | New Topic Name |
> | - | - |
> | `KAFKA_TOPIC_BUILD_RUNTIMEDATA` | `ai.flowx.build.runtime-data.v1` |

### New Kafka features

> [card] Resource Update Propagation
>
> **Consumer Group:** `app-resource-update-propagation-group`\
> **Threads:** 3\
> **Topic:** `ai.flowx.{env}.application-version.resource.update.propagation.v1`\
> **Purpose:** Real-time resource change propagation

> [card] Build Runtime Data
>
> **Consumer Group:** `build-runtime-data-group`\
> **Threads:** 2\
> **Topic:** `ai.flowx.{env}.build.runtime-data.v1`\
> **Purpose:** Build process data management

> [card] Business Rule Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.business-rule.in.v1`\
> **Purpose:** Enhanced business rule synchronization\
> **Consumer Group:** `business-rule-sync-group`

> [card] Process Sync Enhanced
>
> **Topic:** `ai.flowx.{env}.application-version.sync.process.in.v1`\
> **Purpose:** Improved process synchronization\
> **Consumer Group:** `process-sync-group`

> [card] Reusable Template Sync
>
> **Topic:** `ai.flowx.{env}.application-version.sync.reusable-template.in.v1`\
> **Purpose:** Template synchronization\
> **Consumer Group:** `reusable-template-sync-group`

> [card] Correction After App Operation
>
> **Multiple Topics:** Process, business rule, and template correction\
> **Purpose:** Post-deployment resource correction\
> **Consumer Group:** `processCorrectionAfterAppOperationGroup`

### Configure environment variables

> [!NOTE]
>
> **Automatic Configuration**: Most deployments can rely on the built-in naming patterns without explicit environment variable overrides. Only override when custom naming is required.

```bash Application Manager Topics theme={"dark"}
# Resource Update Propagation
KAFKA_TOPIC_APPLICATION_RESOURCE_UPDATEPROPAGATION=ai.flowx.dev.application-version.resource.update.propagation.v1

# Build Runtime Data  
KAFKA_TOPIC_BUILD_RUNTIMEDATA=ai.flowx.dev.build.runtime-data.v1

# Sync Topics
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_PROCESS=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_BUSINESSRULE=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_SYNC_OUT_REUSABLE_TEMPLATE=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_RESOURCE_CORRECTIONAFTERAPPOPERATION_OUT_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
```

```bash Admin Topics theme={"dark"}
# Application Sync
KAFKA_TOPIC_APPLICATION_SYNC_RESPONSE=ai.flowx.dev.application-version.sync.out.v1
KAFKA_TOPIC_APPLICATION_PROCESS_SYNC=ai.flowx.dev.application-version.sync.process.in.v1
KAFKA_TOPIC_APPLICATION_BUSINESSRULE_SYNC=ai.flowx.dev.application-version.sync.business-rule.in.v1
KAFKA_TOPIC_APPLICATION_REUSABLETEMPLATE_SYNC=ai.flowx.dev.application-version.sync.reusable-template.in.v1

# Correction After App Operation
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_PROCESS=ai.flowx.dev.application-version.correction-after-app-operation.process.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_BUSINESSRULE=ai.flowx.dev.application-version.correction-after-app-operation.business-rule.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_IN_REUSABLETEMPLATE=ai.flowx.dev.application-version.correction-after-app-operation.reusable-template.request.v1
KAFKA_TOPIC_APPLICATION_CORRECTIONAFTERAPPOPERATION_OUT=ai.flowx.dev.application-version.correction-after-app-operation.response.v1
```

```bash Consumer Groups and Threads theme={"dark"}
# Application Manager Consumer Groups
KAFKA_CONSUMER_GROUPID_APPLICATION_RESOURCE_UPDATEPROPAGATION=app-resource-update-propagation-group
KAFKA_CONSUMER_GROUPID_BUILD_RUNTIMEDATA=build-runtime-data-group

# Admin Consumer Groups  
KAFKA_CONSUMER_GROUPID_PROCESS_SYNC=process-sync-group
KAFKA_CONSUMER_GROUPID_BUSINESS_RULE_SYNC=business-rule-sync-group
KAFKA_CONSUMER_GROUPID_REUSABLE_TEMPLATE_SYNC=reusable-template-sync-group
KAFKA_CONSUMER_GROUPID_PROCESS_CORRECTIONAFTERAPPOPERATION=processCorrectionAfterAppOperationGroup

# Thread Configuration
KAFKA_CONSUMER_THREADS_APPLICATION_RESOURCE_UPDATEPROPAGATION=3
KAFKA_CONSUMER_THREADS_BUILD_RUNTIMEDATA=2
KAFKA_CONSUMER_THREADS_PROCESS_SYNC=6
KAFKA_CONSUMER_THREADS_BUSINESS_RULE_SYNC=6
KAFKA_CONSUMER_THREADS_REUSABLE_TEMPLATE_SYNC=6
KAFKA_CONSUMER_THREADS_PROCESS_CORRECTIONAFTERAPPOPERATION=6
```

### Additional Application Manager variables

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_RESOURCESUSAGES_REFRESHPRODUCER_REFRESHEXPIRATIONSECONDS` | `300` | Refresh expiration timeout |
| `SERVER_MAXHTTPREQUESTHEADERSIZE` | `16KB` | Maximum HTTP request header size |

## Integration Designer

### Storage configuration

Added support for S3 storage for files in Integration Designer.

| Variable | Default Value | Description |
| - | - | - |
| `APPLICATION_FILESTORAGE_TYPE` | `s3` | Storage type |
| `APPLICATION_FILESTORAGE_PARTITIONSTRATEGY` | `NONE` | Partition strategy |
| `APPLICATION_FILESTORAGE_DELETIONSTRATEGY` | `delete` | Deletion strategy |
| `APPLICATION_FILESTORAGE_S3_ENABLED` | `true` | S3 enabled |
| `APPLICATION_FILESTORAGE_S3_SERVERURL` | `http://minio:9000` | S3 server URL |
| `APPLICATION_FILESTORAGE_S3_ENCRYPTIONENABLED` | `false` | S3 encryption enabled |
| `APPLICATION_FILESTORAGE_S3_ACCESSKEY` | `minio` | S3 access key |
| `APPLICATION_FILESTORAGE_S3_SECRETKEY` | `minio123` | S3 secret key |
| `APPLICATION_FILESTORAGE_S3_BUCKETPREFIX` | `workflows-bucket` | S3 bucket prefix |

### Redis

Added caching when running a workflow.

| Variable | Default Value | Description |
| - | - | - |
| `SPRING_CACHE_TYPE` | `redis` | Cache type |
| `SPRING_CACHE_REDIS_KEYPREFIX` | `flowx:core:cache:integration-designer:` | Cache key prefix |
| `SPRING_CACHE_REDIS_TIMETOLIVE` | `5000000` | Cache time to live |
| `SPRING_REDIS_HOST` | `redis-master` | Redis host |
| `SPRING_REDIS_PORT` | `6379` | Redis port |
| `SPRING_REDIS_PASSWORD` | `defaultpassword` | Redis password |
| `SPRING_REDIS_TTL` | `5000000` | Redis time to live |
| `SPRING_DATA_REDIS_HOST` | `spring.redis.host` | Redis host |

## FlowX Engine

> [!NOTE]
>
> The ADVANCING controller has been redesigned with separate picking and processing operations for improved performance and resource management.

### Variables to remove & replace

| Remove This Variable | Replace With |
| - | - |
| `ADVANCING_THREADS` | `ADVANCING_PICKINGTHREADS` (default: `1`) |
| `ADVANCING_PICKINGBATCHSIZE` | `ADVANCING_PROCESSINGBUFFERSIZE` (default: `20`) |

### New variables to add

| Variable | Default Value | Description |
| - | - | - |
| `ADVANCING_PROCESSINGTHREADS` | `20` | Number of threads for parallel processing of advancing events |
| `ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE` | `true` | Block picking operations when no worker threads are available |
| `ADVANCING_DATASOURCE_MAXIMUMPOOLSIZE` | `20` | Maximum database connection pool size for advancing operations |

### Variables to update

| Variable | Current Value | New Value | Reason |
| - | - | - | - |
| `ADVANCING_PICKINGPAUSEMILLIS` | `100` | `50` | Optimized pause duration for better performance |

> [!NOTE]
>
> **How the new advancing controller works:**
>
> * **Picking threads** (`ADVANCING_PICKINGTHREADS`): Controls how many worker threads read events from the database. This handles only the picking/reading operations.
>
> * **Processing buffer** (`ADVANCING_PROCESSINGBUFFERSIZE`): Acts as a queue between picking and processing. When the buffer is full, no new events are read. When there's available space, that amount of events will be read.
>
> * **Processing threads** (`ADVANCING_PROCESSINGTHREADS`): Controls how many threads process the advancing events in parallel. Events are processed instantly if processing threads are available. If all processing threads are busy, events accumulate in the buffer until it reaches capacity.
>
> * **Blocking behavior** (`ADVANCING_BLOCKPICKINGIFNOWORKERAVAILABLE`): When enabled, prevents picking operations if no worker threads are available, ensuring better resource management.

### Elasticsearch indexing configuration

> [!NOTE]
>
> Elasticsearch indexing environment variables have been updated with new naming conventions for better consistency with FlowX naming standards.

#### Variables to remove & replace

| Remove This Variable | Replace With | Old Default | New Default |
| - | - | - | - |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEXING_TYPE` | `FLOWX_INDEXING_TYPE` | `kafka` | `kafka` |
| `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | `process_instance` | `process_instance` |
| `FLOWX_INDEXING_PROCESSINSTANCE_SHARDS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | `2` | `2` |
| `FLOWX_INDEXING_PROCESSINSTANCE_REPLICAS` | `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | `2` | `0` |

> [!NOTE]
>
> For complete Elasticsearch indexing setup including Kafka Connect configuration and time-based partitioning, see the [Configuring Elasticsearch indexing](/5.1/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing) guide.

## Java runtime configuration

> [!NOTE]
>
> FlowX.AI containers and services must rely exclusively on Java-standard environment variables for runtime tuning.

| Deprecated variables | Standard Replacement | Notes |
| - | - | - |
| `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` | `JDK_JAVA_OPTIONS` | Ensures compatibility with Java 21 and simplifies container config |

> [!NOTE]
>
> Environment-specific memory configurations must now be defined using `JDK_JAVA_OPTIONS`. Avoid relying on `JAVA_OPTS`, `JAVA_TOOL_OPTIONS` or legacy Docker-level overrides — these are no longer processed explicitly.

## Config profiles

> [!NOTE]
>
> Config profiles are deprecated since 4.7.6 version.

Remove legacy `CONFIG_PROFILE` usage. Delete any `CONFIG_PROFILE` environment variable definitions from deployments. This variable is no longer referenced by FlowX.AI services.

### Development environment exception

> [!NOTE]
>
> For development environments only, `CONFIG_PROFILE` migrates to the standard Spring configuration profile variable.

| Remove This Variable | Replace With | Environment |
| - | - | - |
| `CONFIG_PROFILE` | `SPRING_CONFIG_PROFILE` | devenv only |

## SpiceDB integration

> [!NOTE]
>
> FlowX.AI 5.1 introduces SpiceDB integration for enhanced authorization capabilities across all core services.

### Services affected

The following services require new SpiceDB configuration variables:

* Admin
* Application Manager
* Audit Core
* CMS Core
* Document Plugin
* Integration Designer
* Notification Plugin
* Process Engine
* Runtime Manager
* Task Management Plugin

### New variables to add

For every CAS configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_SPICEDB_TOKEN` | *(secret)* | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Data sync updates

### Data Sync additional variables

For every Data-Sync configuration, add the following variables:

| Variable | Default Value | Description |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | `spicedb` | SpiceDB server hostname. Change only if your deployment uses a non-default host. |
| `FLOWX_SPICEDB_PORT` | `50051` | SpiceDB server port. Change only if your deployment uses a non-default port. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_URL` | - | Authentication system URL. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_USERNAME` | - | Authentication system username. |
| `FLOWX_DATASOURCE_AUTHSYSTEM_PASSWORD` | - | Authentication system password. |
| `FLOWX_SPICEDB_TOKEN` | - | SpiceDB authentication token. Add as a Secret to all services connecting to CAS, including Data-Sync. |

## Kafka topic naming

### Global configuration change

| Variable | Old Default | New Default | Description |
| - | - | - | - |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | (varies) | `""` | Moved to default empty environment |

> [!NOTE]
>
> This change standardizes topic naming across environments by defaulting to an empty environment identifier.

## CORS and ingress updates

> [!WARNING]
>
> All services with Kubernetes ingress configurations now require the `Fx-Workspace-Id` header for workspace identification in multi-tenant environments.

### Standard ingress pattern

FlowX.AI v5.1 introduces a standardized ingress configuration pattern for all services. The key change is adding the `Fx-Workspace-Id` header to the CORS configuration.

**Required annotation update:**

```yaml theme={"dark"}
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,flowx-platform,Fx-Workspace-Id"
```

### Services requiring updates

All FlowX.AI services that expose ingress endpoints require this update:

| Service | Fx-Workspace-Id Required | Reference |
| - | - | - |
| Admin | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Application Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Audit Core | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Authorization System | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Events Gateway | ❌ No (SSE) | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) |
| Integration Designer | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Process Engine | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Runtime Manager | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |
| Task Management | ✅ Yes | [Ingress guide](../../../../../5.1/setup-guides/ingress-configuration) |

> [card] [Complete Ingress Configuration Guide](../../../../../5.1/setup-guides/ingress-configuration)
>
> View the complete ingress configuration pattern including:
>
> * Standard template for all services
> * Service-specific paths and rewrite rules
> * Annotation explanations
> * Troubleshooting guide
> * Environment-specific customization

> [!NOTE]
>
> **Exception:** Events Gateway does not require the `Fx-Workspace-Id` header because it handles Server-Sent Events (SSE) with different security requirements. See the [Events Gateway exception](../../../../../5.1/setup-guides/ingress-configuration#events-gateway-exception) section for details.


# Install new services
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/install-services

Step-by-step installation guide for new FlowX.AI 5.1.0 services

FlowX.AI 5.1.0 introduces two new services:

1. **Authorization System (CAS)** - Centralized authorization and permission management
2. **NoSQL DB Runner** - The NoSQL DB Runner is a backend microservice that powers FlowX.AI Database functionality. It provides MongoDB and Azure Cosmos DB operations support for FlowX.AI Database collections and handles data persistence operations across FlowX.AI processes.

> [card] [authorization-system](../../../../../5.1/setup-guides/authorization-setup-guide)

> [card] [nosql-db-runner](../../../../../5.1/setup-guides/nosql-db-runner)


# Overview
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/migration-overview

Complete migration guide from FlowX.AI 4.7.x to 5.1.0 with prerequisites and step-by-step process

> [!WARNING]
>
> You can only upgrade from version 4.7.8 (or newer) to 5.1.0. If you’re on an earlier version, upgrade to the latest LTS version first.

> [!WARNING]
>
> **Continuing to 5.9.x?** If 5.1.x is only an intermediate stop on your path to 5.9.x, land on the **latest available 5.1.x patch**, not 5.1.0. Data migrations and their fixes accumulate across the patches of the family, and the latest patch is the level guaranteed to carry all of them. Before starting the next migration, confirm the environment is fully functional: every service up and healthy in **FlowX.AI Designer → Platform Status**, and the data-sync job completed successfully. See the [5.1 → 5.9 migration prerequisites](/5.9/migrating-from-5.1-lts/prerequisites).

## Success factors

> [!WARNING]
>
> Take care when following the steps below are mandatory and will prevent service startup if skipped:
>
> 1. **SpiceDB and DGraph** must be installed before any FlowX.AI services
>
> > [!NOTE]
> >
> > DGraph is required only if you are using FlowX AI agents. If not, you can skip this step.
>
> 2. **Organization admin user** must be configured before authorization-system service deployment
> 3. **Service accounts** must have `SA_FLOWX` role assigned
> 4. **Elasticsearch indices (data migration)** must complete before service upgrades

## Migration process

Follow these steps in the exact order specified to ensure a successful migration:

**1. Prerequisites**

### Data migration (Elasticsearch indices)

Migrate existing Elasticsearch data to support the new workspace-based architecture.

### Installing new third parties

**New mandatory infrastructure components:**

* **SpiceDB** - Authorization and permission management backend
* **DGraph** - Graph-based data operations and relationships

### Upgrading existing third parties

Update existing infrastructure to the new supported versions:

* Kafka 3.8+, Redis 7.4+, Elasticsearch 8+, Keycloak 26+

### Organization admin user

Configure the organization admin user before deploying the authorization-system service.

### Service accounts

Assign `SA_FLOWX` role to all service accounts used by FlowX services.

> [card] [Prerequisites](./prerequisites)
>
> See the details on prerequisites for migration

**2. Installing new services**

Deploy new FlowX.AI 5.1.0 services in the correct order to ensure proper startup and dependency validation.

**Required installation sequence:**

1. **Authorization System (CAS)** - Must be installed first to validate SpiceDB connection
2. **NoSQL DB Runner** - Backend service for [FlowX.AI Database](../../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)

> [!WARNING]
>
> **Service Startup Dependency**: Authorization System will not start without proper SpiceDB installation and organization admin configuration.

> [card] [Install services](./install-services)
>
> Step-by-step installation with validation procedures

> [!NOTE]
>
> Installing Authorization System first allows you to validate all critical configurations before proceeding.

**3. Update environment variables**

Update environment variable configurations for all existing FlowX.AI services to support version 5.1.0 compatibility.

**Configuration updates include:**

* New Kafka topics and consumer groups
* Updated Elasticsearch settings and index configurations
* Enhanced security and authorization parameters
* New service integration endpoints

> [card] [Update environment variables](./environment-variables)
>
> Update environment variables for all existing FlowX.AI services

**4. Install new versions for existing services**

Upgrade all existing FlowX.AI services to version 5.1.0 after completing environment variable updates.

**5. Container apps (Renderers SDKs)**

> [card] [Container apps (Renderers SDKs)](./renderers)
>
> See the details on container apps (Renderers SDKs)

**6. Post-deployment steps**

Perform the post deployment steps:

* Validate data-sync migrations
* Clear cache with endpoint
* Remove deprecated configuration roles (optional)
* Add users to default workspace

### Validate data-sync migrations

Verify that all data synchronization processes completed successfully and perform additional system checks.

### Clear cache with endpoint

**Required**: Clear Redis cache using the dedicated endpoint with organization admin token.

> [!WARNING]
>
> **Cache Clearing**:
>
> * FlowX.AI 5.1.0 removes process definition versioning. Cache must be cleared to remove legacy cached classes.
> * When you start the runtime-manager on version 5.x, the library-to-library migration runs automatically. You must clear the cache after this step because a new field is added to the build mongo document, which is required for various operations.

### Remove deprecated configuration roles (optional)

Clean up legacy roles from Keycloak or other authentication servers that are now managed by CAS.

### Add users to default workspace

**Process**:

1. **User Re-login**: Existing configurators must log into FlowX.AI Designer once to create user references in FlowX.AI database
2. **Workspace Assignment**: Organization admin assigns users to the default workspace to reestablish access to existing assets and resources

> [!WARNING]
>
> **Access Restoration**: Without workspace assignment, existing users will lose access to previously available resources and projects.

> [card] [Post-deployment configuration](./configuration-and-migration)
>
> Complete post-deployment procedures and validation

> [card] [Troubleshooting](./troubleshooting)
>
> Common issues and solutions for post-upgrade problems


# Prerequisites
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/prerequisites

This section contains the steps in order that we recommend for migrating data from FlowX v4.7.x to v5.1.0.

## Upgrading existing third parties

Update existing infrastructure to at least the new supported versions:

| Component | 4.7.8 | FlowX.AI 5.1.0 |
| - | - | - |
| **Kafka** | 3.2 - 3.9 | **3.8 - 3.9** |
| **Redis** | 7.2 - 8.0 | **7.4 - 8.0** |
| **Elasticsearch** | 7 - 9 | **8 - 9** |
| **Keycloak** | 22,26+ | **26+** |

> [card] [Third parties components versions](../deployment-guidelines-v5.1#third-party-supported-component-versions)

***

## Installing new third parties

FlowX.AI 5.1.0 requires two new infrastructure components that must be installed and properly configured before any FlowX.AI services can start.

* **SpiceDB** - Required for authorization management (Must be accessible by the authorization-system service)
* **DGraph** - Required for data relationships and graph operations. If you are not using FlowX AI agents (you don't have an AI deployment), you can skip this step.

> [card] [SpiceDB setup guide](../../../../../5.1/setup-guides/spicedb)

***

## Elasticsearch workspace migration

**The primary goal of this Elasticsearch migration is to add the default workspace ID to all existing resources in your environment.** This ensures that all your current data (process instances, audit logs, etc.) will be properly associated with a workspace and remain accessible after the upgrade to FlowX 5.1.0.

Without this migration, existing data would not have workspace associations and could become inaccessible or invisible in workspace-scoped operations.

> [!WARNING]
>
> Elasticsearch index mappings must be updated before upgrading to FlowX.AI 5.1.0 to ensure workspace functionality works correctly.

### Migration timing

> [!TIP]
>
> **Recommended approach**: Complete these Elasticsearch migrations **before** upgrading FlowX.AI microservices. Upgrading services first and then creating new workspaces will complicate the migration process.

### Prerequisites for migration

Before upgrading to FlowX.AI 5.1.0, you must update the mappings for all existing Elasticsearch indices to include the `workspaceId` field:

```json theme={"dark"}
PUT /{indexName/indexPattern}/_mapping
{
  "properties": {
    "workspaceId": {
      "type": "keyword"
    }
  }
}
```

This mapping update is required for:

* Process instances indices (you can find the indices in the `flowx-process-engine` setup guide at `FLOWX_INDEXING_PROCESSINSTANCE_INDEX_NAME` environment variable, if not set, the default is `process_instance`)
* Audit log indices (you can find the indices in the `audit-core` setup guide at `SPRING_ELASTICSEARCH_INDEX_SETTINGS_DATASTREAM` environment variable)

### Migration execution methods

You can execute these migration queries using:

* **Kibana Dev Tools**: Execute queries directly in the Kibana interface
* **Elasticsearch API**: Use direct API calls to perform migrations

### Process instances migration

Process instances indices require manual migration using Elasticsearch's `update_by_query` API to assign them to the default workspace:

#### Synchronous migration

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

#### Asynchronous migration (for large datasets)

For large datasets, use asynchronous migration:

```json theme={"dark"}
POST /{indexName}/_update_by_query?slices=auto&wait_for_completion=false
```

Monitor async tasks with:

```json theme={"dark"}
GET /_tasks/{task_id}
```

### Audit logs migration

Audit logs follow the same migration process as process instances, using identical scripts and procedures to assign them to the default workspace:

```json theme={"dark"}
POST /{audit_index_pattern}/_update_by_query?slices=auto
{
  "script": {
    "source": "ctx._source.workspaceId = params.workspace_id;",
    "lang": "painless",
    "params": {
      "workspace_id": "00000000-0000-0000-0000-000000000001"
    }
  },
  "query": {
    "bool": {
      "must_not": {
        "exists": {
          "field": "workspaceId"
        }
      }
    }
  }
}
```

### Performance optimization

* Use `slices=auto` for automatic parallelization based on primary shards
* For multiple indices, use patterns: `POST /my_pattern-*/_update_by_query?slices=auto`
* Batch processing with size parameter: `?size=1000`
* Monitor large operations using asynchronous execution

### Post-migration impact

**Without proper Elasticsearch migration, you will experience:**

* Some process instances may not appear in search results
* Data-search functionality may not return complete results
* Workspace-scoped queries will fail for unmigrated data
* **Existing resources will not be visible or accessible within the new workspace structure**

### Default workspace ID

The migration uses the default workspace ID: `00000000-0000-0000-0000-000000000001`

All existing resources (process instances, audit logs, etc.) will be moved to this default workspace, ensuring continuity of operations after the upgrade to FlowX.AI 5.1.0.

***

## Organization admin user

Configure the organization admin user before deploying the authorization-system service (that is mentioned in the [Install Services](./install-services) section).

Details on how to configure the organization admin user:

> [card] [Authorization system](../../../../../5.1/setup-guides/authorization-setup-guide#organization-admin-bootstrap)

> [card] [Workspaces access rights](../../../../../5.1/setup-guides/access-management/workspaces-access-rights#organization-admin)

***

#### Pre-migration preparation

You must configure the authorization-system service before migration. There are two supported approaches:

> [tab] Recommended: Use admin email (simpler)
>
> Set the following authorization-system environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERNAME=<username-of-admin-user>`: The value for the environment variable must be set with the username of the user that must be the first organization administrator.

> [tab] Alternative: Use admin subject ID
>
> Set the following environment variables:
>
> * `SPRING_LIQUIBASE_PARAMETERS_CREATEDEFAULTWORKSPACE=true`: This environment variable is mandatory for migrations.
>
> * `SPRING_LIQUIBASE_PARAMETERS_DEFAULTORGADMINUSERSUBJECTID=<subject-id-of-admin-user>`: The value for the environment variable can be set with the unique identifier of the user that must be the first organization administrator. The value that is added by auth server on the access token (”sub” attribute - subject identifier in JWT token).
>
> > [!TIP]
> >
> > To get the subject ID of the admin user, extract it from the JWT token of the admin user.
>
> ![JWT token](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sub_id.png)

> [!NOTE]
>
> Make sure the admin user is created in Keycloak before deploying the authorization-system service.

***

## Update service accounts

FlowX.AI 5.1.0 introduces new service account role requirements that must be configured before service deployment.

> [!WARNING]
>
> All service accounts used by FlowX.AI services must have the `SA_FLOWX` role assigned. Services will not authenticate properly without this role.

***

## Additional Keycloak roles requirements for authorization-system service

Before deploying the `authorization-system` service, you must assign additional roles to its service account in Keycloak to enable user management operations.

**Required client roles for the service account:**

```json theme={"dark"}
{
  "clientRoles" : {
    "realm-management" : [
      "manage-users",
      "query-users",
      "view-users",
      "manage-realm"
    ]
  }
}
```

***

## Process instances migration

All active process instances will be migrated under default workspace.

> [!WARNING]
>
> For clients who need inactive process instances migrated, we’ll provide migration script which will be run post migration.


# Renderer SDKs
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/renderers

This guide assists in migrating from FlowX.AI v4.7.x to v5.1.0.

## Angular SDK migration guide

### Upgrading to the new SDK libraries

The Angular SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries (if upgrading from earlier versions):

```bash theme={"dark"}
npm uninstall @flowx/angular-sdk @flowx/core-sdk @flowx/core-theme @flowx/angular-theme @flowx/angular-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/angular-sdk@<version> \
  @flowx/angular-theme@<version> \
  @flowx/angular-ui-toolkit@<version> \
  @angular/cdk@19 \
  @types/event-source-polyfill
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Verify Angular dependencies**

* Ensure your Angular version is compatible:

```bash theme={"dark"}
npm install -g @angular/cli@19
```

* Verify system requirements:
  * Node.js: v20.9.0 or higher
  * npm: v10.1.0 or higher
  * Angular: \~19

**3. Update flx-process-renderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### SDK API changes

In the Angular SDK, the `<flx-process-renderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace identifier** that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
export class AppComponent {
  workspaceId = 'your-workspace-id';
  // ... other existing properties
}
```

Use this parameter as input for the `<flx-process-renderer>` component:

```html theme={"dark"}
<flx-process-renderer
  [workspaceId]="workspaceId"
  [projectInfo]="projectInfo"
  <!-- ... other existing inputs -->
>
</flx-process-renderer>
```

### Task management component changes

The task management component now also requires workspace context:

```html theme={"dark"}
<flx-task-management
  [apiUrl]="apiUrl"
  [authToken]="accessToken"
  [appId]="appId"
  [viewDefinitionId]="viewDefinitionId"
  [workspaceId]="workspaceId"
  <!-- ... other inputs -->
>
</flx-task-management>
```

***

## React SDK migration guide

### Upgrading to the new SDK libraries

The React SDK node packages have been updated to support Workspaces, introduced in FlowX.AI v5.1.0. All container apps that want to use the new SDKs should update to the latest package versions and implement the required workspace configuration.

**1. Remove old packages and install new FlowX.AI v5.1.0 packages**

* Remove old FlowX.AI SDK libraries:

```bash theme={"dark"}
npm uninstall @flowx/react-sdk @flowx/core-sdk @flowx/core-theme @flowx/react-theme @flowx/react-ui-toolkit
```

* Install new FlowX.AI v5.1.0 packages:

```bash theme={"dark"}
npm install \
  react@18 \
  react-dom@18 \
  @flowx/core-sdk@<version> \
  @flowx/core-theme@<version> \
  @flowx/react-sdk@<version> \
  @flowx/react-theme@<version> \
  @flowx/react-ui-toolkit@<version> \
  air-datepicker@3 \
  axios \
  ag-grid-react@32
```

> [!WARNING]
>
> Replace `<version>` with the correct version corresponding to your FlowX.AI v5.1.0 platform version. Check: **Release Notes → v5.1.0 → Deployment guidelines → Component versions**.

**2. Update React dependencies (if needed)**

* Ensure your React version is compatible:

```bash theme={"dark"}
npm install react@~18 react-dom@~18
```

* Verify Node.js version compatibility:
  * Node.js: v18.16.9 or higher
  * npm: v10.8.0 or higher

**3. Update FlxProcessRenderer configuration**

* Run through all the migration steps in the [New SDK API changes](#new-sdk-api-changes) section below.

### New SDK API changes

In the React SDK, the `<FlxProcessRenderer>` component has a new mandatory parameter: `workspaceId`.

| Name | Description | Type | Requirement |
| - | - | - | - |
| `workspaceId` | **Workspace** identifier that contains the project and process to be started | `string` | Mandatory |

Add the definition for this property in your component:

```typescript theme={"dark"}
const workspaceId = 'your-workspace-id';
```

Use this parameter as input for the `<FlxProcessRenderer>` component:

```tsx theme={"dark"}
<FlxProcessRenderer
    workspaceId={workspaceId}
    projectInfo={{ projectId: 'your-project-id' }}
    // ... other existing props
/>
```

### Task management component changes

The task management component now also requires workspace context:

```tsx theme={"dark"}
<FlxTaskManager
    apiUrl={baseUrl}
    authToken={authToken}
    appInfo={appInfo}
    viewId={viewId}
    workspaceId={workspaceId}
    // ... other existing props
/>
```

## Android SDK migration guide

### System requirements

System requirements:

* **minSdk = 26**
* **compileSdk = 35**

The SDK library was build using:

* **[Android Gradle Plugin](https://developer.android.com/build/releases/gradle-plugin) 8.11.0**
* **[Gradle](https://gradle.org/releases/) 8.14.2**
* **[Kotlin](https://kotlinlang.org/) 2.2.0**

### Library dependencies

Impactful dependencies:

* **[Android Core KTX](https://developer.android.com/kotlin/ktx#core) 1.16.0**
* **[Android Activity Compose](https://developer.android.com/jetpack/androidx/releases/activity) 1.10.1**
* **[Compose BOM](https://developer.android.com/jetpack/compose/bom/bom-mapping) 2025.09.01**
* **[Compose Navigation](https://developer.android.com/develop/ui/compose/navigation) 2.9.1**
* **[Android Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle) 2.9.1**
* **[Accompanist Permissions](https://google.github.io/accompanist/permissions/) 0.37.3**
* **[Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) 1.10.2**
* **[Android DataStore](https://developer.android.com/jetpack/androidx/releases/datastore) 1.1.7**
* **[Android Preference](https://developer.android.com/jetpack/androidx/releases/preference) 1.2.1**
* **[Android Security](https://developer.android.com/jetpack/androidx/releases/security) 1.1.0-beta01**
* **[OkHttp BOM](https://square.github.io/okhttp/) 4.12.0**
* **[Retrofit](https://square.github.io/retrofit/) 2.12.0**
* **[Moshi](https://github.com/square/moshi) 1.15.2**
* **[Coil BOM](https://coil-kt.github.io/coil/) 3.2.0**
* **[Android Core Library Desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) 2.1.5**

Other dependencies:

* **[Android Annotation](https://developer.android.com/jetpack/androidx/releases/annotation) 1.9.1**
* **[Google Protobuf](https://github.com/protocolbuffers/protobuf/tree/main/java#use-java-protocol-buffers-on-android) 4.31.1**
* **[Mozilla Rhino](https://github.com/mozilla/rhino) 1.8.0**
* **[JetBrains Markdown](https://github.com/JetBrains/markdown) 0.7.3**
* **[CommonMark](https://github.com/commonmark/commonmark-java) 0.25.0**

> [!NOTE]
>
> * **[Koin](https://insert-koin.io/)** dependency has been removed
> * **[Gson](https://github.com/google/gson)** dependency has been removed

> [!TIP]
>
> Some dependencies were removed, others got updated.\\
>
> It is highly recommended that the container projects to be aligned with these versions to avoid any compatibility issues.

### New SDK Migration Guide

To successfully build and run your project with the updated SDK, please follow these sequential steps within your container project:

**1. Update dependency coordinates**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
implementation("ai.flowx.android:android-sdk:4.0.25") // [!code --]
implementation("ai.flowx.android:sdk:9.0.2") // [!code ++]
```

**2. Increase the `compileSdk` version to `35`**

```kotlin [rootProject]/app/build.gradle.kts lines theme={"dark"}
android {
    compileSdk = 34 // [!code --]
    compileSdk = 35 // [!code ++]
}
```

**3. Recommendation: Upgrade JVM compatibility to Java 17**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    sourceCompatibility = JavaVersion.VERSION_17 // [!code ++]
    targetCompatibility = JavaVersion.VERSION_1_8 // [!code --]
    targetCompatibility = JavaVersion.VERSION_17 // [!code ++]
}

kotlinOptions { // [!code --]
    jvmTarget = "1.8" // [!code --]
} // [!code --]
kotlin { // [!code ++]
    compilerOptions { // [!code ++]
        jvmTarget.set(JvmTarget.JVM_17) // [!code ++]
    } // [!code ++]
} // [!code ++]
```

**4. Update the `Android Gradle plugin` version to at least `8.10.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("com.android.application") version "M.m.p" apply false // where M.m.p < 8.10.0 // [!code --]
    id("com.android.application") version "8.10.0" apply false // [!code ++]
}
```

**5. Update `Gradle` version to at least `8.11.1`**

```properties [root-project]/gradle/wrapper/gradle-wrapper.properties icon="ini" theme={"dark"}
distributionUrl=https\://services.gradle.org/distributions/gradle-M.m.p-bin.zip # where M.m.p < 8.11.1 [!code --]
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip # [!code ++]
```

**6. Update `Kotlin` version to at least `2.2.0`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.android") version "1.m.p" apply false // [!code --]
    id("org.jetbrains.kotlin.android") version "2.2.0" apply false // [!code ++]
}
```

**7. Apply the `Compose Compiler Gradle plugin`**

```kotlin [rootProject]/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.0" apply false // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
plugins {
    id("org.jetbrains.kotlin.plugin.compose") // [!code ++]
}
```

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    composeOptions { // [!code --]
        kotlinCompilerExtensionVersion = "1.m.p" // [!code --]
    } // [!code --]
}
```

> [!TIP]
>
> It is recommended to use the same version as the one configured for the **Kotlin** plugin

> [!TIP]
>
> Consult the [Compose Compiler Migration Guide](https://kotlinlang.org/docs/compose-compiler-migration-guide.html)

**8. Enable core library desugaring**

```kotlin [rootProject]/app/build.gradle.kts theme={"dark"}
android {
    compileOptions { // [!code ++]
        isCoreLibraryDesugaringEnabled = true // [!code ++]
    } // [!code ++]
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") // [!code ++]
}
```

**9. Ensure your `android.app.Application` extending class implements the `FlowxOwner` interface**

```kotlin [rootProject]/app/src/main/[java|kotlin]/com/example/MyApp.kt theme={"dark"}
import ai.flowx.android.sdk.main.FlowxOwner

class MyApp : Application(), FlowxOwner { // [!code ++]
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() } // [!code ++]
}
```

**10. Rename `FlowxSdkApi` class to `Flowx` and update imports accordingly**

As a result of this change, all calls to `FlowxSdkApi.getInstance()` must be replaced with `Flowx.getInstance()`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.Flowx // [!code ++]

FlowxSdkApi.getInstance() // [!code --]
Flowx.getInstance() // [!code ++]
```

**11. Update the `Flowx.getInstance().init()` method parameters**

> [accordion] Detailed step-by-step changes
>
> **1. Rename the `SdkConfig` class to `Config` and update imports accordingly**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
> import ai.flowx.android.sdk.api.Config // [!code ++]
>
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = SdkConfig(...), // [!code --]
>     config = object : Config { ... }, // [!code ++]
> )
> ```
>
> > [!WARNING]
> >
> > The `config` parameter is no longer a `data class`. It is now an `interface`.
> >
> > ```kotlin theme={"dark"}
> > data class SdkConfig(...) // [!code --]
> > interface Config { ... } // [!code ++]
> > ```
>
> > [!TIP]
> >
> > When passing custom validators as a configuration parameter, the linter might show errors related to inferring the type of the `validators` property. To fix, use `Map<String, (String) -> Boolean>?` as a type.
>
> **2. The `enableLog` flag from the configuration parameters has been replaced by the `logEnabled` flag**
>
> ```kotlin focus={5,9} theme={"dark"}
> FlowxSdkApi.getInstance().init( // [!code --]
> Flowx.getInstance().init( // [!code ++]
>     context = applicationContext,
>     config = SdkConfig( // [!code --]
>         enableLog = true, // [!code --]
>     ), // [!code --]
>     config = object : Config {
>         //...
>         override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // [!code ++]
>     }, // [!code ++]
> )
> ```
>
> **3. Remove the `accessTokenProvider` parameter from the initialization parameters (if previously used)**
>
> ```kotlin focus={1,4,5} theme={"dark"}
> Flowx.getInstance().init(
>     context = applicationContext,
>     config = object : Config { ... },
>     accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
> )
> ```
>
> > [!TIP]
> >
> > Authentication will now be managed by calling the `Flowx.getInstance().setAccessToken(accessToken: String?)` method with the appropriate argument\
> > \
> > Refer to the following steps for detailed information about the authentication process migration
>
> **4. Update main imports for `Custom` provided UI components (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]
>
> import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
> import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
> ```
>
> **5. Update `Analytics` related imports**
>
> ```kotlin theme={"dark"}
> // if used explicitly
> import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
> import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]
>
> import ai.flowx.android.sdk.analytics.Event // [!code --]
> import ai.flowx.android.sdk.api.analytics.Event // [!code ++]
> ```
>
> **6. Update `NewProcessStartedHandler` related imports (if used explicitly)**
>
> ```kotlin theme={"dark"}
> import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
> import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]
> ```

**Summary of changes:**

```kotlin diff v4.0.25..v9.0.2 focus={2,5,9,13,17,20,24,27,41-52,63} theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi // [!code --]
import ai.flowx.android.sdk.main.FlowxSdk // [!code ++]

import ai.flowx.android.sdk.process.model.SdkConfig // [!code --]
import ai.flowx.android.sdk.api.Config // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.analytics.AnalyticsCollector // [!code --]
import ai.flowx.android.sdk.api.analytics.AnalyticsCollector // [!code ++]

import ai.flowx.android.sdk.analytics.Event // [!code --]
import ai.flowx.android.sdk.api.analytics.Event // [!code ++]

// if used explicitly
import ai.flowx.android.sdk.NewProcessStartedHandler // [!code --]
import ai.flowx.android.sdk.api.NewProcessStartedHandler // [!code ++]

FlowxSdkApi.getInstance().init( // [!code --]
Flowx.getInstance().init( // [!code ++]
    context = applicationContext,
    config = SdkConfig( // [!code --]
        baseUrl = "flowx base url", // [!code --]
        enginePath = "flowx engine path", // [!code --]
        imageBaseUrl = "flowx image base url", // [!code --]
        language = "en", // [!code --]
        locale = Locale.getDefault(), // [!code --]
        validators = mapOf("cnp" to { it.length == 13 }), // a simplified example for custom validator, named "cnp", which checks only the length of the given data // [!code --]
        customHeaders = mapOf("Custom-Header" to "custom header value"), // [!code --]
        updateStateEnabled = true, // [!code --]
        cacheDocuments = true, // [!code --]
        enableLog = true, // [!code --]
    ), // [!code --]
    config = object : Config { // [!code ++]
        override val baseUrl: String = "flowx base url" // [!code ++]
        override val enginePath: String = "flowx engine path" // [!code ++]
        override val imageBaseUrl: String = "flowx image base url" // [!code ++]
        override val language: String = "en" // defaults to "en" // [!code ++]
        override val locale: Locale = Locale.getDefault() // defaults to Locale.getDefault() // [!code ++]
        override val validators: Map<String, (String) -> Boolean>? = mapOf("cnp" to { it.length == 13 }) // a simplified example for custom validator, named "cnp", which checks only the length of the given data // defaults to null // [!code ++]
        override val customHeaders: Map<String, String>? = mapOf("Custom-Header" to "custom header value") // defaults to null // [!code ++]
        override val updateStateEnabled: Boolean = true // defaults to true // [!code ++]
        override val cacheDocuments: Boolean = true // defaults to true // [!code ++]
        override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE // or whatever value fits your use case // [!code ++]
    }, // [!code ++]
    accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic // [!code --]
    customComponentsProvider = object : CustomComponentsProvider {...},
    customStepperHeaderProvider = object : CustomStepperHeaderProvider { ... },
    analyticsCollector = { event ->
        when (event) {
            is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
            is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
        }
    },
    onNewProcessStarted = object : NewProcessStartedHandler.Delegate { ... }
)
```

**12. Update the method for providing access tokens**

The `setAccessTokenProvider` method on the SDK instance has been replaced with `setAccessToken`.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi.Companion.AccessTokenProvider // [!code --]

fun setAccessTokenProvider(accessTokenProvider: AccessTokenProvider) // [!code --]
fun setAccessToken(accessToken: String?) // null or empty argument clears the token // [!code ++]
```

Consequently, all calls to `setAccessTokenProvider` must be replaced with calls to `setAccessToken`:

```kotlin theme={"dark"}
FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "accessTokenValue" }) // [!code --]
Flowx.getInstance().setAccessToken("accessTokenValue") // [!code ++]
```

**13. `closeModalFunc` is now scoped to the `CloseModalProcessScope`**

To be able to query for substitution tags or media library items to display them in the `CloseModalProcessConfirmAlert`, the `closeModalFunc` lambda passed as a parameter when starting (i.e. `Flowx.getInstance.startProcess(...)`) or continuing (i.e. `Flowx.getInstance.continueProcess(...)`) is now scoped to the `CloseModalProcessScope` interface, which allows that.

```kotlin theme={"dark"}
interface CloseModalProcessScope {
    public fun replaceSubstitutionTag(string: String): String
    public fun getMediaResourceUrl(key: String): String?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CloseModalProcessScope` receiver (i.e. they can now be called only from inside a @Composable running in this scope).

> [!TIP]
>
> Methods within the `CloseModalProcessScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.

```kotlin theme={"dark"}
import ai.flowx.android.sdk.api.CloseModalProcessScope

@Composable
private fun ProcessContent(
    uiState: ProcessViewModel.UiState,
    onProcessEnded: (() -> Unit)? = null,
    onCloseProcessModalFunc: ((processName: String) -> Unit)? = null, // [!code --]
    onCloseProcessModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null, // [!code ++]
) {
    when {
        !uiState.projectId.isNullOrBlank() && !uiState.processName.isNullOrBlank() -> {
            Flowx.getInstance().startProcess(
                projectId = uiState.projectId,
                processName = uiState.processName,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
        !uiState.processUuid.isNullOrBlank() -> {
            Flowx.getInstance().continueProcess(
                processUuid = uiState.processUuid,
                isModal = true,
                onProcessEnded = { onProcessEnded?.invoke() },
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(processName) }, // [!code --]
                closeModalFunc = { processName -> onCloseProcessModalFunc?.invoke(this, processName) }, // [!code ++]
            ).invoke()
        }
    }
}
```

When using it, an approach could be this:

```kotlin ProcessActivity.kt theme={"dark"}
setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    ProcessContent(
        ...
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    )
    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
private fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            ...
            text = { Text(replaceSubstitutionTag("@@close_message")) } // `replaceSubstitutionTag` is now accessible through the `CloseModalProcessScope` scope
        )
    }
}
```

**14. Update custom components implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposable // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponent // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomView // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent // [!code --]

import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction // [!code --]
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.FxEnumerationItem // [!code --]
import ai.flowx.android.sdk.api.custom.components.FxEnumeration // [!code ++]

import ai.flowx.android.sdk.api.custom.components.CustomComponentScope // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
    @Deprecated(...) fun provideCustomViewComponent(): CustomViewComponent? = null
}
interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable?
}
interface CustomComposable {
    @Deprecated(...) val isDefined: Boolean
    val composable: @Composable () -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}
@Deprecated(...)
interface CustomViewComponent {
    @Deprecated(...) fun provideCustomView(componentIdentifier: String): CustomView
}
@Deprecated(...)
interface CustomView {...}
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}




interface CustomComponent {

    val composable: @Composable CustomComponentScope.() -> Unit
    fun populateUi(data: Any?)
    fun populateUi(actions: Map<String, CustomComponentAction>)
    fun validate(): Boolean = true
    fun saveData(): JSONObject? = null
}







```

The structural changes include:

* The `CustomComposable` class has been renamed to `CustomComponent`.
* All deprecated properties, methods, and interfaces have been removed. Support for the Android classical View system has been completely discontinued.
* The `provideCustomComposableComponent()` method within `CustomComponentsProvider` has been replaced with `fun provideCustomComponent(): CustomComponent?`.
* The `CustomComposableComponent` class has been removed.
* The provided @Composable function passed to the `composable` property of the `CustomComponent` interface can now only exist and be called within the context of a `CustomComponentScope` receiver.

```kotlin theme={"dark"}
interface CustomComponent {
    val composable: @Composable () -> Unit // [!code --]
    val composable: @Composable CustomComponentScope.() -> Unit // [!code ++]
}
```

```kotlin theme={"dark"}
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(string: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
```

> [!NOTE]
>
> This restricts the usage of previously unrestricted exposed functions to only within the context of the `CustomComponentScope` receiver (i.e., they can now be called only from within a custom component implementation).

> [!TIP]
>
> Methods within the `CustomComponentScope` are now called through the actual scope itself, rather than relying on `Flowx.getInstance()`, since they are no longer visible on the SDK instance.
>
> ```kotlin theme={"dark"}
> Flowx.getInstance().executeAction(...) // [!code --]
> flowxScope.executeAction(...) // [!code ++]
>
> Flowx.getInstance().replaceSubstitutionTag(...) // [!code --]
> flowxScope.replaceSubstitutionTag(...) // [!code ++]
>
> Flowx.getInstance().getMediaResourceUrl(...) // [!code --]
> flowxScope.getMediaResourceUrl(...) // [!code ++]
>
> Flowx.getInstance().getEnumeration(...) // [!code --]
> flowxScope.getEnumeration(...) // [!code ++]
> ```
>
> Consequently, the following changes should be made to access the scope within the custom component ViewModel:
>
> ```kotlin MyCustomComponentViewModel.kt theme={"dark"}
> class MyCustomComponentViewModel() : ViewModel() {
>     private lateinit var flowxScope: CustomComponentScope
>
>     fun setFlowxScope(scope: CustomComponentScope) {
>         flowxScope = scope
>     }
>
>     fun executeSomeRealAction() {
>         actions["someRealAction"]?.let {
>             if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
>                 flowxScope.executeAction(
>                     action = it,
>                     params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
>                 )
>             }
>         }
>     }
> }
> ```
>
> ```kotlin MyCustomComponent.kt theme={"dark"}
> @Composable
> private fun CustomComponentScope.MyCustomComponent(
>     viewModel: MyCustomComponentViewModel
> ) {
>     viewModel.setFlowxScope(this@MyCustomComponent)
>
>     // here goes the rest of the UI implementation
> }
> ```

* The `CustomComponentAction` is no longer a `data class` as before. It is now an `interface`.\\

  The exposed data has been reduced to the maximum required for executing the action:

```kotlin v4.0.25 theme={"dark"}
data class CustomComponentAction(
    internal val actionName: String?,
    internal val type: ActionType?,
    internal var tokenUuid: String?,
    internal var uiActionFlowxUuid: String,
    internal val context: String,
    internal val params: Params?,
    internal val keys: List<String>?,
    internal val customBody: JsonElement?,
    internal val collectionItemData: JsonObject?,
    internal val componentTemplateConfigId: Int,
)
```

```kotlin v9.0.2 theme={"dark"}
interface CustomComponentAction {
    val name: String
    val uiTemplateId: Int
    val uiTemplateContext: String
    val uiTemplateReusableContext: String?
}







```

* When querying for an enumeration by calling the `CustomComponentScope.getEnumeration(...)` method, the returned type has changed from `List<FxEnumerationItem>` to `FxEnumeration`

```kotlin v4.0.25 theme={"dark"}
data class FxEnumerationItem(
    val type: String? = null,
    val order: Int? = null,
    val childContentDescription: ChildContentDescription? = null,
    val code: String? = null,
    val content: String? = null
) {
    data class ChildContentDescription(
        val name: String? = null
    )
}

```

```kotlin v9.0.2 theme={"dark"}
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}
```

These changes are reflected in an actual implementation as shown below:

```kotlin v4.0.25 expandable theme={"dark"}
import ai.flowx.android.sdk.FlowxSdkApi
import ai.flowx.android.sdk.ui.components.custom.CustomComponentAction
import ai.flowx.android.sdk.ui.components.custom.CustomComponentsProvider
import ai.flowx.android.sdk.ui.components.custom.CustomComposable
import ai.flowx.android.sdk.ui.components.custom.CustomComposableComponent
import ai.flowx.android.sdk.ui.components.custom.CustomView
import ai.flowx.android.sdk.ui.components.custom.CustomViewComponent
import ai.flowx.external.android.template.app.R
import android.content.Context
import android.util.AttributeSet
import android.view.View
import android.widget.Button
import android.widget.LinearLayout
import android.widget.TextView
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.LifecycleRegistry
import androidx.lifecycle.ViewModel
import androidx.lifecycle.ViewModelProvider
import androidx.lifecycle.ViewModelStore
import androidx.lifecycle.ViewModelStoreOwner
import androidx.lifecycle.lifecycleScope
import androidx.lifecycle.viewModelScope
import androidx.lifecycle.viewmodel.compose.viewModel
import kotlinx.coroutines.Job
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable =
                object : CustomComposable {

                    val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                    var actions: Map<String, CustomComponentAction> = emptyMap()

                    override val isDefined: Boolean
                        get() = when (componentIdentifier) {
                            "myCustomComponent" -> true // NOTE: set this to false to use the legacy view system instead of compose, which is mainstream now
                            else -> false
                        }

                    override val composable: @Composable () -> Unit = when (componentIdentifier) {
                        "myCustomComponent" -> { {
                            val viewModel = remember { MyCustomComponentViewModel(data, actions) }
                            MyCustomComponent(viewModel = viewModel)
                        } }

                        else -> { {} }
                    }

                    override fun populateUi(data: Any?) {
                        this.data.value = data
                    }

                    override fun populateUi(actions: Map<String, CustomComponentAction>) {
                        this.actions = actions
                    }

                    // Optional override, defaults to `true`.
                    override fun validate(): Boolean = true

                    // Optional override, defaults to `null`.
                    override fun saveData(): JSONObject? = null
                }
        }
    }

    override fun provideCustomViewComponent(): CustomViewComponent? {
        return object : CustomViewComponent {
            override fun provideCustomView(componentIdentifier: String) = object : CustomView {

                val data: MutableStateFlow<Any?> = MutableStateFlow(null)
                var actions: Map<String, CustomComponentAction> = emptyMap()

                override val isDefined: Boolean
                    get() = when (componentIdentifier) {
                        "myCustomComponent" -> true // NOTE: set the compose equivalent component to false to use the legacy view system instead of compose (which is mainstream now)
                        else -> false
                    }

                override fun getView(context: Context): View = when (componentIdentifier) {
                    "myCustomComponent" -> myCustomComponent(context, data, actions)
                    else -> View(context)
                }

                override fun populateUi(data: Any?) {
                    this.data.value = data
                }

                override fun populateUi(actions: Map<String, CustomComponentAction>) {
                    this.actions = actions
                }
            }
        }
    }
}

@Composable
private fun MyCustomComponent(
    viewModel: MyCustomComponentViewModel = viewModel<MyCustomComponentViewModel>()
) {
    val firstName by viewModel.firstName.collectAsState()
    val lastName by viewModel.lastName.collectAsState()
    val dateOfBirth by viewModel.dateOfBirth.collectAsState()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

private fun myCustomComponent(
    context: Context,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
): View {
    return CustomComponentView(context = context, data = data, actions = actions)
}

class CustomComponentView @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    data: MutableStateFlow<Any?> = MutableStateFlow(null),
    actions: Map<String, CustomComponentAction> = emptyMap(),
) : LinearLayout(context, attrs, defStyleAttr), ViewModelStoreOwner, LifecycleOwner {

    private val registry = LifecycleRegistry(this)

    private var job: Job? = null
    private lateinit var client: TextView
    private lateinit var dateOfBirth: TextView

    private val viewModel: MyCustomComponentViewModel by lazy {
        ViewModelProvider(
            store = viewModelStore,
            factory = object : ViewModelProvider.Factory {
                override fun <T : ViewModel> create(modelClass: Class<T>): T {
                    @Suppress("UNCHECKED_CAST")
                    return MyCustomComponentViewModel(data, actions) as T
                }
            }
        )[MyCustomComponentViewModel::class.java]
    }

    init {
        initView()
    }

    private fun initView() {
        View.inflate(context, R.layout.my_custom_component, this)
        client = findViewById<TextView>(R.id.tvClient)
        dateOfBirth = findViewById<TextView>(R.id.tvDateOfBirth)

        findViewById<Button>(R.id.btnConfirm).also {
            it.setOnClickListener {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        }
    }

    override fun onAttachedToWindow() {
        super.onAttachedToWindow()

        if (job?.isActive == true) {
            job?.cancel()
        }

        job = lifecycleScope.launch {
            combine(
                viewModel.firstName,
                viewModel.lastName,
                viewModel.dateOfBirth
            ) { firstName, lastName, dateOfBirth ->
                Triple(firstName, lastName, dateOfBirth)
            }.collect { (fn, ln, dob) ->
                client.text = String.format("Client: %s %s", fn, ln)
                dateOfBirth.text = String.format("Date of Birth: %s", dob)
            }
        }
    }

    override fun onDetachedFromWindow() {
        job?.cancel()
        job = null
        super.onDetachedFromWindow()
    }

    override val viewModelStore: ViewModelStore = ViewModelStore()

    override val lifecycle: Lifecycle = registry
}

class MyCustomComponentViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            FlowxSdkApi.getInstance().executeAction(
                action = it,
                params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
            )
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

```kotlin v9.0.2 expandable theme={"dark"}
import ai.flowx.android.sdk.api.custom.components.CustomComponent
import ai.flowx.android.sdk.api.custom.components.CustomComponentAction
import ai.flowx.android.sdk.api.custom.components.CustomComponentScope
import ai.flowx.android.sdk.api.custom.components.CustomComponentsProvider
import android.widget.Toast
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.lifecycle.ViewModel
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.flow.update
import kotlinx.coroutines.launch
import org.json.JSONObject

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> MyCustomComponent()
            else -> null
        }
}

[private|internal] class MyCustomComponent : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = MyCustomComponentViewModel(data, actions)

    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            MyCustomComponent(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@MyCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@MyCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    // Optional override, defaults to `true`.
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    override fun saveData(): JSONObject? = null
}

@Composable
private fun CustomComponentScope.MyCustomComponent(
    viewModel: MyCustomComponentViewModel
) {
    viewModel.setFlowxScope(this@MyCustomComponent)

    val firstName by viewModel.firstName.collectAsStateWithLifecycle()
    val lastName by viewModel.lastName.collectAsStateWithLifecycle()
    val dateOfBirth by viewModel.dateOfBirth.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(
            text = "Compose Custom Component",
            style = MaterialTheme.typography.titleLarge,
        )
        Spacer(modifier = Modifier.height(16.dp))
        Column(
            modifier = Modifier
                .background(color = Color(0x80FFFF00))
                .padding(16.dp)
                .fillMaxWidth(),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(4.dp)
        ) {
            Text(
                text = "Client: $firstName $lastName",
                style = MaterialTheme.typography.titleMedium,
            )
            Text(
                text = "Date of Birth: $dateOfBirth",
                style = MaterialTheme.typography.titleMedium,
            )
        }
        val context = LocalContext.current
        TextButton(
            onClick = {
                // enable and adjust values to test the action (which was prior defined in the process)
//                viewModel.executeSomeRealAction()
                Toast.makeText(context, "Define action in the process and enable its execution in the code", Toast.LENGTH_LONG).show()
            }
        ) {
            Text(text = "Confirm")
        }
    }
}

class MyCustomComponentViewModel(
    val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    private val _firstName = MutableStateFlow("")
    val firstName = _firstName.asStateFlow()

    private val _lastName = MutableStateFlow("")
    val lastName = _lastName.asStateFlow()

    private val _dateOfBirth = MutableStateFlow("")
    val dateOfBirth = _dateOfBirth.asStateFlow()

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    init {
        viewModelScope.launch {
            data.collect {
                _firstName.value = (it as? JSONObject)?.optString("firstname") ?: ""
                _lastName.value = (it as? JSONObject)?.optString("lastname") ?: ""
                _dateOfBirth.value = (it as? JSONObject)?.optString("dob") ?: ""
            }
        }
    }

    fun executeSomeRealAction() {
        actions["someRealAction"]?.let {
            if (this@MyCustomComponentViewModel::flowxScope.isInitialized) {
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("MyCustomComponent: `someRealAction` action was not found")
    }
}
```

**15. Update custom stepper header implementation**

Update the related imports:

```kotlin theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData // [!code --]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]
```

The new class hierarchy structure is as follows:

```kotlin v4.0.25 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}
interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}
interface ComposableStepperHeader {
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}
interface CustomStepperHeaderData { ... }
```

```kotlin v9.0.2 theme={"dark"}
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}



interface CustomStepperHeader {
    val composable: @Composable (data: Data) -> Unit
    interface Data { ... }
}
```

The structural changes include:

* The `ComposableStepperHeader` class has been renamed to `CustomStepperHeader`.
* The `CustomStepperHeaderData` class has been moved under the `CustomStepperHeader` and renamed to `Data`.
* The `provideCustomComposableStepperHeader()` method within `CustomStepperProvider` has been replaced with `fun provideCustomStepperHeader(): CustomStepperHeader?`.
* The `CustomComposableStepperHeader` class has been removed.

These changes are reflected in an actual implementation as shown below:

```kotlin diff v4.0.25..v9.0.2 focus={2,5,10,14,16,18,22,23,26} theme={"dark"}
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderProvider // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.ComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.api.custom.stepper.CustomStepperHeader // [!code ++]

import ai.flowx.android.sdk.ui.components.custom.CustomComposableStepperHeader // [!code --]
import ai.flowx.android.sdk.ui.components.custom.CustomStepperHeaderData

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? { // [!code --]
        return object : CustomComposableStepperHeader { // [!code --]
            override fun provideComposableStepperHeader(): ComposableStepperHeader { // [!code --]
            override fun provideCustomStepperHeader(): CustomStepperHeader? { // [!code ++]
                return object : ComposableStepperHeader { // [!code --]
                return object : CustomStepperHeader { // [!code ++]
                    override val composable: @Composable (data: CustomStepperHeaderData) -> Unit // [!code --]
                    override val composable: @Composable ((CustomStepperHeader.Data) -> Unit) // [!code ++]
                        get() = @Composable { data ->
                            // custom header implementation
                        }
                }
            }
        } // [!code --]
    } // [!code --]
}
```

**16. Remove usage of the undocumented `updateConfig(config: SdkConfig)` function**

For runtime environment changes, use the `changeEnvironment` method available on the SDK instance.

```kotlin theme={"dark"}
fun updateConfig(config: SdkConfig) // [!code --]
fun changeEnvironment(baseUrl: String, imageBaseUrl: String, enginePath: String) // [!code ++]
```

> [!WARNING]
>
> Do not change the environment while displaying a running process

> [!WARNING]
>
> When changing the environment, ensure the access token is updated properly

**17. Update the start process API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun startProcess(
    workspaceId: String, // [!code ++]
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the project and process to be started

**18. Update the theme setup API call, which now requires an extra `workspaceId` parameter**

```kotlin diff v4.0.25..v9.0.2 theme={"dark"}
fun setupTheme(
    workspaceUuid: String, // [!code ++]
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: Flowx.ThemeAppearance = Flowx.ThemeAppearance.LIGHT, // or DARK
    @MainThread onCompletion: () -> Unit,
)
```

> [!NOTE]
>
> The `workspaceId` is the identifier of the workspace that contains the theme to be loaded

### ProGuard / R8

The SDK now ships with its own `consumer-rules.pro` file containing the required keep rules for correct functionality.\

These rules are automatically merged into the container app’s ProGuard/R8 configuration and applied during code shrinking and obfuscation.\

The container app may add additional rules if its specific logic requires them.

## iOS SDK migration guide

### SDK API changes

#### Start process

The start process API require a `workspaceId`.

```swift theme={"dark"}
public func startProcess(navigationController: UINavigationController,
                         workspaceId: String, 
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

```swift theme={"dark"}
public func startProcess(tabBarController: UITabBarController,
                         workspaceId: String,
                         projectId: String,
                         name: String,
                         params: [String: Any]?,
                         isModal: Bool = false,
                         showLoader: Bool = false,
                         onProcessEnded: (() -> Void)? = nil)
```

#### Setup theme

The setup theme API requires a `workspaceId`.

```swift theme={"dark"}
public func setupTheme(withUuid uuid: String,
                       workspaceId: String,
                       localFileUrl: URL? = nil,
                       appearance: SwiftUI.ColorScheme? = .light,
                       completion: (() -> Void)?)
```


# Post-upgrade troubleshooting
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/migrating-from-v4.7.x-to-5.1/troubleshooting

Common issues and solutions that may occur after upgrading from FlowX v4.7.x to v5.1.0.

This section covers common issues that may occur after completing the upgrade to FlowX.AI 5.1.0 and their solutions.

## Designer login issues

### DataIntegrityViolationException error

If you cannot login to FlowX Designer after the 5.x upgrade and encounter the following error in the authorization-system logs:

```
org.springframework.dao.DataIntegrityViolationException: could not execute statement [ERROR: duplicate key value violates unique constraint "cas_user_username_key"
  Detail: Key (username)=(admin@flowx.ai) already exists.] [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; SQL [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; constraint [cas_user_username_key]
```

**Root Cause**: This error occurs because the `sub` (subject ID) is missing from JWT tokens. Starting with Keycloak version 25, the `sub` claim is not added by default to lightweight access tokens.

**Solution**: Ensure the `basic` Client Scope is created in your Keycloak Realm and added to all FlowX clients.

> [!WARNING]
>
> Since Keycloak version 25, the `sub` claim is not added by default to JWT lightweight tokens. This is a breaking change that affects FlowX.AI authentication.

### How to verify if subject ID is missing

**1. Login attempt**

Try to login to FlowX Designer and note if the login fails.

**2. Capture the token**

1. Open your browser's Developer Tools
2. Navigate to the **Network** tab
3. Attempt to login again
4. Look for a call to: `https://<your-keycloak-address>/auth/realms/flowx/protocol/openid-connect/token`
5. Copy the access token from the response

**3. Decode the token**

1. Go to [https://jwt.io/](https://jwt.io/)
2. Paste the token in the **Encoded** section
3. Check the **Payload** section for the presence of the `sub` claim

> [!TIP]
>
> If the `sub` claim is present, the token should contain a field like: `"sub": "12345678-1234-1234-1234-123456789abc"`

**4. Verify Client Scope configuration**

If the `sub` claim is missing, you need to configure the Client Scope in Keycloak:

1. Login to your Keycloak Admin Console
2. Navigate to your FlowX realm
3. Go to **Client Scopes**
4. Ensure the `basic` client scope exists and includes the `sub` claim
5. Add this client scope to all FlowX clients (FlowX Designer, Admin, etc.)

### Additional resources

> [card] [Keycloak Release Notes](https://www.keycloak.org/docs/latest/release_notes/#lightweight-access-token-to-be-even-more-lightweight)
>
> Official Keycloak documentation about lightweight access token changes

***

## Other common issues

> [!NOTE]
>
> Additional troubleshooting sections will be added as common post-upgrade issues are identified. If you encounter issues not covered here, please consult the FlowX support team.


# FlowX.AI 5.1.0 Release Notes
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.0-october-2025/v5.1.0-october-2025

Introducing Workspaces, Project Data Model, Library-to-Library Dependencies, Data Mappers, Reusable Resources, and more for a more efficient and flexible development experience.

**What's new? 🆕**

> [tab] Reusability
>
> Build once, use everywhere. These features transform how you develop and maintain applications by eliminating duplication and enabling sophisticated modular architectures.
>
> 🔄 [**Project Data Model (PDM)**](#project-data-model-pdm) - Define reusable data types at the project level to ensure consistency across processes\
> 🔄 [**Library-to-Library Dependencies**](#library-to-library-dependencies) - Create complex dependency trees with multiple levels of library-to-library relationships\
> 🔄 [**Data Mappers**](#data-mappers) - Visual drag-and-drop data mapping with reusable parameter definitions\
> 🔄 [**Reusable Resources**](#reusable-resources) - Create and manage UI Templates and Business Functions across multiple processes\
> 🔄 [**Files in Integration Designer**](#files-in-integration-designer) - Enhanced file management and reusability in integration workflows\
> 🔄 [**Resources Overrides**](#resources-overrides) - Localization and customization of core applications across multiple regions with centralized management\
> 🔄 [**Active Policy Overrides**](#active-policy-overrides) - User-specific and role-specific deployment policies for independent testing and controlled rollouts
>
> ### **Project Data Model (PDM)**
>
> > [card] Project Data Model (PDM)
> >
> > > [tab] PDM Overview
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm.png)
> > >
> > > The new Project Data Model feature enables you to define and manage data types at the project level, which can then be reused across all processes within your project.
> >
> > > [tab] PDM Key Features
> > >
> > > > [card] Centralized Management
> > > >
> > > > Define data types once at the project level and reuse them across multiple processes
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to PDM data types automatically propagate to all referencing processes
> > >
> > > > [card] Enhanced Governance
> > > >
> > > > Configure sensitive data and reporting settings at the project level
> > >
> > > > [card] Library Integration
> > > >
> > > > Use data types from libraries in your Project Data Model
> >
> > > [tab] PDM Benefits
> > >
> > > **1. Reduce duplicate work**
> > >
> > > Define common data types like Customer, Product, or Document once instead of recreating them in each process
> > >
> > > **2. Simplify maintenance**
> > >
> > > Update a data type in one place and have changes apply everywhere it's used
> > >
> > > **3. Standardize data structures**
> > >
> > > Enforce consistent naming, structure, and governance across your application
> > >
> > > **4. Accelerate development**
> > >
> > > Create new processes faster by leveraging pre-defined data types
> >
> > > [tab] Example
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/pdm_example1.png)
> > >
> > > Insurance claim processing example
> >
> > [Learn more about Project Data Model](/5.1/docs/building-blocks/project-data-model)
> >
> > New Feature
>
> ***
>
> ### **Library-to-Library Dependencies**
>
> > [card] Library-to-Library Dependencies
> >
> > > [tab] Lib2Lib Dependencies Overview
> > >
> > > ![Library dependencies example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/libs_dependencies.png)
> > >
> > > FlowX.AI 5.1.0 introduces the ability for libraries to depend on other libraries, enabling hierarchical dependency structures and more sophisticated modular architectures.
> >
> > > [tab] Lib2Lib Dependencies Key Features
> > >
> > > > [card] Hierarchical Structure
> > > >
> > > > Create complex dependency trees with multiple levels of library-to-library relationships
> > >
> > > > [card] Resource Inheritance
> > > >
> > > > Projects automatically gain access to resources from the entire dependency hierarchy
> > >
> > > > [card] Version Control
> > > >
> > > > Single-version constraint ensures consistency across the dependency tree
> > >
> > > > [card] Conflict Prevention
> > > >
> > > > Built-in validation prevents circular dependencies and version conflicts
> >
> > > [tab] Lib2Lib Dependencies Benefits
> > >
> > > **1. Enhanced Modularity**
> > >
> > > Break down complex functionality into smaller, focused libraries that can depend on each other
> > >
> > > **2. Team-based Development**
> > >
> > > Enable different teams to own and maintain specific libraries while building on shared foundations
> > >
> > > **3. Specialized Libraries**
> > >
> > > Create country-specific or domain-specific libraries that extend common base libraries
> > >
> > > **4. Simplified Architecture**
> > >
> > > Organize libraries hierarchically, reducing complexity and improving maintainability
> >
> > > [tab] Example Structure
> > >
> > > ![Dependency tree visualization](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/example_dependency_tree.png)
> > >
> > > Example dependency tree with library-to-library dependencies
> > >
> > > > [accordion] Sample dependency hierarchy
> > > >
> > > > ```
> > > > Mortgage Project
> > > > ├── Enums Library (1.6.0)
> > > > ├── Integrations Library (2.5.0)
> > > > │   ├── Commons Library (1.1.0)  
> > > > │   └── Enums Library (1.6.0) # Transitive dependency
> > > > └── Subprocesses Library (1.3.0)
> > > >     └── Enums Library (1.6.0)  # Transitive dependency
> > > > ```
> > > >
> > > > In this example, both Integrations Library and Subprocesses Library depend on other libraries, creating a multi-level hierarchy that the Mortgage Project can leverage.
> >
> > [Learn more about Library Dependencies](../../../../5.1/docs/projects/managing-applications/dependencies)
> >
> > Major Enhancement
>
> ### **Data Mappers**
>
> > [card] Data Mappers
> >
> > > [tab] Data Mappers Overview
> > >
> > > <video />
> > >
> > > Data Mappers enable users to visually map data transfers between components with intuitive drag-and-drop functionality while maintaining full backward compatibility with existing implementations.
> >
> > > [tab] Data Mappers Key Features
> > >
> > > > [card] Visual Data Mapping
> > > >
> > > > Drag-and-drop interface for mapping data between source and destination components
> > >
> > > > [card] Component Integration
> > > >
> > > > Seamlessly connect processes, subprocesses, workflows, and business rules
> > >
> > > > [card] Parameter Management
> > > >
> > > > Define input/output parameters with predefined and flexible parameter types
> > >
> > > > [card] Backward Compatibility
> > > >
> > > > Choose between new Data Mapper or existing implementation methods
> >
> > > [tab] Data Mappers Benefits
> > >
> > > **1. Simplified Integration**
> > >
> > > Visual interface eliminates complex configuration syntax and reduces integration errors
> > >
> > > **2. Enhanced Reusability**
> > >
> > > Define parameters once and reuse across multiple components and processes
> > >
> > > **3. Improved Governance**
> > >
> > > Centralized parameter management with clear data flow visibility
> > >
> > > **4. Zero Migration Risk**
> > >
> > > Optional adoption with full backward compatibility ensures smooth transition
> >
> > > [tab] Data Mappers Use Cases
> > >
> > > > [card] Call Activity Mapping
> > > >
> > > > Map data between parent processes and subprocesses (sync/async)
> > >
> > > > [card] Integration Workflows
> > > >
> > > > Connect processes with Integration Designer workflows
> > >
> > > > [card] Business Rules
> > > >
> > > > Pass data to and from business rule executions
> > >
> > > > [card] Node-to-Node Data Flow
> > > >
> > > > Map data between workflow nodes (REST endpoints, data persistence)
> >
> > [Learn more about Data Mappers](../../../../5.1/docs/building-blocks/process/data-mappers)
> >
> > New Feature
>
> ***
>
> ### **Reusable Resources**
>
> > [card] Reusable Resources
> >
> > > [tab] Reusable Resources Overview
> > >
> > > ![Reusable Resources in FlowX.AI Designer](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-07-31%20at%2018.08.38.png)
> > >
> > > FlowX.AI 5.1.0 introduces Reusable Resources, a new section that eliminates repetitive development work by enabling you to create and manage both UI Templates and Business Functions that can be used across multiple processes and projects.
> >
> > > [tab] Reusable Functions
> > >
> > > > [card] Business Logic Reuse
> > > >
> > > > Create JavaScript or Python functions once and use them across multiple processes via Business Rule actions
> > >
> > > > [card] Data Model Integration
> > > >
> > > > Define input/output parameters with full project data model integration and testing capabilities
> > >
> > > > [card] Interactive Testing
> > > >
> > > > Test functions with sample data in real-time before deployment to ensure accuracy
> > >
> > > > [card] Automatic Propagation
> > > >
> > > > Changes to functions automatically update all instances across your application
> >
> > > [tab] Reusable UI Templates
> > >
> > > > [card] UI Component Reuse
> > > >
> > > > Design UI components once and instantiate them across multiple User Tasks with automatic data binding
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all templates from the new Reusable Resources section alongside Reusable Functions
> > >
> > > > [card] Omnichannel Support
> > > >
> > > > Templates work seamlessly across different platforms and channels
> > >
> > > > [card] Flexible UI Actions
> > > >
> > > > Define UI actions within templates with two scenarios: template-defined actions or form-centric data handling
> >
> > > [tab] Key Problems Solved
> > >
> > > **1. Eliminate repetitive development**
> > >
> > > Stop recreating the same business logic and UI patterns across different processes - build once, use everywhere
> > >
> > > **2. End manual component updates**
> > >
> > > Update functions and templates in one place to automatically affect all instances across your application
> > >
> > > **3. Centralized template management**
> > >
> > > Replace scattered, inconsistent UI patterns with centrally managed, reusable components
> > >
> > > **4. Accelerate time-to-market**
> > >
> > > Build new processes faster by leveraging pre-built, tested components instead of starting from scratch
> >
> > > [tab] Real-World Examples
> > >
> > > > [accordion] Reusable Functions Examples
> > > >
> > > > **Customer Data Validation Function:**
> > > >
> > > > * **Input**: firstName, lastName, email, phone
> > > > * **Logic**: Format validation, duplicate checking, data standardization
> > > > * **Output**: validatedCustomer object with formatted data
> > > > * **Usage**: Customer onboarding, profile updates, registration processes across all channels
> > > >
> > > > **Credit Risk Assessment Function:**
> > > >
> > > > * **Input**: applicationData, customerProfile, financialHistory
> > > > * **Logic**: Complex credit scoring algorithms, risk categorization, recommendation engine
> > > > * **Output**: riskScore, riskCategory, approvalRecommendation, requiredDocuments
> > > > * **Usage**: Loan applications, credit cards, mortgage processes, business lending
> > > >
> > > > **Document Processing Function:**
> > > >
> > > > * **Input**: documentFile, documentType, customerID
> > > > * **Logic**: OCR processing, data extraction, compliance validation
> > > > * **Output**: extractedData, validationStatus, complianceFlags
> > > > * **Usage**: KYC processes, claims processing, application reviews
> > >
> > > > [accordion] Reusable UI Templates Examples
> > > >
> > > > **Personal Details Card Template:**
> > > >
> > > > * **Root Component**: Card with professional styling
> > > > * **Contains**: Name, email, phone, address input fields with validation
> > > > * **UI Actions**: Save data, clear form, auto-populate from existing data
> > > > * **Usage**: Customer registration, profile updates, employee onboarding, contractor management
> > > >
> > > > **Document Upload Section Template:**
> > > >
> > > > * **Root Component**: Container with drag-and-drop functionality
> > > > * **Contains**: File upload area, progress indicators, document list, preview capabilities
> > > > * **UI Actions**: Upload documents, delete files, download copies, validate formats
> > > > * **Usage**: Loan applications, compliance documentation, claims submissions, HR processes
> > > >
> > > > **Financial Summary Dashboard Template:**
> > > >
> > > > * **Root Component**: Card with data visualization
> > > > * **Contains**: Balance displays, transaction history, chart components, action buttons
> > > > * **UI Actions**: Refresh data, export reports, drill-down details
> > > > * **Usage**: Account overviews, investment portfolios, expense tracking, budget management
> >
> > [Learn about Reusable Functions](../../../../5.1/docs/building-blocks/reusable-resources/reusable-functions)
> >
> > [Learn about UI Templates](../../../../5.1/docs/building-blocks/reusable-resources/reusable-ui)
> >
> > Major Feature
>
> ***
>
> ### **Files in Integration Designer**
>
> > [card] Files in Integration Designer
> >
> > > [tab] Files Overview
> > >
> > > ![Integration Designer file workflows](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/fh.png)
> > >
> > > FlowX.AI 5.1.0 introduces comprehensive file handling capabilities in Integration Designer, resolving previous limitations where sending or receiving documents, photos, or any files via Integration Designer was not supported. This powerful enhancement enables seamless file exchange with external systems through automated workflows.
> >
> > > [tab] Core File Scenarios
> > >
> > > > [card] File Downloads
> > > >
> > > > Process calls external API (GET/POST) and receives files in response. Integration Designer saves files to specified location and returns paths to workflow
> > >
> > > > [card] File Uploads
> > > >
> > > > Process sends files stored in Document Plugin or S3 Bucket to external API via POST request. Workflow transmits file path for seamless transfer
> > >
> > > > [card] Document Plugin Integration
> > > >
> > > > Seamless integration with FlowX.AI Document Plugin for process-specific file management and organization
> > >
> > > > [card] S3 Storage Support
> > > >
> > > > Custom S3 bucket storage for files not tied to specific process instances or when Document Plugin is unavailable
> >
> > > [tab] Enhanced Capabilities
> > >
> > > **1. Automated File Exchange**
> > >
> > > Enable seamless file transfer with external systems without manual handling or complex custom integrations
> > >
> > > **2. Flexible Storage Options**
> > >
> > > Choose between Document Plugin for process-specific files or S3 Protocol for independent file operations
> > >
> > > **3. Workflow Integration**
> > >
> > > Files are automatically integrated into workflow processes with proper path management and metadata handling
> > >
> > > **4. External Service Communication**
> > >
> > > Communicate effectively with document services, AI processing systems, report generators, and CMS platforms
> >
> > > [tab] Real-World Use Cases
> > >
> > > > [accordion] Contract Generation Workflows
> > > >
> > > > **Scenario**: Generate personalized contracts using external document services
> > > >
> > > > * **Process Flow**: Send customer data → External contract service → Receive generated PDF contract
> > > > * **Integration**: Customer information flows to document generation API, completed contracts return to process
> > > > * **Storage**: Generated contracts stored in Document Plugin for process tracking and audit trails
> > > > * **Business Value**: Automated contract creation with legal template compliance and version control
> > >
> > > > [accordion] Document Processing & OCR
> > > >
> > > > **Scenario**: Process uploaded documents through external AI/OCR services
> > > >
> > > > * **Process Flow**: Upload document → AI processing service → Receive extracted data and processed files
> > > > * **Integration**: Documents sent to AI services for text extraction, classification, or compliance validation
> > > > * **Storage**: Processed documents and extracted data stored for business logic processing
> > > > * **Business Value**: Automated document processing with intelligent data extraction capabilities
> > >
> > > > [accordion] Report Generation & Analytics
> > > >
> > > > **Scenario**: Generate business reports using external reporting services
> > > >
> > > > * **Process Flow**: Send business data → Reporting service → Receive formatted reports (PDF, Excel)
> > > > * **Integration**: Business metrics and KPIs sent to specialized reporting engines
> > > > * **Storage**: Generated reports available for download and distribution workflows
> > > > * **Business Value**: Professional report generation with advanced formatting and visualization capabilities
> > >
> > > > [accordion] CMS & Content Management
> > > >
> > > > **Scenario**: Integrate with content management systems for file organization
> > > >
> > > > * **Process Flow**: Upload files → CMS integration → Organize and categorize content
> > > > * **Integration**: Files uploaded to external CMS platforms with metadata and categorization
> > > > * **Storage**: S3 Protocol ideal for CMS integrations with unassociated documents
> > > > * **Business Value**: Centralized content management with automated workflow integration
> >
> > [Learn more about Integration Designer](../../../../5.1/docs/platform-deep-dive/integrations/integration-designer)
> >
> > Major Enhancement
>
> ***
>
> ### **Resources Overrides**
>
> > [card] Resources Overrides
> >
> > > [tab] Resources Overrides Overview
> > >
> > > ![Resources Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ro1.png)
> > >
> > > Resources Overrides enable localization and customization of core business applications across multiple regions while maintaining centralized updates from headquarters. This powerful feature allows organizations to adapt specific business logic, compliance requirements, or local regulations without losing connection to the master application.
> >
> > > [tab] Key Features
> > >
> > > > [card] Localization Control
> > > >
> > > > Customize processes, workflows, and enumerations for different countries or regions while maintaining core functionality
> > >
> > > > [card] Centralized Management
> > > >
> > > > Manage all resource overrides through the Dependencies page with comprehensive override tracking and configuration
> > >
> > > > [card] Selective Overriding
> > > >
> > > > Override only specific resources that need localization while inheriting all other updates from the main library
> > >
> > > > [card] Export/Import Support
> > > >
> > > > Automatically include override configurations in project exports and imports for seamless environment management
> >
> > > [tab] Business Benefits
> > >
> > > **1. Accelerate Global Expansion**
> > >
> > > Deploy core applications to new regions quickly by overriding only country-specific elements instead of rebuilding from scratch
> > >
> > > **2. Maintain Compliance**
> > >
> > > Adapt business logic and data handling to meet local regulatory requirements while preserving global standards
> > >
> > > **3. Preserve Investment**
> > >
> > > Continue receiving updates and improvements from headquarters without losing local customizations
> > >
> > > **4. Reduce Maintenance Overhead**
> > >
> > > Manage regional variations centrally instead of maintaining completely separate application instances
> >
> > > [tab] Supported Resource Types
> > >
> > > > [card] Process Overrides
> > > >
> > > > Customize business process logic while maintaining input/output compatibility and core workflow structure
> > >
> > > > [card] Workflow Overrides
> > > >
> > > > Replace entire workflow implementations to adapt business rules for local requirements
> > >
> > > > [card] Enumeration Overrides
> > > >
> > > > Localize value lists, dropdown options, and classification systems for regional variations
> > >
> > > > [card] Runtime Resolution
> > > >
> > > > Overrides are resolved dynamically at runtime, ensuring the correct regional version is always used
> >
> > > [tab] Real-World Applications
> > >
> > > > [accordion] Multi-National Banking
> > > >
> > > > **Scenario**: Global bank with country-specific loan approval processes
> > > >
> > > > * **Global Library**: Common loan application workflow with standard validation steps
> > > > * **Country Overrides**: Local credit scoring algorithms, regulatory compliance checks, documentation requirements
> > > > * **Business Value**: Single platform maintenance with automated compliance for each country's banking regulations
> > >
> > > > [accordion] Insurance Operations
> > > >
> > > > **Scenario**: Insurance company operating across different regulatory environments
> > > >
> > > > * **Global Library**: Standard claims processing workflow and policy management
> > > > * **Regional Overrides**: Country-specific coverage types, claim validation rules, regulatory reporting
> > > > * **Business Value**: Consistent global operations with local market adaptation and compliance
> > >
> > > > [accordion] Manufacturing & Supply Chain
> > > >
> > > > **Scenario**: Manufacturing company with different operational requirements per region
> > > >
> > > > * **Global Library**: Core production planning and inventory management processes
> > > > * **Local Overrides**: Regional supplier networks, compliance standards, environmental regulations
> > > > * **Business Value**: Standardized operations with flexibility for local business practices and regulations
> >
> > [Learn more about Resources Overrides](../../../../5.1/docs/projects/resources#resources-overrides)
> >
> > Major Enhancement
>
> ***
>
> ### **Active Policy Overrides**
>
> > [card] Active Policy Overrides
> >
> > > [tab] Active Policy Overrides Overview
> > >
> > > ![Active Policy Overrides management interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ap2.png)
> > >
> > > Active Policy Overrides enable user-specific and role-specific deployment policies that allow independent testing of different builds or branches without affecting the global policy. This powerful feature provides granular control over which project versions different users access in runtime environments.
> >
> > > [tab] Key Features
> > >
> > > > [card] User-Specific Policies
> > > >
> > > > Create individual policy overrides for specific users to test different builds independently
> > >
> > > > [card] Role-Based Overrides
> > > >
> > > > Apply policy overrides to entire roles for team-based testing and deployment strategies
> > >
> > > > [card] Priority-Based Resolution
> > > >
> > > > Handle conflicts when multiple overrides apply using configurable priority systems
> > >
> > > > [card] Real-Time Switching
> > > >
> > > > Switch between different project versions instantly without deployment downtime
> >
> > > [tab] Business Benefits
> > >
> > > **1. Independent Testing**
> > >
> > > Enable QA teams and developers to test different builds simultaneously without interfering with production users
> > >
> > > **2. Controlled Rollouts**
> > >
> > > Gradually deploy new features to specific user groups before full production release
> > >
> > > **3. Emergency Rollback**
> > >
> > > Quickly revert specific users to stable versions during incidents without affecting the entire system
> > >
> > > **4. Branch-Specific Development**
> > >
> > > Allow different teams to work with different development branches in shared environments
> >
> > > [tab] Override Management
> > >
> > > > [card] Policy Types
> > > >
> > > > Support for both "Latest on Branch" and specific "Build" policies with flexible branch and version selection
> > >
> > > > [card] Search & Filter
> > > >
> > > > Real-time search functionality to quickly locate specific user or role overrides
> > >
> > > > [card] Activation Control
> > > >
> > > > Enable or disable overrides without deletion for temporary testing scenarios
> > >
> > > > [card] Conflict Resolution
> > > >
> > > > Clear hierarchy: User overrides > Role overrides > Global policy with priority-based resolution
> >
> > > [tab] Real-World Scenarios
> > >
> > > > [accordion] Development Team Testing
> > > >
> > > > **Scenario**: Frontend team needs to test with latest UI changes while backend team tests API updates
> > > >
> > > > * **Override Setup**: Create role-based overrides for "Frontend Developers" and "Backend Developers"
> > > > * **Policy Configuration**: Frontend role uses latest on `ui-redesign` branch, Backend role uses `api-v2` branch
> > > > * **Business Value**: Parallel development with isolated testing environments and no cross-team interference
> > >
> > > > [accordion] Gradual Feature Rollout
> > > >
> > > > **Scenario**: New premium features need testing with select customers before full release
> > > >
> > > > * **Override Setup**: Create user-specific overrides for beta customers and internal stakeholders
> > > > * **Policy Configuration**: Beta users get latest build with premium features, others remain on stable version
> > > > * **Business Value**: Risk mitigation through controlled exposure and real-world testing feedback
> > >
> > > > [accordion] Emergency Response
> > > >
> > > > **Scenario**: Critical bug discovered in production affecting specific user workflows
> > > >
> > > > * **Override Setup**: Create high-priority role override for affected user groups
> > > > * **Policy Configuration**: Temporarily revert affected users to last stable build while others continue normally
> > > > * **Business Value**: Immediate incident response with minimal user impact and service continuity
> >
> > [Learn more about Active Policy Overrides](../../../../5.1/docs/projects/runtime/active-policy)
> >
> > Major Enhancement

> [tab] Persistence
>
> Advanced data management and storage capabilities that enable new architectural patterns and improved data governance.
>
> 🔄 [**Workspaces (Multi-Tenant Architecture)**](#workspaces-multi-tenant-architecture) - Logical separation of business contexts with shared infrastructure\
> 🔄 [**FlowX.AI Database**](#flowx-ai-database) - New persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
>
> ### **Workspaces (Multi-Tenant Architecture)**
>
> > [card] Workspaces
> >
> > > [tab] Workspaces Overview
> > >
> > > ![Workspaces multi-tenant architecture](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/org%20Admin.png)
> > >
> > > FlowX.AI 5.1.0 introduces Workspaces, enabling organizations to manage multiple business lines, verticals, or countries within a single FlowX.AI instance while maintaining complete data isolation.
> >
> > > [tab] Workspaces Key Features
> > >
> > > > [card] Multi-Tenant Architecture
> > > >
> > > > Logical separation of business contexts with shared infrastructure
> > >
> > > > [card] Enhanced Access Control
> > > >
> > > > Role-based access control (RBAC) and Access Control Lists (ACLs) with workspace-specific permissions
> > >
> > > > [card] Data Isolation
> > > >
> > > > Complete logical isolation between workspaces while enabling controlled resource sharing
> > >
> > > > [card] User Groups & Roles
> > > >
> > > > Simplified permission management through groups and workspace-specific roles
> >
> > > [tab] Workspaces Benefits
> > >
> > > **1. Accelerated Onboarding**
> > >
> > > Onboard new business verticals in days instead of weeks with shared platform capabilities
> > >
> > > **2. Enhanced Governance**
> > >
> > > Implement fine-grained access control with workspace-specific roles and permissions
> > >
> > > **3. Operational Efficiency**
> > >
> > > Centralize platform upgrades, maintenance, and monitoring across all business units
> >
> > > [tab] Workspaces Use Cases
> > >
> > > > [card] Multi-National Operations
> > > >
> > > > Separate workspaces for different countries/regions with shared global processes
> > >
> > > > [card] Business Unit Separation
> > > >
> > > > Independent workspaces for retail, corporate, and investment banking divisions
> > >
> > > > [card] Regulatory Compliance
> > > >
> > > > Isolate processes subject to different regulatory requirements
> > >
> > > > [card] Team-Based Development
> > > >
> > > > Enable different teams to work independently while sharing common resources
> >
> > [Learn more about Workspaces](../../../../5.1/docs/projects/workspaces)
> >
> > Platform Evolution
>
> ***
>
> ### **FlowX.AI Database**
>
> > [card] FlowX.AI Database
> >
> > > [tab] FlowX.AI Database Overview
> > >
> > > <video />
> > >
> > > FlowX.AI Database is a new persistence layer that enables you to store and retrieve data across different processes and applications, without relying on external systems.
> >
> > > [tab] FlowX.AI Database Key Features
> > >
> > > > [card] Data Persistence
> > > >
> > > > Store data that persists beyond process instances
> > >
> > > > [card] MongoDB Operations
> > > >
> > > > Find, insert, and manipulate data using familiar MongoDB operations
> > >
> > > > [card] Workflow Integration
> > > >
> > > > Seamlessly integrate with workflows through Data Source nodes
> > >
> > > > [card] Document Collections
> > > >
> > > > Organize your data in structured collections
> >
> > > [tab] FlowX.AI Database Benefits
> > >
> > > **1. Share data between processes**
> > >
> > > Enable communication and data sharing between different process instances
> > >
> > > **2. Reduce external dependencies**
> > >
> > > Store operational data within FlowX.AI instead of building custom connectors
> > >
> > > **3. Enable new use cases**
> > >
> > > Build dashboards, caching solutions, and other applications that require persistent data
> > >
> > > **4. Simplify architecture**
> > >
> > > Keep your data within the FlowX.AI ecosystem for improved security and simplicity
> >
> > > [tab] UI Integration
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/470/flowx_db_select.png)
> > >
> > > FlowX.AI Database as a Data Source type
> > >
> > > FlowX.AI Database integrates directly into the existing Integration Designer as a new Data Source type alongside RESTful System, making it easy to create and manage database collections without learning new interfaces.
> >
> > [Learn more about FlowX.AI Database](../../../../5.1/docs/platform-deep-dive/integrations/flowx-database)
> >
> > New Feature

> [tab] Rendering Improvements & UI/UX Enhancements
>
> Enhanced user experience through improved components, better performance, and streamlined interface design.
>
> 🎨 [**Rendering Improvements & UI/UX Enhancements**](#rendering-improvements-&-ui/ux-enhancements) - Enhanced grid components, navigation redesign, advanced form controls, and analytics capabilities\
> 📋 [**Forms in Collections**](#forms-in-collections) - Enhanced support for form elements within collection components, enabling complex data entry scenarios\
> 🔄 [**Multi Select UI Component**](#multi-select-ui-component) - Allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
>
> ### **Rendering Improvements & UI/UX Enhancements**
>
> > [card] Rendering Improvements & UI/UX Enhancements
> >
> > FlowX.AI 5.1.0 delivers comprehensive UI/UX improvements that enhance the user experience across all platform components, from streamlined navigation to advanced form controls and better workflow handling.
> >
> > ## Interface & Navigation Improvements
> >
> > > [card] Enhanced Grid Component
> > >
> > > Improved performance, responsiveness, and customization options for data display and form organization
> >
> > > [card] Navigation Areas Redesign
> > >
> > > Streamlined navigation experience in both UI Designer and Process Designer with improved interface organization
> >
> > > [card] Multi Actions Support
> > >
> > > Batch operations support for UI components, enabling simultaneous actions on multiple elements, multi select, multi copy/paste, multi drag and drop, multi delete
> >
> > > [card] [Permission-Based UI Editing](../../../../5.1/docs/building-blocks/ui-designer/ui-designer#permission-based-expressions)
> > >
> > > Granular control over UI element editing based on user permissions with partial editing capabilities, allow multiple executors on swimlane level
> >
> > ## Enhanced Form Controls & Components
> >
> > > [card] [Input Type Code](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/input-form-field#input-types)
> > >
> > > Specialized input component for code entry
> >
> > > [card] Formatting Options
> > >
> > > Advanced formatting capabilities for Input and Slider components
> >
> > > [card] [Switch Variants](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/switch-form-field#switch-type)
> > >
> > > Enhanced switch component supporting both toggle and checkbox variants
> >
> > > [card] [Disabled Options on Selectors](/5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select#disabled-options)
> > >
> > > Configure specific options as disabled while keeping them visible in dropdown lists
> >
> > ## User Experience Enhancements
> >
> > > [card] Custom Loader
> > >
> > > Configurable loading indicators for improved user experience during data operations
> >
> > > [card] [Custom Expression Validators](../../../../5.1/docs/building-blocks/ui-designer/validators#custom-validators)
> > >
> > > Advanced validation logic using dynamic computed expressions that can reference other process data values. Write JavaScript expressions that return boolean values for cross-field validation scenarios
> >
> > > [card] File Upload Button Type
> > >
> > > Introduces a specialized button variant for file upload operations, supporting **fill**, **ghost**, and **text** types for flexible UI styling.
> >
> > > [card] Copy Styles
> > >
> > > Efficiently replicate styling across multiple UI components
> >
> > ## Workflow & Analytics Improvements
> >
> > > [card] Analytics Enhancements
> > >
> > > Custom payload support for detailed user interaction tracking and business intelligence
> >
> > > [card] Process End Handling
> > >
> > > Improved user experience when processes complete or terminate
> >
> > > [card] Template Management
> > >
> > > Streamlined template organization by consolidating functionality in Reusable Resources
>
> ***
>
> ### **Forms in Collections**
>
> > [card] Forms in Collections
> >
> > A powerful new feature that enables dynamic, repeatable forms within collection prototypes, eliminating the need for custom development when building forms with repeatable sections like co-debtors, comments, or any list of similar items.
> >
> > <video />
> >
> > ## Key Capabilities
> >
> > > [card] No Custom Development
> > >
> > > Drag Form components directly into Collection Prototypes - they automatically repeat for each item in your data array
> >
> > > [card] Flexible Validation
> > >
> > > Choose between individual item validation or bulk validation across all collection items
> >
> > > [card] Two Saving Scenarios
> > >
> > > Individual save (one item at a time) or bulk save (entire collection) with different validation behaviors
> >
> > ## Common Use Cases Solved
> >
> > **1. Dynamic Forms**
> >
> > Build forms that show different elements based on conditions without custom development
> >
> > **2. Repeatable Sections**
> >
> > Create forms with sections like adding multiple co-debtors, comments, or family members
> >
> > **3. Complex Data Entry**
> >
> > Handle arrays of objects with proper validation and data management
> >
> > **4. Real-time vs Batch Processing**
> >
> > Choose individual saves for real-time editing or bulk saves for form completion workflows
>
> ***
>
> ### **Multi Select UI Component**
>
> > [card] Multi Select UI Component
> >
> > > [tab] Multi Select Overview
> > >
> > > ![Multi Select form field](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select.png)
> > >
> > > The new Multi Select component allows users to choose multiple options from a predefined list, expanding upon the existing single Select component to support multi-value scenarios.
> >
> > > [tab] Key Features
> > >
> > > > [card] Multiple Selections
> > > >
> > > > Users can select multiple options from dropdown lists, with values stored as arrays
> > >
> > > > [card] Flexible Display Options
> > > >
> > > > Show selections as chips, comma-separated lists, or custom formats
> > >
> > > > [card] Selection Limits
> > > >
> > > > Configure maximum number of selectable options to control user input
> > >
> > > > [card] Search & Filter
> > > >
> > > > Built-in search functionality to filter through large option lists
> >
> > > [tab] Multi Select Use Cases
> > >
> > > **1. Skills & Competencies**
> > >
> > > Allow users to select multiple skills, qualifications, or areas of expertise
> > >
> > > **2. Categories & Tags**
> > >
> > > Enable selection of multiple categories, tags, or classification options
> > >
> > > **3. Product Features**
> > >
> > > Let customers choose multiple product features, services, or add-ons
> > >
> > > **4. Preferences & Settings**
> > >
> > > Capture user preferences where multiple options can be active simultaneously
> >
> > > [tab] Configuration
> > >
> > > ![Multi Select configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/multi_select_props.png)
> > >
> > > Multi Select configuration options
> > >
> > > Configure Multi Select components with the same ease as other form elements. Set maximum selections, display formats, search options, and validation rules through the familiar UI Designer interface.
> > >
> > > > [accordion] Key Configuration Options
> > > >
> > > > * **Max. Options Selectable**: Limit the number of selections
> > > > * **Show selections**: Choose how selected items are displayed
> > > > * **Search for options**: Enable filtering within large lists
> > > > * **Has Clear**: Allow users to clear all selections at once
> > > > * **Validation rules**: Min/max selections, required validations
> >
> > [Learn more about Multi Select](../../../../5.1/docs/building-blocks/ui-designer/ui-component-types/form-elements/multi-select)
> >
> > New Component

> [tab] AI Platform
>
> New AI capabilities in Integration Designer for processing text, documents, images, and data using AI-powered nodes.
>
> 🤖 [**AI Nodes in Integration Designer**](#ai-nodes-in-integration-designer) - Process text, documents, images, and data using AI-powered workflow nodes
>
> ### **AI Nodes in Integration Designer**
>
> > [card] AI Nodes in Integration Designer
> >
> > > [tab] AI Nodes Overview
> > >
> > > ![AI Nodes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/ai_nodes.png)
> > >
> > > FlowX.AI 5.1.0 introduces AI-powered nodes in Integration Designer, enabling intelligent processing of text, documents, images, and data within your workflows. These nodes bring AI capabilities directly into your integration flows without requiring external AI services.
> >
> > > [tab] AI Text Operations
> > >
> > > > [card] Text Transformation
> > > >
> > > > Modify text tone, complexity or formatting for better clarity or style
> > >
> > > > [card] Text Understanding
> > > >
> > > > Analyze text to determine sentiment, topics, intent, language and named entities
> > >
> > > > [card] Text Generation
> > > >
> > > > Generate new text such as summaries, completions, translations or paraphrases
> > >
> > > > [card] Text Extraction
> > > >
> > > > Extract structured information, keywords or metadata from text
> >
> > > [tab] AI Document Operations
> > >
> > > > [card] Document Generation
> > > >
> > > > Automatically build reports or complete templates based on given inputs
> > >
> > > > [card] Document Extraction
> > > >
> > > > Identify and extract structured data, entities or metadata from documents
> > >
> > > > [card] Document Understanding
> > > >
> > > > Analyze documents to extract meaning, topics, sentiment, or important information
> > >
> > > > [card] Extract Text from Document
> > > >
> > > > Extract text content from documents (OCR, PDF text extraction)
> >
> > > [tab] AI Image & Data Operations
> > >
> > > **Image Operations:**
> > >
> > > > [card] Image Description
> > > >
> > > > Generate captions or extract detailed information from visual content
> > >
> > > > [card] Image Analysis
> > > >
> > > > Recognize objects, emotions and scenes in images for contextual understanding
> > >
> > > **Data Operations:**
> > >
> > > > [card] Data Enrichment
> > > >
> > > > Add annotations, context or relationships to enhance raw data value
> > >
> > > > [card] Data Generation
> > > >
> > > > Produce synthetic or structured data using templates and logic-based rules
> > >
> > > > [card] Data Transformation
> > > >
> > > > Clean, normalize, aggregate, or restructure datasets into usable formats
> >
> > > [tab] Use Cases
> > >
> > > > [accordion] Intelligent Document Processing
> > > >
> > > > * Extract data from invoices, contracts, and forms
> > > > * Classify documents automatically
> > > > * Validate extracted information against business rules
> > >
> > > > [accordion] Customer Communication Analysis
> > > >
> > > > * Analyze customer feedback sentiment
> > > > * Extract key topics from support tickets
> > > > * Generate personalized responses
> > >
> > > > [accordion] Content Generation
> > > >
> > > > * Create summaries of long documents
> > > > * Translate content to multiple languages
> > > > * Generate reports from structured data
> > >
> > > > [accordion] Data Processing
> > > >
> > > > * Enrich customer data with AI-derived insights
> > > > * Transform unstructured data to structured formats
> > > > * Generate test data for development
> >
> > [Learn more about AI Node Types](../../../../5.1/docs/platform-deep-dive/integrations/ai-nodes)
> >
> > New Feature

> [tab] Info
>
> ## **Additional information**
>
> > [card] [Deployment Guidelines v5.1](./deployment-guidelines-v5.1)
> >
> > Instructions for deploying FlowX.AI 5.1.0
>
> > [card] [Migration Guide (from v4.7.x)](./migrating-from-v4.7.x-to-5.1/migration-overview)
> >
> > Step-by-step guide for migrating from v4.7.x to v5.1.0


# FlowX.AI 5.1.1 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.1-november-2025

WCAG 2.1 Level AA compliance achieved, AI Platform enhancements, bug fixes, and quality improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **accessibility compliance**, **AI Platform enhancements**, **customer issue resolution**, and **proactive quality improvements**.
> Upgrades from **5.1.0 → 5.1.1** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Quality Achievement**: FlowX.AI 5.1.1 demonstrates our commitment to proactive quality improvement:
>
> * **[WCAG 2.1 Level AA compliance](https://www.w3.org/TR/WCAG21/)** achieved across all web components
> * **Proactive quality improvements** identified through internal QA before reaching customers
> * **Customer issues** resolved with full business context
> * **Zero breaking changes** - fully compatible upgrade from 5.1.0
>
> This release represents months of accessibility audits, automated testing, and quality assurance work to deliver exceptional software quality.

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.1 delivers comprehensive improvements across accessibility, stability, and platform reliability.
>
> ♿  [**WCAG 2.1 Compliance Achieved**](#wcag-2-1-compliance) - Full accessibility support across all web components\
> 🌍 [**Task Management Localization**](#task-management-localization) — Comprehensive multi-language support with 51 substitution tags\
> 🤖 [**AI Platform Enhancements**](#ai-platform-enhancements) — Multi-agent system improvements and AI workflow stability\
> 🎯 [**Customer Fixes**](#customer-fixes) — Critical issues resolved based on customer feedback\
> ✨ [**Proactive Improvements**](#proactive-quality-improvements) — Issues identified through internal QA before reaching customers\
> 🔧 [**Platform Enhancements**](#platform-enhancements) — SSE handling, audit logs, and infrastructure improvements
>
> ### **WCAG 2.1 compliance**
>
> > [card] WCAG 2.1 compliance
> >
> > > [tab] Overview
> > >
> > > **FlowX.AI is now WCAG 2.1 Level AA compliant**
> > >
> > > This release delivers full accessibility support through **28 comprehensive improvements** across Angular and React SDKs, making FlowX applications usable by everyone, including users with disabilities.
> > >
> > > ### Business value
> > >
> > > > [card] Government Compliance
> > > >
> > > > Meet accessibility requirements for government and public sector applications
> > >
> > > > [card] Healthcare Standards
> > > >
> > > > Comply with healthcare industry accessibility regulations and standards
> > >
> > > > [card] Financial Services
> > > >
> > > > Satisfy financial sector requirements for inclusive digital experiences
> > >
> > > > [card] Universal UX
> > > >
> > > > Keyboard navigation and clear labels improve usability for all users, not just those with disabilities
> > >
> > > ### What changed
> > >
> > > * All components now fully keyboard-accessible
> > > * Complete screen reader support with ARIA labels
> > > * Proper focus management across all interactions
> > > * Accessible error announcements and validation
> > > * Semantic HTML structure throughout
> >
> > > [tab] Key features
> > >
> > > > [card] Auto-bindable ARIA Tags
> > > >
> > > > Automatically bind accessibility labels, descriptions, and ARIA attributes to all UI components from Designer configuration
> > >
> > > > [card] Keyboard Navigation
> > > >
> > > > Full keyboard navigation support with proper focus management, tab order, and keyboard shortcuts in Angular and React SDKs
> > >
> > > > [card] Screen Reader Support
> > > >
> > > > ARIA labels, descriptions, and live regions implemented across all form elements and interactive components
> > >
> > > > [card] UI Designer Integration
> > > >
> > > > Dedicated accessibility configuration section in UI Designer for managing labels and descriptions
> >
> > > [tab] Supported components
> > >
> > > **1. Form Elements**
> > >
> > > Input fields, Select/Multiselect, Checkbox, Switch, Radio/Segmented buttons, Slider, and File upload with labels, descriptions, and error announcements
> > >
> > > **2. Interactive Components**
> > >
> > > Buttons, Links, Modals, Stepper, Tabs, and Accordion/Card with keyboard navigation, focus management, and state announcements
> > >
> > > **3. Display Components**
> > >
> > > Messages and Images with semantic HTML structure and proper labeling
> > >
> > > **4. Platform Support**
> > >
> > > Complete implementation for Angular and React SDKs (iOS and Android in future releases)
> >
> > > [tab] Implementation details
> > >
> > > **28 Improvements Delivered:**
> > >
> > > > [accordion] Angular SDK
> > > >
> > > > * Custom keyboard navigation implementation
> > > > * Focus management for Select/Multiselect components
> > > > * Modal focus trap and restoration
> > > > * Shift+Tab handling across form elements
> > > > * Listbox keyboard operations
> > > > * Table navigation improvements
> > > > * Switch and checkbox accessibility
> > > > * File preview focus indicators
> > > > * Button Space key activation
> > > > * Link focus outlines
> > > > * Disabled element keyboard behavior
> > >
> > > > [accordion] React SDK
> > > >
> > > > * BaseUI Combobox implementation for Select/Multiselect
> > > > * Keyboard navigation with clear buttons
> > > > * Focus restoration after interactions
> > > > * Outline theming for focus indicators
> > > > * Modal auto-focus on open
> > > > * Card accordion keyboard handling
> > > > * Table row navigation
> > > > * Option highlighting in dropdowns
> > >
> > > > [accordion] UI Designer
> > > >
> > > > * Accessibility configuration panel
> > > > * Auto-bindable tags for all components
> > > > * Label and description fields
> > > > * Alt text management for images
> > > > * ARIA attribute configuration
> > > > * Accessibility section styling
> > > > * Component-specific accessibility settings
> > >
> > > > [accordion] Technical tasks completed
> > > >
> > > > * Implemented BaseUI Combobox for Select/Multiselect
> > > > * Custom keyboard navigation for Angular
> > > > * React SDK keyboard navigation with clear button
> > > > * Auto-bindable accessibility tags for all components
> > > > * Accessibility configuration panel in UI Designer
> > > > * Removed conflicting title attribute tooltips
> > > > * Aligned Stepper accessibility between frameworks
> > > > * Bind labels and descriptions to form fields
> >
> > [Learn more about Accessibility Configuration](/5.1/docs/platform-deep-dive/accessibility)
> >
> > Major Achievement
>
> ***
>
> ### **Customer fixes**
>
> > [card] Customer fixes
> >
> > We prioritized and resolved **customer-reported issues** in this release, addressing critical functionality issues and workflow inefficiencies reported via Zendesk.
> >
> > > [accordion] Action parameters lost on copy/paste
> > >
> > > **Problem:**\
> > > When copying nodes with Kafka send actions, topic and message configurations were not preserved, forcing users to manually reconfigure all action parameters after paste operations.
> > >
> > > **Customer Impact:**
> > >
> > > * Development velocity significantly reduced
> > > * Risk of configuration errors during manual re-entry
> > > * Frustration with repetitive configuration work
> > >
> > > **Resolution:**\
> > > actionParamsMap now properly persists through copy/paste operations
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create send message node with Kafka action
> > > 2. Configure topic and message parameters
> > > 3. Copy and paste the node
> > > 4. All configurations now preserved correctly
> > >
> > > **Customer Benefit:**\
> > > Faster workflow development with reduced configuration errors and improved developer experience.
> >
> > > [accordion] Orphaned warnings block process deployments
> > >
> > > **Problem:**\
> > > When deleting parent actions that had child actions with warnings, the warnings remained in the system as orphans. These orphaned warnings prevented process export/import operations and blocked build deployments.
> > >
> > > **Customer Impact:**
> > >
> > > * Build pipelines blocked by stale warnings
> > > * Deployment delays requiring manual database cleanup
> > > * Process export/import operations failed
> > > * Development and testing workflows disrupted
> > >
> > > **Resolution:**\
> > > Warnings now cascade-delete automatically when parent actions are removed
> > >
> > > **Steps to reproduce (fixed):**
> > >
> > > 1. Create action with subactions containing warnings
> > > 2. Delete the parent action
> > > 3. All child warnings now properly cleaned up
> > >
> > > **Customer Benefit:**\
> > > Clean deployments without manual intervention, faster development cycles, no more blocked pipelines.
> >
> > > [accordion] Default application cannot be removed
> > >
> > > **Problem:**\
> > > Auto-generated `default_application` in new environments existed only in app\_manager schema and could not be deleted through standard operations, returning validation errors.
> > >
> > > **Customer Impact:**
> > >
> > > * Environment cleanup difficulties
> > > * Testing complications with unwanted default projects
> > > * Confusion about application lifecycle management
> > >
> > > **Resolution:**\
> > > Added proper runtime validation for application deletion operations
> > >
> > > **Error (Fixed):**
> > >
> > > ```json theme={"dark"}
> > > {
> > >   "status": 400,
> > >   "message": "error.validation.runtime.application.not_found",
> > >   "title": "Runtime project not found."
> > > }
> > > ```
> > >
> > > **Customer Benefit:**\
> > > Clean environment management with predictable application lifecycle operations.
>
> ***
>
> ### **Proactive quality improvements**
>
> > [card] Proactive quality improvements
> >
> > > [tab] Overview
> > >
> > > **Issues identified and resolved proactively**:
> > >
> > > ### Quality process
> > >
> > > > [card] Accessibility Audits
> > > >
> > > > WCAG 2.1 compliance testing identified keyboard navigation and focus management improvements
> > >
> > > > [card] Automated Testing
> > > >
> > > > Continuous integration pipelines caught component behavior issues and rendering problems
> > >
> > > > [card] Internal QA
> > > >
> > > > Manual testing uncovered edge cases in form interactions and modal behaviors
> > >
> > > > [card] Code Reviews
> > > >
> > > > Peer reviews identified potential stability issues in backend processing and dependency management
> > >
> > > ### Distribution by category
> > >
> > > * **Keyboard Navigation**: Fixes across Angular and React
> > > * **Focus Management**: Fixes for modals, forms, and interactive elements
> > > * **Component Behavior**: Fixes for proper state handling and rendering
> > > * **Backend Stability**: Fixes for processing and dependency management
> >
> > > [tab] Angular SDK
> > >
> > > > [accordion] Keyboard navigation improvements
> > > >
> > > > * Fixed listbox remaining open when pressing Shift+Tab
> > > > * Fixed Shift+Tab not working on Select with search
> > > > * Fixed Multiselect tab navigation moving to first element instead of next
> > > > * Fixed Select input focus not working properly
> > > > * Fixed Select list not scrolling during keyboard navigation
> > > > * Fixed up/down arrow scrolling screen alongside option list
> > > > * Fixed focus lost after loading new user task
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed Link in message focus missing outline
> > > > * Fixed modal close button not focused automatically
> > > > * Fixed file preview focus not highlighted and lost
> > > > * Fixed button inside modal not working with Space key
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Multiselect options list not opening
> > > > * Fixed MultiSelect and link focusable when disabled
> > > > * Fixed modal dismiss buttons not working with Space key
> > > > * Fixed modal without close button not easily focusable
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Space pressed on card with accordion scrolling page
> > > > * Fixed Switch with label position start focus issues
> >
> > > [tab] React SDK
> > >
> > > > [accordion] Keyboard Navigation Improvements
> > > >
> > > > * Fixed outline from theme not applied to modal close button and links
> > > > * Fixed Select selected option not highlighted in options list
> > > > * Fixed Select search not filtering after selection
> > > > * Fixed Input/textarea/select focus lost after using clear button
> > > > * Fixed Tab focus moving inside collapsed card
> > > > * Fixed table Tab navigation skipping rows
> > > > * Fixed focusable table content not reached from table header
> > > > * Fixed file preview retry focus not highlighted and lost
> > >
> > > > [accordion] Component Behavior Fixes
> > > >
> > > > * Fixed Select and link focusable when disabled
> > > > * Fixed Switch type checkbox focus not highlighted
> > > > * Fixed Datepicker clear icon focus not highlighted
> > > > * Fixed modal dismiss not focused automatically
> > > > * Fixed doc preview modal not closable with Enter or Space
> > > > * Fixed button inside table focus not highlighted
> > > > * Fixed Slider decimal numbers not rendered correctly
> > > > * Fixed Substepper not rendered correctly
> > > > * Fixed doc preview display mode showing inline
> > > > * Fixed cards expandable before token reaches them
> >
> > > [tab] Designer & Backend
> > >
> > > > [accordion] UI Designer Improvements
> > > >
> > > > * Fixed missing accessibility section on Link component
> > > > * Fixed missing accessibility section on Image button
> > > > * Fixed missing space in accessibility label and info icon
> > > > * Fixed Alt text field disabled styling not applied
> > > > * Fixed console errors when changing pages from header
> > > > * Fixed Select/multiselect highlighted in preview and settings tabs
> > > > * Fixed outline theming in enumerations and inputs
> > > > * Fixed Workflows info points content not rendered correctly
> > > > * Fixed Workflows tabs content not showing properly
> > > > * Fixed padding missing on RUT UI Assets panel
> > >
> > > > [accordion] Backend Stability Improvements
> > > >
> > > > * Fixed wrong navigationTree response on overridden process
> > > > * Fixed incorrect navigationTree for resource override details
> > > > * Fixed error when trying to update dependency lib versions
> > > > * Fixed error returned when updating dependency with override
> > > > * Fixed no response on out topic for start process by name from Kafka
> > > > * Fixed checkbox "Allow back to this action" status not loaded
> > > > * Fixed empty screen when logging in without workspace access
> > > > * Fixed Elasticsearch scheduled task errors with failed documents
> > > > * Fixed services not logging when Liquibase crashing due to lock
> >
> > Proactive Quality
>
> ***
>
> ### **Task management localization**
>
> > [card] Task management localization
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 adds comprehensive localization support for Task Management, enabling multi-language task management interfaces through 51 system substitution tags. Table grid localization is automatic.
> > >
> > > ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/sys_tm.png)
> > >
> > > * **FlowX Substitution Tags** (51 keys) - Custom Task Management elements, **manually configured in CMS**
> > >
> > > * **Table Grid Localization**  - Data table components, **automatically localized based on container app language**
> > >
> > > > [!NOTE]
> > > >
> > > > This feature enables complete Task Management localization for global deployments, meeting requirements for government, healthcare, and financial services applications requiring multi-language support.
> >
> > > [tab] Key features
> > >
> > > > [card] FlowX Substitution Tags (51 Keys)
> > > >
> > > > Complete set of substitution tags for task actions, statuses, history events, and UI elements
> > >
> > > > [card] Table Grid Localization
> > > >
> > > > Table grid localizes automatically based on container app language; FlowX tags configured manually in CMS
> > >
> > > > [card] Web Renderer Integration
> > > >
> > > > Angular and React renderers use system substitution tags on all task management texts
> >
> > > [tab] What's localized
> > >
> > > **FlowX Substitution Tags (51 Keys):**
> > >
> > > * Table columns (title, stage, assignee, status, priority, last updated)
> > > * Process states (created, started, finished, failed, expired, etc.)
> > > * Task actions (assign, unassign, hold, unhold, execute, start)
> > > * Bulk operations (assign to, unassign all, hold all, etc.)
> > > * History events (task created, assigned, status changed, etc.)
> > > * User selection dialogs and UI states
> > >
> > > **Table Grid Localization**:
> > >
> > > * Filters (set, text, number, date with all operators)
> > > * Menus (column, context, aggregation, sorting)
> > > * Pagination (navigation, page size, row counts)
> > > * Data types (boolean, dates, numbers with formatting)
> > > * ARIA labels for accessibility
> >
> > > [tab] Implementation details
> > >
> > > **1. Set Container App Language**
> > >
> > > Configure your container application language - FlowX.AI automatically handles table grid localization based on this setting
> > >
> > > **2. Configure CMS Tags**
> > >
> > > Add translations for all 51 sys\_tm\_\* tags in CMS for each supported language - this is the only manual configuration needed
> > >
> > > **3. Use in Renderers**
> > >
> > > Web renderers automatically apply system substitution tags to all task management UI elements
> >
> > Localization
>
> > [card] [Task Management Localization Guide](../../../5.1/docs/platform-deep-dive/core-extensions/task-management/task-management-localization)
> >
> > Complete implementation guide with all 51 substitution tags, supported languages, and troubleshooting
>
> > [card] [CMS Substitution Tags](../../../5.1/docs/platform-deep-dive/core-extensions/content-management/substitution-tags)
> >
> > Configure substitution tags in CMS for multi-language support
>
> ***
>
> ### **AI Platform enhancements**
>
> > [card] AI Platform enhancements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.1 delivers significant improvements to the AI Platform, enhancing multi-agent collaboration, conversation management, and AI workflow stability. These enhancements ensure more reliable AI-assisted development workflows and better user experience.
> > >
> > > > [card] Multi-Agent System
> > > >
> > > > Enhanced agent communication and thread management for improved collaborative AI workflows
> > >
> > > > [card] Conversation Stability
> > > >
> > > > Improved conversation handling with better error propagation and session management
> > >
> > > > [card] AI Developer Tools
> > > >
> > > > Enhanced AI Developer capabilities with proper data model integration and expression generation
> > >
> > > > [card] Document Intelligence
> > > >
> > > > Multi-page document generation support and improved content handling
> >
> > > [tab] Key improvements
> > >
> > > **Multi-Agent Conversation Management:**
> > >
> > > * Enhanced conversation thread handling with proper parent action status updates
> > > * Improved backend support for adding new messages on agent threads
> > > * Better session management with new session button in Command Center
> > > * Context switching prevention during execution plan generation
> > >
> > > **AI Developer Enhancements:**
> > >
> > > * Fixed data model integration for expressions and business rules generation
> > > * Improved action target saving and destination setting
> > > * Enhanced execution plan editing from user prompts
> > > * Better handling of empty execution plans
> > >
> > > **Error Handling & Stability:**
> > >
> > > * Graceful error propagation from internal AI agent operations
> > > * Improved CORS headers for document object downloads
> > > * Enhanced telemetry support for debugging and monitoring
> > > * Better handling of plan enhancement patches
> > >
> > > **Document & Content Features:**
> > >
> > > * Multi-page document generation support in AI nodes
> > > * Source selector component for image and document inputs
> > > * Improved messaging system for AI agents in command center
> > > * Enhanced UI feedback for AI-generated resources
> >
> > > [tab] Technical improvements
> > >
> > > **Backend Enhancements:**
> > >
> > > * Continuous patching support for action contexts during execution
> > > * Improved navigation tree responses for overridden processes
> > > * Enhanced dependency management for library overrides
> > > * Better error handling and logging across AI services
> > >
> > > **Frontend Improvements:**
> > >
> > > * Fixed target selector closing behavior in implementation threads
> > > * Improved preview mode handling after developer changes
> > > * Enhanced command center messaging and error display
> > > * Better UI state management for AI workflow interactions
> > >
> > > **Integration Updates:**
> > >
> > > * CORS headers properly configured for GraphQL object downloads
> > > * Process task destinations automatically set to current process
> > > * Improved integration between AI agents and execution plans
> > > * Enhanced audit logging for resource overrides
> >
> > AI Platform
>
> ***
>
> ### **Platform enhancements**
>
> > [card] Platform enhancements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] SSE Disconnect Handling
> > > >
> > > > Improved Server-Sent Events disconnect handling to reduce error log flooding when clients disconnect
> > >
> > > > [card] Resource Overrides Audit
> > > >
> > > > Implemented audit logs for library resource overrides to track configuration changes
> > >
> > > > [card] Security Updates
> > > >
> > > > Fixed high vulnerabilities in Designer 5.1.x and main branch
> >
> > > [tab] Renderer Enhancements
> > >
> > > > [card] System Substitution Tags
> > > >
> > > > Web renderers now use system substitution tags on all task management texts
> > >
> > > > [card] Outline Theming
> > > >
> > > > Enhanced outline and select/multiselect option highlight theming for visual consistency
> >
> > > [tab] Technical Improvements
> > >
> > > **Code Quality:**
> > >
> > > * Eliminated deprecated code for Kafka start process
> > > * Improved error handling for Elasticsearch document updates
> > > * Enhanced dependency management for library overrides
> > > * Better logging and error reporting across services
> > >
> > > **Performance:**
> > >
> > > * Optimized SSE connection handling
> > > * Improved query performance for navigation tree
> > > * Better resource management in long-running processes
> >
> > Platform Updates

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.1 is fully compatible with 5.1.0. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.0 → 5.1.1 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Android and iOS accessibility properties implementation
> > * Additional Select component refinements
> > * UI Designer padding optimizations
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and critical bug fixes
> * Accessibility enhancements for mobile platforms
> * Performance optimizations
>
> Major new features are planned for future releases in the 5.x series. See the [5.2.0 release notes](../v5.2.0-november-2025/v5.2.0-november-2025) for upcoming capabilities.


# FlowX.AI 5.1.2 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.2-december-2025

Bug fixes, stability improvements, and quality enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes**, **stability improvements**, and **quality enhancements**.
> Upgrades from **5.1.1 → 5.1.2** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.2 provides continued quality, stability, and reliability for the platform:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * New features and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.1

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.2 delivers maintenance improvements focused on stability, reliability, and feature enhancements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — issues resolved including customer-reported and proactive fixes\
> ✨ [**New Features**](#new-features) — enhancements including new features and platform improvements\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure and stability enhancements
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Authorization service configuration
> > > >
> > > > **Problem:**\
> > > > Wrong service account client secret config parameter was used in Authorization service, causing authentication failures.
> > > >
> > > > **Resolution:**\
> > > > Fixed configu gration parameter mapping for service account client secret in Authorization service
> > >
> > > > [accordion] Token state changes on back navigation
> > > >
> > > > **Problem:**\
> > > > When performing back in steps actions, tokens incorrectly changed from Aborted to Active state when lazy actions finished.
> > > >
> > > > **Resolution:**\
> > > > Fixed token state management during back navigation to preserve correct state
> > >
> > > > [accordion] Action parameters not copied on node copy
> > > >
> > > > **Problem:**\
> > > > When copying nodes with child actions, action parameters (like Kafka topic and message configurations) were not preserved.
> > > >
> > > > **Resolution:**\
> > > > Fixed actionParamsMap persistence through copy/paste operations
> > >
> > > > [accordion] Permissions updated incorrectly during action execution
> > > >
> > > > **Problem:**\
> > > > hideRules and disableRules values were incorrectly updated in database when executing actions, causing permission issues.
> > > >
> > > > **Resolution:**\
> > > > Fixed permission rule handling during action execution
> > >
> > > > [accordion] Subprocess data mapping issues
> > > >
> > > > **Problem:**\
> > > > Starting subprocess with legacy mapping caused data to be incorrectly appended instead of replaced.
> > > >
> > > > **Resolution:**\
> > > > Fixed data mapping behavior for subprocess start actions
> > >
> > > > [accordion] Forms in collections - action not found
> > > >
> > > > **Problem:**\
> > > > When saving data from outside collection with forms to submit, actions were not found correctly.
> > > >
> > > > **Resolution:**\
> > > > Fixed action resolution for forms inside collections
> >
> > > [tab] AI Platform fixes
> > >
> > > > [accordion] AI Designer improvements
> > > >
> > > > * Fixed no feedback when uploading large documents in command center
> > > > * Fixed targets for business rules never being set by planner
> > > > * Fixed file upload limit lower than 3MB
> > > > * Fixed missing messages on Keep/Discard buttons for UI and BR
> > > > * Fixed Save & Close button not working in Data Model modal
> > > > * Fixed DM keys not created after keeping UI
> > > > * Fixed table key appearing as mapped when Data Model is empty
> > > > * Fixed pip window being clipped
> > > > * Fixed Submit prompt button color not indicating active state
> > > > * Fixed source not indicating uploaded document for some Plan actions
> > > > * Fixed UI outcome duplication until connected-graph keep method finishes
> > > > * Fixed missing scrollbar in Context Documents modal with multiple subprocesses
> > > > * Fixed command center not reopenable after closing in developer preview mode
> > > > * Fixed planner sample data import crashes
> > > > * Fixed business logic targets not correctly stored in execution plan
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Web renderer improvements
> > > >
> > > > * Fixed hide subprocess navigation closing parent navigation with multiple hierarchies
> > > > * Fixed card collapsing when next nav area is modal (Angular & React)
> > > > * Fixed card not expandable after finishing subprocess started from it (Angular & React)
> > > > * Fixed loader missing or not fully shown in React
> > > > * Fixed message icon and text rendered on different rows when width fill in React
> > > > * Fixed collection prototype shown when collection source array doesn't exist in React
> > > > * Fixed broken image rendered when missing url or base64 image in React
> > > > * Fixed switch component knob and container alignment in React
> > > > * Fixed multi select search not filtering available options in React SDK
> > > > * Fixed custom component keys duplicated in action body (React & Angular)
> > >
> > > > [accordion] Task Manager fixes
> > > >
> > > > * Fixed Task Manager theming not applied in Angular
> > > > * Fixed Task Manager header theming not applied in React
> > > > * Fixed assignee dropdown list and placeholder not displayed in React
> > >
> > > > [accordion] Reusable templates fixes
> > > >
> > > > * Fixed custom body being null at runtime for Reusable templates actions
> >
> > > [tab] Platform & Data fixes
> > >
> > > > [accordion] Data model and mappers
> > > >
> > > > * Fixed input/output parameters not deleted after updating parameters
> > > > * Fixed Go to reference button redirecting incorrectly
> > > > * Fixed parameters items deleted when updating Project Data Model object
> > >
> > > > [accordion] Process Designer
> > > >
> > > > * Fixed retry token button available for inactive tokens
> > > > * Fixed missing save action button when opening action config from UI designer
> > >
> > > > [accordion] Platform stability
> > > >
> > > > * Fixed advancing errors in partition event table
>
> ***
>
> ### **New features**
>
> > [card] New features
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation
> > > >
> > > > Generate Data Model for tables and table columns from AI Designer
> >
> > > [tab] Renderers
> > >
> > > > [card] Android Accessibility
> > > >
> > > > Accessibility properties from UI Designer now supported in Android renderer
> > >
> > > > [card] Substitution Tags in Selectors
> > > >
> > > > Selectors (checkbox, radio, select, multiselect) now support substitution tags when source type is process data across Angular, React, and iOS renderers
> > >
> > > > [card] Template Caching
> > > >
> > > > Improved caching for reusable templates at runtime
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Dgraph Upgrade
> > > >
> > > > Bring dgraph to flowx-release
> >
> > > [tab] Performance & Optimization
> > >
> > > > [card] Designer Static Assets
> > > >
> > > > Make designer nginx use compression & caching for static assets

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.2 is fully compatible with 5.1.1. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.1 → 5.1.2 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.2](./deployment-guidelines-v5.1.2).
>
> ### Known issues
>
> > [!WARNING]
> >
> > The following items are in progress or backlog for future releases:
> >
> > * Task Manager theming issues in Angular and React
> > * Task Manager assignee dropdown display issues in React
> > * Custom component key duplication in action body
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.3 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.3-january-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.2 → 5.1.3** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.3 delivers security patches and significant performance improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.2

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.3 delivers comprehensive security, performance, and stability improvements across the platform.
>
> ♿ [**iOS Accessibility**](#improvements-and-enhancements) — VoiceOver accessibility support for iOS renderer\
> ✨ [**Improvements and enhancements**](#improvements-and-enhancements) — AI Platform improvements and enhancements for Data Model generation\
> ⚡ [**Performance Improvements**](#performance-improvements) — Performance improvements and optimizations across platform components and services\
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components\
> 🔧 [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Improvements and enhancements**
>
> > [card] Improvements and enhancements
> >
> > > [tab] Renderers
> > >
> > > > [card] iOS Accessibility
> > > >
> > > > VoiceOver accessibility support for the iOS renderer. Accessibility properties configured in the UI Designer (labels, hints, traits, decorative flags) are now applied to iOS components including form elements, text, images, and links.
> >
> > > [tab] AI Platform
> > >
> > > > [card] Data Model Generation for Tables
> > > >
> > > > Generate Data Model mappings for table components from AI Designer. AI automatically creates array of objects DM keys for tables with type validation and visual feedback.
> > >
> > > > [card] Data Model Generation for Table Columns
> > > >
> > > > Extended DM generation for text and link elements within table columns, with automatic attribute mapping and support for partial matching.
>
> ***
>
> ### **Performance improvements**
>
> > [card] Performance improvements
> >
> > > [tab] Overview
> > >
> > > FlowX.AI 5.1.3 delivers significant performance improvements to the process engine
> > >
> > > > [card] Optimized Writes
> > > >
> > > > Smart change detection skips unnecessary database writes when param\_values unchanged
> > >
> > > > [card] Reduced DB Calls
> > > >
> > > > N+1 query fixes and batch loading significantly reduce database round trips
> > >
> > > > [card] Request Caching
> > > >
> > > > Request-scoped caching for frequently accessed runtime configuration
> >
> > > [tab] Key optimizations
> > >
> > > > [accordion] ProcessInstance param\_values Optimization
> > > >
> > > > Optimized handling of large `param_values` to reduce network overhead and prevent optimistic locking conflicts:
> > > >
> > > > * **Change Detection**: Skip database writes when param\_values unchanged
> > > > * **Lightweight Queries**: Exclude param\_values from SELECT when not needed
> > >
> > > > [accordion] Runtime Improvements - Reduced DB Calls
> > > >
> > > > **Optimizations Implemented:**
> > > >
> > > > * Improved batch loading and caching to reduce redundant queries
> > > > * Streamlined process initiation
> > > > * Enhanced batching for database writes
>
> ***
>
> ### **Bug fixes**
>
> > [card] Bug fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Task Manager View Not Updating
> > > >
> > > > **Problem:**\
> > > > When using a view with dataset config where assignee is set to blank, after assigning a task (or self-assigning), the view appeared unchanged. Similarly, when assignee is set to not blank and you unassign a task, the view did not update.
> > > >
> > > > **Resolution:**\
> > > > Fixed view refresh behavior after assign/unassign operations to properly reflect the updated task state and provide visual feedback to users.
> > >
> > > > [accordion] Forms in Collections - Backend Keys Calculation
> > > >
> > > > **Problem:**\
> > > > When saving data from outside a collection with forms to submit, the backend calculated keys for UUID entries in formsToSubmit. These keys were only partial (relative to the collection array) and could overwrite existing process values.
> > > >
> > > > **Resolution:**\
> > > > Added a flag on PATCH /actions requests to notify the backend to exclude backend keys calculation for forms in collections UUIDs from formsToSubmit.
> > >
> > > > [accordion] Variables Reset on Config Update
> > > >
> > > > **Problem:**\
> > > > Updating parameters in the config page caused existing parameters to be replaced with new ones, generating new flowxUuids. This caused variables in database nodes to no longer match, losing all references.
> > > >
> > > > **Resolution:**\
> > > > Fixed to always send id and flowxUuid for existing params when saving the operation, preserving variable references.
> > >
> > > > [accordion] Build Export Timeout
> > > >
> > > > **Problem:**\
> > > > When exporting builds with multiple resources, some resources remained in EXPORTING status, others got EXPORT\_TIMEOUT without the build export receiving the status, and others had EXPORTED status. This was caused by Kafka messages being processed before the MongoDB transaction was committed.
> > > >
> > > > **Resolution:**\
> > > > Fixed the export function to ensure proper sequencing of database transactions and Kafka messages during build export operations.
> >
> > > [tab] Designer fixes
> > >
> > > > [accordion] Table Row Deletable with Backspace in RUT
> > > >
> > > > **Problem:**\
> > > > In Reusable UI Templates, selecting a table row and pressing backspace would delete the row, even though table rows should not be deletable.
> > > >
> > > > **Resolution:**\
> > > > Fixed keyboard handling to prevent accidental table row deletion via backspace key.
> >
> > > [tab] Renderer fixes
> > >
> > > > [accordion] Android Upload Action Payload Missing
> > > >
> > > > **Problem:**\
> > > > Upload action payload data (except uploadFileTempFileId) was missing on execution in the Android renderer.
> > > >
> > > > **Resolution:**\
> > > > Fixed payload handling to include all required data in upload action execution.
>
> ***
>
> ### **Platform improvements**
>
> > [card] Platform improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Connector Topic Pattern
> > > >
> > > > Added dedicated KAFKA\_TOPIC\_CONNECTOR\_PATTERN variable for connectors, allowing custom topic patterns without breaking other components like document-plugin, data-search, and cms-core
> >
> > > [tab] AI Platform
> > >
> > > > [card] Streaming Client Library
> > > >
> > > > Implemented client library for invoking the run AI node with streaming support for conversational API

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.3 is fully compatible with 5.1.2. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.2 → 5.1.3 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### New configuration options
>
> > [!NOTE]
> >
> > **Optional**: New environment variable available for process-engine
>
> | Variable | Description | Default |
> | - | - | - |
> | `KAFKA_TOPIC_CONNECTOR_PATTERN` | Dedicated topic pattern for FlowX connectors, separate from other platform components | Falls back to `KAFKA_TOPIC_PATTERN` if not set |
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.3](./deployment-guidelines-v5.1.3).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.4 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.4-february-2026

Security patches, performance optimizations, bug fixes, and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **security patches**, **performance optimizations**, **bug fixes**, and **stability improvements**. Upgrades from **5.1.3 → 5.1.4** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.4 delivers security patches and stability improvements:
>
> * Numerous bug fixes addressing reported and internally identified issues
> * Improvements and enhancements to various platform components
> * Platform tasks focused on infrastructure and overall stability
> * No breaking changes — fully compatible upgrade from 5.1.3

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.4 delivers comprehensive security, performance, and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Customer-reported and proactive fixes across platform components and stability improvements\
> ⚡ [**Platform Improvements**](#platform-improvements) — Infrastructure hardening and dependency updates
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Customer fixes
> > >
> > > Issues resolved based on customer feedback:
> > >
> > > > [accordion] Form validators do not work inside collection prototypes
> > > >
> > > > **Summary:**
> > > >
> > > > Validators applied to forms within collection prototypes are not triggered as expected.
> > >
> > > > [accordion] Project editor could modify access permissions
> > > >
> > > > **Summary:**
> > > >
> > > > Project editors were incorrectly able to modify project access permissions and delete projects. This has been fixed: `project_editor` can no longer modify access management or delete projects/libraries. Only `project_owner` and `workspace_admin` can change project ownership, add/remove users and groups from projects/libraries, and delete projects/libraries.
> > >
> > > > [accordion] Subprocess UI still shown after subprocess is finished
> > > >
> > > > **Summary:**
> > > >
> > > > In processes with multiple subprocesses that have UI, the first subprocess UI remained visible after completion until the next user task details were received. The UI now correctly clears when a subprocess finishes.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Infrastructure
> > >
> > > > [card] Kafka environment variables alignment
> > > >
> > > > Kafka environment variables are now consistent across all services with backwards compatibility support for existing configurations.
> > >
> > > > [card] Config params cache improvements
> > > >
> > > > New environment variables for tuning config params cache: `FLOWX_CACHE_CONFIGPARAMS_TTLSECONDS` and `FLOWX_CACHE_CONFIGPARAMS_MAXENTRIES`. See [Engine Setup](/5.1/setup-guides/flowx-engine-setup-guide/engine-setup#config-params-cache).
> > >
> > > > [card] Project editor permissions update
> > > >
> > > > `project_editor` can no longer delete projects or modify access permissions. `projects_admin` permission now grants full project management capabilities. See [Roles Permissions Matrix](/5.1/setup-guides/access-management/roles-permissions-matrix).
> > >
> > > > [card] Advancing partition counter fix
> > > >
> > > > Fixed an issue where the advancing partition counter could go negative, causing event processing failures. Improves reliability in integration-designer and process-engine.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.4 is fully compatible with 5.1.3. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.3 → 5.1.4 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.4](./deployment-guidelines-v5.1.4).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.5 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.5-february-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.4 → 5.1.5** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.5 delivers bug fixes and stability improvements:
>
> * Fixes for process loop rendering issues in the Angular renderer
> * Fix for subprocess output data not being returned from embedded processes
> * No breaking changes — fully compatible upgrade from 5.1.4

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.5 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer and process engine fixes for process loop scenarios
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes
> > >
> > > Issues resolved in the Angular renderer:
> > >
> > > > [accordion] Validation shown without user interaction on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task for the second time, form validation errors were displayed immediately without any user interaction. Validation now correctly waits for user input before showing errors.
> > >
> > > > [accordion] Action executed continuously on process loop
> > > >
> > > > **Summary:**
> > > >
> > > > When a process loop returned to a user task that had a UI action configured on a form element, the action was executed continuously in a loop. Actions are now correctly triggered only on user interaction.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Subprocess not returning output from embedded process
> > > >
> > > > **Summary:**
> > > >
> > > > When a subprocess (call activity) was started from an embedded process, the output data was not passed back to the parent process instance after completion. Data mapping from subprocess to parent now works correctly in embedded process scenarios.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.5 is fully compatible with 5.1.4. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.4 → 5.1.5 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.5](./deployment-guidelines-v5.1.5).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.6 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026

Bug fixes, stability improvements, and platform enhancements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.5 → 5.1.6** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.6 delivers bug fixes and stability improvements:
>
> * Multiple React and Angular renderer fixes for modals, sliders, buttons, and accessibility
> * Data mappers autocomplete fix for values not loading
> * Process engine fix for advancing getting stuck on pod crash with multiple partition events
> * Kafka health check fix for reporting UP despite consumer DNS failure
> * New health indicator for runtime MongoDB connection
> * Connection leak fix in application-manager export/import operations
> * Improved retry mechanism with configurable exponential backoff
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.5

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.6 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Renderer, process engine, and application manager fixes
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Retry mechanism enhancements and security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Renderer fixes (React)
> > >
> > > Issues resolved in the React renderer:
> > >
> > > > [accordion] Clear icon present and clickable on disabled input/textarea
> > > >
> > > > **Summary:**
> > > >
> > > > When an input or textarea component was disabled, the clear icon was still visible and clickable. The clear icon is now hidden and non-interactive on disabled components.
> > >
> > > > [accordion] Options list not shown when selectors are inside modal
> > > >
> > > > **Summary:**
> > > >
> > > > When select or multiselect components were placed inside a modal, the options list was not displayed when opened. Selector dropdowns now render correctly within modal contexts.
> > >
> > > > [accordion] Datepicker calendar shown behind modal
> > > >
> > > > **Summary:**
> > > >
> > > > When a datepicker was placed inside a modal, the calendar popup appeared behind the modal overlay. The datepicker calendar now renders above the modal with correct z-index stacking.
> > >
> > > > [accordion] Slider min/max value not set when loading a screen
> > > >
> > > > **Summary:**
> > > >
> > > > When a slider shared a process data key with an input, or when slider min/max values depended on computed values from another slider, the min/max values were not set on load. Slider initialization now correctly applies min/max values and computed dependencies.
> > >
> > > > [accordion] Slider default value not set with multiple sliders on same page
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple sliders were present on the same page, some sliders did not receive their default values, especially when no explicit null value was set in the data store. Default value initialization now works correctly for all sliders on a page.
> > >
> > > > [accordion] Task management assignee clear icon clickable when disabled
> > > >
> > > > **Summary:**
> > > >
> > > > In the task management view, the assignee field's clear icon was visible and clickable even when the field was disabled (non-editable). The clear icon is now hidden when the assignee field cannot be edited.
> > >
> > > > [accordion] Input, select, datepicker, textarea, and table filters have incorrect inner outline
> > > >
> > > > **Summary:**
> > > >
> > > > Multiple form components displayed an incorrect inner outline styling. The outline now only appears during keyboard navigation, following proper accessibility patterns.
> > >
> > > > [accordion] Data mappers autocomplete values not loading
> > > >
> > > > **Summary:**
> > > >
> > > > Data mapper autocomplete suggestions were not loading values in certain configurations. Autocomplete now correctly fetches and displays available values.
> >
> > > [tab] Renderer fixes (Angular + React)
> > >
> > > Issues resolved in both Angular and React renderers:
> > >
> > > > [accordion] Card height does not update when accordion is collapsed
> > > >
> > > > **Summary:**
> > > >
> > > > When a card component with fixed height contained an accordion, the card height did not update when the accordion was collapsed. Card height now correctly recalculates when accordion state changes.
> > >
> > > > [accordion] Focus outline appears when interacting with card/file preview accordion
> > > >
> > > > **Summary:**
> > > >
> > > > When interacting with a card or file preview component that included an accordion, an unwanted focus outline appeared. The focus outline is now only displayed during keyboard navigation.
> > >
> > > > [accordion] Button icon not correctly rendered
> > > >
> > > > **Summary:**
> > > >
> > > > When a button was configured with a right-aligned icon, fill width, and right-aligned typography, the icon was not aligned with the text, the gap was missing, and text and icon were center-aligned instead of right-aligned. Button icon layout now respects all configured alignment and spacing settings.
> >
> > > [tab] Process engine fixes
> > >
> > > > [accordion] Advancing gets stuck when multiple events are available for one partition and pod crashes
> > > >
> > > > **Summary:**
> > > >
> > > > When multiple events were available for the same partition and a pod crashed, only the first event was picked up and the rest remained stuck. Event processing now correctly handles all pending events after a pod recovery.
> > >
> > > > [accordion] Kafka health check reported UP despite consumer DNS failure
> > > >
> > > > **Summary:**
> > > >
> > > > The Kafka health check indicator could report UP even when consumers had DNS resolution failures, masking connectivity issues. Health indicators now correctly reflect the actual state of Kafka consumer connections.
> > >
> > > > [accordion] Health indicator for runtime MongoDB connection
> > > >
> > > > **Summary:**
> > > >
> > > > A new health indicator has been added to monitor the runtime MongoDB connection. This improves observability and allows operators to detect MongoDB connectivity issues through the standard health endpoint.
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Theme not imported during build import
> > > >
> > > > **Summary:**
> > > >
> > > > When importing a build that included theme resources, the theme was not correctly imported. Build import now includes theme resources as expected.
> > >
> > > > [accordion] Connection leak in export/import services
> > > >
> > > > **Summary:**
> > > >
> > > > During import/export operations, database connections were held for the entire duration of long-running operations (MinIO file transfers, REST calls, Kafka messaging), which could exhaust the connection pool. Transaction boundaries have been refined so that database connections are only held during actual database operations.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Process engine
> > >
> > > > [accordion] Configurable retry mechanism with exponential backoff
> > > >
> > > > **Summary:**
> > > >
> > > > The retry mechanism for optimistic locking in the process engine now uses an Equal Jitter strategy and supports runtime configuration via environment variables. Previously, the jitter was nullified by the max delay cap, causing retrying threads to collide at the same millisecond.
> > > >
> > > > New environment variables for the `process-engine`:
> > > >
> > > > | Environment Variable | Description | Default Value |
> > > > | - | - | - |
> > > > | `FLOWX_RETRY_MAX_RETRIES` | Maximum retry attempts (total = max + 1 including initial) | `9` |
> > > > | `FLOWX_RETRY_BASE_DELAY_MS` | Initial backoff delay in milliseconds | `10` |
> > > > | `FLOWX_RETRY_MAX_DELAY_MS` | Maximum backoff delay cap in milliseconds | `200` |
> > > >
> > > > > [!TIP]
> > > > >
> > > > > Default settings give a total retry window of \~1.2 seconds, which covers most transient optimistic lock conflicts. Increase `FLOWX_RETRY_MAX_RETRIES` or `FLOWX_RETRY_MAX_DELAY_MS` if you see retry exhaustion under high contention.
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Removed deprecated access rights endpoint
> > > >
> > > > **Summary:**
> > > >
> > > > A deprecated endpoint and its associated test for access rights have been removed from the codebase as they are no longer needed.
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across all platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.6 is fully compatible with 5.1.5. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.5 → 5.1.6 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.6](./deployment-guidelines-v5.1.6).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations
> * Additional renderer enhancements


# FlowX.AI 5.1.7 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.7-march-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.6 → 5.1.7** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.7 delivers bug fixes and stability improvements:
>
> * Fix for build import issues with manifest (reimport failures)
> * Security patches
> * No breaking changes, fully compatible upgrade from 5.1.6

***

**What's new? 🆕**

> [tab] Highlights
>
> FlowX.AI 5.1.7 delivers bug fixes and stability improvements across the platform.
>
> 🐛 [**Bug Fixes**](#bug-fixes) — Build import fix
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches
>
> ***
>
> ### **Bug Fixes**
>
> > [card] Bug Fixes
> >
> > > [tab] Application manager fixes
> > >
> > > > [accordion] Build reimport failures with manifest issues
> > > >
> > > > **Summary:**
> > > >
> > > > When reimporting a build, the import could fail due to manifest validation issues, either stopping mid-import or reporting that the build was already being imported. Build reimport now correctly handles manifest validation and prevents duplicate import conflicts.
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.7 is fully compatible with 5.1.6. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.6 → 5.1.7 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.7](./deployment-guidelines-v5.1.7).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations


# FlowX.AI 5.1.8 Release Notes (LTS)
Source: https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.8-april-2026

Bug fixes and stability improvements for the FlowX.AI 5.1.x LTS line.

> [!NOTE]
>
> This is a **Long-Term Support (LTS)** maintenance release focusing on **bug fixes** and **stability improvements**. Upgrades from **5.1.7 → 5.1.8** are non-breaking and fully compatible.

> [card] Release Highlight
>
> **Maintenance Release**: FlowX.AI 5.1.8 delivers security patches and dependency upgrades:
>
> * Security patches and dependency upgrades
> * No breaking changes — fully compatible upgrade from 5.1.7

***

**What's new? 🆕**

> [tab] Highlights
>
> Security patches and dependency upgrades across platform components.
>
> 🔧 [**Platform Improvements**](#platform-improvements) — Security patches and dependency upgrades
>
> ***
>
> ### **Platform Improvements**
>
> > [card] Platform Improvements
> >
> > > [tab] Other improvements
> > >
> > > > [accordion] Security patches
> > > >
> > > > This release includes security patches and dependency upgrades across platform components to address known vulnerabilities.
>
> ***

> [tab] Info
>
> ## Additional information
>
> > [!NOTE]
> >
> > **Upgrade Compatibility**: FlowX.AI 5.1.8 is fully compatible with 5.1.7. No configuration changes, schema migrations, or data transformations are required.
>
> ### Compatibility
>
> > [card] Upgrade Path
> >
> > Direct upgrade from 5.1.7 → 5.1.8 with no breaking changes or configuration updates
>
> > [card] Component Compatibility
> >
> > Compatible with FlowX.AI SDKs (Angular/React/iOS/Android), Designer, and Database 5.1.x
>
> ### Deployment information
>
> > [!NOTE]
> >
> > Standard deployment procedures apply. No special migration steps required for this maintenance release.
>
> For detailed deployment guidelines, see [Deployment Guidelines v5.1.8](./deployment-guidelines-v5.1.8).
>
> ### What's next
>
> **FlowX.AI 5.1.x LTS** will continue to receive maintenance updates focused on:
>
> * Security patches and vulnerability fixes
> * Stability improvements and bug fixes
> * Performance optimizations